@pylonts/dsl 1.1.12 → 1.1.13

package/src/flow.ts

@@ -1,1227 +1,1273 @@
-import type { EnumDef, EnumValue, SchemaBase } from './dsl.js';
-import type { DtoMessage } from './dto.js';
-import type { DomainEventSchema } from './domain-event.js';
-import { UnexpectedException } from './exception.js';
-import type { ExceptionSchema } from './exception.js';
-import type { MethodSchema } from './method.js';
-import type { ConvertMethodSchema } from './convert.js';
-import type { DaoMethodSchema } from './dao.js';
-import type { ServiceMethodSchema } from './service.js';
-import type { ThirdServiceMethodSchema } from './third-service.js';
-import type { UtilsMethodSchema } from './utils.js';
-
-// Flow model: nodes are executors, control flow lives on edges. A FlowNode is
-// an ordered sequence of method invocations (a basic block); when a method in
-// the sequence throws, the rest does not run. A GuardNode is a gate executor:
-// its checks are ordered decisions, the first check that holds routes out
-// (return or throw). A TryNode is a protected region: its body, every catch
-// handler, and the optional finally are all sub-flows — the body's exception
-// ends are matched against the catches by name, a handler's exception ends
-// rethrow out of the region, and all fall-through paths continue via the
-// TryNode's outgoing edges.
-//
-// Every flow has a built-in return exit (flow.returnEnd) plus any number of
-// exception exits: explicit defineExceptionEnd nodes (targets of typed throws
-// edges) or ends synthesized from guard checks. A guard exits implicitly — a
-// check returning routes to the return end, a check throwing routes to the
-// flow's exception end carrying the same name; no edges needed. A step's
-// declared exceptions (methods' contracts and TryNode rethrows) must be
-// routed by a typed throws edge or an untyped exception edge (catch-all).
-//
-// Data flows through slots (a compiler-like register file): the built-in args
-// slot carries the flow input and needs no registration, named slots carry
-// derived objects and are declared via defineSlots, and calls bind slots to
-// method args/results (converting implicitly when contracts differ).
-
-/** A method a flow step can invoke: contract references, or a pure descriptor
- *  (MethodSchema) for the period before the contract file exists. */
-export type FlowMethodRef =
-  | MethodSchema
-  | ConvertMethodSchema
-  | DaoMethodSchema
-  | ServiceMethodSchema
-  | ThirdServiceMethodSchema
-  | UtilsMethodSchema;
-
-/** One named data slot of a flow — a register holding a whole object (like a
- *  compiler's register file). The built-in args slot carries the flow input
- *  (flow.args) and needs no registration: parameters exist in every flow.
- *  Named slots carry derived objects and are declared by binding a method's
- *  args/results message. The declared type is documentation — passing a slot
- *  to a method with a different contract converts implicitly. Slots are scoped
- *  to their flow: they cross into a sub-flow only through the shared input
- *  (flow.args) and out of it only through the wrapping node's reads/writes
- *  declarations. */
-export interface FlowSlot {
-  name: string;
-  /** The contract message this slot was declared with (documentation only —
-   *  call sites convert implicitly). */
-  type?: unknown;
-  description?: string;
-  /** Field access (e.g. slots.args.amt): resolved at access time against the
-   *  slot's declared message fields, returning a SlotFieldRef for the
-   *  comparison builders. Unknown fields throw with the declared field list. */
-  [field: string]: unknown;
-}
-
-/** A field access on a slot (slots.args.amt): the slot plus the resolved
- *  field object from the slot's declared message. */
-export interface SlotFieldRef {
-  slot: FlowSlot;
-  /** The resolved field (DtoField | Field) — carries its schema for codegen. */
-  field: unknown;
-}
-
-/** A flow's slot registers: the built-in args slot plus named slots. */
-export type FlowSlots = { args: FlowSlot } & Record<string, FlowSlot>;
-
-/** 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<T extends Record<string, unknown>>(
-  slots: T,
-): { [K in keyof T]: FlowSlot & { name: K } } & { args: FlowSlot } {
-  const wrap = (slot: FlowSlot): FlowSlot => {
-    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 as { fields?: Record<string, unknown> } | undefined)?.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: Record<string, FlowSlot> = 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 as { [K in keyof T]: FlowSlot & { name: K } } & { args: FlowSlot };
-}
-
-// 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: FlowSlot): void {
-  const fields = (slot.type as { fields?: Record<string, unknown> } | undefined)?.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`,
-    );
-  }
-}
-
-/** A method call with slot bindings: the arg slots are passed to the method
- *  (converted implicitly when the contract differs), the result is assigned
- *  to the result slot. A plain method ref (or an invoke with no bindings) is
- *  a call with args = [slots.args] and no result — the common case. */
-export interface FlowCall {
-  method: FlowMethodRef;
-  /** Slots passed as the method's args — the input slot or derived slots.
-   *  A single-message contract takes the one slot; multiple slots are for
-   *  multi-param signatures (not modeled yet). */
-  args?: FlowSlot[];
-  /** Slot assigned from the method's results. */
-  result?: FlowSlot;
-}
-
-export function invoke(
-  method: FlowMethodRef,
-  options: { args?: FlowSlot[]; result?: FlowSlot } = {},
-): FlowCall {
-  return { method, args: options.args, result: options.result };
-}
-
-/** A node method: a plain contract reference or a call with slot bindings. */
-export type FlowNodeMethodRef = FlowMethodRef | FlowCall;
-
-export function isCall(m: FlowNodeMethodRef | GuardCondition): m is FlowCall {
-  return 'method' in m;
-}
-
-/** The underlying method of a (possibly bound) reference. */
-export function methodOf(m: FlowNodeMethodRef): FlowMethodRef {
-  return isCall(m) ? m.method : m;
-}
-
-/** Comparison operators of a structured condition: ordering, (in)equality
- *  against a literal or enum value, and null checks. */
-export type CompareOp = 'lt' | 'le' | 'gt' | 'ge' | 'eq' | 'ne' | 'isNull' | 'isNotNull';
-
-/** A field comparison: a slot field (slots.args.amt) against a literal or an
- *  enum value — the machine-readable form of a when text. isNull/isNotNull
- *  take no value; the others require one. */
-export interface Comparison {
-  kind: 'comparison';
-  op: CompareOp;
-  field: SlotFieldRef;
-  /** Compared-against value; null checks take none. */
-  value?: string | number | EnumValue;
-}
-
-/** The machine-readable condition behind a guard check or a branch edge
- *  (optional): a utils predicate call (its boolean result decides) or a field
- *  comparison. */
-export type GuardCondition = FlowCall | Comparison;
-
-function comparison(op: CompareOp, field: unknown, value?: string | number | EnumValue): Comparison {
-  const ref = field as Partial<SlotFieldRef> | null;
-  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: unknown, value: string | number): Comparison {
-  return comparison('lt', field, value);
-}
-export function le(field: unknown, value: string | number): Comparison {
-  return comparison('le', field, value);
-}
-export function gt(field: unknown, value: string | number): Comparison {
-  return comparison('gt', field, value);
-}
-export function ge(field: unknown, value: string | number): Comparison {
-  return comparison('ge', field, value);
-}
-export function eq(field: unknown, value: string | number | EnumValue): Comparison {
-  return comparison('eq', field, value);
-}
-export function ne(field: unknown, value: string | number | EnumValue): Comparison {
-  return comparison('ne', field, value);
-}
-export function isNull(field: unknown): Comparison {
-  return comparison('isNull', field);
-}
-export function isNotNull(field: unknown): Comparison {
-  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: EnumDef, symbol: string): EnumValue {
-  const v = def.values.find((v) => v.symbol === symbol);
-  if (v === undefined) {
-    throw new Error(`enum ${def.jsName} has no value "${symbol}"`);
-  }
-  return v;
-}
-
-/** Event publication: a flow node may publish one domain event. The outbox
- *  write joins the node's surrounding transaction — the event is durable with
- *  the node's other side effects. The payload slot defaults to the flow input
- *  (slots.args) when omitted. */
-export interface FlowPublish {
-  event: DomainEventSchema;
-  /** The slot carrying the event payload. */
-  payload?: FlowSlot;
-}
-
-export interface FlowNode extends SchemaBase {
-  /** Optional sub-flow. When present, entering this node runs the sub-flow;
-   *  after the sub-flow reaches any terminal node, the outer flow continues
-   *  via this node's outgoing edges. Sub-flows nest recursively. A plain
-   *  sub-flow may not declare exception ends — it is structure only; use a
-   *  tryNode for a protected region. */
-  flow?: FlowSchema;
-  /** Ordered execution sequence (basic block): methods run in order; if one
-   *  throws, the remaining methods are skipped. A plain reference is a call
-   *  receiving the input slot (slots.args) — the common case. */
-  methods?: FlowNodeMethodRef[];
-  /** A domain event published by this node (same transaction as its methods). */
-  publish?: FlowPublish;
-  /** Slots this node reads to decide its outgoing branches — a semantic
-   *  declaration, not enforced per branch. */
-  reads?: FlowSlot[];
-  /** Slots this node assigns without a method call (constructions). */
-  writes?: FlowSlot[];
-}
-
-// Plain FlowNodes carry no `type` field — the discriminant against
-// GuardNode/TryNode/FlowEnd is its absence (see the is* predicates).
-
-/** One gate check: when the condition holds, either return (early return to
- *  the flow's returnEnd) or throw the given exception (routed implicitly to
- *  the flow's exception end carrying the same name). Exactly one of
- *  return/exception must be set. */
-export interface GuardCheck {
-  /** Condition description shown on the branch edge. */
-  when: string;
-  /** The check returns early (to the flow's returnEnd) — no edge needed. */
-  return?: boolean;
-  /** The check throws this exception — routed implicitly to the flow's
-   *  exception end carrying the same name (no edge needed). */
-  exception?: ExceptionSchema;
-  /** Slots the check reads to decide. */
-  reads?: FlowSlot[];
-  /** Machine-readable condition behind `when` (optional): a utils predicate
-   *  call or a field comparison. Omitted when the condition stays descriptive. */
-  check?: GuardCondition;
-}
-
-/** Gate executor: an ordered set of checks. The first check whose condition
- *  holds routes out implicitly (return to the flow's return end, throw to the
- *  matching exception end); when none holds, the guard falls through its
- *  normal outgoing edges (linked with edge like any node). A guard is the
- *  graph form of a run of `if (bad) throw / return` guards. */
-export interface GuardNode extends SchemaBase {
-  type: 'guard';
-  /** Ordered decision sequence: methods run in order; if one throws, the
-   *  remaining methods are skipped. */
-  methods?: FlowNodeMethodRef[];
-  /** Ordered checks — first hit wins. */
-  checks: GuardCheck[];
-}
-
-/** One catch route of a TryNode: body exception type → handler sub-flow.
- *  First match wins, UnexpectedException is the catch-all and must come
- *  last. The handler's exception ends rethrow out of the TryNode. */
-export interface TryCatch {
-  /** Exception this catch handles — must match a body exception end. */
-  exception: ExceptionSchema;
-  /** Handler sub-flow: its return end falls through, its exception ends
-   *  rethrow (declared as the TryNode's own throws). */
-  handler: FlowSchema;
-  description?: string;
-}
-
-/** Protected region: body, catch handlers, and optional finally are all
- *  sub-flows. Entering the TryNode runs the body; the body's exception ends
- *  are matched against the catches, every catch handler and the body's normal
- *  completion pass through finally (when present), then continue via the
- *  TryNode's outgoing edges. Handler exception ends rethrow out of the region. */
-export interface TryNode extends SchemaBase {
-  type: 'try';
-  /** The protected region. Its exception ends are the region's throw sites. */
-  body: FlowSchema;
-  /** Ordered catch routes; UnexpectedException (catch-all) must be last. */
-  catches: TryCatch[];
-  /** Cleanup sub-flow: may not declare exception ends (Java finally rules). */
-  finally?: FlowSchema;
-}
-
-/** One branch of an ifNode: when the check holds, control moves to `to`. */
-export interface IfCase {
-  /** Branch label (rendered on the branch line). */
-  when: string;
-  /** Machine-readable condition — required (the ifNode's whole purpose). */
-  check: GuardCondition;
-  /** Jump target: a step (node/guard/tryNode/ifNode). Flow exits — return
-   *  and throw — belong to guard checks, so ends are rejected. */
-  to: FlowNodeOrEnd;
-}
-
-/** Decision node — the jump twin of a guard: ordered cases evaluated
- *  first-hit, the first check that holds routes to its target; when none
- *  holds, control goes to `else`. All exits are internal (cases and else),
- *  so the node has no outgoing edges. A guard decides exits (return/throw),
- *  an ifNode decides where control goes next (steps only). */
-export interface IfNode extends SchemaBase {
-  type: 'if';
-  /** Ordered branches — first hit wins. */
-  cases: IfCase[];
-  /** Default branch: a step (never a flow exit). */
-  else: FlowNodeOrEnd;
-}
-
-/** Decision node: ordered cases (check → target) plus a default branch. */
-export function ifNode(
-  name: string,
-  options: {
-    cases: IfCase[];
-    else: FlowNodeOrEnd;
-    description?: string;
-  },
-): IfNode {
-  return {
-    type: 'if',
-    name,
-    description: options.description,
-    cases: options.cases,
-    else: options.else,
-  };
-}
-
-/** Any node an edge can start from. */
-export type FlowStep = FlowNode | GuardNode | TryNode | IfNode;
-
-/** Any node an edge can point at: a step or a flow exit. */
-export type FlowNodeOrEnd = FlowStep | FlowEnd;
-
-/** A flow exit: normal return or uncaught exception. Never an edge start. */
-export interface FlowEnd extends SchemaBase {
-  type: 'return' | 'exception';
-  /** Uncaught exception this exit throws — set when type='exception'. */
-  exception?: ExceptionSchema;
-}
-
-/** 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: FlowSchema, exceptionName: string): FlowEnd | undefined {
-  return schema.nodes.find(
-    (n): n is FlowEnd => 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: FlowSchema, n: FlowStep, exceptionName: string): FlowNodeOrEnd | undefined {
-  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;
-}
-
-export interface FlowEdge extends SchemaBase {
-  /** Trigger condition; undefined = default path (success/normal). */
-  when?: string;
-  start: FlowStep;
-  end: FlowNodeOrEnd;
-  /** Exception path (rendered dashed); without `throws` it is a catch-all. */
-  exception?: boolean;
-  /** Typed exception propagation: this edge carries the named exception
-   *  (rendered dashed with a `throw X` label). Must target an exception end.
-   *  Carrying one of a guard's own check exceptions is rejected — guards
-   *  route those implicitly. */
-  throws?: ExceptionSchema;
-  /** Machine-readable condition behind `when` (optional): a utils predicate
-   *  call or a field comparison. */
-  check?: GuardCondition;
-}
-
-export interface FlowSchema extends SchemaBase {
-  /** Entry node. */
-  start: FlowStep;
-  /** Default exit — every flow has one; edge(node, flow.returnEnd) is a return. */
-  returnEnd: FlowEnd;
-  /** All nodes, collected from edges (deduplicated by object identity). */
-  nodes: FlowNodeOrEnd[];
-  /** Independent edges; a node may be start of many edges, so cycles are expressible. */
-  edges: FlowEdge[];
-  /** Input contract — mirrors a service method's args. */
-  args?: DtoMessage;
-  /** Output contract — mirrors a service method's results. */
-  results?: DtoMessage;
-  /** Declared slot registers of this flow (named slots + the built-in args
-   *  slot). Sub-flows analyze their own slots; sharing happens through the
-   *  same input object (args) or the wrapping node's reads/writes. */
-  slots?: FlowSlots;
-  /** Slots the enclosing flow has already produced before this sub-flow's
-   *  entry (input inheritance). Only meaningful for sub-flows (try bodies,
-   *  catch handlers, named sub-flows) — a top-level flow has none. */
-  entrySlots?: FlowSlot[];
-}
-
-/** Executor node: an ordered sequence of method invocations (and optionally
- *  one event publication). */
-export function node(
-  name: string,
-  options: {
-    flow?: FlowSchema;
-    description?: string;
-    methods?: FlowNodeMethodRef[];
-    publish?: FlowPublish;
-    reads?: FlowSlot[];
-    writes?: FlowSlot[];
-  } = {},
-): FlowNode {
-  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: string,
-  options: {
-    checks: GuardCheck[];
-    methods?: FlowNodeMethodRef[];
-    description?: string;
-  },
-): GuardNode {
-  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: string,
-  options: {
-    body: FlowSchema;
-    catches: TryCatch[];
-    finally?: FlowSchema;
-    description?: string;
-  },
-): TryNode {
-  return {
-    type: 'try',
-    name,
-    description: options.description,
-    body: options.body,
-    catches: options.catches,
-    finally: options.finally,
-  };
-}
-
-export function defineExceptionEnd(exception: ExceptionSchema, description?: string): FlowEnd {
-  return { type: 'exception', name: `throw ${exception.name}`, exception, description };
-}
-
-export function edge(
-  start: FlowStep,
-  end: FlowNodeOrEnd,
-  options: {
-    when?: string;
-    description?: string;
-    exception?: boolean;
-    throws?: ExceptionSchema;
-    check?: GuardCondition;
-  } = {},
-): FlowEdge {
-  // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
-  return {
-    name: `${start.name}->${end.name}`,
-    start,
-    end,
-    when: options.when,
-    description: options.description,
-    exception: options.exception,
-    throws: options.throws,
-    check: options.check,
-  };
-}
-
-export function defineFlow(
-  name: string,
-  schema: {
-    start: FlowStep;
-    edges: (flow: FlowSchema) => FlowEdge[];
-    args?: DtoMessage;
-    results?: DtoMessage;
-    slots?: FlowSlots;
-    entrySlots?: FlowSlot[];
-    description?: string;
-  },
-): FlowSchema {
-  const flow: FlowSchema = {
-    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<FlowNodeOrEnd>();
-  const nodes: FlowNodeOrEnd[] = [];
-  const addNode = (n: FlowNodeOrEnd): void => {
-    if (seen.has(n)) return;
-    seen.add(n);
-    nodes.push(n);
-  };
-  const addGuardTargets = (n: FlowStep): void => {
-    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): x is FlowEnd => 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);
-  }
-  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);
-    }
-  }
-  flow.nodes = nodes;
-  validate(flow);
-  return flow;
-}
-
-// 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: FlowSchema): void {
-  const reverse = new Map<FlowNodeOrEnd, FlowNodeOrEnd[]>();
-  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<FlowNodeOrEnd>();
-  const queue: FlowNodeOrEnd[] = [];
-  for (const n of schema.nodes) {
-    if (isEnd(n)) {
-      reached.add(n);
-      queue.push(n);
-    }
-  }
-  while (queue.length > 0) {
-    const cur = queue.shift()!;
-    for (const prev of reverse.get(cur)!) {
-      if (!reached.has(prev)) {
-        reached.add(prev);
-        queue.push(prev);
-      }
-    }
-  }
-
-  for (const n of schema.nodes) {
-    if (!reached.has(n)) {
-      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<FlowNodeOrEnd>();
-  const forward: FlowNodeOrEnd[] = [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: FlowSchema): void {
-  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: readonly CompareOp[] = ['lt', 'le', 'gt', 'ge', 'eq', 'ne', 'isNull', 'isNotNull'];
-
-function validateCondition(where: string, c: GuardCondition): void {
-  if (!isCall(c)) {
-    const f = c.field as Partial<SlotFieldRef> | null;
-    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 as readonly unknown[]).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 as Partial<EnumValue> | null;
-      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 as { type?: string; name: string };
-  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: GuardCondition): FlowSlot[] {
-  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: IfNode, schema: FlowSchema): void {
-  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: FlowSchema, n: IfNode, t: FlowNodeOrEnd, where: string): void {
-  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: FlowSchema): void {
-  const registry = schema.slots;
-  const argsSlot = registry?.args;
-  const declared = new Set<FlowSlot>(registry === undefined ? [] : Object.values(registry));
-  const used = new Set<FlowSlot>();
-
-  const produced = new Map<FlowNodeOrEnd, Set<FlowSlot>>();
-  for (const n of schema.nodes) {
-    const p = new Set<FlowSlot>();
-    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<FlowNodeOrEnd, FlowNodeOrEnd[]>();
-  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<FlowNodeOrEnd, Set<FlowSlot>>();
-  for (const n of schema.nodes) avail.set(n, new Set<FlowSlot>());
-  const seeded = new Set<FlowSlot>();
-  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: Set<FlowSlot> | undefined;
-      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: FlowStep, t: FlowSlot): Error => {
-    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: FlowStep, schema: FlowSchema): void {
-  const declared = new Set<string>();
-  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<string>();
-  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: TryNode, schema: FlowSchema): void {
-  const seen = new Set<string>();
-  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<string, number>();
-  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: FlowSchema): Set<string> {
-  const names = new Set<string>();
-  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: FlowNodeOrEnd): n is FlowEnd {
-  return 'type' in n && (n.type === 'return' || n.type === 'exception');
-}
-
-function messageName(t: unknown): string {
-  return (t as { name?: string } | null | undefined)?.name ?? 'an unnamed message';
-}
-
-export function isFlowNode(n: FlowNodeOrEnd): n is FlowNode {
-  return !('type' in n);
-}
-
-export function isGuard(n: FlowNodeOrEnd): n is GuardNode {
-  return 'type' in n && n.type === 'guard';
-}
-
-export function isTryNode(n: FlowNodeOrEnd): n is TryNode {
-  return 'type' in n && n.type === 'try';
-}
-
-export function isIfNode(n: FlowNodeOrEnd): n is IfNode {
-  return 'type' in n && n.type === 'if';
+import type { EnumDef, EnumValue, SchemaBase } from './dsl.js';
+import type { DtoMessage } from './dto.js';
+import type { DomainEventSchema } from './domain-event.js';
+import { UnexpectedException } from './exception.js';
+import type { ExceptionSchema } from './exception.js';
+import type { MethodSchema } from './method.js';
+import type { ConvertMethodSchema } from './convert.js';
+import type { DaoMethodSchema } from './dao.js';
+import type { ServiceMethodSchema } from './service.js';
+import type { ThirdServiceMethodSchema } from './third-service.js';
+import type { UtilsMethodSchema } from './utils.js';
+
+// Flow model: nodes are executors, control flow lives on edges. A FlowNode is
+// an ordered sequence of method invocations (a basic block); when a method in
+// the sequence throws, the rest does not run. A GuardNode is a gate executor:
+// its checks are ordered decisions, the first check that holds routes out
+// (return or throw). A TryNode is a protected region: its body, every catch
+// handler, and the optional finally are all sub-flows — the body's exception
+// ends are matched against the catches by name, a handler's exception ends
+// rethrow out of the region, and all fall-through paths continue via the
+// TryNode's outgoing edges.
+//
+// Every flow has a built-in return exit (flow.returnEnd) plus any number of
+// exception exits: explicit defineExceptionEnd nodes (targets of typed throws
+// edges) or ends synthesized from guard checks. A guard exits implicitly — a
+// check returning routes to the return end, a check throwing routes to the
+// flow's exception end carrying the same name; no edges needed. A step's
+// declared exceptions (methods' contracts and TryNode rethrows) must be
+// routed by a typed throws edge or an untyped exception edge (catch-all).
+//
+// Data flows through slots (a compiler-like register file): the built-in args
+// slot carries the flow input and needs no registration, named slots carry
+// derived objects and are declared via defineSlots, and calls bind slots to
+// method args/results (converting implicitly when contracts differ).
+
+/** A method a flow step can invoke: contract references, or a pure descriptor
+ *  (MethodSchema) for the period before the contract file exists.
+ *  Third-party methods are their own contract (ThirdServiceMethodSchema) —
+ *  they can never bind a flow. */
+export type FlowMethodRef =
+  | MethodSchema
+  | ConvertMethodSchema
+  | DaoMethodSchema
+  | ServiceMethodSchema
+  | ThirdServiceMethodSchema
+  | UtilsMethodSchema;
+
+/** One named data slot of a flow — a register holding a whole object (like a
+ *  compiler's register file). The built-in args slot carries the flow input
+ *  (flow.args) and needs no registration: parameters exist in every flow.
+ *  Named slots carry derived objects and are declared by binding a method's
+ *  args/results message. The declared type is documentation — passing a slot
+ *  to a method with a different contract converts implicitly. Slots are scoped
+ *  to their flow: they cross into a sub-flow only through the shared input
+ *  (flow.args) and out of it only through the wrapping node's reads/writes
+ *  declarations. */
+export interface FlowSlot {
+  name: string;
+  /** The contract message this slot was declared with (documentation only —
+   *  call sites convert implicitly). */
+  type?: unknown;
+  description?: string;
+  /** Field access (e.g. slots.args.amt): resolved at access time against the
+   *  slot's declared message fields, returning a SlotFieldRef for the
+   *  comparison builders. Unknown fields throw with the declared field list. */
+  [field: string]: unknown;
+}
+
+/** A field access on a slot (slots.args.amt): the slot plus the resolved
+ *  field object from the slot's declared message. */
+export interface SlotFieldRef {
+  slot: FlowSlot;
+  /** The resolved field (DtoField | Field) — carries its schema for codegen. */
+  field: unknown;
+}
+
+/** A flow's slot registers: the built-in args slot plus named slots. */
+export type FlowSlots = { args: FlowSlot } & Record<string, FlowSlot>;
+
+/** 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<T extends Record<string, unknown>>(
+  slots: T,
+): { [K in keyof T]: FlowSlot & { name: K } } & { args: FlowSlot } {
+  const wrap = (slot: FlowSlot): FlowSlot => {
+    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 typeObj = target.type as
+          | { fields?: Record<string, unknown>; columns?: Array<{ name: string }> }
+          | undefined;
+        const fields = slotFields(typeObj);
+        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: Record<string, FlowSlot> = 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 as { [K in keyof T]: FlowSlot & { name: K } } & { args: FlowSlot };
+}
+
+// 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: FlowSlot): void {
+  const fields = slotFields(slot.type);
+  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`,
+    );
+  }
+}
+
+/** Field map of a slot's declared type: dto/third messages carry `fields`,
+ *  entity rows carry `columns` (named Fields). */
+function slotFields(type: unknown): Record<string, unknown> | undefined {
+  if (typeof type !== 'object' || type === null) return undefined;
+  const t = type as { fields?: Record<string, unknown>; columns?: Array<{ name: string }> };
+  if (t.fields !== undefined) return t.fields;
+  if (t.columns !== undefined) {
+    return Object.fromEntries(t.columns.map((c) => [c.name, c]));
+  }
+  return undefined;
+}
+
+/** A method call with slot bindings: the arg slots are passed to the method
+ *  (converted implicitly when the contract differs), the result is assigned
+ *  to the result slot. A plain method ref (or an invoke with no bindings) is
+ *  a call with args = [slots.args] and no result — the common case. */
+export interface FlowCall {
+  method: FlowMethodRef;
+  /** Slots passed as the method's args — the input slot or derived slots.
+   *  A single-message contract takes the one slot; multiple slots are for
+   *  multi-param signatures (not modeled yet). */
+  args?: FlowSlot[];
+  /** Slot assigned from the method's results. */
+  result?: FlowSlot;
+}
+
+export function invoke(
+  method: FlowMethodRef,
+  options: { args?: FlowSlot[]; result?: FlowSlot } = {},
+): FlowCall {
+  return { method, args: options.args, result: options.result };
+}
+
+/** A node method: a plain contract reference or a call with slot bindings. */
+export type FlowNodeMethodRef = FlowMethodRef | FlowCall;
+
+export function isCall(m: FlowNodeMethodRef | GuardCondition): m is FlowCall {
+  return 'method' in m;
+}
+
+/** The underlying method of a (possibly bound) reference. */
+export function methodOf(m: FlowNodeMethodRef): FlowMethodRef {
+  return isCall(m) ? m.method : m;
+}
+
+/** Comparison operators of a structured condition: ordering, (in)equality
+ *  against a literal or enum value, and null checks. */
+export type CompareOp = 'lt' | 'le' | 'gt' | 'ge' | 'eq' | 'ne' | 'isNull' | 'isNotNull';
+
+/** A field comparison: a slot field (slots.args.amt) against a literal or an
+ *  enum value — the machine-readable form of a when text. isNull/isNotNull
+ *  take no value; the others require one. */
+export interface Comparison {
+  kind: 'comparison';
+  op: CompareOp;
+  /** Field-level comparisons bind a slot field; slot-level null checks
+   *  (isNull/isNotNull on the slot itself) bind the slot directly. */
+  field: SlotFieldRef | FlowSlot;
+  /** Compared-against value; null checks take none. */
+  value?: string | number | EnumValue;
+}
+
+/** The machine-readable condition behind a guard check or a branch edge
+ *  (optional): a utils predicate call (its boolean result decides) or a field
+ *  comparison. */
+export type GuardCondition = FlowCall | Comparison;
+
+/** True when the condition operand is the slot itself (slot-level null check),
+ *  not a field access on it. Slot metadata (name) lives on the proxy target and
+ *  reads without field interception; a field access resolves to { slot, field }. */
+export function isFlowSlot(v: unknown): v is FlowSlot {
+  return typeof v === 'object' && v !== null && typeof (v as FlowSlot).name === 'string';
+}
+
+function comparison(op: CompareOp, field: unknown, value?: string | number | EnumValue): Comparison {
+  if (isFlowSlot(field)) {
+    if (op !== 'isNull' && op !== 'isNotNull') {
+      throw new Error(`${op}: a slot-level check only supports isNull/isNotNull — field comparisons need slots.args.amt`);
+    }
+    if (value !== undefined) {
+      throw new Error(`${op}: takes no value`);
+    }
+    return { kind: 'comparison', op, field, value };
+  }
+  const ref = field as Partial<SlotFieldRef> | null;
+  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: unknown, value: string | number): Comparison {
+  return comparison('lt', field, value);
+}
+export function le(field: unknown, value: string | number): Comparison {
+  return comparison('le', field, value);
+}
+export function gt(field: unknown, value: string | number): Comparison {
+  return comparison('gt', field, value);
+}
+export function ge(field: unknown, value: string | number): Comparison {
+  return comparison('ge', field, value);
+}
+export function eq(field: unknown, value: string | number | EnumValue): Comparison {
+  return comparison('eq', field, value);
+}
+export function ne(field: unknown, value: string | number | EnumValue): Comparison {
+  return comparison('ne', field, value);
+}
+export function isNull(field: unknown): Comparison {
+  return comparison('isNull', field);
+}
+export function isNotNull(field: unknown): Comparison {
+  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: EnumDef, symbol: string): EnumValue {
+  const v = def.values.find((v) => v.symbol === symbol);
+  if (v === undefined) {
+    throw new Error(`enum ${def.jsName} has no value "${symbol}"`);
+  }
+  return v;
+}
+
+/** Event publication: a flow node may publish one domain event. The outbox
+ *  write joins the node's surrounding transaction — the event is durable with
+ *  the node's other side effects. The payload slot defaults to the flow input
+ *  (slots.args) when omitted. */
+export interface FlowPublish {
+  event: DomainEventSchema;
+  /** The slot carrying the event payload. */
+  payload?: FlowSlot;
+}
+
+export interface FlowNode extends SchemaBase {
+  /** Optional sub-flow. When present, entering this node runs the sub-flow;
+   *  after the sub-flow reaches any terminal node, the outer flow continues
+   *  via this node's outgoing edges. Sub-flows nest recursively. A plain
+   *  sub-flow may not declare exception ends — it is structure only; use a
+   *  tryNode for a protected region. */
+  flow?: FlowSchema;
+  /** Ordered execution sequence (basic block): methods run in order; if one
+   *  throws, the remaining methods are skipped. A plain reference is a call
+   *  receiving the input slot (slots.args) — the common case. */
+  methods?: FlowNodeMethodRef[];
+  /** A domain event published by this node (same transaction as its methods). */
+  publish?: FlowPublish;
+  /** Slots this node reads to decide its outgoing branches — a semantic
+   *  declaration, not enforced per branch. */
+  reads?: FlowSlot[];
+  /** Slots this node assigns without a method call (constructions). */
+  writes?: FlowSlot[];
+}
+
+// Plain FlowNodes carry no `type` field — the discriminant against
+// GuardNode/TryNode/FlowEnd is its absence (see the is* predicates).
+
+/** One gate check: when the condition holds, either return (early return to
+ *  the flow's returnEnd) or throw the given exception (routed implicitly to
+ *  the flow's exception end carrying the same name). Exactly one of
+ *  return/exception must be set. */
+export interface GuardCheck {
+  /** Condition description shown on the branch edge. */
+  when: string;
+  /** The check returns early (to the flow's returnEnd) — no edge needed. */
+  return?: boolean;
+  /** The check throws this exception — routed implicitly to the flow's
+   *  exception end carrying the same name (no edge needed). */
+  exception?: ExceptionSchema;
+  /** Slots the check reads to decide. */
+  reads?: FlowSlot[];
+  /** Machine-readable condition behind `when` (optional): a utils predicate
+   *  call or a field comparison. Omitted when the condition stays descriptive. */
+  check?: GuardCondition;
+}
+
+/** Gate executor: an ordered set of checks. The first check whose condition
+ *  holds routes out implicitly (return to the flow's return end, throw to the
+ *  matching exception end); when none holds, the guard falls through its
+ *  normal outgoing edges (linked with edge like any node). A guard is the
+ *  graph form of a run of `if (bad) throw / return` guards. */
+export interface GuardNode extends SchemaBase {
+  type: 'guard';
+  /** Ordered decision sequence: methods run in order; if one throws, the
+   *  remaining methods are skipped. */
+  methods?: FlowNodeMethodRef[];
+  /** Ordered checks — first hit wins. */
+  checks: GuardCheck[];
+}
+
+/** One catch route of a TryNode: body exception type → handler sub-flow.
+ *  First match wins, UnexpectedException is the catch-all and must come
+ *  last. The handler's exception ends rethrow out of the TryNode. */
+export interface TryCatch {
+  /** Exception this catch handles — must match a body exception end. */
+  exception: ExceptionSchema;
+  /** Handler sub-flow: its return end falls through, its exception ends
+   *  rethrow (declared as the TryNode's own throws). */
+  handler: FlowSchema;
+  description?: string;
+}
+
+/** Protected region: body, catch handlers, and optional finally are all
+ *  sub-flows. Entering the TryNode runs the body; the body's exception ends
+ *  are matched against the catches, every catch handler and the body's normal
+ *  completion pass through finally (when present), then continue via the
+ *  TryNode's outgoing edges. Handler exception ends rethrow out of the region. */
+export interface TryNode extends SchemaBase {
+  type: 'try';
+  /** The protected region. Its exception ends are the region's throw sites. */
+  body: FlowSchema;
+  /** Ordered catch routes; UnexpectedException (catch-all) must be last. */
+  catches: TryCatch[];
+  /** Cleanup sub-flow: may not declare exception ends (Java finally rules). */
+  finally?: FlowSchema;
+}
+
+/** One branch of an ifNode: when the check holds, control moves to `to`. */
+export interface IfCase {
+  /** Branch label (rendered on the branch line). */
+  when: string;
+  /** Machine-readable condition — required (the ifNode's whole purpose). */
+  check: GuardCondition;
+  /** Jump target: a step (node/guard/tryNode/ifNode). Flow exits — return
+   *  and throw — belong to guard checks, so ends are rejected. */
+  to: FlowNodeOrEnd;
+}
+
+/** Decision node — the jump twin of a guard: ordered cases evaluated
+ *  first-hit, the first check that holds routes to its target; when none
+ *  holds, control goes to `else`. All exits are internal (cases and else),
+ *  so the node has no outgoing edges. A guard decides exits (return/throw),
+ *  an ifNode decides where control goes next (steps only). */
+export interface IfNode extends SchemaBase {
+  type: 'if';
+  /** Ordered branches — first hit wins. */
+  cases: IfCase[];
+  /** Default branch: a step (never a flow exit). */
+  else: FlowNodeOrEnd;
+}
+
+/** Decision node: ordered cases (check → target) plus a default branch. */
+export function ifNode(
+  name: string,
+  options: {
+    cases: IfCase[];
+    else: FlowNodeOrEnd;
+    description?: string;
+  },
+): IfNode {
+  return {
+    type: 'if',
+    name,
+    description: options.description,
+    cases: options.cases,
+    else: options.else,
+  };
+}
+
+/** Any node an edge can start from. */
+export type FlowStep = FlowNode | GuardNode | TryNode | IfNode;
+
+/** Any node an edge can point at: a step or a flow exit. */
+export type FlowNodeOrEnd = FlowStep | FlowEnd;
+
+/** A flow exit: normal return or uncaught exception. Never an edge start. */
+export interface FlowEnd extends SchemaBase {
+  type: 'return' | 'exception';
+  /** Uncaught exception this exit throws — set when type='exception'. */
+  exception?: ExceptionSchema;
+}
+
+/** 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: FlowSchema, exceptionName: string): FlowEnd | undefined {
+  return schema.nodes.find(
+    (n): n is FlowEnd => 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: FlowSchema, n: FlowStep, exceptionName: string): FlowNodeOrEnd | undefined {
+  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;
+}
+
+export interface FlowEdge extends SchemaBase {
+  /** Trigger condition; undefined = default path (success/normal). */
+  when?: string;
+  start: FlowStep;
+  end: FlowNodeOrEnd;
+  /** Exception path (rendered dashed); without `throws` it is a catch-all. */
+  exception?: boolean;
+  /** Typed exception propagation: this edge carries the named exception
+   *  (rendered dashed with a `throw X` label). Must target an exception end.
+   *  Carrying one of a guard's own check exceptions is rejected — guards
+   *  route those implicitly. */
+  throws?: ExceptionSchema;
+  /** Machine-readable condition behind `when` (optional): a utils predicate
+   *  call or a field comparison. */
+  check?: GuardCondition;
+}
+
+export interface FlowSchema extends SchemaBase {
+  /** Entry node. */
+  start: FlowStep;
+  /** Default exit — every flow has one; edge(node, flow.returnEnd) is a return. */
+  returnEnd: FlowEnd;
+  /** All nodes, collected from edges (deduplicated by object identity). */
+  nodes: FlowNodeOrEnd[];
+  /** Independent edges; a node may be start of many edges, so cycles are expressible. */
+  edges: FlowEdge[];
+  /** Input contract — mirrors a service method's args. */
+  args?: DtoMessage;
+  /** Output contract — mirrors a service method's results. */
+  results?: DtoMessage;
+  /** Declared slot registers of this flow (named slots + the built-in args
+   *  slot). Sub-flows analyze their own slots; sharing happens through the
+   *  same input object (args) or the wrapping node's reads/writes. */
+  slots?: FlowSlots;
+  /** Slots the enclosing flow has already produced before this sub-flow's
+   *  entry (input inheritance). Only meaningful for sub-flows (try bodies,
+   *  catch handlers, named sub-flows) — a top-level flow has none. */
+  entrySlots?: FlowSlot[];
+}
+
+/** Executor node: an ordered sequence of method invocations (and optionally
+ *  one event publication). */
+export function node(
+  name: string,
+  options: {
+    flow?: FlowSchema;
+    description?: string;
+    methods?: FlowNodeMethodRef[];
+    publish?: FlowPublish;
+    reads?: FlowSlot[];
+    writes?: FlowSlot[];
+  } = {},
+): FlowNode {
+  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: string,
+  options: {
+    checks: GuardCheck[];
+    methods?: FlowNodeMethodRef[];
+    description?: string;
+  },
+): GuardNode {
+  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: string,
+  options: {
+    body: FlowSchema;
+    catches: TryCatch[];
+    finally?: FlowSchema;
+    description?: string;
+  },
+): TryNode {
+  return {
+    type: 'try',
+    name,
+    description: options.description,
+    body: options.body,
+    catches: options.catches,
+    finally: options.finally,
+  };
+}
+
+export function defineExceptionEnd(exception: ExceptionSchema, description?: string): FlowEnd {
+  return { type: 'exception', name: `throw ${exception.name}`, exception, description };
+}
+
+export function edge(
+  start: FlowStep,
+  end: FlowNodeOrEnd,
+  options: {
+    when?: string;
+    description?: string;
+    exception?: boolean;
+    throws?: ExceptionSchema;
+    check?: GuardCondition;
+  } = {},
+): FlowEdge {
+  // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
+  return {
+    name: `${start.name}->${end.name}`,
+    start,
+    end,
+    when: options.when,
+    description: options.description,
+    exception: options.exception,
+    throws: options.throws,
+    check: options.check,
+  };
+}
+
+export function defineFlow(
+  name: string,
+  schema: {
+    start: FlowStep;
+    edges: (flow: FlowSchema) => FlowEdge[];
+    args?: DtoMessage;
+    results?: DtoMessage;
+    slots?: FlowSlots;
+    entrySlots?: FlowSlot[];
+    description?: string;
+  },
+): FlowSchema {
+  const flow: FlowSchema = {
+    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<FlowNodeOrEnd>();
+  const nodes: FlowNodeOrEnd[] = [];
+  const addNode = (n: FlowNodeOrEnd): void => {
+    if (seen.has(n)) return;
+    seen.add(n);
+    nodes.push(n);
+  };
+  const addGuardTargets = (n: FlowStep): void => {
+    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): x is FlowEnd => 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);
+  }
+  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);
+    }
+  }
+  flow.nodes = nodes;
+  validate(flow);
+  return flow;
+}
+
+// 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: FlowSchema): void {
+  const reverse = new Map<FlowNodeOrEnd, FlowNodeOrEnd[]>();
+  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<FlowNodeOrEnd>();
+  const queue: FlowNodeOrEnd[] = [];
+  for (const n of schema.nodes) {
+    if (isEnd(n)) {
+      reached.add(n);
+      queue.push(n);
+    }
+  }
+  while (queue.length > 0) {
+    const cur = queue.shift()!;
+    for (const prev of reverse.get(cur)!) {
+      if (!reached.has(prev)) {
+        reached.add(prev);
+        queue.push(prev);
+      }
+    }
+  }
+
+  for (const n of schema.nodes) {
+    if (!reached.has(n)) {
+      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<FlowNodeOrEnd>();
+  const forward: FlowNodeOrEnd[] = [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: FlowSchema): void {
+  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: readonly CompareOp[] = ['lt', 'le', 'gt', 'ge', 'eq', 'ne', 'isNull', 'isNotNull'];
+
+function validateCondition(where: string, c: GuardCondition): void {
+  if (!isCall(c)) {
+    if (isFlowSlot(c.field)) {
+      const nullOp = c.op === 'isNull' || c.op === 'isNotNull';
+      if (!nullOp) {
+        throw new Error(`${where}: a slot-level check only supports isNull/isNotNull`);
+      }
+      if (c.value !== undefined) {
+        throw new Error(`${where}: ${c.op} takes no value`);
+      }
+      return;
+    }
+    const f = c.field as Partial<SlotFieldRef> | null;
+    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 as readonly unknown[]).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 as Partial<EnumValue> | null;
+      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 as { type?: string; name: string };
+  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 the slot itself for
+ *  slot-level checks) or a predicate call's arg slots. */
+function conditionSlots(c: GuardCondition): FlowSlot[] {
+  if (!isCall(c)) return [isFlowSlot(c.field) ? c.field : 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: IfNode, schema: FlowSchema): void {
+  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: FlowSchema, n: IfNode, t: FlowNodeOrEnd, where: string): void {
+  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: FlowSchema): void {
+  const registry = schema.slots;
+  const argsSlot = registry?.args;
+  const declared = new Set<FlowSlot>(registry === undefined ? [] : Object.values(registry));
+  const used = new Set<FlowSlot>();
+
+  const produced = new Map<FlowNodeOrEnd, Set<FlowSlot>>();
+  for (const n of schema.nodes) {
+    const p = new Set<FlowSlot>();
+    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<FlowNodeOrEnd, FlowNodeOrEnd[]>();
+  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<FlowNodeOrEnd, Set<FlowSlot>>();
+  for (const n of schema.nodes) avail.set(n, new Set<FlowSlot>());
+  const seeded = new Set<FlowSlot>();
+  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: Set<FlowSlot> | undefined;
+      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: FlowStep, t: FlowSlot): Error => {
+    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: FlowStep, schema: FlowSchema): void {
+  const declared = new Set<string>();
+  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<string>();
+  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: TryNode, schema: FlowSchema): void {
+  const seen = new Set<string>();
+  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<string, number>();
+  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: FlowSchema): Set<string> {
+  const names = new Set<string>();
+  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: FlowNodeOrEnd): n is FlowEnd {
+  return 'type' in n && (n.type === 'return' || n.type === 'exception');
+}
+
+function messageName(t: unknown): string {
+  return (t as { name?: string } | null | undefined)?.name ?? 'an unnamed message';
+}
+
+export function isFlowNode(n: FlowNodeOrEnd): n is FlowNode {
+  return !('type' in n);
+}
+
+export function isGuard(n: FlowNodeOrEnd): n is GuardNode {
+  return 'type' in n && n.type === 'guard';
+}
+
+export function isTryNode(n: FlowNodeOrEnd): n is TryNode {
+  return 'type' in n && n.type === 'try';
+}
+
+export function isIfNode(n: FlowNodeOrEnd): n is IfNode {
+  return 'type' in n && n.type === 'if';
 }