@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/reference/authoring-surface/type-permissiveworkspaceoptions.md

@@ -10,23 +10,18 @@ Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a
 ```ts
 type PermissiveWorkspaceOptions<TSlots extends string, TInput = unknown> = SandboxOptions<TSlots, TInput> & {
   input?: never;
-  spec: (args: { input: TInput }) => WorkspaceSpec;
 };
 ```
 
-The options of a `workspace()` with no `input`: it starts with any input. The `input` of `spec`
-is then `unknown`, and `spec` must check it before it reads a field.
+The options of a `workspace()` with no `input`: it starts with any input. The `input` of a
+per-run Repo Slot is then `unknown`, and the mapper must check it before it reads a field.
 
-Use it for a Workspace that a Pool or another Machine starts. Give the parameter of `spec` a
-type to say what that input is: `spec: ({ input }: { input: Item }) => …`. That also types the
-input of the Workspace. For a Workspace that a caller starts, declare `input`.
+Use it for a Workspace that a Pool or another Machine starts. The body's `input` type says what
+that input is, and that also types the input of the Workspace. For a Workspace that a caller
+starts, declare `input`.
 
 **Fields**: each field of [`SandboxOptions`](type-sandboxoptions.md), and these:
 
 - `input` (optional): `never`
 
   Not present: a `workspace()` without `input` starts with any input.
-- `spec`: `(args: { input: TInput; }) => WorkspaceSpec`
-
-  A function from the input to the Workspace's [`WorkspaceSpec`](type-workspacespec.md). Its `input` is
-  `unknown` unless you give the parameter a type: `spec: ({ input }: { input: Item }) => …`.

package/docs/reference/authoring-surface/type-poolnextinput.md

@@ -0,0 +1,22 @@
+---
+title: PoolNextInput
+description: "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."
+---
+
+# `PoolNextInput`
+
+Type, 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
+type PoolNextInput<TInput = unknown> = { active: string[]; settled: string[]; input: TInput };
+```
+
+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. So a Source over a list that a Machine holds needs no state
+of its own.
+
+**Fields**
+
+- `active`: `string[]`
+- `settled`: `string[]`
+- `input`: `TInput`

package/docs/reference/authoring-surface/type-poolspec.md

@@ -1,6 +1,6 @@
 ---
 title: PoolSpec
-description: "What you pass to `pool()`: where the items come from, how many workers run at once, and what each worker gets."
+description: What you pass to `pool()` with a child Machine as its worker.
 ---
 
 # `PoolSpec`
@@ -11,17 +11,18 @@ Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type
 type PoolSpec<T, TInput = unknown> = {
   id?: string;
   input?: z.ZodObject;
-  source: SourceSpec<T>;
+  source: SourceSpec<T, TInput> | SourceSpec<T> | ReadSourceSpec<T, TInput> | ReadSourceSpec<T>;
   itemId: (item: T) => string;
   cap?: number | ((args: { input: TInput }) => number);
   itemInput?: (item: T, args: { input: TInput }) => unknown;
   onDrained?: "final";
   failures?: "fail" | "report";
+  standing?: false;
 };
 ```
 
-What you pass to `pool()`: where the items come from, how many workers run at once, and what
-each worker gets.
+What you pass to `pool()` with a child Machine as its worker. It says where the items come
+from, how many workers run at once, and what each worker gets.
 
 **Fields**
 
@@ -33,9 +34,10 @@ each worker gets.
   The run input of the Pool, as a zod object: what a caller sends to start a run. `cap` and
   `itemInput` read it, typed by it. A worker never gets it: each worker gets its item. Default:
   none, and then their `input` is `unknown`.
-- `source`: `SourceSpec<T>`
+- `source`: `SourceSpec<T, TInput> | SourceSpec<T> | ReadSourceSpec<T, TInput> | ReadSourceSpec<T>`
 
-  Where the items come from. Make it with [`source`](source.md).
+  Where the items come from: a pull or a read Source. Make it with [`source`](source.md). A push Source
+  needs a standing Pool of runs.
 - `itemId`: `(item: T) => string`
 
   The id of an item. The Pool uses it as the id of the item's worker and in the `active` list
@@ -58,3 +60,6 @@ each worker gets.
   ends with failures, `drained` or `deadlocked`, it fails the run with the reason
   `"<n> of <m> items failed"` and the detail `{ status, items, failures }`. `"report"`: the Pool
   ends `done`, with the failures in its output. Default: `"fail"`.
+- `standing` (optional): `false`
+
+  A Pool of child Machines never stands: a child cannot be handed over.

package/docs/reference/authoring-surface/type-pushinput.md

@@ -1,6 +1,6 @@
 ---
 title: PushInput
-description: "The input of a `push` Effect: `{ sha }` with `pin`, and `{ message }` with `squash`."
+description: "The input of a `push` Effect: the Worktree that a cut made, `{ sha }` with `pin`, and `{ message }` with `squash`."
 ---
 
 # `PushInput`
@@ -8,8 +8,27 @@ description: "The input of a `push` Effect: `{ sha }` with `pin`, and `{ message
 Type, in `@jr2/orchestrator/src/sandbox-effect.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
 
 ```ts
-type PushInput<O extends PushOptions> = (O["pin"] extends true ? { sha: string } : unknown) &
+type PushInput<O extends PushOptions> = {
+  worktree: O extends { slot: infer S extends string } ? `/work/${S}/${string}` : AnyWorktreePath;
+  branch?: never;
+  to?: never;
+  cwd?: never;
+  path?: never;
+} & (O["pin"] extends true ? { sha: string } : unknown) &
   (O["squash"] extends true ? { message: string } : unknown);
 ```
 
-The input of a `push` Effect: `{ sha }` with `pin`, and `{ message }` with `squash`.
+The input of a `push` Effect: the Worktree that a cut made, `{ sha }` with `pin`, and
+`{ message }` with `squash`. It names no branch: jr2 reads it from the cut's record, so no word of
+a Chart reaches a remote branch. The other keys are refused by name, because each is a key of a
+cut or a Turn, and a mapper's excess key is no compile error otherwise.
+
+**Fields**
+
+- `worktree`: ``O extends { slot: infer S extends string; } ? `/work/${S}/${string}` : AnyWorktreePath``
+
+  The Worktree to push: `event.output.path` of its cut, of the push's Repo Slot.
+- `branch` (optional): `never`
+- `to` (optional): `never`
+- `cwd` (optional): `never`
+- `path` (optional): `never`

package/docs/reference/authoring-surface/type-pushoutput.md

@@ -5,12 +5,13 @@ description: "The output of a `push` Effect: what the `onDone` of its state gets
 
 # `PushOutput`
 
-Type, in `@jr2/orchestrator/src/sandbox-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Type, in `@jr2/orchestrator/src/sandbox-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
 type PushOutput =
   | Exclude<PushWireOutput, { outcome: "pushed" }>
-  | (Omit<Extract<PushWireOutput, { outcome: "pushed" }>, "bundle"> & { sync: SyncState; syncReason?: string });
+  | (Omit<Extract<PushWireOutput, { outcome: "pushed" }>, "bundle"> & { sync: SyncState; syncReason?: string })
+  | LaterOutcome;
 ```
 
 The output of a `push` Effect: what the `onDone` of its state gets as `event.output`. Every
@@ -40,6 +41,8 @@ Beside `pushed`, `sync` tells what jr2 did to the Agent's branch after the push:
 
 With `busy` or `not-synced`, `syncReason` tells why, and jr2 tries again before the next push.
 
+The union is open (`LaterOutcome`): give the rest a last arm with no guard.
+
 **Forms**: it is one of these objects.
 
 - Form 1: `outcome`, `stage`, `reason`, `detail`
@@ -70,13 +73,28 @@ With `busy` or `not-synced`, `syncReason` tells why, and jr2 tries again before
   - `squashed` (optional): `"signed" | "unsigned"`
   - `sync`: [`SyncState`](type-syncstate.md)
   - `syncReason` (optional): `string`
+- Form 5: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
 
 **Example**
 
 ```ts
-import { fail, jr2Setup, push, type PushOutput, workspace, type Workspaced } from "@jr2/orchestrator";
+import {
+  fail,
+  isReady,
+  jr2Setup,
+  push,
+  type PushOutput,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+type Input = Workspaced<{ branch: string; sha: string }, "app">;
 
-type Input = Workspaced<{ sha: string }, "app">;
+const releaseTree = (context: Input) => `${context.workspace.repos.app}/release` as const;
 
 // A push that did not happen (`rejected` or `diverged`) is a different problem from one jr2
 // cannot see (`unknown`).
@@ -85,17 +103,24 @@ const notPushed = (output: PushOutput): boolean =>
 
 const body = jr2Setup({
   types: {} as { context: Input; input: Input },
-  actors: { publish: push({ pin: true }), fail: fail() },
+  actors: { cut: worktree({ expect: "existing" }), publish: push({ pin: true }), fail: fail() },
 }).createMachine({
   id: "release",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "publishing",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: releaseTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "publishing" }, { target: "notCut" }],
+      },
+    },
     publishing: {
       invoke: {
         src: "publish",
-        input: ({ context }) => ({ sha: context.sha }),
+        input: ({ context }) => ({ worktree: releaseTree(context), sha: context.sha }),
         onDone: [
           { guard: ({ event }) => event.output.outcome === "pushed", target: "published" },
           { guard: ({ event }) => notPushed(event.output), target: "notPushed" },
@@ -107,13 +132,13 @@ const body = jr2Setup({
     // Not final states: each one fails the run, with its own reason.
     notPushed: { invoke: { src: "fail", input: { reason: "the remote refused the push" } } },
     unknown: { invoke: { src: "fail", input: { reason: "jr2 cannot tell if the push happened" } } },
+    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: "release" }),
 });
 ```
 

package/docs/reference/authoring-surface/type-pushsourcespec.md

@@ -0,0 +1,38 @@
+---
+title: PushSourceSpec
+description: A push Source.
+---
+
+# `PushSourceSpec`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type PushSourceSpec<T> = {
+  item: z.ZodType<T>;
+  hooks: SourceHooks<Carry<T>, {}>;
+  hold?: number;
+  reply?: SourceReply<T>;
+};
+```
+
+A push Source. Nothing can be read again, and each item comes in a Hook's delivery. A handler
+gives `carry(item)` or `skip(reason)`. The Pool holds each carried item in its run's blob, in the
+order of arrival, until it claims it. Only a standing Pool takes a push Source. Make one with
+[`source`](source.md).
+
+**Fields**
+
+- `item`: `z.ZodType<T>`
+
+  The schema of an item. The Pool parses each carried item with it before it holds it.
+- `hooks`: `SourceHooks<Carry<T>, {}>`
+
+  A handler for each Hook kind id and event key. It gives `carry(item)` or `skip(reason)`.
+- `hold` (optional): `number`
+
+  The most items that the Pool holds. Above it, a carried item is `hold-full`, and the Hook's
+  answer is 429. Default: 1000.
+- `reply` (optional): `SourceReply<T>`
+
+  The text that the person who acted reads, from the verdict. Default: none.

package/docs/reference/authoring-surface/type-readsourcespec.md

@@ -0,0 +1,47 @@
+---
+title: ReadSourceSpec
+description: A read Source.
+---
+
+# `ReadSourceSpec`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type ReadSourceSpec<T, TInput = unknown, R extends AnyActorLogic = AnyActorLogic> = {
+  read: R;
+  items?: (output: LookOutput<R>, args: { input: TInput }) => readonly T[];
+  wake?: EventDef;
+  pollEvery?: number;
+  hooks?: SourceHooks<Reread, TInput>;
+  reply?: SourceReply<T>;
+};
+```
+
+A read Source. `read` reads the whole set, and `items` turns its answer into the items, in
+order. The read is an `http` Effect marked `idempotent: true`, so it can spend a secret that the
+Instance Effector holds, or a promise (`fromPromise`). Its input is the Pool's input. A read that
+fails gives no items. The read is the truth: a Hook's delivery only says "read again". Make one
+with [`source`](source.md).
+
+**Fields**
+
+- `read`: `R`
+
+  The read: an `http` Effect marked `idempotent: true`, or a promise. The Pool runs it at the
+  start, after a worker settles, on `wake`, on a Hook's `reread()` and every `pollEvery`.
+- `items` (optional): `(output: LookOutput<R>, args: { input: TInput; }) => readonly T[]`
+
+  The items in the read's answer, in order. Default: the answer itself, when it is an array.
+- `wake` (optional): [`EventDef`](type-eventdef.md)
+
+  As a pull Source's `wake`.
+- `pollEvery` (optional): `number`
+
+  Read again after this many milliseconds while the Pool waits. Default: none.
+- `hooks` (optional): `SourceHooks<Reread, TInput>`
+
+  What a Hook's delivery does: a handler gives `reread()` or `skip(reason)`. Default: none.
+- `reply` (optional): `SourceReply<T>`
+
+  The text that the person who acted reads, from the verdict. Default: none.

package/docs/reference/authoring-surface/type-reposlot.md

@@ -5,7 +5,7 @@ description: The value of one Repo Slot in `workspace({ repos })`.
 
 # `RepoSlot`
 
-Type, in `@jr2/orchestrator/src/parts.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Workspaces and Repos.
+Type, in `@jr2/orchestrator/src/parts.ts`. It is an export of `@jr2/orchestrator`, in the [Workspaces and Repos](group-workspaces-and-repos.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type RepoSlot<TInput = unknown> =
@@ -24,10 +24,11 @@ The value of one Repo Slot in `workspace({ repos })`. One of:
 - a function of the run input, `({ input }) => url` or a [`Binding`](type-binding.md): each run chooses. The
   url must match an entry of `git.credentials` in `jr2.config.ts`, or the run cannot use it.
 
-The key of the slot is a directory name under `/work`. It starts with a letter, and
-`workspace()` and `customize()` refuse a key that does not: ``<where>: Repo Slot key "<key>" is
-not a directory name — a slot becomes `/work/<slot>` and its order matters, so it starts with a
-letter and matches /^[A-Za-z][A-Za-z0-9._-]*$/ (ADR-0051).`` They refuse a value of another
+The key of the slot is a directory name under `/work`. It starts with a letter, so never with
+`.`: `/work/.jr2/` is reserved for jr2. `workspace()` and `customize()` refuse a key that does
+not: ``<where>: Repo Slot key "<key>" is not a directory name — a slot becomes `/work/<slot>`,
+`/work/.jr2/` is reserved for jr2, and its order matters, so it starts with a letter and matches
+/^[A-Za-z][A-Za-z0-9._-]*$/ (ADR-0051, ADR-0075).`` They refuse a value of another
 shape: ``<where>: Repo Slot "<slot>" is <what> — a slot is `open`, a url, `{ url, ref? }`, or a
 mapper `({ input }) => url | { url, ref? }` over the door (ADR-0051).``
 
@@ -58,7 +59,6 @@ export const deploy = workspace(body, {
     docs: "https://github.com/you/docs.git",
     config: open,
   },
-  spec: ({ input }) => ({ branch: `deploy/${input.service}` }),
 });
 ```
 

package/docs/reference/authoring-surface/type-reread.md

@@ -0,0 +1,18 @@
+---
+title: Reread
+description: What `reread()` gives.
+---
+
+# `Reread`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type Reread = { readonly [VERDICT]: "reread" };
+```
+
+What `reread()` gives. Only a Source that can read (`next` or `read`) gives it.
+
+**Fields**
+
+- `[VERDICT]`: `"reread"`

package/docs/reference/authoring-surface/type-runsconfig.md

@@ -0,0 +1,41 @@
+---
+title: RunsConfig
+description: How long jr2 keeps an ended run, and the volume that keeps it (ADR-0065).
+---
+
+# `RunsConfig`
+
+Type, 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
+type RunsConfig = {
+  retain?: `${number}${"m" | "h" | "d" | "w"}`;
+  volume?: string;
+};
+```
+
+How long jr2 keeps an ended run, and the volume that keeps it ([ADR-0065](../decisions/0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)). When the config loads,
+a bad field is refused: `<file> at runs.<field>: <problem>`.
+
+**Fields**
+
+- `retain` (optional): `` `${number}${"m" | "h" | "d" | "w"}` ``
+
+  How long jr2 keeps an ended run: its row, its conversations and the hook log. A number and
+  `m`, `h`, `d` or `w`, such as `"90d"`. At least `"1h"`, with no upper limit. A live run is
+  never removed. Default: `"30d"`.
+- `volume` (optional): `string`
+
+  The size of the Orchestrator's state volume claim: a number and a unit, such as `"5Gi"` or
+  `"500Mi"` (a number with no unit is refused). Default: `"5Gi"` for a
+  new claim; unset, `jr2 up` keeps the size of a claim that exists. A larger size grows the
+  claim where its StorageClass allows expansion, else `jr2 up` refuses it. A smaller size is
+  refused: Kubernetes never makes a claim smaller.
+
+**Example**
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({ runs: { retain: "90d", volume: "20Gi" } });
+```

package/docs/reference/authoring-surface/type-sandboxoptions.md

@@ -10,6 +10,7 @@ Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a
 ```ts
 type SandboxOptions<TSlots extends string, TInput = unknown> = {
   image?: string;
+  workGroup?: number;
   user?: string | UserContainer;
   resources?: Size;
   repos: Record<TSlots, RepoSlot<TInput>> | typeof open;
@@ -30,6 +31,9 @@ clones. They are the same for each run.
   (`import.meta.resolve("./image")`), which `jr2 up` builds, or a registry ref. Its floor is
   glibc and git; jr2 adds its own runtime at `/opt/jr2`. Default: the Instance's
   `images/default`, then jr2's Harness image.
+- `workGroup` (optional): `number`
+
+  The group id that owns the files in `/work`. Default: 2000. A non-negative integer.
 - `user` (optional): `string | UserContainer`
 
   The User Container: a third container in the Sandbox, for a service that must run beside the
@@ -52,8 +56,8 @@ clones. They are the same for each run.
   choice. The name is the key of `workspace.repos` in the body and the directory under `/work`.
   At least one slot. Leave `repos` out for a Workspace with no Repo Slot (see
   [`NoSlotWorkspaceOptions`](type-noslotworkspaceoptions.md)). Each value is one of:
-  - a url, or `{ url, ref }`, where `ref` is the branch or commit that the Worktree starts from
-    (default: the Repo's default branch);
+  - a url, or `{ url, ref }`, where `ref` is the branch, the tag or the commit that the clone
+    stays on, and that a new branch starts from (default: the Repo's default branch);
   - `open`, for the Instance that registers the Machine to bind with `customize()`;
   - a function of the run input, `({ input }) => url` or `{ url, ref }`, when each run chooses.
 
@@ -63,8 +67,11 @@ clones. They are the same for each run.
 
   The Held secrets that this Sandbox can use: names from the `secrets` list in `jr2.config.ts`.
   The Sandbox's Custodian holds each value and puts it into requests to the hosts of that Held
-  secret. The Agent sees only a Stand-in. You need not list the model key of an Agent that runs
-  here: its provider claims it. Each name once.
+  secret. Listing a name also gives its Stand-in to the Agent's programs — each `bash` call, test,
+  build and `command` — in their env under that name, so code in `/work` can spend it ([ADR-0076](../decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)).
+  You need not list the model key of an Agent that runs here: its provider claims it, and the
+  Harness gives it to the model calls alone. List the model key only when code in `/work` must
+  call the model itself: such a call is outside the Turn's usage record. Each name once.
 - `effector` (optional): `object`
 
   The image of the Sandbox Effector. This container runs three kinds of Effect for this

package/docs/reference/authoring-surface/type-sender.md

@@ -8,12 +8,37 @@ description: "Who delivered an event: an Agent by its slot, or a Gate by its inv
 Type, in `src/define-event.ts` of `@jr2/agent-protocol`, a dependency of `@jr2/orchestrator`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
 
 ```ts
-type Sender = { readonly party: "agent" | "gate"; readonly id: string };
+type Sender = {
+  readonly party: "agent" | "gate";
+  readonly id: string;
+  readonly via?: "token" | "jwt" | "hook";
+  readonly name?: string;
+  readonly onBehalfOf?: string;
+  readonly checked?: readonly SenderCallerField[];
+};
 ```
 
 Who delivered an event: an Agent by its slot, or a Gate by its invoke id ([ADR-0015](../decisions/0015-authoring-surface-absorbs-the-mechanism.md)).
 
+A Gate's event also carries the Caller that answered it ([ADR-0011](../decisions/0011-workflow-defined-events.md), [ADR-0078](../decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): `via` and `name`
+name it, `onBehalfOf` is the party that it says it acts for, and `checked` names the fields that
+jr2 verified. `via` and `name` are always checked, because an authenticator made them;
+`onBehalfOf` is checked only for a Hook, whose signature covers the payload that it comes from.
+An event that a Gate gives with no Caller (its `look`) has none of these fields.
+
 **Fields**
 
 - `party`: `"agent" | "gate"`
 - `id`: `string`
+- `via` (optional): `"token" | "jwt" | "hook"`
+
+  The authenticator that made the Caller: `token`, `jwt` or `hook`. A Gate's event only.
+- `name` (optional): `string`
+
+  The Caller's name for that authenticator. A Gate's event only.
+- `onBehalfOf` (optional): `string`
+
+  The party that the Caller says it acts for. A claim, unless `checked` names it.
+- `checked` (optional): `readonly SenderCallerField[]`
+
+  The fields of the Caller that jr2 verified.

package/docs/reference/authoring-surface/type-sendercallerfield.md

@@ -0,0 +1,14 @@
+---
+title: SenderCallerField
+description: "A field of a `Sender`'s Caller that jr2 can verify."
+---
+
+# `SenderCallerField`
+
+Type, in `src/define-event.ts` of `@jr2/agent-protocol`, a dependency of `@jr2/orchestrator`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type SenderCallerField = "via" | "name" | "onBehalfOf";
+```
+
+A field of a [`Sender`](type-sender.md)'s Caller that jr2 can verify.

package/docs/reference/authoring-surface/type-size.md

@@ -5,7 +5,7 @@ description: "The Size of a Workspace: the most memory and cpu that its whole Sa
 
 # `Size`
 
-Type, in `@jr2/orchestrator/src/size.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+Type, in `@jr2/orchestrator/src/size.ts`. It is an export of `@jr2/orchestrator`, in the [Composition](group-composition.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type Size = {

package/docs/reference/authoring-surface/type-skip.md

@@ -0,0 +1,19 @@
+---
+title: Skip
+description: "What `skip(reason)` gives: the delivery brings nothing, and the reason says why."
+---
+
+# `Skip`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type Skip = { readonly [VERDICT]: "skip"; readonly reason: string };
+```
+
+What `skip(reason)` gives: the delivery brings nothing, and the reason says why.
+
+**Fields**
+
+- `[VERDICT]`: `"skip"`
+- `reason`: `string`

package/docs/reference/authoring-surface/type-slothandles.md

@@ -9,9 +9,7 @@ Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a
 
 ```ts
 type SlotHandles<TSlots extends string> = {
-  repos: Record<TSlots, string>;
-  branch: string;
-  review?: Partial<Record<TSlots, string>>;
+  repos: { [K in TSlots]: `/work/${K}` };
 };
 ```
 
@@ -19,14 +17,8 @@ The handles of a Workspace that declares Repo Slots. @internal
 
 **Fields**
 
-- `repos`: `Record<TSlots, string>`
+- `repos`: ``{ [K in TSlots]: `/work/${K}`; }``
 
-  The absolute path of each Repo Slot's Worktree, `/work/<slot>/<branch>`, in the order that
-  `repos` declares the slots. Give one to an Agent's Turn as its `cwd`.
-- `branch`: `string`
-
-  The branch that the Workspace works on: the `branch` of the spec.
-- `review` (optional): `Partial<Record<TSlots, string>>`
-
-  The path of each Repo Slot's review Worktree. Present only when the spec has `reviewSha`.
-  Give one to a reviewer's Turn as its `cwd`.
+  The folder of each Repo Slot, `/work/<slot>`, in the order that `repos` declares the slots.
+  `${handle}/default` is the clone, on the Binding's base. Any other Worktree is one the Machine
+  cut with `worktree()`.

package/docs/reference/authoring-surface/type-sourcehooks.md

@@ -0,0 +1,23 @@
+---
+title: SourceHooks
+description: "A Source's handlers, by Hook kind and event key."
+---
+
+# `SourceHooks`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type SourceHooks<Out, TInput = unknown> = KindHooks<SourceIn<TInput>, Out | Skip>;
+```
+
+A Source's handlers, by Hook kind and event key. They have the shape of a Gate's `hooks`. A
+handler is pure and synchronous. It gives `Out` or `skip(reason)`, never `undefined`; a throw is a
+skip with the error as its reason.
+
+**Fields**
+
+- `github` (optional): `typeof github`
+- `gitlab` (optional): `typeof gitlab`
+- `slack` (optional): `typeof slack`
+- `discord` (optional): `typeof discord`

package/docs/reference/authoring-surface/type-sourcein.md

@@ -0,0 +1,25 @@
+---
+title: SourceIn
+description: "What a Source's handler reads beside `payload`."
+---
+
+# `SourceIn`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type SourceIn<TInput = unknown> = {
+  readonly caller: CallerRecord;
+  readonly delivery: string;
+  readonly input: TInput;
+};
+```
+
+What a Source's handler reads beside `payload`. `caller` is the Hook as a Caller, `delivery` the
+delivery id, and `input` the Pool's input (`{}` for a standing Pool).
+
+**Fields**
+
+- `caller`: [`CallerRecord`](type-callerrecord.md)
+- `delivery`: `string`
+- `input`: `TInput`

package/docs/reference/authoring-surface/type-sourcereply.md

@@ -0,0 +1,18 @@
+---
+title: SourceReply
+description: "The text that the person who acted reads, from this Source's verdict (ADR-0011, ADR-0017)."
+---
+
+# `SourceReply`
+
+Type, 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
+type SourceReply<T> = (verdict: SourceVerdict<T>, at: { readonly caller: CallerRecord }) => string | undefined;
+```
+
+The text that the person who acted reads, from this Source's verdict ([ADR-0011](../decisions/0011-workflow-defined-events.md), [ADR-0017](../decisions/0017-pool-over-a-source-port.md)).
+Plain text: the Hook kind escapes it and puts it in its envelope. Pure and synchronous.
+`undefined` or `""`: this Source says nothing. It runs only for a delivery whose answer a person
+reads (`slack`, `discord`). The text of a `skipped` verdict shows only when no other target gave
+a text.