feat(spec): enrol RestApiConfigSchema in the liveness ledger as rest_api

[os-warren]

Fixes #14640

Clause-②: no

Enrols RestApiConfigSchema — the api sub-object of RestServerConfig, and the fifth of its five — in the ADR-0049 liveness ledger as a new governed type rest_api. 26 properties classified: 12 live, 14 dead. The card's two containers, api.documentation (ten members) and api.responseFormat (three), are recorded dead with a distinct reason each.

This file records status. It makes no per-key enforce-or-remove call — that is deferred to the human floor, and the two containers deliberately do not share one verdict.

The card's first ordered act: the falsifier, re-established first-hand

The triage answer (comment 5624242736) replaced the body's phantom blocker with a precondition:

Before enrolling either key, establish whether any seam actually constrains them. If one is found, ⛔ stop and report — the card returns to pm:blocked with a resolvable Blocked-by:. If none is found, proceed on the measured zero.

Result: no seam constrains either key. The measured zero holds. Re-measured independently on origin/main at 1ff3a8f210 (the ledger's own census was taken at 31184e5daf3b), by shape and never by line number, since the file has grown and every line number in the card is stale.

The seam that used to constrain them has settled and shipped. RestServer.normalizeConfig now opens with const api = this.parseDeclaredApiConfig(config.api) and builds the api block key by key from that parsed output — documentation: api.documentation and responseFormat: api.responseFormat among them — where it previously discarded the parse and rebuilt from a cast over the raw input. The source says so itself: "the asymmetry is gone and all five now build from their parsed output". Introduced by 53cbad9f75 (2026-09-05, PR #15673); git merge-base --is-ancestor 53cbad9f75 '@objectstack/rest@17.4.0' exits 0 — a positive ancestry result, self-certifying — and packages/rest/package.json on main reads 17.4.0. packages/rest/CHANGELOG.md carries it under the 17.4.0 heading. So: released, not in flight.

Zero read sites, three instruments, each with a lit control.

instrument	result for the two containers	its control
spelling sweep (git grep, no pathspec, filtered after)	responseFormat / includeMetadata / includePagination / termsOfService reach packages/rest/src only at the NormalizedRestServerConfig type declaration and the normalizeConfig build-through	enableCrud / apiPath / projectResolution return real read sites in rest-api-plugin.ts, direct-mount-composition.ts, dispatcher-plugin.ts, serve.ts
spread sweep	no spread of this.config.api anywhere; the only { ...api } in the tree is packages/spec/src/conversions/registry.ts, which copies the stack api: block	80 spreads found in packages/rest/src alone, so the file filter is lit
computed access / whole-config serialization	no bracket access, no Object.keys/values/entries over this.config, no JSON.stringify(this.config	the same regex finds Object.entries(this.config.initialData) in driver-memory

Radius: every tracked file in this repo, plus the sibling repo objectui measured directly at the pinned sha 87af769e and at its head 98178b20. Not in radius, and declared rather than papered over: the closed cloud runtime is not reachable from this container, which is why every evidenceScope reads in-repo.

Two structural backstops a grep cannot give: NormalizedRestServerConfig is declared without export, and RestServer.config is private — the normalized block is unreachable from outside that one class. And for documentation specifically, the /openapi.json handler passes info through untouched by a recorded decision (#11646); the served info.title is the literal 'ObjectStack REST API' written in packages/spec/scripts/build-openapi.ts. An enforce route for that container is not wiring up a title — it is reopening who owns info.

What the parse does and does not settle. Since the seam moved, a malformed api.documentation or api.responseFormat is now refused at construction. That is accept/reject, a different axis from liveness: nothing reads either key's value back. The ledger states this distinction rather than letting a reader collapse the two.

File-surface accounting

The claim declared packages/spec/src/api/rest-server.zod.ts, packages/rest/src/rest-server.ts, their tests, packages/spec/liveness/ conditionally, and .changeset/. Three files on the branch are outside that. Each was put to an ablation — mutate, prove the mutation landed on disk by blob hash, run the gate, restore and prove the restore by git diff HEAD — rather than argued for.

1. docs/qa/platform-checklist/coverage.json — mechanically forced. Kept.
scripts/check-platform-checklist.mjs derives its kind universe from packages/spec/liveness/*.json and is bidirectional. Renaming the key (blob 690af861 to 6a554e59) took pnpm check:platform-checklist to exit 1 on both limbs at once:

✗ coverage.json · rest_api: UNCLASSIFIED — the platform has this capability (liveness ledger exists)
  but the checklist neither tests nor waives it.
✗ coverage.json · rest_api_ABLATED: ORPHAN — mapped kind has no packages/spec/liveness/rest_api_ABLATED.json

Adding the ledger is what obliges the entry. The entry itself is a scope statement, not a coverage claim: it names what the two mapped items do cover (the eight enable* switches at their defaults, and version / basePath / apiPath as a derived prefix) and what they do not (every non-default variant, and both containers on this card).

2. packages/spec/scripts/liveness/check-liveness.mts — mechanically forced, both hunks. Kept.
Deleting the SPEC_ONLY_SCHEMAS row (blob 4ec7afb6 to cc1136c0): check:liveness exits 1 with Error: metadata type 'rest_api' has no registered schema. Deleting the GOVERNED entry (blob 4ec7afb6 to 6adc1c38): exit 1 with four findings — an unbacked README row, a heading error, a stale count artifact, and a README/state-counts disagreement. The ledger is simply not read without both. The same commit also corrects the now-expired fence sentence in the gate's own comment, which is where the exclusion was recorded in the first place.

3. packages/spec/scripts/liveness/tombstoned-row-status.test.ts — NOT gate-forced. Kept anyway, and here is the measurement.
Deleting the mirrored rest_api row leaves the test green. That is not evidence the edit is idle — it is evidence the pin is a floor. TOMBSTONE_FLOOR = 40 is asserted with toBeGreaterThanOrEqual, so it absorbs the loss. Driven directly, with the floor raised to 41 as the probe:

• floor 41, mapping present → green, so the population is 41
• floor 41, mapping deleted → AssertionError: expected 40 to be greater than or equal to 41

So the row adds exactly one member to the measured population: rest_api.requireAuth, a retiredKey() tombstone whose dead verdict would otherwise never be visited by the invariant this test exists to enforce. That is the #18304 shape — agent.tools sat at live on a tombstoned key for months because nothing walked it. The edit is correctness-forced even though no gate reds without it. See the acceptance note below on the floor itself.

Nothing else was widened. packages/spec/liveness/README.md and state-counts.md are inside the conditionally-declared packages/spec/liveness/ surface and are both gate-owned.

Verification

Taken on the final commit 006888fbef.

• Gate families — derived mechanically from the change set, not from a hand-written list: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack yields 70. All 70 ran with $? captured before any pipe; --ran reconciliation reads 70 derived, 66 run, 4 NOT-MEASURED, 0 UNRUN.
• The 4 NOT MEASURED are check:doc-formula-expressions, check:dual-build-cjs-loads, check:lean-entry-closure and check:type-check-debt, all exit 3 — PREREQUISITE NOT MET, one cause: they read built output and the workspace closure is not built in this container. Exit 3 is neither a pass nor a failure, and none of them is recorded as one. CI builds fresh and runs all four.
• Which side the changeset gate can fail on: check-changeset-no-major --base origin/main ran the bump-level limb against the real merge base and passed ("This diff introduces no major bump"). Only its LEVEL AXIS limb reads NOT APPLICABLE, for want of a pull_request payload — so the green is real on the axis this diff could have moved, and vacuous only on the axis a local run cannot reach.
• pnpm lint — the whole-repo scan, eslint . --no-inline-config: exit 0 in 1m40s. No narrowing claimed and none needed.
• pnpm --filter @objectstack/spec typecheck — exit 0. This package's typecheck is three programs, so it reaches src, scripts/ (where the edited gate lives) and the test layer.
• Tests — packages/spec/scripts/liveness: 12 files, 333 tests, all pass. The ledger directory's only consumer outside this package is packages/lint/src/lint-liveness-properties.ts; its tests run 91 assertions green. No author warning is emitted, and none should be: nothing here is marked authorWarn, because a RestServerConfig is never part of a stack and that lint walks stack collections.
• state-counts.md is generated, not hand-edited — git hash-object reads 7c8c1cb1 before gen:liveness-counts and 7c8c1cb1 after, with the working tree clean. Byte-identical to the generator's own output.
• The drilled documentation container adds no row to the undrilled-container baseline — undrilled-containers.baseline.json is untouched by this branch, contains zero rest_api coordinates, and check:liveness is green against it. That gate fails in both directions: an undrilled container missing from the list reds, and so does a listed row whose container has since been drilled.
• A changeset is required and present. packages/spec's files[] includes liveness, so the ledger ships in the tarball. skip-changeset would be wrong here.

Acceptance notes

• The non-vacuity floor was not advanced with the population it measures. TOMBSTONE_FLOOR = 40 in tombstoned-row-status.test.ts, and its comment says "40 was the measured population". This branch takes the real population to 41 (measured above). The pin is toBeGreaterThanOrEqual, so this is not a gate failure and arguably not a defect — a >= floor is loose on purpose so that every new governed type does not have to touch this file. But the prose now reads one behind the tree, and the floor carries a row of slack it did not have before. Whether it advances is the file owner's call, so it is noted rather than changed. Not filed.
• One commit on this branch is mine and not the original author's: 006888fbef corrects the objectui cross-repo control count cited in the ledger. The note recorded basePath = 176 at the pin; re-measured on the two trees the note itself names, git grep -n -F basePath returns 181 at 87af769e and 182 at 98178b20. The zero it controls is unchanged — all six key spellings return 0 at both. A cited count that does not reproduce on the tree it names is not a reading, so the number was corrected rather than the tree re-chosen. Ten row notes plus the header carried it; all eleven updated.
• The upstream paper trail for this family does not resolve. #14366, #14369, #14691, #14365 and #14690 all return HTTP 404 while neighbours resolve at 200. The work they name is visibly landed in the tree, which is how every claim above was checked — read the tree, not the tracker. The class is carded at The repo cites issue numbers that do not resolve — 5 measured instances, and the two cited from source docblocks and a release page are swept by nothing #17512. No replacement numbers were guessed.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 3 changed file(s) yielded no anchor (packages/spec/liveness/README.md, packages/spec/liveness/rest_api.json, packages/spec/liveness/state-counts.md), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 3 changed file(s) yielded no anchor (packages/spec/liveness/README.md, packages/spec/liveness/rest_api.json, packages/spec/liveness/state-counts.md) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 136 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 1f69917c5c76c065256a9bbaac3afc587279b9ba → packageMentionDocs.