@happyvertical/smrt-core 0.30.0

package/dist/dispatch/bus.js

@@ -0,0 +1,583 @@
+import { createLogger } from "@happyvertical/logger";
+import { getDatabase } from "@happyvertical/sql";
+import { ensureDispatchSystemTableCompatibility, ensureDispatchSubscriptionsSystemTableCompatibility } from "../system/compatibility.js";
+import { CREATE_SMRT_DISPATCH_TABLE, CREATE_SMRT_DISPATCH_SUBSCRIPTIONS_TABLE } from "../system/schema.js";
+import { DispatchCollection } from "./collections/Dispatches.js";
+import { DispatchSubscriptionCollection } from "./collections/DispatchSubscriptions.js";
+import { Dispatch } from "./models/Dispatch.js";
+import { DispatchSubscription } from "./models/DispatchSubscription.js";
+import { resolveDispatchTenantId, resolveDispatchTenantScope } from "./tenant-resolver.js";
+const logger = createLogger({ level: "info" });
+class DispatchBus {
+  db;
+  handlers = /* @__PURE__ */ new Map();
+  initialized = false;
+  /**
+   * Reserved subscriber name used internally for in-memory `on()` handlers.
+   * Callers may not register persistent subscriptions under this name, nor
+   * assert it as an emit `source`, so they cannot impersonate the in-memory
+   * pseudo-subscriber (S5 #1398).
+   */
+  static RESERVED_SUBSCRIBER = "_in_memory_";
+  /** Maximum stored length of a caller-asserted dispatch source label. */
+  static MAX_SOURCE_LENGTH = 256;
+  /**
+   * Normalize a caller-asserted `source` into untrusted metadata.
+   *
+   * `source` is a declared label, not an authenticated identity, so it must not
+   * be trusted for authorization. This caps its length and **rejects** the
+   * reserved internal sentinel (`_in_memory_`) by throwing — the contract is
+   * that the sentinel is not an accepted source, so a caller cannot quietly
+   * impersonate the in-memory subscriber pseudo-source (S5 #1398). Empty/missing
+   * values default to `'unknown'` (unchanged behavior).
+   *
+   * @throws Error if `source` is the reserved in-memory sentinel.
+   */
+  static sanitizeSource(source) {
+    const raw = (source ?? "").trim();
+    if (!raw) {
+      return "unknown";
+    }
+    if (raw === DispatchBus.RESERVED_SUBSCRIBER) {
+      throw new Error(
+        `DispatchBus.emit: "${DispatchBus.RESERVED_SUBSCRIBER}" is a reserved source and cannot be asserted`
+      );
+    }
+    return raw.slice(0, DispatchBus.MAX_SOURCE_LENGTH);
+  }
+  /**
+   * Create a new DispatchBus (use createDispatchBus factory instead)
+   */
+  constructor(db) {
+    this.db = db;
+  }
+  /**
+   * Initialize the dispatch tables
+   */
+  async initialize() {
+    if (this.initialized) return;
+    const dispatchExists = await DispatchCollection.tableExists(this.db);
+    if (!dispatchExists) {
+      const statements = CREATE_SMRT_DISPATCH_TABLE.split(";").filter(
+        (s) => s.trim()
+      );
+      for (const stmt of statements) {
+        await this.db.query(stmt);
+      }
+    } else {
+      await ensureDispatchSystemTableCompatibility(this.db);
+    }
+    const subsExists = await DispatchSubscriptionCollection.tableExists(
+      this.db
+    );
+    if (!subsExists) {
+      const statements = CREATE_SMRT_DISPATCH_SUBSCRIPTIONS_TABLE.split(
+        ";"
+      ).filter((s) => s.trim());
+      for (const stmt of statements) {
+        await this.db.query(stmt);
+      }
+    } else {
+      await ensureDispatchSubscriptionsSystemTableCompatibility(this.db);
+    }
+    this.initialized = true;
+  }
+  /**
+   * Emits a dispatch message.
+   *
+   * Two things happen atomically (from the caller's perspective):
+   * 1. One or more `Dispatch` rows are inserted with `status: 'pending'` into `_smrt_dispatch`.
+   * 2. All matching in-memory handlers (registered via `on()`) are invoked
+   *    fire-and-forget (errors are caught and logged, not thrown back to the caller).
+   *
+   * Persistent subscriptions registered via `subscribe()` will see this dispatch
+   * the next time `process(subscriber, handler)` is called for their subscriber name.
+   *
+   * **Delivery modes** affect how dispatches are created:
+   * - `compete` subscribers share a single dispatch (`target_subscriber = NULL`).
+   *   First subscriber to `process()` claims it (at-most-once delivery).
+   * - `fanout` subscribers each get their own dispatch copy (`target_subscriber` set
+   *   to the subscriber name), so each processes independently.
+   *
+   * If no subscriptions exist, one dispatch is created for future processing.
+   *
+   * **Security (S5 #1398):**
+   * - `tenant_id` is derived **server-side** from the active tenant context and
+   *   is never read from caller options, so it cannot be spoofed. Subscribers in
+   *   a different tenant cannot see or claim this dispatch (see {@link process}).
+   *   When there is no active tenant context (system/global), `tenant_id` is
+   *   `NULL` and the dispatch is visible to all scopes — preserving pre-tenancy
+   *   behavior.
+   * - `options.source` is **caller-asserted, untrusted metadata** — it is a
+   *   declared label only and must not be relied on as an authenticated emitter
+   *   identity. It is length-capped and the reserved internal sentinel
+   *   (`_in_memory_`) is rejected so a caller cannot impersonate the in-memory
+   *   subscriber pseudo-source.
+   *
+   * @param type - Signal type string, e.g. `'campaign.completed'` or `'invoice.paid'`
+   * @param payload - Any JSON-serializable data to attach to the dispatch
+   * @param options.source - Declared (untrusted) name of the emitting agent/component (default `'unknown'`)
+   * @param options.sourceId - Optional ID of the specific emitting entity
+   * @param options.metadata - Optional additional JSON metadata for the dispatch record
+   * @returns A persisted `Dispatch` instance (the compete dispatch, or the first fanout copy if fanout-only)
+   *
+   * @example
+   * ```typescript
+   * const dispatch = await bus.emit(
+   *   'campaign.completed',
+   *   { campaignId: 'cmp-001', impressions: 10_000 },
+   *   { source: 'suasor', sourceId: agentId },
+   * );
+   * console.log(dispatch.id); // UUID of the created dispatch record
+   * ```
+   *
+   * @see {@link on} for in-memory handlers
+   * @see {@link subscribe} for persistent subscriptions
+   * @see {@link process} to consume pending dispatches
+   */
+  async emit(type, payload, options = {}) {
+    await this.initialize();
+    const tenantId = resolveDispatchTenantId() ?? null;
+    const source = DispatchBus.sanitizeSource(options.source);
+    const matchingSubs = await DispatchSubscriptionCollection.findBySignalType(
+      this.db,
+      type,
+      resolveDispatchTenantScope()
+    );
+    const fanoutSubs = matchingSubs.filter((s) => s.delivery === "fanout");
+    const competeSubs = matchingSubs.filter((s) => s.delivery !== "fanout");
+    const dispatch = new Dispatch({
+      type,
+      source,
+      source_id: options.sourceId || null,
+      payload: JSON.stringify(payload || {}),
+      metadata: JSON.stringify(options.metadata || {}),
+      status: "pending",
+      correlation_id: options.correlationId || null,
+      tenant_id: tenantId
+    });
+    let returnDispatch = dispatch;
+    for (const sub of fanoutSubs) {
+      const fanoutDispatch = new Dispatch({
+        type,
+        source,
+        source_id: options.sourceId || null,
+        payload: JSON.stringify(payload || {}),
+        metadata: JSON.stringify(options.metadata || {}),
+        status: "pending",
+        target_subscriber: sub.subscriber,
+        correlation_id: options.correlationId || null,
+        tenant_id: tenantId
+      });
+      await DispatchCollection.insert(this.db, fanoutDispatch);
+      if (competeSubs.length === 0 && matchingSubs.length > 0) {
+        returnDispatch = fanoutDispatch;
+      }
+    }
+    if (competeSubs.length > 0 || matchingSubs.length === 0) {
+      await DispatchCollection.insert(this.db, dispatch);
+    }
+    this.notifyHandlers(type, payload, dispatch.getMetadata());
+    return returnDispatch;
+  }
+  /**
+   * Registers an in-memory handler for a signal type pattern.
+   *
+   * In-memory handlers are called immediately (fire-and-forget) during `emit()`.
+   * They are stored only in memory and lost on process restart — use `subscribe()`
+   * for durable, restart-safe subscriptions.
+   *
+   * Pattern matching supports a single-segment wildcard `*`:
+   * - `'campaign.*'` matches `'campaign.completed'` and `'campaign.failed'`
+   * - `'campaign.*'` does **not** match `'campaign.phase.two'`
+   *
+   * Multiple handlers may be registered for the same pattern — all will be called.
+   *
+   * @param pattern - Signal type pattern, optionally with a trailing `.*` wildcard
+   * @param handler - Async or sync function to call with `(payload, metadata)`
+   *
+   * @example
+   * ```typescript
+   * bus.on('invoice.*', async (payload, metadata) => {
+   *   console.log(`Invoice event from ${metadata.source}:`, payload);
+   * });
+   * ```
+   *
+   * @see {@link off} to remove a handler
+   * @see {@link subscribe} for persistent (restart-safe) subscriptions
+   */
+  on(pattern, handler) {
+    const subscription = new DispatchSubscription({
+      signal_type: pattern,
+      subscriber: "_in_memory_",
+      handler: "callback"
+    });
+    const registered = { pattern, handler, subscription };
+    if (!this.handlers.has(pattern)) {
+      this.handlers.set(pattern, []);
+    }
+    this.handlers.get(pattern)?.push(registered);
+  }
+  /**
+   * Remove an in-memory handler
+   *
+   * @param pattern - Signal type pattern
+   * @param handler - Handler function to remove
+   * @returns True if handler was found and removed
+   */
+  off(pattern, handler) {
+    const handlers = this.handlers.get(pattern);
+    if (!handlers) return false;
+    const index = handlers.findIndex((h) => h.handler === handler);
+    if (index === -1) return false;
+    handlers.splice(index, 1);
+    if (handlers.length === 0) {
+      this.handlers.delete(pattern);
+    }
+    return true;
+  }
+  /**
+   * Creates or updates a persistent subscription in the database.
+   *
+   * Persistent subscriptions survive process restarts. When `process(subscriber, handler)`
+   * is called later, all pending dispatches matching this subscriber's signal patterns
+   * will be delivered.
+   *
+   * Calling `subscribe()` with the same `signalType`/`subscriber` pair is idempotent
+   * (upsert) — it is safe to call on every agent startup.
+   *
+   * Set `delivery: 'fanout'` to give each subscriber their own dispatch copy.
+   * Default is `'compete'` (at-most-once, first subscriber to process claims it).
+   *
+   * @param options.signalType - Signal type pattern to subscribe to (wildcards supported)
+   * @param options.subscriber - Name that identifies this subscriber (e.g. agent class name)
+   * @param options.handler - Optional method name on the subscriber to call (default `'handleDispatch'`)
+   * @param options.delivery - `'compete'` (default) for at-most-once, `'fanout'` for per-subscriber copies
+   * @param options.enabled - If `false`, subscription is created but disabled (default `true`)
+   *
+   * @example
+   * ```typescript
+   * // Subscribe on agent startup (idempotent)
+   * await bus.subscribe({ signalType: 'campaign.*', subscriber: 'FiscusAgent' });
+   *
+   * // Fan-out: each subscriber gets their own dispatch copy
+   * await bus.subscribe({
+   *   signalType: 'campaign.*',
+   *   subscriber: 'AuditorAgent',
+   *   delivery: 'fanout',
+   * });
+   *
+   * // Later, process matching pending dispatches
+   * await bus.process('FiscusAgent', async (payload, metadata) => { ... });
+   * ```
+   *
+   * @see {@link process} to consume pending dispatches for this subscriber
+   * @see {@link unsubscribe} to remove the subscription
+   * @see {@link on} for non-persistent in-memory handling
+   */
+  async subscribe(options) {
+    await this.initialize();
+    const subscriber = (options.subscriber ?? "").trim();
+    if (!subscriber) {
+      throw new Error("DispatchBus.subscribe requires a non-empty subscriber");
+    }
+    if (subscriber === DispatchBus.RESERVED_SUBSCRIBER) {
+      throw new Error(
+        `DispatchBus.subscribe: "${DispatchBus.RESERVED_SUBSCRIBER}" is a reserved subscriber name`
+      );
+    }
+    const signalType = (options.signalType ?? "").trim();
+    if (!signalType) {
+      throw new Error("DispatchBus.subscribe requires a non-empty signalType");
+    }
+    const subscription = new DispatchSubscription({
+      signal_type: signalType,
+      subscriber,
+      handler: options.handler || "handleDispatch",
+      delivery: options.delivery || "compete",
+      enabled: options.enabled !== false ? 1 : 0,
+      // Server-derived tenant scope (never from caller options). NULL when there
+      // is no active tenant context (global subscription).
+      tenant_id: resolveDispatchTenantId() ?? null
+    });
+    await DispatchSubscriptionCollection.upsert(this.db, subscription);
+  }
+  /**
+   * Remove a persistent subscription
+   *
+   * @param signalType - Signal type pattern
+   * @param subscriber - Subscriber name
+   */
+  async unsubscribe(signalType, subscriber) {
+    await this.initialize();
+    await DispatchSubscriptionCollection.deleteByKey(
+      this.db,
+      signalType,
+      subscriber,
+      resolveDispatchTenantScope()
+    );
+  }
+  /**
+   * Processes pending dispatches for a named subscriber.
+   *
+   * For each matching `pending` dispatch:
+   * 1. Sets status to `processing`
+   * 2. Calls `handler(payload, metadata)`
+   * 3. On success: sets status to `completed`
+   * 4. On error: sets status to `failed` (stores the error message)
+   *
+   * Uses a wildcard-aware query strategy: subscriptions with `*` patterns fetch
+   * all pending dispatches and filter in memory; exact-match subscriptions use
+   * a direct SQL `IN` query for efficiency.
+   *
+   * @param subscriber - The subscriber name (must match a `subscribe()` call)
+   * @param handler - Function to call for each pending dispatch
+   * @param options.limit - Maximum dispatches to process in one call (default 100)
+   * @param options.signalTypes - Optional filter to process only specific signal types
+   * @returns Number of dispatches successfully processed (excludes failed)
+   *
+   * @example
+   * ```typescript
+   * const count = await bus.process('FiscusAgent', async (payload, metadata) => {
+   *   if (metadata.signalType === 'campaign.completed') {
+   *     await generateInvoice(payload.campaignId);
+   *   }
+   * });
+   * console.log(`Processed ${count} dispatches`);
+   * ```
+   *
+   * @see {@link subscribe} to register the persistent subscription first
+   * @see {@link retry} to reset failed dispatches back to pending
+   */
+  async process(subscriber, handler, options = {}) {
+    await this.initialize();
+    const tenantScope = resolveDispatchTenantScope();
+    const subscriptions = await DispatchSubscriptionCollection.findBySubscriber(
+      this.db,
+      subscriber,
+      true,
+      tenantScope
+    );
+    if (subscriptions.length === 0) {
+      return 0;
+    }
+    const signalTypes = subscriptions.map((s) => s.signalType);
+    const hasWildcards = signalTypes.some((t) => t.includes("*"));
+    const isVisibleToSubscriber = (dispatch) => {
+      if (tenantScope.enforced) {
+        if (tenantScope.tenantId === null) {
+          if (dispatch.tenantId !== null) {
+            return false;
+          }
+        } else if (dispatch.tenantId !== null && dispatch.tenantId !== tenantScope.tenantId) {
+          return false;
+        }
+      }
+      if (dispatch.targetSubscriber === subscriber) {
+        return true;
+      }
+      if (dispatch.targetSubscriber !== null) {
+        return false;
+      }
+      const matchingSub = subscriptions.find(
+        (sub) => sub.matches(dispatch.type)
+      );
+      return matchingSub?.delivery === "compete";
+    };
+    let pendingDispatches;
+    if (hasWildcards) {
+      const allPending = await DispatchCollection.list(this.db, {
+        status: "pending",
+        limit: options.limit || 100,
+        tenantScope
+      });
+      pendingDispatches = allPending.filter(
+        (dispatch) => subscriptions.some((sub) => sub.matches(dispatch.type)) && isVisibleToSubscriber(dispatch)
+      );
+    } else {
+      const raw = await DispatchCollection.findPending(
+        this.db,
+        signalTypes,
+        options.limit || 100,
+        subscriber,
+        tenantScope
+      );
+      pendingDispatches = raw.filter(isVisibleToSubscriber);
+    }
+    if (options.signalTypes && options.signalTypes.length > 0) {
+      pendingDispatches = pendingDispatches.filter(
+        (d) => options.signalTypes?.includes(d.type)
+      );
+    }
+    let processed = 0;
+    for (const dispatch of pendingDispatches) {
+      const claimed = await DispatchCollection.claim(
+        this.db,
+        dispatch,
+        tenantScope
+      );
+      if (!claimed) {
+        continue;
+      }
+      try {
+        await handler(dispatch.payload, dispatch.getMetadata());
+        dispatch.markCompleted(subscriber);
+        await DispatchCollection.update(this.db, dispatch);
+        processed++;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        dispatch.markFailed(errorMessage);
+        await DispatchCollection.update(this.db, dispatch);
+      }
+    }
+    return processed;
+  }
+  /**
+   * Retry failed dispatches
+   *
+   * Resets failed dispatches to pending status so they can be processed again.
+   *
+   * @param options - Retry options
+   * @returns Number of dispatches reset
+   */
+  async retry(options = {}) {
+    await this.initialize();
+    const retryable = await DispatchCollection.findRetryable(
+      this.db,
+      options,
+      resolveDispatchTenantScope()
+    );
+    for (const dispatch of retryable) {
+      dispatch.resetForRetry();
+      await DispatchCollection.update(this.db, dispatch);
+    }
+    return retryable.length;
+  }
+  /**
+   * Clean up old dispatches
+   *
+   * @param options - Cleanup options
+   * @returns Number of dispatches deleted
+   */
+  async cleanup(options = {}) {
+    await this.initialize();
+    return DispatchCollection.cleanup(
+      this.db,
+      options,
+      resolveDispatchTenantScope()
+    );
+  }
+  /**
+   * Lists dispatches, scoped to the active tenant context (S5 #1398).
+   *
+   * The tenant scope is derived **server-side** from the active context and
+   * **overrides any caller-supplied scope** — callers cannot select another
+   * tenant or widen visibility to all tenants. Scoping rules:
+   *
+   * - tenancy off → no tenant filter (pre-tenancy behavior).
+   * - active tenant T → that tenant's dispatches plus global (NULL) dispatches.
+   * - tenancy on but no active tenant → global (NULL) dispatches only
+   *   (fail-closed; never all tenants).
+   *
+   * @param options - Non-tenant list filters (status/type/source/etc.). Any
+   *   `tenantScope` field is ignored and replaced with the server-derived one.
+   */
+  async list(options = {}) {
+    await this.initialize();
+    const { tenantScope: _ignoredCallerScope, ...safeOptions } = options;
+    return DispatchCollection.list(this.db, {
+      ...safeOptions,
+      tenantScope: resolveDispatchTenantScope()
+    });
+  }
+  /**
+   * Gets a dispatch by ID, enforcing the active tenant scope (S5 #1398).
+   *
+   * Applies the same server-derived tenant predicate as {@link list}: a
+   * subscriber in tenant A cannot fetch tenant B's dispatch by id, and when
+   * tenancy is on with no active tenant only global (NULL) dispatches are
+   * returned. Returns `null` when the dispatch exists but is out of scope.
+   */
+  async get(id) {
+    await this.initialize();
+    return DispatchCollection.getScoped(
+      this.db,
+      id,
+      resolveDispatchTenantScope()
+    );
+  }
+  /**
+   * List all subscriptions
+   */
+  async listSubscriptions(subscriber) {
+    await this.initialize();
+    const tenantScope = resolveDispatchTenantScope();
+    if (subscriber) {
+      return DispatchSubscriptionCollection.findBySubscriber(
+        this.db,
+        subscriber,
+        false,
+        tenantScope
+      );
+    }
+    return DispatchSubscriptionCollection.list(this.db, false, tenantScope);
+  }
+  /**
+   * Notify in-memory handlers (fire-and-forget)
+   */
+  notifyHandlers(type, payload, metadata) {
+    const matchingHandlers = [];
+    for (const [, handlers] of this.handlers) {
+      for (const registered of handlers) {
+        if (registered.subscription.matches(type)) {
+          matchingHandlers.push(registered);
+        }
+      }
+    }
+    for (const registered of matchingHandlers) {
+      try {
+        const result = registered.handler(payload, metadata);
+        if (result && typeof result.catch === "function") {
+          void result.catch((error) => {
+            logger.error(
+              `DispatchBus: Handler for "${registered.pattern}" failed`,
+              { error }
+            );
+          });
+        }
+      } catch (error) {
+        logger.error(
+          `DispatchBus: Handler for "${registered.pattern}" failed`,
+          { error }
+        );
+      }
+    }
+  }
+}
+async function createDispatchBus(options = {}) {
+  const dbConfig = options.db || options.persistence;
+  if (!dbConfig) {
+    throw new Error("DispatchBus requires a database configuration");
+  }
+  let db;
+  if (typeof dbConfig === "string") {
+    db = await getDatabase(dbConfig);
+  } else if ("query" in dbConfig) {
+    db = dbConfig;
+  } else if ("type" in dbConfig && "url" in dbConfig) {
+    db = await getDatabase({
+      type: dbConfig.type,
+      url: dbConfig.url
+    });
+  } else {
+    throw new Error("Invalid database configuration for DispatchBus");
+  }
+  const bus = new DispatchBus(db);
+  await bus.initialize();
+  return bus;
+}
+export {
+  DispatchBus,
+  createDispatchBus
+};
+//# sourceMappingURL=bus.js.map

package/dist/dispatch/bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.js","sources":["../../src/dispatch/bus.ts"],"sourcesContent":["/**\n * DispatchBus - Central hub for inter-agent communication\n *\n * The DispatchBus provides both in-memory handlers and persistent subscriptions\n * for asynchronous agent-to-agent messaging.\n *\n * @example\n * ```typescript\n * const bus = await createDispatchBus({ db: { type: 'sqlite', url: 'app.db' } });\n *\n * // In-memory handler (immediate)\n * bus.on('campaign.completed', async (payload, metadata) => {\n *   console.log(`Campaign ${payload.campaignId} completed`);\n * });\n *\n * // Persistent subscription (processed later)\n * await bus.subscribe({ signalType: 'campaign.*', subscriber: 'fiscus' });\n *\n * // Emit a dispatch\n * await bus.emit('campaign.completed', { campaignId: '123' }, { source: 'suasor' });\n *\n * // Process pending dispatches\n * await bus.process('fiscus');\n * ```\n */\n\nimport { createLogger } from '@happyvertical/logger';\nimport type { DatabaseInterface } from '@happyvertical/sql';\nimport { getDatabase } from '@happyvertical/sql';\nimport {\n  ensureDispatchSubscriptionsSystemTableCompatibility,\n  ensureDispatchSystemTableCompatibility,\n} from '../system/compatibility.js';\nimport {\n  CREATE_SMRT_DISPATCH_SUBSCRIPTIONS_TABLE,\n  CREATE_SMRT_DISPATCH_TABLE,\n} from '../system/schema.js';\nimport { DispatchCollection } from './collections/Dispatches.js';\nimport { DispatchSubscriptionCollection } from './collections/DispatchSubscriptions.js';\nimport { Dispatch } from './models/Dispatch.js';\nimport { DispatchSubscription } from './models/DispatchSubscription.js';\nimport {\n  resolveDispatchTenantId,\n  resolveDispatchTenantScope,\n} from './tenant-resolver.js';\nimport type {\n  DispatchBusOptions,\n  DispatchCleanupOptions,\n  DispatchCleanupResult,\n  DispatchEmitOptions,\n  DispatchHandler,\n  DispatchListOptions,\n  DispatchMetadata,\n  DispatchProcessOptions,\n  DispatchRetryOptions,\n  DispatchSubscribeOptions,\n} from './types.js';\n\nconst logger = createLogger({ level: 'info' });\n\n/**\n * Registered in-memory handler\n */\ninterface RegisteredHandler {\n  pattern: string;\n  handler: DispatchHandler;\n  subscription: DispatchSubscription;\n}\n\n/**\n * Central hub for inter-agent messaging with both in-memory and persistent delivery.\n *\n * The `DispatchBus` combines two complementary delivery models:\n *\n * - **In-memory handlers** (`on(pattern, handler)`) — called synchronously (fire-and-forget)\n *   when a dispatch is emitted. Fast, but lost on process restart.\n * - **Persistent subscriptions** (`subscribe({ signalType, subscriber })`) — stored in\n *   `_smrt_dispatch_subscriptions` and processed later by calling `process(subscriber, handler)`.\n *   Survive restarts; suitable for background workers and scheduled agents.\n *\n * Signal types support single-segment wildcards: `'campaign.*'` matches `'campaign.completed'`\n * and `'campaign.failed'`, but not `'campaign.phase.two'`.\n *\n * Dispatch lifecycle: `pending → processing → completed` (or `failed` on handler error).\n * Use `retry()` to reset failed dispatches back to `pending`.\n *\n * Create instances via `createDispatchBus()` — do not use `new DispatchBus()` directly\n * in application code.\n *\n * @example\n * ```typescript\n * const bus = await createDispatchBus({ db: myDb });\n *\n * // In-memory: immediate, fire-and-forget\n * bus.on('invoice.paid', async (payload) => {\n *   console.log('Invoice paid:', payload.invoiceId);\n * });\n *\n * // Persistent: processed by 'notifications' agent on next run\n * await bus.subscribe({ signalType: 'invoice.*', subscriber: 'notifications' });\n *\n * // Emit (notifies in-memory handlers immediately, stores persistent dispatch)\n * await bus.emit('invoice.paid', { invoiceId: 'inv-001' }, { source: 'billing' });\n *\n * // Later, in the notifications agent:\n * await bus.process('notifications', async (payload) => {\n *   await sendEmail(payload.invoiceId);\n * });\n * ```\n */\nexport class DispatchBus {\n  private db: DatabaseInterface;\n  private handlers: Map<string, RegisteredHandler[]> = new Map();\n  private initialized: boolean = false;\n\n  /**\n   * Reserved subscriber name used internally for in-memory `on()` handlers.\n   * Callers may not register persistent subscriptions under this name, nor\n   * assert it as an emit `source`, so they cannot impersonate the in-memory\n   * pseudo-subscriber (S5 #1398).\n   */\n  private static readonly RESERVED_SUBSCRIBER = '_in_memory_';\n\n  /** Maximum stored length of a caller-asserted dispatch source label. */\n  private static readonly MAX_SOURCE_LENGTH = 256;\n\n  /**\n   * Normalize a caller-asserted `source` into untrusted metadata.\n   *\n   * `source` is a declared label, not an authenticated identity, so it must not\n   * be trusted for authorization. This caps its length and **rejects** the\n   * reserved internal sentinel (`_in_memory_`) by throwing — the contract is\n   * that the sentinel is not an accepted source, so a caller cannot quietly\n   * impersonate the in-memory subscriber pseudo-source (S5 #1398). Empty/missing\n   * values default to `'unknown'` (unchanged behavior).\n   *\n   * @throws Error if `source` is the reserved in-memory sentinel.\n   */\n  private static sanitizeSource(source: string | undefined): string {\n    const raw = (source ?? '').trim();\n    if (!raw) {\n      return 'unknown';\n    }\n    if (raw === DispatchBus.RESERVED_SUBSCRIBER) {\n      throw new Error(\n        `DispatchBus.emit: \"${DispatchBus.RESERVED_SUBSCRIBER}\" is a reserved source and cannot be asserted`,\n      );\n    }\n    return raw.slice(0, DispatchBus.MAX_SOURCE_LENGTH);\n  }\n\n  /**\n   * Create a new DispatchBus (use createDispatchBus factory instead)\n   */\n  constructor(db: DatabaseInterface) {\n    this.db = db;\n  }\n\n  /**\n   * Initialize the dispatch tables\n   */\n  async initialize(): Promise<void> {\n    if (this.initialized) return;\n\n    // Create dispatch tables if they don't exist\n    const dispatchExists = await DispatchCollection.tableExists(this.db);\n    if (!dispatchExists) {\n      // Split the DDL into separate statements and execute each\n      const statements = CREATE_SMRT_DISPATCH_TABLE.split(';').filter((s) =>\n        s.trim(),\n      );\n      for (const stmt of statements) {\n        await this.db.query(stmt);\n      }\n    } else {\n      await ensureDispatchSystemTableCompatibility(this.db);\n    }\n\n    const subsExists = await DispatchSubscriptionCollection.tableExists(\n      this.db,\n    );\n    if (!subsExists) {\n      const statements = CREATE_SMRT_DISPATCH_SUBSCRIPTIONS_TABLE.split(\n        ';',\n      ).filter((s) => s.trim());\n      for (const stmt of statements) {\n        await this.db.query(stmt);\n      }\n    } else {\n      await ensureDispatchSubscriptionsSystemTableCompatibility(this.db);\n    }\n\n    this.initialized = true;\n  }\n\n  /**\n   * Emits a dispatch message.\n   *\n   * Two things happen atomically (from the caller's perspective):\n   * 1. One or more `Dispatch` rows are inserted with `status: 'pending'` into `_smrt_dispatch`.\n   * 2. All matching in-memory handlers (registered via `on()`) are invoked\n   *    fire-and-forget (errors are caught and logged, not thrown back to the caller).\n   *\n   * Persistent subscriptions registered via `subscribe()` will see this dispatch\n   * the next time `process(subscriber, handler)` is called for their subscriber name.\n   *\n   * **Delivery modes** affect how dispatches are created:\n   * - `compete` subscribers share a single dispatch (`target_subscriber = NULL`).\n   *   First subscriber to `process()` claims it (at-most-once delivery).\n   * - `fanout` subscribers each get their own dispatch copy (`target_subscriber` set\n   *   to the subscriber name), so each processes independently.\n   *\n   * If no subscriptions exist, one dispatch is created for future processing.\n   *\n   * **Security (S5 #1398):**\n   * - `tenant_id` is derived **server-side** from the active tenant context and\n   *   is never read from caller options, so it cannot be spoofed. Subscribers in\n   *   a different tenant cannot see or claim this dispatch (see {@link process}).\n   *   When there is no active tenant context (system/global), `tenant_id` is\n   *   `NULL` and the dispatch is visible to all scopes — preserving pre-tenancy\n   *   behavior.\n   * - `options.source` is **caller-asserted, untrusted metadata** — it is a\n   *   declared label only and must not be relied on as an authenticated emitter\n   *   identity. It is length-capped and the reserved internal sentinel\n   *   (`_in_memory_`) is rejected so a caller cannot impersonate the in-memory\n   *   subscriber pseudo-source.\n   *\n   * @param type - Signal type string, e.g. `'campaign.completed'` or `'invoice.paid'`\n   * @param payload - Any JSON-serializable data to attach to the dispatch\n   * @param options.source - Declared (untrusted) name of the emitting agent/component (default `'unknown'`)\n   * @param options.sourceId - Optional ID of the specific emitting entity\n   * @param options.metadata - Optional additional JSON metadata for the dispatch record\n   * @returns A persisted `Dispatch` instance (the compete dispatch, or the first fanout copy if fanout-only)\n   *\n   * @example\n   * ```typescript\n   * const dispatch = await bus.emit(\n   *   'campaign.completed',\n   *   { campaignId: 'cmp-001', impressions: 10_000 },\n   *   { source: 'suasor', sourceId: agentId },\n   * );\n   * console.log(dispatch.id); // UUID of the created dispatch record\n   * ```\n   *\n   * @see {@link on} for in-memory handlers\n   * @see {@link subscribe} for persistent subscriptions\n   * @see {@link process} to consume pending dispatches\n   */\n  async emit(\n    type: string,\n    payload: unknown,\n    options: DispatchEmitOptions = {},\n  ): Promise<Dispatch> {\n    await this.initialize();\n\n    // Derive the tenant scope server-side from the active context. This is the\n    // trust anchor for cross-tenant isolation (S5 #1398) — it is never taken\n    // from caller options, so it cannot be spoofed. `undefined`/`null` means\n    // \"no tenant context\" → tenant_id stays NULL (global dispatch).\n    const tenantId = resolveDispatchTenantId() ?? null;\n\n    // Treat the caller-asserted source as untrusted metadata.\n    const source = DispatchBus.sanitizeSource(options.source);\n\n    // Query subscriptions to determine if fan-out copies are needed.\n    // This runs on every emit() — uses SQL-level exact matching with\n    // in-memory fallback only for wildcard subscriptions to minimize I/O.\n    // Scoped to the active tenant so emit only fans out to this tenant's\n    // (and, for global emits, global) subscriptions (S5 #1398).\n    const matchingSubs = await DispatchSubscriptionCollection.findBySignalType(\n      this.db,\n      type,\n      resolveDispatchTenantScope(),\n    );\n\n    // Separate into compete and fanout subscribers\n    const fanoutSubs = matchingSubs.filter((s) => s.delivery === 'fanout');\n    const competeSubs = matchingSubs.filter((s) => s.delivery !== 'fanout');\n\n    // Create the base dispatch record\n    const dispatch = new Dispatch({\n      type,\n      source,\n      source_id: options.sourceId || null,\n      payload: JSON.stringify(payload || {}),\n      metadata: JSON.stringify(options.metadata || {}),\n      status: 'pending',\n      correlation_id: options.correlationId || null,\n      tenant_id: tenantId,\n    });\n\n    // Track first persisted dispatch to return to caller\n    let returnDispatch = dispatch;\n\n    // For fanout subscribers: create a per-subscriber dispatch copy\n    for (const sub of fanoutSubs) {\n      const fanoutDispatch = new Dispatch({\n        type,\n        source,\n        source_id: options.sourceId || null,\n        payload: JSON.stringify(payload || {}),\n        metadata: JSON.stringify(options.metadata || {}),\n        status: 'pending',\n        target_subscriber: sub.subscriber,\n        correlation_id: options.correlationId || null,\n        tenant_id: tenantId,\n      });\n      await DispatchCollection.insert(this.db, fanoutDispatch);\n      // If no compete dispatch will be persisted, return the first fanout copy\n      if (competeSubs.length === 0 && matchingSubs.length > 0) {\n        returnDispatch = fanoutDispatch;\n      }\n    }\n\n    // For compete subscribers (or if no subscriptions found): insert the original\n    // dispatch with target_subscriber = NULL so any compete subscriber can claim it\n    if (competeSubs.length > 0 || matchingSubs.length === 0) {\n      await DispatchCollection.insert(this.db, dispatch);\n    }\n\n    // Notify in-memory handlers immediately (fire-and-forget)\n    this.notifyHandlers(type, payload, dispatch.getMetadata());\n\n    return returnDispatch;\n  }\n\n  /**\n   * Registers an in-memory handler for a signal type pattern.\n   *\n   * In-memory handlers are called immediately (fire-and-forget) during `emit()`.\n   * They are stored only in memory and lost on process restart — use `subscribe()`\n   * for durable, restart-safe subscriptions.\n   *\n   * Pattern matching supports a single-segment wildcard `*`:\n   * - `'campaign.*'` matches `'campaign.completed'` and `'campaign.failed'`\n   * - `'campaign.*'` does **not** match `'campaign.phase.two'`\n   *\n   * Multiple handlers may be registered for the same pattern — all will be called.\n   *\n   * @param pattern - Signal type pattern, optionally with a trailing `.*` wildcard\n   * @param handler - Async or sync function to call with `(payload, metadata)`\n   *\n   * @example\n   * ```typescript\n   * bus.on('invoice.*', async (payload, metadata) => {\n   *   console.log(`Invoice event from ${metadata.source}:`, payload);\n   * });\n   * ```\n   *\n   * @see {@link off} to remove a handler\n   * @see {@link subscribe} for persistent (restart-safe) subscriptions\n   */\n  on(pattern: string, handler: DispatchHandler): void {\n    const subscription = new DispatchSubscription({\n      signal_type: pattern,\n      subscriber: '_in_memory_',\n      handler: 'callback',\n    });\n\n    const registered: RegisteredHandler = { pattern, handler, subscription };\n\n    if (!this.handlers.has(pattern)) {\n      this.handlers.set(pattern, []);\n    }\n    this.handlers.get(pattern)?.push(registered);\n  }\n\n  /**\n   * Remove an in-memory handler\n   *\n   * @param pattern - Signal type pattern\n   * @param handler - Handler function to remove\n   * @returns True if handler was found and removed\n   */\n  off(pattern: string, handler: DispatchHandler): boolean {\n    const handlers = this.handlers.get(pattern);\n    if (!handlers) return false;\n\n    const index = handlers.findIndex((h) => h.handler === handler);\n    if (index === -1) return false;\n\n    handlers.splice(index, 1);\n    if (handlers.length === 0) {\n      this.handlers.delete(pattern);\n    }\n    return true;\n  }\n\n  /**\n   * Creates or updates a persistent subscription in the database.\n   *\n   * Persistent subscriptions survive process restarts. When `process(subscriber, handler)`\n   * is called later, all pending dispatches matching this subscriber's signal patterns\n   * will be delivered.\n   *\n   * Calling `subscribe()` with the same `signalType`/`subscriber` pair is idempotent\n   * (upsert) — it is safe to call on every agent startup.\n   *\n   * Set `delivery: 'fanout'` to give each subscriber their own dispatch copy.\n   * Default is `'compete'` (at-most-once, first subscriber to process claims it).\n   *\n   * @param options.signalType - Signal type pattern to subscribe to (wildcards supported)\n   * @param options.subscriber - Name that identifies this subscriber (e.g. agent class name)\n   * @param options.handler - Optional method name on the subscriber to call (default `'handleDispatch'`)\n   * @param options.delivery - `'compete'` (default) for at-most-once, `'fanout'` for per-subscriber copies\n   * @param options.enabled - If `false`, subscription is created but disabled (default `true`)\n   *\n   * @example\n   * ```typescript\n   * // Subscribe on agent startup (idempotent)\n   * await bus.subscribe({ signalType: 'campaign.*', subscriber: 'FiscusAgent' });\n   *\n   * // Fan-out: each subscriber gets their own dispatch copy\n   * await bus.subscribe({\n   *   signalType: 'campaign.*',\n   *   subscriber: 'AuditorAgent',\n   *   delivery: 'fanout',\n   * });\n   *\n   * // Later, process matching pending dispatches\n   * await bus.process('FiscusAgent', async (payload, metadata) => { ... });\n   * ```\n   *\n   * @see {@link process} to consume pending dispatches for this subscriber\n   * @see {@link unsubscribe} to remove the subscription\n   * @see {@link on} for non-persistent in-memory handling\n   */\n  async subscribe(options: DispatchSubscribeOptions): Promise<void> {\n    await this.initialize();\n\n    // Gate the subscriber namespace (S5 #1398): require a concrete subscriber\n    // name and reject the reserved internal sentinel so callers cannot\n    // register a persistent subscription that masquerades as the in-memory\n    // pseudo-subscriber.\n    const subscriber = (options.subscriber ?? '').trim();\n    if (!subscriber) {\n      throw new Error('DispatchBus.subscribe requires a non-empty subscriber');\n    }\n    if (subscriber === DispatchBus.RESERVED_SUBSCRIBER) {\n      throw new Error(\n        `DispatchBus.subscribe: \"${DispatchBus.RESERVED_SUBSCRIBER}\" is a reserved subscriber name`,\n      );\n    }\n    const signalType = (options.signalType ?? '').trim();\n    if (!signalType) {\n      throw new Error('DispatchBus.subscribe requires a non-empty signalType');\n    }\n\n    const subscription = new DispatchSubscription({\n      signal_type: signalType,\n      subscriber,\n      handler: options.handler || 'handleDispatch',\n      delivery: options.delivery || 'compete',\n      enabled: options.enabled !== false ? 1 : 0,\n      // Server-derived tenant scope (never from caller options). NULL when there\n      // is no active tenant context (global subscription).\n      tenant_id: resolveDispatchTenantId() ?? null,\n    });\n\n    await DispatchSubscriptionCollection.upsert(this.db, subscription);\n  }\n\n  /**\n   * Remove a persistent subscription\n   *\n   * @param signalType - Signal type pattern\n   * @param subscriber - Subscriber name\n   */\n  async unsubscribe(signalType: string, subscriber: string): Promise<void> {\n    await this.initialize();\n    // Scoped to the active tenant so one tenant cannot remove another's\n    // subscription (S5 #1398).\n    await DispatchSubscriptionCollection.deleteByKey(\n      this.db,\n      signalType,\n      subscriber,\n      resolveDispatchTenantScope(),\n    );\n  }\n\n  /**\n   * Processes pending dispatches for a named subscriber.\n   *\n   * For each matching `pending` dispatch:\n   * 1. Sets status to `processing`\n   * 2. Calls `handler(payload, metadata)`\n   * 3. On success: sets status to `completed`\n   * 4. On error: sets status to `failed` (stores the error message)\n   *\n   * Uses a wildcard-aware query strategy: subscriptions with `*` patterns fetch\n   * all pending dispatches and filter in memory; exact-match subscriptions use\n   * a direct SQL `IN` query for efficiency.\n   *\n   * @param subscriber - The subscriber name (must match a `subscribe()` call)\n   * @param handler - Function to call for each pending dispatch\n   * @param options.limit - Maximum dispatches to process in one call (default 100)\n   * @param options.signalTypes - Optional filter to process only specific signal types\n   * @returns Number of dispatches successfully processed (excludes failed)\n   *\n   * @example\n   * ```typescript\n   * const count = await bus.process('FiscusAgent', async (payload, metadata) => {\n   *   if (metadata.signalType === 'campaign.completed') {\n   *     await generateInvoice(payload.campaignId);\n   *   }\n   * });\n   * console.log(`Processed ${count} dispatches`);\n   * ```\n   *\n   * @see {@link subscribe} to register the persistent subscription first\n   * @see {@link retry} to reset failed dispatches back to pending\n   */\n  async process(\n    subscriber: string,\n    handler: DispatchHandler,\n    options: DispatchProcessOptions = {},\n  ): Promise<number> {\n    await this.initialize();\n\n    // Resolve the active tenant scope server-side (S5 #1398). This distinguishes\n    // three states (see resolveDispatchTenantScope):\n    //  - tenancy off → no filter; system/global + non-tenant deployments behave\n    //    exactly as before.\n    //  - active tenant T → only T's dispatches plus global (NULL) dispatches are\n    //    claimable, so a subscriber in tenant A cannot see/claim tenant B's.\n    //  - tenancy on but no active tenant → fail-closed to global (NULL) rows\n    //    only; a missing context never leaks other tenants' dispatches.\n    const tenantScope = resolveDispatchTenantScope();\n\n    // Get subscriber's subscriptions, scoped to the active tenant so a tenant-A\n    // processor only matches tenant-A (and, when global, global) subscriptions.\n    const subscriptions = await DispatchSubscriptionCollection.findBySubscriber(\n      this.db,\n      subscriber,\n      true,\n      tenantScope,\n    );\n\n    if (subscriptions.length === 0) {\n      return 0;\n    }\n\n    // Get signal types (including wildcards)\n    const signalTypes = subscriptions.map((s) => s.signalType);\n\n    // For non-wildcard subscriptions, we can query directly\n    // For wildcards, we need to get all pending and filter\n    const hasWildcards = signalTypes.some((t) => t.includes('*'));\n\n    // Helper: check if a dispatch should be visible to this subscriber\n    const isVisibleToSubscriber = (dispatch: Dispatch): boolean => {\n      // Tenant isolation (defense in depth — the SQL queries below also filter).\n      if (tenantScope.enforced) {\n        if (tenantScope.tenantId === null) {\n          // Tenancy on, no active tenant → only global (NULL) rows are visible.\n          if (dispatch.tenantId !== null) {\n            return false;\n          }\n        } else if (\n          dispatch.tenantId !== null &&\n          dispatch.tenantId !== tenantScope.tenantId\n        ) {\n          // Active tenant → that tenant's rows plus global (NULL) rows only.\n          return false;\n        }\n      }\n      if (dispatch.targetSubscriber === subscriber) {\n        // Targeted at this subscriber (fanout copy) — always visible\n        return true;\n      }\n      if (dispatch.targetSubscriber !== null) {\n        // Targeted at a different subscriber — not visible\n        return false;\n      }\n      // Null target (compete dispatch): only visible if this subscriber\n      // has a compete subscription matching this dispatch type\n      const matchingSub = subscriptions.find((sub) =>\n        sub.matches(dispatch.type),\n      );\n      return matchingSub?.delivery === 'compete';\n    };\n\n    let pendingDispatches: Dispatch[];\n    if (hasWildcards) {\n      // Get all pending dispatches and filter by subscription patterns + target\n      const allPending = await DispatchCollection.list(this.db, {\n        status: 'pending',\n        limit: options.limit || 100,\n        tenantScope,\n      });\n\n      pendingDispatches = allPending.filter(\n        (dispatch) =>\n          subscriptions.some((sub) => sub.matches(dispatch.type)) &&\n          isVisibleToSubscriber(dispatch),\n      );\n    } else {\n      // Direct query for exact signal types (with target_subscriber filter)\n      const raw = await DispatchCollection.findPending(\n        this.db,\n        signalTypes,\n        options.limit || 100,\n        subscriber,\n        tenantScope,\n      );\n      // Post-filter for delivery mode correctness\n      pendingDispatches = raw.filter(isVisibleToSubscriber);\n    }\n\n    // Filter by specific signal types if provided\n    if (options.signalTypes && options.signalTypes.length > 0) {\n      pendingDispatches = pendingDispatches.filter((d) =>\n        options.signalTypes?.includes(d.type),\n      );\n    }\n\n    let processed = 0;\n\n    for (const dispatch of pendingDispatches) {\n      // Atomically claim the dispatch (S5 #1398). The conditional UPDATE\n      // (WHERE id = ? AND status = 'pending' [AND tenant predicate]) closes the\n      // TOCTOU window: if a competing worker — or a system-scoped processor —\n      // already moved this row out of 'pending', our claim affects no rows and\n      // we skip it, so a compete/global dispatch is processed at most once.\n      const claimed = await DispatchCollection.claim(\n        this.db,\n        dispatch,\n        tenantScope,\n      );\n      if (!claimed) {\n        continue;\n      }\n\n      try {\n        // Invoke handler\n        await handler(dispatch.payload, dispatch.getMetadata());\n\n        // Mark as completed\n        dispatch.markCompleted(subscriber);\n        await DispatchCollection.update(this.db, dispatch);\n        processed++;\n      } catch (error) {\n        // Mark as failed\n        const errorMessage =\n          error instanceof Error ? error.message : String(error);\n        dispatch.markFailed(errorMessage);\n        await DispatchCollection.update(this.db, dispatch);\n      }\n    }\n\n    return processed;\n  }\n\n  /**\n   * Retry failed dispatches\n   *\n   * Resets failed dispatches to pending status so they can be processed again.\n   *\n   * @param options - Retry options\n   * @returns Number of dispatches reset\n   */\n  async retry(options: DispatchRetryOptions = {}): Promise<number> {\n    await this.initialize();\n\n    // Tenant isolation (S5 #1398): only the active tenant's failed dispatches\n    // (plus global ones) are eligible — a tenant's retry() must not reset\n    // another tenant's rows. Scope is derived server-side; callers cannot widen\n    // it.\n    const retryable = await DispatchCollection.findRetryable(\n      this.db,\n      options,\n      resolveDispatchTenantScope(),\n    );\n\n    for (const dispatch of retryable) {\n      dispatch.resetForRetry();\n      await DispatchCollection.update(this.db, dispatch);\n    }\n\n    return retryable.length;\n  }\n\n  /**\n   * Clean up old dispatches\n   *\n   * @param options - Cleanup options\n   * @returns Number of dispatches deleted\n   */\n  async cleanup(\n    options: DispatchCleanupOptions = {},\n  ): Promise<DispatchCleanupResult> {\n    await this.initialize();\n    // Tenant isolation (S5 #1398): only the active tenant's dispatches (plus\n    // global ones) are deleted — a tenant's cleanup() must not delete another\n    // tenant's rows. Scope is derived server-side; callers cannot widen it.\n    return DispatchCollection.cleanup(\n      this.db,\n      options,\n      resolveDispatchTenantScope(),\n    );\n  }\n\n  /**\n   * Lists dispatches, scoped to the active tenant context (S5 #1398).\n   *\n   * The tenant scope is derived **server-side** from the active context and\n   * **overrides any caller-supplied scope** — callers cannot select another\n   * tenant or widen visibility to all tenants. Scoping rules:\n   *\n   * - tenancy off → no tenant filter (pre-tenancy behavior).\n   * - active tenant T → that tenant's dispatches plus global (NULL) dispatches.\n   * - tenancy on but no active tenant → global (NULL) dispatches only\n   *   (fail-closed; never all tenants).\n   *\n   * @param options - Non-tenant list filters (status/type/source/etc.). Any\n   *   `tenantScope` field is ignored and replaced with the server-derived one.\n   */\n  async list(options: DispatchListOptions = {}): Promise<Dispatch[]> {\n    await this.initialize();\n    // Strip any caller-supplied scope and inject the server-derived one.\n    const { tenantScope: _ignoredCallerScope, ...safeOptions } = options;\n    return DispatchCollection.list(this.db, {\n      ...safeOptions,\n      tenantScope: resolveDispatchTenantScope(),\n    });\n  }\n\n  /**\n   * Gets a dispatch by ID, enforcing the active tenant scope (S5 #1398).\n   *\n   * Applies the same server-derived tenant predicate as {@link list}: a\n   * subscriber in tenant A cannot fetch tenant B's dispatch by id, and when\n   * tenancy is on with no active tenant only global (NULL) dispatches are\n   * returned. Returns `null` when the dispatch exists but is out of scope.\n   */\n  async get(id: string): Promise<Dispatch | null> {\n    await this.initialize();\n    return DispatchCollection.getScoped(\n      this.db,\n      id,\n      resolveDispatchTenantScope(),\n    );\n  }\n\n  /**\n   * List all subscriptions\n   */\n  async listSubscriptions(\n    subscriber?: string,\n  ): Promise<DispatchSubscription[]> {\n    await this.initialize();\n\n    // Scoped to the active tenant so listing never leaks another tenant's\n    // subscriptions (S5 #1398).\n    const tenantScope = resolveDispatchTenantScope();\n\n    if (subscriber) {\n      return DispatchSubscriptionCollection.findBySubscriber(\n        this.db,\n        subscriber,\n        false,\n        tenantScope,\n      );\n    }\n    return DispatchSubscriptionCollection.list(this.db, false, tenantScope);\n  }\n\n  /**\n   * Notify in-memory handlers (fire-and-forget)\n   */\n  private notifyHandlers(\n    type: string,\n    payload: unknown,\n    metadata: DispatchMetadata,\n  ): void {\n    // Collect all matching handlers\n    const matchingHandlers: RegisteredHandler[] = [];\n\n    for (const [, handlers] of this.handlers) {\n      for (const registered of handlers) {\n        if (registered.subscription.matches(type)) {\n          matchingHandlers.push(registered);\n        }\n      }\n    }\n\n    // Fire-and-forget - don't await\n    for (const registered of matchingHandlers) {\n      try {\n        const result = registered.handler(payload, metadata);\n        // Handle both sync and async handlers\n        if (result && typeof result.catch === 'function') {\n          void result.catch((error: unknown) => {\n            logger.error(\n              `DispatchBus: Handler for \"${registered.pattern}\" failed`,\n              { error },\n            );\n          });\n        }\n      } catch (error) {\n        logger.error(\n          `DispatchBus: Handler for \"${registered.pattern}\" failed`,\n          { error },\n        );\n      }\n    }\n  }\n}\n\n/**\n * Create a DispatchBus instance\n *\n * @param options - Bus configuration\n * @returns Initialized DispatchBus\n */\nexport async function createDispatchBus(\n  options: DispatchBusOptions = {},\n): Promise<DispatchBus> {\n  // Resolve database configuration\n  const dbConfig = options.db || options.persistence;\n\n  if (!dbConfig) {\n    throw new Error('DispatchBus requires a database configuration');\n  }\n\n  // Get or create database interface\n  let db: DatabaseInterface;\n  if (typeof dbConfig === 'string') {\n    db = await getDatabase(dbConfig);\n  } else if ('query' in dbConfig) {\n    // Already a DatabaseInterface (has query method)\n    db = dbConfig as DatabaseInterface;\n  } else if ('type' in dbConfig && 'url' in dbConfig) {\n    // Database config object - use getDatabase with type and url\n    db = await getDatabase({\n      type: dbConfig.type as 'sqlite' | 'postgres' | 'duckdb',\n      url: dbConfig.url,\n    });\n  } else {\n    throw new Error('Invalid database configuration for DispatchBus');\n  }\n\n  const bus = new DispatchBus(db);\n  await bus.initialize();\n\n  return bus;\n}\n"],"names":[],"mappings":"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"}