@jr2/orchestrator 0.6.0 → 0.7.0

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

@@ -0,0 +1,23 @@
+---
+title: SourceHooks
+description: "A Source's handlers, by Hook kind and event key."
+---
+
+# `SourceHooks`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type SourceHooks<Out, TInput = unknown> = KindHooks<SourceIn<TInput>, Out | Skip>;
+```
+
+A Source's handlers, by Hook kind and event key. They have the shape of a Gate's `hooks`. A
+handler is pure and synchronous. It gives `Out` or `skip(reason)`, never `undefined`; a throw is a
+skip with the error as its reason.
+
+**Fields**
+
+- `github` (optional): `typeof github`
+- `gitlab` (optional): `typeof gitlab`
+- `slack` (optional): `typeof slack`
+- `discord` (optional): `typeof discord`

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

@@ -0,0 +1,25 @@
+---
+title: SourceIn
+description: "What a Source's handler reads beside `payload`."
+---
+
+# `SourceIn`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type SourceIn<TInput = unknown> = {
+  readonly caller: CallerRecord;
+  readonly delivery: string;
+  readonly input: TInput;
+};
+```
+
+What a Source's handler reads beside `payload`. `caller` is the Hook as a Caller, `delivery` the
+delivery id, and `input` the Pool's input (`{}` for a standing Pool).
+
+**Fields**
+
+- `caller`: [`CallerRecord`](type-callerrecord.md)
+- `delivery`: `string`
+- `input`: `TInput`

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

@@ -0,0 +1,18 @@
+---
+title: SourceReply
+description: "The text that the person who acted reads, from this Source's verdict (ADR-0011, ADR-0017)."
+---
+
+# `SourceReply`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, in the [Composition](group-composition.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type SourceReply<T> = (verdict: SourceVerdict<T>, at: { readonly caller: CallerRecord }) => string | undefined;
+```
+
+The text that the person who acted reads, from this Source's verdict ([ADR-0011](../decisions/0011-workflow-defined-events.md), [ADR-0017](../decisions/0017-pool-over-a-source-port.md)).
+Plain text: the Hook kind escapes it and puts it in its envelope. Pure and synchronous.
+`undefined` or `""`: this Source says nothing. It runs only for a delivery whose answer a person
+reads (`slack`, `discord`). The text of a `skipped` verdict shows only when no other target gave
+a text.

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

@@ -1,6 +1,6 @@
 ---
 title: SourceSpec
-description: "Where a Pool gets its work items: the Source."
+description: A pull Source.
 ---
 
 # `SourceSpec`
@@ -16,10 +16,12 @@ type SourceSpec<T, TInput = unknown> = {
     | PromiseActorLogic<null, PoolNextInput<TInput>>;
   wake?: EventDef;
   pollEvery?: number;
+  hooks?: SourceHooks<Reread, TInput>;
+  reply?: SourceReply<T>;
 };
 ```
 
-Where a Pool gets its work items: the Source. Make one with [`source`](source.md).
+A pull Source. `next` claims one item at a time. Make one with [`source`](source.md).
 
 **Fields**
 
@@ -30,15 +32,22 @@ Where a Pool gets its work items: the Source. Make one with [`source`](source.md
   the items that workers have now, `settled`, the ids of the items that finished or failed, and
   `input`, the Pool's input. It must not give again an item in `active` or `settled`. It resolves
   to a [`SourceNextResult`](type-sourcenextresult.md). The Pool calls it when the run starts, after each claim, and when a worker settles. While workers run and no item is ready, it
-  also calls it on `wake` and every `pollEvery`.
+  also calls it on `wake`, on a Hook's `reread()` and every `pollEvery`.
 - `wake` (optional): [`EventDef`](type-eventdef.md)
 
   An external event, made with `defineEvent`, that tells the Pool that new work is ready, for
-  example from a webhook or `jr2 send`. While workers run and no item is ready, it makes the Pool
-  call `next` at once. The Pool serves it as a Gate named `source` for the whole run
-  (`<path>.source` when the Pool is composed in another Machine). Default: none.
+  example from `jr2 send`. While workers run and no item is ready, it makes the Pool call `next`
+  at once. The Pool serves it as a Gate named `source` for the whole run (`<path>.source` when the
+  Pool is composed in another Machine). Default: none.
 - `pollEvery` (optional): `number`
 
   While workers run and no item is ready, call `next` again after this many milliseconds. Use
   it for a Source whose items change while the run waits. Default: none, so the Pool calls
-  `next` again only when a worker settles or `wake` comes.
+  `next` again only when a worker settles, `wake` comes, or a Hook's handler gives `reread()`.
+- `hooks` (optional): `SourceHooks<Reread, TInput>`
+
+  What a Hook's delivery does: a handler for each Hook kind id and event key gives `reread()` or
+  `skip(reason)`. Default: none.
+- `reply` (optional): `SourceReply<T>`
+
+  The text that the person who acted reads, from the verdict. Default: none.

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

@@ -0,0 +1,49 @@
+---
+title: SourceVerdict
+description: "A Source's verdict on one delivery, as its `reply` reads it (ADR-0017)."
+---
+
+# `SourceVerdict`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, in the [Composition](group-composition.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type SourceVerdict<T> =
+  | { readonly verdict: "held"; readonly key: string; readonly item: T }
+  | { readonly verdict: "existing"; readonly key: string; readonly item: T; readonly run?: string }
+  | { readonly verdict: "hold-full"; readonly key: string; readonly item: T }
+  | { readonly verdict: "reread" }
+  | { readonly verdict: "skipped"; readonly reason: string };
+```
+
+A Source's verdict on one delivery, as its `reply` reads it ([ADR-0017](../decisions/0017-pool-over-a-source-port.md)). `held`, `existing` and
+`hold-full` come from a push Source and carry the item and its key; `existing` names the run
+that holds the key, when one holds it. `reread` comes from a Source that can read. `skipped`
+carries the reason. A Pool that is paused has no run, so no `reply` of it runs: the door writes
+that text.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `verdict`, `key`, `item`
+
+  - `verdict`: `"held"`
+  - `key`: `string`
+  - `item`: `T`
+- Form 2: `verdict`, `key`, `item`, `run`
+
+  - `verdict`: `"existing"`
+  - `key`: `string`
+  - `item`: `T`
+  - `run` (optional): `string`
+- Form 3: `verdict`, `key`, `item`
+
+  - `verdict`: `"hold-full"`
+  - `key`: `string`
+  - `item`: `T`
+- Form 4: `verdict`
+
+  - `verdict`: `"reread"`
+- Form 5: `verdict`, `reason`
+
+  - `verdict`: `"skipped"`
+  - `reason`: `string`

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

@@ -0,0 +1,12 @@
+---
+title: StandingPoolMachine
+description: A type that the Authoring surface names.
+---
+
+# `StandingPoolMachine`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type StandingPoolMachine = StateMachine<any, any, any, any, any, any, any, any, any, {}, never, any, any, any>;
+```

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

@@ -0,0 +1,51 @@
+---
+title: StandingPoolSpec
+description: What you pass to `pool()` for a Pool of runs.
+---
+
+# `StandingPoolSpec`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type StandingPoolSpec<T, I> = {
+  id?: string;
+  standing: true;
+  source: SourceSpec<T, {}> | SourceSpec<T> | ReadSourceSpec<T, {}> | ReadSourceSpec<T> | PushSourceSpec<T>;
+  itemId: (item: T) => string;
+  cap: number;
+  itemInput?: (item: T) => I;
+  input?: never;
+  onDrained?: never;
+  failures?: never;
+};
+```
+
+What you pass to `pool()` for a Pool of runs. The worker is a `dispatch(...)` slot, and the Pool
+stands. Each item is a run of the slot's Workflow, keyed by `itemId` in that Workflow.
+
+**Fields**
+
+- `id` (optional): `string`
+
+  The Machine id: the name of the Pool in the Console. Default: `"pool"`.
+- `standing`: `true`
+
+  A Pool of runs stands: jr2 keeps one live run of its Workflow, and it never ends by itself.
+- `source`: `SourceSpec<T, {}> | SourceSpec<T> | ReadSourceSpec<T, {}> | ReadSourceSpec<T> | PushSourceSpec<T>`
+
+  Where the items come from: a pull, a read or a push Source. Make it with [`source`](source.md).
+- `itemId`: `(item: T) => string`
+
+  The id of an item, and the KEY of its run in the slot's Workflow ([ADR-0071](../decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)): every Pool, every
+  hand-over and every `jr2 run` that gives this key to that Workflow gets the same run while its
+  row lives — while it is live, and for `runs.retain` after it ends.
+- `cap`: `number`
+
+  The most LIVE runs at once that this Pool dispatched. You must choose it.
+- `itemInput` (optional): `(item: T) => I`
+
+  Make a run's body from its item. Default: the item itself.
+- `input` (optional): `never`
+- `onDrained` (optional): `never`
+- `failures` (optional): `never`

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

@@ -0,0 +1,20 @@
+---
+title: SteerArgs
+description: "The arguments a `steer` text or `from` function gets: the Machine's context and the event that the transition takes."
+---
+
+# `SteerArgs`
+
+Type, in `@jr2/orchestrator/src/steer.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type SteerArgs<TContext, TEvent> = { context: TContext; event: TEvent };
+```
+
+The arguments a `steer` text or `from` function gets: the Machine's context and the event that
+the transition takes.
+
+**Fields**
+
+- `context`: `TContext`
+- `event`: `TEvent`

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

@@ -5,7 +5,7 @@ description: "How hard the model thinks before it answers: `\"off\"`, `\"minimal
 
 # `ThinkingLevel`
 
-Type, in `@jr2/orchestrator/src/agent.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Agents.
+Type, in `@jr2/orchestrator/src/agent.ts`. It is an export of `@jr2/orchestrator`, in the [Agents](group-agents.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";

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

@@ -5,7 +5,7 @@ description: "The User Container in its object form: its image, and its part of
 
 # `UserContainer`
 
-Type, in `@jr2/orchestrator/src/size.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+Type, in `@jr2/orchestrator/src/size.ts`. It is an export of `@jr2/orchestrator`, in the [Composition](group-composition.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type UserContainer = {

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

@@ -5,7 +5,7 @@ description: "The input of a `workspace()` body: the run input, plus `workspace`
 
 # `Workspaced`
 
-Type, in `@jr2/orchestrator/src/workspace.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Workspaces and Repos.
+Type, in `@jr2/orchestrator/src/workspace.ts`. It is an export of `@jr2/orchestrator`, in the [Workspaces and Repos](group-workspaces-and-repos.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type Workspaced<TInput, TSlots extends string> = WithoutEmptyIndex<TInput> & {

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

@@ -1,16 +1,16 @@
 ---
 title: WorktreeFound
-description: "What a cut found: `held`, a cut made this Worktree earlier, so what is in it is earlier work; `local`, a local branch; `remote`, `origin/<branch>`, now tracked; `none`, a new branch with no upstream; `commit`, a detached cut."
+description: What a cut found.
 ---
 
 # `WorktreeFound`
 
-Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type WorktreeFound = "held" | "local" | "remote" | "none" | "commit" | (string & {});
 ```
 
-What a cut found: `held`, a cut made this Worktree earlier, so what is in it is earlier work;
+What a cut found. `held`: a cut made this Worktree earlier, so what is in it is earlier work;
 `local`, a local branch; `remote`, `origin/<branch>`, now tracked; `none`, a new branch with no
 upstream; `commit`, a detached cut. Open: a later value does not break an author's code.

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

@@ -5,7 +5,7 @@ description: "The input of a `worktree()`: a branch Worktree, or a detached one.
 
 # `WorktreeInput`
 
-Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type WorktreeInput =

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

@@ -5,7 +5,7 @@ description: The options of `worktree()`.
 
 # `WorktreeOptions`
 
-Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type WorktreeOptions = {

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

@@ -5,7 +5,7 @@ description: The output of a `worktree()`.
 
 # `WorktreeOutput`
 
-Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type WorktreeOutput<S extends string = string> = WorktreeReady<S> | WorktreeRefused | Unknown | LaterOutcome;

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

@@ -5,7 +5,7 @@ description: A Worktree of the Repo Slots `S`.
 
 # `WorktreePath`
 
-Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type WorktreePath<S extends string> = `/work/${S}/${NameStart}${string}`;

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

@@ -5,7 +5,7 @@ description: Type, an export of @jr2/orchestrator.
 
 # `WorktreeReady`
 
-Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type WorktreeReady<S extends string = string> = {

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

@@ -1,18 +1,18 @@
 ---
 title: WorktreeRefused
-description: "No Worktree, and nothing changed: a bad path, a name git or the push refuses, a re-cut that does not agree with the first, a branch that another Worktree holds, an `expect` that does not hold, or a name that the remote cannot confirm."
+description: No Worktree, and nothing changed.
 ---
 
 # `WorktreeRefused`
 
-Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type WorktreeRefused = { outcome: "refused"; reason: string };
 ```
 
-No Worktree, and nothing changed: a bad path, a name git or the push refuses, a re-cut that does
-not agree with the first, a branch that another Worktree holds, an `expect` that does not hold, or a
+No Worktree, and nothing changed. The cause is a bad path, a name git or the push refuses, a
+re-cut that does not agree with the first, a branch that another Worktree holds, an `expect` that does not hold, or a
 name that the remote cannot confirm.
 
 **Fields**

package/docs/reference/authoring-surface/workspace.md

@@ -5,7 +5,7 @@ description: "Run a body Machine in a Sandbox: a pod of its own, with a clone of
 
 # `workspace`
 
-Function, in `@jr2/orchestrator/src/workspace.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Workspaces and Repos.
+Function, in `@jr2/orchestrator/src/workspace.ts`. It is an export of `@jr2/orchestrator`, in the [Workspaces and Repos](group-workspaces-and-repos.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ## Overload 1
 

package/docs/reference/authoring-surface/worktree.md

@@ -5,7 +5,7 @@ description: "Make a `worktree` Effect: it cuts a Worktree of a Repo Slot, or re
 
 # `worktree`
 
-Function, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function worktree(options: WorktreeOptions = {}): EffectLogic<WorktreeInput, WorktreeOutput>