@ultimat3/entity 11.2.0 → 12.0.0

package/src/plan.ts

@@ -3,6 +3,7 @@
 // which rows are in scope, what the total sort order is, how big a page is. A guard only one
 // driver applies is worse than none: the test passes and production leaks another tenant's rows.
 
+import { assertSeekable } from './cursor';
 import type { EntityCore } from './entity';
 import { EntityError, invariantViolated, patchEmpty, writeUnfiltered } from './errors';
 import type { FindManyArgs, RepoOptions } from './repo';
@@ -49,19 +50,32 @@ export const singleKeyOf = <Row>(entity: EntityCore<Row>, operation: string): st
  * The primary key is always the final key — a cursor needs a total order, or two rows with the same
  * sort value straddle a page boundary.
  *
+ * The tiebreak takes the LAST DECLARED key's direction rather than an unconditional `asc`, and
+ * that is not a preference. `IndexInit.order` is ONE direction for a whole index, so
+ * `orderBy('createdAt', 'desc')` used to run `created_at desc, id asc` — an order this framework's
+ * own DSL cannot declare an index for, whatever the author wrote. It also decided the seek's
+ * shape: a mixed order has no row comparison, so the seek fell to the or-chain, which measured on
+ * Postgres 16 as a BitmapOr plus a Sort where `(created_at, id) < ($1, $2)` is an Index Only Scan.
+ * A caller who wants the mixed order still writes it — naming the key itself is what turns the
+ * append off.
+ *
  * Exported because a chain can be judged before it runs: `inBatches()` refuses an ordering that
- * cannot carry a cursor, and it has to be looking at the order the driver will send rather than at
- * the one the caller typed.
+ * cannot carry a cursor — an undeclared column, or a nullable key in the TIEBREAK, never an
+ * ordinary nullable one — and it has to be looking at the order the driver will send rather than
+ * at the one the caller typed.
  */
 export const totalOrder = <Row>(
   entity: EntityCore<Row>,
   ordered: readonly SortKey[],
-): readonly SortKey[] => [
-  ...ordered,
-  ...entity.$primaryKey
-    .filter((property) => !ordered.some((entry) => entry.column === property))
-    .map((property) => ({ column: property, direction: 'asc' as const })),
-];
+): readonly SortKey[] => {
+  const direction = ordered.at(-1)?.direction ?? 'asc';
+  return [
+    ...ordered,
+    ...entity.$primaryKey
+      .filter((property) => !ordered.some((entry) => entry.column === property))
+      .map((property) => ({ column: property, direction })),
+  ];
+};
 
 /**
  * What a page size has to be before a statement carries it: rows, whole, at least one and at most
@@ -83,8 +97,20 @@ export const assertPageSize = (entityName: string, rows: number): void => {
   });
 };
 
+/**
+ * Whether an ordering can carry a page position is a property of the ORDER, so it is decided here
+ * — where the order the driver will send is first known — and not in `cursorFor`, which runs only
+ * when a page found one row past its limit. That is what made the refusal depend on the table:
+ * `orderBy('publishedAt', 'desc').limit(20)` over a nullable column was green on fifteen seeded
+ * rows for as long as the test suite existed and `X_INVARIANT_VIOLATED` on the first read past
+ * twenty in production. `assertBatchable` has always judged `inBatches()` this way.
+ *
+ * `cursorFor` and `seekFrom` still call it: they are reached from a driver directly.
+ */
 export const planFor = <Row>(entity: EntityCore<Row>, args: FindManyArgs): QueryPlan => {
   if (args.limit !== undefined) assertPageSize(entity.$name, args.limit);
+  const orderBy = totalOrder(entity, args.orderBy ?? []);
+  assertSeekable(entity, orderBy);
   const scoped =
     args.orgId === undefined || entity.$tenantColumn === null
       ? []
@@ -92,7 +118,7 @@ export const planFor = <Row>(entity: EntityCore<Row>, args: FindManyArgs): Query
   return {
     entity: entity.$name,
     where: [...(args.where ?? []), ...scoped],
-    orderBy: totalOrder(entity, args.orderBy ?? []),
+    orderBy,
     limit: args.limit ?? DEFAULT_PAGE_SIZE,
     ...(args.cursor === undefined || args.cursor === null ? {} : { cursor: args.cursor }),
     ...(args.select === undefined ? {} : { select: args.select }),
@@ -109,7 +135,42 @@ export const readPlan = <Row>(
   entity: EntityCore<Row>,
   args: FindManyArgs,
   operation: string,
-): QueryPlan => scopedPlan(entity.$name, entity.$tenantColumn, operation, planFor(entity, args));
+): QueryPlan => {
+  const plan = planFor(entity, args);
+  // BEFORE tenancy, deliberately. Applied after, a tenant-scoped entity had no reachable call at
+  // all: unscoped it was `X_TENANCY_UNSCOPED` and scoped it was the refusal below, so the method
+  // was declared and unusable — the defect class this repo keeps re-shipping. One refusal, and it
+  // names which of the two situations the caller is in.
+  if (operation === 'approximateCount') assertEstimable(entity, plan);
+  return scopedPlan(entity.$name, entity.$tenantColumn, operation, plan);
+};
+
+/**
+ * An estimate is the TABLE's. `reltuples` knows nothing about a predicate, so a filtered chain
+ * asking for one would be answered a different question from the one it asked — and a caller
+ * reading `posts.where({ orgId }).approximateCount()` as "roughly how many of mine" would be
+ * handed every other tenant's rows too, which is the reading that matters.
+ *
+ * A TENANT-SCOPED entity is therefore refused outright, filters or none: its whole-table estimate
+ * is a number about every tenant, and a per-tenant row count is not a thing the planner holds.
+ * That refusal is not a limitation of this method, it is what the method means.
+ */
+const assertEstimable = <Row>(entity: EntityCore<Row>, plan: QueryPlan): void => {
+  if (entity.$tenantColumn !== null) {
+    throw new EntityError({
+      code: 'X_APPROXIMATE_COUNT_FILTERED',
+      cause: `${entity.$name}.approximateCount() is a whole-TABLE estimate and ${entity.$name} is scoped by ${entity.$tenantColumn} — the planner holds one number for every tenant together`,
+      fix: `${entity.$name}.count()   # the exact answer, scoped to the acting actor's tenant as every other read is`,
+    });
+  }
+  if (plan.where.length === 0) return;
+  const named = plan.where.map((each) => each.column).join(', ');
+  throw new EntityError({
+    code: 'X_APPROXIMATE_COUNT_FILTERED',
+    cause: `${entity.$name}.approximateCount() carries ${plan.where.length} predicate(s) (${named}) — the planner estimates the TABLE and knows nothing about them`,
+    fix: `${entity.$name}.count()   # the exact answer for a filtered chain; approximateCount() answers for the whole table only`,
+  });
+};
 
 /**
  * The plan for an id-addressed write. A write is a query too: without the same guard,

package/src/query.ts

@@ -15,7 +15,7 @@ import type { Relation } from './relations';
 import { relationNamed } from './relations';
 import type { Page, Repo, RepoOptions, UpsertArgs } from './repo';
 import type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
-import type { ColumnMap, IdOf, Insertable, RowPatch } from './types';
+import type { ColumnMap, IdOf, Insertable, MoneyValue, RowPatch } from './types';
 
 /**
  * What a preloaded relation adds to a row. `unknown` because the name is a string resolved at
@@ -59,8 +59,12 @@ export interface ReadBuilder<Row> {
    *
    * The loop closes it: `break`, `return` and a throw all stop the next statement, and
    * `await using` does the same for a handle kept in a variable. A chain that cannot carry a
-   * cursor — a nullable sort column — and a chain that also called `limit()` are refused here,
-   * not one batch later.
+   * cursor and a chain that also called `limit()` are refused here, not one batch later. An
+   * ORDINARY nullable sort column is not one of those: it orders `nulls last` ascending and
+   * `nulls first` descending, and the cursor carries that position. What is refused is a sort key
+   * that leaves the order un-total — an undeclared column, a money property named without its
+   * part, or a nullable PRIMARY-KEY column, where `null = null` is unknown and two such rows are
+   * one position to the seek (`cursor.ts`'s `assertSeekable`).
    */
   inBatches(size: number): BatchIterator<Row>;
   /** The terminal: one bounded page and the cursor that continues it. */
@@ -83,6 +87,42 @@ export interface ReadBuilder<Row> {
    * jsonb, money), and a chain matching more distinct values than one statement should answer with.
    */
   countBy<K extends keyof Row & string>(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;
 }
@@ -276,6 +316,22 @@ 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

package/src/registry.ts

@@ -3,6 +3,7 @@
 // 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 { entityDuplicate } from './errors';
 import type { InvariantKind } from './invariants';
 import type { OnDelete } from './types';
@@ -72,6 +73,12 @@ export interface IndexDescription {
   readonly where: string | null;
   /** `null` is Postgres' own default (`asc`), never written out. */
   readonly order: 'asc' | 'desc' | null;
+  /**
+   * The access method, `undefined` for the `btree` every index was before this existed. Absent
+   * rather than `null`, matching `IndexDescriptionLike.using` in `@ultimat3/db`: a snapshot that
+   * predates the field and an index that declares nothing read the same, so nothing regenerates.
+   */
+  readonly using?: IndexMethod | undefined;
 }
 
 export interface EntityDescription {

package/src/repo.ts

@@ -7,18 +7,8 @@
 //     table silently skips and repeats rows. A keyset cursor is stable because it names a
 //     position in the sort order, not a row count.
 
-import { keyOf } from './batch-read';
-import { conflictKeyOf, conflictKeys, upsertPlan } from './bulk-write';
-import { entityNow } from './clock';
-import { narrowMoney } from './columns';
-import { countsFrom, groupColumnOf } from './count-by';
-import { cursorFor, kindOf, seekFrom, valueAt } from './cursor';
-import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
-import { notFound } from './errors';
-import { compareByKind, matchesPredicate } from './memory-match';
-import { deletePlan, idPlan, readPlan, singleKeyOf, updatePlan } from './plan';
-import type { Predicate, QueryPlan, SortKey } from './tenancy';
-import { assertRowTenant } from './tenancy';
+import type { AggregateFn } from './aggregate';
+import type { Predicate, SortKey } from './tenancy';
 import type { IdOf, RowPatch } from './types';
 
 export interface Tx {
@@ -136,6 +126,20 @@ export interface Repo<T = unknown> {
    * `ReadBuilder.countBy`, which knows the row. Ordered by count, biggest group first.
    */
   countBy(column: string, args?: FindManyArgs): Promise<ReadonlyMap<unknown, number>>;
+  /**
+   * One aggregate over exactly the rows `count(args)` counts. Row-agnostic here and typed on the
+   * chain, the same seam `countBy` has: a column name is a runtime string at this contract.
+   *
+   * `null` for an empty set in every function, which is what SQL answers — a `0` would claim rows
+   * were seen. A `sum` or an `avg` comes back as decimal TEXT and a money aggregate as a
+   * `MoneyValue`; neither is ever a float.
+   */
+  aggregate(fn: AggregateFn, column: string, args?: FindManyArgs): Promise<unknown>;
+  /**
+   * 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>;
 }
 
 /**
@@ -154,319 +158,3 @@ export interface MemoryRepo<Row> extends Repo<Row> {
 export interface Transactor {
   run<R>(work: (tx: Tx) => Promise<R>): Promise<R>;
 }
-
-const field = (row: unknown, property: string): unknown =>
-  typeof row === 'object' && row !== null ? (row as Record<string, unknown>)[property] : undefined;
-
-/** Lexicographic over the sort keys, direction applied. `> 0` means "after the cursor". */
-const compareToSeek = <Row>(
-  entity: EntityCore<Row>,
-  plan: QueryPlan,
-  row: unknown,
-  seek: readonly unknown[],
-): number => {
-  for (const [index, entry] of plan.orderBy.entries()) {
-    // The COLUMN's kind, not the value's: the seek was revived from the same kind (`cursor.ts`),
-    // so a `bigint` column compares its stored decimal string against a revived `BigInt` as one
-    // number instead of as two pieces of text.
-    const order = compareByKind(
-      kindOf(entity, entry.column),
-      valueAt(row, entry.column),
-      seek[index],
-    );
-    if (order !== 0) return entry.direction === 'desc' ? -order : order;
-  }
-  return 0;
-};
-
-/**
- * Where the next page starts. By sort position, not by the previous row's id: that row may have
- * been deleted between the two requests, and an id that is no longer there would restart
- * pagination at the top instead of continuing it.
- */
-const afterCursor = <Row>(
-  entity: EntityCore<Row>,
-  plan: QueryPlan,
-  found: readonly Row[],
-): number => {
-  const seek = seekFrom(entity, plan);
-  if (seek === undefined) return 0;
-  const start = found.findIndex((row) => compareToSeek(entity, plan, row, seek) > 0);
-  return start === -1 ? found.length : start;
-};
-
-/**
- * The default driver: correct semantics, no database. `x dev` uses it before the first
- * migration and tests use it everywhere. Postgres is the production driver and implements
- * this same interface.
- */
-export const memoryRepo = <Row>(
-  entity: EntityCore<Row>,
-  seed: readonly Row[] = [],
-): MemoryRepo<Row> => {
-  /**
-   * A stored row's key, spelled the way `batch-read.ts` spells an id — because Postgres compares a
-   * `uuid` as a VALUE and prints it lower-cased, so `findById(UPPER)` reads the row there while
-   * `String(...)` missed it here: `null` from a read and `X_NOT_FOUND` from a write, against a row
-   * that exists, reachable from a path parameter, a client-supplied id or a legacy import.
-   */
-  const storeKey = (row: unknown): string =>
-    entity.$primaryKey
-      .map((property) => keyOf(kindOf(entity, property) ?? '', field(row, property)))
-      .join('
');
-  /** The same key, from the id a caller named rather than from a row it has in hand. */
-  const idStoreKey = (id: unknown, operation: string): string =>
-    keyOf(kindOf(entity, singleKeyOf(entity, operation)) ?? '', id);
-  const rows = new Map<string, Row>(seed.map((row) => [storeKey(row), row]));
-
-  const rowsOf = (plan: QueryPlan, args: FindManyArgs): Row[] => {
-    const visible = (row: Row): boolean =>
-      !entity.$softDelete ||
-      args.includeDeleted === true ||
-      field(row, SOFT_DELETE_COLUMN) === null ||
-      field(row, SOFT_DELETE_COLUMN) === undefined;
-    return [...rows.values()]
-      .filter((row) => plan.where.every((predicate) => matchesPredicate(entity, row, predicate)))
-      .filter(visible)
-      .sort((left, right) => {
-        for (const entry of plan.orderBy) {
-          const order = compareByKind(
-            kindOf(entity, entry.column),
-            valueAt(left, entry.column),
-            valueAt(right, entry.column),
-          );
-          if (order !== 0) return entry.direction === 'desc' ? -order : order;
-        }
-        return 0;
-      });
-  };
-
-  const select = (args: FindManyArgs, operation: string): { plan: QueryPlan; found: Row[] } => {
-    const plan = readPlan(entity, args, operation);
-    return { plan, found: rowsOf(plan, args) };
-  };
-
-  const write = (given: Row, options: RepoOptions | undefined, operation: string): Row => {
-    // `MoneyInput` lets a writer hand a `bigint`; a stored row holds the value type. The Postgres
-    // driver narrows in `bindValues` and reads its answer back through `returning *`, so without
-    // this an in-memory row would be the one row in the framework `JSON.stringify` refuses.
-    const row = narrowMoney(entity.$columns, given);
-    // Beside `$assert`, and before the row lands: a write is judged by the tenant it names as well
-    // as by the invariants it declares, and the Postgres driver runs the same pair in `writeRows`.
-    // `update` reaches here with the STORED row merged under its patch, so a patch that moves a row
-    // out of this tenant is refused by the same call that refuses an insert into another one.
-    assertRowTenant(entity.$name, entity.$tenantColumn, operation, row);
-    entity.$assert(row);
-    const key = storeKey(row);
-    const previous = rows.get(key);
-    options?.tx?.onRollback(() => {
-      if (previous === undefined) rows.delete(key);
-      else rows.set(key, previous);
-    });
-    rows.set(key, row);
-    return row;
-  };
-
-  // The same guard the read path applies: on a tenant-scoped entity an id alone is not enough
-  // to name a row, so `update`/`delete` resolve through a plan rather than through the map.
-  const addressed = (id: string, options: RepoOptions | undefined, operation: string): Row => {
-    const plan = idPlan(entity, id, options, operation);
-    const current = rows.get(idStoreKey(id, operation));
-    // A soft-deleted row is hidden from writes too — `delete` on one is `X_NOT_FOUND`, not a
-    // second stamp, which is what the Postgres driver's `deleted_at is null` clause already says.
-    const hidden =
-      current !== undefined &&
-      entity.$softDelete &&
-      field(current, SOFT_DELETE_COLUMN) !== null &&
-      field(current, SOFT_DELETE_COLUMN) !== undefined;
-    if (
-      current === undefined ||
-      hidden ||
-      !plan.where.every((predicate) => matchesPredicate(entity, current, predicate))
-    ) {
-      throw notFound(entity.$name, id);
-    }
-    return current;
-  };
-
-  // Every method is async: a repository call that fails must reject, never throw
-  // synchronously, or half the call sites would need two error paths.
-  return {
-    async findById(id, options) {
-      const { found } = select(
-        { ...options, where: [{ column: singleKeyOf(entity, 'findById'), op: 'eq', value: id }] },
-        'findById',
-      );
-      return found[0] ?? null;
-    },
-
-    async findMany(args = {}) {
-      const { plan, found } = select(args, 'findMany');
-      const start = afterCursor(entity, plan, found);
-      const page = found.slice(start, start + plan.limit);
-      const last = page.at(-1);
-      const more = start + page.length < found.length;
-      return {
-        rows: page,
-        nextCursor:
-          more && last !== undefined ? cursorFor(entity, plan, last, storeKey(last)) : null,
-      };
-    },
-
-    async insert(values, options) {
-      return write(values, options, 'insert');
-    },
-
-    async insertAll(batch, options) {
-      // The whole batch is judged before any of it lands: Postgres refuses the statement as one,
-      // so a row an invariant rejects — or one naming a tenant this actor may not write — must not
-      // leave the rows before it stored here either. `write` re-checks both per row; this loop is
-      // what makes the batch all-or-nothing, which is the half a per-row check cannot give.
-      for (const row of batch) {
-        assertRowTenant(entity.$name, entity.$tenantColumn, 'insertAll', row);
-        entity.$assert(row);
-      }
-      return batch.map((row) => write(row, options, 'insertAll'));
-    },
-
-    async upsertAll(batch, args) {
-      // The INCOMING rows, judged before any of them is matched: under `onMatch: 'nothing'` a
-      // colliding row is skipped and never reaches `write()`, so checking only what lands would
-      // let a row naming another tenant through whenever it happened to collide.
-      for (const row of batch) {
-        assertRowTenant(entity.$name, entity.$tenantColumn, 'upsertAll', row);
-        entity.$assert(row);
-      }
-      const plan = upsertPlan(entity, batch, args.onConflict, args.onMatch ?? 'update');
-      const keys = conflictKeys(entity, plan, batch);
-      // The stored rows under the same key, so "does this collide" is the question the unique
-      // index answers in Postgres and not a scan per row. A soft-deleted row still occupies its
-      // key here, because the index it would collide with there is not partial either — and a row
-      // whose target holds a null occupies none, because the index is `NULLS DISTINCT`.
-      const stored = new Map<string, Row>();
-      for (const row of rows.values()) {
-        const key = conflictKeyOf(entity, plan.on, row);
-        if (key !== undefined) stored.set(key, row);
-      }
-      const written: Row[] = [];
-      for (const [position, row] of batch.entries()) {
-        const key = keys[position];
-        const existing = key === undefined ? undefined : stored.get(key);
-        // `do nothing` writes no row, and `returning *` therefore names none: a skipped row is
-        // absent from the result rather than present and unchanged.
-        if (existing !== undefined && plan.set.length === 0) continue;
-        const merged =
-          existing === undefined
-            ? row
-            : Object.assign(
-                {},
-                existing,
-                Object.fromEntries(plan.set.map((property) => [property, field(row, property)])),
-              );
-        // `UpsertArgs extends RepoOptions`, so the args ARE the options — one bag, and a `tx`
-        // passed to an upsert registers its undo exactly as it does for every other write here.
-        const result = write(merged, args, 'upsertAll');
-        // Filed as it lands, so a later row of the same batch collides with an earlier one exactly
-        // as it would with a row the request stored a moment before it.
-        if (key !== undefined) stored.set(key, result);
-        written.push(result);
-      }
-      return written;
-    },
-
-    async update(id, patch, options) {
-      return write(Object.assign({}, addressed(id, options, 'update'), patch), options, 'update');
-    },
-
-    async delete(id, options) {
-      const current = addressed(id, options, 'delete');
-      // Soft delete hides the row without losing it; the column's presence is the switch.
-      if (entity.$softDelete) {
-        write(Object.assign({}, current, { [SOFT_DELETE_COLUMN]: entityNow() }), options, 'delete');
-        return;
-      }
-      const key = storeKey(current);
-      options?.tx?.onRollback(() => rows.set(key, current));
-      rows.delete(key);
-    },
-
-    async deleteWhere(filter, options) {
-      // `rowsOf` is the read path: the same predicates, the same tenant scoping, and the same
-      // soft-delete visibility. A row already stamped is not matched, so a second call cannot
-      // move `deletedAt` forward — which is what the Postgres driver's `deleted_at is null`
-      // clause says there.
-      const doomed = rowsOf(deletePlan(entity, filter, options, 'deleteWhere'), {});
-      for (const row of doomed) {
-        if (entity.$softDelete) {
-          write(
-            Object.assign({}, row, { [SOFT_DELETE_COLUMN]: entityNow() }),
-            options,
-            'deleteWhere',
-          );
-          continue;
-        }
-        const key = storeKey(row);
-        options?.tx?.onRollback(() => rows.set(key, row));
-        rows.delete(key);
-      }
-      return doomed.length;
-    },
-
-    async updateWhere(filter, patch, options) {
-      const plan = updatePlan(entity, filter, patch, options, 'updateWhere');
-      // The PATCH, judged whole and before the rows are read — the same call `postgresRepo` makes
-      // before its statement exists. Inside the loop below it is judged only where a row was
-      // matched, so a patch handing rows to another tenant was refused or accepted depending on
-      // what the table happened to hold: `updateWhere(filter, { orgId: theirs })` over a filter
-      // matching nothing answered `0` here and threw there, from one call.
-      assertRowTenant(entity.$name, entity.$tenantColumn, 'updateWhere', patch);
-      // `rowsOf` again, so a soft-deleted row is as unreachable here as it is through
-      // `addressed()` — patching a row the app has already deleted is not an update, it is a
-      // resurrection nobody asked for. `write` re-asserts the invariants on each result.
-      const found = rowsOf(plan, {});
-      for (const row of found) write(Object.assign({}, row, patch), options, 'updateWhere');
-      return found.length;
-    },
-
-    async count(args = {}) {
-      return select(args, 'count').found.length;
-    },
-
-    async countBy(column, args = {}) {
-      // Refused before a row is read, and by the same function the Postgres driver calls: a column
-      // a map cannot be keyed by is that mistake in both drivers or in neither.
-      groupColumnOf(entity, column, 'countBy');
-      const { found } = select(args, 'countBy');
-      const groups = new Map<unknown, number>();
-      for (const row of found) {
-        // `?? null`, so a property this row never carried lands in the same group Postgres puts a
-        // NULL row in — and `0`, `''` and `false` stay the values they are.
-        const value = field(row, column) ?? null;
-        groups.set(value, (groups.get(value) ?? 0) + 1);
-      }
-      return countsFrom(entity, column, 'countBy', [...groups]);
-    },
-
-    reset() {
-      rows.clear();
-      for (const row of seed) rows.set(storeKey(row), row);
-    },
-  };
-};
-
-let txCounter = 0;
-
-/** In-memory transactor: undo closures registered by drivers run on failure. */
-export const memoryTransactor = (): Transactor => ({
-  async run(work) {
-    const undos: (() => void)[] = [];
-    txCounter += 1;
-    const tx: Tx = { id: `tx-${txCounter}`, onRollback: (undo) => undos.push(undo) };
-    try {
-      return await work(tx);
-    } catch (error) {
-      for (const undo of undos.reverse()) undo();
-      throw error;
-    }
-  },
-});

package/src/tenancy.ts

@@ -13,6 +13,18 @@ import {
 } from './errors';
 import type { ColumnMap } from './types';
 
+/**
+ * The predicate vocabulary, closed. The last four are the CONTAINMENT half, added 2026-08-24: a
+ * `json()` or `arrayOf()` column was declared, written and then unfilterable — the ten operators
+ * before them could compare a column to a scalar and nothing else — so an app storing either had
+ * to leave the query language for hand-written SQL, which is the one read path in this framework
+ * with no tenancy guard on it. Their meaning is Postgres', written once in `containment.ts` and
+ * read by both drivers.
+ *
+ * There is deliberately no jsonpath EXPRESSION operator beside them: `contains` already matches
+ * nested structure (`data @> '{"a":{"b":1}}'`), and a path language inside the query language
+ * would be a second way to ask one question.
+ */
 export type Operator =
   | 'eq'
   | 'neq'
@@ -23,7 +35,11 @@ export type Operator =
   | 'lte'
   | 'like'
   | 'is-null'
-  | 'is-not-null';
+  | 'is-not-null'
+  | 'contains'
+  | 'contained-by'
+  | 'overlaps'
+  | 'has-key';
 
 export interface Predicate {
   readonly column: string;
@@ -195,7 +211,7 @@ const verifyScope = (
  * every repository operation through `readPlan`, so both drivers and every read, write and count
  * pass through this one derivation.
  *
- * Runtime only. There is no build-time tenancy step in `x verify` — its 17 steps check none — and
+ * Runtime only. There is no build-time tenancy step in `x verify` — its 20 steps check none — and
  * there cannot usefully be one: the tenant is a request-time value, so a compiler could only prove
  * that some argument was passed, which is exactly the thing that was never a guarantee. That is
  * why this is the seam every plan is built through rather than a lint.

package/src/types.ts

@@ -6,6 +6,8 @@
 // A column carries its TypeScript type in `$parse`, which is what lets the row type be derived
 // from the column set instead of being written a second time as a hand-maintained schema.
 
+import type { IndexMethod } from '@ultimat3/db';
+
 /**
  * Postgres types the builders emit. `money` expands to `bigint` + `char(3)` (+ a nullable
  * `integer` scale); `array` expands to its element's type with `[]` after it.
@@ -268,4 +270,12 @@ export interface IndexDef {
   readonly order?: 'asc' | 'desc';
   /** Partial index predicate — a soft-deleted row is excluded with this. */
   readonly where?: string;
+  /**
+   * The access method. Absent is `btree`, which is Postgres' own default and what every index
+   * declared before this field existed is — so an entity that names none emits the statement it
+   * always emitted, byte for byte, and no app's sidecar regenerates. `@ultimat3/db` owns the
+   * closed set (`INDEX_METHODS`); redeclaring the union here would be the second declaration of
+   * one fact that this release exists to stop.
+   */
+  readonly using?: IndexMethod;
 }