@nanobpm/workflow 0.1.0

package/dist/worker.d.ts

@@ -0,0 +1,51 @@
+import { WorkflowClient } from "./client.js";
+import type { Workflow } from "./types.js";
+/** Fired after a job completes; purely observational. */
+export interface ActivityEvent {
+    workflowId: string;
+    type: string;
+    jobKey: string;
+    elementId: string;
+    /** For an imperative orchestrator turn: the journalled step key, or "__done". */
+    step?: string;
+}
+export interface WorkerOptions {
+    /** Provide a baseUrl (a client is created) or an existing client. */
+    baseUrl?: string;
+    client?: WorkflowClient;
+    workflows: Workflow[];
+    /** Worker name reported to the gateway. Default "nanobpm-workflow". */
+    name?: string;
+    /** Long-poll timeout per activation, ms. Also bounds stop() latency. Default 10000. */
+    pollTimeoutMs?: number;
+    /** Job lock timeout, ms. Default 30000. */
+    jobTimeoutMs?: number;
+    /** Backoff after a transport error, ms. Default 500. */
+    backoffMs?: number;
+    onActivity?: (e: ActivityEvent) => void | Promise<void>;
+    onError?: (err: Error, context: {
+        type: string;
+    }) => void;
+}
+export declare class Worker {
+    private readonly client;
+    private readonly name;
+    private readonly pollTimeoutMs;
+    private readonly jobTimeoutMs;
+    private readonly backoffMs;
+    private readonly onActivity?;
+    private readonly onError?;
+    /** job type → { workflowId, handle } */
+    private readonly routes;
+    private running;
+    private loops;
+    constructor(opts: WorkerOptions);
+    private register;
+    /** The derived job types this worker serves. */
+    get servedTypes(): string[];
+    /** Begin polling. Resolves once the loops are running (they run until stop()). */
+    start(): void;
+    /** Stop polling and wait for in-flight loops to unwind (≤ pollTimeoutMs). */
+    stop(): Promise<void>;
+    private pollLoop;
+}

package/dist/worker.js

@@ -0,0 +1,135 @@
+// The Worker runtime — hosts one or more workflows against a gateway and drives
+// them: long-polls each derived job type, dispatches jobs to handlers, completes
+// them. It generalises the two surfaces:
+//
+//   - a declarative flow contributes one job type per `run` step, dispatched to
+//     the user handler;
+//   - an imperative workflow contributes its single orchestrator job type,
+//     dispatched to the replay engine (which advances the journal one step).
+//
+// It is resilient to the gateway disappearing (each poll loop backs off and
+// reconnects on its own), so it survives an engine crash/restart — the property
+// the ADR 0044 spike proved.
+import { WorkflowClient } from "./client.js";
+import { replayOnce } from "./imperative.js";
+import { jobType } from "./xml.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class Worker {
+    client;
+    name;
+    pollTimeoutMs;
+    jobTimeoutMs;
+    backoffMs;
+    onActivity;
+    onError;
+    /** job type → { workflowId, handle } */
+    routes = new Map();
+    running = false;
+    loops = [];
+    constructor(opts) {
+        this.client = opts.client ?? new WorkflowClient({ baseUrl: requireBaseUrl(opts) });
+        this.name = opts.name ?? "nanobpm-workflow";
+        this.pollTimeoutMs = opts.pollTimeoutMs ?? 10000;
+        this.jobTimeoutMs = opts.jobTimeoutMs ?? 30000;
+        this.backoffMs = opts.backoffMs ?? 500;
+        this.onActivity = opts.onActivity;
+        this.onError = opts.onError;
+        for (const wf of opts.workflows)
+            this.register(wf);
+    }
+    register(wf) {
+        if (wf.kind === "imperative") {
+            this.routes.set(wf.orchestrateType, {
+                workflowId: wf.id,
+                handle: async (job) => {
+                    const input = job.variables.input ?? {};
+                    const journal = job.variables.journal ?? {};
+                    const step = await replayOnce(wf, input, journal);
+                    if (step.done)
+                        return { variables: { wfDone: true }, step: "__done" };
+                    const next = { ...journal, [step.frontier.key]: step.frontier.result };
+                    return { variables: { journal: next, wfDone: false }, step: step.frontier.key };
+                },
+            });
+        }
+        else {
+            for (const s of wf.steps) {
+                if (s.kind !== "run")
+                    continue;
+                const handler = wf.handlers[s.name];
+                this.routes.set(jobType(wf.id, s.name), {
+                    workflowId: wf.id,
+                    handle: async (job) => ({ variables: ((await handler(job)) ?? {}) }),
+                });
+            }
+        }
+    }
+    /** The derived job types this worker serves. */
+    get servedTypes() {
+        return [...this.routes.keys()];
+    }
+    /** Begin polling. Resolves once the loops are running (they run until stop()). */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.loops = [...this.routes.entries()].map(([type, route]) => this.pollLoop(type, route));
+    }
+    /** Stop polling and wait for in-flight loops to unwind (≤ pollTimeoutMs). */
+    async stop() {
+        this.running = false;
+        await Promise.all(this.loops);
+        this.loops = [];
+    }
+    async pollLoop(type, route) {
+        while (this.running) {
+            let jobs = [];
+            try {
+                jobs = await this.client.activateJobs(type, {
+                    worker: this.name,
+                    maxJobsToActivate: 1,
+                    timeout: this.jobTimeoutMs,
+                    requestTimeout: this.pollTimeoutMs,
+                });
+            }
+            catch (e) {
+                // Transport/gateway error (e.g. engine restarting): back off, reconnect.
+                this.onError?.(e, { type });
+                await sleep(this.backoffMs);
+                continue;
+            }
+            for (const job of jobs) {
+                if (!this.running)
+                    break;
+                try {
+                    const { variables, step } = await route.handle(job);
+                    await this.client.completeJob(job.jobKey, variables);
+                    await this.onActivity?.({
+                        workflowId: route.workflowId,
+                        type,
+                        jobKey: job.jobKey,
+                        elementId: job.elementId,
+                        step,
+                    });
+                }
+                catch (e) {
+                    // A handler or completion failed. Report; the engine will redeliver the
+                    // job after its lock times out (at-least-once → handlers must be
+                    // idempotent). Best-effort surface it as an incident-worthy failure.
+                    this.onError?.(e, { type });
+                    try {
+                        await this.client.failJob(job.jobKey, e.message, 0);
+                    }
+                    catch {
+                        /* engine may be down; the lock will expire and redeliver */
+                    }
+                }
+            }
+        }
+    }
+}
+function requireBaseUrl(opts) {
+    if (!opts.baseUrl)
+        throw new Error("Worker needs either options.client or options.baseUrl");
+    return opts.baseUrl;
+}

package/dist/xml.d.ts

@@ -0,0 +1,10 @@
+import type { Workflow } from "./types.js";
+export declare function escapeXml(s: string): string;
+/** Derived job type for a declarative `run` step / imperative orchestrator. */
+export declare const jobType: (workflowId: string, step: string) => string;
+/** Derived message name for a declarative `signal` step. */
+export declare const messageName: (workflowId: string, step: string) => string;
+/** The single orchestrator job type of an imperative workflow. */
+export declare const orchestrateType: (workflowId: string) => string;
+export declare function assertIdent(kind: string, value: string): void;
+export declare function assertWorkflowIds(wf: Workflow): void;

package/dist/xml.js

@@ -0,0 +1,28 @@
+// XML helpers + derived-name conventions shared by both model emitters.
+export function escapeXml(s) {
+    return String(s)
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/** Derived job type for a declarative `run` step / imperative orchestrator. */
+export const jobType = (workflowId, step) => `${workflowId}:${step}`;
+/** Derived message name for a declarative `signal` step. */
+export const messageName = (workflowId, step) => `${workflowId}:${step}`;
+/** The single orchestrator job type of an imperative workflow. */
+export const orchestrateType = (workflowId) => `${workflowId}:__orchestrate`;
+/** A BPMN identifier must be an NCName; validate derived ids fail fast. */
+const NCNAME = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
+export function assertIdent(kind, value) {
+    if (!NCNAME.test(value)) {
+        throw new Error(`${kind} "${value}" is not a valid BPMN identifier (expected an NCName)`);
+    }
+}
+export function assertWorkflowIds(wf) {
+    assertIdent("workflow id", wf.id);
+    if (wf.kind === "declarative") {
+        for (const step of wf.steps)
+            assertIdent("step name", step.name);
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@nanobpm/workflow",
+  "version": "0.1.0",
+  "description": "Code-first durable orchestration for nanobpmn (ADR 0044). Author durable workflows as ordinary async code — either an imperative function driven by engine replay (`defineWorkflow(id, async ctx => { await ctx.run(...) })`, the Temporal-style surface) or a declarative flow with human-in-the-loop signals (`defineFlow`) — and the SDK derives the executable BPMN model, the job types, and the message/correlation wiring, then hosts a generic worker. No diagram, no task-type wiring, no correlation plumbing authored by hand. Talks to a running nanobpmn gateway over the REST v2 API.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Magikcraft/nano-bpm",
+    "directory": "workflow"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./source": "./src/index.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && npm run test:ci",
+    "test:ci": "node --experimental-strip-types --test test/*.test.ts",
+    "test:integration": "node --experimental-strip-types --test test/integration.test.ts",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "^5.6.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/client.ts

@@ -0,0 +1,167 @@
+// A thin, dependency-free client for a running nanobpmn gateway (REST v2):
+// deploy a workflow's derived model, start instances, correlate signals, and the
+// low-level job activate/complete/fail used by the Worker runtime.
+
+import { declarativeToBpmn } from "./declarative.js";
+import { imperativeToBpmn } from "./imperative.js";
+import type { DeclarativeFlow, DeployResult, Job, JsonObject, StartResult, Workflow } from "./types.js";
+import { assertWorkflowIds, messageName } from "./xml.js";
+
+/** Render a workflow (either surface) to its executable BPMN model. */
+export function toBpmn(wf: Workflow): string {
+  assertWorkflowIds(wf);
+  return wf.kind === "imperative" ? imperativeToBpmn(wf) : declarativeToBpmn(wf);
+}
+
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface WorkflowClientOptions {
+  /** Base URL of the nanobpmn gateway, e.g. `http://localhost:8080`. */
+  baseUrl: string;
+  /** Injectable fetch (defaults to the global). Useful for tests/proxies. */
+  fetch?: FetchLike;
+}
+
+export interface ActivateOptions {
+  worker: string;
+  maxJobsToActivate?: number;
+  /** Job timeout in ms (how long the worker holds the job). Default 30000. */
+  timeout?: number;
+  /** Long-poll timeout in ms; `< 0` disables long-poll. Default 15000. */
+  requestTimeout?: number;
+}
+
+export class WorkflowError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+    readonly body?: string,
+  ) {
+    super(message);
+    this.name = "WorkflowError";
+  }
+}
+
+export class WorkflowClient {
+  private readonly baseUrl: string;
+  private readonly fetchImpl: FetchLike;
+
+  constructor(opts: WorkflowClientOptions) {
+    if (!opts?.baseUrl) throw new Error("WorkflowClient needs a baseUrl");
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    const f = opts.fetch ?? (globalThis.fetch as FetchLike | undefined);
+    if (!f) throw new Error("no fetch available; pass options.fetch (Node < 18)");
+    this.fetchImpl = f;
+  }
+
+  private async json<T>(path: string, init: RequestInit, what: string): Promise<T> {
+    const res = await this.send(path, init, what);
+    return (await res.json()) as T;
+  }
+
+  /** Perform a request, throwing WorkflowError on transport error or !ok, and
+   *  return the raw Response (for endpoints with an empty/no-content body). */
+  private async send(path: string, init: RequestInit, what: string): Promise<Response> {
+    let res: Response;
+    try {
+      res = await this.fetchImpl(`${this.baseUrl}${path}`, init);
+    } catch (e) {
+      throw new WorkflowError(`${what} transport error: ${(e as Error).message}`);
+    }
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new WorkflowError(`${what} failed: ${res.status}`, res.status, body);
+    }
+    return res;
+  }
+
+  /** Deploy a workflow's derived BPMN model. */
+  async deploy(wf: Workflow): Promise<DeployResult> {
+    const xml = toBpmn(wf);
+    const form = new FormData();
+    form.append("resources", new Blob([xml], { type: "text/xml" }), `${wf.id}.bpmn`);
+    return this.json<DeployResult>(`/v2/deployments`, { method: "POST", body: form }, "deploy");
+  }
+
+  /**
+   * Start a workflow instance. For imperative workflows the engine variables are
+   * seeded with `{ input, journal: {}, wfDone: false }` (the replay state); for
+   * declarative flows `input` becomes the instance variables directly.
+   */
+  async start(wf: Workflow, input: JsonObject = {}): Promise<StartResult> {
+    const variables: JsonObject =
+      wf.kind === "imperative" ? { input, journal: {}, wfDone: false } : input;
+    return this.json<StartResult>(
+      `/v2/process-instances`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ processDefinitionId: wf.id, variables }),
+      },
+      "start",
+    );
+  }
+
+  /** Correlate a signal to a parked declarative `signal` step. */
+  async signal(
+    flow: DeclarativeFlow,
+    signalName: string,
+    correlationKey: string,
+    variables: JsonObject = {},
+  ): Promise<JsonObject> {
+    return this.json<JsonObject>(
+      `/v2/messages/correlation`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ name: messageName(flow.id, signalName), correlationKey, variables }),
+      },
+      `signal "${signalName}"`,
+    );
+  }
+
+  /** Fetch an instance (used by demos/tests to observe completion). */
+  async getInstance(processInstanceKey: string): Promise<JsonObject | null> {
+    try {
+      const res = await this.fetchImpl(`${this.baseUrl}/v2/process-instances/${processInstanceKey}`);
+      if (!res.ok) return null;
+      return (await res.json()) as JsonObject;
+    } catch {
+      return null;
+    }
+  }
+
+  // --- low-level job protocol (used by the Worker runtime) -------------------
+
+  async activateJobs(type: string, opts: ActivateOptions): Promise<Job[]> {
+    const body = {
+      type,
+      worker: opts.worker,
+      maxJobsToActivate: opts.maxJobsToActivate ?? 1,
+      timeout: opts.timeout ?? 30000,
+      requestTimeout: opts.requestTimeout ?? 15000,
+    };
+    const res = await this.json<{ jobs?: Job[] }>(
+      `/v2/jobs/activation`,
+      { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) },
+      `activate ${type}`,
+    );
+    return res.jobs ?? [];
+  }
+
+  async completeJob(jobKey: string, variables: JsonObject = {}): Promise<void> {
+    await this.send(
+      `/v2/jobs/${jobKey}/completion`,
+      { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ variables }) },
+      "complete job",
+    );
+  }
+
+  async failJob(jobKey: string, errorMessage: string, retries = 0): Promise<void> {
+    await this.send(
+      `/v2/jobs/${jobKey}/failure`,
+      { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ errorMessage, retries }) },
+      "fail job",
+    );
+  }
+}

package/src/declarative.ts

@@ -0,0 +1,110 @@
+// Strategy A — the declarative surface: a step list compiled to a linear model.
+//
+//   const flow = defineFlow("pr-review", (w) => {
+//     w.run("fetchDiff",  async (job) => ({ diff: await gh.diff(job.variables.prId) }));
+//     w.run("autoReview", async (job) => ({ findings: await llm.review(job.variables.diff) }));
+//     w.signal("humanApproval", { correlationKey: "prId" });   // durable human wait
+//     w.run("merge",      async (job) => ({ merged: await gh.merge(job.variables.prId) }));
+//   });
+//
+// The façade derives the BPMN model, the job types (`<id>:<step>`), the message
+// name + `zeebe:subscription correlationKey`, and (via Worker) a generic worker.
+// This surface supports human-in-the-loop signals today.
+
+import type { DeclarativeFlow, DeclarativeStep, StepHandler } from "./types.js";
+import { assertIdent, escapeXml, jobType, messageName } from "./xml.js";
+
+export interface FlowBuilder {
+  /** A durable activity served by a worker (a BPMN service task). */
+  run(name: string, handler: StepHandler): FlowBuilder;
+  /**
+   * A durable wait for an external/human event, correlated on a process
+   * variable (a BPMN message intermediate catch event). Resume it with
+   * `WorkflowClient.signal(flow, name, correlationKeyValue, vars)`.
+   */
+  signal(name: string, opts: { correlationKey: string }): FlowBuilder;
+}
+
+/** Define a declarative flow. `build(w)` declares an ordered list of steps. */
+export function defineFlow(id: string, build: (w: FlowBuilder) => void): DeclarativeFlow {
+  assertIdent("workflow id", id);
+  const steps: DeclarativeStep[] = [];
+  const handlers: Record<string, StepHandler> = {};
+  const seen = new Set<string>();
+  const w: FlowBuilder = {
+    run(name, handler) {
+      assertIdent("step name", name);
+      if (seen.has(name)) throw new Error(`duplicate step name "${name}" in flow "${id}"`);
+      if (typeof handler !== "function") throw new Error(`run("${name}") needs a handler function`);
+      seen.add(name);
+      steps.push({ kind: "run", name });
+      handlers[name] = handler;
+      return w;
+    },
+    signal(name, opts) {
+      assertIdent("step name", name);
+      if (seen.has(name)) throw new Error(`duplicate step name "${name}" in flow "${id}"`);
+      if (!opts || !opts.correlationKey) throw new Error(`signal("${name}") needs { correlationKey }`);
+      assertIdent("correlationKey", opts.correlationKey);
+      seen.add(name);
+      steps.push({ kind: "signal", name, correlationKey: opts.correlationKey });
+      return w;
+    },
+  };
+  build(w);
+  if (steps.length === 0) throw new Error(`flow "${id}" declared no steps`);
+  return { kind: "declarative", id, steps, handlers };
+}
+
+/** Derive an executable BPMN model from a declarative flow. */
+export function declarativeToBpmn(flow: DeclarativeFlow): string {
+  const nodes: string[] = [];
+  const flows: string[] = [];
+  const messages: string[] = [];
+  const ids = ["Start", ...flow.steps.map((s) => s.name), "End"];
+
+  nodes.push(`    <bpmn:startEvent id="Start"><bpmn:outgoing>flow_0</bpmn:outgoing></bpmn:startEvent>`);
+  flow.steps.forEach((step, i) => {
+    const incoming = `flow_${i}`;
+    const outgoing = `flow_${i + 1}`;
+    if (step.kind === "run") {
+      nodes.push(
+        `    <bpmn:serviceTask id="${escapeXml(step.name)}" name="${escapeXml(step.name)}">\n` +
+          `      <bpmn:extensionElements><zeebe:taskDefinition type="${escapeXml(jobType(flow.id, step.name))}" /></bpmn:extensionElements>\n` +
+          `      <bpmn:incoming>${incoming}</bpmn:incoming><bpmn:outgoing>${outgoing}</bpmn:outgoing>\n` +
+          `    </bpmn:serviceTask>`,
+      );
+    } else {
+      const msgId = `Msg_${escapeXml(step.name)}`;
+      nodes.push(
+        `    <bpmn:intermediateCatchEvent id="${escapeXml(step.name)}" name="${escapeXml(step.name)}">\n` +
+          `      <bpmn:incoming>${incoming}</bpmn:incoming><bpmn:outgoing>${outgoing}</bpmn:outgoing>\n` +
+          `      <bpmn:messageEventDefinition messageRef="${msgId}" />\n` +
+          `    </bpmn:intermediateCatchEvent>`,
+      );
+      messages.push(
+        `  <bpmn:message id="${msgId}" name="${escapeXml(messageName(flow.id, step.name))}">\n` +
+          `    <bpmn:extensionElements><zeebe:subscription correlationKey="=${escapeXml(step.correlationKey)}" /></bpmn:extensionElements>\n` +
+          `  </bpmn:message>`,
+      );
+    }
+  });
+  nodes.push(`    <bpmn:endEvent id="End"><bpmn:incoming>flow_${flow.steps.length}</bpmn:incoming></bpmn:endEvent>`);
+  for (let i = 0; i < ids.length - 1; i++) {
+    flows.push(`    <bpmn:sequenceFlow id="flow_${i}" sourceRef="${ids[i]}" targetRef="${ids[i + 1]}" />`);
+  }
+
+  return (
+    `<?xml version="1.0" encoding="UTF-8"?>\n` +
+    `<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" id="Definitions_${escapeXml(flow.id)}" targetNamespace="http://bpmn.io/schema/bpmn">\n` +
+    `  <bpmn:process id="${escapeXml(flow.id)}" name="${escapeXml(flow.id)}" isExecutable="true">\n` +
+    nodes.join("\n") +
+    "\n" +
+    flows.join("\n") +
+    "\n" +
+    `  </bpmn:process>\n` +
+    messages.join("\n") +
+    (messages.length ? "\n" : "") +
+    `</bpmn:definitions>\n`
+  );
+}

package/src/imperative.ts

@@ -0,0 +1,105 @@
+// Strategy B — the imperative surface: a replayed orchestration function (the
+// Temporal-style code-first model).
+//
+//   const wf = defineWorkflow("pr-review", async (ctx) => {
+//     const diff   = await ctx.run("fetchDiff",  () => gh.diff(ctx.input.prId));
+//     const review = await ctx.run("autoReview", () => llm.review(diff));
+//     if (review.blocking) await ctx.run("requestChanges", () => gh.comment(review));
+//     await ctx.run("merge", () => gh.merge(ctx.input.prId));
+//   });
+//
+// Real control flow (`if`, locals, composition) — what the declarative surface
+// cannot express. The engine drives it by REPLAY: the derived model is a single
+// orchestrator service task in a loop; each turn the worker replays the function
+// from the top, feeding each `ctx.run` its recorded result from a durable
+// journal (an engine process variable). Recorded steps are replayed (no side
+// effect); only the frontier step executes. See ADR 0044.
+//
+// The orchestration body MUST be deterministic across replays (no wall-clock
+// branching, RNG, or I/O outside `ctx.run` handlers).
+
+import type { ImperativeWorkflow, Json, JsonObject, Orchestration, WorkflowContext } from "./types.js";
+import { assertIdent, escapeXml, orchestrateType } from "./xml.js";
+
+/** Define an imperative, replay-driven durable workflow. */
+export function defineWorkflow(id: string, orchestrate: Orchestration): ImperativeWorkflow {
+  assertIdent("workflow id", id);
+  if (typeof orchestrate !== "function") throw new Error("defineWorkflow needs an async orchestration function");
+  return { kind: "imperative", id, orchestrate, orchestrateType: orchestrateType(id) };
+}
+
+/** The looped-orchestrator model: start → orchestrate → gw → (done ? end : loop). */
+export function imperativeToBpmn(wf: ImperativeWorkflow): string {
+  return (
+    `<?xml version="1.0" encoding="UTF-8"?>\n` +
+    `<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" id="Definitions_${escapeXml(wf.id)}" targetNamespace="http://bpmn.io/schema/bpmn">\n` +
+    `  <bpmn:process id="${escapeXml(wf.id)}" name="${escapeXml(wf.id)}" isExecutable="true">\n` +
+    `    <bpmn:startEvent id="Start"><bpmn:outgoing>f_start</bpmn:outgoing></bpmn:startEvent>\n` +
+    `    <bpmn:serviceTask id="Orchestrate" name="orchestrate">\n` +
+    `      <bpmn:extensionElements><zeebe:taskDefinition type="${escapeXml(wf.orchestrateType)}" /></bpmn:extensionElements>\n` +
+    `      <bpmn:incoming>f_start</bpmn:incoming><bpmn:incoming>f_loop</bpmn:incoming><bpmn:outgoing>f_toGw</bpmn:outgoing>\n` +
+    `    </bpmn:serviceTask>\n` +
+    `    <bpmn:exclusiveGateway id="Gw" default="f_loop">\n` +
+    `      <bpmn:incoming>f_toGw</bpmn:incoming><bpmn:outgoing>f_done</bpmn:outgoing><bpmn:outgoing>f_loop</bpmn:outgoing>\n` +
+    `    </bpmn:exclusiveGateway>\n` +
+    `    <bpmn:endEvent id="End"><bpmn:incoming>f_done</bpmn:incoming></bpmn:endEvent>\n` +
+    `    <bpmn:sequenceFlow id="f_start" sourceRef="Start" targetRef="Orchestrate" />\n` +
+    `    <bpmn:sequenceFlow id="f_toGw" sourceRef="Orchestrate" targetRef="Gw" />\n` +
+    `    <bpmn:sequenceFlow id="f_done" sourceRef="Gw" targetRef="End">\n` +
+    `      <bpmn:conditionExpression>=wfDone</bpmn:conditionExpression>\n` +
+    `    </bpmn:sequenceFlow>\n` +
+    `    <bpmn:sequenceFlow id="f_loop" sourceRef="Gw" targetRef="Orchestrate" />\n` +
+    `  </bpmn:process>\n` +
+    `</bpmn:definitions>\n`
+  );
+}
+
+/** A journal of recorded step results, keyed by call-ordinal + name. */
+export type Journal = Record<string, Json>;
+
+const SUSPEND = Symbol("nanobpm.workflow.suspend");
+interface SuspendCarrier {
+  [SUSPEND]?: { key: string; result: Json };
+}
+
+/** Outcome of a single replay pass. */
+export type ReplayStep =
+  | { done: true }
+  | { done: false; frontier: { key: string; result: Json } };
+
+/**
+ * Replay the orchestration function against a journal. Returns `{ done: true }`
+ * if the function ran to completion, or the frontier step (the one un-recorded
+ * `ctx.run`) whose handler was just executed and must be journalled next turn.
+ *
+ * Duplicate `ctx.run` names within a single pass are disambiguated by ordinal,
+ * so a loop that calls `ctx.run("x", …)` repeatedly still gets distinct keys.
+ */
+export async function replayOnce(
+  wf: ImperativeWorkflow,
+  input: JsonObject,
+  journal: Journal,
+): Promise<ReplayStep> {
+  let ordinal = 0;
+  const ctx: WorkflowContext = {
+    input,
+    async run<T extends Json = Json>(name: string, fn: () => Promise<T> | T): Promise<T> {
+      const key = `${++ordinal}:${name}`;
+      if (Object.prototype.hasOwnProperty.call(journal, key)) {
+        return journal[key] as T; // replay: return recorded value, no side effect
+      }
+      const result = ((await fn()) ?? null) as T; // frontier: the ONE real side effect this turn
+      const carrier = new Error("nanobpm.workflow suspend") as Error & SuspendCarrier;
+      carrier[SUSPEND] = { key, result };
+      throw carrier;
+    },
+  };
+  try {
+    await wf.orchestrate(ctx);
+    return { done: true };
+  } catch (e) {
+    const s = (e as SuspendCarrier)[SUSPEND];
+    if (s) return { done: false, frontier: s };
+    throw e; // a genuine error in the orchestration or a handler
+  }
+}