@jr2/orchestrator 0.4.1 → 0.5.1

package/src/parts.ts

@@ -51,10 +51,13 @@ import type { AnyActorRef, AnyStateMachine, StateNode, UnknownActorLogic } from
 import { isAgent, isOpenAgent, type AgentDeclaration } from "./agent.ts";
 import { argvText, isEffect, placementOf, type EffectParts, type Placement } from "./effect.ts";
 import { effectBindingLine, openPartsOf, type OpenEffectPart } from "./open-effect.ts";
+import { isFailSlot } from "./fail.ts";
 import { isImageContext } from "./images.ts";
 import { isOpenBody, openBodyDeclarationOf, type OpenBodyDeclaration } from "./open-body.ts";
 import { open } from "./open.ts";
 import { repoIdentity } from "./repo-identity.ts";
+import { refuseUnroutedAgentFault } from "./mechanism-routes.ts";
+import { refuseLostOutput } from "./run-output.ts";
 import { userSeatOf, type Size, type UserContainer } from "./size.ts";
 
 // --- Repo Slots (ADR-0051) ---------------------------------------------------------------------
@@ -71,15 +74,103 @@ import { userSeatOf, type Size, type UserContainer } from "./size.ts";
 // meets it first, and `import { open } from "@jr2/orchestrator"` is the only spelling anyone writes.
 export { open } from "./open.ts";
 
-/** What a Repo Slot resolves to (GLOSSARY.md "Binding"): the url, and the base the branch
- * Worktree is cut from — absent, the Repo's own default branch. */
-export type Binding = { url: string; ref?: string };
+/**
+ * The repository of a Repo Slot: `{ url, ref }`. `url` is the Repo's git url. `ref` is the branch
+ * or commit that the branch Worktree starts from; absent, the Repo's default branch. Where only a
+ * url is needed, a string is enough.
+ *
+ * `workspace()` and `customize()` refuse:
+ * - an empty `url`: ``<where>: Repo Slot "<slot>" is bound to an empty url (got <value>) — a slot
+ *   is `open`, a url, `{ url, ref? }`, or a mapper `({ input }) => url | { url, ref? }` over the
+ *   door (ADR-0051).``
+ * - an empty `ref`: the same text, with `bound with an empty ref` in place of `bound to an empty
+ *   url`.
+ * - a url that names no Repo, such as a relative path: ``<where>: Repo Slot "<slot>" binds
+ *   "<url>", which names no Repo — <reason> (ADR-0051).``
+ *
+ * @example
+ * ```ts
+ * import { jr2Setup, workspace, type Binding } from "@jr2/orchestrator";
+ *
+ * const app: Binding = { url: "https://github.com/you/app.git", ref: "release-2" };
+ *
+ * const body = jr2Setup().createMachine({
+ *   id: "body",
+ *   initial: "done",
+ *   states: { done: { type: "final" } },
+ * });
+ *
+ * export const machine = workspace(body, {
+ *   repos: { app },
+ *   spec: () => ({ branch: "jr2/hotfix" }),
+ * });
+ * ```
+ *
+ * @see docs/concepts/workspaces.md
+ * @see docs/reference/decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md
+ */
+// What a Repo Slot resolves to (GLOSSARY.md "Binding").
+export type Binding = {
+  /** The Repo's git url. */
+  url: string;
+  /** The branch or commit that the branch Worktree starts from. Default: the Repo's default
+   * branch. */
+  ref?: string;
+};
 
+// Bound and open are what `jr2 up` can see; per-run is the run's business, fenced at attach by
+// `git.credentials` (ADR-0051).
 /**
- * One Repo Slot's value: BOUND (a url, or `{ url, ref? }`), OPEN (the {@link open} sentinel —
- * someone downstream binds it), or PER-RUN (a mapper over the wrapper's door, so a run input — a
- * ticket field — decides). Bound and open are what `jr2 up` can see; per-run is the run's business,
- * fenced at attach by `git.credentials` (ADR-0051).
+ * The value of one Repo Slot in `workspace({ repos })`. One of:
+ * - a url, or a {@link Binding} `{ url, ref }`: the Machine names the Repo.
+ * - {@link open}: the Instance that registers the Machine binds it with `customize()`. `jr2 up`
+ *   refuses a Workflow that leaves it open: ``refusing: workflow "<name>" leaves Repo Slot
+ *   "<slot>" open — bind it where the Machine is registered: export const machine =
+ *   customize(<import>, …)  (ADR-0051)``, with the whole `customize` line to paste.
+ * - a function of the run input, `({ input }) => url` or a {@link Binding}: each run chooses. The
+ *   url must match an entry of `git.credentials` in `jr2.config.ts`, or the run cannot use it.
+ *
+ * The key of the slot is a directory name under `/work`. It starts with a letter, and
+ * `workspace()` and `customize()` refuse a key that does not: ``<where>: Repo Slot key "<key>" is
+ * not a directory name — a slot becomes `/work/<slot>` and its order matters, so it starts with a
+ * letter and matches /^[A-Za-z][A-Za-z0-9._-]*$/ (ADR-0051).`` They refuse a value of another
+ * shape: ``<where>: Repo Slot "<slot>" is <what> — a slot is `open`, a url, `{ url, ref? }`, or a
+ * mapper `({ input }) => url | { url, ref? }` over the door (ADR-0051).``
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { jr2Setup, open, workspace, type RepoSlot, type Workspaced } from "@jr2/orchestrator";
+ *
+ * const runInput = z.object({ service: z.string() });
+ * type RunInput = z.infer<typeof runInput>;
+ *
+ * const service: RepoSlot<RunInput> = ({ input }) => `https://github.com/you/${input.service}.git`;
+ *
+ * const body = jr2Setup({
+ *   types: {} as { input: Workspaced<RunInput, "service" | "docs" | "config"> },
+ * }).createMachine({
+ *   id: "body",
+ *   initial: "done",
+ *   states: { done: { type: "final" } },
+ * });
+ *
+ * // A Machine for a package: the Instance that registers it binds `config`.
+ * export const deploy = workspace(body, {
+ *   input: runInput,
+ *   repos: {
+ *     service,
+ *     docs: "https://github.com/you/docs.git",
+ *     config: open,
+ *   },
+ *   spec: ({ input }) => ({ branch: `deploy/${input.service}` }),
+ * });
+ * ```
+ *
+ * @see docs/concepts/workspaces.md
+ * @see docs/guides/bind-open-parts.md
+ * @see docs/guides/give-the-cluster-git-credentials.md
+ * @see docs/reference/decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md
  */
 export type RepoSlot<TInput = unknown> =
   | typeof open
@@ -199,8 +290,8 @@ export function sandboxPartsOf(machine: AnyStateMachine | undefined): SandboxPar
 
 /** Does this Machine COMPOSE a Sandbox — i.e. is it a `workspace()` wrapper? Distinct from
  * `sandboxPartsOf(m)` naming no image: a wrapper that names neither image still owns the two
- * seats, which is what `customize({ image })` retunes (ADR-0049) — and it always carries at least
- * one Repo Slot (ADR-0051). Also the data-plane switch, read off the walk: an Instance needs
+ * seats, which is what `customize({ image })` retunes (ADR-0049) — and it may carry no Repo Slot
+ * at all (ADR-0051). Also the data-plane switch, read off the walk: an Instance needs
  * Sandboxes exactly when a registered Machine composes one. A logic with no `config` (an Effect's,
  * ADR-0067) composes none. */
 export function composesSandbox(machine: AnyStateMachine): boolean {
@@ -492,11 +583,34 @@ export type CarriedEffect = {
     /** A push (ADR-0067, ADR-0051): the Workspace's branch to its Repo Slot's Binding. It names no
      * secret: `jr2 up` resolves its credential through `git.credentials`. */
     | { kind: "push"; slot?: string; sign: boolean; squash: boolean; force: boolean; pin: boolean; secrets: string[] }
+    /** A dispatch (ADR-0071): the Workflow it starts a run of, as `jr2 run` names it, whether it
+     * waits, and — toward another Orchestrator — the target's origin as an http target and its
+     * token as the one secret (placed in the Instance Effector beside the http Effects). No target:
+     * it runs in the Orchestrator's own process and names no secret. `input`: the slot's input
+     * schema as JSON Schema, what the walk compares with the callee's door; absent, the door alone
+     * checks. An Open target has no target and no secret yet. */
+    | {
+        kind: "dispatch";
+        workflow: string;
+        wait: boolean;
+        target?: { scheme: "http" | "https"; host: string; port: number };
+        secrets: string[];
+        input?: Record<string, unknown>;
+        open?: Array<"target">;
+      }
   );
 
+/** One state that can fail the run (ADR-0073): it invokes a `fail()` slot. `state` is the state's
+ * id, `machine` the id of its Machine, `slot` the slot key it invokes, and `path` the `customize()`
+ * route to its Machine, as an {@link OpenSlot}'s. Static, as a Gate or an Effect is: the walk reads
+ * it, and `jr2 up`, `jr2 check` and the Machine doc list it. */
+export type CarriedFailure = { machine: string; state: string; slot: string; path: OpenSlot["path"] };
+
 /** Everything the registered Machines carry that a converge or a boot must act on. */
 export type CarriedParts = {
   agents: CarriedAgent[];
+  /** Every state that invokes a `fail()` slot (ADR-0073), in walk order, nested Machines too. */
+  failures: CarriedFailure[];
   /** Every Effect slot, in walk order — one per Machine and slot key, at the first route the walk
    * reached its Machine by. The placement reads {@link placedEffectsOf}: one per route. */
   effects: CarriedEffect[];
@@ -556,17 +670,18 @@ function inlineMachines(node: StateNode<any, any>): Array<{ machine: AnyStateMac
 }
 
 /**
- * Refuse a Part written inline on an `invoke.src` — an `agent()`, an Effect or a `workspace()` that
+ * Refuse a Part written inline on an `invoke.src` — an `agent()`, an Effect, a `fail()` or a `workspace()` that
  * is no key of the Machine's `actors` (see the module comment). Thrown at build by
  * `jr2Setup.createMachine` and at load by {@link partsOf}, so a Machine built with xstate's own
- * `createMachine` is refused where `jr2 up` and the Orchestrator read it. A plain child Machine
- * written inline is not a Part: it stays walked, with no `customize()` route (its `path` is
- * `undefined`).
+ * `createMachine` is refused where `jr2 check`, `jr2 up` and the Orchestrator read it. A plain
+ * child Machine written inline is not a Part: it stays walked, with no `customize()` route (its
+ * `path` is `undefined`).
  */
 export function refuseInlineParts(machine: AnyStateMachine): void {
   const partOf = (src: unknown): { part: string; written: string } | undefined => {
     if (isAgent(src)) return { part: "an Agent", written: "agent(...)" };
     if (isEffect(src)) return { part: "an Effect", written: `${src.effect.kind}(...)` };
+    if (isFailSlot(src)) return { part: "a fail() Part", written: "fail()" };
     const child = asMachine(src);
     if (child && composesSandbox(child)) return { part: "a Workspace", written: "workspace(...)" };
     return undefined;
@@ -615,6 +730,7 @@ function canonical(value: unknown): string {
  */
 export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
   const agents: CarriedAgent[] = [];
+  const failures: CarriedFailure[] = [];
   const effects: CarriedEffect[] = [];
   const images: CarriedImage[] = [];
   const repos: CarriedRepo[] = [];
@@ -690,6 +806,8 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
     if (walked.has(machine)) return;
     walked.add(machine);
     refuseInlineParts(machine);
+    refuseLostOutput(machine);
+    refuseUnroutedAgentFault(machine);
     const parts = sandboxPartsOf(machine);
     const user = userSeatOf(parts.user);
     collectImage(parts.image);
@@ -706,6 +824,7 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
       });
     }
     const body = wrapperBodyOf(machine);
+    for (const { state, slot } of failingStatesOf(machine)) failures.push({ machine: machine.id, state, slot, path });
     for (const [name, logic] of Object.entries(machine.implementations.actors as Record<string, unknown>)) {
       if (isAgent(logic)) collectAgent(path, name, logic.definition);
       else if (isOpenBody(logic)) {
@@ -735,6 +854,7 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
   for (const body of noneBodies) for (const m of body.declaration.allows.models) harnessModels.add(m);
   return {
     agents,
+    failures,
     effects,
     images,
     repos,
@@ -817,6 +937,23 @@ export function carriedEffectOf(
 ): CarriedEffect {
   const placement = placementOf(parts);
   const openParts = openPartsOf(parts);
+  if (parts.kind === "dispatch") {
+    const input = (parts as { [DISPATCH_INPUT]?: Record<string, unknown> })[DISPATCH_INPUT];
+    return {
+      name,
+      path,
+      route,
+      kind: "dispatch",
+      placement,
+      workflow: parts.workflow,
+      wait: parts.wait,
+      timeoutMs: parts.timeoutMs,
+      ...(parts.target === undefined || parts.target === open ? {} : { target: originTarget(parts.target.url) }),
+      secrets: [...parts.secrets],
+      ...(input !== undefined ? { input } : {}),
+      ...(openParts.length ? { open: openParts as Array<"target"> } : {}),
+    };
+  }
   if (parts.kind === "http") {
     return {
       name,
@@ -867,6 +1004,20 @@ export function carriedEffectOf(
   };
 }
 
+/** The key a dispatch's slot schema rides its parts under (dispatch-effect.ts): `Symbol.for`, so this
+ * walk reads it off a Machine built by another copy of the module (ADR-0071). */
+const DISPATCH_INPUT = Symbol.for("jr2.dispatch.input");
+
+/** A dispatch target's origin as the Effector's fence reads an http target: scheme, host, port. The
+ * origin was checked when the slot was built, so it parses. */
+function originTarget(url: string): { scheme: "http" | "https"; host: string; port: number } {
+  const u = new URL(url);
+  const scheme = u.protocol === "http:" ? "http" : "https";
+  // As an http target's: brackets off an IPv6 literal, lower case (http-effect.ts `targetOf`).
+  const host = u.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  return { scheme, host, port: u.port ? Number(u.port) : scheme === "http" ? 80 : 443 };
+}
+
 /**
  * One Workspace a Machine composes, as its pod's Held secrets are placed (ADR-0059): what the pod
  * names. Located like a {@link CarriedSize} — `path` is the `customize()` route to its
@@ -896,6 +1047,9 @@ export type WorkspacePod = {
   /** Each Repo Slot's Binding url as the Machine binds it, by slot, in order; undefined for an open
    * or per-run slot, whose url `jr2 up` cannot read. A push resolves its credential through it. */
   bindings: Record<string, string | undefined>;
+  /** The `workspace()` declares no Repo Slot (ADR-0051): it has only `/work`, which its steps
+   * share. Absent for one with slots, and for an Open map, whose slots the composer names. */
+  noSlot?: true;
 };
 
 /**
@@ -976,6 +1130,7 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
         ...(parts.effector ? { effector: { ...parts.effector } } : {}),
         ...(parts.image !== undefined ? { image: parts.image } : {}),
         bindings,
+        ...(parts.repos !== open && Object.keys(parts.repos).length === 0 ? { noSlot: true as const } : {}),
       });
     }
     const body = wrapperBodyOf(machine);
@@ -990,6 +1145,22 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
   return pods;
 }
 
+/** Every state of `machine`'s own tree that invokes a `fail()` slot (ADR-0073), in document order,
+ * with the slot key: a state that can fail the run. A child Machine's states are its own walk's. */
+export function failingStatesOf(machine: AnyStateMachine): Array<{ state: string; slot: string }> {
+  const actors = machine.implementations.actors as Record<string, unknown>;
+  const out: Array<{ state: string; slot: string }> = [];
+  const visit = (node: StateNode<any, any>): void => {
+    for (const inv of node.invoke) {
+      if (typeof inv.src === "string" && isFailSlot(actors[inv.src])) out.push({ state: node.id, slot: inv.src });
+    }
+    const children = Object.values(node.states as Record<string, StateNode<any, any>>);
+    for (const child of children.sort((a, b) => a.order - b.order)) visit(child);
+  };
+  visit(machine.root);
+  return out;
+}
+
 /** Every machine object written inline below `node`, at any depth of its state tree, with its hop. */
 function walkStates(node: StateNode<any, any>, visit: (machine: AnyStateMachine, hop: RouteHop) => void): void {
   for (const { machine, hop } of inlineMachines(node)) visit(machine, hop);

package/src/party.ts

@@ -24,9 +24,75 @@ import { vocabularyOf } from "./vocabulary.ts";
 /** The guard type `sentBy` names: dotted, so no author guard can take the name. */
 export const SENT_BY = "jr2.sentBy";
 
-/** A writing runs for this party's events, and for the Machine's own: `guard: sentBy("coder")`. The
- * id is an Agent slot, or a Gate's invoke id, of this Machine — an unknown id is refused at load. */
+/**
+ * A guard that is true for an event that one party sent, and false for an event that another party
+ * sent: `guard: sentBy("coder")`. Use it where two parties may send the same event to one state,
+ * and the transition must run for one of them only. It is also true for an event that the Machine
+ * sends itself, which has no sender.
+ *
+ * It can only make a transition decline the events of other parties. It never lets a party send
+ * an event that the party may not send at that state: the position of the `on` key decides that.
+ * When the guard is false, xstate tries the next transition for the event, as for any guard. Use
+ * it alone, or inside `and([…])`.
+ *
+ * `createMachine` refuses an id that is not a party of the Machine: ``machine "<id>":
+ * sentBy("<party>") on "<event>" at "<state>" names no party of this Machine (Agent slots:
+ * <slots>; Gate invoke ids: <ids>)``
+ *
+ * @param id - The party: the slot key of an Agent of this Machine, or the invoke `id` of one of its
+ *   Gates.
+ * @returns A named guard object, for a transition's `guard`.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { agent, defineEvent, fail, jr2Setup, sentBy } from "@jr2/orchestrator";
+ *
+ * const done = defineEvent({
+ *   name: "done",
+ *   description: "Call this when the draft is ready for review.",
+ *   input: z.object({}),
+ * });
+ *
+ * export const machine = jr2Setup({
+ *   events: [done],
+ *   actors: {
+ *     writer: agent({
+ *       model: "anthropic/claude-haiku-5-5",
+ *       instructions: "You write release notes.",
+ *       workspace: "none",
+ *     }),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "notes",
+ *   on: { "agent.fault": ".failed" },
+ *   initial: "drafting",
+ *   states: {
+ *     drafting: {
+ *       invoke: [
+ *         { src: "writer", input: { prompt: "Draft the release notes." } },
+ *         { src: "gate", id: "editor" },
+ *       ],
+ *       on: {
+ *         // The writer's `done` goes to review; the editor's `done` skips it.
+ *         done: [{ guard: sentBy("writer"), target: "review" }, { target: "published" }],
+ *       },
+ *     },
+ *     review: { invoke: { src: "gate" }, on: { done: "published" } },
+ *     published: { type: "final" },
+ *     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+ *   },
+ * });
+ * ```
+ *
+ * @see docs/concepts/the-menu.md
+ * @see docs/concepts/gates.md
+ * @see docs/reference/decisions/0015-authoring-surface-absorbs-the-mechanism.md
+ */
 export function sentBy<const Id extends string>(id: Id): { type: typeof SENT_BY; params: { id: Id } } {
+  // A NAMED guard with params, so the load walk can read it (see the module header). The id is
+  // refused at load by `refuseUnknownSentBy` when no Agent slot or Gate invoke id has it.
   return { type: SENT_BY, params: { id } };
 }