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

Part of #20596
Clause-②: no

## What changed

This is the fifteenth stage of the `domain:services` lane of the
dead-citation sweep. It covers
`packages/services/service-settings/src/**` and nothing else. By the
seat's claim (`5908460751`), it is the largest package left in the lane.
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 14 (the latest is PR
#20816, landed as `73155fedc`). That is **11 sites on 11 lines in 9
files, covering 4 numbers**:

- 4 census sites (every census site this package has at the base);
- 7 sites in test comments, which the census defers. One of their
numbers, `#11318`, stands only in test files here; it was read on its
own and answers 404.

Each rewritten line now cites the commit in this repository that decided
what the line describes, and says in its own words what was decided: **4
distinct commit shas**. No ADR records any of the four decisions (see
the per-number table), so ruling C's commit rung applies. No number was
dropped.

Only comments changed. Every touched source file keeps its line count
(11 lines out, 11 in, over 9 files), so no line citation into these
files moves. All 11 changed lines carried a dead citation. No code token
moves (see the guard below).

**No citation number is added.** The only tracker number on an added
line is the live `#10251`, once, in
`settings-prebind-read-warning.test.ts:17`. It already stood on that
line, and it now sits beside the sha as the convenience link ruling C
allows: 「(commit 1ec36b7, PR #10251)」. `1ec36b730` is that pull
request's squash commit.

2 dead sites are left on purpose: a test title and a test assertion
message (see the list below).

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

## Census: `service-settings`, 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-settings/`. 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-settings sites | lines | files | numbers |
|---|---|---|---|---|---|---|---|
| before | base `73155fedc`, run 2026-09-30T09:39:38Z to 09:43:17Z |
enumerated, 187 pages, frontier #20830 (newest #20830 before and after)
| 752 | **4** | 4 | 4 | 3 |
| after | head `ac05607d6`, run 10:02:17Z to 10:06:00Z | enumerated, 187
pages, frontier #20834 (newest #20834 before and after) | 748 | **0** |
0 | 0 | 0 |

The whole-repo drop is 4, exactly this diff's census sites. The
`resolves` tally is 33,134 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 4 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, 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-settings/src` (64 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 judged it and the census did not report it. 10 numbers are
covered by neither, because they stand only in test files, or as the
second number of an `#A/#B` pair. Each was read on its own through the
read-only tools. 1 answers 404 (`#11318`, on the issue and the
pull-request endpoint alike); 6 answer as issues; 3 answer as pull
requests (`#7554`, `#10251`, `#5133`). The probe's control: the known
issue `#11352` answers 404 on the pull-request endpoint.

| reading | citations | dead | src comment | test comment | src string |
test string |
|---|---|---|---|---|---|---|
| before, `73155fedc` | 534 | **13** | 4 | 7 | 0 | 2 |
| after, `ac05607d6` | 523 | **2** | 0 | 0 | 0 | 2 |

Its src-comment column equals the census's 4, which is the control on
the second instrument. The 519 live citations and 2 cross-repo citations
are the same in both readings, and the drop of 11 citations is exactly
the rewritten sites. A third, raw reading (every `#` followed by 2 to 6
digits, whatever surrounds it) finds 547 occurrences before and 536
after, the same drop of 11. The 13 tokens beyond the gate's grammar are
the same before and after, and none is dead (see Acceptance notes).

## 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.

| number | sites / files | rewritten / left | anchor: what it decided |
|---|---|---|---|
| `#13279` | 4/4 | 4/0 | `6a180e42d` (PR #13475): `resolveAuthzContext`
raises `AuthzStoreUnavailableError` (`SERVICE_UNAVAILABLE`, 503) when a
permission-store read throws, instead of answering an outage as a caller
with zero capabilities, and each production transport's fail-closed
`catch` re-raises that brand. The settings plugin's
`verifiedContextFromRequest` is one of them. Its message names `#13279`
4 times and its diff 54 times; `git blame` puts
`settings-service-plugin.ts:307` in it, and the other three lines were
written by `ac9376a74` (PR #16580), a descendant, which describes that
re-raise. Stage 6's anchor, reused by the storage, datasource and
analytics stages |
| `#10159` | 3/2 | 3/0 | `1ec36b730` (PR #10251): a settings write
issued before the engine is bound is refused with
`SETTINGS_ENGINE_NOT_BOUND` (503). Its message states that every read in
any state is unchanged, which is the "left reads open" all three lines
describe. The message does not name `#10159`, but its own diff does,
once, in its changeset ("refused loudly instead of resolving
successfully while nothing reaches `sys_setting` (#10159)"), and
`settings-prebind-read-warning.test.ts:17` already paired the two
numbers. `git blame` puts the three lines in `a24b7fa4d` (PR #11044),
the later read-half fix, a descendant. New to the sweep |
| `#17062` | 3/2 | 2/1 | `50b6f17d4` (PR #17071): adds the package-local
route-ledger conformance guard beside the dogfood live-mount parity
gate, and updates the ledger header that had said such a guard was
deliberately omitted. Its message does not name `#17062`; its diff does,
on 3 added lines, which are the three sites here (`git blame` puts all
three in it). New to the sweep |
| `#11318` | 3/1 | 2/1 | `99ccbb9c8` (PR #11467): the Settings, AI "Test
connection" fallback keeps its mount instruction on all three
real-provider branches and gains the cloud-only boundary read from
`PLATFORM_CAPABILITY_PROVIDERS.ai`. Its own changeset states that "the
embedder hint at the fourth site is deliberately left alone ... and
pinned by a contrast test", which is the fence `:339` describes. Its
message's trailer names `#11318` as the issue it answers, its diff names
the number 3 times, and `git blame` puts all three lines in it. New to
the sweep |

Every cited sha matches exactly one commit (`git rev-parse
--disambiguate`, count 1 for each of the 4), and all 4 are ancestors of
the base (`merge-base --is-ancestor`, exit 0 for each; reverse leg, base
against each anchor, exit 1 for each; control legs exit 0: stage 1's
landing `422db788a`, and the repository's root commit, which lies deeper
than every anchor; the history is complete, `--is-shallow-repository`
false, 15,193 commits). Each of the 4 numbers answers 404 on the issues
endpoint, which serves pull requests too, read one by one.

No ADR, `scripts/adr-anchors/` file or other `docs/` page records the
decision of any of the 4: `docs/adr` names none of the numbers, and none
of their mechanisms (`AuthzStoreUnavailableError`,
`SETTINGS_ENGINE_NOT_BOUND`, `engineBindPending`, the settings route
ledger, the AI hint's edition boundary).

## Wordings to check

- **Tag swaps in place.** 「[#13279]」 became 「[commit 6a180e4]」
(`settings-service-plugin.ts:307`); 「(#13279)」 became 「(commit
6a180e4)」 on 2 lines; 「#13279's permission-store re-raise」 became
「commit 6a180e4's permission-store re-raise」. These are the forms the
storage and datasource stages used for the same sha.
- **`#10159`.** 「is why #10159's fix deliberately left reads open」
became 「is why commit 1ec36b7's write refusal deliberately left reads
open」; 「(#10159's fix left reads open on purpose)」 became 「(commit
1ec36b7 left reads open on purpose)」; 「(#10159 / PR #10251)」 became
「(commit 1ec36b7, PR #10251)」, with the pull-request number kept as
the convenience link beside its own squash commit.
- **`#17062`.** 「Two layers, since #17062.」 became 「Two layers, since
commit 50b6f17.」 The docblock goes on to describe the conformance test
that commit added as the second layer.
- **Two headers keep the antecedent of the prose below them**, the form
stage 14 used:
- `settings-route-ledger.conformance.test.ts:4`: 「Settings route-ledger
conformance (#17062)」 became 「Settings route-ledger conformance (the
issue behind commit 50b6f17)」, because `:25` of the same docblock says
「(per the issue)」.
- `manifests/ai.manifest.test.ts:277`: 「#11318 —」 became 「The card
behind commit 99ccbb9:」, because `:288` 「the very claim this card is
about」 and `:329` 「The un-followable form this card retired」 speak of
that card.
- **`ai.manifest.test.ts:339`.** 「deliberately not edited — #11318
fences this site out by name」 became 「... — commit 99ccbb9 fences this
site out by name」. The commit's own changeset names that site (quoted in
the table).

## The 2 sites left

- **Test strings, 2 sites on 2 lines**, left as stages 1 to 14 left
theirs:
  - `manifests/ai.manifest.test.ts:292`, a `describe` title (`#11318`);
- `settings-route-ledger.conformance.test.ts:88`, the assertion message
a failing run prints (`#17062`). It is a string, not a comment, and form
C does not touch strings.
- No 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 shipping `README.md` names only the live `#8026`;
- `vitest.config.ts` names only live numbers (`#8020`, `#8030`, `#8063`,
`#8104`, `#10374`);
  - `tsconfig.json` and `package.json` name none;
- the release-owned `CHANGELOG.md` names `#13279` and `#10159` on 2
lines, the entries of `6a180e4` and `1ec36b7`, which are this PR's
anchors.

## Mechanical guard: no code token moves

The guard compares, base `73155fedc` against head, over all 9 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 final head `ac05607d6`: 9,999 base leaf tokens, **0
files with a token change** on either reading (exit 0). The first commit
`ff7ef46f4` gave the same, and no `.ts` path changed after it.
- Comment control in `settings-service.ts` (「deliberately left reads
open.」 to 「deliberately kept reads open.」): 0 files changed, as expected
(exit 0).
- Positive control, a code token renamed in `settings-service-plugin.ts`
(`isAuthzStoreUnavailableError(err)` to
`isAuthzStoreUnavailableErrorX(err)`): DIFFER on the identifier (exit
1).
- Positive control, one digit changed inside the kept test title
`ai.manifest.test.ts:292` (`#11318` to `#11319`): DIFFER on the string
literal (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 blob (`1248149a428d`, `a2fac9ad1f0b`, `79c2b40a48a6`), with
`git diff HEAD` empty and a clean tree afterwards.

## Changeset

This change ships bytes, so a `patch` changeset for
`@objectstack/service-settings`
(`.changeset/20596-service-settings-provenance-anchors.md`) is included.
Its body is stages 12 and 13's commit-anchor text, word for word, with
the package name changed.

Measured on the built package (A3), after a full workspace build in
which this package was a cache miss (71 of 71 tasks, 0 cached, at
`ff7ef46f4`, which holds every source-line change): `files[]` is `dist`,
`README.md` and `CHANGELOG.md`, and the package is not private.

- The rewritten `settings-service.ts:685` docblock, on the pre-bind read
reporter, is in all four entries: `dist/index.js`, `dist/index.cjs`,
`dist/index.d.ts` and `dist/index.d.cts` (once each).
- The other three rewrites (`settings-route-ledger.ts:17`,
`settings-routes.ts:72`, `settings-service-plugin.ts:307`) are stripped
by the bundle, and the other seven sit in test files.
- Positive controls, the unchanged line beside each rewrite, land
exactly where their neighbours do: the line before
`settings-service.ts:685` once in each of the four entries, and the
neighbours of the three stripped rewrites 0 everywhere.
- A never-written negative phrase appears nowhere in `dist`, and none of
the four old numbers is left there.

The later commit adds only the changeset.

## Gates (final head `ac05607d6`)

- **Citation judging, as CI runs it:** `pnpm check:issue-citations`
exits 0 (self-test, 114 cases, 8 batteries). `node
scripts/check-issue-citations.mjs` exits 0: 「no issue citations added
against 73155fe (4 file(s) read)」.
- **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 `ac05607d6` derived 63 commands,
the same 63 as at dispatch.
- Each ran 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 63 run, 0 NOT
MEASURED (a derived zero), 0 unrun, and exits 0.
- The full `turbo run build` above ran first under the shared verify
lock, 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, at `ac05607d6`:**
- `pnpm --filter @objectstack/service-settings test`: 33 files pass and
584 tests pass, which is every tracked test file under `src/`, the 5
touched ones included.
- `pnpm --filter @objectstack/service-settings typecheck` (`tsc
--noEmit`) exits 0, and `tsc --listFiles` puts all 9 touched files in
the program.
- **Lint, as a proven narrowing:** eslint with inline config disabled,
over the 9 touched `.ts` files, gives 9 files, 0 errors and 0 warnings
(its `--format json` output). All 9 are in eslint's own population (none
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 10 changed files for control bytes finds none.

## Acceptance notes

- **The gate-invisible spellings, grepped as the claim asked** (#20636,
including the `clause #N` position). At the base, `#N-word` is on 0
lines. `#A/#B` is on 11 lines (12 second numbers), and every second
number is live: `#6580`, `#5094`, `#11230`, `#5480`, `#5932`, `#6199`
and `#5204` by the census's own judgement, and `#5133` read on its own
as a pull request. `option #N`, `clause #N` and URL-spelled links are on
0 lines. So the claim's 0 / 11 / 0 / 0 hold, and nothing dead hides
behind them. The one other raw token beyond the grammar is the colour
literal `'#6366f1'` in `manifests/branding.manifest.ts:32`.
- **「The card」 phrases.** 38 lines in 18 files under this package's
`src` speak of 「the card」 or 「this card」. They carry no number, and
neither instrument sees them. The ones whose antecedent this diff would
have removed are handled above; the rest are unchanged, as in stages 8
to 14.
- **The census instrument did not truncate in this stage.** Both
enumerations read 187 pages at the newest frontier.
- **Anchors the next stages can reuse**, each checked here: `#10159` →
`1ec36b730`; `#17062` → `50b6f17d4`; `#11318` → `99ccbb9c8`; and the
reused `#13279` → `6a180e42d`.
- **Base.** The branch is on `main` at `73155fedc`. `main` has since
moved two commits (`4b45afaed`, `15b586dcf`). Neither touches
`packages/services/service-settings`,
`scripts/check-issue-citations.mjs`, `.changeset/config.json` or a path
in this diff. `15b586dcf` moves `packages/spec/liveness/**`, a gate
input this comment-only diff cannot interact with. 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-settings-provenance-anchors.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/service-settings': patch
+---
+
+Provenance comments in `service-settings` 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-settings/src/manifests/ai.manifest.test.ts

@@ -274,7 +274,7 @@ describe('aiSettingsManifest — embedder section', () => {
 });
 
 /**
- * #11318 — the live-call hint an operator reads under "Test connection" in
+ * The card behind commit 99ccbb9c8: the live-call hint an operator reads under "Test connection" in
  * Settings -> AI must carry the edition boundary the platform's own capability
  * roster already records. `PLATFORM_CAPABILITY_PROVIDERS.ai` declares
  * `edition: 'cloud'` ("no installable version in the open edition"), while the
@@ -336,7 +336,7 @@ describe('aiTestActionHandler — live-call hint carries the cloud boundary (#11
   // `@objectstack/embedder-openai`, which IS built in this repo (8 path hits
   // under `git ls-tree -r --name-only HEAD | grep -cF /embedder-openai/`, against
   // 0 for `/service-ai/`), so that instruction is followable as written and stays
-  // a plain mount line. Asserted here, deliberately not edited — #11318 fences
+  // a plain mount line. Asserted here, deliberately not edited — commit 99ccbb9c8 fences
   // this site out by name.
   it('leaves the embedder hint a plain mount line — its package IS built here', async () => {
     const r = await runTestEmbedder({ embedder_provider: 'openai', embedder_api_key: 'sk-test' });

packages/services/service-settings/src/settings-admission-tenancy-posture.test.ts

@@ -614,7 +614,7 @@ describe('#15351 — decision 1 option A: a BROKEN tenancy service is an outage,
     // and not endorsed: the settings route layer had no
     // `isAuthzStoreUnavailableError` arm, so the branded 503 the seam raises
     // was flattened into `500 INTERNAL_ERROR` by the same untyped `else` branch
-    // #13279's permission-store re-raise already reached. All four route
+    // commit 6a180e42d's permission-store re-raise already reached. All four route
     // catches now RELAY the declared envelope instead.
     //
     // What THIS card owns is unchanged and still asserted: the outage is not a

packages/services/service-settings/src/settings-prebind-read-warning.test.ts

@@ -14,7 +14,7 @@
  * specifier's declared `default`, with `source: 'default'` and `locked: false`,
  * and no diagnostic of any kind, while the operator's saved row is never read.
  *
- * The write half (#10159 / PR #10251) could REFUSE, because an in-window write
+ * The write half (commit 1ec36b730, PR #10251) could REFUSE, because an in-window write
  * has no correct outcome. A read does: a setting with genuinely no persisted row
  * must answer the manifest default, and doing so at boot is ordinary. So the
  * fix here is not a refusal — it is that the residual stops being silent.
@@ -299,7 +299,7 @@ describe('a settings read inside the pre-bind window warns', () => {
     expect(reader.engineBoundAtReady).toBe(false);
     // THE DEFECT, still observable: the read answered with the manifest default
     // (`log`) while `sys_setting` held `twilio`. The fix does NOT change this —
-    // that is deliberate (#10159's fix left reads open on purpose) — so this
+    // that is deliberate (commit 1ec36b730 left reads open on purpose) — so this
     // assertion is the reason the warning has to exist at all.
     expect(reader.readAtReady).toBe('resolved:"log"');
 

packages/services/service-settings/src/settings-route-ledger.conformance.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * Settings route-ledger conformance (#17062) — the guard every OTHER
+ * Settings route-ledger conformance (the issue behind commit 50b6f17d4) — the guard every OTHER
  * `*-route-ledger.ts` in the tree pairs with a `*-route-ledger.conformance.test.ts`,
  * missing here since the ledger itself landed at #7526.
  *

packages/services/service-settings/src/settings-route-ledger.ts

@@ -14,7 +14,7 @@
  * asking which rows nobody claims (PENDING-GAPS §E; the gate is
  * `packages/qa/dogfood/test/route-ledger-live-mount-parity.dogfood.test.ts`).
  *
- * WHAT GUARDS IT. Two layers, since #17062. The dogfood parity gate above
+ * WHAT GUARDS IT. Two layers, since commit 50b6f17d4. The dogfood parity gate above
  * checks both directions too — a row here whose route the plugin stops
  * mounting fails it, and any live mount without a row in the union of the
  * ledgers it reads fails it — but only as part of a full boot, in a

packages/services/service-settings/src/settings-routes.authz-outage-relay.test.ts

@@ -9,7 +9,7 @@
  *
  * `SettingsServicePlugin`'s `verifiedContextFromRequest` re-raises
  * `AuthzStoreUnavailableError` rather than returning an enforced-but-empty
- * context the routes would read as a denial (#13279). But it is called as
+ * context the routes would read as a denial (commit 6a180e42d). But it is called as
  * `await ctxOf(req)` from INSIDE each route's own `try`, so the brand was
  * caught here and re-encoded: `message` survived, `code` and `status` did not —
  * and those are the two a client branches on.

packages/services/service-settings/src/settings-routes.ts

@@ -69,7 +69,7 @@ const defaultContext = (_req: IHttpRequest): SettingsContext => ({ enforced: tru
  *
  * `SettingsServicePlugin`'s `verifiedContextFromRequest` already re-raises the
  * brand rather than returning an enforced-but-empty context the routes would
- * read as a denial (#13279). But it is called as `await ctxOf(req)` from INSIDE
+ * read as a denial (commit 6a180e42d). But it is called as `await ctxOf(req)` from INSIDE
  * each route's own `try`, so until now the brand was caught here and re-encoded
  * — `message` survived, `code` and `status` did not, and those are the two a
  * client branches on. The declared `503` / `SERVICE_UNAVAILABLE` never reached

packages/services/service-settings/src/settings-service-plugin.ts

@@ -304,7 +304,7 @@ export class SettingsServicePlugin implements Plugin {
             enforced: true,
           };
         } catch (err) {
-          // [#13279] An unreachable permission store is an outage, not a
+          // [commit 6a180e42d] An unreachable permission store is an outage, not a
           // caller with no permissions — re-raise it rather than returning an
           // enforced-but-empty context the routes read as a denial.
           if (isAuthzStoreUnavailableError(err)) throw err;

packages/services/service-settings/src/settings-service.ts

@@ -682,7 +682,7 @@ export class SettingsService {
    * of a setting that genuinely has no persisted row must answer the manifest
    * `default`, and that is an ordinary, common thing for a boot-time reader to
    * do. Refusing it would turn a correct startup sequence into an error — which
-   * is why #10159's fix deliberately left reads open.
+   * is why commit 1ec36b730's write refusal deliberately left reads open.
    *
    * What is wrong is not the answer, it is that the answer was produced WITHOUT
    * CONSULTING the store. In the window {@link loadRows} takes its `this.memory`