@sguild/dispatcher 2.0.0

package/dist/inbox.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyInboxRequest = verifyInboxRequest;
+exports.tryInsertOrDetectConflict = tryInsertOrDetectConflict;
+const signature_1 = require("./signature");
+/**
+ * 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).
+ */
+function verifyInboxRequest(rawBody, headers, secret) {
+    const signature = headers.get(signature_1.SIGNATURE_HEADER);
+    if (!signature) {
+        return {
+            ok: false,
+            status: 400,
+            reason: `missing ${signature_1.SIGNATURE_HEADER} header`,
+        };
+    }
+    if (!(0, signature_1.verifyEnvelopeSignature)(rawBody, secret, signature)) {
+        return { ok: false, status: 401, reason: "invalid HMAC signature" };
+    }
+    let envelope;
+    try {
+        envelope = JSON.parse(rawBody);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            status: 400,
+            reason: `request body is not valid JSON: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+    if (typeof envelope.event_id !== "string" || envelope.event_id.length === 0) {
+        return { ok: false, status: 400, reason: "envelope missing event_id" };
+    }
+    if (typeof envelope.event_type !== "string" || envelope.event_type.length === 0) {
+        return { ok: false, status: 400, reason: "envelope missing event_type" };
+    }
+    return { ok: true, envelope, rawBody };
+}
+/**
+ * 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 });
+ */
+async function tryInsertOrDetectConflict(insert) {
+    try {
+        await insert();
+        return "first_time";
+    }
+    catch (e) {
+        const code = e?.code;
+        if (code === "P2002")
+            return "already_processed";
+        throw e;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Dispatcher SDK public surface.
+ *
+ * Domain code imports from `@/lib/dispatcher`, never from the internal
+ * files directly. The barrel re-exports the singleton dispatcher, the
+ * envelope types, the registry query functions, the runtime config
+ * helpers, the publish/consumer option shapes, and the error classes
+ * callers may need to handle.
+ *
+ * Internal files (transport implementations, dedup tracking, registry
+ * cache management, validator internals) are not re-exported. The narrow
+ * public surface keeps domains from depending on internal layout that
+ * may change as the remaining Slice 3b through Slice 5 land.
+ *
+ * Phase 2 status: see ./README.md for what's implemented and what's
+ * pending. publish wires to the Postgres-queue transport; subscribe +
+ * start + stop wire the polling worker; LISTEN/NOTIFY wake-up
+ * (Slice 3b) and the per-consumer DLQ read API (Slice 5) remain.
+ */
+export { dispatcher } from "./dispatcher";
+export { DispatcherNotImplementedError, UnregisteredEventTypeError, UnregisteredSchemaVersionError, } from "./dispatcher";
+export { configureDispatcher, type DispatcherConfig, } from "./config";
+export type { PublishOptions } from "./postgres-transport";
+export type { ConsumerLoopOptions } from "./postgres-consumer";
+export { EnvelopeValidationError, PayloadValidationError, PayloadSchemaUnavailableError, } from "./validator";
+export { DeadLetterAlreadyResolvedError, DeadLetterNotFoundError, ProducerDbNotConfiguredError, ReplayConsumerUnknownError, ReplayDeliveryFailedError, getDeadLetter, knownProducers, listDeadLetters, replayDeadLetter, resolveDeadLetter, } from "./dlq";
+export type { DeadLetter, GetDeadLetterOptions, ListDeadLettersFilter, ReplayDeadLetterInput, ReplayDeadLetterOutcome, ResolveDeadLetterInput, } from "./dlq";
+export { configureDispatcherObservability, resetDispatcherObservabilityForTests, } from "./observability";
+export type { DispatcherHistogramName, DispatcherMetricLabels, DispatcherMetricName, DispatcherObservabilityHooks, } from "./observability";
+export type { ActorRef, CanonicalEntityId, EventEmit, EventEnvelope, LiveProducerDomain, ProducerDomain, PublishResult, SubscribeHandler, } from "./types";
+export { getActiveSchemaVersion, getEventTypeRegistration, loadRegistry, } from "./registry";
+export type { EventTypeRegistration, RegistryManifest, SchemaVersionEntry, SchemaVersionStatus, } from "./registry";
+export { tryInsertOrDetectConflict, verifyInboxRequest, } from "./inbox";
+export type { DedupAttempt, DedupOutcome, InboxVerificationResult, } from "./inbox";
+export { EVENT_ID_HEADER, EVENT_TYPE_HEADER, SIGNATURE_HEADER, signEnvelope, verifyEnvelopeSignature, } from "./signature";
+export { WebhookDispatchError } from "./fanout";

package/dist/index.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Dispatcher SDK public surface.
+ *
+ * Domain code imports from `@/lib/dispatcher`, never from the internal
+ * files directly. The barrel re-exports the singleton dispatcher, the
+ * envelope types, the registry query functions, the runtime config
+ * helpers, the publish/consumer option shapes, and the error classes
+ * callers may need to handle.
+ *
+ * Internal files (transport implementations, dedup tracking, registry
+ * cache management, validator internals) are not re-exported. The narrow
+ * public surface keeps domains from depending on internal layout that
+ * may change as the remaining Slice 3b through Slice 5 land.
+ *
+ * Phase 2 status: see ./README.md for what's implemented and what's
+ * pending. publish wires to the Postgres-queue transport; subscribe +
+ * start + stop wire the polling worker; LISTEN/NOTIFY wake-up
+ * (Slice 3b) and the per-consumer DLQ read API (Slice 5) remain.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookDispatchError = exports.verifyEnvelopeSignature = exports.signEnvelope = exports.SIGNATURE_HEADER = exports.EVENT_TYPE_HEADER = exports.EVENT_ID_HEADER = exports.verifyInboxRequest = exports.tryInsertOrDetectConflict = exports.loadRegistry = exports.getEventTypeRegistration = exports.getActiveSchemaVersion = exports.resetDispatcherObservabilityForTests = exports.configureDispatcherObservability = exports.resolveDeadLetter = exports.replayDeadLetter = exports.listDeadLetters = exports.knownProducers = exports.getDeadLetter = exports.ReplayDeliveryFailedError = exports.ReplayConsumerUnknownError = exports.ProducerDbNotConfiguredError = exports.DeadLetterNotFoundError = exports.DeadLetterAlreadyResolvedError = exports.PayloadSchemaUnavailableError = exports.PayloadValidationError = exports.EnvelopeValidationError = exports.configureDispatcher = exports.UnregisteredSchemaVersionError = exports.UnregisteredEventTypeError = exports.DispatcherNotImplementedError = exports.dispatcher = void 0;
+var dispatcher_1 = require("./dispatcher");
+Object.defineProperty(exports, "dispatcher", { enumerable: true, get: function () { return dispatcher_1.dispatcher; } });
+var dispatcher_2 = require("./dispatcher");
+Object.defineProperty(exports, "DispatcherNotImplementedError", { enumerable: true, get: function () { return dispatcher_2.DispatcherNotImplementedError; } });
+Object.defineProperty(exports, "UnregisteredEventTypeError", { enumerable: true, get: function () { return dispatcher_2.UnregisteredEventTypeError; } });
+Object.defineProperty(exports, "UnregisteredSchemaVersionError", { enumerable: true, get: function () { return dispatcher_2.UnregisteredSchemaVersionError; } });
+var config_1 = require("./config");
+Object.defineProperty(exports, "configureDispatcher", { enumerable: true, get: function () { return config_1.configureDispatcher; } });
+var validator_1 = require("./validator");
+Object.defineProperty(exports, "EnvelopeValidationError", { enumerable: true, get: function () { return validator_1.EnvelopeValidationError; } });
+Object.defineProperty(exports, "PayloadValidationError", { enumerable: true, get: function () { return validator_1.PayloadValidationError; } });
+Object.defineProperty(exports, "PayloadSchemaUnavailableError", { enumerable: true, get: function () { return validator_1.PayloadSchemaUnavailableError; } });
+var dlq_1 = require("./dlq");
+Object.defineProperty(exports, "DeadLetterAlreadyResolvedError", { enumerable: true, get: function () { return dlq_1.DeadLetterAlreadyResolvedError; } });
+Object.defineProperty(exports, "DeadLetterNotFoundError", { enumerable: true, get: function () { return dlq_1.DeadLetterNotFoundError; } });
+Object.defineProperty(exports, "ProducerDbNotConfiguredError", { enumerable: true, get: function () { return dlq_1.ProducerDbNotConfiguredError; } });
+Object.defineProperty(exports, "ReplayConsumerUnknownError", { enumerable: true, get: function () { return dlq_1.ReplayConsumerUnknownError; } });
+Object.defineProperty(exports, "ReplayDeliveryFailedError", { enumerable: true, get: function () { return dlq_1.ReplayDeliveryFailedError; } });
+Object.defineProperty(exports, "getDeadLetter", { enumerable: true, get: function () { return dlq_1.getDeadLetter; } });
+Object.defineProperty(exports, "knownProducers", { enumerable: true, get: function () { return dlq_1.knownProducers; } });
+Object.defineProperty(exports, "listDeadLetters", { enumerable: true, get: function () { return dlq_1.listDeadLetters; } });
+Object.defineProperty(exports, "replayDeadLetter", { enumerable: true, get: function () { return dlq_1.replayDeadLetter; } });
+Object.defineProperty(exports, "resolveDeadLetter", { enumerable: true, get: function () { return dlq_1.resolveDeadLetter; } });
+var observability_1 = require("./observability");
+Object.defineProperty(exports, "configureDispatcherObservability", { enumerable: true, get: function () { return observability_1.configureDispatcherObservability; } });
+Object.defineProperty(exports, "resetDispatcherObservabilityForTests", { enumerable: true, get: function () { return observability_1.resetDispatcherObservabilityForTests; } });
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "getActiveSchemaVersion", { enumerable: true, get: function () { return registry_1.getActiveSchemaVersion; } });
+Object.defineProperty(exports, "getEventTypeRegistration", { enumerable: true, get: function () { return registry_1.getEventTypeRegistration; } });
+Object.defineProperty(exports, "loadRegistry", { enumerable: true, get: function () { return registry_1.loadRegistry; } });
+// Inbox helpers consumed by domain webhook endpoints (verify HMAC,
+// dedup on event_id). Platform-side fanout machinery is internal and
+// not re-exported here; instrumentation.ts imports it directly from
+// ./fanout.
+var inbox_1 = require("./inbox");
+Object.defineProperty(exports, "tryInsertOrDetectConflict", { enumerable: true, get: function () { return inbox_1.tryInsertOrDetectConflict; } });
+Object.defineProperty(exports, "verifyInboxRequest", { enumerable: true, get: function () { return inbox_1.verifyInboxRequest; } });
+// HMAC sign/verify primitives live in signature.ts (low-dep, vendorable
+// stand-alone). The fanout module re-exports them for legacy imports;
+// new code imports from the canonical here.
+var signature_1 = require("./signature");
+Object.defineProperty(exports, "EVENT_ID_HEADER", { enumerable: true, get: function () { return signature_1.EVENT_ID_HEADER; } });
+Object.defineProperty(exports, "EVENT_TYPE_HEADER", { enumerable: true, get: function () { return signature_1.EVENT_TYPE_HEADER; } });
+Object.defineProperty(exports, "SIGNATURE_HEADER", { enumerable: true, get: function () { return signature_1.SIGNATURE_HEADER; } });
+Object.defineProperty(exports, "signEnvelope", { enumerable: true, get: function () { return signature_1.signEnvelope; } });
+Object.defineProperty(exports, "verifyEnvelopeSignature", { enumerable: true, get: function () { return signature_1.verifyEnvelopeSignature; } });
+var fanout_1 = require("./fanout");
+Object.defineProperty(exports, "WebhookDispatchError", { enumerable: true, get: function () { return fanout_1.WebhookDispatchError; } });

package/dist/internal/id.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Canonical entity ID generation per ADR-0002.
+ *
+ * Vendored into the dispatcher SDK so the published `@sguild/dispatcher`
+ * package carries no dependency on the platform repo's `lib/id.ts`. Kept
+ * byte-for-byte in step with that source; if the canonical implementation
+ * changes, re-sync this copy. The implementation is dependency-free (only
+ * `node:crypto`) per RFC 9562 §5.7, so vendoring is a literal copy.
+ *
+ * The dispatcher uses `uuidv7()` for envelope `event_id` values and
+ * dead-letter row ids; `prefixedId` and `isUuidV7` are carried for parity
+ * with the source module and may be used by future SDK code.
+ */
+/**
+ * Generate a UUID v7 in canonical form per RFC 9562 §5.7.
+ *
+ * Layout:
+ * - 48 bits: Unix timestamp in milliseconds, big-endian (bytes 0-5)
+ * - 4 bits: version (set to `0111` = 7) (high nibble of byte 6)
+ * - 12 bits: random data (low nibble of byte 6 + byte 7)
+ * - 2 bits: variant (set to `10`) (high two bits of byte 8)
+ * - 62 bits: random data (remaining 62 bits)
+ *
+ * The timestamp prefix gives lexicographic sort order matching insertion
+ * order, which is the property that makes v7 valuable for database keys.
+ *
+ * @returns A 36-character UUID string in the canonical 8-4-4-4-12 form.
+ */
+export declare function uuidv7(): string;
+/**
+ * Generate a prefixed canonical entity ID per ADR-0002. Convenience wrapper
+ * that combines `uuidv7()` with the prefix.
+ *
+ * @example
+ *   prefixedId("per_") // "per_018f3c2d-4a5b-7c8d-9e0f-1a2b3c4d5e6f"
+ */
+export declare function prefixedId(prefix: string): string;
+export declare function isUuidV7(value: string): boolean;

package/dist/internal/id.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Canonical entity ID generation per ADR-0002.
+ *
+ * Vendored into the dispatcher SDK so the published `@sguild/dispatcher`
+ * package carries no dependency on the platform repo's `lib/id.ts`. Kept
+ * byte-for-byte in step with that source; if the canonical implementation
+ * changes, re-sync this copy. The implementation is dependency-free (only
+ * `node:crypto`) per RFC 9562 §5.7, so vendoring is a literal copy.
+ *
+ * The dispatcher uses `uuidv7()` for envelope `event_id` values and
+ * dead-letter row ids; `prefixedId` and `isUuidV7` are carried for parity
+ * with the source module and may be used by future SDK code.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uuidv7 = uuidv7;
+exports.prefixedId = prefixedId;
+exports.isUuidV7 = isUuidV7;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Generate a UUID v7 in canonical form per RFC 9562 §5.7.
+ *
+ * Layout:
+ * - 48 bits: Unix timestamp in milliseconds, big-endian (bytes 0-5)
+ * - 4 bits: version (set to `0111` = 7) (high nibble of byte 6)
+ * - 12 bits: random data (low nibble of byte 6 + byte 7)
+ * - 2 bits: variant (set to `10`) (high two bits of byte 8)
+ * - 62 bits: random data (remaining 62 bits)
+ *
+ * The timestamp prefix gives lexicographic sort order matching insertion
+ * order, which is the property that makes v7 valuable for database keys.
+ *
+ * @returns A 36-character UUID string in the canonical 8-4-4-4-12 form.
+ */
+function uuidv7() {
+    const timestamp = BigInt(Date.now());
+    const bytes = new Uint8Array(16);
+    // Bytes 0-5: 48-bit timestamp, big-endian.
+    bytes[0] = Number((timestamp >> 40n) & 0xffn);
+    bytes[1] = Number((timestamp >> 32n) & 0xffn);
+    bytes[2] = Number((timestamp >> 24n) & 0xffn);
+    bytes[3] = Number((timestamp >> 16n) & 0xffn);
+    bytes[4] = Number((timestamp >> 8n) & 0xffn);
+    bytes[5] = Number(timestamp & 0xffn);
+    // Bytes 6-15: 80 bits of random data (we'll then overlay version + variant).
+    const rand = (0, node_crypto_1.randomBytes)(10);
+    for (let i = 0; i < 10; i++) {
+        bytes[6 + i] = rand[i];
+    }
+    // Set version bits (high nibble of byte 6 to 0111 = 7).
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+    // Set variant bits (high two bits of byte 8 to 10).
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    // Format as canonical UUID string (8-4-4-4-12).
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+/**
+ * Generate a prefixed canonical entity ID per ADR-0002. Convenience wrapper
+ * that combines `uuidv7()` with the prefix.
+ *
+ * @example
+ *   prefixedId("per_") // "per_018f3c2d-4a5b-7c8d-9e0f-1a2b3c4d5e6f"
+ */
+function prefixedId(prefix) {
+    if (!prefix.endsWith("_")) {
+        throw new Error(`prefixedId: prefix '${prefix}' must end with '_' per ADR-0002`);
+    }
+    return `${prefix}${uuidv7()}`;
+}
+/**
+ * Validate the canonical UUID v7 form (lowercase hex, dashed, version
+ * nibble = 7, variant nibble = 8/9/a/b). Useful at storage boundaries.
+ */
+const UUID_V7_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+function isUuidV7(value) {
+    return UUID_V7_PATTERN.test(value);
+}

package/dist/internal/pg-search-path.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Postgres search_path config helper.
+ *
+ * Vendored into the dispatcher SDK so the published `@sguild/dispatcher`
+ * package carries no dependency on the platform repo's
+ * `lib/db/pg-search-path.ts`. Kept byte-for-byte in step with that source;
+ * the implementation is dependency-free (only the WHATWG `URL`), so
+ * vendoring is a literal copy.
+ *
+ * Prisma treats `?schema=<name>` in a Postgres URL as the target schema.
+ * node-postgres does not. Dispatcher consumers use raw pg pools so they can
+ * poll producer schemas without Prisma's generated schema qualification, so
+ * they must translate Prisma's URL convention into Postgres search_path.
+ *
+ * Caveat: Supabase's pgbouncer at port 6543 (transaction-mode pooling) silently
+ * drops the `options` startup parameter. Setting search_path via the libpq
+ * `options=-c search_path=...` mechanism does not survive the pooler. The
+ * options field stays here for direct-connection (port 5432) callers, but the
+ * caller MUST NOT rely on it alone — for pooler DSNs, schema-qualify the SQL
+ * queries explicitly using the `schema` field returned here.
+ */
+export type PgSearchPathConfig = {
+    connectionString: string | undefined;
+    /** libpq startup options. Effective on direct connections; dropped by pgbouncer. */
+    options?: string;
+    /**
+     * The schema name parsed from the DSN's `?schema=<name>` query param.
+     * Null if absent or `public`. Callers schema-qualify their SQL with this
+     * value (e.g., `"${schema}".dispatcher_cursor`) so the query works regardless
+     * of whether the pooler dropped the search_path option.
+     */
+    schema: string | null;
+};
+export declare function pgConfigWithSearchPath(connectionString: string | undefined): PgSearchPathConfig;

package/dist/internal/pg-search-path.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Postgres search_path config helper.
+ *
+ * Vendored into the dispatcher SDK so the published `@sguild/dispatcher`
+ * package carries no dependency on the platform repo's
+ * `lib/db/pg-search-path.ts`. Kept byte-for-byte in step with that source;
+ * the implementation is dependency-free (only the WHATWG `URL`), so
+ * vendoring is a literal copy.
+ *
+ * Prisma treats `?schema=<name>` in a Postgres URL as the target schema.
+ * node-postgres does not. Dispatcher consumers use raw pg pools so they can
+ * poll producer schemas without Prisma's generated schema qualification, so
+ * they must translate Prisma's URL convention into Postgres search_path.
+ *
+ * Caveat: Supabase's pgbouncer at port 6543 (transaction-mode pooling) silently
+ * drops the `options` startup parameter. Setting search_path via the libpq
+ * `options=-c search_path=...` mechanism does not survive the pooler. The
+ * options field stays here for direct-connection (port 5432) callers, but the
+ * caller MUST NOT rely on it alone — for pooler DSNs, schema-qualify the SQL
+ * queries explicitly using the `schema` field returned here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pgConfigWithSearchPath = pgConfigWithSearchPath;
+function pgConfigWithSearchPath(connectionString) {
+    if (!connectionString) {
+        return { connectionString, schema: null };
+    }
+    const schema = readSchemaParam(connectionString);
+    if (!schema) {
+        return { connectionString, schema: null };
+    }
+    return {
+        connectionString,
+        options: `-c search_path=${[schema, "public", "extensions"].join(",")}`,
+        schema,
+    };
+}
+function readSchemaParam(connectionString) {
+    let url;
+    try {
+        url = new URL(connectionString);
+    }
+    catch {
+        return null;
+    }
+    const schema = url.searchParams.get("schema")?.trim();
+    if (!schema || schema === "public") {
+        return null;
+    }
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(schema)) {
+        throw new Error(`Invalid Postgres schema name in connection URL: ${schema}`);
+    }
+    return schema;
+}

package/dist/internal/resolve-contract-path.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Resolve a path inside the bundled contracts tree to an absolute path.
+ *
+ * The dispatcher SDK ships the contracts tree (`contracts/`) bundled inside
+ * the `@sguild/dispatcher` package so the registry manifest and the JSON
+ * Schemas are available at runtime with no dependency on a sibling
+ * coordination repo.
+ *
+ * `contractsRelPath` is a path rooted at `contracts/` exactly as the
+ * coordination repo stores it (e.g. `contracts/event-types-registry.json`,
+ * or a registry `payload_schema` value like
+ * `contracts/<contract>/schema/payloads/<event_type>-v<n>.json`).
+ *
+ * Resolution order (first existing path wins):
+ *
+ *   1. `priorityPaths` — explicit caller overrides and test fixtures,
+ *      resolved against the process cwd (absolute paths pass through).
+ *   2. Module-relative — `moduleDir` (the caller's `__dirname`) plus the
+ *      relative path, and one level up. Reliable under plain Node / tsx,
+ *      which is how the consumer-side subscriber worker runs.
+ *   3. cwd-relative defaults — covers the cases where `__dirname` is
+ *      unreliable because a bundler (e.g. Next.js) rewrote it in a server
+ *      bundle. `lib/dispatcher/<rel>` is the in-platform-repo source
+ *      layout; `node_modules/@sguild/dispatcher/<rel>` is the published
+ *      package; `../coordination/<rel>` is a sibling coordination repo.
+ *   4. `fallbackPaths` — last-resort caller overrides.
+ *
+ * Note for consumers whose producer path runs inside a bundled server
+ * (Next.js route handlers): ensure the deploy ships the package's
+ * `contracts/` directory. Next.js does not trace `readFileSync` data files
+ * automatically; add `node_modules/@sguild/dispatcher/contracts/**` to
+ * `outputFileTracingIncludes` (or equivalent) so the cwd-relative
+ * `node_modules/@sguild/dispatcher` candidate resolves at runtime.
+ */
+export type ResolveContractPathOptions = {
+    /** Tried before any default location. Explicit caller overrides, test fixtures. */
+    priorityPaths?: string[];
+    /** Tried after all default locations. Last-resort caller overrides. */
+    fallbackPaths?: string[];
+};
+export declare function resolveContractPath(moduleDir: string, contractsRelPath: string, options?: ResolveContractPathOptions): string;

package/dist/internal/resolve-contract-path.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Resolve a path inside the bundled contracts tree to an absolute path.
+ *
+ * The dispatcher SDK ships the contracts tree (`contracts/`) bundled inside
+ * the `@sguild/dispatcher` package so the registry manifest and the JSON
+ * Schemas are available at runtime with no dependency on a sibling
+ * coordination repo.
+ *
+ * `contractsRelPath` is a path rooted at `contracts/` exactly as the
+ * coordination repo stores it (e.g. `contracts/event-types-registry.json`,
+ * or a registry `payload_schema` value like
+ * `contracts/<contract>/schema/payloads/<event_type>-v<n>.json`).
+ *
+ * Resolution order (first existing path wins):
+ *
+ *   1. `priorityPaths` — explicit caller overrides and test fixtures,
+ *      resolved against the process cwd (absolute paths pass through).
+ *   2. Module-relative — `moduleDir` (the caller's `__dirname`) plus the
+ *      relative path, and one level up. Reliable under plain Node / tsx,
+ *      which is how the consumer-side subscriber worker runs.
+ *   3. cwd-relative defaults — covers the cases where `__dirname` is
+ *      unreliable because a bundler (e.g. Next.js) rewrote it in a server
+ *      bundle. `lib/dispatcher/<rel>` is the in-platform-repo source
+ *      layout; `node_modules/@sguild/dispatcher/<rel>` is the published
+ *      package; `../coordination/<rel>` is a sibling coordination repo.
+ *   4. `fallbackPaths` — last-resort caller overrides.
+ *
+ * Note for consumers whose producer path runs inside a bundled server
+ * (Next.js route handlers): ensure the deploy ships the package's
+ * `contracts/` directory. Next.js does not trace `readFileSync` data files
+ * automatically; add `node_modules/@sguild/dispatcher/contracts/**` to
+ * `outputFileTracingIncludes` (or equivalent) so the cwd-relative
+ * `node_modules/@sguild/dispatcher` candidate resolves at runtime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveContractPath = resolveContractPath;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * cwd-relative base directories the bundled contracts tree may live under,
+ * tried after the module-relative candidates.
+ */
+const CWD_RELATIVE_BASES = [
+    "lib/dispatcher", // in-platform-repo source consumption
+    "node_modules/@sguild/dispatcher", // published-package consumption
+    "../coordination", // checkout with a sibling coordination repo
+];
+function resolveContractPath(moduleDir, contractsRelPath, options = {}) {
+    const priorityPaths = options.priorityPaths ?? [];
+    const candidates = [
+        ...priorityPaths.map((p) => (0, node_path_1.resolve)(process.cwd(), p)),
+        (0, node_path_1.join)(moduleDir, contractsRelPath), // in-repo source layout
+        (0, node_path_1.join)(moduleDir, "..", contractsRelPath), // published dist/ layout
+        ...CWD_RELATIVE_BASES.map((base) => (0, node_path_1.resolve)(process.cwd(), base, contractsRelPath)),
+        ...(options.fallbackPaths ?? []).map((p) => (0, node_path_1.resolve)(process.cwd(), p)),
+    ];
+    for (const candidate of candidates) {
+        if ((0, node_fs_1.existsSync)(candidate))
+            return candidate;
+    }
+    // Nothing matched; return the first module-relative candidate so the
+    // caller's readFileSync throws an error naming the expected location.
+    return candidates[priorityPaths.length];
+}

package/dist/observability.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Dispatcher observability hooks.
+ *
+ * Phase 3 intentionally exposes a small adapter rather than binding the
+ * SDK to a metrics vendor. Deployments can bridge these hooks to
+ * Prometheus, OpenTelemetry, Datadog, logs, or a domain-local test probe.
+ * The dispatcher never lets hook failures affect delivery.
+ */
+export type DispatcherMetricName = "dispatcher.publish.count" | "dispatcher.consume.count" | "dispatcher.dedup_hit.count" | "dispatcher.dead_letter.count";
+export type DispatcherHistogramName = "dispatcher.end_to_end_latency_ms" | "dispatcher.handler_latency_ms";
+export type DispatcherMetricLabels = {
+    event_type: string;
+    consumer?: string;
+    producer?: string;
+    schema_version?: string;
+};
+export type DispatcherObservabilityHooks = {
+    increment?: (name: DispatcherMetricName, value: number, labels: DispatcherMetricLabels) => void;
+    observe?: (name: DispatcherHistogramName, valueMs: number, labels: DispatcherMetricLabels) => void;
+};
+export declare function configureDispatcherObservability(next: DispatcherObservabilityHooks): void;
+export declare function resetDispatcherObservabilityForTests(): void;
+export declare function recordDispatcherIncrement(name: DispatcherMetricName, labels: DispatcherMetricLabels, value?: number): void;
+export declare function recordDispatcherObservation(name: DispatcherHistogramName, valueMs: number, labels: DispatcherMetricLabels): void;

package/dist/observability.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Dispatcher observability hooks.
+ *
+ * Phase 3 intentionally exposes a small adapter rather than binding the
+ * SDK to a metrics vendor. Deployments can bridge these hooks to
+ * Prometheus, OpenTelemetry, Datadog, logs, or a domain-local test probe.
+ * The dispatcher never lets hook failures affect delivery.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureDispatcherObservability = configureDispatcherObservability;
+exports.resetDispatcherObservabilityForTests = resetDispatcherObservabilityForTests;
+exports.recordDispatcherIncrement = recordDispatcherIncrement;
+exports.recordDispatcherObservation = recordDispatcherObservation;
+let hooks = {};
+function configureDispatcherObservability(next) {
+    hooks = next;
+}
+function resetDispatcherObservabilityForTests() {
+    hooks = {};
+}
+function recordDispatcherIncrement(name, labels, value = 1) {
+    try {
+        hooks.increment?.(name, value, labels);
+    }
+    catch (e) {
+        console.warn(`dispatcher observability increment hook failed for ${name}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+function recordDispatcherObservation(name, valueMs, labels) {
+    try {
+        hooks.observe?.(name, valueMs, labels);
+    }
+    catch (e) {
+        console.warn(`dispatcher observability observe hook failed for ${name}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}