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

package/docs/reference/flow.md

@@ -0,0 +1,1835 @@
+---
+title: "@smthrs/flow"
+description: "What @smthrs/flow exports: the flow, action, runtime-port, and durable-primitive namespaces, with types and defaults from source."
+area: api
+order: 10
+---
+
+Install the package with its `effect` peer:
+
+```bash
+npm install @smthrs/flow@next effect
+```
+
+## Entry points
+
+The `exports` map declares these subpaths:
+
+| Import                          | Source                           | Platform |
+| ------------------------------- | -------------------------------- | -------- |
+| `@smthrs/flow`                  | `src/index.ts`                   | any      |
+| `@smthrs/flow/Action`           | `src/Action/index.ts`            | any      |
+| `@smthrs/flow/CacheEnvironment` | `src/Action/CacheEnvironment.ts` | any      |
+| `@smthrs/flow/FileBoundary`     | `src/Action/FileBoundary.ts`     | any      |
+| `@smthrs/flow/FileInput`        | `src/Action/FileInput.ts`        | any      |
+| `@smthrs/flow/Flow`             | `src/Flow/index.ts`              | any      |
+| `@smthrs/flow/FlowRuntime`      | `src/FlowRuntime/index.ts`       | any      |
+| `@smthrs/flow/StepIdentity`     | `src/Action/StepIdentity.ts`     | any      |
+| `@smthrs/flow/<Module>`         | `src/<Module>.ts`                | any      |
+
+`<Module>` is one of the top-level modules, each listed explicitly in the `exports` map: `Deadline`, `DurableClock`, `DurableDeferred`, `DurableQueue`, `Fault`, `Graph`, `HumanTask`, `Interpreter`, `Poll`, `RetryPolicy`, `Sleep`, `Stall`, and `WaitFor`. No `./*` wildcard is declared. The `exports` map maps `./internal/*`, `./*/index`, `./Action/*`, `./Flow/*`, and `./FlowRuntime/*` to `null`, so those paths do not resolve.
+
+## Namespaces
+
+The package index re-exports seventeen namespaces:
+
+| Namespace         | Summary                                                              |
+| ----------------- | -------------------------------------------------------------------- |
+| `Action`          | Durable action definitions and combinators.                          |
+| `Deadline`        | The wall-clock bound one run settles by, shared across its rounds.   |
+| `DurableClock`    | Durable clock and timer services.                                    |
+| `DurableDeferred` | Durable deferred values.                                             |
+| `DurableQueue`    | Durable queues.                                                      |
+| `Fault`           | One typed fault class per failure, and the response ladder.          |
+| `Flow`            | Durable flow definitions.                                            |
+| `FlowRuntime`     | The execution contract flow authoring APIs are written against.      |
+| `Graph`           | Plan-time graph building from flow declarations.                     |
+| `HumanTask`       | Asking a person something: typed answers, re-asking, and a deadline. |
+| `Interpreter`     | Execution of a flow body, and the layer that registers it.           |
+| `Poll`            | The durable poller: attempts as rounds, waits as durable timers.     |
+| `RetryPolicy`     | Retry policy models and constructors.                                |
+| `Sleep`           | The system timer action and its implementation layer.                |
+| `Stall`           | The stall breaker round loops share.                                 |
+| `StepIdentity`    | Stable step identity construction.                                   |
+| `WaitFor`         | The system wait-point action and its implementation layer.           |
+
+## Action
+
+`Action` exports 45 symbols. Its models and schemas are listed in one table, and constructors, combinators, layers, context references, services, and errors get their own entries:
+
+| Name                 | Kind            | Summary                                                                                                                                                                                                                                                                                             |
+| -------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Tier`               | Schema and type | The durability and retry semantics of an action: `"sealed"`, `"compensable"`, or `"irreversible"`. It IS `@smthrs/plan`'s `Effects.Tier`.                                                                                                                                                           |
+| `IdempotencyKey`     | Schema and type | Caller-declared sealed action identity: a string, or a record of JSON values.                                                                                                                                                                                                                       |
+| `PlannedPayload`     | Type            | Recursively permits planned references wherever a declared action payload accepts a concrete value.                                                                                                                                                                                                 |
+| `Requirement`        | Interface       | The requirement one declared action mints for itself, identified by its tag.                                                                                                                                                                                                                        |
+| `Declared`           | Interface       | A named action declaration whose implementation attaches later through a layer. It carries `name`, `payloadSchema`, `successSchema`, `errorSchema`, `tier`, `idempotencyKey`, `nondeterministic`, `annotations`, and `requirement`, and exposes `call`, `toLayer`, `annotate`, and `annotateMerge`. |
+| `Action`             | Interface       | An inline durable action that is itself an `Effect`. It carries `name`, `successSchema`, `errorSchema`, `exitSchema`, `exitSchemaPartial`, `annotations`, `tier`, `idempotencyKey`, `nondeterministic`, `metadata`, and `retryPolicy`.                                                              |
+| `Any`                | Interface       | Type-erased action shape carrying only identity, name, annotations, and encoded execution.                                                                                                                                                                                                          |
+| `AnyWithProps`       | Interface       | Type-erased action shape that also exposes success and error schemas.                                                                                                                                                                                                                               |
+| `BoundaryMode`       | Schema and type | How strictly an action's filesystem boundary is enforced: `"hard"` or `"expected"`. It IS `@smthrs/plan`'s `FileSet.BoundaryMode`.                                                                                                                                                                  |
+| `CacheEnvironment`   | Schema and type | The complete runtime environment included in every cross-run cache key: `layers` and `capabilities`.                                                                                                                                                                                                |
+| `CacheScope`         | Schema and type | How far a recorded sealed result may travel: `"run"`, `"flow"`, or `"shared"`.                                                                                                                                                                                                                      |
+| `CachePolicy`        | Schema and type | The caller's declaration about the decay and the reach of a sealed action's recorded result.                                                                                                                                                                                                        |
+| `FileBoundary`       | Schema and type | The filesystem boundary of an action: `readSet`, `writeSet`, optional `removes`, and `boundaryMode`.                                                                                                                                                                                                |
+| `FileInput`          | Schema and type | An input file path paired with its measured content digest.                                                                                                                                                                                                                                         |
+| `Implementation`     | Interface       | One declared action's implementation as a driver consumes it: a name, and the durable action a payload produces.                                                                                                                                                                                    |
+| `AllocationIdentity` | Interface       | The declaration material an allocation scope is derived from: `kind`, `name`, optional `idempotency`, and optional `site`.                                                                                                                                                                          |
+
+### `Action.CachePolicyAnnotation`
+
+- **Type:** `Context.Service<CachePolicy>`
+- **Since:** `0.1.0`
+- **Related:** [`Action.withCache`](#actionwithcache)
+
+The annotation key a declaration carries its `CachePolicy` under. The policy is an annotation rather than a field on the action, so adding it changes no existing call site. Its identifier is `"@smthrs/flow/Action/CachePolicy"`.
+
+### `Action.cachePolicyOf`
+
+- **Signature:** `cachePolicyOf(annotations: Context.Context<never>): CachePolicy | undefined`
+- **Since:** `0.1.0`
+
+Reads the cache policy an annotation bag carries. Returns `undefined` when the bag carries none.
+
+### `Action.withCache`
+
+- **Signature:** `withCache<A extends { annotate: (key: typeof CachePolicyAnnotation, value: CachePolicy) => A }>(action: A, policy: CachePolicy): A`
+- **Since:** `0.1.0`
+
+Returns a copy of the action annotated with a cache policy. The action is not mutated: `annotate` returns a separate declaration, and that copy is what a plan captures. `ttlMs` bounds the age of a row the engine may serve, and `scope` narrows the address the row is stored under.
+
+### `Action.CurrentCacheEnvironment`
+
+- **Type:** `Context.Reference<CacheEnvironment | undefined>`
+- **Default:** `undefined`
+- **Since:** `0.1.0`
+
+The complete environment folded into reusable action keys. A composition either provides a complete `CacheEnvironment` or leaves it absent. When it is absent the engine scopes action keys to the current run instead of presenting incomplete environment data as reusable identity.
+
+### `Action.layerCacheEnvironment`
+
+- **Signature:** `layerCacheEnvironment(environment: CacheEnvironment): Layer.Layer<never>`
+- **Since:** `0.1.0`
+
+Declares the complete cache environment of a composition as a layer.
+
+### `Action.OrdinalSlot`
+
+- **Type:** `interface OrdinalSlot { readonly values: Map<string, Array<number>>; readonly cursors: Map<string, number> }`
+- **Since:** `0.1.0`
+
+The ordinal slots a retry sequence shares across its attempts, keyed by allocation scope. A nested block shares the pinned `values` with the enclosing block and owns a private `cursors` view seeded at block entry.
+
+### `Action.CurrentOrdinal`
+
+- **Type:** `Context.Reference<OrdinalSlot | undefined>`
+- **Default:** `undefined`
+- **Since:** `0.1.0`
+
+The ordinal slot of the enclosing `Action.retry` sequence, when one is present.
+
+### `Action.CurrentAttempt`
+
+- **Type:** `Context.Reference<number>`
+- **Default:** `1`
+- **Since:** `0.1.0`
+
+The current durable retry attempt, counted from one.
+
+### `Action.CurrentInvocationKey`
+
+- **Type:** `Context.Reference<string | undefined>`
+- **Default:** `undefined`
+- **Since:** `0.1.0`
+
+The persisted key of the dispatch an implementation is running under, when the runtime supplies one.
+
+### `Action.DuplicateImplementation`
+
+- **Type:** `Schema.TaggedError` with field `name: string`
+- **Since:** `0.1.0`
+
+The defect layer construction dies with when a second, different implementation registers for an action tag without `{ override: true }`.
+
+### `Action.InfraInterrupt`
+
+- **Type:** `Schema.TaggedError` with fields `code: "infra_interrupt"` and `reason?: unknown`
+- **Since:** `0.1.0`
+
+The marker an action implementation or adapter explicitly fails with for an infrastructure event it wants retried under the action's `interruptRetryPolicy`. The shipped engines do not synthesize it from ordinary fiber interruption.
+
+### `Action.InfraInterruptRetriesExhausted`
+
+- **Type:** `Schema.TaggedError` with fields `code: "infra_interrupt_retries_exhausted"`, `actionName: string`, `attempts: number`, `interrupt: InfraInterrupt`, and `message: string`
+- **Since:** `0.1.0`
+
+The identity an action dies with after spending its `interruptRetryPolicy` without reaching an ordinary success or failure.
+
+### `Action.IrreversibleRetryRequiresIdempotencyKey`
+
+- **Type:** `Schema.TaggedError` with fields `code: "irreversible_retry_requires_idempotency_key"`, `actionName: string`, and `attempt: number`
+- **Since:** `0.1.0`
+
+An irreversible action attempted a retry without declaring an idempotency key.
+
+### `Action.ConcurrentKeylessDispatch`
+
+- **Type:** `Schema.TaggedError` with fields `code: "concurrent_keyless_dispatch"` and `actionName: string`
+- **Since:** `0.1.0`
+
+Two ordinal-keyed invocations of one allocation scope were in flight at once, so fiber arrival order would assign their ordinals, step keys, attempt rows, and recorded outcomes. Declare an `idempotencyKey` that distinguishes the invocations to dispatch them concurrently. A sealed action with a key takes a pure cache key and is exempt.
+
+### `Action.UncanonicalIdempotencyKey`
+
+- **Type:** `Schema.TaggedError` with fields `code: "uncanonical_idempotency_key"`, `actionName: string`, `reason: string`, `path: string`, and `message: string`
+- **Since:** `0.1.0`
+
+A caller-declared object-form `idempotencyKey` carried material that canonical serialization rejects. The failure is not retryable: the same declaration derives the same rejection on every attempt, so the body never runs.
+
+### `Action.Filegroup`
+
+- **Type:** namespace re-exporting `Filegroup` (a `Schema.TaggedStruct` of `name` and `entries`), the type alias `Type`, and `make`
+- **Since:** `0.1.0`
+
+Named reusable filesystem declaration groups. `Action.Filegroup.make` creates one.
+
+### `Action.Glob`
+
+- **Type:** namespace re-exporting `Glob`, `Pattern`, `matchesGlob`, `matchesPattern`, and the type alias `Type`
+- **Since:** `0.1.0`
+
+The Bazel-style file glob vocabulary. `Glob` is a `Schema.TaggedStruct` of `include` and optional `exclude` patterns.
+
+### `Action.idempotencyKey`
+
+- **Signature:** `idempotencyKey(name: string, options?: { readonly includeAttempt?: boolean | undefined; readonly parentScope?: string | undefined }): Effect.Effect<string, never, FlowInstance | Crypto.Crypto>`
+- **Since:** `0.1.0`
+
+Computes the run-local invocation key of an internal durable operation. The key is scoped by the caller's declaration name and declared `parentScope`.
+
+### `Action.Implementations`
+
+- **Type:** `Context.Service` keyed `"@smthrs/flow/Action/Implementations"`
+- **Since:** `0.1.0`
+- **Related:** [`Action.layerImplementations`](#actionlayerimplementations)
+
+The table holding the declared action implementations a composition wired up, keyed by action tag. A second, different implementation of one tag dies with `Action.DuplicateImplementation` unless it registers with `toLayer(handler, { override: true })`. An override shadows the earlier registration, and closing the overriding scope restores it. Registering the same implementation object again is not a conflict.
+
+### `Action.layerImplementations`
+
+- **Type:** `Layer.Layer<Implementations>`
+- **Since:** `0.1.0`
+
+The implementation table, scoped to the composition that builds it. Filing an implementation is a build-time effect, so provide this layer under the implementation layers with `Layer.provideMerge` rather than merging it beside them.
+
+### `Action.make`
+
+- **Signature:** `make(tag: Tag, options: { payload, declaredFrom?, implementationVersion?, success?, error?, tier?, idempotencyKey?, nondeterministic?, retryPolicy?, interruptRetryPolicy?, fileBoundary?, annotations? }): Declared<Tag, Payload, Success, Error>`
+- **Signature:** `make(options: { name, success?, error?, execute, tier?, idempotencyKey?, nondeterministic?, metadata?, interruptRetryPolicy?, retryPolicy?, annotations? }): Action<Success, Error, R>`
+- **Since:** `0.1.0`
+- **Related:** [`Action.makeSystem`](#actionmakesystem)
+
+Creates either a named action declaration or an inline executable action, selected by whether the first argument is a string. The declared form is pure data whose implementation attaches later through `Declared.toLayer`. The inline form carries its `execute` effect directly.
+
+The declared form accepts `declaredFrom: original` to retain a native declaration's
+diagnostic source location, including its absence. The new action owns its call
+closures; this option changes neither dispatch identity nor key material.
+
+| Option                  | Forms    | Meaning                                                                         |
+| ----------------------- | -------- | ------------------------------------------------------------------------------- |
+| `payload`               | declared | Payload fields or struct schema, validated on every dispatch.                   |
+| `name`, `execute`       | inline   | The step name and the effect it runs.                                           |
+| `implementationVersion` | declared | Non-empty version string; `toLayer` must pass the same value.                   |
+| `success`, `error`      | both     | Result schemas. Default `Schema.Void` and `Schema.Never`.                       |
+| `tier`                  | both     | Durability tier. Default `"sealed"`.                                            |
+| `idempotencyKey`        | both     | Caller identity. The declared form may compute it from the decoded payload.     |
+| `nondeterministic`      | both     | Marks a result that replay must read from the record rather than recompute.     |
+| `retryPolicy`           | both     | The `RetryPolicy` the engine reads at dispatch.                                 |
+| `interruptRetryPolicy`  | both     | The `Schedule` spent on `Action.InfraInterrupt` failures.                       |
+| `fileBoundary`          | both     | Typed file boundary. The declared form may compute it from the decoded payload. |
+| `metadata`              | inline   | Free-form metadata; a historical boundary declaration is still read from it.    |
+| `annotations`           | both     | Context annotations carried by the action.                                      |
+
+`Declared.toLayer(handler, { implementationVersion?, override? })` registers the implementation. Without `override: true`, a second, different implementation of the tag dies with `Action.DuplicateImplementation`.
+
+### `Action.makeSystem`
+
+- **Signature:** `makeSystem(tag: Tag, options: { payload, declaredFrom?, implementationVersion?, success?, error?, tier?, idempotencyKey?, nondeterministic?, retryPolicy?, interruptRetryPolicy?, fileBoundary?, annotations? }): Declared<Tag, Payload, Success, Error, never>`
+- **Since:** `0.1.0`
+
+Declares a system action, one whose implementation ships with the engine rather than with the composition that calls it. It matches `Action.make`'s declared form in every respect except the requirement: a system declaration mints none, so a body using `Sleep` or `WaitFor` pushes no layer obligation onto its callers.
+
+### `Action.raceAll`
+
+- **Signature:** `raceAll(name: string, actions: Actions): Effect.Effect<...>`
+- **Since:** `0.1.0`
+
+Runs a non-empty collection of actions as a durable race and returns the first success, under the unioned success and error schemas. A losing failure is ignored while another action runs; the race fails only when every action fails. To settle on the first exit, success or failure, race `Effect.exit` of each action and unwrap the winner. One winner is persisted under `name`, so a re-driven round replays it instead of racing again. The race requires every action's services, including `Crypto`, plus the decoding and encoding services of each action's success and error schemas.
+
+### `Action.retry`
+
+- **Signature:** `retry(self: Effect.Effect<A, E, R>, options: O): Effect.Retry.Return<R, E, A, O>`
+- **Since:** `0.1.0`
+
+Retries an effect with `Effect.retry` while updating `CurrentAttempt` on each attempt. The `schedule` option of `Effect.Retry.Options` is omitted. Every attempt of one sequence reuses its own action's ordinals, and a nested block shares the enclosing block's pinned slot.
+
+### `Action.DispatchSite`
+
+- **Type:** `Context.Service<DispatchSite, string>` keyed `"@smthrs/flow/Action/DispatchSite"`
+- **Since:** `0.1.0`
+
+The interpreter graph site the running dispatch is scoped to. Distinct graph sites refine the allocation scope, so they do not contend for one ordinal counter.
+
+### `Action.DispatchOutcome`
+
+- **Type:** `interface DispatchOutcome { readonly outcome: "executed" | "replayed"; readonly stepKeyDigest?: string | undefined; readonly attempt?: number | undefined }`
+- **Since:** `1.0.0`
+
+What one dispatch tells the node that drove it. `outcome` says whether the body ran or a durable record answered. `stepKeyDigest` is the identity the rest of the engine addresses that dispatch by, the digest `flows.engine.attempt-started` carries, and `attempt` is the durable attempt it ran as. Both are optional, because a runtime that keeps no attempt rows has neither.
+
+### `Action.DispatchReport`
+
+- **Type:** `Context.Service<DispatchReport, { readonly dispatched: (dispatch: DispatchOutcome) => Effect.Effect<void> }>` keyed `"@smthrs/flow/Action/DispatchReport"`
+- **Since:** `1.0.0`
+
+Where the dispatches of one interpreter node report what happened to them. The interpreter installs one per node and reads the report back when the node settles: it is how a replayed node is told apart from one that did the work again, how a node names the step keys its attempt records were written under, and how a node's real attempt count reaches its settlement. Absent by default: a dispatch outside an interpreted graph reports to nobody, and reporting stays a side channel rather than a change to what `actionExecute` returns.
+
+### `Action.reportDispatch`
+
+- **Signature:** `reportDispatch(dispatch: DispatchOutcome): Effect.Effect<void>`
+- **Since:** `1.0.0`
+
+Reports one dispatch to the node that drove it, and does nothing where no node did.
+
+### `Action.allocationScope`
+
+- **Signature:** `allocationScope(identity: AllocationIdentity): Effect.Effect<string, Schema.SchemaError, Crypto.Crypto>`
+- **Since:** `0.1.0`
+
+Derives the ordinal allocation scope of a durable operation from its declaration material.
+
+### `Action.invocationKey`
+
+- **Signature:** `invocationKey(input: { readonly runId: string; readonly parentScope?: string | undefined; readonly ordinal: number; readonly tier: "unsealed" | "compensable" | "irreversible" }): Effect.Effect<StoredKey, Schema.SchemaError, Crypto.Crypto>`
+- **Since:** `0.1.0`
+
+Derives an invocation key from engine-generated input.
+
+### `Action.TreeArtifact`
+
+- **Type:** namespace re-exporting `TreeArtifact` (a `Schema.TaggedStruct` of `path`) and the type alias `Type`
+- **Since:** `0.1.0`
+
+A directory output captured and replayed as one tree artifact.
+
+## Deadline
+
+### `Deadline.start`
+
+- **Signature:** `start(options: { readonly flowName: string; readonly deadline?: Duration.Input | undefined; readonly startedAtMs?: number | undefined }): Effect.Effect<LineageDeadline | undefined, never, FlowRuntime | FlowInstance | Crypto.Crypto>`
+- **Since:** `1.0.0`
+
+Starts the current execution's deadline: the lineage deadline the round inherited from a handoff, or `deadline` counted from the execution's journaled first start (or from `startedAtMs`, when the host holds a durable start of its own), with a durable clock armed at it. Answers `undefined` when neither applies. Dies with a `RangeError` when `deadline` is not a positive finite duration, `startedAtMs` is not finite, or the deadline would expire after epoch millisecond `Number.MAX_SAFE_INTEGER`. Start at most one deadline per execution.
+
+### `Deadline.remainingMs`
+
+- **Signature:** `remainingMs(deadline: LineageDeadline): Effect.Effect<number>`
+- **Since:** `1.0.0`
+
+The whole milliseconds left before the deadline passes; zero or less once it has.
+
+### `Deadline.within`
+
+- **Signature:** `within(deadline: LineageDeadline | undefined, flowName: string): <A, E, R>(body: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | FlowInstance>`
+- **Since:** `1.0.0`
+
+Races `body` against a started deadline and settles it with `Flow.DeadlineExceeded` at the deadline, at once when it has already passed. A round that hands off stamps the deadline on its `Flow.Handoff`. `undefined` runs `body` unbounded.
+
+### `Deadline.bound`
+
+- **Signature:** `bound(options: { readonly flowName: string; readonly deadline?: Duration.Input | undefined; readonly startedAtMs?: number | undefined }): <A, E, R>(body: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | FlowRuntime | FlowInstance | Crypto.Crypto>`
+- **Since:** `1.0.0`
+
+`start`, then `within`. The engine applies it to every execution of a flow that declares `deadline`.
+
+## DurableClock
+
+### `DurableClock.DurableClock`
+
+- **Type:** `interface DurableClock { readonly name: string; readonly duration: Duration.Duration; readonly deferred: DurableDeferred.DurableDeferred<typeof Schema.Void> }`
+- **Since:** `0.1.0`
+
+A durable flow timer: a name, a duration, and the deferred that is completed when the timer wakes. The interface also carries a private type identifier.
+
+### `DurableClock.make`
+
+- **Signature:** `make(options: { readonly name: string; readonly duration: Duration.Input }): DurableClock`
+- **Since:** `0.1.0`
+
+Declares one durable clock. Throws a `RangeError` when the duration is malformed, infinite, negative, or longer than `Number.MAX_SAFE_INTEGER` milliseconds: a durable store records a clock's due time as a safe integer.
+
+### `DurableClock.sleep`
+
+- **Signature:** `sleep(options: { readonly name: string; readonly duration: Duration.Input; readonly inMemoryThreshold?: Duration.Input | undefined }): Effect.Effect<void, never, Crypto.Crypto | FlowRuntime | FlowInstance>`
+- **Default:** `inMemoryThreshold` is 60 seconds
+- **Since:** `0.1.0`
+
+Waits inside a flow. A duration at or below `inMemoryThreshold` runs as an in-memory action. A longer duration schedules a durable clock, so the wait outlives the process holding it. Throws a `RangeError` for a duration `make` refuses or a malformed, infinite, or negative threshold. A durable sleep that would wake after epoch millisecond `Number.MAX_SAFE_INTEGER` dies with a `RangeError` instead of arming its clock.
+
+## DurableDeferred
+
+### `DurableDeferred.DurableDeferred`
+
+- **Type:** `interface DurableDeferred<Success extends Schema.Constraint, Error extends Schema.Constraint = Schema.Never>` with `name`, `successSchema`, `errorSchema`, `exitSchema`, and `withActionAttempt`
+- **Since:** `0.1.0`
+
+A named durable deferred whose completion the flow engine persists, encoded through its success and error schemas.
+
+### `DurableDeferred.Any`
+
+- **Type:** `interface Any { readonly name: string }`
+- **Since:** `0.1.0`
+
+The type-erased deferred shape for APIs that need only the identity and the name. It also carries the private type identifier.
+
+### `DurableDeferred.AnyWithProps`
+
+- **Type:** `interface AnyWithProps` with `name`, `successSchema`, `errorSchema`, and `exitSchema`
+- **Since:** `0.1.0`
+
+The type-erased deferred shape that also exposes the schemas.
+
+### `DurableDeferred.make`
+
+- **Signature:** `make(name: string, options?: { readonly success?: Success | undefined; readonly error?: Error | undefined }): DurableDeferred<Success, Error>`
+- **Default:** `success` is `Schema.Void`, `error` is `Schema.Never`
+- **Since:** `0.1.0`
+
+Creates a named durable deferred for a persisted completion.
+
+### `DurableDeferred.await`
+
+- **Signature:** `await(self: DurableDeferred<Success, Error>): Effect.Effect<Success["Type"], Error["Type"], FlowRuntime | FlowInstance | Success["DecodingServices"] | Error["DecodingServices"]>`
+- **Since:** `0.1.0`
+
+Waits for the durable deferred, suspending the current flow when no persisted completion is available. The first recorded exit is the one every later read replays.
+
+### `DurableDeferred.into`
+
+- **Signature:** `into(effect: Effect.Effect<Success["Type"], Error["Type"], R>, self: DurableDeferred<Success, Error>): Effect.Effect<Success["Type"], Error["Type"], R | FlowRuntime | FlowInstance | Success["DecodingServices"] | Success["EncodingServices"] | Error["DecodingServices"] | Error["EncodingServices"]>`
+- **Since:** `0.1.0`
+
+Runs an effect and records its exit into the durable deferred, resuming the flows waiting on that deferred. The data-last form takes the deferred alone.
+
+An interrupt-only exit records nothing. Mixed causes record only their non-interrupt reasons. The effect uses the current flow instance: nested durable waits can suspend, and suspension causes, waiting annotations, and handoffs remain visible to the enclosing flow.
+
+### `DurableDeferred.raceAll`
+
+- **Signature:** `raceAll(options: { name: string; success: Success; error: Error; effects: Effects }): Effect.Effect<...>`
+- **Since:** `0.1.0`
+
+Runs effects as a durable race. A previously persisted result is returned unchanged. Otherwise the first success completes the deferred named `raceAll/<name>`, and the race fails only when every effect fails, so a re-driven round reads the recorded winner instead of racing again.
+
+### `DurableDeferred.TokenTypeId`
+
+- **Type:** `"@smthrs/flow/DurableDeferred/Token"`, exported as both a constant and a type
+- **Since:** `0.1.0`
+
+The brand identifier that distinguishes a completion token from an ordinary string.
+
+### `DurableDeferred.Token`
+
+- **Type:** `Brand.Branded<string, TokenTypeId>` as a type, and `Schema.brand<Schema.String, TokenTypeId>` as a schema
+- **Since:** `0.1.0`
+
+A branded string identifying one durable deferred of one flow execution.
+
+A token is an address, not a credential. It is unsigned base64url JSON of the flow name, execution id, and deferred name, and `tokenFromExecutionId` and `tokenFromPayload` rebuild it from those values. Anyone who can call a completion entry point (`done`, `succeed`, `fail`, `failCause`, `HumanTask.answer`) against the run's `FlowRuntime` can complete an open wait whose address they know or derive. A host that exposes completion to other parties must authorize the caller first.
+
+### `DurableDeferred.TokenInvalid`
+
+- **Type:** `Schema.TaggedError` with fields `code: "malformed_token" | "deferred_mismatch"` and `message: string`
+- **Default:** `code` defaults to `"malformed_token"`
+- **Since:** `0.1.0`
+
+The typed failure every completion surface returns for a token that does not parse, or that names a different deferred than the one it was submitted through.
+
+### `DurableDeferred.TokenParsed`
+
+- **Type:** `Schema.Class` with fields `flowName: string`, `executionId: string`, and `deferredName: string`
+- **Since:** `0.1.0`
+
+A decoded token. The three fields are the durable address a completion is written to.
+
+### `DurableDeferred.token`
+
+- **Signature:** `token(self: DurableDeferred<Success, Error>): Effect.Effect<Token, never, FlowInstance>`
+- **Since:** `0.1.0`
+
+Creates a token for a deferred using the running flow's own name and execution id.
+
+### `DurableDeferred.tokenFromExecutionId`
+
+- **Signature:** `tokenFromExecutionId(self: DurableDeferred<Success, Error>, options: { readonly flow: Flow.Any; readonly executionId: string }): Token`
+- **Since:** `0.1.0`
+
+Creates a token from an explicit flow and execution id, for a resolver outside the run.
+
+### `DurableDeferred.tokenFromPayload`
+
+- **Signature:** `tokenFromPayload(self: DurableDeferred<Success, Error>, options: { readonly flow: W; readonly payload: Flow.PayloadSchema<W>["~type.make.in"] }): Effect.Effect<Token, never, Crypto.Crypto | Flow.PayloadSchema<W>["EncodingServices"]>`
+- **Since:** `0.1.0`
+
+Creates a token by deriving the execution id from the flow payload. Declare an `idempotencyKey` or install the opt-in derived source for stable payload identity. The default fresh source mints a new id on each call; use `tokenFromExecutionId` with a saved id to address an existing execution.
+
+### `DurableDeferred.done`
+
+- **Signature:** `done(self: DurableDeferred<Success, Error>, options: { readonly token: Token; readonly exit: Exit.Exit<Success["Type"], Error["Type"]> }): Effect.Effect<void, TokenInvalid, FlowRuntime | Success["EncodingServices"] | Error["EncodingServices"]>`
+- **Since:** `0.1.0`
+
+Completes the deferred a token addresses with an exit, encoded through the deferred's schemas. A token whose `deferredName` is not this deferred's name fails with `TokenInvalid`. The token is not a credential: authorize the caller before completing a wait on its behalf.
+
+### `DurableDeferred.succeed`
+
+- **Signature:** `succeed(self: DurableDeferred<Success, Error>, options: { readonly token: Token; readonly value: Success["Type"] }): Effect.Effect<void, TokenInvalid, FlowRuntime | Success["EncodingServices"]>`
+- **Since:** `0.1.0`
+
+Completes the deferred with a successful value.
+
+### `DurableDeferred.fail`
+
+- **Signature:** `fail(self: DurableDeferred<Success, Error>, options: { readonly token: Token; readonly error: Error["Type"] }): Effect.Effect<void, TokenInvalid, FlowRuntime | Error["EncodingServices"]>`
+- **Since:** `0.1.0`
+
+Completes the deferred with a typed failure.
+
+### `DurableDeferred.failCause`
+
+- **Signature:** `failCause(self: DurableDeferred<Success, Error>, options: { readonly token: Token; readonly cause: Cause.Cause<Error["Type"]> }): Effect.Effect<void, TokenInvalid, FlowRuntime | Error["EncodingServices"]>`
+- **Since:** `0.1.0`
+
+Completes the deferred with a failure cause.
+
+## DurableQueue
+
+### `DurableQueue.TypeId`
+
+- **Type:** `"@smthrs/flow/DurableQueue"`, exported as both a constant and a type
+- **Since:** `0.1.0`
+
+The identifier attached to `DurableQueue` values.
+
+### `DurableQueue.DurableQueue`
+
+- **Type:** `interface DurableQueue<Payload extends Schema.Top, Success extends Schema.Top = Schema.Void, Error extends Schema.Top = Schema.Never>` with `name`, `payloadSchema`, `idempotencyKey`, and `deferred`
+- **Since:** `0.1.0`
+
+A durable queue definition: the payload schema, the key that identifies one item, and the deferred a caller awaits the worker's result on.
+
+### `DurableQueue.make`
+
+- **Signature:** `make(options: { readonly name: string; readonly payload: Payload; readonly idempotencyKey: (payload) => string; readonly success?: Success | undefined; readonly error?: Error | undefined }): DurableQueue<...>`
+- **Default:** `success` is `Schema.Void`, `error` is `Schema.Never`
+- **Since:** `0.1.0`
+
+Creates a durable queue that waits for persisted items to finish processing through a `DurableDeferred`.
+
+### `DurableQueue.process`
+
+- **Signature:** `process(self: DurableQueue<Payload, Success, Error>, payload: Payload["~type.make.in"], options?: { readonly retrySchedule?: Schedule.Schedule<any, PersistedQueue.PersistedQueueError> | undefined }): Effect.Effect<Success["Type"], Error["Type"], FlowRuntime | FlowInstance | Crypto.Crypto | PersistedQueue.PersistedQueueFactory | Payload["EncodingServices"] | Payload["DecodingServices"] | Success["DecodingServices"] | Error["DecodingServices"]>`
+- **Default:** `retrySchedule` is unbounded, with exponential delays capped at one minute
+- **Since:** `0.1.0`
+
+Offers a payload to the queue under the name `DurableQueue/<name>`, attaches a token, and suspends until a worker records the handler's exit against it. A caller-supplied schedule may exhaust, and its final offer failure becomes a defect so the error channel stays the worker's declared error. A payload that fails the queue's schema is also a defect.
+
+### `DurableQueue.makeWorker`
+
+- **Signature:** `makeWorker(self: DurableQueue<Payload, Success, Error>, f: (payload: Payload["Type"]) => Effect.Effect<Success["Type"], Error["Type"], R>, options?: { readonly concurrency?: number | undefined }): Effect.Effect<never, never, ...>`
+- **Default:** `concurrency` is `1`
+- **Since:** `0.1.0`
+
+Creates the worker effect that processes items from the queue. It throws a `RangeError` when `concurrency` is not a positive safe integer.
+
+### `DurableQueue.worker`
+
+- **Signature:** `worker(self: DurableQueue<Payload, Success, Error>, f: (payload: Payload["Type"]) => Effect.Effect<Success["Type"], Error["Type"], R>, options?: { readonly concurrency?: number | undefined }): Layer.Layer<never, never, ...>`
+- **Default:** `concurrency` is `1`
+- **Since:** `0.1.0`
+
+The layer form of `DurableQueue.makeWorker`, forking the worker into the layer's scope.
+
+## Fault
+
+One typed fault for every failure. The owner of an error union registers each code with a class, so a failure crosses every seam as `{ class, tag }` instead of prose.
+
+### `Fault.Class`
+
+- **Type:** `Schema.Literals<["user", "wait", "infra", "dependency", "bug", "factory", "policy"]>`
+- **Since:** `1.0.0`
+
+`user`, `wait`, `infra`, `dependency`, and `bug` are the wire registry. `factory` means the factory's own work did not converge, so a replan may fix it. `policy` means a cap stopped the work.
+
+### `Fault.Fault`
+
+- **Type:** `Schema.Struct<{ class: Class; tag: Schema.String }>`
+- **Since:** `1.0.0`
+
+`tag` is `<_tag>/<code>`, or `<_tag>` for an error without a code.
+
+### `Fault.register`
+
+- **Signature:** `register<Code extends string>(tag: string, table: Class | Rows<Code>, field?: string): void`
+- **Since:** `1.0.0`
+
+Registers one class for the whole tag, or one per value of `field` (default `code`). Owners write `satisfies Fault.Rows<Code>`, so a new code without a class does not compile. A value the table does not name is `bug`. The registry is one per process, shared by the ESM and CommonJS builds. Registering a tag again with the same rows is a no-op; registering it with different rows throws.
+
+### `Fault.of`
+
+- **Signature:** `of(error: unknown): Fault`
+- **Since:** `1.0.0`
+
+Reads the error and up to 15 `cause` links beneath it and answers the innermost registered tag, because a wrapper names where a failure surfaced and its cause names why. Anything unregistered is `{ class: "bug", tag: "unregistered" }`.
+
+### `Fault.retryTransient`
+
+- **Signature:** `retryTransient<A, E, R>(effect: Effect<A, E, R>): Effect<A, E, R>`
+
+Retries plain effects only while `Fault.of(error).class` is `infra`, using
+`RetryPolicy.transient`: 5 seconds doubling to 5 minutes, expiring after 2 hours.
+The caller guarantees the effect is safe to repeat. The final typed failure is
+preserved, including its class. Defects and interruption are not retried.
+
+### `Fault.respond`
+
+- **Signature:** `respond(fault: Fault, state: State): Response`
+- **Since:** `1.0.0`
+
+The one response ladder, exhaustive over the classes. `wait` backs up, then parks while `parksLeft` allows, then stops. `dependency` backs up, then retries until the third attempt, then stops. `infra` retries until the third attempt, then parks. `factory` replans twice, continues once as `very_hard`, then asks for `help`. A declined request (`coding/Error/declined`) closes, any other `user` fault asks for `help`, and `policy` and `bug` stop.
+
+### `Fault.registered`
+
+- **Signature:** `registered(): ReadonlySet<string>`
+- **Since:** `1.0.0`
+
+Every registered tag. The sweep tests read it.
+
+## Flow
+
+`Flow` models and schemas are listed in one table, and constructors, refinements, results, resource management, annotations, and errors get their own entries:
+
+| Name                  | Kind                 | Summary                                                                                                                                                                                                                                                                                                                                                      |
+| --------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Effects`             | Schema and type      | The declared filesystem effects of a flow: `reads`, `writes`, optional `removes` (workspace-relative patterns, as on an action boundary), and `boundaryMode`. It IS `@smthrs/plan`'s `Plan.NodeEffects`, not a copy of it.                                                                                                                                   |
+| `PlacementDirective`  | Type                 | Where a node runs. It IS `@smthrs/plan`'s `Placement.Placement`, the one typed model, carried unchanged until planning reads it.                                                                                                                                                                                                                             |
+| `ExecutionIdSource`   | Interface            | Mints the execution id of an invocation that named none, through `mint(flow, payload)`.                                                                                                                                                                                                                                                                      |
+| `BodySuccess`         | Type                 | The values a flow body may settle one round with: a decoded success, a planned reference, or an `Outcome`.                                                                                                                                                                                                                                                   |
+| `Flow`                | Interface            | A durable flow definition. It carries `_tag`, `payloadSchema`, `successSchema`, `errorSchema`, `annotations`, `body`, `idempotencyKey`, `suspendedRetryPolicy`, `maxRounds`, and `deadline`, and exposes `call`, `child`, `to`, `annotate`, `annotateMerge`, `execute`, `start`, `ensure`, `poll`, `interrupt`, `resume`, `executionId`, and `withRollback`. |
+| `AnyStructSchema`     | Interface            | The constraint a flow payload schema satisfies: a `Schema.Top` that exposes `fields`.                                                                                                                                                                                                                                                                        |
+| `Execution`           | Interface            | A type-level marker tying a service to one flow tag. It carries no runtime value.                                                                                                                                                                                                                                                                            |
+| `Any`                 | Interface            | The type-erased flow shape for APIs that do not preserve payload, success, or error types.                                                                                                                                                                                                                                                                   |
+| `AnyWithProps`        | Interface            | The type-erased flow shape that also exposes `execute` and `resume`.                                                                                                                                                                                                                                                                                         |
+| `PayloadSchema`       | Type                 | Extracts the payload schema from a `Flow`.                                                                                                                                                                                                                                                                                                                   |
+| `Requirements`        | Type                 | Extracts a flow's requirement channel: the action implementations its body names and does not carry.                                                                                                                                                                                                                                                         |
+| `RequirementsClient`  | Type                 | The schema services a client that executes or polls flows requires.                                                                                                                                                                                                                                                                                          |
+| `RequirementsHandler` | Type                 | The schema services a handler that decodes payloads and encodes results requires.                                                                                                                                                                                                                                                                            |
+| `Done`                | Interface and schema | A completed trampoline lineage value, carrying `value`.                                                                                                                                                                                                                                                                                                      |
+| `To`                  | Interface and schema | A serializable invocation of the next flow round, carrying `flow` and `payload`.                                                                                                                                                                                                                                                                             |
+| `Park`                | Interface and schema | A request to durably park the current round, carrying `reason`.                                                                                                                                                                                                                                                                                              |
+| `Outcome`             | Type and schema      | The union of `Done`, `To`, and `Park`.                                                                                                                                                                                                                                                                                                                       |
+| `CompleteSchema`      | Interface            | The schema constructor for `Complete` results under supplied success and error schemas.                                                                                                                                                                                                                                                                      |
+
+### `Flow.PromptFlow`
+
+A canonical flow with a typed `prompt(payload): string` renderer and an ordinary
+`action` named `<tag>/prompt`. Its requirement channel carries that action's
+implementation requirement. Annotation copies retain the prompt and action.
+
+`Flow.ModelSelection` is a seat string or an ordered nonempty tuple.
+`Flow.DeclarationMetadata` carries optional `model`, `effort`, `system`, `chat`,
+and `flows` fields, interpreted by the host.
+
+### `Flow.Capabilities`
+
+- **Type:** `Context.Reference<ReadonlyArray<string>>`
+- **Default:** `[]`
+- **Since:** `0.1.0`
+
+The capability names a flow may require. Its identifier is `"@smthrs/flow/Flow/Capabilities"`.
+
+### `Flow.EffectsDeclaration`
+
+- **Type:** `Context.Service<Effects>`
+- **Since:** `0.1.0`
+
+The annotation key for a flow's declared filesystem effects. Its identifier is `"@smthrs/flow/Flow/EffectsDeclaration"`.
+
+### `Flow.EffectEnvelope`
+
+- **Type:** `Context.Key<Effects.Declaration, Effects.Declaration>`
+- **Since:** `0.1.0`
+
+The annotation key for the effect AUTHORITY a flow declares: the ceiling every step spliced beneath it must stay inside. It IS `@smthrs/plan`'s `Effects.Envelope`, identified by `"@smthrs/plan/Effects/Envelope"`, which `@smthrs/core` also publishes as `Annotations.Effects`, so a flow annotated for either graph builder is visible to the other. Its value is the one envelope model from `@smthrs/plan/Effects`, and `Flow.make`'s `effects` literal writes it.
+
+It answers a different question from `Flow.EffectsDeclaration`. That one says which FILES a node touches, so a plan can order writers and a sandbox can enforce a boundary at run time. This one says how much a flow is ALLOWED to touch, so `Graph.build` can refuse a composition that claims more than its caller granted, with `effect_outside_envelope`, `effect_mode_widening`, `effect_tier_widening`, or the advisory `capability_outside_grant`.
+
+### `Flow.Placement`
+
+- **Type:** `Context.Key<PlacementDirective, PlacementDirective>`
+- **Since:** `0.1.0`
+
+The annotation key for a flow's placement directive. It IS `@smthrs/plan`'s `Placement.Annotation`, identified by `"@smthrs/plan/Placement"`, which `@smthrs/core` also publishes as `Annotations.Placement`. Crossing between the two used to be a cast in `@smthrs/registry`.
+
+### `Flow.CaptureDefects`
+
+- **Type:** `Context.Reference<boolean>`
+- **Default:** `true`
+- **Since:** `0.1.0`
+
+Whether defects are captured for a flow and included in the result of the flow or its actions.
+
+### `Flow.SuspendOnFailure`
+
+- **Type:** `Context.Reference<boolean>`
+- **Default:** `false`
+- **Since:** `0.1.0`
+
+Whether a flow suspends when it encounters any error. A suspended execution is re-driven with the flow's `resume` method.
+
+### `Flow.ExecutionIdRequired`
+
+- **Type:** `Schema.TaggedError` with fields `code: "execution_id_required"` and `flowName: string`
+- **Since:** `0.1.0`
+
+The opt-in `derived` source dies with this defect when the payload has no canonical form. The default source mints a fresh UUID when the caller and declaration do not select an id. `FlowProxyServer` also dies with it when a configured `ExecutionIdScope` returns `undefined` for a resume request.
+
+### `Flow.derived`
+
+- **Type:** `ExecutionIdSource`
+- **Since:** `0.1.0`
+
+The opt-in deterministic execution-id source. It encodes the payload with the flow's own codec, canonicalizes it under RFC 8785, hashes it with SHA-256, and hashes that key together with the flow tag inside a JSON tuple. The same tag and encoded payload derive the same id. The preimage encoding freezes at rc.0.
+
+### `Flow.fresh`
+
+- **Type:** `ExecutionIdSource`
+- **Since:** `0.1.0`
+
+The default execution-id source. Every invocation mints an independent cryptographic
+UUID. Save the returned execution id to reattach after a crash, or explicitly
+choose a declared idempotency key, `ensure`, or the `derived` source.
+
+### `Flow.CurrentExecutionIds`
+
+- **Type:** `Context.Reference<ExecutionIdSource>`
+- **Default:** `fresh`
+- **Since:** `0.1.0`
+
+The host's execution-id source. Its identifier is `"@smthrs/flow/Flow/CurrentExecutionIds"`.
+
+### `Flow.layerExecutionIds`
+
+- **Signature:** `layerExecutionIds(source: ExecutionIdSource): Layer.Layer<never>`
+- **Since:** `0.1.0`
+
+Declares the host's execution-id source as a layer. Callers that name an `executionId` and flows that declare an `idempotencyKey` are unaffected, because both are decided before the source is consulted.
+
+### `Flow.make`
+
+- **Signature:** `make(tag: Tag, options: { payload, declaredFrom?, description?, capabilities?, effects?, idempotencyKey?, success?, error?, suspendedRetryPolicy?, maxRounds?, deadline?, annotations?, model?, effort?, flows?, system?, chat?, body | prompt }): Flow<Tag, PayloadSchemaOf<Payload>, Success, Error, Requires>`
+- **Default:** `success` is `Schema.Void`, `error` is `Schema.Never`, `annotations` is `Context.empty()`
+- **Required:** `payload` and exactly one of `body` or `prompt`
+- **Since:** `0.1.0`
+
+Creates a durable flow definition. The `body` is the flow's one behavior, evaluated at plan time only, and it must be pure: it may not read mutable module state, clocks, random values, services, or values captured outside `payload`. A typed `prompt(payload)` lowers to one ordinary action named `<tag>/prompt`; its returned `PromptFlow` exposes the declaration as `action` and the renderer as `prompt`. The renderer runs only when the host implementation calls it. Optional `model`, `effort`, `flows`, `system`, and `chat` fields retain host metadata; annotation copies preserve them. `Flow.make` throws a `RangeError` when `maxRounds` is not a positive safe integer or `deadline` is not a positive finite duration of at most `Number.MAX_SAFE_INTEGER` milliseconds. `deadline` bounds one execution, counted from its journaled first start, so a resume after a restart honors the original deadline; on expiry the execution settles with `Flow.DeadlineExceeded` whether it was running or parked.
+
+`Flow.make` throws `TypeError` for a missing or blank tag, or when the declaration
+does not supply exactly one function as `body` or `prompt`.
+
+`declaredFrom: original` retains a native declaration's diagnostic source location,
+including its absence, while constructing a fresh flow with the supplied body.
+It does not change key material or execution identity.
+
+`description`, `capabilities`, and `effects` are declared as literals and lowered into the annotation bag, so a catalog reading the source text projects the same values `Graph.build` enforces. `effects` takes `{ reads, writes, mode, onConflict, tier? }` and is normalized by `Effects.make`.
+
+### `flow.start` and `flow.ensure`
+
+```ts
+import { Action, Flow } from "@smthrs/flow"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+
+const Step = Action.make("worker/step", {
+  payload: { id: Schema.String },
+  success: Schema.String
+})
+
+const flow = Flow.make("worker/run", {
+  payload: { id: Schema.String },
+  success: Schema.String,
+  body: (payload) => Step.call(payload)
+})
+
+const payload = { id: "job-1" }
+
+export const program = Effect.gen(function*() {
+  const freshId = yield* flow.start(payload)
+  const keyedId = yield* flow.ensure(payload, { key: "worker-1" })
+  return { freshId, keyedId }
+})
+```
+
+`start` admits a fresh execution, bypassing declared and ambient idempotency
+policies. `ensure` admits or joins the execution identified by the flow tag and
+caller key. Both return the execution id after admission and scheduling,
+without waiting for the child to settle, including inside an action.
+`execute(payload, { discard: true })` follows the same contract.
+
+The scheduled child belongs to the engine's scope and continues after the
+caller's action or parent round finishes. Keep that engine scope open. A memory
+engine loses its executions when the scope closes; a durable engine retains
+admission and progress for recovery. Explicit parent cancellation still follows
+the engine's cancellation policy for linked children.
+
+Use `flow.poll(id)` to observe the result, or
+`flow.execute(payload, { executionId: id })` to await completion. The returned
+id acknowledges admission, not a successful result or a reached wait point.
+
+### `Flow.MaxRoundsExceeded`
+
+- **Type:** `Schema.TaggedError` with fields `code: "max_rounds_exceeded"`, `flowName: string`, `lineageId: string`, `maxRounds: number`, `roundOrdinal: number`, and `message: string`
+- **Since:** `0.1.0`
+
+A lineage asked for one more round than its flow's `maxRounds` allows. It is recorded as a defect in the execution result, not as a typed `execute` failure.
+
+### `Flow.DeadlineExceeded`
+
+- **Type:** `Schema.TaggedError` with fields `code: "deadline_exceeded"`, `flowName: string`, `executionId: string`, `deadlineMs: number`, `startedAtMs: number`, and `message: string`
+- **Since:** `1.0.0`
+
+An execution was still unsettled when its flow's `deadline` elapsed. It is recorded as a defect in the execution result, not as a typed `execute` failure, and its attached children are cancelled with it.
+
+### `Flow.done`
+
+- **Signature:** `done<A>(value: A): Node.Node<Node.Succeed<Done<A>>>`
+- **Since:** `0.1.0`
+
+Ends a trampoline lineage with a value. The engine encodes the resulting value with the settling flow's success schema.
+
+Constant values use `Node.succeed`’s JSON projection; Dates become strings or `null`. Planned references retain their upstream result type.
+
+### `Flow.park`
+
+- **Signature:** `park(reason: WaitingAnnotation): Node.Node<Park>`
+- **Signature:** `park(reason: string, token?: string | undefined): Node.Node<Park>`
+- **Since:** `0.1.0`
+
+Parks the current round durably under a waiting reason, and an optional wake token.
+
+### `Flow.isOutcome`
+
+- **Signature:** `isOutcome(value: unknown): value is Outcome`
+- **Since:** `0.1.0`
+
+Whether a settled body value is one of the three trampoline settlements. Shape alone is deliberately insufficient, because ordinary success data may carry the same `_tag` fields. Graph construction carries a non-enumerable marker from the authoring node to its hydrated value, and the guard reads that marker.
+
+### `Flow.isResult`
+
+- **Signature:** `isResult<A = unknown, E = unknown>(u: unknown): u is Result<A, E>`
+- **Since:** `0.1.0`
+
+Whether a value is a flow `Result`.
+
+### `Flow.Result`
+
+- **Type:** `Complete<A, E> | Suspended | Handoff` as a type, and `Result(options: { readonly success: Success; readonly error: Error })` as a schema constructor
+- **Since:** `0.1.0`
+
+The result of a flow execution: a completed exit, a suspended state, or a handoff to the next round of a trampoline lineage.
+
+### `Flow.ResultEncoded`
+
+- **Type:** `CompleteEncoded<A, E> | typeof Suspended.Encoded | typeof Handoff.Encoded` as a type, and `Schema.Codec<ResultEncoded<any, any>>` as a schema
+- **Since:** `0.1.0`
+
+The encoded form of a flow `Result`, as it is stored.
+
+### `Flow.CompleteEncoded`
+
+- **Type:** `interface CompleteEncoded<A, E> { readonly _tag: "Complete"; readonly exit: ExitEncoded<A, E> }`
+- **Since:** `0.1.0`
+
+The encoded form of a completed result.
+
+### `Flow.Complete`
+
+- **Type:** `Data.TaggedClass("Complete")<{ readonly exit: Exit.Exit<A, E> }>`
+- **Since:** `0.1.0`
+
+A completed flow execution, carrying its success or failure `Exit`.
+
+### `Flow.Suspended`
+
+- **Type:** `Schema.Class` keyed `"@smthrs/flow/Flow/Suspended"` with fields `_tag: "Suspended"` and optional `cause`
+- **Since:** `0.1.0`
+
+A flow execution that parked on a durable wait. The optional `cause` carries what triggered the suspension.
+
+### `Flow.Handoff`
+
+- **Type:** `Schema.Class` keyed `"@smthrs/flow/Flow/Handoff"` with fields `_tag: "Handoff"`, `flow: NonEmptyString`, optional `capabilityCeilings`, `payload: Unknown`, and optional `deadline: LineageDeadline`
+- **Since:** `0.1.0`
+
+A round that ended by handing off to the next round of its trampoline lineage. `deadline` is the lineage deadline the next round runs under, stamped by a bounded round.
+
+### `Flow.LineageDeadline`
+
+- **Type:** `Schema.Struct({ startedAtMs: Number, deadlineMs: Number })`
+- **Since:** `1.0.0`
+
+The deadline a trampoline lineage's rounds share: the originating round's journaled first start and its bound, so every round expires at `startedAtMs + deadlineMs`.
+
+### `Flow.intoResult`
+
+- **Signature:** `intoResult<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<Result<A, E>, never, Exclude<R, Scope.Scope> | FlowInstance>`
+- **Since:** `0.1.0`
+
+Runs an effect as a flow execution and turns its outcome into a `Result`. It reads `CaptureDefects` and `SuspendOnFailure` from the flow's annotations, and closes the flow scope when the execution completes.
+
+### `Flow.wrapActionResult`
+
+- **Signature:** `wrapActionResult<A, E, R>(effect: Effect.Effect<A, E, R>, isSuspend: (value: A) => boolean): Effect.Effect<A, E, R | FlowInstance>`
+- **Since:** `0.1.0`
+
+Wraps an action-like effect so a flow suspension waits for the actions already running to finish or suspend.
+
+### `Flow.scope`
+
+- **Type:** `Effect.Effect<Scope.Scope, never, FlowInstance>`
+- **Since:** `0.1.0`
+
+The flow scope, which is closed only when the flow execution fully completes.
+
+### `Flow.provideScope`
+
+- **Signature:** `provideScope<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, Exclude<R, Scope.Scope> | FlowInstance>`
+- **Since:** `0.1.0`
+
+Provides the flow scope to an effect, so resources it acquires live as long as the execution does.
+
+### `Flow.addFinalizer`
+
+- **Signature:** `addFinalizer<R>(f: (exit: Exit.Exit<unknown, unknown>) => Effect.Effect<void, never, R>): Effect.Effect<void, never, FlowInstance | R>`
+- **Since:** `0.1.0`
+
+Adds an exit finalizer to the flow scope, preserving the services available when the finalizer is registered.
+
+### `Flow.withRollback`
+
+- **Signature:** `withRollback<A, E, R, R2>(effect: Effect.Effect<A, E, R>, rollback: (value: A, cause: Cause.Cause<unknown>) => Effect.Effect<void, never, R2>): Effect.Effect<A, E, R | R2 | FlowInstance | Scope.Scope>`
+- **Since:** `0.1.0`
+
+Runs an effect and registers how to undo its successful result if the enclosing flow later exits unsuccessfully. An effect that fails registers no rollback. A flow that succeeds discards it. The data-last form takes the rollback alone.
+
+### `Flow.suspend`
+
+- **Signature:** `suspend(instance: FlowInstance["Service"]): Effect.Effect<never>`
+- **Since:** `0.1.0`
+
+Marks a flow instance suspended and interrupts the current fiber, stopping execution until the run is resumed.
+
+## FlowRuntime
+
+### `FlowRuntime.CancelRequestFailed`
+
+- **Type:** `Schema.TaggedError` with fields `code: "cancel_request_failed" | "unsafe_interrupt_unsupported"`, `executionId: string`, and `reason: string`
+- **Since:** `0.1.0`
+
+A runtime could not durably record a cancellation request. `cancel_request_failed` is a storage failure on a supported request. `unsafe_interrupt_unsupported` is the durable engine refusing `interruptUnsafe`, which it does not implement.
+
+### `FlowRuntime.FlowCycleDetected`
+
+- **Type:** `Schema.TaggedError` with fields `code: "flow_cycle_detected"` and `path: ReadonlyArray<string>`
+- **Since:** `0.1.0`
+
+Executing a flow would close a cycle in the persisted parent-execution chain. `path` holds the ordered execution ids from the cycle's target back to itself.
+
+### `FlowRuntime.FlowExecutionNotFound`
+
+- **Type:** `Schema.TaggedError` with fields `code: "execution_not_found"` and `executionId: string`
+- **Since:** `0.1.0`
+
+`poll` was given an execution id the runtime never recorded. `resume` has no error channel and returns without effect for an unknown id.
+
+### `FlowRuntime.FlowInstance`
+
+- **Type:** `Context.Service` keyed `"@smthrs/flow/FlowRuntime/FlowInstance"`
+- **Since:** `0.1.0`
+
+One execution's state: `executionId`, `lineageId`, `flow`, a `scope` closed only when the flow completes, the mutable `suspended`, `interrupted`, `waiting`, `handoff`, and `cause` fields, the optional `lineageDeadline` a round after a handoff inherited, and `actionState`. This package declares the contract; a runtime constructs the value. A completion wakes a parked run through `FlowRuntime.resume`.
+
+### `FlowRuntime.DeferredDoneIfWaitingOutcome`
+
+- **Type:** `"Completed" | "Existing" | "NotWaiting"`
+- **Since:** `1.0.0`
+
+The result of atomically completing a deferred only while its run is parked.
+
+### `FlowRuntime.ResumeOptions`
+
+- **Type:** `interface ResumeOptions { readonly delegated?: boolean | undefined }`
+- **Since:** `1.0.0`
+
+How a caller asks `resume` to re-drive a suspended execution. Without options, `resume` is the operator's own request, which is consent to recover a quarantined execution. `delegated: true` marks a background resume a host takes up for someone else, such as an approval decision or a saved request. A durable engine refuses it for a quarantined execution in the same transaction that reads the park, so a peer that quarantines the run after the host checked it cannot turn the delegation into recovery consent.
+
+### `FlowRuntime.FlowRuntime`
+
+- **Type:** `Context.Service` keyed `"@smthrs/flow/FlowRuntime"`
+- **Since:** `0.1.0`
+
+The port the authoring APIs are written against. It exposes `register`, `execute`, `poll`, `interrupt`, `interruptUnsafe`, `resume`, `actionExecute`, `deferredResult`, `deferredDone`, `deferredDoneIfWaiting`, `scheduleClock`, and the optional `recordNode` and `nodeRecordBytes`. This package declares the port and depends on nothing that implements it, so the dependency direction runs from `@smthrs/flow` to `@smthrs/engine` to the durable stores.
+
+`recordNode(record: NodeRecord): Effect.Effect<void, never, FlowInstance>` is optional in the strong sense: a runtime that keeps no history leaves it absent and skips journal preflight. A recording runtime can refuse oversized node topology before the walk starts. An implementation must write the record under the record's own `sourceId` rather than minting an identity per observation, because that is what makes a resumed walk collapse onto the rows the first walk wrote instead of doubling every node.
+
+### `FlowRuntime.NodeRecord`
+
+- **Type:** `PlanRecorded | SubgraphAppended | NodeScheduled | NodeSettled`
+- **Since:** `1.0.0`
+
+What a driven graph tells its runtime about itself, and the only thing this package says about where the records go. Every record carries its own replay-stable `sourceId`, which is its producer identity. `PlanRecorded` carries `flow`, `generation`, `page`, `pages`, the whole graph's `nodeCount`, and this page's `nodes` and `edges`. `SubgraphAppended` is one further page of the same graph and carries everything but `nodeCount`. `NodeScheduled` carries `nodeId`, `kind`, `attempt`, and the optional `action`; no step key digest rides there, because the engine allocates a dispatch's ordinal when the dispatch happens, which is after the record is written. `NodeSettled` carries `nodeId`, `outcome`, `attempts`, `stepKeyDigests`, the optional `action`, and the `value` the node settled with. `attempts` is the highest durable attempt any of the node's dispatches ran as, so a node whose action was retried says two; `stepKeyDigests` names the distinct dispatches it drove, which is what joins `flows.engine.attempt-started` back to a plan node; `value` is handed over whole and unbounded, and bounding and redacting it belongs to the writer that knows where it is going. A large graph is paged rather than truncated, because a journal entry has a byte bound and a projection that clipped one would lose nodes silently.
+
+### `FlowRuntime.NodeSummary`
+
+- **Type:** `interface NodeSummary { readonly id: string; readonly kind: string; readonly dependsOn: ReadonlyArray<string>; readonly tier: "sealed" | "compensable" | "irreversible"; readonly action?: string | undefined; readonly effects?: Plan.NodeEffects | undefined; readonly declaredAt?: { readonly path: string; readonly line: number } | undefined }`
+- **Since:** `1.0.0`
+
+One node of the graph a run was driven from. `tier` and `effects` are the declaration's own and `dependsOn` is the material dependency set the plan compiles edges from. `action` is the tag the node dispatches, absent on every node that dispatches nothing. `declaredAt` is provenance and never identity: it is outside key material by construction, so a node recorded with it is keyed exactly as the same node without it.
+
+### `FlowRuntime.EdgeSummary`
+
+- **Type:** `interface EdgeSummary { readonly from: string; readonly to: string; readonly reason: "value" | "continuation" | "failure" }`
+- **Since:** `1.0.0`
+
+One edge of the recorded graph, with the reason the builder drew it. A page carries the edges that END on its nodes, so an assembled set of pages is the whole graph and no page names an edge whose destination is missing.
+
+### `FlowRuntime.NodeOutcome`
+
+- **Type:** `"built" | "clean" | "failed" | "skipped"`
+- **Since:** `1.0.0`
+
+How a node left the walk. `built` ran, `clean` was served entirely from durable records, `failed` raised, and `skipped` is a node the walk never reached: an untaken branch arm, or a dependent of something that failed.
+
+### `FlowRuntime.WaitingAnnotation`
+
+- **Type:** `interface WaitingAnnotation { readonly reason: string; readonly wakeAt?: number | undefined; readonly token?: string | undefined }`
+- **Schema:** `Schema.Struct({ reason: Schema.String, wakeAt: Schema.optional(Schema.Number), token: Schema.optional(Schema.String) })`
+- **Since:** `0.1.0`
+
+The waiting classification a flow declares before suspending. `Flow.Park`
+carries this schema as its `reason`, so a parking request and the annotation
+that precedes a suspension cannot describe different waits.
+
+### `FlowRuntime.annotateWaiting`
+
+- **Signature:** `annotateWaiting(waiting: WaitingAnnotation | undefined): Effect.Effect<void, never, FlowInstance>`
+- **Since:** `0.1.0`
+
+Declares how the flow is about to wait, so a durable driver parks the run under that reason and token instead of the derived `timer` or `event` default.
+
+## Graph
+
+### `Graph.EdgeReason`
+
+- **Type:** `"value" | "continuation" | "failure"`
+- **Since:** `0.1.0`
+
+Why one node depends on another. `value` consumes a result. `continuation` is the sequencing edge a builder or a branch arm records against the upstream node it was evaluated with.
+
+### `Graph.Edge`
+
+- **Type:** `interface Edge { readonly from: string; readonly to: string; readonly reason: EdgeReason }`
+- **Since:** `0.1.0`
+
+A dependency edge, pointing from the node that produces to the node that consumes.
+
+### `Graph.GraphNode`
+
+- **Type:** `interface GraphNode` with `id`, `kind`, `dependencies`, `capabilities`, `placement`, `draft`, the authoring node it was observed at, and `declaredAt?: { readonly path: string; readonly line: number } | undefined`
+- **Since:** `0.1.0`
+
+One observed node: its structural address, the authoring variant it came from, and the `Plan.NodeDraft` the plan is compiled from. `kind` is the authoring variant, not the plan's node kind. Every draft a graph produces is a plan `step`. `declaredAt` is where the declaration this node was observed at was written, when the runtime's stack format says so: it is provenance outside `KeyMaterial`, so a node carrying it is byte-identical to the same node without it, and it is absent for a node with no declaration to read and for a declaration the framework itself made.
+
+### `Graph.LayerRequest`
+
+- **Type:** `interface LayerRequest { readonly nodeId: string; readonly kind: Node.Ast["_tag"]; readonly capabilities: ReadonlyArray<string>; readonly effects: Annotations.Effects | undefined; readonly placement: unknown }`
+- **Since:** `0.1.0`
+
+What a pure per-node layer resolver is told. It is the identity of the implementation a node would run against, never a layer value or a runtime handle.
+
+### `Graph.BuildOptions`
+
+- **Type:** `interface BuildOptions { readonly resolveLayers?: ((request: LayerRequest) => Iterable<string>) | undefined; readonly callbackIdentity?: "stable" | "process-local" | undefined; readonly root?: string | undefined }`
+- **Default:** `root` is `"root"`; `callbackIdentity` is `"process-local"`
+- **Since:** `0.1.0`
+
+The options `Graph.build` takes. `resolveLayers` is invoked once per node and 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.
+
+### `Graph.Graph`
+
+- **Type:** `interface Graph { readonly nodes: ReadonlyArray<GraphNode>; readonly edges: ReadonlyArray<Edge>; readonly diagnostics: ReadonlyArray<GraphBuildError> }`
+- **Since:** `0.1.0`
+
+A built graph: the nodes in dependency order, the edges between them, and the refusals recoverable enough to report rather than throw. The drafts are deliberately not a field, because the derivation carries a refusal.
+
+### `Graph.build`
+
+- **Signature:** `build(flowOrNode: Flow.Any | Node.Any, payload?: unknown, options: BuildOptions = {}): Graph`
+- **Since:** `0.1.0`
+
+Builds the graph of a flow declaration, or of a bare node, by walking the authoring tree once. Building is a pure function of the declarations and the payload, so the shape of a round is known before its first action runs. It refuses a nesting depth past its bound and a duplicate node id, because a node id is durable dispatch identity.
+
+### `Graph.nodes`
+
+- **Signature:** `nodes(graph: Graph): ReadonlyArray<GraphNode>`
+- **Since:** `0.1.0`
+
+The observed nodes, children before the parents that consume them.
+
+### `Graph.edges`
+
+- **Signature:** `edges(graph: Graph): ReadonlyArray<Edge>`
+- **Since:** `0.1.0`
+
+The dependency edges, in the order they were observed.
+
+### `Graph.drafts`
+
+- **Signature:** `drafts(graph: Graph): ReadonlyArray<Plan.NodeDraft>`
+- **Since:** `0.1.0`
+
+The drafts, in node order, ready for `Plan.compile` or `Plan.append` unchanged. A graph carrying diagnostics is inspectable but not compilable, so this accessor throws the first typed build refusal instead of returning partial drafts.
+
+### `Graph.diagnostics`
+
+- **Signature:** `diagnostics(graph: Graph): ReadonlyArray<GraphBuildError>`
+- **Since:** `0.1.0`
+
+The recoverable topology issues recorded during the build, 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.
+
+## HumanTask
+
+### `HumanTask.Kind`
+
+- **Type:** `"ask" | "confirm" | "select" | "json"` as a type, and `Schema.Literals(["ask", "confirm", "select", "json"])` as a schema
+- **Since:** `0.1.0`
+
+The shape a person is asked for. `ask` wants prose, `confirm` wants a boolean, `select` wants one of the options the task names, and `json` wants a value the task's JSON Schema accepts.
+
+### `HumanTask.HumanTaskFailed`
+
+- **Type:** `Schema.TaggedError` with fields `code: "request_invalid" | "rejected" | "timeout"`, `task: string`, `attempts: number`, `rejections: ReadonlyArray<string>`, and `message: string`
+- **Since:** `0.1.0`
+
+A question that ended without an answer the task could accept. `request_invalid` refuses an unanswerable question before anyone is asked. `rejected` means the attempt budget was spent on answers the task refused. `timeout` means the deadline passed with the question open.
+
+### `HumanTask.HumanAnswerInvalid`
+
+- **Type:** `Schema.TaggedError` with fields `code: "answer_invalid" | "answer_not_open"` and `message: string`
+- **Default:** `code` defaults to `"answer_invalid"`
+- **Since:** `1.0.0`
+
+An answer refused before it could consume durable storage.
+
+### `HumanTask.tag`
+
+- **Type:** `"system/human-task"`
+- **Since:** `0.1.0`
+
+The tag the human-task declaration is catalogued and resolved under.
+
+### `HumanTask.defaultMaxAttempts`
+
+- **Type:** `10`
+- **Since:** `0.1.0`
+
+The attempt budget a task that names none is asked under.
+
+### `HumanTask.maxSchemaDepth`
+
+- **Type:** `32`
+- **Since:** `0.1.0`
+
+The deepest supported JSON Schema path, counting the root as depth zero.
+
+### `HumanTask.maxSchemaNodes`
+
+- **Type:** `512`
+- **Since:** `0.1.0`
+
+The most schema objects one human-task request may contain.
+
+### `HumanTask.maxSchemaValueNodes`
+
+- **Type:** `10_000`
+- **Since:** `1.0.0`
+
+The most JSON values embedded across schema keywords such as `enum`.
+
+### `HumanTask.maxSchemaValueDepth`
+
+- **Type:** `64`
+- **Since:** `1.0.0`
+
+The deepest JSON value embedded in a schema, including enum members.
+
+### `HumanTask.maxAnswerNodes`
+
+- **Type:** `10_000`
+- **Since:** `0.1.0`
+
+The most JSON values one answer validation may visit.
+
+### `HumanTask.maxAnswerBytes`
+
+- **Type:** `256 * 1024`
+- **Since:** `1.0.0`
+
+The largest encoded JSON answer that can enter the durable store.
+
+### `HumanTask.maxSchemaBytes`
+
+- **Type:** `256 * 1024`
+- **Since:** `1.0.0`
+
+The largest encoded JSON Schema carried by one question.
+
+### `HumanTask.maxAnswerDepth`
+
+- **Type:** `64`
+- **Since:** `1.0.0`
+
+The deepest admitted answer tree.
+
+### `HumanTask.maxJsonStringBytes`
+
+- **Type:** `128 * 1024`
+- **Since:** `1.0.0`
+
+The largest encoded string value admitted in a request or an answer.
+
+### `HumanTask.maxJsonKeyBytes`
+
+- **Type:** `4 * 1024`
+- **Since:** `1.0.0`
+
+The largest encoded object key admitted in a request or an answer.
+
+### `HumanTask.maxJsonMembers`
+
+- **Type:** `10_000`
+- **Since:** `1.0.0`
+
+The most members admitted in one JSON array or object.
+
+### `HumanTask.maxTaskNameBytes`
+
+- **Type:** `1_024`
+- **Since:** `1.0.0`
+
+The largest encoded task name.
+
+### `HumanTask.maxPromptBytes`
+
+- **Type:** `64 * 1024`
+- **Since:** `1.0.0`
+
+The largest encoded prompt.
+
+### `HumanTask.maxOptions`
+
+- **Type:** `256`
+- **Since:** `1.0.0`
+
+The largest option list on one select question.
+
+### `HumanTask.maxOptionBytes`
+
+- **Type:** `4 * 1024`
+- **Since:** `1.0.0`
+
+The largest encoded select option.
+
+### `HumanTask.maxAttemptBudget`
+
+- **Type:** `1_000`
+- **Since:** `0.1.0`
+
+The largest attempt budget one human task may declare.
+
+### `HumanTask.maxDiagnosticChars`
+
+- **Type:** `512`
+- **Since:** `0.1.0`
+
+The most caller-supplied characters retained in one rendered diagnostic. A longer value is truncated with an explicit marker.
+
+### `HumanTask.maxRetainedRejectionChars`
+
+- **Type:** `8_192`
+- **Since:** `0.1.0`
+
+The most characters retained across a terminal failure's rejection list. The list records how many further rejections it omitted, and each per-attempt journal step still holds its own full reason.
+
+### `HumanTask.deferred`
+
+- **Signature:** `deferred(name: string, attempt: number): DurableDeferred.DurableDeferred<typeof Schema.Json>`
+- **Since:** `0.1.0`
+
+The durable deferred one attempt at answering resolves through, named `WaitFor/<name>#<attempt>`. Attempts are separate wait points, because a durable deferred records the first completion and replays it forever.
+
+### `HumanTask.Request`
+
+- **Type:** `interface Request { readonly kind: Kind; readonly options?: ReadonlyArray<string> | undefined; readonly schema?: unknown }`
+- **Since:** `0.1.0`
+
+What `HumanTask.validate` checks an answer against. `options` is ignored for `json`, because an option list alone constrains no JSON value.
+
+### `HumanTask.validateSchema`
+
+- **Signature:** `validateSchema(schema: unknown, path: ReadonlyArray<string> = []): string | undefined`
+- **Since:** `0.1.0`
+
+Checks that a JSON Schema stays inside the bounded subset at every depth. It returns the first reason the schema is out of bounds, or `undefined` when the whole tree is inside it.
+
+### `HumanTask.validate`
+
+- **Signature:** `validate(value: unknown, request: Request): string | undefined`
+- **Since:** `0.1.0`
+
+Checks one answer against the question that was asked. It returns the reason the answer was refused, or `undefined`. Run it in the interface so a typo is refused while the person is still looking at it.
+
+### `HumanTask.action`
+
+- **Type:** `Action.Declared<typeof tag, Schema.Struct<{ name, kind, prompt, options?, schema?, timeoutMs?, maxAttempts? }>, typeof Schema.Json, typeof HumanTaskFailed, never>`
+- **Since:** `0.1.0`
+
+The declared `system/human-task` step. `name` addresses the question, so two calls naming one question in one execution await one answer. The node settles with the answer, and `HumanTask.decode` gives that answer the caller's own type.
+
+### `HumanTask.layer`
+
+- **Type:** `Layer.Layer<never, never, Crypto.Crypto | FlowRuntime>`
+- **Since:** `0.1.0`
+
+The human-task implementation: park, validate, re-ask, settle. Provide it beside the other action implementation layers, over `Action.layerImplementations`.
+
+### `HumanTask.answer`
+
+- **Signature:** `answer(options: { readonly token: DurableDeferred.Token; readonly value: typeof Schema.Json.Type }): Effect.Effect<void, DurableDeferred.TokenInvalid | HumanAnswerInvalid, FlowRuntime>`
+- **Since:** `0.1.0`
+
+Records one answer to a human task. `token` is the value the run parked with. The runtime checks that exact approval wait and records the completion as one mutation, so a guessed, unopened, or stale token cannot pre-answer a run. A token whose deferred name `HumanTask.deferred` could not have written fails with `TokenInvalid` carrying `deferred_mismatch`. The token does not authorize the caller: anyone who knows or derives the open attempt's address can answer it, so the host must decide who may answer before calling `answer`.
+
+### `HumanTask.decode`
+
+- **Signature:** `decode<S extends Schema.ConstraintDecoder<unknown>>(schema: S): <E, R>(self: Node.Node<typeof Schema.Json.Type, E, R>) => Node.Node<S["Type"], E, R>`
+- **Since:** `0.1.0`
+
+Gives an answer the caller's own type. The schema here and the question's own schema description must agree; a disagreement surfaces as a defect rather than a failure a body could catch.
+
+## Interpreter
+
+### `Interpreter.InterpreterError`
+
+- **Type:** `Schema.TaggedError` with fields `code`, `flow: string`, `node: string`, and `message: string`
+- **Since:** `0.1.0`
+
+A graph the interpreter refuses to drive. The `code` is one of `incomplete_graph`, `duplicate_node_id`, `unresolved_action`, `implementation_version_mismatch`, `missing_implementation_version`, `unresolved_reference`, `unsupported_call`, `missing_operation`, `node_record_too_large`, or `join_mismatch` (a race, any, or quorum journaled members, or a losing child boundary, its plan can no longer reproduce).
+
+### `Interpreter.Interpretation`
+
+- **Type:** `interface Interpretation { readonly value: unknown; readonly settled: ReadonlyMap<string, unknown>; readonly failed: ReadonlyMap<string, unknown>; readonly skipped: ReadonlyArray<string> }`
+- **Since:** `0.1.0`
+
+What one interpretation produced: the root's value, every node that settled with the value it settled with, the typed failures observed before a catch recovered them, and the nodes the run never reached because a branch went the other way.
+
+### `Interpreter.childExecutionId`
+
+- **Signature:** `childExecutionId(parentExecutionId: string, nodeId: string, calleeTag: string, payload: unknown): Effect.Effect<string, never, Crypto.Crypto>`
+- **Since:** `0.1.0`
+
+The execution id a `child` boundary runs its child under, derived from the parent execution id, the node id, the callee tag, and the payload digest.
+
+### `Interpreter.maximumPageBytes`
+
+- **Type:** `number`
+- **Default:** `12_000`
+- **Since:** `1.0.0`
+
+The largest UTF-8 encoded plan page, including its envelope. The runtime's
+optional `nodeRecordBytes` hook measures a conservative complete journal entry;
+without a writer hook the interpreter measures the whole node record. Nothing
+about one node has to fit one page: a node is seated with no dependencies on
+it, and its dependency list and its incoming edges are spread over as many
+following pages as they need, so an input-driven fan-in of any width is
+recorded rather than refused. A continuation page re-seats the same summary
+with the next disjoint slice of `dependsOn`; a reader assembles pages in order,
+unions `dependsOn` per node id and concatenates edges. Only a node whose
+summary with NO dependencies on it still exceeds the budget is refused, with
+`node_record_too_large`, before any page or action is written. Every page has a
+deterministic source id across resume. The gateway refuses a bridged graph
+event exceeding 16 KiB including its control envelope; it never clips
+topology.
+
+### `Interpreter.interpret`
+
+- **Signature:** `interpret(flowOrNode: Flow.Any | Node.Any, payload?: unknown, options: Graph.BuildOptions = {}): Effect.Effect<Interpretation, unknown, Services>`
+- **Since:** `0.1.0`
+
+Builds and walks the graph of a flow body, or of a bare node, against real values. 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.
+
+One call is one interpretation of one execution. A runtime that implements `recordNode` addresses the records of a call by the graph's own ids under the current execution, so calling `interpret` twice inside a single execution would address the second graph's records exactly as the first graph's, and a journal that dedupes on identity would keep the first. `Interpreter.layer` gives every trampoline round its own execution id and never does this; a direct caller that wants two graphs recorded separately runs them under separate executions.
+
+### `Interpreter.layer`
+
+- **Type:** `Layer.Layer<never, never, FlowRuntime | Implementations | ...schema services>`
+- **Signature:** `layer(flow: Flow<Tag, Payload, Success, Error, any>, options: Graph.BuildOptions = {}): Layer.Layer<...>`
+- **Since:** `0.1.0`
+
+Registers a flow with the runtime and installs the handler that drives its body. It is the only way a flow's behavior reaches the runtime, and the reason a flow has no `toLayer`. Compose it beside the action implementation layers the body calls, over `Action.layerImplementations`.
+
+### `Interpreter.layerWithImplementations`
+
+- **Signature:** `layerWithImplementations(flow: Flow<Tag, Payload, Success, Error, Requires>, implementations: Layer.Layer<Provided, E, R>, options: Graph.BuildOptions = {}): Layer.Layer<...>`
+- **Since:** `0.1.0`
+
+Builds the interpreter and the action implementations against one fresh, isolated `Action.Implementations` table. The types require every action the flow names. `callbackIdentity` defaults to `"stable"`. A conflicting same-tag registration dies during layer construction unless it passes `{ override: true }`.
+
+## Poll
+
+### `Poll.Backoff`
+
+- **Type:** `"fixed" | "linear" | "exponential"`
+- **Since:** `0.1.0`
+
+How the wait between attempts grows.
+
+### `Poll.Check`
+
+- **Type:** `interface Check<out Result> { readonly satisfied: boolean; readonly output: Result }`
+- **Since:** `0.1.0`
+
+What a check reports: whether the poll is over, and the value this attempt read.
+
+### `Poll.CheckResult`
+
+- **Signature:** `CheckResult<Result extends Schema.Top>(result: Result): Schema.Struct<{ readonly satisfied: typeof Schema.Boolean; readonly output: Result }>`
+- **Since:** `0.1.0`
+
+The success schema a check action declares.
+
+### `Poll.PollExhausted`
+
+- **Type:** `Schema.TaggedError` with fields `code: "poll_exhausted"`, `poll: string`, `attempts: number`, and `message: string`
+- **Since:** `0.1.0`
+
+A poll used its last attempt without a satisfied check. The wire shape freezes at 1.0.0-rc.0.
+
+### `Poll.exhaustedTag`
+
+- **Type:** `"system/poll-exhausted"`
+- **Since:** `0.1.0`
+
+The tag the exhaustion step is catalogued and resolved under.
+
+### `Poll.exhausted`
+
+- **Type:** `Action.Declared<typeof exhaustedTag, Schema.Struct<{ readonly poll: typeof Schema.String; readonly attempts: typeof Schema.Number }>, typeof Schema.Never, typeof PollExhausted, never>`
+- **Since:** `0.1.0`
+
+The declared step a poll takes when its last attempt was not satisfied.
+
+### `Poll.delayMillis`
+
+- **Signature:** `delayMillis(options: { readonly intervalMs: number; readonly backoff: Backoff; readonly attempt: number }): number`
+- **Since:** `0.1.0`
+
+The wait before the attempt after this one, in milliseconds. `fixed` returns the interval, `linear` multiplies it by the attempt, and `exponential` multiplies it by 2 raised to the attempt minus one.
+
+### `Poll.Failure`
+
+- **Type:** `Schema.Union<readonly [typeof PollExhausted, typeof Sleep.SleepRequestInvalid]>`
+- **Since:** `0.1.0`
+
+What a poll round can fail with. `SleepRequestInvalid` is part of it because the wait between attempts is an ordinary `Sleep.action` node, and a round payload can carry an attempt that derives an invalid wait.
+
+### `Poll.PayloadSchema`
+
+- **Type:** `Schema.Struct<Input & { readonly attempt: Schema.optional<typeof Schema.Number> }>`
+- **Since:** `0.1.0`
+
+The payload schema `Poll.make` derives from an author's input fields: the author's own fields, plus the attempt this round is. `attempt` is optional, and the first round reads it as one.
+
+### `Poll.make`
+
+- **Signature:** `make(tag: Tag, options: { readonly input: Input; readonly result: Result; readonly check: (payload: Schema.Struct.Type<Input> & { readonly attempt: number }) => Node.Node<Check<Result["Type"]>, never, R>; readonly intervalMs: number; readonly maxAttempts: number; readonly backoff?: Backoff | undefined; readonly onTimeout?: "fail" | "return-last" | undefined }): Flow.Flow<Tag, PayloadSchema<Input>, Result, typeof Failure, R>`
+- **Required:** `input`, `result`, `check`, `intervalMs`, and `maxAttempts`
+- **Since:** `0.1.0`
+
+Declares a durable poller and returns an ordinary flow. Its body is one attempt: run `check`, then either settle the lineage with the check's output or sleep for this attempt's delay and hand off to the next round with the attempt counter raised. `maxAttempts` is also the flow's `maxRounds`. `onTimeout` chooses between failing with `PollExhausted` at the bound and answering with the last check output. The check may not fail; state what a failure means with `Node.catch` inside the fragment.
+
+`Poll.make` throws a `TypeError` when `input` declares the reserved `attempt` field, and a `RangeError` when `intervalMs` is not a duration a clock accepts, when `maxAttempts` is not a whole number of attempts of at least one, or when the interval under the declared backoff reaches a wait no clock can be armed with before the budget is spent.
+
+### `Poll.layer`
+
+- **Type:** `Layer.Layer<never, never, Crypto.Crypto | FlowRuntime>`
+- **Since:** `0.1.0`
+
+The exhaustion implementation, provided beside the other action layers a poll's rounds call.
+
+## RetryPolicy
+
+### `RetryPolicy.RetryPolicy`
+
+- **Type:** `Schema.Struct({ initialMs: Schema.Number, factor: Schema.Number, maxMs: Schema.Number, maxAttempts: Schema.optional(Schema.Number), expirationMs: Schema.optional(Schema.Number), jitterRatio: Schema.optional(Schema.Number), nonRetryable: Schema.optional(Schema.Array(Schema.String)) })` refined by a `validRetryPolicy` filter, with the type alias `typeof RetryPolicy.Type`
+- **Since:** `0.1.0`
+
+A retry policy as plain data, so the next delay is derived from a persisted attempt count instead of fiber-local `Schedule` state. Decoding enforces the same relational contract as `RetryPolicy.make`, so persisted data cannot bypass the constructor checks.
+
+### `RetryPolicy.make`
+
+- **Signature:** `make(options: { readonly initialMs: number; readonly factor: number; readonly maxMs: number; readonly maxAttempts?: number | undefined; readonly expirationMs?: number | undefined; readonly jitterRatio?: number | undefined; readonly nonRetryable?: ReadonlyArray<string> | undefined }): RetryPolicy`
+- **Required:** `initialMs`, `factor`, and `maxMs`
+- **Since:** `0.1.0`
+
+Creates a policy after checking every numeric bound, and throws a `RangeError` naming the field that is wrong: `initialMs` finite and greater than zero, `factor` finite and positive, `maxMs` finite and not below `initialMs`, `maxAttempts` a safe integer of at least one, `expirationMs` finite and positive, and `jitterRatio` finite and within zero and one inclusive. `initialMs: 0` is refused rather than read as an immediate retry, because every computed delay would be zero and `nextDelay` would report the policy exhausted on the first failure; use `initialMs: 1` for a near-immediate retry. `jitterRatio: 0` disables jitter. The `nonRetryable` array is copied and frozen, so a later mutation of the caller's array cannot change what a parked policy means.
+
+### `RetryPolicy.transient`
+
+- **Type:** `RetryPolicy`
+
+Frozen infrastructure policy: `initialMs: 5000`, `factor: 2`, `maxMs: 300000`,
+`expirationMs: 7200000`. Dispatch uses it by default for repeat-safe typed
+infrastructure failures; `Fault.retryTransient` uses it for plain effects.
+
+### `RetryPolicy.defaultRetryPolicy`
+
+- **Type:** `RetryPolicy`
+- **Default:** `{ initialMs: 200, factor: 1.5, maxMs: 30000 }`
+- **Since:** `0.1.0`
+
+The default engine retry policy. It declares neither `maxAttempts` nor `expirationMs`, so it never gives up. Bound long-lived retries with `make({ ..., expirationMs })` when a wall-clock give-up is required.
+
+### `RetryPolicy.RetryAfter`
+
+- **Type:** `interface RetryAfter { readonly _tag: "RetryAfter"; readonly delayMs: number }`
+- **Since:** `0.1.0`
+
+A retry decision: wait `delayMs` before the next attempt.
+
+### `RetryPolicy.GiveUp`
+
+- **Type:** `interface GiveUp { readonly _tag: "GiveUp"; readonly reason: "nonRetryable" | "exhausted" | "expired" }`
+- **Since:** `0.1.0`
+
+A retry decision: stop retrying, with the reason the policy stopped.
+
+### `RetryPolicy.RetryDecision`
+
+- **Type:** `RetryAfter | GiveUp`
+- **Since:** `0.1.0`
+
+The outcome of the engine's retry decision point.
+
+### `RetryPolicy.retryAfter`
+
+- **Signature:** `retryAfter(delayMs: number): RetryDecision`
+- **Since:** `0.1.0`
+
+Creates a `RetryAfter` decision.
+
+### `RetryPolicy.giveUp`
+
+- **Signature:** `giveUp(reason: GiveUp["reason"]): RetryDecision`
+- **Since:** `0.1.0`
+
+Creates a `GiveUp` decision.
+
+### `RetryPolicy.RetryPolicyExpired`
+
+- **Type:** `Schema.TaggedError` with fields `code: "retry_policy_expired"`, `actionName: string`, `attempt: number`, `expirationMs: number`, and optional `lastError`
+- **Since:** `0.1.0`
+
+A historical retry sequence crossed the policy's `expirationMs` wall-clock bound. Current engines preserve the final declared failure instead; the schema remains for reading old outcomes.
+
+### `RetryPolicy.RetryAttemptsExhausted`
+
+- **Type:** `Schema.TaggedError` with fields `code: "retry_attempts_exhausted"`, `actionName: string`, `attempt: number`, `maxAttempts: number`, and optional `lastError`
+- **Since:** `0.1.0`
+
+A historical retry sequence exhausted the policy's `maxAttempts` bound. Current engines preserve the final declared failure instead; the schema remains for reading old outcomes.
+
+### `RetryPolicy.nextDelay`
+
+- **Signature:** `nextDelay(policy: RetryPolicy, attempt: number, options?: { readonly random?: number | undefined; readonly elapsedMs?: number | undefined }): Option.Option<number>`
+- **Default:** `random` is `1`, which leaves the delay un-jittered
+- **Since:** `0.1.0`
+
+Computes the delay before attempt `attempt + 1` from the persisted attempt count, mirroring Temporal's `ComputeNextDelay`. `attempt` is the one-based attempt that failed. It returns `None` when the policy gives up: `maxAttempts` reached, a non-positive computed interval, a cap below the initial interval, or an elapsed duration past `expirationMs`. It is total even for a policy decoded from a persisted row, so a non-finite attempt, elapsed time, bound, or computed delay answers `None` rather than handing the engine a negative or `NaN` duration.
+
+### `RetryPolicy.nextDelayEffect`
+
+- **Signature:** `nextDelayEffect(policy: RetryPolicy, attempt: number, options?: { readonly elapsedMs?: number | undefined }): Effect.Effect<Option.Option<number>>`
+- **Since:** `0.1.0`
+
+Computes the next delay, sampling the `Random` service for jitter. A policy with no `jitterRatio`, or one at or below zero, skips the sample.
+
+### `RetryPolicy.errorTag`
+
+- **Signature:** `errorTag(error: unknown): string | undefined`
+- **Since:** `0.1.0`
+
+Extracts the stable identity tag of an error for non-retryable matching: an own string `_tag` when present, otherwise the first own `name` descriptor found while walking a bounded prototype chain. That first descriptor decides the result, and only a string data value is a tag.
+
+### `RetryPolicy.defaultNonRetryable`
+
+- **Type:** `ReadonlyArray<string>`
+- **Default:** `["@smthrs/engine-store/CacheCorruptionDetected", "@smthrs/engine-store/AttemptEvidenceQuarantined"]`
+- **Since:** `0.1.0`
+
+The error tags that are non-retryable by type, under every policy. They are integrity verdicts that must reach the driver without an action-level retry hiding the first detection. There is no per-callsite or per-policy opt-out.
+
+### `RetryPolicy.isNonRetryable`
+
+- **Signature:** `isNonRetryable(policy: RetryPolicy, error: unknown): boolean`
+- **Since:** `0.1.0`
+
+Whether an error is classified non-retryable, by `defaultNonRetryable` or by the policy's declared tag list.
+
+### `RetryPolicy.decide`
+
+- **Signature:** `decide(policy: RetryPolicy, options: { readonly attempt: number; readonly error: unknown; readonly random?: number | undefined; readonly elapsedMs?: number | undefined }): RetryDecision`
+- **Since:** `0.1.0`
+
+The pure core of the engine's single retry decision point. Non-retryable errors are classified here and nowhere else.
+
+### `RetryPolicy.decideEffect`
+
+- **Signature:** `decideEffect(policy: RetryPolicy, options: { readonly attempt: number; readonly error: unknown; readonly elapsedMs?: number | undefined }): Effect.Effect<RetryDecision>`
+- **Since:** `0.1.0`
+
+The effect form of `RetryPolicy.decide`, sampling the `Random` service for jitter. It is the engine-facing decision function.
+
+## Sleep
+
+### `Sleep.SleepRequestInvalid`
+
+- **Type:** `Schema.TaggedError` with fields `code: "missing_deadline" | "ambiguous_deadline" | "invalid_deadline"` and `message: string`
+- **Since:** `0.1.0`
+
+A sleep whose payload does not name exactly one deadline. `missing_deadline` names neither `millis` nor `until`. `ambiguous_deadline` names both. `invalid_deadline` names a number that is not a length of time: a non-finite or negative `millis`, a non-finite `until`, or an addition that overflows.
+
+### `Sleep.tag`
+
+- **Type:** `"system/sleep"`
+- **Since:** `0.1.0`
+
+The tag the sleep declaration is catalogued and resolved under.
+
+### `Sleep.action`
+
+- **Type:** `Action.Declared<typeof tag, Schema.Struct<{ readonly millis: Schema.optional<Schema.Number>; readonly until: Schema.optional<Schema.Number> }>, typeof Schema.Void, typeof SleepRequestInvalid, never>`
+- **Since:** `0.1.0`
+
+The declared `system/sleep` step: a relative `millis` from now, or an absolute `until` in epoch milliseconds. Each call is its own keyed node with its own identity, so two waits of the same length are two waits. A deadline that has already passed settles the node instead of parking it.
+
+### `Sleep.layer`
+
+- **Type:** `Layer.Layer<never, never, Crypto.Crypto | FlowRuntime>`
+- **Since:** `0.1.0`
+
+The sleep implementation: arm the durable clock, park under `timer`, wake. Provide it beside the other action implementation layers, over `Action.layerImplementations`.
+
+## Stall
+
+`Stall` is the stall breaker round loops share. `@smthrs/patterns` loops and the coding correction flow use it.
+
+### `Stall.policy`
+
+- **Signature:** `policy(options: Options): Policy`
+- **Since:** `1.0.0`
+
+Resolves `rounds` (at least two) and `on`: `stop` (the default), `park`, or `escalate`. The loop decides what `on` means.
+
+### `Stall.observe`
+
+- **Since:** `1.0.0`
+
+`Stall.observe(policy, state, observation)` folds one round into the carried `State`. It returns the next state, with a `Stalled` verdict once one signal held for `rounds` rounds in a row. An observation reports any of `tree` (a tree fingerprint), `checks` (failing check ids, order ignored, empty not compared), and `output` (compared by the SHA-256 of its canonical JSON; a value with no canonical form is not compared).
+
+### `Stall.initial`
+
+- **Type:** `State`
+- **Since:** `1.0.0`
+
+The state before the first round. `State`, `Policy`, and `Stalled` are schemas, so a trampoline carries the state in its payload and replay reads the same verdict.
+
+## StepIdentity
+
+`StepIdentity` is the module `Action` also re-exports, so `StepIdentity.DispatchSite` and `Action.DispatchSite` are one symbol.
+
+### `StepIdentity.DispatchSite`
+
+- **Type:** `Context.Service<DispatchSite, string>` keyed `"@smthrs/flow/Action/DispatchSite"`
+- **Since:** `0.1.0`
+
+The interpreter graph site the running dispatch is scoped to.
+
+### `StepIdentity.DispatchOutcome`
+
+- **Type:** `interface DispatchOutcome { readonly outcome: "executed" | "replayed"; readonly stepKeyDigest?: string | undefined; readonly attempt?: number | undefined }`
+- **Since:** `1.0.0`
+
+What one dispatch tells the node that drove it: whether the body ran, the step key digest it ran under, and the durable attempt it was.
+
+### `StepIdentity.DispatchReport`
+
+- **Type:** `Context.Service<DispatchReport, { readonly dispatched: (dispatch: DispatchOutcome) => Effect.Effect<void> }>` keyed `"@smthrs/flow/Action/DispatchReport"`
+- **Since:** `1.0.0`
+
+Where the dispatches of one interpreter node report what happened to them.
+
+### `StepIdentity.reportDispatch`
+
+- **Signature:** `reportDispatch(dispatch: DispatchOutcome): Effect.Effect<void>`
+- **Since:** `1.0.0`
+
+Reports one dispatch to the node that drove it, and does nothing where no node did.
+
+### `StepIdentity.AllocationIdentity`
+
+- **Type:** `interface AllocationIdentity { readonly kind: "action" | "internal"; readonly name: string; readonly idempotency?: string | Schema.JsonObject | undefined; readonly site?: string | undefined }`
+- **Since:** `0.1.0`
+
+The declaration material an allocation scope is derived from. `kind` is `"action"` for user-declared dispatches and `"internal"` for engine-owned durable operations, and the two own disjoint counter namespaces. `name` is the stable declaration identity, never a diagnostic name. `idempotency` refines the scope so two concurrent invocations of one name with distinguishable inputs own separate counters. `site` is the replay-stable address of the graph node driving the dispatch, and is absent for handler-driven dispatches.
+
+### `StepIdentity.allocationScope`
+
+- **Signature:** `allocationScope(identity: AllocationIdentity): Effect.Effect<string, Schema.SchemaError, Crypto.Crypto>`
+- **Since:** `0.1.0`
+
+Derives the ordinal allocation scope of a durable operation.
+
+### `StepIdentity.invocationKey`
+
+- **Signature:** `invocationKey(input: { readonly runId: string; readonly parentScope?: string | undefined; readonly ordinal: number; readonly tier: "unsealed" | "compensable" | "irreversible" }): Effect.Effect<StoredKey, Schema.SchemaError, Crypto.Crypto>`
+- **Since:** `0.1.0`
+
+Derives an invocation key from engine-generated input.
+
+## WaitFor
+
+### `WaitFor.WaitForRequestInvalid`
+
+- **Type:** `Schema.TaggedError` with fields `code: "missing_target" | "ambiguous_target" | "malformed_token" | "foreign_execution"` and `message: string`
+- **Since:** `0.1.0`
+
+A wait whose payload does not name exactly one reachable wait point. `missing_target` and `ambiguous_target` cover a payload naming neither or both. `malformed_token` covers a token that does not parse. `foreign_execution` covers a token addressed to another flow or another execution.
+
+### `WaitFor.tag`
+
+- **Type:** `"system/wait-for"`
+- **Since:** `0.1.0`
+
+The tag the wait declaration is catalogued and resolved under.
+
+### `WaitFor.deferred`
+
+- **Signature:** `deferred(name: string): DurableDeferred.DurableDeferred<typeof Schema.Json>`
+- **Since:** `0.1.0`
+
+The durable deferred a named wait point resolves through, named `WaitFor/<name>`. It is the resolver's half of `WaitFor.action`: the value to hand `DurableDeferred.tokenFromExecutionId` and `DurableDeferred.succeed`.
+
+### `WaitFor.action`
+
+- **Type:** `Action.Declared<typeof tag, Schema.Struct<{ readonly token: Schema.optional<Schema.String>; readonly name: Schema.optional<Schema.String> }>, typeof Schema.Json, typeof WaitForRequestInvalid, never>`
+- **Since:** `0.1.0`
+
+The declared `system/wait-for` step: a rendezvous with something outside the run, named by `name` relative to the running execution, or by an absolute `token`.
+
+### `WaitFor.layer`
+
+- **Type:** `Layer.Layer<never, never, Crypto.Crypto | FlowRuntime>`
+- **Since:** `0.1.0`
+
+The wait implementation: park under `event` with the wake token, and settle with the value that resolved the wait. Provide it beside the other action implementation layers, over `Action.layerImplementations`.
+
+## Errors
+
+Every failure the package defines is a `Schema.TaggedError` carrying a stable `code`:
+
+| Tag                                                    | Raised when                                                                                                          | Fields                                                                    |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `@smthrs/flow/InfraInterrupt`                          | An action adapter explicitly marks an infrastructure event for `interruptRetryPolicy`; engines do not synthesize it. | `code`, `reason`                                                          |
+| `@smthrs/flow/InfraInterruptRetriesExhausted`          | An action spends its `interruptRetryPolicy` without reaching an ordinary success or failure.                         | `code`, `actionName`, `attempts`, `interrupt`, `message`                  |
+| `@smthrs/flow/IrreversibleRetryRequiresIdempotencyKey` | An irreversible action attempts a retry without a declared idempotency key.                                          | `code`, `actionName`, `attempt`                                           |
+| `@smthrs/flow/ConcurrentKeylessDispatch`               | Two ordinal-keyed invocations of one allocation scope are in flight at once.                                         | `code`, `actionName`                                                      |
+| `@smthrs/flow/UncanonicalIdempotencyKey`               | A caller-declared object-form `idempotencyKey` carries material canonical serialization rejects.                     | `code`, `actionName`, `reason`, `path`, `message`                         |
+| `@smthrs/flow/DurableDeferred/TokenInvalid`            | A completion token does not parse, or names a different deferred than the surface it was submitted through.          | `code`, `message`                                                         |
+| `@smthrs/flow/ExecutionIdRequired`                     | Opt-in derivation could not canonicalize the payload, or a served resume was not scoped to an id.                    | `code`, `flowName`                                                        |
+| `@smthrs/flow/MaxRoundsExceeded`                       | A trampoline lineage opens a round past its flow's `maxRounds` budget.                                               | `code`, `flowName`, `lineageId`, `maxRounds`, `roundOrdinal`, `message`   |
+| `@smthrs/flow/DeadlineExceeded`                        | An execution is still unsettled when its flow's `deadline` elapses.                                                  | `code`, `flowName`, `executionId`, `deadlineMs`, `startedAtMs`, `message` |
+| `@smthrs/flow/CancelRequestFailed`                     | `interrupt` cannot durably record its cancellation request, or a durable engine is asked for `interruptUnsafe`.      | `code`, `executionId`, `reason`                                           |
+| `@smthrs/flow/FlowCycleDetected`                       | Executing a flow would close a cycle in the persisted parent-execution chain.                                        | `code`, `path`                                                            |
+| `@smthrs/flow/FlowExecutionNotFound`                   | `poll` names an execution id the runtime never recorded.                                                             | `code`, `executionId`                                                     |
+| `@smthrs/flow/HumanTaskFailed`                         | A question is unanswerable, spends its attempt budget on refused answers, or passes its deadline while open.         | `code`, `task`, `attempts`, `rejections`, `message`                       |
+| `@smthrs/flow/HumanAnswerInvalid`                      | An answer is outside the durable JSON boundary, or the attempt it addresses is not open.                             | `code`, `message`                                                         |
+| `@smthrs/flow/InterpreterError`                        | The interpreter refuses a graph it cannot drive.                                                                     | `code`, `flow`, `node`, `message`                                         |
+| `@smthrs/flow/PollExhausted`                           | A poll uses its last attempt without a satisfied check, under `onTimeout: "fail"`.                                   | `code`, `poll`, `attempts`, `message`                                     |
+| `@smthrs/flow/RetryPolicyExpired`                      | A historical retry sequence crossed the policy's `expirationMs` wall-clock bound.                                    | `code`, `actionName`, `attempt`, `expirationMs`, `lastError`              |
+| `@smthrs/flow/RetryAttemptsExhausted`                  | A historical retry sequence exhausted the policy's `maxAttempts` bound.                                              | `code`, `actionName`, `attempt`, `maxAttempts`, `lastError`               |
+| `@smthrs/flow/SleepRequestInvalid`                     | A sleep payload names no deadline, two deadlines, or a value that is not a length of time.                           | `code`, `message`                                                         |
+| `@smthrs/flow/WaitForRequestInvalid`                   | A wait payload names no target, two targets, a token that does not parse, or a token addressed to another execution. | `code`, `message`                                                         |
+
+`Flow.make`, `Poll.make`, `RetryPolicy.make`, and `DurableQueue.makeWorker` refuse invalid static configuration by throwing a `RangeError` at construction, and `Poll.make` throws a `TypeError` for an `input` that declares the reserved `attempt` field. Those are programmer errors, not typed failures.
+
+## Example
+
+An action carries an implementation attached as a layer, a flow carries a pure body, and `Interpreter.layer` makes the flow executable:
+
+```ts
+import { Action, Flow, Interpreter } from "@smthrs/flow"
+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 },
+  success: Schema.String,
+  tier: "sealed"
+})
+
+const Deploy = Flow.make("deploy/watch", {
+  payload: { id: Schema.String },
+  success: Schema.String,
+  idempotencyKey: ({ id }) => id,
+  body: (payload) => Status.call(payload)
+})
+
+// `layerImplementations` goes UNDER the implementation layers, because an
+// implementation files itself in the table while its layer is built.
+export const layer = Layer.mergeAll(
+  Status.toLayer(({ id }) => Effect.succeed(`${id} is live`)),
+  Interpreter.layer(Deploy)
+).pipe(Layer.provideMerge(Action.layerImplementations))
+```
+
+Provide a runtime that implements `FlowRuntime`, then run `Deploy.execute({ id: "greeting-ada-1" }, { executionId: "deploy-greeting-ada-1" })`.
+
+## See also
+
+- [`@smthrs/engine`](/api/engine), which implements the `FlowRuntime` port
+- [`@smthrs/engine-store`](/api/engine-store), which makes that implementation durable
+- [`@smthrs/plan`](/api/plan), whose `Node` and `FileSet` vocabulary a body is written in
+- [`@smthrs/crypto`](/api/crypto) and [`@smthrs/keys`](/api/keys), the digest and key derivations identity is built from
+- [Durable execution](/docs/concepts/durable-execution/), for why a journaled side effect resumes
+- [Flows, actions, and plans](/docs/concepts/flows-actions-plans/), for the division between a body and an implementation
+- [Retries](/docs/concepts/retries/), for how a policy value becomes a durable decision