@datalayer/agent-runtimes 1.5.45 → 1.5.46

package/lib/portable/hosts/deadLetters.js

@@ -0,0 +1,124 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Dead letters (SLACK §9, S-405; DISCORD DC-403): jobs that failed five
+ * times. By default an operator sees their metadata and a hash of their
+ * payload — never the words of a prompt or a delivery. Replaying puts one
+ * back to work, once. Reading a payload is privileged: a dead job's only, it
+ * needs a reason, is recorded in `<prefix>_payload_access` and audited, and
+ * its credentials are still redacted. Every replay is kept in
+ * `<prefix>_job_replays` with who asked. Moved from the Slack service
+ * (plans/DISCORD.md DC-004); each service keeps only the bin that opens its
+ * database and calls `runDeadLettersCli`.
+ *
+ * @module portable/hosts/deadLetters
+ */
+import { createHash } from 'node:crypto';
+import { Logger, redact, redactCredentials } from './observability';
+import { PostgresWorkQueue } from './postgresQueue';
+import { tablePrefixOf } from './queue';
+export function payloadHash(payload) {
+    return createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+}
+export class DeadLetters {
+    database;
+    queue;
+    logger;
+    #access;
+    #queueName;
+    constructor(database, queue, logger = new Logger()) {
+        this.database = database;
+        this.queue = queue;
+        this.logger = logger;
+        const prefix = tablePrefixOf(queue.tablePrefix);
+        this.#access = `${prefix}_payload_access`;
+        this.#queueName = `${prefix}-queue`;
+    }
+    async list(limit = 50) {
+        const dead = await this.queue.dead(limit);
+        return Promise.all(dead.map(async (one) => ({
+            attempts: one.attempts,
+            createdAt: one.createdAt,
+            id: one.id,
+            kind: one.kind,
+            lastError: String(redact(one.lastError ?? '')),
+            payloadHash: payloadHash(await this.queue.payloadOf(one.id)),
+        })));
+    }
+    async replay(id, operator) {
+        if (!operator.trim()) {
+            throw new Error('Name who replays the job.');
+        }
+        const replayed = await this.queue.replay(id, operator);
+        this.logger.audit('admin.changed', {
+            by: operator,
+            installation: this.#queueName,
+            job: id,
+            reason: replayed ? 'dead job replayed' : 'not a dead job',
+        });
+        return replayed;
+    }
+    /** A payload, for a stated reason, recorded and audited; secrets still redacted. */
+    async payload(id, operator, reason) {
+        if (reason.trim().length < 10) {
+            throw new Error('Say why the payload is read: ten characters at least.');
+        }
+        if (!operator.trim()) {
+            throw new Error('Name who reads the payload.');
+        }
+        // A dead job's only: a live job or an unknown id is refused, and no read
+        // of it is recorded.
+        const payload = await this.queue.payloadOf(id);
+        if (payload === undefined) {
+            throw new Error(`Job ${id} is not a dead job: there is no payload to read.`);
+        }
+        await this.database.query(`INSERT INTO ${this.#access} (job_id, operator, reason) VALUES ($1, $2, $3)`, [id, operator, reason.slice(0, 1_000)]);
+        this.logger.audit('payload.read', {
+            by: operator,
+            installation: this.#queueName,
+            job: id,
+            reason: 'privileged payload access',
+        });
+        return redactCredentials(payload);
+    }
+}
+/** The dead letters of a host's queue (`<prefix>_jobs`). */
+export function deadLetters(database, tablePrefix, logger) {
+    return new DeadLetters(database, new PostgresWorkQueue(database, tablePrefix), logger);
+}
+export const DEAD_LETTERS_USAGE = 'Usage: dead-letters list | replay <id> | payload <id> <reason>';
+/**
+ * `dead-letters list | replay <id> | payload <id> <reason…>`: metadata and
+ * hashes by default (S-405). Who acts is said in `operator`
+ * (`DATALAYER_OPERATOR`), never taken from the container's user: a replay
+ * and a payload read are kept with this name. Answers the exit code.
+ */
+export async function runDeadLettersCli(letters, argv, operator, out = {
+    table: rows => console.table(rows),
+    info: line => console.info(line),
+    error: line => console.error(line),
+}) {
+    const [command, id, ...rest] = argv;
+    if (!operator.trim()) {
+        out.error('DATALAYER_OPERATOR is required: the name kept with every replay and payload read.');
+        return 1;
+    }
+    if (command === 'list') {
+        out.table(await letters.list());
+        return 0;
+    }
+    if (command === 'replay' && id) {
+        out.info((await letters.replay(id, operator))
+            ? `Job ${id} is back to work.`
+            : `Job ${id} is not a dead job.`);
+        return 0;
+    }
+    if (command === 'payload' && id) {
+        out.info(JSON.stringify(await letters.payload(id, operator, rest.join(' ')), null, 2));
+        return 0;
+    }
+    out.error(DEAD_LETTERS_USAGE);
+    return 1;
+}

package/lib/portable/hosts/deliveries.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Datalayer's deliveries to a chat host (SLACK §4.3, 3; DISCORD §3.8): the
+ * signed webhook ai-agents pushes to, the outbox read when a push was
+ * missed, and each delivery handled once then acknowledged. What a delivery
+ * shows is the host's own (its `DeliveryHandler`); where its installations
+ * and claims are kept is its store, seen here as a `DeliverySink` and a
+ * `DeliveryClaimStore`. Moved from the Slack service (plans/DISCORD.md
+ * DC-004).
+ *
+ * @module portable/hosts/deliveries
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { DatalayerHostClient } from './client';
+import { type HostDelivery } from './contracts';
+/** Where Datalayer pushes an installation's deliveries, under the service's public address. */
+export declare const DELIVERY_PATH = "/datalayer/deliveries";
+export declare const DELIVERY_ROUTE = "/datalayer/deliveries/:hostUid";
+export type DeliveryJob = Readonly<{
+    delivery: HostDelivery;
+    hostUid: string;
+}>;
+/** A host installation bound at Datalayer: its uid and key. */
+export type BoundHostKey = Readonly<{
+    hostKey: string;
+    hostUid: string;
+}>;
+/** Where a host keeps its installations, as deliveries read them. */
+export interface DeliverySink {
+    /** What Datalayer signs an installation's pushes with, or `undefined` for an unknown one. */
+    deliverySecretOf(hostUid: string): Promise<string | undefined>;
+    /** The installation's key, or `undefined` once it was removed (late work is dropped). */
+    hostKeyOf(hostUid: string): Promise<string | undefined>;
+    /** Every installation bound at Datalayer: whose outbox is read. */
+    boundHosts(): Promise<readonly BoundHostKey[]>;
+}
+/** Where a host keeps what it handled once: a claim taken, or released when handling failed. */
+export interface DeliveryClaimStore {
+    claimEvent(id: string): Promise<boolean>;
+    releaseEvent(id: string): Promise<void>;
+}
+/**
+ * Handle one delivery of an installation once (claimed by its uid), then
+ * acknowledge it at Datalayer. A removed installation's delivery is dropped;
+ * a handling that fails releases its claim, so the queue tries again.
+ */
+export declare function receiveDelivery(job: DeliveryJob, input: {
+    sink: DeliverySink;
+    claims: DeliveryClaimStore;
+    client: Pick<DatalayerHostClient, 'acknowledge'>;
+    handle: (delivery: HostDelivery) => Promise<void>;
+}): Promise<void>;
+/**
+ * The signed webhook Datalayer pushes to (`POST /datalayer/deliveries/{host}`,
+ * registered with `PUT …/self/delivery`): verified with that installation's
+ * secret — HMAC over `<timestamp>.<body>`, five minutes at most — then queued
+ * and acknowledged with 2xx at once; the work runs from the queue.
+ */
+export declare function deliveryRoute(sink: Pick<DeliverySink, 'deliverySecretOf'>, enqueue: (job: DeliveryJob) => Promise<void>, nowSeconds?: () => number): (request: IncomingMessage & {
+    params?: Record<string, string | string[]>;
+}, response: ServerResponse) => Promise<void>;
+/**
+ * The outbox, read when a push was missed or no address is registered
+ * (`GET …/self/deliveries`): each delivery of every bound installation
+ * queued, handled once, then acknowledged.
+ */
+export declare class DeliveryPoller {
+    #private;
+    readonly sink: Pick<DeliverySink, 'boundHosts'>;
+    readonly client: Pick<DatalayerHostClient, 'outbox'>;
+    readonly enqueue: (job: DeliveryJob) => Promise<void>;
+    readonly logger: Pick<Console, 'warn'>;
+    constructor(sink: Pick<DeliverySink, 'boundHosts'>, client: Pick<DatalayerHostClient, 'outbox'>, enqueue: (job: DeliveryJob) => Promise<void>, logger?: Pick<Console, 'warn'>);
+    pollOnce(): Promise<number>;
+    start(intervalSeconds: number): void;
+    stop(): void;
+}

package/lib/portable/hosts/deliveries.js

@@ -0,0 +1,147 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { DELIVERY_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER, verifyDelivery, } from './contracts';
+/** Where Datalayer pushes an installation's deliveries, under the service's public address. */
+export const DELIVERY_PATH = '/datalayer/deliveries';
+export const DELIVERY_ROUTE = `${DELIVERY_PATH}/:hostUid`;
+const DELIVERY_BODY_LIMIT = 64 * 1024;
+/**
+ * Handle one delivery of an installation once (claimed by its uid), then
+ * acknowledge it at Datalayer. A removed installation's delivery is dropped;
+ * a handling that fails releases its claim, so the queue tries again.
+ */
+export async function receiveDelivery(job, input) {
+    const hostKey = await input.sink.hostKeyOf(job.hostUid);
+    if (!hostKey) {
+        return;
+    }
+    const claim = `delivery:${job.hostUid}:${job.delivery.delivery}`;
+    if (await input.claims.claimEvent(claim)) {
+        try {
+            await input.handle(job.delivery);
+        }
+        catch (error) {
+            await input.claims.releaseEvent(claim);
+            throw error;
+        }
+    }
+    await input.client.acknowledge(hostKey, job.delivery.delivery);
+}
+async function rawBodyOf(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > DELIVERY_BODY_LIMIT) {
+            throw new Error('The delivery is too large.');
+        }
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * The signed webhook Datalayer pushes to (`POST /datalayer/deliveries/{host}`,
+ * registered with `PUT …/self/delivery`): verified with that installation's
+ * secret — HMAC over `<timestamp>.<body>`, five minutes at most — then queued
+ * and acknowledged with 2xx at once; the work runs from the queue.
+ */
+export function deliveryRoute(sink, enqueue, nowSeconds) {
+    return async (request, response) => {
+        const answer = (status, body) => {
+            response.writeHead(status, { 'content-type': 'application/json' });
+            response.end(JSON.stringify(body));
+        };
+        try {
+            const named = request.params?.hostUid;
+            const hostUid = typeof named === 'string' ? named : '';
+            const secret = hostUid ? await sink.deliverySecretOf(hostUid) : undefined;
+            if (!secret) {
+                return answer(404, { ok: false, error: 'unknown installation' });
+            }
+            const header = (name) => {
+                const value = request.headers[name.toLowerCase()];
+                return Array.isArray(value) ? value[0] : value;
+            };
+            const rawBody = await rawBodyOf(request);
+            let delivery;
+            try {
+                delivery = verifyDelivery({
+                    nowSeconds: nowSeconds?.(),
+                    rawBody,
+                    secret,
+                    signature: header(SIGNATURE_HEADER),
+                    timestamp: header(TIMESTAMP_HEADER),
+                });
+            }
+            catch {
+                return answer(401, { ok: false, error: 'not verified' });
+            }
+            if (header(DELIVERY_HEADER) &&
+                header(DELIVERY_HEADER) !== delivery.delivery) {
+                return answer(400, { ok: false, error: 'delivery mismatch' });
+            }
+            await enqueue({ delivery, hostUid });
+            return answer(200, { ok: true });
+        }
+        catch {
+            return answer(500, { ok: false });
+        }
+    };
+}
+/**
+ * The outbox, read when a push was missed or no address is registered
+ * (`GET …/self/deliveries`): each delivery of every bound installation
+ * queued, handled once, then acknowledged.
+ */
+export class DeliveryPoller {
+    sink;
+    client;
+    enqueue;
+    logger;
+    #timer;
+    #running = false;
+    constructor(sink, client, enqueue, logger = console) {
+        this.sink = sink;
+        this.client = client;
+        this.enqueue = enqueue;
+        this.logger = logger;
+    }
+    async pollOnce() {
+        let queued = 0;
+        for (const { hostKey, hostUid } of await this.sink.boundHosts()) {
+            try {
+                for (const delivery of await this.client.outbox(hostKey)) {
+                    await this.enqueue({ delivery, hostUid });
+                    queued += 1;
+                }
+            }
+            catch (error) {
+                this.logger.warn(`The outbox of one installation was not read: ${error.message}`);
+            }
+        }
+        return queued;
+    }
+    start(intervalSeconds) {
+        if (intervalSeconds <= 0 || this.#timer) {
+            return;
+        }
+        this.#timer = setInterval(() => {
+            if (this.#running) {
+                return;
+            }
+            this.#running = true;
+            void this.pollOnce().finally(() => {
+                this.#running = false;
+            });
+        }, intervalSeconds * 1000);
+        this.#timer.unref?.();
+    }
+    stop() {
+        if (this.#timer) {
+            clearInterval(this.#timer);
+        }
+        this.#timer = undefined;
+    }
+}

package/lib/portable/hosts/forbiddenGraph.d.ts

@@ -0,0 +1,77 @@
+/**
+ * What may never reach a host service's production code (SLACK §4.2, S-005;
+ * DISCORD §4.2): Jupyter, JupyterLab, Lumino, Datalayer's Jupyter packages,
+ * React, Primer, Reactor and the other host services. Checked over the
+ * service's source imports, its esbuild bundle's module graph
+ * (`forbiddenInBundle`, over the metafile) and the installed graph of the
+ * bundle's externals (`npm ls --omit=dev --omit=peer --all`). Pure functions:
+ * each service reads its files and runs them. Moved from the Slack service
+ * (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/forbiddenGraph
+ */
+export declare const FORBIDDEN: readonly RegExp[];
+/** A package reached, with the chain of dependencies that reached it. */
+export type Reached = Readonly<{
+    chain: string[];
+    name: string;
+}>;
+type LockPackage = {
+    dependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    peerDependenciesMeta?: Record<string, {
+        optional?: boolean;
+    }>;
+};
+/** A lockfile, v2 or v3: its `packages`. */
+export type Lockfile = {
+    packages?: Record<string, LockPackage>;
+};
+/** What `npm ls --json` answers: each package and its own dependencies. */
+export type InstalledTree = {
+    dependencies?: Record<string, InstalledTree | undefined>;
+};
+export declare const isForbidden: (name: string) => boolean;
+/** The package name an import specifier names: `@scope/name/deep` → `@scope/name`. */
+export declare function packageOf(specifier: string): string | undefined;
+/** Every bare import of one source file. */
+export declare function importsOf(source: string): string[];
+/**
+ * The production graph of a lockfile (v2/v3 `packages`): from the root's
+ * `dependencies` and `optionalDependencies` (never `devDependencies`), each
+ * package's own dependencies resolved the way Node resolves them — the
+ * nearest `node_modules` up from the dependent. Answers each package reached
+ * with the chain that reached it.
+ */
+export declare function productionGraph(lock: Lockfile): Reached[];
+/**
+ * The production graph as `npm ls --omit=dev --all --json` answers it, from
+ * what is installed: what the service runs with, whether a lockfile is kept
+ * or not (the monorepo keeps none). Each package with the chain reaching it.
+ */
+export declare function installedGraph(tree: InstalledTree): Reached[];
+/** The forbidden packages an installed graph reaches, each with its chain. */
+export declare function forbiddenInInstalled(tree: InstalledTree): string[];
+/** The forbidden packages a lockfile's production graph reaches, each with its chain. */
+export declare function forbiddenInGraph(lock: Lockfile): string[];
+/** The parts of an esbuild metafile the bundle gate reads. */
+export type BundleMetafile = {
+    inputs: Record<string, unknown>;
+    outputs: Record<string, {
+        imports?: ReadonlyArray<{
+            path: string;
+            external?: boolean;
+        }>;
+    }>;
+};
+/**
+ * What a service's esbuild bundle may hold (DISCORD §4.2): its own sources,
+ * and agent-runtimes' `lib/portable` (by its real path: the monorepo's
+ * workspace link resolves to `ai/agent-runtimes/lib/portable/…`). Every
+ * other module is a package's, and refused; every external is a `node:`
+ * builtin or a name in the service's `dependencies`; nothing matches
+ * `FORBIDDEN`. Answers each violation in words.
+ */
+export declare function forbiddenInBundle(metafile: BundleMetafile, dependencies: readonly string[]): string[];
+export {};

package/lib/portable/hosts/forbiddenGraph.js

@@ -0,0 +1,174 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * What may never reach a host service's production code (SLACK §4.2, S-005;
+ * DISCORD §4.2): Jupyter, JupyterLab, Lumino, Datalayer's Jupyter packages,
+ * React, Primer, Reactor and the other host services. Checked over the
+ * service's source imports, its esbuild bundle's module graph
+ * (`forbiddenInBundle`, over the metafile) and the installed graph of the
+ * bundle's externals (`npm ls --omit=dev --omit=peer --all`). Pure functions:
+ * each service reads its files and runs them. Moved from the Slack service
+ * (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/forbiddenGraph
+ */
+export const FORBIDDEN = [
+    /^@jupyter\//,
+    /^@jupyterlab\//,
+    /^@jupyter-widgets\//,
+    /^@lumino\//,
+    /^@datalayer\/jupyter-/,
+    /^react-dom$/,
+    /^react$/,
+    /^@primer\//,
+    /^@datalayer\/reactor$/,
+    /^@datalayer\/slack$/,
+    /^@datalayer\/discord$/,
+];
+export const isForbidden = (name) => FORBIDDEN.some(pattern => pattern.test(name));
+/** The package name an import specifier names: `@scope/name/deep` → `@scope/name`. */
+export function packageOf(specifier) {
+    if (specifier.startsWith('.') || specifier.startsWith('node:'))
+        return undefined;
+    const parts = specifier.split('/');
+    return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+/** Every bare import of one source file. */
+export function importsOf(source) {
+    const found = new Set();
+    const patterns = [
+        /\bimport\s+(?:type\s+)?(?:[^'"]*?\sfrom\s+)?["']([^"']+)["']/g,
+        /\bexport\s+(?:type\s+)?[^'"]*?\sfrom\s+["']([^"']+)["']/g,
+        /\bimport\(\s*["']([^"']+)["']\s*\)/g,
+        /\brequire\(\s*["']([^"']+)["']\s*\)/g,
+    ];
+    for (const pattern of patterns)
+        for (const match of source.matchAll(pattern)) {
+            const name = packageOf(match[1] ?? '');
+            if (name)
+                found.add(name);
+        }
+    return [...found];
+}
+/**
+ * The production graph of a lockfile (v2/v3 `packages`): from the root's
+ * `dependencies` and `optionalDependencies` (never `devDependencies`), each
+ * package's own dependencies resolved the way Node resolves them — the
+ * nearest `node_modules` up from the dependent. Answers each package reached
+ * with the chain that reached it.
+ */
+export function productionGraph(lock) {
+    const packages = lock.packages ?? {};
+    const root = packages[''] ?? {};
+    const resolve = (from, name) => {
+        let base = from;
+        while (true) {
+            const candidate = `${base ? `${base}/` : ''}node_modules/${name}`;
+            if (packages[candidate])
+                return candidate;
+            if (!base)
+                return undefined;
+            const index = base.lastIndexOf('/node_modules/');
+            base = index >= 0 ? base.slice(0, index) : '';
+        }
+    };
+    const reached = new Map();
+    const queue = [];
+    for (const name of Object.keys({
+        ...root.dependencies,
+        ...root.optionalDependencies,
+    }))
+        queue.push({ chain: [name], from: '', name });
+    while (queue.length > 0) {
+        const { chain, from, name } = queue.shift();
+        const path = resolve(from, name);
+        if (!path || reached.has(path))
+            continue;
+        reached.set(path, { chain, name });
+        const meta = packages[path] ?? {};
+        for (const next of Object.keys({
+            ...meta.dependencies,
+            ...meta.optionalDependencies,
+            ...meta.peerDependencies,
+        }))
+            if (!(meta.peerDependenciesMeta?.[next]?.optional && !resolve(path, next)))
+                queue.push({ chain: [...chain, next], from: path, name: next });
+    }
+    return [...reached.values()];
+}
+/**
+ * The production graph as `npm ls --omit=dev --all --json` answers it, from
+ * what is installed: what the service runs with, whether a lockfile is kept
+ * or not (the monorepo keeps none). Each package with the chain reaching it.
+ */
+export function installedGraph(tree) {
+    const reached = [];
+    const seen = new Set();
+    const walk = (dependencies, chain) => {
+        for (const [name, node] of Object.entries(dependencies ?? {})) {
+            const id = `${chain.join('>')}>${name}`;
+            if (seen.has(id) || chain.includes(name))
+                continue;
+            seen.add(id);
+            reached.push({ chain: [...chain, name], name });
+            walk(node?.dependencies, [...chain, name]);
+        }
+    };
+    walk(tree.dependencies, []);
+    return reached;
+}
+/** The forbidden packages an installed graph reaches, each with its chain. */
+export function forbiddenInInstalled(tree) {
+    return installedGraph(tree)
+        .filter(one => isForbidden(one.name))
+        .map(one => one.chain.join(' → '));
+}
+/** The forbidden packages a lockfile's production graph reaches, each with its chain. */
+export function forbiddenInGraph(lock) {
+    return productionGraph(lock)
+        .filter(one => isForbidden(one.name))
+        .map(one => one.chain.join(' → '));
+}
+/** Where agent-runtimes' portable code lies, by the real path esbuild reads it from. */
+const PORTABLE = /(^|\/)agent-runtimes\/lib\/portable\//;
+/**
+ * What a service's esbuild bundle may hold (DISCORD §4.2): its own sources,
+ * and agent-runtimes' `lib/portable` (by its real path: the monorepo's
+ * workspace link resolves to `ai/agent-runtimes/lib/portable/…`). Every
+ * other module is a package's, and refused; every external is a `node:`
+ * builtin or a name in the service's `dependencies`; nothing matches
+ * `FORBIDDEN`. Answers each violation in words.
+ */
+export function forbiddenInBundle(metafile, dependencies) {
+    const violations = [];
+    for (const input of Object.keys(metafile.inputs)) {
+        const portable = PORTABLE.test(input);
+        const modules = input.lastIndexOf('node_modules/');
+        const name = modules >= 0
+            ? packageOf(input.slice(modules + 'node_modules/'.length))
+            : undefined;
+        if (name && isForbidden(name))
+            violations.push(`${input}: ${name} is forbidden`);
+        else if (!portable && (modules >= 0 || input.startsWith('../')))
+            violations.push(`${input}: bundled from outside the service and agent-runtimes' lib/portable`);
+    }
+    const externals = new Set();
+    for (const output of Object.values(metafile.outputs))
+        for (const one of output.imports ?? [])
+            if (one.external)
+                externals.add(one.path);
+    for (const path of externals) {
+        if (path.startsWith('node:'))
+            continue;
+        const name = packageOf(path);
+        if (!name)
+            violations.push(`${path}: a relative external`);
+        else if (isForbidden(name))
+            violations.push(`${path}: ${name} is forbidden`);
+        else if (!dependencies.includes(name))
+            violations.push(`${path}: external, but ${name} is not one of the service's dependencies`);
+    }
+    return violations;
+}

package/lib/portable/hosts/health.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Liveness and readiness (SLACK §10, S-101; DISCORD §10): `/healthz` says the
+ * process answers; `/readyz` says it can take durable work now — its store
+ * and its queue answer — and never asks the host or Datalayer, so a
+ * transient outage of either does not take the pods out of service: accepted
+ * work waits in the queue instead. And the window a signed host request's
+ * timestamp must fall in. Moved from the Slack service (plans/DISCORD.md
+ * DC-004).
+ *
+ * @module portable/hosts/health
+ */
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+export type ReadinessChecks = Readonly<Record<string, () => Promise<boolean>>>;
+/** Each check, at most `timeoutMs`: a check that throws or is late is not ready. */
+export declare function readiness(checks: ReadinessChecks, timeoutMs?: number): Promise<{
+    ready: boolean;
+    checks: Record<string, boolean>;
+}>;
+/** The health paths, and what each answers. */
+export declare const HEALTH_PATHS: readonly ["/healthz", "/readyz"];
+/**
+ * Answer `GET /healthz` or `GET /readyz`; `false` for any other request,
+ * which the caller answers.
+ */
+export declare function answerHealth(checks: ReadinessChecks, request: IncomingMessage, response: ServerResponse): boolean;
+/** A worker's own server: its health and readiness only (no host route). */
+export declare function healthServer(checks: ReadinessChecks): Server;
+/** How far a signed host request's timestamp may be from now, either way (SLACK §7.1, 1; DISCORD §7.1, 1). */
+export declare const REQUEST_WINDOW_SECONDS: number;
+/**
+ * Whether a request's timestamp header (Slack's `X-Slack-Request-Timestamp`,
+ * Discord's `X-Signature-Timestamp`) is within five minutes of now, in the
+ * past or the future: a replay with a skewed clock is refused too.
+ */
+export declare function timestampWithinWindow(header: string | string[] | undefined, nowSeconds?: number): boolean;