@sguild/dispatcher 2.0.0

package/dist/dlq.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Dispatcher dead-letter queue (DLQ) read and resolve API.
+ *
+ * Phase 2 Slice 5. Operator-facing surface for inspecting and resolving
+ * dispatcher_dead_letter rows produced by ConsumerLoop's dead-letter
+ * path (handler exhausted retries; envelope snapshot persisted with the
+ * error trace for replay or investigation).
+ *
+ * Multi-producer aware. Per ADR-0009, each producer-domain owns its own
+ * dispatcher_dead_letter table in its own DB. The fanout ConsumerLoop
+ * writes DLQ rows into the PRODUCER's DB (because that's where the
+ * cursor and seq advance happen), so reading the DLQ for a given
+ * consumer means scanning every producer this Platform instance has a
+ * DSN for. We resolve the set of producers from the registered event
+ * types' producer field and connect via producer-db.getProducerDb.
+ *
+ * DLQ list reads can be all-consumer or narrowed to one consumer. Detail,
+ * resolve, and replay stay row-id + producer keyed.
+ *
+ * Two read shapes:
+ *
+ *   - `listDeadLetters(consumer, { includeResolved?, producer? })` returns
+ *     the active DLQ aggregated across every producer this Platform can
+ *     reach. Pass a consumer to narrow to one consumer, or null/empty to
+ *     return all consumers. Pass `producer` to narrow to one producer.
+ *
+ *   - `getDeadLetter(deadLetterId, { producer? })` returns one row by its
+ *     `dlq_<UUID>` id. With `producer` set, queries only that producer's
+ *     DB; without, scans every producer until the id is found.
+ *
+ * One write shape:
+ *
+ *   - `resolveDeadLetter(deadLetterId, { producer, resolvedBy,
+ *     resolutionNote? })` marks the row resolved with `resolved_at =
+ *     NOW()`, the operator's identifier, and an optional note. The
+ *     `producer` is required so we write to the correct DB. The
+ *     dead-letter row itself stays in place for audit; resolution does
+ *     not delete or replay.
+ */
+import type { Prisma } from "@prisma/client";
+export type DeadLetter = {
+    /** Which producer DB this DLQ row lives in. */
+    producer: string;
+    dead_letter_id: string;
+    consumer: string;
+    event_id: string;
+    attempt_count: number;
+    last_error: string;
+    last_error_stack: string | null;
+    envelope_snapshot: Prisma.JsonValue;
+    created_at: string;
+    resolved_at: string | null;
+    resolved_by: string | null;
+    resolution_note: string | null;
+};
+export type ListDeadLettersFilter = {
+    /** When true, includes rows where `resolved_at` is set. Default false (active rows only). */
+    includeResolved?: boolean;
+    /** Maximum rows to return across all producers, post-merge. Default 100; capped at 500. */
+    limit?: number;
+    /** Restrict to a single producer's DB. When absent, aggregates across all producers. */
+    producer?: string;
+};
+export type GetDeadLetterOptions = {
+    /** When set, only this producer's DB is queried. Without it, all producers are scanned. */
+    producer?: string;
+};
+export type ResolveDeadLetterInput = {
+    /** Which producer DB the dead-letter lives in. Required for routing the update. */
+    producer: string;
+    /** Operator identifier (Person ID, system handle, etc.) acting on the dead-letter. */
+    resolvedBy: string;
+    /** Optional free-text note describing the resolution. Stored on the row. */
+    resolutionNote?: string;
+};
+export type ReplayDeadLetterInput = {
+    /** Which producer DB the dead-letter lives in. */
+    producer: string;
+    /** Operator identifier credited on the auto-resolve when replay succeeds. */
+    replayedBy: string;
+    /** Optional free-text note added to the auto-resolve note alongside the timestamp. */
+    resolutionNote?: string;
+};
+export type ReplayDeadLetterOutcome = {
+    /** The post-replay dead-letter row (resolved when the replay POST returned 2xx). */
+    dead_letter: DeadLetter;
+    /** Consumer-domain (e.g., "sales") parsed from the row's consumer field. */
+    consumer_domain: string;
+    /** HTTP status code returned by the consumer inbox on the replay POST. */
+    consumer_status: number;
+};
+export declare class DeadLetterNotFoundError extends Error {
+    readonly deadLetterId: string;
+    constructor(deadLetterId: string);
+}
+export declare class DeadLetterAlreadyResolvedError extends Error {
+    readonly deadLetterId: string;
+    readonly resolvedAt: Date;
+    constructor(deadLetterId: string, resolvedAt: Date);
+}
+export declare class ProducerDbNotConfiguredError extends Error {
+    readonly producer: string;
+    constructor(producer: string);
+}
+export declare class ReplayConsumerUnknownError extends Error {
+    readonly consumer: string;
+    constructor(consumer: string);
+}
+export declare class ReplayDeliveryFailedError extends Error {
+    readonly statusCode: number | null;
+    readonly upstreamBody: string;
+    constructor(statusCode: number | null, upstreamBody: string, message: string);
+}
+/**
+ * Enumerate every known producer from the event-types registry. Each
+ * producer is a domain that emits at least one registered event type.
+ * Producers are deduped via Set; order is unimportant since results are
+ * sorted by created_at across the merged set.
+ */
+export declare function knownProducers(): string[];
+/**
+ * List dead-letters aggregated across every reachable producer DB.
+ * Default returns only active (unresolved) rows; pass `includeResolved:
+ * true` to include the resolved tail. Pass `consumer` to narrow to one
+ * consumer, or null/empty to return all consumers. Pass `producer` to
+ * narrow to one producer's DB. Sorted by `created_at` descending so the
+ * most recent failures surface first.
+ *
+ * A producer with no configured DSN (env var missing) is silently
+ * skipped — the boot log already names missing DSNs and the operator
+ * sees an explicit "consumer was excluded" entry there. Surfacing it as
+ * an error per call would be noise.
+ */
+export declare function listDeadLetters(consumer: string | null | undefined, filter?: ListDeadLettersFilter): Promise<DeadLetter[]>;
+/**
+ * Look up a single dead-letter by its `dlq_<UUID>` id. With `producer`
+ * set, only that producer's DB is queried; otherwise every reachable
+ * producer is scanned until the id is found. Returns null when the id
+ * does not match any row in any scanned producer's DB.
+ */
+export declare function getDeadLetter(deadLetterId: string, options?: GetDeadLetterOptions): Promise<DeadLetter | null>;
+/**
+ * Mark a dead-letter as resolved. Sets `resolved_at` to now, records
+ * the operator and the optional resolution note. The `producer` is
+ * required so we connect to the correct DB; callers typically learned
+ * it from a prior list/get call which already includes `producer` on
+ * every returned DeadLetter row.
+ *
+ * Throws DeadLetterNotFoundError if the id does not exist in the
+ * producer's DB; throws DeadLetterAlreadyResolvedError if the row was
+ * already resolved.
+ */
+export declare function resolveDeadLetter(deadLetterId: string, input: ResolveDeadLetterInput): Promise<DeadLetter>;
+/**
+ * Re-POST the dead-letter's stored envelope_snapshot to its consumer
+ * inbox. If the consumer returns 2xx, auto-resolves the DLQ row with a
+ * note recording the replay timestamp and the operator. If the consumer
+ * returns non-2xx (or the POST fails for any reason), the DLQ row stays
+ * active and the caller receives the upstream status + body for
+ * operator inspection.
+ *
+ * Replay only works for fanout-style consumers (`fanout:<domain>`)
+ * because the replay path needs a registered consumer URL + HMAC
+ * secret. Non-fanout consumers (e.g., in-process subscribers from the
+ * pre-topology-B era) throw ReplayConsumerUnknownError; their replay
+ * mechanism is "fix the bug, restart the worker, and roll back the
+ * cursor."
+ *
+ * Idempotent against double-clicks: a row that's already resolved
+ * throws DeadLetterAlreadyResolvedError so the operator sees the
+ * existing resolution rather than triggering a duplicate POST.
+ */
+export declare function replayDeadLetter(deadLetterId: string, input: ReplayDeadLetterInput): Promise<ReplayDeadLetterOutcome>;

package/dist/dlq.js

@@ -0,0 +1,391 @@
+"use strict";
+/**
+ * Dispatcher dead-letter queue (DLQ) read and resolve API.
+ *
+ * Phase 2 Slice 5. Operator-facing surface for inspecting and resolving
+ * dispatcher_dead_letter rows produced by ConsumerLoop's dead-letter
+ * path (handler exhausted retries; envelope snapshot persisted with the
+ * error trace for replay or investigation).
+ *
+ * Multi-producer aware. Per ADR-0009, each producer-domain owns its own
+ * dispatcher_dead_letter table in its own DB. The fanout ConsumerLoop
+ * writes DLQ rows into the PRODUCER's DB (because that's where the
+ * cursor and seq advance happen), so reading the DLQ for a given
+ * consumer means scanning every producer this Platform instance has a
+ * DSN for. We resolve the set of producers from the registered event
+ * types' producer field and connect via producer-db.getProducerDb.
+ *
+ * DLQ list reads can be all-consumer or narrowed to one consumer. Detail,
+ * resolve, and replay stay row-id + producer keyed.
+ *
+ * Two read shapes:
+ *
+ *   - `listDeadLetters(consumer, { includeResolved?, producer? })` returns
+ *     the active DLQ aggregated across every producer this Platform can
+ *     reach. Pass a consumer to narrow to one consumer, or null/empty to
+ *     return all consumers. Pass `producer` to narrow to one producer.
+ *
+ *   - `getDeadLetter(deadLetterId, { producer? })` returns one row by its
+ *     `dlq_<UUID>` id. With `producer` set, queries only that producer's
+ *     DB; without, scans every producer until the id is found.
+ *
+ * One write shape:
+ *
+ *   - `resolveDeadLetter(deadLetterId, { producer, resolvedBy,
+ *     resolutionNote? })` marks the row resolved with `resolved_at =
+ *     NOW()`, the operator's identifier, and an optional note. The
+ *     `producer` is required so we write to the correct DB. The
+ *     dead-letter row itself stays in place for audit; resolution does
+ *     not delete or replay.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReplayDeliveryFailedError = exports.ReplayConsumerUnknownError = exports.ProducerDbNotConfiguredError = exports.DeadLetterAlreadyResolvedError = exports.DeadLetterNotFoundError = void 0;
+exports.knownProducers = knownProducers;
+exports.listDeadLetters = listDeadLetters;
+exports.getDeadLetter = getDeadLetter;
+exports.resolveDeadLetter = resolveDeadLetter;
+exports.replayDeadLetter = replayDeadLetter;
+const fanout_1 = require("./fanout");
+const producer_db_1 = require("./producer-db");
+const registry_1 = require("./registry");
+// =============================================================================
+// Errors
+// =============================================================================
+class DeadLetterNotFoundError extends Error {
+    deadLetterId;
+    constructor(deadLetterId) {
+        super(`Dead-letter ${deadLetterId} not found`);
+        this.deadLetterId = deadLetterId;
+        this.name = "DeadLetterNotFoundError";
+    }
+}
+exports.DeadLetterNotFoundError = DeadLetterNotFoundError;
+class DeadLetterAlreadyResolvedError extends Error {
+    deadLetterId;
+    resolvedAt;
+    constructor(deadLetterId, resolvedAt) {
+        super(`Dead-letter ${deadLetterId} was already resolved at ${resolvedAt.toISOString()}`);
+        this.deadLetterId = deadLetterId;
+        this.resolvedAt = resolvedAt;
+        this.name = "DeadLetterAlreadyResolvedError";
+    }
+}
+exports.DeadLetterAlreadyResolvedError = DeadLetterAlreadyResolvedError;
+class ProducerDbNotConfiguredError extends Error {
+    producer;
+    constructor(producer) {
+        super(`Producer '${producer}' has no DSN configured (DISPATCHER_PRODUCER_DATABASE_URL_${producer.toUpperCase()} or DATABASE_URL for platform). Dead-letter operations against this producer cannot run.`);
+        this.producer = producer;
+        this.name = "ProducerDbNotConfiguredError";
+    }
+}
+exports.ProducerDbNotConfiguredError = ProducerDbNotConfiguredError;
+class ReplayConsumerUnknownError extends Error {
+    consumer;
+    constructor(consumer) {
+        super(`Cannot replay dead-letter: consumer '${consumer}' is not a fanout consumer (expected 'fanout:<domain>' for a known consumer domain). Non-fanout consumers run in-process and have no replay endpoint.`);
+        this.consumer = consumer;
+        this.name = "ReplayConsumerUnknownError";
+    }
+}
+exports.ReplayConsumerUnknownError = ReplayConsumerUnknownError;
+class ReplayDeliveryFailedError extends Error {
+    statusCode;
+    upstreamBody;
+    constructor(statusCode, upstreamBody, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.upstreamBody = upstreamBody;
+        this.name = "ReplayDeliveryFailedError";
+    }
+}
+exports.ReplayDeliveryFailedError = ReplayDeliveryFailedError;
+// =============================================================================
+// Public API
+// =============================================================================
+const DEFAULT_LIST_LIMIT = 100;
+const MAX_LIST_LIMIT = 500;
+/**
+ * Enumerate every known producer from the event-types registry. Each
+ * producer is a domain that emits at least one registered event type.
+ * Producers are deduped via Set; order is unimportant since results are
+ * sorted by created_at across the merged set.
+ */
+function knownProducers() {
+    const manifest = (0, registry_1.loadRegistry)();
+    const set = new Set();
+    for (const entry of Object.values(manifest.events)) {
+        set.add(entry.producer);
+    }
+    return Array.from(set);
+}
+/**
+ * List dead-letters aggregated across every reachable producer DB.
+ * Default returns only active (unresolved) rows; pass `includeResolved:
+ * true` to include the resolved tail. Pass `consumer` to narrow to one
+ * consumer, or null/empty to return all consumers. Pass `producer` to
+ * narrow to one producer's DB. Sorted by `created_at` descending so the
+ * most recent failures surface first.
+ *
+ * A producer with no configured DSN (env var missing) is silently
+ * skipped — the boot log already names missing DSNs and the operator
+ * sees an explicit "consumer was excluded" entry there. Surfacing it as
+ * an error per call would be noise.
+ */
+async function listDeadLetters(consumer, filter = {}) {
+    const consumerFilter = consumer?.trim() || null;
+    const limit = Math.min(filter.limit ?? DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT);
+    const producers = filter.producer ? [filter.producer] : knownProducers();
+    const merged = [];
+    const aggregateRead = !filter.producer;
+    for (const producer of producers) {
+        const db = (0, producer_db_1.getProducerDb)(producer);
+        if (!db)
+            continue;
+        const tablePrefix = db.schema ? `"${db.schema}".` : "";
+        const whereClauses = [];
+        const params = [];
+        if (consumerFilter) {
+            params.push(consumerFilter);
+            whereClauses.push(`consumer = $${params.length}`);
+        }
+        if (!filter.includeResolved) {
+            whereClauses.push("resolved_at IS NULL");
+        }
+        const whereSql = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
+        const sql = `SELECT id, consumer, event_id, attempt_count, last_error,
+                        last_error_stack, envelope_snapshot, created_at,
+                        resolved_at, resolved_by, resolution_note
+                 FROM ${tablePrefix}dispatcher_dead_letter
+                 ${whereSql}
+                 ORDER BY created_at DESC
+                 LIMIT ${limit}`;
+        let rows;
+        try {
+            const result = await db.pool.query(sql, params);
+            rows = result.rows;
+        }
+        catch (e) {
+            if (!aggregateRead)
+                throw e;
+            console.warn(`[dispatcher.dlq] producer ${producer} excluded from aggregate read: ${e instanceof Error ? e.message : String(e)}`);
+            continue;
+        }
+        for (const row of rows) {
+            merged.push(toDeadLetterFromRaw(producer, row));
+        }
+    }
+    merged.sort((a, b) => b.created_at.localeCompare(a.created_at));
+    return merged.slice(0, limit);
+}
+/**
+ * Look up a single dead-letter by its `dlq_<UUID>` id. With `producer`
+ * set, only that producer's DB is queried; otherwise every reachable
+ * producer is scanned until the id is found. Returns null when the id
+ * does not match any row in any scanned producer's DB.
+ */
+async function getDeadLetter(deadLetterId, options = {}) {
+    if (!deadLetterId)
+        return null;
+    const producers = options.producer ? [options.producer] : knownProducers();
+    const aggregateRead = !options.producer;
+    for (const producer of producers) {
+        const db = (0, producer_db_1.getProducerDb)(producer);
+        if (!db)
+            continue;
+        const tablePrefix = db.schema ? `"${db.schema}".` : "";
+        const sql = `SELECT id, consumer, event_id, attempt_count, last_error,
+                        last_error_stack, envelope_snapshot, created_at,
+                        resolved_at, resolved_by, resolution_note
+                 FROM ${tablePrefix}dispatcher_dead_letter
+                 WHERE id = $1
+                 LIMIT 1`;
+        let rows;
+        try {
+            const result = await db.pool.query(sql, [deadLetterId]);
+            rows = result.rows;
+        }
+        catch (e) {
+            if (!aggregateRead)
+                throw e;
+            console.warn(`[dispatcher.dlq] producer ${producer} excluded from aggregate detail read: ${e instanceof Error ? e.message : String(e)}`);
+            continue;
+        }
+        if (rows[0]) {
+            return toDeadLetterFromRaw(producer, rows[0]);
+        }
+    }
+    return null;
+}
+/**
+ * Mark a dead-letter as resolved. Sets `resolved_at` to now, records
+ * the operator and the optional resolution note. The `producer` is
+ * required so we connect to the correct DB; callers typically learned
+ * it from a prior list/get call which already includes `producer` on
+ * every returned DeadLetter row.
+ *
+ * Throws DeadLetterNotFoundError if the id does not exist in the
+ * producer's DB; throws DeadLetterAlreadyResolvedError if the row was
+ * already resolved.
+ */
+async function resolveDeadLetter(deadLetterId, input) {
+    if (!deadLetterId) {
+        throw new DeadLetterNotFoundError(deadLetterId);
+    }
+    if (!input.resolvedBy) {
+        throw new Error("resolveDeadLetter: resolvedBy is required");
+    }
+    if (!input.producer) {
+        throw new Error("resolveDeadLetter: producer is required");
+    }
+    const db = (0, producer_db_1.getProducerDb)(input.producer);
+    if (!db) {
+        throw new ProducerDbNotConfiguredError(input.producer);
+    }
+    const tablePrefix = db.schema ? `"${db.schema}".` : "";
+    const client = await db.pool.connect();
+    try {
+        await client.query("BEGIN");
+        const { rows: existingRows } = await client.query(`SELECT id, resolved_at
+       FROM ${tablePrefix}dispatcher_dead_letter
+       WHERE id = $1
+       FOR UPDATE`, [deadLetterId]);
+        const existing = existingRows[0];
+        if (!existing) {
+            await client.query("ROLLBACK");
+            throw new DeadLetterNotFoundError(deadLetterId);
+        }
+        if (existing.resolved_at !== null) {
+            await client.query("ROLLBACK");
+            throw new DeadLetterAlreadyResolvedError(deadLetterId, existing.resolved_at);
+        }
+        const { rows: updatedRows } = await client.query(`UPDATE ${tablePrefix}dispatcher_dead_letter
+       SET resolved_at = NOW(),
+           resolved_by = $1,
+           resolution_note = $2
+       WHERE id = $3
+       RETURNING id, consumer, event_id, attempt_count, last_error,
+                 last_error_stack, envelope_snapshot, created_at,
+                 resolved_at, resolved_by, resolution_note`, [input.resolvedBy, input.resolutionNote ?? null, deadLetterId]);
+        await client.query("COMMIT");
+        return toDeadLetterFromRaw(input.producer, updatedRows[0]);
+    }
+    catch (e) {
+        if (!(e instanceof DeadLetterNotFoundError) &&
+            !(e instanceof DeadLetterAlreadyResolvedError)) {
+            try {
+                await client.query("ROLLBACK");
+            }
+            catch { }
+        }
+        throw e;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Re-POST the dead-letter's stored envelope_snapshot to its consumer
+ * inbox. If the consumer returns 2xx, auto-resolves the DLQ row with a
+ * note recording the replay timestamp and the operator. If the consumer
+ * returns non-2xx (or the POST fails for any reason), the DLQ row stays
+ * active and the caller receives the upstream status + body for
+ * operator inspection.
+ *
+ * Replay only works for fanout-style consumers (`fanout:<domain>`)
+ * because the replay path needs a registered consumer URL + HMAC
+ * secret. Non-fanout consumers (e.g., in-process subscribers from the
+ * pre-topology-B era) throw ReplayConsumerUnknownError; their replay
+ * mechanism is "fix the bug, restart the worker, and roll back the
+ * cursor."
+ *
+ * Idempotent against double-clicks: a row that's already resolved
+ * throws DeadLetterAlreadyResolvedError so the operator sees the
+ * existing resolution rather than triggering a duplicate POST.
+ */
+async function replayDeadLetter(deadLetterId, input) {
+    if (!deadLetterId) {
+        throw new DeadLetterNotFoundError(deadLetterId);
+    }
+    if (!input.replayedBy) {
+        throw new Error("replayDeadLetter: replayedBy is required");
+    }
+    if (!input.producer) {
+        throw new Error("replayDeadLetter: producer is required");
+    }
+    // Load the dead-letter; reject early if missing or already resolved
+    // so we don't waste a POST.
+    const existing = await getDeadLetter(deadLetterId, { producer: input.producer });
+    if (!existing) {
+        throw new DeadLetterNotFoundError(deadLetterId);
+    }
+    if (existing.resolved_at !== null) {
+        throw new DeadLetterAlreadyResolvedError(deadLetterId, new Date(existing.resolved_at));
+    }
+    // Parse the consumer-domain from the row's consumer string. Replay
+    // only supports fanout:<domain> consumers because non-fanout consumers
+    // don't have a webhook URL to POST to.
+    if (!existing.consumer.startsWith(fanout_1.FANOUT_CONSUMER_PREFIX)) {
+        throw new ReplayConsumerUnknownError(existing.consumer);
+    }
+    const domain = existing.consumer.slice(fanout_1.FANOUT_CONSUMER_PREFIX.length);
+    if (!fanout_1.KNOWN_CONSUMER_DOMAINS.includes(domain)) {
+        throw new ReplayConsumerUnknownError(existing.consumer);
+    }
+    // Reconstruct the envelope from the snapshot. The snapshot is the
+    // exact JSON object the fanout originally POSTed; we re-sign and
+    // re-POST with the current HMAC secret so signature rotation since
+    // the original delivery is handled transparently.
+    const envelope = existing.envelope_snapshot;
+    let consumerStatus = 0;
+    try {
+        await (0, fanout_1.postEnvelopeToConsumer)(domain, envelope);
+        consumerStatus = 200;
+    }
+    catch (e) {
+        if (e instanceof fanout_1.WebhookDispatchError) {
+            throw new ReplayDeliveryFailedError(e.statusCode, e.message, `Replay POST to ${e.consumer}'s inbox failed: ${e.message}`);
+        }
+        throw e;
+    }
+    // Replay succeeded; auto-resolve the row so the DLQ doesn't keep
+    // showing it. The resolution note records what happened so an
+    // operator looking back can tell this was a replay, not a manual
+    // close.
+    const replayedAt = new Date().toISOString();
+    const baseNote = `replayed via DLQ console at ${replayedAt}`;
+    const fullNote = input.resolutionNote
+        ? `${baseNote} — ${input.resolutionNote}`
+        : baseNote;
+    const resolved = await resolveDeadLetter(deadLetterId, {
+        producer: input.producer,
+        resolvedBy: input.replayedBy,
+        resolutionNote: fullNote,
+    });
+    return {
+        dead_letter: resolved,
+        consumer_domain: domain,
+        consumer_status: consumerStatus,
+    };
+}
+// =============================================================================
+// Internal: raw pg row → DTO
+// =============================================================================
+function toDeadLetterFromRaw(producer, row) {
+    const createdAt = row.created_at;
+    const resolvedAt = row.resolved_at;
+    return {
+        producer,
+        dead_letter_id: String(row.id),
+        consumer: String(row.consumer),
+        event_id: String(row.event_id),
+        attempt_count: Number(row.attempt_count),
+        last_error: String(row.last_error),
+        last_error_stack: row.last_error_stack ?? null,
+        envelope_snapshot: row.envelope_snapshot,
+        created_at: createdAt.toISOString(),
+        resolved_at: resolvedAt ? resolvedAt.toISOString() : null,
+        resolved_by: row.resolved_by ?? null,
+        resolution_note: row.resolution_note ?? null,
+    };
+}

package/dist/fanout-drain.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Node-only SIGTERM/SIGINT drain registration for the fanout worker.
+ *
+ * Lives in its own module so `instrumentation.ts` can reference it only via
+ * dynamic import behind the `process.env.NEXT_RUNTIME === "nodejs"` guard.
+ * Doing it this way keeps `process.once` out of the file the Next.js
+ * bundler statically analyzes for Edge Runtime compatibility — otherwise
+ * the build emits an "Ecmascript file had an error: A Node.js API is used"
+ * warning even though the call site is gated and never executes off Node.
+ */
+export declare function registerFanoutDrain(stopFanout: () => Promise<void>): void;

package/dist/fanout-drain.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Node-only SIGTERM/SIGINT drain registration for the fanout worker.
+ *
+ * Lives in its own module so `instrumentation.ts` can reference it only via
+ * dynamic import behind the `process.env.NEXT_RUNTIME === "nodejs"` guard.
+ * Doing it this way keeps `process.once` out of the file the Next.js
+ * bundler statically analyzes for Edge Runtime compatibility — otherwise
+ * the build emits an "Ecmascript file had an error: A Node.js API is used"
+ * warning even though the call site is gated and never executes off Node.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFanoutDrain = registerFanoutDrain;
+function registerFanoutDrain(stopFanout) {
+    const drainOnTermination = async () => {
+        try {
+            const drainPromise = stopFanout();
+            const timeoutPromise = new Promise((resolve) => setTimeout(resolve, 30_000));
+            await Promise.race([drainPromise, timeoutPromise]);
+        }
+        catch (e) {
+            console.error(`[fanout-drain] stop error: ${e instanceof Error ? e.stack ?? e.message : String(e)}`);
+        }
+    };
+    process.once("SIGTERM", () => {
+        void drainOnTermination();
+    });
+    process.once("SIGINT", () => {
+        void drainOnTermination();
+    });
+}