docs(rest): re-anchor the dead tracker citations in packages/rest/src to the commits that decided them

.changeset/rest-provenance-anchors.md

@@ -0,0 +1,11 @@
+---
+'@objectstack/rest': patch
+---
+
+Provenance comments in `@objectstack/rest` 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 route, error code, refusal text, type, export or runtime behaviour
+changes.

packages/rest/src/analytics-dataset-selection-door.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * [#17058] `POST /analytics/dataset/query` parses its `selection` AT THE DOOR.
+ * [commit 94c930248] `POST /analytics/dataset/query` parses its `selection` AT THE DOOR.
  *
  * The defect: the route checked only that `selection.measures` was a non-empty
  * array, so every other member reached `dataset-executor` unrefused — while the
@@ -17,9 +17,9 @@
  * one that matters most: a fully-loaded VALID selection still passes. A door
  * that refuses too much is a worse defect than the one being fixed.
  *
- * ## [#17551, ruled] The half #17058 could not door
+ * ## [#17551, ruled] The half commit 94c930248 could not door
  *
- * #17058 parsed a PROJECTION — the seven members whose declarations coincide
+ * Commit 94c930248 parsed a PROJECTION — the seven members whose declarations coincide
  * with `AnalyticsQuery`'s — and projected `runtimeFilter`, `dateGranularity`,
  * `compareTo` and `totals` AWAY, because `DatasetSelection` had no Zod schema
  * anywhere in the repo and authoring one in this consumer is the second

packages/rest/src/analytics-fault-user-message.test.ts

@@ -24,7 +24,7 @@
  * ①b — the arm that re-dresses `classifiedRefusalAnswer`'s body with
  * `...refusalFields` — IS the arm the card measured, and it does carry the mark
  * because that body comes from `resolveErrorResponse`, whose arms already ride
- * it (`withDeclaredUserMessage`, #9934). §5 pins ①b as untouched, so the two
+ * it (`withDeclaredUserMessage`, commit 79c46da90). §5 pins ①b as untouched, so the two
  * classified arms are not flattened into one story in either direction.
  *
  * What ①, ③a and ③b have in common is that none of them holds a classified body
@@ -43,7 +43,7 @@
  *   1. `classifyDataError` (`error-response.ts`), whose only caller is the
  *      exported `mapDataError`, which IS `withDeclaredUserMessage(error,
  *      classifyDataError(…))`. That door already carries the mark, applied one
- *      layer OUT and branch-agnostically over every arm — the shape #9934 chose
+ *      layer OUT and branch-agnostically over every arm — the shape commit 79c46da90 chose
  *      deliberately, and the reason the shared body-builder carries no mark of
  *      its own.
  *   2. this route's ③a.
@@ -323,7 +323,7 @@ describe('[#12710] §4 both doors carry the same producer mark for the same thro
       const flat = dataDoor(c.error());
       // POSITIVE CONTROL — without this the analytics assertion below could pass
       // for the wrong reason (two doors agreeing the mark does not belong on
-      // this terminal). #9934 rules that it does; `/data` is where that ruling
+      // this terminal). The ruling commit 79c46da90 landed says it does; `/data` is where that ruling
       // already lives.
       expect(
         flat.body.userMessage,

packages/rest/src/auth-gate-allowlist-fault-window.measurement.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * [#15021] MEASUREMENT — does the #13906 fail-closed window also refuse the
+ * [commit cc238db8b] MEASUREMENT — does the #13906 fail-closed window also refuse the
  * ALLOW-LISTED remediation routes `isAuthGateAllowlisted` exists to keep
  * reachable?
  *
@@ -530,7 +530,7 @@ describe('[#15021] §5 can a mounted route capture a CONCRETE remediation path?'
     // mounts (`plugin-auth`'s `/api/v1/auth/*`, `plugin-hono-server`'s
     // `/auth/me/*`) that never enter `computeExecCtx`.
     //
-    // ⚠️ If this goes RED, the reachability qualifier on #15021 is gone and the
+    // ⚠️ If this goes RED, the reachability qualifier commit cc238db8b pinned is gone and the
     // card's impact sentence has become true: a mounted route now answers a
     // remediation path, and §2 says every such answer is 503 for the duration
     // of a session-backend fault. ⛔ Do not relax this to make a new mount

packages/rest/src/direct-mount-base-follows-apipath.test.ts

@@ -1,6 +1,6 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 //
-// [#6306] ONE API base for the whole REST surface — pinned end to end through
+// [commit fec784863] ONE API base for the whole REST surface — pinned end to end through
 // the plugin that composes it in production.
 //
 // The defect this replaces: `RestServer.getApiBasePath()` answers
@@ -13,7 +13,7 @@
 // `/api/v1` (`packages.*` ×4, `datasources/:name/external/*` ×5). Those 9
 // were also absent from `{apiPath}/openapi.json` (71 paths vs 79), because
 // that document is filtered to this server's base — the filter is what made
-// the split visible (#5822 / PR #6303).
+// the split visible (#5822 / commit 465c5fc14).
 //
 // What is pinned here, and at which level. This file drives
 // `createRestApiPlugin(config).start(ctx)` — the real composition — over a

packages/rest/src/discovery-advertised-direct-mounts.parity.test.ts

@@ -17,15 +17,15 @@
 // chain together against the live surface, so ANY future change that moves
 // only one side goes red here: move the mount without the advertisement (or
 // vice versa) and the advertised URL stops resolving in the handler table.
-// #6306 was the first such move and it landed with no edit in this file —
+// Commit fec784863 was the first such move and it landed with no edit in this file —
 // which is the property working, not the pin missing it.
 //
 // The non-default-base case is the load-bearing one: it drives the
 // composition at a base that is not `/api/v1` to prove nothing re-derives the
 // convention. Note the level this file measures at — it calls
 // `mountAndRecordDirectRoutes` directly, so `versionedBase` is its own
 // parameter and the projection is pinned independently of WHO chooses that
-// base. Since #6306 the production chooser is `RestServer.getApiBasePath()`
+// base. Since commit fec784863 the production chooser is `RestServer.getApiBasePath()`
 // (so `apiPath` deployments mount and advertise under `{apiPath}`); that
 // wiring — plugin config in, mounted+advertised+documented URLs out — is
 // pinned end to end in `direct-mount-base-follows-apipath.test.ts`.
@@ -219,7 +219,7 @@ describe('[#6633] /discovery advertises the direct-mount surfaces where they are
     // The mount base is an input here, deliberately decoupled from the
     // RestServer's own base: that is what proves the advertisement is read
     // off the recorded mounts rather than re-derived from config. It is also
-    // what kept advertisement and mount inseparable across #6306's move.
+    // what kept advertisement and mount inseparable across commit fec784863's move.
     const { table } = boot({ versionedBase: '/backend/api/v9' });
     const discovery = await readDiscovery(table);
 

packages/rest/src/discovery-schema-conformance.test.ts

@@ -340,8 +340,8 @@ describe('[#4828] the REST /discovery live shape conforms to DiscoverySchema', (
   // line after calling the producer, so the wire answer was the MOUNTED PATH
   // SEGMENT (`'v1'` by default) — the string the caller had just typed to reach
   // the endpoint. `DiscoverySchema` declares `version` under "System Identity"
-  // next to `name` and `environment`, and the #10993 ruling (reaffirmed by
-  // #11235/#11242) settled that as the SERVING ARTIFACT's version.
+  // next to `name` and `environment`, and the #10993 ruling (which commits
+  // 98ea3443f and 376c70f98 landed) settled that as the SERVING ARTIFACT's version.
   //
   // Every assertion below pins PROVENANCE, never a literal version string: the
   // wire answer is compared against the producer's own answer, or against a

packages/rest/src/error-response-generic-passthrough-object-parity.test.ts

@@ -1,12 +1,12 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * #14725 — the GENERIC declared-status passthrough must answer one refusal
+ * Commit f5cc78b63 — the GENERIC declared-status passthrough must answer one refusal
  * with one body, on both REST error doors.
  *
  * ## What was measured, on `origin/main` @ `a12b15e394`
  *
- * #14541 made the two doors agree for every error a BESPOKE arm classifies.
+ * Commit 6d178a408 made the two doors agree for every error a BESPOKE arm classifies.
  * They still disagreed for every error that reaches the GENERIC declared-status
  * passthrough, because the two copies of that one passthrough differed by
  * exactly one key: `classifyDataError`'s copy ends `...(object ? { object } :
@@ -121,8 +121,8 @@ const singleDoor = (error: unknown, object?: string): Wire => mapDataError(error
  *
  * ⚠️ "Three siblings" is itself easy to over-read, so the measured limit: §3
  * keys on `RECORD_LOCKED`, one of §1's OWN codes, so an arm for that code
- * migrates §3 along with §1. Only §2 and #14541's §4 are independent of the
- * codes below. #14541 §5's "every arm in the SHARED classification has a §1
+ * migrates §3 along with §1. Only §2 and the door-parity file's §4 are independent of the
+ * codes below. The door-parity file's §5 "every arm in the SHARED classification has a §1
  * parity case" reddens when an arm ARRIVES, but goes green again as soon as its
  * author adds the parity case it asks for — it does not hold THIS file's §1 to
  * the passthrough.
@@ -140,7 +140,7 @@ describe('#14725 — the generic declared-status passthrough carries `object` on
             // The card's own measurement. `DUPLICATE_RECORD` HAS a bespoke arm
             // keyed on `DuplicateRecordError`'s class/`name`; a bare property
             // write does not carry it, which is exactly the shape the card
-            // measured on the #14541 branch.
+            // measured on the branch that landed as commit 6d178a408.
             { code: 'DUPLICATE_RECORD', status: 409, message: 'A record with this value already exists' },
             { code: 'RECORD_LOCKED', status: 409, message: 'This record is frozen' },
             // A 4xx from the other end of the band, so the pin is not a

packages/rest/src/error-response-sandbox-arm-message.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * #14704 — the single-record `/data` door must not ship the QuickJS debug
+ * Commit 1c7adc73d — the single-record `/data` door must not ship the QuickJS debug
  * wrapper out of a declared-code structured arm.
  *
  * ## What was measured, on `origin/main` @ `99b4deba49`
@@ -21,7 +21,7 @@
  *
  * The bulk door is right because #11588 taught `resolveErrorResponse`'s
  * declared-status passthrough to read `sandboxBusinessMessage`, and because
- * #14541 excludes a sandbox-origin error from the shared consult entirely. The
+ * commit 6d178a408 excludes a sandbox-origin error from the shared consult entirely. The
  * single door reached the arms and shipped the wrapper — #11588's own defect,
  * one door over, with the direction reversed rather than closed.
  *
@@ -36,7 +36,7 @@
  *  §3 the non-sandbox control: a plain producer on the same codes keeps
  *     `error.message` byte for byte — the two-read rule is a read of a field
  *     the sandbox populated, never a strip of the wrapper off `.message`;
- *  §4 CONVERGED (#15071, maintainer ruling 2026-09-04 / batch #27, option B):
+ *  §4 CONVERGED (commit cf6e0a193, maintainer ruling 2026-09-04 / batch #27, option B):
  *     a sandboxed CRASH carrying a declared code reaches the unwrap door's
  *     sanitised `500 UNCLASSIFIED_FAULT` whatever code it declares — the
  *     terminal moved above the arms (`isSandboxCrash`). This section was the
@@ -47,7 +47,7 @@
  *     crash branch moves", so an ordinary declared refusal is untouched;
  *  §5 the bulk-door control: this change is unreachable from
  *     `resolveErrorResponse`, which declines the consult for a sandbox-origin
- *     error (#14541), so nothing moves on those routes;
+ *     error (commit 6d178a408), so nothing moves on those routes;
  *  §6 the drift guard: every arm in the shared classification that relays a
  *     PRODUCER sentence asks the shared rule, so the next arm cannot
  *     reintroduce the raw relay silently.
@@ -63,7 +63,7 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 
 /**
  * The classification's own source, read once: §4-derivation and §6 both scan it
- * — one re-derives the arm list from the tree (the #15071 ruling's execution
+ * — one re-derives the arm list from the tree (the ruling commit cf6e0a193 landed: its execution
  * constraint), the other guards the sentence rule. Same package, so the read
  * does not escape it (AGENTS.md → cross-package test inputs).
  */
@@ -233,8 +233,8 @@ describe('#14704 · the single `/data` door never ships the QuickJS wrapper out
     });
 
     /**
-     * FLIPPED by #15071, deliberately and in that card's PR, from
-     * `ACCEPTED DIVERGENCE` to `CONVERGED` — the same discipline PR #15065 used
+     * FLIPPED by commit cf6e0a193, deliberately and in that commit, from
+     * `ACCEPTED DIVERGENCE` to `CONVERGED` — the same discipline commit 1c7adc73d used
      * on its own §4 one file over. ⛔ The section is not DELETED: it is the only
      * thing that would notice the divergence coming back, and what changes is
      * its verdict, not its existence.
@@ -256,7 +256,7 @@ describe('#14704 · the single `/data` door never ships the QuickJS wrapper out
      *
      *  - **the flip**, per arm and by NAME over {@link ARMS} — the list the
      *    ruling required be RE-DERIVED from the tree rather than copied from
-     *    #14704, and `§4-derivation` below is the guard that keeps it derived;
+     *    the list commit 1c7adc73d enumerated, and `§4-derivation` below is the guard that keeps it derived;
      *  - **the positive control STAYS** and is still a control: the same crash
      *    carrying NO declared code reaches the same sanitised 500, so a green
      *    flip leg cannot be read as "the terminal swallowed everything";
@@ -337,7 +337,7 @@ describe('#14704 · the single `/data` door never ships the QuickJS wrapper out
 
         /**
          * The ruling's own execution constraint: *"the seat re-derives the arm
-         * list from the tree, not from #14704's list."* Re-deriving once is a
+         * list from the tree, not from [commit 1c7adc73d]'s list."* Re-deriving once is a
          * reading that rots; this leg is the same re-derivation asked
          * mechanically, so the next arm added to the shared classification is
          * either covered above or excused here BY NAME.
@@ -422,7 +422,7 @@ describe('#14704 · the single `/data` door never ships the QuickJS wrapper out
         });
 
         it('a sandbox-origin error never reaches the shared consult there (#14541)', () => {
-            // Proof by the consequence #14541 recorded: the arms' structured
+            // Proof by the consequence commit 6d178a408 recorded: the arms' structured
             // fields are absent on this door for a sandbox producer.
             const wire = bulkDoor(sandboxRefusal({ code: 'DELETE_RESTRICTED', status: 409, object: 'account', dependentObject: 'contact' }), 'account');
             expect(wire.body).not.toHaveProperty('dependentObject');