@ai-digital-factory/state-flow-runtime 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,2877 @@
+// src/durable/definition.ts
+import { z } from "zod";
+import { createHash } from "node:crypto";
+
+// src/durable/errors.ts
+var DurableRuntimeError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = new.target.name;
+  }
+};
+var DurableOwnershipError = class extends DurableRuntimeError {
+};
+var DurableRuntimeClosedError = class extends DurableRuntimeError {
+};
+var DurableShutdownTimeoutError = class extends DurableRuntimeError {
+};
+var DurableDefinitionError = class extends DurableRuntimeError {
+  problems;
+  constructor(chartName, problems) {
+    super(
+      `Durable flow "${chartName}" is invalid:
+- ${problems.join("\n- ")}`
+    );
+    this.problems = problems;
+  }
+};
+var DurableInputError = class extends DurableRuntimeError {
+};
+var DurableSchemaError = class extends DurableRuntimeError {
+};
+var DurableDispatchError = class extends DurableRuntimeError {
+  constructor(outcome, instanceId2, context) {
+    super(`Dispatch for instance ${instanceId2}: ${outcome}`);
+    this.outcome = outcome;
+    this.instanceId = instanceId2;
+    this.context = context;
+  }
+  outcome;
+  instanceId;
+  context;
+  phase = "dispatch";
+};
+var DurableOperationError = class extends DurableRuntimeError {
+  constructor(phase, cause) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause });
+    this.phase = phase;
+  }
+  phase;
+  outcome = "error";
+};
+var DurableDefinitionMismatchError = class extends DurableRuntimeError {
+  constructor(context) {
+    super(context.message);
+    this.context = context;
+  }
+  context;
+  phase = "ensure-instance";
+  outcome = "definition-mismatch";
+};
+
+// src/durable/json.ts
+function isPlainObject(value) {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function findNonJsonValue(value, path = "$") {
+  return findNonJson(value, path, /* @__PURE__ */ new Set());
+}
+function findNonJson(value, path, ancestors) {
+  if (value === null) {
+    return null;
+  }
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return null;
+    case "number":
+      return Number.isFinite(value) ? null : `${path} is not a finite number`;
+    case "object": {
+      if (ancestors.has(value)) {
+        return `${path} is a circular reference`;
+      }
+      ancestors.add(value);
+      try {
+        if (Array.isArray(value)) {
+          for (let index = 0; index < value.length; index += 1) {
+            if (!(index in value)) {
+              return `${path}[${index}] is an empty array slot`;
+            }
+            const found = findNonJson(
+              value[index],
+              `${path}[${index}]`,
+              ancestors
+            );
+            if (found) {
+              return found;
+            }
+          }
+          return null;
+        }
+        if (!isPlainObject(value)) {
+          return `${path} is not a plain object`;
+        }
+        for (const key of Object.keys(value)) {
+          const entry = value[key];
+          if (entry === void 0) {
+            continue;
+          }
+          const found = findNonJson(
+            entry,
+            `${path}[${JSON.stringify(key)}]`,
+            ancestors
+          );
+          if (found) {
+            return found;
+          }
+        }
+        return null;
+      } finally {
+        ancestors.delete(value);
+      }
+    }
+    default:
+      return `${path} is ${typeof value}`;
+  }
+}
+function canonicalJson(value) {
+  return writeCanonical(value, /* @__PURE__ */ new Set());
+}
+function writeCanonical(value, ancestors) {
+  if (value === null || typeof value !== "object") {
+    const text = JSON.stringify(value);
+    if (text === void 0) {
+      throw new TypeError(`Cannot serialize ${typeof value} as JSON`);
+    }
+    return text;
+  }
+  if (ancestors.has(value)) {
+    throw new TypeError("Cannot serialize a circular reference as JSON");
+  }
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return `[${value.map((entry) => writeCanonical(entry ?? null, ancestors)).join(",")}]`;
+    }
+    const parts = [];
+    for (const key of Object.keys(value).sort()) {
+      const entry = value[key];
+      if (entry !== void 0) {
+        parts.push(
+          `${JSON.stringify(key)}:${writeCanonical(entry, ancestors)}`
+        );
+      }
+    }
+    return `{${parts.join(",")}}`;
+  } finally {
+    ancestors.delete(value);
+  }
+}
+function parseJson(text) {
+  return text === null ? null : JSON.parse(text);
+}
+
+// src/durable/definition.ts
+var STRATEGIES = /* @__PURE__ */ new Set([
+  "safe-replay",
+  "reconcile",
+  "manual"
+]);
+var SLOT_EXPORTS = {
+  state: { onEnter: "on-enter", onExit: "on-exit" },
+  transition: { guard: "guard", onTransition: "on-transition" },
+  creation: { resolveStartState: "resolve-start-state" }
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function readCallback(label, kind, value, problems) {
+  if (typeof value === "function") {
+    problems.push(
+      `${label} is a plain function; durable callbacks must declare { run, recovery }`
+    );
+    return null;
+  }
+  if (!isRecord(value) || typeof value.run !== "function") {
+    problems.push(`${label} must be an object with a run function`);
+    return null;
+  }
+  const recovery = value.recovery;
+  if (!isRecord(recovery) || typeof recovery.strategy !== "string") {
+    problems.push(`${label} must declare recovery.strategy`);
+    return null;
+  }
+  if (!STRATEGIES.has(recovery.strategy)) {
+    problems.push(
+      `${label} has unknown recovery strategy ${JSON.stringify(recovery.strategy)}`
+    );
+    return null;
+  }
+  const strategy = recovery.strategy;
+  const hasReconcile = recovery.reconcile !== void 0;
+  if (strategy === "reconcile" && typeof recovery.reconcile !== "function") {
+    problems.push(
+      `${label} uses the reconcile strategy without a reconcile function`
+    );
+    return null;
+  }
+  if (strategy !== "reconcile" && hasReconcile) {
+    problems.push(
+      `${label} declares a reconcile function with the ${strategy} strategy`
+    );
+    return null;
+  }
+  return {
+    kind,
+    strategy,
+    run: value.run,
+    reconcile: strategy === "reconcile" ? recovery.reconcile : null
+  };
+}
+function readSlot(slotKind, label, value, problems) {
+  if (value === null || value === void 0) {
+    return {};
+  }
+  if (!isRecord(value)) {
+    problems.push(`${label} must be a handler module object`);
+    return {};
+  }
+  const exportsForKind = SLOT_EXPORTS[slotKind];
+  const result = {};
+  for (const key of Object.keys(value)) {
+    if (slotKind === "transition" && key === "payloadSchema") continue;
+    const callbackKind = exportsForKind[key];
+    if (!callbackKind) {
+      problems.push(`${label} exports unexpected member "${key}"`);
+      continue;
+    }
+    const callback = readCallback(
+      `${label}.${key}`,
+      callbackKind,
+      value[key],
+      problems
+    );
+    if (callback) {
+      result[key] = callback;
+    }
+  }
+  return result;
+}
+function loadFlowDefinition(module) {
+  const problems = [];
+  if (module.execution !== "durable") {
+    problems.push(
+      "compiled module is not durable; rebuild its handlers package with the current State Flow compiler"
+    );
+  }
+  const statesById = /* @__PURE__ */ new Map();
+  const statesByName = /* @__PURE__ */ new Map();
+  for (const state of module.states) {
+    const slot = readSlot(
+      "state",
+      `state "${state.name}"`,
+      module.hooks.states[state.id],
+      problems
+    );
+    const definition = {
+      id: state.id,
+      name: state.name,
+      onEnter: slot.onEnter ?? null,
+      onExit: slot.onExit ?? null
+    };
+    if (statesByName.has(state.name)) {
+      problems.push(`state name "${state.name}" is declared more than once`);
+    }
+    statesById.set(state.id, definition);
+    statesByName.set(state.name, definition);
+  }
+  const transitionsByName = /* @__PURE__ */ new Map();
+  for (const transition of module.transitions) {
+    const from = statesById.get(transition.fromId);
+    const to = statesById.get(transition.toId);
+    if (!from || !to) {
+      problems.push(
+        `transition "${transition.name}" references an unknown state`
+      );
+      continue;
+    }
+    if (transitionsByName.has(transition.name)) {
+      problems.push(
+        `transition name "${transition.name}" is declared more than once`
+      );
+    }
+    const slot = readSlot(
+      "transition",
+      `transition "${transition.name}"`,
+      module.hooks.transitions[transition.name],
+      problems
+    );
+    const payloadSchema = module.payloadSchemas?.[transition.name];
+    if (!(payloadSchema instanceof z.ZodType)) {
+      problems.push(
+        `transition "${transition.name}" must declare a Zod payloadSchema`
+      );
+    }
+    transitionsByName.set(transition.name, {
+      name: transition.name,
+      payloadSchema: payloadSchema instanceof z.ZodType ? payloadSchema : z.never(),
+      from,
+      to,
+      guard: slot.guard ?? null,
+      onTransition: slot.onTransition ?? null
+    });
+  }
+  const creation = readSlot(
+    "creation",
+    "creation handler",
+    module.hooks.creation,
+    problems
+  );
+  const initialState = statesById.get(module.initialStateId);
+  if (!initialState) {
+    problems.push(`initial state id "${module.initialStateId}" is unknown`);
+  }
+  if (problems.length > 0 || !initialState) {
+    throw new DurableDefinitionError(module.chartName, problems);
+  }
+  const strategyOf = (callback) => callback === null ? null : callback.strategy;
+  const identitySource = {
+    chartName: module.chartName,
+    initialStateId: module.initialStateId,
+    states: [...statesById.values()].map((state) => ({
+      id: state.id,
+      name: state.name,
+      onEnter: strategyOf(state.onEnter),
+      onExit: strategyOf(state.onExit)
+    })),
+    transitions: [...transitionsByName.values()].map((transition) => ({
+      name: transition.name,
+      from: transition.from.id,
+      to: transition.to.id,
+      guard: strategyOf(transition.guard),
+      onTransition: strategyOf(transition.onTransition)
+    })),
+    resolveStartState: strategyOf(creation.resolveStartState ?? null)
+  };
+  const definitionId = `def_${createHash("sha256").update(canonicalJson(identitySource)).digest("hex").slice(0, 32)}`;
+  return {
+    chartName: module.chartName,
+    definitionId,
+    initialState,
+    statesByName,
+    transitionsByName,
+    resolveStartState: creation.resolveStartState ?? null,
+    handlerRevision: typeof module.handlerRevision === "string" ? module.handlerRevision : null
+  };
+}
+
+// src/durable/engine.ts
+import { z as z2 } from "zod";
+
+// src/durable/ids.ts
+import { randomUUID } from "node:crypto";
+var MAX_ID_LENGTH = 256;
+var CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
+function validateApplicationId(kind, value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new DurableInputError(`${kind} must be a non-empty string`);
+  }
+  if (value.length > MAX_ID_LENGTH) {
+    throw new DurableInputError(
+      `${kind} must be at most ${MAX_ID_LENGTH} characters`
+    );
+  }
+  if (CONTROL_CHARACTERS.test(value)) {
+    throw new DurableInputError(`${kind} must not contain control characters`);
+  }
+  return value;
+}
+function instanceId(value) {
+  return validateApplicationId("instanceId", value);
+}
+function requestId(value) {
+  return validateApplicationId("requestId", value);
+}
+function mintOperationId() {
+  return `op_${randomUUID()}`;
+}
+function mintAttemptId() {
+  return `att_${randomUUID()}`;
+}
+function mintExecutionId() {
+  return `exe_${randomUUID()}`;
+}
+
+// src/durable/engine.ts
+var MAX_ATTEMPTS = 4;
+function clampLimit(value, fallback, max) {
+  if (value === void 0 || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.min(max, Math.max(1, Math.floor(value)));
+}
+var RECOVERY_DELAYS_MS = [1e3, 5e3, 3e4];
+var BUSY_RETRY_DELAY_MS = 100;
+var InstanceCore = class {
+  constructor(id, flow) {
+    this.id = id;
+    this.flow = flow;
+  }
+  id;
+  flow;
+  listeners = /* @__PURE__ */ new Set();
+  activeExecutionId = null;
+  timer = null;
+  infrastructureRetries = 0;
+  /**
+   * Set when an infrastructure error stopped execution in this process; shown in snapshots.
+   * `restartRecovery` or opening the instance again resumes from persisted state.
+   */
+  stall = null;
+  get stalled() {
+    return this.stall !== null;
+  }
+};
+var VOID_CALLBACKS = /* @__PURE__ */ new Set([
+  "on-enter",
+  "on-exit",
+  "on-transition"
+]);
+function errorMessage(error) {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}`;
+  }
+  return String(error);
+}
+function delayAfterAttempt(attempts) {
+  return RECOVERY_DELAYS_MS[attempts - 1] ?? RECOVERY_DELAYS_MS[RECOVERY_DELAYS_MS.length - 1];
+}
+function validateCallbackResult(definition, kind, value) {
+  if (VOID_CALLBACKS.has(kind)) {
+    return { ok: true, result: null };
+  }
+  const schema = kind === "guard" ? z2.boolean() : z2.enum([...definition.statesByName.keys()]);
+  const parsed = schema.safeParse(value);
+  return parsed.success ? { ok: true, result: parsed.data } : {
+    ok: false,
+    message: `${kind === "guard" ? "guard result must be a boolean" : "start state must be an authored state"}: ${parsed.error.message}`
+  };
+}
+var RuntimeCore = class {
+  constructor(store, onObserverError, onRecoveryError) {
+    this.store = store;
+    this.onObserverError = onObserverError;
+    this.onRecoveryError = onRecoveryError;
+  }
+  store;
+  onObserverError;
+  onRecoveryError;
+  instances = /* @__PURE__ */ new Map();
+  active = /* @__PURE__ */ new Set();
+  abort = new AbortController();
+  closing = false;
+  closePromise = null;
+  assertOpen() {
+    if (this.closing) {
+      throw new DurableRuntimeClosedError("The durable runtime is closed");
+    }
+  }
+  /**
+   * Stops admission and scheduling, aborts the shared signal, waits for active callbacks to
+   * settle and checkpoint, then releases the database (ADR 0061). With `timeoutMs`, rejects with
+   * {@link DurableShutdownTimeoutError} if callbacks are still running by then; the database
+   * stays owned because those callbacks may still write (ADR 0075). Calling close again keeps waiting.
+   */
+  close(options = {}) {
+    if (!this.closePromise) {
+      this.closing = true;
+      for (const instance of this.instances.values()) {
+        this.clearTimer(instance);
+      }
+      this.abort.abort(
+        new DurableRuntimeClosedError("The durable runtime is closing")
+      );
+      this.closePromise = (async () => {
+        while (this.active.size > 0) {
+          await Promise.allSettled([...this.active]);
+        }
+        this.store.close();
+      })();
+    }
+    const { timeoutMs } = options;
+    if (timeoutMs === void 0) {
+      return this.closePromise;
+    }
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+      timer = setTimeout(
+        () => reject(
+          new DurableShutdownTimeoutError(
+            `${this.active.size} callback execution(s) did not settle within ${timeoutMs} ms; the database is still owned. Exit the process to release it; interrupted work recovers on the next open.`
+          )
+        ),
+        timeoutMs
+      );
+    });
+    return Promise.race([this.closePromise, timeout]).finally(
+      () => clearTimeout(timer)
+    );
+  }
+  get isClosed() {
+    return this.closing;
+  }
+  /** Simulates a crash: stops scheduling and drops the connection without waiting. */
+  abandon() {
+    this.closing = true;
+    for (const instance of this.instances.values()) {
+      this.clearTimer(instance);
+    }
+    this.closePromise = Promise.resolve();
+    this.store.close();
+  }
+  // --- observation ---------------------------------------------------------
+  snapshot(instance) {
+    return this.snapshotOf(instance.id);
+  }
+  /** Snapshot read from storage; works for instances this runtime has not opened. */
+  snapshotOf(instanceId2) {
+    this.assertStoreOpen();
+    const row = this.requireInstanceRow(instanceId2);
+    return Object.freeze({
+      instanceId: instanceId2,
+      chartName: row.chart_name,
+      state: row.state,
+      revision: row.revision,
+      status: Object.freeze(this.status(row)),
+      stall: this.instances.get(instanceId2)?.stall ?? null
+    });
+  }
+  status(row) {
+    const execution = row.current_execution_id === null ? void 0 : this.store.getExecution(row.current_execution_id);
+    switch (row.status) {
+      case "ready":
+        return { kind: "ready" };
+      case "terminated":
+        return { kind: "terminated", reason: row.status_reason ?? "" };
+      case "running":
+        return {
+          kind: "running",
+          requestId: execution?.request_id ?? null
+        };
+      case "recovering":
+      case "needs-attention": {
+        const operation = execution ? this.store.findUnresolvedOperation(execution.execution_id) : void 0;
+        if (!execution || !operation) {
+          return { kind: "running", requestId: null };
+        }
+        const work = this.work(execution, operation);
+        return row.status === "recovering" ? { kind: "recovering", work } : { kind: "needs-attention", work, reason: row.status_reason ?? "" };
+      }
+    }
+  }
+  work(execution, operation) {
+    return Object.freeze({
+      operationId: operation.operation_id,
+      requestId: execution.request_id,
+      callback: Object.freeze(callbackRef(operation)),
+      strategy: operation.strategy,
+      attempts: operation.attempts,
+      lastError: operation.last_error,
+      nextAttemptAt: operation.next_attempt_at
+    });
+  }
+  currentWork(instanceId2) {
+    const row = this.requireInstanceRow(instanceId2);
+    if (row.current_execution_id === null) {
+      return null;
+    }
+    const execution = this.store.getExecution(row.current_execution_id);
+    const operation = execution ? this.store.findUnresolvedOperation(execution.execution_id) : void 0;
+    return execution && operation ? this.work(execution, operation) : null;
+  }
+  assertStoreOpen() {
+    if (!this.store.isOpen) {
+      throw new DurableRuntimeClosedError("The durable runtime is closed");
+    }
+  }
+  history(instanceId2, query = {}) {
+    this.assertStoreOpen();
+    const limit = clampLimit(query.limit, 100, 1e3);
+    const afterSequence = Math.max(0, Math.floor(query.afterSequence ?? 0));
+    const rows = this.store.listHistory(instanceId2, {
+      afterSequence,
+      limit: limit + 1
+    });
+    const events = rows.slice(0, limit).map(
+      (row) => Object.freeze({
+        sequence: row.sequence,
+        at: row.at,
+        type: row.type,
+        requestId: row.request_id,
+        operationId: row.operation_id,
+        attemptId: row.attempt_id,
+        data: parseJson(row.data_json)
+      })
+    );
+    return Object.freeze({
+      events: Object.freeze(events),
+      nextAfterSequence: rows.length > limit ? events[events.length - 1]?.sequence ?? null : null
+    });
+  }
+  listInstances(query = {}) {
+    this.assertStoreOpen();
+    const limit = clampLimit(query.limit, 50, 500);
+    const statuses = query.status === void 0 ? null : Array.isArray(query.status) ? query.status : [query.status];
+    const rows = this.store.listInstances({
+      chartName: query.chartName ?? null,
+      statuses,
+      afterInstanceId: query.after ?? null,
+      limit: limit + 1
+    });
+    const instances = rows.slice(0, limit).map(
+      (row) => Object.freeze({
+        instanceId: row.instance_id,
+        chartName: row.chart_name,
+        state: row.state,
+        status: row.status,
+        statusReason: row.status_reason,
+        revision: row.revision,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at
+      })
+    );
+    return Object.freeze({
+      instances: Object.freeze(instances),
+      next: rows.length > limit ? instances[instances.length - 1]?.instanceId ?? null : null
+    });
+  }
+  /** SQLite lock contention can clear without application intervention; other faults stay visible. */
+  isTransientInfrastructureError(error) {
+    if (typeof error !== "object" || error === null) return false;
+    const code = "code" in error ? error.code : void 0;
+    const number = "errcode" in error ? error.errcode : void 0;
+    return code === "SQLITE_BUSY" || code === "SQLITE_LOCKED" || typeof number === "number" && [5, 6].includes(number & 255);
+  }
+  /** Records an infrastructure stall and tells observers, without letting a broken store throw. */
+  markStalled(instance, error) {
+    instance.stall = Object.freeze({
+      error: errorMessage(error),
+      at: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    try {
+      this.notify(instance);
+    } catch {
+    }
+    if (!this.closing && instance.timer === null && this.isTransientInfrastructureError(error) && instance.infrastructureRetries < RECOVERY_DELAYS_MS.length) {
+      const delay = RECOVERY_DELAYS_MS[instance.infrastructureRetries++];
+      instance.timer = setTimeout(() => {
+        instance.timer = null;
+        if (this.closing || !instance.stalled) return;
+        try {
+          this.startRecovery(instance);
+        } catch (failure) {
+          this.markStalled(instance, failure);
+          this.reportRecoveryError(failure);
+        }
+      }, delay);
+      instance.timer.unref?.();
+    }
+  }
+  /** Explicit restart after a stall (ADR 0076). Returns false when there was nothing to restart. */
+  restartRecovery(instance) {
+    this.assertOpen();
+    if (instance.stall === null || instance.activeExecutionId !== null) {
+      return false;
+    }
+    this.clearTimer(instance);
+    instance.infrastructureRetries = 0;
+    this.startRecovery(instance);
+    this.notify(instance);
+    return true;
+  }
+  /** Runtime-wide snapshot listeners (companion tools). */
+  runtimeListeners = /* @__PURE__ */ new Set();
+  /** Delivers the current snapshot; listener failures never affect execution (ADR 0059). */
+  notify(instance) {
+    if (instance.listeners.size === 0 && this.runtimeListeners.size === 0) {
+      return;
+    }
+    this.store.afterCommit(() => this.deliver(instance));
+  }
+  deliver(instance) {
+    if (!this.store.isOpen) {
+      return;
+    }
+    let snapshot;
+    try {
+      snapshot = this.snapshot(instance);
+    } catch (error) {
+      this.reportObserverError(error);
+      return;
+    }
+    const listeners = [...instance.listeners, ...this.runtimeListeners];
+    queueMicrotask(() => {
+      for (const listener of listeners) {
+        try {
+          const result = listener(snapshot);
+          if (isThenable(result)) {
+            result.then(
+              void 0,
+              (error) => this.reportObserverError(error)
+            );
+          }
+        } catch (error) {
+          this.reportObserverError(error);
+        }
+      }
+    });
+  }
+  reportObserverError(error) {
+    try {
+      this.onObserverError(error);
+    } catch {
+    }
+  }
+  reportRecoveryError(error) {
+    try {
+      this.onRecoveryError(error);
+    } catch {
+    }
+  }
+  record(instanceId2, type, data, refs = {}) {
+    this.store.appendHistory({
+      instance_id: instanceId2,
+      type,
+      request_id: refs.requestId ?? null,
+      operation_id: refs.operationId ?? null,
+      attempt_id: refs.attemptId ?? null,
+      data_json: canonicalJson(data)
+    });
+  }
+  requireInstanceRow(instanceId2) {
+    const row = this.store.getInstance(instanceId2);
+    if (!row) {
+      throw new Error(`Durable instance ${instanceId2} is missing from storage`);
+    }
+    return row;
+  }
+  // --- execution tracking --------------------------------------------------
+  /** Marks the instance busy while `work` runs and lets close() wait for it. */
+  track(instance, executionId, work) {
+    instance.activeExecutionId = executionId;
+    const promise = work().then((result) => {
+      instance.infrastructureRetries = 0;
+      return result;
+    }).catch((error) => {
+      this.markStalled(instance, error);
+      throw error;
+    }).finally(() => {
+      instance.activeExecutionId = null;
+      this.active.delete(promise);
+    });
+    this.active.add(promise);
+    return promise;
+  }
+  // --- stepping ------------------------------------------------------------
+  /** Runs the execution from its checkpointed step until it finishes or suspends. */
+  async advance(instance, executionId) {
+    const { definition } = instance.flow;
+    for (; ; ) {
+      const execution = this.requireExecution(executionId);
+      if (execution.status !== "running") {
+        return;
+      }
+      const step = execution.step;
+      switch (step) {
+        case "resolve-start-state": {
+          const input = parseJson(execution.input_json);
+          const resolver = definition.resolveStartState;
+          let target2 = input.startState ?? definition.initialState.name;
+          if (input.startState === null && resolver) {
+            const outcome = await this.runStep(
+              instance,
+              execution,
+              "resolve-start-state"
+            );
+            if (outcome.kind === "suspended") {
+              return;
+            }
+            target2 = outcome.result;
+          }
+          this.store.updateExecution(executionId, {
+            to_state: target2,
+            step: "commit"
+          });
+          continue;
+        }
+        case "commit": {
+          this.store.transaction(() => {
+            this.store.updateInstance(instance.id, {
+              state: execution.to_state ?? void 0
+            });
+            this.store.updateExecution(executionId, { step: "on-enter" });
+            this.record(
+              instance.id,
+              "state-committed",
+              { from: execution.from_state, to: execution.to_state },
+              { requestId: execution.request_id }
+            );
+          });
+          this.notify(instance);
+          continue;
+        }
+        case "guard": {
+          const outcome = await this.runStep(instance, execution, "guard");
+          if (outcome.kind === "suspended") {
+            return;
+          }
+          if (outcome.result === false) {
+            this.finish(instance, execution, "blocked");
+            return;
+          }
+          this.store.updateExecution(executionId, { step: "on-exit" });
+          continue;
+        }
+        case "on-exit":
+        case "on-transition":
+        case "on-enter": {
+          const outcome = await this.runStep(instance, execution, step);
+          if (outcome.kind === "suspended") {
+            return;
+          }
+          this.store.updateExecution(executionId, { step: nextStep(step) });
+          continue;
+        }
+        case "done":
+          this.finish(instance, execution, "applied");
+          return;
+      }
+    }
+  }
+  finish(instance, execution, status) {
+    this.store.transaction(() => {
+      this.store.updateExecution(execution.execution_id, { status });
+      this.store.updateInstance(instance.id, {
+        status: "ready",
+        status_reason: null,
+        current_execution_id: null
+      });
+      this.record(
+        instance.id,
+        status === "applied" ? "execution-applied" : "execution-blocked",
+        { kind: execution.kind, transition: execution.transition },
+        { requestId: execution.request_id }
+      );
+    });
+    this.notify(instance);
+  }
+  invocation(instance, execution, kind) {
+    const { definition, config } = instance.flow;
+    const chartName = definition.chartName;
+    if (kind === "resolve-start-state") {
+      return {
+        callback: definition.resolveStartState,
+        context: {
+          chartName,
+          initialStateName: definition.initialState.name,
+          config
+        },
+        args: []
+      };
+    }
+    if (execution.kind === "create") {
+      const target2 = this.requireState(definition, execution.to_state);
+      const isInitial = target2.id === definition.initialState.id;
+      return {
+        // Restoring into a non-initial state does not run onEnter (ADR 0035).
+        callback: isInitial ? target2.onEnter : null,
+        context: {
+          chartName,
+          stateName: target2.name,
+          transitionName: "default",
+          config
+        },
+        args: []
+      };
+    }
+    const transition = definition.transitionsByName.get(
+      execution.transition ?? ""
+    );
+    if (!transition) {
+      throw new Error(
+        `Transition ${execution.transition} is missing from definition ${definition.chartName}`
+      );
+    }
+    const payload = parseJson(execution.input_json).payload;
+    switch (kind) {
+      case "guard":
+      case "on-transition":
+        return {
+          callback: kind === "guard" ? transition.guard : transition.onTransition,
+          context: {
+            chartName,
+            fromState: transition.from.name,
+            toState: transition.to.name,
+            transitionName: transition.name,
+            config
+          },
+          args: [payload]
+        };
+      case "on-exit":
+        return {
+          callback: transition.from.onExit,
+          context: {
+            chartName,
+            stateName: transition.from.name,
+            transitionName: transition.name,
+            config
+          },
+          args: []
+        };
+      case "on-enter":
+        return {
+          callback: transition.to.onEnter,
+          context: {
+            chartName,
+            stateName: transition.to.name,
+            transitionName: transition.name,
+            config
+          },
+          args: []
+        };
+    }
+  }
+  requireState(definition, name) {
+    const state = definition.statesByName.get(name ?? "");
+    if (!state) {
+      throw new Error(
+        `State ${name} is missing from definition ${definition.chartName}`
+      );
+    }
+    return state;
+  }
+  /** Returns a checkpointed result, or creates the operation and runs it once. */
+  async runStep(instance, execution, kind) {
+    const invocation = this.invocation(instance, execution, kind);
+    if (!invocation.callback) {
+      return { kind: "completed", result: null };
+    }
+    const existing = this.store.findOperation(execution.execution_id, kind);
+    if (existing) {
+      return existing.status === "completed" ? { kind: "completed", result: parseJson(existing.result_json) } : { kind: "suspended" };
+    }
+    const operation = {
+      operation_id: mintOperationId(),
+      execution_id: execution.execution_id,
+      instance_id: instance.id,
+      callback_kind: kind,
+      callback_target: callbackTarget(invocation, kind),
+      strategy: invocation.callback.strategy,
+      status: "running",
+      result_json: null,
+      attempts: 0,
+      attempt_limit: MAX_ATTEMPTS,
+      last_error: null,
+      last_cause: null,
+      next_attempt_at: null
+    };
+    return this.attempt(instance, execution, operation, "run", {
+      prelude: () => this.store.insertOperation(operation)
+    });
+  }
+  /**
+   * One attempt at an operation. The operation and attempt are persisted in one transaction
+   * before user code runs, so a crash mid-callback is detected as interrupted on the next open
+   * (ADR 0055, 0065). The attempt's result is settled in a second single transaction.
+   */
+  async attempt(instance, execution, operation, mode, options = {}) {
+    const invocation = this.invocation(
+      instance,
+      execution,
+      operation.callback_kind
+    );
+    const callback = invocation.callback;
+    if (!callback) {
+      throw new Error(
+        `Operation ${operation.operation_id} has no callback in the current definition`
+      );
+    }
+    const attemptNumber = operation.attempts + 1;
+    const attemptId = mintAttemptId();
+    this.store.transaction(() => {
+      options.prelude?.();
+      this.store.updateOperation(operation.operation_id, {
+        status: "running",
+        attempts: attemptNumber,
+        next_attempt_at: null
+      });
+      this.store.insertAttempt({
+        attempt_id: attemptId,
+        operation_id: operation.operation_id,
+        mode,
+        number: attemptNumber
+      });
+      this.record(
+        instance.id,
+        "callback-started",
+        { callback: operation.callback_kind, mode, attempt: attemptNumber },
+        {
+          requestId: execution.request_id,
+          operationId: operation.operation_id,
+          attemptId
+        }
+      );
+    });
+    const refs = {
+      requestId: execution.request_id,
+      operationId: operation.operation_id,
+      attemptId
+    };
+    const context = {
+      ...invocation.context,
+      instanceId: instance.id,
+      operation: Object.freeze({
+        operationId: operation.operation_id,
+        attemptId,
+        attempt: attemptNumber
+      }),
+      signal: this.abort.signal
+    };
+    const current = this.requireOperation(operation.operation_id);
+    if (mode === "run") {
+      let value;
+      try {
+        value = await callback.run(context, ...invocation.args);
+      } catch (error) {
+        const cause = this.closing ? "interrupted" : "failed";
+        return this.store.transaction(() => {
+          this.store.finishAttempt(attemptId, cause, errorMessage(error));
+          return this.failed(
+            instance,
+            execution,
+            current,
+            cause,
+            errorMessage(error),
+            refs
+          );
+        });
+      }
+      return this.store.transaction(() => {
+        const validated = validateCallbackResult(
+          instance.flow.definition,
+          operation.callback_kind,
+          value
+        );
+        if (!validated.ok) {
+          this.store.finishAttempt(
+            attemptId,
+            "invalid-result",
+            validated.message
+          );
+          return this.escalate(
+            instance,
+            execution,
+            current,
+            `Invalid callback result: ${validated.message}`,
+            refs
+          );
+        }
+        return this.complete(
+          instance,
+          execution,
+          current,
+          attemptId,
+          validated.result,
+          refs
+        );
+      });
+    }
+    const reconcile = callback.reconcile;
+    if (!reconcile) {
+      throw new Error(
+        `Operation ${operation.operation_id} has no reconcile function`
+      );
+    }
+    let decision;
+    try {
+      decision = await reconcile(
+        {
+          ...context,
+          recovery: Object.freeze({
+            cause: operation.last_cause ?? "failed",
+            lastError: operation.last_error
+          })
+        },
+        ...invocation.args
+      );
+    } catch (error) {
+      return this.store.transaction(() => {
+        this.store.finishAttempt(attemptId, "failed", errorMessage(error));
+        this.store.updateOperation(current.operation_id, {
+          last_error: errorMessage(error)
+        });
+        return this.scheduleOrEscalate(
+          instance,
+          execution,
+          this.requireOperation(current.operation_id),
+          refs,
+          this.closing ? 0 : delayAfterAttempt(attemptNumber)
+        );
+      });
+    }
+    const settled = this.store.transaction(
+      () => this.settleReconcile(
+        instance,
+        execution,
+        current,
+        attemptId,
+        decision,
+        refs
+      )
+    );
+    return settled === "replay" ? this.attempt(instance, execution, current, "run") : settled;
+  }
+  /** Applies one reconciliation decision (ADR 0064). Runs inside a transaction. */
+  settleReconcile(instance, execution, operation, attemptId, decision, refs) {
+    const kind = isRecord2(decision) ? decision.decision : void 0;
+    switch (kind) {
+      case "completed": {
+        const validated = validateCallbackResult(
+          instance.flow.definition,
+          operation.callback_kind,
+          decision.result
+        );
+        if (!validated.ok) {
+          this.store.finishAttempt(
+            attemptId,
+            "invalid-result",
+            validated.message
+          );
+          return this.escalate(
+            instance,
+            execution,
+            operation,
+            `Invalid reconciliation result: ${validated.message}`,
+            refs
+          );
+        }
+        return this.complete(
+          instance,
+          execution,
+          operation,
+          attemptId,
+          validated.result,
+          refs
+        );
+      }
+      case "safe-to-retry":
+        this.store.finishAttempt(attemptId, "safe-to-retry", null);
+        if (operation.attempts >= operation.attempt_limit) {
+          return this.escalate(
+            instance,
+            execution,
+            operation,
+            exhaustedReason(operation),
+            refs
+          );
+        }
+        return "replay";
+      case "pending":
+        this.store.finishAttempt(attemptId, "pending", null);
+        return this.scheduleOrEscalate(
+          instance,
+          execution,
+          operation,
+          refs,
+          delayAfterAttempt(operation.attempts)
+        );
+      case "needs-attention": {
+        const reason = decision.reason;
+        this.store.finishAttempt(attemptId, "needs-attention", null);
+        return this.escalate(
+          instance,
+          execution,
+          operation,
+          typeof reason === "string" && reason.length > 0 ? reason : "Reconciliation requires attention",
+          refs
+        );
+      }
+      default:
+        this.store.finishAttempt(attemptId, "invalid-decision", null);
+        return this.escalate(
+          instance,
+          execution,
+          operation,
+          "Reconciliation returned an invalid decision",
+          refs
+        );
+    }
+  }
+  complete(instance, execution, operation, attemptId, result, refs) {
+    this.store.transaction(() => {
+      this.checkpoint(instance, execution, operation, result);
+      this.store.finishAttempt(attemptId, "completed", null);
+      this.record(
+        instance.id,
+        "callback-completed",
+        { callback: operation.callback_kind, result },
+        refs
+      );
+    });
+    return { kind: "completed", result };
+  }
+  /**
+   * Records a callback as completed and, in the same transaction, marks a suspended execution
+   * running again, so a crash can never leave a completed callback whose execution never resumes.
+   * Must run inside a transaction.
+   */
+  checkpoint(instance, execution, operation, result) {
+    this.store.updateOperation(operation.operation_id, {
+      status: "completed",
+      result_json: JSON.stringify(result),
+      next_attempt_at: null
+    });
+    if (this.requireExecution(execution.execution_id).status !== "running") {
+      this.store.updateExecution(execution.execution_id, { status: "running" });
+      this.store.updateInstance(instance.id, {
+        status: "running",
+        status_reason: null
+      });
+    }
+  }
+  /** Applies the declared strategy after a failed or interrupted run (ADR 0046). */
+  failed(instance, execution, operation, cause, message, refs) {
+    return this.store.transaction(() => {
+      this.store.updateOperation(operation.operation_id, {
+        last_error: message,
+        last_cause: cause
+      });
+      this.record(
+        instance.id,
+        cause === "interrupted" ? "recovery-interrupted" : "callback-failed",
+        { callback: operation.callback_kind, error: message },
+        refs
+      );
+      return this.settleFailure(
+        instance,
+        execution,
+        operation,
+        cause,
+        message,
+        refs
+      );
+    });
+  }
+  settleFailure(instance, execution, operation, cause, message, refs) {
+    const current = this.requireOperation(operation.operation_id);
+    if (current.strategy === "manual") {
+      return this.escalate(
+        instance,
+        execution,
+        current,
+        `Manual recovery required: ${message}`,
+        refs
+      );
+    }
+    return this.scheduleOrEscalate(
+      instance,
+      execution,
+      current,
+      refs,
+      cause === "interrupted" ? 0 : delayAfterAttempt(current.attempts)
+    );
+  }
+  scheduleOrEscalate(instance, execution, operation, refs, delayMs) {
+    if (operation.attempts >= operation.attempt_limit) {
+      return this.escalate(
+        instance,
+        execution,
+        operation,
+        exhaustedReason(operation),
+        refs
+      );
+    }
+    const nextAttemptAt = new Date(Date.now() + delayMs).toISOString();
+    this.store.transaction(() => {
+      this.store.updateOperation(operation.operation_id, {
+        status: "recovering",
+        next_attempt_at: nextAttemptAt
+      });
+      this.store.updateExecution(execution.execution_id, {
+        status: "recovering"
+      });
+      this.store.updateInstance(instance.id, {
+        status: "recovering",
+        status_reason: null
+      });
+      this.record(
+        instance.id,
+        "recovery-scheduled",
+        { callback: operation.callback_kind, nextAttemptAt },
+        refs
+      );
+    });
+    this.scheduleTimer(instance, delayMs);
+    this.notify(instance);
+    return { kind: "suspended" };
+  }
+  escalate(instance, execution, operation, reason, refs) {
+    this.store.transaction(() => {
+      this.store.updateOperation(operation.operation_id, {
+        status: "needs-attention",
+        next_attempt_at: null
+      });
+      this.store.updateExecution(execution.execution_id, {
+        status: "needs-attention"
+      });
+      this.store.updateInstance(instance.id, {
+        status: "needs-attention",
+        status_reason: reason
+      });
+      this.record(
+        instance.id,
+        "needs-attention",
+        { callback: operation.callback_kind, reason },
+        refs
+      );
+    });
+    this.notify(instance);
+    return { kind: "suspended" };
+  }
+  // --- recovery scheduling -------------------------------------------------
+  scheduleTimer(instance, delayMs) {
+    this.store.afterCommit(() => this.armTimer(instance, delayMs));
+  }
+  armTimer(instance, delayMs) {
+    this.clearTimer(instance);
+    if (this.closing) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      instance.timer = null;
+      void this.recover(instance).catch((error) => {
+        this.markStalled(instance, error);
+        this.reportRecoveryError(error);
+      });
+    }, delayMs);
+    timer.unref?.();
+    instance.timer = timer;
+  }
+  clearTimer(instance) {
+    if (instance.timer !== null) {
+      clearTimeout(instance.timer);
+      instance.timer = null;
+    }
+  }
+  /** One scheduled automatic recovery attempt for the instance's unresolved operation. */
+  async recover(instance) {
+    if (this.closing) {
+      return;
+    }
+    if (instance.activeExecutionId !== null) {
+      this.scheduleTimer(instance, BUSY_RETRY_DELAY_MS);
+      return;
+    }
+    const row = this.requireInstanceRow(instance.id);
+    if (row.status !== "recovering" || row.current_execution_id === null) {
+      return;
+    }
+    const execution = this.requireExecution(row.current_execution_id);
+    const operation = this.store.findUnresolvedOperation(
+      execution.execution_id
+    );
+    if (!operation || operation.status !== "recovering") {
+      return;
+    }
+    await this.track(
+      instance,
+      execution.execution_id,
+      () => this.recoverOnce(instance, execution, operation)
+    );
+  }
+  /**
+   * One recovery attempt following the declared strategy (reconcile, or run again for
+   * safe-replay and manual), then the execution's remaining steps if it completed.
+   */
+  async recoverOnce(instance, execution, operation, prelude) {
+    const mode = operation.strategy === "reconcile" ? "reconcile" : "run";
+    const outcome = await this.attempt(instance, execution, operation, mode, {
+      prelude
+    });
+    if (outcome.kind === "completed") {
+      this.notify(instance);
+      await this.advance(instance, execution.execution_id);
+    }
+  }
+  /**
+   * Operator retry (ADR 0073): grants one more bounded attempt and commits it, the resumed
+   * status and the audit entry together with the attempt start, so a crash cannot strand it.
+   */
+  manualRetry(instance, execution, operation, audit) {
+    return this.track(
+      instance,
+      execution.execution_id,
+      () => this.recoverOnce(instance, execution, operation, () => {
+        this.store.updateOperation(operation.operation_id, {
+          // A reconcile check may conclude safe-to-retry, so it also gets the replay it permits.
+          attempt_limit: operation.attempts + (operation.strategy === "reconcile" ? 2 : 1)
+        });
+        this.store.updateExecution(execution.execution_id, {
+          status: "running"
+        });
+        this.store.updateInstance(instance.id, {
+          status: "running",
+          status_reason: null
+        });
+        audit();
+      })
+    );
+  }
+  /**
+   * Starts recovery for an instance loaded from storage (ADR 0050), or restarts it after a
+   * stall. Also repairs an execution whose callback completed but which never resumed.
+   */
+  startRecovery(instance) {
+    instance.stall = null;
+    if (instance.activeExecutionId !== null) {
+      return;
+    }
+    const row = this.requireInstanceRow(instance.id);
+    if (row.status === "ready" || row.status === "terminated" || row.current_execution_id === null) {
+      return;
+    }
+    const execution = this.requireExecution(row.current_execution_id);
+    const operation = this.store.findUnresolvedOperation(
+      execution.execution_id
+    );
+    if (operation?.status === "running") {
+      this.store.transaction(() => {
+        this.store.finishInterruptedAttempts(operation.operation_id);
+        this.failed(
+          instance,
+          execution,
+          operation,
+          "interrupted",
+          "The process stopped while the callback was running",
+          {
+            requestId: execution.request_id,
+            operationId: operation.operation_id
+          }
+        );
+      });
+      return;
+    }
+    if (operation?.status === "recovering") {
+      const due = operation.next_attempt_at ? Date.parse(operation.next_attempt_at) - Date.now() : 0;
+      this.scheduleTimer(instance, Math.max(0, due));
+      return;
+    }
+    if (operation) {
+      return;
+    }
+    if (execution.status !== "running") {
+      this.store.transaction(() => {
+        this.store.updateExecution(execution.execution_id, {
+          status: "running"
+        });
+        this.store.updateInstance(instance.id, {
+          status: "running",
+          status_reason: null
+        });
+      });
+    }
+    void this.track(
+      instance,
+      execution.execution_id,
+      () => this.advance(instance, execution.execution_id)
+    ).catch((error) => {
+      this.markStalled(instance, error);
+      this.reportRecoveryError(error);
+    });
+  }
+  // --- lookups -------------------------------------------------------------
+  requireExecution(executionId) {
+    const execution = this.store.getExecution(executionId);
+    if (!execution) {
+      throw new Error(`Execution ${executionId} is missing from storage`);
+    }
+    return execution;
+  }
+  requireOperation(operationId) {
+    const operation = this.store.getOperation(operationId);
+    if (!operation) {
+      throw new Error(`Operation ${operationId} is missing from storage`);
+    }
+    return operation;
+  }
+};
+function isThenable(value) {
+  return (typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function";
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function exhaustedReason(operation) {
+  const last = operation.last_error ? `: ${operation.last_error}` : "";
+  return `Automatic recovery exhausted after ${operation.attempts} attempts${last}`;
+}
+function nextStep(step) {
+  switch (step) {
+    case "on-exit":
+      return "on-transition";
+    case "on-transition":
+      return "commit";
+    case "on-enter":
+      return "done";
+  }
+}
+function callbackTarget(invocation, kind) {
+  const context = invocation.context;
+  switch (kind) {
+    case "resolve-start-state":
+      return null;
+    case "on-enter":
+    case "on-exit":
+      return context.stateName;
+    case "guard":
+    case "on-transition":
+      return context.transitionName;
+  }
+}
+function callbackRef(operation) {
+  const target2 = operation.callback_target ?? "";
+  switch (operation.callback_kind) {
+    case "resolve-start-state":
+      return { kind: "resolve-start-state" };
+    case "on-enter":
+    case "on-exit":
+      return { kind: operation.callback_kind, state: target2 };
+    case "guard":
+    case "on-transition":
+      return { kind: operation.callback_kind, transition: target2 };
+  }
+}
+
+// src/durable/resolve-input.ts
+import { z as z3 } from "zod";
+var target = {
+  operationId: z3.string().min(1).transform((value) => value),
+  expectedAttempts: z3.number().int().nonnegative(),
+  reason: z3.string().refine((value) => value.trim().length > 0, "A reason is required")
+};
+var confirmation = z3.discriminatedUnion("callback", [
+  z3.strictObject({
+    ...target,
+    action: z3.literal("confirm-completed"),
+    callback: z3.literal("guard"),
+    result: z3.boolean()
+  }),
+  z3.strictObject({
+    ...target,
+    action: z3.literal("confirm-completed"),
+    callback: z3.literal("resolve-start-state"),
+    result: z3.string()
+  }),
+  z3.strictObject({
+    ...target,
+    action: z3.literal("confirm-completed"),
+    callback: z3.enum(["on-enter", "on-exit", "on-transition"]),
+    result: z3.null().optional()
+  }).transform(({ result, ...input }) => {
+    void result;
+    return input;
+  })
+]);
+var resolveInputSchema = z3.discriminatedUnion("action", [
+  z3.strictObject({ ...target, action: z3.literal("retry") }),
+  z3.strictObject({ ...target, action: z3.literal("terminate") }),
+  confirmation
+]);
+function parseResolveInput(value) {
+  const result = resolveInputSchema.safeParse(value);
+  if (!result.success) {
+    throw new DurableInputError(
+      `Invalid resolve input: ${result.error.message}`
+    );
+  }
+  return result.data;
+}
+
+// src/durable/store.ts
+import { DatabaseSync } from "node:sqlite";
+var SCHEMA_VERSION = 2;
+var MIGRATIONS = {
+  // v1 (first durable runtime) lacked per-execution handler revisions (ADR 0076).
+  1: "ALTER TABLE executions ADD COLUMN handler_revision TEXT;"
+};
+var SCHEMA = `
+CREATE TABLE instances (
+  instance_id TEXT PRIMARY KEY,
+  chart_name TEXT NOT NULL,
+  definition_id TEXT NOT NULL,
+  state TEXT NOT NULL,
+  status TEXT NOT NULL,
+  status_reason TEXT,
+  current_execution_id TEXT,
+  revision INTEGER NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE TABLE executions (
+  execution_id TEXT PRIMARY KEY,
+  instance_id TEXT NOT NULL REFERENCES instances(instance_id),
+  kind TEXT NOT NULL,
+  request_id TEXT,
+  input_json TEXT NOT NULL,
+  from_state TEXT,
+  transition TEXT,
+  to_state TEXT,
+  step TEXT NOT NULL,
+  status TEXT NOT NULL,
+  handler_revision TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE (instance_id, request_id)
+);
+CREATE TABLE operations (
+  operation_id TEXT PRIMARY KEY,
+  execution_id TEXT NOT NULL REFERENCES executions(execution_id),
+  instance_id TEXT NOT NULL REFERENCES instances(instance_id),
+  callback_kind TEXT NOT NULL,
+  callback_target TEXT,
+  strategy TEXT NOT NULL,
+  status TEXT NOT NULL,
+  result_json TEXT,
+  attempts INTEGER NOT NULL,
+  attempt_limit INTEGER NOT NULL,
+  last_error TEXT,
+  last_cause TEXT,
+  next_attempt_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE (execution_id, callback_kind)
+);
+CREATE TABLE attempts (
+  attempt_id TEXT PRIMARY KEY,
+  operation_id TEXT NOT NULL REFERENCES operations(operation_id),
+  mode TEXT NOT NULL,
+  number INTEGER NOT NULL,
+  started_at TEXT NOT NULL,
+  finished_at TEXT,
+  outcome TEXT,
+  error TEXT
+);
+CREATE TABLE history (
+  sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+  instance_id TEXT NOT NULL REFERENCES instances(instance_id),
+  at TEXT NOT NULL,
+  type TEXT NOT NULL,
+  request_id TEXT,
+  operation_id TEXT,
+  attempt_id TEXT,
+  data_json TEXT NOT NULL
+);
+CREATE INDEX history_by_instance ON history (instance_id, sequence);
+`;
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+var DurableStore = class {
+  db;
+  transactionDepth = 0;
+  pendingEffects = [];
+  open = true;
+  constructor(databasePath) {
+    this.db = new DatabaseSync(databasePath, { timeout: 0 });
+    try {
+      this.db.exec("PRAGMA locking_mode = EXCLUSIVE;");
+      this.db.exec("PRAGMA synchronous = FULL;");
+      this.db.exec("PRAGMA foreign_keys = ON;");
+      this.db.exec("BEGIN EXCLUSIVE; COMMIT;");
+    } catch (cause) {
+      this.db.close();
+      throw new DurableOwnershipError(
+        `Another State Flow runtime owns ${databasePath}`,
+        { cause }
+      );
+    }
+    this.migrate();
+  }
+  migrate() {
+    const { user_version: version } = this.db.prepare("PRAGMA user_version").get();
+    if (version > SCHEMA_VERSION) {
+      this.db.close();
+      throw new DurableSchemaError(
+        `Database schema version ${version} is newer than supported version ${SCHEMA_VERSION}`
+      );
+    }
+    if (version > 0 && version < SCHEMA_VERSION) {
+      this.transaction(() => {
+        for (let from = version; from < SCHEMA_VERSION; from += 1) {
+          const migration = MIGRATIONS[from];
+          if (migration === void 0) {
+            throw new DurableSchemaError(
+              `No migration from schema version ${from}`
+            );
+          }
+          this.db.exec(migration);
+        }
+        this.db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+      });
+    }
+    if (version === 0) {
+      this.transaction(() => {
+        this.db.exec(SCHEMA);
+        this.db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+      });
+    }
+  }
+  get isOpen() {
+    return this.open;
+  }
+  close() {
+    if (this.open) {
+      this.open = false;
+      this.db.close();
+    }
+  }
+  /** Runs `work` atomically. Nested calls join the outer transaction. */
+  transaction(work) {
+    if (this.transactionDepth > 0) {
+      return work();
+    }
+    this.db.exec("BEGIN IMMEDIATE");
+    this.transactionDepth += 1;
+    let committed = false;
+    try {
+      const result = work();
+      this.db.exec("COMMIT");
+      committed = true;
+      return result;
+    } catch (error) {
+      this.db.exec("ROLLBACK");
+      throw error;
+    } finally {
+      this.transactionDepth -= 1;
+      const effects = this.pendingEffects.splice(0);
+      if (committed) {
+        for (const effect of effects) {
+          effect();
+        }
+      }
+    }
+  }
+  /**
+   * Runs `effect` once the current transaction commits (immediately outside one), and drops it
+   * on rollback. Used for notifications and timers, which must reflect committed state only.
+   */
+  afterCommit(effect) {
+    if (this.transactionDepth > 0) {
+      this.pendingEffects.push(effect);
+    } else {
+      effect();
+    }
+  }
+  // --- instances -----------------------------------------------------------
+  getInstance(instanceId2) {
+    return this.db.prepare("SELECT * FROM instances WHERE instance_id = ?").get(instanceId2);
+  }
+  insertInstance(row) {
+    const at = nowIso();
+    this.db.prepare(
+      `INSERT INTO instances (instance_id, chart_name, definition_id, state, status, status_reason,
+           current_execution_id, revision, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?, ?)`
+    ).run(
+      row.instance_id,
+      row.chart_name,
+      row.definition_id,
+      row.state,
+      row.status,
+      row.status_reason,
+      row.current_execution_id,
+      at,
+      at
+    );
+  }
+  updateInstance(instanceId2, changes) {
+    this.update("instances", "instance_id", instanceId2, changes, {
+      bumpRevision: true
+    });
+  }
+  // --- executions ----------------------------------------------------------
+  getExecution(executionId) {
+    return this.db.prepare("SELECT * FROM executions WHERE execution_id = ?").get(executionId);
+  }
+  findExecutionByRequest(instanceId2, requestId2) {
+    return this.db.prepare(
+      "SELECT * FROM executions WHERE instance_id = ? AND request_id = ?"
+    ).get(instanceId2, requestId2);
+  }
+  insertExecution(row) {
+    const at = nowIso();
+    this.db.prepare(
+      `INSERT INTO executions (execution_id, instance_id, kind, request_id, input_json, from_state,
+           transition, to_state, step, status, handler_revision, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      row.execution_id,
+      row.instance_id,
+      row.kind,
+      row.request_id,
+      row.input_json,
+      row.from_state,
+      row.transition,
+      row.to_state,
+      row.step,
+      row.status,
+      row.handler_revision,
+      at,
+      at
+    );
+  }
+  updateExecution(executionId, changes) {
+    this.update("executions", "execution_id", executionId, changes);
+  }
+  // --- operations ----------------------------------------------------------
+  getOperation(operationId) {
+    return this.db.prepare("SELECT * FROM operations WHERE operation_id = ?").get(operationId);
+  }
+  findOperation(executionId, kind) {
+    return this.db.prepare(
+      "SELECT * FROM operations WHERE execution_id = ? AND callback_kind = ?"
+    ).get(executionId, kind);
+  }
+  /** The execution's operation that is not completed, if any. */
+  findUnresolvedOperation(executionId) {
+    return this.db.prepare(
+      "SELECT * FROM operations WHERE execution_id = ? AND status != 'completed' ORDER BY created_at DESC LIMIT 1"
+    ).get(executionId);
+  }
+  insertOperation(row) {
+    const at = nowIso();
+    this.db.prepare(
+      `INSERT INTO operations (operation_id, execution_id, instance_id, callback_kind, callback_target,
+           strategy, status, attempts, attempt_limit, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      row.operation_id,
+      row.execution_id,
+      row.instance_id,
+      row.callback_kind,
+      row.callback_target,
+      row.strategy,
+      row.status,
+      row.attempts,
+      row.attempt_limit,
+      at,
+      at
+    );
+  }
+  updateOperation(operationId, changes) {
+    this.update("operations", "operation_id", operationId, changes);
+  }
+  // --- attempts ------------------------------------------------------------
+  insertAttempt(row) {
+    this.db.prepare(
+      "INSERT INTO attempts (attempt_id, operation_id, mode, number, started_at) VALUES (?, ?, ?, ?, ?)"
+    ).run(row.attempt_id, row.operation_id, row.mode, row.number, nowIso());
+  }
+  finishAttempt(attemptId, outcome, error) {
+    this.db.prepare(
+      "UPDATE attempts SET finished_at = ?, outcome = ?, error = ? WHERE attempt_id = ?"
+    ).run(nowIso(), outcome, error, attemptId);
+  }
+  /** Attempts left open by a process that stopped mid-callback. */
+  finishInterruptedAttempts(operationId) {
+    this.db.prepare(
+      "UPDATE attempts SET finished_at = ?, outcome = 'interrupted' WHERE operation_id = ? AND finished_at IS NULL"
+    ).run(nowIso(), operationId);
+  }
+  // --- history -------------------------------------------------------------
+  appendHistory(row) {
+    this.db.prepare(
+      `INSERT INTO history (instance_id, at, type, request_id, operation_id, attempt_id, data_json)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      row.instance_id,
+      nowIso(),
+      row.type,
+      row.request_id,
+      row.operation_id,
+      row.attempt_id,
+      row.data_json
+    );
+  }
+  /** One page of history in sequence order, after `afterSequence` (exclusive). */
+  listHistory(instanceId2, page) {
+    return this.db.prepare(
+      "SELECT * FROM history WHERE instance_id = ? AND sequence > ? ORDER BY sequence ASC LIMIT ?"
+    ).all(instanceId2, page.afterSequence, page.limit);
+  }
+  /** One page of instances ordered by ID, after `afterInstanceId` (exclusive). */
+  listInstances(query) {
+    const where = [];
+    const values = [];
+    if (query.chartName !== null) {
+      where.push("chart_name = ?");
+      values.push(query.chartName);
+    }
+    if (query.statuses !== null) {
+      if (query.statuses.length === 0) {
+        return [];
+      }
+      where.push(`status IN (${query.statuses.map(() => "?").join(", ")})`);
+      values.push(...query.statuses);
+    }
+    if (query.afterInstanceId !== null) {
+      where.push("instance_id > ?");
+      values.push(query.afterInstanceId);
+    }
+    const clause = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+    return this.db.prepare(
+      `SELECT * FROM instances ${clause} ORDER BY instance_id ASC LIMIT ?`
+    ).all(...values, query.limit);
+  }
+  // --- helpers -------------------------------------------------------------
+  update(table, keyColumn, key, changes, options = {}) {
+    const columns = Object.keys(changes).filter(
+      (column) => changes[column] !== void 0
+    );
+    const assignments = columns.map((column) => `${column} = ?`);
+    assignments.push("updated_at = ?");
+    if (options.bumpRevision) {
+      assignments.push("revision = revision + 1");
+    }
+    const values = columns.map((column) => changes[column] ?? null);
+    this.db.prepare(
+      `UPDATE ${table} SET ${assignments.join(", ")} WHERE ${keyColumn} = ?`
+    ).run(...values, nowIso(), key);
+  }
+};
+
+// src/durable/runtime.ts
+var runtimeCores = /* @__PURE__ */ new WeakMap();
+function createDurableRuntime(options) {
+  const store = new DurableStore(options.databasePath);
+  const core = new RuntimeCore(
+    store,
+    options.onObserverError ?? ((error) => console.error("State Flow observer failed", error)),
+    options.onRecoveryError ?? ((error) => console.error("State Flow background recovery failed", error))
+  );
+  const flowsByChart = /* @__PURE__ */ new Map();
+  function registerFlow(compiled, config, onFailure) {
+    core.assertOpen();
+    const definition = loadFlowDefinition(compiled);
+    if (flowsByChart.has(definition.chartName))
+      throw new DurableInputError(
+        `Flow "${definition.chartName}" is already registered with this runtime`
+      );
+    const flow = { definition, config };
+    const api = createFlowApi(core, flow, onFailure);
+    flowsByChart.set(definition.chartName, flow);
+    return api;
+  }
+  const runtime = {
+    createFlow(compiled, config) {
+      return {
+        handleFailure(onFailure) {
+          if (typeof onFailure !== "function")
+            throw new DurableInputError("A flow failure handler is required");
+          let pending;
+          return {
+            run() {
+              pending ??= Promise.resolve().then(() => {
+                try {
+                  return registerFlow(
+                    compiled,
+                    config,
+                    onFailure
+                  );
+                } catch (error) {
+                  return rejectFlowFailure(
+                    onFailure,
+                    new DurableOperationError("create-flow", error)
+                  );
+                }
+              });
+              return pending;
+            }
+          };
+        }
+      };
+    },
+    flow(compiled, config) {
+      return registerFlow(
+        compiled,
+        config
+      );
+    },
+    close: (options2) => core.close(options2),
+    inspector: {
+      listInstances: (query) => core.listInstances(query),
+      getSnapshot: (id) => {
+        const valid = instanceId(id);
+        return core.store.getInstance(valid) ? core.snapshotOf(valid) : null;
+      },
+      history: (id, query) => core.history(instanceId(id), query),
+      subscribe(listener) {
+        const wrapped = (snapshot) => listener(snapshot);
+        core.runtimeListeners.add(wrapped);
+        return () => {
+          core.runtimeListeners.delete(wrapped);
+        };
+      }
+    },
+    controls: {
+      async resolve(id, untrustedInput) {
+        core.assertOpen();
+        const valid = instanceId(id);
+        const input = parseResolveInput(untrustedInput);
+        const row = core.store.getInstance(valid);
+        if (!row) {
+          return {
+            outcome: "rejected",
+            reason: "unavailable",
+            message: `Instance ${valid} does not exist`
+          };
+        }
+        const flow = flowsByChart.get(row.chart_name);
+        const loaded = flow ? loadInstance(core, flow, valid) : void 0;
+        if (loaded?.kind === "opened") {
+          return resolve(core, loaded.instance, input);
+        }
+        if (input.action === "terminate") {
+          return terminateUnloadable(core, valid, input);
+        }
+        return {
+          outcome: "rejected",
+          reason: "unavailable",
+          message: flow ? `Instance ${valid} cannot be loaded by the registered flow (${loaded?.kind}); only terminate is available` : `No flow is registered for chart "${row.chart_name}"; only terminate is available`
+        };
+      },
+      restartRecovery(id) {
+        const instance = core.instances.get(instanceId(id));
+        return instance ? core.restartRecovery(instance) : false;
+      }
+    }
+  };
+  runtimeCores.set(runtime, core);
+  return runtime;
+}
+async function rejectFlowFailure(onFailure, failure) {
+  await onFailure(failure);
+  throw new DurableInputError(
+    "The flow failure handler must throw or transfer control"
+  );
+}
+function createFlowApi(core, flow, onFailure) {
+  const { definition } = flow;
+  let dispatchFailure = onFailure ? (failure) => rejectFlowFailure(onFailure, failure) : void 0;
+  const instanceApis = /* @__PURE__ */ new WeakMap();
+  const apiFor = (instance) => {
+    let api = instanceApis.get(instance);
+    if (!api) {
+      api = createInstanceApi(core, instance, () => dispatchFailure, onFailure);
+      instanceApis.set(instance, api);
+    }
+    return api;
+  };
+  async function createInstance(input) {
+    core.assertOpen();
+    const id = instanceId(input.instanceId);
+    if (input.startState !== void 0 && !definition.statesByName.has(input.startState)) {
+      throw new DurableInputError(
+        `Unknown start state ${JSON.stringify(input.startState)} for flow "${definition.chartName}"`
+      );
+    }
+    if (core.instances.has(id) || core.store.getInstance(id)) {
+      return { kind: "already-exists", id };
+    }
+    const executionId = mintExecutionId();
+    core.store.transaction(() => {
+      core.store.insertInstance({
+        instance_id: id,
+        chart_name: definition.chartName,
+        definition_id: definition.definitionId,
+        state: input.startState ?? definition.initialState.name,
+        status: "running",
+        status_reason: null,
+        current_execution_id: executionId
+      });
+      core.store.insertExecution({
+        execution_id: executionId,
+        instance_id: id,
+        kind: "create",
+        request_id: null,
+        input_json: canonicalJson({
+          startState: input.startState ?? null
+        }),
+        from_state: null,
+        transition: null,
+        to_state: null,
+        step: "resolve-start-state",
+        status: "running",
+        handler_revision: definition.handlerRevision
+      });
+      core.record(id, "instance-created", {
+        chartName: definition.chartName,
+        definitionId: definition.definitionId,
+        startState: input.startState ?? null
+      });
+    });
+    const instance = new InstanceCore(id, flow);
+    core.instances.set(id, instance);
+    await core.track(
+      instance,
+      executionId,
+      () => core.advance(instance, executionId)
+    );
+    return { kind: "created", instance, executionId };
+  }
+  const flowApi = {
+    chartName: definition.chartName,
+    definitionId: definition.definitionId,
+    ensureInstance(input) {
+      const captured = { instanceId: input.instanceId };
+      function prepare(override) {
+        let pending;
+        return {
+          handleEnsureInstance(handlers) {
+            assertHandlers(handlers, ["definition-mismatch"]);
+            return prepare(handlers);
+          },
+          run() {
+            pending ??= Promise.resolve().then(async () => {
+              if (!onFailure)
+                throw new DurableInputError(
+                  "Create this flow through createFlow(...).handleFailure(...).run() before using ensureInstance"
+                );
+              try {
+                return await flowApi.handleEnsure({
+                  "definition-mismatch": (context) => {
+                    throw new DurableDefinitionMismatchError(
+                      context
+                    );
+                  }
+                }).ensure(captured);
+              } catch (error) {
+                if (error instanceof DurableDefinitionMismatchError && override) {
+                  await override["definition-mismatch"](error.context);
+                  throw new DurableInputError(
+                    "The definition-mismatch handler must throw or transfer control"
+                  );
+                }
+                return rejectFlowFailure(
+                  onFailure,
+                  error instanceof DurableDefinitionMismatchError ? error : new DurableOperationError("ensure-instance", error)
+                );
+              }
+            });
+            return pending;
+          }
+        };
+      }
+      return prepare();
+    },
+    handleDispatch(onFailure2) {
+      core.assertOpen();
+      if (typeof onFailure2 !== "function")
+        throw new DurableInputError("A dispatch failure handler is required");
+      if (dispatchFailure)
+        throw new DurableInputError(
+          "This flow already has a dispatch failure handler"
+        );
+      dispatchFailure = onFailure2;
+      return flowApi;
+    },
+    handleEnsure(handlers) {
+      assertHandlers(handlers, ["definition-mismatch"]);
+      return {
+        async ensure(input) {
+          core.assertOpen();
+          const id = instanceId(input.instanceId);
+          let loaded = loadInstance(core, flow, id);
+          if (loaded.kind === "not-found") {
+            const created = await createInstance({ instanceId: id });
+            loaded = created.kind === "created" ? { kind: "opened", instance: created.instance } : loadInstance(core, flow, id);
+          }
+          if (loaded.kind === "mismatch") {
+            await handlers["definition-mismatch"](loaded.context);
+            throw new DurableInputError(
+              "The definition-mismatch handler must throw or transfer control; ensure cannot return an incompatible instance"
+            );
+          }
+          if (loaded.kind === "not-found") {
+            throw new DurableInputError(
+              `Instance ${id} disappeared during ensure`
+            );
+          }
+          return apiFor(loaded.instance);
+        }
+      };
+    },
+    handleCreate(handlers) {
+      assertHandlers(handlers, [
+        "created",
+        "already-exists",
+        "recovery-pending",
+        "needs-attention"
+      ]);
+      return {
+        async create(input) {
+          const created = await createInstance(input);
+          if (created.kind === "already-exists") {
+            return handlers["already-exists"]({ instanceId: created.id });
+          }
+          const { instance, executionId } = created;
+          const id = instance.id;
+          const api = apiFor(instance);
+          const snapshot = core.snapshot(instance);
+          const execution = core.requireExecution(executionId);
+          switch (execution.status) {
+            case "recovering":
+              return handlers["recovery-pending"]({
+                instance: api,
+                snapshot,
+                work: requireWork(core, id)
+              });
+            case "needs-attention":
+              return handlers["needs-attention"]({
+                instance: api,
+                snapshot,
+                work: requireWork(core, id),
+                reason: reasonOf(snapshot)
+              });
+            default:
+              return handlers.created({ instance: api, snapshot });
+          }
+        }
+      };
+    },
+    handleOpen(handlers) {
+      assertHandlers(handlers, ["opened", "not-found", "definition-mismatch"]);
+      return {
+        async open(rawInstanceId) {
+          core.assertOpen();
+          const id = instanceId(rawInstanceId);
+          const loaded = loadInstance(core, flow, id);
+          switch (loaded.kind) {
+            case "not-found":
+              return handlers["not-found"]({ instanceId: id });
+            case "mismatch":
+              return handlers["definition-mismatch"](loaded.context);
+          }
+          const instance = loaded.instance;
+          return handlers.opened({
+            instance: apiFor(instance),
+            snapshot: core.snapshot(instance)
+          });
+        }
+      };
+    }
+  };
+  return flowApi;
+}
+function loadInstance(core, flow, id) {
+  const { definition } = flow;
+  const row = core.store.getInstance(id);
+  if (!row) {
+    return { kind: "not-found" };
+  }
+  const cached = core.instances.get(id);
+  if (row.chart_name !== definition.chartName || row.definition_id !== definition.definitionId || cached !== void 0 && cached.flow !== flow) {
+    return {
+      kind: "mismatch",
+      context: {
+        reason: "definition",
+        instanceId: id,
+        message: `Instance ${id} uses chart "${row.chart_name}" with definition ${row.definition_id}; this flow uses "${definition.chartName}" with definition ${definition.definitionId}`,
+        storedChartName: row.chart_name,
+        storedDefinitionId: row.definition_id,
+        currentDefinitionId: definition.definitionId
+      }
+    };
+  }
+  const unresolved = row.current_execution_id === null ? void 0 : core.store.getExecution(row.current_execution_id);
+  if (cached === void 0 && unresolved !== void 0 && unresolved.handler_revision !== definition.handlerRevision) {
+    return {
+      kind: "mismatch",
+      context: {
+        reason: "handler-revision",
+        instanceId: id,
+        message: `Instance ${id} has unresolved work from handler revision ${unresolved.handler_revision}; this build uses ${definition.handlerRevision}`,
+        storedHandlerRevision: unresolved.handler_revision,
+        currentHandlerRevision: definition.handlerRevision
+      }
+    };
+  }
+  if (cached) {
+    if (cached.stalled) {
+      core.startRecovery(cached);
+    }
+    return { kind: "opened", instance: cached };
+  }
+  const instance = new InstanceCore(id, flow);
+  core.instances.set(id, instance);
+  core.startRecovery(instance);
+  return { kind: "opened", instance };
+}
+function createInstanceApi(core, instance, dispatchFailure, flowFailure) {
+  const { definition } = instance.flow;
+  const api = {
+    instanceId: instance.id,
+    getSnapshot: () => core.snapshot(instance),
+    subscribe(listener) {
+      const wrapped = (snapshot) => listener(snapshot);
+      instance.listeners.add(wrapped);
+      return () => {
+        instance.listeners.delete(wrapped);
+      };
+    },
+    history: (query) => core.history(instance.id, query),
+    when(from) {
+      const hasOutgoing = [...definition.transitionsByName.values()].some(
+        (transition) => transition.from.name === from
+      );
+      if (!hasOutgoing) {
+        throw new DurableInputError(
+          `State ${JSON.stringify(from)} has no outgoing transitions in flow "${definition.chartName}"`
+        );
+      }
+      return {
+        async dispatch(input) {
+          const onFailure = dispatchFailure();
+          if (!onFailure)
+            throw new DurableInputError(
+              "Configure flow.handleDispatch before direct dispatch, or use exhaustive handle callbacks"
+            );
+          const handlers = Object.fromEntries(
+            DISPATCH_OUTCOMES.map((outcome) => [
+              outcome,
+              (context) => ({ outcome, context })
+            ])
+          );
+          let result;
+          try {
+            result = await dispatch(
+              core,
+              instance,
+              from,
+              handlers,
+              input
+            );
+          } catch (error) {
+            if (flowFailure)
+              return rejectFlowFailure(
+                flowFailure,
+                new DurableOperationError("dispatch", error)
+              );
+            throw error;
+          }
+          if (result.outcome === "applied") return result.context;
+          await onFailure(
+            new DurableDispatchError(
+              result.outcome,
+              instance.id,
+              result.context
+            )
+          );
+          throw new DurableInputError(
+            "The dispatch failure handler must throw or transfer control"
+          );
+        },
+        handle(handlers) {
+          assertHandlers(handlers, DISPATCH_OUTCOMES);
+          return {
+            dispatch: (input) => dispatch(core, instance, from, handlers, input)
+          };
+        }
+      };
+    },
+    handleResolve(handlers) {
+      assertHandlers(handlers, ["accepted", "rejected"]);
+      return {
+        resolve: async (input) => {
+          const result = await resolve(core, instance, input);
+          return handlers[result.outcome](result);
+        }
+      };
+    },
+    handleRestart(handlers) {
+      assertHandlers(handlers, ["restarted", "not-restarted"]);
+      return {
+        restart: () => handlers[core.restartRecovery(instance) ? "restarted" : "not-restarted"]({})
+      };
+    },
+    resolve: (input) => resolve(core, instance, input),
+    restartRecovery: () => core.restartRecovery(instance)
+  };
+  return api;
+}
+var DISPATCH_OUTCOMES = [
+  "applied",
+  "blocked",
+  "invalid-payload",
+  "busy",
+  "recovery-pending",
+  "needs-attention",
+  "state-mismatch",
+  "request-conflict",
+  "terminated"
+];
+function assertHandlers(handlers, expected) {
+  const missing = expected.filter((key) => typeof handlers[key] !== "function");
+  const extra = Object.keys(handlers).filter((key) => !expected.includes(key));
+  if (missing.length > 0 || extra.length > 0) {
+    throw new DurableInputError(
+      `Outcome handlers must be exactly ${expected.join(", ")}` + (missing.length ? `; missing ${missing.join(", ")}` : "") + (extra.length ? `; unexpected ${extra.join(", ")}` : "")
+    );
+  }
+}
+function requireWork(core, id) {
+  const work = core.currentWork(id);
+  if (!work) {
+    throw new Error(`Instance ${id} has no unresolved work`);
+  }
+  return work;
+}
+function reasonOf(snapshot) {
+  return snapshot.status.kind === "needs-attention" || snapshot.status.kind === "terminated" ? snapshot.status.reason : "";
+}
+function recordedDispatch(core, instance, handlers, input, requestId2, inputJson) {
+  const recorded = core.store.findExecutionByRequest(instance.id, requestId2);
+  if (!recorded) return { found: false };
+  if (recorded.input_json !== inputJson) {
+    const original = parseJson(recorded.input_json);
+    return {
+      found: true,
+      value: handlers["request-conflict"]({ input, recorded: original })
+    };
+  }
+  if (instance.activeExecutionId === recorded.execution_id)
+    return {
+      found: true,
+      value: handlers.busy({ input, snapshot: core.snapshot(instance) })
+    };
+  return {
+    found: true,
+    value: selectRecorded(core, instance, handlers, input, recorded, true)
+  };
+}
+async function dispatch(core, instance, from, handlers, input) {
+  core.assertOpen();
+  const { definition } = instance.flow;
+  const requestId2 = requestId(input.requestId);
+  const transition = definition.transitionsByName.get(input.transition);
+  if (!transition || transition.from.name !== from) {
+    throw new DurableInputError(
+      `Transition ${JSON.stringify(input.transition)} does not leave "${from}" in flow "${definition.chartName}"`
+    );
+  }
+  const payload = input.payload === void 0 ? null : input.payload;
+  const problem = findNonJsonValue(payload);
+  if (problem) {
+    return handlers["invalid-payload"]({
+      input,
+      issues: [
+        { path: [], message: `Payload is not JSON-compatible: ${problem}` }
+      ]
+    });
+  }
+  const payloadJson = canonicalJson(payload);
+  input = Object.freeze({
+    requestId: requestId2,
+    transition: transition.name,
+    payload: parseJson(payloadJson)
+  });
+  const inputJson = canonicalJson({
+    fromState: from,
+    transition: transition.name,
+    payload: input.payload
+  });
+  const previous = recordedDispatch(
+    core,
+    instance,
+    handlers,
+    input,
+    requestId2,
+    inputJson
+  );
+  if (previous.found) return previous.value;
+  const parsed = await transition.payloadSchema.safeParseAsync(
+    parseJson(payloadJson)
+  );
+  core.assertOpen();
+  const concurrent = recordedDispatch(
+    core,
+    instance,
+    handlers,
+    input,
+    requestId2,
+    inputJson
+  );
+  if (concurrent.found) return concurrent.value;
+  if (!parsed.success) {
+    return handlers["invalid-payload"]({
+      input,
+      issues: parsed.error.issues.map(({ path, message }) => ({
+        path,
+        message
+      }))
+    });
+  }
+  const parsedProblem = findNonJsonValue(parsed.data);
+  if (parsedProblem || canonicalJson(parsed.data) !== payloadJson) {
+    return handlers["invalid-payload"]({
+      input,
+      issues: [
+        {
+          path: [],
+          message: "Payload schemas must preserve the JSON input; coercion, defaults, transforms and stripped fields are not supported"
+        }
+      ]
+    });
+  }
+  if (instance.activeExecutionId !== null) {
+    return handlers.busy({ input, snapshot: core.snapshot(instance) });
+  }
+  const row = core.requireInstanceRow(instance.id);
+  const snapshot = core.snapshot(instance);
+  switch (row.status) {
+    case "terminated":
+      return handlers.terminated({
+        input,
+        snapshot,
+        reason: row.status_reason ?? ""
+      });
+    case "needs-attention":
+      return handlers["needs-attention"]({
+        input,
+        snapshot,
+        work: requireWork(core, instance.id),
+        reason: row.status_reason ?? ""
+      });
+    case "recovering":
+      return handlers["recovery-pending"]({
+        input,
+        snapshot,
+        work: requireWork(core, instance.id)
+      });
+    case "running":
+      return handlers.busy({ input, snapshot });
+    case "ready":
+      break;
+  }
+  if (row.state !== from) {
+    return handlers["state-mismatch"]({
+      input,
+      expectedState: from,
+      actualState: row.state,
+      snapshot
+    });
+  }
+  const executionId = mintExecutionId();
+  core.store.transaction(() => {
+    core.store.insertExecution({
+      execution_id: executionId,
+      instance_id: instance.id,
+      kind: "dispatch",
+      request_id: requestId2,
+      input_json: inputJson,
+      from_state: from,
+      transition: transition.name,
+      to_state: transition.to.name,
+      step: "guard",
+      status: "running",
+      handler_revision: definition.handlerRevision
+    });
+    core.store.updateInstance(instance.id, {
+      status: "running",
+      current_execution_id: executionId
+    });
+    core.record(
+      instance.id,
+      "execution-started",
+      { transition: transition.name, from, to: transition.to.name },
+      { requestId: requestId2 }
+    );
+  });
+  core.notify(instance);
+  await core.track(
+    instance,
+    executionId,
+    () => core.advance(instance, executionId)
+  );
+  return selectRecorded(
+    core,
+    instance,
+    handlers,
+    input,
+    core.requireExecution(executionId),
+    false
+  );
+}
+function selectRecorded(core, instance, handlers, input, execution, duplicate) {
+  const snapshot = core.snapshot(instance);
+  switch (execution.status) {
+    case "applied":
+      return handlers.applied({ input, snapshot, duplicate });
+    case "blocked":
+      return handlers.blocked({ input, snapshot, duplicate });
+    case "terminated":
+      return handlers.terminated({
+        input,
+        snapshot,
+        reason: reasonOf(snapshot)
+      });
+    case "needs-attention": {
+      const work = core.currentWork(instance.id);
+      if (work) {
+        return handlers["needs-attention"]({
+          input,
+          snapshot,
+          work,
+          reason: reasonOf(snapshot)
+        });
+      }
+      return handlers.busy({ input, snapshot });
+    }
+    case "recovering":
+    case "running": {
+      const work = core.currentWork(instance.id);
+      if (work && snapshot.status.kind === "recovering") {
+        return handlers["recovery-pending"]({ input, snapshot, work });
+      }
+      return handlers.busy({ input, snapshot });
+    }
+  }
+}
+async function resolve(core, instance, untrustedInput) {
+  core.assertOpen();
+  const input = parseResolveInput(untrustedInput);
+  const row = core.requireInstanceRow(instance.id);
+  const execution = row.current_execution_id === null ? void 0 : core.store.getExecution(row.current_execution_id);
+  const operation = execution ? core.store.findUnresolvedOperation(execution.execution_id) : void 0;
+  if (instance.activeExecutionId !== null || row.status !== "needs-attention" || !execution || !operation || operation.status !== "needs-attention" || operation.operation_id !== input.operationId || operation.attempts !== input.expectedAttempts) {
+    return staleRejection(instance.id, input, operation);
+  }
+  const refs = {
+    requestId: execution.request_id,
+    operationId: operation.operation_id
+  };
+  const audit = (data) => core.record(
+    instance.id,
+    "manual-resolution",
+    { action: input.action, reason: input.reason, ...data },
+    refs
+  );
+  switch (input.action) {
+    case "terminate":
+      terminate(core, instance.id, execution, operation, input.reason, audit);
+      core.notify(instance);
+      return { outcome: "accepted", snapshot: core.snapshot(instance) };
+    case "retry": {
+      await core.manualRetry(instance, execution, operation, () => audit({}));
+      return { outcome: "accepted", snapshot: core.snapshot(instance) };
+    }
+    case "confirm-completed": {
+      if (input.callback !== operation.callback_kind) {
+        return {
+          outcome: "rejected",
+          reason: "callback-mismatch",
+          message: `Operation ${operation.operation_id} is ${operation.callback_kind}, not ${input.callback}`
+        };
+      }
+      const supplied = "result" in input ? input.result : void 0;
+      const validated = validateConfirmedResult(
+        instance.flow.definition,
+        operation.callback_kind,
+        supplied
+      );
+      if (!validated.ok) {
+        return {
+          outcome: "rejected",
+          reason: "invalid-result",
+          message: validated.message
+        };
+      }
+      core.store.transaction(() => {
+        core.checkpoint(instance, execution, operation, validated.result);
+        audit({ result: validated.result });
+      });
+      core.notify(instance);
+      await core.track(
+        instance,
+        execution.execution_id,
+        () => core.advance(instance, execution.execution_id)
+      );
+      return { outcome: "accepted", snapshot: core.snapshot(instance) };
+    }
+    default:
+      throw new DurableInputError(
+        `Unknown resolve action ${JSON.stringify(input.action)}`
+      );
+  }
+}
+function staleRejection(instanceId2, input, operation) {
+  const detail = operation && operation.operation_id === input.operationId ? ` (it has had ${operation.attempts} attempt(s); the action expected ${input.expectedAttempts})` : "";
+  return {
+    outcome: "rejected",
+    reason: "stale",
+    message: `Operation ${input.operationId} is not the work awaiting attention on instance ${instanceId2}${detail}`
+  };
+}
+function terminate(core, instanceId2, execution, operation, reason, audit) {
+  const refs = {
+    requestId: execution.request_id,
+    operationId: operation.operation_id
+  };
+  core.store.transaction(() => {
+    core.store.updateOperation(operation.operation_id, {
+      status: "terminated"
+    });
+    core.store.updateExecution(execution.execution_id, {
+      status: "terminated"
+    });
+    core.store.updateInstance(instanceId2, {
+      status: "terminated",
+      status_reason: reason
+    });
+    audit({});
+    core.record(instanceId2, "instance-terminated", { reason }, refs);
+  });
+}
+function terminateUnloadable(core, instanceId2, input) {
+  const row = core.requireInstanceRow(instanceId2);
+  const cached = core.instances.get(instanceId2);
+  const execution = row.current_execution_id === null ? void 0 : core.store.getExecution(row.current_execution_id);
+  const operation = execution ? core.store.findUnresolvedOperation(execution.execution_id) : void 0;
+  if (cached !== void 0 && cached.activeExecutionId !== null || row.status === "ready" || row.status === "terminated" || !execution || !operation || operation.operation_id !== input.operationId || operation.attempts !== input.expectedAttempts) {
+    return staleRejection(instanceId2, input, operation);
+  }
+  if (cached) {
+    core.clearTimer(cached);
+  }
+  terminate(
+    core,
+    instanceId2,
+    execution,
+    operation,
+    input.reason,
+    (data) => core.record(
+      instanceId2,
+      "manual-resolution",
+      { action: "terminate", reason: input.reason, unloadable: true, ...data },
+      { requestId: execution.request_id, operationId: operation.operation_id }
+    )
+  );
+  if (cached) {
+    core.notify(cached);
+  }
+  return { outcome: "accepted", snapshot: core.snapshotOf(instanceId2) };
+}
+function validateConfirmedResult(definition, kind, result) {
+  if ((kind === "on-enter" || kind === "on-exit" || kind === "on-transition") && result !== void 0 && result !== null) {
+    return { ok: false, message: `${kind} does not produce a result` };
+  }
+  return validateCallbackResult(definition, kind, result);
+}
+
+// src/durable/create-runtime.ts
+function createRuntime(options) {
+  const { shutdownTimeoutMs, ...runtimeOptions } = options;
+  const runtime = createDurableRuntime(runtimeOptions);
+  const close = runtime.close;
+  runtime.close = (options2) => close({ timeoutMs: options2?.timeoutMs ?? shutdownTimeoutMs });
+  return Object.assign(runtime, {
+    [Symbol.asyncDispose]: () => runtime.close()
+  });
+}
+
+// src/durable/scoped-runtime.ts
+async function withDurableRuntime(options, run) {
+  const runtime = createRuntime(options);
+  let work;
+  try {
+    work = { ok: true, value: await run(runtime) };
+  } catch (error) {
+    work = { ok: false, error };
+  }
+  try {
+    await runtime.close();
+  } catch (error) {
+    if (!work.ok)
+      throw new AggregateError(
+        [work.error, error],
+        "Application work and State Flow shutdown both failed"
+      );
+    throw error;
+  }
+  if (!work.ok) throw work.error;
+  return work.value;
+}
+
+// src/durable/recovery-target.ts
+function recoveryTarget(work) {
+  const target2 = {
+    operationId: work.operationId,
+    expectedAttempts: work.attempts
+  };
+  const base = {
+    retry: (reason) => ({ ...target2, action: "retry", reason }),
+    terminate: (reason) => ({ ...target2, action: "terminate", reason })
+  };
+  switch (work.callback.kind) {
+    case "guard":
+      return Object.freeze({
+        ...base,
+        callback: "guard",
+        confirm: (result, reason) => ({
+          ...target2,
+          action: "confirm-completed",
+          callback: "guard",
+          result,
+          reason
+        })
+      });
+    case "resolve-start-state":
+      return Object.freeze({
+        ...base,
+        callback: "resolve-start-state",
+        confirm: (result, reason) => ({
+          ...target2,
+          action: "confirm-completed",
+          callback: "resolve-start-state",
+          result,
+          reason
+        })
+      });
+    default: {
+      const callback = work.callback.kind;
+      return Object.freeze({
+        ...base,
+        callback,
+        confirm: (reason) => ({
+          ...target2,
+          action: "confirm-completed",
+          callback,
+          reason
+        })
+      });
+    }
+  }
+}
+export {
+  DurableDefinitionError,
+  DurableDefinitionMismatchError,
+  DurableDispatchError,
+  DurableInputError,
+  DurableOperationError,
+  DurableOwnershipError,
+  DurableRuntimeClosedError,
+  DurableRuntimeError,
+  DurableSchemaError,
+  DurableShutdownTimeoutError,
+  MAX_ATTEMPTS,
+  RECOVERY_DELAYS_MS,
+  createDurableRuntime,
+  createRuntime,
+  instanceId,
+  parseResolveInput,
+  recoveryTarget,
+  requestId,
+  resolveInputSchema,
+  withDurableRuntime
+};