@sguild/dispatcher 2.0.0

package/dist/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Dispatcher SDK envelope types.
+ *
+ * Mirrors the Sguild Event Envelope JSON Schema at
+ * coordination/contracts/event-envelope/schema/envelope-v1.json
+ * (sourced from contracts/event-envelope/README.md v1.0.2).
+ *
+ * Per §8.2 of the envelope contract, payload schema versioning is per-event-type
+ * and independent of envelope versioning. The generic `TPayload` parameter on
+ * `EventEnvelope` lets callers narrow the payload type at the call site.
+ */
+/**
+ * Closed set of producer domains per the closed-domain rule in
+ * coordination/CONVENTIONS.md and coordination/domains/README.md.
+ *
+ * Coaching was added on 2026-05-01 by ADR-0008. `operations` was the legacy
+ * value during the 2026-04-27 to 2026-05-11 deprecation window per the v1.0.1
+ * changelog of contracts/event-envelope/README.md and is included here so the
+ * type accepts events emitted under the legacy name; consumers MUST treat
+ * `operations` and `delivery` as the same producer per §4.1.
+ */
+export type ProducerDomain = "platform" | "growth" | "sales" | "delivery" | "revenue" | "coaching" | "operations";
+/**
+ * Live producer domains. Excludes the `operations` deprecation alias. New code
+ * SHOULD constrain to this type rather than the broader `ProducerDomain` to
+ * avoid emitting the deprecated value.
+ */
+export type LiveProducerDomain = Exclude<ProducerDomain, "operations">;
+/**
+ * Actor reference per §4.2 of the envelope contract. Either a Person ID
+ * (human-triggered) or `system:<domain>` (automated).
+ */
+export type ActorRef = `per_${string}` | `system:${LiveProducerDomain}`;
+/**
+ * Canonical entity ID prefix-and-UUID-v7 shape per ADR-0002. Used for the
+ * `subject` field. Specific role-record prefixes (per_, lead_, par_, coa_,
+ * crr_, crd_acct_, les_, etc.) are validated by the JSON Schema's regex; the
+ * TS type stays loose because the closed-set of prefixes is broader than the
+ * type system can usefully express here.
+ */
+export type CanonicalEntityId = `${string}_${string}`;
+/**
+ * The envelope every cross-domain event rides on. Required and optional fields
+ * per §4.1 and §4.2 of the contract.
+ *
+ * @typeParam TPayload - the event-specific payload shape, narrowed per
+ *   (event_type, schema_version) by the consumer at the call site.
+ */
+export type EventEnvelope<TPayload = unknown> = {
+    /** evt_<UUID v7 canonical>. Globally unique per ADR-0002. */
+    event_id: string;
+    /** Dotted lowercase noun.verb. Must be registered in the event-type registry. */
+    event_type: string;
+    /** ISO 8601 UTC, producer wall-clock at the moment the event happened. */
+    occurred_at: string;
+    /** Tenant scoping per ADR-0001. */
+    tenant_id: string;
+    /** Which domain emitted the event. */
+    producer: ProducerDomain;
+    /** Per-event-type schema version. Independent of envelope version per §8.2. */
+    schema_version: number;
+    /** Event-specific data; shape determined by (event_type, schema_version). */
+    payload: TPayload;
+    /** Optional. The primary entity the event is about. Usually a person_id. */
+    subject?: CanonicalEntityId;
+    /** Optional. The human or system that caused the event. */
+    actor?: ActorRef;
+    /** Optional. The originating event in a chain. */
+    correlation_id?: string;
+};
+/**
+ * The minimum a producer supplies to `dispatcher.publish`. The SDK fills in
+ * `event_id`, `occurred_at`, `tenant_id`, `producer`, and `schema_version`
+ * automatically per §10.2 of the envelope contract; producers populate
+ * `event_type`, `payload`, and the optional fields.
+ *
+ * Note: `schema_version` defaults to the active version registered in the
+ * event-type registry for `event_type`. Producers emitting at a non-default
+ * version (during a transition window) supply it explicitly via `EventEmit`.
+ */
+export type EventEmit<TPayload = unknown> = {
+    event_type: string;
+    payload: TPayload;
+    schema_version?: number;
+    subject?: CanonicalEntityId;
+    actor?: ActorRef;
+    correlation_id?: string;
+};
+/**
+ * Subscriber handler signature. Per §9.2 of the envelope contract, the SDK
+ * dedupes over `(consumer, event_id)` so handlers are invoked at-most-once
+ * per (consumer, event_id) pair (when the SDK ships; today the SDK is in
+ * Phase 0 per memos/2026/2026-05-01-platform-dispatcher-sdk-build-plan).
+ *
+ * Handlers MUST throw on processing failure to invoke the SDK's retry path.
+ * Swallowing exceptions silently bypasses the dead-letter machinery.
+ */
+export type SubscribeHandler<TPayload = unknown> = (envelope: EventEnvelope<TPayload>) => Promise<void>;
+/**
+ * Result of a successful `dispatcher.publish` call. Returns the canonical
+ * `event_id` so the producer can correlate retries (per §10.6 of the envelope
+ * contract: producers SHALL reuse the same event_id on retry so consumer dedup
+ * works).
+ */
+export type PublishResult = {
+    event_id: string;
+};

package/dist/types.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Dispatcher SDK envelope types.
+ *
+ * Mirrors the Sguild Event Envelope JSON Schema at
+ * coordination/contracts/event-envelope/schema/envelope-v1.json
+ * (sourced from contracts/event-envelope/README.md v1.0.2).
+ *
+ * Per §8.2 of the envelope contract, payload schema versioning is per-event-type
+ * and independent of envelope versioning. The generic `TPayload` parameter on
+ * `EventEnvelope` lets callers narrow the payload type at the call site.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/validator.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Dispatcher payload and envelope validation.
+ *
+ * ADR-0009 action item 8: every emit validates payload against the
+ * registered JSON Schema for `(event_type, schema_version)` before the
+ * row hits dispatcher_event. The validator runs producer-side at publish
+ * time so unschema'd payloads never reach consumers; consumers also
+ * re-validate at subscribe time per envelope contract §5.
+ *
+ * Schemas live in two places per the event-envelope contract:
+ *
+ *   - The envelope schema at
+ *     `coordination/contracts/event-envelope/schema/envelope-v1.json`
+ *     applies to every envelope the SDK builds. Validated once per
+ *     publish; cached after first compile.
+ *
+ *   - Per-event-type payload schemas at
+ *     `coordination/contracts/<contract>/schema/payloads/<event_type>-v<schema_version>.json`
+ *     (path resolved from the registry's `payload_schema` field). One
+ *     compiled validator per (event_type, schema_version), cached on
+ *     first use.
+ *
+ * Validation failures throw `PayloadValidationError` or
+ * `EnvelopeValidationError` with the ajv-shaped error list attached so
+ * callers can surface useful messages.
+ */
+import type { ErrorObject } from "ajv";
+export declare class EnvelopeValidationError extends Error {
+    readonly errors: ErrorObject[];
+    constructor(errors: ErrorObject[]);
+}
+export declare class PayloadValidationError extends Error {
+    readonly eventType: string;
+    readonly schemaVersion: number;
+    readonly errors: ErrorObject[];
+    constructor(eventType: string, schemaVersion: number, errors: ErrorObject[]);
+}
+export declare class PayloadSchemaUnavailableError extends Error {
+    readonly eventType: string;
+    readonly schemaVersion: number;
+    constructor(eventType: string, schemaVersion: number);
+}
+/**
+ * Validate an envelope against the published JSON Schema. Throws
+ * EnvelopeValidationError on failure with the ajv error list attached.
+ * Idempotent: the compiled validator caches across calls.
+ */
+export declare function validateEnvelope(envelope: unknown): void;
+/**
+ * Validate a payload against the registered JSON Schema for
+ * (event_type, schema_version). Throws PayloadValidationError on
+ * validation failure or PayloadSchemaUnavailableError when the registry
+ * has no `payload_schema` recorded for the version (which is itself a
+ * registry-hygiene problem the producer should fix before emitting).
+ */
+export declare function validatePayload(eventType: string, schemaVersion: number, payload: unknown): void;
+/**
+ * Reset the compiled-validator caches. Test-only.
+ */
+export declare function __resetValidatorCachesForTests(): void;

package/dist/validator.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Dispatcher payload and envelope validation.
+ *
+ * ADR-0009 action item 8: every emit validates payload against the
+ * registered JSON Schema for `(event_type, schema_version)` before the
+ * row hits dispatcher_event. The validator runs producer-side at publish
+ * time so unschema'd payloads never reach consumers; consumers also
+ * re-validate at subscribe time per envelope contract §5.
+ *
+ * Schemas live in two places per the event-envelope contract:
+ *
+ *   - The envelope schema at
+ *     `coordination/contracts/event-envelope/schema/envelope-v1.json`
+ *     applies to every envelope the SDK builds. Validated once per
+ *     publish; cached after first compile.
+ *
+ *   - Per-event-type payload schemas at
+ *     `coordination/contracts/<contract>/schema/payloads/<event_type>-v<schema_version>.json`
+ *     (path resolved from the registry's `payload_schema` field). One
+ *     compiled validator per (event_type, schema_version), cached on
+ *     first use.
+ *
+ * Validation failures throw `PayloadValidationError` or
+ * `EnvelopeValidationError` with the ajv-shaped error list attached so
+ * callers can surface useful messages.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PayloadSchemaUnavailableError = exports.PayloadValidationError = exports.EnvelopeValidationError = void 0;
+exports.validateEnvelope = validateEnvelope;
+exports.validatePayload = validatePayload;
+exports.__resetValidatorCachesForTests = __resetValidatorCachesForTests;
+const node_fs_1 = require("node:fs");
+const _2020_1 = __importDefault(require("ajv/dist/2020"));
+const ajv_formats_1 = __importDefault(require("ajv-formats"));
+const registry_1 = require("./registry");
+const resolve_contract_path_1 = require("./internal/resolve-contract-path");
+// =============================================================================
+// ajv setup. Single instance, shared across the process. `strict: false`
+// because the contract schemas use a few patterns ajv's strict mode
+// rejects (notably draft-2020-12 features used loosely); the contracts
+// pass schema linting separately so loose validation here is acceptable.
+// addFormats wires up ISO 8601 date-time, uri, etc. for schema fields
+// that use `format`.
+// =============================================================================
+const ajv = new _2020_1.default({ allErrors: true, strict: false });
+(0, ajv_formats_1.default)(ajv);
+let cachedEnvelopeValidator = null;
+const payloadValidatorCache = new Map();
+// The envelope schema ships bundled inside the package's contracts tree
+// (rooted at `contracts/` exactly as the coordination repo stores it).
+// `resolveContractPath` handles the module-relative and cwd-relative
+// layouts, including the sibling coordination repo fallback.
+const ENVELOPE_SCHEMA_REL_PATH = "contracts/event-envelope/schema/envelope-v1.json";
+// =============================================================================
+// Errors
+// =============================================================================
+class EnvelopeValidationError extends Error {
+    errors;
+    constructor(errors) {
+        super(`Envelope failed JSON Schema validation: ${errors
+            .map((e) => `${e.instancePath || "/"} ${e.message}`)
+            .join("; ")}`);
+        this.errors = errors;
+        this.name = "EnvelopeValidationError";
+    }
+}
+exports.EnvelopeValidationError = EnvelopeValidationError;
+class PayloadValidationError extends Error {
+    eventType;
+    schemaVersion;
+    errors;
+    constructor(eventType, schemaVersion, errors) {
+        super(`Payload for event_type='${eventType}' schema_version=${schemaVersion} failed JSON Schema validation: ${errors
+            .map((e) => `${e.instancePath || "/"} ${e.message}`)
+            .join("; ")}`);
+        this.eventType = eventType;
+        this.schemaVersion = schemaVersion;
+        this.errors = errors;
+        this.name = "PayloadValidationError";
+    }
+}
+exports.PayloadValidationError = PayloadValidationError;
+class PayloadSchemaUnavailableError extends Error {
+    eventType;
+    schemaVersion;
+    constructor(eventType, schemaVersion) {
+        super(`No payload schema registered for event_type='${eventType}' schema_version=${schemaVersion}. ` +
+            `Author the schema at coordination/contracts/<contract>/schema/payloads/<event_type>-v<schema_version>.json ` +
+            `and update the registry's payload_schema field before emitting.`);
+        this.eventType = eventType;
+        this.schemaVersion = schemaVersion;
+        this.name = "PayloadSchemaUnavailableError";
+    }
+}
+exports.PayloadSchemaUnavailableError = PayloadSchemaUnavailableError;
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Validate an envelope against the published JSON Schema. Throws
+ * EnvelopeValidationError on failure with the ajv error list attached.
+ * Idempotent: the compiled validator caches across calls.
+ */
+function validateEnvelope(envelope) {
+    const validator = getEnvelopeValidator();
+    const ok = validator(envelope);
+    if (!ok) {
+        throw new EnvelopeValidationError(validator.errors ?? []);
+    }
+}
+/**
+ * Validate a payload against the registered JSON Schema for
+ * (event_type, schema_version). Throws PayloadValidationError on
+ * validation failure or PayloadSchemaUnavailableError when the registry
+ * has no `payload_schema` recorded for the version (which is itself a
+ * registry-hygiene problem the producer should fix before emitting).
+ */
+function validatePayload(eventType, schemaVersion, payload) {
+    const validator = getPayloadValidator(eventType, schemaVersion);
+    const ok = validator(payload);
+    if (!ok) {
+        throw new PayloadValidationError(eventType, schemaVersion, validator.errors ?? []);
+    }
+}
+/**
+ * Reset the compiled-validator caches. Test-only.
+ */
+function __resetValidatorCachesForTests() {
+    cachedEnvelopeValidator = null;
+    payloadValidatorCache.clear();
+}
+// =============================================================================
+// Internal
+// =============================================================================
+function getEnvelopeValidator() {
+    if (cachedEnvelopeValidator)
+        return cachedEnvelopeValidator;
+    const schemaPath = (0, resolve_contract_path_1.resolveContractPath)(__dirname, ENVELOPE_SCHEMA_REL_PATH);
+    const raw = (0, node_fs_1.readFileSync)(schemaPath, "utf8");
+    const schema = JSON.parse(raw);
+    cachedEnvelopeValidator = ajv.compile(schema);
+    return cachedEnvelopeValidator;
+}
+function getPayloadValidator(eventType, schemaVersion) {
+    const cacheKey = `${eventType}@${schemaVersion}`;
+    const cached = payloadValidatorCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const registration = (0, registry_1.getEventTypeRegistration)(eventType, (0, registry_1.loadRegistry)());
+    if (!registration) {
+        throw new PayloadSchemaUnavailableError(eventType, schemaVersion);
+    }
+    const versionEntry = registration.schema_versions.find((v) => v.version === schemaVersion);
+    if (!versionEntry || !versionEntry.payload_schema) {
+        throw new PayloadSchemaUnavailableError(eventType, schemaVersion);
+    }
+    // The registry stores the payload-schema path rooted at `contracts/`
+    // exactly as the coordination repo does. The dispatcher reads it from the
+    // bundled contracts tree (resolveContractPath handles the layout
+    // waterfall, including the sibling coordination repo fallback).
+    const schemaPath = (0, resolve_contract_path_1.resolveContractPath)(__dirname, versionEntry.payload_schema);
+    const raw = (0, node_fs_1.readFileSync)(schemaPath, "utf8");
+    const schema = JSON.parse(raw);
+    const validator = ajv.compile(schema);
+    payloadValidatorCache.set(cacheKey, validator);
+    return validator;
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@sguild/dispatcher",
+  "version": "2.0.0",
+  "description": "Cross-domain event dispatcher SDK for Sguild domains, per the Sguild Event Envelope contract and ADR-0009. Producer-side transactional emit, consumer-side polling worker with dedup/retry/dead-letter, envelope and payload validation against the bundled contracts tree.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sguild-admin/platform.git",
+    "directory": "lib/dispatcher"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "contracts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "pg": "^8.17.2"
+  },
+  "peerDependencies": {
+    "@prisma/client": ">=7"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/pg": "^8.16.0",
+    "typescript": "^5.2.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}