docs(service-package): re-anchor the dead tracker citations to the commits that decided them (#20742)

Part of #20596
Clause-②: no

## What changed

This is the tenth stage of the `domain:services` lane of the
dead-citation sweep. It covers
`packages/services/service-package/src/**` and nothing else. By the
seat's census at the claim (`5901757839`), it is the largest package in
the lane that no in-flight work holds. 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 9 (PR #20609 as
`422db788a`, PR #20626 as `b80ab579d`, PR #20634 as `4d04b6be3`, PR
#20658 as `9a4b2bb38`, PR #20693 as `0e9ad74fb`, PR #20708 as
`9b384f63a`, PR #20717 as `cbaf04c1f`, PR #20729 as `d2820876f`, PR
#20737 as `4dfff176b`). That is **18 sites on 17 lines in 5 files,
covering 5 numbers**:

- 13 census sites (every census site this package has);
- 5 sites in test comments, which the census defers;
- no site the gate's grammar cannot see (the package has none, see
Acceptance notes).

Each rewritten line now cites the commit in `origin/main` history that
decided what the line describes, and says in its own words what was
decided: **4 distinct shas**. No number in this package has an ADR or
ruling record of its own in the repository (a grep of `docs/adr/` and
`scripts/adr-anchors/` for all 5 finds none, and nothing else under
`docs/` names them), so every anchor is a commit, per ruling C's order.
No number was dropped.

Only comments changed. Every touched source file keeps its line count
(17 lines out, 17 in, over 5 files), so no line citation into these
files moves. Every one of the 17 changed lines carried a dead citation;
there is no reflow line. No code token moves (see the guard below).

**No citation number is added.** The one tracker number on an added
line, `#10677`, was already on the line it replaces (`index.ts:234`) and
resolves. Over the whole diff, added minus removed is 0 for `#10677` and
negative for the five dead numbers, and no number is new to the diff. No
PR number is the citation on an added line: the three `PR #N` spellings
in scope became their pull request's squash commit.

4 dead sites are left on purpose, all of them `describe` titles (see the
list below).

One more file: a `patch` changeset for `@objectstack/service-package`,
because one rewritten docblock ships (see Changeset below).

## Census: `service-package`, 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-package/`. Each run counts as a reading only
because its board frontier equals the newest issue number, read by a
separate request just before and just after the run.

| reading | tree | board | whole-repo `allocated-but-absent` |
service-package sites | lines | files | numbers |
|---|---|---|---|---|---|---|---|
| before | base `4dfff176b`, run 2026-09-30T00:41:15Z to 00:44:24Z |
enumerated, 186 pages, frontier #20741 (newest #20741 before and after),
18,568 numbers | 1,082 | **13** | 12 | 1 | 4 |
| after | head `34ba921e6`, run 00:49:33Z to 00:52:49Z | enumerated, 186
pages, frontier #20741 (newest #20741 before and after), 18,568 numbers
| 1,069 | **0** | 0 | 0 | 0 |

The before count matches the seat's census and A1 (13 sites). The
whole-repo drop is 13, exactly this diff's census sites. The `resolves`
tally is 33,003 in both runs, and `resolves-as-pull-request` (1,984) and
`cross-repo-unjudged` (995) did not move either. The after run was taken
on `34ba921e6`; the head `ffd2f1ed2` adds only the changeset. No run was
truncated or discarded: both enumerations read 186 pages at the newest
frontier.

**Supplementary instrument, the whole scope.** The census does not read
test files or strings, and this stage's scope includes test comments. 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-package/src` (6 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 that census judged it on this
board anywhere (its `--list` extraction, 37,065 rows) and did not report
it. The one number the census never saw, because it stands only in test
files here, was read on its own: `#16650` answers 404 on the issues
endpoint and on the pulls endpoint.

| reading | citations | dead | src comment | test comment | src string |
test string |
|---|---|---|---|---|---|---|
| before, `4dfff176b` | 82 | **22** | 13 | 5 | 0 | 4 |
| after, `34ba921e6` | 64 | **4** | 0 | 0 | 0 | 4 |

Its src-comment column equals the census's 13, which is the control on
the second instrument. The 60 live citations are the same in both
readings (no cross-repo citation stands in this package), and the drop
of 18 citations is exactly the rewritten sites. A third, raw reading
(every `#` followed by 2 to 6 digits, whatever surrounds it) finds 82
occurrences and 22 dead before, 64 and 4 after: the same as the gate's
grammar, so nothing here sits beyond it, and it has no unjudged token.

## Per-number table

Sites and files count every dead occurrence in scope at the base
(comments and strings, tests included). `rewritten / left` counts the
sites rewritten and the sites left. Each anchor was read in its message
and diff, not only its subject, and `git blame` at the base puts every
rewritten line in its anchor commit or in a later commit that descends
from it (`merge-base --is-ancestor` exit 0 for all 17 line and anchor
pairs).

| number | sites / files | rewritten / left | anchor: what it decided |
|---|---|---|---|
| `#10965` | 17/3 | 13/4 | `ab47f6974` (PR #11064): `get()` and `list()`
refuse a storage seam that accepted the query and returned no result
set, with a declared ADR-0112 envelope (`SERVICE_UNAVAILABLE` / 503),
and the skipped boot rehydration is logged at warn; a seam that answers
with zero rows is unchanged. Its body says `Part of #10965` three times,
and it is the only commit that wrote the seam guard (`git log -S
packageSeamUnreadableError`). The `runtime` stage's anchor for the same
number |
| `#10788` | 1/1 | 1/0 | `3a7ec2d3b`: `os migrate duplicates` holds a
raw-SQL seam that cannot answer to be absent, not empty. The squash
commit of the pull request that was `#10788` (404 on the pulls endpoint
too); `#10677`, the card it answers, stays beside it. New to the sweep |
| `#10789` | 1/1 | 1/0 | `38bc74ed1`: `backfillSeedTenancy`'s read
probes hold a seam that cannot answer to be absent, not empty. Its
subject names `#10789`. The `runtime` stage's anchor for the same number
|
| `#10964` | 1/1 | 1/0 | `38bc74ed1`: the same commit, the squash commit
of the pull request that was `#10964` (404 on the pulls endpoint too),
so the pair `#10789 / PR #10964` became one sha |
| `#16650` | 2/2 | 2/0 | `001a83b04`: `SqlDriver.execute()` declares a
backend refusal as `DATABASE_ERROR` / 500. The squash commit of the pull
request that was `#16650`; its review round (「pin the package-door code
flip」) wrote the two `[#16019]` blocks whose closing sentence these
lines are. The `rest` stage's anchor for the same sentence in
`package-door-16019-raw-statement-fault-code.test.ts` |

Every cited sha matches exactly one commit (`git rev-parse
--disambiguate`, count 1 for each of the 4), and every one is an
ancestor of the base (`merge-base --is-ancestor`, exit 0 for all 4;
control leg: stage 1's landing `422db788a` exit 0; the history is
complete, `--is-shallow-repository` false, 15,149 commits). Each of the
5 numbers answers 404 on the issues endpoint and on the pulls endpoint.

## Wordings to check

- **Bracket tags.** `[#10965]` became `[commit ab47f69]` on 9 lines of
`index.ts` (`:208`, `:286`, `:304`, `:327`, `:451`, `:476`, `:502`,
`:517`, `:626`).
- **`index.ts:223`**, a section heading: 「(#10965)」 became 「(commit
ab47f69)」, and its trailing rule was shortened from 11 characters to 2
so the line stays near its old width.
- **`index.ts:234-235`**, the two siblings of the seam guard: 「(#10677 /
PR #10788 for / `os migrate duplicates`, #10789 / PR #10964 for
`backfillSeedTenancy`)」 became 「(#10677 / commit 3a7ec2d for / `os
migrate duplicates`, commit 38bc74e for `backfillSeedTenancy`)」. The
live `#10677` stays beside its fix; the dead issue and its dead pull
request became their one squash commit.
- **`mysql2-tuple.test.ts:26` and `:196`.** 「#10965's guard」 and
「(#10965's leg」 became 「commit ab47f69's guard」 and 「(commit
ab47f69's leg」.
- **`null-seam.test.ts:4`**, the file's title line: 「#10965 — `get()` /
`list()` answered over a driver they never queried.」 became 「The card
behind commit ab47f69 — …」, so line 8's 「The card established the
conflation by READING」 keeps its referent.
- **`delete-driver-fault.test.ts:319` and
`publish-driver-fault.test.ts:357`.** 「The reviewer of PR #16650
required the flip」 became 「The reviewer of commit 001a83b required the
flip」, the `rest` stage's form for the same sentence.

## The 4 sites left

- **Test strings, 4 sites**, all `#10965`, all `describe` titles in
`null-seam.test.ts` (`:140`, `:184`, `:229`, `:284`), left as stages 1
to 9 left theirs.
- No source string, operator log string, assertion message, quoted
maintainer ruling or generated file in this package carries a dead
number.

## Mechanical guard: no code token moves

The guard compares the TypeScript parser's leaf nodes (a `forEachChild`
walk, so comments are trivia and JSDoc nodes are never visited), base
`4dfff176b` against head. String and template literals are therefore
read in full. It ran over all 5 touched `.ts` files.

- Real run: 3,323 base leaf tokens, **0 files with a token change**
(exit 0).
- Comment control in `index.ts` (「Is this the seam refusal above?」 to 「…
named above?」): 0 files changed, as expected (exit 0).
- Positive control, a code token added in `index.ts`
(`isResultSet(result)` given `as any` in `get()`): DIFFER (exit 1).
- Positive control, one digit changed inside a kept test title
(`null-seam.test.ts:140`, `#10965` to `#10966`): DIFFER (exit 1).

Every mutation went through `scripts/ablation-replace.mjs`, and each
landed (anchor 1 to 0, blob changed). Each restore was proven
byte-identical to the HEAD blob (`2555410dd0a7`, `0c5bf5e7e190`), with
`git diff HEAD` empty and a clean tree afterwards.

## Changeset

This change ships bytes, so a `patch` changeset for
`@objectstack/service-package`
(`.changeset/20596-service-package-provenance-anchors.md`) is included.
Its body is stage 9's, word for word, with the package name changed.

Measured on the built package (A3): `files[]` is `dist`, `README.md` and
`CHANGELOG.md`. After the build, `ab47f6974` appears once in each of
`dist/index.d.ts` and `dist/index.d.cts`: the rewritten docblock sits on
the exported `PACKAGE_SEAM_UNREADABLE_MESSAGE`. The other rewritten
comments do not reach `dist` (0 for `3a7ec2d3b`, `38bc74ed1` and
`001a83b04`, and 0 for `ab47f6974` in `index.js` and `index.cjs`).
Positive control: the unchanged line 「Like {@link
PACKAGE_PUBLISH_DRIVER_FAULT_MESSAGE}, a CONSTANT that」, in the same
docblock, is found once in each declaration file. A never-written
negative phrase appears nowhere in `dist`. None of the 5 dead numbers is
left in `dist`.

## Gates (head `ffd2f1ed2`)

- **Citation judging, as CI runs it:** `pnpm check:issue-citations`
(self-test, 114 cases, 8 batteries) exits 0. `node
scripts/check-issue-citations.mjs` exits 0: the diff-scoped run judged 1
citation in 1 file and found it on the board: `#10677`, which already
stood on its line.
- **Doc authoring:** `pnpm check:doc-authoring` exits 0; the
sibling-package prose-id baseline holds (808 pinned sites, no growth).
- **Derived gates:** `node scripts/pm/dispatch-gates.mjs --commands
--repo objectstack-ai/objectstack` at `ffd2f1ed2` derived 62 commands:
all 56 derived at dispatch, plus `check:engine-double-contract`,
`check:objectql-double-limit`, `check:query-options-erasure`,
`check:type-check-coverage`, `check:type-check-debt` and
`check:where-matcher`. Each ran with its exit code captured before any
pipe, and all 62 exit 0. `--ran`, fed each command with its exit code,
reports 62 run, 0 NOT MEASURED (a derived zero), 0 unrun, and exits 0. A
full `turbo run build` of `./packages/*` and `./packages/*/*` ran first
under the shared verify lock (71 of 71 tasks, exit 0), so no gate hit an
unbuilt workspace.
- **Roster families the derivation lists outside its commands** (their
rosters sit in directories this diff touches): `node
scripts/check-changeset-fixed.mjs`, `pnpm check:authz-resolver`, `pnpm
check:error-code-casing` and `pnpm check:filter-alias-parity`, each exit
0.
- **Tests and typecheck, under the verify lock:**
- `pnpm --filter @objectstack/service-package test`: 5 files pass and 79
tests pass. `vitest list --filesOnly` names 5 files, all the tracked
test files, the 4 touched ones included.
- `pnpm --filter @objectstack/service-package typecheck` exits 0. `tsc
--listFiles` holds all 6 files under `src/`, all 5 touched files
included.
- **Lint, as a proven narrowing:** `eslint --no-inline-config --format
json` over the 5 touched `.ts` files gives 5 files, 0 errors and 0
warnings. All 5 are in eslint's own population (`isPathIgnored` is false
for each; a `dist` file, as the control, is 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 6 changed files for control bytes finds none.

## Acceptance notes

- **The gate-invisible spellings, grepped as the claim asked.**
`CITATION_RE` refuses a hyphen after the digits and a `/` before the `#`
(#20636), and `NON_CITATION_HEADS` excuses a number after the word
「option」. In this package: `#N-word` none, `#A/#B` none, `option #N`
none, at the base and at the head. The raw scan agrees: nothing sits
beyond the gate's grammar here.
- **「This card」 phrases are left.** 14 comment lines in 5 files of this
package speak of 「this card」, 「the card」 or 「The card」. They carry no
number and neither instrument sees them. One title line was worded so
that its neighbour keeps a referent (`null-seam.test.ts:4`, above); the
rest are unchanged, as in stages 8 and 9.
- **The census instrument did not truncate in this stage.** Both
enumerations read 186 pages at the newest frontier.
- **Anchors the next stages can reuse**, each checked here: `#10788` →
`3a7ec2d3b`; `#10964` → `38bc74ed1`. The other three reuse sibling
stages' anchors: `#10965` → `ab47f6974` and `#10789` → `38bc74ed1` (the
`runtime` stage), `#16650` → `001a83b04` (the `rest` stage).
- **Base.** The branch is on `main` at `4dfff176b`. `main` has since
moved four commits (`03cdb9a5c`, `b785c3b11`, `5a23096ca`, `01e78dcee`).
Their 40 files touch nothing under `service-package`, nor
`scripts/check-issue-citations.mjs` or `.changeset/config.json`; the
`doc-authoring-prose-id` baseline they shrink has no `service-package`
row. So no merge was taken; the merge queue rebuilds on the merged
generation.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01XY5uCwTjZj7884yYtyur4H)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/20596-service-package-provenance-anchors.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/service-package': patch
+---
+
+Provenance comments in `service-package` were re-anchored
+
+Comment and docblock lines under `src/` that cited tracker numbers which no
+longer resolve on GitHub now cite the commit in this repository's history that
+decided the matter, and say in their own words what was decided. Comments
+only: no type, schema, export, log or refusal text, or runtime behaviour changes.

packages/services/service-package/src/delete-driver-fault.test.ts

@@ -316,7 +316,7 @@ describe('[#8275] a throw that DECLARES an envelope is re-thrown, not swallowed'
  * an accident the `{code}`-only fakes above cannot see.
  *
  * ⛔ Not a re-judgement of `declaresHttpAnswer`: its docblock already says a
- * declared 5xx is re-thrown too. The reviewer of PR #16650 required the flip
+ * declared 5xx is re-thrown too. The reviewer of commit 001a83b04 required the flip
  * to be pinned, not the predicate to be changed.
  */
 describe('[#16019] a raw-statement fault that DECLARES its status is re-thrown, where its undeclared ancestor was swallowed', () => {

packages/services/service-package/src/index.ts

@@ -205,7 +205,7 @@ function declaresHttpAnswer(error: unknown): boolean {
  * the SAME row, so the next divergence is a red test rather than prose someone
  * has to re-read.
  *
- * ⚠️ [#10965] It returns `[]` for EVERYTHING else too, and that is the whole
+ * ⚠️ [commit ab47f6974] It returns `[]` for EVERYTHING else too, and that is the whole
  * defect this file's seam guard exists for — see {@link isResultSet}. Flatten
  * with this only AFTER the result has been established as an answer.
  */
@@ -220,7 +220,7 @@ function normalizeRows(result: any): any[] {
 }
 
 /**
- * ── The seam that ACCEPTS a query but never ANSWERS one (#10965) ───────────
+ * ── The seam that ACCEPTS a query but never ANSWERS one (commit ab47f6974) ──
  *
  * {@link normalizeRows} flattens the result-set shapes a raw SELECT comes back
  * as. A seam can hand back one more thing, and it means something else
@@ -231,8 +231,8 @@ function normalizeRows(result: any): any[] {
  * — which is also what a real driver returns for a SELECT that matched nothing.
  *
  * Both read paths in this service then reported that emptiness as a fact about
- * the data, and unlike its two siblings (#10677 / PR #10788 for
- * `os migrate duplicates`, #10789 / PR #10964 for `backfillSeedTenancy`) what
+ * the data, and unlike its two siblings (#10677 / commit 3a7ec2d3b for
+ * `os migrate duplicates`, commit 38bc74ed1 for `backfillSeedTenancy`) what
  * they hand back is a PRODUCT ANSWER a caller acts on:
  *
  *   - `get()` returned `null` ⇒ "this package is not installed".
@@ -283,7 +283,7 @@ function isResultSet(result: unknown): boolean {
 }
 
 /**
- * [#10965] The caller-facing sentence a read over a non-answering seam gets.
+ * [commit ab47f6974] The caller-facing sentence a read over a non-answering seam gets.
  *
  * Like {@link PACKAGE_PUBLISH_DRIVER_FAULT_MESSAGE}, a CONSTANT that
  * interpolates nothing: no driver text, no statement, no table name. It says
@@ -301,7 +301,7 @@ export const PACKAGE_SEAM_UNREADABLE_MESSAGE =
 const SEAM_UNREADABLE = Symbol.for('objectstack.service-package.seam-unreadable');
 
 /**
- * [#10965] The refusal a read raises when the seam did not answer.
+ * [commit ab47f6974] The refusal a read raises when the seam did not answer.
  *
  * ADR-0112 envelope: a `status` AND a `code`, both declared, so it leaves by
  * the door's shared `errorFromThrown` mapping as the producer's own answer
@@ -324,7 +324,7 @@ function packageSeamUnreadableError(): Error {
 }
 
 /**
- * [#10965] Is this the seam refusal above?
+ * [commit ab47f6974] Is this the seam refusal above?
  *
  * ⛔ Deliberately NOT {@link declaresHttpAnswer}. That predicate asks the much
  * broader "did this throw declare an envelope?", and widening the two READ
@@ -448,7 +448,7 @@ export class PackageServicePlugin implements Plugin {
           const args = version === 'latest' ? [packageId] : [packageId, version];
           const result = await objectql.execute!({ sql, args });
 
-          // [#10965] Before reading emptiness as a fact, establish that there
+          // [commit ab47f6974] Before reading emptiness as a fact, establish that there
           // was an answer to read. A seam that did not run the SELECT hands
           // back no result set, and `normalizeRows` maps that to `[]` — the
           // same value a real driver returns when the package genuinely is not
@@ -473,7 +473,7 @@ export class PackageServicePlugin implements Plugin {
             updated_at: row.updated_at,
           };
         } catch (error) {
-          // [#10965] The seam refusal is the ONE throw this catch must not
+          // [commit ab47f6974] The seam refusal is the ONE throw this catch must not
           // swallow: swallowing it would restore the exact `null` the refusal
           // exists to replace, and the caller would be back to reading "not
           // installed" off a query that never ran. Everything else keeps the
@@ -499,7 +499,7 @@ export class PackageServicePlugin implements Plugin {
             `,
           });
 
-          // [#10965] Same separation as `get()`: a seam that never ran this
+          // [commit ab47f6974] Same separation as `get()`: a seam that never ran this
           // SELECT must not be reported as "no packages are installed". An
           // answering seam with zero rows still returns `[]` below.
           if (!isResultSet(result)) throw packageSeamUnreadableError();
@@ -514,7 +514,7 @@ export class PackageServicePlugin implements Plugin {
             updated_at: row.updated_at,
           }));
         } catch (error) {
-          // [#10965] As in `get()`: only the seam refusal escapes, because
+          // [commit ab47f6974] As in `get()`: only the seam refusal escapes, because
           // swallowing it would answer "nothing installed" over a driver this
           // method never queried.
           if (isSeamUnreadable(error)) {
@@ -623,7 +623,7 @@ export class PackageServicePlugin implements Plugin {
         }
       }
     } catch (error) {
-      // [#10965] The measured consequence of the conflation, and the half that
+      // [commit ab47f6974] The measured consequence of the conflation, and the half that
       // made it invisible. `list()` used to answer `[]` over a seam that never
       // ran the SELECT, so this loop iterated zero times and said nothing —
       // its only log sits behind `hydrated > 0`. A durable package was then

packages/services/service-package/src/mysql2-tuple.test.ts

@@ -23,7 +23,7 @@
  * ## What the defect did
  *
  * The tuple is an ARRAY, so it satisfied both the old `Array.isArray(result)`
- * branch and `isResultSet` — no false 503, and #10965's guard was never at
+ * branch and `isResultSet` — no false 503, and commit ab47f6974's guard was never at
  * fault. `normalizeRows` simply returned the 2-element tuple, so:
  *
  *   - `get()`  read `rows[0]` — the row ARRAY, not a row. `row.manifest` was
@@ -193,7 +193,7 @@ describe('#11062 the tuple test cannot swallow a bare row array', () => {
 
 describe('#11062 empty results remain "no rows", never a refusal', () => {
   /**
-   * The half that stops this being a rename (#10965's leg, re-asserted for the
+   * The half that stops this being a rename (commit ab47f6974's leg, re-asserted for the
    * shape this card adds): an empty result set in ANY spelling is still a
    * result set, so it answers "not installed" / "nothing installed" rather than
    * raising the seam refusal.

packages/services/service-package/src/null-seam.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * #10965 — `get()` / `list()` answered over a driver they never queried.
+ * The card behind commit ab47f6974 — `get()` / `list()` answered over a driver they never queried.
  *
  * ## What was measured before the fix
  *

packages/services/service-package/src/publish-driver-fault.test.ts

@@ -354,7 +354,7 @@ describe('[#8131] the caller-facing sentence interpolates nothing', () => {
  * an accident the `{code}`-only fakes above cannot see.
  *
  * ⛔ Not a re-judgement of `declaresHttpAnswer`: its docblock already says a
- * declared 5xx is re-thrown too. The reviewer of PR #16650 required the flip
+ * declared 5xx is re-thrown too. The reviewer of commit 001a83b04 required the flip
  * to be pinned, not the predicate to be changed.
  */
 describe('[#16019] a raw-statement fault that DECLARES its status is re-thrown, where its undeclared ancestor was swallowed', () => {