@jr2/orchestrator 0.4.1 → 0.6.0

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,26 @@
+---
+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 = Omit<SandboxOptions<never>, "repos"> & {
+  repos?: never;
+  input?: never;
+};
+```
+
+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.

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

@@ -0,0 +1,27 @@
+---
+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;
+};
+```
+
+The options of a `workspace()` with no `input`: it starts with any input. The `input` of a
+per-run Repo Slot is then `unknown`, and the mapper must check it before it reads a field.
+
+Use it for a Workspace that a Pool or another Machine starts. The body's `input` type says what
+that input is, and that also types the input of the Workspace. For a Workspace that a caller
+starts, declare `input`.
+
+**Fields**: each field of [`SandboxOptions`](type-sandboxoptions.md), and these:
+
+- `input` (optional): `never`
+
+  Not present: a `workspace()` without `input` starts with any input.

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

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

@@ -0,0 +1,22 @@
+---
+title: PoolNextInput
+description: "The input of a Source's `next`: the ids of the items that workers have now, the ids of the items that settled, and the Pool's input."
+---
+
+# `PoolNextInput`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+
+```ts
+type PoolNextInput<TInput = unknown> = { active: string[]; settled: string[]; input: TInput };
+```
+
+The input of a Source's `next`: the ids of the items that workers have now, the ids of the items
+that settled, and the Pool's input. So a Source over a list that a Machine holds needs no state
+of its own.
+
+**Fields**
+
+- `active`: `string[]`
+- `settled`: `string[]`
+- `input`: `TInput`

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

@@ -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, TInput> | 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, TInput> | 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,34 @@
+---
+title: PushInput
+description: "The input of a `push` Effect: the Worktree that a cut made, `{ 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> = {
+  worktree: O extends { slot: infer S extends string } ? `/work/${S}/${string}` : AnyWorktreePath;
+  branch?: never;
+  to?: never;
+  cwd?: never;
+  path?: never;
+} & (O["pin"] extends true ? { sha: string } : unknown) &
+  (O["squash"] extends true ? { message: string } : unknown);
+```
+
+The input of a `push` Effect: the Worktree that a cut made, `{ sha }` with `pin`, and
+`{ message }` with `squash`. It names no branch: jr2 reads it from the cut's record, so no word of
+a Chart reaches a remote branch. The other keys are refused by name, because each is a key of a
+cut or a Turn, and a mapper's excess key is no compile error otherwise.
+
+**Fields**
+
+- `worktree`: ``O extends { slot: infer S extends string; } ? `/work/${S}/${string}` : AnyWorktreePath``
+
+  The Worktree to push: `event.output.path` of its cut, of the push's Repo Slot.
+- `branch` (optional): `never`
+- `to` (optional): `never`
+- `cwd` (optional): `never`
+- `path` (optional): `never`

package/docs/reference/authoring-surface/type-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,149 @@
+---
+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 })
+  | LaterOutcome;
+```
+
+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.
+
+The union is open (`LaterOutcome`): give the rest a last arm with no guard.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `stage`, `reason`, `detail`
+
+  - `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`
+- Form 5: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
+
+**Example**
+
+```ts
+import {
+  fail,
+  isReady,
+  jr2Setup,
+  push,
+  type PushOutput,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+type Input = Workspaced<{ branch: string; sha: string }, "app">;
+
+const releaseTree = (context: Input) => `${context.workspace.repos.app}/release` as const;
+
+// A push that did not happen (`rejected` or `diverged`) is a different problem from one jr2
+// cannot see (`unknown`).
+const notPushed = (output: PushOutput): boolean =>
+  output.outcome === "rejected" || output.outcome === "diverged";
+
+const body = jr2Setup({
+  types: {} as { context: Input; input: Input },
+  actors: { cut: worktree({ expect: "existing" }), publish: push({ pin: true }), fail: fail() },
+}).createMachine({
+  id: "release",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: releaseTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "publishing" }, { target: "notCut" }],
+      },
+    },
+    publishing: {
+      invoke: {
+        src: "publish",
+        input: ({ context }) => ({ worktree: releaseTree(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" } } },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  repos: { app: { url: "https://github.com/you/app.git" } },
+});
+```
+
+**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, so never with
+`.`: `/work/.jr2/` is reserved for jr2. `workspace()` and `customize()` refuse a key that does
+not: ``<where>: Repo Slot key "<key>" is not a directory name — a slot becomes `/work/<slot>`,
+`/work/.jr2/` is reserved for jr2, and its order matters, so it starts with a letter and matches
+/^[A-Za-z][A-Za-z0-9._-]*$/ (ADR-0051, ADR-0075).`` They refuse a value of another
+shape: ``<where>: Repo Slot "<slot>" is <what> — a slot is `open`, a url, `{ url, ref? }`, or a
+mapper `({ input }) => url | { url, ref? }` over the door (ADR-0051).``
+
+**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,
+  },
+});
+```
+
+**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;
+```