@sguild/dispatcher 2.0.0

package/contracts/refund-flow/schema/payloads/refund.completed-v1.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/refund-flow/schema/payloads/refund.completed-v1.json",
+  "title": "refund.completed payload v1",
+  "description": "Payload for the refund.completed event_type per contracts/refund-flow/README.md §4.2. Emitted by Revenue at the writeback transaction commit when the Square webhook confirms the refund settled, the Refund record flips to COMPLETED, the Refund Debit ledger entries post, and the Order status flips to PARTIALLY_REFUNDED or REFUNDED. Producer SHALL emit inside the same Prisma transaction as the writeback per ADR-0009. Subscribers: Sales (Lead reactivation routing), Delivery (lock-released invariant verification per §6), platform-warehouse.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "refund_id",
+    "order_id",
+    "person_id",
+    "amount_cents",
+    "currency",
+    "provider_ref",
+    "initiated_at",
+    "completed_at"
+  ],
+  "properties": {
+    "refund_id": {
+      "type": "string",
+      "description": "The Revenue-owned Refund record. Matches the refund_id on the matching refund.initiated event. ref_<UUID v7>.",
+      "pattern": "^ref_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "order_id": {
+      "type": "string",
+      "description": "The Order this refund is against. ord_<UUID v7>.",
+      "pattern": "^ord_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "person_id": {
+      "type": "string",
+      "description": "The Person being refunded. per_<UUID v7>.",
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "amount_cents": {
+      "type": "integer",
+      "description": "Refund amount in the smallest currency unit. Matches the amount_cents on the matching refund.initiated event.",
+      "minimum": 1
+    },
+    "currency": {
+      "type": "string",
+      "description": "ISO-4217 currency code. Matches the matching refund.initiated event.",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "provider_ref": {
+      "type": "string",
+      "description": "Provider-side identifier for the refund. Matches the matching refund.initiated event.",
+      "minLength": 1
+    },
+    "initiated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "The original initiation timestamp from the matching refund.initiated event. Carried on this event for correlation; consumers MAY use (refund_id, initiated_at) as the dedup key for cross-event correlation."
+    },
+    "completed_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Wall-clock UTC timestamp at the writeback transaction commit. Producer's clock."
+    },
+    "cancellation_reason": {
+      "type": "string",
+      "description": "Optional, same shape as on refund.initiated. Mirrors the upstream credit.released v2 reason_code for lock-tied refunds; null for non-lock refunds. Consumers SHALL treat unknown values as safe-to-ignore per §8.",
+      "enum": [
+        "site_closure",
+        "coach_unavailable_reschedule_failed",
+        "force_majeure",
+        "weather",
+        "administrative_void",
+        "customer_requested_in_window",
+        "customer_requested_exception",
+        "policy_exception",
+        "bad_debt_writeoff"
+      ]
+    }
+  }
+}

package/contracts/refund-flow/schema/payloads/refund.initiated-v1.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/refund-flow/schema/payloads/refund.initiated-v1.json",
+  "title": "refund.initiated payload v1",
+  "description": "Payload for the refund.initiated event_type per contracts/refund-flow/README.md §4.1. Emitted by Revenue at the writeback transaction commit when the Refund record is minted at PENDING and the Square refund call has been dispatched. Producer SHALL emit inside the same Prisma transaction as the Refund record insert per ADR-0009. Subscribers: Sales (refund-against-Lead reactivation routing), platform-warehouse. Delivery does not subscribe at v1; the lock-released invariant verification fires on refund.completed.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "refund_id",
+    "order_id",
+    "person_id",
+    "amount_cents",
+    "currency",
+    "provider_ref",
+    "initiated_at"
+  ],
+  "properties": {
+    "refund_id": {
+      "type": "string",
+      "description": "The Revenue-owned Refund record. ref_<UUID v7>.",
+      "pattern": "^ref_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "order_id": {
+      "type": "string",
+      "description": "The Order this refund is against. ord_<UUID v7>.",
+      "pattern": "^ord_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "person_id": {
+      "type": "string",
+      "description": "The Person being refunded. per_<UUID v7>.",
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "amount_cents": {
+      "type": "integer",
+      "description": "Refund amount in the smallest currency unit. Positive integer; the sign on the Refund Debit ledger entry is internal to Revenue.",
+      "minimum": 1
+    },
+    "currency": {
+      "type": "string",
+      "description": "ISO-4217 currency code. Matches the originating Order's currency.",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "provider_ref": {
+      "type": "string",
+      "description": "Provider-side identifier for the refund per the funding-state external-reference rule. Square refund id (sqref_<id>) for refunds reaching the provider; external-actions row id (ext_ prefix) for credit-balance-only refunds.",
+      "minLength": 1
+    },
+    "initiated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Wall-clock UTC timestamp at the writeback transaction commit. Producer's clock. Matches the initiated_at on the corresponding refund.completed event for correlation."
+    },
+    "cancellation_reason": {
+      "type": "string",
+      "description": "Optional. When the refund traces back to a credit-reservation-lock cancellation, mirrors the reason_code from the upstream credit.released v2 event per credit-reservation-lock §6.1. Null for non-lock refunds. Consumers SHALL treat unknown values as safe-to-ignore per §8.",
+      "enum": [
+        "site_closure",
+        "coach_unavailable_reschedule_failed",
+        "force_majeure",
+        "weather",
+        "administrative_void",
+        "customer_requested_in_window",
+        "customer_requested_exception",
+        "policy_exception",
+        "bad_debt_writeoff"
+      ]
+    }
+  }
+}

package/dist/config.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Dispatcher runtime configuration.
+ *
+ * Two values every emit needs that are runtime-context rather than per-call
+ * input: `producer` (which domain emitted the event) and `tenant_id` (the
+ * tenancy scope per ADR-0001). Both live as runtime config rather than
+ * arguments to `dispatcher.publish` because they are properties of the
+ * deploy, not of the individual call site; threading them through every
+ * publish call would be both noisy and a source of drift if a producer
+ * accidentally passed the wrong value.
+ *
+ * Phase 2 deployment shape: single-tenant Sguild, one Node process per
+ * domain repo. Each repo's bootstrap (or the dev-server entry point) calls
+ * `configureDispatcher({ producer, tenantId })` once at startup; the
+ * env-driven fallback below covers the dev-loop and CI cases.
+ *
+ * Multi-tenant deployment shape (forward-compatible per envelope contract
+ * §11.2): the runtime config moves into an async-local-storage context
+ * keyed by request, so a single Node process can emit events for multiple
+ * tenants. Out of scope for Phase 2 since Sguild is single-tenant today;
+ * the API stays the same when the multi-tenant version lands (callers
+ * still call `getDispatcherConfig()`, the implementation reads from ALS
+ * instead of a module-level variable).
+ *
+ * Prisma client injection: the publish path inserts the event row through
+ * a Prisma client. The SDK does not import any domain's generated client
+ * directly (it ships as `@sguild/dispatcher` with `@prisma/client` as a
+ * peer dependency), so the consuming domain injects its own client here at
+ * startup via `configureDispatcher({ ..., prismaClient })`. Per-call
+ * publishes that pass an interactive-transaction `tx` do not need the
+ * injected client; the injected client is the default for publishes with
+ * no caller-supplied transaction.
+ */
+import type { PrismaClient } from "@prisma/client";
+import type { LiveProducerDomain } from "./types";
+export type DispatcherConfig = {
+    /** Which domain emitted the event. Goes onto every envelope's `producer` field. */
+    producer: LiveProducerDomain;
+    /** Tenancy scope per ADR-0001. Goes onto every envelope's `tenant_id` field. */
+    tenantId: string;
+    /**
+     * Prisma client used for the publish path when a per-call `tx` is not
+     * supplied. The consuming domain injects its own generated client (each
+     * domain owns its `DispatcherEvent` model + migration per ADR-0009's
+     * per-domain table family). Optional: a process that only ever publishes
+     * inside caller-supplied transactions, or only consumes, does not need it.
+     */
+    prismaClient?: PrismaClient;
+};
+/**
+ * Set the dispatcher's runtime config. Call once at process startup. A
+ * second call overwrites the first; the production deploy shape calls
+ * this once and never again, but tests may override.
+ */
+export declare function configureDispatcher(config: DispatcherConfig): void;
+/**
+ * Get the dispatcher's runtime config. Returns the value supplied to
+ * `configureDispatcher` if present; otherwise falls back to environment
+ * variables (`DISPATCHER_PRODUCER` and `DISPATCHER_TENANT_ID`). Throws
+ * if neither source is set, because emitting without a producer or
+ * tenant_id violates envelope contract §4.1.
+ */
+export declare function getDispatcherConfig(): DispatcherConfig;
+/**
+ * Reset the runtime config. Test-only; production code does not call this.
+ */
+export declare function __resetDispatcherConfigForTests(): void;

package/dist/config.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Dispatcher runtime configuration.
+ *
+ * Two values every emit needs that are runtime-context rather than per-call
+ * input: `producer` (which domain emitted the event) and `tenant_id` (the
+ * tenancy scope per ADR-0001). Both live as runtime config rather than
+ * arguments to `dispatcher.publish` because they are properties of the
+ * deploy, not of the individual call site; threading them through every
+ * publish call would be both noisy and a source of drift if a producer
+ * accidentally passed the wrong value.
+ *
+ * Phase 2 deployment shape: single-tenant Sguild, one Node process per
+ * domain repo. Each repo's bootstrap (or the dev-server entry point) calls
+ * `configureDispatcher({ producer, tenantId })` once at startup; the
+ * env-driven fallback below covers the dev-loop and CI cases.
+ *
+ * Multi-tenant deployment shape (forward-compatible per envelope contract
+ * §11.2): the runtime config moves into an async-local-storage context
+ * keyed by request, so a single Node process can emit events for multiple
+ * tenants. Out of scope for Phase 2 since Sguild is single-tenant today;
+ * the API stays the same when the multi-tenant version lands (callers
+ * still call `getDispatcherConfig()`, the implementation reads from ALS
+ * instead of a module-level variable).
+ *
+ * Prisma client injection: the publish path inserts the event row through
+ * a Prisma client. The SDK does not import any domain's generated client
+ * directly (it ships as `@sguild/dispatcher` with `@prisma/client` as a
+ * peer dependency), so the consuming domain injects its own client here at
+ * startup via `configureDispatcher({ ..., prismaClient })`. Per-call
+ * publishes that pass an interactive-transaction `tx` do not need the
+ * injected client; the injected client is the default for publishes with
+ * no caller-supplied transaction.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureDispatcher = configureDispatcher;
+exports.getDispatcherConfig = getDispatcherConfig;
+exports.__resetDispatcherConfigForTests = __resetDispatcherConfigForTests;
+let runtimeConfig = null;
+/**
+ * Set the dispatcher's runtime config. Call once at process startup. A
+ * second call overwrites the first; the production deploy shape calls
+ * this once and never again, but tests may override.
+ */
+function configureDispatcher(config) {
+    runtimeConfig = config;
+}
+/**
+ * Get the dispatcher's runtime config. Returns the value supplied to
+ * `configureDispatcher` if present; otherwise falls back to environment
+ * variables (`DISPATCHER_PRODUCER` and `DISPATCHER_TENANT_ID`). Throws
+ * if neither source is set, because emitting without a producer or
+ * tenant_id violates envelope contract §4.1.
+ */
+function getDispatcherConfig() {
+    if (runtimeConfig)
+        return runtimeConfig;
+    const producerEnv = process.env.DISPATCHER_PRODUCER;
+    const tenantEnv = process.env.DISPATCHER_TENANT_ID;
+    if (!producerEnv || !tenantEnv) {
+        throw new Error("Dispatcher runtime config is not set. Either call configureDispatcher({ producer, tenantId }) at process startup or set DISPATCHER_PRODUCER and DISPATCHER_TENANT_ID environment variables. Both are required by envelope contract §4.1.");
+    }
+    if (!isLiveProducerDomain(producerEnv)) {
+        throw new Error(`DISPATCHER_PRODUCER value '${producerEnv}' is not a recognized live producer domain. Expected one of: platform, growth, sales, delivery, revenue, coaching.`);
+    }
+    return { producer: producerEnv, tenantId: tenantEnv };
+}
+/**
+ * Reset the runtime config. Test-only; production code does not call this.
+ */
+function __resetDispatcherConfigForTests() {
+    runtimeConfig = null;
+}
+function isLiveProducerDomain(value) {
+    return (value === "platform" ||
+        value === "growth" ||
+        value === "sales" ||
+        value === "delivery" ||
+        value === "revenue" ||
+        value === "coaching");
+}

package/dist/dispatcher-errors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Dispatcher error classes shared between the public dispatcher surface
+ * and the transport implementations. Extracted into their own module so
+ * postgres-transport.ts can throw `UnregisteredEventTypeError` and
+ * `UnregisteredSchemaVersionError` without circular-importing the
+ * dispatcher singleton.
+ *
+ * `DispatcherNotImplementedError` is no longer thrown by `publish` (Slice
+ * 2 wires the Postgres-queue transport in); it is still thrown by
+ * `subscribe` until Slice 3 lands the consumer-side polling worker.
+ */
+export declare class DispatcherNotImplementedError extends Error {
+    constructor(operation: "publish" | "subscribe");
+}
+export declare class UnregisteredEventTypeError extends Error {
+    constructor(event_type: string);
+}
+export declare class UnregisteredSchemaVersionError extends Error {
+    constructor(event_type: string, schema_version: number | null);
+}

package/dist/dispatcher-errors.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Dispatcher error classes shared between the public dispatcher surface
+ * and the transport implementations. Extracted into their own module so
+ * postgres-transport.ts can throw `UnregisteredEventTypeError` and
+ * `UnregisteredSchemaVersionError` without circular-importing the
+ * dispatcher singleton.
+ *
+ * `DispatcherNotImplementedError` is no longer thrown by `publish` (Slice
+ * 2 wires the Postgres-queue transport in); it is still thrown by
+ * `subscribe` until Slice 3 lands the consumer-side polling worker.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnregisteredSchemaVersionError = exports.UnregisteredEventTypeError = exports.DispatcherNotImplementedError = void 0;
+class DispatcherNotImplementedError extends Error {
+    constructor(operation) {
+        super(`Dispatcher.${operation} is not implemented in the current SDK slice. ` +
+            `Tracking is in memos/2026/2026-05-09-platform-q2-airtable-sunset-directive ` +
+            `(Phase 2 ship 2026-06-22) and the Platform-owed ledger at memos/2026/2026-05-01-platform-owed-ledger.`);
+        this.name = "DispatcherNotImplementedError";
+    }
+}
+exports.DispatcherNotImplementedError = DispatcherNotImplementedError;
+class UnregisteredEventTypeError extends Error {
+    constructor(event_type) {
+        super(`Event type '${event_type}' is not registered in the event-type registry ` +
+            `(coordination/contracts/event-types-registry.json). Producers SHALL register ` +
+            `every new event_type before first use per §10.4 of the event-envelope contract. ` +
+            `Add the event_type to the registry with an initial payload schema and re-emit.`);
+        this.name = "UnregisteredEventTypeError";
+    }
+}
+exports.UnregisteredEventTypeError = UnregisteredEventTypeError;
+class UnregisteredSchemaVersionError extends Error {
+    constructor(event_type, schema_version) {
+        super(schema_version === null
+            ? `Event type '${event_type}' has no active schema_version. Set one in the registry or supply a version explicitly on EventEmit.`
+            : `Schema version ${schema_version} is not registered for event_type '${event_type}'. Register it in coordination/contracts/event-types-registry.json before emitting.`);
+        this.name = "UnregisteredSchemaVersionError";
+    }
+}
+exports.UnregisteredSchemaVersionError = UnregisteredSchemaVersionError;

package/dist/dispatcher.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Dispatcher SDK public API.
+ *
+ * This file is the consumer-facing surface every domain imports from. The
+ * shape is locked in by the build plan memo (memos/2026/2026-05-01-platform-
+ * dispatcher-sdk-build-plan §"Consumer-side subscription API"): imperative
+ * `dispatcher.subscribe(eventType, handler)` and `dispatcher.publish(event)`,
+ * with the handler signature returning a typed validated envelope.
+ *
+ * Phase 2 status: `publish` is wired to the Postgres-queue transport per
+ * ADR-0009; producers can emit events today against the live
+ * dispatcher_event table. `subscribe` still throws
+ * `DispatcherNotImplementedError` until Slice 3 lands the consumer-side
+ * polling worker.
+ *
+ * Why ship the API surface before the consumer-side implementation: types
+ * and method signatures are the contract. Domains scaffolding their
+ * subscriber code (Coaching's availability-projection module, Delivery's
+ * coach-day rewrite) compile against this surface today; when the polling
+ * worker lands, the same code starts working without consumer-side changes.
+ */
+import type { EventEmit, PublishResult, SubscribeHandler } from "./types";
+import { DispatcherNotImplementedError, UnregisteredEventTypeError, UnregisteredSchemaVersionError } from "./dispatcher-errors";
+import { type ConsumerLoopOptions } from "./postgres-consumer";
+import { type PublishOptions } from "./postgres-transport";
+export { DispatcherNotImplementedError, UnregisteredEventTypeError, UnregisteredSchemaVersionError, };
+/**
+ * The Dispatcher singleton. Producers and consumers import this directly:
+ *
+ * Producer side:
+ *
+ * ```ts
+ * import { dispatcher } from "@sguild/dispatcher";
+ *
+ * await prisma.$transaction(async (tx) => {
+ *   await tx.creditReservation.update({ where: { id }, data: { state: "locked" } });
+ *   await dispatcher.publish({
+ *     event_type: "credit.locked",
+ *     payload: { credit_reservation_id: id, ... },
+ *     subject: personId,
+ *     actor: "system:revenue",
+ *   }, { tx });
+ * });
+ * ```
+ *
+ * Consumer side (in `<repo>/scripts/<consumer>-subscriber.ts`):
+ *
+ * ```ts
+ * import { configureDispatcher, dispatcher } from "@sguild/dispatcher";
+ *
+ * configureDispatcher({ producer: "coaching", tenantId: "org_sguild" });
+ *
+ * dispatcher.subscribe<CreditLockedPayload>("credit.locked", async (event) => {
+ *   // handle event
+ * });
+ *
+ * await dispatcher.start({ consumer: "coaching-availability-subscriber" });
+ * // process.on("SIGTERM", () => dispatcher.stop());
+ * ```
+ *
+ * Phase 2 status: `publish` is wired to the Postgres-queue transport;
+ * `subscribe` registers the handler in the singleton; `start` begins the
+ * polling worker. LISTEN/NOTIFY wake-up lands in Slice 3b; today the
+ * worker is poll-only at the configured cadence.
+ */
+declare class Dispatcher {
+    private readonly registeredHandlers;
+    private consumerLoop;
+    /**
+     * Publish an event. Auto-populates SDK-controlled envelope fields,
+     * validates envelope and payload against the registry's schemas, and
+     * inserts into the dispatcher_event table using the optional Prisma
+     * transaction client (the producer-transactional-guarantee primitive
+     * ADR-0009 chose). Returns the canonical event_id for retry
+     * correlation per envelope contract §10.6.
+     */
+    publish<TPayload>(emit: EventEmit<TPayload>, options?: PublishOptions): Promise<PublishResult>;
+    /**
+     * Register a handler for an event_type. The handler is invoked
+     * at-most-once per (consumer, event_id) per §9.2 of the envelope
+     * contract; redelivery is handled inside the SDK and does not
+     * surface to the handler unless the handler throws.
+     *
+     * Multiple subscribe calls register multiple handlers (one per
+     * event_type per consumer). Calling subscribe after start() is a
+     * usage error: the polling loop reads the handler list at start
+     * time. Tests reset via __resetForTests().
+     *
+     * @throws UnregisteredEventTypeError if the event_type is not in the
+     *   registry. Catches subscribers wired against typos or unregistered
+     *   event_types at registration time rather than at runtime.
+     */
+    subscribe<TPayload>(event_type: string, handler: SubscribeHandler<TPayload>): void;
+    /**
+     * Start the consumer-side polling worker. Drives the registered
+     * handlers against the dispatcher_event table; each handler receives
+     * its event_type's events in seq order, with dedup, retry, and
+     * dead-letter handling per ADR-0009 §"Decision".
+     *
+     * Resolves when stop() is called and the in-flight batch (if any)
+     * finishes. Otherwise runs forever; consumers typically wire
+     * `process.on("SIGTERM", () => dispatcher.stop())` so a deploy
+     * rollover drains cleanly.
+     */
+    start(options: ConsumerLoopOptions): Promise<void>;
+    /**
+     * Graceful shutdown. The polling loop finishes the current batch
+     * (so an in-flight handler invocation completes rather than getting
+     * cut off) and then exits.
+     */
+    stop(): Promise<void>;
+    /**
+     * Reset registered handlers and the consumer loop. Test-only;
+     * production code does not call this. Allows test harnesses to
+     * subscribe multiple times across test fixtures without spinning up
+     * a fresh process.
+     */
+    __resetForTests(): void;
+}
+/**
+ * Singleton dispatcher instance. Domain code imports this directly.
+ */
+export declare const dispatcher: Dispatcher;

package/dist/dispatcher.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Dispatcher SDK public API.
+ *
+ * This file is the consumer-facing surface every domain imports from. The
+ * shape is locked in by the build plan memo (memos/2026/2026-05-01-platform-
+ * dispatcher-sdk-build-plan §"Consumer-side subscription API"): imperative
+ * `dispatcher.subscribe(eventType, handler)` and `dispatcher.publish(event)`,
+ * with the handler signature returning a typed validated envelope.
+ *
+ * Phase 2 status: `publish` is wired to the Postgres-queue transport per
+ * ADR-0009; producers can emit events today against the live
+ * dispatcher_event table. `subscribe` still throws
+ * `DispatcherNotImplementedError` until Slice 3 lands the consumer-side
+ * polling worker.
+ *
+ * Why ship the API surface before the consumer-side implementation: types
+ * and method signatures are the contract. Domains scaffolding their
+ * subscriber code (Coaching's availability-projection module, Delivery's
+ * coach-day rewrite) compile against this surface today; when the polling
+ * worker lands, the same code starts working without consumer-side changes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatcher = exports.UnregisteredSchemaVersionError = exports.UnregisteredEventTypeError = exports.DispatcherNotImplementedError = void 0;
+const dispatcher_errors_1 = require("./dispatcher-errors");
+Object.defineProperty(exports, "DispatcherNotImplementedError", { enumerable: true, get: function () { return dispatcher_errors_1.DispatcherNotImplementedError; } });
+Object.defineProperty(exports, "UnregisteredEventTypeError", { enumerable: true, get: function () { return dispatcher_errors_1.UnregisteredEventTypeError; } });
+Object.defineProperty(exports, "UnregisteredSchemaVersionError", { enumerable: true, get: function () { return dispatcher_errors_1.UnregisteredSchemaVersionError; } });
+const postgres_consumer_1 = require("./postgres-consumer");
+const registry_1 = require("./registry");
+const postgres_transport_1 = require("./postgres-transport");
+/**
+ * The Dispatcher singleton. Producers and consumers import this directly:
+ *
+ * Producer side:
+ *
+ * ```ts
+ * import { dispatcher } from "@sguild/dispatcher";
+ *
+ * await prisma.$transaction(async (tx) => {
+ *   await tx.creditReservation.update({ where: { id }, data: { state: "locked" } });
+ *   await dispatcher.publish({
+ *     event_type: "credit.locked",
+ *     payload: { credit_reservation_id: id, ... },
+ *     subject: personId,
+ *     actor: "system:revenue",
+ *   }, { tx });
+ * });
+ * ```
+ *
+ * Consumer side (in `<repo>/scripts/<consumer>-subscriber.ts`):
+ *
+ * ```ts
+ * import { configureDispatcher, dispatcher } from "@sguild/dispatcher";
+ *
+ * configureDispatcher({ producer: "coaching", tenantId: "org_sguild" });
+ *
+ * dispatcher.subscribe<CreditLockedPayload>("credit.locked", async (event) => {
+ *   // handle event
+ * });
+ *
+ * await dispatcher.start({ consumer: "coaching-availability-subscriber" });
+ * // process.on("SIGTERM", () => dispatcher.stop());
+ * ```
+ *
+ * Phase 2 status: `publish` is wired to the Postgres-queue transport;
+ * `subscribe` registers the handler in the singleton; `start` begins the
+ * polling worker. LISTEN/NOTIFY wake-up lands in Slice 3b; today the
+ * worker is poll-only at the configured cadence.
+ */
+class Dispatcher {
+    // Subscribe-side state lives on the singleton because the worker
+    // polls handlers registered through this instance. Tests reset via
+    // __resetForTests().
+    registeredHandlers = [];
+    consumerLoop = null;
+    /**
+     * Publish an event. Auto-populates SDK-controlled envelope fields,
+     * validates envelope and payload against the registry's schemas, and
+     * inserts into the dispatcher_event table using the optional Prisma
+     * transaction client (the producer-transactional-guarantee primitive
+     * ADR-0009 chose). Returns the canonical event_id for retry
+     * correlation per envelope contract §10.6.
+     */
+    async publish(emit, options = {}) {
+        // Phase 2 Slice 2: publish is wired to the Postgres-queue transport.
+        // Registry lookup, schema_version resolution, envelope construction,
+        // envelope and payload validation, and the same-transaction insert
+        // all live in the transport layer per ADR-0009 §"Decision". The
+        // public surface here is intentionally thin so the runtime can swap
+        // transports without changing the call shape (the trigger-to-revisit
+        // framework in ADR-0009 names NATS JetStream as the named successor
+        // when one of three trigger conditions fires; that swap rebinds
+        // publishToPostgres → publishToNats here without touching callers).
+        return (0, postgres_transport_1.publishToPostgres)(emit, options);
+    }
+    /**
+     * Register a handler for an event_type. The handler is invoked
+     * at-most-once per (consumer, event_id) per §9.2 of the envelope
+     * contract; redelivery is handled inside the SDK and does not
+     * surface to the handler unless the handler throws.
+     *
+     * Multiple subscribe calls register multiple handlers (one per
+     * event_type per consumer). Calling subscribe after start() is a
+     * usage error: the polling loop reads the handler list at start
+     * time. Tests reset via __resetForTests().
+     *
+     * @throws UnregisteredEventTypeError if the event_type is not in the
+     *   registry. Catches subscribers wired against typos or unregistered
+     *   event_types at registration time rather than at runtime.
+     */
+    subscribe(event_type, handler) {
+        const registration = (0, registry_1.getEventTypeRegistration)(event_type);
+        if (!registration) {
+            throw new dispatcher_errors_1.UnregisteredEventTypeError(event_type);
+        }
+        if (this.consumerLoop) {
+            throw new Error(`dispatcher.subscribe('${event_type}'): cannot register a handler after start(); register all handlers first, then call start({ consumer })`);
+        }
+        this.registeredHandlers.push({
+            eventType: event_type,
+            handler: handler,
+        });
+    }
+    /**
+     * Start the consumer-side polling worker. Drives the registered
+     * handlers against the dispatcher_event table; each handler receives
+     * its event_type's events in seq order, with dedup, retry, and
+     * dead-letter handling per ADR-0009 §"Decision".
+     *
+     * Resolves when stop() is called and the in-flight batch (if any)
+     * finishes. Otherwise runs forever; consumers typically wire
+     * `process.on("SIGTERM", () => dispatcher.stop())` so a deploy
+     * rollover drains cleanly.
+     */
+    async start(options) {
+        if (this.consumerLoop) {
+            throw new Error(`dispatcher.start({ consumer: '${options.consumer}' }): already running; call stop() before starting a new loop`);
+        }
+        if (this.registeredHandlers.length === 0) {
+            throw new Error("dispatcher.start: no handlers registered; call subscribe() at least once before start()");
+        }
+        this.consumerLoop = new postgres_consumer_1.ConsumerLoop(this.registeredHandlers, options);
+        await this.consumerLoop.start();
+    }
+    /**
+     * Graceful shutdown. The polling loop finishes the current batch
+     * (so an in-flight handler invocation completes rather than getting
+     * cut off) and then exits.
+     */
+    async stop() {
+        if (!this.consumerLoop)
+            return;
+        await this.consumerLoop.stop();
+        this.consumerLoop = null;
+    }
+    /**
+     * Reset registered handlers and the consumer loop. Test-only;
+     * production code does not call this. Allows test harnesses to
+     * subscribe multiple times across test fixtures without spinning up
+     * a fresh process.
+     */
+    __resetForTests() {
+        this.registeredHandlers.length = 0;
+        this.consumerLoop = null;
+    }
+}
+/**
+ * Singleton dispatcher instance. Domain code imports this directly.
+ */
+exports.dispatcher = new Dispatcher();