@ultimat3/entity 22.15.0 → 24.0.0

package/src/sealed-repo.ts

@@ -0,0 +1,235 @@
+// Single responsibility: the ONE seam a sealed column crosses. A repository wrapped here seals the
+// sealed properties of every row and patch on the way in, opens them on the way out, and rewrites
+// or refuses every predicate that names one — so both drivers store ciphertext and neither knows
+// it. Both driver factories return through this, which is why the typed handle and a hand-held
+// `postgresRepo()` cannot disagree. An entity with no sealed column gets its repository back as is.
+
+import type { AggregateFn } from './aggregate';
+import { namedColumns } from './plan';
+import type { FindManyArgs, Repo, UpsertArgs } from './repo';
+import type { SealedField, SealedSource, SealKeys } from './sealed';
+import {
+  lookupCandidates,
+  openValue,
+  sealedFields,
+  sealKeysOnce,
+  sealValue,
+  serverOnly,
+} from './sealed';
+import type { SealedUse } from './sealed-errors';
+import { sealedLookupValue, sealedMissing, sealedPredicate } from './sealed-errors';
+import type { Predicate } from './tenancy';
+
+type Loose = Readonly<Record<string, unknown>>;
+
+const isRecord = (value: unknown): value is Loose => typeof value === 'object' && value !== null;
+
+/**
+ * A row or a patch with its sealed properties sealed. Only a STRING is sealed: `null` clears the
+ * column, `undefined` leaves it alone, and anything else is not a value this column holds — it is
+ * passed on untouched so the driver's own `$parse` refuses it in the words it always uses.
+ *
+ * Each sealed property is read BY NAME and carried explicitly, because the copy below is a spread
+ * and a repository row does not enumerate one: `insert(row)` and `update(id, row)` with a row
+ * passed back whole write exactly what the row holds, a `null` included.
+ *
+ * `inserting` says the values are a whole ROW: a required sealed column it lacks is refused here,
+ * in words that name the spread that usually lost it. The typed handle refuses the same row with
+ * the same error one step earlier (`entity.$parse`); this is the hand-held repository's.
+ */
+const sealRow = async <T>(
+  entity: SealedSource,
+  fields: readonly SealedField[],
+  values: T,
+  keys: SealKeys,
+  inserting = false,
+): Promise<T> => {
+  if (!isRecord(values)) return values;
+  const sealed: Record<string, unknown> = {};
+  for (const field of fields) {
+    const value = Object.hasOwn(values, field.property) ? values[field.property] : undefined;
+    if (typeof value === 'string') sealed[field.property] = await sealValue(field, value, keys);
+    else if (value !== undefined) sealed[field.property] = value;
+    else if (inserting && field.required) throw sealedMissing(entity.$name, field.property);
+  }
+  // A copy, never the caller's object: the row they hold keeps the plaintext they wrote.
+  return { ...values, ...sealed } as T;
+};
+
+/**
+ * A stored row with its sealed properties opened. A projection that left one out leaves it out.
+ * Opened means SERVER-ONLY (`serverOnly`): the plaintext is read by name and enumerated by nothing,
+ * so the row a repository answers can be serialised whole and the secret stays here.
+ */
+const openRow = async <T>(fields: readonly SealedField[], row: T, keys: SealKeys): Promise<T> => {
+  if (!isRecord(row)) return row;
+  const opened: Record<string, unknown> = {};
+  for (const field of fields) {
+    const value = Object.hasOwn(row, field.property) ? row[field.property] : undefined;
+    if (typeof value === 'string') opened[field.property] = await openValue(field, value, keys);
+  }
+  return serverOnly(fields, row, opened) as T;
+};
+
+const openRows = <T>(
+  fields: readonly SealedField[],
+  rows: readonly T[],
+  keys: SealKeys,
+): Promise<T[]> => Promise.all(rows.map((row) => openRow(fields, row, keys)));
+
+/**
+ * One predicate, as the database can answer it.
+ *
+ * A NULL test passes through for EVERY sealed column: `null` is never sealed — it is stored as
+ * NULL in a nullable `text` column — so whether a value is present is a fact the schema already
+ * publishes, and it is what lets a backfill visit only the rows still to be sealed. Past that an
+ * opaque column answers nothing, and a lookup column answers equality: `eq` and `in` are rewritten
+ * to the stored strings the value seals to — one per declared key, so a rotation in progress still
+ * finds the rows written before it.
+ */
+const rewrite = async (
+  entity: SealedSource,
+  fields: readonly SealedField[],
+  predicate: Predicate,
+  keys: SealKeys,
+): Promise<Predicate> => {
+  const field = fields.find((one) => one.property === predicate.column);
+  if (field === undefined) return predicate;
+  const { op, value } = predicate;
+  if (op === 'is-null' || op === 'is-not-null') return predicate;
+  if (!field.lookup) throw sealedPredicate(entity.$name, field.property, 'a filter', false);
+  // A stored value is ciphertext or NULL, so anything but a string or a NULL would reach the driver
+  // and match nothing — indistinguishable from "no such row". Refused instead.
+  const sealable = (one: unknown): boolean =>
+    typeof one === 'string' || one === null || one === undefined;
+  if ((op === 'eq' || op === 'in') && !(Array.isArray(value) ? value : [value]).every(sealable)) {
+    throw sealedLookupValue(entity.$name, field.property, op === 'in' ? 'list' : 'value');
+  }
+  if (op === 'eq') {
+    if (typeof value !== 'string') return predicate;
+    const candidates = await lookupCandidates(field, value, keys);
+    const [only] = candidates;
+    return candidates.length === 1 && only !== undefined
+      ? { ...predicate, value: only }
+      : { ...predicate, op: 'in', value: candidates };
+  }
+  if (op === 'in' && Array.isArray(value)) {
+    const lists = await Promise.all(
+      value.map((one: unknown) =>
+        typeof one === 'string' ? lookupCandidates(field, one, keys) : [one],
+      ),
+    );
+    return { ...predicate, value: lists.flat() };
+  }
+  throw sealedPredicate(entity.$name, field.property, 'a filter', true);
+};
+
+/** A column named where no rewrite exists: an order, a group, an aggregate, a write's filter. */
+const refuseNamed = (
+  entity: SealedSource,
+  fields: readonly SealedField[],
+  properties: readonly string[],
+  use: SealedUse,
+  lookupAllowed = false,
+): void => {
+  for (const property of properties) {
+    const field = fields.find((one) => one.property === property);
+    if (field === undefined || (lookupAllowed && field.lookup)) continue;
+    throw sealedPredicate(entity.$name, field.property, use, field.lookup);
+  }
+};
+
+const readArgs = async <A extends FindManyArgs>(
+  entity: SealedSource,
+  fields: readonly SealedField[],
+  args: A | undefined,
+  keys: SealKeys,
+): Promise<A | undefined> => {
+  if (args === undefined) return args;
+  refuseNamed(
+    entity,
+    fields,
+    (args.orderBy ?? []).map((key) => key.column),
+    'an order',
+  );
+  if (args.where === undefined) return args;
+  const where = await Promise.all(args.where.map((one) => rewrite(entity, fields, one, keys)));
+  return { ...args, where };
+};
+
+/**
+ * `repo`, sealing. Every method stays `async` and rejects rather than throws, as the contract
+ * requires. Written as a spread over the inner repository so a member this file does not know —
+ * `MemoryRepo.reset()` — survives it.
+ */
+export const sealedRepo = <Row, R extends Repo<Row>>(entity: SealedSource, repo: R): R => {
+  const fields = sealedFields(entity);
+  if (fields.length === 0) return repo;
+  const filterOf = (filter: unknown): readonly string[] =>
+    namedColumns(filter).map(([property]) => property);
+
+  // Every method takes its own ring: one resolution per repository call, however many values.
+  const sealing: Repo<Row> = {
+    async findById(id, options) {
+      const row = await repo.findById(id, options);
+      return row === null ? null : openRow(fields, row, sealKeysOnce());
+    },
+    async findMany(args) {
+      const keys = sealKeysOnce();
+      const page = await repo.findMany(await readArgs(entity, fields, args, keys));
+      return { rows: await openRows(fields, page.rows, keys), nextCursor: page.nextCursor };
+    },
+    async insert(values, options) {
+      const keys = sealKeysOnce();
+      const stored = await repo.insert(await sealRow(entity, fields, values, keys, true), options);
+      return openRow(fields, stored, keys);
+    },
+    async insertAll(rows, options) {
+      const keys = sealKeysOnce();
+      const sealed = await Promise.all(rows.map((row) => sealRow(entity, fields, row, keys, true)));
+      return openRows(fields, await repo.insertAll(sealed, options), keys);
+    },
+    async upsertAll(rows, args: UpsertArgs<Row>) {
+      // A conflict target is a uniqueness comparison, so it is a lookup column's or nobody's.
+      refuseNamed(entity, fields, args.onConflict, 'an upsert conflict target', true);
+      const keys = sealKeysOnce();
+      const sealed = await Promise.all(rows.map((row) => sealRow(entity, fields, row, keys, true)));
+      return openRows(fields, await repo.upsertAll(sealed, args), keys);
+    },
+    async update(id, patch, options) {
+      const keys = sealKeysOnce();
+      const stored = await repo.update(id, await sealRow(entity, fields, patch, keys), options);
+      return openRow(fields, stored, keys);
+    },
+    delete: (id, options) => repo.delete(id, options),
+    // A filtered write's filter is refused for every sealed column, lookup included: its shape is
+    // one value per column, and during a rotation a lookup value has one stored form PER KEY.
+    async deleteWhere(filter, options) {
+      refuseNamed(entity, fields, filterOf(filter), "a filtered write's filter");
+      return repo.deleteWhere(filter, options);
+    },
+    async updateWhere(filter, patch, options) {
+      refuseNamed(entity, fields, filterOf(filter), "a filtered write's filter");
+      return repo.updateWhere(
+        filter,
+        await sealRow(entity, fields, patch, sealKeysOnce()),
+        options,
+      );
+    },
+    async count(args) {
+      return repo.count(await readArgs(entity, fields, args, sealKeysOnce()));
+    },
+    async countBy(column, args) {
+      refuseNamed(entity, fields, [column], 'a grouped count');
+      return repo.countBy(column, await readArgs(entity, fields, args, sealKeysOnce()));
+    },
+    async aggregate(fn: AggregateFn, column, args) {
+      refuseNamed(entity, fields, [column], 'an aggregate');
+      return repo.aggregate(fn, column, await readArgs(entity, fields, args, sealKeysOnce()));
+    },
+    async approximateCount(args) {
+      return repo.approximateCount(await readArgs(entity, fields, args, sealKeysOnce()));
+    },
+  };
+  return { ...repo, ...sealing };
+};

package/src/sealed.ts

@@ -0,0 +1,196 @@
+// Single responsibility: which columns of an entity are sealed, and the two conversions a value
+// crosses on — plaintext to the stored string on a write, the stored string back on a read. The
+// cipher is `@ultimat3/core`'s `seal()` / `open()`; this file only decides WHAT is sealed, under
+// which purpose. `sealed-repo.ts` is the one caller on the row path.
+
+import type { SealKeyRing } from '@ultimat3/core';
+import { openText, resolveSealKeys, seal, sealAll } from '@ultimat3/core';
+import { columnName } from './column';
+import type { AnyColumn, ColumnMap } from './types';
+
+/** The slice of an entity this reads, so the declaration path can ask before `entity()` returns. */
+export interface SealedSource {
+  readonly $name: string;
+  readonly $table: string;
+  readonly $columns: ColumnMap;
+}
+
+export interface SealedField {
+  /** Property key on the row. */
+  readonly property: string;
+  /** Physical column — half of the purpose, and what `x doctor` names. */
+  readonly column: string;
+  /**
+   * `entity:<table>.<column>`, derived and never stated: two columns cannot share one by accident,
+   * so a value copied from one sealed column into another does not open there. PHYSICAL names —
+   * the ones a migration renames — so renaming the table or the column is a re-seal.
+   */
+  readonly purpose: string;
+  readonly lookup: boolean;
+  /** NOT NULL — and a sealed column takes no default, so a row to insert must carry it. */
+  readonly required: boolean;
+  /**
+   * The parser the column had before `.sealed()`, which judges a PLAINTEXT — `text({ max })`
+   * included. Run before a value is sealed, because nothing after that point can: the driver only
+   * ever sees the sealed string, which is longer than any bound the author wrote.
+   */
+  readonly parse: (value: unknown) => unknown;
+}
+
+export const sealedPurpose = (table: string, column: string): string => `entity:${table}.${column}`;
+
+const describeField = (table: string, property: string, column: AnyColumn): SealedField[] => {
+  const sealed = column.$meta.sealed;
+  if (sealed === undefined) return [];
+  const physical = columnName(property, column.$meta);
+  return [
+    {
+      property,
+      column: physical,
+      purpose: sealedPurpose(table, physical),
+      lookup: sealed.lookup,
+      required: column.$meta.notNull,
+      // The UNWRAPPED parser: `column.$parse` passes anything shaped like a sealed value, so a
+      // lookalike plaintext skipped `text({ max })` on its way to being sealed.
+      parse: sealed.plaintext,
+    },
+  ];
+};
+
+const fields = new WeakMap<ColumnMap, readonly SealedField[]>();
+
+/**
+ * Every sealed column of the entity, in declaration order — empty for almost every entity, and
+ * that is the fast path: a repository over one with none is returned untouched. Memoised on the
+ * column map, which is the declaration itself and outlives nothing it should not.
+ */
+export const sealedFields = (entity: SealedSource): readonly SealedField[] => {
+  const known = fields.get(entity.$columns);
+  if (known !== undefined) return known;
+  const found = Object.entries(entity.$columns).flatMap(([property, column]) =>
+    describeField(entity.$table, property, column),
+  );
+  fields.set(entity.$columns, found);
+  return found;
+};
+
+/**
+ * The key ring for ONE repository call, resolved the first time a value needs it and shared by
+ * every value after. A 500-row page with two sealed columns is a thousand values and one ring —
+ * not a thousand reads of the environment or the key file. Lazy, so a call that seals and opens
+ * nothing needs no key at all; per call and never longer, so a rotation is seen by the next one.
+ */
+export type SealKeys = () => Promise<SealKeyRing>;
+
+export const sealKeysOnce = (): SealKeys => {
+  let ring: Promise<SealKeyRing> | undefined;
+  return () => {
+    ring ??= resolveSealKeys();
+    return ring;
+  };
+};
+
+/**
+ * The stored form of one value: validated as the plaintext it is, then sealed. A lookup column
+ * seals deterministically so equality survives. `async`, so a refused value rejects like every
+ * other repository failure rather than throwing at the call.
+ */
+export const sealValue = async (
+  field: SealedField,
+  plaintext: string,
+  keys: SealKeys,
+): Promise<string> => {
+  const checked = field.parse(plaintext);
+  return seal(typeof checked === 'string' ? checked : plaintext, {
+    purpose: field.purpose,
+    deterministic: field.lookup,
+    keys: await keys(),
+  });
+};
+
+/**
+ * The plaintext of one stored value. A stored string that is not a sealed value is
+ * `X_SEAL_INVALID`, always: there is no reading of an unsealed row, so a column sealed after rows
+ * were written is migrated by expand, `backfill()`, contract — never by tolerating the old rows.
+ */
+export const openValue = async (
+  field: SealedField,
+  stored: string,
+  keys: SealKeys,
+): Promise<string> => openText(stored, { purpose: field.purpose, keys: await keys() });
+
+/**
+ * Every stored string a lookup may match `plaintext` against: one per declared key. Outside a
+ * rotation that is one string; while a retired key is still declared it is two, so the rows
+ * written before the rotation are still found.
+ */
+export const lookupCandidates = async (
+  field: SealedField,
+  plaintext: string,
+  keys: SealKeys,
+): Promise<readonly string[]> => sealAll(plaintext, { purpose: field.purpose, keys: await keys() });
+
+type Loose = Readonly<Record<string, unknown>>;
+
+/**
+ * A copy of `row` whose sealed properties are SERVER-ONLY: own, readable and writable —
+ * `row.password` is the plaintext and the row type does not change — but NOT ENUMERABLE. So
+ * `JSON.stringify`, an object spread, `Object.keys`/`entries`, `structuredClone` and every
+ * serialiser built on them leave the property behind, which is what keeps a row handed whole to a
+ * `query`, an island prop, a log line, a job payload or a cache tier from carrying the secret out.
+ * Fail closed: a path nobody listed omits it too, and an explicit `row.password` is the only read.
+ *
+ * `opened` wins over the stored value; a property the row does not have is not invented, and a
+ * NULL is hidden like a value — whether a secret is set is not for the wire either.
+ */
+export const serverOnly = <T extends Loose>(
+  fields: readonly SealedField[],
+  row: T,
+  opened: Loose = {},
+): T => {
+  const out: Record<string, unknown> = { ...row };
+  for (const { property } of fields) {
+    if (!Object.hasOwn(row, property)) continue;
+    Object.defineProperty(out, property, {
+      value: Object.hasOwn(opened, property) ? opened[property] : row[property],
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return out as T;
+};
+
+/**
+ * A copy of a row that KEEPS what `serverOnly` set — `{ ...row }` would drop every sealed property,
+ * which is the point of it everywhere a row leaves and wrong where server code only wants its own
+ * object. Enumerable properties stay enumerable, so this is a spread for every other entity.
+ */
+export const copyRow = <T extends object>(row: T): T =>
+  Object.defineProperties({}, Object.getOwnPropertyDescriptors(row)) as T;
+
+/**
+ * `keys` of a row, each as the row holds it: a projection that NAMES a sealed column still answers
+ * it server-only. Assigning the value instead would re-create it enumerable, and a row that names
+ * the secret would be the one repository row that serialises it. A key the row lacks is present
+ * and `undefined`, as an assignment would leave it.
+ */
+export const pickRow = <T extends object, K extends keyof T & string>(
+  row: T,
+  keys: readonly K[],
+): Pick<T, K> => {
+  const picked = {};
+  for (const key of keys) {
+    Object.defineProperty(
+      picked,
+      key,
+      Object.getOwnPropertyDescriptor(row, key) ?? {
+        value: undefined,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      },
+    );
+  }
+  return picked as Pick<T, K>;
+};

package/src/seed.ts

@@ -10,6 +10,7 @@ import type { Driver } from './database';
 import { memoryDriver } from './database';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { EntityError } from './errors';
+import type { Tx } from './repo';
 import type { Predicate } from './tenancy';
 import type { ColumnMap, Insertable } from './types';
 
@@ -143,7 +144,7 @@ export interface SeedContext {
   readonly now: Date;
   readonly environment: Environment;
   readonly tier: SeedTier;
-  /** Reads still run; every write short-circuits and is counted as what it WOULD have written. */
+  /** Every verb runs for real, inside a transaction `run()` rolls back: counted, never kept. */
   readonly dryRun: boolean;
   readonly metrics: SeedMetrics;
 }
@@ -209,6 +210,14 @@ const equalityPredicates = <Row>(where: Partial<Row>): readonly Predicate[] =>
 const primaryKeyTarget = <Row>(entity: EntityCore<Row>): readonly (keyof Row & string)[] =>
   entity.$primaryKey as readonly (keyof Row & string)[];
 
+/**
+ * Thrown out of the dry run's own transaction to roll it back; never leaves `run()`. A dry run IS
+ * the real run, in a transaction (`Driver.transactor()`) that is then rolled back — one rule, so
+ * what it reports is what a real run would do: a key another tenant holds is skipped, a second
+ * verb sees the first one's rows, and a seed that would fail fails.
+ */
+const UNDO = Object.freeze({ seedDryRun: 'undo' });
+
 /**
  * A primary key the row leaves to a GENERATED default is a different id on every run, so the
  * conflict target finds nothing and each replay inserts one more copy. `$parse` refuses a key with
@@ -256,89 +265,104 @@ export const defineSeed = (
       const driver = options.driver ?? memoryDriver();
       const dryRun = options.dryRun ?? false;
       const metrics: SeedMetrics = { inserted: 0, updated: 0, skipped: 0 };
-      const context: SeedContext = {
-        insert: async (entity, rows) => {
-          // Judged on the row as WRITTEN, before `$parse` fills the column that would hide it.
-          for (const [position, row] of rows.entries()) {
-            const missing = entity.$primaryKey.find(
+      /** The context a seed body writes through; `tx` is the dry run's, and absent otherwise. */
+      const contextFor = (tx: Tx | undefined): SeedContext => {
+        // The in-memory driver undoes through the `tx` a write is handed; Postgres finds the open
+        // transaction itself and ignores it.
+        const undo = tx === undefined ? {} : { tx };
+        const context: SeedContext = {
+          insert: async (entity, rows) => {
+            // Judged on the row as WRITTEN, before `$parse` fills the column that would hide it.
+            for (const [position, row] of rows.entries()) {
+              const missing = entity.$primaryKey.find(
+                (property) =>
+                  entity.$columns[property]?.$meta.default?.kind === 'generated' &&
+                  !Object.hasOwn(row, property),
+              );
+              if (missing !== undefined) throw generatedKey(entity, missing, position);
+            }
+            const parsed = rows.map((row) => entity.$parse(row));
+            const written = await driver.repo(entity).upsertAll(parsed, {
+              ...undo,
+              onConflict: primaryKeyTarget(entity),
+              // Never `'update'`: a do-nothing conflict needs no tenant column in the target, so this
+              // is the one form that replays on a tenant-scoped entity whose unique keys are global.
+              onMatch: 'nothing',
+            });
+            metrics.inserted += written.length;
+            metrics.skipped += parsed.length - written.length;
+          },
+
+          upsert: async (entity, key, values) => {
+            const row = entity.$parse(values);
+            const repo = driver.repo(entity);
+            const where = Object.fromEntries(
+              key.by.map((property) => [property, cellOf(row, property)]),
+            );
+            const found = await repo.findMany({ where: equalityPredicates(where), limit: 1 });
+            const stored = found.rows[0];
+            const preserve: readonly string[] = key.preserve ?? [CREATED_AT_COLUMN];
+            // Only what the CALLER named, and never a key the table generates: `$parse` fills a
+            // fresh uuid and a `defaultNow()` into `row`, which no stored row can equal — so a
+            // re-run reported every row `'updated'` and never once `'skipped'`.
+            const compared = Object.keys(row as Record<string, unknown>).filter(
               (property) =>
-                entity.$columns[property]?.$meta.default?.kind === 'generated' &&
-                !Object.hasOwn(row, property),
+                !preserve.includes(property) &&
+                Object.hasOwn(values, property) &&
+                (!entity.$primaryKey.includes(property) || key.by.includes(property as never)),
             );
-            if (missing !== undefined) throw generatedKey(entity, missing, position);
-          }
-          const parsed = rows.map((row) => entity.$parse(row));
-          if (dryRun) {
-            metrics.inserted += parsed.length;
-            return;
-          }
-          const written = await driver.repo(entity).upsertAll(parsed, {
-            onConflict: primaryKeyTarget(entity),
-            // Never `'update'`: a do-nothing conflict needs no tenant column in the target, so this
-            // is the one form that replays on a tenant-scoped entity whose unique keys are global.
-            onMatch: 'nothing',
-          });
-          metrics.inserted += written.length;
-          metrics.skipped += parsed.length - written.length;
-        },
-
-        upsert: async (entity, key, values) => {
-          const row = entity.$parse(values);
-          const repo = driver.repo(entity);
-          const where = Object.fromEntries(
-            key.by.map((property) => [property, cellOf(row, property)]),
-          );
-          const found = await repo.findMany({ where: equalityPredicates(where), limit: 1 });
-          const stored = found.rows[0];
-          const preserve: readonly string[] = key.preserve ?? [CREATED_AT_COLUMN];
-          // Only what the CALLER named, and never a key the table generates: `$parse` fills a
-          // fresh uuid and a `defaultNow()` into `row`, which no stored row can equal — so a
-          // re-run reported every row `'updated'` and never once `'skipped'`.
-          const compared = Object.keys(row as Record<string, unknown>).filter(
-            (property) =>
-              !preserve.includes(property) &&
-              Object.hasOwn(values, property) &&
-              (!entity.$primaryKey.includes(property) || key.by.includes(property as never)),
-          );
-          if (
-            stored !== undefined &&
-            compared.every((property) => sameCell(cellOf(stored, property), cellOf(row, property)))
-          ) {
-            metrics.skipped += 1;
-            return 'skipped';
-          }
-          const write: SeedWrite = stored === undefined ? 'inserted' : 'updated';
-          if (!dryRun) {
+            if (
+              stored !== undefined &&
+              compared.every((property) =>
+                sameCell(cellOf(stored, property), cellOf(row, property)),
+              )
+            ) {
+              metrics.skipped += 1;
+              return 'skipped';
+            }
+            const write: SeedWrite = stored === undefined ? 'inserted' : 'updated';
             await repo.upsertAll([stored === undefined ? row : withoutPreserved(row, preserve)], {
+              ...undo,
               onConflict: key.by,
               onMatch: 'update',
             });
-          }
-          metrics[write === 'inserted' ? 'inserted' : 'updated'] += 1;
-          return write;
-        },
+            metrics[write === 'inserted' ? 'inserted' : 'updated'] += 1;
+            return write;
+          },
 
-        count: async (entity, where) =>
-          driver
-            .repo(entity)
-            .count(where === undefined ? {} : { where: equalityPredicates(where) }),
+          count: async (entity, where) =>
+            driver
+              .repo(entity)
+              .count(where === undefined ? {} : { where: equalityPredicates(where) }),
 
-        exists: async (entity, where) => (await context.count(entity, where)) > 0,
+          exists: async (entity, where) => (await context.count(entity, where)) > 0,
 
-        deleteWhere: async (entity, where) => {
-          if (entity.$softDelete) throw softDeleteWipe(entity);
-          if (dryRun) return context.count(entity, where);
-          return driver.repo(entity).deleteWhere(where);
-        },
+          deleteWhere: async (entity, where) => {
+            if (entity.$softDelete) throw softDeleteWipe(entity);
+            return driver.repo(entity).deleteWhere(where, undo);
+          },
 
-        id: seedId,
-        now: entityNow(),
-        environment: resolveEnvironment({ env: options.env }),
-        tier,
-        dryRun,
-        metrics,
+          id: seedId,
+          now: entityNow(),
+          environment: resolveEnvironment({ env: options.env }),
+          tier,
+          dryRun,
+          metrics,
+        };
+        return context;
       };
-      await build(context);
+      if (!dryRun) {
+        await build(contextFor(undefined));
+        return { name, tier, metrics };
+      }
+      try {
+        await driver.transactor().run(async (tx) => {
+          await build(contextFor(tx));
+          throw UNDO;
+        });
+      } catch (thrown) {
+        if (thrown !== UNDO) throw thrown;
+      }
       return { name, tier, metrics };
     },
   };

package/src/transition.ts

@@ -113,6 +113,9 @@ export const transitionRow = async <Row, C extends ColumnMap>(
   // Keyed on the entity's OWN primary key, never the literal `id`: a `code`-keyed entity has no
   // `id` column, so the filter matched nothing in memory (a false `X_STATE_CONFLICT`) and named a
   // column Postgres does not have (`X_INVARIANT_VIOLATED`).
+  // An absent id names no row, and is refused HERE: `namedColumns` drops an `undefined` filter
+  // value, so the predicate below would be the from-state alone and move every row in it.
+  if (id === undefined || id === null) throw notFound(entity.$name, String(id));
   const key = singleKeyOf(entity, 'transition');
   const filter = { [key]: id, [property]: move.from } as unknown as RowPatch<Row>;
   const values = { [property]: move.to } as unknown as RowPatch<Row>;