@nanobpm/bojtos-kit 0.8.0 → 0.9.0

package/README.md

@@ -61,6 +61,28 @@ The read methods — `searchUserTasks`, `searchProcessInstances`,
 from `@nanobpm/engine-wasm/readmodel-types`, which are **derived** from the
 Camunda-parity REST OpenAPI (one source of truth, not a hand-copy).
 
+### `readModel()` — the `@nanobpm/engine-testkit` assertion handle
+
+A `readmodel`-variant session also exposes `readModel()`, which returns the
+session's engine read model as `@nanobpm/engine-testkit`'s structural
+[`EngineReadModel`](https://www.npmjs.com/package/@nanobpm/engine-testkit) port
+(`snapshot()` + the user-task read channel). Hand it straight to the `assertThat*`
+DSL — it reads the engine's canonical snapshot off *this* session, so there is no
+re-derived copy of the state:
+
+```ts
+import { assertThatInstance, assertThatUserTask, byProcessId } from "@nanobpm/engine-testkit";
+
+const rm = session.readModel(); // typed EngineReadModel — a compile-time guarantee
+
+assertThatInstance(rm, byProcessId("review")).isActive().hasActiveElement("review-task");
+await assertThatUserTask(rm, { elementId: "review-task" }).isCreated();
+```
+
+The React binding surfaces the same handle as `useBojtos({ variant: "readmodel" }).readModel()`
+(`EngineReadModel | null` until the engine is ready).
+
+
 ## Trace model
 
 The kit also holds the framework-agnostic **trace model** the shared

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { ensureWasm, ensureReadModelWasm, createBojtosSession, type BojtosSession, type ReadModelBojtosSession, type EngineVariant, type WasmSource, } from "./session.js";
+export type { EngineReadModel, UserTaskQuery, UserTaskRow, } from "@nanobpm/engine-testkit";
 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";

package/dist/session.d.ts

@@ -1,5 +1,6 @@
 import { type InitInput } from "@nanobpm/engine-wasm";
 import type { FormResult, ProcessInstanceSearchQueryResult, ResourceResult, UserTaskSearchQueryResult, VariableSearchQueryResult } from "@nanobpm/engine-wasm/readmodel-types";
+import type { EngineReadModel } from "@nanobpm/engine-testkit";
 import type { ActivatedJob, ActivateInstruction, AgentResult, Snapshot, WasmEvent } from "./types.js";
 /**
  * Which engine binary backs a session. The two are separate wasm builds
@@ -204,6 +205,18 @@ export interface ReadModelBojtosSession extends BojtosSession {
      * `GET /resources/{resourceKey}`.
      */
     getResourceByKey(resourceKey: string): ResourceResult | null;
+    /**
+     * This session's engine read model as the structural {@link EngineReadModel}
+     * port that `@nanobpm/engine-testkit`'s `assertThat*` DSL asserts over. Hand it
+     * straight to `assertThatInstance` / `assertThatUserTask`: it reads the
+     * canonical engine snapshot (`snapshot()`) and the user-task read channel
+     * (`searchUserTasks` / `openUserTasks`, the CREATED set) off *this* session, so
+     * a consumer (e.g. `camunda/web-demo-framework`) asserts against the engine's
+     * single source of truth rather than re-deriving a snapshot. The returned
+     * object is typed `EngineReadModel`, so its structural conformance to the port
+     * is a compile-time guarantee, not a runtime cast.
+     */
+    readModel(): EngineReadModel;
 }
 /**
  * Create a fresh headless engine session. Ensures the chosen wasm variant is

package/dist/session.js

@@ -154,6 +154,46 @@ class WasmReadModelSession extends WasmBojtosSession {
     getResourceByKey(resourceKey) {
         return JSON.parse(this.rm.getResourceByKey(resourceKey));
     }
+    readModel() {
+        // Reads flow straight off this session's engine — the same parsed snapshot
+        // and the same user-task read channel the rest of the session exposes — so
+        // there is a single source of truth and no re-derived copy of the state
+        // (nanobpm/bojtos#15). Typing the returned object as `EngineReadModel` makes
+        // structural conformance to engine-testkit's port a compile-time assignment.
+        const searchRows = (query) => this.searchUserTasks(JSON.stringify(query.state === undefined ? {} : { state: query.state }))
+            .items.filter((task) => {
+            // The wasm read model honours the lifecycle `state` filter itself; the
+            // non-lifecycle narrowings the DSL relies on (processInstanceKey /
+            // assignee / candidateGroup) are applied here so `assertThatUserTask`'s
+            // `hasAssignee` / `hasCandidateGroup` / instance-scoped selects hold.
+            if (query.processInstanceKey !== undefined &&
+                task.processInstanceKey !== query.processInstanceKey) {
+                return false;
+            }
+            if (query.assignee !== undefined && task.assignee !== query.assignee) {
+                return false;
+            }
+            if (query.candidateGroup !== undefined &&
+                !task.candidateGroups.includes(query.candidateGroup)) {
+                return false;
+            }
+            return true;
+        })
+            .map((task) => ({
+            userTaskKey: task.userTaskKey,
+            elementId: task.elementId ?? undefined,
+        }));
+        return {
+            // The engine snapshot is already the DSL's expected structural shape
+            // (`instances`/`activeElements`/`elementStats`/`incidents`/per-instance
+            // `variables`); the assertion only retypes the same object as the port's
+            // open `Record<string, unknown>` — it does not re-derive it.
+            snapshot: () => this.snapshot(),
+            searchUserTasks: (query) => Promise.resolve(searchRows(query)),
+            // openUserTasks is searchUserTasks pinned to the open (CREATED) set.
+            openUserTasks: (query) => Promise.resolve(searchRows({ ...query, state: "CREATED" })),
+        };
+    }
 }
 export async function createBojtosSession(opts) {
     if (opts?.variant === "readmodel") {

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@nanobpm/bojtos-kit",
-  "version": "0.8.0",
+  "version": "0.9.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",
+  "engines": {
+    "node": ">=22.6"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nanobpm/bojtos.git",
@@ -32,6 +35,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
+    "@nanobpm/engine-testkit": "^0.1.0",
     "@nanobpm/engine-wasm": "^0.7.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -11,6 +11,14 @@ export {
   type EngineVariant,
   type WasmSource,
 } from "./session.js";
+// The engine-testkit read-model port a `ReadModelBojtosSession.readModel()`
+// satisfies, re-exported so a consumer can name the handle's type (e.g. to store
+// it) without a direct import of `@nanobpm/engine-testkit`.
+export type {
+  EngineReadModel,
+  UserTaskQuery,
+  UserTaskRow,
+} from "@nanobpm/engine-testkit";
 export {
   dispatchWorkers,
   dispatchRound,

package/src/session.ts

@@ -6,6 +6,11 @@ import type {
   UserTaskSearchQueryResult,
   VariableSearchQueryResult,
 } from "@nanobpm/engine-wasm/readmodel-types";
+import type {
+  EngineReadModel,
+  UserTaskQuery,
+  UserTaskRow,
+} from "@nanobpm/engine-testkit";
 import type {
   ActivatedJob,
   ActivateInstruction,
@@ -282,6 +287,18 @@ export interface ReadModelBojtosSession extends BojtosSession {
    * `GET /resources/{resourceKey}`.
    */
   getResourceByKey(resourceKey: string): ResourceResult | null;
+  /**
+   * This session's engine read model as the structural {@link EngineReadModel}
+   * port that `@nanobpm/engine-testkit`'s `assertThat*` DSL asserts over. Hand it
+   * straight to `assertThatInstance` / `assertThatUserTask`: it reads the
+   * canonical engine snapshot (`snapshot()`) and the user-task read channel
+   * (`searchUserTasks` / `openUserTasks`, the CREATED set) off *this* session, so
+   * a consumer (e.g. `camunda/web-demo-framework`) asserts against the engine's
+   * single source of truth rather than re-deriving a snapshot. The returned
+   * object is typed `EngineReadModel`, so its structural conformance to the port
+   * is a compile-time guarantee, not a runtime cast.
+   */
+  readModel(): EngineReadModel;
 }
 
 function parseSnapshot(json: string): Snapshot {
@@ -492,6 +509,56 @@ class WasmReadModelSession
       this.rm.getResourceByKey(resourceKey),
     ) as ResourceResult | null;
   }
+
+  readModel(): EngineReadModel {
+    // Reads flow straight off this session's engine — the same parsed snapshot
+    // and the same user-task read channel the rest of the session exposes — so
+    // there is a single source of truth and no re-derived copy of the state
+    // (nanobpm/bojtos#15). Typing the returned object as `EngineReadModel` makes
+    // structural conformance to engine-testkit's port a compile-time assignment.
+    const searchRows = (query: UserTaskQuery): UserTaskRow[] =>
+      this.searchUserTasks(
+        JSON.stringify(query.state === undefined ? {} : { state: query.state }),
+      )
+        .items.filter((task) => {
+          // The wasm read model honours the lifecycle `state` filter itself; the
+          // non-lifecycle narrowings the DSL relies on (processInstanceKey /
+          // assignee / candidateGroup) are applied here so `assertThatUserTask`'s
+          // `hasAssignee` / `hasCandidateGroup` / instance-scoped selects hold.
+          if (
+            query.processInstanceKey !== undefined &&
+            task.processInstanceKey !== query.processInstanceKey
+          ) {
+            return false;
+          }
+          if (query.assignee !== undefined && task.assignee !== query.assignee) {
+            return false;
+          }
+          if (
+            query.candidateGroup !== undefined &&
+            !task.candidateGroups.includes(query.candidateGroup)
+          ) {
+            return false;
+          }
+          return true;
+        })
+        .map((task) => ({
+          userTaskKey: task.userTaskKey,
+          elementId: task.elementId ?? undefined,
+        }));
+
+    return {
+      // The engine snapshot is already the DSL's expected structural shape
+      // (`instances`/`activeElements`/`elementStats`/`incidents`/per-instance
+      // `variables`); the assertion only retypes the same object as the port's
+      // open `Record<string, unknown>` — it does not re-derive it.
+      snapshot: () => this.snapshot() as unknown as Record<string, unknown>,
+      searchUserTasks: (query) => Promise.resolve(searchRows(query)),
+      // openUserTasks is searchUserTasks pinned to the open (CREATED) set.
+      openUserTasks: (query) =>
+        Promise.resolve(searchRows({ ...query, state: "CREATED" })),
+    };
+  }
 }
 
 /**