docs(spec): re-anchor the dead tracker citations in packages/spec/src's test surface to the commits that decided them

.changeset/spec-test-surface-dead-citation-anchors.md

@@ -0,0 +1,16 @@
+---
+'@objectstack/spec': patch
+---
+
+Two provenance comments that tests read literally were re-anchored
+
+Clause-②: no
+
+The removal note on `DATA_ACTION_TO_API_OPERATION` in `src/data/api-derivation.ts` and the
+explanatory block about `ApiKeySchema` in `src/identity/identity.zod.ts` cited tracker numbers
+that no longer resolve on GitHub. Each now opens with the commit in this repository's history
+that decided the matter: 6968885ef removed the producer-less `batch: 'bulk'` alias row, and
+2c86fe3ea deleted `ApiKeySchema` on the maintainer's ruling. The unit tests that read those two
+comments moved with them, and the same re-anchoring was applied to the comments in the
+package's test files, which do not ship. Comments only: no type, schema, export or runtime
+behaviour changes.

packages/spec/src/api/export-job-family-retirement.test.ts

@@ -21,8 +21,8 @@ import { MIGRATIONS_BY_MAJOR, RETIRED_DEFS_BY_MAJOR } from '../migrations/regist
 // (`contracts/export-service.ts`) and `ScheduleExportInput` leave the public
 // surface, and `ScheduleState` (`automation/execution.zod.ts`) goes with them
 // unless a live consumer is measured. Landing route A (decision batch #221
-// item 2): objectui retired its side first (objectui#10247, merged as objectui
-// PR #10264), and the pinned `.objectui-sha` already descends from that merge.
+// item 2): objectui retired its side first (objectui#10247, merged as
+// objectui PR #10264), and the pinned `.objectui-sha` already descends from that merge.
 // Scope note: the export-job LIST pair (`ListExportJobsRequestSchema` with its
 // `limit` / `cursor`, and its response) is in, absorbing #19543 door ②; the
 // import-job family in the same module is served and is NOT in.

packages/spec/src/api/protocol.test.ts

@@ -1805,7 +1805,7 @@ describe('PublishMetaItemRequestSchema mirrors the implementation parameter type
   // `@objectstack/metadata-protocol` — `{ type, name, organizationId?,
   // actor?, message?, packageId? }` — and the REST door's actual reads;
   // nothing else is declared because nothing else is enforced.
-  // As in the #9726/#9741 blocks above, accept-pins assert the parsed VALUE:
+  // As in the #9726 / commit 2a29caa53 blocks above, accept-pins assert the parsed VALUE:
   // this is a non-strict object, so `success` alone is exactly the
   // silent-strip state this family of cards closes.
 
@@ -1935,9 +1935,9 @@ describe('AuditMetaItemRequestSchema mirrors the implementation parameter type (
   // implementation's parameter type in `@objectstack/metadata-protocol` —
   // `{ type, name, organizationId?: string | null, limit?: number }` — and the
   // REST door's actual sends; nothing else is declared because nothing else is
-  // enforced. As in the #9726/#9741/#11006 blocks above, accept-pins assert
-  // the parsed VALUE: this is a non-strict object, so `success` alone is
-  // exactly the silent-strip state this family of cards closes.
+  // enforced. As in the #9726 / commit 2a29caa53 / commit cccbe51bf blocks above,
+  // accept-pins assert the parsed VALUE: this is a non-strict object, so
+  // `success` alone is exactly the silent-strip state this family of cards closes.
 
   const base = { type: 'view', name: 'account_list' } as const;
 

packages/spec/src/api/rest-api-config-dead-keys-retirement.test.ts

@@ -249,8 +249,8 @@ describe('rest_api retirement — ADR-0087 registration', () => {
     expect(entry!.surface).toBe('restServer.api.responseFormat / restServer.api.documentation.enabled');
     expect(entry!.replacement).toContain('`api.enableOpenApi`');
     // Plugin TS configuration has no stored or stack source for a conversion to
-    // rewrite — the #14691 / `openApi31` shape. A conversion id naming either
-    // key would be a strip with nothing to strip.
+    // rewrite — the `RestServerConfig` retirement (commit b3a63d32c) / `openApi31`
+    // shape. A conversion id naming either key would be a strip with nothing to strip.
     expect(step.conversionIds.filter((id) => /response-format|documentation-enabled/.test(id))).toEqual([]);
   });
 

packages/spec/src/automation/control-flow.test.ts

@@ -412,7 +412,7 @@ describe('TryCatchErrorValueSchema', () => {
     expect(TryCatchErrorValueSchema.safeParse({ nodeId: 'guard', message: 'x', iteration: 1.5 }).success).toBe(false);
   });
 
-  // #14954 — `code` (#14419): the engine binds the failing node's
+  // #14954 — `code` (commit c5a7448d5): the engine binds the failing node's
   // platform-classified error code beside `nodeId` / `message`, so a catch
   // region can DISCRIMINATE ("the row is already there" vs "the store is
   // down") by branching on `$error.code` instead of parsing `message`. This

packages/spec/src/automation/schedule-organization.test.ts

@@ -8,7 +8,7 @@ import {
   resolveScheduleOrganization,
 } from './schedule-organization.zod';
 
-// [#16659] The declaration side of the acting-organization ruling. Two
+// [commit ecdfc9411] The declaration side of the acting-organization ruling. Two
 // consumers read this module and they must not be able to disagree about what
 // counts as DECLARED: the automation engine lifts the value onto the trigger
 // binding (`resolveTriggerBinding`), and both time triggers refuse a binding

packages/spec/src/automation/sync-retirement.test.ts

@@ -217,7 +217,7 @@ describe('[#4738] sync/conflict dual-source retirement', () => {
     }
     // Anti-vacuity: the ui namespace we just probed is real and non-trivial —
     // otherwise a broken import would satisfy the three absences above.
-    // (`ThemeSchema` was the probe until #10485 retired it — ADR-0049.)
+    // (`ThemeSchema` was the probe until commit 35ad101bc retired it — ADR-0049.)
     expect('PageSchema' in ui).toBe(true);
   });
 

packages/spec/src/automation/webhook.test.ts

@@ -276,10 +276,10 @@ describe('unknown keys are rejected, not stripped (#4001 batch 11)', () => {
   });
 
   /**
-   * [#6362] The measurement that card asked for, kept as a pin.
+   * [commit b5404f496] The measurement that commit took in the same pass, kept as a pin.
    *
-   * #6362 fixed `connector`, which TOLERATED the stamped envelope and then
-   * stripped it — success with silent data loss — and asked whether `webhook`
+   * Commit b5404f496 fixed `connector`, which TOLERATED the stamped envelope and then
+   * stripped it — success with silent data loss — and measured whether `webhook`
    * had the same drop. It does not: `WebhookSchema` has carried
    * `...MetadataProtectionFields` since #4001 batch 11, and all SEVEN keys
    * survive the round-trip. No spread was added here; this pin is what makes

packages/spec/src/compose-stacks-action-echo.test.ts

@@ -17,7 +17,7 @@
  * three stacks binding b1/b2/b3 to one object, override / merge
  *                                        : shared.actions=["emb3/EMB","b3/BOUND","b1/BOUND","b2/BOUND","b3/BOUND"]
  * defineStack(composeStacks([a, b]))     : REFUSED  'a_item:dup_x' is declared 3 times
- * defineStack(a)   (a lone built input)  : REFUSED  'a_item:dup_x' is declared twice   ← #14686's landed pin
+ * defineStack(a)   (a lone built input)  : REFUSED  'a_item:dup_x' is declared twice   ← commit 279431e7a's landed pin
  * ```
  *
  * The three-stack `merge` row above is a refusal since #14848: `'merge'` no
@@ -31,7 +31,7 @@
  * the very same object as an entry of `object.actions` is that a previous merge
  * put it there. A strict parse produces fresh objects, so a hand-written twin —
  * the same action authored in both positions — never shares identity, and
- * #14686's same-key refusal, which runs before the merge, still refuses it. A
+ * commit 279431e7a's same-key refusal, which runs before the merge, still refuses it. A
  * marker key cannot do this job: `ActionSchema` is a strict object, so the key
  * is refused before it could travel (measured below).
  *
@@ -197,7 +197,7 @@ describe('composeStacks - what the identity skip does NOT fold', () => {
 
   it('under strict: false, ONE action object placed in both positions is one declaration — carried once (before: twice)', () => {
     // No parse clones it, so it shares identity exactly as a build's echo does.
-    // #14686's walk does not run in this mode by the author's choice, and the
+    // Commit 279431e7a's walk does not run in this mode by the author's choice, and the
     // runtime dedupes a standalone against an embedded entry by key anyway.
     const shared = act('sh', { objectName: 'n_item' });
     const out = defineStack({ manifest: mf('com.example.n'), objects: [obj('n_item', [shared])], actions: [shared] }, { strict: false });

packages/spec/src/compose-stacks-action-key-collision.test.ts

@@ -1,6 +1,6 @@
 /**
  * `composeStacks` refuses two INPUT STACKS whose action declarations resolve
- * to one scope-qualified runtime key — and only those (#14662).
+ * to one scope-qualified runtime key — and only those (commit 35dffeace).
  *
  * `defineStack` refuses the same collision within one stack
  * (`stack-duplicate-action-key.test.ts`); the runtime keys a composed artifact

packages/spec/src/compose-stacks-key-loss.test.ts

@@ -170,7 +170,7 @@ describe('#5005 rule 3 — a key with no declared rule warns', () => {
     // One warning that both names the key AND carries the prescription — not
     // two unrelated ones (`defineStack` also warns about undeclared keys).
     // Anchored on the prescription's own words, never on a tracker id the
-    // author cannot resolve (#13156's strip).
+    // author cannot resolve (commit fd289be45's strip).
     const warnings = warnSpy.mock.calls.map((c) => String(c[0]));
     expect(
       warnings.some((w) => w.includes('composeStacks') && w.includes("'futureThing'") && w.includes('COMPOSE_KEY_DISPOSITIONS')),

packages/spec/src/conversions/conversions.test.ts

@@ -571,7 +571,7 @@ describe('conversion layer (ADR-0087 D2)', () => {
     });
 
     /**
-     * The jurisdiction pin for `retiredFromLoadPath` (#16864).
+     * The jurisdiction pin for `retiredFromLoadPath` (commit 29dd1a6dd).
      *
      * `apply.ts` and `types.ts` now declare that retirement is an AUTHORING
      * surface event: the flag keeps an entry off `normalizeStackInput`, while
@@ -895,7 +895,7 @@ describe('conversion layer (ADR-0087 D2)', () => {
     });
   });
 
-  // #6345 — the `mongo` → `mongodb` canonical-id rename. Two claims have to hold
+  // Commit e2798fab7 — the `mongo` → `mongodb` canonical-id rename. Two claims have to hold
   // together, and only together: the stored value CONVERGES, and a deployment
   // that never runs the conversion is NOT broken. Either alone would be the
   // wrong shape — a rename that breaks old rows, or a rename that leaves one
@@ -974,7 +974,7 @@ describe('conversion layer (ADR-0087 D2)', () => {
     });
 
     it('still lands for a row whose driver id is ITSELF being renamed (#6345)', () => {
-      // The pairs are keyed by CANONICAL driver id, and #6345 renamed mongo's.
+      // The pairs are keyed by CANONICAL driver id, and commit e2798fab7 renamed mongo's.
       // A stored `driver: 'mongo'` must therefore still find the mongo pairs
       // (through the alias) even as the sibling conversion rewrites its id —
       // otherwise the rename would quietly un-convert every legacy mongo config.

packages/spec/src/conversions/stored.test.ts

@@ -126,7 +126,7 @@ describe('applyConversionsToStoredItem (stored sys_metadata rows, #3903)', () =>
   // silently move a sqlite `file:` row's data to `:memory:`).
   describe('stored datasource rows (datasource-config-driver-key-aliases, #4456)', () => {
     // The fourth column is the driver id the stored pass SERVES, which differs
-    // from the stored one for exactly one row: #6345 renamed the canonical mongo
+    // from the stored one for exactly one row: commit e2798fab7 renamed the canonical mongo
     // id to `mongodb`, and `datasource-driver-mongo-to-mongodb` converges the
     // stored spelling in the same replay. Both conversions run over one row here,
     // which is the case worth pinning — the config-key rename is keyed by

packages/spec/src/data/analytics-date-range-two-bound-window.test.ts

@@ -55,7 +55,7 @@ const RANGE_PATH = ['timeDimensions', 0, 'dateRange'];
 /** Arities the contract's own prose and #16322's shipped table already excluded. */
 const REFUSED_ARITIES: ReadonlyArray<readonly unknown[]> = [
   [],                                        // no window at all
-  ['2026-01-01'],                            // the shape #17124 measured three ways
+  ['2026-01-01'],                            // read three ways until commit 86c505286 refused it
   ['2026-01-01', '2026-01-31', '2026-02-28'], // three bounds
   ['{7_days_ago}'],                          // one macro token is a bound, not a window
 ];

packages/spec/src/data/analytics-strictness-batchd.test.ts

@@ -93,7 +93,7 @@ describe('#4001 batch D — the doors the cube family is reachable through', ()
   it('[#10194] `analytics_cube` now resolves the SAME schema at the saveMetaItem door', () => {
     // This pin used to assert the opposite — `getMetadataTypeSchema` answering
     // `undefined` — and its comment demanded that the ADR-0010 envelope
-    // question be re-asked before the line was "fixed". It was: #10194 bound
+    // question be re-asked before the line was "fixed". It was: commit 2306a765c bound
     // `analytics_cube` in `UNREGISTERED_KIND_SCHEMAS` (so `PUT
     // /meta/analytics_cube/:name` stops storing any JSON as `success: true`),
     // and CubeSchema now declares `...MetadataProtectionFields`, exactly per

packages/spec/src/data/api-derivation.test.ts

@@ -229,12 +229,12 @@ describe('api-derivation (#3391)', () => {
       );
       expect(doc, 'DATA_ACTION_TO_API_OPERATION lost its TSDoc block').toBeTruthy();
       // The block has two halves and only the first is a claim about today:
-      // the vocabulary description, then a `[#6259]` note recording what was
+      // the vocabulary description, then a `[commit 6968885ef]` note recording what was
       // removed and why. The note is EXPECTED to say `batch`; the description
       // saying it is the drift this issue is about ("runtime `callData`
       // actions (`query`/`find`→`list`, `batch`→`bulk`)").
-      const [description, history] = doc![0].split('[#6259]');
-      expect(history, 'the `[#6259]` removal note vanished from the TSDoc').toBeTruthy();
+      const [description, history] = doc![0].split('[commit 6968885ef]');
+      expect(history, 'the `[commit 6968885ef]` removal note vanished from the TSDoc').toBeTruthy();
       expect(description).not.toMatch(/batch/);
     });
   });

packages/spec/src/data/api-derivation.ts

@@ -160,8 +160,8 @@ export const API_METHOD_DERIVATION: Record<LegacyApiMethod, DerivationRule> = {
  * the resolver, treated as ungated (custom actions were never gated by
  * `apiMethods`).
  *
- * [#6259] The `batch: 'bulk'` row was removed, and the line above no longer
- * calls `batch` a runtime `callData` action (both by commit 6968885ef). It was the one entry with no
+ * [commit 6968885ef] That commit removed the `batch: 'bulk'` row and stopped the
+ * line above calling `batch` a runtime `callData` action. It was the one entry with no
  * producer on either side: `callData` branches on a closed set that has not
  * contained `batch` since that arm was retired (#5856), and every REST caller
  * of `apiAccessDenialFromEnable` passes a canonical literal — including the

packages/spec/src/data/driver/driver-credential-refusal.test.ts

@@ -794,7 +794,7 @@ describe('mongo options passthrough — nested credential-SPELLED keys refused a
  * config cannot work as written and the authoring door — the one place both
  * halves are visible at once — says so.
  *
- * Envelope note (same as the #8082/#9040 pins above): the zod issue's `code`
+ * Envelope note (same as the #8082 / commit 24206416a pins above): the zod issue's `code`
  * and its pathed location are the whole envelope at this layer — every schema
  * refusal is wrapped uniformly by the publish door (metadata-protocol's
  * `422 INVALID_METADATA`, whose `issues[]` carry these codes verbatim).
@@ -1025,7 +1025,7 @@ describe('datasource — bound credentialsRef + user-less mongo url refused (#90
  * ''`); `buildMongoAuth`, the DSN branch's route, returns early on `!url`. So a
  * falsy `username` leaves the secret with nowhere to go.
  *
- * Envelope note (same as the #8082/#9040/#9041 pins above): the zod issue's
+ * Envelope note (same as the #8082 / commit 24206416a / commit d491625c1 pins above): the zod issue's
  * `code` and its pathed location are the whole envelope at this layer — every
  * schema refusal is wrapped uniformly by the publish door (metadata-protocol's
  * `422 INVALID_METADATA`, whose `issues[]` carry these codes verbatim).

packages/spec/src/data/driver/turso.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * The turso/libSQL config contract (#6345).
+ * The turso/libSQL config contract (commit e2798fab7).
  *
  * These assertions are what "`validateDriverConfig('turso')` flipped from
  * `{ known: false }` to `{ known: true }`" MEANS in practice: before this file
@@ -57,7 +57,7 @@ describe('TursoConfigSchema', () => {
   });
 
   // The exact failure this contract was written for: `token` is the plausible
-  // spelling, `authToken` is the real one, and before #6345 the misspelling was
+  // spelling, `authToken` is the real one, and before commit e2798fab7 the misspelling was
   // accepted in silence and the connection attempted unauthenticated. Until
   // #7990 the fix was a rename hint onto `authToken`; now that `authToken` is
   // itself unwritable the same spelling gets the credential refusal directly —

packages/spec/src/identity/api-key-retirement.test.ts

@@ -8,15 +8,15 @@ import {
   holdersOf,
 } from '../../scripts/lib/export-origins-testkit';
 
-// ─── [#8715] `ApiKeySchema` is RETIRED ──────────────────────────────────────
+// ─── [commit 2c86fe3ea] `ApiKeySchema` is RETIRED ───────────────────────────
 //
 // ADR-0049 enforce-or-remove; maintainer ruling 2026-08-15 (disposition B:
 // delete). `identity/identity.zod.ts` no longer declares `ApiKeySchema` /
 // `ApiKey` / `ApiKeyParsed` — 1 emitted def (`identity/ApiKey`), 3 exported
 // names, 19 authorable-surface keys, the reference page's `ApiKey` section
 // with them.
 //
-// The measurement that decided it (issue #8715, dev report 2026-08-14;
+// The measurement that decided it (commit 2c86fe3ea's card, dev report 2026-08-14;
 // re-verified at this retirement's base commit, 7901b2d):
 //
 //   1. STATIC — zero imports of any of the three names outside
@@ -115,6 +115,6 @@ describe('[#8715] identity/ ApiKeySchema retirement', () => {
     }
     // Anti-vacuity: the explanatory block this retirement left behind is
     // present, so "false" above cannot mean "wrong file".
-    expect(src).toContain('are NOT declared here (#8715');
+    expect(src).toContain('are NOT declared here (commit 2c86fe3ea');
   });
 });

packages/spec/src/identity/identity.zod.ts

@@ -227,8 +227,8 @@ export const VerificationTokenSchema = lazySchema(() => z.object({
 export type VerificationToken = z.input<typeof VerificationTokenSchema>;
 
 /*
- * `ApiKey` / `ApiKeySchema` / `ApiKeyParsed` are NOT declared here (#8715,
- * maintainer-ruled DELETE 2026-08-15, commit 2c86fe3ea; ADR-0049 enforce-or-remove).
+ * `ApiKey` / `ApiKeySchema` / `ApiKeyParsed` are NOT declared here (commit 2c86fe3ea,
+ * maintainer-ruled DELETE 2026-08-15; ADR-0049 enforce-or-remove).
  *
  * The schema that stood here documented better-auth's `apiKey` PLUGIN shape —
  * a plugin this platform does not load: `start`, `lastRefetchAt`, `enabled`

packages/spec/src/integration/connector-author-shape.test.ts

@@ -52,7 +52,7 @@ import { ConnectorSchema } from './connector.zod';
 // post-transform `{ dialect, source }` envelope and a bare cron string is
 // correctly rejected. When this gate was written that state sat on the bare
 // `Connector` and the author state on `ConnectorInput`, and this comment called
-// flipping them "a real but separate appetite". ADR-0122 phase 2 (#6083) did it:
+// flipping them "a real but separate appetite". ADR-0122 phase 2 (commit 53068c130) did it:
 // the bare `Connector` is now `z.input` — the shape the document annotates with
 // — and `ConnectorParsed` carries the parse result. The pinned FACT is
 // unchanged; the two names swapped sides, which is what the last describe block