@jr2/orchestrator 0.4.1 → 0.6.0

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)

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

@@ -0,0 +1,45 @@
+---
+title: EventDef
+description: "A workflow event, as `defineEvent` gives it back: plain, frozen data and a zod schema, safe to import anywhere."
+---
+
+# `EventDef`
+
+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 EventDef<Name extends string = string, Input extends z.ZodObject = z.ZodObject> = {
+  readonly name: Name;
+  readonly description?: string;
+  readonly input: Input;
+  readonly semantics: EventSemantics;
+  readonly audience?: EventAudience;
+};
+```
+
+A workflow event, as `defineEvent` gives it back: plain, frozen data and a zod schema, safe to
+import anywhere. Give it to `jr2Setup({ events })`. A Machine accepts only the events in that
+list.
+
+**Fields**
+
+- `name`: `Name`
+
+  The event's name: its xstate event `type`, and the name of its tool on the Agent's Menu.
+- `description` (optional): `string`
+
+  What the event means. An Agent's model reads it as the tool's description.
+- `input`: `Input`
+
+  The schema of the event's payload: a flat `z.object`, never a union.
+- `semantics`: [`EventSemantics`](type-eventsemantics.md)
+
+  How the sender gets its answer: always `"ack"` on an event that `createMachine` accepts.
+- `audience` (optional): [`EventAudience`](type-eventaudience.md)
+
+  Who may send the event. Absent: the state of each `on` key decides (see [`EventAudience`](type-eventaudience.md)).
+
+**See also**
+
+- [Write a Workflow](../../guides/write-a-workflow.md)
+- [ADR-0011: Control events are workflow-defined and delivered by closure, not routed](../decisions/0011-workflow-defined-events.md)

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

@@ -0,0 +1,16 @@
+---
+title: EventFrom
+description: A type that the Authoring surface names.
+---
+
+# `EventFrom`
+
+Type, in `src/define-event.ts` of `@jr2/agent-protocol`, a dependency of `@jr2/orchestrator`. 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 EventFrom<D extends EventDef> =
+  D extends EventDef<infer N, infer I>
+    ?
+      { type: N } & (z.infer<I> extends Record<string, never> ? unknown : z.infer<I>)
+    : never;
+```

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

@@ -0,0 +1,26 @@
+---
+title: EventSemantics
+description: How the party that sends an event gets its answer.
+---
+
+# `EventSemantics`
+
+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 EventSemantics = "ack" | "poll";
+```
+
+How the party that sends an event gets its answer.
+
+- `"ack"`, the default: jr2 delivers the event and answers the sender. When the event starts
+  work inside the Agent's state, the answer comes when that work is done.
+- `"poll"`: reserved. `createMachine` refuses it: ``machine "<id>": event "<name>" is `poll`,
+  which is reserved but NOT IMPLEMENTED (ADR-0013). Only `ack` events can be delivered today;
+  nothing drains a steer inbox, and degrading it to `ack` would hand the Agent a lying tool
+  contract.``
+
+**See also**
+
+- [The Menu](../../concepts/the-menu.md)
+- [ADR-0006: The agent picks from a Machine-defined, schema-backed menu; it does not drive the workflow](../decisions/0006-agent-control-surface.md)

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

@@ -0,0 +1,34 @@
+---
+title: ExecOutcome
+description: How an exec ended.
+---
+
+# `ExecOutcome`
+
+Type, in `@jr2/orchestrator/src/wire.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 ExecOutcome =
+  | { outcome: "exited"; code: number; tail: string }
+  | { outcome: "timeout"; tail: string }
+  | { outcome: "killed"; signal: string; tail: string };
+```
+
+How an exec ended. Every one is output; none is a fault.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `code`, `tail`
+
+  - `outcome`: `"exited"`
+  - `code`: `number`
+  - `tail`: `string`
+- Form 2: `outcome`, `tail`
+
+  - `outcome`: `"timeout"`
+  - `tail`: `string`
+- Form 3: `outcome`, `signal`, `tail`
+
+  - `outcome`: `"killed"`
+  - `signal`: `string`
+  - `tail`: `string`

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

@@ -0,0 +1,14 @@
+---
+title: FailSlot
+description: "The logic `fail()` returns: `failLogic` with the brand the walk reads."
+---
+
+# `FailSlot`
+
+Type, in `@jr2/orchestrator/src/fail.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 FailSlot = PromiseActorLogic<never, FailureInput> & { readonly [FAIL_SLOT]: true };
+```
+
+The logic `fail()` returns: `failLogic` with the brand the walk reads.

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

@@ -0,0 +1,19 @@
+---
+title: Failure
+description: "A Failure as `isFailure` narrows an error to it: the payload's fields, on the error itself."
+---
+
+# `Failure`
+
+Type, in `@jr2/orchestrator/src/fail.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 Failure = { readonly reason: string; readonly detail?: unknown };
+```
+
+A Failure as `isFailure` narrows an error to it: the payload's fields, on the error itself.
+
+**Fields**
+
+- `reason`: `string`
+- `detail` (optional): `unknown`

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

@@ -0,0 +1,20 @@
+---
+title: FailureInput
+description: "What a Failure carries: `reason`, text for a person, and `detail`, optional JSON for a machine reader."
+---
+
+# `FailureInput`
+
+Type, in `@jr2/orchestrator/src/fail.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 FailureInput = { reason: string; detail?: unknown };
+```
+
+What a Failure carries: `reason`, text for a person, and `detail`, optional JSON for a machine
+reader. The input of `fail()` and the output of a run that ends `failed`.
+
+**Fields**
+
+- `reason`: `string`
+- `detail` (optional): `unknown`

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

@@ -0,0 +1,37 @@
+---
+title: FileBody
+description: "`file(path, { segments?, contentType? })`: a Worktree file as an `http` body."
+---
+
+# `FileBody`
+
+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 FileBody<S extends z.ZodType | undefined = undefined> = {
+  readonly file: {
+    readonly path: FromInput<S, string>;
+    readonly segments?: FromInput<S, readonly string[]>;
+    readonly contentType?: string;
+  };
+};
+```
+
+`file(path, { segments?, contentType? })`: a Worktree file as an `http` body.
+
+**Fields**
+
+- `file`: `object`
+
+  - `path`: `FromInput<S, string>`
+
+    The file, relative to the Worktree that `worktree` of the Effect's input names, or to `/work`
+    in a Workspace with no Repo Slot.
+  - `segments` (optional): `FromInput<S, readonly string[]>`
+
+    Path segments that jr2 adds to the end of the url, as `path` of `request` does for a json
+    or text body.
+  - `contentType` (optional): `string`
+
+    The content type of the body. Write it or a `content-type` header, not both. With neither,
+    it is `application/octet-stream`.

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

@@ -0,0 +1,14 @@
+---
+title: FramePath
+description: "A Turn's Frame in a Workspace with the Repo Slots `S`."
+---
+
+# `FramePath`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type FramePath<S extends string> = WorktreePath<S> | "/work";
+```
+
+A Turn's Frame in a Workspace with the Repo Slots `S`.

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

@@ -0,0 +1,14 @@
+---
+title: FromInput
+description: "A value of a file body's part: as written, or from the Effect's input."
+---
+
+# `FromInput`
+
+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 FromInput<S, T> = T | ((input: S extends z.ZodType ? z.infer<S> : void) => T);
+```
+
+A value of a file body's part: as written, or from the Effect's input.

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

@@ -0,0 +1,56 @@
+---
+title: HostInjectedInput
+description: The fields that jr2 adds to the input of the Machine that a run starts, beside the input that the caller sent.
+---
+
+# `HostInjectedInput`
+
+Type, in `@jr2/orchestrator/src/vocabulary.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Machine and events.
+
+```ts
+type HostInjectedInput = { instanceId: string };
+```
+
+The fields that jr2 adds to the input of the Machine that a run starts, beside the input that
+the caller sent. Today it is one field: `instanceId`, an id that jr2 makes for the run.
+
+Add it to the type of your root Machine's input when the Machine reads it:
+`HostInjectedInput & RunInput`. Do not put it in the `input` schema that a run starts with. No
+caller sends it. jr2 writes it over any value that a caller sends.
+
+Only the root Machine of a run gets it. A Machine that another Machine invokes gets the input
+that its parent gives it. A `workspace()` passes its input to its body, so the body of a root
+`workspace()` gets it too: `Workspaced<HostInjectedInput & RunInput, "app">`. For example, a cut
+can name a branch for each run: `` branch: `fix/${context.instanceId}` ``.
+
+It is not the run id. Use it, for example, to give each run a branch of its own.
+
+**Fields**
+
+- `instanceId`: `string`
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { jr2Setup, type HostInjectedInput } from "@jr2/orchestrator";
+
+const runInput = z.object({ ticket: z.string() });
+type Input = HostInjectedInput & z.infer<typeof runInput>;
+
+export const machine = jr2Setup({
+  types: {} as { input: Input; context: Input; output: { run: string; ticket: string } },
+}).createMachine({
+  id: "ticket",
+  input: runInput,
+  context: ({ input }) => input,
+  initial: "done",
+  states: { done: { type: "final" } },
+  output: ({ context }) => ({ run: context.instanceId, ticket: context.ticket }),
+});
+```
+
+**See also**
+
+- [Write a Workflow](../../guides/write-a-workflow.md)
+- [ADR-0033: A Machine declares the input that starts it](../decisions/0033-a-machine-declares-the-input-that-starts-it.md)

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

@@ -0,0 +1,104 @@
+---
+title: HttpDefinition
+description: "An `http` Effect's definition."
+---
+
+# `HttpDefinition`
+
+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 HttpDefinition<S extends z.ZodType | undefined = undefined> = {
+  method: HttpMethod;
+  url: string | Text | typeof open;
+  headers?: Readonly<Record<string, string | Text>>;
+  auth?: { readonly bearer: Secret } | { readonly basic: { user: Text; password: Text } } | Text;
+  input?: S;
+  request?: (input: S extends z.ZodType ? z.infer<S> : void) => HttpRequestParts;
+  body?: FileBody<S>;
+  timeout?: Duration;
+  maxBody?: number;
+  idempotent?: boolean;
+};
+```
+
+An `http` Effect's definition.
+
+**Fields**
+
+- `method`: [`HttpMethod`](type-httpmethod.md)
+
+  The HTTP method: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`. It refuses
+  another: `http({ method: "<method>" }): the method is one of GET, HEAD, POST, PUT, PATCH,
+  DELETE, OPTIONS`.
+- `url`: `string | Text | typeof open`
+
+  The url: `http://` or `https://`, then a literal host. No input, param or Effect secret can
+  change where the call goes. An Effect secret can be only in the path:
+  `` text`https://api.telegram.org/bot${secret("tg")}/sendMessage` ``.
+
+  Or `open`: a packaged Machine that cannot know the host leaves the url Open, and the composer
+  binds it one time with `customize(machine, { effects: { <slot>: { url } } })`.
+
+  It refuses:
+  - a scheme or host that is not literal: `` http({ url }): the url is an http:// or https:// url
+    whose scheme and host are literal — a secret may sit only in its path, after a "/":
+    text`https://api.example.com/bot${secret("tg")}/send` (ADR-0068) ``
+  - an Effect secret after `?` or `#`: `` http({ url }): secret("<name>") sits in the url's query
+    or fragment — a secret may sit only in its path; send it in `auth` or a header instead:
+    headers: { "x-api-key": text`${secret("...")}` } (ADR-0068) ``
+  - a host that is not a host: `http({ url }): "<scheme>://<host>" is not a host`
+  - a user name or password in the url: ``http({ url }): the url carries userinfo — use `auth` ``
+- `headers` (optional): `Readonly<Record<string, string | Text>>`
+
+  Headers that are the same for each run. Each name is lowercase. A value is a string, or a
+  `text` with an Effect secret.
+
+  It refuses:
+  - a name that is not lowercase, or that frames or routes the request (`host`,
+    `content-length`, `transfer-encoding`, `connection`, `upgrade`, `te`, `trailer`,
+    `keep-alive`, `proxy-*`): `http({ headers }): "<name>" is not a header an Effect sets — a
+    lowercase name that does not frame or route the request (ADR-0068)`
+  - an `authorization` header beside `auth`: ``http({ headers }): "authorization" is set by
+    `auth` — write one of them``
+- `auth` (optional): `{ readonly bearer: Secret; } | { readonly basic: { user: Text; password: Text; }; } | Text`
+
+  The `Authorization` header: `bearer(secret("x"))`, `basic(user, password)`, or a `text` that
+  is the whole value.
+- `input` (optional): `S`
+
+  The zod schema of the input of the Effect: what the `input` of the `invoke`, or `fromPick`,
+  gives it. jr2 parses the input with it before the call. When it starts, input that does not
+  agree with it makes the Effect fail (its `onError` route): `http "<slot>": its input does not
+  match the definition's input schema — <path>: <message>`, one `<path>: <message>` for each
+  problem, joined by `; `.
+- `request` (optional): `(input: S extends z.ZodType ? z.infer<S> : void) => HttpRequestParts`
+
+  A function that makes the part of the request that changes for each run, from the input:
+  `path` segments, and a `json` or `text` body. It cannot change the host, a header or an
+  Effect secret. Do not write it beside `body`.
+- `body` (optional): `FileBody<S>`
+
+  A Worktree file as the body: `file(path, { segments?, contentType? })`. The Effect then
+  runs in the Sandbox Effector of its Workspace. Under a Workspace with Repo Slots, the invoke's
+  input names a Worktree that a cut of this run made, in `worktree`; with none, it refuses when
+  it starts: ``http "<slot>" reads a Worktree file, under a Workspace with Repo Slots, and its
+  input names no `worktree` ``. Do not write `request` beside it: the `segments`
+  of `file` are the path. It refuses another body: ``http({ body }): a body is file(path, {
+  segments?, contentType? }) — json and text come from `request` ``.
+- `timeout` (optional): [`Duration`](type-duration.md)
+
+  How long jr2 waits for the answer: a number and a unit, such as `"30s"` or `"2m"`. Default
+  `"30s"`. With no answer in that time, the output is `unknown`. It refuses a value that is not
+  a positive duration: `http: timeout "<timeout>" is not a positive duration (like "30s",
+  "2m")`.
+- `maxBody` (optional): `number`
+
+  The largest number of bytes of a text response body that the output keeps. Default 65536.
+  When jr2 cuts the body, `truncated` is `true`. It refuses a value that is not a positive whole
+  number: `http({ maxBody }): a positive number of bytes`.
+- `idempotent` (optional): `boolean`
+
+  `true` when it is safe to send the call two times: it has its own idempotency key, or it only
+  reads. Default `false`. After an Orchestrator restart, jr2 cannot always tell if the call went
+  out. Then it sends an idempotent call again, and gives any other call the output `unknown`.

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

@@ -0,0 +1,20 @@
+---
+title: HttpFileInput
+description: The input of an `http` Effect with a Worktree file as its body.
+---
+
+# `HttpFileInput`
+
+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 HttpFileInput<S> = (S extends z.ZodType ? z.infer<S> : unknown) & { worktree?: AnyWorktreePath };
+```
+
+The input of an `http` Effect with a Worktree file as its body. Under a Workspace with Repo
+Slots, `worktree` names the Worktree. In a Workspace with no Repo Slot, the input has no
+`worktree`, and the path is relative to `/work`.
+
+**Fields**
+
+- `worktree` (optional): [`AnyWorktreePath`](type-anyworktreepath.md)

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

@@ -0,0 +1,12 @@
+---
+title: HttpInput
+description: A type that the Authoring surface names.
+---
+
+# `HttpInput`
+
+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 HttpInput<S> = S extends z.ZodType ? z.infer<S> : void;
+```

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

@@ -0,0 +1,14 @@
+---
+title: HttpMethod
+description: "The method of an `http` Effect: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`."
+---
+
+# `HttpMethod`
+
+Type, in `@jr2/orchestrator/src/effector-wire.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 HttpMethod = z.infer<typeof HttpMethodShape>;
+```
+
+The method of an `http` Effect: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`.

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

@@ -0,0 +1,12 @@
+---
+title: HttpOpenParts
+description: A type that the Authoring surface names.
+---
+
+# `HttpOpenParts`
+
+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 HttpOpenParts<U, A, H> = (U extends typeof open ? "url" : never) | OpenSecretIn<A | ValuesOf<H>>;
+```