From 34ba921e60c0f9d9936571087b103186563d7c79 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 30 Sep 2026 00:48:51 +0000 Subject: [PATCH 1/2] docs(service-package): re-anchor the dead tracker citations to the commits that decided them Stage 10 of the domain:services dead-citation sweep (ruling C+D, form C). Every comment or docblock site under packages/services/service-package/src that cited a tracker number answering 404 now cites the commit in this repository's history that decided what the line describes, and says in its own words what that commit decided. Comments only: each touched file keeps its line count, and no code token moves. Claude-Session: https://claude.ai/code/session_01XY5uCwTjZj7884yYtyur4H Co-authored-by: Claude --- .../src/delete-driver-fault.test.ts | 2 +- .../services/service-package/src/index.ts | 24 +++++++++---------- .../service-package/src/mysql2-tuple.test.ts | 4 ++-- .../service-package/src/null-seam.test.ts | 2 +- .../src/publish-driver-fault.test.ts | 2 +- 5 files changed, 17 insertions(+), 17 deletions(-) diff --git a/packages/services/service-package/src/delete-driver-fault.test.ts b/packages/services/service-package/src/delete-driver-fault.test.ts index e4e00542a49..75db6d44e7f 100644 --- a/packages/services/service-package/src/delete-driver-fault.test.ts +++ b/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', () => { diff --git a/packages/services/service-package/src/index.ts b/packages/services/service-package/src/index.ts index 745eccefba7..2555410dd0a 100644 --- a/packages/services/service-package/src/index.ts +++ b/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 diff --git a/packages/services/service-package/src/mysql2-tuple.test.ts b/packages/services/service-package/src/mysql2-tuple.test.ts index f840592cc2e..4d9a7483020 100644 --- a/packages/services/service-package/src/mysql2-tuple.test.ts +++ b/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. diff --git a/packages/services/service-package/src/null-seam.test.ts b/packages/services/service-package/src/null-seam.test.ts index 1ce5bba4449..0c5bf5e7e19 100644 --- a/packages/services/service-package/src/null-seam.test.ts +++ b/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 * diff --git a/packages/services/service-package/src/publish-driver-fault.test.ts b/packages/services/service-package/src/publish-driver-fault.test.ts index d9eb9e24fd6..e650e17de89 100644 --- a/packages/services/service-package/src/publish-driver-fault.test.ts +++ b/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', () => { From ffd2f1ed2a6aa8e23a83e3292628109a4d56db80 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 30 Sep 2026 01:00:26 +0000 Subject: [PATCH 2/2] chore(changeset): patch for the service-package provenance re-anchor The rewritten docblock on the exported PACKAGE_SEAM_UNREADABLE_MESSAGE reaches dist/index.d.ts and dist/index.d.cts, so the package ships changed bytes. Claude-Session: https://claude.ai/code/session_01XY5uCwTjZj7884yYtyur4H Co-authored-by: Claude --- .changeset/20596-service-package-provenance-anchors.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 .changeset/20596-service-package-provenance-anchors.md diff --git a/.changeset/20596-service-package-provenance-anchors.md b/.changeset/20596-service-package-provenance-anchors.md new file mode 100644 index 00000000000..44811c125a4 --- /dev/null +++ b/.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.