@jarenjs/flow 0.49.2 → 0.66.1

package/README.md

@@ -190,7 +190,7 @@ built with `@jarenjs/flow` and XState v5 and asserted to agree before
 timing:
 
 - **Transitions** — the pure `step` runs several times faster than an
-  XState actor's `send` (≈<!--bm:flow.fsmBand-->5.6–8.1<!--/bm-->× across 5/50/500-state machines); the
+  XState actor's `send` (≈<!--fact:flow.fsmBand-->5.6–8.1<!--/fact-->× across 5/50/500-state machines); the
   `createFsmSession` wrapper is on the page too.
 - **Compile** — `compileFsm` beats `createMachine` + `createActor`
   ≈1.5–2.6×. Not like-for-like: XState builds a scheduling actor, so the
@@ -227,6 +227,56 @@ section shows the `composeChecks(schema, compileGate)` recipe, and
 runs a model as an ordinary dag `task`. Neither package imports the
 other — the composition is data.
 
+## Authoring by code
+
+The same documents have a by-code twin. `@jarenjs/linq/flow` is the
+suite's pen for both formats: state ids, event names and node ids are
+literal types, so a transition into an undeclared state or an edge from
+an undeclared node is a compile error, and guards, effect props, node
+queries and edge selectors are callbacks captured over the scope the
+engine evaluates them in — never a path typed as a string.
+
+```javascript
+import { defineFsm, on, state, effect } from '@jarenjs/linq/flow';
+
+const doc = defineFsm({
+  initial: 'idle',
+  states: [
+    'idle',
+    state('loading', { entry: [effect('fetch', (s) => ({ url: s.context.url }))] }),
+    state('done', { final: true }),
+  ],
+  transitions: [
+    on('idle', 'start').to('loading'),
+    on('loading', 'ok').when((s) => s.payload.fresh).to('done'),
+    on('loading', 'fail').to('idle'),
+  ],
+});                                // the document at the top of this README, byte for byte
+
+compileFsm(doc).step('idle', 'start', { context: { url: '/rows' } });
+```
+
+A model-authored document and a pen-written one go through the SAME
+gate — `compileFsm`/`compileDag`. The mapping table, and where the pen's
+refusals end and the compiler's begin, are
+[FLOW-PEN.md](../linq/docs/FLOW-PEN.md).
+
+## Exports
+
+Every subpath a consumer can import, derived from the manifest by
+`npm run docs:derive` (`npm run docs:check` fails when the two drift):
+
+<!--fact:exports.flow-->
+| Import | Kind | Declarations |
+|---|---|---|
+| `@jarenjs/flow` | JavaScript | declared |
+| `@jarenjs/flow/schemas/jaren-dag.draft-07.schema.json` | schema | — |
+| `@jarenjs/flow/schemas/jaren-dag.schema.json` | schema | — |
+| `@jarenjs/flow/schemas/jaren-fsm.draft-07.schema.json` | schema | — |
+| `@jarenjs/flow/schemas/jaren-fsm.schema.json` | schema | — |
+| `@jarenjs/flow/package.json` | metadata | — |
+<!--/fact-->
+
 ## Development
 
 Unit tests live in `test/flow/` at the repository root

package/dist/types/dag.d.ts

@@ -31,6 +31,13 @@ export type CompiledDag = {
      * - The output node's id.
      */
     output: string;
+    /**
+     * - Every
+     * declared task identity this workflow depends on, keyed by node id and
+     * SORTED (§7.8); a nested workflow's map composes under its node's
+     * path. Empty when no node declares a version.
+     */
+    taskVersions: Readonly<Record<string, string>>;
     /**
      * -
      * Execute the graph for one input (`undefined` reads as `null`).
@@ -41,30 +48,6 @@ export type CompiledDag = {
         runId?: string;
     }) => Promise<any>;
 };
-/**
- * A settlement record handed to `onNode` (§7.4). `restored` fires at
- * the start of a RESUMED run for every node whose checkpointed value
- * was seeded instead of evaluated (§7.6).
- * @typedef {{ id: string, status: 'ok'|'error'|'aborted'|'restored', ms: number }} DagNodeRecord
- */
-/**
- * The opt-in checkpoint store (§7.6): `load` answers a prior run's
- * recorded values (or null), `save` records one declared node's
- * value, `complete` records the run's result. Any member may return a
- * promise; a throwing store fails the run (JF2009), never silently.
- * @typedef {Object} DagCheckpointStore
- * @property {(runId: string) => any} load
- * @property {(runId: string, nodeId: string, value: any) => any} save
- * @property {(runId: string, result: any) => any} complete
- */
-/**
- * A compiled jaren-dag graph.
- * @typedef {Object} CompiledDag
- * @property {readonly string[]} nodes - Declared node ids, document order.
- * @property {string} output - The output node's id.
- * @property {(input?: any, opts?: { signal?: AbortSignal, onNode?: (record: DagNodeRecord) => void, runId?: string }) => Promise<any>} run -
- *   Execute the graph for one input (`undefined` reads as `null`).
- */
 /**
  * Compile a jaren-dag document (docs/FLOW-FORMAT.md §6–§7) against a
  * task registry. Everything is decided here: structural validation,
@@ -72,7 +55,9 @@ export type CompiledDag = {
  * registry resolution — `run` only executes closures.
  *
  * @param {any} doc - the jaren-dag document
- * @param {{ tasks?: Record<string, (props: { with: any, input: any }, signal: AbortSignal) => any>,
+ * @param {{ tasks?: Record<string, ((props: { with: any, input: any }, signal: AbortSignal) => any)
+ *     | { run: (props: { with: any, input: any }, signal: AbortSignal) => any, version?: string,
+ *         taskVersions?: Record<string, string> }>,
  *   checkpoint?: DagCheckpointStore }} [options]
  * @returns {CompiledDag}
  * @throws {FlowCompileError} when the document violates the format (JF0xxx)
@@ -81,9 +66,16 @@ export type CompiledDag = {
  *   checkpoint store missing one of load/save/complete)
  */
 export declare function compileDag(doc: any, options?: {
-    tasks?: Record<string, (props: {
+    tasks?: Record<string, ((props: {
         with: any;
         input: any;
-    }, signal: AbortSignal) => any>;
+    }, signal: AbortSignal) => any) | {
+        run: (props: {
+            with: any;
+            input: any;
+        }, signal: AbortSignal) => any;
+        version?: string;
+        taskVersions?: Record<string, string>;
+    }>;
     checkpoint?: DagCheckpointStore;
 }): CompiledDag;

package/dist/types/errors.d.ts

@@ -33,6 +33,7 @@ export declare const FLOW_CODES: Readonly<{
     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";
+    JF0019: "a task node and its registered handler disagree about the handler version";
     JF2001: "a state id the machine does not declare";
     JF2002: "step was called with a non-string event";
     JF2003: "a guard threw while evaluating";

package/dist/types/persist.d.ts

@@ -5,9 +5,10 @@
  * 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
+ * SYNCHRONOUS `{ load, save }` store on every fired transition,
+ * including self-transitions — a store that throws leaves the session
+ * at its previous state, so the event can be retried without losing a
+ * transition. An asynchronous store composes its own wrapper; the session contract
  * stays synchronous.
  */
 /**
@@ -44,8 +45,10 @@ export declare function resumeFsmSession(fsm: any, snapshot: {
 /**
  * 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.
+ * start), `save(state)` records every fired transition's state,
+ * including self-transitions, before the step result is returned and
+ * the session advances. A failed save leaves
+ * the session unchanged.
  * @param {any} fsm - a machine from `compileFsm`
  * @param {{ load: () => string | null | undefined,
  *   save: (state: string) => void }} store
@@ -57,5 +60,5 @@ export declare function createDurableFsmSession(fsm: any, store: {
     readonly state: string;
     readonly done: boolean;
     can: (event: any, opts: any) => boolean;
-    send(event: any, opts: any): import("./fsm.js").FsmStepResult;
+    send(event: any, opts: any): any;
 }>;

package/docs/FLOW-FORMAT.md

@@ -67,6 +67,15 @@ honestly-stated divergences, is specified in
 [APP-INTEGRATION.md](APP-INTEGRATION.md); nothing there changes the
 format defined here.
 
+Documents in both formats are authored by hand, projected from a
+diagram, decoded by a model under the published grammar, or written by
+code: `@jarenjs/linq/flow` is the suite's by-code producer
+(`defineFsm`, `defineDag`), and it emits exactly the documents this
+section defines — its guards, effect props, node queries and edge
+selectors are callbacks captured over the scopes §3 and §6.1 fix. It
+imports nothing of this package; the compilers here remain the only
+judge of what a document means.
+
 ## §2 The jaren-fsm document
 
 ```json
@@ -201,6 +210,7 @@ tables there and here MUST stay in sync.
 | JF0016 | the graph has a cycle (member ids in the message, `docPath` at the first edge inside it) |
 | JF0017 | not exactly one `output` node |
 | JF0018 | a `task` node names no registered handler |
+| JF0019 | a `task` node and its registered handler disagree about the handler version |
 
 ### §5.2 Runtime: thrown vs recorded
 
@@ -296,7 +306,8 @@ A node's `$` is decided by its inbound edges:
   inbound edge MUST name one, ports MUST be unique, and `$` is the
   object of port-named values, members in **edge document order**. A
   single ported edge therefore yields `{ port: value }` — the way to
-  force the object shape.
+  force the object shape. Each port is an own object member, including
+  names that also occur on `Object.prototype`.
 - Two or more unported inbound edges are a compile error (JF0015).
 
 A delivery whose `select` yields the empty sequence delivers `null`; a
@@ -420,6 +431,51 @@ await dag.run(input, { runId: 'run-42' });
   reason). Values recorded for node ids the current document does not
   declare (or no longer declares `checkpoint`) are ignored.
 
+### §7.8 Declared task versions
+
+A checkpointed node's value is REPLAYED on a later run instead of being
+recomputed. That is sound only while the handler that produced it is the
+same handler. So a `task` node that declares `checkpoint: true` must also
+declare `version`: a non-empty string naming the identity of the
+implementation it depends on.
+
+```jsonc
+{ "kind": "task", "run": "summarise", "version": "2026-09-05", "checkpoint": true }
+```
+
+**The identity is declared, never derived.** Hashing the handler's source
+would call a reformat a new task and a changed dependency the same one;
+neither is what a caller means. The host states it, and the host is the
+only party that knows when its implementation actually changed.
+
+**The registry must agree.** A registered handler is either a bare
+function — the shorthand, which carries no version — or
+`{ run, version }`. A node that declares a version against a bare handler,
+or against a different version, is `JF0019` at COMPILE time, before any
+node runs. The shorthand therefore serves exactly the workflows that
+checkpoint nothing, and a checkpointed node cannot use it.
+
+`version` is allowed on a node that does not checkpoint, so a workflow can
+carry one identity vocabulary throughout.
+
+**The canonical map.** A compiled workflow answers `taskVersions`: every
+declared identity it depends on, keyed by node id and SORTED, so two
+compiles of the same document produce the same map — byte for byte —
+whatever order the declarations were written in. A handler that is itself
+a compiled workflow may expose its own `taskVersions`; those compose under
+the node's path (`outer`, `outer/inner`), so a composed run has one
+identity rather than two. Every task id is retained as an own member,
+including names inherited by ordinary JavaScript objects.
+
+```js
+compileDag(doc, { tasks: { summarise: { version: '2026-09-05', run: handler } } })
+  .taskVersions; // → { "draft": "2026-09-05", "draft/tidy": "1" }
+```
+
+That map is what a durable queue fingerprints alongside the workflow
+revision and the input, so a run cannot resume onto checkpoints written by
+an implementation nobody is running any more.
+
 ### §7.7 FSM persistence
 
 Needs nothing new: `step` is pure and a session's whole durable state
@@ -427,9 +483,11 @@ IS its current state string. `@jarenjs/flow` ships three thin helpers
 — `snapshotFsm(session)` → `{ state }`, `resumeFsmSession(fsm,
 snapshot)` (an undeclared state refuses with the session's own
 JF2001), and `createDurableFsmSession(fsm, { load, save })`, which
-persists through a SYNCHRONOUS store on every state CHANGE, before
-the step result returns; a throwing `save` fails the send rather than
-lose a transition. A worked example over a `@jarenjs/db` collection:
+persists through a SYNCHRONOUS store on every fired transition,
+including self-transitions (`changed: true`), before
+the step result returns and the session advances; a throwing `save`
+leaves the session unchanged so the event can be retried. A worked
+example over a `@jarenjs/db` collection:
 
 ```js
 const machine = compileFsm(doc);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/flow",
   "private": false,
-  "version": "0.49.2",
+  "version": "0.66.1",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -49,7 +49,7 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.49.2",
-    "@jarenjs/json": "^0.49.2"
+    "@jarenjs/core": "^0.66.1",
+    "@jarenjs/json": "^0.66.1"
   }
 }

package/schemas/jaren-dag.draft-07.schema.json

@@ -146,6 +146,11 @@
               "type": "string",
               "minLength": 1
             },
+            "version": {
+              "description": "The declared identity of the handler implementation this node depends on (FLOW-FORMAT section 7.8). REQUIRED when checkpoint is true: a recorded value is replayed only while the handler that produced it is the same one, and that identity is declared, never derived from source. The registry must supply the same token.",
+              "type": "string",
+              "minLength": 1
+            },
             "with": {
               "description": "Handler props: a query resolved against the node's input scope (null when absent or empty).",
               "allOf": [

package/schemas/jaren-dag.schema.json

@@ -146,6 +146,11 @@
               "type": "string",
               "minLength": 1
             },
+            "version": {
+              "description": "The declared identity of the handler implementation this node depends on (FLOW-FORMAT section 7.8). REQUIRED when checkpoint is true: a recorded value is replayed only while the handler that produced it is the same one, and that identity is declared, never derived from source. The registry must supply the same token.",
+              "type": "string",
+              "minLength": 1
+            },
             "with": {
               "description": "Handler props: a query resolved against the node's input scope (null when absent or empty).",
               "allOf": [

package/src/dag.js

@@ -18,7 +18,7 @@ import { compileJsonQuery } from '@jarenjs/json/query';
 import { compileJsltStylesheet } from '@jarenjs/json/jslt';
 import { canonicalizeJson } from '@jarenjs/json/canonical';
 import { encodeJSONPointerSegment } from '@jarenjs/json/pointer';
-import { isJsonObject } from '@jarenjs/core/object';
+import { isJsonObject, setObjectMember } from '@jarenjs/core/object';
 import { asError, FlowCompileError, FlowRuntimeError } from './errors.js';
 
 const KINDS = ['input', 'output', 'const', 'query', 'jslt', 'task'];
@@ -67,10 +67,49 @@ function compileEmbedded(compile, embedded, docPath) {
  * @typedef {Object} CompiledDag
  * @property {readonly string[]} nodes - Declared node ids, document order.
  * @property {string} output - The output node's id.
+ * @property {Readonly<Record<string, string>>} taskVersions - Every
+ *   declared task identity this workflow depends on, keyed by node id and
+ *   SORTED (§7.8); a nested workflow's map composes under its node's
+ *   path. Empty when no node declares a version.
  * @property {(input?: any, opts?: { signal?: AbortSignal, onNode?: (record: DagNodeRecord) => void, runId?: string }) => Promise<any>} run -
  *   Execute the graph for one input (`undefined` reads as `null`).
  */
 
+/**
+ * One registry entry, in either accepted spelling.
+ *
+ * `{ run, version }` is the full one. A bare function is the shorthand,
+ * and it carries no version — which is why a checkpointed node, whose
+ * declared version has nothing to be compared against, cannot use it.
+ * An entry may also expose a `taskVersions` map of its own: a handler
+ * that is itself a compiled workflow contributes its versions under this
+ * node's path, so a composed run has one identity, not two.
+ * @param {any} entry
+ * @param {string} name
+ * @returns {{ run: Function, version: string | null, taskVersions: Record<string, string> | null }}
+ */
+function normalizeTaskEntry(entry, name) {
+  if (typeof entry === 'function') return { run: entry, version: null, taskVersions: null };
+  if (!isJsonObject(entry) || typeof entry.run !== 'function') {
+    throw new TypeError(
+      `compileDag: the registered handler '${name}' is not a function, nor { run, version }`);
+  }
+  if (entry.version !== undefined
+    && (typeof entry.version !== 'string' || entry.version === '')) {
+    throw new TypeError(
+      `compileDag: the registered handler '${name}' has a version that is not a non-empty string`);
+  }
+  if (entry.taskVersions !== undefined && !isJsonObject(entry.taskVersions)) {
+    throw new TypeError(
+      `compileDag: the registered handler '${name}' has a taskVersions that is not an object`);
+  }
+  return {
+    run: entry.run,
+    version: entry.version ?? null,
+    taskVersions: entry.taskVersions ?? null,
+  };
+}
+
 /**
  * Compile a jaren-dag document (docs/FLOW-FORMAT.md §6–§7) against a
  * task registry. Everything is decided here: structural validation,
@@ -78,7 +117,9 @@ function compileEmbedded(compile, embedded, docPath) {
  * registry resolution — `run` only executes closures.
  *
  * @param {any} doc - the jaren-dag document
- * @param {{ tasks?: Record<string, (props: { with: any, input: any }, signal: AbortSignal) => any>,
+ * @param {{ tasks?: Record<string, ((props: { with: any, input: any }, signal: AbortSignal) => any)
+ *     | { run: (props: { with: any, input: any }, signal: AbortSignal) => any, version?: string,
+ *         taskVersions?: Record<string, string> }>,
  *   checkpoint?: DagCheckpointStore }} [options]
  * @returns {CompiledDag}
  * @throws {FlowCompileError} when the document violates the format (JF0xxx)
@@ -160,16 +201,45 @@ export function compileDag(doc, options) {
           throw new FlowCompileError('JF0011',
             `task node '${id}' must carry a non-empty string "run"`, `${base}/run`);
         }
+        if (decl.version !== undefined
+          && (typeof decl.version !== 'string' || decl.version === '')) {
+          throw new FlowCompileError('JF0011',
+            `task node '${id}' has a "version" member that is not a non-empty string`,
+            `${base}/version`);
+        }
+        // a checkpointed node's output is REPLAYED on a later run, which
+        // is only sound while the implementation that produced it is the
+        // same implementation. That identity is declared, never derived:
+        // hashing a closure's source would call a reformat a new task and
+        // a changed dependency the same one
+        if (node.checkpoint && decl.version === undefined) {
+          throw new FlowCompileError('JF0011',
+            `task node '${id}' declares checkpoint, so it must also declare a "version" — `
+            + 'a checkpointed result is replayed only while the handler that produced it is '
+            + 'the same one, and that identity has to be stated', `${base}/version`);
+        }
         if (!Object.hasOwn(tasks, decl.run)) {
           throw new FlowCompileError('JF0018',
             `task node '${id}' names the handler '${decl.run}', which the registry does not provide`,
             `${base}/run`);
         }
-        if (typeof tasks[decl.run] !== 'function') {
-          throw new TypeError(
-            `compileDag: the registered handler '${decl.run}' is not a function`);
+        const entry = normalizeTaskEntry(tasks[decl.run], decl.run);
+        if (decl.version !== undefined) {
+          if (entry.version === null) {
+            throw new FlowCompileError('JF0019',
+              `task node '${id}' declares version '${decl.version}', but the registry provides `
+              + `'${decl.run}' as a bare handler with no version — register it as `
+              + '{ run, version } so the two can be compared', `${base}/version`);
+          }
+          if (entry.version !== decl.version) {
+            throw new FlowCompileError('JF0019',
+              `task node '${id}' declares version '${decl.version}', but the registry provides `
+              + `'${decl.run}' at version '${entry.version}'`, `${base}/version`);
+          }
         }
-        node.handler = tasks[decl.run];
+        node.handler = entry.run;
+        node.version = decl.version ?? null;
+        node.nestedVersions = entry.taskVersions;
         node.with = decl.with === undefined
           ? null
           : compileEmbedded(compileJsonQuery, decl.with, `${base}/with`);
@@ -449,7 +519,7 @@ export function compileDag(doc, options) {
         if (node.ports) {
           scope = {};
           for (let i = 0; i < node.inbound.length; i++) {
-            scope[node.inbound[i].port] = delivered[i];
+            setObjectMember(scope, node.inbound[i].port, delivered[i]);
           }
         }
         else if (node.inbound.length === 1) {
@@ -552,9 +622,28 @@ export function compileDag(doc, options) {
     return result;
   }
 
+  // The canonical version map: every declared task identity this
+  // workflow depends on, keyed by node path and SORTED, so two compiles
+  // of the same document answer the same map whatever order the
+  // declarations were written in. A handler that is itself a workflow
+  // contributes its own map under this node's path.
+  /** @type {Record<string, string>} */
+  const versions = {};
+  for (const node of nodes.values()) {
+    if (node.kind !== 'task' || node.version === null) continue;
+    setObjectMember(versions, node.id, node.version);
+    if (node.nestedVersions === null) continue;
+    for (const [path, version] of Object.entries(node.nestedVersions)) {
+      setObjectMember(versions, `${node.id}/${path}`, version);
+    }
+  }
+  const taskVersions = Object.freeze(Object.fromEntries(
+    Object.keys(versions).sort().map((key) => [key, versions[key]])));
+
   return Object.freeze({
     nodes: Object.freeze(order.slice()),
     output: outputId,
+    taskVersions,
     run,
   });
 }

package/src/errors.js

@@ -36,6 +36,7 @@ export const FLOW_CODES = Object.freeze({
   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',
+  JF0019: 'a task node and its registered handler disagree about the handler version',
   JF2001: 'a state id the machine does not declare',
   JF2002: 'step was called with a non-string event',
   JF2003: 'a guard threw while evaluating',

package/src/persist.js

@@ -6,9 +6,10 @@
  * 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
+ * SYNCHRONOUS `{ load, save }` store on every fired transition,
+ * including self-transitions — a store that throws leaves the session
+ * at its previous state, so the event can be retried without losing a
+ * transition. An asynchronous store composes its own wrapper; the session contract
  * stays synchronous.
  */
 
@@ -40,8 +41,10 @@ export function resumeFsmSession(fsm, snapshot) {
 /**
  * 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.
+ * start), `save(state)` records every fired transition's state,
+ * including self-transitions, before the step result is returned and
+ * the session advances. A failed save leaves
+ * the session unchanged.
  * @param {any} fsm - a machine from `compileFsm`
  * @param {{ load: () => string | null | undefined,
  *   save: (state: string) => void }} store
@@ -51,14 +54,15 @@ export function createDurableFsmSession(fsm, store) {
     throw new TypeError('createDurableFsmSession: the store must provide load and save');
   }
   const stored = store.load();
-  const session = createFsmSession(fsm, stored ?? undefined);
+  let 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);
+      const result = fsm.step(session.state, event, opts);
       if (result.changed) store.save(result.state);
+      session = createFsmSession(fsm, result.state);
       return result;
     },
   });