@arki/journal 0.0.0-stage → 0.1.0

package/src/hooks.ts

@@ -0,0 +1,85 @@
+/**
+ * Around-hooks: the one way to extend a command run or an effect run from the
+ * outside. A hook receives the context and `next`, and runs inside the same
+ * transaction (commands) or lease (effects). The rules, all enforced here:
+ * `next` exactly once, or throw before it to stop; a rejection of `next` is the
+ * hook's rejection too; the context is frozen; hooks run in registration order,
+ * the first one outermost; registration is frozen once the journal has done work.
+ * Leaf file: may import `errors` only.
+ */
+import { JournalError } from './errors.js';
+
+/** A hook. `next` runs the rest of the chain and the work itself. It gives no result and takes no input. */
+export type Around<Ctx> = (ctx: Ctx, next: () => Promise<void>) => Promise<void>;
+
+/** What the app sees: register only. */
+export type HookPoint<Ctx> = {
+  /** Wrap every run. Throws `BAD_DEFINITION` once the journal has run a command, a drain or a worker. */
+  around(hook: Around<Ctx>): void;
+};
+
+export function createHookPoint<Ctx extends object>(what: 'command' | 'effect') {
+  const hooks: Around<Ctx>[] = [];
+  let frozen = false;
+
+  const point: HookPoint<Ctx> = {
+    around(hook) {
+      if (frozen) {
+        throw new JournalError(
+          'BAD_DEFINITION',
+          'hook',
+          what,
+          `journal: ${what} hooks are frozen once the journal has run a command, a drain or a worker; register hooks at boot, before any work`,
+        );
+      }
+      hooks.push(hook);
+    },
+  };
+
+  /** From now on, `around` throws. Called by the first `run` or `drain`. */
+  const freeze = (): void => {
+    frozen = true;
+  };
+
+  /** Run `work` inside every registered hook. The result is the work's own; no hook can change it. */
+  const run = async <T>(ctx: Ctx, work: () => Promise<T>): Promise<T> => {
+    if (hooks.length === 0) return work();
+    const frozenCtx = Object.freeze(ctx);
+    let result: { readonly value: T } | undefined;
+    const layer = async (index: number): Promise<void> => {
+      const hook = hooks[index];
+      if (hook === undefined) {
+        result = { value: await work() };
+        return;
+      }
+      let calls = 0;
+      let failure: { readonly error: unknown } | undefined;
+      const next = async (): Promise<void> => {
+        calls += 1;
+        if (calls > 1)
+          throw new Error(`journal: a ${what} hook called next twice; next runs the ${what} and may run once`);
+        try {
+          await layer(index + 1);
+        } catch (error) {
+          failure = { error };
+          throw error;
+        }
+      };
+      await hook(frozenCtx, next);
+      // A hook that swallowed the failure would turn a rolled-back command into a success for the caller.
+      if (failure !== undefined) throw failure.error;
+      if (calls === 0) {
+        throw new Error(
+          `journal: a ${what} hook returned without calling next; call next to run the ${what}, or throw to stop it`,
+        );
+      }
+    };
+    await layer(0);
+    if (result === undefined) throw new Error(`journal: the ${what} did not run`);
+    return result.value;
+  };
+
+  return { point, freeze, run };
+}
+
+export type HookPointInternal<Ctx extends object> = ReturnType<typeof createHookPoint<Ctx>>;

package/src/id.ts

@@ -0,0 +1,54 @@
+import { createId } from '@paralleldrive/cuid2';
+
+import { JournalError } from './errors.js';
+
+/**
+ * Same shape as `createPrefixedId` in `@arki/db/id`. That module is not
+ * imported because its value export pulls `drizzle-orm/pg-core` and
+ * `@arki/contracts` into browser bundles.
+ */
+const prefixed = <P extends string>(prefix: P): `${P}${string}` => `${prefix}${createId()}`;
+
+export const eventId = () => prefixed('evt_');
+export const jobId = () => prefixed('job_');
+export const commandId = () => prefixed('cmd_');
+export const correlationId = () => prefixed('cor_');
+export const leaseToken = () => createId();
+
+const NAME_KINDS = {
+  'entity kind': 64,
+  'event type': 128,
+  'effect name': 128,
+} as const;
+
+/**
+ * Throws unless `name` fits the `varchar` column the journal stores it in: non-empty,
+ * well-formed UTF-16 (a lone surrogate would be stored as U+FFFD and alias another name),
+ * and at most the column length in code points. Hermes-safe: no `isWellFormed`, no lookbehind.
+ */
+export function assertStoredName(what: keyof typeof NAME_KINDS, name: string): void {
+  const limit = NAME_KINDS[what];
+  const shown = JSON.stringify(name);
+  if (name === '') throw new JournalError('BAD_DEFINITION', what, shown, `journal: ${what} must not be empty`);
+  let length = 0;
+  for (const ch of name) {
+    const point = ch.codePointAt(0);
+    if (point !== undefined && point >= 55_296 && point <= 57_343) {
+      throw new JournalError(
+        'BAD_DEFINITION',
+        what,
+        shown,
+        `journal: ${what} ${shown} has an unpaired surrogate; the database would store it as U+FFFD`,
+      );
+    }
+    length++;
+  }
+  if (length > limit) {
+    throw new JournalError(
+      'BAD_DEFINITION',
+      what,
+      shown,
+      `journal: ${what} ${shown} is ${length} characters; the limit is ${limit}`,
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+export { initJournal } from './journal.js';
+export { need } from './handlers.js';
+export type {
+  Command,
+  CommandContext,
+  CommandRunner,
+  Journal,
+  JournalDefinitions,
+  ReplayResult,
+  RootCommandRunner,
+  RunOptions,
+  CallOptions,
+  VerifyResult,
+  ForgetResult,
+  NextEvents,
+  WriteInput,
+  WriteOptions,
+  WriteResult,
+} from './api.js';
+export { CommandError, JournalError, isCommandError, isJournalError } from './errors.js';
+export type { CommandErrorCode, JournalErrorCode } from './errors.js';
+export type { GuaranteedCreateKeys, EntityBuilder, OnReducerRow, OnOnlyEntityBuilder } from './entity.js';
+export type {
+  AnyEntity,
+  AnyEventDef,
+  CreateReducer,
+  DbHandle,
+  Effect,
+  EffectContext,
+  EffectHandlers,
+  EntityDef,
+  EntityId,
+  EntityIdOf,
+  EntityInfo,
+  EntityTable,
+  EventDef,
+  EventOptions,
+  Upcaster,
+  UpcasterSteps,
+  ProjectionOptions,
+  Tap,
+  TapContext,
+  TapHandlers,
+  Unlisten,
+  WakeListener,
+  CommandHookContext,
+  EffectHookContext,
+  EventsOf,
+  IdTable,
+  KeyColumn,
+  Need,
+  Needed,
+  Needs,
+  ReducerValues,
+  OnReducer,
+  Patch,
+  Pending,
+  PendingOf,
+  Projection,
+  ProjectionHandlers,
+  Recorded,
+  RecordedOf,
+  Reducers,
+  ReducerRow,
+  RootDb,
+  Row,
+  Services,
+  ServicesFor,
+  TransactionSource,
+  JournalWorker,
+  StrandedJobs,
+} from './types.js';
+export type { JournalTables } from './pg.js';
+export type { Around, HookPoint } from './hooks.js';
+export { listenOnPool } from './listen.js';
+export type { ListenClient, ListenPool } from './listen.js';

package/src/journal.ts

@@ -0,0 +1,256 @@
+/**
+ * The entry point: `initJournal`, the definition helpers it returns, and
+ * `createJournal`, which checks the handlers, builds each part with its
+ * dependencies and wires the public methods.
+ * May import every other file. No implementation file may import this one.
+ */
+import { getTableColumns, getTableName, is, lt } from 'drizzle-orm';
+import { getTableConfig, PgColumn } from 'drizzle-orm/pg-core';
+import { z } from 'zod';
+
+import type { Journal, JournalDefinitions, RootCommandRunner } from './api.js';
+import type { EntityBuilder } from './entity.js';
+import type { JournalTables } from './pg.js';
+import type {
+  AnyEntity,
+  CommandHookContext,
+  DbHandle,
+  Effect,
+  EffectHookContext,
+  EntityTable,
+  IdTable,
+  KeyName,
+  Projection,
+  RootDb,
+  SingleKey,
+  Tap,
+  TransactionSource,
+} from './types.js';
+import { createCommandRunner } from './command.js';
+import { defineEntity } from './entity.js';
+import { JournalError } from './errors.js';
+import { defineEvent } from './event.js';
+import { bindEffect, bindTap, defineProjection, effectFor, tapFor } from './handlers.js';
+import { createHistory } from './history.js';
+import { createHookPoint } from './hooks.js';
+import {
+  createAdmin,
+  createCatchUp,
+  createDrain,
+  createStrandedJobs,
+  createTapDispatch,
+  createWorkers,
+} from './worker.js';
+import { createWriter } from './write.js';
+
+const emptyMeta = z.object({});
+type EmptyMeta = typeof emptyMeta;
+
+function initFor<Tx extends TransactionSource<Tx>, AppDb extends RootDb>() {
+  function init(): JournalDefinitions<EmptyMeta, Tx, AppDb>;
+  function init<Meta extends z.ZodObject>(options: { readonly meta: Meta }): JournalDefinitions<Meta, Tx, AppDb>;
+  function init<Meta extends z.ZodObject>(options?: {
+    readonly meta?: Meta;
+  }): JournalDefinitions<Meta, Tx, AppDb> | JournalDefinitions<EmptyMeta, Tx, AppDb> {
+    return options?.meta === undefined
+      ? createInit<EmptyMeta, Tx, AppDb>(emptyMeta)
+      : createInit<Meta, Tx, AppDb>(options.meta);
+  }
+  return init;
+}
+
+/**
+ * `initJournal({ meta })` types `write`'s `tx`, `events`' `{ tx }` and
+ * projection handlers with the structural `DbHandle`. `initJournal.tx<AppTx>()
+ * .create({ meta })` uses the app's own Drizzle transaction type instead, so
+ * repositories typed against it fit. `initJournal.db<AppDb>()` names the
+ * app's root database type: effects get it as `ctx.db`, and `drain` and
+ * `worker` then need it. Both are type-only steps and chain in either order.
+ */
+export const initJournal = Object.assign(initFor<DbHandle, RootDb>(), {
+  tx: <Tx extends TransactionSource<Tx>>() => ({
+    create: initFor<Tx, RootDb>(),
+    db: <AppDb extends RootDb>() => ({ create: initFor<Tx, AppDb>() }),
+  }),
+  db: <AppDb extends RootDb>() => ({
+    create: initFor<DbHandle, AppDb>(),
+    tx: <Tx extends TransactionSource<Tx>>() => ({ create: initFor<Tx, AppDb>() }),
+  }),
+});
+
+/** A table with a column called `id`. The check is real; the guard narrows to `IdTable`. */
+function hasIdColumn<Tbl extends EntityTable>(table: Tbl): table is Tbl & IdTable {
+  const columns: Record<string, unknown> = getTableColumns(table);
+  return is(columns.id, PgColumn);
+}
+
+function createInit<Meta extends z.ZodObject, Tx extends TransactionSource<Tx>, AppDb extends RootDb>(
+  metaSchema: Meta,
+): JournalDefinitions<Meta, Tx, AppDb> {
+  type MetaOut = z.output<Meta>;
+  function entity<K extends string, Tbl extends IdTable>(
+    kind: K,
+    table: Tbl,
+  ): EntityBuilder<K, Tbl, never, MetaOut, 'id'>;
+  function entity<K extends string, Tbl extends EntityTable, Key extends KeyName<Tbl>>(
+    kind: K,
+    table: Tbl,
+    options: { readonly key: Key & SingleKey<Key> },
+  ): EntityBuilder<K, Tbl, never, MetaOut, Key>;
+  function entity<K extends string, Tbl extends EntityTable>(kind: K, table: Tbl, options?: { readonly key: string }) {
+    if (options !== undefined) {
+      return defineEntity<K, Tbl, MetaOut, string>(kind, table, options.key);
+    }
+    if (!hasIdColumn(table)) {
+      throw new JournalError(
+        'BAD_DEFINITION',
+        'entity',
+        kind,
+        `journal: entity "${kind}": table "${getTableName(table)}" has no "id" column; pass { key: 'columnName' }`,
+      );
+    }
+    return defineEntity<K, Tbl, MetaOut, 'id'>(kind, table, 'id');
+  }
+  return {
+    event: defineEvent,
+    entity,
+    command: (name, input, handler) => ({ name, input, handler }),
+    projection: (name, entity, on, opts) => defineProjection(name, entity, on, opts),
+    effect: effectFor<MetaOut, AppDb, RootCommandRunner<Meta, Tx>>(),
+    tap: tapFor<MetaOut, AppDb>(),
+    compose: config => {
+      const effects = (config.effects ?? []).map(effect => bindEffect(effect, config.services ?? {}));
+      const taps = (config.taps ?? []).map(tap => bindTap(tap, config.services ?? {}));
+      return createJournal<Meta, Tx, AppDb>(metaSchema, config.tables, config.projections ?? [], effects, taps);
+    },
+  };
+}
+
+/** Throws when two handlers of one kind share a name: the second would silently replace the first. */
+function assertUniqueNames(
+  kind: 'effect' | 'projection' | 'tap',
+  handlers: readonly { readonly name: string }[],
+): void {
+  const seen = new Set<string>();
+  for (const { name } of handlers) {
+    if (seen.has(name))
+      throw new JournalError('BAD_DEFINITION', kind, name, `journal: duplicate ${kind} name "${name}"`);
+    seen.add(name);
+  }
+}
+
+function createJournal<Meta extends z.ZodObject, Tx extends TransactionSource<Tx>, AppDb extends RootDb>(
+  metaSchema: Meta,
+  tables: JournalTables,
+  projections: readonly Projection<z.output<Meta>, Tx>[],
+  effects: readonly Effect<z.output<Meta>, AppDb, RootCommandRunner<Meta, Tx>>[],
+  taps: readonly Tap<z.output<Meta>, AppDb>[] = [],
+): Journal<Meta, Tx, AppDb> {
+  assertUniqueNames('tap', taps);
+  const eventsSchema = getTableConfig(tables.events).schema;
+  const wakeChannel = eventsSchema === undefined ? 'journal_wake' : `${eventsSchema}_journal_wake`;
+  type MetaOut = z.output<Meta>;
+
+  assertUniqueNames('effect', effects);
+  assertUniqueNames('projection', projections);
+  const entitiesByKind = new Map<string, AnyEntity<MetaOut>>();
+  for (const handler of [...projections, ...effects]) {
+    for (const entity of handler.entities) entitiesByKind.set(entity.kind, entity);
+  }
+
+  // `journal.drain`, `journal.wake` and `journal.run` are read from the journal object on each
+  // call, so the worker loop, `run`, a bound runner and an effect's `ctx.run` always use the methods the object holds.
+  const history = createHistory<Meta>({ metaSchema, tables });
+  const inlineProjections = projections.filter(projection => projection.lane === 'inline');
+  const asyncProjections = projections.filter(projection => projection.lane === 'async');
+  const { write, adopt, writeWithValidatedMeta } = createWriter<Meta, Tx>({
+    metaSchema,
+    tables,
+    projections: inlineProjections,
+    asyncProjections,
+    effects,
+    history,
+    wakeChannel,
+  });
+  const commandHooks = createHookPoint<CommandHookContext<z.output<Meta>>>('command');
+  const effectHooks = createHookPoint<EffectHookContext<z.output<Meta>>>('effect');
+  const run = createCommandRunner<Meta, Tx>({
+    metaSchema,
+    writeWithValidatedMeta,
+    wake: () => journal.wake(),
+    hooks: commandHooks,
+    tables,
+  });
+  // The worker's database is also the source of every command an effect runs, so it opens `Tx`.
+  type WorkerDb = AppDb & TransactionSource<Tx>;
+  const drain = createDrain<Meta, WorkerDb, RootCommandRunner<Meta, Tx>>({
+    tables,
+    hooks: effectHooks,
+    effects,
+    history,
+    runOn: (db, cause) => (command, input, meta, call) => run(db, command, input, meta, call, cause),
+  });
+  const catching = createCatchUp<Meta, Tx>({ tables, projections: asyncProjections, history });
+  const dispatch = createTapDispatch<Meta, WorkerDb>({ tables, taps, history });
+  const workers = createWorkers<WorkerDb>({
+    drain: (db, opts) => journal.drain(db, opts),
+    catchUp: (db, opts) => journal.catchUp(db, opts),
+    dispatch,
+    tapNames: taps.map(tap => tap.name),
+  });
+  const strandedJobs = createStrandedJobs({ tables, effectNames: effects.map(effect => effect.name) });
+  const admin = createAdmin({ tables, wake: () => journal.wake() });
+
+  const journal: Journal<Meta, Tx, AppDb> = {
+    write: (tx, entity, id, input) => write(tx, entity, id, input),
+    adopt: (tx, entity, id, input) => adopt(tx, entity, id, input),
+    run: (source, command, input, meta, opts) => run(source, command, input, meta, opts),
+    bind: (source, meta, opts) => (command, input, call) =>
+      journal.run(source, command, input, meta, { ...opts, ...call }),
+    replay: (db, entity, id, opts) => history.replay(db, entity, id, opts),
+    verify: (db, entity, id) => history.verify(db, entity, id),
+    repair: (db, entity, id) => history.repair(db, entity, id),
+    forget: (db, entity, id) => history.forget(db, entity, id),
+    pruneReceipts: async (db, opts) => {
+      const gone = await db
+        .delete(tables.receipts)
+        .where(lt(tables.receipts.recordedAt, opts.before))
+        .returning({ key: tables.receipts.key });
+      return gone.length;
+    },
+    rerun: (db, projection, opts) => {
+      if (projection.lane === 'async')
+        throw new JournalError(
+          'BAD_DEFINITION',
+          'projection',
+          projection.name,
+          `journal: projection "${projection.name}" is async; use reset and catchUp instead of rerun`,
+        );
+      return history.rerun(db, projection, opts);
+    },
+    catchUp: (db, opts) => catching.catchUp(db, opts),
+    reset: (db, projection, clear) => catching.reset(db, projection, clear),
+    cursors: db => catching.cursors(db),
+    drain: (db, opts) => drain(db, opts),
+    worker: (db, opts) => workers.worker(db, opts),
+    wake: () => workers.wakeAll(),
+    strandedJobs: db => strandedJobs(db),
+    jobs: (db, opts) => admin.jobs(db, opts),
+    retry: (db, jobId) => admin.retry(db, jobId),
+    discard: (db, jobId) => admin.discard(db, jobId),
+    wakeChannel,
+    hooks: { command: commandHooks.point, effect: effectHooks.point },
+    catalog: {
+      entities: [...entitiesByKind.values()].map(entity => ({
+        kind: entity.kind,
+        table: getTableName(entity.table),
+        events: [...entity.events.keys()],
+      })),
+      projections: projections.map(projection => projection.name),
+      effects: effects.map(effect => effect.name),
+      taps: taps.map(tap => tap.name),
+    },
+  };
+
+  return journal;
+}

package/src/listen.ts

@@ -0,0 +1,109 @@
+/**
+ * `listenOnPool`: the `WakeListener` for a `pg` pool. It borrows one client from
+ * the pool for as long as the worker runs, `LISTEN`s on the channel, and forwards
+ * each payload. A dropped connection is released and replaced after `retryMs`;
+ * notifications sent while it was gone are lost, which taps accept and polling
+ * covers for jobs. Typed by shape, so this file imports no driver.
+ * Leaf file: may import `debug` and `types` only.
+ */
+import type { WakeListener } from './types.js';
+import { debugWorker } from './debug.js';
+
+/**
+ * Let the process exit while this timer waits. Node and Bun return a timer object
+ * with `unref`; browsers, Deno's web API and Hermes return a number, which never
+ * holds a process open, so there is nothing to do.
+ */
+export function unrefTimer(timer: unknown): void {
+  if (typeof timer === 'object' && timer !== null && 'unref' in timer && typeof timer.unref === 'function')
+    timer.unref();
+}
+
+/** The part of a `pg` pool client a listener uses. */
+export type ListenClient = {
+  query(text: string): Promise<unknown>;
+  on(
+    event: 'notification',
+    listener: (message: { readonly channel: string; readonly payload?: string }) => void,
+  ): unknown;
+  on(event: 'error', listener: (error: Error) => void): unknown;
+  release(error?: Error | boolean): void;
+};
+
+/** The part of a `pg` pool a listener uses: `new pg.Pool(...)`, or a Drizzle node-postgres database's `$client`. */
+export type ListenPool = { connect(): Promise<ListenClient> };
+
+/**
+ * Hear `channel` on a dedicated client of `pool`: `journal.worker(db, { listen: listenOnPool(db.$client, journal.wakeChannel) })`.
+ * The first connection is made when the worker starts; if it fails, `start()` rejects.
+ */
+export function listenOnPool(pool: ListenPool, channel: string, opts?: { readonly retryMs?: number }): WakeListener {
+  const retryMs = opts?.retryMs ?? 1000;
+  const quoted = `"${channel.replaceAll('"', '""')}"`;
+  return async onMessage => {
+    let stopped = false;
+    let current: ListenClient | undefined;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+
+    const connect = async (): Promise<void> => {
+      const client = await pool.connect();
+      let released = false;
+      const drop = (error?: Error) => {
+        if (released) return;
+        released = true;
+        if (current === client) current = undefined;
+        client.release(error ?? true);
+      };
+      client.on('notification', message => {
+        if (message.channel === channel && message.payload !== undefined) onMessage(message.payload);
+      });
+      client.on('error', error => {
+        debugWorker.debug('listen {channel}: connection lost: {lost}', { channel, lost: error.message });
+        drop(error);
+        schedule();
+      });
+      try {
+        await client.query(`LISTEN ${quoted}`);
+      } catch (error) {
+        drop(error instanceof Error ? error : new Error(String(error)));
+        throw error;
+      }
+      if (stopped) {
+        drop();
+        return;
+      }
+      current = client;
+      debugWorker.debug('listen {channel}: connected', { channel });
+    };
+
+    const schedule = (): void => {
+      if (stopped || timer !== undefined) return;
+      timer = setTimeout(() => {
+        timer = undefined;
+        connect().catch((error: unknown) => {
+          debugWorker.debug('listen {channel}: reconnect failed', {
+            channel,
+            error: error instanceof Error ? error.message : String(error),
+          });
+          schedule();
+        });
+      }, retryMs);
+      unrefTimer(timer);
+    };
+
+    await connect();
+    return async () => {
+      stopped = true;
+      if (timer !== undefined) clearTimeout(timer);
+      const client = current;
+      current = undefined;
+      if (client === undefined) return;
+      try {
+        await client.query(`UNLISTEN ${quoted}`);
+        client.release();
+      } catch (error) {
+        client.release(error instanceof Error ? error : true);
+      }
+    };
+  };
+}

package/src/orpc.ts

@@ -0,0 +1,59 @@
+/**
+ * `@orpc/server` adapter: what an oRPC client sees when a command fails.
+ *
+ * - `toORPCError(error)` maps one error.
+ * - `commandErrors()` is the middleware that maps whatever a procedure throws.
+ *
+ * `@orpc/server` is an optional peer. Import this module only in an app that
+ * serves oRPC. May import `errors` only; this is the one file that may import
+ * `@orpc/server`.
+ */
+import { ORPCError, os } from '@orpc/server';
+
+import { CommandError, isJournalError } from './errors.js';
+
+/**
+ * Another request changed the same entity first, or the client's `expectedVersion`
+ * is behind. Nothing was written. Repeating the same request as it stands fails
+ * again when a version was given, so the client reloads first. The journal's own
+ * message names the entity kind and id; the client does not get those.
+ */
+const CONFLICT_MESSAGE = 'This was changed by another request. Reload the current state and try again.';
+
+/**
+ * - A `CommandError` becomes the `ORPCError` with the same code and message.
+ * - A `JournalError` with code `CONFLICT` becomes an `ORPCError('CONFLICT')`, a 409 the client can retry.
+ * - Anything else is returned unchanged: the app decides what it means.
+ *
+ * The original error is NOT attached as `cause`. The journal's message names the entity kind and
+ * id, and a host may log or serialize a cause. A host that wants the original logs it itself,
+ * in a middleware placed inside this one.
+ */
+export function toORPCError(error: unknown): unknown {
+  if (error instanceof CommandError) {
+    return new ORPCError(error.code, { message: error.message });
+  }
+  if (isJournalError(error, 'CONFLICT')) {
+    return new ORPCError('CONFLICT', { message: CONFLICT_MESSAGE });
+  }
+  return error;
+}
+
+/**
+ * The middleware form of `toORPCError`. Add it once to the app's procedure
+ * builders, and no procedure needs a try/catch around a command.
+ *
+ * Order: put it INSIDE the app's own error middleware, so after it in the
+ * chain: `os.use(appErrors).use(commandErrors())`. A rejected rule is then
+ * already an `ORPCError` when the app's middleware sees it, and passes. Placed
+ * before it, the app's middleware sees a plain error first and answers 500.
+ */
+export function commandErrors() {
+  return os.middleware(async ({ next }) => {
+    try {
+      return await next();
+    } catch (error) {
+      throw toORPCError(error);
+    }
+  });
+}