@open-mercato/events 0.6.6-develop.5586.1.c9ed1d68a8 → 0.6.6-develop.5594.1.30cd738303

package/.turbo/turbo-build.log

@@ -1,2 +1,2 @@
-[build:events] found 8 entry points
+[build:events] found 9 entry points
 [build:events] built successfully

package/AGENTS.md

@@ -76,15 +76,18 @@ 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`)
+### Persistent delivery: single-delivery (`OM_EVENTS_SINGLE_DELIVERY`, default ON)
 
-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.
+Single-delivery is the default. A persistent emit is delivered on exactly one path:
 
-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.
+- the bus skips inline delivery of **persistent-marked** subscribers on a persistent emit (ephemeral subscribers still run inline — read-your-writes paths like `query_index.upsert_one` are `persistent: false` and are unaffected);
+- the events worker dispatches **persistent** subscribers via `matchEventPattern`, so wildcard (`event: '*'`) persistent subscribers (workflow triggers, business-rules CRUD trigger, webhook outbound dispatch) are 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.
+This avoids the legacy dual-dispatch (set `OM_EVENTS_SINGLE_DELIVERY=false` to opt back in) where persistent emits ran inline **and** in the worker — double-running exact-match persistent subscribers (duplicate notifications/emails) and never reaching wildcard persistent subscribers in the worker. Both halves read the same env var and MUST agree within a process.
+
+**Worker guard (silent-loss protection).** With single-delivery on, persistent subscribers run ONLY in the worker. The server bootstrap (`mercato server`/`start`) reconciles the flag against worker availability: if a process auto-spawns no events worker (`AUTO_SPAWN_WORKERS=off`) and `OM_EVENTS_EXTERNAL_WORKER` is not set, it logs a loud warning and falls back to inline dual-dispatch so persistent side effects are never silently dropped. Run an events worker out-of-process and set `OM_EVENTS_EXTERNAL_WORKER=true` to keep single-delivery without auto-spawn. Transient worker downtime is not a concern — the durable queue holds jobs until a worker returns; the guard only catches the "no worker at all" misconfiguration. Reconcile logic: `reconcileSingleDelivery` in `@open-mercato/events/single-delivery` (mirrored for the CLI in `packages/cli/src/lib/events-single-delivery.ts`).
+
+**Enqueue-only emits.** Pass `{ persistent: true, deliverInline: false }` to hand a heavy persistent job (e.g. a full query-index rebuild) to the durable queue without ANY inline delivery, independent of the single-delivery flag. Only use it when every subscriber to the event is `persistent: true`. This is the "Ask First: changing persistent delivery semantics" surface — coordinate before altering these defaults.
 
 ## Queue Integration
 

package/dist/bus.js

@@ -1,5 +1,6 @@
 import { createQueue } from "@open-mercato/queue";
 import { parseBooleanWithDefault } from "@open-mercato/shared/lib/boolean";
+import { isSingleDeliveryRequested } from "./single-delivery.js";
 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";
@@ -7,7 +8,7 @@ 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);
+  return isSingleDeliveryRequested();
 }
 const GLOBAL_EVENT_TAPS_KEY = "__openMercatoEventBusGlobalTaps__";
 function hasTenantScope(payload) {
@@ -126,8 +127,11 @@ function createEventBus(opts) {
         console.error(`[events] Global tap error for "${event}":`, error);
       }
     }
-    const skipPersistentInline = Boolean(options?.persistent) && isSingleDeliveryEnabled();
-    await deliver(event, payload, options, skipPersistentInline);
+    const enqueueOnly = Boolean(options?.persistent) && options?.deliverInline === false;
+    if (!enqueueOnly) {
+      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 { 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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",
+  "sourcesContent": ["import { createQueue } from '@open-mercato/queue'\nimport type { Queue } from '@open-mercato/queue'\nimport { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'\nimport { isSingleDeliveryRequested } from './single-delivery'\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. Defaults ON; the server bootstrap\n * reconciles the env against worker availability (and may rewrite it to `false`\n * for a worker-less process). Both the bus and the events worker read the same\n * (possibly reconciled) env var, so they always agree within a process.\n */\nfunction isSingleDeliveryEnabled(): boolean {\n  return isSingleDeliveryRequested()\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    //\n    // `deliverInline: false` on a persistent emit is enqueue-only: skip inline\n    // delivery entirely so a heavy persistent job runs solely in the events\n    // worker, off the caller's request path (the queued enqueue below still\n    // happens). Without this, a persistent emit dual-dispatches by default and\n    // runs the subscriber inline in the caller's request too.\n    const enqueueOnly = Boolean(options?.persistent) && options?.deliverInline === false\n    if (!enqueueOnly) {\n      const skipPersistentInline = Boolean(options?.persistent) && isSingleDeliveryEnabled()\n      await deliver(event, payload, options, skipPersistentInline)\n    }\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": "AAAA,SAAS,mBAAmB;AAE5B,SAAS,+BAA+B;AACxC,SAAS,iCAAiC;AAC1C,SAAS,yBAAyB;AAClC,SAAS,0BAA0B;AACnC,SAAS,wBAAwB;AACjC,SAAS,yCAAyC;AAClD,SAAS,gCAAgC;AAWzC,MAAM,oBAAoB;AAW1B,SAAS,0BAAmC;AAC1C,SAAO,0BAA0B;AACnC;AAGA,MAAM,wBAAwB;AAE9B,SAAS,eAAe,SAAgC;AACtD,SAAO,OAAQ,SAAqC,aAAa,YAC5D,OAAQ,QAAoC,QAAQ,EAAE,KAAK,EAAE,SAAS;AAC7E;AAEA,SAAS,qBAA0C;AACjD,QAAM,WAAY,WAAuC,qBAAqB;AAC9E,MAAI,oBAAoB,KAAK;AAC3B,WAAO;AAAA,EACT;AACA,QAAM,UAAU,oBAAI,IAAoB;AACvC,EAAC,WAAuC,qBAAqB,IAAI;AAClE,SAAO;AACT;AAEO,SAAS,uBAAuB,SAAqC;AAC1E,QAAM,OAAO,mBAAmB;AAChC,OAAK,IAAI,OAAO;AAChB,SAAO,MAAM;AACX,SAAK,OAAO,OAAO;AAAA,EACrB;AACF;AAkBA,MAAM,4BAA4B;AAClC,MAAM,+BAA+B;AAErC,SAAS,0BAAmC;AAC1C,SAAO,wBAAwB,QAAQ,IAAI,2BAA2B,IAAI;AAC5E;AAEA,SAAS,2BAA6D;AACpE,QAAM,WAAY,WAAuC,yBAAyB;AAClF,MAAI,oBAAoB,KAAK;AAC3B,WAAO;AAAA,EACT;AACA,QAAM,UAAU,oBAAI,IAAiC;AACpD,EAAC,WAAuC,yBAAyB,IAAI;AACtE,SAAO;AACT;AAEA,SAAS,+BAAqC;AAC5C,MAAK,WAAuC,4BAA4B,EAAG;AAC3E,QAAM,WAAW,MAAM;AACrB,UAAM,WAAW,yBAAyB;AAC1C,eAAW,eAAe,SAAS,OAAO,GAAG;AAC3C,cAAQ,QAAQ,YAAY,MAAM,CAAC,EAAE,MAAM,MAAM;AAAA,MAAC,CAAC;AAAA,IACrD;AACA,aAAS,MAAM;AAAA,EACjB;AACA,UAAQ,KAAK,WAAW,QAAQ;AAChC,UAAQ,KAAK,UAAU,QAAQ;AAC9B,EAAC,WAAuC,4BAA4B,IAAI;AAC3E;AAgCO,SAAS,eAAe,MAAkC;AAE/D,QAAM,YAAY,oBAAI,IAAoC;AAG1D,QAAM,qBAAqB,oBAAI,IAAuB;AAGtD,QAAM,gBAAgB,KAAK,kBACxB,QAAQ,IAAI,mBAAmB,UAAU,UAAU;AAGtD,MAAI,QAAoC;AAUxC,WAAS,WAAgC;AACvC,QAAI,kBAAkB,WAAW,CAAC,wBAAwB,GAAG;AAC3D,UAAI,CAAC,OAAO;AACV,gBAAQ,kBAAkB,UACtB,YAA0B,mBAAmB,SAAS;AAAA,UACpD,YAAY,EAAE,KAAK,mBAAmB,OAAO,EAAE;AAAA,QACjD,CAAC,IACD,YAA0B,mBAAmB,OAAO;AAAA,MAC1D;AACA,aAAO;AAAA,IACT;AAEA,UAAM,WAAW,mBAAmB,OAAO;AAC3C,UAAM,WAAW,yBAAyB;AAC1C,UAAM,WAAW,SAAS,QAAQ;AAClC,QAAI,SAAS,SAAS,IAAI,QAAQ;AAClC,QAAI,CAAC,QAAQ;AACX,eAAS,YAA0B,mBAAmB,SAAS;AAAA,QAC7D,YAAY,EAAE,KAAK,SAAS;AAAA,MAC9B,CAAC;AACD,eAAS,IAAI,UAAU,MAAM;AAC7B,mCAA6B;AAAA,IAC/B;AACA,WAAO;AAAA,EACT;AAMA,iBAAe,QACb,OACA,SACA,SACA,iBAAiB,OACF;AAEf,eAAW,CAAC,SAAS,QAAQ,KAAK,WAAW;AAC3C,UAAI,CAAC,kBAAkB,OAAO,OAAO,EAAG;AACxC,UAAI,CAAC,YAAY,SAAS,SAAS,EAAG;AAEtC,iBAAW,WAAW,UAAU;AAG9B,YAAI,kBAAkB,mBAAmB,IAAI,OAAO,EAAG;AACvD,YAAI;AAEF,gBAAM,QAAQ,QAAQ,QAAQ,SAAS;AAAA,YACrC,SAAS,KAAK;AAAA,YACd,WAAW;AAAA,YACX,UAAU,SAAS,YAAY;AAAA,YAC/B,gBAAgB,SAAS,kBAAkB;AAAA,UAC7C,CAAC,CAAC;AAAA,QACJ,SAAS,OAAO;AACd,kBAAQ,MAAM,+BAA+B,KAAK,gBAAgB,OAAO,OAAO,KAAK;AAAA,QACvF;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAKA,WAAS,GAAG,OAAe,SAA4B,SAA0C;AAC/F,QAAI,CAAC,UAAU,IAAI,KAAK,GAAG;AACzB,gBAAU,IAAI,OAAO,oBAAI,IAAI,CAAC;AAAA,IAChC;AACA,cAAU,IAAI,KAAK,EAAG,IAAI,OAAO;AACjC,QAAI,SAAS,YAAY;AACvB,yBAAmB,IAAI,OAAO;AAAA,IAChC;AAAA,EACF;AAKA,WAAS,0BAA0B,MAAoC;AACrE,eAAW,OAAO,MAAM;AACtB,SAAG,IAAI,OAAO,IAAI,SAAS,EAAE,YAAY,IAAI,WAAW,CAAC;AAAA,IAC3D;AAAA,EACF;AAOA,iBAAe,KACb,OACA,SACA,SACe;AACf,UAAM,OAAO,mBAAmB;AAChC,eAAW,OAAO,MAAM;AACtB,UAAI;AACF,cAAM,QAAQ,QAAQ,IAAI,OAAO,SAAS,OAAO,CAAC;AAAA,MACpD,SAAS,OAAO;AACd,gBAAQ,MAAM,kCAAkC,KAAK,MAAM,KAAK;AAAA,MAClE;AAAA,IACF;AAWA,UAAM,cAAc,QAAQ,SAAS,UAAU,KAAK,SAAS,kBAAkB;AAC/E,QAAI,CAAC,aAAa;AAChB,YAAM,uBAAuB,QAAQ,SAAS,UAAU,KAAK,wBAAwB;AACrF,YAAM,QAAQ,OAAO,SAAS,SAAS,oBAAoB;AAAA,IAC7D;AAEA,QAAI,iBAAiB,KAAK,KAAK,eAAe,OAAO,GAAG;AACtD,UAAI;AACF,cAAM,yBAAyB,OAAO,SAAS,OAAO;AAAA,MACxD,SAAS,OAAO;AACd,gBAAQ,MAAM,6CAA6C,KAAK,MAAM,KAAK;AAAA,MAC7E;AAAA,IACF;AAGA,QAAI,SAAS,YAAY;AACvB,YAAM,IAAI,SAAS;AACnB,YAAM,EAAE,QAAQ,EAAE,OAAO,SAAS,QAAQ,CAAC;AAAA,IAC7C;AAAA,EACF;AAKA,iBAAe,aAA2C;AACxD,UAAM,IAAI,SAAS;AACnB,WAAO,EAAE,MAAM;AAAA,EACjB;AAGA,QAAM,YAAY;AAElB,SAAO;AAAA,IACL;AAAA,IACA;AAAA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;",
   "names": []
 }

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

@@ -1,6 +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";
+import { isSingleDeliveryRequested } from "../../../single-delivery.js";
 const EVENTS_QUEUE_NAME = "events";
 const DEFAULT_CONCURRENCY = 1;
 const envConcurrency = process.env.WORKERS_EVENTS_CONCURRENCY;
@@ -9,7 +9,7 @@ const metadata = {
   concurrency: envConcurrency ? parseInt(envConcurrency, 10) : DEFAULT_CONCURRENCY
 };
 function isSingleDeliveryEnabled() {
-  return parseBooleanWithDefault(process.env.OM_EVENTS_SINGLE_DELIVERY, false);
+  return isSingleDeliveryRequested();
 }
 function resolveSubscribers(listeners, event) {
   if (!isSingleDeliveryEnabled()) {

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'\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;",
+  "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 { isSingleDeliveryRequested } from '../../../single-delivery'\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. Defaults ON;\n * reconciled by the server bootstrap against worker availability and read from\n * the same env var as the bus so the two always agree within a process.\n */\nfunction isSingleDeliveryEnabled(): boolean {\n  return isSingleDeliveryRequested()\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,iCAAiC;AAEnC,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;AA+BA,SAAS,0BAAmC;AAC1C,SAAO,0BAA0B;AACnC;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/dist/single-delivery.js

@@ -0,0 +1,25 @@
+import { parseBooleanWithDefault } from "@open-mercato/shared/lib/boolean";
+const EVENTS_SINGLE_DELIVERY_ENV = "OM_EVENTS_SINGLE_DELIVERY";
+const EVENTS_EXTERNAL_WORKER_ENV = "OM_EVENTS_EXTERNAL_WORKER";
+function isSingleDeliveryRequested(env = process.env) {
+  return parseBooleanWithDefault(env[EVENTS_SINGLE_DELIVERY_ENV], true);
+}
+function isExternalWorkerAcknowledged(env = process.env) {
+  return parseBooleanWithDefault(env[EVENTS_EXTERNAL_WORKER_ENV], false);
+}
+function reconcileSingleDelivery(input) {
+  if (!input.requested) return { effective: false };
+  if (input.workersAvailable) return { effective: true };
+  return {
+    effective: false,
+    warning: `[events] ${EVENTS_SINGLE_DELIVERY_ENV} is on (default) but this process auto-spawns no events worker (AUTO_SPAWN_WORKERS=off) and ${EVENTS_EXTERNAL_WORKER_ENV} is not set. Persistent subscribers would be skipped inline with nothing to drain the queue, silently dropping notifications, queued emails, and indexing. Falling back to legacy inline dual-dispatch for safety. To keep single-delivery, run an events worker (\`mercato queue worker events\`) and set ${EVENTS_EXTERNAL_WORKER_ENV}=true, or enable AUTO_SPAWN_WORKERS.`
+  };
+}
+export {
+  EVENTS_EXTERNAL_WORKER_ENV,
+  EVENTS_SINGLE_DELIVERY_ENV,
+  isExternalWorkerAcknowledged,
+  isSingleDeliveryRequested,
+  reconcileSingleDelivery
+};
+//# sourceMappingURL=single-delivery.js.map

package/dist/single-delivery.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/single-delivery.ts"],
+  "sourcesContent": ["import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'\n\n/** Env var that toggles single-path persistent delivery. Defaults ON (see below). */\nexport const EVENTS_SINGLE_DELIVERY_ENV = 'OM_EVENTS_SINGLE_DELIVERY'\n/**\n * Operator acknowledgment that an events worker runs OUT OF PROCESS (separate\n * `mercato queue worker` container/process), so the server bootstrap must not\n * disable single-delivery just because it does not auto-spawn workers itself.\n */\nexport const EVENTS_EXTERNAL_WORKER_ENV = 'OM_EVENTS_EXTERNAL_WORKER'\n\ntype EnvSource = Record<string, string | undefined>\n\n/**\n * Whether single-path persistent delivery is requested.\n *\n * Default ON: a persistent emit is delivered on exactly one path \u2014 persistent\n * subscribers run in the events worker (matched by pattern, so wildcard\n * persistent subscribers are reached), ephemeral subscribers still run inline.\n * This is the correct behavior; the legacy dual-dispatch (inline AND worker)\n * double-ran exact-match persistent subscribers and never reached wildcard\n * persistent subscribers in the worker. Set the env to a false token to opt back\n * into legacy dual-dispatch.\n *\n * The server bootstrap reconciles this against worker availability (see\n * {@link reconcileSingleDelivery}) and may rewrite the env to `false` for a\n * process that would otherwise skip inline delivery with no worker to drain the\n * queue. The bus and the events worker both read the (possibly reconciled) env,\n * so they always agree within a process.\n */\nexport function isSingleDeliveryRequested(env: EnvSource = process.env): boolean {\n  return parseBooleanWithDefault(env[EVENTS_SINGLE_DELIVERY_ENV], true)\n}\n\nexport function isExternalWorkerAcknowledged(env: EnvSource = process.env): boolean {\n  return parseBooleanWithDefault(env[EVENTS_EXTERNAL_WORKER_ENV], false)\n}\n\nexport type SingleDeliveryReconciliation = {\n  /** The value the process should actually use. */\n  effective: boolean\n  /** Set when single-delivery was requested but disabled for safety. */\n  warning?: string\n}\n\n/**\n * Guards the default-on single-delivery against the silent-loss failure mode:\n * with single-delivery on, persistent subscribers are skipped inline and ONLY\n * the events worker dispatches them. If no worker drains the queue, those\n * persistent side effects (notifications, queued emails, indexing) never run.\n *\n * The durable queue already covers transient worker downtime \u2014 a job persists\n * and drains when a worker returns. The dangerous case is a process configured\n * to run with NO events worker at all (auto-spawn off and no external worker).\n * For that case this fails safe: it disables single-delivery so persistent\n * subscribers run inline (dual-dispatch) and side effects are never dropped,\n * and surfaces a loud warning telling the operator how to opt back in.\n */\nexport function reconcileSingleDelivery(input: {\n  requested: boolean\n  workersAvailable: boolean\n}): SingleDeliveryReconciliation {\n  if (!input.requested) return { effective: false }\n  if (input.workersAvailable) return { effective: true }\n  return {\n    effective: false,\n    warning:\n      `[events] ${EVENTS_SINGLE_DELIVERY_ENV} is on (default) but this process auto-spawns no events worker ` +\n      `(AUTO_SPAWN_WORKERS=off) and ${EVENTS_EXTERNAL_WORKER_ENV} is not set. Persistent subscribers would be ` +\n      `skipped inline with nothing to drain the queue, silently dropping notifications, queued emails, and ` +\n      `indexing. Falling back to legacy inline dual-dispatch for safety. To keep single-delivery, run an events ` +\n      `worker (\\`mercato queue worker events\\`) and set ${EVENTS_EXTERNAL_WORKER_ENV}=true, or enable ` +\n      `AUTO_SPAWN_WORKERS.`,\n  }\n}\n"],
+  "mappings": "AAAA,SAAS,+BAA+B;AAGjC,MAAM,6BAA6B;AAMnC,MAAM,6BAA6B;AAqBnC,SAAS,0BAA0B,MAAiB,QAAQ,KAAc;AAC/E,SAAO,wBAAwB,IAAI,0BAA0B,GAAG,IAAI;AACtE;AAEO,SAAS,6BAA6B,MAAiB,QAAQ,KAAc;AAClF,SAAO,wBAAwB,IAAI,0BAA0B,GAAG,KAAK;AACvE;AAsBO,SAAS,wBAAwB,OAGP;AAC/B,MAAI,CAAC,MAAM,UAAW,QAAO,EAAE,WAAW,MAAM;AAChD,MAAI,MAAM,iBAAkB,QAAO,EAAE,WAAW,KAAK;AACrD,SAAO;AAAA,IACL,WAAW;AAAA,IACX,SACE,YAAY,0BAA0B,+FACN,0BAA0B,8SAGN,0BAA0B;AAAA,EAElF;AACF;",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/events",
-  "version": "0.6.6-develop.5586.1.c9ed1d68a8",
+  "version": "0.6.6-develop.5594.1.30cd738303",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -32,8 +32,8 @@
     }
   },
   "dependencies": {
-    "@open-mercato/queue": "0.6.6-develop.5586.1.c9ed1d68a8",
-    "@open-mercato/shared": "0.6.6-develop.5586.1.c9ed1d68a8",
+    "@open-mercato/queue": "0.6.6-develop.5594.1.30cd738303",
+    "@open-mercato/shared": "0.6.6-develop.5594.1.30cd738303",
     "pg": "8.21.0"
   },
   "devDependencies": {

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

@@ -0,0 +1,44 @@
+import {
+  isSingleDeliveryRequested,
+  isExternalWorkerAcknowledged,
+  reconcileSingleDelivery,
+} from '@open-mercato/events/single-delivery'
+
+describe('isSingleDeliveryRequested', () => {
+  it('defaults ON when unset', () => {
+    expect(isSingleDeliveryRequested({})).toBe(true)
+  })
+
+  it('honors an explicit false token', () => {
+    expect(isSingleDeliveryRequested({ OM_EVENTS_SINGLE_DELIVERY: 'false' })).toBe(false)
+    expect(isSingleDeliveryRequested({ OM_EVENTS_SINGLE_DELIVERY: '0' })).toBe(false)
+  })
+})
+
+describe('isExternalWorkerAcknowledged', () => {
+  it('defaults off and reads truthy tokens', () => {
+    expect(isExternalWorkerAcknowledged({})).toBe(false)
+    expect(isExternalWorkerAcknowledged({ OM_EVENTS_EXTERNAL_WORKER: 'true' })).toBe(true)
+  })
+})
+
+describe('reconcileSingleDelivery', () => {
+  it('stays on when a worker is available', () => {
+    expect(reconcileSingleDelivery({ requested: true, workersAvailable: true })).toEqual({
+      effective: true,
+    })
+  })
+
+  it('falls back to inline with a warning when no worker is available', () => {
+    const result = reconcileSingleDelivery({ requested: true, workersAvailable: false })
+    expect(result.effective).toBe(false)
+    expect(result.warning).toContain('OM_EVENTS_SINGLE_DELIVERY')
+    expect(result.warning).toContain('OM_EVENTS_EXTERNAL_WORKER')
+  })
+
+  it('stays off (no warning) when not requested', () => {
+    expect(reconcileSingleDelivery({ requested: false, workersAvailable: false })).toEqual({
+      effective: false,
+    })
+  })
+})

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

@@ -38,15 +38,31 @@ describe('Event bus single-delivery (OM_EVENTS_SINGLE_DELIVERY)', () => {
     return { id, event, persistent, handler: () => { sink.push(id) } }
   }
 
-  test('flag OFF (default): a persistent subscriber still runs inline on a persistent emit', async () => {
+  test('default (unset): a persistent subscriber is skipped inline (single-delivery is default-on)', 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),
+      makeSub('ephemeral-sub', 'demo', false, calls),
+    ])
+
+    await bus.emit('demo', { a: 1 }, { persistent: true })
+
+    // Default-on: the persistent subscriber is deferred to the worker; only the
+    // ephemeral subscriber runs inline.
+    expect(calls).toEqual(['ephemeral-sub'])
+  })
+
+  test('flag explicitly OFF (legacy opt-out): a persistent subscriber still runs inline', async () => {
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'false'
+    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.
+    // Legacy dual-dispatch: inline delivery is preserved when explicitly opted out.
     expect(calls).toEqual(['persistent-sub'])
   })
 
@@ -93,3 +109,79 @@ describe('Event bus single-delivery (OM_EVENTS_SINGLE_DELIVERY)', () => {
     expect(list.length).toBeGreaterThanOrEqual(1)
   })
 })
+
+/**
+ * Regression coverage for the onboarding stall: `enqueueQueryIndexRebuild` emits
+ * a persistent `query_index.reindex` with `deliverInline: false` so the heavy
+ * rebuild runs solely in the events worker, never inline in the onboarding
+ * request. A bare `{ persistent: true }` dual-dispatches and ran the reindex
+ * inline (reusing the request's committed em), which is exactly the bug.
+ */
+describe('Event bus enqueue-only persistent emit (deliverInline: false)', () => {
+  const origCwd = process.cwd()
+  const origFlag = process.env.OM_EVENTS_SINGLE_DELIVERY
+  let tmp: string
+
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'events-enqueue-only-'))
+    process.chdir(tmp)
+    delete process.env.QUEUE_STRATEGY
+    delete process.env.EVENTS_STRATEGY
+    // Prove the skip is driven by deliverInline, not the single-delivery flag.
+    delete process.env.OM_EVENTS_SINGLE_DELIVERY
+  })
+
+  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 pushHandler(id: string, event: string, persistent: boolean, sink: string[]): SubscriberDescriptor {
+    return { id, event, persistent, handler: () => { sink.push(id) } }
+  }
+
+  test('skips inline delivery of every subscriber but still enqueues for the worker', async () => {
+    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([
+      pushHandler('persistent-sub', 'query_index.reindex', true, calls),
+      pushHandler('ephemeral-sub', 'query_index.reindex', false, calls),
+    ])
+
+    await bus.emit('query_index.reindex', { entityType: 'catalog:product' }, { persistent: true, deliverInline: false })
+
+    // Nothing ran inline — the worker is the sole dispatcher.
+    expect(calls).toEqual([])
+    const list = JSON.parse(fs.readFileSync(queuePath, 'utf8'))
+    expect(Array.isArray(list)).toBe(true)
+    expect(list.length).toBeGreaterThanOrEqual(1)
+  })
+
+  test('deliverInline: false has no effect on a non-persistent emit', async () => {
+    const calls: string[] = []
+    const bus = createEventBus({ resolve: ((name: string) => name) as never })
+    bus.registerModuleSubscribers([pushHandler('sub', 'demo', false, calls)])
+
+    // Not persistent → nothing is enqueued, so inline is the only path and runs.
+    await bus.emit('demo', { a: 1 }, { deliverInline: false })
+
+    expect(calls).toEqual(['sub'])
+  })
+
+  test('deliverInline unset under legacy opt-out preserves inline dual-dispatch', async () => {
+    // Isolate the deliverInline default from the single-delivery default by
+    // explicitly opting out: a persistent emit with deliverInline unset still
+    // runs inline (legacy dual-dispatch).
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'false'
+    const calls: string[] = []
+    const bus = createEventBus({ resolve: ((name: string) => name) as never })
+    bus.registerModuleSubscribers([pushHandler('persistent-sub', 'demo', true, calls)])
+
+    await bus.emit('demo', { a: 1 }, { persistent: true })
+
+    expect(calls).toEqual(['persistent-sub'])
+  })
+})

package/src/bus.ts

@@ -1,6 +1,7 @@
 import { createQueue } from '@open-mercato/queue'
 import type { Queue } from '@open-mercato/queue'
 import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
+import { isSingleDeliveryRequested } from './single-delivery'
 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'
@@ -22,12 +23,13 @@ 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.
+ * ephemeral subscribers keep running inline. Defaults ON; the server bootstrap
+ * reconciles the env against worker availability (and may rewrite it to `false`
+ * for a worker-less process). Both the bus and the events worker read the same
+ * (possibly reconciled) env var, so they always agree within a process.
  */
 function isSingleDeliveryEnabled(): boolean {
-  return parseBooleanWithDefault(process.env.OM_EVENTS_SINGLE_DELIVERY, false)
+  return isSingleDeliveryRequested()
 }
 
 type GlobalEventTap = (event: string, payload: EventPayload, options?: EmitOptions) => void | Promise<void>
@@ -259,8 +261,17 @@ export function createEventBus(opts: CreateBusOptions): EventBus {
     // 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)
+    //
+    // `deliverInline: false` on a persistent emit is enqueue-only: skip inline
+    // delivery entirely so a heavy persistent job runs solely in the events
+    // worker, off the caller's request path (the queued enqueue below still
+    // happens). Without this, a persistent emit dual-dispatches by default and
+    // runs the subscriber inline in the caller's request too.
+    const enqueueOnly = Boolean(options?.persistent) && options?.deliverInline === false
+    if (!enqueueOnly) {
+      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

@@ -33,6 +33,19 @@ describe('Events Worker', () => {
   })
 
   describe('handle', () => {
+    // These tests exercise the legacy exact-match dispatch (the worker runs every
+    // matching subscriber, persistent or not). Single-delivery (now default-on)
+    // dispatches only persistent subscribers in the worker, so pin the legacy
+    // path here; single-delivery semantics are covered in the sibling describe.
+    const ORIG_SINGLE_DELIVERY = process.env.OM_EVENTS_SINGLE_DELIVERY
+    beforeEach(() => {
+      process.env.OM_EVENTS_SINGLE_DELIVERY = 'false'
+    })
+    afterEach(() => {
+      if (ORIG_SINGLE_DELIVERY === undefined) delete process.env.OM_EVENTS_SINGLE_DELIVERY
+      else process.env.OM_EVENTS_SINGLE_DELIVERY = ORIG_SINGLE_DELIVERY
+    })
+
     const createMockJob = (
       event: string,
       payload: unknown,
@@ -486,7 +499,7 @@ describe('Events Worker', () => {
       expect(calls).toEqual(['p'])
     })
 
-    it('flag OFF (default): preserves legacy exact-match dispatch and never reaches wildcards', async () => {
+    it('default (unset): dispatches wildcard persistent subscribers (single-delivery is default-on)', async () => {
       delete process.env.OM_EVENTS_SINGLE_DELIVERY
       clearListenerCache()
       const calls: string[] = []
@@ -500,6 +513,25 @@ describe('Events Worker', () => {
 
       await handle(createMockJob('user.created', {}), createMockContext())
 
+      // Default-on: pattern dispatch reaches both the exact-match and the wildcard
+      // persistent subscriber.
+      expect(calls.sort()).toEqual(['p', 'w'])
+    })
+
+    it('flag explicitly OFF (legacy opt-out): preserves exact-match dispatch and never reaches wildcards', async () => {
+      process.env.OM_EVENTS_SINGLE_DELIVERY = 'false'
+      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,7 +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'
+import { isSingleDeliveryRequested } from '../../../single-delivery'
 
 export const EVENTS_QUEUE_NAME = 'events'
 
@@ -38,11 +38,12 @@ type SubscriberEntry = {
 /**
  * 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.
+ * (`event: '*'`) persistent subscribers are finally reached. Defaults ON;
+ * reconciled by the server bootstrap against worker availability and read from
+ * the same env var as the bus so the two always agree within a process.
  */
 function isSingleDeliveryEnabled(): boolean {
-  return parseBooleanWithDefault(process.env.OM_EVENTS_SINGLE_DELIVERY, false)
+  return isSingleDeliveryRequested()
 }
 
 /**

package/src/single-delivery.ts

@@ -0,0 +1,75 @@
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
+
+/** Env var that toggles single-path persistent delivery. Defaults ON (see below). */
+export const EVENTS_SINGLE_DELIVERY_ENV = 'OM_EVENTS_SINGLE_DELIVERY'
+/**
+ * Operator acknowledgment that an events worker runs OUT OF PROCESS (separate
+ * `mercato queue worker` container/process), so the server bootstrap must not
+ * disable single-delivery just because it does not auto-spawn workers itself.
+ */
+export const EVENTS_EXTERNAL_WORKER_ENV = 'OM_EVENTS_EXTERNAL_WORKER'
+
+type EnvSource = Record<string, string | undefined>
+
+/**
+ * Whether single-path persistent delivery is requested.
+ *
+ * Default ON: a persistent emit is delivered on exactly one path — persistent
+ * subscribers run in the events worker (matched by pattern, so wildcard
+ * persistent subscribers are reached), ephemeral subscribers still run inline.
+ * This is the correct behavior; the legacy dual-dispatch (inline AND worker)
+ * double-ran exact-match persistent subscribers and never reached wildcard
+ * persistent subscribers in the worker. Set the env to a false token to opt back
+ * into legacy dual-dispatch.
+ *
+ * The server bootstrap reconciles this against worker availability (see
+ * {@link reconcileSingleDelivery}) and may rewrite the env to `false` for a
+ * process that would otherwise skip inline delivery with no worker to drain the
+ * queue. The bus and the events worker both read the (possibly reconciled) env,
+ * so they always agree within a process.
+ */
+export function isSingleDeliveryRequested(env: EnvSource = process.env): boolean {
+  return parseBooleanWithDefault(env[EVENTS_SINGLE_DELIVERY_ENV], true)
+}
+
+export function isExternalWorkerAcknowledged(env: EnvSource = process.env): boolean {
+  return parseBooleanWithDefault(env[EVENTS_EXTERNAL_WORKER_ENV], false)
+}
+
+export type SingleDeliveryReconciliation = {
+  /** The value the process should actually use. */
+  effective: boolean
+  /** Set when single-delivery was requested but disabled for safety. */
+  warning?: string
+}
+
+/**
+ * Guards the default-on single-delivery against the silent-loss failure mode:
+ * with single-delivery on, persistent subscribers are skipped inline and ONLY
+ * the events worker dispatches them. If no worker drains the queue, those
+ * persistent side effects (notifications, queued emails, indexing) never run.
+ *
+ * The durable queue already covers transient worker downtime — a job persists
+ * and drains when a worker returns. The dangerous case is a process configured
+ * to run with NO events worker at all (auto-spawn off and no external worker).
+ * For that case this fails safe: it disables single-delivery so persistent
+ * subscribers run inline (dual-dispatch) and side effects are never dropped,
+ * and surfaces a loud warning telling the operator how to opt back in.
+ */
+export function reconcileSingleDelivery(input: {
+  requested: boolean
+  workersAvailable: boolean
+}): SingleDeliveryReconciliation {
+  if (!input.requested) return { effective: false }
+  if (input.workersAvailable) return { effective: true }
+  return {
+    effective: false,
+    warning:
+      `[events] ${EVENTS_SINGLE_DELIVERY_ENV} is on (default) but this process auto-spawns no events worker ` +
+      `(AUTO_SPAWN_WORKERS=off) and ${EVENTS_EXTERNAL_WORKER_ENV} is not set. Persistent subscribers would be ` +
+      `skipped inline with nothing to drain the queue, silently dropping notifications, queued emails, and ` +
+      `indexing. Falling back to legacy inline dual-dispatch for safety. To keep single-delivery, run an events ` +
+      `worker (\`mercato queue worker events\`) and set ${EVENTS_EXTERNAL_WORKER_ENV}=true, or enable ` +
+      `AUTO_SPAWN_WORKERS.`,
+  }
+}

package/src/types.ts

@@ -61,6 +61,19 @@ export type SubscriberDescriptor = {
 export type EmitOptions = {
   /** If true, the event will be persisted to a queue for async processing */
   persistent?: boolean
+  /**
+   * Controls inline in-memory delivery on a persistent emit. Defaults to `true`,
+   * which preserves the legacy dual-dispatch behavior (subscribers run inline AND
+   * the event is enqueued for the worker). Set to `false` to ENQUEUE-ONLY: inline
+   * delivery is skipped entirely and the events worker is the sole dispatcher.
+   *
+   * Use this to hand a heavy persistent job (e.g. a full query-index rebuild) to
+   * the durable queue without running it on the caller's request path. Has no
+   * effect unless `persistent: true`. Ephemeral subscribers to the event will not
+   * run inline either, so only use it for events whose subscribers are all
+   * worker-dispatched (`persistent: true`).
+   */
+  deliverInline?: boolean
   /** Trusted tenant scope for subscribers that must not rely on payload scope */
   tenantId?: string | null
   /** Trusted organization scope for subscribers that must not rely on payload scope */