@jr2/orchestrator 0.3.0 → 0.5.1

package/src/parts.ts

@@ -16,8 +16,9 @@
 //     Instance Harness converges when any of them declares `workspace: "none"`, every `file:`
 //     image context a Machine ships is built and content-tagged, every BOUND Repo is known before
 //     a run can ask for it, an OPEN part — a Repo Slot with no url, an Agent with no model
-//     (ADR-0054) — is refused before anything is built, and whether any registered Machine
-//     composes a Sandbox at all is the data-plane switch. None of these can read
+//     (ADR-0054) — is refused before anything is built, every Size a `workspace()` states is split
+//     and held to the Harness floor (ADR-0060), and whether any registered Machine composes a
+//     Sandbox at all is the data-plane switch. None of these can read
 //     an invoke's `input` (it is a function — dials are not statically recoverable), and none
 //     needs to: identity lives in the definition, the image and the slots are options, and all are
 //     values ON the Machine. A per-run slot is a function too, and the walk reports nothing for
@@ -33,6 +34,13 @@
 //     xstate rewrites to a generated key and keeps only on the raw config node. Nothing jr2 owns
 //     arrives this way any more; the walk keeps it because an AUTHOR may still write one.
 //
+// A PART written inline is refused, not walked (`refuseInlineParts`): an `agent()`, an Effect
+// (ADR-0067) or a `workspace()` on an `invoke.src` has no author-written name. xstate's generated
+// key (`xstate.invoke.<n>.<state id>`) moves when a state is renamed, so the ledger, the Console doc
+// and `jr2 up`'s report would name it by a number, and `customize()` — xstate's `provide`, keyed on
+// `actors` — could not reach it at all. A slot key is the one name every reader shares (ADR-0049),
+// so a Part is a key of `actors`, and the refusal says how to write it.
+//
 // Deliberately NOT a `provide()`-aware read: the walk runs on the registered Machine, which is the
 // object the run will start, so a `customize()` clone is walked as itself and a test seam's fake
 // (unbranded) contributes nothing.
@@ -41,9 +49,16 @@ import { basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { AnyActorRef, AnyStateMachine, StateNode, UnknownActorLogic } from "xstate";
 import { isAgent, isOpenAgent, type AgentDeclaration } from "./agent.ts";
+import { argvText, isEffect, placementOf, type EffectParts, type Placement } from "./effect.ts";
+import { effectBindingLine, openPartsOf, type OpenEffectPart } from "./open-effect.ts";
+import { isFailSlot } from "./fail.ts";
 import { isImageContext } from "./images.ts";
+import { isOpenBody, openBodyDeclarationOf, type OpenBodyDeclaration } from "./open-body.ts";
 import { open } from "./open.ts";
 import { repoIdentity } from "./repo-identity.ts";
+import { refuseUnroutedAgentFault } from "./mechanism-routes.ts";
+import { refuseLostOutput } from "./run-output.ts";
+import { userSeatOf, type Size, type UserContainer } from "./size.ts";
 
 // --- Repo Slots (ADR-0051) ---------------------------------------------------------------------
 // A `workspace()` names each Repo it attaches under a SLOT — the Machine's own word for it, the
@@ -51,7 +66,7 @@ import { repoIdentity } from "./repo-identity.ts";
 // is one of three states, and the walk tells them apart without evaluating anything. A Machine
 // whose body names no slot — it enumerates whatever is attached — declares the whole MAP Open
 // instead (`repos: open`): the composer names every slot, in an order the Machine may give a
-// meaning to. Open at the map is the same word as Open at a slot, one level up (CONTEXT.md).
+// meaning to. Open at the map is the same word as Open at a slot, one level up (ADR-0051).
 
 // The sentinel itself lives in open.ts, a module with nothing else in it: since ADR-0054 it marks
 // an Agent's model too, and agent.ts must read it without importing this file (the walk imports
@@ -59,15 +74,103 @@ import { repoIdentity } from "./repo-identity.ts";
 // meets it first, and `import { open } from "@jr2/orchestrator"` is the only spelling anyone writes.
 export { open } from "./open.ts";
 
-/** What a Repo Slot resolves to (CONTEXT.md "Binding"): the url, and the base the branch
- * Worktree is cut from — absent, the Repo's own default branch. */
-export type Binding = { url: string; ref?: string };
+/**
+ * The repository of a Repo Slot: `{ url, ref }`. `url` is the Repo's git url. `ref` is the branch
+ * or commit that the branch Worktree starts from; absent, the Repo's default branch. Where only a
+ * url is needed, a string is enough.
+ *
+ * `workspace()` and `customize()` refuse:
+ * - an empty `url`: ``<where>: Repo Slot "<slot>" is bound to an empty url (got <value>) — a slot
+ *   is `open`, a url, `{ url, ref? }`, or a mapper `({ input }) => url | { url, ref? }` over the
+ *   door (ADR-0051).``
+ * - an empty `ref`: the same text, with `bound with an empty ref` in place of `bound to an empty
+ *   url`.
+ * - a url that names no Repo, such as a relative path: ``<where>: Repo Slot "<slot>" binds
+ *   "<url>", which names no Repo — <reason> (ADR-0051).``
+ *
+ * @example
+ * ```ts
+ * import { jr2Setup, workspace, type Binding } from "@jr2/orchestrator";
+ *
+ * const app: Binding = { url: "https://github.com/you/app.git", ref: "release-2" };
+ *
+ * const body = jr2Setup().createMachine({
+ *   id: "body",
+ *   initial: "done",
+ *   states: { done: { type: "final" } },
+ * });
+ *
+ * export const machine = workspace(body, {
+ *   repos: { app },
+ *   spec: () => ({ branch: "jr2/hotfix" }),
+ * });
+ * ```
+ *
+ * @see docs/concepts/workspaces.md
+ * @see docs/reference/decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md
+ */
+// What a Repo Slot resolves to (GLOSSARY.md "Binding").
+export type Binding = {
+  /** The Repo's git url. */
+  url: string;
+  /** The branch or commit that the branch Worktree starts from. Default: the Repo's default
+   * branch. */
+  ref?: string;
+};
 
+// Bound and open are what `jr2 up` can see; per-run is the run's business, fenced at attach by
+// `git.credentials` (ADR-0051).
 /**
- * One Repo Slot's value: BOUND (a url, or `{ url, ref? }`), OPEN (the {@link open} sentinel —
- * someone downstream binds it), or PER-RUN (a mapper over the wrapper's door, so a run input — a
- * ticket field — decides). Bound and open are what `jr2 up` can see; per-run is the run's business,
- * fenced at attach by `git.credentials` (ADR-0051).
+ * The value of one Repo Slot in `workspace({ repos })`. One of:
+ * - a url, or a {@link Binding} `{ url, ref }`: the Machine names the Repo.
+ * - {@link open}: the Instance that registers the Machine binds it with `customize()`. `jr2 up`
+ *   refuses a Workflow that leaves it open: ``refusing: workflow "<name>" leaves Repo Slot
+ *   "<slot>" open — bind it where the Machine is registered: export const machine =
+ *   customize(<import>, …)  (ADR-0051)``, with the whole `customize` line to paste.
+ * - a function of the run input, `({ input }) => url` or a {@link Binding}: each run chooses. The
+ *   url must match an entry of `git.credentials` in `jr2.config.ts`, or the run cannot use it.
+ *
+ * The key of the slot is a directory name under `/work`. It starts with a letter, and
+ * `workspace()` and `customize()` refuse a key that does not: ``<where>: Repo Slot key "<key>" is
+ * not a directory name — a slot becomes `/work/<slot>` and its order matters, so it starts with a
+ * letter and matches /^[A-Za-z][A-Za-z0-9._-]*$/ (ADR-0051).`` They refuse a value of another
+ * shape: ``<where>: Repo Slot "<slot>" is <what> — a slot is `open`, a url, `{ url, ref? }`, or a
+ * mapper `({ input }) => url | { url, ref? }` over the door (ADR-0051).``
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { jr2Setup, open, workspace, type RepoSlot, type Workspaced } from "@jr2/orchestrator";
+ *
+ * const runInput = z.object({ service: z.string() });
+ * type RunInput = z.infer<typeof runInput>;
+ *
+ * const service: RepoSlot<RunInput> = ({ input }) => `https://github.com/you/${input.service}.git`;
+ *
+ * const body = jr2Setup({
+ *   types: {} as { input: Workspaced<RunInput, "service" | "docs" | "config"> },
+ * }).createMachine({
+ *   id: "body",
+ *   initial: "done",
+ *   states: { done: { type: "final" } },
+ * });
+ *
+ * // A Machine for a package: the Instance that registers it binds `config`.
+ * export const deploy = workspace(body, {
+ *   input: runInput,
+ *   repos: {
+ *     service,
+ *     docs: "https://github.com/you/docs.git",
+ *     config: open,
+ *   },
+ *   spec: ({ input }) => ({ branch: `deploy/${input.service}` }),
+ * });
+ * ```
+ *
+ * @see docs/concepts/workspaces.md
+ * @see docs/guides/bind-open-parts.md
+ * @see docs/guides/give-the-cluster-git-credentials.md
+ * @see docs/reference/decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md
  */
 export type RepoSlot<TInput = unknown> =
   | typeof open
@@ -146,11 +249,20 @@ export function assertRepoSlot(where: string, slot: string, value: unknown): ass
 export type SandboxParts = {
   /** The Sandbox Image. Absent → the Instance's `images/default`, then the stock Harness. */
   image?: string;
-  /** The User Container's image (ADR-0005). Absent → the pod has no third container. */
-  user?: string;
+  /** The User Container (ADR-0005): its image, or `{ image, resources }` when the Machine states
+   * its split of the Size (ADR-0060). Absent → the pod has no third container. */
+  user?: string | UserContainer;
   /** The Repo Slots, in declaration order — which the handles keep (ADR-0051) — or
    * {@link open} for a map the composer fills whole. */
   repos: Record<string, RepoSlot> | typeof open;
+  /** The Size the Machine states (ADR-0060) — the `workspace()`'s, with any `customize()` layered
+   * over it. Absent → the Instance's `sandbox.resources`, then the kit default. */
+  resources?: Size;
+  /** The Held secrets this Workspace's pod gets beside its Agents' model keys (ADR-0059): names of
+   * the `secrets` list. Naming is placement — no other pod gets a name for being listed here. */
+  secrets?: string[];
+  /** The Sandbox Effector's image (ADR-0068). Absent → the Sandbox Image. */
+  effector?: { image: string };
 };
 
 // The stamps below are written ON `machine.config` under `Symbol.for` keys, never held in a
@@ -178,11 +290,12 @@ export function sandboxPartsOf(machine: AnyStateMachine | undefined): SandboxPar
 
 /** Does this Machine COMPOSE a Sandbox — i.e. is it a `workspace()` wrapper? Distinct from
  * `sandboxPartsOf(m)` naming no image: a wrapper that names neither image still owns the two
- * seats, which is what `customize({ image })` retunes (ADR-0049) — and it always carries at least
- * one Repo Slot (ADR-0051). Also the data-plane switch, read off the walk: an Instance needs
- * Sandboxes exactly when a registered Machine composes one. */
+ * seats, which is what `customize({ image })` retunes (ADR-0049) — and it may carry no Repo Slot
+ * at all (ADR-0051). Also the data-plane switch, read off the walk: an Instance needs
+ * Sandboxes exactly when a registered Machine composes one. A logic with no `config` (an Effect's,
+ * ADR-0067) composes none. */
 export function composesSandbox(machine: AnyStateMachine): boolean {
-  return (machine.config as Stamped)[SANDBOX_PARTS] !== undefined;
+  return (machine.config as Stamped | undefined)?.[SANDBOX_PARTS] !== undefined;
 }
 
 // The slot a jr2 WRAPPER is transparent to (ADR-0049): `workspace()`'s `body`, `pool()`'s
@@ -295,8 +408,43 @@ export type CarriedRepo = { url: string; ref?: string; identity: string; key: st
  */
 export type OpenSlot = { slot: string | undefined; path: readonly string[] | undefined };
 
-/** Which kind of Open part a fix line binds — the two `customize()` keys (ADR-0051, ADR-0054). */
-export type OpenPart = "repo" | "agent";
+/**
+ * One hop of a placement route (ADR-0059, ADR-0068): the `actors` slot key a child is invoked by,
+ * or — for a plain child Machine written INLINE on a state's invoke — xstate's generated invoke
+ * src for that hop (`xstate.invoke.<index>.<state id>`), which the static walk computes from the
+ * state node and the run reads off the live child. An inline hop is an object, so it can never
+ * equal a slot key.
+ */
+export type RouteHop = string | { readonly inline: string };
+
+/**
+ * Where a placement sits: the chain of hops from the registered root down to it, a wrapper's
+ * transparent body skipped as {@link OpenSlot}'s `path` skips it. Unlike `path`, a route goes on
+ * past an inline Machine, so every placement — a Workspace's pod, an Effect — has a route of its
+ * own, and the pod keys of two Workspaces never collide. Where `path` is defined the route is that
+ * same list of slot keys, so a pod key reached by slot keys alone is what it was.
+ */
+export type PlacementRoute = readonly RouteHop[];
+
+/** The hop xstate gives the `index`-th invoke of state node `stateId` when its `src` is inline. */
+export const inlineHop = (index: number, stateId: string): RouteHop => ({
+  inline: `xstate.invoke.${index}.${stateId}`,
+});
+
+/** A route as a human reads it, for a label: ` → "review"`, ` → invoked inline in state "w.a"`. */
+export function routeText(route: PlacementRoute): string {
+  return route
+    .map((hop) =>
+      typeof hop === "string"
+        ? ` → "${hop}"`
+        : ` → invoked inline in state "${hop.inline.replace(/^xstate\.invoke\.\d+\./, "")}"`,
+    )
+    .join("");
+}
+
+/** Which kind of Open part a fix line binds — a Repo Slot (`repos`, ADR-0051), an Agent's model
+ * (`agents`, ADR-0054), or an Effect's url, argv or secret (`effects`, ADR-0054). */
+export type OpenPart = "repo" | "agent" | OpenEffectPart;
 
 /**
  * The `customize` line that binds an Open part, given the identifier the composer holds the
@@ -305,22 +453,26 @@ export type OpenPart = "repo" | "agent";
  * `customize(top, { actors: { review: { repos: { target: "<url>" } } } })`. The same nesting
  * `customize()` accepts, so the line pastes.
  *
- * An Agent binds through `agents` instead, and the placeholder is the model spelling ADR-0018
+ * An Agent binds through `agents` instead, and the sample value is the model spelling ADR-0018
  * demands — `<provider>/<model>`, not a bare model id, since the prefix is what picks the
- * endpoint. `repo` is the default because a Repo Slot was the first Open part and reads as the
- * unmarked case. An Open MAP has no slot to print (`slot` undefined): the placeholder `<slot>`
+ * endpoint. An Effect binds through `effects`: its url, its argv, its secret, or one object with two
+ * of them for an Effect with two Open parts (open-effect.ts). `repo` is the
+ * default because a Repo Slot was the first Open part and reads as the
+ * unmarked case. An Open MAP has no slot to print (`slot` undefined): the sample `<slot>`
  * stands where the composer's own word goes, since choosing it is the composer's half of the line.
  */
 export function customizeLine(
   machine: string,
   path: readonly string[],
   slot: string | undefined,
-  part: OpenPart = "repo",
+  part: OpenPart | readonly OpenEffectPart[] = "repo",
 ): string {
   const binds =
     part === "agent"
       ? `{ agents: { ${slot}: { model: "<provider>/<model>" } } }`
-      : `{ repos: { ${slot ?? "<slot>"}: "<url>" } }`;
+      : part === "repo"
+        ? `{ repos: { ${slot ?? "<slot>"}: "<url>" } }`
+        : effectBindingLine(slot ?? "<slot>", part);
   const inner = path.reduceRight((parts, key) => `{ actors: { ${key}: ${parts} } }`, binds);
   return `customize(${machine}, ${inner})`;
 }
@@ -329,8 +481,10 @@ export function customizeLine(
  * The runtime twin of the walk's `path`: the actor-slot chain from a run's root actor down to
  * `actor` (its own `src` included), read off the live actor tree — each `src` is the slot key it
  * was invoked or spawned as, and a wrapper's transparent body is skipped by the same record
- * ({@link wrapperBodyOf}) the walk skips it by. `undefined` past an inline-invoked actor, whose
- * `src` is the logic itself and names no slot.
+ * ({@link wrapperBodyOf}) the walk skips it by. `undefined` past an inline-invoked actor, as the
+ * walk's `path` is: such an actor names no slot. xstate gives an inline `invoke.src` a generated
+ * string (`xstate.invoke.<n>.<state id>`) that is no key of its parent's `actors`, so the test is
+ * that registry, not the type of `src`; inline logic passed to `spawn` keeps the logic as `src`.
  */
 export function actorSlotPath(actor: AnyActorRef | undefined): string[] | undefined {
   const path: string[] = [];
@@ -338,14 +492,128 @@ export function actorSlotPath(actor: AnyActorRef | undefined): string[] | undefi
     const src = (node as { src?: unknown }).src;
     if (typeof src !== "string") return undefined;
     const parent = asMachine((node._parent as { logic?: unknown }).logic);
+    if (parent && !Object.hasOwn(parent.implementations.actors, src)) return undefined;
     if (!parent || wrapperBodyOf(parent) !== src) path.unshift(src);
   }
   return path;
 }
 
+/**
+ * The runtime twin of the walk's `route` (ADR-0059): the placement route from a run's root actor
+ * down to `actor`, read off the live actor tree. A child invoked by a slot key adds that key, as
+ * {@link actorSlotPath} does; a plain Machine invoked inline adds xstate's generated src as an
+ * inline hop, which the walk computes from the state node — so `jr2 up` and the provision derive
+ * one pod key. Never undefined: an actor the walk cannot see — a Machine object handed to
+ * `spawnChild`, whose `src` is the logic itself — is refused with the slot form.
+ */
+export function actorRoute(actor: AnyActorRef | undefined): RouteHop[] {
+  const route: RouteHop[] = [];
+  for (let node = actor; node?._parent; node = node._parent) {
+    const src = (node as { src?: unknown }).src;
+    const parent = asMachine((node._parent as { logic?: unknown }).logic);
+    if (typeof src === "string" && (!parent || Object.hasOwn(parent.implementations.actors, src))) {
+      if (!parent || wrapperBodyOf(parent) !== src) route.unshift(src);
+    } else if (typeof src === "string" && /^xstate\.invoke\.\d+\./.test(src)) {
+      route.unshift({ inline: src });
+    } else {
+      throw new Error(
+        `actor "${node.id}" was spawned from a logic object, which no walk can see, so jr2 up placed nothing ` +
+          "for what it composes — a Part is reached through keys of actors, so it has a name that the ledger, " +
+          'the report and customize() share: actors: { <name>: <machine> }, then spawnChild("<name>") (ADR-0059)',
+      );
+    }
+  }
+  return route;
+}
+
+/**
+ * One `workspace()` a Machine composes, and the Size it states (ADR-0060) — what `jr2 up` resolves
+ * against the Instance default and splits, so a split that leaves the Harness below its floor is
+ * refused at the converge rather than at the first provision, and a Size no Sandbox node could hold
+ * is warned about. Located like an {@link OpenSlot}: `path` is the `customize()` route to it.
+ */
+export type CarriedSize = {
+  path: readonly string[] | undefined;
+  /** The placement route to it (ADR-0059). */
+  route: PlacementRoute;
+  /** The Machine's Size, as stated; absent when it states none. */
+  resources?: Size;
+  /** The User Container's split, as stated; absent when it states none. */
+  user?: Size;
+};
+
+/** One Effect slot a Machine carries (ADR-0067), by its slot key and the `customize()` route to its
+ * Machine, with the plain data `jr2 up` prints: the kind, where it runs, a command's argv (an argv
+ * slot reads `<name>`), its timeout, and the Repo Slot whose Worktree is its cwd, when it names one.
+ * `open` names the parts a package left Open (ADR-0054) — an http url, which then has no target
+ * yet, or a command's argv, which reads `<open>`, and a secret its auth, a header or its env names
+ * as `secret(open)`, which names no secret yet — and the walk reports them for `jr2 up` to refuse;
+ * once `customize()` binds them, the slot carries the bound Effect and `open` is absent. */
+export type CarriedEffect = {
+  name: string;
+  path: readonly string[] | undefined;
+  /** The placement route to its Machine (ADR-0068): what its placement key reads, never `path`. */
+  route: PlacementRoute;
+  placement: Placement;
+  timeoutMs: number;
+} &
+  /** A command; one whose env names a secret runs in the Sandbox Effector (ADR-0067). */
+  (| {
+        kind: "command";
+        argv: string[];
+        slot?: string;
+        secrets?: string[];
+        pin?: true;
+        open?: Array<"argv" | "secret">;
+      }
+    /** An http Effect (ADR-0068): its method, its fixed target, and the secrets it names — what
+     * places each secret, and what its Effector's config allows. `file`: its body is a Worktree
+     * file (ADR-0067), so it runs in its Workspace's Sandbox Effector, on Repo Slot `slot` when named.
+     * An Open url has no target, and names only the secrets its headers and auth name. */
+    | {
+        kind: "http";
+        method: string;
+        target?: { scheme: "http" | "https"; host: string; port: number };
+        secrets: string[];
+        idempotent: boolean;
+        file?: true;
+        slot?: string;
+        open?: Array<"url" | "secret">;
+      }
+    /** A push (ADR-0067, ADR-0051): the Workspace's branch to its Repo Slot's Binding. It names no
+     * secret: `jr2 up` resolves its credential through `git.credentials`. */
+    | { kind: "push"; slot?: string; sign: boolean; squash: boolean; force: boolean; pin: boolean; secrets: string[] }
+    /** A dispatch (ADR-0071): the Workflow it starts a run of, as `jr2 run` names it, whether it
+     * waits, and — toward another Orchestrator — the target's origin as an http target and its
+     * token as the one secret (placed in the Instance Effector beside the http Effects). No target:
+     * it runs in the Orchestrator's own process and names no secret. `input`: the slot's input
+     * schema as JSON Schema, what the walk compares with the callee's door; absent, the door alone
+     * checks. An Open target has no target and no secret yet. */
+    | {
+        kind: "dispatch";
+        workflow: string;
+        wait: boolean;
+        target?: { scheme: "http" | "https"; host: string; port: number };
+        secrets: string[];
+        input?: Record<string, unknown>;
+        open?: Array<"target">;
+      }
+  );
+
+/** One state that can fail the run (ADR-0073): it invokes a `fail()` slot. `state` is the state's
+ * id, `machine` the id of its Machine, `slot` the slot key it invokes, and `path` the `customize()`
+ * route to its Machine, as an {@link OpenSlot}'s. Static, as a Gate or an Effect is: the walk reads
+ * it, and `jr2 up`, `jr2 check` and the Machine doc list it. */
+export type CarriedFailure = { machine: string; state: string; slot: string; path: OpenSlot["path"] };
+
 /** Everything the registered Machines carry that a converge or a boot must act on. */
 export type CarriedParts = {
   agents: CarriedAgent[];
+  /** Every state that invokes a `fail()` slot (ADR-0073), in walk order, nested Machines too. */
+  failures: CarriedFailure[];
+  /** Every Effect slot, in walk order — one per Machine and slot key, at the first route the walk
+   * reached its Machine by. The placement reads {@link placedEffectsOf}: one per route. */
+  effects: CarriedEffect[];
   images: CarriedImage[];
   /** Every bound Repo, deduped by identity, in walk order. */
   repos: CarriedRepo[];
@@ -355,8 +623,32 @@ export type CarriedParts = {
   /** Every Agent whose model is still Open (ADR-0054), in walk order — the same refusal, by the
    * same route, and the reason these are two lists rather than one: the fix lines differ. */
   openAgents: OpenSlot[];
+  /** Every Effect whose url, argv or secret is still Open (ADR-0054), in walk order — the same
+   * refusal, by the same route; `parts` says which line binds it: one object for both of two. */
+  openEffects: Array<OpenSlot & { parts: OpenEffectPart[] }>;
+  /** Every `workspace()` reached, with the Size it states, in walk order (ADR-0060). */
+  sizes: CarriedSize[];
   /** Whether any Machine reached, at any depth, composes a Sandbox — the data-plane switch. */
   composesSandbox: boolean;
+  /**
+   * Every Open body slot (ADR-0070), in walk order, with its declaration: what it lends, what a Chart
+   * may define, its ceilings. The one Open part a run binds, not a composer, so it is never in an
+   * Open list: an Open body whose lent names did not resolve never reaches the walk (createMachine
+   * refused it).
+   */
+  openBodies: Array<{ slot: string; declaration: OpenBodyDeclaration; path: OpenSlot["path"] }>;
+  /**
+   * Every model a key is placed and a provider preflighted for: each bound Agent's, and each model
+   * an Open body allows a Chart's own Agents (ADR-0070: a minted model is a door refusal, never a
+   * 401 mid-run). Deduped, sorted.
+   */
+  models: string[];
+  /**
+   * The Instance Harness is needed (ADR-0031): an Agent declares `workspace: "none"`, or an Open
+   * body allows it. `models` are the models its Turns may run: those Agents', and those Open bodies'
+   * allowed ones. Absent when nothing needs it.
+   */
+  instanceHarness?: { models: string[] };
 };
 
 /** A machine actor, told apart from a promise/callback/observable one by having a state tree.
@@ -366,16 +658,49 @@ export function asMachine(logic: unknown): AnyStateMachine | undefined {
   return (logic as AnyStateMachine | undefined)?.root ? (logic as AnyStateMachine) : undefined;
 }
 
-/** Every machine object written INLINE on one state's invokes. A named `src` resolves through
+/** Every machine object written INLINE on one state's invokes, with the hop xstate gives it (its
+ * generated src, from the invoke's index on the state). A named `src` resolves through
  * `implementations.actors` instead and is walked there. */
-function inlineMachines(node: StateNode<any, any>): AnyStateMachine[] {
+function inlineMachines(node: StateNode<any, any>): Array<{ machine: AnyStateMachine; hop: RouteHop }> {
   const config = [node.config.invoke ?? []].flat() as Array<{ src?: unknown }>;
-  return config.flatMap((inv) => {
+  return config.flatMap((inv, index) => {
     const machine = asMachine(inv?.src);
-    return machine ? [machine] : [];
+    return machine ? [{ machine, hop: inlineHop(index, node.id) }] : [];
   });
 }
 
+/**
+ * Refuse a Part written inline on an `invoke.src` — an `agent()`, an Effect, a `fail()` or a `workspace()` that
+ * is no key of the Machine's `actors` (see the module comment). Thrown at build by
+ * `jr2Setup.createMachine` and at load by {@link partsOf}, so a Machine built with xstate's own
+ * `createMachine` is refused where `jr2 check`, `jr2 up` and the Orchestrator read it. A plain
+ * child Machine written inline is not a Part: it stays walked, with no `customize()` route (its
+ * `path` is `undefined`).
+ */
+export function refuseInlineParts(machine: AnyStateMachine): void {
+  const partOf = (src: unknown): { part: string; written: string } | undefined => {
+    if (isAgent(src)) return { part: "an Agent", written: "agent(...)" };
+    if (isEffect(src)) return { part: "an Effect", written: `${src.effect.kind}(...)` };
+    if (isFailSlot(src)) return { part: "a fail() Part", written: "fail()" };
+    const child = asMachine(src);
+    if (child && composesSandbox(child)) return { part: "a Workspace", written: "workspace(...)" };
+    return undefined;
+  };
+  const visit = (node: StateNode<any, any>): void => {
+    for (const inv of [node.config.invoke ?? []].flat() as Array<{ src?: unknown }>) {
+      const found = partOf(inv?.src);
+      if (found === undefined) continue;
+      throw new Error(
+        `machine "${machine.id}": state "${node.id}" invokes ${found.part} inline — a Part is a key of actors, so ` +
+          `it has a name that the ledger, the report and customize() share: actors: { <name>: ${found.written} }, ` +
+          `then invoke: { src: "<name>" }`,
+      );
+    }
+    for (const child of Object.values(node.states as Record<string, StateNode<any, any>>)) visit(child);
+  };
+  visit(machine.root);
+}
+
 /** `JSON.stringify` with object keys sorted at every depth — a value's identity, not its spelling.
  * Symbols are spelled out rather than dropped: `JSON.stringify` silently omits a symbol-valued
  * key, which would make an Open Agent (ADR-0054) collapse into a bound one that differs in nothing
@@ -405,10 +730,17 @@ function canonical(value: unknown): string {
  */
 export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
   const agents: CarriedAgent[] = [];
+  const failures: CarriedFailure[] = [];
+  const effects: CarriedEffect[] = [];
   const images: CarriedImage[] = [];
   const repos: CarriedRepo[] = [];
   const openSlots: OpenSlot[] = [];
   const openAgents: OpenSlot[] = [];
+  const openEffects: CarriedParts["openEffects"] = [];
+  const sizes: CarriedSize[] = [];
+  const openBodies: CarriedParts["openBodies"] = [];
+  // The Machine that declares each Open body: where its lent Agents are read (not carried data).
+  const bodyWrappers = new Map<CarriedParts["openBodies"][number], AnyStateMachine>();
   let sandboxed = false;
   const seen = new Set<string>();
   // Cycle guard AND work saver: a Machine reached twice carries the same parts both times, and a
@@ -466,35 +798,371 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
     }
   };
 
-  const walkStates = (node: StateNode<any, any>, visit: (machine: AnyStateMachine) => void): void => {
-    for (const machine of inlineMachines(node)) visit(machine);
-    for (const child of Object.values(node.states as Record<string, StateNode<any, any>>)) walkStates(child, visit);
-  };
-
   // `path` is the `customize()` route from the registered root to `machine` (see `OpenSlot`):
   // a named child slot extends it, a wrapper's transparent body does not, and an inline invoke
   // ends it — nothing downstream of an actor without a slot key can be named by a composer.
-  const walk = (machine: AnyStateMachine, path: OpenSlot["path"]): void => {
+  // `route` is the placement route, which an inline invoke extends by its hop (`PlacementRoute`).
+  const walk = (machine: AnyStateMachine, path: OpenSlot["path"], route: PlacementRoute): void => {
     if (walked.has(machine)) return;
     walked.add(machine);
+    refuseInlineParts(machine);
+    refuseLostOutput(machine);
+    refuseUnroutedAgentFault(machine);
     const parts = sandboxPartsOf(machine);
+    const user = userSeatOf(parts.user);
     collectImage(parts.image);
-    collectImage(parts.user);
+    collectImage(user.image);
+    collectImage(parts.effector?.image);
     if (composesSandbox(machine)) {
       sandboxed = true;
       collectRepos(path, parts.repos);
+      sizes.push({
+        path,
+        route,
+        ...(parts.resources !== undefined ? { resources: parts.resources } : {}),
+        ...(user.resources !== undefined ? { user: user.resources } : {}),
+      });
     }
     const body = wrapperBodyOf(machine);
+    for (const { state, slot } of failingStatesOf(machine)) failures.push({ machine: machine.id, state, slot, path });
     for (const [name, logic] of Object.entries(machine.implementations.actors as Record<string, unknown>)) {
       if (isAgent(logic)) collectAgent(path, name, logic.definition);
-      else {
+      else if (isOpenBody(logic)) {
+        const body = { slot: name, declaration: openBodyDeclarationOf(logic), path };
+        openBodies.push(body);
+        bodyWrappers.set(body, machine);
+      } else if (isEffect(logic)) {
+        const effect = carriedEffectOf(name, path, route, logic.effect);
+        effects.push(effect);
+        if (effect.kind !== "push" && effect.open !== undefined)
+          openEffects.push({ slot: name, path, parts: [...effect.open] });
+      } else {
         const child = asMachine(logic);
-        if (child) walk(child, path === undefined ? undefined : name === body ? path : [...path, name]);
+        if (child) walk(child, slotPath(path, name, body), name === body ? route : [...route, name]);
       }
     }
-    walkStates(machine.root, (inline) => walk(inline, undefined));
+    walkStates(machine.root, (inline, hop) => walk(inline, undefined, [...route, hop]));
   };
 
-  for (const machine of machines) walk(machine, []);
-  return { agents, images, repos, openSlots, openAgents, composesSandbox: sandboxed };
+  for (const machine of machines) walk(machine, [], []);
+  const bound = (m: unknown): m is string => typeof m === "string";
+  const models = new Set<string>(agents.map((a) => a.definition.model).filter(bound));
+  for (const body of openBodies) for (const m of body.declaration.allows.models) models.add(m);
+  const menuOnly = agents.filter((a) => a.definition.workspace === "none");
+  const noneBodies = openBodies.filter((b) => bodyTurnsRunIn(bodyWrappers.get(b)!, b.declaration, "instance"));
+  const harnessModels = new Set<string>(menuOnly.map((a) => a.definition.model).filter(bound));
+  for (const body of noneBodies) for (const m of body.declaration.allows.models) harnessModels.add(m);
+  return {
+    agents,
+    failures,
+    effects,
+    images,
+    repos,
+    openSlots,
+    openAgents,
+    openEffects,
+    sizes,
+    composesSandbox: sandboxed,
+    openBodies,
+    models: [...models].sort(),
+    ...(menuOnly.length || noneBodies.length ? { instanceHarness: { models: [...harnessModels].sort() } } : {}),
+  };
+}
+
+/**
+ * Can a Turn under an Open body of `wrapper` run where `where` says, with a model the body allows
+ * (ADR-0070: a minted model needs a key the Assembly placed, a door refusal and never a 401)? A
+ * Chart's own Agent runs where its Workspace access says, so a body that allows "write" or "read"
+ * runs Turns in a pod, and one that allows "none" at the Instance Harness. A lent Agent runs where
+ * its own access says, and a Chart may set its `model` dial to an allowed model: a lent Agent that
+ * is not "none" is a pod Turn, and a "none" one an Instance Harness Turn.
+ */
+function bodyTurnsRunIn(wrapper: AnyStateMachine, decl: OpenBodyDeclaration, where: "pod" | "instance"): boolean {
+  const atInstance = (w: string | undefined) => w === "none";
+  if (decl.allows.workspace.some((w) => (where === "instance" ? atInstance(w) : !atInstance(w)))) return true;
+  const actors = wrapper.implementations.actors as Record<string, unknown>;
+  return (decl.lends.agents ?? []).some((slot) => {
+    const logic = actors[slot];
+    if (!isAgent(logic)) return false;
+    const access = (logic.definition as { workspace?: string }).workspace;
+    return where === "instance" ? atInstance(access) : !atInstance(access);
+  });
+}
+
+/** The `customize()` route to a child of slot `name`: a wrapper's body does not extend it. */
+function slotPath(path: OpenSlot["path"], name: string, body: string | undefined): OpenSlot["path"] {
+  return path === undefined ? undefined : name === body ? path : [...path, name];
+}
+
+/**
+ * Every Effect the registered Machine `root` places, at every route it is reached by — one entry
+ * per route, as {@link workspacePodsOf} lists pods: a Machine invoked under two slot keys places
+ * its Effects twice, and each is checked where it is. What the placement walk reads (ADR-0068),
+ * never {@link partsOf}'s list, which holds one entry per Machine. A cycle (a recursive pool
+ * worker) stops at the Machine on its own route.
+ */
+export function placedEffectsOf(root: AnyStateMachine): CarriedEffect[] {
+  const effects: CarriedEffect[] = [];
+  const walk = (
+    machine: AnyStateMachine,
+    path: OpenSlot["path"],
+    route: PlacementRoute,
+    on: Set<AnyStateMachine>,
+  ): void => {
+    if (on.has(machine)) return;
+    on.add(machine);
+    const body = wrapperBodyOf(machine);
+    for (const [name, logic] of Object.entries(machine.implementations.actors as Record<string, unknown>)) {
+      if (isAgent(logic)) continue;
+      if (isEffect(logic)) {
+        effects.push(carriedEffectOf(name, path, route, logic.effect));
+        continue;
+      }
+      const child = asMachine(logic);
+      if (child) walk(child, slotPath(path, name, body), name === body ? route : [...route, name], on);
+    }
+    walkStates(machine.root, (inline, hop) => walk(inline, undefined, [...route, hop], on));
+    on.delete(machine);
+  };
+  walk(root, [], [], new Set());
+  return effects;
+}
+
+/** One Effect slot's plain data, as `jr2 up` and the placement read it. */
+export function carriedEffectOf(
+  name: string,
+  path: OpenSlot["path"],
+  route: PlacementRoute,
+  parts: EffectParts,
+): CarriedEffect {
+  const placement = placementOf(parts);
+  const openParts = openPartsOf(parts);
+  if (parts.kind === "dispatch") {
+    const input = (parts as { [DISPATCH_INPUT]?: Record<string, unknown> })[DISPATCH_INPUT];
+    return {
+      name,
+      path,
+      route,
+      kind: "dispatch",
+      placement,
+      workflow: parts.workflow,
+      wait: parts.wait,
+      timeoutMs: parts.timeoutMs,
+      ...(parts.target === undefined || parts.target === open ? {} : { target: originTarget(parts.target.url) }),
+      secrets: [...parts.secrets],
+      ...(input !== undefined ? { input } : {}),
+      ...(openParts.length ? { open: openParts as Array<"target"> } : {}),
+    };
+  }
+  if (parts.kind === "http") {
+    return {
+      name,
+      path,
+      route,
+      kind: "http",
+      placement,
+      method: parts.method,
+      ...(parts.target === open ? {} : { target: { ...parts.target } }),
+      ...(openParts.length ? { open: openParts as Array<"url" | "secret"> } : {}),
+      secrets: [...parts.secrets],
+      idempotent: parts.idempotent,
+      timeoutMs: parts.timeoutMs,
+      ...(parts.file ? { file: true as const } : {}),
+      ...(parts.file?.slot !== undefined ? { slot: parts.file.slot } : {}),
+    };
+  }
+  if (parts.kind === "push") {
+    const { sign, squash, force, pin, timeoutMs, slot } = parts;
+    return {
+      name,
+      path,
+      route,
+      kind: "push",
+      placement,
+      sign,
+      squash,
+      force,
+      pin,
+      secrets: [],
+      timeoutMs,
+      ...(slot !== undefined ? { slot } : {}),
+    };
+  }
+  const { argv, timeoutMs, slot, secrets, pin } = parts;
+  return {
+    name,
+    path,
+    route,
+    kind: "command",
+    placement,
+    argv: argvText(argv),
+    timeoutMs,
+    ...(slot !== undefined ? { slot } : {}),
+    ...(secrets?.length ? { secrets: [...secrets] } : {}),
+    ...(pin ? { pin } : {}),
+    ...(openParts.length ? { open: openParts as Array<"argv" | "secret"> } : {}),
+  };
+}
+
+/** The key a dispatch's slot schema rides its parts under (dispatch-effect.ts): `Symbol.for`, so this
+ * walk reads it off a Machine built by another copy of the module (ADR-0071). */
+const DISPATCH_INPUT = Symbol.for("jr2.dispatch.input");
+
+/** A dispatch target's origin as the Effector's fence reads an http target: scheme, host, port. The
+ * origin was checked when the slot was built, so it parses. */
+function originTarget(url: string): { scheme: "http" | "https"; host: string; port: number } {
+  const u = new URL(url);
+  const scheme = u.protocol === "http:" ? "http" : "https";
+  // As an http target's: brackets off an IPv6 literal, lower case (http-effect.ts `targetOf`).
+  const host = u.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  return { scheme, host, port: u.port ? Number(u.port) : scheme === "http" ? 80 : 443 };
+}
+
+/**
+ * One Workspace a Machine composes, as its pod's Held secrets are placed (ADR-0059): what the pod
+ * names. Located like a {@link CarriedSize} — `path` is the `customize()` route to its
+ * `workspace()`, and `route` its placement route, the same route the run host reads off the live
+ * actor at provision (`actorRoute`), so `jr2 up` and the provision name one pod alike.
+ */
+export type WorkspacePod = {
+  path: readonly string[] | undefined;
+  /** The pod's placement route: what its pod key reads (`workspaceHeldPod`). */
+  route: PlacementRoute;
+  /** The `workspace()`'s own `secrets: [...]`, as written. */
+  secrets: string[];
+  /** The model of every bound Agent whose Turn runs in this pod: each Agent below the
+   * `workspace()` that is not `workspace: "none"` (those run at the Instance Harness, ADR-0031),
+   * down to the next `workspace()`, which is a pod of its own, and every model an Open body below
+   * it allows a Chart's own Agents when it allows "write" or "read" (ADR-0070). Sorted, deduped. */
+  models: string[];
+  /** The Effects placed in this pod's Sandbox Effector (ADR-0068): every `push`, file-body `http` and
+   * credentialed `command` slot below the `workspace()`, down to the next `workspace()` — read off
+   * their plain data, statically. Empty → the pod gets no Sandbox Effector and no Secret. */
+  effects: CarriedEffect[];
+  /** The `workspace()`'s `effector: { image }`, as written. Absent → the Sandbox Image. */
+  effector?: { image: string };
+  /** The `workspace()`'s own `image`, as written — its Sandbox Image. Absent → `images/default`,
+   * then the stock Harness (ADR-0037). */
+  image?: string;
+  /** Each Repo Slot's Binding url as the Machine binds it, by slot, in order; undefined for an open
+   * or per-run slot, whose url `jr2 up` cannot read. A push resolves its credential through it. */
+  bindings: Record<string, string | undefined>;
+  /** The `workspace()` declares no Repo Slot (ADR-0051): it has only `/work`, which its steps
+   * share. Absent for one with slots, and for an Open map, whose slots the composer names. */
+  noSlot?: true;
+};
+
+/**
+ * Every Workspace a Machine composes, at every route it is reached by — one entry per route, so a
+ * `workspace()` composed under two slot keys is two pods. Not deduped like {@link partsOf}: a pod
+ * is a route, not a Machine. A cycle (a recursive pool worker) stops at the Machine on its own
+ * route.
+ */
+export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
+  const pods: WorkspacePod[] = [];
+  /** The bound models of the Agents in `machine` and the Machines it composes, short of a
+   * `workspace()`. */
+  const modelsIn = (
+    machine: AnyStateMachine,
+    models: Set<string>,
+    on: Set<AnyStateMachine>,
+    effects: Map<string, CarriedEffect>,
+    path: OpenSlot["path"],
+    route: PlacementRoute,
+  ): void => {
+    if (on.has(machine)) return;
+    on.add(machine);
+    const body = wrapperBodyOf(machine);
+    const visit = (child: AnyStateMachine, at: OpenSlot["path"], to: PlacementRoute) => {
+      if (!composesSandbox(child)) modelsIn(child, models, on, effects, at, to);
+    };
+    for (const [name, logic] of Object.entries(machine.implementations.actors as Record<string, unknown>)) {
+      if (isAgent(logic)) {
+        const { model, workspace } = logic.definition;
+        if (workspace !== "none" && typeof model === "string") models.add(model);
+        continue;
+      }
+      // A Turn under an Open body may run in this pod with any model the body allows (ADR-0070):
+      // a Chart's own Agent, when the body allows a Workspace access other than "none", and a lent
+      // Agent that is not "none", whose `model` dial a Chart may set to an allowed model.
+      if (isOpenBody(logic)) {
+        const decl = openBodyDeclarationOf(logic);
+        if (bodyTurnsRunIn(machine, decl, "pod")) for (const m of decl.allows.models) models.add(m);
+        continue;
+      }
+      if (isEffect(logic)) {
+        const effect = carriedEffectOf(name, path, route, logic.effect);
+        if (effect.placement === "sandbox") effects.set(JSON.stringify([route, name]), effect);
+        continue;
+      }
+      const child = asMachine(logic);
+      if (child) visit(child, slotPath(path, name, body), name === body ? route : [...route, name]);
+    }
+    walkStates(machine.root, (inline, hop) => visit(inline, undefined, [...route, hop]));
+    on.delete(machine);
+  };
+  const walk = (
+    machine: AnyStateMachine,
+    path: OpenSlot["path"],
+    route: PlacementRoute,
+    on: Set<AnyStateMachine>,
+  ): void => {
+    if (on.has(machine)) return;
+    on.add(machine);
+    if (composesSandbox(machine)) {
+      const models = new Set<string>();
+      const effects = new Map<string, CarriedEffect>();
+      modelsIn(machine, models, new Set(), effects, path, route);
+      const parts = sandboxPartsOf(machine);
+      const bindings: Record<string, string | undefined> = {};
+      if (parts.repos !== open) {
+        for (const [slot, value] of Object.entries(parts.repos)) {
+          const state = repoSlotState(value);
+          bindings[slot] = state.kind === "bound" ? state.binding.url : undefined;
+        }
+      }
+      pods.push({
+        path,
+        route,
+        secrets: [...(parts.secrets ?? [])],
+        models: [...models].sort(),
+        effects: [...effects.values()],
+        ...(parts.effector ? { effector: { ...parts.effector } } : {}),
+        ...(parts.image !== undefined ? { image: parts.image } : {}),
+        bindings,
+        ...(parts.repos !== open && Object.keys(parts.repos).length === 0 ? { noSlot: true as const } : {}),
+      });
+    }
+    const body = wrapperBodyOf(machine);
+    for (const [name, logic] of Object.entries(machine.implementations.actors as Record<string, unknown>)) {
+      const child = isAgent(logic) || isEffect(logic) ? undefined : asMachine(logic);
+      if (child) walk(child, slotPath(path, name, body), name === body ? route : [...route, name], on);
+    }
+    walkStates(machine.root, (inline, hop) => walk(inline, undefined, [...route, hop], on));
+    on.delete(machine);
+  };
+  walk(root, [], [], new Set());
+  return pods;
+}
+
+/** Every state of `machine`'s own tree that invokes a `fail()` slot (ADR-0073), in document order,
+ * with the slot key: a state that can fail the run. A child Machine's states are its own walk's. */
+export function failingStatesOf(machine: AnyStateMachine): Array<{ state: string; slot: string }> {
+  const actors = machine.implementations.actors as Record<string, unknown>;
+  const out: Array<{ state: string; slot: string }> = [];
+  const visit = (node: StateNode<any, any>): void => {
+    for (const inv of node.invoke) {
+      if (typeof inv.src === "string" && isFailSlot(actors[inv.src])) out.push({ state: node.id, slot: inv.src });
+    }
+    const children = Object.values(node.states as Record<string, StateNode<any, any>>);
+    for (const child of children.sort((a, b) => a.order - b.order)) visit(child);
+  };
+  visit(machine.root);
+  return out;
+}
+
+/** Every machine object written inline below `node`, at any depth of its state tree, with its hop. */
+function walkStates(node: StateNode<any, any>, visit: (machine: AnyStateMachine, hop: RouteHop) => void): void {
+  for (const { machine, hop } of inlineMachines(node)) visit(machine, hop);
+  for (const child of Object.values(node.states as Record<string, StateNode<any, any>>)) walkStates(child, visit);
 }