@voltro/workflow 0.24.0 → 0.26.0

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
@@ -681,6 +703,18 @@ export declare type WorkflowRunEventType = 'run-started' | 'run-suspended' | 'ru
 *  errorTag, errorMessage }`; the caller's update promise rejects. */
 | 'update-failed';
 
+/** A workflow run's TERMINAL outcome, handed to the metrics hook. Kept local to
+ *  this package (structurally matching `@voltro/runtime`'s `WorkflowRunRecord`) so
+ *  the workflow package stays free of a `@voltro/runtime` dependency — the CLI
+ *  wiring supplies a `recordRun` that forwards to `recordWorkflowRun`. */
+declare interface WorkflowRunOutcome {
+    readonly name: string;
+    readonly status: 'succeeded' | 'failed';
+    readonly durationMs: number;
+    /** UNIX seconds — set only on success (drives the last-success gauge). */
+    readonly completedAtSec?: number;
+}
+
 export declare class WorkflowRunRecorder extends WorkflowRunRecorder_base {
 }
 
@@ -695,6 +729,11 @@ export declare interface WorkflowRunRecorderOptions {
     /** Dormancy wakeup producer — present only in sleep mode. Absent →
      *  zero overhead (always-on default). */
     readonly wakeups?: WorkflowWakeupHook;
+    /** Terminal-outcome metrics hook — supplied by the CLI wiring (mirrors
+     *  `emit`/`wakeups`), so this package needs no `@voltro/runtime` dep. Called once
+     *  per run at a TERMINAL outcome (succeeded/failed), never on suspend. Absent →
+     *  no metrics, zero overhead. */
+    readonly recordRun?: (outcome: WorkflowRunOutcome) => void;
 }
 
 /** Per-step lifecycle hooks. Implementations should not throw —
@@ -826,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-ByK8t2Nv.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 };