@jr2/orchestrator 0.4.1 → 0.6.0

package/src/index.ts

@@ -1,85 +1,77 @@
-// @jr2/orchestrator — the deployed app that runs Machines: workflow config, the agent + gate
-// delivery surfaces, the duplex Actor over the Harness wire, and durable snapshot persistence
-// (ADR-0002/0006/0007). Builds on the `@jr2/agent-protocol` wire contract.
+// @jr2/orchestrator — the Authoring surface (GLOSSARY.md): the names an author writes in a
+// workflow module or in `jr2.config.ts`, and no other name. A name is here when an author writes
+// it; a name an author only meets through inference (a jr2Setup event union, a gate's input, a
+// pick's Frame) stays internal. A workflow authors against ONE package — `defineEvent`,
+// `jr2Setup`, `workspace`, … all import from "@jr2/orchestrator" (ADR-0015) — and an Assistant that
+// reads this file reads the whole of what it may write.
 //
-// It does NOT speak MCP (ADR-0013): the Harness presents the Menu to its model itself, and reaches
-// the surface here through the Custodian in its pod. What lives here is the registration table and
-// two thin HTTP adapters over it — plus what composes a Custodian (ADR-0059).
+// Named re-exports only, never `export *`: each name below is a decision, and
+// test/authoring-surface.test.ts pins the list. The kit's own packages (the CLI, the e2e suite,
+// the Harness's tests) import "@jr2/orchestrator/internal", which holds everything here and the
+// runtime besides.
 
-// The wire contract, re-exported: a workflow authors against ONE package (`defineEvent`,
-// `jr2Setup`, `workspace`, … all import from "@jr2/orchestrator" — ADR-0015).
-export * from "@jr2/agent-protocol";
-export * from "./agent.ts";
-// The Effect surface (ADR-0067): `command` itself is the wire-bound one, from harness-client.ts;
-// `fromPick`, `paramsOf` and `answer` are what an author writes between a pick and its work.
-export * from "./effect.ts";
-// The http kind (ADR-0068): `http`, `secret`, `bearer`, `basic`, `text`, and the Effector's wire.
-export * from "./http-effect.ts";
-export * from "./sandbox-effect.ts";
-// An Effect's Open parts (ADR-0054): the types `customize({ effects })` reads.
-export type { EffectBinding, OpenEffect, OpenEffectPart } from "./open-effect.ts";
-export { openPartsText } from "./open-effect.ts";
-export * from "./effector-wire.ts";
-export * from "./pick.ts";
-// The Chart (ADR-0070): its grammar (`chartSchema`, which a Chart wrapper's door and a planner's pick
-// import), the door that admits one, and the resolver of its references.
-export * from "./chart.ts";
-// The Open body a Chart binds (`openBody`, the slot constructor a Chart wrapper places in `actors`)
-// and the named Charts of an Instance: Chart files and runtime Charts (ADR-0070).
-export * from "./open-body.ts";
-export * from "./charts.ts";
-export * from "./parts.ts";
-export * from "./size.ts";
-export * from "./customize.ts";
-export * from "./ambient.ts";
-export * from "./config.ts";
-export * from "./repo-identity.ts";
-export * from "./pool.ts";
-export * from "./setup.ts";
-// The author's routing guard (ADR-0015).
+// Machine and events: the setup a workflow writes its Machine with, the events its parties send,
+// and the guard that makes a writing decline other senders (ADR-0011, ADR-0015).
+export { defineEvent } from "@jr2/agent-protocol";
+export { jr2Setup } from "./setup.ts";
 export { sentBy } from "./party.ts";
-export * from "./vocabulary.ts";
-export * from "./tokens.ts";
-export * from "./durability.ts";
-export * from "./snapshot-store.ts";
-export * from "./actor.ts";
-export * from "./gate.ts";
-export * from "./workspace.ts";
-export * from "./images.ts";
-// The Assembly's content address and wire form (ADR-0069): `jr2 up` and the door share both.
-export * from "./content-hash.ts";
-export * from "./assembly-tar.ts";
-// The current Assembly and the publish door (ADR-0069), and the walk's refusal listing that
-// `jr2 up` and the door both run.
-export * from "./assembly.ts";
-export * from "./assembly-checks.ts";
-export * from "./mount-digest.ts";
-export * from "./model-keys.ts";
-export * from "./held-secrets.ts";
-export * from "./secret-placement.ts";
-export * from "./git-push.ts";
-export * from "./git-clone.ts";
-export * from "./custodian.ts";
-export * from "./sandbox-kube.ts";
-export {
-  effectorManifestKey,
-  LABEL_EFFECTOR_POD,
-  readSandboxEffectorManifest,
-  sandboxEffectorKeySecret,
-  sandboxEffectorObjectsOf,
-  type ProjectedSecret,
-  type SandboxEffectorManifest,
-} from "./sandbox-effector.ts";
-export * from "./repos.ts";
-export * from "./repo-fetch.ts";
-// Type-only: what a workflow event delivery looks like (the registration TABLE stays internal —
-// ADR-0011: workflows speak only defineEvent/agent/gate).
-export type { ChildErrorMarker, DeliveredEvent, PlacingMarker, RunMarker, TurnMarker } from "./registration.ts";
-export * from "./machine-doc.ts";
-export * from "./run-host.ts";
-export * from "./http.ts";
-export * from "./harness-client.ts";
-export * from "./stub-harness.ts";
-export * from "./instance.ts";
-export * from "./server.ts";
-export * from "./names.ts";
+export type { HostInjectedInput } from "./vocabulary.ts";
+
+// Failure: the Part a Machine invokes to fail its run, and the guard that tells a Failure from a
+// defect in an `onError` (ADR-0073).
+export { fail, isFailure } from "./fail.ts";
+
+// Agents: an Agent slot and the definition it carries (ADR-0028, ADR-0049).
+export { agent } from "./harness-client.ts";
+export type { AgentDefinition, ThinkingLevel } from "./agent.ts";
+
+// Workspaces and Repos: a Sandbox and the Repo Slots it binds (ADR-0012, ADR-0051).
+export { workspace } from "./workspace.ts";
+export type { Workspaced } from "./workspace.ts";
+export type { Binding, RepoSlot } from "./parts.ts";
+
+// Effects: work a Machine does outside itself, as an actor slot (ADR-0067, ADR-0068, ADR-0071),
+// and what an author writes between a pick and that work.
+export { arg } from "./effect.ts";
+export type { CommandOutput, LaterOutcome } from "./effect.ts";
+export { command } from "./harness-client.ts";
+export { basic, bearer, file, http, secret, text } from "./http-effect.ts";
+export type { HttpOutput } from "./effector-wire.ts";
+export { push } from "./sandbox-effect.ts";
+export type { PushOutput } from "./sandbox-effect.ts";
+export { branchName, isReady, readyOf, worktree } from "./worktree.ts";
+export type {
+  AnyFramePath,
+  AnyWorktreePath,
+  FramePath,
+  WorktreeFound,
+  WorktreeInput,
+  WorktreeOptions,
+  WorktreeOutput,
+  WorktreePath,
+  WorktreeReady,
+  WorktreeRefused,
+} from "./worktree.ts";
+export { dispatch } from "./dispatch-effect.ts";
+export type { DispatchOutput } from "./effect.ts";
+export { answer, fromPick, paramsOf } from "./pick.ts";
+
+// Composition: a part left Open, a Machine's parts retuned, a Pool over a Source (ADR-0017,
+// ADR-0049, ADR-0054, ADR-0060).
+export { open } from "./parts.ts";
+export { customize } from "./customize.ts";
+export type { Customize } from "./customize.ts";
+export type { EffectBinding } from "./open-effect.ts";
+export type { Size, UserContainer } from "./size.ts";
+export { pool, source } from "./pool.ts";
+export type { PoolNextInput } from "./pool.ts";
+
+// Charts: the Open body a Chart wrapper places in `actors`, and the grammar a planner's pick
+// declares, whole or narrowed to one wrapper (ADR-0070).
+export { openBody } from "./open-body.ts";
+export type { OpenBodyDeclaration, OpenBodyOutput } from "./open-body.ts";
+export { chartSchema, chartSchemaFor } from "./chart.ts";
+
+// Config: `jr2.config.ts`, the deployment facts a Machine cannot carry (ADR-0050).
+export { defineConfig } from "./config.ts";
+export type { JR2Config } from "./config.ts";

package/src/instance.ts

@@ -38,8 +38,17 @@ import {
   type ResolvedAssembly,
 } from "./assembly.ts";
 import { assemblyRefusals, type LoadedWorkflow } from "./assembly-checks.ts";
-import { chartName, NamedCharts, readChartFiles, splitChartName, type ChartCounts, type ChartFile } from "./charts.ts";
+import {
+  chartName,
+  NamedCharts,
+  readChartFiles,
+  readRuntimeCharts,
+  splitChartName,
+  type ChartCounts,
+  type ChartFile,
+} from "./charts.ts";
 import type { ImageRefs } from "./images.ts";
+import { partsOf } from "./parts.ts";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import type { AddressInfo } from "node:net";
@@ -56,6 +65,7 @@ import type { SnapshotStore } from "./snapshot-store.ts";
 import { createAuthenticator, effectorKey, harnessToken, loadSigningKey, mintInstanceToken } from "./tokens.ts";
 import type { SandboxPort } from "./workspace.ts";
 import type { EffectorPlacement, EffectorTarget } from "./http-effect.ts";
+import { WORKFLOW_NAME } from "./effector-wire.ts";
 
 export type InstanceOptions = {
   /** The instance folder: the state volume `.jr2/` (its `state.db` unless `store` is supplied, and
@@ -119,6 +129,10 @@ export type InstanceOptions = {
    * The entrypoint derives it from the pod's namespace (deterministic Service DNS); absent,
    * such a Turn without an explicit `endpoint` faults pointedly. */
   instanceHarness?: string;
+  /** The name this Orchestrator gives itself at another Orchestrator's door (ADR-0071): a foreign
+   * dispatch's `dispatchedBy.instance`. The entrypoint passes the pod's namespace; absent, a foreign
+   * dispatch names an unnamed caller. */
+  orchestratorName?: string;
   /** The Instance Effector's headless Service, `host:port` (ADR-0068) — where an http Effect is sent.
    * The entrypoint derives it from the pod's namespace; absent, an http Effect faults pointedly. */
   instanceEffector?: string;
@@ -287,6 +301,7 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
     resolveDef,
     sandbox: opts.sandbox,
     instanceHarness: opts.instanceHarness,
+    ...(opts.orchestratorName !== undefined ? { orchestratorName: opts.orchestratorName } : {}),
     harnessBearer: (placement) => harnessToken(signingKey, placement),
     // The Effectors (ADR-0068): each placement's Service, and the key its wire is signed with —
     // derived from the signing key as the Harness bearer is, so nothing is stored. The Instance
@@ -307,12 +322,15 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
     // says why (ADR-0030). stderr, because it is a fault, not the boot's structured result.
     onRestoreError: (runId, err) =>
       console.error(`restore failed for run ${runId}: ${err instanceof Error ? err.message : err}`),
+    // An in-process dispatch of a named Chart the current Assembly left unrunnable answers 409, as
+    // the HTTP door does (ADR-0071). The registry is built after the host; this runs only at a start.
+    unrunnableChart: (name): string | undefined => charts.get(name)?.unrunnable,
   });
 
   // The named Charts (ADR-0070). The runtime ones are read from the volume now, and admitted when
   // the first Assembly binds; with none current, every one waits unrunnable ("not in the current
   // Assembly") and is never deleted.
-  const charts = new NamedCharts({ dir: opts.dir, host });
+  const charts: NamedCharts = new NamedCharts({ dir: opts.dir, host });
   await charts.load();
   // The current Assembly's own Workflow names (ADR-0069, ADR-0070): its Machines and its Chart
   // files, as its record lists them. `GET /assembly` answers these; the runtime Charts the host
@@ -352,7 +370,8 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
   // by name. No current Assembly → no Workflows, and the process still serves (ADR-0048).
   if (current) {
     const booted = current;
-    swap(await importAssembly(booted.hash, booted.root), await readChartFiles(booted.root), booted);
+    const loaded = await importAssembly(booted.hash, booted.root);
+    swap(loaded, await readChartFiles(booted.root, undefined, contextDirsOf(loaded)), booted);
   } else {
     charts.bind({ workflows: [], files: [] });
   }
@@ -390,11 +409,14 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
       const workflows = await importWorkflows(root);
       // The Assembly's Chart files (ADR-0070): the door admits each against its wrapper, and one
       // that fails refuses the publish naming the file.
-      const files = await readChartFiles(root);
+      const files = await readChartFiles(root, undefined, contextDirsOf(workflows));
+      // The runtime Charts on the volume: a dispatch of a named Chart may resolve to one (ADR-0071).
+      const runtimeCharts = (await readRuntimeCharts(opts.dir)).map((c) => ({ name: chartName(c.wrapper, c.name) }));
       const refusals = await assemblyRefusals({
         config,
         workflows,
         charts: files,
+        runtimeCharts,
         ...(opts.imageMap ? { images: opts.imageMap } : {}),
         root,
       });
@@ -615,10 +637,22 @@ export async function loadWorkflows(dir: string): Promise<Array<{ name: string;
  * `workflows/<wrapper>/<name>.chart.json`, one level below the flat `workflows/*.ts`. The sibling
  * of {@link loadWorkflows}, for `jr2 up`'s host-side walk, which admits each file against its
  * wrapper with `chartFileRefusals`, the check the door's `assemblyRefusals({ charts })` runs. Any other file in a
- * wrapper's directory is ignored and named to `warn`.
+ * wrapper's directory is ignored and named to `warn`, except in a docker context that one of
+ * `workflows` names (ADR-0037): jr2 reads that folder too.
  */
-export function loadCharts(root: string, warn?: (line: string) => void): Promise<ChartFile[]> {
-  return readChartFiles(root, warn);
+export function loadCharts(
+  root: string,
+  workflows: LoadedWorkflow[],
+  warn?: (line: string) => void,
+): Promise<ChartFile[]> {
+  return readChartFiles(root, warn, contextDirsOf(workflows));
+}
+
+/** Every docker context folder the registered Machines name (ADR-0037, ADR-0049): a Sandbox
+ * Image, a User Container image or an Effector image that jr2 builds. The Chart discovery does not
+ * name a file in one (ADR-0070). */
+function contextDirsOf(workflows: LoadedWorkflow[]): string[] {
+  return partsOf(workflows.map((w) => w.machine)).images.map((i) => i.dir);
 }
 
 /**
@@ -629,6 +663,11 @@ export function loadCharts(root: string, warn?: (line: string) => void): Promise
  * and the `images/<name>` dirname scan it was also written for both retired with ADR-0049. An
  * ABSENT dir is empty; any other readdir failure (EACCES, ENOTDIR, …) throws — a directory that
  * exists but cannot be read must be loud, never "no modules".
+ *
+ * A stem is a Workflow name, and a Workflow name has one rule wherever it is written: lowercase
+ * letters, digits and "-", the rule a Chart name keeps too (`WORKFLOW_NAME`). So `jr2 run`, the
+ * door's path and a `dispatch` slot name the same set of Workflows (ADR-0071), and a stem outside
+ * the rule throws here, naming the rename, before anything registers it.
  */
 export async function discoverModules(moduleDir: string): Promise<Array<{ name: string; file: string }>> {
   let entries: string[];
@@ -638,10 +677,31 @@ export async function discoverModules(moduleDir: string): Promise<Array<{ name:
     if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
     throw err;
   }
-  return entries
+  const modules = entries
     .filter((f) => f.endsWith(".ts") && !f.endsWith(".d.ts") && !f.startsWith("_"))
     .sort()
     .map((f) => ({ name: f.slice(0, -3), file: join(moduleDir, f) }));
+  for (const { name } of modules) {
+    if (!WORKFLOW_NAME.test(name)) {
+      throw new Error(
+        `${join(moduleDir, `${name}.ts`)}: a Workflow is named by its filename stem, in lowercase letters, digits ` +
+          `and "-", so that \`jr2 run\` and a \`dispatch\` slot name it the same way — rename it to ` +
+          `${kebabOf(name)}.ts (ADR-0071)`,
+      );
+    }
+  }
+  return modules;
+}
+
+/** A stem outside the rule, as the rule would spell it: `reviewLoop` and `review_loop` are
+ * `review-loop`. */
+function kebabOf(stem: string): string {
+  const out = stem
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return out === "" ? "workflow" : out;
 }
 
 /**

package/src/internal.ts

@@ -0,0 +1,85 @@
+// @jr2/orchestrator/internal — NOT for workflow authors. Everything the kit's own packages share
+// that is not on the Authoring surface (index.ts): the run host, the HTTP API, the Harness wire,
+// the Custodian, the Effector wire, the cluster names, the load walk. The CLI, the e2e suite,
+// and any other kit package that imports this one use it. No stability promise: any
+// name here can change or go in any release, so a workflow or a `jr2.config.ts` that imports it
+// is wrong, whatever compiles.
+//
+// It is the whole of index.ts plus the rest, so a kit file imports one specifier. The Orchestrator
+// does NOT speak MCP (ADR-0013): the Harness presents the Menu to its model itself, and reaches the
+// surface here through the Custodian in its pod.
+
+export * from "./index.ts";
+
+// The wire contract (ADR-0011): `defineEvent` is on the surface; the rest is the kit's.
+export * from "@jr2/agent-protocol";
+export * from "./agent.ts";
+export * from "./effect.ts";
+export * from "./http-effect.ts";
+export * from "./sandbox-effect.ts";
+export * from "./dispatch-effect.ts";
+export type { EffectBinding, OpenEffect, OpenEffectPart } from "./open-effect.ts";
+export { openPartsText } from "./open-effect.ts";
+export * from "./effector-wire.ts";
+export * from "./pick.ts";
+export * from "./chart.ts";
+export * from "./open-body.ts";
+export * from "./charts.ts";
+export * from "./parts.ts";
+export * from "./size.ts";
+export * from "./customize.ts";
+export * from "./ambient.ts";
+export * from "./config.ts";
+export * from "./repo-identity.ts";
+export * from "./pool.ts";
+export * from "./setup.ts";
+export { sentBy } from "./party.ts";
+export * from "./vocabulary.ts";
+export * from "./tokens.ts";
+export * from "./durability.ts";
+export * from "./snapshot-store.ts";
+export * from "./actor.ts";
+// The `gate` actor: jr2Setup pre-registers it and a state invokes it as `src: "gate"`, so no
+// author writes the value (ADR-0015).
+export * from "./gate.ts";
+// The Failure's brand stays in fail.ts, and so does the logic that throws it: the kit makes a Failure
+// only through `fail()` and `workspace()`, which imports that logic from fail.ts (ADR-0073).
+export { failurePayload, isFailSlot } from "./fail.ts";
+export type { Failure, FailSlot, FailureInput } from "./fail.ts";
+export * from "./workspace.ts";
+export * from "./images.ts";
+export * from "./content-hash.ts";
+export * from "./assembly-tar.ts";
+export * from "./assembly.ts";
+export * from "./assembly-checks.ts";
+export * from "./mount-digest.ts";
+export * from "./model-keys.ts";
+export * from "./held-secrets.ts";
+export * from "./secret-placement.ts";
+export * from "./git-push.ts";
+export * from "./git-clone.ts";
+export * from "./custodian.ts";
+export * from "./harness-env.ts";
+export * from "./sandbox-kube.ts";
+export {
+  effectorManifestKey,
+  LABEL_EFFECTOR_POD,
+  readSandboxEffectorManifest,
+  sandboxEffectorKeySecret,
+  sandboxEffectorObjectsOf,
+  type ProjectedSecret,
+  type SandboxEffectorManifest,
+} from "./sandbox-effector.ts";
+export * from "./repos.ts";
+export * from "./repo-fetch.ts";
+// Type-only: what a workflow event delivery looks like (the registration TABLE stays internal
+// even here — ADR-0011).
+export type { ChildErrorMarker, DeliveredEvent, PlacingMarker, RunMarker, TurnMarker } from "./registration.ts";
+export * from "./machine-doc.ts";
+export * from "./run-host.ts";
+export * from "./http.ts";
+export * from "./harness-client.ts";
+export * from "./stub-harness.ts";
+export * from "./instance.ts";
+export * from "./server.ts";
+export * from "./names.ts";

package/src/kube-client.ts

@@ -108,7 +108,7 @@ export interface KubeClient {
   /** Create; an existing object is a {@link KubeError} with status 409. */
   create<T extends KubeObject>(kind: KubeKind, namespace: string, body: T): Promise<T & KubeObject>;
   /** Delete; true when there was one to delete, false when it was already gone. */
-  delete(kind: KubeKind, namespace: string, name: string): Promise<boolean>;
+  delete(kind: KubeKind, namespace: string, name: string, opts?: { foreground?: boolean }): Promise<boolean>;
   /** A JSON merge patch — `null` removes a key. `status` patches the status subresource. Answers
    * the object as it stands after the patch. */
   patch<T extends KubeObject>(
@@ -216,9 +216,12 @@ export function kubeClient(opts: KubeClientOptions = {}): KubeClient {
       });
     },
 
-    delete(kind: KubeKind, ns: string, name: string) {
+    delete(kind: KubeKind, ns: string, name: string, opts: { foreground?: boolean } = {}) {
       return writes(async () => {
-        const res = await send("DELETE", pathOf(kind, ns, name));
+        // Foreground: the object stays until its dependents, a Sandbox's pod, are gone.
+        const res = await send("DELETE", pathOf(kind, ns, name), {
+          ...(opts.foreground ? { query: { propagationPolicy: "Foreground" } } : {}),
+        });
         if (res.status === 404) {
           await res.body?.cancel();
           return false;

package/src/machine-doc.ts

@@ -19,7 +19,9 @@ import type { AnyStateMachine, StateNode, TransitionDefinition } from "xstate";
 import { z } from "zod";
 import type { EventAudience } from "@jr2/agent-protocol";
 import { argvText, isEffect, targetText, type EffectParts } from "./effect.ts";
+import { isFailSlot } from "./fail.ts";
 import { loadWarningsOf, seatsOf, vocabularyOf, type MachineSeat } from "./vocabulary.ts";
+import { open } from "./open.ts";
 
 /** One transition of the Machine, id-addressed at both ends. */
 export type MachineTransitionDoc = {
@@ -40,9 +42,9 @@ export type MachineTransitionDoc = {
 };
 
 /** An Effect slot's parts, as the doc carries them (ADR-0067): a command's argv (an argv slot reads
- * `<name>`), its timeout, and the Repo Slot whose Worktree is its cwd, when it names one. */
+ * `<name>`) and its timeout. Its input names its Worktree, so the doc does not (ADR-0075). */
 export type EffectDoc =
-  | { kind: "command"; argv: string[]; timeoutMs: number; slot?: string; secrets?: string[]; pin?: true }
+  | { kind: "command"; argv: string[]; timeoutMs: number; secrets?: string[]; pin?: true }
   /** An http Effect (ADR-0068): its method, its fixed target, the secrets it names — never a value
    * — and `file` when its body is a Worktree file (ADR-0067). */
   | {
@@ -55,7 +57,11 @@ export type EffectDoc =
       file?: true;
     }
   /** A push (ADR-0067): which options the author set. */
-  | { kind: "push"; sign: boolean; squash: boolean; force: boolean; pin: boolean; timeoutMs: number; slot?: string };
+  | { kind: "push"; sign: boolean; squash: boolean; force: boolean; pin: boolean; timeoutMs: number; slot?: string }
+  /** A dispatch (ADR-0071): the Workflow it starts a run of, whether it waits, and the other
+   * Orchestrator's origin (`<open>` while a package leaves it Open); no target is this Orchestrator.
+   * The token's secret is named on the parts, never here: the target is what a reader routes on. */
+  | { kind: "dispatch"; workflow: string; wait: boolean; target?: string; timeoutMs: number };
 
 /** One state of the Machine; `states` nests in document order. */
 export type MachineStateDoc = {
@@ -67,8 +73,9 @@ export type MachineStateDoc = {
   /** Initial child state id (compound only). */
   initial?: string;
   /** Each invoke's id and slot; an Effect's carries its plain-data parts (ADR-0067) — what it runs,
-   * where, and for how long, read without running anything. */
-  invoke: Array<{ id: string; src: string; effect?: EffectDoc }>;
+   * where, and for how long, read without running anything. `fail`: the slot is a `fail()`, so this
+   * state can fail the run (ADR-0073). */
+  invoke: Array<{ id: string; src: string; effect?: EffectDoc; fail?: true }>;
   tags: string[];
   description?: string;
   states: MachineStateDoc[];
@@ -326,6 +333,7 @@ function serializeState(node: StateNode<any, any>, into: MachineTransitionDoc[],
     type: node.type,
     invoke: node.invoke.map((inv) => {
       const logic = typeof inv.src === "string" ? scope.actors[inv.src] : undefined;
+      if (isFailSlot(logic)) return { id: inv.id, src: srcName(inv.src), fail: true as const };
       if (!isEffect(logic)) return { id: inv.id, src: srcName(inv.src) };
       return { id: inv.id, src: srcName(inv.src), effect: effectDoc(logic.effect) };
     }),
@@ -404,12 +412,21 @@ function effectDoc(parts: EffectParts): EffectDoc {
     const { sign, squash, force, pin, timeoutMs, slot } = parts;
     return { kind: "push", sign, squash, force, pin, timeoutMs, ...(slot ? { slot } : {}) };
   }
-  const { argv, timeoutMs, slot, secrets, pin } = parts;
+  if (parts.kind === "dispatch") {
+    const { workflow, wait, timeoutMs, target } = parts;
+    return {
+      kind: "dispatch",
+      workflow,
+      wait,
+      ...(target === undefined ? {} : { target: target === open ? "<open>" : target.url }),
+      timeoutMs,
+    };
+  }
+  const { argv, timeoutMs, secrets, pin } = parts;
   return {
     kind: "command",
     argv: argvText(argv),
     timeoutMs,
-    ...(slot ? { slot } : {}),
     ...(secrets?.length ? { secrets: [...secrets] } : {}),
     ...(pin ? { pin } : {}),
   };