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

package/dist/execution/workflows/failure.js

@@ -0,0 +1,143 @@
+import { declaredErrorFactory, declaredErrorOf } from '../../application/error/index.js';
+import { ResponseError } from '../../platform/client/index.js';
+/** Metadata key the Kernel reads a declared failure from (`backend/restate` outcome decoding). */
+const FAILURE = 'astrale.failure';
+/** Failure code of an Execution whose Workflow did not catch a Step that spent its retry budget. */
+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, or whose attempt the Kernel refused for good. Its message
+ * never carries what the last attempt threw; when the Kernel refused that attempt, `refusal` names
+ * the refusal by its codes alone.
+ */
+export class StepExhausted extends Error {
+    step;
+    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 message of a failed attempt: what it threw, after the Kernel refusal's codes, if any. */
+export function attemptMessage(cause, refusal = kernelRefusalOf(cause)) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    if (refusal === undefined)
+        return message;
+    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 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;
+    }
+}
+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 or a failed attempt; a
+    // bare one is an engine's budget.
+    if (encoded === undefined)
+        return new StepExhausted(step, refusalIn(cause.message));
+    const failure = JSON.parse(encoded);
+    // 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, 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,81 @@
+import type { Fetch } from '@astrale-os/kernel-client';
+import type { DurableStepRetry } from '../../application/workflow/index.js';
+import type { DurableEngine, EngineRetryPolicy } from './engine.js';
+/** Serving configuration of the durable Workflows of one deployment. */
+export interface DurableServing {
+    /** The Restate SDK Fetch build of this platform. */
+    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: 10 attempts from 1 s to 60 s by default, and no
+     * duration limit. Only a Step's own failures spend its attempts; it waits out an unavailable Kernel
+     * within its `maxDurationMs`. A Step that spends it fails into its Workflow. `maxAttempts` also
+     * bounds the attempts of a run that fails outside any Step, an unreachable deployment included,
+     * which then pauses for `resume` or `cancel`; 20 when it declares none. The Host caps them.
+     */
+    readonly retry?: DurableStepRetry;
+    /** Deadline of one Step attempt that declares none, including its Kernel calls. One minute by default. */
+    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 and its attempt deadline. */
+export interface StepServing {
+    readonly retry: StepRetryBudget;
+    readonly timeoutMs: number;
+}
+/**
+ * The retry budget of one Step, which the Step spends attempt by attempt (see `attempts.ts`). An
+ * absent limit does not bound it.
+ */
+export interface StepRetryBudget {
+    /** Attempts whose failure is the Step's own, the first one included. */
+    readonly maxAttempts?: number;
+    /** Time from the start of the Step's first attempt after which a failed attempt is not retried. */
+    readonly maxDurationMs?: number;
+    readonly initialIntervalMs: number;
+    readonly maxIntervalMs: number;
+    readonly intervalFactor: number;
+}
+/**
+ * The members of the Restate SDK Fetch entrypoint the durable receiver uses, which a platform's
+ * engine module must export.
+ */
+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;

package/dist/execution/workflows/options.js

@@ -0,0 +1,158 @@
+/**
+ * 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',
+    '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 function isDurableEngine(module) {
+    if (module === null || typeof module !== 'object')
+        return false;
+    return DURABLE_ENGINE_EXPORTS.every((member) => {
+        const value = Reflect.get(module, member);
+        if (member !== 'RestatePromise')
+            return typeof value === 'function';
+        return (typeof value === 'object' &&
+            value !== null &&
+            typeof Reflect.get(value, 'allSettled') === 'function');
+    });
+}
+const HOUR_MS = 60 * 60_000;
+const DAY_MS = 24 * HOUR_MS;
+/**
+ * Attempts a Step's own failures may spend when the deployment declares none. An unavailable Kernel
+ * spends none of them, so they bound only failures that sending again may not cure.
+ */
+const DEFAULT_STEP_ATTEMPTS = 10;
+/**
+ * Attempts of a run failing outside any Step when the deployment declares none. The engine counts an
+ * unreachable deployment as such a failure, which it cannot tell apart from the code's own, so these
+ * also span an unavailability of the deployment, about fourteen minutes at the default intervals.
+ */
+const DEFAULT_RUN_ATTEMPTS = 20;
+/** The longest attempt a Step may declare, which the engine's abort timeout leaves to end first. */
+const MAXIMUM_STEP_TIMEOUT_MS = 10 * 60_000;
+/**
+ * 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({
+    maxAttempts: DEFAULT_STEP_ATTEMPTS,
+    initialIntervalMs: 1_000,
+    maxIntervalMs: 60_000,
+    intervalFactor: 2,
+});
+/** Capture one durable serving configuration, failing closed on any gap. */
+export function durableServing(input) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        Reflect.ownKeys(input).some((key) => key !== 'engine' &&
+            key !== 'fetch' &&
+            key !== 'retentionMs' &&
+            key !== 'retry' &&
+            key !== 'stepTimeoutMs')) {
+        invalid('Durable serving options are invalid.');
+    }
+    const engine = input.engine;
+    if (!isDurableEngine(engine)) {
+        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 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,
+            RestatePromise: Object.freeze({
+                allSettled: engine.RestatePromise.allSettled.bind(engine.RestatePromise),
+            }),
+        }),
+        fetch,
+        retentionMs: bounded(input.retentionMs, 7 * DAY_MS, HOUR_MS, 365 * DAY_MS, 'retentionMs'),
+        retryPolicy: Object.freeze({
+            maxAttempts: input.retry?.maxAttempts ?? DEFAULT_RUN_ATTEMPTS,
+            onMaxAttempts: 'pause',
+            initialInterval: step.retry.initialIntervalMs,
+            maxInterval: step.retry.maxIntervalMs,
+            exponentiationFactor: step.retry.intervalFactor,
+        }),
+        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.maxAttempts;
+    const maxDuration = limited
+        ? optionalBounded(retry.maxDurationMs, 1, 365 * DAY_MS, 'maxDurationMs')
+        : fallback.retry.maxDurationMs;
+    const initialInterval = bounded(retry.initialIntervalMs, fallback.retry.initialIntervalMs, 1, HOUR_MS, 'initialIntervalMs');
+    const maxInterval = bounded(retry.maxIntervalMs, Math.max(fallback.retry.maxIntervalMs, initialInterval), initialInterval, DAY_MS, 'maxIntervalMs');
+    return Object.freeze({
+        retry: Object.freeze({
+            ...(maxAttempts === undefined ? {} : { maxAttempts }),
+            ...(maxDuration === undefined ? {} : { maxDurationMs: maxDuration }),
+            initialIntervalMs: initialInterval,
+            maxIntervalMs: maxInterval,
+            intervalFactor: fallback.retry.intervalFactor,
+        }),
+        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;
+    if (!Number.isSafeInteger(input) || input < minimum || input > maximum) {
+        invalid(`Durable ${label} must be an integer between ${minimum} and ${maximum}.`);
+    }
+    return input;
+}
+function invalid(message) {
+    throw new TypeError(message);
+}

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

@@ -0,0 +1,24 @@
+import type { IntegrationClientFactory, Integrations } from '../../application/integration/index.js';
+import type { RuntimeWorkflow } from '../../application/runtime/workflows.js';
+import type { Domain } from '../../platform/schema/index.js';
+import type { Identity } from '../identity/index.js';
+import type { AdmittedDurableServing } from './options.js';
+/** Serves the engine's discovery and invocations of this deployment's durable Workflows. */
+export interface DurableReceiver {
+    fetch(request: Request): Promise<Response>;
+}
+/**
+ * Route `…/invoke/restate/<Kernel issuer>/<declaration key>/<service>/{discover,invoke/…}` to one
+ * engine endpoint. Routes discover
+ * their signing authority at the named Kernel; that issuer also binds the run envelope. Each
+ * endpoint serves exactly that service with the declared Workflow. A declaration this Release does not
+ * serve durably is refused, so an endpoint never runs code it does not declare.
+ */
+export declare function createDurableReceiver(input: {
+    readonly workflows: readonly RuntimeWorkflow[];
+    readonly domain: Domain;
+    readonly identity: Identity;
+    readonly serving: AdmittedDurableServing;
+    /** Integration clients of the initialized Runtime, which every Step holds. */
+    readonly integrations: IntegrationClientFactory<Integrations>;
+}): DurableReceiver;

package/dist/execution/workflows/receiver.js

@@ -0,0 +1,99 @@
+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';
+const MAXIMUM_ENDPOINTS = 256;
+/**
+ * Route `…/invoke/restate/<Kernel issuer>/<declaration key>/<service>/{discover,invoke/…}` to one
+ * engine endpoint. Routes discover
+ * their signing authority at the named Kernel; that issuer also binds the run envelope. Each
+ * endpoint serves exactly that service with the declared Workflow. A declaration this Release does not
+ * serve durably is refused, so an endpoint never runs code it does not declare.
+ */
+export function createDurableReceiver(input) {
+    const executor = input.identity.executor;
+    if (executor === undefined) {
+        throw new TypeError('Durable Workflows require an execution Identity that can act as the Domain.');
+    }
+    const steps = sessionSteps({
+        executor: executor.bind(input.identity),
+        domain: input.domain,
+        integrations: input.integrations,
+    });
+    const declared = new Map(input.workflows
+        .filter((workflow) => workflow.durable)
+        .map((workflow) => [workflow.callable.key, workflow]));
+    const endpoints = new Map();
+    const { engine } = input.serving;
+    const discovery = workflowEngineDiscovery(input.serving.fetch);
+    return Object.freeze({
+        async fetch(request) {
+            const route = durableRoute(request);
+            if (route === undefined)
+                return refused();
+            const { kernel, declaration, service } = route;
+            const workflow = declared.get(declaration);
+            if (workflow === undefined)
+                return refused();
+            let identityKeys;
+            try {
+                identityKeys = (await discovery.resolve(kernel)).identity_keys;
+            }
+            catch (cause) {
+                if (!(cause instanceof WorkflowEngineUnavailable))
+                    throw cause;
+                return unavailable();
+            }
+            request.signal.throwIfAborted();
+            const cacheKey = JSON.stringify([kernel, declaration, service, identityKeys]);
+            let endpoint = endpoints.get(cacheKey);
+            if (endpoint === undefined) {
+                const definition = engine.workflow({
+                    name: service,
+                    handlers: durableHandlers({
+                        workflow,
+                        domain: input.domain,
+                        serving: input.serving,
+                        steps,
+                        kernel,
+                    }),
+                    options: {
+                        workflowRetention: input.serving.retentionMs,
+                        retryPolicy: input.serving.retryPolicy,
+                        abortTimeout: ENGINE_ABORT_TIMEOUT_MS,
+                    },
+                });
+                try {
+                    endpoint = engine.createEndpointHandler({
+                        identityKeys: [...identityKeys],
+                        services: [definition],
+                    });
+                }
+                catch {
+                    discovery.forget(kernel, identityKeys);
+                    return unavailable();
+                }
+                if (endpoints.size >= MAXIMUM_ENDPOINTS)
+                    endpoints.delete(endpoints.keys().next().value);
+                endpoints.set(cacheKey, endpoint);
+            }
+            const response = await endpoint(request);
+            if (response.status === 401)
+                discovery.invalidate(kernel, identityKeys);
+            return response;
+        },
+    });
+}
+function refused() {
+    return new Response('{"error":"Unknown durable declaration."}', {
+        status: 404,
+        headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+    });
+}
+function unavailable() {
+    return new Response('{"error":"Workflow engine authority is unavailable."}', {
+        status: 503,
+        headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+    });
+}

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

@@ -0,0 +1,12 @@
+import type { IssuerId } from '../../platform/auth/index.js';
+export interface DurableRoute {
+    readonly kernel: IssuerId;
+    readonly declaration: string;
+    readonly service: string;
+}
+/** Whether the request is owned by the durable receiver, including malformed paths. */
+export declare function isDurableRequest(request: Request): boolean;
+/** Canonical requests discover authority at the HTTPS Kernel named by this admitted route. */
+export declare function isCanonicalDurableRequest(request: Request): boolean;
+/** One wire decoder shared by the receiver and platform lazy-load eligibility. */
+export declare function durableRoute(request: Request): DurableRoute | undefined;

package/dist/execution/workflows/route.js

@@ -0,0 +1,35 @@
+import { Key } from '@astrale-os/kernel-dsl/v1/addressing';
+import { invocationPath } from '../../deployment/release/invocation.js';
+import { AuthValueError } from '../../platform/auth/index.js';
+import { httpIssuer } from '../identity/errors.js';
+const PREFIX = `${invocationPath()}/restate/`;
+const SERVICE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/u;
+/** Whether the request is owned by the durable receiver, including malformed paths. */
+export function isDurableRequest(request) {
+    return new URL(request.url).pathname.startsWith(PREFIX);
+}
+/** Canonical requests discover authority at the HTTPS Kernel named by this admitted route. */
+export function isCanonicalDurableRequest(request) {
+    return durableRoute(request)?.kernel !== undefined;
+}
+/** One wire decoder shared by the receiver and platform lazy-load eligibility. */
+export function durableRoute(request) {
+    const pathname = new URL(request.url).pathname;
+    if (!pathname.startsWith(PREFIX))
+        return undefined;
+    const parts = pathname.slice(PREFIX.length).split('/');
+    try {
+        const first = decodeURIComponent(parts[0] ?? '');
+        const kernel = httpIssuer(first, false);
+        const declaration = decodeURIComponent(parts[1] ?? '');
+        const service = parts[2] ?? '';
+        if (!Key.is(declaration) || !SERVICE.test(service))
+            return undefined;
+        return Object.freeze({ kernel, declaration, service });
+    }
+    catch (cause) {
+        if (cause instanceof URIError || cause instanceof AuthValueError || cause instanceof TypeError)
+            return undefined;
+        throw cause;
+    }
+}

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

@@ -0,0 +1,23 @@
+import type { RuntimeWorkflow } from '../../application/runtime/workflows.js';
+import type { IssuerId } from '../../platform/auth/index.js';
+import type { Domain } from '../../platform/schema/index.js';
+import type { EngineSharedContext, EngineWorkflowContext } from './engine.js';
+import type { AdmittedDurableServing } from './options.js';
+import type { StepAuthorities } from './steps.js';
+export interface DurableRun {
+    readonly kernel: IssuerId;
+    readonly workflow: RuntimeWorkflow;
+    readonly domain: Domain;
+    readonly serving: AdmittedDurableServing;
+    /** What each Step attempt holds. */
+    readonly steps: StepAuthorities;
+    /** The clock that times each Step attempt against its Step's `maxDurationMs`; `Date.now` by default. */
+    readonly now?: () => number;
+}
+/** Engine handlers of one durable Workflow: the `run` and the shared `signal`. */
+export declare function durableHandlers(input: DurableRun): Readonly<{
+    run: (context: EngineWorkflowContext, raw: unknown) => Promise<import("../../platform/schema/index.js").Value>;
+    signal(context: EngineSharedContext, raw: unknown): Promise<{
+        accepted: boolean;
+    }>;
+}>;