@jr2/orchestrator 0.4.1 → 0.6.0

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

@@ -0,0 +1,95 @@
+---
+title: HttpOutput
+description: "The output of an `http` Effect: what the `onDone` of its state gets as `event.output`."
+---
+
+# `HttpOutput`
+
+Type, in `@jr2/orchestrator/src/effector-wire.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type HttpOutput = LaterOutcome | {
+  outcome: "response";
+  status: number;
+  headers: Record<string, string>;
+  contentType: string;
+  size: number;
+  body?: string | undefined;
+  truncated?: boolean | undefined;
+} | {
+  outcome: "unknown" | "unreachable" | "refused";
+  reason: string;
+};
+```
+
+The output of an `http` Effect: what the `onDone` of its state gets as `event.output`. Every
+outcome is output. A 4xx or 5xx status is output too. Route on `outcome`:
+
+- `response`: an answer came back. `status` is its HTTP status. `headers`, `contentType` and
+  `size` tell about the body. `body` is there when the body is text: at most `maxBody` bytes
+  (`truncated` is `true` when jr2 cut it). A body that is not text gives only its size and
+  content type. jr2 replaces each value of an Effect secret that the Effector holds, and its
+  usual encodings, with `[secret:<name>]`, in the body and the headers.
+- `unreachable`: the call did not go out, for example because the name did not resolve, or the
+  connection or TLS failed. `reason` tells why.
+- `refused`: jr2 or the Effector refused the call, and nothing was sent. For example, a path
+  segment that is `.`, `..` or empty, or a request that is too large. `reason` tells why.
+- `unknown`: the call can have gone out, but no answer came, or jr2 cannot tell after a restart.
+  `reason` tells why. jr2 does not send it again unless it is marked `idempotent`.
+
+The union is open (`LaterOutcome`): give the rest a last arm with no guard.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `status`, `headers`, `contentType`, `size`, `body`, `truncated`
+
+  - `outcome`: `"response"`
+  - `status`: `number`
+  - `headers`: `Record<string, string>`
+  - `contentType`: `string`
+  - `size`: `number`
+  - `body` (optional): `string`
+  - `truncated` (optional): `boolean`
+- Form 2: `outcome`, `reason`
+
+  - `outcome`: `"unknown" | "unreachable" | "refused"`
+  - `reason`: `string`
+- Form 3: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
+
+**Example**
+
+```ts
+import { fail, http, jr2Setup, type HttpOutput } from "@jr2/orchestrator";
+
+const ok = (output: HttpOutput): boolean => output.outcome === "response" && output.status < 300;
+
+export const machine = jr2Setup({
+  actors: { health: http({ method: "GET", url: "https://app.example.com/healthz" }), fail: fail() },
+}).createMachine({
+  id: "health",
+  initial: "checking",
+  states: {
+    checking: {
+      invoke: {
+        src: "health",
+        onDone: [
+          { guard: ({ event }) => ok(event.output), target: "healthy" },
+          { target: "unhealthy" },
+        ],
+      },
+    },
+    healthy: { type: "final" },
+    // Not a final state: the run ends `failed`, and `jr2 run` exits 1.
+    unhealthy: { invoke: { src: "fail", input: { reason: "the app is not healthy" } } },
+  },
+});
+```
+
+**See also**
+
+- [Effects](../../concepts/effects.md)
+- [Run a command or call a URL with an Effect](../../guides/run-a-command-or-call-a-url.md)
+- [ADR-0068: An Effector holds an Effect's secrets and signs its wire](../decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)

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

@@ -0,0 +1,33 @@
+---
+title: HttpRequestParts
+description: "What the `request` of an `http` definition returns: the part of the request that changes for each run."
+---
+
+# `HttpRequestParts`
+
+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 HttpRequestParts = {
+  path?: readonly string[];
+  json?: unknown;
+  text?: string;
+};
+```
+
+What the `request` of an `http` definition returns: the part of the request that changes for
+each run. The definition fixes the rest.
+
+**Fields**
+
+- `path` (optional): `readonly string[]`
+
+  Path segments that jr2 adds to the end of the url. jr2 encodes each segment. A segment that
+  is `.`, `..` or empty gives the output `refused`, and nothing is sent.
+- `json` (optional): `unknown`
+
+  A JSON body. Do not give `text` too. When it starts, the Effect refuses both: ``http:
+  `request` returned both json and text``.
+- `text` (optional): `string`
+
+  A text body.

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-lateroutcome.md

@@ -0,0 +1,21 @@
+---
+title: LaterOutcome
+description: A value of `outcome` that this kit does not give.
+---
+
+# `LaterOutcome`
+
+Type, in `@jr2/orchestrator/src/effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type LaterOutcome = { outcome: "(a later outcome)"; reason?: string };
+```
+
+A value of `outcome` that this kit does not give. It stands in the union so that no author can
+write an exhaustive check, so that a later outcome is no break: route on what you know, and give
+the rest a last arm.
+
+**Fields**
+
+- `outcome`: `"(a later outcome)"`
+- `reason` (optional): `string`

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-namestart.md

@@ -0,0 +1,77 @@
+---
+title: NameStart
+description: "What a Worktree's name may start with: neither `.` nor `-`, and not the end of the path."
+---
+
+# `NameStart`
+
+Type, in `@jr2/orchestrator/src/worktree.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 NameStart =
+  | "a"
+  | "b"
+  | "c"
+  | "d"
+  | "e"
+  | "f"
+  | "g"
+  | "h"
+  | "i"
+  | "j"
+  | "k"
+  | "l"
+  | "m"
+  | "n"
+  | "o"
+  | "p"
+  | "q"
+  | "r"
+  | "s"
+  | "t"
+  | "u"
+  | "v"
+  | "w"
+  | "x"
+  | "y"
+  | "z"
+  | "A"
+  | "B"
+  | "C"
+  | "D"
+  | "E"
+  | "F"
+  | "G"
+  | "H"
+  | "I"
+  | "J"
+  | "K"
+  | "L"
+  | "M"
+  | "N"
+  | "O"
+  | "P"
+  | "Q"
+  | "R"
+  | "S"
+  | "T"
+  | "U"
+  | "V"
+  | "W"
+  | "X"
+  | "Y"
+  | "Z"
+  | "0"
+  | "1"
+  | "2"
+  | "3"
+  | "4"
+  | "5"
+  | "6"
+  | "7"
+  | "8"
+  | "9"
+  | "_";
+```
+
+What a Worktree's name may start with: neither `.` nor `-`, and not the end of the path.

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

@@ -0,0 +1,27 @@
+---
+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;
+};
+```
+
+The options of a `workspace()` with no Repo Slot that declares the input that starts a run.
+`repos` is left out.
+
+**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).

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

@@ -0,0 +1,12 @@
+---
+title: NotWorktreeKeys
+description: A type that the Authoring surface names.
+---
+
+# `NotWorktreeKeys`
+
+Type, in `@jr2/orchestrator/src/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 NotWorktreeKeys = { cwd?: never; path?: never; branch?: never };
+```

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,22 @@
+---
+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, Opt = unknown> = Readonly<Record<string, string>> &
+  ([P] extends [true] ? { sha: string } : unknown) &
+  WorktreeKey<Opt>;
+```
+
+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.
+
+**Fields**
+
+- `worktree` (optional): [`AnyWorktreePath`](type-anyworktreepath.md)

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"];
+```