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

package/dist/esm/Poll.js

@@ -0,0 +1,289 @@
+/**
+ * Polling as a durable lineage: one attempt per round, a durable wait between
+ * attempts, and a bound the lineage settles on.
+ *
+ * Smithers 0.x had a `Poller` component — a check, an interval, a backoff, an
+ * attempt bound, and what to do at that bound. The pieces it was built from
+ * already exist here: {@link module:Sleep.action} is the durable wait, and
+ * `Flow.to` opens the next round. What was missing is the shape that puts them
+ * together, and that is this module.
+ *
+ * A poll is a flow whose body is ONE attempt. It runs the check, and branches:
+ * a satisfied check settles the lineage with the check's own output, an
+ * unsatisfied one sleeps for this attempt's delay and hands off to the next
+ * round with the attempt counter raised. The last attempt has no sleep and no
+ * handoff — it either answers with the output it just read (`return-last`) or
+ * fails {@link PollExhausted} (`fail`).
+ *
+ * Everything durable about it is durable for the ordinary reason. Each attempt
+ * is a round with its own keyed plan nodes, so a check that already ran replays
+ * from its recorded outcome instead of running again; the wait between attempts
+ * is a durable timer, so a process that dies during it resumes on the round it
+ * left rather than starting the poll over; and the attempt counter travels in
+ * the payload, so nothing about "which attempt is this" lives in memory.
+ *
+ * The bound is stated twice on purpose. The body ends the lineage on the last
+ * attempt, and `maxAttempts` is also the flow's `maxRounds` budget, so a
+ * lineage that somehow opened another round is refused by the engine rather
+ * than polling forever.
+ *
+ * @since 0.1.0
+ */
+import * as Node from "@smthrs/plan/Node";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Action from "./Action/index.js";
+import * as Flow from "./Flow/index.js";
+import * as Sleep from "./Sleep.js";
+/**
+ * The success schema a check action declares.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const CheckResult = (result) => Schema.Struct({ satisfied: Schema.Boolean, output: result });
+/**
+ * A poll that used its last attempt without a satisfied check.
+ *
+ * It is a typed failure rather than a defect: running out of attempts is an
+ * expected outcome of polling something that may never become ready, so a
+ * caller recovers from it through `Node.catch` like any other declared failure.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class PollExhausted extends Schema.TaggedError()("@smthrs/flow/PollExhausted", {
+    // This wire shape freezes at 1.0.0-rc.0.
+    code: Schema.Literal("poll_exhausted").pipe(Schema.withConstructorDefault(Effect.succeed("poll_exhausted"))),
+    poll: Schema.String,
+    attempts: Schema.Number,
+    message: Schema.String
+}) {
+}
+/**
+ * The tag the exhaustion step is catalogued and resolved under.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const exhaustedTag = "system/poll-exhausted";
+/**
+ * The declared step a poll takes when its last attempt was not satisfied.
+ *
+ * Running out of attempts is a step rather than a bare `Effect.fail` so the
+ * exhaustion is in the plan and in the journal: the round that gave up shows
+ * which poll gave up and after how many attempts, exactly like every other node
+ * a body drove.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const exhausted = Action.makeSystem(exhaustedTag, {
+    payload: { poll: Schema.String, attempts: Schema.Number },
+    success: Schema.Never,
+    error: PollExhausted,
+    tier: "sealed"
+});
+/**
+ * The wait before the attempt after this one, in milliseconds.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export const delayMillis = (options) => 
+// A zero interval is zero under every backoff. Multiplying it by a factor
+// that has overflowed to `Infinity` would make it `NaN`.
+options.intervalMs === 0 ? 0 : options.intervalMs *
+    (options.backoff === "fixed" ? 1 : options.backoff === "linear" ? options.attempt : 2 ** (options.attempt - 1));
+/**
+ * What a poll round can fail with.
+ *
+ * {@link PollExhausted} is the poll's own failure. `SleepRequestInvalid` is the
+ * wait node's, declared because the wait between attempts is an ordinary
+ * {@link module:Sleep.action} node and its typed refusal is part of the
+ * topology a poll carries. Its codes cover a payload that names no deadline,
+ * names two deadlines, or names a value that is not a deadline. {@link make}
+ * refuses invalid author schedules at construction. A caller-visible round
+ * payload can still carry an invalid attempt that produces an invalid derived
+ * wait, so `Sleep` refuses that wait before the round parks.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Failure = Schema.Union([PollExhausted, Sleep.SleepRequestInvalid]);
+/**
+ * The payload schema one round is opened with: the author's fields, plus the
+ * attempt counter the lineage carries between them.
+ *
+ * @private
+ */
+const payloadSchema = (input, maxAttempts) => Schema.Struct({
+    ...input,
+    attempt: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1), Schema.isLessThanOrEqualTo(maxAttempts)))
+});
+/**
+ * The attempt a round payload carries, defaulting to the first.
+ *
+ * @private
+ */
+const attemptOf = (payload) => {
+    const attempt = payload.attempt;
+    return typeof attempt === "number" ? attempt : 1;
+};
+/**
+ * Rebuilds a round payload with an explicit attempt.
+ *
+ * The two views of one round payload — what the check reads, and what the next
+ * round is opened with — are the same fields with `attempt` resolved. TypeScript
+ * cannot reduce a mapped type over an unresolved generic field set, so the
+ * shape is stated once here instead of at each use.
+ *
+ * @private
+ */
+const withAttempt = (payload, attempt) => ({ ...payload, attempt });
+/**
+ * Declares a durable poller.
+ *
+ * **When to use**
+ *
+ * Use it wherever a run has to keep asking until something is ready — a build
+ * that finishes, a deployment that goes live, a review that lands — and the
+ * waiting has to survive a restart. `check` is the one thing an author writes:
+ * a body fragment that reads whatever it polls and reports a {@link Check}.
+ * Everything else is schedule. Under stable callback admission (the default of
+ * `Interpreter.layerWithImplementations`), wrap `check` in `Node.capture` with
+ * every semantic capture, including a version for imported behavior. An
+ * uncaptured check keeps the poll process-local. The helper captures its own
+ * callbacks using the schedule and the check's identity.
+ *
+ * ```ts
+ * const Deployment = Poll.make("deploy/wait", {
+ *   input: { id: Schema.String },
+ *   result: Schema.String,
+ *   intervalMs: 5_000,
+ *   backoff: "exponential",
+ *   maxAttempts: 8,
+ *   onTimeout: "fail",
+ *   check: Node.capture(
+ *     { action: Status.name, implementationVersion: "deploy/status-check/v1" },
+ *     ({ attempt, id }) => Status.call({ attempt, id })
+ *   )
+ * })
+ * ```
+ *
+ * The check may not fail. A check that can fail states what a failure means for
+ * the poll — give up, or treat it as "not ready yet" — with `Node.catch` inside
+ * the fragment, rather than leaving the poll to guess.
+ *
+ * A per-attempt time limit on the check itself is NOT a poll option. A plan
+ * node's duration is not something the body around it can bound; that bound
+ * belongs in the check's own implementation, where `DurableDeferred.raceAll`
+ * races the work against a durable clock and stays replayable.
+ *
+ * A schedule no clock can be armed with is refused here, with a `RangeError`
+ * naming the option that is wrong. `intervalMs` becomes the `millis` of a
+ * {@link module:Sleep.action} node, and a wait of `Infinity`, `NaN`, or a
+ * negative length arms a timer that never fires — a poll that hangs forever
+ * with a plan that looks correct. The check is on the schedule, not only on the
+ * interval: `{ intervalMs: 1000, maxAttempts: 2000, backoff: "exponential" }`
+ * states three finite options and asks for an infinite wait, so the LAST wait
+ * the poll can arm has to be a length too, and no longer than
+ * `Number.MAX_SAFE_INTEGER` milliseconds, the latest deadline a durable timer
+ * records. `maxAttempts` is the lineage's round
+ * budget, and a budget below one attempt reaches `Flow.make` as a `maxRounds`
+ * complaint about an option the author never wrote.
+ *
+ * @throws A `RangeError` when `intervalMs` is not a duration a clock accepts,
+ * when `maxAttempts` is not a whole number of attempts of at least one, or when
+ * the interval under the declared backoff reaches a wait no clock can be armed
+ * with before the budget is spent.
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (tag, options) => {
+    if (Object.prototype.hasOwnProperty.call(options.input, "attempt")) {
+        throw new TypeError(`Poll.make: "${tag}" input cannot declare the reserved "attempt" field. ` +
+            "Poll owns that counter across durable rounds.");
+    }
+    const input = Object.freeze({ ...options.input });
+    const result = options.result;
+    const check = options.check;
+    const intervalMs = options.intervalMs;
+    const maxAttempts = options.maxAttempts;
+    if (!Number.isFinite(intervalMs) || intervalMs < 0) {
+        throw new RangeError(`Poll.make: "${tag}" intervalMs must be a finite number of milliseconds that is not negative, ` +
+            `and was ${intervalMs}. The interval is the length of a durable wait, and a wait of ` +
+            "that length never ends.");
+    }
+    if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1) {
+        throw new RangeError(`Poll.make: "${tag}" maxAttempts must be a whole number of attempts of at least one, and was ` +
+            `${maxAttempts}. A poll checks at least once.`);
+    }
+    const backoff = options.backoff ?? "fixed";
+    // The wait a poll arms is not `intervalMs`. {@link delayMillis} multiplies it
+    // by the backoff, so a schedule whose options are each finite can still ask
+    // for a wait that is not a length — and that wait arms the same timer that
+    // never fires the interval guard above exists to refuse. The last wait is the
+    // one before the final attempt, because the attempt at the budget gives up
+    // rather than sleeps, and the schedule never shrinks, so the last wait is
+    // also the longest: checking it checks all of them.
+    const longestWaitMs = maxAttempts > 1
+        ? delayMillis({ intervalMs, backoff, attempt: maxAttempts - 1 })
+        : 0;
+    // A durable timer records its deadline as a safe integer of milliseconds,
+    // so `Sleep` refuses a longer wait on the round that reaches it.
+    if (!Number.isFinite(longestWaitMs) || longestWaitMs > Number.MAX_SAFE_INTEGER) {
+        throw new RangeError(`Poll.make: "${tag}" asks for a wait of ${longestWaitMs} ms before its last attempt. An ` +
+            `intervalMs of ${intervalMs} under the "${backoff}" backoff reaches a length no clock ` +
+            `can be armed with by attempt ${maxAttempts - 1} of ${maxAttempts}. Lower ` +
+            "maxAttempts, shorten the interval, or slow the backoff.");
+    }
+    const onTimeout = options.onTimeout ?? "fail";
+    const captures = { tag, intervalMs, backoff, maxAttempts, onTimeout, check: Node.functionIdentity(check) };
+    const body = (payload) => {
+        const attempt = attemptOf(payload);
+        const last = attempt >= maxAttempts;
+        return check(withAttempt(payload, attempt)).pipe(Node.branch({
+            if: Node.capture(captures, (checked) => checked.satisfied),
+            then: (checked) => Flow.done(checked.output),
+            else: (checked) => last
+                ? onTimeout === "return-last"
+                    ? Flow.done(checked.output)
+                    : exhausted.call({ poll: tag, attempts: attempt })
+                : Sleep.action.call({
+                    millis: delayMillis({ intervalMs, backoff, attempt })
+                }).pipe(Node.andThen(self.to(withAttempt(payload, attempt + 1))))
+        }));
+    };
+    // The body names the flow it is the body of, which is what makes one round
+    // open the next. It is read when a round is planned, long after `Flow.make`
+    // has returned, so the binding is initialized by then.
+    const self = Flow.make(tag, {
+        payload: payloadSchema(input, maxAttempts),
+        success: result,
+        error: Failure,
+        maxRounds: maxAttempts,
+        // A captured wrapper must not admit a process-local check as stable.
+        body: captures.check.algorithm === "sha256-source-ephemeral/v4" ? body : Node.capture(captures, body)
+    });
+    return self;
+};
+/**
+ * The exhaustion implementation, provided beside the other action layers a
+ * poll's rounds call.
+ *
+ * ```ts
+ * Layer.mergeAll(Poll.layer, Sleep.layer, Interpreter.layer(Deployment)).pipe(
+ *   Layer.provideMerge(Action.layerImplementations)
+ * )
+ * ```
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = exhausted.toLayer(({ attempts, poll }) => Effect.fail(new PollExhausted({
+    poll,
+    attempts,
+    message: `Poll "${poll}" used all ${attempts} attempts without a satisfied check.`
+})));
+//# sourceMappingURL=Poll.js.map

package/dist/esm/Poll.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Poll.js","sourceRoot":"","sources":["../../src/Poll.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Polling as a durable lineage: one attempt per round, a durable wait between\n * attempts, and a bound the lineage settles on.\n *\n * Smithers 0.x had a `Poller` component — a check, an interval, a backoff, an\n * attempt bound, and what to do at that bound. The pieces it was built from\n * already exist here: {@link module:Sleep.action} is the durable wait, and\n * `Flow.to` opens the next round. What was missing is the shape that puts them\n * together, and that is this module.\n *\n * A poll is a flow whose body is ONE attempt. It runs the check, and branches:\n * a satisfied check settles the lineage with the check's own output, an\n * unsatisfied one sleeps for this attempt's delay and hands off to the next\n * round with the attempt counter raised. The last attempt has no sleep and no\n * handoff — it either answers with the output it just read (`return-last`) or\n * fails {@link PollExhausted} (`fail`).\n *\n * Everything durable about it is durable for the ordinary reason. Each attempt\n * is a round with its own keyed plan nodes, so a check that already ran replays\n * from its recorded outcome instead of running again; the wait between attempts\n * is a durable timer, so a process that dies during it resumes on the round it\n * left rather than starting the poll over; and the attempt counter travels in\n * the payload, so nothing about \"which attempt is this\" lives in memory.\n *\n * The bound is stated twice on purpose. The body ends the lineage on the last\n * attempt, and `maxAttempts` is also the flow's `maxRounds` budget, so a\n * lineage that somehow opened another round is refused by the engine rather\n * than polling forever.\n *\n * @since 0.1.0\n */\n\nimport * as Node from \"@smthrs/plan/Node\"\nimport type * as Repetition from \"@smthrs/plan/Repetition\"\nimport type * as Crypto from \"effect/Crypto\"\nimport * as Effect from \"effect/Effect\"\nimport type * as Layer from \"effect/Layer\"\nimport * as Schema from \"effect/Schema\"\nimport * as Action from \"./Action/index.ts\"\nimport * as Flow from \"./Flow/index.ts\"\nimport type { FlowRuntime } from \"./FlowRuntime/FlowRuntime.ts\"\nimport * as Sleep from \"./Sleep.ts\"\n\n/**\n * How the wait between attempts grows.\n *\n * `fixed` waits the interval every time, `linear` waits the interval times the\n * attempt, and `exponential` doubles the interval on every attempt.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Backoff = \"fixed\" | \"linear\" | \"exponential\"\n\n/**\n * What a check reports: whether the poll is over, and the value this attempt\n * read.\n *\n * The output travels on every attempt, satisfied or not, because it is also\n * the answer a `return-last` poll settles with when it runs out of attempts.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Check<out Result> {\n  readonly satisfied: boolean\n  readonly output: Result\n}\n\n/**\n * The success schema a check action declares.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const CheckResult = <Result extends Schema.Top>(\n  result: Result\n): Schema.Struct<{\n  readonly satisfied: typeof Schema.Boolean\n  readonly output: Result\n}> => Schema.Struct({ satisfied: Schema.Boolean, output: result })\n\n/**\n * A poll that used its last attempt without a satisfied check.\n *\n * It is a typed failure rather than a defect: running out of attempts is an\n * expected outcome of polling something that may never become ready, so a\n * caller recovers from it through `Node.catch` like any other declared failure.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class PollExhausted extends Schema.TaggedError<PollExhausted>()(\n  \"@smthrs/flow/PollExhausted\",\n  {\n    // This wire shape freezes at 1.0.0-rc.0.\n    code: Schema.Literal(\"poll_exhausted\").pipe(\n      Schema.withConstructorDefault(Effect.succeed(\"poll_exhausted\"))\n    ),\n    poll: Schema.String,\n    attempts: Schema.Number,\n    message: Schema.String\n  }\n) {}\n\n/**\n * The tag the exhaustion step is catalogued and resolved under.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const exhaustedTag = \"system/poll-exhausted\"\n\n/**\n * The declared step a poll takes when its last attempt was not satisfied.\n *\n * Running out of attempts is a step rather than a bare `Effect.fail` so the\n * exhaustion is in the plan and in the journal: the round that gave up shows\n * which poll gave up and after how many attempts, exactly like every other node\n * a body drove.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const exhausted: Action.Declared<\n  typeof exhaustedTag,\n  Schema.Struct<{\n    readonly poll: typeof Schema.String\n    readonly attempts: typeof Schema.Number\n  }>,\n  typeof Schema.Never,\n  typeof PollExhausted,\n  never\n> = Action.makeSystem(exhaustedTag, {\n  payload: { poll: Schema.String, attempts: Schema.Number },\n  success: Schema.Never,\n  error: PollExhausted,\n  tier: \"sealed\"\n})\n\n/**\n * The wait before the attempt after this one, in milliseconds.\n *\n * @category combinators\n * @since 0.1.0\n */\nexport const delayMillis = (options: {\n  readonly intervalMs: number\n  readonly backoff: Backoff\n  readonly attempt: number\n}): number =>\n  // A zero interval is zero under every backoff. Multiplying it by a factor\n  // that has overflowed to `Infinity` would make it `NaN`.\n  options.intervalMs === 0 ? 0 : options.intervalMs *\n    (options.backoff === \"fixed\" ? 1 : options.backoff === \"linear\" ? options.attempt : 2 ** (options.attempt - 1))\n\n/**\n * What a poll round can fail with.\n *\n * {@link PollExhausted} is the poll's own failure. `SleepRequestInvalid` is the\n * wait node's, declared because the wait between attempts is an ordinary\n * {@link module:Sleep.action} node and its typed refusal is part of the\n * topology a poll carries. Its codes cover a payload that names no deadline,\n * names two deadlines, or names a value that is not a deadline. {@link make}\n * refuses invalid author schedules at construction. A caller-visible round\n * payload can still carry an invalid attempt that produces an invalid derived\n * wait, so `Sleep` refuses that wait before the round parks.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const Failure: Schema.Union<\n  readonly [typeof PollExhausted, typeof Sleep.SleepRequestInvalid]\n> = Schema.Union([PollExhausted, Sleep.SleepRequestInvalid])\n\n/**\n * The payload schema {@link make} derives from an author's input fields: the\n * author's own fields, plus the attempt this round is.\n *\n * `attempt` is optional so a caller starts a poll with its own fields alone;\n * the first round reads it as one.\n *\n * @category models\n * @since 0.1.0\n */\nexport type PayloadSchema<Input extends Schema.Struct.Fields> = Schema.Struct<\n  Input & { readonly attempt: Schema.optional<typeof Schema.Number> }\n>\n\n/**\n * The payload schema one round is opened with: the author's fields, plus the\n * attempt counter the lineage carries between them.\n *\n * @private\n */\nconst payloadSchema = <Input extends Schema.Struct.Fields>(\n  input: Input,\n  maxAttempts: number\n): PayloadSchema<Input> =>\n  Schema.Struct({\n    ...input,\n    attempt: Schema.optional(\n      Schema.Int.check(\n        Schema.isGreaterThanOrEqualTo(1),\n        Schema.isLessThanOrEqualTo(maxAttempts)\n      )\n    )\n  })\n\n/**\n * The attempt a round payload carries, defaulting to the first.\n *\n * @private\n */\nconst attemptOf = (payload: object): number => {\n  const attempt = (payload as { readonly attempt?: unknown }).attempt\n  return typeof attempt === \"number\" ? attempt : 1\n}\n\n/**\n * Rebuilds a round payload with an explicit attempt.\n *\n * The two views of one round payload — what the check reads, and what the next\n * round is opened with — are the same fields with `attempt` resolved. TypeScript\n * cannot reduce a mapped type over an unresolved generic field set, so the\n * shape is stated once here instead of at each use.\n *\n * @private\n */\nconst withAttempt = <Payload>(payload: object, attempt: number): Payload =>\n  ({ ...payload, attempt }) as unknown as Payload\n\n/**\n * Declares a durable poller.\n *\n * **When to use**\n *\n * Use it wherever a run has to keep asking until something is ready — a build\n * that finishes, a deployment that goes live, a review that lands — and the\n * waiting has to survive a restart. `check` is the one thing an author writes:\n * a body fragment that reads whatever it polls and reports a {@link Check}.\n * Everything else is schedule. Under stable callback admission (the default of\n * `Interpreter.layerWithImplementations`), wrap `check` in `Node.capture` with\n * every semantic capture, including a version for imported behavior. An\n * uncaptured check keeps the poll process-local. The helper captures its own\n * callbacks using the schedule and the check's identity.\n *\n * ```ts\n * const Deployment = Poll.make(\"deploy/wait\", {\n *   input: { id: Schema.String },\n *   result: Schema.String,\n *   intervalMs: 5_000,\n *   backoff: \"exponential\",\n *   maxAttempts: 8,\n *   onTimeout: \"fail\",\n *   check: Node.capture(\n *     { action: Status.name, implementationVersion: \"deploy/status-check/v1\" },\n *     ({ attempt, id }) => Status.call({ attempt, id })\n *   )\n * })\n * ```\n *\n * The check may not fail. A check that can fail states what a failure means for\n * the poll — give up, or treat it as \"not ready yet\" — with `Node.catch` inside\n * the fragment, rather than leaving the poll to guess.\n *\n * A per-attempt time limit on the check itself is NOT a poll option. A plan\n * node's duration is not something the body around it can bound; that bound\n * belongs in the check's own implementation, where `DurableDeferred.raceAll`\n * races the work against a durable clock and stays replayable.\n *\n * A schedule no clock can be armed with is refused here, with a `RangeError`\n * naming the option that is wrong. `intervalMs` becomes the `millis` of a\n * {@link module:Sleep.action} node, and a wait of `Infinity`, `NaN`, or a\n * negative length arms a timer that never fires — a poll that hangs forever\n * with a plan that looks correct. The check is on the schedule, not only on the\n * interval: `{ intervalMs: 1000, maxAttempts: 2000, backoff: \"exponential\" }`\n * states three finite options and asks for an infinite wait, so the LAST wait\n * the poll can arm has to be a length too, and no longer than\n * `Number.MAX_SAFE_INTEGER` milliseconds, the latest deadline a durable timer\n * records. `maxAttempts` is the lineage's round\n * budget, and a budget below one attempt reaches `Flow.make` as a `maxRounds`\n * complaint about an option the author never wrote.\n *\n * @throws A `RangeError` when `intervalMs` is not a duration a clock accepts,\n * when `maxAttempts` is not a whole number of attempts of at least one, or when\n * the interval under the declared backoff reaches a wait no clock can be armed\n * with before the budget is spent.\n * @category constructors\n * @since 0.1.0\n */\nexport const make = <\n  const Tag extends string,\n  Input extends Schema.Struct.Fields,\n  Result extends Schema.Top,\n  R = never\n>(\n  tag: Tag,\n  options: {\n    readonly input: Input\n    readonly result: Result\n    readonly check: (\n      payload: Schema.Struct.Type<Input> & { readonly attempt: number }\n    ) => Node.Node<Check<Result[\"Type\"]>, never, R>\n    readonly intervalMs: number\n    readonly maxAttempts: number\n    readonly backoff?: Backoff | undefined\n    readonly onTimeout?: Repetition.AtCeiling | undefined\n  }\n): Flow.Flow<Tag, PayloadSchema<Input>, Result, typeof Failure, R> => {\n  type Round = Flow.Flow<Tag, PayloadSchema<Input>, Result, typeof Failure, R>\n  type RoundPayload = PayloadSchema<Input>[\"Type\"]\n  if (Object.prototype.hasOwnProperty.call(options.input, \"attempt\")) {\n    throw new TypeError(\n      `Poll.make: \"${tag}\" input cannot declare the reserved \"attempt\" field. ` +\n        \"Poll owns that counter across durable rounds.\"\n    )\n  }\n  const input = Object.freeze({ ...options.input }) as Input\n  const result = options.result\n  const check = options.check\n  const intervalMs = options.intervalMs\n  const maxAttempts = options.maxAttempts\n  if (!Number.isFinite(intervalMs) || intervalMs < 0) {\n    throw new RangeError(\n      `Poll.make: \"${tag}\" intervalMs must be a finite number of milliseconds that is not negative, ` +\n        `and was ${intervalMs}. The interval is the length of a durable wait, and a wait of ` +\n        \"that length never ends.\"\n    )\n  }\n  if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1) {\n    throw new RangeError(\n      `Poll.make: \"${tag}\" maxAttempts must be a whole number of attempts of at least one, and was ` +\n        `${maxAttempts}. A poll checks at least once.`\n    )\n  }\n  const backoff = options.backoff ?? \"fixed\"\n  // The wait a poll arms is not `intervalMs`. {@link delayMillis} multiplies it\n  // by the backoff, so a schedule whose options are each finite can still ask\n  // for a wait that is not a length — and that wait arms the same timer that\n  // never fires the interval guard above exists to refuse. The last wait is the\n  // one before the final attempt, because the attempt at the budget gives up\n  // rather than sleeps, and the schedule never shrinks, so the last wait is\n  // also the longest: checking it checks all of them.\n  const longestWaitMs = maxAttempts > 1\n    ? delayMillis({ intervalMs, backoff, attempt: maxAttempts - 1 })\n    : 0\n  // A durable timer records its deadline as a safe integer of milliseconds,\n  // so `Sleep` refuses a longer wait on the round that reaches it.\n  if (!Number.isFinite(longestWaitMs) || longestWaitMs > Number.MAX_SAFE_INTEGER) {\n    throw new RangeError(\n      `Poll.make: \"${tag}\" asks for a wait of ${longestWaitMs} ms before its last attempt. An ` +\n        `intervalMs of ${intervalMs} under the \"${backoff}\" backoff reaches a length no clock ` +\n        `can be armed with by attempt ${maxAttempts - 1} of ${maxAttempts}. Lower ` +\n        \"maxAttempts, shorten the interval, or slow the backoff.\"\n    )\n  }\n  const onTimeout = options.onTimeout ?? \"fail\"\n  const captures = { tag, intervalMs, backoff, maxAttempts, onTimeout, check: Node.functionIdentity(check) }\n  const body = (\n    payload: RoundPayload\n  ): Node.Node<Flow.BodySuccess<Result[\"Type\"]>, typeof Failure.Type, R> => {\n    const attempt = attemptOf(payload)\n    const last = attempt >= maxAttempts\n    return check(withAttempt(payload, attempt)).pipe(\n      Node.branch({\n        if: Node.capture(captures, (checked) => checked.satisfied),\n        then: (checked) => Flow.done(checked.output),\n        else: (checked): Node.Node<Flow.BodySuccess<Result[\"Type\"]>, typeof Failure.Type> =>\n          last\n            ? onTimeout === \"return-last\"\n              ? Flow.done(checked.output)\n              : exhausted.call({ poll: tag, attempts: attempt })\n            : Sleep.action.call({\n              millis: delayMillis({ intervalMs, backoff, attempt })\n            }).pipe(\n              Node.andThen(\n                self.to(withAttempt<Parameters<Round[\"to\"]>[0]>(payload, attempt + 1))\n              )\n            )\n      })\n    )\n  }\n  // The body names the flow it is the body of, which is what makes one round\n  // open the next. It is read when a round is planned, long after `Flow.make`\n  // has returned, so the binding is initialized by then.\n  const self: Round = Flow.make(tag, {\n    payload: payloadSchema(input, maxAttempts),\n    success: result,\n    error: Failure,\n    maxRounds: maxAttempts,\n    // A captured wrapper must not admit a process-local check as stable.\n    body: captures.check.algorithm === \"sha256-source-ephemeral/v4\" ? body : Node.capture(captures, body)\n  })\n  return self\n}\n\n/**\n * The exhaustion implementation, provided beside the other action layers a\n * poll's rounds call.\n *\n * ```ts\n * Layer.mergeAll(Poll.layer, Sleep.layer, Interpreter.layer(Deployment)).pipe(\n *   Layer.provideMerge(Action.layerImplementations)\n * )\n * ```\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer: Layer.Layer<never, never, Crypto.Crypto | FlowRuntime> = exhausted.toLayer(\n  ({ attempts, poll }) =>\n    Effect.fail(\n      new PollExhausted({\n        poll,\n        attempts,\n        message: `Poll \"${poll}\" used all ${attempts} attempts without a satisfied check.`\n      })\n    )\n)\n"]}

package/dist/esm/RetryPolicy.d.ts

@@ -0,0 +1,273 @@
+/**
+ * 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 Schema from "effect/Schema";
+/**
+ * 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 declare const RetryPolicy: Schema.Struct<{
+    readonly initialMs: Schema.Number;
+    readonly factor: Schema.Number;
+    readonly maxMs: Schema.Number;
+    readonly maxAttempts: Schema.optional<Schema.Number>;
+    readonly expirationMs: Schema.optional<Schema.Number>;
+    readonly jitterRatio: Schema.optional<Schema.Number>;
+    readonly nonRetryable: Schema.optional<Schema.$Array<Schema.String>>;
+}>;
+/**
+ * The value form of a {@link RetryPolicy}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type RetryPolicy = typeof RetryPolicy.Type;
+/**
+ * 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 declare const make: (options: {
+    readonly initialMs: number;
+    readonly factor: number;
+    readonly maxMs: number;
+    readonly maxAttempts?: number | undefined;
+    readonly expirationMs?: number | undefined;
+    readonly jitterRatio?: number | undefined;
+    readonly nonRetryable?: ReadonlyArray<string> | undefined;
+}) => RetryPolicy;
+/**
+ * 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 declare const defaultRetryPolicy: RetryPolicy;
+/**
+ * Bounded infrastructure retry: 5 seconds doubling to 5 minutes, for 2 hours.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const transient: RetryPolicy;
+/**
+ * A retry decision: wait `delayMs` before the next attempt.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface RetryAfter {
+    readonly _tag: "RetryAfter";
+    readonly delayMs: number;
+}
+/**
+ * A retry decision: stop retrying.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface GiveUp {
+    readonly _tag: "GiveUp";
+    readonly reason: "nonRetryable" | "exhausted" | "expired";
+}
+/**
+ * The outcome of the engine's retry decision point.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type RetryDecision = RetryAfter | GiveUp;
+/**
+ * Creates a `RetryAfter` decision.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const retryAfter: (delayMs: number) => RetryDecision;
+/**
+ * Creates a `GiveUp` decision.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const giveUp: (reason: GiveUp["reason"]) => RetryDecision;
+declare const RetryPolicyExpired_base: Schema.Class<RetryPolicyExpired, Schema.TaggedStruct<"@smthrs/flow/RetryPolicyExpired", {
+    readonly code: Schema.withConstructorDefault<Schema.Literal<"retry_policy_expired">>;
+    readonly actionName: Schema.String;
+    readonly attempt: Schema.Number;
+    readonly expirationMs: Schema.Number;
+    readonly lastError: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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 declare class RetryPolicyExpired extends RetryPolicyExpired_base {
+}
+declare const RetryAttemptsExhausted_base: Schema.Class<RetryAttemptsExhausted, Schema.TaggedStruct<"@smthrs/flow/RetryAttemptsExhausted", {
+    readonly code: Schema.withConstructorDefault<Schema.Literal<"retry_attempts_exhausted">>;
+    readonly actionName: Schema.String;
+    readonly attempt: Schema.Number;
+    readonly maxAttempts: Schema.Number;
+    readonly lastError: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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 declare class RetryAttemptsExhausted extends RetryAttemptsExhausted_base {
+}
+/**
+ * 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 declare const nextDelay: (policy: RetryPolicy, attempt: number, options?: {
+    readonly random?: number | undefined;
+    readonly elapsedMs?: number | undefined;
+}) => Option.Option<number>;
+/**
+ * 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 declare const nextDelayEffect: (policy: RetryPolicy, attempt: number, options?: {
+    readonly elapsedMs?: number | undefined;
+}) => Effect.Effect<Option.Option<number>>;
+/**
+ * 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 declare const errorTag: (error: unknown) => string | 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 declare const defaultNonRetryable: ReadonlyArray<string>;
+/**
+ * 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 declare const isNonRetryable: (policy: RetryPolicy, error: unknown) => boolean;
+/**
+ * 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 declare const decide: (policy: RetryPolicy, options: {
+    readonly attempt: number;
+    readonly error: unknown;
+    readonly random?: number | undefined;
+    readonly elapsedMs?: number | undefined;
+}) => RetryDecision;
+/**
+ * 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 declare const decideEffect: (policy: RetryPolicy, options: {
+    readonly attempt: number;
+    readonly error: unknown;
+    readonly elapsedMs?: number | undefined;
+}) => Effect.Effect<RetryDecision>;
+export {};
+//# sourceMappingURL=RetryPolicy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RetryPolicy.d.ts","sourceRoot":"","sources":["../../src/RetryPolicy.ts"],"names":[],"mappings":"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"}