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

package/dist/esm/Action/retry.js

@@ -0,0 +1,72 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+/**
+ * Retries effects while preserving durable action identity.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import { dual } from "effect/Function";
+import { CurrentAttempt, CurrentOrdinal } from "./Context.js";
+/**
+ * Retries an effect with `Effect.retry` while updating `CurrentAttempt` for
+ * each attempt.
+ *
+ * @category error handling
+ * @since 0.1.0
+ */
+export const retry = dual(2, (effect, options) => Effect.gen(function* () {
+    // A nested retry block shares the enclosing block's slot instead of
+    // shadowing it with a fresh one (issue #108): a per-invocation slot was
+    // rebuilt on every outer attempt, discarding the pinned `values`, so a
+    // completed irreversible inner dispatch drew a brand-new ordinal — a
+    // new step key — and re-executed instead of replaying. Sharing the
+    // outermost slot keeps every pin alive for the whole outer sequence.
+    const enclosing = yield* CurrentOrdinal;
+    // One `values` map for the whole retry sequence: the engine fills each
+    // action's scope with the ordinal it allocates on the first attempt,
+    // and every later attempt of the same sequence reuses those ordinals
+    // (issues #73, #84). The `cursors` map, however, is *per block*
+    // (issue #116): #108 shared the enclosing block's mutable cursor map
+    // wholesale, so a sibling block's attempt boundary — sanctioned to run
+    // concurrently under keyed overlap (issue #111) — cleared every
+    // scope's cursor and rewound another block's mid-flight dispatch onto
+    // an already-consumed pinned ordinal, a duplicate step key. Each block
+    // now owns a private cursor view seeded from the enclosing block's
+    // cursors at entry, so its attempt boundaries reset only its own view.
+    const slot = {
+        values: enclosing?.values ?? new Map(),
+        cursors: new Map(enclosing?.cursors)
+    };
+    // Where each scope's dispatch cursor stood when this block was entered.
+    // An inner attempt replays the block from its own first dispatch, not
+    // from the outer attempt's start, so its cursors rewind to the block
+    // entry rather than to zero (issues #100, #108). At the top level the
+    // snapshot is empty and rewinding degenerates to a plain reset.
+    const entryCursors = new Map(slot.cursors);
+    let attempt = 1;
+    return yield* Effect.suspend(() => {
+        // Every attempt replays the block from its first dispatch, so the
+        // per-scope dispatch cursors restart with it (issue #100); the pinned
+        // ordinal sequences in `values` persist across attempts.
+        slot.cursors.clear();
+        for (const [scope, cursor] of entryCursors) {
+            slot.cursors.set(scope, cursor);
+        }
+        return effect.pipe(Effect.provideService(CurrentAttempt, attempt++), Effect.provideService(CurrentOrdinal, slot));
+    }).pipe(Effect.retry(options), 
+    // On exit, fold this block's final cursor positions back into the
+    // enclosing block's view (max-merge, so a concurrent sibling's later
+    // propagation never rewinds a scope): an enclosing dispatch of a
+    // scope this block consumed must take the next pinned position, not
+    // re-consume this block's ordinals.
+    Effect.onExit(() => Effect.sync(() => {
+        if (enclosing === undefined)
+            return;
+        for (const [scope, cursor] of slot.cursors) {
+            const current = enclosing.cursors.get(scope) ?? 0;
+            if (cursor > current)
+                enclosing.cursors.set(scope, cursor);
+        }
+    })));
+}));
+//# sourceMappingURL=retry.js.map

package/dist/esm/Action/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/Action/retry.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAEtC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAoB,MAAM,cAAc,CAAA;AAE/E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,KAAK,GAQd,IAAI,CACN,CAAC,EACD,CAAC,MAAoC,EAAE,OAAe,EAAE,EAAE,CACxD,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,oEAAoE;IACpE,wEAAwE;IACxE,uEAAuE;IACvE,qEAAqE;IACrE,mEAAmE;IACnE,qEAAqE;IACrE,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,cAAc,CAAA;IACvC,uEAAuE;IACvE,qEAAqE;IACrE,qEAAqE;IACrE,gEAAgE;IAChE,qEAAqE;IACrE,uEAAuE;IACvE,gEAAgE;IAChE,sEAAsE;IACtE,uEAAuE;IACvE,mEAAmE;IACnE,uEAAuE;IACvE,MAAM,IAAI,GAAgB;QACxB,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,IAAI,GAAG,EAAE;QACtC,OAAO,EAAE,IAAI,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC;KACrC,CAAA;IACD,wEAAwE;IACxE,sEAAsE;IACtE,qEAAqE;IACrE,sEAAsE;IACtE,gEAAgE;IAChE,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAC1C,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE;QAChC,kEAAkE;QAClE,sEAAsE;QACtE,yDAAyD;QACzD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QACpB,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,YAAY,EAAE,CAAC;YAC3C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;QACjC,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAChB,MAAM,CAAC,cAAc,CAAC,cAAc,EAAE,OAAO,EAAE,CAAC,EAChD,MAAM,CAAC,cAAc,CAAC,cAAc,EAAE,IAAI,CAAC,CAC5C,CAAA;IACH,CAAC,CAAC,CAAC,IAAI,CACL,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;IACrB,kEAAkE;IAClE,qEAAqE;IACrE,iEAAiE;IACjE,oEAAoE;IACpE,oCAAoC;IACpC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CACjB,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;QACf,IAAI,SAAS,KAAK,SAAS;YAAE,OAAM;QACnC,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC3C,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YACjD,IAAI,MAAM,GAAG,OAAO;gBAAE,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;QAC5D,CAAC;IACH,CAAC,CAAC,CACH,CACF,CAAA;AACH,CAAC,CAAC,CACL,CAAA","sourcesContent":["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * Retries effects while preserving durable action identity.\n *\n * @since 0.1.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport { dual } from \"effect/Function\"\nimport type * as Types from \"effect/Types\"\nimport { CurrentAttempt, CurrentOrdinal, type OrdinalSlot } from \"./Context.ts\"\n\n/**\n * Retries an effect with `Effect.retry` while updating `CurrentAttempt` for\n * each attempt.\n *\n * @category error handling\n * @since 0.1.0\n */\nexport const retry: {\n  <E, O extends Types.NoExcessProperties<Omit<Effect.Retry.Options<E>, \"schedule\">, O>>(\n    options: O\n  ): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Retry.Return<R, E, A, O>\n  <A, E, R, O extends Types.NoExcessProperties<Omit<Effect.Retry.Options<E>, \"schedule\">, O>>(\n    self: Effect.Effect<A, E, R>,\n    options: O\n  ): Effect.Retry.Return<R, E, A, O>\n} = dual(\n  2,\n  (effect: Effect.Effect<any, any, any>, options: object) =>\n    Effect.gen(function*() {\n      // A nested retry block shares the enclosing block's slot instead of\n      // shadowing it with a fresh one (issue #108): a per-invocation slot was\n      // rebuilt on every outer attempt, discarding the pinned `values`, so a\n      // completed irreversible inner dispatch drew a brand-new ordinal — a\n      // new step key — and re-executed instead of replaying. Sharing the\n      // outermost slot keeps every pin alive for the whole outer sequence.\n      const enclosing = yield* CurrentOrdinal\n      // One `values` map for the whole retry sequence: the engine fills each\n      // action's scope with the ordinal it allocates on the first attempt,\n      // and every later attempt of the same sequence reuses those ordinals\n      // (issues #73, #84). The `cursors` map, however, is *per block*\n      // (issue #116): #108 shared the enclosing block's mutable cursor map\n      // wholesale, so a sibling block's attempt boundary — sanctioned to run\n      // concurrently under keyed overlap (issue #111) — cleared every\n      // scope's cursor and rewound another block's mid-flight dispatch onto\n      // an already-consumed pinned ordinal, a duplicate step key. Each block\n      // now owns a private cursor view seeded from the enclosing block's\n      // cursors at entry, so its attempt boundaries reset only its own view.\n      const slot: OrdinalSlot = {\n        values: enclosing?.values ?? new Map(),\n        cursors: new Map(enclosing?.cursors)\n      }\n      // Where each scope's dispatch cursor stood when this block was entered.\n      // An inner attempt replays the block from its own first dispatch, not\n      // from the outer attempt's start, so its cursors rewind to the block\n      // entry rather than to zero (issues #100, #108). At the top level the\n      // snapshot is empty and rewinding degenerates to a plain reset.\n      const entryCursors = new Map(slot.cursors)\n      let attempt = 1\n      return yield* Effect.suspend(() => {\n        // Every attempt replays the block from its first dispatch, so the\n        // per-scope dispatch cursors restart with it (issue #100); the pinned\n        // ordinal sequences in `values` persist across attempts.\n        slot.cursors.clear()\n        for (const [scope, cursor] of entryCursors) {\n          slot.cursors.set(scope, cursor)\n        }\n        return effect.pipe(\n          Effect.provideService(CurrentAttempt, attempt++),\n          Effect.provideService(CurrentOrdinal, slot)\n        )\n      }).pipe(\n        Effect.retry(options),\n        // On exit, fold this block's final cursor positions back into the\n        // enclosing block's view (max-merge, so a concurrent sibling's later\n        // propagation never rewinds a scope): an enclosing dispatch of a\n        // scope this block consumed must take the next pinned position, not\n        // re-consume this block's ordinals.\n        Effect.onExit(() =>\n          Effect.sync(() => {\n            if (enclosing === undefined) return\n            for (const [scope, cursor] of slot.cursors) {\n              const current = enclosing.cursors.get(scope) ?? 0\n              if (cursor > current) enclosing.cursors.set(scope, cursor)\n            }\n          })\n        )\n      )\n    })\n)\n"]}

package/dist/esm/Deadline.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The wall-clock bound one run of a flow settles by.
+ *
+ * A deadline counts from the run's FIRST start, which is journaled, so it
+ * survives park, resume and process death: a restarted engine honors the
+ * original deadline instead of starting a new one. A trampoline lineage is one
+ * run, so its rounds share one deadline: the round that hands off stamps the
+ * lineage's start and bound on the {@link module:Result.Handoff}, and the next
+ * round runs under that stamp rather than starting a clock of its own. Like
+ * `maxRounds`, the bound belongs to the lineage originator; a handoff target
+ * cannot reset or replace it.
+ *
+ * The engine applies {@link bound} to every execution of a flow that declares
+ * `Flow.make(tag, { deadline })`. A control plane applies it inside a run body
+ * to bound a run by an approved envelope's deadline. Both settle an expired
+ * run with the same {@link module:DeadlineExceeded.DeadlineExceeded} defect.
+ *
+ * @since 1.0.0
+ */
+import type * as Crypto from "effect/Crypto";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import { type LineageDeadline } from "./Flow/Result.ts";
+import { FlowInstance } from "./FlowRuntime/FlowInstance.ts";
+import { FlowRuntime } from "./FlowRuntime/FlowRuntime.ts";
+/**
+ * Starts the current execution's deadline: the lineage deadline this round
+ * inherited from a handoff, or `deadline` counted from the execution's
+ * journaled first start, or from `startedAtMs` when the host supplies a
+ * durable start of its own. Answers `undefined` when neither applies, which is
+ * an unbounded execution.
+ *
+ * **Details**
+ *
+ * The first start is a sealed action, so every later drive of the execution,
+ * on this engine or one that resumes it after a restart, reads the same
+ * origin. A durable clock is armed at the deadline so a parked execution is
+ * driven again when it passes; the clock keeps the due time it was first armed
+ * with, so arming it on every drive is idempotent.
+ *
+ * **Gotchas**
+ *
+ * Start at most one deadline per execution, before any other dispatch that a
+ * 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
+ */
+export declare const start: (options: {
+    /** The flow the refusal names. */
+    readonly flowName: string;
+    /** The bound; a positive finite duration. Absent means unbounded. */
+    readonly deadline?: Duration.Input | undefined;
+    /**
+     * Where the bound counts from, when the host already holds a durable
+     * start of its own, such as the time a control plane accepted the run.
+     * Absent, the execution's first start is journaled and read back.
+     */
+    readonly startedAtMs?: number | undefined;
+}) => Effect.Effect<LineageDeadline | undefined, never, FlowRuntime | FlowInstance | Crypto.Crypto>;
+/**
+ * The whole milliseconds left before `deadline` passes, as the durable clock
+ * row stores its due time; zero or less once it has passed.
+ *
+ * @category getters
+ * @since 1.0.0
+ */
+export declare const remainingMs: (deadline: LineageDeadline) => Effect.Effect<number>;
+/**
+ * Runs `body` within a started deadline.
+ *
+ * A body that starts at or past the deadline settles at once, and one that
+ * starts before it races the time remaining in this fiber, so a running
+ * execution is stopped too. Both settle with the same `DeadlineExceeded`
+ * defect. The race is `raceFirst`: a body that parks exits first, so parking
+ * still parks. A round that hands off stamps the deadline on its handoff, so
+ * the next round of the lineage runs under it. An `undefined` deadline runs
+ * `body` unbounded.
+ *
+ * @category combinators
+ * @since 1.0.0
+ */
+export declare const within: (deadline: LineageDeadline | undefined, flowName: string) => <A, E, R>(body: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | FlowInstance>;
+/**
+ * Bounds the current execution by `deadline`, counted from its journaled first
+ * start, or by the lineage deadline this round inherited from a handoff:
+ * {@link start}, then {@link within}.
+ *
+ * A round that inherited a lineage deadline runs under it whatever it
+ * declares, so every round of a lineage expires at the originator's time. With
+ * no inherited deadline and `deadline` absent, the body runs unbounded.
+ *
+ * @category combinators
+ * @since 1.0.0
+ */
+export declare const bound: (options: {
+    /** The flow the refusal names. */
+    readonly flowName: string;
+    /** The bound; a positive finite duration. Absent means unbounded. */
+    readonly deadline?: Duration.Input | undefined;
+    /** Where the bound counts from; see {@link start}. */
+    readonly startedAtMs?: number | undefined;
+}) => <A, E, R>(body: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | FlowRuntime | FlowInstance | Crypto.Crypto>;
+//# sourceMappingURL=Deadline.d.ts.map

package/dist/esm/Deadline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Deadline.d.ts","sourceRoot":"","sources":["../../src/Deadline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAMvC,OAAO,EAAW,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAA;AAgB1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,KAAK,GAAI,SAAS;IAC7B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1C,KAAG,MAAM,CAAC,MAAM,CAAC,eAAe,GAAG,SAAS,EAAE,KAAK,EAAE,WAAW,GAAG,YAAY,GAAG,MAAM,CAAC,MAAM,CAoC5F,CAAA;AAEJ;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,eAAe,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAC+B,CAAA;AAE3G;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM,GAChB,UAAU,eAAe,GAAG,SAAS,EAAE,UAAU,MAAM,MACvD,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,YAAY,CAwBzE,CAAA;AAEN;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK,GAAI,SAAS;IAC7B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;IAC9C,sDAAsD;IACtD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1C,MACA,CAAC,EAAE,CAAC,EAAE,CAAC,EACN,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,WAAW,GAAG,YAAY,GAAG,MAAM,CAAC,MAAM,CACmB,CAAA"}

package/dist/esm/Deadline.js

@@ -0,0 +1,164 @@
+/**
+ * The wall-clock bound one run of a flow settles by.
+ *
+ * A deadline counts from the run's FIRST start, which is journaled, so it
+ * survives park, resume and process death: a restarted engine honors the
+ * original deadline instead of starting a new one. A trampoline lineage is one
+ * run, so its rounds share one deadline: the round that hands off stamps the
+ * lineage's start and bound on the {@link module:Result.Handoff}, and the next
+ * round runs under that stamp rather than starting a clock of its own. Like
+ * `maxRounds`, the bound belongs to the lineage originator; a handoff target
+ * cannot reset or replace it.
+ *
+ * The engine applies {@link bound} to every execution of a flow that declares
+ * `Flow.make(tag, { deadline })`. A control plane applies it inside a run body
+ * to bound a run by an approved envelope's deadline. Both settle an expired
+ * run with the same {@link module:DeadlineExceeded.DeadlineExceeded} defect.
+ *
+ * @since 1.0.0
+ */
+import * as Clock from "effect/Clock";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Action from "./Action/index.js";
+import * as DurableClock from "./DurableClock.js";
+import { DeadlineExceeded } from "./Flow/DeadlineExceeded.js";
+import { Handoff } from "./Flow/Result.js";
+import { FlowInstance } from "./FlowRuntime/FlowInstance.js";
+import { FlowRuntime } from "./FlowRuntime/FlowRuntime.js";
+/**
+ * The execution's first start, journaled once.
+ *
+ * A sealed action's result is recorded with its attempt and replayed on every
+ * later drive, so the origin a deadline counts from is the time the execution
+ * first ran, on this engine or on the one that resumes it after a restart.
+ */
+const origin = Action.make({
+    name: "@smthrs/engine/deadline-origin",
+    tier: "sealed",
+    success: Schema.Number,
+    execute: Clock.currentTimeMillis.pipe(Effect.map(Math.floor))
+});
+/**
+ * Starts the current execution's deadline: the lineage deadline this round
+ * inherited from a handoff, or `deadline` counted from the execution's
+ * journaled first start, or from `startedAtMs` when the host supplies a
+ * durable start of its own. Answers `undefined` when neither applies, which is
+ * an unbounded execution.
+ *
+ * **Details**
+ *
+ * The first start is a sealed action, so every later drive of the execution,
+ * on this engine or one that resumes it after a restart, reads the same
+ * origin. A durable clock is armed at the deadline so a parked execution is
+ * driven again when it passes; the clock keeps the due time it was first armed
+ * with, so arming it on every drive is idempotent.
+ *
+ * **Gotchas**
+ *
+ * Start at most one deadline per execution, before any other dispatch that a
+ * 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
+ */
+export const start = (options) => Effect.gen(function* () {
+    const instance = yield* FlowInstance;
+    let lineage = instance.lineageDeadline;
+    if (lineage === undefined) {
+        if (options.deadline === undefined)
+            return undefined;
+        const deadlineMs = Option.match(Duration.fromInput(options.deadline), {
+            onNone: () => Number.NaN,
+            onSome: Duration.toMillis
+        });
+        if (!Number.isFinite(deadlineMs) || deadlineMs <= 0) {
+            return yield* Effect.die(new RangeError(`Deadline.start: "${options.flowName}" deadline must be a positive finite duration`));
+        }
+        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) {
+        yield* (yield* FlowRuntime).scheduleClock(instance.flow, {
+            executionId: instance.executionId,
+            clock: DurableClock.make({ name: "@smthrs/engine/deadline", duration: remaining })
+        });
+    }
+    return lineage;
+});
+/**
+ * The whole milliseconds left before `deadline` passes, as the durable clock
+ * row stores its due time; zero or less once it has passed.
+ *
+ * @category getters
+ * @since 1.0.0
+ */
+export const remainingMs = (deadline) => Effect.map(Clock.currentTimeMillis, (now) => Math.ceil(deadline.startedAtMs + deadline.deadlineMs - now));
+/**
+ * Runs `body` within a started deadline.
+ *
+ * A body that starts at or past the deadline settles at once, and one that
+ * starts before it races the time remaining in this fiber, so a running
+ * execution is stopped too. Both settle with the same `DeadlineExceeded`
+ * defect. The race is `raceFirst`: a body that parks exits first, so parking
+ * still parks. A round that hands off stamps the deadline on its handoff, so
+ * the next round of the lineage runs under it. An `undefined` deadline runs
+ * `body` unbounded.
+ *
+ * @category combinators
+ * @since 1.0.0
+ */
+export const within = (deadline, flowName) => (body) => deadline === undefined ? body : Effect.gen(function* () {
+    const instance = yield* FlowInstance;
+    const expired = new DeadlineExceeded({
+        flowName,
+        executionId: instance.executionId,
+        deadlineMs: deadline.deadlineMs,
+        startedAtMs: deadline.startedAtMs,
+        message: `${flowName} execution ${instance.executionId} ran past its ${deadline.deadlineMs} ms deadline, ` +
+            `counted from its start at ${new Date(deadline.startedAtMs).toISOString()}`
+    });
+    const remaining = yield* remainingMs(deadline);
+    if (remaining <= 0)
+        return yield* Effect.die(expired);
+    const value = yield* Effect.raceFirst(body, Effect.andThen(Effect.sleep(remaining), Effect.die(expired)));
+    const handoff = instance.handoff;
+    if (handoff !== undefined && handoff.deadline === undefined) {
+        instance.handoff = new Handoff({
+            flow: handoff.flow,
+            payload: handoff.payload,
+            ...(handoff.capabilityCeilings === undefined ? {} : { capabilityCeilings: handoff.capabilityCeilings }),
+            deadline
+        });
+    }
+    return value;
+});
+/**
+ * Bounds the current execution by `deadline`, counted from its journaled first
+ * start, or by the lineage deadline this round inherited from a handoff:
+ * {@link start}, then {@link within}.
+ *
+ * A round that inherited a lineage deadline runs under it whatever it
+ * declares, so every round of a lineage expires at the originator's time. With
+ * no inherited deadline and `deadline` absent, the body runs unbounded.
+ *
+ * @category combinators
+ * @since 1.0.0
+ */
+export const bound = (options) => (body) => Effect.flatMap(start(options), (deadline) => within(deadline, options.flowName)(body));
+//# sourceMappingURL=Deadline.js.map

package/dist/esm/Deadline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Deadline.js","sourceRoot":"","sources":["../../src/Deadline.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The wall-clock bound one run of a flow settles by.\n *\n * A deadline counts from the run's FIRST start, which is journaled, so it\n * survives park, resume and process death: a restarted engine honors the\n * original deadline instead of starting a new one. A trampoline lineage is one\n * run, so its rounds share one deadline: the round that hands off stamps the\n * lineage's start and bound on the {@link module:Result.Handoff}, and the next\n * round runs under that stamp rather than starting a clock of its own. Like\n * `maxRounds`, the bound belongs to the lineage originator; a handoff target\n * cannot reset or replace it.\n *\n * The engine applies {@link bound} to every execution of a flow that declares\n * `Flow.make(tag, { deadline })`. A control plane applies it inside a run body\n * to bound a run by an approved envelope's deadline. Both settle an expired\n * run with the same {@link module:DeadlineExceeded.DeadlineExceeded} defect.\n *\n * @since 1.0.0\n */\n\nimport * as Clock from \"effect/Clock\"\nimport type * as Crypto from \"effect/Crypto\"\nimport * as Duration from \"effect/Duration\"\nimport * as Effect from \"effect/Effect\"\nimport * as Option from \"effect/Option\"\nimport * as Schema from \"effect/Schema\"\nimport * as Action from \"./Action/index.ts\"\nimport * as DurableClock from \"./DurableClock.ts\"\nimport { DeadlineExceeded } from \"./Flow/DeadlineExceeded.ts\"\nimport { Handoff, type LineageDeadline } from \"./Flow/Result.ts\"\nimport { FlowInstance } from \"./FlowRuntime/FlowInstance.ts\"\nimport { FlowRuntime } from \"./FlowRuntime/FlowRuntime.ts\"\n\n/**\n * The execution's first start, journaled once.\n *\n * A sealed action's result is recorded with its attempt and replayed on every\n * later drive, so the origin a deadline counts from is the time the execution\n * first ran, on this engine or on the one that resumes it after a restart.\n */\nconst origin = Action.make({\n  name: \"@smthrs/engine/deadline-origin\",\n  tier: \"sealed\",\n  success: Schema.Number,\n  execute: Clock.currentTimeMillis.pipe(Effect.map(Math.floor))\n})\n\n/**\n * Starts the current execution's deadline: the lineage deadline this round\n * inherited from a handoff, or `deadline` counted from the execution's\n * journaled first start, or from `startedAtMs` when the host supplies a\n * durable start of its own. Answers `undefined` when neither applies, which is\n * an unbounded execution.\n *\n * **Details**\n *\n * The first start is a sealed action, so every later drive of the execution,\n * on this engine or one that resumes it after a restart, reads the same\n * origin. A durable clock is armed at the deadline so a parked execution is\n * driven again when it passes; the clock keeps the due time it was first armed\n * with, so arming it on every drive is idempotent.\n *\n * **Gotchas**\n *\n * Start at most one deadline per execution, before any other dispatch that a\n * replay must line up with: the origin and the clock are addressed by fixed\n * names within the execution.\n *\n * A deadline that is not a positive finite duration, a `startedAtMs` that is\n * not finite, or a bound that would expire after epoch millisecond\n * `Number.MAX_SAFE_INTEGER` dies with a `RangeError`: a durable store records\n * the clock's due time as a safe integer.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const start = (options: {\n  /** The flow the refusal names. */\n  readonly flowName: string\n  /** The bound; a positive finite duration. Absent means unbounded. */\n  readonly deadline?: Duration.Input | undefined\n  /**\n   * Where the bound counts from, when the host already holds a durable\n   * start of its own, such as the time a control plane accepted the run.\n   * Absent, the execution's first start is journaled and read back.\n   */\n  readonly startedAtMs?: number | undefined\n}): Effect.Effect<LineageDeadline | undefined, never, FlowRuntime | FlowInstance | Crypto.Crypto> =>\n  Effect.gen(function*() {\n    const instance = yield* FlowInstance\n    let lineage = instance.lineageDeadline\n    if (lineage === undefined) {\n      if (options.deadline === undefined) return undefined\n      const deadlineMs = Option.match(Duration.fromInput(options.deadline), {\n        onNone: () => Number.NaN,\n        onSome: Duration.toMillis\n      })\n      if (!Number.isFinite(deadlineMs) || deadlineMs <= 0) {\n        return yield* Effect.die(\n          new RangeError(`Deadline.start: \"${options.flowName}\" deadline must be a positive finite duration`)\n        )\n      }\n      const startedAtMs = options.startedAtMs ?? (yield* origin)\n      // The clock armed below is due at `startedAtMs + deadlineMs`, and a\n      // durable store records a due time as a safe integer.\n      if (!Number.isFinite(startedAtMs) || startedAtMs + deadlineMs > Number.MAX_SAFE_INTEGER) {\n        return yield* Effect.die(\n          new RangeError(\n            `Deadline.start: \"${options.flowName}\" deadline must expire by epoch millisecond ` +\n              `${Number.MAX_SAFE_INTEGER}, and a ${deadlineMs} ms deadline from ${startedAtMs} does not`\n          )\n        )\n      }\n      lineage = { startedAtMs, deadlineMs }\n    }\n    const remaining = yield* remainingMs(lineage)\n    if (remaining > 0) {\n      yield* (yield* FlowRuntime).scheduleClock(instance.flow, {\n        executionId: instance.executionId,\n        clock: DurableClock.make({ name: \"@smthrs/engine/deadline\", duration: remaining })\n      })\n    }\n    return lineage\n  })\n\n/**\n * The whole milliseconds left before `deadline` passes, as the durable clock\n * row stores its due time; zero or less once it has passed.\n *\n * @category getters\n * @since 1.0.0\n */\nexport const remainingMs = (deadline: LineageDeadline): Effect.Effect<number> =>\n  Effect.map(Clock.currentTimeMillis, (now) => Math.ceil(deadline.startedAtMs + deadline.deadlineMs - now))\n\n/**\n * Runs `body` within a started deadline.\n *\n * A body that starts at or past the deadline settles at once, and one that\n * starts before it races the time remaining in this fiber, so a running\n * execution is stopped too. Both settle with the same `DeadlineExceeded`\n * defect. The race is `raceFirst`: a body that parks exits first, so parking\n * still parks. A round that hands off stamps the deadline on its handoff, so\n * the next round of the lineage runs under it. An `undefined` deadline runs\n * `body` unbounded.\n *\n * @category combinators\n * @since 1.0.0\n */\nexport const within =\n  (deadline: LineageDeadline | undefined, flowName: string) =>\n  <A, E, R>(body: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | FlowInstance> =>\n    deadline === undefined ? body : Effect.gen(function*() {\n      const instance = yield* FlowInstance\n      const expired = new DeadlineExceeded({\n        flowName,\n        executionId: instance.executionId,\n        deadlineMs: deadline.deadlineMs,\n        startedAtMs: deadline.startedAtMs,\n        message: `${flowName} execution ${instance.executionId} ran past its ${deadline.deadlineMs} ms deadline, ` +\n          `counted from its start at ${new Date(deadline.startedAtMs).toISOString()}`\n      })\n      const remaining = yield* remainingMs(deadline)\n      if (remaining <= 0) return yield* Effect.die(expired)\n      const value = yield* Effect.raceFirst(body, Effect.andThen(Effect.sleep(remaining), Effect.die(expired)))\n      const handoff = instance.handoff\n      if (handoff !== undefined && handoff.deadline === undefined) {\n        instance.handoff = new Handoff({\n          flow: handoff.flow,\n          payload: handoff.payload,\n          ...(handoff.capabilityCeilings === undefined ? {} : { capabilityCeilings: handoff.capabilityCeilings }),\n          deadline\n        })\n      }\n      return value\n    })\n\n/**\n * Bounds the current execution by `deadline`, counted from its journaled first\n * start, or by the lineage deadline this round inherited from a handoff:\n * {@link start}, then {@link within}.\n *\n * A round that inherited a lineage deadline runs under it whatever it\n * declares, so every round of a lineage expires at the originator's time. With\n * no inherited deadline and `deadline` absent, the body runs unbounded.\n *\n * @category combinators\n * @since 1.0.0\n */\nexport const bound = (options: {\n  /** The flow the refusal names. */\n  readonly flowName: string\n  /** The bound; a positive finite duration. Absent means unbounded. */\n  readonly deadline?: Duration.Input | undefined\n  /** Where the bound counts from; see {@link start}. */\n  readonly startedAtMs?: number | undefined\n}) =>\n<A, E, R>(\n  body: Effect.Effect<A, E, R>\n): Effect.Effect<A, E, R | FlowRuntime | FlowInstance | Crypto.Crypto> =>\n  Effect.flatMap(start(options), (deadline) => within(deadline, options.flowName)(body))\n"]}

package/dist/esm/DurableClock.d.ts

@@ -0,0 +1,60 @@
+import type * as Crypto from "effect/Crypto";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import type * as Schema from "effect/Schema";
+import * as DurableDeferred from "./DurableDeferred.ts";
+import { FlowInstance } from "./FlowRuntime/FlowInstance.ts";
+import { FlowRuntime } from "./FlowRuntime/FlowRuntime.ts";
+declare const TypeId = "@smthrs/flow/DurableClock";
+/**
+ * Represents a durable flow timer with a name, duration, and deferred
+ * completed when the timer wakes.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface DurableClock {
+    readonly [TypeId]: typeof TypeId;
+    readonly name: string;
+    readonly duration: Duration.Duration;
+    readonly deferred: DurableDeferred.DurableDeferred<typeof Schema.Void>;
+}
+/**
+ * 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 declare const make: (options: {
+    readonly name: string;
+    readonly duration: Duration.Input;
+}) => DurableClock;
+/**
+ * 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
+ */
+export declare const sleep: (options: {
+    readonly name: string;
+    readonly duration: Duration.Input;
+    /**
+     * If the duration is less than or equal to this threshold, the clock will
+     * be executed in memory.
+     *
+     * @default 60 seconds
+     */
+    readonly inMemoryThreshold?: Duration.Input | undefined;
+}) => Effect.Effect<void, never, Crypto.Crypto | FlowRuntime | FlowInstance>;
+export {};
+//# sourceMappingURL=DurableClock.d.ts.map

package/dist/esm/DurableClock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DurableClock.d.ts","sourceRoot":"","sources":["../../src/DurableClock.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAE5C,OAAO,KAAK,eAAe,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAA;AAE1D,QAAA,MAAM,MAAM,8BAA8B,CAAA;AAE1C;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,MAAM,CAAA;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAA;IACpC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC,eAAe,CAAC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAA;CACvE;AAkDD;;;;;;;;;GASG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAA;CAClC,KAAG,YAAwE,CAAA;AAE5E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK,GAChB,SAAS;IACP,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAA;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;CACxD,KACA,MAAM,CAAC,MAAM,CACd,IAAI,EACJ,KAAK,EACL,MAAM,CAAC,MAAM,GAAG,WAAW,GAAG,YAAY,CA2C3C,CAAA"}

package/dist/esm/DurableClock.js

@@ -0,0 +1,122 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+/**
+ * Durable timers for flow sleeps.
+ *
+ * `make` creates a `DurableClock` with a name, duration, and deferred wake-up
+ * signal. `sleep` ignores zero durations, runs short sleeps through an
+ * in-memory action, and schedules longer sleeps through the `FlowRuntime`
+ * before awaiting the durable deferred tied to the clock.
+ *
+ * @since 0.1.0
+ */
+import * as Clock from "effect/Clock";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Action from "./Action/index.js";
+import * as DurableDeferred from "./DurableDeferred.js";
+import { FlowInstance } from "./FlowRuntime/FlowInstance.js";
+import { FlowRuntime } from "./FlowRuntime/FlowRuntime.js";
+const TypeId = "@smthrs/flow/DurableClock";
+/**
+ * Parses one author-supplied duration and requires it to be finite and
+ * nonnegative. Invalid input throws `RangeError` so the authoring mistake is
+ * caught at declaration time, matching `Flow.make` and `Poll.make`.
+ *
+ * @private
+ */
+const durationFromInput = (input, field) => {
+    const parsed = Duration.fromInput(input);
+    if (Option.isNone(parsed)) {
+        throw new RangeError(`DurableClock: "${field}" must be a valid finite duration that is not negative.`);
+    }
+    const millis = Duration.toMillis(parsed.value);
+    if (!Duration.isFinite(parsed.value) || !Number.isFinite(millis) || millis < 0) {
+        throw new RangeError(`DurableClock: "${field}" must be a valid finite duration that is not negative.`);
+    }
+    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) => {
+    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, duration) => ({
+    [TypeId]: TypeId,
+    name,
+    duration,
+    deferred: DurableDeferred.make(`DurableClock/${name}`)
+});
+/**
+ * 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) => 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
+ */
+export const sleep = (options) => {
+    const name = options.name;
+    const duration = clockDuration(options.duration);
+    const inMemoryThreshold = durationFromInput(options.inMemoryThreshold ?? defaultInMemoryThreshold, "inMemoryThreshold");
+    // Untraced because durable sleeps are recursively resumed by the engine.
+    return Effect.fnUntraced(function* () {
+        if (Duration.isZero(duration)) {
+            return;
+        }
+        if (Duration.isLessThanOrEqualTo(duration, inMemoryThreshold)) {
+            return yield* Action.make({
+                name: `DurableClock/${name}`,
+                tier: "sealed",
+                execute: Effect.sleep(duration)
+            });
+        }
+        // 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);
+        yield* engine.scheduleClock(instance.flow, {
+            executionId: instance.executionId,
+            clock
+        });
+        return yield* DurableDeferred.await(clock.deferred);
+    })();
+};
+const defaultInMemoryThreshold = Duration.seconds(60);
+//# sourceMappingURL=DurableClock.js.map

package/dist/esm/DurableClock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DurableClock.js","sourceRoot":"","sources":["../../src/DurableClock.ts"],"names":[],"mappings":"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","sourcesContent":["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * Durable timers for flow sleeps.\n *\n * `make` creates a `DurableClock` with a name, duration, and deferred wake-up\n * signal. `sleep` ignores zero durations, runs short sleeps through an\n * in-memory action, and schedules longer sleeps through the `FlowRuntime`\n * before awaiting the durable deferred tied to the clock.\n *\n * @since 0.1.0\n */\n\nimport * as Clock from \"effect/Clock\"\nimport type * as Crypto from \"effect/Crypto\"\nimport * as Duration from \"effect/Duration\"\nimport * as Effect from \"effect/Effect\"\nimport * as Option from \"effect/Option\"\nimport type * as Schema from \"effect/Schema\"\nimport * as Action from \"./Action/index.ts\"\nimport * as DurableDeferred from \"./DurableDeferred.ts\"\nimport { FlowInstance } from \"./FlowRuntime/FlowInstance.ts\"\nimport { FlowRuntime } from \"./FlowRuntime/FlowRuntime.ts\"\n\nconst TypeId = \"@smthrs/flow/DurableClock\"\n\n/**\n * Represents a durable flow timer with a name, duration, and deferred\n * completed when the timer wakes.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface DurableClock {\n  readonly [TypeId]: typeof TypeId\n  readonly name: string\n  readonly duration: Duration.Duration\n  readonly deferred: DurableDeferred.DurableDeferred<typeof Schema.Void>\n}\n\n/**\n * Parses one author-supplied duration and requires it to be finite and\n * nonnegative. Invalid input throws `RangeError` so the authoring mistake is\n * caught at declaration time, matching `Flow.make` and `Poll.make`.\n *\n * @private\n */\nconst durationFromInput = (input: Duration.Input, field: string): Duration.Duration => {\n  const parsed = Duration.fromInput(input)\n  if (Option.isNone(parsed)) {\n    throw new RangeError(`DurableClock: \"${field}\" must be a valid finite duration that is not negative.`)\n  }\n  const millis = Duration.toMillis(parsed.value)\n  if (!Duration.isFinite(parsed.value) || !Number.isFinite(millis) || millis < 0) {\n    throw new RangeError(`DurableClock: \"${field}\" must be a valid finite duration that is not negative.`)\n  }\n  return parsed.value\n}\n\n/**\n * The latest due time a durable timer records, in epoch milliseconds: a store\n * keeps a clock's due time as a safe integer.\n *\n * @private\n */\nconst latestDueAtMs = Number.MAX_SAFE_INTEGER\n\n/**\n * Parses a clock's own duration, which a store adds to the current time and\n * records, so it is at most {@link latestDueAtMs} milliseconds.\n *\n * @private\n */\nconst clockDuration = (input: Duration.Input): Duration.Duration => {\n  const duration = durationFromInput(input, \"duration\")\n  if (Duration.toMillis(duration) > latestDueAtMs) {\n    throw new RangeError(`DurableClock: \"duration\" must be at most ${latestDueAtMs} milliseconds.`)\n  }\n  return duration\n}\n\nconst makeClock = (name: string, duration: Duration.Duration): DurableClock => ({\n  [TypeId]: TypeId,\n  name,\n  duration,\n  deferred: DurableDeferred.make(`DurableClock/${name}`)\n})\n\n/**\n * Declares one durable clock after validating its finite nonnegative duration.\n *\n * Throws a `RangeError` for a malformed, infinite or negative duration, or one\n * longer than `Number.MAX_SAFE_INTEGER` milliseconds: a durable store records\n * a clock's due time as a safe integer.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = (options: {\n  readonly name: string\n  readonly duration: Duration.Input\n}): DurableClock => makeClock(options.name, clockDuration(options.duration))\n\n/**\n * Waits inside a flow, using an in-memory action for durations at or\n * below the threshold and scheduling a durable clock for longer durations.\n *\n * Throws a `RangeError` for the same durations {@link make} refuses, and for\n * a malformed, infinite or negative threshold. A durable sleep that would\n * wake after epoch millisecond `Number.MAX_SAFE_INTEGER` dies with a\n * `RangeError` instead of arming its clock.\n *\n * @category sleeping\n * @since 0.1.0\n */\nexport const sleep = (\n  options: {\n    readonly name: string\n    readonly duration: Duration.Input\n    /**\n     * If the duration is less than or equal to this threshold, the clock will\n     * be executed in memory.\n     *\n     * @default 60 seconds\n     */\n    readonly inMemoryThreshold?: Duration.Input | undefined\n  }\n): Effect.Effect<\n  void,\n  never,\n  Crypto.Crypto | FlowRuntime | FlowInstance\n> => {\n  const name = options.name\n  const duration = clockDuration(options.duration)\n  const inMemoryThreshold = durationFromInput(\n    options.inMemoryThreshold ?? defaultInMemoryThreshold,\n    \"inMemoryThreshold\"\n  )\n\n  // Untraced because durable sleeps are recursively resumed by the engine.\n  return Effect.fnUntraced(function*() {\n    if (Duration.isZero(duration)) {\n      return\n    }\n\n    if (Duration.isLessThanOrEqualTo(duration, inMemoryThreshold)) {\n      return yield* Action.make({\n        name: `DurableClock/${name}`,\n        tier: \"sealed\",\n        execute: Effect.sleep(duration)\n      })\n    }\n\n    // A due time past the latest one a store records would fail the park\n    // write deep in the engine, so the sleep refuses it here by name.\n    const now = yield* Clock.currentTimeMillis\n    if (now + Duration.toMillis(duration) > latestDueAtMs) {\n      return yield* Effect.die(\n        new RangeError(\n          `DurableClock: \"${name}\" would wake after epoch millisecond ${latestDueAtMs}, ` +\n            `the latest due time a durable timer records.`\n        )\n      )\n    }\n    const engine = yield* FlowRuntime\n    const instance = yield* FlowInstance\n    const clock = makeClock(name, duration)\n    yield* engine.scheduleClock(instance.flow, {\n      executionId: instance.executionId,\n      clock\n    })\n    return yield* DurableDeferred.await(clock.deferred)\n  })()\n}\n\nconst defaultInMemoryThreshold = Duration.seconds(60)\n"]}