@jr2/orchestrator 0.3.0 → 0.5.1

package/src/setup.ts

@@ -42,22 +42,69 @@ 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 { refuseLostOutput } from "./run-output.ts";
+import { refuseUnroutedAgentFault } from "./mechanism-routes.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.
+ * The marker that `compileChart` puts on the config of a Chart's Machine (ADR-0070). In a Chart the
+ * `agent.fault` route is optional: the Open body sends an `agent.fault` that no transition takes to
+ * the Machine that invoked it, so `createMachine` does not refuse a Chart state with no route. Not on the Authoring
+ * surface (index.ts). The load walk (`partsOf`) refuses an author's Machine with no route, with or
+ * without the marker (ADR-0074).
  */
-export type MechanismEvent = FaultTelemetry | { type: "workspace.lost" };
+export const COMPILED_CHART: unique symbol = Symbol("jr2.compiledChart");
 
-/** 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;
+// 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.
+/** The events that jr2 itself sends into each Machine that `jr2Setup` makes. A Mechanism event's
+ * name has a dot, and a workflow event's name cannot, so the two never collide. */
+export type MechanismEvent = FaultTelemetry | WorkspaceLost;
+
+// A Workspace's Continuity broke (ADR-0021): its Sandbox is gone, or Lost. `reason` and `message`
+// are for a body whose policy tells the causes apart, or only reports them; no policy needs them.
+/**
+ * jr2 sends `workspace.lost` to the body of a `workspace()` when its Sandbox is gone: its pod was
+ * evicted or deleted, or its node went. jr2 does not make the Sandbox again, and the commits that
+ * were not pushed go with it. The body decides what to do next: route the event with
+ * `on: { "workspace.lost": … }`, usually once, on the body's root. `workspace()` refuses a body
+ * with a state that is not final and has no route for it on itself or on a state above. When the
+ * event comes and no transition takes it (the route's guard is false), the run ends `error`, with
+ * the event, the state and the reason in its fault.
+ */
+export type WorkspaceLost = {
+  type: "workspace.lost";
+  /** Why the Sandbox is gone, for a person or a log: the pod's reason (`Evicted`, `NodeShutdown`),
+   * the operator's (`PodDeleted`, `NodeLost`), or `Deleted`. A body can act without it. */
+  reason?: string;
+  /** More text about the loss, when jr2 has it. */
+  message?: string;
+};
+
+// The defs' derived types plus the mechanism's (ADR-0015).
+/** The type of `event` in a Machine that `jr2Setup` makes: each workflow event in its `events`,
+ * and each Mechanism event. A workflow event that an Agent or a Gate sent has `event.sender`. An
+ * event that the Machine sent to itself (`raise`, `sendTo`) has no `sender`. */
+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.
+ *
+ * @internal
+ */
+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
@@ -65,25 +112,154 @@ export type WorkflowEvent<TDefs extends readonly EventDef[]> = EventFrom<TDefs[n
 const jr2Actors = { gate };
 type JR2Actors = typeof jr2Actors;
 
-/** Consumer actors merge OVER the pre-registered set: same name → the consumer's logic wins. */
+/**
+ * Consumer actors merge OVER the pre-registered set: same name → the consumer's logic wins.
+ *
+ * @internal
+ */
 type MergedActors<TActors extends Record<string, UnknownActorLogic>> = Omit<JR2Actors, keyof TActors> & TActors;
 
 // Local equivalents of xstate's non-exported setup() mapped helpers (setup.d.ts) — same shapes,
 // so the declared signature below composes with the public `ActionFunction`/`GuardPredicate`.
+/** @internal */
 type ToParameterizedObject<T extends Record<string, ParameterizedObject["params"] | undefined>> = {
   [K in keyof T & string]: { type: K; params: T[K] };
 }[keyof T & string];
+/** @internal */
 type ToProvidedActor<TActors extends Record<string, UnknownActorLogic>> = {
   [K in keyof TActors & string]: { src: K; logic: TActors[K]; id: string | undefined };
 }[keyof TActors & string];
 
 /**
- * Author a workflow machine (ADR-0015). Like `setup()`, but `types.events` is gone: the event
- * union derives from `events` (defineEvent defs, taken as values) plus the mechanism events.
+ * Set up a Machine that takes workflow events: the jr2 form of xstate's `setup()`. Write a Machine
+ * with it when an Agent or a Gate sends events into the Machine, or when the Machine declares a
+ * door. Call `.createMachine(config)` on the result, as with `setup()`. The Machine you get is a
+ * plain xstate Machine.
+ *
+ * What it adds to `setup()`:
+ * - `events` replaces `types.events`. The event type of the Machine comes from the
+ *   `defineEvent` events you list, plus the events jr2 itself sends (`agent.fault`,
+ *   `workspace.lost`). An event that a party sent has `event.sender`. A Machine that takes no
+ *   workflow event leaves out `events`.
+ * - The `gate` actor is ready to invoke by name: `invoke: { src: "gate" }`.
+ * - Each Agent slot (`actors: { coder: agent(…) }`) gets its Menu from the states that invoke it.
+ * - The `sentBy(id)` guard is ready to use.
+ * - `createMachine` also takes `input`: a zod object for the input that starts a run. jr2 checks
+ *   each start against it. Without it, a run can start with any input. The `setup()` of xstate
+ *   does not read this `input`, so a Machine with a door uses `jr2Setup`, also when it takes no
+ *   workflow event. `jr2 up` and the publish door refuse a registered Machine that has a zod
+ *   `input` if `jr2Setup` did not make the Machine: ``workflow "<name>": machine "<id>" has a zod `input` on
+ *   createMachine, but jr2Setup did not make this Machine, so no door reads that input …``
+ *
+ * The output of a run is the root `output` of `createMachine`, beside `id` and `states`, as in
+ * xstate v5. xstate does not read the `output` of a final state as the output of the Machine. It
+ * gives that output to the root `output` as `event.output`. Write
+ * `output: ({ event }) => event.output as Output` at the root, or make the output from `context`
+ * there. `createMachine` refuses an `output` on a final state directly below the root when the root
+ * has no `output` (see the list below).
+ *
+ * `createMachine` refuses a Machine that it cannot run as written. Among the refusals:
+ * - an `on` key that no listed event has: ``machine "<id>" handles event "<key>", which no def in
+ *   jr2Setup({ events }) declares (declared: <names>) — a typo, or a missing defineEvent``
+ * - a listed event that no state takes: ``machine "<id>" declares "<name>", which no state handles
+ *   — a pick no state takes is on no Menu and no Gate: handle it, or drop it from
+ *   jr2Setup({ events })``
+ * - an entry of `events` that `defineEvent` did not make, or one name listed twice:
+ *   ``machine "<id>": `events` entry is not a defineEvent() def: <entry>``,
+ *   ``machine "<id>": duplicate event "<name>" in `events` ``
+ * - an `agent()`, an Effect or a `workspace()` written on `invoke.src` instead of under `actors`:
+ *   ``machine "<id>": state "<state>" invokes <part> inline — a Part is a key of actors, so it has
+ *   a name that the ledger, the report and customize() share: actors: { <name>: <factory>(...) },
+ *   then invoke: { src: "<name>" }``. `<part>` is `an Agent`, `an Effect` or `a Workspace`.
+ *   `<factory>` is `agent`, the Effect's kind (such as `command`), or `workspace`.
+ * - an `output` on a final state directly below the root, when the root has no `output`:
+ *   ``machine "<id>": final state "<state>" declares an output, and the root has no output — xstate
+ *   v5 gives a run only its root output, so this output reaches nothing and the run ends with none:
+ *   write it at the root, as output: ({ context }) => ..., or keep it on the final state and pass it
+ *   on with output: ({ event }) => event.output at the root``. With more than one such final state,
+ *   it names each one and puts the words in the plural: ``final states "<state>", "<state>"
+ *   declare an output``, ``these outputs reach nothing``, ``write one at the root`` and ``keep
+ *   them on the final states and pass them on``. An `output` on a
+ *   final state inside a compound state is legal: the `onDone` of that compound state gets it as
+ *   `event.output`.
+ * - a parallel state at or below a state that invokes an Agent: ``machine "<id>": state "<state>"
+ *   is parallel, at or below Agent "<slot>"'s state "<state>" — 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``
+ * - a state below an Agent's state that invokes something and that nothing enters: ``machine
+ *   "<id>": state "<state>" below Agent "<slot>"'s state "<state>" is entered by nothing, so what
+ *   it invokes (<src>) never runs — target it from a pick or a route, or delete it``
+ * - a state that invokes an Agent when that state and each state above it have no `agent.fault`
+ *   route: ``machine "<id>": state "<state>" invokes an Agent, and no route for "agent.fault" is
+ *   on it or on a state above — jr2 sends agent.fault when the Agent's Turn cannot go on, and with
+ *   no route the run faults: route it on that state or on a state above it, as on: {
+ *   "agent.fault": "<the state that handles it>" } (ADR-0074)``. A state that invokes an Open body
+ *   that lends an Agent or allows a model gets the same line, with `invokes an Open body that can
+ *   run an Agent`: the body sends it a Chart's unrouted `agent.fault`. When both kinds have no route,
+ *   one line names both, joined by `, and`. One route on the root is a route for each state. A
+ *   Chart's Machine does not get this refusal: in a Chart the route is optional (ADR-0070).
+ *
+ * It also refuses a `sentBy` that names no party (see `sentBy`). It refuses a pick param that
+ * nothing reads, where the pick enters a state that invokes an Effect (see `fromPick`). Shapes that
+ * are legal but probably not what you mean, such as a mode that nothing enters, are warnings that
+ * `jr2 up` prints.
+ *
+ * @param def - What `setup()` takes, with `events` in place of `types.events`. A Machine that
+ *   needs none of it calls `jr2Setup()`.
+ * @returns What `setup()` returns. Call `.createMachine(config)` on it.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { agent, defineEvent, fail, jr2Setup } from "@jr2/orchestrator";
+ *
+ * const proposed = defineEvent({
+ *   name: "proposed",
+ *   description: "Call this with your plan.",
+ *   input: z.object({ plan: z.string() }),
+ * });
+ * const approve = defineEvent({ name: "approve", input: z.object({}) });
+ * const reject = defineEvent({ name: "reject", input: z.object({ reason: z.string() }) });
+ *
+ * export const machine = jr2Setup({
+ *   types: {} as { input: { goal: string }; context: { goal: string } },
+ *   events: [proposed, approve, reject],
+ *   actors: {
+ *     planner: agent({
+ *       model: "anthropic/claude-haiku-5-5",
+ *       instructions: "You plan small releases.",
+ *       workspace: "none",
+ *     }),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "plan",
+ *   input: z.object({ goal: z.string() }),
+ *   context: ({ input }) => ({ goal: input.goal }),
+ *   on: { "agent.fault": ".failed" },
+ *   initial: "planning",
+ *   states: {
+ *     planning: {
+ *       invoke: { src: "planner", input: ({ context }) => ({ prompt: `Plan this: ${context.goal}` }) },
+ *       on: { proposed: "review" },
+ *     },
+ *     review: {
+ *       invoke: { src: "gate" },
+ *       on: { approve: "approved", reject: "planning" },
+ *     },
+ *     approved: { type: "final" },
+ *     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+ *   },
+ * });
+ * ```
+ *
+ * @see docs/guides/write-a-workflow.md
+ * @see docs/concepts/machines-and-workflows.md
+ * @see docs/reference/decisions/0015-authoring-surface-absorbs-the-mechanism.md
  */
 export function jr2Setup<
   TContext extends MachineContext = MachineContext,
-  const TDefs extends readonly EventDef[] = readonly EventDef[],
+  const TDefs extends readonly EventDef[] = readonly [],
   TActors extends Record<string, UnknownActorLogic> = {},
   TActions extends Record<string, ParameterizedObject["params"] | undefined> = {},
   TGuards extends Record<string, ParameterizedObject["params"] | undefined> = {},
@@ -93,50 +269,62 @@ export function jr2Setup<
   TOutput extends NonReducibleUnknown = NonReducibleUnknown,
   TEmitted extends EventObject = EventObject,
   TMeta extends MetaObject = MetaObject,
->(def: {
-  /** context/input/output/tags/emitted/meta — never `events`; the union is derived. */
-  types?: {
-    context?: TContext;
-    input?: TInput;
-    output?: TOutput;
-    tags?: TTag;
-    emitted?: TEmitted;
-    meta?: TMeta;
-  };
-  /** This Machine's vocabulary, as values — the single source for types, validation, delivery. */
-  events: TDefs;
-  actors?: TActors;
-  actions?: {
-    [K in keyof TActions]: ActionFunction<
-      TContext,
-      WorkflowEvent<TDefs>,
-      WorkflowEvent<TDefs>,
-      TActions[K],
-      ToProvidedActor<MergedActors<TActors>>,
-      ToParameterizedObject<TActions>,
-      ToParameterizedObject<TGuards>,
-      TDelay,
-      TEmitted
-    >;
-  };
-  guards?: {
-    [K in keyof TGuards]: GuardPredicate<TContext, WorkflowEvent<TDefs>, TGuards[K], ToParameterizedObject<TGuards>>;
-  };
-  delays?: {
-    [K in TDelay]: DelayConfig<
-      TContext,
-      WorkflowEvent<TDefs>,
-      ToParameterizedObject<TActions>["params"],
-      WorkflowEvent<TDefs>
-    >;
-  };
-}): SetupReturn<
+>(
+  def: {
+    /** The types of the Machine, as in `setup()`: `context`, `input`, `output`, `tags`, `emitted`
+     * and `meta`. Not `events`: the event type comes from `events`. */
+    types?: {
+      context?: TContext;
+      input?: TInput;
+      output?: TOutput;
+      tags?: TTag;
+      emitted?: TEmitted;
+      meta?: TMeta;
+    };
+    // The single source for types, validation and delivery.
+    /** The workflow events this Machine takes: each one made by `defineEvent`. Leave it out when the
+     * Machine takes none. Each listed event must be the name of an `on` key. Each `on` key must be
+     * listed, if it is not a jr2 or xstate event (an event with a `.` in its name). */
+    events?: TDefs;
+    /** The actors the states invoke by name, as in `setup()`: Agent slots (`agent(…)`), Effects
+     * (`command(…)`, `http(…)`, `push(…)`), child Machines, `workspace(…)` and plain xstate logic.
+     * The key is the slot's name. An actor named `gate` replaces jr2's Gate. */
+    actors?: TActors;
+    /** Named actions, as in `setup()`. Their `event` has the type of this Machine's events. */
+    actions?: {
+      [K in keyof TActions]: ActionFunction<
+        TContext,
+        WorkflowEvent<TDefs>,
+        WorkflowEvent<TDefs>,
+        TActions[K],
+        ToProvidedActor<MergedActors<TActors>>,
+        ToParameterizedObject<TActions>,
+        ToParameterizedObject<TGuards>,
+        TDelay,
+        TEmitted
+      >;
+    };
+    /** Named guards, as in `setup()`. `sentBy` is there already; do not name a guard `jr2.sentBy`. */
+    guards?: {
+      [K in keyof TGuards]: GuardPredicate<TContext, WorkflowEvent<TDefs>, TGuards[K], ToParameterizedObject<TGuards>>;
+    };
+    /** Named delays, as in `setup()`. */
+    delays?: {
+      [K in TDelay]: DelayConfig<
+        TContext,
+        WorkflowEvent<TDefs>,
+        ToParameterizedObject<TActions>["params"],
+        WorkflowEvent<TDefs>
+      >;
+    };
+  } = {},
+): SetupReturn<
   TContext,
   WorkflowEvent<TDefs>,
   MergedActors<TActors>,
   {},
   TActions,
-  TGuards,
+  TGuards & SentByGuards,
   TDelay,
   TTag,
   TInput,
@@ -144,11 +332,14 @@ export function jr2Setup<
   TEmitted,
   TMeta
 > {
+  // Like `setup()`, but `types.events` is gone (ADR-0015): the event union derives from `events`
+  // (defineEvent defs, taken as values) plus the mechanism events.
   const inner = setup({
     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);
 
@@ -157,19 +348,28 @@ export function jr2Setup<
     // machine receives at creation — and is pulled OFF before xstate sees it: a zod schema is
     // not machine structure, and it must never reach the fingerprint/serialization paths that
     // read `machine.config`. It is attached beside the vocabulary below.
-    const { input: inputSchema, ...machineConfig } = config as { input?: z.ZodObject } & Record<string, unknown>;
+    // A compiled Chart (ADR-0070) is marked, and the marker is pulled off as `input` is.
+    const {
+      input: inputSchema,
+      [COMPILED_CHART]: compiledChart,
+      ...machineConfig
+    } = config as { input?: z.ZodObject; [COMPILED_CHART]?: true } & Record<string, unknown>;
 
     // Resolve the defs first (duplicates and reserved semantics fail HERE, naming the machine —
     // the same loud failure `eventMap` gave the manifest, moved to machine-build time)…
-    const defs = eventMap((machineConfig as { id?: string }).id ?? "(machine)", def.events);
+    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 +377,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 +387,51 @@ 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);
+    // A final state's output with no root output (ADR-0015): the run would end with none.
+    refuseLostOutput(machine);
+    // A state that invokes an Agent, or an Open body that can run one, with no `agent.fault` route
+    // (ADR-0074): the run would wait for ever. Not in a compiled Chart: there the route is optional,
+    // and the Open body sends the event that no transition takes to the Machine that invoked it (ADR-0070).
+    if (compiledChart !== true) refuseUnroutedAgentFault(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 +444,7 @@ export function jr2Setup<
     MergedActors<TActors>,
     {},
     TActions,
-    TGuards,
+    TGuards & SentByGuards,
     TDelay,
     TTag,
     TInput,
@@ -214,12 +454,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 +485,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 +572,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 +624,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;
   };
-  for (const child of Object.values(node.states ?? {})) descend(child);
+  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);
+  };
+  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 +1063,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);
@@ -378,6 +1074,9 @@ function wrapAgentInput(orig: unknown, derived: string[], agentName: string) {
       // jr2 mints every id (ADR-0016, ADR-0057): the Turn's input carries no id to honor, so
       // nothing a Machine writes can address a conversation jr2 did not derive.
       instanceId: mintIid(consumer, agentName, args.self),
+      // One per invocation (ADR-0016): two Turns that continue one conversation share the iid, the
+      // admission ledger's key, and a restore must not re-attach one Turn to the other's admission.
+      turnId: randomUUID(),
       endpoint: consumer.endpoint,
       sandbox: consumer.sandbox,
       prompt: consumer.prompt,
@@ -391,8 +1090,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),
     };
   };
 }