@sguild/dispatcher 2.0.0

package/dist/postgres-consumer.js

@@ -0,0 +1,561 @@
+"use strict";
+/**
+ * Postgres-queue transport: consumer-side polling worker.
+ *
+ * Implements the consume path of the bus dispatcher per ADR-0009
+ * §"Decision". Long-lived process (typically run from
+ * `<repo>/scripts/<consumer>-subscriber.ts` per the per-domain module
+ * pattern) that polls `dispatcher_event` past a per-(consumer,
+ * event_type) cursor, dedups against `dispatcher_dedup`, invokes the
+ * registered handler, retries on exception with exponential backoff and
+ * jitter, dead-letters on exhaustion, and advances the cursor atomically
+ * with the dedup write on success (or the dead-letter write on
+ * exhaustion).
+ *
+ * Phase 2 Slice 3 (this file): poll-only consumer. The LISTEN/NOTIFY
+ * wake-up primitive ADR-0009 §"Decision" calls for is the Slice 3b
+ * deliverable; Slice 3 ships poll-only because the polling loop is the
+ * durable fallback regardless of whether LISTEN/NOTIFY is wired, and
+ * shipping poll-only first gives consumers a working subscriber surface
+ * to scaffold against. Consumers cut over to the same call shape when
+ * LISTEN/NOTIFY lands; only the latency profile changes (sub-second on
+ * the happy path, polling cadence as the fallback under either model).
+ *
+ * Per-consumer scope: each consumer instance is identified by a
+ * stable string (e.g., "coaching-availability-subscriber") that goes
+ * onto the cursor and dedup rows. A given consumer string MUST be
+ * unique across deployments; running two processes against the same
+ * consumer string causes them to compete for cursor advancement and
+ * the dedup window collapses to per-consumer-id rather than
+ * per-process. Per the build plan §3, the typical shape is one
+ * consumer string per long-lived worker process per domain.
+ *
+ * Per-event-type fan-out: a single ConsumerLoop instance processes
+ * all subscribed event_types serially within a poll cycle (one
+ * batch per event_type, in registration order). For workloads where
+ * one event_type has substantially higher volume than others and the
+ * serial drain becomes a latency bottleneck, run multiple
+ * ConsumerLoop instances against the same database with different
+ * consumer strings — but typical Sguild volume per consumer fits
+ * comfortably inside a single loop's drain cadence.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsumerLoop = void 0;
+const pg_1 = require("pg");
+const pg_search_path_1 = require("./internal/pg-search-path");
+const id_1 = require("./internal/id");
+const observability_1 = require("./observability");
+// =============================================================================
+// Defaults aligned with ADR-0009 §"Action Items" and §"Trade-off Analysis".
+// =============================================================================
+/** Default poll interval; the LISTEN/NOTIFY wake-up shipping in Slice 3b will reduce typical wake-up latency to sub-second. */
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+/** Default batch size per event_type per poll cycle. Bounded so a single consumer cannot starve other event_types within the same loop. */
+const DEFAULT_BATCH_SIZE = 50;
+/**
+ * Default retry-after delays in ms. Three retries past the initial
+ * attempt per ADR-0009 §"Decision"; exponential progression with the
+ * actual delay carrying multiplicative jitter (0-30 percent of base) so
+ * a thundering herd of failed events does not retry in lockstep.
+ */
+const DEFAULT_RETRY_DELAYS_MS = [1000, 5000, 15000];
+/** ID prefix for dead-letter rows per the prefix convention in ADR-0002. */
+const DEAD_LETTER_ID_PREFIX = "dlq_";
+/** LISTEN channel name. Matches the trigger function in Slice 1's migration. */
+const LISTEN_CHANNEL = "dispatcher_event_inserted";
+/** Backoff delays when the LISTEN connection drops and needs to reconnect. */
+const LISTEN_RECONNECT_DELAYS_MS = [1000, 5000, 15000, 60000];
+// =============================================================================
+// ConsumerLoop
+// =============================================================================
+class ConsumerLoop {
+    handlers;
+    running = false;
+    inflight = false;
+    options;
+    pool;
+    ownsPool;
+    databaseUrl;
+    /**
+     * Quoted table-name prefix. Empty string when no schema is configured;
+     * `"<schema>".` (with trailing dot) when a schema is set. Prepended to
+     * every dispatcher_X table reference in the SQL queries so they work
+     * even when Supabase's pooler drops the search_path option.
+     */
+    tablePrefix;
+    subscribedEventTypes;
+    // LISTEN/NOTIFY state. The listenClient is a separate pg.Client (not
+    // the Prisma pool) because LISTEN ties up the connection for the
+    // duration; using a Prisma-pool connection would block other queries.
+    // Reconnect attempts run with backoff per LISTEN_RECONNECT_DELAYS_MS;
+    // polling stays as the durable fallback the whole time.
+    listenClient = null;
+    listenReconnectScheduled = false;
+    listenReconnectAttempt = 0;
+    // Wake-up controller. The polling loop's between-cycle sleep is
+    // interruptible: when a NOTIFY arrives for a subscribed event_type
+    // (or when stop() is called), `wakeUp()` aborts the sleep and the
+    // loop runs another cycle immediately.
+    sleepAbort = null;
+    constructor(handlers, options) {
+        this.handlers = handlers;
+        if (!options.consumer) {
+            throw new Error("ConsumerLoop: consumer name is required");
+        }
+        if (handlers.length === 0) {
+            throw new Error("ConsumerLoop: at least one handler must be registered");
+        }
+        this.options = {
+            consumer: options.consumer,
+            batchSize: options.batchSize ?? DEFAULT_BATCH_SIZE,
+            pollIntervalMs: options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+            retryDelaysMs: options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS,
+        };
+        this.databaseUrl = options.databaseUrl ?? process.env.DATABASE_URL;
+        if (options.pool) {
+            this.pool = options.pool;
+            this.ownsPool = false;
+        }
+        else {
+            // Default pool from DATABASE_URL for the in-process Platform path.
+            // Owned by this loop so stop() can drain connections cleanly.
+            this.pool = new pg_1.Pool((0, pg_search_path_1.pgConfigWithSearchPath)(this.databaseUrl));
+            this.pool.on("error", (error) => {
+                console.warn(`ConsumerLoop[${this.options.consumer}]: pool error: ${error.message}`);
+            });
+            this.ownsPool = true;
+        }
+        // Schema-qualify the dispatcher tables if a schema is configured. Bypasses
+        // pgbouncer's transaction-mode pooling, which silently drops the libpq
+        // `options=-c search_path=...` startup parameter — the search_path config
+        // ends up not applying on pooler DSNs even though the helper sets it.
+        // Fall back to the DSN's `?schema=` parsed value when the caller did not
+        // pass an explicit `schema` option, so the in-process path (Platform's
+        // own DATABASE_URL with `?schema=platform`) gets the same treatment.
+        const resolvedSchema = options.schema ?? (0, pg_search_path_1.pgConfigWithSearchPath)(this.databaseUrl).schema;
+        if (resolvedSchema) {
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(resolvedSchema)) {
+                throw new Error(`ConsumerLoop[${options.consumer}]: invalid schema name "${resolvedSchema}"`);
+            }
+            this.tablePrefix = `"${resolvedSchema}".`;
+        }
+        else {
+            this.tablePrefix = "";
+        }
+        this.subscribedEventTypes = new Set(handlers.map((h) => h.eventType));
+    }
+    /**
+     * Start the polling loop with LISTEN/NOTIFY wake-up. Resolves when
+     * `stop()` is called and the current in-flight batch (if any) finishes
+     * draining; otherwise runs forever.
+     *
+     * The LISTEN connection is best-effort: if it fails to set up or drops
+     * mid-flight, the polling loop still drains at the configured cadence
+     * and reconnect attempts run with backoff. Sub-second wake-up is the
+     * happy path; degraded poll-cadence wake-up is the durable fallback.
+     */
+    async start() {
+        if (this.running) {
+            throw new Error(`ConsumerLoop[${this.options.consumer}]: already running`);
+        }
+        this.running = true;
+        // Kick off the LISTEN connection in the background; do not await so
+        // the polling loop starts immediately whether or not LISTEN comes
+        // up successfully.
+        void this.startListenConnection();
+        while (this.running) {
+            this.inflight = true;
+            try {
+                for (const reg of this.handlers) {
+                    if (!this.running)
+                        break;
+                    await this.processBatchForEventType(reg);
+                }
+            }
+            finally {
+                this.inflight = false;
+            }
+            if (!this.running)
+                break;
+            await this.sleepOrWakeUp(this.options.pollIntervalMs);
+        }
+        await this.stopListenConnection();
+    }
+    /**
+     * Graceful shutdown. Sets the running flag false, wakes the polling
+     * loop early so it exits the current sleep without waiting for the
+     * full poll interval, then waits for the in-flight batch to drain
+     * before resolving. Closes the LISTEN connection on the way out.
+     */
+    async stop() {
+        this.running = false;
+        this.wakeUp();
+        while (this.inflight) {
+            await this.sleep(50);
+        }
+        await this.stopListenConnection();
+        if (this.ownsPool) {
+            await this.pool.end().catch(() => {
+                // Pool may already be closing if Node is shutting down; the
+                // exit handler races with stop(). Swallow so SIGTERM drain
+                // doesn't crash.
+            });
+        }
+    }
+    // =============================================================================
+    // Internal: batch processing
+    // =============================================================================
+    // ===========================================================================
+    // Raw SQL queries. Unqualified table names so the connection's search_path
+    // (derived from the DSN's `?schema=<domain>` query param) resolves to the right
+    // schema. This is what makes the loop work against producer DBs whose
+    // dispatcher tables live in domain-specific schemas (Sales' `sales`,
+    // Growth's `growth`, etc.) — Platform's Prisma client always qualifies
+    // with `public`, which fails against those.
+    // ===========================================================================
+    async getCursorLastSeq(eventType) {
+        const result = await this.pool.query(`SELECT last_seq::text FROM ${this.tablePrefix}dispatcher_cursor
+       WHERE consumer = $1 AND event_type = $2`, [this.options.consumer, eventType]);
+        if (result.rows.length === 0)
+            return 0n;
+        return BigInt(result.rows[0].last_seq);
+    }
+    async findEventsAfter(eventType, afterSeq) {
+        const result = await this.pool.query(`SELECT id, seq::text, event_type, schema_version, tenant_id, producer,
+              subject, actor, occurred_at, payload, correlation_id
+       FROM ${this.tablePrefix}dispatcher_event
+       WHERE event_type = $1 AND seq > $2
+       ORDER BY seq ASC
+       LIMIT $3`, [eventType, afterSeq.toString(), this.options.batchSize]);
+        return result.rows.map((row) => ({
+            id: row.id,
+            seq: BigInt(row.seq),
+            eventType: row.event_type,
+            schemaVersion: row.schema_version,
+            tenantId: row.tenant_id,
+            producer: row.producer,
+            subject: row.subject,
+            actor: row.actor,
+            occurredAt: new Date(row.occurred_at),
+            payload: row.payload,
+            correlationId: row.correlation_id,
+        }));
+    }
+    async getDedupHit(eventId) {
+        const result = await this.pool.query(`SELECT 1 FROM ${this.tablePrefix}dispatcher_dedup
+       WHERE consumer = $1 AND event_id = $2 LIMIT 1`, [this.options.consumer, eventId]);
+        return result.rows.length > 0;
+    }
+    /**
+     * Single-transaction dedup-insert + cursor-advance. The pg.PoolClient
+     * is checked out for the transaction so the BEGIN/COMMIT pair is
+     * scoped to one connection. Errors trigger a ROLLBACK and the loop
+     * retries via the normal retry path.
+     */
+    async commitSuccessfulDelivery(eventId, eventType, seq) {
+        const client = await this.pool.connect();
+        try {
+            await client.query("BEGIN");
+            await client.query(`INSERT INTO ${this.tablePrefix}dispatcher_dedup (consumer, event_id)
+         VALUES ($1, $2)`, [this.options.consumer, eventId]);
+            await client.query(`INSERT INTO ${this.tablePrefix}dispatcher_cursor (consumer, event_type, last_seq, updated_at)
+         VALUES ($1, $2, $3, CURRENT_TIMESTAMP)
+         ON CONFLICT (consumer, event_type)
+         DO UPDATE SET last_seq = EXCLUDED.last_seq, updated_at = CURRENT_TIMESTAMP`, [this.options.consumer, eventType, seq.toString()]);
+            await client.query("COMMIT");
+        }
+        catch (e) {
+            await client.query("ROLLBACK").catch(() => { });
+            throw e;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async commitDeadLetter(eventId, eventType, seq, attemptCount, lastError, envelope) {
+        const client = await this.pool.connect();
+        try {
+            await client.query("BEGIN");
+            await client.query(`INSERT INTO ${this.tablePrefix}dispatcher_dead_letter
+           (id, consumer, event_id, attempt_count, last_error, last_error_stack, envelope_snapshot)
+         VALUES ($1, $2, $3, $4, $5, $6, $7)`, [
+                `${DEAD_LETTER_ID_PREFIX}${(0, id_1.uuidv7)()}`,
+                this.options.consumer,
+                eventId,
+                attemptCount,
+                lastError?.message ?? "unknown error",
+                lastError?.stack ?? null,
+                JSON.stringify(envelope),
+            ]);
+            await client.query(`INSERT INTO ${this.tablePrefix}dispatcher_cursor (consumer, event_type, last_seq, updated_at)
+         VALUES ($1, $2, $3, CURRENT_TIMESTAMP)
+         ON CONFLICT (consumer, event_type)
+         DO UPDATE SET last_seq = EXCLUDED.last_seq, updated_at = CURRENT_TIMESTAMP`, [this.options.consumer, eventType, seq.toString()]);
+            await client.query("COMMIT");
+        }
+        catch (e) {
+            await client.query("ROLLBACK").catch(() => { });
+            throw e;
+        }
+        finally {
+            client.release();
+        }
+    }
+    // ===========================================================================
+    // Batch processing
+    // ===========================================================================
+    async processBatchForEventType(reg) {
+        const lastSeq = await this.getCursorLastSeq(reg.eventType);
+        const events = await this.findEventsAfter(reg.eventType, lastSeq);
+        for (const eventRow of events) {
+            if (!this.running)
+                break;
+            await this.deliverEvent(eventRow, reg.handler);
+        }
+    }
+    async deliverEvent(eventRow, handler) {
+        // Dedup check: if the (consumer, event_id) tuple was already
+        // delivered, skip the handler invocation but still advance the
+        // cursor so a re-dispatched event does not block the queue.
+        if (await this.getDedupHit(eventRow.id)) {
+            (0, observability_1.recordDispatcherIncrement)("dispatcher.dedup_hit.count", {
+                event_type: eventRow.eventType,
+                consumer: this.options.consumer,
+            });
+            console.log(`[${this.options.consumer}] dedup-hit ${eventRow.eventType} ${eventRow.id}`);
+            await this.advanceCursor(eventRow.eventType, eventRow.seq);
+            return;
+        }
+        const envelope = rowToEnvelope(eventRow);
+        const totalAttempts = this.options.retryDelaysMs.length + 1;
+        let lastError = null;
+        let attemptCount = 0;
+        for (let attempt = 0; attempt < totalAttempts; attempt += 1) {
+            attemptCount = attempt + 1;
+            try {
+                const handlerStartedAt = Date.now();
+                await handler(envelope);
+                const handlerLatencyMs = Math.max(0, Date.now() - handlerStartedAt);
+                const endToEndLatencyMs = Math.max(0, Date.now() - eventRow.occurredAt.getTime());
+                await this.commitSuccessfulDelivery(eventRow.id, eventRow.eventType, eventRow.seq);
+                (0, observability_1.recordDispatcherIncrement)("dispatcher.consume.count", {
+                    event_type: eventRow.eventType,
+                    consumer: this.options.consumer,
+                });
+                (0, observability_1.recordDispatcherObservation)("dispatcher.end_to_end_latency_ms", endToEndLatencyMs, {
+                    event_type: eventRow.eventType,
+                    consumer: this.options.consumer,
+                });
+                (0, observability_1.recordDispatcherObservation)("dispatcher.handler_latency_ms", handlerLatencyMs, {
+                    event_type: eventRow.eventType,
+                    consumer: this.options.consumer,
+                });
+                console.log(`[${this.options.consumer}] delivered ${eventRow.eventType} ${eventRow.id} in ${handlerLatencyMs}ms (e2e ${endToEndLatencyMs}ms)`);
+                return;
+            }
+            catch (e) {
+                lastError = e instanceof Error ? e : new Error(String(e));
+                if (attempt < this.options.retryDelaysMs.length) {
+                    const baseDelay = this.options.retryDelaysMs[attempt];
+                    const jitter = Math.random() * 0.3 * baseDelay;
+                    console.warn(`[${this.options.consumer}] retry ${attemptCount}/${totalAttempts} for ${eventRow.eventType} ${eventRow.id} after ${baseDelay}ms: ${lastError.message}`);
+                    await this.sleep(baseDelay + jitter);
+                }
+            }
+        }
+        // Retries exhausted: dead-letter the event and advance the cursor.
+        await this.commitDeadLetter(eventRow.id, eventRow.eventType, eventRow.seq, attemptCount, lastError, envelope);
+        (0, observability_1.recordDispatcherIncrement)("dispatcher.dead_letter.count", {
+            event_type: eventRow.eventType,
+            consumer: this.options.consumer,
+        });
+        console.error(`[${this.options.consumer}] DLQ ${eventRow.eventType} ${eventRow.id} after ${attemptCount} attempts: ${lastError?.message ?? "unknown error"}`);
+    }
+    async advanceCursor(eventType, seq) {
+        await this.pool.query(`INSERT INTO ${this.tablePrefix}dispatcher_cursor (consumer, event_type, last_seq, updated_at)
+       VALUES ($1, $2, $3, CURRENT_TIMESTAMP)
+       ON CONFLICT (consumer, event_type)
+       DO UPDATE SET last_seq = EXCLUDED.last_seq, updated_at = CURRENT_TIMESTAMP`, [this.options.consumer, eventType, seq.toString()]);
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    // =============================================================================
+    // LISTEN/NOTIFY wake-up. The trigger function in Slice 1's migration
+    // fires `pg_notify('dispatcher_event_inserted', NEW.event_type)` on
+    // every insert into dispatcher_event. The consumer LISTENs on that
+    // channel, filters on event_type (only wakes up for event_types it
+    // subscribes to), and aborts the polling sleep so the next batch
+    // runs immediately. Polling cadence is the durable fallback for
+    // missed notifications (LISTEN connection drop, NOTIFY queue
+    // overflow, transient network blip, etc.).
+    // =============================================================================
+    /**
+     * Detect whether a DSN points at a transaction-mode pooler (Supabase's
+     * pgbouncer at port 6543). LISTEN holds a connection open waiting for
+     * NOTIFY; transaction-mode pooling reuses connections across queries
+     * and rejects LISTEN with ENOIDENTIFIER. The fix is to skip the LISTEN
+     * client entirely against pooler URLs and rely on polling. Operators
+     * who want sub-second wake-up can either provide a session-mode URL
+     * (port 5432 / direct connection) via a future databaseUrl override
+     * or run a non-pooler DSN.
+     *
+     * Signal: `pgbouncer=true` query param OR port 6543 anywhere in the
+     * URL. Both are conventions Supabase generates for pooled URLs.
+     */
+    isPoolerDsn(dsn) {
+        return /pgbouncer=true/i.test(dsn) || /:6543\b/.test(dsn);
+    }
+    async startListenConnection() {
+        if (!this.running)
+            return;
+        if (this.listenClient)
+            return; // already connected
+        const databaseUrl = this.databaseUrl;
+        if (!databaseUrl) {
+            // No DSN provisioned means we cannot construct a pg.Client; the
+            // polling loop is the only path. Log and skip; do not throw, so
+            // a misconfigured env still gets degraded-but-correct delivery.
+            // Production deploys MUST set DATABASE_URL (or the producer-specific
+            // DISPATCHER_PRODUCER_DATABASE_URL_<PRODUCER> when this loop reads
+            // a non-self producer); this guard exists for CI and dev-loop edge
+            // cases.
+            console.warn(`ConsumerLoop[${this.options.consumer}]: no DSN provided; LISTEN/NOTIFY wake-up disabled, polling-only fallback active`);
+            return;
+        }
+        if (this.isPoolerDsn(databaseUrl)) {
+            // Transaction-mode pooler can't host a LISTEN socket. Log once at
+            // boot, never schedule a reconnect, drain via polling. The Slice 3
+            // ship memo treats polling as the durable fallback; this just makes
+            // explicit that there's no LISTEN path on this loop.
+            if (this.listenReconnectAttempt === 0) {
+                console.log(`ConsumerLoop[${this.options.consumer}]: DSN is a transaction-mode pooler; LISTEN/NOTIFY skipped, polling at ${this.options.pollIntervalMs}ms`);
+                this.listenReconnectAttempt = 1; // mark as "decided"; suppresses any later reconnect path
+            }
+            return;
+        }
+        const client = new pg_1.Client((0, pg_search_path_1.pgConfigWithSearchPath)(databaseUrl));
+        client.on("notification", (msg) => this.onNotification(msg));
+        client.on("error", (err) => {
+            console.warn(`ConsumerLoop[${this.options.consumer}]: LISTEN connection error: ${err.message}; will reconnect with backoff`);
+            void client.end().catch(() => undefined);
+            this.scheduleListenReconnect();
+        });
+        client.on("end", () => {
+            // Connection closed (server-side timeout, restart, etc.); reconnect
+            // unless we are shutting down.
+            if (this.running) {
+                this.scheduleListenReconnect();
+            }
+        });
+        try {
+            await client.connect();
+            await client.query(`LISTEN ${LISTEN_CHANNEL}`);
+            this.listenClient = client;
+            this.listenReconnectAttempt = 0; // success resets backoff
+        }
+        catch (e) {
+            console.warn(`ConsumerLoop[${this.options.consumer}]: LISTEN setup failed: ${e instanceof Error ? e.message : String(e)}; will reconnect with backoff`);
+            // Best-effort cleanup on the half-connected client
+            try {
+                await client.end();
+            }
+            catch {
+                // ignore
+            }
+            this.scheduleListenReconnect();
+        }
+    }
+    scheduleListenReconnect() {
+        if (!this.running)
+            return;
+        if (this.listenReconnectScheduled)
+            return;
+        this.listenReconnectScheduled = true;
+        this.listenClient = null;
+        const delay = LISTEN_RECONNECT_DELAYS_MS[Math.min(this.listenReconnectAttempt, LISTEN_RECONNECT_DELAYS_MS.length - 1)];
+        this.listenReconnectAttempt += 1;
+        setTimeout(() => {
+            this.listenReconnectScheduled = false;
+            void this.startListenConnection();
+        }, delay).unref();
+    }
+    async stopListenConnection() {
+        const client = this.listenClient;
+        if (!client)
+            return;
+        this.listenClient = null;
+        try {
+            // UNLISTEN is implicit on connection close, but explicit is
+            // clearer for the audit trail in Postgres logs.
+            await client.query(`UNLISTEN ${LISTEN_CHANNEL}`);
+        }
+        catch {
+            // ignore; about to close anyway
+        }
+        try {
+            await client.end();
+        }
+        catch {
+            // ignore
+        }
+    }
+    onNotification(msg) {
+        if (msg.channel !== LISTEN_CHANNEL)
+            return;
+        // Filter on event_type so we only wake up for events this consumer
+        // actually subscribes to. The trigger payload is the event_type
+        // string. NOTIFY payload limit is ~8000 bytes; event_type names are
+        // short, so truncation is not a concern.
+        const eventType = msg.payload ?? "";
+        if (!this.subscribedEventTypes.has(eventType))
+            return;
+        this.wakeUp();
+    }
+    wakeUp() {
+        if (this.sleepAbort) {
+            this.sleepAbort.abort();
+        }
+    }
+    async sleepOrWakeUp(ms) {
+        this.sleepAbort = new AbortController();
+        const signal = this.sleepAbort.signal;
+        try {
+            await new Promise((resolve) => {
+                const timeout = setTimeout(resolve, ms);
+                signal.addEventListener("abort", () => {
+                    clearTimeout(timeout);
+                    resolve();
+                }, { once: true });
+            });
+        }
+        finally {
+            this.sleepAbort = null;
+        }
+    }
+}
+exports.ConsumerLoop = ConsumerLoop;
+function rowToEnvelope(row) {
+    // Reconstruct the envelope from the persisted row. The shape mirrors
+    // the producer's published envelope exactly so the handler sees the
+    // same object the producer intended.
+    const envelope = {
+        event_id: row.id,
+        event_type: row.eventType,
+        occurred_at: row.occurredAt.toISOString(),
+        tenant_id: row.tenantId,
+        producer: row.producer,
+        schema_version: row.schemaVersion,
+        payload: row.payload,
+    };
+    if (row.subject !== null) {
+        envelope.subject = row.subject;
+    }
+    if (row.actor) {
+        envelope.actor = row.actor;
+    }
+    if (row.correlationId !== null) {
+        envelope.correlation_id = row.correlationId;
+    }
+    return envelope;
+}

package/dist/postgres-transport.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Postgres-queue transport for the dispatcher SDK.
+ *
+ * Implements the publish-side path of the bus dispatcher per ADR-0009
+ * §"Decision". The producer-side transactional guarantee is the
+ * load-bearing primitive: producers call `dispatcher.publish` inside a
+ * Prisma transaction, the SDK inserts the event row in the SAME
+ * transaction (via the `tx` argument), and either both the domain write
+ * and the event emit commit or both roll back. No outbox pattern, no
+ * staging table, no second state machine to debug; this is the property
+ * that breaks the tie among the four bus options ADR-0009 considered.
+ *
+ * Phase 2 Slice 2 (this file): publish path. Slice 3 lands the consumer
+ * polling worker plus LISTEN/NOTIFY listener; Slice 4 wires this into
+ * `dispatcher.ts`'s public surface (replacing the
+ * DispatcherNotImplementedError stubs); Slice 5 ships the per-consumer
+ * DLQ read API.
+ *
+ * Usage shape producers will adopt at their state-transition call sites:
+ *
+ *   await prisma.$transaction(async (tx) => {
+ *     // ... domain write that produces the event ...
+ *     await tx.creditReservation.update({ where: { id }, data: { state: "locked" } });
+ *
+ *     // ... emit the event in the SAME transaction ...
+ *     await dispatcher.publish({
+ *       event_type: "credit.locked",
+ *       payload: { credit_reservation_id: id, ... },
+ *       subject: personId,
+ *       actor: "system:revenue",
+ *     }, { tx });
+ *   });
+ *
+ * Without the `tx` option, publish runs in its own transaction off the
+ * default Prisma client. That's the right shape for emit paths that have
+ * no domain write to coordinate with (e.g., a periodic job that emits a
+ * status event); it preserves the at-most-once-insert semantics but
+ * without coupling to a domain write.
+ */
+import type { Prisma } from "@prisma/client";
+import type { EventEmit, PublishResult } from "./types";
+/**
+ * ID prefix for envelope event_id values per envelope contract §4.1
+ * and ADR-0002. `evt_<UUID v7 canonical>` is the canonical shape.
+ */
+export declare const EVENT_ID_PREFIX = "evt_";
+export type PublishOptions = {
+    /**
+     * Optional Prisma interactive-transaction client. When supplied, the
+     * SDK inserts the event row in the same transaction as the caller's
+     * domain write, giving the producer-transactional-guarantee shape
+     * ADR-0009 §"Producer transactional guarantee" describes. When
+     * omitted, the SDK uses the default Prisma client and the insert
+     * runs in its own transaction.
+     */
+    tx?: Prisma.TransactionClient;
+};
+/**
+ * Publish an event to the Postgres-queue transport. Returns the canonical
+ * event_id so the producer can correlate retries per envelope contract
+ * §10.6 (producers SHALL reuse the same event_id on retry so consumer
+ * dedup works).
+ *
+ * Validation order: registry lookup → schema_version resolution →
+ * envelope construction → envelope JSON Schema validation → payload
+ * validation → INSERT. A failure at any step throws before the row
+ * lands, so the dispatcher_event table never carries unschema'd or
+ * unregistered events.
+ */
+export declare function publishToPostgres<TPayload>(emit: EventEmit<TPayload>, options?: PublishOptions): Promise<PublishResult>;