@humwick/server 0.130.0 → 0.130.2

package/node_modules/@humwick/kernel/workflow-runtime.ts

@@ -1,938 +0,0 @@
-import {
-  OpError,
-  type Clock,
-  type JsonValue,
-  type ModuleCtx,
-  type RetryPolicy,
-  type Rng,
-  type StepResult,
-  type WaitCondition,
-  type WorkflowClient,
-  type WorkflowDecl,
-  type WorkflowRun,
-  type WorkflowStartOptions,
-  type WorkflowStatusName,
-} from "./contract";
-import type { AsyncEntitySession } from "./async-entity-persistence";
-import type { AsyncEventSession } from "./async-event-log";
-import { MessageAuthorityCommitRefusedError, type MessageAuthoritySession } from "./message-authority";
-import {
-  foldWorkflowJournal,
-  workflowInstanceFromRow,
-  workflowJournalRecordFromRow,
-  type WorkflowResumePoint,
-  type WorkflowWaitCondition,
-} from "./workflow-journal-codec";
-import {
-  WorkflowContendedError,
-  WorkflowLeaseLostError,
-  WorkflowStepConflictError,
-  type WorkflowInstanceRow,
-} from "./workflow-journal";
-import { type WorkflowStepCommitFaults } from "./workflow-step-commit";
-import type { KernelPersistence } from "./kernel-persistence";
-import { recoverIndeterminate } from "./kernel-persistence";
-import { armCompatibilityStepFaults } from "./sqlite-kernel-persistence";
-import { createWorkflowLeaseOwner } from "./workflow-lease-owner";
-
-/**
- * The predicate the M3 wakeup pass consults to decide whether a `waiting` instance's
- * {@link WaitCondition} is satisfied. A sleeper's dueness is a pure clock comparison the runtime
- * owns; a waiter's dueness depends on events/commands the kernel journal does NOT own, so the host
- * injects this seam (backed by the event log / command status). It must be a pure, side-effect-free
- * read: the runtime calls it while scanning and again under the acquired lease before firing, so it
- * may be evaluated more than once. Defaults to "never satisfied" when the host wires no evaluator.
- */
-export type WaitEvaluator = (waitFor: WaitCondition, instanceId: string) => boolean | Promise<boolean>;
-
-/**
- * Compute the durable backoff delay (ms) to wait before the NEXT attempt of a step whose attempt
- * `failedAttempt` (1-based) just failed. `fixed` is constant; `exponential` grows
- * `initialMs · multiplier^(failedAttempt-1)` capped at `maxMs` (default multiplier 2). Optional
- * jitter rides the injected {@link Rng} so it stays deterministic under a seeded/controllable rng.
- * A retry that must wait becomes a `sleeping` row the wakeup pass fires — never a busy-loop.
- */
-export function retryBackoffMs(policy: RetryPolicy, failedAttempt: number, rng: Rng): number {
-  const backoff = policy.backoff;
-  let base: number;
-  if (backoff.kind === "fixed") {
-    base = backoff.delayMs;
-  } else {
-    const multiplier = backoff.multiplier ?? 2;
-    const grown = backoff.initialMs * multiplier ** Math.max(0, failedAttempt - 1);
-    base = Math.min(grown, backoff.maxMs);
-  }
-  if (policy.jitter !== undefined && policy.jitter > 0) base = rng.jitter(base, policy.jitter);
-  return Math.max(0, Math.round(base));
-}
-
-/**
- * The default executor lease TTL. A driver acquires a lease before running any step body and
- * renews it every iteration while it makes progress, so this window only needs to comfortably
- * outlast a single step's run+commit. It is injectable ({@link WorkflowRuntimeDeps.leaseTtlMs}) so
- * tests can shrink it to drive expiry/reclaim deterministically under a controllable clock.
- */
-const DEFAULT_EXECUTOR_LEASE_TTL_MS = 3_600_000;
-
-/** Discard a step's buffered sessions after a failed/aborted commit, tolerating a session the
- *  rolled-back flush already finalized (double-discard would otherwise throw). Nothing reached
- *  storage — the transaction rolled back — so this only drops in-memory buffers. */
-function discardSessions(entitySession: AsyncEntitySession<unknown>, eventSession: AsyncEventSession<unknown>, messageAuthoritySession?: MessageAuthoritySession): void {
-  for (const session of [entitySession, eventSession, messageAuthoritySession]) {
-    if (!session) continue;
-    try {
-      session.discard();
-    } catch {
-      // The session was already finalized by the (rolled-back) flush; its buffer is moot.
-    }
-  }
-}
-
-/** The fresh per-step context and the sessions that carry that step's K4/K5 effects to commit. */
-export interface WorkflowStepContext {
-  readonly ctx: ModuleCtx;
-  readonly entitySession: AsyncEntitySession<unknown>; readonly eventSession: AsyncEventSession<unknown>;
-  readonly messageAuthoritySession: MessageAuthoritySession;
-}
-
-export interface WorkflowRuntimeDeps {
-  readonly persistence: KernelPersistence;
-  /** Module catalog install barrier; every operation awaits it before touching storage. */
-  readonly ready: Promise<void>;
-  readonly clock: Clock;
-  readonly rng: Rng;
-  readonly moduleName: string;
-  /** The creator's actor (from `ctx.principal.actor`), stamped into `workflow_instances.created_by`
-   *  when this runtime seeds a new instance at {@link WorkflowRuntime.start}. The generic owner column
-   *  (KAPI-1 / decision 3) that unlocks a per-creator filter. Absent for system-driven runtimes → the
-   *  instance lands `created_by = NULL` (accepted creator-invisible divergence). */
-  readonly createdBy?: string | null;
-  /** The declaring module's workflows, keyed by name (from the manifest). */
-  readonly workflows: Readonly<Record<string, WorkflowDecl>>;
-  /** Build a fresh `ModuleCtx` + its entity/event sessions for one step attempt, bound to the
-   * declaring module's principal/config (the same assembly the op path uses). */
-  readonly beginStepContext: () => WorkflowStepContext;
-  /** Executor lease TTL in ms; defaults to {@link DEFAULT_EXECUTOR_LEASE_TTL_MS}. */
-  readonly leaseTtlMs?: number;
-  /** Decides whether a `waiting` instance's {@link WaitCondition} is satisfied; see
-   *  {@link WaitEvaluator}. Defaults to "never satisfied" (waits only fire once the host wires one). */
-  readonly isWaitSatisfied?: WaitEvaluator;
-  /** Crash/fault-injection seam at the step-commit boundary (the M0 fault hooks, wired through to
-   *  the executor). Returns the faults to arm for a given attempt, or `undefined` for none. M4's
-   *  kill-9 chaos harness drives this; M3 uses it only to prove per-instance loop isolation. */
-  readonly commitFaults?: (instanceId: string, stepName: string) => WorkflowStepCommitFaults | undefined;
-}
-
-/** How {@link WorkflowRuntime.#drive} treats a PARKED (`sleeping`/`waiting`) resume point: a normal
- *  forward driver leaves parked work alone, whereas the M3 wakeup pass fires it once it is due. */
-type DriveMode = "forward" | "wake";
-
-type AnyWorkflowDecl = WorkflowDecl<unknown, JsonValue>;
-
-interface StepTransition {
-  readonly state: JsonValue;
-  readonly next: string;
-  readonly nextStatus: WorkflowStatusName;
-  readonly sleepUntil?: number;
-  readonly waitFor?: WaitCondition;
-  readonly output?: unknown;
-  readonly hasOutput: boolean;
-}
-
-function errMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-/** The stored wait condition (validated at write time by `#validateWaitCondition`) as its contract
- *  type, for handing to the injected {@link WaitEvaluator}. */
-function waitConditionOf(value: WorkflowWaitCondition): WaitCondition {
-  return value as unknown as WaitCondition;
-}
-
-/**
- * A `start` whose seed/drive are SPLIT so a host can enlist the seed in an op's atomic commit
- * (`WorkflowStartOptions.enlist: "op-commit"`, T-0 hardening #1409 finding 1). Input/state are
- * already validated (a schema failure threw a typed `invalid_input` {@link OpError} at prepare
- * time), so `seed` is a pure idempotent insert the enclosing transaction owns.
- */
-export interface PreparedWorkflowStart {
-  /** The projection handed back to the enlisted caller at prepare time: the LIVE run when the
-   *  idempotency key already names an instance, else a `pending` stub carrying the id the seed
-   *  envelope proposes (a concurrent same-key seed dedupes inside the writer job). */
-  readonly provisional: WorkflowRun;
-  /** Clone-safe seed data. The persistence writer executes it inside the enlisting op commit and
-   *  returns the authoritative id (including an idempotency-key dedupe result). */
-  readonly seed: import("./workflow-journal").WorkflowInstanceSeed;
-  /** Drive the seeded instance forward under the single-writer lease (a contended or terminal
-   *  instance drives zero step bodies). Call only AFTER the enlisting transaction committed. */
-  readonly drive: (instanceId: string) => Promise<void>;
-}
-
-/**
- * Whether a step-body throw is a transient (retryable) failure rather than a permanent one. The
- * ratified contract has no error taxonomy to change, so the kernel applies a conservative rule: a
- * `TypeError` signals a deterministic programming/contract bug (retrying re-throws it), and a step
- * may explicitly opt a specific error out of retry by tagging it `retryable: false`. Everything else
- * is treated as transient and retried within the step's `RetryPolicy` bound. (Retries are still
- * gated by `maxAttempts`, so even a mis-classified permanent error terminates after exhaustion.)
- */
-function isRetryableError(error: unknown): boolean {
-  if (error instanceof TypeError) return false;
-  if (error !== null && typeof error === "object" && (error as { retryable?: unknown }).retryable === false) return false;
-  return true;
-}
-
-function failureText(failure: unknown): string {
-  if (typeof failure === "string") return failure;
-  if (failure !== null && typeof failure === "object" && !Array.isArray(failure)) {
-    const error = (failure as { error?: unknown }).error;
-    if (typeof error === "string") return error;
-  }
-  return JSON.stringify(failure) ?? "unknown error";
-}
-
-/**
- * The workflow executor + `WorkflowClient` (start/status/cancel) plus the M2 recovery path. Given
- * a started instance, it acquires a fresh single-writer lease, then drives the `WorkflowDecl` step
- * graph: fold the journal for the resume state, run the next un-memoized step to a `StepResult`,
- * validate it, then commit the step's K4/K5 effects AND its journal memo row atomically through
- * M0's {@link commitStepAttempt}. It transitions per the result (`next`/`sleepUntil`/`waitFor`/
- * done) and continues until the instance completes or suspends. A step whose memo row already
- * exists is never re-run — the fold advances past it, so a same-key re-`start` and a re-drive both
- * execute zero steps.
- *
- * M2 single-writer semantics: a driver must {@link WorkflowJournalPersistence.acquireLease | win a
- * lease} before running any step body. Two concurrent same-key drivers therefore serialize — one
- * acquires and runs, the second fails to acquire and runs ZERO step bodies. The holder
- * {@link WorkflowJournalPersistence.renewLease | renews} each iteration so a slow drive cannot lose
- * the lease mid-progress. {@link WorkflowRuntime.recover} clears confirmed-dead owner incarnations
- * immediately, or reclaims expired leases, then resumes from the memoized state. If a commit
- * loses the fence (a zombie driver whose lease was reclaimed), the buffered sessions are discarded
- * and the driver relinquishes cleanly, leaving the instance reclaimable rather than marking it
- * failed for merely losing a race.
- */
-export class WorkflowRuntime implements WorkflowClient<unknown> {
-  readonly #deps: WorkflowRuntimeDeps;
-  readonly #leaseTtlMs: number;
-  readonly #owner: string;
-  readonly #isWaitSatisfied: WaitEvaluator;
-  /** Leases this driver is actively holding mid-drive (instanceId → token), so {@link heartbeat}
-   *  can renew a long-running body's lease from the injected clock without a live JS timer. */
-  readonly #active = new Map<string, string>();
-
-  constructor(deps: WorkflowRuntimeDeps) {
-    this.#deps = deps;
-    this.#leaseTtlMs = deps.leaseTtlMs ?? DEFAULT_EXECUTOR_LEASE_TTL_MS;
-    this.#isWaitSatisfied = deps.isWaitSatisfied ?? (() => false);
-    // The owner records process incarnation for recovery; the per-drive token fences commits.
-    this.#owner = createWorkflowLeaseOwner(`${deps.moduleName}:${deps.rng.uuid()}`);
-  }
-
-  async start<N extends string>(name: N, input: unknown, options: WorkflowStartOptions): Promise<WorkflowRun> {
-    // Enlistment needs an op commit to join; only the module host's op invocation path provides one
-    // (it routes enlisted starts through prepareStart itself, never here). Fail closed everywhere
-    // else — a step body or standalone client asking for atomicity that does not exist must not get
-    // a silent immediate commit instead.
-    if (options?.enlist === "op-commit") {
-      throw new Error("workflow start enlist:'op-commit' is only available inside an op invocation");
-    }
-    const prepared = await this.prepareStart(name, input, options);
-
-    // Own commit (the ratified default), deduped on UNIQUE(module, workflow, idempotency_key): the
-    // same key returns the same run and never seeds a second instance. The instance is seeded
-    // UNLEASED — the driver below acquires its own fresh lease, so two concurrent same-key starts
-    // contend on the acquire (one wins, one runs zero step bodies).
-    await this.#deps.ready;
-    const requestKey = this.#deps.rng.uuid(), capturedAt = this.#deps.clock.now();
-    const seed = structuredClone(prepared.seed);
-    const { instance } = await recoverIndeterminate(() => this.#deps.persistence.seedWorkflow(requestKey, seed, capturedAt));
-    const instanceId = instance.id;
-
-    // In-process there is no separate executor yet, so `start` IS the driver: acquire the lease and
-    // drive until the instance completes or parks on its first suspension, then return. A dedupe hit
-    // that is already terminal (or held live by a concurrent driver) drives zero steps. Durable
-    // firing of a parked suspension is M3.
-    await prepared.drive(instanceId);
-    return (await this.status(instanceId))!;
-  }
-
-  /**
-   * Validate + stage a `start` WITHOUT committing anything: the returned {@link PreparedWorkflowStart}
-   * splits the idempotent instance SEED envelope (which the writer executes inside the caller's
-   * T-0 enlisted-op-commit job) from the post-commit DRIVE. All validation happens HERE, eagerly:
-   * a workflow-input/state schema failure throws a typed `invalid_input` {@link OpError} (#1409
-   * finding 2 — a deterministic validation failure must be classifiable by callers, never a raw
-   * ZodError that reads as transient), so an enlisting op aborts before buffering a seed at all.
-   */
-  async prepareStart(name: string, input: unknown, options: WorkflowStartOptions): Promise<PreparedWorkflowStart> {
-    const decl = this.#deps.workflows[name] as AnyWorkflowDecl | undefined;
-    if (!decl) throw new Error(`module '${this.#deps.moduleName}' declares no workflow '${name}'`);
-    const idempotencyKey = options?.idempotencyKey;
-    if (typeof idempotencyKey !== "string" || idempotencyKey.length === 0) {
-      throw new TypeError("workflow start requires a non-empty idempotencyKey");
-    }
-
-    const qualified = `${this.#deps.moduleName}.${name}`;
-    const parsedInput = this.#parseAsInvalidInput(() => decl.input.parse(input), `workflow '${qualified}' input`) as unknown;
-    const initialState = this.#parseAsInvalidInput(
-      () => decl.state.parse(decl.init(parsedInput)),
-      `workflow '${qualified}' initial state`,
-    ) as JsonValue;
-
-    const seedId = this.#deps.rng.uuid();
-    await this.#deps.ready;
-    const existing = await this.#deps.persistence.getWorkflowInstanceByIdentity(this.#deps.moduleName, name, idempotencyKey);
-    const now = this.#deps.clock.now();
-    const provisional: WorkflowRun = existing
-      ? await this.#projectRun(existing)
-      : { id: seedId, status: "pending", attempts: 0, createdAt: now, updatedAt: now };
-    return {
-      provisional,
-      seed: {
-        id: seedId, moduleName: this.#deps.moduleName, workflowName: name, idempotencyKey,
-        input: parsedInput as JsonValue, initialState,
-        startStep: decl.start, status: "pending", createdBy: this.#deps.createdBy ?? null,
-      },
-      drive: async (instanceId: string) => {
-        await this.#driveWithLease(instanceId, decl);
-      },
-    };
-  }
-
-  /** Run a schema parse, converting a deterministic validation failure (ZodError) into the typed
-   *  `invalid_input` {@link OpError} the op/apply layers classify on. Non-validation throws (a
-   *  buggy `init`, an exotic schema) propagate unchanged — they are not input classifications. */
-  #parseAsInvalidInput<T>(parse: () => T, what: string): T {
-    try {
-      return parse();
-    } catch (error) {
-      if (error instanceof Error && error.name === "ZodError") {
-        throw new OpError("invalid_input", 400, `${what} failed validation: ${errMessage(error)}`);
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * The M2 recovery entry point for ONE instance: reclaim its lease (if unleased/expired) and
-   * resume driving from the folded journal to completion or its next suspension. Committed steps
-   * are never re-run. A supervisor calls this (or {@link WorkflowRuntime.recover}) to pick up an
-   * instance orphaned by a crashed driver. Returns the projected run, or `undefined` if the
-   * instance is absent. If the lease is currently held live by another driver, the acquire fails
-   * and this resumes zero steps — the live driver keeps ownership.
-   */
-  async resume(id: string): Promise<WorkflowRun | undefined> {
-    await this.#deps.ready;
-    const row = await this.#deps.persistence.getWorkflowInstance(id);
-    if (!row) return undefined;
-    const decl = this.#deps.workflows[row.workflow_name] as AnyWorkflowDecl | undefined;
-    // A missing decl means this runtime does not own that workflow; leave it for a runtime that does.
-    if (decl) await this.#driveWithLease(id, decl);
-    return this.status(id);
-  }
-
-  /**
-   * The M2 recovery driver: clear leases of confirmed-dead local owners, then scan for open,
-   * drivable instances whose lease is absent or expired. This is the boot + interval job of S4 §6.4
-   * — a supervisor invokes it on startup and on a tick to reclaim orphaned work. Returns the ids it
-   * drove. Parked `sleeping`/`waiting` instances are intentionally excluded (their wakeup is M3).
-   */
-  async recover(): Promise<string[]> {
-    await this.#deps.ready;
-    const now = this.#deps.clock.now();
-    await recoverIndeterminate(() => this.#deps.persistence.reclaimDeadWorkflowLeases(this.#deps.moduleName, now));
-    return this.#drivePass(await this.#deps.persistence.listResumableWorkflows(this.#deps.moduleName, this.#deps.clock.now()), "forward");
-  }
-
-  /**
-   * A SINGLE-snapshot classification of this module's residual OPEN work for a boot/OFF reconcile that has
-   * no ticker (#1447 finding C, round-7). Samples the injected clock EXACTLY ONCE and issues ONE journal
-   * query ({@link WorkflowJournalPersistence.snapshotReconcileResidual}), so the reclaimable-now count and
-   * the live-lease recovery delay are computed against ONE `now` and CANNOT disagree across the
-   * lease-expiry boundary — the round-6 false-convergence (a reclaimable read at E-1 = 0 AND an
-   * independent live-lease read at E = undefined, from two separate clock samples, wrongly declaring
-   * "converged" and stranding an acknowledged close) is impossible by construction. READ-ONLY (no lease
-   * mutation).
-   *   • `reclaimableCount` — OPEN instances {@link recover} could drive RIGHT NOW (unleased or expired). If
-   *     a sweep drove nothing yet this is > 0, the acquire was transiently CONTENDED (not "no work") — the
-   *     reconcile must retry (a short backoff), not declare a false convergence and strand the close.
-   *   • `liveLeaseRecoveryDelayMs` — ms (≥ 0) until this module's earliest STILL-LIVE crash lease lapses
-   *     and becomes plain-{@link recover}-reclaimable, or `undefined` when no open instance holds a live
-   *     lease. A step killed BEFORE its journal commit leaves a `pending` instance still holding the dead
-   *     driver's lease. Recovery clears confirmed-dead local incarnations before this read; legacy,
-   *     remote or unverifiable owners still require a bounded retry at expiry. It never force-clears
-   *     a lease that might belong to a LIVE concurrent process
-   *     (round-4: clearing a live lease would double-drive its step body, breaking the single-writer
-   *     invariant).
-   */
-  async classifyReconcileResidual(): Promise<{ reclaimableCount: number; liveLeaseRecoveryDelayMs: number | undefined }> {
-    const now = this.#deps.clock.now();
-    await this.#deps.ready;
-    const { reclaimableCount, nextLiveLeaseExpiry } = await this.#deps.persistence.snapshotWorkflowResidual(this.#deps.moduleName, now);
-    return { reclaimableCount, liveLeaseRecoveryDelayMs: nextLiveLeaseExpiry === undefined ? undefined : Math.max(0, nextLiveLeaseExpiry - now) };
-  }
-
-  /**
-   * The M3 timer/wait wakeup pass — the firing counterpart to {@link recover}. Driven by the
-   * injected clock (there is NO live `setTimeout`), it finds DUE parked instances and drives them
-   * forward: `sleeping` rows whose `sleep_until <= now` (durable timers AND retry backoffs both park
-   * this way), plus `waiting` rows whose {@link WaitCondition} the injected evaluator reports
-   * satisfied. Each is acquired FIRST (same single-writer lease discipline as recovery, so a wakeup
-   * and a recover can never double-drive one instance) and then fired. This realizes the timers
-   * pilot's deferred `fired` as a sleeping-row a pass claims. Returns the ids it genuinely acquired
-   * and drove — a candidate a rival grabbed first, or that is no longer due under the lease, is not
-   * reported. A supervisor calls this on a clock tick; before that, it drives ZERO.
-   */
-  async wakeup(now = this.#deps.clock.now()): Promise<string[]> {
-    await this.#deps.ready;
-    const sleepers = await this.#deps.persistence.listDueWorkflows(this.#deps.moduleName, now);
-    const waiters: string[] = [];
-    for (const id of await this.#deps.persistence.listWaitingWorkflows(this.#deps.moduleName, now)) {
-      if (await this.#waiterSatisfied(id, now)) waiters.push(id);
-    }
-    // Dedup in case a status raced between the two queries; preserve sleeper-first ordering.
-    const due = [...new Set([...sleepers, ...waiters])];
-    return this.#drivePass(due, "wake");
-  }
-
-  /**
-   * Drive a work-list of instance ids under `mode`, ISOLATING each instance (M2 review residual 2):
-   * one instance's non-lease failure (e.g. an entity OCC conflict re-thrown from its commit) is
-   * caught and the pass continues to the next — it never aborts the whole tick and strands later
-   * due work. Only instances this call GENUINELY acquired and drove are reported (residual 4): a
-   * failed acquire (contended/terminal) or a mid-drive throw is excluded, so the returned list is an
-   * honest record of what this pass advanced, which the recovery/wakeup metrics count.
-   */
-  async #drivePass(ids: readonly string[], mode: DriveMode): Promise<string[]> {
-    const driven: string[] = [];
-    for (const id of ids) {
-      const row = await this.#deps.persistence.getWorkflowInstance(id);
-      if (!row) continue;
-      const decl = this.#deps.workflows[row.workflow_name] as AnyWorkflowDecl | undefined;
-      if (!decl) continue;
-      try {
-        if (await this.#driveWithLease(id, decl, mode)) driven.push(id);
-      } catch {
-        // Residual 2: a per-instance failure must not abort the pass. The lease was already
-        // released in #driveWithLease's finally, so a later tick can retry this instance.
-      }
-    }
-    return driven;
-  }
-
-  /**
-   * Renew every lease this driver is actively holding mid-drive, from the injected clock. This is
-   * the residual-1 heartbeat: a step body slower than one lease TTL would otherwise let its OWN
-   * lease lapse (and self-fence at commit) — a supervisor calls this on a clock tick to keep a
-   * long-running body's lease alive WITHOUT any live `setInterval`. Returns the ids renewed; a lease
-   * already reclaimed by a rival (token rotated) simply fails to renew and is omitted.
-   */
-  async heartbeat(now = this.#deps.clock.now()): Promise<string[]> {
-    const renewed: string[] = [];
-    for (const [instanceId, token] of this.#active) {
-      const requestKey = this.#deps.rng.uuid();
-      if (await recoverIndeterminate(() => this.#deps.persistence.renewWorkflowLease(requestKey, { instanceId, token, now, ttlMs: this.#leaseTtlMs }))) renewed.push(instanceId);
-    }
-    return renewed;
-  }
-
-  /** Pre-screen a `waiting` candidate from its row's `wait_for`, written in the same commit as the
-   *  journal memo. The full journal fold runs only under the acquired lease in #drive (#3006). */
-  async #waiterSatisfied(instanceId: string, _now: number): Promise<boolean> {
-    const row = await this.#deps.persistence.getWorkflowInstance(instanceId);
-    if (!row || row.status !== "waiting") return false;
-    const { waitFor } = workflowInstanceFromRow(row);
-    if (waitFor === undefined) return false;
-    return this.#isWaitSatisfied(waitConditionOf(waitFor), instanceId);
-  }
-
-  async status(id: string): Promise<WorkflowRun | undefined> {
-    const row = await this.#deps.persistence.getWorkflowInstance(id);
-    if (!row) return undefined;
-    return this.#projectRun(row);
-  }
-
-  /** Project one instance row to its contract {@link WorkflowRun} (shared by `status` and the
-   *  prepare-time provisional for an already-existing identity). */
-  async #projectRun(row: WorkflowInstanceRow): Promise<WorkflowRun> {
-    const instance = workflowInstanceFromRow(row);
-    // The cursor counts every memoized row (the fold enforces it); a prune deletes through it (#3006).
-    const attempts = instance.journalCursor - instance.journalPrunedThrough;
-    return {
-      id: instance.id,
-      status: instance.status,
-      attempts,
-      createdAt: instance.createdAt,
-      updatedAt: instance.updatedAt,
-      ...(instance.status === "done" && instance.output !== undefined ? { output: instance.output } : {}),
-      ...(instance.failure !== undefined ? { error: failureText(instance.failure) } : {}),
-    };
-  }
-
-  async cancel(id: string): Promise<boolean> {
-    return this.control("cancel", id);
-  }
-
-  async control(operation: "cancel" | "fail" | "reopen", id: string, failure?: unknown): Promise<boolean> {
-    const requestKey = this.#deps.rng.uuid();
-    const now = this.#deps.clock.now();
-    return recoverIndeterminate(() => this.#deps.persistence.controlWorkflow(requestKey, operation, id, now, failure));
-  }
-
-  /**
-   * Acquire the single-writer lease, then drive, then release. Acquire is the mutual-exclusion
-   * point: it succeeds only when the instance is unleased or its lease has expired, so a second
-   * concurrent driver of the same instance FAILS HERE and runs zero step bodies. This is also the
-   * crash-recovery reclaim — an expired lease left by a dead driver is taken over with a fresh
-   * token. When {@link WorkflowRuntime.#drive} returns `true` we still hold the lease and release
-   * it (so a parked instance can be reacquired by M3 without waiting out the TTL); when it returns
-   * `false` we already lost the fence and there is nothing of ours to release.
-   */
-  async #driveWithLease(instanceId: string, decl: AnyWorkflowDecl, mode: DriveMode = "forward"): Promise<boolean> {
-    const token = this.#deps.rng.uuid();
-    let acquired: boolean;
-    try {
-      const requestKey = this.#deps.rng.uuid();
-      const now = this.#deps.clock.now();
-      acquired = await recoverIndeterminate(() => this.#deps.persistence.acquireWorkflowLease(requestKey, {
-        instanceId,
-        owner: this.#owner,
-        token,
-        now,
-        ttlMs: this.#leaseTtlMs,
-      }));
-    } catch (error) {
-      // A SQLITE_BUSY on the acquire itself is a clean back-off: we did NOT take the lease (the
-      // UPDATE never landed), so treat it exactly like a contended/terminal acquire — drive nothing,
-      // let a later tick retry. Never leaks as an untyped error that would abort the pass.
-      if (error instanceof WorkflowContendedError) return false;
-      throw error;
-    }
-    // Contended (a live lease held by another driver) or terminal (no open row to claim): another
-    // writer owns this instance, or there is nothing to drive. Either way, run no step body and
-    // report that we did NOT drive it (so a pass never over-reports what it advanced).
-    if (!acquired) return false;
-
-    // Register the live lease so heartbeat() can renew it mid-body from the injected clock.
-    this.#active.set(instanceId, token);
-    let holdsLease = true;
-    try {
-      holdsLease = await this.#drive(instanceId, decl, token, mode);
-    } catch (error) {
-      // A SQLITE_BUSY on a renew or the commit tx propagates here as WorkflowContendedError. Nothing
-      // of ours committed (the tx rolled back), and we still hold our lease — so this is a typed
-      // relinquish, NOT a failure: fall through to the finally, which RELEASES our lease so a later
-      // tick/recovery reclaims and re-runs the same un-memoized step. The instance is never marked
-      // failed for merely losing a storage race.
-      if (!(error instanceof WorkflowContendedError)) throw error;
-      holdsLease = true;
-      return false;
-    } finally {
-      this.#active.delete(instanceId);
-      if (holdsLease) {
-        const requestKey = this.#deps.rng.uuid();
-        const now = this.#deps.clock.now();
-        await recoverIndeterminate(() => this.#deps.persistence.releaseWorkflowLease(requestKey, instanceId, token, now));
-      }
-    }
-    return true;
-  }
-
-  /**
-   * Drive the step graph forward under lease `token` until the instance is terminal or parked on a
-   * suspension. Returns whether we STILL hold the lease at exit: `true` after a normal
-   * terminal/parked stop, `false` if we relinquished because a commit lost the fence (our lease was
-   * reclaimed by another driver — a zombie-driver fence-off). The caller releases the lease only in
-   * the `true` case.
-   */
-  async #drive(instanceId: string, decl: AnyWorkflowDecl, token: string, mode: DriveMode): Promise<boolean> {
-    for (;;) {
-      const row = await this.#deps.persistence.getWorkflowInstance(instanceId);
-      if (!row) throw new Error(`workflow instance '${instanceId}' vanished mid-drive`);
-      // Pause TOCTOU (second half): the acquire gated on `paused_at IS NULL`, but a pause can still
-      // land AFTER a successful acquire and BEFORE we run the next step — or mid-drive between steps
-      // of a forward drive. Re-check here so a paused instance runs NO new step: pause takes effect
-      // as "no new step after the current one." We still hold the lease, so return `true` for the
-      // caller to release it; the instance simply sits paused until resumed.
-      if (row.paused_at !== null) return true;
-      const instance = workflowInstanceFromRow(row);
-      const records = (await this.#deps.persistence.listWorkflowSteps(instanceId)).map(workflowJournalRecordFromRow);
-      const resume = foldWorkflowJournal(instance, records);
-
-      // A `ready` resume has an un-memoized step to run. `done`/`failed`/`canceled` are terminal.
-      // `sleeping`/`waiting` are parked: a forward driver leaves them be, but a `wake` pass fires
-      // them ONCE they are DUE (timer elapsed / wait satisfied) — the same clock and predicate the
-      // pass pre-screened with, re-checked here under the acquired lease so a "due but un-drivable"
-      // gap cannot open. After the parked step runs the instance is `running`, so subsequent loop
-      // iterations proceed as a normal forward drive.
-      const runnable = resume.status === "ready"
-        || (mode === "wake" && await this.#isDue(resume, this.#deps.clock.now(), instanceId));
-      if (!runnable) return true;
-      const stepName = resume.stepName;
-      if (!stepName) return true;
-
-      const step = decl.steps[stepName];
-      if (!step) {
-        await this.#fail(instanceId, `workflow '${instance.workflowName}' has no step '${stepName}'`);
-        return true;
-      }
-
-      // Renew before running the step so a competitor cannot reclaim while a long body runs, and so
-      // progress across steps keeps extending the window. A failed renew means our lease was already
-      // reclaimed (we were too slow) — relinquish without running the body; the reclaiming driver
-      // owns the instance now.
-      if (!await this.#renew(instanceId, token)) {
-        return false;
-      }
-
-      const { ctx, entitySession, eventSession, messageAuthoritySession } = this.#deps.beginStepContext();
-      const startedAt = this.#deps.clock.now();
-      let result: StepResult<JsonValue>;
-      try {
-        result = await step.run(ctx, resume.state as JsonValue);
-      } catch (error) {
-        // The step body threw. Its buffered effects never commit; classify the failure and either
-        // retry (immediately, or parked on a backoff sleeping-row) or go terminal `failed`.
-        entitySession.discard();
-        eventSession.discard();
-        messageAuthoritySession.discard();
-        const outcome = await this.#handleStepFailure(instanceId, resume, stepName, step.retry, startedAt, token, error);
-        if (outcome === "retry-loop") continue;
-        return outcome === "relinquish" ? false : true;
-      }
-
-      let transition: StepTransition;
-      try {
-        transition = this.#validateTransition(decl, stepName, result);
-      } catch (error) {
-        // A malformed `StepResult` is a deterministic contract violation, never a transient fault —
-        // retrying cannot help, so it is always permanent regardless of the step's retry policy.
-        entitySession.discard();
-        eventSession.discard();
-        messageAuthoritySession.discard();
-        const outcome = await this.#commitFailedAttempt(instanceId, resume, stepName, startedAt, token, errMessage(error), { terminal: true });
-        return outcome === "relinquish" ? false : true;
-      }
-
-      // The memoized `result` JSON must round-trip through the journal codec, so it carries the
-      // same sleepUntil/waitFor/output the transition columns record.
-      const resultJson: Record<string, JsonValue> = { state: transition.state, next: transition.next };
-      if (transition.hasOutput) resultJson.output = (transition.output ?? null) as JsonValue;
-      if (transition.sleepUntil !== undefined) resultJson.sleepUntil = transition.sleepUntil;
-      if (transition.waitFor !== undefined) resultJson.waitFor = transition.waitFor as unknown as JsonValue;
-
-      // Residual 1 (renew cadence): renew right before the commit using the post-body clock, so a
-      // body that alone outran the TTL still fences successfully AS LONG AS no rival actually
-      // reclaimed. If the renew fails, a rival already rotated our token — relinquish; nothing of
-      // ours committed. This makes the "body slower than the TTL self-fences" failure impossible
-      // for a solo holder, while still yielding to a genuine reclaim.
-      if (!await this.#renew(instanceId, token)) {
-        discardSessions(entitySession, eventSession, messageAuthoritySession);
-        return false;
-      }
-
-      // The four-way atomic commit: fence re-check + entity flush + event flush + journal memo,
-      // all-or-nothing. No effect reaches storage on any side channel.
-      const faults = this.#deps.commitFaults?.(instanceId, stepName);
-      try {
-        entitySession.seal();
-        eventSession.seal();
-        messageAuthoritySession.seal();
-        const capturedAt = this.#deps.clock.now();
-        const requestKey = this.#deps.rng.uuid();
-        if (faults) armCompatibilityStepFaults(this.#deps.persistence, requestKey, faults);
-        const envelope = structuredClone({
-          requestKey,
-          capturedAt,
-          lease: { instanceId, token, now: capturedAt },
-          entities: entitySession.mutations(),
-          events: eventSession.appends(capturedAt),
-          messageAuthority: messageAuthoritySession.operations(),
-          record: {
-            instanceId,
-            stepIndex: resume.stepIndex,
-            stepName,
-            attempt: resume.nextAttempt,
-            outcome: "completed" as const,
-            state: transition.state,
-            result: resultJson,
-            nextStatus: transition.nextStatus,
-            startedAt,
-            sleepUntil: transition.sleepUntil ?? null,
-            waitFor: transition.waitFor ?? null,
-            output: transition.nextStatus === "done" && transition.hasOutput ? ((transition.output ?? null) as JsonValue) : null,
-          },
-        });
-        await recoverIndeterminate(() => this.#deps.persistence.stepCommit(envelope));
-      } catch (error) {
-        // We lost the race for this step: either our lease was reclaimed/expired (fence failed) or
-        // another driver already memoized this exact attempt (conflict). The transaction rolled
-        // back — no effect of ours reached storage. Discard the buffered sessions and relinquish;
-        // do NOT mark the instance failed, because a legitimate driver may be progressing it. Leave
-        // it exactly as found so that driver (or a later reclaim) continues from the memoized state.
-        if (error instanceof WorkflowLeaseLostError || error instanceof WorkflowStepConflictError) {
-          discardSessions(entitySession, eventSession, messageAuthoritySession);
-          return false;
-        }
-        if (error instanceof MessageAuthorityCommitRefusedError && error.refusal.code === "superseded") {
-          // The participant proved that a higher fence/generation owns this timer. Its first
-          // transaction rolled back every proposed domain effect; now memoize a domain-free done
-          // transition so the obsolete due sleeper is reaped instead of re-driven every tick.
-          discardSessions(entitySession, eventSession, messageAuthoritySession);
-          const disposition = await this.#commitSupersededAttempt(instanceId, resume, stepName, startedAt, token, error);
-          return disposition === "relinquish" ? false : true;
-        }
-        // Any other commit failure (e.g. an entity OCC conflict) is not a lost-lease condition;
-        // drop the buffers and propagate — nothing was committed. The wakeup/recover pass isolates
-        // this per-instance (residual 2) so it does not abort the whole tick.
-        discardSessions(entitySession, eventSession, messageAuthoritySession);
-        throw error;
-      }
-
-      // Terminal (done) or parked (sleeping/waiting): stop. Only `running` continues the loop, and
-      // the next fold advances past the step we just memoized.
-      if (transition.nextStatus !== "running") return true;
-    }
-  }
-
-  /** Whether a PARKED resume point is due to fire now: a `sleeping` timer/backoff whose deadline has
-   *  passed, or a `waiting` condition the injected evaluator reports satisfied. */
-  async #isDue(resume: WorkflowResumePoint, now: number, instanceId: string): Promise<boolean> {
-    if (resume.status === "sleeping") return resume.sleepUntil !== undefined && resume.sleepUntil <= now;
-    if (resume.status === "waiting") {
-      return resume.waitFor !== undefined && await this.#isWaitSatisfied(waitConditionOf(resume.waitFor), instanceId);
-    }
-    return false;
-  }
-
-  /**
-   * Classify a step-body throw and act. With a retry policy and attempts remaining (and a retryable
-   * error), journal a `failed` attempt — bumping `attempt` under the UNIQUE(instance, step, attempt)
-   * index so each retry is exactly-once — and either retry immediately (`retry-loop`, backoff 0) or
-   * park a `sleeping` backoff row the wakeup pass fires. Otherwise (no policy, attempts exhausted, or
-   * a non-retryable error) journal the final `failed` attempt and go terminal `failed`. Returns how
-   * `#drive` should proceed. A lost lease during the commit yields `relinquish`.
-   */
-  async #handleStepFailure(
-    instanceId: string,
-    resume: WorkflowResumePoint,
-    stepName: string,
-    retry: RetryPolicy | undefined,
-    startedAt: number,
-    token: string,
-    error: unknown,
-  ): Promise<"retry-loop" | "stop" | "relinquish"> {
-    const failedAttempt = resume.nextAttempt;
-    const message = errMessage(error);
-    const retryable = retry !== undefined && failedAttempt < retry.maxAttempts && isRetryableError(error);
-    if (!retryable) {
-      return this.#commitFailedAttempt(instanceId, resume, stepName, startedAt, token, message, { terminal: true });
-    }
-    const delayMs = retryBackoffMs(retry, failedAttempt, this.#deps.rng);
-    return this.#commitFailedAttempt(instanceId, resume, stepName, startedAt, token, message, { terminal: false, delayMs });
-  }
-
-  /**
-   * Journal one `failed` attempt atomically under the fence and advance the instance: to terminal
-   * `failed` (`terminal`), to a `sleeping` backoff row due at `now + delayMs` (a retry that must
-   * wait), or straight back to `running` for an immediate retry (`delayMs === 0`). Renews the lease
-   * with the post-body clock first (residual 1) so a slow failing body still fences. Returns
-   * `retry-loop` to re-run in the same drive, `stop` when parked/terminal, or `relinquish` on a lost
-   * lease / attempt conflict (another writer owns the instance).
-   */
-  async #commitFailedAttempt(
-    instanceId: string,
-    resume: WorkflowResumePoint,
-    stepName: string,
-    startedAt: number,
-    token: string,
-    message: string,
-    disposition: { terminal: true } | { terminal: false; delayMs: number },
-  ): Promise<"retry-loop" | "stop" | "relinquish"> {
-    if (!await this.#renew(instanceId, token)) {
-      return "relinquish";
-    }
-    const failedAt = this.#deps.clock.now();
-    const immediate = !disposition.terminal && disposition.delayMs <= 0;
-    const nextStatus: WorkflowStatusName = disposition.terminal ? "failed" : immediate ? "running" : "sleeping";
-    // M4 chaos seam: a kill point armed here fires while scheduling the backoff/failed row.
-    const faults = this.#deps.commitFaults?.(instanceId, stepName);
-    try {
-      const requestKey = this.#deps.rng.uuid();
-      if (faults) armCompatibilityStepFaults(this.#deps.persistence, requestKey, faults);
-      const envelope = structuredClone({
-        requestKey,
-        capturedAt: failedAt,
-        lease: { instanceId, token, now: failedAt },
-        record: {
-          instanceId,
-          stepIndex: resume.stepIndex,
-          stepName,
-          attempt: resume.nextAttempt,
-          outcome: "failed" as const,
-          state: resume.state as JsonValue,
-          result: { error: message },
-          nextStatus,
-          startedAt,
-          sleepUntil: disposition.terminal || immediate ? null : failedAt + disposition.delayMs,
-          waitFor: null,
-          output: null,
-          failure: disposition.terminal ? { error: message } : null,
-        },
-      });
-      await recoverIndeterminate(() => this.#deps.persistence.failedStepCommit(envelope));
-    } catch (error) {
-      // Same race semantics as a completed commit: a fenced-off zombie or a duplicate attempt row
-      // rolls back; relinquish and leave the instance for its rightful driver.
-      if (error instanceof WorkflowLeaseLostError || error instanceof WorkflowStepConflictError) return "relinquish";
-      throw error;
-    }
-    return immediate ? "retry-loop" : "stop";
-  }
-
-  /** Terminalize an exact authority generation that the host proved was superseded. Contention and
-   *  ordinary refusals never enter here: those retain the sleeping row and remain retryable. */
-  async #commitSupersededAttempt(
-    instanceId: string,
-    resume: WorkflowResumePoint,
-    stepName: string,
-    startedAt: number,
-    token: string,
-    refusal: MessageAuthorityCommitRefusedError,
-  ): Promise<"stop" | "relinquish"> {
-    if (!await this.#renew(instanceId, token)) {
-      return "relinquish";
-    }
-    const faults = this.#deps.commitFaults?.(instanceId, stepName);
-    try {
-      const capturedAt = this.#deps.clock.now();
-      const requestKey = this.#deps.rng.uuid();
-      if (faults) armCompatibilityStepFaults(this.#deps.persistence, requestKey, faults);
-      const envelope = structuredClone({
-        requestKey,
-        capturedAt,
-        lease: { instanceId, token, now: capturedAt },
-        record: {
-          instanceId,
-          stepIndex: resume.stepIndex,
-          stepName,
-          attempt: resume.nextAttempt,
-          outcome: "completed" as const,
-          state: resume.state as JsonValue,
-          result: {
-            state: resume.state as JsonValue,
-            next: "done",
-            superseded: true,
-            reason: refusal.refusal.reason,
-          },
-          nextStatus: "done" as const,
-          startedAt,
-          sleepUntil: null,
-          waitFor: null,
-          output: null,
-        },
-      });
-      await recoverIndeterminate(() => this.#deps.persistence.supersededStepCommit(envelope));
-    } catch (error) {
-      if (error instanceof WorkflowLeaseLostError || error instanceof WorkflowStepConflictError) return "relinquish";
-      throw error;
-    }
-    return "stop";
-  }
-
-  /** Validate a step's `StepResult` against the decl and project its durable transition. */
-  #validateTransition(decl: AnyWorkflowDecl, stepName: string, result: StepResult<JsonValue>): StepTransition {
-    if (result === null || typeof result !== "object") {
-      throw new TypeError(`step '${stepName}' must return a StepResult object`);
-    }
-    const next = (result as { next?: unknown }).next;
-    if (typeof next !== "string" || next.length === 0) {
-      throw new TypeError(`step '${stepName}' must return a non-empty 'next'`);
-    }
-    if (next !== "done" && !Object.hasOwn(decl.steps, next)) {
-      throw new TypeError(`step '${stepName}' returned unknown next step '${next}'`);
-    }
-    const state = decl.state.parse((result as { state: unknown }).state) as JsonValue;
-
-    const sleepUntilRaw = (result as { sleepUntil?: unknown }).sleepUntil;
-    const waitForRaw = (result as { waitFor?: unknown }).waitFor;
-    if (sleepUntilRaw !== undefined && waitForRaw !== undefined) {
-      throw new TypeError(`step '${stepName}' cannot return both sleepUntil and waitFor`);
-    }
-    let sleepUntil: number | undefined;
-    if (sleepUntilRaw !== undefined) {
-      if (typeof sleepUntilRaw !== "number" || !Number.isFinite(sleepUntilRaw)) {
-        throw new TypeError(`step '${stepName}' sleepUntil must be a finite number`);
-      }
-      sleepUntil = sleepUntilRaw;
-    }
-    let waitFor: WaitCondition | undefined;
-    if (waitForRaw !== undefined) {
-      waitFor = this.#validateWaitCondition(stepName, waitForRaw);
-    }
-    if (next === "done" && (sleepUntil !== undefined || waitFor !== undefined)) {
-      throw new TypeError(`step '${stepName}' cannot schedule work after next=done`);
-    }
-
-    const hasOutput = next === "done" && Object.hasOwn(result, "output");
-    const nextStatus: WorkflowStatusName = next === "done" ? "done"
-      : sleepUntil !== undefined ? "sleeping"
-      : waitFor !== undefined ? "waiting"
-      : "running";
-    return {
-      state,
-      next,
-      nextStatus,
-      ...(sleepUntil !== undefined ? { sleepUntil } : {}),
-      ...(waitFor !== undefined ? { waitFor } : {}),
-      ...(hasOutput ? { output: (result as { output?: unknown }).output } : {}),
-      hasOutput,
-    };
-  }
-
-  #validateWaitCondition(stepName: string, value: unknown): WaitCondition {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-      throw new TypeError(`step '${stepName}' waitFor must be a WaitCondition object`);
-    }
-    const kind = (value as { kind?: unknown }).kind;
-    if (kind === "event") {
-      const topic = (value as { topic?: unknown }).topic;
-      if (typeof topic !== "string" || !topic.includes(".")) {
-        throw new TypeError(`step '${stepName}' waitFor event requires a '<module>.<name>' topic`);
-      }
-      const correlationId = (value as { correlationId?: unknown }).correlationId;
-      return {
-        kind: "event",
-        topic: topic as `${string}.${string}`,
-        ...(correlationId !== undefined ? { correlationId: String(correlationId) } : {}),
-      };
-    }
-    if (kind === "command") {
-      const commandId = (value as { commandId?: unknown }).commandId;
-      if (typeof commandId !== "string" || commandId.length === 0) {
-        throw new TypeError(`step '${stepName}' waitFor command requires a commandId`);
-      }
-      return { kind: "command", commandId };
-    }
-    throw new TypeError(`step '${stepName}' waitFor kind must be 'event' or 'command'`);
-  }
-
-  /** Durably transition an open instance to `failed`. M1 has no retry driver (that is M3), so an
-   * unhandled step throw or an invalid result terminates the instance rather than looping. */
-  async #fail(instanceId: string, message: string): Promise<void> {
-    const requestKey = this.#deps.rng.uuid(), now = this.#deps.clock.now();
-    await recoverIndeterminate(() => this.#deps.persistence.controlWorkflow(requestKey, "fail", instanceId, now, { error: message }));
-  }
-
-  async #renew(instanceId: string, token: string): Promise<boolean> {
-    const requestKey = this.#deps.rng.uuid();
-    const now = this.#deps.clock.now();
-    return recoverIndeterminate(() => this.#deps.persistence.renewWorkflowLease(requestKey, { instanceId, token, now, ttlMs: this.#leaseTtlMs }));
-  }
-}
-
-export function createWorkflowRuntime(deps: WorkflowRuntimeDeps): WorkflowRuntime {
-  return new WorkflowRuntime(deps);
-}
-
-export type { WorkflowResumePoint };