@sguild/dispatcher 2.0.0

package/dist/fanout.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Platform-side dispatcher fanout worker per the 2026-05-12 topology
+ * decision (memos/2026-05-12-platform-cross-db-consumer-dsn-upstream).
+ *
+ * For each (event_type, consumer-domain) registered in the event-types
+ * registry, the fanout creates a webhook-dispatch handler that POSTs the
+ * envelope to the consumer-domain's configured URL with an HMAC-signed
+ * body. The existing ConsumerLoop machinery owns the cursor advancement,
+ * retry-with-backoff, dedup, and dead-letter logic; this module is a
+ * thin layer over it that swaps the in-process handler invocation for an
+ * HTTP POST.
+ *
+ * Multi-producer fanout: one ConsumerLoop per (producer-domain,
+ * consumer-domain) pair. Each loop reads from the producer's
+ * `dispatcher_event` table (per ADR-0009's per-domain table family) via
+ * a producer-specific Prisma client resolved through producer-db.ts. The
+ * fanout is centralized in Platform's worker rather than distributed
+ * across each consumer process, preserving topology B's "one place
+ * owns retry / dedup / DLQ" rationale even when the producer is a
+ * different domain's database.
+ *
+ * Consumer name pattern: "fanout:<consumer-domain>" (e.g., "fanout:sales").
+ * The dispatcher_cursor, dispatcher_dedup, and dispatcher_dead_letter
+ * rows live in the producer's database, so the same consumer name
+ * appearing in multiple producer DBs does not collide — each producer's
+ * cursor table tracks its own (consumer, event_type) pair independently.
+ *
+ * Routing is env-var-driven so the same code runs in dev, staging, and
+ * production with different DSNs / URLs:
+ *
+ *   DISPATCHER_PRODUCER_DATABASE_URL_<PRODUCER>  source DSN per producer
+ *                                                (DATABASE_URL is used
+ *                                                for the worker's own
+ *                                                producer when applicable)
+ *   DISPATCHER_CONSUMER_URL_<DOMAIN>             destination webhook URL
+ *   DISPATCHER_CONSUMER_SECRET_<DOMAIN>          shared HMAC secret
+ *
+ * A producer with no DSN, or a consumer with no URL or secret, is logged
+ * at info level and excluded from the fanout. The loop appears
+ * automatically on the next process restart once the missing env arrives.
+ *
+ * Master gate: DISPATCHER_FANOUT_ENABLED=true must be set for the
+ * fanout to start. Absent the flag, startFanout returns a no-op stop
+ * function and logs that the fanout is disabled. Useful for local dev
+ * loops where Platform's web server should run without firing webhooks.
+ *
+ * HMAC signature contract: header `X-Sguild-Signature: sha256=<hex>` over
+ * the JSON-serialized envelope body, computed with the per-consumer
+ * shared secret. Consumers verify by recomputing the same digest and
+ * constant-time comparing. Compromised secret is rotated by updating
+ * both the Platform env and the consumer env in lockstep.
+ *
+ * Slice 4 of the Phase 2 dispatcher SDK; lands the topology B decision.
+ */
+import { ConsumerLoop } from "./postgres-consumer";
+import type { EventEnvelope, LiveProducerDomain } from "./types";
+export { EVENT_ID_HEADER, EVENT_TYPE_HEADER, SIGNATURE_HEADER, signEnvelope, verifyEnvelopeSignature, } from "./signature";
+export declare const FANOUT_CONSUMER_PREFIX = "fanout:";
+/**
+ * Domains the fanout knows about as webhook destinations. Platform is
+ * now included so cross-domain producers (e.g., Sales emitting
+ * `role.assigned` for the lead role) can fan back to Platform's own
+ * webhook inbox — Platform's person_role projection consumes those
+ * events the same way Sales/Growth consume person.updated.
+ *
+ * Self-fanout is prevented separately by the `consumer === producer`
+ * check in buildFanoutLoops, so Platform producing person.updated still
+ * doesn't get re-delivered to its own inbox.
+ *
+ * `platform-warehouse` stays excluded — that's a synthetic consumer
+ * for the warehouse loader, not a webhook destination.
+ */
+export declare const KNOWN_CONSUMER_DOMAINS: ReadonlyArray<LiveProducerDomain>;
+export declare class WebhookDispatchError extends Error {
+    readonly consumer: string;
+    readonly url: string;
+    readonly statusCode: number | null;
+    constructor(consumer: string, url: string, statusCode: number | null, message: string);
+}
+export declare function consumerUrl(domain: LiveProducerDomain): string | null;
+export declare function consumerSecret(domain: LiveProducerDomain): string | null;
+/**
+ * POST an envelope to a single consumer-domain's inbox URL. Throws a
+ * WebhookDispatchError on non-2xx response or network failure; the
+ * ConsumerLoop's retry-with-backoff handles the rest.
+ *
+ * The envelope is JSON-serialized once; the same string is both signed
+ * and sent as the request body so the consumer's signature verification
+ * uses the exact bytes the signature was computed over.
+ */
+export declare function postEnvelopeToConsumer(consumer: LiveProducerDomain, envelope: EventEnvelope<unknown>, fetchImpl?: typeof fetch): Promise<void>;
+export type FanoutLoopHandle = {
+    /** Source producer-domain this loop polls from. Determines which DB's dispatcher_event the loop reads. */
+    producer: string;
+    /** Destination consumer-domain this loop POSTs envelopes to. */
+    consumer: LiveProducerDomain;
+    loop: ConsumerLoop;
+};
+/**
+ * Build the consumer-loop set for Platform's fanout. Reads the registry,
+ * groups events by (producer, consumer-domain), and for each producer
+ * resolves the producer's DSN via producer-db.ts so the loop's reads
+ * and LISTEN/NOTIFY wake-up target that producer's database. Returns an
+ * array of {producer, consumer, loop} ready to start.
+ *
+ * Exclusion logging at info level:
+ *   - Producer DSN missing: every loop reading that producer is skipped.
+ *     The boot log names the producer and the env var to provision
+ *     (DATABASE_URL for self-producer, DISPATCHER_PRODUCER_DATABASE_URL_*
+ *     for everything else).
+ *   - Consumer URL or secret missing: every loop POSTing to that
+ *     consumer is skipped.
+ *
+ * Skipped (producer, consumer) pairs pick up automatically on the next
+ * process restart once the missing env is provisioned.
+ */
+export declare function buildFanoutLoops(options?: {
+    fetchImpl?: typeof fetch;
+}): FanoutLoopHandle[];
+/**
+ * Start all fanout loops. Returns a stop function the caller invokes
+ * on shutdown (SIGTERM via instrumentation.ts).
+ *
+ * Master gate: DISPATCHER_FANOUT_ENABLED=true is required for the
+ * fanout to start. Absent the flag, this is a no-op and the caller
+ * gets a stop function that resolves immediately. This lets dev and
+ * test environments run Platform without firing webhooks unless the
+ * developer explicitly opts in.
+ *
+ * Calling startFanout twice without an intervening stop throws.
+ */
+export declare function startFanout(options?: {
+    fetchImpl?: typeof fetch;
+}): Promise<() => Promise<void>>;
+/**
+ * Test-only: get the running loops for introspection. Production code
+ * never calls this.
+ */
+export declare function __getRunningLoopsForTests(): FanoutLoopHandle[];
+/**
+ * Test-only: reset the running-loops state. Used between test fixtures
+ * to allow startFanout to be called again without a prior stop call.
+ */
+export declare function __resetFanoutStateForTests(): void;

package/dist/fanout.js

@@ -0,0 +1,321 @@
+"use strict";
+/**
+ * Platform-side dispatcher fanout worker per the 2026-05-12 topology
+ * decision (memos/2026-05-12-platform-cross-db-consumer-dsn-upstream).
+ *
+ * For each (event_type, consumer-domain) registered in the event-types
+ * registry, the fanout creates a webhook-dispatch handler that POSTs the
+ * envelope to the consumer-domain's configured URL with an HMAC-signed
+ * body. The existing ConsumerLoop machinery owns the cursor advancement,
+ * retry-with-backoff, dedup, and dead-letter logic; this module is a
+ * thin layer over it that swaps the in-process handler invocation for an
+ * HTTP POST.
+ *
+ * Multi-producer fanout: one ConsumerLoop per (producer-domain,
+ * consumer-domain) pair. Each loop reads from the producer's
+ * `dispatcher_event` table (per ADR-0009's per-domain table family) via
+ * a producer-specific Prisma client resolved through producer-db.ts. The
+ * fanout is centralized in Platform's worker rather than distributed
+ * across each consumer process, preserving topology B's "one place
+ * owns retry / dedup / DLQ" rationale even when the producer is a
+ * different domain's database.
+ *
+ * Consumer name pattern: "fanout:<consumer-domain>" (e.g., "fanout:sales").
+ * The dispatcher_cursor, dispatcher_dedup, and dispatcher_dead_letter
+ * rows live in the producer's database, so the same consumer name
+ * appearing in multiple producer DBs does not collide — each producer's
+ * cursor table tracks its own (consumer, event_type) pair independently.
+ *
+ * Routing is env-var-driven so the same code runs in dev, staging, and
+ * production with different DSNs / URLs:
+ *
+ *   DISPATCHER_PRODUCER_DATABASE_URL_<PRODUCER>  source DSN per producer
+ *                                                (DATABASE_URL is used
+ *                                                for the worker's own
+ *                                                producer when applicable)
+ *   DISPATCHER_CONSUMER_URL_<DOMAIN>             destination webhook URL
+ *   DISPATCHER_CONSUMER_SECRET_<DOMAIN>          shared HMAC secret
+ *
+ * A producer with no DSN, or a consumer with no URL or secret, is logged
+ * at info level and excluded from the fanout. The loop appears
+ * automatically on the next process restart once the missing env arrives.
+ *
+ * Master gate: DISPATCHER_FANOUT_ENABLED=true must be set for the
+ * fanout to start. Absent the flag, startFanout returns a no-op stop
+ * function and logs that the fanout is disabled. Useful for local dev
+ * loops where Platform's web server should run without firing webhooks.
+ *
+ * HMAC signature contract: header `X-Sguild-Signature: sha256=<hex>` over
+ * the JSON-serialized envelope body, computed with the per-consumer
+ * shared secret. Consumers verify by recomputing the same digest and
+ * constant-time comparing. Compromised secret is rotated by updating
+ * both the Platform env and the consumer env in lockstep.
+ *
+ * Slice 4 of the Phase 2 dispatcher SDK; lands the topology B decision.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookDispatchError = exports.KNOWN_CONSUMER_DOMAINS = exports.FANOUT_CONSUMER_PREFIX = exports.verifyEnvelopeSignature = exports.signEnvelope = exports.SIGNATURE_HEADER = exports.EVENT_TYPE_HEADER = exports.EVENT_ID_HEADER = void 0;
+exports.consumerUrl = consumerUrl;
+exports.consumerSecret = consumerSecret;
+exports.postEnvelopeToConsumer = postEnvelopeToConsumer;
+exports.buildFanoutLoops = buildFanoutLoops;
+exports.startFanout = startFanout;
+exports.__getRunningLoopsForTests = __getRunningLoopsForTests;
+exports.__resetFanoutStateForTests = __resetFanoutStateForTests;
+const postgres_consumer_1 = require("./postgres-consumer");
+const producer_db_1 = require("./producer-db");
+const registry_1 = require("./registry");
+const signature_1 = require("./signature");
+// Re-export the signature primitives at the fanout layer so existing
+// consumers of these constants from fanout.ts continue to work. The
+// canonical home is signature.ts; this is a soft-deprecation alias for
+// the legacy import path.
+var signature_2 = require("./signature");
+Object.defineProperty(exports, "EVENT_ID_HEADER", { enumerable: true, get: function () { return signature_2.EVENT_ID_HEADER; } });
+Object.defineProperty(exports, "EVENT_TYPE_HEADER", { enumerable: true, get: function () { return signature_2.EVENT_TYPE_HEADER; } });
+Object.defineProperty(exports, "SIGNATURE_HEADER", { enumerable: true, get: function () { return signature_2.SIGNATURE_HEADER; } });
+Object.defineProperty(exports, "signEnvelope", { enumerable: true, get: function () { return signature_2.signEnvelope; } });
+Object.defineProperty(exports, "verifyEnvelopeSignature", { enumerable: true, get: function () { return signature_2.verifyEnvelopeSignature; } });
+// =============================================================================
+// Constants
+// =============================================================================
+exports.FANOUT_CONSUMER_PREFIX = "fanout:";
+/**
+ * Domains the fanout knows about as webhook destinations. Platform is
+ * now included so cross-domain producers (e.g., Sales emitting
+ * `role.assigned` for the lead role) can fan back to Platform's own
+ * webhook inbox — Platform's person_role projection consumes those
+ * events the same way Sales/Growth consume person.updated.
+ *
+ * Self-fanout is prevented separately by the `consumer === producer`
+ * check in buildFanoutLoops, so Platform producing person.updated still
+ * doesn't get re-delivered to its own inbox.
+ *
+ * `platform-warehouse` stays excluded — that's a synthetic consumer
+ * for the warehouse loader, not a webhook destination.
+ */
+exports.KNOWN_CONSUMER_DOMAINS = [
+    "platform",
+    "growth",
+    "sales",
+    "delivery",
+    "revenue",
+    "coaching",
+];
+// =============================================================================
+// Error types
+// =============================================================================
+class WebhookDispatchError extends Error {
+    consumer;
+    url;
+    statusCode;
+    constructor(consumer, url, statusCode, message) {
+        super(message);
+        this.consumer = consumer;
+        this.url = url;
+        this.statusCode = statusCode;
+        this.name = "WebhookDispatchError";
+    }
+}
+exports.WebhookDispatchError = WebhookDispatchError;
+// =============================================================================
+// Routing config
+// =============================================================================
+function consumerUrl(domain) {
+    const envName = `DISPATCHER_CONSUMER_URL_${domain.toUpperCase()}`;
+    return process.env[envName] || null;
+}
+function consumerSecret(domain) {
+    const envName = `DISPATCHER_CONSUMER_SECRET_${domain.toUpperCase()}`;
+    return process.env[envName] || null;
+}
+// =============================================================================
+// Webhook dispatch
+// =============================================================================
+/**
+ * POST an envelope to a single consumer-domain's inbox URL. Throws a
+ * WebhookDispatchError on non-2xx response or network failure; the
+ * ConsumerLoop's retry-with-backoff handles the rest.
+ *
+ * The envelope is JSON-serialized once; the same string is both signed
+ * and sent as the request body so the consumer's signature verification
+ * uses the exact bytes the signature was computed over.
+ */
+async function postEnvelopeToConsumer(consumer, envelope, fetchImpl = globalThis.fetch) {
+    const url = consumerUrl(consumer);
+    const secret = consumerSecret(consumer);
+    if (!url) {
+        throw new WebhookDispatchError(consumer, "<unset>", null, `Consumer URL not set; expected env DISPATCHER_CONSUMER_URL_${consumer.toUpperCase()}`);
+    }
+    if (!secret) {
+        throw new WebhookDispatchError(consumer, url, null, `Consumer HMAC secret not set; expected env DISPATCHER_CONSUMER_SECRET_${consumer.toUpperCase()}`);
+    }
+    const body = JSON.stringify(envelope);
+    const signature = `sha256=${(0, signature_1.signEnvelope)(body, secret)}`;
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                [signature_1.EVENT_ID_HEADER]: envelope.event_id,
+                [signature_1.EVENT_TYPE_HEADER]: envelope.event_type,
+                [signature_1.SIGNATURE_HEADER]: signature,
+            },
+            body,
+        });
+    }
+    catch (e) {
+        throw new WebhookDispatchError(consumer, url, null, `Network error POSTing to consumer: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!response.ok) {
+        let bodyText;
+        try {
+            bodyText = (await response.text()).slice(0, 500);
+        }
+        catch {
+            bodyText = "<unreadable response body>";
+        }
+        throw new WebhookDispatchError(consumer, url, response.status, `Consumer returned non-2xx: ${response.status} ${response.statusText}; body: ${bodyText}`);
+    }
+}
+/**
+ * Build the consumer-loop set for Platform's fanout. Reads the registry,
+ * groups events by (producer, consumer-domain), and for each producer
+ * resolves the producer's DSN via producer-db.ts so the loop's reads
+ * and LISTEN/NOTIFY wake-up target that producer's database. Returns an
+ * array of {producer, consumer, loop} ready to start.
+ *
+ * Exclusion logging at info level:
+ *   - Producer DSN missing: every loop reading that producer is skipped.
+ *     The boot log names the producer and the env var to provision
+ *     (DATABASE_URL for self-producer, DISPATCHER_PRODUCER_DATABASE_URL_*
+ *     for everything else).
+ *   - Consumer URL or secret missing: every loop POSTing to that
+ *     consumer is skipped.
+ *
+ * Skipped (producer, consumer) pairs pick up automatically on the next
+ * process restart once the missing env is provisioned.
+ */
+function buildFanoutLoops(options = {}) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const manifest = (0, registry_1.loadRegistry)();
+    // Group registrations by (producer, consumer). The outer key is the
+    // producer (because each producer has its own DSN and its own
+    // ConsumerLoop instance); the inner key is the consumer (because each
+    // consumer has its own webhook URL).
+    const byProducerThenConsumer = new Map();
+    for (const [eventType, entry] of Object.entries(manifest.events)) {
+        const producer = entry.producer;
+        for (const consumer of entry.consumers) {
+            if (consumer === "platform-warehouse")
+                continue;
+            if (consumer === producer)
+                continue; // no self-fanout
+            if (!exports.KNOWN_CONSUMER_DOMAINS.includes(consumer))
+                continue;
+            const domain = consumer;
+            let consumerMap = byProducerThenConsumer.get(producer);
+            if (!consumerMap) {
+                consumerMap = new Map();
+                byProducerThenConsumer.set(producer, consumerMap);
+            }
+            if (!consumerMap.has(domain)) {
+                consumerMap.set(domain, []);
+            }
+            consumerMap.get(domain).push({
+                eventType,
+                handler: (envelope) => postEnvelopeToConsumer(domain, envelope, fetchImpl),
+            });
+        }
+    }
+    const result = [];
+    for (const [producer, consumerMap] of byProducerThenConsumer.entries()) {
+        const producerDb = (0, producer_db_1.getProducerDb)(producer);
+        if (!producerDb) {
+            const envName = producer === "platform"
+                ? "DATABASE_URL"
+                : `DISPATCHER_PRODUCER_DATABASE_URL_${producer.toUpperCase()}`;
+            console.log(`[dispatcher.fanout] producer ${producer} excluded: DSN not set; expected env ${envName}; ${consumerMap.size} consumer loop(s) will start once the env is provisioned`);
+            continue;
+        }
+        for (const [domain, registrations] of consumerMap.entries()) {
+            const url = consumerUrl(domain);
+            const secret = consumerSecret(domain);
+            if (!url || !secret) {
+                console.log(`[dispatcher.fanout] consumer ${domain} from producer ${producer} excluded: ${!url ? "URL" : "secret"} env var not set; the loop will start once DISPATCHER_CONSUMER_URL_${domain.toUpperCase()} and DISPATCHER_CONSUMER_SECRET_${domain.toUpperCase()} are provisioned`);
+                continue;
+            }
+            const loop = new postgres_consumer_1.ConsumerLoop(registrations, {
+                consumer: `${exports.FANOUT_CONSUMER_PREFIX}${domain}`,
+                pool: producerDb.pool,
+                databaseUrl: producerDb.databaseUrl,
+                schema: producerDb.schema,
+            });
+            result.push({ producer, consumer: domain, loop });
+        }
+    }
+    return result;
+}
+// =============================================================================
+// Bootstrap entry point
+// =============================================================================
+let runningLoops = [];
+/**
+ * Start all fanout loops. Returns a stop function the caller invokes
+ * on shutdown (SIGTERM via instrumentation.ts).
+ *
+ * Master gate: DISPATCHER_FANOUT_ENABLED=true is required for the
+ * fanout to start. Absent the flag, this is a no-op and the caller
+ * gets a stop function that resolves immediately. This lets dev and
+ * test environments run Platform without firing webhooks unless the
+ * developer explicitly opts in.
+ *
+ * Calling startFanout twice without an intervening stop throws.
+ */
+async function startFanout(options = {}) {
+    if (process.env.DISPATCHER_FANOUT_ENABLED !== "true") {
+        console.log("[dispatcher.fanout] disabled (DISPATCHER_FANOUT_ENABLED != 'true'); skipping bootstrap");
+        return async () => { };
+    }
+    if (runningLoops.length > 0) {
+        throw new Error("dispatcher.fanout.startFanout: already running; call the previous stop() before starting again");
+    }
+    const loops = buildFanoutLoops(options);
+    if (loops.length === 0) {
+        console.log("[dispatcher.fanout] no fanout loops to start (no Platform-produced events with provisioned consumer URLs)");
+        return async () => { };
+    }
+    runningLoops = loops;
+    const pairs = loops.map((l) => `${l.producer}->${l.consumer}`).join(", ");
+    console.log(`[dispatcher.fanout] starting fanout for ${loops.length} (producer, consumer) pair(s): ${pairs}`);
+    // Fire-and-forget each loop's start(). ConsumerLoop.start() returns
+    // a promise that only resolves when stop() is called and the
+    // in-flight batch finishes draining, so awaiting all of them would
+    // block forever. Track unhandled errors so a misbehaving loop crash
+    // is visible in logs rather than swallowed.
+    for (const { producer, consumer, loop } of loops) {
+        loop.start().catch((e) => {
+            console.error(`[dispatcher.fanout] ${producer}->${consumer} loop crashed: ${e instanceof Error ? e.stack ?? e.message : String(e)}`);
+        });
+    }
+    return async () => {
+        const current = runningLoops;
+        runningLoops = [];
+        await Promise.all(current.map((l) => l.loop.stop()));
+    };
+}
+/**
+ * Test-only: get the running loops for introspection. Production code
+ * never calls this.
+ */
+function __getRunningLoopsForTests() {
+    return runningLoops;
+}
+/**
+ * Test-only: reset the running-loops state. Used between test fixtures
+ * to allow startFanout to be called again without a prior stop call.
+ */
+function __resetFanoutStateForTests() {
+    runningLoops = [];
+}

package/dist/inbox.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Domain-side dispatcher inbox helpers.
+ *
+ * Per the 2026-05-12 topology decision (memos/2026-05-12-platform-cross-db-
+ * consumer-dsn-upstream): Platform's fanout worker POSTs events to each
+ * consumer domain's webhook endpoint. The endpoint pattern is roughly:
+ *
+ *   POST /api/dispatcher/inbox
+ *
+ * with these headers from Platform's fanout:
+ *
+ *   x-sguild-event-id: evt_<UUIDv7>
+ *   x-sguild-event-type: <event_type>
+ *   x-sguild-signature: sha256=<hex>
+ *
+ * and the JSON-serialized envelope as the request body. This module
+ * carries the two pieces every domain inbox needs:
+ *
+ * 1. `verifyInboxRequest(...)` — validates the HMAC signature against
+ *    the raw request body using the domain's shared secret, returns the
+ *    parsed envelope on success or a typed error on failure.
+ *
+ * 2. `dedupOnEventId(...)` — wraps an idempotency check in the domain's
+ *    own database. Domains track which event_ids they have already
+ *    processed; a duplicate hit returns early without re-running the
+ *    handler. The dedup table is domain-owned, not Platform's.
+ *
+ * Domains import these helpers from `@/lib/dispatcher/inbox` once they
+ * vendor Platform's dispatcher SDK. The handler shape is the domain's
+ * own concern — this module does not own routing; it owns signature
+ * verification and the dedup contract.
+ *
+ * The reference route at `app/api/dispatcher/inbox/route.ts` in this
+ * repo shows the full assembly: verify, parse, dedup, dispatch, ack.
+ */
+import type { EventEnvelope } from "./types";
+export type InboxVerificationResult<TPayload = unknown> = {
+    ok: true;
+    envelope: EventEnvelope<TPayload>;
+    rawBody: string;
+} | {
+    ok: false;
+    status: 401 | 400;
+    reason: string;
+};
+/**
+ * Verify a Platform-fanout-style POST request against the domain's
+ * shared HMAC secret. The signature is computed over the raw request
+ * body, so callers MUST pass the exact bytes received (not a re-
+ * stringified JSON object). The standard pattern in a Next.js route
+ * handler is:
+ *
+ *   const rawBody = await req.text();
+ *   const result = verifyInboxRequest(rawBody, req.headers, secret);
+ *
+ * Returns the parsed envelope on success. Failures map to the right
+ * HTTP status: 401 for signature mismatch, 400 for missing header or
+ * malformed body. The route handler returns that status verbatim.
+ *
+ * On 5xx-shaped failures (database errors during dedup, handler
+ * throws, etc.), the route handler returns 500 separately; Platform's
+ * fanout retries on 5xx and dead-letters on permanent failure. 4xx
+ * responses also retry once per Platform's ConsumerLoop retry budget
+ * (4xx may indicate a deploy-in-progress secret rotation that is
+ * transient).
+ */
+export declare function verifyInboxRequest<TPayload = unknown>(rawBody: string, headers: Headers, secret: string): InboxVerificationResult<TPayload>;
+/**
+ * Domain-side dedup helper. Domains track which event_ids they have
+ * already processed in their own table; Platform's fanout retries can
+ * deliver the same envelope twice, and the inbox must be idempotent.
+ *
+ * The dedup contract:
+ *
+ * 1. Before invoking the handler, attempt to INSERT (consumer-name,
+ *    event_id) into the domain's dedup table.
+ * 2. On unique-constraint conflict (already processed), short-circuit
+ *    and return 200; Platform's fanout treats this as success and
+ *    advances its cursor.
+ * 3. On successful insert, invoke the handler. If the handler throws,
+ *    the row stays (a future retry will see "already processed" and
+ *    short-circuit, by design: the handler was attempted, even if it
+ *    failed — operator inspects via the domain's lead_activity / audit
+ *    log if a retry is needed; do NOT re-invoke on retry, that breaks
+ *    at-most-once).
+ *
+ * The schema each domain owns:
+ *
+ *   CREATE TABLE dispatcher_inbox_dedup (
+ *     event_id   TEXT PRIMARY KEY,
+ *     event_type TEXT NOT NULL,
+ *     processed_at TIMESTAMPTZ NOT NULL DEFAULT now()
+ *   );
+ *
+ * Domains may add columns (e.g., outcome_summary, handler_version) for
+ * audit. The PRIMARY KEY on event_id is the load-bearing piece.
+ *
+ * Why event_id alone is sufficient (no consumer column): each domain's
+ * dedup table is exclusive to that domain. Cross-consumer dedup is
+ * Platform's responsibility on the fanout side (dispatcher_dedup with
+ * consumer = "fanout:<domain>").
+ *
+ * This module does not ship an opinionated implementation; the domain's
+ * Prisma client and schema vary. The interface is documented above so
+ * each domain can drop in a 5-line repo function.
+ */
+export type DedupOutcome = "first_time" | "already_processed";
+export type DedupAttempt = (eventId: string, eventType: string) => Promise<DedupOutcome>;
+/**
+ * Helper for the common case where the dedup INSERT throws on conflict
+ * with a recognizable Prisma error code. Wrap a Prisma insert and pass
+ * the throwing function in. The helper inspects the thrown error for
+ * Prisma's unique-violation code (P2002) and translates to
+ * `already_processed`; any other error rethrows.
+ *
+ * Usage:
+ *
+ *   const outcome = await tryInsertOrDetectConflict(async () => {
+ *     await prisma.dispatcherInboxDedup.create({
+ *       data: { eventId, eventType }
+ *     });
+ *   });
+ *   if (outcome === "already_processed") return new Response(null, { status: 200 });
+ */
+export declare function tryInsertOrDetectConflict(insert: () => Promise<void>): Promise<DedupOutcome>;