@jr2/orchestrator 0.4.1 → 0.6.0

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

@@ -0,0 +1,22 @@
+---
+title: ChartTransition
+description: "A transition: a target alone, or the object form."
+---
+
+# `ChartTransition`
+
+Type, in `@jr2/orchestrator/src/chart.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 ChartTransition =
+  | string
+  | {
+      target?: string | string[];
+      guard?: ChartGuard;
+      actions?: ChartAction[];
+      reenter?: boolean;
+      description?: string;
+    };
+```
+
+A transition: a target alone, or the object form.

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

@@ -0,0 +1,14 @@
+---
+title: ChartTransitions
+description: "One transition or a list, in xstate's order."
+---
+
+# `ChartTransitions`
+
+Type, in `@jr2/orchestrator/src/chart.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 ChartTransitions = ChartTransition | ChartTransition[];
+```
+
+One transition or a list, in xstate's order.

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

@@ -0,0 +1,15 @@
+---
+title: ChartValue
+description: "A value whose strings may hold `{{<root>.<path>}}` placeholders and whose objects may be `{ \"$ref\": \"<root>.<path>\" }`."
+---
+
+# `ChartValue`
+
+Type, in `@jr2/orchestrator/src/chart.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 ChartValue = ChartJson;
+```
+
+A value whose strings may hold `{{<root>.<path>}}` placeholders and whose objects may be
+`{ "$ref": "<root>.<path>" }`. Resolved by `resolveReferences` at invoke time.

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

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

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

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

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

@@ -0,0 +1,15 @@
+---
+title: CommandEnv
+description: "The `env` of a `command`: for each variable, `secret(\"name\")` for the value of an Effect secret, or `secret(\"name\").path` for the path of a file that holds it."
+---
+
+# `CommandEnv`
+
+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 CommandEnv = Readonly<Record<string, { readonly secret: string; readonly path: unknown }>>;
+```
+
+The `env` of a `command`: for each variable, `secret("name")` for the value of an Effect
+secret, or `secret("name").path` for the path of a file that holds it.

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

@@ -0,0 +1,20 @@
+---
+title: CommandInput
+description: "A command's input: one string per argv slot, and with `pin` the approved commit (`{ sha }`); none when there is neither."
+---
+
+# `CommandInput`
+
+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 CommandInput<A extends readonly unknown[], P = false, Opt = unknown> = [
+  ArgNames<A> | ([P] extends [true] ? "sha" : never),
+] extends [never]
+  ? (WorktreeKey<Opt> & NotWorktreeKeys) | ([Opt] extends [{ readonly env: object }] ? never : void)
+  : { [K in ArgNames<A> | ([P] extends [true] ? "sha" : never)]: string } & WorktreeKey<Opt> &
+      Omit<NotWorktreeKeys, ArgNames<A>>;
+```
+
+A command's input: one string per argv slot, and with `pin` the approved commit (`{ sha }`);
+none when there is neither.

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

@@ -0,0 +1,56 @@
+---
+title: CommandOptions
+description: "The options of `command()`: the Repo Slot it runs in, how long it can run, how much of its output it keeps, its Effect secrets, and the commit it runs against."
+---
+
+# `CommandOptions`
+
+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 CommandOptions = {
+  timeout?: Duration;
+  tail?: number;
+  env?: CommandEnv;
+  pin?: boolean;
+};
+```
+
+The options of `command()`: the Repo Slot it runs in, how long it can run, how much of its
+output it keeps, its Effect secrets, and the commit it runs against.
+
+**Fields**
+
+- `timeout` (optional): [`Duration`](type-duration.md)
+
+  How long the command can run: a number and a unit, such as `"90s"`, `"10m"` or `"1h"`.
+  Default `"10m"`. When the time ends, jr2 kills the process group, and the output is
+  `timeout`. It refuses a value that is not a positive duration: `command: timeout "<timeout>"
+  is not a positive duration (like "90s", "10m", "1h")`.
+- `tail` (optional): `number`
+
+  The number of characters that `tail` keeps from the end of what the command wrote. Default
+  4096.
+- `env` (optional): [`CommandEnv`](type-commandenv.md)
+
+  The environment variables of the command, each an Effect secret. `secret("x")` gives the
+  value, and `secret("x").path` gives the path of a file that holds the value. When `env` names
+  one, the command runs in the Sandbox Effector against one commit, not in the Worktree that the
+  Agent changes. Without `env`, it runs in the Harness container, beside the Agent.
+
+  It refuses a name that is not a variable name, and `PATH`, `HOME` and `TMPDIR`: ``command(argv,
+  { env }): "<name>" is not a variable the author sets — PATH, HOME and TMPDIR are the
+  Effector's (ADR-0067)``.
+- `pin` (optional): `boolean`
+
+  Only for a command whose `env` names an Effect secret. `true`: the input of the Effect names
+  the commit to run against (`{ sha }`, a full commit id, for example one that a Gate approved).
+  Default: the tip of the Agent's branch when the Effect starts.
+
+  It refuses `pin: true` on a command that names no Effect secret: ``command(argv, { pin: true
+  }) names no secret in its env: `pin` chooses the commit a credentialed command runs against in
+  the Sandbox Effector, and a command that names no secret runs in the live Worktree (ADR-0067)
+  — name its secret, command(argv, { env: { NAME: secret("x") }, pin: true }), or drop `pin` ``.
+
+  When it starts, it refuses an input `sha` that is not a full commit id: `command "<slot>"
+  (pin): its input's sha is not a full commit id`.

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

@@ -0,0 +1,122 @@
+---
+title: CommandOutput
+description: "The output of a `command` Effect: what the `onDone` of its state gets as `event.output`."
+---
+
+# `CommandOutput`
+
+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 CommandOutput = (ExecOutcome & { dirty?: boolean }) | Unknown | LaterOutcome;
+```
+
+The output of a `command` Effect: what the `onDone` of its state gets as `event.output`. Every
+outcome is output. A failed program is output too. Route on `outcome`:
+
+- `exited`: the program ended. `code` is its exit code. A program that the container does not
+  have is `exited` with code 127.
+- `timeout`: the command ran past its `timeout`, and jr2 killed it.
+- `killed`: a signal ended it. `signal` names the signal.
+- `unknown`: jr2 cannot tell what the command did, for example because the Harness restarted
+  while it ran. `reason` tells why. jr2 does not run it again.
+
+`tail` is the end of what the command wrote, at most the `tail` option of `command` in
+characters. `dirty` is `true` when a command that names an Effect secret ran against a commit,
+and the Worktree held changes that it did not see.
+
+The union is open ([`LaterOutcome`](type-lateroutcome.md)): give the rest a last arm with no guard.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `code`, `tail`, `dirty`
+
+  - `outcome`: `"exited"`
+  - `code`: `number`
+  - `tail`: `string`
+  - `dirty` (optional): `boolean`
+- Form 2: `outcome`, `tail`, `dirty`
+
+  - `outcome`: `"timeout"`
+  - `tail`: `string`
+  - `dirty` (optional): `boolean`
+- Form 3: `outcome`, `signal`, `tail`, `dirty`
+
+  - `outcome`: `"killed"`
+  - `signal`: `string`
+  - `tail`: `string`
+  - `dirty` (optional): `boolean`
+- Form 4: `outcome`, `reason`
+
+  - `outcome`: `"unknown"`
+  - `reason`: `string`
+- Form 5: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
+
+**Example**
+
+```ts
+import {
+  command,
+  type CommandOutput,
+  fail,
+  isReady,
+  jr2Setup,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+type Input = Workspaced<{}, "app">;
+
+const testTree = (context: Input) => `${context.workspace.repos.app}/test` as const;
+
+const passed = (output: CommandOutput): boolean =>
+  output.outcome === "exited" && output.code === 0;
+
+const body = jr2Setup({
+  types: {} as { context: Input; input: Input },
+  actors: { cut: worktree(), tests: command(["npm", "test"], { timeout: "15m" }), fail: fail() },
+}).createMachine({
+  id: "tests",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: testTree(context), branch: "tests" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "testing" }, { target: "notCut" }],
+      },
+    },
+    testing: {
+      invoke: {
+        src: "tests",
+        input: ({ context }) => ({ worktree: testTree(context) }),
+        onDone: [
+          { guard: ({ event }) => passed(event.output), target: "green" },
+          { target: "red" },
+        ],
+      },
+    },
+    green: { type: "final" },
+    // Not a final state: a final state means `done`, and the run ends `failed` here.
+    red: { invoke: { src: "fail", input: { reason: "npm test did not pass" } } },
+    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**
+
+- [Effects](../../concepts/effects.md)
+- [Run a command or call a URL with an Effect](../../guides/run-a-command-or-call-a-url.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-customize.md

@@ -0,0 +1,111 @@
+---
+title: Customize
+description: "The parts of one Machine that `customize()` can retune: its Agents, its Open Effects, the Machines it composes, and the Sandbox of its `workspace()`."
+---
+
+# `Customize`
+
+Type, in `@jr2/orchestrator/src/customize.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+
+```ts
+type Customize<M extends AnyStateMachine> = {
+  agents?: [AgentSlots<Reached<M>>] extends [never]
+    ? never
+    : { [K in AgentSlots<Reached<M>>]?: Partial<AgentDefinition> };
+  effects?: [OpenEffectSlots<Reached<M>>] extends [never]
+    ? never
+    : { [K in OpenEffectSlots<Reached<M>>]?: BindingOf<LogicAt<Reached<M>, K>> };
+  actors?: [ChildSlots<Reached<M>>] extends [never]
+    ? never
+    : { [K in ChildSlots<Reached<M>>]?: Customize<ChildAt<Reached<M>, K>> };
+  image?: string;
+  user?: string | UserContainer;
+  resources?: Size;
+  repos?: [RepoSlotsOf<M>] extends [never]
+    ? never
+    : { [K in RepoSlotsOf<M>]?: RepoSlot<Exclude<InputFrom<WorkspaceOf<M>>, undefined>> };
+};
+```
+
+The parts of one Machine that `customize()` can retune: its Agents, its Open Effects, the
+Machines it composes, and the Sandbox of its `workspace()`. The type comes from the Machine
+itself, so it offers only the parts that the Machine declares. A key for a part the Machine does
+not declare does not compile. The `agents`, `effects`, `actors` and `repos` keys take no value
+when the Machine has no such part. `image`, `user` and `resources` compile on every Machine, and
+`customize()` refuses them when the Machine composes no `workspace()`.
+
+Every key is optional. Write only what you change.
+
+**Fields**
+
+- `agents` (optional): `[ AgentSlots<Reached<M>> ] extends [ never ] ? never : { [K in AgentSlots<Reached<M>>]?: Partial<AgentDefinition>; }`
+
+  Retune the Agents that this Machine carries, by slot name: `{ coder: { model } }`. Each
+  override goes over the definition that the author wrote, field by field, so `{ model }` alone
+  keeps the author's instructions. When the author left the model Open, this is where you bind
+  it. Allowed fields: the fields of an `agent()` definition. At run time, `customize()` refuses a
+  slot that holds no Agent: `customize(): machine "<id>" carries no Agent slot "<slot>" — its
+  Agents are: <slots>`.
+- `effects` (optional): `[ OpenEffectSlots<Reached<M>> ] extends [ never ] ? never : { [K in OpenEffectSlots<Reached<M>>]?: BindingOf<LogicAt<Reached<M>, K>>; }`
+
+  Bind the Open parts of this Machine's Effects, by slot name: `{ url }` for an `http` Effect
+  whose url is Open, `{ argv }` for a `command` whose argv is Open, `{ secret }` for an Effect
+  that names `secret(open)`, `{ target: { url, token: secret("<name>") } }` for a `dispatch`
+  whose target is Open. For an Effect with two Open parts, one object holds both keys, and
+  a binding that leaves one out does not compile. Only Effects with an Open part are offered.
+  See [`EffectBinding`](type-effectbinding.md) for the values and the refusals.
+- `actors` (optional): `[ ChildSlots<Reached<M>> ] extends [ never ] ? never : { [K in ChildSlots<Reached<M>>]?: Customize<ChildAt<Reached<M>, K>>; }`
+
+  Retune a Machine that this Machine composes, by slot name. The value has the same shape as
+  these parts, one level down. At run time, `customize()` refuses a slot that holds no Machine:
+  `customize(): machine "<id>" composes no Machine under "<slot>"`.
+- `image` (optional): `string`
+
+  The Sandbox Image: a `file:` URL to a docker context that your module ships
+  (`import.meta.resolve("./image")`), which `jr2 up` builds, or a registry ref. It replaces the
+  image of the `workspace()`. When the Machine composes no `workspace()`, `customize()` refuses it
+  at run time.
+- `user` (optional): `string | UserContainer`
+
+  The User Container: its image, as a `file:` URL or a registry ref, or a
+  [`UserContainer`](type-usercontainer.md) that also gives its part of the Size. It replaces the whole User
+  Container, its part of the Size included. When the Machine composes no `workspace()`,
+  `customize()` refuses it at run time.
+- `resources` (optional): [`Size`](type-size.md)
+
+  The Size, layered field by field over the Size of the `workspace()`: `{ limits: { memory } }`
+  keeps the author's cpu. Only `limits.memory` and `limits.cpu`. See [`Size`](type-size.md). Only for a
+  Machine that composes a `workspace()`.
+- `repos` (optional): `[ RepoSlotsOf<M> ] extends [ never ] ? never : { [K in RepoSlotsOf<M>]?: RepoSlot<Exclude<InputFrom<WorkspaceOf<M>>, undefined>>; }`
+
+  Bind the Repo Slots of the `workspace()`, by slot name. Each value is one of these:
+
+  - a url
+  - a Binding `{ url, ref? }`
+  - a function `({ input }) => url | { url, ref? }` over the run input
+  - `open`, to leave the slot for the next composer to bind
+
+  You can bind an Open slot, or give a bound or per-run slot a different Binding. A slot that
+  the Machine does not declare does not compile. Some Machines, such as `task`, leave their
+  whole slot map Open. Then you name every slot, and at least one. The keys are your names for
+  the Repos, and the Machine says what their order means.
+
+**Example**
+
+```ts
+import { customize, type Customize } from "@jr2/orchestrator";
+import { task } from "@jr2/machines";
+
+const parts: Customize<typeof task> = {
+  repos: { app: { url: "https://github.com/you/app.git", ref: "main" } },
+  agents: { coder: { model: "anthropic/claude-haiku-5-5", thinkingLevel: "high" } },
+};
+
+export const machine = customize(task, parts);
+```
+
+**See also**
+
+- [Bind a shipped Machine's Open parts](../../guides/bind-open-parts.md)
+- [Composition](../../concepts/composition.md)
+- [ADR-0049: A Machine carries its parts and composes by invoke](../decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md)

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

@@ -0,0 +1,39 @@
+---
+title: DispatchDefinition
+description: The definition of a `dispatch` Effect (ADR-0071).
+---
+
+# `DispatchDefinition`
+
+Type, in `@jr2/orchestrator/src/dispatch-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 DispatchDefinition<S extends z.ZodObject | undefined = undefined> = {
+  input?: S;
+  wait?: boolean;
+  timeout?: Duration;
+  target?: { url: string; token: NamedSecret } | typeof open;
+};
+```
+
+The definition of a `dispatch` Effect ([ADR-0071](../decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)). Every field is optional.
+
+**Fields**
+
+- `input` (optional): `S`
+
+  A zod schema of the run input of the Workflow. It types the `input` of the invoke and
+  `fromPick`, and `jr2 up` compares it with the input that the Workflow declares. Without it,
+  only the Workflow checks the input.
+- `wait` (optional): `boolean`
+
+  `true`: end when the new run ends (`settled`). `false`, the default: end when the
+  Orchestrator accepts the run (`started`).
+- `timeout` (optional): [`Duration`](type-duration.md)
+
+  How long the Effect waits: by default 30s for the start, and 10m with `wait`.
+- `target` (optional): `{ url: string; token: NamedSecret; } | typeof open`
+
+  A different Orchestrator: `url` is its origin, and `token` is the secret that holds its
+  Instance token. Or `open`, which the composer binds with `customize(<import>, { effects: {
+  <slot>: { target: { url, token } } } })`. Without it, the run starts in this Orchestrator.

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

@@ -0,0 +1,14 @@
+---
+title: DispatchInput
+description: "A dispatch's input: the run's body — the slot's schema's type, or any JSON object."
+---
+
+# `DispatchInput`
+
+Type, in `@jr2/orchestrator/src/dispatch-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 DispatchInput<S> = S extends z.ZodObject ? z.infer<S> : Record<string, unknown>;
+```
+
+A dispatch's input: the run's body — the slot's schema's type, or any JSON object.

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

@@ -0,0 +1,14 @@
+---
+title: DispatchOpenParts
+description: "The Open part a dispatch definition states: its target, when it is `open`."
+---
+
+# `DispatchOpenParts`
+
+Type, in `@jr2/orchestrator/src/dispatch-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 DispatchOpenParts<T> = T extends typeof open ? "target" : never;
+```
+
+The Open part a dispatch definition states: its target, when it is `open`.

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

@@ -0,0 +1,72 @@
+---
+title: DispatchOutput
+description: The output of a `dispatch` Effect.
+---
+
+# `DispatchOutput`
+
+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 DispatchOutput =
+  | { outcome: "started"; run: string }
+  | {
+      outcome: "settled";
+      run: string;
+      status: "done" | "failed" | "error" | "cancelled" | "lost" | "drifted" | "live";
+      output?: unknown;
+    }
+  | { outcome: "refused"; status: number; report: string[] }
+  | { outcome: "unreachable"; reason: string }
+  | Unknown
+  | LaterOutcome;
+```
+
+The output of a `dispatch` Effect. Route on `outcome`:
+
+- `started`: the Orchestrator accepted the new run. `run` is its id.
+- `settled`: with `wait`, the new run ended. `status` is `done`, `failed`, `error`, `cancelled`,
+  `lost` or `drifted`, and `output` is the output of its Machine. For `failed`, `output` is the
+  Failure, `{ reason, detail? }`. `status` is `live` when the timeout came first, and the run
+  continues.
+- `refused`: the Orchestrator started no run. `status` is the HTTP status: 400 for an input that
+  the Workflow does not take, 404 for a Workflow that it does not have, 409 for a named Chart that
+  cannot run now, 422 for a Chart that it refuses. `report` holds the lines of the refusal.
+- `unreachable`: the Orchestrator of the target did not answer. No run started.
+- `unknown`: jr2 cannot tell if a run started.
+
+The union is open ([`LaterOutcome`](type-lateroutcome.md)): give the rest a last arm with no guard.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `reason`
+
+  - `outcome`: `"unknown"`
+  - `reason`: `string`
+- Form 2: `outcome`, `run`
+
+  - `outcome`: `"started"`
+  - `run`: `string`
+- Form 3: `outcome`, `run`, `status`, `output`
+
+  - `outcome`: `"settled"`
+  - `run`: `string`
+  - `status`: `"done" | "failed" | "error" | "cancelled" | "lost" | "drifted" | "live"`
+  - `output` (optional): `unknown`
+- Form 4: `outcome`, `status`, `report`
+
+  - `outcome`: `"refused"`
+  - `status`: `number`
+  - `report`: `string[]`
+- Form 5: `outcome`, `reason`
+
+  - `outcome`: `"unreachable"`
+  - `reason`: `string`
+- Form 6: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
+
+**See also**
+
+- [Effects](../../concepts/effects.md)

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

@@ -0,0 +1,19 @@
+---
+title: DoorlessInput
+description: A type that the Authoring surface names.
+---
+
+# `DoorlessInput`
+
+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 DoorlessInput<TBody extends AnyStateMachine> =
+  unknown extends InputFrom<TBody>
+    ? unknown
+    : [keyof Omit<InputFrom<TBody>, "workspace">] extends [never]
+      ? unknown
+      : {} extends Omit<InputFrom<TBody>, "workspace">
+        ? Omit<InputFrom<TBody>, "workspace"> | undefined
+        : Omit<InputFrom<TBody>, "workspace">;
+```

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

@@ -0,0 +1,15 @@
+---
+title: Duration
+description: "A length of time: a positive number and a unit, `s`, `m` or `h`."
+---
+
+# `Duration`
+
+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 Duration = `${number}s` | `${number}m` | `${number}h`;
+```
+
+A length of time: a positive number and a unit, `s`, `m` or `h`. For example `"90s"`, `"10m"`
+or `"1h"`.