@jarenjs/flow 0.34.0

package/README.md

@@ -0,0 +1,234 @@
+# @jarenjs/flow
+
+Executable workflow documents, in two formats. The **jaren-fsm 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)
+documents — compiled, once, into a **pure step function**. The
+**jaren-dag format** is an acyclic dataflow whose nodes are the suite's
+own engines — query documents, JSLT stylesheets, registered async
+tasks — wired by edges that carry data and compiled into a
+run-to-completion executor.
+
+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
+engine runs it. The format is a strict superset of that projection
+contract — every projected document compiles unchanged.
+
+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
+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`.
+
+## The format in one glance
+
+```json
+{
+  "$fsm": "0.1",
+  "initial": "idle",
+  "states": [
+    "idle",
+    { "id": "loading", "entry": [{ "run": "fetch", "with": { "url": "$.context.url" } }] },
+    { "id": "done", "final": true }
+  ],
+  "transitions": [
+    { "from": "idle", "event": "start", "to": "loading" },
+    { "from": "loading", "event": "ok", "guard": "$.payload.fresh", "to": "done" },
+    { "from": "loading", "event": "fail", "to": "idle" }
+  ]
+}
+```
+
+Guards are asserted by effective boolean value against one scope —
+`{ state, event, payload, context }` — and **effects are data**: a fired
+transition returns resolved `{ run, with? }` descriptors (exit →
+transition → entry); the engine never executes them. Which registry runs
+them is the host's business, the same boundary discipline as
+`@jarenjs/app` effects.
+
+## Usage
+
+```javascript
+import { compileFsm, createFsmSession } from '@jarenjs/flow';
+
+const fsm = compileFsm(doc);        // throws FlowCompileError (JF0xxx) on a bad document
+fsm.initial;                        // 'idle'
+fsm.states;                         // ['idle', 'loading', 'done'] (frozen)
+fsm.events('loading');              // ['ok', 'fail'] (frozen)
+
+// The pure core: state in, result out. Nothing is held, nothing runs.
+const r = fsm.step('loading', 'ok', { payload: { fresh: true }, context: { url: '/api' } });
+r; // { changed: true, state: 'done', effects: [], final: true, errors: [] }
+
+// The thin mutable convenience over it:
+const s = createFsmSession(fsm);    // starts at doc initial
+s.can('start');                     // true — a dry run (step is pure, so can() IS step())
+s.send('start');                    // advances; returns the same result shape
+s.state;                            // 'loading'
+s.done;                             // final-state flag
+```
+
+`step` is **total over machine input**: an event no transition answers
+is ignored (`changed: false`, no effects) — the conventional FSM
+reading. Only caller mistakes throw: an undeclared state id or a
+non-string event (`FlowRuntimeError`, JF2001/JF2002).
+
+## Fail closed, report precisely
+
+A guard that throws at evaluation reads **false**; an effect whose
+`with` throws is **omitted**. Neither aborts the step — each appends a
+plain-data record `{ code, docPath, message }` to the result's `errors`
+array, where `docPath` is a JSON Pointer to exactly the query that
+failed (`/transitions/2/guard`). That is the suite's standard
+machine-repairable error shape: a host surfaces the records through its
+own error channel, and a repair loop knows precisely what to fix.
+
+Compile-time failures throw `FlowCompileError` with the same `code` +
+`docPath` discipline (JF0001–JF0009, table in
+[FLOW-FORMAT.md §5](docs/FLOW-FORMAT.md)); a guard that cannot compile
+is a compile error, never a runtime surprise.
+
+## Hosting a machine in @jarenjs/app
+
+`fsmToApp` turns the same document into **generated standard app
+documents** — a state slice plus one plain-JSON action per named event,
+compiled by the app like any hand-written action, with no flow code at
+runtime:
+
+```javascript
+import { fsmToApp, fsmStateSchema } from '@jarenjs/flow';
+import { createApp } from '@jarenjs/app';
+
+const { slice, actions, events } = fsmToApp(doc);   // { pointer: '/fsm', namespace: 'fsm/' }
+const app = createApp({
+  state: { fsm: slice },
+  view,
+  actions: { ...actions, ...hostActions },
+}, { node, effects, validateState });               // fsmStateSchema(doc) guards the slice
+```
+
+Control state lives at `<pointer>/current`; the host's app state **is**
+the machine's `context`; guards and effect props evaluate
+pre-transition in both worlds, and target states are baked as literals.
+Selection semantics are provably the headless engine's — the test
+suite drives both through the same scripts and asserts state and
+effects agree. The convention, the scope mapping table, multi-machine
+layout and the honestly-stated divergences (a throwing guard fails the
+hosted transaction instead of reading false) live in
+[docs/APP-INTEGRATION.md](docs/APP-INTEGRATION.md).
+
+## The dataflow half — jaren-dag
+
+"Connect different parts together" as one schema-validated JSON value:
+nodes from a closed vocabulary (`input`, `output`, `const`, `query`,
+`jslt`, `task`) wired by edges, run to completion for one input. The
+suite's engines compose as **data** — a query filters, a stylesheet
+projects, and the result can be a vnode tree without this package ever
+importing a rendering line:
+
+```javascript
+import { compileDag } from '@jarenjs/flow';
+
+const dag = compileDag({
+  $dag: '0.1',
+  nodes: {
+    rows:   { kind: 'input' },
+    adults: { kind: 'query',
+      query: { $for: { r: '$[*]' }, $where: { $ge: ['$r.age', 18] }, $return: '$r' } },
+    view:   { kind: 'jslt',
+      stylesheet: [{ match: '$', body: ['ul', {},
+        [{ $for: { p: '$[*]' }, $return: ['li', {}, '$p.name'] }]] }] },
+    out:    { kind: 'output' },
+  },
+  edges: [
+    { from: 'rows', to: 'adults' },
+    { from: 'adults', to: 'view' },
+    { from: 'view', to: 'out' },
+  ],
+}, { tasks: {} });
+
+await dag.run(people);   // ['ul', {}, [['li', {}, 'ada'], …]] — a vnode, as JSON
+```
+
+Cycles, port rules and the exactly-one-output rule are **compile-time**
+rejections (JF0xxx with `docPath`); a `task` node's handler is resolved
+at compile too, and called as `handler({ with, input }, signal)` with
+the run's shared `AbortSignal`. Independent branches run concurrently,
+but determinism is *same input → same output values* — results are
+keyed and port objects assemble in edge document order, so completion
+timing can never change a value. Failure is fail-closed: the first
+failing node aborts the shared signal and rejects the whole run
+(`JF2006` with `nodeId`, `docPath`, `cause`; a caller abort is
+`JF2007`) — no retries, no partial results. Per-node observability is
+the `onNode` record stream (`{ id, status, ms }`), and a compiled dag
+hosts in an app as **one effect** through `createTaskEffect` — the
+recipe is in [docs/APP-INTEGRATION.md](docs/APP-INTEGRATION.md), the
+contract in [docs/FLOW-FORMAT.md](docs/FLOW-FORMAT.md) §6–§7.
+
+## One scope, one honest quirk
+
+`$.state`, `$.event`, `$.payload`, `$.context` — control state lives in
+the machine, data state lives in the host, passed per call. A guard
+written as a plain string that does not start with `$` is a *literal*
+(query semantics), and a non-empty literal is EBV-**true**: a display
+guard carried over from a diagram label (`count > 3`) is vacuously true
+by design, because a picture's annotation must not change execution.
+Real conditions are `$`-paths (`"$.payload.fresh"`) or operator
+documents (`{ "$gt": ["$.context.count", 3] }`).
+
+## Performance (measured)
+
+`npm run benchmark:flow` (run it yourself — the FSM head-to-head needs
+the `xstate` benchmark devDependency, and the memory row needs
+`node --expose-gc`, which the script passes). The same logical machine is
+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
+  `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
+  row is each engine's description→drivable cost.
+- **The wedge** — a conformance fact, not a timing: a jaren-fsm document
+  is JSON *including its guards*, so it survives `JSON.stringify` →
+  `JSON.parse` and still compiles and still fires its guard. XState's
+  guards are functions JSON drops, so the round-tripped machine throws
+  "Guard not implemented" at the guarded transition. Serialize, store,
+  diff, ship, replay — that is the whole reason to speak JSON all the way
+  down.
+- **Where we lose** — a compiled Jaren machine holds **more** memory than
+  the XState actor (every guard compiles to its own query closure); the
+  benchmark publishes the KiB-per-machine loss beside the wins.
+- **The dag tax** — no npm library executes schema-validated JSON
+  dataflow, so the honest rival is the same pipeline hand-written in
+  JavaScript. A `compileDag` run costs ~8–20× the hand-written baseline —
+  the published price of dataflow as one serializable,
+  constrained-decodable JSON value, sitting beside what it buys.
+
+The full tables, the wedge as a conformance row, and the fairness notes
+are on the [benchmarks page](https://jklarenbeek.github.io/jarenjs/#/benchmarks?suite=flow).
+
+## Authoring with a model
+
+A jaren-fsm or jaren-dag document is JSON published as a schema, so a
+constrained decoder can author one — and because every compile error
+carries a `code` and a `docPath`, a schema-valid but semantically broken
+machine (a transition to an undeclared state, say) repairs in a bounded
+loop rather than flailing. `@jarenjs/ai`'s
+[*Authoring engine documents*](../ai/README.md#authoring-engine-documents-validate-and-compile)
+section shows the `composeChecks(schema, compileGate)` recipe, and
+[*A model as a dataflow node*](../ai/README.md#a-model-as-a-dataflow-node)
+runs a model as an ordinary dag `task`. Neither package imports the
+other — the composition is data.
+
+## Development
+
+Unit tests live in `test/flow/` at the repository root
+(`npm run test:flow`). See the repository [README](../../README.md) for
+the full suite documentation.

package/dist/types/app.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @file The @jarenjs/app adapter: turn a jaren-fsm document into the
+ * standard app documents that host it (docs/APP-INTEGRATION.md). This
+ * is a GENERATOR, not a runtime — it emits pure JSON action documents
+ * the app compiles like any hand-written action, and nothing from this
+ * package runs afterwards. Selection semantics are the headless
+ * engine's, reproduced structurally: one conditional chain per named
+ * event, transitions in document order, `$and`'s first-false stop
+ * playing the role of the step function's guard gate.
+ *
+ * The scope mapping (APP-INTEGRATION.md §scope): a guard or `with`
+ * query authored against FLOW-FORMAT §3's `{ state, event, payload,
+ * context }` is rewritten to read the reserved variable `__fsm`, bound
+ * once per action to `{ state: <pointer>.current, event: <literal>,
+ * payload: $payload, context: $ }` — all pre-transition, exactly like
+ * the headless step scope.
+ */
+/**
+ * Generate the standard app documents that host a jaren-fsm machine:
+ * a state slice, one action document per distinct named event, and the
+ * event vocabulary. The output is pure JSON with the machine's target
+ * states, event names and effect origins baked as literals; guards and
+ * effect props run through the app's own query engine at dispatch
+ * time. See docs/APP-INTEGRATION.md for the convention this implements.
+ *
+ * @param {any} fsmDoc - a jaren-fsm document (FLOW-FORMAT §2)
+ * @param {{ pointer?: string, namespace?: string }} [options] -
+ *   `pointer` (default `/fsm`) is where the slice lives in app state,
+ *   as a chain of identifier-safe segments; `namespace` (default
+ *   `fsm/`) prefixes the generated action names.
+ * @returns {{ slice: { current: string|null }, actions: Record<string, any>, events: string[] }}
+ * @throws {import('./errors.js').FlowCompileError} on a bad machine
+ *   document (the same JF0xxx codes as `compileFsm`)
+ * @throws {TypeError} on malformed options or a document binding the
+ *   reserved `__fsm` variable name
+ */
+export declare function fsmToApp(fsmDoc: any, options?: {
+    pointer?: string;
+    namespace?: string;
+}): {
+    slice: {
+        current: string | null;
+    };
+    actions: Record<string, any>;
+    events: string[];
+};
+/**
+ * The state slice's JSON Schema: `current` as an enum of the machine's
+ * declared state ids — compose it into a `validateState` schema at the
+ * slice pointer so no hand-written action can corrupt the control
+ * state (APP-INTEGRATION.md §fail-closed).
+ * @param {any} fsmDoc - a jaren-fsm document
+ * @returns {{ type: 'object', required: string[], properties: { current: { description: string, enum: string[] } } }}
+ * @throws {import('./errors.js').FlowCompileError} on a bad machine document
+ */
+export declare function fsmStateSchema(fsmDoc: any): {
+    type: 'object';
+    required: string[];
+    properties: {
+        current: {
+            description: string;
+            enum: string[];
+        };
+    };
+};

package/dist/types/dag.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @file The jaren-dag engine: compile an acyclic dataflow document
+ * (docs/FLOW-FORMAT.md §6) once — every embedded query, stylesheet,
+ * `with` and `select` becomes a closure, the task registry is resolved,
+ * the wiring rules are proven — and run it many times. A run resolves
+ * nodes as their inputs arrive (independent branches concurrently),
+ * delivers values by reference, and fails closed: the first failing
+ * node aborts the shared signal and rejects the whole run (§7.3) — no
+ * retries, no partial results.
+ *
+ * Determinism is same input → same output VALUES, never same timing:
+ * results are keyed per node and port objects assemble in edge
+ * document order, so completion order cannot change a value (§7.2).
+ */
+export type DagNodeRecord = {
+    id: string;
+    status: 'ok' | 'error' | 'aborted' | 'restored';
+    ms: number;
+};
+export type DagCheckpointStore = {
+    load: (runId: string) => any;
+    save: (runId: string, nodeId: string, value: any) => any;
+    complete: (runId: string, result: any) => any;
+};
+export type CompiledDag = {
+    /**
+     * - Declared node ids, document order.
+     */
+    nodes: readonly string[];
+    /**
+     * - The output node's id.
+     */
+    output: string;
+    /**
+     * -
+     * Execute the graph for one input (`undefined` reads as `null`).
+     */
+    run: (input?: any, opts?: {
+        signal?: AbortSignal;
+        onNode?: (record: DagNodeRecord) => void;
+        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,
+ * the wiring rules, acyclicity, embedded-document compilation and
+ * 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>,
+ *   checkpoint?: DagCheckpointStore }} [options]
+ * @returns {CompiledDag}
+ * @throws {FlowCompileError} when the document violates the format (JF0xxx)
+ * @throws {TypeError} when the options are malformed (a registry that is
+ *   not an object, a registered handler that is not a function, or a
+ *   checkpoint store missing one of load/save/complete)
+ */
+export declare function compileDag(doc: any, options?: {
+    tasks?: Record<string, (props: {
+        with: any;
+        input: any;
+    }, signal: AbortSignal) => any>;
+    checkpoint?: DagCheckpointStore;
+}): CompiledDag;

package/dist/types/errors.d.ts

@@ -0,0 +1,155 @@
+/**
+ * @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 declare const FLOW_CODES: Readonly<{
+    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 declare 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: string, reason: string, docPath?: string, cause?: Error);
+}
+/**
+ * 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 declare 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: string, reason: string, docPath?: string, cause?: Error);
+}
+/**
+ * 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 declare function asError(v: unknown): Error;