@jr2/orchestrator 0.1.0

package/src/customize.ts

@@ -0,0 +1,348 @@
+// `customize(machine, parts)` (ADR-0049, ADR-0051): RETUNE what a Machine carries, without
+// editing the module that exports it. A package exports a Machine and nothing beside it — the
+// door, the vocabulary, the Agents, the Sandbox Image and the Repo Slots all ride the exported
+// object — so the only thing a consumer can be handed is the Machine, and the only honest way to
+// say "same workflow, my model, my repository" is a function over it.
+//
+// It is a plain function in the family of `workspace()` and `pool()`, returning a plain
+// `StateMachine`: no jr2-owned machine type over xstate's, nothing to survive a later
+// `.provide()`, nothing to learn (ADR-0015's rule, restated by ADR-0049 — a `.with()` method and
+// a callable-machine hybrid were both rejected there).
+//
+// Three moves, and each is the smallest one that works:
+//
+//   - An AGENT override is xstate's own `provide`: `machine.provide({ actors: { coder:
+//     agent({ ...stock, ...override }) } })`. The slot already IS the Agent (ADR-0049), so
+//     retuning one is substituting a slot's logic, which is what `provide` is for.
+//   - A CHILD override is the same call one level down, recursing. Each level is exactly the
+//     one-level reach ADR-0015 found `provide` has — held by the composer who owns the child
+//     object, never host-side injection into somebody else's Machine.
+//   - The IMAGE and the REPOS are the parts `provide` cannot carry: xstate copies implementations
+//     and passes the CONFIG through by reference, and every part a Machine carries is keyed on
+//     that config (parts.ts, vocabulary.ts). A new image or a bound slot therefore needs a new key
+//     — so those fields clone the wrapper's config and rebuild it with the same implementations,
+//     re-attaching what the original carried.
+//
+// jr2's wrappers are TRANSPARENT: `agents`/`actors` route through `workspace()`'s `body` and
+// `pool()`'s `worker`, so a consumer customizing a Workspace-rooted workflow never writes `body`
+// and never has to know that jr2 wrapped anything. `image`/`user`/`repos` travel the same chain in
+// the other direction — down to the `workspace()` that owns the seats and the slots.
+//
+// Both halves route on the wrapper's own RECORD of being one, never on a slot's spelling: the
+// runtime reads `wrapperBodyOf` and the types read `JR2Wrapper` (parts.ts), which the wrappers
+// stamp and state together. That is what keeps the compiler's answer and the runtime's the same
+// answer for a Machine whose author happened to name a slot `body`.
+//
+// Only DECLARED parts can be customized; none can be added. A consumer who needs a third Agent
+// composes a new Machine — which is the same act, spelled honestly. A `workspace()` that declared
+// its slot MAP Open (`repos: open`, ADR-0051) declared exactly this: every slot is the composer's
+// to name, so the map they write is the declaration, not an addition to one.
+
+import { StateMachine, type AnyStateMachine, type InputFrom, type ProvidedActor } from "xstate";
+import type { AgentLogic } from "./actor.ts";
+import { isAgent, type AgentDefinition } from "./agent.ts";
+import { agent } from "./harness-client.ts";
+import {
+  asMachine,
+  assertRepoSlot,
+  attachSandboxParts,
+  attachWrapperBody,
+  composesSandbox,
+  open,
+  sandboxPartsOf,
+  wrapperBodyOf,
+  type JR2Repos,
+  type JR2Wrapper,
+  type RepoSlot,
+  type SandboxParts,
+} from "./parts.ts";
+import { attachInputSchema, attachVocabulary, inputSchemaOf, vocabularyOf } from "./vocabulary.ts";
+
+// --- What a Machine declares, read at the TYPE level ---------------------------------------------
+// Everything below reads xstate's own `TActor` parameter — the `{ src, logic, id }` union
+// `setup({ actors })` derives and `provide()` is checked against. Nothing is registered, declared
+// twice, or inferred from a name: the slots a Machine carries ARE its type, so a `customize()` of
+// an Agent the Machine does not carry is a compile error (ADR-0050) and `jr2 up`'s typecheck gate
+// is where it stops.
+
+/** The actor slots a Machine declares. */
+type SlotsOf<M extends AnyStateMachine> =
+  M extends StateMachine<
+    any,
+    any,
+    any,
+    infer TActor extends ProvidedActor,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any
+  >
+    ? TActor
+    : never;
+
+/** The logic a Machine declares under one slot key. */
+type LogicAt<M extends AnyStateMachine, K extends string> = Extract<SlotsOf<M>, { src: K }>["logic"];
+
+/** The Agent slots — told from every other slot by their logic, which no other actor kind has. */
+type AgentSlots<M extends AnyStateMachine> = Extract<SlotsOf<M>, { logic: AgentLogic }>["src"];
+
+/** The child-Machine slots: the slots composition reaches (ADR-0049 — a nested Machine is an
+ * ordinary `invoke` of an ordinary slot). */
+type ChildSlots<M extends AnyStateMachine> = Extract<SlotsOf<M>, { logic: AnyStateMachine }>["src"];
+
+/** The child Machine under one slot key, constrained so `Customize` may recurse into it. */
+type ChildAt<M extends AnyStateMachine, K extends string> = Extract<LogicAt<M, K>, AnyStateMachine>;
+
+/**
+ * The Machine a `customize()` actually reaches: jr2's wrappers are transparent to their body, so
+ * this is the first Machine an AUTHOR wrote. It mirrors `bodyOf`'s runtime walk, and reads the
+ * SAME record — `JR2Wrapper` is the type half of the stamp `attachWrapperBody` writes — so both
+ * stop at the same Machine and what the compiler offers is what the call retunes. Recursive in
+ * tail position, as the runtime walk is unbounded: however many wrappers a composer stacks, the
+ * compiler and the call answer alike.
+ */
+// Each step is taken on the wrapper's MARKER (`JR2Wrapper`, parts.ts), never on a slot's spelling —
+// an author is free to name a slot `body` or `worker`, and routing through it because of the name
+// would offer the Agents of a Machine the composer never named.
+type Reached<M extends AnyStateMachine> = M extends JR2Wrapper<infer TBody> ? Reached<TBody> : M;
+
+/**
+ * The `workspace()` a `customize()` reaches for its SEATS and SLOTS — the other direction from
+ * {@link Reached}: down through the wrappers to the first Machine that composes a Sandbox, which
+ * is the one whose `JR2Repos` marker says which slots exist (ADR-0051). `never` when no wrapper on
+ * the chain composes one, which is what makes `repos` unavailable there rather than `{}`.
+ */
+type WorkspaceOf<M extends AnyStateMachine> =
+  M extends JR2Repos<any> ? M : M extends JR2Wrapper<infer TBody> ? WorkspaceOf<TBody> : never;
+
+/** The Repo Slot keys the reached `workspace()` declared. The `never` case is tested by itself,
+ * because `never extends JR2Repos<infer TSlots>` is true with nothing to infer from — and an
+ * uninferred `TSlots` widens to `string`, which would offer every key exactly where there are none. */
+type RepoSlotsOf<M extends AnyStateMachine> = [WorkspaceOf<M>] extends [never]
+  ? never
+  : WorkspaceOf<M> extends JR2Repos<infer TSlots>
+    ? TSlots
+    : never;
+
+/**
+ * What may be retuned on one Machine, mirroring the DECLARATION's own shape and recursively
+ * partial (ADR-0049): every key optional, every Agent override a partial definition, every child
+ * a `Customize` of that child.
+ *
+ * `image`/`user` are the `workspace()` options (ADR-0037, ADR-0005) and apply to the wrapper the
+ * chain reaches; a Machine that composes no Sandbox refuses them at build time, because there is
+ * nothing for them to name.
+ */
+export type Customize<M extends AnyStateMachine> = {
+  /** Retune an Agent this Machine carries: the override is layered over the stock definition, so
+   * `{ model }` alone keeps the instructions the author wrote — and BINDS the model when the
+   * author left it Open (ADR-0054), which is the common consumer line for a packaged Machine. The
+   * override is a `Partial<AgentDefinition>`, never a declaration: a composer binds, and binding
+   * to `open` again is not a thing anyone means. A Machine carrying no Agent takes `never` rather
+   * than `{}`: an empty object type accepts any literal, which would make the one case with
+   * nothing to name the one case with nothing checked. */
+  agents?: [AgentSlots<Reached<M>>] extends [never]
+    ? never
+    : { [K in AgentSlots<Reached<M>>]?: Partial<AgentDefinition> };
+  /** Retune a Machine this one composes — the same shape, one level down. */
+  actors?: [ChildSlots<Reached<M>>] extends [never]
+    ? never
+    : { [K in ChildSlots<Reached<M>>]?: Customize<ChildAt<Reached<M>, K>> };
+  /** The Sandbox Image (ADR-0037): a `file:` URL to a docker context this module ships, or a
+   * registry ref. */
+  image?: string;
+  /** The User Container's image (ADR-0005), in the same two shapes. */
+  user?: string;
+  /** Bind the Repo Slots the reached `workspace()` declared (ADR-0051) — an open slot to a url,
+   * or a bound or per-run one to a different Binding; any of the three forms, so a consumer can
+   * also bind a mapper over the wrapper's door. A slot the Machine does not declare is a compile
+   * error, and a Machine that composes no Sandbox takes `never`, as `agents` does. A `workspace()`
+   * that declared its map Open takes any keys — they are the composer's words, in the order the
+   * Machine documents — and at least one, checked at the call. */
+  repos?: [RepoSlotsOf<M>] extends [never] ? never : { [K in RepoSlotsOf<M>]?: RepoSlot<InputFrom<WorkspaceOf<M>>> };
+};
+
+/** The same shape with the types erased — what the implementation walks. */
+type LooseParts = {
+  agents?: Record<string, Partial<AgentDefinition> | undefined>;
+  actors?: Record<string, LooseParts | undefined>;
+  image?: string;
+  user?: string;
+  repos?: Record<string, RepoSlot | undefined>;
+};
+
+/**
+ * Retune the parts a Machine carries, returning a NEW Machine of the same type — the original is
+ * untouched, so two customizations of one import are two independent Machines (ADR-0049's
+ * `deep`/`quick`), and a run of either carries what it was given.
+ */
+export function customize<M extends AnyStateMachine>(machine: M, parts: Customize<M>): M {
+  const { agents, actors, image, user, repos } = parts as LooseParts;
+  let out: AnyStateMachine = machine;
+  // Order matters in one direction only: the Sandbox seats and slots REBUILD the wrapper, so they
+  // go last and carry the retuned implementations with them.
+  if (agents || actors) out = retune(out, { agents, actors });
+  const seats: Seats = {
+    ...(image !== undefined ? { image } : {}),
+    ...(user !== undefined ? { user } : {}),
+    ...(repos !== undefined ? { repos } : {}),
+  };
+  if (seats.image !== undefined || seats.user !== undefined || seats.repos !== undefined) out = reseat(out, seats);
+  return out as M;
+}
+
+/** What `reseat` carries down the chain: the two image seats and the slot overrides, each present
+ * only when the composer named it. */
+type Seats = { image?: string; user?: string; repos?: Record<string, RepoSlot | undefined> };
+
+/** The slot keys whose logic answers `pred` — what an error names, so the message is the
+ * Machine's own declaration rather than advice. */
+function slotsWhere(machine: AnyStateMachine, pred: (logic: unknown) => boolean): string[] {
+  return Object.entries(machine.implementations.actors as Record<string, unknown>)
+    .filter(([, logic]) => pred(logic))
+    .map(([name]) => name);
+}
+
+const listed = (names: string[]): string => names.join(", ") || "none";
+
+/** The Machine a wrapper is transparent to, or undefined for a Machine an author wrote. */
+function bodyOf(machine: AnyStateMachine): { slot: string; body: AnyStateMachine } | undefined {
+  const slot = wrapperBodyOf(machine);
+  if (!slot) return undefined;
+  const body = asMachine((machine.implementations.actors as Record<string, unknown>)[slot]);
+  return body ? { slot, body } : undefined;
+}
+
+/** Substitute one slot's logic — the one move every level of this module makes. */
+function substitute(machine: AnyStateMachine, actors: Record<string, unknown>): AnyStateMachine {
+  return machine.provide({ actors } as Parameters<AnyStateMachine["provide"]>[0]);
+}
+
+/** Agents and children, resolved against the first Machine an author wrote. */
+function retune(machine: AnyStateMachine, parts: LooseParts): AnyStateMachine {
+  const inner = bodyOf(machine);
+  if (inner) return substitute(machine, { [inner.slot]: retune(inner.body, parts) });
+
+  const actors: Record<string, unknown> = {};
+  for (const [name, override] of Object.entries(parts.agents ?? {})) {
+    if (!override) continue;
+    const logic = (machine.implementations.actors as Record<string, unknown>)[name];
+    if (!isAgent(logic)) {
+      throw new Error(
+        `customize(): machine "${machine.id}" carries no Agent slot "${name}" — its Agents are: ` +
+          `${listed(slotsWhere(machine, isAgent))} (ADR-0049). Only declared parts can be retuned; ` +
+          "a Machine that needs another Agent is a new Machine.",
+      );
+    }
+    // The override is layered OVER the stock declaration, never merged into it: `{ model }` alone
+    // keeps the author's instructions, and the result is one whole declaration the slot carries —
+    // bound, if the model was Open and this override named one; still Open if it did not, and the
+    // walk reports it again (ADR-0054).
+    actors[name] = agent({ ...logic.definition, ...override });
+  }
+  for (const [name, childParts] of Object.entries(parts.actors ?? {})) {
+    if (!childParts) continue;
+    const child = asMachine((machine.implementations.actors as Record<string, unknown>)[name]);
+    if (!child) {
+      throw new Error(
+        `customize(): machine "${machine.id}" composes no Machine under "${name}" — the Machines ` +
+          `it composes are: ${listed(slotsWhere(machine, (logic) => !!asMachine(logic)))} (ADR-0049).`,
+      );
+    }
+    actors[name] = customize(child, childParts as Customize<AnyStateMachine>);
+  }
+  return substitute(machine, actors);
+}
+
+/** The Sandbox seats and slots, applied to the `workspace()` the chain reaches. */
+function reseat(machine: AnyStateMachine, seats: Seats): AnyStateMachine {
+  if (composesSandbox(machine)) {
+    const { repos: override, ...images } = seats;
+    const parts = sandboxPartsOf(machine);
+    if (parts.repos === open) return rebuild(machine, { ...parts, ...images, repos: nameSlots(machine, override) });
+    const repos = { ...parts.repos };
+    // Only DECLARED slots can be bound (ADR-0051): the Machine's own word for each Repo is the
+    // key, and a key it never declared would attach a repository the body has no handle for.
+    // The check is on the declaration's OWN keys — `in` would also answer yes for `constructor`
+    // and every other prototype key, and this runtime twin of the compile-time check must give
+    // the compiler's answer for the calls the compiler never sees (an untyped call, a widened
+    // key). Binding a per-run slot with a static url is legal — it becomes bound; which slots a
+    // consumer may fix is the package author's call, expressed by the slot's state.
+    for (const [slot, value] of Object.entries(override ?? {})) {
+      if (value === undefined) continue;
+      if (!Object.hasOwn(parts.repos, slot)) {
+        throw new Error(
+          `customize(): machine "${machine.id}" declares no Repo Slot "${slot}" — its slots are: ` +
+            `${listed(Object.keys(parts.repos))} (ADR-0051)`,
+        );
+      }
+      assertRepoSlot("customize()", slot, value);
+      repos[slot] = value;
+    }
+    return rebuild(machine, { ...parts, ...images, repos });
+  }
+  const inner = bodyOf(machine);
+  if (!inner) {
+    const named = seats.repos !== undefined ? "`repos`" : "`image`/`user`";
+    throw new Error(
+      `customize(): ${named} say what a SANDBOX is made of and which Repos it attaches, and machine ` +
+        `"${machine.id}" composes none — only a workspace() wrapper carries those seats and slots ` +
+        "(ADR-0049, ADR-0037, ADR-0051).",
+    );
+  }
+  return substitute(machine, { [inner.slot]: reseat(inner.body, seats) });
+}
+
+/**
+ * The composer's half of an Open slot MAP (ADR-0051): the Machine said `repos: open`, so the map
+ * written here IS the declaration — every key is the composer's word for a Repo, the order is
+ * kept for the body, and each value is any of the three slot forms (a composer building a further
+ * package may leave one `open` for the next composer). Held to the same checks `workspace()` runs
+ * on a declared map, because it is the same map one call later: a directory-shaped key, a valid
+ * binding, and at least one slot. A `customize` that names no `repos` leaves the map Open, and
+ * the walk reports it again.
+ */
+function nameSlots(machine: AnyStateMachine, override: Seats["repos"]): SandboxParts["repos"] {
+  if (override === undefined) return open;
+  const repos: Record<string, RepoSlot> = {};
+  for (const [slot, value] of Object.entries(override)) {
+    if (value === undefined) continue;
+    assertRepoSlot("customize()", slot, value);
+    repos[slot] = value;
+  }
+  if (Object.keys(repos).length === 0) {
+    throw new Error(
+      `customize(): machine "${machine.id}" declares its Repo Slots open as a map — name at least one: ` +
+        '`repos: { app: "https://…" }` (ADR-0051).',
+    );
+  }
+  return repos;
+}
+
+/**
+ * Rebuild a wrapper around a NEW config object, carrying everything the original carried.
+ *
+ * `provide()` cannot do this: it passes `this.config` through by reference, and the parts a
+ * Machine carries are keyed on exactly that object — so writing new Sandbox seats under it would
+ * retune the ORIGINAL too, and `deep`/`quick` would be one Machine wearing the last image
+ * assigned. The clone is shallow because only the object's IDENTITY changes: the states, the
+ * transitions and the invokes are the same values, so the Machine shape — and therefore the
+ * fingerprint a restore compares (ADR-0030) — is bit-identical to the original's.
+ */
+function rebuild(machine: AnyStateMachine, seats: SandboxParts): AnyStateMachine {
+  const clone = new StateMachine({ ...machine.config }, machine.implementations) as AnyStateMachine;
+  const vocabulary = vocabularyOf(machine);
+  if (vocabulary) attachVocabulary(clone, vocabulary);
+  const door = inputSchemaOf(machine);
+  if (door) attachInputSchema(clone, door);
+  const slot = wrapperBodyOf(machine);
+  if (slot) attachWrapperBody(clone, slot);
+  attachSandboxParts(clone, seats);
+  return clone;
+}

package/src/durability.ts

@@ -0,0 +1,135 @@
+// Durable Machine state codec (ADR-0007): strip the non-serializable, environment-bound parts
+// of an xstate snapshot on the way to the store, and re-inject them on the way back. Context
+// holds live ports (a FlueClient, the ControlPlane) and child actor inputs reference them; the
+// codec replaces those with placeholders the host re-hydrates against the current process.
+//
+// A live handle hides in TWO places: the parent `context`, and each invoked child's persisted
+// input at `snapshot.children.<id>.snapshot.input`. We strip both on save and re-inject both on
+// restore. The child re-attach lever is the persisted input, not the parent `invoke` (xstate v5
+// re-spawns from the child's persisted input on restore), so `rewriteChildInput` is what makes a
+// restored run re-attach its stream instead of re-POSTing.
+//
+// We rebuild the touched paths immutably rather than `structuredClone`-ing the whole snapshot:
+// a live handle in `context` (e.g. a function) makes `structuredClone` throw DataCloneError
+// *before* a stripper could run, so the strip must replace those references, not clone them.
+
+export type StoredSnapshot = {
+  runId: string;
+  status: string;
+  snapshot: unknown;
+  reason?: string;
+};
+
+type ChildEntry = { snapshot?: { input?: unknown; [k: string]: unknown }; [k: string]: unknown };
+
+type AnySnapshot = {
+  context?: unknown;
+  children?: Record<string, ChildEntry | undefined>;
+  [k: string]: unknown;
+};
+
+/**
+ * Rebuild a snapshot, applying `onContext` to `context` and `onChildInput` to every invoked
+ * child's persisted input. Returns a new top-level structure (the source is never mutated); the
+ * untouched JSON-shaped siblings are carried by reference. Used in both directions — on serialize
+ * the callbacks strip live handles (yielding a JSON-safe value), on hydrate they re-inject them.
+ */
+function mapSnapshot(value: unknown, onContext: (ctx: any) => any, onChildInput: (input: any) => any): unknown {
+  if (!value || typeof value !== "object") return value;
+  const src = value as AnySnapshot;
+  const out: AnySnapshot = { ...src };
+
+  if ("context" in src) {
+    out.context = onContext(src.context);
+  }
+
+  const children = src.children;
+  if (children && typeof children === "object") {
+    const nextChildren: Record<string, ChildEntry | undefined> = {};
+    for (const id of Object.keys(children)) {
+      const child = children[id];
+      const childSnapshot = child?.snapshot;
+      if (child && childSnapshot && typeof childSnapshot === "object" && "input" in childSnapshot) {
+        nextChildren[id] = {
+          ...child,
+          snapshot: { ...childSnapshot, input: onChildInput(childSnapshot.input) },
+        };
+      } else {
+        nextChildren[id] = child;
+      }
+    }
+    out.children = nextChildren;
+  }
+
+  return out;
+}
+
+/** Serialize a snapshot for persistence, stripping live context and child inputs. */
+export function serializeSnapshot(
+  snapshot: unknown,
+  opts: { stripContext: (ctx: any) => any; stripChildInput: (input: any) => any },
+): unknown {
+  return mapSnapshot(snapshot, opts.stripContext, opts.stripChildInput);
+}
+
+/** Rebuild a runnable snapshot from stored form, re-injecting live context and child inputs. */
+export function hydrateSnapshot(
+  stored: unknown,
+  opts: { injectContext: (ctx: any) => any; rewriteChildInput: (input: any) => any },
+): unknown {
+  return mapSnapshot(stored, opts.injectContext, opts.rewriteChildInput);
+}
+
+/** The durable admission record restore rewrites into a child input (see actor.ts). Structural
+ * twin of `AgentAdmission` — kept import-free so this codec module stays a pure leaf.
+ * `instanceId` is the actor's live-conversation stamp (a runaway reroll advances it past the
+ * ledger key — ADR-0035); it rides the rewrite verbatim so the restored actor re-addresses the
+ * live conversation. */
+type Admission = { streamUrl: string; offset: string; submissionId: string; instanceId?: string };
+
+/** A persisted Agent child input: `instanceId` (the durable handle) beside `agentName` —
+ * both strings by construction (machine children carry neither at top level; `endpoint` can no
+ * longer identify it, being ambient-optional since ADR-0016). */
+function isAgentRunInput(input: unknown): input is { instanceId: string; agentName: string } {
+  return (
+    !!input &&
+    typeof input === "object" &&
+    typeof (input as { instanceId?: unknown }).instanceId === "string" &&
+    typeof (input as { agentName?: unknown }).agentName === "string"
+  );
+}
+
+/**
+ * Rewrite every persisted Agent child input in a snapshot TREE so restore re-attaches
+ * (drop `prompt`, set `attach`) instead of re-prompting — at any nesting depth. The admissions
+ * come from the run's HOST LEDGER (ADR-0016), keyed by iid: iids are globally unique, so one
+ * flat map covers the whole tree (the old per-level `context.offsets` scoping died with the
+ * context leg). An instanceId with no recorded admission re-admits its prompt — a run that
+ * crashed before its admission was ledgered is the same first-turn at-most-once edge as before
+ * (ADR-0007), narrowed to the send→record window.
+ */
+export function reattachAgentRuns(snapshot: unknown, admissions: Record<string, Admission>): unknown {
+  const walk = (node: unknown): unknown => {
+    if (!node || typeof node !== "object") return node;
+    const src = node as AnySnapshot & { input?: unknown };
+    const out: typeof src = { ...src };
+
+    const admission = isAgentRunInput(src.input) ? admissions[src.input.instanceId] : undefined;
+    if (isAgentRunInput(src.input) && admission !== undefined) {
+      out.input = { ...src.input, prompt: undefined, attach: admission };
+    }
+
+    const children = src.children;
+    if (children && typeof children === "object") {
+      const nextChildren: Record<string, ChildEntry | undefined> = {};
+      for (const id of Object.keys(children)) {
+        const child = children[id];
+        nextChildren[id] =
+          child && child.snapshot ? { ...child, snapshot: walk(child.snapshot) as ChildEntry["snapshot"] } : child;
+      }
+      out.children = nextChildren;
+    }
+    return out;
+  };
+  return walk(snapshot);
+}

package/src/fingerprint.ts

@@ -0,0 +1,92 @@
+// The content address of a Machine's SHAPE (ADR-0030). A persisted snapshot names the Machine it
+// was written under; restore compares and refuses a mismatch, because a workflow is matched to a
+// run by filename alone and the state volume outlives the image that wrote it — so a run parked at
+// a Gate meets whatever `jr2 up` baked in next, and nothing used to notice.
+//
+// What it hashes is RESTORABILITY, not behavior: the facts that decide whether an old snapshot can
+// still be interpreted — state ids and nesting, which state is initial, what each state invokes and
+// under which id (the invoke id is the key in the snapshot's `children` map), and where every
+// transition goes. Not guard bodies, not assigns, not prompts. Editing a guard changes what a run
+// DOES next; it does not make the snapshot unreadable, and restore-after-redeploy would be unusable
+// if every such edit stranded the runs in flight. That line is the whole design, and ADR-0030 argues
+// it: this is a restorability check, and drift means "I can no longer read what I saved."
+//
+// The traversal is `machine-doc.ts`'s, deliberately — it is already deterministic (states sorted by
+// `order`), JSON-pure, provider-independent, and descends into invoked AND spawned child machines.
+// This module only projects it down and hashes the result.
+
+import { createHash } from "node:crypto";
+import type { AnyStateMachine } from "xstate";
+import { serializeMachine, type MachineBodyDoc, type MachineStateDoc } from "./machine-doc.ts";
+
+/** The projection that gets hashed — a Machine reduced to what restore has to agree about. */
+type ShapeState = {
+  id: string;
+  key: string;
+  type: string;
+  initial?: string;
+  /** `id` as well as `src`: the id keys this child in the persisted `children` map. */
+  invoke: Array<{ id: string; src: string }>;
+  states: ShapeState[];
+  children: Array<{ src: string; via: string; machine?: ShapeBody }>;
+  /** The walk could not see this state's spawns — recorded so the blind spot is IN the hash. */
+  opaque?: true;
+};
+
+type ShapeBody = {
+  id: string;
+  root: ShapeState;
+  /** `source|event|targets`, sorted — reordering `on:` keys is not a restorability change. */
+  transitions: string[];
+};
+
+function shapeState(state: MachineStateDoc): ShapeState {
+  const out: ShapeState = {
+    id: state.id,
+    key: state.key,
+    type: state.type,
+    invoke: state.invoke.map((inv) => ({ id: inv.id, src: inv.src })),
+    states: state.states.map(shapeState),
+    children: state.children.map((child) => ({
+      src: child.src,
+      via: child.via,
+      ...(child.machine ? { machine: shapeBody(child.machine) } : {}),
+    })),
+  };
+  if (state.initial !== undefined) out.initial = state.initial;
+  if (state.opaqueActions) out.opaque = true;
+  return out;
+}
+
+function shapeBody(body: MachineBodyDoc): ShapeBody {
+  return {
+    id: body.id,
+    root: shapeState(body.root),
+    transitions: body.transitions.map((t) => `${t.source}|${t.event}|${t.targets.join(",")}`).sort(),
+  };
+}
+
+/** Memoized per machine OBJECT: `persist` runs on every snapshot microtask, and a dev reload's
+ * fresh machine object correctly gets a fresh entry. Deliberately NOT `vocabularyOf`'s key —
+ * that one is `machine.config`, because a `.provide()` clone must keep the defs it was built
+ * with (ADR-0011). A shape has nothing to keep: it is derived from the config alone, so a clone
+ * recomputes the identical digest and only pays for the walk once. */
+const cache = new WeakMap<AnyStateMachine, string>();
+
+/**
+ * This Machine's shape, as 12 hex chars — the same width `jr2 up`'s content hash uses, and for the
+ * same reason: it is read by humans in error messages far more often than by machines.
+ *
+ * The workflow NAME is deliberately excluded. A run already carries its workflow, and restore looks
+ * the def up by that name before it gets here; folding the name in would only make a rename look
+ * like a shape change on a run that never resolves to the renamed def anyway.
+ */
+export function fingerprintOf(machine: AnyStateMachine): string {
+  const hit = cache.get(machine);
+  if (hit !== undefined) return hit;
+  // `serializeMachine` wants a workflow name for the DTO; the projection drops it.
+  const shape = shapeBody(serializeMachine("", machine));
+  const digest = createHash("sha256").update(JSON.stringify(shape)).digest("hex").slice(0, 12);
+  cache.set(machine, digest);
+  return digest;
+}

package/src/gate.ts

@@ -0,0 +1,76 @@
+// The `gate` actor (ADR-0011): a pending external input on a run, as an addressable resource.
+// The symmetric twin of the Agent actor for every NON-agent caller — humans (`jr2 send`, a UI),
+// webhook translators, CI. "Human" is policy, not mechanism, so the actor is not named for one
+// caller.
+//
+// A state that needs outside input invokes `gate` with `{ gate?, accepts?, meta? }`. On start
+// the actor resolves the accepted names against the vocabulary of the MACHINE THAT INVOKED IT —
+// `self._parent.logic`, per-Machine scoping (ADR-0011, ADR-0049), which is what lets a nested
+// Machine keep its own `approve` — and registers into the host's table; `GET /runs/:id` then
+// lists the gate (accepts +
+// schemas + meta — what a CLI, an inbox UI, or a webhook translator discovers), and
+// `POST /runs/:id/gates/:gate/events` validates against the named schema and delivers through
+// the closure below — the event lands on the state that invoked the gate, at any nesting depth.
+// Leaving the state stops the actor, which destroys the gate: parking IS retention (ADR-0012),
+// and a gone state is a gone surface.
+
+import { fromCallback } from "xstate";
+import { actorPath, gateAddress, resolveAccepts, runBindingOf, type DeliveredEvent } from "./registration.ts";
+
+export type GateInput = {
+  /**
+   * The gate's caller-facing id. LEAVE IT UNSET for the derived default: the actor path below
+   * the run root (in a jr2Setup machine the leaf is the state key path — `deriveMenus` names the
+   * invoke), which is unique wherever concurrently live siblings have distinct actor ids — i.e.
+   * wherever fan-out is correct at all. Author an id only to give external callers a meaningful
+   * flat name (e.g. the feature id); then run-wide uniqueness is the author's problem, and two
+   * LIVE gates with one id fail loudly at invoke. Run-scoped by the host either way — two runs'
+   * `"F-12"` gates cannot collide.
+   */
+  gate?: string;
+  /**
+   * Accepted event names. In a jr2Setup machine LEAVE IT UNSET: the accepted set derives from
+   * the invoking state's transitions, audience ∈ {external, any} (ADR-0015) — this field is the
+   * escape hatch. An unlisted name is an invoke-time error either way.
+   */
+  accepts?: readonly string[];
+  /** Serializable context for callers: what a UI renders, what a webhook matches on (prUrl…). */
+  meta?: Record<string, unknown>;
+};
+
+/** The gate actor. Sends nothing of its own; every event it delivers is a caller's, validated.
+ * Input admits `undefined` so `invoke: { src: "gate" }` — the fully-derived common case —
+ * typechecks without an input mapper. */
+export const gate = fromCallback<DeliveredEvent, GateInput | undefined>(({ input: raw, system, sendBack, self }) => {
+  const input = raw ?? {};
+  const binding = runBindingOf(system);
+  // The derived id is deterministic from machine structure, so recomputing it on every (re)start
+  // is restore-stable and needs no input-mapper persistence — the mapper is only load-bearing
+  // where minting has a random component (mintIid's fresh-session suffix, ADR-0016).
+  const path = actorPath(self);
+  const id = input.gate ?? path.join(".");
+  if (!id) {
+    // Only a rootless invocation (createActor(gate) directly) has an empty path.
+    throw new Error("gate has no derivable id (no parent actor) — pass `gate` explicitly");
+  }
+  if (!input.accepts?.length) {
+    // Derivation found nothing (or a plain-setup machine passed nothing): a gate accepting no
+    // events can never be moved — refuse loudly at invoke rather than park a dead surface.
+    throw new Error(
+      `gate "${id}" accepts no events — handle at least one external/any event on the ` +
+        `invoking state (the accepted set derives from its transitions), or pass \`accepts\` explicitly`,
+    );
+  }
+  const defs = resolveAccepts(self, input.accepts);
+  const dispose = binding.table.register({
+    address: gateAddress(binding.runId, id),
+    runId: binding.runId,
+    kind: "gate",
+    id,
+    path,
+    defs,
+    meta: input.meta,
+    deliver: (event) => sendBack(event),
+  });
+  return dispose;
+});