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

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/discovery.d.ts

@@ -0,0 +1,14 @@
+import type { Fetch } from '@astrale-os/kernel-client';
+import type { WorkflowEngine } from '@astrale-os/kernel-protocol/issuer/workflow-engine';
+/** Discovery failure never admits static keys for an issuer-prefixed request. */
+export declare class WorkflowEngineUnavailable extends Error {
+    readonly name = "WorkflowEngineUnavailable";
+}
+/** One receiver retains bounded, recently admitted engine authority and deduplicates refreshes. */
+export declare function workflowEngineDiscovery(fetch: Fetch, now?: () => number): Readonly<{
+    resolve(issuer: string): Promise<WorkflowEngine>;
+    /** A crypto provider rejected this authority; the next request must discover it again. */
+    forget(issuer: string, observedKeys: readonly string[]): void;
+    /** Authentication refusal expires the basis for the next request, without replaying its body. */
+    invalidate(issuer: string, observedKeys: readonly string[]): void;
+}>;

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,83 @@
+/**
+ * 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;
+}
+/**
+ * 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 `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>;
+    };
+    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,39 @@
+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, 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;
+    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 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);
+}
+/**
+ * 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;