@jr2/orchestrator 0.3.0 → 0.5.1

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

@@ -0,0 +1,126 @@
+---
+title: JR2Config
+description: "The shape of `jr2.config.ts`: the deployment facts of an Instance, which a Machine cannot carry."
+---
+
+# `JR2Config`
+
+Type, in `@jr2/orchestrator/src/config.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Config.
+
+```ts
+type JR2Config = {
+  name?: string;
+  secrets?: readonly SecretEntry[];
+  git?: GitConfig;
+  harness?: HarnessConfig;
+  sandbox?: SandboxConfig;
+  priorityClasses?: PriorityClasses;
+  registry?: string;
+  kitRegistry?: string;
+  platforms?: readonly string[];
+  operator?: {
+    manage?: boolean;
+  };
+};
+```
+
+The shape of `jr2.config.ts`: the deployment facts of an Instance, which a Machine cannot carry.
+It holds the Instance's name, its secrets, how the cluster authenticates to Repos, what the
+Harness can reach, where Sandboxes run, and where images go. It names no Repo, no model and no
+Sandbox Image: a Machine names those itself.
+
+Every field is optional, and an Instance can run with no `jr2.config.ts`. Write the file as
+`export default defineConfig({ … })`. When the config loads, a file with no default export is
+refused: `` <file> has no default export (use `export default defineConfig({…})`) ``. The load also
+checks the shape of `git.credentials`, `secrets`, `harness.catalog` and `priorityClasses`. It
+checks that `sandbox` is an object, and checks its `resources`. Each refusal names the field.
+`jr2 up` checks the rest.
+
+**Fields**
+
+- `name` (optional): `string`
+
+  The Instance's name. Its Kubernetes namespace is this name (`-n` overrides it), and
+  `jr2 up` labels every object that it owns with it. Default: the name of the Instance folder.
+- `secrets` (optional): `readonly SecretEntry[]`
+
+  Every secret of the Instance, in one list. A secret goes where something names it. A Held
+  secret goes where a `workspace()` lists it under `secrets` or an Agent's provider reads it. An
+  Effect secret goes where an Effect names it with `secret("name")`. Its `hosts` is a Held
+  secret's binding, never its placement: an entry that nothing names goes nowhere. A model API
+  key goes here, never in `harness.env`. See [`SecretEntry`](../config.md#secrets). Each entry is checked when the
+  config loads: `<file> at secrets[<i>]<path>: <problem>`, followed by the shape of an entry.
+- `git` (optional): [`GitConfig`](../config.md#git)
+
+  How the cluster authenticates to Repos, and the fence that a per-run url must pass. It is not
+  a list of Repos: a Machine names its Repos in the Repo Slots of its `workspace()`. See
+  [`GitConfig`](../config.md#git).
+- `harness` (optional): [`HarnessConfig`](../config.md#harness)
+
+  What the Harness can reach: a custom model provider, gateways for catalog providers, env
+  vars, and CAs. See [`HarnessConfig`](../config.md#harness).
+- `sandbox` (optional): [`SandboxConfig`](../config.md#sandbox)
+
+  Which nodes are Sandbox nodes, and the Size of a Workspace that states none. Default: a
+  Sandbox runs wherever an ordinary pod runs, at the kit's Size. See [`SandboxConfig`](../config.md#sandbox).
+- `priorityClasses` (optional): [`PriorityClasses`](../config.md#priorityclasses)
+
+  Existing PriorityClasses to use in place of the two that `jr2 up` creates. See
+  [`PriorityClasses`](../config.md#priorityclasses).
+- `registry` (optional): `string`
+
+  The image registry prefix to which `jr2 up` pushes the images that it builds, such as
+  `registry.example.com/team`. It changes between deployments, so read it from `process.env`
+  (`.env`). Default: none; `jr2 up` loads the images into the kind cluster. On a cluster that is
+  not kind, `jr2 up` then refuses:
+  `` context <context> is not a kind cluster and no `registry` is configured ``.
+- `kitRegistry` (optional): `string`
+
+  The registry from which this cluster pulls the published Kit images: a mirror for a cluster
+  that is self-hosted, air-gapped, or mirror-only. Default: none; the cluster pulls from the
+  canonical home, `ghcr.io/snapwich/jr2-harness:<version>` and the others. Set, the cluster pulls
+  the same tags from `<kitRegistry>/jr2-harness:<version>`. Fill the mirror with
+  `jr2 kit push <registry>`; `jr2 up` never pushes to it. Read it from `process.env` (`.env`).
+- `platforms` (optional): `readonly string[]`
+
+  The platforms for which `jr2 up` builds its images, as docker platform strings, such as
+  `["linux/arm64"]`. Default: the platforms of the cluster's schedulable nodes that the kit
+  releases images for. `jr2 up` reports a node platform that it skips.
+
+  Set it when the nodes cannot tell. One case is a node group that scales up from zero. Another
+  is a set of nodes that need no image, such as an amd64 GPU group beside arm64 nodes. When you
+  set it, it replaces the default. It adds to nothing and removes from nothing. The kit releases
+  images for `linux/amd64` and `linux/arm64` only, so `jr2 up` refuses any other:
+  `` `platforms` names <platforms> — the kit releases images for linux/amd64, linux/arm64 and nothing else ``.
+- `operator` (optional): `object`
+
+  Settings of the operator layer, for kit development.
+
+  - `manage` (optional): `boolean`
+
+    `false`: `jr2 up` does not converge the operator, and you run its controller yourself.
+    Default: `true`.
+
+**Example**
+
+```ts
+import { defineConfig, type JR2Config } from "@jr2/orchestrator";
+
+const harness: JR2Config["harness"] = {
+  provider: {
+    id: "vllm",
+    api: "openai-completions",
+    baseUrl: process.env.VLLM_URL ?? "",
+    models: { "Qwen/Qwen3.6-35B-A3B": { contextWindow: 131072, maxTokens: 16384 } },
+  },
+};
+
+export default defineConfig({ name: "my-instance", harness });
+```
+
+**See also**
+
+- [jr2.config.ts](../config.md)
+- [Connect a model](../../get-started/connect-a-model.md)
+- [Secrets and trust](../../concepts/secrets-and-trust.md)
+- [ADR-0050: What code names, config declares; what the CLI names, discovery finds](../decisions/0050-what-code-names-config-declares-what-the-cli-names-discovery-finds.md)

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

@@ -0,0 +1,38 @@
+---
+title: Lends
+description: The parts of the Chart wrapper that a Chart can use, by their keys in `actors`, `guards`, `actions` and `delays`.
+---
+
+# `Lends`
+
+Type, in `@jr2/orchestrator/src/open-body.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 Lends = {
+  agents?: string[];
+  effects?: string[];
+  machines?: string[];
+  guards?: string[];
+  actions?: string[];
+  delays?: string[];
+  gate?: boolean;
+  fail?: boolean;
+};
+```
+
+The parts of the Chart wrapper that a Chart can use, by their keys in `actors`, `guards`,
+`actions` and `delays`. `gate: true` lends the Gate, so that a Chart can wait for an answer from
+outside the run. `fail: true` lends the Part that fails the run, so that a Chart can end its run
+as a Failure ([ADR-0073](../decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)): the Machine decides which ends a Chart can choose. A Chart can use no
+other part.
+
+**Fields**
+
+- `agents` (optional): `string[]`
+- `effects` (optional): `string[]`
+- `machines` (optional): `string[]`
+- `guards` (optional): `string[]`
+- `actions` (optional): `string[]`
+- `delays` (optional): `string[]`
+- `gate` (optional): `boolean`
+- `fail` (optional): `boolean`

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

@@ -0,0 +1,12 @@
+---
+title: LogicAt
+description: A type that the Authoring surface names.
+---
+
+# `LogicAt`
+
+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 LogicAt<M extends AnyStateMachine, K extends string> = Extract<SlotsOf<M>, { src: K }>["logic"];
+```

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

@@ -0,0 +1,12 @@
+---
+title: MarkedIf
+description: A type that the Authoring surface names.
+---
+
+# `MarkedIf`
+
+Type, in `@jr2/orchestrator/src/http-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 MarkedIf<V, T> = [Extract<V, OpenSecretMark>] extends [never] ? T : T & OpenSecretMark;
+```

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

@@ -0,0 +1,12 @@
+---
+title: MergedActors
+description: A type that the Authoring surface names.
+---
+
+# `MergedActors`
+
+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 MergedActors<TActors extends Record<string, UnknownActorLogic>> = Omit<JR2Actors, keyof TActors> & TActors;
+```

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

@@ -0,0 +1,25 @@
+---
+title: NamedSecret
+description: "A named secret, never `secret(open)`: where a definition's Open part is a whole that holds a secret — a dispatch's target (ADR-0071) — the secret is bound with it, to a name, so the mark `secret(open)` carries may not be present."
+---
+
+# `NamedSecret`
+
+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 NamedSecret = Secret & { readonly [K in keyof OpenSecretMark]?: never };
+```
+
+A named secret, never `secret(open)`: where a definition's Open part is a whole that holds a
+secret — a dispatch's target ([ADR-0071](../decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)) — the secret is bound with it, to a name, so the mark
+`secret(open)` carries may not be present. One type for the definition and the binding.
+
+**Fields**
+
+- `secret`: `string`
+- `path`: `object`
+
+  - `secret`: `string`
+  - `path`: `true`
+- `[openSecretMark]` (optional): `true`

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

@@ -0,0 +1,26 @@
+---
+title: NoSlotSpec
+description: "What the `spec` of a `workspace()` with no Repo Slot returns: only `workGroup`."
+---
+
+# `NoSlotSpec`
+
+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 NoSlotSpec = Pick<WorkspaceSpec, "workGroup"> & { branch?: never; reviewSha?: never };
+```
+
+What the `spec` of a `workspace()` with no Repo Slot returns: only `workGroup`. There is no
+branch and no review Worktree, because the Workspace has no Repo Slot.
+
+**Fields**
+
+- `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.
+- `branch` (optional): `never`
+- `reviewSha` (optional): `never`

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

@@ -0,0 +1,32 @@
+---
+title: NoSlotWorkspaceOptions
+description: The options of a `workspace()` with no Repo Slot that declares the input that starts a run.
+---
+
+# `NoSlotWorkspaceOptions`
+
+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 NoSlotWorkspaceOptions<TSchema extends z.ZodObject> = Omit<SandboxOptions<never>, "repos"> & {
+  repos?: never;
+  input: TSchema;
+  spec?: (args: { input: WithoutEmptyIndex<z.infer<TSchema>> & HostInjectedInput }) => NoSlotSpec;
+};
+```
+
+The options of a `workspace()` with no Repo Slot that declares the input that starts a run.
+`repos` is left out, and `spec` is optional.
+
+**Fields**: each field of [`SandboxOptions`](type-sandboxoptions.md), except `repos`, and these:
+
+- `repos` (optional): `never`
+
+  Not present: the Workspace has no Repo Slot. Its Agents work in `/work`.
+- `input`: `TSchema`
+
+  The input that starts a run, as a `z.object`, as in [`WorkspaceOptions`](type-workspaceoptions.md).
+- `spec` (optional): `(args: { input: WithoutEmptyIndex<z.infer<TSchema>> & HostInjectedInput; }) => NoSlotSpec`
+
+  A function from the run input to the Workspace's [`NoSlotSpec`](type-noslotspec.md): only `workGroup`.
+  Default: no `workGroup`.

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

@@ -0,0 +1,40 @@
+---
+title: OpenBodyDeclaration
+description: "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."
+---
+
+# `OpenBodyDeclaration`
+
+Type, in `@jr2/orchestrator/src/open-body.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Charts.
+
+```ts
+type OpenBodyDeclaration = {
+  lends: Lends;
+  allows: { models: string[]; workspace: WorkspaceAccess[] };
+  ceilings: Ceilings;
+};
+```
+
+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. Give it to [`openBody`](openbody.md), and to `chartSchemaFor` for the
+pick of a planner.
+
+**Fields**
+
+- `lends`: [`Lends`](type-lends.md)
+
+  The parts that a Chart can use.
+- `allows`: `object`
+
+  What the Agents that a Chart adds can have: a model from `models`, and a Workspace access
+  from `workspace`. With no model, a Chart cannot add an Agent.
+
+  - `models`: `string[]`
+  - `workspace`: `WorkspaceAccess[]`
+- `ceilings`: [`Ceilings`](type-ceilings.md)
+
+  The limits of one Chart.
+
+**See also**
+
+- [Charts](../../concepts/charts.md)

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

@@ -0,0 +1,14 @@
+---
+title: OpenBodyLogic
+description: "The logic `openBody()` returns: actor logic that carries the brand."
+---
+
+# `OpenBodyLogic`
+
+Type, in `@jr2/orchestrator/src/open-body.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 OpenBodyLogic = UnknownActorLogic & OpenBodySlot;
+```
+
+The logic `openBody()` returns: actor logic that carries the brand.

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

@@ -0,0 +1,42 @@
+---
+title: OpenBodyOutput
+description: The output of an Open body.
+---
+
+# `OpenBodyOutput`
+
+Type, in `@jr2/orchestrator/src/open-body.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Charts.
+
+```ts
+type OpenBodyOutput =
+  | { outcome: "done"; output: unknown }
+  | { outcome: "refused"; report: string[] }
+  | { outcome: "ceiling"; ceiling: keyof Ceilings; detail: string };
+```
+
+The output of an Open body. Route on `outcome` in the `onDone` of the state that invokes it:
+
+- `done`: the Chart got to a final state. `output` is the output of the Chart.
+- `refused`: the door refused the Chart. `report` has one line for each problem. Give it to the
+  Agent that wrote the Chart, so that it can send a corrected one.
+- `ceiling`: the Chart got to a ceiling, and the Open body stopped it. `ceiling` names it.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `output`
+
+  - `outcome`: `"done"`
+  - `output`: `unknown`
+- Form 2: `outcome`, `report`
+
+  - `outcome`: `"refused"`
+  - `report`: `string[]`
+- Form 3: `outcome`, `ceiling`, `detail`
+
+  - `outcome`: `"ceiling"`
+  - `ceiling`: `keyof Ceilings`
+  - `detail`: `string`
+
+**See also**
+
+- [Charts](../../concepts/charts.md)

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

@@ -0,0 +1,18 @@
+---
+title: OpenBodySlot
+description: The brand an Open body slot carries, as `definition` marks an Agent slot (ADR-0049).
+---
+
+# `OpenBodySlot`
+
+Type, in `@jr2/orchestrator/src/open-body.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 OpenBodySlot = { readonly openBody: OpenBodyDeclaration };
+```
+
+The brand an Open body slot carries, as `definition` marks an Agent slot ([ADR-0049](../decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md)).
+
+**Fields**
+
+- `openBody`: [`OpenBodyDeclaration`](type-openbodydeclaration.md)

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

@@ -0,0 +1,17 @@
+---
+title: OpenCommandInput
+description: "The input of a `command(open)`: a string for each `arg()` of the argv that the Instance binds, and with `pin`, the commit (`{ sha }`)."
+---
+
+# `OpenCommandInput`
+
+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 OpenCommandInput<P = false> = Readonly<Record<string, string>> &
+  ([P] extends [true] ? { sha: string } : unknown);
+```
+
+The input of a `command(open)`: a string for each `arg()` of the argv that the Instance binds,
+and with `pin`, the commit (`{ sha }`). The compiler cannot check the names. When the input has
+no string for an `arg()`, the Effect fails when it starts.

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

@@ -0,0 +1,12 @@
+---
+title: OpenEffect
+description: A type that the Authoring surface names.
+---
+
+# `OpenEffect`
+
+Type, in `@jr2/orchestrator/src/open-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 OpenEffect<P extends OpenEffectPart> = { readonly [openPart]: P };
+```

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

@@ -0,0 +1,12 @@
+---
+title: OpenEffectSlots
+description: A type that the Authoring surface names.
+---
+
+# `OpenEffectSlots`
+
+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 OpenEffectSlots<M extends AnyStateMachine> = Extract<SlotsOf<M>, { logic: OpenEffect<OpenEffectPart> }>["src"];
+```

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

@@ -0,0 +1,12 @@
+---
+title: OpenOf
+description: A type that the Authoring surface names.
+---
+
+# `OpenOf`
+
+Type, in `@jr2/orchestrator/src/open-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 OpenOf<P extends OpenEffectPart> = [P] extends [never] ? unknown : OpenEffect<P>;
+```

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

@@ -0,0 +1,23 @@
+---
+title: OpenSecret
+description: "`secret(open)`: a secret a packaged Machine names in its auth, a header or a command's env, and leaves for its composer to name (ADR-0054)."
+---
+
+# `OpenSecret`
+
+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 OpenSecret = {
+  readonly secret: string;
+  readonly path: { readonly secret: string; readonly path: true } & OpenSecretMark;
+} & OpenSecretMark;
+```
+
+`secret(open)`: a secret a packaged Machine names in its auth, a header or a command's env, and
+leaves for its composer to name ([ADR-0054](../decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)).
+
+**Fields**: each field of [`OpenSecretMark`](type-opensecretmark.md), and these:
+
+- `secret`: `string`
+- `path`: `{ readonly secret: string; readonly path: true; } & OpenSecretMark`

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

@@ -0,0 +1,12 @@
+---
+title: OpenSecretMark
+description: A type that the Authoring surface names.
+---
+
+# `OpenSecretMark`
+
+Type, in `@jr2/orchestrator/src/http-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 OpenSecretMark = { readonly [openSecretMark]: true };
+```

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

@@ -0,0 +1,31 @@
+---
+title: PermissiveNoSlotWorkspaceOptions
+description: "The options of a `workspace()` with no Repo Slot and no `input`: it starts with any input."
+---
+
+# `PermissiveNoSlotWorkspaceOptions`
+
+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 PermissiveNoSlotWorkspaceOptions<TInput = unknown> = Omit<SandboxOptions<never>, "repos"> & {
+  repos?: never;
+  input?: never;
+  spec?: (args: { input: TInput }) => NoSlotSpec;
+};
+```
+
+The options of a `workspace()` with no Repo Slot and no `input`: it starts with any input.
+
+**Fields**: each field of [`SandboxOptions`](type-sandboxoptions.md), except `repos`, and these:
+
+- `repos` (optional): `never`
+
+  Not present: the Workspace has no Repo Slot. Its Agents work in `/work`.
+- `input` (optional): `never`
+
+  Not present: a `workspace()` without `input` starts with any input.
+- `spec` (optional): `(args: { input: TInput; }) => NoSlotSpec`
+
+  A function from the input to the Workspace's [`NoSlotSpec`](type-noslotspec.md): only `workGroup`. Default:
+  no `workGroup`.

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

@@ -0,0 +1,32 @@
+---
+title: PermissiveWorkspaceOptions
+description: "The options of a `workspace()` with no `input`: it starts with any input."
+---
+
+# `PermissiveWorkspaceOptions`
+
+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 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.
+
+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`.
+
+**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-poolmachine.md

@@ -0,0 +1,28 @@
+---
+title: PoolMachine
+description: A type that the Authoring surface names.
+---
+
+# `PoolMachine`
+
+Type, in `@jr2/orchestrator/src/pool.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 PoolMachine<TWorker extends AnyStateMachine, TInput> = StateMachine<
+  any,
+  any,
+  any,
+  WrapperActors<"worker", TWorker, "next" | "gate" | "fail">,
+  any,
+  any,
+  any,
+  any,
+  any,
+  TInput,
+  PoolOutput,
+  any,
+  any,
+  any
+> &
+  JR2Wrapper<TWorker>;
+```