@sguild/dispatcher 2.0.0

package/dist/postgres-transport.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_ID_PREFIX = void 0;
+exports.publishToPostgres = publishToPostgres;
+const id_1 = require("./internal/id");
+const config_1 = require("./config");
+const dispatcher_errors_1 = require("./dispatcher-errors");
+const observability_1 = require("./observability");
+const registry_1 = require("./registry");
+const validator_1 = require("./validator");
+/**
+ * ID prefix for envelope event_id values per envelope contract §4.1
+ * and ADR-0002. `evt_<UUID v7 canonical>` is the canonical shape.
+ */
+exports.EVENT_ID_PREFIX = "evt_";
+/**
+ * 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.
+ */
+async function publishToPostgres(emit, options = {}) {
+    // 1. Registry lookup.
+    const registration = (0, registry_1.getEventTypeRegistration)(emit.event_type);
+    if (!registration) {
+        throw new dispatcher_errors_1.UnregisteredEventTypeError(emit.event_type);
+    }
+    // 2. Schema_version resolution. Caller-supplied wins; fall back to
+    //    the active version registered for this event_type.
+    const targetVersion = emit.schema_version ?? (0, registry_1.getActiveSchemaVersion)(emit.event_type)?.version ?? null;
+    if (targetVersion === null) {
+        throw new dispatcher_errors_1.UnregisteredSchemaVersionError(emit.event_type, null);
+    }
+    const versionEntry = registration.schema_versions.find((v) => v.version === targetVersion);
+    if (!versionEntry) {
+        throw new dispatcher_errors_1.UnregisteredSchemaVersionError(emit.event_type, targetVersion);
+    }
+    // 3. Envelope construction. Auto-populate the SDK-controlled fields
+    //    per envelope contract §10.2; producer supplies the rest.
+    const config = (0, config_1.getDispatcherConfig)();
+    const envelope = {
+        event_id: `${exports.EVENT_ID_PREFIX}${(0, id_1.uuidv7)()}`,
+        event_type: emit.event_type,
+        occurred_at: new Date().toISOString(),
+        tenant_id: config.tenantId,
+        producer: config.producer,
+        schema_version: targetVersion,
+        payload: emit.payload,
+        ...(emit.subject ? { subject: emit.subject } : {}),
+        ...(emit.actor ? { actor: emit.actor } : {}),
+        ...(emit.correlation_id ? { correlation_id: emit.correlation_id } : {}),
+    };
+    // 4. Envelope JSON Schema validation. Catches shape errors at the
+    //    SDK boundary, before the row hits the table.
+    (0, validator_1.validateEnvelope)(envelope);
+    // 5. Payload JSON Schema validation. Per ADR-0009 action item 8:
+    //    every emit validates against the registered schema for the
+    //    (event_type, schema_version) tuple. Skip if the registry has no
+    //    payload_schema recorded; the registry-hygiene story per the
+    //    Phase 0 wrap is that authorship belongs to the owning domain
+    //    and pending entries are not yet validate-blocking.
+    if (versionEntry.payload_schema !== null) {
+        (0, validator_1.validatePayload)(emit.event_type, targetVersion, emit.payload);
+    }
+    // 6. INSERT into dispatcher_event using the caller's tx if supplied,
+    //    otherwise the Prisma client injected at startup via
+    //    configureDispatcher({ prismaClient }). The same-transaction insert
+    //    is the producer-transactional-guarantee primitive ADR-0009 chose
+    //    Postgres for. The SDK does not import any domain's generated client
+    //    directly; the consuming domain injects its own (@prisma/client is a
+    //    peer dependency).
+    const db = options.tx ?? config.prismaClient;
+    if (!db) {
+        throw new Error("dispatcher.publish: no Prisma client available for the insert. Either pass " +
+            "{ tx } to publish() with an interactive-transaction client, or call " +
+            "configureDispatcher({ producer, tenantId, prismaClient }) at process startup " +
+            "so the publish path has a default client.");
+    }
+    await db.dispatcherEvent.create({
+        data: {
+            id: envelope.event_id,
+            eventType: envelope.event_type,
+            schemaVersion: envelope.schema_version,
+            tenantId: envelope.tenant_id,
+            producer: envelope.producer,
+            subject: envelope.subject ?? null,
+            actor: envelope.actor ?? "",
+            occurredAt: new Date(envelope.occurred_at),
+            payload: envelope.payload,
+            ...(envelope.correlation_id ? { correlationId: envelope.correlation_id } : {}),
+        },
+    });
+    (0, observability_1.recordDispatcherIncrement)("dispatcher.publish.count", {
+        event_type: envelope.event_type,
+        producer: envelope.producer,
+        schema_version: String(envelope.schema_version),
+    });
+    return { event_id: envelope.event_id };
+}

package/dist/producer-db.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Producer-DB resolution for the fanout worker.
+ *
+ * Per ADR-0009 §"Per-domain table family," each producer-domain owns its
+ * own `dispatcher_event` / `dispatcher_cursor` / `dispatcher_dedup` /
+ * `dispatcher_dead_letter` tables in the producer's database. Cross-DB
+ * transactions are not supported, so the producer-side write to
+ * `dispatcher_event` happens in the producer's DB and any reader of that
+ * stream needs a connection there.
+ *
+ * Topology B (per 2026-05-12-platform-cross-db-consumer-dsn-upstream):
+ * Platform runs one fanout worker that polls every producer's
+ * `dispatcher_event` and POSTs envelopes to the registered consumer
+ * webhook inboxes. Centralizing here means the cross-DB read happens in
+ * exactly one place (the worker), not in N consumer processes. This file
+ * resolves "producer name" -> "pg.Pool pointed at that producer's DB"
+ * for the worker.
+ *
+ * Why pg.Pool instead of PrismaClient: Platform's Prisma client is
+ * generated against Platform's schema.prisma, which has no
+ * `multiSchema` or `@@schema` declarations and so always qualifies
+ * dispatcher_X queries with `public.`. Producer DBs (Growth, Sales,
+ * etc.) put their dispatcher tables in domain-specific schemas (Sales'
+ * `sales` schema, Growth's `growth` schema via `?schema=` URL param).
+ * Platform's `public.`-qualified queries fail there. Raw pg.Pool +
+ * unqualified SQL + the connection's search_path (derived from the DSN's
+ * `?schema=<domain>` query param by pgConfigWithSearchPath) resolves the
+ * schema correctly per producer with zero code per producer.
+ *
+ * Env var convention:
+ *
+ *   - For the worker's own producer (`platform`): DATABASE_URL.
+ *   - For every other producer: `DISPATCHER_PRODUCER_DATABASE_URL_<PRODUCER>`
+ *     e.g., DISPATCHER_PRODUCER_DATABASE_URL_GROWTH points at Growth's
+ *     `sguild-domains` Supabase project pooler URL with
+ *     `?schema=growth` so unqualified `dispatcher_cursor` queries
+ *     resolve to `growth.dispatcher_cursor`.
+ *
+ * A missing DSN for a producer logs a warning and excludes that
+ * producer from the fanout boot loop (sibling pattern to a missing
+ * consumer URL excluding that consumer-domain). Operators see the gap in
+ * the boot log and provision the env var; the cursor for any
+ * (consumer, event_type) reading from that producer stays put until the
+ * env arrives.
+ *
+ * Lifecycle: pools are cached by producer name for process lifetime.
+ * fanout-worker.ts's SIGTERM handler closes the ConsumerLoops which
+ * close pools they own; pools handed out here are NOT owned by the
+ * loops (multiple loops can share a pool against the same producer DB).
+ * The cached pools rely on Node process exit to drain.
+ */
+import { Pool } from "pg";
+/**
+ * Resolve a producer name to its DSN. Returns undefined if the env var
+ * is not set; in that case the fanout boot loop logs and skips this
+ * producer.
+ */
+export declare function resolveProducerDsn(producer: string): string | undefined;
+/**
+ * Resolve a producer name to a pg.Pool + databaseUrl pointed at that
+ * producer's DB. Returns undefined if the DSN is missing (the caller
+ * logs and skips).
+ *
+ * Pools are cached by producer name so multiple loops reading the same
+ * producer share a single pool. Pool size defaults to pg's default
+ * (10 connections); for the dispatcher fanout that's well within
+ * typical Supabase pooler limits.
+ */
+export declare function getProducerDb(producer: string): {
+    pool: Pool;
+    databaseUrl: string;
+    schema: string | null;
+} | undefined;
+/**
+ * Test-only seam: clear the cache so each test boots the resolver from
+ * scratch. Production code MUST NOT call this; it would leak the
+ * existing pool connections (the old pools stay open and the new ones
+ * start from zero).
+ */
+export declare function __resetProducerDbCacheForTests(): void;

package/dist/producer-db.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Producer-DB resolution for the fanout worker.
+ *
+ * Per ADR-0009 §"Per-domain table family," each producer-domain owns its
+ * own `dispatcher_event` / `dispatcher_cursor` / `dispatcher_dedup` /
+ * `dispatcher_dead_letter` tables in the producer's database. Cross-DB
+ * transactions are not supported, so the producer-side write to
+ * `dispatcher_event` happens in the producer's DB and any reader of that
+ * stream needs a connection there.
+ *
+ * Topology B (per 2026-05-12-platform-cross-db-consumer-dsn-upstream):
+ * Platform runs one fanout worker that polls every producer's
+ * `dispatcher_event` and POSTs envelopes to the registered consumer
+ * webhook inboxes. Centralizing here means the cross-DB read happens in
+ * exactly one place (the worker), not in N consumer processes. This file
+ * resolves "producer name" -> "pg.Pool pointed at that producer's DB"
+ * for the worker.
+ *
+ * Why pg.Pool instead of PrismaClient: Platform's Prisma client is
+ * generated against Platform's schema.prisma, which has no
+ * `multiSchema` or `@@schema` declarations and so always qualifies
+ * dispatcher_X queries with `public.`. Producer DBs (Growth, Sales,
+ * etc.) put their dispatcher tables in domain-specific schemas (Sales'
+ * `sales` schema, Growth's `growth` schema via `?schema=` URL param).
+ * Platform's `public.`-qualified queries fail there. Raw pg.Pool +
+ * unqualified SQL + the connection's search_path (derived from the DSN's
+ * `?schema=<domain>` query param by pgConfigWithSearchPath) resolves the
+ * schema correctly per producer with zero code per producer.
+ *
+ * Env var convention:
+ *
+ *   - For the worker's own producer (`platform`): DATABASE_URL.
+ *   - For every other producer: `DISPATCHER_PRODUCER_DATABASE_URL_<PRODUCER>`
+ *     e.g., DISPATCHER_PRODUCER_DATABASE_URL_GROWTH points at Growth's
+ *     `sguild-domains` Supabase project pooler URL with
+ *     `?schema=growth` so unqualified `dispatcher_cursor` queries
+ *     resolve to `growth.dispatcher_cursor`.
+ *
+ * A missing DSN for a producer logs a warning and excludes that
+ * producer from the fanout boot loop (sibling pattern to a missing
+ * consumer URL excluding that consumer-domain). Operators see the gap in
+ * the boot log and provision the env var; the cursor for any
+ * (consumer, event_type) reading from that producer stays put until the
+ * env arrives.
+ *
+ * Lifecycle: pools are cached by producer name for process lifetime.
+ * fanout-worker.ts's SIGTERM handler closes the ConsumerLoops which
+ * close pools they own; pools handed out here are NOT owned by the
+ * loops (multiple loops can share a pool against the same producer DB).
+ * The cached pools rely on Node process exit to drain.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProducerDsn = resolveProducerDsn;
+exports.getProducerDb = getProducerDb;
+exports.__resetProducerDbCacheForTests = __resetProducerDbCacheForTests;
+const pg_1 = require("pg");
+const pg_search_path_1 = require("./internal/pg-search-path");
+/**
+ * Cache of producer name -> { pool, databaseUrl, schema }. Keyed by producer
+ * name for fast lookup at boot. The databaseUrl is also kept so the
+ * ConsumerLoop can wire its LISTEN/NOTIFY pg.Client against the same
+ * producer's DSN. The schema is the parsed `?schema=` query param value
+ * (null if absent or `public`); ConsumerLoop schema-qualifies its SQL
+ * with this value so queries work even when pgbouncer's transaction-mode
+ * pooler drops the libpq `options` startup parameter.
+ */
+const cache = new Map();
+/**
+ * Resolve a producer name to its DSN. Returns undefined if the env var
+ * is not set; in that case the fanout boot loop logs and skips this
+ * producer.
+ */
+function resolveProducerDsn(producer) {
+    if (producer === "platform") {
+        return process.env.DATABASE_URL;
+    }
+    const envName = `DISPATCHER_PRODUCER_DATABASE_URL_${producer.toUpperCase()}`;
+    return process.env[envName];
+}
+/**
+ * Resolve a producer name to a pg.Pool + databaseUrl pointed at that
+ * producer's DB. Returns undefined if the DSN is missing (the caller
+ * logs and skips).
+ *
+ * Pools are cached by producer name so multiple loops reading the same
+ * producer share a single pool. Pool size defaults to pg's default
+ * (10 connections); for the dispatcher fanout that's well within
+ * typical Supabase pooler limits.
+ */
+function getProducerDb(producer) {
+    const cached = cache.get(producer);
+    if (cached)
+        return cached;
+    const dsn = resolveProducerDsn(producer);
+    if (!dsn)
+        return undefined;
+    const config = (0, pg_search_path_1.pgConfigWithSearchPath)(dsn);
+    const pool = new pg_1.Pool(config);
+    pool.on("error", (error) => {
+        console.warn(`[dispatcher.producer-db] ${producer} pool error: ${error.message}`);
+    });
+    const entry = { pool, databaseUrl: dsn, schema: config.schema };
+    cache.set(producer, entry);
+    return entry;
+}
+/**
+ * Test-only seam: clear the cache so each test boots the resolver from
+ * scratch. Production code MUST NOT call this; it would leak the
+ * existing pool connections (the old pools stay open and the new ones
+ * start from zero).
+ */
+function __resetProducerDbCacheForTests() {
+    cache.clear();
+}

package/dist/registry.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Event-type registry loader and query.
+ *
+ * Reads the canonical registry manifest at
+ * coordination/contracts/event-types-registry.json (path resolved relative to
+ * the platform repo's working directory; the registry is checked into the
+ * coordination repo and the platform repo references it via its known
+ * filesystem location during local development; CI gets a copy via the same
+ * mechanism).
+ *
+ * The registry is the single source of truth for which (event_type,
+ * schema_version) pairs are valid. The dispatcher reads it at startup to drive
+ * validation; producers register new event_types here before first use per
+ * §10.4 of the envelope contract.
+ */
+import type { ProducerDomain } from "./types";
+export type SchemaVersionStatus = "active" | "deprecated" | "sunset";
+export type SchemaVersionEntry = {
+    version: number;
+    /** Path to the JSON Schema for this payload version, relative to the coordination repo root. May be null if the schema has not yet been authored. */
+    payload_schema: string | null;
+    status: SchemaVersionStatus;
+    /** YYYY-MM-DD when this version was registered. */
+    registered_at: string;
+    notes?: string;
+};
+export type EventTypeRegistration = {
+    event_type: string;
+    producer: ProducerDomain;
+    /**
+     * The closed-set domains that subscribe, plus the synthetic "platform-warehouse"
+     * value for the warehouse loader. Today this is informational; once CI
+     * validation lands as a Phase 0 deliverable, it gates emit-side smoke tests
+     * against unregistered consumers.
+     */
+    consumers: Array<ProducerDomain | "platform-warehouse">;
+    /** Path to the contract that owns the producer surface. May be null for events whose owning contract has not been written yet. */
+    owning_contract: string | null;
+    schema_versions: SchemaVersionEntry[];
+};
+export type RegistryManifest = {
+    registry_version: string;
+    registry_date: string;
+    registry_owner: string;
+    registry_notes: string;
+    events: Record<string, Omit<EventTypeRegistration, "event_type">>;
+};
+/**
+ * Location of the registry manifest inside the bundled contracts tree,
+ * rooted at `contracts/` exactly as the coordination repo stores it. The
+ * `@sguild/dispatcher` package ships this file bundled, so the default
+ * needs no sibling coordination checkout. `resolveContractPath` knows the
+ * module-relative and cwd-relative layouts this can live at (including the
+ * sibling coordination repo) and tries them in order.
+ */
+export declare const DEFAULT_REGISTRY_PATH = "contracts/event-types-registry.json";
+/**
+ * Load and cache the registry manifest from the filesystem. Called once per
+ * process at startup; subsequent calls return the cached value.
+ *
+ * Resolution order: an explicit `path` argument (resolved against the
+ * process cwd; absolute paths pass through unchanged, which is how the test
+ * fixtures load) wins; otherwise the bundled copy shipped inside the
+ * package; otherwise the cwd-relative sibling coordination repo. See
+ * `resolveContractPath` for the full waterfall.
+ *
+ * The registry is read from disk synchronously at first use. A future
+ * version may switch to an async loader if the registry grows large or
+ * moves to a network-fetched location.
+ */
+export declare function loadRegistry(path?: string): RegistryManifest;
+/**
+ * Look up an event_type's registration. Returns null if the event_type is
+ * not registered; producers calling `dispatcher.publish` against an
+ * unregistered event_type will see a clear error rather than a successful
+ * emit that consumers cannot decode.
+ */
+export declare function getEventTypeRegistration(event_type: string, manifest?: RegistryManifest): EventTypeRegistration | null;
+/**
+ * Look up the active schema_version for an event_type. Returns null if the
+ * event_type is not registered or has no active version (every version is
+ * deprecated or sunset, which is itself a registry hygiene problem).
+ *
+ * Producers emitting without an explicit `schema_version` get the active
+ * version returned here. During a transition window where multiple versions
+ * are simultaneously active, producers MUST supply the version explicitly.
+ */
+export declare function getActiveSchemaVersion(event_type: string, manifest?: RegistryManifest): SchemaVersionEntry | null;
+/**
+ * Reset the cached manifest. Test-only; production code does not call this.
+ * Exported so test files can reload the registry between fixtures without
+ * spinning up a fresh process.
+ */
+export declare function __resetRegistryCacheForTests(): void;

package/dist/registry.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Event-type registry loader and query.
+ *
+ * Reads the canonical registry manifest at
+ * coordination/contracts/event-types-registry.json (path resolved relative to
+ * the platform repo's working directory; the registry is checked into the
+ * coordination repo and the platform repo references it via its known
+ * filesystem location during local development; CI gets a copy via the same
+ * mechanism).
+ *
+ * The registry is the single source of truth for which (event_type,
+ * schema_version) pairs are valid. The dispatcher reads it at startup to drive
+ * validation; producers register new event_types here before first use per
+ * §10.4 of the envelope contract.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REGISTRY_PATH = void 0;
+exports.loadRegistry = loadRegistry;
+exports.getEventTypeRegistration = getEventTypeRegistration;
+exports.getActiveSchemaVersion = getActiveSchemaVersion;
+exports.__resetRegistryCacheForTests = __resetRegistryCacheForTests;
+const node_fs_1 = require("node:fs");
+const resolve_contract_path_1 = require("./internal/resolve-contract-path");
+/**
+ * Location of the registry manifest inside the bundled contracts tree,
+ * rooted at `contracts/` exactly as the coordination repo stores it. The
+ * `@sguild/dispatcher` package ships this file bundled, so the default
+ * needs no sibling coordination checkout. `resolveContractPath` knows the
+ * module-relative and cwd-relative layouts this can live at (including the
+ * sibling coordination repo) and tries them in order.
+ */
+exports.DEFAULT_REGISTRY_PATH = "contracts/event-types-registry.json";
+let cachedManifest = null;
+/**
+ * Load and cache the registry manifest from the filesystem. Called once per
+ * process at startup; subsequent calls return the cached value.
+ *
+ * Resolution order: an explicit `path` argument (resolved against the
+ * process cwd; absolute paths pass through unchanged, which is how the test
+ * fixtures load) wins; otherwise the bundled copy shipped inside the
+ * package; otherwise the cwd-relative sibling coordination repo. See
+ * `resolveContractPath` for the full waterfall.
+ *
+ * The registry is read from disk synchronously at first use. A future
+ * version may switch to an async loader if the registry grows large or
+ * moves to a network-fetched location.
+ */
+function loadRegistry(path) {
+    if (cachedManifest)
+        return cachedManifest;
+    const resolvedPath = (0, resolve_contract_path_1.resolveContractPath)(__dirname, exports.DEFAULT_REGISTRY_PATH, {
+        priorityPaths: path ? [path] : [],
+    });
+    const raw = (0, node_fs_1.readFileSync)(resolvedPath, "utf8");
+    cachedManifest = JSON.parse(raw);
+    return cachedManifest;
+}
+/**
+ * Look up an event_type's registration. Returns null if the event_type is
+ * not registered; producers calling `dispatcher.publish` against an
+ * unregistered event_type will see a clear error rather than a successful
+ * emit that consumers cannot decode.
+ */
+function getEventTypeRegistration(event_type, manifest = loadRegistry()) {
+    const entry = manifest.events[event_type];
+    if (!entry)
+        return null;
+    return { event_type, ...entry };
+}
+/**
+ * Look up the active schema_version for an event_type. Returns null if the
+ * event_type is not registered or has no active version (every version is
+ * deprecated or sunset, which is itself a registry hygiene problem).
+ *
+ * Producers emitting without an explicit `schema_version` get the active
+ * version returned here. During a transition window where multiple versions
+ * are simultaneously active, producers MUST supply the version explicitly.
+ */
+function getActiveSchemaVersion(event_type, manifest = loadRegistry()) {
+    const reg = getEventTypeRegistration(event_type, manifest);
+    if (!reg)
+        return null;
+    const active = reg.schema_versions.filter((v) => v.status === "active");
+    if (active.length === 0)
+        return null;
+    if (active.length > 1) {
+        throw new Error(`Multiple active schema_versions for event_type '${event_type}'; producers must supply schema_version explicitly during the transition window.`);
+    }
+    return active[0];
+}
+/**
+ * Reset the cached manifest. Test-only; production code does not call this.
+ * Exported so test files can reload the registry between fixtures without
+ * spinning up a fresh process.
+ */
+function __resetRegistryCacheForTests() {
+    cachedManifest = null;
+}

package/dist/signature.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Sign/verify primitives shared between the Platform-side fanout worker
+ * (producer of signatures) and domain-side inbox handlers (verifiers).
+ *
+ * Extracted out of fanout.ts so domains can vendor a minimal three-file
+ * surface (signature.ts + inbox.ts + types.ts) without pulling in the
+ * polling-consumer machinery, registry loader, transport implementation,
+ * Prisma client wiring, or any of the rest of the SDK. This is the
+ * canonical low-dependency module domains depend on for HMAC.
+ *
+ * No imports from prisma, the registry, the dispatcher singleton, or
+ * any other dispatcher file. Only node:crypto. Keep it that way.
+ *
+ * Contract: Platform's fanout signs the JSON-serialized envelope body
+ * with the per-consumer HMAC secret and sends `X-Sguild-Signature:
+ * sha256=<hex>`. The receiving inbox recomputes the same digest from
+ * the raw request body and constant-time compares.
+ */
+/** Header carrying the HMAC signature. Sha256 hex digest, prefixed by algorithm. */
+export declare const SIGNATURE_HEADER = "x-sguild-signature";
+/** Header carrying the event_id for log correlation on the consumer side. */
+export declare const EVENT_ID_HEADER = "x-sguild-event-id";
+/** Header carrying the event_type for log correlation. */
+export declare const EVENT_TYPE_HEADER = "x-sguild-event-type";
+/**
+ * Compute the HMAC-SHA256 signature for an envelope body. Output is a
+ * hex string; the header value is `sha256=<output>`. Body is the exact
+ * JSON-serialized envelope the consumer will receive; sender and
+ * receiver MUST serialize identically (no whitespace differences,
+ * key-ordering differences, etc.) or the signature will mismatch. The
+ * recommended pattern: sender produces `JSON.stringify(envelope)` and
+ * the receiver verifies against the raw request body before parsing.
+ */
+export declare function signEnvelope(body: string, secret: string): string;
+/**
+ * Verify a signature against a body. Constant-time comparison to
+ * prevent timing attacks. Accepts the signature with or without the
+ * `sha256=` prefix; consumers should pass the header verbatim and this
+ * function normalizes.
+ *
+ * Returns true on match, false on mismatch or any parse/length error.
+ * Never throws.
+ */
+export declare function verifyEnvelopeSignature(body: string, secret: string, signatureHeaderValue: string): boolean;

package/dist/signature.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Sign/verify primitives shared between the Platform-side fanout worker
+ * (producer of signatures) and domain-side inbox handlers (verifiers).
+ *
+ * Extracted out of fanout.ts so domains can vendor a minimal three-file
+ * surface (signature.ts + inbox.ts + types.ts) without pulling in the
+ * polling-consumer machinery, registry loader, transport implementation,
+ * Prisma client wiring, or any of the rest of the SDK. This is the
+ * canonical low-dependency module domains depend on for HMAC.
+ *
+ * No imports from prisma, the registry, the dispatcher singleton, or
+ * any other dispatcher file. Only node:crypto. Keep it that way.
+ *
+ * Contract: Platform's fanout signs the JSON-serialized envelope body
+ * with the per-consumer HMAC secret and sends `X-Sguild-Signature:
+ * sha256=<hex>`. The receiving inbox recomputes the same digest from
+ * the raw request body and constant-time compares.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_TYPE_HEADER = exports.EVENT_ID_HEADER = exports.SIGNATURE_HEADER = void 0;
+exports.signEnvelope = signEnvelope;
+exports.verifyEnvelopeSignature = verifyEnvelopeSignature;
+const node_crypto_1 = require("node:crypto");
+/** Header carrying the HMAC signature. Sha256 hex digest, prefixed by algorithm. */
+exports.SIGNATURE_HEADER = "x-sguild-signature";
+/** Header carrying the event_id for log correlation on the consumer side. */
+exports.EVENT_ID_HEADER = "x-sguild-event-id";
+/** Header carrying the event_type for log correlation. */
+exports.EVENT_TYPE_HEADER = "x-sguild-event-type";
+/**
+ * Compute the HMAC-SHA256 signature for an envelope body. Output is a
+ * hex string; the header value is `sha256=<output>`. Body is the exact
+ * JSON-serialized envelope the consumer will receive; sender and
+ * receiver MUST serialize identically (no whitespace differences,
+ * key-ordering differences, etc.) or the signature will mismatch. The
+ * recommended pattern: sender produces `JSON.stringify(envelope)` and
+ * the receiver verifies against the raw request body before parsing.
+ */
+function signEnvelope(body, secret) {
+    return (0, node_crypto_1.createHmac)("sha256", secret).update(body, "utf8").digest("hex");
+}
+function hexToBytes(hex) {
+    if (hex.length % 2 !== 0) {
+        throw new Error("invalid hex length");
+    }
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i += 1) {
+        const byte = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+        if (Number.isNaN(byte)) {
+            throw new Error("invalid hex byte");
+        }
+        bytes[i] = byte;
+    }
+    return bytes;
+}
+/**
+ * Verify a signature against a body. Constant-time comparison to
+ * prevent timing attacks. Accepts the signature with or without the
+ * `sha256=` prefix; consumers should pass the header verbatim and this
+ * function normalizes.
+ *
+ * Returns true on match, false on mismatch or any parse/length error.
+ * Never throws.
+ */
+function verifyEnvelopeSignature(body, secret, signatureHeaderValue) {
+    const provided = signatureHeaderValue.startsWith("sha256=")
+        ? signatureHeaderValue.slice("sha256=".length)
+        : signatureHeaderValue;
+    const expected = signEnvelope(body, secret);
+    if (provided.length !== expected.length)
+        return false;
+    try {
+        return (0, node_crypto_1.timingSafeEqual)(hexToBytes(provided), hexToBytes(expected));
+    }
+    catch {
+        return false;
+    }
+}