@jr2/orchestrator 0.4.1 → 0.5.1

package/src/cause.ts

@@ -0,0 +1,234 @@
+// What took the Machine out of an Agent's state (ADR-0024): the Turn's own pick, or something else.
+// The Agent's Actor asks it as its invocation stops, and its sweep says `cause: "pick"` only for
+// the first, so the Harness settles that Submission `ended` and every other end `aborted`. The pick
+// may be from an earlier Submission of the same Turn: a nudge or a wake starts a new Submission in
+// the same Turn.
+//
+// The answer comes from the events the Machines took, never from the pick's answer: "was the pick's
+// work stopped" (`Hold.cutShort`, the answer's `stopped`) is another question. Two facts are kept,
+// read off xstate's inspection stream and the actor system's scheduler and clock:
+//
+//   - THE CAUSE OF EACH RELAY: the set of Agents' picks it comes from. ADR-0024 lists the four ways
+//     a relay comes from a pick: the pick itself, the work below the Agent's state, a send of an
+//     actor that takes a caused relay, and a timer armed while its Machine took one. The cause rides
+//     the RELAY, never the event object: xstate relays one object each time a config action with an
+//     object literal runs. A timer's cause rides its own `setTimeout` on the run's clock, so two
+//     timers of one id each keep their own.
+//   - THE EXIT. On each microstep of a Machine, the first microstep that stops the Agent's
+//     invocation names the cause of the macrostep it is part of. After it, the Agent's actor is no
+//     longer the child of the Machine that invokes it, a child Machine on the way up is no longer a
+//     child of the one above, or a Machine on the way up is done. A microstep that throws is never
+//     inspected, so a fault is never the exit. When a Machine above catches a fault on the way up,
+//     that catch is the exit, and it has no cause: a fault is never the pick's, even when the pick's
+//     route caused it. The stop of a run is no event of the Machine's.
+//   - A FAILURE (ADR-0073) is not a fault: it is the end that a state chose. When a Machine on the
+//     way up from the Agent ends with a Failure, its own error event is the exit, with the cause of
+//     that relay. So a pick whose route invokes `fail` ends its Turn, whether a Machine above
+//     catches the Failure or the run ends `failed`.
+//
+// Which relay an actor takes now is read from the relay order: xstate relays an event (inspected as
+// `@xstate.event`) to the actor's mailbox. The mailbox takes events one at a time, in order, and
+// xstate inspects `@xstate.snapshot` with that event when the actor has taken it. An actor's own done
+// or error event (`xstate.done.actor.<id>`, `xstate.error.actor.<id>`) is the last relay it makes
+// with a cause. It takes the cause of the relay the actor took then; after it, the actor is
+// finished. A finished actor has no cause, and a relay to it, or to a stopped actor, is not queued:
+// xstate drops it. Status alone does not say it: a done Machine makes its last deferred sends with
+// status `done`, and a Machine done at start is `done` before its init relay. And an errored callback
+// is never stopped: its own later sends still reach its parent.
+
+import type { AnyActorRef, AnyEventObject, AnyMachineSnapshot } from "xstate";
+import { isFailure } from "./fail.ts";
+import type { Registration } from "./registration.ts";
+
+const XSTATE_STOP = "xstate.stop";
+
+/** The Agents' picks a relay comes from; undefined for none. */
+type Cause = ReadonlySet<Registration> | undefined;
+
+export class PickCauses {
+  /** Each actor's relays that it has not taken yet, in order, with their causes: the first is the
+   * one it takes now, or next. */
+  private readonly pending = new WeakMap<AnyActorRef, Array<{ event: AnyEventObject; cause: Cause }>>();
+  /** For each registration, the cause of the microstep that took the Machine out of its Agent's
+   * state, or `null` for none. Set once, at the first such microstep. */
+  private readonly exits = new WeakMap<Registration, Cause | null>();
+  /** Each registration's Agent actor, read off the invoking Machine's committed snapshot. */
+  private readonly actors = new WeakMap<Registration, AnyActorRef>();
+  /** Each actor that relayed its own done or error event: it takes nothing more, and has no cause. */
+  private readonly finished = new WeakSet<AnyActorRef>();
+  /** The cause of the timer the scheduler arms now: the next `setTimeout` on the clock keeps it. */
+  private arming: Cause;
+  /** Set while a timer's callback runs: its cause, for the relay the scheduler makes next. */
+  private firing: { cause: Cause } | undefined;
+
+  /** The scheduler arms a timer whose source is `source`: its cause is the relay `source` takes now. */
+  armingFrom(source: AnyActorRef): void {
+    this.arming = this.causeOfCurrent(source);
+  }
+
+  /**
+   * The run's clock, over `base`: each `setTimeout` keeps the cause of the timer the scheduler arms
+   * with it, and gives it to the relay its callback makes. So each timer's cause is its own, even
+   * for two timers of one id. A clear needs nothing: the callback never runs.
+   */
+  clockOver<T>(base: { setTimeout: (fn: () => void, ms: number) => T; clearTimeout: (timer: T) => void }) {
+    return {
+      setTimeout: (fn: () => void, ms: number): T => {
+        const cause = this.arming;
+        this.arming = undefined;
+        return base.setTimeout(() => {
+          this.firing = { cause };
+          try {
+            fn();
+          } finally {
+            this.firing = undefined;
+          }
+        }, ms);
+      },
+      clearTimeout: (timer: T) => base.clearTimeout(timer),
+    };
+  }
+
+  /**
+   * `@xstate.event`: `event` is relayed from `source` to `target`. `pickOf` names the registrations
+   * whose pick it is, or whose work below it comes from. With them: the cause of the timer whose
+   * callback makes this relay, or else of the relay that `source` takes now.
+   *
+   * When the relay is the error event of a Machine that a Failure ended, it is the exit of each of
+   * `registrations` whose Agent that Machine invokes, or is above: the Failure took the Agent's
+   * state away, and the pick that chose it is the cause.
+   */
+  relayed(
+    source: AnyActorRef | undefined,
+    target: AnyActorRef,
+    event: AnyEventObject,
+    pickOf: () => Cause,
+    registrations: () => Iterable<Registration> = () => [],
+  ): void {
+    const firing = this.firing;
+    this.firing = undefined;
+    const by = firing ? firing.cause : source !== undefined ? this.causeOfCurrent(source) : undefined;
+    const cause = union(pickOf(), by);
+    // The source's own done or error event: the last relay it makes with a cause.
+    if (source !== undefined && isOwnEnd(source, event)) {
+      this.finished.add(source);
+      this.pending.delete(source);
+      if (isFailure((event as { error?: unknown }).error)) this.failedAt(source, cause, registrations());
+    }
+    if (this.finished.has(target) || statusOf(target) === "stopped") return;
+    const queue = this.pending.get(target);
+    if (queue) queue.push({ event, cause });
+    else this.pending.set(target, [{ event, cause }]);
+  }
+
+  /** A Failure ended `machine`: record the exit of each registration whose invoker is `machine` or
+   * is below it, with the cause of the Failure's relay. */
+  private failedAt(machine: AnyActorRef, cause: Cause, registrations: Iterable<Registration>): void {
+    for (const reg of registrations) {
+      if (this.exits.has(reg)) continue;
+      for (let at: AnyActorRef | undefined = reg.invoker; at !== undefined; at = at._parent) {
+        if (at !== machine) continue;
+        this.exits.set(reg, cause ?? null);
+        break;
+      }
+    }
+  }
+
+  /** `@xstate.snapshot`: `actor` has taken `event`. An event that was not relayed (a stop) leaves
+   * the order as it is; a stop clears it, since a stopped actor takes nothing more. */
+  taken(actor: AnyActorRef, event: AnyEventObject): void {
+    const queue = this.pending.get(actor);
+    if (!queue) return;
+    if (event.type === XSTATE_STOP) {
+      queue.length = 0;
+      return;
+    }
+    const at = queue.findIndex((relay) => relay.event === event);
+    if (at !== -1) queue.splice(0, at + 1);
+  }
+
+  /**
+   * `@xstate.microstep` of `machine`, with the snapshot after it: record the exit of each of
+   * `registrations` that this microstep takes out of the Machine.
+   */
+  microstep(
+    machine: AnyActorRef,
+    snapshot: AnyMachineSnapshot,
+    event: AnyEventObject,
+    registrations: Iterable<Registration>,
+  ): void {
+    for (const reg of registrations) {
+      if (this.exits.has(reg) || !reg.invoker || !reg.invokeId) continue;
+      if (!this.actors.has(reg)) {
+        // The committed snapshot: the invoking Machine's own microstep is not committed until its
+        // macrostep ends, so this is the actor the registration was made for.
+        const ref = childrenOf(reg.invoker.getSnapshot())[reg.invokeId];
+        if (ref === undefined) continue;
+        this.actors.set(reg, ref);
+      }
+      const exit = leaves(reg, this.actors.get(reg)!, machine, snapshot);
+      if (exit === false) continue;
+      // A fault on the way up took the Agent's state away when the Machine above caught it: that is
+      // the exit, and a fault is never the pick's, even when the pick's route caused it.
+      const none = event.type === XSTATE_STOP || exit === "fault";
+      this.exits.set(reg, none ? null : (this.causeOfCurrent(machine) ?? null));
+    }
+  }
+
+  /** Did this registration's own pick take the Machine out of its Agent's state? */
+  endedByPick(reg: Registration): boolean {
+    return this.exits.get(reg)?.has(reg) === true;
+  }
+
+  /** The cause of the relay `actor` takes now. A done or errored actor relays its own done or error
+   * event while it takes its last relay, so that event keeps the cause. A finished or stopped actor
+   * has none. */
+  private causeOfCurrent(actor: AnyActorRef): Cause {
+    const status = statusOf(actor);
+    if (status === undefined || status === "stopped" || this.finished.has(actor)) return undefined;
+    return this.pending.get(actor)?.[0]?.cause;
+  }
+}
+
+function statusOf(actor: AnyActorRef): string | undefined {
+  return (actor.getSnapshot() as { status?: string } | undefined)?.status;
+}
+
+/** Is `event` the actor's own done or error event? */
+function isOwnEnd(actor: AnyActorRef, event: AnyEventObject): boolean {
+  return event.type === `xstate.done.actor.${actor.id}` || event.type === `xstate.error.actor.${actor.id}`;
+}
+
+function union(a: Cause, b: Cause): Cause {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  return new Set([...a, ...b]);
+}
+
+/** Does this microstep of `machine` stop `reg`'s invocation: `machine` is on the way up from the
+ * Agent and is done, or the actor (or child Machine) on the way down is no longer its child. It is
+ * `"fault"` when a Machine on the way up below `machine` has status `error`: `machine` caught that
+ * fault. A Failure is no fault (ADR-0073), but it never gets here: its relay records the exit
+ * (`failedAt`) before a Machine above takes it. The invoker's own microstep has no Machine below it
+ * on the way up, so the error of a child of the invoker is never a fault here. */
+function leaves(
+  reg: Registration,
+  agent: AnyActorRef,
+  machine: AnyActorRef,
+  snapshot: AnyMachineSnapshot,
+): "exit" | "fault" | false {
+  let below = agent;
+  let faulted = false;
+  for (let at: AnyActorRef | undefined = reg.invoker; at !== undefined; below = at, at = at._parent) {
+    if (at === machine) {
+      if (snapshot.status !== "done" && childrenOf(snapshot)[below.id] === below) return false;
+      return faulted ? "fault" : "exit";
+    }
+    if (statusOf(at) === "error") faulted = true;
+  }
+  return false;
+}
+
+function childrenOf(snapshot: unknown): Record<string, AnyActorRef | undefined> {
+  return (snapshot as { children?: Record<string, AnyActorRef | undefined> } | undefined)?.children ?? {};
+}

package/src/chart.ts

@@ -23,6 +23,7 @@ import { z } from "zod";
 import { defineEvent, type EventAudience, type EventDef } from "@jr2/agent-protocol";
 import type { AgentDefinition, ThinkingLevel, WorkspaceAccess } from "./agent.ts";
 import { inputKeysOf, isEffect } from "./effect.ts";
+import { FAILURE_GUARD } from "./fail.ts";
 import { compileChart, durationMs, type LentParts, type OpenBodyDeclaration } from "./open-body.ts";
 import { SENT_BY } from "./party.ts";
 import { loadWarningsOf } from "./vocabulary.ts";
@@ -38,7 +39,8 @@ export type ChartJson = string | number | boolean | null | ChartJson[] | { [key:
  */
 export type ChartValue = ChartJson;
 
-/** A guard: a lent guard by name, with or without params, `jr2.sentBy`, or `not`/`and`/`or`. */
+/** A guard: a lent guard by name, with or without params, `jr2.sentBy`, `jr2.failure`, or
+ * `not`/`and`/`or`. */
 export type ChartGuard =
   | string
   | { type: string; params?: ChartValue }
@@ -71,7 +73,7 @@ export type ChartTransition =
 /** One transition or a list, in xstate's order. */
 export type ChartTransitions = ChartTransition | ChartTransition[];
 
-/** An invoke: a lent Agent, Effect or Machine, a minted Agent, or the kit's `gate`. */
+/** An invoke: a lent Agent, Effect or Machine, a minted Agent, or the kit's `gate` or `fail`. */
 export type ChartInvoke = {
   src: string;
   id?: string;
@@ -158,6 +160,10 @@ export function chartBriefing(narrow?: Narrow): string {
     ? ' `src: "gate"` is the kit\'s Gate: the Chart waits there for an outside answer (a human, a webhook), ' +
       'one of its `events` with `audience: "external"`, not an Agent\'s Turn.'
     : "";
+  const fail = narrow?.fail
+    ? ' `src: "fail"` with `input: { reason }` ends the run as a Failure: work that did not succeed, with ' +
+      `the reason for a person; an \`onError\` with the guard \`${FAILURE_GUARD}\` catches it. A final state means done.`
+    : "";
   const agents = mints
     ? `A state runs an Agent with \`invoke: { src, input: { prompt } }\`: \`src\` is a lent Agent's name${lent}. ` +
       "This Chart mints no Agent of its own: there is no `agents`."
@@ -165,7 +171,7 @@ export function chartBriefing(narrow?: Narrow): string {
       "a key of `agents`; a lent Agent needs no entry in `agents`, which mints new ones.";
   return (
     `A Chart is a workflow written as data: states, the events its Agents pick${mints ? "" : ", and the Agents it mints"}. ` +
-    `${agents}${gate} An Agent's Turn ends only when it ` +
+    `${agents}${gate}${fail} An Agent's Turn ends only when it ` +
     "picks one of the Chart's `events`: declare each pick in `events` with an `input` schema " +
     '(`{ "type": "object", "properties": { "<field>": { "type": "string" } }, "required": ["<field>"] }`; a field not in ' +
     "`required` may be absent), and " +
@@ -233,6 +239,7 @@ type Narrow = {
   srcs: string[];
   lentAgents: string[];
   gate: boolean;
+  fail: boolean;
   guards: string[];
   actions: string[];
   delays: string[];
@@ -353,16 +360,25 @@ function grammar(narrow?: Narrow): z.ZodType<ChartText> {
     })
     .describe('A context path without the "context." root, like "round" or "ticket.notes".');
 
-  // `jr2.sentBy` is the kit's routing guard (ADR-0015), and the one guard that is never lent.
+  // `jr2.sentBy` is the kit's routing guard (ADR-0015), and `jr2.failure` its test for a Failure on
+  // an `onError` (ADR-0073): every Chart has both, and neither is lent.
   const sentByArm = z.strictObject({ type: z.literal(SENT_BY), params: z.strictObject({ id: z.string() }) });
+  const failureArm = z.strictObject({ type: z.literal(FAILURE_GUARD) });
   const lentGuardName = narrow
-    ? enumOf(narrow.guards)
+    ? enumOf([...narrow.guards, FAILURE_GUARD])
     : z.string().refine((t) => t !== SENT_BY, { message: `"${SENT_BY}" takes params { id }` });
+  const paramGuardName = narrow
+    ? enumOf(narrow.guards)
+    : z
+        .string()
+        .refine((t) => t !== SENT_BY, { message: `"${SENT_BY}" takes params { id }` })
+        .refine((t) => t !== FAILURE_GUARD, { message: `"${FAILURE_GUARD}" takes no params` });
   const guard: z.ZodType<ChartGuard> = z
     .union([
       lentGuardName,
       sentByArm,
-      z.strictObject({ type: lentGuardName, params: template.optional() }),
+      failureArm,
+      z.strictObject({ type: paramGuardName, params: template.optional() }),
       z.strictObject({
         get not() {
           return guard;
@@ -381,7 +397,7 @@ function grammar(narrow?: Narrow): z.ZodType<ChartText> {
     ])
     .meta({
       id: `${ID_PREFIX}ChartGuard`,
-      description: "A lent guard by name, `jr2.sentBy`, or not/and/or of guards.",
+      description: `A lent guard by name, \`jr2.sentBy\`, \`${FAILURE_GUARD}\`, or not/and/or of guards.`,
     }) as never;
 
   const lentActionName = narrow
@@ -425,9 +441,14 @@ function grammar(narrow?: Narrow): z.ZodType<ChartText> {
     : z.string();
   const invoke = z
     .strictObject({
+      // A narrowed grammar names `fail` only where the body lends it: a model reads only what it can use.
       src: src.describe(
-        "A lent Agent, Effect or Machine by its name; the kit's `gate` (waits for an outside answer: a human, a " +
-          "webhook) where the body lends it; or a key of this Chart's `agents`.",
+        narrow && !narrow.fail
+          ? "A lent Agent, Effect or Machine by its name; the kit's `gate` (waits for an outside answer: a human, a " +
+              "webhook) where the body lends it; or a key of this Chart's `agents`."
+          : "A lent Agent, Effect or Machine by its name; the kit's `gate` (waits for an outside answer: a human, a " +
+              "webhook) or `fail` (ends the run as a Failure, with `input: { reason }`) where the body lends it; or a " +
+              "key of this Chart's `agents`.",
       ),
       id: name("invoke id").optional(),
       input: template.optional().describe("An Agent takes `{ prompt }`; an Effect or a Machine takes its own input."),
@@ -526,9 +547,17 @@ function grammar(narrow?: Narrow): z.ZodType<ChartText> {
     .describe(chartBriefing(narrow)) as unknown as z.ZodType<ChartText>;
 }
 
+// A door field or a pick param that IS this schema is a Chart field: `isChartSchema` tells, and
+// jr2 reads a Chart wrapper's one-shot door off it (ADR-0070).
 /**
- * The Chart grammar (ADR-0070), as zod. A door field or a pick param that IS this schema is a
- * Chart field: `isChartSchema` tells, and jr2 reads a Chart wrapper's one-shot door off it.
+ * The Chart grammar, as a zod schema. Make a field of the run input of a Chart wrapper this schema,
+ * as in `z.object({ topic: z.string(), chart: chartSchema })`. Then a run input can carry a Chart,
+ * and the wrapper can keep Charts under names: Chart files in `workflows/<wrapper>/`, and runtime
+ * Charts. For the pick of a planner, use `chartSchemaFor`, which knows the names that the Open body
+ * lends.
+ *
+ * @see docs/guides/run-a-chart-by-name.md
+ * @see docs/concepts/charts.md
  */
 export const chartSchema: z.ZodType<ChartText> = guarded(grammar());
 
@@ -578,13 +607,38 @@ export function chartBriefingOf(schema: unknown): string | undefined {
 
 const narrowedSchemas = new WeakMap<OpenBodyDeclaration, z.ZodType<ChartText>>();
 
+// Either way it is a Chart field (`isChartSchema`), and the door still admits the Chart against
+// the lent set the body has at its start. One schema per declaration (ADR-0070).
 /**
- * The Chart grammar as zod, narrowed to one Open body (ADR-0070): the lent `src` names, guard,
- * action and delay names, and the allowed models and Workspace accesses are enums. A planner's
- * pick whose field is this schema gets the narrowed grammar as its tool parameters, so the model
- * is constrained when it writes the Chart; a Chart wrapper's door may take it too. Either way it
- * is a Chart field (`isChartSchema`), and the door still admits the Chart against the lent set the
- * body has at its start. One schema per declaration.
+ * The Chart grammar for one Open body, as a zod schema. The names that the Open body lends, and the
+ * models and the Workspace accesses that it allows, are the only values that the schema takes.
+ * Make it the parameter of the pick of a planner. The model then gets the grammar as the
+ * parameters of its tool, and the Briefing tells it how a Chart runs. The door still checks each
+ * Chart before it runs.
+ *
+ * @param decl - The declaration of the Open body that the Chart binds.
+ * @returns The schema of a Chart for that Open body.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { chartSchemaFor, defineEvent, type OpenBodyDeclaration } from "@jr2/orchestrator";
+ *
+ * const declaration: OpenBodyDeclaration = {
+ *   lends: { agents: ["writer"], gate: true },
+ *   allows: { models: ["anthropic/claude-haiku-5-5"], workspace: ["none"] },
+ *   ceilings: { turns: 12, wallClock: "30m", transitions: 500, fanOut: 2, size: 65536 },
+ * };
+ *
+ * export const runChart = defineEvent({
+ *   name: "run_chart",
+ *   description: "Run this Chart. Its outcome is the answer to this call.",
+ *   input: z.object({ chart: chartSchemaFor(declaration) }),
+ * });
+ * ```
+ *
+ * @see docs/guides/let-an-agent-write-a-chart.md
+ * @see docs/concepts/charts.md
  */
 export function chartSchemaFor(decl: OpenBodyDeclaration): z.ZodType<ChartText> {
   const hit = narrowedSchemas.get(decl);
@@ -607,6 +661,7 @@ function lendsOf(decl: OpenBodyDeclaration) {
     actions: decl.lends.actions ?? [],
     delays: decl.lends.delays ?? [],
     gate: decl.lends.gate === true,
+    fail: decl.lends.fail === true,
   };
 }
 
@@ -624,9 +679,10 @@ export function narrowedChartSchema(decl: OpenBodyDeclaration): Record<string, u
 function narrowOf(decl: OpenBodyDeclaration): Narrow {
   const l = lendsOf(decl);
   return {
-    srcs: [...l.agents, ...l.effects, ...l.machines, ...(l.gate ? ["gate"] : [])],
+    srcs: [...l.agents, ...l.effects, ...l.machines, ...(l.gate ? ["gate"] : []), ...(l.fail ? ["fail"] : [])],
     lentAgents: l.agents,
     gate: l.gate,
+    fail: l.fail,
     guards: l.guards,
     actions: l.actions,
     delays: l.delays,
@@ -867,6 +923,9 @@ function issueLines(
 
 const pathText = (path: readonly PropertyKey[]): string => (path.length ? path.map(String).join(".") : "(chart)");
 
+/** What an invoke's `src` names (rule 3). */
+type InvokeKind = "agent" | "minted" | "effect" | "machine" | "gate" | "fail";
+
 /** One state of the Chart, indexed for the checks. */
 type Node = {
   key: string;
@@ -1064,11 +1123,12 @@ class Door {
   private lentText(): string {
     const actors = this.lentActors().map((a) => `${a.name} (${a.kind})`);
     const minted = Object.keys(this.chart.agents ?? {});
-    return `lent: ${names(actors)}; kit: ${this.lends.gate ? "gate" : "none"}; minted: ${names(minted)}`;
+    const kit = [...(this.lends.gate ? ["gate"] : []), ...(this.lends.fail ? ["fail"] : [])];
+    return `lent: ${names(actors)}; kit: ${kit.length ? kit.join(", ") : "none"}; minted: ${names(minted)}`;
   }
 
   /** What an invoke's `src` names, or undefined after a refusal line. */
-  private srcKind(src: string, path: string): "agent" | "minted" | "effect" | "machine" | "gate" | undefined {
+  private srcKind(src: string, path: string): InvokeKind | undefined {
     const lentNow = (name: string) => name in this.lent.actors;
     const declared = [...this.lends.agents, ...this.lends.effects, ...this.lends.machines];
     if (declared.includes(src) && !lentNow(src)) {
@@ -1089,6 +1149,14 @@ class Door {
       );
       return undefined;
     }
+    if (src === "fail") {
+      if (this.lends.fail) return "fail";
+      this.fail(
+        3,
+        `${path}: "fail" is the kit's Part that ends the run as a Failure, and this Open body does not lend it (\`lends.fail: true\` would); ${this.lentText()}`,
+      );
+      return undefined;
+    }
     if (Object.hasOwn(this.chart.agents ?? {}, src)) return "minted";
     this.fail(3, `${path}: "${src}" is not a lent actor or an Agent of this Chart; ${this.lentText()}`);
     return undefined;
@@ -1103,11 +1171,16 @@ class Door {
       this.sentBys.push({ id: (guard.params as { id: string }).id, path: `${path}.params.id` });
       return;
     }
+    if (guard.type === FAILURE_GUARD) {
+      if (guard.params !== undefined) this.fail(3, `${path}.params: "${FAILURE_GUARD}" takes no params`);
+      return;
+    }
     this.checkGuardName(guard.type, `${path}.type`);
     if (guard.params !== undefined) this.checkRefs(guard.params, `${path}.params`, scope);
   }
 
   private checkGuardName(name: string, path: string): void {
+    if (name === FAILURE_GUARD) return;
     const lent = this.lends.guards.filter((g) => g in this.lent.guards);
     if (this.lends.guards.includes(name) && !(name in this.lent.guards)) {
       this.fail(
@@ -1117,7 +1190,7 @@ class Door {
     } else if (!this.lends.guards.includes(name)) {
       this.fail(
         3,
-        `${path}: "${name}" is not a lent guard; lent guards: ${names(lent)} (and ${SENT_BY} with params { id })`,
+        `${path}: "${name}" is not a lent guard; lent guards: ${names(lent)} (and ${SENT_BY} with params { id }, and ${FAILURE_GUARD})`,
       );
     }
   }
@@ -1262,7 +1335,7 @@ class Door {
   // --- rule 5: minted Agents ------------------------------------------------------------------------
 
   private checkAgents(): void {
-    const lentNames = new Set([...this.lends.agents, ...this.lends.effects, ...this.lends.machines, "gate"]);
+    const lentNames = new Set([...this.lends.agents, ...this.lends.effects, ...this.lends.machines, "gate", "fail"]);
     for (const [slot, a] of Object.entries(this.chart.agents ?? {})) {
       const path = `agents.${slot}`;
       if (lentNames.has(slot)) {
@@ -1835,15 +1908,12 @@ class Door {
 
   // --- rule 8: lent input shapes --------------------------------------------------------------------
 
-  private checkInvokeInput(
-    inv: ChartInvoke,
-    kind: "agent" | "minted" | "effect" | "machine" | "gate",
-    path: string,
-  ): void {
+  private checkInvokeInput(inv: ChartInvoke, kind: InvokeKind, path: string): void {
     const ipath = `${path}.input`;
     const input = inv.input;
     const isObject = typeof input === "object" && input !== null && !Array.isArray(input) && !("$ref" in input);
     if (kind === "machine") return;
+    if (kind === "fail") return this.checkFailInput(input, isObject, ipath);
     if (kind === "gate") {
       if (input === undefined) return;
       if (!isObject) return this.fail(8, `${ipath}: a Gate's input is an object of gate (a name) and meta`);
@@ -1864,6 +1934,23 @@ class Door {
     if (kind === "effect") {
       const logic = this.lent.actors[inv.src];
       const keys = isEffect(logic) ? inputKeysOf(logic.effect) : undefined;
+      if (keys === undefined && isEffect(logic) && logic.effect.kind === "dispatch") {
+        // A dispatch with no input schema has no keys to hold the Chart to: its input is the run's
+        // body, and the callee's door is the check (ADR-0071). Its values are what any Effect's
+        // input slot takes.
+        if (input === undefined) return;
+        if (!isObject) {
+          return this.fail(
+            8,
+            `${ipath}: the lent dispatch "${inv.src}" takes an object, the run's body — the callee's door checks it`,
+          );
+        }
+        for (const [k, v] of Object.entries(input as Record<string, unknown>)) {
+          if (typeof v !== "string" && !isRef(v))
+            this.fail(8, `${ipath}.${k}: an Effect's input slot takes a string or a reference`);
+        }
+        return;
+      }
       if (keys === undefined) {
         return this.fail(
           8,
@@ -1895,6 +1982,24 @@ class Door {
     this.checkAgentInput(inv.src, kind, input, isObject, ipath);
   }
 
+  /** The input of `fail` (ADR-0073): `{ reason, detail? }`, `reason` a text for a person (a string
+   * or a reference), `detail` any value. */
+  private checkFailInput(input: unknown, isObject: boolean, ipath: string): void {
+    if (!isObject) {
+      return this.fail(8, `${ipath}: \`fail\` takes { reason, detail? }: reason is a text for a person`);
+    }
+    for (const key of Object.keys(input as Record<string, unknown>)) {
+      if (key !== "reason" && key !== "detail") {
+        this.fail(8, `${ipath}.${key}: \`fail\` takes reason and detail only`);
+      }
+    }
+    const reason = (input as Record<string, unknown>).reason;
+    if (reason === undefined) this.fail(8, `${ipath}.reason: \`fail\` needs a reason, a text for a person`);
+    else if ((typeof reason !== "string" || reason === "") && !isRef(reason)) {
+      this.fail(8, `${ipath}.reason: a reason is a string that is not empty, or a reference`);
+    }
+  }
+
   /**
    * An Agent invoke's input is a Turn's Frame and Dials (ADR-0057): `prompt` (a string), and
    * optionally `cwd`, `continue: true`, a `model` the Open body allows, and a `thinkingLevel`.
@@ -1953,9 +2058,10 @@ class Door {
  * The JSON Schema keywords a Chart event's payload may use (ADR-0070, rule 4). The Orchestrator
  * checks every pick against this schema in its own process, before the Allowed check, so a keyword
  * whose cost the door cannot bound is refused by name: `pattern` (a backtracking regex),
- * `patternProperties`, `$ref`, the combinators and the conditionals.
+ * `patternProperties`, `$ref`, the combinators and the conditionals. It is also the subset a
+ * dispatch's slot schema and its callee's door are compared within (ADR-0071, door-compat.ts).
  */
-const PAYLOAD_KEYWORDS = new Set([
+export const PAYLOAD_KEYWORDS: ReadonlySet<string> = new Set([
   "type",
   "properties",
   "required",
@@ -1981,6 +2087,39 @@ const PAYLOAD_KEYWORDS = new Set([
  * the payload name the event a Chart receives (registration.ts builds `{ type, ...payload }`).
  */
 function payloadSchemaFaults(schema: unknown): Array<{ path: PropertyKey[]; message: string }> {
+  const out = subsetFaults(
+    schema,
+    (key) =>
+      `"${key}" is not a keyword a Chart event's payload may use; it may use ${[...PAYLOAD_KEYWORDS].join(", ")}`,
+  );
+  const props = (schema as { properties?: unknown } | null)?.properties;
+  if (typeof props === "object" && props !== null && Object.hasOwn(props, "type")) {
+    out.push({
+      path: ["properties", "type"],
+      message: "a payload field named `type` is refused: jr2 writes the event's type, and the payload never names it",
+    });
+  }
+  return out;
+}
+
+/**
+ * The faults of a door's JSON Schema, or of a dispatch slot's (ADR-0071): every keyword not in
+ * {@link PAYLOAD_KEYWORDS} and a list-form `items` — the payload rules without the Chart's own one
+ * (a field named `type` is a door's to have). A schema with a fault is reported "not compared":
+ * outside the subset, a comparison would be a guess.
+ */
+export function doorSchemaFaults(schema: unknown): Array<{ path: PropertyKey[]; message: string }> {
+  return subsetFaults(
+    schema,
+    (key) => `"${key}" is outside the JSON Schema subset jr2 compares (${[...PAYLOAD_KEYWORDS].join(", ")})`,
+  );
+}
+
+/** The subset's faults: `outside` words the fault of a keyword not in it, for whose rule it is. */
+function subsetFaults(
+  schema: unknown,
+  outside: (key: string) => string,
+): Array<{ path: PropertyKey[]; message: string }> {
   const out: Array<{ path: PropertyKey[]; message: string }> = [];
   const walk = (node: unknown, path: PropertyKey[]): void => {
     if (typeof node === "boolean" && path.length && path[path.length - 1] === "additionalProperties") return;
@@ -1993,7 +2132,7 @@ function payloadSchemaFaults(schema: unknown): Array<{ path: PropertyKey[]; mess
       if (!PAYLOAD_KEYWORDS.has(key)) {
         out.push({
           path: [...path, key],
-          message: `"${key}" is not a keyword a Chart event's payload may use; it may use ${[...PAYLOAD_KEYWORDS].join(", ")}`,
+          message: outside(key),
         });
         continue;
       }
@@ -2012,13 +2151,6 @@ function payloadSchemaFaults(schema: unknown): Array<{ path: PropertyKey[]; mess
     }
   };
   walk(schema, []);
-  const props = (schema as { properties?: unknown } | null)?.properties;
-  if (typeof props === "object" && props !== null && Object.hasOwn(props, "type")) {
-    out.push({
-      path: ["properties", "type"],
-      message: "a payload field named `type` is refused: jr2 writes the event's type, and the payload never names it",
-    });
-  }
   return out;
 }