feat(spec): declare the save door's request members and de-cast the REST PUT literal (#12004)

[os-warren]

Fixes #12004

PUT /api/v1/meta/:type/:name was the biggest remaining request-shape gap in the meta write family: saveMetaItem is a REQUIRED protocol member, but SaveMetaItemRequestSchema declared 3 of the ~11 members the REST door sends, so the call-site literal was cast as any — pure request-shape smuggling (TS2353 on every undeclared key once the cast comes off), never member-existence feature detection. This lands the #11006 maintainer-ruled pattern (2026-08-22, option B: per-member protocol-vs-transport walk, mirror the implementation's parameter type member for member) exactly as PR #12003 landed it for the audit and reset doors and PR #13521 for the history door.

Per-member verdicts (triage 2026-08-25, executed here)

Member	Verdict	Basis
organizationId (optional string)	DECLARED	straight #11426/#11679-lineage; selects the ADR-0005 overlay partition and the audit-row scope; refused 403 for non-overridable types
parentVersion (optional, string or null)	DECLARED, nullable	implementation declares string-or-null and, unlike the reset twin (which folds a present null back to the current hash), passes null through to the repository conflict check: null is the first-write pin, absent is unpinned last-write-wins — a real, enforced absent-vs-null distinction
actor (optional string)	DECLARED	#11679 lineage; recorded on the history event and audit row; the REST door's one producer is the authenticated identity, never a header
force (optional boolean)	DECLARED	the destructive-change acknowledgement (query param force=true); only object saves reach that diff
mode (optional, draft or publish)	DECLARED, closed enum	ADR-0005 lifecycle; anything but draft (absent included) is the legacy straight-to-live default
packageId (optional, string or null)	DECLARED, nullable	ADR-0048 binding; the absent-vs-null distinction the publish schema already documents; a named read-only base package is refused
writeFace (optional, closed enum of the three faces)	DECLARED after the four-axis walk (below)	server-stated per #10888 — declared because it is a real implementation parameter with three server-side producers
environmentId	NOT declared	transport-level by the #9741 ruling; rides the rest wrapper TransportScopedMetaRequest, pinned shape-absent
source	NOT declared	never sent by any door — its only producer is the implementation's own internal migrate call; the #11426 publish precedent leaves it out until a producer on this contract pulls it; pinned shape-absent

The writeFace walk (converged: declare)

• Real business need: measured producers — the REST PUT door (meta-envelope), the runtime dispatcher door (meta-dispatch, packages/runtime/src/domains/meta.ts), and the duplicate-package internal call (package-duplicate); measured consumers — the 409 destructive-change remedy and the 422 findings clause both branch on it. A real parameter, not speculation.
• Long-term soundness: the [finding] Meta-read request schemas still omit previewDrafts / state / environmentId, so the REST call-site casts survive the organizationId catch-up #9741 transport test (routing resolved before method entry, implementation never reads it) answers the OPPOSITE here — the implementation reads it, and one producer is not even a transport. The wrapper's own contract says a key that belongs to the request belongs in the spec schema; leaving it out would force the cast to stay forever.
• Hard to get wrong for AI authors: the declared member is a closed enum whose describe() states the server-stated property (saveMetaItem's spec-validation 422 message restates its issues[] on the envelope, but message-only faces (duplicatePackage failed[].error) forbid the #10524 trim until they declare a structured channel #10888: every producer builds the request field by field, never spreads a wire body, so a client-sent face is simply never read) — the same treatment the merged reset twin gives actor. Declaring records the truth; hiding it keeps a phantom surface only the cast could reach.
• Startup scope: records what ships, adds zero capability; the alternative (leaving it undeclared) blocks the card's primary deliverable, since the door sends the face unconditionally.

The de-cast, and its reverse verification

The literal is now a named const typed TransportScopedMetaRequest wrapping SaveMetaItemRequest — the reset-door spelling, because this door still spreads the transport-level environmentId (long-standing wire shape, deliberately unchanged). Wire payload byte-identical: same keys, same conditional spreads, same server-stated face; the rest-server diff adds a type annotation and a comment, nothing else.

Reverse verification (predicted red, from the committed fix): a smuggledKey pasted into the literal turned the rest typecheck red with

src/rest-server.ts(5831,25): error TS2353: Object literal may only specify known properties, and 'smuggledKey' does not exist in type 'TransportScopedMetaRequest...'

and the error text prints the widened member list from the rebuilt spec dist — proving the literal compiles against the regenerated declarations, not a cache. Restore proven byte-identical: git diff HEAD empty, worktree blob hash equals the HEAD blob hash, zero grep hits for the smuggled key.

One measured behaviour pin rode along: the untouched item: z.unknown() member is key-REQUIRED at parse (absent key refused; a present explicit null parses and is then refused 400 by the implementation's own guard) — pre-existing contract behaviour, now pinned instead of silent.

Verification (all quoted verdicts from head 397d9ea; census repair at 722b069, union re-run on that final head reported on the card)

• spec build: check-dts-emitted: @objectstack/spec - 34/34 declared declaration file(s) present. — VERDICT command-exit 0
• spec typecheck (tsc + test-layer): check:test-typecheck: OK — @objectstack/spec's test layer compiles — VERDICT command-exit 0
• spec targeted suites (protocol.test.ts + type-alias-convention.pin.test.ts): Test Files 2 passed (2) · Tests 181 passed (181) — the existing Iso135 isomorphism pin still holds (widening adds only optional/nullable/enum members, no defaults or transforms)
• rest dependency graph build (turbo, 26 packages): Tasks: 25 successful, 25 total
• rest typecheck: check:test-typecheck: OK — @objectstack/rest's test layer compiles — VERDICT command-exit 0
• rest door suites (9 files: capability gate, compound force/mode parity, write org-scope, query multiplicity, org-scope url spelling, rest.test.ts, 4xx truncation, unknown-type refusal): 110 passed + 261 passed
• spec generated artifacts: check:generated proved exactly one stale (content/docs/references — the new describe() rows) and --fix regenerated only it; check:authorable-surface, check:api-surface, check:export-origins, check:strictness-ledger all green (no new z.object sites, no new exports — the authorable-surface api.json picked up the seven new member rows from the rebuilt schema, as the history precedent's did)
• system-context census: the door diff shifted eight rest-server.ts isSystem anchors (+1 import, +17 door block); --fix refused as in the history landing, anchors re-pointed by hand; check-system-context-census: OK — 109 elevation read sites in 20 packages across 45 files, all anchored; 145 anchors resolve, 27 declared non-read.
• derived-gate union (dispatch-gates.mjs, no paths — 62 commands): first pass 56 exit-0; census repaired to green as above; check-test-completeness and check:pm-half-states exit 3 (locally unmeasurable by design — CI shard attestation and the PM board sweep); the three workspace-build-prerequisite gates re-run after a full turbo run build, and the whole union re-runs on the final head — quoted verdicts land in the card report

skip-changeset does not apply: this PR publishes a spec minor and a rest patch (changeset pair mirrors the merged history precedent).

Out of scope, untouched here: the door's 501 envelope, tenant-scoping questions, and the dispatcher door's own literals (#13598 records the adjacent runtime service-handle casts). #12004 is the only card addressed by this PR.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/rest, @objectstack/spec, touching 9 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/rest/src/rest-server.ts, packages/spec/authorable-surface/api.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

16 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 3d0897459577835a78fc96a8f718eb3b139708a3.

⛔ 2 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/rest/src/rest-server.ts, packages/spec/authorable-surface/api.json) — pages documenting those are invisible to this run
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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.

Coarse fallback — 128 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 3d0897459577835a78fc96a8f718eb3b139708a3 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 88612888280db45443f56bed4a6c0786d8660a68 — the merge of head 722b069fa7f5c361b7d94861404e4bdd940e0264 into base 3d0897459577835a78fc96a8f718eb3b139708a3, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 88612888280db45443f56bed4a6c0786d8660a68 && git checkout 88612888280db45443f56bed4a6c0786d8660a68
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 3d0897459577835a78fc96a8f718eb3b139708a3 722b069fa7f5c361b7d94861404e4bdd940e0264 && git checkout -B drift-repro 3d0897459577835a78fc96a8f718eb3b139708a3 && git merge --no-ff 722b069fa7f5c361b7d94861404e4bdd940e0264

node scripts/docs-audit/affected-docs.mjs --json 3d0897459577835a78fc96a8f718eb3b139708a3

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 3d0897459577835a78fc96a8f718eb3b139708a3 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-warren]

Released by maintainer instruction. Provenance: maintainer, live PM session chat, 2026-08-31 ~04:0xZ, verbatim 「pr 绿了为什么不合并」 — read as a personal release of the green parked contract-face PRs, per the recorded #12606 precedent (「12606 绿了」= personal release lifting the needs:contract-review park). Not a self-release: the dispatching seat acts on the maintainer's word, citing it here. Pre-release verification: all 36 check runs on head 722b069f completed success/skipped (zero red); PM checklist review of record: ACCEPT on #12004 (comment 5473171979), run at claude-fable-5; dispatch tier claude-fable-5 (not below CONTRACT_REVIEW_TIER); the one member carrying its own verdict (writeFace, four-axis converged to declare) is named in that review; no governed surface in the diff. Stripping needs:contract-review from both carriers, flipping ready, arming the queue. — session_01PBjwYLS6BciTQW3c9xQiD2

---

Generated by Claude Code