@nanobpm/bojtos-kit 0.3.0 → 0.5.0

package/README.md

@@ -1,9 +1,9 @@
 # @nanobpm/bojtos-kit
 
 Framework-agnostic core of the **Bojtos** in-browser BPMN demo framework
-([ADR 0043](../docs/adr/0043-bojtos-demo-framework.md)).
+([ADR 0043](../README.md#design)).
 
-It wraps [`@nanobpm/engine-wasm`](../engine-wasm) as a single scenario runner —
+It wraps [`@nanobpm/engine-wasm`](https://www.npmjs.com/package/@nanobpm/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.
@@ -29,5 +29,7 @@ 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`.
+`dist/` (the tsc-emitted JS + `.d.ts`) is what ships, built by `prepack` on
+publish and by `npm test` locally. It is **not** committed — `.gitignore` covers
+it — so build before pointing a `file:` consumer at this workspace. Regenerate
+with `npm run build`.

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { ensureWasm, createBojtosSession, type BojtosSession, type WasmSource, } from "./session.js";
-export { dispatchWorkers, dispatchRound, JobFailure, type JobHandler, type JobResult, type AgentHandler, type DispatchOptions, type DispatchResult, type RoundResult, } from "./worker.js";
-export type { Snapshot, InstanceDto, JobDto, ActivatedJob, IncidentDto, TimerDto, ActiveEl, AgentActivation, AgentResult, WasmEvent, } from "./types.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 type { Snapshot, InstanceDto, JobDto, ActivatedJob, IncidentDto, TimerDto, UserTaskDto, MessageSubscriptionDto, SignalSubscriptionDto, ElementStatDto, SequenceFlowDto, DecisionInstanceDto, ActiveEl, ActivateInstruction, AgentActivation, AgentResult, WasmEvent, } from "./types.js";

package/dist/index.js

@@ -2,4 +2,4 @@
 // 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";
+export { dispatchWorkers, dispatchRound, settleReason, unhandledJobTypes, JobFailure, } from "./worker.js";

package/dist/types.d.ts

@@ -169,6 +169,15 @@ export interface Snapshot {
     signalSubscriptions: SignalSubscriptionDto[];
     elementStats: ElementStatDto[];
     takenSequenceFlows: SequenceFlowDto[];
+    /**
+     * Evaluated DMN decisions.
+     *
+     * **Reserved.** `BojtosSession.deploy` takes a BPMN resource only, so there is
+     * currently no way to deploy a decision and nothing can populate this — treat
+     * a consumer that renders it as writing for a future engine, not reading live
+     * data. Kept in the contract so the shape doesn't change when deployment of
+     * decision resources lands.
+     */
     decisionInstances: DecisionInstanceDto[];
     activeElementIds: string[];
     incidentElementIds: string[];

package/dist/worker.d.ts

@@ -61,13 +61,72 @@ export interface DispatchOptions {
      * whole agent conversation to quiescence.
      */
     agents?: Record<string, AgentHandler>;
+    /**
+     * Let the drain loop move the virtual clock when it runs out of work but a
+     * timer is still pending: it jumps to the next due timer and keeps going.
+     *
+     * Off by default, because advancing time is a decision about what the demo is
+     * showing, not a detail. With it off, a model that waits on a timer settles
+     * with `reason: "timers"` — the loop is *done*, the process isn't — and the
+     * caller advances the clock itself.
+     *
+     * `true` advances as far as needed. `{ maxTotalMs }` sets a **budget for the
+     * whole drain**, not per jump — the loop advances while it can afford to and
+     * then settles with `reason: "timers"`, so "run for up to an hour of virtual
+     * time" is expressible and a `PT24H` timer can't be reached a second at a
+     * time.
+     */
+    advanceTimers?: boolean | {
+        maxTotalMs: number;
+    };
 }
+/**
+ * Why a drain stopped. `handled === 0` alone can't say: a completed instance, a
+ * human step, a pending timer, a message that never arrived and a job type
+ * nobody registered all look identical from the outside, and each one needs a
+ * different response from the UI above.
+ */
+export type SettleReason = 
+/** No live instances remain — every one completed or was terminated. */
+"completed"
+/** Waiting on a `userTask`; complete it with `session.completeUserTask`. */
+ | "userTasks"
+/** Waiting on a timer; advance the clock (or pass `advanceTimers`). */
+ | "timers"
+/** Waiting on a message subscription; publish with `correlateMessage`. */
+ | "messages"
+/** Waiting on a signal subscription; publish with `broadcastSignal`. */
+ | "signals"
+/** Jobs are waiting whose job type has no registered handler. */
+ | "unhandledJobs"
+/** An incident is blocking progress; resolve it to continue. */
+ | "incidents"
+/** Nothing is running and nothing is waiting — an empty or unstarted engine. */
+ | "idle";
+/**
+ * Classify why the loop has nothing left to do. Pure, and exported so a consumer
+ * can label a snapshot it obtained some other way (and so it can be tested
+ * without an engine).
+ *
+ * Order matters: it reports the thing a caller can act on first. Incidents come
+ * before waiting states because an incident is why the wait will never end.
+ */
+export declare function settleReason(snapshot: Snapshot, handledJobTypes?: Iterable<string>): SettleReason;
+/** Job types with waiting jobs that no registered handler serves. */
+export declare function unhandledJobTypes(snapshot: Snapshot, handledJobTypes?: Iterable<string>): string[];
 /** 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;
+    /**
+     * Why there was nothing left to do, when `handled === 0`. Undefined while the
+     * round did work — the loop hasn't settled, so there is nothing to explain.
+     */
+    reason?: SettleReason;
+    /** Waiting job types no registered handler serves (usually a typo). */
+    unhandled?: string[];
 }
 /** What {@link dispatchWorkers} did. */
 export interface DispatchResult {
@@ -77,6 +136,15 @@ export interface DispatchResult {
     handled: number;
     /** How many activate rounds ran (including the final quiescent one). */
     rounds: number;
+    /**
+     * Why the drain stopped. Always set: a settled drain always has a reason, and
+     * "the loop finished" is not the same claim as "the process finished".
+     */
+    reason: SettleReason;
+    /** Waiting job types no registered handler serves (usually a typo). */
+    unhandled: string[];
+    /** How far the virtual clock was moved, when `advanceTimers` is on. */
+    advancedMs: number;
 }
 /**
  * Run one activate-and-handle pass: activate every registered job type's

package/dist/worker.js

@@ -12,6 +12,40 @@ export class JobFailure extends Error {
         this.retries = opts?.retries;
     }
 }
+/**
+ * Classify why the loop has nothing left to do. Pure, and exported so a consumer
+ * can label a snapshot it obtained some other way (and so it can be tested
+ * without an engine).
+ *
+ * Order matters: it reports the thing a caller can act on first. Incidents come
+ * before waiting states because an incident is why the wait will never end.
+ */
+export function settleReason(snapshot, handledJobTypes = []) {
+    const live = snapshot.instances.filter((i) => !i.completed);
+    if (live.length === 0)
+        return snapshot.totalInstances > 0 ? "completed" : "idle";
+    if (snapshot.incidents.length > 0)
+        return "incidents";
+    const known = new Set(handledJobTypes);
+    if (snapshot.jobs.some((j) => !known.has(j.jobType)))
+        return "unhandledJobs";
+    if (snapshot.userTasks.some((t) => t.state === "Created"))
+        return "userTasks";
+    if (snapshot.timers.length > 0)
+        return "timers";
+    if (snapshot.messageSubscriptions.length > 0)
+        return "messages";
+    if (snapshot.signalSubscriptions.length > 0)
+        return "signals";
+    return "idle";
+}
+/** Job types with waiting jobs that no registered handler serves. */
+export function unhandledJobTypes(snapshot, handledJobTypes = []) {
+    const known = new Set(handledJobTypes);
+    return [...new Set(snapshot.jobs.map((j) => j.jobType))]
+        .filter((t) => !known.has(t))
+        .sort();
+}
 async function runOne(session, handler, job) {
     let payload;
     try {
@@ -112,9 +146,18 @@ export async function dispatchRound(session, workers, opts = {}) {
     for (const { handler, job } of agentBatch) {
         await runOneAgent(session, handler, job);
     }
+    const snapshot = session.snapshot();
+    const handled = jobBatch.length + agentBatch.length;
+    if (handled > 0)
+        return { snapshot, handled };
+    // Nothing left to do this round — say why, so the caller isn't left to infer
+    // "finished" from "quiet".
+    const known = [...Object.keys(workers), ...Object.keys(agents)];
     return {
-        snapshot: session.snapshot(),
-        handled: jobBatch.length + agentBatch.length,
+        snapshot,
+        handled,
+        reason: settleReason(snapshot, known),
+        unhandled: unhandledJobTypes(snapshot, known),
     };
 }
 /**
@@ -129,8 +172,16 @@ export async function dispatchRound(session, workers, opts = {}) {
  */
 export async function dispatchWorkers(session, workers, opts = {}) {
     const maxRounds = opts.maxRounds ?? 1000;
+    // `typeof null === "object"`, so guard against a JS caller passing `null`
+    // (via `any`) — otherwise reading `.maxTotalMs` off it throws.
+    const advanceTimers = opts.advanceTimers;
+    const timeBudgetMs = advanceTimers != null && typeof advanceTimers === "object"
+        ? advanceTimers.maxTotalMs
+        : Infinity;
+    const mayAdvance = advanceTimers != null && advanceTimers !== false;
     let handled = 0;
     let rounds = 0;
+    let advancedMs = 0;
     for (;;) {
         if (rounds >= maxRounds) {
             throw new Error(`dispatchWorkers exceeded maxRounds (${maxRounds}) — a handler may be creating work without end`);
@@ -138,8 +189,40 @@ export async function dispatchWorkers(session, workers, opts = {}) {
         rounds++;
         const round = await dispatchRound(session, workers, opts);
         handled += round.handled;
-        if (round.handled === 0) {
-            return { snapshot: round.snapshot, handled, rounds };
+        if (round.handled > 0)
+            continue;
+        // Out of jobs. If the only thing standing between here and more work is the
+        // clock, and the caller asked us to, jump to the next due timer and carry
+        // on — otherwise a timer-bearing model looks finished when it is waiting.
+        if (mayAdvance && round.reason === "timers") {
+            const due = round.snapshot.timers.reduce((min, t) => Math.min(min, t.dueInMs), Infinity);
+            // `dueInMs` can be <= 0 for a timer that is already due but hasn't been
+            // triggered; nudge by 1ms so the clock always moves and the loop can't spin.
+            const jump = Math.max(due, 1);
+            // Only jump if the whole hop fits the budget. A partial hop would burn the
+            // budget without firing anything, which is strictly worse than stopping
+            // and telling the caller a timer is still pending.
+            if (Number.isFinite(jump) && advancedMs + jump <= timeBudgetMs) {
+                session.advanceTime(jump);
+                advancedMs += jump;
+                continue;
+            }
         }
+        return {
+            snapshot: round.snapshot,
+            handled,
+            rounds,
+            // `round.reason` is always set once `round.handled === 0` (the only way to
+            // reach here), so the fallback is currently unreachable — but if it ever
+            // did fire it must use the same handler set as the round, or it would
+            // recompute against an empty set and flag every job type as unhandled.
+            reason: round.reason ??
+                settleReason(round.snapshot, [
+                    ...Object.keys(workers),
+                    ...Object.keys(opts.agents ?? {}),
+                ]),
+            unhandled: round.unhandled ?? [],
+            advancedMs,
+        };
     }
 }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@nanobpm/bojtos-kit",
-  "version": "0.3.0",
+  "version": "0.5.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": "git+https://github.com/Magikcraft/nano-bpm.git",
+    "url": "git+https://github.com/nanobpm/bojtos.git",
     "directory": "bojtos-kit"
   },
   "main": "./dist/index.js",

package/src/index.ts

@@ -11,6 +11,8 @@ export {
 export {
   dispatchWorkers,
   dispatchRound,
+  settleReason,
+  unhandledJobTypes,
   JobFailure,
   type JobHandler,
   type JobResult,
@@ -18,7 +20,11 @@ export {
   type DispatchOptions,
   type DispatchResult,
   type RoundResult,
+  type SettleReason,
 } from "./worker.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`.
 export type {
   Snapshot,
   InstanceDto,
@@ -26,7 +32,14 @@ export type {
   ActivatedJob,
   IncidentDto,
   TimerDto,
+  UserTaskDto,
+  MessageSubscriptionDto,
+  SignalSubscriptionDto,
+  ElementStatDto,
+  SequenceFlowDto,
+  DecisionInstanceDto,
   ActiveEl,
+  ActivateInstruction,
   AgentActivation,
   AgentResult,
   WasmEvent,

package/src/types.ts

@@ -190,6 +190,15 @@ export interface Snapshot {
   signalSubscriptions: SignalSubscriptionDto[];
   elementStats: ElementStatDto[];
   takenSequenceFlows: SequenceFlowDto[];
+  /**
+   * Evaluated DMN decisions.
+   *
+   * **Reserved.** `BojtosSession.deploy` takes a BPMN resource only, so there is
+   * currently no way to deploy a decision and nothing can populate this — treat
+   * a consumer that renders it as writing for a future engine, not reading live
+   * data. Kept in the contract so the shape doesn't change when deployment of
+   * decision resources lands.
+   */
   decisionInstances: DecisionInstanceDto[];
   activeElementIds: string[];
   incidentElementIds: string[];

package/src/worker.ts

@@ -72,6 +72,84 @@ export interface DispatchOptions {
    * whole agent conversation to quiescence.
    */
   agents?: Record<string, AgentHandler>;
+  /**
+   * Let the drain loop move the virtual clock when it runs out of work but a
+   * timer is still pending: it jumps to the next due timer and keeps going.
+   *
+   * Off by default, because advancing time is a decision about what the demo is
+   * showing, not a detail. With it off, a model that waits on a timer settles
+   * with `reason: "timers"` — the loop is *done*, the process isn't — and the
+   * caller advances the clock itself.
+   *
+   * `true` advances as far as needed. `{ maxTotalMs }` sets a **budget for the
+   * whole drain**, not per jump — the loop advances while it can afford to and
+   * then settles with `reason: "timers"`, so "run for up to an hour of virtual
+   * time" is expressible and a `PT24H` timer can't be reached a second at a
+   * time.
+   */
+  advanceTimers?: boolean | { maxTotalMs: number };
+}
+
+/**
+ * Why a drain stopped. `handled === 0` alone can't say: a completed instance, a
+ * human step, a pending timer, a message that never arrived and a job type
+ * nobody registered all look identical from the outside, and each one needs a
+ * different response from the UI above.
+ */
+export type SettleReason =
+  /** No live instances remain — every one completed or was terminated. */
+  | "completed"
+  /** Waiting on a `userTask`; complete it with `session.completeUserTask`. */
+  | "userTasks"
+  /** Waiting on a timer; advance the clock (or pass `advanceTimers`). */
+  | "timers"
+  /** Waiting on a message subscription; publish with `correlateMessage`. */
+  | "messages"
+  /** Waiting on a signal subscription; publish with `broadcastSignal`. */
+  | "signals"
+  /** Jobs are waiting whose job type has no registered handler. */
+  | "unhandledJobs"
+  /** An incident is blocking progress; resolve it to continue. */
+  | "incidents"
+  /** Nothing is running and nothing is waiting — an empty or unstarted engine. */
+  | "idle";
+
+/**
+ * Classify why the loop has nothing left to do. Pure, and exported so a consumer
+ * can label a snapshot it obtained some other way (and so it can be tested
+ * without an engine).
+ *
+ * Order matters: it reports the thing a caller can act on first. Incidents come
+ * before waiting states because an incident is why the wait will never end.
+ */
+export function settleReason(
+  snapshot: Snapshot,
+  handledJobTypes: Iterable<string> = [],
+): SettleReason {
+  const live = snapshot.instances.filter((i) => !i.completed);
+  if (live.length === 0)
+    return snapshot.totalInstances > 0 ? "completed" : "idle";
+  if (snapshot.incidents.length > 0) return "incidents";
+
+  const known = new Set(handledJobTypes);
+  if (snapshot.jobs.some((j) => !known.has(j.jobType))) return "unhandledJobs";
+
+  if (snapshot.userTasks.some((t) => t.state === "Created")) return "userTasks";
+  if (snapshot.timers.length > 0) return "timers";
+  if (snapshot.messageSubscriptions.length > 0) return "messages";
+  if (snapshot.signalSubscriptions.length > 0) return "signals";
+  return "idle";
+}
+
+/** Job types with waiting jobs that no registered handler serves. */
+export function unhandledJobTypes(
+  snapshot: Snapshot,
+  handledJobTypes: Iterable<string> = [],
+): string[] {
+  const known = new Set(handledJobTypes);
+  return [...new Set(snapshot.jobs.map((j) => j.jobType))]
+    .filter((t) => !known.has(t))
+    .sort();
 }
 
 /** What one {@link dispatchRound} pass did. */
@@ -80,6 +158,13 @@ export interface RoundResult {
   snapshot: Snapshot;
   /** How many jobs were completed or failed in this pass. */
   handled: number;
+  /**
+   * Why there was nothing left to do, when `handled === 0`. Undefined while the
+   * round did work — the loop hasn't settled, so there is nothing to explain.
+   */
+  reason?: SettleReason;
+  /** Waiting job types no registered handler serves (usually a typo). */
+  unhandled?: string[];
 }
 
 /** What {@link dispatchWorkers} did. */
@@ -90,6 +175,15 @@ export interface DispatchResult {
   handled: number;
   /** How many activate rounds ran (including the final quiescent one). */
   rounds: number;
+  /**
+   * Why the drain stopped. Always set: a settled drain always has a reason, and
+   * "the loop finished" is not the same claim as "the process finished".
+   */
+  reason: SettleReason;
+  /** Waiting job types no registered handler serves (usually a typo). */
+  unhandled: string[];
+  /** How far the virtual clock was moved, when `advanceTimers` is on. */
+  advancedMs: number;
 }
 
 async function runOne(
@@ -208,9 +302,17 @@ export async function dispatchRound(
   for (const { handler, job } of agentBatch) {
     await runOneAgent(session, handler, job);
   }
+  const snapshot = session.snapshot();
+  const handled = jobBatch.length + agentBatch.length;
+  if (handled > 0) return { snapshot, handled };
+  // Nothing left to do this round — say why, so the caller isn't left to infer
+  // "finished" from "quiet".
+  const known = [...Object.keys(workers), ...Object.keys(agents)];
   return {
-    snapshot: session.snapshot(),
-    handled: jobBatch.length + agentBatch.length,
+    snapshot,
+    handled,
+    reason: settleReason(snapshot, known),
+    unhandled: unhandledJobTypes(snapshot, known),
   };
 }
 
@@ -230,8 +332,18 @@ export async function dispatchWorkers(
   opts: DispatchOptions = {},
 ): Promise<DispatchResult> {
   const maxRounds = opts.maxRounds ?? 1000;
+  // `typeof null === "object"`, so guard against a JS caller passing `null`
+  // (via `any`) — otherwise reading `.maxTotalMs` off it throws.
+  const advanceTimers = opts.advanceTimers;
+  const timeBudgetMs =
+    advanceTimers != null && typeof advanceTimers === "object"
+      ? advanceTimers.maxTotalMs
+      : Infinity;
+  const mayAdvance = advanceTimers != null && advanceTimers !== false;
+
   let handled = 0;
   let rounds = 0;
+  let advancedMs = 0;
   for (;;) {
     if (rounds >= maxRounds) {
       throw new Error(
@@ -241,8 +353,45 @@ export async function dispatchWorkers(
     rounds++;
     const round = await dispatchRound(session, workers, opts);
     handled += round.handled;
-    if (round.handled === 0) {
-      return { snapshot: round.snapshot, handled, rounds };
+    if (round.handled > 0) continue;
+
+    // Out of jobs. If the only thing standing between here and more work is the
+    // clock, and the caller asked us to, jump to the next due timer and carry
+    // on — otherwise a timer-bearing model looks finished when it is waiting.
+    if (mayAdvance && round.reason === "timers") {
+      const due = round.snapshot.timers.reduce(
+        (min, t) => Math.min(min, t.dueInMs),
+        Infinity,
+      );
+      // `dueInMs` can be <= 0 for a timer that is already due but hasn't been
+      // triggered; nudge by 1ms so the clock always moves and the loop can't spin.
+      const jump = Math.max(due, 1);
+      // Only jump if the whole hop fits the budget. A partial hop would burn the
+      // budget without firing anything, which is strictly worse than stopping
+      // and telling the caller a timer is still pending.
+      if (Number.isFinite(jump) && advancedMs + jump <= timeBudgetMs) {
+        session.advanceTime(jump);
+        advancedMs += jump;
+        continue;
+      }
     }
+
+    return {
+      snapshot: round.snapshot,
+      handled,
+      rounds,
+      // `round.reason` is always set once `round.handled === 0` (the only way to
+      // reach here), so the fallback is currently unreachable — but if it ever
+      // did fire it must use the same handler set as the round, or it would
+      // recompute against an empty set and flag every job type as unhandled.
+      reason:
+        round.reason ??
+        settleReason(round.snapshot, [
+          ...Object.keys(workers),
+          ...Object.keys(opts.agents ?? {}),
+        ]),
+      unhandled: round.unhandled ?? [],
+      advancedMs,
+    };
   }
 }