[finding] No shipped boot path authors `RestServerConfig` at all — `os serve` fixes it and the dev plugin passes none, so every live `crud` / `metadata` / `batch` key is embedder-only

[claude]

Filed unassigned and unlabelled for triage, from the capability-coverage work on #14961 (PR #15541). Not that PR's change and not addressed there.

Measured on origin/main 6f944589

RestServerConfig declares four sub-objects the REST server parses and consumes at construction — crud, metadata, batch, routes — with live keys that decide real behaviour: which CRUD and bulk routes are mounted, the data and metadata path prefixes, the batch size cap, and the ADR-0106 D8 object-schema masking posture.

No shipped boot path authors any of them.

• packages/cli/src/commands/serve.ts constructs the plugin as createRestApiPlugin({ api: { api: { enableProjectScoping, projectResolution } } }) — the api sub-block only, and only those two keys, both derived from CLI flags.
• packages/plugins/plugin-dev/src/dev-plugin.ts calls createRestApiPlugin() with no config at all.
• The only doors that accept a full RestServerConfig are programmatic: createRestApiPlugin({ api }) (packages/rest/src/rest-api-plugin.ts) and createHonoServerPlugin({ restConfig }) (packages/plugins/plugin-hono-server/src/hono-plugin.ts).

So a deployment driven by the CLI cannot set batch.maxBatchSize, move crud.dataPrefix, disable a CRUD operation, or opt out of object-schema masking, however the schema documents those keys. Every value is whatever the Zod defaults say.

Why it is worth a decision

1. The keys read as deployment policy and are not reachable as such. batch.maxBatchSize's own docblock calls the cap "deployment policy"; metadata.maskObjectFields's says false "opts this server out". Both are true only for an embedder.
2. It sharpens [finding] The client SDK hard-codes /data/${object}… while crud.dataPrefix is live and discovery advertises routes.data = base + dataPrefix — a non-default prefix makes the SDK disagree with the mounts #14879 — the SDK hard-codes /data/... while crud.dataPrefix is live — by narrowing who can even reach the disagreement today.
3. It sets the cost of testing them: the platform checklist now carries items for these keys (PR docs(qa): classify the five UNCLASSIFIED capability ledgers — four REST-config kinds authored, realtime_subscription waived #15541), and every non-default clause has to be scored in a unit harness rather than against a running deployment, which is recorded on each item's knownGaps.

Options (not decided here)

1. Thread a config through — let the stack/app or a CLI flag supply a RestServerConfig (or the subset that is genuinely deployment policy: the cap, the prefixes, the masking opt-out).
2. Rule it embedder-only and say so in the schema — the keys stay, their docblocks stop describing a deployment posture nobody can author from the CLI, and the ADR-0049 question "is this key reachable?" gets its answer written down.
3. Retire the unreachable half under enforce-or-remove, keeping only what an embedder demonstrably uses.

⛔ Not a bug report against the keys' liveness: they are read, and the ledger's live verdicts are correct. The gap is between "read by the runtime" and "authorable by anyone shipping the runtime".

Where it is already captured

docs/qa/platform-checklist/FOLLOW-UPS.md §10b E2, and in the knownGaps of the three new api-backend.rest-*-config-contract items.

---

Generated by Claude Code

[os-zhuang]

分诊 · domain:spec / priority:p2 / pm:queue

Anchor read, not guessed — and the anchor is genuinely contested here, so the reasoning is on the record. Two of the three options (rule it embedder-only and say so in the schema; retire the unreachable half) land in packages/spec/src/api/rest-server.zod.ts, which is also where the docblocks making the false claim live. ⇒ domain:spec. ⚠️ Option 1 (thread a config through) lands in packages/cli and would hand off to domain:cli — that hand-off is part of the deliverable if option 1 is chosen, not a re-route.

Verified on origin/main f1d7872 (2026-09-05T00:14:36Z), and both boot paths read exactly as filed:

packages/cli/src/commands/serve.ts:3916
  createRestApiPlugin({ api: { api: { enableProjectScoping, projectResolution } } as any }),

packages/plugins/plugin-dev/src/dev-plugin.ts:856
  this.childPlugins.push(createRestApiPlugin());

⇒ The api sub-block only, two CLI-derived keys, in one path; no config at all in the other. ⭐ Incidental but worth naming: serve.ts:3916 reaches the plugin through an as any cast, so even the two keys it does pass are unchecked at that seam.

Grade — p2

The card's framing is the right one and the grade follows from it:

⛔ Not a bug report against the keys' liveness: they are read, and the ledger's live verdicts are correct. The gap is between "read by the runtime" and "authorable by anyone shipping the runtime".

⇒ Nothing is broken; every value is whatever the Zod defaults say, and the defaults are fine. What makes it p2 rather than p3 is that the docblocks assert a posture that does not exist: batch.maxBatchSize's own docblock calls the cap "deployment policy", and metadata.maskObjectFields's says false "opts this server out". Both sentences are true only for a programmatic embedder, and neither says so. An operator reading the schema to plan a deployment is being told they can set things they cannot set — including an ADR-0106 D8 object-schema masking posture, which is the one on this list that sounds like a security control.

Not p1: no deployment is misconfigured, because none of them can be configured at all — the failure is entirely in what the documentation promises.

⭐ Why this card is more useful than its own size suggests

It sharpens two other open items rather than only adding one:

1. [finding] The client SDK hard-codes /data/${object}… while crud.dataPrefix is live and discovery advertises routes.data = base + dataPrefix — a non-default prefix makes the SDK disagree with the mounts #14879 (the SDK hard-codes /data/… while crud.dataPrefix is live) — this narrows who can even reach that disagreement today. A conflict nobody can trigger is a different card from one every deployment could.
2. It sets the cost of testing. The platform checklist now carries items for these keys (PR docs(qa): classify the five UNCLASSIFIED capability ledgers — four REST-config kinds authored, realtime_subscription waived #15541), and every non-default clause has to be scored in a unit harness rather than against a running deployment — recorded on each item's knownGaps. ⇒ That is not a footnote; it is the standing price of leaving this as-is, paid at every checklist run.

Boundary test — all three options cross, in different directions

• 1 — thread a config through (stack/app or a CLI flag supplies a RestServerConfig, or the subset that is genuinely deployment policy: the cap, the prefixes, the masking opt-out). ⇒ New authorable surface ⇒ Feature ⇒ manual floor. ⚠️ And the subsetting is the design question: "which of these keys is deployment policy" is not obvious, and shipping all of them because they exist would be the wrong answer.
• 2 — rule it embedder-only and say so in the schema. ⇒ Contract prose, but it writes down an answer to the ADR-0049 question "is this key reachable?", which is a ruling, not an edit.
• 3 — retire the unreachable half under enforce-or-remove. ⇒ Removes exported keys ⇒ contract change, manual floor.

⛔ Triage is not choosing. ⚠️ One input the chooser should not have to re-derive: option 2 is not "do nothing". It costs one honest sentence per key and it permanently answers the reachability question that this card, #15542, and the three new checklist items all currently have to re-ask. If option 1 is wanted but not soon, 2 is the correct interim state — ⛔ not silence.

Sequencing — one cluster, three cards, keep them three

Filed within a minute of each other by the same flight (#14961 / PR #15541), and best read together:

• [finding] metadata.endpoints.items gates four routes — the _migrate-stored write door and the diagnostics sweep among them — while its declared meaning names only the type listing #15542 — metadata.endpoints.items gates four routes including a write door, while its describe() names one. ⚠️ This card is that card's mitigation: [finding] metadata.endpoints.items gates four routes — the _migrate-stored write door and the diagnostics sweep among them — while its declared meaning names only the type listing #15542 is only p2 because RestServerConfig is unreachable from a shipped boot. ⇒ If option 1 is chosen here, [finding] metadata.endpoints.items gates four routes — the _migrate-stored write door and the diagnostics sweep among them — while its declared meaning names only the type listing #15542 must be fixed first or in the same change, or threading the config through hands operators a switch labelled "list items" that silently unmounts POST /_migrate-stored.
• [finding] The MOUNT half of every RestServerConfig switch is unpinned — the tests assert what a switch normalizes to, never that the route leaves the table #15544 — the MOUNT half of every switch is unpinned.

⇒ ⭐ Dependency stated plainly: option 1 here is blocked on #15542 landing. That is the single most important thing this routing adds.

Already captured downstream: docs/qa/platform-checklist/FOLLOW-UPS.md §10b E2 and the knownGaps of the three new api-backend.rest-*-config-contract items. ⛔ Do not close this in a way that makes those knownGaps stale without updating them.

⛔ Not a claim, not a dispatch — routing only.

---

Generated by Claude Code