@voltro/workflow 0.25.0 → 0.26.0

package/dist/clusterTestSuite.d.ts

@@ -116,6 +116,40 @@ declare interface WorkflowEngineLayerOptions {
     readonly shardLockMode?: ShardLockMode;
     readonly runnerListenHost?: string;
     readonly runnerListenPort?: number;
+    /**
+     * FAILOVER TUNING — the two knobs that govern how fast a SURVIVING replica
+     * takes over a CRASHED replica's in-flight workflows. Reclaim is a
+     * lease-expiry problem, NOT a polling one: a dead runner keeps its shards
+     * until its heartbeat goes stale, so the floor is the lease TTL.
+     *
+     * - `failoverLeaseSeconds` (default 35, `@effect/cluster`
+     *   `shardLockExpiration`) — how long after a runner's last heartbeat its
+     *   shards become claimable. Lower = faster failover on a hard crash, at the
+     *   cost of false-positive reclaims if a healthy runner is paused longer than
+     *   this by a GC pause or a DB-latency spike (two runners could then briefly
+     *   both think they own a shard).
+     * - `failoverHeartbeatSeconds` (default 10, `shardLockRefreshInterval`) — how
+     *   often a runner refreshes its lease + heartbeat. Keep it well below the
+     *   lease (≈ lease/3) so a single slow refresh doesn't trip a false reclaim.
+     *
+     * Omit both for production defaults. A push wake (LISTEN/NOTIFY) does NOT help
+     * here — reclaim is time-bound, not notification-bound; only these two (or a
+     * K8s liveness probe) move the floor.
+     */
+    readonly failoverLeaseSeconds?: number;
+    readonly failoverHeartbeatSeconds?: number;
+    /**
+     * NEW-MESSAGE latency across replicas (default 10, `@effect/cluster`
+     * `entityMessagePollInterval`). DISTINCT from failover: this is how long a
+     * freshly-triggered workflow can wait before the replica that OWNS its shard
+     * picks it up. When the triggering replica owns the shard it's immediate
+     * (a same-process push); when ANOTHER replica owns it, Voltro's single-runner
+     * topology has no cross-runner push, so the owner sees it on its next poll —
+     * up to this interval. Lower it for latency-sensitive multi-replica workloads,
+     * at the cost of more idle poll queries. (The lower-load fix is a pg
+     * LISTEN/NOTIFY wake, not yet wired.) No effect on a single replica.
+     */
+    readonly messagePollSeconds?: number;
     /**
      * Extra layers that need the cluster's `Sharding` service — most
      * prominently `ClusterCron` layers for `cluster`-coordinated

package/dist/clusterTestSuite.js

@@ -1,6 +1,6 @@
-import { C as e, m as t, p as n, v as r, x as i } from "./primitives-CWy1iu5w.js";
-import { i as a } from "./src-DQww25rP.js";
-import { c as o, t as s } from "./cluster-DuFweKq0.js";
+import { C as e, m as t, p as n, v as r, x as i } from "./primitives-Dgu3O55Q.js";
+import { i as a } from "./src-KDx7NTsa.js";
+import { f as o, r as s } from "./cluster-BQ0H5M9n.js";
 import { Cron as c, Deferred as l, Effect as u, Fiber as d, Layer as f, Schema as p } from "effect";
 import { SqlClient as m } from "@effect/sql";
 import { beforeAll as h, describe as g, expect as _, test as v } from "vitest";
@@ -33,14 +33,14 @@ var y = async (e, t, n = 750) => {
 			for (let t of b) yield* e.unsafe(`DELETE FROM ${t}`).pipe(u.ignore);
 		}).pipe(u.scoped, u.provide(e.sqlClientLayer)));
 	} catch {}
-}, S = (e, t) => u.gen(function* () {
+}, S = "10 seconds", C = "30 seconds", w = (e, t) => u.gen(function* () {
 	let n = yield* u.sync(() => Date.now() + t);
 	for (; !e();) {
 		if (Date.now() > n) return !1;
 		yield* u.sleep("250 millis");
 	}
 	return !0;
-}), C = (m) => {
+}), T = (m) => {
 	let y = `${m.name}-${Date.now()}`, b = (e, t) => o({
 		sqlClientLayer: m.sqlClientLayer,
 		runnerStorage: m.runnerStorage,
@@ -104,7 +104,9 @@ var y = async (e, t, n = 750) => {
 			_(await u.runPromise(u.scoped(u.gen(function* () {
 				return yield* f.build(b(m.runnerPort + 1, [n])), yield* l.await(e).pipe(u.timeout("25 seconds"), u.orElseSucceed(() => !1));
 			})))).toBe(!0), _(t).toBeGreaterThanOrEqual(1);
-		}, 35e3), v.runIf(m.clusterResume)("a sleeping workflow resumes on a fresh runner after the first is torn down", async () => {
+		}, 35e3);
+		let g = m.clusterResume ? v : (() => {});
+		g("a sleeping workflow resumes on a fresh runner after the first is torn down", async () => {
 			if (!o) return;
 			let e = `dormancyResume_${y}`, i = [], a = [], s = [], c = () => r({
 				name: e,
@@ -126,7 +128,7 @@ var y = async (e, t, n = 750) => {
 					})
 				}), yield* n({
 					name: "nap",
-					duration: "30 seconds"
+					duration: S
 				}), yield* t({
 					name: "step2",
 					success: p.Void,
@@ -142,13 +144,13 @@ var y = async (e, t, n = 750) => {
 				};
 			}, v = { id: `resume-${y}` }, x = await u.runPromise(u.scoped(u.gen(function* () {
 				let { wf: e, layer: t } = g("A"), n = yield* f.build(t), r = yield* u.forkDaemon(e.execute(v).pipe(u.provide(n), u.ignore));
-				return (yield* S(() => s.length > 0, 6e4)) ? r : yield* u.die(/* @__PURE__ */ Error("runner A never journaled step1"));
+				return (yield* w(() => s.length > 0, 6e4)) ? r : yield* u.die(/* @__PURE__ */ Error("runner A never journaled step1"));
 			})));
 			await u.runPromise(d.interrupt(x).pipe(u.ignore)), _(i).toEqual(["A"]), _(a).toEqual([]), _(await u.runPromise(u.scoped(u.gen(function* () {
 				let { wf: e, layer: t } = g("B"), n = yield* f.build(t);
 				return yield* e.execute(v).pipe(u.provide(n), u.timeout("240 seconds"), u.orElseSucceed(() => "TIMEOUT"));
 			})))).toBe("done"), _(i).toEqual(["A"]), _(a).toEqual(["B"]);
-		}, 48e4), v.runIf(m.clusterResume)("dormancy loop: a wake signal survives teardown and is cleared on resume", async () => {
+		}, 48e4), g("dormancy loop: a wake signal survives teardown and is cleared on resume", async () => {
 			if (!o) return;
 			let s = `dormancyLoop_${y}`, c = `wr_${s}`, l = [], h = /* @__PURE__ */ new Map(), g = a({
 				store: {
@@ -176,7 +178,7 @@ var y = async (e, t, n = 750) => {
 					execute: u.void
 				}), yield* n({
 					name: "nap",
-					duration: "30 seconds"
+					duration: C
 				}), yield* t({
 					name: "step2",
 					success: p.Void,
@@ -184,22 +186,22 @@ var y = async (e, t, n = 750) => {
 						l.push(a);
 					})
 				}), "done";
-			}).pipe(u.locally(i, c), u.provideService(e, g))), C = m.runnerPort + 2, w = (e) => {
+			}).pipe(u.locally(i, c), u.provideService(e, g))), S = m.runnerPort + 2, T = (e) => {
 				let t = v();
 				return {
 					wf: t,
-					layer: x(t, e).pipe(f.provideMerge(b(C)))
+					layer: x(t, e).pipe(f.provideMerge(b(S)))
 				};
-			}, T = { id: `loop-${y}` }, E = await u.runPromise(u.scoped(u.gen(function* () {
-				let { wf: e, layer: t } = w("A"), n = yield* f.build(t), r = yield* u.forkDaemon(e.execute(T).pipe(u.provide(n), u.ignore));
-				return (yield* S(() => h.has(c), 6e4)) ? (yield* u.sleep("1 second"), r) : yield* u.die(/* @__PURE__ */ Error("workflow never registered a wakeup"));
+			}, E = { id: `loop-${y}` }, D = await u.runPromise(u.scoped(u.gen(function* () {
+				let { wf: e, layer: t } = T("A"), n = yield* f.build(t), r = yield* u.forkDaemon(e.execute(E).pipe(u.provide(n), u.ignore));
+				return (yield* w(() => h.has(c), 6e4)) ? (yield* u.sleep("1 second"), r) : yield* u.die(/* @__PURE__ */ Error("workflow never registered a wakeup"));
 			})));
-			await u.runPromise(d.interrupt(E).pipe(u.ignore)), _(h.has(c)).toBe(!0), _(l).toEqual([]), _(await u.runPromise(u.scoped(u.gen(function* () {
-				let { wf: e, layer: t } = w("B"), n = yield* f.build(t);
-				return yield* e.execute(T).pipe(u.provide(n), u.timeout("240 seconds"), u.orElseSucceed(() => "TIMEOUT"));
+			await u.runPromise(d.interrupt(D).pipe(u.ignore)), _(h.has(c)).toBe(!0), _(l).toEqual([]), _(await u.runPromise(u.scoped(u.gen(function* () {
+				let { wf: e, layer: t } = T("B"), n = yield* f.build(t);
+				return yield* e.execute(E).pipe(u.provide(n), u.timeout("600 seconds"), u.orElseSucceed(() => "TIMEOUT"));
 			})))).toBe("done"), _(l).toEqual(["B"]), _(h.has(c)).toBe(!1);
-		}, 48e4);
+		}, 9e5);
 	});
 };
 //#endregion
-export { C as runClusterEngineSuite, y as tcpReachable };
+export { T as runClusterEngineSuite, y as tcpReachable };

package/dist/index.d.ts

@@ -426,42 +426,58 @@ declare type StepOptions<R, Success extends Schema.Schema.Any, Error extends Sch
     /** Structured value recorded into `_voltro_workflow_run_steps.input`.
      *  Pass whatever makes the step debuggable in isolation. */
     readonly input?: unknown;
-    /** Declarative retry-policy summary recorded into
-     *  `_voltro_workflow_run_steps.retryPolicy`. Pure metadata — does
-     *  NOT change retry behavior on its own. Wire actual retries via
-     *  `Effect.retry` inside `execute:` or via `interruptRetryPolicy`
-     *  above; this field tells the dashboard what the intended policy
-     *  looks like so the per-attempt panel can show "attempt 2 of 5,
-     *  exponential 1s base" instead of just "attempt 2". */
+    /** Declarative retry policy — ENFORCED. The framework compiles it to an
+     *  Effect `Schedule` and retries `execute` accordingly (backoff, jitter,
+     *  attempt cap, time budget, error classification, provider `Retry-After`).
+     *  See {@link StepRetryPolicy}. Retries run INSIDE this one step and are
+     *  transparent to the durable engine; the step's FINAL outcome is recorded.
+     *  The serialisable knobs are also stored as `_voltro_workflow_run_steps.
+     *  retryPolicy` for the dashboard. `retry: { maxAttempts: 5 }` is enough. */
     readonly retry?: StepRetryPolicy;
 };
 
 /**
- * Declarative retry-policy summary. Pure metadata for the dashboard;
- * the framework does NOT apply this. Users wire actual retry behavior
- * via `Effect.retry(Schedule.*)` inside `execute:` or
- * `Activity.make`'s `interruptRetryPolicy`.
- *
- * Shape is intentionally close to Effect's Schedule combinators so a
- * future framework version can auto-translate declarative policies
- * into a Schedule + apply it. For now: record + display.
- *
- *   { strategy: 'exponential', maxAttempts: 5, baseDelay: '1 second', maxDelay: '30 seconds' }
- *   { strategy: 'fixed',       maxAttempts: 3, baseDelay: '500 millis' }
- *   { strategy: 'linear',      maxAttempts: 4, baseDelay: '1 second',  step: '2 seconds' }
+ * A step's retry policy. Every field is optional — `retry: {}` is already a
+ * sensible policy (3 attempts, exponential backoff, jittered). All fields are
+ * JSON-serialisable EXCEPT `retryable` (a predicate), which the recorder drops
+ * when it stores the policy as dashboard metadata.
  */
 export declare interface StepRetryPolicy {
-    readonly strategy: 'exponential' | 'fixed' | 'linear';
-    readonly maxAttempts: number;
-    /** Effect Duration string, e.g. `'1 second'`, `'500 millis'`. */
+    /** Total attempts INCLUDING the first. Default `3`. `1` disables retry. */
+    readonly maxAttempts?: number;
+    /** Backoff shape between attempts. Default `'exponential'`. */
+    readonly strategy?: 'exponential' | 'fixed' | 'linear';
+    /** First delay (Effect Duration string, e.g. `'500 millis'`). Default `'200 millis'`. */
     readonly baseDelay?: string;
-    /** Cap on exponential / linear growth, e.g. `'30 seconds'`. */
-    readonly maxDelay?: string;
-    /** Increment for `linear` strategy. */
+    /** Growth factor for `'exponential'`. Default `2`. */
+    readonly factor?: number;
+    /** Increment per attempt for `'linear'`. Default = `baseDelay`. */
     readonly step?: string;
-    /** Free-form note rendered as a chip in the dashboard. Useful when
-     *  the retry behavior is partially implemented in the user's
-     *  Effect chain and the summary is just documentation. */
+    /** Ceiling on any single delay, so exponential growth can't run away
+     *  (e.g. `'30 seconds'`). Applied before jitter. */
+    readonly maxDelay?: string;
+    /** Full jitter on each delay — spreads retries so a fleet doesn't
+     *  re-hit a recovering dependency in lockstep. Default `true`. */
+    readonly jitter?: boolean;
+    /** A total wall-clock BUDGET across all attempts: stop retrying once
+     *  this much time has elapsed since the first attempt, even if attempts
+     *  remain (e.g. `'5 minutes'`). A deadline, not a count. */
+    readonly maxElapsed?: string;
+    /** Retry ONLY failures whose typed-error `_tag` is in this list; every
+     *  other error fails fast. The declarative "retry transient, fail
+     *  permanent" — e.g. `['ProviderDown', 'RateLimited']`. */
+    readonly retryableErrors?: ReadonlyArray<string>;
+    /** Retry-predicate on the raw error (wins over `retryableErrors` when
+     *  both are set). Not serialised into dashboard metadata. Default:
+     *  retry every failure. */
+    readonly retryable?: (error: unknown) => boolean;
+    /** Honor a provider's own backoff: if a retryable error carries a
+     *  `retryAfterMillis` number (or `retryAfter` in seconds), use exactly that as
+     *  the delay before the next attempt — REPLACING the computed backoff for
+     *  that attempt (a 429 `Retry-After`, say). Falls back to the normal backoff
+     *  when the error carries no hint. Default `false`. */
+    readonly respectRetryAfter?: boolean;
+    /** Free-form note rendered as a chip in the dashboard. */
     readonly note?: string;
 }
 
@@ -637,7 +653,13 @@ export declare interface WorkflowResolvedRun {
  * open-text on purpose (future phases add new types without a column
  * migration) — but at emit time we still want type-safety.
  */
-export declare type WorkflowRunEventType = 'run-started' | 'run-suspended' | 'run-resumed' | 'run-cancelled' | 'run-succeeded' | 'run-failed'
+export declare type WorkflowRunEventType = 'run-started' | 'run-suspended' | 'run-resumed'
+/** Emitted when an operator re-drives a terminally-FAILED run from its
+*  durable journal (`voltro workflows redrive` / `ctx.workflows.redrive`).
+*  `payload` carries `{ reason, activitiesReset }` — how many failed step
+*  attempts were reset so they re-execute (completed steps replay). Distinct
+*  from `run-resumed`, which continues a *suspended* run. */
+| 'run-redriven' | 'run-cancelled' | 'run-succeeded' | 'run-failed'
 /** Emitted when `sleep({ name, duration })` enters the wait — `payload`
 *  carries `{ name, durationMs, scheduledWakeAt }`. The dashboard
 *  Gantt renders these as a hatched bar in the timeline so a
@@ -843,6 +865,25 @@ export declare interface WorkflowVersionOptions {
     readonly version?: string | number;
     readonly compatibleWith?: ReadonlyArray<string | number>;
     readonly patches?: ReadonlyArray<string>;
+    /**
+     * When `true`, a workflow whose top-level body FAILS does not become a
+     * terminal `failed` run — it **suspends** with its durable journal intact, so
+     * `voltro workflows resume <id>` (or `ctx.workflows.resume`) re-drives it from
+     * the point of failure: every completed activity replays from the journal
+     * (NOT re-executed) and only the failed activity runs again. This is the
+     * durable-execution way to make a workflow recoverable across a transient
+     * downstream outage without re-doing prior work.
+     *
+     * Default `false` — a failure is terminal (the dead-letter state; see
+     * `voltro workflows list --dead-letter`). Choose per workflow: `true` for a
+     * long multi-step pipeline where re-doing step 1..N-1 is expensive or unsafe;
+     * `false` for a short idempotent job where a fresh `retry` is simpler. A
+     * suspended-on-failure run shows up under `--status suspended`, NOT in the
+     * dead-letter view — it is recoverable, not dead.
+     *
+     * Maps to `@effect/workflow`'s `SuspendOnFailure` annotation.
+     */
+    readonly suspendOnFailure?: boolean;
 }
 
 export declare const WorkflowVersionTypeId: unique symbol;

package/dist/index.js

@@ -1,3 +1,3 @@
-import { C as e, E as t, T as n, _ as r, a as i, b as a, c as o, d as s, f as c, g as l, h as u, i as d, l as f, m as p, n as m, o as h, p as g, r as _, s as v, t as y, u as b, v as x, w as S, x as C, y as w } from "./primitives-CWy1iu5w.js";
-import { _ as T, a as E, b as D, c as O, d as k, f as A, g as j, h as M, i as N, l as P, m as F, n as I, o as L, p as R, r as z, s as B, t as V, u as H, v as U, x as W, y as G } from "./src-DQww25rP.js";
+import { C as e, E as t, T as n, _ as r, a as i, b as a, c as o, d as s, f as c, g as l, h as u, i as d, l as f, m as p, n as m, o as h, p as g, r as _, s as v, t as y, u as b, v as x, w as S, x as C, y as w } from "./primitives-Dgu3O55Q.js";
+import { _ as T, a as E, b as D, c as O, d as k, f as A, g as j, h as M, i as N, l as P, m as F, n as I, o as L, p as R, r as z, s as B, t as V, u as H, v as U, x as W, y as G } from "./src-KDx7NTsa.js";
 export { a as CurrentWorkflowExecutionId, C as CurrentWorkflowRunId, y as WorkflowMessagesProperty, e as WorkflowRunRecorder, S as WorkflowStepInterceptorTag, m as WorkflowVersionTypeId, _ as WorkflowWorkerLayerTypeId, U as _voltroWorkflowRunEventsTable, G as _voltroWorkflowRunStepsTable, D as _voltroWorkflowRunsTable, T as _voltroWorkflowStartContextsTable, j as awaitSignal, P as awaitSignalSuspending, O as awaitUpdate, z as closeWorkflowChildrenForParent, H as completeSuspendingSignal, d as durableClock, i as durableQueue, h as durableQueueModule, v as durableRateLimiterModule, n as getCurrentWorkflowExecutionId, t as getCurrentWorkflowRunId, o as getWorkflowVersionMetadata, W as inMemoryWorkflowEngineLayer, I as inspectWorkflow, f as isWorkflowWorkerLayer, V as makeInMemoryRecorder, N as makeWorkflowRunRecorder, A as makeWorkflowUpdateId, b as processQueue, s as queueWorker, c as rateLimit, R as resolveWorkflowMessageRun, F as sendWorkflowSignal, M as sendWorkflowUpdate, E as serialiseWorkflowRowForWire, g as sleep, p as step, u as stepIdempotencyKey, l as stepModule, k as suspendingSignalDeferredName, L as truncateWorkflowValue, r as withCompensation, x as workflow, w as workflowModule, B as wrapWorkflowExecuteWithRunRecording };

package/dist/primitives-Dgu3O55Q.js

@@ -0,0 +1,164 @@
+import { Activity as e, Activity as t, DurableClock as n, DurableClock as r, DurableQueue as i, DurableQueue as a, DurableRateLimiter as o, DurableRateLimiter as s, Workflow as c, Workflow as l } from "@effect/workflow";
+import { Cause as u, Context as d, Duration as f, Effect as p, Exit as m, FiberRef as h, Option as g, Schedule as _ } from "effect";
+//#region src/recorder.ts
+var v = class extends d.Tag("@voltro/WorkflowRunRecorder")() {}, y = h.unsafeMake(void 0), b = h.unsafeMake(void 0), x = h.unsafeMake(void 0), S = () => h.get(y), C = () => h.get(b), w = class extends d.Tag("@voltro/WorkflowStepInterceptor")() {}, T = (e) => {
+	if (typeof e != "object" || !e) return;
+	let t = e.retryAfterMillis;
+	if (typeof t == "number" && Number.isFinite(t) && t >= 0) return f.millis(t);
+	let n = e.retryAfter;
+	if (typeof n == "number" && Number.isFinite(n) && n >= 0) return f.seconds(n);
+}, E = (e) => f.decode(e), D = (e) => typeof e == "object" && e && "_tag" in e ? String(e._tag) : void 0, O = (e) => e !== void 0 && (e.maxAttempts ?? 3) > 1, k = (e) => {
+	if (e.retryable) return e.retryable;
+	if (e.retryableErrors && e.retryableErrors.length > 0) {
+		let t = new Set(e.retryableErrors);
+		return (e) => {
+			let n = D(e);
+			return n !== void 0 && t.has(n);
+		};
+	}
+	return () => !0;
+}, A = (e) => {
+	let t = e.baseDelay ?? "200 millis", n = e.strategy ?? "exponential", r = e.maxAttempts ?? 3, i = n === "linear" ? _.linear(E(e.step ?? t)) : n === "fixed" ? _.spaced(E(t)) : _.exponential(E(t), e.factor ?? 2);
+	if (e.maxDelay !== void 0) {
+		let t = E(e.maxDelay);
+		i = _.modifyDelay(i, (e, n) => f.min(n, t));
+	}
+	(e.jitter ?? !0) === !0 && (i = _.jittered(i));
+	let a = _.intersect(i, _.recurs(Math.max(0, r - 1)));
+	return e.maxElapsed !== void 0 && (a = _.upTo(E(e.maxElapsed))(a)), a;
+}, j = (e, t) => {
+	let n = f.toMillis(E(e.baseDelay ?? "200 millis")), r = e.strategy ?? "exponential", i = r === "fixed" ? n : r === "linear" ? n + f.toMillis(E(e.step ?? e.baseDelay ?? "200 millis")) * (t - 1) : n * (e.factor ?? 2) ** (t - 1);
+	return e.maxDelay !== void 0 && (i = Math.min(i, f.toMillis(E(e.maxDelay)))), (e.jitter ?? !0) === !0 && (i *= Math.random()), i;
+}, M = (e, t, n, r) => p.gen(function* () {
+	let i = t.maxAttempts ?? 3, a = t.maxElapsed === void 0 ? Infinity : f.toMillis(E(t.maxElapsed)), o = yield* p.sync(() => Date.now()), s = 0;
+	for (;;) {
+		let c = yield* p.exit(e);
+		if (m.isSuccess(c)) return c.value;
+		let l = c.cause, d = u.failureOption(l), h = g.isSome(d) ? d.value : u.squash(l);
+		s += 1;
+		let _ = (yield* p.sync(() => Date.now())) - o;
+		if (s >= i || !n(h) || _ >= a) return yield* p.failCause(l);
+		r?.(h);
+		let v = T(h), y = v === void 0 ? j(t, s) : f.toMillis(v);
+		yield* p.sleep(f.millis(y));
+	}
+}), N = (e, t, n) => {
+	if (!O(t)) return e;
+	let r = k(t);
+	if (t.respectRetryAfter === !0) return M(e, t, r, n);
+	let i = A(t), a = n ? p.tapError(e, (e) => p.sync(() => {
+		r(e) && n(e);
+	})) : e;
+	return p.retry(a, {
+		schedule: i,
+		while: r
+	});
+}, P = Symbol.for("voltro.workflow.workerLayer"), F = Symbol.for("voltro.workflow.version"), I = "__voltroWorkflowMessages", L = (e) => typeof e == "object" && !!e && e[P] === !0, R = (e) => typeof e == "object" && e && e[F] !== void 0 ? e[F] : {
+	version: "1",
+	compatibleWith: ["1"],
+	patches: []
+}, z = ((e) => {
+	let t = c.make(e), n = e.suspendOnFailure === !0 ? t.annotate(c.SuspendOnFailure, !0) : t, r = String(e.version ?? "1"), i = {
+		version: r,
+		compatibleWith: (e.compatibleWith ?? [r]).map(String),
+		patches: [...e.patches ?? []]
+	}, a = {
+		signals: { ...e.messages?.signals ?? {} },
+		updates: { ...e.messages?.updates ?? {} },
+		queries: { ...e.messages?.queries ?? {} }
+	};
+	return Object.defineProperty(n, F, {
+		value: i,
+		enumerable: !1
+	}), Object.defineProperty(n, I, {
+		value: a,
+		enumerable: !1
+	}), n;
+}), B = i.make, V = i.process, H = ((...e) => {
+	let t = i.worker(...e);
+	return Object.defineProperty(t, P, {
+		value: !0,
+		enumerable: !1
+	}), t;
+}), U = o.rateLimit, W = (e) => p.gen(function* () {
+	let t = yield* y, r = yield* p.serviceOption(v), i = f.toMillis(f.decode(e.duration));
+	if (t !== void 0 && r._tag === "Some") {
+		let a = r.value, o = new Date(Date.now() + i).toISOString(), s = yield* x;
+		yield* p.promise(() => a.recordEvent({
+			runId: t,
+			eventType: "timer-set",
+			payload: {
+				name: e.name,
+				durationMs: i,
+				scheduledWakeAt: o,
+				...s === void 0 ? {} : { tenantId: s }
+			}
+		}).catch(() => {}));
+		let c = Date.now();
+		yield* n.sleep(e), yield* p.promise(() => a.recordEvent({
+			runId: t,
+			eventType: "timer-fired",
+			payload: {
+				name: e.name,
+				actualDurationMs: Date.now() - c,
+				...s === void 0 ? {} : { tenantId: s }
+			}
+		}).catch(() => {}));
+		return;
+	}
+	yield* n.sleep(e);
+}), G = (t, n, r, i) => p.gen(function* () {
+	let a = yield* y, o = yield* e.CurrentAttempt, s = yield* p.serviceOption(v), c = yield* p.serviceOption(w), l = c._tag === "Some" ? c.value.interceptor(n, {
+		runId: a ?? "unrecorded",
+		stepName: t,
+		attempt: o
+	}) : n, d, f;
+	if (a !== void 0 && s._tag === "Some") {
+		f = s.value;
+		let e = i === void 0 ? void 0 : (({ retryable: e, ...t }) => t)(i);
+		try {
+			d = yield* p.promise(() => f.startStep({
+				runId: a,
+				stepName: t,
+				attempt: o,
+				stepInput: r,
+				...e === void 0 ? {} : { retryPolicy: e }
+			}));
+		} catch {
+			d = void 0;
+		}
+	}
+	let m = Date.now();
+	return yield* N(l, i).pipe(p.tap((e) => d && f ? p.promise(async () => {
+		try {
+			await f.endStepSuccess({
+				stepRecordId: d,
+				output: e,
+				durationMs: Date.now() - m
+			});
+		} catch {}
+	}) : p.void), p.tapErrorCause((e) => d && f && !u.isInterruptedOnly(e) ? p.promise(async () => {
+		try {
+			let t = u.failureOption(e), n = Array.from(u.failures(e)), r = Array.from(u.defects(e)), i = t._tag === "Some" ? t.value : r[0] ?? u.squash(e), a = i?.message ?? String(i), o = i && typeof i == "object" && "_tag" in i ? String(i._tag) : null;
+			await f.endStepFailure({
+				stepRecordId: d,
+				errorTag: o,
+				errorMessage: a,
+				errorCause: {
+					pretty: u.pretty(e),
+					failures: n,
+					defects: r
+				},
+				durationMs: Date.now() - m
+			});
+		} catch {}
+	}) : p.void));
+}), K = (t) => {
+	let { input: n, retry: r, ...i } = t;
+	return e.make({
+		...i,
+		execute: G(i.name, i.execute, n, r)
+	});
+}, q = c.withCompensation, J = e.idempotencyKey;
+//#endregion
+export { v as C, S as E, x as S, C as T, q as _, B as a, b, R as c, H as d, U as f, t as g, J as h, r as i, L as l, K as m, F as n, a as o, W as p, P as r, s, I as t, V as u, z as v, w, y as x, l as y };

package/dist/primitives.d.ts

@@ -107,42 +107,58 @@ declare type StepOptions<R, Success extends Schema.Schema.Any, Error extends Sch
     /** Structured value recorded into `_voltro_workflow_run_steps.input`.
      *  Pass whatever makes the step debuggable in isolation. */
     readonly input?: unknown;
-    /** Declarative retry-policy summary recorded into
-     *  `_voltro_workflow_run_steps.retryPolicy`. Pure metadata — does
-     *  NOT change retry behavior on its own. Wire actual retries via
-     *  `Effect.retry` inside `execute:` or via `interruptRetryPolicy`
-     *  above; this field tells the dashboard what the intended policy
-     *  looks like so the per-attempt panel can show "attempt 2 of 5,
-     *  exponential 1s base" instead of just "attempt 2". */
+    /** Declarative retry policy — ENFORCED. The framework compiles it to an
+     *  Effect `Schedule` and retries `execute` accordingly (backoff, jitter,
+     *  attempt cap, time budget, error classification, provider `Retry-After`).
+     *  See {@link StepRetryPolicy}. Retries run INSIDE this one step and are
+     *  transparent to the durable engine; the step's FINAL outcome is recorded.
+     *  The serialisable knobs are also stored as `_voltro_workflow_run_steps.
+     *  retryPolicy` for the dashboard. `retry: { maxAttempts: 5 }` is enough. */
     readonly retry?: StepRetryPolicy;
 };
 
 /**
- * Declarative retry-policy summary. Pure metadata for the dashboard;
- * the framework does NOT apply this. Users wire actual retry behavior
- * via `Effect.retry(Schedule.*)` inside `execute:` or
- * `Activity.make`'s `interruptRetryPolicy`.
- *
- * Shape is intentionally close to Effect's Schedule combinators so a
- * future framework version can auto-translate declarative policies
- * into a Schedule + apply it. For now: record + display.
- *
- *   { strategy: 'exponential', maxAttempts: 5, baseDelay: '1 second', maxDelay: '30 seconds' }
- *   { strategy: 'fixed',       maxAttempts: 3, baseDelay: '500 millis' }
- *   { strategy: 'linear',      maxAttempts: 4, baseDelay: '1 second',  step: '2 seconds' }
+ * A step's retry policy. Every field is optional — `retry: {}` is already a
+ * sensible policy (3 attempts, exponential backoff, jittered). All fields are
+ * JSON-serialisable EXCEPT `retryable` (a predicate), which the recorder drops
+ * when it stores the policy as dashboard metadata.
  */
 declare interface StepRetryPolicy {
-    readonly strategy: 'exponential' | 'fixed' | 'linear';
-    readonly maxAttempts: number;
-    /** Effect Duration string, e.g. `'1 second'`, `'500 millis'`. */
+    /** Total attempts INCLUDING the first. Default `3`. `1` disables retry. */
+    readonly maxAttempts?: number;
+    /** Backoff shape between attempts. Default `'exponential'`. */
+    readonly strategy?: 'exponential' | 'fixed' | 'linear';
+    /** First delay (Effect Duration string, e.g. `'500 millis'`). Default `'200 millis'`. */
     readonly baseDelay?: string;
-    /** Cap on exponential / linear growth, e.g. `'30 seconds'`. */
-    readonly maxDelay?: string;
-    /** Increment for `linear` strategy. */
+    /** Growth factor for `'exponential'`. Default `2`. */
+    readonly factor?: number;
+    /** Increment per attempt for `'linear'`. Default = `baseDelay`. */
     readonly step?: string;
-    /** Free-form note rendered as a chip in the dashboard. Useful when
-     *  the retry behavior is partially implemented in the user's
-     *  Effect chain and the summary is just documentation. */
+    /** Ceiling on any single delay, so exponential growth can't run away
+     *  (e.g. `'30 seconds'`). Applied before jitter. */
+    readonly maxDelay?: string;
+    /** Full jitter on each delay — spreads retries so a fleet doesn't
+     *  re-hit a recovering dependency in lockstep. Default `true`. */
+    readonly jitter?: boolean;
+    /** A total wall-clock BUDGET across all attempts: stop retrying once
+     *  this much time has elapsed since the first attempt, even if attempts
+     *  remain (e.g. `'5 minutes'`). A deadline, not a count. */
+    readonly maxElapsed?: string;
+    /** Retry ONLY failures whose typed-error `_tag` is in this list; every
+     *  other error fails fast. The declarative "retry transient, fail
+     *  permanent" — e.g. `['ProviderDown', 'RateLimited']`. */
+    readonly retryableErrors?: ReadonlyArray<string>;
+    /** Retry-predicate on the raw error (wins over `retryableErrors` when
+     *  both are set). Not serialised into dashboard metadata. Default:
+     *  retry every failure. */
+    readonly retryable?: (error: unknown) => boolean;
+    /** Honor a provider's own backoff: if a retryable error carries a
+     *  `retryAfterMillis` number (or `retryAfter` in seconds), use exactly that as
+     *  the delay before the next attempt — REPLACING the computed backoff for
+     *  that attempt (a 429 `Retry-After`, say). Falls back to the normal backoff
+     *  when the error carries no hint. Default `false`. */
+    readonly respectRetryAfter?: boolean;
+    /** Free-form note rendered as a chip in the dashboard. */
     readonly note?: string;
 }
 
@@ -216,6 +232,25 @@ export declare interface WorkflowVersionOptions {
     readonly version?: string | number;
     readonly compatibleWith?: ReadonlyArray<string | number>;
     readonly patches?: ReadonlyArray<string>;
+    /**
+     * When `true`, a workflow whose top-level body FAILS does not become a
+     * terminal `failed` run — it **suspends** with its durable journal intact, so
+     * `voltro workflows resume <id>` (or `ctx.workflows.resume`) re-drives it from
+     * the point of failure: every completed activity replays from the journal
+     * (NOT re-executed) and only the failed activity runs again. This is the
+     * durable-execution way to make a workflow recoverable across a transient
+     * downstream outage without re-doing prior work.
+     *
+     * Default `false` — a failure is terminal (the dead-letter state; see
+     * `voltro workflows list --dead-letter`). Choose per workflow: `true` for a
+     * long multi-step pipeline where re-doing step 1..N-1 is expensive or unsafe;
+     * `false` for a short idempotent job where a fresh `retry` is simpler. A
+     * suspended-on-failure run shows up under `--status suspended`, NOT in the
+     * dead-letter view — it is recoverable, not dead.
+     *
+     * Maps to `@effect/workflow`'s `SuspendOnFailure` annotation.
+     */
+    readonly suspendOnFailure?: boolean;
 }
 
 export declare const WorkflowVersionTypeId: unique symbol;

package/dist/primitives.js

@@ -1,2 +1,2 @@
-import { _ as e, a as t, c as n, d as r, f as i, g as a, h as o, i as s, l as c, m as l, n as u, o as d, p as f, r as p, s as m, t as h, u as g, v as _, y as v } from "./primitives-CWy1iu5w.js";
+import { _ as e, a as t, c as n, d as r, f as i, g as a, h as o, i as s, l as c, m as l, n as u, o as d, p as f, r as p, s as m, t as h, u as g, v as _, y as v } from "./primitives-Dgu3O55Q.js";
 export { h as WorkflowMessagesProperty, u as WorkflowVersionTypeId, p as WorkflowWorkerLayerTypeId, s as durableClock, t as durableQueue, d as durableQueueModule, m as durableRateLimiterModule, n as getWorkflowVersionMetadata, c as isWorkflowWorkerLayer, g as processQueue, r as queueWorker, i as rateLimit, f as sleep, l as step, o as stepIdempotencyKey, a as stepModule, e as withCompensation, _ as workflow, v as workflowModule };