@jr2/orchestrator 0.5.1 → 0.7.0

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

@@ -0,0 +1,23 @@
+---
+title: carry
+description: Give the item itself.
+---
+
+# `carry`
+
+Function, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, in the [Composition](group-composition.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+function carry<T>(item: T): Carry<T>
+```
+
+Give the item itself. The Pool holds it, in its run's blob, until it claims it. Only a push
+Source gives it.
+
+**Parameters**
+
+- `item`: The item, of the type of the Source's `item` schema.
+
+**See also**
+
+- [Pools and Sources](../../concepts/pools-and-sources.md)

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

@@ -5,7 +5,7 @@ description: The Chart grammar, as a zod schema.
 
 # `chartSchema`
 
-Constant, in `@jr2/orchestrator/src/chart.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Charts.
+Constant, in `@jr2/orchestrator/src/chart.ts`. It is an export of `@jr2/orchestrator`, in the [Charts](group-charts.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 const chartSchema: z.ZodType<ChartText>

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

@@ -5,7 +5,7 @@ description: The Chart grammar for one Open body, as a zod schema.
 
 # `chartSchemaFor`
 
-Function, in `@jr2/orchestrator/src/chart.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Charts.
+Function, in `@jr2/orchestrator/src/chart.ts`. It is an export of `@jr2/orchestrator`, in the [Charts](group-charts.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function chartSchemaFor(decl: OpenBodyDeclaration): z.ZodType<ChartText>

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

@@ -5,7 +5,7 @@ description: "Make a `command` Effect: an actor slot that runs one program in th
 
 # `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.
+Function, in `@jr2/orchestrator/src/harness-client.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ## Overload 1
 
@@ -16,7 +16,7 @@ function command<
 >(
   argv: A,
   options?: Opt,
-): EffectLogic<CommandInput<A, Opt["pin"]>, CommandOutput> & OpenOf<EnvOpenParts<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
@@ -29,8 +29,8 @@ 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 of a Repo Slot, or in `/work` in a Workspace with no Repo Slot. The
-  Agent's Working tools also run in this container.
+  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
@@ -67,11 +67,9 @@ It refuses, when you call it:
 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 `slot` under a Workspace with more than one Repo Slot: `command "<slot>" runs under a
-  Workspace carrying more than one Repo Slot (<slots>) and names none — say which Worktree it
-  runs in: command(argv, { slot: "<slot>" }) (ADR-0051)`
-- a `slot` that the Workspace does not have: `command "<slot>" names Repo Slot "<name>", which
-  its Workspace does not carry (<slots>)`
+- 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
@@ -80,15 +78,13 @@ And when it starts, with no Effect secret in `env`:
 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)`
-- no `slot` under a Workspace with more than one Repo Slot: `command "<slot>" runs under a
-  Workspace carrying more than one Repo Slot (<slots>) — say which: { slot: "<slot>" }
-  (ADR-0051)`
 - 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 `slot` that the Workspace does not have: `command "<slot>" names Repo Slot "<name>", which
-  its Workspace does not carry (<slots>)`
+- 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.
@@ -98,8 +94,7 @@ And when it starts, with an Effect secret in `env`:
 - `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. `slot`: the Repo Slot whose Worktree the command runs in; needed only
-  where the Workspace has more than one. `timeout`: `"90s"`, `"10m"` or `"1h"`, default
+- `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
@@ -112,26 +107,46 @@ And when it starts, with an Effect secret in `env`:
 
 ```ts
 import { z } from "zod";
-import { arg, command, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+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 },
+  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: "testing",
+  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: { file: "test/greet.test.js" },
+        input: ({ context }) => ({ file: "test/greet.test.js", worktree: testTree(context) }),
         onDone: [
           {
             guard: ({ event }) => event.output.outcome === "exited" && event.output.code === 0,
@@ -144,6 +159,7 @@ const body = jr2Setup({
     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" } } },
   },
 });
@@ -151,7 +167,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -170,7 +185,7 @@ function command<
 >(
   argv: typeof open,
   options?: Opt,
-): EffectLogic<OpenCommandInput<Opt["pin"]>, CommandOutput> & OpenEffect<"argv" | EnvOpenParts<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

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

@@ -5,7 +5,7 @@ description: Retune the parts that a Machine carries, without a change to the mo
 
 # `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.
+Function, in `@jr2/orchestrator/src/customize.ts`. It is an export of `@jr2/orchestrator`, in the [Composition](group-composition.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function customize<M extends AnyStateMachine>(machine: M, parts: Customize<M>): M
@@ -24,6 +24,9 @@ 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>" carries no Gate slot "<slot>" — its Gate slots are: <slots>`
+- `` customize(): Gate slot "<slot>"'s look is bound once, to a look or "none" — not `open` again ``, and the
+  refusals of a look that `gate()` makes
 - `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

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

@@ -5,7 +5,7 @@ description: "Declare the config of an Instance: the default export of `jr2.conf
 
 # `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.
+Function, in `@jr2/orchestrator/src/config.ts`. It is an export of `@jr2/orchestrator`, in the [Config](group-config.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function defineConfig(c: JR2Config): JR2Config

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

@@ -5,7 +5,7 @@ description: "Define one workflow event: an event that an Agent or the caller of
 
 # `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.
+Function, in `src/define-event.ts` of `@jr2/agent-protocol`, a dependency of `@jr2/orchestrator`. It is an export of `@jr2/orchestrator`, in the [Machine and events](group-machine-and-events.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function defineEvent<const Name extends string, Input extends z.ZodObject>(def: {

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

@@ -5,7 +5,7 @@ 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.
+Function, in `@jr2/orchestrator/src/dispatch-effect.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function dispatch<
@@ -69,9 +69,10 @@ It refuses:
     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.
+    A different Orchestrator: `url` is its origin, and `token` is the secret that holds the token
+    of a Caller of it with `start` for the Workflow, and `read` too when `wait` is true. 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`.
 

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

@@ -5,7 +5,7 @@ description: "Fail the run: the Part a Machine invokes to end work that did not
 
 # `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.
+Function, in `@jr2/orchestrator/src/fail.ts`. It is an export of `@jr2/orchestrator`, in the [Failure](group-failure.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function fail(): FailSlot
@@ -37,24 +37,37 @@ It refuses an input that is not a Failure's, and the run ends `error`: ``fail: t
 
 ```ts
 import { z } from "zod";
-import { command, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+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: Workspaced<z.infer<typeof runInput>, "app"> },
+  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: "testing",
+  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,
@@ -67,6 +80,7 @@ const body = jr2Setup({
     // 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" } } },
   },
 });
@@ -74,7 +88,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 

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

@@ -5,25 +5,28 @@ description: "Make a Worktree file the body of an `http` Effect: `body: file(\"d
 
 # `file`
 
-Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function file<S extends z.ZodType | undefined = undefined>(path: FromInput<S, string>, options: {
-  slot?: string;
   segments?: FromInput<S, readonly string[]>;
   contentType?: string;
 } = {}): FileBody<S>
 ```
 
 Make a Worktree file the body of an `http` Effect: `body: file("dist/report.pdf")`. The Effect
-then runs in the Sandbox Effector of the Workspace whose body invokes it. That Effector opens the
-file in the Worktree and sends it. In a Workspace with no Repo Slot, the path is relative to
+then runs in the Sandbox Effector of the Workspace whose body invokes it. Under a Workspace with
+Repo Slots, the invoke's input names the Worktree: `input: { worktree: "/work/app/fix" }`. It is a
+Worktree that a cut of this run made. That Effector opens the file in that Worktree and sends it.
+In a Workspace with no Repo Slot, the input names no `worktree`, and the path is relative to
 `/work`, the folder that its steps share. Use it with `PUT`, `POST` or `PATCH`. `path` and
 `segments` can be functions of the input of the Effect.
 
-Some paths and files give the output `refused`, and then nothing is sent. The path has a symlink
-in it, has `..`, or is absolute. Or the file is a FIFO, a directory, or a file with more than one
-link.
+Some inputs, paths and files give the output `refused`, and then nothing is sent. The `worktree`
+has no cut in this Sandbox: `no cut made <path> in this Sandbox: cut it with worktree(); nothing
+was sent`. Or the input names a `worktree` in a Workspace with no Repo Slot. Or the path has a
+symlink in it, has `..`, or is absolute. Or the file is a FIFO, a directory, or a file with more
+than one link.
 
 It refuses, when you call it:
 - a path that is not a string or a function: `file(path): the path is a string, or a function of
@@ -43,16 +46,17 @@ And at `jr2 up`, an Effect that no `workspace()` invokes: `workflow "<workflow>"
 there is no Worktree to read; invoke it from a workspace()'s body, or send a json or text body
 (ADR-0068)`.
 
+And when it starts, under a Workspace with Repo Slots, an input with no `worktree`: ``http
+"<slot>" reads a Worktree file, under a Workspace with Repo Slots, and its input names no
+`worktree` ``.
+
 **Parameters**
 
-- `path` ([`FromInput`](type-frominput.md)): The file, relative to the Worktree of the Repo Slot, or to `/work` in a Workspace
-  with no Repo Slot: a string, or a function of the input of the Effect that gives one.
+- `path` ([`FromInput`](type-frominput.md)): The file, relative to the Worktree that `worktree` of the input names, or to
+  `/work` in a Workspace with no Repo Slot: a string, or a function of the input of the Effect
+  that gives one.
 - `options`: Optional. Each field says what it does.
 
-  - `slot` (optional): `string`
-
-    The Repo Slot whose Worktree holds the file. Write it only when the Workspace has more than
-    one.
   - `segments` (optional): `FromInput<S, readonly string[]>`
 
     Path segments that jr2 adds to the end of the url, as `path` does in `request` for a json or
@@ -73,17 +77,22 @@ import {
   fail,
   file,
   http,
+  isReady,
   jr2Setup,
   secret,
   workspace,
+  worktree,
   type Workspaced,
 } from "@jr2/orchestrator";
 
 type Input = Workspaced<{}, "app">;
 
+const reportTree = (context: Input) => `${context.workspace.repos.app}/report` as const;
+
 const body = jr2Setup({
   types: {} as { context: Input; input: Input },
   actors: {
+    cut: worktree(),
     build: command(["npm", "run", "report"]),
     upload: http({
       method: "PUT",
@@ -100,18 +109,29 @@ const body = jr2Setup({
   id: "report",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "building",
+  initial: "cutting",
   states: {
-    building: { invoke: { src: "build", onDone: "uploading" } },
-    uploading: { invoke: { src: "upload", onDone: "done" } },
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reportTree(context), branch: "report" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "building" }, { target: "notCut" }],
+      },
+    },
+    building: {
+      invoke: { src: "build", input: ({ context }) => ({ worktree: reportTree(context) }), onDone: "uploading" },
+    },
+    uploading: {
+      invoke: { src: "upload", input: ({ context }) => ({ worktree: reportTree(context) }), onDone: "done" },
+    },
     done: { 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, {
   repos: { app: { url: "https://github.com/you/app.git" } },
-  spec: () => ({ branch: "report" }),
 });
 ```
 

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

@@ -5,7 +5,7 @@ description: "Make the `input` of the invoke of a state that a pick enters: the
 
 # `fromPick`
 
-Function, in `@jr2/orchestrator/src/pick.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/pick.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ## Overload 1
 

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

@@ -0,0 +1,118 @@
+---
+title: gate
+description: "The Gate: an input that a run waits for from outside the run (ADR-0011)."
+---
+
+# `gate`
+
+Function, in `@jr2/orchestrator/src/gate.ts`. It is an export of `@jr2/orchestrator`, in the [Gates](group-gates.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+function gate<
+  const D extends readonly EventDef[],
+  M extends z.ZodObject = z.ZodObject<{}>,
+  R extends AnyActorLogic = never,
+>(
+  spec: {
+    readonly meta?: M;
+    readonly delivers: D;
+    readonly hooks?: GateHooks<z.output<NoInfer<M>>, Delivered<D>>;
+    readonly look?: GateLook<z.output<NoInfer<M>>, Delivered<D>, R> | typeof open | "none";
+    readonly reply?: GateReply<z.output<NoInfer<M>>, Delivered<D>>;
+  },
+): GateSlot<z.output<M>, Delivered<D>>
+```
+
+The Gate: an input that a run waits for from outside the run ([ADR-0011](../decisions/0011-workflow-defined-events.md)).
+
+`gate({ … })` declares a GATE SLOT that also hears a Hook: put it in `actors` and invoke it by
+its key. A plain Gate needs no value: jr2Setup puts it in each Machine as `invoke: { src: "gate" }`.
+Its accepted set derives from the invoking state's transitions, and a Caller answers it with
+`jr2 send`, the Console or `POST /runs/:runId/gates/:gate/events`.
+
+- `meta`: a zod object of the meta that the invoking state sets. The Gate checks it when it
+  opens, and the handlers, the look and `reply` read it typed.
+- `delivers`: the events that the handlers and the look can give. An event whose def leaves the
+  audience unset reads as `audience: "external"`, so no Agent below the Gate has it on its Menu.
+  `createMachine` refuses an entry that the Gate's derived accepted set does not hold.
+- `hooks`: a handler for each Hook kind id and event key. A handler reads `{ payload, meta,
+  caller }` and gives one event of `delivers`, or `undefined` to ignore the delivery. It is pure
+  and synchronous. A throw is a refusal that the hook log keeps; it never faults the run.
+- `look`: the Gate's read of the fact that it waits for (see [`GateLook`](type-gatelook.md)), `"none"` for a
+  Gate that hears a command, or `open` for the composer to bind with
+  `customize(m, { gates: { <slot>: { look } } })`. With no look and no `after` on the invoking
+  state, or with an Open look, `jr2 up` warns.
+- `reply`: the text that the person who acted reads, for a Hook kind whose answer a person reads.
+
+It throws on a spec that it cannot run: an unknown key, a `delivers` that is empty or that holds an
+entry `defineEvent` did not make, a handler that is not a function, or a look whose read is not an
+`http` Effect marked `idempotent: true` or a promise.
+
+**Parameters**
+
+- `spec`
+
+  - `meta` (optional): `M`
+
+    A zod object for the meta that the invoking state sets. The Gate checks it when it opens.
+  - `delivers`: `D`
+
+    The events that the handlers and the look can give.
+  - `hooks` (optional): `GateHooks<z.output<NoInfer<M>>, Delivered<D>>`
+
+    The handlers, by Hook kind id and event key.
+  - `look` (optional): `GateLook<z.output<NoInfer<M>>, Delivered<D>, R> | typeof open | "none"`
+
+    The look, `"none"` for a Gate that hears a command, or `open` for its composer to bind.
+  - `reply` (optional): `GateReply<z.output<NoInfer<M>>, Delivered<D>>`
+
+    The text that the person who acted reads.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import type {} from "@jr2/orchestrator/hooks/github";
+import { defineEvent, gate, jr2Setup } from "@jr2/orchestrator";
+
+const approve = defineEvent({ name: "approve", input: z.object({ by: z.string() }) });
+
+const review = gate({
+  meta: z.object({ pr: z.string(), sha: z.string() }),
+  delivers: [approve],
+  hooks: {
+    github: {
+      "pull_request_review.submitted": ({ payload, meta }) =>
+        payload.pull_request.html_url === meta.pr &&
+        payload.review.commit_id === meta.sha &&
+        payload.review.state === "approved"
+          ? { type: "approve", by: payload.review.user.login }
+          : undefined,
+    },
+  },
+  look: "none",
+});
+
+export const machine = jr2Setup({
+  types: {} as { context: { pr: string; sha: string }; input: { pr: string; sha: string } },
+  events: [approve],
+  actors: { review },
+}).createMachine({
+  id: "pr",
+  context: ({ input }) => input,
+  initial: "inReview",
+  states: {
+    inReview: {
+      invoke: { src: "review", input: ({ context }) => ({ meta: { pr: context.pr, sha: context.sha } }) },
+      on: { approve: "merged" },
+    },
+    merged: { type: "final" },
+  },
+});
+```
+
+**See also**
+
+- [Gates](../../concepts/gates.md)
+- [Answer a Gate from a forge](../../guides/answer-a-gate-from-a-forge.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/group-agents.md

@@ -0,0 +1,15 @@
+---
+title: "Authoring surface: Agents"
+description: An Agent slot and the definition it carries (ADR-0028, ADR-0049).
+---
+
+# Authoring surface: Agents
+
+This page is one group of the names that `@jr2/orchestrator` exports from its root, on the [Authoring surface](../authoring-surface.md) page. It gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in this folder.
+
+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`](agent.md) (function): Make an Agent: an actor slot that runs one Turn of a model each time a state invokes it.
+- [`AgentDefinition`](type-agentdefinition.md) (type): An Agent's definition: which model it runs, its instructions, and what it may do to the Workspace.
+- [`AgentMcpServer`](type-agentmcpserver.md) (type): One MCP server that an Agent uses, and the tools that it may call there.
+- [`ThinkingLevel`](type-thinkinglevel.md) (type): How hard the model thinks before it answers: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"` or `"xhigh"`.

package/docs/reference/authoring-surface/group-charts.md

@@ -0,0 +1,16 @@
+---
+title: "Authoring surface: Charts"
+description: "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)."
+---
+
+# Authoring surface: Charts
+
+This page is one group of the names that `@jr2/orchestrator` exports from its root, on the [Authoring surface](../authoring-surface.md) page. It gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in this folder.
+
+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`](openbody.md) (function): Make an Open body: the actor slot that a Chart binds.
+- [`OpenBodyDeclaration`](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`](type-openbodyoutput.md) (type): The output of an Open body.
+- [`chartSchema`](chartschema.md) (constant): The Chart grammar, as a zod schema.
+- [`chartSchemaFor`](chartschemafor.md) (function): The Chart grammar for one Open body, as a zod schema.

package/docs/reference/authoring-surface/group-composition.md

@@ -0,0 +1,25 @@
+---
+title: "Authoring surface: Composition"
+description: "A part left Open, a Machine's parts retuned, a Pool over a Source (ADR-0017, ADR-0049, ADR-0054, ADR-0060)."
+---
+
+# Authoring surface: Composition
+
+This page is one group of the names that `@jr2/orchestrator` exports from its root, on the [Authoring surface](../authoring-surface.md) page. It gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in this folder.
+
+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`](open.md) (constant): Leave a part of a Machine Open: for the Instance that registers the Machine to bind with `customize()`.
+- [`customize`](customize.md) (function): Retune the parts that a Machine carries, without a change to the module that exports it.
+- [`Customize`](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`](type-effectbinding.md) (type): The values that bind the Open parts of one Effect.
+- [`Size`](type-size.md) (type): The Size of a Workspace: the most memory and cpu that its whole Sandbox can use.
+- [`UserContainer`](type-usercontainer.md) (type): The User Container in its object form: its image, and its part of the Workspace's Size.
+- [`carry`](carry.md) (function): Give the item itself.
+- [`pool`](pool.md) (function): Make a Pool: a Machine that runs one worker for each item that a Source gives, with at most `cap` workers at once.
+- [`reread`](reread.md) (function): Read the Source again.
+- [`skip`](skip.md) (function): Bring nothing, and say why.
+- [`source`](source.md) (function): Declare a Source: where a `pool()` gets its work items, one at a time.
+- [`PoolNextInput`](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.
+- [`SourceReply`](type-sourcereply.md) (type): The text that the person who acted reads, from this Source's verdict (ADR-0011, ADR-0017).
+- [`SourceVerdict`](type-sourceverdict.md) (type): A Source's verdict on one delivery, as its `reply` reads it (ADR-0017).

package/docs/reference/authoring-surface/group-config.md

@@ -0,0 +1,17 @@
+---
+title: "Authoring surface: Config"
+description: "`jr2.config.ts`, the deployment facts a Machine cannot carry (ADR-0050)."
+---
+
+# Authoring surface: Config
+
+This page is one group of the names that `@jr2/orchestrator` exports from its root, on the [Authoring surface](../authoring-surface.md) page. It gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in this folder.
+
+`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`](defineconfig.md) (function): Declare the config of an Instance: the default export of `jr2.config.ts`.
+- [`JR2Config`](type-jr2config.md) (type): The shape of `jr2.config.ts`: the deployment facts of an Instance, which a Machine cannot carry.
+- [`McpRemoteServer`](type-mcpremoteserver.md) (type): A remote MCP server, which the Harness reaches over Streamable HTTP.
+- [`McpServer`](type-mcpserver.md) (type): One MCP server of the Instance: a `McpRemoteServer` (`url`) or a `McpStdioServer` (`command`).
+- [`McpStdioServer`](type-mcpstdioserver.md) (type): A stdio MCP server: a program of the Sandbox Image that the Harness starts for each Agent conversation, through jr2's spawner, inside the Agent's confinement.
+- [`RunsConfig`](type-runsconfig.md) (type): How long jr2 keeps an ended run, and the volume that keeps it (ADR-0065).