@nanobpm/bojtos-kit 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# @nanobpm/bojtos-kit
+
+Framework-agnostic core of the **Bojtos** in-browser BPMN demo framework
+([ADR 0043](../docs/adr/0043-bojtos-demo-framework.md)).
+
+It wraps [`@nanobpm/engine-wasm`](../engine-wasm) as a single scenario runner —
+the one runner the whole framework (and the console test-run panel) drives, so
+there is no second, drift-prone engine harness — and re-exports the engine's
+snapshot/event contract types.
+
+```ts
+import { createBojtosSession } from "@nanobpm/bojtos-kit";
+
+const session = await createBojtosSession(); // loads the wasm engine once
+const { processIds } = session.deploy(bpmnXml);
+let snapshot = session.createInstance(processIds[0], "{}");
+// a service task is now waiting as a job:
+snapshot = session.completeJob(snapshot.jobs[0].key, JSON.stringify({ ok: true }));
+const trace = session.events(); // WasmEvent[] for a step/trace view
+session.free();
+```
+
+Every command returns the post-run `Snapshot`: `activeElementIds` /
+`incidentElementIds` drive the token/incident highlight, and
+`instances[].variables` is the live payload that mutates as workers complete.
+
+For React, use [`@nanobpm/bojtos-react`](../bojtos-react), which owns the session
+lifecycle and reactive state on top of this kit.
+
+## Build
+
+`dist/` (the tsc-emitted JS + `.d.ts`) is committed so `file:` consumers and CI
+need no build-on-install step. Regenerate with `npm run build`.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ensureWasm, createBojtosSession, type BojtosSession, type WasmSource, } from "./session.js";
+export { dispatchWorkers, dispatchRound, JobFailure, type JobHandler, type JobResult, type DispatchOptions, type DispatchResult, type RoundResult, } from "./worker.js";
+export type { Snapshot, InstanceDto, JobDto, ActivatedJob, IncidentDto, TimerDto, ActiveEl, WasmEvent, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+// @nanobpm/bojtos-kit — the framework-agnostic core of the Bojtos demo
+// framework (ADR 0043). Wraps the in-browser wasm engine as a single scenario
+// runner and re-exports the engine's snapshot/event contract types.
+export { ensureWasm, createBojtosSession, } from "./session.js";
+export { dispatchWorkers, dispatchRound, JobFailure, } from "./worker.js";

package/dist/session.d.ts

@@ -0,0 +1,85 @@
+import { type InitInput } from "@nanobpm/engine-wasm";
+import type { ActivatedJob, Snapshot, WasmEvent } from "./types.js";
+/**
+ * The source of the engine wasm binary. Under a bundler that understands
+ * `new URL(..., import.meta.url)` (e.g. Vite) the default loader needs no
+ * argument; pass an explicit `URL` / `Response` / bytes / `WebAssembly.Module`
+ * when the environment can't resolve it that way (Node, Jest, or the external-
+ * `.wasm` "wasmUrl" mode — ADR 0043 §3).
+ */
+export type WasmSource = InitInput;
+/**
+ * Initialise the wasm engine module (idempotent; safe to call repeatedly). The
+ * first successful call wins: a `source` passed to a later call is ignored once
+ * the module is already loading or loaded. Pass a `source` in environments where
+ * the default `import.meta.url` fetch can't resolve the binary
+ * (Node/Jest/webpack).
+ *
+ * If a load *fails*, the cached promise is cleared so a later call — e.g. one
+ * that supplies a working `WasmSource` after the default loader couldn't resolve
+ * the binary — can retry rather than being stuck on the first rejection.
+ */
+export declare function ensureWasm(source?: WasmSource): Promise<void>;
+/**
+ * A headless handle to one in-browser engine instance: deploy a diagram, start
+ * instances, complete/fail jobs, advance the virtual clock, and read the event
+ * log. Every command returns the post-run {@link Snapshot}. This is the single
+ * scenario runner the Bojtos framework and the console both drive (ADR 0043 §8);
+ * framework bindings (`@nanobpm/bojtos-react`) own the reactive state on top.
+ */
+export interface BojtosSession {
+    /**
+     * Parse and deploy a BPMN resource. Returns the deployable process ids.
+     * Throws a JS error carrying the parse/deploy failure message.
+     */
+    deploy(xml: string): {
+        processIds: string[];
+    };
+    /** Start an instance of `processId`, seeding it with `variablesJson`. */
+    createInstance(processId: string, variablesJson: string): Snapshot;
+    /**
+     * Activate up to `maxJobs` `Created` jobs of `jobType`, locking them to
+     * `worker` until `now + timeoutMs`. Returns the activated jobs (each carrying
+     * the instance's current variables) for a dispatch loop to hand to worker
+     * handlers. A job that is already activated is not re-returned.
+     */
+    activateJobs(jobType: string, maxJobs: number, timeoutMs: number, worker: string): ActivatedJob[];
+    /** Complete a waiting job, merging `variablesJson` into the instance. */
+    completeJob(jobKey: string, variablesJson: string): Snapshot;
+    /** Fail a waiting job; with no retries left this raises an incident. */
+    failJob(jobKey: string, retries: number, message: string): Snapshot;
+    /**
+     * Correlate a message to any instance waiting on it: publishes `messageName`
+     * with `correlationKey` (the value the waiting subscription's `correlationKey`
+     * expression resolved to) and merges `variablesJson` into each correlated
+     * instance. Unblocks a message intermediate-catch / receive task without an
+     * external broker — the in-browser equivalent of an app publishing a message.
+     */
+    correlateMessage(messageName: string, correlationKey: string, variablesJson: string): Snapshot;
+    /** Advance the virtual clock by `byMs`, firing due timers and lapsed locks. */
+    advanceTime(byMs: number): Snapshot;
+    /**
+     * Discard all engine state (definitions, instances, jobs, timers, event log
+     * and clock), returning the underlying engine to its pristine state. The
+     * caller redeploys afterwards to begin a clean run — this is what lets a
+     * re-run start from zero completed instances instead of accumulating across
+     * runs.
+     */
+    reset(): void;
+    /** The full ordered event log emitted so far. */
+    events(): WasmEvent[];
+    /** The current simulation state. */
+    snapshot(): Snapshot;
+    /** Release the underlying wasm engine. */
+    free(): void;
+}
+/**
+ * Create a fresh headless engine session. Ensures the wasm module is loaded
+ * (once per page), then constructs a new {@link TestEngine}. The virtual clock
+ * starts at 0; deploy a diagram before starting instances. Pass a `wasm` source
+ * in environments where the default `import.meta.url` loader can't resolve the
+ * binary (Node/Jest, or the external-`.wasm` mode — ADR 0043 §3).
+ */
+export declare function createBojtosSession(opts?: {
+    wasm?: WasmSource;
+}): Promise<BojtosSession>;

package/dist/session.js

@@ -0,0 +1,80 @@
+import init, { TestEngine } from "@nanobpm/engine-wasm";
+// Lazily initialise the wasm module exactly once per page, no matter how many
+// sessions are created. Mirrors the console's original `ensureWasm`.
+let wasmReady = null;
+/**
+ * Initialise the wasm engine module (idempotent; safe to call repeatedly). The
+ * first successful call wins: a `source` passed to a later call is ignored once
+ * the module is already loading or loaded. Pass a `source` in environments where
+ * the default `import.meta.url` fetch can't resolve the binary
+ * (Node/Jest/webpack).
+ *
+ * If a load *fails*, the cached promise is cleared so a later call — e.g. one
+ * that supplies a working `WasmSource` after the default loader couldn't resolve
+ * the binary — can retry rather than being stuck on the first rejection.
+ */
+export function ensureWasm(source) {
+    if (!wasmReady) {
+        wasmReady = init(source === undefined ? undefined : { module_or_path: source })
+            .then(() => undefined)
+            .catch((e) => {
+            wasmReady = null;
+            throw e;
+        });
+    }
+    return wasmReady;
+}
+function parseSnapshot(json) {
+    // The wasm engine is the schema authority; its JSON is the contract boundary.
+    return JSON.parse(json);
+}
+class WasmBojtosSession {
+    engine;
+    constructor(engine) {
+        this.engine = engine;
+    }
+    deploy(xml) {
+        return JSON.parse(this.engine.deploy(xml));
+    }
+    createInstance(processId, variablesJson) {
+        return parseSnapshot(this.engine.createInstance(processId, variablesJson || "{}"));
+    }
+    activateJobs(jobType, maxJobs, timeoutMs, worker) {
+        return JSON.parse(this.engine.activateJobs(jobType, maxJobs, timeoutMs, worker));
+    }
+    completeJob(jobKey, variablesJson) {
+        return parseSnapshot(this.engine.completeJob(jobKey, variablesJson || "{}"));
+    }
+    failJob(jobKey, retries, message) {
+        return parseSnapshot(this.engine.failJob(jobKey, retries, message));
+    }
+    correlateMessage(messageName, correlationKey, variablesJson) {
+        return parseSnapshot(this.engine.correlateMessage(messageName, correlationKey, variablesJson || "{}"));
+    }
+    advanceTime(byMs) {
+        return parseSnapshot(this.engine.advanceTime(byMs));
+    }
+    reset() {
+        this.engine.reset();
+    }
+    events() {
+        return JSON.parse(this.engine.events());
+    }
+    snapshot() {
+        return parseSnapshot(this.engine.snapshot());
+    }
+    free() {
+        this.engine.free();
+    }
+}
+/**
+ * Create a fresh headless engine session. Ensures the wasm module is loaded
+ * (once per page), then constructs a new {@link TestEngine}. The virtual clock
+ * starts at 0; deploy a diagram before starting instances. Pass a `wasm` source
+ * in environments where the default `import.meta.url` loader can't resolve the
+ * binary (Node/Jest, or the external-`.wasm` mode — ADR 0043 §3).
+ */
+export async function createBojtosSession(opts) {
+    await ensureWasm(opts?.wasm);
+    return new WasmBojtosSession(new TestEngine());
+}

package/dist/types.d.ts

@@ -0,0 +1,82 @@
+/** One active element token within an instance. */
+export interface ActiveEl {
+    key: string;
+    elementId: string;
+}
+/** A process instance's live state. */
+export interface InstanceDto {
+    key: string;
+    processId: string;
+    state: string;
+    completed: boolean;
+    activeElements: ActiveEl[];
+    variables: Record<string, unknown>;
+}
+/** A job waiting for a worker. */
+export interface JobDto {
+    key: string;
+    instanceKey: string;
+    elementId: string;
+    jobType: string;
+    state: string;
+    retries: number;
+}
+/**
+ * A job locked to a worker by {@link BojtosSession.activateJobs}, ready to hand
+ * to a {@link JobHandler}. Carries the instance's current `variables` so a
+ * handler can compute its output from the live payload. `key` is what
+ * `completeJob` / `failJob` take.
+ */
+export interface ActivatedJob {
+    key: string;
+    type: string;
+    instanceKey: string;
+    elementId: string;
+    retries: number;
+    variables: Record<string, unknown>;
+}
+/** An incident raised on an element. */
+export interface IncidentDto {
+    key: string;
+    instanceKey: string;
+    elementId: string;
+    kind: string;
+    reason: string;
+}
+/** A pending timer. */
+export interface TimerDto {
+    key: string;
+    instanceKey: string;
+    elementId: string;
+    dueAt: number;
+    dueInMs: number;
+}
+/**
+ * The full simulation state returned by every engine command. `activeElementIds`
+ * / `incidentElementIds` drive the token/incident highlight (the visual
+ * contract, ADR 0043 §4); `instances[].variables` is the live payload.
+ */
+export interface Snapshot {
+    now: number;
+    eventCount: number;
+    /** Present on a `createInstance` snapshot: the new instance key. */
+    created?: string;
+    totalInstances: number;
+    completedInstances: number;
+    instances: InstanceDto[];
+    jobs: JobDto[];
+    incidents: IncidentDto[];
+    timers: TimerDto[];
+    activeElementIds: string[];
+    incidentElementIds: string[];
+}
+/**
+ * A flattened wasm engine event: `{ seq, now, type, ...snake_case fields }`.
+ * Produced by `TestEngine.events()` and folded into a trace view by consumers.
+ */
+export interface WasmEvent {
+    seq: number;
+    now: number;
+    type: string;
+    [k: string]: unknown;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+// The shapes the in-browser engine (`@nanobpm/engine-wasm`) emits from its
+// JSON string surface — `deploy` / `createInstance` / `completeJob` / `failJob`
+// / `advanceTime` / `snapshot` return a `Snapshot`, and `events()` returns a
+// `WasmEvent[]`. These describe the engine's public contract, so they live in
+// the framework-agnostic kit and are re-exported by the React binding.
+export {};

package/dist/worker.d.ts

@@ -0,0 +1,81 @@
+import type { BojtosSession } from "./session.js";
+import type { ActivatedJob, Snapshot } from "./types.js";
+/**
+ * The variables a handler merges into its instance on completion. Return an
+ * object to merge it, or `void`/`undefined` to complete with no new variables.
+ * To fail a job instead, throw — a plain `Error` fails it with `retries - 1`
+ * (an incident once retries reach 0); throw a {@link JobFailure} to set the
+ * remaining retries explicitly.
+ */
+export type JobResult = Record<string, unknown>;
+/**
+ * A worker for one job type: given an {@link ActivatedJob} (carrying the
+ * instance's current variables), compute the output variables to merge on
+ * completion. May be async. Throw to fail the job.
+ */
+export type JobHandler = (job: ActivatedJob) => JobResult | void | Promise<JobResult | void>;
+/**
+ * Throw from a {@link JobHandler} to fail a job with an explicit remaining
+ * `retries` count (default is `job.retries - 1`). With `retries: 0` the engine
+ * raises an incident, which surfaces in the snapshot's `incidentElementIds` —
+ * handy for demoing the failure path deterministically.
+ */
+export declare class JobFailure extends Error {
+    readonly retries?: number;
+    constructor(message: string, opts?: {
+        retries?: number;
+    });
+}
+/** Tuning for {@link dispatchWorkers}. */
+export interface DispatchOptions {
+    /** Max jobs to activate per job type per round (default 10). */
+    maxJobsPerActivation?: number;
+    /** Lock timeout handed to `activateJobs`, in ms (default 30_000). */
+    lockTimeoutMs?: number;
+    /** Worker name jobs are locked to (default `"bojtos"`). */
+    worker?: string;
+    /**
+     * Safety cap on drain rounds (default 1000). A handler that keeps creating
+     * work (e.g. an unbounded loop in the model) would otherwise spin forever;
+     * exceeding the cap throws instead.
+     */
+    maxRounds?: number;
+}
+/** What one {@link dispatchRound} pass did. */
+export interface RoundResult {
+    /** The snapshot after this pass. */
+    snapshot: Snapshot;
+    /** How many jobs were completed or failed in this pass. */
+    handled: number;
+}
+/** What {@link dispatchWorkers} did. */
+export interface DispatchResult {
+    /** The snapshot after the drain settled. */
+    snapshot: Snapshot;
+    /** How many jobs were completed or failed. */
+    handled: number;
+    /** How many activate rounds ran (including the final quiescent one). */
+    rounds: number;
+}
+/**
+ * Run one activate-and-handle pass: activate every registered job type's
+ * currently-`Created` jobs *first* (a snapshot of the token frontier), then hand
+ * each to its handler (complete on return, fail on throw). Jobs a handler
+ * unblocks downstream are deliberately *not* chased within the same round — they
+ * belong to the next frontier — so one round advances every live token by
+ * exactly one step. That makes this the animatable unit: drive it on a timer to
+ * watch the token(s) hop task-to-task. {@link dispatchWorkers} loops it to
+ * quiescence.
+ */
+export declare function dispatchRound(session: BojtosSession, workers: Record<string, JobHandler>, opts?: DispatchOptions): Promise<RoundResult>;
+/**
+ * Drive an in-browser worker loop over a {@link BojtosSession}: repeatedly
+ * {@link dispatchRound} until a round handles nothing, so a whole process runs
+ * to quiescence in one call. Job types with no registered handler are simply
+ * left waiting.
+ *
+ * This is the dispatch half of the Bojtos runtime (ADR 0043 §8 step 3) — the
+ * "activate → JS handler → complete/fail" loop that makes the token move and the
+ * variable payload mutate as workers run.
+ */
+export declare function dispatchWorkers(session: BojtosSession, workers: Record<string, JobHandler>, opts?: DispatchOptions): Promise<DispatchResult>;

package/dist/worker.js

@@ -0,0 +1,92 @@
+/**
+ * Throw from a {@link JobHandler} to fail a job with an explicit remaining
+ * `retries` count (default is `job.retries - 1`). With `retries: 0` the engine
+ * raises an incident, which surfaces in the snapshot's `incidentElementIds` —
+ * handy for demoing the failure path deterministically.
+ */
+export class JobFailure extends Error {
+    retries;
+    constructor(message, opts) {
+        super(message);
+        this.name = "JobFailure";
+        this.retries = opts?.retries;
+    }
+}
+async function runOne(session, handler, job) {
+    let payload;
+    try {
+        // Only the handler and the serialization of its result are treated as a
+        // job failure: a handler that throws (or returns something unserializable)
+        // is the demo's own logic failing, so we translate it into `failJob`.
+        const out = await handler(job);
+        payload = JSON.stringify(out ?? {});
+    }
+    catch (e) {
+        const retries = e instanceof JobFailure && e.retries !== undefined
+            ? e.retries
+            : Math.max(0, job.retries - 1);
+        const message = e instanceof Error ? e.message : String(e);
+        session.failJob(job.key, retries, message);
+        return;
+    }
+    // An engine command failure (invalid JSON the engine rejects, ABI mismatch,
+    // internal engine error) is a real problem, not a handler failure — masking
+    // it as `failJob` would hide the bug and mutate engine state incorrectly, so
+    // we let it bubble to the caller.
+    session.completeJob(job.key, payload);
+}
+/**
+ * Run one activate-and-handle pass: activate every registered job type's
+ * currently-`Created` jobs *first* (a snapshot of the token frontier), then hand
+ * each to its handler (complete on return, fail on throw). Jobs a handler
+ * unblocks downstream are deliberately *not* chased within the same round — they
+ * belong to the next frontier — so one round advances every live token by
+ * exactly one step. That makes this the animatable unit: drive it on a timer to
+ * watch the token(s) hop task-to-task. {@link dispatchWorkers} loops it to
+ * quiescence.
+ */
+export async function dispatchRound(session, workers, opts = {}) {
+    const maxJobs = opts.maxJobsPerActivation ?? 10;
+    const timeout = opts.lockTimeoutMs ?? 30_000;
+    const worker = opts.worker ?? "bojtos";
+    // Activation pass: lock the whole current frontier before running any handler,
+    // so a job a handler unblocks isn't also picked up this round (which would
+    // cascade the entire chain in a single "step").
+    const batch = [];
+    for (const [jobType, handler] of Object.entries(workers)) {
+        for (const job of session.activateJobs(jobType, maxJobs, timeout, worker)) {
+            batch.push({ handler, job });
+        }
+    }
+    // Handle pass.
+    for (const { handler, job } of batch) {
+        await runOne(session, handler, job);
+    }
+    return { snapshot: session.snapshot(), handled: batch.length };
+}
+/**
+ * Drive an in-browser worker loop over a {@link BojtosSession}: repeatedly
+ * {@link dispatchRound} until a round handles nothing, so a whole process runs
+ * to quiescence in one call. Job types with no registered handler are simply
+ * left waiting.
+ *
+ * This is the dispatch half of the Bojtos runtime (ADR 0043 §8 step 3) — the
+ * "activate → JS handler → complete/fail" loop that makes the token move and the
+ * variable payload mutate as workers run.
+ */
+export async function dispatchWorkers(session, workers, opts = {}) {
+    const maxRounds = opts.maxRounds ?? 1000;
+    let handled = 0;
+    let rounds = 0;
+    for (;;) {
+        if (rounds >= maxRounds) {
+            throw new Error(`dispatchWorkers exceeded maxRounds (${maxRounds}) — a handler may be creating work without end`);
+        }
+        rounds++;
+        const round = await dispatchRound(session, workers, opts);
+        handled += round.handled;
+        if (round.handled === 0) {
+            return { snapshot: round.snapshot, handled, rounds };
+        }
+    }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@nanobpm/bojtos-kit",
+  "version": "0.1.0",
+  "description": "Framework-agnostic core of the Bojtos in-browser BPMN demo framework (ADR 0043): a single scenario runner over the @nanobpm/engine-wasm engine (deploy, start instances, complete/fail jobs, advance the clock, read snapshots and the event log), plus the engine's snapshot/event contract types. Consumed by @nanobpm/bojtos-react and the console test-run panel.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Magikcraft/nano-bpm",
+    "directory": "bojtos-kit"
+  },
+  "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"
+  ],
+  "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",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@nanobpm/engine-wasm": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+// @nanobpm/bojtos-kit — the framework-agnostic core of the Bojtos demo
+// framework (ADR 0043). Wraps the in-browser wasm engine as a single scenario
+// runner and re-exports the engine's snapshot/event contract types.
+
+export {
+  ensureWasm,
+  createBojtosSession,
+  type BojtosSession,
+  type WasmSource,
+} from "./session.js";
+export {
+  dispatchWorkers,
+  dispatchRound,
+  JobFailure,
+  type JobHandler,
+  type JobResult,
+  type DispatchOptions,
+  type DispatchResult,
+  type RoundResult,
+} from "./worker.js";
+export type {
+  Snapshot,
+  InstanceDto,
+  JobDto,
+  ActivatedJob,
+  IncidentDto,
+  TimerDto,
+  ActiveEl,
+  WasmEvent,
+} from "./types.js";

package/src/session.ts

@@ -0,0 +1,191 @@
+import init, { type InitInput, TestEngine } from "@nanobpm/engine-wasm";
+import type { ActivatedJob, Snapshot, WasmEvent } from "./types.js";
+
+// Lazily initialise the wasm module exactly once per page, no matter how many
+// sessions are created. Mirrors the console's original `ensureWasm`.
+let wasmReady: Promise<void> | null = null;
+
+/**
+ * The source of the engine wasm binary. Under a bundler that understands
+ * `new URL(..., import.meta.url)` (e.g. Vite) the default loader needs no
+ * argument; pass an explicit `URL` / `Response` / bytes / `WebAssembly.Module`
+ * when the environment can't resolve it that way (Node, Jest, or the external-
+ * `.wasm` "wasmUrl" mode — ADR 0043 §3).
+ */
+export type WasmSource = InitInput;
+
+/**
+ * Initialise the wasm engine module (idempotent; safe to call repeatedly). The
+ * first successful call wins: a `source` passed to a later call is ignored once
+ * the module is already loading or loaded. Pass a `source` in environments where
+ * the default `import.meta.url` fetch can't resolve the binary
+ * (Node/Jest/webpack).
+ *
+ * If a load *fails*, the cached promise is cleared so a later call — e.g. one
+ * that supplies a working `WasmSource` after the default loader couldn't resolve
+ * the binary — can retry rather than being stuck on the first rejection.
+ */
+export function ensureWasm(source?: WasmSource): Promise<void> {
+  if (!wasmReady) {
+    wasmReady = init(
+      source === undefined ? undefined : { module_or_path: source },
+    )
+      .then(() => undefined)
+      .catch((e) => {
+        wasmReady = null;
+        throw e;
+      });
+  }
+  return wasmReady;
+}
+
+/**
+ * A headless handle to one in-browser engine instance: deploy a diagram, start
+ * instances, complete/fail jobs, advance the virtual clock, and read the event
+ * log. Every command returns the post-run {@link Snapshot}. This is the single
+ * scenario runner the Bojtos framework and the console both drive (ADR 0043 §8);
+ * framework bindings (`@nanobpm/bojtos-react`) own the reactive state on top.
+ */
+export interface BojtosSession {
+  /**
+   * Parse and deploy a BPMN resource. Returns the deployable process ids.
+   * Throws a JS error carrying the parse/deploy failure message.
+   */
+  deploy(xml: string): { processIds: string[] };
+  /** Start an instance of `processId`, seeding it with `variablesJson`. */
+  createInstance(processId: string, variablesJson: string): Snapshot;
+  /**
+   * Activate up to `maxJobs` `Created` jobs of `jobType`, locking them to
+   * `worker` until `now + timeoutMs`. Returns the activated jobs (each carrying
+   * the instance's current variables) for a dispatch loop to hand to worker
+   * handlers. A job that is already activated is not re-returned.
+   */
+  activateJobs(
+    jobType: string,
+    maxJobs: number,
+    timeoutMs: number,
+    worker: string,
+  ): ActivatedJob[];
+  /** Complete a waiting job, merging `variablesJson` into the instance. */
+  completeJob(jobKey: string, variablesJson: string): Snapshot;
+  /** Fail a waiting job; with no retries left this raises an incident. */
+  failJob(jobKey: string, retries: number, message: string): Snapshot;
+  /**
+   * Correlate a message to any instance waiting on it: publishes `messageName`
+   * with `correlationKey` (the value the waiting subscription's `correlationKey`
+   * expression resolved to) and merges `variablesJson` into each correlated
+   * instance. Unblocks a message intermediate-catch / receive task without an
+   * external broker — the in-browser equivalent of an app publishing a message.
+   */
+  correlateMessage(
+    messageName: string,
+    correlationKey: string,
+    variablesJson: string,
+  ): Snapshot;
+  /** Advance the virtual clock by `byMs`, firing due timers and lapsed locks. */
+  advanceTime(byMs: number): Snapshot;
+  /**
+   * Discard all engine state (definitions, instances, jobs, timers, event log
+   * and clock), returning the underlying engine to its pristine state. The
+   * caller redeploys afterwards to begin a clean run — this is what lets a
+   * re-run start from zero completed instances instead of accumulating across
+   * runs.
+   */
+  reset(): void;
+  /** The full ordered event log emitted so far. */
+  events(): WasmEvent[];
+  /** The current simulation state. */
+  snapshot(): Snapshot;
+  /** Release the underlying wasm engine. */
+  free(): void;
+}
+
+function parseSnapshot(json: string): Snapshot {
+  // The wasm engine is the schema authority; its JSON is the contract boundary.
+  return JSON.parse(json) as Snapshot;
+}
+
+class WasmBojtosSession implements BojtosSession {
+  private readonly engine: TestEngine;
+
+  constructor(engine: TestEngine) {
+    this.engine = engine;
+  }
+
+  deploy(xml: string): { processIds: string[] } {
+    return JSON.parse(this.engine.deploy(xml)) as { processIds: string[] };
+  }
+
+  createInstance(processId: string, variablesJson: string): Snapshot {
+    return parseSnapshot(
+      this.engine.createInstance(processId, variablesJson || "{}"),
+    );
+  }
+
+  activateJobs(
+    jobType: string,
+    maxJobs: number,
+    timeoutMs: number,
+    worker: string,
+  ): ActivatedJob[] {
+    return JSON.parse(
+      this.engine.activateJobs(jobType, maxJobs, timeoutMs, worker),
+    ) as ActivatedJob[];
+  }
+
+  completeJob(jobKey: string, variablesJson: string): Snapshot {
+    return parseSnapshot(this.engine.completeJob(jobKey, variablesJson || "{}"));
+  }
+
+  failJob(jobKey: string, retries: number, message: string): Snapshot {
+    return parseSnapshot(this.engine.failJob(jobKey, retries, message));
+  }
+
+  correlateMessage(
+    messageName: string,
+    correlationKey: string,
+    variablesJson: string,
+  ): Snapshot {
+    return parseSnapshot(
+      this.engine.correlateMessage(
+        messageName,
+        correlationKey,
+        variablesJson || "{}",
+      ),
+    );
+  }
+
+  advanceTime(byMs: number): Snapshot {
+    return parseSnapshot(this.engine.advanceTime(byMs));
+  }
+
+  reset(): void {
+    this.engine.reset();
+  }
+
+  events(): WasmEvent[] {
+    return JSON.parse(this.engine.events()) as WasmEvent[];
+  }
+
+  snapshot(): Snapshot {
+    return parseSnapshot(this.engine.snapshot());
+  }
+
+  free(): void {
+    this.engine.free();
+  }
+}
+
+/**
+ * Create a fresh headless engine session. Ensures the wasm module is loaded
+ * (once per page), then constructs a new {@link TestEngine}. The virtual clock
+ * starts at 0; deploy a diagram before starting instances. Pass a `wasm` source
+ * in environments where the default `import.meta.url` loader can't resolve the
+ * binary (Node/Jest, or the external-`.wasm` mode — ADR 0043 §3).
+ */
+export async function createBojtosSession(opts?: {
+  wasm?: WasmSource;
+}): Promise<BojtosSession> {
+  await ensureWasm(opts?.wasm);
+  return new WasmBojtosSession(new TestEngine());
+}

package/src/types.ts

@@ -0,0 +1,95 @@
+// The shapes the in-browser engine (`@nanobpm/engine-wasm`) emits from its
+// JSON string surface — `deploy` / `createInstance` / `completeJob` / `failJob`
+// / `advanceTime` / `snapshot` return a `Snapshot`, and `events()` returns a
+// `WasmEvent[]`. These describe the engine's public contract, so they live in
+// the framework-agnostic kit and are re-exported by the React binding.
+
+/** One active element token within an instance. */
+export interface ActiveEl {
+  key: string;
+  elementId: string;
+}
+
+/** A process instance's live state. */
+export interface InstanceDto {
+  key: string;
+  processId: string;
+  state: string;
+  completed: boolean;
+  activeElements: ActiveEl[];
+  variables: Record<string, unknown>;
+}
+
+/** A job waiting for a worker. */
+export interface JobDto {
+  key: string;
+  instanceKey: string;
+  elementId: string;
+  jobType: string;
+  state: string;
+  retries: number;
+}
+
+/**
+ * A job locked to a worker by {@link BojtosSession.activateJobs}, ready to hand
+ * to a {@link JobHandler}. Carries the instance's current `variables` so a
+ * handler can compute its output from the live payload. `key` is what
+ * `completeJob` / `failJob` take.
+ */
+export interface ActivatedJob {
+  key: string;
+  type: string;
+  instanceKey: string;
+  elementId: string;
+  retries: number;
+  variables: Record<string, unknown>;
+}
+
+/** An incident raised on an element. */
+export interface IncidentDto {
+  key: string;
+  instanceKey: string;
+  elementId: string;
+  kind: string;
+  reason: string;
+}
+
+/** A pending timer. */
+export interface TimerDto {
+  key: string;
+  instanceKey: string;
+  elementId: string;
+  dueAt: number;
+  dueInMs: number;
+}
+
+/**
+ * The full simulation state returned by every engine command. `activeElementIds`
+ * / `incidentElementIds` drive the token/incident highlight (the visual
+ * contract, ADR 0043 §4); `instances[].variables` is the live payload.
+ */
+export interface Snapshot {
+  now: number;
+  eventCount: number;
+  /** Present on a `createInstance` snapshot: the new instance key. */
+  created?: string;
+  totalInstances: number;
+  completedInstances: number;
+  instances: InstanceDto[];
+  jobs: JobDto[];
+  incidents: IncidentDto[];
+  timers: TimerDto[];
+  activeElementIds: string[];
+  incidentElementIds: string[];
+}
+
+/**
+ * A flattened wasm engine event: `{ seq, now, type, ...snake_case fields }`.
+ * Produced by `TestEngine.events()` and folded into a trace view by consumers.
+ */
+export interface WasmEvent {
+  seq: number;
+  now: number;
+  type: string;
+  [k: string]: unknown;
+}

package/src/worker.ts

@@ -0,0 +1,164 @@
+import type { BojtosSession } from "./session.js";
+import type { ActivatedJob, Snapshot } from "./types.js";
+
+/**
+ * The variables a handler merges into its instance on completion. Return an
+ * object to merge it, or `void`/`undefined` to complete with no new variables.
+ * To fail a job instead, throw — a plain `Error` fails it with `retries - 1`
+ * (an incident once retries reach 0); throw a {@link JobFailure} to set the
+ * remaining retries explicitly.
+ */
+export type JobResult = Record<string, unknown>;
+
+/**
+ * A worker for one job type: given an {@link ActivatedJob} (carrying the
+ * instance's current variables), compute the output variables to merge on
+ * completion. May be async. Throw to fail the job.
+ */
+export type JobHandler = (
+  job: ActivatedJob,
+) => JobResult | void | Promise<JobResult | void>;
+
+/**
+ * Throw from a {@link JobHandler} to fail a job with an explicit remaining
+ * `retries` count (default is `job.retries - 1`). With `retries: 0` the engine
+ * raises an incident, which surfaces in the snapshot's `incidentElementIds` —
+ * handy for demoing the failure path deterministically.
+ */
+export class JobFailure extends Error {
+  readonly retries?: number;
+  constructor(message: string, opts?: { retries?: number }) {
+    super(message);
+    this.name = "JobFailure";
+    this.retries = opts?.retries;
+  }
+}
+
+/** Tuning for {@link dispatchWorkers}. */
+export interface DispatchOptions {
+  /** Max jobs to activate per job type per round (default 10). */
+  maxJobsPerActivation?: number;
+  /** Lock timeout handed to `activateJobs`, in ms (default 30_000). */
+  lockTimeoutMs?: number;
+  /** Worker name jobs are locked to (default `"bojtos"`). */
+  worker?: string;
+  /**
+   * Safety cap on drain rounds (default 1000). A handler that keeps creating
+   * work (e.g. an unbounded loop in the model) would otherwise spin forever;
+   * exceeding the cap throws instead.
+   */
+  maxRounds?: number;
+}
+
+/** What one {@link dispatchRound} pass did. */
+export interface RoundResult {
+  /** The snapshot after this pass. */
+  snapshot: Snapshot;
+  /** How many jobs were completed or failed in this pass. */
+  handled: number;
+}
+
+/** What {@link dispatchWorkers} did. */
+export interface DispatchResult {
+  /** The snapshot after the drain settled. */
+  snapshot: Snapshot;
+  /** How many jobs were completed or failed. */
+  handled: number;
+  /** How many activate rounds ran (including the final quiescent one). */
+  rounds: number;
+}
+
+async function runOne(
+  session: BojtosSession,
+  handler: JobHandler,
+  job: ActivatedJob,
+): Promise<void> {
+  let payload: string;
+  try {
+    // Only the handler and the serialization of its result are treated as a
+    // job failure: a handler that throws (or returns something unserializable)
+    // is the demo's own logic failing, so we translate it into `failJob`.
+    const out = await handler(job);
+    payload = JSON.stringify(out ?? {});
+  } catch (e) {
+    const retries =
+      e instanceof JobFailure && e.retries !== undefined
+        ? e.retries
+        : Math.max(0, job.retries - 1);
+    const message = e instanceof Error ? e.message : String(e);
+    session.failJob(job.key, retries, message);
+    return;
+  }
+  // An engine command failure (invalid JSON the engine rejects, ABI mismatch,
+  // internal engine error) is a real problem, not a handler failure — masking
+  // it as `failJob` would hide the bug and mutate engine state incorrectly, so
+  // we let it bubble to the caller.
+  session.completeJob(job.key, payload);
+}
+
+/**
+ * Run one activate-and-handle pass: activate every registered job type's
+ * currently-`Created` jobs *first* (a snapshot of the token frontier), then hand
+ * each to its handler (complete on return, fail on throw). Jobs a handler
+ * unblocks downstream are deliberately *not* chased within the same round — they
+ * belong to the next frontier — so one round advances every live token by
+ * exactly one step. That makes this the animatable unit: drive it on a timer to
+ * watch the token(s) hop task-to-task. {@link dispatchWorkers} loops it to
+ * quiescence.
+ */
+export async function dispatchRound(
+  session: BojtosSession,
+  workers: Record<string, JobHandler>,
+  opts: DispatchOptions = {},
+): Promise<RoundResult> {
+  const maxJobs = opts.maxJobsPerActivation ?? 10;
+  const timeout = opts.lockTimeoutMs ?? 30_000;
+  const worker = opts.worker ?? "bojtos";
+  // Activation pass: lock the whole current frontier before running any handler,
+  // so a job a handler unblocks isn't also picked up this round (which would
+  // cascade the entire chain in a single "step").
+  const batch: { handler: JobHandler; job: ActivatedJob }[] = [];
+  for (const [jobType, handler] of Object.entries(workers)) {
+    for (const job of session.activateJobs(jobType, maxJobs, timeout, worker)) {
+      batch.push({ handler, job });
+    }
+  }
+  // Handle pass.
+  for (const { handler, job } of batch) {
+    await runOne(session, handler, job);
+  }
+  return { snapshot: session.snapshot(), handled: batch.length };
+}
+
+/**
+ * Drive an in-browser worker loop over a {@link BojtosSession}: repeatedly
+ * {@link dispatchRound} until a round handles nothing, so a whole process runs
+ * to quiescence in one call. Job types with no registered handler are simply
+ * left waiting.
+ *
+ * This is the dispatch half of the Bojtos runtime (ADR 0043 §8 step 3) — the
+ * "activate → JS handler → complete/fail" loop that makes the token move and the
+ * variable payload mutate as workers run.
+ */
+export async function dispatchWorkers(
+  session: BojtosSession,
+  workers: Record<string, JobHandler>,
+  opts: DispatchOptions = {},
+): Promise<DispatchResult> {
+  const maxRounds = opts.maxRounds ?? 1000;
+  let handled = 0;
+  let rounds = 0;
+  for (;;) {
+    if (rounds >= maxRounds) {
+      throw new Error(
+        `dispatchWorkers exceeded maxRounds (${maxRounds}) — a handler may be creating work without end`,
+      );
+    }
+    rounds++;
+    const round = await dispatchRound(session, workers, opts);
+    handled += round.handled;
+    if (round.handled === 0) {
+      return { snapshot: round.snapshot, handled, rounds };
+    }
+  }
+}