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

package/dist/esm/RetryPolicy.js

@@ -0,0 +1,429 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+/**
+ * Defines data-shaped retry policies for durable action retries.
+ *
+ * A `RetryPolicy` is a plain value — initial interval, backoff factor, cap,
+ * optional maximum attempts, optional jitter, and optional non-retryable
+ * error tags — so the next retry delay can be derived from a persisted
+ * attempt count instead of fiber-local `Schedule` state. `nextDelay` mirrors
+ * Temporal's `ExponentialRetryPolicy.ComputeNextDelay` formula, and `decide`
+ * is the engine's single retry decision point: the core default a pluggable
+ * `resolveRetry` resolution can later dispatch in front of.
+ *
+ * The historical terminal-failure schemas below use the `@smthrs/flow/` tags settled for
+ * 1.0.0-rc.0. The release candidate makes no compatibility promise to 0.x
+ * journals, and these tags freeze at the RC. Current action dispatch preserves
+ * the final declared failure when a retry policy is spent.
+ *
+ * See `docs/guides/retry-a-failing-action.md`; its "Infrastructure
+ * interrupts" section covers the interrupt retry schedule.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Random from "effect/Random";
+import * as Schema from "effect/Schema";
+/**
+ * Data-shaped retry policy schema.
+ *
+ * The delay before attempt `n + 1` is
+ * `min(initialMs * factor^(n - 1), maxMs)`, where `n` is the attempt that
+ * just failed. `maxAttempts` bounds the total number of attempts;
+ * `expirationMs` bounds the total wall-clock retry duration
+ * (schedule-to-close, mirroring Temporal's `expirationInterval`);
+ * `jitterRatio` spreads the final portion of each delay uniformly;
+ * `nonRetryable` lists error tags that must never be retried.
+ *
+ * The bounds are per STEP KEY, which is what makes them the provider-retry
+ * budget for one agent ask rather than a budget for the exchange the ask
+ * belongs to. A structured-output correction re-prompts under a NEW session,
+ * so the corrected ask is a different sealed step with its own attempt
+ * sequence: `maxAttempts` bounds the provider retries inside one correction
+ * session and does not bound the correction ladder, which `AgentAction`
+ * bounds separately with its own `corrections` budget.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+const RetryPolicyFields = 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))
+});
+/** Returns the first contract violation shared by decoding and construction. */
+const validationIssue = (policy) => {
+    // Zero is refused rather than read as "retry immediately": every computed
+    // delay would be zero, so such a policy would give up on its first failure
+    // no matter what `maxAttempts` promised. Use `initialMs: 1` for a
+    // near-immediate retry.
+    if (!Number.isFinite(policy.initialMs) || policy.initialMs <= 0) {
+        return `"initialMs" must be a finite number of milliseconds greater than zero, and was ${policy.initialMs}.`;
+    }
+    if (!Number.isFinite(policy.factor) || policy.factor <= 0) {
+        return `"factor" must be a finite number greater than zero, and was ${policy.factor}.`;
+    }
+    if (!Number.isFinite(policy.maxMs) || policy.maxMs < policy.initialMs) {
+        return `"maxMs" must be a finite number of milliseconds at least as large as initialMs, and was ${policy.maxMs}.`;
+    }
+    if (policy.maxAttempts !== undefined &&
+        (!Number.isSafeInteger(policy.maxAttempts) || policy.maxAttempts < 1)) {
+        return `"maxAttempts" must be a safe integer of at least one, and was ${policy.maxAttempts}.`;
+    }
+    if (policy.expirationMs !== undefined &&
+        (!Number.isFinite(policy.expirationMs) || policy.expirationMs <= 0)) {
+        return `"expirationMs" must be a finite number of milliseconds greater than zero, and was ${policy.expirationMs}.`;
+    }
+    if (policy.jitterRatio !== undefined &&
+        (!Number.isFinite(policy.jitterRatio) || policy.jitterRatio < 0 || policy.jitterRatio > 1)) {
+        return `"jitterRatio" must be a finite number between zero and one, inclusive, and was ${policy.jitterRatio}.`;
+    }
+    return undefined;
+};
+/**
+ * Data-shaped retry policy schema. Decoding enforces the same relational
+ * contract as {@link make}; persisted data cannot bypass constructor checks.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const RetryPolicy = RetryPolicyFields.check(Schema.makeFilter((policy) => validationIssue(policy) ?? true, { title: "validRetryPolicy" }));
+/**
+ * Creates a `RetryPolicy` value after checking every numeric bound.
+ * `initialMs` must be greater than zero: a zero initial interval would
+ * compute a zero delay for every attempt, which {@link nextDelay} reads as
+ * exhausted, so the policy would never retry. `jitterRatio` must be between
+ * zero and one, inclusive, and `jitterRatio: 0` disables jitter.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (options) => {
+    const issue = validationIssue(options);
+    if (issue !== undefined)
+        throw new RangeError(`RetryPolicy.make: ${issue}`);
+    return Object.freeze({
+        initialMs: options.initialMs,
+        factor: options.factor,
+        maxMs: options.maxMs,
+        ...(options.maxAttempts !== undefined ? { maxAttempts: options.maxAttempts } : {}),
+        ...(options.expirationMs !== undefined ? { expirationMs: options.expirationMs } : {}),
+        ...(options.jitterRatio !== undefined ? { jitterRatio: options.jitterRatio } : {}),
+        ...(options.nonRetryable !== undefined
+            ? { nonRetryable: Object.freeze([...options.nonRetryable]) }
+            : {})
+    });
+};
+/**
+ * The default engine retry policy.
+ *
+ * Uses a 200ms initial delay growing by 1.5x, capped at 30s, and never gives
+ * up: it declares neither `maxAttempts` nor `expirationMs`. Bound long-lived
+ * retries with `make({ ..., expirationMs })` when a wall-clock give-up is
+ * required.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const defaultRetryPolicy = Object.freeze(make({
+    initialMs: 200,
+    factor: 1.5,
+    maxMs: 30000
+}));
+/**
+ * Bounded infrastructure retry: 5 seconds doubling to 5 minutes, for 2 hours.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const transient = make({
+    initialMs: 5000,
+    factor: 2,
+    maxMs: 300000,
+    expirationMs: 7200000
+});
+/**
+ * Creates a `RetryAfter` decision.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const retryAfter = (delayMs) => ({
+    _tag: "RetryAfter",
+    delayMs
+});
+/**
+ * Creates a `GiveUp` decision.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const giveUp = (reason) => ({
+    _tag: "GiveUp",
+    reason
+});
+/**
+ * A historical retry sequence crossed its `expirationMs` wall-clock bound.
+ * Current dispatch preserves the final declared failure instead of emitting this defect.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class RetryPolicyExpired extends Schema.TaggedError()("@smthrs/flow/RetryPolicyExpired", {
+    code: Schema.Literal("retry_policy_expired").pipe(Schema.withConstructorDefault(Effect.succeed("retry_policy_expired"))),
+    actionName: Schema.String,
+    attempt: Schema.Number,
+    expirationMs: Schema.Number,
+    lastError: Schema.optional(Schema.Unknown)
+}) {
+}
+/**
+ * A historical retry sequence exhausted its `maxAttempts` bound.
+ * Current dispatch preserves the final declared failure instead of emitting this defect.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class RetryAttemptsExhausted extends Schema.TaggedError()("@smthrs/flow/RetryAttemptsExhausted", {
+    code: Schema.Literal("retry_attempts_exhausted").pipe(Schema.withConstructorDefault(Effect.succeed("retry_attempts_exhausted"))),
+    actionName: Schema.String,
+    attempt: Schema.Number,
+    maxAttempts: Schema.Number,
+    lastError: Schema.optional(Schema.Unknown)
+}) {
+}
+/**
+ * Computes the delay before attempt `attempt + 1` from the persisted attempt
+ * count, mirroring Temporal's `ComputeNextDelay`
+ * (`common/backoff/retrypolicy.go`).
+ *
+ * `attempt` is the 1-based attempt that just failed. Returns `None` when the
+ * policy gives up: `maxAttempts` reached, a non-positive computed interval,
+ * a cap below the initial interval, or — when the policy declares
+ * `expirationMs` and the caller supplies `elapsedMs` — an elapsed duration
+ * past the expiration bound. Otherwise the delay is capped to the remaining
+ * expiration window, expiring only when that window cannot fit one more
+ * full-value (`initialMs`) attempt.
+ *
+ * Jitter is deterministic-friendly: `options.random` is a `[0, 1]` sample
+ * supplied by the caller and defaults to `1`, which leaves the delay at its
+ * un-jittered value. Use {@link nextDelayEffect} to sample the `Random`
+ * service instead. A sample outside `[0, 1]`, or a persisted `jitterRatio`
+ * above one, gives up rather than returning a delay the policy never
+ * declared. A sample of zero under `jitterRatio: 1` is a delay of zero, which
+ * retries immediately.
+ *
+ * @category attempts
+ * @since 0.1.0
+ */
+export const nextDelay = (policy, attempt, options) => {
+    // Persisted policies can be decoded without `make`, so these guards treat a
+    // corrupt row as terminal instead of sending an invalid delay to the engine.
+    if (validationIssue(policy) !== undefined || !Number.isSafeInteger(attempt) || attempt < 1) {
+        return Option.none();
+    }
+    if (options?.elapsedMs !== undefined &&
+        (!Number.isFinite(options.elapsedMs) || options.elapsedMs < 0)) {
+        return Option.none();
+    }
+    if (policy.maxAttempts !== undefined && attempt >= policy.maxAttempts) {
+        return Option.none();
+    }
+    if (policy.expirationMs !== undefined &&
+        options?.elapsedMs !== undefined &&
+        options.elapsedMs > policy.expirationMs) {
+        return Option.none();
+    }
+    const raw = policy.initialMs * Math.pow(policy.factor, attempt - 1);
+    if (!(raw > 0)) {
+        return Option.none();
+    }
+    let delay = Math.min(raw, policy.maxMs);
+    // Temporal caps the delay to the remaining expiration window rather than
+    // refusing outright; the below-initial check then expires sequences whose
+    // remaining window cannot fit one more full-value attempt.
+    if (policy.expirationMs !== undefined && options?.elapsedMs !== undefined) {
+        delay = Math.min(delay, Math.max(0, policy.expirationMs - options.elapsedMs));
+    }
+    if (delay < policy.initialMs) {
+        return Option.none();
+    }
+    // `validationIssue` established finite `maxMs`, so `Math.min` made the
+    // un-jittered delay finite even when the exponential itself overflowed.
+    // This check belongs before jitter conceptually: a full-jitter sample of
+    // zero is a legitimate immediate retry rather than a give-up.
+    if (policy.jitterRatio !== undefined && policy.jitterRatio > 0) {
+        // Both jitter inputs are bounded to [0, 1] where they are accepted --
+        // `make` for `jitterRatio` and this function's contract for `random` --
+        // while `random` is a public option that still needs checking here.
+        const random = options?.random ?? 1;
+        if (!(random >= 0 && random <= 1)) {
+            return Option.none();
+        }
+        // In range, the result is between `delay * (1 - jitterRatio)` and `delay`,
+        // so it is finite and never negative. A jittered value of zero retries
+        // immediately; it does not exhaust the sequence.
+        //
+        // The two terms do not sum to exactly `delay` at `random: 1`: at
+        // `jitterRatio: 0.000002` a delay of 100 rounds up to 100.00000000000001,
+        // above the policy's own cap and above the remaining expiration window.
+        // Clamping down to the un-jittered delay is what makes the upper bound
+        // stated above exact rather than approximate.
+        const jittered = delay * (1 - policy.jitterRatio) + random * delay * policy.jitterRatio;
+        delay = Math.min(delay, jittered);
+    }
+    return Option.some(delay);
+};
+/**
+ * Computes the next retry delay, sampling the `Random` service for jitter.
+ *
+ * Deterministic under `Random.withSeed`. Policies without a `jitterRatio`
+ * never touch the service.
+ *
+ * @category attempts
+ * @since 0.1.0
+ */
+export const nextDelayEffect = (policy, attempt, options) => policy.jitterRatio === undefined || policy.jitterRatio <= 0
+    ? Effect.sync(() => nextDelay(policy, attempt, { elapsedMs: options?.elapsedMs }))
+    : Effect.map(Random.next, (random) => nextDelay(policy, attempt, { random, elapsedMs: options?.elapsedMs }));
+/**
+ * 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: only a string data value is a tag.
+ *
+ * Descriptors keep accessors inert instead of running author code through a
+ * property read. A bounded walk also terminates when a hostile proxy reports a
+ * cyclic prototype chain; any proxy trap that throws leaves the error untagged.
+ *
+ * @category attempts
+ * @since 0.1.0
+ */
+export const errorTag = (error) => {
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    try {
+        const tag = Object.getOwnPropertyDescriptor(error, "_tag");
+        if (tag !== undefined && "value" in tag && typeof tag.value === "string")
+            return tag.value;
+        let current = error;
+        for (let depth = 0; current !== null && depth < 64; depth++) {
+            const name = Object.getOwnPropertyDescriptor(current, "name");
+            if (name !== undefined) {
+                return "value" in name && typeof name.value === "string" ? name.value : undefined;
+            }
+            current = Object.getPrototypeOf(current);
+        }
+    }
+    catch {
+        // Proxies and hostile accessors are untrusted failure payloads. An error
+        // that cannot be inspected inertly simply has no stable retry tag.
+    }
+    return undefined;
+};
+/**
+ * Error tags that are non-retryable by type, under every policy (issue #156).
+ *
+ * These failures are integrity verdicts that must reach the driver without an
+ * action-level retry hiding the first detection. Their persistence seams
+ * take a quarantine state action before raising them, so a later dispatch can
+ * heal, but the detecting dispatch remains a non-retryable failure. No
+ * per-callsite or per-policy opt-out exists; the tags are matched by string so
+ * the classification does not invert the package dependency direction.
+ *
+ * `AttemptEvidenceQuarantined` (issue #171) is the succeeded-attempt-row
+ * counterpart: the corrupt boundary evidence is removed while the completed
+ * outcome stays durable. It reaches the driver unretried, which parks the
+ * first detection in the `quarantine` waiting state; the next explicit resume
+ * returns the recorded outcome without re-executing the action.
+ *
+ * @category attempts
+ * @since 0.1.0
+ */
+export const defaultNonRetryable = [
+    "@smthrs/engine-store/CacheCorruptionDetected",
+    "@smthrs/engine-store/AttemptEvidenceQuarantined"
+];
+/**
+ * Whether an error is classified non-retryable, either by type (see
+ * {@link defaultNonRetryable}) or by the policy's declared tag list.
+ *
+ * @category attempts
+ * @since 0.1.0
+ */
+export const isNonRetryable = (policy, error) => {
+    const tag = errorTag(error);
+    if (tag === undefined) {
+        return false;
+    }
+    if (defaultNonRetryable.includes(tag)) {
+        return true;
+    }
+    return policy.nonRetryable !== undefined && policy.nonRetryable.includes(tag);
+};
+/**
+ * The pure core of the engine's single retry decision point.
+ *
+ * Non-retryable classification is evaluated here and nowhere else. This is
+ * the default a pluggable `resolveRetry` resolution falls back to when no
+ * plugin claims the decision.
+ *
+ * @category attempts
+ * @since 0.1.0
+ */
+export const decide = (policy, options) => {
+    if (isNonRetryable(policy, options.error)) {
+        return giveUp("nonRetryable");
+    }
+    return Option.match(nextDelay(policy, options.attempt, { random: options.random, elapsedMs: options.elapsedMs }), {
+        onNone: () => 
+        // A policy can report `expired` only when it declares an expiration
+        // bound and dropping elapsed time would have allowed another attempt.
+        // A malformed elapsed value still gives up because the sequence cannot
+        // continue without a trustworthy clock reading; without an expiration
+        // bound, the public terminal reason for that refusal is `exhausted`.
+        policy.expirationMs !== undefined &&
+            Option.isSome(nextDelay(policy, options.attempt, { random: options.random }))
+            ? giveUp("expired")
+            : giveUp("exhausted"),
+        onSome: (delay) => {
+            // Tool failures may supply a delay instead of using policy backoff.
+            // Inspect only an own data property: failure payloads can be untrusted.
+            let hint;
+            if (typeof options.error === "object" && options.error !== null) {
+                try {
+                    const descriptor = Object.getOwnPropertyDescriptor(options.error, "retryAfterMs");
+                    if (descriptor !== undefined && "value" in descriptor)
+                        hint = descriptor.value;
+                }
+                catch {
+                    // An uninspectable failure falls back to the policy delay.
+                }
+            }
+            if (typeof hint !== "number" || !Number.isFinite(hint) || hint < 0) {
+                return retryAfter(delay);
+            }
+            return retryAfter(Math.min(hint, policy.maxMs, policy.expirationMs !== undefined && options.elapsedMs !== undefined
+                ? Math.max(0, policy.expirationMs - options.elapsedMs)
+                : policy.maxMs));
+        }
+    });
+};
+/**
+ * Effect form of {@link decide}, sampling the `Random` service for jitter.
+ *
+ * This is the engine-facing decision function: keep calls to it behind a
+ * single decision point so a plugin hook dispatch can later be inserted in
+ * front of it without touching call sites.
+ *
+ * @category attempts
+ * @since 0.1.0
+ */
+export const decideEffect = (policy, options) => policy.jitterRatio === undefined || policy.jitterRatio <= 0
+    ? Effect.sync(() => decide(policy, options))
+    : Effect.map(Random.next, (random) => decide(policy, { ...options, random }));
+//# sourceMappingURL=RetryPolicy.js.map

package/dist/esm/RetryPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RetryPolicy.js","sourceRoot":"","sources":["../../src/RetryPolicy.ts"],"names":[],"mappings":"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","sourcesContent":["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * Defines data-shaped retry policies for durable action retries.\n *\n * A `RetryPolicy` is a plain value — initial interval, backoff factor, cap,\n * optional maximum attempts, optional jitter, and optional non-retryable\n * error tags — so the next retry delay can be derived from a persisted\n * attempt count instead of fiber-local `Schedule` state. `nextDelay` mirrors\n * Temporal's `ExponentialRetryPolicy.ComputeNextDelay` formula, and `decide`\n * is the engine's single retry decision point: the core default a pluggable\n * `resolveRetry` resolution can later dispatch in front of.\n *\n * The historical terminal-failure schemas below use the `@smthrs/flow/` tags settled for\n * 1.0.0-rc.0. The release candidate makes no compatibility promise to 0.x\n * journals, and these tags freeze at the RC. Current action dispatch preserves\n * the final declared failure when a retry policy is spent.\n *\n * See `docs/guides/retry-a-failing-action.md`; its \"Infrastructure\n * interrupts\" section covers the interrupt retry schedule.\n *\n * @since 0.1.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Option from \"effect/Option\"\nimport * as Random from \"effect/Random\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * Data-shaped retry policy schema.\n *\n * The delay before attempt `n + 1` is\n * `min(initialMs * factor^(n - 1), maxMs)`, where `n` is the attempt that\n * just failed. `maxAttempts` bounds the total number of attempts;\n * `expirationMs` bounds the total wall-clock retry duration\n * (schedule-to-close, mirroring Temporal's `expirationInterval`);\n * `jitterRatio` spreads the final portion of each delay uniformly;\n * `nonRetryable` lists error tags that must never be retried.\n *\n * The bounds are per STEP KEY, which is what makes them the provider-retry\n * budget for one agent ask rather than a budget for the exchange the ask\n * belongs to. A structured-output correction re-prompts under a NEW session,\n * so the corrected ask is a different sealed step with its own attempt\n * sequence: `maxAttempts` bounds the provider retries inside one correction\n * session and does not bound the correction ladder, which `AgentAction`\n * bounds separately with its own `corrections` budget.\n *\n * @category models\n * @since 0.1.0\n */\nconst RetryPolicyFields = Schema.Struct({\n  initialMs: Schema.Number,\n  factor: Schema.Number,\n  maxMs: Schema.Number,\n  maxAttempts: Schema.optional(Schema.Number),\n  expirationMs: Schema.optional(Schema.Number),\n  jitterRatio: Schema.optional(Schema.Number),\n  nonRetryable: Schema.optional(Schema.Array(Schema.String))\n})\n\ntype RetryPolicyFields = typeof RetryPolicyFields.Type\n\n/** Returns the first contract violation shared by decoding and construction. */\nconst validationIssue = (policy: RetryPolicyFields): string | undefined => {\n  // Zero is refused rather than read as \"retry immediately\": every computed\n  // delay would be zero, so such a policy would give up on its first failure\n  // no matter what `maxAttempts` promised. Use `initialMs: 1` for a\n  // near-immediate retry.\n  if (!Number.isFinite(policy.initialMs) || policy.initialMs <= 0) {\n    return `\"initialMs\" must be a finite number of milliseconds greater than zero, and was ${policy.initialMs}.`\n  }\n  if (!Number.isFinite(policy.factor) || policy.factor <= 0) {\n    return `\"factor\" must be a finite number greater than zero, and was ${policy.factor}.`\n  }\n  if (!Number.isFinite(policy.maxMs) || policy.maxMs < policy.initialMs) {\n    return `\"maxMs\" must be a finite number of milliseconds at least as large as initialMs, and was ${policy.maxMs}.`\n  }\n  if (\n    policy.maxAttempts !== undefined &&\n    (!Number.isSafeInteger(policy.maxAttempts) || policy.maxAttempts < 1)\n  ) {\n    return `\"maxAttempts\" must be a safe integer of at least one, and was ${policy.maxAttempts}.`\n  }\n  if (\n    policy.expirationMs !== undefined &&\n    (!Number.isFinite(policy.expirationMs) || policy.expirationMs <= 0)\n  ) {\n    return `\"expirationMs\" must be a finite number of milliseconds greater than zero, and was ${policy.expirationMs}.`\n  }\n  if (\n    policy.jitterRatio !== undefined &&\n    (!Number.isFinite(policy.jitterRatio) || policy.jitterRatio < 0 || policy.jitterRatio > 1)\n  ) {\n    return `\"jitterRatio\" must be a finite number between zero and one, inclusive, and was ${policy.jitterRatio}.`\n  }\n  return undefined\n}\n\n/**\n * Data-shaped retry policy schema. Decoding enforces the same relational\n * contract as {@link make}; persisted data cannot bypass constructor checks.\n *\n * @category models\n * @since 0.1.0\n */\nexport const RetryPolicy = RetryPolicyFields.check(\n  Schema.makeFilter(\n    (policy) => validationIssue(policy) ?? true,\n    { title: \"validRetryPolicy\" }\n  )\n)\n\n/**\n * The value form of a {@link RetryPolicy}.\n *\n * @category models\n * @since 0.1.0\n */\nexport type RetryPolicy = typeof RetryPolicy.Type\n\n/**\n * Creates a `RetryPolicy` value after checking every numeric bound.\n * `initialMs` must be greater than zero: a zero initial interval would\n * compute a zero delay for every attempt, which {@link nextDelay} reads as\n * exhausted, so the policy would never retry. `jitterRatio` must be between\n * zero and one, inclusive, and `jitterRatio: 0` disables jitter.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = (options: {\n  readonly initialMs: number\n  readonly factor: number\n  readonly maxMs: number\n  readonly maxAttempts?: number | undefined\n  readonly expirationMs?: number | undefined\n  readonly jitterRatio?: number | undefined\n  readonly nonRetryable?: ReadonlyArray<string> | undefined\n}): RetryPolicy => {\n  const issue = validationIssue(options)\n  if (issue !== undefined) throw new RangeError(`RetryPolicy.make: ${issue}`)\n  return Object.freeze({\n    initialMs: options.initialMs,\n    factor: options.factor,\n    maxMs: options.maxMs,\n    ...(options.maxAttempts !== undefined ? { maxAttempts: options.maxAttempts } : {}),\n    ...(options.expirationMs !== undefined ? { expirationMs: options.expirationMs } : {}),\n    ...(options.jitterRatio !== undefined ? { jitterRatio: options.jitterRatio } : {}),\n    ...(options.nonRetryable !== undefined\n      ? { nonRetryable: Object.freeze([...options.nonRetryable]) }\n      : {})\n  })\n}\n\n/**\n * The default engine retry policy.\n *\n * Uses a 200ms initial delay growing by 1.5x, capped at 30s, and never gives\n * up: it declares neither `maxAttempts` nor `expirationMs`. Bound long-lived\n * retries with `make({ ..., expirationMs })` when a wall-clock give-up is\n * required.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const defaultRetryPolicy: RetryPolicy = Object.freeze(\n  make({\n    initialMs: 200,\n    factor: 1.5,\n    maxMs: 30000\n  })\n)\n\n/**\n * Bounded infrastructure retry: 5 seconds doubling to 5 minutes, for 2 hours.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const transient: RetryPolicy = make({\n  initialMs: 5000,\n  factor: 2,\n  maxMs: 300000,\n  expirationMs: 7200000\n})\n\n/**\n * A retry decision: wait `delayMs` before the next attempt.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface RetryAfter {\n  readonly _tag: \"RetryAfter\"\n  readonly delayMs: number\n}\n\n/**\n * A retry decision: stop retrying.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface GiveUp {\n  readonly _tag: \"GiveUp\"\n  readonly reason: \"nonRetryable\" | \"exhausted\" | \"expired\"\n}\n\n/**\n * The outcome of the engine's retry decision point.\n *\n * @category models\n * @since 0.1.0\n */\nexport type RetryDecision = RetryAfter | GiveUp\n\n/**\n * Creates a `RetryAfter` decision.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const retryAfter = (delayMs: number): RetryDecision => ({\n  _tag: \"RetryAfter\",\n  delayMs\n})\n\n/**\n * Creates a `GiveUp` decision.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const giveUp = (reason: GiveUp[\"reason\"]): RetryDecision => ({\n  _tag: \"GiveUp\",\n  reason\n})\n\n/**\n * A historical retry sequence crossed its `expirationMs` wall-clock bound.\n * Current dispatch preserves the final declared failure instead of emitting this defect.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class RetryPolicyExpired extends Schema.TaggedError<RetryPolicyExpired>()(\n  \"@smthrs/flow/RetryPolicyExpired\",\n  {\n    code: Schema.Literal(\"retry_policy_expired\").pipe(\n      Schema.withConstructorDefault(Effect.succeed(\"retry_policy_expired\"))\n    ),\n    actionName: Schema.String,\n    attempt: Schema.Number,\n    expirationMs: Schema.Number,\n    lastError: Schema.optional(Schema.Unknown)\n  }\n) {}\n\n/**\n * A historical retry sequence exhausted its `maxAttempts` bound.\n * Current dispatch preserves the final declared failure instead of emitting this defect.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class RetryAttemptsExhausted extends Schema.TaggedError<RetryAttemptsExhausted>()(\n  \"@smthrs/flow/RetryAttemptsExhausted\",\n  {\n    code: Schema.Literal(\"retry_attempts_exhausted\").pipe(\n      Schema.withConstructorDefault(Effect.succeed(\"retry_attempts_exhausted\"))\n    ),\n    actionName: Schema.String,\n    attempt: Schema.Number,\n    maxAttempts: Schema.Number,\n    lastError: Schema.optional(Schema.Unknown)\n  }\n) {}\n\n/**\n * Computes the delay before attempt `attempt + 1` from the persisted attempt\n * count, mirroring Temporal's `ComputeNextDelay`\n * (`common/backoff/retrypolicy.go`).\n *\n * `attempt` is the 1-based attempt that just failed. Returns `None` when the\n * policy gives up: `maxAttempts` reached, a non-positive computed interval,\n * a cap below the initial interval, or — when the policy declares\n * `expirationMs` and the caller supplies `elapsedMs` — an elapsed duration\n * past the expiration bound. Otherwise the delay is capped to the remaining\n * expiration window, expiring only when that window cannot fit one more\n * full-value (`initialMs`) attempt.\n *\n * Jitter is deterministic-friendly: `options.random` is a `[0, 1]` sample\n * supplied by the caller and defaults to `1`, which leaves the delay at its\n * un-jittered value. Use {@link nextDelayEffect} to sample the `Random`\n * service instead. A sample outside `[0, 1]`, or a persisted `jitterRatio`\n * above one, gives up rather than returning a delay the policy never\n * declared. A sample of zero under `jitterRatio: 1` is a delay of zero, which\n * retries immediately.\n *\n * @category attempts\n * @since 0.1.0\n */\nexport const nextDelay = (\n  policy: RetryPolicy,\n  attempt: number,\n  options?: {\n    readonly random?: number | undefined\n    readonly elapsedMs?: number | undefined\n  }\n): Option.Option<number> => {\n  // Persisted policies can be decoded without `make`, so these guards treat a\n  // corrupt row as terminal instead of sending an invalid delay to the engine.\n  if (validationIssue(policy) !== undefined || !Number.isSafeInteger(attempt) || attempt < 1) {\n    return Option.none()\n  }\n  if (\n    options?.elapsedMs !== undefined &&\n    (!Number.isFinite(options.elapsedMs) || options.elapsedMs < 0)\n  ) {\n    return Option.none()\n  }\n  if (policy.maxAttempts !== undefined && attempt >= policy.maxAttempts) {\n    return Option.none()\n  }\n  if (\n    policy.expirationMs !== undefined &&\n    options?.elapsedMs !== undefined &&\n    options.elapsedMs > policy.expirationMs\n  ) {\n    return Option.none()\n  }\n  const raw = policy.initialMs * Math.pow(policy.factor, attempt - 1)\n  if (!(raw > 0)) {\n    return Option.none()\n  }\n  let delay = Math.min(raw, policy.maxMs)\n  // Temporal caps the delay to the remaining expiration window rather than\n  // refusing outright; the below-initial check then expires sequences whose\n  // remaining window cannot fit one more full-value attempt.\n  if (policy.expirationMs !== undefined && options?.elapsedMs !== undefined) {\n    delay = Math.min(delay, Math.max(0, policy.expirationMs - options.elapsedMs))\n  }\n  if (delay < policy.initialMs) {\n    return Option.none()\n  }\n  // `validationIssue` established finite `maxMs`, so `Math.min` made the\n  // un-jittered delay finite even when the exponential itself overflowed.\n  // This check belongs before jitter conceptually: a full-jitter sample of\n  // zero is a legitimate immediate retry rather than a give-up.\n  if (policy.jitterRatio !== undefined && policy.jitterRatio > 0) {\n    // Both jitter inputs are bounded to [0, 1] where they are accepted --\n    // `make` for `jitterRatio` and this function's contract for `random` --\n    // while `random` is a public option that still needs checking here.\n    const random = options?.random ?? 1\n    if (!(random >= 0 && random <= 1)) {\n      return Option.none()\n    }\n    // In range, the result is between `delay * (1 - jitterRatio)` and `delay`,\n    // so it is finite and never negative. A jittered value of zero retries\n    // immediately; it does not exhaust the sequence.\n    //\n    // The two terms do not sum to exactly `delay` at `random: 1`: at\n    // `jitterRatio: 0.000002` a delay of 100 rounds up to 100.00000000000001,\n    // above the policy's own cap and above the remaining expiration window.\n    // Clamping down to the un-jittered delay is what makes the upper bound\n    // stated above exact rather than approximate.\n    const jittered = delay * (1 - policy.jitterRatio) + random * delay * policy.jitterRatio\n    delay = Math.min(delay, jittered)\n  }\n  return Option.some(delay)\n}\n\n/**\n * Computes the next retry delay, sampling the `Random` service for jitter.\n *\n * Deterministic under `Random.withSeed`. Policies without a `jitterRatio`\n * never touch the service.\n *\n * @category attempts\n * @since 0.1.0\n */\nexport const nextDelayEffect = (\n  policy: RetryPolicy,\n  attempt: number,\n  options?: { readonly elapsedMs?: number | undefined }\n): Effect.Effect<Option.Option<number>> =>\n  policy.jitterRatio === undefined || policy.jitterRatio <= 0\n    ? Effect.sync(() => nextDelay(policy, attempt, { elapsedMs: options?.elapsedMs }))\n    : Effect.map(Random.next, (random) => nextDelay(policy, attempt, { random, elapsedMs: options?.elapsedMs }))\n\n/**\n * Extracts the stable identity tag of an error for non-retryable matching:\n * an own string `_tag` when present, otherwise the first own `name` descriptor\n * found while walking a bounded prototype chain. That first descriptor decides\n * the result: only a string data value is a tag.\n *\n * Descriptors keep accessors inert instead of running author code through a\n * property read. A bounded walk also terminates when a hostile proxy reports a\n * cyclic prototype chain; any proxy trap that throws leaves the error untagged.\n *\n * @category attempts\n * @since 0.1.0\n */\nexport const errorTag = (error: unknown): string | undefined => {\n  if (typeof error !== \"object\" || error === null) return undefined\n  try {\n    const tag = Object.getOwnPropertyDescriptor(error, \"_tag\")\n    if (tag !== undefined && \"value\" in tag && typeof tag.value === \"string\") return tag.value\n\n    let current: object | null = error\n    for (let depth = 0; current !== null && depth < 64; depth++) {\n      const name = Object.getOwnPropertyDescriptor(current, \"name\")\n      if (name !== undefined) {\n        return \"value\" in name && typeof name.value === \"string\" ? name.value : undefined\n      }\n      current = Object.getPrototypeOf(current)\n    }\n  } catch {\n    // Proxies and hostile accessors are untrusted failure payloads. An error\n    // that cannot be inspected inertly simply has no stable retry tag.\n  }\n  return undefined\n}\n\n/**\n * Error tags that are non-retryable by type, under every policy (issue #156).\n *\n * These failures are integrity verdicts that must reach the driver without an\n * action-level retry hiding the first detection. Their persistence seams\n * take a quarantine state action before raising them, so a later dispatch can\n * heal, but the detecting dispatch remains a non-retryable failure. No\n * per-callsite or per-policy opt-out exists; the tags are matched by string so\n * the classification does not invert the package dependency direction.\n *\n * `AttemptEvidenceQuarantined` (issue #171) is the succeeded-attempt-row\n * counterpart: the corrupt boundary evidence is removed while the completed\n * outcome stays durable. It reaches the driver unretried, which parks the\n * first detection in the `quarantine` waiting state; the next explicit resume\n * returns the recorded outcome without re-executing the action.\n *\n * @category attempts\n * @since 0.1.0\n */\nexport const defaultNonRetryable: ReadonlyArray<string> = [\n  \"@smthrs/engine-store/CacheCorruptionDetected\",\n  \"@smthrs/engine-store/AttemptEvidenceQuarantined\"\n]\n\n/**\n * Whether an error is classified non-retryable, either by type (see\n * {@link defaultNonRetryable}) or by the policy's declared tag list.\n *\n * @category attempts\n * @since 0.1.0\n */\nexport const isNonRetryable = (policy: RetryPolicy, error: unknown): boolean => {\n  const tag = errorTag(error)\n  if (tag === undefined) {\n    return false\n  }\n  if (defaultNonRetryable.includes(tag)) {\n    return true\n  }\n  return policy.nonRetryable !== undefined && policy.nonRetryable.includes(tag)\n}\n\n/**\n * The pure core of the engine's single retry decision point.\n *\n * Non-retryable classification is evaluated here and nowhere else. This is\n * the default a pluggable `resolveRetry` resolution falls back to when no\n * plugin claims the decision.\n *\n * @category attempts\n * @since 0.1.0\n */\nexport const decide = (\n  policy: RetryPolicy,\n  options: {\n    readonly attempt: number\n    readonly error: unknown\n    readonly random?: number | undefined\n    readonly elapsedMs?: number | undefined\n  }\n): RetryDecision => {\n  if (isNonRetryable(policy, options.error)) {\n    return giveUp(\"nonRetryable\")\n  }\n  return Option.match(\n    nextDelay(policy, options.attempt, { random: options.random, elapsedMs: options.elapsedMs }),\n    {\n      onNone: () =>\n        // A policy can report `expired` only when it declares an expiration\n        // bound and dropping elapsed time would have allowed another attempt.\n        // A malformed elapsed value still gives up because the sequence cannot\n        // continue without a trustworthy clock reading; without an expiration\n        // bound, the public terminal reason for that refusal is `exhausted`.\n        policy.expirationMs !== undefined &&\n          Option.isSome(nextDelay(policy, options.attempt, { random: options.random }))\n          ? giveUp(\"expired\")\n          : giveUp(\"exhausted\"),\n      onSome: (delay) => {\n        // Tool failures may supply a delay instead of using policy backoff.\n        // Inspect only an own data property: failure payloads can be untrusted.\n        let hint: unknown\n        if (typeof options.error === \"object\" && options.error !== null) {\n          try {\n            const descriptor = Object.getOwnPropertyDescriptor(options.error, \"retryAfterMs\")\n            if (descriptor !== undefined && \"value\" in descriptor) hint = descriptor.value\n          } catch {\n            // An uninspectable failure falls back to the policy delay.\n          }\n        }\n        if (typeof hint !== \"number\" || !Number.isFinite(hint) || hint < 0) {\n          return retryAfter(delay)\n        }\n        return retryAfter(Math.min(\n          hint,\n          policy.maxMs,\n          policy.expirationMs !== undefined && options.elapsedMs !== undefined\n            ? Math.max(0, policy.expirationMs - options.elapsedMs)\n            : policy.maxMs\n        ))\n      }\n    }\n  )\n}\n\n/**\n * Effect form of {@link decide}, sampling the `Random` service for jitter.\n *\n * This is the engine-facing decision function: keep calls to it behind a\n * single decision point so a plugin hook dispatch can later be inserted in\n * front of it without touching call sites.\n *\n * @category attempts\n * @since 0.1.0\n */\nexport const decideEffect = (\n  policy: RetryPolicy,\n  options: {\n    readonly attempt: number\n    readonly error: unknown\n    readonly elapsedMs?: number | undefined\n  }\n): Effect.Effect<RetryDecision> =>\n  policy.jitterRatio === undefined || policy.jitterRatio <= 0\n    ? Effect.sync(() => decide(policy, options))\n    : Effect.map(Random.next, (random) => decide(policy, { ...options, random }))\n"]}

package/dist/esm/Sleep.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The system timer, as an ordinary declared action.
+ *
+ * `docs/concepts/flows-and-actions.md` names the timer primitive a
+ * gap and says how to close it: ship it over the existing `DurableClock`, so a
+ * wait is a visible, keyed plan node rather than a second execution mechanism.
+ * That is this module. {@link action} is a plain `Action.make` declaration —
+ * it appears in a catalog, `.call()` records a node, and `Graph.build` puts that
+ * node in the plan beside every other step — and {@link layer} is the
+ * implementation the hosts that can run a timer provide.
+ *
+ * The wait itself is `DurableClock`'s, not a new one. The implementation arms
+ * the durable clock and awaits its deferred, which is what parks the execution;
+ * the park is declared through the ordinary waiting vocabulary
+ * ({@link module:WaitingAnnotation.annotateWaiting}) under `timer`, with the
+ * deadline as `wakeAt`, so a durable driver records the same waiting row it
+ * records for a hand-written `DurableClock.sleep`. Replay is the deferred's:
+ * once the clock has fired, its result is persisted, so a re-driven round reads
+ * it and runs straight through instead of parking a second time.
+ *
+ * Which clock a wait arms is the dispatch's own, read from
+ * {@link module:Context.CurrentInvocationKey}: a keyed node already owns an
+ * identity that survives replay and separates two identical calls, so the timer
+ * inherits it rather than being addressed by the payload it was called with.
+ *
+ * @since 0.1.0
+ */
+import type * as Crypto from "effect/Crypto";
+import type * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Action from "./Action/index.ts";
+import type { FlowRuntime } from "./FlowRuntime/FlowRuntime.ts";
+declare const SleepRequestInvalid_base: Schema.Class<SleepRequestInvalid, Schema.TaggedStruct<"@smthrs/flow/SleepRequestInvalid", {
+    readonly code: Schema.Literals<readonly ["missing_deadline", "ambiguous_deadline", "invalid_deadline"]>;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A sleep whose payload does not name exactly one deadline.
+ *
+ * A payload carries a relative `millis` or an absolute `until`, and naming
+ * both, or neither, leaves no deadline to arm a clock with. It is a typed
+ * failure rather than a defect because the payload of a driven node is
+ * assembled from plan values, so an author's mistake is recoverable through
+ * `Node.catch` like any other declared failure.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class SleepRequestInvalid extends SleepRequestInvalid_base {
+}
+/**
+ * The tag the sleep declaration is catalogued and resolved under.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const tag = "system/sleep";
+/**
+ * The declared sleep action: `millis` from now, or an absolute `until`.
+ *
+ * **When to use**
+ *
+ * Use it in a body wherever a round has to wait for time to pass —
+ * `Sleep.action.call({ millis: 60_000 })` — rather than reaching for
+ * `DurableClock.sleep`, which is only callable from a handler and leaves
+ * nothing in the plan. A sleep node is keyed, inspectable, and skippable by a
+ * branch exactly like an action that does work.
+ *
+ * Two waits of the same length are two waits: `sleep(1h)` followed by
+ * `sleep(1h)` sleeps for two hours, because each call is its own node with its
+ * own identity, exactly as two calls of any other declaration are.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const action: Action.Declared<typeof tag, Schema.Struct<{
+    readonly millis: Schema.optional<Schema.Number>;
+    readonly until: Schema.optional<Schema.Number>;
+}>, typeof Schema.Void, typeof SleepRequestInvalid, never>;
+/**
+ * The sleep implementation: arm the durable clock, park under `timer`, wake.
+ *
+ * Provide it beside the other action implementation layers a body calls, over
+ * the {@link module:Implementations.layerImplementations} table they file
+ * themselves in:
+ *
+ * ```ts
+ * Layer.mergeAll(Sleep.layer, Interpreter.layer(Pipeline)).pipe(
+ *   Layer.provideMerge(Action.layerImplementations)
+ * )
+ * ```
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<never, never, Crypto.Crypto | FlowRuntime>;
+export {};
+//# sourceMappingURL=Sleep.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Sleep.d.ts","sourceRoot":"","sources":["../../src/Sleep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAG5C,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAA;AAE3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAA;;;;;AAG/D;;;;;;;;;;;GAWG;AACH,qBAAa,mBAAoB,SAAQ,wBAMxC;CAAG;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,GAAG,iBAAiB,CAAA;AAEjC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,QAAQ,CAClC,OAAO,GAAG,EACV,MAAM,CAAC,MAAM,CAAC;IACZ,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;CAC/C,CAAC,EACF,OAAO,MAAM,CAAC,IAAI,EAClB,OAAO,mBAAmB,EAC1B,KAAK,CASL,CAAA;AA0IF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,GAAG,WAAW,CAuCxE,CAAA"}