@jr2/orchestrator 0.1.0

package/src/pool.ts

@@ -0,0 +1,284 @@
+// `pool(worker, spec)` (ADR-0017): the jr2-owned top-of-the-run Machine — one worker per Source
+// item, at most `cap` at once. It absorbs what every jr-shaped workflow used to hand-roll:
+// spawn-under-cap, stable child identity, `xstate.done.actor.*` completion collection,
+// `stopChild` bookkeeping, the wake gate, and the re-query timer. The one top-level `spawnChild`
+// lives HERE, once — which is what keeps the Console's static trace guaranteed by
+// construction (the comment-enforced "keep spawnChild top-level" footgun deletes), and the
+// worker is a registered string src, which is what makes spawned children persistable at all
+// (xstate cannot persist inline-src children).
+//
+// The Source port is generalized — `next(active) → item | null`, plus an optional `wake` event
+// def (a webhook / `jr2 send` push seam, served as a standing gate named "source") and
+// `pollEvery` (the set mutates underneath us — re-query). A queue, a generator, or a re-queried
+// set; tk's claim actor is one adapter (CONTEXT.md: Work Source is the ticket-flavored Source).
+//
+// Terminal triage is three-valued (ADR-0017, forced by parking-is-retention):
+//   - drained    — source empty and all children settled → final (jr exit 0);
+//   - deadlocked — open-but-never-ready items and nothing running that could unblock them →
+//                  final, distinct status (jr exit 2), never an indistinguishable idle poll;
+//   - waiting    — children parked (gates, agents) → the run stays open; the gates list is the
+//                  "what needs me" surface (jr exit 3).
+// The pool can make this call because it owns both the source and the children. Distinguishing
+// drained from deadlocked needs one more bit than `null` carries, so a Source's `next` MAY
+// resolve the richer `{ item: null, open: n }` shape; a bare `null` means drained-when-idle.
+
+import {
+  assign,
+  setup,
+  spawnChild,
+  stopChild,
+  type AnyStateMachine,
+  type PromiseActorLogic,
+  type StateMachine,
+} from "xstate";
+import type { z } from "zod";
+import type { EventDef } from "@jr2/agent-protocol";
+import { gate } from "./gate.ts";
+import { attachWrapperBody, type JR2Wrapper, type WrapperActors } from "./parts.ts";
+import { attachInputSchema, attachVocabulary } from "./vocabulary.ts";
+
+/**
+ * What `next` resolves. A plain item claims it; `null` says "nothing ready now" (drained, when
+ * nothing is running); the rich shape adds `open` — how many items exist but are not ready —
+ * which is the one bit that separates DRAINED from DEADLOCKED when the pool goes idle.
+ */
+export type SourceNextResult<T> = T | null | { item: T | null; open: number };
+
+/** The Source port (ADR-0017): where a pool draws work from. Build one with {@link source}. */
+export type SourceSpec<T> = {
+  /** Claim the next ready item, excluding the ones already being worked (`input.active`).
+   * A union of the accepted output shapes because xstate's actor-logic type is invariant in its
+   * output — a `fromPromise` inferred as `T | null` must still assign. */
+  next:
+    | PromiseActorLogic<SourceNextResult<T>, { active: string[] }>
+    | PromiseActorLogic<{ item: T | null; open: number }, { active: string[] }>
+    | PromiseActorLogic<T | null, { active: string[] }>
+    | PromiseActorLogic<null, { active: string[] }>;
+  /** An external event def that wakes discovery early (webhook / `jr2 send` push seam). The pool
+   * serves it as a standing gate named "source"; the def IS the pool machine's vocabulary. */
+  wake?: EventDef;
+  /** Re-query cadence while parked, in ms — for sets that mutate underneath us. */
+  pollEvery?: number;
+};
+
+/** Declare a Source. Identity by design — the value IS the spec; this is the naming/typing seam. */
+export function source<T>(spec: SourceSpec<T>): SourceSpec<T> {
+  return spec;
+}
+
+/** How a pool run ends (its machine output). `items` maps itemId → the worker's output. */
+export type PoolOutput = { status: "drained" | "deadlocked"; items: Record<string, unknown> };
+
+/**
+ * How a pool is configured (ADR-0017, ADR-0033). `TInput` is what came through the pool's door:
+ * the PARSED schema when `input` declares one, and `unknown` when it does not — absence is
+ * permissive, so jr2 knows nothing and says so, exactly as `workspace()`'s door-less path does.
+ * A pool that is fed by something other than a caller may state what it is fed by annotating the
+ * mapper's parameter; for anything a caller starts, the honest fix is to declare `input`.
+ */
+export type PoolSpec<T, TInput = unknown> = {
+  /** The machine id (the workflow's name in the Console). Default "pool". */
+  id?: string;
+  /** The pool's OWN declared run input (ADR-0033) — what `cap` and `itemInput` read off the door,
+   * and what types their `input`. The WORKER's schema is deliberately not the door: workers are
+   * fed per-ITEM (the source item, or `itemInput`'s result), never the run body, so it describes
+   * nothing a starter sends. */
+  input?: z.ZodObject;
+  source: SourceSpec<T>;
+  /** Stable child identity: the spawn id, the active-set entry, the outcome key. */
+  itemId: (item: T) => string;
+  /** Max concurrent workers — a number, or derived from run input. Default 1. */
+  cap?: number | ((args: { input: TInput }) => number);
+  /** Map an item (+ run input) to the worker's input. Default: the item itself. */
+  itemInput?: (item: T, args: { input: TInput }) => unknown;
+  /** Terminal policy when the source runs dry and children settle. Only "final" exists today
+   * (jr semantics: runs END); a parking policy can be added when a workflow needs one. */
+  onDrained?: "final";
+};
+
+/**
+ * What `pool()` returns: the door a run of it starts with, the pool's own output, and the
+ * wrapper's actor slots — `worker` holding the worker's own type, because the pool is
+ * TRANSPARENT to its worker (ADR-0049), so `customize(machine, { agents })` on a pool-rooted
+ * workflow offers the WORKER's Agents and the composer never spells `worker`. {@link JR2Wrapper} is
+ * what marks it a jr2 wrapper: the transparency follows the marker, not the slot's spelling.
+ */
+export type PoolMachine<TWorker extends AnyStateMachine, TInput> = StateMachine<
+  any,
+  any,
+  any,
+  WrapperActors<"worker", TWorker, "next" | "gate">,
+  any,
+  any,
+  any,
+  any,
+  any,
+  TInput,
+  PoolOutput,
+  any,
+  any,
+  any
+> &
+  JR2Wrapper<TWorker>;
+
+type PoolCtx = {
+  runInput: Record<string, unknown>;
+  cap: number;
+  /** Item ids currently being worked — the spawn ids of live workers, and `next`'s exclusion. */
+  active: string[];
+  /** Settled workers' outputs, by item id — the pool's output collects them. */
+  items: Record<string, unknown>;
+  status?: "drained" | "deadlocked";
+};
+
+/** A claimed item, normalized (see {@link SourceNextResult}). */
+type Claim = { item: unknown | null; open: number };
+
+function normalizeClaim(output: unknown): Claim {
+  if (
+    output !== null &&
+    typeof output === "object" &&
+    "item" in output &&
+    typeof (output as { open?: unknown }).open === "number"
+  ) {
+    return output as Claim;
+  }
+  return { item: output, open: 0 };
+}
+
+/**
+ * Build the pool machine (ADR-0017). Returns a plain machine — the usual workflow ROOT
+ * (`export const machine = pool(...)`), but nestable as a child like any other. Its vocabulary is
+ * the wake def alone: the worker keeps its own (ADR-0011, ADR-0049).
+ */
+export function pool<TWorker extends AnyStateMachine, TSchema extends z.ZodObject>(
+  worker: TWorker,
+  spec: PoolSpec<any, z.infer<TSchema>> & { input: TSchema },
+): PoolMachine<TWorker, z.infer<TSchema>>;
+export function pool<TWorker extends AnyStateMachine, TInput = unknown>(
+  worker: TWorker,
+  spec: PoolSpec<any, TInput> & { input?: never },
+): PoolMachine<TWorker, TInput>;
+export function pool(worker: AnyStateMachine, spec: PoolSpec<any, any>): AnyStateMachine {
+  const wake = spec.source.wake;
+  const claimOf = (event: unknown): Claim => normalizeClaim((event as { output: unknown }).output);
+  const itemIdOf = (event: unknown): string => spec.itemId(claimOf(event).item as never);
+  /** `xstate.done.actor.<childId>` → the settled worker's item id. */
+  const doneChildOf = (event: unknown): string =>
+    ((event as { type: string }).type.match(/^xstate\.done\.actor\.(.+)$/) as RegExpMatchArray)[1]!;
+
+  const machine = setup({
+    actors: { worker, next: spec.source.next, gate },
+  }).createMachine({
+    id: spec.id ?? "pool",
+    context: ({ input }): PoolCtx => ({
+      runInput: (input ?? {}) as Record<string, unknown>,
+      cap: typeof spec.cap === "function" ? spec.cap({ input }) : (spec.cap ?? 1),
+      active: [],
+      items: {},
+    }),
+    // The wake seam: a standing gate for the whole run's life (root invokes stop only at final).
+    // The invoke id IS the gate's name (the id derives from the actor path — ADR-0011):
+    // `source` when the pool is the root, `<path>.source` nested — so two nested
+    // pools' wake gates cannot collide.
+    invoke: wake ? [{ id: "source", src: "gate", input: { accepts: [wake.name] } }] : [],
+    initial: "discovering",
+    on: {
+      // A worker settled, at any moment: collect its output, free its slot, stop the ref, and
+      // go look for more work. Internal to jr2 once — the consumer casts this used to force
+      // (`DoneActorEvent` unions, `assertEvent`) ship as documented patterns instead.
+      "xstate.done.actor.*": {
+        target: ".discovering",
+        actions: [
+          assign({
+            items: ({ context, event }) => ({
+              ...(context as unknown as PoolCtx).items,
+              [doneChildOf(event)]: (event as unknown as { output: unknown }).output,
+            }),
+            active: ({ context, event }) =>
+              (context as unknown as PoolCtx).active.filter((id) => id !== doneChildOf(event)),
+          }),
+          stopChild(({ event }) => doneChildOf(event)),
+        ],
+      },
+    },
+    states: {
+      discovering: {
+        // Saturated: don't even query — park until a worker settles (which re-enters here).
+        always: [{ guard: ({ context }) => context.active.length >= (context as PoolCtx).cap, target: "saturated" }],
+        invoke: {
+          id: "discover",
+          src: "next",
+          input: ({ context }) => ({ active: (context as PoolCtx).active }),
+          onDone: [
+            {
+              // Claimed: record it, spawn its worker (TOP-LEVEL spawnChild — the visualize
+              // trace), and loop for more. `reenter` re-invokes the query actor.
+              guard: ({ event }) => claimOf(event).item !== null,
+              target: "discovering",
+              reenter: true,
+              actions: [
+                assign({
+                  active: ({ context, event }) => [...(context as unknown as PoolCtx).active, itemIdOf(event)],
+                }),
+                spawnChild("worker", {
+                  id: ({ event }) => itemIdOf(event),
+                  input: ({ context, event }) => {
+                    const item = claimOf(event).item;
+                    const runInput = (context as unknown as PoolCtx).runInput;
+                    return (spec.itemInput ? spec.itemInput(item as never, { input: runInput }) : item) as never;
+                  },
+                }),
+              ],
+            },
+            // Nothing ready, workers live → healthy parking: their settling re-queries, as do
+            // the wake gate and the poll timer. This is jr's exit-3 "waiting" as a state.
+            { guard: ({ context }) => (context as PoolCtx).active.length > 0, target: "parked" },
+            // Idle + items exist that will never become ready by themselves → jr's exit 2.
+            {
+              guard: ({ event }) => claimOf(event).open > 0,
+              target: "deadlocked",
+              actions: assign({ status: () => "deadlocked" as const }),
+            },
+            // Idle + nothing anywhere → done (jr exit 0).
+            { target: "drained", actions: assign({ status: () => "drained" as const }) },
+          ],
+        },
+      },
+      saturated: {
+        // Every slot full: only a settling worker (the root `xstate.done.actor.*`) moves us.
+      },
+      parked: {
+        // Waiting on the world: wake early on push, or re-query on the poll cadence.
+        on: wake ? { [wake.name]: "discovering" } : {},
+        after: spec.source.pollEvery ? { [spec.source.pollEvery]: { target: "discovering" } } : {},
+      },
+      drained: { type: "final" },
+      deadlocked: { type: "final" },
+    },
+    // Outcome-in-context (the documented cast-free idiom): the two finals stamped `status`.
+    output: ({ context }): PoolOutput => ({
+      status: (context as unknown as PoolCtx).status ?? "drained",
+      items: (context as unknown as PoolCtx).items,
+    }),
+  });
+
+  // The pool's vocabulary is the pool's OWN — the wake def and nothing else (ADR-0011,
+  // ADR-0049). The worker's names stay the worker's: its gates and menus resolve against the
+  // Machine that invoked them, which is the worker, so merging them up here would only make a
+  // same-name/different-payload pair between two workers a collision that per-Machine scoping
+  // had already avoided.
+  if (wake) attachVocabulary(machine, new Map([[wake.name, wake]]));
+  // The pool is TRANSPARENT to its worker (ADR-0049), exactly as `workspace()` is to its body: a
+  // `customize(machine, { agents })` on a pool-rooted workflow means the worker's Agents, which
+  // is the only Machine under a pool that carries any.
+  attachWrapperBody(machine, "worker");
+  // The run input does NOT propagate from the worker (ADR-0033): a wrapper declares its own door,
+  // because what it feeds its child is not what a caller sends. Here it is sharpest — the pool
+  // never passes the run body to a worker at all, workers get items — so propagating the worker's
+  // schema would demand fields at the door the pool never uses, and zod's unknown-key stripping
+  // would silently DROP the pool-level fields `cap`/`itemInput` actually read. `workspace` is the
+  // milder case of the same species. A pool with a contract declares `spec.input`.
+  if (spec.input) attachInputSchema(machine, spec.input);
+  return machine;
+}

package/src/registration.ts

@@ -0,0 +1,340 @@
+// The internal registration table (ADR-0011): one structure behind both delivery dialects.
+// An Agent slot and `gate` register `address → { accepted event defs, deliver closure, meta }`;
+// the two HTTP surfaces (`/agents/:iid/*` for the Adapter, `/runs/:id/gates/*` for humans and
+// webhooks) are adapters over it — lookup, schema validation, delivery, discovery, and lifecycle
+// are implemented ONCE. The table is implementation structure, not vocabulary: workflows speak
+// only `defineEvent` / `agent` / `gate`.
+//
+// The dialects are also the AUTHORIZATION boundary (ADR-0013), which is why an agent registration
+// records its `sandbox`: a Sandbox token may deliver to `kind: "agent"` registrations whose Sandbox
+// is its own, and to nothing else. Never a Gate — a compromised Agent must not be able to approve
+// its own review — and never another Sandbox: `coding.ts`'s iids are derivable, so a run-scoped
+// credential would let one feature's coder inject a verdict into another feature's reviewer.
+//
+// Run identity reaches every registration mechanically through the xstate actor `system`: the
+// host binds each run's root system to a RunBinding at createActor time, and callback actors
+// (which receive `system`, shared by every actor in the tree at any nesting depth) resolve it
+// here. That is what makes gate ids run-scoped — `gate: "F-12"` in two concurrent runs cannot
+// collide — with zero workflow plumbing. The WeakMap is rendezvous keyed by per-run object
+// identity, not a swappable adapter (the distinction ADR-0011 draws for the demux).
+//
+// The binding carries run identity and host infrastructure and NO vocabulary: event names are
+// scoped to the Machine that declared them, not to the run (ADR-0011, ADR-0049), so
+// `resolveAccepts` reads them off the invoking Machine below and a nested Machine's names are
+// never the root's problem.
+
+import type { ActorSystem, AnyActorRef, AnyEventObject } from "xstate";
+import type { EventDef } from "@jr2/agent-protocol";
+import type { AgentAdmission } from "./actor.ts";
+import type { SandboxPort } from "./workspace.ts";
+import { invokingMachine, vocabularyOf } from "./vocabulary.ts";
+
+/** xstate doesn't export its internal AnyActorSystem; this matches what actors receive. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyActorSystem = ActorSystem<any>;
+
+/** A workflow event as delivered into a Machine: the def's name as `type`, plus its payload. */
+export type DeliveredEvent = { type: string } & Record<string, unknown>;
+
+/** One live registration: a state's declared surface, addressable by one external caller. */
+export type Registration = {
+  /** Table-wide unique address (see {@link gateAddress} / {@link agentAddress}). */
+  address: string;
+  runId: string;
+  /** Which dialect registered it — what `GET /runs/:id` lists as gates vs agent surfaces. */
+  kind: "gate" | "agent";
+  /** The caller-facing id within its dialect (the gate id, or the agent's instance id). */
+  id: string;
+  /** Accepted events, name→def — the validation scope AND the discovery listing. */
+  defs: Map<string, EventDef>;
+  /** Serializable caller/integration context (PR URL, title …) — rides the discovery listing. */
+  meta?: Record<string, unknown>;
+  /**
+   * The actor path below the run root ({@link actorPath}) — WHERE in the Machine this surface
+   * lives. Carried beside `id` because an authored gate id ("F-12") erases the path a derived id
+   * happens to spell, and a caller locating the invoking state (the Console's gate pin) must
+   * never parse ids. Gates always carry it; agent registrations don't need it today.
+   */
+  path?: string[];
+  /**
+   * The Sandbox this agent runs in — the scope of the Sandbox token that may deliver here
+   * (ADR-0013). Absent on gates, and on a workspace-less Agent turn (the mechanics tier's stub
+   * Harness runs on the host, in no Sandbox at all): those are the Instance token's business.
+   */
+  sandbox?: string;
+  /** Close over the invoking state's `sendBack`; delivery lands where the actor was invoked. */
+  deliver: (event: DeliveredEvent) => void;
+  /**
+   * The Machine that invoked this actor — `self._parent`, captured at registration. The menu was
+   * derived from THIS machine's transitions (ADR-0015), so it is the only snapshot whose guards
+   * can answer "would this event move anything" (see {@link wouldMove}). Absent on registrations
+   * that have no parent to name, which is why every read of it fails open.
+   */
+  invoker?: AnyActorRef;
+};
+
+/**
+ * Would this exact event move the invoking Machine? The guard question the derived menu cannot ask
+ * for itself: `deriveMenus` reads transition KEYS, so an event whose every transition is guarded
+ * false is on the menu regardless (ADR-0029).
+ *
+ * This is the AUTHORITATIVE form — delivery has the validated payload, so payload-reading guards
+ * answer on real data. {@link mayMove} is the menu's weaker form.
+ *
+ * **Fails open**: no invoker, or a guard that throws, reads as `true`. The failure modes are not
+ * symmetric. A wrong `true` offers a tool that does nothing — today's behavior, and recoverable,
+ * because the receipt now says so. A wrong `false` tells an Agent its work was rejected when the
+ * workflow would have accepted it, and nothing recovers from that.
+ *
+ * A transition that neither targets nor acts (`on: { X: {} }`) reads as false, matching xstate's
+ * own `can()`. Correct: a handler that does nothing is not a handler.
+ */
+export function wouldMove(invoker: AnyActorRef | undefined, event: AnyEventObject): boolean {
+  if (!invoker) return true;
+  try {
+    return invoker.getSnapshot().can(event);
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * COULD this event move the invoking Machine, judged before the Agent has picked its arguments?
+ * What the surface build can ask (ADR-0029) — there is no payload yet, so a guard reading one
+ * would answer on `undefined` and report a false "no".
+ *
+ * So the probe watches. The event goes in behind a Proxy that records any read outside `type`; a
+ * `false` is trusted only when the guard never looked at the payload, and a guard that did look is
+ * offered anyway and settled exactly at delivery by {@link wouldMove}. That keeps the two failure
+ * modes where they belong: a context-only guard (`rounds > 0`) filters precisely, and a
+ * payload-only guard (`event.verdict === "approved"`) is never silently hidden from the Agent.
+ *
+ * Verified against the pinned xstate: guards receive the object handed to `can()`, unspread and
+ * unwrapped, so the trap sees exactly the guard's own reads. If an xstate bump ever broke that, the
+ * trap would simply see nothing and this would degrade to filtering slightly more — hence the test
+ * that pins a payload-reading guard STAYING on the menu.
+ */
+export function mayMove(invoker: AnyActorRef | undefined, type: string): boolean {
+  if (!invoker) return true;
+  let readPayload = false;
+  const watch = (prop: string | symbol): void => {
+    if (typeof prop === "string" && prop !== "type") readPayload = true;
+  };
+  const probe = new Proxy({ type } as Record<string, unknown>, {
+    get(target, prop, receiver) {
+      watch(prop);
+      return Reflect.get(target, prop, receiver);
+    },
+    has(target, prop) {
+      watch(prop);
+      return Reflect.has(target, prop);
+    },
+  });
+  try {
+    if (invoker.getSnapshot().can(probe as AnyEventObject)) return true;
+  } catch {
+    return true;
+  }
+  return readPayload;
+}
+
+/** Delivery target absent (unknown address, settled run, exited state) — the one catch point. */
+export class UnknownAddressError extends Error {}
+/** Delivery body rejected (unaccepted name, or payload failing the named schema). */
+export class EventValidationError extends Error {}
+
+/**
+ * The actor path below the run's root: every id from the root's children down to `ref` itself,
+ * root-most first. The root is excluded because its id is generated per process — everything
+ * below it is author-named and stable across restore (ADR-0016). One walk for both address
+ * kinds: `mintIid` builds iids from it, `gate` derives default gate ids from it, so the two
+ * cannot drift.
+ */
+export function actorPath(ref: AnyActorRef): string[] {
+  const segments: string[] = [];
+  for (let r: AnyActorRef | undefined = ref; r?._parent; r = r._parent) segments.unshift(r.id);
+  return segments;
+}
+
+/** The address of a run's gate: gate ids are run-scoped by construction (ADR-0011). */
+export function gateAddress(runId: string, gate: string): string {
+  return `gate/${runId}/${gate}`;
+}
+
+/** The address of an agent instance's surface (`/agents/:iid/*`): iids are globally unique. */
+export function agentAddress(instanceId: string): string {
+  return `agent/${instanceId}`;
+}
+
+export class RegistrationTable {
+  private readonly byAddress = new Map<string, Registration>();
+
+  /** Register a live surface; returns its disposer (actors call it from their stop cleanup). */
+  register(reg: Registration): () => void {
+    if (this.byAddress.has(reg.address)) {
+      throw new Error(
+        `registration address "${reg.address}" is already live (two concurrent registrations share an id)`,
+      );
+    }
+    this.byAddress.set(reg.address, reg);
+    return () => {
+      // Dispose only our own entry — a re-registration under the same address must not be
+      // clobbered by a stale disposer running late (dev reload, restore races).
+      if (this.byAddress.get(reg.address) === reg) this.byAddress.delete(reg.address);
+    };
+  }
+
+  lookup(address: string): Registration | undefined {
+    return this.byAddress.get(address);
+  }
+
+  /** All live registrations for one run — the `GET /runs/:id` discovery listing. */
+  byRun(runId: string): Registration[] {
+    return [...this.byAddress.values()].filter((r) => r.runId === runId);
+  }
+
+  /**
+   * Validate and deliver one event to an address: the shared behavior both dialect adapters
+   * call. Unknown address / unaccepted name / bad payload throw typed errors the adapters map
+   * to their wire (404 / 400, MCP tool errors). The payload is parsed by the named def's
+   * schema, so what lands in the Machine is exactly the validated shape.
+   */
+  deliver(address: string, type: string, payload: unknown): void {
+    const reg = this.byAddress.get(address);
+    if (!reg) throw new UnknownAddressError(`no live registration at "${address}"`);
+    const def = reg.defs.get(type);
+    if (!def) {
+      throw new EventValidationError(
+        `"${reg.id}" does not accept "${type}" (accepts: ${[...reg.defs.keys()].join(", ") || "nothing"})`,
+      );
+    }
+    const parsed = def.input.safeParse(payload ?? {});
+    if (!parsed.success) {
+      throw new EventValidationError(`invalid "${type}" payload: ${parsed.error.message}`);
+    }
+    reg.deliver({ type: def.name, ...parsed.data });
+  }
+}
+
+/** What a callback actor needs from its host: run identity, the table, and the host's ports. */
+export type RunBinding = {
+  runId: string;
+  workflow: string;
+  table: RegistrationTable;
+  /** The host's Sandbox backend, when it has a cluster (`workspace()` resolves it here —
+   * one cluster per orchestrator instance, so it is host infrastructure like the table). */
+  sandbox?: SandboxPort;
+  /**
+   * The Instance Harness base URL (ADR-0031) — the deterministic Service DNS a
+   * `workspace: "none"` Turn is admitted at. Deployed instances derive it from their namespace;
+   * absent, a `"none"` Agent without an explicit `endpoint` fails loudly.
+   */
+  instanceHarness?: string;
+  /**
+   * Record an Agent invocation's durable admission in the host ledger (ADR-0016): persisted
+   * beside the snapshot in the same RunBlob save, keyed by iid (globally unique, so the map is
+   * flat). Optional so a bare unit-test binding can omit it — then admissions simply are not
+   * durable.
+   */
+  recordAdmission?: (instanceId: string, admission: AgentAdmission) => void;
+  /**
+   * Surface absorbed-retry telemetry on the run feed (ADR-0016): attempts are observable, but
+   * as `{ child, attempt }` — state-key-class data, never iids (ADR-0014's line holds on the
+   * open feed).
+   */
+  telemetry?: (event: RetryTelemetry) => void;
+  /**
+   * Put a Turn marker on the run's feed (ADR-0023): an Agent turn reports its admission and its
+   * settlement pick, so the run's narrative can name what a Turn hosted elsewhere decided.
+   * Host-supplied; absent (bare unit-test bindings), turns leave no markers.
+   */
+  marker?: (event: TurnMarker) => void;
+  /**
+   * Attach the run-narrative echo to a Workspace's Harness (ADR-0023): the host replays the
+   * run's feed-so-far to `endpoint`, then tees live; returns the detach. Called by `workspace()`'s
+   * registrar — the same restore-safe seat the ambient handles ride — and scoped to the OWNING
+   * run by construction: the binding is per-run, so a sibling run's feed is unreachable.
+   * Host-supplied; absent = no echo.
+   */
+  echo?: (endpoint: string) => () => void;
+  /**
+   * The HOST is ending this run for its own reasons (ADR-0024). An Agent invocation ending
+   * normally ends the Agent's turn — the state stopped waiting — but `RunHost.stop()` is the one
+   * ending that must leave the durable submission alive, because ADR-0007's restore re-attaches
+   * to it. The host cannot be INFERRED (process shutdown stops no actors, and restore is a fresh
+   * process), so it says so here, before it stops the actor.
+   */
+  hostStopping?: boolean;
+  /**
+   * iid → the abort still in flight for it (ADR-0024). The Agent actor fills this on the way out and
+   * waits on it before admitting, so an abort can never overtake the next turn on the same
+   * instance — flue QUEUES per instance, and an abort that lost that race would settle the new
+   * submission before it ran. Created on demand: the ordering must hold for ANY binding, not only
+   * one the host remembered to equip.
+   */
+  pendingAborts?: Map<string, Promise<void>>;
+};
+
+/** One absorbed-retry attempt (a no-signal nudge), as the run feed carries it. */
+export type RetryTelemetry = { kind: "retry"; child: string; attempt: number; reason: string };
+
+/**
+ * ADR-0023's Turn markers, as the run feed carries them: a Turn admitted on a Harness (the Agent
+ * and its framing), and the settlement pick that ended it. `endpoint` names the HOSTING Harness —
+ * what lets the echo tee keep "markers, not mirrors": a marker whose Turn ran AT the echo's own
+ * target is dropped there, because that pod's log already carries the whole transcript. Feed
+ * data of the Instance-token class (the prompt is working data): markers ride the per-run feed
+ * and the echo, never ADR-0014's open band.
+ */
+export type TurnMarker =
+  | { kind: "admission"; agent: string; endpoint: string; prompt: string }
+  | { kind: "pick"; agent: string; endpoint: string; event: string; payload?: Record<string, unknown> };
+
+const bindings = new WeakMap<AnyActorSystem, RunBinding>();
+
+/** Host-side: bind a run's actor system to its identity, before the actor starts. */
+export function bindRun(system: AnyActorSystem, binding: RunBinding): void {
+  bindings.set(system, binding);
+}
+
+/** The bound run's id, or undefined outside a jr2 host — the SOFT read `jr2Setup`'s iid minting
+ * uses, so a machine stays constructible and provide()-testable with no host at all. */
+export function boundRunId(system: AnyActorSystem): string | undefined {
+  return bindings.get(system)?.runId;
+}
+
+/** Actor-side: resolve the run this actor tree belongs to. Throws outside a jr2 host. */
+export function runBindingOf(system: AnyActorSystem): RunBinding {
+  const binding = bindings.get(system);
+  if (!binding) {
+    throw new Error(
+      "no run binding for this actor system — gate and Agent slots only run under a jr2 RunHost " +
+        "(unit tests: bindRun(actor.system, …) before start)",
+    );
+  }
+  return binding;
+}
+
+/**
+ * Resolve `accepts` names against the vocabulary of the Machine that INVOKED this actor
+ * (ADR-0011, ADR-0049). Names are local to their Machine — `coding`'s `approve` and `release`'s
+ * `approve` may carry different payloads, and one run may hold both — so the scope is
+ * `self._parent.logic`, never a run-wide set. An unlisted name fails at invoke time, naming the
+ * Machine and its declared set.
+ */
+export function resolveAccepts(self: AnyActorRef, accepts: readonly string[]): Map<string, EventDef> {
+  const machine = invokingMachine(self);
+  const vocabulary = (machine && vocabularyOf(machine)) ?? new Map<string, EventDef>();
+  const defs = new Map<string, EventDef>();
+  for (const name of accepts) {
+    const def = vocabulary.get(name);
+    if (!def) {
+      throw new Error(
+        `machine "${machine?.id ?? "(no invoking machine)"}" does not declare event "${name}" ` +
+          `(declared: ${[...vocabulary.keys()].join(", ") || "none — pass its def to jr2Setup({ events })"})`,
+      );
+    }
+    defs.set(name, def);
+  }
+  return defs;
+}