chore(spec): govern the four RestServerConfig sub-objects in the liveness ledger - #14638

Fixes #14369

Lands the ten declared-but-unread RestServerConfig keys in the liveness ledger, with the census re-run and pinned to a ref. Per the triage ruling, the dispatchable unit is the LEDGER: no key is removed, enforced, deprecated or re-described, packages/spec/src/api/rest-server.zod.ts is not edited, and the @example fence is left for the per-key follow-up.

Correction: the card's named landing is wrong-typed

The card names packages/spec/liveness/api.json. Measured on origin/main, that file is ApiEndpointSchema's ledger ("type": "api", and its only cacheTtl row is ApiEndpointSchema.cacheTtl, a different key from RestServerConfig.metadata.cacheTtl). RestServerConfigSchema is server/plugin construction config and is not a registered metadata type, so appending rows to api.json would have put them under a schema the gate never walks — orphan rows on arrival.

The route non-metadata-type schemas take is SPEC_ONLY_SCHEMAS in packages/spec/scripts/liveness/check-liveness.mts, the way query, webhook, validation, qa and manifest are governed. This PR follows that precedent.

Why four roots and not one

RestServerConfigSchema is the obvious single root and measurement rules it out. The ledger walk drills exactly one level (check-liveness.mts classifies props[key] and, when the entry declares children, one level beneath it — there is no recursion, and no ledger file in the repo carries nested children). With the whole config as the root, the four sub-objects would BE the drilled level, so metadata.endpoints.schema and batch.operations.upsertMany — two of the card's ten — would have no row of their own. Their container's blanket verdict would be live (three of four members gate a real route mount), silently covering a dead key: the #4956 shape, in the file written to end it.

Rooting on the four sub-schemas puts every one of the ten keys at a drillable coordinate, so each carries its own falsifiable verdict. RestApiConfigSchema (the fifth sub-object, api) is deliberately not enrolled — its consumption seam is still validate-only and is the subject of #14366, so a census of it would record a half that is about to move.

Container coverage is unchanged by this PR: still 58 blanket verdicts over 301 child keys, 7 deferrals over 273. No row is added to undrilled-containers.baseline.json — the shrink-only ratchet is not touched.

Files

Enrolment: GOVERNED + SPEC_ONLY_SCHEMAS in packages/spec/scripts/liveness/check-liveness.mts (import + four entries + the rationale block). README.md gains four "Current state" rows and its heading moves 31 → 35; state-counts.md was regenerated by the gate (pnpm --filter @objectstack/spec gen:liveness-counts), never by hand.

Census, re-run and pinned

Ref: 2514d49f388e898e666ae04f19ba376d04db5422 (2514d49f3), the merge base this branch is cut from. Method: read sites in packages/rest/src non-test sources, excluding NormalizedRestServerConfig's type declaration (rest-server.ts lines 723-786) and normalizeConfig itself (3518-3616), comments excluded; plus a repo-wide grep outside packages/spec and that file; plus objectui @ d4c6a86.

Ten keys, fifteen rows: the two container keys are expanded into a row per member so the verdict is falsifiable per key rather than inherited. The card's first list is confirmed live in the same pass and carries live rows with path#symbol evidence plus a producer pointer at rest-server.ts#normalizeConfig: crud.operations.{create,read,update,delete,list} and crud.dataPrefix (5 independent consumers); metadata.{prefix,enableCache,maskObjectFields} and metadata.endpoints.{types,items,item}; batch.{maxBatchSize,enableBatchEndpoint} and batch.operations.{createMany,updateMany,deleteMany}.

Repo-wide grep for nameTransform / objectParamStyle / defaultAtomic outside packages/spec and rest-server.ts returns only changesets, the generated reference page content/docs/references/api/rest-server.mdx, and #11984's own refusal tests — no consumer. objectui @ d4c6a86 is clean (0 hits for every key, and 0 for RestServerConfig itself). The closed cloud runtime was not reachable from the measuring container, so every row declares "evidenceScope": "in-repo" rather than claiming a sweep that was not run.

No premise change. All ten keys still measure 0. Two sharpenings the re-run added, both recorded in the rows rather than acted on: metadata.endpoints.schema gates a route that does not exist (packages/rest/src mounts no path ending in /schema at all), and batch.operations.upsertMany is its twin (the protocol carries createManyData / updateManyData / deleteManyData and no upsertManyData).

metadata.cacheTtl's negative-bound observation travels in that key's ledger note, per the triage ruling, and is not filed as a separate defect.

What #11984 settled, and what it did not

Kept as the note's own distinction: #11984 made RestServer.normalizeConfig PARSE and CONSUME these four sub-objects instead of casting them, so an out-of-enum or out-of-range value is refused at construction. That settles accept/reject. Executing a declared contract does not give a key a consumer — which is why routes.nameTransform is validated against its enum and still mounts exactly what 'none' mounts.

Out of scope, reported not fixed

api.documentation and api.responseFormat (and their children) also measure 0 read sites in packages/rest/src at this ref — dead keys in the same declared-but-unenforced class, on the one sub-object this PR does not enrol. Not classified here and not filed as part of this card; recorded for the dev report so the api half can be dispatched with the finding in hand.

Changeset

packages/spec/liveness/** is named in packages/spec's files, so the ledgers ship in the published tarball — a patch changeset for @objectstack/spec is included and pnpm check:published-files is green. No skip-changeset label.

Gates

Derived on the final head with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack (36 commands) and run with each exit code captured before any pipe. At 0e9a1f50a:

• 34 pass, including pnpm --filter @objectstack/spec check:liveness, check:generated (all 15 artifacts current), check:empty-state, check:strictness-ledger, check:variant-docs, check:published-files, check:merge-driver, check:adr-0087-registration, check:pm-governed-merges, pnpm check:nul-bytes.
• 3 NOT MEASURED — all one cause, an unbuilt workspace in the measuring container, none a finding: check-test-completeness (exit 3, its own text says it grades a saved turbo run test log and none was named), check:dual-build-cjs-loads (exit 3, "PREREQUISITE NOT MET — this gate reads built output"; its 93-case self-test passes), check-dev-prereqs (exit 1, "1 unmet precondition, not a list of problems" — 66 of 67 packages have no dist/). CI checks out fresh and builds, so all three are measured there.
• Liveness script suites: pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 scripts/liveness scripts/zod-graph.test.ts src/system/metadata-form-zod-reconciliation.test.ts — 13 files, 360 tests, all pass (the gate script is edited, so its own suite is not optional).
• pnpm --filter @objectstack/spec typecheck — green (tsc --noEmit + check:scripts-typecheck + check:test-typecheck).

The gate is what judges this work: with the four files absent, check:liveness reds with four UNCLASSIFIED types; with them present and the README/state-counts halves missing, it reds on the index and on the generated count artifact. Both were observed on the way in.

🤖 Generated with Claude Code

https://claude.ai/code/session_017RbbUMnxkUnWhE4j94v8FE

Generated by Claude Code