@jarenjs/flow 0.34.0

package/src/errors.js

@@ -0,0 +1,169 @@
+//@ts-check
+/**
+ * @file Error types for @jarenjs/flow, built on `@jarenjs/core`'s coded
+ * contract: every failure carries a stable `code` (JF0xxx compile,
+ * JF2xxx runtime), a bare `reason`, a composed `message`, and — where
+ * one exists — the `docPath` of the offending member of the flow
+ * document. The feedback shape a repair loop needs. The normative
+ * table lives in docs/FLOW-FORMAT.md §5, proven in sync with
+ * `FLOW_CODES` below by a test.
+ */
+
+import { CodedError } from '@jarenjs/core/errors';
+
+/**
+ * The runtime code table (the `CSV_CODES` shape): one entry per code
+ * this package can raise, proven in sync with FLOW-FORMAT.md §5's
+ * normative table by a test — the "must stay in sync by hand" note this
+ * file used to carry is now a checked fact.
+ */
+export const FLOW_CODES = Object.freeze({
+  JF0001: 'the document is not an object, or $fsm is not 0.1',
+  JF0002: 'states is not an array, or a state entry is malformed',
+  JF0003: 'two state entries share one id',
+  JF0004: 'initial is neither null nor a declared state id',
+  JF0005: 'transitions is not an array, or an entry is malformed',
+  JF0006: 'a transition from/to names no declared state',
+  JF0007: 'a guard failed to compile as a query document',
+  JF0008: 'an effects list or effect descriptor is malformed',
+  JF0009: 'an effect with failed to compile as a query document',
+  JF0010: 'the dag document is not an object, or $dag is not 0.1',
+  JF0011: 'nodes is not an object, or a node declaration is malformed',
+  JF0012: 'edges is not an array, or an edge entry is malformed',
+  JF0013: 'an edge from/to names no declared node',
+  JF0014: 'an embedded document failed to compile',
+  JF0015: 'the wiring rules are violated',
+  JF0016: 'the graph has a cycle',
+  JF0017: 'the document does not declare exactly one output node',
+  JF0018: 'a task node names a handler the registry does not provide',
+  JF2001: 'a state id the machine does not declare',
+  JF2002: 'step was called with a non-string event',
+  JF2003: 'a guard threw while evaluating',
+  JF2004: 'an effect with threw while evaluating',
+  JF2005: 'a session was created with no start state',
+  JF2006: 'a dag node failed while evaluating; the run rejects',
+  JF2007: 'the caller signal aborted the run',
+  JF2008: 'a declared checkpoint value is not JSON-serializable',
+  JF2009: 'the checkpoint store failed',
+});
+
+/**
+ * A defect in the flow document itself, raised while `compileFsm`
+ * compiles it. Codes:
+ *
+ *  - `JF0001` — the document is not an object, or `$fsm` is present and
+ *    not `'0.1'`
+ *  - `JF0002` — `states` is not an array, or a state entry is neither a
+ *    string nor an object with a string `id` (or carries a non-boolean
+ *    `final`)
+ *  - `JF0003` — two state entries share one id
+ *  - `JF0004` — `initial` is neither null nor the id of a declared state
+ *  - `JF0005` — `transitions` is not an array, or a transition entry is
+ *    malformed (not an object; `from`/`to` not strings; `event` neither
+ *    a string nor null)
+ *  - `JF0006` — a transition's `from` or `to` names no declared state
+ *  - `JF0007` — a guard failed to compile as a query document (see
+ *    `cause`)
+ *  - `JF0008` — an effects list is not an array, or an effect
+ *    descriptor is not an object with a non-empty string `run`
+ *  - `JF0009` — an effect's `with` failed to compile as a query
+ *    document (see `cause`)
+ *
+ * Dag documents (`compileDag`):
+ *
+ *  - `JF0010` — the dag document is not an object, or `$dag` is not
+ *    `'0.1'` (the key is required — the dag format has no legacy
+ *    contract to stay compatible with)
+ *  - `JF0011` — `nodes` is not an object, or a node declaration is
+ *    malformed (not an object; unknown `kind`; a kind-specific member
+ *    missing or mistyped: `const` needs `value`, `query` needs
+ *    `query`, `jslt` needs `stylesheet`, `task` needs a non-empty
+ *    string `run`)
+ *  - `JF0012` — `edges` is not an array, or an edge entry is malformed
+ *    (not an object; `from`/`to` not strings; `port` present but not a
+ *    non-empty string)
+ *  - `JF0013` — an edge's `from` or `to` names no declared node
+ *  - `JF0014` — an embedded document failed to compile (a node's
+ *    `query`/`stylesheet`/`with` or an edge's `select`; see `cause`)
+ *  - `JF0015` — the wiring rules are violated: an edge enters an
+ *    `input`/`const` node or leaves the `output` node; fan-in without
+ *    complete unique ports (a ported inbound set must be all-ported
+ *    and duplicate-free); or a consuming node (`query`/`jslt`/`task`/
+ *    `output`) has no inbound edge
+ *  - `JF0016` — the graph has a cycle (the message lists the member
+ *    ids; `docPath` points at the first edge inside it)
+ *  - `JF0017` — the document does not declare exactly one `output`
+ *    node
+ *  - `JF0018` — a `task` node names a handler the compile-time
+ *    registry does not provide
+ */
+export class FlowCompileError extends CodedError {
+  /**
+   * @param {string} code
+   * @param {string} reason - The bare reason; `message` is composed per
+   *   the coded contract.
+   * @param {string} [docPath] - JSON Pointer into the flow document;
+   *   `''` is the document root, `undefined` means no location.
+   * @param {Error} [cause]
+   */
+  constructor(code, reason, docPath, cause) {
+    super('FlowCompileError', code, reason, docPath,
+      cause !== undefined ? { cause } : undefined);
+  }
+}
+
+/**
+ * A failure while a compiled machine is being driven. Only caller
+ * mistakes throw; document-level evaluation failures never do — they
+ * fail closed and are recorded as plain data on the step result
+ * (FLOW-FORMAT §5.2). Codes:
+ *
+ *  - `JF2001` — `step`, `events` or `final` was called with a state id
+ *    the machine does not declare (thrown; a caller bug, not machine
+ *    input)
+ *  - `JF2002` — `step` was called with a non-string event (thrown)
+ *  - `JF2003` — a guard threw while evaluating (recorded on the step
+ *    result; the guard reads false and selection continues)
+ *  - `JF2004` — an effect's `with` threw while evaluating (recorded on
+ *    the step result; the effect is omitted)
+ *  - `JF2005` — a session was created with no start state (`initial`
+ *    is null and none was given) (thrown)
+ *
+ * Dag runs (`compileDag(...).run`) have no recorded-error channel —
+ * a failure rejects the run promise (fail closed, no partial results):
+ *
+ *  - `JF2006` — a node failed while evaluating; the run rejects, the
+ *    shared signal aborts in-flight siblings, and the error carries
+ *    the failing node's id as an own `nodeId` property beside
+ *    `docPath` and `cause`
+ *  - `JF2007` — the caller's `signal` aborted the run (`cause` is the
+ *    abort reason when one was given)
+ */
+export class FlowRuntimeError extends CodedError {
+  /**
+   * @param {string} code
+   * @param {string} reason - The bare reason; `message` is composed per
+   *   the coded contract.
+   * @param {string} [docPath] - JSON Pointer into the flow document;
+   *   `''` is the document root, `undefined` means no location.
+   * @param {Error} [cause]
+   */
+  constructor(code, reason, docPath, cause) {
+    super('FlowRuntimeError', code, reason, docPath,
+      cause !== undefined ? { cause } : undefined);
+  }
+}
+
+/**
+ * Normalize a thrown value to an `Error`. A dag run rejects with whatever
+ * a registered task threw, and a task is host code free to throw a
+ * non-Error, so the rejection contract needs one: a bare value becomes an
+ * `Error` naming the type it arrived as. In the fsm engine the only throw
+ * sources are the query engine's own error classes, so there it is
+ * belt-and-braces rather than hostile-input hardening.
+ * @param {unknown} v
+ * @returns {Error}
+ */
+export function asError(v) {
+  return v instanceof Error ? v : new Error(`non-Error thrown (${typeof v})`);
+}

package/src/fsm.js

@@ -0,0 +1,396 @@
+//@ts-check
+/**
+ * @file The jaren-fsm engine: compile a finite-state-machine document
+ * (docs/FLOW-FORMAT.md §2) into a PURE step function. Everything is
+ * decided once at compile time — guards and effect `with` members
+ * become compiled query closures — and the running machine holds no
+ * mutable state at all: `step(state, event, opts)` maps its arguments
+ * to a transition result, and `createFsmSession` is the thin mutable
+ * convenience over it.
+ *
+ * The engine never executes an effect. A fired transition RETURNS
+ * resolved effect descriptors as data (exit → transition → entry); how
+ * they run — as @jarenjs/app effects, or in any host loop — is the
+ * caller's registry, the same boundary discipline the rest of the
+ * suite keeps.
+ */
+
+import { isJsonObject } from '@jarenjs/core/object';
+import { compileJsonQuery } from '@jarenjs/json/query';
+import { asError, FlowCompileError, FlowRuntimeError } from './errors.js';
+
+/**
+ * A compiled effect: the registered handler name, the compiled `with`
+ * query (or null) and the descriptor's docPath for runtime records.
+ * @typedef {{ run: string, with: any, docPath: string }} CompiledEffect
+ */
+
+/**
+ * Compile one effects list (`entry`, `exit` or a transition's
+ * `effects`). Absent means none; anything else must be an array of
+ * `{ run, with? }` descriptors.
+ * @param {any} list
+ * @param {string} docPath - JSON Pointer of the list member.
+ * @returns {CompiledEffect[]}
+ */
+function compileEffectList(list, docPath) {
+  if (list === undefined) return [];
+  if (!Array.isArray(list)) {
+    throw new FlowCompileError('JF0008',
+      'an effects list must be an array of { run, with? } descriptors', docPath);
+  }
+  return list.map((effect, i) => {
+    const path = `${docPath}/${i}`;
+    if (!isJsonObject(effect) || typeof effect.run !== 'string' || effect.run === '') {
+      throw new FlowCompileError('JF0008',
+        'an effect descriptor must be an object with a non-empty string "run"', path);
+    }
+    let withQuery = null;
+    if (effect.with !== undefined) {
+      try {
+        withQuery = compileJsonQuery(effect.with);
+      }
+      catch (err) {
+        const cause = asError(err);
+        throw new FlowCompileError('JF0009',
+          `effect '${effect.run}' has a "with" that failed to compile: ${cause.message}`,
+          `${path}/with`, cause);
+      }
+    }
+    return { run: effect.run, with: withQuery, docPath: path };
+  });
+}
+
+/**
+ * Resolve one compiled effect against the evaluation scope. An empty
+ * query result omits the `with` member; a throwing `with` fails closed —
+ * the effect is omitted and the failure recorded (JF2004).
+ * @param {CompiledEffect} effect
+ * @param {any} scope
+ * @param {any[]} out - resolved descriptors, appended to
+ * @param {any[]} errors - step-result error records, appended to
+ */
+function resolveEffect(effect, scope, out, errors) {
+  if (effect.with === null) {
+    out.push({ run: effect.run });
+    return;
+  }
+  let value;
+  try {
+    value = effect.with(scope);
+  }
+  catch (err) {
+    errors.push({
+      code: 'JF2004',
+      docPath: `${effect.docPath}/with`,
+      message: `effect '${effect.run}' was omitted: its "with" threw while evaluating: ${asError(err).message}`,
+    });
+    return;
+  }
+  out.push(value === undefined ? { run: effect.run } : { run: effect.run, with: value });
+}
+
+/**
+ * The result of one pure step.
+ * @typedef {Object} FsmStepResult
+ * @property {boolean} changed - A transition fired. A self-transition
+ *   reports true with an unchanged `state`; inspect `state` to tell the
+ *   two apart.
+ * @property {string} state - The resulting state id.
+ * @property {any[]} effects - Resolved `{ run, with? }` descriptors in
+ *   firing order: exit → transition → entry (exit/entry only when the
+ *   state actually changed).
+ * @property {boolean} final - Whether the resulting state is final.
+ * @property {{ code: string, docPath: string, message: string }[]} errors -
+ *   Fail-closed evaluation records (JF2003/JF2004); empty on a clean step.
+ */
+
+/**
+ * A compiled jaren-fsm machine.
+ * @typedef {Object} CompiledFsm
+ * @property {string|null} initial - The document's initial state id.
+ * @property {readonly string[]} states - Declared state ids, document order.
+ * @property {(state: string) => readonly string[]} events - The unique
+ *   named events leaving a state (wildcards excluded), document order.
+ * @property {(state: string) => boolean} final - Whether a state is final.
+ * @property {(state: string, event: string, opts?: { payload?: any, context?: any }) => FsmStepResult} step -
+ *   The pure step function.
+ */
+
+/**
+ * Compile a jaren-fsm document (docs/FLOW-FORMAT.md) into a pure
+ * machine. Every guard and effect `with` member compiles once, here;
+ * `step` only runs specialized closures.
+ *
+ * The document contract is a strict superset of the mermaid
+ * `jaren-workflow` projection shape: `$fsm` is optional, a plain-string
+ * guard is a query (a `$`-path expression — any other non-empty string
+ * is a literal and therefore always true), and `guard: null` /
+ * `event: null` mean no guard / any event.
+ *
+ * @param {any} doc - the jaren-fsm document
+ * @returns {CompiledFsm}
+ * @throws {FlowCompileError} when the document violates the format (JF0xxx)
+ * @example
+ * const fsm = compileFsm({
+ *   initial: 'idle',
+ *   states: ['idle', 'busy'],
+ *   transitions: [{ from: 'idle', event: 'start', to: 'busy' }],
+ * });
+ * fsm.step('idle', 'start').state; // 'busy'
+ */
+export function compileFsm(doc) {
+  if (!isJsonObject(doc)) {
+    throw new FlowCompileError('JF0001', 'the fsm document must be an object', '');
+  }
+  if (doc.$fsm !== undefined && doc.$fsm !== '0.1') {
+    throw new FlowCompileError('JF0001',
+      `unknown fsm format version ${JSON.stringify(doc.$fsm)} (this engine speaks '0.1')`,
+      '/$fsm');
+  }
+
+  // states: string shorthand or { id, entry?, exit?, final? }
+  if (!Array.isArray(doc.states)) {
+    throw new FlowCompileError('JF0002',
+      'the "states" member must be an array of state declarations', '/states');
+  }
+  /** @type {Map<string, { entry: CompiledEffect[], exit: CompiledEffect[], final: boolean }>} */
+  const stateMap = new Map();
+  /** @type {string[]} */
+  const stateOrder = [];
+  for (let i = 0; i < doc.states.length; i++) {
+    const entry = doc.states[i];
+    const base = `/states/${i}`;
+    let id;
+    let meta = { entry: /** @type {CompiledEffect[]} */ ([]), exit: /** @type {CompiledEffect[]} */ ([]), final: false };
+    if (typeof entry === 'string') {
+      id = entry;
+    }
+    else if (isJsonObject(entry) && typeof entry.id === 'string') {
+      id = entry.id;
+      if (entry.final !== undefined && typeof entry.final !== 'boolean') {
+        throw new FlowCompileError('JF0002',
+          `state '${id}' has a non-boolean "final"`, `${base}/final`);
+      }
+      meta = {
+        entry: compileEffectList(entry.entry, `${base}/entry`),
+        exit: compileEffectList(entry.exit, `${base}/exit`),
+        final: entry.final === true,
+      };
+    }
+    else {
+      throw new FlowCompileError('JF0002',
+        `state ${i} must be a string id or an object with a string "id"`, base);
+    }
+    if (stateMap.has(id)) {
+      throw new FlowCompileError('JF0003',
+        `duplicate state id '${id}'`, base);
+    }
+    stateMap.set(id, meta);
+    stateOrder.push(id);
+  }
+
+  // initial: null, or a declared state id
+  const initial = doc.initial;
+  if (initial !== null && typeof initial !== 'string') {
+    throw new FlowCompileError('JF0004',
+      'the "initial" member must be a state id or null', '/initial');
+  }
+  if (initial !== null && !stateMap.has(initial)) {
+    throw new FlowCompileError('JF0004',
+      `the initial state '${initial}' is not declared in "states"`, '/initial');
+  }
+
+  // transitions: document order is the selection order (§4)
+  if (!Array.isArray(doc.transitions)) {
+    throw new FlowCompileError('JF0005',
+      'the "transitions" member must be an array of transition entries', '/transitions');
+  }
+  /** @type {Map<string, any[]>} */
+  const byFrom = new Map();
+  for (let i = 0; i < doc.transitions.length; i++) {
+    const t = doc.transitions[i];
+    const base = `/transitions/${i}`;
+    if (!isJsonObject(t)) {
+      throw new FlowCompileError('JF0005',
+        `transition ${i} must be an object`, base);
+    }
+    if (typeof t.from !== 'string') {
+      throw new FlowCompileError('JF0005',
+        `transition ${i} must carry a string "from"`, `${base}/from`);
+    }
+    if (typeof t.to !== 'string') {
+      throw new FlowCompileError('JF0005',
+        `transition ${i} must carry a string "to"`, `${base}/to`);
+    }
+    if (t.event !== undefined && t.event !== null && typeof t.event !== 'string') {
+      throw new FlowCompileError('JF0005',
+        `transition ${i} has an "event" that is neither a string nor null`, `${base}/event`);
+    }
+    if (!stateMap.has(t.from)) {
+      throw new FlowCompileError('JF0006',
+        `transition ${i} leaves the undeclared state '${t.from}'`, `${base}/from`);
+    }
+    if (!stateMap.has(t.to)) {
+      throw new FlowCompileError('JF0006',
+        `transition ${i} enters the undeclared state '${t.to}'`, `${base}/to`);
+    }
+    let guard = null;
+    if (t.guard !== undefined && t.guard !== null) {
+      try {
+        guard = compileJsonQuery(t.guard);
+      }
+      catch (err) {
+        const cause = asError(err);
+        throw new FlowCompileError('JF0007',
+          `transition ${i} has a guard that failed to compile: ${cause.message}`,
+          `${base}/guard`, cause);
+      }
+    }
+    const compiled = {
+      event: t.event === undefined || t.event === null ? null : t.event,
+      to: t.to,
+      guard,
+      guardPath: `${base}/guard`,
+      effects: compileEffectList(t.effects, `${base}/effects`),
+    };
+    const list = byFrom.get(t.from);
+    if (list === undefined) byFrom.set(t.from, [compiled]);
+    else list.push(compiled);
+  }
+
+  // per-state introspection: unique named events, document order
+  /** @type {Map<string, readonly string[]>} */
+  const eventsByState = new Map();
+  for (const id of stateOrder) {
+    const names = [];
+    for (const t of byFrom.get(id) ?? []) {
+      if (t.event !== null && !names.includes(t.event)) names.push(t.event);
+    }
+    eventsByState.set(id, Object.freeze(names));
+  }
+
+  /**
+   * @param {string} state
+   * @param {string} member
+   */
+  function assertKnown(state, member) {
+    if (!stateMap.has(state)) {
+      throw new FlowRuntimeError('JF2001',
+        `${member} was called with the undeclared state ${JSON.stringify(state)}`);
+    }
+  }
+
+  /** @type {CompiledFsm['step']} */
+  function step(state, event, opts) {
+    assertKnown(state, 'step');
+    if (typeof event !== 'string') {
+      throw new FlowRuntimeError('JF2002',
+        `step was called with a non-string event (${typeof event})`);
+    }
+    const scope = {
+      state,
+      event,
+      payload: opts?.payload ?? null,
+      context: opts?.context ?? null,
+    };
+    /** @type {FsmStepResult['errors']} */
+    const errors = [];
+    for (const t of byFrom.get(state) ?? []) {
+      if (t.event !== null && t.event !== event) continue;
+      if (t.guard !== null) {
+        let pass = false;
+        try {
+          pass = t.guard.ebv(scope);
+        }
+        catch (err) {
+          errors.push({
+            code: 'JF2003',
+            docPath: t.guardPath,
+            message: `the guard threw while evaluating and reads false: ${asError(err).message}`,
+          });
+        }
+        if (!pass) continue;
+      }
+      const effects = [];
+      const moved = state !== t.to;
+      if (moved) {
+        for (const e of /** @type {any} */ (stateMap.get(state)).exit) {
+          resolveEffect(e, scope, effects, errors);
+        }
+      }
+      for (const e of t.effects) resolveEffect(e, scope, effects, errors);
+      if (moved) {
+        for (const e of /** @type {any} */ (stateMap.get(t.to)).entry) {
+          resolveEffect(e, scope, effects, errors);
+        }
+      }
+      return {
+        changed: true,
+        state: t.to,
+        effects,
+        final: /** @type {any} */ (stateMap.get(t.to)).final,
+        errors,
+      };
+    }
+    return {
+      changed: false,
+      state,
+      effects: [],
+      final: /** @type {any} */ (stateMap.get(state)).final,
+      errors,
+    };
+  }
+
+  return Object.freeze({
+    initial: initial ?? null,
+    states: Object.freeze(stateOrder.slice()),
+    /** @type {CompiledFsm['events']} */
+    events(state) {
+      assertKnown(state, 'events');
+      return /** @type {readonly string[]} */ (eventsByState.get(state));
+    },
+    /** @type {CompiledFsm['final']} */
+    final(state) {
+      assertKnown(state, 'final');
+      return /** @type {any} */ (stateMap.get(state)).final;
+    },
+    step,
+  });
+}
+
+/**
+ * The thin mutable convenience over a compiled machine: it holds the
+ * current state and forwards to the pure `step`. Because `step` is
+ * pure, `can` IS a dry run — it evaluates guards but changes nothing.
+ * @param {CompiledFsm} fsm - a machine from {@link compileFsm}
+ * @param {string} [startState] - defaults to the document's `initial`
+ * @returns {{ readonly state: string, readonly done: boolean,
+ *   send: (event: string, opts?: { payload?: any, context?: any }) => FsmStepResult,
+ *   can: (event: string, opts?: { payload?: any, context?: any }) => boolean }}
+ * @throws {FlowRuntimeError} JF2005 when neither a start state nor a
+ *   document `initial` exists; JF2001 when the start state is undeclared.
+ */
+export function createFsmSession(fsm, startState) {
+  let current = startState ?? fsm.initial;
+  if (current === null || current === undefined) {
+    throw new FlowRuntimeError('JF2005',
+      'the session has no start state: the document\'s "initial" is null and none was given');
+  }
+  if (!fsm.states.includes(current)) {
+    throw new FlowRuntimeError('JF2001',
+      `the session start state ${JSON.stringify(current)} is not declared`);
+  }
+  return {
+    get state() { return /** @type {string} */ (current); },
+    get done() { return fsm.final(/** @type {string} */ (current)); },
+    send(event, opts) {
+      const result = fsm.step(/** @type {string} */ (current), event, opts);
+      current = result.state;
+      return result;
+    },
+    can(event, opts) {
+      return fsm.step(/** @type {string} */ (current), event, opts).changed;
+    },
+  };
+}

package/src/index.js

@@ -0,0 +1,13 @@
+//@ts-check
+/**
+ * @file @jarenjs/flow — executable workflow documents over the
+ * @jarenjs/json engines: the jaren-fsm finite-state-machine format
+ * compiled to a pure step function. See README.md and
+ * docs/FLOW-FORMAT.md.
+ */
+
+export { compileFsm, createFsmSession } from './fsm.js';
+export { fsmToApp, fsmStateSchema } from './app.js';
+export { compileDag } from './dag.js';
+export { snapshotFsm, resumeFsmSession, createDurableFsmSession } from './persist.js';
+export { FlowCompileError, FlowRuntimeError, FLOW_CODES } from './errors.js';

package/src/persist.js

@@ -0,0 +1,65 @@
+//@ts-check
+/**
+ * @file FSM persistence (FLOW-FORMAT §7.7): nothing new was needed —
+ * `step` is pure and a session's whole run state IS its current state
+ * string — so these helpers are deliberately thin. `snapshotFsm`
+ * captures a session as JSON, `resumeFsmSession` rebuilds one (the
+ * existing JF2001 refusal covers a snapshot naming an undeclared
+ * state), and `createDurableFsmSession` persists through a
+ * SYNCHRONOUS `{ load, save }` store on every state CHANGE — a store
+ * that throws fails the send, never loses a transition silently. An
+ * asynchronous store composes its own wrapper; the session contract
+ * stays synchronous.
+ */
+
+import { createFsmSession } from './fsm.js';
+
+/**
+ * Capture a session's durable state — the whole of it.
+ * @param {{ state: string, done: boolean }} session
+ * @returns {{ state: string }}
+ */
+export function snapshotFsm(session) {
+  return { state: session.state };
+}
+
+/**
+ * Rebuild a session from a snapshot. An undeclared state refuses with
+ * the session's own JF2001.
+ * @param {any} fsm - a machine from `compileFsm`
+ * @param {{ state: string }} snapshot
+ */
+export function resumeFsmSession(fsm, snapshot) {
+  if (snapshot === null || typeof snapshot !== 'object'
+    || typeof snapshot.state !== 'string') {
+    throw new TypeError('resumeFsmSession: the snapshot must carry a string "state"');
+  }
+  return createFsmSession(fsm, snapshot.state);
+}
+
+/**
+ * A session that persists its state through a synchronous store:
+ * `load()` answers the stored state (or null/undefined for a fresh
+ * start), `save(state)` records each CHANGED state before the step
+ * result is returned.
+ * @param {any} fsm - a machine from `compileFsm`
+ * @param {{ load: () => string | null | undefined,
+ *   save: (state: string) => void }} store
+ */
+export function createDurableFsmSession(fsm, store) {
+  if (typeof store?.load !== 'function' || typeof store.save !== 'function') {
+    throw new TypeError('createDurableFsmSession: the store must provide load and save');
+  }
+  const stored = store.load();
+  const session = createFsmSession(fsm, stored ?? undefined);
+  return Object.freeze({
+    get state() { return session.state; },
+    get done() { return session.done; },
+    can: (event, opts) => session.can(event, opts),
+    send(event, opts) {
+      const result = session.send(event, opts);
+      if (result.changed) store.save(result.state);
+      return result;
+    },
+  });
+}