@affordance/core 0.1.0 → 0.2.0

package/dist/execution/execute.d.ts

@@ -3,7 +3,7 @@
  *
  * ```
  *   ┌── transaction ──────────────┐                    ┌── transaction ──────────────┐
- *   │ lock the case row           │                    │ lock the case row           │
+ *   │ serialize the case          │                    │ serialize the case          │
  *   │ take over an expired claim  │   handler runs     │ verify the claim is ours    │
  *   │ re-evaluate the guard  ←────┼── here, outside ───┼→ write state, bump seq      │
  *   │ insert the claim (lease)    │   any transaction  │ run ctx.onCommit writes     │
@@ -20,9 +20,8 @@
  *    same race, handled the same way). A claim that fails rejects with the
  *    *current* unmet conditions and writes nothing at all.
  * 2. **No transaction spans a handler.** Handlers call the outside world;
- *    a transaction held across an escrow API call would tie up a pooled
- *    connection and the case row's lock for as long as the external service
- *    takes to answer. The lease (a `claims` row keyed by case id) carries
+ *    an atomic case operation held across an external call would block other
+ *    work for as long as the provider takes to answer. An expiring claim carries
  *    the exclusivity instead, and a heartbeat keeps it alive.
  * 3. **A crashed handler cannot deadlock a case.** The lease expires. The
  *    next claimant takes the case over, journaling the abandonment; if the
@@ -32,7 +31,8 @@
  */
 import type { GuardEvaluation, Instant } from '../guards/index.js';
 import type { AnyCaseType, RetryOptions } from '../model/index.js';
-import type { DatabaseAccess, Dormancy } from '../store/index.js';
+import type { EngineStorage } from '../storage.js';
+import type { Dormancy } from '../store/index.js';
 import type { StateDelta } from './delta.js';
 import type { LifecyclePort } from './port.js';
 import type { Timers } from './timers.js';
@@ -40,10 +40,10 @@ import type { Timers } from './timers.js';
 export declare const DEFAULT_CLAIM_TTL_MS = 30000;
 export declare const DEFAULT_HEARTBEAT_MS = 5000;
 /** What {@link executeStep} needs from its caller (the engine supplies all of it). */
-export interface ExecutionEnvironment {
-    readonly db: DatabaseAccess;
+export interface ExecutionEnvironment<TCommit = unknown> {
+    readonly storage: EngineStorage<TCommit>;
     /** Resolve a persisted `case_type` name to its registered definition; throws if unknown. */
-    readonly caseTypeFor: (caseTypeName: string) => AnyCaseType;
+    readonly caseTypeFor: (caseTypeName: string) => AnyCaseType<TCommit>;
     readonly claimTtlMs: number;
     readonly heartbeatMs: number;
     /**
@@ -101,10 +101,11 @@ export interface ExecutionResult<TState = unknown> {
 }
 /**
  * What the lifecycle core needs besides storage: the clock, the timers, and
- * the lease timings. Definition resolution is the port's own (its `loadCase`
- * returns the case resolved whole), so it is no part of this interface.
+ * the lease timings and registry. Storage returns raw records; definition
+ * resolution and schema validation belong to this shared lifecycle.
  */
-export interface LifecycleDeps {
+export interface LifecycleDeps<TCommit = unknown> {
+    readonly caseTypeFor: (caseTypeName: string) => AnyCaseType<TCommit>;
     readonly now: () => Date;
     readonly timers: Timers;
     readonly claimTtlMs: number;
@@ -113,11 +114,11 @@ export interface LifecycleDeps {
 /**
  * The lifecycle core: claim → run → commit against a {@link LifecyclePort}.
  *
- * {@link executeStep} binds this to the pg port; the claim state machine's
+ * {@link executeStep} supplies the configured storage adapter; the claim state machine's
  * own tests bind it to an in-memory port instead. Same body either way — the
  * port is the only storage the lifecycle knows.
  */
-export declare const runLifecycle: (port: LifecyclePort, deps: LifecycleDeps, caseId: string, stepName: string, options: ExecuteOptions) => Promise<ExecutionResult>;
+export declare const runLifecycle: <TCommit>(port: LifecyclePort<TCommit>, deps: LifecycleDeps<TCommit>, caseId: string, stepName: string, options: ExecuteOptions) => Promise<ExecutionResult>;
 /**
  * Execute one step on one case: claim it, run its handler, commit the result.
  *
@@ -133,9 +134,9 @@ export declare const runLifecycle: (port: LifecyclePort, deps: LifecycleDeps, ca
  * run out, a `failed` entry is journaled, the case is released, and
  * {@link StepExecutionError} is thrown.
  *
- * This is {@link runLifecycle} bound to the pg port.
+ * This runs the shared lifecycle with the configured storage adapter.
  */
-export declare const executeStep: (env: ExecutionEnvironment, caseId: string, stepName: string, options: ExecuteOptions) => Promise<ExecutionResult>;
+export declare const executeStep: <TCommit>(env: ExecutionEnvironment<TCommit>, caseId: string, stepName: string, options: ExecuteOptions) => Promise<ExecutionResult>;
 /** A committed system run. */
 export interface SystemCommit {
     readonly outcome: 'committed';
@@ -156,13 +157,13 @@ export interface SystemSettled {
 /** How a step the system ran ended — total over every way the lifecycle can answer. */
 export type SystemRunOutcome = SystemCommit | SystemSettled;
 /** What a sweep may ask for beyond the lifecycle's own execute options. */
-export interface SystemRunOptions extends ExecuteOptions {
+export interface SystemRunOptions<TCommit = unknown> extends ExecuteOptions {
     /**
      * Run against this definition instead of the registry's — how a migration
      * executes its synthetic `migrate:<name>` step. First-class here so no
      * sweep has to smuggle a definition in by rewriting `caseTypeFor`.
      */
-    readonly definition?: AnyCaseType;
+    readonly definition?: AnyCaseType<TCommit>;
 }
 /**
  * Turn a throw into the settled value. No classification happens here —
@@ -176,4 +177,4 @@ export declare const settleSystemRun: (error: unknown) => SystemSettled;
  * so the answer is a value — committed (with the result) or settled (with
  * the error) — and each sweep decides what its kind of sweep does with it.
  */
-export declare const runAsSystem: (env: ExecutionEnvironment, caseId: string, stepName: string, options: SystemRunOptions) => Promise<SystemRunOutcome>;
+export declare const runAsSystem: <TCommit>(env: ExecutionEnvironment<TCommit>, caseId: string, stepName: string, options: SystemRunOptions<TCommit>) => Promise<SystemRunOutcome>;

package/dist/execution/execute.js

@@ -3,7 +3,7 @@
  *
  * ```
  *   ┌── transaction ──────────────┐                    ┌── transaction ──────────────┐
- *   │ lock the case row           │                    │ lock the case row           │
+ *   │ serialize the case          │                    │ serialize the case          │
  *   │ take over an expired claim  │   handler runs     │ verify the claim is ours    │
  *   │ re-evaluate the guard  ←────┼── here, outside ───┼→ write state, bump seq      │
  *   │ insert the claim (lease)    │   any transaction  │ run ctx.onCommit writes     │
@@ -20,9 +20,8 @@
  *    same race, handled the same way). A claim that fails rejects with the
  *    *current* unmet conditions and writes nothing at all.
  * 2. **No transaction spans a handler.** Handlers call the outside world;
- *    a transaction held across an escrow API call would tie up a pooled
- *    connection and the case row's lock for as long as the external service
- *    takes to answer. The lease (a `claims` row keyed by case id) carries
+ *    an atomic case operation held across an external call would block other
+ *    work for as long as the provider takes to answer. An expiring claim carries
  *    the exclusivity instead, and a heartbeat keeps it alive.
  * 3. **A crashed handler cannot deadlock a case.** The lease expires. The
  *    next claimant takes the case over, journaling the abandonment; if the
@@ -32,12 +31,10 @@
  */
 import { thrownMessage, toError } from '../errors.js';
 import { toIso } from '../guards/index.js';
-import { registerCorrelation } from '../ingestion/correlation.js';
 import { evaluateTarget, normalizeRetry, resolveTarget, validateStepInput, } from '../model/index.js';
-import { mintId, validateCaseState } from '../store/index.js';
+import { mintId, resolveCase, validateCaseState } from '../store/index.js';
 import { diffState } from './delta.js';
 import { CaseBusyError, ClaimLostError, StepExecutionError, StepNotAvailableError, } from './errors.js';
-import { pgLifecyclePort } from './port.js';
 /** How long a claim survives without a heartbeat, and how often the heartbeat beats. */
 export const DEFAULT_CLAIM_TTL_MS = 30_000;
 export const DEFAULT_HEARTBEAT_MS = 5_000;
@@ -59,7 +56,7 @@ const toJournalError = (error) => error instanceof Error
     : { name: 'UnknownError', message: String(error) };
 /**
  * Resolve whatever claim already sits on this case, inside the claim
- * transaction (the case row is locked, so no two claimants decide this at
+ * transaction (the case operation is serialized, so no two claimants decide this at
  * once): a live claim means the case is busy; an expired one is a crashed
  * handler's abandoned lease — journal the abandonment and take it.
  *
@@ -98,12 +95,12 @@ const clearStaleClaim = async (tx, caseId, claimant) => {
 /**
  * The claim: one short transaction that either takes the case and journals a
  * `claimed` entry, or writes nothing and throws the reason. Loading, guard
- * re-evaluation, and the exclusivity decision all happen under the case row's
- * lock, which is what makes "exactly one of N concurrent attempts claims"
+ * re-evaluation, and the exclusivity decision all happen under the case's
+ * serialization, which is what makes "exactly one of N concurrent attempts claims"
  * true rather than likely.
  */
-const claimCase = async (port, deps, caseId, stepName, options, executionId, claimTtlMs) => port.withCaseLock(caseId, async (tx) => {
-    const { definition, handle, state } = await tx.loadCase();
+const claimCase = async (port, deps, caseId, stepName, options, executionId, claimTtlMs) => port.withCase(caseId, async (tx) => {
+    const { definition, handle, state } = await resolveCase(await tx.loadCase(), deps.caseTypeFor);
     await clearStaleClaim(tx, caseId, executionId);
     const target = resolveTarget(definition, state, stepName, options.scopeKey);
     const scopeKey = target.binding?.key ?? null;
@@ -148,13 +145,12 @@ const claimCase = async (port, deps, caseId, stepName, options, executionId, cla
  */
 const commitExecution = async (port, claim, caseId, stepName, nextState, attempt, dormancy, writes) => {
     // Both inputs are fixed before the transaction opens, so the deep diff —
-    // pure CPU over the whole state document — runs before the row lock is
-    // taken, not while holding it.
+    // pure CPU over the whole state document — runs before case serialization
+    // begins, not while holding it.
     const delta = diffState(claim.state, nextState);
-    return port.withCaseLock(caseId, async (tx) => {
-        await tx.lockCase();
+    return port.withCase(caseId, async (tx) => {
         // The one check that makes a stale write impossible. Changing Case State
-        // requires holding the claim, and taking the claim over replaces this row
+        // requires holding the claim, and taking the claim over replaces this ownership record
         // — so finding our own execution id here means nothing has committed on
         // this case since we claimed it, and the state the handler computed from
         // is still current. An expired-but-undisturbed lease therefore commits
@@ -165,7 +161,7 @@ const commitExecution = async (port, claim, caseId, stepName, nextState, attempt
             throw new ClaimLostError(caseId, claim.executionId, holder);
         }
         const updated = await tx.updateCaseState(nextState, dormancy);
-        await tx.appWrites(writes);
+        await tx.applyEffects(writes);
         const entry = await tx.appendEntry({
             caseId,
             executionId: claim.executionId,
@@ -199,7 +195,7 @@ const commitExecution = async (port, claim, caseId, stepName, nextState, attempt
 /**
  * The lifecycle core: claim → run → commit against a {@link LifecyclePort}.
  *
- * {@link executeStep} binds this to the pg port; the claim state machine's
+ * {@link executeStep} supplies the configured storage adapter; the claim state machine's
  * own tests bind it to an in-memory port instead. Same body either way — the
  * port is the only storage the lifecycle knows.
  */
@@ -240,7 +236,7 @@ export const runLifecycle = async (port, deps, caseId, stepName, options) => {
                 attempt,
                 maxAttempts: policy.maxAttempts,
                 onCommit: (write) => {
-                    writes.push(write);
+                    writes.push({ kind: 'write', write });
                 },
                 // Correlation is an ordinary commit write: the mapping
                 // lands in the same transaction as the state that says the external
@@ -248,14 +244,15 @@ export const runLifecycle = async (port, deps, caseId, stepName, options) => {
                 // its own element — an envelope sent for buyer #7 belongs to
                 // buyer #7 unless the handler says otherwise.
                 correlate: (request) => {
-                    writes.push(async (tx) => {
-                        await registerCorrelation(tx, {
+                    writes.push({
+                        kind: 'correlation',
+                        registration: {
                             ...request,
                             caseId,
                             scopeKey: request.scopeKey === undefined
                                 ? claim.scopeKey
                                 : request.scopeKey,
-                        });
+                        },
                     });
                 },
                 end: () => {
@@ -322,9 +319,9 @@ export const runLifecycle = async (port, deps, caseId, stepName, options) => {
  * run out, a `failed` entry is journaled, the case is released, and
  * {@link StepExecutionError} is thrown.
  *
- * This is {@link runLifecycle} bound to the pg port.
+ * This runs the shared lifecycle with the configured storage adapter.
  */
-export const executeStep = async (env, caseId, stepName, options) => runLifecycle(pgLifecyclePort(env.db, env.caseTypeFor), env, caseId, stepName, options);
+export const executeStep = async (env, caseId, stepName, options) => runLifecycle(env.storage.execution, env, caseId, stepName, options);
 /**
  * Turn a throw into the settled value. No classification happens here —
  * "is this a Refusal" is asked exactly once, where a consumer needs the

package/dist/execution/execute.js.map

@@ -1 +1 @@
-{"version":3,"file":"execute.js","sourceRoot":"","sources":["../../src/execution/execute.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The execution lifecycle: **claim → run → commit**.\n *\n * ```\n *   ┌── transaction ──────────────┐                    ┌── transaction ──────────────┐\n *   │ lock the case row           │                    │ lock the case row           │\n *   │ take over an expired claim  │   handler runs     │ verify the claim is ours    │\n *   │ re-evaluate the guard  ←────┼── here, outside ───┼→ write state, bump seq      │\n *   │ insert the claim (lease)    │   any transaction  │ run ctx.onCommit writes     │\n *   │ journal `claimed`           │   (heartbeating)   │ journal `completed`         │\n *   └─────────────────────────────┘                    └─────────────────────────────┘\n * ```\n *\n * Three things this shape buys, each load-bearing:\n *\n * 1. **Guards advise, handlers enforce.** The affordance a client rendered is\n *    advice; the claim's transactional re-evaluation is the enforcement\n *    moment. State may have moved (another Execution committed) or the\n *    definitions may have (a deploy — definition drift is the\n *    same race, handled the same way). A claim that fails rejects with the\n *    *current* unmet conditions and writes nothing at all.\n * 2. **No transaction spans a handler.** Handlers call the outside world;\n *    a transaction held across an escrow API call would tie up a pooled\n *    connection and the case row's lock for as long as the external service\n *    takes to answer. The lease (a `claims` row keyed by case id) carries\n *    the exclusivity instead, and a heartbeat keeps it alive.\n * 3. **A crashed handler cannot deadlock a case.** The lease expires. The\n *    next claimant takes the case over, journaling the abandonment; if the\n *    zombie ever comes back to commit, it is refused ({@link ClaimLostError})\n *    — at-least-once effects are the handler's problem to deduplicate on\n *    `ctx.executionId`, but a stale state write is the framework's to refuse.\n */\n\nimport { thrownMessage, toError } from '../errors.js'\nimport type { GuardEvaluation, Instant } from '../guards/index.js'\nimport { toIso } from '../guards/index.js'\nimport { registerCorrelation } from '../ingestion/correlation.js'\nimport type {\n  AnyCaseType,\n  CommitWrite,\n  CorrelationRequest,\n  RetryOptions,\n  RetryPolicy,\n  StepTarget,\n} from '../model/index.js'\nimport {\n  evaluateTarget,\n  normalizeRetry,\n  resolveTarget,\n  validateStepInput,\n} from '../model/index.js'\nimport type { DatabaseAccess, Dormancy } from '../store/index.js'\nimport { mintId, validateCaseState } from '../store/index.js'\nimport type { StateDelta } from './delta.js'\nimport { diffState } from './delta.js'\nimport {\n  CaseBusyError,\n  ClaimLostError,\n  StepExecutionError,\n  StepNotAvailableError,\n} from './errors.js'\nimport type { JournalError } from './journal.js'\nimport type { LifecyclePort, LifecycleTx } from './port.js'\nimport { pgLifecyclePort } from './port.js'\nimport type { Timers } from './timers.js'\n\n/** How long a claim survives without a heartbeat, and how often the heartbeat beats. */\nexport const DEFAULT_CLAIM_TTL_MS = 30_000\nexport const DEFAULT_HEARTBEAT_MS = 5_000\n\n/** What {@link executeStep} needs from its caller (the engine supplies all of it). */\nexport interface ExecutionEnvironment {\n  readonly db: DatabaseAccess\n  /** Resolve a persisted `case_type` name to its registered definition; throws if unknown. */\n  readonly caseTypeFor: (caseTypeName: string) => AnyCaseType\n  readonly claimTtlMs: number\n  readonly heartbeatMs: number\n  /**\n   * The clock. Conditions never read it; every process-side \"as of now\"\n   * comes through here, so a test can hand the lifecycle a deterministic\n   * instant instead of building fixtures around far-future dates. (Lease\n   * expiry is judged by the storage adapter's own clock — see\n   * {@link LifecyclePort}.)\n   */\n  readonly now: () => Date\n  /** The process timers — retry delays and the heartbeat. See {@link Timers}. */\n  readonly timers: Timers\n}\n\n/** Options for one execute call. */\nexport interface ExecuteOptions<TActor = unknown> {\n  /** The Actor executing the step; `permits` conditions are evaluated against it. */\n  readonly actor: TActor\n  /** Required for a scoped step, forbidden otherwise — the element's scope key. */\n  readonly scopeKey?: string\n  /** The step's input, validated against its declared input schema before the handler runs. */\n  readonly input?: unknown\n  /** The instant to re-evaluate the guard as of; defaults to now. */\n  readonly asOf?: Instant\n  /** Override the claim lease for this Execution (long-running handler). */\n  readonly claimTtlMs?: number\n  /** Override the heartbeat interval for this Execution. */\n  readonly heartbeatMs?: number\n  /** Override the step's declared retry policy for this Execution. */\n  readonly retry?: RetryOptions\n}\n\n/** A committed Execution — what `execute` resolves to. */\nexport interface ExecutionResult<TState = unknown> {\n  readonly executionId: string\n  readonly caseId: string\n  readonly caseTypeName: string\n  readonly step: string\n  /** Present iff the step is scoped. */\n  readonly scopeKey?: string\n  /** How many attempts ran, including the one that succeeded. */\n  readonly attempts: number\n  /** The claim-time guard evaluation — the enforcement moment, as journaled. */\n  readonly guard: GuardEvaluation\n  /** The committed Case State. */\n  readonly state: TState\n  /** What changed, as JSON Patch. */\n  readonly delta: StateDelta\n  /** The case's sequence counter after this Execution. */\n  readonly seq: number\n  /** `end()` / `reopen()` called by the handler, if either was. */\n  readonly dormancy: Dormancy | null\n  /** The case's dormancy marker after this Execution (ISO-8601 UTC), `null` while active. */\n  readonly endedAt: string | null\n  readonly claimedAt: string\n  readonly committedAt: string\n}\n\n/** A held claim plus everything the run and commit phases need from the claim transaction. */\ninterface Claim {\n  readonly executionId: string\n  readonly caseTypeName: string\n  readonly definition: AnyCaseType\n  readonly target: StepTarget<unknown, unknown>\n  readonly state: unknown\n  readonly input: unknown\n  readonly asOf: string\n  readonly guard: GuardEvaluation\n  readonly claimedAt: string\n  readonly scopeKey: string | null\n  readonly actor: unknown\n}\n\n/**\n * Wraps a failure that must not be retried because retrying is guaranteed to\n * reproduce it: a handler returning a Case State its schema rejects, or a\n * commit refused because the claim is gone.\n */\nclass NonRetryable extends Error {\n  readonly reason: unknown\n  constructor(reason: unknown) {\n    super(thrownMessage(reason))\n    this.name = 'NonRetryable'\n    this.reason = reason\n  }\n}\n\nconst toJournalError = (error: unknown): JournalError =>\n  error instanceof Error\n    ? { name: error.name, message: error.message }\n    : { name: 'UnknownError', message: String(error) }\n\n/**\n * Resolve whatever claim already sits on this case, inside the claim\n * transaction (the case row is locked, so no two claimants decide this at\n * once): a live claim means the case is busy; an expired one is a crashed\n * handler's abandoned lease — journal the abandonment and take it.\n *\n * Both the `expired` entry and the takeover ride on this transaction, so a\n * claim that goes on to fail its guard rolls the abandonment record back and\n * leaves the dead lease in place. That is deliberate: an expired lease blocks\n * nothing, and the abandonment is only a fact worth recording when somebody\n * actually took the case over.\n */\nconst clearStaleClaim = async (\n  tx: LifecycleTx,\n  caseId: string,\n  claimant: string,\n): Promise<void> => {\n  const held = await tx.currentClaim()\n  if (!held) return\n  if (!held.expired) {\n    throw new CaseBusyError(caseId, {\n      executionId: held.executionId,\n      stepName: held.step,\n      scopeKey: held.scopeKey,\n      expiresAt: held.expiresAt,\n    })\n  }\n  await tx.appendEntry({\n    caseId,\n    executionId: held.executionId,\n    entry: 'expired',\n    attempt: held.attempt,\n    step: held.step,\n    scopeKey: held.scopeKey,\n    error: {\n      name: 'ClaimExpiredError',\n      message: `claim expired at ${held.expiresAt} with no terminal entry; case taken over by execution ${claimant}`,\n    },\n  })\n  await tx.deleteClaim(held.executionId)\n}\n\n/**\n * What the lifecycle core needs besides storage: the clock, the timers, and\n * the lease timings. Definition resolution is the port's own (its `loadCase`\n * returns the case resolved whole), so it is no part of this interface.\n */\nexport interface LifecycleDeps {\n  readonly now: () => Date\n  readonly timers: Timers\n  readonly claimTtlMs: number\n  readonly heartbeatMs: number\n}\n\n/**\n * The claim: one short transaction that either takes the case and journals a\n * `claimed` entry, or writes nothing and throws the reason. Loading, guard\n * re-evaluation, and the exclusivity decision all happen under the case row's\n * lock, which is what makes \"exactly one of N concurrent attempts claims\"\n * true rather than likely.\n */\nconst claimCase = async (\n  port: LifecyclePort,\n  deps: LifecycleDeps,\n  caseId: string,\n  stepName: string,\n  options: ExecuteOptions,\n  executionId: string,\n  claimTtlMs: number,\n): Promise<Claim> =>\n  port.withCaseLock(caseId, async (tx) => {\n    const { definition, handle, state } = await tx.loadCase()\n\n    await clearStaleClaim(tx, caseId, executionId)\n\n    const target = resolveTarget(\n      definition,\n      state,\n      stepName,\n      options.scopeKey,\n    ) as StepTarget<unknown, unknown>\n    const scopeKey = target.binding?.key ?? null\n    const input = await validateStepInput(target.step, options.input)\n\n    const asOf = toIso(options.asOf ?? deps.now())\n    const guard = evaluateTarget(target, { actor: options.actor, asOf })\n    if (!guard.available)\n      throw new StepNotAvailableError(caseId, stepName, scopeKey, guard)\n\n    const { claimedAt } = await tx.insertClaim(\n      executionId,\n      stepName,\n      scopeKey,\n      claimTtlMs,\n    )\n\n    await tx.appendEntry({\n      caseId,\n      executionId,\n      entry: 'claimed',\n      attempt: 1,\n      step: stepName,\n      scopeKey,\n      actor: options.actor,\n      input,\n      asOf,\n      guard,\n      // The Case State the guard was evaluated against, stored so audit\n      // reconstruction is exact rather than approximate.\n      state,\n    })\n\n    return {\n      executionId,\n      caseTypeName: handle.caseTypeName,\n      definition,\n      target,\n      state,\n      input,\n      asOf,\n      guard,\n      claimedAt,\n      scopeKey,\n      actor: options.actor,\n    }\n  })\n\n/**\n * The commit: the new Case State, the app's own writes, and the `completed`\n * journal entry, all in one transaction — or none of them.\n */\nconst commitExecution = async (\n  port: LifecyclePort,\n  claim: Claim,\n  caseId: string,\n  stepName: string,\n  nextState: unknown,\n  attempt: number,\n  dormancy: Dormancy | null,\n  writes: readonly CommitWrite[],\n): Promise<ExecutionResult> => {\n  // Both inputs are fixed before the transaction opens, so the deep diff —\n  // pure CPU over the whole state document — runs before the row lock is\n  // taken, not while holding it.\n  const delta = diffState(claim.state, nextState)\n  return port.withCaseLock(caseId, async (tx) => {\n    await tx.lockCase()\n    // The one check that makes a stale write impossible. Changing Case State\n    // requires holding the claim, and taking the claim over replaces this row\n    // — so finding our own execution id here means nothing has committed on\n    // this case since we claimed it, and the state the handler computed from\n    // is still current. An expired-but-undisturbed lease therefore commits\n    // quite legitimately: a handler that overran its lease with no contender\n    // has raced nobody.\n    const holder = (await tx.currentClaim())?.executionId ?? null\n    if (holder !== claim.executionId) {\n      throw new ClaimLostError(caseId, claim.executionId, holder)\n    }\n\n    const updated = await tx.updateCaseState(nextState, dormancy)\n    await tx.appWrites(writes)\n\n    const entry = await tx.appendEntry({\n      caseId,\n      executionId: claim.executionId,\n      entry: 'completed',\n      attempt,\n      step: stepName,\n      scopeKey: claim.scopeKey,\n      actor: claim.actor,\n      delta,\n      dormancy,\n    })\n    await tx.deleteClaim(claim.executionId)\n\n    return {\n      executionId: claim.executionId,\n      caseId,\n      caseTypeName: claim.caseTypeName,\n      step: stepName,\n      ...(claim.scopeKey !== null && { scopeKey: claim.scopeKey }),\n      attempts: attempt,\n      guard: claim.guard,\n      state: nextState,\n      delta,\n      seq: updated.seq,\n      dormancy,\n      endedAt: updated.endedAt,\n      claimedAt: claim.claimedAt,\n      committedAt: entry.recordedAt,\n    }\n  })\n}\n\n/**\n * The lifecycle core: claim → run → commit against a {@link LifecyclePort}.\n *\n * {@link executeStep} binds this to the pg port; the claim state machine's\n * own tests bind it to an in-memory port instead. Same body either way — the\n * port is the only storage the lifecycle knows.\n */\nexport const runLifecycle = async (\n  port: LifecyclePort,\n  deps: LifecycleDeps,\n  caseId: string,\n  stepName: string,\n  options: ExecuteOptions,\n): Promise<ExecutionResult> => {\n  const executionId = mintId('execution')\n  const claimTtlMs = options.claimTtlMs ?? deps.claimTtlMs\n  const heartbeatMs = options.heartbeatMs ?? deps.heartbeatMs\n\n  const claim = await claimCase(\n    port,\n    deps,\n    caseId,\n    stepName,\n    options,\n    executionId,\n    claimTtlMs,\n  )\n  const policy: RetryPolicy =\n    options.retry === undefined\n      ? claim.target.step.retry\n      : normalizeRetry(stepName, options.retry)\n  // Keep the lease alive while the handler runs. Best-effort: a failed beat\n  // just lets the claim age.\n  const stopHeartbeat = deps.timers.every(heartbeatMs, () => {\n    void port.heartbeat(caseId, executionId, claimTtlMs)\n  })\n\n  const journal = (\n    entry: 'attempt-failed' | 'failed',\n    attempt: number,\n    error: JournalError,\n  ): Promise<unknown> =>\n    port.appendEntry({\n      caseId,\n      executionId,\n      entry,\n      attempt,\n      step: stepName,\n      scopeKey: claim.scopeKey,\n      actor: claim.actor,\n      error,\n    })\n\n  try {\n    for (let attempt = 1; ; attempt += 1) {\n      // Per-attempt, never carried over: a failed attempt's registered writes\n      // and dormancy intent are discarded with the attempt that made them.\n      const writes: CommitWrite[] = []\n      let dormancy: Dormancy | null = null\n\n      const context = {\n        executionId,\n        caseId,\n        actor: options.actor,\n        input: claim.input,\n        attempt,\n        maxAttempts: policy.maxAttempts,\n        onCommit: (write: CommitWrite) => {\n          writes.push(write)\n        },\n        // Correlation is an ordinary commit write: the mapping\n        // lands in the same transaction as the state that says the external\n        // interaction was started. A scoped step's registration defaults to\n        // its own element — an envelope sent for buyer #7 belongs to\n        // buyer #7 unless the handler says otherwise.\n        correlate: (request: CorrelationRequest) => {\n          writes.push(async (tx) => {\n            await registerCorrelation(tx, {\n              ...request,\n              caseId,\n              scopeKey:\n                request.scopeKey === undefined\n                  ? claim.scopeKey\n                  : request.scopeKey,\n            })\n          })\n        },\n        end: () => {\n          dormancy = 'ended'\n        },\n        reopen: () => {\n          dormancy = 'reopened'\n        },\n        ...(claim.target.binding !== null && {\n          scope: claim.target.binding.element,\n          scopeKey: claim.target.binding.key,\n        }),\n      }\n\n      try {\n        const returned = await claim.target.step.handler(claim.state, context)\n        const nextState = await validateCaseState(\n          claim.definition,\n          returned,\n          `state returned by step '${stepName}'`,\n        ).catch((error) => {\n          // A handler that returns state its own schema rejects is a\n          // deterministic defect: the next attempt would return it again.\n          throw new NonRetryable(error)\n        })\n        return await commitExecution(\n          port,\n          claim,\n          caseId,\n          stepName,\n          nextState,\n          attempt,\n          dormancy,\n          writes,\n        )\n      } catch (error) {\n        const fatal =\n          error instanceof NonRetryable || error instanceof ClaimLostError\n        const cause = error instanceof NonRetryable ? error.reason : error\n        const journalError = toJournalError(cause)\n\n        if (!fatal && attempt < policy.maxAttempts) {\n          // The attempt-failed entry and the lease's attempt counter (kept\n          // current so a takeover's `expired` entry names the right attempt)\n          // are independent writes — one round trip, not two.\n          await Promise.all([\n            journal('attempt-failed', attempt, journalError),\n            port.bumpAttempt(caseId, executionId, attempt + 1),\n          ])\n          await deps.timers.sleep(policy.delayMs(attempt))\n          continue\n        }\n        await Promise.all([\n          journal('failed', attempt, journalError),\n          port.releaseClaim(caseId, executionId),\n        ])\n        if (cause instanceof ClaimLostError) throw cause\n        throw new StepExecutionError(\n          caseId,\n          executionId,\n          stepName,\n          claim.scopeKey,\n          attempt,\n          cause,\n        )\n      }\n    }\n  } finally {\n    stopHeartbeat()\n  }\n}\n\n/**\n * Execute one step on one case: claim it, run its handler, commit the result.\n *\n * Rejections before anything runs — {@link StepNotAvailableError} (the guard\n * said no), {@link CaseBusyError} (another Execution holds the case),\n * `UnknownStepError` / `ScopeKeyError` (bad address) — write nothing, not\n * even a journal entry: the journal records Executions, and a refused claim\n * never became one.\n *\n * A handler that throws is retried per the step's retry policy (same\n * `executionId`, same claim, same starting state — nothing else can have\n * moved it), each failure journaled as `attempt-failed`. When the attempts\n * run out, a `failed` entry is journaled, the case is released, and\n * {@link StepExecutionError} is thrown.\n *\n * This is {@link runLifecycle} bound to the pg port.\n */\nexport const executeStep = async (\n  env: ExecutionEnvironment,\n  caseId: string,\n  stepName: string,\n  options: ExecuteOptions,\n): Promise<ExecutionResult> =>\n  runLifecycle(\n    pgLifecyclePort(env.db, env.caseTypeFor),\n    env,\n    caseId,\n    stepName,\n    options,\n  )\n\n// ── The system runner ──────────────────────────────────────────────────────\n//\n// `docs/architecture.md` draws a lenient/loud pair wherever the same need\n// recurs: loud for an addressed request, lenient for a sweep. For running a\n// step, loud is `Engine.execute` — it propagates, because somebody named a\n// case and a step and is owed the refusal. The lenient half is here: every\n// sweep (ingestion, migration) runs steps *as the system*, with no caller\n// an exception could reach, and each would otherwise wrap the lifecycle in\n// its own try/catch classification. `runAsSystem` is the lenient half\n// stated once — a total, named outcome the sweeps filter, the same way\n// listings are filters over `selectTargets`.\n\n/** A committed system run. */\nexport interface SystemCommit {\n  readonly outcome: 'committed'\n  readonly result: ExecutionResult\n}\n\n/**\n * A system run that did not commit, carrying whatever the lifecycle threw —\n * a Refusal keeps its identity (its code is the answer, projectable by\n * `isAffordanceError`, never re-derived from a class), a bug or an\n * infrastructure failure passes through as itself. One settled variant, not\n * a refused/failed pair: no sweep ever treated the halves differently, and a\n * discriminant nobody branches on is interface without behaviour.\n */\nexport interface SystemSettled {\n  readonly outcome: 'settled'\n  readonly error: Error\n}\n\n/** How a step the system ran ended — total over every way the lifecycle can answer. */\nexport type SystemRunOutcome = SystemCommit | SystemSettled\n\n/** What a sweep may ask for beyond the lifecycle's own execute options. */\nexport interface SystemRunOptions extends ExecuteOptions {\n  /**\n   * Run against this definition instead of the registry's — how a migration\n   * executes its synthetic `migrate:<name>` step. First-class here so no\n   * sweep has to smuggle a definition in by rewriting `caseTypeFor`.\n   */\n  readonly definition?: AnyCaseType\n}\n\n/**\n * Turn a throw into the settled value. No classification happens here —\n * \"is this a Refusal\" is asked exactly once, where a consumer needs the\n * distinction (ingestion's `classifyDeadLetter`), via `isAffordanceError`.\n */\nexport const settleSystemRun = (error: unknown): SystemSettled => ({\n  outcome: 'settled',\n  error: toError(error),\n})\n\n/**\n * Run one step on behalf of the system and say how it ended. Never throws:\n * a sweep ranges over many cases with no caller waiting on any single one,\n * so the answer is a value — committed (with the result) or settled (with\n * the error) — and each sweep decides what its kind of sweep does with it.\n */\nexport const runAsSystem = async (\n  env: ExecutionEnvironment,\n  caseId: string,\n  stepName: string,\n  options: SystemRunOptions,\n): Promise<SystemRunOutcome> => {\n  const { definition, ...lifecycleOptions } = options\n  const environment: ExecutionEnvironment =\n    definition === undefined ? env : { ...env, caseTypeFor: () => definition }\n  try {\n    return {\n      outcome: 'committed',\n      result: await executeStep(\n        environment,\n        caseId,\n        stepName,\n        lifecycleOptions,\n      ),\n    }\n  } catch (error) {\n    return settleSystemRun(error)\n  }\n}\n"]}
+{"version":3,"file":"execute.js","sourceRoot":"","sources":["../../src/execution/execute.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The execution lifecycle: **claim → run → commit**.\n *\n * ```\n *   ┌── transaction ──────────────┐                    ┌── transaction ──────────────┐\n *   │ serialize the case          │                    │ serialize the case          │\n *   │ take over an expired claim  │   handler runs     │ verify the claim is ours    │\n *   │ re-evaluate the guard  ←────┼── here, outside ───┼→ write state, bump seq      │\n *   │ insert the claim (lease)    │   any transaction  │ run ctx.onCommit writes     │\n *   │ journal `claimed`           │   (heartbeating)   │ journal `completed`         │\n *   └─────────────────────────────┘                    └─────────────────────────────┘\n * ```\n *\n * Three things this shape buys, each load-bearing:\n *\n * 1. **Guards advise, handlers enforce.** The affordance a client rendered is\n *    advice; the claim's transactional re-evaluation is the enforcement\n *    moment. State may have moved (another Execution committed) or the\n *    definitions may have (a deploy — definition drift is the\n *    same race, handled the same way). A claim that fails rejects with the\n *    *current* unmet conditions and writes nothing at all.\n * 2. **No transaction spans a handler.** Handlers call the outside world;\n *    an atomic case operation held across an external call would block other\n *    work for as long as the provider takes to answer. An expiring claim carries\n *    the exclusivity instead, and a heartbeat keeps it alive.\n * 3. **A crashed handler cannot deadlock a case.** The lease expires. The\n *    next claimant takes the case over, journaling the abandonment; if the\n *    zombie ever comes back to commit, it is refused ({@link ClaimLostError})\n *    — at-least-once effects are the handler's problem to deduplicate on\n *    `ctx.executionId`, but a stale state write is the framework's to refuse.\n */\n\nimport { thrownMessage, toError } from '../errors.js'\nimport type { GuardEvaluation, Instant } from '../guards/index.js'\nimport { toIso } from '../guards/index.js'\nimport type {\n  AnyCaseType,\n  CommitEffect,\n  CommitWrite,\n  CorrelationRequest,\n  RetryOptions,\n  RetryPolicy,\n  StepTarget,\n} from '../model/index.js'\nimport {\n  evaluateTarget,\n  normalizeRetry,\n  resolveTarget,\n  validateStepInput,\n} from '../model/index.js'\nimport type { EngineStorage } from '../storage.js'\nimport type { Dormancy } from '../store/index.js'\nimport { mintId, resolveCase, validateCaseState } from '../store/index.js'\nimport type { StateDelta } from './delta.js'\nimport { diffState } from './delta.js'\nimport {\n  CaseBusyError,\n  ClaimLostError,\n  StepExecutionError,\n  StepNotAvailableError,\n} from './errors.js'\nimport type { JournalError } from './journal.js'\nimport type { LifecyclePort, LifecycleTx } from './port.js'\nimport type { Timers } from './timers.js'\n\n/** How long a claim survives without a heartbeat, and how often the heartbeat beats. */\nexport const DEFAULT_CLAIM_TTL_MS = 30_000\nexport const DEFAULT_HEARTBEAT_MS = 5_000\n\n/** What {@link executeStep} needs from its caller (the engine supplies all of it). */\nexport interface ExecutionEnvironment<TCommit = unknown> {\n  readonly storage: EngineStorage<TCommit>\n  /** Resolve a persisted `case_type` name to its registered definition; throws if unknown. */\n  readonly caseTypeFor: (caseTypeName: string) => AnyCaseType<TCommit>\n  readonly claimTtlMs: number\n  readonly heartbeatMs: number\n  /**\n   * The clock. Conditions never read it; every process-side \"as of now\"\n   * comes through here, so a test can hand the lifecycle a deterministic\n   * instant instead of building fixtures around far-future dates. (Lease\n   * expiry is judged by the storage adapter's own clock — see\n   * {@link LifecyclePort}.)\n   */\n  readonly now: () => Date\n  /** The process timers — retry delays and the heartbeat. See {@link Timers}. */\n  readonly timers: Timers\n}\n\n/** Options for one execute call. */\nexport interface ExecuteOptions<TActor = unknown> {\n  /** The Actor executing the step; `permits` conditions are evaluated against it. */\n  readonly actor: TActor\n  /** Required for a scoped step, forbidden otherwise — the element's scope key. */\n  readonly scopeKey?: string\n  /** The step's input, validated against its declared input schema before the handler runs. */\n  readonly input?: unknown\n  /** The instant to re-evaluate the guard as of; defaults to now. */\n  readonly asOf?: Instant\n  /** Override the claim lease for this Execution (long-running handler). */\n  readonly claimTtlMs?: number\n  /** Override the heartbeat interval for this Execution. */\n  readonly heartbeatMs?: number\n  /** Override the step's declared retry policy for this Execution. */\n  readonly retry?: RetryOptions\n}\n\n/** A committed Execution — what `execute` resolves to. */\nexport interface ExecutionResult<TState = unknown> {\n  readonly executionId: string\n  readonly caseId: string\n  readonly caseTypeName: string\n  readonly step: string\n  /** Present iff the step is scoped. */\n  readonly scopeKey?: string\n  /** How many attempts ran, including the one that succeeded. */\n  readonly attempts: number\n  /** The claim-time guard evaluation — the enforcement moment, as journaled. */\n  readonly guard: GuardEvaluation\n  /** The committed Case State. */\n  readonly state: TState\n  /** What changed, as JSON Patch. */\n  readonly delta: StateDelta\n  /** The case's sequence counter after this Execution. */\n  readonly seq: number\n  /** `end()` / `reopen()` called by the handler, if either was. */\n  readonly dormancy: Dormancy | null\n  /** The case's dormancy marker after this Execution (ISO-8601 UTC), `null` while active. */\n  readonly endedAt: string | null\n  readonly claimedAt: string\n  readonly committedAt: string\n}\n\n/** A held claim plus everything the run and commit phases need from the claim transaction. */\ninterface Claim<TCommit> {\n  readonly executionId: string\n  readonly caseTypeName: string\n  readonly definition: AnyCaseType<TCommit>\n  readonly target: StepTarget<unknown, unknown, TCommit>\n  readonly state: unknown\n  readonly input: unknown\n  readonly asOf: string\n  readonly guard: GuardEvaluation\n  readonly claimedAt: string\n  readonly scopeKey: string | null\n  readonly actor: unknown\n}\n\n/**\n * Wraps a failure that must not be retried because retrying is guaranteed to\n * reproduce it: a handler returning a Case State its schema rejects, or a\n * commit refused because the claim is gone.\n */\nclass NonRetryable extends Error {\n  readonly reason: unknown\n  constructor(reason: unknown) {\n    super(thrownMessage(reason))\n    this.name = 'NonRetryable'\n    this.reason = reason\n  }\n}\n\nconst toJournalError = (error: unknown): JournalError =>\n  error instanceof Error\n    ? { name: error.name, message: error.message }\n    : { name: 'UnknownError', message: String(error) }\n\n/**\n * Resolve whatever claim already sits on this case, inside the claim\n * transaction (the case operation is serialized, so no two claimants decide this at\n * once): a live claim means the case is busy; an expired one is a crashed\n * handler's abandoned lease — journal the abandonment and take it.\n *\n * Both the `expired` entry and the takeover ride on this transaction, so a\n * claim that goes on to fail its guard rolls the abandonment record back and\n * leaves the dead lease in place. That is deliberate: an expired lease blocks\n * nothing, and the abandonment is only a fact worth recording when somebody\n * actually took the case over.\n */\nconst clearStaleClaim = async <TCommit>(\n  tx: LifecycleTx<TCommit>,\n  caseId: string,\n  claimant: string,\n): Promise<void> => {\n  const held = await tx.currentClaim()\n  if (!held) return\n  if (!held.expired) {\n    throw new CaseBusyError(caseId, {\n      executionId: held.executionId,\n      stepName: held.step,\n      scopeKey: held.scopeKey,\n      expiresAt: held.expiresAt,\n    })\n  }\n  await tx.appendEntry({\n    caseId,\n    executionId: held.executionId,\n    entry: 'expired',\n    attempt: held.attempt,\n    step: held.step,\n    scopeKey: held.scopeKey,\n    error: {\n      name: 'ClaimExpiredError',\n      message: `claim expired at ${held.expiresAt} with no terminal entry; case taken over by execution ${claimant}`,\n    },\n  })\n  await tx.deleteClaim(held.executionId)\n}\n\n/**\n * What the lifecycle core needs besides storage: the clock, the timers, and\n * the lease timings and registry. Storage returns raw records; definition\n * resolution and schema validation belong to this shared lifecycle.\n */\nexport interface LifecycleDeps<TCommit = unknown> {\n  readonly caseTypeFor: (caseTypeName: string) => AnyCaseType<TCommit>\n  readonly now: () => Date\n  readonly timers: Timers\n  readonly claimTtlMs: number\n  readonly heartbeatMs: number\n}\n\n/**\n * The claim: one short transaction that either takes the case and journals a\n * `claimed` entry, or writes nothing and throws the reason. Loading, guard\n * re-evaluation, and the exclusivity decision all happen under the case's\n * serialization, which is what makes \"exactly one of N concurrent attempts claims\"\n * true rather than likely.\n */\nconst claimCase = async <TCommit>(\n  port: LifecyclePort<TCommit>,\n  deps: LifecycleDeps<TCommit>,\n  caseId: string,\n  stepName: string,\n  options: ExecuteOptions,\n  executionId: string,\n  claimTtlMs: number,\n): Promise<Claim<TCommit>> =>\n  port.withCase(caseId, async (tx) => {\n    const { definition, handle, state } = await resolveCase(\n      await tx.loadCase(),\n      deps.caseTypeFor,\n    )\n\n    await clearStaleClaim(tx, caseId, executionId)\n\n    const target = resolveTarget(\n      definition,\n      state,\n      stepName,\n      options.scopeKey,\n    ) as StepTarget<unknown, unknown, TCommit>\n    const scopeKey = target.binding?.key ?? null\n    const input = await validateStepInput(target.step, options.input)\n\n    const asOf = toIso(options.asOf ?? deps.now())\n    const guard = evaluateTarget(target, { actor: options.actor, asOf })\n    if (!guard.available)\n      throw new StepNotAvailableError(caseId, stepName, scopeKey, guard)\n\n    const { claimedAt } = await tx.insertClaim(\n      executionId,\n      stepName,\n      scopeKey,\n      claimTtlMs,\n    )\n\n    await tx.appendEntry({\n      caseId,\n      executionId,\n      entry: 'claimed',\n      attempt: 1,\n      step: stepName,\n      scopeKey,\n      actor: options.actor,\n      input,\n      asOf,\n      guard,\n      // The Case State the guard was evaluated against, stored so audit\n      // reconstruction is exact rather than approximate.\n      state,\n    })\n\n    return {\n      executionId,\n      caseTypeName: handle.caseTypeName,\n      definition,\n      target,\n      state,\n      input,\n      asOf,\n      guard,\n      claimedAt,\n      scopeKey,\n      actor: options.actor,\n    }\n  })\n\n/**\n * The commit: the new Case State, the app's own writes, and the `completed`\n * journal entry, all in one transaction — or none of them.\n */\nconst commitExecution = async <TCommit>(\n  port: LifecyclePort<TCommit>,\n  claim: Claim<TCommit>,\n  caseId: string,\n  stepName: string,\n  nextState: unknown,\n  attempt: number,\n  dormancy: Dormancy | null,\n  writes: readonly CommitEffect<TCommit>[],\n): Promise<ExecutionResult> => {\n  // Both inputs are fixed before the transaction opens, so the deep diff —\n  // pure CPU over the whole state document — runs before case serialization\n  // begins, not while holding it.\n  const delta = diffState(claim.state, nextState)\n  return port.withCase(caseId, async (tx) => {\n    // The one check that makes a stale write impossible. Changing Case State\n    // requires holding the claim, and taking the claim over replaces this ownership record\n    // — so finding our own execution id here means nothing has committed on\n    // this case since we claimed it, and the state the handler computed from\n    // is still current. An expired-but-undisturbed lease therefore commits\n    // quite legitimately: a handler that overran its lease with no contender\n    // has raced nobody.\n    const holder = (await tx.currentClaim())?.executionId ?? null\n    if (holder !== claim.executionId) {\n      throw new ClaimLostError(caseId, claim.executionId, holder)\n    }\n\n    const updated = await tx.updateCaseState(nextState, dormancy)\n    await tx.applyEffects(writes)\n\n    const entry = await tx.appendEntry({\n      caseId,\n      executionId: claim.executionId,\n      entry: 'completed',\n      attempt,\n      step: stepName,\n      scopeKey: claim.scopeKey,\n      actor: claim.actor,\n      delta,\n      dormancy,\n    })\n    await tx.deleteClaim(claim.executionId)\n\n    return {\n      executionId: claim.executionId,\n      caseId,\n      caseTypeName: claim.caseTypeName,\n      step: stepName,\n      ...(claim.scopeKey !== null && { scopeKey: claim.scopeKey }),\n      attempts: attempt,\n      guard: claim.guard,\n      state: nextState,\n      delta,\n      seq: updated.seq,\n      dormancy,\n      endedAt: updated.endedAt,\n      claimedAt: claim.claimedAt,\n      committedAt: entry.recordedAt,\n    }\n  })\n}\n\n/**\n * The lifecycle core: claim → run → commit against a {@link LifecyclePort}.\n *\n * {@link executeStep} supplies the configured storage adapter; the claim state machine's\n * own tests bind it to an in-memory port instead. Same body either way — the\n * port is the only storage the lifecycle knows.\n */\nexport const runLifecycle = async <TCommit>(\n  port: LifecyclePort<TCommit>,\n  deps: LifecycleDeps<TCommit>,\n  caseId: string,\n  stepName: string,\n  options: ExecuteOptions,\n): Promise<ExecutionResult> => {\n  const executionId = mintId('execution')\n  const claimTtlMs = options.claimTtlMs ?? deps.claimTtlMs\n  const heartbeatMs = options.heartbeatMs ?? deps.heartbeatMs\n\n  const claim = await claimCase(\n    port,\n    deps,\n    caseId,\n    stepName,\n    options,\n    executionId,\n    claimTtlMs,\n  )\n  const policy: RetryPolicy =\n    options.retry === undefined\n      ? claim.target.step.retry\n      : normalizeRetry(stepName, options.retry)\n  // Keep the lease alive while the handler runs. Best-effort: a failed beat\n  // just lets the claim age.\n  const stopHeartbeat = deps.timers.every(heartbeatMs, () => {\n    void port.heartbeat(caseId, executionId, claimTtlMs)\n  })\n\n  const journal = (\n    entry: 'attempt-failed' | 'failed',\n    attempt: number,\n    error: JournalError,\n  ): Promise<unknown> =>\n    port.appendEntry({\n      caseId,\n      executionId,\n      entry,\n      attempt,\n      step: stepName,\n      scopeKey: claim.scopeKey,\n      actor: claim.actor,\n      error,\n    })\n\n  try {\n    for (let attempt = 1; ; attempt += 1) {\n      // Per-attempt, never carried over: a failed attempt's registered writes\n      // and dormancy intent are discarded with the attempt that made them.\n      const writes: CommitEffect<TCommit>[] = []\n      let dormancy: Dormancy | null = null\n\n      const context = {\n        executionId,\n        caseId,\n        actor: options.actor,\n        input: claim.input,\n        attempt,\n        maxAttempts: policy.maxAttempts,\n        onCommit: (write: CommitWrite<TCommit>) => {\n          writes.push({ kind: 'write', write })\n        },\n        // Correlation is an ordinary commit write: the mapping\n        // lands in the same transaction as the state that says the external\n        // interaction was started. A scoped step's registration defaults to\n        // its own element — an envelope sent for buyer #7 belongs to\n        // buyer #7 unless the handler says otherwise.\n        correlate: (request: CorrelationRequest) => {\n          writes.push({\n            kind: 'correlation',\n            registration: {\n              ...request,\n              caseId,\n              scopeKey:\n                request.scopeKey === undefined\n                  ? claim.scopeKey\n                  : request.scopeKey,\n            },\n          })\n        },\n        end: () => {\n          dormancy = 'ended'\n        },\n        reopen: () => {\n          dormancy = 'reopened'\n        },\n        ...(claim.target.binding !== null && {\n          scope: claim.target.binding.element,\n          scopeKey: claim.target.binding.key,\n        }),\n      }\n\n      try {\n        const returned = await claim.target.step.handler(claim.state, context)\n        const nextState = await validateCaseState(\n          claim.definition,\n          returned,\n          `state returned by step '${stepName}'`,\n        ).catch((error) => {\n          // A handler that returns state its own schema rejects is a\n          // deterministic defect: the next attempt would return it again.\n          throw new NonRetryable(error)\n        })\n        return await commitExecution(\n          port,\n          claim,\n          caseId,\n          stepName,\n          nextState,\n          attempt,\n          dormancy,\n          writes,\n        )\n      } catch (error) {\n        const fatal =\n          error instanceof NonRetryable || error instanceof ClaimLostError\n        const cause = error instanceof NonRetryable ? error.reason : error\n        const journalError = toJournalError(cause)\n\n        if (!fatal && attempt < policy.maxAttempts) {\n          // The attempt-failed entry and the lease's attempt counter (kept\n          // current so a takeover's `expired` entry names the right attempt)\n          // are independent writes — one round trip, not two.\n          await Promise.all([\n            journal('attempt-failed', attempt, journalError),\n            port.bumpAttempt(caseId, executionId, attempt + 1),\n          ])\n          await deps.timers.sleep(policy.delayMs(attempt))\n          continue\n        }\n        await Promise.all([\n          journal('failed', attempt, journalError),\n          port.releaseClaim(caseId, executionId),\n        ])\n        if (cause instanceof ClaimLostError) throw cause\n        throw new StepExecutionError(\n          caseId,\n          executionId,\n          stepName,\n          claim.scopeKey,\n          attempt,\n          cause,\n        )\n      }\n    }\n  } finally {\n    stopHeartbeat()\n  }\n}\n\n/**\n * Execute one step on one case: claim it, run its handler, commit the result.\n *\n * Rejections before anything runs — {@link StepNotAvailableError} (the guard\n * said no), {@link CaseBusyError} (another Execution holds the case),\n * `UnknownStepError` / `ScopeKeyError` (bad address) — write nothing, not\n * even a journal entry: the journal records Executions, and a refused claim\n * never became one.\n *\n * A handler that throws is retried per the step's retry policy (same\n * `executionId`, same claim, same starting state — nothing else can have\n * moved it), each failure journaled as `attempt-failed`. When the attempts\n * run out, a `failed` entry is journaled, the case is released, and\n * {@link StepExecutionError} is thrown.\n *\n * This runs the shared lifecycle with the configured storage adapter.\n */\nexport const executeStep = async <TCommit>(\n  env: ExecutionEnvironment<TCommit>,\n  caseId: string,\n  stepName: string,\n  options: ExecuteOptions,\n): Promise<ExecutionResult> =>\n  runLifecycle(env.storage.execution, env, caseId, stepName, options)\n\n// ── The system runner ──────────────────────────────────────────────────────\n//\n// `docs/architecture.md` draws a lenient/loud pair wherever the same need\n// recurs: loud for an addressed request, lenient for a sweep. For running a\n// step, loud is `Engine.execute` — it propagates, because somebody named a\n// case and a step and is owed the refusal. The lenient half is here: every\n// sweep (ingestion, migration) runs steps *as the system*, with no caller\n// an exception could reach, and each would otherwise wrap the lifecycle in\n// its own try/catch classification. `runAsSystem` is the lenient half\n// stated once — a total, named outcome the sweeps filter, the same way\n// listings are filters over `selectTargets`.\n\n/** A committed system run. */\nexport interface SystemCommit {\n  readonly outcome: 'committed'\n  readonly result: ExecutionResult\n}\n\n/**\n * A system run that did not commit, carrying whatever the lifecycle threw —\n * a Refusal keeps its identity (its code is the answer, projectable by\n * `isAffordanceError`, never re-derived from a class), a bug or an\n * infrastructure failure passes through as itself. One settled variant, not\n * a refused/failed pair: no sweep ever treated the halves differently, and a\n * discriminant nobody branches on is interface without behaviour.\n */\nexport interface SystemSettled {\n  readonly outcome: 'settled'\n  readonly error: Error\n}\n\n/** How a step the system ran ended — total over every way the lifecycle can answer. */\nexport type SystemRunOutcome = SystemCommit | SystemSettled\n\n/** What a sweep may ask for beyond the lifecycle's own execute options. */\nexport interface SystemRunOptions<TCommit = unknown> extends ExecuteOptions {\n  /**\n   * Run against this definition instead of the registry's — how a migration\n   * executes its synthetic `migrate:<name>` step. First-class here so no\n   * sweep has to smuggle a definition in by rewriting `caseTypeFor`.\n   */\n  readonly definition?: AnyCaseType<TCommit>\n}\n\n/**\n * Turn a throw into the settled value. No classification happens here —\n * \"is this a Refusal\" is asked exactly once, where a consumer needs the\n * distinction (ingestion's `classifyDeadLetter`), via `isAffordanceError`.\n */\nexport const settleSystemRun = (error: unknown): SystemSettled => ({\n  outcome: 'settled',\n  error: toError(error),\n})\n\n/**\n * Run one step on behalf of the system and say how it ended. Never throws:\n * a sweep ranges over many cases with no caller waiting on any single one,\n * so the answer is a value — committed (with the result) or settled (with\n * the error) — and each sweep decides what its kind of sweep does with it.\n */\nexport const runAsSystem = async <TCommit>(\n  env: ExecutionEnvironment<TCommit>,\n  caseId: string,\n  stepName: string,\n  options: SystemRunOptions<TCommit>,\n): Promise<SystemRunOutcome> => {\n  const { definition, ...lifecycleOptions } = options\n  const environment: ExecutionEnvironment<TCommit> =\n    definition === undefined ? env : { ...env, caseTypeFor: () => definition }\n  try {\n    return {\n      outcome: 'committed',\n      result: await executeStep(\n        environment,\n        caseId,\n        stepName,\n        lifecycleOptions,\n      ),\n    }\n  } catch (error) {\n    return settleSystemRun(error)\n  }\n}\n"]}

package/dist/execution/index.d.ts

@@ -15,11 +15,9 @@ export { CaseBusyError, ClaimLostError, StepExecutionError, StepNotAvailableErro
 export type { ExecuteOptions, ExecutionEnvironment, ExecutionResult, LifecycleDeps, SystemCommit, SystemRunOptions, SystemRunOutcome, SystemSettled, } from './execute.js';
 export { DEFAULT_CLAIM_TTL_MS, DEFAULT_HEARTBEAT_MS, executeStep, runAsSystem, runLifecycle, settleSystemRun, } from './execute.js';
 export type { ClaimedEntryInput, ClaimedJournalEntry, CompletedEntryInput, ExecutionRecord, ExecutionStatus, FailureEntryInput, JournalEntry, JournalEntryColumns, JournalEntryInput, JournalEntryType, JournalError, JournalFilter, } from './journal.js';
-export { appendEntry, foldExecutions, isClaimedEntry, projectEntry, readJournal, } from './journal.js';
+export { foldExecutions, isClaimedEntry, projectEntry, } from './journal.js';
 export type { HeldClaim, LifecyclePort, LifecycleTx } from './port.js';
-export { pgLifecyclePort } from './port.js';
 export type { GuardReplay } from './replay.js';
 export { replayGuard } from './replay.js';
 export type { Timers } from './timers.js';
 export { realTimers } from './timers.js';
-export { withTransaction } from './transaction.js';

package/dist/execution/index.js

@@ -12,9 +12,7 @@
 export { diffState, jsonEqual } from './delta.js';
 export { CaseBusyError, ClaimLostError, StepExecutionError, StepNotAvailableError, stepLabel, } from './errors.js';
 export { DEFAULT_CLAIM_TTL_MS, DEFAULT_HEARTBEAT_MS, executeStep, runAsSystem, runLifecycle, settleSystemRun, } from './execute.js';
-export { appendEntry, foldExecutions, isClaimedEntry, projectEntry, readJournal, } from './journal.js';
-export { pgLifecyclePort } from './port.js';
+export { foldExecutions, isClaimedEntry, projectEntry, } from './journal.js';
 export { replayGuard } from './replay.js';
 export { realTimers } from './timers.js';
-export { withTransaction } from './transaction.js';
 //# sourceMappingURL=index.js.map

package/dist/execution/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/execution/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,EACL,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,SAAS,GACV,MAAM,aAAa,CAAA;AAWpB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,YAAY,EACZ,eAAe,GAChB,MAAM,cAAc,CAAA;AAerB,OAAO,EACL,WAAW,EACX,cAAc,EACd,cAAc,EACd,YAAY,EACZ,WAAW,GACZ,MAAM,cAAc,CAAA;AAErB,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAE3C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA","sourcesContent":["/**\n * The execution lifecycle and the journal.\n *\n * An **Execution** is one recorded run of a step on a case (CONTEXT.md): a\n * claim that re-evaluates the guard transactionally, a handler run outside\n * any transaction, and a commit that writes the new Case State together with\n * the journal entry describing it. The **journal** is the immutable,\n * append-only record those Executions leave behind.\n *\n * See `execute.ts` for the lifecycle's shape and the reasoning behind it.\n */\n\nexport type { PatchOp, StateDelta } from './delta.js'\nexport { diffState, jsonEqual } from './delta.js'\nexport {\n  CaseBusyError,\n  ClaimLostError,\n  StepExecutionError,\n  StepNotAvailableError,\n  stepLabel,\n} from './errors.js'\nexport type {\n  ExecuteOptions,\n  ExecutionEnvironment,\n  ExecutionResult,\n  LifecycleDeps,\n  SystemCommit,\n  SystemRunOptions,\n  SystemRunOutcome,\n  SystemSettled,\n} from './execute.js'\nexport {\n  DEFAULT_CLAIM_TTL_MS,\n  DEFAULT_HEARTBEAT_MS,\n  executeStep,\n  runAsSystem,\n  runLifecycle,\n  settleSystemRun,\n} from './execute.js'\nexport type {\n  ClaimedEntryInput,\n  ClaimedJournalEntry,\n  CompletedEntryInput,\n  ExecutionRecord,\n  ExecutionStatus,\n  FailureEntryInput,\n  JournalEntry,\n  JournalEntryColumns,\n  JournalEntryInput,\n  JournalEntryType,\n  JournalError,\n  JournalFilter,\n} from './journal.js'\nexport {\n  appendEntry,\n  foldExecutions,\n  isClaimedEntry,\n  projectEntry,\n  readJournal,\n} from './journal.js'\nexport type { HeldClaim, LifecyclePort, LifecycleTx } from './port.js'\nexport { pgLifecyclePort } from './port.js'\nexport type { GuardReplay } from './replay.js'\nexport { replayGuard } from './replay.js'\nexport type { Timers } from './timers.js'\nexport { realTimers } from './timers.js'\nexport { withTransaction } from './transaction.js'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/execution/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,EACL,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,SAAS,GACV,MAAM,aAAa,CAAA;AAWpB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,YAAY,EACZ,eAAe,GAChB,MAAM,cAAc,CAAA;AAerB,OAAO,EACL,cAAc,EACd,cAAc,EACd,YAAY,GACb,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA","sourcesContent":["/**\n * The execution lifecycle and the journal.\n *\n * An **Execution** is one recorded run of a step on a case (CONTEXT.md): a\n * claim that re-evaluates the guard transactionally, a handler run outside\n * any transaction, and a commit that writes the new Case State together with\n * the journal entry describing it. The **journal** is the immutable,\n * append-only record those Executions leave behind.\n *\n * See `execute.ts` for the lifecycle's shape and the reasoning behind it.\n */\n\nexport type { PatchOp, StateDelta } from './delta.js'\nexport { diffState, jsonEqual } from './delta.js'\nexport {\n  CaseBusyError,\n  ClaimLostError,\n  StepExecutionError,\n  StepNotAvailableError,\n  stepLabel,\n} from './errors.js'\nexport type {\n  ExecuteOptions,\n  ExecutionEnvironment,\n  ExecutionResult,\n  LifecycleDeps,\n  SystemCommit,\n  SystemRunOptions,\n  SystemRunOutcome,\n  SystemSettled,\n} from './execute.js'\nexport {\n  DEFAULT_CLAIM_TTL_MS,\n  DEFAULT_HEARTBEAT_MS,\n  executeStep,\n  runAsSystem,\n  runLifecycle,\n  settleSystemRun,\n} from './execute.js'\nexport type {\n  ClaimedEntryInput,\n  ClaimedJournalEntry,\n  CompletedEntryInput,\n  ExecutionRecord,\n  ExecutionStatus,\n  FailureEntryInput,\n  JournalEntry,\n  JournalEntryColumns,\n  JournalEntryInput,\n  JournalEntryType,\n  JournalError,\n  JournalFilter,\n} from './journal.js'\nexport {\n  foldExecutions,\n  isClaimedEntry,\n  projectEntry,\n} from './journal.js'\nexport type { HeldClaim, LifecyclePort, LifecycleTx } from './port.js'\nexport type { GuardReplay } from './replay.js'\nexport { replayGuard } from './replay.js'\nexport type { Timers } from './timers.js'\nexport { realTimers } from './timers.js'\n"]}

package/dist/execution/journal.d.ts

@@ -9,12 +9,10 @@
  * scope key, actor). Per-track audit — "everything that happened on buyer
  * #7" — is therefore a filter, not a reconstruction.
  *
- * Only inserts exist in this module. There is no update or delete path for a
- * journal row anywhere in the library.
+ * This module defines journal evidence and its projections. Storage adapters
+ * append and read the records; the engine never rewrites historical entries.
  */
-import type { JournalEntryKind } from '@affordance/contract';
 import type { GuardEvaluation } from '../guards/index.js';
-import type { Queryable } from '../store/index.js';
 import type { StateDelta } from './delta.js';
 /**
  * Which lifecycle moment an entry records.
@@ -27,7 +25,8 @@ import type { StateDelta } from './delta.js';
  * - `expired` — the claim lapsed without a terminal entry: the handler's
  *   process died, and a later claimant recorded the abandonment
  */
-export type JournalEntryType = JournalEntryKind;
+export declare const JOURNAL_ENTRY_KINDS: readonly ["claimed", "attempt-failed", "completed", "failed", "expired"];
+export type JournalEntryType = (typeof JOURNAL_ENTRY_KINDS)[number];
 /** A failure as journaled — the error's identity, not a live Error object. */
 export interface JournalError {
     readonly name: string;
@@ -145,13 +144,6 @@ export type JournalEntryColumns = Omit<JournalEntry, 'ordinal' | 'id' | 'recorde
  * a second, divergent copy of the journal's semantics.
  */
 export declare const projectEntry: (input: JournalEntryInput) => JournalEntryColumns;
-/** Append one entry. Inserts only — journal rows are never updated or deleted. */
-export declare const appendEntry: (db: Queryable, input: JournalEntryInput) => Promise<JournalEntry>;
-/**
- * Read a case's journal in insertion order, oldest first. With no filter this
- * is the whole story of the case; with `scopeKey` it is one track's audit.
- */
-export declare const readJournal: (db: Queryable, caseId: string, filter?: JournalFilter) => Promise<readonly JournalEntry[]>;
 /** How an Execution ended up, folded from its entries. */
 export type ExecutionStatus = 'in-progress' | 'completed' | 'failed' | 'expired';
 /**

package/dist/execution/journal.js

@@ -9,54 +9,33 @@
  * scope key, actor). Per-track audit — "everything that happened on buyer
  * #7" — is therefore a filter, not a reconstruction.
  *
- * Only inserts exist in this module. There is no update or delete path for a
- * journal row anywhere in the library.
+ * This module defines journal evidence and its projections. Storage adapters
+ * append and read the records; the engine never rewrites historical entries.
  */
-import { FRAMEWORK_SCHEMA, mintId, sqlWhere } from '../store/index.js';
-const JOURNAL = `${FRAMEWORK_SCHEMA}.journal`;
-const JOURNAL_COLUMNS = 'ordinal, id, case_id, execution_id, entry, attempt, step, scope_key, actor, input, as_of, guard, state, delta, dormancy, error, recorded_at';
+/**
+ * Which lifecycle moment an entry records.
+ *
+ * - `claimed` — the claim's transactional guard re-evaluation passed and the
+ *   Execution took the case; carries `guard`, `asOf` and `state`
+ * - `attempt-failed` — one attempt threw and another will follow
+ * - `completed` — the handler's Case State was committed; carries `delta`
+ * - `failed` — retries exhausted (or a deterministic defect); case released
+ * - `expired` — the claim lapsed without a terminal entry: the handler's
+ *   process died, and a later claimant recorded the abandonment
+ */
+export const JOURNAL_ENTRY_KINDS = [
+    'claimed',
+    'attempt-failed',
+    'completed',
+    'failed',
+    'expired',
+];
 /**
  * Narrow a read entry to the claimed moment. The one predicate every reader
  * of claim-time evidence (`foldExecutions`, audit replay) shares, so what
  * counts as "carries the evidence" is decided once.
  */
 export const isClaimedEntry = (entry) => entry.entry === 'claimed' && entry.guard !== null && entry.asOf !== null;
-const toEntry = (row) => ({
-    ordinal: Number(row.ordinal),
-    id: row.id,
-    caseId: row.case_id,
-    executionId: row.execution_id,
-    entry: row.entry,
-    attempt: row.attempt,
-    step: row.step,
-    scopeKey: row.scope_key,
-    actor: row.actor,
-    input: row.input,
-    asOf: row.as_of === null ? null : row.as_of.toISOString(),
-    guard: row.guard,
-    state: row.state,
-    delta: row.delta,
-    dormancy: row.dormancy,
-    error: row.error,
-    recordedAt: row.recorded_at.toISOString(),
-});
-/**
- * Serialize a value for a jsonb column. Actors and inputs are app-owned
- * shapes, and a journal append must never be the thing that fails an
- * otherwise-good Execution: a value that will not stringify (a cycle, a
- * BigInt) is journaled as a marker string rather than thrown over.
- */
-const toJsonb = (value) => {
-    if (value === undefined || value === null)
-        return null;
-    try {
-        const json = JSON.stringify(value);
-        return json === undefined ? null : json;
-    }
-    catch {
-        return JSON.stringify({ '~unserializable': String(value) });
-    }
-};
 /**
  * Project an input onto a stored entry's fields — the one statement of the
  * defaulting and of which fields accompany which lifecycle moment. Every
@@ -85,58 +64,6 @@ export const projectEntry = (input) => {
         error: failure?.error ?? null,
     };
 };
-/** Append one entry. Inserts only — journal rows are never updated or deleted. */
-export const appendEntry = async (db, input) => {
-    const entry = projectEntry(input);
-    const { rows } = await db.query(`insert into ${JOURNAL}
-       (id, case_id, execution_id, entry, attempt, step, scope_key, actor, input, as_of, guard, state, delta, dormancy, error)
-     values ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9::jsonb, $10::timestamptz, $11::jsonb, $12::jsonb, $13::jsonb, $14, $15::jsonb)
-     returning ${JOURNAL_COLUMNS}`, [
-        mintId('journal'),
-        entry.caseId,
-        entry.executionId,
-        entry.entry,
-        entry.attempt,
-        entry.step,
-        entry.scopeKey,
-        toJsonb(entry.actor),
-        toJsonb(entry.input),
-        entry.asOf,
-        toJsonb(entry.guard),
-        toJsonb(entry.state),
-        toJsonb(entry.delta),
-        entry.dormancy,
-        toJsonb(entry.error),
-    ]);
-    const row = rows[0];
-    if (!row)
-        throw new Error(`insert into ${JOURNAL} returned no row`);
-    return toEntry(row);
-};
-/**
- * Read a case's journal in insertion order, oldest first. With no filter this
- * is the whole story of the case; with `scopeKey` it is one track's audit.
- */
-export const readJournal = async (db, caseId, filter = {}) => {
-    const { conditions, values, bind, where } = sqlWhere(['case_id = $1'], [caseId]);
-    if (filter.scopeKey !== undefined)
-        conditions.push(`scope_key = ${bind(filter.scopeKey)}`);
-    if (filter.step !== undefined)
-        conditions.push(`step = ${bind(filter.step)}`);
-    if (filter.executionId !== undefined)
-        conditions.push(`execution_id = ${bind(filter.executionId)}`);
-    if (filter.entry !== undefined) {
-        const entries = Array.isArray(filter.entry) ? filter.entry : [filter.entry];
-        conditions.push(`entry = any(${bind(entries)}::text[])`);
-    }
-    if (filter.since !== undefined)
-        conditions.push(`ordinal > ${bind(filter.since)}`);
-    const limit = filter.limit === undefined ? '' : ` limit ${bind(filter.limit)}`;
-    const { rows } = await db.query(`select ${JOURNAL_COLUMNS} from ${JOURNAL}
-     where ${where()}
-     order by ordinal asc${limit}`, values);
-    return rows.map(toEntry);
-};
 const TERMINAL = {
     completed: 'completed',
     failed: 'failed',