docs(spec): re-anchor the last six dead tracker citations in packages/spec/src to the commits that decided them (#21642)

Part of #20234

Clause-②: no

The next stage of the dead-citation sweep under ruling C+D (record
`5749154545` on #19123): the six comment sites the census pointer
`5923089344` names, claimed in `5973700515`. Each cited a tracker number
that answers 404. Each now cites, in form C, the commit on `main` that
decided the rule, and in every case that is the anchor an earlier stage
of this card already landed for the same number in a sibling site.
Comment text only: no string literal, `.describe()` text, schema, type,
export or test changes.

## The rule applied

Form C, as triage's first grade (`5856637615`) states it and stages 1 to
11 applied it: "the ADR or ruling record, else the commit sha, with a PR
number allowed only beside it as a link", and "Each rewritten line says
what the cited object decided … Where nothing answers, keep the
sentence's reason in words and drop the citation." Stage 10's ACCEPT
(`5902947213`) adds: "Where the number alone carried the meaning, the
decision is also said in words." Live numbers stay (stage 9's ACCEPT
`5899135835`: "its claims forbid removing a lit citation"). A slash
group keeps its live numbers and takes the commit beside them, as stage
5 did for `#9881/#9972` in `component.test.ts` (now `the #9881 / commit
60e0f90 records`).

## What changes (line numbers at base `5b5e83f446`)

| site | dead number | now reads | the same anchor already on `main` |
|:--|:--|:--|:--|
| `data/datasource.zod.ts:701` | `#9040` in `#8082/#8336/#9040` |
`#8082/#8336, or the refusal of a credential in mongo's options
passthrough (commit 2420641)` |
`data/datasource-credential-redaction.ts`, `data/driver/common.zod.ts`
(stage 3) |
| `data/filter.zod.ts:1067` | `@see` URL of `#17590` | `@see commit
e04a0af (the membership reading, landed with the SQL family)` |
`data/filter.zod.ts:979` (stage 3) |
| `data/value-roundtrip-conformance.ts:100` | `@see` URL of `#12380` |
`@see commit 4045b95 (the measured boundary set)` | the same file's
family table and `v_json` paragraph (stage 3) |
| `ui/component.zod.ts:675` | `#6276` in `#5611/#5775/#6276` | `#5611 /
#5775 / commit 78f0be8` | `ui/component.zod.ts:71`, `:207`, `:682`
(stage 5) |
| `ui/component.zod.ts:751` | `#6276` in `#5611/#5775/#6276` | `#5611 /
#5775 / commit 78f0be8` | as above |
| `ui/component.zod.ts:4555` | `#9972` in `#9881/#9972` | `#9881 /
commit 60e0f90` | `ui/component.zod.ts:2609`,
`ui/component.test.ts:407` (stage 5) |

The datasource line is the one site whose sentence did not say what the
dead number decided, so it now says it in words, from the code: the
mongo `options` passthrough refusal is part of the config gate
(`credentialFreeMongoOptions` on `MongoConfigSchema.options`). That
comment reflows from two lines to three. Every other edit is one line
for one line, and each of those sentences already stated its decision in
words.

## Evidence

**The six are dead, measured with the gate's own instrument.** `node
scripts/check-issue-citations.mjs --census --json` (read-only, board
enumerated, 195 pages) at base `5b5e83f446` lists exactly these six plus
the two literal-read sites stage 6 kept on purpose
(`data/api-derivation.ts:163` `[#6259]`, `identity/identity.zod.ts:230`
`#8715`). Lines match the claim. No seventh dead number in
`packages/spec/src`. REST `issues/N`, redirects not followed: `#9040`,
`#17590`, `#12380`, `#6276`, `#9972` answer 404; the lit controls
`#8082`, `#8336`, `#5611`, `#5775`, `#9881`, `#5286`, `#12624` answer
200.

**After, at head `dbacec5f91`:** the same census reads
`allocated-but-absent` 119 → 113 repo-wide and 8 → 2 in
`packages/spec/src`. Gone: exactly the six. New: none.

**Each anchor is on `main` and names its number.** REST
`compare/SHA...5b5e83f` answers `ahead`, `behind_by: 0` for all five
shas (controls: `5b5e83f446~1` answers `ahead`, `behind_by: 0`; the
off-main branch commit `25fb56f1b7` answers `diverged`, `behind_by: 3`).
The local `merge-base --is-ancestor` exits 1 for all five on this
shallow checkout, which is the shallow false negative, so the REST
reading is the one cited. Each commit's own text names the number it
replaces: `24206416a` (subject: refuse a credential in the mongo options
passthrough at publish, `#9040`); `e04a0aff2` (its body names `#17590`
as the card it delivers, and its diff wrote the very `@see` line
rewritten here); `4045b954d` ("Part of #12380", with the live 17-value
measurement across three dialects); `78f0be872` (subject names `#6276`);
`60e0f900a` (subject names `#9972`).

**Comment-only, proved two ways.**
- A parser-driven token comparison (TypeScript parser, leaf tokens off
the syntax tree, JSDoc nodes skipped): base and head token streams are
identical in all four files (2,231 / 6,169 / 1,098 / 16,019 tokens),
with 0 parse diagnostics on either side. Controls, 7 of 7 behave: an
identifier edit, a `.describe()` string edit, a template-literal edit
and a regex-literal edit each report DIFFERS; a line-comment edit, a
JSDoc edit and an `@see`-line edit each report IDENTICAL.
- Every added or removed line in the source diff is a comment line: 15
of 15 (+8 / −7).

**Generated artifacts.** After a spec build, `check:generated` reports
15 of 15 up to date. No reference page renders any of the six comments
(`content/docs/references/` holds neither the old nor the new text).
Nothing was regenerated.

**Changeset: `@objectstack/spec` patch.** Measured after the build:
`datasource.zod.ts`, `filter.zod.ts` and `component.zod.ts` ship
verbatim through the package's `files` entry `src/**/*.zod.ts`; in
`dist`, the three `component.zod.ts` comments are in 14 `.js` / `.mjs`
bundles and the `value-roundtrip-conformance.ts` `@see` is in
`dist/data/index.d.ts` and `.d.mts`. The datasource and filter comments
reach no `dist` file. Positive control: the `maxVisible` `.describe()`
text is in 14 `dist` files. So the change publishes text, and
`skip-changeset` does not apply.

**Tests and gates, at head `dbacec5f91`.**
- `pnpm --filter @objectstack/spec build`: exit 0. Spec `local` vitest:
609 files, 18,057 passed, 1 todo. `pnpm --filter @objectstack/spec
typecheck`: exit 0.
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 79 families; `--ran` reconciles 78
run, all exit 0, and 1 NOT MEASURED, 0 unrun.
- NOT MEASURED: `check:dual-build-cjs-loads`, reason: it refuses (exit
3) until every publishable package is built, and a full monorepo build
was not run locally. Narrowed and declared: the diff is comment-only in
`packages/spec`, and of the gate's 106 `require` entries (its own
`--list`), spec's 19 all load at head. CI runs the full gate.
- Two gates first refused for unbuilt prerequisites (`@objectstack/lint`
`check:doc-formula-expressions`, `check:lean-entry-closure`). After
building `formula`, `lint` and `objectql` (14 of 14 turbo tasks), both
exit 0.

**Overlap.** Open PR #21632 and PR #21625 touch `ui/component.zod.ts` in
other regions. Neither had landed at `origin/main` `36e4647520`,
re-fetched before this PR opened, so no merge was taken. A `merge-tree`
of this head onto that tip exits 0, and none of the five changed paths
is routed to the regeneration merge driver, so the local answer is
GitHub's.

## Acceptance notes

- `docs/audits/2026-07-unknown-key-strictness-ledger.md:676` still names
the `#5611/#5775/#6276` rule. It is outside this stage's file surface
and outside the census surface. Carrier: none.
- For `#17590` the commit rung was taken, although `e04a0aff2`'s message
names a director-seat ruling record. That matches stage 3's anchor for
the same number at `filter.zod.ts:979`, reviewed PASS.
- Not governed: no path under `docs/adr/`, `.claude/`, `skills/`,
`AGENTS.md` or `CLAUDE.md`. 29 changed lines.

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

---------

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

Author: objectstack-fleet[bot]

.changeset/spec-last-six-dead-citation-anchors.md

@@ -0,0 +1,14 @@
+---
+'@objectstack/spec': patch
+---
+
+Six provenance comments in `src/data/` and `src/ui/` were re-anchored
+
+Clause-②: no
+
+Six comment and docblock lines in `src/data/datasource.zod.ts`, `src/data/filter.zod.ts`,
+`src/data/value-roundtrip-conformance.ts` and `src/ui/component.zod.ts` cited tracker numbers
+that no longer resolve on GitHub. Each now cites the commit in this repository's history that
+decided the matter, and the datasource comment also says in words which refusal it means: a
+credential written into mongo's `options` passthrough. The live numbers beside them stay.
+Comments only: no type, schema, export or runtime behaviour changes.

packages/spec/src/data/datasource.zod.ts

@@ -698,8 +698,9 @@ export const DatasourceSchema = lazySchema(() => strictObject(
   // `MongoConfigSchema` (a config-level refinement sees only `config`;
   // `credentialsRef` sits on the datasource), so both run here, where both
   // halves are visible at once. They compose independently with the config
-  // gate above: a config also violating #8082/#8336/#9040 reports those
-  // issues too, each at its own path.
+  // gate above: a config also violating #8082/#8336, or the refusal of a
+  // credential in mongo's `options` passthrough (commit 24206416a), reports
+  // those issues too, each at its own path.
   //
   // The two arms split on the connect path's OWN branch test, not on key
   // presence: `buildMongoUrl` opens `if (explicit) return explicit;`, so a

packages/spec/src/data/filter.zod.ts

@@ -1064,7 +1064,7 @@ export const RangeOperatorSchema = lazySchema(() => z.object({
  * @see https://github.com/objectstack-ai/objectstack/issues/4706 (the ruling)
  * @see https://github.com/objectstack-ai/objectstack/issues/5702 (the SQL family — landed)
  * @see https://github.com/objectstack-ai/objectstack/issues/6520 (the JS faces — landed)
- * @see https://github.com/objectstack-ai/objectstack/issues/17590 (the membership reading — the SQL family landed)
+ * @see commit e04a0aff2 (the membership reading, landed with the SQL family)
  * @see https://github.com/objectstack-ai/objectstack/issues/7398 (the refusal whose prescription this spelling is)
  */
 /**

packages/spec/src/data/value-roundtrip-conformance.ts

@@ -97,7 +97,7 @@
  * belongs in this table and the case that proves it belongs in this file.
  *
  * @see https://github.com/objectstack-ai/objectstack/issues/12393 (this table)
- * @see https://github.com/objectstack-ai/objectstack/issues/12380 (the measured boundary set)
+ * @see commit 4045b954d (the measured boundary set)
  * @see https://github.com/objectstack-ai/objectstack/issues/9276 (the value class deliberately excluded)
  */
 

packages/spec/src/ui/component.zod.ts

@@ -672,7 +672,7 @@ export const PageHeaderProps = strictObject({
    * How many header actions render as inline buttons before the rest fold into
    * the overflow menu — desktop and mobile budgets (#4001 batch A).
    *
-   * Declared on the #5611/#5775/#6276 rule, for the same reason and by the same
+   * Declared on the #5611 / #5775 / commit 78f0be872 rule, for the same reason and by the same
    * evidence: the renderer has always read them and the schema had not caught
    * up. `containers.tsx:1358` resolves
    * `schema?.maxVisible ?? schema?.properties?.maxVisible` (and the `mobile*`
@@ -748,7 +748,7 @@ export const PageTabsProps = strictObject({
    * comment invites the override: *"Authors who want the strip even at length 1
    * can pass `properties.alwaysShowStrip: true`"* (`containers.tsx:637`, read as
    * `schema?.properties?.alwaysShowStrip === true`). Declared on the same
-   * #5611/#5775/#6276 rule as `page:header`'s action budget: the delivered,
+   * #5611 / #5775 / commit 78f0be872 rule as `page:header`'s action budget: the delivered,
    * invited shape is the contract, and a closed schema that rejected it would
    * be the declaration disagreeing with the renderer in the direction that
    * costs the author.
@@ -4636,7 +4636,7 @@ export const ObjectMetricPropsSchema = lazySchema(() => strictObject({
    * equally true of `page:header`'s `icon`, which is REFUSED precisely because
    * no render path reads it. Vocabulary does not separate the two verdicts; a
    * read point does (#9397 closed premise-overtaken re-deriving one from
-   * scratch; #9881/#9972 recorded the accordion and tab items). This is the
+   * scratch; #9881 / commit 60e0f900a recorded the accordion and tab items). This is the
    * same record for the metric tile.
    *
    * The key is LIVE at the objectui pin this repo builds against