@jr2/orchestrator 0.4.1 → 0.6.0

package/docs/reference/authoring-surface/command.md

@@ -0,0 +1,206 @@
+---
+title: command
+description: "Make a `command` Effect: an actor slot that runs one program in the Workspace's Sandbox when a state invokes it."
+---
+
+# `command`
+
+Function, in `@jr2/orchestrator/src/harness-client.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+## Overload 1
+
+```ts
+function command<
+  const A extends readonly (string | Arg)[],
+  const Opt extends CommandOptions = CommandOptions,
+>(
+  argv: A,
+  options?: Opt,
+): EffectLogic<CommandInput<A, Opt["pin"], Opt>, CommandOutput> & OpenOf<EnvOpenParts<Opt>>
+```
+
+Make a `command` Effect: an actor slot that runs one program in the Workspace's Sandbox when a
+state invokes it. Put it under `actors` and invoke it by its key: `actors: { tests:
+command(["node", "--test"]) }`, then `invoke: { src: "tests", onDone: … }`.
+
+`argv` is a list, never shell text: each entry is one argument. An `arg("name")` entry is filled
+from the invoke's `input` (`input: { name: "…" }`), as one argument whatever its text. To use a
+shell, write it: `["sh", "-c", "…"]`.
+
+Where it runs:
+- With no Effect secret in `env`, in the Harness container of the enclosing Workspace's Sandbox.
+  It runs in the Worktree that `worktree` of the invoke's input names, or in `/work` in a
+  Workspace with no Repo Slot. The Agent's Working tools also run in this container.
+- With an Effect secret in `env`, in the Sandbox Effector, against a commit of the branch. This
+  is the branch tip when it starts, or with `pin: true` the commit that the invoke's `input.sha`
+  names. The output then says `dirty: true` when the Worktree held edits that the command did
+  not see.
+
+Every outcome is output for `onDone`, never an error: `{ outcome: "exited", code, tail }`,
+`{ outcome: "timeout", tail }`, `{ outcome: "killed", signal, tail }`, or `{ outcome: "unknown",
+reason }` when jr2 cannot know what happened. `tail` is the end of the output stream.
+
+After an Orchestrator restart:
+- A command with no Effect secret in `env` never runs twice. jr2 attaches to it again, or settles
+  `unknown`.
+- A command with an Effect secret in `env` runs again when the Sandbox Effector no longer holds
+  it. It runs against the same commit. If jr2 has no commit for it, it settles `unknown`.
+
+When the state exits, the command stops: jr2 kills its process group. `onError` is only for a
+Machine or config defect.
+
+It refuses, when you call it:
+- an empty `argv`: `command(argv): argv is a non-empty list — each entry one argument, never
+  shell text`
+- an entry that is not a string or `arg()`: `command(argv): an argv entry is a string or
+  arg("name"), got <entry>`
+- a `timeout` that is not a positive duration: `command: timeout "<timeout>" is not a positive
+  duration (like "90s", "10m", "1h")`
+- an `env` name that is not a variable name, or `PATH`, `HOME` or `TMPDIR`: ``command(argv, {
+  env }): "<name>" is not a variable the author sets — PATH, HOME and TMPDIR are the Effector's
+  (ADR-0067)``
+- `pin: true` with no Effect secret in `env`: ``command(argv, { pin: true }) names no secret in
+  its env: `pin` chooses the commit a credentialed command runs against in the Sandbox
+  Effector, and a command that names no secret runs in the live Worktree (ADR-0067) — name its
+  secret, command(argv, { env: { NAME: secret("x") }, pin: true }), or drop `pin` ``
+
+And when it starts, with no Effect secret in `env`:
+- outside a `workspace()`: `command "<slot>" runs in the Harness container of a Workspace, and
+  its state is not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`
+- no `worktree` under Repo Slots: `` command "<slot>" runs under a Workspace with Repo Slots
+  (<slots>) and its input names no `worktree`: say which, a Worktree that a cut gave or
+  `<slot>/default` ``
+- an `arg()` with no string in `input`: `command "<slot>": argv slot <<name>> has no string
+  value in its input (got <type>) — map it in the invoke's input`. The angle brackets around the
+  arg's name are in the text: `argv slot <file>`. `<type>` is `nothing` when `input` has no such
+  field, or the type of its value, such as `number`.
+
+And when it starts, with an Effect secret in `env`:
+- outside a `workspace()`: `command "<slot>" runs in the Sandbox Effector of a Workspace, and its
+  state is not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`
+- a Workspace with no Repo Slot: `command "<slot>" runs under a Workspace with no Repo Slot: a
+  command with an Effect secret runs against one commit of a Repo Slot's branch, and there is
+  none — declare a Repo Slot, or name no secret in its env, and it runs in /work beside the Agent
+  (ADR-0051)`. `jr2 up` refuses it first, with the same reason
+- a `worktree` that no cut made in this Sandbox: the output is `exited` 127, with `no cut made
+  <path> in this Sandbox: cut it with worktree()` in its tail. A detached Worktree gets the same
+  form
+- `pin: true` and an `input.sha` that is not a full commit id: `command "<slot>" (pin): its
+  input's sha is not a full commit id`
+- an `arg()` with no string in `input`: the same text as above.
+
+**Parameters**
+
+- `argv`: The program and its arguments: strings and `arg("name")` entries. Or `open`, in a
+  Machine that you publish as a package, for the Instance that registers it to bind with
+  `customize()`.
+- `options` ([`CommandOptions`](type-commandoptions.md)): Optional. `timeout`: `"90s"`, `"10m"` or `"1h"`, default
+  `"10m"`; when it expires, the output is `timeout`. `tail`: how many characters of the end of
+  the output stream to keep, default 4096. `env`: environment variables. Each value is
+  `secret("name")` for the value of an Effect secret, or `secret("name").path` for the path of a
+  file that holds it. `pin`: `true` to run against the commit in `input.sha`. Use `pin` only
+  with an Effect secret in `env`.
+
+**Returns**: The actor logic of the Effect's slot. Its output is a `CommandOutput`.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import {
+  arg,
+  command,
+  fail,
+  isReady,
+  jr2Setup,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+const runInput = z.object({ branch: z.string() });
+type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+
+const testTree = (context: BodyInput) => `${context.workspace.repos.app}/test` as const;
+
+const body = jr2Setup({
+  types: {} as { input: BodyInput; context: BodyInput },
+  actors: {
+    cut: worktree(),
+    tests: command(["node", "--test", arg("file")], { timeout: "5m" }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "check",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: testTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "testing" }, { target: "notCut" }],
+      },
+    },
+    testing: {
+      invoke: {
+        src: "tests",
+        input: ({ context }) => ({ file: "test/greet.test.js", worktree: testTree(context) }),
+        onDone: [
+          {
+            guard: ({ event }) => event.output.outcome === "exited" && event.output.code === 0,
+            target: "passed",
+          },
+          { target: "failed" },
+        ],
+      },
+    },
+    passed: { type: "final" },
+    // Not final states: each one fails the run, and the run ends `failed`.
+    failed: { invoke: { src: "fail", input: { reason: "the test did not pass" } } },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  repos: { app: "https://github.com/you/app.git" },
+});
+```
+
+**See also**
+
+- [Effects](../../concepts/effects.md)
+- [Run a command or call a URL with an Effect](../../guides/run-a-command-or-call-a-url.md)
+- [ADR-0067: An Effect is an actor slot, and runs at most once unless marked idempotent](../decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)
+- [ADR-0068: An Effector holds an Effect's secrets and signs its wire](../decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)
+
+## Overload 2
+
+```ts
+function command<
+  const Opt extends CommandOptions = CommandOptions,
+>(
+  argv: typeof open,
+  options?: Opt,
+): EffectLogic<OpenCommandInput<Opt["pin"], Opt>, CommandOutput> & OpenEffect<"argv" | EnvOpenParts<Opt>>
+```
+
+Make a `command` Effect whose argv is Open: `command(open, options)`, in a Machine that you
+publish as a package. The Instance that registers the Machine binds the argv one time:
+`customize(machine, { effects: { <slot>: { argv } } })`. `command` tells the rest, and
+what it refuses.
+
+**Parameters**
+
+- `argv`: `open`.
+- `options` ([`CommandOptions`](type-commandoptions.md)): Optional. The same options as for a written argv.
+
+**Returns**: The actor logic of the Effect's slot. Its output is a `CommandOutput`.
+
+**See also**
+
+- [Bind a shipped Machine's Open parts](../../guides/bind-open-parts.md)
+- [ADR-0054: The kit ships Machines, and a shipped Machine leaves its parts Open](../decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)

package/docs/reference/authoring-surface/customize.md

@@ -0,0 +1,64 @@
+---
+title: customize
+description: Retune the parts that a Machine carries, without a change to the module that exports it.
+---
+
+# `customize`
+
+Function, in `@jr2/orchestrator/src/customize.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+
+```ts
+function customize<M extends AnyStateMachine>(machine: M, parts: Customize<M>): M
+```
+
+Retune the parts that a Machine carries, without a change to the module that exports it. Use it
+where you register a Machine as a Workflow. It binds the parts that a packaged Machine leaves
+Open: its Repo Slots, an Agent's model, or an Effect's url, argv or secret. It also changes the
+parts that its author fixed: an Agent's instructions, the Sandbox Image, or the Size.
+
+It gives back a new Machine of the same type. The original does not change, so two
+`customize()` calls on one import give two Machines. Only the parts the Machine declares can be
+retuned. You cannot add a part: a Machine that needs another Agent is a new Machine. The types
+refuse most mistakes when you compile. At run time, `customize()` also throws:
+
+- `customize(): machine "<id>" carries no Agent slot "<slot>" — its Agents are: <slots>`
+- `customize(): machine "<id>" composes no Machine under "<slot>" — the Machines it composes are: <slots>`
+- `customize(): machine "<id>" carries no Effect slot "<slot>" — its Effects are: <slots>`
+- `customize(): machine "<id>" declares no Repo Slot "<slot>" — its slots are: <slots>`
+- `customize(): machine "<id>" declares its Repo Slots open as a map — name at least one`
+- `` customize(): `repos` say what a SANDBOX is made of, how big it is and which Repos it
+  attaches, and machine "<id>" composes none `` (for `resources`, the text starts
+  `` customize(): `resources` ``; for `image` or `user`, it starts `` customize(): `image`/`user` ``)
+- `customize(): machine "<id>": <errors>`, when an Effect argv that you bind fails the checks
+  that the Machine passed when it was built
+- the refusals of [`EffectBinding`](type-effectbinding.md), [`RepoSlot`](type-reposlot.md), [`Size`](type-size.md) and
+  [`UserContainer`](type-usercontainer.md), which start with `customize()`
+
+**Parameters**
+
+- `machine`: The Machine to retune: one you import from a package, or one you wrote. When
+  its root is a `workspace()` or a `pool()`, `customize()` reaches through to the Machine inside,
+  so you never name the wrapper's own slot.
+- `parts`: The parts to change. See [`Customize`](type-customize.md).
+
+**Returns**: A new Machine of the same type, with the parts changed.
+
+**Example**
+
+```ts
+import { customize } from "@jr2/orchestrator";
+import { task } from "@jr2/machines";
+
+export const machine = customize(task, {
+  repos: { app: { url: "https://github.com/you/app.git" } },
+  agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+  resources: { limits: { memory: "4Gi" } },
+});
+```
+
+**See also**
+
+- [Bind a shipped Machine's Open parts](../../guides/bind-open-parts.md)
+- [Composition](../../concepts/composition.md)
+- [ADR-0049: A Machine carries its parts and composes by invoke](../decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md)
+- [ADR-0054: The kit ships Machines, and a shipped Machine leaves its parts Open](../decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)

package/docs/reference/authoring-surface/defineconfig.md

@@ -0,0 +1,41 @@
+---
+title: defineConfig
+description: "Declare the config of an Instance: the default export of `jr2.config.ts`."
+---
+
+# `defineConfig`
+
+Function, in `@jr2/orchestrator/src/config.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Config.
+
+```ts
+function defineConfig(c: JR2Config): JR2Config
+```
+
+Declare the config of an Instance: the default export of `jr2.config.ts`. It gives back the
+object that you pass. Its only work is to check that object against [`JR2Config`](type-jr2config.md) where you
+write it, at every depth, a misspelled key included. `jr2 up` typechecks the file before it
+converges.
+
+**Parameters**
+
+- `c`: The Instance's config. See [`JR2Config`](type-jr2config.md) for every field.
+
+**Returns**: The same object.
+
+**Example**
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({
+  name: "my-instance",
+  secrets: [{ name: "ANTHROPIC_API_KEY", value: process.env.ANTHROPIC_API_KEY }],
+  git: { credentials: [{ match: "github.com/you/", token: "GITHUB_TOKEN" }] },
+});
+```
+
+**See also**
+
+- [jr2.config.ts](../config.md)
+- [Create an Instance](../../get-started/create-an-instance.md)
+- [ADR-0050: What code names, config declares; what the CLI names, discovery finds](../decisions/0050-what-code-names-config-declares-what-the-cli-names-discovery-finds.md)

package/docs/reference/authoring-surface/defineevent.md

@@ -0,0 +1,114 @@
+---
+title: defineEvent
+description: "Define one workflow event: an event that an Agent or the caller of a Gate may send into your Machine."
+---
+
+# `defineEvent`
+
+Function, in `src/define-event.ts` of `@jr2/agent-protocol`, a dependency of `@jr2/orchestrator`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Machine and events.
+
+```ts
+function defineEvent<const Name extends string, Input extends z.ZodObject>(def: {
+  name: Name;
+  description?: string;
+  input: Input;
+  semantics?: EventSemantics;
+  audience?: EventAudience;
+}): EventDef<Name, Input>
+```
+
+Define one workflow event: an event that an Agent or the caller of a Gate may send into your
+Machine. Give the result to `jr2Setup({ events })`, and write its name as an `on` key on the
+states that take it. An Agent sees each event it may send as one tool on its Menu.
+
+It gives back a frozen [`EventDef`](type-eventdef.md) and registers nothing. Each Machine whose `jr2Setup`
+lists the event takes it. A Machine that does not list it does not take it.
+
+Give an event only the params that the Machine reads. When a pick enters a state that invokes an
+Effect, `createMachine` refuses each param of the pick that nothing reads: the input of the
+Effect, an `assign`, or the `fill` of `fromPick`. The compiler does not find this error.
+`jr2 check` and `jr2 up` find it when they load the module. Thus when you copy a `finish` event with a `summary`
+and nothing uses the summary, drop `summary` from the `input`, or store it with `assign`.
+
+It refuses:
+- a name with a character other than a letter, a digit, `_` or `-`:
+  `defineEvent: invalid name "<name>" — must match /^[a-zA-Z0-9_-]+$/ (it becomes an MCP tool
+  name and an xstate event type)`
+- an `input` with a `sender` field:
+  ``defineEvent: "<name>" declares `sender` in its input — the Orchestrator writes that field
+  on every delivered event (who sent it); name the payload field something else``
+- an `output` field:
+  ``defineEvent: "<name>" declares an `output`, which is retired — every pick is answered when
+  the work it started is done, and the answer is the Machine's, not the def's``. With
+  `semantics: "deferred"`, the text says ``declares `deferred` `` in place of
+  ``declares an `output` ``.
+
+**Parameters**
+
+- `def`: The event: its `name`, its `input` schema, and optionally its `description`,
+  `semantics` and `audience`.
+
+  - `name`: `Name`
+
+    The event's name: the `on` key that takes it, and the name of its tool on the Agent's Menu.
+    Letters, digits, `_` and `-` only.
+  - `description` (optional): `string`
+
+    What the event means, and when to send it. An Agent's model reads it as the tool's
+    description. Make it true at every state that takes the event.
+  - `input`: `Input`
+
+    The schema of the payload: a flat `z.object`. Use `z.object({})` for an event with no
+    payload. Do not name a field `sender`: jr2 writes that field.
+  - `semantics` (optional): [`EventSemantics`](type-eventsemantics.md)
+
+    How the sender gets its answer. Default: `"ack"`, the only value `createMachine` accepts.
+  - `audience` (optional): [`EventAudience`](type-eventaudience.md)
+
+    Who may send the event: `"agent"`, `"external"` or `"any"`. Default: unset, and the state of
+    each `on` key decides (see [`EventAudience`](type-eventaudience.md)).
+
+**Returns**: The event, as plain data to list in `jr2Setup({ events })`.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { agent, defineEvent, fail, jr2Setup } from "@jr2/orchestrator";
+
+const done = defineEvent({
+  name: "done",
+  description: "Call this when the summary is written.",
+  input: z.object({ summary: z.string() }),
+});
+
+export const machine = jr2Setup({
+  events: [done],
+  actors: {
+    writer: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You write short summaries.",
+      workspace: "none",
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "summary",
+  on: { "agent.fault": ".failed" },
+  initial: "writing",
+  states: {
+    writing: {
+      invoke: { src: "writer", input: { prompt: "Summarize the release notes in one line." } },
+      on: { done: "finished" },
+    },
+    finished: { type: "final" },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+  },
+});
+```
+
+**See also**
+
+- [Write a Workflow](../../guides/write-a-workflow.md)
+- [The Menu](../../concepts/the-menu.md)
+- [ADR-0011: Control events are workflow-defined and delivered by closure, not routed](../decisions/0011-workflow-defined-events.md)

package/docs/reference/authoring-surface/dispatch.md

@@ -0,0 +1,126 @@
+---
+title: dispatch
+description: "Make a `dispatch` Effect: it starts a run of a Workflow."
+---
+
+# `dispatch`
+
+Function, in `@jr2/orchestrator/src/dispatch-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+function dispatch<
+  S extends z.ZodObject | undefined = undefined,
+  const T extends DispatchDefinition<S>["target"] = undefined,
+>(
+  workflow: string,
+  def?: DispatchDefinition<S> & { target?: T },
+): EffectLogic<DispatchInput<S>, DispatchOutput> & OpenOf<DispatchOpenParts<T>>
+```
+
+Make a `dispatch` Effect: it starts a run of a Workflow. Put it in `actors`, and invoke it from a
+state: `actors: { triage: dispatch("triage", { input }) }`. The input of the invoke is the run
+input of the new run, as `jr2 run --input` gives it.
+
+The new run is a run of its own, with its own id, its own Workspaces and its own `CANCEL`. Its
+record names this run as the run that dispatched it. A `CANCEL` of this run does not end it.
+
+With no `target`, the run starts in this Orchestrator, under the current Assembly. With
+`target: { url, token }`, it starts on the Orchestrator at `url`, and the Effect runs in the
+Instance Effector. Every outcome is output ([`DispatchOutput`](type-dispatchoutput.md)): `started`, `settled`,
+`refused`, `unreachable` or `unknown`. Each start carries a key, so a start that jr2 sends again
+after a restart starts no second run.
+
+It refuses:
+- a name that is not a Workflow name: ``dispatch("<name>"): the Workflow is named as `jr2 run`
+  names it — a Machine's filename stem ("review"), or "<wrapper>/<name>" for a named Chart:
+  lowercase letters, digits and "-" (ADR-0071)``
+- a `wait` that is not a boolean: `dispatch("<name>", { wait }): wait is true or false — a slot
+  that needs both declares two`
+- an `input` that is not a `z.object()`: `dispatch("<name>", { input }): the input is a
+  z.object(...) — the run's body is a JSON object (ADR-0071)`
+- a `timeout` that is not a duration: `dispatch("<name>"): timeout "<timeout>" is not a positive
+  duration (like "30s", "10m", "1h")`
+- a `target` url that is not an origin: `dispatch("<name>", { target }): "<url>" is not an
+  origin — write the scheme and the host, with a port if it is not the scheme's, and no path,
+  query or userinfo`, then two examples
+- `secret(open)` in a target: `dispatch("<name>", { target }): secret(open) in a target — the
+  target is the Open part, not its secret`, then the fix
+
+`jr2 up` refuses a dispatch with no target whose Workflow the Assembly does not have, and an
+`input` schema that the input of that Workflow does not take.
+
+**Parameters**
+
+- `workflow`: The Workflow to start, as `jr2 run` names it: `"triage"`, or
+  `"<wrapper>/<name>"` for a named Chart.
+- `def`: Optional. Each field tells what it does.
+
+  - `input` (optional): `S`
+
+    A zod schema of the run input of the Workflow. It types the `input` of the invoke and
+    `fromPick`, and `jr2 up` compares it with the input that the Workflow declares. Without it,
+    only the Workflow checks the input.
+  - `wait` (optional): `boolean`
+
+    `true`: end when the new run ends (`settled`). `false`, the default: end when the
+    Orchestrator accepts the run (`started`).
+  - `timeout` (optional): [`Duration`](type-duration.md)
+
+    How long the Effect waits: by default 30s for the start, and 10m with `wait`.
+  - `target` (optional): `{ url: string; token: NamedSecret; } | typeof open`
+
+    A different Orchestrator: `url` is its origin, and `token` is the secret that holds its
+    Instance token. Or `open`, which the composer binds with `customize(<import>, { effects: {
+    <slot>: { target: { url, token } } } })`. Without it, the run starts in this Orchestrator.
+
+**Returns**: An Effect, for `actors`.
+
+**Example**
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { defineEvent, dispatch, jr2Setup } from "@jr2/orchestrator";
+
+const triageInput = z.object({ request: z.string() });
+
+const report = defineEvent({
+  name: "report",
+  description: "Report a request. A run of triage starts for it.",
+  input: triageInput,
+});
+
+export const machine = jr2Setup({
+  types: {} as { context: { request: string } },
+  events: [report],
+  // `wait: true`: the Effect ends when the run of triage ends.
+  actors: { triage: dispatch("triage", { input: triageInput, wait: true }) },
+}).createMachine({
+  id: "intake",
+  context: { request: "" },
+  initial: "listening",
+  states: {
+    listening: {
+      invoke: { src: "gate" },
+      on: { report: { target: "starting", actions: assign({ request: ({ event }) => event.request }) } },
+    },
+    starting: {
+      invoke: {
+        src: "triage",
+        input: ({ context }) => ({ request: context.request }),
+        onDone: [
+          { guard: ({ event }) => event.output.outcome === "settled", target: "done" },
+          { target: "listening" },
+        ],
+      },
+    },
+    done: { type: "final" },
+  },
+});
+```
+
+**See also**
+
+- [Start a run from a run](../../guides/start-a-run-from-a-run.md)
+- [Effects](../../concepts/effects.md)
+- [ADR-0071: A run starts a run through a `dispatch` Effect](../decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)

package/docs/reference/authoring-surface/fail.md

@@ -0,0 +1,96 @@
+---
+title: fail
+description: "Fail the run: the Part a Machine invokes to end work that did not succeed."
+---
+
+# `fail`
+
+Function, in `@jr2/orchestrator/src/fail.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Failure.
+
+```ts
+function fail(): FailSlot
+```
+
+Fail the run: the Part a Machine invokes to end work that did not succeed. Put it in `actors`
+under a name, and invoke it from any state, at any depth: `actors: { fail: fail() }`, then
+`invoke: { src: "fail", input: { reason } }`.
+
+The input is `{ reason: string; detail?: unknown }`. `reason` is text for a person, and it must
+not be empty. `detail` is optional JSON for a machine reader.
+
+The Failure goes up from the state that invokes `fail`, through each parent Machine, as an error
+does. An `onError` on the way catches it; [`isFailure`](isfailure.md) tells it from a defect. When no state
+catches it, the run ends `failed`: its output is `{ reason, detail }`, and `jr2 run` exits 1. A
+`workspace()` that a Failure goes through deletes its Sandbox first.
+
+To fail, invoke `fail`. Do not throw from a promise to fail: a throw is a defect, and the run
+ends `error`. A final state means `done`: do not use one for work that did not succeed. To keep
+the work for a person to read, wait at a Gate before the state that fails.
+
+It refuses an input that is not a Failure's, and the run ends `error`: ``fail: the input must be
+{ reason: string; detail?: unknown } with a reason that is not empty (got <value>) — invoke:
+{ src: "fail", input: { reason: "the tests failed" } } (ADR-0073)``.
+
+**Returns**: The actor logic of the slot.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { command, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
+
+const runInput = z.object({ branch: z.string() });
+type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+
+const testTree = (context: BodyInput) => `${context.workspace.repos.app}/test` as const;
+
+const body = jr2Setup({
+  types: {} as { input: BodyInput; context: BodyInput },
+  actors: {
+    cut: worktree(),
+    tests: command(["npm", "test"], { timeout: "15m" }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "check",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: testTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "testing" }, { target: "notCut" }],
+      },
+    },
+    testing: {
+      invoke: {
+        src: "tests",
+        input: ({ context }) => ({ worktree: testTree(context) }),
+        onDone: [
+          {
+            guard: ({ event }) => event.output.outcome === "exited" && event.output.code === 0,
+            target: "passed",
+          },
+          { target: "failing" },
+        ],
+      },
+    },
+    // Not a final state: the run ends `failed`, and the Workspace deletes the Sandbox.
+    failing: { invoke: { src: "fail", input: { reason: "npm test did not pass" } } },
+    passed: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  repos: { app: "https://github.com/you/app.git" },
+});
+```
+
+**See also**
+
+- [ADR-0073: A Machine fails a run with `fail()`, and an uncaught Failure ends it `failed`](../decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)