@ultimat3/entity 30.8.0 → 31.0.0

package/src/driver-kit-types.ts

@@ -0,0 +1,107 @@
+// Single responsibility: the contract a custom store implements under `defineDriver` — the raw
+// repository. It receives plans the kit has already scoped (tenant, soft delete, page bound, total
+// order, cursor position), never `FindManyArgs`, so there is no argument a driver could read and
+// skip a guard by. Every guard stays the kit's; the store only stores.
+
+import type { AggregateFn } from './aggregate';
+import type { UpsertPlan } from './bulk-write';
+import type { EntityCore } from './entity';
+import type { Transactor, Tx } from './repo';
+import type { QueryPlan } from './tenancy';
+import type { SeriesPoint, SeriesSpec } from './time-bucket';
+
+/**
+ * What a store may declare beyond the required five methods. A call needing an undeclared one is
+ * `X_DRIVER_UNSUPPORTED` with the capability in `meta.capability`; a declared one with no method
+ * behind it is `X_DRIVER_CAPABILITY_MISSING` at definition.
+ */
+export const DRIVER_CAPABILITIES = [
+  'transactions',
+  'lock',
+  'series',
+  'upsert',
+  'matches',
+  'aggregate:countBy',
+  'aggregate:sum',
+  'aggregate:avg',
+  'aggregate:min',
+  'aggregate:max',
+  'aggregate:approximateCount',
+] as const;
+
+export type DriverCapability = (typeof DRIVER_CAPABILITIES)[number];
+
+/** The rows a filtered call addresses. `plan.where` already carries the tenant and soft delete. */
+export interface DriverFilter {
+  readonly plan: QueryPlan;
+  readonly tx?: Tx | undefined;
+}
+
+/**
+ * One page: the rows matching EVERY `plan.where` predicate, ordered by `plan.orderBy`, strictly
+ * after `after` (the cursor's sort values, aligned with `plan.orderBy`) when present, at most
+ * `limit`. Whole rows — the kit projects `select` itself, after it has checked the scope.
+ */
+export interface DriverRead extends DriverFilter {
+  readonly after: readonly unknown[] | undefined;
+  readonly limit: number;
+}
+
+export interface DriverWrite {
+  readonly tx?: Tx | undefined;
+}
+
+/**
+ * Rows arrive narrowed, tenant-checked and invariant-judged; a duplicate key is the store's to
+ * refuse, with `entityUniqueViolation(entity, constraint)`. Writes are all or nothing per call.
+ */
+/** A column `update` moves forward per row rather than sets: see `DriverRepo.update`. */
+export interface DriverAdvance {
+  readonly property: string;
+  readonly stepMs: number;
+}
+
+export interface DriverRepo<Row> {
+  select(read: DriverRead): Promise<readonly Row[]>;
+  count(filter: DriverFilter): Promise<number>;
+  /** The rows as stored, defaults included, in the order given. */
+  insert(rows: readonly Row[], write: DriverWrite): Promise<readonly Row[]>;
+  /**
+   * Sets `patch` (property names, already parsed) on every matched row; answers how many. With
+   * `advance`, the store writes `advance.property` per row as the LATER of the patch's instant and
+   * that row's stored instant + `advance.stepMs`, in the same atomic write — a searchable entity's
+   * version, strictly increasing per row even when two processes write it in one millisecond.
+   * `entityDriverConformance` checks it; `advanceVersion` is the rule for a store merging in code.
+   */
+  update(
+    filter: DriverFilter,
+    patch: Readonly<Record<string, unknown>>,
+    advance?: DriverAdvance,
+  ): Promise<number>;
+  delete(filter: DriverFilter): Promise<number>;
+  /** `'upsert'`. The plan is `bulk-write.ts`'s — target, overwritten columns — already judged. */
+  upsert?(rows: readonly Row[], plan: UpsertPlan, write: DriverWrite): Promise<readonly Row[]>;
+  /** `'aggregate:countBy'`. Pairs of value and count; the kit orders and bounds them. */
+  countBy?(column: string, filter: DriverFilter): Promise<readonly (readonly [unknown, number])[]>;
+  /** `'aggregate:<fn>'`. Decimal text or a money value, never a float; `null` for no rows. */
+  aggregate?(fn: AggregateFn, column: string, filter: DriverFilter): Promise<unknown>;
+  /** `'aggregate:approximateCount'`. The whole table's estimate; `null` when unknown. */
+  approximateCount?(): Promise<number | null>;
+  /** `'series'`. `time-bucket.ts` is the meaning: buckets truncated in `spec.timeZone`. */
+  series?(spec: SeriesSpec, filter: DriverFilter): Promise<readonly SeriesPoint[]>;
+  /** `'lock'`. Holds the one row `filter` addresses for as long as `fn` runs. */
+  lock?<R>(filter: DriverFilter, fn: (row: Row | null, tx: Tx) => Promise<R> | R): Promise<R>;
+  /** `'lock'`. `fn` alone among callers of `key` (already tenant-qualified by the kit). */
+  lockKey?<R>(key: string, fn: (tx: Tx) => Promise<R> | R, tx: Tx | undefined): Promise<R>;
+}
+
+export interface DriverDefinition {
+  /** Named in every refusal, so an operator knows which store answered. */
+  readonly name: string;
+  readonly capabilities: readonly DriverCapability[];
+  repo<Row>(entity: EntityCore<Row>): DriverRepo<Row>;
+  /** Required by `'transactions'`; without it the driver's `transactor()` refuses. */
+  transactor?(): Transactor;
+  /** The test seam `Driver.reset?()` forwards to. */
+  reset?(): void;
+}

package/src/driver-registry.ts

@@ -0,0 +1,26 @@
+// Single responsibility: which kinds of store this process has constructed a driver for, so a
+// tool that loaded the app can tell a Postgres app from one whose rows live in a store that owns
+// its own schema. `x verify`'s drift step reads it: migrations describe Postgres and nothing else.
+
+/** `sql`: Postgres, whose schema `x db` owns. `custom`: a `defineDriver` store, which owns its own. */
+export type DriverStoreKind = 'sql' | 'custom';
+
+const constructed = new Map<DriverStoreKind, Set<string>>();
+
+/** Called by every driver factory as it is built. Idempotent per name. */
+export const noteDriverStore = (kind: DriverStoreKind, name: string): void => {
+  const names = constructed.get(kind) ?? new Set<string>();
+  names.add(name);
+  constructed.set(kind, names);
+};
+
+/** The store names noted so far, per kind. A fresh view: the caller cannot edit the record. */
+export const driverStores = (): Readonly<Record<DriverStoreKind, readonly string[]>> => ({
+  sql: [...(constructed.get('sql') ?? [])].sort(),
+  custom: [...(constructed.get('custom') ?? [])].sort(),
+});
+
+/** TEST SEAM: forget every noted store. */
+export const clearDriverStores = (): void => {
+  constructed.clear();
+};

package/src/driver-repo-reads.ts

@@ -0,0 +1,102 @@
+// Single responsibility: the read half of a `defineDriver` repository. Each method builds its plan
+// with `plan.ts` — the builders both shipped drivers use — so tenancy, the page bound, the total
+// order and the cursor mean here what they mean on Postgres; the store only answers the plan.
+
+import { pageOf } from '@ultimat3/core';
+import { aggregateColumnOf } from './aggregate';
+import { countsFrom, groupColumnOf } from './count-by';
+import { cursorFor, seekFrom } from './cursor';
+import { projectRow } from './driver-rows';
+import type { DriverScope } from './driver-scope';
+import { idPlan, readPlan, singleKeyOf } from './plan';
+import type { Repo } from './repo';
+import { rowKey } from './row-key';
+import { seriesPlanOf } from './time-bucket';
+
+export type DriverReads<Row> = Pick<
+  Repo<Row>,
+  'findById' | 'findMany' | 'count' | 'countBy' | 'aggregate' | 'approximateCount' | 'series'
+>;
+
+export const driverReads = <Row>(scope: DriverScope<Row>): DriverReads<Row> => {
+  const { entity, raw } = scope;
+  const series = raw.series;
+  return {
+    async findById(id, options) {
+      const op = 'findById';
+      singleKeyOf(entity, op);
+      const plan = scope.storePlan(op, idPlan(entity, id, options, op), options?.includeDeleted);
+      const tx = scope.txOf(op, options);
+      const found = await raw.select({ plan, after: undefined, limit: 1, tx });
+      return scope.checked(op, plan, found)[0] ?? null;
+    },
+
+    async findMany(args = {}) {
+      const op = 'findMany';
+      // The cursor is minted and read against the plan `readPlan` built, never the store's copy:
+      // `planScope` hashes the predicates, and the soft-delete one is the kit's, not the caller's.
+      const plan = readPlan(entity, args, op);
+      const after = seekFrom(entity, plan);
+      const stored = scope.storePlan(op, plan, args.includeDeleted);
+      const tx = scope.txOf(op, args);
+      const found = scope.checked(
+        op,
+        stored,
+        await raw.select({ plan: stored, after, limit: plan.limit + 1, tx }),
+      );
+      const page = found.slice(0, plan.limit);
+      const last = page.at(-1);
+      const next =
+        found.length > plan.limit && last !== undefined
+          ? cursorFor(entity, plan, last, rowKey(entity, last))
+          : null;
+      return pageOf(
+        page.map((row) => projectRow(entity, plan, row)),
+        next,
+      );
+    },
+
+    async count(args = {}) {
+      const op = 'count';
+      const plan = scope.storePlan(op, readPlan(entity, args, op), args.includeDeleted);
+      return raw.count({ plan, tx: scope.txOf(op, args) });
+    },
+
+    async countBy(column, args = {}) {
+      const op = 'countBy';
+      groupColumnOf(entity, column, op);
+      scope.need(op, 'aggregate:countBy');
+      const plan = scope.storePlan(op, readPlan(entity, args, op), args.includeDeleted);
+      const groups = await raw.countBy?.(column, { plan, tx: scope.txOf(op, args) });
+      return countsFrom(entity, column, op, groups ?? []);
+    },
+
+    async aggregate(fn, column, args = {}) {
+      aggregateColumnOf(entity, fn, column);
+      scope.need(fn, `aggregate:${fn}`);
+      const plan = scope.storePlan(fn, readPlan(entity, args, fn), args.includeDeleted);
+      return raw.aggregate?.(fn, column, { plan, tx: scope.txOf(fn, args) }) ?? null;
+    },
+
+    async approximateCount(args = {}) {
+      const op = 'approximateCount';
+      // `readPlan` refuses a filter or a tenant-scoped entity first, as on Postgres.
+      readPlan(entity, args, op);
+      scope.need(op, 'aggregate:approximateCount');
+      return (await raw.approximateCount?.()) ?? null;
+    },
+
+    // Present only when declared, so the typed handle answers `X_ENTITY_SERIES_UNSUPPORTED` — the
+    // shipped code for a repository without one — rather than a second code for the same fact.
+    ...(series === undefined || !scope.definition.capabilities.includes('series')
+      ? {}
+      : {
+          async series(spec, args = {}) {
+            const op = 'series';
+            seriesPlanOf(entity, spec);
+            const plan = scope.storePlan(op, readPlan(entity, args, op), args.includeDeleted);
+            return series.call(raw, spec, { plan, tx: scope.txOf(op, args) });
+          },
+        }),
+  };
+};

package/src/driver-repo-writes.ts

@@ -0,0 +1,236 @@
+// Single responsibility: the write half of a `defineDriver` repository. A custom store enforces
+// no CHECK constraint, so EVERY invariant is judged here on the row as it will be stored, with the
+// tenant, before the store is called — and the store is handed only scoped plans and judged rows.
+
+import { refuseAbandoned } from '@ultimat3/db';
+import { conflictKeys, upsertPlan } from './bulk-write';
+import { entityNow } from './clock';
+import { narrowRow } from './columns';
+import { byKeys, checkedDelete } from './driver-delete';
+import type { DriverScope } from './driver-scope';
+import {
+  assertWrittenInScope,
+  sameTenantProperties,
+  sameTenantReferences,
+} from './driver-write-scope';
+import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
+import { notFound } from './errors';
+import { assertedRowsTooMany, MAX_ASSERTED_ROWS } from './invariants';
+import { mergedRow } from './memory-update';
+import { deletePlan, idPlan, namedColumns, singleKeyOf, updatePlan } from './plan';
+import type { Repo, RepoOptions, Tx } from './repo';
+import { advancingVersionColumn, deletionStamp, VERSION_STEP_MS } from './search-index-version';
+import { writtenRowsSink } from './search-written-rows';
+import { assertRowTenant, type QueryPlan } from './tenancy';
+import type { RowPatch, RowWrite } from './types';
+
+export type DriverWrites<Row> = Pick<
+  Repo<Row>,
+  'insert' | 'insertAll' | 'upsertAll' | 'update' | 'delete' | 'deleteWhere' | 'updateWhere'
+>;
+
+export const driverWrites = <Row>(scope: DriverScope<Row>): DriverWrites<Row> => {
+  const { entity, raw } = scope;
+  const references = sameTenantReferences(entity, scope.rawFor);
+  /** What the store handed back, checked against the tenants the write named. */
+  const returned = (op: string, written: readonly Row[], rows: readonly Row[]) =>
+    assertWrittenInScope(scope.definition.name, entity, op, written, rows);
+
+  /** Narrowed, tenant-checked and judged as one batch, before any of it is stored. */
+  const judged = (op: string, given: readonly RowWrite<Row>[]): readonly Row[] => {
+    const batch = given.map((row) => narrowRow<Row>(entity.$columns, row));
+    for (const row of batch) {
+      assertRowTenant(entity.$name, entity.$tenantColumn, op, row);
+      entity.$assert(row);
+    }
+    return batch;
+  };
+
+  /**
+   * The rows a write left, read back by their keys alone — a patch may move a row out of the
+   * filter that matched it — for the search mirror, which asked (`writtenRowsSink`).
+   */
+  const writtenBack = async (
+    op: string,
+    plan: QueryPlan,
+    rows: readonly Row[],
+    tx: Tx | undefined,
+  ) => {
+    const keyed = byKeys(scope, { ...plan, where: [] }, rows);
+    const read: Row[] = [];
+    for (const each of keyed) {
+      const found = await raw.select({ plan: each, after: undefined, limit: rows.length, tx });
+      read.push(...scope.checked(op, each, found));
+    }
+    return read;
+  };
+
+  /**
+   * A patch applied to the rows a plan matches. With an invariant declared, every merged row is
+   * judged first, bounded as a judged write is on Postgres; then one store call. Answers how many
+   * rows the store wrote. A searchable entity's version is the STORE's to advance, per row and
+   * atomically (`DriverRepo.update`'s `advance`): a value the kit computed from a read would let a
+   * second process's newer version be written over.
+   */
+  const patched = async (
+    op: string,
+    plan: QueryPlan,
+    patch: object,
+    options: RepoOptions | undefined,
+  ): Promise<number> => {
+    const tx = scope.txOf(op, options);
+    // Nothing to judge: no read-back and no cap — one store call, as Postgres sends one statement.
+    // The patch's tenant was judged by the caller; a soft-delete stamp names none.
+    const movesReference = namedColumns(patch).some(([key]) =>
+      sameTenantProperties(entity).has(key),
+    );
+    const sink = writtenRowsSink();
+    const version = advancingVersionColumn(entity as EntityCore<unknown>);
+    const advance =
+      version !== undefined && namedColumns(patch).some(([key]) => key === version)
+        ? { property: version, stepMs: VERSION_STEP_MS }
+        : undefined;
+    const narrowed = narrowRow<Record<string, unknown>>(
+      entity.$columns,
+      Object.fromEntries(namedColumns(patch)),
+    );
+    if (entity.$invariants.length === 0 && !movesReference) {
+      // The search mirror asked for the rows: read them first, as the judged path does. Past the
+      // judged bound they are not handed over — the mirror logs the write it could not name.
+      const before =
+        sink === undefined
+          ? []
+          : scope.checked(
+              op,
+              plan,
+              await raw.select({ plan, after: undefined, limit: MAX_ASSERTED_ROWS + 1, tx }),
+            );
+      const written = await raw.update({ plan, tx }, narrowed, advance);
+      if (sink !== undefined && before.length <= MAX_ASSERTED_ROWS) {
+        sink(await writtenBack(op, plan, before, tx));
+      }
+      return written;
+    }
+    // Every invariant, a SQL-expressible one too: a custom store enforces no CHECK.
+    const found = scope.checked(
+      op,
+      plan,
+      await raw.select({ plan, after: undefined, limit: MAX_ASSERTED_ROWS + 1, tx }),
+    );
+    if (found.length > MAX_ASSERTED_ROWS) throw assertedRowsTooMany(entity.$name, op, found.length);
+    const [first] = found;
+    if (first === undefined) return 0;
+    const results = found.map((row) => mergedRow(entity, row, patch));
+    for (const merged of results) {
+      assertRowTenant(entity.$name, entity.$tenantColumn, op, merged);
+      entity.$assert(merged);
+    }
+    await references(results);
+    // The narrowed values the merge produced — the same for every row — so the store holds what
+    // was judged rather than a money `bigint` the row type never carries. The version is the
+    // patch's instant: the store advances it per row.
+    const merged = mergedRow(entity, first, patch) as Record<string, unknown>;
+    const values = Object.fromEntries(namedColumns(patch).map(([key]) => [key, merged[key]]));
+    if (advance !== undefined) values[advance.property] = narrowed[advance.property];
+    const written = await raw.update({ plan, tx }, values, advance);
+    if (sink !== undefined) sink(await writtenBack(op, plan, found, tx));
+    return written;
+  };
+
+  /** Hard or soft, decided once so `delete(id)` and `deleteWhere` cannot drift apart. */
+  const removed = (op: string, plan: QueryPlan, options: RepoOptions | undefined) =>
+    entity.$softDelete
+      ? patched(
+          op,
+          plan,
+          deletionStamp(entity as EntityCore<unknown>, SOFT_DELETE_COLUMN, entityNow()),
+          options,
+        )
+      : checkedDelete(scope, op, plan, options);
+
+  return {
+    async insert(values, options) {
+      refuseAbandoned();
+      const [row] = judged('insert', [values]);
+      if (row === undefined) return narrowRow<Row>(entity.$columns, values);
+      await references([row]);
+      const stored = await raw.insert([row], { tx: scope.txOf('insert', options) });
+      const [written] = returned('insert', [row], stored);
+      return written ?? row;
+    },
+
+    async insertAll(given, options) {
+      refuseAbandoned();
+      const batch = judged('insertAll', given);
+      if (batch.length === 0) return [];
+      await references(batch);
+      return returned(
+        'insertAll',
+        batch,
+        await raw.insert(batch, { tx: scope.txOf('insertAll', options) }),
+      );
+    },
+
+    async upsertAll(given, args) {
+      refuseAbandoned();
+      scope.need('upsertAll', 'upsert');
+      const batch = given.map((row) => narrowRow<Row>(entity.$columns, row));
+      const { onConflict, onMatch = 'update', overwrites } = args;
+      const plan = upsertPlan(entity, batch, onConflict, onMatch, overwrites);
+      conflictKeys(entity, plan, batch);
+      judged('upsertAll', batch);
+      await references(batch);
+      const stored = (await raw.upsert?.(batch, plan, { tx: scope.txOf('upsertAll', args) })) ?? [];
+      return returned('upsertAll', batch, stored);
+    },
+
+    async update(id, given, options) {
+      refuseAbandoned();
+      const op = 'update';
+      const patch = entity.$parsePatch(given);
+      const plan = scope.storePlan(op, idPlan(entity, id, options, op));
+      assertRowTenant(entity.$name, entity.$tenantColumn, op, patch);
+      if (namedColumns(patch).length > 0 && (await patched(op, plan, patch, options)) === 0) {
+        throw notFound(entity.$name, id);
+      }
+      // The row as the store now holds it — what `returning *` answers on Postgres: read by the
+      // key the patch left it under, soft-deleted or not, since the patch may have moved either.
+      const tx = scope.txOf(op, options);
+      // Only a patch that NAMES the stamp may read a soft-deleted row back: an empty patch wrote
+      // nothing, so `update(deletedId, {})` stays the `X_NOT_FOUND` both shipped drivers answer.
+      const named = namedColumns(patch);
+      const movedTo = named.find(([column]) => column === singleKeyOf(entity, op));
+      const key = movedTo === undefined ? id : String(movedTo[1]);
+      const stamps = entity.$softDelete && named.some(([column]) => column === SOFT_DELETE_COLUMN);
+      const reread = scope.storePlan(op, idPlan(entity, key, options, op), stamps);
+      const [after] = scope.checked(
+        op,
+        reread,
+        await raw.select({ plan: reread, after: undefined, limit: 1, tx }),
+      );
+      if (after === undefined) throw notFound(entity.$name, id);
+      return after;
+    },
+
+    async delete(id, options) {
+      refuseAbandoned();
+      const plan = scope.storePlan('delete', idPlan(entity, id, options, 'delete'));
+      if ((await removed('delete', plan, options)) === 0) throw notFound(entity.$name, id);
+    },
+
+    async deleteWhere(filter, options) {
+      refuseAbandoned();
+      const op = 'deleteWhere';
+      return removed(op, scope.storePlan(op, deletePlan(entity, filter, options, op)), options);
+    },
+
+    async updateWhere(filter, given, options) {
+      refuseAbandoned();
+      const op = 'updateWhere';
+      const patch = entity.$parsePatch(given) as RowPatch<Row>;
+      const plan = scope.storePlan(op, updatePlan(entity, filter, patch, options, op));
+      assertRowTenant(entity.$name, entity.$tenantColumn, op, patch);
+      return patched(op, plan, patch, options);
+    },
+  };
+};

package/src/driver-rows.ts

@@ -0,0 +1,108 @@
+// Single responsibility: rows as the driver kit reads them — `selectRows`, the whole read half of
+// an in-process store in one call; the projection `select` asks for; and the scope check every
+// row a custom store returns passes before a caller sees it. Every meaning is borrowed:
+// `matchesPredicate` and `compareByKind` are the memory driver's, which is Postgres' by parity.
+
+import { kindOf, valueAt } from './cursor';
+import type { DriverRead } from './driver-kit-types';
+import type { EntityCore } from './entity';
+import { compareByKind, matchesPredicate } from './memory-match';
+import type { Predicate, QueryPlan } from './tenancy';
+
+/** Lexicographic over the plan's sort keys, direction applied. */
+const compareRows = <Row>(entity: EntityCore<Row>, plan: QueryPlan, a: unknown, b: unknown) => {
+  for (const entry of plan.orderBy) {
+    const order = compareByKind(
+      kindOf(entity, entry.column),
+      valueAt(a, entry.column),
+      valueAt(b, entry.column),
+    );
+    if (order !== 0) return entry.direction === 'desc' ? -order : order;
+  }
+  return 0;
+};
+
+/**
+ * Whether `row` sorts strictly after the cursor's values, by the COLUMN's kind (the seek was
+ * revived from it, `cursor.ts`): one rule for this kit and the memory driver's binary search.
+ */
+export const afterSeek = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  row: unknown,
+  seek: readonly unknown[],
+): boolean => {
+  for (const [index, entry] of plan.orderBy.entries()) {
+    const order = compareByKind(
+      kindOf(entity, entry.column),
+      valueAt(row, entry.column),
+      seek[index],
+    );
+    if (order !== 0) return (entry.direction === 'desc' ? -order : order) > 0;
+  }
+  return false;
+};
+
+/**
+ * A `DriverRead` answered over rows held in process: every predicate, the total order, the
+ * cursor position and the page bound. A key-value or document store that cannot evaluate a plan
+ * natively hands its candidate rows here and returns what comes back.
+ */
+export const selectRows = <Row>(
+  entity: EntityCore<Row>,
+  rows: Iterable<Row>,
+  read: Pick<DriverRead, 'plan' | 'after' | 'limit'>,
+): Row[] => {
+  const { plan, after } = read;
+  const matched = [...rows]
+    .filter((row) => plan.where.every((predicate) => matchesPredicate(entity, row, predicate)))
+    .sort((a, b) => compareRows(entity, plan, a, b));
+  const from =
+    after === undefined ? matched : matched.filter((row) => afterSeek(entity, plan, row, after));
+  return from.slice(0, read.limit);
+};
+
+/**
+ * What `select` returns, as `pg-sql.ts`'s projection reads it: the asked properties, the primary
+ * key and the top-level sort keys — without those the page could not mint its next cursor.
+ */
+export const projectRow = <Row>(entity: EntityCore<Row>, plan: QueryPlan, row: Row): Row => {
+  if (plan.select === undefined) return row;
+  const wanted = new Set([
+    ...plan.select,
+    ...entity.$primaryKey,
+    ...plan.orderBy.map((entry) => entry.column.split('.')[0] ?? entry.column),
+  ]);
+  const source = row as Record<string, unknown>;
+  // Built from the row's own keys, so a property the row never held stays absent, as in Postgres.
+  return Object.fromEntries(
+    Object.keys(source)
+      .filter((key) => wanted.has(key))
+      .map((key) => [key, source[key]]),
+  ) as Row;
+};
+
+/**
+ * The predicates a returned row MUST satisfy whatever the store's own semantics: the tenant, the
+ * soft-delete stamp and the primary key. The caller's other predicates are the store's to mean —
+ * a collation may differ — but these three are the framework's, and a row failing one is a leak.
+ */
+export const structuralPredicates = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  softDeleteColumn: string,
+): readonly Predicate[] =>
+  plan.where.filter(
+    (predicate) =>
+      (predicate.column === entity.$tenantColumn && predicate.op === 'eq') ||
+      (predicate.column === softDeleteColumn && predicate.op === 'is-null') ||
+      (entity.$primaryKey.includes(predicate.column) && predicate.op === 'eq'),
+  );
+
+/** The first structural predicate `row` fails, by column; `undefined` when it is in scope. */
+export const outOfScope = <Row>(
+  entity: EntityCore<Row>,
+  structural: readonly Predicate[],
+  row: unknown,
+): string | undefined =>
+  structural.find((predicate) => !matchesPredicate(entity, row, predicate))?.column;

package/src/driver-scope.ts

@@ -0,0 +1,77 @@
+// Single responsibility: what every method of a `defineDriver` repository shares — the raw store,
+// the capability check, the plan a store is handed (soft delete folded in, `select` and `cursor`
+// taken out) and the scope check on every row a store hands back.
+
+import { driverRowOutOfScope, driverUnsupported } from './driver-errors';
+import type { DriverCapability, DriverDefinition, DriverRepo } from './driver-kit-types';
+import { outOfScope, structuralPredicates } from './driver-rows';
+import type { RawFor } from './driver-write-scope';
+import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
+import type { Tx } from './repo';
+import type { QueryPlan } from './tenancy';
+
+export interface DriverScope<Row> {
+  readonly definition: DriverDefinition;
+  readonly entity: EntityCore<Row>;
+  readonly raw: DriverRepo<Row>;
+  /** Another entity's raw store in this driver — the one a same-tenant reference is read from. */
+  readonly rawFor: RawFor;
+  /** Refuses `X_DRIVER_UNSUPPORTED` unless the driver declared `capability`. */
+  need(operation: string, capability: DriverCapability): void;
+  /** The `tx` a write may carry: only a driver that declared `'transactions'` takes one. */
+  txOf(operation: string, options: { readonly tx?: Tx } | undefined): Tx | undefined;
+  /** The plan as the store sees it. `includeDeleted` is the caller's; writes never pass it. */
+  storePlan(operation: string, plan: QueryPlan, includeDeleted?: boolean): QueryPlan;
+  /** Every row a store returned, refused whole if one is out of the plan's scope. */
+  checked(operation: string, plan: QueryPlan, rows: readonly Row[]): readonly Row[];
+}
+
+export const driverScope = <Row>(
+  definition: DriverDefinition,
+  entity: EntityCore<Row>,
+  rawFor: RawFor,
+): DriverScope<Row> => {
+  const declared: ReadonlySet<DriverCapability> = new Set(definition.capabilities);
+  const need = (operation: string, capability: DriverCapability): void => {
+    if (!declared.has(capability)) {
+      throw driverUnsupported(definition.name, entity.$name, operation, capability);
+    }
+  };
+  return {
+    definition,
+    entity,
+    raw: rawFor(entity),
+    rawFor,
+    need,
+    txOf(operation, options) {
+      if (options?.tx === undefined) return undefined;
+      // A transaction from elsewhere promises atomicity this store cannot give: refused, not
+      // ignored — an ignored tx is a rollback that silently keeps the write.
+      need(operation, 'transactions');
+      return options.tx;
+    },
+    storePlan(operation, plan, includeDeleted = false) {
+      if (plan.where.some((predicate) => predicate.op === 'matches')) need(operation, 'matches');
+      const hidden =
+        entity.$softDelete && !includeDeleted
+          ? [{ column: SOFT_DELETE_COLUMN, op: 'is-null' as const }]
+          : [];
+      return {
+        entity: plan.entity,
+        where: [...plan.where, ...hidden],
+        orderBy: plan.orderBy,
+        limit: plan.limit,
+      };
+    },
+    checked(operation, plan, rows) {
+      const structural = structuralPredicates(entity, plan, SOFT_DELETE_COLUMN);
+      for (const row of rows) {
+        const column = outOfScope(entity, structural, row);
+        if (column !== undefined) {
+          throw driverRowOutOfScope(definition.name, entity.$name, operation, column);
+        }
+      }
+      return rows;
+    },
+  };
+};