@pylonts/dsl 1.1.6 → 1.1.12

package/dist/flow.js

@@ -1,11 +1,189 @@
+import { UnexpectedException } from './exception.js';
+/** Declare a flow's named slots — each bound to the message of a method's
+ *  args/results (the slot's type). The built-in args slot (the flow input)
+ *  is added automatically: parameters need no registration. To make its
+ *  fields accessible (slots.args.amt), declare its input message via the
+ *  `args` key — that declares the slot's type, not a new slot. */
+export function defineSlots(slots) {
+    const wrap = (slot) => {
+        const proxy = new Proxy(slot, {
+            get(target, prop, receiver) {
+                if (typeof prop === 'symbol')
+                    return Reflect.get(target, prop, receiver);
+                // Slot metadata wins over same-named message fields; reflection keys
+                // (then/toJSON and Object.prototype members) keep plain object
+                // behavior so serialization, promises, and console output never throw.
+                if (prop === 'type' ||
+                    prop === 'description' ||
+                    prop === 'then' ||
+                    prop === 'toJSON' ||
+                    prop in target) {
+                    return Reflect.get(target, prop, receiver);
+                }
+                const fields = target.type?.fields;
+                if (fields !== undefined && Object.prototype.hasOwnProperty.call(fields, prop)) {
+                    return { slot: proxy, field: fields[prop] };
+                }
+                throw new Error(`slot "${target.name}" has no field "${prop}" — its type declares: ${fields ? Object.keys(fields).join(', ') : 'no fields'}`);
+            },
+        });
+        return proxy;
+    };
+    const registry = Object.create(null);
+    for (const key of Object.keys(slots)) {
+        if (key === 'args') {
+            registry.args = wrap({ name: 'args', type: slots.args, description: 'flow input (flow.args)' });
+            warnShadowedFields(registry.args);
+            continue;
+        }
+        registry[key] = wrap({ name: key, type: slots[key] });
+        warnShadowedFields(registry[key]);
+    }
+    if (registry.args === undefined) {
+        registry.args = wrap({ name: 'args', description: 'flow input (flow.args)' });
+    }
+    return registry;
+}
+// A message field named type/name/description is shadowed by slot metadata and
+// unreachable via dot access (slots.args.type reads the message, not the
+// field) — warn instead of failing: the field may never be needed.
+function warnShadowedFields(slot) {
+    const fields = slot.type?.fields;
+    if (fields === undefined)
+        return;
+    const shadowed = ['type', 'name', 'description'].filter((k) => k in fields);
+    if (shadowed.length > 0) {
+        console.warn(`slot "${slot.name}": message fields ${shadowed.join(', ')} are shadowed by slot metadata and unreachable via field access`);
+    }
+}
+export function invoke(method, options = {}) {
+    return { method, args: options.args, result: options.result };
+}
+export function isCall(m) {
+    return 'method' in m;
+}
+/** The underlying method of a (possibly bound) reference. */
+export function methodOf(m) {
+    return isCall(m) ? m.method : m;
+}
+function comparison(op, field, value) {
+    const ref = field;
+    if (typeof ref !== 'object' || ref === null || typeof ref.slot !== 'object' || typeof ref.field !== 'object') {
+        throw new Error(`${op}: field must be a slot field access like slots.args.amt`);
+    }
+    const nullOp = op === 'isNull' || op === 'isNotNull';
+    if (nullOp !== (value === undefined)) {
+        throw new Error(`${op}: ${nullOp ? 'takes no' : 'requires a'} value`);
+    }
+    return { kind: 'comparison', op, field: { slot: ref.slot, field: ref.field }, value };
+}
+export function lt(field, value) {
+    return comparison('lt', field, value);
+}
+export function le(field, value) {
+    return comparison('le', field, value);
+}
+export function gt(field, value) {
+    return comparison('gt', field, value);
+}
+export function ge(field, value) {
+    return comparison('ge', field, value);
+}
+export function eq(field, value) {
+    return comparison('eq', field, value);
+}
+export function ne(field, value) {
+    return comparison('ne', field, value);
+}
+export function isNull(field) {
+    return comparison('isNull', field);
+}
+export function isNotNull(field) {
+    return comparison('isNotNull', field);
+}
+/** An enum value referenced by symbol — the compared-against target of eq/ne
+ *  (e.g. eq(slots.args.state, enumValue(PayState, 'success'))). */
+export function enumValue(def, symbol) {
+    const v = def.values.find((v) => v.symbol === symbol);
+    if (v === undefined) {
+        throw new Error(`enum ${def.jsName} has no value "${symbol}"`);
+    }
+    return v;
+}
+/** Decision node: ordered cases (check → target) plus a default branch. */
+export function ifNode(name, options) {
+    return {
+        type: 'if',
+        name,
+        description: options.description,
+        cases: options.cases,
+        else: options.else,
+    };
+}
+/** The flow's exception end carrying the given exception name — the implicit
+ *  target of a guard check throwing it. Undefined when the flow has no such
+ *  end (guard checks synthesize one at definition time, so this only happens
+ *  for hand-assembled flows). */
+export function findExceptionEnd(schema, exceptionName) {
+    return schema.nodes.find((n) => isEnd(n) && n.type === 'exception' && n.exception?.name === exceptionName);
+}
+/** Where a throw of `exceptionName` from step `n` lands: the target of a typed
+ *  throws edge (first match), or an untyped exception edge as catch-all.
+ *  Undefined when no route exists (validation error). Guards route implicitly
+ *  — see findExceptionEnd.
+ *  @deprecated no internal use remains; kept for API compatibility. */
+export function resolveThrowTarget(schema, n, exceptionName) {
+    for (const e of schema.edges) {
+        if (e.start !== n)
+            continue;
+        if (e.throws && e.throws.name === exceptionName)
+            return e.end;
+    }
+    for (const e of schema.edges) {
+        if (e.start === n && e.exception === true && e.throws === undefined)
+            return e.end;
+    }
+    return undefined;
+}
+/** Executor node: an ordered sequence of method invocations (and optionally
+ *  one event publication). */
 export function node(name, options = {}) {
     return {
         name,
         flow: options.flow,
         description: options.description,
         methods: options.methods,
+        publish: options.publish,
+        reads: options.reads,
+        writes: options.writes,
+    };
+}
+/** Guard node: a gate executor — ordered checks, first hit routes out;
+ *  all misses fall through the guard's normal outgoing edges. */
+export function guard(name, options) {
+    return {
+        type: 'guard',
+        name,
+        description: options.description,
+        methods: options.methods,
+        checks: options.checks,
+    };
+}
+/** Try node: a protected region whose body, catch handlers, and optional
+ *  finally are sub-flows. */
+export function tryNode(name, options) {
+    return {
+        type: 'try',
+        name,
+        description: options.description,
+        body: options.body,
+        catches: options.catches,
+        finally: options.finally,
     };
 }
+export function defineExceptionEnd(exception, description) {
+    return { type: 'exception', name: `throw ${exception.name}`, exception, description };
+}
 export function edge(start, end, options = {}) {
     // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
     return {
@@ -15,45 +193,137 @@ export function edge(start, end, options = {}) {
         when: options.when,
         description: options.description,
         exception: options.exception,
+        throws: options.throws,
+        check: options.check,
     };
 }
 export function defineFlow(name, schema) {
+    const flow = {
+        name,
+        description: schema.description,
+        start: schema.start,
+        returnEnd: { type: 'return', name: 'return' },
+        nodes: [],
+        edges: [],
+        args: schema.args,
+        results: schema.results,
+        slots: schema.slots,
+        entrySlots: schema.entrySlots,
+    };
+    // The input slot's type is the flow's args message: stamp it on first use,
+    // and refuse a registry already bound to a different input contract (slot
+    // registries belong to one call tree). Same-name messages are the same
+    // contract regardless of instance identity.
+    if (schema.args !== undefined && schema.slots !== undefined) {
+        const t = schema.slots.args.type;
+        if (t === undefined) {
+            schema.slots.args.type = schema.args;
+            warnShadowedFields(schema.slots.args);
+        }
+        else if (messageName(t) !== schema.args.name) {
+            throw new Error(`flow ${name}: the slots args slot carries ${messageName(t)} but the flow declares ${schema.args.name}`);
+        }
+    }
+    const edges = schema.edges(flow);
+    flow.edges = edges; // before node collection: guard check targets resolve through it
     const seen = new Set();
     const nodes = [];
-    for (const e of schema.edges) {
-        for (const n of [e.start, e.end]) {
-            if (!seen.has(n)) {
-                seen.add(n);
-                nodes.push(n);
+    const addNode = (n) => {
+        if (seen.has(n))
+            return;
+        seen.add(n);
+        nodes.push(n);
+    };
+    const addGuardTargets = (n) => {
+        if (!isGuard(n))
+            return;
+        for (const c of n.checks) {
+            const ex = c.exception;
+            if (c.return) {
+                addNode(flow.returnEnd);
+            }
+            else if (ex) {
+                // Guard checks exit implicitly: reuse the flow's exception end of the
+                // same name (declared by an edge or another guard), else synthesize it.
+                let t = nodes.find((x) => isEnd(x) && x.type === 'exception' && x.exception?.name === ex.name);
+                if (!t) {
+                    t = {
+                        type: 'exception',
+                        name: `throw ${ex.name}`,
+                        exception: ex,
+                        description: 'guard implicit exit',
+                    };
+                }
+                addNode(t);
             }
         }
+    };
+    for (const e of edges) {
+        addNode(e.start);
+        addNode(e.end);
     }
-    if (!seen.has(schema.start)) {
-        seen.add(schema.start);
-        nodes.push(schema.start);
+    addNode(schema.start);
+    // Guard targets resolve after every edge endpoint is collected, so an
+    // exception end referenced by any edge is reused before synthesis. ifNode
+    // targets (cases and else) are collected the same way — an ifNode has no
+    // outgoing edges, so its targets enter the flow only here. Targets chain
+    // (an ifNode may target another ifNode, or a guard whose implicit exit
+    // ends need collecting), so the loop runs over the growing list to a
+    // fixpoint instead of a snapshot.
+    for (let i = 0; i < nodes.length; i++) {
+        const n = nodes[i];
+        addGuardTargets(n);
+        if (isIfNode(n)) {
+            for (const c of n.cases)
+                addNode(c.to);
+            addNode(n.else);
+        }
     }
-    const flow = { name, description: schema.description, start: schema.start, nodes, edges: schema.edges };
+    flow.nodes = nodes;
     validate(flow);
     return flow;
 }
-// Nodes that never appear as an edge start are terminals. Reverse BFS from all
-// terminals marks every node that can reach a terminal; unmarked nodes sit on
-// a path that never ends (e.g. a cycle without an exit) — reject them at
-// definition time.
+// Reverse BFS from every FlowEnd marks all nodes that can reach an exit;
+// unmarked nodes sit on a path that never ends (e.g. a cycle without an exit)
+// — reject them at definition time. Guard checks count as implicit edges of
+// the guard itself; TryNode internals are validated inside their own flows.
 function validate(schema) {
-    const starts = new Set();
-    for (const e of schema.edges)
-        starts.add(e.start);
     const reverse = new Map();
     for (const n of schema.nodes)
         reverse.set(n, []);
     for (const e of schema.edges) {
         reverse.get(e.end).push(e.start);
     }
+    // guard checks are implicit edges of the guard node itself (return checks
+    // to the return end, exception checks to the matching exception end)
+    for (const n of schema.nodes) {
+        if (!isGuard(n))
+            continue;
+        for (const c of n.checks) {
+            if (c.return) {
+                const arr = reverse.get(schema.returnEnd);
+                if (arr)
+                    arr.push(n); // returnEnd is absent when no edge targets it; the guard is then unreachable anyway
+            }
+            else if (c.exception) {
+                const t = findExceptionEnd(schema, c.exception.name);
+                if (t)
+                    reverse.get(t).push(n);
+            }
+        }
+    }
+    // ifNode branches are implicit edges of the decision node itself
+    for (const n of schema.nodes) {
+        if (!isIfNode(n))
+            continue;
+        for (const c of n.cases)
+            reverse.get(c.to).push(n);
+        reverse.get(n.else).push(n);
+    }
     const reached = new Set();
     const queue = [];
     for (const n of schema.nodes) {
-        if (!starts.has(n)) {
+        if (isEnd(n)) {
             reached.add(n);
             queue.push(n);
         }
@@ -69,7 +339,522 @@ function validate(schema) {
     }
     for (const n of schema.nodes) {
         if (!reached.has(n)) {
-            throw new Error(`flow ${schema.name}: node "${n.name}" cannot reach a terminal`);
+            throw new Error(`flow ${schema.name}: node "${n.name}" cannot reach an end node`);
+        }
+    }
+    // Forward BFS from the start: every node must be reachable, so dead regions
+    // cannot silently pollute the escape set (or the catch matching).
+    const fromStart = new Set();
+    const forward = [schema.start];
+    while (forward.length > 0) {
+        const cur = forward.shift();
+        if (fromStart.has(cur))
+            continue;
+        fromStart.add(cur);
+        for (const e of schema.edges) {
+            if (e.start === cur)
+                forward.push(e.end);
+        }
+        if (isGuard(cur)) {
+            for (const c of cur.checks) {
+                if (c.return) {
+                    forward.push(schema.returnEnd);
+                }
+                else if (c.exception) {
+                    const t = findExceptionEnd(schema, c.exception.name);
+                    if (t)
+                        forward.push(t);
+                }
+            }
+        }
+        if (isIfNode(cur)) {
+            for (const c of cur.cases)
+                forward.push(c.to);
+            forward.push(cur.else);
+        }
+    }
+    for (const n of schema.nodes) {
+        if (!fromStart.has(n)) {
+            throw new Error(`flow ${schema.name}: node "${n.name}" is not reachable from the start node`);
         }
     }
+    validateGuardChecks(schema);
+    for (const e of schema.edges) {
+        if (e.check !== undefined) {
+            validateCondition(`flow ${schema.name}: edge "${e.name}"`, e.check);
+        }
+    }
+    for (const n of schema.nodes) {
+        if (isIfNode(n))
+            validateIfNode(n, schema);
+    }
+    validateSlots(schema);
+    for (const n of schema.nodes) {
+        if (isEnd(n))
+            continue;
+        validateThrowsCoverage(n, schema);
+        if (isTryNode(n))
+            validateTryNode(n, schema);
+    }
+    // Guard check exceptions exit implicitly — a typed throws edge carrying
+    // one of the guard's own check exceptions would duplicate the route. Edges
+    // carrying other exceptions (or catch-all edges) stay legal: they route
+    // throws declared by the guard's methods.
+    for (const e of schema.edges) {
+        if (!isGuard(e.start))
+            continue;
+        if (e.throws !== undefined && e.start.checks.some((c) => c.exception?.name === e.throws.name)) {
+            throw new Error(`flow ${schema.name}: edge "${e.name}" from guard "${e.start.name}" duplicates the implicit route of check exception ${e.throws.name} — guard checks route implicitly to the matching exception end`);
+        }
+    }
+    // An ifNode owns its exits internally (cases and else) — outgoing edges
+    // would be a second way out of the decision.
+    for (const e of schema.edges) {
+        if (!isIfNode(e.start))
+            continue;
+        throw new Error(`flow ${schema.name}: edge "${e.name}" from ifNode "${e.start.name}" is redundant — ifNode exits are internal (cases and else)`);
+    }
+    // Typed throws edges land on an exception end carrying the same exception
+    // (escape) — never on a plain step, and no silent renames.
+    for (const e of schema.edges) {
+        if (e.throws === undefined)
+            continue;
+        if (!isEnd(e.end) || e.end.type !== 'exception') {
+            throw new Error(`flow ${schema.name}: edge "${e.name}" carries throw ${e.throws.name} but its target is not an exception end`);
+        }
+        if (!e.end.exception) {
+            throw new Error(`flow ${schema.name}: edge "${e.name}" targets exception end "${e.end.name}" with no exception type`);
+        }
+        if (e.end.exception.name !== e.throws.name) {
+            throw new Error(`flow ${schema.name}: edge "${e.name}" carries throw ${e.throws.name} but targets the ${e.end.exception.name} exception end`);
+        }
+    }
+    // Untyped catch-all edges also escape — the target must be an exception end.
+    for (const e of schema.edges) {
+        if (e.exception !== true || e.throws !== undefined)
+            continue;
+        if (!isEnd(e.end) || e.end.type !== 'exception') {
+            throw new Error(`flow ${schema.name}: edge "${e.name}" catch-all exception path must target an exception end`);
+        }
+    }
+    // Plain sub-flows are structure only — exceptions must go through a tryNode.
+    for (const n of schema.nodes) {
+        if (!isFlowNode(n) || !n.flow)
+            continue;
+        const ends = exceptionEndNames(n.flow);
+        if (ends.size > 0) {
+            throw new Error(`flow ${schema.name}: node "${n.name}" sub-flow must not declare exception ends (${[...ends].join(', ')}) — a guard check exception also creates one; use a tryNode for a protected region`);
+        }
+    }
+}
+// Every guard check must choose exactly one of return / exception; its
+// optional machine-readable condition must be well-formed.
+function validateGuardChecks(schema) {
+    for (const n of schema.nodes) {
+        if (!isGuard(n))
+            continue;
+        for (const c of n.checks) {
+            const hasReturn = c.return === true;
+            const hasException = c.exception !== undefined;
+            if (hasReturn === hasException) {
+                throw new Error(`flow ${schema.name}: guard "${n.name}" check "${c.when}" must have exactly one of return/exception`);
+            }
+            if (c.check !== undefined) {
+                validateCondition(`flow ${schema.name}: guard "${n.name}" check "${c.when}"`, c.check);
+            }
+        }
+    }
+}
+// A condition must be a utils predicate call (boolean result, no result
+// slot) or a field comparison whose op is known and whose value presence and
+// type match the operator.
+const COMPARE_OPS = ['lt', 'le', 'gt', 'ge', 'eq', 'ne', 'isNull', 'isNotNull'];
+function validateCondition(where, c) {
+    if (!isCall(c)) {
+        const f = c.field;
+        if (typeof f !== 'object' || f === null || typeof f.slot !== 'object' || typeof f.field !== 'object') {
+            throw new Error(`${where}: ${c.op} field must be a slot field access like slots.args.amt`);
+        }
+        if (!COMPARE_OPS.includes(c.op)) {
+            throw new Error(`${where}: unknown comparison op ${String(c.op)}`);
+        }
+        const nullOp = c.op === 'isNull' || c.op === 'isNotNull';
+        if (nullOp && c.value !== undefined) {
+            throw new Error(`${where}: ${c.op} takes no value`);
+        }
+        if (!nullOp && c.value === undefined) {
+            throw new Error(`${where}: ${c.op} requires a value`);
+        }
+        const v = c.value;
+        if (v !== undefined && typeof v !== 'string' && typeof v !== 'number') {
+            const ev = v;
+            if (typeof ev !== 'object' || ev === null || ev.value === undefined || ev.symbol === undefined || ev.label === undefined) {
+                throw new Error(`${where}: ${c.op} value must be a string, number, or enum value`);
+            }
+        }
+        return;
+    }
+    const m = c.method;
+    if (m.type !== 'utilsMethod') {
+        throw new Error(`${where}: check call must be a utils predicate, got ${m.type ?? m.name}`);
+    }
+    if (c.result !== undefined) {
+        throw new Error(`${where}: a predicate call cannot bind a result slot`);
+    }
+}
+/** Slots a condition reads: a comparison's field slot or a predicate call's arg slots. */
+function conditionSlots(c) {
+    if (!isCall(c))
+        return [c.field.slot];
+    return c.args ?? [];
+}
+// ifNode rules: at least one case, every condition well-formed, and targets
+// are steps — flow exits (return/throw) belong to guard checks, not to
+// conditional jumps.
+function validateIfNode(n, schema) {
+    if (n.cases.length === 0) {
+        throw new Error(`flow ${schema.name}: ifNode "${n.name}" must have at least one case`);
+    }
+    for (const c of n.cases) {
+        validateCondition(`flow ${schema.name}: ifNode "${n.name}" case "${c.when}"`, c.check);
+        validateIfTarget(schema, n, c.to, `case "${c.when}"`);
+    }
+    validateIfTarget(schema, n, n.else, 'else');
+}
+function validateIfTarget(schema, n, t, where) {
+    if (isEnd(t)) {
+        throw new Error(`flow ${schema.name}: ifNode "${n.name}" ${where} must target a step — flow exits (return/throw) belong to guard checks`);
+    }
+}
+// Slots: every referenced slot must be declared in this flow's registers
+// (sub-flows analyze their own slots), every declared named slot must be
+// used, and a slot may only be consumed when every path from the start has
+// produced it (must-analysis over the control graph). The built-in args slot
+// is the flow input: it needs no registration and is available on entry.
+// Within one node, calls run in order, so an earlier call's result feeds a
+// later call's args; the node's own writes feed everything after them.
+// Slot/contract type differences convert implicitly and are not validated.
+function validateSlots(schema) {
+    const registry = schema.slots;
+    const argsSlot = registry?.args;
+    const declared = new Set(registry === undefined ? [] : Object.values(registry));
+    const used = new Set();
+    const produced = new Map();
+    for (const n of schema.nodes) {
+        const p = new Set();
+        if (!isEnd(n) && !isTryNode(n)) {
+            if (isIfNode(n)) {
+                for (const c of n.cases) {
+                    for (const t of conditionSlots(c.check))
+                        used.add(t);
+                }
+            }
+            else {
+                for (const ref of n.methods ?? []) {
+                    if (!isCall(ref))
+                        continue;
+                    for (const t of ref.args ?? [])
+                        used.add(t);
+                    if (ref.result) {
+                        used.add(ref.result);
+                        p.add(ref.result);
+                    }
+                }
+                if (isFlowNode(n)) {
+                    for (const t of n.reads ?? [])
+                        used.add(t);
+                    if (n.publish?.payload)
+                        used.add(n.publish.payload);
+                    for (const t of n.writes ?? []) {
+                        used.add(t);
+                        p.add(t);
+                    }
+                }
+                if (isGuard(n)) {
+                    for (const ch of n.checks) {
+                        for (const t of ch.reads ?? [])
+                            used.add(t);
+                        if (ch.check) {
+                            for (const t of conditionSlots(ch.check))
+                                used.add(t);
+                        }
+                    }
+                }
+            }
+        }
+        produced.set(n, p);
+    }
+    // a branch edge's condition is decided at its start node
+    for (const e of schema.edges) {
+        if (!e.check)
+            continue;
+        for (const t of conditionSlots(e.check))
+            used.add(t);
+    }
+    for (const t of used) {
+        if (!declared.has(t)) {
+            if (t.name === 'args') {
+                throw new Error(`flow ${schema.name}: slot "args" is not declared — declare the flow's slots via defineSlots (its built-in args slot)`);
+            }
+            throw new Error(`flow ${schema.name}: slot "${t.name}" is not declared in the flow's slots`);
+        }
+    }
+    for (const t of declared) {
+        if (t === argsSlot)
+            continue; // the input slot needs no use
+        if (!used.has(t)) {
+            throw new Error(`flow ${schema.name}: slot "${t.name}" is declared but never used`);
+        }
+    }
+    // Fixpoint over the graph: available(n) = intersection over all incoming
+    // edges of (available(start) ∪ produced(start)). The input slot is seeded
+    // at the start. Sets only grow, so the fixpoint terminates. Incoming edges
+    // include the implicit ones (ifNode cases/else), so availability flows
+    // through decision nodes the same way reachability does.
+    const reverse = new Map();
+    for (const n of schema.nodes)
+        reverse.set(n, []);
+    for (const e of schema.edges)
+        reverse.get(e.end).push(e.start);
+    for (const n of schema.nodes) {
+        if (!isIfNode(n))
+            continue;
+        for (const c of n.cases)
+            reverse.get(c.to).push(n);
+        reverse.get(n.else).push(n);
+    }
+    const avail = new Map();
+    for (const n of schema.nodes)
+        avail.set(n, new Set());
+    const seeded = new Set();
+    if (argsSlot)
+        seeded.add(argsSlot);
+    for (const t of schema.entrySlots ?? []) {
+        if (!declared.has(t)) {
+            throw new Error(`flow ${schema.name}: entry slot "${t.name}" is not declared in the flow's slots`);
+        }
+        seeded.add(t);
+    }
+    // add one by one: this engine's Set.prototype.add takes a single value
+    for (const t of seeded)
+        avail.get(schema.start).add(t);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const n of schema.nodes) {
+            if (n === schema.start)
+                continue;
+            const incoming = reverse.get(n);
+            if (incoming.length === 0)
+                continue;
+            let intersection;
+            for (const srcN of incoming) {
+                const src = new Set(avail.get(srcN));
+                for (const t of produced.get(srcN))
+                    src.add(t);
+                intersection = intersection === undefined ? src : new Set([...intersection].filter((t) => src.has(t)));
+            }
+            if (intersection === undefined)
+                continue;
+            for (const t of intersection) {
+                if (!avail.get(n).has(t)) {
+                    avail.get(n).add(t);
+                    changed = true;
+                }
+            }
+        }
+    }
+    // Consumption check walks each node's ordered sequence: writes
+    // (constructions) first, then calls in order, then branch reads/checks.
+    const missing = (n, t) => {
+        if (n === schema.start) {
+            return new Error(`flow ${schema.name}: start node "${n.name}" cannot consume slot "${t.name}" — nothing else is produced before entry`);
+        }
+        return new Error(`flow ${schema.name}: node "${n.name}" reads slot "${t.name}" that may not be written on every path`);
+    };
+    for (const n of schema.nodes) {
+        if (isEnd(n) || isTryNode(n))
+            continue;
+        const inner = new Set(avail.get(n));
+        if (isFlowNode(n)) {
+            for (const t of n.writes ?? [])
+                inner.add(t);
+        }
+        if (!isIfNode(n)) {
+            for (const ref of n.methods ?? []) {
+                if (!isCall(ref))
+                    continue;
+                for (const t of ref.args ?? []) {
+                    if (!inner.has(t))
+                        throw missing(n, t);
+                }
+                if (ref.result)
+                    inner.add(ref.result);
+            }
+        }
+        if (isFlowNode(n)) {
+            for (const t of n.reads ?? []) {
+                if (!inner.has(t))
+                    throw missing(n, t);
+            }
+            if (n.publish?.payload && !inner.has(n.publish.payload))
+                throw missing(n, n.publish.payload);
+        }
+        if (isGuard(n)) {
+            for (const ch of n.checks) {
+                for (const t of ch.reads ?? []) {
+                    if (!inner.has(t))
+                        throw missing(n, t);
+                }
+                if (ch.check) {
+                    for (const t of conditionSlots(ch.check)) {
+                        if (!inner.has(t))
+                            throw missing(n, t);
+                    }
+                }
+            }
+        }
+        if (isIfNode(n)) {
+            for (const c of n.cases) {
+                for (const t of conditionSlots(c.check)) {
+                    if (!inner.has(t))
+                        throw missing(n, t);
+                }
+            }
+        }
+        // branch decisions read their slots at the end of the node
+        for (const e of schema.edges) {
+            if (e.start !== n || !e.check)
+                continue;
+            for (const t of conditionSlots(e.check)) {
+                if (!inner.has(t))
+                    throw missing(n, t);
+            }
+        }
+    }
+}
+// Every exception a step declares (methods throws, TryNode rethrows) must be
+// routed: typed throws edges or an untyped exception edge (catch-all). Guard
+// check exceptions route implicitly to the matching exception end and are not
+// covered here. The reverse direction (routed ⊆ declared) is intentionally
+// not validated while steps carry pure descriptors — a MethodSchema has no
+// throws field yet, so typed edges may document throws the descriptor cannot
+// express. Once contract refs replace the descriptors, the reverse check can
+// be enforced.
+function validateThrowsCoverage(n, schema) {
+    const declared = new Set();
+    if (!isTryNode(n) && !isIfNode(n)) {
+        for (const ref of n.methods ?? []) {
+            const m = methodOf(ref);
+            if ('throws' in m && m.throws) {
+                for (const e of m.throws)
+                    declared.add(e.name);
+            }
+        }
+    }
+    if (isTryNode(n)) {
+        for (const c of n.catches) {
+            for (const name of exceptionEndNames(c.handler))
+                declared.add(name);
+        }
+    }
+    if (declared.size === 0)
+        return;
+    const routed = new Set();
+    for (const e of schema.edges) {
+        if (e.start !== n)
+            continue;
+        if (e.throws) {
+            routed.add(e.throws.name);
+        }
+        else if (e.exception === true) {
+            return; // untyped exception edge: catch-all
+        }
+    }
+    for (const d of declared) {
+        if (!routed.has(d)) {
+            throw new Error(`flow ${schema.name}: node "${n.name}" declares throw ${d} but has no typed throws edge for it`);
+        }
+    }
+}
+// TryNode rules: catches must be unique with UnexpectedException last, every
+// body exception end needs a catch, every catch must match a body exception
+// end (no dead catches), and finally must be pure cleanup (no exception ends).
+// Body end names must be unique so catch matching is unambiguous. Catch
+// matching works on declared end names — reachability of a body end from the
+// body start is not analyzed (a dead region's end would still count).
+function validateTryNode(n, schema) {
+    const seen = new Set();
+    let catchAll = false;
+    for (const c of n.catches) {
+        if (seen.has(c.exception.name)) {
+            throw new Error(`flow ${schema.name}: tryNode "${n.name}" has duplicate catch ${c.exception.name}`);
+        }
+        seen.add(c.exception.name);
+        if (catchAll) {
+            throw new Error(`flow ${schema.name}: tryNode "${n.name}" catch ${c.exception.name} must precede the ${UnexpectedException.name} catch`);
+        }
+        if (c.exception.name === UnexpectedException.name)
+            catchAll = true;
+    }
+    const bodyEndCounts = new Map();
+    for (const node of n.body.nodes) {
+        if (isEnd(node) && node.type === 'exception' && node.exception) {
+            bodyEndCounts.set(node.exception.name, (bodyEndCounts.get(node.exception.name) ?? 0) + 1);
+        }
+    }
+    for (const [name, count] of bodyEndCounts) {
+        if (count > 1) {
+            throw new Error(`flow ${schema.name}: tryNode "${n.name}" body has ${count} exception ends named ${name}`);
+        }
+    }
+    const bodyEnds = new Set(bodyEndCounts.keys());
+    for (const name of bodyEnds) {
+        if (!seen.has(name)) {
+            throw new Error(`flow ${schema.name}: tryNode "${n.name}" body exception end ${name} has no catch`);
+        }
+    }
+    for (const c of n.catches) {
+        if (!bodyEnds.has(c.exception.name)) {
+            throw new Error(`flow ${schema.name}: tryNode "${n.name}" catch ${c.exception.name} matches no body exception end`);
+        }
+    }
+    if (n.finally) {
+        const f = exceptionEndNames(n.finally);
+        if (f.size > 0) {
+            throw new Error(`flow ${schema.name}: tryNode "${n.name}" finally must not declare exception ends: ${[...f].join(', ')}`);
+        }
+    }
+}
+/** Exception names declared by a flow's exception ends — the flow's escape
+ *  set (throws that reach the caller unless caught by an outer tryNode). */
+export function exceptionEndNames(flow) {
+    const names = new Set();
+    for (const n of flow.nodes) {
+        if (!isEnd(n) || n.type !== 'exception')
+            continue;
+        if (!n.exception) {
+            throw new Error(`flow ${flow.name}: exception end "${n.name}" has no exception type`);
+        }
+        names.add(n.exception.name);
+    }
+    return names;
+}
+export function isEnd(n) {
+    return 'type' in n && (n.type === 'return' || n.type === 'exception');
+}
+function messageName(t) {
+    return t?.name ?? 'an unnamed message';
+}
+export function isFlowNode(n) {
+    return !('type' in n);
+}
+export function isGuard(n) {
+    return 'type' in n && n.type === 'guard';
+}
+export function isTryNode(n) {
+    return 'type' in n && n.type === 'try';
+}
+export function isIfNode(n) {
+    return 'type' in n && n.type === 'if';
 }