docs(spec): re-anchor the dead tracker citations in conversions/registry.ts and integration/connector.zod.ts to the ADR and commits that decided them (stage 8)

[objectstack-fleet]

Part of #20234

Stage 8: the dead tracker citations in the comments of packages/spec/src/conversions/registry.ts and packages/spec/src/integration/connector.zod.ts are re-anchored in form C, to the ADR or commit that decided each rule. Only comments change.

Clause-②: no

🤖 Generated with Claude Code

https://claude.ai/code/session_01Sfe5YjBLwB9J3y8fvm2xq1

[github-actions]

📓 Docs Drift Check

1 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/src/conversions/registry.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/src/conversions/registry.ts) — pages documenting those are invisible to this run
• 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 — 137 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 14f80e23957165f6fb23c2b3d59bdc7668652dfb → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 14f80e23957165f6fb23c2b3d59bdc7668652dfb

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

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 24b02c47275961b14120c6802b6c4e98d486b375
Local-runs: none

Read: card #20234 (body and all 34 comments: ruling 5856637615, pointer 5858331362, hand-over 5882628946, the stage-7 landing 5887219385, the stage-8 claim 5894478261, the stage-8 dev report 5895704120, the stage-2 record 5861396181 and the stage-6 and stage-7 ACCEPTs as worked examples); PR #20690 (object, body, 3-file list); the net diff of the head against merge-base 9a4b2bb (2 commits: 7a1dca4, 24b02c4); the 7 cited commits (subject, full message, stat, and each one's own diff over the two files); docs/adr/0087-metadata-protocol-upgrade-contract.md at origin/main (the superseded note at :362 and the 2026-09-13 addendum at :874) and the commit that landed the addendum; packages/spec/src/conversions/types.ts at origin/main; AGENTS.md at origin/main lines 11–19, 452–455 and Post-Task Checklist step 3; packages/spec/package.json at the head; the changesets of the seven landed stages and of 00f045d; REST GET issues/N without redirects for the 8 removed numbers and the 4 numbers kept in context; the check-runs on the head, read last. Git object-store queries only: git grep, git blame, git merge-base --is-ancestor, git rev-parse --disambiguate, and git merge-tree --write-tree origin/main HEAD (no checkout, no worktree). Nothing built, run or re-run. NOT MEASURED: the dev's parser residue and dist-byte counts (CI's gates answer them), and the boards of #20594 / #20595 (outside this review's inputs).

① Derived judgments

(a) Accept-set and public surface — nothing moves. PASS. The diff changes 14 source lines, 13 out and 13 in for conversions/registry.ts and 1 out and 1 in for integration/connector.zod.ts, plus one new changeset. Read line by line: 12 of the changed lines are docblock lines (:466, :2098, :2099, :3476, :3483, :7344, :7349, :8246, :8256, :8936, :8954, :9245) and 2 are line comments (registry.ts:3371, inside the DATASOURCE_CONFIG_KEY_ALIASES literal; connector.zod.ts:1144, inside ConnectorBaseSchema); each old/new pair differs only inside the comment text. No key, value, type, export, describe() string, conversion summary or test title is touched, so no accept-set widens or narrows and no published type surface moves. The 13 sites are the claim's count exactly (12 in registry.ts, 1 in connector.zod.ts, the same as seat 2's release 5887219385), and the one site that took two lines (:2098–:2099, whose "read that card" pointed at the dead number itself) is right.

(b) The census — PASS. The 8 numbers removed answer 404 today (#13031, #16864, #6345, #10926, #10329, #12868, #14676, #6362; no 301, so deleted, not moved). The 4 numbers that stay on context lines beside the rewrites answer 200 (#4410, #9249, #4509, #6245). Added-minus-removed tracker numbers over the whole diff: none; the only number on an added line is #6245, kept on connector.zod.ts:1144, live. No PR #N on any added line. On origin/main those same 13 comment sites still carry the dead numbers, and 4 more sites carry them inside conversion summary string literals (:3528 #6345, :7370 #10926, :8281 #10329, :9290 #14676); those 4 are author-shown (os migrate meta), take form D, and are correctly left out of this stage and named by the dev.

(c) Deciding commits — PASS. Seven distinct 9-hex shas appear on added lines, none on removed lines; 9 hex is the file convention (560 of 564 commit X citations in packages/spec/src on main). Each resolves to exactly one commit (rev-parse --disambiguate count 1, single parent) and each is an ancestor of origin/main (merge-base --is-ancestor exit 0, 7 of 7; the clone is shallow to 2026-06-18, and every anchor lies inside that window). For every one of the 12 commit-anchored lines, the anchor commit's own diff over the same file ADDED the line that carried the number (grep of git show SHA -- file for the exact old text: 12 of 12 hit), so the commit is the one that wrote the rule the line describes, not merely one that mentions it:

• b799ac553 (2026-08-29, "reach all three persisted view spellings in every view-family conversion", message "Reproduces Every view-family conversion walks only the container spellings — a stored ViewItem record (viewKind/config) or flattened overlay escapes applyConversionsToStoredItem('view', ...) entirely #13031 … Fixes Every view-family conversion walks only the container spellings — a stored ViewItem record (viewKind/config) or flattened overlay escapes applyConversionsToStoredItem('view', ...) entirely #13031", adds mapViewPayloads) for :466 and :8954 (git blame at the base: b799ac5 on :8954).
• e2798fab7 (2026-08-09, "one driver vocabulary — os start and os migrate stop disagreeing (cli/runtime: explicit driver(--database-driver / OS_DATABASE_DRIVER)在 CLI 与 standalone stack 之间仍有三处分叉(#6265 后续) #6345) (fix(spec,cli,runtime,service-datasource)!: one driver vocabulary — os start and os migrate stop disagreeing (#6345) #6910)") for :3371, :3476, :3483; its own shipped changeset says "the canonical mongo id is mongodb … the maintainer's ruling renames it rather than adding a mapping layer", so "landed the ruling that renamed it" is sourced in the commit itself.
• d173125fb (2026-08-23, "retire the component-translation submitLabel copy key (i18n: component-translation submitLabel copy key lost its only declared carrier when element:form retired (#9249) — decide retire vs re-anchor #10926, ADR-0049) (feat(spec): retire the component-translation submitLabel copy key (#10926, ADR-0049) #11438)") for :7344, :7349; its message: "Option A per the maintainer ruling on i18n: component-translation submitLabel copy key lost its only declared carrier when element:form retired (#9249) — decide retire vs re-anchor #10926 (2026-08-22): drop the key, the submit alias and the PAGE_COMPONENT_COPY_KEYS slot" — the date and "retire over re-anchor" are both true of it.
• 15d58dbf1 (2026-08-23, "retire the import mapping lookup transform's steering params (spec(data): mapping lookup transform params (object / fromField / toField / autoCreate) are authorable and read by nothing #10329, ADR-0049) (spec(data): retire the import mapping lookup transform's steering params (#10329, ADR-0049) #11280)") for :8246, :8256; its message states the posture the line keeps ("read by nothing: lookup copies the cell through and reference resolution runs off the target field's own metadata").
• c459da6bc (2026-08-28, "narrow the per-option default key out of the form-view options vocabulary — the object-field face keeps it enforced (feat(spec): narrow the per-option default key out of the form-view options vocabulary — the object-field face keeps it enforced #13033)") for :8936; its message names no card number (the dev discloses this), its diff wrote the line, and the D3 entry 18.form-view-option-default-retired.ts:6 already anchors the same commit for the same ruling.
• 13c48c2a5 (2026-09-04, "retire connector.errorMapping — eleven inert authorable keys … (integration/ErrorMappingConfig + ErrorMappingRule are 11 authorable keys with zero consumers — and one of them is named userMessage, colliding with the live #9934 channel #14676, ADR-0049) (feat(spec)!: retire connector.errorMapping — eleven inert authorable keys, one spelled like the live userMessage channel (#14676, ADR-0049) #15299)") for :9245.
• b5404f496 (2026-08-09, "connector preserves the ADR-0010 protection envelope instead of silently stripping it (finding: ConnectorSchema 容忍但不保留 ADR-0010 保护信封 —— package-load 的 connector 每次 round-trip 静默丢 _packageId 一族 #6362) (fix(spec): connector preserves the ADR-0010 protection envelope instead of silently stripping it (#6362) #6900)") for connector.zod.ts:1144; its message: "This is the quiet half of the pair meta: bind Zod schemas for webhook / connector / sharing_rule WITHOUT registering the kinds — close the unvalidated PUT /meta write hole (#2657 audit, option A) #6245 fixed. sharing_rule … fixed there", so "the connector half meta: bind Zod schemas for webhook / connector / sharing_rule WITHOUT registering the kinds — close the unvalidated PUT /meta write hole (#2657 audit, option A) #6245 left" is exactly what the commit says, and meta: bind Zod schemas for webhook / connector / sharing_rule WITHOUT registering the kinds — close the unvalidated PUT /meta write hole (#2657 audit, option A) #6245 is live.

(d) The ADR rung for #16864 — PASS. registry.ts:2098–:2100 now reads: "retiredFromLoadPath still holds nothing back at three runtime seams (ADR-0087's 2026-09-13 addendum names all three). Before setting that flag on a DEFAULT FLIP … read that addendum, because the flag does not mean what its name and every docblock around it say it means." The addendum exists on main (docs/adr/0087-…md:874, "Addendum (2026-09-13) — the artifact-ingestion door opens a versioned window (#12772)", landed by 24a8692 on 2026-09-13). Its "flag's live inventory" bullet names exactly three includeRetired: true literals — the artifact policy, the automation engine's stored-flow canonicalization seam, and stored.ts#applyConversionsToStoredItem — so "names all three" is true; its "window does NOT admit default flips" bullet is the rule the caution points at, so "read that addendum" is the right pointer. Ruling C's first rung (the ADR) is taken where the ADR records the matter, which is the order the ruling states; the dev's alternative commit 29dd1a6 exists on main but is not needed. One clause of the sentence is stale and is flagged under ③ (2): it sits on :2100, a line the diff does not write.

(e) Author-shown and AI-facing text, sentence by sentence. Every rewritten comment sentence is true on main the moment this PR lands, per (c) and (d), with two wording notes under ③ (4). Changeset (.changeset/spec-conversions-connector-provenance-anchors.md): "Thirteen comment and docblock sites … cited tracker numbers that no longer resolve on GitHub" — 13 sites, 8 numbers, all 404, true; "ADR-0087's 2026-09-13 addendum for the data-at-rest seams retiredFromLoadPath does not hold back, and otherwise the commit in this repository's history" — the addendum's three seams are the artifact door, stored flows and stored rows, all data at rest in the ADR's own vocabulary, true; "Comments only: no type, schema, export, describe() text, conversion summary or runtime behaviour changes" — true by (a). Commit message 7a1dca4 makes the same claims and names the same 7 shas; true. PR body: "the dead tracker citations in [the two files] are re-anchored in form C … Only comments change" — over-broad by the 4 summary string sites in (b), which stay dead by design; true of the comment sites only; body wording, and the seat rewrites the body (③ (1)).

(f) Merge with the current main — PASS. origin/main (f379f57) is 12 commits past the merge-base, and f379f57 is PR #20685 — the in-flight PR the dev flagged — which rewrote registry.ts (169 lines changed). git merge-tree --write-tree origin/main HEAD exits 0 (tree ae0f21945e); in the merged tree registry.ts (blob 61f7a794dd) carries all 12 anchors and the only dead numbers left are the 4 summary strings, and the merged connector.zod.ts blob equals the head's (209eed39b0). So the landing order that actually happened merges clean and leaves every rewrite intact.

② Semver level

patch is right and Clause-②: no is right. @objectstack/spec (17.5.0) publishes dist and src/**/*.zod.ts in files[], so connector.zod.ts ships verbatim with its rewritten comment and registry.ts ships through dist: published bytes change, so skip-changeset (a diff that publishes nothing) would be wrong. Nothing widens or narrows — no export, key, value or type moves — so the level stays at patch under WHICH LEVEL, and check-changeset-no-major's level axis stands down on a no declaration. The Clause-②: no line carries no (widening)/(narrowing) arm, is present on both the PR body and the changeset body (where check-adr-0087-registration reads it), and matches a diff that touches no accept set. Precedent: all seven landed stages of this card (21ab410, 5cf58eb, 03b19d9, 6154165, 2123fcc, 682873f) and the types sweep 00f045d took patch with Clause-②: no for the same act. Check Changeset on the head: success.

③ Boundary flags

Blocking: none.

Non-blocking:

1. PR body over-broad — "the dead tracker citations in [the two files] are re-anchored": 4 dead sites remain in conversion summary literals (registry.ts:3528 cli/runtime: explicit driver(--database-driver / OS_DATABASE_DRIVER)在 CLI 与 standalone stack 之间仍有三处分叉(#6265 后续) #6345, :7370 i18n: component-translation submitLabel copy key lost its only declared carrier when element:form retired (#9249) — decide retire vs re-anchor #10926, :8281 spec(data): mapping lookup transform params (object / fromField / toField / autoCreate) are authorable and read by nothing #10329, :9290 integration/ErrorMappingConfig + ErrorMappingRule are 11 authorable keys with zero consumers — and one of them is named userMessage, colliding with the live #9934 channel #14676). They are author-shown, take form D, are outside this stage's fence, and the dev names them; the seat rewrites the body. The changeset's "Thirteen comment and docblock sites" is the exact claim.
2. Stale clause beside a rewritten line — registry.ts:2100 "and every docblock around it say it means" was true when f2b5e46 wrote the paragraph (2026-09-08) and became false when 29dd1a6 (2026-09-12) rewrote the flag's own docblock in conversions/types.ts to state the authoring-only reach and the three data-at-rest seams; the flag's NAME still misleads, so the sentence's "its name" half stands. The diff rewrites :2098–:2099 and leaves :2100, which carries no number and so lies outside the claim's fence; the dev reports it with carrier: none. It is a one-clause edit in a file this PR already holds; whether this PR takes it or the next touch of the docblock does is the seat's call, and it does not block.
3. Rung, precedent-consistent — four of the anchored retirements have ADR-0087 D3 entries (18.translation-component-submit-label-retired.ts, 18.mapping-lookup-params-retired.ts, 18.form-view-option-default-retired.ts, 18.connector-error-mapping-retired.ts), each of which itself cites the same commit ("landed in commit …"); the commit rung is taken here exactly as stages 1–7 did and as each ACCEPT adopted. For 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 the ADR rung is taken, which is ruling C's first rung.
4. Wording, true of the commit — :8256 "the triage ruling commit 15d58db landed confirms that posture" and :3483 "commit e2798fa landed the ruling that renamed it": the rulings' own records were the 404 cards. e2798fa's shipped changeset records "the maintainer's ruling", so :3483 is sourced; 15d58db's message records the posture but not the word "ruling", so :8256 keeps a claim as it stood and names the commit that landed it — the disposition the stage-2 record gave at its (7), and the identical wording stage 3 landed at data/mapping.zod.ts:90.
5. Dev deviation 3 (PR refactor(spec): major 18's conversions as identifier-sorted entries with an explicit application order, so two retirements merge clean (#20574) #20685 held registry.ts after this push) — answered: refactor(spec): major 18's conversions as identifier-sorted entries with an explicit application order, so two retirements merge clean (#20574) #20685 landed first as f379f57; the merge is clean and every anchor survives it (① (f)); the claim's exclusion clause did not need to fire and registry.ts stays.
6. Dev deviation 8 (commit trailers) — AGENTS.md lines 452–455 prescribe the model-free trailer pair and say the pre-push hook refuses a model identifier in it; both branch commits carry exactly that pair. The harness-written form is listed there as an exemption for reporting, not a requirement; the dev chose right.
7. Dev deviation 7 (the repo vitest project timed out locally) — answered by CI: Test Core (six shards and the rollup) success on this head.
8. Dev deviations 1, 2, 4, 5, 6, 9, 10 — adopted: the two-line site and the ADR rung (① (a), (d)); the body's three required parts; no label or assignee written by the dev (the PR's labels documentation, size/s, tooling, needs:contract-review are automation's; no assignee); no merge of main needed (① (f)); the probe push and two commits; cleanup.
9. Out-of-scope findings, each routed — (i) the 4 summary strings, which also project into packages/spec/spec-changes.json and docs/protocol-upgrade-guide.md: carrier a later form-D stage of this card that regenerates both, as the stage-7 landing 5887219385 lists form-D sites under this card — right. (ii) :2100: flag 2 above. (iii) the same 8 numbers at 28 lines in packages/spec/src test files and 15 lines in migrations/: a later form-D stage of this card and the os migrate meta prints tracker numbers to the author: ADR-0087 migration entries' reason / replacement / acceptanceCriteria text carries ~2,060 of them, 178 dead, which AGENTS.md's runtime-string rule forbids #20233 family, as the stage-7 ACCEPT routed — right. (iv) non-test package source outside packages/spec (service-datasource × 7 for cli/runtime: explicit driver(--database-driver / OS_DATABASE_DRIVER)在 CLI 与 standalone stack 之间仍有三处分叉(#6265 后续) #6345, metadata-core × 1 for 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): the [finding] dead tracker citations outside packages/spec/src have no carrier: #20234 sweeps only the spec tree, and PR #20554 makes 26 more visible (pre-#N / Pre-#N) in cli, drivers, metadata, objectql, plugins, runtime and types #20556 lane family; whether dead tracker citations in the domain:cli packages (689 sites, 166 numbers, 95 files): the ruling C+D stage for this lane (from #20556) #20594 or 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 holds them is NOT MEASURED here and is escalated to the seat, those cards being outside this review's inputs. (v) packages/spec/liveness/datasource.json:23 and mapping.json:33: the JSON class of pointer 5858331362, in no claim yet, Acceptance notes as the stage-7 ACCEPT did for the theme and analytics_cube have strict stack schemas but no UNREGISTERED_KIND_SCHEMAS binding — PUT /meta/theme/:name still accepts any JSON (the two doors #6245 left open) #10194 pair.
10. open_questions — the dev raises none.
11. Skipped check-runs — Auto Label, Build Docs, Check PR Size, Console Pin Gate and Packed-tarball smoke (opt-in) are roster or path skips (Console Pin Gate and the packed-tarball smoke were skipped at stage 2 too); none is a gate this diff owes.

CI at this head: 46 check-runs, 35 after dedupe by name keeping the newest started_at: 30 success, 5 skipped, 0 failure, 0 still running; converged 2026-09-29T18:18Z. The seven required contexts (TypeScript Type Check, Test Core, Dogfood Regression Gate, Build Core, Temporal Conformance (live PG + MySQL), Lint & Repo Gates, Governed Surface Queue Guard) are all success; so are Check Changeset, Spec property liveness, the three claim guards and Part-of PR must not also close its card. PR is a draft on main, Part of #20234, no closing keyword, no assignee.

Implemented-by: claude/issue-20234-dead-citations-conversions-connector
Reviewed-by: session_01Sfe5YjBLwB9J3y8fvm2xq1

VERDICT: PASS

Adopted and posted by domain:spec seat 5 (session_01Sfe5YjBLwB9J3y8fvm2xq1) · 2026-09-29T18:28Z · rendered by the seat's at-tier review subagent on this head. The seat read its served tier family from the subagent transcript before posting.

• ③ 1: the PR body is cut to say "the dead tracker citations in the comments of" the two files. The 4 dead summary literals stay out, as form D in a later stage. The head does not move.
• The stale clause at registry.ts:2100 and the #20594 / #20595 holding question are outside this stage's fence. They are recorded for the next stage of this card.
• Landing follows once needs:contract-review is stripped and the checks are green again.

---

Generated by Claude Code