@astrale-os/sdk 0.6.0-beta.2 → 0.6.0-beta.21

package/dist/execution/service/create.js

@@ -3,11 +3,12 @@ import { isRuntime } from '../../application/runtime/index.js';
 import { invocationPath } from '../../deployment/release/invocation.js';
 import { identity as captureIdentity } from '../identity/index.js';
 import { createHandler } from '../invocation/index.js';
-import { initialize, load } from '../runtime/index.js';
+import { initialize, load, serving as servedRelease } from '../runtime/index.js';
+import { createDurableReceiver, durableServing, isDurableRequest, } from '../workflows/index.js';
 import { initialization } from './initialization.js';
 import { lifecycle } from './lifecycle.js';
-import { delivery, installation, source } from './publication/index.js';
 import { loadRelease } from './release.js';
+import { delivery, installation, source } from './serving/index.js';
 /** Create one lazy running Service around the exact current Release. */
 export function createService(input) {
     if (input === null || typeof input !== 'object' || Array.isArray(input))
@@ -16,24 +17,28 @@ export function createService(input) {
         throw new TypeError('Service Runtime is not admitted.');
     const selectedIdentity = captureIdentity(input.identity);
     const providedDelivery = delivery(input.delivery);
+    const durable = input.durable;
+    // Preserve eager admission for an already loaded engine; providers stay outside ordinary startup.
+    const serving = durable === undefined || typeof durable === 'function' ? undefined : durableServing(durable);
     let running;
     const state = lifecycle(() => running?.server.drain());
     const realized = initialization(async () => {
         const release = await loadRelease(input.load, input.environment, input.runtime);
-        if (release.addressing.issuer !== selectedIdentity.issuer) {
+        const served = servedRelease(release);
+        if (served.issuer !== selectedIdentity.issuer) {
             throw new TypeError('Service Identity differs from Release Addressing.');
         }
         if (selectedIdentity.subject !== release.build.schema.compiled.root.origin) {
             throw new TypeError('Service Identity subject differs from the Release Domain origin.');
         }
-        const selectedDelivery = providedDelivery ?? selectedIdentity.delivery(release.publication);
-        installation(release, selectedDelivery);
+        const selectedDelivery = providedDelivery ?? selectedIdentity.delivery(served.document);
+        installation(served.document, selectedDelivery);
         const loaded = load(release);
         const runtime = await initialize(loaded, input.environment);
         const prepared = prepareServer({
             ...serverOptions(input.server),
             path: invocationPath(),
-            publicOrigin: release.addressing.publicUrl,
+            publicOrigin: served.publicUrl,
             invocation: {
                 source: selectedIdentity.issuer,
                 next: () => crypto.randomUUID(),
@@ -42,7 +47,7 @@ export function createService(input) {
             ...(selectedIdentity.tokenExchange === undefined
                 ? {}
                 : { tokenExchange: selectedIdentity.tokenExchange }),
-            publication: source(loaded),
+            ...source(loaded),
             ...(selectedDelivery === undefined ? {} : { delivery: selectedDelivery }),
         });
         const server = prepared.create(createHandler({
@@ -55,6 +60,19 @@ export function createService(input) {
             server.drain();
         return running;
     });
+    const receiver = initialization(async (request) => {
+        const selected = typeof durable === 'function' ? await durable(request) : undefined;
+        const configuration = serving ?? (selected === undefined ? undefined : durableServing(selected));
+        if (configuration === undefined)
+            return undefined;
+        const { runtime } = await realized.get();
+        return createDurableReceiver({
+            workflows: runtime.loaded.registry.workflows,
+            domain: runtime.loaded.domain,
+            identity: selectedIdentity,
+            serving: configuration,
+        });
+    });
     let closing;
     const service = Object.freeze({
         async fetch(request, host) {
@@ -63,6 +81,13 @@ export function createService(input) {
             const ready = await realized.get();
             if (!state.accepting)
                 return unavailable();
+            // Without engine configuration only durable calls fail: the engine's discovery is refused.
+            if (isDurableRequest(request)) {
+                const selected = await receiver.get(request);
+                if (!state.accepting)
+                    return unavailable();
+                return selected?.fetch(request) ?? notServed();
+            }
             return ready.server.app.fetch(request, host);
         },
         async release() {
@@ -95,6 +120,7 @@ function serverOptions(input) {
         'issuer',
         'publicOrigin',
         'tokenExchange',
+        'release',
         'publication',
         'delivery',
         'handler',
@@ -104,6 +130,12 @@ function serverOptions(input) {
     }
     return input;
 }
+function notServed() {
+    return new Response('{"error":"This deployment serves no durable Workflows."}', {
+        status: 404,
+        headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+    });
+}
 function unavailable() {
     return new Response('{"error":"Service is draining."}', {
         status: 503,

package/dist/execution/service/initialization.d.ts

@@ -1,6 +1,6 @@
-export interface Initialization<Value> {
-    get(): Promise<Value>;
+export interface Initialization<Value, Arguments extends readonly unknown[] = []> {
+    get(...args: Arguments): Promise<Value>;
     current(): Promise<Value> | undefined;
 }
-/** Share one successful initialization and allow a later retry after failure. */
-export declare function initialization<Value>(create: () => Promise<Value>): Initialization<Value>;
+/** Share an initialized value; absence and failure leave initialization retryable. */
+export declare function initialization<Value, Arguments extends readonly unknown[] = []>(create: (...args: Arguments) => Promise<Value>): Initialization<Value, Arguments>;

package/dist/execution/service/initialization.js

@@ -1,18 +1,27 @@
-/** Share one successful initialization and allow a later retry after failure. */
+/** Share an initialized value; absence and failure leave initialization retryable. */
 export function initialization(create) {
-    let current;
+    let state;
+    const get = (...args) => {
+        if (state?.phase === 'ready')
+            return state.promise;
+        if (state !== undefined) {
+            // Absence can depend on the initializing request. A waiter gets its own eligibility check.
+            return state.promise.then((value) => (value === undefined ? get(...args) : value));
+        }
+        const pending = create(...args).then((value) => {
+            if (state?.promise === pending)
+                state = value === undefined ? undefined : { phase: 'ready', promise: pending };
+            return value;
+        }, (cause) => {
+            if (state?.promise === pending)
+                state = undefined;
+            throw cause;
+        });
+        state = { phase: 'pending', promise: pending };
+        return pending;
+    };
     return Object.freeze({
-        get() {
-            if (current !== undefined)
-                return current;
-            const pending = create().catch((cause) => {
-                if (current === pending)
-                    current = undefined;
-                throw cause;
-            });
-            current = pending;
-            return pending;
-        },
-        current: () => current,
+        get,
+        current: () => state?.promise,
     });
 }

package/dist/execution/service/release.d.ts

@@ -1,7 +1,7 @@
 import type { Runtime } from '../../application/runtime/index.js';
 import type { Build } from '../../deployment/build/build.js';
-import type { Release } from '../../deployment/release/release.js';
 import type { schema } from '../../platform/schema/index.js';
-export type ReleaseForRuntime<RuntimeValue extends Runtime> = Release<Build<schema.DomainSchema, RuntimeValue>>;
+import type { ServedRelease } from '../runtime/index.js';
+export type ReleaseForRuntime<RuntimeValue extends Runtime> = ServedRelease<Build<schema.DomainSchema, RuntimeValue>>;
 export type ReleaseLoader<Environment, RuntimeValue extends Runtime = Runtime> = (environment: Environment) => ReleaseForRuntime<RuntimeValue> | Promise<ReleaseForRuntime<RuntimeValue>>;
 export declare function loadRelease<Environment, RuntimeValue extends Runtime>(load: ReleaseLoader<Environment, RuntimeValue>, environment: Environment, runtime: RuntimeValue): Promise<ReleaseForRuntime<RuntimeValue>>;

package/dist/execution/service/release.js

@@ -1,10 +1,11 @@
-import { isRelease } from '../../deployment/release/admission.js';
+import { isServedRelease } from '../runtime/index.js';
 export async function loadRelease(load, environment, runtime) {
     if (typeof load !== 'function')
         throw new TypeError('Service Release loader is invalid.');
     const release = await load(environment);
-    if (!isRelease(release))
+    if (!isServedRelease(release)) {
         throw new TypeError('Service loader returned an unadmitted Release.');
+    }
     if (release.build.runtime !== runtime) {
         throw new TypeError('Service Release Runtime differs from the generated entrypoint Runtime.');
     }

package/dist/execution/service/service.d.ts

@@ -1,23 +1,33 @@
 import type { ApplicationHost, ServerCloseOptions, ServerOptions } from '@astrale-os/kernel-server';
-import type { publication } from '@astrale-os/kernel-server';
+import type { release } from '@astrale-os/kernel-server';
 import type { Runtime } from '../../application/runtime/index.js';
 import type { WorkflowRunner } from '../../application/workflow/runner/index.js';
-import type { Release } from '../../deployment/release/index.js';
 import type { Identity } from '../identity/index.js';
+import type { ServedRelease } from '../runtime/index.js';
+import type { DurableServing, DurableServingProvider } from '../workflows/index.js';
 import type { ReleaseLoader } from './release.js';
-export type ServiceServerOptions = Omit<ServerOptions, 'path' | 'invocation' | 'issuer' | 'publicOrigin' | 'tokenExchange' | 'publication' | 'delivery'>;
+export type ServiceServerOptions = Omit<ServerOptions, 'path' | 'invocation' | 'issuer' | 'publicOrigin' | 'tokenExchange' | 'release' | 'publication' | 'delivery'>;
 export interface ServiceInput<Environment, RuntimeValue extends Runtime = Runtime> {
     readonly runtime: RuntimeValue;
     readonly environment: Environment;
     readonly load: ReleaseLoader<Environment, RuntimeValue>;
     readonly identity: Identity;
     readonly server: ServiceServerOptions;
-    readonly delivery?: publication.delivery.Provider;
+    /**
+     * Answers Delivery in the request's version: v2 over an immutable deployment's release, v1 over
+     * the Publication (a release's frozen v3 projection). Defaults to the Identity's own.
+     */
+    readonly delivery?: release.delivery.Provider;
     readonly workflows?: WorkflowRunner;
+    /**
+     * Serve the Release's durable Workflows. A provider is resolved on the first engine request,
+     * shared by concurrent requests, and retried after initialization fails.
+     */
+    readonly durable?: DurableServing | DurableServingProvider;
 }
 export interface Service {
     fetch(request: Request, host?: ApplicationHost): Promise<Response>;
-    release(): Promise<Release>;
+    release(): Promise<ServedRelease>;
     drain(): void;
     close(options: ServerCloseOptions): Promise<void>;
 }

package/dist/execution/service/serving/delivery.d.ts

@@ -0,0 +1,6 @@
+import type { release } from '@astrale-os/kernel-server';
+/**
+ * Capture an explicit Delivery Provider. It answers in the request's version: v2 over an immutable
+ * deployment's release, v1 over the Publication (a release's frozen v3 projection).
+ */
+export declare function delivery(input: release.delivery.Provider | undefined): release.delivery.Provider | undefined;

package/dist/execution/service/{publication → serving}/delivery.js

@@ -1,8 +1,12 @@
+/**
+ * Capture an explicit Delivery Provider. It answers in the request's version: v2 over an immutable
+ * deployment's release, v1 over the Publication (a release's frozen v3 projection).
+ */
 export function delivery(input) {
     if (input === undefined)
         return undefined;
     if (input === null || typeof input !== 'object' || typeof input.create !== 'function') {
-        throw new TypeError('Publication delivery Provider is invalid.');
+        throw new TypeError('Delivery Provider is invalid.');
     }
     const create = input.create.bind(input);
     return Object.freeze({ create });

package/dist/execution/service/{publication → serving}/index.d.ts

@@ -1,3 +1,3 @@
 export { delivery } from './delivery.js';
 export { installation } from './installation.js';
-export { source } from './source.js';
+export { source, type ServingSource } from './source.js';

package/dist/execution/service/serving/installation.d.ts

@@ -0,0 +1,4 @@
+import type { release } from '@astrale-os/kernel-server';
+import type { Serving } from '../../runtime/index.js';
+/** A served document advertises Delivery exactly when the Service has a Provider for it. */
+export declare function installation(served: Serving['document'], provider: release.delivery.Provider | undefined): void;

package/dist/execution/service/serving/installation.js

@@ -0,0 +1,9 @@
+/** A served document advertises Delivery exactly when the Service has a Provider for it. */
+export function installation(served, provider) {
+    const advertised = served.delivery !== undefined;
+    if (advertised !== (provider !== undefined)) {
+        throw new TypeError(advertised
+            ? 'Release advertises delivery without a Provider.'
+            : 'Delivery Provider has no Release endpoint.');
+    }
+}

package/dist/execution/service/serving/legacy/index.d.ts

@@ -0,0 +1,15 @@
+import type { PublicationSource } from '@astrale-os/kernel-server';
+import type * as legacy from '../../../../deployment/release/legacy/index.js';
+import type { LoadedRuntime } from '../../../runtime/index.js';
+/**
+ * Serve a stable target's v3 Publication through the Kernel Server's v3-input source: `domain.json`
+ * only (404 at `release.json`), with the same-schema continuity of a stable Worker.
+ *
+ * @deprecated Replacement: the release source of `../source.ts`, which serves an immutable
+ * deployment's `DomainRelease` v4. Consumer: the stable Worker of the direct-mode path (the
+ * consumers of `deployment/release/legacy/index.ts`), whose host binds no build digest. Removal:
+ * D10, with `deployment/release/legacy/` and Kernel Server's `publication` source.
+ */
+export declare function publicationSource(runtime: LoadedRuntime, served: legacy.Release): {
+    readonly publication: PublicationSource;
+};

package/dist/execution/service/serving/legacy/index.js

@@ -0,0 +1,19 @@
+import { preparePublicationSnapshot } from '@astrale-os/kernel-server';
+/**
+ * Serve a stable target's v3 Publication through the Kernel Server's v3-input source: `domain.json`
+ * only (404 at `release.json`), with the same-schema continuity of a stable Worker.
+ *
+ * @deprecated Replacement: the release source of `../source.ts`, which serves an immutable
+ * deployment's `DomainRelease` v4. Consumer: the stable Worker of the direct-mode path (the
+ * consumers of `deployment/release/legacy/index.ts`), whose host binds no build digest. Removal:
+ * D10, with `deployment/release/legacy/` and Kernel Server's `publication` source.
+ */
+export function publicationSource(runtime, served) {
+    const snapshot = preparePublicationSnapshot({
+        publication: served.publication,
+        bundle: served.build.schema.bundle.bytes(),
+        table: served.routes,
+        domain: runtime.domain,
+    });
+    return Object.freeze({ publication: Object.freeze({ current: () => snapshot }) });
+}

package/dist/execution/service/serving/source.d.ts

@@ -0,0 +1,18 @@
+import type { PublicationSource, ReleaseSource } from '@astrale-os/kernel-server';
+import type { LoadedRuntime } from '../../runtime/index.js';
+/** The one source a Kernel Server serves, as `ServerOptions` takes it. */
+export type ServingSource = 
+/** The release of an immutable deployment: `release.json` and its v3 projection. */
+{
+    readonly release: ReleaseSource;
+}
+/** @deprecated A stable target's v3 Publication; see `legacy/index.ts`. */
+ | {
+    readonly publication: PublicationSource;
+};
+/**
+ * Prepare, once, the exact snapshot the loaded Release serves: an immutable deployment serves its
+ * `DomainRelease` through `prepareReleaseSnapshot`, which admits only routing naming that exact
+ * release or its exact v3 projection; a stable target keeps serving its v3 Publication.
+ */
+export declare function source(runtime: LoadedRuntime): ServingSource;

package/dist/execution/service/serving/source.js

@@ -0,0 +1,19 @@
+import { prepareReleaseSnapshot } from '@astrale-os/kernel-server';
+import { publicationSource } from './legacy/index.js';
+/**
+ * Prepare, once, the exact snapshot the loaded Release serves: an immutable deployment serves its
+ * `DomainRelease` through `prepareReleaseSnapshot`, which admits only routing naming that exact
+ * release or its exact v3 projection; a stable target keeps serving its v3 Publication.
+ */
+export function source(runtime) {
+    const served = runtime.release;
+    if (served.kind !== 'release')
+        return publicationSource(runtime, served);
+    const snapshot = prepareReleaseSnapshot({
+        release: served.document,
+        bundle: served.build.schema.bundle.bytes(),
+        table: served.routes,
+        domain: runtime.domain,
+    });
+    return Object.freeze({ release: Object.freeze({ current: () => snapshot }) });
+}

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,52 @@
+/**
+ * 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;
+}
+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;
+    };
+}
+export interface EngineRetryPolicy {
+    readonly maxAttempts: number;
+    readonly onMaxAttempts: 'pause' | 'kill';
+    readonly initialInterval: number;
+    readonly maxInterval: number;
+    readonly exponentiationFactor: number;
+}
+/** Journaled operations of one workflow run. */
+export interface EngineWorkflowContext {
+    run<Output>(name: string, action: () => Promise<Output>): PromiseLike<Output>;
+    sleep(durationMs: number, name?: string): PromiseLike<void>;
+    promise<Output>(name: string): {
+        get(): PromiseLike<Output>;
+    };
+    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,11 @@
+import type { DurableEngine } from './engine.js';
+/**
+ * Encode a declared business error of `definition` 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.
+ */
+export declare function replayedFailure(engine: DurableEngine, cause: unknown, definition: object): Error | undefined;