@nylorun/runtime 0.10.0-beta → 0.11.0-beta

package/dist/host/stack-config.js

@@ -0,0 +1,193 @@
+/**
+ * Stack configuration for the Runtime process, parsed from an environment
+ * snapshot and argv. Pure: `host/main.ts` passes the process environment and
+ * arguments; nothing here reads ambient state.
+ *
+ * Two listen modes:
+ * - **local** (no `NYLORUN_LISTEN_*` / `NYLORUN_ALLOWED_HOSTS`): the Host binds
+ *   what `host.json` names, loopback only unless `allowNonLoopback`.
+ * - **container**: the Host binds `NYLORUN_LISTEN_HOST:NYLORUN_LISTEN_PORT`
+ *   (default `0.0.0.0:4000`) and accepts only the `Host` headers in
+ *   `NYLORUN_ALLOWED_HOSTS`, plus the loopback forms of the listen port for
+ *   probes from inside the container.
+ *
+ * The Postgres, Restate and S2 endpoints are parsed and validated here;
+ * `infra/*` builds the clients from them.
+ */
+export const RUNTIME_ROLES = ["api", "worker", "all"];
+export const DEFAULT_CONTAINER_LISTEN_HOST = "0.0.0.0";
+export const DEFAULT_CONTAINER_LISTEN_PORT = 4000;
+export class StackConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StackConfigError";
+    }
+}
+function read(env, name) {
+    const value = env[name];
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+export function parseRole(argv) {
+    let role;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        let value;
+        if (arg === "--role") {
+            value = argv[index + 1];
+            index += 1;
+            if (value === undefined || value.startsWith("-"))
+                throw new StackConfigError("--role requires a value: api, worker or all");
+        }
+        else if (arg.startsWith("--role=")) {
+            value = arg.slice("--role=".length);
+        }
+        else {
+            throw new StackConfigError(`Unknown argument ${arg}. Usage: main.js [--role api|worker|all]`);
+        }
+        if (role !== undefined)
+            throw new StackConfigError("--role may only be supplied once");
+        if (!RUNTIME_ROLES.includes(value))
+            throw new StackConfigError(`Invalid --role ${value}; expected api, worker or all`);
+        role = value;
+    }
+    return role ?? "all";
+}
+function parsePort(name, raw) {
+    if (!/^\d+$/.test(raw))
+        throw new StackConfigError(`${name} must be a port number; got ${raw}`);
+    const port = Number(raw);
+    if (port < 1 || port > 65535)
+        throw new StackConfigError(`${name} must be between 1 and 65535; got ${raw}`);
+    return port;
+}
+/**
+ * Normalize one `Host` header allowlist entry to lowercase `name:port`.
+ * IPv6 literals must be bracketed (`[::1]:4000`).
+ */
+export function normalizeAllowedHost(name, entry) {
+    const value = entry.trim().toLowerCase();
+    const match = /^(\[[0-9a-f:.]+\]|[a-z0-9]([a-z0-9.-]*[a-z0-9])?):(\d+)$/.exec(value);
+    if (!match)
+        throw new StackConfigError(`${name} entry "${entry}" must be host:port (IPv6 in brackets)`);
+    parsePort(name, match[3]);
+    return value;
+}
+function loopbackForms(port) {
+    return [`localhost:${port}`, `127.0.0.1:${port}`, `[::1]:${port}`];
+}
+function isLoopbackAddress(host) {
+    const value = host.toLowerCase();
+    return value === "127.0.0.1" || value === "::1" || value === "localhost";
+}
+function parseUrl(env, name, protocols) {
+    const raw = read(env, name);
+    if (raw === undefined)
+        return undefined;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new StackConfigError(`${name} is not a valid URL`);
+    }
+    if (!protocols.includes(url.protocol))
+        throw new StackConfigError(`${name} must use ${protocols.map((p) => p.replace(/:$/, "")).join(" or ")}; got ${url.protocol.replace(/:$/, "")}`);
+    return raw;
+}
+function parseListen(env) {
+    const rawHost = read(env, "NYLORUN_LISTEN_HOST");
+    const rawPort = read(env, "NYLORUN_LISTEN_PORT");
+    const rawAllowed = read(env, "NYLORUN_ALLOWED_HOSTS");
+    if (rawHost === undefined && rawPort === undefined && rawAllowed === undefined)
+        return undefined;
+    const host = rawHost ?? DEFAULT_CONTAINER_LISTEN_HOST;
+    if (/\s|\//.test(host))
+        throw new StackConfigError(`NYLORUN_LISTEN_HOST is not an address: ${host}`);
+    const port = rawPort === undefined
+        ? DEFAULT_CONTAINER_LISTEN_PORT
+        : parsePort("NYLORUN_LISTEN_PORT", rawPort);
+    const explicit = rawAllowed === undefined
+        ? []
+        : rawAllowed
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry !== "")
+            .map((entry) => normalizeAllowedHost("NYLORUN_ALLOWED_HOSTS", entry));
+    if (explicit.length === 0 && !isLoopbackAddress(host))
+        throw new StackConfigError(`NYLORUN_ALLOWED_HOSTS is required when NYLORUN_LISTEN_HOST is ${host}: list the Host headers clients send, e.g. runtime:${port},localhost:<published port>`);
+    // Loopback forms of the listen port serve probes from inside the container
+    // (health checks). A browser on the Docker host never sends them: it sends
+    // the published port.
+    const allowedHosts = [...new Set([...explicit, ...loopbackForms(port)])];
+    return { host, port, allowedHosts };
+}
+const IDENTITY_KEY = /^publickeyv1_[1-9A-HJ-NP-Za-km-z]{32,64}$/;
+function parseIdentityKeys(env) {
+    const raw = read(env, "NYLORUN_RESTATE_IDENTITY_KEY");
+    if (raw === undefined)
+        return undefined;
+    const keys = raw
+        .split(",")
+        .map((key) => key.trim())
+        .filter((key) => key !== "");
+    for (const key of keys)
+        if (!IDENTITY_KEY.test(key))
+            throw new StackConfigError("NYLORUN_RESTATE_IDENTITY_KEY must be publickeyv1_<base58 Ed25519 public key>, comma-separated");
+    return keys.length > 0 ? keys : undefined;
+}
+/** Parse the stack configuration; throws `StackConfigError` naming the variable. */
+export function parseStackConfig(env, argv) {
+    const role = parseRole(argv);
+    const listen = parseListen(env);
+    const http = ["http:", "https:"];
+    const endpoints = {};
+    const databaseUrl = parseUrl(env, "NYLORUN_DATABASE_URL", [
+        "postgres:",
+        "postgresql:",
+    ]);
+    if (databaseUrl)
+        endpoints.databaseUrl = databaseUrl;
+    const restateIngressUrl = parseUrl(env, "NYLORUN_RESTATE_INGRESS_URL", http);
+    if (restateIngressUrl)
+        endpoints.restateIngressUrl = restateIngressUrl;
+    const restateAdminUrl = parseUrl(env, "NYLORUN_RESTATE_ADMIN_URL", http);
+    if (restateAdminUrl)
+        endpoints.restateAdminUrl = restateAdminUrl;
+    const workerUrl = parseUrl(env, "NYLORUN_WORKER_URL", http);
+    if (workerUrl)
+        endpoints.workerUrl = workerUrl;
+    const s2Endpoint = parseUrl(env, "NYLORUN_S2_ENDPOINT", http);
+    if (s2Endpoint)
+        endpoints.s2Endpoint = s2Endpoint;
+    const s2Token = read(env, "NYLORUN_S2_TOKEN");
+    if (s2Token)
+        endpoints.s2Token = s2Token;
+    const workspaceStoreUrl = parseUrl(env, "NYLORUN_WORKSPACE_STORE_URL", [
+        "file:",
+        "s3:",
+        "http:",
+        "https:",
+    ]);
+    if (workspaceStoreUrl)
+        endpoints.workspaceStoreUrl = workspaceStoreUrl;
+    const restateIdentityKeys = parseIdentityKeys(env);
+    if (restateIdentityKeys)
+        endpoints.restateIdentityKeys = restateIdentityKeys;
+    const publicUrl = parseUrl(env, "NYLORUN_PUBLIC_URL", http)?.replace(/\/+$/, "");
+    return {
+        role,
+        ...(listen ? { listen } : {}),
+        endpoints,
+        ...(publicUrl ? { publicUrl } : {}),
+    };
+}
+/** Endpoint summary for logs: which endpoints are set, never their values. */
+export function describeEndpoints(endpoints) {
+    return Object.entries(endpoints)
+        .filter(([, value]) => value !== undefined)
+        .map(([key]) => key)
+        .sort();
+}

package/dist/index.d.ts

@@ -7,4 +7,4 @@ export { IMAGE_MEDIA_TYPES, MAX_IMAGE_BYTES, decodeImageBase64, validateImageByt
 export type { RuntimeModelAdapter } from "./contracts.js";
 export { baselineEnvironment, hostProcessEnvironment, tenantChildEnvironment, } from "./host/environment.js";
 export type { HostProcessPathInputs } from "./host/environment.js";
-export type { HostConfigFile, HostCredentialsFile, HostStateFile, } from "./host/config.js";
+export type { HostConfigFile, HostCredentialsFile, } from "./host/config.js";

package/dist/infra/database.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Builds the Host's Postgres connection pool from the stack configuration
+ * (architecture §12.2, §14.5). One pool serves the Tenant catalog and every
+ * Tenant schema; the Host ends it at shutdown. The driver stays behind
+ * `store/postgres/connect.ts`.
+ */
+import type { StackConfig } from "../host/stack-config.js";
+import { type PostgresClient, type PostgresClientOptions } from "../store/postgres/connect.js";
+export type { PostgresClient };
+/** Throws when `NYLORUN_DATABASE_URL` is unset: there is no in-memory Session Store. */
+export declare function createDatabase(config: Pick<StackConfig, "endpoints">, options?: PostgresClientOptions): PostgresClient;
+/**
+ * Readiness probe: resolves when `select 1` answers within `signal`'s
+ * lifetime. An aborted probe cancels its query.
+ */
+export declare function probeDatabase(client: PostgresClient, signal: AbortSignal): Promise<void>;

package/dist/infra/database.js

@@ -0,0 +1,31 @@
+import { createPostgresClient, } from "../store/postgres/connect.js";
+/** Throws when `NYLORUN_DATABASE_URL` is unset: there is no in-memory Session Store. */
+export function createDatabase(config, options = {}) {
+    const url = config.endpoints.databaseUrl;
+    if (!url)
+        throw new Error("NYLORUN_DATABASE_URL is required: the Postgres URL of the Session Store");
+    return createPostgresClient(url, options);
+}
+/**
+ * Readiness probe: resolves when `select 1` answers within `signal`'s
+ * lifetime. An aborted probe cancels its query.
+ */
+export async function probeDatabase(client, signal) {
+    signal.throwIfAborted();
+    const query = client `select 1 as ok`;
+    const cancel = () => void query.cancel();
+    signal.addEventListener("abort", cancel, { once: true });
+    try {
+        await Promise.race([
+            query,
+            new Promise((_, reject) => {
+                if (signal.aborted)
+                    reject(signal.reason);
+                signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+            }),
+        ]);
+    }
+    finally {
+        signal.removeEventListener("abort", cancel);
+    }
+}

package/dist/infra/execution.d.ts

@@ -0,0 +1,39 @@
+import type { DurableExecution } from "../execution/types.js";
+import type { RuntimeRole, StackConfig } from "../host/stack-config.js";
+/** Where a Worker serves the Restate endpoint (architecture §14.3). */
+export declare const WORKER_LISTEN: {
+    readonly host: "0.0.0.0";
+    readonly port: 9080;
+};
+export interface CreateExecutionOptions {
+    /**
+     * Prepended to Restate service names, so several Runtimes or test runs can
+     * share one Restate server. Letters, digits and `_`. Default "".
+     */
+    servicePrefix?: string;
+    /** Replaces `WORKER_LISTEN` (tests serving several Workers on one machine). */
+    workerListen?: {
+        host: string;
+        port: number;
+    };
+    /** Receives the Restate SDK's log lines instead of the console. */
+    logger?: (level: string, message: string) => void;
+}
+/** Which implementation `createExecution` chooses for a configuration. */
+export declare function executionKind(config: Pick<StackConfig, "endpoints">): "restate" | "memory";
+/**
+ * Throws naming the missing variable when the Restate endpoints are
+ * incomplete for `role`. The api role never serves the Worker endpoint, so it
+ * needs no `NYLORUN_WORKER_URL`.
+ */
+export declare function validateExecutionConfig(config: Pick<StackConfig, "endpoints"> & {
+    role?: RuntimeRole;
+}): void;
+export declare function createExecution(config: Pick<StackConfig, "endpoints"> & {
+    role?: RuntimeRole;
+}, options?: CreateExecutionOptions): DurableExecution;
+/**
+ * Readiness probe: resolves when Restate's admin API and ingress answer
+ * within `signal`'s lifetime. The memory execution is always ready.
+ */
+export declare function probeExecution(execution: DurableExecution, signal: AbortSignal): Promise<void>;

package/dist/infra/execution.js

@@ -0,0 +1,68 @@
+/**
+ * Builds the Host's Durable Session Execution from the stack configuration
+ * (architecture §6, §12.3, §14.5).
+ *
+ * With `NYLORUN_RESTATE_INGRESS_URL` and `NYLORUN_RESTATE_ADMIN_URL` the Host
+ * uses Restate:
+ *
+ * - wakes, timers and sweep arming go through the ingress, so every role can
+ *   call them;
+ * - a Worker (`--role worker|all`) serves the Restate endpoint on
+ *   `0.0.0.0:9080` and registers `NYLORUN_WORKER_URL` with the admin API when
+ *   `infra/workers.ts` starts it;
+ * - with `NYLORUN_RESTATE_IDENTITY_KEY` the endpoint accepts only requests
+ *   signed by the Restate server holding the matching private key.
+ *
+ * Without Restate endpoints it returns the in-process memory execution, which
+ * only unit tests and a local development Host use.
+ */
+import { createRestateExecution } from "../adapters/execution/restate.js";
+import { MemoryExecution } from "../execution/memory.js";
+/** Where a Worker serves the Restate endpoint (architecture §14.3). */
+export const WORKER_LISTEN = { host: "0.0.0.0", port: 9080 };
+/** Which implementation `createExecution` chooses for a configuration. */
+export function executionKind(config) {
+    const { restateIngressUrl, restateAdminUrl } = config.endpoints;
+    return restateIngressUrl || restateAdminUrl ? "restate" : "memory";
+}
+/**
+ * Throws naming the missing variable when the Restate endpoints are
+ * incomplete for `role`. The api role never serves the Worker endpoint, so it
+ * needs no `NYLORUN_WORKER_URL`.
+ */
+export function validateExecutionConfig(config) {
+    const { restateIngressUrl, restateAdminUrl, workerUrl, restateIdentityKeys } = config.endpoints;
+    if (executionKind(config) === "memory") {
+        if (workerUrl || restateIdentityKeys?.length)
+            throw new Error(`${workerUrl ? "NYLORUN_WORKER_URL" : "NYLORUN_RESTATE_IDENTITY_KEY"} is set without the Restate endpoints; set NYLORUN_RESTATE_INGRESS_URL and NYLORUN_RESTATE_ADMIN_URL`);
+        return;
+    }
+    if (!restateIngressUrl)
+        throw new Error("NYLORUN_RESTATE_INGRESS_URL is required with NYLORUN_RESTATE_ADMIN_URL");
+    if (!restateAdminUrl)
+        throw new Error("NYLORUN_RESTATE_ADMIN_URL is required with NYLORUN_RESTATE_INGRESS_URL");
+    if ((config.role ?? "all") !== "api" && !workerUrl)
+        throw new Error(`NYLORUN_WORKER_URL is required for --role ${config.role ?? "all"}: the Worker endpoint URL Restate calls`);
+}
+export function createExecution(config, options = {}) {
+    validateExecutionConfig(config);
+    const { restateIngressUrl, restateAdminUrl, workerUrl, restateIdentityKeys } = config.endpoints;
+    if (!restateIngressUrl || !restateAdminUrl)
+        return new MemoryExecution();
+    return createRestateExecution({
+        ingressUrl: restateIngressUrl,
+        adminUrl: restateAdminUrl,
+        workerListen: options.workerListen ?? { ...WORKER_LISTEN },
+        ...(workerUrl ? { workerAdvertisedUrl: workerUrl } : {}),
+        ...(restateIdentityKeys?.length ? { identityKeys: [...restateIdentityKeys] } : {}),
+        ...(options.servicePrefix ? { servicePrefix: options.servicePrefix } : {}),
+        ...(options.logger ? { logger: options.logger } : {}),
+    });
+}
+/**
+ * Readiness probe: resolves when Restate's admin API and ingress answer
+ * within `signal`'s lifetime. The memory execution is always ready.
+ */
+export async function probeExecution(execution, signal) {
+    await execution.probe?.(signal);
+}

package/dist/infra/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The Host's infrastructure clients, built from the stack configuration: the
+ * Postgres pool, Durable Session Execution and Durable Streams, each only when
+ * its endpoints are configured, plus the readiness that covers them.
+ *
+ * Building a client connects to nothing: the pool connects on first query,
+ * Restate and S2 on first call. Nothing here starts a Worker (see
+ * `workers.ts`).
+ */
+import type { DurableExecution } from "../execution/types.js";
+import type { StackConfig } from "../host/stack-config.js";
+import type { DurableStreams } from "../streams/types.js";
+import type { Logger } from "../tenant/types.js";
+import { type PostgresClient } from "./database.js";
+import { type CreateExecutionOptions } from "./execution.js";
+import { type Readiness } from "./readiness.js";
+import { type CreateStreamsOptions } from "./streams.js";
+export { createDatabase, probeDatabase } from "./database.js";
+export { createExecution, probeExecution, WORKER_LISTEN } from "./execution.js";
+export { createReadiness, infraProbes } from "./readiness.js";
+export type { Probe, Readiness, ReadinessReport } from "./readiness.js";
+export { createStreams, probeStreams } from "./streams.js";
+export { servesWorker, startWorker, stopWorker } from "./workers.js";
+export type { WorkerHandle } from "./workers.js";
+export interface Infra {
+    database?: PostgresClient;
+    execution?: DurableExecution;
+    streams?: DurableStreams;
+    /** Present when at least one client was built. */
+    readiness?: Readiness;
+    /** Ends the pool and closes the streams. Does not stop a Worker. */
+    close(): Promise<void>;
+}
+/**
+ * Builds the configured clients. Throws naming the variable when endpoints are
+ * incomplete (e.g. a Restate ingress without an admin URL).
+ */
+export declare function createInfra(config: Pick<StackConfig, "role" | "endpoints">, options?: {
+    logger?: Logger;
+    execution?: CreateExecutionOptions;
+    streams?: CreateStreamsOptions;
+}): Infra;

package/dist/infra/index.js

@@ -0,0 +1,56 @@
+import { createDatabase } from "./database.js";
+import { createExecution, executionKind } from "./execution.js";
+import { createReadiness, infraProbes } from "./readiness.js";
+import { createStreams, streamsKind } from "./streams.js";
+export { createDatabase, probeDatabase } from "./database.js";
+export { createExecution, probeExecution, WORKER_LISTEN } from "./execution.js";
+export { createReadiness, infraProbes } from "./readiness.js";
+export { createStreams, probeStreams } from "./streams.js";
+export { servesWorker, startWorker, stopWorker } from "./workers.js";
+/**
+ * Builds the configured clients. Throws naming the variable when endpoints are
+ * incomplete (e.g. a Restate ingress without an admin URL).
+ */
+export function createInfra(config, options = {}) {
+    const database = config.endpoints.databaseUrl ? createDatabase(config) : undefined;
+    const execution = executionKind(config) === "restate"
+        ? createExecution(config, options.execution)
+        : undefined;
+    const streams = streamsKind(config) === "s2" ? createStreams(config, options.streams) : undefined;
+    const probes = infraProbes({
+        ...(database ? { database } : {}),
+        ...(execution ? { execution } : {}),
+        ...(streams ? { streams } : {}),
+    });
+    const readiness = Object.keys(probes).length > 0
+        ? logTransitions(createReadiness(probes), options.logger)
+        : undefined;
+    return {
+        ...(database ? { database } : {}),
+        ...(execution ? { execution } : {}),
+        ...(streams ? { streams } : {}),
+        ...(readiness ? { readiness } : {}),
+        async close() {
+            await Promise.allSettled([database?.end({ timeout: 5 }), streams?.close()]);
+        },
+    };
+}
+/** Logs a check when it starts failing and when it recovers, not on every probe. */
+function logTransitions(readiness, logger) {
+    if (!logger)
+        return readiness;
+    const failing = new Set();
+    return async () => {
+        const report = await readiness();
+        for (const [name, ok] of Object.entries(report.checks)) {
+            if (!ok && !failing.has(name)) {
+                failing.add(name);
+                logger.warn("ready_check_failed", { check: name, error: report.errors[name] });
+            }
+            else if (ok && failing.delete(name)) {
+                logger.info("ready_check_recovered", { check: name });
+            }
+        }
+        return report;
+    };
+}

package/dist/infra/readiness.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Aggregate readiness of the Host's infrastructure (architecture §13, §14.3):
+ * the Runtime's `/ready` covers Postgres, Restate and S2. s2-lite's image has
+ * no health check of its own, so this is the only place its health shows.
+ *
+ * Every probe runs on each call, in parallel, bounded by one timeout. A probe
+ * that throws or outlives the timeout marks its check `false`. Only check
+ * names and booleans are reported; the errors stay in the report for logs.
+ */
+import type { DurableExecution } from "../execution/types.js";
+import type { DurableStreams } from "../streams/types.js";
+import { type PostgresClient } from "./database.js";
+/** Resolves when the dependency answers; rejects otherwise. Must honour `signal`. */
+export type Probe = (signal: AbortSignal) => Promise<void>;
+export interface ReadinessReport {
+    ok: boolean;
+    /** One entry per configured dependency, e.g. `{ postgres, restate, s2 }`. */
+    checks: Record<string, boolean>;
+    /** Why each failing check failed. Not for unauthenticated responses. */
+    errors: Record<string, string>;
+}
+export type Readiness = () => Promise<ReadinessReport>;
+/** Default bound on one readiness pass. Compose probes `/ready` every 2 s with a 5 s timeout. */
+export declare const READINESS_TIMEOUT_MS = 2000;
+export declare function createReadiness(probes: Readonly<Record<string, Probe>>, options?: {
+    timeoutMs?: number;
+}): Readiness;
+/** The standard checks for whichever infrastructure the Host was built with. */
+export declare function infraProbes(infra: {
+    database?: PostgresClient;
+    execution?: DurableExecution;
+    streams?: DurableStreams;
+}): Record<string, Probe>;

package/dist/infra/readiness.js

@@ -0,0 +1,53 @@
+import { probeDatabase } from "./database.js";
+import { probeExecution } from "./execution.js";
+import { probeStreams } from "./streams.js";
+/** Default bound on one readiness pass. Compose probes `/ready` every 2 s with a 5 s timeout. */
+export const READINESS_TIMEOUT_MS = 2000;
+export function createReadiness(probes, options = {}) {
+    const timeoutMs = options.timeoutMs ?? READINESS_TIMEOUT_MS;
+    return async () => {
+        const entries = Object.entries(probes);
+        const results = await Promise.all(entries.map(async ([name, probe]) => [name, await runProbe(probe, timeoutMs)]));
+        const checks = {};
+        const errors = {};
+        for (const [name, error] of results) {
+            checks[name] = error === undefined;
+            if (error !== undefined)
+                errors[name] = error;
+        }
+        return { ok: Object.values(checks).every(Boolean), checks, errors };
+    };
+}
+/** The standard checks for whichever infrastructure the Host was built with. */
+export function infraProbes(infra) {
+    const probes = {};
+    const { database, execution, streams } = infra;
+    if (database)
+        probes.postgres = (signal) => probeDatabase(database, signal);
+    if (execution)
+        probes.restate = (signal) => probeExecution(execution, signal);
+    if (streams)
+        probes.s2 = (signal) => probeStreams(streams, signal);
+    return probes;
+}
+/** Runs one probe under a timeout; returns its failure message, or undefined when ready. */
+async function runProbe(probe, timeoutMs) {
+    const controller = new AbortController();
+    let timer;
+    const timedOut = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            controller.abort(new Error(`timed out after ${timeoutMs} ms`));
+            resolve(`timed out after ${timeoutMs} ms`);
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([
+            probe(controller.signal).then(() => undefined, (error) => (error instanceof Error ? error.message : String(error))),
+            timedOut,
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort(new Error("readiness pass finished"));
+    }
+}

package/dist/infra/streams.d.ts

@@ -0,0 +1,17 @@
+import type { StackConfig } from "../host/stack-config.js";
+import type { DurableStreams } from "../streams/types.js";
+export interface CreateStreamsOptions {
+    /**
+     * Prepended to every basin name, so several Hosts or test runs can share one
+     * S2 account. See `streams/basin.ts`. Default "".
+     */
+    basinPrefix?: string;
+}
+/** Which implementation `createStreams` chooses for a configuration. */
+export declare function streamsKind(config: Pick<StackConfig, "endpoints">): "s2" | "memory";
+export declare function createStreams(config: Pick<StackConfig, "endpoints">, options?: CreateStreamsOptions): DurableStreams;
+/**
+ * Readiness probe: resolves when the streams' service answers within
+ * `signal`'s lifetime. In-memory streams are always ready.
+ */
+export declare function probeStreams(streams: DurableStreams, signal: AbortSignal): Promise<void>;

package/dist/infra/streams.js

@@ -0,0 +1,33 @@
+/**
+ * Builds the Host's Durable Streams from the stack configuration
+ * (architecture §12.4, §14.5). Only endpoints are configurable, never the kind:
+ * with `NYLORUN_S2_ENDPOINT` the Host uses S2 (s2-lite on a developer machine,
+ * or the S2 service); without it, the in-memory implementation, which only
+ * unit tests and a local development Host use.
+ */
+import { createS2Streams } from "../adapters/streams/s2.js";
+import { MemoryStreams } from "../streams/memory.js";
+/** Which implementation `createStreams` chooses for a configuration. */
+export function streamsKind(config) {
+    return config.endpoints.s2Endpoint ? "s2" : "memory";
+}
+export function createStreams(config, options = {}) {
+    const { s2Endpoint, s2Token } = config.endpoints;
+    if (!s2Endpoint) {
+        if (s2Token)
+            throw new Error("NYLORUN_S2_TOKEN is set without NYLORUN_S2_ENDPOINT; set the endpoint too");
+        return new MemoryStreams();
+    }
+    return createS2Streams({
+        endpoint: s2Endpoint,
+        ...(s2Token ? { token: s2Token } : {}),
+        ...(options.basinPrefix ? { basinPrefix: options.basinPrefix } : {}),
+    });
+}
+/**
+ * Readiness probe: resolves when the streams' service answers within
+ * `signal`'s lifetime. In-memory streams are always ready.
+ */
+export async function probeStreams(streams, signal) {
+    await streams.probe?.(signal);
+}

package/dist/infra/workers.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Worker lifecycle by role (architecture §6).
+ *
+ * | Role | Serves | `execution.start` |
+ * | --- | --- | --- |
+ * | `api` | Tenant API, Admin API, SSE | **never**: wakes, timers and sweep arming go through Restate's ingress, which needs no Worker endpoint |
+ * | `worker` | the Restate endpoint (`NylorunSession.advance`, `NylorunTenant.sweep`, timers) | yes |
+ * | `all` | both (the local stack) | yes |
+ *
+ * An API node that called `start` would register its own endpoint with
+ * Restate, and Restate would send new invocations to it (it routes to the
+ * latest registered deployment), so the rule is enforced here rather than left
+ * to callers: `startWorker` with role `api` returns a handle that never
+ * started anything.
+ */
+import type { DurableExecution, WorkerHandlers } from "../execution/types.js";
+import type { RuntimeRole } from "../host/stack-config.js";
+export interface WorkerHandle {
+    readonly role: RuntimeRole;
+    /** True when this process serves the Worker endpoint. */
+    readonly serving: boolean;
+}
+/** Whether a process in `role` serves the Worker endpoint. */
+export declare function servesWorker(role: RuntimeRole): boolean;
+/**
+ * Starts delivering Restate invocations to `handlers` when `role` is `worker`
+ * or `all` (serving and registering the Worker endpoint, for Restate). For
+ * `api` it does nothing. Rejects if the endpoint cannot listen or register.
+ */
+export declare function startWorker(input: {
+    role: RuntimeRole;
+    execution: DurableExecution;
+    handlers: WorkerHandlers;
+}): Promise<WorkerHandle>;
+/**
+ * Stops a Worker started by `startWorker`: aborts running advances' signals
+ * and waits for them. Idempotent; a no-op for the api role.
+ */
+export declare function stopWorker(handle: WorkerHandle): Promise<void>;

package/dist/infra/workers.js

@@ -0,0 +1,31 @@
+/** Whether a process in `role` serves the Worker endpoint. */
+export function servesWorker(role) {
+    return role !== "api";
+}
+/** What `stopWorker` needs for a handle that serves the endpoint. */
+const started = new WeakMap();
+/**
+ * Starts delivering Restate invocations to `handlers` when `role` is `worker`
+ * or `all` (serving and registering the Worker endpoint, for Restate). For
+ * `api` it does nothing. Rejects if the endpoint cannot listen or register.
+ */
+export async function startWorker(input) {
+    const { role, execution, handlers } = input;
+    const handle = Object.freeze({ role, serving: servesWorker(role) });
+    if (!handle.serving)
+        return handle;
+    await execution.start(handlers);
+    started.set(handle, { execution });
+    return handle;
+}
+/**
+ * Stops a Worker started by `startWorker`: aborts running advances' signals
+ * and waits for them. Idempotent; a no-op for the api role.
+ */
+export async function stopWorker(handle) {
+    const worker = started.get(handle);
+    if (!worker)
+        return;
+    worker.stopped ??= worker.execution.stop();
+    await worker.stopped;
+}