@jarenjs/flow 0.72.2 → 0.73.0

package/README.md

@@ -1,6 +1,8 @@
 # @jarenjs/flow
 
-Executable workflow documents, in two formats. The **jaren-fsm format**
+Executable JSON workflows: flat FSMs, statecharts, DAGs, and a composition
+compiler that combines long-lived control with concurrent work regions.
+The **jaren-fsm 0.1 format**
 is a finite state machine as one JSON value — declared states, an
 initial state, and a document-ordered transition table whose guards and
 effect props are [Jaren JSON Query](../json/docs/QUERY-FORMAT.md)
@@ -10,6 +12,12 @@ own engines — query documents, JSLT stylesheets, registered async
 tasks — wired by edges that carry data and compiled into a
 run-to-completion executor.
 
+`compileStatechart` adds compound states, parallel regions, shallow/deep
+history and explicit-time delayed transitions in jaren-fsm 0.2.
+`compileWorkflow` lowers one composed document onto statechart control and
+DAG work, with choices, bounded loops, nested flows, saved waits and
+generation-fenced checkpoints. Existing 0.1 APIs keep their behavior.
+
 It is the executable half of a round trip the suite already ships: a
 `stateDiagram-v2` parsed by [`@jarenjs/mermaid`](../../components/mermaid)
 projects (via a JSLT stylesheet) into exactly this shape, and this
@@ -20,10 +28,51 @@ The grammar is published as JSON Schema in
 [`schemas/jaren-fsm.schema.json`](schemas/jaren-fsm.schema.json) (with a
 mechanically derived draft-07 twin for providers pinned to older
 drafts) — hand it to a constrained decoder and a language model cannot
-emit a machine with an unknown member or a malformed guard. The
+emit a machine with a structurally malformed guard. The
 normative contract is [docs/FLOW-FORMAT.md](docs/FLOW-FORMAT.md). Zero
 dependencies outside the suite; no `eval`, CSP-safe; the only runtime
-import is `@jarenjs/json`.
+dependencies are `@jarenjs/core` and `@jarenjs/json`.
+
+## Composed workflows and statecharts
+
+```js
+import { compileWorkflow } from '@jarenjs/flow';
+
+const workflow = compileWorkflow({
+  $workflow: '0.2', revision: 'review/1', initial: 'prepare',
+  states: {
+    prepare: { work: { task: 'prepare', version: '1' }, then: 'review' },
+    review: { on: [{ event: 'approve', to: 'done' }] },
+    done: { final: true },
+  },
+}, { tasks: { prepare: { version: '1', run: ({ input }) => ({ ...input, ready: true }) } } });
+
+const first = await workflow.run({ title: 'Draft' }, { runId: 'review-7' });
+const done = await workflow.run({ title: 'Draft' }, {
+  runId: 'review-7', snapshot: first.snapshot, event: { type: 'approve' },
+});
+// done.result = { title: 'Draft', ready: true }
+```
+
+Use `work: {dag: document}` for concurrent branches, `choose` for guarded
+switches, `flow` for nested control, and `limit` to bound a loop. An optional
+CAS store persists node values and control before advancing. The compiler
+rejects a resume whose document, input or task identities changed.
+[WORKFLOW-FORMAT.md](docs/WORKFLOW-FORMAT.md) defines lowering, scope,
+idempotency keys, crash windows and the benchmark command that consumes it.
+
+For statecharts directly, `compileStatechart(doc).start({now})` returns the
+initial control snapshot and entry-effect descriptors. `step(state,event)`
+handles an event; `advance(state,now)` processes deadlines supplied by the
+host. Snapshots include active leaves, history and pending timers.
+`createStatechartSession` provides synchronous save-before-advance sessions.
+[STATECHART-FORMAT.md](docs/STATECHART-FORMAT.md) specifies the semantics.
+Neither API silently upgrades a 0.1 FSM or its string snapshots.
+
+Both formats publish canonical, draft-07 and derived authoring schemas.
+`createGrammarAuthor` accepts `statechart` and `workflow` with their full
+schema/compiler gates. The existing LINQ flow pen continues to author the
+0.1 FSM and DAG documents; its DAG documents can be embedded as work regions.
 
 ## The format in one glance
 
@@ -280,6 +329,14 @@ Every subpath a consumer can import, derived from the manifest by
 | `@jarenjs/flow/schemas/jaren-fsm.authoring.schema.json` | schema | — |
 | `@jarenjs/flow/schemas/jaren-fsm.draft-07.schema.json` | schema | — |
 | `@jarenjs/flow/schemas/jaren-fsm.schema.json` | schema | — |
+| `@jarenjs/flow/schemas/jaren-statechart-state.draft-07.schema.json` | schema | — |
+| `@jarenjs/flow/schemas/jaren-statechart-state.schema.json` | schema | — |
+| `@jarenjs/flow/schemas/jaren-statechart.authoring.schema.json` | schema | — |
+| `@jarenjs/flow/schemas/jaren-statechart.draft-07.schema.json` | schema | — |
+| `@jarenjs/flow/schemas/jaren-statechart.schema.json` | schema | — |
+| `@jarenjs/flow/schemas/jaren-workflow.authoring.schema.json` | schema | — |
+| `@jarenjs/flow/schemas/jaren-workflow.draft-07.schema.json` | schema | — |
+| `@jarenjs/flow/schemas/jaren-workflow.schema.json` | schema | — |
 | `@jarenjs/flow/package.json` | metadata | — |
 <!--/fact-->
 

package/dist/types/dag.d.ts

@@ -18,9 +18,9 @@ export type DagNodeRecord = {
     ms: number;
 };
 export type DagCheckpointStore = {
-    load: (runId: string) => any;
-    save: (runId: string, nodeId: string, value: any) => any;
-    complete: (runId: string, result: any) => any;
+    load: (runId: string, identity?: any) => any;
+    save: (runId: string, nodeId: string, value: any, identity?: any) => any;
+    complete: (runId: string, result: any, identity?: any) => any;
 };
 export type CompiledDag = {
     /**
@@ -46,6 +46,7 @@ export type CompiledDag = {
         signal?: AbortSignal;
         onNode?: (record: DagNodeRecord) => void;
         runId?: string;
+        drainOnAbort?: boolean;
     }) => Promise<any>;
 };
 /**
@@ -58,7 +59,7 @@ export type CompiledDag = {
  * @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]
+ *   checkpoint?: DagCheckpointStore, revision?: string }} [options]
  * @returns {CompiledDag}
  * @throws {FlowCompileError} when the document violates the format (JF0xxx)
  * @throws {TypeError} when the options are malformed (a registry that is
@@ -78,4 +79,5 @@ export declare function compileDag(doc: any, options?: {
         taskVersions?: Record<string, string>;
     }>;
     checkpoint?: DagCheckpointStore;
+    revision?: string;
 }): CompiledDag;

package/dist/types/errors.d.ts

@@ -34,6 +34,9 @@ export declare const FLOW_CODES: Readonly<{
     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";
+    JF0020: "a statechart declaration violates hierarchy or transition rules";
+    JF0021: "a workflow declaration or reference is malformed";
+    JF0022: "an automatic workflow cycle has no declared visit bound";
     JF2001: "a state id the machine does not declare";
     JF2002: "step was called with a non-string event";
     JF2003: "a guard threw while evaluating";
@@ -43,6 +46,13 @@ export declare const FLOW_CODES: Readonly<{
     JF2007: "the caller signal aborted the run";
     JF2008: "a declared checkpoint value is not JSON-serializable";
     JF2009: "the checkpoint store failed";
+    JF2010: "a statechart snapshot is malformed or has an illegal configuration";
+    JF2011: "explicit time moved backwards or a timer exceeded its numeric range";
+    JF2012: "a statechart exceeded its microstep limit";
+    JF2013: "a checkpoint belongs to a different workflow, input or task implementation";
+    JF2014: "a workflow run is busy or its snapshot generation is stale";
+    JF2015: "a workflow state exceeded its declared visit bound";
+    JF2016: "a workflow snapshot is malformed or execution could not progress";
 }>;
 /**
  * A defect in the flow document itself, raised while `compileFsm`

package/dist/types/fsm.d.ts

@@ -18,6 +18,30 @@ export type CompiledEffect = {
     with: any;
     docPath: string;
 };
+/**
+ * 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[]}
+ */
+export declare function compileEffectList(list: any, docPath: string): CompiledEffect[];
+/**
+ * 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
+ */
+export declare function resolveEffect(effect: CompiledEffect, scope: any, out: any[], errors: any[]): void;
 export type FsmStepResult = {
     /**
      * - A transition fired. A self-transition

package/dist/types/index.d.ts

@@ -7,5 +7,23 @@
 export { compileFsm, createFsmSession } from './fsm.js';
 export { fsmToApp, fsmStateSchema } from './app.js';
 export { compileDag } from './dag.js';
+export { compileStatechart, createStatechartSession } from './statechart.js';
+export { lowerWorkflow, compileWorkflow } from './workflow.js';
 export { snapshotFsm, resumeFsmSession, createDurableFsmSession } from './persist.js';
 export { FlowCompileError, FlowRuntimeError, FLOW_CODES } from './errors.js';
+export type StatechartState = import('./statechart.js').StatechartState;
+export type StatechartResult = import('./statechart.js').StatechartResult;
+export type CompiledStatechart = import('./statechart.js').CompiledStatechart;
+export type LoweredWorkflow = import('./workflow.js').LoweredWorkflow;
+export type WorkflowSnapshot = import('./workflow.js').WorkflowSnapshot;
+export type WorkflowStore = import('./workflow.js').WorkflowStore;
+export type WorkflowResult = import('./workflow.js').WorkflowResult;
+export type CompiledWorkflow = import('./workflow.js').CompiledWorkflow;
+/** @typedef {import('./statechart.js').StatechartState} StatechartState */
+/** @typedef {import('./statechart.js').StatechartResult} StatechartResult */
+/** @typedef {import('./statechart.js').CompiledStatechart} CompiledStatechart */
+/** @typedef {import('./workflow.js').LoweredWorkflow} LoweredWorkflow */
+/** @typedef {import('./workflow.js').WorkflowSnapshot} WorkflowSnapshot */
+/** @typedef {import('./workflow.js').WorkflowStore} WorkflowStore */
+/** @typedef {import('./workflow.js').WorkflowResult} WorkflowResult */
+/** @typedef {import('./workflow.js').CompiledWorkflow} CompiledWorkflow */

package/dist/types/statechart.d.ts

@@ -0,0 +1,82 @@
+export type StatechartState = Readonly<{
+    active: readonly string[];
+    history: Readonly<Record<string, readonly string[]>>;
+    timers: readonly Readonly<{
+        transition: number;
+        at: number;
+        token: number;
+    }>[];
+    serial: number;
+    time: number;
+}>;
+export type StatechartOptions = {
+    now?: number;
+    payload?: any;
+    context?: any;
+    one?: boolean;
+};
+export type StatechartResult = {
+    changed: boolean;
+    state: StatechartState;
+    final: boolean;
+    effects: any[];
+    errors: {
+        code: string;
+        docPath: string;
+        message: string;
+    }[];
+    entered: string[];
+    exited: string[];
+    transitions: number[];
+};
+export type CompiledStatechart = {
+    states: readonly string[];
+    start: (opts?: StatechartOptions) => StatechartResult;
+    step: (state: StatechartState, event: string, opts?: StatechartOptions) => StatechartResult;
+    advance: (state: StatechartState, now: number, opts?: StatechartOptions) => StatechartResult;
+    final: (state: StatechartState) => boolean;
+    events: (state: StatechartState) => readonly string[];
+    restore: (state: StatechartState) => StatechartState;
+};
+/** Compile jaren-fsm 0.2 without creating a clock, timer or effect handler.
+ * @param {any} doc
+ * @param {{ maxMicrosteps?: number }} [options]
+ * @returns {CompiledStatechart}
+ */
+export declare function compileStatechart(doc: any, options?: {
+    maxMicrosteps?: number;
+}): CompiledStatechart;
+/** A synchronous session; callers execute returned effects and supply time.
+ * @param {CompiledStatechart} chart
+ * @param {{ state?: StatechartState, now?: number, context?: any,
+ * store?: { load: () => StatechartState | null, save: (state: StatechartState) => void } }} [options]
+ */
+export declare function createStatechartSession(chart: CompiledStatechart, options?: {
+    state?: StatechartState;
+    now?: number;
+    context?: any;
+    store?: {
+        load: () => StatechartState | null;
+        save: (state: StatechartState) => void;
+    };
+}): Readonly<{
+    readonly state: Readonly<{
+        active: readonly string[];
+        history: Readonly<Record<string, readonly string[]>>;
+        timers: readonly Readonly<{
+            transition: number;
+            at: number;
+            token: number;
+        }>[];
+        serial: number;
+        time: number;
+    }>;
+    readonly done: boolean;
+    initial: StatechartResult | null;
+    /** @param {string} event @param {StatechartOptions} [opts] */
+    send: (event: string, opts?: StatechartOptions) => StatechartResult;
+    /** @param {number} now @param {StatechartOptions} [opts] */
+    advance: (now: number, opts?: StatechartOptions) => StatechartResult;
+    /** @param {string} event @param {StatechartOptions} [opts] */
+    can: (event: string, opts?: StatechartOptions) => boolean;
+}>;

package/dist/types/workflow.d.ts

@@ -0,0 +1,97 @@
+import { compileDag } from './dag.js';
+export type LoweredWorkflow = {
+    version: string;
+    revision: string;
+    document: any;
+    fsm: any;
+    dags: Record<string, any>;
+    sources: Record<string, string>;
+    specs: Record<string, any>;
+};
+export type WorkflowSnapshot = {
+    format: string;
+    runId: string;
+    identity: any;
+    generation: number;
+    control: import('./statechart.js').StatechartState;
+    context: {
+        input: any;
+        data: any;
+        event: null | {
+            type: string;
+            payload?: any;
+        };
+        results: Record<string, any>;
+        visits: Record<string, number>;
+    };
+    pending: null | {
+        state: string;
+        visit: number;
+        input: any;
+        values: Record<string, any>;
+        identity?: any;
+        result?: any;
+    };
+    status: 'running' | 'waiting' | 'done';
+};
+export type WorkflowResult = {
+    status: 'waiting' | 'done';
+    result: any;
+    snapshot: WorkflowSnapshot;
+};
+export type CompiledWorkflow = {
+    lowered: LoweredWorkflow;
+    revisions: {
+        control: string;
+        dags: Record<string, string>;
+    };
+    taskVersions: Readonly<Record<string, string>>;
+    run: (input: any, opts: WorkflowRunOptions) => Promise<WorkflowResult>;
+};
+/** @typedef {{version: string, revision: string, document: any, fsm: any,
+ * dags: Record<string, any>, sources: Record<string, string>, specs: Record<string, any>}} LoweredWorkflow */
+/** @typedef {{format: string, runId: string, identity: any, generation: number,
+ * control: import('./statechart.js').StatechartState,
+ * context: {input: any, data: any, event: null | {type: string, payload?: any}, results: Record<string, any>, visits: Record<string, number>},
+ * pending: null | {state: string, visit: number, input: any, values: Record<string, any>, identity?: any, result?: any},
+ * status: 'running'|'waiting'|'done'}} WorkflowSnapshot */
+/** @typedef {{status: 'waiting'|'done', result: any, snapshot: WorkflowSnapshot}} WorkflowResult */
+/** @typedef {{lowered: LoweredWorkflow, revisions: {control: string, dags: Record<string, string>},
+ * taskVersions: Readonly<Record<string, string>>,
+ * run: (input: any, opts: WorkflowRunOptions) => Promise<WorkflowResult>}} CompiledWorkflow */
+/** Lower one neutral workflow to inspectable JSON, without resolving host tasks.
+ * Work states carry work:{task,version,with?} or work:{dag}; choose/on/flow/final
+ * are the other mutually exclusive control forms. @param {any} document
+ * @returns {LoweredWorkflow} */
+export declare function lowerWorkflow(document: any): LoweredWorkflow;
+export type WorkflowStore = {
+    load: (runId: string) => WorkflowSnapshot | null | Promise<WorkflowSnapshot | null>;
+    save: (runId: string, snapshot: WorkflowSnapshot, expectedGeneration: number) => boolean | Promise<boolean>;
+};
+export type WorkflowRunOptions = {
+    runId: string;
+    snapshot?: any;
+    expectedGeneration?: number;
+    signal?: AbortSignal;
+    now?: number;
+    event?: {
+        type: string;
+        payload?: any;
+    };
+    onTrace?: (record: any) => void;
+};
+/** @typedef {{ load: (runId: string) => WorkflowSnapshot | null | Promise<WorkflowSnapshot | null>,
+ * save: (runId: string, snapshot: WorkflowSnapshot, expectedGeneration: number) => boolean | Promise<boolean> }} WorkflowStore */
+/** @typedef {{ runId: string, snapshot?: any, expectedGeneration?: number,
+ * signal?: AbortSignal, now?: number, event?: {type: string, payload?: any},
+ * onTrace?: (record: any) => void }} WorkflowRunOptions */
+/** Compile once; each run owns its control and checkpoint records.
+ * Store save MUST atomically compare expectedGeneration (0 means absent).
+ * @param {any} document
+ * @param {{tasks?: NonNullable<Parameters<typeof compileDag>[1]>['tasks'], store?: WorkflowStore}} [options]
+ * @returns {CompiledWorkflow}
+ */
+export declare function compileWorkflow(document: any, options?: {
+    tasks?: NonNullable<Parameters<typeof compileDag>[1]>['tasks'];
+    store?: WorkflowStore;
+}): CompiledWorkflow;

package/docs/APP-INTEGRATION.md

@@ -1,5 +1,13 @@
 # Hosting a machine in @jarenjs/app
 
+This generator targets jaren-fsm **0.1**. Statecharts and composed workflows
+use structured snapshots; they do not pass through `fsmToApp`. Host a composed
+run through the same `createTaskEffect`/id-guard convention as a DAG, persist
+its snapshot, and submit external events on subsequent calls to
+`workflow.run(input, {runId, snapshot, event, signal})`. A returned `waiting`
+status means control is saved and ready for an event; it is not an unresolved
+effect promise. [WORKFLOW-FORMAT](WORKFLOW-FORMAT.md) defines that boundary.
+
 How a jaren-fsm document drives a live `@jarenjs/app` application. The
 shape of the convention is one sentence: **control state is a state
 slice, and the machine's transition table becomes generated standard

package/docs/FLOW-FORMAT.md

@@ -9,8 +9,10 @@ authoritative for everything a structural schema cannot express, and
 the compiler enforces it.
 
 Section map: §1 scope, §2 the jaren-fsm document, §3 the evaluation
-scope, §4 the selection rule, §5 errors. §6 (the jaren-dag document)
-and §7 (dag execution) are reserved for the dataflow format.
+scope, §4 the selection rule, §5 errors, §6 the jaren-dag document and
+§7 DAG execution/persistence. This document retains the 0.1 engine contracts.
+[STATECHART-FORMAT.md](STATECHART-FORMAT.md) specifies jaren-fsm 0.2 and
+[WORKFLOW-FORMAT.md](WORKFLOW-FORMAT.md) specifies their composed workflow.
 
 ## §1 Scope
 
@@ -42,15 +44,18 @@ them, the same boundary discipline `@jarenjs/app` keeps.
 
 ### §1.1 Non-goals of format 0.1
 
-Named so nobody reads absence as oversight:
+These remain limits of `compileFsm` and its 0.1 format. Compound states,
+history, parallel regions, explicit-time delays, completion and eventless
+transitions ship separately through `compileStatechart` and jaren-fsm 0.2;
+existing string snapshots and app-generated actions retain their contracts.
 
 - **Hierarchy.** No compound or nested states; a mermaid composite state
   arrives flattened.
 - **Eventless chains.** A transition only ever fires in answer to a
   `step`/`send` call; there are no spontaneous microsteps and no
   always-transitions that cascade.
-- **History, parallel regions, delayed/timed transitions.** Statechart
-  vocabulary deferred until a use case demands it.
+- **History, parallel regions, delayed/timed transitions.** These require
+  the structured snapshot and explicit time of version 0.2.
 - **Effect execution.** The engine resolves descriptors and returns
   them; it MUST NOT invoke handlers.
 - **Persistence.** A machine's current state is a string; storing it is
@@ -211,10 +216,13 @@ tables there and here MUST stay in sync.
 | 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 |
+| JF0020 | a statechart violates hierarchy, initial, state or transition rules (STATECHART-FORMAT) |
+| JF0021 | a composed workflow declaration or reference is malformed (WORKFLOW-FORMAT) |
+| JF0022 | an automatic workflow cycle has no declared visit bound |
 
 ### §5.2 Runtime: thrown vs recorded
 
-Only **caller mistakes** throw (`FlowRuntimeError`):
+In the **0.1 FSM**, only caller mistakes throw (`FlowRuntimeError`):
 
 | code | condition |
 |---|---|
@@ -246,6 +254,13 @@ exactly the kind of partial result D7 forbids:
 | JF2007 | the caller's signal aborted the run |
 | JF2008 | a node declared `checkpoint: true` but produced a value that is not JSON-serializable; the run rejects at save time |
 | JF2009 | the checkpoint store threw while loading, saving or completing; the run rejects |
+| JF2010 | an invalid statechart snapshot or illegal active/history/timer configuration |
+| JF2011 | time moved backwards or a deadline/token exceeded its numeric range |
+| JF2012 | a statechart exceeded its microstep limit |
+| JF2013 | checkpoint workflow, lowering, input or task provenance disagrees or is missing |
+| JF2014 | a workflow run is busy or a snapshot/event generation is stale |
+| JF2015 | a workflow state exceeded its declared visit limit |
+| JF2016 | a workflow snapshot is malformed or execution failed to progress cleanly |
 
 ## §6 The jaren-dag document
 
@@ -433,11 +448,11 @@ await dag.run(input, { runId: 'run-42' });
   runs twice after a crash is the caller's bug, bluntly. The
   mitigation is an idempotency key threaded through the node's
   `with` props and honoured by the effectful system itself.
-- A standalone checkpoint store owns run identity: it must bind the run
-  id to the workflow, input and `taskVersions` before returning saved
-  values. `compileDag` validates the registry but cannot infer the
-  provenance of an arbitrary host store. Use the `@jarenjs/db` DAG job
-  runner for persisted identity comparison before node-value loading. Values recorded for node ids the current document does not
+- A legacy standalone checkpoint store owns run identity. The opt-in
+  `revision` gate (§7.9) now compares the exact document, input and
+  `taskVersions` before using saved values; the composed workflow supplies
+  this gate and a CAS store automatically. The `@jarenjs/db` DAG job runner
+  retains its own persisted identity and lease checks. Values recorded for node ids the current document does not
   declare (or no longer declares `checkpoint`) are ignored.
 
 ### §7.8 Declared task versions
@@ -511,3 +526,44 @@ const session = createDurableFsmSession(machine, {
   save: (state) => orders.put({ id: 'order-7', state }, 'order-7'),
 });
 ```
+
+### §7.9 Standalone DAG provenance
+
+Pass a nonblank `revision` with a checkpoint store to enable engine-checked
+provenance. The engine constructs an identity containing that revision, the
+exact canonical DAG document, the canonical input and the sorted task-version
+map. It supplies that identity to `load(runId, identity)`,
+`save(runId, nodeId, value, identity)` and `complete(runId, result, identity)`.
+The store persists it beside `values`:
+
+```js
+let record = null; // One-run example; production stores key by runId.
+const checkpoint = {
+  load: () => record,
+  save(runId, nodeId, value, identity) {
+    record ??= { identity, values: {} };
+    Object.defineProperty(record.values, nodeId, { value, enumerable: true,
+      configurable: true, writable: true });
+  },
+  complete() {},
+};
+const dag = compileDag(doc, { tasks, checkpoint, revision: 'enrich/3' });
+await dag.run(input, { runId: 'enrich-7' });
+```
+
+Any non-null loaded record with a missing or different identity is JF2013
+**before** values enter the node memo. Equality uses exact canonical JSON,
+not a collision-prone fingerprint. The store still owns atomic run binding,
+concurrency and retention; the composed workflow's CAS protocol supplies those
+checks for its runs. Supplying no `revision` preserves the legacy store API
+and its host-owned provenance contract. Handler versions remain declarations:
+a host MUST change them when implementation behavior changes.
+
+Caller abort now settles a run even while a task or store load ignores the
+signal. A task settling after failure cannot start a new checkpoint save.
+`run(input, {drainOnAbort: true})` instead waits for started node evaluations
+to settle before rejecting a caller abort. `createDagJobRunner` selects this
+mode so its separately bounded stop grace reports actual unfinished handlers;
+ordinary callers and composed workflows keep prompt rejection.
+Already-started host writes cannot be undone; a durable multi-writer host
+must fence them, as the composed workflow's generation protocol does.