@ultimat3/entity 1.2.0 → 2.0.0

package/src/batch.ts

@@ -0,0 +1,125 @@
+// Single responsibility: what `inBatches(size)` hands back — the keyset iteration a `for await`
+// consumes, one page per statement, holding its own position and closed by the loop that reads it.
+//
+// Not a second read path. Every batch is the `findMany` the chain would have sent at that
+// position, so filters, tenancy, soft delete, the projection and every `preload()` mean here
+// exactly what they mean in `page()`. What this file owns is the loop, the refusals that belong on
+// the chain rather than one batch later, and what closing means.
+
+import { assertSeekable } from './cursor';
+import type { EntityCore } from './entity';
+import { EntityError } from './errors';
+import { MAX_PAGE_SIZE, totalOrder } from './plan';
+import type { Page } from './repo';
+import type { SortKey } from './tenancy';
+
+/**
+ * A batch size is rows, whole, at least one and at most `MAX_PAGE_SIZE`. `0`, a fraction and a
+ * `NaN` from a parsed environment variable all reach the same statement — `limit 0` reads nothing
+ * forever — so they are refused where they were written instead of hanging a job. The ceiling is
+ * the top of the same range: a batch IS a page (`inBatches` sends the `findMany` the chain would
+ * have sent), so `planFor` would refuse it one statement in, in `limit()`'s voice, for an author
+ * who never wrote a `limit()`.
+ */
+const badBatchSize = (entityName: string, size: number): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.inBatches(${String(size)}) — a batch is a whole number of rows, at least one and at most ${MAX_PAGE_SIZE}`,
+    fix: `${entityName}.inBatches(500)   # the rows one statement reads`,
+  });
+
+/**
+ * `limit()` bounds one page; `inBatches()` reads every page. A chain saying both has written one
+ * number with two meanings, and neither reading is safe to guess: honouring the limit reads a
+ * fraction of a batch, dropping it reads the whole table the caller thought they had bounded.
+ */
+const limitedBatches = (entityName: string, limit: number, size: number): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.limit(${limit}).inBatches(${size}) — limit() bounds one page, inBatches() reads every page`,
+    fix: `${entityName}.inBatches(${limit})   # drop the limit(): the batch size is the page size`,
+  });
+
+/**
+ * What the chain has to be before a batch of it exists. Every one of these is the author's own
+ * text, so all three are refused when `inBatches()` is called rather than one statement in: an
+ * iteration that reads half a table and then fails has already done half the work twice.
+ */
+export const assertBatchable = <Row>(
+  entity: EntityCore<Row>,
+  size: number,
+  chain: { readonly limit: number | undefined; readonly orderBy: readonly SortKey[] },
+): void => {
+  if (!Number.isSafeInteger(size) || size < 1 || size > MAX_PAGE_SIZE) {
+    throw badBatchSize(entity.$name, size);
+  }
+  if (chain.limit !== undefined) throw limitedBatches(entity.$name, chain.limit, size);
+  // The order the driver will sort by, primary key included: the cursor between two batches is
+  // minted from it, and an ordering that cannot carry one fails on the batch *after* the first —
+  // where whatever size the caller happened to pass decides whether anyone ever finds out.
+  assertSeekable(entity, totalOrder(entity, chain.orderBy));
+};
+
+/** Where the batches come from: the chain's own starting position, and one page of it at a time. */
+export interface BatchRead<Row> {
+  /** `after(cursor)` on the chain, or `null` for the first batch. */
+  readonly from: string | null;
+  /** The page this chain reads at `cursor` — relations attached, exactly as `page()` returns it. */
+  page(cursor: string | null): Promise<Page<Row>>;
+}
+
+/**
+ * One iteration, one handle. `for await` consumes it and closes it on the way out — `break`,
+ * `return` and a throw all call `return()` on the iterator, which is what stops the next statement
+ * from going out; `await using` is the same guarantee for a handle kept in a variable. It is its
+ * own iterator, so a second `for await` continues where the first stopped instead of re-reading
+ * the table from the top.
+ */
+export interface BatchIterator<Row> extends AsyncIterable<readonly Row[]>, AsyncDisposable {
+  /**
+   * Where the next batch starts, `null` once there is no next one. Persist it and
+   * `.after(cursor).inBatches(size)` resumes the iteration — which is what makes stopping early
+   * cheap rather than wasted.
+   */
+  readonly cursor: string | null;
+  /** Ends the iteration. Idempotent, and what `await using` calls. */
+  close(): Promise<void>;
+}
+
+/**
+ * The loop itself. Keyset, never OFFSET: each batch resumes from the cursor the previous one ended
+ * on, so a row inserted or deleted mid-iteration cannot make the loop skip or repeat one — the
+ * whole reason this package has no `offset`.
+ */
+export const batchIterator = <Row>(read: BatchRead<Row>): BatchIterator<Row> => {
+  let cursor = read.from;
+
+  async function* batches(): AsyncGenerator<readonly Row[], void, undefined> {
+    do {
+      const page = await read.page(cursor);
+      // Advanced before the yield, so a consumer that breaks reads `.cursor` as the position it
+      // stopped at rather than the one it just consumed.
+      cursor = page.nextCursor;
+      // Never an empty batch: a consumer forced to check `batch.length` is reading around the
+      // iterator instead of through it. The last page ends the loop by its cursor, not by
+      // yielding nothing.
+      if (page.rows.length > 0) yield page.rows;
+    } while (cursor !== null);
+  }
+
+  // Created once and never restarted: the generator's own state is what "closed" means, so
+  // `close()` is idempotent by construction rather than by a flag two paths could disagree about.
+  const iterator = batches();
+  const close = async (): Promise<void> => {
+    await iterator.return(undefined);
+  };
+
+  return {
+    get cursor(): string | null {
+      return cursor;
+    },
+    [Symbol.asyncIterator]: () => iterator,
+    close,
+    [Symbol.asyncDispose]: close,
+  };
+};

package/src/bulk-write.ts

@@ -0,0 +1,285 @@
+// Single responsibility: what a many-row write is made of, decided once in PROPERTY space so both
+// drivers write the same thing — the columns one statement carries, which of them a collision
+// overwrites, and the chunking that keeps a statement inside Postgres's bind count. The SQL is
+// `pg-sql.ts`'s; everything here is the decision that has to precede it, and the in-memory driver
+// reads the same answer rather than a second copy of the rule.
+
+import { keyOf } from './batch-read';
+import { valueAt } from './cursor';
+import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
+import { EntityError, invariantViolated } from './errors';
+import { columnsOf } from './pg-row';
+
+/**
+ * Postgres binds at most 65535 parameters in one statement and a multi-row insert spends
+ * rows × columns of them, so a wide batch becomes several statements rather than one the server
+ * refuses — the same rule `MAX_IDS_PER_STATEMENT` (`batch-read.ts`) applies to a batched read.
+ */
+export const MAX_BIND_PARAMETERS = 65535;
+
+/** What an `upsertAll` resolves to. Property names, so the two drivers read one answer. */
+export interface UpsertPlan {
+  /** The unique constraint a collision is judged against. */
+  readonly on: readonly string[];
+  /** What a colliding row takes from the incoming one. Empty leaves the stored row alone. */
+  readonly set: readonly string[];
+}
+
+const owns = (row: unknown, property: string): boolean =>
+  typeof row === 'object' && row !== null && Object.hasOwn(row, property);
+
+/**
+ * The properties a batch writes: every declared column at least one row names, in declaration
+ * order. `Object.hasOwn` decides it, exactly as `bindValues` does — a property present and
+ * `undefined` is a value the caller wrote, and dropping it here would insert a column the update
+ * set then skipped.
+ */
+export const namedProperties = <Row>(
+  entity: EntityCore<Row>,
+  rows: readonly Partial<Row>[],
+): readonly string[] =>
+  Object.keys(entity.$columns).filter((property) => rows.some((row) => owns(row, property)));
+
+/** Those properties as physical columns. Money is two columns, so this is not the same list. */
+export const insertColumns = <Row>(
+  entity: EntityCore<Row>,
+  properties: readonly string[],
+): readonly string[] =>
+  properties.flatMap((property) => {
+    const column = entity.$columns[property];
+    return column === undefined ? [] : columnsOf(property, column);
+  });
+
+/**
+ * Rows per statement: the bind budget divided by one row's width, never fewer than one. Splitting
+ * can only cost round trips; not splitting would fail a write that succeeded one row at a time.
+ */
+export const insertChunks = <T>(rows: readonly T[], width: number): readonly (readonly T[])[] => {
+  if (rows.length === 0) return [];
+  const size = width <= 0 ? rows.length : Math.max(1, Math.floor(MAX_BIND_PARAMETERS / width));
+  const chunks: (readonly T[])[] = [];
+  for (let from = 0; from < rows.length; from += size) chunks.push(rows.slice(from, from + size));
+  return chunks;
+};
+
+/**
+ * Not `invariantViolated`: its fix opens `x entity explain`, which describes invariants nobody
+ * wrote here. What repairs each of these is one edit to the call.
+ */
+const noConflictTarget = (entityName: string): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.upsertAll() named no onConflict columns — a collision is judged against a unique constraint, never against "any"`,
+    fix: `${entityName}.upsertAll(rows, { onConflict: ['<column>'] })   # the columns of the unique index a duplicate lands on`,
+  });
+
+const nothingToSet = (
+  entityName: string,
+  on: readonly string[],
+  spared: readonly string[],
+): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.upsertAll() would write nothing on a collision: every column in the batch is one a collision never moves (${spared.join(', ')})`,
+    fix: `${entityName}.upsertAll(rows, { onConflict: ['${on.join("', '")}'], onMatch: 'nothing' })   # keep the stored row`,
+  });
+
+const collidesWithItself = (
+  entityName: string,
+  on: readonly string[],
+  position: number,
+): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.upsertAll() row ${position + 1} repeats a value of (${on.join(', ')}) already in the batch — one statement cannot update the same row twice`,
+    fix: `${entityName}.upsertAll(rows, { onConflict: ['${on.join("', '")}'], onMatch: 'nothing' })   # or dedupe rows on (${on.join(', ')}) before the call`,
+  });
+
+const noSuchConstraint = (
+  entityName: string,
+  on: readonly string[],
+  declared: readonly string[],
+): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName} declares no unique constraint on (${on.join(', ')}); Postgres answers a conflict target it cannot match with 42P10${declared.length === 0 ? '' : ` — it has ${declared.join('; ')}`}`,
+    fix: `indexes: [{ on: ['${on.join("', '")}'], unique: true }]   # in the ${entityName} entity(), then x db gen "unique ${on.join(' ')}"`,
+  });
+
+const unevenBatch = (entityName: string, position: number, missing: string): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.upsertAll() row ${position + 1} does not name "${missing}", which other rows of the batch do — under onMatch: 'update' a column one row omits would be overwritten with that column's default, not left alone`,
+    fix: `${entityName}.upsertAll(rows.map((row) => ({ ...row, ${missing}: <value> })), args)   # every row of an updating batch names the same columns`,
+  });
+
+/**
+ * A cross-tenant upsert is not a batching mistake, it is a write into another tenant's row, so it
+ * gets tenancy's own code. `X_TENANCY_UNSCOPED`'s own factory sends the reader to the request
+ * context the tenant is derived from, which is not what repairs this: an upsert builds no read
+ * plan, so nothing derives anything onto it — the scope has to be part of the constraint the
+ * collision is judged against, or the row that comes back was never in scope to begin with.
+ */
+const crossTenantUpsert = (
+  entityName: string,
+  tenant: string,
+  on: readonly string[],
+): EntityError =>
+  new EntityError({
+    code: 'X_TENANCY_UNSCOPED',
+    cause: `${entityName}.upsertAll() resolves a collision on (${on.join(', ')}), which does not include the tenant column "${tenant}" — a row stored by another tenant would match and be overwritten`,
+    fix: `${entityName}.upsertAll(rows, { onConflict: ['${tenant}', '${on.join("', '")}'] })   # or onMatch: 'nothing', which writes nothing to a row it does not own`,
+  });
+
+/**
+ * Every conflict target Postgres could infer an index for. Three sources, because this framework
+ * has three ways to declare one unique index and a target refused for being declared the "wrong"
+ * way would send its author to add a SECOND declaration of a constraint they already wrote:
+ * the primary key, `unique()`/`indexes: [{ unique: true }]` (both land in `$indexes`), and
+ * `invariant(name, c.unique([…]))`, which emits its `create unique index` out of `$invariants`.
+ *
+ * A partial unique index is excluded from all three: its predicate would have to be repeated in
+ * the `on conflict` clause, which this layer does not spell. `bindInvariant` stamps that `where`
+ * on a soft-deleting entity, so the same one rule covers both lists.
+ */
+const uniqueTargets = <Row>(entity: EntityCore<Row>): readonly (readonly string[])[] => [
+  insertColumns(entity, entity.$primaryKey),
+  ...entity.$indexes.filter((i) => i.unique && i.where === undefined).map((i) => i.columns),
+  ...entity.$invariants
+    .filter((i) => i.kind === 'unique' && i.where === undefined)
+    .map((i) => i.columns),
+];
+
+const sameColumns = (left: readonly string[], right: readonly string[]): boolean =>
+  left.length === right.length && [...left].sort().join() === [...right].sort().join();
+
+/**
+ * The conflict target, and what a collision overwrites. `'nothing'` overwrites nothing by
+ * definition; `'update'` takes every column the batch writes except three closed sets — the
+ * conflict target, which is how the stored row was found, the primary key, which is its address,
+ * and the soft-delete stamp, which is whether the row is there at all. An upsert that moved one of
+ * the first two would move a row nobody asked to move, and every foreign key already pointing at
+ * that id would miss it.
+ *
+ * The stamp is the third for a reason no caller can work around: a soft-deleted row still occupies
+ * its conflict target — the unique index it collides with is not partial — so setting `deleted_at`
+ * from `excluded` would clear a stamp the app wrote and hand the row back holding this batch's
+ * values. That is the resurrection `update(id, patch)` and `updateWhere` both refuse by carrying
+ * `deleted_at is null`, which an `on conflict` clause cannot carry. Excluded rather than refused,
+ * because `$parse` fills every declared column before a row reaches here: the `deletedAt: null` in
+ * the batch is the framework's, not the caller's, and refusing it would make `'update'` impossible
+ * on every soft-deleting entity. `insertAll` is untouched — a row with no stored row to collide
+ * with writes the stamp it carries, exactly as `insert` does.
+ *
+ * Four refusals precede all of that, and each one is a statement Postgres would either reject or,
+ * worse, accept: a target no declared unique constraint matches (`42P10`), a target that does not
+ * carry the tenant column under `'update'` (another tenant's row, silently rewritten), a batch
+ * whose rows name different columns under `'update'` (`excluded.<col>` is the column's default for
+ * a row that omitted it, so "leave it alone" is not what happens), and a target that leaves
+ * nothing to write.
+ */
+export const upsertPlan = <Row>(
+  entity: EntityCore<Row>,
+  rows: readonly Partial<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) {
+      throw invariantViolated(
+        entity.$name,
+        'upsertAll',
+        `no column "${property}" — pick from: ${Object.keys(entity.$columns).join(', ')}`,
+      );
+    }
+  }
+  const targets = uniqueTargets(entity);
+  const physical = insertColumns(entity, onConflict);
+  if (!targets.some((target) => sameColumns(target, physical))) {
+    throw noSuchConstraint(
+      entity.$name,
+      onConflict,
+      targets.map((target) => `(${target.join(', ')})`),
+    );
+  }
+  if (onMatch === 'nothing') return { on: onConflict, set: [] };
+  const tenant = entity.$tenantColumn;
+  if (tenant !== null && !onConflict.includes(tenant)) {
+    throw crossTenantUpsert(entity.$name, tenant, onConflict);
+  }
+  const properties = namedProperties(entity, rows);
+  for (const [position, row] of rows.entries()) {
+    const missing = properties.find((property) => !owns(row, property));
+    if (missing !== undefined) throw unevenBatch(entity.$name, position, missing);
+  }
+  const spared = new Set([
+    ...onConflict,
+    ...entity.$primaryKey,
+    ...(entity.$softDelete ? [SOFT_DELETE_COLUMN] : []),
+  ]);
+  const set = properties.filter((property) => !spared.has(property));
+  // An empty batch sends no statement, so there is nothing to refuse — but the target above is
+  // checked either way, so a typo in `onConflict` fails on no rows exactly as it does on a page.
+  if (set.length === 0 && properties.length > 0) {
+    throw nothingToSet(entity.$name, onConflict, [...spared]);
+  }
+  return { on: onConflict, set };
+};
+
+/**
+ * One cell of a conflict target. `keyOf` alone is `batch-read.ts`'s spelling of an *id*, and three
+ * kinds need more than it: a `Date` stringifies without its milliseconds, an object (money is one)
+ * stringifies to `[object Object]`, and — the one that changes an answer — a null is not a value
+ * Postgres compares. A default unique index is `NULLS DISTINCT`, so two rows with a null in the
+ * target collide with nothing, not with each other.
+ */
+const cellKey = (kind: string, value: unknown): string | undefined => {
+  if (value === null || value === undefined) return undefined;
+  if (value instanceof Date) return `date:${value.getTime()}`;
+  if (typeof value === 'object') {
+    return `json:${JSON.stringify(value, (_, part) => (typeof part === 'bigint' ? `${part}n` : part))}`;
+  }
+  return `value:${keyOf(kind, value)}`;
+};
+
+/**
+ * One row's conflict target as a string, spelled the way a batched read spells a key — a `uuid`
+ * handed in upper case is the value Postgres matches, so it must be the value matched here.
+ * `undefined` when any cell is null: that row's target is distinct from every other, as it is in
+ * the index, so it collides with nothing.
+ */
+export const conflictKeyOf = <Row>(
+  entity: EntityCore<Row>,
+  on: readonly string[],
+  row: Partial<Row>,
+): string | undefined => {
+  const cells = on.map((property) =>
+    cellKey(entity.$columns[property]?.$meta.kind ?? '', valueAt(row, property)),
+  );
+  return cells.some((cell) => cell === undefined) ? undefined : JSON.stringify(cells);
+};
+
+/**
+ * Every row's conflict key, refusing a batch that collides with itself. Postgres answers two rows
+ * with one conflict target under `do update` with `ON CONFLICT DO UPDATE command cannot affect row
+ * a second time`, so it is refused here — in both drivers — rather than passing in memory and
+ * failing in production. Under `do nothing` the server skips the repeat, and so does the memory
+ * driver, which is why this only guards the update form.
+ */
+export const conflictKeys = <Row>(
+  entity: EntityCore<Row>,
+  plan: UpsertPlan,
+  rows: readonly Partial<Row>[],
+): readonly (string | undefined)[] => {
+  const keys = rows.map((row) => conflictKeyOf(entity, plan.on, row));
+  if (plan.set.length === 0) return keys;
+  const seen = new Set<string>();
+  for (const [position, key] of keys.entries()) {
+    // A null in the target is no key at all, so it repeats nothing — `NULLS DISTINCT` again.
+    if (key === undefined) continue;
+    if (seen.has(key)) throw collidesWithItself(entity.$name, plan.on, position);
+    seen.add(key);
+  }
+  return keys;
+};

package/src/coalesce.ts

@@ -0,0 +1,175 @@
+// Single responsibility: collapse the point lookups one request issues in the same microtask into
+// a single `where id in (…)`, and hand a lookup a page already answered straight to the preload.
+// A list that resolves an author per row is the N+1 this removes, and it removes it without adding
+// a second way to read — `findById` keeps its signature and its meaning, and pays for one round
+// trip instead of one per row.
+
+import { type Ctx, tryUseContext } from '@ultimat3/core';
+import type { DbClient } from '@ultimat3/db';
+import {
+  type Answer,
+  type KeyColumn,
+  keyOf,
+  type PointRead,
+  readByIds,
+  scopeKey,
+  statementChunks,
+} from './batch-read';
+import type { EntityCore } from './entity';
+import { preloadedFindById } from './jit-preload';
+import { physicalName } from './pg-row';
+import type { ReadShape } from './pg-sql';
+import type { QueryPlan } from './tenancy';
+
+/** One caller's lookup: the row it asked for, and the two ends of the promise it is holding. */
+interface Pending {
+  readonly id: unknown;
+  /** What the answer will be filed under — `keyOf(id)`, not the id itself. */
+  readonly key: string;
+  readonly row: Promise<unknown>;
+  readonly settle: (row: unknown) => void;
+  readonly fail: (error: unknown) => void;
+}
+
+/** One statement in the making: the ids collected so far, and the read that will send them. */
+interface Batch {
+  /** Two lookups share a statement only when they read from the same place. */
+  readonly client: DbClient;
+  /** Keyed by `String(id)`, so the same id asked for twice is one bind and one row. */
+  readonly pending: Map<string, Pending>;
+  readonly load: (ids: readonly unknown[]) => Promise<ReadonlyMap<string, Answer>>;
+}
+
+/**
+ * Per request, keyed by ctx identity, so a batch dies with the request that opened it — the shape
+ * `@ultimat3/query`'s request memo has one tier up. `entity` cannot import that one (tier 2 to
+ * tier 3 is upward), so it owns this one.
+ */
+const requests = new WeakMap<object, Map<string, Batch>>();
+
+const batchesFor = (ctx: Ctx): Map<string, Batch> => {
+  const key: object = ctx;
+  const existing = requests.get(key);
+  if (existing !== undefined) return existing;
+  const created = new Map<string, Batch>();
+  requests.set(key, created);
+  return created;
+};
+
+const pendingFor = (id: unknown, key: string): Pending => {
+  // The executor runs synchronously, so both are assigned before this returns. TypeScript cannot
+  // see through the callback, which is all the definite assignments claim.
+  let settle!: (row: unknown) => void;
+  let fail!: (error: unknown) => void;
+  const row = new Promise<unknown>((resolve, reject) => {
+    settle = resolve;
+    fail = reject;
+  });
+  return { id, key, row, settle, fail };
+};
+
+const openBatch = (
+  batches: Map<string, Batch>,
+  key: string,
+  client: DbClient,
+  load: Batch['load'],
+): Batch => {
+  const batch: Batch = { client, pending: new Map(), load };
+  batches.set(key, batch);
+  // The window is one microtask: every lookup issued before the current synchronous run ends
+  // shares this statement. It closes here, before the statement is sent, so a lookup arriving
+  // mid-flight opens the next batch instead of joining ids already on the wire.
+  queueMicrotask(() => {
+    if (batches.get(key) === batch) batches.delete(key);
+    void flush(batch);
+  });
+  return batch;
+};
+
+const flush = async (batch: Batch): Promise<void> => {
+  const waiting = [...batch.pending.values()];
+  batch.pending.clear();
+  // One statement at a time: a batch wide enough to split must not take the pool with it.
+  for (const chunk of statementChunks(waiting)) {
+    try {
+      const answers = await batch.load(chunk.map((entry) => entry.id));
+      for (const entry of chunk) {
+        const answer = answers.get(entry.key);
+        // An id the statement did not answer for is a row that is not there — `findById`'s `null`,
+        // never a rejection, and never another caller's row.
+        if (answer === undefined) entry.settle(null);
+        else if ('error' in answer) entry.fail(answer.error);
+        else entry.settle(answer.row);
+      }
+    } catch (error) {
+      // The statement failed, so everyone in it gets the failure the single statement would have
+      // handed them. Every one of these promises was returned to a caller, so none goes unhandled.
+      for (const entry of chunk) entry.fail(error);
+    }
+  }
+};
+
+/**
+ * The shared read this lookup joins, or `undefined` when there is none to join: no request in
+ * scope, a composite key, a scope this cannot compare, or a client the open batch does not read
+ * from. Declining is always correct — the caller sends the one statement it always sent.
+ *
+ * Two shapes, one seam. A page already read answers first (one statement for a whole sequential
+ * loop), and what no page can answer joins the microtask batch.
+ */
+export const coalesceFindById = <Row>(
+  entity: EntityCore<Row>,
+  client: DbClient,
+  plan: QueryPlan,
+  shape: ReadShape,
+  id: unknown,
+): Promise<Row | null> | undefined => {
+  const ctx = tryUseContext();
+  const [keyColumn] = entity.$primaryKey;
+  const declared = keyColumn === undefined ? undefined : entity.$columns[keyColumn];
+  if (
+    ctx === undefined ||
+    keyColumn === undefined ||
+    declared === undefined ||
+    entity.$primaryKey.length !== 1
+  ) {
+    return undefined;
+  }
+  // A seek positions a page, never a point lookup. If one ever reaches here the statement is not
+  // the one this batches.
+  if (shape.seek !== undefined) return undefined;
+  const at = plan.where.findIndex(
+    (predicate) =>
+      predicate.column === keyColumn && predicate.op === 'eq' && predicate.value === id,
+  );
+  if (at === -1) return undefined;
+  const scoped: QueryPlan = { ...plan, where: plan.where.filter((_, index) => index !== at) };
+  const key = scopeKey(entity, scoped, shape);
+  if (key === undefined) return undefined;
+
+  const keyColumnRef: KeyColumn = {
+    property: keyColumn,
+    column: physicalName(entity, keyColumn),
+    kind: declared.$meta.kind,
+  };
+  const read: PointRead<Row> = { entity, client, scoped, shape, key: keyColumnRef };
+  // A page whose foreign keys this id is one of answers for every row of that page at once, which
+  // is the only thing that batches a `for … of` loop: its `await` already ended the microtask.
+  const preloaded = preloadedFindById<Row>(ctx, read, key, id);
+  if (preloaded !== undefined) return preloaded;
+
+  const batches = batchesFor(ctx);
+  const open = batches.get(key);
+  // A pinned client and the ambient pool are two places to read from, and a batch is one
+  // statement: a lookup that does not share the open batch's client sends its own.
+  if (open !== undefined && open.client !== client) return undefined;
+  const batch = open ?? openBatch(batches, key, client, (ids) => readByIds(read, ids));
+
+  const filedAt = keyOf(keyColumnRef.kind, id);
+  const already = batch.pending.get(filedAt);
+  const pending = already ?? pendingFor(id, filedAt);
+  if (already === undefined) batch.pending.set(filedAt, pending);
+  // One batch is one entity — the key fixed that before the batch existed — so this re-attaches
+  // the row type the store erased rather than asserting anything new about it.
+  return pending.row as Promise<Row | null>;
+};

package/src/column.ts

@@ -56,6 +56,30 @@ export const bindColumn = (column: AnyColumn, table: string, property: string):
 
 export const bindingOf = (column: AnyColumn): Binding | undefined => bindings.get(column);
 
+/**
+ * A declared foreign key, resolved to where its target actually landed — `null` when the column
+ * declares none. The thunk exists because two schema modules import each other in a cycle, so
+ * this can only be answered after both have evaluated; it is answered in ONE place so the DDL
+ * projection (`describe.ts`) and the relation map (`relations.ts`) can never disagree about what
+ * a `references()` points at.
+ */
+export const referenceBinding = (
+  entityName: string,
+  property: string,
+  meta: ColumnMeta,
+): Binding | null => {
+  if (meta.references === undefined) return null;
+  const target = bindingOf(meta.references());
+  if (target === undefined) {
+    throw invariantViolated(
+      entityName,
+      property,
+      'references a column that belongs to no entity — pass a column of an entity() result',
+    );
+  }
+  return target;
+};
+
 const literal = (value: unknown): ColumnDefault => {
   if (value === null) return { kind: 'value', value: null };
   if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {