@ultimat3/entity 3.0.0 → 4.1.0

package/CLAUDE.md

@@ -29,6 +29,38 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `pg-driver-bulk.live.test.ts`, `pg-driver-tenancy.live.test.ts`). A method with only the first is
   unproven against Postgres itself; a method with only the second is unproven against memory. Both
   are the bar, not either one.
+- **What a PREDICATE means is decided by the column's declared KIND, and `memory-match.ts` is
+  where that one meaning is written.** The database decides by the column's type, so a driver
+  deciding by the JS `typeof` of the value in hand is answering a different question — four rules,
+  each of them a place the two drivers used to disagree, `As of 2026-08`. **A decimal-string column
+  orders by its digits**: `bigint()` and `decimal()` both hand back a STRING (deliberately —
+  `JSON.stringify` throws on a `bigint` and a `number` loses digits past 2^53), so neither the
+  `number`/`number` branch nor the `bigint`/`bigint` branch fired and both fell to
+  `String(left) < String(right)` — `["10","100","2","9"]` against Postgres' `2, 9, 10, 100`, and a
+  keyset page cut where the database cuts none, since the seek compares the stored string against
+  a revived `BigInt`. The comparison is exact at any width (the fractions are padded and both sides
+  become one integer), which no `Number()` is — and `As of 2026-08` it is **`@ultimat3/core`'s
+  `compareDecimalText`**, not this file's, because the text arrives in more than one package while
+  the declared kind does not. What stays here is `DECIMAL_TEXT` (which kinds are decimal text) and
+  the decision to ask; core's function answers `undefined` for a pair that is not two plain
+  decimals, so a caller with no kinds — `@ultimat3/query`, whose `OrderKey` is a name and a
+  direction — deliberately never calls it: Postgres orders a `text` column of digits lexically, and
+  a comparator guessing "both sides look like decimals" would trade this agreement for that
+  disagreement. That residual gap is `@ultimat3/query`'s `shape-order.test.ts` `DECLARED_GAP`. **A `uuid` is a VALUE**: Postgres parses it and
+  prints it lower-cased, so `findById(UPPER)` reads the row there and answered `null` here, and
+  `update(UPPER)` was `X_NOT_FOUND` against a row that exists — `keyOf(kind, value)`
+  (`batch-read.ts`), which already carried that rule for a batched read, now spells the memory
+  store's key and its equality too. Text is NOT narrowed: lower-casing it would merge two rows
+  Postgres keeps apart. **A `LIKE` pattern uses Postgres' default escape**: `\` escapes `%`, `_`
+  or itself, so `like 'a\%b'` matches the literal `a%b` in both drivers rather than
+  `a\<anything>b` in one — and a pattern ending in the escape character is refused here as
+  Postgres refuses it (`22025`). A RUN of `%` is still one `.*`: twenty adjacent `.*` groups in an
+  anchored regex is a CPU stall on a filter value forwarded from a search box. **`in` takes a list
+  or nothing**, in both drivers and in `@ultimat3/query`: a scalar operand matches NO rows (it was
+  wrapped into a one-element list for the SQL and refused in memory — 0 rows against one driver, 1
+  against the other, from a call `andWhere(column, op, value: unknown)` compiles), and a list
+  carrying a NULL emits `(col in (…) or col is null)` — `col = null` is UNKNOWN, so the null row
+  the caller listed was the one row Postgres left out while memory included it.
 - **The Postgres driver is proved against a real Postgres, not only against a recording client.**
   `pg-driver.live.test.ts` runs the whole chain — `entity()` -> `$describe()` ->
   `generateMigration()` -> a live server -> `postgresDriver()` -> decoded row — and skips when no
@@ -74,9 +106,15 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   calls `forgetPreloaded(entity.$name)` *before* the statement, so a row a request changed is
   re-read and never served from a page read before it. **Values, not rows**: the index is keyed by
   id and holds ids, so a page early in a long request pins its keys and not its rows, and it dies
-  with the request like every other per-ctx store here. **Declining is the old behaviour**: no
-  request in scope, an id no page indexed, a key that resolved to nothing — the caller reads the
-  statement it always read. `MAX_IDS_PER_STATEMENT` bounds the preload exactly as it bounds a
+  with the request like every other per-ctx store here. **And the store itself is BOUNDED**
+  (`MAX_SIBLING_KEYS`, four statements' worth), `As of 2026-08`: "dies with the request" is a job's
+  whole attempt, `MAX_IDS_PER_STATEMENT` bounded the statement and nothing bounded the store, and
+  1,000 pages x 1,000 distinct keys measured **159.3 MB retained** against a 2.7 MB control — ~2 GB
+  on a 12M-row `backfill()`, an OOM in the worker on the DEFAULT configuration, since `jitPreload`
+  defaults to true and `backfill()` names no driver option. Oldest page first, for both maps: the
+  key index AND the bucket, which holds rows and is therefore the worse of the two.
+  **Declining is the old behaviour**: no request in scope, an id no page indexed, a key that
+  resolved to nothing, a key the bound evicted — the caller reads the statement it always read. `MAX_IDS_PER_STATEMENT` bounds the preload exactly as it bounds a
   batch. What both share — the scope key, `keyOf`, the one `in` statement — lives in
   `batch-read.ts` so the two can never disagree about when a shared statement is legal.
   **One switch, where the driver is built**: `postgresDriver({ jitPreload: false })` /
@@ -282,7 +320,12 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   rendered from it.** The resolved records are the source; `ColumnDescription.references` spells
   `"<table>.<column>"` out of one for the migration generator, which is in tier 1 and cannot
   import this package. Never parse that string back — it carries physical names and a traversal
-  reads row *properties*, so the parse would be a second, lossy resolver. `references()` is a
+  reads row *properties*, so the parse would be a second, lossy resolver. **`onDelete` rides
+  beside it, on both `ColumnDescription` and `ReferenceDescription`, `As of 2026-08-19`**: the flat
+  string has no room for a rule and neither record had a field for one, so a declared
+  `{ onDelete: 'cascade' }` type-checked and reached no SQL for three majors — `@ultimat3/db` emits
+  it now, and it can only see what the projection carries. Read off the resolved reference, never
+  off `meta` a second time: a rule with no key is not a thing. `references()` is a
   method, not a field: a thunk may point at an entity two modules of an import cycle have not
   finished evaluating. `relationMap()` memoises the whole-registry derivation against
   `registryGeneration()`, which every registration bumps — a schema module imported late must
@@ -368,6 +411,16 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
     the three callers want three answers and the wrong one is invisible in the result. The soft
     delete inside `removal()` passes `false` too — both its callers read a count through
     `execute()`, so its rows were never readable by anyone.
+- **Every instant the write path stamps comes from `ctx.clock`, through `entityNow()`**
+  (`clock.ts`, `As of 2026-08`). `defaultNow()`, `touch()`'s `onUpdateNow()`, the soft-delete stamp
+  in BOTH drivers and a seed's `now` each read `systemClock` directly, so a frozen test clock drove
+  nothing the entity layer wrote — `createdAt`, `updatedAt` and `deletedAt` were the wall clock
+  however the ctx was built, and a test could only assert a range where it wanted a value. The read
+  path still reads no clock at all, which is what makes IT drivable (`@ultimat3/query`'s CLAUDE.md
+  says so in as many words); this is the write half of the same property. Outside a request there
+  is no ctx and the system clock IS the answer — a script, a worker boot and a seed take that
+  branch exactly as before. Never read `systemClock` on the write path again: five sites is how the
+  four stamps of one write ended up able to disagree.
 - **`touch()` in `query.ts` is the ONE place `onUpdateNow()` columns are stamped**, for
   `update(id, patch)` and `updateWhere(filter, patch)` alike — a second copy is how one of them
   ends up writing a stale `updatedAt`. It returns an empty patch untouched, so whether
@@ -664,13 +717,15 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 
 | File | Job |
 |---|---|
-| `types.ts` | `Column`, `RowOf`, `Insertable`, `IdOf` — the type derivation |
+| `types.ts` | `Column`, `RowOf`, `Insertable`, `IdOf` — the type derivation. `COLUMN_KINDS` is the runtime array `ColumnKind` DERIVES from (the shape core's `PRIMITIVE_KINDS` uses), so a package answering "one case per kind" reads a real list rather than spelling its own |
 | `column.ts` / `columns.ts` | the chain + property-key binding; the blessed builders; `columnName`/`moneyColumns`, the ONE physical-name resolver; `narrowMoney`, the one write-side narrowing both drivers run |
 | `columns-data.ts` | the wide vocabulary an existing schema needs: `json`, `decimal`, `date`, `bigint`, `bytes`, `arrayOf` |
 | `expr.ts` / `invariants.ts` | the `invariants: (c) => …` rule language; bind + `toSql()` DDL |
 | `entity.ts` / `describe.ts` | `entity()`, `$row`; the `EntityDescription` projection |
 | `view.ts` | `$view(keys)` — the row projection an action names as its `output` |
 | `query.ts` / `database.ts` | chainable read to a cursor page; `database()` + `Driver` |
+| `clock.ts` | `entityNow()` — the ONE clock read on the write path, `ctx.clock` else the system's |
+| `memory-match.ts` | what a `Predicate` means in the memory driver: compare/equal/LIKE, by the column's kind. The decimal comparison itself is `@ultimat3/core`'s `compareDecimalText` |
 | `repo.ts` / `tenancy.ts` | `Repo<T>` + `memoryDriver`'s repo, tx rollback; `QueryPlan` + `scopedPlan()` for a read and `assertRowTenant()` for a write — one actor-derived tenant guard, both halves |
 | `cross-tenant.ts` | `crossTenant(reason, fn)` — the capability-gated scope that lifts it |
 | `plan.ts` / `cursor.ts` | the plan both drivers execute; the one keyset cursor codec |

package/README.md

@@ -381,6 +381,13 @@ database({ orgs, posts }, { driver: postgresDriver() });   // production
 | For | tests, `x dev` before the first migration | production |
 | Transaction | `memoryTransactor()` — undo closures | `postgresTransactor()` — real `BEGIN`/`COMMIT` |
 | `reset()` | empties every repository it built | not implemented — the rows are the app's |
+| A predicate | `memory-match.ts`, by the column's declared KIND | the SQL `pg-sql.ts` compiles |
+
+Both answer the same predicate the same way, and the kind is what decides — never the JS type of
+the value: `bigint()`/`decimal()` hold decimal STRINGS and order by their digits (`2, 9, 10, 100`),
+a `uuid` compares case-insensitively because Postgres compares it as a value, `\` escapes a `%` or
+a `_` inside a `like`, and `in` takes a list or nothing (a scalar matches no rows; a list carrying
+a `null` also matches the NULL rows, which `col = null` never does).
 
 `database()` called with no driver takes the process default, and `defaultDriver()` is that same
 object — the one seam a test harness needs, `As of 2026-08`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "3.0.0",
+  "version": "4.1.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "3.0.0",
-    "@ultimat3/db": "3.0.0",
-    "@ultimat3/schema": "3.0.0",
-    "@ultimat3/time": "3.0.0"
+    "@ultimat3/core": "4.1.0",
+    "@ultimat3/db": "4.1.0",
+    "@ultimat3/schema": "4.1.0",
+    "@ultimat3/time": "4.1.0"
   }
 }

package/src/bulk-write.ts

@@ -5,10 +5,12 @@
 // reads the same answer rather than a second copy of the rule.
 
 import { keyOf } from './batch-read';
+import { columnFor } from './column';
 import { valueAt } from './cursor';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { EntityError, invariantViolated } from './errors';
 import { columnsOf } from './pg-row';
+import type { RowPatch } from './types';
 
 /**
  * Postgres binds at most 65535 parameters in one statement and a multi-row insert spends
@@ -36,7 +38,7 @@ const owns = (row: unknown, property: string): boolean =>
  */
 export const namedProperties = <Row>(
   entity: EntityCore<Row>,
-  rows: readonly Partial<Row>[],
+  rows: readonly RowPatch<Row>[],
 ): readonly string[] =>
   Object.keys(entity.$columns).filter((property) => rows.some((row) => owns(row, property)));
 
@@ -46,7 +48,7 @@ export const insertColumns = <Row>(
   properties: readonly string[],
 ): readonly string[] =>
   properties.flatMap((property) => {
-    const column = entity.$columns[property];
+    const column = columnFor(entity.$columns, property);
     return column === undefined ? [] : columnsOf(property, column);
   });
 
@@ -180,13 +182,13 @@ const sameColumns = (left: readonly string[], right: readonly string[]): boolean
  */
 export const upsertPlan = <Row>(
   entity: EntityCore<Row>,
-  rows: readonly Partial<Row>[],
+  rows: readonly RowPatch<Row>[],
   onConflict: readonly string[],
   onMatch: 'update' | 'nothing',
 ): UpsertPlan => {
   if (onConflict.length === 0) throw noConflictTarget(entity.$name);
   for (const property of onConflict) {
-    if (entity.$columns[property] === undefined) {
+    if (columnFor(entity.$columns, property) === undefined) {
       throw invariantViolated(
         entity.$name,
         'upsertAll',
@@ -252,10 +254,10 @@ const cellKey = (kind: string, value: unknown): string | undefined => {
 export const conflictKeyOf = <Row>(
   entity: EntityCore<Row>,
   on: readonly string[],
-  row: Partial<Row>,
+  row: RowPatch<Row>,
 ): string | undefined => {
   const cells = on.map((property) =>
-    cellKey(entity.$columns[property]?.$meta.kind ?? '', valueAt(row, property)),
+    cellKey(columnFor(entity.$columns, property)?.$meta.kind ?? '', valueAt(row, property)),
   );
   return cells.some((cell) => cell === undefined) ? undefined : JSON.stringify(cells);
 };
@@ -270,7 +272,7 @@ export const conflictKeyOf = <Row>(
 export const conflictKeys = <Row>(
   entity: EntityCore<Row>,
   plan: UpsertPlan,
-  rows: readonly Partial<Row>[],
+  rows: readonly RowPatch<Row>[],
 ): readonly (string | undefined)[] => {
   const keys = rows.map((row) => conflictKeyOf(entity, plan.on, row));
   if (plan.set.length === 0) return keys;

package/src/clock.ts

@@ -0,0 +1,18 @@
+// Single responsibility: the instant the entity layer WRITES. One reader of the clock, so
+// `defaultNow()`, `onUpdateNow()`, the soft-delete stamp and a seed's `now` are one value from one
+// source — and a second `systemClock.now()` anywhere on the write path is a timestamp no test can
+// drive and no two of these four can agree with.
+
+import { systemClock, tryUseContext } from '@ultimat3/core';
+
+/**
+ * `ctx.clock`, and the system clock outside every request.
+ *
+ * The READ path reads no clock at all, which is what makes it drivable (`@ultimat3/query`'s
+ * CLAUDE.md says so in as many words). The write path read `systemClock` directly at five sites, so
+ * a frozen test clock drove nothing the entity layer stamped: `createdAt`, `updatedAt` and
+ * `deletedAt` all came from the wall clock however the ctx was built, and a test asserting on one
+ * had to assert a range instead of a value. Outside a request there is no ctx and the system clock
+ * IS the answer — a script, a worker boot and a seed all take that branch, exactly as before.
+ */
+export const entityNow = (): Date => (tryUseContext()?.clock ?? systemClock).now();

package/src/column.ts

@@ -11,11 +11,26 @@ import type {
   AnyColumn,
   Column,
   ColumnDefault,
+  ColumnMap,
   ColumnMeta,
   MoneyColumnNames,
   TimestampColumn,
 } from './types';
 
+/**
+ * The column a NAME resolves to, or `undefined` — the ONE read of a column map by a name that came
+ * from outside it.
+ *
+ * `columns[property]` alone walks `Object.prototype`: an app's column map is a plain object
+ * literal, so `columns['constructor']` answers the `Object` FUNCTION, every `=== undefined` guard
+ * downstream passes, and the next `.$meta.kind` is a bare `TypeError` where the caller was owed
+ * `X_INVARIANT_VIOLATED` naming the columns that do exist. The name is caller data on every path
+ * that reaches here — a predicate column, a sort key, an `onConflict` target, a `select` list — so
+ * the discriminator lives in one place. Same read `tenancy.ts` already does for the tenant column.
+ */
+export const columnFor = (columns: ColumnMap, property: string): AnyColumn | undefined =>
+  Object.hasOwn(columns, property) ? columns[property] : undefined;
+
 export const snake = (value: string): string =>
   value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
 

package/src/count-by.ts

@@ -4,6 +4,7 @@
 // a `countBy` against Postgres means; a rule added to one driver alone is the drift this file
 // exists to prevent.
 
+import { columnFor } from './column';
 import type { EntityCore } from './entity';
 import { EntityError } from './errors';
 import type { AnyColumn, ColumnKind } from './types';
@@ -86,7 +87,7 @@ export const groupColumnOf = <Row>(
   property: string,
   operation: string,
 ): AnyColumn => {
-  const column = entity.$columns[property];
+  const column = columnFor(entity.$columns, property);
   if (column === undefined) {
     throw notGroupable(
       entity,

package/src/cursor.ts

@@ -7,6 +7,7 @@
 // to still exist, and a row deleted between two pages would silently restart pagination.
 
 import { CursorInvalidError, decodeCursor, encodeCursor } from '@ultimat3/core';
+import { columnFor } from './column';
 import type { EntityCore } from './entity';
 import { invariantViolated } from './errors';
 import type { QueryPlan } from './tenancy';
@@ -28,7 +29,7 @@ const partsOf = (path: string): { readonly property: string; readonly part?: str
 };
 
 const columnAt = <Row>(entity: EntityCore<Row>, path: string): AnyColumn => {
-  const column = entity.$columns[partsOf(path).property];
+  const column = columnFor(entity.$columns, partsOf(path).property);
   if (column === undefined) {
     throw invariantViolated(entity.$name, 'orderBy', `no column "${path}"`);
   }
@@ -51,13 +52,33 @@ const kindAt = <Row>(entity: EntityCore<Row>, path: string): ColumnKind => {
       `${path} is money: order by ${path}.minor or ${path}.currency`,
     );
   }
-  const money = kind === 'money' ? MONEY_PARTS[part] : undefined;
+  // `MONEY_PARTS[part]` alone answers a FUNCTION for `orderBy('price.toString')` — not
+  // `undefined` — so the refusal below never fired and `assertSeekable` minted a cursor for it.
+  const money =
+    kind === 'money' && Object.hasOwn(MONEY_PARTS, part) ? MONEY_PARTS[part] : undefined;
   if (money === undefined) {
     throw invariantViolated(entity.$name, 'orderBy', `${path} names no column part`);
   }
   return money;
 };
 
+/**
+ * The kind a PATH holds, or `undefined` when it names none — the non-throwing half of `kindAt`.
+ *
+ * The in-memory driver asks this about a predicate column and a sort key, both of which are caller
+ * data: an unknown name compares as text there exactly as it always did, rather than turning a
+ * filter into a refusal the Postgres driver does not make. It is what lets a comparison be decided
+ * by the column's DECLARED kind — which is what Postgres decides by — instead of by the JS type of
+ * whichever value is in hand.
+ */
+export const kindOf = <Row>(entity: EntityCore<Row>, path: string): ColumnKind | undefined => {
+  const { property, part } = partsOf(path);
+  const kind = columnFor(entity.$columns, property)?.$meta.kind;
+  if (kind === undefined) return undefined;
+  if (part === undefined) return kind === 'money' ? undefined : kind;
+  return kind === 'money' && Object.hasOwn(MONEY_PARTS, part) ? MONEY_PARTS[part] : undefined;
+};
+
 export const valueAt = (row: unknown, path: string): unknown => {
   const { property, part } = partsOf(path);
   const record = typeof row === 'object' && row !== null ? (row as Record<string, unknown>) : {};

package/src/describe.ts

@@ -48,6 +48,7 @@ export const describeReferences = (
         targetEntity: target.table,
         targetProperty: target.property,
         targetColumn: target.name,
+        onDelete: meta.onDelete ?? null,
       },
     ];
   });
@@ -90,6 +91,7 @@ const describeColumn = <Row>(
       unique: false,
       hasDefault: false,
       references: null,
+      onDelete: null,
     };
     return [
       {
@@ -142,6 +144,9 @@ const describeColumn = <Row>(
       // traversal reads can never disagree about what a `references()` points at.
       references:
         reference === undefined ? null : `${reference.targetEntity}.${reference.targetColumn}`,
+      // Off the resolved reference, never off `meta` again: a rule with no key is not a thing, and
+      // reading the option twice is two places for the pair to disagree.
+      onDelete: reference?.onDelete ?? null,
     },
   ];
 };

package/src/entity.ts

@@ -3,8 +3,8 @@
 // (the typed db handle, migrations, cache tags, the admin UI, the manifest) is projected from
 // this one call.
 
-import { systemClock } from '@ultimat3/core';
 import { describeValue, type StandardSchemaV1 } from '@ultimat3/schema';
+import { entityNow } from './clock';
 import { assertColumnName, bindColumn, columnName, moneyColumns } from './column';
 import { newId } from './columns';
 import { describeEntity, describeReferences } from './describe';
@@ -115,7 +115,7 @@ const defaultValue = (meta: ColumnMeta): unknown => {
   const declared = meta.default;
   if (declared === undefined) return undefined;
   if (declared.kind === 'value') return declared.value;
-  return declared.by === 'uuid-v7' ? newId() : systemClock.now();
+  return declared.by === 'uuid-v7' ? newId() : entityNow();
 };
 
 export const entity = <const C extends ColumnMap>(

package/src/index.ts

@@ -101,6 +101,7 @@ export {
 export type { EntityRelations, Relation, RelationKind, RelationMap } from './relations';
 export { relationMap, relationNamed, relationsFor, relationsOf } from './relations';
 export type {
+  FindByIdOptions,
   FindManyArgs,
   MemoryRepo,
   Page,
@@ -152,9 +153,11 @@ export type {
   OnDelete,
   ReferenceOptions,
   RowOf,
+  RowPatch,
   TimestampColumn,
   TypeOf,
   UuidColumn,
 } from './types';
+export { COLUMN_KINDS } from './types';
 // `viewFor` stays internal: a view is reached through the entity, as `posts.$view([...])`.
 export type { EntityView } from './view';

package/src/jit-preload.ts

@@ -5,7 +5,9 @@
 //
 // The trigger carries an id, not a row, so what a page leaves behind is an index of its foreign
 // key VALUES rather than a map keyed by row identity: an id is a thing that can be looked up in
-// it, and it holds values, so it pins no rows for the request's lifetime.
+// it, and a page therefore costs its keys rather than its rows. That was true PER PAGE and false
+// across them until `MAX_SIBLING_KEYS` — the store outlives every page and dies with the ctx,
+// which for a job is the whole attempt, so both maps here are bounded and evict the oldest page.
 //
 // The scope guard is a security boundary, not a tuning knob. A preloaded row is served only to a
 // lookup with the same scope key, the same client and no write since — anything else reads the
@@ -14,7 +16,15 @@
 import type { Ctx } from '@ultimat3/core';
 import { tryUseContext } from '@ultimat3/core';
 import type { DbClient } from '@ultimat3/db';
-import { type Answer, keyOf, type PointRead, readByIds, statementChunks } from './batch-read';
+import {
+  type Answer,
+  keyOf,
+  MAX_IDS_PER_STATEMENT,
+  type PointRead,
+  readByIds,
+  statementChunks,
+} from './batch-read';
+import { columnFor } from './column';
 import type { EntityCore } from './entity';
 
 /** The rows one page's worth of foreign keys resolved to, under one scope. */
@@ -53,10 +63,54 @@ const storeFor = (ctx: Ctx): Store => {
   return created;
 };
 
+/**
+ * How many id keys ONE edge may hold, and how many rows one bucket may keep — a few pages' worth,
+ * the way `MAX_IDS_PER_STATEMENT` bounds a statement.
+ *
+ * `MAX_IDS_PER_STATEMENT` bounded the statement and nothing bounded the STORE: every page merged
+ * its keys in and the store died only with the ctx, which for a job is the whole attempt. Measured
+ * at 1,000 pages x 1,000 rows with distinct foreign keys, rows dropped after each call and
+ * `Bun.gc(true)` either side: **159.3 MB retained**, against 2.7 MB with the tagging off — so a
+ * 12M-row `backfill()` retains ~2 GB and OOMs the worker on the DEFAULT configuration, since
+ * `jitPreload` defaults to true and `backfill()` names no driver option.
+ *
+ * Four statements' worth. The keys of one page are filed contiguously, so the survivors are the
+ * newest pages' and the arrays every evicted key referenced go with them — which is what makes the
+ * bound a bound on bytes and not only on entries. Past it a lookup DECLINES, and declining is the
+ * old behaviour everywhere else in this file: the caller reads the statement it always read.
+ */
+export const MAX_SIBLING_KEYS = MAX_IDS_PER_STATEMENT * 4;
+
+/**
+ * Newest wins, oldest goes. A `Map` iterates in insertion order, so its first key is the oldest
+ * page's — and the page a sequential `for … of` loop is walking is the newest one, which is the
+ * only page this store exists to answer for. Re-filed rather than overwritten, so a key a later
+ * page carries again moves to the newest end instead of ageing out under it.
+ */
+const remember = <V>(index: Map<string, V>, key: string, value: V, cap: number): void => {
+  index.delete(key);
+  index.set(key, value);
+  while (index.size > cap) {
+    const oldest = index.keys().next();
+    if (oldest.done === true) return;
+    index.delete(oldest.value);
+  }
+};
+
 /** Both ends of the edge: a key pointing at another column of the same entity is another edge. */
 const siblingKey = (targetEntity: string, targetProperty: string): string =>
   JSON.stringify([targetEntity, targetProperty]);
 
+/** TEST SEAM: id keys this request is holding, across every edge. A bound nothing can observe is a
+ * bound nothing can pin, and `MAX_SIBLING_KEYS` is the number this answers against. */
+export const siblingKeysHeld = (ctx: Ctx): number => {
+  const store = requests.get(ctx);
+  if (store === undefined) return 0;
+  let held = 0;
+  for (const index of store.siblings.values()) held += index.size;
+  return held;
+};
+
 const writesTo = (store: Store, entity: string): number => store.writes.get(entity) ?? 0;
 
 /**
@@ -80,7 +134,7 @@ export const tagSiblings = <Row>(entity: EntityCore<Row>, rows: readonly Row[]):
   for (const reference of references) {
     // The declaring column's own kind: a foreign key mirrors the key it points at, and a value is
     // filed here exactly as `findById` will spell it when it comes looking.
-    const kind = entity.$columns[reference.property]?.$meta.kind;
+    const kind = columnFor(entity.$columns, reference.property)?.$meta.kind;
     if (kind === undefined) continue;
     const ids: unknown[] = [];
     const keys = new Set<string>();
@@ -96,7 +150,7 @@ export const tagSiblings = <Row>(entity: EntityCore<Row>, rows: readonly Row[]):
     if (ids.length === 0) continue;
     const at = siblingKey(reference.targetEntity, reference.targetProperty);
     const index = store.siblings.get(at) ?? new Map<string, readonly unknown[]>();
-    for (const key of keys) index.set(key, ids);
+    for (const key of keys) remember(index, key, ids, MAX_SIBLING_KEYS);
     store.siblings.set(at, index);
   }
 };
@@ -165,12 +219,14 @@ const preload = <Row>(read: PointRead<Row>, bucket: Bucket, ids: readonly unknow
     if (bucket.rows.has(at)) continue;
     // The executor runs synchronously, so `settle` is assigned before the promise is stored.
     let settle!: (answer: Answer) => void;
-    bucket.rows.set(
-      at,
-      new Promise<Answer>((resolve) => {
-        settle = resolve;
-      }),
-    );
+    const answer = new Promise<Answer>((resolve) => {
+      settle = resolve;
+    });
+    // Bounded for the reason the sibling index is: a bucket holds ROWS, so a long request that
+    // preloads page after page retains every row it ever resolved. An evicted entry still settles
+    // — `fill` holds its own settler — and a lookup that no longer finds one reads its own
+    // statement, which is what it would have read had no page indexed the id at all.
+    remember(bucket.rows, at, answer, MAX_SIBLING_KEYS);
     settlers.set(at, settle);
     wanted.push(id);
   }