@ultimat3/entity 29.3.2 → 30.0.0

package/src/query.ts

@@ -7,24 +7,26 @@
 import type { Page } from '@ultimat3/core';
 import { pageOf } from '@ultimat3/core';
 import { assertBatchable, type BatchIterator, batchIterator } from './batch';
-import { entityNow } from './clock';
+import { overwrittenBy } from './bulk-write';
 import type { EntityCore } from './entity';
 import { searchUndeclared } from './feature-errors';
 import { checkedPredicate, type Operator } from './operator';
-import { assertFinitePageSize, DEFAULT_PAGE_SIZE, namedColumns } from './plan';
+import { assertFinitePageSize, DEFAULT_PAGE_SIZE } from './plan';
 import { preloaded, type RelatedTables } from './preload';
 import { type PreloadOptions, type PreloadRelation, preloadsWith } from './preload-ceiling';
+import { type ReadAggregates, readAggregates } from './read-aggregates';
 import type { Repo, RepoOptions, UpsertArgs } from './repo';
-import { copyRow, pickRow } from './sealed';
+import { pickRow } from './sealed';
 import { SEARCH_PROPERTY } from './search';
+import { type TableLocks, tableLocks } from './table-locks';
 import type { Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
+import { stampedColumns, touch } from './touch';
 import { type Move, transitionRow } from './transition';
 import type {
   ColumnMap,
   Filterable,
   IdOf,
   Insertable,
-  MoneyValue,
   NoSealedKeys,
   RowPatch,
   SealedKeySet,
@@ -42,7 +44,8 @@ export type Preloaded<Name extends string> = { readonly [K in Name]: unknown };
  * `S` names the entity's sealed columns, so naming one in a filter or an order is a COMPILE error
  * and not only `X_ENTITY_SEALED_PREDICATE` at runtime. It defaults to none.
  */
-export interface ReadBuilder<Row, S extends SealedKeySet = NoSealedKeys> {
+export interface ReadBuilder<Row, S extends SealedKeySet = NoSealedKeys>
+  extends ReadAggregates<Row, S> {
   /** Equality on the columns given. `where({ orgId })` is what satisfies the tenancy guard. */
   where(filter: RowPatch<Filterable<Row, S>>): ReadBuilder<Row, S>;
   // NULL is never sealed, so its tests take ANY column. First: `Parameters<…>` reads the last.
@@ -123,65 +126,13 @@ export interface ReadBuilder<Row, S extends SealedKeySet = NoSealedKeys> {
   all(): Promise<readonly Row[]>;
   one(): Promise<Row | null>;
   count(): Promise<number>;
-  /**
-   * The grouped count: one statement, one entry per distinct value of `column`, keyed by that
-   * value — the aggregate a `count()` per row is the N+1 of. `recount every post's likes` is one
-   * `likes.andWhere('postId', 'in', ids).countBy('postId')`, not one statement per post.
-   *
-   * Counts the whole predicate, exactly as `count()` does: the chain's filters, its tenancy and
-   * its soft-delete visibility, never its page. A value nothing matched is absent rather than `0`,
-   * which is what `group by` returns and what lets a caller tell "none" from "never asked".
-   * Entries come back biggest group first, ties by the value, `null` — the group every row without
-   * one shares — last.
-   *
-   * Refused rather than answered: a column whose values a map cannot be keyed by (a timestamp, a
-   * jsonb, money), and a chain matching more distinct values than one statement should answer with.
-   */
-  countBy<K extends Exclude<keyof Row & string, S['sealed']>>(
-    column: K,
-  ): Promise<ReadonlyMap<Row[K], number>>;
-  /**
-   * The four SQL aggregates, over exactly the rows `count()` counts — the chain's filters, its
-   * tenancy and its soft-delete visibility, never its page. "Total spend this month" is
-   * `payments.where({ orgId }).andWhere('paidAt', 'gte', from).sum('amount')`, one statement,
-   * rather than a page loop or a hand-written query outside every guard this layer applies.
-   *
-   * **Never a float.** `sum` and `avg` answer decimal TEXT whatever the column was — the sum of a
-   * million `integer` rows is not an `integer` and `Number()` on it loses digits past 2^53 — and a
-   * money column answers a `MoneyValue` in integer minor units. `min`/`max` answer the row's own
-   * type, because the answer is one of the values that went in.
-   *
-   * `null` for an empty set in every one of them, which is what SQL answers: a `0` would claim
-   * rows were seen.
-   *
-   * Refused rather than answered: a kind with no aggregate the two drivers can agree on (`text`
-   * ordering is the database's collation here and JS code-unit order there), `avg` over money
-   * (every answer would be a silent rounding of a fraction of a minor unit), and an amount
-   * covering more than one currency or scale.
-   */
-  sum<K extends keyof Row & string>(
-    column: K,
-  ): Promise<(Row[K] extends MoneyValue | null ? MoneyValue : string) | null>;
-  avg<K extends keyof Row & string>(column: K): Promise<string | null>;
-  min<K extends keyof Row & string>(column: K): Promise<Row[K] | null>;
-  max<K extends keyof Row & string>(column: K): Promise<Row[K] | null>;
-  /**
-   * The planner's own row estimate for the table — `reltuples`, one row out of `pg_class`, and the
-   * only count that stays constant time as the table grows. `count()` walks every visible row
-   * because MVCC gives it no shortcut, so past a few million it is the read that trips a web
-   * role's `statement_timeout` and no index can make it cheaper.
-   *
-   * The whole TABLE, never the chain's filters — a filtered chain is `X_APPROXIMATE_COUNT_FILTERED`
-   * rather than an estimate that answers a different question than the one asked. `null` when the
-   * table has never been analysed, which is the absence of an estimate and not an estimate of zero.
-   */
-  approximateCount(): Promise<number | null>;
   /** The plan this chain describes. Safe to log — `describePlan()` elides values. */
   plan(): QueryPlan;
 }
 
 export interface Table<Row, C extends ColumnMap = ColumnMap>
-  extends ReadBuilder<Row, SealedKeysOf<C>> {
+  extends ReadBuilder<Row, SealedKeysOf<C>>,
+    TableLocks<Row> {
   /**
    * Move one row through the state machine `column` declares, in ONE statement.
    *
@@ -402,28 +353,7 @@ const builder = <Source, Row>(
 
     count: () => repo.count(args()),
 
-    // The one cast on each of these, and it is the same seam `countBy` and `select()` have: the
-    // driver contract is row-agnostic because a column name is a runtime string there, while the
-    // chain knows which property it just named and therefore what comes back.
-    sum: async <K extends keyof Row & string>(column: K) =>
-      (await repo.aggregate('sum', column, args())) as
-        | (Row[K] extends MoneyValue | null ? MoneyValue : string)
-        | null,
-    avg: async (column: keyof Row & string) =>
-      (await repo.aggregate('avg', column, args())) as string | null,
-    min: async <K extends keyof Row & string>(column: K) =>
-      (await repo.aggregate('min', column, args())) as Row[K] | null,
-    max: async <K extends keyof Row & string>(column: K) =>
-      (await repo.aggregate('max', column, args())) as Row[K] | null,
-
-    approximateCount: () => repo.approximateCount(args()),
-
-    async countBy<K extends keyof Row & string>(column: K) {
-      // The one cast on this terminal, and it is the same seam `select()` has: the driver contract
-      // is row-agnostic because a column name is a runtime string there, while the chain knows
-      // which property it just named and therefore what the map is keyed by.
-      return (await repo.countBy(column, args())) as ReadonlyMap<Row[K], number>;
-    },
+    ...readAggregates(entity, repo, args),
 
     plan: (): QueryPlan => ({
       entity: entity.$name,
@@ -439,26 +369,6 @@ const builder = <Source, Row>(
   };
 };
 
-/**
- * Columns declared `onUpdateNow()` are written by the framework, never by the caller. One helper,
- * so `update(id, patch)` and `updateWhere(filter, patch)` stamp the same columns at the same
- * moment — a second copy is how one of them ends up with a stale `updatedAt`.
- *
- * A patch that names nothing is returned untouched. Stamping `updatedAt` onto "the caller named no
- * columns" would turn that mistake into a real write on any entity that happens to declare the
- * column, and `X_PATCH_EMPTY` downstream would never see it — so whether the refusal fires would
- * depend on the schema rather than on the call.
- */
-const touch = <Row, Patch>(entity: EntityCore<Row>, patch: Patch): Patch => {
-  if (namedColumns(patch).length === 0) return patch;
-  const stamped: Record<string, unknown> = {};
-  for (const [property, column] of Object.entries(entity.$columns)) {
-    if (column.$meta.onUpdate !== undefined) stamped[property] = entityNow();
-  }
-  // `copyRow`, never `Object.assign({}, patch)`: a row passed back whole keeps its sealed properties.
-  return Object.assign(copyRow(patch as object), stamped) as Patch;
-};
-
 // Every write is `async`, matching the repository contract: a failing call rejects and never
 // throws synchronously. `$parse` throws — without the wrapper, a bad row escapes at call time
 // while a bad id rejects, and every call site would need two error paths for one mistake.
@@ -482,11 +392,21 @@ export const tableFor = <Row, C extends ColumnMap>(
   // `touch` and not `$parse` alone: an upsert that lands on a stored row IS an update, so an
   // `onUpdateNow()` column has to move exactly as `update(id, patch)` moves it — and stamping it
   // in a second place is how one of the two ends up writing a stale `updatedAt`.
-  upsertAll: async (rows, args) =>
-    repo.upsertAll(
+  // Asked of the caller's rows, BEFORE `$parse` makes every row name every column: otherwise a
+  // collision resets each column nobody mentioned to its default.
+  upsertAll: async (rows, args) => {
+    const overwrites =
+      args.onMatch === 'nothing'
+        ? undefined
+        : ([
+            ...overwrittenBy(entity, rows as readonly RowPatch<Row>[]),
+            ...stampedColumns(entity),
+          ] as (keyof Row & string)[]);
+    return repo.upsertAll(
       rows.map((row) => touch(entity, entity.$parse(row))),
-      args,
-    ),
+      overwrites === undefined ? args : { ...args, overwrites },
+    );
+  },
   update: async (id, patch, options) => repo.update(id, touch(entity, patch), options),
   delete: async (id, options) => repo.delete(id, options),
   deleteWhere: async (filter, options) => repo.deleteWhere(filter, options),
@@ -497,4 +417,5 @@ export const tableFor = <Row, C extends ColumnMap>(
   // the row moved, using the stamp already declared instead of a second one beside it.
   transition: async (column, id, move, options) =>
     transitionRow(entity, repo, column, id, move, (patch) => touch(entity, patch), options),
+  ...tableLocks(entity, repo),
 });

package/src/read-aggregates.ts

@@ -0,0 +1,138 @@
+// Single responsibility: the chain's aggregate terminals — `countBy`, the four SQL aggregates,
+// `approximateCount` and `series` — typed by the row and forwarded to the row-agnostic repository.
+// Split from `query.ts` at its line ceiling; the chain's arguments arrive as `args()`, so every
+// terminal here counts exactly the rows `count()` counts.
+
+import type { Repo } from './repo';
+import { seriesUnsupported } from './series-unsupported';
+import type { SeriesPoint, SeriesUnit, SeriesValue } from './time-bucket';
+import type { MoneyValue, NoSealedKeys, SealedKeySet } from './types';
+
+/** The properties a series may bucket by: a `timestamp()` column, nullable or not, never sealed. */
+export type TimestampKeys<Row, S extends SealedKeySet = NoSealedKeys> = {
+  [K in keyof Row & string]: K extends S['sealed']
+    ? never
+    : [NonNullable<Row[K]>] extends [Date]
+      ? K
+      : never;
+}[keyof Row & string];
+
+/** What one bucket's `value` is: a count, or the sum `sum()` would answer over that bucket. */
+export type SeriesValueOf<Row, V> = V extends 'count'
+  ? number
+  : V extends { readonly sum: infer K extends keyof Row }
+    ? (Row[K] extends MoneyValue | null ? MoneyValue : string) | null
+    : never;
+
+/** `ReadBuilder.series`'s argument. `timeZone` is required: there is no ambient zone. */
+export interface SeriesOptions<On, V> {
+  readonly on: On;
+  readonly unit: SeriesUnit;
+  readonly timeZone: string;
+  readonly value: V;
+}
+
+export interface ReadAggregates<Row, S extends SealedKeySet = NoSealedKeys> {
+  /**
+   * The grouped count: one statement, one entry per distinct value of `column`, keyed by that
+   * value — the aggregate a `count()` per row is the N+1 of. `recount every post's likes` is one
+   * `likes.andWhere('postId', 'in', ids).countBy('postId')`, not one statement per post.
+   *
+   * Counts the whole predicate, exactly as `count()` does: the chain's filters, its tenancy and
+   * its soft-delete visibility, never its page. A value nothing matched is absent rather than `0`,
+   * which is what `group by` returns and what lets a caller tell "none" from "never asked".
+   * Entries come back biggest group first, ties by the value, `null` — the group every row without
+   * one shares — last.
+   *
+   * Refused rather than answered: a column whose values a map cannot be keyed by (a timestamp, a
+   * jsonb, money), and a chain matching more distinct values than one statement should answer with.
+   */
+  countBy<K extends Exclude<keyof Row & string, S['sealed']>>(
+    column: K,
+  ): Promise<ReadonlyMap<Row[K], number>>;
+  /**
+   * The four SQL aggregates, over exactly the rows `count()` counts — the chain's filters, its
+   * tenancy and its soft-delete visibility, never its page. "Total spend this month" is
+   * `payments.where({ orgId }).andWhere('paidAt', 'gte', from).sum('amount')`, one statement,
+   * rather than a page loop or a hand-written query outside every guard this layer applies.
+   *
+   * **Never a float.** `sum` and `avg` answer decimal TEXT whatever the column was — the sum of a
+   * million `integer` rows is not an `integer` and `Number()` on it loses digits past 2^53 — and a
+   * money column answers a `MoneyValue` in integer minor units. `min`/`max` answer the row's own
+   * type, because the answer is one of the values that went in.
+   *
+   * `null` for an empty set in every one of them, which is what SQL answers: a `0` would claim
+   * rows were seen.
+   *
+   * Refused rather than answered: a kind with no aggregate the two drivers can agree on (`text`
+   * ordering is the database's collation here and JS code-unit order there), `avg` over money
+   * (every answer would be a silent rounding of a fraction of a minor unit), and an amount
+   * covering more than one currency or scale.
+   */
+  sum<K extends keyof Row & string>(
+    column: K,
+  ): Promise<(Row[K] extends MoneyValue | null ? MoneyValue : string) | null>;
+  avg<K extends keyof Row & string>(column: K): Promise<string | null>;
+  min<K extends keyof Row & string>(column: K): Promise<Row[K] | null>;
+  max<K extends keyof Row & string>(column: K): Promise<Row[K] | null>;
+  /**
+   * The planner's own row estimate for the table — `reltuples`, one row out of `pg_class`, and the
+   * only count that stays constant time as the table grows. `count()` walks every visible row
+   * because MVCC gives it no shortcut, so past a few million it is the read that trips a web
+   * role's `statement_timeout` and no index can make it cheaper.
+   *
+   * The whole TABLE, never the chain's filters — a filtered chain is `X_APPROXIMATE_COUNT_FILTERED`
+   * rather than an estimate that answers a different question than the one asked. `null` when the
+   * table has never been analysed, which is the absence of an estimate and not an estimate of zero.
+   */
+  approximateCount(): Promise<number | null>;
+  /**
+   * Rows per time bucket, in the zone named — "signups per day in this person's zone" is
+   * `users.where({ orgId }).series({ on: 'createdAt', unit: 'day', timeZone, value: 'count' })`,
+   * one statement, under the chain's filters, tenancy and soft-delete visibility, never its page.
+   *
+   * `unit` is `minute`, `hour`, `day`, `week` (from Monday) or `month`, truncated as Postgres'
+   * `date_trunc(unit, col, zone)` truncates — so a DST day has 23 or 25 hours and 23:30 UTC is the
+   * next day in Tokyo. `value` is `'count'` or `{ sum: column }`, never a float. Ascending; a
+   * bucket with no rows is absent (the range is the caller's); past `MAX_GROUPS` buckets it is
+   * refused (`X_ENTITY_SERIES_INVALID`), never truncated.
+   */
+  series<
+    On extends TimestampKeys<Row, S>,
+    V extends SeriesValue<Exclude<keyof Row & string, S['sealed']>>,
+  >(spec: SeriesOptions<On, V>): Promise<readonly SeriesPoint<SeriesValueOf<Row, V>>[]>;
+}
+
+/** The members of `Repo` these read, none of which names the row — so any repository fits. */
+type AggregateRepo = Pick<Repo<unknown>, 'aggregate' | 'approximateCount' | 'countBy' | 'series'>;
+
+export const readAggregates = <Row, S extends SealedKeySet>(
+  entity: { readonly $name: string },
+  repo: AggregateRepo,
+  args: () => Parameters<Repo['count']>[0],
+): ReadAggregates<Row, S> => ({
+  // The one cast on each of these, and it is the same seam `select()` has: the driver contract is
+  // row-agnostic because a column name is a runtime string there, while the chain knows which
+  // property it just named and therefore what comes back.
+  sum: async <K extends keyof Row & string>(column: K) =>
+    (await repo.aggregate('sum', column, args())) as
+      | (Row[K] extends MoneyValue | null ? MoneyValue : string)
+      | null,
+  avg: async (column: keyof Row & string) =>
+    (await repo.aggregate('avg', column, args())) as string | null,
+  min: async <K extends keyof Row & string>(column: K) =>
+    (await repo.aggregate('min', column, args())) as Row[K] | null,
+  max: async <K extends keyof Row & string>(column: K) =>
+    (await repo.aggregate('max', column, args())) as Row[K] | null,
+
+  approximateCount: () => repo.approximateCount(args()),
+
+  countBy: async <K extends keyof Row & string>(column: K) =>
+    (await repo.countBy(column, args())) as ReadonlyMap<Row[K], number>,
+
+  series: async <On extends TimestampKeys<Row, S>, V>(spec: SeriesOptions<On, V>) => {
+    if (repo.series === undefined) throw seriesUnsupported(entity.$name);
+    const points = await repo.series({ ...spec, value: spec.value as SeriesValue }, args());
+    return points as readonly SeriesPoint<SeriesValueOf<Row, V>>[];
+  },
+});

package/src/read-capture.ts

@@ -0,0 +1,22 @@
+// Single responsibility: the read half of failure capture — a row a repository answered, into
+// `@ultimat3/core`'s buffer while a captured call is in flight, so `x repro` can seed exactly what
+// the failing code read. Sealed columns never; secret-named columns masked by core. Off, one check.
+
+import { failureCaptureActive, recordFailureFact } from '@ultimat3/core';
+
+/** A recorder for one entity: `sealed` is its sealed properties, which leave through no path. */
+export function readRecorder(
+  entity: string,
+  sealed: readonly string[],
+): (rows: readonly unknown[]) => void {
+  return (rows) => {
+    if (!failureCaptureActive()) return;
+    for (const row of rows) {
+      if (typeof row !== 'object' || row === null) continue;
+      const kept = Object.fromEntries(
+        Object.entries(row).filter(([property]) => !sealed.includes(property)),
+      );
+      recordFailureFact({ kind: 'read', entity, row: kept });
+    }
+  };
+}

package/src/registry.ts

@@ -3,13 +3,27 @@
 // whole domain without importing it — and what makes a duplicate name a build error rather
 // than a silent last-one-wins.
 
-import type { IndexMethod } from '@ultimat3/db';
+import type {
+  CounterDescriptionLike,
+  HistoryDescriptionLike,
+  IndexMethod,
+  RetainDescriptionLike,
+} from '@ultimat3/db';
 import type { EntityCore } from './entity';
 import { entityDuplicate } from './entity-error';
 import type { InvariantKind } from './invariants';
 import type { RecordProjection } from './record-projection';
 import type { ColumnDefault, OnDelete } from './types';
 
+/**
+ * A `references()` whose two ends share a tenant: the physical tenant column on each side, which is
+ * what makes the key composite (`(column, key) -> target (targetColumn, its key)`).
+ */
+export interface SameTenantKey {
+  readonly column: string;
+  readonly targetColumn: string;
+}
+
 export interface ColumnDescription {
   readonly property: string;
   readonly column: string;
@@ -46,6 +60,12 @@ export interface ColumnDescription {
    * none, so a description written before this existed reads the same and nothing regenerates.
    */
   readonly default?: ColumnDefault;
+  /**
+   * Present when the key is same-tenant, absent otherwise: `x verify` hashes this projection, and
+   * an entity with no such edge must hash exactly what it hashed before. `null` is `@ultimat3/db`'s
+   * own word for absent, and this package never writes one here.
+   */
+  readonly sameTenant?: SameTenantKey;
 }
 
 /**
@@ -63,10 +83,14 @@ export interface ReferenceDescription {
   readonly nullable: boolean;
   /** The entity referenced. Not necessarily registered — an entity may point outside a set. */
   readonly targetEntity: string;
+  /** Its physical table, what the key names: the entity's name unless `{ table }` was declared. */
+  readonly targetTable: string;
   readonly targetProperty: string;
   readonly targetColumn: string;
   /** What the database does to this row when the target goes. `null` is Postgres' `no action`. */
   readonly onDelete: OnDelete | null;
+  /** `null` is a plain key: an end with no tenant, the tenant column itself, or `crossTenant`. */
+  readonly sameTenant: SameTenantKey | null;
 }
 
 export interface InvariantDescription {
@@ -112,6 +136,11 @@ export interface IndexDescription {
    * predates the field and an index that declares nothing read the same, so nothing regenerates.
    */
   readonly using?: IndexMethod | undefined;
+  /**
+   * `true` when the index is built with `create index concurrently`, outside a transaction; absent
+   * otherwise, so an entity that never asked hashes exactly what it hashed before.
+   */
+  readonly concurrently?: true | undefined;
 }
 
 export interface EntityDescription {
@@ -127,6 +156,25 @@ export interface EntityDescription {
   readonly orgScoped: boolean;
   /** `entity({ appendOnly: true })`; absent on every entity that did not say it. `x db gen` reads it. */
   readonly appendOnly?: true;
+  /** `entity({ retired: [...] })`; physical names, absent when there are none. `x db gen` reads it. */
+  readonly retired?: readonly string[] | undefined;
+  /** `entity({ shared: '<why>' })`: why a row referencing a tenant's belongs to no tenant. */
+  readonly shared?: string | undefined;
+  /** `entity({ scan: '<why>' })`: why the plan sweep may see this table scanned. */
+  readonly scan?: string | undefined;
+  /**
+   * `entity({ view: { sql } })`: a relation Postgres derives. Absent on a table. `x db gen` emits
+   * it (`@ultimat3/db`'s `generate-view.ts`), admin lists it read-only.
+   */
+  readonly view?: { readonly sql: string; readonly materialized?: true } | undefined;
+  /** `entity({ history: true })`: where its trigger records. Absent otherwise. `x db gen` reads it. */
+  readonly history?: HistoryDescriptionLike;
+  /** `countedIn` keys pointing at it: the counters its children's triggers keep. */
+  readonly counts?: readonly CounterDescriptionLike[];
+  /** `entity({ retain })`: the window and the physical column a purge sweeps by. */
+  readonly retain?: RetainDescriptionLike;
+  /** On a history entity: its parent's name. */
+  readonly historyOf?: string;
 }
 
 export interface RegistryEntry {

package/src/repo.ts

@@ -10,6 +10,7 @@
 import type { Page } from '@ultimat3/core';
 import type { AggregateFn } from './aggregate';
 import type { Predicate, SortKey } from './tenancy';
+import type { SeriesPoint, SeriesSpec } from './time-bucket';
 import type { IdOf, RowPatch, RowWrite } from './types';
 
 export interface Tx {
@@ -48,6 +49,14 @@ export interface UpsertArgs<T = unknown> extends RepoOptions {
    * omits it from the result, so the result is always "the rows this call wrote".
    */
   readonly onMatch?: 'update' | 'nothing';
+  /**
+   * What a collision overwrites, when the rows cannot say it: `db.*.upsertAll` sets this from what
+   * the caller's rows named, plus `onUpdateNow()` columns, because `$parse` fills every column
+   * before a row reaches a repository and an unnamed one would otherwise reset the stored value.
+   * The conflict target, the primary key and the soft-delete stamp stay spared. Absent, every
+   * column the rows write.
+   */
+  readonly overwrites?: readonly (keyof T & string)[];
 }
 
 /**
@@ -144,11 +153,36 @@ export interface Repo<T = unknown> {
    * `MoneyValue`; neither is ever a float.
    */
   aggregate(fn: AggregateFn, column: string, args?: FindManyArgs): Promise<unknown>;
+  /**
+   * One point per time bucket that holds rows, over exactly the rows `count(args)` counts with an
+   * instant in `spec.on` — truncated in `spec.timeZone` as Postgres' `date_trunc(unit, col, zone)`
+   * truncates (`time-bucket.ts`), ascending, refused past `MAX_GROUPS` buckets. `value` is a count
+   * (`number`) or a `sum` (decimal text, or a `MoneyValue`), never a float.
+   *
+   * Optional, like `lock`: a hand-written driver still compiles, and the typed handle answers
+   * `X_ENTITY_SERIES_UNSUPPORTED` for one without it.
+   */
+  series?(spec: SeriesSpec, args?: FindManyArgs): Promise<readonly SeriesPoint[]>;
   /**
    * The planner's own row estimate for the table — not a count, and never filtered. `null` when
    * the table has never been analysed, which is a fact and not an estimate.
    */
   approximateCount(args?: FindManyArgs): Promise<number | null>;
+  /**
+   * The row, locked, for as long as `fn` runs: a read-modify-write that loses no update. A
+   * transaction of its own, or a savepoint in an open one, where the lock lives to the root COMMIT.
+   * The read is the read path's, so another tenant's id and a soft-deleted row are `X_NOT_FOUND`.
+   * `fn` writes with `{ tx }`, the rule on every write.
+   *
+   * Optional, like `lockKey`: a hand-written driver still compiles, and the typed handle answers
+   * `X_LOCK_UNSUPPORTED` for one without it.
+   */
+  lock?<R>(id: IdOf<T>, fn: (row: T, tx: Tx) => Promise<R> | R, options?: RepoOptions): Promise<R>;
+  /**
+   * `fn` alone among callers of this key, in this table and this tenant, for work no one row names.
+   * On a tenant-scoped entity with no actor it is `X_TENANCY_UNSCOPED`, exactly as a read.
+   */
+  lockKey?<R>(key: string, fn: (tx: Tx) => Promise<R> | R, options?: RepoOptions): Promise<R>;
 }
 
 /**

package/src/retain.ts

@@ -0,0 +1,71 @@
+// Single responsibility: `entity({ retain: { after, on } })` checked where it is written. The window
+// is required and the app's — no default anywhere; `on` is an indexed timestamp, or every sweep is a
+// table scan; and `appendOnly` beside it is refused, because that trigger refuses every delete.
+
+import { retainInvalid } from '@ultimat3/db';
+import { parseDuration } from '@ultimat3/time';
+import { columnName } from './column';
+import { EntityError } from './errors';
+import type { AnyColumn, IndexDef } from './types';
+
+/** What `retain` declares: rows whose `on` is older than `after` are swept by `purge()`. */
+export interface RetainInit<K extends string = string> {
+  readonly after: string;
+  readonly on: K;
+}
+
+/** The checked declaration: the window in milliseconds and both spellings of the column. */
+export interface Retain {
+  readonly after: string;
+  readonly afterMs: number;
+  /** The property, as a row names it. */
+  readonly on: string;
+  /** The physical column, as the sweep's statement names it. */
+  readonly column: string;
+}
+
+const windowMs = (entity: string, after: unknown): number => {
+  if (typeof after !== 'string' || after.trim() === '') {
+    throw retainInvalid(entity, "names no after window — the window is the app's to choose");
+  }
+  let ms: number;
+  try {
+    ms = parseDuration(after);
+  } catch {
+    throw retainInvalid(entity, `"${after}" is not a duration like '90d' or '2w'`);
+  }
+  if (!(ms > 0))
+    throw retainInvalid(entity, `"${after}" is no window: it must be longer than zero`);
+  return ms;
+};
+
+/** `null` when `retain` is absent. Every refusal raised here is at declaration. */
+export function retainOf(
+  entity: string,
+  init: RetainInit | undefined,
+  columns: readonly (readonly [string, AnyColumn])[],
+  indexes: readonly IndexDef[],
+  appendOnly: boolean,
+): Retain | null {
+  if (init === undefined) return null;
+  if (appendOnly) {
+    throw retainInvalid(
+      entity,
+      'is appendOnly: its trigger refuses every delete, a sweep included',
+    );
+  }
+  const afterMs = windowMs(entity, init.after);
+  const column = columns.find(([property]) => property === init.on)?.[1];
+  if (column === undefined || column.$meta.kind !== 'timestamptz') {
+    throw retainInvalid(entity, `retain.on "${String(init.on)}" is no timestamp() column of it`);
+  }
+  const physical = columnName(init.on, column.$meta);
+  if (!indexes.some((index) => index.columns[0] === physical)) {
+    throw new EntityError({
+      code: 'X_ENTITY_RETAIN_UNINDEXED',
+      cause: `entity "${entity}" retains by ${init.on}, and no index starts with it: every sweep would read the whole table`,
+      fix: `x db gen "retain index"   # after adding { on: ['${init.on}'] } to indexes in entity('${entity}')`,
+    });
+  }
+  return { after: init.after, afterMs, on: init.on, column: physical };
+}

package/src/row-observer.ts

@@ -16,7 +16,9 @@
 import { currentWriteOrigin } from '@ultimat3/core';
 import { currentTx, expectedQueryLoop } from '@ultimat3/db';
 import type { EntityCore } from './entity';
+import { memoryJournal } from './memory-journal';
 import { MAX_PAGE_SIZE } from './plan';
+import { readRecorder } from './read-capture';
 import type { Repo, RepoOptions, UpsertArgs } from './repo';
 import { sealedFields } from './sealed';
 import type { IdOf, RowPatch } from './types';
@@ -137,7 +139,7 @@ const beforeOf = async <Row>(
 
 /**
  * The `before` rows of a batch, read as ONE statement per `MAX_PAGE_SIZE` ids rather than one per
- * row. Measured on ai-maxxing, 2026-09-06: an `upsertAll` of five pull requests logged
+ * row. Measured on one adopter's app, 2026-09-06: an `upsertAll` of five pull requests logged
  * `X_N_PLUS_ONE_QUERY: pull_requests.findById ran 5 times in one request` — the framework's own
  * feed tripping the framework's own detector, exactly as the job step-write did before #415. A
  * `findById` per row is not even coalesced into one statement, because each one is awaited
@@ -200,14 +202,15 @@ export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Rep
   };
 
   /**
-   * Reported at COMMIT. The write may sit in a transaction — the caller's `options.tx`, or the
-   * ambient `withTransaction` a Postgres repository joins — and a change reported before COMMIT
+   * Reported at COMMIT. The write may sit in a transaction — the caller's `options.tx`, the
+   * ambient `withTransaction` a Postgres repository joins, or the ambient memory one — and a change reported before COMMIT
    * put a row in a live query that a rollback then erased (plan 101, 06 m). Outside a transaction
    * the write is already durable, so it is reported at once. The write origin is read NOW: it is
    * the request's, and the commit callback may run outside that request's scope.
    */
   const afterCommit = (options: RepoOptions | undefined, report: () => void): void => {
-    const tx: { onCommit?(effect: () => void): void } | undefined = options?.tx ?? currentTx();
+    const tx: { onCommit?(effect: () => void): void } | undefined =
+      options?.tx ?? currentTx() ?? memoryJournal();
     if (tx?.onCommit === undefined) report();
     else tx.onCommit(report);
   };
@@ -241,9 +244,24 @@ export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Rep
   // Spread first, exactly as `examples/dummy`'s own capturing driver does: a repository may carry
   // members `Repo` does not name — `memoryRepo`'s `reset()` is one — and a wrapper that listed only
   // the interface would silently drop them.
+  // The read half of failure capture (`read-capture.ts`): one check when no captured call is open.
+  const read = readRecorder(name, sealed);
+
   return {
     ...repo,
 
+    findById: async (id, options) => {
+      const row = await repo.findById(id, options);
+      if (row !== null) read([row]);
+      return row;
+    },
+
+    findMany: async (args) => {
+      const page = await repo.findMany(args);
+      read(page.rows);
+      return page;
+    },
+
     insert: async (values: Row, options?: RepoOptions): Promise<Row> => {
       const stored = await repo.insert(values, options);
       emit('insert', null, stored, options);