@sigrun/ext-gateway 0.0.0-stage → 0.1.2

package/dist/log.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Engine logging + id hashing (spec §8.0/§8.12): one scoped console
+ * logger with a per-process `once` dedupe (per-key — a repeated warn
+ * fires a single line, never one per event), and `hashId` — the
+ * non-reversible form sender ids take in status output.
+ */
+/** The irreversible form a platform sender id takes in operator-facing
+ *  output: the sha256 digest's first 8 hex chars (the plan's pinned
+ *  format — enough to correlate without leaking the raw platform id). */
+export declare function hashId(id: string): string;
+/** One scoped logger: console methods plus a per-key `once`. */
+export interface EngineLog {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string, error?: unknown): void;
+    debug(msg: string): void;
+    /** Emit `msg` at `level` ONCE per process per `key` (per-key dedupe). */
+    once(key: string, level: "info" | "warn", msg: string): void;
+}
+/** Build the scoped console logger (the `gateway:` prefix names the engine). */
+export declare function createLog(scope: string): EngineLog;

package/dist/log.js

@@ -0,0 +1,42 @@
+/**
+ * Engine logging + id hashing (spec §8.0/§8.12): one scoped console
+ * logger with a per-process `once` dedupe (per-key — a repeated warn
+ * fires a single line, never one per event), and `hashId` — the
+ * non-reversible form sender ids take in status output.
+ */
+import { createHash } from "node:crypto";
+/** The irreversible form a platform sender id takes in operator-facing
+ *  output: the sha256 digest's first 8 hex chars (the plan's pinned
+ *  format — enough to correlate without leaking the raw platform id). */
+export function hashId(id) {
+    return createHash("sha256").update(id).digest("hex").slice(0, 8);
+}
+/** The emitted-once keys this process has already logged. */
+const onceLogged = new Set();
+/** Build the scoped console logger (the `gateway:` prefix names the engine). */
+export function createLog(scope) {
+    const prefix = `gateway: ${scope}`.trim();
+    return {
+        info: (msg) => console.info(`${prefix} ${msg}`),
+        warn: (msg) => console.warn(`${prefix} ${msg}`),
+        error: (msg, error) => {
+            if (error === undefined)
+                console.error(`${prefix} ${msg}`);
+            else
+                console.error(`${prefix} ${msg}`, error);
+        },
+        // debug rides the console's debug channel: visible when the
+        // environment enables it, silent otherwise.
+        debug: (msg) => console.debug(`${prefix} ${msg}`),
+        once: (key, level, msg) => {
+            const onceKey = `${prefix} ${key}`;
+            if (onceLogged.has(onceKey))
+                return;
+            onceLogged.add(onceKey);
+            if (level === "info")
+                console.info(`${prefix} ${msg}`);
+            else
+                console.warn(`${prefix} ${msg}`);
+        },
+    };
+}

package/dist/notify.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The home-chat notifier (spec §8.8): core chooses the recipients; the
+ * engine turns each event into durable ledger entries for that user's
+ * home DMs. Handlers only enqueue — channel workers own platform I/O.
+ */
+import type { NotifierContribution, SigrunHost } from "@sigrun/sigrun/extension";
+import type { BindingStore } from "./state/bindings.js";
+import type { IdentityStore } from "./state/identities.js";
+import type { Ledger } from "./state/ledger.js";
+import type { GatewayConfig } from "./config.js";
+import type { EngineLog } from "./log.js";
+export interface NotifyDeps {
+    readonly host: SigrunHost;
+    readonly bindings: BindingStore;
+    readonly identities: IdentityStore;
+    readonly ledger: Ledger;
+    readonly readConfig: () => Promise<GatewayConfig>;
+    readonly log: EngineLog;
+}
+/** Build the factory-result notifier over the engine's shared stores. */
+export declare function createNotifier(deps: NotifyDeps): NotifierContribution;

package/dist/notify.js

@@ -0,0 +1,64 @@
+/**
+ * The home-chat notifier (spec §8.8): core chooses the recipients; the
+ * engine turns each event into durable ledger entries for that user's
+ * home DMs. Handlers only enqueue — channel workers own platform I/O.
+ */
+/** Build the factory-result notifier over the engine's shared stores. */
+export function createNotifier(deps) {
+    return {
+        name: "home",
+        notify: async (event) => {
+            try {
+                await notify(event, deps);
+            }
+            catch (error) {
+                // A notice must never break core's other notifier deliveries;
+                // the event is best-effort, but its loss is always visible.
+                deps.log.error(`home notification failed (${event.type})`, error);
+            }
+        },
+    };
+}
+async function notify(event, deps) {
+    // Task 9 owns chat presentation for interaction records.
+    if (event.type === "interaction.pending")
+        return;
+    if (event.user === undefined)
+        return;
+    const config = await deps.readConfig();
+    if (!config.notify.home)
+        return;
+    if (event.type === "run.settled") {
+        if (event.conversationId === undefined)
+            return;
+        // The settled fan-out owns bound conversations; a second notice
+        // here would duplicate the answer the chat just received. Only
+        // LIVE bindings suppress: a dead binding is skipped by the
+        // fan-out, so counting it would drop the answer with no log.
+        const live = deps.bindings.keysOf(event.conversationId)
+            .filter((key) => deps.bindings.get(key)?.dead !== true);
+        if (live.length > 0)
+            return;
+        const meta = await deps.host.conversations.meta(event.conversationId);
+        // New-conversation jobs are unbound, but their delivery and
+        // job.failed paths own notices. The settled outcome (Task 4) is
+        // structured on the event: only an ANSWERED run may read as a
+        // ready reply; a failed/aborted run is a truthful non-success
+        // notice carrying the run's own reason.
+        if (meta.jobId !== undefined)
+            return;
+    }
+    const text = event.type === "run.settled"
+        ? event.outcome.status === "answered"
+            ? `Reply ready — ${event.body}${event.url === undefined ? "" : `\n${event.url}`}`
+            : `Run ended without a reply — ${event.body}${event.outcome.reason === "" ? "" : ` (${event.outcome.reason})`}${event.url === undefined ? "" : `\n${event.url}`}`
+        : `${event.title}\n${event.body}${event.url === undefined ? "" : `\n${event.url}`}`;
+    for (const home of deps.identities.homesOf(event.user)) {
+        await deps.ledger.enqueue({
+            channel: home.channel,
+            chat: home.chat,
+            kind: "notice",
+            message: { chat: home.chat, text },
+        });
+    }
+}

package/dist/outbound/delivery.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The per-channel delivery worker (spec §8.6): ONE in-flight send per
+ * channel, entries pulled from the ledger in enqueue order.
+ *
+ * Retry ladder (pinned): a `transient` failure retries at 1000, 5000
+ * and 30000 ms, then the entry is `failed`. A `permanent` failure
+ * fails at once. A `chat_gone` failure marks the binding dead
+ * (future sends to that chat skip; the chat's next inbound message
+ * clears it) and drops the entry. A send that exceeds the 60 s bound
+ * (spec's Review Focus 2 — an adapter call that never resolves)
+ * classifies TRANSIENT: the worker abandons the call, retries, and
+ * never wedges the channel's queue.
+ *
+ * Recovered entries (restart recovery flagged them) are resent with the
+ * leading "(resent after restart)" line — the platform may already
+ * hold the message, and the marker tells the human what happened.
+ *
+ * `drain(deadlineMs)` is the shutdown path: send until the ledger is
+ * empty or the deadline passes; retries are NOT waited out (a retry
+ * timer armed by drain settles after stop() — the entry stays pending
+ * and the next boot's recovery resends it).
+ */
+import type { ChannelContribution, OutboundMessage } from "@sigrun/sigrun/extension";
+import type { Ledger, LedgerEntry } from "../state/ledger.js";
+import type { BindingStore } from "../state/bindings.js";
+import { type EngineLog } from "../log.js";
+/** The worker's injectable dependencies. */
+export interface DeliveryDeps {
+    readonly bindings: BindingStore;
+    /** The send bound (a hung adapter call never wedges the queue). */
+    readonly timeoutMs: number;
+    /** The pinned retry ladder: delays[attempt] before retry N. */
+    readonly delays: readonly [number, number, number];
+    /** Schedule `fn` at `ms`; the return value cancels it. */
+    readonly setTimer: (fn: () => void, ms: number) => () => void;
+    readonly log: EngineLog;
+    /** Clock (the tests' virtual clock). Default: real. */
+    readonly now?: () => number;
+    /** Re-read file bytes at send time; ledger entries persist paths only. */
+    readonly resolveFiles?: (entry: LedgerEntry) => Promise<OutboundMessage["files"]>;
+    /** Terminal delivery outcomes for the channel's status counters. */
+    readonly counts?: {
+        delivered(): void;
+        failed(): void;
+        cancelled?(): void;
+    };
+    /** Persist a delivered interaction prompt's platform refs for edits/replies. */
+    readonly onInteractionReceipt?: (entry: LedgerEntry, receipt: {
+        readonly messageIds: readonly string[];
+    }) => void | Promise<void>;
+}
+/** The pinned resend marker for recovered entries. */
+export declare const RESENT_MARKER = "(resent after restart)";
+/**
+ * One channel's delivery worker. `kick()` starts the loop if idle (an
+ * enqueue calls it); `drain(deadlineMs)` runs sends until empty or the
+ * deadline; `stop()` cancels timers and joins the in-flight send. Not
+ * restartable after `stop()` (the engine stops once per boot).
+ */
+export declare class DeliveryWorker {
+    private readonly channel;
+    private readonly ledger;
+    private readonly deps;
+    private readonly now;
+    private busy;
+    private stopped;
+    /** The in-flight send's settle handle (stop joins it). */
+    private inFlight;
+    /** The cancel for the armed retry timer. */
+    private cancelRetry;
+    constructor(channel: ChannelContribution, ledger: Ledger, deps: DeliveryDeps);
+    /** Start the loop if idle (the enqueue-side poke). A no-op while a
+     *  drain owns the queue (the drain IS the loop until it resolves). */
+    kick(): void;
+    /**
+     * Send until the ledger's channel queue is empty or `deadlineMs`
+     * (absolute clock ms) passes. The drain TAKES OWNERSHIP of the
+     * queue: `busy` is set for its duration (a kick during a drain is a
+     * no-op), the armed retry timer is CANCELLED (the drain pulls the
+     * re-pended entry directly — no timer-driven second loop races
+     * it), and any in-flight loop is joined first. Retries are NOT
+     * waited out: a retry-armed entry parks the drain (the entry stays
+     * pending; the next boot's recovery resends it).
+     */
+    drain(deadlineMs: number): Promise<void>;
+    /** Cancel the retry timer and join the in-flight send. Idempotent. */
+    stop(): Promise<void>;
+    /**
+     * The steady-state loop: pull, send, repeat; a retry-armed state
+     * parks until the timer fires (kick re-arms after each timer hop).
+     */
+    private runLoop;
+    /**
+     * Send one entry: attempting → send → delivered (receipt) / the
+     * error-classified failure path. Returns false when the entry needs
+     * a retry wait (the loop parks until the retry timer re-kicks) —
+     * enqueue ORDER holds: no later entry overtakes a retrying one.
+     * Never throws.
+     */
+    private sendOne;
+    /**
+     * The platform call, abandoned at `timeoutMs`: a send that exceeds
+     * the bound classifies TRANSIENT (the worker retries, never wedges).
+     */
+    private boundedSend;
+    /** Apply an edit entry; its ledger row carries the target MessageRef. */
+    private boundedEdit;
+    /**
+     * The classified failure path: transient retries (the ladder),
+     * permanent fails at once, chat_gone marks the binding dead.
+     * Returns false when a retry wait was armed (the caller parks).
+     */
+    private onSendError;
+    /**
+     * A ledger mark with its own error isolation (never throws). Returns
+     * whether the transition APPLIED: a refusal means the entry left
+     * `pending` behind our back (a settlement cancelled it), so the caller
+     * must skip its failure/retry side effects rather than count a failure
+     * for a cancelled entry or arm a retry that re-pulls it.
+     */
+    private markLedger;
+    /**
+     * The classification read (adapter's `classifyError` when present,
+     * transient otherwise) with the timeout error forced transient.
+     */
+    private classify;
+    /** The send-shaped message for one entry (the recovered marker rule). */
+    private buildMessage;
+}
+/** The timeout error's name (matched by `classify`, never instanceof). */
+export declare const SEND_TIMEOUT_NAME = "GatewaySendTimeout";

package/dist/outbound/delivery.js

@@ -0,0 +1,404 @@
+/**
+ * The per-channel delivery worker (spec §8.6): ONE in-flight send per
+ * channel, entries pulled from the ledger in enqueue order.
+ *
+ * Retry ladder (pinned): a `transient` failure retries at 1000, 5000
+ * and 30000 ms, then the entry is `failed`. A `permanent` failure
+ * fails at once. A `chat_gone` failure marks the binding dead
+ * (future sends to that chat skip; the chat's next inbound message
+ * clears it) and drops the entry. A send that exceeds the 60 s bound
+ * (spec's Review Focus 2 — an adapter call that never resolves)
+ * classifies TRANSIENT: the worker abandons the call, retries, and
+ * never wedges the channel's queue.
+ *
+ * Recovered entries (restart recovery flagged them) are resent with the
+ * leading "(resent after restart)" line — the platform may already
+ * hold the message, and the marker tells the human what happened.
+ *
+ * `drain(deadlineMs)` is the shutdown path: send until the ledger is
+ * empty or the deadline passes; retries are NOT waited out (a retry
+ * timer armed by drain settles after stop() — the entry stays pending
+ * and the next boot's recovery resends it).
+ */
+import { hashId } from "../log.js";
+/** The pinned resend marker for recovered entries. */
+export const RESENT_MARKER = "(resent after restart)";
+/**
+ * One channel's delivery worker. `kick()` starts the loop if idle (an
+ * enqueue calls it); `drain(deadlineMs)` runs sends until empty or the
+ * deadline; `stop()` cancels timers and joins the in-flight send. Not
+ * restartable after `stop()` (the engine stops once per boot).
+ */
+export class DeliveryWorker {
+    channel;
+    ledger;
+    deps;
+    now;
+    busy = false;
+    stopped = false;
+    /** The in-flight send's settle handle (stop joins it). */
+    inFlight;
+    /** The cancel for the armed retry timer. */
+    cancelRetry;
+    constructor(channel, ledger, deps) {
+        this.channel = channel;
+        this.ledger = ledger;
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+    }
+    /** Start the loop if idle (the enqueue-side poke). A no-op while a
+     *  drain owns the queue (the drain IS the loop until it resolves). */
+    kick() {
+        if (this.stopped || this.busy)
+            return;
+        const loop = this.runLoop();
+        this.inFlight = loop.catch((error) => {
+            // A loop failure is engine-side (the ledger or the adapter
+            // wrapper): logged loud, never silent — the channel's queue
+            // stays honest (the next kick retries).
+            this.deps.log.error(`delivery: loop failed (channel "${this.channel.id}")`, error);
+        });
+        void loop;
+    }
+    /**
+     * Send until the ledger's channel queue is empty or `deadlineMs`
+     * (absolute clock ms) passes. The drain TAKES OWNERSHIP of the
+     * queue: `busy` is set for its duration (a kick during a drain is a
+     * no-op), the armed retry timer is CANCELLED (the drain pulls the
+     * re-pended entry directly — no timer-driven second loop races
+     * it), and any in-flight loop is joined first. Retries are NOT
+     * waited out: a retry-armed entry parks the drain (the entry stays
+     * pending; the next boot's recovery resends it).
+     */
+    async drain(deadlineMs) {
+        if (this.stopped)
+            return;
+        // Cancel the pending retry: the drain owns the queue now.
+        this.cancelRetry?.();
+        this.cancelRetry = undefined;
+        // Join any in-flight loop before taking the busy flag.
+        await this.inFlight;
+        if (this.stopped)
+            return;
+        if (this.busy) {
+            // A concurrent drain (the engine's stop is idempotent, but a
+            // caller may race): join it rather than run a second loop.
+            await this.inFlight;
+            return;
+        }
+        this.busy = true;
+        try {
+            for (;;) {
+                if (this.stopped)
+                    return;
+                if (this.now() >= deadlineMs)
+                    return;
+                const entry = this.ledger.nextPending(this.channel.id);
+                if (entry === undefined)
+                    return;
+                const progressed = await this.sendOne(entry);
+                if (!progressed)
+                    return;
+            }
+        }
+        finally {
+            this.busy = false;
+        }
+    }
+    /** Cancel the retry timer and join the in-flight send. Idempotent. */
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.cancelRetry?.();
+        this.cancelRetry = undefined;
+        const flight = this.inFlight;
+        if (flight !== undefined)
+            await flight.catch(() => { });
+    }
+    /**
+     * The steady-state loop: pull, send, repeat; a retry-armed state
+     * parks until the timer fires (kick re-arms after each timer hop).
+     */
+    async runLoop() {
+        if (this.busy)
+            return;
+        this.busy = true;
+        try {
+            for (;;) {
+                if (this.stopped)
+                    return;
+                const entry = this.ledger.nextPending(this.channel.id);
+                if (entry === undefined)
+                    return;
+                const progressed = await this.sendOne(entry);
+                if (!progressed) {
+                    // A retry is armed (or the entry is terminal-failed): the loop
+                    // parks — the retry timer's kick() restarts it. Enqueue order
+                    // holds (no later entry overtakes a retrying one).
+                    return;
+                }
+            }
+        }
+        finally {
+            this.busy = false;
+        }
+    }
+    /**
+     * Send one entry: attempting → send → delivered (receipt) / the
+     * error-classified failure path. Returns false when the entry needs
+     * a retry wait (the loop parks until the retry timer re-kicks) —
+     * enqueue ORDER holds: no later entry overtakes a retrying one.
+     * Never throws.
+     */
+    async sendOne(entry) {
+        try {
+            // Resolution belongs inside the classified boundary: a deleted
+            // or unreadable file must fail this entry, never wedge the queue.
+            const message = await this.buildMessage(entry);
+            // The attempting mark rides the same isolation as the rest: a
+            // failing ledger write is LOGGED and the send does not run (an
+            // unmarked entry must not be sent — the crash window would
+            // duplicate it on recovery).
+            // A refused claim means the entry is no longer pending (a
+            // settlement cancelled it between the loop's read and here).
+            // Sending it anyway would deliver a live prompt for a decided
+            // interaction, so stop: the cancellation is the barrier.
+            if (!(await this.ledger.mark(entry.id, "attempting"))) {
+                this.deps.counts?.cancelled?.();
+                return true;
+            }
+            const receipt = entry.kind === "edit"
+                ? await this.boundedEdit(entry, message)
+                : await this.boundedSend(message);
+            await this.ledger.mark(entry.id, "delivered", receipt.messageIds);
+            if (entry.kind === "interaction") {
+                await this.deps.onInteractionReceipt?.(entry, receipt);
+            }
+            this.deps.counts?.delivered();
+            return true;
+        }
+        catch (error) {
+            return await this.onSendError(entry, error);
+        }
+    }
+    /**
+     * The platform call, abandoned at `timeoutMs`: a send that exceeds
+     * the bound classifies TRANSIENT (the worker retries, never wedges).
+     */
+    async boundedSend(message) {
+        return await new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = this.deps.setTimer(() => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(timeoutError(this.deps.timeoutMs));
+            }, this.deps.timeoutMs);
+            this.channel
+                .send(message)
+                .then((receipt) => {
+                if (settled)
+                    return;
+                settled = true;
+                timer();
+                resolve(receipt);
+            }, (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                timer();
+                reject(error);
+            })
+                .catch((error) => {
+                // The .then handlers never throw; the catch is the
+                // belt-and-braces shape for a misbehaving adapter.
+                if (settled)
+                    return;
+                settled = true;
+                timer();
+                reject(error);
+            });
+        });
+    }
+    /** Apply an edit entry; its ledger row carries the target MessageRef. */
+    async boundedEdit(entry, message) {
+        if (entry.ref === undefined || this.channel.edit === undefined) {
+            const error = new Error("gateway: edit delivery requires a ref and adapter edit()");
+            error.name = EDIT_PRECONDITION_ERROR;
+            throw error;
+        }
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = this.deps.setTimer(() => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(timeoutError(this.deps.timeoutMs));
+            }, this.deps.timeoutMs);
+            this.channel.edit(entry.ref, message).then(() => {
+                if (settled)
+                    return;
+                settled = true;
+                timer();
+                resolve();
+            }, (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                timer();
+                reject(error);
+            });
+        });
+        return { messageIds: [entry.ref.messageId] };
+    }
+    /**
+     * The classified failure path: transient retries (the ladder),
+     * permanent fails at once, chat_gone marks the binding dead.
+     * Returns false when a retry wait was armed (the caller parks).
+     */
+    async onSendError(entry, error) {
+        const kind = this.classify(error);
+        const detail = error instanceof Error ? error.message : String(error);
+        // A ledger-mark failure arrives here too (sendOne's try wraps the
+        // attempting mark): it is NOT a send failure — a transient retry of
+        // an unmarked entry would double-send after recovery. Mark errors
+        // log loud and park the entry as-is (the next boot's recovery owns
+        // the resend).
+        if (kind === "chat_gone") {
+            if (entry.bindingKey !== undefined) {
+                try {
+                    await this.deps.bindings.markDead(entry.bindingKey);
+                }
+                catch (markError) {
+                    this.deps.log.error(`delivery: markDead failed for binding "${hashId(entry.bindingKey)}"`, markError);
+                    this.deps.log.debug(`delivery: markDead failed for binding "${entry.bindingKey}"`);
+                }
+            }
+            this.deps.log.warn(`delivery: chat gone for "${entry.channel}:${hashId(entry.chat.chatId)}" — binding marked dead`);
+            this.deps.log.debug(`delivery: chat gone for "${entry.channel}:${entry.chat.chatId}" — binding marked dead`);
+            if (await this.markLedger(entry.id, "failed"))
+                this.deps.counts?.failed();
+            return true;
+        }
+        if (kind === "permanent") {
+            const fileDetail = error instanceof Error && error.name === FILE_RESOLUTION_ERROR
+                ? ` (${error.message})`
+                : "";
+            this.deps.log.error(`delivery: permanent failure ("${entry.kind}" to "${hashId(entry.chat.chatId)}")${fileDetail}`, error);
+            this.deps.log.debug(`delivery: permanent failure ("${entry.kind}" to "${entry.chat.chatId}")${fileDetail}`);
+            if (await this.markLedger(entry.id, "failed"))
+                this.deps.counts?.failed();
+            return true;
+        }
+        // Transient: the retry ladder. attempts was already incremented by
+        // the attempting mark; a send is allowed delays.length + 1 tries
+        // total (the initial attempt plus one per delay).
+        const retriesUsed = entry.attempts;
+        if (retriesUsed >= this.deps.delays.length) {
+            this.deps.log.error(`delivery: retries exhausted ("${entry.kind}" to "${hashId(entry.chat.chatId)}"): ${detail}`);
+            this.deps.log.debug(`delivery: retries exhausted ("${entry.kind}" to "${entry.chat.chatId}"): ${detail}`);
+            if (await this.markLedger(entry.id, "failed"))
+                this.deps.counts?.failed();
+            return true;
+        }
+        const delay = this.deps.delays[retriesUsed] ?? 0;
+        this.deps.log.warn(`delivery: transient failure (attempt ${retriesUsed + 1}, retry in ${delay} ms): ${detail}`);
+        // The entry returns to pending (the retry re-pulls it); the timer
+        // re-kicks the loop. A stop cancels the timer — the entry stays
+        // pending for the next boot's recovery.
+        // A refused re-arm means the entry was cancelled while we were
+        // classifying the failure: do not arm a retry that would re-pull it.
+        if (!(await this.markLedger(entry.id, "pending")))
+            return true;
+        if (this.stopped)
+            return false;
+        this.cancelRetry?.();
+        this.cancelRetry = this.deps.setTimer(() => {
+            this.cancelRetry = undefined;
+            this.kick();
+        }, delay);
+        return false;
+    }
+    /**
+     * A ledger mark with its own error isolation (never throws). Returns
+     * whether the transition APPLIED: a refusal means the entry left
+     * `pending` behind our back (a settlement cancelled it), so the caller
+     * must skip its failure/retry side effects rather than count a failure
+     * for a cancelled entry or arm a retry that re-pulls it.
+     */
+    async markLedger(id, state) {
+        try {
+            return await this.ledger.mark(id, state);
+        }
+        catch (markError) {
+            this.deps.log.error("delivery: ledger mark failed", markError);
+            return false;
+        }
+    }
+    /**
+     * The classification read (adapter's `classifyError` when present,
+     * transient otherwise) with the timeout error forced transient.
+     */
+    classify(error) {
+        if (error instanceof Error && (error.name === FILE_RESOLUTION_ERROR || error.name === EDIT_PRECONDITION_ERROR)) {
+            return "permanent";
+        }
+        if (error instanceof Error &&
+            error.name === "GatewaySendTimeout") {
+            // Review Focus 2: a send over the bound is TRANSIENT — never
+            // permanent, never chat_gone.
+            return "transient";
+        }
+        if (this.channel.classifyError !== undefined) {
+            return this.channel.classifyError(error);
+        }
+        return "transient";
+    }
+    /** The send-shaped message for one entry (the recovered marker rule). */
+    async buildMessage(entry) {
+        // An edit replaces its target; adding a resend prefix would corrupt
+        // the already-final outcome text (the marker belongs on fresh sends).
+        const text = entry.recovered === true && entry.kind !== "edit"
+            ? `${RESENT_MARKER}\n${entry.message.text}`
+            : entry.message.text;
+        let files;
+        if (entry.message.files !== undefined && this.deps.resolveFiles !== undefined) {
+            try {
+                files = await this.deps.resolveFiles(entry);
+            }
+            catch (error) {
+                const paths = entry.message.files.map((file) => file.path).join(", ");
+                this.deps.log.warn(`delivery: file resolution failed for ${paths}`);
+                const failure = new Error(`file resolution failed for ${paths}`, {
+                    cause: error,
+                });
+                failure.name = FILE_RESOLUTION_ERROR;
+                throw failure;
+            }
+        }
+        return {
+            chat: entry.message.chat,
+            text,
+            ...(entry.message.replyTo === undefined
+                ? {}
+                : { replyTo: entry.message.replyTo }),
+            ...(entry.message.buttons === undefined
+                ? {}
+                : { buttons: entry.message.buttons }),
+            ...(files === undefined ? {} : { files }),
+        };
+    }
+}
+/** A workspace file no longer exists/readable; retrying cannot repair it. */
+const FILE_RESOLUTION_ERROR = "GatewayFileResolutionError";
+/** A structurally undeliverable edit can never succeed on retry. */
+const EDIT_PRECONDITION_ERROR = "GatewayEditPreconditionError";
+/** The timeout error's name (matched by `classify`, never instanceof). */
+export const SEND_TIMEOUT_NAME = "GatewaySendTimeout";
+/** Build the timeout error. */
+function timeoutError(ms) {
+    const error = new Error(`gateway: send exceeded ${ms} ms`);
+    error.name = SEND_TIMEOUT_NAME;
+    return error;
+}