@jr2/orchestrator 0.4.1 → 0.6.0

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

@@ -0,0 +1,287 @@
+---
+title: workspace
+description: "Run a body Machine in a Sandbox: a pod of its own, with a clone of each Repo Slot."
+---
+
+# `workspace`
+
+Function, in `@jr2/orchestrator/src/workspace.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Workspaces and Repos.
+
+## Overload 1
+
+```ts
+function workspace<
+  TSchema extends z.ZodObject,
+  TBody extends AnyStateMachine,
+  TSlots extends string = never,
+>(
+  body: TBody & BodyAcceptsDoor<TBody, z.infer<TSchema>, TSlots>,
+  options: WorkspaceOptions<TSchema, TSlots> | NoSlotWorkspaceOptions<TSchema>,
+): WorkspaceMachine<WithoutEmptyIndex<z.infer<TSchema>>, OutputFrom<TBody>, TBody, TSlots>
+```
+
+Run a body Machine in a Sandbox: a pod of its own, with a clone of each Repo Slot. The result is
+a Machine. Register it as a Workflow, or invoke it from another Machine as
+an actor slot.
+
+When a run enters it, the Workspace makes the Sandbox and waits for room on a node, with no
+deadline. It clones each Repo Slot to `/work/<slot>/default`, on the Binding's base, and makes no
+Worktree: the body cuts each Worktree that it needs with `worktree()`. A slot that is only read
+needs no cut. No work happens in `default/`. Then it runs the body with the run input plus
+`workspace`, the handles (see [`Workspaced`](type-workspaced.md)). The Agents with Working tools and the `command` Effects in the body run in that Sandbox. An Agent
+with `workspace: "none"` runs on the Instance Harness. When the body reaches a final state, the
+Workspace deletes the Sandbox, and its output is the body's output. Push each branch before
+then: jr2 deletes the Sandbox's commits with it.
+
+The author chooses how many Agents work in a Workspace. Agents in one Worktree share git, as
+people in one checkout do. Each coder that needs its own branch gets its own Worktree of the one
+clone.
+
+Leave out `repos` for a Workspace with no Repo Slot: its Agents and `command` Effects share
+`/work`, as the steps of one job share a folder. The body's input is then `Workspaced<RunInput, never>`. An `http` Effect sends a
+file of `/work` with `file(path)`. A `worktree()`, a `push`, and a `command` with an Effect secret in its
+`env`, need a Repo Slot, so jr2 refuses them there. jr2 deletes `/work` with the Sandbox: send what
+must stay before the body ends.
+
+Give each run a different branch, so that two runs do not push to one branch. Make it from a
+field of the run input, or from `instanceId` when the run input has no field that is different
+for each run: ``branch: `fix/${context.instanceId}` `` in the input of the cut. Add
+`HostInjectedInput` to the body's input type to read it. Only a root `workspace()` gets `instanceId` from jr2. A `workspace()` that a different Machine invokes gets
+it only when its parent gives it.
+
+The Sandbox is Lost when its pod is evicted or its node goes. Then the body gets the event
+`workspace.lost`, and the body decides what to do. jr2 does not make the Lost Sandbox again.
+
+When the body fails (it invokes a `fail()` slot), the Workspace deletes the Sandbox, and then the
+same Failure goes up to the parent. With no parent to catch it, the run ends `failed`. When the
+body has a defect (an error that is not a Failure), the run faults: it ends `error`, and the
+Sandbox stays for you to inspect, until jr2's operator removes it after an idle timeout.
+
+Give the run input to `input`, not to the body: a body with an `input` schema of its own is
+refused. The types refuse a body whose input does not accept the run input plus the handles,
+with the message `the body's declared input must accept the door plus the injected handles`.
+
+It refuses, when you call it:
+- a body with a state that is not final, when that state and each state above it have no
+  `workspace.lost` route: ``workspace(): the body "<id>" has a state "<state>" that is not final,
+  and no route for "workspace.lost" is on 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)``
+- a body with its own `input`: ``workspace(): the body "<id>" declares its own run input, which
+  nothing will ever serve or enforce — the wrapper feeds the body the run input PLUS the injected
+  `workspace` handles, so the body's schema is not the door. Move it to the wrapper:
+  workspace(body, { input }) (ADR-0033).``
+- an empty `image`: ``workspace(): `image` must be a non-empty string (got <value>) — either a
+  `file:` URL to a docker context this module ships (`import.meta.resolve("./image")`) or a
+  registry ref (ADR-0037).``
+- an empty `repos`: ``workspace(): `repos: {}` names no Repo Slot — leave `repos` out for a
+  Workspace with no Repo Slot, or name a slot: `repos: { app: "https://…" }` (ADR-0051).``
+- a `repos` that is not a map or `open`: ``workspace(): `repos` must be a map of Repo Slots —
+  `repos: { app: "https://…" }` — or `open` whole, for a map the consumer names; leave it out
+  for a Workspace with no Repo Slot (ADR-0051).``
+- a bad Repo Slot name or value (see [`RepoSlot`](type-reposlot.md))
+- a `workGroup` that is not a gid: ``workspace(): `workGroup` must be a gid (got <value>)``
+- a bad `secrets` list: ``workspace(): `secrets` must be a list of distinct names from
+  jr2.config.ts's `secrets` list (got <value>) — secrets: ["JIRA_TOKEN"] (ADR-0059).``
+- a bad `effector`: ``workspace(): `effector` is { image } — a `file:` URL to a docker context
+  or a registry ref (got <value>) — effector: { image: import.meta.resolve("./effector") }
+  (ADR-0068).``
+- a `user` that is not an image or `{ image, resources? }`: ``workspace(): `user` must be a
+  non-empty string (an image), or { image, resources? } (got <value>) — either a `file:` URL to a
+  docker context this module ships (`import.meta.resolve("./image")`) or a registry ref
+  (ADR-0037, ADR-0060).``, or ``workspace(): user.<key> is not accepted — the User Container is {
+  image, resources? } (ADR-0005, ADR-0060)`` (see [`UserContainer`](type-usercontainer.md))
+- a `resources` key other than `limits` or `requests`: ``workspace(): resources.<key> is not accepted — a
+  Size is { limits: { memory?, cpu? } } and nothing else — Agent Substrate's template size
+  (ADR-0060)``, or the same text for `resources.limits.<key>`. The other texts are in
+  [`Size`](type-size.md).
+
+And when a run enters it, a per-run Repo Slot's mapper that gives no `url`, or a bad `ref`:
+``workspace invalid: repos.<slot> mapper returned <fields> — the mapper derives from run
+input; does `jr2 run --input` carry every field this workflow's workspace() slot reads?``
+
+**Parameters**
+
+- `body`: The Machine to run in the Sandbox. Its input is `Workspaced<RunInput, Slots>`.
+- `options` ([`WorkspaceOptions`](type-workspaceoptions.md) | [`NoSlotWorkspaceOptions`](type-noslotworkspaceoptions.md)): What the Sandbox is made of (`image`, `user`, `resources`, `effector`), the
+  Repo Slots it clones (`repos`), the Held secrets it can use (`secrets`), the pod's `fsGroup`
+  (`workGroup`), and the run input (`input`).
+
+**Returns**: A Machine whose input is the run input and whose output is the body's output.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import {
+  command,
+  fail,
+  isReady,
+  jr2Setup,
+  workspace,
+  worktree,
+  type CommandOutput,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+const runInput = z.object({ ticket: z.string(), repo: z.string() });
+type BodyInput = Workspaced<z.infer<typeof runInput>, "app" | "docs">;
+
+// The Worktree of this run. An Agent or a command that only reads `docs` uses `/work/docs/default`.
+const buildTree = (context: BodyInput) => `${context.workspace.repos.app}/build` as const;
+
+const passed = (output: CommandOutput): boolean =>
+  output.outcome === "exited" && output.code === 0;
+
+const body = jr2Setup({
+  types: {} as { input: BodyInput; context: BodyInput },
+  actors: {
+    cut: worktree(),
+    build: command(["npm", "run", "build"]),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "build",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: buildTree(context), branch: `fix/${context.ticket}` }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "building" }, { target: "notCut" }],
+      },
+    },
+    building: {
+      invoke: {
+        src: "build",
+        input: ({ context }) => ({ worktree: buildTree(context) }),
+        onDone: [
+          { guard: ({ event }) => passed(event.output), target: "built" },
+          { target: "broken" },
+        ],
+      },
+    },
+    built: { type: "final" },
+    broken: { invoke: { src: "fail", input: { reason: "npm run build 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,
+  image: "docker.io/library/node:24",
+  resources: { limits: { memory: "4Gi", cpu: "2" } },
+  repos: {
+    app: ({ input }) => input.repo,
+    docs: { url: "https://github.com/you/docs.git", ref: "main" },
+  },
+});
+```
+
+**Example**
+
+```ts
+import { z } from "zod";
+import {
+  command,
+  fail,
+  isReady,
+  jr2Setup,
+  workspace,
+  worktree,
+  type CommandOutput,
+  type HostInjectedInput,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+const passed = (output: CommandOutput): boolean =>
+  output.outcome === "exited" && output.code === 0;
+
+// The run input has no field that is different for each run, so the branch comes from
+// `instanceId`.
+const runInput = z.object({});
+type BodyInput = Workspaced<z.infer<typeof runInput> & HostInjectedInput, "app">;
+
+const nightlyTree = (context: BodyInput) => `${context.workspace.repos.app}/nightly` as const;
+
+const body = jr2Setup({
+  types: {} as { input: BodyInput; context: BodyInput },
+  actors: { cut: worktree(), test: command(["npm", "test"]), fail: fail() },
+}).createMachine({
+  id: "nightly",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: nightlyTree(context), branch: `nightly/${context.instanceId}` }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "testing" }, { target: "notCut" }],
+      },
+    },
+    testing: {
+      invoke: {
+        src: "test",
+        input: ({ context }) => ({ worktree: nightlyTree(context) }),
+        onDone: [
+          { guard: ({ event }) => passed(event.output), target: "tested" },
+          { target: "red" },
+        ],
+      },
+    },
+    tested: { type: "final" },
+    red: { invoke: { src: "fail", input: { reason: "npm 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,
+  image: "docker.io/library/node:24",
+  repos: { app: "https://github.com/you/app.git" },
+});
+```
+
+**See also**
+
+- [Workspaces](../../concepts/workspaces.md)
+- [Write a Workflow](../../guides/write-a-workflow.md)
+- [Size a Workspace](../../guides/size-a-workspace.md)
+- [Add tools to the Sandbox](../../guides/add-tools-to-the-sandbox.md)
+- [ADR-0012: `workspace()` wraps a body Machine and owns only Sandbox lifecycle](../decisions/0012-workspace-wrapper-machine.md)
+- [ADR-0051: A Repo is a slot on the `workspace()` and a cache on the node](../decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md)
+
+## Overload 2
+
+```ts
+function workspace<
+  TBody extends AnyStateMachine,
+  TSlots extends string = never,
+  TInput = DoorlessInput<TBody>,
+>(
+  body: TBody & BodyAcceptsSlots<TBody, TSlots>,
+  options: PermissiveWorkspaceOptions<TSlots, Exclude<TInput, undefined>> | PermissiveNoSlotWorkspaceOptions,
+): WorkspaceMachine<TInput, OutputFrom<TBody>, TBody, TSlots>
+```
+
+Run a body Machine in a Sandbox, with no `input` schema: the Workspace starts with any input. Use
+it for a Workspace that a Pool or another Machine starts. `workspace` tells the rest, and
+what it refuses.
+
+**Parameters**
+
+- `body`: The Machine to run in the Sandbox. Its input is the input of the Workspace plus
+  `workspace`, the handles.
+- `options` ([`PermissiveWorkspaceOptions`](type-permissiveworkspaceoptions.md) | [`PermissiveNoSlotWorkspaceOptions`](type-permissivenoslotworkspaceoptions.md)): The options of the Sandbox. There is no `input`.
+
+**Returns**: A Machine whose input is the run input and whose output is the body's output.
+
+**See also**
+
+- [Workspaces](../../concepts/workspaces.md)
+- [ADR-0033: A Machine declares the input that starts it](../decisions/0033-a-machine-declares-the-input-that-starts-it.md)

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

@@ -0,0 +1,71 @@
+---
+title: worktree
+description: "Make a `worktree` Effect: it cuts a Worktree of a Repo Slot, or reads the one that is there."
+---
+
+# `worktree`
+
+Function, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+function worktree(options: WorktreeOptions = {}): EffectLogic<WorktreeInput, WorktreeOutput>
+```
+
+Make a `worktree` Effect: it cuts a Worktree of a Repo Slot, or reads the one that is there. Put it
+in `actors`, and invoke it from a `workspace()` body.
+
+With `{ path, branch, from? }`, the branch resolves in this order, after a fetch: a local branch;
+`origin/<branch>`, tracked; a new branch from `from` or the Binding's base, with no upstream. With
+`{ path, detach }`, the Worktree is forced to that commit and cleaned, each time. `path` is exactly
+`/work/<slot>/<name>`. Each outcome is output: `ready`, `refused`, `unknown`.
+
+`expect` says if the branch can exist: `worktree({ expect: "new" })` refuses a branch that exists,
+and `worktree({ expect: "existing" })` refuses a branch that does not exist. A run cannot change it.
+
+A cut needs a Repo Slot. Under a Workspace with no Repo Slot, `jr2 up` refuses it, and the invoke
+fails with `worktree "<slot>" runs under a Workspace with no Repo Slot: a cut makes a Worktree of a
+Repo Slot, and there is none — declare one: repos: { app: "<url>" } (ADR-0075)`.
+
+**Parameters**
+
+- `options` ([`WorktreeOptions`](type-worktreeoptions.md)): Optional. `expect`, and `timeout`, how long the fetch and the cut can take.
+  Default: `"10m"`.
+
+**Returns**: The actor logic of the Effect's slot. Its output is a [`WorktreeOutput`](type-worktreeoutput.md).
+
+**Example**
+
+```ts
+import { fail, isReady, jr2Setup, worktree, type Workspaced } from "@jr2/orchestrator";
+
+type BodyInput = Workspaced<{ branch: string }, "app">;
+const tree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
+export const body = jr2Setup({
+  types: {} as { input: BodyInput; context: BodyInput },
+  actors: { cut: worktree({ expect: "new" }), fail: fail() },
+}).createMachine({
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".notCut" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: tree(context), branch: context.branch }),
+        // The last arm has no guard: it takes `refused`, `unknown` and each later outcome.
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "done" }, { target: "notCut" }],
+      },
+    },
+    done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+  },
+});
+```
+
+**See also**
+
+- [Cut a Worktree](../../guides/cut-a-worktree.md)
+- [Workspaces](../../concepts/workspaces.md)
+- [Effects](../../concepts/effects.md)
+- [ADR-0075: A Machine cuts a Worktree, and the Workspace only clones](../decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)

package/docs/reference/authoring-surface.md

@@ -0,0 +1,217 @@
+---
+title: Authoring surface
+description: "Every name that @jr2/orchestrator exports from its root, by group, with a link to its page: its signature, its TSDoc, and an example."
+---
+
+# Authoring surface
+
+The [Authoring surface](glossary.md#authoring-surface) is every name that `@jr2/orchestrator` exports from its root, and nothing else: a workflow module and `jr2.config.ts` import only these names. The groups and their order are those of the root's `src/index.ts`. This page gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in `authoring-surface/`, with the file that declares it, its signature, and its TSDoc.
+
+## Machine and events
+
+The setup a workflow writes its Machine with, the events its parties send, and the guard that makes a writing decline other senders ([ADR-0011](decisions/0011-workflow-defined-events.md), [ADR-0015](decisions/0015-authoring-surface-absorbs-the-mechanism.md)).
+
+- [`defineEvent`](authoring-surface/defineevent.md) (function): Define one workflow event: an event that an Agent or the caller of a Gate may send into your Machine.
+- [`jr2Setup`](authoring-surface/jr2setup.md) (function): Set up a Machine that takes workflow events: the jr2 form of xstate's `setup()`.
+- [`sentBy`](authoring-surface/sentby.md) (function): A guard that is true for an event that one party sent, and false for an event that another party sent: `guard: sentBy("coder")`.
+- [`HostInjectedInput`](authoring-surface/type-hostinjectedinput.md) (type): The fields that jr2 adds to the input of the Machine that a run starts, beside the input that the caller sent.
+
+## Failure
+
+The Part a Machine invokes to fail its run, and the guard that tells a Failure from a defect in an `onError` ([ADR-0073](decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)).
+
+- [`fail`](authoring-surface/fail.md) (function): Fail the run: the Part a Machine invokes to end work that did not succeed.
+- [`isFailure`](authoring-surface/isfailure.md) (function): Is this error a Failure, which a state invoked `fail` to make?
+
+## Agents
+
+An Agent slot and the definition it carries ([ADR-0028](decisions/0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md), [ADR-0049](decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md)).
+
+- [`agent`](authoring-surface/agent.md) (function): Make an Agent: an actor slot that runs one Turn of a model each time a state invokes it.
+- [`AgentDefinition`](authoring-surface/type-agentdefinition.md) (type): An Agent's definition: which model it runs, its instructions, and what it may do to the Workspace.
+- [`ThinkingLevel`](authoring-surface/type-thinkinglevel.md) (type): How hard the model thinks before it answers: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"` or `"xhigh"`.
+
+## Workspaces and Repos
+
+A Sandbox and the Repo Slots it binds ([ADR-0012](decisions/0012-workspace-wrapper-machine.md), [ADR-0051](decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md)).
+
+- [`workspace`](authoring-surface/workspace.md) (function): Run a body Machine in a Sandbox: a pod of its own, with a clone of each Repo Slot.
+- [`Workspaced`](authoring-surface/type-workspaced.md) (type): The input of a `workspace()` body: the run input, plus `workspace`, the handles that the Workspace adds (`workspace.repos`, the folder of each Repo Slot).
+- [`Binding`](authoring-surface/type-binding.md) (type): The repository of a Repo Slot: `{ url, ref }`.
+- [`RepoSlot`](authoring-surface/type-reposlot.md) (type): The value of one Repo Slot in `workspace({ repos })`.
+
+## Effects
+
+Work a Machine does outside itself, as an actor slot ([ADR-0067](decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md), [ADR-0068](decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md), [ADR-0071](decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)), and what an author writes between a pick and that work.
+
+- [`arg`](authoring-surface/arg.md) (constant): Mark one argv entry of a `command` that the input of the Effect fills.
+- [`CommandOutput`](authoring-surface/type-commandoutput.md) (type): The output of a `command` Effect: what the `onDone` of its state gets as `event.output`.
+- [`LaterOutcome`](authoring-surface/type-lateroutcome.md) (type): A value of `outcome` that this kit does not give.
+- [`command`](authoring-surface/command.md) (function): Make a `command` Effect: an actor slot that runs one program in the Workspace's Sandbox when a state invokes it.
+- [`basic`](authoring-surface/basic.md) (function): Make the `auth` of an `http` Effect that sends `Authorization: Basic <value>`, where the value is the base64 of `user:password`.
+- [`bearer`](authoring-surface/bearer.md) (function): Make the `auth` of an `http` Effect that sends `Authorization: Bearer <value>`, with the value of an Effect secret.
+- [`file`](authoring-surface/file.md) (function): Make a Worktree file the body of an `http` Effect: `body: file("dist/report.pdf")`.
+- [`http`](authoring-surface/http.md) (function): Make an `http` Effect: a call to a URL, with Effect secrets that the Agent never reads.
+- [`secret`](authoring-surface/secret.md) (function): Name an Effect secret: `secret("jira")`.
+- [`text`](authoring-surface/text.md) (function): Make a string from literal text and Effect secrets, as a tagged template: `` text`Token ${secret("x")}` ``.
+- [`HttpOutput`](authoring-surface/type-httpoutput.md) (type): The output of an `http` Effect: what the `onDone` of its state gets as `event.output`.
+- [`push`](authoring-surface/push.md) (function): Make a `push` Effect: it pushes the branch of a Worktree to the Binding of its Repo Slot.
+- [`PushOutput`](authoring-surface/type-pushoutput.md) (type): The output of a `push` Effect: what the `onDone` of its state gets as `event.output`.
+- [`branchName`](authoring-surface/branchname.md) (constant): A kit schema for a pick param that names a branch.
+- [`isReady`](authoring-surface/isready.md) (constant): Is it `ready`?
+- [`readyOf`](authoring-surface/readyof.md) (function): The `ready` output of an `onDone` arm that `isReady` guards.
+- [`worktree`](authoring-surface/worktree.md) (function): Make a `worktree` Effect: it cuts a Worktree of a Repo Slot, or reads the one that is there.
+- [`AnyFramePath`](authoring-surface/type-anyframepath.md) (type): A Turn's Frame: a Worktree, or `/work`, stated.
+- [`AnyWorktreePath`](authoring-surface/type-anyworktreepath.md) (type): A Worktree of any Repo Slot: what a kit factory states, before `jr2Setup` narrows it to the slots of the body.
+- [`FramePath`](authoring-surface/type-framepath.md) (type): A Turn's Frame in a Workspace with the Repo Slots `S`.
+- [`WorktreeFound`](authoring-surface/type-worktreefound.md) (type): What a cut found: `held`, a cut made this Worktree earlier, so what is in it is earlier work; `local`, a local branch; `remote`, `origin/<branch>`, now tracked; `none`, a new branch with no upstream; `commit`, a detached cut.
+- [`WorktreeInput`](authoring-surface/type-worktreeinput.md) (type): The input of a `worktree()`: a branch Worktree, or a detached one.
+- [`WorktreeOptions`](authoring-surface/type-worktreeoptions.md) (type): The options of `worktree()`.
+- [`WorktreeOutput`](authoring-surface/type-worktreeoutput.md) (type): The output of a `worktree()`.
+- [`WorktreePath`](authoring-surface/type-worktreepath.md) (type): A Worktree of the Repo Slots `S`.
+- [`WorktreeReady`](authoring-surface/type-worktreeready.md) (type)
+- [`WorktreeRefused`](authoring-surface/type-worktreerefused.md) (type): No Worktree, and nothing changed: a bad path, a name git or the push refuses, a re-cut that does not agree with the first, a branch that another Worktree holds, an `expect` that does not hold, or a name that the remote cannot confirm.
+- [`dispatch`](authoring-surface/dispatch.md) (function): Make a `dispatch` Effect: it starts a run of a Workflow.
+- [`DispatchOutput`](authoring-surface/type-dispatchoutput.md) (type): The output of a `dispatch` Effect.
+- [`answer`](authoring-surface/answer.md) (function): Set what the Agent reads when jr2 answers its pick.
+- [`fromPick`](authoring-surface/frompick.md) (function): Make the `input` of the invoke of a state that a pick enters: the params of the pick go to the input of the invoked actor by name.
+- [`paramsOf`](authoring-surface/paramsof.md) (function): Read the params of a pick from the event that entered the state.
+
+## Composition
+
+A part left Open, a Machine's parts retuned, a Pool over a Source ([ADR-0017](decisions/0017-pool-over-a-source-port.md), [ADR-0049](decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md), [ADR-0054](decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md), [ADR-0060](decisions/0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md)).
+
+- [`open`](authoring-surface/open.md) (constant): Leave a part of a Machine Open: for the Instance that registers the Machine to bind with `customize()`.
+- [`customize`](authoring-surface/customize.md) (function): Retune the parts that a Machine carries, without a change to the module that exports it.
+- [`Customize`](authoring-surface/type-customize.md) (type): The parts of one Machine that `customize()` can retune: its Agents, its Open Effects, the Machines it composes, and the Sandbox of its `workspace()`.
+- [`EffectBinding`](authoring-surface/type-effectbinding.md) (type): The values that bind the Open parts of one Effect.
+- [`Size`](authoring-surface/type-size.md) (type): The Size of a Workspace: the most memory and cpu that its whole Sandbox can use.
+- [`UserContainer`](authoring-surface/type-usercontainer.md) (type): The User Container in its object form: its image, and its part of the Workspace's Size.
+- [`pool`](authoring-surface/pool.md) (function): Make a Pool: a Machine that runs one worker Machine for each item that a Source gives, with at most `cap` workers at once.
+- [`source`](authoring-surface/source.md) (function): Declare a Source: where a `pool()` gets its work items, one at a time.
+- [`PoolNextInput`](authoring-surface/type-poolnextinput.md) (type): The input of a Source's `next`: the ids of the items that workers have now, the ids of the items that settled, and the Pool's input.
+
+## Charts
+
+The Open body a Chart wrapper places in `actors`, and the grammar a planner's pick declares, whole or narrowed to one wrapper ([ADR-0070](decisions/0070-a-machine-lends-its-parts-to-a-chart.md)).
+
+- [`openBody`](authoring-surface/openbody.md) (function): Make an Open body: the actor slot that a Chart binds.
+- [`OpenBodyDeclaration`](authoring-surface/type-openbodydeclaration.md) (type): What an Open body declares: the parts that it lends a Chart, what the Agents of a Chart can have, and the limits of a Chart.
+- [`OpenBodyOutput`](authoring-surface/type-openbodyoutput.md) (type): The output of an Open body.
+- [`chartSchema`](authoring-surface/chartschema.md) (constant): The Chart grammar, as a zod schema.
+- [`chartSchemaFor`](authoring-surface/chartschemafor.md) (function): The Chart grammar for one Open body, as a zod schema.
+
+## Config
+
+`jr2.config.ts`, the deployment facts a Machine cannot carry ([ADR-0050](decisions/0050-what-code-names-config-declares-what-the-cli-names-discovery-finds.md)).
+
+- [`defineConfig`](authoring-surface/defineconfig.md) (function): Declare the config of an Instance: the default export of `jr2.config.ts`.
+- [`JR2Config`](authoring-surface/type-jr2config.md) (type): The shape of `jr2.config.ts`: the deployment facts of an Instance, which a Machine cannot carry.
+
+## Types these signatures name
+
+The signature of an export, or a type here, names each of these types. They are not exports of `@jr2/orchestrator`, so a workflow module does not import them by name.
+
+- [`EventSemantics`](authoring-surface/type-eventsemantics.md): How the party that sends an event gets its answer.
+- [`EventAudience`](authoring-surface/type-eventaudience.md): Who may send an event: `"agent"` (an Agent, as a pick from its Menu), `"external"` (the caller of a Gate), or `"any"` (both).
+- [`EventDef`](authoring-surface/type-eventdef.md): A workflow event, as `defineEvent` gives it back: plain, frozen data and a zod schema, safe to import anywhere.
+- [`WorkflowEvent`](authoring-surface/type-workflowevent.md): The type of `event` in a Machine that `jr2Setup` makes: each workflow event in its `events`, and each Mechanism event.
+- [`FailSlot`](authoring-surface/type-failslot.md): The logic `fail()` returns: `failLogic` with the brand the walk reads.
+- [`Failure`](authoring-surface/type-failure.md): A Failure as `isFailure` narrows an error to it: the payload's fields, on the error itself.
+- [`AgentDeclaration`](authoring-surface/type-agentdeclaration.md): What `agent()` takes: an `AgentDefinition`, except that `model` can also be `open`.
+- [`WorkspaceAccess`](authoring-surface/type-workspaceaccess.md): What an Agent may do to the Workspace: `"write"`, `"read"` or `"none"`.
+- [`WorkspaceOptions`](authoring-surface/type-workspaceoptions.md): The options of a `workspace()` that declares the input that starts a run.
+- [`NoSlotWorkspaceOptions`](authoring-surface/type-noslotworkspaceoptions.md): The options of a `workspace()` with no Repo Slot that declares the input that starts a run.
+- [`WithoutEmptyIndex`](authoring-surface/type-withoutemptyindex.md): The fields of the run input `T`.
+- [`PermissiveWorkspaceOptions`](authoring-surface/type-permissiveworkspaceoptions.md): The options of a `workspace()` with no `input`: it starts with any input.
+- [`PermissiveNoSlotWorkspaceOptions`](authoring-surface/type-permissivenoslotworkspaceoptions.md): The options of a `workspace()` with no Repo Slot and no `input`: it starts with any input.
+- [`WorkspaceHandles`](authoring-surface/type-workspacehandles.md): What the body of a `workspace()` gets as `input.workspace`: the folder of each Repo Slot.
+- [`ExecOutcome`](authoring-surface/type-execoutcome.md): How an exec ended.
+- [`Unknown`](authoring-surface/type-unknown.md): The output `{ outcome: "unknown", reason }`: the Effect may have acted, and jr2 cannot tell.
+- [`Arg`](authoring-surface/type-arg.md): One entry of a command's argv that the input of the Effect fills, as `arg("name")` makes it.
+- [`CommandOptions`](authoring-surface/type-commandoptions.md): The options of `command()`: the Repo Slot it runs in, how long it can run, how much of its output it keeps, its Effect secrets, and the commit it runs against.
+- [`CommandInput`](authoring-surface/type-commandinput.md): A command's input: one string per argv slot, and with `pin` the approved commit (`{ sha }`); none when there is neither.
+- [`OpenCommandInput`](authoring-surface/type-opencommandinput.md): The input of a `command(open)`: a string for each `arg()` of the argv that the Instance binds, and with `pin`, the commit (`{ sha }`).
+- [`Secret`](authoring-surface/type-secret.md): What `secret("name")` gives: an Effect secret, by its name in the `secrets` list of `jr2.config.ts`.
+- [`Text`](authoring-surface/type-text.md): What the `text` template gives: a string of literal text and Effect secrets, in order.
+- [`FromInput`](authoring-surface/type-frominput.md): A value of a file body's part: as written, or from the Effect's input.
+- [`FileBody`](authoring-surface/type-filebody.md): `file(path, { segments?, contentType? })`: a Worktree file as an `http` body.
+- [`HttpDefinition`](authoring-surface/type-httpdefinition.md): An `http` Effect's definition.
+- [`HttpFileInput`](authoring-surface/type-httpfileinput.md): The input of an `http` Effect with a Worktree file as its body.
+- [`OpenSecret`](authoring-surface/type-opensecret.md): `secret(open)`: a secret a packaged Machine names in its auth, a header or a command's env, and leaves for its composer to name (ADR-0054).
+- [`PushOptions`](authoring-surface/type-pushoptions.md): The options of `push()`.
+- [`PushInput`](authoring-surface/type-pushinput.md): The input of a `push` Effect: the Worktree that a cut made, `{ sha }` with `pin`, and `{ message }` with `squash`.
+- [`Duration`](authoring-surface/type-duration.md): A length of time: a positive number and a unit, `s`, `m` or `h`.
+- [`NameStart`](authoring-surface/type-namestart.md): What a Worktree's name may start with: neither `.` nor `-`, and not the end of the path.
+- [`DispatchDefinition`](authoring-surface/type-dispatchdefinition.md): The definition of a `dispatch` Effect (ADR-0071).
+- [`DispatchInput`](authoring-surface/type-dispatchinput.md): A dispatch's input: the run's body — the slot's schema's type, or any JSON object.
+- [`DispatchOpenParts`](authoring-surface/type-dispatchopenparts.md): The Open part a dispatch definition states: its target, when it is `open`.
+- [`ChainLink`](authoring-surface/type-chainlink.md): One reply since the pick, as the author reads it: an invoked actor's output, typed by its slot (`src`); or an event that answered a state below the Agent's — a Gate's answer, a nested Agent's pick — typed by the Machine's events.
+- [`Quantity`](authoring-surface/type-quantity.md): A Kubernetes quantity: `"2Gi"`, `"1500m"`, `"2"`, or a plain number (`2` cpus, bytes of memory).
+- [`PoolSpec`](authoring-surface/type-poolspec.md): What you pass to `pool()`: where the items come from, how many workers run at once, and what each worker gets.
+- [`SourceSpec`](authoring-surface/type-sourcespec.md): Where a Pool gets its work items: the Source.
+- [`OpenBodyLogic`](authoring-surface/type-openbodylogic.md): The logic `openBody()` returns: actor logic that carries the brand.
+- [`Lends`](authoring-surface/type-lends.md): The parts of the Chart wrapper that a Chart can use, by their keys in `actors`, `guards`, `actions` and `delays`.
+- [`Ceilings`](authoring-surface/type-ceilings.md): The limits that an Open body sets on its Chart.
+- [`ChartText`](authoring-surface/type-charttext.md): The Chart text (ADR-0070).
+- [`Sender`](authoring-surface/type-sender.md): Who delivered an event: an Agent by its slot, or a Gate by its invoke id (ADR-0015).
+- [`FailureInput`](authoring-surface/type-failureinput.md): What a Failure carries: `reason`, text for a person, and `detail`, optional JSON for a machine reader.
+- [`SandboxOptions`](authoring-surface/type-sandboxoptions.md): The options of a `workspace()` that say what its Sandbox is made of and which Repos it clones.
+- [`SlotHandles`](authoring-surface/type-slothandles.md): The handles of a Workspace that declares Repo Slots.
+- [`CommandEnv`](authoring-surface/type-commandenv.md): The `env` of a `command`: for each variable, `secret("name")` for the value of an Effect secret, or `secret("name").path` for the path of a file that holds it.
+- [`TextPart`](authoring-surface/type-textpart.md): One part of a `Text`: `{ text }`, literal text, or `{ secret }`, the name of an Effect secret.
+- [`HttpMethod`](authoring-surface/type-httpmethod.md): The method of an `http` Effect: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`.
+- [`HttpRequestParts`](authoring-surface/type-httprequestparts.md): What the `request` of an `http` definition returns: the part of the request that changes for each run.
+- [`NamedSecret`](authoring-surface/type-namedsecret.md): A named secret, never `secret(open)`: where a definition's Open part is a whole that holds a secret — a dispatch's target (ADR-0071) — the secret is bound with it, to a name, so the mark `secret(open)` carries may not be present.
+- [`SourceNextResult`](authoring-surface/type-sourcenextresult.md): What the `next` of a Source resolves to: an item, to claim it; `null`, when no item is ready now; or `{ item, open }`, where `open` is the number of items that exist but are not ready.
+- [`OpenBodySlot`](authoring-surface/type-openbodyslot.md): The brand an Open body slot carries, as `definition` marks an Agent slot (ADR-0049).
+- [`ChartJson`](authoring-surface/type-chartjson.md): Plain JSON.
+- [`ChartEvent`](authoring-surface/type-chartevent.md): An event a Chart mints: its payload is a JSON Schema object, built into zod at admission.
+- [`ChartAgent`](authoring-surface/type-chartagent.md): An Agent a Chart mints: the plain fields of an Agent definition (ADR-0049).
+- [`ChartState`](authoring-surface/type-chartstate.md): A state node.
+- [`ChartValue`](authoring-surface/type-chartvalue.md): A value whose strings may hold `{{<root>.<path>}}` placeholders and whose objects may be `{ "$ref": "<root>.<path>" }`.
+- [`ChartInvoke`](authoring-surface/type-chartinvoke.md): An invoke: a lent Agent, Effect or Machine, a minted Agent, or the kit's `gate` or `fail`.
+- [`ChartTransitions`](authoring-surface/type-charttransitions.md): One transition or a list, in xstate's order.
+- [`ChartAction`](authoring-surface/type-chartaction.md): An action.
+- [`ChartTransition`](authoring-surface/type-charttransition.md): A transition: a target alone, or the object form.
+- [`ChartGuard`](authoring-surface/type-chartguard.md): A guard: a lent guard by name, with or without params, `jr2.sentBy`, `jr2.failure`, or `not`/`and`/`or`.
+
+**Type plumbing.** These types compute a type from the types of a Machine or of its parts. A workflow module does not write them. Each has a page with its declaration:
+
+- [`ToProvidedActor`](authoring-surface/type-toprovidedactor.md)
+- [`MergedActors`](authoring-surface/type-mergedactors.md)
+- [`ToParameterizedObject`](authoring-surface/type-toparameterizedobject.md)
+- [`BindActors`](authoring-surface/type-bindactors.md)
+- [`SentByGuards`](authoring-surface/type-sentbyguards.md)
+- [`AgentLogic`](authoring-surface/type-agentlogic.md)
+- [`BodyAcceptsDoor`](authoring-surface/type-bodyacceptsdoor.md)
+- [`WorkspaceMachine`](authoring-surface/type-workspacemachine.md)
+- [`DoorlessInput`](authoring-surface/type-doorlessinput.md)
+- [`BodyAcceptsSlots`](authoring-surface/type-bodyacceptsslots.md)
+- [`EffectLogic`](authoring-surface/type-effectlogic.md)
+- [`OpenOf`](authoring-surface/type-openof.md)
+- [`EnvOpenParts`](authoring-surface/type-envopenparts.md)
+- [`OpenEffect`](authoring-surface/type-openeffect.md)
+- [`MarkedIf`](authoring-surface/type-markedif.md)
+- [`HttpOpenParts`](authoring-surface/type-httpopenparts.md)
+- [`HttpInput`](authoring-surface/type-httpinput.md)
+- [`PushWireOutput`](authoring-surface/type-pushwireoutput.md)
+- [`SyncState`](authoring-surface/type-syncstate.md)
+- [`AnswerAction`](authoring-surface/type-answeraction.md)
+- [`AgentSlots`](authoring-surface/type-agentslots.md)
+- [`Reached`](authoring-surface/type-reached.md)
+- [`OpenEffectSlots`](authoring-surface/type-openeffectslots.md)
+- [`BindingOf`](authoring-surface/type-bindingof.md)
+- [`LogicAt`](authoring-surface/type-logicat.md)
+- [`ChildSlots`](authoring-surface/type-childslots.md)
+- [`ChildAt`](authoring-surface/type-childat.md)
+- [`RepoSlotsOf`](authoring-surface/type-reposlotsof.md)
+- [`WorkspaceOf`](authoring-surface/type-workspaceof.md)
+- [`PoolMachine`](authoring-surface/type-poolmachine.md)
+- [`EventFrom`](authoring-surface/type-eventfrom.md)
+- [`ArgNames`](authoring-surface/type-argnames.md)
+- [`WorktreeKey`](authoring-surface/type-worktreekey.md)
+- [`NotWorktreeKeys`](authoring-surface/type-notworktreekeys.md)
+- [`OpenSecretMark`](authoring-surface/type-opensecretmark.md)
+
+These names come from a dependency: from `zod`, `z.ZodObject`, `z.infer`, `z.ZodType`; from `xstate`, `MachineContext`, `UnknownActorLogic`, `ParameterizedObject`, `NonReducibleUnknown`, `EventObject`, `MetaObject`, `ActionFunction`, `GuardPredicate`, `DelayConfig`, `SetupReturn`, `AnyStateMachine`, `OutputFrom`, `ProvidedActor`, `AnyActorRef`, `InputFrom`, `PromiseActorLogic`.