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

Every comment and docblock site under packages/types/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; every touched file keeps its
line count. A patch changeset ships because the docblocks reach dist.

Claude-Session: https://claude.ai/code/session_local_1d2a197c-c20e-4e90-9be8-413d4d432289
Co-authored-by: Claude <noreply@anthropic.com>

Author: hotlong

.changeset/types-provenance-anchors.md

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

packages/types/src/driver-error-classification.callers.test.ts

@@ -7,7 +7,7 @@
  *
  * ── The defect class ─────────────────────────────────────────────────────────
  *
- * #13324 repaired the predicate by giving it `readObject`, so a driver fault
+ * Commit 4cda78c9b repaired the predicate by giving it `readObject`, so a driver fault
  * naming a DIFFERENT relation can no longer be answered "this table is not
  * provisioned yet". The parameter had to ship OPTIONAL: `@objectstack/types` is
  * published (17.2.0, `exports` `.` and `./node`), and re-exported again from
@@ -17,12 +17,12 @@
  *
  * Optional is right for the world outside this repo and wrong for the inside of
  * it. `isMissingTableError(err)` still compiles, still type-checks, and still
- * returns the pre-#13324 WIDE verdict — silently. On the authz path
+ * returns the WIDE verdict from before commit 4cda78c9b — silently. On the authz path
  * (`packages/core/src/security/resolve-authz-context.ts`) that verdict resolves
  * a permission-store OUTAGE to `[]` permissions instead of failing loud, so the
  * omission fails in the OPEN direction. That is the same declared-but-not-
- * enforced shape #13324 existed to close, one level up: the obligation is
- * stated in prose, and prose is exactly what #13324 proved insufficient.
+ * enforced shape commit 4cda78c9b closed, one level up: the obligation is
+ * stated in prose, and prose is exactly what that commit's defect proved insufficient.
  *
  * ── Why a gate and not a required parameter ──────────────────────────────────
  *

packages/types/src/driver-error-classification.operator-text.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * [#16657] `operatorFacingErrorText` — the dialect's words for a record an
+ * [commit 5a95b0e93] `operatorFacingErrorText` — the dialect's words for a record an
  * operator reads later.
  *
  * ## The regression this closes, and why "one `cause` away" was not enough

packages/types/src/driver-error-classification.targeted-table.test.ts

@@ -4,7 +4,7 @@
  * #13438 — `isMissingTableError` prefers the table a driver DECLARED it targeted
  * over the caller-supplied `readObject`.
  *
- * The residual #13324 left behind: a caller names its OBJECT, a driver compiles
+ * The residual commit 4cda78c9b left behind: a caller names its OBJECT, a driver compiles
  * the statement against the PHYSICAL table, and for a federated object
  * (ADR-0015, `external.remoteName`) the two differ. `crm_order` reads
  * `legacy_orders`; when that remote is genuinely absent the phrase names
@@ -14,7 +14,7 @@
  * Maintainer ruling 2026-09-01 (option 2 on the card): the driver declares the
  * table it targeted on the envelope, the predicate prefers it. The pair the
  * ruling asks for is pinned here — an absent remote reads benign again, and a
- * DIFFERENT relation's error still reads not-benign (the #13324 narrowing must
+ * DIFFERENT relation's error still reads not-benign (the narrowing commit 4cda78c9b made must
  * not reopen) — with the declaration present. The driver's half (that
  * `driver-sql` really stamps `external.remoteName`, live, on each dialect) is
  * `packages/drivers/driver-sql/src/sql-driver-13438-federated-missing-remote-envelope.test.ts`.
@@ -181,7 +181,7 @@ describe('isMissingTableError — a declared targeted table beats the caller-sup
         });
 
         it('a declared node whose phrase mismatches is NOT rescued by a matching cause', () => {
-            // Same disposition #6347 and #13324 gave the exclusion: recognition
+            // Same disposition #6347 and commit 4cda78c9b gave the exclusion: recognition
             // ends the question rather than descending.
             const err = envelope(
                 Object.assign(new Error('no such table: main.absent_base'), {

packages/types/src/driver-error-classification.test.ts

@@ -4,7 +4,7 @@
  * #4728 / #4825 — the classifications that decide whether a driver failure may
  * be silenced.
  *
- * [#13279] Moved here with the module it tests, from
+ * [commit 6a180e42d] Moved here with the module it tests, from
  * `packages/metadata/src/utils/schema-sync-errors.test.ts`. Unchanged except
  * for the import path: `@objectstack/core`'s authorization resolver now asks
  * `isMissingTableError`, so the predicate lives in the package both sides

packages/types/src/driver-error-classification.ts

@@ -4,7 +4,7 @@
  * Driver-error classification: "which driver failures may be silenced?"
  * (#4728, #4825; rule from #4632).
  *
- * ## Home — `@objectstack/types`, since #13279
+ * ## Home — `@objectstack/types`, since commit 6a180e42d
  *
  * This module was born in `@objectstack/metadata` and lived there through
  * #4728 / #4825 / #5841. `@objectstack/metadata/errors`' own docblock recorded
@@ -16,7 +16,7 @@
  *
  * What forced it: `resolveAuthzContext` (`@objectstack/core`) must ask
  * {@link isMissingTableError} to tell a permission-store OUTAGE from a
- * deployment whose `sys_*` tables were never provisioned (#13279). Core cannot
+ * deployment whose `sys_*` tables were never provisioned (commit 6a180e42d). Core cannot
  * import `@objectstack/metadata` — metadata **depends on** core — so the
  * predicate had to move to a package both sides already depend on, or be
  * copied. Copying was measured and rejected: two vocabularies of "which driver
@@ -134,7 +134,7 @@
 // `relation-sub-object.ts` next door for the superstring hole it closes and for
 // why the exclusion's width deliberately differs from the extractor's. That
 // module was already this one's dependency across the package boundary; since
-// #13279 moved this file into `@objectstack/types`, the two are siblings.
+// commit 6a180e42d moved this file into `@objectstack/types`, the two are siblings.
 import { isRelationSubObjectPhrase } from './relation-sub-object.js';
 
 /**
@@ -372,7 +372,7 @@ const MISSING_TABLE: DriverErrorSignature = {
          *
          * [#6615] All three now read one home — `@objectstack/types` — instead
          * of three hand-kept copies, so the phrase can no longer be taught to
-         * the repo a fourth time or drift in one package only. [#13279] This
+         * the repo a fourth time or drift in one package only. [commit 6a180e42d] This
          * file now lives in that same home, so the read is a sibling import. The **width**
          * difference that used to justify the copy is preserved and is the
          * reason the home exports two functions rather than one: those two
@@ -386,7 +386,7 @@ const MISSING_TABLE: DriverErrorSignature = {
          */
         matchesMessage: isRelationSubObjectPhrase,
         /**
-         * [#13324] "…and the relation it names is not the one you read."
+         * [commit 4cda78c9b] "…and the relation it names is not the one you read."
          *
          * The sibling of the phrase above, reached one step further out. That
          * one recognises a failure about something INSIDE a relation, which
@@ -408,7 +408,7 @@ const MAX_CAUSE_DEPTH = 4;
  * [#13438] The physical table a driver's statement TARGETED, declared on the
  * error envelope by the producer that knows it.
  *
- * `readObject` closed the #13324 hole for callers that can name what they read
+ * `readObject` (commit 4cda78c9b) closed the hole for callers that can name what they read
  * — and left a residual one layer down. A caller names its OBJECT (the API
  * name); a driver compiles the statement against the PHYSICAL table, and for a
  * federated object (ADR-0015, `external.remoteName`) those are two different
@@ -424,7 +424,7 @@ const MAX_CAUSE_DEPTH = 4;
  * stamps the table its statement targeted onto it — and the predicate PREFERS
  * a declared table over the caller-supplied `readObject`. The caller never
  * needs to know a federated object's remote name, and a driver that declares
- * nothing gets exactly the #13324 behaviour.
+ * nothing gets exactly the behaviour commit 4cda78c9b introduced.
  *
  * A symbol key from the global registry, held non-enumerable: the carrier
  * discipline `driver-sql` already applies to its withheld-diagnostic symbols
@@ -438,7 +438,7 @@ const MAX_CAUSE_DEPTH = 4;
  * ⚠️ A declaration is EVIDENCE, so it also narrows the one-argument form: an
  * envelope declaring `legacy_orders` whose dialect phrase names some other
  * relation reads not-benign even with no `readObject` — the driver supplied
- * the fact the caller could not. That is the #13324 verdict reached without
+ * the fact the caller could not. That is commit 4cda78c9b's verdict, reached without
  * the caller's help, in the direction the module docblock calls cheap.
  */
 export const DRIVER_TARGETED_TABLE: symbol = Symbol.for('objectstack.driver.targetedTable');
@@ -596,7 +596,7 @@ export function isSchemaAlreadyExistsError(error: unknown, depth = 0): boolean {
  * Postgres' two phrasings — the relation is right there in the message because
  * it exists (#6347). See {@link MISSING_TABLE}'s `excludes`.
  *
- * [#13324] Neither is a failure that names a **different relation**, and that
+ * [commit 4cda78c9b] Neither is a failure that names a **different relation**, and that
  * one cannot be seen without `readObject`. The message test asks what the
  * phrase LOOKS like and never which table it names, so a read of a view whose
  * base table has been dropped — `no such table: main.<base>`, measured on
@@ -605,7 +605,7 @@ export function isSchemaAlreadyExistsError(error: unknown, depth = 0): boolean {
  * be about the table the caller asked for, or it is not evidence about it.
  *
  * Pass `readObject` from every in-repo call site. It is **optional** so that
- * omitting it is exactly the pre-#13324 behaviour rather than a new loud
+ * omitting it is exactly the behaviour before commit 4cda78c9b rather than a new loud
  * failure — this is a published export (`@objectstack/types`, and still
  * `@objectstack/metadata/errors` by re-export), and a required parameter would
  * be a breaking change to it. The cost of the choice
@@ -626,12 +626,12 @@ export function isSchemaAlreadyExistsError(error: unknown, depth = 0): boolean {
  * federated object (ADR-0015) that is not the name the driver put in the
  * statement — `crm_order` reads `external.remoteName: 'legacy_orders'`, so a
  * genuinely absent remote raised a phrase naming `legacy_orders` against a
- * caller naming `crm_order`, and the #13324 comparison read it loud. A driver
+ * caller naming `crm_order`, and the comparison commit 4cda78c9b added read it loud. A driver
  * that knows the table it targeted now DECLARES it on the envelope
  * ({@link declareTargetedTable}), and a declared table is preferred over
  * `readObject` outright: the phrase is compared against the declared name, and
  * the caller-supplied one is not consulted at that node or below it. Absent a
- * declaration the comparison is the #13324 one, unchanged. Two consequences,
+ * declaration the comparison is commit 4cda78c9b's, unchanged. Two consequences,
  * both pinned: a genuinely absent federated remote reads benign again without
  * the caller learning the mapping; and — because a declaration is evidence the
  * caller did not have — an envelope whose phrase names a relation other than
@@ -654,11 +654,11 @@ export function isMissingTableError(error: unknown, readObject?: string, depth =
 }
 
 // ---------------------------------------------------------------------------
-// Operator-facing text for a DECLARED driver fault (#16657)
+// Operator-facing text for a DECLARED driver fault (commit 5a95b0e93)
 // ---------------------------------------------------------------------------
 
 /**
- * [#16657] The ADR-0112 code a driver declares when the backend, not the
+ * [commit 5a95b0e93] The ADR-0112 code a driver declares when the backend, not the
  * caller, refused the work. Spelled as a literal for the same reason
  * {@link declaresServerFault} spells `status`/`code` by hand: this package is
  * the common dependency every consumer of the question already has, and reading
@@ -667,7 +667,7 @@ export function isMissingTableError(error: unknown, readObject?: string, depth =
 const DECLARED_DATABASE_FAULT_CODE = 'DATABASE_ERROR';
 
 /**
- * [#16657] The fragment that identifies `SqlDriver`'s RAW-path envelope, and
+ * [commit 5a95b0e93] The fragment that identifies `SqlDriver`'s RAW-path envelope, and
  * only it.
  *
  * The raw terminal (`rawStatementFaultError`, `driver-sql/src/sql-driver.ts`;
@@ -727,7 +727,7 @@ function messageChannelOf(node: unknown): string {
 
 /**
  * The text an OPERATOR should read for `error` — the dialect's own words when a
- * driver composed over them, the error's own message otherwise (#16657).
+ * driver composed over them, the error's own message otherwise (commit 5a95b0e93).
  *
  * # The defect this closes
  *

packages/types/src/email-verified.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * [#11343 / #12751] The verified-email allow-list, pinned representation by
+ * [commit c0714eb5d / #12751] The verified-email allow-list, pinned representation by
  * representation. This predicate is shared between the walled owner-elevation
  * gate (which REFUSES on `false`) and the owner-verification boot diagnostic
  * (which stays quiet on `true`) — the pin here is what both consumers stand

packages/types/src/email-verified.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * [#11343 / #12751] Verified-email predicate over a stored `sys_user` row — a
+ * [commit c0714eb5d / #12751] Verified-email predicate over a stored `sys_user` row — a
  * fail-closed ALLOW-LIST over the representations a driver may hand back for
  * the `sys_user.email_verified` boolean column (JS `true`, SQLite `1`, and
  * their stringified forms). Everything else — `false`/`0`, `null`, an ABSENT

packages/types/src/error-leak.test.ts

@@ -138,7 +138,7 @@ describe('looksLikeInternalErrorLeak — shipped-dialect phrasings (#8132)', ()
         // SQLite/libsql message-only errors: the same conditions with NO
         // `SQLITE_` prefix to trip the existing limb. Measured shapes in this
         // repo — `driver-error-classification.ts` (next door, moved here by
-        // #13279 from `metadata/src/utils/schema-sync-errors.ts`) documents both.
+        // commit 6a180e42d from `metadata/src/utils/schema-sync-errors.ts`) documents both.
         ['sqlite bare missing table', 'no such table: sys_metadata'],
         ['sqlite bare missing table with a schema prefix', 'no such table: main.sys_metadata_history'],
         ['sqlite bare missing column', 'no such column: bogus'],
@@ -177,7 +177,7 @@ describe('looksLikeInternalErrorLeak — shipped-dialect phrasings (#8132)', ()
  * MySQL, and a reviewer sizing a disclosure residual on PR #8737 quoted it in
  * good faith; the claim was false (`driver-sql` branches on `mysql`/`mysql2`,
  * CI stands up a live `mysql:8.0` for a required check, live MySQL 8.0.46
- * measurements landed driver fixes #8621/#8622). PR #8824 corrected the
+ * measurements landed driver fixes #8621/#8622). Commit 8ac232306 corrected the
  * sentence and pinned the narrower, then-true fact — the predicate did not
  * COVER MySQL — as a deliberate tripwire for the decision that was still open.
  *

packages/types/src/index.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 export * from './degraded-boot.js';
-// [#11343/#12751] The one verified-email predicate the walled owner-elevation
+// [commit c0714eb5d / #12751] The one verified-email predicate the walled owner-elevation
 // gate (plugin-security) and the owner-verification boot diagnostic
 // (plugin-auth) both read — see the module doc for why it must be one.
 export * from './email-verified.js';
@@ -48,7 +48,7 @@ export * from './relation-sub-object.js';
 // Four hand-written vocabularies used to answer it and disagreed about MySQL,
 // which is why every MySQL conflict came back 500 instead of 409.
 export * from './unique-violation.js';
-// [#4728/#4825, moved here by #13279] The one "which driver failures may be
+// [#4728/#4825, moved here by commit 6a180e42d] The one "which driver failures may be
 // silenced?" vocabulary — `isMissingTableError` (a READ failed because the
 // table was never provisioned) and `isSchemaAlreadyExistsError` (a DDL failure
 // that was just the table already being there). It was `@objectstack/metadata`'s