@jr2/orchestrator 0.5.1 → 0.7.0

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

@@ -5,7 +5,7 @@ description: "Leave a part of a Machine Open: for the Instance that registers th
 
 # `open`
 
-Constant, in `@jr2/orchestrator/src/open.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+Constant, in `@jr2/orchestrator/src/open.ts`. It is an export of `@jr2/orchestrator`, in the [Composition](group-composition.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 const open: unique symbol
@@ -17,18 +17,31 @@ part that the package cannot know or pay for:
 - a Repo Slot: `repos: { app: open }`, or the whole map: `repos: open`;
 - an Agent's model: `agent({ model: open, … })`;
 - an Effect's url or argv: `http({ url: open, … })`, `command(open)`;
-- the secret of an Effect's auth, of a header, or of a command's `env`: `secret(open)`.
+- the secret of an Effect's auth, of a header, or of a command's `env`: `secret(open)`;
+- the look of a Gate slot: `gate({ …, look: open })`.
 
 `jr2 up` refuses a Workflow with an Open part that nobody bound, and prints the `customize()`
 line that binds it: ``refusing: workflow "<name>" leaves <part> open — bind it where the Machine
 is registered: export const machine = customize(<import>, …)  (<adr>)``. A run never sees an
-Open part.
+Open part. An Open look is the one exception: `jr2 up` warns about it and does not refuse,
+because a person can still answer the Gate with `jr2 send`.
 
 **Example**
 
 ```ts
 import { z } from "zod";
-import { agent, customize, defineEvent, fail, jr2Setup, open, workspace } from "@jr2/orchestrator";
+import {
+  agent,
+  customize,
+  defineEvent,
+  fail,
+  isReady,
+  jr2Setup,
+  open,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
 
 const finish = defineEvent({
   name: "finish",
@@ -36,19 +49,40 @@ const finish = defineEvent({
   input: z.object({}),
 });
 
+type Input = Workspaced<{}, "app">;
+
+const fixTree = (context: Input) => `${context.workspace.repos.app}/fix` as const;
+
 const body = jr2Setup({
+  types: {} as { context: Input; input: Input },
   events: [finish],
-  actors: { coder: agent({ model: open, instructions: "You fix the failing test." }), fail: fail() },
+  actors: {
+    coder: agent({ model: open, instructions: "You fix the failing test." }),
+    cut: worktree(),
+    fail: fail(),
+  },
 }).createMachine({
   id: "fix",
+  context: ({ input }) => input,
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: "jr2/fix" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
-      invoke: { src: "coder", input: { prompt: "Make `node --test` pass." } },
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({ prompt: "Make `node --test` pass.", cwd: fixTree(context) }),
+      },
       on: { finish: "done" },
     },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
@@ -57,7 +91,6 @@ const body = jr2Setup({
 // What a package exports: the repository and the model are Open.
 export const fix = workspace(body, {
   repos: { app: open },
-  spec: () => ({ branch: "jr2/fix" }),
 });
 
 // What an Instance's `workflows/fix.ts` exports: the same Machine, its Open parts bound.

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

@@ -5,7 +5,7 @@ description: "Make an Open body: the actor slot that a Chart binds."
 
 # `openBody`
 
-Function, in `@jr2/orchestrator/src/open-body.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Charts.
+Function, in `@jr2/orchestrator/src/open-body.ts`. It is an export of `@jr2/orchestrator`, in the [Charts](group-charts.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function openBody(decl: OpenBodyDeclaration): OpenBodyLogic

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

@@ -5,7 +5,7 @@ description: Read the params of a pick from the event that entered the state.
 
 # `paramsOf`
 
-Function, in `@jr2/orchestrator/src/pick.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/pick.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 paramsOf<
@@ -50,9 +50,11 @@ import {
   command,
   defineEvent,
   fail,
+  isReady,
   jr2Setup,
   paramsOf,
   workspace,
+  worktree,
   type Workspaced,
 } from "@jr2/orchestrator";
 
@@ -70,6 +72,8 @@ const finished = defineEvent({
 
 type Input = Workspaced<{}, "app">;
 
+const fixTree = (context: Input) => `${context.workspace.repos.app}/fix` as const;
+
 const body = jr2Setup({
   types: {} as { context: Input; input: Input },
   events: [runTest, finished],
@@ -78,6 +82,7 @@ const body = jr2Setup({
       model: "anthropic/claude-haiku-5-5",
       instructions: "You are a careful engineer.",
     }),
+    cut: worktree(),
     test: command(["node", "--test", arg("file")]),
     fail: fail(),
   },
@@ -85,12 +90,22 @@ const body = jr2Setup({
   id: "fix-tests",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: "fix-tests" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
       invoke: {
         src: "coder",
-        input: { prompt: "Make the tests pass. Run the tests of one module at a time." },
+        input: ({ context }) => ({
+          prompt: "Make the tests pass. Run the tests of one module at a time.",
+          cwd: fixTree(context),
+        }),
       },
       on: { finished: "done" },
       initial: "ready",
@@ -100,13 +115,17 @@ const body = jr2Setup({
           invoke: {
             src: "test",
             // A plain mapper: the Machine makes the file name from the pick's `module`.
-            input: ({ event }) => ({ file: `test/${paramsOf(event, runTest).module}.test.js` }),
+            input: ({ context, event }) => ({
+              file: `test/${paramsOf(event, runTest).module}.test.js`,
+              worktree: fixTree(context),
+            }),
             onDone: "ready",
           },
         },
       },
     },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
@@ -114,7 +133,6 @@ const body = jr2Setup({
 
 export const machine = workspace(body, {
   repos: { app: { url: "https://github.com/you/app.git" } },
-  spec: () => ({ branch: "fix-tests" }),
 });
 ```
 

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

@@ -1,11 +1,11 @@
 ---
 title: pool
-description: "Make a Pool: a Machine that runs one worker Machine for each item that a Source gives, with at most `cap` workers at once."
+description: "Make a Pool: a Machine that runs one worker for each item that a Source gives, with at most `cap` workers at once."
 ---
 
 # `pool`
 
-Function, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+Function, 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.
 
 ## Overload 1
 
@@ -19,9 +19,12 @@ function pool<
 ): PoolMachine<TWorker, z.infer<TSchema>>
 ```
 
-Make a Pool: a Machine that runs one worker Machine for each item that a Source gives, with at
-most `cap` workers at once. Use it as the root of a Workflow (`export const machine = pool(…)`),
-or compose it in another Machine.
+Make a Pool: a Machine that runs one worker for each item that a Source gives, with at most
+`cap` workers at once. Use it as the root of a Workflow (`export const machine = pool(…)`), or
+compose it in another Machine.
+
+The worker is a Machine, which runs inside the Pool's run, or a `dispatch(...)` slot, which makes
+each item a run of its own (a Pool of runs, which stands; see the third form).
 
 The run ends when the Source has no item ready and no worker runs. Its output is
 `{ status, items, failures }`: `status` is `"drained"` when no item is left, or `"deadlocked"`
@@ -51,9 +54,10 @@ its own.
     The run input of the Pool, as a zod object: what a caller sends to start a run. `cap` and
     `itemInput` read it, typed by it. A worker never gets it: each worker gets its item. Default:
     none, and then their `input` is `unknown`.
-  - `source`: `SourceSpec<T>`
+  - `source`: `SourceSpec<T, TInput> | SourceSpec<T> | ReadSourceSpec<T, TInput> | ReadSourceSpec<T>`
 
-    Where the items come from. Make it with [`source`](source.md).
+    Where the items come from: a pull or a read Source. Make it with [`source`](source.md). A push Source
+    needs a standing Pool of runs.
   - `itemId`: `(item: T) => string`
 
     The id of an item. The Pool uses it as the id of the item's worker and in the `active` list
@@ -76,6 +80,9 @@ its own.
     ends with failures, `drained` or `deadlocked`, it fails the run with the reason
     `"<n> of <m> items failed"` and the detail `{ status, items, failures }`. `"report"`: the Pool
     ends `done`, with the failures in its output. Default: `"fail"`.
+  - `standing` (optional): `false`
+
+    A Pool of child Machines never stands: a child cannot be handed over.
 
 **Returns**: The Pool, as a Machine.
 
@@ -83,7 +90,7 @@ its own.
 
 ```ts
 import { fromPromise } from "xstate";
-import { customize, pool, source } from "@jr2/orchestrator";
+import { customize, pool, source, type PoolNextInput } from "@jr2/orchestrator";
 import { task } from "@jr2/machines";
 
 type Issue = { id: string; title: string };
@@ -94,7 +101,7 @@ const backlog: Issue[] = [
 ];
 
 const issues = source<Issue>({
-  next: fromPromise(async ({ input }: { input: { active: string[] } }) => {
+  next: fromPromise(async ({ input }: { input: PoolNextInput }) => {
     const issue = backlog.find((i) => !input.active.includes(i.id)) ?? null;
     if (issue) backlog.splice(backlog.indexOf(issue), 1);
     return issue;
@@ -151,9 +158,10 @@ an example.
     The run input of the Pool, as a zod object: what a caller sends to start a run. `cap` and
     `itemInput` read it, typed by it. A worker never gets it: each worker gets its item. Default:
     none, and then their `input` is `unknown`.
-  - `source`: `SourceSpec<T>`
+  - `source`: `SourceSpec<T, TInput> | SourceSpec<T> | ReadSourceSpec<T, TInput> | ReadSourceSpec<T>`
 
-    Where the items come from. Make it with [`source`](source.md).
+    Where the items come from: a pull or a read Source. Make it with [`source`](source.md). A push Source
+    needs a standing Pool of runs.
   - `itemId`: `(item: T) => string`
 
     The id of an item. The Pool uses it as the id of the item's worker and in the `active` list
@@ -176,6 +184,9 @@ an example.
     ends with failures, `drained` or `deadlocked`, it fails the run with the reason
     `"<n> of <m> items failed"` and the detail `{ status, items, failures }`. `"report"`: the Pool
     ends `done`, with the failures in its output. Default: `"fail"`.
+  - `standing` (optional): `false`
+
+    A Pool of child Machines never stands: a child cannot be handed over.
 
 **Returns**: The Pool, as a Machine.
 
@@ -184,3 +195,60 @@ an example.
 - [Run one worker per item](../../guides/run-one-worker-per-item.md)
 - [Pools and Sources](../../concepts/pools-and-sources.md)
 - [ADR-0017: The run loop is a jr2 `pool` over a generalized source port](../decisions/0017-pool-over-a-source-port.md)
+
+## Overload 3
+
+```ts
+function pool<
+  I,
+  T,
+>(
+  worker: EffectLogic<I, DispatchOutput>,
+  spec: StandingPoolSpec<T, I>,
+): StandingPoolMachine
+```
+
+Make a standing Pool of runs: each item that the Source gives is a run of the `dispatch` slot's
+Workflow, keyed by `itemId` in that Workflow, with at most `cap` live at once ([ADR-0017](../decisions/0017-pool-over-a-source-port.md)). The
+slot says `wait: true` and has no `target`. The Pool never ends by itself: when it has no work, it
+waits for a Hook's delivery, a `reread` or its `pollEvery`. A run that ends in any way frees its
+slot, and is a `settled` mark on the run's feed; it is never the Pool's error, because the run is
+not the Pool's child. Use it as the top Machine of its Workflow, in a file of its own.
+
+**Parameters**
+
+- `worker` ([`EffectLogic`](type-effectlogic.md)): The `dispatch(...)` slot of the Workflow that runs each item.
+- `spec`: The Source, the item id, the cap and the run's body. See [`StandingPoolSpec`](type-standingpoolspec.md).
+
+**Returns**: The standing Pool, as a Machine.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { carry, dispatch, pool, skip, source } from "@jr2/orchestrator";
+import type {} from "@jr2/orchestrator/hooks/gitlab";
+
+const failed = z.object({ sha: z.string() });
+
+export const machine = pool(dispatch("triage", { input: failed, wait: true }), {
+  id: "pipelines",
+  standing: true,
+  source: source({
+    item: failed,
+    hooks: {
+      gitlab: {
+        "pipeline.failed": ({ payload }) =>
+          payload.object_attributes.sha === "" ? skip("no commit") : carry({ sha: payload.object_attributes.sha }),
+      },
+    },
+  }),
+  itemId: (p) => `pipeline-${p.sha}`,
+  cap: 4,
+});
+```
+
+**See also**
+
+- [Pools and Sources](../../concepts/pools-and-sources.md)
+- [ADR-0017: The run loop is a jr2 `pool` over a generalized source port](../decisions/0017-pool-over-a-source-port.md)

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

@@ -1,24 +1,23 @@
 ---
 title: push
-description: "Make a `push` Effect: it pushes the branch of the Workspace to the Binding of its Repo Slot."
+description: "Make a `push` Effect: it pushes the branch of a Worktree to the Binding of its Repo Slot."
 ---
 
 # `push`
 
-Function, in `@jr2/orchestrator/src/sandbox-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/sandbox-effect.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 push<
-  const O extends PushOptions,
->(
-  options?: O,
-): EffectLogic<PushInput<O> | void, PushOutput>
+function push<const O extends PushOptions>(options?: O): EffectLogic<PushInput<O>, PushOutput>
 ```
 
-Make a `push` Effect: it pushes the branch of the Workspace to the Binding of its Repo Slot.
+Make a `push` Effect: it pushes the branch of a Worktree to the Binding of its Repo Slot.
 Put it in `actors`, and invoke it from the body of a `workspace()`: `actors: { publish: push({
 sign: true }) }`.
 
+Its input names the Worktree: `{ worktree }`. It has no branch. jr2 reads the branch from the
+`worktree()` cut of that path, so an Agent that moves `HEAD` does not change what jr2 pushes.
+
 It runs in the Sandbox Effector of the Workspace, with the push credential of the
 `git.credentials` entry that the Binding matches. The Agent never reads that credential. It
 pushes one commit: the tip of the Agent's branch when the Effect starts, or, with `pin`, the
@@ -26,8 +25,10 @@ commit that the input names. After an Orchestrator restart, jr2 pushes only that
 again. With `sign` or `squash`, the commit on the remote is not the Agent's own. Then jr2 moves
 the Agent's branch to it.
 
-Every outcome is output (`PushOutput`): `pushed`, `rejected`, `diverged` or `unknown`. Each
-field of [`PushOptions`](type-pushoptions.md) tells what it refuses. When it starts, it also refuses a push
+Every outcome is output (`PushOutput`): `pushed`, `rejected`, `diverged` or `unknown`. A
+`worktree` that no cut made in this Sandbox, a Worktree of another Repo Slot, and a detached
+Worktree are `rejected` at `stage` `start`, and nothing is pushed. Each field of
+[`PushOptions`](type-pushoptions.md) tells what it refuses. When it starts, it also refuses a push
 outside a Workspace: `push "<slot>" runs in the Sandbox Effector of a Workspace, and its state is
 not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`.
 
@@ -45,9 +46,11 @@ import {
   agent,
   defineEvent,
   fail,
+  isReady,
   jr2Setup,
   push,
   workspace,
+  worktree,
   type Workspaced,
 } from "@jr2/orchestrator";
 
@@ -59,6 +62,8 @@ const committed = defineEvent({
 
 type Input = Workspaced<{}, "app">;
 
+const fixTree = (context: Input) => `${context.workspace.repos.app}/fix` as const;
+
 const body = jr2Setup({
   types: {} as { context: Input; input: Input },
   events: [committed],
@@ -67,6 +72,7 @@ const body = jr2Setup({
       model: "anthropic/claude-haiku-5-5",
       instructions: "You are a careful engineer.",
     }),
+    cut: worktree(),
     publish: push({ sign: true }),
     fail: fail(),
   },
@@ -74,10 +80,20 @@ const body = jr2Setup({
   id: "fix-test",
   context: ({ input }) => input,
   on: { "workspace.lost": ".failed", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: "fix-test" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
-      invoke: { src: "coder", input: { prompt: "Fix the failing test, and commit the fix." } },
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({ prompt: "Fix the failing test, and commit the fix.", cwd: fixTree(context) }),
+      },
       // The Agent moves the Machine on with a pick. An Agent's actor never ends, so `onDone`
       // never fires.
       on: { committed: "publishing" },
@@ -85,6 +101,8 @@ const body = jr2Setup({
     publishing: {
       invoke: {
         src: "publish",
+        // jr2 reads the branch from the cut of this Worktree.
+        input: ({ context }) => ({ worktree: fixTree(context) }),
         onDone: [
           { guard: ({ event }) => event.output.outcome === "pushed", target: "done" },
           { target: "failed" },
@@ -92,6 +110,7 @@ const body = jr2Setup({
       },
     },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     // Not a final state: the run ends `failed`, and the Workspace deletes the Sandbox.
     failed: { invoke: { src: "fail", input: { reason: "the fix was not pushed" } } },
   },
@@ -99,7 +118,6 @@ const body = jr2Setup({
 
 export const machine = workspace(body, {
   repos: { app: { url: "https://github.com/you/app.git" } },
-  spec: () => ({ branch: "fix-test" }),
 });
 ```
 

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

@@ -0,0 +1,21 @@
+---
+title: readyOf
+description: The `ready` output of an `onDone` arm that `isReady` guards.
+---
+
+# `readyOf`
+
+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 readyOf<O extends { outcome: string }>(output: O): Extract<O, { outcome: "ready" }>
+```
+
+The `ready` output of an `onDone` arm that `isReady` guards. xstate carries no guard's narrowing
+to its actions, so an `assign` reads the output through this.
+
+**Parameters**
+
+- `output`
+
+  - `outcome`: `string`

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

@@ -0,0 +1,19 @@
+---
+title: reread
+description: Read the Source again.
+---
+
+# `reread`
+
+Function, 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
+function reread(): Reread
+```
+
+Read the Source again. The Pool calls its `next`, or runs its `read`, at once; a read that runs
+now reads once more after it ends. Only a Source that can read gives it.
+
+**See also**
+
+- [Pools and Sources](../../concepts/pools-and-sources.md)

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

@@ -5,7 +5,7 @@ description: "Name an Effect secret: `secret(\"jira\")`."
 
 # `secret`
 
-Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ## Overload 1
 
@@ -56,13 +56,25 @@ And at `jr2 up`:
 **Example**
 
 ```ts
-import { command, fail, jr2Setup, secret, workspace, type Workspaced } from "@jr2/orchestrator";
+import {
+  command,
+  fail,
+  isReady,
+  jr2Setup,
+  secret,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
 
 type Input = Workspaced<{}, "app">;
 
+const deployTree = (context: Input) => `${context.workspace.repos.app}/deploy` as const;
+
 const body = jr2Setup({
   types: {} as { context: Input; input: Input },
   actors: {
+    cut: worktree(),
     // The command reads the file at $KUBECONFIG. The Agent never reads the secret.
     deploy: command(["kubectl", "apply", "-f", "k8s/"], {
       env: { KUBECONFIG: secret("kube").path },
@@ -73,17 +85,26 @@ const body = jr2Setup({
   id: "deploy",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "deploying",
+  initial: "cutting",
   states: {
-    deploying: { invoke: { src: "deploy", onDone: "done" } },
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: deployTree(context), branch: "deploy" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "deploying" }, { target: "notCut" }],
+      },
+    },
+    deploying: {
+      invoke: { src: "deploy", input: ({ context }) => ({ worktree: deployTree(context) }), onDone: "done" },
+    },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
 });
 
 export const machine = workspace(body, {
   repos: { app: { url: "https://github.com/you/app.git" } },
-  spec: () => ({ branch: "deploy" }),
 });
 ```
 

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

@@ -5,7 +5,7 @@ description: "A guard that is true for an event that one party sent, and false f
 
 # `sentBy`
 
-Function, in `@jr2/orchestrator/src/party.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Machine and events.
+Function, in `@jr2/orchestrator/src/party.ts`. It is an export of `@jr2/orchestrator`, in the [Machine and events](group-machine-and-events.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function sentBy<const Id extends string>(id: Id): { type: typeof SENT_BY; params: { id: Id } }

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

@@ -0,0 +1,22 @@
+---
+title: skip
+description: Bring nothing, and say why.
+---
+
+# `skip`
+
+Function, 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
+function skip(reason: string): Skip
+```
+
+Bring nothing, and say why. The reason goes in the Hook's answer and in its hook log.
+
+**Parameters**
+
+- `reason`: Why the delivery brings nothing, for a person to read.
+
+**See also**
+
+- [Pools and Sources](../../concepts/pools-and-sources.md)