@pylonts/dsl 1.1.6 → 1.1.12

package/src/flow.ts

@@ -1,70 +1,539 @@
-import { SchemaBase } from './dsl.js';
+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 { ConvertSchema } from './convert.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 and edges are separate entities. A FlowNode is a plain
-// named step; a FlowEdge references its start/end node objects directly (no
-// ids). Because a node object may appear in many edges, the graph can share
-// nodes, merge branches, and form cycles (e.g. poll-and-retry loops).
+// 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 node can invoke: contract references, or a pure descriptor
+/** 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
-  | ConvertSchema
+  | 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. */
+   *  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;
-  /** Methods this node invokes — contract references or pure descriptors
-   *  (rendered under the node label). */
-  methods?: FlowMethodRef[];
+  /** 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: FlowNode;
-  end: FlowNode;
-  /** Exception path (rendered dashed); defaults to normal. */
+  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: FlowNode;
+  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: FlowNode[];
+  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?: FlowMethodRef[] } = {},
+  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: FlowNode,
-  end: FlowNode,
-  options: { when?: string; description?: string; exception?: boolean } = {},
+  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 {
@@ -74,54 +543,143 @@ export function edge(
     when: options.when,
     description: options.description,
     exception: options.exception,
+    throws: options.throws,
+    check: options.check,
   };
 }
 
 export function defineFlow(
   name: string,
   schema: {
-    start: FlowNode;
-    edges: FlowEdge[];
+    start: FlowStep;
+    edges: (flow: FlowSchema) => FlowEdge[];
+    args?: DtoMessage;
+    results?: DtoMessage;
+    slots?: FlowSlots;
+    entrySlots?: FlowSlot[];
     description?: string;
   },
 ): FlowSchema {
-  const seen = new Set<FlowNode>();
-  const nodes: FlowNode[] = [];
-  for (const e of schema.edges) {
-    for (const n of [e.start, e.end]) {
-      if (!seen.has(n)) {
-        seen.add(n);
-        nodes.push(n);
+  const 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);
   }
-  if (!seen.has(schema.start)) {
-    seen.add(schema.start);
-    nodes.push(schema.start);
+  addNode(schema.start);
+  // Guard targets resolve after every edge endpoint is collected, so an
+  // exception end referenced by any edge is reused before synthesis. ifNode
+  // targets (cases and else) are collected the same way — an ifNode has no
+  // outgoing edges, so its targets enter the flow only here. Targets chain
+  // (an ifNode may target another ifNode, or a guard whose implicit exit
+  // ends need collecting), so the loop runs over the growing list to a
+  // fixpoint instead of a snapshot.
+  for (let i = 0; i < nodes.length; i++) {
+    const n = nodes[i];
+    addGuardTargets(n);
+    if (isIfNode(n)) {
+      for (const c of n.cases) addNode(c.to);
+      addNode(n.else);
+    }
   }
-  const flow: FlowSchema = { name, description: schema.description, start: schema.start, nodes, edges: schema.edges };
+  flow.nodes = nodes;
   validate(flow);
   return flow;
 }
 
-// Nodes that never appear as an edge start are terminals. Reverse BFS from all
-// terminals marks every node that can reach a terminal; unmarked nodes sit on
-// a path that never ends (e.g. a cycle without an exit) — reject them at
-// definition time.
+// Reverse BFS from every FlowEnd marks all nodes that can reach an exit;
+// unmarked nodes sit on a path that never ends (e.g. a cycle without an exit)
+// — reject them at definition time. Guard checks count as implicit edges of
+// the guard itself; TryNode internals are validated inside their own flows.
 function validate(schema: FlowSchema): void {
-  const starts = new Set<FlowNode>();
-  for (const e of schema.edges) starts.add(e.start);
-
-  const reverse = new Map<FlowNode, FlowNode[]>();
+  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<FlowNode>();
-  const queue: FlowNode[] = [];
+  const reached = new Set<FlowNodeOrEnd>();
+  const queue: FlowNodeOrEnd[] = [];
   for (const n of schema.nodes) {
-    if (!starts.has(n)) {
+    if (isEnd(n)) {
       reached.add(n);
       queue.push(n);
     }
@@ -138,7 +696,532 @@ function validate(schema: FlowSchema): void {
 
   for (const n of schema.nodes) {
     if (!reached.has(n)) {
-      throw new Error(`flow ${schema.name}: node "${n.name}" cannot reach a terminal`);
+      throw new Error(`flow ${schema.name}: node "${n.name}" cannot reach an end node`);
+    }
+  }
+
+  // Forward BFS from the start: every node must be reachable, so dead regions
+  // cannot silently pollute the escape set (or the catch matching).
+  const fromStart = new Set<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';
 }