@affordance/core 0.1.0 → 0.2.0

package/dist/ingestion/ingest.d.ts

@@ -5,10 +5,9 @@
  * them has to be visible afterwards:
  *
  * 1. **Dedup.** Providers retry; "at least once" is the delivery guarantee
- *    every one of them offers. The gate is a unique insert into
- *    `ingested_events` — not a lookup-then-insert, which races itself — so
- *    three concurrent deliveries of one event produce exactly one Execution
- *    and two `duplicate` results.
+ *    every one of them offers. Storage atomically acquires a delivery, so
+ *    concurrent deliveries of one event produce one Execution and the
+ *    remaining callers receive `duplicate`.
  * 2. **Correlate.** The external identifier is resolved to (case, scope,
  *    step) through the registry the initiating handler wrote.
  * 3. **Execute.** Through the ordinary claim → run → commit, with the
@@ -21,9 +20,8 @@
  * surface. "The webhook definitely arrived, so why is the case still waiting"
  * is a question this table answers without anyone reading a log file.
  */
-import type { DeadLetterReason as ContractDeadLetterReason, IngestionStatus as ContractIngestionStatus } from '@affordance/contract';
+import type { AffordanceErrorCode } from '../errors.js';
 import type { ExecutionEnvironment, ExecutionResult, SystemSettled } from '../execution/index.js';
-import type { Queryable } from '../store/index.js';
 import type { Correlation } from './correlation.js';
 /** An event as an external system delivered it. */
 export interface ExternalEvent {
@@ -48,10 +46,9 @@ export interface ExternalEvent {
  * How an ingested event ended up: `executed` (the target step ran and
  * committed), `duplicate` (already seen — this delivery changed nothing, by
  * design), or `dead-lettered` (nothing could be done with it, and it is
- * sitting in the dead-letter surface). Wire vocabulary, so the contract
- * declares it and this is the same closed set.
+ * sitting in the dead-letter surface).
  */
-export type IngestionStatus = ContractIngestionStatus;
+export type IngestionStatus = 'executed' | 'duplicate' | 'dead-lettered';
 /**
  * Why an event was dead-lettered — the operator's first question, answered.
  *
@@ -60,10 +57,9 @@ export type IngestionStatus = ContractIngestionStatus;
  * names a step); every other reason **is** the `AffordanceErrorCode`
  * the refused Execution already declared at its raise site. Ingestion does
  * not re-derive the kind of a Refusal — it projects the code the error
- * carries, so a new refusal class can never misroute here. Wire vocabulary,
- * declared once by the contract; this is the same closed set.
+ * carries, so a new refusal class can never misroute here.
  */
-export type DeadLetterReason = ContractDeadLetterReason;
+export type DeadLetterReason = 'unrouted' | 'no-step' | AffordanceErrorCode;
 /**
  * Whether a provider redelivery of the same event deserves another attempt.
  *
@@ -142,7 +138,7 @@ export interface IngestionSettings {
  * of them — named here so that contract is a type, not a coincidence of an
  * object literal.
  */
-export interface IngestionEnvironment extends ExecutionEnvironment {
+export interface IngestionEnvironment<TCommit = unknown> extends ExecutionEnvironment<TCommit> {
     readonly ingestion: IngestionSettings;
 }
 export declare const externalActor: (event: ExternalEvent) => ExternalActor;
@@ -180,7 +176,7 @@ export declare const routedStep: (event: {
  * succeed. Infrastructure failures (the database is gone) do still throw,
  * because those the caller must not acknowledge.
  */
-export declare const ingest: (env: IngestionEnvironment, event: ExternalEvent) => Promise<IngestionResult>;
+export declare const ingest: <TCommit>(env: IngestionEnvironment<TCommit>, event: ExternalEvent) => Promise<IngestionResult>;
 /**
  * Project a settled system run onto the reason an operator needs to see —
  * the one place that asks whether what settled was a Refusal.
@@ -192,5 +188,3 @@ export declare const ingest: (env: IngestionEnvironment, event: ExternalEvent) =
  * silently dropped, with the crash's own words as the detail.
  */
 export declare const classifyDeadLetter: (ran: SystemSettled) => [DeadLetterReason, string];
-/** Read the dead-letter surface, newest first — the ops view of "arrived, did nothing". */
-export declare const readDeadLetters: (db: Queryable, filter?: DeadLetterFilter) => Promise<readonly DeadLetter[]>;

package/dist/ingestion/ingest.js

@@ -5,10 +5,9 @@
  * them has to be visible afterwards:
  *
  * 1. **Dedup.** Providers retry; "at least once" is the delivery guarantee
- *    every one of them offers. The gate is a unique insert into
- *    `ingested_events` — not a lookup-then-insert, which races itself — so
- *    three concurrent deliveries of one event produce exactly one Execution
- *    and two `duplicate` results.
+ *    every one of them offers. Storage atomically acquires a delivery, so
+ *    concurrent deliveries of one event produce one Execution and the
+ *    remaining callers receive `duplicate`.
  * 2. **Correlate.** The external identifier is resolved to (case, scope,
  *    step) through the registry the initiating handler wrote.
  * 3. **Execute.** Through the ordinary claim → run → commit, with the
@@ -24,9 +23,6 @@
 import { createHash } from 'node:crypto';
 import { isAffordanceError } from '../errors.js';
 import { runAsSystem } from '../execution/index.js';
-import { FRAMEWORK_SCHEMA, mintId, queryableOf, sqlWhere, } from '../store/index.js';
-import { lookupCorrelation } from './correlation.js';
-const EVENTS = `${FRAMEWORK_SCHEMA}.ingested_events`;
 /**
  * Whether a provider redelivery of the same event deserves another attempt.
  *
@@ -83,71 +79,17 @@ export const idempotencyKeyFor = (event) => {
             .slice(0, 32);
     return `${event.system}/${event.externalId}/${event.type}/${tail}`;
 };
-/**
- * The dedup gate. Inserts the event's row and reports whether this delivery
- * is the one that got it.
- *
- * `on conflict do nothing` is the whole mechanism: exactly one of N
- * concurrent deliveries inserts, and the losers read what the winner wrote.
- * A previous delivery that ended `dead-lettered` for a *transient* reason is
- * reopened rather than deduplicated — a provider retry after "the case was
- * busy" should get its chance, which is precisely what provider retries are
- * for.
- */
-const claimDelivery = async (db, event, idempotencyKey) => {
-    const inserted = await db.query(`insert into ${EVENTS} (id, system, external_id, type, idempotency_key, status, event)
-     values ($1, $2, $3, $4, $5, 'pending', $6::jsonb)
-     on conflict (idempotency_key) do nothing
-     returning *`, [
-        mintId('event'),
-        event.system,
-        event.externalId,
-        event.type,
-        idempotencyKey,
-        JSON.stringify(event),
-    ]);
-    const row = inserted.rows[0];
-    if (row)
-        return { row, fresh: true };
-    const retried = await db.query(`update ${EVENTS}
-     set status = 'pending', reason = null, detail = null, received_at = now(), event = $2::jsonb
-     where idempotency_key = $1 and status = 'dead-lettered' and reason = any($3)
-     returning *`, [idempotencyKey, JSON.stringify(event), REOPENABLE]);
-    const reopened = retried.rows[0];
-    if (reopened)
-        return { row: reopened, fresh: true };
-    const existing = await db.query(`select * from ${EVENTS} where idempotency_key = $1`, [idempotencyKey]);
-    const previous = existing.rows[0];
-    if (!previous)
-        throw new Error(`${EVENTS}: delivery neither inserted nor found — key ${idempotencyKey}`);
-    return { row: previous, fresh: false };
-};
-/** Record how a delivery ended. The row is the dead-letter surface, so this is the only settle path. */
-const settle = async (db, id, fields) => {
-    await db.query(`update ${EVENTS}
-     set status = $2, case_id = $3, scope_key = $4, step = $5, reason = $6, detail = $7, execution_id = $8
-     where id = $1`, [
-        id,
-        fields.status,
-        fields.caseId ?? null,
-        fields.scopeKey ?? null,
-        fields.step ?? null,
-        fields.reason ?? null,
-        fields.detail ?? null,
-        fields.executionId ?? null,
-    ]);
-};
 const result = (row, status, extra = {}) => ({
     id: row.id,
     status,
     system: row.system,
-    externalId: row.external_id,
-    idempotencyKey: row.idempotency_key,
+    externalId: row.externalId,
+    idempotencyKey: row.idempotencyKey,
     correlation: null,
     execution: null,
     reason: null,
     detail: null,
-    receivedAt: row.received_at.toISOString(),
+    receivedAt: row.receivedAt,
     ...extra,
 });
 /**
@@ -167,19 +109,18 @@ export const routedStep = (event, correlation) => event.step ?? correlation.step
  * because those the caller must not acknowledge.
  */
 export const ingest = async (env, event) => {
-    const db = queryableOf(env.db);
     const idempotencyKey = idempotencyKeyFor(event);
-    const { row, fresh } = await claimDelivery(db, event, idempotencyKey);
+    const { row, fresh } = await env.storage.deliveries.acquire(event, idempotencyKey, REOPENABLE);
     if (!fresh) {
         return result(row, 'duplicate', {
-            reason: row.reason ?? null,
-            detail: `already ingested as ${row.status} at ${row.received_at.toISOString()}`,
+            reason: row.reason,
+            detail: `already ingested as ${row.status} at ${row.receivedAt}`,
         });
     }
     // Settle the row and answer the caller with the same reason/detail pair —
     // one helper, so a branch cannot record one thing and report another.
     const deadLetter = async (fields) => {
-        await settle(db, row.id, {
+        await env.storage.deliveries.settle(row.id, {
             status: 'dead-lettered',
             reason: fields.reason,
             detail: fields.detail,
@@ -197,7 +138,7 @@ export const ingest = async (env, event) => {
             }),
         });
     };
-    const correlation = await lookupCorrelation(db, event.system, event.externalId);
+    const correlation = await env.storage.correlations.lookup(event.system, event.externalId);
     if (correlation === null) {
         return deadLetter({
             reason: 'unrouted',
@@ -218,7 +159,7 @@ export const ingest = async (env, event) => {
         ...(event.payload !== undefined && { input: event.payload }),
     });
     if (ran.outcome === 'committed') {
-        await settle(db, row.id, {
+        await env.storage.deliveries.settle(row.id, {
             status: 'executed',
             caseId: correlation.caseId,
             scopeKey: correlation.scopeKey,
@@ -243,33 +184,4 @@ export const ingest = async (env, event) => {
 export const classifyDeadLetter = (ran) => isAffordanceError(ran.error)
     ? [ran.error.code, ran.error.message]
     : ['execution-failed', ran.error.message];
-const toDeadLetter = (row) => ({
-    id: row.id,
-    system: row.system,
-    externalId: row.external_id,
-    type: row.type,
-    idempotencyKey: row.idempotency_key,
-    caseId: row.case_id,
-    scopeKey: row.scope_key,
-    step: row.step,
-    reason: row.reason,
-    detail: row.detail,
-    event: row.event,
-    receivedAt: row.received_at.toISOString(),
-});
-/** Read the dead-letter surface, newest first — the ops view of "arrived, did nothing". */
-export const readDeadLetters = async (db, filter = {}) => {
-    const { conditions, values, bind, where } = sqlWhere([
-        `status = 'dead-lettered'`,
-    ]);
-    if (filter.system !== undefined)
-        conditions.push(`system = ${bind(filter.system)}`);
-    if (filter.caseId !== undefined)
-        conditions.push(`case_id = ${bind(filter.caseId)}`);
-    if (filter.reason !== undefined)
-        conditions.push(`reason = ${bind(filter.reason)}`);
-    const limit = filter.limit === undefined ? '' : ` limit ${bind(filter.limit)}`;
-    const { rows } = await db.query(`select * from ${EVENTS} where ${where()} order by received_at desc${limit}`, values);
-    return rows.map(toDeadLetter);
-};
 //# sourceMappingURL=ingest.js.map

package/dist/ingestion/ingest.js.map

@@ -1 +1 @@
-{"version":3,"file":"ingest.js","sourceRoot":"","sources":["../../src/ingestion/ingest.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Ingestion: external events become Executions.\n *\n * A webhook arrives. Three things have to happen, in this order, and each of\n * them has to be visible afterwards:\n *\n * 1. **Dedup.** Providers retry; \"at least once\" is the delivery guarantee\n *    every one of them offers. The gate is a unique insert into\n *    `ingested_events` — not a lookup-then-insert, which races itself — so\n *    three concurrent deliveries of one event produce exactly one Execution\n *    and two `duplicate` results.\n * 2. **Correlate.** The external identifier is resolved to (case, scope,\n *    step) through the registry the initiating handler wrote.\n * 3. **Execute.** Through the ordinary claim → run → commit, with the\n *    external system as the journaled actor. Ingestion has no privileged\n *    path: the guard still decides, transactionally.\n *\n * What is *not* allowed is a quiet drop. An event nothing can route, an event\n * whose step the guard refuses, an event whose case is busy — each lands in\n * the same table with a status and a reason, which is the dead-letter\n * surface. \"The webhook definitely arrived, so why is the case still waiting\"\n * is a question this table answers without anyone reading a log file.\n */\n\nimport { createHash } from 'node:crypto'\nimport type {\n  DeadLetterReason as ContractDeadLetterReason,\n  IngestionStatus as ContractIngestionStatus,\n} from '@affordance/contract'\nimport { isAffordanceError } from '../errors.js'\nimport type {\n  ExecutionEnvironment,\n  ExecutionResult,\n  SystemSettled,\n} from '../execution/index.js'\nimport { runAsSystem } from '../execution/index.js'\nimport type { Queryable } from '../store/index.js'\nimport {\n  FRAMEWORK_SCHEMA,\n  mintId,\n  queryableOf,\n  sqlWhere,\n} from '../store/index.js'\nimport type { Correlation } from './correlation.js'\nimport { lookupCorrelation } from './correlation.js'\n\nconst EVENTS = `${FRAMEWORK_SCHEMA}.ingested_events`\n\n/** An event as an external system delivered it. */\nexport interface ExternalEvent {\n  /** The system that emitted it, matching the correlation's `system`. */\n  readonly system: string\n  /** The identifier that routes it — the one the initiating handler registered. */\n  readonly externalId: string\n  /** What happened, in the provider's own words: `'envelope.completed'`. */\n  readonly type: string\n  /** The provider's delivery id, when it has one — the strongest dedup key. */\n  readonly eventId?: string\n  /** The payload, passed to the target step as its input (validated by the step's schema). */\n  readonly payload?: unknown\n  /** Execute this step instead of the correlation's registered one. */\n  readonly step?: string\n  /** Override the derived idempotency key — for a provider whose retries are not identical. */\n  readonly idempotencyKey?: string\n  /** When the external system says it happened (ISO-8601); recorded, never used as `asOf`. */\n  readonly occurredAt?: string\n}\n\n/**\n * How an ingested event ended up: `executed` (the target step ran and\n * committed), `duplicate` (already seen — this delivery changed nothing, by\n * design), or `dead-lettered` (nothing could be done with it, and it is\n * sitting in the dead-letter surface). Wire vocabulary, so the contract\n * declares it and this is the same closed set.\n */\nexport type IngestionStatus = ContractIngestionStatus\n\n/**\n * Why an event was dead-lettered — the operator's first question, answered.\n *\n * Two reasons are ingestion's own (`unrouted`: no correlation claims the\n * identifier; `no-step`: routed, but neither the event nor the correlation\n * names a step); every other reason **is** the `AffordanceErrorCode`\n * the refused Execution already declared at its raise site. Ingestion does\n * not re-derive the kind of a Refusal — it projects the code the error\n * carries, so a new refusal class can never misroute here. Wire vocabulary,\n * declared once by the contract; this is the same closed set.\n */\nexport type DeadLetterReason = ContractDeadLetterReason\n\n/**\n * Whether a provider redelivery of the same event deserves another attempt.\n *\n * Total over {@link DeadLetterReason}, so a new code cannot be added without\n * deciding its reopen policy. `true` marks the outcomes that another delivery\n * could genuinely cure — the case was busy, the handler crashed. Everything\n * deterministic (a payload its schema rejects, an address that does not\n * resolve, a guard that said no) stays dead-lettered: it will be refused the\n * same way on every retry, so reopening it would only invite endless\n * redelivery.\n */\nexport const REOPENS_ON_REDELIVERY: Record<DeadLetterReason, boolean> = {\n  unrouted: false,\n  'no-step': false,\n  'step-not-available': false,\n  'case-busy': true,\n  'invalid-input': false,\n  'not-found': false,\n  'bad-request': false,\n  'execution-failed': true,\n  'invalid-state': false,\n}\n\nconst REOPENABLE = Object.entries(REOPENS_ON_REDELIVERY)\n  .filter(([, reopens]) => reopens)\n  .map(([reason]) => reason)\n\n/** What {@link ingest} resolves to — always a record, never a throw. */\nexport interface IngestionResult {\n  readonly id: string\n  readonly status: IngestionStatus\n  readonly system: string\n  readonly externalId: string\n  readonly idempotencyKey: string\n  /** Where it routed, when it routed. */\n  readonly correlation: Correlation | null\n  /** The Execution it produced, on `executed`. */\n  readonly execution: ExecutionResult | null\n  /** Why it is in the dead-letter surface, on `dead-lettered`. */\n  readonly reason: DeadLetterReason | null\n  /** Human-readable detail: the unmet conditions, the failure message. */\n  readonly detail: string | null\n  readonly receivedAt: string\n}\n\n/** A row of the dead-letter surface. */\nexport interface DeadLetter {\n  readonly id: string\n  readonly system: string\n  readonly externalId: string\n  readonly type: string\n  readonly idempotencyKey: string\n  readonly caseId: string | null\n  readonly scopeKey: string | null\n  readonly step: string | null\n  readonly reason: DeadLetterReason\n  readonly detail: string | null\n  readonly event: ExternalEvent\n  readonly receivedAt: string\n}\n\n/** Filters for {@link readDeadLetters}; all optional, all AND-ed. */\nexport interface DeadLetterFilter {\n  readonly system?: string\n  readonly caseId?: string\n  readonly reason?: DeadLetterReason\n  readonly limit?: number\n}\n\n/** How ingestion presents the external system to guards and the journal. */\nexport interface ExternalActor {\n  readonly kind: 'external'\n  readonly system: string\n  readonly externalId: string\n  readonly eventType: string\n}\n\n/** Engine-level ingestion settings. */\nexport interface IngestionOptions {\n  /**\n   * Map an event to the Actor its Execution runs as. Defaults to an\n   * {@link ExternalActor}; an app whose `permits` conditions read its own\n   * actor shape supplies a mapping instead of bending that shape.\n   */\n  readonly actor?: (event: ExternalEvent) => unknown\n}\n\n/** The normalized settings the environment carries. */\nexport interface IngestionSettings {\n  readonly actor: (event: ExternalEvent) => unknown\n}\n\n/**\n * What {@link ingest} needs from its caller: the execution environment plus\n * ingestion's own settings. This is the widest environment any subsystem\n * asks for, so it is also the shape the engine builds once and hands to all\n * of them — named here so that contract is a type, not a coincidence of an\n * object literal.\n */\nexport interface IngestionEnvironment extends ExecutionEnvironment {\n  readonly ingestion: IngestionSettings\n}\n\nexport const externalActor = (event: ExternalEvent): ExternalActor => ({\n  kind: 'external',\n  system: event.system,\n  externalId: event.externalId,\n  eventType: event.type,\n})\n\nexport const normalizeIngestion = (\n  options: IngestionOptions = {},\n): IngestionSettings => ({\n  actor: options.actor ?? externalActor,\n})\n\n/**\n * The idempotency key an event dedups on.\n *\n * `(system, externalId, type)` is the key's fixed prefix, so the *same*\n * notification about the *same* envelope produces the same key however many\n * times it is delivered — and, because an external id resolves to one (case,\n * scope element), the key is scoped exactly as far as the correlation is. The\n * tail is the provider's own delivery id where there is one, and a hash of\n * the payload where there is not: a provider that cannot tell you which\n * delivery this is gets content-addressed dedup, which is the best anyone\n * can do.\n */\nexport const idempotencyKeyFor = (event: ExternalEvent): string => {\n  if (event.idempotencyKey !== undefined) return event.idempotencyKey\n  const tail =\n    event.eventId ??\n    createHash('sha256')\n      .update(JSON.stringify(event.payload ?? null))\n      .digest('hex')\n      .slice(0, 32)\n  return `${event.system}/${event.externalId}/${event.type}/${tail}`\n}\n\ntype EventRow = {\n  id: string\n  system: string\n  external_id: string\n  type: string\n  idempotency_key: string\n  case_id: string | null\n  scope_key: string | null\n  step: string | null\n  status: string\n  reason: string | null\n  detail: string | null\n  execution_id: string | null\n  event: ExternalEvent\n  received_at: Date\n}\n\n/**\n * The dedup gate. Inserts the event's row and reports whether this delivery\n * is the one that got it.\n *\n * `on conflict do nothing` is the whole mechanism: exactly one of N\n * concurrent deliveries inserts, and the losers read what the winner wrote.\n * A previous delivery that ended `dead-lettered` for a *transient* reason is\n * reopened rather than deduplicated — a provider retry after \"the case was\n * busy\" should get its chance, which is precisely what provider retries are\n * for.\n */\nconst claimDelivery = async (\n  db: Queryable,\n  event: ExternalEvent,\n  idempotencyKey: string,\n): Promise<{ row: EventRow; fresh: boolean }> => {\n  const inserted = await db.query<EventRow>(\n    `insert into ${EVENTS} (id, system, external_id, type, idempotency_key, status, event)\n     values ($1, $2, $3, $4, $5, 'pending', $6::jsonb)\n     on conflict (idempotency_key) do nothing\n     returning *`,\n    [\n      mintId('event'),\n      event.system,\n      event.externalId,\n      event.type,\n      idempotencyKey,\n      JSON.stringify(event),\n    ],\n  )\n  const row = inserted.rows[0]\n  if (row) return { row, fresh: true }\n\n  const retried = await db.query<EventRow>(\n    `update ${EVENTS}\n     set status = 'pending', reason = null, detail = null, received_at = now(), event = $2::jsonb\n     where idempotency_key = $1 and status = 'dead-lettered' and reason = any($3)\n     returning *`,\n    [idempotencyKey, JSON.stringify(event), REOPENABLE],\n  )\n  const reopened = retried.rows[0]\n  if (reopened) return { row: reopened, fresh: true }\n\n  const existing = await db.query<EventRow>(\n    `select * from ${EVENTS} where idempotency_key = $1`,\n    [idempotencyKey],\n  )\n  const previous = existing.rows[0]\n  if (!previous)\n    throw new Error(\n      `${EVENTS}: delivery neither inserted nor found — key ${idempotencyKey}`,\n    )\n  return { row: previous, fresh: false }\n}\n\n/** Record how a delivery ended. The row is the dead-letter surface, so this is the only settle path. */\nconst settle = async (\n  db: Queryable,\n  id: string,\n  fields: {\n    status: 'executed' | 'dead-lettered'\n    caseId?: string | null\n    scopeKey?: string | null\n    step?: string | null\n    reason?: DeadLetterReason | null\n    detail?: string | null\n    executionId?: string | null\n  },\n): Promise<void> => {\n  await db.query(\n    `update ${EVENTS}\n     set status = $2, case_id = $3, scope_key = $4, step = $5, reason = $6, detail = $7, execution_id = $8\n     where id = $1`,\n    [\n      id,\n      fields.status,\n      fields.caseId ?? null,\n      fields.scopeKey ?? null,\n      fields.step ?? null,\n      fields.reason ?? null,\n      fields.detail ?? null,\n      fields.executionId ?? null,\n    ],\n  )\n}\n\nconst result = (\n  row: EventRow,\n  status: IngestionStatus,\n  extra: Partial<IngestionResult> = {},\n): IngestionResult => ({\n  id: row.id,\n  status,\n  system: row.system,\n  externalId: row.external_id,\n  idempotencyKey: row.idempotency_key,\n  correlation: null,\n  execution: null,\n  reason: null,\n  detail: null,\n  receivedAt: row.received_at.toISOString(),\n  ...extra,\n})\n\n/**\n * Which step an ingested event executes: the event's own naming wins,\n * falling back to what the correlation registered. The precedence is stated\n * once so any surface that *previews* routing (a dev console's world panel)\n * asks the same question `ingest` will answer.\n */\nexport const routedStep = (\n  event: { readonly step?: string },\n  correlation: { readonly step: string | null },\n): string | null => event.step ?? correlation.step ?? null\n\n/**\n * Ingest one external event: dedup, correlate, execute — or dead-letter it\n * with a reason.\n *\n * Never throws for an event's own sake: a webhook endpoint that 500s because\n * a guard said no teaches the provider to retry something that will never\n * succeed. Infrastructure failures (the database is gone) do still throw,\n * because those the caller must not acknowledge.\n */\nexport const ingest = async (\n  env: IngestionEnvironment,\n  event: ExternalEvent,\n): Promise<IngestionResult> => {\n  const db = queryableOf(env.db)\n  const idempotencyKey = idempotencyKeyFor(event)\n  const { row, fresh } = await claimDelivery(db, event, idempotencyKey)\n  if (!fresh) {\n    return result(row, 'duplicate', {\n      reason: (row.reason as DeadLetterReason | null) ?? null,\n      detail: `already ingested as ${row.status} at ${row.received_at.toISOString()}`,\n    })\n  }\n\n  // Settle the row and answer the caller with the same reason/detail pair —\n  // one helper, so a branch cannot record one thing and report another.\n  const deadLetter = async (fields: {\n    readonly reason: DeadLetterReason\n    readonly detail: string\n    readonly correlation?: Correlation\n    readonly step?: string\n  }): Promise<IngestionResult> => {\n    await settle(db, row.id, {\n      status: 'dead-lettered',\n      reason: fields.reason,\n      detail: fields.detail,\n      ...(fields.correlation !== undefined && {\n        caseId: fields.correlation.caseId,\n        scopeKey: fields.correlation.scopeKey,\n      }),\n      ...(fields.step !== undefined && { step: fields.step }),\n    })\n    return result(row, 'dead-lettered', {\n      reason: fields.reason,\n      detail: fields.detail,\n      ...(fields.correlation !== undefined && {\n        correlation: fields.correlation,\n      }),\n    })\n  }\n\n  const correlation = await lookupCorrelation(\n    db,\n    event.system,\n    event.externalId,\n  )\n  if (correlation === null) {\n    return deadLetter({\n      reason: 'unrouted',\n      detail: `no correlation registered for ${event.system}/${event.externalId}`,\n    })\n  }\n\n  const stepName = routedStep(event, correlation)\n  if (stepName === null) {\n    return deadLetter({\n      correlation,\n      reason: 'no-step',\n      detail: `correlation ${event.system}/${event.externalId} names no step, and the event does not either`,\n    })\n  }\n\n  const ran = await runAsSystem(env, correlation.caseId, stepName, {\n    actor: env.ingestion.actor(event),\n    ...(correlation.scopeKey !== null && { scopeKey: correlation.scopeKey }),\n    ...(event.payload !== undefined && { input: event.payload }),\n  })\n  if (ran.outcome === 'committed') {\n    await settle(db, row.id, {\n      status: 'executed',\n      caseId: correlation.caseId,\n      scopeKey: correlation.scopeKey,\n      step: stepName,\n      executionId: ran.result.executionId,\n    })\n    return result(row, 'executed', { correlation, execution: ran.result })\n  }\n  const [reason, detail] = classifyDeadLetter(ran)\n  return deadLetter({ correlation, step: stepName, reason, detail })\n}\n\n/**\n * Project a settled system run onto the reason an operator needs to see —\n * the one place that asks whether what settled was a Refusal.\n *\n * A framework Refusal already names its own kind and explains itself — the\n * reason is its code, the detail its message (a refused guard's message\n * carries the unmet conditions, addressed). Anything else is a bug, not a\n * Refusal; it lands as `execution-failed` so the event is kept, never\n * silently dropped, with the crash's own words as the detail.\n */\nexport const classifyDeadLetter = (\n  ran: SystemSettled,\n): [DeadLetterReason, string] =>\n  isAffordanceError(ran.error)\n    ? [ran.error.code, ran.error.message]\n    : ['execution-failed', ran.error.message]\n\nconst toDeadLetter = (row: EventRow): DeadLetter => ({\n  id: row.id,\n  system: row.system,\n  externalId: row.external_id,\n  type: row.type,\n  idempotencyKey: row.idempotency_key,\n  caseId: row.case_id,\n  scopeKey: row.scope_key,\n  step: row.step,\n  reason: row.reason as DeadLetterReason,\n  detail: row.detail,\n  event: row.event,\n  receivedAt: row.received_at.toISOString(),\n})\n\n/** Read the dead-letter surface, newest first — the ops view of \"arrived, did nothing\". */\nexport const readDeadLetters = async (\n  db: Queryable,\n  filter: DeadLetterFilter = {},\n): Promise<readonly DeadLetter[]> => {\n  const { conditions, values, bind, where } = sqlWhere([\n    `status = 'dead-lettered'`,\n  ])\n\n  if (filter.system !== undefined)\n    conditions.push(`system = ${bind(filter.system)}`)\n  if (filter.caseId !== undefined)\n    conditions.push(`case_id = ${bind(filter.caseId)}`)\n  if (filter.reason !== undefined)\n    conditions.push(`reason = ${bind(filter.reason)}`)\n  const limit = filter.limit === undefined ? '' : ` limit ${bind(filter.limit)}`\n\n  const { rows } = await db.query<EventRow>(\n    `select * from ${EVENTS} where ${where()} order by received_at desc${limit}`,\n    values,\n  )\n  return rows.map(toDeadLetter)\n}\n"]}
+{"version":3,"file":"ingest.js","sourceRoot":"","sources":["../../src/ingestion/ingest.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Ingestion: external events become Executions.\n *\n * A webhook arrives. Three things have to happen, in this order, and each of\n * them has to be visible afterwards:\n *\n * 1. **Dedup.** Providers retry; \"at least once\" is the delivery guarantee\n *    every one of them offers. Storage atomically acquires a delivery, so\n *    concurrent deliveries of one event produce one Execution and the\n *    remaining callers receive `duplicate`.\n * 2. **Correlate.** The external identifier is resolved to (case, scope,\n *    step) through the registry the initiating handler wrote.\n * 3. **Execute.** Through the ordinary claim → run → commit, with the\n *    external system as the journaled actor. Ingestion has no privileged\n *    path: the guard still decides, transactionally.\n *\n * What is *not* allowed is a quiet drop. An event nothing can route, an event\n * whose step the guard refuses, an event whose case is busy — each lands in\n * the same table with a status and a reason, which is the dead-letter\n * surface. \"The webhook definitely arrived, so why is the case still waiting\"\n * is a question this table answers without anyone reading a log file.\n */\n\nimport { createHash } from 'node:crypto'\nimport type { AffordanceErrorCode } from '../errors.js'\nimport { isAffordanceError } from '../errors.js'\nimport type {\n  ExecutionEnvironment,\n  ExecutionResult,\n  SystemSettled,\n} from '../execution/index.js'\nimport { runAsSystem } from '../execution/index.js'\nimport type { DeliveryRecord } from '../storage.js'\nimport type { Correlation } from './correlation.js'\n\n/** An event as an external system delivered it. */\nexport interface ExternalEvent {\n  /** The system that emitted it, matching the correlation's `system`. */\n  readonly system: string\n  /** The identifier that routes it — the one the initiating handler registered. */\n  readonly externalId: string\n  /** What happened, in the provider's own words: `'envelope.completed'`. */\n  readonly type: string\n  /** The provider's delivery id, when it has one — the strongest dedup key. */\n  readonly eventId?: string\n  /** The payload, passed to the target step as its input (validated by the step's schema). */\n  readonly payload?: unknown\n  /** Execute this step instead of the correlation's registered one. */\n  readonly step?: string\n  /** Override the derived idempotency key — for a provider whose retries are not identical. */\n  readonly idempotencyKey?: string\n  /** When the external system says it happened (ISO-8601); recorded, never used as `asOf`. */\n  readonly occurredAt?: string\n}\n\n/**\n * How an ingested event ended up: `executed` (the target step ran and\n * committed), `duplicate` (already seen — this delivery changed nothing, by\n * design), or `dead-lettered` (nothing could be done with it, and it is\n * sitting in the dead-letter surface).\n */\nexport type IngestionStatus = 'executed' | 'duplicate' | 'dead-lettered'\n\n/**\n * Why an event was dead-lettered — the operator's first question, answered.\n *\n * Two reasons are ingestion's own (`unrouted`: no correlation claims the\n * identifier; `no-step`: routed, but neither the event nor the correlation\n * names a step); every other reason **is** the `AffordanceErrorCode`\n * the refused Execution already declared at its raise site. Ingestion does\n * not re-derive the kind of a Refusal — it projects the code the error\n * carries, so a new refusal class can never misroute here.\n */\nexport type DeadLetterReason = 'unrouted' | 'no-step' | AffordanceErrorCode\n\n/**\n * Whether a provider redelivery of the same event deserves another attempt.\n *\n * Total over {@link DeadLetterReason}, so a new code cannot be added without\n * deciding its reopen policy. `true` marks the outcomes that another delivery\n * could genuinely cure — the case was busy, the handler crashed. Everything\n * deterministic (a payload its schema rejects, an address that does not\n * resolve, a guard that said no) stays dead-lettered: it will be refused the\n * same way on every retry, so reopening it would only invite endless\n * redelivery.\n */\nexport const REOPENS_ON_REDELIVERY: Record<DeadLetterReason, boolean> = {\n  unrouted: false,\n  'no-step': false,\n  'step-not-available': false,\n  'case-busy': true,\n  'invalid-input': false,\n  'not-found': false,\n  'bad-request': false,\n  'execution-failed': true,\n  'invalid-state': false,\n}\n\nconst REOPENABLE = Object.entries(REOPENS_ON_REDELIVERY)\n  .filter(([, reopens]) => reopens)\n  .map(([reason]) => reason as DeadLetterReason)\n\n/** What {@link ingest} resolves to — always a record, never a throw. */\nexport interface IngestionResult {\n  readonly id: string\n  readonly status: IngestionStatus\n  readonly system: string\n  readonly externalId: string\n  readonly idempotencyKey: string\n  /** Where it routed, when it routed. */\n  readonly correlation: Correlation | null\n  /** The Execution it produced, on `executed`. */\n  readonly execution: ExecutionResult | null\n  /** Why it is in the dead-letter surface, on `dead-lettered`. */\n  readonly reason: DeadLetterReason | null\n  /** Human-readable detail: the unmet conditions, the failure message. */\n  readonly detail: string | null\n  readonly receivedAt: string\n}\n\n/** A row of the dead-letter surface. */\nexport interface DeadLetter {\n  readonly id: string\n  readonly system: string\n  readonly externalId: string\n  readonly type: string\n  readonly idempotencyKey: string\n  readonly caseId: string | null\n  readonly scopeKey: string | null\n  readonly step: string | null\n  readonly reason: DeadLetterReason\n  readonly detail: string | null\n  readonly event: ExternalEvent\n  readonly receivedAt: string\n}\n\n/** Filters for {@link readDeadLetters}; all optional, all AND-ed. */\nexport interface DeadLetterFilter {\n  readonly system?: string\n  readonly caseId?: string\n  readonly reason?: DeadLetterReason\n  readonly limit?: number\n}\n\n/** How ingestion presents the external system to guards and the journal. */\nexport interface ExternalActor {\n  readonly kind: 'external'\n  readonly system: string\n  readonly externalId: string\n  readonly eventType: string\n}\n\n/** Engine-level ingestion settings. */\nexport interface IngestionOptions {\n  /**\n   * Map an event to the Actor its Execution runs as. Defaults to an\n   * {@link ExternalActor}; an app whose `permits` conditions read its own\n   * actor shape supplies a mapping instead of bending that shape.\n   */\n  readonly actor?: (event: ExternalEvent) => unknown\n}\n\n/** The normalized settings the environment carries. */\nexport interface IngestionSettings {\n  readonly actor: (event: ExternalEvent) => unknown\n}\n\n/**\n * What {@link ingest} needs from its caller: the execution environment plus\n * ingestion's own settings. This is the widest environment any subsystem\n * asks for, so it is also the shape the engine builds once and hands to all\n * of them — named here so that contract is a type, not a coincidence of an\n * object literal.\n */\nexport interface IngestionEnvironment<TCommit = unknown>\n  extends ExecutionEnvironment<TCommit> {\n  readonly ingestion: IngestionSettings\n}\n\nexport const externalActor = (event: ExternalEvent): ExternalActor => ({\n  kind: 'external',\n  system: event.system,\n  externalId: event.externalId,\n  eventType: event.type,\n})\n\nexport const normalizeIngestion = (\n  options: IngestionOptions = {},\n): IngestionSettings => ({\n  actor: options.actor ?? externalActor,\n})\n\n/**\n * The idempotency key an event dedups on.\n *\n * `(system, externalId, type)` is the key's fixed prefix, so the *same*\n * notification about the *same* envelope produces the same key however many\n * times it is delivered — and, because an external id resolves to one (case,\n * scope element), the key is scoped exactly as far as the correlation is. The\n * tail is the provider's own delivery id where there is one, and a hash of\n * the payload where there is not: a provider that cannot tell you which\n * delivery this is gets content-addressed dedup, which is the best anyone\n * can do.\n */\nexport const idempotencyKeyFor = (event: ExternalEvent): string => {\n  if (event.idempotencyKey !== undefined) return event.idempotencyKey\n  const tail =\n    event.eventId ??\n    createHash('sha256')\n      .update(JSON.stringify(event.payload ?? null))\n      .digest('hex')\n      .slice(0, 32)\n  return `${event.system}/${event.externalId}/${event.type}/${tail}`\n}\n\nconst result = (\n  row: DeliveryRecord,\n  status: IngestionStatus,\n  extra: Partial<IngestionResult> = {},\n): IngestionResult => ({\n  id: row.id,\n  status,\n  system: row.system,\n  externalId: row.externalId,\n  idempotencyKey: row.idempotencyKey,\n  correlation: null,\n  execution: null,\n  reason: null,\n  detail: null,\n  receivedAt: row.receivedAt,\n  ...extra,\n})\n\n/**\n * Which step an ingested event executes: the event's own naming wins,\n * falling back to what the correlation registered. The precedence is stated\n * once so any surface that *previews* routing (a dev console's world panel)\n * asks the same question `ingest` will answer.\n */\nexport const routedStep = (\n  event: { readonly step?: string },\n  correlation: { readonly step: string | null },\n): string | null => event.step ?? correlation.step ?? null\n\n/**\n * Ingest one external event: dedup, correlate, execute — or dead-letter it\n * with a reason.\n *\n * Never throws for an event's own sake: a webhook endpoint that 500s because\n * a guard said no teaches the provider to retry something that will never\n * succeed. Infrastructure failures (the database is gone) do still throw,\n * because those the caller must not acknowledge.\n */\nexport const ingest = async <TCommit>(\n  env: IngestionEnvironment<TCommit>,\n  event: ExternalEvent,\n): Promise<IngestionResult> => {\n  const idempotencyKey = idempotencyKeyFor(event)\n  const { row, fresh } = await env.storage.deliveries.acquire(\n    event,\n    idempotencyKey,\n    REOPENABLE,\n  )\n  if (!fresh) {\n    return result(row, 'duplicate', {\n      reason: row.reason,\n      detail: `already ingested as ${row.status} at ${row.receivedAt}`,\n    })\n  }\n\n  // Settle the row and answer the caller with the same reason/detail pair —\n  // one helper, so a branch cannot record one thing and report another.\n  const deadLetter = async (fields: {\n    readonly reason: DeadLetterReason\n    readonly detail: string\n    readonly correlation?: Correlation\n    readonly step?: string\n  }): Promise<IngestionResult> => {\n    await env.storage.deliveries.settle(row.id, {\n      status: 'dead-lettered',\n      reason: fields.reason,\n      detail: fields.detail,\n      ...(fields.correlation !== undefined && {\n        caseId: fields.correlation.caseId,\n        scopeKey: fields.correlation.scopeKey,\n      }),\n      ...(fields.step !== undefined && { step: fields.step }),\n    })\n    return result(row, 'dead-lettered', {\n      reason: fields.reason,\n      detail: fields.detail,\n      ...(fields.correlation !== undefined && {\n        correlation: fields.correlation,\n      }),\n    })\n  }\n\n  const correlation = await env.storage.correlations.lookup(\n    event.system,\n    event.externalId,\n  )\n  if (correlation === null) {\n    return deadLetter({\n      reason: 'unrouted',\n      detail: `no correlation registered for ${event.system}/${event.externalId}`,\n    })\n  }\n\n  const stepName = routedStep(event, correlation)\n  if (stepName === null) {\n    return deadLetter({\n      correlation,\n      reason: 'no-step',\n      detail: `correlation ${event.system}/${event.externalId} names no step, and the event does not either`,\n    })\n  }\n\n  const ran = await runAsSystem(env, correlation.caseId, stepName, {\n    actor: env.ingestion.actor(event),\n    ...(correlation.scopeKey !== null && { scopeKey: correlation.scopeKey }),\n    ...(event.payload !== undefined && { input: event.payload }),\n  })\n  if (ran.outcome === 'committed') {\n    await env.storage.deliveries.settle(row.id, {\n      status: 'executed',\n      caseId: correlation.caseId,\n      scopeKey: correlation.scopeKey,\n      step: stepName,\n      executionId: ran.result.executionId,\n    })\n    return result(row, 'executed', { correlation, execution: ran.result })\n  }\n  const [reason, detail] = classifyDeadLetter(ran)\n  return deadLetter({ correlation, step: stepName, reason, detail })\n}\n\n/**\n * Project a settled system run onto the reason an operator needs to see —\n * the one place that asks whether what settled was a Refusal.\n *\n * A framework Refusal already names its own kind and explains itself — the\n * reason is its code, the detail its message (a refused guard's message\n * carries the unmet conditions, addressed). Anything else is a bug, not a\n * Refusal; it lands as `execution-failed` so the event is kept, never\n * silently dropped, with the crash's own words as the detail.\n */\nexport const classifyDeadLetter = (\n  ran: SystemSettled,\n): [DeadLetterReason, string] =>\n  isAffordanceError(ran.error)\n    ? [ran.error.code, ran.error.message]\n    : ['execution-failed', ran.error.message]\n"]}

package/dist/migration/migrate.d.ts

@@ -32,7 +32,7 @@
  * if a total condition can read the old shape, write the total condition.
  */
 import type { ExecutionEnvironment, StateDelta } from '../execution/index.js';
-import type { Queryable } from '../store/index.js';
+import type { EngineStorage } from '../storage.js';
 /** The synthetic step name a migration executes under — its journal marker. */
 export declare const migrationStepName: (name: string) => string;
 /** The Actor a migration runs as, when the app supplies none. */
@@ -110,10 +110,9 @@ export interface MigrationReport {
  * state schema) is reported and the run moves on, and the next run will pick
  * it up because it never got its marker.
  *
- * The cursor walks case ids ascending, and the "already migrated" filter is
- * applied by the database on every batch — so a case migrated by a
- * concurrently-running instance of the same migration simply is not returned.
+ * Storage owns candidate order and continuation. It excludes completed
+ * migration markers on every page; the core passes its cursor back unchanged.
  */
-export declare const migrate: (env: ExecutionEnvironment, caseTypeName: string, name: string, transform: MigrationTransform, options?: MigrationOptions) => Promise<MigrationReport>;
-/** Whether one case already carries a migration's marker. */
-export declare const hasMigrated: (db: Queryable, caseId: string, name: string) => Promise<boolean>;
+export declare const migrate: <TCommit>(env: ExecutionEnvironment<TCommit>, caseTypeName: string, name: string, transform: MigrationTransform, options?: MigrationOptions) => Promise<MigrationReport>;
+/** Whether one case carries a completed migration marker. */
+export declare const hasMigrated: (storage: Pick<EngineStorage, "migrations">, caseId: string, name: string) => Promise<boolean>;

package/dist/migration/migrate.js

@@ -34,9 +34,7 @@
 import { toError } from '../errors.js';
 import { diffState, runAsSystem } from '../execution/index.js';
 import { step } from '../model/index.js';
-import { FRAMEWORK_SCHEMA, queryableOf, resolveStoredState, sqlWhere, } from '../store/index.js';
-const CASES = `${FRAMEWORK_SCHEMA}.cases`;
-const JOURNAL = `${FRAMEWORK_SCHEMA}.journal`;
+import { resolveStoredState } from '../store/index.js';
 /** The synthetic step name a migration executes under — its journal marker. */
 export const migrationStepName = (name) => `migrate:${name}`;
 /**
@@ -62,30 +60,6 @@ const withMigrationStep = (definition, migration) => ({
     steps: [...definition.steps, migration],
     getStep: (stepName) => stepName === migration.name ? migration : definition.getStep(stepName),
 });
-/** Case ids of this type that do not yet carry the migration's marker, oldest first. */
-const findCandidates = async (db, caseTypeName, marker, options, afterId, batchSize) => {
-    const { conditions, values, bind, where } = sqlWhere([
-        `c.case_type = $1`,
-        // The marker: a completed Execution of this migration on this case. The
-        // journal is the record of what has happened, so it is also the record of
-        // what has already been migrated — no bookkeeping table, no state flag.
-        `not exists (
-       select 1 from ${JOURNAL} j
-       where j.case_id = c.id and j.step = $2 and j.entry = 'completed'
-     )`,
-    ], [caseTypeName, marker]);
-    if (options.includeEnded !== true)
-        conditions.push(`c.ended_at is null`);
-    if (options.caseIds !== undefined)
-        conditions.push(`c.id = any(${bind(options.caseIds)}::text[])`);
-    if (afterId !== null)
-        conditions.push(`c.id > ${bind(afterId)}`);
-    const { rows } = await db.query(`select c.id, c.state from ${CASES} c
-     where ${where()}
-     order by c.id asc
-     limit ${bind(batchSize)}`, values);
-    return rows;
-};
 /**
  * Run a state restructure over every case of a case type, as journaled
  * system Executions.
@@ -97,9 +71,8 @@ const findCandidates = async (db, caseTypeName, marker, options, afterId, batchS
  * state schema) is reported and the run moves on, and the next run will pick
  * it up because it never got its marker.
  *
- * The cursor walks case ids ascending, and the "already migrated" filter is
- * applied by the database on every batch — so a case migrated by a
- * concurrently-running instance of the same migration simply is not returned.
+ * Storage owns candidate order and continuation. It excludes completed
+ * migration markers on every page; the core passes its cursor back unchanged.
  */
 export const migrate = async (env, caseTypeName, name, transform, options = {}) => {
     if (typeof name !== 'string' || name.trim() === '') {
@@ -162,11 +135,10 @@ export const migrate = async (env, caseTypeName, name, transform, options = {})
         const remaining = options.limit === undefined ? batchSize : options.limit - scanned;
         if (remaining <= 0)
             break;
-        const candidates = await findCandidates(queryableOf(env.db), caseTypeName, marker, options, cursor, Math.min(batchSize, remaining));
-        if (candidates.length === 0)
+        const page = await env.storage.migrations.candidates(caseTypeName, marker, options, cursor, Math.min(batchSize, remaining));
+        if (page.cases.length === 0)
             break;
-        for (const candidate of candidates) {
-            cursor = candidate.id;
+        for (const candidate of page.cases) {
             scanned += 1;
             const { outcome, delta, error } = await runOne(candidate);
             if (error !== null)
@@ -183,13 +155,12 @@ export const migrate = async (env, caseTypeName, name, transform, options = {})
                 processed: scanned,
             });
         }
+        cursor = page.nextCursor;
+        if (cursor === null)
+            break;
     }
     return { name, caseTypeName, dryRun, scanned, migrated, unchanged, failed };
 };
-/** Whether one case already carries a migration's marker. */
-export const hasMigrated = async (db, caseId, name) => {
-    const { rows } = await db.query(`select 1 as one from ${JOURNAL}
-     where case_id = $1 and step = $2 and entry = 'completed' limit 1`, [caseId, migrationStepName(name)]);
-    return rows.length > 0;
-};
+/** Whether one case carries a completed migration marker. */
+export const hasMigrated = (storage, caseId, name) => storage.migrations.hasCompleted(caseId, migrationStepName(name));
 //# sourceMappingURL=migrate.js.map

package/dist/migration/migrate.js.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../src/migration/migrate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The migration escape hatch.\n *\n * Cases float to the latest definitions: a deploy changes what the steps are\n * and every in-flight case is immediately governed by the new ones, with no\n * migration executed and no version pinned. That covers almost everything,\n * because almost every change is *additive* — a new step, a new condition, a\n * new optional field — and the `?? fallback` discipline makes old\n * state readable by new code.\n *\n * What float cannot cover is a **restructure**: a field renamed, one field\n * split into two, a scalar turned into a collection. No fallback expression\n * makes `state.buyer` readable as `state.buyers[]`. For exactly that,\n * this module.\n *\n * Two properties make it an escape hatch rather than a second way of working:\n *\n * 1. **A migration is an Execution.** Not a script with a database\n *    connection — the same claim → run → commit as any step, so the case row\n *    lock, the in-flight claim, state schema validation\n *    and the journal entry all apply unchanged. The transform runs\n *    as a synthetic step named `migrate:<name>`, with a migration actor.\n *    An auditor asking \"why did this case's shape change in March\" gets the\n *    same kind of answer as for anything else that ever happened to it.\n * 2. **The journal is the marker.** A case has been migrated iff it carries a\n *    completed `migrate:<name>` entry. Nothing is written into app state to\n *    record it, so a migration leaves no residue in the document it\n *    restructured — and re-running is a no-op by construction, which is also\n *    what makes an interrupted run resumable.\n *\n * When *not* to reach for this is in `docs/migration.md`. The short version:\n * if a total condition can read the old shape, write the total condition.\n */\n\nimport { toError } from '../errors.js'\nimport type { ExecutionEnvironment, StateDelta } from '../execution/index.js'\nimport { diffState, runAsSystem } from '../execution/index.js'\nimport type { AnyCaseType, StepDefinition } from '../model/index.js'\nimport { step } from '../model/index.js'\nimport type { Queryable } from '../store/index.js'\nimport {\n  FRAMEWORK_SCHEMA,\n  queryableOf,\n  resolveStoredState,\n  sqlWhere,\n} from '../store/index.js'\n\nconst CASES = `${FRAMEWORK_SCHEMA}.cases`\nconst JOURNAL = `${FRAMEWORK_SCHEMA}.journal`\n\n/** The synthetic step name a migration executes under — its journal marker. */\nexport const migrationStepName = (name: string): string => `migrate:${name}`\n\n/** The Actor a migration runs as, when the app supplies none. */\nexport interface MigrationActor {\n  readonly kind: 'migration'\n  readonly migration: string\n}\n\n/**\n * The state transform. Pure and total, like a condition: it will\n * be handed state written by every definition the case has ever floated\n * through, and returning the input unchanged must be safe.\n */\nexport type MigrationTransform<TState = any> = (state: TState) => TState\n\n/** Options for {@link migrate}. */\nexport interface MigrationOptions {\n  /** How many cases to claim per round trip when scanning (default 100). */\n  readonly batchSize?: number\n  /** Stop after this many cases — for a cautious first run. */\n  readonly limit?: number\n  /** Restrict the run to these cases; they are still skipped if already migrated. */\n  readonly caseIds?: readonly string[]\n  /** The Actor the Executions run as; defaults to a {@link MigrationActor}. */\n  readonly actor?: unknown\n  /** Include dormant (ended) cases. Off by default — a closed case is usually not worth restructuring. */\n  readonly includeEnded?: boolean\n  /**\n   * Compute what each case *would* become and report the deltas without\n   * writing anything. Nothing is journaled, so a dry run leaves no marker\n   * and the real run still has every case to do.\n   */\n  readonly dryRun?: boolean\n  /** Called after each case, for a progress bar or a log line. */\n  readonly onProgress?: (progress: MigrationProgress) => void\n}\n\n/** Progress after one case. */\nexport interface MigrationProgress {\n  readonly caseId: string\n  readonly outcome: 'migrated' | 'unchanged' | 'failed'\n  /** What the transform changed, as JSON Patch; empty when it changed nothing. */\n  readonly delta: StateDelta\n  readonly error: Error | null\n  /** How many cases have been processed so far in this run. */\n  readonly processed: number\n}\n\n/** One case a migration could not restructure. */\nexport interface MigrationFailure {\n  readonly caseId: string\n  readonly error: Error\n}\n\n/** What {@link migrate} resolves to. */\nexport interface MigrationReport {\n  readonly name: string\n  readonly caseTypeName: string\n  readonly dryRun: boolean\n  /** Cases examined — those not already bearing the marker. */\n  readonly scanned: number\n  /** Cases whose state the transform changed and which committed. */\n  readonly migrated: number\n  /**\n   * Cases the transform left identical. Still journaled (and so still\n   * marked), because \"this migration considered this case and had nothing to\n   * do\" is a fact worth being able to prove.\n   */\n  readonly unchanged: number\n  readonly failed: readonly MigrationFailure[]\n}\n\n/**\n * Build the synthetic step the transform runs as. It declares no conditions:\n * a migration is not a business affordance and must not be blockable by one\n * — it is the deliberate exception float reserves, and the guard model\n * would only ever be in its way. `maxAttempts: 1` because a transform that\n * throws is a defect in the transform, and retrying it just throws again.\n */\nconst migrationStep = (\n  name: string,\n  transform: MigrationTransform,\n): StepDefinition<unknown, unknown> =>\n  step({\n    name: migrationStepName(name),\n    retry: { maxAttempts: 1 },\n    handler: async (state: unknown) => transform(state),\n  })\n\n/**\n * A view of the case type with the migration step spliced in, so the\n * ordinary lifecycle can address it by name. The real definition is left\n * untouched: the migration step exists for the duration of the run and is\n * never part of anything a client could see as an affordance.\n */\nconst withMigrationStep = (\n  definition: AnyCaseType,\n  migration: StepDefinition<unknown, unknown>,\n): AnyCaseType => ({\n  ...definition,\n  steps: [...definition.steps, migration],\n  getStep: (stepName: string) =>\n    stepName === migration.name ? migration : definition.getStep(stepName),\n})\n\n/** Case ids of this type that do not yet carry the migration's marker, oldest first. */\nconst findCandidates = async (\n  db: Queryable,\n  caseTypeName: string,\n  marker: string,\n  options: MigrationOptions,\n  afterId: string | null,\n  batchSize: number,\n): Promise<readonly { id: string; state: unknown }[]> => {\n  const { conditions, values, bind, where } = sqlWhere(\n    [\n      `c.case_type = $1`,\n      // The marker: a completed Execution of this migration on this case. The\n      // journal is the record of what has happened, so it is also the record of\n      // what has already been migrated — no bookkeeping table, no state flag.\n      `not exists (\n       select 1 from ${JOURNAL} j\n       where j.case_id = c.id and j.step = $2 and j.entry = 'completed'\n     )`,\n    ],\n    [caseTypeName, marker],\n  )\n  if (options.includeEnded !== true) conditions.push(`c.ended_at is null`)\n  if (options.caseIds !== undefined)\n    conditions.push(`c.id = any(${bind(options.caseIds)}::text[])`)\n  if (afterId !== null) conditions.push(`c.id > ${bind(afterId)}`)\n\n  const { rows } = await db.query<{ id: string; state: unknown }>(\n    `select c.id, c.state from ${CASES} c\n     where ${where()}\n     order by c.id asc\n     limit ${bind(batchSize)}`,\n    values,\n  )\n  return rows\n}\n\n/**\n * Run a state restructure over every case of a case type, as journaled\n * system Executions.\n *\n * Idempotent: a case that already carries the migration's marker is never\n * examined again, so re-running is a no-op and an interrupted run resumes\n * where it stopped. Failures do not stop the run — a case that cannot be\n * migrated (its claim is held, the transform threw, the result fails the\n * state schema) is reported and the run moves on, and the next run will pick\n * it up because it never got its marker.\n *\n * The cursor walks case ids ascending, and the \"already migrated\" filter is\n * applied by the database on every batch — so a case migrated by a\n * concurrently-running instance of the same migration simply is not returned.\n */\nexport const migrate = async (\n  env: ExecutionEnvironment,\n  caseTypeName: string,\n  name: string,\n  transform: MigrationTransform,\n  options: MigrationOptions = {},\n): Promise<MigrationReport> => {\n  if (typeof name !== 'string' || name.trim() === '') {\n    throw new TypeError(\n      'migrate: a migration must have a non-empty name — it is the journal marker',\n    )\n  }\n  if (typeof transform !== 'function') {\n    throw new TypeError(\n      `migrate '${name}': the transform must be a function of case state`,\n    )\n  }\n\n  const definition = env.caseTypeFor(caseTypeName)\n  const marker = migrationStepName(name)\n  const migration = migrationStep(name, transform)\n  const augmented = withMigrationStep(definition, migration)\n  const actor: unknown = options.actor ?? { kind: 'migration', migration: name }\n  const batchSize = Math.max(1, options.batchSize ?? 100)\n  const dryRun = options.dryRun === true\n\n  let scanned = 0\n  let migrated = 0\n  let unchanged = 0\n  const failed: MigrationFailure[] = []\n  let cursor: string | null = null\n\n  /** One candidate's verdict, with early returns — no outcome threading. */\n  const runOne = async (candidate: {\n    readonly id: string\n    readonly state: unknown\n  }): Promise<Pick<MigrationProgress, 'outcome' | 'delta' | 'error'>> => {\n    try {\n      if (dryRun) {\n        // The transform is pure, so \"what would this become\" needs no\n        // claim, no lock and no write — and leaves no marker behind.\n        const resolved = await resolveStoredState(definition, candidate.state)\n        const before = resolved === null ? candidate.state : resolved.state\n        const delta = diffState(before, transform(before))\n        return {\n          outcome: delta.length === 0 ? 'unchanged' : 'migrated',\n          delta,\n          error: null,\n        }\n      }\n      // The system runner returns case-level failures as values rather than\n      // throwing, and the sweep filters on that outcome: only a commit\n      // advances this case. A settled run — a held claim, a throwing\n      // transform, a result its schema rejects — is reported with no marker\n      // written, so the next run picks the case up again.\n      const ran = await runAsSystem(env, candidate.id, marker, {\n        actor,\n        definition: augmented,\n      })\n      if (ran.outcome === 'settled')\n        return { outcome: 'failed', delta: [], error: ran.error }\n      const delta = ran.result.delta\n      return {\n        outcome: delta.length === 0 ? 'unchanged' : 'migrated',\n        delta,\n        error: null,\n      }\n    } catch (caught) {\n      // The dry-run path's own throws (a transform is app code).\n      return { outcome: 'failed', delta: [], error: toError(caught) }\n    }\n  }\n\n  for (;;) {\n    const remaining =\n      options.limit === undefined ? batchSize : options.limit - scanned\n    if (remaining <= 0) break\n    const candidates = await findCandidates(\n      queryableOf(env.db),\n      caseTypeName,\n      marker,\n      options,\n      cursor,\n      Math.min(batchSize, remaining),\n    )\n    if (candidates.length === 0) break\n\n    for (const candidate of candidates) {\n      cursor = candidate.id\n      scanned += 1\n      const { outcome, delta, error } = await runOne(candidate)\n      if (error !== null) failed.push({ caseId: candidate.id, error })\n      else if (outcome === 'unchanged') unchanged += 1\n      else migrated += 1\n\n      options.onProgress?.({\n        caseId: candidate.id,\n        outcome,\n        delta,\n        error,\n        processed: scanned,\n      })\n    }\n  }\n\n  return { name, caseTypeName, dryRun, scanned, migrated, unchanged, failed }\n}\n\n/** Whether one case already carries a migration's marker. */\nexport const hasMigrated = async (\n  db: Queryable,\n  caseId: string,\n  name: string,\n): Promise<boolean> => {\n  const { rows } = await db.query<{ one: number }>(\n    `select 1 as one from ${JOURNAL}\n     where case_id = $1 and step = $2 and entry = 'completed' limit 1`,\n    [caseId, migrationStepName(name)],\n  )\n  return rows.length > 0\n}\n"]}
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../src/migration/migrate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The migration escape hatch.\n *\n * Cases float to the latest definitions: a deploy changes what the steps are\n * and every in-flight case is immediately governed by the new ones, with no\n * migration executed and no version pinned. That covers almost everything,\n * because almost every change is *additive* — a new step, a new condition, a\n * new optional field — and the `?? fallback` discipline makes old\n * state readable by new code.\n *\n * What float cannot cover is a **restructure**: a field renamed, one field\n * split into two, a scalar turned into a collection. No fallback expression\n * makes `state.buyer` readable as `state.buyers[]`. For exactly that,\n * this module.\n *\n * Two properties make it an escape hatch rather than a second way of working:\n *\n * 1. **A migration is an Execution.** Not a script with a database\n *    connection — the same claim → run → commit as any step, so the case row\n *    lock, the in-flight claim, state schema validation\n *    and the journal entry all apply unchanged. The transform runs\n *    as a synthetic step named `migrate:<name>`, with a migration actor.\n *    An auditor asking \"why did this case's shape change in March\" gets the\n *    same kind of answer as for anything else that ever happened to it.\n * 2. **The journal is the marker.** A case has been migrated iff it carries a\n *    completed `migrate:<name>` entry. Nothing is written into app state to\n *    record it, so a migration leaves no residue in the document it\n *    restructured — and re-running is a no-op by construction, which is also\n *    what makes an interrupted run resumable.\n *\n * When *not* to reach for this is in `docs/migration.md`. The short version:\n * if a total condition can read the old shape, write the total condition.\n */\n\nimport { toError } from '../errors.js'\nimport type { ExecutionEnvironment, StateDelta } from '../execution/index.js'\nimport { diffState, runAsSystem } from '../execution/index.js'\nimport type { AnyCaseType, StepDefinition } from '../model/index.js'\nimport { step } from '../model/index.js'\nimport type { EngineStorage } from '../storage.js'\nimport { resolveStoredState } from '../store/index.js'\n\n/** The synthetic step name a migration executes under — its journal marker. */\nexport const migrationStepName = (name: string): string => `migrate:${name}`\n\n/** The Actor a migration runs as, when the app supplies none. */\nexport interface MigrationActor {\n  readonly kind: 'migration'\n  readonly migration: string\n}\n\n/**\n * The state transform. Pure and total, like a condition: it will\n * be handed state written by every definition the case has ever floated\n * through, and returning the input unchanged must be safe.\n */\nexport type MigrationTransform<TState = any> = (state: TState) => TState\n\n/** Options for {@link migrate}. */\nexport interface MigrationOptions {\n  /** How many cases to claim per round trip when scanning (default 100). */\n  readonly batchSize?: number\n  /** Stop after this many cases — for a cautious first run. */\n  readonly limit?: number\n  /** Restrict the run to these cases; they are still skipped if already migrated. */\n  readonly caseIds?: readonly string[]\n  /** The Actor the Executions run as; defaults to a {@link MigrationActor}. */\n  readonly actor?: unknown\n  /** Include dormant (ended) cases. Off by default — a closed case is usually not worth restructuring. */\n  readonly includeEnded?: boolean\n  /**\n   * Compute what each case *would* become and report the deltas without\n   * writing anything. Nothing is journaled, so a dry run leaves no marker\n   * and the real run still has every case to do.\n   */\n  readonly dryRun?: boolean\n  /** Called after each case, for a progress bar or a log line. */\n  readonly onProgress?: (progress: MigrationProgress) => void\n}\n\n/** Progress after one case. */\nexport interface MigrationProgress {\n  readonly caseId: string\n  readonly outcome: 'migrated' | 'unchanged' | 'failed'\n  /** What the transform changed, as JSON Patch; empty when it changed nothing. */\n  readonly delta: StateDelta\n  readonly error: Error | null\n  /** How many cases have been processed so far in this run. */\n  readonly processed: number\n}\n\n/** One case a migration could not restructure. */\nexport interface MigrationFailure {\n  readonly caseId: string\n  readonly error: Error\n}\n\n/** What {@link migrate} resolves to. */\nexport interface MigrationReport {\n  readonly name: string\n  readonly caseTypeName: string\n  readonly dryRun: boolean\n  /** Cases examined — those not already bearing the marker. */\n  readonly scanned: number\n  /** Cases whose state the transform changed and which committed. */\n  readonly migrated: number\n  /**\n   * Cases the transform left identical. Still journaled (and so still\n   * marked), because \"this migration considered this case and had nothing to\n   * do\" is a fact worth being able to prove.\n   */\n  readonly unchanged: number\n  readonly failed: readonly MigrationFailure[]\n}\n\n/**\n * Build the synthetic step the transform runs as. It declares no conditions:\n * a migration is not a business affordance and must not be blockable by one\n * — it is the deliberate exception float reserves, and the guard model\n * would only ever be in its way. `maxAttempts: 1` because a transform that\n * throws is a defect in the transform, and retrying it just throws again.\n */\nconst migrationStep = <TCommit>(\n  name: string,\n  transform: MigrationTransform,\n): StepDefinition<unknown, unknown, TCommit> =>\n  step({\n    name: migrationStepName(name),\n    retry: { maxAttempts: 1 },\n    handler: async (state: unknown) => transform(state),\n  })\n\n/**\n * A view of the case type with the migration step spliced in, so the\n * ordinary lifecycle can address it by name. The real definition is left\n * untouched: the migration step exists for the duration of the run and is\n * never part of anything a client could see as an affordance.\n */\nconst withMigrationStep = <TCommit>(\n  definition: AnyCaseType<TCommit>,\n  migration: StepDefinition<unknown, unknown, TCommit>,\n): AnyCaseType<TCommit> => ({\n  ...definition,\n  steps: [...definition.steps, migration],\n  getStep: (stepName: string) =>\n    stepName === migration.name ? migration : definition.getStep(stepName),\n})\n\n/**\n * Run a state restructure over every case of a case type, as journaled\n * system Executions.\n *\n * Idempotent: a case that already carries the migration's marker is never\n * examined again, so re-running is a no-op and an interrupted run resumes\n * where it stopped. Failures do not stop the run — a case that cannot be\n * migrated (its claim is held, the transform threw, the result fails the\n * state schema) is reported and the run moves on, and the next run will pick\n * it up because it never got its marker.\n *\n * Storage owns candidate order and continuation. It excludes completed\n * migration markers on every page; the core passes its cursor back unchanged.\n */\nexport const migrate = async <TCommit>(\n  env: ExecutionEnvironment<TCommit>,\n  caseTypeName: string,\n  name: string,\n  transform: MigrationTransform,\n  options: MigrationOptions = {},\n): Promise<MigrationReport> => {\n  if (typeof name !== 'string' || name.trim() === '') {\n    throw new TypeError(\n      'migrate: a migration must have a non-empty name — it is the journal marker',\n    )\n  }\n  if (typeof transform !== 'function') {\n    throw new TypeError(\n      `migrate '${name}': the transform must be a function of case state`,\n    )\n  }\n\n  const definition = env.caseTypeFor(caseTypeName)\n  const marker = migrationStepName(name)\n  const migration = migrationStep<TCommit>(name, transform)\n  const augmented = withMigrationStep(definition, migration)\n  const actor: unknown = options.actor ?? { kind: 'migration', migration: name }\n  const batchSize = Math.max(1, options.batchSize ?? 100)\n  const dryRun = options.dryRun === true\n\n  let scanned = 0\n  let migrated = 0\n  let unchanged = 0\n  const failed: MigrationFailure[] = []\n  let cursor: string | null = null\n\n  /** One candidate's verdict, with early returns — no outcome threading. */\n  const runOne = async (candidate: {\n    readonly id: string\n    readonly state: unknown\n  }): Promise<Pick<MigrationProgress, 'outcome' | 'delta' | 'error'>> => {\n    try {\n      if (dryRun) {\n        // The transform is pure, so \"what would this become\" needs no\n        // claim, no lock and no write — and leaves no marker behind.\n        const resolved = await resolveStoredState(definition, candidate.state)\n        const before = resolved === null ? candidate.state : resolved.state\n        const delta = diffState(before, transform(before))\n        return {\n          outcome: delta.length === 0 ? 'unchanged' : 'migrated',\n          delta,\n          error: null,\n        }\n      }\n      // The system runner returns case-level failures as values rather than\n      // throwing, and the sweep filters on that outcome: only a commit\n      // advances this case. A settled run — a held claim, a throwing\n      // transform, a result its schema rejects — is reported with no marker\n      // written, so the next run picks the case up again.\n      const ran = await runAsSystem(env, candidate.id, marker, {\n        actor,\n        definition: augmented,\n      })\n      if (ran.outcome === 'settled')\n        return { outcome: 'failed', delta: [], error: ran.error }\n      const delta = ran.result.delta\n      return {\n        outcome: delta.length === 0 ? 'unchanged' : 'migrated',\n        delta,\n        error: null,\n      }\n    } catch (caught) {\n      // The dry-run path's own throws (a transform is app code).\n      return { outcome: 'failed', delta: [], error: toError(caught) }\n    }\n  }\n\n  for (;;) {\n    const remaining =\n      options.limit === undefined ? batchSize : options.limit - scanned\n    if (remaining <= 0) break\n    const page = await env.storage.migrations.candidates(\n      caseTypeName,\n      marker,\n      options,\n      cursor,\n      Math.min(batchSize, remaining),\n    )\n    if (page.cases.length === 0) break\n\n    for (const candidate of page.cases) {\n      scanned += 1\n      const { outcome, delta, error } = await runOne(candidate)\n      if (error !== null) failed.push({ caseId: candidate.id, error })\n      else if (outcome === 'unchanged') unchanged += 1\n      else migrated += 1\n\n      options.onProgress?.({\n        caseId: candidate.id,\n        outcome,\n        delta,\n        error,\n        processed: scanned,\n      })\n    }\n    cursor = page.nextCursor\n    if (cursor === null) break\n  }\n\n  return { name, caseTypeName, dryRun, scanned, migrated, unchanged, failed }\n}\n\n/** Whether one case carries a completed migration marker. */\nexport const hasMigrated = (\n  storage: Pick<EngineStorage, 'migrations'>,\n  caseId: string,\n  name: string,\n): Promise<boolean> =>\n  storage.migrations.hasCompleted(caseId, migrationStepName(name))\n"]}

package/dist/model/casetype.d.ts

@@ -14,9 +14,9 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { StepDefinition } from './step.js';
 /** Options for {@link caseType}. */
-export interface CaseTypeOptions<S extends StandardSchemaV1, TActor = unknown> {
+export interface CaseTypeOptions<S extends StandardSchemaV1, TActor = unknown, TCommit = unknown> {
     /**
-     * The case type's name — what `cases.case_type` records. Only the name is
+     * The case type's name — what the persisted case records. Only the name is
      * stored: the code definition floats, meaning existing cases always run
      * against the latest deployed definition.
      */
@@ -24,15 +24,15 @@ export interface CaseTypeOptions<S extends StandardSchemaV1, TActor = unknown> {
     /** The Case State schema (any Standard Schema — zod v4 qualifies). */
     readonly state: S;
     /** The case type's steps, in declaration order (which affordance listings preserve). */
-    readonly steps: readonly StepDefinition<StandardSchemaV1.InferOutput<S>, TActor>[];
+    readonly steps: readonly StepDefinition<StandardSchemaV1.InferOutput<S>, TActor, TCommit>[];
 }
 /** A validated case type definition — the unit the engine registers. */
-export interface CaseTypeDefinition<S extends StandardSchemaV1 = StandardSchemaV1, TActor = unknown> {
+export interface CaseTypeDefinition<S extends StandardSchemaV1 = StandardSchemaV1, TActor = unknown, TCommit = unknown> {
     readonly name: string;
     readonly state: S;
-    readonly steps: readonly StepDefinition<StandardSchemaV1.InferOutput<S>, TActor>[];
+    readonly steps: readonly StepDefinition<StandardSchemaV1.InferOutput<S>, TActor, TCommit>[];
     /** Look up a step by name; `undefined` when the case type declares no such step. */
-    readonly getStep: (name: string) => StepDefinition<StandardSchemaV1.InferOutput<S>, TActor> | undefined;
+    readonly getStep: (name: string) => StepDefinition<StandardSchemaV1.InferOutput<S>, TActor, TCommit> | undefined;
 }
 /**
  * A case type with its schema and actor generics erased — what heterogeneous
@@ -41,7 +41,7 @@ export interface CaseTypeDefinition<S extends StandardSchemaV1 = StandardSchemaV
  * `CaseTypeDefinition<LoanSchema, Servicer>` fit one list; every use is
  * re-anchored by the state schema validation the engine performs on load.
  */
-export type AnyCaseType = CaseTypeDefinition<any, any>;
+export type AnyCaseType<TCommit = unknown> = CaseTypeDefinition<any, any, TCommit>;
 /**
  * Define a case type. Validates loudly at construction time:
  *
@@ -50,4 +50,4 @@ export type AnyCaseType = CaseTypeDefinition<any, any>;
  * - step names must be unique within the case type — a duplicate would make
  *   affordance identity (step × scope key) ambiguous
  */
-export declare const caseType: <S extends StandardSchemaV1, TActor = unknown>(options: CaseTypeOptions<S, TActor>) => CaseTypeDefinition<S, TActor>;
+export declare const caseType: <S extends StandardSchemaV1, TActor = unknown, TCommit = unknown>(options: CaseTypeOptions<S, TActor, TCommit>) => CaseTypeDefinition<S, TActor, TCommit>;