@nanobpm/bojtos-kit 0.5.0 → 0.7.0

package/README.md

@@ -27,6 +27,61 @@ Every command returns the post-run `Snapshot`: `activeElementIds` /
 For React, use [`@nanobpm/bojtos-react`](../bojtos-react), which owns the session
 lifecycle and reactive state on top of this kit.
 
+## Engine variants — `lean` (default) and `readmodel`
+
+`@nanobpm/engine-wasm` ships two binaries; a session picks one via `variant`:
+
+- **`lean`** (default) — primary state only. Read it through `snapshot()` /
+  `events()`. Loaded statically, so every consumer bundles it.
+- **`readmodel`** — the lean surface **plus** the gateway's Camunda-parity REST
+  read channel. Loaded via a **dynamic import**, so a lean-only page never
+  downloads the heavier read-model binary (wasm can't be tree-shaken out of a
+  single build — code-splitting is the only lever).
+
+```ts
+import {
+  createBojtosSession,
+  type UserTaskSearchQueryResult,
+} from "@nanobpm/bojtos-kit";
+
+// `variant: "readmodel"` widens the return type to `ReadModelBojtosSession`:
+const session = await createBojtosSession({ variant: "readmodel" });
+session.deploy(bpmnXml);
+session.createInstance("review", "{}");
+
+// Typed against @nanobpm/engine-wasm/readmodel-types (re-exported here):
+const open: UserTaskSearchQueryResult = session.searchUserTasks(
+  JSON.stringify({ state: "CREATED" }),
+);
+const form = session.getFormByKey("2251799813685250"); // FormResult | null
+```
+
+The read methods — `searchUserTasks`, `searchProcessInstances`,
+`searchVariables`, `getFormByKey`, `getResourceByKey` — return DTOs re-exported
+from `@nanobpm/engine-wasm/readmodel-types`, which are **derived** from the
+Camunda-parity REST OpenAPI (one source of truth, not a hand-copy).
+
+## Trace model
+
+The kit also holds the framework-agnostic **trace model** the shared
+`<TraceTimeline>` (in `@nanobpm/bojtos-react`) renders — one normalized
+row/turn-group model plus the two adapters that map a source into it, so the two
+formerly forked timelines share one fold instead of drifting apart:
+
+- **`foldEngineEvents(events)`** — the engine-event fold: a `WasmEvent[]` (from
+  `session.events()` / `useBojtos().events`) → normalized `TraceRow[]`, keeping the
+  run's milestones and dropping low-signal lifecycle noise. The non-agentic /
+  test-view case.
+- **`traceEntriesToRows(entries)`** — the handler-emitted adapter: agent/tool/turn
+  `TraceEntry` lines (with the additive `turn` grouping field) → `TraceRow[]`. The
+  agentic web-demo case.
+- **`buildTraceItems(rows)`** — folds consecutive same-`turn` rows into
+  `TraceTurnGroup`s; rows with no `turn` stay flat. `isTraceTurnGroup` narrows an
+  item. This is the grouping the view consumes.
+
+It is pure and React-free (no React import in the kit), keeping the presentational
+layer thin.
+
 ## Build
 
 `dist/` (the tsc-emitted JS + `.d.ts`) is what ships, built by `prepack` on

package/dist/index.d.ts

@@ -1,3 +1,6 @@
-export { ensureWasm, createBojtosSession, type BojtosSession, type WasmSource, } from "./session.js";
+export { ensureWasm, ensureReadModelWasm, createBojtosSession, type BojtosSession, type ReadModelBojtosSession, type EngineVariant, type WasmSource, } from "./session.js";
 export { dispatchWorkers, dispatchRound, settleReason, unhandledJobTypes, JobFailure, type JobHandler, type JobResult, type AgentHandler, type DispatchOptions, type DispatchResult, type RoundResult, type SettleReason, } from "./worker.js";
+export { buildTraceItems, isTraceTurnGroup, foldEngineEvents, traceEntriesToRows, } from "./trace.js";
+export type { TraceRowKind, TraceEntry, TraceRow, TraceTurnGroup, TraceItem, TraceAdapter, } from "./trace.js";
 export type { Snapshot, InstanceDto, JobDto, ActivatedJob, IncidentDto, TimerDto, UserTaskDto, MessageSubscriptionDto, SignalSubscriptionDto, ElementStatDto, SequenceFlowDto, DecisionInstanceDto, ActiveEl, ActivateInstruction, AgentActivation, AgentResult, WasmEvent, } from "./types.js";
+export type { UserTaskSearchQueryResult, UserTaskResult, ProcessInstanceSearchQueryResult, ProcessInstanceResult, VariableSearchQueryResult, VariableResult, FormResult, ResourceResult, SearchQueryResponse, SearchQueryPageResponse, } from "@nanobpm/engine-wasm/readmodel-types";

package/dist/index.js

@@ -1,5 +1,9 @@
 // @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 { ensureWasm, ensureReadModelWasm, createBojtosSession, } from "./session.js";
 export { dispatchWorkers, dispatchRound, settleReason, unhandledJobTypes, JobFailure, } from "./worker.js";
+// The shared trace model + both adapters (engine-event fold and handler-emitted
+// `TraceEntry`) that retired the two forked `TraceTimeline` copies (#9). Pure and
+// React-free — the presentational component lives in @nanobpm/bojtos-react.
+export { buildTraceItems, isTraceTurnGroup, foldEngineEvents, traceEntriesToRows, } from "./trace.js";

package/dist/session.d.ts

@@ -1,5 +1,23 @@
 import { type InitInput } from "@nanobpm/engine-wasm";
+import type { FormResult, ProcessInstanceSearchQueryResult, ResourceResult, UserTaskSearchQueryResult, VariableSearchQueryResult } from "@nanobpm/engine-wasm/readmodel-types";
 import type { ActivatedJob, ActivateInstruction, AgentResult, Snapshot, WasmEvent } from "./types.js";
+/**
+ * Which engine binary backs a session. The two are separate wasm builds
+ * (engine-wasm ships them at distinct subpaths, ADR 0043 §3 / engine-wasm
+ * README):
+ *
+ * - `"lean"` (default) — primary state only; the binary demos/the modeler use.
+ *   Loaded via the static `@nanobpm/engine-wasm` import, so a bundler emits it
+ *   for every bojtos-kit consumer.
+ * - `"readmodel"` — the lean surface **plus** the gateway's Camunda-parity REST
+ *   read channel (`searchUserTasks`/`searchProcessInstances`/`searchVariables`/
+ *   `getFormByKey`/`getResourceByKey`). It carries an in-memory wasm SQLite read
+ *   model (~2× the wire size), so it is loaded via a **dynamic import** — a
+ *   lean-only page never bundles it (wasm can't be tree-shaken out of a fat
+ *   build; code-splitting is the only lever).
+ */
+export type EngineVariant = "lean" | "readmodel";
+type ReadModelModule = typeof import("@nanobpm/engine-wasm/readmodel");
 /**
  * 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
@@ -20,6 +38,15 @@ export type WasmSource = InitInput;
  * the binary — can retry rather than being stuck on the first rejection.
  */
 export declare function ensureWasm(source?: WasmSource): Promise<void>;
+/**
+ * Load **and** initialise the read-model engine variant (idempotent; once per
+ * page). Unlike {@link ensureWasm} this also code-splits the binary in via a
+ * dynamic `import("@nanobpm/engine-wasm/readmodel")`, so a page that only ever
+ * calls {@link ensureWasm} never downloads the heavier read-model wasm. Same
+ * first-call-wins / retry-on-failure semantics as {@link ensureWasm}. Returns
+ * the module namespace so the caller can construct its `TestEngine`.
+ */
+export declare function ensureReadModelWasm(source?: WasmSource): Promise<ReadModelModule>;
 /**
  * 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
@@ -141,12 +168,66 @@ export interface BojtosSession {
     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
+ * A {@link BojtosSession} backed by the **read-model** engine variant: the full
+ * lean command surface **plus** the gateway's Camunda-parity REST read channel.
+ * Each read method delegates to the in-memory read model (kept current after
+ * every command, cleared by {@link BojtosSession.reset}) and returns the parsed
+ * DTO — typed against `@nanobpm/engine-wasm/readmodel-types`, which is derived
+ * from the same Camunda REST OpenAPI the wasm mirrors, so these stay in lockstep
+ * with the engine instead of being hand-copied. Obtain one via
+ * `createBojtosSession({ variant: "readmodel" })`.
+ */
+export interface ReadModelBojtosSession extends BojtosSession {
+    /**
+     * Search user tasks through the read model. Honours an optional `{ state? }`
+     * filter (e.g. `"CREATED"`). Mirrors `POST /user-tasks/search`.
+     */
+    searchUserTasks(filterJson?: string): UserTaskSearchQueryResult;
+    /**
+     * Search process instances through the read model. Body is shape-validated;
+     * filter/sort/page fields are not yet honoured (returns every instance).
+     * Mirrors `POST /process-instances/search`.
+     */
+    searchProcessInstances(filterJson?: string): ProcessInstanceSearchQueryResult;
+    /**
+     * Search variables through the read model. Long values are truncated with
+     * `isTruncated: true`. Mirrors `POST /variables/search`.
+     */
+    searchVariables(filterJson?: string): VariableSearchQueryResult;
+    /**
+     * The latest deployed form for `formKey`, or `null` if none. Mirrors
+     * `GET /forms/{formKey}`.
+     */
+    getFormByKey(formKey: string): FormResult | null;
+    /**
+     * The generic resource for `resourceKey`, or `null` if none. Mirrors
+     * `GET /resources/{resourceKey}`.
+     */
+    getResourceByKey(resourceKey: string): ResourceResult | null;
+}
+/**
+ * Create a fresh headless engine session. Ensures the chosen wasm variant is
+ * loaded (once per page), then constructs a new `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).
+ *
+ * With `variant: "readmodel"` the returned session also exposes the gateway's
+ * REST read channel (typed {@link ReadModelBojtosSession}); the default `"lean"`
+ * variant is state-only and never downloads the heavier read-model binary. A
+ * statically-`"readmodel"` variant widens the return type; a value only known as
+ * the `EngineVariant` union resolves to the base {@link BojtosSession}.
  */
 export declare function createBojtosSession(opts?: {
     wasm?: WasmSource;
+    variant?: "lean";
+}): Promise<BojtosSession>;
+export declare function createBojtosSession(opts: {
+    wasm?: WasmSource;
+    variant: "readmodel";
+}): Promise<ReadModelBojtosSession>;
+export declare function createBojtosSession(opts: {
+    wasm?: WasmSource;
+    variant: EngineVariant;
 }): Promise<BojtosSession>;
+export {};

package/dist/session.js

@@ -1,7 +1,9 @@
 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`.
+// sessions are created. Mirrors the console's original `ensureWasm`. The two
+// variants init independently (a page may use either or both).
 let wasmReady = null;
+let readModelReady = 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
@@ -24,6 +26,28 @@ export function ensureWasm(source) {
     }
     return wasmReady;
 }
+/**
+ * Load **and** initialise the read-model engine variant (idempotent; once per
+ * page). Unlike {@link ensureWasm} this also code-splits the binary in via a
+ * dynamic `import("@nanobpm/engine-wasm/readmodel")`, so a page that only ever
+ * calls {@link ensureWasm} never downloads the heavier read-model wasm. Same
+ * first-call-wins / retry-on-failure semantics as {@link ensureWasm}. Returns
+ * the module namespace so the caller can construct its `TestEngine`.
+ */
+export function ensureReadModelWasm(source) {
+    if (!readModelReady) {
+        readModelReady = import("@nanobpm/engine-wasm/readmodel")
+            .then(async (mod) => {
+            await mod.default(source === undefined ? undefined : { module_or_path: source });
+            return mod;
+        })
+            .catch((e) => {
+            readModelReady = null;
+            throw e;
+        });
+    }
+    return readModelReady;
+}
 function parseSnapshot(json) {
     // The wasm engine is the schema authority; its JSON is the contract boundary.
     return JSON.parse(json);
@@ -104,14 +128,38 @@ class WasmBojtosSession {
         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).
- */
+class WasmReadModelSession extends WasmBojtosSession {
+    // The read-model engine is a structural superset of the lean `TestEngine`
+    // (identical command surface + the 5 read methods), so it satisfies the base
+    // constructor while we keep our own read-model-typed reference for the read
+    // channel — no casts, so a future divergence in the shared surface is a
+    // compile error rather than a runtime one.
+    rm;
+    constructor(engine) {
+        super(engine);
+        this.rm = engine;
+    }
+    searchUserTasks(filterJson = "{}") {
+        return JSON.parse(this.rm.searchUserTasks(filterJson || "{}"));
+    }
+    searchProcessInstances(filterJson = "{}") {
+        return JSON.parse(this.rm.searchProcessInstances(filterJson || "{}"));
+    }
+    searchVariables(filterJson = "{}") {
+        return JSON.parse(this.rm.searchVariables(filterJson || "{}"));
+    }
+    getFormByKey(formKey) {
+        return JSON.parse(this.rm.getFormByKey(formKey));
+    }
+    getResourceByKey(resourceKey) {
+        return JSON.parse(this.rm.getResourceByKey(resourceKey));
+    }
+}
 export async function createBojtosSession(opts) {
+    if (opts?.variant === "readmodel") {
+        const mod = await ensureReadModelWasm(opts.wasm);
+        return new WasmReadModelSession(new mod.TestEngine());
+    }
     await ensureWasm(opts?.wasm);
     return new WasmBojtosSession(new TestEngine());
 }

package/dist/trace.d.ts

@@ -0,0 +1,97 @@
+import type { WasmEvent } from "./types.js";
+/**
+ * Semantic classification of a trace row, driving how the view styles it (the
+ * `log-<kind>` class the two forked timelines already keyed off) and which
+ * affordance it carries. Framework-agnostic — an engine-event fold and an
+ * agentic handler stream both land in this shared vocabulary:
+ *
+ * - `start` — the run/instance began.
+ * - `agent` — an agent decision, or a tool the agent activated this turn.
+ * - `llm`   — a raw model reply.
+ * - `tool`  — a tool/handler log line (a job running, a timer, a message).
+ * - `human` — a user task awaiting or completed by a person.
+ * - `done`  — the final outcome (the instance completed/terminated).
+ * - `error` — a failure, incident, or thrown error.
+ * - `vars`  — a variables/result update (e.g. what a tool returned).
+ */
+export type TraceRowKind = "start" | "agent" | "llm" | "tool" | "human" | "done" | "error" | "vars";
+/**
+ * A source line before it is placed in the normalized model. This is the shape a
+ * handler emits (the web-demo framework's `TraceEntry`): `kind`/`text` are all a
+ * plain consumer needs; every other field is additive and safe to ignore.
+ */
+export interface TraceEntry {
+    kind: TraceRowKind;
+    /** The human-readable line. */
+    text: string;
+    /**
+     * Stable id for an entry that updates in place — a streaming completion grows
+     * one line rather than spamming forty.
+     */
+    key?: string;
+    /** True while the entry is still being produced (renders a spinner). */
+    pending?: boolean;
+    /**
+     * Groups every entry produced by one agent turn together (the streamed LLM
+     * reply, each tool it activated, and that tool's result). Consecutive entries
+     * sharing a `turn` fold into one turn card; entries with no `turn` render as
+     * plain rows in their original order.
+     */
+    turn?: number;
+    /** The BPMN element (tool or task) this entry concerns. */
+    elementId?: string;
+    /** Arguments supplied when activating a tool — the coerced values, not the raw reply. */
+    args?: Record<string, unknown>;
+    /** What a tool/handler returned, paired with its activation by `elementId`. */
+    result?: unknown;
+}
+/**
+ * A normalized row: a {@link TraceEntry} stamped with a stable, monotonic `id`.
+ * The `id` is what the view keys off and what pairs a tool's result with its
+ * activation and orders loose lines within a turn.
+ */
+export interface TraceRow extends TraceEntry {
+    id: number;
+}
+/** Consecutive same-turn rows, folded into one group by {@link buildTraceItems}. */
+export interface TraceTurnGroup {
+    turn: number;
+    rows: TraceRow[];
+}
+/** A top-level item the view renders: either a plain row or a turn group. */
+export type TraceItem = TraceRow | TraceTurnGroup;
+/** Narrow a {@link TraceItem} to a {@link TraceTurnGroup}. */
+export declare function isTraceTurnGroup(item: TraceItem): item is TraceTurnGroup;
+/**
+ * An adapter maps a source (`WasmEvent[]`, a `TraceEntry[]`, …) into the shared
+ * normalized row model. Both built-in adapters — {@link foldEngineEvents} and
+ * {@link traceEntriesToRows} — satisfy this; a consumer can supply its own for a
+ * bespoke source.
+ */
+export type TraceAdapter<TSource> = (source: TSource) => TraceRow[];
+/**
+ * Fold a flat list of normalized rows into the view model: consecutive rows
+ * sharing a `turn` become one {@link TraceTurnGroup}; everything else stays a
+ * plain row in its original order. A row with no `turn` breaks the current group,
+ * so an interleaved non-turn line never gets swallowed into a card. This is the
+ * grouping both forked timelines did by hand, lifted into the shared kit.
+ */
+export declare function buildTraceItems(rows: TraceRow[]): TraceItem[];
+/**
+ * The handler-emitted `TraceEntry` adapter: stamp each entry with a stable `id`
+ * (its index) to lift it into a {@link TraceRow}. The entries already carry the
+ * additive `turn`/`elementId`/`args`/`result` fields, so {@link buildTraceItems}
+ * over the result reproduces the agentic turn-grouped card view without any
+ * re-forked grouping logic. The input is never mutated.
+ */
+export declare function traceEntriesToRows(entries: readonly TraceEntry[]): TraceRow[];
+/**
+ * The engine-event fold adapter: map a `WasmEvent[]` (the flattened
+ * `{ seq, now, type, …snake_case }` stream from `useBojtos().events`) into
+ * normalized rows, keeping only the meaningful milestones (see
+ * {@link ENGINE_EVENT_RULES}). Each row's `id` is the event's `seq`, so ids stay
+ * stable and monotonic across re-reads of a growing log. Engine events carry no
+ * turn, so {@link buildTraceItems} over the result is a flat list of rows — the
+ * non-agentic test-view shape.
+ */
+export declare function foldEngineEvents(events: readonly WasmEvent[]): TraceRow[];

package/dist/trace.js

@@ -0,0 +1,185 @@
+// The framework-agnostic trace model shared by the Bojtos demo framework and the
+// console test-view — the single source that retired the two drifted, forked
+// `TraceTimeline` copies (nanobpm/bojtos#9). It defines one normalized row/turn
+// model plus the two adapters that map a source into it:
+//
+//   1. the **engine-event fold** — `WasmEvent[]` (from `useBojtos().events`) →
+//      rows, covering the non-agentic / test-view case; and
+//   2. the **handler-emitted `TraceEntry`** adapter — the agent/tool/turn entries
+//      (with the additive `turn` grouping field) → rows, covering the agentic
+//      web-demo case.
+//
+// It is deliberately React-free: the presentational component (`TraceTimeline` in
+// `@nanobpm/bojtos-react`) renders this model, keeping the view layer thin.
+/** Narrow a {@link TraceItem} to a {@link TraceTurnGroup}. */
+export function isTraceTurnGroup(item) {
+    return item.rows !== undefined;
+}
+/**
+ * Fold a flat list of normalized rows into the view model: consecutive rows
+ * sharing a `turn` become one {@link TraceTurnGroup}; everything else stays a
+ * plain row in its original order. A row with no `turn` breaks the current group,
+ * so an interleaved non-turn line never gets swallowed into a card. This is the
+ * grouping both forked timelines did by hand, lifted into the shared kit.
+ */
+export function buildTraceItems(rows) {
+    const items = [];
+    let current = null;
+    for (const row of rows) {
+        if (row.turn !== undefined) {
+            if (current && current.turn === row.turn) {
+                current.rows.push(row);
+            }
+            else {
+                current = { turn: row.turn, rows: [row] };
+                items.push(current);
+            }
+        }
+        else {
+            current = null;
+            items.push(row);
+        }
+    }
+    return items;
+}
+/**
+ * The handler-emitted `TraceEntry` adapter: stamp each entry with a stable `id`
+ * (its index) to lift it into a {@link TraceRow}. The entries already carry the
+ * additive `turn`/`elementId`/`args`/`result` fields, so {@link buildTraceItems}
+ * over the result reproduces the agentic turn-grouped card view without any
+ * re-forked grouping logic. The input is never mutated.
+ */
+export function traceEntriesToRows(entries) {
+    return entries.map((entry, id) => ({ ...entry, id }));
+}
+/** Read a string field off a `WasmEvent`'s open payload, or `undefined`. */
+function str(ev, key) {
+    const v = ev[key];
+    return typeof v === "string" ? v : undefined;
+}
+/** The element this event concerns, if it names one — for pairing/labelling. */
+function elementOf(ev) {
+    return str(ev, "element_id");
+}
+const ENGINE_EVENT_RULES = {
+    ProcessInstanceCreated: {
+        kind: "start",
+        text: (ev) => `Process ${str(ev, "process_id") ?? "instance"} started`,
+    },
+    JobCreated: {
+        kind: "tool",
+        text: (ev) => `Job ${str(ev, "job_type") ?? ""} created`.trim() +
+            (elementOf(ev) ? ` on ${elementOf(ev)}` : ""),
+    },
+    JobCompleted: {
+        kind: "vars",
+        text: (ev) => `Job ${str(ev, "job_type") ?? ""} completed`.trim(),
+    },
+    JobFailed: {
+        kind: "error",
+        text: (ev) => `Job ${str(ev, "job_type") ?? ""} failed`.trim(),
+    },
+    JobErrorThrown: {
+        kind: "error",
+        text: (ev) => `Job threw error ${str(ev, "error_code") ?? ""}`.trim() +
+            (elementOf(ev) ? ` on ${elementOf(ev)}` : ""),
+    },
+    IncidentRaised: {
+        kind: "error",
+        text: (ev) => `Incident on ${elementOf(ev) ?? "instance"}` +
+            (str(ev, "reason") ? `: ${str(ev, "reason")}` : ""),
+    },
+    IncidentResolved: {
+        kind: "tool",
+        text: (ev) => `Incident resolved on ${elementOf(ev) ?? "instance"}`,
+    },
+    UserTaskCreated: {
+        kind: "human",
+        text: (ev) => `User task ${elementOf(ev) ?? ""} awaiting a human`.trim(),
+    },
+    UserTaskAssigned: {
+        kind: "human",
+        text: (ev) => `User task ${elementOf(ev) ?? ""} assigned`.trim() +
+            (str(ev, "assignee") ? ` to ${str(ev, "assignee")}` : ""),
+    },
+    UserTaskCompleted: {
+        kind: "human",
+        text: (ev) => `User task ${elementOf(ev) ?? ""} completed`.trim(),
+    },
+    UserTaskCanceled: {
+        kind: "human",
+        text: (ev) => `User task ${elementOf(ev) ?? ""} canceled`.trim(),
+    },
+    TimerCreated: {
+        kind: "tool",
+        text: (ev) => `Timer set on ${elementOf(ev) ?? "instance"}`,
+    },
+    TimerTriggered: {
+        kind: "tool",
+        text: (ev) => `Timer fired on ${elementOf(ev) ?? "instance"}`,
+    },
+    MessagePublished: {
+        kind: "tool",
+        text: (ev) => `Message ${str(ev, "message_name") ?? ""} published`.trim(),
+    },
+    MessageCorrelated: {
+        kind: "tool",
+        text: (ev) => `Message ${str(ev, "message_name") ?? ""} correlated`.trim(),
+    },
+    SignalBroadcast: {
+        kind: "tool",
+        text: (ev) => `Signal ${str(ev, "signal_name") ?? ""} broadcast`.trim(),
+    },
+    SignalCorrelated: {
+        kind: "tool",
+        text: (ev) => `Signal ${str(ev, "signal_name") ?? ""} correlated`.trim(),
+    },
+    AdHocActivated: {
+        kind: "agent",
+        text: (ev) => `Ad-hoc sub-process ${elementOf(ev) ?? ""} activated`.trim(),
+    },
+    AdHocToolActivated: {
+        kind: "agent",
+        text: (ev) => `Tool ${elementOf(ev) ?? ""} activated`.trim(),
+    },
+    AdHocToolCompleted: {
+        kind: "vars",
+        text: (ev) => `Tool ${elementOf(ev) ?? ""} returned`.trim(),
+    },
+    AdHocCompleted: {
+        kind: "agent",
+        text: (ev) => `Ad-hoc sub-process ${elementOf(ev) ?? ""} completed`.trim(),
+    },
+    ProcessInstanceCompleted: {
+        kind: "done",
+        text: () => "Process completed",
+    },
+    ProcessInstanceTerminated: {
+        kind: "error",
+        text: () => "Process terminated",
+    },
+};
+/**
+ * The engine-event fold adapter: map a `WasmEvent[]` (the flattened
+ * `{ seq, now, type, …snake_case }` stream from `useBojtos().events`) into
+ * normalized rows, keeping only the meaningful milestones (see
+ * {@link ENGINE_EVENT_RULES}). Each row's `id` is the event's `seq`, so ids stay
+ * stable and monotonic across re-reads of a growing log. Engine events carry no
+ * turn, so {@link buildTraceItems} over the result is a flat list of rows — the
+ * non-agentic test-view shape.
+ */
+export function foldEngineEvents(events) {
+    const rows = [];
+    for (const ev of events) {
+        const rule = ENGINE_EVENT_RULES[ev.type];
+        if (!rule)
+            continue;
+        rows.push({
+            id: ev.seq,
+            kind: rule.kind,
+            text: rule.text(ev),
+            elementId: elementOf(ev),
+        });
+    }
+    return rows;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/bojtos-kit",
-  "version": "0.5.0",
+  "version": "0.7.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",
@@ -32,7 +32,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@nanobpm/engine-wasm": "^0.3.0"
+    "@nanobpm/engine-wasm": "^0.7.0"
   },
   "devDependencies": {
     "typescript": "^5.6.3"

package/src/index.ts

@@ -4,8 +4,11 @@
 
 export {
   ensureWasm,
+  ensureReadModelWasm,
   createBojtosSession,
   type BojtosSession,
+  type ReadModelBojtosSession,
+  type EngineVariant,
   type WasmSource,
 } from "./session.js";
 export {
@@ -22,6 +25,23 @@ export {
   type RoundResult,
   type SettleReason,
 } from "./worker.js";
+// The shared trace model + both adapters (engine-event fold and handler-emitted
+// `TraceEntry`) that retired the two forked `TraceTimeline` copies (#9). Pure and
+// React-free — the presentational component lives in @nanobpm/bojtos-react.
+export {
+  buildTraceItems,
+  isTraceTurnGroup,
+  foldEngineEvents,
+  traceEntriesToRows,
+} from "./trace.js";
+export type {
+  TraceRowKind,
+  TraceEntry,
+  TraceRow,
+  TraceTurnGroup,
+  TraceItem,
+  TraceAdapter,
+} from "./trace.js";
 // Every type reachable from `Snapshot` is exported: a consumer that can read
 // `snapshot.userTasks` must also be able to name `UserTaskDto` to write a
 // helper for it. Keep this list exhaustive when adding to `types.ts`.
@@ -44,3 +64,20 @@ export type {
   AgentResult,
   WasmEvent,
 } from "./types.js";
+// The read-model query-result DTOs, re-exported from
+// `@nanobpm/engine-wasm/readmodel-types` (derived from the Camunda-parity REST
+// OpenAPI — a single source of truth, not a hand-copy). A consumer that reads a
+// `ReadModelBojtosSession`'s `searchUserTasks()` / `getFormByKey()` return must
+// be able to name these to write helpers over them.
+export type {
+  UserTaskSearchQueryResult,
+  UserTaskResult,
+  ProcessInstanceSearchQueryResult,
+  ProcessInstanceResult,
+  VariableSearchQueryResult,
+  VariableResult,
+  FormResult,
+  ResourceResult,
+  SearchQueryResponse,
+  SearchQueryPageResponse,
+} from "@nanobpm/engine-wasm/readmodel-types";

package/src/session.ts

@@ -1,4 +1,11 @@
 import init, { type InitInput, TestEngine } from "@nanobpm/engine-wasm";
+import type {
+  FormResult,
+  ProcessInstanceSearchQueryResult,
+  ResourceResult,
+  UserTaskSearchQueryResult,
+  VariableSearchQueryResult,
+} from "@nanobpm/engine-wasm/readmodel-types";
 import type {
   ActivatedJob,
   ActivateInstruction,
@@ -7,9 +14,35 @@ import type {
   WasmEvent,
 } from "./types.js";
 
+/**
+ * Which engine binary backs a session. The two are separate wasm builds
+ * (engine-wasm ships them at distinct subpaths, ADR 0043 §3 / engine-wasm
+ * README):
+ *
+ * - `"lean"` (default) — primary state only; the binary demos/the modeler use.
+ *   Loaded via the static `@nanobpm/engine-wasm` import, so a bundler emits it
+ *   for every bojtos-kit consumer.
+ * - `"readmodel"` — the lean surface **plus** the gateway's Camunda-parity REST
+ *   read channel (`searchUserTasks`/`searchProcessInstances`/`searchVariables`/
+ *   `getFormByKey`/`getResourceByKey`). It carries an in-memory wasm SQLite read
+ *   model (~2× the wire size), so it is loaded via a **dynamic import** — a
+ *   lean-only page never bundles it (wasm can't be tree-shaken out of a fat
+ *   build; code-splitting is the only lever).
+ */
+export type EngineVariant = "lean" | "readmodel";
+
+// Type-only view of the read-model module so we can name its `TestEngine`
+// (a distinct wasm-bindgen class from lean's, with the +5 read methods) without
+// statically importing the heavy binary — the runtime handle is fetched lazily
+// by `ensureReadModelWasm`'s dynamic `import()`.
+type ReadModelModule = typeof import("@nanobpm/engine-wasm/readmodel");
+type ReadModelEngine = InstanceType<ReadModelModule["TestEngine"]>;
+
 // Lazily initialise the wasm module exactly once per page, no matter how many
-// sessions are created. Mirrors the console's original `ensureWasm`.
+// sessions are created. Mirrors the console's original `ensureWasm`. The two
+// variants init independently (a page may use either or both).
 let wasmReady: Promise<void> | null = null;
+let readModelReady: Promise<ReadModelModule> | null = null;
 
 /**
  * The source of the engine wasm binary. Under a bundler that understands
@@ -45,6 +78,33 @@ export function ensureWasm(source?: WasmSource): Promise<void> {
   return wasmReady;
 }
 
+/**
+ * Load **and** initialise the read-model engine variant (idempotent; once per
+ * page). Unlike {@link ensureWasm} this also code-splits the binary in via a
+ * dynamic `import("@nanobpm/engine-wasm/readmodel")`, so a page that only ever
+ * calls {@link ensureWasm} never downloads the heavier read-model wasm. Same
+ * first-call-wins / retry-on-failure semantics as {@link ensureWasm}. Returns
+ * the module namespace so the caller can construct its `TestEngine`.
+ */
+export function ensureReadModelWasm(
+  source?: WasmSource,
+): Promise<ReadModelModule> {
+  if (!readModelReady) {
+    readModelReady = import("@nanobpm/engine-wasm/readmodel")
+      .then(async (mod) => {
+        await mod.default(
+          source === undefined ? undefined : { module_or_path: source },
+        );
+        return mod;
+      })
+      .catch((e) => {
+        readModelReady = null;
+        throw e;
+      });
+  }
+  return readModelReady;
+}
+
 /**
  * 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
@@ -185,13 +245,52 @@ export interface BojtosSession {
   free(): void;
 }
 
+/**
+ * A {@link BojtosSession} backed by the **read-model** engine variant: the full
+ * lean command surface **plus** the gateway's Camunda-parity REST read channel.
+ * Each read method delegates to the in-memory read model (kept current after
+ * every command, cleared by {@link BojtosSession.reset}) and returns the parsed
+ * DTO — typed against `@nanobpm/engine-wasm/readmodel-types`, which is derived
+ * from the same Camunda REST OpenAPI the wasm mirrors, so these stay in lockstep
+ * with the engine instead of being hand-copied. Obtain one via
+ * `createBojtosSession({ variant: "readmodel" })`.
+ */
+export interface ReadModelBojtosSession extends BojtosSession {
+  /**
+   * Search user tasks through the read model. Honours an optional `{ state? }`
+   * filter (e.g. `"CREATED"`). Mirrors `POST /user-tasks/search`.
+   */
+  searchUserTasks(filterJson?: string): UserTaskSearchQueryResult;
+  /**
+   * Search process instances through the read model. Body is shape-validated;
+   * filter/sort/page fields are not yet honoured (returns every instance).
+   * Mirrors `POST /process-instances/search`.
+   */
+  searchProcessInstances(filterJson?: string): ProcessInstanceSearchQueryResult;
+  /**
+   * Search variables through the read model. Long values are truncated with
+   * `isTruncated: true`. Mirrors `POST /variables/search`.
+   */
+  searchVariables(filterJson?: string): VariableSearchQueryResult;
+  /**
+   * The latest deployed form for `formKey`, or `null` if none. Mirrors
+   * `GET /forms/{formKey}`.
+   */
+  getFormByKey(formKey: string): FormResult | null;
+  /**
+   * The generic resource for `resourceKey`, or `null` if none. Mirrors
+   * `GET /resources/{resourceKey}`.
+   */
+  getResourceByKey(resourceKey: string): ResourceResult | null;
+}
+
 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;
+  protected readonly engine: TestEngine;
 
   constructor(engine: TestEngine) {
     this.engine = engine;
@@ -350,16 +449,84 @@ class WasmBojtosSession implements BojtosSession {
   }
 }
 
+class WasmReadModelSession
+  extends WasmBojtosSession
+  implements ReadModelBojtosSession
+{
+  // The read-model engine is a structural superset of the lean `TestEngine`
+  // (identical command surface + the 5 read methods), so it satisfies the base
+  // constructor while we keep our own read-model-typed reference for the read
+  // channel — no casts, so a future divergence in the shared surface is a
+  // compile error rather than a runtime one.
+  private readonly rm: ReadModelEngine;
+
+  constructor(engine: ReadModelEngine) {
+    super(engine);
+    this.rm = engine;
+  }
+
+  searchUserTasks(filterJson = "{}"): UserTaskSearchQueryResult {
+    return JSON.parse(
+      this.rm.searchUserTasks(filterJson || "{}"),
+    ) as UserTaskSearchQueryResult;
+  }
+
+  searchProcessInstances(filterJson = "{}"): ProcessInstanceSearchQueryResult {
+    return JSON.parse(
+      this.rm.searchProcessInstances(filterJson || "{}"),
+    ) as ProcessInstanceSearchQueryResult;
+  }
+
+  searchVariables(filterJson = "{}"): VariableSearchQueryResult {
+    return JSON.parse(
+      this.rm.searchVariables(filterJson || "{}"),
+    ) as VariableSearchQueryResult;
+  }
+
+  getFormByKey(formKey: string): FormResult | null {
+    return JSON.parse(this.rm.getFormByKey(formKey)) as FormResult | null;
+  }
+
+  getResourceByKey(resourceKey: string): ResourceResult | null {
+    return JSON.parse(
+      this.rm.getResourceByKey(resourceKey),
+    ) as ResourceResult | null;
+  }
+}
+
 /**
- * Create a fresh headless engine session. Ensures the wasm module is loaded
- * (once per page), then constructs a new {@link TestEngine}. The virtual clock
+ * Create a fresh headless engine session. Ensures the chosen wasm variant is
+ * loaded (once per page), then constructs a new `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).
+ *
+ * With `variant: "readmodel"` the returned session also exposes the gateway's
+ * REST read channel (typed {@link ReadModelBojtosSession}); the default `"lean"`
+ * variant is state-only and never downloads the heavier read-model binary. A
+ * statically-`"readmodel"` variant widens the return type; a value only known as
+ * the `EngineVariant` union resolves to the base {@link BojtosSession}.
  */
 export async function createBojtosSession(opts?: {
   wasm?: WasmSource;
+  variant?: "lean";
+}): Promise<BojtosSession>;
+export async function createBojtosSession(opts: {
+  wasm?: WasmSource;
+  variant: "readmodel";
+}): Promise<ReadModelBojtosSession>;
+export async function createBojtosSession(opts: {
+  wasm?: WasmSource;
+  variant: EngineVariant;
+}): Promise<BojtosSession>;
+export async function createBojtosSession(opts?: {
+  wasm?: WasmSource;
+  variant?: EngineVariant;
 }): Promise<BojtosSession> {
+  if (opts?.variant === "readmodel") {
+    const mod = await ensureReadModelWasm(opts.wasm);
+    return new WasmReadModelSession(new mod.TestEngine());
+  }
   await ensureWasm(opts?.wasm);
   return new WasmBojtosSession(new TestEngine());
 }

package/src/trace.ts

@@ -0,0 +1,291 @@
+// The framework-agnostic trace model shared by the Bojtos demo framework and the
+// console test-view — the single source that retired the two drifted, forked
+// `TraceTimeline` copies (nanobpm/bojtos#9). It defines one normalized row/turn
+// model plus the two adapters that map a source into it:
+//
+//   1. the **engine-event fold** — `WasmEvent[]` (from `useBojtos().events`) →
+//      rows, covering the non-agentic / test-view case; and
+//   2. the **handler-emitted `TraceEntry`** adapter — the agent/tool/turn entries
+//      (with the additive `turn` grouping field) → rows, covering the agentic
+//      web-demo case.
+//
+// It is deliberately React-free: the presentational component (`TraceTimeline` in
+// `@nanobpm/bojtos-react`) renders this model, keeping the view layer thin.
+
+import type { WasmEvent } from "./types.js";
+
+/**
+ * Semantic classification of a trace row, driving how the view styles it (the
+ * `log-<kind>` class the two forked timelines already keyed off) and which
+ * affordance it carries. Framework-agnostic — an engine-event fold and an
+ * agentic handler stream both land in this shared vocabulary:
+ *
+ * - `start` — the run/instance began.
+ * - `agent` — an agent decision, or a tool the agent activated this turn.
+ * - `llm`   — a raw model reply.
+ * - `tool`  — a tool/handler log line (a job running, a timer, a message).
+ * - `human` — a user task awaiting or completed by a person.
+ * - `done`  — the final outcome (the instance completed/terminated).
+ * - `error` — a failure, incident, or thrown error.
+ * - `vars`  — a variables/result update (e.g. what a tool returned).
+ */
+export type TraceRowKind =
+  | "start"
+  | "agent"
+  | "llm"
+  | "tool"
+  | "human"
+  | "done"
+  | "error"
+  | "vars";
+
+/**
+ * A source line before it is placed in the normalized model. This is the shape a
+ * handler emits (the web-demo framework's `TraceEntry`): `kind`/`text` are all a
+ * plain consumer needs; every other field is additive and safe to ignore.
+ */
+export interface TraceEntry {
+  kind: TraceRowKind;
+  /** The human-readable line. */
+  text: string;
+  /**
+   * Stable id for an entry that updates in place — a streaming completion grows
+   * one line rather than spamming forty.
+   */
+  key?: string;
+  /** True while the entry is still being produced (renders a spinner). */
+  pending?: boolean;
+  /**
+   * Groups every entry produced by one agent turn together (the streamed LLM
+   * reply, each tool it activated, and that tool's result). Consecutive entries
+   * sharing a `turn` fold into one turn card; entries with no `turn` render as
+   * plain rows in their original order.
+   */
+  turn?: number;
+  /** The BPMN element (tool or task) this entry concerns. */
+  elementId?: string;
+  /** Arguments supplied when activating a tool — the coerced values, not the raw reply. */
+  args?: Record<string, unknown>;
+  /** What a tool/handler returned, paired with its activation by `elementId`. */
+  result?: unknown;
+}
+
+/**
+ * A normalized row: a {@link TraceEntry} stamped with a stable, monotonic `id`.
+ * The `id` is what the view keys off and what pairs a tool's result with its
+ * activation and orders loose lines within a turn.
+ */
+export interface TraceRow extends TraceEntry {
+  id: number;
+}
+
+/** Consecutive same-turn rows, folded into one group by {@link buildTraceItems}. */
+export interface TraceTurnGroup {
+  turn: number;
+  rows: TraceRow[];
+}
+
+/** A top-level item the view renders: either a plain row or a turn group. */
+export type TraceItem = TraceRow | TraceTurnGroup;
+
+/** Narrow a {@link TraceItem} to a {@link TraceTurnGroup}. */
+export function isTraceTurnGroup(item: TraceItem): item is TraceTurnGroup {
+  return (item as TraceTurnGroup).rows !== undefined;
+}
+
+/**
+ * An adapter maps a source (`WasmEvent[]`, a `TraceEntry[]`, …) into the shared
+ * normalized row model. Both built-in adapters — {@link foldEngineEvents} and
+ * {@link traceEntriesToRows} — satisfy this; a consumer can supply its own for a
+ * bespoke source.
+ */
+export type TraceAdapter<TSource> = (source: TSource) => TraceRow[];
+
+/**
+ * Fold a flat list of normalized rows into the view model: consecutive rows
+ * sharing a `turn` become one {@link TraceTurnGroup}; everything else stays a
+ * plain row in its original order. A row with no `turn` breaks the current group,
+ * so an interleaved non-turn line never gets swallowed into a card. This is the
+ * grouping both forked timelines did by hand, lifted into the shared kit.
+ */
+export function buildTraceItems(rows: TraceRow[]): TraceItem[] {
+  const items: TraceItem[] = [];
+  let current: TraceTurnGroup | null = null;
+  for (const row of rows) {
+    if (row.turn !== undefined) {
+      if (current && current.turn === row.turn) {
+        current.rows.push(row);
+      } else {
+        current = { turn: row.turn, rows: [row] };
+        items.push(current);
+      }
+    } else {
+      current = null;
+      items.push(row);
+    }
+  }
+  return items;
+}
+
+/**
+ * The handler-emitted `TraceEntry` adapter: stamp each entry with a stable `id`
+ * (its index) to lift it into a {@link TraceRow}. The entries already carry the
+ * additive `turn`/`elementId`/`args`/`result` fields, so {@link buildTraceItems}
+ * over the result reproduces the agentic turn-grouped card view without any
+ * re-forked grouping logic. The input is never mutated.
+ */
+export function traceEntriesToRows(entries: readonly TraceEntry[]): TraceRow[] {
+  return entries.map((entry, id) => ({ ...entry, id }));
+}
+
+/**
+ * How one engine event type folds into the trace: its row {@link TraceRowKind}
+ * and a function turning the event's snake_case payload into a line. Returning
+ * a mapping opts the event into the story; every type absent from the table
+ * below is deliberately dropped as low-signal lifecycle noise (`ElementActivating`
+ * / `ElementCompleting`, `JobActivated`, `SequenceFlowTaken`, the scoped-variable
+ * and parallel-join bookkeeping), so the fold reads as a run's milestones rather
+ * than a raw trace.
+ */
+interface EngineEventRule {
+  kind: TraceRowKind;
+  text: (ev: WasmEvent) => string;
+}
+
+/** Read a string field off a `WasmEvent`'s open payload, or `undefined`. */
+function str(ev: WasmEvent, key: string): string | undefined {
+  const v = ev[key];
+  return typeof v === "string" ? v : undefined;
+}
+
+/** The element this event concerns, if it names one — for pairing/labelling. */
+function elementOf(ev: WasmEvent): string | undefined {
+  return str(ev, "element_id");
+}
+
+const ENGINE_EVENT_RULES: Record<string, EngineEventRule> = {
+  ProcessInstanceCreated: {
+    kind: "start",
+    text: (ev) => `Process ${str(ev, "process_id") ?? "instance"} started`,
+  },
+  JobCreated: {
+    kind: "tool",
+    text: (ev) =>
+      `Job ${str(ev, "job_type") ?? ""} created`.trim() +
+      (elementOf(ev) ? ` on ${elementOf(ev)}` : ""),
+  },
+  JobCompleted: {
+    kind: "vars",
+    text: (ev) => `Job ${str(ev, "job_type") ?? ""} completed`.trim(),
+  },
+  JobFailed: {
+    kind: "error",
+    text: (ev) => `Job ${str(ev, "job_type") ?? ""} failed`.trim(),
+  },
+  JobErrorThrown: {
+    kind: "error",
+    text: (ev) =>
+      `Job threw error ${str(ev, "error_code") ?? ""}`.trim() +
+      (elementOf(ev) ? ` on ${elementOf(ev)}` : ""),
+  },
+  IncidentRaised: {
+    kind: "error",
+    text: (ev) =>
+      `Incident on ${elementOf(ev) ?? "instance"}` +
+      (str(ev, "reason") ? `: ${str(ev, "reason")}` : ""),
+  },
+  IncidentResolved: {
+    kind: "tool",
+    text: (ev) => `Incident resolved on ${elementOf(ev) ?? "instance"}`,
+  },
+  UserTaskCreated: {
+    kind: "human",
+    text: (ev) => `User task ${elementOf(ev) ?? ""} awaiting a human`.trim(),
+  },
+  UserTaskAssigned: {
+    kind: "human",
+    text: (ev) =>
+      `User task ${elementOf(ev) ?? ""} assigned`.trim() +
+      (str(ev, "assignee") ? ` to ${str(ev, "assignee")}` : ""),
+  },
+  UserTaskCompleted: {
+    kind: "human",
+    text: (ev) => `User task ${elementOf(ev) ?? ""} completed`.trim(),
+  },
+  UserTaskCanceled: {
+    kind: "human",
+    text: (ev) => `User task ${elementOf(ev) ?? ""} canceled`.trim(),
+  },
+  TimerCreated: {
+    kind: "tool",
+    text: (ev) => `Timer set on ${elementOf(ev) ?? "instance"}`,
+  },
+  TimerTriggered: {
+    kind: "tool",
+    text: (ev) => `Timer fired on ${elementOf(ev) ?? "instance"}`,
+  },
+  MessagePublished: {
+    kind: "tool",
+    text: (ev) => `Message ${str(ev, "message_name") ?? ""} published`.trim(),
+  },
+  MessageCorrelated: {
+    kind: "tool",
+    text: (ev) => `Message ${str(ev, "message_name") ?? ""} correlated`.trim(),
+  },
+  SignalBroadcast: {
+    kind: "tool",
+    text: (ev) => `Signal ${str(ev, "signal_name") ?? ""} broadcast`.trim(),
+  },
+  SignalCorrelated: {
+    kind: "tool",
+    text: (ev) => `Signal ${str(ev, "signal_name") ?? ""} correlated`.trim(),
+  },
+  AdHocActivated: {
+    kind: "agent",
+    text: (ev) => `Ad-hoc sub-process ${elementOf(ev) ?? ""} activated`.trim(),
+  },
+  AdHocToolActivated: {
+    kind: "agent",
+    text: (ev) => `Tool ${elementOf(ev) ?? ""} activated`.trim(),
+  },
+  AdHocToolCompleted: {
+    kind: "vars",
+    text: (ev) => `Tool ${elementOf(ev) ?? ""} returned`.trim(),
+  },
+  AdHocCompleted: {
+    kind: "agent",
+    text: (ev) => `Ad-hoc sub-process ${elementOf(ev) ?? ""} completed`.trim(),
+  },
+  ProcessInstanceCompleted: {
+    kind: "done",
+    text: () => "Process completed",
+  },
+  ProcessInstanceTerminated: {
+    kind: "error",
+    text: () => "Process terminated",
+  },
+};
+
+/**
+ * The engine-event fold adapter: map a `WasmEvent[]` (the flattened
+ * `{ seq, now, type, …snake_case }` stream from `useBojtos().events`) into
+ * normalized rows, keeping only the meaningful milestones (see
+ * {@link ENGINE_EVENT_RULES}). Each row's `id` is the event's `seq`, so ids stay
+ * stable and monotonic across re-reads of a growing log. Engine events carry no
+ * turn, so {@link buildTraceItems} over the result is a flat list of rows — the
+ * non-agentic test-view shape.
+ */
+export function foldEngineEvents(events: readonly WasmEvent[]): TraceRow[] {
+  const rows: TraceRow[] = [];
+  for (const ev of events) {
+    const rule = ENGINE_EVENT_RULES[ev.type];
+    if (!rule) continue;
+    rows.push({
+      id: ev.seq,
+      kind: rule.kind,
+      text: rule.text(ev),
+      elementId: elementOf(ev),
+    });
+  }
+  return rows;
+}