@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/reference/decisions/0070-a-machine-lends-its-parts-to-a-chart.md

@@ -49,19 +49,26 @@ their own maintainers, and the escapes shipped in systems that used them were in
   answer into the run), so the Open body lends it whole, `lends.gate: true`, and a body that does not has no `gate` in
   its grammar and refuses one at the door; a lent Gate's ids sit below the body's own actor path, so a Chart cannot take
   the name of its wrapper's Gate. (Measured: with `gate` offered beside one lent Agent, three of five missed second
-  Charts reached for it as a worker.) And it mints its own Agents, because an Agent is five plain fields
+  Charts reached for it as a worker.) And it mints its own Agents, because an Agent is plain fields
   ([ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md)) and the Harness runs whatever definition
-  rides the Turn. A minted Agent's model must be one the Open body allows and the Assembly placed a key for;
-  `workspace: "none"` needs the Instance Harness the Assembly converged. Both are door refusals, never a 401 mid-run. It
-  borrows, by slot name only, every Effect (the url, argv and secret were bound once by the author and the Chart fills
-  only its input slots), every Repo and image, every secret, every child Machine, and every guard, action or delay
-  beyond the generic set. Lending is attenuated by construction; an author who lends
-  `command(["sh", "-c", arg("script")])` has lent a shell, and that is theirs to choose. A lent name may not be dotted,
-  `gate`, `fail`, a generic action's name or an integer, because those are the kit's; the Gate itself is lent as
-  `gate: true`, and the Part that fails the run as `fail: true`
+  rides the Turn. A minted Agent names no MCP server: the Chart grammar refuses `mcp`, because an MCP server with its
+  secret is reach, and MCP tools reach a Chart only through a lent Agent
+  ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)). A
+  minted Agent's model must be one the Open body allows and the Assembly placed a key for; `workspace: "none"` needs the
+  Instance Harness the Assembly converged. Both are door refusals, never a 401 mid-run. It borrows, by slot name only,
+  every Effect (the url, argv, MCP server and tool, and secret were bound once by the author and the Chart fills only
+  its input slots), every Repo and image, every secret, every child Machine, and every guard, action or delay beyond the
+  generic set. Lending is attenuated by construction; an author who lends `command(["sh", "-c", arg("script")])` has
+  lent a shell, and that is theirs to choose. A lent name may not be dotted, `gate`, `fail`, a generic action's name or
+  an integer, because those are the kit's; the Gate itself is lent as `gate: true`, and a Gate slot that hears a Hook
+  ([ADR-0011](0011-workflow-defined-events.md)) is lent by its slot name in `lends.gates`, as an Effect is in
+  `lends.effects`; the door refuses a lent Gate slot whose `delivers` names an event that is not in the Chart's
+  Vocabulary. The Part that fails the run is lent as `fail: true`
   ([ADR-0073](0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)), because the Machine
-  decides which ends a Chart can choose. The guard `jr2.failure`, which tells a Failure from a defect on an `onError`,
-  is in every Chart, as `jr2.sentBy` is: it is a predicate and gives no capability.
+  decides which ends a Chart can choose. The guards `jr2.failure`, which tells a Failure from a defect on an `onError`,
+  and `jr2.ready`, which says that a cut settled `ready`
+  ([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)), are in every Chart, as `jr2.sentBy` is:
+  each is a predicate and gives no capability.
 - **Constants for authority, references for data.** `invoke.src`, guard and action `type`s, delay names and event names
   are constants, checked against the lent set and the Chart's own declarations at admission. Data flows through
   references: a placeholder `{{context.ticket.title}}`, or `{ "$ref": "event.summary" }`, in an invoke's `input`, an
@@ -130,11 +137,14 @@ their own maintainers, and the escapes shipped in systems that used them were in
   briefing names the lent Agents, and a body that allows no model has NO `agents` in its grammar and a briefing that
   says so: a planner reads a field it cannot fill as one to fill (measured: eight of ten first Charts minted under a
   `never` model, and read "must not have additional properties" for it), and a Chart that brings `agents` anyway reads
-  at the door why there is none. And the Agent's surface MARKS a pick whose parameter is a Chart with that grammar's
-  briefing (`SurfaceEvent.briefing`, by schema identity), so the Harness says the text in the Turn part, right before
-  "Allowed now", on every Turn where that pick is Allowed, and on a restatement that opens it
-  ([ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)). Nowhere else: the standing Briefing stays
-  Chart-agnostic, the tools block stays the same bytes on every Turn
+  at the door why there is none. The briefing of a body that lends an Effect says how a Chart works under Repo Slots:
+  work happens in a Worktree; a lent cut takes a `path` of `/work/<slot>/<name>` and a `branch`, and `<name>` is not the
+  branch; its `onDone` has an edge with the guard `jr2.ready` and an edge with no guard, for a refused cut; and that one
+  literal path is the `cwd` of each Turn and the `worktree` of each Effect there. And the Agent's surface MARKS a pick
+  whose parameter is a Chart with that grammar's briefing (`SurfaceEvent.briefing`, by schema identity), so the Harness
+  says the text in the Turn part, right before "Allowed now", on every Turn where that pick is Allowed, and on a
+  restatement that opens it ([ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)). Nowhere else: the
+  standing Briefing stays Chart-agnostic, the tools block stays the same bytes on every Turn
   ([ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)), and a seat whose Menu
   holds no Chart pick reads not a word of it. The cost is the author's to scope: a seat whose Menu holds a Chart pick
   carries the grammar as cached tool parameters on every Turn, so an author who wants a planner that only sometimes
@@ -167,10 +177,9 @@ their own maintainers, and the escapes shipped in systems that used them were in
   token, not the publish token, because a Chart is data and cannot reach the process, which is the whole point of this
   decision; it lives on the Orchestrator's volume at `.jr2/charts/<wrapper>/<name>.chart.json` beside the Assemblies,
   written durably, and survives restarts. A live run holds its Chart through the text in its own snapshot, so a `DELETE`
-  while a run is live answers at once and the run goes on. It lists in `jr2 runs` and the Console with its origin shown:
-  `jr2 runs` keeps its result, the live runs, and prints the listing beside it as activity, with `--workflows` to make
-  the listing the result ([ADR-0009](0009-cli-and-instance-interface.md)); there is no verb for `PUT` or `DELETE`, an
-  MCP or `curl` is the client. `GET /workflows` lists each wrapper with its Charts inside its entry, not beside it, and
+  while a run is live answers at once and the run goes on. It lists in `jr2 workflows` and the Console with its origin
+  shown ([ADR-0009](0009-cli-and-instance-interface.md)); there is no verb for `PUT` or `DELETE`, an MCP or `curl` is
+  the client. `GET /workflows` lists each wrapper with its Charts inside its entry, not beside it, and
   `GET /workflows/<wrapper>` carries each Open body's declaration. So a Workflow is one of three things: a Machine from
   the Assembly, a Chart file from the Assembly, or a runtime Chart, and the last two are children of the first. **There
   is no collision rule between a Machine and a Chart**: a Machine's name is a filename stem and holds no slash, a
@@ -206,13 +215,14 @@ their own maintainers, and the escapes shipped in systems that used them were in
   above. The minted Agents: every model against the allowed list and the placed keys, every Workspace access against the
   allowed set. The structure: no `always` cycle without a guard, through parallel regions and history too; no `onDone`
   on an Agent invoke, because a Turn never settles by itself, it ends on a pick in `on`; no Agent state that nothing can
-  end; no parallel state at or below an Agent's. An Agent state of a Chart needs no `agent.fault` route. A state of a
-  Machine needs one ([ADR-0074](0074-an-unrouted-mechanism-event-is-refused-at-load-and-faults-the-run.md)). An
-  `agent.fault` that no transition of the Chart takes goes, unchanged, to the Machine that invoked the Open body, and
-  that Machine's `agent.fault` route takes it, as it takes the fault of an Agent of its own. So a Machine that invokes
-  an Open body that can run an Agent needs the route too, on that state or above it. A route in the Chart stays legal,
-  and it can read `{{event.reason}}`. The wrapper is the right place: a Chart under a body that lends no `fail` has no
-  correct end for a fault, because a final state means `done`
+  end; no parallel state at or below an Agent's; no Agent in two states that can be active together. An Agent state of a
+  Chart needs no `agent.fault` route. A state of a Machine needs one
+  ([ADR-0074](0074-an-unrouted-mechanism-event-is-refused-at-load-and-faults-the-run.md)). An `agent.fault` that no
+  transition of the Chart takes goes, unchanged, to the Machine that invoked the Open body, and that Machine's
+  `agent.fault` route takes it, as it takes the fault of an Agent of its own. So a Machine that invokes an Open body
+  that can run an Agent needs the route too, on that state or above it. A route in the Chart stays legal, and it can
+  read `{{event.reason}}`. The wrapper is the right place: a Chart under a body that lends no `fail` has no correct end
+  for a fault, because a final state means `done`
   ([ADR-0073](0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)) and a state that waits
   holds the run until the wall clock. So the briefing does not teach the route, and the grammar's fragment does not show
   it. And two checks that stand in for the types a Chart does not have. **Dataflow**: every reference a Chart makes,
@@ -224,12 +234,17 @@ their own maintainers, and the escapes shipped in systems that used them were in
   is refused. The fields a Chart declares are its types. **Lent input shapes**: an Effect carries an `input` schema and
   an Agent's Turn input is a fixed key set (`prompt`, `cwd`, `continue`, `model`, `thinkingLevel`, no placement), so the
   literal parts of a Chart's `input` objects are validated at the door and the resolved object again at invoke time,
-  where a failure is that invoke's error and never a mid-Turn surprise. Last, the door compiles the Chart as the body
-  would: `jr2Setup`'s own refusals (less its `agent.fault` refusal), and the load warnings a hand-written Machine gets
-  (an unentered mode), are refusal lines for a Chart, because a planner reads a report and nobody reads a warning. A
-  refusal is the body's OUTPUT, `{ outcome: "refused", report }`, routed by the wrapper's `onDone` with a guard on
-  `outcome`, so a wrapper whose `onDone` returns to the planning state hands it to the planner as the output link in its
-  Chain ([ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)): "Chart refused:
+  where a failure is that invoke's error and never a mid-Turn surprise. Then the rules of a Worktree (ADR-0075). Under
+  Repo Slots, a Turn's `cwd` and an Effect's `worktree` are required, and the door refuses a `cwd` that is a slot's
+  folder. A cut lent to a Chart must state `expect`, which is static, so a Chart cannot change it. The door refuses
+  `expect: "existing"` beside a lent force push, because together they let a Chart force-push any existing branch that
+  `default/` does not hold. A Chart's payload has no `pattern`, so a bad branch name reaches the cut, and the cut
+  refuses it. Last, the door compiles the Chart as the body would: `jr2Setup`'s own refusals (less its `agent.fault`
+  refusal), and the load warnings a hand-written Machine gets (an unentered mode), are refusal lines for a Chart,
+  because a planner reads a report and nobody reads a warning. A refusal is the body's OUTPUT,
+  `{ outcome: "refused", report }`, routed by the wrapper's `onDone` with a guard on `outcome`, so a wrapper whose
+  `onDone` returns to the planning state hands it to the planner as the output link in its Chain
+  ([ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)): "Chart refused:
   `src: "linter"` is not a lent actor; lent: coder, reviewer, push", and the planner answers with a corrected Chart. It
   is not the body's error, because a child's error is a defect that never reaches the model (ADR-0067, which stands); at
   the HTTP door it is 422 with the same report. No new mechanism: an Agent reads its children's outputs through the

package/docs/reference/decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md

@@ -48,9 +48,13 @@ composition and does not replace it. The two uses stay two mechanisms.
   the url and the token together, one Open part, with `customize(m, { effects: { task: { target: { url, token } } } })`
   ([ADR-0054](0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)); `secret(open)` inside a
   target is refused, since the whole target is the part. Another Instance may run another Kit version, so the HTTP door
-  is the only contract there. The token is the Instance token, which unlocks all control
-  ([ADR-0032](0032-the-console-unlocks-with-the-instance-token.md)); a start-only token is a token kind of its own and
-  is deferred.
+  is the only contract there. The token is any Caller's credential of the other Instance with `start` for the callee
+  Workflow ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): a named Caller
+  token made for this, or that Instance's Instance token. A `wait` also polls `GET /runs/<id>`, so its token needs
+  `read` for that Workflow too. The start carries the first Caller of the calling run's `startedBy` chain as
+  `onBehalfOf`, in the header `jr2-on-behalf-of`, which the other Instance records and does not check: that Caller's own
+  `onBehalfOf`, else the name that jr2 shows, else `<via>/<name>`. A chain that jr2 started, or a text that is not
+  printable ASCII of at most 256 characters, sends no claim.
 - **Two settlements, `started` by default, and every outcome is output.** `{ outcome: "started", run }` settles when the
   Orchestrator accepts the run; the watcher goes round again. `wait: true` settles
   `{ outcome: "settled", run, status, output }` when that run ends, `status` in the store's own words (`done`, `failed`,
@@ -69,12 +73,12 @@ composition and does not replace it. The two uses stay two mechanisms.
   a DELETE of the Effect ends that poll and never touches the run. No callback from the callee: a callback needs the
   callee to hold its caller's address and a token for it, which inverts the trust. A door refusal is OUTPUT,
   `{ outcome: "refused", status, report }`, with the door's status — 400 for bad input, 404 for a name the current
-  Assembly lacks, 409 for an unrunnable named Chart or a key another Workflow's run holds, 422 for a Chart the door
-  refuses, 413 for a start over the bytes an Effector reads, 0 when the Effector refused it before anything was sent —
-  as a Chart refusal is ([ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md)): the body may have come from a model,
-  and the report must be able to reach it through the Chain. A target no replica could reach is
-  `{ outcome: "unreachable" }`, output, as an `http` Effect's is (ADR-0067): nothing was started. The invoke's error is
-  kept for defects: no run host or Effector, input that fails the slot's schema, a refused or malformed wire.
+  Assembly lacks, 409 for an unrunnable named Chart, 422 for a Chart the door refuses, 413 for a start over the bytes an
+  Effector reads, 0 when the Effector refused it before anything was sent — as a Chart refusal is
+  ([ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md)): the body may have come from a model, and the report must
+  be able to reach it through the Chain. A target no replica could reach is `{ outcome: "unreachable" }`, output, as an
+  `http` Effect's is (ADR-0067): nothing was started. The invoke's error is kept for defects: no run host or Effector,
+  input that fails the slot's schema (when no run has the key, below), a refused or malformed wire.
 - **The two runs are independent.** Cancelling the caller never cancels the callee; the caller's end never ends it;
   leaving the state stops a wait and never the run; the callee's Workspaces are its own. Temporal's parent-close policy
   (`TERMINATE` by default, `REQUEST_CANCEL`, `ABANDON`) exists because a child there is both a run and a child, and its
@@ -89,7 +93,8 @@ composition and does not replace it. The two uses stay two mechanisms.
   `dispatched [{ slot, run, at }]`, the chain's other direction. `jr2 runs` carries `dispatchedBy` after the id,
   `jr2 status` prints `dispatched by:` and `dispatched:` lines, and the Console shows both. The word is **dispatched
   by**. The callee reads nothing of its caller from its input: a Machine that wants to tell its callee something passes
-  it as input like any caller.
+  it as input like any caller. A local dispatch records its caller's run as the callee's `startedBy`,
+  `{ kind: "run", run, slot }`, and `jr2 status` walks that chain to the first Caller (ADR-0078).
 - **A chain of dispatches is unbounded.** A run may dispatch a Workflow that dispatches another, or itself: a run that
   dispatches its own successor and ends is Temporal's continue-as-new, the honest way to keep a watcher's snapshot
   small, and a depth ceiling would refuse it. A runaway chain is a resource problem the cluster owner's quota and
@@ -100,24 +105,45 @@ composition and does not replace it. The two uses stay two mechanisms.
   key, out of band — the `jr2-dispatched-by` header, the `dispatchedBy` record as JSON, never a body field the callee's
   door would have to reserve — and `POST /workflows/<name>/runs` asks the key before anything else, so a re-sent start
   answers its run even when the name would be refused now: 201 with the run for a new one, 200 with
-  `{ runId, instanceId, existing: true }` for a repeat, 409 when a run of ANOTHER Workflow holds the key (the caller
-  asked for one Workflow and would wait on a run of another), 400 when the header does not parse, and 500, never 404,
-  for any other throw, since a foreign caller reads a 404 as "nothing was started" (ADR-0033 as amended). The key lives
-  in the callee's blob, and the store copies it into a `dispatch_effect` column of its own at every save and indexes
-  that, not an expression index over `json_extract`: SQLite's JSON parser refuses a blob nested about a thousand deep,
-  and such an index would fail that row's save and every later open of the volume. A run restore marks `lost` keeps its
-  row and its blob, so its key keeps answering; the weekly sweep
-  ([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-a-week.md)) removes the key with the row, and a re-send
-  after it starts a new run: known, and not guarded. In-process the ledger is consulted directly, through the same start
-  under the same key, with the starts in flight held so two arrivals of one key before the first save are one run. So a
-  dispatch is idempotent whatever its author writes: its intent row says `idempotent: true`, a restore that cannot tell
-  whether its start arrived sends it again under its key with what is left of the bound, the Instance Effector sends a
-  start whose answer was lost again under its key with backoff until the bound, and the Effector's rollout grace is
-  never stretched by a dispatch's wait. Once the answer names the run, the intent row carries it, the Effector's
-  `running` state carries it on the wire, and a restore with it starts nothing: it settles `started` at once, or resumes
-  the wait. Without it a watcher double-starts a run after a restart, which a human notices as two pull requests. What
-  it does not guard: a door at a Kit version before this decision ignores the header, so a re-send to it starts a second
-  run, and neither the Effector nor the preflight can tell. A capability check is named and deferred.
+  `{ runId, instanceId, existing: true }` for a repeat, 200 with `{ existing: false }` for a key-only ask (below) with
+  no run under the key, 400 when a header does not parse, and 500, never 404, for any other throw, since a foreign
+  caller reads a 404 as "nothing was started" (ADR-0033 as amended). **The key is scoped to the callee Workflow**: the
+  store finds a key with the Workflow's name, so the same key in two Workflows is two runs, and a key never answers with
+  a run of another Workflow. A key answers `existing` while its run's row lives, in any status: live, and for
+  `runs.retain` after it ends ([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)). A
+  retry after a failure is then a person's act, not a re-sent start's. The Effect checks the key before it checks its
+  input against the slot's schema, in-process and on the foreign path, as the door does: a start sent again across a
+  change of the callee's door answers `existing`, not an error. In-process it asks the run host for the key before it
+  reads the input, within the slot's bound. On the foreign path, a body that the slot's schema refuses is never sent:
+  the start is a **key-only ask**, the header `jr2-key-only: true` beside `jr2-dispatched-by` and no body, out of band
+  as the key is. The door keeps its order: the scope check (ADR-0078), then the key. With a run under the key it answers
+  `existing`, as for any start; with none it starts nothing and answers 200 with `{ existing: false }`, which a foreign
+  caller cannot read as a refused name (404) or a defect (5xx). The Instance Effector settles that answer as `absent`,
+  an outcome of the wire alone, and the Effect makes it the slot's schema refusal, the invoke's error. So input that
+  fails the slot's schema starts nothing on either path, and a run that its key already started is answered on both. A
+  body that the slot's schema takes goes as before, in one request. This is the same for a first send and for a send
+  again (a restore, a retry): a Pool's hand-over is a first send of a new run's Effect under a key that may already name
+  a run of a callee whose door changed. A `wait` sent again under a key that answers `existing` follows that run, and
+  settles when it ends. **A Pool's worker sends its `itemId` as the key** ([ADR-0017](0017-pool-over-a-source-port.md)),
+  so a Pool's hand-over re-attaches to each live run. An author's own key (`dispatch({ key })`) is not offered now; to
+  add it later breaks nothing. The key lives in the callee's blob (a Pool's `dispatchedBy.key`, else
+  `dispatchedBy.effect`), and the store copies it and the Workflow into columns of their own (`dispatch_effect`,
+  `dispatch_workflow`) at every save and indexes the pair, not an expression index over `json_extract`: SQLite's JSON
+  parser refuses a blob nested about a thousand deep, and such an index would fail that row's save and every later open
+  of the volume. A run restore marks `lost` keeps its row and its blob, so its key keeps answering; the sweep of rows
+  older than `runs.retain` ([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)) removes
+  the key with the row, and a re-send after it starts a new run: known, and not guarded. In-process the ledger is
+  consulted directly, through the same start under the same key, with the starts in flight held so two arrivals of one
+  key before the first save are one run. So a dispatch is idempotent whatever its author writes: its intent row says
+  `idempotent: true`, a restore that cannot tell whether its start arrived sends it again under its key with what is
+  left of the bound, the Instance Effector sends a start whose answer was lost again under its key with backoff until
+  the bound, and the Effector's rollout grace is never stretched by a dispatch's wait. Once the answer names the run,
+  the intent row carries it, the Effector's `running` state carries it on the wire, and a restore with it starts
+  nothing: it settles `started` at once, or resumes the wait. Without it a watcher double-starts a run after a restart,
+  which a human notices as two pull requests. What it does not guard: a door at a Kit version before this decision
+  ignores the header, so a re-send to it starts a second run, and a door that knows the key but not the key-only ask
+  reads one as a start with no body; neither the Effector nor the preflight can tell. A capability check is named and
+  deferred.
 - **`jr2 up` checks what it can see, and the severity follows who owns both sides.** For a same-Instance name the walk
   resolves it in the Assembly and REFUSES a miss, naming the fix: on the host, among the Machines and the Chart files,
   and a slashed name whose wrapper exists but whose Chart the host cannot see is a warning there, since a runtime Chart
@@ -172,7 +198,7 @@ composition and does not replace it. The two uses stay two mechanisms.
 - ADR-0049's "no sub-run" is restated, not reversed: a nested Machine is reached by `import`, never by name; a run that
   starts a run is a `dispatch`, by name, and the two are different uses. ADR-0067 gains the kind and a fourth Placement,
   `orchestrator`. ADR-0068's Instance Effector gains the `dispatch` kind, its stop route stops a dispatch's wait too,
-  and its `running` state carries the run. ADR-0033's door gains an idempotency key.
+  and its `running` state carries the run. ADR-0033's door gains an idempotency key and the key-only ask.
 - The GLOSSARY's **Effect** gains "or starts a run", and `_Avoid_: sub-run, child run, nested run, spawned run` for the
   relation, which is **dispatched by**; its **Effector** and **Instance Effector** entries name the in-process exception
   and the new kind.
@@ -180,4 +206,4 @@ composition and does not replace it. The two uses stay two mechanisms.
   routing of both, without the key.
 - An Open body may lend a `dispatch` slot as it lends any Effect (`lends.effects`), so a Chart can start a run of a
   Workflow its wrapper chose; the Chart fills the body only.
-- Deferred, named: a start-only token; a depth ceiling; a capability check for a door that ignores the key.
+- Deferred, named: a depth ceiling; a capability check for a door that ignores the key; an author's own key.

package/docs/reference/decisions/0072-the-docs-ship-inside-the-kit-and-an-instances-agents-md-indexes-them.md

@@ -15,22 +15,27 @@ Next.js ships the same design: its docs as Markdown inside the `next` package, a
   - **The bundle.** `@jr2/orchestrator` ships `docs/`: every page of the sitemap, the generated Reference, the Glossary
     and the Decisions, as plain Markdown. No site-generator syntax reaches it. It is the main channel for an Assistant.
     Each page is at its slug, such as `concepts/gates.md`, and each ADR is at `reference/decisions/<file>`. An Assistant
-    reads a page with its file tool, which cuts off a long file. So the Authoring surface is two parts:
-    `reference/authoring-surface.md`, a contents page that gives each name its kind and the first sentence of its TSDoc,
-    and `reference/authoring-surface/<anchor>.md`, one page for each export and for each type that a signature names.
-    One page of all the names is about 200 KB, and the contents page is less than 25 KB. No line of the contents page or
-    of an entry page is longer than 1,000 characters, so the type plumbing is a list, not a paragraph. When the contents
-    page passes 25 KB, first make the long first sentences shorter; if it still passes, give each group of the contents
-    page a page of its own, and make the contents page a list of the groups. The first sentence ends at a stop, not at a
-    colon, because the words before a colon often tell nothing alone ("An invoke."). A link to an entry goes to its
-    page. Each of the other generated Reference pages (CLI, config, machines, mechanism events, HTTP API) stays one
-    page. Each is less than 30 KB, the size that one read of a file tool shows, with one exception: the HTTP API page is
-    about 50 KB. It is one page because its routes come first and are less than 30 KB, so one read shows every route;
-    the types of the bodies come after the routes, and an Assistant reads one of them with an offset or by its heading.
-    When the routes pass 30 KB, give the types a page of their own. The alternative, a split of the HTTP API page now,
-    is rejected because a route and the types it names are then on two pages, and one read shows all routes already. The
-    Glossary and the Decisions are not generated, and this rule does not hold them: an ADR can be about 50 KB, and an
-    Assistant reads the one ADR that a page links to.
+    reads a page with its file tool, which cuts off a long file. So the Authoring surface is three parts.
+    `reference/authoring-surface.md` is a contents page that gives each group of the root's `src/index.ts`, and the
+    group of the types that the signatures name, its description and its names.
+    `reference/authoring-surface/group-<title>.md` is one page for each group, which gives each name of the group its
+    kind and the first sentence of its TSDoc. `reference/authoring-surface/<anchor>.md` is one page for each export and
+    for each type that a signature names. The `group-` prefix keeps a group page apart from an entry page, and
+    `docs:build` fails when two pages have one path. One page of all the names is about 200 KB. The contents page and
+    each group page are less than 25 KB, and each entry page is less than 15 KB. On the contents page, a type that a
+    signature names is code with no link, because there are more than a hundred of them; its group page links each one.
+    No line of a contents, group or entry page is longer than 1,000 characters, so the contents page breaks a list of
+    names into lines, and the type plumbing is a list, not a paragraph. When a group page passes 25 KB, first make the
+    long first sentences shorter; if it still passes, divide that group into two groups. The first sentence ends at a
+    stop, not at a colon, because the words before a colon often tell nothing alone ("An invoke."). A link to an entry
+    goes to its page. Each of the other generated Reference pages (CLI, config, machines, Hook kinds, mechanism events,
+    HTTP API) stays one page. Each is less than 30 KB, the size that one read of a file tool shows, with one exception:
+    the HTTP API page is about 50 KB. It is one page because its routes come first and are less than 30 KB, so one read
+    shows every route; the types of the bodies come after the routes, and an Assistant reads one of them with an offset
+    or by its heading. When the routes pass 30 KB, give the types a page of their own. The alternative, a split of the
+    HTTP API page now, is rejected because a route and the types it names are then on two pages, and one read shows all
+    routes already. The Glossary and the Decisions are not generated, and this rule does not hold them: an ADR can be
+    about 50 KB, and an Assistant reads the one ADR that a page links to.
   - **The `AGENTS.md` block.** A compressed index of the bundle, and an instruction in five parts. jr2 is newer than
     your training data, so read the bundled docs before you write a Machine or config. Start with the guide "Write a
     workflow" and the contents page of the Authoring surface. Read one page with each call of the file tool. Run
@@ -63,21 +68,26 @@ Next.js ships the same design: its docs as Markdown inside the `next` package, a
   exists for it. A broken marker pair is reported, and `up` does not change the file.
 - **The Reference is generated from the code wherever the code holds the facts.**
 
-  | Page                                                    | Source                                                 |
-  | ------------------------------------------------------- | ------------------------------------------------------ |
-  | Authoring surface: a contents page, and a page per name | TSDoc on the exports, exactly the root's list          |
-  | `@jr2/machines`                                         | TSDoc on the exports                                   |
-  | `jr2.config.ts`                                         | TSDoc on the `JR2Config` fields                        |
-  | CLI                                                     | a structured command table, which also prints `--help` |
-  | HTTP API                                                | the route table in `http.ts`, made data                |
-  | Mechanism events                                        | the code that defines them                             |
-  | Glossary, Decisions                                     | `GLOSSARY.md` and `docs/adr/`, rendered as they are    |
+  | Page                                                                      | Source                                                         |
+  | ------------------------------------------------------------------------- | -------------------------------------------------------------- |
+  | Authoring surface: a contents page, a page per group, and a page per name | TSDoc on the exports, exactly the root's list                  |
+  | `@jr2/machines`                                                           | TSDoc on the exports                                           |
+  | `@jr2/orchestrator/hooks`                                                 | TSDoc on the exports of each module but `door`, one group each |
+  | `jr2.config.ts`                                                           | TSDoc on the `JR2Config` fields                                |
+  | CLI                                                                       | a structured command table, which also prints `--help`         |
+  | HTTP API                                                                  | the route table in `http.ts`, made data                        |
+  | Mechanism events                                                          | the code that defines them                                     |
+  | Glossary, Decisions                                                       | `GLOSSARY.md` and `docs/adr/`, rendered as they are            |
 
   The TSDoc on an Authoring surface export is written for the author: what it does, what it refuses, what to read next,
   and one example. Maintainer reasoning goes in `//` comments in the body. The packages ship their `.ts` source, so an
   Assistant that follows an import into `node_modules` reads the same text the site shows. The Authoring surface is
   exactly what `@jr2/orchestrator` exports from its root: what the kit's packages share is internal even where it can be
   imported, and `@jr2/machines` is not part of it, because it ships Machines, not names to author with.
+  `@jr2/orchestrator/hooks` is not part of it either, because a Hook kind is a module of its own interface, which a kind
+  from another package imports too
+  ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). Its page leaves out
+  `hook-kinds/door.ts`, which only the Orchestrator reads.
 
 - **`docs:build` assembles the bundle at pack time.** Its inputs are the hand-written pages in `docs/site/`, the
   generated Reference, `GLOSSARY.md`, and `docs/adr/`. It runs in `@jr2/orchestrator`'s `prepack` and before the site

package/docs/reference/decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md

@@ -39,7 +39,7 @@ comment "the run faults rather than lie about a decision", and that run ended `d
   the run holds then, and nor does a Workspace that was stopped in `placing`
   ([ADR-0064](0064-a-workspace-waits-for-capacity.md)): a parent that invokes the same Machine again gives the new
   Workspace the same invoke id, and so the same Sandbox name. That new Workspace takes over the Sandbox and its
-  Worktree, as a restore does, with the work of the failed attempt still in it. To keep the work for a person to read,
+  Worktrees, as a restore does, with the work of the failed attempt still in it. To keep the work for a person to read,
   the Machine waits at a Gate before it fails.
 - **`jr2 run` exits 0 only for `done`.** It exits 1 for every other end: `failed`, `error`, `cancelled`, `lost`,
   `drifted`, and a run that was parked before it settled. Exit code 2 stays the CLI's code for a usage error. The status