@astrale-os/sdk 0.6.0-beta.38 → 0.6.0-beta.39

package/dist/application/runtime/workflows.js

@@ -20,9 +20,6 @@ export function admitWorkflows(callables, input) {
             throw new TypeError(`Runtime Workflow ${definition.address} must have value output.`);
         }
         const durable = callable.execution?.durable === true;
-        if (!durable && definition.compat !== undefined) {
-            throw new TypeError(`Runtime Workflow ${definition.address} declares compat but its callable is not durable.`);
-        }
         return Object.freeze({
             kind: 'workflow',
             address: definition.address,

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

@@ -1,5 +1,5 @@
 export { defineWorkflow } from './define.js';
 export type { InlineWorkflowContext, WorkflowContext } from './context.js';
-export type { DurableCallable, DurableExecution, DurableStep, DurableStepAuthority, DurableWorkflowContext, SignalOutcome, } from './durable.js';
+export type { DurableCallable, DurableExecution, DurableStep, DurableStepAuthority, DurableStepDeclaration, DurableStepId, DurableStepRetry, DurableWorkflowContext, SignalOutcome, } from './durable.js';
 export type { Workflow, WorkflowAddress, WorkflowDefinition, WorkflowOptions } from './workflow.js';
 export type { DeclaredErrorDefinition, DeclaredErrorFactory, DeclaredErrorFamily, DeclaredErrorOptions, DeclaredErrors, } from '../error/index.js';

package/dist/application/workflow/define.js

@@ -1,7 +1,6 @@
 import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
 import { rememberDeclaredErrors } from '../error/index.js';
 const admittedWorkflows = new WeakSet();
-const COMPAT_TOKEN = /^[A-Za-z0-9._~-]{1,64}$/u;
 /** Define one multi-step value-output implementation by its SDK Action address. */
 export function defineWorkflow() {
     return function define(address, optionsOrRun, possibleRun) {
@@ -10,12 +9,7 @@ export function defineWorkflow() {
         const run = possibleRun ?? optionsOrRun;
         if (typeof run !== 'function')
             throw new TypeError('Workflow run must be a function.');
-        const workflow = Object.freeze({
-            kind: 'workflow',
-            address,
-            run,
-            ...(options?.compat === undefined ? {} : { compat: options.compat }),
-        });
+        const workflow = Object.freeze({ kind: 'workflow', address, run });
         if (options?.errors !== undefined)
             rememberDeclaredErrors(workflow, { errors: options.errors });
         admittedWorkflows.add(workflow);
@@ -26,15 +20,10 @@ function acceptOptions(input) {
     if (input === null ||
         typeof input !== 'object' ||
         Array.isArray(input) ||
-        Reflect.ownKeys(input).some((key) => key !== 'errors' && key !== 'compat')) {
-        throw new TypeError('Workflow options accept only errors and compat.');
+        Reflect.ownKeys(input).some((key) => key !== 'errors')) {
+        throw new TypeError('Workflow options accept only errors.');
     }
-    const options = input;
-    if (options.compat !== undefined &&
-        (typeof options.compat !== 'string' || !COMPAT_TOKEN.test(options.compat))) {
-        throw new TypeError(`Invalid Workflow compat token: ${JSON.stringify(options.compat)}.`);
-    }
-    return options;
+    return input;
 }
 export function isWorkflow(input) {
     return input !== null && typeof input === 'object' && admittedWorkflows.has(input);

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

@@ -61,24 +61,55 @@ export interface DurableStepAuthority<DomainValue extends Domain = Domain, Defin
      */
     readonly integrations: ReplayableIntegrationClients<Definitions>;
 }
+/**
+ * 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.
+ */
+export interface DurableStepRetry {
+    /** Attempts, the first one included: 1 to 1,000. */
+    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.
+     */
+    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. */
+    readonly maxIntervalMs?: number;
+}
+/** A Step: its id, and the retry budget and timeout it declares instead of the deployment's. */
+export interface DurableStepDeclaration {
+    readonly id: string;
+    readonly retry?: DurableStepRetry;
+    /** Deadline of one attempt, including its Kernel calls: one second to ten minutes. */
+    readonly timeoutMs?: number;
+}
+/**
+ * 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`.
+ */
+export type DurableStepId = string | DurableStepDeclaration;
 export interface DurableStep<DomainValue extends Domain = Domain, Definitions extends Integrations = Readonly<Record<never, never>>> {
     /**
      * Run `execute` once and journal its portable output; a replay returns the journaled output. A
      * Step may run again when its outcome was not journaled: its Mutations, durable calls and keyed
      * Integration operations are answered from their keys, and any other effect must be idempotent.
      */
-    run<Output>(id: string, execute: (authority: DurableStepAuthority<DomainValue, Definitions>) => Output | Promise<Output>): Promise<Output>;
+    run<Output>(step: DurableStepId, execute: (authority: DurableStepAuthority<DomainValue, Definitions>) => Output | Promise<Output>): Promise<Output>;
     /**
      * One journaled Query. A replay returns the result of its first run, so a later Step that depends
      * on it resends the same request whenever it is retried.
      */
-    query<Output>(id: string, query: QueryDefinition<DomainValue, void, Output>): Promise<Output>;
-    query<Input, Output>(id: string, query: QueryDefinition<DomainValue, Input, Output>, input: Input): Promise<Output>;
+    query<Output>(step: DurableStepId, query: QueryDefinition<DomainValue, void, Output>): Promise<Output>;
+    query<Input, Output>(step: DurableStepId, query: QueryDefinition<DomainValue, Input, Output>, input: Input): Promise<Output>;
     /**
      * One journaled Mutation. A Step replayed after its commit receives the result of that commit
      * from the Kernel's receipt instead of writing again.
      */
-    mutate<Input, Output>(id: string, mutation: Mutation<DomainValue, Input, Output>, input: Input): Promise<Output>;
+    mutate<Input, Output>(step: DurableStepId, mutation: Mutation<DomainValue, Input, Output>, input: Input): Promise<Output>;
 }
 type DurableSelfOf<Callable> = Callable extends ResolvedMethod<unknown, unknown, false> ? {
     readonly self: NodeId;
@@ -116,6 +147,14 @@ 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. */
+    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.
+     */
+    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>;

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

@@ -1,6 +1,6 @@
 export { defineWorkflow, isWorkflow } from './define.js';
 export type { InlineWorkflowContext, WorkflowContext } from './context.js';
-export type { DurableCallable, DurableExecution, DurableStep, DurableStepAuthority, DurableWorkflowContext, SignalOutcome, } from './durable.js';
+export type { DurableCallable, DurableExecution, DurableStep, DurableStepAuthority, DurableStepDeclaration, DurableStepId, DurableStepRetry, DurableWorkflowContext, SignalOutcome, } from './durable.js';
 export type { CallableAtWorkflowAddress, Workflow, WorkflowAddress, WorkflowCallable, WorkflowDefinition, WorkflowOptions, } from './workflow.js';
 export * as step from './step/index.js';
 export * as runner from './runner/index.js';

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

@@ -13,20 +13,12 @@ declare const WORKFLOW_SCHEMA: unique symbol;
 /** Options of one Workflow implementation. */
 export interface WorkflowOptions<out Errors extends DeclaredErrors = DeclaredErrors> {
     readonly errors?: Errors;
-    /**
-     * Durable only. Compatibility token journaled first by every run: keep it while a redeployment
-     * can replay the journals of running Executions, change it when it cannot, and those runs pause
-     * until they are resumed on compatible code or cancelled.
-     */
-    readonly compat?: string;
 }
 /** Sealed multi-step Workflow awaiting canonical callable association by Runtime admission. */
 export interface WorkflowDefinition<Schema extends schema.DomainSchema = schema.DomainSchema, Address extends WorkflowAddress<Schema> = WorkflowAddress<Schema>, Definitions extends Integrations = Readonly<Record<never, never>>, Errors extends DeclaredErrors = NoDeclaredErrors> {
     readonly kind: 'workflow';
     readonly address: Address;
     readonly run: Workflow<CallableAtWorkflowAddress<Schema, Address>, Definitions, ResolvedDomainOf<Schema>, Errors>;
-    /** Durable compatibility token; absent means the default token. */
-    readonly compat?: string;
     /** Invariant type-only Schema witness; absent from emitted JavaScript. */
     readonly [WORKFLOW_SCHEMA]: (schema: Schema) => Schema;
 }

package/dist/deployment/address/configuration.d.ts

@@ -67,6 +67,7 @@ export interface FrozenDurableOptions {
     readonly retry?: {
         readonly initialIntervalMs?: number;
         readonly maxAttempts?: number;
+        readonly maxDurationMs?: number;
         readonly maxIntervalMs?: number;
     };
     readonly stepTimeoutMs?: number;

package/dist/deployment/address/configuration.js

@@ -195,11 +195,12 @@ function durableOptionsOf(input) {
     const options = input;
     let retry;
     if (Object.hasOwn(options, 'retry')) {
-        exact(options.retry, [], ['initialIntervalMs', 'maxAttempts', 'maxIntervalMs']);
+        exact(options.retry, [], ['initialIntervalMs', 'maxAttempts', 'maxDurationMs', 'maxIntervalMs']);
         const value = options.retry;
         retry = Object.freeze({
             ...optional(value, 'initialIntervalMs'),
             ...optional(value, 'maxAttempts'),
+            ...optional(value, 'maxDurationMs'),
             ...optional(value, 'maxIntervalMs'),
         });
     }

package/dist/execution/index.d.ts

@@ -3,4 +3,5 @@ export type { ExecutionContext, ServedDomain, ServeInput } from './serve.js';
 export { DEFAULT_MEMORY_CACHE_ENTRIES, memoryCache, type DeploymentCache, type MemoryCacheOptions, } from './cache/index.js';
 export { createIdentity, maximumExchangeTtl, type ExchangeOptions, type Identity, type IdentityInput, } from './identity/index.js';
 export type { DurableEngine, DurableServing, DurableServingProvider } from './workflows/index.js';
+export { DURABLE_ENGINE_EXPORTS } from './workflows/options.js';
 export { isCanonicalDurableRequest } from './workflows/route.js';

package/dist/execution/index.js

@@ -1,4 +1,5 @@
 export { serve } from './serve.js';
 export { DEFAULT_MEMORY_CACHE_ENTRIES, memoryCache, } from './cache/index.js';
 export { createIdentity, maximumExchangeTtl, } from './identity/index.js';
+export { DURABLE_ENGINE_EXPORTS } from './workflows/options.js';
 export { isCanonicalDurableRequest } from './workflows/route.js';

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

@@ -15,6 +15,11 @@ export interface DurableEngine {
         readonly metadata?: Record<string, string>;
     }) => Error;
     readonly CancelledError: abstract new (...input: never[]) => Error;
+    /** A failure inside `run` that the engine attempts again no earlier than `retryAfter` ms. */
+    readonly RetryableError: new (message: string, options?: {
+        readonly retryAfter?: number;
+        readonly cause?: unknown;
+    }) => Error;
     /** The rejection of `orTimeout` once its duration elapses first. */
     readonly TimeoutError: abstract new (...input: never[]) => Error;
 }
@@ -27,6 +32,8 @@ export interface EngineWorkflowDefinition {
     readonly options: {
         readonly workflowRetention: number;
         readonly retryPolicy: EngineRetryPolicy;
+        /** How long an attempt may run without progress before the engine aborts it. */
+        readonly abortTimeout: number;
     };
 }
 export interface EngineRetryPolicy {
@@ -36,6 +43,17 @@ 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.
@@ -46,7 +64,7 @@ export interface EnginePromise<Output> extends PromiseLike<Output> {
 }
 /** Journaled operations of one workflow run. */
 export interface EngineWorkflowContext {
-    run<Output>(name: string, action: () => Promise<Output>): PromiseLike<Output>;
+    run<Output>(name: string, action: () => Promise<Output>, options?: EngineRunOptions): PromiseLike<Output>;
     sleep(durationMs: number, name?: string): PromiseLike<void>;
     promise(name: string): {
         get(): EnginePromise<unknown>;

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

@@ -1,11 +1,46 @@
 import type { DurableEngine } from './engine.js';
+/** Failure code of an Execution whose Workflow did not catch a Step that spent its retry budget. */
+export declare const STEP_EXHAUSTED = "STEP_EXHAUSTED";
+/** A Kernel refusal as the wire names it: its protocol code and, when given, its reason code. */
+export interface KernelRefusal {
+    readonly code: number;
+    readonly reason?: string;
+}
 /**
- * Encode a declared business error of `definition` as a terminal engine failure, or return
- * undefined for any other error, which the engine retries.
+ * 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.
+ */
+export declare class StepExhausted extends Error {
+    readonly step: string;
+    readonly refusal?: KernelRefusal;
+    constructor(step: string, refusal?: KernelRefusal);
+}
+/** 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. */
+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.
  */
 export declare function terminalFailure(engine: DurableEngine, cause: unknown, definition: object): Error | undefined;
 /**
- * The declared business error a journaled Step failed with, rebuilt through the definition's own
- * factory, so a replay throws what the live run threw.
+ * What a journaled Step failed with, as the Workflow sees it: its declared business error, rebuilt
+ * through the definition's own factory, or `StepExhausted` once the engine spent its retry budget
+ * or the Step threw an exhaustion caught from an earlier Step. A replay throws what the live run
+ * threw.
  */
-export declare function replayedFailure(engine: DurableEngine, cause: unknown, definition: object): Error | undefined;
+export declare function replayedFailure(engine: DurableEngine, cause: unknown, definition: object, step: string): Error | undefined;

package/dist/execution/workflows/failure.js

@@ -1,6 +1,101 @@
 import { declaredErrorFactory, declaredErrorOf } from '../../application/error/index.js';
+import { ResponseError, retryAfterOf } 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. */
+export const STEP_EXHAUSTED = 'STEP_EXHAUSTED';
+/** The longest delay a Step attempt may ask for, as the Kernel bounds a `retryAfterMs` hint. */
+const MAXIMUM_RETRY_AFTER_MS = 3_600_000;
+/** How deep a failure's causes are searched for the Kernel refusal behind it. */
+const MAXIMUM_CAUSE_DEPTH = 8;
+const REASON_CODE = /^[A-Z][A-Z0-9_]{0,63}$/u;
+/**
+ * The mark a failed attempt's message carries when the Kernel refused it. The engine journals only
+ * that message, and gives back the last one when the budget is spent.
+ */
+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.
+ */
+export class StepExhausted extends Error {
+    step;
+    refusal;
+    constructor(step, refusal) {
+        super(`Workflow Step ${step} exhausted its retries.`);
+        this.name = 'StepExhausted';
+        this.step = step;
+        if (refusal !== undefined)
+            this.refusal = refusal;
+    }
+}
+/** The Kernel refusal behind `cause`, itself or one of its causes. */
+export function kernelRefusalOf(cause) {
+    let current = cause;
+    for (let depth = 0; depth < MAXIMUM_CAUSE_DEPTH; depth += 1) {
+        if (current instanceof ResponseError) {
+            const reason = current.reason?.code;
+            return Object.freeze({
+                code: current.code,
+                ...(reason !== undefined && REASON_CODE.test(reason) ? { reason } : {}),
+            });
+        }
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        current = current.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)) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    if (refusal === undefined)
+        return message;
+    const reason = refusal.reason === undefined ? '' : ` ${refusal.reason}`;
+    return `[kernel refusal ${refusal.code}${reason}] ${message}`;
+}
+/** The refusal the last attempt's message names, if the Kernel refused it. */
+function refusalIn(message) {
+    const marks = [...message.matchAll(REFUSAL_MARK)];
+    const last = marks.at(-1);
+    if (last === undefined)
+        return undefined;
+    return Object.freeze({
+        code: Number(last[1]),
+        ...(last[2] === undefined ? {} : { reason: last[2] }),
+    });
+}
+/** A Step attempt's failure that asks the engine to wait `delayMs` before the next attempt. */
+export class StepRetryAfter extends Error {
+    delayMs;
+    constructor(delayMs, cause) {
+        if (!Number.isSafeInteger(delayMs) || delayMs < 0 || delayMs > MAXIMUM_RETRY_AFTER_MS) {
+            throw new TypeError(`A Step retry delay must be an integer between 0 and ${MAXIMUM_RETRY_AFTER_MS} ms.`);
+        }
+        super(cause instanceof Error ? cause.message : `Workflow Step asked to retry after ${delayMs} ms.`, cause === undefined ? undefined : { cause });
+        this.name = 'StepRetryAfter';
+        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,
@@ -8,10 +103,24 @@ const STATUS = {
     UNSUPPORTED: 422,
 };
 /**
- * Encode a declared business error of `definition` as a terminal engine failure, or return
- * undefined for any other error, which the engine retries.
+ * 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.
  */
 export function terminalFailure(engine, cause, definition) {
+    if (cause instanceof StepExhausted) {
+        return new engine.TerminalError(cause.message, {
+            metadata: {
+                [FAILURE]: JSON.stringify({
+                    code: STEP_EXHAUSTED,
+                    message: cause.message,
+                    details: {
+                        step: cause.step,
+                        ...(cause.refusal === undefined ? {} : { refusal: cause.refusal }),
+                    },
+                }),
+            },
+        });
+    }
     const declared = declaredErrorOf(cause, definition);
     if (declared === undefined)
         return undefined;
@@ -28,16 +137,24 @@ export function terminalFailure(engine, cause, definition) {
     });
 }
 /**
- * The declared business error a journaled Step failed with, rebuilt through the definition's own
- * factory, so a replay throws what the live run threw.
+ * What a journaled Step failed with, as the Workflow sees it: its declared business error, rebuilt
+ * through the definition's own factory, or `StepExhausted` once the engine spent its retry budget
+ * or the Step threw an exhaustion caught from an earlier Step. A replay throws what the live run
+ * threw.
  */
-export function replayedFailure(engine, cause, definition) {
+export function replayedFailure(engine, cause, definition, step) {
     if (!(cause instanceof engine.TerminalError) || cause instanceof engine.CancelledError) {
         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.
     if (encoded === undefined)
-        return undefined;
+        return new StepExhausted(step, refusalIn(cause.message));
     const failure = JSON.parse(encoded);
+    // Only a declared business error has a family, so a declared code may be STEP_EXHAUSTED too.
+    if (failure.family === undefined && failure.code === STEP_EXHAUSTED) {
+        const details = failure.details;
+        return new StepExhausted(details.step, details.refusal);
+    }
     return declaredErrorFactory(definition)(failure.code, failure.details);
 }

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

@@ -1,4 +1,4 @@
-export type { DurableEngine, EnginePromise, EngineRetryPolicy, EngineSharedContext, EngineWorkflowContext, EngineWorkflowDefinition, } from './engine.js';
-export { durableServing, type AdmittedDurableServing, type DurableServing, type DurableServingProvider, } from './options.js';
+export type { DurableEngine, EnginePromise, EngineRetryPolicy, EngineRunOptions, EngineSharedContext, EngineWorkflowContext, EngineWorkflowDefinition, } from './engine.js';
+export { DURABLE_ENGINE_EXPORTS, durableServing, 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/index.js

@@ -1,3 +1,3 @@
-export { durableServing, } from './options.js';
+export { DURABLE_ENGINE_EXPORTS, durableServing, } from './options.js';
 export { createDurableReceiver } from './receiver.js';
 export { isDurableRequest, isCanonicalDurableRequest } from './route.js';

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

@@ -1,5 +1,6 @@
 import type { Fetch } from '@astrale-os/kernel-client';
-import type { DurableEngine, EngineRetryPolicy } from './engine.js';
+import type { DurableStepRetry } from '../../application/workflow/index.js';
+import type { DurableEngine, EngineRetryPolicy, EngineRunOptions } from './engine.js';
 /** Serving configuration of the durable Workflows of one deployment. */
 export interface DurableServing {
     /** The Restate SDK Fetch build of this platform. */
@@ -12,13 +13,13 @@ export interface DurableServing {
      * default.
      */
     readonly retentionMs?: number;
-    /** Attempts of a failing run before it pauses for `resume` or `cancel`. The Host caps them. */
-    readonly retry?: {
-        readonly maxAttempts?: number;
-        readonly initialIntervalMs?: number;
-        readonly maxIntervalMs?: number;
-    };
-    /** Deadline of one Step, including its Kernel calls. One minute by default. */
+    /**
+     * 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.
+     */
+    readonly retry?: DurableStepRetry;
+    /** Deadline of one Step attempt that declares none, including its Kernel calls. One minute by default. */
     readonly stepTimeoutMs?: number;
 }
 /** Resolve a deployment's engine only when its durable receiver is first requested. */
@@ -27,8 +28,34 @@ export interface AdmittedDurableServing {
     readonly engine: DurableEngine;
     readonly fetch: Fetch;
     readonly retentionMs: number;
+    /** Attempts of a run that fails outside any Step, before the engine pauses it. */
     readonly retryPolicy: EngineRetryPolicy;
-    readonly stepTimeoutMs: number;
+    /** 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. */
+export interface StepServing {
+    readonly retry: EngineRunOptions;
+    readonly timeoutMs: number;
 }
+/**
+ * The members of the Restate SDK Fetch entrypoint the durable receiver uses, which a platform's
+ * engine module must export.
+ */
+export declare const DURABLE_ENGINE_EXPORTS: readonly ["createEndpointHandler", "workflow", "TerminalError", "CancelledError", "RetryableError", "TimeoutError"];
+/**
+ * How long the engine lets an attempt run without progress before it aborts it, declared on every
+ * Workflow service. Restate's own default is ten minutes, which a ten-minute Step would race: the
+ * margin lets a Step's own timeout fail the attempt, and report it, before the engine cuts it.
+ */
+export declare const ENGINE_ABORT_TIMEOUT_MS: number;
 /** Capture one durable serving configuration, failing closed on any gap. */
 export declare function durableServing(input: DurableServing): AdmittedDurableServing;
+/**
+ * What one Step is held to: the retry budget and timeout it declares, in place of `fallback`'s. A
+ * declared limit replaces both limits of the fallback; an undeclared interval keeps the fallback's.
+ */
+export declare function stepServing(declared: {
+    readonly retry?: DurableStepRetry | undefined;
+    readonly timeoutMs?: number | undefined;
+}, fallback: StepServing): StepServing;

package/dist/execution/workflows/options.js

@@ -1,5 +1,32 @@
+/**
+ * The members of the Restate SDK Fetch entrypoint the durable receiver uses, which a platform's
+ * engine module must export.
+ */
+export const DURABLE_ENGINE_EXPORTS = Object.freeze([
+    'createEndpointHandler',
+    'workflow',
+    'TerminalError',
+    'CancelledError',
+    'RetryableError',
+    'TimeoutError',
+]);
 const HOUR_MS = 60 * 60_000;
 const DAY_MS = 24 * HOUR_MS;
+const DEFAULT_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;
+/**
+ * How long the engine lets an attempt run without progress before it aborts it, declared on every
+ * Workflow service. Restate's own default is ten minutes, which a ten-minute Step would race: the
+ * margin lets a Step's own timeout fail the attempt, and report it, before the engine cuts it.
+ */
+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,
+});
 /** Capture one durable serving configuration, failing closed on any gap. */
 export function durableServing(input) {
     if (input === null ||
@@ -15,45 +42,81 @@ export function durableServing(input) {
     const engine = input.engine;
     if (engine === null ||
         typeof engine !== 'object' ||
-        typeof engine.createEndpointHandler !== 'function' ||
-        typeof engine.workflow !== 'function' ||
-        typeof engine.TerminalError !== 'function' ||
-        typeof engine.CancelledError !== 'function' ||
-        typeof engine.TimeoutError !== 'function') {
+        DURABLE_ENGINE_EXPORTS.some((member) => typeof engine[member] !== 'function')) {
         invalid('Durable serving requires the Restate SDK Fetch entrypoint of this platform.');
     }
     const fetch = input.fetch ?? globalThis.fetch.bind(globalThis);
     if (typeof fetch !== 'function')
         invalid('Durable serving requires Fetch for engine discovery.');
-    const retry = input.retry ?? {};
-    if (retry === null ||
-        typeof retry !== 'object' ||
-        Array.isArray(retry) ||
-        Reflect.ownKeys(retry).some((key) => key !== 'maxAttempts' && key !== 'initialIntervalMs' && key !== 'maxIntervalMs')) {
-        invalid('Durable retry options are invalid.');
-    }
-    const initialInterval = bounded(retry.initialIntervalMs, 1_000, 1, HOUR_MS, 'initialIntervalMs');
-    const maxInterval = bounded(retry.maxIntervalMs, 60_000, initialInterval, DAY_MS, 'maxIntervalMs');
+    const step = stepServing({ retry: input.retry, timeoutMs: input.stepTimeoutMs }, { retry: DEFAULT_STEP_RETRY, timeoutMs: 60_000 });
     return Object.freeze({
         engine: Object.freeze({
             createEndpointHandler: engine.createEndpointHandler.bind(engine),
             workflow: engine.workflow.bind(engine),
             TerminalError: engine.TerminalError,
             CancelledError: engine.CancelledError,
+            RetryableError: engine.RetryableError,
             TimeoutError: engine.TimeoutError,
         }),
         fetch,
         retentionMs: bounded(input.retentionMs, 7 * DAY_MS, HOUR_MS, 365 * DAY_MS, 'retentionMs'),
         retryPolicy: Object.freeze({
-            maxAttempts: bounded(retry.maxAttempts, 20, 1, 1_000, 'maxAttempts'),
+            maxAttempts: input.retry?.maxAttempts ?? DEFAULT_ATTEMPTS,
             onMaxAttempts: 'pause',
-            initialInterval,
-            maxInterval,
-            exponentiationFactor: 2,
+            initialInterval: step.retry.initialRetryInterval,
+            maxInterval: step.retry.maxRetryInterval,
+            exponentiationFactor: step.retry.retryIntervalFactor,
         }),
-        stepTimeoutMs: bounded(input.stepTimeoutMs, 60_000, 1_000, HOUR_MS, 'stepTimeoutMs'),
+        step,
     });
 }
+/**
+ * What one Step is held to: the retry budget and timeout it declares, in place of `fallback`'s. A
+ * declared limit replaces both limits of the fallback; an undeclared interval keeps the fallback's.
+ */
+export function stepServing(declared, fallback) {
+    const retry = declared.retry;
+    if (retry === undefined) {
+        return Object.freeze({
+            retry: fallback.retry,
+            timeoutMs: stepTimeout(declared.timeoutMs, fallback.timeoutMs),
+        });
+    }
+    if (retry === null ||
+        typeof retry !== 'object' ||
+        Array.isArray(retry) ||
+        Reflect.ownKeys(retry).some((key) => key !== 'maxAttempts' &&
+            key !== 'maxDurationMs' &&
+            key !== 'initialIntervalMs' &&
+            key !== 'maxIntervalMs')) {
+        invalid('Durable retry options are invalid.');
+    }
+    const limited = retry.maxAttempts !== undefined || retry.maxDurationMs !== undefined;
+    const maxAttempts = limited
+        ? optionalBounded(retry.maxAttempts, 1, 1_000, 'maxAttempts')
+        : fallback.retry.maxRetryAttempts;
+    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');
+    return Object.freeze({
+        retry: Object.freeze({
+            ...(maxAttempts === undefined ? {} : { maxRetryAttempts: maxAttempts }),
+            ...(maxDuration === undefined ? {} : { maxRetryDuration: maxDuration }),
+            initialRetryInterval: initialInterval,
+            maxRetryInterval: maxInterval,
+            retryIntervalFactor: fallback.retry.retryIntervalFactor,
+        }),
+        timeoutMs: stepTimeout(declared.timeoutMs, fallback.timeoutMs),
+    });
+}
+function stepTimeout(input, fallback) {
+    return bounded(input, fallback, 1_000, MAXIMUM_STEP_TIMEOUT_MS, 'Step timeout');
+}
+function optionalBounded(input, minimum, maximum, label) {
+    return input === undefined ? undefined : bounded(input, minimum, minimum, maximum, label);
+}
 function bounded(input, fallback, minimum, maximum, label) {
     if (input === undefined)
         return fallback;

package/dist/execution/workflows/receiver.js

@@ -1,4 +1,5 @@
 import { workflowEngineDiscovery, WorkflowEngineUnavailable } from './discovery.js';
+import { ENGINE_ABORT_TIMEOUT_MS } from './options.js';
 import { durableRoute } from './route.js';
 import { durableHandlers } from './run.js';
 import { sessionSteps } from './steps.js';
@@ -60,6 +61,7 @@ export function createDurableReceiver(input) {
                     options: {
                         workflowRetention: input.serving.retentionMs,
                         retryPolicy: input.serving.retryPolicy,
+                        abortTimeout: ENGINE_ABORT_TIMEOUT_MS,
                     },
                 });
                 try {

package/dist/execution/workflows/run.js

@@ -4,10 +4,9 @@ import { acceptStepOutput } from '../../application/workflow/step/output.js';
 import { ResponseError } from '../../platform/client/index.js';
 import { validateOutput } from '../invocation/result/index.js';
 import { decodeEnvelope } from './envelope.js';
-import { replayedFailure, terminalFailure } from './failure.js';
+import { delayedRetry, replayedFailure, StepExhausted, StepRetryAfter, attemptFailure, terminalFailure, } from './failure.js';
+import { stepServing } from './options.js';
 import { keySequence } from './steps.js';
-/** Token of a Workflow that declares none. */
-const DEFAULT_COMPAT = '0';
 const MAXIMUM_SLEEP_MS = 365 * 24 * 60 * 60_000;
 const MAXIMUM_SIGNAL_NAME = 128;
 /** Bounds of one `result` wait and of the durable pause between two of them. */
@@ -37,15 +36,9 @@ async function run(input, context, raw) {
     const { workflow, serving } = input;
     const { engine } = serving;
     const definition = workflow.definition;
-    // Journaled first. A redeployment that changed the token cannot replay this run: it fails every
-    // attempt with this reason until the engine pauses it, then `resume` on compatible code or cancel.
-    const token = definition.compat ?? DEFAULT_COMPAT;
-    const recorded = await context.run('compat', async () => token);
-    if (recorded !== token) {
-        throw new Error(`Workflow ${workflow.address} started under compat token ${JSON.stringify(recorded)}; ` +
-            `this deployment declares ${JSON.stringify(token)}.`);
-    }
-    // Code that cannot read what the Kernel recorded pauses the run the same way.
+    // A run replays the code of the release that started it, each release at its own URL. Code
+    // served in place of it replays the journal: the engine refuses a journal whose Steps no longer
+    // match, and code that cannot read what the Kernel recorded fails every attempt; both pause.
     const envelope = admitted(workflow, raw, input.kernel);
     const durable = durableContext(input, context, envelope);
     let output;
@@ -82,13 +75,25 @@ function durableContext(input, context, envelope) {
     /**
      * One journaled unit of work holding the capabilities of an Action as the Domain alone. Its
      * Mutations, durable calls and Integration calls share one key sequence derived from its name.
+     * With a `retry` budget, the engine retries a failed attempt within it, after its backoff or the
+     * delay the failure prescribes, and the Step throws `StepExhausted` once it is spent; without
+     * one, a failed attempt fails the run's attempt, which the engine retries until it pauses.
      */
-    const journal = (name, execute) => Promise.resolve(context.run(name, async () => {
-        const lifetime = { deadline: Date.now() + serving.stepTimeoutMs, signal };
-        const next = await keySequence(execution.id, name);
-        const step = input.steps({ name, execution, next, lifetime });
+    const journal = (id, name, timeoutMs, retry, execute) => Promise.resolve(context.run(name, async () => {
+        const expiry = new AbortController();
+        const timer = setTimeout(() => expiry.abort(new Error(`Workflow Step ${id} exceeded its ${timeoutMs} ms timeout.`)), timeoutMs);
+        let step;
         try {
-            const output = await execute(step.authority);
+            const lifetime = {
+                deadline: Date.now() + timeoutMs,
+                signal: AbortSignal.any([signal, expiry.signal]),
+            };
+            const next = await keySequence(execution.id, name);
+            const { authority } = (step = input.steps({ name, execution, next, lifetime }));
+            const output = await Promise.race([
+                Promise.resolve().then(() => execute(authority)),
+                expired(expiry.signal),
+            ]);
             try {
                 return acceptStepOutput(output);
             }
@@ -97,26 +102,30 @@ function durableContext(input, context, envelope) {
             }
         }
         catch (cause) {
-            throw terminalFailure(engine, cause, definition) ?? cause;
+            throw (terminalFailure(engine, cause, definition) ??
+                delayedRetry(engine, cause) ??
+                attemptFailure(cause));
         }
         finally {
-            step.close();
+            clearTimeout(timer);
+            step?.close();
         }
-    })).catch((cause) => {
-        throw replayedFailure(engine, cause, definition) ?? cause;
+    }, retry)).catch((cause) => {
+        throw replayedFailure(engine, cause, definition, id) ?? cause;
     });
-    const step = (id, execute) => {
+    const step = (declared, execute) => {
         let accepted;
         try {
-            accepted = acceptStepId(id);
-            if (steps.has(accepted))
-                throw new TypeError(`Workflow Step ${accepted} occurs more than once.`);
+            accepted = stepDeclaration(declared, serving.step);
+            if (steps.has(accepted.id))
+                throw new TypeError(`Workflow Step ${accepted.id} occurs more than once.`);
         }
         catch (cause) {
             return Promise.reject(cause);
         }
-        steps.add(accepted);
-        return journal(`step:${accepted}`, execute);
+        steps.add(accepted.id);
+        const { held } = accepted;
+        return journal(accepted.id, `step:${accepted.id}`, held.timeoutMs, held.retry, execute);
     };
     return Object.freeze({
         domain,
@@ -156,12 +165,16 @@ function durableContext(input, context, envelope) {
             }
         },
         cancelled: (error) => error instanceof engine.CancelledError,
+        exhausted: (error) => error instanceof StepExhausted,
+        retryAfter: (delayMs, cause) => new StepRetryAfter(delayMs, cause),
         async awaitExecution(target) {
             for (let poll = 1;; poll++) {
-                const polled = await journal(`await:${target.id}:${poll}`, async ({ kernel }) => {
+                // A poll is no Step of the author's: it has no budget, so an outage pauses the run instead.
+                const name = `await:${target.id}:${poll}`;
+                const polled = await journal(name, name, serving.step.timeoutMs, undefined, async ({ kernel }) => {
                     try {
                         const outcome = await kernel.execution.result(target, {
-                            waitMs: Math.min(AWAIT_WAIT_MS, Math.floor(serving.stepTimeoutMs / 2)),
+                            waitMs: Math.min(AWAIT_WAIT_MS, Math.floor(serving.step.timeoutMs / 2)),
                         });
                         return { ended: true, outcome };
                     }
@@ -180,6 +193,33 @@ function durableContext(input, context, envelope) {
         ...(execution.receiver === undefined ? {} : { self: execution.receiver }),
     });
 }
+/** Admit a Step's id, and its declared retry budget and timeout over the deployment's. */
+function stepDeclaration(declared, fallback) {
+    if (typeof declared === 'string')
+        return { id: acceptStepId(declared), held: fallback };
+    if (declared === null ||
+        typeof declared !== 'object' ||
+        Array.isArray(declared) ||
+        Reflect.ownKeys(declared).some((key) => key !== 'id' && key !== 'retry' && key !== 'timeoutMs')) {
+        throw new TypeError('A Workflow Step declaration takes only id, retry and timeoutMs.');
+    }
+    return {
+        id: acceptStepId(declared.id),
+        held: stepServing({ retry: declared.retry, timeoutMs: declared.timeoutMs }, fallback),
+    };
+}
+/**
+ * Rejects with the abort reason once `signal` aborts, at once if it already has: a timeout may fire
+ * while the attempt derives its keys. Never settles otherwise.
+ */
+function expired(signal) {
+    return new Promise((_, reject) => {
+        if (signal.aborted)
+            reject(signal.reason);
+        else
+            signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+    });
+}
 function signalRequest(input) {
     if (input === null ||
         typeof input !== 'object' ||

package/dist/testing/durable/engine.d.ts

@@ -1,7 +1,7 @@
 import type { ActionOutputOf, ResolvedDomainOf } from '../../application/action/index.js';
 import type { DeclaredErrors } from '../../application/error/index.js';
 import type { Integrations, Providers } from '../../application/integration/index.js';
-import type { CallableAtWorkflowAddress, WorkflowAddress, WorkflowDefinition } from '../../application/workflow/index.js';
+import type { CallableAtWorkflowAddress, DurableStepRetry, WorkflowAddress, WorkflowDefinition } from '../../application/workflow/index.js';
 import type { ExecutionOutcome, ExecutionState } from '../../platform/client/session/index.js';
 import type { NodeId } from '../../platform/graph/node/index.js';
 import type { CallableInputOf, ResolvedMethod, schema } from '../../platform/schema/index.js';
@@ -10,13 +10,18 @@ import type { TestStepCapabilities } from './steps.js';
 export interface TestEngineOptions {
     /** Start of the virtual clock, in Unix milliseconds; the current time by default. */
     readonly now?: number;
-    /** Attempts of a run before it pauses; 20 by default, as on a Host. */
-    readonly maxAttempts?: number;
+    /**
+     * The deployment's `durable.retry`: the budget of every Step that declares none, 20 attempts by
+     * default, and with `maxAttempts` the attempts of a run failing outside any Step before it pauses.
+     */
+    readonly retry?: DurableStepRetry;
 }
 /**
  * An in-memory workflow engine that runs durable Workflows with the receiver a Host serves: it
- * journals each Step, replays the journal on every attempt, retries failed attempts, keeps timers
- * on a virtual clock, buffers signals, pauses after the last attempt and cancels cooperatively.
+ * journals each Step, replays the journal on every attempt, retries a failed Step within its budget
+ * and fails it once the budget is spent, keeps timers on a virtual clock, buffers signals, pauses a
+ * run failing outside any Step after its last attempt and cancels cooperatively. A retry does not
+ * wait out its backoff, but the backoff it skips counts toward the Step's `maxDurationMs`.
  */
 export interface TestEngine {
     /** The virtual clock, in Unix milliseconds. */
@@ -57,7 +62,10 @@ export interface TestExecution<Output> {
     readonly state: Extract<ExecutionState, 'running' | 'waiting' | 'paused' | 'completed' | 'failed' | 'cancelled'>;
     /** Present once the Execution ended, as `Execution.result` answers it. */
     readonly outcome: ExecutionOutcome<Output> | undefined;
-    /** What the last failed attempt threw; it is why a paused Execution paused. */
+    /**
+     * What the last failed attempt threw: why a paused Execution paused, or what the last attempt of
+     * an exhausted Step threw, which its `STEP_EXHAUSTED` outcome does not carry.
+     */
     readonly failure: unknown;
     /** Attempts made so far, replays included. */
     readonly attempts: number;
@@ -88,6 +96,8 @@ export type TestJournalEntry = {
     readonly kind: 'run';
     readonly name: string;
     readonly settled: boolean;
+    /** Times the Step ran, retries and interruptions included; a replay runs it no more. */
+    readonly attempts: number;
     readonly value?: unknown;
     readonly error?: unknown;
 } | {

package/dist/testing/durable/engine.js

@@ -8,8 +8,6 @@ import { NodeId as nodeId } from '../../platform/graph/node/index.js';
 import { testSteps } from './steps.js';
 /** Kernel every test Execution names; Steps never reach it. */
 const TEST_KERNEL = issuer.accept('https://kernel.test.astrale.invalid');
-/** Attempts before a run pauses, as on a Host. */
-const DEFAULT_MAXIMUM_ATTEMPTS = 20;
 /** Microtask turns without progress after which a blocked attempt counts as suspended. */
 const QUIET_TURNS = 64;
 /** Metadata the Kernel reads a declared failure from. */
@@ -37,6 +35,15 @@ class TimeoutError extends TerminalError {
         this.name = 'TimeoutError';
     }
 }
+class RetryableError extends Error {
+    retryAfter;
+    constructor(message, options) {
+        super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'RetryableError';
+        if (options?.retryAfter !== undefined)
+            this.retryAfter = options.retryAfter;
+    }
+}
 /** The attempt lost its Step result on purpose; the engine retries it. */
 class Interruption extends Error {
     constructor(step) {
@@ -57,14 +64,16 @@ const ENGINE = Object.freeze({
     workflow: (definition) => definition,
     TerminalError,
     CancelledError,
+    RetryableError,
     TimeoutError,
 });
 /** Create an in-memory workflow engine for tests. */
 export function createTestEngine(options = {}) {
-    const maxAttempts = options.maxAttempts ?? DEFAULT_MAXIMUM_ATTEMPTS;
-    if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1) {
-        throw new TypeError('Test engine maxAttempts must be a positive integer.');
-    }
+    const serving = durableServing({
+        engine: ENGINE,
+        ...(options.retry === undefined ? {} : { retry: options.retry }),
+    });
+    const maxAttempts = serving.retryPolicy.maxAttempts;
     let now = options.now ?? Date.now();
     if (!Number.isFinite(now))
         throw new TypeError('Test engine now must be finite.');
@@ -77,7 +86,7 @@ export function createTestEngine(options = {}) {
         },
         async start(workflow, input) {
             sequence += 1;
-            const run = new TestRun(workflow, input, clock, maxAttempts, sequence);
+            const run = new TestRun(workflow, input, clock, serving, maxAttempts, sequence);
             runs.add(run);
             await run.settle();
             return run.execution;
@@ -108,7 +117,7 @@ class TestRun {
     handlers;
     envelope;
     execution;
-    constructor(workflow, input, clock, maxAttempts, sequence) {
+    constructor(workflow, input, clock, serving, maxAttempts, sequence) {
         this.clock = clock;
         this.maxAttempts = maxAttempts;
         const domain = input.schema;
@@ -122,7 +131,7 @@ class TestRun {
             kernel: TEST_KERNEL,
             workflow: admitted,
             domain,
-            serving: durableServing({ engine: ENGINE }),
+            serving,
             steps: testSteps({
                 domain,
                 capabilities: (input.capabilities ?? {}),
@@ -158,6 +167,10 @@ class TestRun {
                 this.end({ kind: 'completed', value: attempted.value });
                 return;
             }
+            if (attempted.kind === 'retried') {
+                this.failure = attempted.error;
+                continue;
+            }
             const { error } = attempted;
             if (error instanceof TerminalError) {
                 this.end(outcomeOf(error));
@@ -186,7 +199,7 @@ class TestRun {
             .then(() => this.handlers.run(attempt.context, this.envelope))
             .then((value) => ({ kind: 'completed', value }), (error) => ({ kind: 'failed', error }))
             .finally(() => attempt.finish());
-        return Promise.race([running, attempt.suspended()]).finally(() => attempt.finish());
+        return Promise.race([running, attempt.suspended(), attempt.ended]).finally(() => attempt.finish());
     }
     async signal(name, value) {
         if (this.ended)
@@ -276,12 +289,17 @@ class Attempt {
     progress = 0;
     done = false;
     controller = new AbortController();
+    end;
+    /** Settles when a Step ends the attempt without reaching the Workflow, as a retry or a crash. */
+    ended = new Promise((resolve) => {
+        this.end = resolve;
+    });
     context;
     constructor(run, mode) {
         this.run = run;
         this.mode = mode;
         this.context = Object.freeze({
-            run: (name, action) => this.journalRun(name, action),
+            run: (name, action, options) => this.journalRun(name, action, options),
             sleep: (durationMs) => this.sleep(durationMs),
             promise: (name) => ({ get: () => this.promise(name) }),
             request: () => ({ attemptCompletedSignal: this.controller.signal }),
@@ -353,7 +371,12 @@ class Attempt {
         this.progress += 1;
         return new Promise(() => { });
     }
-    journalRun(name, action) {
+    /**
+     * One journaled `run`. A failure within the budget of `options` ends the attempt before the
+     * Workflow sees it, as the engine retries the `run` with a fresh attempt; a spent budget settles
+     * the entry with a `TerminalError`. Without options, the failure reaches the Workflow.
+     */
+    journalRun(name, action, options) {
         let entry;
         try {
             entry = this.take('run', name);
@@ -369,11 +392,15 @@ class Attempt {
             return Promise.reject(new JournalMismatch(this.cursor - 1, 'a pending entry', `${name} to run again`));
         }
         this.active += 1;
+        entry.attempts = (entry.attempts ?? 0) + 1;
         return (async () => {
             try {
                 const value = await action();
-                if (this.run.interruptions.delete(name))
-                    throw new Interruption(name.replace(/^step:/u, ''));
+                if (this.run.interruptions.delete(name)) {
+                    // A crash after the effect: the run is attempted again, and the Step with it.
+                    this.end({ kind: 'failed', error: new Interruption(name.replace(/^step:/u, '')) });
+                    return this.block();
+                }
                 entry.settled = true;
                 entry.value = value;
                 return value;
@@ -382,8 +409,20 @@ class Attempt {
                 if (cause instanceof TerminalError) {
                     entry.settled = true;
                     entry.error = cause;
+                    throw cause;
                 }
-                throw cause;
+                this.run.failure = cause;
+                if (options === undefined)
+                    throw cause;
+                if (spent(entry, options)) {
+                    entry.settled = true;
+                    entry.error = new TerminalError(cause?.message ?? String(cause));
+                    throw entry.error;
+                }
+                // An attempt takes time too: a zero delay still spends a duration budget, by a millisecond.
+                entry.waitedMs = (entry.waitedMs ?? 0) + Math.max(1, delayOf(entry, options, cause));
+                this.end({ kind: 'retried', error: cause });
+                return this.block();
             }
             finally {
                 this.active -= 1;
@@ -477,6 +516,18 @@ class Attempt {
         return Promise.resolve(value);
     }
 }
+/** Whether a Step that just failed spent its budget: its attempts, or the backoff it waited. */
+function spent(entry, options) {
+    return ((options.maxRetryAttempts !== undefined && (entry.attempts ?? 0) >= options.maxRetryAttempts) ||
+        (options.maxRetryDuration !== undefined && (entry.waitedMs ?? 0) >= options.maxRetryDuration));
+}
+/** The delay before a failed Step's next attempt: the one its failure prescribes, or its backoff. */
+function delayOf(entry, options, cause) {
+    if (cause instanceof RetryableError && cause.retryAfter !== undefined)
+        return cause.retryAfter;
+    const retries = (entry.attempts ?? 1) - 1;
+    return Math.min(options.maxRetryInterval, options.initialRetryInterval * options.retryIntervalFactor ** retries);
+}
 function outcomeOf(error) {
     const declared = error.metadata?.[FAILURE];
     if (declared !== undefined) {
@@ -506,6 +557,7 @@ function snapshot(entry) {
                 kind: 'run',
                 name: entry.name,
                 settled: entry.settled,
+                attempts: entry.attempts ?? 0,
                 ...(entry.settled && entry.error === undefined ? { value: entry.value } : {}),
                 ...(entry.error === undefined ? {} : { error: entry.error }),
             });

package/dist/tooling/linter/implementations/source/workflows.js

@@ -1,10 +1,17 @@
 import ts from 'typescript';
 import { expressionType, propertyChain, unwrap, visit, visitOwnBody, } from '../../adapters/typescript/index.js';
-import { ambiguity, calls, contextPath, globalCallName, production, staticId, violation, } from './shared.js';
+import { ambiguity, calls, contextPath, globalCallName, production, propertyExpression, staticId, violation, } from './shared.js';
 // `query` and `mutate` are the durable Step sugar over `run`; each is one Step too.
 const STEP_METHODS = new Set(['run', 'query', 'mutate']);
 // Members only a durable Workflow context has: using one proves the Workflow durable.
-const DURABLE_CONTEXT_MEMBERS = new Set(['awaitSignal', 'awaitExecution', 'cancelled', 'sleep']);
+const DURABLE_CONTEXT_MEMBERS = new Set([
+    'awaitSignal',
+    'awaitExecution',
+    'cancelled',
+    'exhausted',
+    'retryAfter',
+    'sleep',
+]);
 const AUTHORITIES = new Set(['caller', 'self']);
 // Raw Kernel graph reads a Step's `kernel` offers beside `mutate`.
 const KERNEL_READS = new Set(['query', 'get', 'getOrThrow', 'neighbors']);
@@ -71,7 +78,7 @@ export const workflowRules = [
                         const method = stepMethod(node, roots);
                         if (!method)
                             return;
-                        const id = staticId(node.arguments[0]);
+                        const id = stepId(node.arguments[0]);
                         if (!id || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(id)) {
                             evidence.push(violation(file, node.arguments[0] ?? node, `Workflow ${method} step ID is not a non-empty kebab-case literal.`));
                         }
@@ -209,8 +216,11 @@ function durableSteps(project, evidence) {
                 if (!ts.isCallExpression(node))
                     return;
                 const method = stepMethod(node, roots);
-                if (method === 'query' || method === 'mutate')
+                if (!method)
+                    return;
+                if (method === 'query' || method === 'mutate' || declaredStep(node.arguments[0])) {
                     durable = true;
+                }
                 if (method !== 'run')
                     return;
                 const callback = node.arguments[1] && stepRunCallback(node.arguments[1], helpers);
@@ -218,7 +228,7 @@ function durableSteps(project, evidence) {
                     return;
                 if (callback.parameters.length > 0)
                     durable = true;
-                const id = staticId(node.arguments[0]);
+                const id = stepId(node.arguments[0]);
                 runs.push({ file, call: node, label: id ?? 'with a dynamic id', callback });
             });
             if (durable)
@@ -227,6 +237,19 @@ function durableSteps(project, evidence) {
     }
     return steps;
 }
+/** Only a durable Step takes a declaration, `{ id, retry, timeoutMs }`, in place of its id. */
+function declaredStep(argument) {
+    return argument !== undefined && ts.isObjectLiteralExpression(unwrap(argument));
+}
+/** A Step's literal id: its first argument, or the `id` of the declaration written there. */
+function stepId(argument) {
+    if (argument === undefined)
+        return undefined;
+    const value = unwrap(argument);
+    return ts.isObjectLiteralExpression(value)
+        ? staticId(propertyExpression(value, 'id'))
+        : staticId(value);
+}
 /**
  * A `step.run` callback written inline or named by one local function. Any other is not inspected;
  * FNC-NO-NEST reports it as ambiguous.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.6.0-beta.38",
+  "version": "0.6.0-beta.39",
   "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
   "keywords": [
     "astrale",