Merge remote-tracking branch 'origin/main' into claude/issue-14967-governed-review-request-patrol

Author: claude

.changeset/core-private-keys-pin-extension-boundary.md

@@ -0,0 +1,44 @@
+---
+"@objectstack/core": patch
+---
+
+fix(core): narrow the operation-private-keys pin's scanner to `.ts`, so it judges exactly the population turbo re-runs it for (#15090)
+
+`packages/core/src/security/operation-private-keys.pin.test.ts` filtered its
+candidate set with `/\.tsx?$/` — `.ts` **and** `.tsx` — while this package's
+declared radius in the cross-package declaration table is a `packages/**`
+subtree glob ending in `.ts`. So the pin judged a population **strictly wider**
+than the one either scoping layer of `check:cross-package-test-inputs` knows
+about: Layer A never unions this package into the test shard when a `.tsx` file
+changes, and Layer B never moves the `test` task's cache hash for one. A `.tsx`
+file under `packages/` declaring its own `OPERATION_PRIVATE_KEY_PREFIX` or
+`withoutOperationPrivateKeys` was therefore scanned by the pin and invisible to
+CI's scoping — landing on `main` with every PR green and then reddening whichever
+unrelated PR next touched a `.ts` file. That is the #7802 shape the declaration
+table exists to close, one extension wide.
+
+Repaired by narrowing the **scanner**, not by widening the **glob** — and that
+asymmetry is measured rather than assumed. On `b548e438d`, adding a `.tsx` glob
+to this package's roster entry and re-deriving `check:cross-package-test-inputs`'
+watch hints flips the dispatch-gates self-test case *"nor a .tsx test file inside
+it"* from true to false, with the added glob itself as the covering hint. That
+case is a live specimen for "a test class the hint route cannot reach", so the
+red is real and re-pointing it is a decision in another lane, not a fixup.
+
+What the boundary costs, measured on the pin's own surface (tracked **plus**
+untracked, ignored paths excluded) at `b548e438d`: **5408** `.ts` files scanned,
+8 of them mentioning a guarded symbol; **8** `.tsx` files excluded, **0** of them
+mentioning either symbol. The loss is empty today — and that reading is no longer
+transcribed and trusted. A new case re-measures it on every run: it asserts the
+excluded `.tsx` population is non-empty (so the boundary is an exclusion and not
+an empty tree describing itself), that the filter really drops those files, and
+that none of them declares either symbol. Ablation, with the restore proven by
+blob hash rather than by exit code: re-widening the scanner reddens it while the
+offender assertion stays green — which is precisely the failure mode, since a
+wider scanner reads as coverage CI never runs — and planting a `.tsx`
+redeclaration reddens it with a message that says the choice is a second-gate
+trade, not a one-line widening.
+
+The correspondence between scanner and glob is now stated at **both** ends: the
+pin's header and the declaration table's entry for this package. No published
+surface moves — the only source file edited is a test.

.changeset/driver-memory-find-findone-create-honest-types.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/driver-memory': minor
+---
+
+fix(driver-memory): `find()`, `findOne()` and `create()` publish their declared types (#14435)
+
+**BREAKING** for TypeScript consumers — a published TYPE-surface narrowing, the same shape #13878 landed on `update()` / `upsert()` one door over, shipped as `minor` under the launch-window convention (`major` is refused by `check-changeset-no-major`, so the BREAKING banner and the ADR-0087 disposition are the carriers, not the level).
+
+`IDataDriver` has always declared `Promise<Record<string, unknown>[]>`, `Promise<Record<string, unknown> | null>` and `Promise<Record<string, unknown>>` on these three doors. The emitted `.d.ts` published `Promise<any[]>`, `Promise<any>` and `Promise<Record<string, any>>`: the return types of `find` and `findOne` were INFERRED through the backing store's `any[]` rows (`private db: Record<string, any[]>` to `getTable()`), and `create` carried an explicit annotation that itself spelled `Record<string, any>`. They are now declared as the contract declares them.
+
+What this asks of a consumer holding a concrete `InMemoryDriver`: a caller that reads fields off a `findOne()` result narrows the `null` arm first — the arm the driver has always been able to answer with (`results[0] || null`) and that no caller was ever asked to handle; and a caller that leaned on `any` to read a member off a `find()` row or a `create()` result now types it, since the rows are `Record<string, unknown>`. A consumer whose receiver is typed as `IDataDriver` sees no change at all — that declaration already said this.
+
+The parameters are deliberately untouched: `create(data: Record<string, any>)` stays as it is, because narrowing an INPUT would be a second, unrelated break, and method parameters compare bivariantly against the contract's `Record<string, unknown>`. No runtime behaviour changes; the store keeps its `any[]` rows, which the card measured to cascade if re-typed.
+
+<!-- adr-0087: not-required (no-migration-prescription) A published return type moves off `any` onto the contract's own shape: no metadata key is removed, renamed or re-shaped, no spec schema changes (this diff touches `packages/drivers/driver-memory/**` only), and nothing exists for `objectstack migrate meta` to rewrite. The obligation is a TypeScript narrowing at the consumer's call site, delivered by the compiler. -->

content/docs/data-modeling/field-types.mdx

@@ -653,7 +653,7 @@ These properties are available on **all** field types:
 | `description` | `string` | — | Field description / help text |
 | `type` | `FieldType` | **required** | One of the supported field types |
 | `required` | `boolean` | `false` | Whether the field is required |
-| `unique` | `boolean \| 'global' \| 'organization'` | `false` | Unique constraint **and its scope** (ADR-0120). `'organization'` = one holder per organization; `true` = that same per-organization scope (positional synonym — prefer the explicit spelling in new code); `'global'` = one holder across the whole installation; `false` = no constraint. `'tenant'`/`'org'` are rejected — the word is `'organization'`. Full rule in the `unique` doc block in [`FieldSchema`](/docs/references/data/field) |
+| `unique` | `boolean \| 'global' \| 'organization'` | `false` (`'organization'` on `autonumber`) | Unique constraint **and its scope** (ADR-0120). `'organization'` = one holder per organization; `true` = that same per-organization scope (positional synonym — prefer the explicit spelling in new code); `'global'` = one holder across the whole installation; `false` = no constraint. Omitted ⇒ `false`, except on an `autonumber` field, where omitted ⇒ `'organization'` — an auto-number is a business identifier, so the platform makes it unique per organization by default; write `unique: false` explicitly to opt out. `'tenant'`/`'org'` are rejected — the word is `'organization'`. Full rule in the `unique` doc block in [`FieldSchema`](/docs/references/data/field) |
 | `multiple` | `boolean` | `false` | Allow array of values (multi-record lookup, multi-select, multi-file). An emptied multi-value lookup reads back as `[]`, never `null` — the `multiple` doc block in [`FieldSchema`](/docs/references/data/field) |
 | `searchable` | `boolean` | `false` | Include in search index |
 | `sortable` | `boolean` | `true` | Allow sorting by this field |

packages/core/src/security/operation-private-keys.pin.test.ts

@@ -155,13 +155,69 @@ function git(args: string[]): string[] {
   return stdout.split('\0').filter((line) => line.length > 0);
 }
 
-const isScannedSource = (path: string) => /\.tsx?$/.test(path) && !path.endsWith('.d.ts');
+/**
+ * ── The EXTENSION boundary is `.ts` ALONE, and unlike the tree it is not free ──
+ *
+ * `.ts` and NOT `.tsx`, which is what this filter said first (`/\.tsx?$/`, one
+ * character wide). The population this pin JUDGES has to equal the population
+ * turbo RE-RUNS it for, and the second of those is declared somewhere else: the
+ * radius roster entry for `@objectstack/core` in the declaration table at
+ * scripts/cross-package-test-inputs.mjs declares a `packages/**` subtree glob
+ * ending in `.ts`, which does not cover `.tsx`.
+ *
+ * A scanner wider than that glob judges files neither scoping layer of
+ * `check:cross-package-test-inputs` can see. Layer A never unions this package
+ * into the test shard when the diff touches one of them; Layer B never moves
+ * this package's `test` task cache hash for one of them. So a `.tsx` file under
+ * packages/ that declared its own copy would be scanned by this pin and
+ * invisible to both — landing on `main` with every PR reporting green, and then
+ * reddening whichever unrelated PR next touches a `.ts` file. That is #7802's
+ * shape, one extension wide, and it is exactly what the declaration table
+ * exists to prevent.
+ *
+ * ⛔ The repair is to narrow the SCANNER, never to widen the GLOB — the two
+ * directions are not symmetric. Those globs are INHERITED as watch hints by
+ * `check:cross-package-test-inputs`, and a self-test in the dispatch-gates tool
+ * pins that no hint of that family reaches the realtime-hooks test file — the
+ * `.tsx` one — in the client-react package, its live specimen for "a test class
+ * the hint route cannot reach". Measured on b548e438d rather than reasoned:
+ * with that same subtree glob ending in `.tsx` added to this package's roster
+ * entry and that family's hints re-derived, the case flipped from true to false
+ * and the added glob was itself the covering hint. It is a real red and not a
+ * nuisance — the specimen is how that tool proves its residue classes are not
+ * empty — and re-pointing it is an edit in another lane. ⇒ Extensions and glob
+ * widen together or not at all; the sibling pin in `@objectstack/types` records
+ * the same trade from the other side of it.
+ *
+ * (That specimen is named in two halves rather than as one quoted path on
+ * purpose. `check:cross-package-test-inputs` collects quoted whole
+ * repo-relative paths out of this file's source, COMMENTS INCLUDED, into the
+ * roster it demands the declared globs cover — so spelling it here in one
+ * quoted piece would demand the very `.tsx` glob this paragraph exists to
+ * forbid. Measured the same way.)
+ *
+ * ⚠️ What narrowing GIVES UP, measured rather than assumed. Under packages/ on
+ * b548e438d, over this pin's own surface (tracked PLUS untracked, ignored paths
+ * excluded), against this pin's own two symbols:
+ *
+ *     .ts    5408 files, 8 mention a guarded symbol   <- scanned
+ *     .tsx      8 files, 0 mention a guarded symbol   <- excluded
+ *
+ * ⇒ the loss is empty today. ⛔ That reading is not transcribed and then
+ * trusted: the last test below RE-MEASURES it on every run, because a count
+ * with a commit on it is honest and a count without one rots silently. The day
+ * a `.tsx` file under packages/ declares either symbol, that case goes red and
+ * says what the choice actually is — which is not "widen this filter".
+ */
+const isScannedSource = (path: string) => path.endsWith('.ts') && !path.endsWith('.d.ts');
 
 /**
- * The scan surface: every `.ts`/`.tsx` file under `packages/` that a human
- * authored — tracked plus untracked, ignored paths (build output) excluded.
+ * Every file under `packages/` that a human authored — tracked plus untracked,
+ * ignored paths (build output) excluded — BEFORE the extension boundary. Split
+ * out from `scannedFiles()` so the boundary has something to be measured
+ * against: a filter is only an exclusion while the set it filters is non-empty.
  */
-function scannedFiles(): string[] {
+function authoredPaths(): string[] {
   return git([
     'ls-files',
     '-z',
@@ -170,15 +226,22 @@ function scannedFiles(): string[] {
     '--exclude-standard',
     '--',
     'packages',
-  ]).filter(isScannedSource);
+  ]);
+}
+
+/** The scan surface: the authored files the extension boundary above admits. */
+function scannedFiles(): string[] {
+  return authoredPaths().filter(isScannedSource);
 }
 
 /**
- * The subset of the scan surface that so much as mentions either identifier.
- * Fixed-string, so it is an exact superset of `declarationMatcher()`'s matches; the regex
- * still decides which of these — if any — is an actual declaration.
+ * Every path the fixed-string prefilter returns, BEFORE the extension boundary
+ * — so it includes the `.tsx` (and `.md`, and config) files the scan does not
+ * judge. Split out for the same reason as `authoredPaths()`: the trade the
+ * boundary rests on is a claim about the files it drops, and a claim about
+ * dropped files cannot be made from the set they were dropped from.
  */
-function filesMentioningASymbol(): string[] {
+function prefilterHits(): string[] {
   return git([
     'grep',
     '--files-with-matches',
@@ -192,7 +255,16 @@ function filesMentioningASymbol(): string[] {
     HELPER_SYMBOL,
     '--',
     'packages',
-  ]).filter(isScannedSource);
+  ]);
+}
+
+/**
+ * The subset of the scan surface that so much as mentions either identifier.
+ * Fixed-string, so it is an exact superset of `declarationMatcher()`'s matches; the regex
+ * still decides which of these — if any — is an actual declaration.
+ */
+function filesMentioningASymbol(): string[] {
+  return prefilterHits().filter(isScannedSource);
 }
 
 function declaringFiles(): string[] {
@@ -297,4 +369,73 @@ describe('the `__` operation-private-key convention has one owner (#7284)', () =
     },
     SCAN_TIMEOUT_MS,
   );
+
+  it(
+    'the extension boundary is `.ts` alone, and the trade that buys it has not expired',
+    () => {
+      // The executable half of the EXTENSION boundary section on
+      // `isScannedSource`. That paragraph is the only thing keeping the judged
+      // population equal to the population turbo re-runs this pin for, and
+      // #9763 is the day a radius held by prose alone came unforced by an
+      // innocent reword. Three claims, in the order they can go false.
+
+      // 1. THE EXCLUSION IS REAL. `.tsx` files exist under packages/, so "the
+      //    scan sees none" is an exclusion and not an empty tree describing
+      //    itself — #4690's shape, applied to the boundary rather than to the
+      //    offender set.
+      const excluded = authoredPaths().filter((file) => file.endsWith('.tsx'));
+
+      expect(
+        excluded.length,
+        'No `.tsx` file exists under packages/ at all, so the extension boundary '
+          + 'below excludes nothing and this case proves nothing. Re-measure the '
+          + 'trade in the header before trusting it.',
+      ).toBeGreaterThan(0);
+
+      // 2. …AND THE FILTER REALLY DROPS THEM. Re-widen `isScannedSource` and
+      //    this is what goes red first, in the same run that the offender test
+      //    above stays green — which is the whole point: widening the scanner
+      //    alone reads as coverage while turbo never re-runs this pin for the
+      //    files it has started to judge.
+      expect(
+        scannedFiles().filter((file) => file.endsWith('.tsx')),
+        'The scan surface has grown `.tsx` files back. The declared radius for '
+          + 'this package covers `.ts` only, so these are judged by a pin that '
+          + 'CI will not re-run when they change. Narrow the filter back, or '
+          + 'widen the glob too — and read the header first, because the second '
+          + 'half of that is a trade with another gate, not a formality.',
+      ).toEqual([]);
+
+      // 3. THE TRADE ITSELF, re-measured rather than transcribed. The boundary
+      //    gives up naming a `.tsx` redeclaration as an offender; that costs
+      //    nothing only while no excluded file declares either symbol. The
+      //    header's counts carry a commit precisely because they rot — this is
+      //    the part that cannot.
+      const excludedDeclarations = prefilterHits()
+        .filter((file) => file.endsWith('.tsx'))
+        .filter((file) => declarationMatcher().test(readFileSync(join(REPO_ROOT, file), 'utf8')));
+
+      expect(
+        excludedDeclarations,
+        excludedDeclarations.length === 0
+          ? ''
+          : [
+              'These `.tsx` files declare their own copy of the `__` operation-private-key',
+              'convention, and the extension boundary above means this pin no longer names',
+              'them as offenders:',
+              ...excludedDeclarations.map((f) => `  - ${f}`),
+              '',
+              'The trade recorded in this file\'s header has expired. ⛔ Do NOT simply widen',
+              '`isScannedSource` back to `.tsx`: that rebuilds the exact mismatch it was',
+              'narrowed to remove — a pin judging files CI never re-runs it for. Widening',
+              'the scanner is only HALF the change; this package\'s declared radius has to',
+              'widen with it, and that glob is inherited as a watch hint by a second gate',
+              'whose self-test owns a live `.tsx` specimen. Read the EXTENSION boundary',
+              'section above, then take it to whoever owns that tool — it is a decision,',
+              'not a one-line fix.',
+            ].join('\n'),
+      ).toEqual([]);
+    },
+    SCAN_TIMEOUT_MS,
+  );
 });

packages/drivers/driver-memory/src/memory-datetime-storage.test.ts

@@ -66,8 +66,14 @@ describe('InMemoryDriver Field.datetime storage (#4047)', () => {
       expect(typeof (row as any).created_at, `${(row as any).id} stored form`).toBe('string');
       expect((row as any).created_at).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
     }
-    const midnight = raw.find((r: any) => r.id === 'd_midnight');
-    expect(midnight.created_at).toBe('2026-07-28T00:00:00.000Z');
+    // `find()` now publishes the contract's `Record<string, unknown>[]`
+    // (#14435), so `Array.prototype.find` hands back the `undefined` arm it
+    // has always been able to produce. Narrowed rather than cast: the row
+    // being present is a real precondition of the assertion below, and while
+    // `raw` was `any[]` a missing row raised a TypeError instead of failing here.
+    const midnight = raw.find((r) => r.id === 'd_midnight');
+    expect(midnight, 'd_midnight seeded and returned by find()').toBeDefined();
+    expect(midnight!.created_at).toBe('2026-07-28T00:00:00.000Z');
   });
 
   it('a date window reaches rows written in BOTH forms', async () => {
@@ -173,7 +179,12 @@ describe('InMemoryDriver Field.datetime storage (#4047)', () => {
     }
     const all = await driver.find('task', {});
     for (const row of all) expect(typeof (row as any).created_on).toBe('string');
-    expect((all.find((r: any) => r.id === 'on_obj')).created_on).toBe('2026-07-28');
+    // Same narrowing as above (#14435): the `undefined` arm of
+    // `Array.prototype.find` is now visible, and the row's presence is an
+    // assertion in its own right rather than a TypeError waiting to happen.
+    const onObj = all.find((r) => r.id === 'on_obj');
+    expect(onObj, 'on_obj seeded and returned by find()').toBeDefined();
+    expect(onObj!.created_on).toBe('2026-07-28');
 
     const found = await driver.find('task', {
       where: { created_on: { $gte: '2026-04-29', $lte: '2026-07-28' } },