@jr2/orchestrator 0.4.1 → 0.5.1

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,84 @@
+// @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 "./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/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 = {
@@ -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,6 +412,16 @@ function effectDoc(parts: EffectParts): EffectDoc {
     const { sign, squash, force, pin, timeoutMs, slot } = parts;
     return { kind: "push", sign, squash, force, pin, timeoutMs, ...(slot ? { slot } : {}) };
   }
+  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, slot, secrets, pin } = parts;
   return {
     kind: "command",

package/src/mechanism-routes.ts

@@ -0,0 +1,168 @@
+// A mechanism event must have a route (ADR-0074). jr2 sends `agent.fault` to the Machine that
+// invoked an Agent when the Agent's Turn cannot go on (ADR-0016), and `workspace()` sends
+// `workspace.lost` to its body when the Sandbox is gone (ADR-0012), and an Open body sends a
+// Chart's unrouted `agent.fault` to the Machine that invoked it (ADR-0070). Each is a relayed
+// event, and xstate drops an event that no active state handles. So the walk refuses a state that cannot
+// route one, and the run host faults a run in which none took one.
+//
+// - `refuseUnroutedAgentFault`: a state that invokes an Agent, or an Open body that can run one
+//   (it lends an Agent or allows a model), when that state and all its ancestors have no
+//   `agent.fault` route. In `jr2Setup().createMachine` and in the load walk (`partsOf`), beside the
+//   lost-output refusal, so `jr2 check`, `jr2 up` and the Orchestrator's load show it. Not for a
+//   compiled Chart: there the route is optional, and the Open body sends an `agent.fault` that no
+//   transition of the Chart takes to the Machine that invoked it (open-body.ts; ADR-0070).
+// - `refuseUnroutedLost`: a non-final leaf state of a `workspace()` body, when that state and all
+//   its ancestors have no `workspace.lost` route. In `workspace()`, the one place that knows that a
+//   Machine is a body. A compound or parallel state is not judged by itself: an event goes to the
+//   active leaves first, so a route on each leaf (or above it) is a route for the compound state.
+//   A final state of the root ends the body, so it is not judged. A nested final state is judged
+//   when its compound state has no `onDone`: the body then stays in the compound state, and a
+//   route on the compound state or above it is the route. The line names the compound state. A
+//   final state of a parallel region is not judged: the other regions are active, and their leaves
+//   are judged.
+// - `unroutedMechanismEvent`: the runtime half, for a route that the walk cannot judge (a guard
+//   that is false when the event comes). The run host reads it off each microstep.
+//
+// A route is any transition for the event: one with actions only counts, because it can be a
+// deliberate `reenter: true` that invokes the Agent again. jr2 does not judge what a route does.
+// A wildcard (`"*"`, `"agent.*"`) that takes the event is a route too, as it is at runtime.
+
+import type { AnyStateMachine, StateNode } from "xstate";
+import { isAgent } from "./agent.ts";
+import { isOpenBody, openBodyDeclarationOf } from "./open-body.ts";
+
+/** The two mechanism events that must have a route. */
+const ROUTED_MECHANISM_EVENTS = ["agent.fault", "workspace.lost"] as const;
+
+type Node = StateNode<any, any>;
+
+/** Does a descriptor of a state's `on` take this event type? xstate's own match: the exact type,
+ * `"*"`, or a partial wildcard like `"agent.*"`. */
+function takes(descriptor: string, type: string): boolean {
+  if (descriptor === type || descriptor === "*") return true;
+  return descriptor.endsWith(".*") && type.startsWith(descriptor.slice(0, -1));
+}
+
+/** Does this state, or a state above it, have a route for `type`? */
+function routedAt(node: Node, type: string): boolean {
+  for (let at: Node | undefined = node; at !== undefined; at = at.parent) {
+    for (const descriptor of at.transitions.keys()) if (takes(descriptor, type)) return true;
+  }
+  return false;
+}
+
+/** Every state node of the tree below (and with) `node`, in document order. */
+function statesOf(node: Node): Node[] {
+  const out: Node[] = [node];
+  const children = Object.values(node.states as Record<string, Node>).sort((a, b) => a.order - b.order);
+  for (const child of children) out.push(...statesOf(child));
+  return out;
+}
+
+/** The text of one or more state ids, quoted. */
+function quoted(ids: readonly string[]): string {
+  return ids.map((id) => `"${id}"`).join(", ");
+}
+
+/** Is this slot an Open body that can run an Agent whose `agent.fault` comes to the Machine? One
+ * that lends an Agent or lets a Chart add its own: the body sends the Machine a Chart's unrouted
+ * `agent.fault`. A lent Machine routes its own Agents, and the walk judges it by itself. */
+function runsChartAgents(logic: unknown): boolean {
+  if (!isOpenBody(logic)) return false;
+  const decl = openBodyDeclarationOf(logic);
+  return (decl.lends.agents?.length ?? 0) > 0 || decl.allows.models.length > 0;
+}
+
+/**
+ * Refuse a Machine with a state that invokes an Agent, or an Open body that can run one, when that
+ * state and all its ancestors have no `agent.fault` route (ADR-0074). The slots are the Machine's
+ * own `actors`. Throws one line that names each state, the event and the route to write.
+ */
+export function refuseUnroutedAgentFault(machine: AnyStateMachine): void {
+  const actors = (machine.implementations.actors ?? {}) as Record<string, unknown>;
+  const agents: string[] = [];
+  const bodies: string[] = [];
+  for (const node of statesOf(machine.root as Node)) {
+    if (routedAt(node, "agent.fault")) continue;
+    const srcs = node.invoke.map((inv) => (typeof inv.src === "string" ? actors[inv.src] : undefined));
+    if (srcs.some((logic) => isAgent(logic))) agents.push(node.id);
+    else if (srcs.some((logic) => runsChartAgents(logic))) bodies.push(node.id);
+  }
+  if (!agents.length && !bodies.length) return;
+  const clause = (ids: string[], what: string) =>
+    `${ids.length > 1 ? "states" : "state"} ${quoted(ids)} ${ids.length > 1 ? "invoke" : "invokes"} ${what}`;
+  const what = [
+    ...(agents.length ? [clause(agents, "an Agent")] : []),
+    ...(bodies.length ? [clause(bodies, "an Open body that can run an Agent")] : []),
+  ].join(", and ");
+  const many = agents.length + bodies.length > 1;
+  throw new Error(
+    `machine "${machine.id}": ${what}, and no route for "agent.fault" is on ${many ? "them" : "it"} or on a state ` +
+      `above — jr2 sends agent.fault when the Agent's Turn cannot go on, and with no route the run faults: route it ` +
+      `on that state or on a state above it, as on: { "agent.fault": "<the state that handles it>" } (ADR-0074)`,
+  );
+}
+
+/** Does the body stay in this final state? It does when the final state is nested, its compound
+ * state has no `onDone`, and that compound state is no region of a parallel state. */
+function staysIn(final: Node): boolean {
+  const parent = final.parent;
+  if (parent === undefined || parent.parent === undefined) return false;
+  if (parent.parent.type === "parallel") return false;
+  return !parent.transitions.has(`xstate.done.state.${parent.id}`);
+}
+
+/**
+ * Refuse a `workspace()` body with a state that is not final, that it can stay in, when that state
+ * and all its ancestors have no `workspace.lost` route (ADR-0074). Throws one line that names each
+ * state, the event and the route to write.
+ */
+export function refuseUnroutedLost(body: AnyStateMachine): void {
+  // The leaves: an atomic state, a root with no child state, or a final state that the body can stay
+  // in. A history state is no state the body is in.
+  const unrouted = statesOf(body.root as Node)
+    .filter((node) => Object.keys(node.states).length === 0 && node.type !== "history")
+    .filter((node) => node.type !== "final" || staysIn(node))
+    .filter((node) => !routedAt(node, "workspace.lost"))
+    // The body stays in the compound state of a final state that it can stay in, and that state is
+    // not final: the line names it.
+    .map((node) => (node.type === "final" ? node.parent!.id : node.id));
+  if (!unrouted.length) return;
+  const many = unrouted.length > 1;
+  throw new Error(
+    `workspace(): the body "${body.id}" has ${many ? "states" : "a state"} ${quoted(unrouted)} that ` +
+      `${many ? "are" : "is"} not final, and no route for "workspace.lost" is on ${many ? "them" : "it"} or on a ` +
+      `state above — jr2 sends workspace.lost to the body when its Sandbox is gone, and with no route the run ` +
+      `faults: route it on the body's root, as on: { "workspace.lost": "<the state that handles it>" } (ADR-0074)`,
+  );
+}
+
+/** The parts of an `@xstate.microstep` inspection event that the runtime check reads. */
+export type MicrostepView = {
+  actorRef: { id: string; getSnapshot(): unknown; logic?: unknown };
+  event: { type: string; reason?: unknown };
+  snapshot?: unknown;
+  _transitions?: readonly unknown[];
+};
+
+/**
+ * The fault of a microstep in which a Machine got `agent.fault` or `workspace.lost` and took no
+ * transition for it (ADR-0074), or undefined for every other microstep. The text names the event,
+ * the Machine and its state, and the event's `reason`. For `workspace.lost` this is the body's
+ * microstep: the wrapper always takes its own transition, to forward the event to the body.
+ */
+export function unroutedMechanismEvent(ev: MicrostepView): string | undefined {
+  const type = ev.event?.type;
+  if (!(ROUTED_MECHANISM_EVENTS as readonly string[]).includes(type)) return undefined;
+  if (ev._transitions === undefined || ev._transitions.length > 0) return undefined;
+  const snapshot = (ev.snapshot ?? ev.actorRef.getSnapshot()) as { value?: unknown; status?: string } | undefined;
+  if (snapshot?.status !== undefined && snapshot.status !== "active") return undefined;
+  const machine = (ev.actorRef.logic as { id?: unknown } | undefined)?.id;
+  const name = typeof machine === "string" ? machine : ev.actorRef.id;
+  const reason = typeof ev.event.reason === "string" && ev.event.reason !== "" ? ev.event.reason : "no reason given";
+  return (
+    `machine "${name}" got "${type}" in state ${JSON.stringify(snapshot?.value ?? null)}, and no transition took ` +
+    `it (${reason}) — no route for "${type}" is on that state or on a state above, or the guard of each route ` +
+    `was false: route it with a transition that is always taken (ADR-0074)`
+  );
+}

package/src/model-keys.generated.ts

@@ -0,0 +1,53 @@
+// Made from @earendil-works/pi-ai 1.4.0 by `just model-keys` (packages/harness/scripts/model-keys.ts).
+// Do not edit: run the recipe at each pi bump. `model-keys.ts` says what the table means (ADR-0059).
+
+import type { ModelKey } from "./model-keys.ts";
+
+export const MODEL_KEYS: Readonly<Record<string, ModelKey>> = {
+  // No default host: the calls go to more than one host: bedrock-runtime.us-east-1.amazonaws.com, bedrock-runtime.eu-central-1.amazonaws.com.
+  AWS_BEARER_TOKEN_BEDROCK: { providers: ["amazon-bedrock"] },
+  ANT_LING_API_KEY: { providers: ["ant-ling"], host: "api.ant-ling.com" },
+  ANTHROPIC_AUTH_TOKEN: { providers: ["anthropic"], host: "api.anthropic.com" },
+  ANTHROPIC_OAUTH_TOKEN: { providers: ["anthropic"], host: "api.anthropic.com" },
+  ANTHROPIC_API_KEY: { providers: ["anthropic"], host: "api.anthropic.com" },
+  // No default host: the catalog names no base URL.
+  AZURE_OPENAI_API_KEY: { providers: ["azure"] },
+  BASETEN_API_KEY: { providers: ["baseten"], host: "inference.baseten.co" },
+  CEREBRAS_API_KEY: { providers: ["cerebras"], host: "api.cerebras.ai" },
+  // No default host: a base URL is a template.
+  CLOUDFLARE_API_KEY: { providers: ["cloudflare-ai-gateway", "cloudflare-workers-ai"] },
+  DEEPSEEK_API_KEY: { providers: ["deepseek"], host: "api.deepseek.com" },
+  FIREWORKS_API_KEY: { providers: ["fireworks"], host: "api.fireworks.ai" },
+  COPILOT_GITHUB_TOKEN: { providers: ["github-copilot"], host: "api.individual.githubcopilot.com" },
+  GEMINI_API_KEY: { providers: ["google"], host: "generativelanguage.googleapis.com" },
+  // No default host: a base URL is a template.
+  GOOGLE_CLOUD_API_KEY: { providers: ["google-vertex"] },
+  GROQ_API_KEY: { providers: ["groq"], host: "api.groq.com" },
+  HF_TOKEN: { providers: ["huggingface"], host: "router.huggingface.co" },
+  KIMI_API_KEY: { providers: ["kimi-coding"], host: "api.kimi.com" },
+  META_API_KEY: { providers: ["meta"], host: "api.meta.ai" },
+  MINIMAX_API_KEY: { providers: ["minimax"], host: "api.minimax.io" },
+  MINIMAX_CN_API_KEY: { providers: ["minimax-cn"], host: "api.minimaxi.com" },
+  MISTRAL_API_KEY: { providers: ["mistral"], host: "api.mistral.ai" },
+  // No default host: the calls go to more than one host: api.moonshot.ai, api.moonshot.cn.
+  MOONSHOT_API_KEY: { providers: ["moonshotai", "moonshotai-cn"] },
+  NVIDIA_API_KEY: { providers: ["nvidia"], host: "integrate.api.nvidia.com" },
+  OPENAI_API_KEY: { providers: ["openai"], host: "api.openai.com" },
+  OPENCODE_API_KEY: { providers: ["opencode", "opencode-go"], host: "opencode.ai" },
+  OPENROUTER_API_KEY: { providers: ["openrouter"], host: "openrouter.ai" },
+  QWEN_TOKEN_PLAN_API_KEY: {
+    providers: ["qwen-token-plan", "qwen-token-plan-individual"],
+    host: "token-plan.ap-southeast-1.maas.aliyuncs.com",
+  },
+  QWEN_TOKEN_PLAN_CN_API_KEY: { providers: ["qwen-token-plan-cn"], host: "token-plan.cn-beijing.maas.aliyuncs.com" },
+  RADIUS_API_KEY: { providers: ["radius"], host: "radius.pi.dev" },
+  TOGETHER_API_KEY: { providers: ["together"], host: "api.together.ai" },
+  AI_GATEWAY_API_KEY: { providers: ["vercel-ai-gateway"], host: "ai-gateway.vercel.sh" },
+  XAI_API_KEY: { providers: ["xai"], host: "api.x.ai" },
+  XIAOMI_API_KEY: { providers: ["xiaomi"], host: "api.xiaomimimo.com" },
+  XIAOMI_TOKEN_PLAN_AMS_API_KEY: { providers: ["xiaomi-token-plan-ams"], host: "token-plan-ams.xiaomimimo.com" },
+  XIAOMI_TOKEN_PLAN_CN_API_KEY: { providers: ["xiaomi-token-plan-cn"], host: "token-plan-cn.xiaomimimo.com" },
+  XIAOMI_TOKEN_PLAN_SGP_API_KEY: { providers: ["xiaomi-token-plan-sgp"], host: "token-plan-sgp.xiaomimimo.com" },
+  ZAI_API_KEY: { providers: ["zai"], host: "api.z.ai" },
+  ZAI_CODING_CN_API_KEY: { providers: ["zai-coding-cn"], host: "open.bigmodel.cn" },
+};

package/src/model-keys.ts

@@ -1,17 +1,29 @@
 // The known model keys (ADR-0059): every env var pi's catalog reads a provider's credential from,
 // the catalog provider(s) that read it, and the one host those providers' calls go to by default.
 //
-// A COPY of pi's data at the exact pin `@jr2/harness` holds, because this package has no pi
-// dependency and must not grow one: `jr2 up` reads this table host-side (R1, and the default
-// `hosts` of a held secret), and the in-cluster Orchestrator never touches pi. The copy cannot
-// drift silently — `@jr2/harness`'s `model-keys.test.ts` checks it against pi itself, env names per
-// provider and every provider's default host, in the default gate. A pi bump that adds or moves a
-// provider fails there first, the same canary role Harness conformance plays (ADR-0027).
+// pi's data at the exact pin `@jr2/harness` holds, made into plain data by a script, because this
+// package has no pi dependency and must not grow one: `jr2 up` reads this table host-side (R1, and
+// the default `hosts` of a held secret), and the in-cluster Orchestrator never touches pi. The table
+// is `model-keys.generated.ts`, and `just model-keys` writes it from pi-ai at each pi bump
+// (`packages/harness/scripts/model-keys.ts`). It cannot drift silently: `@jr2/harness`'s
+// `model-keys.test.ts` checks it against pi itself, env names per provider and every provider's
+// default host, in the default gate. A pi bump that adds or moves a provider fails there first, the
+// same canary role Harness conformance plays (ADR-0027).
 //
 // `host` is present only when every model of every provider that reads the name goes to ONE static
 // host. It is absent when there is none: the base URL is a template (`{location}`, an account id),
 // the providers disagree (MOONSHOT_API_KEY serves two regions), or the host is regional (Bedrock).
 // A held secret with such a name must then say its `hosts` itself (§3.4 of the spec, R5).
+//
+// Two facts the data does not say. anthropic reads three names: AUTH_TOKEN goes as `Authorization:
+// Bearer`, the other two as `x-api-key` (an `sk-ant-oat` value is an OAuth token, which a Stand-in
+// never is). AWS_BEARER_TOKEN_BEDROCK is the bearer form of Bedrock auth, which pi reads through
+// its credential chain; SigV4 credentials cannot be held at all — a signature is not a header a
+// Stand-in can be swapped into — and `jr2 up` warns on them (`SIGNING_CREDENTIALS`).
+
+import { MODEL_KEYS } from "./model-keys.generated.ts";
+
+export { MODEL_KEYS };
 
 /** One known model-key env name. */
 export type ModelKey = {
@@ -21,58 +33,6 @@ export type ModelKey = {
   host?: string;
 };
 
-export const MODEL_KEYS: Readonly<Record<string, ModelKey>> = {
-  // anthropic reads three names. AUTH_TOKEN goes as `Authorization: Bearer`, the other two as
-  // `x-api-key` (an `sk-ant-oat` value is an OAuth token, which a Stand-in never is).
-  ANTHROPIC_API_KEY: { providers: ["anthropic"], host: "api.anthropic.com" },
-  ANTHROPIC_AUTH_TOKEN: { providers: ["anthropic"], host: "api.anthropic.com" },
-  ANTHROPIC_OAUTH_TOKEN: { providers: ["anthropic"], host: "api.anthropic.com" },
-  OPENAI_API_KEY: { providers: ["openai"], host: "api.openai.com" },
-  GEMINI_API_KEY: { providers: ["google"], host: "generativelanguage.googleapis.com" },
-  // `https://{location}-aiplatform.googleapis.com` — regional, so no default.
-  GOOGLE_CLOUD_API_KEY: { providers: ["google-vertex"] },
-  COPILOT_GITHUB_TOKEN: { providers: ["github-copilot"], host: "api.individual.githubcopilot.com" },
-  // The bearer form of Bedrock auth. Regional, so no default. (SigV4 credentials cannot be held at
-  // all — a signature is not a header a Stand-in can be swapped into — and `jr2 up` warns on them.)
-  AWS_BEARER_TOKEN_BEDROCK: { providers: ["amazon-bedrock"] },
-  ANT_LING_API_KEY: { providers: ["ant-ling"], host: "api.ant-ling.com" },
-  QWEN_TOKEN_PLAN_API_KEY: {
-    providers: ["qwen-token-plan"],
-    host: "token-plan.ap-southeast-1.maas.aliyuncs.com",
-  },
-  QWEN_TOKEN_PLAN_CN_API_KEY: { providers: ["qwen-token-plan-cn"], host: "token-plan.cn-beijing.maas.aliyuncs.com" },
-  // The catalog names no base URL: an Azure deployment is the user's own resource.
-  AZURE_OPENAI_API_KEY: { providers: ["azure-openai-responses"] },
-  NVIDIA_API_KEY: { providers: ["nvidia"], host: "integrate.api.nvidia.com" },
-  DEEPSEEK_API_KEY: { providers: ["deepseek"], host: "api.deepseek.com" },
-  GROQ_API_KEY: { providers: ["groq"], host: "api.groq.com" },
-  CEREBRAS_API_KEY: { providers: ["cerebras"], host: "api.cerebras.ai" },
-  XAI_API_KEY: { providers: ["xai"], host: "api.x.ai" },
-  // pi reads the name, and its catalog lists no model for the provider at this pin.
-  RADIUS_API_KEY: { providers: ["radius"] },
-  OPENROUTER_API_KEY: { providers: ["openrouter"], host: "openrouter.ai" },
-  AI_GATEWAY_API_KEY: { providers: ["vercel-ai-gateway"], host: "ai-gateway.vercel.sh" },
-  ZAI_API_KEY: { providers: ["zai"], host: "api.z.ai" },
-  ZAI_CODING_CN_API_KEY: { providers: ["zai-coding-cn"], host: "open.bigmodel.cn" },
-  MISTRAL_API_KEY: { providers: ["mistral"], host: "api.mistral.ai" },
-  MINIMAX_API_KEY: { providers: ["minimax"], host: "api.minimax.io" },
-  MINIMAX_CN_API_KEY: { providers: ["minimax-cn"], host: "api.minimaxi.com" },
-  // Two providers, two hosts (`.ai` and `.cn`): no single default.
-  MOONSHOT_API_KEY: { providers: ["moonshotai", "moonshotai-cn"] },
-  HF_TOKEN: { providers: ["huggingface"], host: "router.huggingface.co" },
-  FIREWORKS_API_KEY: { providers: ["fireworks"], host: "api.fireworks.ai" },
-  TOGETHER_API_KEY: { providers: ["together"], host: "api.together.ai" },
-  // Two providers, one host.
-  OPENCODE_API_KEY: { providers: ["opencode", "opencode-go"], host: "opencode.ai" },
-  KIMI_API_KEY: { providers: ["kimi-coding"], host: "api.kimi.com" },
-  // Account-templated base URLs.
-  CLOUDFLARE_API_KEY: { providers: ["cloudflare-workers-ai", "cloudflare-ai-gateway"] },
-  XIAOMI_API_KEY: { providers: ["xiaomi"], host: "api.xiaomimimo.com" },
-  XIAOMI_TOKEN_PLAN_CN_API_KEY: { providers: ["xiaomi-token-plan-cn"], host: "token-plan-cn.xiaomimimo.com" },
-  XIAOMI_TOKEN_PLAN_AMS_API_KEY: { providers: ["xiaomi-token-plan-ams"], host: "token-plan-ams.xiaomimimo.com" },
-  XIAOMI_TOKEN_PLAN_SGP_API_KEY: { providers: ["xiaomi-token-plan-sgp"], host: "token-plan-sgp.xiaomimimo.com" },
-};
-
 /** Every catalog provider id some known model key belongs to — the set `harness.catalog` may name. */
 export const MODEL_KEY_PROVIDERS: ReadonlySet<string> = new Set(
   Object.values(MODEL_KEYS).flatMap((key) => key.providers),