@ultimat3/entity 23.0.0 → 25.0.0

package/src/batch.ts

@@ -6,11 +6,11 @@
 // 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 type { Page } from '@ultimat3/core';
 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';
 
 /**

package/src/bulk-write.ts

@@ -11,6 +11,7 @@ import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { EntityError, invariantViolated } from './errors';
 import { columnsOf } from './pg-row';
 import type { RowPatch } from './types';
+import { uniqueConstraints } from './unique-constraints';
 
 /**
  * Postgres binds at most 65535 parameters in one statement and a multi-row insert spends
@@ -134,22 +135,12 @@ const crossTenantUpsert = (
   });
 
 /**
- * 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.
+ * Every conflict target Postgres could infer an index for: the primary key, and every non-partial
+ * unique the entity declares by either spelling (`unique-constraints.ts`).
  */
 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),
+  ...uniqueConstraints(entity).map((unique) => unique.columns),
 ];
 
 const sameColumns = (left: readonly string[], right: readonly string[]): boolean =>

package/src/column.ts

@@ -240,8 +240,43 @@ export const makeColumn = <T, Optional extends boolean>(
  * the derived name is checked, because that runs once per column at `entity()` rather than on
  * every statement.
  */
+const isPhysicalName = (name: string): boolean =>
+  /^[a-z_][a-z0-9_$]*$/.test(name) && name.length <= 63;
+
+/** The nearest legal spelling of a name, so the fix hands back a value and never a placeholder. */
+const physicalSpelling = (name: string): string => {
+  const snake = name
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9_$]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+  return (/^[a-z_]/.test(snake) ? snake : `t_${snake}`).slice(0, 63);
+};
+
+/** A name as a TypeScript literal that parses whatever it holds — it is pasted into source. */
+const asSource = (name: string): string =>
+  /^[\w-]+$/.test(name) ? `'${name}'` : JSON.stringify(name);
+
+/**
+ * The TABLE's physical name — `init.table`, or the entity name when none is declared. The same
+ * rule as a column's, and its own refusal: it used to go through `assertColumnName`, which called
+ * a table "not a physical column name" and handed back `.column('created_at')`, an edit to a
+ * column that was never the problem. The repair is at `entity(name, { table })`, and the entity
+ * NAME stays what it was — cache tags and policies key on it.
+ */
+export const assertTableName = (entityName: string, table: string): string => {
+  if (!isPhysicalName(table)) {
+    refuseColumn(
+      'table-name',
+      `"${table}" is not a physical table name: lower-case letters, digits and underscores, at most 63 of them`,
+      `entity(${asSource(entityName)}, { table: '${physicalSpelling(table)}', columns })   # table is the physical name; the entity name is unchanged`,
+    );
+  }
+  return table;
+};
+
 export const assertColumnName = (name: string): string => {
-  if (!/^[a-z_][a-z0-9_$]*$/.test(name) || name.length > 63) {
+  if (!isPhysicalName(name)) {
     refuseColumn(
       'column-name',
       `"${name}" is not a physical column name: lower-case letters, digits and underscores, at most 63 of them`,

package/src/columns-data.ts

@@ -58,6 +58,25 @@ const canonicalDigits = (digits: string): string => {
   return negative && whole !== '0' ? `-${whole}` : whole;
 };
 
+const INT8_MIN = -(2n ** 63n);
+const INT8_MAX = 2n ** 63n - 1n;
+
+/**
+ * Whole digits inside `int8`, in Postgres's spelling. Memory stored a 40-digit value the server
+ * answers `22003 — bigint out of range` for, so a row every app test wrote was one production
+ * refuses. The digits are never echoed: a column message reaches the log line.
+ */
+const int8 = (digits: string): string => {
+  const value = BigInt(digits);
+  return value >= INT8_MIN && value <= INT8_MAX
+    ? canonicalDigits(digits)
+    : refuseColumn(
+        'bigint',
+        'the value is past the int8 range (-2^63 to 2^63 - 1), which Postgres answers 22003 for',
+        'declare the column decimal({ precision: 40, scale: 0 }) — a numeric holds whole numbers past int8 — and run x db gen "widen the bigint to numeric"',
+      );
+};
+
 /**
  * An ACCEPTED decimal in Postgres's spelling: leading zeros stripped, `-0` and `-0.00` unsigned,
  * and a short fraction padded to the column's scale (`numeric(8, 2)` answers `7.50` for `7.5`).
@@ -86,7 +105,7 @@ const canonicalDecimal = (text: string, scale: number | undefined): string => {
  */
 export const bigint = (): Column<string> =>
   column<string>('bigint', (value) => {
-    if (typeof value === 'bigint') return value.toString();
+    if (typeof value === 'bigint') return int8(value.toString());
     if (typeof value === 'number') {
       return Number.isSafeInteger(value)
         ? String(value)
@@ -97,7 +116,7 @@ export const bigint = (): Column<string> =>
           );
     }
     return typeof value === 'string' && DIGITS.test(value)
-      ? canonicalDigits(value)
+      ? int8(value)
       : refuseColumn(
           'bigint',
           `expected whole digits, ${got(value)}`,
@@ -167,7 +186,9 @@ export const decimal = (options: DecimalOptions = {}): Column<string> => {
           `Number(value).toFixed(${scale}) at the call site decides the rounding, or widen the column to decimal({ precision: ${(precision ?? fraction) + fraction - scale}, scale: ${fraction} }) and run x db gen "widen the numeric"`,
         );
       }
-      const whole = (digits[0] ?? '').replace(/^0+(?=\d)/, '').length;
+      // A whole part of `0` is NO digit: `numeric(2, 2)` holds `0.50`, and counting the zero
+      // refused every legal value of a `numeric(p, p)` column.
+      const whole = (digits[0] ?? '').replace(/^0+/, '').length;
       if (precision !== undefined && whole > precision - (scale ?? 0)) {
         return refuseColumn(
           'numeric',

package/src/columns.ts

@@ -2,7 +2,7 @@
 // locale and a time zone — the alternatives (float money, naive timestamps, a single implied
 // currency) are the bugs this file exists to make unreachable.
 
-import { uuid as uuidV7 } from '@ultimat3/core';
+import { uuidV7 } from '@ultimat3/core';
 import {
   CURRENCY_CODE_PATTERN,
   isCurrencyCode,
@@ -109,6 +109,9 @@ const parseInstant = (value: unknown): Date => {
 export const timestamp = (): TimestampColumn =>
   makeTimestamp<false>({ ...BARE, kind: 'timestamptz' }, parseInstant, false);
 
+/** The column's CHECK (`~ '^https?://'`), before the scheme is lower-cased. */
+const STORED_HTTP = /^https?:\/\//i;
+
 /**
  * An absolute http(s) URL, validated on write rather than on render: a bad URL stored once is
  * served to every reader, and `<img src>` fails silently in the browser.
@@ -126,7 +129,11 @@ export const url = (): Column<string> =>
           // The scheme is stored in its canonical LOWER case: the CHECK is `~ '^https?://'`, so
           // `HTTPS://a.b` was stored by memory and refused by Postgres. Only the scheme is
           // rewritten — the rest of the URL is the caller's, byte for byte.
-          if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
+          // And the STORED text must itself open with it: WHATWG strips leading whitespace and
+          // embedded tabs and mends `https:/a.b` before `protocol` is read, while the column keeps
+          // the caller's bytes — which the CHECK then refused as a raw 23514.
+          const http = parsed.protocol === 'http:' || parsed.protocol === 'https:';
+          if (http && STORED_HTTP.test(value)) {
             return value.replace(/^https?(?=:)/i, (scheme) => scheme.toLowerCase());
           }
         } catch {

package/src/containment.ts

@@ -28,6 +28,15 @@ const sameElement = (left: unknown, right: unknown): boolean => {
   return left === right;
 };
 
+/**
+ * Two elements of a SQL ARRAY, equal — and a NULL element is equal to nothing, itself included.
+ * `array['a', null] @> array[null]` and `array[null] && array[null]` are both FALSE in Postgres:
+ * the element comparison is `=`, and `NULL = NULL` is unknown. Arrays only — a `jsonb` `null` is a
+ * VALUE and equals itself, which is why `jsonContains` keeps `sameElement`.
+ */
+const sameArrayElement = (left: unknown, right: unknown): boolean =>
+  !isNull(left) && !isNull(right) && sameElement(left, right);
+
 /**
  * `left @> right` for `jsonb`, to the letter of Postgres' definition — each clause below measured
  * on Postgres 16 rather than read off a summary, because three of them are easy to state wrongly:
@@ -67,7 +76,7 @@ const contains = (left: unknown, right: unknown, top: boolean): boolean => {
  * by every array, which is what Postgres answers.
  */
 export const arrayContains = (left: readonly unknown[], right: readonly unknown[]): boolean =>
-  right.every((item) => left.some((candidate) => sameElement(candidate, item)));
+  right.every((item) => left.some((candidate) => sameArrayElement(candidate, item)));
 
 /**
  * `left && right`: they share at least one element. Arrays only — `jsonb` has no `&&` — and the
@@ -75,7 +84,7 @@ export const arrayContains = (left: readonly unknown[], right: readonly unknown[
  * contained by everything.
  */
 export const arrayOverlaps = (left: readonly unknown[], right: readonly unknown[]): boolean =>
-  right.some((item) => left.some((candidate) => sameElement(candidate, item)));
+  right.some((item) => left.some((candidate) => sameArrayElement(candidate, item)));
 
 /**
  * The memory half of `col ? key`. The SQL side emits the OPERATOR, schema-qualified —
@@ -88,6 +97,10 @@ export const arrayOverlaps = (left: readonly unknown[], right: readonly unknown[
  * Three shapes, all of them Postgres': a top-level key of an object, a string ELEMENT of an array,
  * and a string value equal to the key. A number never matches — `'[1]'::jsonb ? '1'` is false
  * there, and a `String(item) === key` here would have made it true.
+ *
+ * The KEY is a string or the test matches no row, in both drivers: `pg-sql.ts` compiles any other
+ * operand to no rows rather than binding `String(key)`, which found a key named `"null"` for a
+ * `null` operand and `"1"` for the number `1`.
  */
 export const jsonHasKey = (value: unknown, key: unknown): boolean => {
   if (typeof key !== 'string' || isNull(value)) return false;

package/src/database.ts

@@ -2,11 +2,11 @@
 // writes a repository class per entity, and nobody can reach a table that is not in the set.
 
 import type { EntityCore } from './entity';
-import { memoryRepo } from './memory-repo';
+import { memoryRepo, memoryTransactor } from './memory-repo';
 import type { RelatedTables } from './preload';
 import type { Table } from './query';
 import { tableFor } from './query';
-import type { Repo } from './repo';
+import type { Repo, Transactor } from './repo';
 import { observedRepo } from './row-observer';
 
 export type EntitySet = Readonly<Record<string, EntityCore>>;
@@ -25,6 +25,12 @@ export interface Driver {
    * `reset()` eventually would. A harness therefore asks and does not assume: `driver.reset?.()`.
    */
   reset?(): void;
+  /**
+   * The transactor that undoes THIS driver's writes. Required: a seed dry run writes for real and
+   * rolls back through it, and a driver that could not undo would be found out at run time. A
+   * driver that wraps another delegates — `transactor: () => inner.transactor()`.
+   */
+  transactor(): Transactor;
 }
 
 export interface DatabaseOptions {
@@ -54,6 +60,7 @@ export const memoryDriver = (): Driver => {
     reset() {
       for (const reset of resets) reset();
     },
+    transactor: () => memoryTransactor(),
   };
 };
 

package/src/describe.ts

@@ -26,6 +26,8 @@ export interface DescribeInput<Row> {
   readonly tenantColumn: string | null;
   /** The generated `tsvector`, when any column is `.searchable()`. */
   readonly search?: SearchVector | null;
+  /** `entity({ appendOnly: true })` — projected only when true. */
+  readonly appendOnly?: boolean;
 }
 
 /**
@@ -234,5 +236,8 @@ export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescriptio
     cacheTag: input.cacheTag,
     softDelete: input.softDelete,
     orgScoped: input.tenantColumn !== null,
+    // `true` or absent, never `false`: `x verify`'s source drift hashes this projection as JSON,
+    // and an entity that never said `appendOnly` must hash exactly what it hashed before.
+    ...(input.appendOnly === true ? { appendOnly: true as const } : {}),
   };
 };

package/src/entity-error.ts

@@ -1,12 +1,19 @@
 // The entity layer's code registry, its error class, and the two refusals the declaration path
 // raises — split from `errors.ts` so a module the BROWSER loads (the record key, the projection,
-// the registry) can raise one without importing `@ultimat3/db`, which `errors.ts` needs for
-// `dbDrift`'s shell-inert fix line.
+// the registry) can raise one without importing `@ultimat3/db`.
 import type { ErrorRetry } from '@ultimat3/core';
-import { registerErrorCodes, registerErrorRetry, UltimateError } from '@ultimat3/core';
+import {
+  isFixShellSafe,
+  registerErrorCodes,
+  registerErrorRetry,
+  UltimateError,
+} from '@ultimat3/core';
 
-/** Codes this package declares and owns. */
-export const ENTITY_OWNED_ERROR_CODES = [
+/**
+ * Every code this package throws, and it owns each one. `X_DB_DRIFT` is `@ultimat3/db`'s and is
+ * raised there — drift is a fact about migrations.
+ */
+export const ENTITY_ERROR_CODES = [
   'X_ENTITY_DUPLICATE',
   'X_INVARIANT_VIOLATED',
   'X_TENANCY_UNSCOPED',
@@ -31,25 +38,12 @@ export const ENTITY_OWNED_ERROR_CODES = [
   'X_RECORD_KEY_MISSING',
   'X_ENTITY_SEALED_PREDICATE',
   'X_ENTITY_SEALED_IN_VIEW',
+  'X_ENTITY_APPEND_ONLY',
 ] as const;
 
-/**
- * `X_DB_DRIFT` is `@ultimat3/db`'s — drift is a fact about migrations, and this package imports db
- * rather than the other way round. `dbDrift()` below throws it; nothing here titles it, because a
- * second copy of the title is what lets the two packages disagree about what the code means.
- */
-export const ENTITY_BORROWED_ERROR_CODES = ['X_DB_DRIFT'] as const;
-
-/** Every code entity can throw: the ones it owns plus the one it borrows. */
-export const ENTITY_ERROR_CODES = [
-  ...ENTITY_OWNED_ERROR_CODES,
-  ...ENTITY_BORROWED_ERROR_CODES,
-] as const;
-
-export type EntityOwnedErrorCode = (typeof ENTITY_OWNED_ERROR_CODES)[number];
 export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
 
-export const ENTITY_ERROR_TITLES: Readonly<Record<EntityOwnedErrorCode, string>> = {
+export const ENTITY_ERROR_TITLES: Readonly<Record<EntityErrorCode, string>> = {
   X_ENTITY_DUPLICATE: 'two entities claim the same name',
   X_INVARIANT_VIOLATED: 'a domain invariant rejected this row',
   X_TENANCY_UNSCOPED: 'a tenant-scoped query has no org predicate',
@@ -77,6 +71,7 @@ export const ENTITY_ERROR_TITLES: Readonly<Record<EntityOwnedErrorCode, string>>
   X_ENTITY_SEALED_PREDICATE:
     'a sealed column is read by a predicate, an order or a rule the database evaluates',
   X_ENTITY_SEALED_IN_VIEW: 'a sealed column is named in a view',
+  X_ENTITY_APPEND_ONLY: 'an append-only entity was asked to rewrite or remove a row',
 };
 
 // Registered at module load, unconditionally, in one call. Without this the registry humanises the
@@ -87,8 +82,8 @@ registerErrorCodes(
 );
 
 /**
- * How the codes here that are worth classifying are retried. Only the two sealed-column refusals:
- * both are the app's own declaration or call, so attempt five answers what attempt one did — and
+ * How the codes here that are worth classifying are retried. The two sealed-column refusals and
+ * the append-only refusal: each is the app's own declaration or call, so attempt five answers what attempt one did — and
  * left unclassified, `classifyThrown` reads them as undecided and a job spends its whole retry
  * policy re-proving it. Listed although `terminal` is the default, for the reason core's own table
  * gives for `X_NOT_IMPLEMENTED`. The rest of this package's codes are unclassified, as they were.
@@ -96,7 +91,8 @@ registerErrorCodes(
 export const ENTITY_ERROR_RETRY = {
   X_ENTITY_SEALED_PREDICATE: 'terminal',
   X_ENTITY_SEALED_IN_VIEW: 'terminal',
-} as const satisfies Readonly<Partial<Record<EntityOwnedErrorCode, ErrorRetry>>>;
+  X_ENTITY_APPEND_ONLY: 'terminal',
+} as const satisfies Readonly<Partial<Record<EntityErrorCode, ErrorRetry>>>;
 
 registerErrorRetry(ENTITY_ERROR_RETRY);
 
@@ -120,6 +116,18 @@ export class EntityError extends UltimateError {
   }
 }
 
+/**
+ * The one command a BOUND refusal hands back — a page size, a preload ceiling, a judged write: it
+ * runs, and it names the real entity. The edit itself is code on a chain whose variable no error
+ * can know (`db.members`, not `preload_test_members`), so it is spelled in the `cause` as the call
+ * to write, never in the `fix` as though the entity name were that variable. A name a shell would
+ * read is not spliced.
+ */
+export const describeCommand = (entityName: string): string =>
+  isFixShellSafe(entityName)
+    ? `x entities describe ${entityName} --json`
+    : 'x entities list --json';
+
 /**
  * The entity name is a VALUE, never a literal — `entity.$name`, `table`, the `name` `entity()` was
  * given. A literal is an entity that does not exist, and this fix then hands the reader

package/src/entity.ts

@@ -5,13 +5,15 @@
 
 import type { IndexMethod } from '@ultimat3/db';
 import { describeValue, type Schema } from '@ultimat3/schema';
+import { assertAppendOnlyColumns } from './append-only';
 import { entityNow } from './clock';
-import { assertColumnName, bindColumn, columnName, moneyColumns } from './column';
+import { assertTableName, bindColumn, columnName, moneyColumns } from './column';
 import { newId } from './columns';
 import { describeEntity, describeReferences } from './describe';
 import { invariantViolated } from './errors';
-import type { Expr, InvariantColumns, Resolve } from './expr';
+import type { InvariantColumns, Resolve } from './expr';
 import { invariantColumns } from './expr';
+import type { IndexInit } from './index-init';
 import { indexName } from './index-name';
 import type { Invariant, InvariantDef } from './invariants';
 import { assertInvariants, bindInvariant } from './invariants';
@@ -32,29 +34,6 @@ import { viewFor } from './view';
 /** Presence of this column is what makes an entity soft-deletable — not a flag. */
 export const SOFT_DELETE_COLUMN = 'deletedAt';
 
-export interface IndexInit<C extends ColumnMap> {
-  readonly on: readonly (keyof C & string)[];
-  readonly order?: 'asc' | 'desc';
-  readonly unique?: boolean;
-  /** Partial index predicate, written in the same language as an invariant. */
-  readonly where?: (columns: InvariantColumns<C>) => Expr;
-  /**
-   * The access method. Omitted is `btree`, which is Postgres' own default and what every index
-   * declared before this existed is — so an entity that names none emits the statement it always
-   * emitted and nothing regenerates.
-   *
-   * `'gin'` is the one with a caller, and it is the whole point of the containment operators:
-   * measured on Postgres 16 over 20,000 rows, `tags @> …`, `tags <@ …`, `tags && …` and
-   * `data @> …` are each a Bitmap Index Scan with one and a Seq Scan without. The set is
-   * `@ultimat3/db`'s `INDEX_METHODS`, imported rather than restated — one declaration of one fact.
-   *
-   * Two Postgres rules ride with it and both are refused HERE, where the author is, rather than at
-   * `x db gen` or inside `ROLE=migrate` as the server's own syntax error: a GIN index cannot be
-   * unique and cannot order its keys.
-   */
-  readonly using?: IndexMethod;
-}
-
 export interface EntityInit<C extends ColumnMap> {
   readonly columns: C;
   /**
@@ -94,6 +73,12 @@ export interface EntityInit<C extends ColumnMap> {
    * and disk is a decision. Read off `recordProjection(entity).persist` by realtime's persister.
    */
   readonly persist?: boolean;
+  /**
+   * Rows are written once and never changed or removed — a ledger, an audit trail, an event log.
+   * The repository refuses every rewrite (`append-only.ts`) and `x db gen` emits the trigger that
+   * refuses the same in raw SQL. A soft-delete, `onUpdateNow()` or state-machine column is refused.
+   */
+  readonly appendOnly?: boolean;
 }
 
 /**
@@ -112,6 +97,8 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
   /** `entity:<name>`. `@ultimat3/cache` invalidates by this string. */
   readonly $cacheTag: string;
   readonly $softDelete: boolean;
+  /** `entity({ appendOnly: true })`: update and delete are refused, here and by the table. */
+  readonly $appendOnly: boolean;
   /** Property key of the tenant column, or `null`. Presence is what turns tenancy on. */
   readonly $tenantColumn: string | null;
   /**
@@ -186,10 +173,12 @@ export const entity = <const C extends ColumnMap>(
   // Both branches. The declared table was checked and the fallback — which is every entity that
   // does not rename its table — was not, so an entity NAME closed the identifier in the same way a
   // column name could: `entity('t" (x int); drop table u; --')` emitted that `drop table` verbatim.
-  const table = assertColumnName(init.table ?? name);
+  const table = assertTableName(name, init.table ?? name);
   const cacheTag = `entity:${name}`;
   const softDelete = Object.hasOwn(init.columns, SOFT_DELETE_COLUMN);
   const tenantColumn = resolveTenantColumn(name, init.columns, init.tenant);
+  const appendOnly = init.appendOnly === true;
+  if (appendOnly) assertAppendOnlyColumns(name, entries, SOFT_DELETE_COLUMN);
 
   const searchSources: readonly SearchSource[] = entries.flatMap(([property, column]) => {
     const weight = column.$meta.searchable;
@@ -242,10 +231,7 @@ export const entity = <const C extends ColumnMap>(
     return part === 'minor' ? parts.minor : parts.currency;
   };
 
-  const columnsExpr = invariantColumns<C>(
-    name,
-    entries.map(([property]) => property),
-  );
+  const columnsExpr = invariantColumns<C>(name, init.columns);
   // Through the one resolver, so a soft-delete column the table spells differently is still the
   // column every partial index excludes rows by.
   const partialWhere = softDelete ? `${resolve([SOFT_DELETE_COLUMN])} is null` : undefined;
@@ -383,6 +369,7 @@ export const entity = <const C extends ColumnMap>(
       softDelete,
       tenantColumn,
       search,
+      appendOnly,
     });
   const references = (): readonly ReferenceDescription[] => describeReferences(name, entries);
 
@@ -463,6 +450,7 @@ export const entity = <const C extends ColumnMap>(
     $tags: tags,
     $cacheTag: cacheTag,
     $softDelete: softDelete,
+    $appendOnly: appendOnly,
     $tenantColumn: tenantColumn,
     $search: search,
     $schema: schema,

package/src/errors.ts

@@ -1,16 +1,14 @@
-// The entity layer's stable error codes. Each factory produces the exact command
-// that fixes the situation — `X_DB_DRIFT` is the flagship: it names the table, the
-// column and the generator invocation. The code registry, the class, `invariantViolated` and
-// `entityDuplicate` live in `entity-error.ts`, which imports no `@ultimat3/db`; re-exported here.
-import { shellInertIdentifier } from '@ultimat3/db';
+// The entity layer's stable error codes. Each factory produces the exact command that fixes the
+// situation. The code registry, the class, `invariantViolated` and `entityDuplicate` live in
+// `entity-error.ts`, which imports no `@ultimat3/db`; re-exported here. `X_DB_DRIFT` is not
+// raised here at all: drift is `@ultimat3/db`'s, factory included.
 import { EntityError } from './entity-error';
 
-export type { EntityErrorCode, EntityOwnedErrorCode } from './entity-error';
+export type { EntityErrorCode } from './entity-error';
 export {
-  ENTITY_BORROWED_ERROR_CODES,
+  describeCommand,
   ENTITY_ERROR_CODES,
   ENTITY_ERROR_TITLES,
-  ENTITY_OWNED_ERROR_CODES,
   EntityError,
   entityDuplicate,
   invariantViolated,
@@ -72,7 +70,7 @@ export const tenancyUnscoped = (
         : `${entityName}.${operation}() was checked against a plan with no org predicate, though the acting actor's tenant is ${renderValue(actorOrg)} — a plan is verified here, never rewritten, so the tenant had to be on it already`,
     fix:
       actorOrg === undefined
-        ? `run it inside runWithContext(createContext({ actor: userActor({ id, orgId }) }), fn) — the actor's org scopes the plan — or name the tenant: ${entityName}.${operation}({ orgId }), which orgScoped(plan, orgId) is the plan-level form of`
+        ? `run it inside runWithContext(ctxOf({ actor: userActor({ id, orgId }) }), fn) — the actor's org scopes the plan — or name the tenant: ${entityName}.${operation}({ orgId }), which orgScoped(plan, orgId) is the plan-level form of`
         : `build the plan with scopedPlan('${entityName}', tenantColumn, '${operation}', plan) — it applies the actor's tenant — or add the predicate first: orgScoped(plan, ${asLiteral(actorOrg, "'<org>'")})`,
   });
 
@@ -161,24 +159,22 @@ export const crossTenantDenied = (init: {
   new EntityError({
     code: 'X_TENANCY_CROSS_DENIED',
     cause: `crossTenant(${JSON.stringify(init.reason)}) was entered by ${init.actor}, which does not carry the ${JSON.stringify(init.scope)} scope`,
-    fix: `grant the capability where the actor is minted — serviceActor({ id: 'reconciler', scopes: ['${init.scope}'] }) — and run the sweep inside runWithContext(createContext({ actor }), fn); an ordinary request scopes to its own tenant instead and needs no crossTenant()`,
+    fix: `grant the capability where the actor is minted — serviceActor({ id: 'reconciler', scopes: ['${init.scope}'] }) — and run the sweep inside runWithContext(ctxOf({ actor }), fn); an ordinary request scopes to its own tenant instead and needs no crossTenant()`,
   });
 
 /**
- * A repository built with an explicit `client`, used while a transaction is open.
+ * A repository built with an explicit `client`, used inside a transaction that was opened on some
+ * OTHER client.
  *
- * Refused rather than resolved, because neither answer is available. `withTransaction` reserves
- * ONE connection and runs `BEGIN` on it — the ambient pool's, or a reservation of its own
- * `client:` option — while a repository pinned through `postgresDriver({ client })` sends every
- * statement straight to that client, which takes a different connection out of the pool. So the
- * write commits immediately and survives the rollback, and the read cannot see the rows the
- * transaction has already written; both are silent. Joining the transaction instead would be the
- * worse half of the same guess: a `DbTx` does not name the client it was opened on, so "is this
- * even the same database" is not a question this layer can ask, and on a sharded app the answer
- * is no.
+ * Refused rather than resolved. `withTransaction` reserves one connection and runs `BEGIN` on it,
+ * while a pinned repository sends to its own client — another connection, and on a sharded app
+ * another database — so the write would commit immediately and survive the rollback, and the read
+ * would miss rows the transaction has written; both silent. A transaction opened ON the pinned
+ * client (`tx.origin`) is the same database and the same reservation, and the repository joins it:
+ * that case never reaches here.
  *
- * The fix names the ambient seam because that is the one path a repository joins a transaction
- * through: `db()` resolves `currentTx()` first, which is exactly what a pinned client skips.
+ * The fix names the ambient seam because that is the path a repository joins the AMBIENT
+ * transaction through: `db()` resolves `currentTx()` first, which is what a pinned client skips.
  */
 export const repoClientPinned = (entityName: string): EntityError =>
   new EntityError({
@@ -187,28 +183,6 @@ export const repoClientPinned = (entityName: string): EntityError =>
     fix: `setDbClient(client) at boot and build the repository with no client: — postgresDriver() then resolves the open transaction through db() — or run this call outside withTransaction()`,
   });
 
-/**
- * The contract's pinned wording. Mirror of `@ultimat3/db`'s `dbDrift()` (`drift-errors.ts`) —
- * keep in sync; both screen through the same `shellInertIdentifier`, so the two lines are one
- * text on both sides of the tier seam, and `errors.test.ts` asserts it rather than asking.
- *
- * The column is the CATALOG's, so it is data, and `x db gen "add C"` puts it inside SHELL DOUBLE
- * QUOTES where `$(…)` and a backtick substitute before `x` is reached at all. The argument is a
- * migration DESCRIPTION, not an identifier, so no quoted form makes a hostile name safe to pass —
- * a refused one is left OUT of the command rather than escaped into it, and read off `cause`.
- */
-export const dbDrift = (tableName: string, columnName: string): EntityError =>
-  new EntityError({
-    code: 'X_DB_DRIFT',
-    cause: `table "${tableName}" has column "${columnName}" not present in any migration`,
-    fix:
-      shellInertIdentifier(columnName) === null
-        ? 'x db gen "add the column named in this error"   # its name carries a backtick, a ' +
-          'dollar sign, a quote, a backslash or whitespace, so it is in the cause and not in ' +
-          'this command'
-        : `x db gen "add ${columnName}"`,
-  });
-
 export const notFound = (entityName: string, id: string): EntityError =>
   new EntityError({
     code: 'X_NOT_FOUND',