docs(spec): re-anchor the dead tracker citations in packages/spec/src's test surface to the commits that decided them

[objectstack-fleet]

Part of #20234

Clause-②: no

What this stage does

The citation gate's census defers packages/**/*.test.ts, so the dead tracker numbers in packages/spec/src's test files were never in its count. This stage measured that surface and re-anchored every dead site in its comment and docblock text, in ruling C+D form C (triage 5856637615): each line now cites the commit on main that decided what it describes, and says the decision in words. Wherever an earlier stage of this card, or a sibling lane, already landed an anchor for the same number, this stage reuses it.

It also takes the two source comments that tests read literally, and moves each reader onto the new text:

• src/data/api-derivation.ts:163: the [#6259] marker on DATA_ACTION_TO_API_OPERATION becomes [commit 6968885ef] and the sentence says what that commit did (it removed the producer-less batch: 'bulk' row and stopped the description calling batch a runtime action). Its reader, src/data/api-derivation.test.ts:236, splits on the new marker.
• src/identity/identity.zod.ts:230: (#8715, becomes (commit 2c86fe3ea,; the maintainer-ruled DELETE and its date stay. Its reader, src/identity/api-key-retirement.test.ts:118, asserts the new opening phrase.
• The runtime test that stage 6's record also named (packages/runtime/src/api-exposure.test.ts:152) reads packages/runtime/src/api-exposure.ts, not the spec file, so it is not a reader of this text and is untouched.

Comment and docblock text only, plus those two readers. No test title, schema, type, export or behaviour change.

Census (base 7d0781482d, head 0e92e882f4)

Instrument: the gate's own extractCitations (comment-prose projection) and namesThisRepository over all 596 packages/spec/src/**/*.test.ts files (no .test.tsx, .spec.ts or __tests__/ files exist there), with string literals read through the shared scanSource literal projection. Every distinct in-repo number was probed with REST issues/N, redirects not followed, with lit controls #16862 #16847 #17698 and dead controls #16714 #16715 #16697 at the start, every 100 numbers and the end.

	base	head
distinct in-repo numbers probed	1,397: 1,310 answer 200, 87 answer 404, 0 other	1,377: 1,309 answer 200, 68 answer 404, 0 other
controls	45/45 lit = 200, 45/45 dead = 404	45/45 and 45/45
dead sites in comments and docblocks	87 sites, 85 lines, 34 files, 40 numbers	0
dead sites in string literals	150 sites, 147 lines, 56 files, 69 numbers	147 sites, 144 lines, 55 files, 68 numbers

87 is under the stage's 120-site bound, so this stage takes all of it. By area: package root 36, shared/ 10, system/ 9, data/ 8, api/ 5, automation/ 5, integration/ 5, conversions/ 4, security/ 3, identity/ 2. The excluded files (migrations/**; automation/flow-slot-refusal-codes.test.ts; automation/flow-write-node-stored-metadata-target.test.ts) carry 0 dead sites, so the exclusions removed nothing.

The three literal sites that left are exactly the two readers' literals. Every test title is untouched. No in-repo comment citation was added at head. The one live number that left the in-repo count is #6110, which now carries its objectui# qualifier (below). A raw #N scan of the comment projection agrees with the gate's extractor: its only extra hits are three objectui #11166 sites that are objectui's.

The gate's own census (check-issue-citations.mjs --census --json, board enumerated, 196 pages, frontier #21684) reads 0 findings in packages/spec/src at head. The gate's extractor read 2 at base (api-derivation.ts:163 #6259, identity.zod.ts:230 #8715).

Dead numbers left in string literals (not touched; #20749's class (e))

68 numbers at 147 sites, all test titles. data/ 40, api/ 33, ui/ 21, kernel/ 18, contracts/ 10, shared/ 6, system/ 6, integration/ 5, (root) 3, identity/ 3, conversions/ 2, automation/ 1. One of them is not a tracker number at all: #0000 in shared/retired-key*.test.ts is a fixture placeholder.

Anchors

number	sites	anchor	where
#6037	4	18189983d	type-alias-convention.pin.test.ts
#6072	1	7f713b662 (the squash commit of PR #6072, ADR-0122 phase 1)	type-alias-convention.pin.test.ts
#6083	5	53068c130 (ADR-0122 phase 2)	connector-author-shape, environment-artifact, type-alias-convention
#6085	1	026101660 (added this very pin file)	shared/expression-dialect-docs.pin.test.ts
#6239	1	f549a0d4a (the sweep commit, cited on the sweep's header line)	type-alias-convention.pin.test.ts
#6259	1	6968885ef	data/api-derivation.test.ts
#6345	5	e2798fab7 (its diff wrote all five lines)	conversions.test.ts, stored.test.ts, driver/turso.test.ts
#6362	3	b5404f496	automation/webhook.test.ts, integration/connector.test.ts
#6527	1	259459d8b (the squash commit of PR #6527)	type-alias-convention.pin.test.ts
#6604	2	d127ff002	type-alias-convention.pin.test.ts
#6605	3	c6b05c76a (wrote the prose-count check)	type-alias-convention.pin.test.ts
#8714	3	42b05af89	security/explain.test.ts
#8715	2	2c86fe3ea	identity/api-key-retirement.test.ts
#9040	2	24206416a	data/driver/driver-credential-refusal.test.ts
#9041	1	d491625c1	data/driver/driver-credential-refusal.test.ts
#9741	2	2a29caa53	api/protocol.test.ts
#10194	2	2306a765c	analytics-strictness-batchd, metadata-url-spelling
#10485	9	35ad101bc	sync-retirement, metadata-collection, metadata-url-spelling, stack-top-level-strict, type-alias-convention
#10926	2	d173125fb	system/i18n-resolver.test.ts, system/translation.test.ts
#11006	4	cccbe51bf	api/protocol.test.ts, type-alias-convention.pin.test.ts
#11166	1	735f5c709 (the runtime and service-datasource lanes' anchor)	shared/external-errors.test.ts
#11333	1	e58ea8b38 (stage 6's anchor for the same phrase)	system/environment-artifact.test.ts
#12194	1	311433f6b	type-alias-convention.pin.test.ts
#12493	1	aa5994e17	system/operation-message.test.ts
#12961	2	901355c3b	system/i18n-resolver.test.ts
#13135	3	9e0ba21a1	type-alias-convention.pin.test.ts
#13156	1	fd289be45 (the sibling files' spelling, "commit fd289be's strip")	compose-stacks-key-loss.test.ts
#13218	2	c45d8e6b4	system/i18n-resolver.test.ts
#14162	1	c5a9a437d (the squash commit of PR #14240, whose body names #14162 as the card it lands; it is the load path that judges each packages[] entry with ArtifactPackageEntrySchema)	stack-artifact-packages.test.ts
#14419	1	c5a7448d5 (its message names #14419 as the card it lands)	automation/control-flow.test.ts
#14662	1	35dffeace	compose-stacks-action-key-collision.test.ts
#14676	4	13c48c2a5	integration/connector.test.ts, type-alias-convention.pin.test.ts
#14686	3	279431e7a	compose-stacks-action-echo.test.ts
#14691	2	b3a63d32c	rest-api-config-dead-keys-retirement, type-alias-convention
#14722	2	23c72be3c (stage 1's "refuted in commit 23c72be")	shared/union-author-message-pins.test.ts
#16659	3	ecdfc9411	schedule-organization.test.ts, type-alias-convention.pin.test.ts
#16864	1	29dd1a6dd (it wrote this very pin line)	conversions/conversions.test.ts
#17124	1	86c505286 (the service-analytics and core lanes' anchor)	data/analytics-date-range-two-bound-window.test.ts

Every anchor is unique at nine hex digits, single-parent, and an ancestor of main. That was read from a full, not shallow, treeless clone of main at the base. For 40 of the 49 (number, anchor, file) pairs, the anchor's own diff wrote a line naming the number into that file. Where it did not, the anchor's message or its PR body names the number.

Two census-dead sites are not this repository's numbers. They are respelled so the gate reads their qualifier, following stage 5's precedent, and are not re-anchored. Both numbers answer 200 on objectui.

• api/export-job-family-retirement.test.ts:24-25: objectui / PR #10264 was split across a line break, so the census read dogfood: simulate a brand-new developer's first-run journey — README → create an app → skills-driven AI build → validate & test #10264 as bare. The line break now falls before objectui PR #10264.
• shared/editability-boundary.test.ts:391-392: (objectui#6010 / #6110 / #6111) becomes (objectui#6010 / objectui#6110 / objectui#6111), the spelling ui/view.zod.ts and data/field.zod.ts already use for the same pair.

Proof that only text moved

• Token streams. A TypeScript 6.0.3 parser leaf-token comparison (JSDoc nodes skipped) and a comment-blanked comparison (the shared maskComments, whitespace collapsed) run over all 36 files, base vs head. 34 files are IDENTICAL on both instruments. The other two differ only in the declared reader literals: api-derivation.test.ts in 2 string tokens ('[#6259]' and its assertion message), and api-key-retirement.test.ts in 1 ('are NOT declared here (#8715'). VERDICT text-only (36 files), exit 0.
• Controls, 8 of 8 as expected. These ran on scratch copies. An identifier change, a test-title string, a template literal and a regex literal each read DIFFERS (exit 1). A line comment, a JSDoc edit and a block comment each read IDENTICAL (exit 0). An undeclared literal changed beside the declared ones reads DIFFERS (exit 1).
• Lines. 206 changed lines (103 out, 103 in; every file keeps its line count). 200 are comment lines, and 6 are the three reader lines out and in.
• Test counts unchanged. The 34 touched test files ran at base in a separate base worktree, and at head: 346 suites and 1,689 tests passed on both sides. The (fullName, status) list matched for every file.

Reverse verification of the two readers (each leg through scripts/ablation-replace.mjs, restore proven against HEAD)

leg	mutation	result
A1	api-derivation.ts: [commit 6968885ef] back to [#6259]	red: "the [commit 6968885ef] removal note vanished from the TSDoc", 1 failed, 31 passed
A2	api-derivation.test.ts: the reader back to split('[#6259]')	red, same assertion
B1	identity.zod.ts: back to are NOT declared here (#8715	red: toContain('are NOT declared here (commit 2c86fe3ea'), 1 failed, 2 passed
B2	api-key-retirement.test.ts: the reader back to (#8715	red, same assertion

Each leg's mutation landed (anchor 1 → 0, blob changed), and each restore read blob == HEAD with an empty git diff HEAD. Both files are green at HEAD (32/32, 3/3), and the tree is clean afterwards.

Generated artifacts and the changeset

• After pnpm --filter @objectstack/spec build, the rewritten DATA_ACTION_TO_API_OPERATION docblock is in dist/data/index.d.ts and index.d.mts. The positive control, the same docblock's unchanged first sentence, is in the same two files, and the old [#6259] marker is in 0 dist files.
• The identity.zod.ts block comment is in no dist file, and neither is the control sentence from the same block. But files[] ships src/**/*.zod.ts verbatim, so the new text publishes.
• So this PR carries a @objectstack/spec patch changeset (.changeset/spec-test-surface-dead-citation-anchors.md, with the Clause-②: no line), and skip-changeset does not apply. Test files do not ship.
• check:generated: all 15 generated artifacts are up to date, with nothing regenerated. check:docs is green, so no reference page renders either comment.

Verification

• pnpm --filter @objectstack/spec build, then check:generated: exit 0.
• pnpm --filter @objectstack/spec exec vitest run --project local --maxWorkers=2: 610 files passed, 18,113 tests passed, 1 todo.
• The two touched repo-project files (export-job-family-retirement, rest-api-config-dead-keys-retirement) are green in the 34-file run.
• pnpm --filter @objectstack/spec typecheck: exit 0 (check:test-typecheck OK: 52 files, 246 errors, 135 pinned signatures held).
• dispatch-gates --commands at 0e92e882f4 derives 85 families. --ran reports 85 accounted, 84 run (all exit 0), 1 NOT MEASURED and 0 unrun.
• The NOT MEASURED one is check:dual-build-cjs-loads, which exits 3 (PREREQUISITE NOT MET) without a full monorepo build. It is a declared narrowing: the diff is comment-only in packages/spec, and spec's 19 require entries from the gate's own --list all load at head (a missing-entry control throws). CI runs the full gate.
• Lint, a proven narrowing: eslint --no-inline-config --format json over the 36 touched files gives 36 files, 0 errors and 0 warnings. isPathIgnored is false for all 36, read from eslint's own config. eslint.config.mjs enables no type-aware linting (no parserOptions.project), so a comment edit cannot move any untouched file's verdict. The repo-wide pnpm lint is CI's.
• These readings are at head 0e92e882f4.

origin/main was re-fetched before opening this PR (83e2feeb46, 5 commits past the base). None of those commits touches packages/spec or any file here, and git merge-tree onto it exits 0, so no merge was taken.

Acceptance notes

• Rung choices, one line each. retiredFromLoadPath: true does not keep a conversion off any load path — three runtime seams replay every retired entry with includeRetired: true, and apply.ts says only migrate meta does #16864 cites 29dd1a6dd, the commit that wrote this exact pin line; stage 8 took ADR-0087's 2026-09-13 addendum for a different sentence about the three data-at-rest seams. [spec] View-Management 五方法(listViews/getView/createView/updateView/deleteView)是零实现零路由的声明面 —— 已导致 #5948 把它的响应 schema 误当成线上路由的契约 #6239's row in the -7 receipt table now reads views, and the sweep commit f549a0d4a is cited on the sweep's header line beside the live #6486.
• What remains of this card's surface. In packages/spec/src there are no dead comment or docblock citations left: the gate census reads 0 and the test-surface census reads 0. What remains are the 68 dead numbers in 147 test-title literals listed above. This stage's dispatch assigns those to runtime strings in the domain:spec packages carry tracker numbers (spec 175 and lint 83 messages): this lane's share of the #20513 A/A burn-down #20749's class (e), so this PR says Part of and leaves the card open for that call.
• Outside the card's census surface, as earlier stages recorded. docs/audits/2026-07-unknown-key-strictness-ledger.md:676 (element:record_picker 的 sort / limit 扁平简写:renderer 兑现、schema 未声明(#5775 实施中新测出,A 表之外的第 7 处) #6276) has no carrier.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 2 changed file(s) yielded no anchor (packages/spec/src/data/api-derivation.ts, packages/spec/src/identity/identity.zod.ts), 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

• 2 changed file(s) yielded no anchor (packages/spec/src/data/api-derivation.ts, packages/spec/src/identity/identity.zod.ts) — 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 — 138 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 83e2feeb46be3c22b7139b01114612e93afcf412 → packageMentionDocs.

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 37186683796 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Console Pin Gate — 失败步骤: Build the Console SPA at the pinned objectui SHA

  ✗ Built console still carries the PUBLISHED @objectstack/spec.
  

• Test Core (6/6) — 失败步骤: Run this shard's tests

  @objectstack/objectql:test:  FAIL   local  src/engine-insert-static-readonly-strip.test.ts > #14147 — the exemptions, each one load-bearing > [#21682] a write middleware’s fill is not caller-supplied 
    ↳ 失败原因: @objectstack/objectql:test: AssertionError: the platform’s value reaches the driver: expected undefined to be 'stamp' // Object.is equality
  

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

⚠️ 断言这一侧有一类例外，判据是断言在测什么，不是它是不是 AssertionError。 断言的对象是产品行为（一个值、一个形状、一次拒收）⇒ 照上面读：真实的行为改变，去查，⛔ 不要重排掉；
断言的对象是这次实验自身的有效性前提（跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件）⇒ 它跟超时是同一类，同样对负载敏感，重排一次是合法的判别手段。
识别是机械的：断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为（真回归）；
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提：它守护的那条不变式当时是绿的，同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量，仍然是时间测量。（⛔ 这只改「怎么读一次红」，不改「哪些测试可以重排」——后者由别处管。）

跨 PR 相同签名（24h，按失败测试文件聚合）：

• src/engine-insert-static-readonly-strip.test.ts — 24h 内已弹出 2 个 PR（docs(spec): re-anchor the dead tracker citations in packages/spec/src's test surface to the commits that decided them #21700、fix(objectql): droppedFields on a create names only keys the caller sent, never a middleware fill (#21682) #21701），但它们同属 1 条投机栈 ⇒ 1 次独立命中。汇总 issue：Queue-flake anchor: src/engine-insert-static-readonly-strip.test.ts #21705（新建）
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 3 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)

[objectstack-fleet]

Queue build 37186683796 triaged by the owning seat (domain:spec seat 1, session_01T9u38rswFp5Rw8DswRUReJ, 2026-10-04T08:14Z): neither red is this PR's.

• Test Core (6/6): the failing case, engine-insert-static-readonly-strip.test.ts › "[[finding] On a walled posture a create that names no organization_id answers droppedFields [organization_id: readonly], a field the caller never sent (the insert analogue of #8093) #21682] a write middleware's fill is not caller-supplied", is the test PR fix(objectql): droppedFields on a create names only keys the caller sent, never a middleware fill (#21682) #21701 adds in @objectstack/objectql. It rode the same speculative group, ahead of this PR. This PR's diff is comment text in 36 packages/spec/src files and two test readers' literals; it touches no objectql file and no behaviour.
• Console Pin Gate ("Built console still carries the PUBLISHED @objectstack/spec"): this PR moves none of that gate's inputs. It does not touch .objectui-sha, the console build scripts, packages/spec/package.json or packages/spec/tsup.config.ts.

GitHub rebuilt this PR's merge group on 16d241a6af without #21701 (gh-readonly-queue/main/pr-21700-16d241a6af…), and that build is running. No re-queue was made by hand. If the rebuilt group reds on either check, the seat takes it from there.

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 37187916146 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Console Pin Gate — 失败步骤: Build the Console SPA at the pinned objectui SHA

  ✗ Built console still carries the PUBLISHED @objectstack/spec.
  

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

⚠️ 断言这一侧有一类例外，判据是断言在测什么，不是它是不是 AssertionError。 断言的对象是产品行为（一个值、一个形状、一次拒收）⇒ 照上面读：真实的行为改变，去查，⛔ 不要重排掉；
断言的对象是这次实验自身的有效性前提（跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件）⇒ 它跟超时是同一类，同样对负载敏感，重排一次是合法的判别手段。
识别是机械的：断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为（真回归）；
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提：它守护的那条不变式当时是绿的，同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量，仍然是时间测量。（⛔ 这只改「怎么读一次红」，不改「哪些测试可以重排」——后者由别处管。）

跨 PR 相同签名（24h，按失败测试文件聚合）：

• ⚠️ 本次没有可用的聚合签名（日志里没有能解析出测试文件名的 FAIL 行）—— 这不是「没有同签名的其他 PR」，是这一轮没测到。跨 PR 聚合本次不可用，请手工比对其他 PR 的同类评论。
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• ⚠️ 本 PR 过去 24h 已在队列失败 1 次（不含本次）。 内容未变而反复失败 ⇒ 高度怀疑 flaky 测试或与同组 PR 的语义冲突，重排不解决。
• 过去 24h 队列共有 4 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)