@jarenjs/linq 0.46.5 → 0.56.0

package/src/flow/capture.js

@@ -0,0 +1,33 @@
+//@ts-check
+/**
+ * @file The one capture under every query-valued member of the flow
+ * documents: a transition guard and an effect's `with` over
+ * FLOW-FORMAT §3's step scope, a `query` node's document, a task's
+ * `with` and an edge's `select` over §6.1's input scope.
+ *
+ * The scope binds NO externals — both engines evaluate these with a
+ * single `$` and nothing else — so a name read off the capture's second
+ * argument is `JL0104` here, where the fix can be named, rather than
+ * `JQ2006` at step time, where a guard that cannot bind reads as a
+ * recorded false (FLOW-FORMAT §5.2). A returned literal is spelled as
+ * the format's own constructor and never folded into `$const`:
+ * §2's `{ "text": "retrying" }` is what a machine document carries.
+ */
+
+import { cloneJson } from '@jarenjs/core/object';
+import { captureQuery } from '../capture-root.js';
+import { requireJson } from '../json-boundary.js';
+
+/**
+ * One query-valued member: a callback captured over `$`, or a query
+ * document written by hand, copied.
+ * @param {string} what - the method, for the message
+ * @param {string} scope - what `$` is bound to, for the `JL0104` advice
+ * @param {any} value - a callback `(s) => …`, or a query document
+ * @returns {any} the query document (plain JSON)
+ */
+export function queryMember(what, scope, value) {
+  if (typeof value !== 'function') return cloneJson(requireJson(value, what));
+  const advice = () => ` — ${what} evaluates over ${scope}, which its argument IS`;
+  return cloneJson(captureQuery(what, [], value, { advice, fold: false, noun: 'callback' }));
+}

package/src/flow/dag.js

@@ -0,0 +1,302 @@
+//@ts-check
+/**
+ * @file `defineDag()` — one `jaren-dag` 0.1 document (FLOW-FORMAT.md
+ * §6), deep-frozen, that `compileDag` takes unchanged. `input()`,
+ * `constant()`, `query()`, `jslt()`, `task()` and `output()` are the
+ * closed kind vocabulary §6 fixes — one pen method per kind, so a kind
+ * the format does not have cannot be spelled — and `edge()` is the
+ * wiring. `.checkpoint()` writes §7.6's opt-in `checkpoint: true`.
+ *
+ * A `query` node's document, a `task`'s props and an edge's `select`
+ * are captured over the node's input scope (§6.1) at `$`; a `jslt`
+ * node's stylesheet is the JSLT pen's document, or one written by hand.
+ * Node ids are literal types, so an edge from a node nothing declares
+ * is a compile error; at runtime it is `JL0102` naming the id, before
+ * the compiler's `JF0013`.
+ *
+ * What the pen does NOT judge is the compiler's, and every emitted
+ * document is compiled in the tests: the wiring rules (`JF0015`),
+ * acyclicity (`JF0016`), the exactly-one-output rule (`JF0017`) and
+ * task-registry resolution (`JF0018`).
+ */
+
+import { cloneJson, deepFreeze, setObjectMember } from '@jarenjs/core/object';
+
+import { LinqBuildError } from '../errors.js';
+import { describeValue, requireJson, requireNameMap } from '../json-boundary.js';
+import { queryMember } from './capture.js';
+
+const DAG_VERSION = '0.1';
+
+/** FLOW-FORMAT §6.1's scope, for a `JL0104` message. */
+const SCOPE = "the node's input scope (FLOW-FORMAT §6.1)";
+
+/** The node-declaration brand; the members it emits live under it. */
+const NODE = Symbol.for('@jarenjs/linq/flow-node');
+/** The edge brand; the members it emits live under it. */
+const EDGE = Symbol.for('@jarenjs/linq/flow-edge');
+
+/** The members `edge()` takes beside its two positional arguments. */
+const EDGE_MEMBERS = Object.freeze(['port', 'select']);
+/** The members `defineDag()` takes. */
+const DAG_MEMBERS = Object.freeze(['nodes', 'edges']);
+
+/** @param {any} value */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * A member set the pen knows, or `JL0101` naming the one it does not.
+ * @param {any} spec
+ * @param {readonly string[]} members
+ * @param {string} what
+ */
+function closedTo(spec, members, what) {
+  for (const key of Object.keys(spec)) {
+    if (!members.includes(key)) {
+      throw new LinqBuildError('JL0101',
+        `${what} does not take '${key}' — it takes ${members.join(', ')}`, `/${key}`);
+    }
+  }
+}
+
+/**
+ * One node declaration: immutable, its emitted members carried under
+ * the brand so `checkpoint` can be a method here and a member there.
+ * @param {any} members - the node's members, in document order
+ * @returns {any}
+ */
+function node(members) {
+  const out = {
+    /**
+     * Declare this node's value durable (§7.6): a checkpoint store
+     * records it and a resumed run seeds it instead of re-evaluating.
+     * The value must be JSON — `JF2008` at save time otherwise, never
+     * a silent skip.
+     */
+    checkpoint() { return node({ ...members, checkpoint: true }); },
+  };
+  Object.defineProperty(out, NODE, { value: members, enumerable: false });
+  return Object.freeze(out);
+}
+
+/**
+ * The `input` node (§6): it yields the `run(input)` value — `null` when
+ * the caller passes none — and accepts no inbound edge.
+ * @returns {any} the node declaration
+ */
+export function input() { return node({ kind: 'input' }); }
+
+/**
+ * The `output` node (§6): its input-scope value IS the run's result.
+ * Exactly one per document (the compiler's `JF0017`), no outbound edge.
+ * @returns {any} the node declaration
+ */
+export function output() { return node({ kind: 'output' }); }
+
+/**
+ * A `const` node (§6): its literal value, delivered by reference.
+ * @param {any} value - any JSON value
+ * @returns {any} the node declaration
+ * @example
+ * constant({ threshold: 18 });
+ */
+export function constant(value) {
+  if (value === undefined) {
+    throw new LinqBuildError('JL0101',
+      'constant() takes the value the node yields — every JSON value, null included; '
+      + 'undefined is not one', '/value');
+  }
+  return node({ kind: 'const', value: cloneJson(requireJson(value, 'constant()')) });
+}
+
+/**
+ * A `query` node (§6): a Jaren JSON Query over the node's input scope.
+ * @param {any} document - `(v) => …` captured over `$`, or a query document
+ * @returns {any} the node declaration
+ * @example
+ * query((rows) => rows.all().age);      // captured
+ * query('$.summary');                   // a path document, verbatim
+ */
+export function query(document) {
+  if (document === undefined) {
+    throw new LinqBuildError('JL0101',
+      'query() takes a callback (v) => … captured over the node input, or a query document',
+      '/query');
+  }
+  return node({ kind: 'query', query: queryMember('query()', SCOPE, document) });
+}
+
+/**
+ * A `jslt` node (§6): a stylesheet transforming the node's input scope.
+ * @param {any} document - the JSLT pen's stylesheet (or rule array), or one by hand
+ * @returns {any} the node declaration
+ * @example
+ * jslt(stylesheet([rule('$', (v) => ({ names: [apply(v.all())] }))]));
+ */
+export function jslt(document) {
+  if (document === undefined) {
+    throw new LinqBuildError('JL0101',
+      'jslt() takes a stylesheet document — the JSLT pen\'s stylesheet(…) or rule array, '
+      + 'or one written by hand', '/stylesheet');
+  }
+  return node({ kind: 'jslt', stylesheet: cloneJson(requireJson(document, 'jslt()')) });
+}
+
+/**
+ * A `task` node (§7.2): a registered async handler, called as
+ * `handler({ with, input }, signal)`. The pen writes the NAME; the
+ * registry a host hands `compileDag` resolves it (`JF0018` when it
+ * cannot).
+ * @param {string} run - the registry handler name
+ * @param {any} [props] - `(v) => ({ … })` over the input scope, or a query document
+ * @returns {any} the node declaration
+ * @example
+ * task('llm', (v) => ({ prompt: v.instruction }));
+ */
+export function task(run, props = undefined) {
+  if (typeof run !== 'string' || run === '') {
+    throw new LinqBuildError('JL0101',
+      `task() takes the handler name as a non-empty string, got ${describeValue(run)}`, '/run');
+  }
+  const members = { kind: 'task', run };
+  if (props !== undefined) members.with = queryMember('task() with', SCOPE, props);
+  return node(members);
+}
+
+/**
+ * One edge (§6): data flows from a node's result to a consumer's input
+ * scope. `port` names the delivery in a ported fan-in (§6.1); `select`
+ * is applied to the source value before delivery.
+ * @param {string} from - the producing node id
+ * @param {string} to - the consuming node id
+ * @param {{ port?: string, select?: any }} [options]
+ * @returns {any} the edge declaration
+ * @example
+ * edge('rows', 'adults');
+ * edge('adults', 'report', { port: 'rows', select: (v) => v.all().name });
+ */
+export function edge(from, to, options = undefined) {
+  if (typeof from !== 'string' || from === '') {
+    throw new LinqBuildError('JL0101',
+      `edge() takes the producing node id as a non-empty string, got ${describeValue(from)}`,
+      '/from');
+  }
+  if (typeof to !== 'string' || to === '') {
+    throw new LinqBuildError('JL0101',
+      `edge() takes the consuming node id as a non-empty string, got ${describeValue(to)}`,
+      '/to');
+  }
+  const members = { from, to };
+  if (options !== undefined) {
+    if (!isPlainObject(options)) {
+      throw new LinqBuildError('JL0101',
+        `edge() options are { port?, select? }, got ${describeValue(options)}`);
+    }
+    closedTo(options, EDGE_MEMBERS, 'edge()');
+    if (options.port !== undefined) {
+      if (typeof options.port !== 'string' || options.port === '') {
+        throw new LinqBuildError('JL0101',
+          `edge() port is a non-empty string, got ${describeValue(options.port)}`, '/port');
+      }
+      members.port = options.port;
+    }
+    if (options.select !== undefined) {
+      members.select = queryMember('edge() select', 'the source value (FLOW-FORMAT §6)',
+        options.select);
+    }
+  }
+  const out = {};
+  Object.defineProperty(out, EDGE, { value: members, enumerable: false });
+  return Object.freeze(out);
+}
+
+/**
+ * Write a `jaren-dag` 0.1 document (FLOW-FORMAT.md §6).
+ *
+ * Every id an edge names must be declared — `JL0102` naming it, before
+ * the compiler's `JF0013`. Everything else about the wiring is
+ * `compileDag`'s.
+ *
+ * @param {any} spec - `{ nodes, edges }`
+ * @returns {any} the deep-frozen `$dag` 0.1 document
+ * @throws {LinqBuildError} `JL0101` a value the pen cannot spell;
+ *   `JL0102` an edge on an undeclared node id
+ * @example
+ * const graph = defineDag({
+ *   nodes: { rows: input(), adults: query('$[*]'), out: output() },
+ *   edges: [edge('rows', 'adults'), edge('adults', 'out')],
+ * });
+ * await compileDag(graph).run([{ age: 20 }]);
+ */
+export function defineDag(spec) {
+  if (!isPlainObject(spec)) {
+    throw new LinqBuildError('JL0101',
+      `defineDag() takes { nodes, edges }, got ${describeValue(spec)}`);
+  }
+  closedTo(spec, DAG_MEMBERS, 'defineDag()');
+  if (!isPlainObject(spec.nodes)) {
+    throw new LinqBuildError('JL0101',
+      `defineDag() nodes is a plain object of id → node declaration, got ${describeValue(spec.nodes)}`,
+      '/nodes');
+  }
+  requireNameMap(spec.nodes, 'defineDag() nodes', '/nodes');
+  const ids = Object.keys(spec.nodes);
+  if (ids.length === 0) {
+    throw new LinqBuildError('JL0101', 'defineDag() needs at least one node', '/nodes');
+  }
+  const nodes = {};
+  for (const id of ids) {
+    const declared = spec.nodes[id];
+    const members = isPlainObject(declared) ? declared[NODE] : undefined;
+    if (members === undefined) {
+      throw new LinqBuildError('JL0101',
+        `defineDag() node '${id}' is input(), constant(), query(), jslt(), task() or `
+        + `output(), got ${describeValue(declared)}`, `/nodes/${id}`);
+    }
+    setObjectMember(nodes, id, { ...members });
+  }
+
+  if (!Array.isArray(spec.edges)) {
+    throw new LinqBuildError('JL0101',
+      `defineDag() edges is an array of edge(from, to) declarations, got ${describeValue(spec.edges)}`,
+      '/edges');
+  }
+  const edges = spec.edges.map((declared, i) => {
+    const at = `/edges/${i}`;
+    const members = isPlainObject(declared) ? declared[EDGE] : undefined;
+    if (members === undefined) {
+      throw new LinqBuildError('JL0101',
+        `defineDag() edges[${i}] is edge(from, to, options?), got ${describeValue(declared)}`, at);
+    }
+    for (const end of ['from', 'to']) {
+      if (!Object.hasOwn(nodes, members[end])) {
+        throw new LinqBuildError('JL0102',
+          `edge ${i} names the node '${members[end]}', which "nodes" does not declare — the `
+          + `declared nodes are ${ids.map((id) => `'${id}'`).join(', ')}`, `${at}/${end}`);
+      }
+    }
+    return { ...members };
+  });
+
+  return deepFreeze({ $dag: DAG_VERSION, nodes, edges });
+}
+
+/**
+ * Bind a task registry to the graph it serves. Identity at runtime: the
+ * table is checked against the task names the document declares, so the
+ * registry `compileDag` resolves and the document agree at compile
+ * time; the runtime check remains `JF0018`.
+ * @template D
+ * @template T
+ * @param {D} dag - the pen's graph; the type argument only
+ * @param {T} tasks - handler name → handler
+ * @returns {T}
+ * @example
+ * compileDag(graph, { tasks: typedTasks(graph, { llm: askModel }) });
+ */
+export function typedTasks(dag, tasks) {
+  void dag;
+  return tasks;
+}

package/src/flow/fsm.js

@@ -0,0 +1,328 @@
+//@ts-check
+/**
+ * @file `defineFsm()` — one `jaren-fsm` 0.1 document
+ * (FLOW-FORMAT.md §2), deep-frozen, that `compileFsm` and `fsmToApp`
+ * take unchanged. `state()` declares one state, `on()` one transition
+ * (`.when()` its guard, `.to()` its target, `.effects()` its
+ * descriptors) and `effect()` one `{ run, with? }`.
+ *
+ * Guards and `with` members are captured over FLOW-FORMAT §3's scope —
+ * `{ state, event, payload, context }` at `$` — so `(s) =>
+ * s.payload.fresh` writes `"$.payload.fresh"` and `() => ({ text:
+ * 'retrying' })` writes the constructor the format's own example
+ * carries. The one trap the format names is refused here: a guard given
+ * as a plain STRING is `JL0102`, because §3 makes a non-`$` literal
+ * vacuously TRUE and a picture's display annotation must never decide
+ * execution.
+ *
+ * State ids are literal types, so a transition into an undeclared state
+ * is a compile error; at runtime it is `JL0102` naming the state,
+ * before the compiler's `JF0006`. What the pen does NOT judge is the
+ * compiler's: duplicate ids (`JF0003`), a guard's operators (`JF0007`)
+ * and everything else §5.1 lists.
+ */
+
+import { deepFreeze } from '@jarenjs/core/object';
+
+import { LinqBuildError } from '../errors.js';
+import { effectDescriptor, readEffects } from '../effect.js';
+import { describeValue } from '../json-boundary.js';
+import { isSchemaBuilder } from '../schema/brand.js';
+import { queryMember } from './capture.js';
+
+const FSM_VERSION = '0.1';
+
+/** FLOW-FORMAT §3's scope, for a `JL0104` message. */
+const SCOPE = 'the step scope { state, event, payload, context } (FLOW-FORMAT §3)';
+
+/** The state-declaration brand: how `defineFsm` tells one apart. */
+const STATE = Symbol.for('@jarenjs/linq/flow-state');
+/** The transition brand; the entry it carries lives under it. */
+const TRANSITION = Symbol.for('@jarenjs/linq/flow-transition');
+
+/** The members `state()` takes, in the order §2 writes them. */
+const STATE_MEMBERS = Object.freeze(['entry', 'exit', 'final']);
+/** The members `on()` takes beside its two positional arguments. */
+const ON_MEMBERS = Object.freeze(['payload']);
+/** The members `defineFsm()` takes. */
+const FSM_MEMBERS = Object.freeze(['initial', 'states', 'transitions', 'context']);
+
+/** @param {any} value */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * A member set the pen knows, or `JL0101` naming the one it does not.
+ * @param {any} spec
+ * @param {readonly string[]} members
+ * @param {string} what
+ * @param {string} [at]
+ */
+function closedTo(spec, members, what, at = '') {
+  for (const key of Object.keys(spec)) {
+    if (!members.includes(key)) {
+      throw new LinqBuildError('JL0101',
+        `${what} does not take '${key}' — it takes ${members.join(', ')}`, `${at}/${key}`);
+    }
+  }
+}
+
+/**
+ * A state id: a non-empty string, or `JL0101`.
+ * @param {any} id
+ * @param {string} what
+ * @returns {string}
+ */
+function readId(id, what) {
+  if (typeof id !== 'string' || id === '') {
+    throw new LinqBuildError('JL0101',
+      `${what} takes a state id — a non-empty string, got ${describeValue(id)}`);
+  }
+  return id;
+}
+
+/**
+ * One effect descriptor (§2): `{ run, with? }`, its props captured over
+ * the step scope. The engine never executes it — the host's registry
+ * does — so `run` is a name the pen writes and never resolves.
+ * @param {string} run - the host-registered handler name
+ * @param {any} [props] - `(s) => ({ … })`, or a query document
+ * @returns {any} the effect declaration
+ * @example
+ * effect('fetch', (s) => ({ url: s.context.url }));   // { run, with }
+ * effect('toast', () => ({ text: 'retrying' }));      // a constructor, not $const
+ */
+export function effect(run, props = undefined) {
+  return effectDescriptor(run, props, (p) => queryMember('effect() with', SCOPE, p));
+}
+
+/**
+ * One state declaration (§2): `{ id, entry?, exit?, final? }`. A bare
+ * string in `states` is the format's own shorthand for `{ id }` and
+ * stays one — it is the shape the `jaren-workflow` projection carries.
+ * @param {string} id - the state id transitions refer to
+ * @param {{ entry?: readonly any[], exit?: readonly any[], final?: boolean }} [options]
+ * @returns {any} the state declaration
+ * @example
+ * state('loading', { entry: [effect('fetch', (s) => ({ url: s.context.url }))] });
+ * state('done', { final: true });
+ */
+export function state(id, options = undefined) {
+  const out = { id: readId(id, 'state()') };
+  if (options !== undefined) {
+    if (!isPlainObject(options)) {
+      throw new LinqBuildError('JL0101',
+        `state() options are { entry?, exit?, final? }, got ${describeValue(options)}`);
+    }
+    closedTo(options, STATE_MEMBERS, 'state()');
+    if (options.entry !== undefined) out.entry = readEffects(options.entry, 'state() entry');
+    if (options.exit !== undefined) out.exit = readEffects(options.exit, 'state() exit');
+    if (options.final !== undefined) {
+      if (typeof options.final !== 'boolean') {
+        throw new LinqBuildError('JL0101',
+          `state() final is a boolean, got ${describeValue(options.final)}`, '/final');
+      }
+      out.final = options.final;
+    }
+  }
+  Object.defineProperty(out, STATE, { value: true, enumerable: false });
+  return Object.freeze(out);
+}
+
+/**
+ * A guard, as the document carries it: a captured body, or a query
+ * document by hand. A plain STRING is the one trap FLOW-FORMAT §3 names
+ * itself, and the pen refuses it.
+ * @param {any} value
+ * @returns {any}
+ */
+function readGuard(value) {
+  if (typeof value === 'string') {
+    throw new LinqBuildError('JL0102',
+      'a guard given as a plain string is asserted by effective boolean value, and a '
+      + 'non-empty literal is therefore VACUOUSLY TRUE (FLOW-FORMAT §3: a projected '
+      + `display guard must not change execution) — got ${JSON.stringify(value)}; pass a `
+      + 'body instead: .when((s) => s.payload.fresh)', '/guard');
+  }
+  return queryMember('when()', SCOPE, value);
+}
+
+/**
+ * The transition builder: immutable, one new builder per call, its
+ * entry carried under the brand.
+ * @param {any} entry
+ * @returns {any}
+ */
+function transition(entry) {
+  const out = {
+    /**
+     * The transition's guard (§3), captured over the step scope.
+     * @param {any} guard - `(s) => …`, or a query document
+     */
+    when(guard) { return transition({ ...entry, guard: readGuard(guard) }); },
+    /**
+     * The state this transition enters.
+     * @param {string} to
+     */
+    to(to) { return transition({ ...entry, to: readId(to, 'to()') }); },
+    /**
+     * The transition's own effects, fired between exit and entry (§4).
+     * @param {readonly any[]} effects
+     */
+    effects(effects) {
+      return transition({ ...entry, effects: readEffects(effects, 'effects()') });
+    },
+  };
+  Object.defineProperty(out, TRANSITION, { value: entry, enumerable: false });
+  return Object.freeze(out);
+}
+
+/**
+ * One transition (§2), left open until `.to()` names its target.
+ * Document order is the whole priority scheme (§4), so the order of the
+ * `transitions` array is the order the pen writes.
+ * @param {string} from - the state this transition leaves
+ * @param {string|null} [event] - the event name; null or absent is a wildcard
+ * @param {{ payload?: any }} [options] - the event's payload schema; a
+ *   TYPE only, the format carries no payload schema
+ * @returns {any} the transition builder
+ * @example
+ * on('draft', 'submit').to('review');
+ * on('review', 'approve').when((s) => s.payload.fresh).to('published');
+ * on('review').to('draft');                        // a wildcard, listed last
+ */
+export function on(from, event = null, options = undefined) {
+  const entry = { from: readId(from, 'on()') };
+  if (event !== null && event !== undefined) {
+    if (typeof event !== 'string' || event === '') {
+      throw new LinqBuildError('JL0101',
+        'on() takes an event name as a non-empty string, or null for the wildcard that '
+        + `matches any event (FLOW-FORMAT §2), got ${describeValue(event)}`, '/event');
+    }
+    entry.event = event;
+  }
+  if (options !== undefined) {
+    if (!isPlainObject(options)) {
+      throw new LinqBuildError('JL0101',
+        `on() options are { payload? }, got ${describeValue(options)}`);
+    }
+    closedTo(options, ON_MEMBERS, 'on()');
+    if (options.payload !== undefined && !isSchemaBuilder(options.payload)) {
+      throw new LinqBuildError('JL0101',
+        'on() payload is a schema-pen builder that types the event\'s payload — the format '
+        + `carries no payload schema, so nothing is emitted for it; got ${describeValue(options.payload)}`,
+        '/payload');
+    }
+  }
+  return transition(entry);
+}
+
+/**
+ * Write a `jaren-fsm` 0.1 document (FLOW-FORMAT.md §2).
+ *
+ * `initial` is declared, never guessed: the format requires the member
+ * and `null` is what a document that chooses no start state writes.
+ * Every state id `initial` and a transition name must be declared —
+ * `JL0102` naming it, before the compiler's `JF0004`/`JF0006`.
+ *
+ * @param {any} spec - `{ initial, states, transitions, context? }`
+ * @returns {any} the deep-frozen `$fsm` 0.1 document
+ * @throws {LinqBuildError} `JL0101` a value the pen cannot spell;
+ *   `JL0102` a plain-string guard, or an undeclared state id
+ * @example
+ * const machine = defineFsm({
+ *   initial: 'draft',
+ *   states: ['draft', 'review', state('published', { final: true })],
+ *   transitions: [on('draft', 'submit').to('review'), on('review', 'approve').to('published')],
+ * });
+ * compileFsm(machine).step('draft', 'submit').state;   // 'review'
+ */
+export function defineFsm(spec) {
+  if (!isPlainObject(spec)) {
+    throw new LinqBuildError('JL0101',
+      `defineFsm() takes { initial, states, transitions, context? }, got ${describeValue(spec)}`);
+  }
+  closedTo(spec, FSM_MEMBERS, 'defineFsm()');
+  if (spec.context !== undefined && !isSchemaBuilder(spec.context)) {
+    throw new LinqBuildError('JL0101',
+      'defineFsm() context is a schema-pen builder that types the host data a guard reads '
+      + '(FLOW-FORMAT §3) — the format carries no context schema, so nothing is emitted for '
+      + `it; got ${describeValue(spec.context)}`, '/context');
+  }
+  if (!Array.isArray(spec.states)) {
+    throw new LinqBuildError('JL0101',
+      `defineFsm() states is an array of ids and state() declarations, got ${describeValue(spec.states)}`,
+      '/states');
+  }
+
+  /** @type {any[]} */
+  const states = [];
+  /** @type {Set<string>} */
+  const declared = new Set();
+  spec.states.forEach((entry, i) => {
+    if (typeof entry === 'string') {
+      declared.add(readId(entry, 'defineFsm() states'));
+      states.push(entry);
+      return;
+    }
+    if (!isPlainObject(entry) || entry[STATE] !== true) {
+      throw new LinqBuildError('JL0101',
+        `defineFsm() states[${i}] is an id or state(id, options?), got ${describeValue(entry)}`,
+        `/states/${i}`);
+    }
+    declared.add(entry.id);
+    states.push({ ...entry });
+  });
+
+  /**
+   * @param {any} id
+   * @param {string} what
+   * @param {string} at
+   */
+  const declaredId = (id, what, at) => {
+    if (!declared.has(id)) {
+      throw new LinqBuildError('JL0102',
+        `${what} names the state '${id}', which "states" does not declare — the declared `
+        + `states are ${[...declared].map((s) => `'${s}'`).join(', ')}`, at);
+    }
+    return id;
+  };
+
+  if (spec.initial === undefined) {
+    throw new LinqBuildError('JL0101',
+      'defineFsm() needs an initial state — the format requires the member; pass null for a '
+      + 'machine that chooses none (a session then starts with an explicit state)', '/initial');
+  }
+  if (spec.initial !== null) {
+    declaredId(readId(spec.initial, 'defineFsm() initial'), 'defineFsm() initial', '/initial');
+  }
+
+  if (!Array.isArray(spec.transitions)) {
+    throw new LinqBuildError('JL0101',
+      `defineFsm() transitions is an array of on(…) declarations, got ${describeValue(spec.transitions)}`,
+      '/transitions');
+  }
+  const transitions = spec.transitions.map((declaration, i) => {
+    const at = `/transitions/${i}`;
+    const entry = isPlainObject(declaration) ? declaration[TRANSITION] : undefined;
+    if (entry === undefined) {
+      throw new LinqBuildError('JL0101',
+        `defineFsm() transitions[${i}] is on(from, event?).to(state), got `
+        + `${describeValue(declaration)}`, at);
+    }
+    if (entry.to === undefined) {
+      throw new LinqBuildError('JL0101',
+        `defineFsm() transitions[${i}] never named its target — on('${entry.from}'`
+        + `${entry.event === undefined ? '' : `, '${entry.event}'`}) needs .to(state)`, at);
+    }
+    const out = { from: declaredId(entry.from, `transition ${i}`, `${at}/from`) };
+    if (entry.event !== undefined) out.event = entry.event;
+    if (entry.guard !== undefined) out.guard = entry.guard;
+    out.to = declaredId(entry.to, `transition ${i}`, `${at}/to`);
+    if (entry.effects !== undefined) out.effects = entry.effects;
+    return out;
+  });
+
+  return deepFreeze({ $fsm: FSM_VERSION, initial: spec.initial, states, transitions });
+}

package/src/flow/index.js

@@ -0,0 +1,22 @@
+//@ts-check
+/**
+ * @file `@jarenjs/linq/flow` — the `jaren-fsm` and `jaren-dag` 0.1
+ * documents by code. `defineFsm()` writes the machine `compileFsm` and
+ * `fsmToApp` take; `defineDag()` writes the dataflow `compileDag`
+ * takes. Guards, effect props, node queries and edge selectors are
+ * callbacks captured over the scope the engine evaluates them in
+ * (FLOW-FORMAT §3 and §6.1), so a path is written, never typed as a
+ * string — which is also why a plain-string guard is refused here
+ * (§3 makes a literal one vacuously true).
+ *
+ * State ids, event names and node ids are literal types: a transition
+ * into an undeclared state or an edge from an undeclared node is a
+ * compile error before it is a `JL0102`, and long before the engine's
+ * `JF0006`/`JF0013`. The document is the deliverable — plain,
+ * deep-frozen JSON — and nothing here imports `@jarenjs/flow`.
+ */
+
+export { defineFsm, state, on, effect } from './fsm.js';
+export {
+  defineDag, input, output, constant, query, jslt, task, edge, typedTasks,
+} from './dag.js';