@jr2/orchestrator 0.3.0 → 0.5.1

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

@@ -0,0 +1,60 @@
+---
+title: PoolSpec
+description: "What you pass to `pool()`: where the items come from, how many workers run at once, and what each worker gets."
+---
+
+# `PoolSpec`
+
+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 PoolSpec<T, TInput = unknown> = {
+  id?: string;
+  input?: z.ZodObject;
+  source: SourceSpec<T>;
+  itemId: (item: T) => string;
+  cap?: number | ((args: { input: TInput }) => number);
+  itemInput?: (item: T, args: { input: TInput }) => unknown;
+  onDrained?: "final";
+  failures?: "fail" | "report";
+};
+```
+
+What you pass to `pool()`: where the items come from, how many workers run at once, and what
+each worker gets.
+
+**Fields**
+
+- `id` (optional): `string`
+
+  The Machine id: the name of the Pool in the Console. Default: `"pool"`.
+- `input` (optional): `z.ZodObject`
+
+  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>`
+
+  Where the items come from. Make it with [`source`](source.md).
+- `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
+  that `next` gets. It is also the key of that worker's output in `items`. Give each item an id
+  of its own, and the same id every time.
+- `cap` (optional): `number | ((args: { input: TInput; }) => number)`
+
+  The most workers that run at once: a number, or a function of the run input. Default: `1`.
+- `itemInput` (optional): `(item: T, args: { input: TInput; }) => unknown`
+
+  Make a worker's input from its item and the run input. Default: the item itself.
+- `onDrained` (optional): `"final"`
+
+  What the Pool does when the Source has no more items and every worker has settled. Only
+  `"final"`: the run ends. Default: `"final"`.
+- `failures` (optional): `"fail" | "report"`
+
+  What the Pool does at the end when one or more workers failed. The Pool catches each worker's
+  Failure either way, so one failed item does not stop the other workers. `"fail"`: when the Pool
+  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"`.

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

@@ -0,0 +1,15 @@
+---
+title: PushInput
+description: "The input of a `push` Effect: `{ sha }` with `pin`, and `{ message }` with `squash`."
+---
+
+# `PushInput`
+
+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) &
+  (O["squash"] extends true ? { message: string } : unknown);
+```
+
+The input of a `push` Effect: `{ sha }` with `pin`, and `{ message }` with `squash`.

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

@@ -0,0 +1,79 @@
+---
+title: PushOptions
+description: The options of `push()`.
+---
+
+# `PushOptions`
+
+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 PushOptions = {
+  pin?: boolean;
+  sign?: boolean;
+  squash?: boolean;
+  force?: boolean;
+  slot?: string;
+  timeout?: Duration;
+};
+```
+
+The options of `push()`.
+
+**Fields**
+
+- `pin` (optional): `boolean`
+
+  `true`: the input of the Effect names the commit to push (`{ sha }`, a full commit id, for
+  example one that a Gate approved). Default: the tip of the Agent's branch when the Effect
+  starts. When the Agent removed that commit from its branch, the remote refuses the push. jr2
+  never pushes another commit in its place.
+
+  When it starts, it refuses a `sha` that is not a full commit id: `push({ pin: true }): its
+  input's sha is not a full commit id (got <sha>)`.
+- `sign` (optional): `boolean`
+
+  `true`: push signed copies of the commits. The `sign` field of the `git.credentials` entry that
+  the Binding matches names the key. Default `false`.
+
+  At `jr2 up`, it refuses an entry with no `sign` field: `<push> signed, and git.credentials
+  entry "<match>" holds no sign field — add sign: { sshKey: "<a Secret with identity>", name:
+  "<committer name>", email: "<committer email>" } to it; the email must belong to the forge
+  account that holds the key (ADR-0051, ADR-0067)`. `<push>` names the push: `workflow
+  "<workflow>": push "<slot>" pushes Repo Slot "<name>" (<url>)`.
+- `squash` (optional): `boolean`
+
+  `true`: push one commit that holds all the changes. The input of the Effect gives its message
+  (`{ message }`). Signed, its committer is the signer. Unsigned, it is the `committer` of the
+  `git.credentials` entry that the Binding matches. Default `false`.
+
+  When it starts, it refuses an input with no message: `push({ squash: true }): its input
+  carries no message`.
+
+  At `jr2 up`, it refuses an unsigned squash whose entry has no `sign` and no `committer`:
+  `<push> squashed without sign, and git.credentials entry "<match>" holds neither sign nor
+  committer — the squashed commit is new and needs a committer; add committer: { name:
+  "<committer name>", email: "<committer email>" } to it, or sign the push — push({ squash:
+  true, sign: true }) — and add sign: { sshKey: "<a Secret with identity>", name: "<committer
+  name>", email: "<committer email>" } to it (ADR-0051, ADR-0067)`.
+- `force` (optional): `boolean`
+
+  `true`: replace what the remote branch holds. Default `false`.
+- `slot` (optional): `string`
+
+  The Repo Slot to push. Write it only when the Workspace has more than one.
+
+  When it starts, it refuses:
+  - no `slot` under a Workspace with more than one Repo Slot: `push "<slot>" runs under a
+    Workspace carrying more than one Repo Slot (<slots>) — say which: { slot: "<slot>" }
+    (ADR-0051)`
+  - a `slot` that the Workspace does not have: `push "<slot>" names Repo Slot "<name>", which
+    its Workspace does not carry (<slots>)`
+  - a Workspace with no Repo Slot: `push "<slot>" runs under a Workspace with no Repo Slot: a
+    push publishes a Repo Slot's branch, and there is none — declare one: repos: { app: "<url>" }
+    (ADR-0051)`. `jr2 up` refuses it first, with the same reason.
+- `timeout` (optional): [`Duration`](type-duration.md)
+
+  How long jr2 waits for the push: a number and a unit, such as `"90s"` or `"5m"`. Default
+  `"5m"`. With no answer in that time, the output is `unknown`. It refuses a value that is not a
+  positive duration: `timeout "<timeout>" is not a positive duration (like "30s", "5m")`.

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

@@ -0,0 +1,124 @@
+---
+title: PushOutput
+description: "The output of a `push` Effect: what the `onDone` of its state gets as `event.output`."
+---
+
+# `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.
+
+```ts
+type PushOutput =
+  | Exclude<PushWireOutput, { outcome: "pushed" }>
+  | (Omit<Extract<PushWireOutput, { outcome: "pushed" }>, "bundle"> & { sync: SyncState; syncReason?: string });
+```
+
+The output of a `push` Effect: what the `onDone` of its state gets as `event.output`. Every
+outcome is output, so route on `outcome`:
+
+- `pushed`: the remote has the commit. `published` is the commit on the remote, and `source` is
+  the Agent's commit that it comes from. They are the same commit, unless the push was signed or
+  squashed. `previous` is what the remote had before, and `unchanged` is `true` when the remote
+  had the commit already. `squashed` is `signed` or `unsigned` when the commit on the remote is
+  one squashed commit. `via` tells how jr2 found the new commits after a signed push:
+  `ancestry`, `pair`, `cherry` or `force`.
+- `rejected`: git or the remote refused the push. `stage` tells where, `reason` tells why, and
+  `detail` has the words of git.
+- `diverged`: the commit on the remote is not in the history of the Agent's branch, and jr2
+  could not pair it with a commit there. Nothing was pushed. `reason` tells why, and `published`
+  and `source` name the two commits.
+- `unknown`: jr2 cannot tell what the push did. `reason` tells why.
+
+Beside `pushed`, `sync` tells what jr2 did to the Agent's branch after the push:
+
+- `synced`: the commit on the remote is not the Agent's own, and jr2 moved the branch to the
+  published commits.
+- `already`: the branch has the published commit already.
+- `skipped`: the remote has the Agent's own commit, so the branch does not move.
+- `busy`: a rebase, merge, cherry-pick or revert of the branch is in progress. Nothing changed.
+- `not-synced`: the branch did not move.
+
+With `busy` or `not-synced`, `syncReason` tells why, and jr2 tries again before the next push.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `stage`, `reason`, `detail`
+
+  - `outcome`: `"rejected"`
+  - `stage`: `string`
+  - `reason`: `string`
+  - `detail` (optional): `string`
+- Form 2: `outcome`, `reason`, `published`, `source`
+
+  - `outcome`: `"diverged"`
+  - `reason`: `string`
+  - `published`: `string`
+  - `source`: `string`
+- Form 3: `outcome`, `reason`
+
+  - `outcome`: `"unknown"`
+  - `reason`: `string`
+- Form 4: `outcome`, `published`, `source`, `previous`, `via`, `unchanged`, `newCommits`, `squashed`, `sync`, `syncReason`
+
+  - `outcome`: `"pushed"`
+  - `published`: `string`
+  - `source`: `string`
+  - `previous` (optional): `string`
+  - `via` (optional): `string`
+  - `unchanged` (optional): `boolean`
+  - `newCommits` (optional): `number`
+  - `squashed` (optional): `"signed" | "unsigned"`
+  - `sync`: [`SyncState`](type-syncstate.md)
+  - `syncReason` (optional): `string`
+
+**Example**
+
+```ts
+import { fail, jr2Setup, push, type PushOutput, workspace, type Workspaced } from "@jr2/orchestrator";
+
+type Input = Workspaced<{ sha: string }, "app">;
+
+// A push that did not happen (`rejected` or `diverged`) is a different problem from one jr2
+// cannot see (`unknown`).
+const notPushed = (output: PushOutput): boolean =>
+  output.outcome === "rejected" || output.outcome === "diverged";
+
+const body = jr2Setup({
+  types: {} as { context: Input; input: Input },
+  actors: { publish: push({ pin: true }), fail: fail() },
+}).createMachine({
+  id: "release",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost" },
+  initial: "publishing",
+  states: {
+    publishing: {
+      invoke: {
+        src: "publish",
+        input: ({ context }) => ({ sha: context.sha }),
+        onDone: [
+          { guard: ({ event }) => event.output.outcome === "pushed", target: "published" },
+          { guard: ({ event }) => notPushed(event.output), target: "notPushed" },
+          { target: "unknown" },
+        ],
+      },
+    },
+    published: { type: "final" },
+    // 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" } } },
+    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" }),
+});
+```
+
+**See also**
+
+- [Push and sign a branch](../../guides/push-and-sign-a-branch.md)
+- [Effects](../../concepts/effects.md)
+- [ADR-0067: An Effect is an actor slot, and runs at most once unless marked idempotent](../decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)

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

@@ -0,0 +1,12 @@
+---
+title: PushWireOutput
+description: A type that the Authoring surface names.
+---
+
+# `PushWireOutput`
+
+Type, in `@jr2/orchestrator/src/effector-wire.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type PushWireOutput = z.infer<typeof PushOutputShape>;
+```

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

@@ -0,0 +1,14 @@
+---
+title: Quantity
+description: "A Kubernetes quantity: `\"2Gi\"`, `\"1500m\"`, `\"2\"`, or a plain number (`2` cpus, bytes of memory)."
+---
+
+# `Quantity`
+
+Type, in `@jr2/orchestrator/src/size.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 Quantity = string | number;
+```
+
+A Kubernetes quantity: `"2Gi"`, `"1500m"`, `"2"`, or a plain number (`2` cpus, bytes of memory).

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

@@ -0,0 +1,12 @@
+---
+title: Reached
+description: A type that the Authoring surface names.
+---
+
+# `Reached`
+
+Type, in `@jr2/orchestrator/src/customize.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type Reached<M extends AnyStateMachine> = M extends JR2Wrapper<infer TBody> ? Reached<TBody> : M;
+```

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

@@ -0,0 +1,70 @@
+---
+title: RepoSlot
+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.
+
+```ts
+type RepoSlot<TInput = unknown> =
+  | typeof open
+  | string
+  | Binding
+  | ((args: { input: TInput }) => string | Binding);
+```
+
+The value of one Repo Slot in `workspace({ repos })`. One of:
+- a url, or a [`Binding`](type-binding.md) `{ url, ref }`: the Machine names the Repo.
+- [`open`](open.md): the Instance that registers the Machine binds it with `customize()`. `jr2 up`
+  refuses a Workflow that leaves it open: ``refusing: workflow "<name>" leaves Repo Slot
+  "<slot>" open — bind it where the Machine is registered: export const machine =
+  customize(<import>, …)  (ADR-0051)``, with the whole `customize` line to paste.
+- a function of the run input, `({ input }) => url` or a [`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
+shape: ``<where>: Repo Slot "<slot>" is <what> — a slot is `open`, a url, `{ url, ref? }`, or a
+mapper `({ input }) => url | { url, ref? }` over the door (ADR-0051).``
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { jr2Setup, open, workspace, type RepoSlot, type Workspaced } from "@jr2/orchestrator";
+
+const runInput = z.object({ service: z.string() });
+type RunInput = z.infer<typeof runInput>;
+
+const service: RepoSlot<RunInput> = ({ input }) => `https://github.com/you/${input.service}.git`;
+
+const body = jr2Setup({
+  types: {} as { input: Workspaced<RunInput, "service" | "docs" | "config"> },
+}).createMachine({
+  id: "body",
+  initial: "done",
+  states: { done: { type: "final" } },
+});
+
+// A Machine for a package: the Instance that registers it binds `config`.
+export const deploy = workspace(body, {
+  input: runInput,
+  repos: {
+    service,
+    docs: "https://github.com/you/docs.git",
+    config: open,
+  },
+  spec: ({ input }) => ({ branch: `deploy/${input.service}` }),
+});
+```
+
+**See also**
+
+- [Workspaces](../../concepts/workspaces.md)
+- [Bind a shipped Machine's Open parts](../../guides/bind-open-parts.md)
+- [Give the cluster git credentials](../../guides/give-the-cluster-git-credentials.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)

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

@@ -0,0 +1,16 @@
+---
+title: RepoSlotsOf
+description: A type that the Authoring surface names.
+---
+
+# `RepoSlotsOf`
+
+Type, in `@jr2/orchestrator/src/customize.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type RepoSlotsOf<M extends AnyStateMachine> = [WorkspaceOf<M>] extends [never]
+  ? never
+  : WorkspaceOf<M> extends JR2Repos<infer TSlots>
+    ? TSlots
+    : never;
+```

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

@@ -0,0 +1,77 @@
+---
+title: SandboxOptions
+description: The options of a `workspace()` that say what its Sandbox is made of and which Repos it clones.
+---
+
+# `SandboxOptions`
+
+Type, in `@jr2/orchestrator/src/workspace.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 SandboxOptions<TSlots extends string, TInput = unknown> = {
+  image?: string;
+  user?: string | UserContainer;
+  resources?: Size;
+  repos: Record<TSlots, RepoSlot<TInput>> | typeof open;
+  secrets?: readonly string[];
+  effector?: { image: string };
+};
+```
+
+The options of a `workspace()` that say what its Sandbox is made of and which Repos it
+clones. They are the same for each run.
+
+**Fields**
+
+- `image` (optional): `string`
+
+  The Sandbox Image: the image of the container where the Agent's Working tools and
+  `command` Effects run. A `file:` URL to a docker context that your module ships
+  (`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.
+- `user` (optional): `string | UserContainer`
+
+  The User Container: a third container in the Sandbox, for a service that must run beside the
+  Agent, such as an sshd. Its image, in the same two forms as `image`, or `{ image, resources }`
+  to give it a part of the Size. It runs its own entrypoint, with `/work` mounted. jr2 adds
+  nothing to it. Default: none. Without `resources`, it has no limit of its own and shares the
+  Size of the Sandbox.
+- `resources` (optional): [`Size`](type-size.md)
+
+  The Size: the memory and cpu limit of the whole Sandbox, `{ limits: { memory, cpu } }`, such as
+  `{ limits: { memory: "4Gi", cpu: "2" } }`. jr2 reserves all of it on the node: each request
+  equals its limit. jr2 also enforces the cpu limit. Only `limits`,
+  and in it only `memory` and `cpu`, are accepted. Default: the Instance's `sandbox.resources`,
+  then 2Gi and 1 cpu. Under a Size that you give, a field you leave out takes the kit's value,
+  not the Instance's. The Instance that registers the Machine can change it with
+  `customize(machine, { resources })`.
+- `repos`: `Record<TSlots, RepoSlot<TInput>> | typeof open`
+
+  The Repo Slots: the repositories that the Sandbox clones, each under a name of your Machine's
+  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);
+  - `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.
+
+  Or `repos: open` for the whole map: the Machine names no slot, and the Instance that registers
+  it names each one with `customize()`. The body's input is then `Workspaced<RunInput, string>`.
+- `secrets` (optional): `readonly string[]`
+
+  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.
+- `effector` (optional): `object`
+
+  The image of the Sandbox Effector. This container runs three kinds of Effect for this
+  Workspace: a `push`, an `http` Effect with a Worktree file as its body, and a `command` with an
+  Effect secret in its `env`. It gets the Effect secrets that those Effects name. Give an image
+  when those Effects need tools or credentials that you keep out of the Sandbox Image, such as
+  `terraform`. A `file:` URL or a registry ref, as for `image`. Default: the Sandbox Image,
+  which already holds `git`.
+
+  - `image`: `string`

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

@@ -0,0 +1,25 @@
+---
+title: Secret
+description: "What `secret(\"name\")` gives: an Effect secret, by its name in the `secrets` list of `jr2.config.ts`."
+---
+
+# `Secret`
+
+Type, in `@jr2/orchestrator/src/http-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 Secret = { readonly secret: string; readonly path: { readonly secret: string; readonly path: true } };
+```
+
+What `secret("name")` gives: an Effect secret, by its name in the `secrets` list of
+`jr2.config.ts`. Put it in an Effect's `auth`, a header, a `text` or a command's `env`. Its
+`.path` is the path of a file that holds the value. The value stays in the Effector, so the
+Machine and the Agent never see it.
+
+**Fields**
+
+- `secret`: `string`
+- `path`: `object`
+
+  - `secret`: `string`
+  - `path`: `true`

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

@@ -0,0 +1,19 @@
+---
+title: Sender
+description: "Who delivered an event: an Agent by its slot, or a Gate by its invoke id (ADR-0015)."
+---
+
+# `Sender`
+
+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 };
+```
+
+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)).
+
+**Fields**
+
+- `party`: `"agent" | "gate"`
+- `id`: `string`

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

@@ -0,0 +1,12 @@
+---
+title: SentByGuards
+description: A type that the Authoring surface names.
+---
+
+# `SentByGuards`
+
+Type, in `@jr2/orchestrator/src/setup.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type SentByGuards = { [SENT_BY]: { id: string } };
+```

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

@@ -0,0 +1,85 @@
+---
+title: Size
+description: "The Size of a Workspace: the most memory and cpu that its whole Sandbox can use."
+---
+
+# `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.
+
+```ts
+type Size = {
+  limits: {
+    memory?: Quantity;
+    cpu?: Quantity;
+  };
+};
+```
+
+The Size of a Workspace: the most memory and cpu that its whole Sandbox can use. jr2 reserves
+all of it on the node. Thus a Sandbox never gets less than its Size and never uses more.
+
+Write it as `{ limits: { memory, cpu } }`. You can write it in three places: the `resources`
+option of `workspace()`, `customize(machine, { resources })`, and `sandbox.resources` in
+`jr2.config.ts`. The Size is a fact of the Machine. The Instance's `sandbox.resources` applies
+only to a Workspace that states no Size. A field that neither states comes from the kit default:
+memory `2Gi`, cpu `1`.
+
+The same shape is the User Container's part of the Size, in `user: { image, resources }`. There,
+a field you leave out gives the User Container no limit of its own: it shares the pod's budget.
+
+It refuses any key but `limits.memory` and `limits.cpu`, where you write it. The message names
+the field: `<where>` is where you wrote the Size, for example `workspace(): resources`.
+
+- `<where>.requests is not accepted — jr2 reserves the whole Size, so every request equals its
+  limit — a Size is { limits: { memory?, cpu? } } and nothing else — Agent Substrate's template
+  size (ADR-0060)`
+- `<where>.<key> is not accepted — a Size is { limits: { memory?, cpu? } } and nothing else —
+  Agent Substrate's template size (ADR-0060)`
+- `<where>.limits.<key> is not accepted — a Size is { limits: { memory?, cpu? } } and nothing
+  else — Agent Substrate's template size (ADR-0060)`
+- `<where>.limits.memory: <value> is not a positive quantity (e.g. "2Gi", "512Mi")`, and for
+  cpu, `<where>.limits.cpu: <value> is not a positive quantity (e.g. "2", "1500m")`
+
+`jr2 up` also refuses a Size that leaves the Harness container less than its floor. The message
+starts with `the Size leaves the Harness container <memory> memory, below its 256Mi floor:` or
+with `the Size leaves the Harness container no cpu:`. The text that follows names each number
+and where it came from.
+
+**Fields**
+
+- `limits`: `object`
+
+  The two limits. Write `limits: {}` to state no field: each field then comes from the next
+  source.
+
+  - `memory` (optional): [`Quantity`](type-quantity.md)
+
+    The memory limit, as a Kubernetes quantity: `"4Gi"`, `"512Mi"`, or a number of bytes.
+    It must be more than zero. When you leave it out, it comes from the next source, as above.
+  - `cpu` (optional): [`Quantity`](type-quantity.md)
+
+    The cpu limit, as a Kubernetes quantity: `"2"`, `"1500m"`, or a number of cpus. It must be
+    more than zero. jr2 enforces it. When you leave it out, it comes from the next source, as
+    above.
+
+**Example**
+
+```ts
+import { customize, type Size } from "@jr2/orchestrator";
+import { task } from "@jr2/machines";
+
+const size: Size = { limits: { memory: "4Gi", cpu: "2" } };
+
+export const machine = customize(task, {
+  repos: { app: { url: "https://github.com/you/app.git" } },
+  agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+  resources: size,
+});
+```
+
+**See also**
+
+- [Size a Workspace](../../guides/size-a-workspace.md)
+- [Workspaces](../../concepts/workspaces.md)
+- [ADR-0060: A Workspace states its Size, and jr2 reserves all of it](../decisions/0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md)

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

@@ -0,0 +1,32 @@
+---
+title: SlotHandles
+description: The handles of a Workspace that declares Repo Slots.
+---
+
+# `SlotHandles`
+
+Type, in `@jr2/orchestrator/src/workspace.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 SlotHandles<TSlots extends string> = {
+  repos: Record<TSlots, string>;
+  branch: string;
+  review?: Partial<Record<TSlots, string>>;
+};
+```
+
+The handles of a Workspace that declares Repo Slots. @internal
+
+**Fields**
+
+- `repos`: `Record<TSlots, string>`
+
+  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`.