@arki/journal 0.0.0-stage → 0.1.0

package/src/entity.ts

@@ -0,0 +1,377 @@
+import { getTableColumns, getTableName } from 'drizzle-orm';
+import { getTableConfig, PgColumn } from 'drizzle-orm/pg-core';
+
+import type {
+  AnyEventDef,
+  EntityDef,
+  EntityId,
+  EntityTable,
+  KeyColumn,
+  KeyLimit,
+  Patch,
+  Recorded,
+  RecordedOf,
+  ReducerRow,
+  Reducers,
+  ReducerValues,
+  Row,
+} from './types.js';
+import { JournalError } from './errors.js';
+import { assertStoredName } from './id.js';
+
+/**
+ * The keys that every `.create` reducer so far returns with a type that
+ * excludes `undefined`. `CreateResults` is the union of their return types, so a key
+ * one of them leaves out, or may set to `undefined`, is not in the set. With
+ * no `.create` yet, the set is empty.
+ *
+ * `keyof CreateResults & string` keeps the mapped type from distributing over the
+ * union: `keyof (A | B)` is the keys both have, and `CreateResults[P]` is the union
+ * of what each branch holds there. A create returning `cond ? { note } : {}`
+ * therefore promises nothing.
+ */
+export type GuaranteedCreateKeys<CreateResults> = [CreateResults] extends [never]
+  ? never
+  : { [P in keyof CreateResults & string]: undefined extends CreateResults[P] ? never : P }[keyof CreateResults &
+      string];
+
+/**
+ * The state an `.on` reducer receives: the reducer-shaped row, with the keys
+ * every `.create` reducer sets made required. A patch cannot unset a key and
+ * `undefined` values are stripped, so a key a create sets stays set.
+ */
+export type OnReducerRow<Tbl extends EntityTable, Key extends string, CreateResults> = ReducerRow<Tbl, Key> &
+  Required<Pick<ReducerValues<Tbl, Key>, GuaranteedCreateKeys<CreateResults> & keyof ReducerValues<Tbl, Key>>>;
+
+/**
+ * An entity under construction. Each `.create` / `.on` adds the event to the
+ * union the entity accepts, so `events` cannot return an undeclared event.
+ * `CreateResults` collects what the `.create` reducers return; see `OnReducerRow`.
+ *
+ * The rule: every `.create` comes before the first `.on`. After the first
+ * `.on` the builder is `OnOnlyEntityBuilder`, which has no `.create`: a later
+ * create could leave out a column that `.on` was promised.
+ */
+export type EntityBuilder<
+  Kind extends string,
+  Tbl extends EntityTable,
+  EventDefs extends AnyEventDef,
+  Meta,
+  Key extends string = 'id',
+  CreateResults = never,
+> = OnOnlyEntityBuilder<Kind, Tbl, EventDefs, Meta, Key, CreateResults> & {
+  /** A create reducer receives no row. It builds the first row from the event. */
+  create<AddedEvent extends AnyEventDef, CreateResult extends ReducerValues<Tbl, Key>>(
+    event: AddedEvent,
+    reduce: (event: RecordedOf<AddedEvent, Meta, EntityId<Tbl, Key>>) => CreateResult,
+  ): EntityBuilder<Kind, Tbl, EventDefs | AddedEvent, Meta, Key, CreateResults | CreateResult>;
+};
+
+/** An entity after its first `.on`: only more `.on` reducers may follow. */
+export type OnOnlyEntityBuilder<
+  Kind extends string,
+  Tbl extends EntityTable,
+  EventDefs extends AnyEventDef,
+  Meta,
+  Key extends string = 'id',
+  CreateResults = never,
+> = EntityDef<Kind, Tbl, EventDefs, Meta, Key> & {
+  /**
+   * An `.on` reducer always receives the reducer-shaped state: the insert shape plus
+   * the key column and `version`. Columns with database defaults may be absent unless
+   * every `.create` reducer sets them. It returns a patch that is merged onto the
+   * state. Returning `null` deletes the row; the events stay.
+   */
+  on<AddedEvent extends AnyEventDef>(
+    event: AddedEvent,
+    reduce: (
+      row: OnReducerRow<Tbl, Key, CreateResults>,
+      event: RecordedOf<AddedEvent, Meta, EntityId<Tbl, Key>>,
+    ) => Patch<Tbl, Key> | null,
+  ): OnOnlyEntityBuilder<Kind, Tbl, EventDefs | AddedEvent, Meta, Key, CreateResults>;
+};
+
+/** The two facts `KeyColumn` states: the column holds a string and is not null. */
+function isKeyColumn(column: PgColumn): column is KeyColumn {
+  const [dataType] = column.dataType.split(' ');
+  return dataType === 'string' && column.notNull;
+}
+
+/**
+ * The supported key types: `text`, `varchar`, `varchar(n)` and `uuid`. The first three compare
+ * as exact strings. A `uuid` ignores case, so its ids must also use the canonical spelling
+ * (lower-case, hyphenated); `assertExactId` checks that on every call.
+ */
+const EXACT_KEY_TYPE = /^(?:text|uuid|varchar(?:\s*\(\s*\d+\s*\))?)$/;
+
+/** A column's SQL type in comparable form: trimmed and lower-case. */
+function sqlTypeOf(column: PgColumn): string {
+  return column.getSQLType().trim().toLowerCase();
+}
+
+/** The journal's own limit: `journal_events.entity_id` holds 256 characters. */
+const LOG_KEY_LIMIT = 256;
+
+/**
+ * The longest id the key may hold, in code points: `varchar(n)` allows `min(n, 256)`, `text` and
+ * `varchar` allow the log's 256, and a `uuid` is fixed at 36.
+ */
+function keyLimitOf(column: PgColumn): KeyLimit {
+  const sqlType = sqlTypeOf(column);
+  if (sqlType === 'uuid') return { max: 36, source: 'column' };
+  const length = /\(\s*(\d+)\s*\)/.exec(sqlType)?.[1];
+  if (length !== undefined && Number(length) <= LOG_KEY_LIMIT) return { max: Number(length), source: 'column' };
+  return { max: LOG_KEY_LIMIT, source: 'journal' };
+}
+
+/**
+ * Whether `column` identifies one row on its own: it is the primary key, or
+ * carries a unique constraint, or is the only column of a table-level primary
+ * key, unique constraint or unique index. Table-level constraints and indexes
+ * hold their own column objects (an index wraps them), so they are matched by
+ * SQL name; an SQL expression in an index has no name and never matches.
+ */
+function isUniqueOn(table: EntityTable, column: PgColumn): boolean {
+  if (column.primary || column.isUnique) return true;
+  const only = (columns: readonly unknown[]): boolean => {
+    const [first] = columns;
+    return (
+      columns.length === 1 &&
+      typeof first === 'object' &&
+      first !== null &&
+      'name' in first &&
+      first.name === column.name
+    );
+  };
+  const config = getTableConfig(table);
+  return (
+    config.primaryKeys.some(pk => only(pk.columns)) ||
+    config.uniqueConstraints.some(constraint => only(constraint.columns)) ||
+    // A unique index with a `where` is unique only inside that subset, so it is no key.
+    config.indexes.some(index => index.config.unique && index.config.where === undefined && only(index.config.columns))
+  );
+}
+
+/** The column `table` holds under `key`, checked to be a usable entity key. */
+function keyColumnOf(kind: string, table: EntityTable, key: string): KeyColumn {
+  const columns: Record<string, unknown> = getTableColumns(table);
+  const column = columns[key];
+  if (!(column instanceof PgColumn)) {
+    throw new JournalError(
+      'BAD_DEFINITION',
+      'entity',
+      kind,
+      `journal: entity "${kind}": table "${getTableName(table)}" has no column "${key}"`,
+    );
+  }
+  const [dataType] = column.dataType.split(' ');
+  const sqlType = sqlTypeOf(column);
+  if (dataType !== 'custom' && !isKeyColumn(column)) {
+    throw new JournalError(
+      'BAD_DEFINITION',
+      'entity',
+      kind,
+      dataType === 'string'
+        ? `journal: entity "${kind}": key column "${key}" must be not null`
+        : `journal: entity "${kind}": key column "${key}" must hold a string, it holds ${column.dataType}`,
+    );
+  }
+  if (!EXACT_KEY_TYPE.test(sqlType)) {
+    throw new JournalError(
+      'BAD_DEFINITION',
+      'entity',
+      kind,
+      `journal: entity "${kind}": key column "${key}" has SQL type "${sqlType}"; the key must be text, varchar or uuid, because other types can treat two different strings as the same key`,
+    );
+  }
+  if (!isKeyColumn(column)) {
+    throw new JournalError(
+      'BAD_DEFINITION',
+      'entity',
+      kind,
+      `journal: entity "${kind}": key column "${key}" is a custom column type; a key must be a plain text, varchar or uuid column, because a custom type's mapping can change the string`,
+    );
+  }
+  if (!isUniqueOn(table, column)) {
+    throw new JournalError(
+      'BAD_DEFINITION',
+      'entity',
+      kind,
+      `journal: entity "${kind}": key column "${key}" must be the primary key or carry a unique constraint`,
+    );
+  }
+  return column;
+}
+
+export function defineEntity<Kind extends string, Tbl extends EntityTable, Meta, Key extends string>(
+  kind: Kind,
+  table: Tbl,
+  key: Key,
+): EntityBuilder<Kind, Tbl, never, Meta, Key> {
+  assertStoredName('entity kind', kind);
+  const keyColumn = keyColumnOf(kind, table, key);
+  const uuidKey = sqlTypeOf(keyColumn) === 'uuid';
+  const keyLimit = keyLimitOf(keyColumn);
+  return builder<Kind, Tbl, never, Meta, Key, never>(
+    kind,
+    table,
+    key,
+    keyColumn,
+    uuidKey,
+    keyLimit,
+    new Map(),
+    new Map(),
+    null,
+  );
+}
+
+function builder<
+  Kind extends string,
+  Tbl extends EntityTable,
+  EventDefs extends AnyEventDef,
+  Meta,
+  Key extends string,
+  CreateResults,
+>(
+  kind: Kind,
+  table: Tbl,
+  key: Key,
+  keyColumn: KeyColumn,
+  uuidKey: boolean,
+  keyLimit: KeyLimit,
+  events: ReadonlyMap<string, AnyEventDef>,
+  reducers: ReadonlyMap<string, Reducers<Tbl, Meta, Key>>,
+  /** The first `.on` event type, once one is declared. `.create` is refused after it. */
+  firstOn: string | null,
+): EntityBuilder<Kind, Tbl, EventDefs, Meta, Key, CreateResults> {
+  const declare = <AddedEvent extends AnyEventDef, Next>(
+    event: AddedEvent,
+    next: Reducers<Tbl, Meta, Key>,
+    sealedBy: string | null,
+  ): EntityBuilder<Kind, Tbl, EventDefs | AddedEvent, Meta, Key, Next> =>
+    builder<Kind, Tbl, EventDefs | AddedEvent, Meta, Key, Next>(
+      kind,
+      table,
+      key,
+      keyColumn,
+      uuidKey,
+      keyLimit,
+      new Map([...events, [event.type, event]]),
+      new Map([...reducers, [event.type, next]]),
+      sealedBy,
+    );
+  const create = <AddedEvent extends AnyEventDef, CreateResult extends ReducerValues<Tbl, Key>>(
+    event: AddedEvent,
+    reduce: (event: RecordedOf<AddedEvent, Meta, EntityId<Tbl, Key>>) => CreateResult,
+  ): EntityBuilder<Kind, Tbl, EventDefs | AddedEvent, Meta, Key, CreateResults | CreateResult> => {
+    if (firstOn !== null) {
+      throw new JournalError(
+        'BAD_DEFINITION',
+        'entity',
+        kind,
+        `journal: entity "${kind}": declare .create(${event.type}) before any .on; .on(${firstOn}) came first`,
+      );
+    }
+    const current = reducers.get(event.type) ?? {};
+    if (current.create !== undefined) {
+      throw new JournalError(
+        'BAD_DEFINITION',
+        'entity',
+        kind,
+        `journal: entity "${kind}" already declares a create reducer for "${event.type}"`,
+      );
+    }
+    return declare<AddedEvent, CreateResults | CreateResult>(event, { ...current, create: reduce }, null);
+  };
+  const on = <AddedEvent extends AnyEventDef>(
+    event: AddedEvent,
+    reduce: (
+      row: OnReducerRow<Tbl, Key, CreateResults>,
+      event: RecordedOf<AddedEvent, Meta, EntityId<Tbl, Key>>,
+    ) => Patch<Tbl, Key> | null,
+  ): OnOnlyEntityBuilder<Kind, Tbl, EventDefs | AddedEvent, Meta, Key, CreateResults> => {
+    const current = reducers.get(event.type) ?? {};
+    if (current.on !== undefined) {
+      throw new JournalError(
+        'BAD_DEFINITION',
+        'entity',
+        kind,
+        `journal: entity "${kind}" already declares an on reducer for "${event.type}"`,
+      );
+    }
+    return declare<AddedEvent, CreateResults>(event, { ...current, on: reduce }, firstOn ?? event.type);
+  };
+  return { kind, table, key, keyColumn, uuidKey, keyLimit, events, reducers, create, on };
+}
+
+/**
+ * A copy of `value` without the own keys that hold `undefined`. In a patch,
+ * `undefined` means "unchanged". In a create result it means "not set": the
+ * database default applies, and the key is not part of the journal's state.
+ */
+function definedOnly<T extends object>(value: T): T {
+  const out = { ...value };
+  for (const key in out) {
+    if (Object.hasOwn(out, key) && out[key] === undefined) delete out[key];
+  }
+  return out;
+}
+
+function hasKey<T extends object, K extends string>(value: T, key: K): value is T & Record<K, unknown> {
+  return key in value;
+}
+
+/**
+ * `{ [key]: id }` typed by the key. TypeScript types a computed key as an
+ * index signature; the guard above narrows it back to the one key.
+ */
+function keyed<K extends string, Id>(key: K, id: Id): Record<K, Id> {
+  const out = { [key]: id };
+  if (!hasKey(out, key)) throw new Error(`journal: key "${key}" was not set`);
+  return out;
+}
+
+/** The reducer-shaped row: a state plus the key column and `version`. */
+export function withEntityIdentity<Tbl extends EntityTable, Key extends string>(
+  entity: EntityDef<string, Tbl, AnyEventDef, unknown, Key>,
+  state: Row<Tbl> | ReducerValues<Tbl, Key>,
+  id: EntityId<Tbl, Key>,
+  version: number,
+): ReducerRow<Tbl, Key> {
+  return { ...state, ...keyed(entity.key, id), version };
+}
+
+/**
+ * Fold one event onto the in-memory state. Shared by write and replay, so
+ * both produce the same value for every column a reducer set. The caller has
+ * checked that a reducer exists for the event in this state. `reducerColumns`, when
+ * given, collects the columns the reducers set: a create starts it afresh, a
+ * patch adds its keys, a delete empties it.
+ */
+export function reduceOne<Tbl extends EntityTable, Meta, Key extends string>(
+  entity: EntityDef<string, Tbl, AnyEventDef, Meta, Key>,
+  state: Row<Tbl> | ReducerValues<Tbl, Key> | null,
+  id: EntityId<Tbl, Key>,
+  event: Recorded<string, unknown, Meta>,
+  reducerColumns?: Set<string>,
+): ReducerValues<Tbl, Key> | null {
+  const reducers = entity.reducers.get(event.type);
+  if (state === null) {
+    if (reducers?.create === undefined)
+      throw new Error(`journal: entity "${entity.kind}" has no create reducer for "${event.type}"`);
+    const created = definedOnly(reducers.create(event));
+    reducerColumns?.clear();
+    for (const key of Object.keys(created)) reducerColumns?.add(key);
+    return created;
+  }
+  if (reducers?.on === undefined)
+    throw new Error(`journal: entity "${entity.kind}" has no on reducer for "${event.type}"`);
+  const patch = reducers.on(withEntityIdentity(entity, state, id, event.version - 1), event);
+  if (patch === null) {
+    reducerColumns?.clear();
+    return null;
+  }
+  const defined = definedOnly(patch);
+  for (const key of Object.keys(defined)) reducerColumns?.add(key);
+  return { ...state, ...defined };
+}

package/src/errors.ts

@@ -0,0 +1,134 @@
+export type JournalErrorCode =
+  | 'CONFLICT'
+  | 'NO_ROW'
+  | 'ROW_EXISTS'
+  | 'UNKNOWN_EVENT'
+  | 'VERSION_MISMATCH'
+  | 'NO_HISTORY'
+  | 'HISTORY_GAP'
+  | 'REPLAY_FAILED'
+  | 'UNSTABLE_SCHEMA'
+  | 'ID_MISMATCH'
+  | 'VALUE_MISMATCH'
+  | 'BAD_DEFINITION';
+
+/** Per code: what happened, and what to do next. The throw site adds the detail (event type, version, column). */
+const MESSAGES: Record<JournalErrorCode, { readonly what: string; readonly next: string }> = {
+  CONFLICT: {
+    what: 'the row and its event history cannot accept this write',
+    next: 'If another writer appended first, run the command again on the current state. If the row and the history disagree, check with `verify`, and use `repair` only when the history is complete',
+  },
+  NO_ROW: {
+    what: 'no row exists, and this event has no `.create` reducer',
+    next: 'Create the entity first, or declare `.create` for this event on the entity',
+  },
+  ROW_EXISTS: {
+    what: 'a row exists, and this event has no `.on` reducer',
+    next: 'Write an update event instead, or declare `.on` for this event on the entity',
+  },
+  UNKNOWN_EVENT: {
+    what: 'the entity does not declare this event',
+    next: 'Add `.create(Event, ...)` or `.on(Event, ...)` for it on this entity, or write it to the entity that declares it',
+  },
+  VERSION_MISMATCH: {
+    what: 'no row matched the expected version when saving',
+    next: 'The row version changed, or the row was removed, after this write locked it. Look for a statement that does this outside the journal (for example a direct update or delete inside `events`), then run the command again',
+  },
+  NO_HISTORY: {
+    what: 'a complete history that starts at version 1 is not available',
+    next: 'Replay and repair cannot rebuild this row. Check whether the row existed before the journal, or restore the missing events',
+  },
+  HISTORY_GAP: {
+    what: 'the log has a hole, or the row is newer than a log that says it is alive',
+    next: 'An event was lost after it was written. Replay and repair refuse to build a row the real history never produced. Restore the missing event from a backup, or accept the row as it is',
+  },
+  REPLAY_FAILED: {
+    what: 'a stored event cannot be decoded or applied',
+    next: 'Check the event schema and the reducers against the stored history',
+  },
+  UNSTABLE_SCHEMA: {
+    what: 'the value changes or fails across JSON storage and a second parse',
+    next: 'Return JSON-compatible data that the schema accepts unchanged, because replay parses stored data again',
+  },
+  ID_MISMATCH: {
+    what: 'the entity id is not valid, or differs from its stored spelling',
+    next: 'Use a non-empty, well-formed id within the limit, spelled exactly as stored. A uuid must be lower-case and hyphenated',
+  },
+  VALUE_MISMATCH: {
+    what: 'the database stored a different value than the reducer produced',
+    next: 'The write was rolled back. Make the reducer produce the value in the form the column stores',
+  },
+  BAD_DEFINITION: {
+    what: 'a declaration is wrong',
+    next: 'Fix the declaration named in the detail. It is thrown when the module that declares it loads, so no data was touched',
+  },
+};
+
+/**
+ * An error about one entity's row or history: a write, replay, verify or repair
+ * that the journal refuses. Match on `code`, never on the message.
+ *
+ * Not every error the journal lets out is a `JournalError`:
+ * - A wrong definition is a `JournalError` with code `BAD_DEFINITION`, thrown when the
+ *   declaration runs (a bad name, a bad key column, a duplicate reducer or handler name).
+ * - A misuse at run time is a plain `Error` whose message starts with `journal:` (two
+ *   operations at once on one transaction, `drain` inside a transaction).
+ * - Command input, event data or `meta` that fails its schema is a `ZodError`.
+ * - An error thrown by a command handler, an `events` function, a reducer or a
+ *   projection passes through unchanged. A rejected business rule is one of
+ *   these: a `CommandError`, below.
+ * An error thrown by an effect is caught by `drain` and stored on the job.
+ */
+export class JournalError extends Error {
+  readonly code: JournalErrorCode;
+  readonly kind: string;
+  readonly entityId: string;
+
+  /** The message reads: `CODE: what happened (kind id): detail. What to do next.` */
+  constructor(code: JournalErrorCode, kind: string, entityId: string, detail?: string, options?: ErrorOptions) {
+    const { what, next } = MESSAGES[code];
+    const where = `${code}: ${what} (${kind} ${entityId})`;
+    const happened = detail === undefined ? where : `${where}: ${detail}`;
+    super(`${happened}. ${next}.`, options);
+    this.name = 'JournalError';
+    this.code = code;
+    this.kind = kind;
+    this.entityId = entityId;
+  }
+}
+
+export function isJournalError(error: unknown, code?: JournalErrorCode): error is JournalError {
+  return error instanceof JournalError && (code === undefined || error.code === code);
+}
+
+/** The kind of answer a rejected request gets. The names are the usual HTTP ones: 404, 400, 403, 409. */
+export type CommandErrorCode = 'NOT_FOUND' | 'BAD_REQUEST' | 'FORBIDDEN' | 'CONFLICT';
+
+/**
+ * A business rule rejected the request. App code throws it: a command handler,
+ * or the `events` function of a `write`. The code names the kind of answer and
+ * the message is written for the client.
+ *
+ * It is NOT a `JournalError`. A `JournalError` is the library's own failure: a
+ * row or a history it refuses. A `CommandError` is the app's rule saying no.
+ * The library never throws one and never changes one: like every error thrown
+ * by app code, it leaves `journal.run` as the same instance, after the
+ * command's transaction rolled back.
+ *
+ * Nothing here knows HTTP. The host maps the code to its own transport:
+ * `@arki/journal/orpc` does it for oRPC, and any other host matches on the
+ * code with `isCommandError`.
+ */
+export class CommandError extends Error {
+  readonly code: CommandErrorCode;
+
+  constructor(code: CommandErrorCode, message: string) {
+    super(message);
+    this.name = 'CommandError';
+    this.code = code;
+  }
+}
+
+export function isCommandError(error: unknown, code?: CommandErrorCode): error is CommandError {
+  return error instanceof CommandError && (code === undefined || error.code === code);
+}

package/src/event.ts

@@ -0,0 +1,26 @@
+import type { z } from 'zod';
+
+import type { EventDef, EventOptions, Pending, Upcaster } from './types.js';
+import { assertStoredName } from './id.js';
+
+/**
+ * Declare an event. Calling the result validates the data and returns a pending event.
+ * `opts.erased` gives the event's erased form for `forget`; see the README, Erasure.
+ * `opts.upcasters` lifts data stored under older schemas; see the README, Changing events later.
+ */
+export function defineEvent<T extends string, S extends z.ZodType, const U extends readonly z.ZodType[] = readonly []>(
+  type: T,
+  schema: S,
+  opts?: EventOptions<S, U>,
+): EventDef<T, S> {
+  assertStoredName('event type', type);
+  const upcasters: readonly Upcaster[] = opts?.upcasters ?? [];
+  const make = (data: z.input<S>): Pending<T, z.output<S>> => ({ type, data: schema.parse(data) });
+  return Object.assign(make, {
+    type,
+    schema,
+    version: upcasters.length + 1,
+    upcasters,
+    ...(opts?.erased === undefined ? {} : { erased: opts.erased }),
+  });
+}

package/src/fold.ts

@@ -0,0 +1,97 @@
+/**
+ * The fold that write and replay share: apply recorded events to a row in memory.
+ * Also the two lookups by event type. Pure functions: no database access, no state.
+ * May import `entity` and leaf files. Must not import `journal`, `api`, `write`,
+ * `command`, `history`, `storage` or `worker`.
+ */
+import type {
+  AnyEntity,
+  AnyEventDef,
+  EntityDef,
+  EntityId,
+  EntityTable,
+  Recorded,
+  RecordedOf,
+  ReducerRow,
+  ReducerValues,
+  Row,
+} from './types.js';
+import { reduceOne, withEntityIdentity } from './entity.js';
+import { JournalError } from './errors.js';
+
+type RecordedEvent<MetaOut> = Recorded<string, unknown, MetaOut>;
+
+export const findEventDefinition = <MetaOut>(
+  entities: readonly AnyEntity<MetaOut>[],
+  kind: string,
+  type: string,
+): AnyEventDef | undefined => entities.find(entity => entity.kind === kind)?.events.get(type);
+
+/**
+ * Fold events onto a starting state. A create event on a row, or a non-create
+ * event with no row, is `ROW_EXISTS` / `NO_ROW` during a write and
+ * `REPLAY_FAILED` when reading the log back. `recreated` is true when the state
+ * passed through `null` and ended non-null: the row is a new incarnation.
+ */
+export const fold = <Tbl extends EntityTable, Key extends string, MetaOut>(
+  entity: EntityDef<string, Tbl, AnyEventDef, MetaOut, Key>,
+  start: Row<Tbl> | null,
+  id: EntityId<Tbl, Key>,
+  history: readonly RecordedEvent<MetaOut>[],
+  mode: 'write' | 'replay',
+): {
+  readonly row: ReducerRow<Tbl, Key> | null;
+  readonly recreated: boolean;
+  /** The columns the reducers set in this fold (since the last create). */
+  readonly reducerColumns: ReadonlySet<string>;
+} => {
+  let state: Row<Tbl> | ReducerValues<Tbl, Key> | null = start;
+  let deleted = false;
+  const reducerColumns = new Set<string>();
+  for (const event of history) {
+    const reducers = entity.reducers.get(event.type);
+    // A write names the exact refusal. A replay reports each one as REPLAY_FAILED and says why.
+    const at = `event "${event.type}" at version ${event.version}`;
+    if (reducers === undefined) {
+      throw mode === 'write'
+        ? new JournalError('UNKNOWN_EVENT', entity.kind, id, at)
+        : new JournalError('REPLAY_FAILED', entity.kind, id, `${at} has no reducer on this entity`);
+    }
+    if (state !== null && reducers.on === undefined) {
+      throw mode === 'write'
+        ? new JournalError('ROW_EXISTS', entity.kind, id, at)
+        : new JournalError(
+            'REPLAY_FAILED',
+            entity.kind,
+            id,
+            `${at} has no .on reducer, but the history has a row at that point`,
+          );
+    }
+    if (state === null && reducers.create === undefined) {
+      throw mode === 'write'
+        ? new JournalError('NO_ROW', entity.kind, id, at)
+        : new JournalError(
+            'REPLAY_FAILED',
+            entity.kind,
+            id,
+            `${at} has no .create reducer, but the history has no row at that point`,
+          );
+    }
+    state = reduceOne(entity, state, id, event, reducerColumns);
+    if (state === null) deleted = true;
+  }
+  if (state === null) return { row: null, recreated: false, reducerColumns };
+  const last = history.at(-1);
+  const version = last === undefined ? (start === null ? 0 : start.version) : last.version;
+  return { row: withEntityIdentity(entity, state, id, version), recreated: deleted, reducerColumns };
+};
+
+/**
+ * Narrows a decoded event to the entity's own event union. It is a type guard, not
+ * a filter for bad data: `decodeStoredEvent` has already thrown for a type the
+ * entity does not declare. Do not use it to skip stored events that fail to decode.
+ */
+export const hasDeclaredEventType = <E extends AnyEventDef, Id extends string, MetaOut>(
+  entity: EntityDef<string, EntityTable, E, MetaOut, string>,
+  event: Recorded<string, unknown, MetaOut, Id>,
+): event is RecordedOf<E, MetaOut, Id> => entity.events.has(event.type);