fix(spec): judge a nested RETIRED_KEYS_BY_MAJOR row instead of ignoring it

[os-bill]

Fixes #17969

Clause-②: yes

What was broken, and the reading that says so

check:authorable-surface builds currentKeys from schema.properties one level deep
(packages/spec/scripts/build-schemas.ts). Check (b2) — the guard that refuses a
RETIRED_KEYS_BY_MAJOR entry naming a key the build still emits as LIVE — consults that map, so a
dotted row matched nothing in it and was silently ignored rather than judged. 48 of the shipped
rows are dotted.

Reproduced on this branch before the fix, by ablation, with the card's own controls:

probe	pre-fix check:authorable-surface
fabricated nested row system/SchemaLevelIsolationStrategy:performance.zzNotARealKey9999	exit 0, zero failures
lit control: system/SchemaLevelIsolationStrategy:strategy, a live top-level key	exit 1, refused

The coupling, measured before the fix was written

Three lines below currentKeys the same map is currentEntries, the published
authorable-surface baseline. The dispatch asked for a measurement rather than an argument, so:

1. Does widening currentKeys in place move authorable-surface/**? Measured, not reasoned:
   the one-level loop was replaced with a recursive walk, gen:schema was run, and the diff read
   +14,376 lines across all 14 shards (ai 320, api 6099, automation 496, data 1393, identity 83, integration 170, kernel 1997, marketplace 86, qa 93, security 90, shared 6, studio 187, system 1648, ui 1709). The script was then restored byte-identical
   (git hash-object back to b4f0ac58c00086a60528b88acdf1c45f13115387, git diff HEAD empty).
   So yes: widening in place publishes the whole nested key space as a ratcheted, author-facing
   contract.
2. Is a nested view consulted only by the checker sufficient? Yes, and that is what shipped.
   currentKeys and currentEntries are untouched; the nested state is resolved for the
   registered rows only and reaches nothing that emits. Deliberately no nested map is
   materialised — the hazard here is a nested key space lying around for a later author to pipe
   into currentEntries, so there is nothing to pipe.
3. Does the published surface have to move? No. git diff --exit-code -- packages/spec/authorable-surface/
   is clean after a full gen:schema on this branch, and check:generated reports all 15 generated
   artifacts up to date.

What the change does to each check that reads currentKeys

• (a0) lost by a declared rename — unchanged. Reads currentKeys, which is byte-for-byte what
  it was.
• (a) a key that vanished outright — unchanged, and deliberately so: it would otherwise start
  reporting every nested key as "vanished" against a baseline that has never recorded one.
• (b) live to retired must be registered — unchanged. It still demands a row only for a
  TOP-LEVEL transition, so no nested retirement that owes nothing today starts owing one. This is
  the behaviour change the card itself flagged under its shape 1, and it is not made here.
• (b2) an entry naming a key still LIVE — now reaches nested rows. A top-level row is judged on
  the same expression and the same message as before; a nested row is judged on the resolved state
  of its path.
• (b3), new — an entry naming a nested path this build does not emit. For a TOP-LEVEL key that
  state is the aged-out steady state (b2) exempts: the tombstone carried [RETIRED], aged two
  majors, and check (c) let its baseline line go, with evidence at every step. A nested key reaches
  none of that — it has no baseline line, no mark and no aging clock — so no gated route can produce
  a registered nested row whose path is absent, and the one origin left is that the row is wrong.
• A row whose whole DEF this build does not emit stays unjudged, exactly as today: that is the
  RETIRED_DEFS_BY_MAJOR steady state, adjudicated by the json-schema.manifest/ ratchet. Three
  of the 48 nested rows are in it (the change-management family, retired whole).

Population, which the card recorded as unmeasured

Censused over the 48 dotted rows the shipped table declares: 45 resolve to a tombstone, 3 name a
def this build does not emit, 0 resolve LIVE, 0 fail to resolve. The gate is green on the shipped
table, and the sixth test case below keeps that measured rather than assumed.

Acceptance — a probe, a lit control, and two dark controls

Pinned end to end in scripts/build-schemas-check-mode.test.ts, spawned against the real generator
in a sandbox that substitutes its own RETIRED_KEYS_BY_MAJOR:

case	expected	why it is here
PROBE — the card's fabricated nested row	refused, exit 1	the run the card measured at exit 0
LIT CONTROL — a live TOP-LEVEL key	refused, same message class	the guard that worked must not regress
a live NESTED key	refused by (b2)	the row the top-level-only map could never see
a live TOP-LEVEL key whose own NAME carries a dot	refused by (b2), not (b3)	routing asks the schema, not the spelling
DARK CONTROL — a real nested retirement	passes, exit 0	a checker that refused every dotted row would pass the probe too
DARK CONTROL — a fabricated row under a def this build does not emit	passes, exit 0	absence waived by the DEF's state, never by the path being real
the shipped table, seeded whole	passes, exit 0	the population, kept measured

Reverse verification. With the fix committed, packages/spec/scripts/build-schemas.ts was
restored to its pre-fix bytes (git restore --source=BASE, on-disk hash verified equal to the base
blob, nestedStates occurrences 3 to 0) and the block re-run: exactly 2 of 7 cases go red — the
PROBE and the live-NESTED case, both on expected +0 to be 1, i.e. the gate exiting 0. The five
controls stay green. Restored afterwards with git checkout HEAD --; git diff HEAD empty and the
on-disk blob back to 4948f991ee792944f90e91747054950bf7726fe7.

A discovery from the first run of the new pins, recorded because it moved the design: the
published baseline carries 4 dotted keys that are TOP-LEVEL property names containing a dot —
api/ODataResponse:@odata.context and two siblings, and a SCIM extension URN on
identity/SCIMUser. So "has a dot" is not the same question as "names a path": routing asks the
emitted schema first and reads a row as a path only when this build emits no top-level property of
that exact name. A fifth test case and an enumerated roster pin it, and the roster is also what a
widened published surface would blow up. A second discovery, from the resolver's own unit pins:
36 of the emitted refs are spelled # (a recursive schema pointing at its own document), which
the first cut read as external and would have reported as a typo'd path.

Evidence

pnpm --filter @objectstack/spec check:authorable-surface   exit 0
pnpm --filter @objectstack/spec check:generated            exit 0   all 15 generated artifacts up to date
pnpm --filter @objectstack/spec check:api-surface          exit 0   public API surface + factory signatures unchanged
pnpm --filter @objectstack/spec check:docs                 exit 0   224 generated files in sync
pnpm --filter @objectstack/spec typecheck                  exit 0   tsc + check:scripts-typecheck + check:test-typecheck
pnpm --filter @objectstack/spec test                       exit 0   485 files, 13835 tests
pnpm --filter @objectstack/spec test:repo                  exit 0   31 files, 536 tests
node scripts/pm/check-widening-tells.mjs --declaration yes --diff BRANCH.diff   exit 0
git diff --exit-code -- packages/spec/authorable-surface/  exit 0   published surface byte-identical

ESLint, narrowed and declared: pnpm exec eslint --no-inline-config --format json over the 4 files
this branch touches — 4 files linted, 0 errors, 0 warnings, file count read from the JSON
report. The universe eslint itself configures is **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} minus
NEVER_LINTED, read from eslint.config.mjs; and the narrowing is sound because that config
never enables type-aware linting for any file (no parserOptions.project, no typed
@typescript-eslint rules — the config says so in its own measured note), so this diff cannot move
the verdict on a file it does not touch. The repo-wide sweep is CI's.

Gate families, derived from the real change set rather than from the dispatch list
(node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack): 59 derived, 28 run here
with recorded exit codes, 1 NOT MEASURED (check:type-check-debt exits 3 — it refuses without a
whole-repo build closure, which is CI's), 1 not measured by a runner cap
(check:pm-dispatch-gates, killed at 420s by this seat's own timeout), 30 declared to CI —
cross-cutting families this 4-file spec-scripts diff cannot move.

File surface

• packages/spec/scripts/build-schemas.ts — the routing, (b2)'s nested limb, (b3), and isRetired
  delegating to one definition of the tombstone predicate.
• packages/spec/scripts/lib/nested-authorable-keys.ts — new. The resolution rules, and the
  authority on what they cannot see.
• packages/spec/scripts/nested-authorable-keys.test.ts — new. 17 unit pins on the resolver.
• packages/spec/scripts/build-schemas-check-mode.test.ts — the 7 acceptance cases above.

Untouched, as declared at claim time: packages/spec/authorable-surface/** (byte-identical),
packages/spec/scripts/lib/renamed-defs.ts, and the RETIRED_KEYS_BY_MAJOR registry — the two
ablations that wrote to the tree were restored byte-identical and proved so.

No changeset, skip-changeset. Measured rather than assumed: @objectstack/spec ships
files[] = dist, json-schema, liveness, prompts, llms.txt, README.md, src/**/*.zod.ts,
CHANGELOG.md, api-surface, spec-changes.json — scripts/ is not in it, and neither bin nor
exports reaches it. Grepping the built published paths for every symbol this diff adds
(nestedAuthorableKeyState, isNestedAuthorableKey, isRetiredJsonSchemaNode,
unresolvableNested, nested-authorable-keys) returns 0 files each, against positive controls
that return 8 (SchemaLevelIsolationStrategySchema) and 25 (RETIRED_KEYS_BY_MAJOR).

On the Clause-②: yes declaration

Declared yes conservatively at claim time, because the honest answer depended on the measurement
above. The delivered diff leaves the published authorable surface byte-identical and only gives
a checker a discrimination it lacked over a class of inputs; nothing an author may write changes,
and nothing published moves. That is the evidence, stated plainly — the contract review decides the
declaration, and this PR does not lower it.

Acceptance notes

• The RETIRED_KEYS_BY_MAJOR docblock now under-describes its own gate by one state. Its
  "Lifecycle" paragraph says "The one state the gate rejects is an entry naming a key that is still
  LIVE", and after this change a nested row has a second rejected state. The registry was declared
  read-only for this card, so it is not edited here: a one-paragraph follow-up, noted rather than
  filed.
• check:cross-package-test-inputs reds in a worktree that has a built packages/spec/dist/.
  Measured here with a control: this branch reds it (naming packages/cli/test/init-created-files-summary.e2e.test.ts
  walking packages/spec/dist/, a radius no declared glob reaches), while the same gate on a
  checkout with no packages/spec/dist/ exits 0. Independent of this diff, which touches neither
  packages/cli/** nor any declaration the gate reads. Two readings and both are worth a card: a
  gate whose verdict depends on local build state, or a true finding CI cannot see because it runs
  the gate without that build. Reported for filing rather than filed.
• This branch is based on e81c4e5f30 and main has moved since; the merge and CI convergence are
  the seat's, per the dispatch contract.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• 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 — 0 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 21b7c12b4f779b86409db2a7bb9235fe80ef8a54 → packageMentionDocs.

[os-bill]

Contract review

Served-tier: 88/88 CONTRACT_REVIEW_TIER
Head-sha: 37330e85c91f488db1e0cb4d80ab2ea5a3476689

Isolated at-tier review. Fed: card #17969 (body and comments) and PR #18618 (body, diff, file list, check runs). Withheld by design: the dispatch order and the dispatching seat's conclusions; no seat comment was treated as a finding of fact. Every reading below was taken on a detached worktree at the head sha above (base 21b7c12b4f, merge-base e81c4e5f30), with the fix ablated where the reading needed it. Stamp control: 88/88 harness-stamped assistant turns of this reviewer's own transcript read at CONTRACT_REVIEW_TIER, 1 distinct value, 0 disagreeing (a zero-hit control over the same file would have been 88 misses, so the count is a reading).

① Derived judgments

1. Published surface: nothing moves — RIGHT, established rather than read off the body. @objectstack/spec files[] = dist, json-schema, liveness, prompts, llms.txt, README.md, src/**/*.zod.ts, CHANGELOG.md, api-surface, spec-changes.json. All 4 touched paths are under packages/spec/scripts/, outside every files[] entry and outside tsup's src/ entries, so dist and api-surface cannot move. The one published artifact this diff's own generator writes is json-schema/ (gitignored, emitted by gen:schema, i.e. by the modified script). Measured: gen:schema at head, then again with build-schemas.ts restored to the base blob b4f0ac58… — 1529 files each side, every file byte-identical except .build-input-hash-schema, a digest of the generation inputs that moves whenever the script's own bytes move (c9d6be5b… → 9335cc35…): a freshness stamp, not a contract. Tracked generated artifacts (authorable-surface/** 14 shards, json-schema.manifest/**, authorable-defaults/**, api-surface/**, spec-changes.json): git status --porcelain packages/spec empty after both regenerations. This is a gate gaining discrimination without moving a published accept set.
2. Check (b2) accept set narrows for one input class — RIGHT; this is the card's surviving claim, closed. A RETIRED_KEYS_BY_MAJOR row whose name half is dotted, is not an emitted top-level property of its def, and resolves to a writable leaf is now refused where it was ignored. Top-level rows are judged on the unchanged expression and message. Independent census of the shipped table against the emitted schemas at head: 192 rows; 48 routed as nested → 45 retired, 3 def-not-emitted, 0 live, 0 unresolvable; 144 top-level → 0 live, 16 in the not-emitted steady state. 0 registered dotted keys are emitted top-level properties, so the routing limb (currentKeys.has(k) before the spelling) is exercised by the pin only, not by the population — acceptable, the pin is real and enumerates the 4 dotted top-level baseline names.
3. New check (b3) — a nested row whose def is emitted but whose path is not: refused — RIGHT on this tree, with a boundary wider than its text admits (③ item 5). The reasoning holds: a nested key has no baseline line, no [RETIRED] mark and no aging clock, so no gated route produces that state today. No row this tree carries is refused by it.
4. Checks (a0)/(a)/(b)/(c), the defaults ratchet and the manifest gate — unchanged — RIGHT. currentKeys and currentEntries are byte-identical; isRetired becomes an alias of isRetiredJsonSchemaNode, whose body is the moved text. Evidence: the sandbox case seeding the shipped table whole exits 0; real-tree check:authorable-surface exits 0; the five control cases stay green with the fix ablated.
5. The pins fail when the fix is removed — verified. With build-schemas.ts restored to b4f0ac58… (nestedStates occurrences 3 → 0) exactly 2 of 7 sandbox cases go red — PROBE and live-NESTED, both expected +0 to be 1, the gate exiting 0 — and the 5 controls pass; head restored to 4948f991… and git status clean. The resolver unit pins pass 18/18 (the body says 17; the file carries 18 — prose only).
6. Departure from the triage implementer note — argued, not silent — RIGHT. Triage asked that the checked set include nested keys rather than adding an assertion on a set that cannot see them. The diff does not recurse currentKeys; it resolves each registered nested row against the full emitted schema graph — a set that does see nested keys — and the body argues the departure with the measurement the coupling question demanded (+14,376 lines on authorable-surface/** if currentKeys were recursed; not re-measured here and not needed: the emitted baseline carries 0 nested paths). This is the card's own shape 2.
7. Resolver probes beyond the PR's pins — no false red found on any shape this tree emits. Nullable optional nested object (anyOf of object and null) → retired; allOf-only leaf → retired; $ref census of the emitted tree: 1012 #/$defs/…, 36 bare #, 0 external, so the external-ref → unresolvable limb cannot fire here.

② Semver level

• Level: none. Nothing published moves (① item 1); the change is a dev-time gate under packages/spec/scripts/. skip-changeset is the correct declaration for this diff (tests/tooling-only PRs take the label, never an empty changeset).
• Clause-②: yes is overturned to no. Declared conservatively at claim time; measured here as not the truth: the diff widens no published accept set and adds no public export — it gives a gate discrimination over a class of registry rows. Under AGENTS.md a yes owes at least a minor changeset, so the body's yes and the skip-changeset label are consistent only under this ruling; a declaration overturned by review is not a seat fault. Whether the body line is rewritten to no at adoption is the adopting seat's call: check-widening-tells never blocks yes, and under no it reports all 4 files NOT MEASURED (no declared surface covers packages/spec/scripts/), exit 0 either way.

③ Boundary flags

1. PR flag — RETIRED_KEYS_BY_MAJOR docblock "Lifecycle" under-describes the gate by one state. Confirmed stale after this diff. Add to it: (b3)'s refusal text offers "delete the entry" as a remedy while that docblock says "Entries are permanent" — reconcilable (a row that never named a real key was never an entry the lifecycle protects) but the docblock should say so. One-paragraph follow-up; whether a card already exists: unverified (this seat cannot search). Adopting seat's.
2. PR flag — check:cross-package-test-inputs reds with a built packages/spec/dist/. Reproduced: exit 0 with no dist/, exit 1 with a one-file stub dist/, naming packages/cli/test/init-created-files-summary.e2e.test.ts descending packages/spec/dist/ with no declared glob reaching inside. Independent of this diff (touches neither packages/cli/** nor any declaration the gate reads). Worth the card the report asks for; existence unverified.
3. PR flag — a row whose DEF this build does not emit stays unjudged. Agreed: pre-existing and by design (the RETIRED_DEFS_BY_MAJOR steady state, adjudicated by the manifest ratchet). Not this PR's.
4. PR note — branch based on e81c4e5f30, main since moved. The API reads the PR mergeable against 21b7c12b4f; landing convergence is the adopting seat's per the dispatch contract.
5. NEW (this review) — (b3) can refuse a truthful row once an ANCESTOR of a registered nested key leaves the schema. Probed against the resolver: a registered Def:performance.schemaCacheTTL reads unresolvable when performance is later tombstoned in place ({ "not": {} } carries no properties), when it is removed from a strictObject via the guidance route, or when the intermediate is a $ref to a tombstoned $def. def-not-emitted waives absence at the def level; the same waiver has no ancestor level. Unreached on this tree (0 of 48 rows; no registered row has a registered ancestor), the refusal is loud and lands on the retiring PR itself, and the text's "teach this check the shape, do not delete a row that is telling the truth" clause applies — but the two shapes the text names are not this one, and the printed remedy ("fix the spelling … or delete the entry") would be wrong for it. Not a FAIL: no legitimate row on this tree is refused, and the failure direction is the safe one the module declares. It is the first shape the next nested-object retirement will meet; follow-up, unverified whether carded.
6. NEW — tuples. 24 emitted schemas carry prefixItems; the resolver traverses items but not prefixItems, so a nested row under a tuple member would read unresolvable. No such row exists and the registry has no spelling for a tuple position; a limit of sight, recorded so it is not rediscovered.
7. CI at post time (head 37330e85): 29 check runs success, none in progress, 0 failed (read 2026-09-17T09:32Z). Locally on the head: check:authorable-surface exit 0, check:scripts-typecheck exit 0, eslint on the 4 touched files exit 0, resolver unit pins 18/18, sandbox cases 7/7. Green-at-landing is the adopting seat's pre-landing check, not part of this verdict.
8. Governed surfaces: none of the 4 paths is governed.

Implemented-by: claude/issue-17969-nested-retirement-verifiable
Reviewed-by: session_01JbZnqu8bt6YqfJsr9vaFb3

VERDICT: PASS

---

Generated by Claude Code

[os-bill]

Clause-② adopted — PASS,双载体同笔剥;⚠️ 申报被复核推翻

⏱️ 本条读数取自同一动作:2026-09-17T09:35Z。

复核记录:PR 线程评论 5712143155。
所判 head:37330e85c91f488db1e0cb4d80ab2ea5a3476689 —— 采纳时复读,未动(mergeable_state: clean),所以判的就是会合的那个 head。

逐字采纳。 派发席对隔离复核记录只能整体采纳或整体作废,⛔ 永不改写润色;本席两者都没做。下面只是对它提出的旗的处置,⛔ 不是对它判断的补充。

needs:contract-review 已在同一笔里从 PR #18618 与卡 #17969 两侧剥除。

独立性对

Implemented-by: claude/issue-17969-nested-retirement-verifiable(产 diff 的分支,mode:subagent)· Reviewed-by: session_01JbZnqu8bt6YqfJsr9vaFb3(渲染/采纳的席位;隔离复核子代理无自有 session,按 contract-review.md 记采纳席)。两者不同身份 ⇒ ⛔ 无 SELF-REVIEW。

档位证据

复核员解析自身 transcript 每条 type:"assistant" 的 harness 盖章 message.model,对 dispatch-gates.mjs 实时 import 的 CONTRACT_REVIEW_TIER 逐条比:88/88 达档,1 个不同取值,0 条不一致。⛔ 未用 get_session(mode:subagent 里它量的是派发会话)。
本席独立复核了泄漏面:把实时 import 到的常量值拿去在记录正文里搜 —— False,⛔ 型号串未入正文。--pair 18618 亦在 C6/C7 上确认该记录在此 head 且 Served-tier: 立在 88/88 的盖章对照上。

⚠️ 申报 Clause-②: yes 被推翻为 no —— 这是设计内的,不是过失

那个 yes 是本席在认领时写的,理由写在认领评论里:它依赖的测量(就地放宽 currentKeys 会不会动已发布面)本席当时答不了,按 contract-review.md 的「claim 拿不准 ⇒ 按 yes 挂标走席内契约复核」保守挂。复核把那个测量做了,判没有任何已发布面移动,于是申报归 no。

contract-review.md 原文:「Clause-②: yes | no 按设计临时:只定是否必过席内契约复核的保守方向,⛔ 非终审」,以及「真闸门在 PR 或报告时点的席内复核;声明被复核推翻 ⛔ 不作席位过失」。⇒ 记录成立,⛔ 无人需要为此改正。

PR 正文那行 Clause-②: yes 保持原样,⛔ 不改写。 三个理由,第三个是测出来的:

1. 记录本身就是闸门与权威,推翻写在记录与本评论里,改正文反而抹掉「保守路由曾发生过」这段历史。
2. 本仓实测:REST PATCH PR 正文会追加第二个页脚。
3. ⭐ 有没有门禁读这一行? 读 Clause-② 的门禁是 check-adr-0087-registration.mjs 与 check-changeset-no-major.mjs(后者 import { readClause2Line }),而它们读的是 changeset 里的那一行 —— 本 PR 带 skip-changeset、没有 changeset ⇒ 没有任何门禁读到它,CI 也确实全绿(32 success / 11 skipped / 0 red)。⛔ 所以留着它不构成闸门风险,这是查过的、不是推断。

③ 边界旗的处置

旗	处置
1 · 登记表 docblock 的 Lifecycle 段少描述了一个状态,且 (b3) 的「删条目」处方与「Entries are permanent」相抵	待立卡,见下
2 · check:cross-package-test-inputs 依本地有无 packages/spec/dist 给相反判决(复核员独立复现过)	⛔ 不立孪生 —— 已有 #18353 / #18440,本席逐张读过标题确认
3 · def 未 emit 的行不判	既有语义、按设计,无动作
4 · 新 — 祖先被墓碑化/走 guidance 路移除/经 $ref 指向已墓碑 $def 时,(b3) 可能拒绝一条真实的行,而印出的处方对这一形状是错的	待立卡,见下
5 · 新 — resolver 走 items 但不走 prefixItems	并入 4 的卡
6 · CI	所有 required context 均 success,0 失败;未碰受管面

⚠️ 旗 4 与 5 本席只部分复现,如实记下:nested-authorable-keys.ts 里 prefixItems 计数读 0(与复核员一致);但本席找「有多少 emitted schema 带 tuple」时搜错了树(搜了 packages/spec/src,而 emitted schema 在生成物里),所以那一半是 NOT MEASURED,⛔ 不是反证。(b3) 的处方原文与登记表 docblock 的两句,本席的 grep 窗口也没取到。⇒ 立卡时会写明哪一部分是复核记录的、哪一部分是本席自己测到的,⛔ 不把转述写成第一手。

随后按 landing-operations.md 走落地前检 → 转 ready → 挂 auto-merge。

---

Generated by Claude Code