feat(spec): the /layers answer declares the pending draft as a layer, draft - #29863

📓 Docs Drift Check

4 anchor(s) derived from 1 changed package(s); no hand-written page names any of them. ⚠️ 1 changed file(s) yielded no anchor (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.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin f93d95ad1640c3bb40ed53700316611b710913da && git checkout f93d95ad1640c3bb40ed53700316611b710913da
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4b71a82b76531059ad45ba224899aaadaa219ebc 40182cb5ffc8b95957e96def6a7e55a8460c9a55 && git checkout -B drift-repro 4b71a82b76531059ad45ba224899aaadaa219ebc && git merge --no-ff 40182cb5ffc8b95957e96def6a7e55a8460c9a55

node scripts/docs-audit/affected-docs.mjs --json 4b71a82b76531059ad45ba224899aaadaa219ebc

domain:server#1 · os-warren · session_01JQwxbXsK9j25sd7eVwW96G

Contract-review-claim: session_01JQwxbXsK9j25sd7eVwW96G · head 74983ea · 2026-11-03T08:39Z

domain:server#1 · os-warren · session_01JQwxbXsK9j25sd7eVwW96G

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 74983ea388b27ece483f9112df1b5c21e6efa1bd
Local-runs: none
Scope: packages/spec/src/api/protocol.zod.ts + packages/spec/authorable-surface/api.json, .changeset/29855-layers-draft-layer.md, content/docs/references/api/protocol.mdx, packages/spec/src/api/meta-item-response-shapes.test.ts (read for the pins), scripts/check-changeset-no-major.mjs, scripts/pm/clause2-line.mjs, packages/spec/scripts/build-schemas.ts (ledger depth), packages/metadata-protocol/src/protocol-meta-layered-reads.ts, packages/metadata-protocol/src/protocol-meta-item-reads.ts, packages/rest/src/meta-item-read-gate.ts (createMetaLayeredAnswer, META_ITEM_LAYERS), packages/rest/src/rest-server.ts (serveMetaItemLayered), packages/runtime/src/domains/meta.ts (layered dispatch), AGENTS.md Post-Task Checklist §3 — all read in the live tree, none reviewed. The lane remainder at TIER_DEFAULT is the test file, the changeset prose and the regenerated mdx.

① Derived judgments

1. GetMetaItemLayeredResponseSchema gains draft: z.unknown().optional() — a widening of a published response accept set (packages/spec/src/api/**, exported). Clause-②: yes (widening) is right. The type GetMetaItemLayeredResponse gains an optional key; no existing member changes; an answer without the key still parses (pinned). Correct.
2. GetMetaItemLayeredRequestSchema.packageId — describe text only, no accept-set change. Correct.
3. packages/spec/authorable-surface/api.json gains the row api/GetMetaItemLayeredResponse:draft. The ledger is built from schema.properties ONE LEVEL DEEP (build-schemas.ts L107–117 and nested-authorable-keys.test.ts say so in as many words: recursing would publish 14,376 nested keys), and GetMetaItemLayeredResponse is a ledgered schema, so a new TOP-LEVEL member moves the shard. The regenerated row is correct and the only one the member can move. This row is what ② turns on.
4. content/docs/references/api/protocol.mdx: two rows regenerated. I compared both cells against the describes in the head tree: the draft row and the layered-request packageId row match the Zod text byte for byte. Correct.
5. No export added, so api-surface/, export-origins and the declaration map do not move — consistent with the file list. Correct.
6. check:test-typecheck ledger unchanged — the one new compile-time pin is in a tsconfig.test.json file, no new error. Plausible from the diff; CI's Type Check lanes did not conclude on this head (see ②).

② Semver level

Must-fix — the head's own Check Changeset is red, and the gate is right. Run 41604712591 job 125811566989, step check-changeset-no-major --base, verdict none-baseline-moved: "This PR declares clause-② yes (widening) and metadata-protocol none, and it moves a metadata-protocol baseline the ratchets record: packages/spec/authorable-surface/api.json". The changeset at this head grades @objectstack/spec patch with Metadata-protocol: none; the PR body as read by that run said the same.

Which is right. Ruling A as mechanised (check-changeset-no-major.mjs L907–945): the level follows the Metadata-protocol: line alone, and "where the existing ratchets can SEE a protocol change, a declared none over it is refused: a changed packages/spec/authorable-surface/ shard is a key added or removed." The gate's remedy text is explicit that the fix is the declaration, never the baseline: "a baseline is never edited to quiet this gate." AGENTS.md Post-Task Checklist §3 says the same in prose ("a kind takes at least minor on a package the diff moves, none takes patch"). So on this diff the right declaration is Metadata-protocol: added with '@objectstack/spec': minor, in both carriers (the gate reads the body line from $GITHUB_EVENT_PATH, L1845; check-adr-0087-registration reads the changeset).

Why the precedent did not transfer. PR #29779 (f87239ae7b) added data.noticeCode to CloneFlowResponseSchema — a key NESTED under data. The ledger records api/CloneFlowResponse:data and nothing beneath it (one level deep, above), so that shard did not move, none was invisible to the ratchet, and patch passed. Here draft is a top-level member of a ledgered schema, the shard moved, and the ratchet saw it. The card's "precedent PR #29779 ⇒ patch" was a reading of the gate's blind spot, not of its rule. Semver-wise minor is also the honest level for a new optional response member.

One observation, not this PR's to fix: under this gate the level of two equally additive REST-response members depends on nesting depth (top-level ⇒ minor, nested ⇒ patch), and api/* response schemas are in a ledger whose rule text speaks of "what a metadata author can write". If a lane disagrees with REST response keys driving the level, that is a card against the ledger or the gate text, not a reason to keep none here.

Clause-②: line — yes (widening) matches the diff. Metadata-protocol: line — none is wrong at this head; added is right.

Check-runs on this head, read from the API: Check Changeset failure (real, above). Green: Governed Surface Queue Guard, PR-body guards, Check PR Size, Spec property liveness, Lint · PM dispatch-gates, Lint · scoped · tooling self-tests, Dogfood Regression Gate, Check Documentation Links, Plan Test Core shards, Auto Label, filter, Flag docs. Not concluded: Test Core 1–8, Test UI 1–16, Type Check UI, Build Core, Live E2E UI, Build Docs, every Type Check and Lint lane were cancelled when the branch moved to a newer head; the aggregators TypeScript Type Check, Lint & Repo Gates and Test UI report failure only because their lanes concluded cancelled ("lane typecheck-workspace concluded cancelled -- expected success"), which is a cancellation signature, not a gate red. The Check Changeset red is this PR's own declaration, not a merge-base signature, so no exception applies. "All checks green" is not met on this head.

Head movement. The branch now carries one further commit after this head, which rewrites the changeset to '@objectstack/spec': minor and Metadata-protocol: added, and the live PR body now reads Metadata-protocol: added. That commit is a fix-only commit answering this finding; it is NOT reviewed by this record and owes a delta review by the same reviewer on its own head (contract-review.md: 只落发现的 commit 由同一复核者 delta 复核). Auto-merge is not armed; the PR is a draft; nothing to disarm.

③ Boundary flags

• Dev flag (PR body, os-dev-report): GetMetaItemLayeredRequestSchema.packageId's describe now says it also scopes "the draft layer to that package's pending draft row". Fine. In scope: same hits file, and the card's Wanted names the draft "for the item (and the requested packageId, when given)". Accurate as the conditional it states: the producer already resolves draft rows by package (findServedOverlayRow({ state: 'draft', packageId }) in protocol-meta-item-reads.ts L266–270), so "when given, that package's draft row" is implementable without a decision. It says nothing about the absent case, which is exactly what the acceptance note defers to meta: a pending draft has no untranslated, author-owned read; Studio re-opens its object draft translated and governed #29814 — consistent, not premature. (Pre-existing and not this PR's: the sentence says packageId scopes code, while on main it also addresses the overlay row via contentPackageId, L278.)
• Acceptance note "what a server does when packageId is absent is meta: a pending draft has no untranslated, author-owned read; Studio re-opens its object draft translated and governed #29814's" — accepted, and escalated to meta: a pending draft has no untranslated, author-owned read; Studio re-opens its object draft translated and governed #29814 with the existing addresses to report against: the protocol's strictDraftReadAddress (the draft the version names; protocol-meta-item-reads.ts L203–214) and, at the transport, step 1c of createMetaLayeredAnswer (a name several packages hold, read naming none, is refused 409 before any layer is served).
• Escalated to meta: a pending draft has no untranslated, author-owned read; Studio re-opens its object draft translated and governed #29814 (not a finding against the schema): (a) createMetaLayeredAnswer judges absence (step 1, 404) over META_ITEM_LAYERS = ['effective','code','overlay'] and masks over META_ITEM_MASKED_LAYERS; the server half must decide whether draft joins the presence test (a draft-only item with no published layers) and must add it to the gate and mask lists ("⛔ A step is added there, never here"). (b) With packageId absent and "no injected columns", the body carries no package binding; the server half may want to report which package's draft row was served (as overlayScope does for overlay). Both are the consumer's to settle and report.
• open_questions: [] — none to answer.
• PR user.login is objectstack-fleet[bot]; no author note owed.

④ Design judgment

packages/spec/src/api/protocol.zod.ts, judged against the #5882 ruling it cites, the card's Wanted, and its first consumer #29814 (the REST route serveMetaItemLayered, the runtime dispatcher, and the shared chain createMetaLayeredAnswer):

• Shape — a /layers member, not a ?state=draft switch: holds. GET /meta/:type/:name?layers=true 应答一个 spec 未声明的第三形状 —— 路由只声明了一个 responseSchema #5882 B retired "two shapes, chosen by query flag" so one path has one response shape; a switch that changes the plain read's representation is that pattern. /layers is already the untranslated, stored-at-each-layer view (REST serveMetaItemLayered: "Not translated and not cached, both deliberately"). The new docblock paragraph states this accurately; the GET /meta/:type/:name?layers=true 应答一个 spec 未声明的第三形状 —— 路由只声明了一个 responseSchema #5882 rationale paragraph is byte-identical to main save "three-layer" → "layered", which the fourth layer makes true.
• Name draft: fine. The three existing layers are named by what they are, not by row state, so draft is the first state-named layer; but it is the stored draft overlay and nothing else, the card proposed it, triage endorsed it under the veto window, and the Studio/Setup buffer code already spells draft ?? …. No better name is owed.
• z.unknown().optional(): holds. Same carrier as code/overlay/effective (z.unknown(), which accepts null), so the three-way state is absent / null / object. The three runtime pins cover all three and the ablation shows the object and null pins are load-bearing. The compile-time pin LayeredDeclaresDraft keeps the consumer cast-free.
• "absent = not served, never no draft": consistent and necessary. Until meta: a pending draft has no untranslated, author-owned read; Studio re-opens its object draft translated and governed #29814 lands every server answers without the key; a consumer that read absence as "no draft" would fall through to overlay ?? code and silently lose the author's draft — the very defect of meta: a pending draft has no untranslated, author-owned read; Studio re-opens its object draft translated and governed #29814. The sentence follows the _diagnostics precedent in the same schema ("absence means no opinion, never valid") and the feat(spec): CloneFlowResponseSchema declares an optional data.noticeCode beside notice #29779 noticeCode one. The corollary the describe implies — a server that serves the layer always emits the key, null when nothing is pending — is what meta: a pending draft has no untranslated, author-owned read; Studio re-opens its object draft translated and governed #29814 must pin.
• "untranslated, ungoverned, with no injected columns": accurate and implementable. On main the layered producer builds overlay as convertStoredItem(type, storedRowDocument(rec)) with no governServedObject (that is applied to effective only, L506), and the REST/runtime chain does not translate it. The ?state=draft item read, by contrast, goes through serveItem → decorateMetadataItem and serveDraft (protocol-meta-item-reads.ts L105–130), which is the governed, decorated copy the card measured. A draft row served through the same convertStoredItem(storedRowDocument(row)) path is exactly what the describe promises. "Exactly as stored" reads as code's "exactly as shipped" does: the transport's per-caller gate ([finding] class closure: the alternate read doors of /meta/:type/:name (/layers, ?layers=true, /published) serve a set-gated doc's BODY to a non-holder; they skip every per-caller read gate the plain read applies #20156, whole for whoever may write the item) and the ADR-0106 mask apply to every layer alike, and that is the chain's documented contract, not this describe's to restate.
• null when no draft is pending: holds. Parallel to overlay: null ("not customised") and distinct from the strict ?state=draft read's 404 no_draft, which is the right split: /layers reports, it does not refuse.
• packageId scoping: holds (③ above).

No must-fix in ④. No should-fix in ④. The one must-fix in this record is ②'s declaration/level, which the gate itself names.

Lane remainder (not reviewed here, noted for the ACCEPT): meta-item-response-shapes.test.ts L76, the LayeredCarriesNoItem alias, lost the space between = and Assert — cosmetic; Lint · ESLint did not conclude on this head.

Implemented-by: claude/project-thread-dxle5n
Reviewed-by: session_01JQwxbXsK9j25sd7eVwW96G

VERDICT: FAIL

domain:server#1 · os-warren · session_01JQwxbXsK9j25sd7eVwW96G

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 40182cb5ffc8b95957e96def6a7e55a8460c9a55
Local-runs: none
Scope: packages/spec/src/api/protocol.zod.ts + .changeset/29855-layers-draft-layer.md (the one file the delta commit moves), the live PR body (both declaration lines and the level bullet), the two Check Changeset runs on this head, scripts/check-changeset-no-major.mjs (read), and the prior record on 74983ea388b27ece483f9112df1b5c21e6efa1bd, comment 6599317618, whose ①, ③ and ④ this delta carries forward unchanged.

Delta review: the same reviewer, on the one fix-only commit after the FAIL head. The compare 74983ea388…40182cb5ff holds one commit and one file, .changeset/29855-layers-draft-layer.md, +2 −2: '@objectstack/spec': patch → minor, Metadata-protocol: none → added. No hits file moved, so ④ is the prior record's and is not re-rendered; the tier stays CONTRACT_REVIEW_TIER because the PR's committed tree still carries the published schema.

① Derived judgments

Unchanged from 6599317618 ①: the diff against main publishes the same accept-set widening (GetMetaItemLayeredResponseSchema.draft, optional), the same ledger row api/GetMetaItemLayeredResponse:draft, the same two regenerated mdx rows, no export. The delta commit publishes nothing new; it changes what the release ledger says about the same diff.

② Semver level

The must-fix of 6599317618 is answered. At this head the changeset grades @objectstack/spec minor and declares Clause-②: yes (widening) / Metadata-protocol: added; the live PR body carries the same two lines (lines 4–5) and its "What changes" bullet now reads "@objectstack/spec minor, with both declaration lines", so body, changeset and diff agree. added is the kind the moved authorable-surface shard records (a key entered), minor is the level ruling A assigns it, and the pair is the shape check-changeset-no-major and check-adr-0087-registration both accept for a non-breaking widening (no (narrowing) arm, no !, no banner owed).

Gate verdicts on this head, read from the check-runs API:

• Check Changeset ran twice. Run 125813870035 is failure with the prior head's signature (none-baseline-moved: body line read as Metadata-protocol: none) — it fired on the push, before the PR body was edited, and the gate reads the declaration from the event's body. Run 125814393589 is success: "LEVEL AXIS: this PR declares clause-② yes (widening) and metadata-protocol added, and no package whose published source it moves is graded patch." The gate re-reads the body on the edited event by design, so the newest run of this check on this head governs; the earlier red is superseded, not a standing red.
• Completed green: 23 (among them Governed Surface Queue Guard, PR-body guards, Check PR Size, Spec property liveness, Lint · PM dispatch-gates, Lint · scoped · tooling self-tests, Lint · ESLint, Lint · docs & code guards, Lint · repo & tooling gates, Type Check · source gates, Type Check · debt ledger, Build Docs, Build UI Deps, Dogfood Regression Gate, Check Documentation Links). Skipped: 10 (opt-in and conditional workflows).
• Still in_progress at the time of this read: 31 — Test Core 1–8, Test UI 1–16, Type Check UI, Build & E2E UI, Live E2E UI, Build Core, Type Check · consumer gates, Type Check · workspace, Lint · CI, release & engine gates. None has concluded red. The landing pre-check "every PR check green" is therefore not yet satisfiable from this read; the dispatching seat confirms it when these conclude. Nothing in the delta can move them: the one changed file is a changeset, which none of those lanes compile or test.

Clause-②: yes (widening) — right. Metadata-protocol: added — right at this head.

③ Boundary flags

• No new dev flag and no open_questions on the delta. The prior record's ③ stands: the request-side packageId describe edit is fine; the absent-packageId case, the META_ITEM_LAYERS / mask-list presence question and the draft row's package binding are escalated to meta: a pending draft has no untranslated, author-owned read; Studio re-opens its object draft translated and governed #29814, the consumer, to settle and report.
• The PR body's level bullet was edited to match (minor); the body's Human Minimum §5 tick ("both declaration lines are filled in here and in the changeset") is now true.
• PR user.login is objectstack-fleet[bot]; no author note owed. PR is a draft; auto-merge not armed; nothing to disarm.
• Observation carried from 6599317618, not this PR's: the ledger's one-level depth makes the level of an additive REST-response member depend on nesting (top-level ⇒ minor, nested ⇒ patch); a card against the gate or ledger text if a lane disagrees.

④ Design judgment

Not re-rendered: the delta moves no hits file. The judgment on packages/spec/src/api/protocol.zod.ts in 6599317618 ④ stands in full — the /layers member over a ?state=draft switch holds against #5882 B; the draft name, the z.unknown().optional() tri-state, the "untranslated, ungoverned, no injected columns" describe and its packageId scoping are accurate and implementable against the layered producer and the REST/runtime chain; the regenerated mdx matches the describe byte for byte. No must-fix, no should-fix. Lane remainder note (cosmetic =/Assert spacing in the test file) is unchanged and is the lane seat's.

Implemented-by: claude/project-thread-dxle5n
Reviewed-by: session_01JQwxbXsK9j25sd7eVwW96G

VERDICT: PASS

domain:server#1 · os-warren · session_01JQwxbXsK9j25sd7eVwW96G

席位核对

ACCEPT · domain:server#1 · head 40182cb5ffc8b95957e96def6a7e55a8460c9a55 · 2026-11-03T09:16Z · contract review FAIL 6599317618 on 74983ea3 (one must-fix: the changeset level), then delta PASS 6599376127 on this head, at CONTRACT_REVIEW_TIER (schema face packages/spec/src/api/protocol.zod.ts, fable subagent, independent of the dev); test file, changeset prose and regenerated mdx read by the seat at TIER_DEFAULT

1. Shape: draft, base main, Fixes #29855. 5 files, +66/-4: protocol.zod.ts (GetMetaItemLayeredResponseSchema.draft: z.unknown().optional(), docblock paragraph, request packageId describe), meta-item-response-shapes.test.ts (three new pins), regenerated protocol.mdx (two rows) and authorable-surface/api.json (one row, api/GetMetaItemLayeredResponse:draft), one changeset (@objectstack/spec minor, Clause-②: yes (widening), Metadata-protocol: added). Spec half of meta: a pending draft has no untranslated, author-owned read; Studio re-opens its object draft translated and governed #29814, split out contract-first. Not governed, under 3000 lines.
2. Premise measured (report 6599096757): the ?state=draft read serves the draft translated and governed, with injected columns. /layers is the untranslated author read, and under GET /meta/:type/:name?layers=true 应答一个 spec 未声明的第三形状 —— 路由只声明了一个 responseSchema #5882 (B) the draft joins it as a member, not as a query switch. The review checked the describe against the live producer: overlay is built without governServedObject, and findServedOverlayRow({state:'draft', packageId}) already exists.
3. Gates on this head: check-runs pinned to 40182cb5: 69 total, 58 success, 10 skipped, 1 failed. The one red is Check Changeset 125813870035. It fired on the push and read the pre-edit body line Metadata-protocol: none. Its rerun 125814393589 on the edited body is success, so the red is superseded.
4. Accepted deviations: the first head graded spec patch / none over a moved authorable-surface shard. Fixed in 40182cb, and the seat patched the PR body to match (added, minor). This PR ships no server code: an older server still parses without draft, and an absent draft means "not served".
5. Out of scope: meta: a pending draft has no untranslated, author-owned read; Studio re-opens its object draft translated and governed #29814 (the REST route and the runtime dispatcher serve draft) is paused under the maintainer's order 「没开工的暂停」. The review escalated these to it: createMetaLayeredAnswer's META_ITEM_LAYERS presence test and mask list gain draft, plus draft-only items, packageless draft addressing (strictDraftReadAddress 1c) and the draft row's package binding. Cosmetic: test file L76 is missing a space before Assert.
6. Landing: not governed and under 3000 lines ⇒ the seat lands it (pr_ready + automerge_enable). At MERGED: landing record on protocol: GetMetaItemLayeredResponseSchema declares an optional draft layer, the pending draft as authored, so Studio can re-open a draft untranslated (contract-first half of #29814) #29855 (closed by Fixes), pm:dispatched and pm:blocking removed.