@ultimat3/query 31.6.1 → 31.7.0

package/CLAUDE.md

@@ -261,7 +261,8 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 ## Invariants — caching
 
 - **The request memo holds the read, not the rows**: `readOnce` publishes the in-flight promise
-  before its first await; a rejection is evicted. `requestMemo(ctx)` is `Map<string, Promise<unknown>>`.
+  before its first await; a rejection is evicted. `requestMemo(ctx)` is `memoFlights(ctx,
+  'query')` (`@ultimat3/cache`): one store, 8 MiB per ctx. Never a second `WeakMap` here.
 - **Every read is memoized; only a `cache:` read goes through the tier** (`readThrough`). One key
   function, `cacheKeyFor`, over the PARSED input `admitAndBuild` returns — never `raw`, or a
   stripped `?junk=N` is an entry and a read per N (`read-cache-key.test.ts`). Outside, a key

package/README.md

@@ -609,9 +609,15 @@ round trip. A rejection is evicted — a failed read is not the request's answer
 
 | Layer | Applies to | Lifetime |
 |---|---|---|
-| request memo (`readOnce`) | **every** query, `cache:` or not | the request — a `Ctx`'s identity is the key |
+| request memo (`readOnce`) | **every** query, `cache:` or not | the request — a `Ctx`'s identity is the key; at most `MEMO_MAX_BYTES` (8 MiB) per ctx, oldest evicted (a job attempt reading page after page) |
 | tag-keyed tier (`readThrough`) | a query that declares `cache:` | `ttlMs`, or until an `invalidates` fan-out drops the tag |
 
+**`requestMemo(ctx)` returns `MemoFlights`** (`@ultimat3/cache`), not a `Map` — `get`, `has`,
+`publish`, `bytes` over `memoFlights(ctx, 'query')`, the one per-ctx memo store. A caller that wrote
+`requestMemo(ctx).set(…)`/`.delete(…)` no longer compiles: publish with `readFresh(ctx, key, run)`,
+and let a rejection evict itself. A held read is charged by `approxBytes` — a bounded sample of
+the rows (≈2 µs for 50 or 500 rows), never a `JSON.stringify` (≈155 µs / 1.5 ms).
+
 `cache:` buys the tier, never the memo: an uncached lookup called once per row of a list would
 otherwise cost one round trip per row. Parsing, the policy and `sql()` still run on every call —
 the memo holds the execution, not the decision — and `.as()` reads in a child context, so an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "31.6.1",
+  "version": "31.7.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "keywords": [
     "ultimate",
@@ -49,12 +49,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "31.6.1",
-    "@ultimat3/core": "31.6.1",
-    "@ultimat3/db": "31.6.1",
-    "@ultimat3/entity": "31.6.1",
-    "@ultimat3/http": "31.6.1",
-    "@ultimat3/policy": "31.6.1",
-    "@ultimat3/schema": "31.6.1"
+    "@ultimat3/cache": "31.7.0",
+    "@ultimat3/core": "31.7.0",
+    "@ultimat3/db": "31.7.0",
+    "@ultimat3/entity": "31.7.0",
+    "@ultimat3/http": "31.7.0",
+    "@ultimat3/policy": "31.7.0",
+    "@ultimat3/schema": "31.7.0"
   }
 }

package/src/cache.ts

@@ -5,8 +5,8 @@
  * read gets the memo; the ladder is the half a query opts into.
  */
 
-import type { CacheStack, CacheTag, CacheTier } from '@ultimat3/cache';
-import { cacheStack, registeredTiers, tagKeys } from '@ultimat3/cache';
+import type { CacheStack, CacheTag, CacheTier, MemoFlights } from '@ultimat3/cache';
+import { cacheStack, memoFlights, registeredTiers, tagKeys } from '@ultimat3/cache';
 import type { Actor, Clock, Ctx } from '@ultimat3/core';
 import { assertNever, fingerprint } from '@ultimat3/core';
 
@@ -18,22 +18,18 @@ import { assertNever, fingerprint } from '@ultimat3/core';
 export const DEFAULT_READ_CACHE_TTL_MS = 60_000;
 
 /**
- * Request-scoped memo. Keyed by ctx identity so it dies with the request.
+ * Request-scoped memo: `@ultimat3/cache`'s per-ctx memo store, under its `MEMO_MAX_BYTES` bound —
+ * never a second store. Keyed by ctx identity so it dies with the request; bounded because a job's
+ * ctx is the whole attempt, and an unbounded memo held every page a backfill read until it ended.
  *
  * An entry is the read *in flight*, not its value: unsettled it is the answer a caller is
  * already waiting for, settled it is the answer. That is what makes two concurrent identical
  * reads one round trip — and it is why no sentinel is needed for a legitimately `undefined`
  * value, which a value-keyed memo cannot tell apart from a miss. A promise is never `undefined`.
+ * An evicted entry is one more read of the source, never a wrong answer.
  */
-const memos = new WeakMap<object, Map<string, Promise<unknown>>>();
-
-export function requestMemo(ctx: Ctx): Map<string, Promise<unknown>> {
-  const key: object = ctx;
-  const existing = memos.get(key);
-  if (existing !== undefined) return existing;
-  const created = new Map<string, Promise<unknown>>();
-  memos.set(key, created);
-  return created;
+export function requestMemo(ctx: Ctx): MemoFlights {
+  return memoFlights(ctx, 'query');
 }
 
 /**
@@ -153,28 +149,21 @@ export async function readOnce<T>(ctx: Ctx, key: string, run: () => Promise<T>):
  * the same request the answer this one just proved stale — so the guarantee would end at the one
  * call that asked for it.
  */
-export function readFresh<T>(ctx: Ctx, key: string, run: () => Promise<T>): Promise<T> {
-  return publish(requestMemo(ctx), key, run);
+export async function readFresh<T>(ctx: Ctx, key: string, run: () => Promise<T>): Promise<T> {
+  // `async`, so a `run` that throws synchronously rejects like every other failed read.
+  return await publish(requestMemo(ctx), key, run);
 }
 
-/** The read in flight: published before its first await, evicted if it rejects. */
-async function publish<T>(
-  memo: Map<string, Promise<unknown>>,
-  key: string,
-  run: () => Promise<T>,
-): Promise<T> {
+/**
+ * The read in flight: published before its first await. A rejection is not an answer, so the store
+ * drops it and a later read in the same request retries — only ours: a fresh read may have
+ * replaced this entry already, and evicting that one would discard a live answer (`holdValue`).
+ */
+function publish<T>(memo: MemoFlights, key: string, run: () => Promise<T>): Promise<T> {
   // Published before the first await, so a reader arriving in the same tick finds this read.
   const flight = run();
-  memo.set(key, flight);
-  try {
-    return await flight;
-  } catch (error) {
-    // A rejection is not an answer. Drop it so a later read in the same request retries
-    // instead of replaying one failure until the request ends. Only ours: a fresh read may have
-    // replaced this entry already, and evicting that one would discard a live answer.
-    if (memo.get(key) === flight) memo.delete(key);
-    throw error;
-  }
+  memo.publish(key, flight);
+  return flight;
 }
 
 /**