@ultimat3/entity 29.4.0 → 30.0.0

package/src/entity.ts

@@ -4,33 +4,43 @@
 // this one call.
 
 import type { IndexMethod } from '@ultimat3/db';
-import { describeValue, type Schema } from '@ultimat3/schema';
+import type { Schema } from '@ultimat3/schema';
 import { assertAppendOnlyColumns } from './append-only';
-import { entityNow } from './clock';
 import { assertTableName, bindColumn, columnName, moneyColumns } from './column';
-import { newId } from './columns';
-import { describeEntity, describeReferences } from './describe';
+import {
+  assertNotRetired,
+  assertScan,
+  assertShared,
+  describeEntity,
+  describeReferences,
+} from './describe';
+import { rowParsers } from './entity-parse';
+import { parseEntityPatch } from './entity-patch';
 import { invariantViolated } from './errors';
 import type { InvariantColumns, Resolve } from './expr';
 import { invariantColumns } from './expr';
+import type { HistoryEntity, HistoryInit } from './history';
 import { distinctIndexes } from './index-identity';
 import type { IndexInit } from './index-init';
 import { indexName } from './index-name';
 import type { Invariant, InvariantDef } from './invariants';
 import { assertInvariants, bindInvariant } from './invariants';
+import { describeLifecycle, lifecycleHistory } from './lifecycle';
 import { recordProjection } from './record-projection';
 import type { EntityDescription, ReferenceDescription } from './registry';
 import { registerEntity } from './registry';
+import { type Retain, type RetainInit, retainOf } from './retain';
 import { rowSchema } from './row-schema';
 import { sealedFields } from './sealed';
 import { assertSealedDeclaration } from './sealed-declaration';
-import { sealedInView, sealedMissing } from './sealed-errors';
+import { sealedInView } from './sealed-errors';
 import type { SearchInit, SearchSource, SearchVector } from './search';
 import { searchVectorOf } from './search';
 import { resolveTenantColumn } from './tenancy';
-import type { AnyColumn, ColumnMap, ColumnMeta, IndexDef, RowOf, WireRow } from './types';
+import type { AnyColumn, ColumnMap, IndexDef, RowOf, WireRow } from './types';
 import type { EntityView } from './view';
 import { viewFor } from './view';
+import { type ViewInit, type ViewQuery, viewQueryOf } from './view-entity';
 
 /** Presence of this column is what makes an entity soft-deletable — not a flag. */
 export const SOFT_DELETE_COLUMN = 'deletedAt';
@@ -51,6 +61,17 @@ export interface EntityInit<C extends ColumnMap> {
    * `orgId`, so silence never means unscoped.
    */
   readonly tenant?: keyof C & string;
+  /**
+   * Why an entity with no tenant column, referencing a tenant-owned one, belongs to no tenant.
+   * Without it `x verify`'s exercise step reports `X_ENTITY_TENANT_UNDECLARED`; blank is refused.
+   */
+  readonly shared?: string;
+  /**
+   * Why this table may be read by a sequential scan: a closed catalog that stays a handful of rows.
+   * Without it `x verify`'s exercise step reports a statement no index serves (`X_QUERY_UNINDEXED`)
+   * and a reference column no index leads with; blank is refused.
+   */
+  readonly scan?: string;
   /** Composite keys only — a single key is `uuid().primaryKey()` on the column itself. */
   readonly primaryKey?: readonly (keyof C & string)[];
   /**
@@ -80,6 +101,26 @@ export interface EntityInit<C extends ColumnMap> {
    * refuses the same in raw SQL. A soft-delete, `onUpdateNow()` or state-machine column is refused.
    */
   readonly appendOnly?: boolean;
+  /**
+   * Physical columns the previous release still reads and this one does not: a rolling deploy's
+   * first half of a column drop. Delete the column from `columns` and name it here, so it leaves
+   * the row type, the projection and every insert while `x db gen` writes a marker and keeps it.
+   * Remove it from this list in the next release, and `x db gen --allow-destructive` drops it. A
+   * name, not a chain on the column: a column here has no builder left to chain from.
+   */
+  readonly retired?: readonly string[];
+  /**
+   * A relation Postgres derives rather than a table: `x db gen` emits `create [materialized] view`
+   * from `sql`, reads are the chain's (tenancy, codec, `$view`), and every write is
+   * `X_ENTITY_VIEW_READ_ONLY`. `columns` name its output columns; `primaryKey` is the read identity.
+   */
+  readonly view?: ViewInit;
+  /** Rows older than `after` by `on` are swept by `purge({ entities: 'declared' })` (`retain.ts`). */
+  readonly retain?: RetainInit<keyof C & string>;
+  /** Every row change recorded into `<table>_history` by trigger (`history.ts`, `$history`). */
+  readonly history?: HistoryInit;
+  /** Set by `history.ts` on the history entity it declares: the parent's name. Never by hand. */
+  readonly historyOf?: string;
 }
 
 /**
@@ -100,6 +141,14 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
   readonly $softDelete: boolean;
   /** `entity({ appendOnly: true })`: update and delete are refused, here and by the table. */
   readonly $appendOnly: boolean;
+  /** `entity({ retain })`, checked; `null` when rows are kept. */
+  readonly $retain: Retain | null;
+  /** `entity({ history: true })`: the history entity, registered beside this one; else `null`. */
+  readonly $history: HistoryEntity | null;
+  /** On a history entity, its parent's name; `null` everywhere else. */
+  readonly $historyOf: string | null;
+  /** `entity({ view })`: the query a view is derived by, `null` on a table. Writes are refused. */
+  readonly $viewQuery: ViewQuery | null;
   /** Property key of the tenant column, or `null`. Presence is what turns tenancy on. */
   readonly $tenantColumn: string | null;
   /**
@@ -125,6 +174,8 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
   $tagFor(id: string): string;
   /** Fills declared defaults, then validates every column. Throws on a bad value. */
   $parse(value: unknown): Row;
+  /** `$parse` for the columns a patch names: no default fills an absent one. `entity-patch.ts`. */
+  $parsePatch<Patch>(patch: Patch): Patch;
   /**
    * `const PostView = posts.$view(['id', 'title'])` — the projection an action names as its
    * `output`. An unknown key is a compile error, and a declaration error for a JS caller.
@@ -156,28 +207,27 @@ export type Entity<Row, C extends ColumnMap = ColumnMap> = Omit<EntityCore<Row,
 
 const MONEY_PARTS = new Set(['minor', 'currency']);
 
-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() : entityNow();
-};
-
 export const entity = <const C extends ColumnMap>(
   name: string,
   init: EntityInit<C>,
 ): Entity<RowOf<C>, C> => {
   type Row = RowOf<C>;
   const entries: readonly (readonly [string, AnyColumn])[] = Object.entries(init.columns);
-  for (const [property, column] of entries) bindColumn(column, name, property);
+  // Resolved before the bindings, because a binding carries the tenant's PHYSICAL column: a
+  // `references()` on another entity reads it through this column's binding at describe time.
+  const tenantColumn = resolveTenantColumn(name, init.columns, init.tenant);
+  const tenantMeta = tenantColumn === null ? undefined : init.columns[tenantColumn]?.$meta;
+  const tenant = tenantMeta === undefined ? null : columnName(tenantColumn ?? '', tenantMeta);
 
   // Both branches. The declared table was checked and the fallback — which is every entity that
   // does not rename its table — was not, so an entity NAME closed the identifier in the same way a
   // column name could: `entity('t" (x int); drop table u; --')` emitted that `drop table` verbatim.
   const table = assertTableName(name, init.table ?? name);
+  assertShared(name, table, init.shared, tenantColumn);
+  assertScan(name, init.scan);
+  for (const [property, column] of entries) bindColumn(column, name, property, tenant, table);
   const cacheTag = `entity:${name}`;
   const softDelete = Object.hasOwn(init.columns, SOFT_DELETE_COLUMN);
-  const tenantColumn = resolveTenantColumn(name, init.columns, init.tenant);
   const appendOnly = init.appendOnly === true;
   if (appendOnly) assertAppendOnlyColumns(name, entries, SOFT_DELETE_COLUMN);
 
@@ -325,6 +375,7 @@ export const entity = <const C extends ColumnMap>(
   // A foreign key's own index named again in `indexes` is one index, not two (`index-identity.ts`).
   const indexes = distinctIndexes(declared);
 
+  const retain = retainOf(name, init.retain, entries, indexes, appendOnly);
   const sealed = sealedFields({ $name: name, $table: table, $columns: init.columns });
   assertSealedDeclaration({
     name,
@@ -335,6 +386,11 @@ export const entity = <const C extends ColumnMap>(
     invariants,
   });
   const sealedKeys = new Set(sealed.map((field) => field.property));
+  const viewQuery = viewQueryOf(name, init.view, {
+    appendOnly,
+    indexes,
+    sealed: [...sealedKeys],
+  });
   /** The columns that leave the server: every one that is not sealed. */
   const wireEntries = entries.filter(([property]) => !sealedKeys.has(property));
 
@@ -353,69 +409,16 @@ export const entity = <const C extends ColumnMap>(
       tenantColumn,
       search,
       appendOnly,
+      retired: init.retired,
+      shared: init.shared,
+      scan: init.scan,
+      view: viewQuery,
+      lifecycle: describeLifecycle(core as EntityCore, retain, init.historyOf),
     });
+  assertNotRetired(name, entries, init.retired);
   const references = (): readonly ReferenceDescription[] => describeReferences(name, entries);
 
-  const parse = (value: unknown): Row => {
-    if (typeof value !== 'object' || value === null) {
-      // `describeValue`, never `String(value)`: this message is a `$parse` failure, which reaches
-      // the caller and the log line — and the whole row is the last value in the framework that
-      // may be echoed there. Same renderer as the column builders (`columns.ts`) use.
-      throw invariantViolated(name, 'row', `expected an object, got ${describeValue(value)}`);
-    }
-    const input = value as Readonly<Record<string, unknown>>;
-    const row: Record<string, unknown> = {};
-    for (const [property, column] of entries) {
-      // `=== undefined`, never `??`: an explicit `null` is the caller CLEARING a nullable column,
-      // and `??` read it as absence and wrote the column's declared default straight back — so
-      // `update(id, { status: null })` reported success and stored `'draft'`, with nothing on any
-      // surface to say otherwise. A present `undefined` still means absence, which is what a
-      // spread of an omitted optional key produces and is the shape every existing caller has.
-      const raw = input[property];
-      const given = raw === undefined ? defaultValue(column.$meta) : raw;
-      if (given === undefined || given === null) {
-        if (column.$meta.notNull) {
-          // A required sealed column ABSENT from a row is nearly always a spread of a repository
-          // row, which does not enumerate it — so the refusal names that, and the rewrite.
-          throw given === undefined && sealedKeys.has(property)
-            ? sealedMissing(name, property)
-            : invariantViolated(name, property, 'is required and has no default');
-        }
-        row[property] = null;
-        continue;
-      }
-      row[property] = column.$parse(given);
-    }
-    // Every property was validated by its own column above, so the shape is the derived row.
-    return row as Row;
-  };
-
-  /**
-   * The row as `$schema` validates it: the sealed columns are neither required nor returned, so a
-   * handler's row — which holds their plaintext — parses to a value that does not.
-   */
-  const parseWire = (value: unknown): WireRow<Row, C> => {
-    if (sealedKeys.size === 0) return parse(value) as WireRow<Row, C>;
-    if (typeof value !== 'object' || value === null) {
-      throw invariantViolated(name, 'row', `expected an object, got ${describeValue(value)}`);
-    }
-    const input = value as Readonly<Record<string, unknown>>;
-    const row: Record<string, unknown> = {};
-    for (const [property, column] of wireEntries) {
-      const raw = input[property];
-      const given = raw === undefined ? defaultValue(column.$meta) : raw;
-      if (given === undefined || given === null) {
-        if (column.$meta.notNull) {
-          throw invariantViolated(name, property, 'is required and has no default');
-        }
-        row[property] = null;
-        continue;
-      }
-      row[property] = column.$parse(given);
-    }
-    // Every wire property was validated by its own column, and no sealed one was copied.
-    return row as WireRow<Row, C>;
-  };
+  const { parse, parseWire } = rowParsers<Row, WireRow<Row, C>>(name, entries, sealedKeys);
 
   const schema = rowSchema<WireRow<Row, C>>(
     { name, table, primaryKey, persist: init.persist === true, sealed: [...sealedKeys] },
@@ -433,7 +436,8 @@ export const entity = <const C extends ColumnMap>(
     $tags: tags,
     $cacheTag: cacheTag,
     $softDelete: softDelete,
-    $appendOnly: appendOnly,
+    $appendOnly: appendOnly || init.historyOf !== undefined,
+    $viewQuery: viewQuery,
     $tenantColumn: tenantColumn,
     $search: search,
     $schema: schema,
@@ -443,6 +447,7 @@ export const entity = <const C extends ColumnMap>(
     },
     $tagFor: (id) => `${cacheTag}:${id}`,
     $parse: parse,
+    $parsePatch: (patch) => parseEntityPatch(name, init.columns, patch),
     $view: <K extends keyof Row & string>(keys: readonly K[]) => {
       // Before the view exists: a view is an `output`, and a sealed column is in none.
       const named = keys.find((key) => sealedKeys.has(key));
@@ -452,6 +457,11 @@ export const entity = <const C extends ColumnMap>(
     $assert: (row) => assertInvariants(name, invariants, row),
     $describe: describe,
     $references: references,
+    $retain: retain,
+    // Assigned below, once this entity is registered: the history entity is declared after it.
+    $history: null,
+    // A history table is append-only to every repository: its rows are its trigger's to write.
+    $historyOf: init.historyOf ?? null,
   };
 
   registerEntity({
@@ -463,6 +473,10 @@ export const entity = <const C extends ColumnMap>(
     describe,
     references,
   });
+  const { history, historyOf } = init;
+  const lifecycle = { name, table, columns: init.columns, primaryKey, tenantColumn, appendOnly };
+  const historyEntity = lifecycleHistory({ ...lifecycle, history, historyOf });
+  if (historyEntity !== null) Object.assign(core, { $history: historyEntity });
   // The columns land on the entity itself so `orgs.id` is a column reference; every framework
   // member is `$`-prefixed, which is why a column may be called `name`.
   // `$schema` is restated so the result carries its real output type; it is the same object.

package/src/errors.ts

@@ -183,6 +183,14 @@ export const repoClientPinned = (entityName: string): EntityError =>
     fix: `setDbClient(client) at boot and build the repository with no client: — postgresDriver() then resolves the open transaction through db() — or run this call outside withTransaction()`,
   });
 
+/** `testDriver()`: the transaction began on one store and `setDbClient` now names the other. */
+export const testDriverClientChanged = (entityName: string, began: string): EntityError =>
+  new EntityError({
+    code: 'X_TEST_DRIVER_CLIENT_CHANGED',
+    cause: `${entityName} was called inside a transaction that began on ${began}, and setDbClient has since ${began === 'memory' ? 'installed a client' : 'cleared the client'} — following it would split one transaction's writes across two stores`,
+    fix: 'beforeAll(() => setDbClient(client)); afterAll(() => setDbClient(undefined));   # outside every transactor().run / withTransaction scope',
+  });
+
 export const notFound = (entityName: string, id: string): EntityError =>
   new EntityError({
     code: 'X_NOT_FOUND',

package/src/history-actor.ts

@@ -0,0 +1,22 @@
+// Single responsibility: who a history row names. The history trigger reads `x.actor` and
+// `x.request` from the WRITE'S transaction; this sets them, once per transaction, before the first
+// repository write to an entity that keeps history. No transaction, nothing set: the trigger then
+// records `null`, never a guess.
+
+import { tryUseContext } from '@ultimat3/core';
+import { ACTOR_SETTING, currentTx, type DbTx, REQUEST_SETTING, setLocal } from '@ultimat3/db';
+
+const stamped = new WeakSet<DbTx>();
+
+/** Before a write to `entity` on the ambient connection. A pinned repository is never stamped. */
+export async function stampHistoryActor(
+  entity: { readonly $history: unknown },
+  pinned: boolean,
+): Promise<void> {
+  if (entity.$history === null || pinned) return;
+  const tx = currentTx();
+  const ctx = tryUseContext();
+  if (tx === undefined || ctx === undefined || stamped.has(tx)) return;
+  await setLocal(tx, { [ACTOR_SETTING]: ctx.actor.id, [REQUEST_SETTING]: ctx.requestId });
+  stamped.add(tx);
+}

package/src/history.ts

@@ -0,0 +1,86 @@
+// Single responsibility: `entity({ history: true })`'s history table as a REAL entity, registered
+// beside its parent — so `$tenantColumn` holds, row security emits its policy, the tenant proof and
+// subject data walk it, and a read of it is an ordinary tenant-scoped, cursor-paged read.
+
+import { t } from '@ultimat3/schema';
+import { columnName, makeColumn } from './column';
+import { text, timestamp, uuid } from './columns';
+import { json } from './columns-data';
+import type { Entity } from './entity';
+import { entity } from './entity';
+import { invariantViolated } from './errors';
+import type { AnyColumn, ColumnMap, RowOf } from './types';
+
+/** `history: true`, or with a retention window of its own. No default window, here or anywhere. */
+export type HistoryInit = true | { readonly retain?: { readonly after: string } };
+
+/** The parent facts the history table is built from. */
+export interface HistoryParent {
+  readonly name: string;
+  readonly table: string;
+  readonly columns: ColumnMap;
+  readonly primaryKey: readonly string[];
+  readonly tenantColumn: string | null;
+}
+
+/** A row image: the stored row as `to_jsonb` spells it, physical names. Any JSON object. */
+const image = () => json(t.record(t.json())).nullable();
+
+/** Every history table's own columns; the parent's tenant column joins them at runtime. */
+const historyColumns = () => ({
+  id: uuid().primaryKey(),
+  rowId: text(),
+  op: text(),
+  at: timestamp().defaultNow(),
+  actorId: text().nullable(),
+  requestId: text().nullable(),
+  before: image(),
+  after: image(),
+});
+
+export type HistoryColumns = ReturnType<typeof historyColumns>;
+/**
+ * A history entity as a read types it. The tenant column is on the row at runtime and absent from
+ * the type: every read of it is scoped by the repository, never filtered by hand.
+ */
+export type HistoryEntity = Entity<RowOf<HistoryColumns>, HistoryColumns>;
+
+/**
+ * The tenant column, copied without its foreign key: a history row outlives an org's cascade only
+ * until its purge, and a key would cascade a delete the guard refuses.
+ */
+const tenantCopy = (column: AnyColumn): AnyColumn => {
+  const { references: _r, onDelete: _o, crossTenant: _c, countedIn: _n, ...meta } = column.$meta;
+  return makeColumn({ ...meta, tenant: true, index: true }, column.$parse, false);
+};
+
+/** The history entity of `parent`, declared now. Its name and table are the parent's `_history`. */
+export function historyEntity(parent: HistoryParent, init: HistoryInit): HistoryEntity {
+  if (parent.primaryKey.length !== 1) {
+    throw invariantViolated(
+      parent.name,
+      'history',
+      'history records a row by its single primary key, and this entity declares a composite one',
+    );
+  }
+  const tenant = parent.tenantColumn;
+  const tenantColumn = tenant === null ? undefined : parent.columns[tenant];
+  const columns = {
+    ...historyColumns(),
+    ...(tenant === null || tenantColumn === undefined
+      ? {}
+      : { [tenant]: tenantCopy(tenantColumn).column(columnName(tenant, tenantColumn.$meta)) }),
+  };
+  const after = init === true ? undefined : init.retain?.after;
+  // Typed as its fixed columns: the tenant key is a runtime name, so it cannot be in the type.
+  return entity<ColumnMap>(`${parent.name}_history`, {
+    table: `${parent.table}_history`,
+    columns,
+    historyOf: parent.name,
+    indexes: [
+      { on: [...(tenant === null ? [] : [tenant]), 'rowId', 'at'] },
+      ...(after === undefined ? [] : [{ on: ['at'] }]),
+    ],
+    ...(after === undefined ? {} : { retain: { after, on: 'at' } }),
+  }) as unknown as HistoryEntity;
+}

package/src/index.ts

@@ -28,12 +28,16 @@ export {
 } from './columns';
 export type { DecimalOptions } from './columns-data';
 export { arrayOf, bigint, bytes, date, decimal, json } from './columns-data';
+export type { Counter } from './counter';
+export { countersOf, describeCounter } from './counter';
 // `crossTenantReason` stays internal: an app that could read the flag would have a second way to
 // reason about tenant scope — branch on it — next to the one way, which is entering the scope.
-export { CROSS_TENANT_SCOPE, crossTenant } from './cross-tenant';
+export { CROSS_TENANT_SCOPE, crossTenant, setCrossTenantObserver } from './cross-tenant';
 export type { Database, DatabaseOptions, Driver, EntitySet } from './database';
 export { database, defaultDriver, memoryDriver } from './database';
 export type { DescribeInput } from './describe';
+export type { TenantColumnDescription } from './describe-tenancy';
+export { describeTenancy } from './describe-tenancy';
 export type { Entity, EntityCore, EntityInit } from './entity';
 export { entity, SOFT_DELETE_COLUMN } from './entity';
 // The vocabulary an EXISTING schema needs. Separate from the blessed builders on purpose: those
@@ -77,9 +81,11 @@ export {
   stateTransitionIllegal,
   stateUndeclared,
 } from './feature-errors';
+export type { HistoryColumns, HistoryEntity, HistoryInit } from './history';
 export type { IndexInit } from './index-init';
 export type { Invariant, InvariantDef, InvariantKind } from './invariants';
 export { assertInvariants, invariant, MAX_ASSERTED_ROWS } from './invariants';
+export { memoryJournal } from './memory-journal';
 // How Postgres compares two values of one column, decided by the column's declared KIND. Exported
 // because `@ultimat3/query`'s matcher and in-memory source ask the same question — and a second
 // answer there is how a live window and the database returned one read in two orders.
@@ -105,6 +111,12 @@ export type { PreloadOptions } from './preload-ceiling';
 export { MAX_PRELOADED_ROWS } from './preload-ceiling';
 export type { Preloaded, ReadBuilder, Table } from './query';
 export { tableFor } from './query';
+export type {
+  ReadAggregates,
+  SeriesOptions,
+  SeriesValueOf,
+  TimestampKeys,
+} from './read-aggregates';
 // The client projection of an entity (plan 101): record type, record key, and the brand on
 // `$schema` that lets an action or query derive its record envelope from its output schema.
 // Value-light — no Postgres driver behind any of them — so a browser store may import them here.
@@ -118,6 +130,7 @@ export type {
   InvariantDescription,
   ReferenceDescription,
   RegistryEntry,
+  SameTenantKey,
 } from './registry';
 export {
   clearRegistry,
@@ -140,8 +153,10 @@ export type {
   Tx,
   UpsertArgs,
 } from './repo';
+export type { Retain, RetainInit } from './retain';
 export type { RowBulkChange, RowChange, RowChangeOp, RowObserver } from './row-observer';
 export { observedRepo, rowObserver, setRowObserver } from './row-observer';
+export { rowSecuritySettings } from './row-security-settings';
 export type { RecordsByKey, RecordsByType } from './rows-of';
 export { hasEntityRows, projectionsIn, rowsOf } from './rows-of';
 // Sealed columns. `sealedFields` is what a manifest or `x doctor` reads to say which columns are
@@ -191,6 +206,10 @@ export {
   orgScoped,
   scopedPlan,
 } from './tenancy';
+// The scaffolded handle's driver under test: memory until `setDbClient` installs a client.
+export { testDriver } from './test-driver';
+export type { SeriesPoint, SeriesSpec, SeriesUnit, SeriesValue } from './time-bucket';
+export { bucketStart, SERIES_UNITS } from './time-bucket';
 export type { Move } from './transition';
 export type { TransitionObservation } from './transition-pins';
 export type {

package/src/jit-preload.ts

@@ -10,8 +10,9 @@
 // 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
-// statement it always read.
+// lookup with the same scope key, the same client and no write since — to ANY entity, because the
+// database rewrites rows the statement never named — anything else reads the statement it always
+// read.
 
 import type { Ctx } from '@ultimat3/core';
 import { tryUseContext } from '@ultimat3/core';
@@ -29,11 +30,9 @@ import type { EntityCore } from './entity';
 
 /** The rows one page's worth of foreign keys resolved to, under one scope. */
 interface Bucket {
-  /** The entity the rows belong to — what a write invalidates. */
-  readonly entity: string;
   /** Where the rows were read from. A pinned client and the ambient pool are two places. */
   readonly client: DbClient;
-  /** Writes to `entity` when the bucket was opened. A later write makes every row of it stale. */
+  /** The store's writes when the bucket was opened. A later write makes every row of it stale. */
   readonly generation: number;
   /** Never rejects: a failure is an `Answer`, so an id nobody asks for cannot go unhandled. */
   readonly rows: Map<string, Promise<Answer>>;
@@ -44,8 +43,13 @@ interface Store {
   readonly siblings: Map<string, Map<string, readonly unknown[]>>;
   /** Scope key -> the rows preloaded under it. */
   readonly preloaded: Map<string, Bucket>;
-  /** Entity name -> writes this request has issued against it. */
-  readonly writes: Map<string, number>;
+  /**
+   * Writes this request has issued, to any entity. ONE counter, not one per entity: a
+   * `countedIn` trigger rewrites the parent of the row inserted, an `onDelete` cascade or
+   * `set null` the children of the row deleted, and an app's own trigger anything at all — a
+   * write's statement names its entity, never every row it moves.
+   */
+  writes: number;
 }
 
 /**
@@ -58,7 +62,7 @@ const storeFor = (ctx: Ctx): Store => {
   const key: object = ctx;
   const existing = requests.get(key);
   if (existing !== undefined) return existing;
-  const created: Store = { siblings: new Map(), preloaded: new Map(), writes: new Map() };
+  const created: Store = { siblings: new Map(), preloaded: new Map(), writes: 0 };
   requests.set(key, created);
   return created;
 };
@@ -111,8 +115,6 @@ export const siblingKeysHeld = (ctx: Ctx): number => {
   return held;
 };
 
-const writesTo = (store: Store, entity: string): number => store.writes.get(entity) ?? 0;
-
 /**
  * What a page of rows leaves behind: for each foreign key it declares, the distinct values that
  * page carried, filed under every one of them. A later `findById` for any of those values is a
@@ -156,19 +158,20 @@ export const tagSiblings = <Row>(entity: EntityCore<Row>, rows: readonly Row[]):
 };
 
 /**
- * A write makes every preloaded row of that entity stale, so the bucket holding them is not read
- * again. Called before the statement goes out: a row read back afterwards is the row the write
- * left, and one read concurrently with it was concurrent either way.
+ * A write makes every preloaded row stale — of every entity, since the database may rewrite rows
+ * of another (`Store.writes`) — so no bucket open before it is read again. Called before the
+ * statement goes out: a row read back afterwards is the row the write left, and one read
+ * concurrently with it was concurrent either way.
  */
-export const forgetPreloaded = (entityName: string): void => {
+export const forgetPreloaded = (): void => {
   const ctx = tryUseContext();
   if (ctx === undefined) return;
   const store = requests.get(ctx);
   if (store === undefined) return;
-  store.writes.set(entityName, writesTo(store, entityName) + 1);
+  store.writes += 1;
 };
 
-/** The bucket this lookup may be served from, or `undefined` — a stale one is dropped, not read. */
+/** The bucket this lookup may be served from: one opened on this client with no write since. */
 const usableBucket = <Row>(
   store: Store,
   read: PointRead<Row>,
@@ -176,11 +179,15 @@ const usableBucket = <Row>(
 ): Bucket | undefined => {
   const open = store.preloaded.get(scope);
   if (open === undefined) return undefined;
-  if (open.client === read.client && open.generation === writesTo(store, open.entity)) return open;
-  store.preloaded.delete(scope);
-  return undefined;
+  return open.client === read.client && open.generation === store.writes ? open : undefined;
 };
 
+const emptyBucket = <Row>(store: Store, read: PointRead<Row>): Bucket => ({
+  client: read.client,
+  generation: store.writes,
+  rows: new Map<string, Promise<Answer>>(),
+});
+
 type Settlers = ReadonlyMap<string, (answer: Answer) => void>;
 
 /** One statement at a time: a page wide enough to split must not take the pool with it. */
@@ -277,12 +284,15 @@ export const preloadedFindById = <Row>(
   if (already !== undefined) return answered<Row>(already);
   const ids = store.siblings.get(siblingKey(read.entity.$name, read.key.property))?.get(filedAt);
   if (ids === undefined) return undefined;
-  const target = bucket ?? {
-    entity: read.entity.$name,
-    client: read.client,
-    generation: writesTo(store, read.entity.$name),
-    rows: new Map<string, Promise<Answer>>(),
-  };
+  const stale = store.preloaded.get(scope);
+  if (bucket === undefined && stale !== undefined && stale.generation !== store.writes) {
+    // A write since this scope last preloaded. Declined, not re-preloaded: a loop that writes on
+    // every iteration would otherwise re-read the rest of the page each time — the page's rows
+    // squared. The empty bucket lets the first lookup after a write-free stretch preload again.
+    store.preloaded.set(scope, emptyBucket(store, read));
+    return undefined;
+  }
+  const target = bucket ?? emptyBucket(store, read);
   store.preloaded.set(scope, target);
   preload(read, target, keptWindow(read, ids, filedAt));
   const answer = target.rows.get(filedAt);