@ultimat3/entity 29.3.2 → 30.0.0

package/src/batch-read.ts

@@ -5,6 +5,7 @@
 
 import type { DbClient } from '@ultimat3/db';
 import type { EntityCore } from './entity';
+import { canonicalDecimal, canonicalInteger } from './numeric-compare';
 import { decodeRow, type PhysicalRow } from './pg-row';
 import { type ReadShape, selectStatement } from './pg-sql';
 import type { QueryPlan } from './tenancy';
@@ -35,11 +36,18 @@ export type Answer = { readonly row: unknown } | { readonly error: unknown };
  * The string both sides of a batch are filed under — the requested id, and the key of a row that
  * came back. Postgres compares a `uuid` as a value and prints it lower-cased, so an id handed in
  * upper case matches the row *there* and would miss it here, which would make an answer depend on
- * whether some other lookup shared the microtask. Every other kind compares by its bytes, and
- * lower-casing a text key would merge two rows Postgres keeps apart.
+ * whether some other lookup shared the microtask. An integer or `numeric` is compared by value too:
+ * `'007'` matched the row and missed its answer here, filed under `'7'`. One the column could not
+ * hold stays as written, so the statement still carries it and Postgres answers its own refusal.
+ * Every other kind compares by its bytes, and lower-casing a text key would merge two rows
+ * Postgres keeps apart.
  */
-export const keyOf = (kind: string, value: unknown): string =>
-  kind === 'uuid' ? String(value).toLowerCase() : String(value);
+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);
+  return String(value);
+};
 
 /** A scope value has to be comparable as a string, or two scopes cannot be told apart. */
 const scopeValue = (value: unknown): string | undefined => {

package/src/bulk-write-send.ts

@@ -0,0 +1,49 @@
+// Single responsibility: sending a batch's chunks so the batch is one write. `bulk-write.ts` decides
+// what the chunks are; this decides what holds them together, split from `pg-driver.ts`, which
+// resolves the connection and hands it over.
+
+import { type DbClient, withTransaction } from '@ultimat3/db';
+import { insertChunks } from './bulk-write';
+import type { EntityCore } from './entity';
+import { hasJsOnlyInvariant } from './invariants';
+import { decodeRow, type PhysicalRow } from './pg-row';
+import { type InsertShape, insertStatement } from './pg-write-sql';
+
+/**
+ * One chunk is one autocommit statement, atomic by itself, with no `BEGIN`. Several are one
+ * transaction — a SAVEPOINT inside an open one — or a batch failing in its last chunk would leave
+ * the earlier ones stored, and a job retrying it would meet its own partial write. The memory
+ * driver leaves nothing, and the two mean one thing.
+ *
+ * `direct` is resolved by the CALLER first, so a pinned repository inside a transaction opened on
+ * another client is refused (`X_REPO_CLIENT_PINNED`) before anything opens, and `pinned` is where
+ * the transaction opens when the repository has one, as in `judgedWrite`.
+ *
+ * An updating upsert with an app-only rule takes a transaction at any width: what a collision
+ * stored is the incoming row merged into the stored one, and only `returning *` shows that row. The
+ * memory driver judges the same merge in `write`, so without this the rule held only there.
+ */
+export const writeChunks = async <Row>(
+  entity: EntityCore<Row>,
+  bound: readonly ReadonlyMap<string, unknown>[],
+  shape: InsertShape,
+  direct: DbClient,
+  pinned: DbClient | undefined,
+): Promise<readonly Row[]> => {
+  const chunks = insertChunks(bound, shape.columns.length);
+  const judges =
+    shape.conflict !== undefined &&
+    shape.conflict.set.length > 0 &&
+    hasJsOnlyInvariant(entity.$invariants);
+  const send = async (on: DbClient): Promise<readonly Row[]> => {
+    const written: Row[] = [];
+    for (const chunk of chunks) {
+      const stored = await on.query<PhysicalRow>(insertStatement(entity, chunk, shape));
+      for (const row of stored) written.push(decodeRow(entity, row));
+    }
+    if (judges) for (const row of written) entity.$assert(row);
+    return written;
+  };
+  if (chunks.length === 1 && !judges) return send(direct);
+  return withTransaction(send, pinned === undefined ? {} : { client: pinned });
+};

package/src/bulk-write.ts

@@ -9,7 +9,7 @@ import { columnFor } from './column';
 import { valueAt } from './cursor';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { EntityError, invariantViolated } from './errors';
-import { columnsOf } from './pg-row';
+import { allColumns, columnsOf } from './pg-row';
 import type { RowPatch } from './types';
 import { uniqueConstraints } from './unique-constraints';
 
@@ -31,11 +31,14 @@ export interface UpsertPlan {
 const owns = (row: unknown, property: string): boolean =>
   typeof row === 'object' && row !== null && Object.hasOwn(row, property);
 
+/** A value this row writes: present and not `undefined`, the same two tests `bindValues` makes. */
+const writes = (row: unknown, property: string): boolean =>
+  owns(row, property) && (row as Readonly<Record<string, unknown>>)[property] !== undefined;
+
 /**
- * The properties a batch writes: every declared column at least one row names, in declaration
- * order. `Object.hasOwn` decides it, exactly as `bindValues` does — a property present and
- * `undefined` is a value the caller wrote, and dropping it here would insert a column the update
- * set then skipped.
+ * The columns a batch's statement lists: every declared column at least one row names, in
+ * declaration order. A present `undefined` keeps its place here and binds no value, so its cell is
+ * `default`. What a COLLISION overwrites is a narrower question: `upsertPlan` asks `writes`.
  */
 export const namedProperties = <Row>(
   entity: EntityCore<Row>,
@@ -53,6 +56,19 @@ export const insertColumns = <Row>(
     return column === undefined ? [] : columnsOf(property, column);
   });
 
+/**
+ * The column list one statement of this batch carries. Rows naming nothing are all defaults, which
+ * only a column list can spell for several rows at once: no list at all is
+ * `insert into t () values ()`, a syntax error the framework would have written.
+ */
+export const statementColumns = <Row>(
+  entity: EntityCore<Row>,
+  rows: readonly RowPatch<Row>[],
+): readonly string[] => {
+  const named = insertColumns(entity, namedProperties(entity, rows));
+  return named.length > 0 ? named : allColumns(entity);
+};
+
 /**
  * Rows per statement: the bind budget divided by one row's width, never fewer than one. Splitting
  * can only cost round trips; not splitting would fail a write that succeeded one row at a time.
@@ -146,6 +162,27 @@ const uniqueTargets = <Row>(entity: EntityCore<Row>): readonly (readonly string[
 const sameColumns = (left: readonly string[], right: readonly string[]): boolean =>
   left.length === right.length && [...left].sort().join() === [...right].sort().join();
 
+/**
+ * What a batch overwrites on a collision: the columns its rows write, refusing a batch whose rows
+ * disagree. `writes`, not `owns`: a present `undefined` is absent in every write there is, and
+ * overwriting with it would hand the stored row the column's default — the loss `unevenBatch`
+ * refuses. `tableFor` asks this of the CALLER's rows, before `$parse` makes every row name every
+ * column; a repository handed rows directly asks it in `upsertPlan`.
+ */
+export const overwrittenBy = <Row>(
+  entity: EntityCore<Row>,
+  rows: readonly RowPatch<Row>[],
+): readonly string[] => {
+  const properties = Object.keys(entity.$columns).filter((property) =>
+    rows.some((row) => writes(row, property)),
+  );
+  for (const [position, row] of rows.entries()) {
+    const missing = properties.find((property) => !writes(row, property));
+    if (missing !== undefined) throw unevenBatch(entity.$name, position, missing);
+  }
+  return properties;
+};
+
 /**
  * The conflict target, and what a collision overwrites. `'nothing'` overwrites nothing by
  * definition; `'update'` takes every column the batch writes except three closed sets — the
@@ -169,13 +206,14 @@ const sameColumns = (left: readonly string[], right: readonly string[]): boolean
  * carry the tenant column under `'update'` (another tenant's row, silently rewritten), a batch
  * whose rows name different columns under `'update'` (`excluded.<col>` is the column's default for
  * a row that omitted it, so "leave it alone" is not what happens), and a target that leaves
- * nothing to write.
+ * nothing to write. `overwrites` is `UpsertArgs.overwrites`: named, it replaces what the rows say.
  */
 export const upsertPlan = <Row>(
   entity: EntityCore<Row>,
   rows: readonly RowPatch<Row>[],
   onConflict: readonly string[],
   onMatch: 'update' | 'nothing',
+  overwrites?: readonly string[],
 ): UpsertPlan => {
   if (onConflict.length === 0) throw noConflictTarget(entity.$name);
   for (const property of onConflict) {
@@ -201,11 +239,10 @@ export const upsertPlan = <Row>(
   if (tenant !== null && !onConflict.includes(tenant)) {
     throw crossTenantUpsert(entity.$name, tenant, onConflict);
   }
-  const properties = namedProperties(entity, rows);
-  for (const [position, row] of rows.entries()) {
-    const missing = properties.find((property) => !owns(row, property));
-    if (missing !== undefined) throw unevenBatch(entity.$name, position, missing);
-  }
+  const properties =
+    overwrites === undefined
+      ? overwrittenBy(entity, rows)
+      : Object.keys(entity.$columns).filter((property) => overwrites.includes(property));
   const spared = new Set([
     ...onConflict,
     ...entity.$primaryKey,

package/src/column.ts

@@ -82,11 +82,16 @@ export const BARE: Omit<ColumnMeta, 'kind'> = {
 };
 
 export interface Binding {
+  /** The entity's NAME, what a relation and the registry key on. */
   readonly table: string;
+  /** The physical table, what a foreign key names. Equal to `table` unless `{ table }` was said. */
+  readonly physicalTable: string;
   /** camelCase key on the row. */
   readonly property: string;
   /** snake_case physical column name. */
   readonly name: string;
+  /** The physical tenant column of the entity that owns this column, `null` when it has none. */
+  readonly tenant: string | null;
 }
 
 const bindings = new WeakMap<AnyColumn, Binding>();
@@ -96,7 +101,13 @@ const bindings = new WeakMap<AnyColumn, Binding>();
  * one between two entities would give it two physical names and silently mis-name a foreign
  * key, so a second binding is a declaration-time error.
  */
-export const bindColumn = (column: AnyColumn, table: string, property: string): Binding => {
+export const bindColumn = (
+  column: AnyColumn,
+  table: string,
+  property: string,
+  tenant: string | null = null,
+  physicalTable: string = table,
+): Binding => {
   const existing = bindings.get(column);
   if (existing !== undefined && existing.table !== table) {
     throw invariantViolated(
@@ -109,8 +120,10 @@ export const bindColumn = (column: AnyColumn, table: string, property: string):
   // The DERIVED name too, not only a declared one: `snake(property)` lower-cases and nothing else.
   const binding: Binding = {
     table,
+    physicalTable,
     property,
     name: assertColumnName(columnName(property, column.$meta)),
+    tenant,
   };
   bindings.set(column, binding);
   return binding;
@@ -205,17 +218,29 @@ export const makeColumn = <T, Optional extends boolean>(
 
   tenant: () => makeColumn<T, Optional>({ ...meta, tenant: true, index: true }, parse, optional),
 
-  references: (target, options = {}) =>
-    makeColumn<T, Optional>(
+  references: (target, options = {}) => {
+    // The rule `crossTenant()` already sets: an escape with no argument reads like a forgotten key,
+    // and the next reader cannot tell a considered edge from an accident.
+    if (options.crossTenant !== undefined && options.crossTenant.trim() === '') {
+      refuseColumn(
+        'references',
+        'crossTenant was given a blank reason, so the same-tenant key it lifts carries no argument',
+        "uuid().references(() => target.id, { crossTenant: 'why this edge spans tenants' })   # or drop the option and keep the same-tenant key",
+      );
+    }
+    return makeColumn<T, Optional>(
       {
         ...meta,
         references: target,
         index: true,
         ...(options.onDelete === undefined ? {} : { onDelete: options.onDelete }),
+        ...(options.crossTenant === undefined ? {} : { crossTenant: options.crossTenant }),
+        ...(options.countedIn === undefined ? {} : { countedIn: options.countedIn }),
       },
       parse,
       optional,
-    ),
+    );
+  },
 
   default: (value) => makeColumn<T, true>({ ...meta, default: literal(value) }, parse, true),
 

package/src/counter.ts

@@ -0,0 +1,109 @@
+// Single responsibility: what `references(() => posts.id, { countedIn: () => posts.likeCount })`
+// means once both schema modules have evaluated — the parent column resolved, held to being an
+// integer of the entity the key points at, and projected for `@ultimat3/db` (which emits the
+// trigger) and for the memory driver (which mirrors it).
+
+import type { CounterDescriptionLike } from '@ultimat3/db';
+import { bindingOf, columnName } from './column';
+import type { EntityCore } from './entity';
+import { SOFT_DELETE_COLUMN } from './entity';
+import { EntityError } from './errors';
+import { getEntity, registeredEntities, registryGeneration } from './registry';
+import type { AnyColumn } from './types';
+
+/** One resolved counter: both entities, both properties. */
+export interface Counter {
+  readonly parent: EntityCore;
+  /** The counting integer's property on the parent. */
+  readonly column: string;
+  readonly child: EntityCore;
+  /** The child's foreign-key property. */
+  readonly references: string;
+}
+
+const countsInvalid = (entity: string, property: string, reason: string): EntityError =>
+  new EntityError({
+    code: 'X_ENTITY_COUNTS_INVALID',
+    cause: `${entity}.${property} declares countedIn, and ${reason}`,
+    fix: `x db gen "count"   # after ${property}: uuid().references(() => <parent>.id, { countedIn: () => <parent>.<count> }) in entity('${entity}'), where <count> is integer().default(0)`,
+  });
+
+/** The counter one child key declares, resolved and checked. `null` when it declares none. */
+export function counterOf(child: EntityCore, property: string, column: AnyColumn): Counter | null {
+  const target = column.$meta.countedIn;
+  if (target === undefined) return null;
+  const counting = target();
+  const binding = bindingOf(counting);
+  const parent = binding === undefined ? undefined : getEntity(binding.table)?.core;
+  if (binding === undefined || parent === undefined) {
+    throw countsInvalid(child.$name, property, 'its countedIn column belongs to no entity');
+  }
+  if (counting.$meta.kind !== 'integer') {
+    throw countsInvalid(
+      child.$name,
+      property,
+      `${binding.table}.${binding.property} is no integer()`,
+    );
+  }
+  // `NULL + 1` is NULL in the trigger and memory counts from 0: a nullable count means two things.
+  if (!counting.$meta.notNull) {
+    throw countsInvalid(child.$name, property, `${binding.table}.${binding.property} is nullable`);
+  }
+  const points =
+    column.$meta.references === undefined ? undefined : bindingOf(column.$meta.references());
+  const key = parent.$primaryKey.length === 1 ? parent.$primaryKey[0] : undefined;
+  if (points?.table !== parent.$name || points.property !== key) {
+    throw countsInvalid(
+      child.$name,
+      property,
+      `it is no foreign key to ${parent.$name}'s single primary key, so it cannot count into it`,
+    );
+  }
+  return { parent, column: binding.property, child, references: property };
+}
+
+let cached: { readonly generation: number; readonly counters: readonly Counter[] } | undefined;
+
+/**
+ * Every counter declared on the keys of every registered entity — memoised on
+ * `registryGeneration()` as `relationMap()` is, because the memory driver asks on every write.
+ */
+export function registeredCounters(): readonly Counter[] {
+  const generation = registryGeneration();
+  if (cached?.generation === generation) return cached.counters;
+  const counters = registeredEntities().flatMap((entry) => {
+    const child = entry.core;
+    if (child === undefined) return [];
+    return Object.entries(child.$columns).flatMap(([property, column]) => {
+      const counter = counterOf(child, property, column);
+      return counter === null ? [] : [counter];
+    });
+  });
+  cached = { generation, counters };
+  return counters;
+}
+
+/** The counters kept ON `parent`'s columns. */
+export const countersOf = (parent: EntityCore): readonly Counter[] =>
+  registeredCounters().filter((counter) => counter.parent.$name === parent.$name);
+
+/** The counters whose CHILD is `entity`: what a write to it must move. */
+export const countersTargeting = (entity: string): readonly Counter[] =>
+  registeredCounters().filter((counter) => counter.child.$name === entity);
+
+const physical = (entity: EntityCore, property: string): string => {
+  const column = entity.$columns[property];
+  return column === undefined ? property : columnName(property, column.$meta);
+};
+
+/** The projection `@ultimat3/db` compiles to a trigger on the child. */
+export function describeCounter(counter: Counter): CounterDescriptionLike {
+  const key = counter.parent.$primaryKey[0] ?? '';
+  return {
+    column: physical(counter.parent, counter.column),
+    key: physical(counter.parent, key),
+    table: counter.child.$table,
+    references: physical(counter.child, counter.references),
+    softDelete: counter.child.$softDelete ? physical(counter.child, SOFT_DELETE_COLUMN) : null,
+  };
+}

package/src/cross-tenant.ts

@@ -20,6 +20,18 @@ 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
@@ -47,6 +59,7 @@ 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);
   return storage.run(reason, fn);
 }
 

package/src/cursor.ts

@@ -191,6 +191,13 @@ const assertAliasFits = <Row>(entity: EntityCore<Row>, path: string): void => {
   );
 };
 
+/**
+ * The kinds with no text a seek can bind back: `bytea` cut a page at nothing and answered an empty
+ * page 2 with no error, an array answered `22P02` there, and `jsonb` threw a `TypeError` on the
+ * memory side and at the cursor on Postgres.
+ */
+const UNSEEKABLE: ReadonlySet<ColumnKind> = new Set<ColumnKind>(['jsonb', 'bytea', 'array']);
+
 /**
  * A keyset seek only has a total order when every sort column is present on every row —
  * `null > 'x'` is unknown in SQL and would drop rows from the middle of a listing.
@@ -209,7 +216,16 @@ export const assertSeekable = <Row>(
   for (const key of orderBy) {
     // Resolving the kind is the other half: it refuses a column the entity never declared and a
     // money property named without its part — both mint a cursor nothing can decode.
-    if (kindAt(entity, key.column) === 'timestamptz') assertAliasFits(entity, key.column);
+    const kind = kindAt(entity, key.column);
+    if (kind === 'timestamptz') assertAliasFits(entity, key.column);
+    if (UNSEEKABLE.has(kind)) {
+      throw invariantViolated(
+        entity.$name,
+        'cursor',
+        `${key.column} is ${kind}, which no cursor can carry a position in: page 2 came back ` +
+          'empty or as an error, depending on the row count. Order by a scalar column',
+      );
+    }
     if (columnAt(entity, key.column).$meta.notNull) continue;
     // An ORDINARY nullable key is orderable, `As of 2026-08-24`: NULL has a declared place
     // (`asc nulls last` / `desc nulls first`), the cursor carries that place, and the seek reaches

package/src/database.ts

@@ -3,6 +3,7 @@
 
 import type { EntityCore } from './entity';
 import { memoryRepo, memoryTransactor } from './memory-repo';
+import type { MemoryTables } from './memory-same-tenant';
 import type { RelatedTables } from './preload';
 import type { Table } from './query';
 import { tableFor } from './query';
@@ -46,17 +47,22 @@ export const memoryDriver = (): Driver => {
   // Held separately from `repos` so the reset is a call on the repository the tables already
   // resolved, never a replacement of it.
   const resets: (() => void)[] = [];
+  // The repositories as a same-tenant reference reads them: below the sealing and tenant seams.
+  const stored: MemoryTables = new Map();
+  const repo = <Row>(entity: EntityCore<Row>): Repo<Row> => {
+    const existing = repos.get(entity.$name);
+    // Keyed by entity name and only ever written from that same entity, so the row type a
+    // caller asks for is the one that was stored.
+    if (existing !== undefined) return existing as Repo<Row>;
+    const created = memoryRepo<Row>(entity, [], stored);
+    repos.set(entity.$name, created);
+    resets.push(() => created.reset());
+    // Its history table beside it, as the migration creates both: the parent's writes land there.
+    if (entity.$history !== null) repo(entity.$history);
+    return created;
+  };
   return {
-    repo<Row>(entity: EntityCore<Row>): Repo<Row> {
-      const existing = repos.get(entity.$name);
-      // Keyed by entity name and only ever written from that same entity, so the row type a
-      // caller asks for is the one that was stored.
-      if (existing !== undefined) return existing as Repo<Row>;
-      const created = memoryRepo<Row>(entity);
-      repos.set(entity.$name, created);
-      resets.push(() => created.reset());
-      return created;
-    },
+    repo,
     reset() {
       for (const reset of resets) reset();
     },

package/src/describe-tenancy.ts

@@ -0,0 +1,25 @@
+// Single responsibility: the tenant column of every registered tenant table, physical names only —
+// what `x db gen` writes a row-security policy over. Beside the description, never on it: `x
+// verify` hashes `describeEntities()`, and every tenant app's hash would move for a fact it has.
+
+import { registeredEntities } from './registry';
+
+/** One tenant table: its physical table and the physical column its rows are scoped by. */
+export interface TenantColumnDescription {
+  readonly table: string;
+  readonly column: string;
+}
+
+/**
+ * In the registry's own order (by entity name, then sorted by table for a stable migration). An
+ * entry with no `core` is a hand-registered test double, never an `entity()`: it declares nothing.
+ */
+export const describeTenancy = (): readonly TenantColumnDescription[] =>
+  registeredEntities()
+    .flatMap((entry): TenantColumnDescription[] => {
+      const property = entry.core?.$tenantColumn ?? null;
+      if (property === null) return [];
+      const column = entry.describe().columns.find((candidate) => candidate.property === property);
+      return column === undefined ? [] : [{ table: entry.tableName, column: column.column }];
+    })
+    .sort((a, b) => (a.table < b.table ? -1 : a.table > b.table ? 1 : 0));