docs(metadata-protocol): re-anchor the remaining dead tracker and comment-id citations in test comments (stage 2 of #20595)

[objectstack-fleet]

Part of #20595
Clause-②: no

What changed

Stage 2 of the domain:engine lane of the dead-citation sweep: the packages/metadata-protocol remainder that stage 1 (PR #21233, landed as a7d9768ec) left, per the claim (5940298570). Comment and docblock prose only. #20595 stays open for the next stages (objectql next).

The population is what stage 1's contract review (5939794396) escalated to this sub-stage:

• the 22 test-comment sites carrying 13 numbers that answer 404, which the census never reads (it defers test files);
• the dead comment-id citation comment 5299845282, on two lines;
• the dead convenience number PR #14767 beside its anchor 96326040f.

Each is rewritten in ruling C+D's form C (record 5749154545 on #19123): the commit in this repository's history that made the decision the sentence describes. 23 lines in 16 files (21 lines for the 22 numbered sites, 2 for the comment id). Anchors: 13 numbers and the comment id, all by commit sha; 0 by ADR or ruling record (none exists for any of them); 0 by words alone. Seven numbers reuse the commit another lane already chose for them, #14767 and the comment id keep stage 1's commit already on their line, and five were measured here.

Every file keeps its line count (+23 / -23). No code token moves (guard below). No citation number is added: the only numbers left on changed lines, #9612 and #13331, stood there before and answer as issues.

No changeset, and skip-changeset is the declaration: 22 of the 23 lines are in test files, which the tsup entry graph never reaches, and the one protocol.ts line is a // comment inside a method body that the build drops. Measured, not assumed (see Changeset).

Population, before and after

H1, re-enumerated on origin/main (a7d9768ec). The instrument is the gate's own code, read-only. extractCitations from scripts/check-issue-citations.mjs runs over every tracked file in the package (239), in both projections (whole file and comment prose), keeping the citations namesThisRepository assigns to this board. classifyCitation judges each one against a board read by the gate's own enumerateBoard: 191 pages, frontier #21241, 19,062 records, read 20:54:38Z to 20:58:19Z on 2026-10-01. Then one REST read per number: all 13 answer 404, and the lit controls #5286 and #12624 answer 200.

reading	tree	citations	dead	src comment	test comment	test string	changelog
before	base a7d9768ec	6,092	141	0	22	63	56
after	head 16b5bf6c1	6,070	119	0	0	63	56

• The before reading matches stage 1's own after reading (141: 0 / 22 / 63 / 56).
• The drop of 22 citations is exactly the rewritten numbered sites. No live count moved: test comments resolve 1,586 and resolve-as-pull-request 111 at both.
• The count against the dispatch's 22 / 13: 22 sites, 13 numbers, on 21 lines. One line carries two numbers. The lines are in 14 test files; the review counted 15.
• Comment ids (10-digit, outside the citation grammar): 9 sites, 5 distinct ids at the base. Read one by one through the comments endpoint, 5299845282 answers 404 and the other four answer 200: 5302933802 (on [finding] diffMetaItem answers 200 with an empty diff when sys_metadata_history is unreadable — an outage is indistinguishable from "nothing changed" #8833), 5528370129 ([finding] QA observed /api/v1/meta/datasource serving a deleted datasource's entry cluster-wide, but MetadataManager's unregister DOES broadcast — the observed prolongation sits in an unidentified seam #13609), 5865708652 ([finding] GET /meta/:type/:name/diff serves PENDING draft content to a member with no authoring capability: its history versions include draft saves, and it is the one draft-serving door the #20338 gate leaves open #20378) and 5875579209 (GET /meta/:type/:name/diff with no from: after a draft is published, the default range compares the new version against the draft's own save and answers "no changes", never against the previous published version #20451). The control 5940298570 (on dead tracker citations in the domain:engine packages (645 sites, 160 numbers, 104 files): the ruling C+D stage for this lane (from #20556) #20595) answers 200. After: 7 sites, 0 dead.

Per-number table

Every sha below resolves to exactly one commit (git rev-parse --disambiguate). Each is an ancestor of the base: git merge-base --is-ancestor exits 0 for all 14, on a full clone (--is-shallow-repository is false). Each one's message or diff names the number it replaces. ADR: git grep over docs/adr and scripts/adr-anchors names none of the 13 numbers or the comment id, so the ADR rung is empty for all of them.

number	sites	anchor	kind	named in	provenance	what it decided
#6287	1	84c86fb45	commit	message (squash suffix) + diff	reused: runtime and spec lanes	preview / trial discovery folds declared, the fold table exhaustive over EnvironmentType
#10058	1	6f5a44976	commit	subject (the squash of that PR)	measured here	judge a package write against its own closure
#10064	2	def0d3e63	commit	message + diff	reused: lint lane	key publish-gate finding paths by name, not the private snapshot index
#10420	1	05bc692e0	commit	message + diff	measured here	run SysMetadataRepository through the shared repository contract suite (it adds this file)
#10978	2	4c9780c7a	commit	message + diff	reused: runtime lane	ObjectQL doubles enforce limit after the filter and by presence
#11017	1	d806081dd	commit	diff (it adds this file)	measured here	render the 422 findings clause per write face
#13214	1	cc837dbfe	commit	diff	reused: rest lane	require the resolved environment to belong to the caller at GET /ui/view/:object/:type
#13244	1	889ec5b42	commit	subject (squash)	reused: rest lane	measure identity resolution at GET /ui/view/:object/:type
#13258	1	3d10755f0	commit	subject (squash)	reused: rest lane	drive the tenancy axis of GET /ui/view/:object/:type (it adds the sibling harness)
#14389	1	10220a7bf	commit	diff	reused: rest lane	the 409 arm gated on the engine's envelope (name and code)
#14431	5	a98b61b3e	commit	subject (squash)	measured here	re-measure the deleted-datasource prolongation across replicas (it adds this file)
#14767	1	96326040f	commit	subject (squash)	stage 1's anchor, already on the line	the dead convenience number is dropped; the sha stays
#17621	4	7e74af3df	commit	message + diff	measured here	execute the read-probe PostgreSQL arm on a live server (it adds the live-postgres file)
comment 5299845282	2	75e66fc8e	commit	message	stage 1's anchor, already beside both lines	its message records the ruling: diff raw, then redact (Option B)

Sentences that credit a commit with a finding, a ruling or a record were checked against that commit's own message:

• a98b61b3e carries the finding all five #14431 sites describe: the bridge heals the registry, a read inside the residue window re-hydrates the deleted row, and the window is bounded only when no read lands in it.
• 7e74af3df records the no-coverage state: the PostgreSQL arm was pinned and run nowhere.
• 6f5a44976 records the package-closure ruling.
• 75e66fc8e carries the Option B ruling.
• 10220a7bf records the name-and-code gate.
• 4c9780c7a records the after-the-filter, by-presence bound.
• d806081dd records the per-face decision (silence keeps the full prose on the duplicate face) but not the ruling itself. So that site keeps the ruling's own date and now reads 「landed as」. This is stage 1's precedent for #9741 and 2a29caa53.

Wordings to check

Most rewrites swap the tag in place, as the landed stages do: (#N) becomes (commit SHA), [#N] becomes [commit SHA], and PR #N becomes commit SHA. These say more than the tag:

• protocol.invalid-metadata-422-face-inventory.test.ts:22: 「The maintainer ruling on [裁决] duplicatePackage 的 failed[] 是否应在 spec 声明结构化 issues 通道 —— 它今天在 spec 里没有任何响应 schema #11017 (2026-08-22, option D) resolved it by」 became 「The maintainer ruling of 2026-08-22 (option D, landed as commit d806081) resolved it by」.
• protocol.ui-view-hidden-columns.test.ts:46: 「([finding] GET /api/v1/ui/view/:object/:type resolves a UI view with no identity resolution and no anonymous-deny at the REST seam #13214 / PR test(rest): drive the tenancy axis of GET /ui/view/:object/:type — an anonymous caller can name another environment and receive its UI view #13258) drives the same defect」 became 「(commit 3d10755, for the card commit cc837db fixed) drives the same defect」. Line :47 says 「It belongs to that card」, and this wording keeps an antecedent for it.
• protocol.batch-row-http-status.test.ts:546: 「(mapDataError has no DUPLICATE_RECORD arm: the engine's insert conflict envelope reaches the wire through the generic passthrough, dropping the field key and the user-facing conflict sentence #14389 §5)」 became 「(commit 10220a7)」. The §5 named a section of the deleted card's body, so it goes with the number.
• get-meta-item-org-read-gate.test.ts:10: 「Commit 9632604 (PR fix(metadata-protocol): apply the allowOrgOverride read gate inside getMetaItems, so multi-type sweeps are scoped per type #14767) moved」 became 「Commit 9632604 moved」. Ruling C allows a PR number only as a convenience link, and a link that answers 404 is not one.
• protocol.ts:22793: 「maintainer ruling (comment 5299845282), Option B.」 became 「maintainer ruling (recorded in that commit's message), Option B.」. The line above opens with [commit 75e66fc8e].
• protocol.diff-credential-redaction.test.ts:19: 「(maintainer ruling, issue comment 5299845282 — Option B)」 became 「(maintainer ruling, recorded in commit 75e66fc's message — Option B)」.
• migrations/seed-tenancy-backfill.live-postgres.test.ts:55 and :256: 「the no-coverage state metadata-protocol's live-DB CI step supplies only OS_TEST_MYSQL_URL, so the new catalog presence probe's PostgreSQL arm is pinned as TEXT and has never been executed #17621 records」 became 「the no-coverage state commit 7e74af3 records」, and 「metadata-protocol's live-DB CI step supplies only OS_TEST_MYSQL_URL, so the new catalog presence probe's PostgreSQL arm is pinned as TEXT and has never been executed #17621 exists because it was」 became 「commit 7e74af3 exists because it was」.
• No line was reflowed, so some lines now run past their block's wrap. eslint.config.mjs declares no line-length rule, and a reflow would move neighbouring lines and every line citation into the file.

Sites left in this package

• Dead tracker numbers in comment prose (src, tests and tsup.config.ts): none. Dead comment ids: none.
• 63 test-string sites (describe / it titles and assertion arguments) are not edited. 56 carry census-dead numbers and 7 carry #17621. They are recorded on dead tracker citations in the domain:engine packages (645 sites, 160 numbers, 104 files): the ruling C+D stage for this lane (from #20556) #20595, and the claim excludes string literals.
• CHANGELOG.md, 56 sites, is release-owned and not edited.

Mechanical guard: no code token moves

The guard compares the base blob with the working tree for all 16 touched files, with TypeScript 6.0.3, on two readings:

• Reading 1: the parser's leaf nodes, from a forEachChild walk. Comments are trivia there, and JSDoc is never visited.
• Reading 2: the full token stream in parser context, from a getChildren walk, with JSDoc nodes skipped.

String, template and numeric literals are compared in full on both readings.

• Real run at head 16b5bf6c1: 104,684 base tokens, 0 files with a token change (exit 0).
• Controls, each through scripts/ablation-replace.mjs in wrap mode, under a shell trap that restores by absolute path from HEAD:
  • comment (bodies untouched to bodies UNTOUCHED, protocol.ts): 0 files changed, exit 0;
  • identifier (const issues to const issuesX, runtime-authoring-gate.dataset-writes.test.ts): DIFFER on both readings, exit 1;
  • string ('organization probe' to 'organization probeX', live-postgres test): DIFFER on both, exit 1;
  • numeric (WINDOWS_PROBED = 10 to 11, prolongation test): DIFFER on both, exit 1.
• Each control landed: anchor count went from 1 to 0 and the blob changed. Each restore equals its HEAD blob (766d14add061, 9c4bcfec727d, 3457d6e431ed, 9931944568bb). git diff HEAD is empty and the tree is clean afterwards.

Changeset: none, with skip-changeset (dist measured)

files[] is dist, README.md and CHANGELOG.md. The tsup entry is src/index.ts, and no test file is in its graph. For the one non-test line (H3), the dependency closure was built first (turbo run build --filter='@objectstack/metadata-protocol^...', 12 of 12 tasks). Then the package's own build ran four times under the shared verify lock, and each leg hashed all 24 dist files:

leg	state of protocol.ts	dist against leg 1
1	head	(reference)
2	the base text put back on :22793, blob 5be50ab59075 (stage 1's recorded head blob for this file)	0 of 24 files differ; the marker comment 5299845282 is in no built file
positive control	a docblock line on an exported member changed (refusal is being to refusal is BEING)	index.d.ts and index.d.cts differ; ablation-dist-preflight finds the marker in 2 built files
3	head again	0 of 24 differ (deterministic); ablation-dist-preflight --absent passes

So a comment change that ships is visible to this instrument, and this one does not ship. Restore proof: the protocol.ts blob equals HEAD (766d14add061), git diff HEAD is empty and the tree is clean.

Gates (head 16b5bf6c1)

• Derived gates: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derives 55 commands for 16 paths against merge base a7d9768ec. All 55 ran, each exit captured before any pipe, and all 55 exit 0. --ran, given COMMAND :: exit CODE lines, reports 「55 derived, 55 run, 0 NOT-MEASURED, 0 UNRUN」, a derived zero, and exits 0. A full turbo run build over ./packages/* and ./packages/*/* ran first under the verify lock (71 of 71 tasks), so no gate read an unbuilt workspace.
• Named readings among them:
  • node scripts/check-issue-citations.mjs exits 0: 「no issue citations added against a7d9768」.
  • pnpm check:issue-citations exits 0: self-test, 173 cases, 9 batteries.
  • pnpm check:doc-authoring exits 0, and the sibling-package prose-id baseline holds with no growth.
  • pnpm check:nul-bytes exits 0 (9,902 files). A raw control-byte scan of the 16 changed files finds none (grep exit 1).
• Tests and typecheck, under the verify lock:
  • pnpm --filter @objectstack/metadata-protocol test: 200 test files pass and 3 skip (203); 2,973 tests pass and 19 skip. These are the same totals as stage 1's.
  • pnpm --filter @objectstack/metadata-protocol typecheck exits 0, and tsc --noEmit --listFiles puts all 203 tracked test files and all 16 changed files in the program.
• Lint, as a proven narrowing: eslint runs with inline config off (--format json) over the 16 touched files plus dist/index.js as the control. It gives 17 results, 0 errors and 1 warning, the control's ignore notice, and none of the 16 is reported ignored. eslint.config.mjs:327-328 states that no type-aware linting is enabled, so a comment edit cannot move the verdict on an untouched file. The repo-wide pnpm lint is CI's run.

Acceptance notes

• Base. The branch is on main at a7d9768ec, the stage 1 squash. main has moved two commits since (1a4c7f826, ef96c9ede). Neither touches this package, scripts/check-issue-citations.mjs or scripts/pm/dispatch-gates.mjs. No merge was taken; the merge queue rebuilds on the merged generation.
• File count. The review recorded the 22 sites as 「21 lines in 15 test files」. Measured here: 21 lines in 14 files. The site and number counts agree.
• The same family in other packages, not edited. Two other packages carry similar test comments: packages/rest (#14389 §5 in error-response-sandbox-arm-message.test.ts and rest-duplicate-record-arm.test.ts) and packages/lint ((#10064) in runtime-gate.object-writes.test.ts and validate-object-field-refs.test.ts). They are independent sites with the same rot, outside this claim's file surface. Their lanes' anchors are 10220a7bf and def0d3e63.
• The census tool was not re-run. Its surface defers test files, so this population is outside it by construction. The same extractor and classifier, over the census's comment-prose projection of the package's non-test files, read 0 dead both before and after.
• Wording only: 「the card」 / 「this card」 stands on many comment lines in this package. It carries no number, and neither instrument sees it. This diff removes one antecedent of it, and the rewrite repairs that one in place (protocol.ui-view-hidden-columns.test.ts:46).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol, touching 4 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/api/client-sdk.mdx (via diffItem (sdk, the bare tail of client method meta.diffItem, bound to GET /api/v1/meta/:type/:name/diff), meta.diffItem (sdk, the route ledger binds it to GET /api/v1/meta/:type/:name/diff, selected by route anchor /:type/:name/diff))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-1.mdx (via diffMetaItem (symbol, a method of class ObjectStackProtocolImplementation), /:type/:name/diff (route, bridged from symbol diffMetaItem — its route source's handler names it))
• content/docs/releases/v17/17-5.mdx (via /:type/:name/diff (route, bridged from symbol diffMetaItem — its route source's handler names it))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 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.
• 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 — 11 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 be5a83cfaaf3051eb0182e23b0e62e77f5a12866 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from a2b6694575bdde4cdd6357b0b3bb17686e81feed — the merge of head 16b5bf6c1848573eb8b7efd85b4ffcd91c9ee78f into base be5a83cfaaf3051eb0182e23b0e62e77f5a12866, 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 a2b6694575bdde4cdd6357b0b3bb17686e81feed && git checkout a2b6694575bdde4cdd6357b0b3bb17686e81feed
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin be5a83cfaaf3051eb0182e23b0e62e77f5a12866 16b5bf6c1848573eb8b7efd85b4ffcd91c9ee78f && git checkout -B drift-repro be5a83cfaaf3051eb0182e23b0e62e77f5a12866 && git merge --no-ff 16b5bf6c1848573eb8b7efd85b4ffcd91c9ee78f

node scripts/docs-audit/affected-docs.mjs --json be5a83cfaaf3051eb0182e23b0e62e77f5a12866

⚠️ 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 be5a83cfaaf3051eb0182e23b0e62e77f5a12866 → pass the list as
args.docs, on the commit named under Which tree this was computed on.