@smthrs/flow 1.0.0-rc.7 → 1.0.0-rc.9

package/docs/api.md

@@ -44,7 +44,7 @@ The [export reference](./reference/flow.md) lists every exported symbol with its
 
 ## `Flow`
 
-`Flow.make(tag, options)` accepts struct payload fields, success and error schemas, an optional `idempotencyKey`, annotations, a `suspendedRetryPolicy`, a `maxRounds` bound for trampoline lineages, and a `deadline` for one execution. Four literals lower into the annotation bag rather than staying options: `description`, `capabilities`, `effects`, the effect envelope from [`@smthrs/plan`](/api/plan#effects), and `modelInvocable`, which says whether a catalog may offer this flow to a model and defaults to `true`. They are literals so a catalog can project a discovered flow's authority from source text without importing the module, and `Graph.build` refuses a composition beneath the flow that reads or writes outside that envelope, loosens its mode, or raises its tier. Declare exactly one of `body` or `prompt`. A prompt declaration lowers to one ordinary action, exposed as `flow.action`; its host supplies the implementation through `flow.action.toLayer`. The typed `flow.prompt` renderer runs inside that implementation, never during planning. Optional `model`, `effort`, `flows`, `system`, and `chat` fields retain host metadata. See [Prompt-backed flows](./guides/use-a-prompt.md). `maxRounds` must be a positive safe integer and `deadline` a positive finite duration; `Flow.make` throws a `RangeError` when either is not. The deadline counts from the execution's journaled first start, so a resume after a restart honors the original deadline, and expiry settles the execution with the `DeadlineExceeded` defect whether it was running or parked. A trampoline lineage is one run: every round after a handoff expires at the originator's start plus the originator's deadline, whatever the round itself declares.
+`Flow.make(tag, options)` accepts struct payload fields, success and error schemas, an optional `idempotencyKey`, annotations, a `suspendedRetryPolicy`, a `maxRounds` bound for trampoline lineages, and a `deadline` for one execution. Four literals lower into the annotation bag rather than staying options: `description`, `capabilities`, `effects`, the effect envelope from [`@smthrs/plan`](/api/plan#effects), and `modelInvocable`, which says whether a catalog may offer this flow to a model and defaults to `true`. They are literals so a catalog can project a discovered flow's authority from source text without importing the module, and `Graph.build` refuses a composition beneath the flow that reads or writes outside that envelope, loosens its mode, or raises its tier. Declare exactly one of `body` or `prompt`. A prompt declaration lowers to one ordinary action, exposed as `flow.action`; its host supplies the implementation through `flow.action.toLayer`. The typed `flow.prompt` renderer runs inside that implementation, never during planning. Optional `model`, `effort`, `flows`, `system`, and `chat` fields retain host metadata. See [Prompt-backed flows](./guides/use-a-prompt.md). `maxRounds` must be a positive safe integer and `deadline` a positive finite duration of at most `Number.MAX_SAFE_INTEGER` milliseconds; `Flow.make` throws a `RangeError` when either is not. The deadline counts from the execution's journaled first start, so a resume after a restart honors the original deadline, and expiry settles the execution with the `DeadlineExceeded` defect whether it was running or parked. A trampoline lineage is one run: every round after a handoff expires at the originator's start plus the originator's deadline, whatever the round itself declares.
 
 The returned definition exposes:
 
@@ -157,6 +157,8 @@ Sealed idempotency identity has two forms. A string is namespaced by the action
 | `DurableQueue`    | `make`, `process`, `makeWorker`, and `worker` over Effect's `PersistedQueue`                                                  |
 | `Deadline`        | `start`, `within`, and `bound`: the run deadline `Flow.make` applies, for a host that bounds a run by an approved deadline    |
 
+`DurableClock.make` and `DurableClock.sleep` throw a `RangeError` for a malformed, infinite, or negative duration, or one longer than `Number.MAX_SAFE_INTEGER` milliseconds: a durable store records a clock's due time as a safe integer. A durable sleep that would wake after epoch millisecond `Number.MAX_SAFE_INTEGER` dies with a `RangeError` instead of arming its clock.
+
 A deferred token encodes the flow name, the execution id, and the deferred name, so another process can complete the correct durable address. `TokenInvalid` is 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. Completing a deferred is first-writer-wins: the first recorded exit is the one every later read replays.
 
 `DurableQueue.process` offers a payload, attaches a token, and suspends until a worker records the handler's exit against it. Its `retrySchedule` option bounds how a failing offer is retried; the default retries with exponential backoff, capped at one minute, and never gives up before the call dies. `DurableQueue.worker` and `makeWorker` take a `concurrency` that must be a positive safe integer.
@@ -219,11 +221,11 @@ Sleep.action.call({ millis: 60_000 })
 
 A payload names exactly one deadline: a relative `millis`, or an absolute `until` in epoch milliseconds. `SleepRequestInvalid` is the typed refusal, with three codes:
 
-| Code                 | Meaning                                                                                                                                |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `missing_deadline`   | the payload named neither `millis` nor `until`                                                                                         |
-| `ambiguous_deadline` | it named both, which are the same fact stated two ways                                                                                 |
-| `invalid_deadline`   | it named a number that is not a length of time: a non-finite or negative `millis`, a non-finite `until`, or an addition that overflows |
+| Code                 | Meaning                                                                                                                                                                                              |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `missing_deadline`   | the payload named neither `millis` nor `until`                                                                                                                                                       |
+| `ambiguous_deadline` | it named both, which are the same fact stated two ways                                                                                                                                               |
+| `invalid_deadline`   | it named a number that is not a length of time: a non-finite or negative `millis`, a non-finite `until`, an addition that overflows, or a deadline after epoch millisecond `Number.MAX_SAFE_INTEGER` |
 
 Two waits of the same length are two waits: each call is its own node with its own identity, so `sleep` followed by `sleep` waits twice. A deadline that has already passed settles the node instead of parking it, because a run that resumes after its own deadline has to make progress.
 
@@ -254,7 +256,7 @@ yield * DurableDeferred.succeed(gate, { token, value: { approved: true } })
 
 `delayMillis` is the exported schedule function, `CheckResult(result)` is the success schema a check action declares, `Failure` is the union a poll's rounds can fail with, and `Poll.layer` implements the `system/poll-exhausted` step. `PollExhausted` carries the stable code `poll_exhausted`.
 
-`Poll.make` refuses a schedule no clock can keep, with a `RangeError` naming the option that is wrong: an `intervalMs` that is not finite or is negative becomes a `system/sleep` node whose timer never fires, and a `maxAttempts` below one whole attempt reaches `Flow.make` as a complaint about `maxRounds`, an option the author never wrote. The check is on the schedule rather than on the interval alone, because `delayMillis` multiplies the interval by the backoff: `{ intervalMs: 1000, maxAttempts: 2000, backoff: "exponential" }` states three finite options and still asks for a wait of `Infinity`. The last wait a poll can arm, the one before the final attempt, has to be a length too, since the attempt at the budget gives up rather than sleeps.
+`Poll.make` refuses a schedule no clock can keep, with a `RangeError` naming the option that is wrong: an `intervalMs` that is not finite or is negative becomes a `system/sleep` node whose timer never fires, and a `maxAttempts` below one whole attempt reaches `Flow.make` as a complaint about `maxRounds`, an option the author never wrote. The check is on the schedule rather than on the interval alone, because `delayMillis` multiplies the interval by the backoff: `{ intervalMs: 1000, maxAttempts: 2000, backoff: "exponential" }` states three finite options and still asks for a wait of `Infinity`. The last wait a poll can arm, the one before the final attempt, has to be a length too, since the attempt at the budget gives up rather than sleeps, and no longer than `Number.MAX_SAFE_INTEGER` milliseconds, the latest deadline a durable timer records.
 
 ### Bounding a check that can hang
 
@@ -327,15 +329,15 @@ A failed agent run, and a launch the executor refused, journal the fault on `con
 
 `HumanTask.action` is the declared `system/human-task` step: a typed question with re-asking and a deadline, built on `WaitFor`'s wait points and `DurableClock`.
 
-| Payload field | Meaning                                                                                                      |
-| ------------- | ------------------------------------------------------------------------------------------------------------ |
-| `name`        | addresses the question. Two calls naming one question in one execution await one answer                      |
-| `kind`        | `ask` (prose), `confirm` (a boolean), `select` (one of `options`), `json` (a value `schema` accepts)         |
-| `prompt`      | what the person is asked                                                                                     |
-| `options`     | the choices a `select` offers                                                                                |
-| `schema`      | a JSON Schema in the bounded subset, valid only with `kind: "json"`                                          |
-| `maxAttempts` | how many answers may be refused before the task fails. Defaults to `defaultMaxAttempts` (10)                 |
-| `timeoutMs`   | how long the question stays open, across every attempt. A finite number of milliseconds that is not negative |
+| Payload field | Meaning                                                                                                              |
+| ------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `name`        | addresses the question. Two calls naming one question in one execution await one answer                              |
+| `kind`        | `ask` (prose), `confirm` (a boolean), `select` (one of `options`), `json` (a value `schema` accepts)                 |
+| `prompt`      | what the person is asked                                                                                             |
+| `options`     | the choices a `select` offers                                                                                        |
+| `schema`      | a JSON Schema in the bounded subset, valid only with `kind: "json"`                                                  |
+| `maxAttempts` | how many answers may be refused before the task fails. Defaults to `defaultMaxAttempts` (10)                         |
+| `timeoutMs`   | how long the question stays open, across every attempt. A number of milliseconds from 0 to `Number.MAX_SAFE_INTEGER` |
 
 The bounded schema subset is `type` (`object`, `array`, `string`, `number`, `integer`, `boolean`, `null`), `enum`, `properties`, `required`, `items`, `nullable`, `description`, and `title`. `enum` members may be any JSON value, including objects and arrays, and membership is compared structurally rather than by reference. A schema supplied with any kind other than `json` is refused as `request_invalid`, because nothing would check it.
 
@@ -347,7 +349,7 @@ declared `options` or `schema`. It describes the question without including an
 answer. Durable readers use it to render pending questions, including waits
 inside child executions; routing still uses the wait token.
 
-`HumanTaskFailed` carries `code`, `task`, `attempts`, the `rejections` it collected, and a message. `request_invalid` refuses an unanswerable question before anyone is asked: a `select` with no options, an attempt budget below one or above the documented ceiling, a `timeoutMs` that is not a length of time, a schema outside the subset, a schema past the depth or node bound, or a schema supplied with the wrong kind. `rejected` means the budget was spent on answers the task refused. `timeout` means the deadline passed with the question open.
+`HumanTaskFailed` carries `code`, `task`, `attempts`, the `rejections` it collected, and a message. `request_invalid` refuses an unanswerable question before anyone is asked: a `select` with no options, an attempt budget below one or above the documented ceiling, a `timeoutMs` that is not a length of time or is above `Number.MAX_SAFE_INTEGER`, a schema outside the subset, a schema past the depth or node bound, or a schema supplied with the wrong kind. `rejected` means the budget was spent on answers the task refused. `timeout` means the deadline passed with the question open.
 
 Sizes are bounded so one question cannot grow a durable record without limit. The attempt budget is refused above `maxAttemptBudget`, the schema is refused past `maxSchemaDepth` levels or `maxSchemaNodes` nodes, an answer is refused past `maxAnswerNodes` visited values, a value echoed into a rejection message is truncated at `maxDiagnosticChars` with an explicit marker, and the retained `rejections` array stops at `maxRetainedRejectionChars` and records how many further rejections it omitted. The per-attempt journal step still records its own full reason: only the accumulated array is capped, because a refused answer stays recorded so the record shows what was actually said.
 
@@ -365,6 +367,8 @@ A `RetryPolicy` is a plain value, so the next retry delay is derived from a pers
 
 `decide` classifies non-retryable errors here and nowhere else, by the policy's declared tags and by `defaultNonRetryable`, which lists the integrity verdicts that must reach the driver unretried under every policy. Exhaustion and expiration preserve the final declared failure. The older `RetryPolicyExpired` and `RetryAttemptsExhausted` schemas remain available for interpreting historical outcomes.
 
+The package's [`examples/retry-and-stall.ts`](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/examples/retry-and-stall.ts) runs `RetryPolicy.decide` over five failed attempts and `Stall.observe` over a repair loop's rounds, with no runtime. Run it with `node examples/retry-and-stall.ts` from the package directory.
+
 ## `StepIdentity`
 
 | Export               | Purpose                                                |

package/docs/guides/ask-a-person.md

@@ -139,11 +139,11 @@ so a restart between the park and the answer resumes on the same token.
 `HumanTask.HumanTaskFailed` carries `code`, `task`, `attempts`, the `rejections`
 it collected, and a message:
 
-| Code              | Meaning                                                                                                                                                                                                                                                           |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request_invalid` | The question was unanswerable before anyone was asked: a `select` with no options, an attempt budget below one or above `HumanTask.maxAttemptBudget`, a `timeoutMs` that is not a length of time, or a schema outside the subset or past its depth or node bound. |
-| `rejected`        | The attempt budget was spent on answers the task refused.                                                                                                                                                                                                         |
-| `timeout`         | The deadline passed with the question still open.                                                                                                                                                                                                                 |
+| Code              | Meaning                                                                                                                                                                                                                                                                                                 |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request_invalid` | The question was unanswerable before anyone was asked: a `select` with no options, an attempt budget below one or above `HumanTask.maxAttemptBudget`, a `timeoutMs` that is not a length of time or is above `Number.MAX_SAFE_INTEGER`, or a schema outside the subset or past its depth or node bound. |
+| `rejected`        | The attempt budget was spent on answers the task refused.                                                                                                                                                                                                                                               |
+| `timeout`         | The deadline passed with the question still open.                                                                                                                                                                                                                                                       |
 
 `HumanTask.HumanAnswerInvalid` is the separate refusal an answer earns before it
 can consume durable storage, with `answer_invalid` for an answer outside the

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

@@ -19,7 +19,7 @@ engine, database, or jj: planning reads declarations only. They import
 add both at the version of `@smthrs/flows` you have:
 
 ```bash
-npm install @smthrs/flow@1.0.0-rc.7 @smthrs/plan@1.0.0-rc.7
+npm install @smthrs/flow@1.0.0-rc.9 @smthrs/plan@1.0.0-rc.9
 ```
 
 `@smthrs/flows` re-exports the same modules, so `import { Graph } from "@smthrs/flows"`

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

@@ -107,7 +107,9 @@ because the backoff multiplies the interval:
 `{ intervalMs: 1000, maxAttempts: 2000, backoff: "exponential" }` states three
 finite options and still asks for a wait of `Infinity`. The check looks at the
 last wait a poll can arm, the one before the final attempt, since the attempt at
-the budget gives up rather than sleeps.
+the budget gives up rather than sleeps. That wait must also be at most
+`Number.MAX_SAFE_INTEGER` milliseconds, the latest deadline a durable timer
+records, so a one-millisecond interval doubling allows at most 54 attempts.
 
 ## Handle exhaustion
 

package/docs/guides/wait-for-a-deadline.md

@@ -62,11 +62,11 @@ milliseconds, and exactly one of them. `Sleep.SleepRequestInvalid` is the typed
 refusal, so a body can recover from it with `Node.catch` like any other declared
 failure:
 
-| Code                 | What was wrong                                                                                                                          |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `missing_deadline`   | The payload named neither `millis` nor `until`.                                                                                         |
-| `ambiguous_deadline` | It named both, which are the same fact stated twice.                                                                                    |
-| `invalid_deadline`   | It named a number that is not a length of time: a non-finite or negative `millis`, a non-finite `until`, or an addition that overflows. |
+| Code                 | What was wrong                                                                                                                                                                                        |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `missing_deadline`   | The payload named neither `millis` nor `until`.                                                                                                                                                       |
+| `ambiguous_deadline` | It named both, which are the same fact stated twice.                                                                                                                                                  |
+| `invalid_deadline`   | It named a number that is not a length of time: a non-finite or negative `millis`, a non-finite `until`, an addition that overflows, or a deadline after epoch millisecond `Number.MAX_SAFE_INTEGER`. |
 
 Two behaviors are worth knowing before you write the body:
 

package/docs/installation.md

@@ -1,13 +1,17 @@
 ---
 title: "Installation"
-description: "Install @smthrs/flow, its runtime requirements and effect range, its import forms, and the packages a runnable composition adds."
+description: "Install @smthrs/flow from npm, its runtime requirements and effect range, its import forms, and the packages a runnable composition adds."
 sidebar:
   order: 1
 ---
 
 ## Install the package
 
-`@smthrs/flow` is not on npm yet. Link the source packages as described in [Use the libraries](#use-the-libraries).
+```bash
+npm install @smthrs/flow@next effect
+```
+
+The `next` tag carries the 1.0 release candidates.
 
 `effect` is a peer dependency of this package, in the range `^4.0.4`. Add one
 `effect` in that range to your own dependencies: your declarations import
@@ -23,17 +27,18 @@ from, and the canonical JSON checks applied to values.
 
 ## Use the libraries
 
-First [install the source checkout](https://github.com/smithersai/smithers/blob/main/packages/smithers/docs/installation.md#install-the-cli). The checkout's `examples` workspace carries the packages used by the flow tutorials and their pinned `effect@4.0.4`.
-
-Create a project beside the checkout:
+Every `@smthrs` library installs from npm the same way. Name each package your
+code imports with the `next` tag, and add one `effect` in the `^4.0.4` range
+the libraries peer. The [Quickstart](./quickstart.md) program needs these:
 
 ```bash
-mkdir my-flows && cd my-flows
-echo '{ "type": "module" }' > package.json
-ln -s /path/to/smithers/examples/node_modules node_modules
+npm install @smthrs/flow@next @smthrs/engine@next @smthrs/plan@next @effect/platform-node effect
 ```
 
-Replace `/path/to/smithers` with the absolute path to your installed checkout. Run programs with `node <file>.ts`. Packages absent from the examples workspace, such as `@smthrs/artifacts`, resolve only inside the checkout; use the owning package's workspace for those examples. This linking recipe uses source exports and requires no package build.
+`next` resolves every `@smthrs` package to the same release candidate. With
+pnpm 11, name that version instead of the tag; the
+[Flows installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/docs/installation.md)
+explains why.
 
 ## Import forms
 

package/docs/quickstart.md

@@ -15,7 +15,11 @@ A runnable copy of this program is published in the Smithers examples,
 ## Prerequisites
 
 - Node.js 26.4.0 or later.
-- A package with the dependencies installed. Not on npm yet; see [Installation](./installation.md#use-the-libraries).
+- A project with the packages installed:
+
+  ```bash
+  npm install @smthrs/flow@next @smthrs/engine@next @smthrs/plan@next @effect/platform-node effect
+  ```
 
 ## Declare the action and the flow
 

package/docs/reference/flow.md

@@ -5,7 +5,11 @@ area: api
 order: 10
 ---
 
-Install the package with its `effect` peer. Not on npm yet; see [Installation](../installation.md#use-the-libraries).
+Install the package with its `effect` peer:
+
+```bash
+npm install @smthrs/flow@next effect
+```
 
 ## Entry points
 
@@ -325,7 +329,7 @@ A directory output captured and replayed as one tree artifact.
 - **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. Start at most one deadline per execution.
+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`
 
@@ -362,7 +366,7 @@ A durable flow timer: a name, a duration, and the deferred that is completed whe
 - **Signature:** `make(options: { readonly name: string; readonly duration: Duration.Input }): DurableClock`
 - **Since:** `0.1.0`
 
-Declares one durable clock. The duration must be finite and not negative.
+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`
 
@@ -370,7 +374,7 @@ Declares one durable clock. The duration must be finite and not negative.
 - **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.
+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
 
@@ -736,7 +740,7 @@ Declares the host's execution-id source as a layer. Callers that name an `execut
 - **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. `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.
+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`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smthrs/flow",
   "type": "module",
-  "version": "1.0.0-rc.7",
+  "version": "1.0.0-rc.9",
   "license": "MIT",
   "smthrs": {
     "group": "engine"
@@ -289,11 +289,11 @@
     "tag": "next"
   },
   "dependencies": {
-    "@smthrs/crypto": "1.0.0-rc.7",
-    "@smthrs/keys": "1.0.0-rc.7",
-    "@smthrs/plan": "1.0.0-rc.7",
-    "@smthrs/canonical": "1.0.0-rc.7",
-    "@smthrs/capability": "1.0.0-rc.7"
+    "@smthrs/crypto": "1.0.0-rc.9",
+    "@smthrs/keys": "1.0.0-rc.9",
+    "@smthrs/plan": "1.0.0-rc.9",
+    "@smthrs/canonical": "1.0.0-rc.9",
+    "@smthrs/capability": "1.0.0-rc.9"
   },
   "devDependencies": {
     "@effect/language-service": "0.87.2",
@@ -319,7 +319,7 @@
     "effect": "^4.0.4"
   },
   "scripts": {
-    "lint": "eslint src --max-warnings=0 && dprint check",
+    "lint": "eslint src examples --max-warnings=0 && dprint check",
     "format": "dprint fmt",
     "build": "node scripts/build.mjs",
     "check": "tsc -b tsconfig.json && tsc -p tsconfig.test.json --noEmit",

package/src/Deadline.ts

@@ -66,6 +66,11 @@ const origin = Action.make({
  * replay must line up with: the origin and the clock are addressed by fixed
  * names within the execution.
  *
+ * A deadline that is not a positive finite duration, a `startedAtMs` that is
+ * not finite, or a bound that would expire after epoch millisecond
+ * `Number.MAX_SAFE_INTEGER` dies with a `RangeError`: a durable store records
+ * the clock's due time as a safe integer.
+ *
  * @category constructors
  * @since 1.0.0
  */
@@ -95,7 +100,18 @@ export const start = (options: {
           new RangeError(`Deadline.start: "${options.flowName}" deadline must be a positive finite duration`)
         )
       }
-      lineage = { startedAtMs: options.startedAtMs ?? (yield* origin), deadlineMs }
+      const startedAtMs = options.startedAtMs ?? (yield* origin)
+      // The clock armed below is due at `startedAtMs + deadlineMs`, and a
+      // durable store records a due time as a safe integer.
+      if (!Number.isFinite(startedAtMs) || startedAtMs + deadlineMs > Number.MAX_SAFE_INTEGER) {
+        return yield* Effect.die(
+          new RangeError(
+            `Deadline.start: "${options.flowName}" deadline must expire by epoch millisecond ` +
+              `${Number.MAX_SAFE_INTEGER}, and a ${deadlineMs} ms deadline from ${startedAtMs} does not`
+          )
+        )
+      }
+      lineage = { startedAtMs, deadlineMs }
     }
     const remaining = yield* remainingMs(lineage)
     if (remaining > 0) {

package/src/DurableClock.ts

@@ -11,6 +11,7 @@
  * @since 0.1.0
  */
 
+import * as Clock from "effect/Clock"
 import type * as Crypto from "effect/Crypto"
 import * as Duration from "effect/Duration"
 import * as Effect from "effect/Effect"
@@ -56,6 +57,28 @@ const durationFromInput = (input: Duration.Input, field: string): Duration.Durat
   return parsed.value
 }
 
+/**
+ * The latest due time a durable timer records, in epoch milliseconds: a store
+ * keeps a clock's due time as a safe integer.
+ *
+ * @private
+ */
+const latestDueAtMs = Number.MAX_SAFE_INTEGER
+
+/**
+ * Parses a clock's own duration, which a store adds to the current time and
+ * records, so it is at most {@link latestDueAtMs} milliseconds.
+ *
+ * @private
+ */
+const clockDuration = (input: Duration.Input): Duration.Duration => {
+  const duration = durationFromInput(input, "duration")
+  if (Duration.toMillis(duration) > latestDueAtMs) {
+    throw new RangeError(`DurableClock: "duration" must be at most ${latestDueAtMs} milliseconds.`)
+  }
+  return duration
+}
+
 const makeClock = (name: string, duration: Duration.Duration): DurableClock => ({
   [TypeId]: TypeId,
   name,
@@ -66,18 +89,27 @@ const makeClock = (name: string, duration: Duration.Duration): DurableClock => (
 /**
  * Declares one durable clock after validating its finite nonnegative duration.
  *
+ * Throws a `RangeError` for a malformed, infinite or negative duration, or one
+ * longer than `Number.MAX_SAFE_INTEGER` milliseconds: a durable store records
+ * a clock's due time as a safe integer.
+ *
  * @category constructors
  * @since 0.1.0
  */
 export const make = (options: {
   readonly name: string
   readonly duration: Duration.Input
-}): DurableClock => makeClock(options.name, durationFromInput(options.duration, "duration"))
+}): DurableClock => makeClock(options.name, clockDuration(options.duration))
 
 /**
  * Waits inside a flow, using an in-memory action for durations at or
  * below the threshold and scheduling a durable clock for longer durations.
  *
+ * Throws a `RangeError` for the same durations {@link make} refuses, and for
+ * 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.
+ *
  * @category sleeping
  * @since 0.1.0
  */
@@ -99,7 +131,7 @@ export const sleep = (
   Crypto.Crypto | FlowRuntime | FlowInstance
 > => {
   const name = options.name
-  const duration = durationFromInput(options.duration, "duration")
+  const duration = clockDuration(options.duration)
   const inMemoryThreshold = durationFromInput(
     options.inMemoryThreshold ?? defaultInMemoryThreshold,
     "inMemoryThreshold"
@@ -119,6 +151,17 @@ export const sleep = (
       })
     }
 
+    // A due time past the latest one a store records would fail the park
+    // write deep in the engine, so the sleep refuses it here by name.
+    const now = yield* Clock.currentTimeMillis
+    if (now + Duration.toMillis(duration) > latestDueAtMs) {
+      return yield* Effect.die(
+        new RangeError(
+          `DurableClock: "${name}" would wake after epoch millisecond ${latestDueAtMs}, ` +
+            `the latest due time a durable timer records.`
+        )
+      )
+    }
     const engine = yield* FlowRuntime
     const instance = yield* FlowInstance
     const clock = makeClock(name, duration)

package/src/Flow/make.ts

@@ -99,7 +99,8 @@ interface MakeOptions<
   readonly maxRounds?: number | undefined
   /**
    * How long one execution may take, counted from its journaled first start.
-   * A positive finite duration; see {@link Flow.deadline}.
+   * A positive finite duration of at most `Number.MAX_SAFE_INTEGER`
+   * milliseconds; see {@link Flow.deadline}.
    */
   readonly deadline?: Duration.Input | undefined
   readonly annotations?: Context.Context<never>
@@ -222,6 +223,11 @@ export const make: {
   ) {
     throw new RangeError(`Flow.make: "${tag}" deadline must be a positive finite duration`)
   }
+  // The durable clock that enforces a deadline is due at its start plus the
+  // deadline, and a store records that due time as a safe integer.
+  if (deadline !== undefined && Duration.toMillis(deadline) > Number.MAX_SAFE_INTEGER) {
+    throw new RangeError(`Flow.make: "${tag}" deadline must be at most ${Number.MAX_SAFE_INTEGER} ms`)
+  }
   // Captured here, where the stack still names the author's file, and carried
   // as a non-enumerable property so no digest can see it
   // (`internal/DeclarationSite.ts`).

package/src/HumanTask.ts

@@ -680,7 +680,9 @@ const budgetOf = (payload: Payload): Effect.Effect<number, HumanTaskFailed> => {
 const deadlineOf = (payload: Payload): Effect.Effect<Duration.Duration | undefined, HumanTaskFailed> => {
   const timeoutMs = payload.timeoutMs
   if (timeoutMs === undefined) return Effect.succeed(undefined)
-  return Number.isFinite(timeoutMs) && timeoutMs >= 0
+  // The timeout clock is due at its start plus the deadline, and a durable
+  // store records that due time as a safe integer.
+  return Number.isFinite(timeoutMs) && timeoutMs >= 0 && timeoutMs <= Number.MAX_SAFE_INTEGER
     ? Effect.succeed(Duration.millis(timeoutMs))
     : Effect.fail(
       failed(
@@ -688,8 +690,8 @@ const deadlineOf = (payload: Payload): Effect.Effect<Duration.Duration | undefin
         "request_invalid",
         0,
         [],
-        `${tag} was called with timeoutMs ${timeoutMs}. A deadline is a finite number of ` +
-          "milliseconds that is not negative; the question would be over before it was asked, or " +
+        `${tag} was called with timeoutMs ${timeoutMs}. A deadline is a number of milliseconds ` +
+          `from 0 to ${Number.MAX_SAFE_INTEGER}; the question would be over before it was asked, or ` +
           "never over at all."
       )
     )

package/src/Poll.ts

@@ -149,8 +149,10 @@ export const delayMillis = (options: {
   readonly backoff: Backoff
   readonly attempt: number
 }): number =>
-  options.intervalMs *
-  (options.backoff === "fixed" ? 1 : options.backoff === "linear" ? options.attempt : 2 ** (options.attempt - 1))
+  // A zero interval is zero under every backoff. Multiplying it by a factor
+  // that has overflowed to `Infinity` would make it `NaN`.
+  options.intervalMs === 0 ? 0 : options.intervalMs *
+    (options.backoff === "fixed" ? 1 : options.backoff === "linear" ? options.attempt : 2 ** (options.attempt - 1))
 
 /**
  * What a poll round can fail with.
@@ -274,7 +276,9 @@ const withAttempt = <Payload>(payload: object, attempt: number): Payload =>
  * with a plan that looks correct. The check is on the schedule, not only on the
  * interval: `{ intervalMs: 1000, maxAttempts: 2000, backoff: "exponential" }`
  * states three finite options and asks for an infinite wait, so the LAST wait
- * the poll can arm has to be a length too. `maxAttempts` is the lineage's round
+ * the poll can arm has to be a length too, and no longer than
+ * `Number.MAX_SAFE_INTEGER` milliseconds, the latest deadline a durable timer
+ * records. `maxAttempts` is the lineage's round
  * budget, and a budget below one attempt reaches `Flow.make` as a `maxRounds`
  * complaint about an option the author never wrote.
  *
@@ -341,7 +345,9 @@ export const make = <
   const longestWaitMs = maxAttempts > 1
     ? delayMillis({ intervalMs, backoff, attempt: maxAttempts - 1 })
     : 0
-  if (!Number.isFinite(longestWaitMs)) {
+  // A durable timer records its deadline as a safe integer of milliseconds,
+  // so `Sleep` refuses a longer wait on the round that reaches it.
+  if (!Number.isFinite(longestWaitMs) || longestWaitMs > Number.MAX_SAFE_INTEGER) {
     throw new RangeError(
       `Poll.make: "${tag}" asks for a wait of ${longestWaitMs} ms before its last attempt. An ` +
         `intervalMs of ${intervalMs} under the "${backoff}" backoff reaches a length no clock ` +

package/src/Sleep.ts

@@ -102,6 +102,30 @@ export const action: Action.Declared<
   tier: "sealed"
 })
 
+/**
+ * The latest deadline a sleep can arm, in epoch milliseconds.
+ *
+ * A durable store records `wakeAt` and a clock's due time as a non-negative
+ * safe integer. A finite deadline past this one passed every other check and
+ * then failed the park write, so it is refused with the payload's other
+ * invalid deadlines instead.
+ *
+ * @private
+ */
+const latestDeadline = Number.MAX_SAFE_INTEGER
+
+/**
+ * The refusal for a deadline later than {@link latestDeadline}.
+ *
+ * @private
+ */
+const tooLate = (stated: string): SleepRequestInvalid =>
+  new SleepRequestInvalid({
+    code: "invalid_deadline",
+    message: `${tag} was called with ${stated}, which ends after ${latestDeadline}, the latest epoch ` +
+      "millisecond a durable timer records."
+  })
+
 /**
  * The absolute deadline a payload names, in epoch milliseconds.
  *
@@ -153,12 +177,13 @@ const deadlineOf = (
         })
       )
     }
-    return Effect.succeed(deadline)
+    return Math.ceil(deadline) > latestDeadline
+      ? Effect.fail(tooLate(`millis ${payload.millis} at current time ${now}`))
+      : Effect.succeed(deadline)
   }
   if (payload.until !== undefined) {
-    return Number.isFinite(payload.until)
-      ? Effect.succeed(payload.until)
-      : Effect.fail(
+    if (!Number.isFinite(payload.until)) {
+      return Effect.fail(
         new SleepRequestInvalid({
           code: "invalid_deadline",
           message:
@@ -166,6 +191,10 @@ const deadlineOf = (
             "the sleep must end at a real point in time."
         })
       )
+    }
+    return Math.ceil(payload.until) > latestDeadline
+      ? Effect.fail(tooLate(`until ${payload.until}`))
+      : Effect.succeed(payload.until)
   }
   return Effect.fail(
     new SleepRequestInvalid({