@ultimat3/query 3.0.0 → 4.1.0

package/CLAUDE.md

@@ -154,6 +154,10 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   `query.page(input, { first, after })` — a page is the read's own answer, not an imported helper.
   `src/index.ts` exports `Page` and `PaginateArgs` and not the function: re-exporting it would be
   a second way to ask for the thing `.page()` already does.
+- **A `RowProvider` may be a list, a sync function or an async one** (`As of 2026-08-19`).
+  `execute()` awaits whatever the function returns, so all three were always accepted at runtime —
+  the type declared only `() => Promise<readonly TRow[]>`, which refused a repo method already
+  holding its page and every in-memory fixture. `source.test.ts` pins all three.
 - **A cursor is a position, not a row.** `isAfterKey` in `source.ts` is the one definition of
   "after this position": `Builder.seek()` compiles it to SQL and `paginate()` applies it when a
   source cannot push the seek down. The fallback used to find the cursor's row by id and slice
@@ -213,10 +217,25 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   `["10", "100", "9"]`. `bigint` is the physical type of every `<p>_minor` column and
   `@ultimat3/entity`'s `count-by.ts` lists it as groupable, so the in-memory source, the live
   matcher and the seek fallback ALL disagreed with the database on any bigint-ordered read.
-  `shape-order.test.ts` is the pin: one case per `ColumnKind`, each asserting the order Postgres
-  returns, plus the NULL rule and the cursor round trip. The kind list is spelled out rather than
-  imported — `tsconfig.json` excludes `*.test.ts`, so a `satisfies Record<ColumnKind, …>` written
-  in a test is a type assertion `tsc` never reads; a runtime count is the enforceable half.
+  `shape-order.test.ts` is the pin, and `As of 2026-08` it reads a REAL kind list: `COLUMN_KINDS`
+  is the runtime array `@ultimat3/entity`'s `ColumnKind` derives from, and entity is tier 2 so a
+  test here may import it as a VALUE — which is what a `satisfies Record<ColumnKind, …>` could not
+  be, since `tsconfig.json` excludes `*.test.ts` and `tsc` never reads one. It had a spelled-out
+  list and `const COUNT = 9` beside a union of THIRTEEN members: `9 === 9`, a test that could not
+  fail, with `numeric`, `date`, `bytea` and `array` carrying no case at all.
+- **`numeric` and the TEXT form of `bigint` are a DECLARED gap here, and closing it is a
+  declaration change** (`shape-order.test.ts`, `As of 2026-08`). `@ultimat3/entity`'s `bigint()`
+  and `decimal()` hand digits back as strings, so `["9","10","100","2"]` sorts to
+  `["10","100","2","9"]` here and `["2","9","10","100"]` in the database — and a cursor's revived
+  `bigint` against a stored decimal string (`compareValues(9n, "10")` → `1`) cuts page two where
+  the database does not. It is **not** fixed by calling `@ultimat3/core`'s `compareDecimalText`
+  from `compareValues`: that function answers only for a caller holding the column's declared kind
+  (`@ultimat3/entity`'s `compareByKind`), and `QueryShape.orderBy` is a name and a direction —
+  nothing here can tell a `numeric` holding `"10"` from a `text` holding `"10"`, which Postgres
+  orders lexically, so a comparator guessing would trade one disagreement with the SQL it prints
+  for another. The fix is an `OrderKey` that carries a kind, from `sourceFor` down. Until then the
+  `DECLARED_GAP` block asserts both halves, so the gap cannot be silently re-discovered or
+  silently widened.
 - **A read's `input:` must survive a query STRING, and `query()` refuses one that cannot**
   (`input-shape.ts`, `X_QUERY_INPUT_UNENCODABLE`, `As of 2026-08`). `client.ts` encoded a nested
   member as `JSON.stringify(item)` and skipped a `null`, while `coerceQuery` has no inverse for
@@ -258,11 +277,23 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   `@ultimat3/http`. `tagKey` went with it: `serializeTag` under a second name, zero call sites.
   `@ultimat3/render` exports a *different* function under the same name (declaration order kept);
   never import that one here.
-- **A fingerprint is an identity, so two different inputs may not share one** (`stable.ts`).
-  `NaN`, `±Infinity` and JSON `null` all encoded as `'null'`, and `String(-0)` is `"0"` — so four
-  distinct inputs shared one read-cache entry and one cursor scope. They are bare tokens now
-  (`NaN`, `Infinity`, `-Infinity`, `-0`), which the `string` branch cannot spell because it always
-  quotes. Ordinary numbers are byte-identical, so no existing cursor scope moved.
+- **A fingerprint is an identity, so two different inputs may not share one — and it is
+  `@ultimat3/core`'s, not this package's, `As of 2026-08`.** `canonicalJson` + `fingerprint` moved
+  down to tier 0 because `@ultimat3/action` and `@ultimat3/realtime` needed the identical function
+  and all three are tier 3, so a copy in any of them was a second answer for the other two — and
+  the copies had already diverged. This one had **no `Date` branch**: `Object.keys(date)` is `[]`,
+  so the object branch rendered every date as `{}` and `queryHash({from: 2020…, to: 2020…})`
+  equalled `queryHash({from: 2026…, to: 2026…})`. Reachable on the ordinary HTTP path — `http.ts`
+  decodes a query string through `coerceQuery`, which turns a `t.date` member into a real `Date`,
+  and `input-shape.ts` permits `date` members — so ONE read-cache entry answered every date window
+  of that read for the TTL, page two of range A was served from range B's cursor scope, and every
+  date window shared one live query id. The hash form tags a `Date`, a `Map` and a `Set`
+  (`Date(<epoch>)`, `Map(…)`, `Set(…)`) beside the bare `NaN` / `±Infinity` / `-0` tokens it
+  already emitted, all for the reason a bare token exists: `'null'` collided with JSON `null` and
+  `String(-0)` is `"0"`. `stable.ts` keeps `isJsonObject`/`columnOf` and nothing else. Ordinary
+  inputs are byte-identical, so the durable-key cost is confined to reads whose input carries a
+  `Date`, a `Map` or a `Set`: those cursors answer `X_CURSOR_INVALID` once, and their cache entries
+  are cold once. `query-hash.test.ts` is the pin, at `queryHash` and at `cacheKeyFor`.
 - The cursor codec is `@ultimat3/core`'s (`encodeCursor` / `decodeCursor` / `configureCursorSigning`).
   This package supplies only the scope a cursor is bound to — `queryHash(name, input)` — and never
   signs, encodes or parses one itself. An unverified or foreign cursor is `X_CURSOR_INVALID`, thrown
@@ -289,19 +320,31 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   is the mechanism: declaring nothing gets the narrowest key. `'tenant'` and `'global'` are written
   statements about the rows — the `unenforced:` shape one field over — and `'tenant'` with no
   `orgId` narrows to the actor rather than widening to everyone, because nothing here can prove two
-  org-less callers share a tenant. The authority is JSON, never a joined string, for the reason
+  org-less callers share a tenant. **All THREE spellings of "no org" take that branch**, `As of
+  2026-08`: `undefined`, `''` and `null`. The last one missed it, so every org-less caller shared
+  the single key `["org",null]` and was served the rows of whoever asked first. `orgless()` widens
+  its parameter past core's `orgId?: string` because **`orgId` is a value off the wire** — an app's
+  adapter, a decoded session row, a JSON payload — not because a declared type permits a `null`.
+  `@ultimat3/policy`'s `PolicyActorFields` reads like the reason and is not it (corrected
+  2026-08-19): `Actor = CoreActor & PolicyActorFields`, and that intersection collapses its
+  `string | null | undefined` back to `string | undefined`, so the widening is **inert** at the type
+  level and `{ orgId: null }` is a type error. Its `testActor` mints `orgId: null` through the one
+  cast left in `packages/policy/src/test-kit.ts`, which is why `cache-authority.test.ts` can reach
+  this branch at all — the repo's only producer of that `null`, and a test seam rather than a proof.
+  The authority is JSON, never a joined string, for the reason
   `@ultimat3/entity`'s `scopeKey` gives: an actor id is app data and may carry the separator.
 - **`cache.ttlMs` is judged at `query()`, not on the first read.** Every `CacheTier` refuses a
   lease that is not positive and finite (`assertTtl`), and the read tier's one catch absorbs
   `X_CACHE_TOO_LARGE` only — so `ttlMs: Infinity` turned a typo into a permanently failing business
   read whose cause named a cache key. `X_QUERY_CACHE_TTL_INVALID`, on the line that wrote it. It
   restates `assertTtl`'s bar as a refusal and never as a second resolution.
-- **`fingerprint` is SHA-256/16, never a 32-bit hash** (`stable.ts`, `As of 2026-08`). It is a
+- **`fingerprint` is SHA-256/16, never a 32-bit hash** (`@ultimat3/core`, `As of 2026-08`). It is a
   SHARING key over client-chosen input — which read-cache entry two callers are served from, which
   scope a cursor is bound to — so FNV-1a/32's 4×10⁹ values are a collision found offline in
-  seconds. Same primitive and width as `@ultimat3/realtime`'s `stableDigest`. `stableStringify` did
-  not move, so the only cost is one cold cache and every open cursor answering `X_CURSOR_INVALID`
-  with its own "request the first page again" fix.
+  seconds. `@ultimat3/realtime`'s `stableDigest` was the same primitive at the same width and is
+  gone with the rest of that copy: a `qid` is `queryHash(name, input)` now, imported across the
+  declared `realtime -> query` edge, so the two hashes cannot drift apart while `planResume`
+  compares one against a cursor's.
 - **A fill is FENCED, and the fence is `@ultimat3/cache`'s** (`As of 2026-08`). `run()` answers with
   rows it read in the past: a mutator committing in between busts a key not yet in the tier, so the
   drop is a no-op reporting `errors: []`, and the fill then publishes the pre-write rows for the

package/README.md

@@ -143,13 +143,20 @@ the package, and rotating the secret is what invalidates every open cursor. This
 the only thing that is its business — the scope, `queryHash(name, input)` — and re-exports
 `CursorInvalidError` so the failure keeps its name on this surface.
 
-The scope's hash is **SHA-256, first 16 hex** (`fingerprint` in `stable.ts`), the primitive and
-width `@ultimat3/realtime`'s `stableDigest` and `@ultimat3/entity`'s `planScope` already use. It
-was FNV-1a/32 until 2026-08 — 4×10⁹ values over input a client chooses, brute-forceable offline in
-seconds, and a fingerprint here is a *sharing* key: which read-cache entry two callers are served
-from, and which scope a cursor is bound to. The canonical serialization did not change, only the
-hash, so a cursor issued before it fails its scope check as `X_CURSOR_INVALID` with "request the
-first page again" as its fix, and a warm read cache is cold once.
+The scope's hash is **SHA-256, first 16 hex** — `fingerprint` from `@ultimat3/core`, the primitive
+and width `@ultimat3/entity`'s `planScope` already uses, and the same function
+`@ultimat3/action`'s `requestHash` and `@ultimat3/realtime`'s `qid` are taken over `As of 2026-08`.
+It was FNV-1a/32 until 2026-08 — 4×10⁹ values over input a client chooses, brute-forceable offline
+in seconds, and a fingerprint here is a *sharing* key: which read-cache entry two callers are served
+from, and which scope a cursor is bound to.
+
+The canonical form is **injective**, which is the other half of the same requirement. It had no
+`Date` branch until 2026-08: `Object.keys(date)` is `[]`, so every date rendered `{}` and one key
+answered for every date window a read ever served — a real leak on the ordinary HTTP path, since
+`coerceQuery` turns a `t.date` member into a `Date` and `input-shape.ts` permits `date` members. A
+`Date`, a `Map` and a `Set` are tagged now. Ordinary inputs are byte-identical, so the cost is
+confined to reads whose input carries one of the three: those cursors answer `X_CURSOR_INVALID`
+once, with "request the first page again" as their fix, and their cache entries are cold once.
 
 A cursor names a **position in the ordering**, never a row and never a count. Both seek paths
 answer "is this row after that position?" through the one predicate, `isAfterKey`: `Builder.seek()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "3.0.0",
+  "version": "4.1.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -31,10 +31,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "3.0.0",
-    "@ultimat3/core": "3.0.0",
-    "@ultimat3/http": "3.0.0",
-    "@ultimat3/policy": "3.0.0",
-    "@ultimat3/schema": "3.0.0"
+    "@ultimat3/cache": "4.1.0",
+    "@ultimat3/core": "4.1.0",
+    "@ultimat3/http": "4.1.0",
+    "@ultimat3/policy": "4.1.0",
+    "@ultimat3/schema": "4.1.0"
   }
 }

package/src/cache.ts

@@ -8,8 +8,7 @@
 import type { CacheStack, CacheTag, CacheTier } from '@ultimat3/cache';
 import { createCacheStack, registeredTiers, tagKeys } from '@ultimat3/cache';
 import type { Actor, Clock, Ctx } from '@ultimat3/core';
-import { assertNever } from '@ultimat3/core';
-import { fingerprint } from './stable';
+import { assertNever, fingerprint } from '@ultimat3/core';
 
 /**
  * A `cache:` block with no `ttlMs`. Tag invalidation is the primary eviction, so this is the
@@ -47,6 +46,24 @@ export function requestMemo(ctx: Ctx): Map<string, Promise<unknown>> {
  */
 export type QueryCacheScope = 'actor' | 'tenant' | 'global';
 
+/**
+ * "This actor is inside no org", in all three spellings it arrives in. The parameter is widened
+ * past core's `Actor.orgId` (`string | undefined`) because `orgId` is a value off the wire, not a
+ * value this process minted: an app's own adapter, a decoded session row or a JSON payload can put
+ * a `null` here, and it used to miss the `undefined`/`''` test below — which handed every org-less
+ * caller the single shared key `["org",null]` and served each one the rows of whoever asked first.
+ * `actorAuthority` already wrote `?? null` for the same reason.
+ *
+ * `@ultimat3/policy`'s `PolicyActorFields` is NOT the justification, though it reads like one:
+ * `Actor = CoreActor & PolicyActorFields`, and that intersection collapses its
+ * `string | null | undefined` back to core's `string | undefined`, so the widening is inert at the
+ * type level. Its `testActor` mints `orgId: null` through the one cast left in that file, which is
+ * why `cache-authority.test.ts` can exercise this branch at all — a test producer, not a proof
+ * that the declared type permits one.
+ */
+const orgless = (orgId: string | null | undefined): boolean =>
+  orgId === undefined || orgId === null || orgId === '';
+
 /**
  * The authority a read was answered under, as a key component.
  *
@@ -67,9 +84,8 @@ export function readAuthority(actor: Actor, scope: QueryCacheScope): string {
       // An actor inside no org is not a shared tenant. Nothing here can prove two org-less callers
       // see the same rows, so the key narrows to the actor rather than widening to everyone —
       // declining instead of guessing, which is the only safe direction for a sharing key.
-      return actor.orgId === undefined || actor.orgId === ''
-        ? actorAuthority(actor)
-        : JSON.stringify(['org', actor.orgId]);
+      //
+      return orgless(actor.orgId) ? actorAuthority(actor) : JSON.stringify(['org', actor.orgId]);
     case 'actor':
       return actorAuthority(actor);
     default:

package/src/query.ts

@@ -9,6 +9,7 @@
 import type { CacheTag } from '@ultimat3/cache';
 import { tagKeys } from '@ultimat3/cache';
 import type { Actor, Ctx } from '@ultimat3/core';
+import { fingerprint } from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { QueryCacheScope } from './cache';
 import type { QueryClientMethod, QueryClientOptions } from './client';
@@ -23,7 +24,6 @@ import type { QueryPolicy, QuerySurface } from './policy-gate';
 import { policyCapability, policyPermissions } from './policy-gate';
 import { hasDef, queryName, runQuery, stashDef } from './read';
 import type { SqlSource } from './source';
-import { fingerprint } from './stable';
 
 export interface QueryCache {
   /** Tags this read depends on. An action's `invalidates` drops exactly these keys. */

package/src/source.ts

@@ -35,7 +35,15 @@ export interface SqlSource<TRow> {
   seek?(after: SeekKey | null, limit: number): SqlSource<TRow>;
 }
 
-export type RowProvider<TRow> = readonly TRow[] | (() => Promise<readonly TRow[]>);
+/**
+ * Rows, or a function that answers them. The function half is `readonly TRow[] | Promise<…>`
+ * because `execute()` **awaits** whatever it returns — declaring only the promise refused a
+ * synchronous provider the implementation has always accepted, which is a repo method that
+ * already has its page in hand, and every in-memory fixture.
+ */
+export type RowProvider<TRow> =
+  | readonly TRow[]
+  | (() => readonly TRow[] | Promise<readonly TRow[]>);
 
 /**
  * In-memory reference source. `from<Post>('posts', rows).where({ orgId }).orderBy('createdAt')`

package/src/sql.ts

@@ -59,7 +59,9 @@ export async function describeSql(
   const entries: QuerySqlInfo[] = [];
   for (const target of queries) {
     const name = queryName(target);
-    const sample = samples[name];
+    // `Object.hasOwn`, because `samples` is a caller's object literal and a name it never carried
+    // — `constructor`, `toString` — would otherwise resolve to a FUNCTION and be parsed as input.
+    const sample = Object.hasOwn(samples, name) ? samples[name] : undefined;
     if (sample === undefined) {
       entries.push({ query: name, live: target.isLive, sql: null });
       continue;

package/src/stable.ts

@@ -1,65 +1,17 @@
 /**
- * Deterministic JSON plus a content hash. Query hashes, cursor payloads and
- * cache keys all need byte-stable serialization, so nothing here may depend on
- * key insertion order.
+ * What a JSON object IS to this package, and how a column is read off a row that declares no index
+ * signature. Two small predicates the read path needs everywhere.
+ *
+ * The deterministic-JSON half used to live here and no longer does: `canonicalJson` and
+ * `fingerprint` are `@ultimat3/core`'s, because `@ultimat3/action` and `@ultimat3/realtime` need
+ * the identical function and all three are tier 3 — so a copy in any of them was a second answer
+ * for the other two, and the copies had already diverged. This one rendered every `Date` as `{}`.
  */
 
 export function isJsonObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-export function stableStringify(value: unknown): string {
-  if (value === null) return 'null';
-  switch (typeof value) {
-    case 'string':
-      return JSON.stringify(value);
-    // A bare token, never `'null'` and never a quoted string: this output is only ever hashed, so
-    // an unquoted word cannot collide with the `string` branch (which always quotes) while
-    // `'null'` collided with JSON `null` itself — `{ n: NaN }`, `{ n: Infinity }` and `{ n: null }`
-    // fingerprinted identically and shared one cache entry and one cursor scope. `-0` is spelled
-    // out for the same reason: `String(-0)` is `"0"`, so `-0` and `0` were one key too.
-    case 'number':
-      if (Number.isNaN(value)) return 'NaN';
-      if (!Number.isFinite(value)) return value > 0 ? 'Infinity' : '-Infinity';
-      return Object.is(value, -0) ? '-0' : String(value);
-    case 'boolean':
-      return String(value);
-    case 'bigint':
-      return JSON.stringify(`${value}n`);
-    case 'undefined':
-    case 'function':
-    case 'symbol':
-      return 'null';
-    default:
-      break;
-  }
-  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
-  const record = value as Record<string, unknown>;
-  const keys = Object.keys(record)
-    .filter((key) => record[key] !== undefined)
-    .sort();
-  const entries = keys.map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`);
-  return `{${entries.join(',')}}`;
-}
-
-/**
- * SHA-256, first 16 hex characters — the same primitive and the same width `@ultimat3/realtime`'s
- * `stableDigest` and `@ultimat3/entity`'s `planScope` already chose, and for the same reason.
- *
- * A fingerprint is a SHARING key, not a checksum: it decides which read-cache entry two callers
- * are served from and which scope a cursor is bound to, over input a client chooses. FNV-1a/32 —
- * what this was — is 4x10^9 values, brute-forceable offline in seconds, so an attacker could mint
- * an input that lands on another read's entry or another page's scope. It identifies, and here
- * identifying IS the boundary.
- *
- * The canonical form above is unchanged, so the only thing that moved is the hash: a cursor issued
- * before this fails its scope check as `X_CURSOR_INVALID` — cleanly, with "request the first page
- * again" as its fix — and a warm read cache is cold once.
- */
-export function fingerprint(value: unknown): string {
-  return new Bun.CryptoHasher('sha256').update(stableStringify(value)).digest('hex').slice(0, 16);
-}
-
 /** Column read that works for interfaces without an index signature. */
 export function columnOf(row: object, column: string): unknown {
   const record: unknown = row;