@smthrs/flow 0.0.0-stage → 1.0.0-rc.12

package/docs/guides/cancel-and-roll-back.md

@@ -0,0 +1,112 @@
+---
+title: "Cancel a run and undo its effects"
+description: "Request cancellation of an execution, register a rollback for a successful effect, add a finalizer to the flow scope, and know which undo belongs to the engine."
+sidebar:
+  order: 9
+---
+
+Stopping a durable run and undoing what it already did are two separate jobs.
+This package gives you a request for the first and three mechanisms for the
+second, and each of the three covers a different kind of work.
+
+## Request cancellation
+
+```ts
+// `Checkout` is a flow declaration; the id names one of its executions.
+const stop = Checkout.interrupt("checkout-42")
+```
+
+`interrupt` is not a pause. The engine interrupts active work while preserving
+its normal cleanup, compensation, and child-flow semantics, and calling `resume`
+afterwards does not undo the cancellation request.
+
+A durable engine records the request **before** it interrupts anything, and
+reports `FlowRuntime.CancelRequestFailed` when that record could not be written.
+The execution is then still running, so the caller sees the storage failure
+instead of a false success. An in-memory engine has nothing to record and never
+raises it.
+
+The same failure carries `unsafe_interrupt_unsupported` when a durable engine is
+asked for `interruptUnsafe`, which it does not implement.
+
+## Undo a successful effect
+
+`Flow.withRollback` registers how to undo an effect's successful result if the
+current round later exits unsuccessfully:
+
+```ts
+import { Flow } from "@smthrs/flow"
+
+const reserved = Flow.withRollback(
+  reserveInventory(order),
+  (reservation, cause) => releaseInventory(reservation, cause)
+)
+```
+
+The three cases are worth stating exactly:
+
+- If the effect itself fails, no rollback is registered. There is nothing to undo.
+- If both the effect and the round succeed, the rollback is discarded.
+- If the effect succeeds and the round exits unsuccessfully, the rollback
+  receives the effect's successful value and the round's failure cause when
+  the scope closes.
+
+A handoff completes the round successfully and discards its `withRollback` registrations.
+Failure or cancellation in a later round cannot invoke those rollbacks. The
+engine does not provide lineage-scoped compensation; compensation across rounds
+requires an explicit durable design. These in-memory finalizers are not durable
+compensation records.
+
+This applies only to effects run directly inside the flow execution. It does
+**not** attach rollback behavior to nested actions. An action that changes the
+world undoes itself through its tier, which is the next section.
+
+`flow.withRollback` is the same function reachable off a flow declaration, typed
+with that flow's error channel.
+
+## Clean up on exit
+
+`Flow.addFinalizer` registers an exit finalizer on the flow scope, preserving the
+services available where it was registered:
+
+```ts
+import * as Effect from "effect/Effect"
+
+const withCleanup = Effect.gen(function*() {
+  const handle = yield* openHandle()
+  yield* Flow.addFinalizer(() => closeHandle(handle))
+  return handle
+})
+```
+
+Suspension keeps the current round's scope open for a re-drive of the same
+instance. Terminal completion closes it with the round's success or failure
+exit. Handoff closes it with a success exit and runs its finalizers; the next
+round has a fresh scope. `Flow.scope` and `Flow.provideScope` refer to this
+round's scope. Its resources and finalizers do not survive process death.
+
+## Let the engine undo the work
+
+An action whose body changes the workspace declares `tier: "compensable"`. The
+engine then takes a pre-image before each attempt and restores it before the
+next one, so an action that failed halfway through leaves nothing behind for
+attempt two to trip over. The undo is the engine's rather than the body's, and
+it needs a `FlowEngine.SnapshotBoundary` in context, which
+[`@smthrs/engine-store`](/api/engine-store) supplies.
+
+Choosing between the three:
+
+| The work                                               | The undo                                                                                                 |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| An action that writes to the workspace                 | `tier: "compensable"`. The engine snapshots and restores.                                                |
+| An action that changes the world outside the workspace | `tier: "irreversible"` plus an `idempotencyKey`. There is no undo, so the engine refuses to retry blind. |
+| An effect inside a handler                             | `Flow.withRollback`, or `Flow.addFinalizer` when the cleanup is unconditional.                           |
+
+## Related pages
+
+- [Attach an implementation to an action](./implement-an-action.md): choosing a
+  tier.
+- [Run a flow as a child execution](./run-a-child-flow.md): how cancellation
+  travels down a lineage.
+- [Suspension and replay](../concepts/suspension-and-replay.md): scope lifetime
+  across suspension, completion, and handoff.

package/docs/guides/implement-an-action.md

@@ -0,0 +1,155 @@
+---
+title: "Attach an implementation to an action"
+description: "Declare an action, write its implementation with toLayer, choose its tier, and compose the layers in the order the implementation table requires."
+sidebar:
+  order: 1
+---
+
+An action declaration holds no code. This guide attaches the code, picks the tier
+that describes what the code does to the world, and composes the layers in the
+one order that works.
+
+## Declare the action
+
+```ts
+import { Action } from "@smthrs/flow"
+import * as Schema from "effect/Schema"
+
+export class ChargeDeclined extends Schema.TaggedError<ChargeDeclined>()(
+  "payments/ChargeDeclined",
+  { reason: Schema.String }
+) {}
+
+export const Charge = Action.make("payments/Charge", {
+  payload: { customer: Schema.String, cents: Schema.Number },
+  success: Schema.String,
+  error: ChargeDeclined,
+  tier: "irreversible",
+  idempotencyKey: { charge: "checkout-v1" }
+})
+```
+
+The declared options are `payload`, `success`, `error`, `tier`,
+`idempotencyKey`, `nondeterministic`, and `annotations`. `success` defaults to
+`Schema.Void` and `error` to `Schema.Never`, so an action that declares no error
+schema cannot fail typed.
+
+## Write the implementation
+
+`toLayer` takes a function from the decoded payload to an effect and returns the
+layer that provides this declaration's requirement:
+
+```ts
+import * as Effect from "effect/Effect"
+
+export const charges = Charge.toLayer(({ cents, customer }) =>
+  Effect.gen(function*() {
+    const attempt = yield* Action.CurrentAttempt
+    const result = yield* chargeCard(customer, cents, { attempt })
+    return result.confirmation
+  })
+)
+```
+
+Inside the implementation you can read three references the runtime supplies:
+
+| Reference                     | What it carries                                                                |
+| ----------------------------- | ------------------------------------------------------------------------------ |
+| `Action.CurrentAttempt`       | The one-based durable attempt. Defaults to `1`.                                |
+| `Action.CurrentInvocationKey` | The persisted key of the dispatch, when the runtime supplies one.              |
+| `Action.CurrentOrdinal`       | The `OrdinalSlot` of the enclosing `Action.retry` sequence, when there is one. |
+
+The implementation may also require services of its own. Those requirements
+appear on the returned layer, so a composition that forgot a database client
+fails to compile the same way a missing action implementation does.
+
+## Choose the tier
+
+The tier tells the engine what retrying this action means. It is part of the step
+key, so it is not a hint.
+
+| Tier           | Choose it when                                        | What the engine does                                                                                                                                                                                                                                                                                     |
+| -------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sealed`       | The result is a pure function of the declared inputs. | Records the result and replays it. With the right declarations, reuses it across runs.                                                                                                                                                                                                                   |
+| `compensable`  | The body changes the workspace.                       | Takes a pre-image before each attempt and restores it before the next one, so attempt two does not trip over attempt one's half-written files. Requires a `FlowEngine.SnapshotBoundary` in context, which [`@smthrs/engine-store`](/api/engine-store) supplies, and a workspace that is a jj repository. |
+| `irreversible` | The body changes the world outside the workspace.     | Refuses to retry without a declared `idempotencyKey`, dying with `IrreversibleRetryRequiresIdempotencyKey`.                                                                                                                                                                                              |
+
+The `compensable` pre-image is a jj snapshot of the workspace, so the
+workspace must be a jj repository: run `jj git init` in it first. Without one,
+the step dies before its first attempt runs:
+
+```text
+@smthrs/jj/JjError: jj snapshot: Error: There is no jj repo in "."
+```
+
+`sealed` is the default, and it is a claim about the body: this result is worth
+replaying. Add `nondeterministic: true` when several legitimate results may race
+under one cache key, so a conflict is resolved first-writer-wins instead of being
+reported as a hermeticity violation. The flag is key material, so a tolerant
+declaration never consumes a strict declaration's recorded row.
+
+## Compose the layers
+
+Three rules, in the order they bite:
+
+```ts
+import { FlowEngine } from "@smthrs/engine"
+import { Interpreter } from "@smthrs/flow"
+import * as Layer from "effect/Layer"
+
+export const layer = Layer.mergeAll(
+  charges,
+  Interpreter.layer(Checkout)
+).pipe(
+  Layer.provideMerge(Action.layerImplementations),
+  Layer.provideMerge(FlowEngine.layerMemory)
+)
+```
+
+1. Merge the implementation layers beside `Interpreter.layer(flow)`. The
+   interpreter registers the flow and installs the handler that drives its body.
+2. Provide `Action.layerImplementations` **under** them with
+   `Layer.provideMerge`, never beside them. An implementation files itself in the
+   table while its own layer is built, so the table has to be built first.
+3. Provide the engine under that. Every declaration above it is engine agnostic.
+
+A second, different implementation of one tag dies during layer construction
+with `Action.DuplicateImplementation`. To substitute one on purpose, register it
+with `action.toLayer(handler, { override: true })`. The override shadows the
+earlier registration, and closing its scope restores what it shadowed. That is
+what lets a test scope an override to one block without leaking it into the
+next.
+
+## Skip the layer for a nested operation
+
+Not every durable step needs a declaration. Inside an implementation, the inline
+form of `Action.make` is itself an `Effect`, and the engine records it as a step
+of its own:
+
+```ts
+import { RetryPolicy } from "@smthrs/flow"
+
+const settle = Action.make({
+  name: "payments/Settle",
+  success: Schema.String,
+  error: Schema.String,
+  tier: "irreversible",
+  idempotencyKey: "settle:checkout-v1",
+  retryPolicy: RetryPolicy.make({ initialMs: 200, factor: 2, maxMs: 10_000, maxAttempts: 5 }),
+  execute: Effect.succeed("settled")
+})
+```
+
+Both forms take `retryPolicy` and `interruptRetryPolicy`; only the inline form
+takes `metadata`. The [`Action.make` reference](../reference/flow.md#actionmake)
+is the one option table. Reach for the inline form when an implementation needs
+a nested durable operation of its own; reach for the declared form when a body
+should name the step.
+
+## Related pages
+
+- [Flows and actions](../concepts/flows-and-actions.md): why the split exists.
+- [Retry a failing action](./retry-a-failing-action.md): what a policy does, and
+  where a policy can be declared.
+- [Reuse a recorded result](./reuse-a-recorded-result.md): the three declarations
+  a sealed result needs before it can be shared.

package/docs/guides/inspect-the-plan.md

@@ -0,0 +1,235 @@
+---
+title: "Inspect the plan a body builds"
+description: "Build a flow's graph without running it, read its nodes, edges, and diagnostics, and drive one interpretation to see what settled, failed, or was skipped."
+sidebar:
+  order: 11
+---
+
+Building a plan is a pure function of the declarations and the payload, so you
+can look at the whole shape of a round before its first step runs. That is the
+tool to reach for when a step key changed unexpectedly, when a branch took the
+arm you did not expect, or when you want to show an operator what a run is about
+to do.
+
+## Before you start
+
+The examples run with `node <file>.ts` on Node.js 26.4.0 or later and need no
+engine, database, or jj: planning reads declarations only. They import
+`@smthrs/flow` and `@smthrs/plan`. In a project that installed `@smthrs/flows`,
+add both at the version of `@smthrs/flows` you have:
+
+```bash
+npm install @smthrs/flow@1.0.0-rc.12 @smthrs/plan@1.0.0-rc.12
+```
+
+`@smthrs/flows` re-exports the same modules, so `import { Graph } from "@smthrs/flows"`
+and its `Plan.Node` work too. The outputs below are real output from 1.0.0-rc.6.
+
+## Build the graph
+
+Create `inspect.ts`. The flow runs two checks in parallel, joins them into a
+report, and then ships or explains:
+
+```ts
+import { Action, Flow, Graph } from "@smthrs/flow"
+import { Node } from "@smthrs/plan"
+import * as Schema from "effect/Schema"
+
+const Lint = Action.make("release/Lint", { payload: { target: Schema.String }, success: Schema.String })
+const Types = Action.make("release/Types", { payload: { target: Schema.String }, success: Schema.String })
+const Report = Action.make("release/Report", {
+  payload: { lint: Schema.String, types: Schema.String },
+  success: Schema.String
+})
+const Ship = Action.make("release/Ship", { payload: { report: Schema.String }, success: Schema.String })
+const Explain = Action.make("release/Explain", { payload: { reason: Schema.String }, success: Schema.String })
+
+const Release = Flow.make("release/Release", {
+  payload: { target: Schema.String },
+  success: Schema.String,
+  body: ({ target }) =>
+    Node.all({ lint: Lint.call({ target }), types: Types.call({ target }) }).pipe(
+      Node.bindPlanned((checks) => Report.call({ lint: checks.lint, types: checks.types })),
+      Node.branch({
+        if: (report) => report.includes("clean"),
+        then: (report) => Ship.call({ report }),
+        else: (reason) => Explain.call({ reason })
+      })
+    )
+})
+
+const graph = Graph.build(Release, { target: "web" })
+
+for (const node of Graph.nodes(graph)) {
+  console.log(`${node.id} ${node.kind} [${node.dependencies.join(", ")}]`)
+}
+
+for (const edge of Graph.edges(graph)) {
+  console.log(`${edge.from} -> ${edge.to} (${edge.reason})`)
+}
+```
+
+```bash
+node inspect.ts
+```
+
+```text
+root.flow.branch.andThen.all.lint ActionCall []
+root.flow.branch.andThen.all.types ActionCall []
+root.flow.branch.andThen All [root.flow.branch.andThen.all.lint, root.flow.branch.andThen.all.types]
+root.flow.branch.then ActionCall [root.flow.branch.andThen]
+root.flow.branch AndThen [root.flow.branch.andThen, root.flow.branch.then]
+root.flow.then ActionCall [root.flow.branch]
+root.flow.else ActionCall [root.flow.branch]
+root.flow Branch [root.flow.branch, root.flow.then, root.flow.else]
+root FlowCall [root.flow]
+root.flow.branch.andThen.all.lint -> root.flow.branch.andThen (value)
+root.flow.branch.andThen.all.types -> root.flow.branch.andThen (value)
+root.flow.branch.andThen -> root.flow.branch (value)
+root.flow.branch.andThen -> root.flow.branch.then (continuation)
+root.flow.branch.then -> root.flow.branch (value)
+root.flow.branch -> root.flow (value)
+root.flow.branch -> root.flow.then (continuation)
+root.flow.then -> root.flow (value)
+root.flow.branch -> root.flow.else (continuation)
+root.flow.else -> root.flow (value)
+root.flow -> root (value)
+```
+
+`Graph.build` takes a flow declaration or a bare node, the payload, and options.
+Nothing runs. It refuses a nesting depth past its bound and a duplicate node id,
+because a node id is durable dispatch identity and two nodes answering to one
+address would let a later settlement overwrite an earlier one.
+
+## What a node carries
+
+| Field                       | What it holds                                                                                                                 |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `id`                        | The structural address, which is what the durable step key is derived from.                                                   |
+| `kind`                      | The authoring variant it came from, not the plan's node kind. Every draft a graph produces is a plan `step`.                  |
+| `dependencies`              | The ids this node consumes.                                                                                                   |
+| `capabilities`, `placement` | The declarations lowered onto it.                                                                                             |
+| `draft`                     | The `Plan.NodeDraft` the plan is compiled from.                                                                               |
+| `ast`                       | The authoring node it was observed at, so a driver can reach the real mapper, predicate, and member names.                    |
+| `payload`                   | What the node passes on, hydrated: real data where the author wrote data, and a planned placeholder where a step result goes. |
+
+Nodes come back with children before the parents that consume them. An `Edge`
+points from the node that produces to the node that consumes, and its `reason` is
+`value` for a consumed result, `continuation` for the sequencing edge a builder
+or branch arm records, or `failure` for a recovery arm.
+
+## Read the diagnostics
+
+`Graph.inspect(flow)` exports JSON-safe nodes, edges, steps, diagnostics and,
+for prompt declarations, the renderer's source. It supplies an unresolved
+`Planned` input and uses the same graph builder. It never runs an action or
+renders a prompt. Repository declarations must still be inspected in their
+guest, because building a graph calls their plan-time bodies.
+
+Inspect `diagnostics` before interpreting the steps. A body that computes on its
+input can require a real payload; inspection reports `declaration_requires_input`
+and shows the declaration as one opaque flow boundary, without declaring it
+unloadable or borrowing another version’s steps. Use `Graph.build(flow, payload)` to plan
+that invocation. Symbolic inputs have the same restrictions as planned step
+results: use node combinators for branching, not JavaScript truthiness or
+reference comparisons. Prompt source is code for inspection, not a rendered
+prompt or an executable browser artifact.
+
+`Graph.diagnostics(graph)` holds the recoverable topology issues, such as a
+missing continuation builder or a continuation that produced no node. Fatal
+refusals, including computing on a planned value and a recursive inline `call`,
+throw from `Graph.build` and never appear here.
+
+A graph carrying diagnostics is inspectable but deliberately not compilable, so
+`Graph.drafts(graph)` throws the first typed build refusal rather than returning
+partial drafts. Check diagnostics before asking for drafts:
+
+```ts
+const issues = Graph.diagnostics(graph)
+if (issues.length === 0) {
+  const drafts = Graph.drafts(graph) // ready for Plan.compile or Plan.append
+  console.log(`${drafts.length} drafts`)
+}
+```
+
+Appended to `inspect.ts`, it prints `9 drafts`: one per node above.
+[Diff two plans](../../../plan/docs/guides/diff-two-plans.md) compiles drafts like
+these and compares two versions of a flow.
+
+## Resolve layers while building
+
+`BuildOptions.resolveLayers` is invoked once per node and is told a
+`LayerRequest`: the node id, its authoring kind, its capabilities, its declared
+effects, and its placement. It answers the identity of the implementation the
+node would run against, never a layer value or a runtime handle:
+
+```ts
+const planned = Graph.build(Release, { target: "web" }, {
+  resolveLayers: (request) => request.capabilities.map((name) => `layer:${name}`),
+  root: "root"
+})
+```
+
+The resolver must be pure. Planning performs no input or output, and a resolver
+that read the world would make a plan a function of more than its declarations.
+`root` defaults to `"root"` and names the address the walk starts from.
+
+## Drive one interpretation
+
+`Interpreter.interpret` builds the graph and walks it against real values,
+without registering the flow. It is the walk `Interpreter.layer` runs for each
+round of an execution, and it requires the `FlowInstance` the runtime provides
+to an executing round, so a program reaches it through `execute` rather than by
+calling it at top level. It answers an `Interpretation`:
+
+```ts
+interface Interpretation {
+  /** The root's value. */
+  readonly value: unknown
+  /** Every node that settled. */
+  readonly settled: ReadonlyMap<string, unknown>
+  /** The typed failures observed before a catch recovered them. */
+  readonly failed: ReadonlyMap<string, unknown>
+  /** The nodes a branch went the other way on. */
+  readonly skipped: ReadonlyArray<string>
+}
+```
+
+`skipped` is the field that answers "why did nothing happen here". The walk is
+demand driven from the root rather than a sweep over the node list, because
+dependency order puts both branch arms before the branch that chooses between
+them, and executing an arm to discover it was not taken is exactly what static
+topology exists to avoid.
+
+## The refusals the interpreter reports
+
+`Interpreter.InterpreterError` carries a stable `code`, the flow, and the node:
+
+| Code                              | What it means                                                                        |
+| --------------------------------- | ------------------------------------------------------------------------------------ |
+| `incomplete_graph`                | The build reported topology it could not complete.                                   |
+| `duplicate_node_id`               | Two nodes answer to one dispatch address.                                            |
+| `unresolved_action`               | An action the body names has no implementation wired up.                             |
+| `implementation_version_mismatch` | A declaration and its registered implementation disagree on `implementationVersion`. |
+| `missing_implementation_version`  | A content-reusable sealed action declares no `implementationVersion`.                |
+| `unresolved_reference`            | A payload reads a node this graph does not hold.                                     |
+| `unsupported_call`                | A call whose declaration did not survive serialization.                              |
+| `missing_operation`               | A deferred function that did not survive serialization.                              |
+
+Missing mappers, branch predicates, and catch schema filters are refused before
+any action dispatch, including operations in untaken arms. `Node.catch` cannot
+recover an `InterpreterError`, even without an error schema.
+
+`unresolved_action` is the one an author meets most: it means a layer is missing
+from the composition, or `Action.layerImplementations` was merged beside the
+implementation layers instead of provided under them.
+
+## Related pages
+
+- [Diff two plans](../../../plan/docs/guides/diff-two-plans.md): compile two
+  versions of a flow and see which steps were added, removed, or re-keyed.
+- [Bodies are plans](../concepts/bodies-and-plans.md): why the build is pure and
+  what it refuses.
+- [Execution identity](../concepts/execution-identity.md): how a node id becomes
+  a durable step key.
+- [Troubleshooting](../troubleshooting.md): the same refusals, sorted by symptom.

package/docs/guides/poll-until-ready.md

@@ -0,0 +1,169 @@
+---
+title: "Poll until something is ready"
+description: "Declare a durable poller whose attempts are rounds and whose waits are durable timers, choose its backoff and bound, and put a time limit on a check that can hang."
+sidebar:
+  order: 7
+---
+
+`Poll.make` declares an ordinary flow whose body is **one attempt**: run the
+check, and either settle the lineage with the check's own output or sleep for
+this attempt's delay and hand off to the next round with the attempt counter
+raised.
+
+That shape is what makes a poll durable. Each attempt is a round with its own
+keyed plan nodes, a check that already ran replays from its recorded outcome, and
+the wait between attempts is a durable timer that survives a process restart.
+
+## Declare the poll
+
+```ts
+import { Action, Interpreter, Poll, Sleep } from "@smthrs/flow"
+import { Node } from "@smthrs/plan"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+
+const Status = Action.make("deploy/Status", {
+  payload: { id: Schema.String, attempt: Schema.Number },
+  success: Poll.CheckResult(Schema.String)
+})
+
+export const Deployment = Poll.make("deploy/Wait", {
+  input: { id: Schema.String },
+  result: Schema.String,
+  intervalMs: 5_000,
+  backoff: "exponential",
+  maxAttempts: 8,
+  onTimeout: "fail",
+  check: Node.capture(
+    { action: Status.name, implementationVersion: "deploy/status-check/v1" },
+    ({ attempt, id }) => Status.call({ attempt, id })
+  )
+})
+
+export const layer = Interpreter.layerWithImplementations(
+  Deployment,
+  Layer.mergeAll(
+    Status.toLayer(({ attempt, id }) =>
+      Effect.map(readDeployment(id), (live) => ({
+        satisfied: live,
+        output: `attempt-${attempt}`
+      }))
+    ),
+    Poll.layer,
+    Sleep.layer
+  )
+)
+```
+
+`check` must be capture-stable under the default policy of
+`Interpreter.layerWithImplementations`. Use `Node.capture` with every semantic
+capture and a version for imported behavior. Capture any mappers, predicates,
+or planned continuations inside the check as well. JavaScript cannot verify
+closure completeness. `Poll.make` captures its generated body and predicate
+using the schedule and `Node.functionIdentity(check)`. An uncaptured check keeps
+the poll process-local and stable admission refuses it. Explicit
+`callbackIdentity: "process-local"` allows experimentation without a
+cross-process callback identity guarantee.
+
+`Sleep.layer` is not optional. The wait between attempts is an ordinary
+`system/sleep` node, so a composition without it has a plan node no
+implementation answers. `Poll.layer` implements the `system/poll-exhausted` step
+the last unsatisfied attempt takes.
+
+## The options
+
+| Option        | Meaning                                                                                                                                           |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `input`       | Your payload fields. `attempt` is added to them and defaults to one.                                                                              |
+| `result`      | The schema the poll settles with.                                                                                                                 |
+| `check`       | A body fragment returning `{ satisfied, output }`. It may not fail: state what a failure means with `Node.catch` inside the fragment.             |
+| `intervalMs`  | The base wait before the next attempt.                                                                                                            |
+| `backoff`     | `fixed`, `linear` (interval multiplied by attempt), or `exponential` (interval multiplied by 2 raised to attempt minus one). Defaults to `fixed`. |
+| `maxAttempts` | The attempt bound. It is also the flow's `maxRounds`, so a lineage that opened another round is refused by the engine.                            |
+| `onTimeout`   | `fail` fails `PollExhausted` at the bound; `return-last` answers with the last check output. Defaults to `fail`.                                  |
+
+`Poll.CheckResult(schema)` is the success schema a check action declares, and
+`Poll.delayMillis` is the exported schedule function if you want to compute the
+same delays yourself.
+
+## What a bad schedule earns
+
+`Poll.make` refuses a schedule no clock can keep, at declaration time, naming the
+option that is wrong:
+
+- A `TypeError` when `input` declares the reserved `attempt` field. `Poll` owns
+  that counter across rounds.
+- A `RangeError` when `intervalMs` is not a finite number of milliseconds that is
+  not negative, because that interval becomes a `system/sleep` node whose timer
+  never fires.
+- A `RangeError` when `maxAttempts` is not a whole number of attempts of at least
+  one. A poll checks at least once.
+- A `RangeError` when the interval under the declared backoff reaches a wait no
+  clock can be armed with before the budget is spent.
+
+That last check is on the whole schedule rather than on the interval alone,
+because the backoff multiplies the interval:
+`{ intervalMs: 1000, maxAttempts: 2000, backoff: "exponential" }` states three
+finite options and still asks for a wait of `Infinity`. The check looks at the
+last wait a poll can arm, the one before the final attempt, since the attempt at
+the budget gives up rather than sleeps. That wait must also be at most
+`Number.MAX_SAFE_INTEGER` milliseconds, the latest deadline a durable timer
+records, so a one-millisecond interval doubling allows at most 54 attempts.
+
+## Handle exhaustion
+
+Under `onTimeout: "fail"` a spent budget fails `Poll.PollExhausted`, carrying the
+poll name and the attempt count under the stable code `poll_exhausted`. A body
+catches it like any other declared failure.
+
+`Poll.Failure` is the union a poll's rounds can fail with, and it includes
+`Sleep.SleepRequestInvalid` as well: the wait between attempts is an ordinary
+sleep node, and a round payload can carry an attempt that derives an invalid
+wait.
+
+## Bound a check that can hang
+
+There is deliberately no per-attempt time limit option. A plan node's duration is
+not something the body around it can bound, so the bound goes in the check's own
+implementation, where a durable race puts it on the recorded step:
+
+```ts
+import { DurableClock, DurableDeferred } from "@smthrs/flow"
+import * as Duration from "effect/Duration"
+
+const statusLayer = Status.toLayer(({ attempt, id }) =>
+  DurableDeferred.raceAll({
+    name: `deploy/status#${attempt}`,
+    success: Poll.CheckResult(Schema.String),
+    error: Schema.Never,
+    effects: [
+      readDeploymentStatus(id),
+      Effect.as(
+        DurableClock.sleep({
+          name: `deploy/status#${attempt}`,
+          duration: Duration.seconds(30),
+          inMemoryThreshold: Duration.zero
+        }),
+        { satisfied: false, output: "unknown" }
+      )
+    ]
+  })
+)
+```
+
+Three things make that the durable bound rather than a wall-clock one:
+
+1. The race records its winner under a name carrying the attempt, so a re-driven
+   round reads the recorded outcome instead of racing again.
+2. The clock parks the execution rather than holding a fiber, so the bound
+   outlives the process waiting on it.
+3. The clock's branch answers `satisfied: false`, so a check that ran out of time
+   costs the poll one attempt and nothing else. The round takes its declared
+   interval and hands off exactly as an unsatisfied check does.
+
+## Related pages
+
+- [Trampoline rounds](../concepts/trampoline-rounds.md): the lineage machinery a
+  poll is built out of.
+- [Wait for a deadline](./wait-for-a-deadline.md): the timer the interval arms.