@jr2/orchestrator 0.3.0 → 0.5.1

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,19 @@
+---
+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> = [
+  ArgNames<A> | ([P] extends [true] ? "sha" : never),
+] extends [never]
+  ? void
+  : { [K in ArgNames<A> | ([P] extends [true] ? "sha" : never)]: string };
+```
+
+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,78 @@
+---
+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 = {
+  slot?: string;
+  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**
+
+- `slot` (optional): `string`
+
+  The Repo Slot whose Worktree is the working directory of the command. Write it only when the
+  Workspace has more than one Repo Slot. In a Workspace with no Repo Slot, the command starts in
+  `/work`, the folder that the steps of the Workspace share.
+
+  The command starts in the root of that Worktree. To run it in a subfolder, give the path as an
+  argument, or write `["sh", "-c", "cd <dir> && <program>"]`.
+
+  When it starts, it refuses:
+  - no `slot` under a Workspace with more than one Repo Slot: `command "<slot>" runs under a
+    Workspace carrying more than one Repo Slot (<slots>) and names none — say which Worktree it
+    runs in: command(argv, { slot: "<slot>" }) (ADR-0051)`. When `env` names an Effect secret,
+    the text is `command "<slot>" runs under a Workspace carrying more than one Repo Slot
+    (<slots>) — say which: { slot: "<slot>" } (ADR-0051)`.
+  - with an Effect secret in `env`, a Workspace with no Repo Slot: `command "<slot>" runs under
+    a Workspace with no Repo Slot: a command with an Effect secret runs against one commit of a
+    Repo Slot's branch, and there is none — declare a Repo Slot, or name no secret in its env, and
+    it runs in /work beside the Agent (ADR-0051)`.
+  - a `slot` that the Workspace does not have: `command "<slot>" names Repo Slot "<name>", which
+    its Workspace does not carry (<slots>)`.
+- `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,104 @@
+---
+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;
+```
+
+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.
+
+**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`
+
+**Example**
+
+```ts
+import {
+  command,
+  type CommandOutput,
+  fail,
+  jr2Setup,
+  workspace,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+type Input = Workspaced<{}, "app">;
+
+const passed = (output: CommandOutput): boolean =>
+  output.outcome === "exited" && output.code === 0;
+
+const body = jr2Setup({
+  types: {} as { context: Input; input: Input },
+  actors: { tests: command(["npm", "test"], { timeout: "15m" }), fail: fail() },
+}).createMachine({
+  id: "tests",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost" },
+  initial: "testing",
+  states: {
+    testing: {
+      invoke: {
+        src: "tests",
+        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" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  repos: { app: { url: "https://github.com/you/app.git" } },
+  spec: () => ({ branch: "tests" }),
+});
+```
+
+**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,109 @@
+---
+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<InputFrom<WorkspaceOf<M>>> };
+};
+```
+
+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<InputFrom<WorkspaceOf<M>>>; }`
+
+  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,65 @@
+---
+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;
+```
+
+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.
+
+**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`
+
+**See also**
+
+- [Effects](../../concepts/effects.md)

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"`.

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

@@ -0,0 +1,93 @@
+---
+title: EffectBinding
+description: The values that bind the Open parts of one Effect.
+---
+
+# `EffectBinding`
+
+Type, in `@jr2/orchestrator/src/open-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+
+```ts
+type EffectBinding = {
+  readonly url?: string | Text;
+  readonly argv?: readonly (string | Arg)[];
+  readonly secret?: string;
+  readonly target?: { readonly url: string; readonly token: Secret };
+};
+```
+
+The values that bind the Open parts of one Effect. A packaged Machine leaves a part of an Effect
+Open when it cannot know it. That part is the url of an `http` Effect, the argv of a `command`,
+the name of a secret, written `secret(open)`, or the target of a `dispatch`: the url of another
+Orchestrator and the secret that holds its Instance token, bound as one. You bind it once, where you register the
+Machine, with `customize(machine, { effects: { <slot>: binding } })`. Each key binds one Open
+part. For an Effect with two Open parts, one object holds both keys.
+
+The binding is a value, never a function of the run: no run chooses an Effect's url, argv or
+secret. `customize()` builds the Effect again with the bound parts, so a bound part gets every
+check that a part written in the definition gets.
+
+`customize()` refuses:
+- an empty binding, or a key for a part that is not Open: `customize(): the <kind> Effect
+  "<slot>" leaves its <parts> Open — bind it with <binding> (ADR-0054)`
+- an Effect with no Open part: ``customize(): the <kind> Effect "<slot>" of machine "<id>"
+  leaves nothing Open — its parts are fixed in its definition, and only a part a package left
+  `open` is bound, once (ADR-0054).``
+- `open` as a value: ``customize(): the <kind> Effect "<slot>"'s <part> is bound once, to a
+  value — not `open` again: no run chooses an Effect's <part> (ADR-0054)``. A function as a
+  value gives the same text, with `a function of the run` for `` `open` again ``.
+- a secret that is not a string: `customize(): the <kind> Effect "<slot>"'s secret is bound to
+  a secret's name, a string — the file the Effector reads it from: { secret: "<name>" }
+  (ADR-0054, ADR-0068)`
+
+`jr2 up` refuses a registered Machine with an Open part that nobody bound, and prints the
+`customize` line that binds it.
+
+**Fields**
+
+- `url` (optional): `string | Text`
+
+  The url of an `http` Effect whose url is Open: a string, or a `text` template with a secret
+  in its path, such as `` text`https://hooks.example.com/services/${secret("hook")}` ``. Its
+  scheme and host must be literal.
+- `argv` (optional): `readonly (string | Arg)[]`
+
+  The argv of a `command` whose argv is Open: one entry for each argument, never shell text.
+  An entry is a string or an `arg("<param>")` that the invoke's input fills. It must not be
+  empty.
+- `secret` (optional): `string`
+
+  The name of the secret that `secret(open)` stands for: an entry of `secrets` in
+  `jr2.config.ts`. The Effector reads it from a file of that name.
+- `target` (optional): `object`
+
+  - `url`: `string`
+  - `token`: [`Secret`](type-secret.md)
+
+**Example**
+
+```ts
+import { customize, http, jr2Setup, open, type EffectBinding } from "@jr2/orchestrator";
+
+const notifier = jr2Setup({
+  actors: { notify: http({ method: "POST", url: open }) },
+}).createMachine({
+  id: "notifier",
+  initial: "sending",
+  states: {
+    sending: { invoke: { src: "notify", onDone: "done" } },
+    done: { type: "final" },
+  },
+});
+
+const notify = { url: "https://hooks.example.com/build" } satisfies EffectBinding;
+
+export const machine = customize(notifier, { effects: { notify } });
+```
+
+**See also**
+
+- [Bind a shipped Machine's Open parts](../../guides/bind-open-parts.md)
+- [Effects](../../concepts/effects.md)
+- [ADR-0054: The kit ships Machines, and a shipped Machine leaves its parts Open](../decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.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-effectlogic.md

@@ -0,0 +1,12 @@
+---
+title: EffectLogic
+description: A type that the Authoring surface names.
+---
+
+# `EffectLogic`
+
+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 EffectLogic<I, O> = ActorLogic<EffectSnapshot<O, I>, EventObject, I> & EffectSlot;
+```

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

@@ -0,0 +1,14 @@
+---
+title: EnvOpenParts
+description: A type that the Authoring surface names.
+---
+
+# `EnvOpenParts`
+
+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 EnvOpenParts<Opt> = Opt extends { readonly env: infer E }
+  ? OpenSecretIn<E extends Readonly<Record<string, infer V>> ? V : never>
+  : never;
+```

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

@@ -0,0 +1,27 @@
+---
+title: EventAudience
+description: "Who may send an event: `\"agent\"` (an Agent, as a pick from its Menu), `\"external\"` (the caller of a Gate), or `\"any\"` (both)."
+---
+
+# `EventAudience`
+
+Type, in `src/define-event.ts` of `@jr2/agent-protocol`, a dependency of `@jr2/orchestrator`. 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 EventAudience = "agent" | "external" | "any";
+```
+
+Who may send an event: `"agent"` (an Agent, as a pick from its Menu), `"external"` (the caller of
+a Gate), or `"any"` (both).
+
+Leave it unset in most cases. Then the position of each `on` key decides: the event belongs to
+the party that its state, or the nearest state above it, invokes. An `on` key on a state that
+invokes no party, with no such state above it, belongs to both. Set an audience only to give an
+event to the other party too (`"any"`). Or set it to keep an event on the root from one party
+(`"agent"` or `"external"`).
+
+**See also**
+
+- [The Menu](../../concepts/the-menu.md)
+- [Gates](../../concepts/gates.md)
+- [ADR-0015: Workflows are authored through `jr2Setup`; vocabulary and agent menus derive from the machine](../decisions/0015-authoring-surface-absorbs-the-mechanism.md)