@jr2/orchestrator 0.5.1 → 0.7.0

package/src/setup.ts

@@ -29,6 +29,7 @@ import { randomUUID } from "node:crypto";
 import {
   setup,
   type ActionFunction,
+  type ActorLogic,
   type AnyActorRef,
   type AnyStateMachine,
   type DelayConfig,
@@ -39,6 +40,7 @@ import {
   type NonReducibleUnknown,
   type ParameterizedObject,
   type SetupReturn,
+  type Snapshot,
   type UnknownActorLogic,
 } from "xstate";
 import type { z } from "zod";
@@ -46,11 +48,13 @@ import { eventMap, type EventDef, type EventFrom, type Sender } from "@jr2/agent
 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 type { AnyFramePath, FramePath, WorktreePath, WorktreeReady } from "./worktree.ts";
+import { effectChecks, refuseUnroutedOutcome } from "./effect-checks.ts";
+import { isGateInvoke } from "./gate-brand.ts";
+import { isGateSlot, plainGate, settlesOnItsOwn, type PlainGate } 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 { partyWarnings, refuseSlotActiveTwice, 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";
@@ -109,7 +113,7 @@ 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
  * Machine declares, `actors: { coder: agent(def) }` (ADR-0049). */
-const jr2Actors = { gate };
+const jr2Actors: { gate: PlainGate } = { gate: plainGate };
 type JR2Actors = typeof jr2Actors;
 
 /**
@@ -130,6 +134,74 @@ type ToProvidedActor<TActors extends Record<string, UnknownActorLogic>> = {
   [K in keyof TActors & string]: { src: K; logic: TActors[K]; id: string | undefined };
 }[keyof TActors & string];
 
+// The types below carry the body's Repo Slots to every Worktree input.
+/** @internal */
+type NoHandles = { readonly noHandles: true };
+/** `S`, the slots of the body, or {@link NoHandles} when its input and context hold no handles.
+ * @internal */
+type RepoSlotsOf<TInput, TContext> = TInput extends { workspace: { repos: infer R } }
+  ? keyof R & string
+  : TContext extends { workspace: { repos: infer R } }
+    ? keyof R & string
+    : NoHandles;
+/** The Worktrees of the slots `S` that this key takes: a `push({ slot })` keeps to its own slot.
+ * @internal */
+type PathIn<W, S> = S extends string ? (`/work/${S}/x` extends NonNullable<W> ? WorktreePath<S> : never) : never;
+/** One arm of an input. A key that names a Worktree or a Frame is REQUIRED under a body with Repo
+ * Slots, so that no mix of `cwd`, `worktree` and `path` lands in `/work`. Under a body with none,
+ * `worktree` goes: there is no Worktree. A Turn's arm that carries no kit path (the run's own form)
+ * and every other key stay.
+ * @internal */
+type BindArm<I, S> = I extends object
+  ? "worktree" extends keyof I
+    ? [S] extends [never]
+      ? Omit<I, "worktree"> & { worktree?: never }
+      : Omit<I, "worktree"> & { worktree: PathIn<I["worktree"], S> }
+    : "cwd" extends keyof I
+      ? [NonNullable<I["cwd"]>] extends [AnyFramePath]
+        ? [S] extends [never]
+          ? I
+          : Omit<I, "cwd"> & { cwd: FramePath<S & string> }
+        : I
+      : "path" extends keyof I
+        ? [S] extends [never]
+          ? I
+          : Omit<I, "path"> & { path: PathIn<I["path"], S> }
+        : I
+  : I;
+/** Does this input name a Worktree? @internal */
+type NamesWorktree<I> = I extends object ? ("worktree" extends keyof I ? true : never) : never;
+/** @internal */
+type BindInput<I, S> = [NamesWorktree<I>] extends [never]
+  ? BindArm<I, S>
+  : [S] extends [never]
+    ? BindArm<I, S>
+    : Exclude<BindArm<I, S>, void | undefined>;
+/** A cut's `ready` output with the body's slots. @internal */
+type BindOutput<O, S> = O extends WorktreeReady ? WorktreeReady<S & string> : O;
+/** @internal */
+type BindSnapshot<Snap, S> = Snap extends { output: infer O }
+  ? [O] extends [BindOutput<O, S>]
+    ? Snap
+    : Omit<Snap, "output"> & { output: BindOutput<O, S> }
+  : Snap;
+/** @internal */
+type BindLogic<L extends UnknownActorLogic, S> = L extends AnyStateMachine
+  ? L
+  : ([S] extends [never] ? false : [S] extends [NoHandles] ? true : false) extends true
+    ? L
+    : L extends { readonly definition: { readonly workspace: "none" } }
+      ? L
+      : L extends ActorLogic<infer Snap, infer Ev, infer I, infer Sys, infer Em>
+        ? BindSnapshot<Snap, S> extends infer B extends Snapshot<unknown>
+          ? Omit<L, keyof ActorLogic<Snap, Ev, I, Sys, Em>> & ActorLogic<B, Ev, BindInput<I, S>, any, Em>
+          : never
+        : L;
+/** @internal */
+type BindActors<A extends Record<string, UnknownActorLogic>, TInput, TContext> = {
+  [K in keyof A]: BindLogic<A[K], RepoSlotsOf<TInput, TContext>>;
+};
+
 /**
  * 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
@@ -141,7 +213,9 @@ type ToProvidedActor<TActors extends Record<string, UnknownActorLogic>> = {
  *   `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" }`.
+ * - The `gate` actor is ready to invoke by name: `invoke: { src: "gate" }`. A Gate slot that hears a
+ *   Hook (`actors: { review: gate({ … }) }`) is invoked by its key. An event in its `delivers` whose
+ *   def leaves `audience` unset is `audience: "external"` in this Machine.
  * - 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
@@ -198,6 +272,13 @@ type ToProvidedActor<TActors extends Record<string, UnknownActorLogic>> = {
  *   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).
+ * - an event in a Gate slot's `delivers` that `events` does not list: ``machine "<id>": Gate slot
+ *   "<slot>" delivers "<name>", which no def in jr2Setup({ events }) declares (declared: <names>) —
+ *   list it in events (ADR-0011)``
+ * - an event in a Gate slot's `delivers` that the Gate does not accept at a state that invokes it:
+ *   ``machine "<id>": state "<state>" invokes Gate slot "<slot>", which delivers "<name>", and its
+ *   Gate does not accept it (accepts: <names>) — no handler or look could deliver it: handle it on
+ *   that state, a state above it or a plain child, or drop it from delivers (ADR-0011)``
  *
  * 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
@@ -287,7 +368,8 @@ export function jr2Setup<
      * 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.
+     * (`command(…)`, `http(…)`, `push(…)`), Gate slots (`gate({ … })`), 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. */
@@ -321,7 +403,7 @@ export function jr2Setup<
 ): SetupReturn<
   TContext,
   WorkflowEvent<TDefs>,
-  MergedActors<TActors>,
+  MergedActors<BindActors<TActors, TInput, TContext>>,
   {},
   TActions,
   TGuards & SentByGuards,
@@ -358,6 +440,10 @@ export function jr2Setup<
     // 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 ?? []);
+    // A Gate slot's `delivers` (ADR-0011, ADR-0015): each name is one of this Machine's events, and
+    // one whose def leaves the audience unset reads as `external`, so no Agent has a Hook's event on
+    // its Menu. Before the Menus derive, so the walk, the Menu and the runtime read one vocabulary.
+    externalDelivers((machineConfig as { id?: string }).id ?? "(machine)", defs, def.actors ?? {});
 
     // 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,
@@ -370,6 +456,12 @@ export function jr2Setup<
     // ADR-0007 restore path and invoke-time `resolveAccepts` validation are unchanged.
     const derived = deriveMenus(machineConfig, defs, def.actors ?? {});
     const machine = (inner.createMachine as unknown as (c: never) => AnyStateMachine)(derived.config as never);
+    // A Gate slot's event that its state's Gate does not accept (ADR-0011): no handler or look could
+    // ever deliver it.
+    if (derived.refused.length) {
+      const idOf = (path: readonly string[]): string => stateAt(machine, path).id;
+      throw new Error(`machine "${machine.id}": ${derived.refused.map((r) => r(idOf)).join("; ")}`);
+    }
 
     // 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
@@ -411,13 +503,20 @@ export function jr2Setup<
     // (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);
+    // An Effect's `onDone` with no last arm that always matches (ADR-0075): the run would stay in the
+    // state and show no fault. A compiled Chart comes here too, so the door refuses it.
+    refuseUnroutedOutcome(machine);
     refuseParallelBelowAgents(machine, def.actors ?? {});
+    // One slot, two Turns at once (ADR-0015): one sender and one conversation cannot hold both.
+    refuseSlotActiveTwice(machine);
     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);
+    // A Chart's door reads each reference itself (rule 7), and it refuses every load warning: the
+    // walk's "I could not run this" says nothing of a Chart's `{{...}}` mapper or its `set`.
+    const effects = effectChecks(machine, def.actors ?? {}, defs, compiledChart === true);
     if (effects.errors.length) throw new Error(`machine "${machine.id}": ${effects.errors.join("; ")}`);
 
     const idOf = (path: readonly string[]): string => stateAt(machine, path).id;
@@ -441,7 +540,7 @@ export function jr2Setup<
   return { ...inner, createMachine } as unknown as SetupReturn<
     TContext,
     WorkflowEvent<TDefs>,
-    MergedActors<TActors>,
+    MergedActors<BindActors<TActors, TInput, TContext>>,
     {},
     TActions,
     TGuards & SentByGuards,
@@ -525,7 +624,7 @@ function deriveMenus(
   config: unknown,
   defs: Map<string, EventDef>,
   actors: Record<string, UnknownActorLogic>,
-): { config: unknown; seats: Seat[]; warnings: Warning[]; derivedGateIds: Set<string> } {
+): { config: unknown; seats: Seat[]; warnings: Warning[]; derivedGateIds: Set<string>; refused: Warning[] } {
   const pick = (reach: Reach, kind: "agent" | "external", self: string): string[] =>
     [...reach]
       .filter(([name, owners]) => {
@@ -545,6 +644,8 @@ function deriveMenus(
   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>();
+  // A Gate slot's `delivers` that its state's Gate does not accept (ADR-0011): refusals.
+  const refused: Warning[] = [];
 
   const walk = (
     node: LooseState,
@@ -567,7 +668,7 @@ function deriveMenus(
       const invokes = Array.isArray(node.invoke) ? node.invoke : [node.invoke];
       // >1 unnamed gate in one state would collide on the state-key id; suffix ONLY then, so
       // the common case (one gate per state) keeps the clean name.
-      const unnamedGates = invokes.filter((inv) => inv?.src === "gate" && inv.id == null).length;
+      const unnamedGates = invokes.filter((inv) => isGateInvoke(inv, actors) && inv.id == null).length;
       let ordinal = 0;
       const wrapOne = (inv: LooseInvoke): LooseInvoke => {
         // The slot key IS the Agent name (ADR-0049) — read off the declaration, never authored.
@@ -600,7 +701,7 @@ function deriveMenus(
           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") {
+        if (isGateInvoke(inv, actors)) {
           // 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)]));
@@ -608,6 +709,20 @@ function deriveMenus(
             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 slot = typeof inv.src === "string" ? actors[inv.src] : undefined;
+          if (isGateSlot(slot)) {
+            const outside = slot.gateSlot.delivers.map((d) => d.name).filter((name) => !accepts.includes(name));
+            if (outside.length) {
+              const name = inv.src as string;
+              refused.push(
+                (idOf) =>
+                  `state "${idOf(path)}" invokes Gate slot "${name}", which delivers ${outside.map((n) => `"${n}"`).join(", ")}, ` +
+                  `and its Gate does not accept ${outside.length > 1 ? "them" : "it"} (accepts: ${accepts.join(", ") || "nothing"}) — ` +
+                  "no handler or look could deliver it: handle it on that state, a state above it or a plain child, " +
+                  "or drop it from delivers (ADR-0011)",
+              );
+            }
+          }
           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.
@@ -632,7 +747,7 @@ function deriveMenus(
   };
 
   const out = walk(config as LooseState, new Map(), new Map(), [], NOBODY);
-  return { config: out, seats, warnings: [...warnings.values()], derivedGateIds };
+  return { config: out, seats, warnings: [...warnings.values()], derivedGateIds, refused };
 }
 
 /**
@@ -767,7 +882,7 @@ function unenteredModes(machine: AnyStateMachine, actors: Record<string, Unknown
             continue;
           }
           const party = child.invoke.some(
-            (inv) => inv.src === "gate" || (typeof inv.src === "string" && isAgent(actors[inv.src])),
+            (inv) => isGateInvoke(inv, actors) || (typeof inv.src === "string" && isAgent(actors[inv.src])),
           );
           if (!party) descend(child);
           continue;
@@ -790,27 +905,6 @@ function unenteredModes(machine: AnyStateMachine, actors: Record<string, Unknown
   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
@@ -840,7 +934,7 @@ function restWarnings(machine: AnyStateMachine, actors: Record<string, UnknownAc
           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") {
+            if (isGateInvoke(inv, actors)) {
               for (const [event, candidates] of child.transitions) {
                 if (event.includes(".") || event === "*") continue;
                 if (candidates.some((t) => (t.target ?? []).length > 0)) continue;
@@ -904,6 +998,7 @@ function stampOpenBodies(
       ["agents", "an Agent slot (agent(...))", isAgent],
       ["effects", "an Effect slot", isEffect],
       ["machines", "a Machine", (l: unknown) => (l as { root?: unknown } | undefined)?.root !== undefined],
+      ["gates", "a Gate slot (gate({ … }))", isGateSlot],
     ] as const;
     for (const [kind, what, test] of actorKinds) {
       for (const name of decl.lends[kind] ?? []) {
@@ -974,6 +1069,29 @@ function stateAt(machine: AnyStateMachine, path: readonly string[]): AnyStateMac
   return node;
 }
 
+/**
+ * The `delivers` of each Gate slot this setup declares (ADR-0011, ADR-0015). Each name must be an
+ * event of the Machine: a handler or a look gives a plain event, which the Machine's own def parses.
+ * An event whose def leaves the audience unset reads as `audience: "external"` in this Machine's
+ * vocabulary, so no Agent of the Machine has it on its Menu, and the author does not have to know
+ * this. An explicit audience stays.
+ */
+function externalDelivers(machineId: string, defs: Map<string, EventDef>, actors: Record<string, unknown>): void {
+  for (const [slot, logic] of Object.entries(actors)) {
+    if (!isGateSlot(logic)) continue;
+    for (const d of logic.gateSlot.delivers) {
+      const own = defs.get(d.name);
+      if (!own) {
+        throw new Error(
+          `machine "${machineId}": Gate slot "${slot}" delivers "${d.name}", which no def in jr2Setup({ events }) ` +
+            `declares (declared: ${[...defs.keys()].join(", ") || "none"}) — list it in events (ADR-0011)`,
+        );
+      }
+      if (own.audience === undefined) defs.set(d.name, Object.freeze({ ...own, audience: "external" as const }));
+    }
+  }
+}
+
 /** 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 !== "*");
@@ -984,7 +1102,7 @@ function partiesOf(node: LooseState, actors: Record<string, UnknownActorLogic>):
   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"),
+    gate: invokes.some((inv) => isGateInvoke(inv, actors)),
   };
 }
 
@@ -1066,7 +1184,7 @@ function refuseUnknownKeys(consumer: object, agentName: string): void {
 /** 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 wrapped = (args: InputArgs): AgentRunInput => {
     const consumer = resolveInput(orig, args) as Partial<AgentTurnInput & AgentRunInput>;
     refuseUnknownKeys(consumer, agentName);
     return {
@@ -1097,6 +1215,8 @@ function wrapAgentInput(orig: unknown, derived: string[], agentName: string, men
       menu: menuOf(agentName),
     };
   };
+  // The walk reads what the author wrote: `workspace()`, for a literal `cwd`.
+  return Object.assign(wrapped, { consumerInput: orig });
 }
 
 /** Wrap a gate invoke input: append the derived accepted set. */