@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/reference/authoring-surface.md

@@ -5,193 +5,134 @@ description: "Every name that @jr2/orchestrator exports from its root, by group,
 
 # Authoring surface
 
-The [Authoring surface](glossary.md#authoring-surface) is every name that `@jr2/orchestrator` exports from its root, and nothing else: a workflow module and `jr2.config.ts` import only these names. The groups and their order are those of the root's `src/index.ts`. This page gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in `authoring-surface/`, with the file that declares it, its signature, and its TSDoc.
+The [Authoring surface](glossary.md#authoring-surface) is every name that `@jr2/orchestrator` exports from its root, and nothing else: a workflow module and `jr2.config.ts` import only these names. The groups and their order are those of the root's `src/index.ts`. This page gives each group its description and its names. Each group has a page of its own, in `authoring-surface/`, which gives each name of the group its kind and the first sentence of its TSDoc. Each name has a page of its own, in the same folder, with the file that declares it, its signature, and its TSDoc.
 
 ## Machine and events
 
 The setup a workflow writes its Machine with, the events its parties send, and the guard that makes a writing decline other senders ([ADR-0011](decisions/0011-workflow-defined-events.md), [ADR-0015](decisions/0015-authoring-surface-absorbs-the-mechanism.md)).
 
-- [`defineEvent`](authoring-surface/defineevent.md) (function): Define one workflow event: an event that an Agent or the caller of a Gate may send into your Machine.
-- [`jr2Setup`](authoring-surface/jr2setup.md) (function): Set up a Machine that takes workflow events: the jr2 form of xstate's `setup()`.
-- [`sentBy`](authoring-surface/sentby.md) (function): A guard that is true for an event that one party sent, and false for an event that another party sent: `guard: sentBy("coder")`.
-- [`HostInjectedInput`](authoring-surface/type-hostinjectedinput.md) (type): The fields that jr2 adds to the input of the Machine that a run starts, beside the input that the caller sent.
+- Page: [Machine and events](authoring-surface/group-machine-and-events.md)
+- Names: [`defineEvent`](authoring-surface/defineevent.md), [`jr2Setup`](authoring-surface/jr2setup.md),
+  [`sentBy`](authoring-surface/sentby.md), [`HostInjectedInput`](authoring-surface/type-hostinjectedinput.md)
+
+## Gates
+
+A Gate slot hears a Hook ([ADR-0011](decisions/0011-workflow-defined-events.md)).
+
+- Page: [Gates](authoring-surface/group-gates.md)
+- Names: [`gate`](authoring-surface/gate.md), [`Delivered`](authoring-surface/type-delivered.md),
+  [`GateLook`](authoring-surface/type-gatelook.md), [`GateOutcome`](authoring-surface/type-gateoutcome.md),
+  [`GateReply`](authoring-surface/type-gatereply.md)
 
 ## Failure
 
 The Part a Machine invokes to fail its run, and the guard that tells a Failure from a defect in an `onError` ([ADR-0073](decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)).
 
-- [`fail`](authoring-surface/fail.md) (function): Fail the run: the Part a Machine invokes to end work that did not succeed.
-- [`isFailure`](authoring-surface/isfailure.md) (function): Is this error a Failure, which a state invoked `fail` to make?
+- Page: [Failure](authoring-surface/group-failure.md)
+- Names: [`fail`](authoring-surface/fail.md), [`isFailure`](authoring-surface/isfailure.md)
 
 ## Agents
 
 An Agent slot and the definition it carries ([ADR-0028](decisions/0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md), [ADR-0049](decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md)).
 
-- [`agent`](authoring-surface/agent.md) (function): Make an Agent: an actor slot that runs one Turn of a model each time a state invokes it.
-- [`AgentDefinition`](authoring-surface/type-agentdefinition.md) (type): An Agent's definition: which model it runs, its instructions, and what it may do to the Workspace.
-- [`ThinkingLevel`](authoring-surface/type-thinkinglevel.md) (type): How hard the model thinks before it answers: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"` or `"xhigh"`.
+- Page: [Agents](authoring-surface/group-agents.md)
+- Names: [`agent`](authoring-surface/agent.md), [`AgentDefinition`](authoring-surface/type-agentdefinition.md),
+  [`AgentMcpServer`](authoring-surface/type-agentmcpserver.md),
+  [`ThinkingLevel`](authoring-surface/type-thinkinglevel.md)
 
 ## Workspaces and Repos
 
 A Sandbox and the Repo Slots it binds ([ADR-0012](decisions/0012-workspace-wrapper-machine.md), [ADR-0051](decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md)).
 
-- [`workspace`](authoring-surface/workspace.md) (function): Run a body Machine in a Sandbox: a pod of its own, with a Worktree of each Repo Slot on one branch.
-- [`Workspaced`](authoring-surface/type-workspaced.md) (type): The input of a `workspace()` body: the run input, plus `workspace`, the handles that the Workspace adds (`workspace.repos`, `workspace.branch`, `workspace.review`).
-- [`Binding`](authoring-surface/type-binding.md) (type): The repository of a Repo Slot: `{ url, ref }`.
-- [`RepoSlot`](authoring-surface/type-reposlot.md) (type): The value of one Repo Slot in `workspace({ repos })`.
+- Page: [Workspaces and Repos](authoring-surface/group-workspaces-and-repos.md)
+- Names: [`workspace`](authoring-surface/workspace.md), [`Workspaced`](authoring-surface/type-workspaced.md),
+  [`Binding`](authoring-surface/type-binding.md), [`RepoSlot`](authoring-surface/type-reposlot.md)
 
 ## Effects
 
-Work a Machine does outside itself, as an actor slot ([ADR-0067](decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md), [ADR-0068](decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md), [ADR-0071](decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)), and what an author writes between a pick and that work.
-
-- [`arg`](authoring-surface/arg.md) (constant): Mark one argv entry of a `command` that the input of the Effect fills.
-- [`CommandOutput`](authoring-surface/type-commandoutput.md) (type): The output of a `command` Effect: what the `onDone` of its state gets as `event.output`.
-- [`command`](authoring-surface/command.md) (function): Make a `command` Effect: an actor slot that runs one program in the Workspace's Sandbox when a state invokes it.
-- [`basic`](authoring-surface/basic.md) (function): Make the `auth` of an `http` Effect that sends `Authorization: Basic <value>`, where the value is the base64 of `user:password`.
-- [`bearer`](authoring-surface/bearer.md) (function): Make the `auth` of an `http` Effect that sends `Authorization: Bearer <value>`, with the value of an Effect secret.
-- [`file`](authoring-surface/file.md) (function): Make a Worktree file the body of an `http` Effect: `body: file("dist/report.pdf")`.
-- [`http`](authoring-surface/http.md) (function): Make an `http` Effect: a call to a URL, with Effect secrets that the Agent never reads.
-- [`secret`](authoring-surface/secret.md) (function): Name an Effect secret: `secret("jira")`.
-- [`text`](authoring-surface/text.md) (function): Make a string from literal text and Effect secrets, as a tagged template: `` text`Token ${secret("x")}` ``.
-- [`HttpOutput`](authoring-surface/type-httpoutput.md) (type): The output of an `http` Effect: what the `onDone` of its state gets as `event.output`.
-- [`push`](authoring-surface/push.md) (function): Make a `push` Effect: it pushes the branch of the Workspace to the Binding of its Repo Slot.
-- [`PushOutput`](authoring-surface/type-pushoutput.md) (type): The output of a `push` Effect: what the `onDone` of its state gets as `event.output`.
-- [`dispatch`](authoring-surface/dispatch.md) (function): Make a `dispatch` Effect: it starts a run of a Workflow.
-- [`DispatchOutput`](authoring-surface/type-dispatchoutput.md) (type): The output of a `dispatch` Effect.
-- [`answer`](authoring-surface/answer.md) (function): Set what the Agent reads when jr2 answers its pick.
-- [`fromPick`](authoring-surface/frompick.md) (function): Make the `input` of the invoke of a state that a pick enters: the params of the pick go to the input of the invoked actor by name.
-- [`paramsOf`](authoring-surface/paramsof.md) (function): Read the params of a pick from the event that entered the state.
+Work a Machine does outside itself, as an actor slot ([ADR-0067](decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md), [ADR-0068](decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md), [ADR-0071](decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md), [ADR-0079](decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)), and what an author writes between a pick and that work.
+
+- Page: [Effects](authoring-surface/group-effects.md)
+- Names: [`arg`](authoring-surface/arg.md), [`CommandOutput`](authoring-surface/type-commandoutput.md),
+  [`LaterOutcome`](authoring-surface/type-lateroutcome.md), [`command`](authoring-surface/command.md),
+  [`basic`](authoring-surface/basic.md), [`bearer`](authoring-surface/bearer.md), [`file`](authoring-surface/file.md),
+  [`http`](authoring-surface/http.md), [`secret`](authoring-surface/secret.md), [`text`](authoring-surface/text.md),
+  [`HttpOutput`](authoring-surface/type-httpoutput.md), [`push`](authoring-surface/push.md),
+  [`PushOutput`](authoring-surface/type-pushoutput.md), [`branchName`](authoring-surface/branchname.md),
+  [`isReady`](authoring-surface/isready.md), [`readyOf`](authoring-surface/readyof.md),
+  [`worktree`](authoring-surface/worktree.md), [`AnyFramePath`](authoring-surface/type-anyframepath.md),
+  [`AnyWorktreePath`](authoring-surface/type-anyworktreepath.md), [`FramePath`](authoring-surface/type-framepath.md),
+  [`WorktreeFound`](authoring-surface/type-worktreefound.md),
+  [`WorktreeInput`](authoring-surface/type-worktreeinput.md),
+  [`WorktreeOptions`](authoring-surface/type-worktreeoptions.md),
+  [`WorktreeOutput`](authoring-surface/type-worktreeoutput.md),
+  [`WorktreePath`](authoring-surface/type-worktreepath.md), [`WorktreeReady`](authoring-surface/type-worktreeready.md),
+  [`WorktreeRefused`](authoring-surface/type-worktreerefused.md), [`dispatch`](authoring-surface/dispatch.md),
+  [`DispatchOutput`](authoring-surface/type-dispatchoutput.md), [`mcp`](authoring-surface/mcp.md),
+  [`McpOptions`](authoring-surface/type-mcpoptions.md), [`McpCallOutput`](authoring-surface/type-mcpcalloutput.md),
+  [`McpOutput`](authoring-surface/type-mcpoutput.md), [`McpReadOutput`](authoring-surface/type-mcpreadoutput.md),
+  [`answer`](authoring-surface/answer.md), [`fromPick`](authoring-surface/frompick.md),
+  [`paramsOf`](authoring-surface/paramsof.md)
+
+## Steering
+
+The Machine's free text to one of its Agents, which the Agent hears once ([ADR-0002](decisions/0002-duplex-streaming-actor.md)).
+
+- Page: [Steering](authoring-surface/group-steering.md)
+- Names: [`steer`](authoring-surface/steer.md)
 
 ## Composition
 
 A part left Open, a Machine's parts retuned, a Pool over a Source ([ADR-0017](decisions/0017-pool-over-a-source-port.md), [ADR-0049](decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md), [ADR-0054](decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md), [ADR-0060](decisions/0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md)).
 
-- [`open`](authoring-surface/open.md) (constant): Leave a part of a Machine Open: for the Instance that registers the Machine to bind with `customize()`.
-- [`customize`](authoring-surface/customize.md) (function): Retune the parts that a Machine carries, without a change to the module that exports it.
-- [`Customize`](authoring-surface/type-customize.md) (type): The parts of one Machine that `customize()` can retune: its Agents, its Open Effects, the Machines it composes, and the Sandbox of its `workspace()`.
-- [`EffectBinding`](authoring-surface/type-effectbinding.md) (type): The values that bind the Open parts of one Effect.
-- [`Size`](authoring-surface/type-size.md) (type): The Size of a Workspace: the most memory and cpu that its whole Sandbox can use.
-- [`UserContainer`](authoring-surface/type-usercontainer.md) (type): The User Container in its object form: its image, and its part of the Workspace's Size.
-- [`pool`](authoring-surface/pool.md) (function): Make a Pool: a Machine that runs one worker Machine for each item that a Source gives, with at most `cap` workers at once.
-- [`source`](authoring-surface/source.md) (function): Declare a Source: where a `pool()` gets its work items, one at a time.
+- Page: [Composition](authoring-surface/group-composition.md)
+- Names: [`open`](authoring-surface/open.md), [`customize`](authoring-surface/customize.md),
+  [`Customize`](authoring-surface/type-customize.md), [`EffectBinding`](authoring-surface/type-effectbinding.md),
+  [`Size`](authoring-surface/type-size.md), [`UserContainer`](authoring-surface/type-usercontainer.md),
+  [`carry`](authoring-surface/carry.md), [`pool`](authoring-surface/pool.md), [`reread`](authoring-surface/reread.md),
+  [`skip`](authoring-surface/skip.md), [`source`](authoring-surface/source.md),
+  [`PoolNextInput`](authoring-surface/type-poolnextinput.md), [`SourceReply`](authoring-surface/type-sourcereply.md),
+  [`SourceVerdict`](authoring-surface/type-sourceverdict.md)
 
 ## Charts
 
 The Open body a Chart wrapper places in `actors`, and the grammar a planner's pick declares, whole or narrowed to one wrapper ([ADR-0070](decisions/0070-a-machine-lends-its-parts-to-a-chart.md)).
 
-- [`openBody`](authoring-surface/openbody.md) (function): Make an Open body: the actor slot that a Chart binds.
-- [`OpenBodyDeclaration`](authoring-surface/type-openbodydeclaration.md) (type): What an Open body declares: the parts that it lends a Chart, what the Agents of a Chart can have, and the limits of a Chart.
-- [`OpenBodyOutput`](authoring-surface/type-openbodyoutput.md) (type): The output of an Open body.
-- [`chartSchema`](authoring-surface/chartschema.md) (constant): The Chart grammar, as a zod schema.
-- [`chartSchemaFor`](authoring-surface/chartschemafor.md) (function): The Chart grammar for one Open body, as a zod schema.
+- Page: [Charts](authoring-surface/group-charts.md)
+- Names: [`openBody`](authoring-surface/openbody.md),
+  [`OpenBodyDeclaration`](authoring-surface/type-openbodydeclaration.md),
+  [`OpenBodyOutput`](authoring-surface/type-openbodyoutput.md), [`chartSchema`](authoring-surface/chartschema.md),
+  [`chartSchemaFor`](authoring-surface/chartschemafor.md)
 
 ## Config
 
 `jr2.config.ts`, the deployment facts a Machine cannot carry ([ADR-0050](decisions/0050-what-code-names-config-declares-what-the-cli-names-discovery-finds.md)).
 
-- [`defineConfig`](authoring-surface/defineconfig.md) (function): Declare the config of an Instance: the default export of `jr2.config.ts`.
-- [`JR2Config`](authoring-surface/type-jr2config.md) (type): The shape of `jr2.config.ts`: the deployment facts of an Instance, which a Machine cannot carry.
+- Page: [Config](authoring-surface/group-config.md)
+- Names: [`defineConfig`](authoring-surface/defineconfig.md), [`JR2Config`](authoring-surface/type-jr2config.md),
+  [`McpRemoteServer`](authoring-surface/type-mcpremoteserver.md), [`McpServer`](authoring-surface/type-mcpserver.md),
+  [`McpStdioServer`](authoring-surface/type-mcpstdioserver.md), [`RunsConfig`](authoring-surface/type-runsconfig.md)
 
 ## Types these signatures name
 
 The signature of an export, or a type here, names each of these types. They are not exports of `@jr2/orchestrator`, so a workflow module does not import them by name.
 
-- [`EventSemantics`](authoring-surface/type-eventsemantics.md): How the party that sends an event gets its answer.
-- [`EventAudience`](authoring-surface/type-eventaudience.md): Who may send an event: `"agent"` (an Agent, as a pick from its Menu), `"external"` (the caller of a Gate), or `"any"` (both).
-- [`EventDef`](authoring-surface/type-eventdef.md): A workflow event, as `defineEvent` gives it back: plain, frozen data and a zod schema, safe to import anywhere.
-- [`WorkflowEvent`](authoring-surface/type-workflowevent.md): The type of `event` in a Machine that `jr2Setup` makes: each workflow event in its `events`, and each Mechanism event.
-- [`FailSlot`](authoring-surface/type-failslot.md): The logic `fail()` returns: `failLogic` with the brand the walk reads.
-- [`Failure`](authoring-surface/type-failure.md): A Failure as `isFailure` narrows an error to it: the payload's fields, on the error itself.
-- [`AgentDeclaration`](authoring-surface/type-agentdeclaration.md): What `agent()` takes: an `AgentDefinition`, except that `model` can also be `open`.
-- [`WorkspaceAccess`](authoring-surface/type-workspaceaccess.md): What an Agent may do to the Workspace: `"write"`, `"read"` or `"none"`.
-- [`WorkspaceOptions`](authoring-surface/type-workspaceoptions.md): The options of a `workspace()` that declares the input that starts a run.
-- [`NoSlotWorkspaceOptions`](authoring-surface/type-noslotworkspaceoptions.md): The options of a `workspace()` with no Repo Slot that declares the input that starts a run.
-- [`WithoutEmptyIndex`](authoring-surface/type-withoutemptyindex.md): The fields of the run input `T`.
-- [`PermissiveWorkspaceOptions`](authoring-surface/type-permissiveworkspaceoptions.md): The options of a `workspace()` with no `input`: it starts with any input.
-- [`PermissiveNoSlotWorkspaceOptions`](authoring-surface/type-permissivenoslotworkspaceoptions.md): The options of a `workspace()` with no Repo Slot and no `input`: it starts with any input.
-- [`WorkspaceHandles`](authoring-surface/type-workspacehandles.md): What the body of a `workspace()` gets as `input.workspace`: the path of each Worktree, and the branch.
-- [`ExecOutcome`](authoring-surface/type-execoutcome.md): How an exec ended.
-- [`Unknown`](authoring-surface/type-unknown.md): The output `{ outcome: "unknown", reason }`: the Effect may have acted, and jr2 cannot tell.
-- [`Arg`](authoring-surface/type-arg.md): One entry of a command's argv that the input of the Effect fills, as `arg("name")` makes it.
-- [`CommandOptions`](authoring-surface/type-commandoptions.md): 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.
-- [`CommandInput`](authoring-surface/type-commandinput.md): A command's input: one string per argv slot, and with `pin` the approved commit (`{ sha }`); none when there is neither.
-- [`OpenCommandInput`](authoring-surface/type-opencommandinput.md): The input of a `command(open)`: a string for each `arg()` of the argv that the Instance binds, and with `pin`, the commit (`{ sha }`).
-- [`Secret`](authoring-surface/type-secret.md): What `secret("name")` gives: an Effect secret, by its name in the `secrets` list of `jr2.config.ts`.
-- [`Text`](authoring-surface/type-text.md): What the `text` template gives: a string of literal text and Effect secrets, in order.
-- [`FromInput`](authoring-surface/type-frominput.md): A value of a file body's part: as written, or from the Effect's input.
-- [`FileBody`](authoring-surface/type-filebody.md): `file(path, { slot?, segments?, contentType? })`: a Worktree file as an `http` body.
-- [`HttpDefinition`](authoring-surface/type-httpdefinition.md): An `http` Effect's definition.
-- [`OpenSecret`](authoring-surface/type-opensecret.md): `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).
-- [`PushOptions`](authoring-surface/type-pushoptions.md): The options of `push()`.
-- [`PushInput`](authoring-surface/type-pushinput.md): The input of a `push` Effect: `{ sha }` with `pin`, and `{ message }` with `squash`.
-- [`DispatchDefinition`](authoring-surface/type-dispatchdefinition.md): The definition of a `dispatch` Effect (ADR-0071).
-- [`DispatchInput`](authoring-surface/type-dispatchinput.md): A dispatch's input: the run's body — the slot's schema's type, or any JSON object.
-- [`DispatchOpenParts`](authoring-surface/type-dispatchopenparts.md): The Open part a dispatch definition states: its target, when it is `open`.
-- [`ChainLink`](authoring-surface/type-chainlink.md): One reply since the pick, as the author reads it: an invoked actor's output, typed by its slot (`src`); or an event that answered a state below the Agent's — a Gate's answer, a nested Agent's pick — typed by the Machine's events.
-- [`Quantity`](authoring-surface/type-quantity.md): A Kubernetes quantity: `"2Gi"`, `"1500m"`, `"2"`, or a plain number (`2` cpus, bytes of memory).
-- [`PoolSpec`](authoring-surface/type-poolspec.md): What you pass to `pool()`: where the items come from, how many workers run at once, and what each worker gets.
-- [`SourceSpec`](authoring-surface/type-sourcespec.md): Where a Pool gets its work items: the Source.
-- [`OpenBodyLogic`](authoring-surface/type-openbodylogic.md): The logic `openBody()` returns: actor logic that carries the brand.
-- [`Lends`](authoring-surface/type-lends.md): The parts of the Chart wrapper that a Chart can use, by their keys in `actors`, `guards`, `actions` and `delays`.
-- [`Ceilings`](authoring-surface/type-ceilings.md): The limits that an Open body sets on its Chart.
-- [`ChartText`](authoring-surface/type-charttext.md): The Chart text (ADR-0070).
-- [`Sender`](authoring-surface/type-sender.md): Who delivered an event: an Agent by its slot, or a Gate by its invoke id (ADR-0015).
-- [`FailureInput`](authoring-surface/type-failureinput.md): What a Failure carries: `reason`, text for a person, and `detail`, optional JSON for a machine reader.
-- [`SandboxOptions`](authoring-surface/type-sandboxoptions.md): The options of a `workspace()` that say what its Sandbox is made of and which Repos it clones.
-- [`WorkspaceSpec`](authoring-surface/type-workspacespec.md): What the `spec` of a `workspace()` returns: the branch that the Workspace works on, and two optional fields.
-- [`NoSlotSpec`](authoring-surface/type-noslotspec.md): What the `spec` of a `workspace()` with no Repo Slot returns: only `workGroup`.
-- [`SlotHandles`](authoring-surface/type-slothandles.md): The handles of a Workspace that declares Repo Slots.
-- [`Duration`](authoring-surface/type-duration.md): A length of time: a positive number and a unit, `s`, `m` or `h`.
-- [`CommandEnv`](authoring-surface/type-commandenv.md): 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.
-- [`TextPart`](authoring-surface/type-textpart.md): One part of a `Text`: `{ text }`, literal text, or `{ secret }`, the name of an Effect secret.
-- [`HttpMethod`](authoring-surface/type-httpmethod.md): The method of an `http` Effect: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`.
-- [`HttpRequestParts`](authoring-surface/type-httprequestparts.md): What the `request` of an `http` definition returns: the part of the request that changes for each run.
-- [`NamedSecret`](authoring-surface/type-namedsecret.md): A named secret, never `secret(open)`: where a definition's Open part is a whole that holds a secret — a dispatch's target (ADR-0071) — the secret is bound with it, to a name, so the mark `secret(open)` carries may not be present.
-- [`SourceNextResult`](authoring-surface/type-sourcenextresult.md): What the `next` of a Source resolves to: an item, to claim it; `null`, when no item is ready now; or `{ item, open }`, where `open` is the number of items that exist but are not ready.
-- [`OpenBodySlot`](authoring-surface/type-openbodyslot.md): The brand an Open body slot carries, as `definition` marks an Agent slot (ADR-0049).
-- [`ChartJson`](authoring-surface/type-chartjson.md): Plain JSON.
-- [`ChartEvent`](authoring-surface/type-chartevent.md): An event a Chart mints: its payload is a JSON Schema object, built into zod at admission.
-- [`ChartAgent`](authoring-surface/type-chartagent.md): An Agent a Chart mints: the plain fields of an Agent definition (ADR-0049).
-- [`ChartState`](authoring-surface/type-chartstate.md): A state node.
-- [`ChartValue`](authoring-surface/type-chartvalue.md): A value whose strings may hold `{{<root>.<path>}}` placeholders and whose objects may be `{ "$ref": "<root>.<path>" }`.
-- [`ChartInvoke`](authoring-surface/type-chartinvoke.md): An invoke: a lent Agent, Effect or Machine, a minted Agent, or the kit's `gate` or `fail`.
-- [`ChartTransitions`](authoring-surface/type-charttransitions.md): One transition or a list, in xstate's order.
-- [`ChartAction`](authoring-surface/type-chartaction.md): An action.
-- [`ChartTransition`](authoring-surface/type-charttransition.md): A transition: a target alone, or the object form.
-- [`ChartGuard`](authoring-surface/type-chartguard.md): A guard: a lent guard by name, with or without params, `jr2.sentBy`, `jr2.failure`, or `not`/`and`/`or`.
-
-**Type plumbing.** These types compute a type from the types of a Machine or of its parts. A workflow module does not write them. Each has a page with its declaration:
-
-- [`ToProvidedActor`](authoring-surface/type-toprovidedactor.md)
-- [`MergedActors`](authoring-surface/type-mergedactors.md)
-- [`ToParameterizedObject`](authoring-surface/type-toparameterizedobject.md)
-- [`SentByGuards`](authoring-surface/type-sentbyguards.md)
-- [`AgentLogic`](authoring-surface/type-agentlogic.md)
-- [`BodyAcceptsDoor`](authoring-surface/type-bodyacceptsdoor.md)
-- [`WorkspaceMachine`](authoring-surface/type-workspacemachine.md)
-- [`BodyAcceptsSlots`](authoring-surface/type-bodyacceptsslots.md)
-- [`EffectLogic`](authoring-surface/type-effectlogic.md)
-- [`OpenOf`](authoring-surface/type-openof.md)
-- [`EnvOpenParts`](authoring-surface/type-envopenparts.md)
-- [`OpenEffect`](authoring-surface/type-openeffect.md)
-- [`MarkedIf`](authoring-surface/type-markedif.md)
-- [`HttpInput`](authoring-surface/type-httpinput.md)
-- [`HttpOpenParts`](authoring-surface/type-httpopenparts.md)
-- [`PushWireOutput`](authoring-surface/type-pushwireoutput.md)
-- [`SyncState`](authoring-surface/type-syncstate.md)
-- [`AnswerAction`](authoring-surface/type-answeraction.md)
-- [`AgentSlots`](authoring-surface/type-agentslots.md)
-- [`Reached`](authoring-surface/type-reached.md)
-- [`OpenEffectSlots`](authoring-surface/type-openeffectslots.md)
-- [`BindingOf`](authoring-surface/type-bindingof.md)
-- [`LogicAt`](authoring-surface/type-logicat.md)
-- [`ChildSlots`](authoring-surface/type-childslots.md)
-- [`ChildAt`](authoring-surface/type-childat.md)
-- [`RepoSlotsOf`](authoring-surface/type-reposlotsof.md)
-- [`WorkspaceOf`](authoring-surface/type-workspaceof.md)
-- [`PoolMachine`](authoring-surface/type-poolmachine.md)
-- [`EventFrom`](authoring-surface/type-eventfrom.md)
-- [`ArgNames`](authoring-surface/type-argnames.md)
-- [`OpenSecretMark`](authoring-surface/type-opensecretmark.md)
-
-These names come from a dependency: from `zod`, `z.ZodObject`, `z.infer`, `z.ZodType`; from `xstate`, `MachineContext`, `UnknownActorLogic`, `ParameterizedObject`, `NonReducibleUnknown`, `EventObject`, `MetaObject`, `ActionFunction`, `GuardPredicate`, `DelayConfig`, `SetupReturn`, `AnyStateMachine`, `OutputFrom`, `ProvidedActor`, `AnyActorRef`, `InputFrom`, `PromiseActorLogic`.
+- Page: [Types these signatures name](authoring-surface/group-types-these-signatures-name.md)
+- Types: `EventSemantics`, `EventAudience`, `EventDef`, `WorkflowEvent`, `GateSlot`, `Duration`, `CallerRecord`,
+  `FailSlot`, `Failure`, `AgentDeclaration`, `WorkspaceAccess`, `WorkspaceOptions`, `NoSlotWorkspaceOptions`,
+  `WithoutEmptyIndex`, `PermissiveWorkspaceOptions`, `PermissiveNoSlotWorkspaceOptions`, `WorkspaceHandles`,
+  `ExecOutcome`, `Unknown`, `Arg`, `CommandOptions`, `CommandInput`, `OpenCommandInput`, `Secret`, `Text`, `FromInput`,
+  `FileBody`, `HttpDefinition`, `HttpFileInput`, `OpenSecret`, `PushOptions`, `PushInput`, `NameStart`,
+  `DispatchDefinition`, `DispatchInput`, `DispatchOpenParts`, `McpNotReturned`, `ChainLink`, `SteerArgs`, `Sender`,
+  `Quantity`, `Carry`, `PoolSpec`, `StandingPoolSpec`, `Reread`, `Skip`, `SourceSpec`, `SourceHooks`, `PushSourceSpec`,
+  `ReadSourceSpec`, `OpenBodyLogic`, `Lends`, `Ceilings`, `ChartText`, `DeliveredEvent`, `Caller`, `FailureInput`,
+  `SandboxOptions`, `SlotHandles`, `CommandEnv`, `TextPart`, `HttpMethod`, `HttpRequestParts`, `NamedSecret`,
+  `SenderCallerField`, `SourceNextResult`, `SourceIn`, `OpenBodySlot`, `ChartJson`, `ChartEvent`, `ChartAgent`,
+  `ChartState`, `ChartValue`, `ChartInvoke`, `ChartTransitions`, `ChartAction`, `ChartTransition`, `ChartGuard`
+- Type plumbing: `ToProvidedActor`, `MergedActors`, `ToParameterizedObject`, `BindActors`, `SentByGuards`, `GateHooks`,
+  `EventFrom`, `LookOutput`, `AgentLogic`, `BodyAcceptsDoor`, `WorkspaceMachine`, `DoorlessInput`, `BodyAcceptsSlots`,
+  `EffectLogic`, `OpenOf`, `EnvOpenParts`, `OpenEffect`, `MarkedIf`, `HttpOpenParts`, `HttpInput`, `PushWireOutput`,
+  `SyncState`, `AnswerAction`, `AgentSlots`, `Reached`, `OpenEffectSlots`, `BindingOf`, `LogicAt`, `GateSlots`,
+  `GateBinding`, `GateTypesAt`, `ChildSlots`, `ChildAt`, `RepoSlotsOf`, `WorkspaceOf`, `PoolMachine`,
+  `StandingPoolMachine`, `GateSlotInput`, `GateSlotParts`, `ArgNames`, `WorktreeKey`, `NotWorktreeKeys`,
+  `OpenSecretMark`