@sigrun/ext-gateway 0.0.0-stage → 0.1.1

package/dist/engine.js

@@ -0,0 +1,645 @@
+/**
+ * The gateway engine (spec §8.0, gateway C2): chat-transport supervision
+ * over the boot's channel bindings. ONE engine per boot; `start` runs
+ * after the server listens, `stopIntake` before the shutdown drain,
+ * `stop` after it.
+ *
+ * Task 2 owns supervision: `start` reads the LIVE config once for the
+ * restart-required enablement (a channel absent from `channels`, an
+ * `enabled: false`, or a `{failed}` config block never starts its
+ * adapter — the engine records a static row instead), then hands every
+ * enabled channel a {@link Supervisor}. Health (§8.12) reads the
+ * supervisors' unhealthy dwell plus the ledger's failed-in-last-hour
+ * count (Task 5: the engine-owned ledger feeds the `failedRecently`
+ * seam — tests may still override it).
+ *
+ * The inbound pipeline (Task 3) drives `receive` (§8.4): the config
+ * block is read LIVE per event, admission runs the ordered steps, and
+ * the supervisor counts every outcome. `action` (button taps) stays a
+ * no-op until the token table lands (Tasks 4/9).
+ *
+ * `EngineInternals` is the test/task-internal surface (the state-dir
+ * path, the status read) — NOT part of the loader contract, which sees
+ * only the {@link GatewayEngine} four.
+ */
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { readConfig } from "./config.js";
+import { createLog } from "./log.js";
+import { createPipeline } from "./inbound/pipeline.js";
+import { Supervisor, } from "./supervisor.js";
+import { PairingStore } from "./access/pairing.js";
+import { LinkCodes } from "./access/link-codes.js";
+import { LoopGuard } from "./access/loop-guard.js";
+import { ButtonTokens } from "./inbound/tokens.js";
+import { chatCommandMenu } from "./commands/chat.js";
+import { bindingKey, BindingStore } from "./state/bindings.js";
+import { CHANNEL_ID_PATTERN, IdentityStore } from "./state/identities.js";
+import { Ledger } from "./state/ledger.js";
+import { DeliveryWorker } from "./outbound/delivery.js";
+import { onRunSettled } from "./outbound/settled.js";
+import { createNotifier } from "./notify.js";
+import { SessionMetaDoc } from "./session-meta.js";
+import { StreamRegistry } from "./outbound/stream.js";
+import { hashId } from "./log.js";
+import { collectAttachments } from "./inbound/media.js";
+import { PromptStore } from "./interactions/prompts.js";
+import { createInteractionNotifier, onInteractionSettled } from "./interactions/chat.js";
+import { answerFromChat, createInteractionAnswerStage } from "./interactions/answer.js";
+import { receiptForInteraction } from "./interactions/receipts.js";
+/** The engine's own timer defaults (the real world). */
+function defaultTimers() {
+    return {
+        now: () => Date.now(),
+        // The jitter source is RANDOM (never the clock): a deterministic
+        // sequence would phase-lock concurrent deployments onto the same
+        // retry beat.
+        random: () => Math.random(),
+        setTimer: (fn, ms) => {
+            const handle = setTimeout(fn, ms);
+            return () => clearTimeout(handle);
+        },
+    };
+}
+/** The unhealthy-dwell threshold (ms) before health degrades (§8.12). */
+const DEGRADED_AFTER_MS = 300_000;
+/** Await an operation only until its shutdown budget expires. */
+async function bounded(operation, ms, onTimeout) {
+    let timer;
+    try {
+        await Promise.race([
+            operation,
+            new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    onTimeout();
+                    resolve();
+                }, ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** One static (never-supervised) status row. */
+function staticRow(state, detail, since) {
+    return {
+        state,
+        detail,
+        since,
+        counts: { admitted: 0, dropped: 0, delivered: 0, failed: 0 },
+    };
+}
+/**
+ * Build the engine over the host. The factory wires the real
+ * dependencies; tests inject the clock/log/timer seams through the same
+ * parameter.
+ */
+export function createEngine(host, deps = {}) {
+    const log = deps.log ?? createLog("engine");
+    const timers = deps.timers ?? defaultTimers();
+    const stateDir = host.stores.paths.state;
+    const gatewayDir = join(stateDir, "gateway");
+    // The delivery ledger (Task 5): engine-wide (every channel's worker
+    // pulls its own queue from it), built over the state dir at factory
+    // time — the stores load synchronously, no timers (the pi lifecycle
+    // rule holds). Restart recovery runs at `start` (the boot's one
+    // recovery point) — a `recoverAfterRestart()` BEFORE any worker runs
+    // re-arms `attempting` entries with the recovered flag.
+    const ledger = deps.deliveryLedger ?? new Ledger(join(gatewayDir, "ledger.json"), {
+        now: timers.now,
+        log,
+    });
+    // One delivery worker per supervised channel, keyed channel id
+    // (built at start — a worker owns its channel's timers).
+    const workers = new Map();
+    // The ONE binding store: every pipeline (threaded through
+    // PipelineDeps.bindings), the settled fan-out and the delivery
+    // workers share THIS instance — JsonFile's write serialization is
+    // PER INSTANCE, so a second store over the same file would interleave
+    // its writes with this one's and lose updates.
+    const bindings = new BindingStore(join(gatewayDir, "bindings.json"), {
+        now: timers.now,
+    });
+    const failedRecently = deps.failedRecently ??
+        (() => ledger.failedSince(timers.now() - 3_600_000));
+    let channels = [];
+    // One supervisor per supervised channel, keyed channel id.
+    const supervisors = new Map();
+    // Static rows for channels that never reach a supervisor, keyed id.
+    const staticRows = new Map();
+    // submissionId → the origin record (Task 3's pipeline writes; the
+    // outbound tasks read). One map per ENGINE (shared across channels).
+    const origins = new Map();
+    // ONE pipeline per supervised channel, built at start and reused by
+    // every supervision retry. Retrying an adapter must not accumulate
+    // duplicate SeenSets or open-album collectors for the process lifetime.
+    const pipelines = new Map();
+    let started = false;
+    let intakeStopped = false;
+    // Per-channel abort ownership lets stop() signal adapters even when an
+    // embedder does not abort the engine's start signal itself.
+    const channelAborters = new Map();
+    // The engine-wide access state (Task 4): ONE pairing queue, link-code
+    // table, token table and loop guard shared by every channel pipeline
+    // and the pair/link commands. Built over the engine's state dir at
+    // factory time (cheap: the stores load synchronously; no timers, no
+    // I/O beyond the state reads — the pi lifecycle rule holds).
+    const access = {
+        identities: new IdentityStore(host, join(gatewayDir, "identities.json"), { log }),
+        pairing: new PairingStore(join(gatewayDir, "pairing.json")),
+        linkCodes: new LinkCodes(),
+        tokens: new ButtonTokens(),
+        loopGuard: new LoopGuard(),
+    };
+    // The engine-owned half of every adapter context (Task 3's pipeline
+    // drives `receive`; the supervisor's makeContext seam stays stable).
+    // `supervisorOf` is resolved lazily — the context is built only during
+    // a start ATTEMPT, after the supervisor exists (a direct reference
+    // would hit the TDZ at construction).
+    const makeContext = (_signal, report, supervisorOf, 
+    /** The channel id — per-channel log attribution (Task 1's
+     *  `channel:${id}` scoping; a bare "channel" scope loses which
+     *  adapter a line came from). */
+    id) => {
+        const channelLog = ctxLog(`channel:${id}`);
+        // The channel's ONE pipeline was built at engine start. A retry
+        // closes over the same receive/flush handles, preserving its seen
+        // set and any open album window instead of allocating replacements.
+        const receivePipeline = pipelines.get(id);
+        if (receivePipeline === undefined) {
+            throw new Error(`gateway: channel "${id}" context built without its pipeline`);
+        }
+        return {
+            signal: _signal,
+            // The §8.4 pipeline: the config block is read LIVE per event
+            // (every field but `enabled` is per-event); a `{failed}` or
+            // absent block drops (the channel's enablement was read once at
+            // start — a supervised channel whose config went bad drops
+            // events until its next restart).
+            receive: async (event) => {
+                try {
+                    if (intakeStopped) {
+                        supervisorOf().countDropped();
+                        return { outcome: "dropped" };
+                    }
+                    const config = await readConfig(host);
+                    const block = config.channels[id];
+                    if (block === undefined || "failed" in block) {
+                        supervisorOf().countDropped();
+                        return { outcome: "dropped" };
+                    }
+                    const outcome = await receivePipeline(id, event, block);
+                    if (outcome.outcome === "admitted") {
+                        supervisorOf().countAdmitted();
+                    }
+                    else if (outcome.outcome === "dropped") {
+                        supervisorOf().countDropped();
+                    }
+                    return outcome;
+                }
+                catch (error) {
+                    // An engine failure (the §8.4 contract): the adapter does
+                    // not ack, the platform redelivers, and the supervisor's
+                    // counts stay honest (no admission claimed).
+                    channelLog.error("receive failed", error);
+                    throw error;
+                }
+            },
+            // Button taps route through the pipeline's token handler (Task
+            // 4: pair decisions; Task 9 adds interactions). A tap on an
+            // unknown channel block drops like an event would.
+            action: async (event) => {
+                try {
+                    if (intakeStopped)
+                        return;
+                    const config = await readConfig(host);
+                    const block = config.channels[id];
+                    if (block === undefined || "failed" in block)
+                        return;
+                    await receivePipeline.action(id, event, block);
+                }
+                catch (error) {
+                    // A tap failure never rejects the adapter's ack: the token is
+                    // consumed, the decision lost — logged loud, never retried
+                    // (a replayed tap is a no-op by the token's single use).
+                    channelLog.error("action failed", error);
+                }
+            },
+            status: report,
+            fail: () => {
+                // The supervisor wraps this member (its own fail routes into
+                // supervision); reaching the base means the wrapper was
+                // bypassed — log it, never crash.
+                log.warn("channel fail reached the engine base context");
+            },
+            log: channelLog,
+        };
+    };
+    // The origin-chat stream registry is engine-wide: pipelines open on
+    // admission, settled runs finalize with rendered chunks, and every
+    // channel lookup resolves against the same supervised contribution set.
+    const streams = new StreamRegistry({
+        host,
+        channelOf: (id) => channels.find((entry) => entry.channel.id === id)?.channel,
+        configOf: async (id) => {
+            const config = await readConfig(host);
+            const block = config.channels[id];
+            return block === undefined || "failed" in block ? undefined : block;
+        },
+        log,
+        now: timers.now,
+        setTimer: timers.setTimer,
+    });
+    /** The settled-run fan-out deps (the factory's `runSettled` closes over
+     *  these — the same stores the pipelines and commands share, plus the
+     *  delivery ledger and the stream registry). */
+    const settledDeps = (api, context) => ({
+        host,
+        bindings,
+        identities: access.identities,
+        ledger,
+        channelOf: (id) => channels.find((entry) => entry.channel.id === id)?.channel,
+        configOf: async (id) => {
+            const config = await readConfig(host);
+            const block = config.channels[id];
+            return block === undefined || "failed" in block ? undefined : block;
+        },
+        origins,
+        streams,
+        log,
+        // The event bus's narrowed snapshot API works in harness-only
+        // embedders; host.conversations.meta would wait for a server
+        // bridge that those embedders never create.
+        readMeta: async (conversationId) => await api.document(SessionMetaDoc, conversationId, context),
+    });
+    const notifyDeps = () => ({
+        host,
+        bindings,
+        identities: access.identities,
+        ledger,
+        readConfig: () => readConfig(host),
+        log,
+    });
+    const prompts = new PromptStore(join(gatewayDir, "prompts.json"));
+    const interactionDeps = () => ({
+        host,
+        bindings,
+        identities: access.identities,
+        prompts,
+        ledger,
+        tokens: access.tokens,
+        channelOf,
+        log,
+    });
+    const kickWorkers = () => {
+        for (const worker of workers.values())
+            worker.kick();
+    };
+    const channelOf = (id) => channels.find((entry) => entry.channel.id === id)?.channel;
+    const ctxLog = (scope) => ({
+        info: (msg) => log.info(`[${scope}] ${msg}`),
+        warn: (msg) => log.warn(`[${scope}] ${msg}`),
+        error: (msg, error) => log.error(`[${scope}] ${msg}`, error),
+        debug: (msg) => log.debug(`[${scope}] ${msg}`),
+        once: (key, level, msg) => log.once(key, level, `[${scope}] ${msg}`),
+    });
+    const status = () => {
+        const channelsOut = {};
+        for (const { channel } of channels) {
+            const supervised = supervisors.get(channel.id);
+            channelsOut[channel.id] = supervised
+                ? supervised.status()
+                : (staticRows.get(channel.id) ??
+                    staticRow("stopped", "never started", timers.now()));
+        }
+        return { channels: channelsOut };
+    };
+    return {
+        stateDir: gatewayDir,
+        channelIds: () => channels.map((entry) => entry.channel.id),
+        status,
+        pairingStatus: () => access.pairing.pending().map((row) => ({
+            channel: row.channel,
+            sender: hashId(row.senderId),
+            createdAt: row.createdAt,
+        })),
+        /** The engine-wide access state (the commands and pipelines share). */
+        accessState: () => access,
+        /** The `/pair` decision deps over the shared state (the factory's
+         *  command closes over these). */
+        pairDeps: (hostArg) => ({
+            host: hostArg,
+            identities: access.identities,
+            pairing: access.pairing,
+            channelOf: (id) => channels.find((entry) => entry.channel.id === id)?.channel,
+            log,
+            now: timers.now,
+        }),
+        toolDeps: () => ({
+            host,
+            bindings,
+            identities: access.identities,
+            ledger,
+            channelOf,
+            readConfig: () => readConfig(host),
+            log,
+            kick: kickWorkers,
+            ...(deps.toolReceiptWaitMs === undefined
+                ? {}
+                : { receiptWaitMs: deps.toolReceiptWaitMs }),
+        }),
+        sectionDeps: () => ({
+            host,
+            bindings,
+            channelOf,
+            readConfig: () => readConfig(host),
+        }),
+        notifier: () => {
+            const home = createNotifier(notifyDeps());
+            const interactions = createInteractionNotifier(interactionDeps());
+            return {
+                name: "gateway",
+                notify: async (event, ctx) => {
+                    await interactions.notify(event, ctx);
+                    await home.notify(event, ctx);
+                    kickWorkers();
+                },
+            };
+        },
+        interactionSettled: async (event, context) => {
+            await onInteractionSettled(event, interactionDeps(), context);
+            kickWorkers();
+        },
+        settle: async (event, api, context) => {
+            // The fan-out runs over the engine's deps, then every LIVE
+            // worker kicks (an entry for an unsupervised channel parks in
+            // the ledger — the channel's next start drains it). The prune
+            // rides settles too: a long-lived engine prunes without owning
+            // a recurring timer.
+            await onRunSettled(event, settledDeps(api, context));
+            await ledger.prune(timers.now()).catch((error) => {
+                log.error("ledger prune failed", error);
+            });
+            kickWorkers();
+        },
+        start: async (ctx) => {
+            // ONE start per engine instance (the handle's lazy `started`
+            // already guards re-reads; this guards a direct second call).
+            if (started)
+                return;
+            started = true;
+            channels = ctx.channels;
+            await mkdir(gatewayDir, { recursive: true });
+            // Ledger restart recovery runs BEFORE any worker (§8.6): every
+            // `attempting` entry re-arms `pending` with the recovered flag,
+            // and the workers resend them with the marker line. The prune of
+            // delivered entries past 7 days rides the same point (plus every
+            // settle — no recurring timer: the supervisor tests count the
+            // engine's scheduled timers, and an idle engine owns ZERO).
+            await ledger.recoverAfterRestart();
+            await ledger.prune(timers.now()).catch((error) => {
+                log.error("ledger prune failed", error);
+            });
+            // Enablement is restart-required (spec §8.1): read ONCE at start.
+            const config = await readConfig(host);
+            log.info(`started: ${channels.length} channel(s) [${channels
+                .map((entry) => `${entry.extension}/${entry.channel.id}`)
+                .join(", ")}]`);
+            for (const entry of channels) {
+                const id = entry.channel.id;
+                // Adapters are the registration boundary: reject an id core
+                // could never place inside chat:<channel>, before any event
+                // reaches the identity store. The failed row makes the skip
+                // visible on the status route as well as in the log.
+                if (!CHANNEL_ID_PATTERN.test(id)) {
+                    const detail = `channel "${id}" has an invalid id (expected ${CHANNEL_ID_PATTERN.source})`;
+                    staticRows.set(id, staticRow("failed", detail, timers.now()));
+                    log.warn(detail);
+                    continue;
+                }
+                const block = config.channels[id];
+                if (block === undefined) {
+                    // Absent from `channels` = disabled (spec §8.1).
+                    staticRows.set(id, staticRow("stopped", "channel not configured", timers.now()));
+                    log.info(`channel "${id}" not in settings — skipped`);
+                    continue;
+                }
+                if ("failed" in block) {
+                    // A malformed block disables the channel with the reason; the
+                    // row is `failed` and §8.12's health reads its dwell like any
+                    // other `failed` state (degraded after 300000 ms).
+                    staticRows.set(id, staticRow("failed", block.failed, timers.now()));
+                    log.warn(`channel "${id}" config failed: ${block.failed}`);
+                    continue;
+                }
+                if (!block.enabled) {
+                    staticRows.set(id, staticRow("stopped", "disabled", timers.now()));
+                    log.info(`channel "${id}" disabled via settings`);
+                    continue;
+                }
+                const channelLog = ctxLog(`channel:${id}`);
+                // One lifetime signal per channel: the long-lived pipeline's
+                // attachment fetches abort with the channel, not one retry.
+                const abort = new AbortController();
+                const receivePipeline = (deps.pipelineFactory ?? createPipeline)({
+                    host,
+                    channel: entry.channel,
+                    stateDir: gatewayDir,
+                    log: channelLog,
+                    origins,
+                    access,
+                    // The ONE engine-wide binding store — the fan-out and the
+                    // delivery workers share this exact instance.
+                    bindings,
+                    streams,
+                    channelOf,
+                    interactionAnswer: async (answer) => await answerFromChat(interactionDeps(), answer),
+                    stages: {
+                        interactionAnswer: createInteractionAnswerStage({
+                            ...interactionDeps(),
+                            configOf: async (channel) => {
+                                const live = await readConfig(host);
+                                const block = live.channels[channel];
+                                return block === undefined || "failed" in block ? undefined : block;
+                            },
+                            reply: async (event, text) => {
+                                await entry.channel.send({ chat: event.chat, text });
+                            },
+                        }),
+                        attachments: async (event) => {
+                            const binding = bindings.get(bindingKey(id, event.chat));
+                            if (binding === undefined)
+                                return { parts: [], notes: [] };
+                            const liveConfig = await readConfig(host);
+                            return await collectAttachments({ host, log: channelLog }, binding.conversationId, event.attachments ?? [], liveConfig.media.maxBytes, abort.signal);
+                        },
+                    },
+                });
+                pipelines.set(id, receivePipeline);
+                const supervisor = new Supervisor(entry, {
+                    makeContext: (signal, report) => makeContext(signal, report, () => {
+                        // The lazy lookup: the context is built only inside a start
+                        // attempt, after `supervisors.set` ran.
+                        const current = supervisors.get(id);
+                        if (current === undefined) {
+                            throw new Error(`gateway: channel "${id}" context built without a supervisor`);
+                        }
+                        return current;
+                    }, id),
+                    now: timers.now,
+                    random: timers.random,
+                    setTimer: timers.setTimer,
+                    log: createLog(`channel:${id}`),
+                });
+                supervisors.set(id, supervisor);
+                // The channel's delivery worker (Task 5): one in-flight send,
+                // the pinned retry ladder, the ledger's queue. Built BEFORE the
+                // supervisor starts (its first delivery may kick immediately —
+                // recovery entries ride the same loop).
+                const worker = new DeliveryWorker(entry.channel, ledger, {
+                    bindings,
+                    timeoutMs: 60_000,
+                    delays: [1_000, 5_000, 30_000],
+                    setTimer: timers.setTimer,
+                    now: timers.now,
+                    log: createLog(`channel:${id}`),
+                    counts: {
+                        delivered: () => supervisor.countDelivered(),
+                        failed: () => supervisor.countFailed(),
+                    },
+                    resolveFiles: (entry) => ledger.resolveFiles(host, entry),
+                    onInteractionReceipt: async (entry, receipt) => {
+                        await receiptForInteraction(prompts, entry, receipt);
+                    },
+                });
+                workers.set(id, worker);
+                // The first attempt settles before start resolves (running
+                // or backoff — a failing adapter never wedges boot). The engine
+                // owns a per-channel signal so stop() aborts adapters directly;
+                // the host's start signal is bridged for the normal core order.
+                channelAborters.set(id, abort);
+                if (ctx.signal.aborted)
+                    abort.abort();
+                else
+                    ctx.signal.addEventListener("abort", () => abort.abort(), { once: true });
+                await supervisor.start(abort.signal);
+                // Native menus publish AFTER the adapter start attempt so a
+                // hanging setCommands cannot block supervision. Publication is
+                // bounded and best-effort; there is no retry on later reconnects.
+                if (entry.channel.capabilities.commandMenu === true &&
+                    entry.channel.setCommands !== undefined) {
+                    let timeout;
+                    try {
+                        await Promise.race([
+                            entry.channel.setCommands(await chatCommandMenu(host)),
+                            new Promise((_resolve, reject) => {
+                                timeout = setTimeout(() => reject(new Error("command-menu setup timed out")), 5_000);
+                            }),
+                        ]);
+                    }
+                    catch (error) {
+                        log.error(`channel "${id}" command-menu setup failed`, error);
+                    }
+                    finally {
+                        if (timeout !== undefined)
+                            clearTimeout(timeout);
+                    }
+                }
+                // The recovery kick runs only once the ADAPTER is live (or in
+                // backoff): a send before the adapter connected would burn the
+                // entry's first attempt on a transport that cannot take it.
+                worker.kick();
+            }
+        },
+        stopIntake: async () => {
+            // Intake closes before the shutdown drain (the ordering) — but
+            // FIRST every open album window flushes: a shutdown inside the
+            // 1500 ms merge window must submit the already-admitted album
+            // events (they committed `seen`; without the flush, the
+            // platform's redelivery would dedupe to a no-op and the album
+            // would be lost). One failed album's flush is logged and never
+            // strands the others (flushAlbums drains every group).
+            // Keep the handles through the shutdown drain: a supervision retry
+            // may still call makeContext before stop() aborts the channel. Album
+            // flushing is idempotent, so clearing the map buys nothing and would
+            // turn that retry into an unhandled rejection.
+            const pending = [...pipelines.values()];
+            await Promise.all(pending.map((pipeline) => pipeline.flushAlbums()));
+            // Close only after the album flush: those events already committed
+            // their dedupe ids and must be admitted before new intake is refused.
+            intakeStopped = true;
+        },
+        stop: async () => {
+            // A stop-before-start resolves (the lazy-start shutdown edge).
+            // Delivery drains share one 10 s budget across channels. A hung
+            // adapter send cannot extend it; its entry remains pending or
+            // attempting in the durable ledger for restart recovery.
+            const draining = [...workers.values()];
+            workers.clear();
+            const deadline = timers.now() + 10_000;
+            await Promise.all(draining.map(async (worker) => {
+                try {
+                    await bounded(worker.drain(deadline), 10_000, () => log.warn("delivery drain exceeded 10000 ms — abandoning the wait"));
+                }
+                catch (error) {
+                    log.error("delivery drain failed", error);
+                }
+                finally {
+                    // stop() cancels retry timers synchronously, then joins the
+                    // in-flight send. That join may never settle; the 10 s
+                    // drain bound above is the only wait shutdown owns.
+                    void worker.stop().catch((error) => {
+                        log.error("delivery worker stop failed", error);
+                    });
+                }
+            }));
+            for (const abort of channelAborters.values())
+                abort.abort();
+            channelAborters.clear();
+            const pending = [...supervisors.values()];
+            supervisors.clear();
+            await Promise.all(pending.map(async (supervisor) => {
+                try {
+                    await bounded(supervisor.stop(), 5_000, () => {
+                        log.warn(`channel "${supervisor.id}" stop exceeded 5000 ms — abandoning the wait`);
+                    });
+                }
+                catch (error) {
+                    log.error(`channel "${supervisor.id}" stop failed`, error);
+                }
+            }));
+            // Live previews are not durable delivery. Release their watches
+            // after adapter stop; settled previews finalized during the drain
+            // have already released theirs.
+            streams.abandonAll();
+            if (started)
+                log.info("stopped");
+        },
+        health: () => {
+            // §8.12: degraded when any enabled, configured channel has been
+            // in backoff/failed for over 300000 ms, or the ledger holds
+            // failed entries from the last hour (the window is Task 5's
+            // `failedRecently` dependency — the engine never reads a clock
+            // against the ledger itself). Supervisors own `backoff` dwell;
+            // static rows own `failed` dwell (config-error channels).
+            const now = timers.now();
+            for (const supervisor of supervisors.values()) {
+                if (supervisor.unhealthyMs(now) > DEGRADED_AFTER_MS) {
+                    return "degraded";
+                }
+            }
+            for (const row of staticRows.values()) {
+                if (row.state === "failed" &&
+                    now - row.since > DEGRADED_AFTER_MS) {
+                    return "degraded";
+                }
+            }
+            if (failedRecently() > 0) {
+                return "degraded";
+            }
+            return "ok";
+        },
+    };
+}

package/dist/inbound/albums.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Album merging (spec §8.4 step 6): events sharing a `groupId` that
+ * arrive within 1500 ms merge into ONE submission (a platform media
+ * group delivered as several events). There is no time-based burst
+ * merging otherwise — every non-album message submits on arrival.
+ *
+ * The window runs from the FIRST event of its group: the group is
+ * closed once a later sibling arrives past `firstAt + 1500`, and a
+ * `groupId` reused later opens a NEW group. Group state is per
+ * binding key (the chat) — two chats never share an album. Attachment
+ * arrays are preserved alongside envelope texts so every sibling's
+ * media reaches the one submission.
+ */
+import type { InboundAttachment, InboundEvent } from "@sigrun/sigrun/extension";
+/** The album merge window (ms) — the plan's pinned 1.5 s. */
+export declare const ALBUM_WINDOW_MS = 1500;
+/** One complete album, or a plain event's single-item batch. */
+export interface AlbumBatch {
+    readonly texts: readonly string[];
+    readonly attachments: readonly InboundAttachment[];
+}
+/**
+ * The in-flight album collector, one instance per engine. `add` returns
+ * `undefined` while the album stays OPEN (the caller holds the event
+ * back — no submission yet) and the collected batch when the group is
+ * COMPLETE. A follow-up event with no `groupId` returns its own batch.
+ */
+export declare class AlbumCollector {
+    private readonly now;
+    private readonly windowMs;
+    private readonly groups;
+    constructor(now: () => number, windowMs?: number);
+    /** Offer one event's envelope text; undefined means still collecting. */
+    add(key: string, event: InboundEvent, text: string): AlbumBatch | undefined;
+    /** Close and remove one open group, returning its complete batch. */
+    close(key: string, groupId: string): AlbumBatch;
+    /** Is a group OPEN (collecting) for `key`/`groupId`? */
+    isOpen(key: string, groupId: string): boolean;
+}