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

package/dist/execution/workflows/discovery.js

@@ -0,0 +1,151 @@
+import { paths } from '@astrale-os/kernel-protocol/issuer/paths';
+import { acceptWorkflowEngine } from '@astrale-os/kernel-protocol/issuer/workflow-engine';
+const MAXIMUM_BYTES = 16 * 1024;
+const MAXIMUM_ISSUERS = 64;
+const TTL_MS = 60_000;
+const TIMEOUT_MS = 10_000;
+/** Discovery failure never admits static keys for an issuer-prefixed request. */
+export class WorkflowEngineUnavailable extends Error {
+    name = 'WorkflowEngineUnavailable';
+}
+/** One receiver retains bounded, recently admitted engine authority and deduplicates refreshes. */
+export function workflowEngineDiscovery(fetch, now = Date.now) {
+    const bases = new Map();
+    return Object.freeze({
+        async resolve(issuer) {
+            const basis = bases.get(issuer);
+            if (basis?.pending !== undefined)
+                return basis.pending;
+            const observedAt = now();
+            if (basis?.engine !== undefined &&
+                observedAt >= basis.expiresAt - TTL_MS &&
+                observedAt < basis.expiresAt)
+                return basis.engine;
+            if (basis === undefined) {
+                if (bases.size >= MAXIMUM_ISSUERS) {
+                    // Pending requests retain their slot; arbitrary issuers cannot exceed the concurrency cap.
+                    const oldest = [...bases].find(([, value]) => value.pending === undefined);
+                    if (oldest === undefined)
+                        throw new WorkflowEngineUnavailable('Engine discovery is busy.');
+                    bases.delete(oldest[0]);
+                }
+            }
+            // A refresh owns a new basis, so a late rejection of old keys cannot discard pending work.
+            const selected = {
+                expiresAt: 0,
+                ...(basis?.rejectedAt === undefined ? {} : { rejectedAt: basis.rejectedAt }),
+            };
+            bases.set(issuer, selected);
+            const pending = discover(fetch, issuer)
+                .then((engine) => {
+                selected.engine = engine;
+                selected.expiresAt = now() + TTL_MS;
+                // Move the successfully refreshed authority to the end of the bounded cache.
+                bases.delete(issuer);
+                bases.set(issuer, selected);
+                return engine;
+            })
+                .finally(() => {
+                if (selected.pending === pending)
+                    selected.pending = undefined;
+            });
+            selected.pending = pending;
+            return pending;
+        },
+        /** A crypto provider rejected this authority; the next request must discover it again. */
+        forget(issuer, observedKeys) {
+            if (bases.get(issuer)?.engine?.identity_keys === observedKeys)
+                bases.delete(issuer);
+        },
+        /** Authentication refusal expires the basis for the next request, without replaying its body. */
+        invalidate(issuer, observedKeys) {
+            const basis = bases.get(issuer);
+            const observedAt = now();
+            if (basis?.engine?.identity_keys !== observedKeys ||
+                (basis.rejectedAt !== undefined &&
+                    observedAt >= basis.rejectedAt &&
+                    observedAt - basis.rejectedAt < TTL_MS))
+                return;
+            basis.rejectedAt = observedAt;
+            basis.expiresAt = 0;
+        },
+    });
+}
+async function discover(fetch, issuer) {
+    const url = new URL(paths(issuer).workflowEngine, issuer);
+    if (url.protocol !== 'https:')
+        throw new WorkflowEngineUnavailable('Engine discovery requires HTTPS.');
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new WorkflowEngineUnavailable('Engine discovery timed out.')), TIMEOUT_MS);
+    let expired;
+    const timeout = new Promise((_resolve, reject) => {
+        expired = () => reject(controller.signal.reason);
+        controller.signal.addEventListener('abort', expired, { once: true });
+    });
+    try {
+        return await Promise.race([readDocument(fetch, url, issuer, controller.signal), timeout]);
+    }
+    catch (cause) {
+        if (cause instanceof WorkflowEngineUnavailable)
+            throw cause;
+        throw new WorkflowEngineUnavailable('Engine discovery is unavailable or invalid.', { cause });
+    }
+    finally {
+        clearTimeout(timer);
+        controller.signal.removeEventListener('abort', expired);
+    }
+}
+async function readDocument(fetch, url, issuer, signal) {
+    const response = await fetch(url.href, {
+        method: 'GET',
+        redirect: 'manual',
+        signal: signal,
+    });
+    if (!response.ok || response.redirected || (response.url !== '' && response.url !== url.href)) {
+        await response.body?.cancel();
+        throw new WorkflowEngineUnavailable('Engine discovery did not return its document.');
+    }
+    if (signal.aborted) {
+        await response.body?.cancel();
+        signal.throwIfAborted();
+    }
+    const advertised = response.headers.get('content-length');
+    if (advertised !== null && Number(advertised) > MAXIMUM_BYTES) {
+        await response.body?.cancel();
+        throw new WorkflowEngineUnavailable('Engine discovery exceeds its byte limit.');
+    }
+    if (response.body === null)
+        throw new WorkflowEngineUnavailable('Engine discovery is empty.');
+    const reader = response.body.getReader();
+    const cancel = () => {
+        void reader.cancel(signal.reason).catch(() => { });
+    };
+    signal.addEventListener('abort', cancel, { once: true });
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            signal.throwIfAborted();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAXIMUM_BYTES)
+                throw new WorkflowEngineUnavailable('Engine discovery exceeds its byte limit.');
+            chunks.push(value);
+        }
+    }
+    finally {
+        signal.removeEventListener('abort', cancel);
+        await reader.cancel();
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    const document = JSON.parse(new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(bytes));
+    return acceptWorkflowEngine(document, issuer);
+}

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

@@ -0,0 +1,89 @@
+/**
+ * The part of the Restate TypeScript SDK's Fetch entrypoint the durable receiver uses. A runtime
+ * supplies the build for its platform: `@restatedev/restate-sdk/fetch` on Node and Bun,
+ * `@restatedev/restate-sdk-cloudflare-workers/fetch` on Cloudflare Workers, which cannot compile
+ * WebAssembly at run time. Both expose this exact surface.
+ */
+export interface DurableEngine {
+    createEndpointHandler(options: {
+        readonly services: unknown[];
+        readonly identityKeys?: string[];
+    }): (request: Request) => Promise<Response>;
+    workflow(definition: EngineWorkflowDefinition): unknown;
+    readonly TerminalError: new (message: string, options?: {
+        readonly errorCode?: number;
+        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;
+    /**
+     * The engine's own combinators, the one way to await several journaled operations together: the
+     * engine then follows them as one operation, and a replay settles them as the first run did.
+     */
+    readonly RestatePromise: EngineCombinators;
+}
+export interface EngineCombinators {
+    /** Settle once every one of `values`, promises of this engine's `run`, has settled. */
+    allSettled(values: readonly PromiseLike<unknown>[]): PromiseLike<readonly PromiseSettledResult<unknown>[]>;
+}
+export interface EngineWorkflowDefinition {
+    readonly name: string;
+    readonly handlers: {
+        readonly run: (context: EngineWorkflowContext, input: unknown) => Promise<unknown>;
+        readonly signal: (context: EngineSharedContext, input: unknown) => Promise<unknown>;
+    };
+    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 {
+    readonly maxAttempts: number;
+    readonly onMaxAttempts: 'pause' | 'kill';
+    readonly initialInterval: number;
+    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.
+ */
+export interface EnginePromise<Output> extends PromiseLike<Output> {
+    /** Settle with this promise, or reject with `TimeoutError` once `millis` elapse first. */
+    orTimeout(millis: number): PromiseLike<unknown>;
+}
+/** Journaled operations of one workflow run. */
+export interface EngineWorkflowContext {
+    run<Output>(name: string, action: () => Promise<Output>, options?: EngineRunOptions): PromiseLike<Output>;
+    sleep(durationMs: number, name?: string): PromiseLike<void>;
+    promise(name: string): {
+        get(): EnginePromise<unknown>;
+    };
+    request(): {
+        readonly attemptCompletedSignal: AbortSignal;
+    };
+}
+export interface EngineSharedContext {
+    promise<Output>(name: string): {
+        resolve(value?: Output): PromiseLike<void>;
+    };
+}

package/dist/execution/workflows/engine.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,12 @@
+import type { DurableExecution } from '../../application/workflow/index.js';
+import type { Value } from '../../platform/value/index.js';
+/** Engine input of one run, as the Kernel submits it. */
+export interface Envelope {
+    readonly execution: DurableExecution;
+    readonly input: Value;
+}
+/**
+ * Decode the run input the engine delivers. Fields a newer Kernel may add are ignored, so a Domain
+ * keeps running Executions submitted by it.
+ */
+export declare function decodeEnvelope(input: unknown): Envelope;

package/dist/execution/workflows/envelope.js

@@ -0,0 +1,46 @@
+import { issuer } from '../../platform/auth/index.js';
+import { NodeId } from '../../platform/graph/node/index.js';
+import * as portable from '../../platform/value/index.js';
+const VERSION = /^sha256:[0-9a-f]{64}$/u;
+/**
+ * Decode the run input the engine delivers. Fields a newer Kernel may add are ignored, so a Domain
+ * keeps running Executions submitted by it.
+ */
+export function decodeEnvelope(input) {
+    const envelope = record(input, 'envelope');
+    const fn = record(envelope.function, 'envelope.function');
+    const initiator = record(envelope.initiator, 'envelope.initiator');
+    if (typeof fn.version !== 'string' || !VERSION.test(fn.version)) {
+        throw new TypeError('Durable envelope.function.version is invalid.');
+    }
+    if (typeof envelope.kernel !== 'string')
+        throw new TypeError('Durable envelope.kernel is invalid.');
+    const receiver = envelope.receiver === undefined ? undefined : node(envelope.receiver, 'receiver');
+    const execution = Object.freeze({
+        id: node(envelope.execution, 'execution'),
+        function: Object.freeze({
+            id: node(fn.id, 'function.id'),
+            version: fn.version,
+        }),
+        kernel: issuer.accept(envelope.kernel),
+        initiator: Object.freeze({
+            principal: node(initiator.principal, 'initiator.principal'),
+            caller: node(initiator.caller, 'initiator.caller'),
+        }),
+        ...(receiver === undefined ? {} : { receiver }),
+    });
+    if (!Object.hasOwn(envelope, 'input'))
+        throw new TypeError('Durable envelope.input is missing.');
+    return Object.freeze({ execution, input: portable.accept(envelope.input) });
+}
+function record(input, label) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError(`Durable ${label} must be an object.`);
+    }
+    return input;
+}
+function node(input, label) {
+    if (typeof input !== 'string')
+        throw new TypeError(`Durable envelope.${label} is invalid.`);
+    return NodeId(input);
+}

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

@@ -0,0 +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;
+}
+/**
+ * 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;
+/**
+ * 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, step: string): Error | undefined;

package/dist/execution/workflows/failure.js

@@ -0,0 +1,160 @@
+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,
+    CONFLICT: 409,
+    UNSUPPORTED: 422,
+};
+/**
+ * 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;
+    return new engine.TerminalError(declared.message, {
+        errorCode: STATUS[declared.family],
+        metadata: {
+            [FAILURE]: JSON.stringify({
+                family: declared.family,
+                code: declared.code,
+                message: declared.message,
+                details: declared.details,
+            }),
+        },
+    });
+}
+/**
+ * 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, 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 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

@@ -0,0 +1,4 @@
+export type { DurableEngine, EnginePromise, EngineRetryPolicy, EngineCombinators, EngineRunOptions, 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/index.js

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

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

@@ -0,0 +1,13 @@
+import type { IntegrationAuthentication, IntegrationInvocationOwner } from '../../application/integration/index.js';
+import type { Lifetime } from '../invocation/lifecycle/index.js';
+/**
+ * The Integration calls of one Step attempt. Each call takes the Step's next derived key as its
+ * call id, so every attempt presents the same ids in the same order, and a keyed operation of
+ * source `execution` sends the same idempotency key. A retried Step may run an operation again,
+ * so an `unsafe` one is refused before its Provider runs. There is no caller to invoke for.
+ */
+export declare function stepCalls(input: {
+    readonly next: () => string;
+    readonly lifetime: Lifetime;
+    readonly auth: IntegrationAuthentication;
+}): IntegrationInvocationOwner;

package/dist/execution/workflows/integrations.js

@@ -0,0 +1,25 @@
+import { active } from '../invocation/lifecycle/index.js';
+/**
+ * The Integration calls of one Step attempt. Each call takes the Step's next derived key as its
+ * call id, so every attempt presents the same ids in the same order, and a keyed operation of
+ * source `execution` sends the same idempotency key. A retried Step may run an operation again,
+ * so an `unsafe` one is refused before its Provider runs. There is no caller to invoke for.
+ */
+export function stepCalls(input) {
+    const { next, lifetime, auth } = input;
+    return Object.freeze({
+        invoke(call) {
+            if (call.replay.kind === 'unsafe') {
+                throw new TypeError(`Integration operation ${call.integration}.${call.operation} is unsafe, and a retried ` +
+                    'durable Step would run it again.');
+            }
+            active(lifetime);
+            return call.attempt({
+                callId: next(),
+                signal: lifetime.signal,
+                deadline: lifetime.deadline,
+                auth,
+            });
+        },
+    });
+}

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

@@ -0,0 +1,66 @@
+import type { Fetch } from '@astrale-os/kernel-client';
+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. */
+    readonly engine: DurableEngine;
+    /** Fetch capability used for HTTPS discovery of a canonical request's Kernel engine. */
+    readonly fetch?: Fetch;
+    /**
+     * How long the engine retains a finished run. At least the Host minimum (one hour or more, one
+     * day by default); the Kernel resubmits an unstarted call only within half of it. Seven days by
+     * default.
+     */
+    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.
+     */
+    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. */
+export type DurableServingProvider = (request: Request) => DurableServing | undefined | Promise<DurableServing | undefined>;
+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;
+    /** 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", "RestatePromise"];
+/**
+ * Whether `module` exports the members of the Restate SDK Fetch entrypoint the durable receiver
+ * uses: each a function, but `RestatePromise`, the namespace of its combinators.
+ */
+export declare function isDurableEngine(module: unknown): boolean;
+/**
+ * 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;