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

package/docs/concepts/bodies-and-plans.md

@@ -0,0 +1,157 @@
+---
+title: "Bodies are plans"
+description: "Why a flow body runs at plan time, what a planned value is and the one rule it obeys, and how branches, fan-out, and recovery stay static topology."
+sidebar:
+  order: 2
+---
+
+A flow's `body` is a pure function from the decoded payload to a
+[`Node`](/api/plan). Calling it builds topology. It runs nothing, reads nothing,
+and returns a description that `Graph.build` can walk without dispatching a
+single step.
+
+A flow authored with `prompt` has the same body contract: `Flow.make` supplies
+a body that records one ordinary action call. Planning never renders the prompt
+or calls a model. The host implements the exposed `flow.action` and renders
+`flow.prompt` with the decoded payload when that action runs.
+
+Reproducible plans require complete, stable declaration identities as well as
+the same payload. Use `Node.capture` to declare semantic captures and imported
+implementation versions, and select stable callback validation. The low-level
+process-local callback policy permits inspection but does not promise the same
+plan across processes. Stable node addresses alone do not prove unchanged
+behavior.
+
+## What a body may not do
+
+The body's source digest enters the flow's content identity, so the body must not
+depend on anything the digest cannot observe. In practice:
+
+- No mutable module state, clocks, random values, services, or environment
+  values captured outside `payload`.
+- No conditionals on a step result written as ordinary JavaScript. A decision
+  between two continuations is `Node.branch`, which stores both arms.
+- No work that genuinely wants opaque code. That work is an action, and its
+  implementation attaches as a layer.
+
+`Flow.make` cannot enforce purity or verify capture completeness. An omitted
+semantic input can change behavior without changing a key, allowing stale
+replay. Do not rely on a key mismatch to detect undeclared behavior changes.
+
+## Planned values
+
+The payload a body receives is real data. Every step result inside it is a value
+that does not exist yet, and the body sees it as a `Planned` placeholder.
+
+A planned value obeys one rule: **pass it, never compute on it.** Passing it into
+a payload field, into a branch, or into a `map` is fine, and field access is
+allowed because it records a reference path rather than reading anything.
+
+```ts
+import { Node } from "@smthrs/plan"
+
+// Allowed: the placeholder is passed on, and `report.summary` records a path.
+Build.call({ target: "site" }).pipe(
+  Node.bindPlanned((report) => Publish.call({ summary: report.summary }))
+)
+```
+
+Misuse fails twice, and both failures are deliberate. `Planned` is branded, so
+arithmetic and template interpolation are compile errors. At run time the
+placeholder is a strict proxy whose `Symbol.toPrimitive`, `valueOf`, `toString`,
+`toJSON`, and call traps throw a `GraphBuildError` with the code
+`planned_value_computed`, rather than let a plan be built around `NaN` or
+`"[object Object]"`.
+
+Two operations JavaScript exposes no trap for, `Boolean(value)` and strict
+identity, cannot be refused at run time. They reveal only the proxy's truthiness
+or identity, never the result. Decide on real values with `Node.branch`.
+
+## The node vocabulary
+
+A body is written in [`@smthrs/plan`](/api/plan)'s `Node` combinators, and each
+one has a job:
+
+| Combinator                                | What it is for                                                                                                             |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `Node.succeed(value)`                     | A constant, for a body that settles without a step.                                                                        |
+| `Node.all({ ... })`                       | Independent children, settled concurrently, keyed by name. Width is fixed here, at plan time.                              |
+| `Node.map(node, f)`                       | Computation on a step result. The function is digested, not run; it executes later on the real value.                      |
+| `Node.andThen(node, next)`                | A success barrier: no part of the next subtree starts until the first node succeeds. Bound long chains as described below. |
+| `Node.bindPlanned(node, build)`           | Builds data dependencies from a placeholder. Independent descendants may run concurrently with the producer.               |
+| `Node.branch(node, { if, then, else })`   | A decision. Both arms are built once at plan time and both are stored.                                                     |
+| `Node.catch(node, { onFailure, error? })` | Recovery. The failure arm is topology too, and a schema narrows which failures it handles.                                 |
+| `Node.priority(node, n)`                  | Scheduling order for ready work. It never enters key material, so raising it cannot invalidate a recorded result.          |
+
+Nested explicit `andThen` subtrees carry only their nearest success barrier.
+That prerequisite already depends on the outer barriers, so ordering remains
+transitive and a right-nested chain has linear continuation edges and `Pending`
+inputs.
+
+Structural node IDs retain the `.andThen` and `.then` path segments because
+these addresses participate in durable dispatch identity. Each ID grows with
+nesting depth, and total ID bytes in a sequential chain grow quadratically,
+including fluent left-nested chains. Plans repeat IDs in inputs and dependency
+lists. Split long chains into bounded [trampoline rounds](./trampoline-rounds.md)
+or `.child()` flow boundaries; shorter barrier lists do not bound ID bytes.
+
+A `map` that decides what happens next is a `branch` written wrongly. Both a
+branch's arms and a catch's failure arm contribute their requirements to the
+node, because both are topology the plan carries: a run takes one of them, but
+which one is not known until the predicate sees the real value.
+
+## Fixed width, and what to do instead
+
+`Node.all` settles its members concurrently with no bound, and the member set is
+fixed when the plan is built. Fanning out over something a step discovered is not
+this. End the round and carry the list in the next flow's payload, where it is
+real data. See [Trampoline rounds](./trampoline-rounds.md).
+
+For explicit batches, sequence whole `Node.all` subtrees with `Node.andThen`.
+Members within an opened batch remain concurrent. A `bindPlanned` reference
+orders its consumers, not every independent member of the continuation; it is
+not a whole-batch admission barrier. This manual batching is distinct from the
+compiled scheduler's admission caps, which the public interpreter does not yet
+consume.
+
+## What the build refuses
+
+`Graph.build` reports what it can and throws what it cannot. Recoverable topology
+issues land in `Graph.diagnostics(graph)`, and a graph carrying diagnostics is
+inspectable but deliberately not compilable, so an incomplete body is reported
+rather than half-driven.
+
+Fatal refusals throw a `GraphBuildError` naming the site and the fix. The ones an
+author meets are:
+
+| Code                                                   | What happened                                                                                                          |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `planned_value_computed`                               | A body computed on a step result.                                                                                      |
+| `invalid_all_member`, `invalid_continuation`           | An `all` member or a branch arm was not a node.                                                                        |
+| `invalid_join`                                         | A race, any, or quorum had a non-node member, no members, or a quorum count its members cannot reach.                  |
+| `recursion_requires_boundary`                          | A flow called itself inline. Use `flow.to` or `flow.child`.                                                            |
+| `placement_requires_boundary`                          | An inline callee declares a placement the caller cannot satisfy. Use `flow.child`.                                     |
+| `duplicate_node`                                       | Two structural addresses resolved to one durable node id, which would let a later settlement overwrite an earlier one. |
+| `graph_too_deep`, `payload_too_deep`, `cyclic_payload` | Topology or payload past the build bound, or a payload that contains itself.                                           |
+| `invalid_priority`, `invalid_payload`                  | A priority that is not a safe integer, or a payload member that cannot be captured as inert JSON.                      |
+
+The two depth refusals exist because the build walks with an explicit stack and
+refuses at a bound, rather than recursing until the native stack overflows
+without a typed error.
+
+## The walk
+
+`Interpreter.interpret` builds the graph in full and then drives it, demand
+driven from the root rather than as a sweep over the node list. 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.
+
+## Related pages
+
+- [Compose a body from branches and fan-out](../guides/build-a-body.md): the same
+  vocabulary as worked code.
+- [Inspect the plan a body builds](../guides/inspect-the-plan.md): read nodes,
+  edges, and diagnostics before anything runs.
+- [Execution identity](./execution-identity.md): how a node address becomes a
+  durable step key.

package/docs/concepts/execution-identity.md

@@ -0,0 +1,142 @@
+---
+title: "Execution identity"
+description: "How a run gets its execution id, how one dispatch gets its step key, and what enters each of those keys."
+sidebar:
+  order: 3
+---
+
+Durability is identity. A re-driven run reads a recorded result only if it asks
+under the same name, so this package is careful about two names: the id of a
+whole execution, and the key of one dispatch inside it.
+
+## The execution id
+
+`Flow.execute` resolves identity from the first source that has one:
+
+1. The `executionId` the caller named on `execute`.
+2. The flow's declared `idempotencyKey`, JSON-tuple framed with the flow tag and
+   hashed.
+3. The ambient `Flow.CurrentExecutionIds` source. Its default, `Flow.fresh`,
+   mints a cryptographic UUID, so equal unkeyed requests start independent work.
+
+A declared key beats the ambient source because it is the narrower statement:
+this author said what makes two invocations of _this_ flow the same, where the
+source is the host's blanket answer for every flow it drives. Both preimage
+encodings freeze at rc.0, and neither applies Unicode normalization.
+
+Install `Flow.derived` explicitly when equal encoded payloads of one flow are
+one piece of work. It encodes the payload with the flow's own codec,
+canonicalizes it under RFC 8785, hashes it, and hashes that together with the
+flow tag:
+
+```ts
+const derivedIdentity = Flow.layerExecutionIds(Flow.derived)
+```
+
+Install the deterministic `derived` source only when equal payloads deliberately
+identify one request. Its existing codec, canonicalization and hash framing are
+unchanged, so this is also the migration path for callers that need to reattach
+to historical automatically derived executions.
+
+```ts
+import { Flow } from "@smthrs/flow"
+
+const intentionalPayloadIdentity = Flow.layerExecutionIds(Flow.derived)
+```
+
+`flow.start(payload)` always creates fresh work and returns its id, including
+when the declaration carries an idempotency key. `flow.ensure(payload, { key })`
+returns the id of an explicitly keyed new or existing execution. After a crash,
+reattach with the saved id or the same explicit key; calling unkeyed `execute`
+again starts new work. Read a run with `poll(id)`, or await it with
+`execute(payload, { executionId: id })`.
+
+Callers that name an `executionId` and flows that declare an `idempotencyKey` are
+unaffected, because both are decided before the source is consulted.
+
+### When identity cannot be derived
+
+`Flow.ExecutionIdRequired` is a defect, not a typed failure. The opt-in derived source raises it when the payload has no canonical
+form: a non-finite number, a lone surrogate, or a cycle. Derivation fails before the
+engine is invoked, because a run under the wrong id is worse than a run that
+does not start.
+
+`Flow.executionId(payload)` asks the configured source for an id. With the fresh
+source, pass that returned id explicitly to `execute`; asking again mints a new id. It dies when the payload
+fails the flow's own schema, where `Flow.execute` fails with a typed
+`Schema.SchemaError` for the same input. Precompute an id only for a payload you
+have already validated. Identity and `tokenFromPayload` helpers carry the payload schema's
+`EncodingServices` requirement because the ambient source may encode the payload.
+
+### Child executions
+
+A `flow.child(payload)` boundary derives its child's id from the parent
+execution id, the node's address, the callee tag, and a digest of the payload.
+`Interpreter.childExecutionId` is that derivation, exported so a host can name a
+child the same way the interpreter does. Because the id is derived from the
+node's address rather than minted, a re-driven parent lands on the child it
+already started.
+
+## The step key
+
+Inside one execution, every dispatch is recorded under a key derived from three
+things.
+
+**The allocation scope** comes from `StepIdentity.AllocationIdentity`: the `kind`
+(`action` for user dispatches, `internal` for engine-owned operations, which own
+disjoint counter namespaces), the declaration `name`, an optional `idempotency`
+refinement, and the optional `site`, which is the replay-stable address of the
+graph node driving the dispatch. Distinct graph sites are distinct scopes, so two
+call sites of one declaration never contend for one counter.
+
+**The ordinal** is allocated per scope and pinned by dispatch position.
+`Action.CurrentOrdinal` carries an `OrdinalSlot` (`{ values, cursors }`) rather
+than a number, which is what lets every attempt of one `Action.retry` sequence
+reuse its own action's ordinals even when the block dispatches several
+declarations. A nested block shares the pinned `values` with the enclosing block
+and owns a private `cursors` view seeded at entry and merged back on exit, so a
+concurrent sibling never rewinds another block's mid-flight cursor.
+
+**The tier** distinguishes an unsealed key from a compensable or irreversible
+one. `StepIdentity.invocationKey` is the single derivation.
+
+Concurrent dispatch of one allocation scope is refused with
+`Action.ConcurrentKeylessDispatch`, because arrival order would otherwise decide
+which fiber got which ordinal, and with it which attempt row and which recorded
+outcome. Only a sealed action with a declared `idempotencyKey` is exempt: that
+key is a pure cache key rather than an ordinal, and distinct keys are distinct
+scopes that overlap freely.
+
+## What enters a sealed action's cache key
+
+A sealed action's recorded result can be replayed, and with the right
+declarations reused. What the key covers is deliberate:
+
+- **Caller-owned identity.** A string `idempotencyKey` is namespaced by the
+  action name and the declared schemas. An object key is caller-owned canonical
+  JSON and stays stable across an action rename. An object key carrying material
+  canonical serialization rejects, such as a `Date`, an `undefined`, a class
+  instance, or a `Redacted`, is refused with `Action.UncanonicalIdempotencyKey`
+  naming the offending path, and the refusal is not retryable because the same
+  declaration derives it on every attempt.
+- **Runtime facts the engine adds.** The complete `Action.CacheEnvironment`
+  (`layers` and `capabilities`) and any file boundary derived from the action's
+  `metadata`. The engine adds these separately, so caller identity cannot
+  override them. When the environment is absent, the engine scopes the key to the
+  current execution rather than presenting incomplete data as reusable identity.
+
+A flow call node folds the declared schemas into its key material as their JSON
+Schema documents, so changing what a callee accepts or produces re-keys the call.
+The limit is worth stating plainly: two schemas whose decoders disagree can
+serialize to the same document, so changing only a codec's behavior does **not**
+re-key the call, and a result recorded under the old codec is replayed under the
+new one. Effect codecs are not serializable, so nothing can close this
+automatically. Rename the declaration when a transformation changes and the call
+has to be re-keyed.
+
+## Related pages
+
+- [Reuse a recorded result](../guides/reuse-a-recorded-result.md): cache policy,
+  scope, and the three declarations a shareable result needs.
+- [Suspension and replay](./suspension-and-replay.md): what a replay actually
+  does with these keys.

package/docs/concepts/flows-and-actions.md

@@ -0,0 +1,129 @@
+---
+title: "Flows and actions"
+description: "The two nouns of the authoring model: an action carries an implementation attached as a layer, a flow carries a pure body, and the requirement channel is what connects them."
+sidebar:
+  order: 1
+---
+
+The package has two nouns and one rule about each.
+
+- An **action** is the atom that does the work. It carries an implementation,
+  and that implementation attaches separately, as a layer.
+- A **flow** is the composite. It carries a `body`, and never opaque executable
+  code.
+
+A typed `prompt` declaration lowers to a flow whose body calls one ordinary
+action. The host attaches the model implementation to `flow.action`; the
+renderer is `flow.prompt`. See [Prompt-backed flows](../guides/use-a-prompt.md).
+
+Everything else follows from that split, including the surprising part: there is
+no `toLayer` on a flow. A flow has exactly one behavior and it is the body, so
+there is no second behavior to attach.
+
+## Two forms of action
+
+`Action.make` selects its form by whether the first argument is a string.
+
+The **declared** form is the one you write in a body. It is pure data: a tag,
+schemas, a tier, and optional identity. It holds no code.
+
+```ts
+import { Action } from "@smthrs/flow"
+import * as Schema from "effect/Schema"
+
+export const Charge = Action.make("payments/Charge", {
+  payload: { customer: Schema.String, cents: Schema.Number },
+  success: Schema.String,
+  tier: "irreversible",
+  idempotencyKey: { charge: "checkout-v1" }
+})
+```
+
+The **inline** form carries its `execute` effect directly and is itself an
+`Effect`. It is what an implementation reaches for when it needs a nested durable
+operation of its own, and it is what `Action.retry` and `Action.raceAll` take.
+
+```ts
+import * as Effect from "effect/Effect"
+
+const probe = Action.make({
+  name: "payments/Probe",
+  success: Schema.String,
+  execute: Effect.succeed("ok")
+})
+```
+
+## The requirement channel
+
+`Action.make(tag, ...)` mints one context key for that declaration, derived from
+the tag. `Charge.call(payload)` records a node whose type carries that key.
+`Flow.make` reads the union of those keys off the node its body returns, so a
+flow states in its own type which implementations it names and does not hold:
+
+```ts
+Checkout.execute({ customer: "ada", cents: 4_200 }, { executionId: "checkout-1" })
+// Effect<string, ..., FlowRuntime | Crypto.Crypto | Action.Requirement<"payments/Charge">>
+```
+
+`Charge.toLayer(...)` provides that key. A composition missing an implementation
+therefore fails to compile at the call site instead of dying partway through a
+run. Planning stays requirement-free: building the plan a body describes asks for
+no service at all, and `execute` is the one place the obligations are collected.
+
+Three propagation rules follow from where a plan actually goes:
+
+| Where                                        | What happens to the requirement                                                                                                                      |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `flow.call(payload)`                         | Propagates. The callee's steps join the caller's plan, so its obligations are the caller's.                                                          |
+| `flow.child(payload)` and `flow.to(payload)` | Dropped. Each opens a new execution whose own driver supplies its context. Dropping at `to` is also what keeps a self-looping lineage's type finite. |
+| `poll`, `interrupt`, `resume`                | Not collected. The first two never drive a body, and a re-driven round runs under the context the flow was registered with, not the resumer's.       |
+
+## System actions mint nothing
+
+`Action.makeSystem` is the declared form with the requirement erased. `Sleep`,
+`WaitFor`, `HumanTask`, and `Poll`'s exhaustion step all use it, so a body that
+waits pushes no layer obligation onto its callers. The engine owns those
+implementations, and an author cannot be the party who forgot them. You still
+provide `Sleep.layer` or `WaitFor.layer` in the composition; the compiler does
+not force you to.
+
+## The name-keyed table
+
+The requirement is the compile-time half. `Action.Implementations` is the
+run-time half: a table keyed by action tag that `toLayer` files itself into. A
+driver expanding a plan it read back out of a journal has no types left to
+consult, so it resolves by tag.
+
+That is why `Action.layerImplementations` goes **under** the implementation
+layers rather than beside them:
+
+```ts
+import { Interpreter } from "@smthrs/flow"
+import * as Layer from "effect/Layer"
+
+Layer.mergeAll(Charge.toLayer(chargeCard), Interpreter.layer(Checkout)).pipe(
+  Layer.provideMerge(Action.layerImplementations)
+)
+```
+
+Filing an implementation happens while its layer is built, so the table has to
+exist first. The table is optional: a composition that only executes handlers
+registered directly with the runtime never needs it.
+
+## Tiers
+
+Every action declares a `tier`, which tells the engine what a retry of it means.
+
+| Tier           | Meaning                                                                                                                                                                 |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sealed`       | The default. The result is a pure function of the inputs, so a recorded result can be replayed and, with the right declarations, reused across runs.                    |
+| `compensable`  | The body changes the workspace. The engine takes a pre-image before an attempt and restores it before the next one, so the undo is the engine's rather than the body's. |
+| `irreversible` | The body changes the world outside the workspace. Retrying one without a declared `idempotencyKey` fails with `IrreversibleRetryRequiresIdempotencyKey`.                |
+
+## Related pages
+
+- [Bodies are plans](./bodies-and-plans.md): what a body may and may not do.
+- [Attach an implementation to an action](../guides/implement-an-action.md): the
+  layer, the tier, and the ordering rules, in one place.
+- [The runtime port](./the-runtime-port.md): what an engine has to supply for any
+  of this to run.

package/docs/concepts/suspension-and-replay.md

@@ -0,0 +1,130 @@
+---
+title: "Suspension and replay"
+description: "The three results a flow settles with, what parking on a durable wait actually does, and what a re-driven round replays."
+sidebar:
+  order: 4
+---
+
+A flow round settles with one of three results, and the difference between them
+is the whole durability story.
+
+| Result           | Meaning                                                                           |
+| ---------------- | --------------------------------------------------------------------------------- |
+| `Flow.Complete`  | The round finished. It carries an `Exit`, so a typed failure is a completion too. |
+| `Flow.Suspended` | The round parked on a durable wait and will be re-driven.                         |
+| `Flow.Handoff`   | The round ended by handing off to the next round of a trampoline lineage.         |
+
+`Flow.isResult` is the guard, `Flow.Result({ success, error })` builds the schema,
+and `Flow.ResultEncoded` is the stored form.
+
+## What parking does
+
+A durable wait is not a held fiber. When a body reaches `Sleep.action`,
+`WaitFor.action`, `HumanTask.action`, or an unresolved `DurableDeferred`, the
+implementation declares how it is about to wait through
+`FlowRuntime.annotateWaiting` and then suspends. The engine records a waiting row
+carrying that annotation and releases the run. The process can exit.
+
+A `WaitingAnnotation` is `{ reason, wakeAt?, token? }`, and the reason is what an
+operator reads off the run:
+
+| Reason     | Declared by                                                         |
+| ---------- | ------------------------------------------------------------------- |
+| `timer`    | `Sleep`, with the deadline as `wakeAt`.                             |
+| `event`    | `WaitFor`, carrying the wake token a completion is matched against. |
+| `approval` | `HumanTask`, carrying the current attempt's token.                  |
+
+`execute(payload, { discard: true })`, `start(payload)`, and
+`ensure(payload, { key })` acknowledge admission without awaiting the result;
+the run can stay parked after the caller receives its execution id.
+Ordinary `execute` follows the run instead: a parked run keeps its caller waiting.
+`flow.poll(executionId)` answers `Option.none` for a run that is known and has
+not settled. An id the
+runtime never recorded is `FlowRuntime.FlowExecutionNotFound` instead, which is a
+different fact and a different failure.
+
+## What a re-drive replays
+
+`flow.resume(executionId)` re-drives a suspended execution. The round starts over
+from the top of the body, which is safe precisely because the body is a plan:
+
+1. The graph is rebuilt. Same declarations, same payload, same node addresses.
+2. Every node whose result the engine already recorded settles from that record.
+   No dispatch happens.
+3. The walk reaches the node that was unsettled and drives it. If its wait is now
+   resolved, the recorded completion is what it reads.
+
+Nothing about a resume collects the flow's requirements. The runtime captures the
+context a flow was registered under and merges it beneath whatever the run
+supplies, so the implementations that made the first round possible are the ones
+a re-driven round reaches. A party holding an execution id is not the party
+holding the layers.
+
+Completion is first-writer-wins. A `DurableDeferred` records the first exit
+submitted against it, and every later read replays that exit. A second completion
+does not overwrite the first.
+
+## The caller's polling budget
+
+Ordinary `execute` follows a suspended run, polling and re-driving it instead
+of returning a suspended result. Its default `suspendedRetryPolicy` has no
+attempt or expiry bound, so the caller can keep waiting while the run is parked.
+A bounded `Flow.make` `suspendedRetryPolicy` limits **one caller**: if its
+schedule is spent, `execute` fails with a `SuspendedResumeGaveUp` defect, but
+the execution stays parked. The next caller starts a budget of its own. This
+budget is not durable and does not cancel the run.
+
+What bounds work durably is an action's own `RetryPolicy`. The engine restores
+`maxAttempts` from the persisted attempt sequence and the `expirationMs` origin
+from the first attempt's start time, so those survive park, resume, and process
+death. See [Retry a failing action](../guides/retry-a-failing-action.md).
+
+## Failures, defects, and parking on either
+
+Two annotations on the flow decide what a round does with something that went
+wrong:
+
+```ts
+import { Flow } from "@smthrs/flow"
+
+const Hardened = Review
+  .annotate(Flow.CaptureDefects, true)
+  .annotate(Flow.SuspendOnFailure, true)
+```
+
+- `Flow.CaptureDefects` defaults to `true`. It includes defects in the result of
+  the flow and its actions instead of letting them escape the execution.
+- `Flow.SuspendOnFailure` defaults to `false`. Set it when a round should park on
+  any error rather than fail, so an operator can fix the cause and resume.
+
+`Flow.intoResult` is what turns a handler effect into a `Result` under those two
+annotations, and it closes the round's flow scope on completion or handoff.
+
+## Scope and cleanup
+
+Each round has its own flow scope. Suspension keeps that 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; the next round
+has a fresh scope.
+
+A handoff completes the round successfully and discards its `withRollback` registrations.
+A later round's failure cannot invoke an earlier round's rollback. The engine
+does not provide lineage-scoped compensation. Compensation across rounds
+requires an explicit durable design, not an in-memory scope finalizer. Open
+scopes and their resources do not survive process death.
+
+- `Flow.scope` is the scope itself.
+- `Flow.provideScope(effect)` runs an effect against it.
+- `Flow.addFinalizer(f)` registers an exit finalizer, preserving the services
+  available where it was registered.
+- `Flow.withRollback(effect, rollback)` registers how to undo a successful effect
+  if the current round later exits unsuccessfully. See
+  [Cancel a run and undo its effects](../guides/cancel-and-roll-back.md).
+
+## Related pages
+
+- [Wait for a deadline](../guides/wait-for-a-deadline.md) and
+  [wait for an external signal](../guides/wait-for-an-external-signal.md): the
+  two ways a body parks on purpose.
+- [Trampoline rounds](./trampoline-rounds.md): the third result, and the loops it
+  makes possible.