@nanobpm/workflow 0.1.0

package/README.md

@@ -0,0 +1,130 @@
+# @nanobpm/workflow
+
+Code-first durable orchestration for [nanobpmn](https://github.com/Magikcraft/nano-bpm)
+(**ADR 0044**). Author durable workflows as ordinary async code; the SDK derives
+the executable BPMN model, the job types, and the message/correlation wiring, and
+hosts a generic worker. No diagram, no task-type wiring, no correlation plumbing
+written by hand.
+
+It talks to a **running nanobpmn gateway** over the REST v2 API — the engine
+provides the durability (crash-resume, at-least-once jobs, message correlation);
+this package is a thin authoring + runtime layer on top.
+
+## Why
+
+Nano already *is* a durable-execution substrate: the raft journal is the event
+history, the engine is itself replay-from-journal, a job+worker is an activity, a
+message is a signal, a BPMN timer is a timer. The missing piece was never
+durability — it was **authoring ergonomics**. This package removes the ceremony
+(model a diagram → wire each task to a job type → wire payloads → register
+workers) that Temporal and Camunda both impose.
+
+## Install
+
+```sh
+npm install @nanobpm/workflow
+```
+
+Requires Node ≥ 20 and a reachable nanobpmn gateway (default `http://localhost:8080`).
+
+## Two authoring surfaces
+
+Both compile to the same engine durability; pick per workflow.
+
+### Imperative (Temporal-style, engine-replayed)
+
+Write the orchestration as a function. `ctx.run(name, fn)` is a durable step: its
+result is journalled in an engine process variable, so on resume a completed step
+is **replayed from the journal** (its side effect is **not** re-run) and only the
+frontier step executes. The engine drives the function by re-invoking a single
+looped orchestrator job each turn.
+
+```ts
+import { defineWorkflow, WorkflowClient, Worker } from "@nanobpm/workflow";
+
+const prReview = defineWorkflow("pr-review", async (ctx) => {
+  const diff = await ctx.run("fetchDiff", () => gh.diff(ctx.input.prId));
+  const review = await ctx.run("review", () => llm.review(diff));
+  await ctx.run("merge", () => gh.merge(ctx.input.prId));
+});
+
+const client = new WorkflowClient({ baseUrl: "http://localhost:8080" });
+await client.deploy(prReview);
+
+const worker = new Worker({ baseUrl: "http://localhost:8080", workflows: [prReview] });
+worker.start();
+
+await client.start(prReview, { prId: "PR-1234" });
+```
+
+If the engine crashes after `review` commits and restarts cold, `fetchDiff` and
+`review` are **not** re-run — the workflow resumes at `merge`, which runs exactly
+once.
+
+### Declarative (with human-in-the-loop signals)
+
+Describe the flow as an ordered set of steps and signals. Each `w.run` is a
+service task (its own job type + handler); each `w.signal` parks the instance on a
+message-catch that resumes via a correlated message — the human-in-the-loop path.
+
+```ts
+import { defineFlow, WorkflowClient, Worker } from "@nanobpm/workflow";
+
+const onboarding = defineFlow("onboarding", (w) => {
+  w.run("createAccount", async (job) => ({ userId: makeId() }));
+  w.signal("approved", { correlationKey: "userId" });
+  w.run("provision", async (job) => ({ ok: true }));
+});
+
+const client = new WorkflowClient({ baseUrl: "http://localhost:8080" });
+await client.deploy(onboarding);
+new Worker({ baseUrl: "http://localhost:8080", workflows: [onboarding] }).start();
+
+const { processInstanceKey } = await client.start(onboarding, {});
+// ... later, when a human approves:
+await client.signal(onboarding, "approved", userId, { by: "alice" });
+```
+
+## Honest scope
+
+- **Durability is the engine's**, via leader-durable replication (ADR 0003). On a
+  single node it survives process crash / SIGKILL / OOM; on a cluster it is
+  majority-durable and survives node loss.
+- **Jobs are at-least-once.** A step's side effect runs *before* the job
+  completes; a crash in between causes redelivery and a repeat. **Handlers must be
+  idempotent.** For the imperative surface, `ctx.run` de-dupes *within* a workflow
+  (the journal), not across an external side effect that already partially applied.
+- **The determinism constraint binds only the imperative orchestration
+  function**, not the activities. Do all non-deterministic / side-effecting work
+  inside `ctx.run(name, fn)` closures — never in the orchestration body directly.
+- **The worker uses a single `baseUrl`.** For the single-user SDLC use case this
+  is fine; it is a client SPOF (no worker-side failover), not an engine limit.
+
+## API
+
+| Export | Purpose |
+| --- | --- |
+| `defineWorkflow(id, orchFn)` | Imperative (replayed) workflow. |
+| `defineFlow(id, build)` | Declarative flow with `w.run` / `w.signal`. |
+| `WorkflowClient` | `deploy`, `start`, `signal`, `getInstance` over REST v2. |
+| `Worker` | Generic job runtime; routes job types → handlers, hosts the replay loop. |
+| `toBpmn(workflow)` | The derived BPMN XML (for inspection / deployment). |
+
+See [ADR 0044](../docs/adr/0044-code-first-durable-orchestration.md) for the design
+rationale and the de-risking spike.
+
+## Development
+
+```sh
+npm ci
+npm run build        # tsc → dist/ (committed)
+npm run typecheck
+npm test             # build + unit tests; integration tests self-skip without a gateway binary
+```
+
+The integration tests boot a real gateway from the sibling `server/` build if
+present (`server/target/debug/nanobpm-gateway-rest-server`); otherwise they skip.
+
+## License
+
+Apache-2.0.

package/dist/client.d.ts

@@ -0,0 +1,48 @@
+import type { DeclarativeFlow, DeployResult, Job, JsonObject, StartResult, Workflow } from "./types.js";
+/** Render a workflow (either surface) to its executable BPMN model. */
+export declare function toBpmn(wf: Workflow): string;
+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 declare class WorkflowError extends Error {
+    readonly status?: number | undefined;
+    readonly body?: string | undefined;
+    constructor(message: string, status?: number | undefined, body?: string | undefined);
+}
+export declare class WorkflowClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(opts: WorkflowClientOptions);
+    private json;
+    /** Perform a request, throwing WorkflowError on transport error or !ok, and
+     *  return the raw Response (for endpoints with an empty/no-content body). */
+    private send;
+    /** Deploy a workflow's derived BPMN model. */
+    deploy(wf: Workflow): Promise<DeployResult>;
+    /**
+     * 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.
+     */
+    start(wf: Workflow, input?: JsonObject): Promise<StartResult>;
+    /** Correlate a signal to a parked declarative `signal` step. */
+    signal(flow: DeclarativeFlow, signalName: string, correlationKey: string, variables?: JsonObject): Promise<JsonObject>;
+    /** Fetch an instance (used by demos/tests to observe completion). */
+    getInstance(processInstanceKey: string): Promise<JsonObject | null>;
+    activateJobs(type: string, opts: ActivateOptions): Promise<Job[]>;
+    completeJob(jobKey: string, variables?: JsonObject): Promise<void>;
+    failJob(jobKey: string, errorMessage: string, retries?: number): Promise<void>;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,112 @@
+// 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 { assertWorkflowIds, messageName } from "./xml.js";
+/** Render a workflow (either surface) to its executable BPMN model. */
+export function toBpmn(wf) {
+    assertWorkflowIds(wf);
+    return wf.kind === "imperative" ? imperativeToBpmn(wf) : declarativeToBpmn(wf);
+}
+export class WorkflowError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "WorkflowError";
+    }
+}
+export class WorkflowClient {
+    baseUrl;
+    fetchImpl;
+    constructor(opts) {
+        if (!opts?.baseUrl)
+            throw new Error("WorkflowClient needs a baseUrl");
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        const f = opts.fetch ?? globalThis.fetch;
+        if (!f)
+            throw new Error("no fetch available; pass options.fetch (Node < 18)");
+        this.fetchImpl = f;
+    }
+    async json(path, init, what) {
+        const res = await this.send(path, init, what);
+        return (await res.json());
+    }
+    /** Perform a request, throwing WorkflowError on transport error or !ok, and
+     *  return the raw Response (for endpoints with an empty/no-content body). */
+    async send(path, init, what) {
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.baseUrl}${path}`, init);
+        }
+        catch (e) {
+            throw new WorkflowError(`${what} transport error: ${e.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) {
+        const xml = toBpmn(wf);
+        const form = new FormData();
+        form.append("resources", new Blob([xml], { type: "text/xml" }), `${wf.id}.bpmn`);
+        return this.json(`/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, input = {}) {
+        const variables = wf.kind === "imperative" ? { input, journal: {}, wfDone: false } : input;
+        return this.json(`/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, signalName, correlationKey, variables = {}) {
+        return this.json(`/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) {
+        try {
+            const res = await this.fetchImpl(`${this.baseUrl}/v2/process-instances/${processInstanceKey}`);
+            if (!res.ok)
+                return null;
+            return (await res.json());
+        }
+        catch {
+            return null;
+        }
+    }
+    // --- low-level job protocol (used by the Worker runtime) -------------------
+    async activateJobs(type, opts) {
+        const body = {
+            type,
+            worker: opts.worker,
+            maxJobsToActivate: opts.maxJobsToActivate ?? 1,
+            timeout: opts.timeout ?? 30000,
+            requestTimeout: opts.requestTimeout ?? 15000,
+        };
+        const res = await this.json(`/v2/jobs/activation`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) }, `activate ${type}`);
+        return res.jobs ?? [];
+    }
+    async completeJob(jobKey, variables = {}) {
+        await this.send(`/v2/jobs/${jobKey}/completion`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ variables }) }, "complete job");
+    }
+    async failJob(jobKey, errorMessage, retries = 0) {
+        await this.send(`/v2/jobs/${jobKey}/failure`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ errorMessage, retries }) }, "fail job");
+    }
+}

package/dist/declarative.d.ts

@@ -0,0 +1,17 @@
+import type { DeclarativeFlow, StepHandler } from "./types.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 declare function defineFlow(id: string, build: (w: FlowBuilder) => void): DeclarativeFlow;
+/** Derive an executable BPMN model from a declarative flow. */
+export declare function declarativeToBpmn(flow: DeclarativeFlow): string;

package/dist/declarative.js

@@ -0,0 +1,91 @@
+// 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 { assertIdent, escapeXml, jobType, messageName } from "./xml.js";
+/** Define a declarative flow. `build(w)` declares an ordered list of steps. */
+export function defineFlow(id, build) {
+    assertIdent("workflow id", id);
+    const steps = [];
+    const handlers = {};
+    const seen = new Set();
+    const w = {
+        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) {
+    const nodes = [];
+    const flows = [];
+    const messages = [];
+    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/dist/imperative.d.ts

@@ -0,0 +1,26 @@
+import type { ImperativeWorkflow, Json, JsonObject, Orchestration } from "./types.js";
+/** Define an imperative, replay-driven durable workflow. */
+export declare function defineWorkflow(id: string, orchestrate: Orchestration): ImperativeWorkflow;
+/** The looped-orchestrator model: start → orchestrate → gw → (done ? end : loop). */
+export declare function imperativeToBpmn(wf: ImperativeWorkflow): string;
+/** A journal of recorded step results, keyed by call-ordinal + name. */
+export type Journal = Record<string, 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 declare function replayOnce(wf: ImperativeWorkflow, input: JsonObject, journal: Journal): Promise<ReplayStep>;

package/dist/imperative.js

@@ -0,0 +1,85 @@
+// 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 { assertIdent, escapeXml, orchestrateType } from "./xml.js";
+/** Define an imperative, replay-driven durable workflow. */
+export function defineWorkflow(id, orchestrate) {
+    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) {
+    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`);
+}
+const SUSPEND = Symbol("nanobpm.workflow.suspend");
+/**
+ * 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, input, journal) {
+    let ordinal = 0;
+    const ctx = {
+        input,
+        async run(name, fn) {
+            const key = `${++ordinal}:${name}`;
+            if (Object.prototype.hasOwnProperty.call(journal, key)) {
+                return journal[key]; // replay: return recorded value, no side effect
+            }
+            const result = ((await fn()) ?? null); // frontier: the ONE real side effect this turn
+            const carrier = new Error("nanobpm.workflow suspend");
+            carrier[SUSPEND] = { key, result };
+            throw carrier;
+        },
+    };
+    try {
+        await wf.orchestrate(ctx);
+        return { done: true };
+    }
+    catch (e) {
+        const s = e[SUSPEND];
+        if (s)
+            return { done: false, frontier: s };
+        throw e; // a genuine error in the orchestration or a handler
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { defineWorkflow, imperativeToBpmn, replayOnce } from "./imperative.js";
+export type { Journal, ReplayStep } from "./imperative.js";
+export { defineFlow, declarativeToBpmn } from "./declarative.js";
+export type { FlowBuilder } from "./declarative.js";
+export { WorkflowClient, WorkflowError, toBpmn } from "./client.js";
+export type { WorkflowClientOptions, ActivateOptions } from "./client.js";
+export { Worker } from "./worker.js";
+export type { WorkerOptions, ActivityEvent } from "./worker.js";
+export type { Json, JsonObject, Job, StepHandler, DeclarativeFlow, DeclarativeStep, ImperativeWorkflow, Orchestration, WorkflowContext, Workflow, DeployResult, StartResult, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,28 @@
+// @nanobpm/workflow — code-first durable orchestration for nanobpmn (ADR 0044).
+//
+// Two authoring surfaces over the same engine durability:
+//
+//   defineWorkflow(id, async (ctx) => { await ctx.run(...) })   // imperative (replay)
+//   defineFlow(id, (w) => { w.run(...); w.signal(...); })       // declarative (+signals)
+//
+// The SDK derives the BPMN model, job types, and message/correlation wiring; the
+// Worker runtime hosts them; the WorkflowClient deploys, starts, and signals.
+//
+// Quickstart:
+//
+//   import { defineWorkflow, WorkflowClient, Worker } from "@nanobpm/workflow";
+//
+//   const wf = defineWorkflow("pr-review", async (ctx) => {
+//     const diff = await ctx.run("fetchDiff", () => gh.diff(ctx.input.prId));
+//     await ctx.run("merge", () => gh.merge(ctx.input.prId));
+//   });
+//
+//   const client = new WorkflowClient({ baseUrl: "http://localhost:8080" });
+//   await client.deploy(wf);
+//   const worker = new Worker({ baseUrl: "http://localhost:8080", workflows: [wf] });
+//   worker.start();
+//   await client.start(wf, { prId: "PR-1234" });
+export { defineWorkflow, imperativeToBpmn, replayOnce } from "./imperative.js";
+export { defineFlow, declarativeToBpmn } from "./declarative.js";
+export { WorkflowClient, WorkflowError, toBpmn } from "./client.js";
+export { Worker } from "./worker.js";

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+/** A JSON-serialisable value, as carried by process variables. */
+export type Json = null | boolean | number | string | Json[] | {
+    [k: string]: Json;
+};
+export type JsonObject = {
+    [k: string]: Json;
+};
+/** A job as delivered by the nanobpmn gateway's `POST /v2/jobs/activation`. */
+export interface Job {
+    jobKey: string;
+    processInstanceKey: string;
+    elementId: string;
+    type: string;
+    variables: JsonObject;
+}
+/** Handler for a declarative `run` step: does real work, returns variables. */
+export type StepHandler = (job: Job) => Promise<JsonObject | void> | JsonObject | void;
+export type DeclarativeStep = {
+    kind: "run";
+    name: string;
+} | {
+    kind: "signal";
+    name: string;
+    correlationKey: string;
+};
+export interface DeclarativeFlow {
+    kind: "declarative";
+    id: string;
+    steps: DeclarativeStep[];
+    handlers: Record<string, StepHandler>;
+}
+/** The context passed to an imperative orchestration function. */
+export interface WorkflowContext {
+    /** The workflow's start input (immutable across replays). */
+    readonly input: JsonObject;
+    /**
+     * A durable activity. On first execution the handler runs (its side effects
+     * happen once); on every subsequent replay the recorded result is returned
+     * WITHOUT invoking the handler. The handler is the only place side effects
+     * (I/O, network, shell, LLM) are allowed — the orchestration body itself must
+     * be deterministic.
+     */
+    run<T extends Json = Json>(name: string, fn: () => Promise<T> | T): Promise<T>;
+}
+export type Orchestration = (ctx: WorkflowContext) => Promise<void>;
+export interface ImperativeWorkflow {
+    kind: "imperative";
+    id: string;
+    orchestrate: Orchestration;
+    /** Derived job type of the single orchestrator task: `<id>:__orchestrate`. */
+    orchestrateType: string;
+}
+export type Workflow = DeclarativeFlow | ImperativeWorkflow;
+/** Result of deploying a workflow. */
+export interface DeployResult {
+    [k: string]: Json;
+}
+/** Result of starting a workflow instance. */
+export interface StartResult {
+    processInstanceKey?: string;
+    [k: string]: Json | undefined;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// Public types for @nanobpm/workflow.
+export {};