@open-mercato/events 0.6.5-develop.5382.1.f542de69af → 0.6.5

package/AGENTS.md

@@ -76,6 +76,16 @@ export default async function handler(payload, ctx) { /* ... */ }
 - When `QUEUE_STRATEGY=local`, persistent events process from `.mercato/queue/` (or `QUEUE_BASE_DIR`)
 - Ephemeral subscribers always run in-process regardless of queue strategy
 
+### Persistent delivery: legacy vs single-delivery (`OM_EVENTS_SINGLE_DELIVERY`)
+
+By default (`OM_EVENTS_SINGLE_DELIVERY` unset/false) a persistent emit is delivered on **both** paths: inline to every matching in-memory subscriber **and** through the events worker (exact-match). This double-dispatches exact-match subscribers and never reaches wildcard (`event: '*'`) persistent subscribers in the worker.
+
+Set `OM_EVENTS_SINGLE_DELIVERY=true` to make persistent delivery single-path:
+- the bus skips inline delivery of **persistent-marked** subscribers on a persistent emit (ephemeral subscribers still run inline);
+- the events worker dispatches **persistent** subscribers via `matchEventPattern`, so wildcard persistent subscribers are finally reached.
+
+Both halves are gated by the same flag and MUST move together. When enabling it, ensure the events worker runs (default `AUTO_SPAWN_WORKERS=true`) and validate under both `QUEUE_STRATEGY=local` and `=async` so no persistent subscriber is dropped. This is the "Ask First: changing persistent delivery semantics" gate — the flag defaults off to preserve today's behavior.
+
 ## Queue Integration
 
 | Queue strategy | Ephemeral events | Persistent events |

package/dist/bus.js

@@ -1,10 +1,14 @@
 import { createQueue } from "@open-mercato/queue";
+import { parseBooleanWithDefault } from "@open-mercato/shared/lib/boolean";
 import { matchEventPattern } from "@open-mercato/shared/lib/events/patterns";
 import { getRedisUrlOrThrow } from "@open-mercato/shared/lib/redis/connection";
 import { isBroadcastEvent } from "@open-mercato/shared/modules/events";
 import { registerCrossProcessEventListener } from "./bridge.js";
 import { publishCrossProcessEvent } from "./bridge.js";
 const EVENTS_QUEUE_NAME = "events";
+function isSingleDeliveryEnabled() {
+  return parseBooleanWithDefault(process.env.OM_EVENTS_SINGLE_DELIVERY, false);
+}
 const GLOBAL_EVENT_TAPS_KEY = "__openMercatoEventBusGlobalTaps__";
 function hasTenantScope(payload) {
   return typeof payload?.tenantId === "string" && String(payload.tenantId).trim().length > 0;
@@ -25,23 +29,67 @@ function registerGlobalEventTap(handler) {
     taps.delete(handler);
   };
 }
+const EVENTS_PRODUCER_QUEUE_KEY = "__openMercatoEventsProducerQueues__";
+const EVENTS_PRODUCER_SHUTDOWN_KEY = "__openMercatoEventsProducerShutdown__";
+function isSharedProducerEnabled() {
+  return parseBooleanWithDefault(process.env.OM_EVENTS_SHARED_PRODUCER, true);
+}
+function getProducerQueueRegistry() {
+  const existing = globalThis[EVENTS_PRODUCER_QUEUE_KEY];
+  if (existing instanceof Map) {
+    return existing;
+  }
+  const created = /* @__PURE__ */ new Map();
+  globalThis[EVENTS_PRODUCER_QUEUE_KEY] = created;
+  return created;
+}
+function registerProducerShutdownHook() {
+  if (globalThis[EVENTS_PRODUCER_SHUTDOWN_KEY]) return;
+  const shutdown = () => {
+    const registry = getProducerQueueRegistry();
+    for (const sharedQueue of registry.values()) {
+      Promise.resolve(sharedQueue.close()).catch(() => {
+      });
+    }
+    registry.clear();
+  };
+  process.once("SIGTERM", shutdown);
+  process.once("SIGINT", shutdown);
+  globalThis[EVENTS_PRODUCER_SHUTDOWN_KEY] = true;
+}
 function createEventBus(opts) {
   const listeners = /* @__PURE__ */ new Map();
+  const persistentHandlers = /* @__PURE__ */ new Set();
   const queueStrategy = opts.queueStrategy ?? (process.env.QUEUE_STRATEGY === "async" ? "async" : "local");
   let queue = null;
   function getQueue() {
-    if (!queue) {
-      queue = queueStrategy === "async" ? createQueue(EVENTS_QUEUE_NAME, "async", {
-        connection: { url: getRedisUrlOrThrow("QUEUE") }
-      }) : createQueue(EVENTS_QUEUE_NAME, "local");
+    if (queueStrategy !== "async" || !isSharedProducerEnabled()) {
+      if (!queue) {
+        queue = queueStrategy === "async" ? createQueue(EVENTS_QUEUE_NAME, "async", {
+          connection: { url: getRedisUrlOrThrow("QUEUE") }
+        }) : createQueue(EVENTS_QUEUE_NAME, "local");
+      }
+      return queue;
     }
-    return queue;
+    const redisUrl = getRedisUrlOrThrow("QUEUE");
+    const registry = getProducerQueueRegistry();
+    const cacheKey = `async:${redisUrl}`;
+    let shared = registry.get(cacheKey);
+    if (!shared) {
+      shared = createQueue(EVENTS_QUEUE_NAME, "async", {
+        connection: { url: redisUrl }
+      });
+      registry.set(cacheKey, shared);
+      registerProducerShutdownHook();
+    }
+    return shared;
   }
-  async function deliver(event, payload, options) {
+  async function deliver(event, payload, options, skipPersistent = false) {
     for (const [pattern, handlers] of listeners) {
       if (!matchEventPattern(event, pattern)) continue;
       if (!handlers || handlers.size === 0) continue;
       for (const handler of handlers) {
+        if (skipPersistent && persistentHandlers.has(handler)) continue;
         try {
           await Promise.resolve(handler(payload, {
             resolve: opts.resolve,
@@ -55,15 +103,18 @@ function createEventBus(opts) {
       }
     }
   }
-  function on(event, handler) {
+  function on(event, handler, options) {
     if (!listeners.has(event)) {
       listeners.set(event, /* @__PURE__ */ new Set());
     }
     listeners.get(event).add(handler);
+    if (options?.persistent) {
+      persistentHandlers.add(handler);
+    }
   }
   function registerModuleSubscribers(subs) {
     for (const sub of subs) {
-      on(sub.event, sub.handler);
+      on(sub.event, sub.handler, { persistent: sub.persistent });
     }
   }
   async function emit(event, payload, options) {
@@ -75,7 +126,8 @@ function createEventBus(opts) {
         console.error(`[events] Global tap error for "${event}":`, error);
       }
     }
-    await deliver(event, payload, options);
+    const skipPersistentInline = Boolean(options?.persistent) && isSingleDeliveryEnabled();
+    await deliver(event, payload, options, skipPersistentInline);
     if (isBroadcastEvent(event) && hasTenantScope(payload)) {
       try {
         await publishCrossProcessEvent(event, payload, options);

package/dist/bus.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/bus.ts"],
-  "sourcesContent": ["import { createQueue } from '@open-mercato/queue'\nimport type { Queue } from '@open-mercato/queue'\nimport { matchEventPattern } from '@open-mercato/shared/lib/events/patterns'\nimport { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'\nimport { isBroadcastEvent } from '@open-mercato/shared/modules/events'\nexport { registerCrossProcessEventListener } from './bridge'\nimport { publishCrossProcessEvent } from './bridge'\nimport type {\n  EventBus,\n  CreateBusOptions,\n  SubscriberHandler,\n  SubscriberDescriptor,\n  EventPayload,\n  EmitOptions,\n} from './types'\n\n/** Queue name for persistent events */\nconst EVENTS_QUEUE_NAME = 'events'\n\ntype GlobalEventTap = (event: string, payload: EventPayload, options?: EmitOptions) => void | Promise<void>\nconst GLOBAL_EVENT_TAPS_KEY = '__openMercatoEventBusGlobalTaps__'\n\nfunction hasTenantScope(payload: EventPayload): boolean {\n  return typeof (payload as Record<string, unknown>)?.tenantId === 'string'\n    && String((payload as Record<string, unknown>).tenantId).trim().length > 0\n}\n\nfunction getGlobalEventTaps(): Set<GlobalEventTap> {\n  const existing = (globalThis as Record<string, unknown>)[GLOBAL_EVENT_TAPS_KEY]\n  if (existing instanceof Set) {\n    return existing as Set<GlobalEventTap>\n  }\n  const created = new Set<GlobalEventTap>()\n  ;(globalThis as Record<string, unknown>)[GLOBAL_EVENT_TAPS_KEY] = created\n  return created\n}\n\nexport function registerGlobalEventTap(handler: GlobalEventTap): () => void {\n  const taps = getGlobalEventTaps()\n  taps.add(handler)\n  return () => {\n    taps.delete(handler)\n  }\n}\n\n/** Job data structure for queued events */\ntype EventJobData = {\n  event: string\n  payload: EventPayload\n  options?: EmitOptions\n}\n\n/**\n * Creates an event bus instance.\n *\n * The event bus provides:\n * - In-memory event delivery to registered handlers\n * - Optional persistence via the queue package when `persistent: true`\n *\n * @param opts - Configuration options\n * @returns An EventBus instance\n *\n * @example\n * ```typescript\n * const bus = createEventBus({\n *   resolve: container.resolve.bind(container),\n *   queueStrategy: 'local', // or 'async' for BullMQ\n * })\n *\n * // Register a handler\n * bus.on('user.created', async (payload, ctx) => {\n *   const userService = ctx.resolve('userService')\n *   await userService.sendWelcomeEmail(payload.userId)\n * })\n *\n * // Emit an event (immediate delivery)\n * await bus.emit('user.created', { userId: '123' })\n *\n * // Emit with persistence (for async worker processing)\n * await bus.emit('order.placed', { orderId: '456' }, { persistent: true })\n * ```\n */\nexport function createEventBus(opts: CreateBusOptions): EventBus {\n  // In-memory listeners for immediate event delivery\n  const listeners = new Map<string, Set<SubscriberHandler>>()\n\n  // Determine queue strategy from options or environment\n  const queueStrategy = opts.queueStrategy ??\n    (process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local')\n\n  // Lazy-initialized queue for persistent events\n  let queue: Queue<EventJobData> | null = null\n\n  /**\n   * Gets or creates the queue instance for persistent events.\n   */\n  function getQueue(): Queue<EventJobData> {\n    if (!queue) {\n      queue = queueStrategy === 'async'\n        ? createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'async', {\n            connection: { url: getRedisUrlOrThrow('QUEUE') },\n          })\n        : createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'local')\n    }\n    return queue\n  }\n\n  /**\n   * Delivers an event to all registered in-memory handlers.\n   * Supports wildcard pattern matching for event patterns.\n   */\n  async function deliver(event: string, payload: EventPayload, options?: EmitOptions): Promise<void> {\n    // Check all registered patterns (including wildcards)\n    for (const [pattern, handlers] of listeners) {\n      if (!matchEventPattern(event, pattern)) continue\n      if (!handlers || handlers.size === 0) continue\n\n      for (const handler of handlers) {\n        try {\n          // Pass eventName in context for wildcard handlers\n          await Promise.resolve(handler(payload, {\n            resolve: opts.resolve,\n            eventName: event,\n            tenantId: options?.tenantId ?? null,\n            organizationId: options?.organizationId ?? null,\n          }))\n        } catch (error) {\n          console.error(`[events] Handler error for \"${event}\" (pattern: \"${pattern}\"):`, error)\n        }\n      }\n    }\n  }\n\n  /**\n   * Registers a handler for an event.\n   */\n  function on(event: string, handler: SubscriberHandler): void {\n    if (!listeners.has(event)) {\n      listeners.set(event, new Set())\n    }\n    listeners.get(event)!.add(handler)\n  }\n\n  /**\n   * Registers multiple module subscribers at once.\n   */\n  function registerModuleSubscribers(subs: SubscriberDescriptor[]): void {\n    for (const sub of subs) {\n      on(sub.event, sub.handler)\n    }\n  }\n\n  /**\n   * Emits an event to all registered handlers.\n   *\n   * If `persistent: true`, also enqueues the event for async processing.\n   */\n  async function emit(\n    event: string,\n    payload: EventPayload,\n    options?: EmitOptions\n  ): Promise<void> {\n    const taps = getGlobalEventTaps()\n    for (const tap of taps) {\n      try {\n        await Promise.resolve(tap(event, payload, options))\n      } catch (error) {\n        console.error(`[events] Global tap error for \"${event}\":`, error)\n      }\n    }\n\n    // Always deliver to in-memory handlers first\n    await deliver(event, payload, options)\n\n    if (isBroadcastEvent(event) && hasTenantScope(payload)) {\n      try {\n        await publishCrossProcessEvent(event, payload, options)\n      } catch (error) {\n        console.error(`[events] Cross-process publish error for \"${event}\":`, error)\n      }\n    }\n\n    // If persistent, also enqueue for async processing\n    if (options?.persistent) {\n      const q = getQueue()\n      await q.enqueue({ event, payload, options })\n    }\n  }\n\n  /**\n   * Clears all events from the persistent queue.\n   */\n  async function clearQueue(): Promise<{ removed: number }> {\n    const q = getQueue()\n    return q.clear()\n  }\n\n  // Backward compatibility alias\n  const emitEvent = emit\n\n  return {\n    emit,\n    emitEvent, // Alias for backward compatibility\n    on,\n    registerModuleSubscribers,\n    clearQueue,\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import { createQueue } from '@open-mercato/queue'\nimport type { Queue } from '@open-mercato/queue'\nimport { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'\nimport { matchEventPattern } from '@open-mercato/shared/lib/events/patterns'\nimport { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'\nimport { isBroadcastEvent } from '@open-mercato/shared/modules/events'\nexport { registerCrossProcessEventListener } from './bridge'\nimport { publishCrossProcessEvent } from './bridge'\nimport type {\n  EventBus,\n  CreateBusOptions,\n  SubscriberHandler,\n  SubscriberDescriptor,\n  EventPayload,\n  EmitOptions,\n} from './types'\n\n/** Queue name for persistent events */\nconst EVENTS_QUEUE_NAME = 'events'\n\n/**\n * When enabled, a persistent emit delivers each subscriber on exactly one path:\n * persistent-marked subscribers are skipped inline (the events worker dispatches\n * them via pattern match, so wildcard persistent subscribers are reached), while\n * ephemeral subscribers keep running inline. Default off preserves the legacy\n * dual-dispatch behavior. Both this flag and the worker MUST agree, so the worker\n * reads the same env var.\n */\nfunction isSingleDeliveryEnabled(): boolean {\n  return parseBooleanWithDefault(process.env.OM_EVENTS_SINGLE_DELIVERY, false)\n}\n\ntype GlobalEventTap = (event: string, payload: EventPayload, options?: EmitOptions) => void | Promise<void>\nconst GLOBAL_EVENT_TAPS_KEY = '__openMercatoEventBusGlobalTaps__'\n\nfunction hasTenantScope(payload: EventPayload): boolean {\n  return typeof (payload as Record<string, unknown>)?.tenantId === 'string'\n    && String((payload as Record<string, unknown>).tenantId).trim().length > 0\n}\n\nfunction getGlobalEventTaps(): Set<GlobalEventTap> {\n  const existing = (globalThis as Record<string, unknown>)[GLOBAL_EVENT_TAPS_KEY]\n  if (existing instanceof Set) {\n    return existing as Set<GlobalEventTap>\n  }\n  const created = new Set<GlobalEventTap>()\n  ;(globalThis as Record<string, unknown>)[GLOBAL_EVENT_TAPS_KEY] = created\n  return created\n}\n\nexport function registerGlobalEventTap(handler: GlobalEventTap): () => void {\n  const taps = getGlobalEventTaps()\n  taps.add(handler)\n  return () => {\n    taps.delete(handler)\n  }\n}\n\n/** Job data structure for queued events */\ntype EventJobData = {\n  event: string\n  payload: EventPayload\n  options?: EmitOptions\n}\n\n// Process-wide cache of the async (BullMQ) persistent-events producer queue.\n// Each authenticated request builds a fresh DI container and event bus, so a\n// per-bus producer queue opened a new ioredis connection per write request that\n// was never closed \u2014 leaking one Redis connection per request until maxclients\n// exhaustion. Memoizing the producer on `globalThis` (keyed by Redis URL, so a\n// reconfigured URL still gets its own queue) keeps it at one connection per\n// process, mirroring the `GLOBAL_EVENT_TAPS_KEY` and `getCachedRateLimiterService`\n// patterns. The local (file-based) strategy holds no pooled connection and its\n// base dir is cwd-relative, so it stays per-bus.\nconst EVENTS_PRODUCER_QUEUE_KEY = '__openMercatoEventsProducerQueues__'\nconst EVENTS_PRODUCER_SHUTDOWN_KEY = '__openMercatoEventsProducerShutdown__'\n\nfunction isSharedProducerEnabled(): boolean {\n  return parseBooleanWithDefault(process.env.OM_EVENTS_SHARED_PRODUCER, true)\n}\n\nfunction getProducerQueueRegistry(): Map<string, Queue<EventJobData>> {\n  const existing = (globalThis as Record<string, unknown>)[EVENTS_PRODUCER_QUEUE_KEY]\n  if (existing instanceof Map) {\n    return existing as Map<string, Queue<EventJobData>>\n  }\n  const created = new Map<string, Queue<EventJobData>>()\n  ;(globalThis as Record<string, unknown>)[EVENTS_PRODUCER_QUEUE_KEY] = created\n  return created\n}\n\nfunction registerProducerShutdownHook(): void {\n  if ((globalThis as Record<string, unknown>)[EVENTS_PRODUCER_SHUTDOWN_KEY]) return\n  const shutdown = () => {\n    const registry = getProducerQueueRegistry()\n    for (const sharedQueue of registry.values()) {\n      Promise.resolve(sharedQueue.close()).catch(() => {})\n    }\n    registry.clear()\n  }\n  process.once('SIGTERM', shutdown)\n  process.once('SIGINT', shutdown)\n  ;(globalThis as Record<string, unknown>)[EVENTS_PRODUCER_SHUTDOWN_KEY] = true\n}\n\n/**\n * Creates an event bus instance.\n *\n * The event bus provides:\n * - In-memory event delivery to registered handlers\n * - Optional persistence via the queue package when `persistent: true`\n *\n * @param opts - Configuration options\n * @returns An EventBus instance\n *\n * @example\n * ```typescript\n * const bus = createEventBus({\n *   resolve: container.resolve.bind(container),\n *   queueStrategy: 'local', // or 'async' for BullMQ\n * })\n *\n * // Register a handler\n * bus.on('user.created', async (payload, ctx) => {\n *   const userService = ctx.resolve('userService')\n *   await userService.sendWelcomeEmail(payload.userId)\n * })\n *\n * // Emit an event (immediate delivery)\n * await bus.emit('user.created', { userId: '123' })\n *\n * // Emit with persistence (for async worker processing)\n * await bus.emit('order.placed', { orderId: '456' }, { persistent: true })\n * ```\n */\nexport function createEventBus(opts: CreateBusOptions): EventBus {\n  // In-memory listeners for immediate event delivery\n  const listeners = new Map<string, Set<SubscriberHandler>>()\n  // Handlers registered as persistent (worker-dispatched). Used by the\n  // single-delivery path to skip them inline on a persistent emit.\n  const persistentHandlers = new Set<SubscriberHandler>()\n\n  // Determine queue strategy from options or environment\n  const queueStrategy = opts.queueStrategy ??\n    (process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local')\n\n  // Lazy-initialized queue for persistent events\n  let queue: Queue<EventJobData> | null = null\n\n  /**\n   * Gets or creates the queue instance for persistent events.\n   *\n   * The async (BullMQ) producer is memoized process-wide so the per-request\n   * event bus reuses one Redis connection instead of leaking one per write\n   * request. The local strategy stays per-bus (no pooled connection, cwd-relative\n   * base dir). Set `OM_EVENTS_SHARED_PRODUCER=0` to fall back to per-bus producers.\n   */\n  function getQueue(): Queue<EventJobData> {\n    if (queueStrategy !== 'async' || !isSharedProducerEnabled()) {\n      if (!queue) {\n        queue = queueStrategy === 'async'\n          ? createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'async', {\n              connection: { url: getRedisUrlOrThrow('QUEUE') },\n            })\n          : createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'local')\n      }\n      return queue\n    }\n\n    const redisUrl = getRedisUrlOrThrow('QUEUE')\n    const registry = getProducerQueueRegistry()\n    const cacheKey = `async:${redisUrl}`\n    let shared = registry.get(cacheKey)\n    if (!shared) {\n      shared = createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'async', {\n        connection: { url: redisUrl },\n      })\n      registry.set(cacheKey, shared)\n      registerProducerShutdownHook()\n    }\n    return shared\n  }\n\n  /**\n   * Delivers an event to all registered in-memory handlers.\n   * Supports wildcard pattern matching for event patterns.\n   */\n  async function deliver(\n    event: string,\n    payload: EventPayload,\n    options?: EmitOptions,\n    skipPersistent = false,\n  ): Promise<void> {\n    // Check all registered patterns (including wildcards)\n    for (const [pattern, handlers] of listeners) {\n      if (!matchEventPattern(event, pattern)) continue\n      if (!handlers || handlers.size === 0) continue\n\n      for (const handler of handlers) {\n        // Single-delivery: persistent subscribers are dispatched by the worker,\n        // so skip them inline to avoid double execution.\n        if (skipPersistent && persistentHandlers.has(handler)) continue\n        try {\n          // Pass eventName in context for wildcard handlers\n          await Promise.resolve(handler(payload, {\n            resolve: opts.resolve,\n            eventName: event,\n            tenantId: options?.tenantId ?? null,\n            organizationId: options?.organizationId ?? null,\n          }))\n        } catch (error) {\n          console.error(`[events] Handler error for \"${event}\" (pattern: \"${pattern}\"):`, error)\n        }\n      }\n    }\n  }\n\n  /**\n   * Registers a handler for an event.\n   */\n  function on(event: string, handler: SubscriberHandler, options?: { persistent?: boolean }): void {\n    if (!listeners.has(event)) {\n      listeners.set(event, new Set())\n    }\n    listeners.get(event)!.add(handler)\n    if (options?.persistent) {\n      persistentHandlers.add(handler)\n    }\n  }\n\n  /**\n   * Registers multiple module subscribers at once.\n   */\n  function registerModuleSubscribers(subs: SubscriberDescriptor[]): void {\n    for (const sub of subs) {\n      on(sub.event, sub.handler, { persistent: sub.persistent })\n    }\n  }\n\n  /**\n   * Emits an event to all registered handlers.\n   *\n   * If `persistent: true`, also enqueues the event for async processing.\n   */\n  async function emit(\n    event: string,\n    payload: EventPayload,\n    options?: EmitOptions\n  ): Promise<void> {\n    const taps = getGlobalEventTaps()\n    for (const tap of taps) {\n      try {\n        await Promise.resolve(tap(event, payload, options))\n      } catch (error) {\n        console.error(`[events] Global tap error for \"${event}\":`, error)\n      }\n    }\n\n    // Deliver to in-memory handlers first. Under single-delivery, persistent\n    // subscribers are skipped inline on a persistent emit because the events\n    // worker will dispatch them from the queue.\n    const skipPersistentInline = Boolean(options?.persistent) && isSingleDeliveryEnabled()\n    await deliver(event, payload, options, skipPersistentInline)\n\n    if (isBroadcastEvent(event) && hasTenantScope(payload)) {\n      try {\n        await publishCrossProcessEvent(event, payload, options)\n      } catch (error) {\n        console.error(`[events] Cross-process publish error for \"${event}\":`, error)\n      }\n    }\n\n    // If persistent, also enqueue for async processing\n    if (options?.persistent) {\n      const q = getQueue()\n      await q.enqueue({ event, payload, options })\n    }\n  }\n\n  /**\n   * Clears all events from the persistent queue.\n   */\n  async function clearQueue(): Promise<{ removed: number }> {\n    const q = getQueue()\n    return q.clear()\n  }\n\n  // Backward compatibility alias\n  const emitEvent = emit\n\n  return {\n    emit,\n    emitEvent, // Alias for backward compatibility\n    on,\n    registerModuleSubscribers,\n    clearQueue,\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/modules/events/workers/events.worker.js

@@ -1,4 +1,6 @@
 import { getCliModules } from "@open-mercato/shared/modules/registry";
+import { matchEventPattern } from "@open-mercato/shared/lib/events/patterns";
+import { parseBooleanWithDefault } from "@open-mercato/shared/lib/boolean";
 const EVENTS_QUEUE_NAME = "events";
 const DEFAULT_CONCURRENCY = 1;
 const envConcurrency = process.env.WORKERS_EVENTS_CONCURRENCY;
@@ -6,6 +8,22 @@ const metadata = {
   queue: EVENTS_QUEUE_NAME,
   concurrency: envConcurrency ? parseInt(envConcurrency, 10) : DEFAULT_CONCURRENCY
 };
+function isSingleDeliveryEnabled() {
+  return parseBooleanWithDefault(process.env.OM_EVENTS_SINGLE_DELIVERY, false);
+}
+function resolveSubscribers(listeners, event) {
+  if (!isSingleDeliveryEnabled()) {
+    return listeners.get(event) ?? [];
+  }
+  const matched = [];
+  for (const [pattern, subs] of listeners) {
+    if (!matchEventPattern(event, pattern)) continue;
+    for (const sub of subs) {
+      if (sub.persistent) matched.push(sub);
+    }
+  }
+  return matched;
+}
 let cachedListenerMap = null;
 function clearListenerCache() {
   cachedListenerMap = null;
@@ -31,7 +49,7 @@ function getListenerMap() {
 async function handle(job, ctx) {
   const { event, payload, options } = job.payload;
   const listeners = getListenerMap();
-  const subscribers = listeners.get(event);
+  const subscribers = resolveSubscribers(listeners, event);
   if (!subscribers || subscribers.length === 0) return;
   const handlerCtx = {
     resolve: ctx.resolve,

package/dist/modules/events/workers/events.worker.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/events/workers/events.worker.ts"],
-  "sourcesContent": ["import type { QueuedJob, JobContext, WorkerMeta } from '@open-mercato/queue'\nimport { getCliModules } from '@open-mercato/shared/modules/registry'\n\nexport const EVENTS_QUEUE_NAME = 'events'\n\nconst DEFAULT_CONCURRENCY = 1\nconst envConcurrency = process.env.WORKERS_EVENTS_CONCURRENCY\n\nexport const metadata: WorkerMeta = {\n  queue: EVENTS_QUEUE_NAME,\n  concurrency: envConcurrency ? parseInt(envConcurrency, 10) : DEFAULT_CONCURRENCY,\n}\n\ntype EventJobPayload = {\n  event: string\n  payload: unknown\n  options?: {\n    tenantId?: string | null\n    organizationId?: string | null\n  }\n}\n\ntype HandlerContext = {\n  resolve: <T = unknown>(name: string) => T\n  tenantId?: string | null\n  organizationId?: string | null\n}\n\ntype SubscriberEntry = {\n  id: string\n  event: string\n  handler: (payload: unknown, ctx: unknown) => Promise<void> | void\n}\n\n// Cached listener map - built once on first use\nlet cachedListenerMap: Map<string, SubscriberEntry[]> | null = null\n\n/**\n * Clear the cached listener map (for testing purposes).\n */\nexport function clearListenerCache(): void {\n  cachedListenerMap = null\n}\n\n// Build listener map from module subscribers\nfunction buildListenerMap(): Map<string, SubscriberEntry[]> {\n  const listeners = new Map<string, SubscriberEntry[]>()\n  for (const mod of getCliModules()) {\n    const subs = (mod as { subscribers?: SubscriberEntry[] }).subscribers\n    if (!subs) continue\n    for (const sub of subs) {\n      if (!listeners.has(sub.event)) listeners.set(sub.event, [])\n      listeners.get(sub.event)!.push(sub)\n    }\n  }\n  return listeners\n}\n\n// Get cached listener map, building on first access\nfunction getListenerMap(): Map<string, SubscriberEntry[]> {\n  if (!cachedListenerMap) {\n    cachedListenerMap = buildListenerMap()\n  }\n  return cachedListenerMap\n}\n\n/**\n * Events worker handler.\n * Dispatches queued events to registered module subscribers.\n * Each subscriber is isolated - failures in one don't affect others.\n */\nexport default async function handle(\n  job: QueuedJob<EventJobPayload>,\n  ctx: JobContext & HandlerContext\n): Promise<void> {\n  const { event, payload, options } = job.payload\n  const listeners = getListenerMap()\n  const subscribers = listeners.get(event)\n\n  if (!subscribers || subscribers.length === 0) return\n\n  const handlerCtx = {\n    resolve: ctx.resolve,\n    tenantId: options?.tenantId ?? null,\n    organizationId: options?.organizationId ?? null,\n  }\n\n  const results = await Promise.allSettled(\n    subscribers.map((sub) => Promise.resolve(sub.handler(payload, handlerCtx)))\n  )\n\n  const errors: Array<{ subscriberId: string; error: unknown }> = []\n  for (let i = 0; i < results.length; i++) {\n    const result = results[i]\n    if (result.status === 'rejected') {\n      const sub = subscribers[i]\n      console.error(`[events] Subscriber \"${sub.id}\" failed for event \"${event}\":`, result.reason)\n      errors.push({ subscriberId: sub.id, error: result.reason })\n    }\n  }\n\n  if (errors.length > 0) {\n    const failedIds = errors.map((e) => e.subscriberId).join(', ')\n    throw new Error(\n      `${errors.length}/${subscribers.length} subscriber(s) failed for event \"${event}\": ${failedIds}`\n    )\n  }\n}\n"],
-  "mappings": "AACA,SAAS,qBAAqB;AAEvB,MAAM,oBAAoB;AAEjC,MAAM,sBAAsB;AAC5B,MAAM,iBAAiB,QAAQ,IAAI;AAE5B,MAAM,WAAuB;AAAA,EAClC,OAAO;AAAA,EACP,aAAa,iBAAiB,SAAS,gBAAgB,EAAE,IAAI;AAC/D;AAwBA,IAAI,oBAA2D;AAKxD,SAAS,qBAA2B;AACzC,sBAAoB;AACtB;AAGA,SAAS,mBAAmD;AAC1D,QAAM,YAAY,oBAAI,IAA+B;AACrD,aAAW,OAAO,cAAc,GAAG;AACjC,UAAM,OAAQ,IAA4C;AAC1D,QAAI,CAAC,KAAM;AACX,eAAW,OAAO,MAAM;AACtB,UAAI,CAAC,UAAU,IAAI,IAAI,KAAK,EAAG,WAAU,IAAI,IAAI,OAAO,CAAC,CAAC;AAC1D,gBAAU,IAAI,IAAI,KAAK,EAAG,KAAK,GAAG;AAAA,IACpC;AAAA,EACF;AACA,SAAO;AACT;AAGA,SAAS,iBAAiD;AACxD,MAAI,CAAC,mBAAmB;AACtB,wBAAoB,iBAAiB;AAAA,EACvC;AACA,SAAO;AACT;AAOA,eAAO,OACL,KACA,KACe;AACf,QAAM,EAAE,OAAO,SAAS,QAAQ,IAAI,IAAI;AACxC,QAAM,YAAY,eAAe;AACjC,QAAM,cAAc,UAAU,IAAI,KAAK;AAEvC,MAAI,CAAC,eAAe,YAAY,WAAW,EAAG;AAE9C,QAAM,aAAa;AAAA,IACjB,SAAS,IAAI;AAAA,IACb,UAAU,SAAS,YAAY;AAAA,IAC/B,gBAAgB,SAAS,kBAAkB;AAAA,EAC7C;AAEA,QAAM,UAAU,MAAM,QAAQ;AAAA,IAC5B,YAAY,IAAI,CAAC,QAAQ,QAAQ,QAAQ,IAAI,QAAQ,SAAS,UAAU,CAAC,CAAC;AAAA,EAC5E;AAEA,QAAM,SAA0D,CAAC;AACjE,WAAS,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;AACvC,UAAM,SAAS,QAAQ,CAAC;AACxB,QAAI,OAAO,WAAW,YAAY;AAChC,YAAM,MAAM,YAAY,CAAC;AACzB,cAAQ,MAAM,wBAAwB,IAAI,EAAE,uBAAuB,KAAK,MAAM,OAAO,MAAM;AAC3F,aAAO,KAAK,EAAE,cAAc,IAAI,IAAI,OAAO,OAAO,OAAO,CAAC;AAAA,IAC5D;AAAA,EACF;AAEA,MAAI,OAAO,SAAS,GAAG;AACrB,UAAM,YAAY,OAAO,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,IAAI;AAC7D,UAAM,IAAI;AAAA,MACR,GAAG,OAAO,MAAM,IAAI,YAAY,MAAM,oCAAoC,KAAK,MAAM,SAAS;AAAA,IAChG;AAAA,EACF;AACF;",
+  "sourcesContent": ["import type { QueuedJob, JobContext, WorkerMeta } from '@open-mercato/queue'\nimport { getCliModules } from '@open-mercato/shared/modules/registry'\nimport { matchEventPattern } from '@open-mercato/shared/lib/events/patterns'\nimport { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'\n\nexport const EVENTS_QUEUE_NAME = 'events'\n\nconst DEFAULT_CONCURRENCY = 1\nconst envConcurrency = process.env.WORKERS_EVENTS_CONCURRENCY\n\nexport const metadata: WorkerMeta = {\n  queue: EVENTS_QUEUE_NAME,\n  concurrency: envConcurrency ? parseInt(envConcurrency, 10) : DEFAULT_CONCURRENCY,\n}\n\ntype EventJobPayload = {\n  event: string\n  payload: unknown\n  options?: {\n    tenantId?: string | null\n    organizationId?: string | null\n  }\n}\n\ntype HandlerContext = {\n  resolve: <T = unknown>(name: string) => T\n  tenantId?: string | null\n  organizationId?: string | null\n}\n\ntype SubscriberEntry = {\n  id: string\n  event: string\n  persistent?: boolean\n  handler: (payload: unknown, ctx: unknown) => Promise<void> | void\n}\n\n/**\n * Mirror of the event bus single-delivery flag. When enabled, the worker owns\n * dispatch of every persistent subscriber and matches by pattern so wildcard\n * (`event: '*'`) persistent subscribers are finally reached. Default off keeps\n * the legacy exact-match dispatch of all subscribers.\n */\nfunction isSingleDeliveryEnabled(): boolean {\n  return parseBooleanWithDefault(process.env.OM_EVENTS_SINGLE_DELIVERY, false)\n}\n\n/**\n * Resolves the subscribers to run for a queued event.\n * - Legacy (flag off): exact-match lookup of every subscriber for the event.\n * - Single-delivery (flag on): persistent subscribers whose pattern matches the\n *   event, including wildcards, so they run exactly once here instead of inline.\n */\nfunction resolveSubscribers(\n  listeners: Map<string, SubscriberEntry[]>,\n  event: string,\n): SubscriberEntry[] {\n  if (!isSingleDeliveryEnabled()) {\n    return listeners.get(event) ?? []\n  }\n  const matched: SubscriberEntry[] = []\n  for (const [pattern, subs] of listeners) {\n    if (!matchEventPattern(event, pattern)) continue\n    for (const sub of subs) {\n      if (sub.persistent) matched.push(sub)\n    }\n  }\n  return matched\n}\n\n// Cached listener map - built once on first use\nlet cachedListenerMap: Map<string, SubscriberEntry[]> | null = null\n\n/**\n * Clear the cached listener map (for testing purposes).\n */\nexport function clearListenerCache(): void {\n  cachedListenerMap = null\n}\n\n// Build listener map from module subscribers\nfunction buildListenerMap(): Map<string, SubscriberEntry[]> {\n  const listeners = new Map<string, SubscriberEntry[]>()\n  for (const mod of getCliModules()) {\n    const subs = (mod as { subscribers?: SubscriberEntry[] }).subscribers\n    if (!subs) continue\n    for (const sub of subs) {\n      if (!listeners.has(sub.event)) listeners.set(sub.event, [])\n      listeners.get(sub.event)!.push(sub)\n    }\n  }\n  return listeners\n}\n\n// Get cached listener map, building on first access\nfunction getListenerMap(): Map<string, SubscriberEntry[]> {\n  if (!cachedListenerMap) {\n    cachedListenerMap = buildListenerMap()\n  }\n  return cachedListenerMap\n}\n\n/**\n * Events worker handler.\n * Dispatches queued events to registered module subscribers.\n * Each subscriber is isolated - failures in one don't affect others.\n */\nexport default async function handle(\n  job: QueuedJob<EventJobPayload>,\n  ctx: JobContext & HandlerContext\n): Promise<void> {\n  const { event, payload, options } = job.payload\n  const listeners = getListenerMap()\n  const subscribers = resolveSubscribers(listeners, event)\n\n  if (!subscribers || subscribers.length === 0) return\n\n  const handlerCtx = {\n    resolve: ctx.resolve,\n    tenantId: options?.tenantId ?? null,\n    organizationId: options?.organizationId ?? null,\n  }\n\n  const results = await Promise.allSettled(\n    subscribers.map((sub) => Promise.resolve(sub.handler(payload, handlerCtx)))\n  )\n\n  const errors: Array<{ subscriberId: string; error: unknown }> = []\n  for (let i = 0; i < results.length; i++) {\n    const result = results[i]\n    if (result.status === 'rejected') {\n      const sub = subscribers[i]\n      console.error(`[events] Subscriber \"${sub.id}\" failed for event \"${event}\":`, result.reason)\n      errors.push({ subscriberId: sub.id, error: result.reason })\n    }\n  }\n\n  if (errors.length > 0) {\n    const failedIds = errors.map((e) => e.subscriberId).join(', ')\n    throw new Error(\n      `${errors.length}/${subscribers.length} subscriber(s) failed for event \"${event}\": ${failedIds}`\n    )\n  }\n}\n"],
+  "mappings": "AACA,SAAS,qBAAqB;AAC9B,SAAS,yBAAyB;AAClC,SAAS,+BAA+B;AAEjC,MAAM,oBAAoB;AAEjC,MAAM,sBAAsB;AAC5B,MAAM,iBAAiB,QAAQ,IAAI;AAE5B,MAAM,WAAuB;AAAA,EAClC,OAAO;AAAA,EACP,aAAa,iBAAiB,SAAS,gBAAgB,EAAE,IAAI;AAC/D;AA8BA,SAAS,0BAAmC;AAC1C,SAAO,wBAAwB,QAAQ,IAAI,2BAA2B,KAAK;AAC7E;AAQA,SAAS,mBACP,WACA,OACmB;AACnB,MAAI,CAAC,wBAAwB,GAAG;AAC9B,WAAO,UAAU,IAAI,KAAK,KAAK,CAAC;AAAA,EAClC;AACA,QAAM,UAA6B,CAAC;AACpC,aAAW,CAAC,SAAS,IAAI,KAAK,WAAW;AACvC,QAAI,CAAC,kBAAkB,OAAO,OAAO,EAAG;AACxC,eAAW,OAAO,MAAM;AACtB,UAAI,IAAI,WAAY,SAAQ,KAAK,GAAG;AAAA,IACtC;AAAA,EACF;AACA,SAAO;AACT;AAGA,IAAI,oBAA2D;AAKxD,SAAS,qBAA2B;AACzC,sBAAoB;AACtB;AAGA,SAAS,mBAAmD;AAC1D,QAAM,YAAY,oBAAI,IAA+B;AACrD,aAAW,OAAO,cAAc,GAAG;AACjC,UAAM,OAAQ,IAA4C;AAC1D,QAAI,CAAC,KAAM;AACX,eAAW,OAAO,MAAM;AACtB,UAAI,CAAC,UAAU,IAAI,IAAI,KAAK,EAAG,WAAU,IAAI,IAAI,OAAO,CAAC,CAAC;AAC1D,gBAAU,IAAI,IAAI,KAAK,EAAG,KAAK,GAAG;AAAA,IACpC;AAAA,EACF;AACA,SAAO;AACT;AAGA,SAAS,iBAAiD;AACxD,MAAI,CAAC,mBAAmB;AACtB,wBAAoB,iBAAiB;AAAA,EACvC;AACA,SAAO;AACT;AAOA,eAAO,OACL,KACA,KACe;AACf,QAAM,EAAE,OAAO,SAAS,QAAQ,IAAI,IAAI;AACxC,QAAM,YAAY,eAAe;AACjC,QAAM,cAAc,mBAAmB,WAAW,KAAK;AAEvD,MAAI,CAAC,eAAe,YAAY,WAAW,EAAG;AAE9C,QAAM,aAAa;AAAA,IACjB,SAAS,IAAI;AAAA,IACb,UAAU,SAAS,YAAY;AAAA,IAC/B,gBAAgB,SAAS,kBAAkB;AAAA,EAC7C;AAEA,QAAM,UAAU,MAAM,QAAQ;AAAA,IAC5B,YAAY,IAAI,CAAC,QAAQ,QAAQ,QAAQ,IAAI,QAAQ,SAAS,UAAU,CAAC,CAAC;AAAA,EAC5E;AAEA,QAAM,SAA0D,CAAC;AACjE,WAAS,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;AACvC,UAAM,SAAS,QAAQ,CAAC;AACxB,QAAI,OAAO,WAAW,YAAY;AAChC,YAAM,MAAM,YAAY,CAAC;AACzB,cAAQ,MAAM,wBAAwB,IAAI,EAAE,uBAAuB,KAAK,MAAM,OAAO,MAAM;AAC3F,aAAO,KAAK,EAAE,cAAc,IAAI,IAAI,OAAO,OAAO,OAAO,CAAC;AAAA,IAC5D;AAAA,EACF;AAEA,MAAI,OAAO,SAAS,GAAG;AACrB,UAAM,YAAY,OAAO,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,IAAI;AAC7D,UAAM,IAAI;AAAA,MACR,GAAG,OAAO,MAAM,IAAI,YAAY,MAAM,oCAAoC,KAAK,MAAM,SAAS;AAAA,IAChG;AAAA,EACF;AACF;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/events",
-  "version": "0.6.5-develop.5382.1.f542de69af",
+  "version": "0.6.5",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -32,8 +32,8 @@
     }
   },
   "dependencies": {
-    "@open-mercato/queue": "0.6.5-develop.5382.1.f542de69af",
-    "@open-mercato/shared": "0.6.5-develop.5382.1.f542de69af",
+    "@open-mercato/queue": "0.6.5",
+    "@open-mercato/shared": "0.6.5",
     "pg": "8.21.0"
   },
   "devDependencies": {
@@ -48,6 +48,5 @@
     "type": "git",
     "url": "https://github.com/open-mercato/open-mercato",
     "directory": "packages/events"
-  },
-  "stableVersion": "0.6.4"
+  }
 }

package/src/__tests__/shared-producer.test.ts

@@ -0,0 +1,97 @@
+const createQueueMock = jest.fn()
+
+jest.mock('@open-mercato/queue', () => ({
+  createQueue: (...args: unknown[]) => createQueueMock(...args),
+}))
+
+import { createEventBus } from '@open-mercato/events/index'
+
+const PRODUCER_QUEUE_KEY = '__openMercatoEventsProducerQueues__'
+const PRODUCER_SHUTDOWN_KEY = '__openMercatoEventsProducerShutdown__'
+
+function makeFakeQueue(id: number) {
+  return {
+    id,
+    name: 'events',
+    strategy: 'async' as const,
+    enqueue: jest.fn(async () => `job-${id}`),
+    clear: jest.fn(async () => ({ removed: 0 })),
+    close: jest.fn(async () => {}),
+    process: jest.fn(),
+    getJobCounts: jest.fn(),
+  }
+}
+
+describe('persistent-events producer memoization (#2959)', () => {
+  const resolve = ((name: string) => name) as never
+
+  beforeEach(() => {
+    createQueueMock.mockReset()
+    let created = 0
+    createQueueMock.mockImplementation(() => makeFakeQueue(created++))
+    delete (globalThis as Record<string, unknown>)[PRODUCER_QUEUE_KEY]
+    delete (globalThis as Record<string, unknown>)[PRODUCER_SHUTDOWN_KEY]
+    process.env.REDIS_URL = 'redis://localhost:6379'
+    delete process.env.OM_EVENTS_SHARED_PRODUCER
+  })
+
+  afterEach(() => {
+    delete process.env.REDIS_URL
+    delete process.env.OM_EVENTS_SHARED_PRODUCER
+    delete (globalThis as Record<string, unknown>)[PRODUCER_QUEUE_KEY]
+    delete (globalThis as Record<string, unknown>)[PRODUCER_SHUTDOWN_KEY]
+  })
+
+  test('async strategy reuses a single process-wide producer across buses', async () => {
+    const busA = createEventBus({ resolve, queueStrategy: 'async' })
+    const busB = createEventBus({ resolve, queueStrategy: 'async' })
+
+    await busA.emit('demo.event.happened', { id: 1 }, { persistent: true })
+    await busB.emit('demo.event.happened', { id: 2 }, { persistent: true })
+
+    // The leak fix: only one producer queue (one Redis connection) is created
+    // even though two separate request-scoped buses emitted persistent events.
+    expect(createQueueMock).toHaveBeenCalledTimes(1)
+
+    const registry = (globalThis as Record<string, unknown>)[PRODUCER_QUEUE_KEY] as Map<string, { enqueue: jest.Mock }>
+    expect(registry.size).toBe(1)
+    const shared = [...registry.values()][0]
+    expect(shared.enqueue).toHaveBeenCalledTimes(2)
+  })
+
+  test('kill switch OM_EVENTS_SHARED_PRODUCER=0 restores per-bus producers', async () => {
+    process.env.OM_EVENTS_SHARED_PRODUCER = '0'
+    const busA = createEventBus({ resolve, queueStrategy: 'async' })
+    const busB = createEventBus({ resolve, queueStrategy: 'async' })
+
+    await busA.emit('demo.event.happened', { id: 1 }, { persistent: true })
+    await busB.emit('demo.event.happened', { id: 2 }, { persistent: true })
+
+    expect(createQueueMock).toHaveBeenCalledTimes(2)
+    expect((globalThis as Record<string, unknown>)[PRODUCER_QUEUE_KEY]).toBeUndefined()
+  })
+
+  test('separate Redis URLs get separate producers', async () => {
+    const busA = createEventBus({ resolve, queueStrategy: 'async' })
+    await busA.emit('demo.event.happened', { id: 1 }, { persistent: true })
+
+    process.env.REDIS_URL = 'redis://other-host:6379'
+    const busB = createEventBus({ resolve, queueStrategy: 'async' })
+    await busB.emit('demo.event.happened', { id: 2 }, { persistent: true })
+
+    expect(createQueueMock).toHaveBeenCalledTimes(2)
+    const registry = (globalThis as Record<string, unknown>)[PRODUCER_QUEUE_KEY] as Map<string, unknown>
+    expect(registry.size).toBe(2)
+  })
+
+  test('local strategy is not memoized (no pooled connection to share)', async () => {
+    const busA = createEventBus({ resolve, queueStrategy: 'local' })
+    const busB = createEventBus({ resolve, queueStrategy: 'local' })
+
+    await busA.emit('demo.event.happened', { id: 1 }, { persistent: true })
+    await busB.emit('demo.event.happened', { id: 2 }, { persistent: true })
+
+    expect(createQueueMock).toHaveBeenCalledTimes(2)
+    expect((globalThis as Record<string, unknown>)[PRODUCER_QUEUE_KEY]).toBeUndefined()
+  })
+})

package/src/__tests__/single-delivery.test.ts

@@ -0,0 +1,95 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { createEventBus } from '@open-mercato/events/index'
+import type { SubscriberDescriptor } from '@open-mercato/events/types'
+
+/**
+ * Regression coverage for issue #2960: persistent subscribers must run on
+ * exactly one path under the OM_EVENTS_SINGLE_DELIVERY flag, and the default-off
+ * behavior must be preserved byte-for-byte.
+ */
+describe('Event bus single-delivery (OM_EVENTS_SINGLE_DELIVERY)', () => {
+  const origCwd = process.cwd()
+  const origFlag = process.env.OM_EVENTS_SINGLE_DELIVERY
+  let tmp: string
+
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'events-single-delivery-'))
+    process.chdir(tmp)
+    delete process.env.QUEUE_STRATEGY
+    delete process.env.EVENTS_STRATEGY
+  })
+
+  afterEach(() => {
+    process.chdir(origCwd)
+    if (origFlag === undefined) delete process.env.OM_EVENTS_SINGLE_DELIVERY
+    else process.env.OM_EVENTS_SINGLE_DELIVERY = origFlag
+    try { fs.rmSync(tmp, { recursive: true, force: true }) } catch {}
+  })
+
+  function makeSub(
+    id: string,
+    event: string,
+    persistent: boolean,
+    sink: string[],
+  ): SubscriberDescriptor {
+    return { id, event, persistent, handler: () => { sink.push(id) } }
+  }
+
+  test('flag OFF (default): a persistent subscriber still runs inline on a persistent emit', async () => {
+    delete process.env.OM_EVENTS_SINGLE_DELIVERY
+    const calls: string[] = []
+    const bus = createEventBus({ resolve: ((name: string) => name) as never })
+    bus.registerModuleSubscribers([makeSub('persistent-sub', 'demo', true, calls)])
+
+    await bus.emit('demo', { a: 1 }, { persistent: true })
+
+    // Legacy dual-dispatch: inline delivery is preserved when the flag is off.
+    expect(calls).toEqual(['persistent-sub'])
+  })
+
+  test('flag ON: a persistent subscriber is skipped inline (deferred to the worker)', async () => {
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'true'
+    const calls: string[] = []
+    const bus = createEventBus({ resolve: ((name: string) => name) as never })
+    bus.registerModuleSubscribers([
+      makeSub('persistent-sub', 'demo', true, calls),
+      makeSub('ephemeral-sub', 'demo', false, calls),
+    ])
+
+    await bus.emit('demo', { a: 1 }, { persistent: true })
+
+    // Only the ephemeral subscriber runs inline; the persistent one is dispatched
+    // by the events worker from the queue, so it is skipped here.
+    expect(calls).toEqual(['ephemeral-sub'])
+  })
+
+  test('flag ON: a non-persistent emit still delivers persistent subscribers inline', async () => {
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'true'
+    const calls: string[] = []
+    const bus = createEventBus({ resolve: ((name: string) => name) as never })
+    bus.registerModuleSubscribers([makeSub('persistent-sub', 'demo', true, calls)])
+
+    // Non-persistent emit is never enqueued, so inline delivery is the only path.
+    await bus.emit('demo', { a: 1 })
+
+    expect(calls).toEqual(['persistent-sub'])
+  })
+
+  test('flag ON: persistent emit is still enqueued for the worker', async () => {
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'true'
+    const queuePath = path.join(path.resolve('.mercato/queue', 'events'), 'queue.json')
+    const calls: string[] = []
+    const bus = createEventBus({ resolve: ((name: string) => name) as never })
+    bus.registerModuleSubscribers([makeSub('persistent-sub', 'demo', true, calls)])
+
+    await bus.emit('demo', { a: 1 }, { persistent: true })
+
+    expect(calls).toEqual([])
+    const list = JSON.parse(fs.readFileSync(queuePath, 'utf8'))
+    expect(Array.isArray(list)).toBe(true)
+    expect(list.length).toBeGreaterThanOrEqual(1)
+  })
+})

package/src/bus.ts

@@ -1,5 +1,6 @@
 import { createQueue } from '@open-mercato/queue'
 import type { Queue } from '@open-mercato/queue'
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import { matchEventPattern } from '@open-mercato/shared/lib/events/patterns'
 import { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'
 import { isBroadcastEvent } from '@open-mercato/shared/modules/events'
@@ -17,6 +18,18 @@ import type {
 /** Queue name for persistent events */
 const EVENTS_QUEUE_NAME = 'events'
 
+/**
+ * When enabled, a persistent emit delivers each subscriber on exactly one path:
+ * persistent-marked subscribers are skipped inline (the events worker dispatches
+ * them via pattern match, so wildcard persistent subscribers are reached), while
+ * ephemeral subscribers keep running inline. Default off preserves the legacy
+ * dual-dispatch behavior. Both this flag and the worker MUST agree, so the worker
+ * reads the same env var.
+ */
+function isSingleDeliveryEnabled(): boolean {
+  return parseBooleanWithDefault(process.env.OM_EVENTS_SINGLE_DELIVERY, false)
+}
+
 type GlobalEventTap = (event: string, payload: EventPayload, options?: EmitOptions) => void | Promise<void>
 const GLOBAL_EVENT_TAPS_KEY = '__openMercatoEventBusGlobalTaps__'
 
@@ -50,6 +63,46 @@ type EventJobData = {
   options?: EmitOptions
 }
 
+// Process-wide cache of the async (BullMQ) persistent-events producer queue.
+// Each authenticated request builds a fresh DI container and event bus, so a
+// per-bus producer queue opened a new ioredis connection per write request that
+// was never closed — leaking one Redis connection per request until maxclients
+// exhaustion. Memoizing the producer on `globalThis` (keyed by Redis URL, so a
+// reconfigured URL still gets its own queue) keeps it at one connection per
+// process, mirroring the `GLOBAL_EVENT_TAPS_KEY` and `getCachedRateLimiterService`
+// patterns. The local (file-based) strategy holds no pooled connection and its
+// base dir is cwd-relative, so it stays per-bus.
+const EVENTS_PRODUCER_QUEUE_KEY = '__openMercatoEventsProducerQueues__'
+const EVENTS_PRODUCER_SHUTDOWN_KEY = '__openMercatoEventsProducerShutdown__'
+
+function isSharedProducerEnabled(): boolean {
+  return parseBooleanWithDefault(process.env.OM_EVENTS_SHARED_PRODUCER, true)
+}
+
+function getProducerQueueRegistry(): Map<string, Queue<EventJobData>> {
+  const existing = (globalThis as Record<string, unknown>)[EVENTS_PRODUCER_QUEUE_KEY]
+  if (existing instanceof Map) {
+    return existing as Map<string, Queue<EventJobData>>
+  }
+  const created = new Map<string, Queue<EventJobData>>()
+  ;(globalThis as Record<string, unknown>)[EVENTS_PRODUCER_QUEUE_KEY] = created
+  return created
+}
+
+function registerProducerShutdownHook(): void {
+  if ((globalThis as Record<string, unknown>)[EVENTS_PRODUCER_SHUTDOWN_KEY]) return
+  const shutdown = () => {
+    const registry = getProducerQueueRegistry()
+    for (const sharedQueue of registry.values()) {
+      Promise.resolve(sharedQueue.close()).catch(() => {})
+    }
+    registry.clear()
+  }
+  process.once('SIGTERM', shutdown)
+  process.once('SIGINT', shutdown)
+  ;(globalThis as Record<string, unknown>)[EVENTS_PRODUCER_SHUTDOWN_KEY] = true
+}
+
 /**
  * Creates an event bus instance.
  *
@@ -83,6 +136,9 @@ type EventJobData = {
 export function createEventBus(opts: CreateBusOptions): EventBus {
   // In-memory listeners for immediate event delivery
   const listeners = new Map<string, Set<SubscriberHandler>>()
+  // Handlers registered as persistent (worker-dispatched). Used by the
+  // single-delivery path to skip them inline on a persistent emit.
+  const persistentHandlers = new Set<SubscriberHandler>()
 
   // Determine queue strategy from options or environment
   const queueStrategy = opts.queueStrategy ??
@@ -93,29 +149,57 @@ export function createEventBus(opts: CreateBusOptions): EventBus {
 
   /**
    * Gets or creates the queue instance for persistent events.
+   *
+   * The async (BullMQ) producer is memoized process-wide so the per-request
+   * event bus reuses one Redis connection instead of leaking one per write
+   * request. The local strategy stays per-bus (no pooled connection, cwd-relative
+   * base dir). Set `OM_EVENTS_SHARED_PRODUCER=0` to fall back to per-bus producers.
    */
   function getQueue(): Queue<EventJobData> {
-    if (!queue) {
-      queue = queueStrategy === 'async'
-        ? createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'async', {
-            connection: { url: getRedisUrlOrThrow('QUEUE') },
-          })
-        : createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'local')
+    if (queueStrategy !== 'async' || !isSharedProducerEnabled()) {
+      if (!queue) {
+        queue = queueStrategy === 'async'
+          ? createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'async', {
+              connection: { url: getRedisUrlOrThrow('QUEUE') },
+            })
+          : createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'local')
+      }
+      return queue
+    }
+
+    const redisUrl = getRedisUrlOrThrow('QUEUE')
+    const registry = getProducerQueueRegistry()
+    const cacheKey = `async:${redisUrl}`
+    let shared = registry.get(cacheKey)
+    if (!shared) {
+      shared = createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'async', {
+        connection: { url: redisUrl },
+      })
+      registry.set(cacheKey, shared)
+      registerProducerShutdownHook()
     }
-    return queue
+    return shared
   }
 
   /**
    * Delivers an event to all registered in-memory handlers.
    * Supports wildcard pattern matching for event patterns.
    */
-  async function deliver(event: string, payload: EventPayload, options?: EmitOptions): Promise<void> {
+  async function deliver(
+    event: string,
+    payload: EventPayload,
+    options?: EmitOptions,
+    skipPersistent = false,
+  ): Promise<void> {
     // Check all registered patterns (including wildcards)
     for (const [pattern, handlers] of listeners) {
       if (!matchEventPattern(event, pattern)) continue
       if (!handlers || handlers.size === 0) continue
 
       for (const handler of handlers) {
+        // Single-delivery: persistent subscribers are dispatched by the worker,
+        // so skip them inline to avoid double execution.
+        if (skipPersistent && persistentHandlers.has(handler)) continue
         try {
           // Pass eventName in context for wildcard handlers
           await Promise.resolve(handler(payload, {
@@ -134,11 +218,14 @@ export function createEventBus(opts: CreateBusOptions): EventBus {
   /**
    * Registers a handler for an event.
    */
-  function on(event: string, handler: SubscriberHandler): void {
+  function on(event: string, handler: SubscriberHandler, options?: { persistent?: boolean }): void {
     if (!listeners.has(event)) {
       listeners.set(event, new Set())
     }
     listeners.get(event)!.add(handler)
+    if (options?.persistent) {
+      persistentHandlers.add(handler)
+    }
   }
 
   /**
@@ -146,7 +233,7 @@ export function createEventBus(opts: CreateBusOptions): EventBus {
    */
   function registerModuleSubscribers(subs: SubscriberDescriptor[]): void {
     for (const sub of subs) {
-      on(sub.event, sub.handler)
+      on(sub.event, sub.handler, { persistent: sub.persistent })
     }
   }
 
@@ -169,8 +256,11 @@ export function createEventBus(opts: CreateBusOptions): EventBus {
       }
     }
 
-    // Always deliver to in-memory handlers first
-    await deliver(event, payload, options)
+    // Deliver to in-memory handlers first. Under single-delivery, persistent
+    // subscribers are skipped inline on a persistent emit because the events
+    // worker will dispatch them from the queue.
+    const skipPersistentInline = Boolean(options?.persistent) && isSingleDeliveryEnabled()
+    await deliver(event, payload, options, skipPersistentInline)
 
     if (isBroadcastEvent(event) && hasTenantScope(payload)) {
       try {

package/src/modules/events/workers/__tests__/events.worker.test.ts

@@ -431,4 +431,77 @@ describe('Events Worker', () => {
       errorSpy.mockRestore()
     })
   })
+
+  describe('single-delivery dispatch (OM_EVENTS_SINGLE_DELIVERY) — issue #2960', () => {
+    const origFlag = process.env.OM_EVENTS_SINGLE_DELIVERY
+
+    afterEach(() => {
+      if (origFlag === undefined) delete process.env.OM_EVENTS_SINGLE_DELIVERY
+      else process.env.OM_EVENTS_SINGLE_DELIVERY = origFlag
+    })
+
+    const createMockJob = (event: string, payload: unknown): QueuedJob<{ event: string; payload: unknown }> => ({
+      id: 'test-job-id',
+      payload: { event, payload },
+      createdAt: new Date().toISOString(),
+    })
+
+    const createMockContext = (): JobContext & { resolve: <T = unknown>(name: string) => T } => ({
+      jobId: 'test-job-id',
+      attemptNumber: 1,
+      queueName: 'events',
+      resolve: <T = unknown>(name: string): T => { throw new Error(`No mock for ${name}`) },
+    })
+
+    it('flag ON: dispatches wildcard persistent subscribers that exact-match never reached', async () => {
+      process.env.OM_EVENTS_SINGLE_DELIVERY = 'true'
+      clearListenerCache()
+      const calls: string[] = []
+      registerCliModules([{
+        id: 'm',
+        subscribers: [
+          { id: 'wildcard:persistent', event: '*', persistent: true, handler: () => { calls.push('wild') } },
+        ],
+      }])
+
+      await handle(createMockJob('any.event', {}), createMockContext())
+
+      expect(calls).toEqual(['wild'])
+    })
+
+    it('flag ON: excludes non-persistent subscribers from worker dispatch', async () => {
+      process.env.OM_EVENTS_SINGLE_DELIVERY = 'true'
+      clearListenerCache()
+      const calls: string[] = []
+      registerCliModules([{
+        id: 'm',
+        subscribers: [
+          { id: 'p', event: 'user.created', persistent: true, handler: () => { calls.push('p') } },
+          { id: 'e', event: 'user.created', persistent: false, handler: () => { calls.push('e') } },
+        ],
+      }])
+
+      await handle(createMockJob('user.created', {}), createMockContext())
+
+      expect(calls).toEqual(['p'])
+    })
+
+    it('flag OFF (default): preserves legacy exact-match dispatch and never reaches wildcards', async () => {
+      delete process.env.OM_EVENTS_SINGLE_DELIVERY
+      clearListenerCache()
+      const calls: string[] = []
+      registerCliModules([{
+        id: 'm',
+        subscribers: [
+          { id: 'p', event: 'user.created', persistent: true, handler: () => { calls.push('p') } },
+          { id: 'w', event: '*', persistent: true, handler: () => { calls.push('w') } },
+        ],
+      }])
+
+      await handle(createMockJob('user.created', {}), createMockContext())
+
+      // Legacy behavior: exact-match only, so the wildcard subscriber is not reached here.
+      expect(calls).toEqual(['p'])
+    })
+  })
 })

package/src/modules/events/workers/events.worker.ts

@@ -1,5 +1,7 @@
 import type { QueuedJob, JobContext, WorkerMeta } from '@open-mercato/queue'
 import { getCliModules } from '@open-mercato/shared/modules/registry'
+import { matchEventPattern } from '@open-mercato/shared/lib/events/patterns'
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 
 export const EVENTS_QUEUE_NAME = 'events'
 
@@ -29,9 +31,43 @@ type HandlerContext = {
 type SubscriberEntry = {
   id: string
   event: string
+  persistent?: boolean
   handler: (payload: unknown, ctx: unknown) => Promise<void> | void
 }
 
+/**
+ * Mirror of the event bus single-delivery flag. When enabled, the worker owns
+ * dispatch of every persistent subscriber and matches by pattern so wildcard
+ * (`event: '*'`) persistent subscribers are finally reached. Default off keeps
+ * the legacy exact-match dispatch of all subscribers.
+ */
+function isSingleDeliveryEnabled(): boolean {
+  return parseBooleanWithDefault(process.env.OM_EVENTS_SINGLE_DELIVERY, false)
+}
+
+/**
+ * Resolves the subscribers to run for a queued event.
+ * - Legacy (flag off): exact-match lookup of every subscriber for the event.
+ * - Single-delivery (flag on): persistent subscribers whose pattern matches the
+ *   event, including wildcards, so they run exactly once here instead of inline.
+ */
+function resolveSubscribers(
+  listeners: Map<string, SubscriberEntry[]>,
+  event: string,
+): SubscriberEntry[] {
+  if (!isSingleDeliveryEnabled()) {
+    return listeners.get(event) ?? []
+  }
+  const matched: SubscriberEntry[] = []
+  for (const [pattern, subs] of listeners) {
+    if (!matchEventPattern(event, pattern)) continue
+    for (const sub of subs) {
+      if (sub.persistent) matched.push(sub)
+    }
+  }
+  return matched
+}
+
 // Cached listener map - built once on first use
 let cachedListenerMap: Map<string, SubscriberEntry[]> | null = null
 
@@ -75,7 +111,7 @@ export default async function handle(
 ): Promise<void> {
   const { event, payload, options } = job.payload
   const listeners = getListenerMap()
-  const subscribers = listeners.get(event)
+  const subscribers = resolveSubscribers(listeners, event)
 
   if (!subscribers || subscribers.length === 0) return
 

package/src/types.ts

@@ -43,6 +43,12 @@ export type SubscriberDescriptor = {
   id: string
   /** Event name to subscribe to */
   event: string
+  /**
+   * Whether this subscriber is dispatched through the persistent events queue
+   * (events worker) rather than inline. Consulted by the `OM_EVENTS_SINGLE_DELIVERY`
+   * single-delivery path to decide which subscribers run inline vs in the worker.
+   */
+  persistent?: boolean
   /** Handler function */
   handler: SubscriberHandler
 }
@@ -100,8 +106,10 @@ export interface EventBus {
    *
    * @param event - Event name to listen for
    * @param handler - Handler function
+   * @param options - Optional registration options. `persistent: true` marks the
+   *   handler as worker-dispatched so the single-delivery path skips it inline.
    */
-  on(event: string, handler: SubscriberHandler): void
+  on(event: string, handler: SubscriberHandler, options?: { persistent?: boolean }): void
 
   /**
    * Register multiple module subscribers at once.