docs(service-realtime): re-anchor the dead tracker citation to the commit that decided it

[objectstack-fleet]

Part of #20596
Clause-②: no

What changed

This is the eighteenth stage of the domain:services lane of the dead-citation sweep, and the lane's last package. It covers packages/services/service-realtime/src/** and nothing else. By the seat's claim (5913177103), it is the last of the single-site packages, taken one package per stage. The card's own close is the seat's act, so this PR says Part of and the card stays open.

Every comment or docblock site in scope that cited a tracker number answering 404 has been rewritten in ruling C+D's form C (comment 5749154545 on #19123), by the method of stages 1 to 17 (the latest is PR #20866, landed as 6c96b37be, the base here). That is 1 site on 1 line in 1 file, covering 1 number:

• src/translations/index.ts:27, the census's one site in this package at the base (a docblock). No test comment, test string, source string or gate-invisible spelling in this package carries a dead number (see the supplementary reading below), so the census site is the whole population.

The rewritten line now cites the commit in this repository that decided what it describes: 1 commit sha. No ADR or ruling record records that decision (see the per-number table), so ruling C's commit rung applies. No number was dropped.

Only a comment changed. The file keeps its line count (1 line out, 1 in), so no line citation into it moves. No code token moves (see the guard below). No citation number is added: the only tracker number on the added line is the live #12069, which already stood on it.

The rewritten line is byte-identical to the line the seven sibling translation sets already carry (plugin-approvals:26, plugin-audit:28, plugin-security:26, plugin-sharing:26, plugin-webhooks:26, service-messaging:29, service-storage:29), landed by stages 1, 2, 4, 6, 7, 9 and 16.

No changeset. The rewritten docblock does not reach dist, and dist is byte-identical with and without the rewrite (see Changeset below), so this PR takes skip-changeset.

Census: service-realtime, before and after

Instrument (A1). The gate's own node scripts/check-issue-citations.mjs --census --json, read-only and unchanged. The count below is its allocated-but-absent findings under packages/services/service-realtime/. Each run counts as a reading only because its board frontier equals the newest issue or pull-request number, read by a separate request just before and just after the run.

reading	tree	board	whole-repo allocated-but-absent	service-realtime sites	lines	files	numbers
before	base 6c96b37be, run 2026-09-30T14:25:19Z to 14:29:09Z	enumerated, 188 pages, frontier #20876 (newest #20876 before and after)	744	1	1	1	1
after	head 3e5cba47c, run 14:40:18Z to 14:44:03Z	enumerated, 188 pages, frontier #20878 (newest #20878 before and after)	743	0	0	0	0

The whole-repo drop is 1, and the finding sets of the two runs differ by exactly one row, translations/index.ts:27 #11671, removed; none was added. The resolves tally is 33,322 in both runs, and resolves-as-pull-request (1,985) and cross-repo-unjudged (1,022) did not move either. Neither run was truncated or discarded: both enumerations read 188 pages at the newest frontier. The seat's census counted 1 here at 6bff748b, and the base agrees: 6bff748b is an ancestor of the base, and no commit between them touches this package.

At the after head, no package under packages/services/, packages/plugins/ or packages/triggers/ holds a census finding.

Supplementary instrument, the whole scope. The census does not read test files or strings. So a second reading runs the gate's own exported extractCitations (whole-file and comment-prose projections) and namesThisRepository over every .ts file under service-realtime/src (18 files). It takes its verdicts from the before census's own board reading rather than from a second enumeration: a number is dead when that census reported it allocated-but-absent, and alive when the gate's own census-scope extraction (collectCitations) judged it and the census did not report it. One number is covered by neither, because it stands only in test files: #20044, read on its own through the read-only tools, answers as an issue. The probe's control: #11671 answers 404 on the issues endpoint and on the pull-request endpoint.

reading	citations	dead	src comment	test comment	src string	test string
before, 6c96b37be	20	1	1	0	0	0
after, 3e5cba47c	19	0	0	0	0	0

Its src-comment column equals the census's 1, which is the control on the second instrument. The 19 live citations are the same in both readings (17 by the census's judgement, 2 by the single read), none is cross-repo, none is unjudged, and the drop of 1 citation is exactly the rewritten site. A third, raw reading (every # followed by 2 to 6 digits, whatever surrounds it) finds 20 occurrences before and 19 after, the same drop of 1, and no token beyond the gate's grammar.

Per-number table

Sites and files count every dead occurrence in scope at the base (comments and strings, tests included).

number	sites / files	rewritten / left	anchor: what it decided
#11671	1/1	1/0	09b4f4e4e (PR #12557): the extract command's --source-hashes option writes a per-locale provenance companion, LOCALE.source-hashes.generated.ts, beside the generated translation bundles, recording for each leaf the source revision it is still a byte copy of, per maintainer ruling #12069 Option A. That is exactly what :26-27 say. Its message names #12069 but not #11671; its own diff names #11671 on 16 added lines. git blame puts :27 in 30928a615 (PR #12724, which wires the serving-time read of that companion into all nine bundle sets), a descendant of the anchor. Reused: stages 1, 2, 4, 6, 7, 9 and 16 gave the identical line in seven sibling packages this anchor

The sha matches exactly one commit (git rev-parse --disambiguate, count 1) and is an ancestor of the base (merge-base --is-ancestor, exit 0; reverse leg, base against the anchor, exit 1; control leg exit 0: the repository's root commit 1598cabe4, 15,219 commits behind the base, against the anchor's 3,821; the history is complete, --is-shallow-repository false, 15,220 commits at the base). #11671 answers 404 on the issues endpoint and on the pull-request endpoint, read one by one.

No ADR, scripts/adr-anchors/ file or ruling record names #11671, #12069 or the source-hash companion (git grep over docs/adr and scripts/adr-anchors: one unrelated source-hash cache hit in ADR-0080; nothing under docs/ outside the release pages names either number), so ruling C's first rung is empty.

Wordings to check

• Tag swap in place. 「(maintainer ruling [Decision] 把 #8765 的 source-hash sidecar 扩展到生成的 i18n bundle —— #9672 写明的升级条件已满足 #12069 Option A, [finding] check:i18n verifies key presence, not that an untranslated leaf still matches the source string it was filled from — and the drift is sticky #11671)」 became 「(maintainer ruling [Decision] 把 #8765 的 source-hash sidecar 扩展到生成的 i18n bundle —— #9672 写明的升级条件已满足 #12069 Option A, commit 09b4f4e)」. It is the form, and the byte-identical line, the seven sibling translation sets carry. The line grows from 77 to 87 characters, as it did in each sibling; eslint.config.mjs declares no line-length rule, and reflowing would have moved neighbouring lines.

Sites left

• In src: none. No test title, assertion message, operator log string, runtime refusal, quoted maintainer ruling or generated file in this package carries a dead number. The three generated *.source-hashes.generated.ts headers carry only the live #12069 and #8765.
• Outside src, listed and left, not edited in this stage:
  • scripts/i18n-extract.config.ts:17 names the dead #11671 (beside the live #12069); the anchor for whoever next edits it is 09b4f4e4e. The file is outside files[] and outside the census surface. Its other numbers are live: #12559 and #10868.
  • tsconfig.scripts.json:1 names the dead #11351 (404 on the issue and pull-request endpoints). Its other numbers are live: #10756 and #5475.
  • vitest.config.ts names the live #10374; README.md names the live #2992 on 2 lines.
  • The release-owned CHANGELOG.md names the dead #11671 on 2 lines (:779, :825) and the dead #13112 on 1 line (:696; 404 on the issue and pull-request endpoints). Its other 15 numbers are live: 11 by the census's judgement, and by single reads #18715, #20044 and #12642 as issues and #2528 as a pull request.
  • package.json and tsconfig.json name none.

Mechanical guard: no code token moves

The guard compares, base 6c96b37be against head, over the one touched .ts file:

• Reading 1, the TypeScript parser's leaf nodes (a forEachChild walk, so comments are trivia and JSDoc nodes are never visited). String and template literals are therefore read in full.
• Reading 2, the full token stream in parser context (a getChildren walk, so punctuation and keywords are included; JSDoc nodes skipped).

Results:

• Real run at the head 3e5cba47c: 50 base leaf tokens, 0 files with a token change on either reading (exit 0).
• Comment control (「Recording alone changes nothing a user sees」 to 「... alters ...」): 0 files changed, as expected (exit 0).
• Positive control, a code identifier renamed (undefined, zhCNGeneratedSourceHashes) to ...SourceHashesX)): DIFFER on the identifier in both readings (exit 1).
• Positive control, a string-literal key changed ('es-ES': withSourceFallback to 'es-EZ': ...): DIFFER on the string literal in both readings (exit 1).
• Positive control, a keyword changed (const enSource to let enSource): DIFFER on the keyword in reading 2 (exit 1). Reading 1 cannot see it, which is why both readings run.

Every mutation went through scripts/ablation-replace.mjs (wrap mode) under a shell trap that restores by absolute path, and each landed (anchor 1 to 0, blob changed). Each restore was proven byte-identical to the HEAD blob (cb6af4310953), with git diff HEAD empty and a clean tree afterwards.

Changeset: none (skip-changeset)

files[] is dist, README.md and CHANGELOG.md, and the package is not private. Measured on the built package (A3), after a full turbo run build at 3e5cba47c, where this package's own tsup ran (a cache miss) and cleaned its output folder:

• The rewritten line, its whole docblock (:23-49, which sits on the unexported const enSource), the anchor sha, the old number and the live #12069 appear in no dist file (0 in all 6, source maps included). Nor do its neighbours :24, :26, :28, :29 and :46, the module header :4, or a never-written negative phrase. The bundle hoists that declaration to a bare var enSource, RealtimeTranslations; inside the lazily imported module's init wrapper, and its docblock does not travel with it.
• Positive controls, text that does ship: from this same file, RealtimeTranslations (12 hits), withSourceFallback (7) and zhCNGeneratedSourceHashes (6) are in the JS entries. A docblock line of this package, realtime-service-plugin.ts:49 (「Services init() registers on every path」, on a class field), is in all four entries: index.js, index.cjs, index.d.ts and index.d.cts. So a docblock can reach dist here; this one does not.
• Byte identity. The package was rebuilt with the base line put back (through scripts/ablation-replace.mjs, with the file proven equal to the base blob 19744f2a54a4 during the leg), and again after the proven restore. Each leg cleaned the output folder and rebuilt ESM, CJS and declarations. The sha256 of all 6 dist files is identical in all three builds: JS entries, declaration files and source maps.

So nothing this PR rewrites is published, and a changeset would announce a change no consumer can observe. No .changeset/* file is added or touched.

Gates (head 3e5cba47c)

• Citation judging, as CI runs it: node scripts/check-issue-citations.mjs exits 0 (「every citation this change adds resolves」; it judged the one added citation, #12069). pnpm check:issue-citations exits 0 (self-test, 114 cases, 8 batteries).
• Doc authoring: pnpm check:doc-authoring exits 0 (the sibling-package prose-id baseline holds, no growth).
• Derived gates: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at 3e5cba47c (change set derived from git: 1 path against the merge base 6c96b37be) derived 50 commands, all among the dispatch list's 63.
  • All 63 of the dispatch list ran, each with its exit code captured before any pipe, and all 63 exit 0; none exited 3.
  • --ran, fed each command with its exit code, reports 50 derived, 50 run, 0 NOT MEASURED (a derived zero), 0 unrun, and exits 0. Of the other 13, it classifies 7 as pending-changeset families and 6 as outside this derivation.
  • A full turbo run build over ./packages/* and ./packages/*/* ran first under the shared verify lock (71 of 71 tasks), so no gate hit an unbuilt workspace.
• Roster families the derivation lists outside its commands (their rosters sit in a directory this diff touches): pnpm check:authz-resolver, pnpm check:error-code-casing and pnpm check:filter-alias-parity, plus node scripts/check-changeset-fixed.mjs, which the dispatch named. Each exits 0.
• Tests and typecheck, under the verify lock, at 3e5cba47c:
  • pnpm --filter @objectstack/service-realtime test: 5 files pass and 33 tests pass, which is every tracked test file under src/.
  • pnpm --filter @objectstack/service-realtime typecheck exits 0, and tsc --noEmit --listFiles puts the touched file in the program (the config includes src and excludes no test file; all 5 test files are listed). The package has no check:test-typecheck script.
• Lint, as a proven narrowing: eslint with inline config disabled, over the touched .ts file, gives 1 file, 0 errors and 0 warnings (its --format json output). The file is in eslint's own population (not reported ignored; dist/index.js, the control, reads ignored). eslint.config.mjs never enables type-aware linting (no parserOptions.project, as its own lines 327-328 state), so a comment edit here cannot move the verdict on any untouched file. The repo-wide pnpm lint is CI's run.
• Control bytes: pnpm check:nul-bytes exits 0, and a raw scan of the changed file for control bytes finds none.

Acceptance notes

• The gate-invisible spellings, grepped as the claim asked (check-issue-citations closeout (extractor spellings): CITATION_RE refuses a hyphen after the digits, so a dead #N-word citation (#13398-class) is invisible to the diff gate and to the census #20636, including the clause #N position). At the base and at the head, #N-word, #A/#B, option #N, clause #N and URL-spelled links are each on 0 lines of this package's src (a known-present spelling, #14646, reads 3 lines as the control), so the claim's 0 / 0 / 0 / 0 / 0 hold.
• #11671 elsewhere. Five comment lines in packages/platform-objects/src still name it (setup.translation.ts:49, source-hash.ts:87, :214, :568, metadata-translations/index.ts:31), all in the census; that package belongs to the engine lane's stage card, 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. The anchor measured here, 09b4f4e4e, is reusable there.
• Outside-src residue. Two dead numbers in files outside src and outside files[] (#11671, #11351, listed above) are left, as stages 13 to 17 left theirs. They ship nothing and move no gate.
• The census instrument did not truncate in this stage. Both enumerations read 188 pages at the newest frontier.
• Base. The branch is on main at 6c96b37be. main has since moved six commits (to 9905e61ca, read at 14:58Z). None touches packages/services/service-realtime, scripts/check-issue-citations.mjs, scripts/pm/dispatch-gates.mjs, .changeset/config.json or the doc-authoring prose-id baseline, so no merge was taken; the merge queue rebuilds on the merged generation. The derivation's STALE TREE note names three inputs that moved there (scripts/check-stack-collection-maps.mjs, scripts/fixtures/i18n-walk-parity/every-group.stack.json, scripts/role-word-baseline.json); none of the derived 50 commands names them, and none mentions this package before or after, so a comment-only diff here cannot interact with them.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/services/service-realtime/src/translations/index.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

• 1 changed file(s) yielded no anchor (packages/services/service-realtime/src/translations/index.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 — 8 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 9905e61ca2fddb43d266c23cdb12ced5019c1a74 → packageMentionDocs.