docs(plugin-security): re-anchor the dead tracker citations to the commits and ADRs that decided them

.changeset/20596-plugin-security-provenance-anchors.md

@@ -0,0 +1,11 @@
+---
+'@objectstack/plugin-security': patch
+---
+
+Provenance comments in `plugin-security` were re-anchored
+
+Comment and docblock lines under `src/` that cited tracker numbers which no
+longer resolve on GitHub now cite the record in this repository that decided
+the matter (an ADR where one exists, otherwise the commit in this repository's
+history), and say in their own words what was decided. Comments only: no type,
+schema, export, log or refusal text, or runtime behaviour changes.

packages/plugins/plugin-security/src/bootstrap-declared-capabilities.test.ts

@@ -60,12 +60,12 @@ function makeQl(declared: any[] = []) {
           return (v === null ? r[k] == null : r[k] === v);
         }),
       );
-      // [#11518] `limit` is HONOURED, and a paged read is ordered by `id`
+      // [commit e1d773eb7] `limit` is HONOURED, and a paged read is ordered by `id`
       // ascending (#4363's pagination tie-breaker). Both are properties of the
       // shipped drivers, measured for the sibling double in
       // `bootstrap-system-capabilities.test.ts`; this one ignored `limit`
       // entirely, which made the whole class of page-cap defect INEXPRESSIBLE
-      // here — including #11518's, whose consequence lands on THIS seeder.
+      // here — including the cap commit e1d773eb7 fixed, whose consequence lands on THIS seeder.
       if (q?.limit === undefined) return matched;
       return [...matched]
         .sort((a, b) => (String(a.id) < String(b.id) ? -1 : String(a.id) > String(b.id) ? 1 : 0))
@@ -434,7 +434,7 @@ describe('unowned-declaration diagnostic (#4967 Part 3)', () => {
 });
 
 /**
- * [#11518] THE CONSEQUENCE THIS SEEDER PAYS FOR A TRUNCATED EXISTENCE PAGE.
+ * [commit e1d773eb7] THE CONSEQUENCE THIS SEEDER PAYS FOR A TRUNCATED EXISTENCE PAGE.
  *
  * This is one of the two callers on `main` that read UNSCOPED (the other is
  * `permission-set-projection`'s overlay pass), and `seed-name-lookup.ts` capped

packages/plugins/plugin-security/src/bootstrap-platform-admin-existing-holder-scan.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * #16861 — whether this deployment ALREADY has a platform admin, and why the
+ * Commit 1c83ca226 — whether this deployment ALREADY has a platform admin, and why the
  * answer stopped being a function of how many ORG admins it has.
  *
  * ## The defect, re-measured on this branch's base before anything changed
@@ -58,7 +58,7 @@
  * ## Why the row ORDER is permuted rather than a second driver package
  *
  * Same reason as `bootstrap-platform-admin-promotion-selection.test.ts`
- * (#16682): `@objectstack/driver-memory` cannot be declared here without a
+ * (commit 9b9581b11): `@objectstack/driver-memory` cannot be declared here without a
  * `scripts/driver-memory-census.ledger.json` disposition, which is a
  * maintainer ruling. Each case runs the REAL engine over the REAL
  * better-sqlite3 driver behind a facade that permutes a result ONLY when the

packages/plugins/plugin-security/src/bootstrap-platform-admin-promotion-selection.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * #16682 — WHICH user the `single`-posture bootstrap promotes, and why.
+ * Commit 9b9581b11 — WHICH user the `single`-posture bootstrap promotes, and why.
  *
  * ## The defect, re-measured on this branch's base before anything changed
  *
@@ -199,7 +199,7 @@ async function seedUser(
   email: string,
   createdAt: string,
   withAccount: boolean,
-  // [#16682, maintainer ruling batch #100] Absent means UNVERIFIED, which is
+  // [commit 9b9581b11, maintainer ruling batch #100] Absent means UNVERIFIED, which is
   // what `isEmailVerifiedUserRow` reads an absent column as — so every fixture
   // that does not say otherwise is a row the declared-owner leg must REFUSE.
   emailVerified = false,

packages/plugins/plugin-security/src/bootstrap-platform-admin-seeded-provenance.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * #8692 — what provenance a REAL `bootstrapPlatformAdmin` run leaves on the
+ * [commit 712e185db] What provenance a REAL `bootstrapPlatformAdmin` run leaves on the
  * platform default permission sets, and what `os meta resync` then does with it.
  *
  * ## Why this file exists at all
@@ -136,7 +136,7 @@ async function rowViaEngine(engine: ObjectQL, name: string): Promise<any> {
 }
 
 /**
- * A row exactly as a PRE-#8692 install holds it — written the way the old
+ * A row exactly as an install before commit 712e185db holds it — written the way the old
  * seeder wrote it, which is to say WITHOUT `managed_by`, so the value comes
  * from the declaration's `defaultValue: 'admin'` by the very mechanism that
  * produced it on every install created before the ruling.

packages/plugins/plugin-security/src/bootstrap-platform-admin-walled-owner.test.ts

@@ -6,7 +6,7 @@
  * History of this surface, because the pins below flip an older family:
  *  - #11184 (framework leg of cloud#1509): walled postures stopped promoting
  *    the first registrant; only the env-declared owner elevated.
- *  - #11343: the walled match additionally required a VERIFIED email.
+ *  - commit c0714eb5d: the walled match additionally required a VERIFIED email.
  *  - #13147: `OS_PLATFORM_OWNER_EMAIL` became a comma-separated list through
  *    the ONE parser in `@objectstack/core`.
  *  - **#11974 (#11663 L4, maintainer acceptance 2026-08-25, Choice 4A/5A):
@@ -24,7 +24,7 @@
  * state, and `single` still PROMOTES (Choice 4A — the over-denial guard:
  * retiring the walled write must not retire the `single` one).
  *
- *  - **#16682: the `single` SELECTION is repaired.** That guard used to be
+ *  - **Commit 9b9581b11: the `single` SELECTION is repaired.** That guard used to be
  *    written as "byte-for-byte", and one case snapshotted the incumbent's
  *    refusal to read `OS_PLATFORM_OWNER_EMAIL` on this branch. The incumbent
  *    was the defect: an unordered, cap-50 `sys_user` read sorted client-side,
@@ -460,7 +460,7 @@ describe('single posture — "first user is owner" is ruled reasonable and UNCHA
   });
 
   /**
-   * ⚠️ RE-AUTHORED by #16682. This case used to assert the opposite —
+   * ⚠️ RE-AUTHORED by commit 9b9581b11. This case used to assert the opposite —
    * "never consults the owner-email variable: a declared owner does NOT
    * redirect the single-org promotion" — and it is worth being explicit about
    * what changed and what did NOT, because the two are easy to confuse.
@@ -479,7 +479,7 @@ describe('single posture — "first user is owner" is ruled reasonable and UNCHA
    * only on the walled branch.
    *
    * The authority for the reversal is a MAINTAINER ruling — 2026-09-08,
-   * decision batch #100, recorded on #16682 (comment 5587754690), which
+   * decision batch #100, applied by commit 9b9581b11, which
    * supersedes the Choice 4A sentence for this one point and states what
    * survives it, verbatim:
    *
@@ -490,7 +490,7 @@ describe('single posture — "first user is owner" is ruled reasonable and UNCHA
    *   > `single` one, and the over-denial invariant (`adminPromoted === true`
    *   > with a grant row minted) stays pinned.
    *
-   * ⛔ An earlier revision of this comment quoted the #16682 TRIAGE seat's
+   * ⛔ An earlier revision of this comment quoted the TRIAGE seat's
    * ruling instead. That quotation was the reviewer's F3 finding: a pin
    * recorded under a maintainer ruling cannot be rewritten under a seat's.
    * The quotation above is the record that resolved it.
@@ -518,7 +518,7 @@ describe('single posture — "first user is owner" is ruled reasonable and UNCHA
     // #11974's over-denial guard, unchanged: the `single` write still happens.
     expect(r.adminPromoted).toBe(true);
     expect(ql.grants()).toHaveLength(1);
-    // #16682: and it goes to the address the operator declared, not to
+    // Commit 9b9581b11: and it goes to the address the operator declared, not to
     // whichever row the driver handed back first.
     expect(ql.grants()[0]?.user_id).toBe('u_second');
     expect(r.basis).toBe('declared-owner');
@@ -550,8 +550,8 @@ describe('single posture — "first user is owner" is ruled reasonable and UNCHA
 });
 
 // ───────────────────────────────────────────────────────────────────────────
-// [#11974, amended by #16682] The bootstrap-replay trigger set. #11974
-// narrowed it to `single` + create/insert: the #11343 update arm (email /
+// [#11974, amended by commit 9b9581b11] The bootstrap-replay trigger set. #11974
+// narrowed it to `single` + create/insert: commit c0714eb5d's update arm (email /
 // email_verified) fired for the walled verify-then-elevate sequence, which no
 // longer exists, and its own rationale was that "`single` promotes the oldest
 // authenticable human and never reads `email`/`email_verified`".