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

[objectstack-fleet]

Part of #20596
Clause-②: no

What changed

This is the seventeenth stage of the domain:services lane of the dead-citation sweep. It covers packages/services/service-job/src/** and nothing else. By the seat's claim (5911377566), it is the next of the two single-site packages left in the lane, taken one package per stage. Later stages cover the other packages, 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 16 (the latest is PR #20850, landed as 40d6c5fbd, the base here). That is 2 sites on 2 lines in 2 files, covering 1 number:

• src/never-fires.fixture.ts:30, the census's one site in this package at the base (a docblock);
• src/db-job-adapter.timeout.test.ts:55, a test-comment site the census defers, found by the supplementary reading below and rewritten too, as stages 1 to 15 did.

No test string, source string or gate-invisible spelling in this package carries a dead number, so these two sites are the whole population.

Both rewritten lines now cite the commit in this repository that decided what they describe: 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 comments changed. Each file keeps its line count (2 lines out, 2 in), so no line citation into either file moves. No code token moves (see the guard below). No citation number is added: the only tracker number on the added lines is the live #8628, which already stood on its line.

No changeset. Neither rewritten line reaches dist, and dist is byte-identical with and without the rewrite (see Changeset below), so this PR takes skip-changeset.

Census: service-job, 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-job/. 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-job sites	lines	files	numbers
before	base 40d6c5fbd, run 2026-09-30T12:36:32Z to 12:40:56Z	enumerated, 187 pages, frontier #20855 (newest #20854 before; #20855 after, an issue opened 12:40:06Z inside the run, so the frontier equals the newest at the run's end)	745	1	1	1	1
after	head 6ac866f86, run 12:46:10Z to 12:49:55Z	enumerated, 187 pages, frontier #20856 (newest #20856 before and after)	744	0	0	0	0

The whole-repo drop is 1, and the finding sets of the two runs differ by exactly one row, never-fires.fixture.ts:30 #8748, removed; none was added. The resolves tally is 33,221 in both runs, and resolves-as-pull-request (1,985) and cross-repo-unjudged (1,018) did not move either. Neither run was truncated or discarded: both enumerations read 187 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's src.

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-job/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. 4 numbers are covered by neither, because they stand only in test files. Each was read on its own through the read-only tools, and each answers as an issue: #8628, #9611, #9631 and #9633. The probe's control: #8748 answers 404 on the issues endpoint and on the pull-request endpoint.

reading	citations	dead	src comment	test comment	src string	test string
before, 40d6c5fbd	95	2	1	1	0	0
after, 6ac866f86	93	0	0	0	0	0

Its src-comment column equals the census's 1, which is the control on the second instrument. The 93 live citations are the same in both readings (81 by the census's judgement, 12 by the single reads), none is cross-repo, none is unjudged, and the drop of 2 citations is exactly the two rewritten sites. A third, raw reading (every # followed by 2 to 6 digits, whatever surrounds it) finds 95 occurrences before and 93 after, the same drop of 2, 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
#8748	2/2	2/0	226cb71d5 (PR #8774): every exact-count case in this package moves onto the inert NEVER_FIRES cron fixture ('0 0 30 2 *', February 30th, which never occurs), and the fixture moves out of the timeout suite into the shared never-fires.fixture.ts. Its message records the measurement :30 describes: only Date faked, the registration placed 2/5/10/15 ms before the expression's instant, one extra handler run per case under the firing spellings, and two of the three no longer reproducing at a 2 ms lead. That is what :30 says, and what :55's 「now shared with the sibling job suites rather than spelled a second time here」 says. Its subject names #8748, and its own diff names it on 2 added lines; git blame puts both rewritten lines in this commit

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 legs exit 0: 7246d631d, 5,451 commits behind the base, and the repository's root commit 1598cabe4, 15,209 behind, against the anchor's 5,436; the history is complete, --is-shallow-repository false, 15,210 commits at the base). #8748 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 #8748, PR #8774, NEVER_FIRES, never-fires, February 30th or an inert cron (git grep over docs/adr and scripts/adr-anchors: 0 hits), so ruling C's first rung is empty. The repository's other #8748 tokens are objectui#8748, a cross-repo reference the gate never judges.

Wordings to check

• never-fires.fixture.ts:30, tag swap in place. 「Measured (service-job: cron-job-adapter.test.ts carries the same minute-boundary self-fire hazard fixed in #8628 — four cases register a real every-minute cron and assert exact counts #8748) by faking ONLY Date」 became 「Measured (commit 226cb71) by faking ONLY Date」. The form is the one packages/lint/src/lint-flow-patterns.ts:1468 already carries on main (「Measured (commit 8ed9c54)」).
• db-job-adapter.timeout.test.ts:55, tag swap in place. 「(service-job: db-job-adapter.timeout.test.ts reds CI whenever the run crosses a minute boundary — it registers a real every-minute cron and asserts exactly one run row #8628, service-job: cron-job-adapter.test.ts carries the same minute-boundary self-fire hazard fixed in #8628 — four cases register a real every-minute cron and assert exact counts #8748)」 became 「(service-job: db-job-adapter.timeout.test.ts reds CI whenever the run crosses a minute boundary — it registers a real every-minute cron and asserts exactly one run row #8628, commit 226cb71)」. The live #8628 stays: it is the report of the wall-clock flake, whose own change, 7246d631d (PR test(service-job): make the timeout suite's cron unable to self-fire #8750), first made this suite's cron unable to self-fire. The form is the one stages 7 and 9 landed (for example (#5928, commit 69787f07b) in plugin-audit).
• Neither line was reflowed, so each is 11 characters longer than before (70 to 81, and 72 to 83), a little past its block's wrap. 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.
• Outside src, listed and left, not edited in this stage:
  • The release-owned CHANGELOG.md names the dead #13112 on 1 line (:705; 404 on the issue and pull-request endpoints). Its other 27 numbers are live: 19 by the census's judgement, and by single reads #18715, #14619, #9517, #1893, #9611, #9631 and #9633 as issues and #9546 as a pull request.
  • vitest.config.ts names the live #10374.
  • README.md, package.json and tsconfig.json name none.

Mechanical guard: no code token moves

The guard compares, base 40d6c5fbd against head, over both touched .ts files:

• 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 6ac866f86: 755 base leaf tokens, 0 files with a token change on either reading (exit 0).
• Comment control (「croner resolves Feb 29 forward」 to 「croner rolls Feb 29 forward」): 0 files changed, as expected (exit 0).
• Positive control, a code identifier renamed (expression: NEVER_FIRES } to expression: NEVER_FIRESX }): DIFFER on the identifier in both readings (exit 1).
• Positive control, a string literal changed ('0 0 30 2 *' to '0 0 31 2 *'): DIFFER on the string literal in both readings (exit 1).
• Positive control in the second file, a numeric literal changed (TIMEOUT_MS = 20 to 21): DIFFER on the literal in both readings (exit 1).

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 blobs (1fd5e1b3f612, ce37b1050c78), 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. never-fires.fixture.ts is a test-only support module (nothing in src/index.ts re-exports it, and the tsup entry is src/index.ts alone), and the other touched file is a test. Measured on the built package (A3), after pnpm --filter '@objectstack/service-job...' build at 6ac866f86, where the package's own tsup ran and cleaned its output folder:

• Neither rewritten line appears in any dist file (0 in all 6, source maps included). Nor do the old number, #8628, the anchor sha, the neighbouring lines :28, :31, :54 and :56, NEVER_FIRES, the '0 0 30 2 *' expression, or a never-written negative phrase.
• Positive controls, text that does ship: CronJobAdapter (45 hits), DbJobAdapter (73) and sys_job_run (52) across the entries, and two docblock lines of the DbJobAdapter class JSDoc in db-job-adapter.ts (「{@link DbJobAdapterOptions.recordRuns} is false, the on/off switch for」 and the recordRuns gating line below it), each in index.d.ts and index.d.cts.
• Byte identity. The package was rebuilt with the base text put back in both files (through nested scripts/ablation-replace.mjs legs, with each file proven equal to its base blob, 919a2e444f23 and eb00f6eb1978, during the leg), and again after the proven restore. 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 6ac866f86)

• Citation judging, as CI runs it: node scripts/check-issue-citations.mjs exits 0 (「no issue citations added against 40d6c5f」). 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 6ac866f86 (change set derived from git: 2 paths against the merge base 40d6c5fbd) derived 54 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 54 derived, 54 run, 0 NOT MEASURED (a derived zero), 0 unrun, and exits 0. Of the other 9, it classifies 7 as pending-changeset families and 2 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 6ac866f86:
  • pnpm --filter @objectstack/service-job test: 11 files pass and 117 tests pass, which is every tracked test file under src/.
  • pnpm --filter @objectstack/service-job typecheck exits 0, and tsc --noEmit --listFiles puts both touched files in the program (the config includes src and excludes no test file).
• Lint, as a proven narrowing: eslint with inline config disabled, over the 2 touched .ts files, gives 2 files, 0 errors and 0 warnings (its --format json output). Both files are 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 files 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, so the claim's 0 / 0 / 0 / 0 / 0 hold. The one prefix-joined token, pre-#6617 in a test title of db-job-adapter.degraded-outcome.test.ts, is inside the gate's grammar and names a live number.
• Wording only: 「the card」 / 「this card」 stands on 4 comment lines in 3 files under service-job/src. It carries no number, neither instrument sees it, and this diff removes no antecedent.
• Outside-src residue. CHANGELOG.md:705 names the dead #13112; the file is release-owned and is left.
• The census instrument did not truncate in this stage. Both enumerations read 187 pages at the newest frontier.
• Base. The branch is on main at 40d6c5fbd. main has since moved two commits (to 660a9b247). Neither touches packages/services/service-job, scripts/check-issue-citations.mjs, scripts/pm/dispatch-gates.mjs or .changeset/config.json, so no merge was taken; the merge queue rebuilds on the merged generation. The one derivation input that moved is scripts/doc-authoring-prose-id.baseline.json, where the second commit removed only packages/objectql entries; this package has no entry there before or after, so the merged tree cannot move that gate's verdict on this diff.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/services/service-job/src/never-fires.fixture.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-job/src/never-fires.fixture.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 — 3 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 660a9b247e824f7747d63f3b778dccc9cb4751d6 → packageMentionDocs.