@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/concepts/gates.md

@@ -1,13 +1,14 @@
 ---
 title: Gates
-description: How a run waits for an event from a person, the CLI, the Console, a webhook or a CI job.
+description: How a run waits for an event from a person, the CLI, the Console, a Hook or a CI job.
 ---
 
 # Gates
 
 A [Gate](../reference/glossary.md#gate) is an input that a run waits for from outside the run. A person, a CI job or a
-webhook can send it. A state of a [Machine](../reference/glossary.md#machine) opens a Gate when it invokes the `gate`
-actor, and the Gate closes when the state exits. While the Gate is open, a caller can send one of its events.
+[Hook](../reference/glossary.md#hook) can send it. A state of a [Machine](../reference/glossary.md#machine) opens a Gate
+when it invokes the `gate` actor, and the Gate closes when the state exits. While the Gate is open, a caller can send
+one of its events.
 
 ## Why Gates exist
 
@@ -105,7 +106,8 @@ export const machine = jr2Setup({
 ```
 
 You do not import the `gate` actor. `jr2Setup` adds it, and a state invokes it as `invoke: { src: "gate" }`. Its input
-is optional. It can hold `meta`, and an authored `gate` id.
+is optional. It can hold `meta`, and an authored `gate` id. A Gate that hears a Hook is a Gate slot, which you declare
+with `gate({ … })` (see [A Gate that hears a Hook](#a-gate-that-hears-a-hook)).
 
 ### The id
 
@@ -133,29 +135,36 @@ that the run takes from the Gate now. jr2 refuses an event that is not in `accep
 
 ### The meta
 
-`meta` is data for the caller. It tells a person what to decide, and it lets a webhook find the correct Gate. In the
-example, the `review` Gate shows the version and the URL of the CI job. jr2 does not read `meta`.
+`meta` is data for the caller. It tells a person what to decide, and it lets the handler of a Gate slot find the correct
+Gate. In the example, the `review` Gate shows the version and the URL of the CI job. jr2 does not read the `meta` of a
+plain Gate. A Gate slot checks its `meta` against its schema when it opens.
 
 ### The callers
 
-A caller finds the open Gates of a run with [`GET /runs/:runId`](../reference/http-api.md#get-runs-runid). Each Gate
-gives its id, its events with their input schemas, `acceptsNow` and `meta` (see
-[`GateView`](../reference/http-api.md#type-gateview)). Then the caller sends one event, with its input. These callers
-use the same route,
+A caller finds the open Gates of all the live runs that it can answer with
+[`GET /gates`](../reference/http-api.md#get-gates), the oldest first, and the open Gates of one run with
+[`GET /runs/:runId`](../reference/http-api.md#get-runs-runid). Each Gate gives its id, its events with their input
+schemas, `acceptsNow` and `meta` (see [`GateView`](../reference/http-api.md#type-gateview)). Then the caller sends one
+event, with its input. These callers use the same route,
 [`POST /runs/:runId/gates/:gate/events`](../reference/http-api.md#post-runs-runid-gates-gate-events), with the
 [Instance](../reference/glossary.md#instance) token:
 
-- **The [jr2 CLI](../reference/glossary.md#jr2-cli).** [`jr2 status`](../reference/cli.md#status) prints the open Gates
-  of a run under `gates`. [`jr2 send`](../reference/cli.md#send) with `--gate` sends an event to one of them.
-- **The [Console](../reference/glossary.md#console).** When you type the Instance token, the Attention tab shows a card
-  for each open Gate. The card has a form for each event.
-- **A webhook or a CI job.** Any client that can reach the [Orchestrator](../reference/glossary.md#orchestrator), and
-  that holds the Instance token, can send to a Gate. It can call the route, or run `jr2 send` with `--url` and
+- **The [jr2 CLI](../reference/glossary.md#jr2-cli).** [`jr2 gates`](../reference/cli.md#gates) prints the open Gates of
+  all the live runs that you can answer, the oldest first, each with the time when it opened.
+  [`jr2 status`](../reference/cli.md#status) prints the open Gates of one run under `gates`.
+  [`jr2 send`](../reference/cli.md#send) with `--gate` sends an event to one of them.
+- **The [Console](../reference/glossary.md#console).** When you type a token with the `answer` scope, or log in, the
+  Attention tab shows a card for each open Gate of the Workflows of that scope. The card has a form for each event.
+- **A CI job.** Any client that can reach the [Orchestrator](../reference/glossary.md#orchestrator), and that holds a
+  credential with the `answer` scope, can send to a Gate. It can call the route, or run `jr2 send` with `--url` and
   `JR2_TOKEN`.
+- **A Hook.** A Gate slot's handlers turn a delivery of an outside service into one of the Gate's events (see below).
 
-The [Sender](../reference/glossary.md#sender) of the event is the Gate, by its invoke id, and not the person or the
-system behind it. The invoke id is not always the id that a caller uses. [The Menu](the-menu.md) tells how to use the
-Sender.
+The [Sender](../reference/glossary.md#sender) of the event is the Gate, by its invoke id. The invoke id is not always
+the id that a caller uses. The Sender also carries the [Caller](../reference/glossary.md#caller) that answered: `via`,
+`name`, `onBehalfOf` when the Caller gives it, and `checked`, the fields that jr2 verified.
+[The Sender](the-menu.md#the-sender) tells how to use the Sender, and why you must not trust an `onBehalfOf` that
+`checked` does not name.
 
 ### A run that waits
 
@@ -173,7 +182,62 @@ After each answer, the Agent can pick again, so it can ask and get answers with
 on the pick. For example, `guard: ({ context }) => context.replies < 1` allows one question only. A guard that reads
 only the context removes the pick from the [Allowed picks](the-menu.md#allowed-picks).
 
-A Pool that has a `wake` event serves it as a Gate with the id `source` (see [Pools and Sources](pools-and-sources.md)).
+A Pool that has a `wake` event, or a Source that hears a Hook, serves a Gate with the id `source`. A Hook's delivery
+reaches the Source's handlers through it (see [Pools and Sources](pools-and-sources.md#a-hook-reaches-a-source)).
+
+## A Gate that hears a Hook
+
+A [Hook](../reference/glossary.md#hook) checks that a delivery comes from its service, and decides nothing
+([Callers and Hooks](callers-and-hooks.md) tells what the door of a Hook does). A Gate decides what the delivery means
+for its run. Thus a Gate that hears a Hook is an extension of the Gate, and not a second concept. You declare it as a
+Gate slot in `actors`, as `actors: { review: gate({ meta, delivers, hooks, look, reply }) }`, and a state invokes it by
+its key, as `invoke: { src: "review" }`.
+
+- **`meta`** is a zod object. The Gate checks the state's `meta` against it when it opens, and its handlers and its look
+  read the `meta` typed.
+- **`delivers`** lists the events that the handlers and the look can give. An event whose def does not set `audience` is
+  `"external"` here, so an Agent below the Gate does not have it on its Menu. `createMachine` refuses an event of
+  `delivers` that the Gate does not take at the state that invokes it.
+- **`hooks`** has a handler for each [Hook kind](../reference/glossary.md#hook-kind) and event key, such as
+  `github: { "pull_request_review.submitted": handler }`. A delivery goes to each open Gate whose handlers hear its kind
+  and key. The handler compares the payload with the `meta`, and gives one event of `delivers`, or `undefined`. It is
+  pure and synchronous.
+- **`look`** reads the fact that the Gate waits for. It reads once after the Gate opens, again after each restart of the
+  Orchestrator, and every `every` (default `"10m"`) while the Gate is open, until the run takes the event that `until`
+  gives. So a delivery that came before the Gate opened, or that was lost in an outage, does not stop the run. The read
+  is an `http` Effect marked `idempotent: true`, or a promise. A looked event has the Gate as its Sender and no Caller,
+  and the run's feed shows `looked`. `look: "none"` is for a Gate that hears a command, such as `/retry`, which no read
+  can find. A packaged Machine leaves its look `open`, and the composer binds it with
+  `customize(machine, { gates: { <slot>: { look } } })`.
+- **`reply`** gives the text that the person who acted reads, for a kind whose answer a person reads: a Slack command or
+  click, or a Discord interaction. `reply(outcome, { meta, caller })` is pure and synchronous. `outcome.state` is
+  `delivered`, with the event, or `refused`, with the reason. It runs after the run answers. It does not run for a Gate
+  whose handler gave `undefined`, because that Gate was not a target. It runs for every other target, and a handler that
+  threw is one of them: its `outcome` is `refused`, with the reason. It gives plain text or `undefined`. The Hook kind
+  escapes the text and shows it only to the person who acted.
+
+### The answer that a person reads
+
+For a chat command or click, the Hook's door answers 200 with one text in the kind's envelope, not the outcome JSON:
+
+- The door joins the `reply` text of each target. A Source's text comes first, then a Gate's. In each, the order is by
+  Workflow name and then by run id. The door drops an empty text and a text that is the same as one before it. The text
+  of a Source's `skipped` verdict shows only when no other target gave a text.
+- When no target gives a text, the door writes one: for example `Nothing in jr2 waits for this now.`, or that jr2 got
+  the delivery before.
+- Where the door's rules give 429 or 503, the person gets 200, and a line of the text says why. The hook log keeps the
+  status of the rules.
+- The door cuts the text to the limit of the kind (Discord: 2000 characters; Slack: 4000).
+- Slack shows no text in the answer to a click. Thus the door answers the click with an empty 200, and then posts the
+  text to the click's `response_url` through the Instance Effector. A post that fails is a `follow-up` line in
+  [`jr2 hooks <name>`](../reference/cli.md#hooks).
+
+A message that everyone in the channel sees is a change of shared state. Write it as an `http` Effect of the Machine.
+
+A Chart can invoke a Gate slot that its Open body lends in `lends.gates` (see [Charts](charts.md)). The Chart must
+declare each event of the slot's `delivers` in its `events`.
+
+[Answer a Gate from a forge](../guides/answer-a-gate-from-a-forge.md) shows a full example.
 
 ## Rules
 
@@ -189,20 +253,26 @@ A Pool that has a `wake` event serves it as a Gate with the id `source` (see [Po
 - jr2 refuses a second open Gate with the same id in one run.
 - `jr2 up` warns about a Gate above an Agent's state that takes an event that the Agent can also reach. The Gate's
   caller can send the event, and the Agent cannot.
+- `jr2 up` warns about a Gate slot that hears a Hook and has no look and no `after` on its state, and about a look that
+  a package left `open` and that nobody bound. A person can still answer that Gate with `jr2 send`.
+- A Gate slot's handler that throws, or that gives an event that the run does not take now, never faults the run. The
+  Hook's answer names the Gate in `refused`, and the run's feed shows `hook-refused`.
 
 ## Read next
 
-- [Answer a Gate](../guides/answer-a-gate.md)
+- [Answer a Gate](../guides/answer-a-gate.md) and [Answer a Gate from a forge](../guides/answer-a-gate-from-a-forge.md)
 - [Open the Console](../guides/open-the-console.md)
-- [The Menu](the-menu.md), [Pools and Sources](pools-and-sources.md) and [Durable runs](durable-runs.md)
+- [The Menu](the-menu.md), [Callers and Hooks](callers-and-hooks.md), [Pools and Sources](pools-and-sources.md) and
+  [Durable runs](durable-runs.md)
 - Reference: [`jr2 send`](../reference/cli.md#send), [`jr2 status`](../reference/cli.md#status),
   [`GET /runs/:runId`](../reference/http-api.md#get-runs-runid),
   [`POST /runs/:runId/gates/:gate/events`](../reference/http-api.md#post-runs-runid-gates-gate-events),
   [`GateView`](../reference/http-api.md#type-gateview) and [`sentBy`](../reference/authoring-surface/sentby.md)
-- [ADR-0011](../reference/decisions/0011-workflow-defined-events.md): a Gate is an addressable resource on a run
+- [ADR-0011](../reference/decisions/0011-workflow-defined-events.md): a Gate is an addressable resource on a run, and a
+  Gate slot hears a Hook and looks before it waits
 - [ADR-0013](../reference/decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md): an Agent
   cannot send to a Gate, and a send that the run does not take is refused
 - [ADR-0015](../reference/decisions/0015-authoring-surface-absorbs-the-mechanism.md): the position of an `on` key gives
   its event to a Gate or to an Agent
-- [ADR-0032](../reference/decisions/0032-the-console-unlocks-with-the-instance-token.md): the Console sends to a Gate
-  with the Instance token
+- [ADR-0032](../reference/decisions/0032-the-console-unlocks-with-a-callers-credential.md): the Console sends to a Gate
+  with a Caller's credential

package/docs/concepts/machines-and-workflows.md

@@ -160,7 +160,8 @@ jr2 makes three things from the Vocabulary:
 
 - **The Menu of each Agent.** Each event that an Agent can send is a tool for its model. The description of the event is
   the description of the tool. [The Menu](the-menu.md) tells how.
-- **The events that a Gate accepts.** `jr2 send`, the Console and a webhook can send only those events.
+- **The events that a Gate accepts.** `jr2 send`, the Console and a [Hook](../reference/glossary.md#hook) can send only
+  those events.
 - **The check of each delivery.** jr2 parses the payload of each event with its schema before the Machine gets the
   event.
 
@@ -232,13 +233,13 @@ in the run to the feeds, also those of each child Machine.
 
 You see an Emit in these places:
 
-- `jr2 run`, and `jr2 logs -f`, write each Emit on stderr while they are attached to the run. The line holds `emit`,
-  then the Emit as JSON. `jr2 logs` without `-f` writes no Emit.
+- `jr2 run` and `jr2 watch` write each Emit while they are attached to the run. The line holds `emit`, then the Emit as
+  JSON. `jr2 run` and `jr2 watch --json` write it on stderr; `jr2 watch` writes it on stdout.
 - The Activity tab of the Console shows the type of each Emit that comes while the page is open.
 - The [Harness](../reference/glossary.md#harness) of each [Workspace](../reference/glossary.md#workspace) writes the
   Emits of its run in its log, beside the conversation of its Agents.
 - The feed of a run, [`GET /runs/:runId/events`](../reference/http-api.md#get-runs-runid-events), carries each Emit with
-  its payload. This feed needs the Instance token.
+  its payload. This feed needs the `read` scope for the Workflow of the run.
 
 The feeds that need no token carry the type of an Emit, but not its payload. The payload is your data, as the context of
 a run is.

package/docs/concepts/pools-and-sources.md

@@ -1,6 +1,6 @@
 ---
 title: Pools and Sources
-description: How a Pool runs one worker Machine for each work item that a Source gives, and how its run ends.
+description: How a Pool runs one worker for each item of a Source, how a Hook brings items, and how its run ends.
 ---
 
 # Pools and Sources
@@ -166,9 +166,9 @@ not a status in the output: a run that waits has no output yet.
   input to a worker. `itemInput` can copy a part of it into the worker's input.
 - The run input of a Pool is its own `input` schema, not the input of its worker. `cap` and `itemInput` read it.
 - The Gates of a worker show in the run. The id of each one starts with the id of its item, such as `T-1.review`.
-- The Pool takes the `wake` event of the Source at a Gate named `source`, for the whole run. A webhook or
-  [`jr2 send`](../reference/cli.md#send) sends it. When the Pool is inside a different Machine, the Gate is
-  `<path>.source`.
+- The Pool takes the `wake` event of the Source at a Gate named `source`, for the whole run.
+  [`jr2 send`](../reference/cli.md#send) sends it. A Hook reaches the Source's handlers through the same Gate. When the
+  Pool is inside a different Machine, the Gate is `<path>.source`.
 - The [Vocabulary](../reference/glossary.md#vocabulary) of a Pool is only its `wake` event. Each worker keeps its own.
 
 A Pool is a Machine. It can be the root of a Workflow, or a different Machine can compose it.
@@ -177,8 +177,18 @@ A Pool is a Machine. It can be the root of a Workflow, or a different Machine ca
 
 ## Sources
 
-[`source(spec)`](../reference/authoring-surface/source.md) declares where a Pool gets its items. A Source has three
-parts ([`SourceSpec`](../reference/authoring-surface/type-sourcespec.md)):
+[`source(spec)`](../reference/authoring-surface/source.md) declares where a Pool gets its items. A Source has one of
+three forms:
+
+| Form | What it has                    | How the Pool gets items                                                                  |
+| ---- | ------------------------------ | ---------------------------------------------------------------------------------------- |
+| Pull | `next`                         | The Pool calls `next`, and `next` gives one item at a time.                              |
+| Read | `read` and `items`             | The Pool reads the whole set, and starts the items that are new, one for each slot.      |
+| Push | `item` (a zod schema), `hooks` | Each [Hook](../reference/glossary.md#hook) delivery carries one item. The Pool holds it. |
+
+### Pull
+
+A pull Source has three parts ([`SourceSpec`](../reference/authoring-surface/type-sourcespec.md)):
 
 - `next`: an [xstate](https://xstate.js.org) promise actor that claims the next ready item. Its input is
   `{ active, settled, input }`: the ids of the items that workers have now, the ids of the finished and failed items,
@@ -194,6 +204,166 @@ ready. Without `open`, the Pool cannot tell a finished run from a blocked one. T
 
 A Source can be a queue, a generator, or a set that `next` queries again each time.
 
+### Read
+
+A read Source reads the whole set each time. `read` is an `http` Effect marked `idempotent: true`, so that the read can
+use a secret that the Instance Effector holds, or a promise. Its input is the input of the Pool. `items(output)` gives
+the items in its answer, in order. Without `items`, the answer must be the list of items.
+
+- The Pool reads when the run starts, when a worker finishes, on `wake`, when a Hook's handler gives `reread()`, and
+  after `pollEvery` milliseconds while it waits.
+- One read fills each free slot. The Pool does not start an item whose id a worker has, or that finished in this run.
+  The items that do not get a slot stay in the Source: the next read finds them again.
+- When a `reread()`, a `wake` or a finished worker comes during a read, the Pool reads one more time after that read.
+  Thus no change is lost.
+- A read that fails gives no items. The next read tries again.
+- An item whose `itemId` throws or gives no id is skipped, and the read starts the other items. The run's feed has a
+  `pool` line `skipped` that says which item and why, one time in the run's life.
+
+The read is the truth. A Hook delivery only says "read again". An item that changed while it waited is read as it is
+now.
+
+### Push
+
+A push Source has no read. Each item comes in a Hook delivery, and the handler gives `carry(item)`. The Pool parses the
+item with the `item` schema and holds it in its run, in the order of arrival. When a slot is free, the Pool starts the
+oldest held item. Only a standing Pool of runs takes a push Source (see [A Pool of runs](#a-pool-of-runs)), because a
+Pool that ends when no item is ready would end at once.
+
+`hold` is the most items that the Pool holds, 1000 by default. A held item is in the run's saved state before the Hook
+gets its answer, so a restart does not lose it.
+
+### A Hook reaches a Source
+
+The `hooks` of a Source have the shape of a [Gate's](gates.md) handlers: a handler for each Hook kind and event key. A
+handler reads `{ payload, caller, delivery, input }`. It is pure and synchronous, and it gives one of three answers:
+
+- [`reread()`](../reference/authoring-surface/reread.md): read the Source again now. A pull or a read Source gives it.
+- [`carry(item)`](../reference/authoring-surface/carry.md): here is the item. A push Source gives it.
+- [`skip(reason)`](../reference/authoring-surface/skip.md): this delivery brings nothing, because of `reason`.
+
+A handler never gives `undefined`. A handler that throws is a skip, with the error as its reason. The Hook reaches the
+Source through the Pool's `source` Gate, so the Hook's `may.answer` must name the Pool's Workflow.
+
+The answer of the Hook's door has a line in `sources` for each Source that heard the delivery. Its `verdict` is one of
+these:
+
+| `verdict`   | What it means                                                                                    |
+| ----------- | ------------------------------------------------------------------------------------------------ |
+| `held`      | The Pool holds the carried item. `key` is its id.                                                |
+| `existing`  | The Pool holds the key already, a worker has it, or a run of the callee has it (`run` names it). |
+| `hold-full` | The Pool holds `hold` items. When each Source says `hold-full`, the answer is 429.               |
+| `reread`    | The Source reads again.                                                                          |
+| `skipped`   | The handler gave `skip(reason)`, or threw. `reason` says why.                                    |
+| `paused`    | The standing Pool is paused, and it holds nothing. `jr2 run <workflow>` resumes it.              |
+
+A 429 does not mark the delivery as seen, so the service can send it again. For a chat command or a click, the person
+gets 200 and a text that says why ([The answer that a person reads](gates.md#the-answer-that-a-person-reads)).
+
+A Source can also give `reply(verdict, { caller })`: the text that the person who acted on a chat service reads, from
+its verdict. `verdict.verdict` is one of the names above, except `paused`. `held`, `existing` and `hold-full` also carry
+the `item` and its `key`. The text of a `skipped` verdict shows only when no Gate or other Source gave a text, because a
+skip says "not for me". See [The answer that a person reads](gates.md#the-answer-that-a-person-reads).
+
+## A Pool of runs
+
+The worker of a Pool can be a [`dispatch(...)`](../reference/authoring-surface/dispatch.md) slot in place of a Machine.
+Then each item is a run of its own of the slot's Workflow: it has its own row in `jr2 runs`, its own cancel and its own
+Workspaces. The example starts one `triage` run for each alert that an alert service sends:
+
+```ts
+import { z } from "zod";
+import { carry, dispatch, pool, skip, source } from "@jr2/orchestrator";
+import type {} from "../hooks/sentry.ts";
+
+// The door of the triage Workflow: each alert is one run of it.
+const triageDoor = z.object({ issue: z.string(), title: z.string() });
+
+// A push Source: each Hook delivery carries an alert, and the Pool holds it until a slot is free.
+const alerts = source({
+  item: z.object({ issue: z.string(), title: z.string(), level: z.string() }),
+  hooks: {
+    sentry: {
+      "issue.created": ({ payload }) => {
+        const issue = payload.data.issue;
+        if (issue.level !== "error" && issue.level !== "fatal") return skip(`level is ${issue.level}`);
+        return carry({ issue: issue.id, title: issue.title, level: issue.level });
+      },
+    },
+  },
+});
+
+// A standing Pool of runs: one triage run for each alert, at most 8 live at once.
+export const machine = pool(dispatch("triage", { input: triageDoor, wait: true }), {
+  id: "alerts",
+  standing: true,
+  source: alerts,
+  itemId: (alert) => `sentry-${alert.issue}`,
+  cap: 8,
+  itemInput: (alert) => ({ issue: alert.issue, title: alert.title }),
+});
+```
+
+jr2 ships no kind for this alert service. Thus the Instance makes the `sentry` kind with `webhook()` from
+`@jr2/orchestrator/hooks/webhook`, in a module of its own: `hooks/sentry.ts`. `jr2.config.ts` imports it for the Hook,
+and the Workflow imports it for the types of its handlers.
+
+A Pool of runs is different from a Pool of child Machines:
+
+- **The key.** `itemId(item)` is the key of the item's run in the callee Workflow. Each start with the same key gets the
+  same run while the run's row lives: while the run is live, and for `runs.retain` after it ends. Thus an item never
+  starts two runs, also after a restart. `jr2 status` of the run prints the key, and the Hook delivery that carried the
+  item.
+- **It stands.** A Pool of runs needs `standing: true`. It never ends by itself, and it has no output. When it has no
+  work, it waits for a Hook delivery, a `reread()`, a `wake` or its `pollEvery`.
+- **`cap` counts live runs.** The `dispatch` slot must say `wait: true`, so that the Pool knows when a run ends. A run
+  that ends in any way frees its slot. A run that ends `failed`, or a start that the callee's door refuses, ends only
+  its item: the run is not the Pool's child. The run's feed has a `pool` line for each start and each end.
+- **Independent runs.** A cancel of the Pool does not cancel its runs. `customize()` does not reach into them.
+
+### jr2 keeps the standing run
+
+Nobody starts the run of a standing Pool. jr2 starts it at the publish that adds the Workflow, and keeps one live run of
+it after that:
+
+- **A restart keeps it.** The restored run keeps its held items and its live runs. jr2 starts no second one.
+- **A publish hands it over.** At each publish, jr2 starts a new run under the new Assembly and ends the old run `done`.
+  `jr2 status <old run>` prints `handed over to: <new run>`. The new run takes the held items, parsed again by the new
+  `item` schema (an item that does not parse is dropped, with a `carry-refused` line on the feed), and it sends each
+  active key again: the key finds its run, so no item starts a second run. jr2 also hands the run over when it has taken
+  500 items or is one day old, and when its Assembly can no longer be read (drift).
+- **An `error` is handed over after a back-off** of 1 s, then 4 s, then 16 s. A run that ends `failed` is handed over as
+  a run that ends `error` is. While the Pool waits, it has no live run, and the Hook's door answers 503 to a delivery
+  for it, so the service sends it again. For a chat command or a click, the person gets 200 and a text that says why
+  ([The answer that a person reads](gates.md#the-answer-that-a-person-reads)).
+- **A bound with no run started is handed over after the back-off too.** When a run takes its 500 items and none of them
+  starts a run (the callee's door refuses each one, for example), jr2 ends the run and waits before the next run. The
+  Pool knows an item that ends with no run only during the run that took it. Without the wait, each new run would take
+  the same items again at once, with no end.
+- **jr2 pauses a Pool whose items start no run.** One rule counts a run that ends `error`, ends `failed`, or takes its
+  bound: when no item that the run took itself starts a run, the run counts. An active key that a hand-over carried to
+  the run does not count, because its run started before. A run in which an item that it took starts a run starts the
+  count again. After 3 hand-overs from counted runs in a row, jr2 pauses the Pool when the next counted run ends.
+  `jr2 status` and the Orchestrator's log say which end paused the Pool.
+- **A cancel is a pause.** `jr2 send <run> --event CANCEL` ends the run `cancelled`, and jr2 starts no run of the
+  Workflow at a restart or a publish. A delivery gets the verdict `paused`, and the Pool holds nothing. `jr2 status`
+  prints the Pool as paused, with the number of items it holds.
+- **`jr2 run <workflow>` resumes it.** It is the one start of a standing Workflow that jr2 accepts: the new run takes
+  the held items and the active keys of the paused run, and `jr2 status` prints `resumed by:` with the Caller.
+  `jr2 run <workflow> --drop-held` resumes it with no held item. While the Pool is live, `jr2 run` of it is refused.
+
+`jr2 up` prints the chain from each Hook to each standing Pool and its callee (`standing: sentry → alerts → triage`),
+and the state of each standing Pool after the publish. It warns when two standing Pools dispatch to one Workflow: `cap`
+is for each Pool, so the caps add.
+
+`pool()` and the load walk refuse a Pool that cannot run, and the message tells the fix:
+
+- A worker that is a Workflow name. Write `dispatch("<name>", { input, wait: true })`.
+- A Pool of runs without `standing: true`, a `dispatch` slot without `wait: true` or with a `target`, and a Pool of runs
+  without `cap`.
+- `standing: true` on a Pool of child Machines, and a push Source on a Pool that does not stand.
+- A standing Pool that is not the top Machine of its Workflow. Put it in a file of its own in `workflows/`.
+
 ## Work Source and the Ready-set
 
 A [Work Source](../reference/glossary.md#work-source) is a Source over an issue tracker, such as GitHub issues or Jira.
@@ -211,20 +381,26 @@ the issue tracker.
 ## Rules
 
 - `itemId` gives each item an id of its own, and the same id each time. The Pool uses it as the id of the worker and as
-  the key in `items`.
+  the key in `items`. An item whose `itemId` throws or gives no id is skipped: a push Source's verdict is `skipped`, and
+  a read Source puts a `skipped` line on the feed. In a pull Source, the run ends `error`.
 - `next` must not give an item in `active` or in `settled`.
-- `cap` is a number, or a function of the run input. Without `cap`, one worker runs at a time.
+- `cap` is a number, or a function of the run input. Without `cap`, one worker runs at a time. A Pool of runs must state
+  `cap`.
 - `onDrained` takes only `"final"`: the run ends.
-- The Pool calls `next` again on `wake` or after `pollEvery` only while it waits: workers run and no item is ready.
+- The Pool calls `next` again on `wake`, on `reread()` or after `pollEvery` only while it waits: workers run and no item
+  is ready. A `wake` or a `reread()` that comes while `next` runs makes the Pool call `next` once more.
 - A `task` in a Pool needs a `branch` in its input. Make it in `itemInput`, for example from the item id.
 
 ## Read next
 
-- [Run one worker per item](../guides/run-one-worker-per-item.md)
+- [Run one worker per item](../guides/run-one-worker-per-item.md) and
+  [Start a run for each alert](../guides/start-a-run-for-each-alert.md)
+- [Callers and Hooks](callers-and-hooks.md)
 - [Composition](composition.md)
 - [Gates](gates.md)
 - Reference: [`pool()`](../reference/authoring-surface/pool.md), [`source()`](../reference/authoring-surface/source.md),
-  [`PoolSpec`](../reference/authoring-surface/type-poolspec.md),
+  [`carry()`](../reference/authoring-surface/carry.md), [`reread()`](../reference/authoring-surface/reread.md),
+  [`skip()`](../reference/authoring-surface/skip.md), [`PoolSpec`](../reference/authoring-surface/type-poolspec.md),
   [`SourceSpec`](../reference/authoring-surface/type-sourcespec.md),
   [`SourceNextResult`](../reference/authoring-surface/type-sourcenextresult.md)
 - [ADR-0017](../reference/decisions/0017-pool-over-a-source-port.md): the run loop is a Pool over a Source