@ultimat3/entity 30.9.0 → 31.1.0

package/src/batch-read.ts

@@ -46,9 +46,21 @@ export const keyOf = (kind: string, value: unknown): string => {
   if (kind === 'uuid') return String(value).toLowerCase();
   if (kind === 'integer' || kind === 'bigint') return canonicalInteger(value) ?? String(value);
   if (kind === 'numeric') return canonicalDecimal(value) ?? String(value);
+  if (kind === 'timestamptz') return canonicalInstant(value) ?? String(value);
   return String(value);
 };
 
+/**
+ * An instant as ISO 8601 in UTC — a `Date` and its ISO text are one key. `String(date)` was the
+ * process time zone's spelling: a partitioned table's key held a different id per server, and a
+ * search index's id could not be read back into the value it named.
+ */
+const canonicalInstant = (value: unknown): string | undefined => {
+  const ms =
+    value instanceof Date ? value.getTime() : typeof value === 'string' ? Date.parse(value) : NaN;
+  return Number.isFinite(ms) ? new Date(ms).toISOString() : undefined;
+};
+
 /** A scope value has to be comparable as a string, or two scopes cannot be told apart. */
 const scopeValue = (value: unknown): string | undefined => {
   if (value === null || value === undefined) return 'null';

package/src/column.ts

@@ -7,6 +7,7 @@
 // physical name even though two schema modules import each other in a cycle.
 
 import { invariantViolated } from './errors';
+import { isPersonalDataKind, PERSONAL_DATA_KINDS } from './personal-data-kind';
 import { refuseColumn } from './refuse';
 import { DEFAULT_SEARCH_WEIGHT, isSearchWeight } from './search';
 import type {
@@ -216,6 +217,17 @@ export const makeColumn = <T, Optional extends boolean>(
     return makeColumn<T, Optional>({ ...meta, searchable: weight }, parse, optional);
   },
 
+  personalData: (kind) => {
+    if (!isPersonalDataKind(kind)) {
+      refuseColumn(
+        'personal-data',
+        `"${String(kind)}" is not a personal data kind`,
+        `text().personalData('contact') — one of: ${PERSONAL_DATA_KINDS.join(', ')}`,
+      );
+    }
+    return makeColumn<T, Optional>({ ...meta, personalData: kind }, parse, optional);
+  },
+
   tenant: () => makeColumn<T, Optional>({ ...meta, tenant: true, index: true }, parse, optional),
 
   references: (target, options = {}) => {

package/src/columns.ts

@@ -163,6 +163,14 @@ export const url = (): Column<string> =>
  * it is wrong twice a year on top of being unformattable.
  */
 export const tz = <const Z extends readonly string[]>(zones: Z): Column<Z[number]> => {
+  // An empty set renders `x in ()`, which `x db migrate` dies on with 42601 — refused here instead.
+  if (zones.length === 0) {
+    refuseColumn(
+      'iana-tz',
+      'the set of allowed values is empty — no row could ever hold this column',
+      "tz(['Europe/Bucharest']) — declare at least one IANA zone; Intl.supportedValuesOf('timeZone') lists them",
+    );
+  }
   for (const zone of zones) {
     if (!isValidTimeZone(zone)) {
       refuseColumn(
@@ -190,6 +198,13 @@ export const tz = <const Z extends readonly string[]>(zones: Z): Column<Z[number
 const BCP47 = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
 
 export const locale = <const L extends readonly string[]>(locales: L): Column<L[number]> => {
+  if (locales.length === 0) {
+    refuseColumn(
+      'bcp-47',
+      'the set of allowed values is empty — no row could ever hold this column',
+      "locale(['en']) — declare at least one BCP-47 tag",
+    );
+  }
   for (const tag of locales) {
     if (!BCP47.test(tag)) {
       refuseColumn(
@@ -401,17 +416,14 @@ const narrowUuid = <Row>(columns: ColumnMap, row: Row): Row => {
   for (const [property, column] of Object.entries(columns)) {
     if (column.$meta.kind !== 'uuid') continue;
     const value = record[property];
-    // Untouched unless it is a string that actually carries an upper-case character: a malformed
-    // value is the column parser's to refuse, with its own message, and no allocation is paid by
-    // the overwhelmingly common case (axiom 6).
+    // A string Postgres would refuse is refused HERE, in both drivers, with the column parser's
+    // message: a repository write is not parsed, so memory stored `…-0000000000p0` that Postgres
+    // answered 22P02 for. Anything else non-string is the column parser's (or the server's).
     if (typeof value !== 'string') continue;
+    parseUuid(value);
     const lower = value.toLowerCase();
+    // No allocation for the overwhelmingly common case, an id already lower-cased (axiom 6).
     if (lower === value) continue;
-    // And only a value Postgres would have accepted, which is the whole justification for touching
-    // it: the memory driver stores what `$assert` was shown, so a malformed id lower-cased here is
-    // a spelling NEITHER driver holds — Postgres refuses that insert outright. Asked last, so the
-    // regex is paid only by the rare value that carries an upper-case character at all.
-    if (!UUID.test(value)) continue;
     narrowed ??= { ...record };
     narrowed[property] = lower;
   }

package/src/cross-tenant.ts

@@ -7,7 +7,14 @@
 // concurrent requests — one of them ordinary — so it needs an async context. Opened through core's
 // one lazy seam rather than a `node:async_hooks` construction here, which threw at module
 // EVALUATION in a browser bundle (the bundler stubs the module to `{}`).
-import { actorLabel, assert, asyncContext, hasScope, tryUseContext } from '@ultimat3/core';
+import {
+  actorLabel,
+  assert,
+  asyncContext,
+  hasScope,
+  instrument,
+  tryUseContext,
+} from '@ultimat3/core';
 import { crossTenantDenied } from './errors';
 
 /**
@@ -20,18 +27,6 @@ export const CROSS_TENANT_SCOPE = 'tenancy:cross';
 
 const storage = asyncContext<string>('the cross-tenant reason');
 
-let witness: ((reason: string) => void) | undefined;
-
-/**
- * Install the one process-wide witness of every scope opened, or remove it with `undefined`. The
- * caller is `@ultimat3/testing`'s tenant proof: a job that crossed tenants under a declared reason
- * is a sweep, one that crossed without one is a leak, and only the scope itself knows which. One
- * witness, not a list (`setStatementObserver`'s rule), told only after the capability is proven.
- */
-export function setCrossTenantObserver(next: ((reason: string) => void) | undefined): void {
-  witness = next;
-}
-
 /**
  * Run `fn` with the tenant guard lifted — every read and write it issues, at any depth and across
  * every `await`, may span tenants. For the three cases that genuinely have no single tenant: an
@@ -59,7 +54,9 @@ export function crossTenant<T>(reason: string, fn: () => T): T {
     "pass why the read spans tenants: crossTenant('nightly expiry sweeps every org', fn)",
   );
   assertCrossTenant(reason);
-  witness?.(reason);
+  // Emitted only after the capability is proven: `@ultimat3/testing`'s tenant proof subscribes, and
+  // a job that crossed under a declared reason is a sweep, one that crossed without is a leak.
+  instrument('entity.cross_tenant', { reason });
   return storage.run(reason, fn);
 }
 

package/src/cursor.ts

@@ -123,6 +123,9 @@ const serializeSortValue = (kind: ColumnKind, value: unknown): string | undefine
   if (kind === 'timestamptz') return instantMicros(value)?.toString();
   if (value instanceof Date) return value.toISOString();
   if (typeof value === 'bigint') return value.toString();
+  // A `uuid` as its value, the spelling `keyOf` gives it: a store answering upper case must mint
+  // the cursor a lower-case one does, or one position has two cursors.
+  if (kind === 'uuid') return String(value).toLowerCase();
   return String(value);
 };
 

package/src/database.ts

@@ -103,8 +103,8 @@ export const database = <E extends EntitySet>(
   const tables: Record<string, unknown> = {};
   for (const [key, entity] of Object.entries(entities)) {
     // Wrapped here rather than in a driver, so a committed row change is reported the same whether
-    // rows live in memory or in Postgres — `setRowObserver` is the seam, and with none installed the
-    // wrapper is one comparison per write. `related` below stays unwrapped on purpose: a relation
+    // rows live in memory or in Postgres — `entity.row` on the bus, and with no subscriber the
+    // wrapper is one map read per write. `related` below stays unwrapped on purpose: a relation
     // preload is a READ, and a change feed has nothing to say about one.
     tables[key] = tableFor(entity, observedRepo(entity, driver.repo(entity)), related);
   }

package/src/declared-index.ts

@@ -0,0 +1,72 @@
+// One `indexes: [...]` entry of `entity(name, { indexes })` turned into the `IndexDef` it declares,
+// refusing what Postgres would refuse later. Split out of `entity.ts` at the 500-line ceiling.
+
+import { invariantViolated } from './errors';
+import type { InvariantColumns, Resolve } from './expr';
+import type { IndexInit } from './index-init';
+import { indexName } from './index-name';
+import type { ColumnMap, IndexDef } from './types';
+
+export interface DeclaredIndexContext<C extends ColumnMap> {
+  readonly name: string;
+  readonly table: string;
+  readonly resolve: Resolve;
+  readonly columns: InvariantColumns<C>;
+}
+
+export const declaredIndexOf = <C extends ColumnMap>(
+  index: IndexInit<C>,
+  context: DeclaredIndexContext<C>,
+): IndexDef => {
+  const { name, table, resolve, columns: columnsExpr } = context;
+  const columns = index.on.map((property) => resolve([property]));
+  const unique = index.unique === true;
+  // `on: []` is type-legal and names nothing: the generated DDL would be `on "posts" ()`, a
+  // syntax error one migration later. Refused where it was written instead.
+  if (columns.length === 0) {
+    throw invariantViolated(name, 'index', 'an index must name at least one column');
+  }
+  const where = index.where?.(columnsExpr).toSql(resolve) ?? null;
+  if (index.where !== undefined && where === null) {
+    throw invariantViolated(
+      name,
+      'index',
+      'a partial index predicate must be expressible in SQL; a JS predicate cannot be one',
+    );
+  }
+  // Two rules Postgres has that a declaration can break, refused where the author wrote it.
+  // `@ultimat3/db` refuses both again at `createIndex` — that is not a duplicate, it is the
+  // guard for a description nobody built here — but its refusal lands at `x db gen` or, if a
+  // migration was already written, inside `ROLE=migrate` as the server's own syntax error with
+  // none of the entity's words in it.
+  if (index.using !== undefined && index.using !== 'btree') {
+    if (unique) {
+      throw invariantViolated(
+        name,
+        'index',
+        `the index on (${columns.join(', ')}) is unique and ${index.using}; ` +
+          `Postgres has no unique ${index.using} index — drop unique, or drop using`,
+      );
+    }
+    if (index.order !== undefined) {
+      throw invariantViolated(
+        name,
+        'index',
+        `the index on (${columns.join(', ')}) is ${index.using} and ${index.order}; ` +
+          'only a btree orders its keys — drop order, or drop using',
+      );
+    }
+  }
+  return {
+    name: indexName(name, table, columns, unique, index.order, where, index.using),
+    columns,
+    unique,
+    ...(index.order === undefined ? {} : { order: index.order }),
+    ...(where === null ? {} : { where }),
+    // Absent stays absent: `btree` written out would be a field every existing snapshot lacks,
+    // and `indexMethodOf` reads the two the same way precisely so nothing regenerates.
+    ...(index.using === undefined || index.using === 'btree' ? {} : { using: index.using }),
+    // How it is BUILT, so not part of the name: `true` or absent, like `appendOnly`.
+    ...(index.concurrently === true ? { concurrently: true as const } : {}),
+  };
+};

package/src/define-driver.ts

@@ -0,0 +1,156 @@
+// Single responsibility: `defineDriver` — a custom store (Mongo, Cassandra, key-value) as a `Driver`.
+// The store sees only scoped plans and judged rows; this assembles the read and write halves, the
+// locks and both outer seams (`sealedRepo`, then `appendOnlyRepo`), so nothing a store forgets
+// becomes a leak. Capabilities are declared here and checked when a table opens.
+
+import { refuseAbandoned } from '@ultimat3/db';
+import { appendOnlyRepo } from './append-only';
+import type { Driver } from './database';
+import { driverCapabilityMissing, driverUnsupported } from './driver-errors';
+import type { DriverCapability, DriverDefinition, DriverRepo } from './driver-kit-types';
+import { noteDriverStore } from './driver-registry';
+import { driverReads } from './driver-repo-reads';
+import { driverWrites } from './driver-repo-writes';
+import { driverScope } from './driver-scope';
+import type { RawFor } from './driver-write-scope';
+import type { EntityCore } from './entity';
+import { notFound } from './errors';
+import { lockKeyInput } from './lock-key';
+import { idPlan } from './plan';
+import type { Repo, RepoOptions, Tx } from './repo';
+import { sealedRepo } from './sealed-repo';
+import type { IdOf } from './types';
+
+export type {
+  DriverAdvance,
+  DriverCapability,
+  DriverDefinition,
+  DriverFilter,
+  DriverRead,
+  DriverRepo,
+  DriverWrite,
+} from './driver-kit-types';
+
+/** The raw-repo member each capability needs; `transactions` is the definition's `transactor`. */
+const MEMBER: Readonly<Record<DriverCapability, keyof DriverRepo<unknown> | 'transactor'>> = {
+  transactions: 'transactor',
+  lock: 'lock',
+  series: 'series',
+  upsert: 'upsert',
+  matches: 'select',
+  'aggregate:countBy': 'countBy',
+  'aggregate:sum': 'aggregate',
+  'aggregate:avg': 'aggregate',
+  'aggregate:min': 'aggregate',
+  'aggregate:max': 'aggregate',
+  'aggregate:approximateCount': 'approximateCount',
+};
+
+const assertImplemented = (definition: DriverDefinition, raw: DriverRepo<unknown>): void => {
+  for (const capability of definition.capabilities) {
+    // Own keys only: a JS caller's `capabilities: ['toString']` must not read the prototype.
+    const member = Object.hasOwn(MEMBER, capability) ? MEMBER[capability] : undefined;
+    if (member === undefined) {
+      throw driverCapabilityMissing(definition.name, String(capability), 'a known capability');
+    }
+    const present =
+      member === 'transactor'
+        ? typeof definition.transactor === 'function'
+        : typeof raw[member] === 'function';
+    if (!present) throw driverCapabilityMissing(definition.name, capability, member);
+    // `'lock'` is two methods, as `Repo` has: one alone would leave both absent on the repository.
+    if (capability === 'lock' && typeof raw.lockKey !== 'function') {
+      throw driverCapabilityMissing(definition.name, capability, 'lockKey');
+    }
+  }
+};
+
+/** A `defineDriver` repository for one entity: reads, writes, locks when declared, both seams. */
+const driverRepo = <Row>(
+  definition: DriverDefinition,
+  entity: EntityCore<Row>,
+  rawFor: RawFor,
+): Repo<Row> => {
+  const scope = driverScope(definition, entity, rawFor);
+  assertImplemented(definition, scope.raw as DriverRepo<unknown>);
+  const { raw } = scope;
+  // Absent unless declared, so the typed handle answers the shipped `X_LOCK_UNSUPPORTED`.
+  const locks = (): Pick<Repo<Row>, 'lock' | 'lockKey'> => {
+    const { lock, lockKey } = raw;
+    if (lock === undefined || lockKey === undefined) return {};
+    if (!definition.capabilities.includes('lock')) return {};
+    return {
+      async lock<R>(
+        id: IdOf<Row>,
+        fn: (row: Row, tx: Tx) => Promise<R> | R,
+        options?: RepoOptions,
+      ): Promise<R> {
+        refuseAbandoned();
+        const plan = scope.storePlan('lock', idPlan(entity, id, options, 'lock'));
+        const tx = scope.txOf('lock', options);
+        return lock.call<DriverRepo<Row>, Parameters<typeof lock<R>>, Promise<R>>(
+          raw,
+          { plan, tx },
+          (row, held) => {
+            if (row === null) throw notFound(entity.$name, id);
+            const [inScope] = scope.checked('lock', plan, [row]);
+            return fn(inScope ?? row, held);
+          },
+        );
+      },
+      async lockKey<R>(key: string, fn: (tx: Tx) => Promise<R> | R, options?: RepoOptions) {
+        refuseAbandoned();
+        return lockKey.call<DriverRepo<Row>, Parameters<typeof lockKey<R>>, Promise<R>>(
+          raw,
+          lockKeyInput(entity, key, options),
+          fn,
+          options?.tx,
+        );
+      },
+    };
+  };
+  const repo: Repo<Row> = { ...driverReads(scope), ...driverWrites(scope), ...locks() };
+  return appendOnlyRepo(entity, sealedRepo(entity, repo));
+};
+
+/**
+ * `database(entities, { driver: defineDriver({ name, capabilities, repo }) })`. Repositories are
+ * built once per entity, as `memoryDriver()`'s are, so a store keeping state per table keeps one.
+ */
+export const defineDriver = (definition: DriverDefinition): Driver => {
+  if (definition.capabilities.includes('transactions') && definition.transactor === undefined) {
+    throw driverCapabilityMissing(definition.name, 'transactions', 'transactor');
+  }
+  noteDriverStore('custom', definition.name);
+  const repos = new Map<string, unknown>();
+  // One raw store per entity, shared by its own repository and by every reference read into it.
+  const raws = new Map<string, unknown>();
+  const rawFor: RawFor = <R>(entity: EntityCore<R>): DriverRepo<R> => {
+    const known = raws.get(entity.$name);
+    if (known !== undefined) return known as DriverRepo<R>;
+    const created = definition.repo(entity);
+    raws.set(entity.$name, created);
+    return created;
+  };
+  const transactor = definition.transactor;
+  const reset = definition.reset;
+  return {
+    repo: <Row>(entity: EntityCore<Row>): Repo<Row> => {
+      const existing = repos.get(entity.$name);
+      // Keyed by entity name and written only from that entity, so the row type is the stored one.
+      if (existing !== undefined) return existing as Repo<Row>;
+      const created = driverRepo(definition, entity, rawFor);
+      repos.set(entity.$name, created);
+      return created;
+    },
+    // No `'transactions'`: a seed dry run (which writes and rolls back) refuses here, by name,
+    // rather than writing for real into a store that cannot undo.
+    transactor: () => {
+      if (transactor === undefined) {
+        throw driverUnsupported(definition.name, definition.name, 'transactor', 'transactions');
+      }
+      return transactor.call(definition);
+    },
+    ...(reset === undefined ? {} : { reset: () => reset.call(definition) }),
+  };
+};

package/src/describe.ts

@@ -10,6 +10,7 @@ import { currencyCheck, scaleCheck } from './columns';
 import { EntityError, invariantViolated } from './errors';
 import type { Invariant } from './invariants';
 import type { LifecycleDescription } from './lifecycle';
+import type { PartitionDescription } from './partition';
 import type {
   ColumnDescription,
   EntityDescription,
@@ -48,6 +49,8 @@ export interface DescribeInput<Row> {
   readonly view?: ViewQuery | null | undefined;
   /** `retain`, `history`, `countedIn` counters — each projected only when declared (`lifecycle.ts`). */
   readonly lifecycle?: LifecycleDescription | undefined;
+  /** `entity({ partitionBy })`, checked (`partition.ts`) — projected only when declared. */
+  readonly partition?: PartitionDescription | null | undefined;
 }
 
 /**
@@ -385,5 +388,7 @@ export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescriptio
           },
         }),
     ...input.lifecycle,
+    // Absent unless declared: no entity that never said `partitionBy` moves the hash.
+    ...(input.partition == null ? {} : { partition: input.partition }),
   };
 };

package/src/driver-delete.ts

@@ -0,0 +1,62 @@
+// Single responsibility: a custom store's HARD delete. The rows are read and scope-checked first,
+// then deleted by their checked keys only — a store whose filter ignores the tenant is refused
+// before it removes anything, rather than discovered by the rows another tenant no longer has.
+
+import { valueAt } from './cursor';
+import type { DriverScope } from './driver-scope';
+import { describeCommand, EntityError } from './errors';
+import { MAX_ASSERTED_ROWS } from './invariants';
+import type { RepoOptions } from './repo';
+import { writtenRowsSink } from './search-written-rows';
+import type { Predicate, QueryPlan } from './tenancy';
+
+const tooMany = (entityName: string, operation: string, matched: number): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.${operation}() matches more than ${MAX_ASSERTED_ROWS} rows (${matched} read) on a custom driver, whose delete is checked row by row before the store removes any. Sweep the filter with .where(filter).inBatches(1000) and delete each page`,
+    fix: `${describeCommand(entityName)}   # the entity whose filtered delete must be swept in pages`,
+  });
+
+/** The key predicates that name exactly these rows, beside the plan's own. */
+export const byKeys = <Row>(scope: DriverScope<Row>, plan: QueryPlan, rows: readonly Row[]) => {
+  const keys = scope.entity.$primaryKey;
+  const [only] = keys;
+  if (keys.length === 1 && only !== undefined) {
+    const where: Predicate[] = [
+      { column: only, op: 'in', value: rows.map((row) => valueAt(row, only)) },
+      ...plan.where,
+    ];
+    return [{ ...plan, where }];
+  }
+  return rows.map((row) => ({
+    ...plan,
+    where: [
+      ...keys.map((key): Predicate => ({ column: key, op: 'eq', value: valueAt(row, key) })),
+      ...plan.where,
+    ],
+  }));
+};
+
+/** Answers how many rows the store removed. */
+export const checkedDelete = async <Row>(
+  scope: DriverScope<Row>,
+  op: string,
+  plan: QueryPlan,
+  options: RepoOptions | undefined,
+): Promise<number> => {
+  const tx = scope.txOf(op, options);
+  const found = scope.checked(
+    op,
+    plan,
+    await scope.raw.select({ plan, after: undefined, limit: MAX_ASSERTED_ROWS + 1, tx }),
+  );
+  if (found.length > MAX_ASSERTED_ROWS) throw tooMany(scope.entity.$name, op, found.length);
+  if (found.length === 0) return 0;
+  let removed = 0;
+  for (const keyed of byKeys(scope, plan, found)) {
+    removed += await scope.raw.delete({ plan: keyed, tx });
+  }
+  // The checked rows, for the search mirror when it asked (`search-written-rows.ts`).
+  writtenRowsSink()?.(found);
+  return removed;
+};

package/src/driver-errors.ts

@@ -0,0 +1,80 @@
+// Single responsibility: the refusals a custom driver built with `defineDriver` meets, and the
+// unique-violation a store raises for a duplicate key. The codes and titles live in
+// `entity-error.ts` with every other entity code; these carry `meta.capability`, which
+// `EntityError` has no slot for, so they are `UltimateError`s of their own.
+
+import { renderCauseValue, UltimateError } from '@ultimat3/core';
+import { DbError } from '@ultimat3/db';
+import type { EntityCore } from './entity';
+import type { EntityErrorCode } from './entity-error';
+
+/** One refusal of this file: an entity code, plus the capability or the store it names. */
+export class DriverError extends UltimateError {
+  override readonly name = 'DriverError';
+
+  constructor(init: {
+    code: EntityErrorCode;
+    cause: string;
+    fix: string;
+    meta: Readonly<Record<string, unknown>>;
+  }) {
+    super(init);
+  }
+}
+
+/** A call needs a capability the driver did not declare. Raised before the store is reached. */
+export const driverUnsupported = (
+  driverName: string,
+  entityName: string,
+  operation: string,
+  capability: string,
+): DriverError =>
+  new DriverError({
+    code: 'X_DRIVER_UNSUPPORTED',
+    cause: `${entityName}.${operation}() needs '${capability}', and driver ${renderCauseValue(driverName)} does not declare it in defineDriver({ capabilities })`,
+    fix: `defineDriver({ name: ${JSON.stringify(driverName)}, capabilities: [..., '${capability}'], repo })   # and implement it on the object repo() returns — or read ${entityName} through postgresDriver(), which has every capability`,
+    meta: { capability, driver: driverName, entity: entityName, operation },
+  });
+
+/** A declared capability with nothing behind it: refused when the driver is defined. */
+export const driverCapabilityMissing = (
+  driverName: string,
+  capability: string,
+  member: string,
+): DriverError =>
+  new DriverError({
+    code: 'X_DRIVER_CAPABILITY_MISSING',
+    cause: `driver ${renderCauseValue(driverName)} declares '${capability}' and provides no ${member}`,
+    fix: `defineDriver({ name: ${JSON.stringify(driverName)}, capabilities: [/* without '${capability}' */], repo })   # or implement ${member} on the object repo() returns`,
+    meta: { capability, driver: driverName },
+  });
+
+/**
+ * The store answered with a row the plan excludes. Refused, never filtered out: a driver that
+ * ignores a tenant predicate also ignores it on writes, and a quiet filter would hide that.
+ */
+export const driverRowOutOfScope = (
+  driverName: string,
+  entityName: string,
+  operation: string,
+  column: string,
+): DriverError =>
+  new DriverError({
+    code: 'X_DRIVER_ROW_OUT_OF_SCOPE',
+    cause: `driver ${renderCauseValue(driverName)} answered ${entityName}.${operation}() with a row whose ${column} the plan excludes — its select() did not apply plan.where`,
+    fix: "selectRows(entity, rows, read)   # return this from the store's select(): it applies every plan.where predicate in process (@ultimat3/entity/adapter); a native store applies each one itself",
+    meta: { column, driver: driverName, entity: entityName, operation },
+  });
+
+/**
+ * The refusal a store raises for a duplicate key: `X_DB_UNIQUE_VIOLATION`, the code Postgres'
+ * `23505` becomes, so a caller catching it reads one code whatever stores the row. No SQLSTATE
+ * is invented: `sqlState()` answers `undefined`, because no server said anything.
+ */
+export const entityUniqueViolation = (entity: EntityCore, constraint: string): DbError =>
+  new DbError({
+    code: 'X_DB_UNIQUE_VIOLATION',
+    cause: `a row written into ${entity.$table} repeats the key of constraint ${renderCauseValue(constraint)}`,
+    fix: `upsertAll(rows, { onConflict: [...] }) over the columns ${constraint} covers — or catch X_DB_UNIQUE_VIOLATION and answer 409, which is what a raced signup is`,
+    meta: { constraint },
+  });