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

.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', () => {