@jr2/orchestrator 0.4.1 → 0.5.1

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

@@ -0,0 +1,17 @@
+---
+title: SourceNextResult
+description: "What the `next` of a Source resolves to: an item, to claim it; `null`, when no item is ready now; or `{ item, open }`, where `open` is the number of items that exist but are not ready."
+---
+
+# `SourceNextResult`
+
+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 SourceNextResult<T> = T | null | { item: T | null; open: number };
+```
+
+What the `next` of a Source resolves to: an item, to claim it; `null`, when no item is ready
+now; or `{ item, open }`, where `open` is the number of items that exist but are not ready.
+When no worker runs and `next` gives no item, the Pool ends: `drained` when `open` is 0 or
+absent, `deadlocked` when `open` is more than 0.

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

@@ -0,0 +1,44 @@
+---
+title: SourceSpec
+description: "Where a Pool gets its work items: the Source."
+---
+
+# `SourceSpec`
+
+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 SourceSpec<T> = {
+  next:
+    | PromiseActorLogic<SourceNextResult<T>, { active: string[] }>
+    | PromiseActorLogic<{ item: T | null; open: number }, { active: string[] }>
+    | PromiseActorLogic<T | null, { active: string[] }>
+    | PromiseActorLogic<null, { active: string[] }>;
+  wake?: EventDef;
+  pollEvery?: number;
+};
+```
+
+Where a Pool gets its work items: the Source. Make one with [`source`](source.md).
+
+**Fields**
+
+- `next`: `PromiseActorLogic<SourceNextResult<T>, { active: string[]; }> | PromiseActorLogic<{ item: T | null; open: number; }, { active: string[]; }> | PromiseActorLogic<T | null, { active: string[]; }> | PromiseActorLogic<null, { active: string[]; }>`
+
+  Claim the next ready item. Write it as an xstate promise actor,
+  `fromPromise(async ({ input }) => …)`. Its input is `{ active }`: the ids of the items that
+  workers have now, which it must not give again. It must also not give again an item that a
+  worker finished. It resolves to a [`SourceNextResult`](type-sourcenextresult.md). The Pool calls it when the run
+  starts, after each claim, and when a worker settles. While workers run and no item is ready, it
+  also calls it on `wake` and every `pollEvery`.
+- `wake` (optional): [`EventDef`](type-eventdef.md)
+
+  An external event, made with `defineEvent`, that tells the Pool that new work is ready, for
+  example from a webhook or `jr2 send`. While workers run and no item is ready, it makes the Pool
+  call `next` at once. The Pool serves it as a Gate named `source` for the whole run
+  (`<path>.source` when the Pool is composed in another Machine). Default: none.
+- `pollEvery` (optional): `number`
+
+  While workers run and no item is ready, call `next` again after this many milliseconds. Use
+  it for a Source whose items change while the run waits. Default: none, so the Pool calls
+  `next` again only when a worker settles or `wake` comes.

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

@@ -0,0 +1,12 @@
+---
+title: SyncState
+description: A type that the Authoring surface names.
+---
+
+# `SyncState`
+
+Type, in `@jr2/orchestrator/src/sandbox-effect.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 SyncState = SyncAnswer["sync"];
+```

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

@@ -0,0 +1,19 @@
+---
+title: Text
+description: "What the `text` template gives: a string of literal text and Effect secrets, in order."
+---
+
+# `Text`
+
+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 Text = { readonly text: readonly TextPart[] };
+```
+
+What the `text` template gives: a string of literal text and Effect secrets, in order. The
+Effector builds the string, so the Machine never sees the value of a secret.
+
+**Fields**
+
+- `text`: `readonly TextPart[]`

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

@@ -0,0 +1,24 @@
+---
+title: TextPart
+description: "One part of a `Text`: `{ text }`, literal text, or `{ secret }`, the name of an Effect secret."
+---
+
+# `TextPart`
+
+Type, in `@jr2/orchestrator/src/effector-wire.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 TextPart = z.infer<typeof TextPartShape>;
+```
+
+One part of a [`Text`](type-text.md): `{ text }`, literal text, or `{ secret }`, the name of an Effect
+secret. The `text` template makes the parts.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `text`
+
+  - `text`: `string`
+- Form 2: `secret`
+
+  - `secret`: `string`

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

@@ -0,0 +1,39 @@
+---
+title: ThinkingLevel
+description: "How hard the model thinks before it answers: `\"off\"`, `\"minimal\"`, `\"low\"`, `\"medium\"`, `\"high\"` or `\"xhigh\"`."
+---
+
+# `ThinkingLevel`
+
+Type, in `@jr2/orchestrator/src/agent.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Agents.
+
+```ts
+type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+```
+
+How hard the model thinks before it answers: `"off"`, `"minimal"`, `"low"`, `"medium"`,
+`"high"` or `"xhigh"`. Set it on an Agent's definition (`thinkingLevel`), or for one Turn in the
+invoke's `input`.
+
+A model can lack a level. Claude Sonnet 5.5 has no `"off"`, and at `"off"` the Harness's request
+then sends effort `"high"`. The Harness does not refuse such a level: it runs the Turn, and the
+printed conversation names the level that the model ran at.
+
+**Example**
+
+```ts
+import { agent, type ThinkingLevel } from "@jr2/orchestrator";
+
+const effort: ThinkingLevel = "high";
+
+export const reviewer = agent({
+  model: "anthropic/claude-haiku-5-5",
+  instructions: "You review diffs for correctness.",
+  thinkingLevel: effort,
+});
+```
+
+**See also**
+
+- [Set an Agent's access and Dials](../../guides/set-an-agents-access-and-dials.md)
+- [ADR-0018: The instance authors Agent definitions; jr2 assembles the Harness](../decisions/0018-instance-agents-are-definitions-jr2-assembles-the-harness.md)

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

@@ -0,0 +1,14 @@
+---
+title: ToParameterizedObject
+description: A type that the Authoring surface names.
+---
+
+# `ToParameterizedObject`
+
+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 ToParameterizedObject<T extends Record<string, ParameterizedObject["params"] | undefined>> = {
+  [K in keyof T & string]: { type: K; params: T[K] };
+}[keyof T & string];
+```

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

@@ -0,0 +1,14 @@
+---
+title: ToProvidedActor
+description: A type that the Authoring surface names.
+---
+
+# `ToProvidedActor`
+
+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 ToProvidedActor<TActors extends Record<string, UnknownActorLogic>> = {
+  [K in keyof TActors & string]: { src: K; logic: TActors[K]; id: string | undefined };
+}[keyof TActors & string];
+```

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

@@ -0,0 +1,21 @@
+---
+title: Unknown
+description: "The output `{ outcome: \"unknown\", reason }`: the Effect may have acted, and jr2 cannot tell."
+---
+
+# `Unknown`
+
+Type, in `@jr2/orchestrator/src/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 Unknown = { outcome: "unknown"; reason: string };
+```
+
+The output `{ outcome: "unknown", reason }`: the Effect may have acted, and jr2 cannot tell.
+For example, the Harness lost the exec, or its state exited while it ran. Route on it. jr2 does
+not run the Effect again.
+
+**Fields**
+
+- `outcome`: `"unknown"`
+- `reason`: `string`

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

@@ -0,0 +1,77 @@
+---
+title: UserContainer
+description: "The User Container in its object form: its image, and its part of the Workspace's Size."
+---
+
+# `UserContainer`
+
+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 UserContainer = {
+  image: string;
+  resources?: Size;
+};
+```
+
+The User Container in its object form: its image, and its part of the Workspace's Size. The User
+Container is an optional container of your own in the Sandbox pod. It runs its own entrypoint
+with `/work` mounted, and jr2 never builds into it, probes it or sends it commands. Use it for a
+service that must run without an Agent, such as an sshd.
+
+Write it in the `user` option of `workspace()` or of `customize()`. That option also takes the
+image as a string; use this object form only to give the User Container a part of the Size. A
+`customize()` that names `user` replaces the whole User Container, its part of the Size
+included.
+
+It refuses, where you write it. `<where>` is `workspace()` or `customize()`:
+
+- an image that is not a non-empty string. The message starts with
+  `` <where>: `user` must be a non-empty string (an image), or { image, resources? } ``.
+- `<where>: user.<key> is not accepted — the User Container is { image, resources? } (ADR-0005,
+  ADR-0060)`
+
+`resources` is checked as a [`Size`](type-size.md), with the same refusals.
+
+`jr2 up` refuses a part 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**
+
+- `image`: `string`
+
+  The image: a `file:` URL to a docker context that your module ships
+  (`import.meta.resolve("./sshd")`), which `jr2 up` builds, or a registry ref. It must not be
+  empty.
+- `resources` (optional): [`Size`](type-size.md)
+
+  This container's part of the Workspace's Size, as a Size. jr2 takes it from the Harness
+  container's part. A field you leave out gives this container no limit of its own for it: it
+  shares the pod's budget. Default: no part.
+
+**Example**
+
+```ts
+import { customize, type UserContainer } from "@jr2/orchestrator";
+import { task } from "@jr2/machines";
+
+const sshd: UserContainer = {
+  image: "registry.example.com/sshd:1.0",
+  resources: { limits: { memory: "256Mi", cpu: "250m" } },
+};
+
+export const machine = customize(task, {
+  repos: { app: { url: "https://github.com/you/app.git" } },
+  agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+  user: sshd,
+});
+```
+
+**See also**
+
+- [Workspaces](../../concepts/workspaces.md)
+- [Size a Workspace](../../guides/size-a-workspace.md)
+- [ADR-0005: The Sandbox pod's containers: Harness, Custodian, an optional User Container, and an optional Sandbox Effector](../decisions/0005-sandbox-pod-composition.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-withoutemptyindex.md

@@ -0,0 +1,20 @@
+---
+title: WithoutEmptyIndex
+description: The fields of the run input `T`.
+---
+
+# `WithoutEmptyIndex`
+
+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 WithoutEmptyIndex<T> = string extends keyof T
+  ? [T[string & keyof T]] extends [never]
+    ? { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K] }
+    : T
+  : T;
+```
+
+The fields of the run input `T`. A string index signature whose value is `never` is not one of
+them: `z.infer` gives `Record<string, never>` for `z.object({})`, and this type makes it `{}`. The
+named fields of `T` stay. A different `T` does not change.

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

@@ -0,0 +1,46 @@
+---
+title: WorkflowEvent
+description: "The type of `event` in a Machine that `jr2Setup` makes: each workflow event in its `events`, and each Mechanism event."
+---
+
+# `WorkflowEvent`
+
+Type, in `@jr2/orchestrator/src/setup.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 WorkflowEvent<TDefs extends readonly EventDef[]> =
+  | (EventFrom<TDefs[number]> & { readonly sender?: Sender })
+  | MechanismEvent;
+```
+
+The type of `event` in a Machine that `jr2Setup` makes: each workflow event in its `events`,
+and each Mechanism event. A workflow event that an Agent or a Gate sent has `event.sender`. An
+event that the Machine sent to itself (`raise`, `sendTo`) has no `sender`.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `type`, `sender`
+
+  - `type`: `N`
+  - `sender` (optional): [`Sender`](type-sender.md)
+- Form 2: `type`, `instanceId`, `reason`
+
+  - `type`: `"agent.fault"`
+  - `instanceId`: `string`
+
+    The Instance ID of the Agent's conversation that failed: the same id on each Turn that
+    continues it.
+  - `reason`: `string`
+
+    Why the Turn failed, as text for a person or a log: the Harness's error, or that the Agent
+    ended its Turns without a pick after every nudge. Route on the event, not on this text.
+- Form 3: `type`, `reason`, `message`
+
+  - `type`: `"workspace.lost"`
+  - `reason` (optional): `string`
+
+    Why the Sandbox is gone, for a person or a log: the pod's reason (`Evicted`, `NodeShutdown`),
+    the operator's (`PodDeleted`, `NodeLost`), or `Deleted`. A body can act without it.
+  - `message` (optional): `string`
+
+    More text about the loss, when jr2 has it.

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

@@ -0,0 +1,16 @@
+---
+title: WorkspaceAccess
+description: "What an Agent may do to the Workspace: `\"write\"`, `\"read\"` or `\"none\"`."
+---
+
+# `WorkspaceAccess`
+
+Type, in `@jr2/orchestrator/src/agent.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 WorkspaceAccess = "write" | "read" | "none";
+```
+
+What an Agent may do to the Workspace: `"write"`, `"read"` or `"none"`. With `"none"`, its Turn
+runs on the Instance Harness, not in a Sandbox. The `workspace` field of [`AgentDefinition`](type-agentdefinition.md)
+tells what each value gives.

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

@@ -0,0 +1,94 @@
+---
+title: Workspaced
+description: "The input of a `workspace()` body: the run input, plus `workspace`, the handles that the Workspace adds (`workspace.repos`, `workspace.branch`, `workspace.review`)."
+---
+
+# `Workspaced`
+
+Type, in `@jr2/orchestrator/src/workspace.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Workspaces and Repos.
+
+```ts
+type Workspaced<TInput, TSlots extends string> = WithoutEmptyIndex<TInput> & {
+  workspace: WorkspaceHandles<TSlots>;
+};
+```
+
+The input of a `workspace()` body: the run input, plus `workspace`, the handles that the
+Workspace adds (`workspace.repos`, `workspace.branch`, `workspace.review`). Use it as the type of
+the body's input.
+
+The first argument is the run input: the `input` schema of the `workspace()`. The second is the
+Repo Slots that the body reads, by name (`"app"` or `"app" | "docs"`). Under `repos: open`, write
+`string`: the body cannot know the names, so it reads the slots in order. For a `workspace()`
+with no `repos`, write `never`. The second argument has no default.
+
+A body under a root `workspace()` also gets the fields of `HostInjectedInput`. Add them when the
+body reads them: `Workspaced<HostInjectedInput & RunInput, "app">`.
+
+Its fields are the fields of the run input, and `workspace`. The run input can have no fields:
+`Workspaced<z.infer<typeof door>, "app">` for the door `z.object({})` holds only `workspace`.
+
+**Fields**: each field of [`WithoutEmptyIndex`](type-withoutemptyindex.md), and these:
+
+- `workspace`: `WorkspaceHandles<TSlots>`
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { agent, defineEvent, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+
+const done = defineEvent({
+  name: "done",
+  description: "Call this when REVIEW.md is written.",
+  input: z.object({}),
+});
+const runInput = z.object({ branch: z.string(), sha: z.string() });
+type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+
+const body = jr2Setup({
+  types: {} as { input: BodyInput; context: BodyInput },
+  events: [done],
+  actors: {
+    reviewer: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You review one commit and write REVIEW.md.",
+      workspace: "read",
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "review",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  initial: "reviewing",
+  states: {
+    reviewing: {
+      invoke: {
+        src: "reviewer",
+        input: ({ context }) => ({
+          prompt: `Review commit ${context.sha} on ${context.workspace.branch}.`,
+          cwd: context.workspace.review?.app ?? context.workspace.repos.app,
+        }),
+      },
+      on: { done: "finished" },
+    },
+    finished: { type: "final" },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  repos: { app: "https://github.com/you/app.git" },
+  spec: ({ input }) => ({ branch: input.branch, reviewSha: input.sha }),
+});
+```
+
+**See also**
+
+- [Workspaces](../../concepts/workspaces.md)
+- [Write a Workflow](../../guides/write-a-workflow.md)
+- [ADR-0012: `workspace()` wraps a body Machine and owns only Sandbox lifecycle](../decisions/0012-workspace-wrapper-machine.md)
+- [ADR-0051: A Repo is a slot on the `workspace()` and a cache on the node](../decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md)

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

@@ -0,0 +1,23 @@
+---
+title: WorkspaceHandles
+description: "What the body of a `workspace()` gets as `input.workspace`: the path of each Worktree, and the branch."
+---
+
+# `WorkspaceHandles`
+
+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 WorkspaceHandles<TSlots extends string> = [TSlots] extends [never]
+  ? { repos: Record<never, string> }
+  : SlotHandles<TSlots>;
+```
+
+What the body of a `workspace()` gets as `input.workspace`: the path of each Worktree, and the
+branch. A path is correct in each Instance that registers the Machine.
+
+`TSlots` is the names of the Repo Slots that the body reads. `workspace()` refuses a body that
+names a slot that the Workspace does not have. Write `string` for a body that names no slot and
+reads the Worktrees in the order of `repos`, as under `repos: open`. Write `never` for a
+Workspace with no Repo Slot: its handles are `{ repos: {} }`, with no branch, and its Agents work
+in `/work`.

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

@@ -0,0 +1,29 @@
+---
+title: WorkspaceMachine
+description: A type that the Authoring surface names.
+---
+
+# `WorkspaceMachine`
+
+Type, in `@jr2/orchestrator/src/workspace.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 WorkspaceMachine<TInput, TOutput, TBody extends AnyStateMachine, TSlots extends string> = StateMachine<
+  any,
+  any,
+  any,
+  WrapperActors<"body", TBody, "place" | "provision" | "attach" | "registrar" | "lease" | "destroy" | "fail">,
+  any,
+  any,
+  any,
+  any,
+  any,
+  TInput,
+  TOutput,
+  any,
+  any,
+  any
+> &
+  JR2Wrapper<TBody> &
+  JR2Repos<TSlots>;
+```

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

@@ -0,0 +1,13 @@
+---
+title: WorkspaceOf
+description: A type that the Authoring surface names.
+---
+
+# `WorkspaceOf`
+
+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 WorkspaceOf<M extends AnyStateMachine> =
+  M extends JR2Repos<any> ? M : M extends JR2Wrapper<infer TBody> ? WorkspaceOf<TBody> : never;
+```

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

@@ -0,0 +1,39 @@
+---
+title: WorkspaceOptions
+description: The options of a `workspace()` that declares the input that starts a run.
+---
+
+# `WorkspaceOptions`
+
+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 WorkspaceOptions<TSchema extends z.ZodObject, TSlots extends string> = SandboxOptions<
+  TSlots,
+  z.infer<TSchema>
+> & {
+  input: TSchema;
+  spec: (args: { input: WithoutEmptyIndex<z.infer<TSchema>> & HostInjectedInput }) => WorkspaceSpec;
+};
+```
+
+The options of a `workspace()` that declares the input that starts a run.
+
+**Fields**: each field of [`SandboxOptions`](type-sandboxoptions.md), and these:
+
+- `input`: `TSchema`
+
+  The input that starts a run, as a `z.object`. jr2 checks each start against it. It also types
+  the `input` of `spec` and of a per-run Repo Slot, and the body must accept it plus the
+  `workspace` handles. Write it here, not on the body.
+- `spec`: `(args: { input: WithoutEmptyIndex<z.infer<TSchema>> & HostInjectedInput; }) => WorkspaceSpec`
+
+  A function from the run input to the Workspace's [`WorkspaceSpec`](type-workspacespec.md): the `branch` it works
+  on, and optionally `reviewSha` and `workGroup`. jr2 calls it when the run enters the
+  Workspace.
+
+  The input of `spec` also holds `instanceId`, the seed Instance ID of the run (see
+  [`HostInjectedInput`](type-hostinjectedinput.md)). Use it to give each run a branch of its own:
+  ``spec: ({ input }) => ({ branch: `fix/${input.instanceId}` })``. Only a root `workspace()` gets
+  it from jr2. A `workspace()` that a different Machine invokes gets only the input that its
+  parent gives it, so that parent must give `instanceId` when `spec` reads it.

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

@@ -0,0 +1,37 @@
+---
+title: WorkspaceSpec
+description: "What the `spec` of a `workspace()` returns: the branch that the Workspace works on, and two optional fields."
+---
+
+# `WorkspaceSpec`
+
+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 WorkspaceSpec = {
+  branch: string;
+  workGroup?: number;
+  reviewSha?: string;
+};
+```
+
+What the `spec` of a `workspace()` returns: the branch that the Workspace works on, and two
+optional fields. jr2 calls `spec` with the run input when the run enters the Workspace.
+
+**Fields**
+
+- `branch`: `string`
+
+  The branch that the Workspace works on: each Repo Slot gets a Worktree for it, at
+  `/work/<slot>/<branch>`, with each `/` in the branch written as `-`. Required, and not
+  `default`, which is the directory of the clone. Your Machine decides its name.
+- `workGroup` (optional): `number`
+
+  The group id that owns the files in `/work`. With it, the Sandbox Image and the User
+  Container can both write those files when they run as different users. Default: 2000. Set it
+  to a group id that the User Container's sessions already have, for example when a root sshd
+  builds their groups from `/etc/group`. A non-negative integer.
+- `reviewSha` (optional): `string`
+
+  A commit to check out in a second, detached Worktree beside each branch Worktree, for a
+  reviewer: `/work/<slot>/<branch>-review`. The body gets its paths as `workspace.review`.