@ngockhoale/ukit 3.0.8 → 3.0.10

package/src/core/agentRuntime/vmEngine.js

@@ -0,0 +1,621 @@
+/**
+ * agentRuntime/vmEngine.js — decision-first-runtime G4 (DR-06), VM vertical
+ * slice, omp-scoped, off-rollout (gated by host-side `decisionRuntime.vm`
+ * flag; this module reads no config itself).
+ *
+ * Executes a compiled ValidatedPlan (SPEC §4 frozen shape — literal nodes
+ * Map, entryNodes, topological order) purely against G1 durable primitives:
+ *
+ * - cursor + continuations are registered BEFORE the first node activation
+ *   (register-before-start is structural; no "start without register" path)
+ * - `deliver` consumes continuations idempotently via `consumptionKey` and
+ *   applies a deterministic per-node transition table — routine transitions
+ *   for known nodes need ZERO classifyFn calls (no external poll)
+ * - `resume` replays journals to rebuild state (journal is source of truth;
+ *   the plan state file is a rebuildable cache) and marks ambiguous crash
+ *   windows `recovery_required` — never auto-replays non-idempotent nodes
+ *
+ * Journal layout (per node, operationId = `<planInstanceId>:<nodeId>`):
+ *   seq1 'operation.transition' {to:'starting'}  — activation record
+ *   seq2 'operation.transition' {to:'running'}
+ *   seqN delivered SemanticEvent (producer seq, kept verbatim)
+ *   seqN+1..  'operation.transition' records {to:'completed'|...}
+ * Engine transition records use strictly increasing seq after the delivered
+ * event, so the journal stays gap-free and the activation record suppresses
+ * any second `startFn` side-effect on replay.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import {
+  CONTRACT_VERSION,
+  OPERATION_STATES,
+  isTerminal,
+  validateTransition,
+  validateSemanticEvent,
+  validateRetry,
+} from './contract.js';
+import {
+  registerContinuation,
+  consumeContinuation,
+  appendEvent,
+  readJournal,
+} from './eventStore.js';
+
+const STATE_SET = new Set(OPERATION_STATES);
+const PLANS_DIR = 'plans';
+const FENCING = { fencingEpoch: 0 };
+
+/** Outcomes that resolve a RUN/WAIT_EVENT node. Undeclared -> recovery_required. */
+const NODE_OUTCOMES = Object.freeze({
+  completed: 'completed',
+  failed: 'failed',
+  cancelled: 'cancelled',
+});
+
+export class VmEngineError extends Error {
+  constructor(code, message) {
+    super(message ?? code);
+    this.name = 'VmEngineError';
+    this.code = code;
+  }
+}
+
+async function pathExists(p) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function writeFileAtomic(target, data) {
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  const tmp = `${target}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+  const fh = await fs.open(tmp, 'w');
+  try {
+    await fh.writeFile(data, 'utf8');
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+  await fs.rename(tmp, target);
+}
+
+/**
+ * @param {{dir:string, now?:()=>Date, classifyFn?:Function, startFn?:Function, hooks?:object}} opts
+ */
+export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
+  if (typeof dir !== 'string' || dir === '') {
+    throw new VmEngineError('malformed_opts', 'dir required');
+  }
+  const clock = typeof now === 'function' ? now : () => new Date();
+  const fire = typeof startFn === 'function' ? startFn : async () => {};
+  const instances = new Map(); // planInstanceId -> instance
+  let closed = false;
+
+  const planPath = (pi) => path.join(dir, PLANS_DIR, `${pi}.json`);
+  const opId = (pi, nodeId) => `${pi}:${nodeId}`;
+  const obs = () => clock().toISOString();
+
+  function transitionRecord(nodeId, to, seq, extra = {}) {
+    return {
+      eventId: `vm-${nodeId}-${to}-${seq}-${Math.random().toString(36).slice(2, 10)}`,
+      operationId: opId(extra.pi ?? '', nodeId),
+      seq,
+      eventType: 'operation.transition',
+      observedAt: obs(),
+      producerVersion: 'ukit-vm',
+      contractVersion: CONTRACT_VERSION,
+      privacyClass: 'internal',
+      artifactRefs: [],
+      safePayload: { to, ...(extra.payload ?? {}) },
+    };
+  }
+
+  async function appendTransition(inst, nodeId, to, payload) {
+    const seq = ++inst.cursors[nodeId].lastSeq;
+    const event = transitionRecord(nodeId, to, seq, { pi: inst.planInstanceId, payload });
+    await appendEvent(dir, event, { hooks: { afterAppend: hooks?.afterEventAppend } });
+    return event;
+  }
+
+  function setNodeState(inst, nodeId, next) {
+    const prev = inst.nodes[nodeId].state;
+    if (prev === next) return;
+    const check = validateTransition(prev, next, FENCING);
+    if (!check.ok) {
+      throw new VmEngineError(check.code, `${nodeId}: ${prev} -> ${next} rejected (${check.code})`);
+    }
+    inst.nodes[nodeId].state = next;
+  }
+
+  async function moveNode(inst, nodeId, to, payload) {
+    setNodeState(inst, nodeId, to);
+    await appendTransition(inst, nodeId, to, payload);
+  }
+
+  function planStatus(inst) {
+    const states = Object.values(inst.nodes).map((n) => n.state);
+    if (states.some((s) => s === 'recovery_required')) return 'recovery_required';
+    if (!states.every((s) => isTerminal(s))) {
+      return states.some((s) => s === 'failed') ? 'failed' : 'running';
+    }
+    if (states.some((s) => s === 'failed')) return 'failed';
+    if (states.some((s) => s === 'cancelled')) return 'cancelled';
+    return 'completed';
+  }
+
+  async function persist(inst) {
+    const nodes = {};
+    for (const [id, n] of Object.entries(inst.nodes)) {
+      nodes[id] = { state: n.state, attempt: n.attempt, lastEventSeq: n.lastEventSeq };
+    }
+    const cursor = {};
+    for (const [id, c] of Object.entries(inst.cursors)) cursor[id] = c.lastSeq;
+    // compiled nodes are persisted so a fresh engine (post-crash process)
+    // can rehydrate the instance from disk and replay journals — the plan
+    // file is still a cache: journal replay remains authoritative.
+    const payload = {
+      planInstanceId: inst.planInstanceId,
+      planVersion: inst.planVersion,
+      status: planStatus(inst),
+      nodes,
+      cursor,
+      recoveryReason: inst.recoveryReason ?? null,
+      plan: { nodes: Object.fromEntries(inst.nodeMap), entryNodes: inst.entryNodes },
+      contractVersion: CONTRACT_VERSION,
+    };
+    await hooks?.beforePlanWrite?.(inst.planInstanceId);
+    await writeFileAtomic(planPath(inst.planInstanceId), `${JSON.stringify(payload)}\n`);
+  }
+
+  function nodeMap(plan) {
+    if (plan?.nodes instanceof Map) return plan.nodes;
+    if (plan?.nodes && typeof plan.nodes === 'object') return new Map(Object.entries(plan.nodes));
+    return new Map();
+  }
+
+  function depsSatisfied(inst, node) {
+    return (node.deps ?? []).every((d) => inst.nodes[d]?.state === 'completed');
+  }
+
+  async function markRecoveryRequired(inst, nodeId, reason) {
+    if (nodeId != null && inst.nodes[nodeId] && !isTerminal(inst.nodes[nodeId].state)) {
+      await moveNode(inst, nodeId, 'recovery_required', { reason });
+    }
+    inst.recoveryReason = reason;
+    inst.forcedStatus = 'recovery_required';
+    // fail closed: dependents never start
+    for (const [id, node] of inst.nodeMap) {
+      if (id !== nodeId && inst.nodes[id].state === 'queued'
+        && (node.deps ?? []).includes(nodeId)) {
+        inst.nodes[id].state = 'cancelled';
+      }
+    }
+  }
+
+  async function cancelDependents(inst, nodeId) {
+    for (const [id, node] of inst.nodeMap) {
+      if (inst.nodes[id].state === 'queued' && (node.deps ?? []).includes(nodeId)) {
+        inst.nodes[id].state = 'cancelled';
+        await cancelDependents(inst, id);
+      }
+    }
+  }
+
+  /** Activate a queued node whose deps are satisfied. */
+  async function activate(inst, nodeId, { suppressStart = false } = {}) {
+    const node = inst.nodeMap.get(nodeId);
+    if (!node || !STATE_SET.has(inst.nodes[nodeId].state)) return;
+    if (inst.nodes[nodeId].state !== 'queued') return;
+
+    // activation record lands in the journal BEFORE any side effect so that
+    // journal replay never fires startFn twice
+    inst.nodes[nodeId].attempt += 1;
+    setNodeState(inst, nodeId, 'starting');
+    await appendTransition(inst, nodeId, 'starting');
+
+    switch (node.op) {
+      case 'RUN': {
+        setNodeState(inst, nodeId, 'running');
+        await appendTransition(inst, nodeId, 'running');
+        if (!suppressStart) {
+          await fire(node.spec ?? {}, { planInstanceId: inst.planInstanceId, nodeId, node });
+          await hooks?.afterStart?.(nodeId);
+        }
+        break;
+      }
+      case 'WAIT_EVENT': {
+        setNodeState(inst, nodeId, 'running');
+        await appendTransition(inst, nodeId, 'running');
+        break;
+      }
+      case 'BRANCH': {
+        setNodeState(inst, nodeId, 'running');
+        await appendTransition(inst, nodeId, 'running');
+        break;
+      }
+      case 'COMPLETE': {
+        setNodeState(inst, nodeId, 'running');
+        await appendTransition(inst, nodeId, 'running');
+        await moveNode(inst, nodeId, 'completed');
+        await activateDependents(inst, nodeId);
+        break;
+      }
+      case 'ESCALATE': {
+        setNodeState(inst, nodeId, 'running');
+        await appendTransition(inst, nodeId, 'running');
+        await moveNode(inst, nodeId, 'completed', { escalated: true });
+        inst.recoveryReason = 'escalated';
+        inst.forcedStatus = 'recovery_required';
+        break;
+      }
+      default:
+        throw new VmEngineError('unknown_opcode', `${nodeId}: ${node.op}`);
+    }
+  }
+
+  async function activateDependents(inst, nodeId, { suppressStart = false } = {}) {
+    for (const [id, node] of inst.nodeMap) {
+      if (inst.nodes[id].state === 'queued' && depsSatisfied(inst, inst.nodeMap.get(id))) {
+        await activate(inst, id, { suppressStart });
+      }
+    }
+  }
+
+  function findWaiting(inst, event) {
+    const nodeId = event.operationId.slice(inst.planInstanceId.length + 1);
+    const node = inst.nodeMap.get(nodeId);
+    if (!node) return { nodeId, node: null, matched: false };
+    const sel = node.selector;
+    const matched = inst.nodes[nodeId]?.state === 'running'
+      && sel && sel.eventType === event.eventType
+      && (!sel.fields || Object.entries(sel.fields).every(([k, v]) => event.safePayload?.[k] === v));
+    return { nodeId, node, matched };
+  }
+
+  /** Apply the deterministic per-node transition table for a consumed event. */
+  async function applyOutcome(inst, nodeId, node, outcome, event, { suppressStart = false } = {}) {
+    const rec = inst.nodes[nodeId];
+    rec.lastEventSeq = event.seq;
+
+    if (node.op === 'BRANCH') {
+      const field = node.selector?.field ?? 'branch';
+      const value = event.safePayload?.[field];
+      const target = node.branches?.[value];
+      if (target == null || !inst.nodeMap.has(target)) {
+        await markRecoveryRequired(inst, nodeId, `unknown_branch:${String(value)}`);
+        return { node: nodeId, to: 'recovery_required' };
+      }
+      await moveNode(inst, nodeId, 'completed', { branch: value, target });
+      for (const other of Object.values(node.branches ?? {})) {
+        if (other !== target && inst.nodes[other]?.state === 'queued') {
+          inst.nodes[other].state = 'cancelled';
+          await cancelDependents(inst, other);
+        }
+      }
+      await activate(inst, target, { suppressStart });
+      return { node: nodeId, to: 'completed', branch: value };
+    }
+
+    // RUN / WAIT_EVENT
+    const to = NODE_OUTCOMES[outcome];
+    if (to == null) {
+      await markRecoveryRequired(inst, nodeId, `undeclared_outcome:${String(outcome)}`);
+      return { node: nodeId, to: 'recovery_required' };
+    }
+    if (to === 'cancelled') {
+      // node can't self-transition to cancelled from running per G1 table;
+      // route through cancel_pending
+      setNodeState(inst, nodeId, 'cancel_pending');
+      await appendTransition(inst, nodeId, 'cancel_pending');
+      await moveNode(inst, nodeId, 'cancelled');
+      await cancelDependents(inst, nodeId);
+      return { node: nodeId, to: 'cancelled' };
+    }
+    if (to === 'completed') {
+      await moveNode(inst, nodeId, 'completed');
+      await activateDependents(inst, nodeId, { suppressStart });
+    } else {
+      // 'failed': bounded auto-retry only for AUTO_RETRYABLE classes per
+      // validateRetry — the retry edge is running->retry_pending->running,
+      // so it must be attempted BEFORE the terminal 'failed' transition
+      const cls = node.retry?.sideEffectClass ?? 'write';
+      const policy = { maxAttempts: node.retry?.maxAttempts ?? 1 };
+      const retry = validateRetry(cls, rec.attempt + 1, policy);
+      if (retry.ok) {
+        setNodeState(inst, nodeId, 'retry_pending');
+        await appendTransition(inst, nodeId, 'retry_pending');
+        setNodeState(inst, nodeId, 'running');
+        await appendTransition(inst, nodeId, 'running');
+        rec.attempt += 1;
+        if (!suppressStart) await fire(node.spec ?? {}, { planInstanceId: inst.planInstanceId, nodeId, node });
+        return { node: nodeId, to: 'running' };
+      }
+      await moveNode(inst, nodeId, 'failed', { reason: retry.code });
+      inst.recoveryReason = inst.recoveryReason ?? `node_failed:${nodeId}:${retry.code}`;
+    }
+    return { node: nodeId, to };
+  }
+
+  async function escalateUnclassified(inst, event) {
+    inst.recoveryReason = `unclassifiable:${event.eventId}`;
+    inst.forcedStatus = 'recovery_required';
+    // terminal-record in the plan's own operation journal space: mark every
+    // still-waiting node recovery_required so resume folds identically
+    for (const [id] of inst.nodeMap) {
+      if (!isTerminal(inst.nodes[id].state) && inst.nodes[id].state !== 'queued') {
+        await moveNode(inst, id, 'recovery_required', { reason: 'unclassifiable_event' });
+        break;
+      }
+    }
+    await persist(inst);
+    return { consumed: false, code: 'escalated' };
+  }
+
+  // ----------------------------------------------------------------- API
+
+  async function start(plan, opts = {}) {
+    if (closed) throw new VmEngineError('engine_closed', 'close() called');
+    const nodes = nodeMap(plan);
+    if (nodes.size === 0 || !Array.isArray(plan?.entryNodes) || plan.entryNodes.length === 0) {
+      return { unsupported: true, code: 'malformed_plan' };
+    }
+
+    const planInstanceId = `pi-${clock().getTime().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    const inst = {
+      planInstanceId,
+      planVersion: plan.planVersion,
+      nodeMap: nodes,
+      entryNodes: plan.entryNodes,
+      nodes: {},
+      cursors: {},
+      continuations: {},
+      recoveryReason: null,
+      forcedStatus: null,
+    };
+    for (const [id] of nodes) {
+      inst.nodes[id] = { state: 'queued', attempt: 0, lastEventSeq: 0 };
+      inst.cursors[id] = { lastSeq: 0, seenEventIds: new Set() };
+    }
+    instances.set(planInstanceId, inst);
+
+    // 1) cursor + continuations registered BEFORE any node activation
+    for (const [id, node] of nodes) {
+      if (node.selector) {
+        const rec = await registerContinuation(dir, {
+          continuationId: `cont-${planInstanceId}-${id}`,
+          planVersion: plan.planVersion,
+          nodeId: id,
+          operationId: opId(planInstanceId, id),
+          afterSeq: 0,
+          selector: node.selector,
+          consumptionKey: `${planInstanceId}:${id}`,
+        });
+        inst.continuations[id] = rec.continuationId;
+      }
+    }
+    await persist(inst);
+
+    // 2) activate entry nodes (first startFn call happens only now)
+    for (const id of plan.entryNodes) {
+      await activate(inst, id);
+    }
+    await persist(inst);
+    return { planInstanceId };
+  }
+
+  /**
+   * Rehydrate an instance from the persisted plan file after the owning
+   * process dropped (real crash). The file seeds nodeMap/continuations/
+   * bookkeeping only — journal replay in `resume` stays authoritative.
+   */
+  async function ensureInst(planInstanceId) {
+    let inst = instances.get(planInstanceId);
+    if (inst) return inst;
+    const file = planPath(planInstanceId);
+    if (!(await pathExists(file))) return null;
+    let raw;
+    try {
+      raw = JSON.parse(await fs.readFile(file, 'utf8'));
+    } catch {
+      // corrupt plan file — rehydration impossible; deliver degrades to
+      // 'unroutable' and resume/state surface 'unknown_plan'
+      return null;
+    }
+    const nodeMap = new Map(Object.entries(raw.plan?.nodes ?? {}));
+    if (nodeMap.size === 0) return null;
+    inst = {
+      planInstanceId,
+      planVersion: raw.planVersion,
+      nodeMap,
+      entryNodes: raw.plan?.entryNodes ?? [],
+      nodes: {},
+      cursors: {},
+      continuations: {},
+      recoveryReason: raw.recoveryReason ?? null,
+      forcedStatus: null,
+    };
+    for (const [id] of nodeMap) {
+      const seed = raw.nodes?.[id] ?? {};
+      inst.nodes[id] = {
+        state: seed.state ?? 'queued',
+        attempt: seed.attempt ?? 0,
+        lastEventSeq: seed.lastEventSeq ?? 0,
+      };
+      inst.cursors[id] = { lastSeq: 0, seenEventIds: new Set() };
+    }
+    // continuation registration survived the crash on disk — recover the ids
+    try {
+      const lines = (await fs.readFile(path.join(dir, 'continuations.jsonl'), 'utf8'))
+        .split('\n').filter(Boolean);
+      for (const line of lines) {
+        let c;
+        // one torn line must not drop every recovered continuation
+        try { c = JSON.parse(line); } catch { continue; }
+        const nid = c.operationId?.startsWith(`${planInstanceId}:`)
+          ? c.operationId.slice(planInstanceId.length + 1) : null;
+        if (nid && inst.nodeMap.has(nid)) inst.continuations[nid] = c.continuationId;
+      }
+    } catch { /* no continuations file — nothing registered yet */ }
+    instances.set(planInstanceId, inst);
+    return inst;
+  }
+
+  async function deliver(event) {
+    if (closed) throw new VmEngineError('engine_closed', 'close() called');
+    const shape = validateSemanticEvent(event);
+    if (!shape.ok) return { consumed: false, code: shape.code };
+
+    const sep = event.operationId.indexOf(':');
+    const pi = sep > 0 ? event.operationId.slice(0, sep) : null;
+    const inst = pi ? await ensureInst(pi) : null;
+    if (!inst) return { consumed: false, code: 'unroutable' };
+    const { nodeId, node, matched } = findWaiting(inst, event);
+    const cursor = inst.cursors[nodeId] ?? { lastSeq: 0, seenEventIds: new Set() };
+
+    // ordering: known eventId -> duplicate; seq <= cursor -> out_of_order;
+    // anything else is checked for causality vs the journal on append
+    if (cursor.seenEventIds.has(event.eventId)) {
+      return { consumed: false, code: 'duplicate' };
+    }
+    if (event.seq <= cursor.lastSeq) {
+      return { consumed: false, code: 'out_of_order' };
+    }
+
+    // classify only when the IR itself cannot route the event (G4-FR05)
+    let outcome = event.safePayload?.outcome;
+    let targetMatched = matched;
+    if (!targetMatched) {
+      if (typeof classifyFn !== 'function') {
+        return escalateUnclassified(inst, event);
+      }
+      const verdict = await classifyFn(event, { planInstanceId: pi, nodeId, node });
+      if (verdict?.action === 'escalate' || verdict == null) {
+        return escalateUnclassified(inst, event);
+      }
+      if (verdict?.action === 'route' && typeof verdict.outcome === 'string') {
+        outcome = verdict.outcome;
+        targetMatched = node != null && inst.nodes[nodeId]?.state === 'running';
+      }
+    }
+    if (!targetMatched) return escalateUnclassified(inst, event);
+
+    // journal the delivered event BEFORE consumption record: a crash between
+    // the two leaves a journal event replay will re-apply idempotently;
+    // a second delivery of the same eventId is still a consume no-op
+    try {
+      await appendEvent(dir, event, { hooks: { afterAppend: hooks?.afterEventAppend } });
+    } catch (err) {
+      if (err?.code === 'out_of_order') return { consumed: false, code: 'out_of_order' };
+      throw err;
+    }
+    cursor.lastSeq = event.seq;
+    cursor.seenEventIds.add(event.eventId);
+
+    const cont = await consumeContinuation(dir, inst.continuations[nodeId], event);
+    if (!cont.consumed && cont.duplicate) {
+      return { consumed: false, code: 'duplicate' };
+    }
+
+    const transitions = [await applyOutcome(inst, nodeId, node, outcome, event)];
+    await persist(inst);
+    return { consumed: true, transitions };
+  }
+
+  /**
+   * Rebuild instance state by replaying journals (journal is truth). Already-
+   * journaled activations suppress startFn; non-idempotent nodes caught in a
+   * crash window resolve to recovery_required — never auto-replayed.
+   */
+  async function resume(planInstanceId) {
+    const inst = await ensureInst(planInstanceId);
+    if (!inst) throw new VmEngineError('unknown_plan', planInstanceId);
+    const report = { planInstanceId, replayedEvents: 0, recovered: [], recoveryRequired: [] };
+
+    for (const [nodeId, node] of inst.nodeMap) {
+      const cursor = inst.cursors[nodeId];
+      let derived = null;
+      let delivered = [];
+      for await (const ev of readJournal(dir, opId(planInstanceId, nodeId))) {
+        report.replayedEvents += 1;
+        cursor.lastSeq = ev.seq;
+        cursor.seenEventIds.add(ev.eventId);
+        if (ev.eventType === 'operation.transition' && ev.safePayload?.to) {
+          derived = ev.safePayload.to;
+        } else {
+          delivered.push(ev);
+        }
+      }
+      if (derived != null) inst.nodes[nodeId].state = derived;
+
+      const state = inst.nodes[nodeId].state;
+      if (isTerminal(state)) continue;
+
+      // crash window: running/starting node with non-idempotent side effects
+      // cannot prove whether its side effect landed
+      const cls = node.retry?.sideEffectClass ?? 'write';
+      const retryable = validateRetry(cls, 2, { maxAttempts: node.retry?.maxAttempts ?? 1 }).ok;
+      if (!retryable && (state === 'starting' || state === 'running') && delivered.length === 0 && node.op === 'RUN') {
+        // only ambiguous if its activation record exists but no outcome yet —
+        // that is exactly "side effect may have fired"
+        await markRecoveryRequired(inst, nodeId, `crash_window:${cls}`);
+        report.recoveryRequired.push(nodeId);
+        continue;
+      }
+      // re-apply pending delivered events not yet folded into a transition
+      for (const ev of delivered) {
+        const outcome = ev.safePayload?.outcome;
+        await applyOutcome(inst, nodeId, node, outcome, ev, { suppressStart: true });
+        report.recovered.push(nodeId);
+      }
+      if (inst.nodes[nodeId].state === 'queued' && depsSatisfied(inst, node)) {
+        await activate(inst, nodeId, { suppressStart: true });
+      }
+    }
+    await persist(inst);
+    report.status = inst.forcedStatus ?? planStatus(inst);
+    return report;
+  }
+
+  async function state(planInstanceId) {
+    const inst = instances.get(planInstanceId);
+    if (!inst) {
+      const file = planPath(planInstanceId);
+      if (await pathExists(file)) {
+        try {
+          const raw = JSON.parse(await fs.readFile(file, 'utf8'));
+          if (raw !== null && typeof raw === 'object' && !Array.isArray(raw)) return raw;
+        } catch { /* corrupt plan file — same surface as missing file */ }
+      }
+      throw new VmEngineError('unknown_plan', planInstanceId);
+    }
+    const nodes = {};
+    for (const [id, n] of Object.entries(inst.nodes)) {
+      nodes[id] = { state: n.state, attempt: n.attempt, lastEventSeq: n.lastEventSeq };
+    }
+    const cursor = {};
+    for (const [id, c] of Object.entries(inst.cursors)) cursor[id] = c.lastSeq;
+    const status = inst.forcedStatus ?? planStatus(inst);
+    return {
+      planInstanceId,
+      planVersion: inst.planVersion,
+      status,
+      nodes,
+      cursor,
+      ...(inst.recoveryReason ? { recoveryReason: inst.recoveryReason } : {}),
+    };
+  }
+
+  async function close() {
+    closed = true;
+    for (const inst of instances.values()) {
+      await persist(inst);
+    }
+  }
+
+  return { start, deliver, resume, state, close };
+}

package/src/core/codeintel/analogy.js

@@ -99,10 +99,11 @@ async function loadProcedureCandidates(projectRoot, config) {
       return { records: null, why: 'memory-unavailable' };
     }
     const loaded = await loader.loadV2Records(projectRoot, { type: 'procedure' });
-    if (!Array.isArray(loaded) || loaded.length === 0) {
+    const loadedRecords = Array.isArray(loaded?.records) ? loaded.records : [];
+    if (loaded?.state !== 'ok' || loadedRecords.length === 0) {
       return { records: [], why: 'memory-unavailable' };
     }
-    return { records: loaded.filter((r) => records.isRecordUsable(r)), why: null };
+    return { records: loadedRecords.filter((r) => records.isRecordUsable(r)), why: null };
   } catch {
     return { records: null, why: 'memory-unavailable' };
   }

package/src/core/experiments/dynamicWorkflow.js

@@ -412,7 +412,14 @@ export function runProgram({
     while (!done && blockedReason === null) {
       attempt += 1;
       const strategy = strategies.length > 0 ? strategies[attempt - 1] : undefined;
-      const result = runner({ task, attempt, strategy, state }) ?? {};
+      // A throwing runner degrades to a failure result — it must never escape
+      // runProgram as an exception (degrade contract, SPEC §FR-008).
+      let result;
+      try {
+        result = runner({ task, attempt, strategy, state }) ?? {};
+      } catch (err) {
+        result = { status: 'runner-threw', failure: String(err?.message ?? err) };
+      }
       state.budget.consumed += 1;
       if (completion(result)) {
         done = true;
@@ -482,7 +489,15 @@ export function runProgram({
 
   state.workflow.phase = 'blocked';
   if (typeof fallback === 'function') {
-    const fallbackResult = fallback({ state, blockers }) ?? {};
+    // A throwing fallback is still a degrade contract — record the throw as a
+    // blocker and report 'blocked', never let the exception escape (FR-008).
+    let fallbackResult = null;
+    try {
+      fallbackResult = fallback({ state, blockers }) ?? {};
+    } catch {
+      blockers.push({ taskId: null, reason: 'fallback-threw' });
+      return { status: 'blocked', ...result, blockers };
+    }
     if (fallbackResult.status === 'ok') {
       return { status: 'degraded', fallback: fallbackResult, ...result };
     }