@jr2/orchestrator 0.3.0 → 0.4.1

package/src/setup.ts

@@ -42,22 +42,43 @@ import {
   type UnknownActorLogic,
 } from "xstate";
 import type { z } from "zod";
-import { eventMap, type EventDef, type EventFrom } from "@jr2/agent-protocol";
+import { eventMap, type EventDef, type EventFrom, type Sender } from "@jr2/agent-protocol";
 import type { AgentRunInput, AgentTurnInput, FaultTelemetry } from "./actor.ts";
 import { isAgent } from "./agent.ts";
+import { isEffect } from "./effect.ts";
+import { effectChecks } from "./effect-checks.ts";
 import { gate } from "./gate.ts";
+import { attachLent, isOpenBody, openBodyDeclarationOf, type LentParts } from "./open-body.ts";
+import { refuseInlineParts } from "./parts.ts";
+import { partyWarnings, refuseUnknownSentBy, SENT_BY, sentByGuard } from "./party.ts";
 import { boundEpoch, boundRunId, continuedIid } from "./registration.ts";
-import { attachInputSchema, attachVocabulary } from "./vocabulary.ts";
+import { attachInputSchema, attachLoadWarnings, attachSeats, attachVocabulary } from "./vocabulary.ts";
 
 /**
  * The events jr2's own mechanism delivers into any workflow machine, injected into every jr2Setup
  * union. Dotted names by construction (`NAME_RE` forbids dots in workflow event names), so they
  * can never collide with a def.
  */
-export type MechanismEvent = FaultTelemetry | { type: "workspace.lost" };
+export type MechanismEvent = FaultTelemetry | WorkspaceLost;
 
-/** The full event union a jr2Setup machine sees: the defs' derived types plus the mechanism's. */
-export type WorkflowEvent<TDefs extends readonly EventDef[]> = EventFrom<TDefs[number]> | MechanismEvent;
+/**
+ * A Workspace's Continuity broke (ADR-0021): its Sandbox is gone, or Lost. `reason` and `message`
+ * say why — the pod's own reason (`Evicted`, `NodeShutdown`, ...) or the operator's (`PodDeleted`,
+ * `NodeLost`), or `Deleted` for a Sandbox that is gone — for a body whose policy tells them apart,
+ * or only reports them. Optional: the body's policy never needs them to act.
+ */
+export type WorkspaceLost = { type: "workspace.lost"; reason?: string; message?: string };
+
+/** The full event union a jr2Setup machine sees: the defs' derived types plus the mechanism's. A
+ * workflow event a party delivered carries its `sender` (ADR-0015); the Machine's own events
+ * (`raise`, `sendTo` itself) carry none. */
+export type WorkflowEvent<TDefs extends readonly EventDef[]> =
+  | (EventFrom<TDefs[number]> & { readonly sender?: Sender })
+  | MechanismEvent;
+
+/** The guard jr2Setup registers for every Machine — `sentBy(id)` (ADR-0015) — in the typed guard
+ * map, so `sentBy("coder")` and `and([sentBy("coder"), "ready"])` type-check with no cast. */
+type SentByGuards = { [SENT_BY]: { id: string } };
 
 /** The jr2 actor every workflow can invoke by name without listing it (ADR-0015). `gate` is the
  * whole set: an Agent is not pre-registered, because it is not one logic — it is the slot the
@@ -136,7 +157,7 @@ export function jr2Setup<
   MergedActors<TActors>,
   {},
   TActions,
-  TGuards,
+  TGuards & SentByGuards,
   TDelay,
   TTag,
   TInput,
@@ -148,7 +169,8 @@ export function jr2Setup<
     types: def.types,
     actors: { ...jr2Actors, ...(def.actors ?? {}) },
     actions: def.actions,
-    guards: def.guards,
+    // `sentBy(id)` is a named guard with params, so the load walk can READ it (ADR-0015).
+    guards: { ...(def.guards ?? {}), [SENT_BY]: sentByGuard },
     delays: def.delays,
   } as never);
 
@@ -163,13 +185,17 @@ export function jr2Setup<
     // the same loud failure `eventMap` gave the manifest, moved to machine-build time)…
     const defs = eventMap((machineConfig as { id?: string }).id ?? "(machine)", def.events);
 
+    // Every Open body slot (ADR-0070), found by its brand: each name it lends resolves against THIS
+    // setup's own parts, or the Machine is refused naming it. The resolved set is stamped on the slot,
+    // for the door that admits a Chart before a run and for the walk at `jr2 up`.
+    stampOpenBodies((machineConfig as { id?: string }).id ?? "(machine)", def);
+
     // …then rewrite the config (ADR-0015): every Agent-slot/`gate` invoke's input is wrapped to
     // append its DERIVED menu and finalize the mechanism fields. Static — the walk sees the same
     // config the Console will — and the derived names still ride serializable input, so the
     // ADR-0007 restore path and invoke-time `resolveAccepts` validation are unchanged.
-    const machine = (inner.createMachine as unknown as (c: never) => AnyStateMachine)(
-      deriveMenus(machineConfig, defs, def.actors ?? {}) as never,
-    );
+    const derived = deriveMenus(machineConfig, defs, def.actors ?? {});
+    const machine = (inner.createMachine as unknown as (c: never) => AnyStateMachine)(derived.config as never);
 
     // Close the nested-`on` typo hole (ADR-0015): with the manifest dead, a typo'd key would
     // silently become vocabulary — so every non-dotted key the machine handles anywhere must map
@@ -177,6 +203,7 @@ export function jr2Setup<
     // targetless/actionless transitions — exactly where a typo'd key would hide). Dotted names
     // (`agent.*`, `workspace.*`, `xstate.*`, delayed transitions) are mechanically jr2's/xstate's;
     // `*` is the wildcard descriptor.
+    const handled = new Set<string>();
     const walk = (node: AnyStateMachine["root"]): void => {
       for (const descriptor of node.transitions.keys()) {
         if (descriptor === "*" || descriptor.includes(".")) continue;
@@ -186,12 +213,45 @@ export function jr2Setup<
               `declares (declared: ${[...defs.keys()].join(", ") || "none"}) — a typo, or a missing defineEvent`,
           );
         }
+        handled.add(descriptor);
       }
       for (const child of Object.values(node.states)) walk(child);
     };
     walk(machine.root);
 
+    // The other direction (ADR-0015): a def no state handles is in no derived set, so it is on no
+    // Menu and no Gate — a pick nothing can send and nothing would take.
+    const dead = [...defs.keys()].filter((name) => !handled.has(name));
+    if (dead.length) {
+      throw new Error(
+        `machine "${machine.id}" declares ${dead.map((name) => `"${name}"`).join(", ")}, which no state handles — ` +
+          `a pick no state takes is on no Menu and no Gate: handle it, or drop it from jr2Setup({ events })`,
+      );
+    }
+
+    // A Part written inline has no name (ADR-0049, ADR-0067): refused, with the slot form.
+    refuseInlineParts(machine);
+    refuseParallelBelowAgents(machine, def.actors ?? {});
+    refuseUnknownSentBy(machine);
+    // Before the Effect checks: they ask who may send a writing (`mayTake`), which reads its audience.
     attachVocabulary(machine, defs);
+    // The Effect checks (ADR-0067): a pick param nothing reads, a `fill` that overwrites one, a
+    // `fromPick` of another pick — refused; a mapper the probe cannot run — warned.
+    const effects = effectChecks(machine, def.actors ?? {}, defs);
+    if (effects.errors.length) throw new Error(`machine "${machine.id}": ${effects.errors.join("; ")}`);
+
+    const idOf = (path: readonly string[]): string => stateAt(machine, path).id;
+    attachSeats(
+      machine,
+      derived.seats.map(({ path, ...seat }) => ({ state: idOf(path), ...seat })),
+    );
+    attachLoadWarnings(machine, [
+      ...unenteredModes(machine, def.actors ?? {}),
+      ...restWarnings(machine, def.actors ?? {}),
+      ...effects.warnings,
+      ...derived.warnings.map((warning) => warning(idOf)),
+      ...partyWarnings(machine, derived.derivedGateIds),
+    ]);
     if (inputSchema) attachInputSchema(machine, inputSchema);
     return machine;
   };
@@ -204,7 +264,7 @@ export function jr2Setup<
     MergedActors<TActors>,
     {},
     TActions,
-    TGuards,
+    TGuards & SentByGuards,
     TDelay,
     TTag,
     TInput,
@@ -214,12 +274,17 @@ export function jr2Setup<
   >;
 }
 
-// --- Menu derivation (ADR-0015) ------------------------------------------------------------------
-// A state that invokes an AGENT SLOT gets, as its Agent's tool menu, the workflow events its
-// transitions handle — own + bubbled ancestors, per statechart semantics — filtered to audience
-// ∈ {agent, any}; a `gate` gets the same set filtered to {external, any}. The invoking actor
-// kind is the primary router; `audience` on the def exists to RESTRICT (tag the security-
-// sensitive events). Explicit `tools:`/`accepts:` on the invoke input remain as escape hatches.
+// --- Menu derivation (ADR-0015, ADR-0029) --------------------------------------------------------
+// A state that invokes an AGENT SLOT derives the workflow events the Turn may pick: its own
+// transitions, its ancestors' (bubbled, per statechart semantics), and those written on the states
+// below it — its MODES (`modePicks`) — filtered to the names that Agent may send (the audience
+// rule, on `deriveMenus`). That is its derived set, before its guards narrow it to the Allowed
+// picks; the Allowed picks are read off the live snapshot, so they follow the active mode. The
+// Agent's MENU — its tools block — is the union of those sets over every state that invokes it,
+// fixed for the conversation. A `gate` derives its own and its ancestors' transitions, and those
+// written on its plain children (the same descent, stopping at a child that invokes a party),
+// filtered to the names its caller may send. An explicit `accepts:` on a gate's input remains an
+// escape hatch.
 //
 // An agent invoke is identified by its LOGIC, not by a reserved src name: the walk looks the
 // invoke's `src` up in the setup's own `actors` map and asks `isAgent` (ADR-0049). That is also
@@ -240,18 +305,81 @@ type LooseState = {
 };
 type InputArgs = { context: unknown; event: unknown; self: AnyActorRef };
 
-/** Rewrite a machine config, wrapping every Agent-slot/`gate` invoke input (immutably). */
-function deriveMenus(config: unknown, defs: Map<string, EventDef>, actors: Record<string, UnknownActorLogic>): unknown {
-  const pick = (names: Set<string>, kind: "agent" | "external"): string[] =>
-    [...names].filter((name) => {
-      const d = defs.get(name);
-      return !!d && (d.audience === kind || d.audience === "any");
-    });
-
-  const walk = (node: LooseState, inherited: Set<string>, path: readonly string[]): LooseState => {
-    const names = new Set(inherited);
-    for (const key of Object.keys(node.on ?? {})) {
-      if (!key.includes(".") && key !== "*") names.add(key);
+/**
+ * One party's seat on one state: who may send what there (ADR-0015). `path` is the state's key
+ * path below the Machine's root; `names` is the derived set — for an Agent, what its Turn may pick
+ * before the guards narrow it; for a Gate, its accepted set unless its input names `accepts:`.
+ */
+export type Seat = { path: readonly string[]; party: "agent" | "gate"; agent?: string; names: string[] };
+
+/** Each name in reach, with the OWNER mark of every writing of it in reach (see below). */
+type Reach = Map<string, Set<string>>;
+/** Each name written on the path from the root: where, and the owner mark of each writing. */
+type Writings = Map<string, Array<{ path: readonly string[]; owner: string }>>;
+/** A load warning, rendered once the built Machine can turn a key path into a state id. */
+type Warning = (idOf: (path: readonly string[]) => string) => string;
+
+/** The owner mark of a writing no party answers for — at or above it, no state invokes an Agent
+ * slot or a `gate` — so both kinds may send it. */
+const NOBODY = "";
+/** The owner mark of the state at `path`: the party it invokes answers for the writings below it.
+ * `#` keeps the root's mark apart from {@link NOBODY}. */
+const ownerMark = (path: readonly string[]): string => `#${path.join(".")}`;
+
+/** Rewrite a machine config, wrapping every Agent-slot/`gate` invoke input (immutably).
+ *
+ * The same walk derives each Agent name's MENU (ADR-0029): the union of the derived sets of every
+ * state that invokes an Agent of that name in this Machine — the scope of its continued
+ * conversation's id (ADR-0057) — sorted, so it is byte-stable for every Turn of the conversation
+ * and for every fresh one. The wrapped inputs read it at invoke time, when the walk is long done.
+ *
+ * WHO may send a name (the audience rule, ADR-0015). A writing — an `on` key on a state —
+ * belongs to the party that its state, or the nearest state above it, invokes: an Agent slot, a
+ * `gate`, or both when one state invokes both. With no such state above, it belongs to both. An
+ * event whose def leaves `audience` unset follows that rule; an explicit `audience` overrides it
+ * BY KIND over the whole reach (`agent`: every Agent whose reach holds a writing of it; `external`:
+ * every Gate's; `any`: both). The REACH never changes — own + ancestors, plus the states below
+ * with no party-invoking state between (an Agent's modes, a Gate's plain children) — and the rule
+ * only filters inside it, so it cannot widen who may send a name. */
+function deriveMenus(
+  config: unknown,
+  defs: Map<string, EventDef>,
+  actors: Record<string, UnknownActorLogic>,
+): { config: unknown; seats: Seat[]; warnings: Warning[]; derivedGateIds: Set<string> } {
+  const pick = (reach: Reach, kind: "agent" | "external", self: string): string[] =>
+    [...reach]
+      .filter(([name, owners]) => {
+        const d = defs.get(name);
+        if (!d) return false;
+        if (d.audience !== undefined) return d.audience === kind || d.audience === "any";
+        return owners.has(self) || owners.has(NOBODY);
+      })
+      .map(([name]) => name);
+  const menus = new Map<string, Set<string>>();
+  const menuOf = (agentName: string): string[] => [...(menus.get(agentName) ?? [])].sort();
+  const seats: Seat[] = [];
+  // The load warnings this walk can see (ADR-0015), each rendered once the states have ids. Keyed,
+  // so a writing seen from two paths is one warning.
+  const warnings = new Map<string, Warning>();
+  // Which parties each owner mark's state invokes — what the Gate-above warning reads.
+  const parties = new Map<string, { agents: string[]; gate: boolean }>();
+  // The Gate invoke ids this walk names: a party warning says how to name one instead.
+  const derivedGateIds = new Set<string>();
+
+  const walk = (
+    node: LooseState,
+    inherited: Reach,
+    writtenAbove: Writings,
+    path: readonly string[],
+    ownerAbove: string,
+  ): LooseState => {
+    const owner = invokesParty(node, actors) ? ownerMark(path) : ownerAbove;
+    if (owner !== ownerAbove) parties.set(owner, partiesOf(node, actors));
+    const names: Reach = new Map([...inherited].map(([name, owners]) => [name, new Set(owners)]));
+    const written: Writings = new Map([...writtenAbove].map(([name, at]) => [name, [...at]]));
+    for (const name of ownPicks(node)) {
+      names.set(name, (names.get(name) ?? new Set<string>()).add(owner));
+      written.set(name, [...(written.get(name) ?? []), { path, owner }]);
     }
 
     let out = node;
@@ -264,17 +392,49 @@ function deriveMenus(config: unknown, defs: Map<string, EventDef>, actors: Recor
       const wrapOne = (inv: LooseInvoke): LooseInvoke => {
         // The slot key IS the Agent name (ADR-0049) — read off the declaration, never authored.
         if (typeof inv?.src === "string" && isAgent(actors[inv.src])) {
-          const derived = pick(names, "agent");
-          if (derived.length === 0) refuseBuriedPicks(node, inv.src, path, pick);
-          return { ...inv, input: wrapAgentInput(inv.input, derived, inv.src) };
+          // A mode's writings are this state's by construction: the descent stops at any child
+          // that invokes a party, so none answers between them and this one.
+          const reach: Reach = new Map([...names].map(([name, owners]) => [name, new Set(owners)]));
+          for (const name of modePicks(node, actors))
+            reach.set(name, (reach.get(name) ?? new Set<string>()).add(owner));
+          const derived = pick(reach, "agent", owner);
+          // A Gate above that takes a writing from this Agent: the Gate's caller owns it, so the
+          // Agent below — which reaches it — cannot send it. Legal, and the one narrowing of the
+          // audience rule an author may not expect.
+          const agent = inv.src;
+          for (const [name, owners] of reach) {
+            if (derived.includes(name) || defs.get(name)?.audience !== undefined) continue;
+            for (const at of written.get(name) ?? []) {
+              if (!owners.has(at.owner) || at.owner === owner || !parties.get(at.owner)?.gate) continue;
+              warnings.set(
+                `gate:${agent}:${path.join(".")}:${name}:${at.path.join(".")}`,
+                (idOf) =>
+                  `Agent "${agent}" on "${idOf(path)}" cannot send "${name}": it is written on "${idOf(at.path)}", ` +
+                  `whose Gate's caller owns it — give the def \`audience: "any"\` for both to send it`,
+              );
+            }
+          }
+          const menu = menus.get(inv.src) ?? new Set<string>();
+          for (const name of derived) menu.add(name);
+          menus.set(inv.src, menu);
+          seats.push({ path, party: "agent", agent: inv.src, names: [...derived].sort() });
+          return { ...inv, input: wrapAgentInput(inv.input, derived, inv.src, menuOf) };
         }
         if (inv?.src === "gate") {
-          const wrapped: LooseInvoke = { ...inv, input: wrapGateInput(inv.input, pick(names, "external")) };
+          // A Gate's plain children — below it, with no party-invoking state between — are its own
+          // by position, as an Agent's modes are its (ADR-0015).
+          const reach: Reach = new Map([...names].map(([name, owners]) => [name, new Set(owners)]));
+          for (const name of modePicks(node, actors))
+            reach.set(name, (reach.get(name) ?? new Set<string>()).add(owner));
+          const accepts = pick(reach, "external", owner);
+          seats.push({ path, party: "gate", names: [...accepts].sort() });
+          const wrapped: LooseInvoke = { ...inv, input: wrapGateInput(inv.input, accepts) };
           // A machine-root gate (empty path) is left to xstate's default id: a `""` id would be
           // worse than a noisy one, and the derived gate id still works.
           if (inv.id == null && path.length) {
             const key = path.join(".");
             wrapped.id = unnamedGates > 1 ? `${key}.${ordinal++}` : key;
+            derivedGateIds.add(wrapped.id as string);
           }
           return wrapped;
         }
@@ -284,53 +444,409 @@ function deriveMenus(config: unknown, defs: Map<string, EventDef>, actors: Recor
     }
     if (node.states) {
       const states: Record<string, LooseState> = {};
-      for (const [key, child] of Object.entries(node.states)) states[key] = walk(child, names, [...path, key]);
+      for (const [key, child] of Object.entries(node.states))
+        states[key] = walk(child, names, written, [...path, key], owner);
       out = { ...(out === node ? node : out), states };
     }
     return out;
   };
 
-  return walk(config as LooseState, new Set(), []);
+  const out = walk(config as LooseState, new Map(), new Map(), [], NOBODY);
+  return { config: out, seats, warnings: [...warnings.values()], derivedGateIds };
 }
 
 /**
- * Refuse the one shape that LOOKS like a Menu and is not one (ADR-0015, ADR-0057): an Agent
- * invoked on a state whose picks are written in its SUBSTATES.
+ * A mode that nothing enters (ADR-0015): a state below an Agent's state with no invoke that the
+ * Machine can never enter. Its picks are on the Menu and never allowed. A warning, not a refusal: the
+ * Machine is legal, and a mode left unwired is often work in progress. A state below an Agent's state
+ * that INVOKES something and that nothing enters is refused (ADR-0067): what it invokes never runs,
+ * which is never work in progress. Both look below a state that invokes an Effect or a child Machine;
+ * neither looks below one that invokes another Agent or a Gate.
  *
- * A Menu derives from the invoking state's own + ANCESTOR transitions, per statechart semantics,
- * so a pick written below that state is one the Turn is never offered — the model is handed a
- * Menu it cannot end its turn with, and the actor reads an empty Menu as a Turn that ended as
- * intended, so nothing nudges and nothing faults: the run parks. Until ADR-0057 the `tools:`
- * override papered over it; with the override gone the kit says it here, at build, where `jr2 up`
- * walks every registered Machine.
+ * "Can enter" is reachability from the root, to a fixed point. A state is entered when its parent is
+ * entered and it is the parent's initial state or a region of a parallel parent, or when a transition
+ * whose SOURCE can be entered targets it or a state inside it (entering a state enters its
+ * ancestors). So a compound mode's own `initial` does not enter it, and neither does a transition
+ * written on the mode into itself: neither runs unless the mode is already active.
  *
- * An EMPTY Menu is not itself wrong — a state moved by a Gate or a timer asks its Agent for text
- * and nothing else — so only the contradiction is refused: no Menu here, and picks below.
+ * A transition into a history state enters what that history state restores. The walk follows its
+ * DEFAULT target — shallow or deep, what xstate enters when nothing is recorded yet — or, with none
+ * written, its parent's initial state, which entering the parent already covers. A recorded history
+ * restores only states that were entered another way. A default target the walk cannot resolve is a
+ * warning of its own: the modes behind it may read as unentered when they are not, and a state that
+ * invokes below that history state's parent is warned about, never refused — the walk refuses only
+ * what it knows nothing enters. A history state is no mode.
  */
-function refuseBuriedPicks(
-  node: LooseState,
-  agentName: string,
-  path: readonly string[],
-  pick: (names: Set<string>, kind: "agent" | "external") => string[],
+function unenteredModes(machine: AnyStateMachine, actors: Record<string, UnknownActorLogic>): string[] {
+  type Node = AnyStateMachine["root"];
+  const all: Node[] = [];
+  const collect = (node: Node): void => {
+    all.push(node);
+    for (const child of Object.values(node.states)) collect(child);
+  };
+  collect(machine.root);
+
+  const out: string[] = [];
+  const entered = new Set<Node>([machine.root]);
+  const enter = (node: Node): boolean => {
+    let added = false;
+    for (let n: Node | undefined = node; n !== undefined && !entered.has(n); n = n.parent) {
+      entered.add(n);
+      added = true;
+    }
+    if (node.type === "history") for (const target of historyDefault(node)) added = enter(target) || added;
+    return added;
+  };
+  /** A history state's default target, resolved the way xstate resolves it: a path from its parent,
+   * or a `#id`. Unresolvable: warned once, and nothing is followed. */
+  const unresolved = new Set<Node>();
+  const historyDefault = (node: Node): Node[] => {
+    const written = (node.config as { target?: unknown }).target;
+    if (written === undefined) return [];
+    const targets = (Array.isArray(written) ? written : [written]) as unknown[];
+    const resolved: Node[] = [];
+    for (const target of targets) {
+      const found = typeof target === "string" ? resolvePath(node.parent!, target) : undefined;
+      if (found !== undefined) {
+        resolved.push(found);
+        continue;
+      }
+      if (unresolved.has(node)) continue;
+      unresolved.add(node);
+      out.push(
+        `history state "${node.id}" has a default target the load walk cannot follow (${JSON.stringify(target)}) — ` +
+          `a mode entered only through it is reported as unentered, and a state that invokes is warned, not refused`,
+      );
+    }
+    return resolved;
+  };
+  const resolvePath = (parent: Node, target: string): Node | undefined => {
+    if (target.startsWith("#")) {
+      try {
+        return machine.getStateNodeById(target.slice(1)) as Node;
+      } catch {
+        return undefined;
+      }
+    }
+    let at: Node | undefined = parent;
+    for (const key of target.split(".")) at = at?.states[key];
+    return at;
+  };
+  for (let changed = true; changed; ) {
+    changed = false;
+    for (const node of all) {
+      const parent = node.parent;
+      if (parent === undefined || entered.has(node) || !entered.has(parent)) continue;
+      if (parent.type === "parallel" || (parent.type === "compound" && parent.initial.target.includes(node)))
+        changed = enter(node) || changed;
+    }
+    for (const node of all) {
+      if (!entered.has(node)) continue;
+      const transitions = [...node.transitions.values()].flat().concat(node.always ?? []);
+      for (const t of transitions) for (const target of t.target ?? []) changed = enter(target) || changed;
+    }
+  }
+  const invokedAgent = (node: Node): string | undefined =>
+    node.invoke.find((inv) => typeof inv.src === "string" && isAgent(actors[inv.src]))?.src as string | undefined;
+  const isBelow = (node: Node, ancestor: Node): boolean => {
+    for (let n = node.parent; n !== undefined; n = n.parent) if (n === ancestor) return true;
+    return false;
+  };
+
+  const refused: string[] = [];
+  for (const node of all) {
+    const agent = invokedAgent(node);
+    // An Agent's state the Machine never enters is a larger defect than its modes, and not this check.
+    if (agent === undefined || !entered.has(node)) continue;
+    // Every state below the Agent's state belongs to its Turn, down to a child that invokes another
+    // party (an Agent or a Gate): that child is checked, and below it is that party's. A state below
+    // an unentered one is not reported again.
+    const descend = (parent: Node): void => {
+      for (const child of Object.values(parent.states)) {
+        if (child.type === "history") continue;
+        if (child.invoke.length > 0) {
+          // A child that invokes something and that nothing enters (ADR-0067): what it invokes never
+          // runs — a refusal, where a mode nothing enters is only a warning.
+          if (!entered.has(child)) {
+            const what = child.invoke.map((inv) => (typeof inv.src === "string" ? inv.src : inv.id)).join(", ");
+            // Where a history default the walk cannot follow may enter it, the walk does not know: a
+            // warning, never a refusal of a Machine that may be legal.
+            const unsure = [...unresolved].find((h) => isBelow(child, h.parent!));
+            if (unsure !== undefined) {
+              out.push(
+                `state "${child.id}" below Agent "${agent}"'s state "${node.id}" may be entered by nothing, so what ` +
+                  `it invokes (${what}) may never run — the walk cannot follow history state "${unsure.id}"'s ` +
+                  `default target, which may enter it`,
+              );
+            } else {
+              refused.push(
+                `state "${child.id}" below Agent "${agent}"'s state "${node.id}" is entered by nothing, so what it ` +
+                  `invokes (${what}) never runs — target it from a pick or a route, or delete it`,
+              );
+            }
+            continue;
+          }
+          const party = child.invoke.some(
+            (inv) => inv.src === "gate" || (typeof inv.src === "string" && isAgent(actors[inv.src])),
+          );
+          if (!party) descend(child);
+          continue;
+        }
+        if (!entered.has(child)) {
+          const picks = [...child.transitions.keys()].filter((key) => !key.includes(".") && key !== "*");
+          out.push(
+            `mode "${child.id}" of Agent "${agent}"'s state "${node.id}" — nothing enters it: it is not ` +
+              `initial and no state the Machine can enter has a transition into it, so its picks` +
+              `${picks.length ? ` (${picks.join(", ")})` : ""} are on the Menu and never allowed`,
+          );
+          continue;
+        }
+        descend(child);
+      }
+    };
+    descend(node);
+  }
+  if (refused.length) throw new Error(`machine "${machine.id}": ${refused.join("; ")}`);
+  return out;
+}
+
+/**
+ * Does this logic settle on its own — a promise, the one plain xstate actor that ends without being
+ * stopped? Asked of its own transition: a promise logic's initial snapshot, sent xstate's resolve
+ * event, is `done`. That event name is an xstate internal (5.32.2); a bump that renamed it would
+ * make every promise read long-lived, and setup.test.ts pins it against the real constructors.
+ */
+function settlesOnItsOwn(logic: unknown): boolean {
+  const l = logic as {
+    getInitialSnapshot?: (scope: unknown, input: unknown) => unknown;
+    transition?: (snapshot: unknown, event: unknown, scope: unknown) => { status?: string } | undefined;
+  };
+  if (typeof l?.getInitialSnapshot !== "function" || typeof l.transition !== "function") return false;
+  try {
+    const scope = { self: {}, defer: () => {}, emit: () => {} };
+    const snapshot = l.getInitialSnapshot(scope, undefined);
+    return l.transition(snapshot, { type: "xstate.promise.resolve", data: undefined }, scope)?.status === "done";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The load walk's Rest warnings (ADR-0024): shapes below an Agent's state that keep it from Rest, so
+ * every pick of the Agent is refused for longer than the author likely meant. Warnings, never
+ * refusals: each can be intended.
+ *
+ * - **A Gate whose answer has no target.** The Gate stays open after its answer, and the Agent's
+ *   state is not at Rest again until the Gate's state exits.
+ * - **A long-lived invoke** — an actor that runs until its state exits: not a promise or an Effect (each settles),
+ *   a Gate, an Agent or a child Machine. While it runs, the Agent's state is never at Rest.
+ *
+ * The descent below an Agent's state stops at a child that invokes another Agent: below it is that
+ * Agent's state, read for that Agent.
+ */
+function restWarnings(machine: AnyStateMachine, actors: Record<string, UnknownActorLogic>): string[] {
+  type Node = AnyStateMachine["root"];
+  const implementations = machine.implementations.actors as Record<string, unknown>;
+  const logicOf = (src: unknown): unknown => (typeof src === "string" ? (actors[src] ?? implementations[src]) : src);
+  const agentOf = (node: Node): string | undefined =>
+    node.invoke.find((inv) => typeof inv.src === "string" && isAgent(actors[inv.src]))?.src as string | undefined;
+  const out: string[] = [];
+  const visit = (node: Node): void => {
+    const agent = agentOf(node);
+    if (agent !== undefined) {
+      const descend = (parent: Node): void => {
+        for (const child of Object.values(parent.states)) {
+          if (agentOf(child) !== undefined) continue;
+          for (const inv of child.invoke) {
+            const logic = logicOf(inv.src);
+            const name = typeof inv.src === "string" ? inv.src : inv.id;
+            if (inv.src === "gate") {
+              for (const [event, candidates] of child.transitions) {
+                if (event.includes(".") || event === "*") continue;
+                if (candidates.some((t) => (t.target ?? []).length > 0)) continue;
+                out.push(
+                  `Gate "${inv.id}" at "${child.id}", below Agent "${agent}"'s state "${node.id}": its answer "${event}" ` +
+                    `has no target, so the Gate stays open after it — the Agent's state is not at rest again until ` +
+                    `"${child.id}" exits, and every pick of the Agent is refused until then; give the answer a target`,
+                );
+              }
+              continue;
+            }
+            // An Open body (ADR-0070) runs a Chart, as a child Machine runs its states.
+            if (
+              isAgent(logic) ||
+              isEffect(logic) ||
+              isOpenBody(logic) ||
+              (logic as { root?: unknown } | undefined)?.root !== undefined
+            )
+              continue;
+            if (settlesOnItsOwn(logic)) continue;
+            out.push(
+              `"${child.id}", below Agent "${agent}"'s state "${node.id}", invokes "${name}", which runs until its ` +
+                `state exits (not a promise, an Effect, a Gate, an Agent or a child Machine): while it runs the Agent's state ` +
+                `is never at rest, so it blocks every pick of the Agent — invoke it above the Agent's state`,
+            );
+          }
+          descend(child);
+        }
+      };
+      descend(node);
+    }
+    for (const child of Object.values(node.states)) visit(child);
+  };
+  visit(machine.root);
+  return out;
+}
+
+/**
+ * Resolve and stamp every Open body slot's lent set (ADR-0070). Each name an Open body lends must be
+ * a part of this setup, of the kind it is lent as: an `agents` entry an Agent slot (an Open one too:
+ * its composer binds it as today), an `effects` entry an Effect, a `machines` entry a Machine, and a
+ * guard, action or delay one this setup implements. An unknown name refuses the createMachine naming
+ * it, so an Open body whose names did not resolve never reaches the walk.
+ */
+function stampOpenBodies(
+  machineId: string,
+  def: {
+    actors?: Record<string, unknown>;
+    guards?: Record<string, unknown>;
+    actions?: Record<string, unknown>;
+    delays?: Record<string, unknown>;
+  },
 ): void {
-  const below = new Set<string>();
-  const descend = (n: LooseState): void => {
-    for (const key of Object.keys(n.on ?? {})) if (!key.includes(".") && key !== "*") below.add(key);
-    for (const child of Object.values(n.states ?? {})) descend(child);
+  const actors = def.actors ?? {};
+  for (const [slot, logic] of Object.entries(actors)) {
+    if (!isOpenBody(logic)) continue;
+    const decl = openBodyDeclarationOf(logic);
+    const faults: string[] = [];
+    const lent: LentParts = { actors: {}, guards: {}, actions: {}, delays: {} };
+    const actorKinds = [
+      ["agents", "an Agent slot (agent(...))", isAgent],
+      ["effects", "an Effect slot", isEffect],
+      ["machines", "a Machine", (l: unknown) => (l as { root?: unknown } | undefined)?.root !== undefined],
+    ] as const;
+    for (const [kind, what, test] of actorKinds) {
+      for (const name of decl.lends[kind] ?? []) {
+        const found = actors[name];
+        if (name === slot) faults.push(`lends.${kind}: "${name}" is the Open body itself`);
+        else if (found === undefined) {
+          faults.push(
+            `lends.${kind}: "${name}" is no actor slot of this Machine; its actors: ${Object.keys(actors).join(", ")}`,
+          );
+        } else if (!test(found)) faults.push(`lends.${kind}: "${name}" is not ${what}`);
+        else lent.actors[name] = found as UnknownActorLogic;
+      }
+    }
+    const implKinds = [
+      ["guards", def.guards ?? {}, lent.guards],
+      ["actions", def.actions ?? {}, lent.actions],
+      ["delays", def.delays ?? {}, lent.delays],
+    ] as const;
+    for (const [kind, impl, into] of implKinds) {
+      for (const name of decl.lends[kind] ?? []) {
+        if (impl[name] === undefined) {
+          faults.push(
+            `lends.${kind}: "${name}" is no ${kind.slice(0, -1)} of this Machine; its ${kind}: ${Object.keys(impl).join(", ") || "none"}`,
+          );
+        } else (into as Record<string, unknown>)[name] = impl[name];
+      }
+    }
+    if (faults.length) throw new Error(`machine "${machineId}": Open body "${slot}": ${faults.join("; ")}`);
+    attachLent(logic, lent);
+  }
+}
+
+/**
+ * A parallel region below a state that invokes an Agent is refused (ADR-0015). The shape is
+ * reserved for picks the Agent does not wait for, which jr2 does not build; a Turn takes one pick
+ * at a time. The Agent's state itself being parallel counts: its regions are below it. A
+ * Background work goes above the Agent's state.
+ */
+function refuseParallelBelowAgents(machine: AnyStateMachine, actors: Record<string, UnknownActorLogic>): void {
+  type Node = AnyStateMachine["root"];
+  const firstParallel = (node: Node): Node | undefined => {
+    if (node.type === "parallel") return node;
+    for (const child of Object.values(node.states)) {
+      const found = firstParallel(child);
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  };
+  const visit = (node: Node): void => {
+    const agent = node.invoke.find((inv) => typeof inv.src === "string" && isAgent(actors[inv.src]))?.src;
+    const parallel = agent === undefined ? undefined : firstParallel(node);
+    if (parallel !== undefined) {
+      throw new Error(
+        `machine "${machine.id}": state "${parallel.id}" is parallel, at or below Agent "${String(agent)}"'s state ` +
+          `"${node.id}" — a parallel region below an Agent's state is reserved for picks the Agent does not wait ` +
+          `for, which jr2 does not build; background work goes above the Agent's state`,
+      );
+    }
+    for (const child of Object.values(node.states)) visit(child);
   };
-  for (const child of Object.values(node.states ?? {})) descend(child);
+  visit(machine.root);
+}
 
-  const buried = pick(below, "agent");
-  if (buried.length === 0) return;
-  const state = path.length ? path.join(".") : "(the machine root)";
-  throw new Error(
-    `agent "${agentName}" is invoked on state "${state}", which derives an EMPTY Menu while the ` +
-      `states BELOW it handle ${buried.join(", ")} — a Menu is the invoking state's own plus its ` +
-      `ancestors' transitions (ADR-0015), so a pick written below is one the Turn can never be ` +
-      `offered, and a Turn with no Menu ends with no pick at all. Move it onto "${state}" (guard ` +
-      `it if it must not always be offered — ADR-0029), or, if this Turn is deliberately ` +
-      `menu-less, the pick belongs to another invoke.`,
-  );
+/** The built state node at a key path below the root — what turns a walk's path into a state id. */
+function stateAt(machine: AnyStateMachine, path: readonly string[]): AnyStateMachine["root"] {
+  let node = machine.root;
+  for (const key of path) node = node.states[key]!;
+  return node;
+}
+
+/** A state's own workflow-event keys: dotted names are jr2's or xstate's, `*` is the wildcard. */
+function ownPicks(node: LooseState): string[] {
+  return Object.keys(node.on ?? {}).filter((key) => !key.includes(".") && key !== "*");
+}
+
+/** The parties a state invokes: its Agent slots by name, and whether it invokes a `gate`. */
+function partiesOf(node: LooseState, actors: Record<string, UnknownActorLogic>): { agents: string[]; gate: boolean } {
+  const invokes = node.invoke ? (Array.isArray(node.invoke) ? node.invoke : [node.invoke]) : [];
+  return {
+    agents: invokes.flatMap((inv) => (typeof inv?.src === "string" && isAgent(actors[inv.src]) ? [inv.src] : [])),
+    gate: invokes.some((inv) => inv?.src === "gate"),
+  };
+}
+
+/** Does this state invoke a party that sends this Machine's workflow events — an Agent slot or a
+ * `gate`? An Effect, a child Machine, a `workspace()`/`pool()` body: none of them sends them. */
+function invokesParty(node: LooseState, actors: Record<string, UnknownActorLogic>): boolean {
+  const { agents, gate } = partiesOf(node, actors);
+  return gate || agents.length > 0;
+}
+
+/**
+ * The picks written on the states BELOW an Agent's state — its modes (ADR-0015). xstate hands an
+ * event to the deepest active state that handles it, and a false guard there falls through to the
+ * parent, so a child's `on` keys are picks the Turn can be allowed while that child is active — and
+ * `can()` on the live snapshot already answers for the active child (ADR-0029).
+ *
+ * The descent STOPS at a child that invokes another party — an Agent slot (a nested Turn: its picks
+ * are its own) or a `gate` (its `on` keys are the Gate's accepted set) — and leaves out everything
+ * below it. A child that runs an Effect, a child Machine or a timer is no stop: its `on` keys are
+ * this Turn's.
+ */
+function modePicks(node: LooseState, actors: Record<string, UnknownActorLogic>): Set<string> {
+  return new Set(modeWritings(node, [], actors).map((w) => w.name));
+}
+
+/** Each writing {@link modePicks} reads, with the key path of the mode it is written on. */
+function modeWritings(
+  node: LooseState,
+  path: readonly string[],
+  actors: Record<string, UnknownActorLogic>,
+): Array<{ name: string; path: readonly string[] }> {
+  const out: Array<{ name: string; path: readonly string[] }> = [];
+  const descend = (n: LooseState, at: readonly string[]): void => {
+    for (const [key, child] of Object.entries(n.states ?? {})) {
+      if (invokesParty(child, actors)) continue;
+      const childPath = [...at, key];
+      for (const name of ownPicks(child)) out.push({ name, path: childPath });
+      descend(child, childPath);
+    }
+  };
+  descend(node, path);
+  return out;
 }
 
 const resolveInput = (orig: unknown, args: InputArgs): Record<string, unknown> =>
@@ -367,9 +883,9 @@ function refuseUnknownKeys(consumer: object, agentName: string): void {
   );
 }
 
-/** Wrap an Agent slot's invoke input: name the Agent (the slot key), append the derived menu, and
- * finalize the mechanism fields. */
-function wrapAgentInput(orig: unknown, derived: string[], agentName: string) {
+/** Wrap an Agent slot's invoke input: name the Agent (the slot key), append the state's derived set
+ * and the Agent's Menu, and finalize the mechanism fields. */
+function wrapAgentInput(orig: unknown, derived: string[], agentName: string, menuOf: (agentName: string) => string[]) {
   return (args: InputArgs): AgentRunInput => {
     const consumer = resolveInput(orig, args) as Partial<AgentTurnInput & AgentRunInput>;
     refuseUnknownKeys(consumer, agentName);
@@ -391,8 +907,11 @@ function wrapAgentInput(orig: unknown, derived: string[], agentName: string) {
       // ADR-0035's reroll gate: closed to `continue: true`, which names an EXISTING conversation
       // while the runaway's one recovery is a fresh one — exactly what it opted out of.
       ...(consumer.continue === true ? { continuation: true } : {}),
-      // The Menu (ADR-0015): always the derived one, since ADR-0057 retired the override.
+      // The state's derived set (ADR-0015): always the derived one, since ADR-0057 retired the
+      // override. What delivery validates against, and what the Allowed picks narrow.
       tools: derived,
+      // The Menu (ADR-0029): every pick any state invoking this Agent derives — the tools block.
+      menu: menuOf(agentName),
     };
   };
 }