Merge remote-tracking branch 'origin/main' into claude/issue-20822-retired-matcher-pointers

Author: claude

.changeset/20595-driver-memory-provenance-anchors.md

@@ -0,0 +1,14 @@
+---
+'@objectstack/driver-memory': patch
+---
+
+Provenance comments in `@objectstack/driver-memory` cite the commits that decided them, not tracker numbers that no longer resolve
+
+Clause-②: no
+
+Docblocks and comments across the package cited issue-tracker numbers that now answer 404 on GitHub.
+Each one now cites the commit in this repository's history that made the decision it describes. Some of
+these docblocks sit on exported members, so the reworded text appears in the published `index.d.ts` /
+`index.d.mts`, and comments that esbuild keeps appear in the JavaScript output.
+
+Comment only: no export, type, error code, status, message text or runtime behaviour changes.

.github/workflows/lint.yml

@@ -563,12 +563,14 @@ jobs:
       # agent typed the command by hand.
       #
       # ⛔ NOT a hole in `check:self-test-wired`, whose green is correct by its
-      # own definition: its population is the scripts CI RUNS, and this file is a
-      # MODULE no workflow can invoke, so it sat in that gate's remainder by
-      # construction. The blast radius and the population rule point in opposite
-      # directions here: the file with the largest inheritance surface in the
-      # farm is the one shape the wiring gate cannot see. Naming it in this step
-      # is what moves it INTO that population (161 -> 162 scripts CI runs that
+      # own definition: its population is the scripts CI RUNS plus, since
+      # #21351, the scripts a root `package.json` alias self-tests, and this
+      # file is a MODULE no workflow can invoke and no alias names, so it sat in
+      # that gate's remainder by construction. The blast radius and the
+      # population rule point in opposite directions here: the file with the
+      # largest inheritance surface in the farm is the one shape the wiring gate
+      # cannot see. Naming it in this step is what moves it INTO that population
+      # (161 -> 162 scripts CI runs that
       # ship a `--self-test`), and it is the smaller of the two remedies — the
       # other being to widen the gate to a transitive closure, which #14007
       # explicitly does not ask for. ⛔ It is also not a licence to sweep the
@@ -1545,11 +1547,12 @@ jobs:
       # just as green, and a wrong transfer is a write against a shared board,
       # not a report.
       #
-      # ⛔ `check:self-test-wired` does not hold this step. No other workflow
-      # names this script, and that gate's population is the scripts a
-      # workflow names, so deleting this step drops the script back out of it
-      # with every gate still green — the same hole the stale-`finding` sweep
-      # step below records, which only the step itself closes.
+      # `check:self-test-wired` holds this step through the declared alias. No
+      # other workflow names this script, but since #21351 that gate's
+      # population includes every root `package.json` alias whose expansion
+      # carries `--self-test`, so deleting this step reds it with
+      # `[alias-self-test-not-run] pnpm check:pm-issue-transfer`. The
+      # stale-`finding` sweep step below is held the same way.
       - name: Issue-transfer door self-test
         run: pnpm check:pm-issue-transfer
 
@@ -1584,9 +1587,12 @@ jobs:
       #
       # Until this step existed the instrument was UNFIRED: the tool shipped a
       # 91-case `--self-test` that nothing in CI ran, which is the second half
-      # of the pair `check:self-test-wired` exists for (a script is IN its
-      # population only once a workflow names it, so an unwired tool's self-test
-      # is not a hole the gate can see — it is a hole only this step closes).
+      # of the pair `check:self-test-wired` exists for. A script was then IN
+      # that gate's population only once a workflow named it, so the unwired
+      # self-test was a hole only this step could close. Since #21351 the gate
+      # also reads every root `package.json` alias whose expansion carries
+      # `--self-test`, so it holds this step through `check:pm-stale-finding`:
+      # deleting the step reds `[alias-self-test-not-run]`.
       #
       # What the self-test instruments is the set of rules a clean tree cannot
       # exercise: the screen's ungraded verdict, which is the ONE thing the

.github/workflows/release.yml

@@ -51,7 +51,10 @@ name: Release
 #   push to main  →  `release-integrity`   audits ONLY the version at
 #                                          `github.sha`, and names the VERSION
 #                                          COMMIT — the landing that brought
-#                                          main to that version. Never publishes,
+#                                          main to that version; when it queues
+#                                          the publish, it also warns of every
+#                                          changeset that commit carries but did
+#                                          not consume. Never publishes,
 #                                          never pushes a tag. May backfill GitHub
 #                                          Releases / the ADR-0087 D4 asset /
 #                                          the runtime image — but only for a
@@ -913,6 +916,30 @@ jobs:
                 echo "${version}, i.e. what the Version Packages PR decided — and nothing that"
                 echo "landed after it, whatever main's head is by then."
               } >> "$GITHUB_STEP_SUMMARY"
+
+              # ── what ${version} ships without a CHANGELOG entry (#21361) ───
+              # The merge queue lands the Version Packages PR on top of the
+              # current main, and the PR cannot be refreshed while queued, so
+              # the version commit's tree can carry landings whose changesets
+              # it never consumed: their code ships in this release and its
+              # CHANGELOG does not name them (17.3.0 through 17.6.0 each did).
+              # This is the run that queues the publish, so the approver reads
+              # the list here, before the release is cut. A warning annotation:
+              # the level this job gives every finding that leaves the release
+              # incomplete without stopping it (the Releases, the D4 asset, the
+              # image, an unreadable range). It REPORTS and never refuses, so
+              # it neither fails this step nor holds the publish job. A report
+              # that cannot be measured says so in an error annotation (a
+              # shallow clone is refused, never answered from a graft
+              # boundary), and the publish stays queued all the same.
+              if ! node scripts/release-pending-publish.mjs unconsumed --version-commit "$version_commit" --version "$version"; then
+                echo "The changesets the version commit ${version_commit} did not consume were NOT MEASURED (reason above). This report never holds a release, so the publish of ${version} stays queued."
+                {
+                  echo
+                  echo "**Changesets: NOT MEASURED.** Whether ${version}'s CHANGELOG leaves out a change that landed in"
+                  echo "the version commit's tree is unknown; the reason is in this step's log."
+                } >> "$GITHUB_STEP_SUMMARY"
+              fi
               exit 0
             fi
             echo "publish-pending=false" >> "$GITHUB_OUTPUT"

packages/drivers/driver-memory/objectstack.config.ts

@@ -16,14 +16,14 @@ const MemoryDriverPlugin: ObjectStackManifest = {
   scope: 'project',
   description: 'A reference specification implementation of the IDataDriver interface using in-memory arrays. Suitable for testing and development.',
 
-  // `configuration` and `capabilities` were retired (#11332, ADR-0049
+  // `configuration` and `capabilities` were retired (commit dce5cd4f0, ADR-0049
   // enforce-or-remove): nothing ever read either container. The settings this
   // driver needs are passed by the host that composes it (the options object
   // handed to its constructor), and protocol/capability discovery never
   // consulted the declaration — dependency resolution runs off top-level
   // `dependencies`.
 
-  // `contributes.drivers` was retired (#10724, ADR-0049): the declaration drove
+  // `contributes.drivers` was retired (commit be21955ba, ADR-0049): the declaration drove
   // nothing — this driver is wired by registering the `driver.memory` kernel
   // service (the objectql plugin calls `registerDriver` on `driver.*` services),
   // which is the enforced channel.

packages/drivers/driver-memory/src/index.ts

@@ -18,21 +18,21 @@ export {
   MULTI_TENANT_UNSUPPORTED_CODE,
   assertSingleTenantPosture,
   assertObjectsNotTenantScoped,
-  // [#16589] Seam 3 — the per-call refusal. Exported on the same reasoning as
+  // [commit 555a89cbd] Seam 3 — the per-call refusal. Exported on the same reasoning as
   // the two boot seams above: a consumer asserting this driver's behaviour under
   // a tenant scope needs the refusal's identity, not its message text.
   assertCallNotTenantScoped,
   declaresTenantScope,
 } from './memory-tenancy-guard.js';
 export type { TenancyAwareSchema } from './memory-tenancy-guard.js';
 
-// [#13197, #13239] Uniqueness on BOTH declaration surfaces — field-level
+// [commit 56c093c4d, #13239] Uniqueness on BOTH declaration surfaces — field-level
 // `unique` and object-level declared `indexes[]` — with the refusal's wire
 // identity and the scoping helpers, exported so a consumer can assert the
 // envelope (`code` AND `status`, never merely "it threw") without
 // string-matching the message.
 //
-// [#16729] `computeAndRecordTenantField` is published BESIDE `tenantFieldOf`,
+// [commit 0f38ab084] `computeAndRecordTenantField` is published BESIDE `tenantFieldOf`,
 // not kept private, because publishing only the inner half is what let this
 // package diverge in the first place: `tenantFieldOf` mirrors
 // `SqlDriver.computeTenantField`, the stickiness lives in the wrapper AROUND

packages/drivers/driver-memory/src/memory-20874-contains-membership.test.ts

@@ -60,7 +60,7 @@ import { MemoryAnalyticsService } from './memory-analytics.js';
 
 const byId = (a: string, b: string) => a.localeCompare(b);
 
-/** `driver-sql`'s #17590 fixture, plus its #20874 `owners` column. */
+/** `driver-sql`'s commit e04a0aff2 fixture, plus its #20874 `owners` column. */
 const MEMBERSHIP = {
   object: 'mem20874_membership',
   fields: {
@@ -107,7 +107,7 @@ const SHAPES = {
 type Fixture = typeof MEMBERSHIP | typeof SHAPES;
 type Case = readonly [name: string, where: FilterCondition, expected: readonly string[]];
 
-/** Fixture one — `driver-sql`'s #17590 assertions, verbatim, and #20874's. */
+/** Fixture one — `driver-sql`'s commit e04a0aff2 assertions, verbatim, and #20874's. */
 const MEMBERSHIP_CASES: readonly Case[] = [
   ['tags: the member row, never the substring row', { tags_: { $contains: 'red' } }, ['1']],
   ['tags: a whole member', { tags_: { $contains: 'redwood' } }, ['2']],

packages/drivers/driver-memory/src/memory-analytics-echo-operator-coverage.test.ts

@@ -364,7 +364,7 @@ describe('[#7117] the analytics echo renders the query it describes', () => {
     });
 
     /**
-     * [#13195] The one cell where SQL could not say what mingo said — CLOSED,
+     * [commit 9dac1ae01] The one cell where SQL could not say what mingo said — CLOSED,
      * and closed from the mingo side.
      *
      * This assertion used to be an INEQUALITY, kept so the split could not be
@@ -468,7 +468,7 @@ describe('[#7117] the analytics echo renders the query it describes', () => {
       it(`${op}: running the echo returns exactly the rows the query returns`, async () => {
         const executed = await executedIds(where);
         const echoed = await echoIds(where);
-        // [#13195] `$exists` used to return early here — the documented residue
+        // [commit 9dac1ae01] `$exists` used to return early here — the documented residue
         // above was asserted there and skipped in this loop, so the loop was a
         // statement about every OTHER operator. The residue is gone, the skip
         // with it, and this loop is now total over the face's vocabulary.

packages/drivers/driver-memory/src/memory-analytics.ts

@@ -358,7 +358,7 @@ const CUBE_OPERATOR_TO_MONGO_PREDICATE: Readonly<Record<CubeOperator, MongoPredi
   // builds for `$notContains` (`memory-driver.ts` `normalizeFieldOperators`) —
   // and, since #20874, the SAME test it builds, membership or substring.
   notContains: ({ raw, containment }) => ({ $not: containment(raw[0]) }),
-  // [#13195] A presence flag, not a comparand — and "present" means HAS A
+  // [commit 9dac1ae01] A presence flag, not a comparand — and "present" means HAS A
   // VALUE (`!= null`), never key presence: #5298 leg 3 / #5369, landed in PR
   // #5962, ruled onto this face 2026-08-30. It used to emit `{$exists: <bool>}`
   // and hand it to mingo, which reads key presence, so this exit EXECUTED the
@@ -555,7 +555,7 @@ function globSubstringPattern(value: unknown): string {
  * `memory-analytics-echo-operator-coverage.test.ts` so it could not be closed
  * in silence.
  *
- * [#13195] It was not closed in silence: the maintainer ruled on 2026-08-30
+ * [commit 9dac1ae01] It was not closed in silence: the maintainer ruled on 2026-08-30
  * that `$exists` means HAS A VALUE (`!= null`) on every exit — #5298 leg 3 /
  * #5369, shipped in PR #5962 and until then still unmet here — so the mingo
  * twin now emits `{$ne: null}` / `{$eq: null}`. SQL's `IS NOT NULL` was already
@@ -660,7 +660,7 @@ function sizeDistinctSet(values: readonly unknown[]): number {
 }
 
 /**
- * [#11065] `path`, with a BOOLEAN rendered as the number it is worth — the
+ * [commit 20950404c] `path`, with a BOOLEAN rendered as the number it is worth — the
  * aggregand expression `$sum` and `$avg` consume on this face, and, since the
  * #11152 ruling (maintainer 2026-08-28: booleans aggregate as numbers on every
  * face, no per-aggregate exception), `$min` and `$max` as well.

packages/drivers/driver-memory/src/memory-boolean-aggregand.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * [#11065] `avg` and `sum` over a BOOLEAN column answer the SQL number here too.
+ * [commit 20950404c] `avg` and `sum` over a BOOLEAN column answer the SQL number here too.
  *
  * ## The measurement this file pins
  *
@@ -248,7 +248,7 @@ describe('[#11065] InMemoryDriver data face — a boolean aggregand is worth 1 o
  *
  * It reaches the numbers by a different route — a mingo `$group` expression
  * rather than JavaScript — and mingo's `$avg` ignores a non-numeric value
- * exactly as MongoDB's does, so before #11065 this face had the identical
+ * exactly as MongoDB's does, so before commit 20950404c this face had the identical
  * divergence on its own account: `{avg: null, sum: 0}` over the same five rows.
  * Aligning the data face alone would have left it free to keep that answer,
  * which is the same mistake #6814 recorded on `count_distinct`.

packages/drivers/driver-memory/src/memory-bulk-create-atomicity.test.ts

@@ -20,12 +20,12 @@
  * ```
  *
  * ⛔ Asserting "the refusal still happens" proves NOTHING here — the refusal
- * was already correct, and #13197 / #13239 already pin it. That assertion was
+ * was already correct, and commit 56c093c4d / #13239 already pin it. That assertion was
  * green throughout the defect's entire life. **The discriminating fact is that
  * THE ROW COUNT DOES NOT MOVE**, so every test below reads the store after the
  * refusal rather than stopping at the envelope.
  *
- * The fix is `updateMany`'s posture, one method over: #13197 made that method
+ * The fix is `updateMany`'s posture, one method over: commit 56c093c4d made that method
  * prepare and check every row before mutating any of it, precisely so a
  * half-applied batch cannot happen. The two batch paths of this driver now
  * give the SAME answer to "is a batch atomic?" — they disagreed for as long as