@astrale-os/sdk 0.6.0-beta.40 → 0.6.0-beta.41

package/dist/application/workflow/durable.d.ts

@@ -1,5 +1,4 @@
 import type { IssuerId } from '../../platform/auth/index.js';
-import type { ExecutionOutcome, ExecutionRef } from '../../platform/client/session/index.js';
 import type { NodeId } from '../../platform/graph/node/index.js';
 import type { CallableInputOf, Domain, ResolvedMethod } from '../../platform/schema/index.js';
 import type { Value } from '../../platform/value/index.js';
@@ -65,18 +64,29 @@ export interface DurableStepAuthority<DomainValue extends Domain = Domain, Defin
  * How long a failing Step is retried. Its limits, `maxAttempts` and `maxDurationMs`, go together: a
  * Step that declares either replaces both limits of the deployment, and the one it omits does not
  * bound it. The budget is spent at the first limit reached.
+ *
+ * Only a failure of the Step's own spends an attempt. A Kernel that refuses with a prescribed delay
+ * (capacity, draining, maintenance), or that does not answer a Query or a keyed call, is waited out
+ * without spending one; a request the Kernel can never accept fails the Step at once.
  */
 export interface DurableStepRetry {
-    /** Attempts, the first one included: 1 to 1,000. */
+    /**
+     * Attempts that may fail on the Step's own account, the first one included: 1 to 1,000. A wait for
+     * the platform spends none.
+     */
     readonly maxAttempts?: number;
     /**
-     * Time from the first attempt after which a failed attempt is not retried, 1 ms to 365 days; an
-     * attempt already scheduled, such as after a long prescribed delay, still runs.
+     * Time from the first attempt after which a failed attempt is not retried, whatever it failed on,
+     * 1 ms to 365 days; an attempt already scheduled, such as after a long prescribed delay, still
+     * runs. The only bound on waiting for the platform.
      */
     readonly maxDurationMs?: number;
     /** Delay before the first retry, doubled on each failure: 1 ms to one hour. */
     readonly initialIntervalMs?: number;
-    /** Longest delay between two attempts: `initialIntervalMs` to one day. */
+    /**
+     * Longest backoff between two attempts: `initialIntervalMs` to one day. A longer delay the Kernel
+     * prescribes is still waited.
+     */
     readonly maxIntervalMs?: number;
 }
 /** A Step: its id, and the retry budget and timeout it declares instead of the deployment's. */
@@ -88,8 +98,8 @@ export interface DurableStepDeclaration {
 }
 /**
  * A Step's id alone, under the deployment's retry budget and Step timeout, or a declaration of its
- * own. A Step that spends its budget throws an error `exhausted` recognizes; uncaught, the Execution
- * ends `failed` with code `STEP_EXHAUSTED`.
+ * own. A Step that spends its budget, or that the Kernel refuses for good, throws an error
+ * `exhausted` recognizes; uncaught, the Execution ends `failed` with code `STEP_EXHAUSTED`.
  */
 export type DurableStepId = string | DurableStepDeclaration;
 export interface DurableStep<DomainValue extends Domain = Domain, Definitions extends Integrations = Readonly<Record<never, never>>> {
@@ -171,15 +181,17 @@ export type DurableWorkflowContext<Callable, DomainValue extends Domain = Domain
     }): Promise<SignalOutcome<Signal>>;
     /** Whether `error` is the engine's cooperative cancellation, which the Workflow may compensate. */
     cancelled(error: unknown): boolean;
-    /** Whether `error` is a Step that spent its retry budget, which the Workflow may handle. */
+    /**
+     * Whether `error` is a Step that spent its retry budget, or that the Kernel refused for good,
+     * which the Workflow may handle.
+     */
     exhausted(error: unknown): boolean;
     /**
-     * The failure of a Step attempt, to throw inside the Step, that the engine attempts again no
-     * earlier than `delayMs` (at most one hour), as an HTTP `Retry-After` asks. The attempt counts
-     * toward the Step's budget. A Kernel refusal that prescribes a delay is retried this way already.
+     * The failure of a Step attempt, to throw inside the Step, that the engine attempts again after
+     * exactly `delayMs` (at most one hour), as an HTTP `Retry-After` asks. The attempt spends the
+     * Step's budget, since only the Step knows whether its cause clears. A Kernel refusal that
+     * prescribes a delay is waited out already, without spending it.
      */
     retryAfter(delayMs: number, cause?: unknown): Error;
-    /** Wait durably for another Execution to end, by journaled polling of its `result`. */
-    awaitExecution<Output>(execution: ExecutionRef<Output>): Promise<ExecutionOutcome<Output>>;
 } & DurableSelfOf<Callable>;
 export {};

package/dist/execution/workflows/attempts.d.ts

@@ -0,0 +1,87 @@
+import type { DurableEngine } from './engine.js';
+import type { KernelRefusal } from './failure.js';
+import type { StepRetryBudget } from './options.js';
+/**
+ * What the failure of one Step attempt means for its Step, read from protocol facts alone:
+ *
+ * - `permanent`: the Kernel refused a request that cannot succeed sent again unchanged. The Step
+ *   fails at once.
+ * - `platform`: the Kernel or the way to it was unavailable, and sending the request again repeats
+ *   no effect. The Step waits and tries again without spending an attempt, bounded only by its
+ *   `maxDurationMs` and by cancellation. An attempt after an unkeyed `invoke` that may have run,
+ *   which the next attempt sends again, is never one: it spends an attempt.
+ * - `own`: anything else, the Step's code, a Provider, or a refusal whose retry meaning the Kernel
+ *   leaves open. The attempt spends one of the Step's attempts.
+ */
+export type AttemptFailureKind = 'permanent' | 'platform' | 'own';
+/** One failed Step attempt, as its journal entry records it. */
+export interface FailedAttempt {
+    readonly kind: AttemptFailureKind;
+    /** The delay the failure prescribes: a Kernel `retryAfterMs`, or the Step's own `retryAfter`. */
+    readonly delayMs?: number;
+    readonly refusal?: KernelRefusal;
+    /** When the attempt started and ended, on the run's clock. */
+    readonly startedAt: number;
+    readonly endedAt: number;
+}
+/** What the failed attempts of one Step spent so far. */
+export interface StepSpending {
+    /** The start of the Step's first attempt, from which `maxDurationMs` runs. */
+    readonly startedAt: number;
+    /** Attempts that failed for the Step's own reason. */
+    readonly attempts: number;
+    /** Platform failures since the Step's last own failure, which space the next platform wait. */
+    readonly unavailable: number;
+}
+/** How a Step goes on after a failed attempt. */
+export type NextAttempt = {
+    readonly kind: 'retry';
+    readonly delayMs: number;
+    /** A wait for the platform, or the backoff of an own failure. */
+    readonly wait: typeof UNAVAILABLE | typeof BACKOFF;
+    readonly spending: StepSpending;
+} | {
+    readonly kind: 'exhausted';
+    readonly refusal?: KernelRefusal;
+};
+/** Name prefix of the durable wait before the attempt that follows an own failure. */
+export declare const BACKOFF = "retry";
+/** Name prefix of the durable wait before the attempt that follows a platform failure. */
+export declare const UNAVAILABLE = "unavailable";
+/**
+ * The outcome of a Kernel call that repeats no effect when sent again, a read or a call carrying
+ * its idempotency key: its failure lets the Step tell an unreachable Kernel from its own failure.
+ */
+export declare function resendableCall<Output>(call: () => Output): Output;
+/**
+ * The outcome of a Kernel call that runs its effect again when sent again, an `invoke` without a
+ * key: `ran` hears that the call may have run, unless its failure proves it did not.
+ */
+export declare function unkeyedCall<Output>(call: () => Promise<Output>, ran: () => void): Promise<Output>;
+/**
+ * Classify the failure of one Step attempt, a declared error excepted, by the first Kernel answer or
+ * transport failure among its causes, and name the Kernel refusal behind it, if any.
+ */
+export declare function classifyFailure(cause: unknown): Pick<FailedAttempt, 'kind' | 'delayMs' | 'refusal'>;
+/**
+ * The terminal failure a Step attempt hands the engine for `cause`: the engine journals it as the
+ * attempt's outcome, so the Step decides whether to go on from the journal alone, live and on
+ * replay. Its message starts with the Kernel refusal's codes, if any, and is bounded.
+ * `repeatsEffects` says whether the attempt ran a request the next attempt runs again with its
+ * effect, so an outage never repeats that effect beyond the Step's budget.
+ */
+export declare function failedAttemptError(engine: DurableEngine, cause: unknown, startedAt: number, endedAt: number, repeatsEffects: boolean): Error;
+/** The failed attempt a journaled `run` outcome records, if it records one. */
+export declare function failedAttemptOf(engine: DurableEngine, outcome: unknown): FailedAttempt | undefined;
+/**
+ * How a Step goes on after `failed`, given what its earlier attempts spent:
+ *
+ * - A permanent failure exhausts the Step at once.
+ * - An own failure spends an attempt; the next one waits the delay the failure prescribes, or the
+ *   Step's backoff over its own failures.
+ * - A platform failure spends no attempt; the next one waits the longer of the delay the Kernel
+ *   prescribes and the Step's backoff over its platform failures since its last own one, so a long
+ *   outage costs one attempt per `maxIntervalMs`.
+ * - Either way, a failure at or past `maxDurationMs` from the Step's first attempt exhausts it.
+ */
+export declare function nextAttempt(spent: StepSpending | undefined, failed: FailedAttempt, budget: StepRetryBudget): NextAttempt;

package/dist/execution/workflows/attempts.js

@@ -0,0 +1,205 @@
+import { ClientError, ResponseError, TransportError, isExpectationMismatch, isMaintenanceSessionStale, isSnapshotStale, retryAfterOf, } from '../../platform/client/index.js';
+import { attemptMessage, kernelRefusalOf, StepRetryAfter } from './failure.js';
+/** Name prefix of the durable wait before the attempt that follows an own failure. */
+export const BACKOFF = 'retry';
+/** Name prefix of the durable wait before the attempt that follows a platform failure. */
+export const UNAVAILABLE = 'unavailable';
+/** Metadata key under which a failed attempt's journal entry records its `FailedAttempt`. */
+const ATTEMPT = 'astrale.attempt';
+/** The longest message a failed attempt's journal entry keeps, so an outage journals little. */
+const MAXIMUM_MESSAGE = 1_024;
+/** How deep a failure's causes are searched for the call that failed. */
+const MAXIMUM_CAUSE_DEPTH = 8;
+/**
+ * Kernel refusals that name a request that cannot succeed sent again unchanged: a malformed or
+ * unsupported request, or a Domain meaning this Instance does not serve.
+ */
+const PERMANENT_CODES = new Set([
+    1001, // PARSE_ERROR
+    1002, // INVALID_REQUEST
+    3003, // METHOD_NOT_ALLOWED
+    4002, // UNSUPPORTED
+]);
+const OUTCOME_UNKNOWN = 5002;
+/** HTTP answers without an invocation response that say the server took no work. */
+const UNAVAILABLE_STATUS = /^(?:429|502|503)$/u;
+const STATUS_OF_ANSWER = /^server returned HTTP (\d{3}) without an invocation response\.$/u;
+const STATUS_OF_DISCOVERY = /^Release discovery returned HTTP (\d{3})\.$/u;
+/** Failures of Kernel calls that send again without repeating an effect: reads and keyed calls. */
+const resendable = new WeakSet();
+/**
+ * The outcome of a Kernel call that repeats no effect when sent again, a read or a call carrying
+ * its idempotency key: its failure lets the Step tell an unreachable Kernel from its own failure.
+ */
+export function resendableCall(call) {
+    let output;
+    try {
+        output = call();
+    }
+    catch (cause) {
+        markResendable(cause);
+        throw cause;
+    }
+    if (!(output instanceof Promise))
+        return output;
+    return output.catch((cause) => {
+        markResendable(cause);
+        throw cause;
+    });
+}
+function markResendable(cause) {
+    if (cause !== null && typeof cause === 'object')
+        resendable.add(cause);
+}
+/**
+ * The outcome of a Kernel call that runs its effect again when sent again, an `invoke` without a
+ * key: `ran` hears that the call may have run, unless its failure proves it did not.
+ */
+export function unkeyedCall(call, ran) {
+    const failed = (cause) => {
+        // For a call sent without a key, only a failure that proves nothing ran is the platform's.
+        if (classifyFailure(cause).kind !== 'platform')
+            ran();
+        throw cause;
+    };
+    let output;
+    try {
+        output = call();
+    }
+    catch (cause) {
+        return failed(cause);
+    }
+    return Promise.resolve(output).then((value) => {
+        ran();
+        return value;
+    }, failed);
+}
+/**
+ * Classify the failure of one Step attempt, a declared error excepted, by the first Kernel answer or
+ * transport failure among its causes, and name the Kernel refusal behind it, if any.
+ */
+export function classifyFailure(cause) {
+    const refusal = kernelRefusalOf(cause);
+    const named = refusal === undefined ? {} : { refusal };
+    if (cause instanceof StepRetryAfter)
+        return { kind: 'own', delayMs: cause.delayMs, ...named };
+    let resent = false;
+    let current = cause;
+    for (let depth = 0; depth < MAXIMUM_CAUSE_DEPTH; depth += 1) {
+        if (current === null || typeof current !== 'object')
+            break;
+        resent ||= resendable.has(current);
+        if (current instanceof ResponseError)
+            return { ...refusalKind(current, resent), ...named };
+        if (current instanceof TransportError)
+            return { kind: transportKind(current, resent), ...named };
+        if (current instanceof ClientError && unavailableStatus(STATUS_OF_DISCOVERY, current.message)) {
+            // Release discovery is a read the Kernel's own server failed to answer.
+            return { kind: 'platform', ...named };
+        }
+        current = current.cause;
+    }
+    return { kind: 'own', ...named };
+}
+function refusalKind(error, resent) {
+    // Read before the refusal guards, which narrow a `ResponseError` they reject to nothing.
+    const { code } = error;
+    // Capacity, draining and maintenance: refused before any work was admitted.
+    const delayMs = retryAfterOf(error);
+    if (delayMs !== undefined)
+        return { kind: 'platform', delayMs };
+    // A sealed conflict whose snapshot advanced ran nothing, and may be sent again at once.
+    if (isSnapshotStale(error))
+        return { kind: 'platform' };
+    if (PERMANENT_CODES.has(code) ||
+        isExpectationMismatch(error) ||
+        isMaintenanceSessionStale(error)) {
+        return { kind: 'permanent' };
+    }
+    // The Kernel asks not to send again an unknown outcome automatically, unless its key replays it.
+    if (code === OUTCOME_UNKNOWN && resent)
+        return { kind: 'platform' };
+    return { kind: 'own' };
+}
+/**
+ * A transport failure is the platform's when it is no local bound or deadline, and its request
+ * provably did not reach the Kernel or repeats no effect when sent again.
+ */
+function transportKind(error, resent) {
+    // A deadline may be the request's own cost: it spends an attempt, as any slow attempt does.
+    if (error.phase === 'timeout')
+        return 'own';
+    // A failure with neither a network cause nor an unavailable answer is a local bound.
+    const network = error.cause !== undefined || unavailableStatus(STATUS_OF_ANSWER, error.message);
+    if (!network)
+        return 'own';
+    if (error.context.kind === 'acquisition')
+        return 'platform';
+    return error.context.delivery === 'not-sent' || resent ? 'platform' : 'own';
+}
+function unavailableStatus(pattern, message) {
+    const status = pattern.exec(message)?.[1];
+    return status !== undefined && UNAVAILABLE_STATUS.test(status);
+}
+/**
+ * The terminal failure a Step attempt hands the engine for `cause`: the engine journals it as the
+ * attempt's outcome, so the Step decides whether to go on from the journal alone, live and on
+ * replay. Its message starts with the Kernel refusal's codes, if any, and is bounded.
+ * `repeatsEffects` says whether the attempt ran a request the next attempt runs again with its
+ * effect, so an outage never repeats that effect beyond the Step's budget.
+ */
+export function failedAttemptError(engine, cause, startedAt, endedAt, repeatsEffects) {
+    const classified = classifyFailure(cause);
+    const kind = repeatsEffects && classified.kind === 'platform' ? 'own' : classified.kind;
+    const failed = { ...classified, kind, startedAt, endedAt };
+    const message = attemptMessage(cause);
+    const error = new engine.TerminalError(message.length > MAXIMUM_MESSAGE ? `${message.slice(0, MAXIMUM_MESSAGE - 1)}…` : message, { metadata: { [ATTEMPT]: JSON.stringify(failed) } });
+    // Kept on the live error only: what the attempt threw, for a test engine to show.
+    Object.defineProperty(error, 'cause', { value: cause, configurable: true, writable: true });
+    return error;
+}
+/** The failed attempt a journaled `run` outcome records, if it records one. */
+export function failedAttemptOf(engine, outcome) {
+    if (!(outcome instanceof engine.TerminalError) || outcome instanceof engine.CancelledError) {
+        return undefined;
+    }
+    const encoded = outcome.metadata?.[ATTEMPT];
+    return encoded === undefined ? undefined : JSON.parse(encoded);
+}
+/**
+ * How a Step goes on after `failed`, given what its earlier attempts spent:
+ *
+ * - A permanent failure exhausts the Step at once.
+ * - An own failure spends an attempt; the next one waits the delay the failure prescribes, or the
+ *   Step's backoff over its own failures.
+ * - A platform failure spends no attempt; the next one waits the longer of the delay the Kernel
+ *   prescribes and the Step's backoff over its platform failures since its last own one, so a long
+ *   outage costs one attempt per `maxIntervalMs`.
+ * - Either way, a failure at or past `maxDurationMs` from the Step's first attempt exhausts it.
+ */
+export function nextAttempt(spent, failed, budget) {
+    const refusal = failed.refusal === undefined ? {} : { refusal: failed.refusal };
+    if (failed.kind === 'permanent')
+        return { kind: 'exhausted', ...refusal };
+    const startedAt = spent?.startedAt ?? failed.startedAt;
+    const own = failed.kind === 'own';
+    const attempts = (spent?.attempts ?? 0) + (own ? 1 : 0);
+    const unavailable = own ? 0 : (spent?.unavailable ?? 0) + 1;
+    if ((budget.maxAttempts !== undefined && attempts >= budget.maxAttempts) ||
+        (budget.maxDurationMs !== undefined && failed.endedAt - startedAt >= budget.maxDurationMs)) {
+        return { kind: 'exhausted', ...refusal };
+    }
+    const delayMs = own
+        ? (failed.delayMs ?? backoff(budget, attempts))
+        : Math.max(failed.delayMs ?? 0, backoff(budget, unavailable));
+    return {
+        kind: 'retry',
+        delayMs,
+        wait: own ? BACKOFF : UNAVAILABLE,
+        spending: { startedAt, attempts, unavailable },
+    };
+}
+/** The `failures`-th wait of a capped exponential backoff, the first one `initialIntervalMs`. */
+function backoff(budget, failures) {
+    return Math.min(budget.maxIntervalMs, budget.initialIntervalMs * budget.intervalFactor ** (failures - 1));
+}

package/dist/execution/workflows/engine.d.ts

@@ -52,17 +52,6 @@ export interface EngineRetryPolicy {
     readonly maxInterval: number;
     readonly exponentiationFactor: number;
 }
-/**
- * The retry budget of one journaled `run`. Spent, the `run` rejects with a `TerminalError` and the
- * engine attempts it no more; an absent limit does not bound it.
- */
-export interface EngineRunOptions {
-    readonly maxRetryAttempts?: number;
-    readonly maxRetryDuration?: number;
-    readonly initialRetryInterval: number;
-    readonly maxRetryInterval: number;
-    readonly retryIntervalFactor: number;
-}
 /**
  * A promise the engine journals. Its combinators are journaled too, so a replay settles them as the
  * first run did; racing it against another promise with `Promise.race` would not be.
@@ -73,7 +62,12 @@ export interface EnginePromise<Output> extends PromiseLike<Output> {
 }
 /** Journaled operations of one workflow run. */
 export interface EngineWorkflowContext {
-    run<Output>(name: string, action: () => Promise<Output>, options?: EngineRunOptions): PromiseLike<Output>;
+    /**
+     * Run `action` once and journal its outcome: its value, or the `TerminalError` it throws. Any
+     * other failure fails the run's attempt, which the engine attempts again under its retry policy.
+     */
+    run<Output>(name: string, action: () => Promise<Output>): PromiseLike<Output>;
+    /** A durable timer; `name` labels its journal entry. */
     sleep(durationMs: number, name?: string): PromiseLike<void>;
     promise(name: string): {
         get(): EnginePromise<unknown>;

package/dist/execution/workflows/failure.d.ts

@@ -7,8 +7,9 @@ export interface KernelRefusal {
     readonly reason?: string;
 }
 /**
- * A Step that spent its retry budget. Its message never carries what the last attempt threw; when
- * the Kernel refused that attempt, `refusal` names the refusal by its codes alone.
+ * A Step that spent its retry budget, or whose attempt the Kernel refused for good. Its message
+ * never carries what the last attempt threw; when the Kernel refused that attempt, `refusal` names
+ * the refusal by its codes alone.
  */
 export declare class StepExhausted extends Error {
     readonly step: string;
@@ -17,21 +18,13 @@ export declare class StepExhausted extends Error {
 }
 /** The Kernel refusal behind `cause`, itself or one of its causes. */
 export declare function kernelRefusalOf(cause: unknown): KernelRefusal | undefined;
-/**
- * The failure a Step attempt hands the engine: `cause` itself, or, when the Kernel refused the
- * attempt, an error whose message starts with the refusal's codes, so the exhaustion can name it.
- */
-export declare function attemptFailure(cause: unknown): unknown;
-/** A Step attempt's failure that asks the engine to wait `delayMs` before the next attempt. */
+/** The message of a failed attempt: what it threw, after the Kernel refusal's codes, if any. */
+export declare function attemptMessage(cause: unknown, refusal?: KernelRefusal | undefined): string;
+/** A Step attempt's failure that asks to wait `delayMs` before the next attempt. */
 export declare class StepRetryAfter extends Error {
     readonly delayMs: number;
     constructor(delayMs: number, cause?: unknown);
 }
-/**
- * The failure of a Step attempt that waits out a prescribed delay before the next attempt, instead
- * of the Step's backoff: a `retryAfter` failure, or a Kernel refusal that prescribes `retryAfterMs`.
- */
-export declare function delayedRetry(engine: DurableEngine, cause: unknown): Error | undefined;
 /**
  * Encode a declared business error of `definition`, or a Step that spent its retry budget, as a
  * terminal engine failure, or return undefined for any other error, which the engine retries.

package/dist/execution/workflows/failure.js

@@ -1,5 +1,5 @@
 import { declaredErrorFactory, declaredErrorOf } from '../../application/error/index.js';
-import { ResponseError, retryAfterOf } from '../../platform/client/index.js';
+import { ResponseError } from '../../platform/client/index.js';
 /** Metadata key the Kernel reads a declared failure from (`backend/restate` outcome decoding). */
 const FAILURE = 'astrale.failure';
 /** Failure code of an Execution whose Workflow did not catch a Step that spent its retry budget. */
@@ -15,8 +15,9 @@ const REASON_CODE = /^[A-Z][A-Z0-9_]{0,63}$/u;
  */
 const REFUSAL_MARK = /\[kernel refusal ([1-9][0-9]{3})(?: ([A-Z][A-Z0-9_]{0,63}))?\] /gu;
 /**
- * A Step that spent its retry budget. Its message never carries what the last attempt threw; when
- * the Kernel refused that attempt, `refusal` names the refusal by its codes alone.
+ * A Step that spent its retry budget, or whose attempt the Kernel refused for good. Its message
+ * never carries what the last attempt threw; when the Kernel refused that attempt, `refusal` names
+ * the refusal by its codes alone.
  */
 export class StepExhausted extends Error {
     step;
@@ -46,17 +47,8 @@ export function kernelRefusalOf(cause) {
     }
     return undefined;
 }
-/**
- * The failure a Step attempt hands the engine: `cause` itself, or, when the Kernel refused the
- * attempt, an error whose message starts with the refusal's codes, so the exhaustion can name it.
- */
-export function attemptFailure(cause) {
-    const refusal = kernelRefusalOf(cause);
-    if (refusal === undefined)
-        return cause;
-    return new Error(attemptMessage(cause, refusal), { cause });
-}
-function attemptMessage(cause, refusal = kernelRefusalOf(cause)) {
+/** The message of a failed attempt: what it threw, after the Kernel refusal's codes, if any. */
+export function attemptMessage(cause, refusal = kernelRefusalOf(cause)) {
     const message = cause instanceof Error ? cause.message : String(cause);
     if (refusal === undefined)
         return message;
@@ -74,7 +66,7 @@ function refusalIn(message) {
         ...(last[2] === undefined ? {} : { reason: last[2] }),
     });
 }
-/** A Step attempt's failure that asks the engine to wait `delayMs` before the next attempt. */
+/** A Step attempt's failure that asks to wait `delayMs` before the next attempt. */
 export class StepRetryAfter extends Error {
     delayMs;
     constructor(delayMs, cause) {
@@ -86,16 +78,6 @@ export class StepRetryAfter extends Error {
         this.delayMs = delayMs;
     }
 }
-/**
- * The failure of a Step attempt that waits out a prescribed delay before the next attempt, instead
- * of the Step's backoff: a `retryAfter` failure, or a Kernel refusal that prescribes `retryAfterMs`.
- */
-export function delayedRetry(engine, cause) {
-    const delayMs = cause instanceof StepRetryAfter ? cause.delayMs : retryAfterOf(cause);
-    if (delayMs === undefined)
-        return undefined;
-    return new engine.RetryableError(attemptMessage(cause), { retryAfter: delayMs, cause });
-}
 const STATUS = {
     VALIDATION_ERROR: 422,
     NOT_FOUND: 404,
@@ -147,7 +129,8 @@ export function replayedFailure(engine, cause, definition, step) {
         return undefined;
     }
     const encoded = cause.metadata?.[FAILURE];
-    // The Step's own code turns every terminal failure into a declared one; the engine's is its budget.
+    // The Step's own code turns every terminal failure into a declared one or a failed attempt; a
+    // bare one is an engine's budget.
     if (encoded === undefined)
         return new StepExhausted(step, refusalIn(cause.message));
     const failure = JSON.parse(encoded);

package/dist/execution/workflows/index.d.ts

@@ -1,4 +1,4 @@
-export type { DurableEngine, EnginePromise, EngineRetryPolicy, EngineCombinators, EngineRunOptions, EngineSharedContext, EngineWorkflowContext, EngineWorkflowDefinition, } from './engine.js';
+export type { DurableEngine, EnginePromise, EngineRetryPolicy, EngineCombinators, EngineSharedContext, EngineWorkflowContext, EngineWorkflowDefinition, } from './engine.js';
 export { DURABLE_ENGINE_EXPORTS, durableServing, isDurableEngine, type AdmittedDurableServing, type DurableServing, type DurableServingProvider, } from './options.js';
 export { createDurableReceiver, type DurableReceiver } from './receiver.js';
 export { isDurableRequest, isCanonicalDurableRequest } from './route.js';

package/dist/execution/workflows/options.d.ts

@@ -1,6 +1,6 @@
 import type { Fetch } from '@astrale-os/kernel-client';
 import type { DurableStepRetry } from '../../application/workflow/index.js';
-import type { DurableEngine, EngineRetryPolicy, EngineRunOptions } from './engine.js';
+import type { DurableEngine, EngineRetryPolicy } from './engine.js';
 /** Serving configuration of the durable Workflows of one deployment. */
 export interface DurableServing {
     /** The Restate SDK Fetch build of this platform. */
@@ -14,9 +14,11 @@ export interface DurableServing {
      */
     readonly retentionMs?: number;
     /**
-     * Retry budget of every Step that declares none: 20 attempts from 1 s to 60 s by default. A Step
-     * that spends it fails into its Workflow. `maxAttempts` also bounds the attempts of a run that
-     * fails outside any Step, which then pauses for `resume` or `cancel`. The Host caps them.
+     * Retry budget of every Step that declares none: 10 attempts from 1 s to 60 s by default, and no
+     * duration limit. Only a Step's own failures spend its attempts; it waits out an unavailable Kernel
+     * within its `maxDurationMs`. A Step that spends it fails into its Workflow. `maxAttempts` also
+     * bounds the attempts of a run that fails outside any Step, an unreachable deployment included,
+     * which then pauses for `resume` or `cancel`; 20 when it declares none. The Host caps them.
      */
     readonly retry?: DurableStepRetry;
     /** Deadline of one Step attempt that declares none, including its Kernel calls. One minute by default. */
@@ -33,11 +35,24 @@ export interface AdmittedDurableServing {
     /** Retry budget and attempt deadline of a Step that declares none. */
     readonly step: StepServing;
 }
-/** What a Step is held to: its retry budget, as the engine applies it, and its attempt deadline. */
+/** What a Step is held to: its retry budget and its attempt deadline. */
 export interface StepServing {
-    readonly retry: EngineRunOptions;
+    readonly retry: StepRetryBudget;
     readonly timeoutMs: number;
 }
+/**
+ * The retry budget of one Step, which the Step spends attempt by attempt (see `attempts.ts`). An
+ * absent limit does not bound it.
+ */
+export interface StepRetryBudget {
+    /** Attempts whose failure is the Step's own, the first one included. */
+    readonly maxAttempts?: number;
+    /** Time from the start of the Step's first attempt after which a failed attempt is not retried. */
+    readonly maxDurationMs?: number;
+    readonly initialIntervalMs: number;
+    readonly maxIntervalMs: number;
+    readonly intervalFactor: number;
+}
 /**
  * The members of the Restate SDK Fetch entrypoint the durable receiver uses, which a platform's
  * engine module must export.

package/dist/execution/workflows/options.js

@@ -29,7 +29,17 @@ export function isDurableEngine(module) {
 }
 const HOUR_MS = 60 * 60_000;
 const DAY_MS = 24 * HOUR_MS;
-const DEFAULT_ATTEMPTS = 20;
+/**
+ * Attempts a Step's own failures may spend when the deployment declares none. An unavailable Kernel
+ * spends none of them, so they bound only failures that sending again may not cure.
+ */
+const DEFAULT_STEP_ATTEMPTS = 10;
+/**
+ * Attempts of a run failing outside any Step when the deployment declares none. The engine counts an
+ * unreachable deployment as such a failure, which it cannot tell apart from the code's own, so these
+ * also span an unavailability of the deployment, about fourteen minutes at the default intervals.
+ */
+const DEFAULT_RUN_ATTEMPTS = 20;
 /** The longest attempt a Step may declare, which the engine's abort timeout leaves to end first. */
 const MAXIMUM_STEP_TIMEOUT_MS = 10 * 60_000;
 /**
@@ -39,10 +49,10 @@ const MAXIMUM_STEP_TIMEOUT_MS = 10 * 60_000;
  */
 export const ENGINE_ABORT_TIMEOUT_MS = MAXIMUM_STEP_TIMEOUT_MS + 5 * 60_000;
 const DEFAULT_STEP_RETRY = Object.freeze({
-    maxRetryAttempts: DEFAULT_ATTEMPTS,
-    initialRetryInterval: 1_000,
-    maxRetryInterval: 60_000,
-    retryIntervalFactor: 2,
+    maxAttempts: DEFAULT_STEP_ATTEMPTS,
+    initialIntervalMs: 1_000,
+    maxIntervalMs: 60_000,
+    intervalFactor: 2,
 });
 /** Capture one durable serving configuration, failing closed on any gap. */
 export function durableServing(input) {
@@ -79,11 +89,11 @@ export function durableServing(input) {
         fetch,
         retentionMs: bounded(input.retentionMs, 7 * DAY_MS, HOUR_MS, 365 * DAY_MS, 'retentionMs'),
         retryPolicy: Object.freeze({
-            maxAttempts: input.retry?.maxAttempts ?? DEFAULT_ATTEMPTS,
+            maxAttempts: input.retry?.maxAttempts ?? DEFAULT_RUN_ATTEMPTS,
             onMaxAttempts: 'pause',
-            initialInterval: step.retry.initialRetryInterval,
-            maxInterval: step.retry.maxRetryInterval,
-            exponentiationFactor: step.retry.retryIntervalFactor,
+            initialInterval: step.retry.initialIntervalMs,
+            maxInterval: step.retry.maxIntervalMs,
+            exponentiationFactor: step.retry.intervalFactor,
         }),
         step,
     });
@@ -112,19 +122,19 @@ export function stepServing(declared, fallback) {
     const limited = retry.maxAttempts !== undefined || retry.maxDurationMs !== undefined;
     const maxAttempts = limited
         ? optionalBounded(retry.maxAttempts, 1, 1_000, 'maxAttempts')
-        : fallback.retry.maxRetryAttempts;
+        : fallback.retry.maxAttempts;
     const maxDuration = limited
         ? optionalBounded(retry.maxDurationMs, 1, 365 * DAY_MS, 'maxDurationMs')
-        : fallback.retry.maxRetryDuration;
-    const initialInterval = bounded(retry.initialIntervalMs, fallback.retry.initialRetryInterval, 1, HOUR_MS, 'initialIntervalMs');
-    const maxInterval = bounded(retry.maxIntervalMs, Math.max(fallback.retry.maxRetryInterval, initialInterval), initialInterval, DAY_MS, 'maxIntervalMs');
+        : fallback.retry.maxDurationMs;
+    const initialInterval = bounded(retry.initialIntervalMs, fallback.retry.initialIntervalMs, 1, HOUR_MS, 'initialIntervalMs');
+    const maxInterval = bounded(retry.maxIntervalMs, Math.max(fallback.retry.maxIntervalMs, initialInterval), initialInterval, DAY_MS, 'maxIntervalMs');
     return Object.freeze({
         retry: Object.freeze({
-            ...(maxAttempts === undefined ? {} : { maxRetryAttempts: maxAttempts }),
-            ...(maxDuration === undefined ? {} : { maxRetryDuration: maxDuration }),
-            initialRetryInterval: initialInterval,
-            maxRetryInterval: maxInterval,
-            retryIntervalFactor: fallback.retry.retryIntervalFactor,
+            ...(maxAttempts === undefined ? {} : { maxAttempts }),
+            ...(maxDuration === undefined ? {} : { maxDurationMs: maxDuration }),
+            initialIntervalMs: initialInterval,
+            maxIntervalMs: maxInterval,
+            intervalFactor: fallback.retry.intervalFactor,
         }),
         timeoutMs: stepTimeout(declared.timeoutMs, fallback.timeoutMs),
     });