@open-mercato/events 0.8.1-develop.7296.1.2111d779db → 0.9.0

package/src/__tests__/broadcast-coalescing-bus.test.ts

@@ -0,0 +1,409 @@
+const publishCrossProcessEventMock = jest.fn(async () => undefined)
+
+jest.mock('../bridge', () => ({
+  publishCrossProcessEvent: (...args: unknown[]) => publishCrossProcessEventMock(...args),
+  registerCrossProcessEventListener: jest.fn(),
+  CROSS_PROCESS_EVENT_INSTANCE_ID: 'test-instance',
+}))
+
+import { createModuleEvents } from '@open-mercato/shared/modules/events'
+import { createEventBus, registerGlobalEventTap } from '@open-mercato/events/bus'
+import { resetBroadcastCoalescerForTests } from '@open-mercato/events/broadcast-coalescer'
+
+const INTERVAL_MS = 50
+
+createModuleEvents({
+  moduleId: 'coalesce_test',
+  events: [
+    { id: 'coalesce_test.bulk.created', label: 'Bulk Created', clientBroadcast: true, broadcastCoalescing: true },
+    { id: 'coalesce_test.plain.created', label: 'Plain Created', clientBroadcast: true },
+    { id: 'coalesce_test.recipient.created', label: 'Recipient Created', clientBroadcast: true, broadcastCoalescing: true },
+    { id: 'coalesce_test.portal.created', label: 'Portal Created', portalBroadcast: true, broadcastCoalescing: true },
+  ] as const,
+})
+
+function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+describe('event bus browser-delivery coalescing', () => {
+  const resolve = ((name: string) => name) as never
+  const originalInterval = process.env.OM_BROADCAST_COALESCE_INTERVAL_MS
+  let unregisterTap: (() => void) | null = null
+
+  beforeEach(() => {
+    publishCrossProcessEventMock.mockClear()
+    process.env.OM_BROADCAST_COALESCE_INTERVAL_MS = String(INTERVAL_MS)
+  })
+
+  afterEach(() => {
+    unregisterTap?.()
+    unregisterTap = null
+    resetBroadcastCoalescerForTests()
+    if (originalInterval === undefined) delete process.env.OM_BROADCAST_COALESCE_INTERVAL_MS
+    else process.env.OM_BROADCAST_COALESCE_INTERVAL_MS = originalInterval
+  })
+
+  it('keeps domain delivery per record while collapsing the browser dispatch', async () => {
+    const bus = createEventBus({ resolve, queueStrategy: 'local' })
+    const subscriberCalls: string[] = []
+    const tappedIds: string[] = []
+
+    bus.on('coalesce_test.bulk.created', async (payload) => {
+      subscriberCalls.push(String((payload as { id: string }).id))
+    })
+    unregisterTap = registerGlobalEventTap((_event, payload) => {
+      tappedIds.push(String((payload as { id: string }).id))
+    })
+
+    for (let index = 0; index < 100; index += 1) {
+      await bus.emit(
+        'coalesce_test.bulk.created',
+        { id: `product-${index}`, tenantId: 'tenant-1', organizationId: 'org-1' },
+        { tenantId: 'tenant-1', organizationId: 'org-1' },
+      )
+    }
+    await wait(INTERVAL_MS * 2)
+
+    // The hard requirement from the issue: the domain event still fires once per
+    // record, so webhooks, notification handlers and indexers are untouched.
+    expect(subscriberCalls).toHaveLength(100)
+    expect(subscriberCalls[0]).toBe('product-0')
+    expect(subscriberCalls[99]).toBe('product-99')
+
+    // The browser half collapses, and the burst still ends on the final record.
+    expect(tappedIds.length).toBeLessThan(100)
+    expect(tappedIds[0]).toBe('product-0')
+    expect(tappedIds[tappedIds.length - 1]).toBe('product-99')
+
+    // The pg_notify roundtrip collapses with it — half the cost the issue names.
+    expect(publishCrossProcessEventMock.mock.calls.length).toBe(tappedIds.length)
+  })
+
+  it('leaves an event that did not opt in on the per-record path', async () => {
+    const bus = createEventBus({ resolve, queueStrategy: 'local' })
+    const tappedIds: string[] = []
+    unregisterTap = registerGlobalEventTap((_event, payload) => {
+      tappedIds.push(String((payload as { id: string }).id))
+    })
+
+    for (let index = 0; index < 10; index += 1) {
+      await bus.emit(
+        'coalesce_test.plain.created',
+        { id: `product-${index}`, tenantId: 'tenant-1', organizationId: 'org-1' },
+        { tenantId: 'tenant-1', organizationId: 'org-1' },
+      )
+    }
+
+    expect(tappedIds).toHaveLength(10)
+    expect(publishCrossProcessEventMock).toHaveBeenCalledTimes(10)
+  })
+
+  it('never delivers one tenant or organization payload under another scope', async () => {
+    const bus = createEventBus({ resolve, queueStrategy: 'local' })
+    const seen: Array<{ tenantId: string; organizationId: string; id: string }> = []
+    unregisterTap = registerGlobalEventTap((_event, payload) => {
+      const data = payload as { id: string; tenantId: string; organizationId: string }
+      seen.push({ tenantId: data.tenantId, organizationId: data.organizationId, id: data.id })
+    })
+
+    const scopes = [
+      { tenantId: 'tenant-a', organizationId: 'org-1' },
+      { tenantId: 'tenant-b', organizationId: 'org-1' },
+      { tenantId: 'tenant-a', organizationId: 'org-2' },
+    ]
+
+    for (let round = 0; round < 5; round += 1) {
+      for (const scope of scopes) {
+        await bus.emit(
+          'coalesce_test.bulk.created',
+          { id: `${scope.tenantId}-${scope.organizationId}-${round}`, ...scope },
+          scope,
+        )
+      }
+    }
+    await wait(INTERVAL_MS * 2)
+
+    // Every scope gets its own leading edge and its own trailing flush, and no
+    // delivered payload ever carries a scope other than the one it was keyed by.
+    for (const scope of scopes) {
+      const forScope = seen.filter((entry) => entry.tenantId === scope.tenantId && entry.organizationId === scope.organizationId)
+      expect(forScope.length).toBeGreaterThanOrEqual(2)
+      expect(forScope[forScope.length - 1].id).toBe(`${scope.tenantId}-${scope.organizationId}-4`)
+      for (const entry of forScope) {
+        expect(entry.id.startsWith(`${scope.tenantId}-${scope.organizationId}-`)).toBe(true)
+      }
+    }
+  })
+
+  it('flushes the tail on a natural exit as well as on a signal', async () => {
+    const registered: string[] = []
+    const onceSpy = jest.spyOn(process, 'once').mockImplementation(function (this: NodeJS.Process, event: string) {
+      registered.push(event)
+      return this
+    } as never)
+
+    try {
+      delete (globalThis as Record<string, unknown>).__openMercatoBroadcastCoalescerShutdown__
+      createEventBus({ resolve, queueStrategy: 'local' })
+    } finally {
+      onceSpy.mockRestore()
+    }
+
+    // The trailing timer is unref'd, so a CLI that emits and exits normally never
+    // sees a signal — beforeExit is the hook that saves its tail.
+    expect(registered).toEqual(expect.arrayContaining(['SIGTERM', 'SIGINT', 'beforeExit']))
+  })
+
+  it('re-raises a signal after the flush only when no other listener owns the exit', async () => {
+    const handlers = new Map<string, () => void>()
+    const onceSpy = jest.spyOn(process, 'once').mockImplementation(function (this: NodeJS.Process, event: string, handler: () => void) {
+      handlers.set(event, handler)
+      return this
+    } as never)
+    try {
+      delete (globalThis as Record<string, unknown>).__openMercatoBroadcastCoalescerShutdown__
+      createEventBus({ resolve, queueStrategy: 'local' })
+    } finally {
+      onceSpy.mockRestore()
+    }
+
+    const killSpy = jest.spyOn(process, 'kill').mockImplementation(() => true)
+    const listenerCountSpy = jest.spyOn(process, 'listenerCount')
+    const bus = createEventBus({ resolve, queueStrategy: 'local' })
+    const tappedIds: string[] = []
+    unregisterTap = registerGlobalEventTap((_event, payload) => {
+      tappedIds.push(String((payload as { id: string }).id))
+    })
+    try {
+      for (const id of ['first', 'tail']) {
+        await bus.emit(
+          'coalesce_test.bulk.created',
+          { id, tenantId: 'tenant-1', organizationId: 'org-1' },
+          { tenantId: 'tenant-1', organizationId: 'org-1' },
+        )
+      }
+
+      listenerCountSpy.mockReturnValue(0)
+      handlers.get('SIGINT')?.()
+      await wait(INTERVAL_MS / 5)
+      expect(tappedIds).toEqual(['first', 'tail'])
+      expect(killSpy).toHaveBeenCalledWith(process.pid, 'SIGINT')
+
+      killSpy.mockClear()
+      listenerCountSpy.mockReturnValue(1)
+      handlers.get('SIGTERM')?.()
+      await wait(INTERVAL_MS / 5)
+      expect(killSpy).not.toHaveBeenCalled()
+    } finally {
+      killSpy.mockRestore()
+      listenerCountSpy.mockRestore()
+    }
+  })
+
+  it('keys a present-but-empty options tenant per payload tenant, so no tenant suppresses another', async () => {
+    const bus = createEventBus({ resolve, queueStrategy: 'local' })
+    const tenants = ['tenant-a', 'tenant-b']
+
+    for (let round = 0; round < 3; round += 1) {
+      for (const tenantId of tenants) {
+        await bus.emit(
+          'coalesce_test.bulk.created',
+          { id: `${tenantId}-${round}`, tenantId, organizationId: 'org-1' },
+          { tenantId: undefined },
+        )
+      }
+    }
+    await wait(INTERVAL_MS * 2)
+
+    const published = publishCrossProcessEventMock.mock.calls.map((call) => (call as unknown[])[1] as { id: string; tenantId: string })
+    for (const tenantId of tenants) {
+      const forTenant = published.filter((entry) => entry.tenantId === tenantId)
+      expect(forTenant.length).toBeGreaterThanOrEqual(2)
+      expect(forTenant[forTenant.length - 1].id).toBe(`${tenantId}-2`)
+    }
+  })
+
+  it('keys portal organizations from the payload even when options carry a trusted tenant', async () => {
+    const bus = createEventBus({ resolve, queueStrategy: 'local' })
+    const seen: Array<{ organizationId: string; id: string }> = []
+    unregisterTap = registerGlobalEventTap((_event, payload) => {
+      const data = payload as { id: string; organizationId: string }
+      seen.push({ organizationId: data.organizationId, id: data.id })
+    })
+    const organizations = ['org-1', 'org-2']
+
+    for (let round = 0; round < 3; round += 1) {
+      for (const organizationId of organizations) {
+        await bus.emit(
+          'coalesce_test.portal.created',
+          { id: `${organizationId}-${round}`, tenantId: 'tenant-1', organizationId },
+          { tenantId: 'tenant-1' },
+        )
+      }
+    }
+    await wait(INTERVAL_MS * 2)
+
+    for (const organizationId of organizations) {
+      const forOrganization = seen.filter((entry) => entry.organizationId === organizationId)
+      expect(forOrganization.length).toBeGreaterThanOrEqual(2)
+      expect(forOrganization[forOrganization.length - 1].id).toBe(`${organizationId}-2`)
+    }
+  })
+
+  it('does not share a key between absent and present-but-empty options tenants', async () => {
+    const bus = createEventBus({ resolve, queueStrategy: 'local' })
+    const tappedIds: string[] = []
+    unregisterTap = registerGlobalEventTap((_event, payload) => {
+      tappedIds.push(String((payload as { id: string }).id))
+    })
+    const payload = { tenantId: 'tenant-1', organizationId: 'org-1' }
+
+    await bus.emit('coalesce_test.bulk.created', { ...payload, id: 'absent' }, {})
+    await bus.emit('coalesce_test.bulk.created', { ...payload, id: 'present-empty' }, { tenantId: undefined })
+
+    expect(tappedIds).toEqual(['absent', 'present-empty'])
+  })
+
+  it('never delivers one recipient user\'s payload under another recipient user\'s key', async () => {
+    const bus = createEventBus({ resolve, queueStrategy: 'local' })
+    const seen: Array<{ recipientUserId: string; id: string }> = []
+    unregisterTap = registerGlobalEventTap((_event, payload) => {
+      const data = payload as { id: string; recipientUserId: string }
+      seen.push({ recipientUserId: data.recipientUserId, id: data.id })
+    })
+
+    // Same tenant/org for both users — options carry no recipient dimension at
+    // all, so only the payload-derived union in the coalescing key can keep
+    // these two audiences from suppressing each other.
+    const users = ['user-a', 'user-b']
+    for (let round = 0; round < 5; round += 1) {
+      for (const recipientUserId of users) {
+        await bus.emit(
+          'coalesce_test.recipient.created',
+          { id: `${recipientUserId}-${round}`, tenantId: 'tenant-1', organizationId: 'org-1', recipientUserId },
+          { tenantId: 'tenant-1', organizationId: 'org-1' },
+        )
+      }
+    }
+    await wait(INTERVAL_MS * 2)
+
+    for (const recipientUserId of users) {
+      const forUser = seen.filter((entry) => entry.recipientUserId === recipientUserId)
+      expect(forUser.length).toBeGreaterThanOrEqual(2)
+      expect(forUser[forUser.length - 1].id).toBe(`${recipientUserId}-4`)
+      for (const entry of forUser) {
+        expect(entry.id.startsWith(`${recipientUserId}-`)).toBe(true)
+      }
+    }
+  })
+
+  it('never delivers one recipient role\'s payload under another recipient role\'s key', async () => {
+    const bus = createEventBus({ resolve, queueStrategy: 'local' })
+    const seen: Array<{ recipientRoleId: string; id: string }> = []
+    unregisterTap = registerGlobalEventTap((_event, payload) => {
+      const data = payload as { id: string; recipientRoleId: string }
+      seen.push({ recipientRoleId: data.recipientRoleId, id: data.id })
+    })
+
+    const roles = ['role-a', 'role-b']
+    for (let round = 0; round < 5; round += 1) {
+      for (const recipientRoleId of roles) {
+        await bus.emit(
+          'coalesce_test.recipient.created',
+          { id: `${recipientRoleId}-${round}`, tenantId: 'tenant-1', organizationId: 'org-1', recipientRoleId },
+          { tenantId: 'tenant-1', organizationId: 'org-1' },
+        )
+      }
+    }
+    await wait(INTERVAL_MS * 2)
+
+    for (const recipientRoleId of roles) {
+      const forRole = seen.filter((entry) => entry.recipientRoleId === recipientRoleId)
+      expect(forRole.length).toBeGreaterThanOrEqual(2)
+      expect(forRole[forRole.length - 1].id).toBe(`${recipientRoleId}-4`)
+      for (const entry of forRole) {
+        expect(entry.id.startsWith(`${recipientRoleId}-`)).toBe(true)
+      }
+    }
+  })
+
+  it('never delivers one tenant\'s payload under another tenant\'s key for a portal-only event', async () => {
+    const bus = createEventBus({ resolve, queueStrategy: 'local' })
+    const seen: Array<{ tenantId: string; id: string }> = []
+    unregisterTap = registerGlobalEventTap((_event, payload) => {
+      const data = payload as { id: string; tenantId: string }
+      seen.push({ tenantId: data.tenantId, id: data.id })
+    })
+
+    // A portal-only broadcast has no `clientBroadcast`, so `resolveCrossProcessEmitOptions`
+    // never promotes payload scope into options for it — the coalescing key can
+    // only be correct here if it reads tenantId straight off the payload, the
+    // way this test never passes it in `options` at all.
+    const tenants = ['tenant-a', 'tenant-b']
+    for (let round = 0; round < 5; round += 1) {
+      for (const tenantId of tenants) {
+        await bus.emit(
+          'coalesce_test.portal.created',
+          { id: `${tenantId}-${round}`, tenantId },
+        )
+      }
+    }
+    await wait(INTERVAL_MS * 2)
+
+    for (const tenantId of tenants) {
+      const forTenant = seen.filter((entry) => entry.tenantId === tenantId)
+      expect(forTenant.length).toBeGreaterThanOrEqual(2)
+      expect(forTenant[forTenant.length - 1].id).toBe(`${tenantId}-4`)
+      for (const entry of forTenant) {
+        expect(entry.id.startsWith(`${tenantId}-`)).toBe(true)
+      }
+    }
+  })
+
+  it('restores per-record browser delivery when the interval is disabled', async () => {
+    process.env.OM_BROADCAST_COALESCE_INTERVAL_MS = '0'
+    const bus = createEventBus({ resolve, queueStrategy: 'local' })
+    const tappedIds: string[] = []
+    unregisterTap = registerGlobalEventTap((_event, payload) => {
+      tappedIds.push(String((payload as { id: string }).id))
+    })
+
+    for (let index = 0; index < 10; index += 1) {
+      await bus.emit(
+        'coalesce_test.bulk.created',
+        { id: `product-${index}`, tenantId: 'tenant-1', organizationId: 'org-1' },
+        { tenantId: 'tenant-1', organizationId: 'org-1' },
+      )
+    }
+
+    expect(tappedIds).toHaveLength(10)
+    expect(publishCrossProcessEventMock).toHaveBeenCalledTimes(10)
+  })
+
+  it('restores the develop dispatch order (pg_notify publish after inline) when the interval is disabled', async () => {
+    process.env.OM_BROADCAST_COALESCE_INTERVAL_MS = '0'
+    const bus = createEventBus({ resolve, queueStrategy: 'local' })
+    const order: string[] = []
+    bus.on('coalesce_test.bulk.created', async () => {
+      order.push('inline')
+    })
+    publishCrossProcessEventMock.mockImplementationOnce(async () => {
+      order.push('publish')
+    })
+
+    // On the non-coalesced path (and on develop before this feature existed),
+    // the pg_notify publish that reaches other processes always ran AFTER inline
+    // in-memory delivery. The coalesced path bundles it with the tap dispatch
+    // instead, ahead of inline delivery — `OM_BROADCAST_COALESCE_INTERVAL_MS=0`
+    // promises to fully restore the develop order, not merely the per-record
+    // delivery count.
+    await bus.emit(
+      'coalesce_test.bulk.created',
+      { id: 'product-0', tenantId: 'tenant-1', organizationId: 'org-1' },
+      { tenantId: 'tenant-1', organizationId: 'org-1' },
+    )
+
+    expect(order).toEqual(['inline', 'publish'])
+  })
+})

package/src/broadcast-coalescer.ts

@@ -0,0 +1,204 @@
+import { parseNumberWithDefault } from '@open-mercato/shared/lib/number'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+/**
+ * Coalesces the BROWSER half of an event emit.
+ *
+ * A `clientBroadcast: true` event costs a serialized `pg_notify` roundtrip plus a
+ * tenant-wide SSE fan-out on every emit, so a bulk writer pays both once per
+ * record even though its browser consumers only refresh a list. Events that opt
+ * in with `broadcastCoalescing: true` route their browser dispatch through here:
+ * the first emit of a burst goes out immediately (leading edge) and later emits
+ * sharing a key replace the pending payload instead of being delivered.
+ *
+ * A trailing flush is ALWAYS armed, so the last emit of a burst is delivered and
+ * a DataTable never ends the burst stale. This is where the mechanism goes past
+ * the progress service's private throttle, which can drop its tail only because
+ * its terminal transitions emit through a separate unthrottled path.
+ *
+ * Inline subscribers, webhooks and the queue never reach this module — the domain
+ * event still fires once per record.
+ */
+
+const DEFAULT_COALESCE_INTERVAL_MS = 250
+const PENDING_BROADCASTS_KEY = '__openMercatoPendingBroadcasts__'
+
+const logger = createLogger('events').child({ component: 'broadcast-coalescer' })
+
+type BroadcastDispatch = () => Promise<void>
+
+type PendingBroadcast = {
+  /** The newest superseding dispatch awaiting the trailing flush, if any. */
+  pending: BroadcastDispatch | null
+  timer: ReturnType<typeof setTimeout> | null
+  suppressed: number
+}
+
+/**
+ * Held on `globalThis` for the same reason as the bus's global taps and producer
+ * queue: a fresh event bus is built per request, so per-bus state would coalesce
+ * nothing across the emits of a single bulk job.
+ */
+function getPendingBroadcasts(): Map<string, PendingBroadcast> {
+  const existing = (globalThis as Record<string, unknown>)[PENDING_BROADCASTS_KEY]
+  if (existing instanceof Map) {
+    return existing as Map<string, PendingBroadcast>
+  }
+  const created = new Map<string, PendingBroadcast>()
+  ;(globalThis as Record<string, unknown>)[PENDING_BROADCASTS_KEY] = created
+  return created
+}
+
+/**
+ * Minimum elapsed time between coalesced browser deliveries of one key. `0`
+ * disables coalescing process-wide, restoring per-record delivery — the runtime
+ * escape hatch, mirroring `OM_PROGRESS_BROADCAST_MIN_INTERVAL_MS=0`.
+ */
+export function resolveBroadcastCoalesceIntervalMs(): number {
+  return parseNumberWithDefault(
+    process.env.OM_BROADCAST_COALESCE_INTERVAL_MS,
+    DEFAULT_COALESCE_INTERVAL_MS,
+    { min: 0, integer: true },
+  )
+}
+
+function armTimer(key: string, intervalMs: number): ReturnType<typeof setTimeout> {
+  const timer = setTimeout(() => {
+    void onWindowClosed(key, intervalMs)
+  }, intervalMs)
+  // Never keep a CLI or worker process alive just to flush a browser delivery.
+  // The shutdown hook flushes what is still pending on the way out.
+  if (typeof (timer as { unref?: () => void }).unref === 'function') {
+    ;(timer as { unref: () => void }).unref()
+  }
+  return timer
+}
+
+async function onWindowClosed(key: string, intervalMs: number): Promise<void> {
+  const entries = getPendingBroadcasts()
+  const entry = entries.get(key)
+  if (!entry) return
+
+  const pending = entry.pending
+  if (!pending) {
+    // The window closed with nothing superseded: the burst is over.
+    entry.timer = null
+    entries.delete(key)
+    return
+  }
+
+  const suppressed = entry.suppressed
+  entry.pending = null
+  entry.suppressed = 0
+  entry.timer = null
+
+  await runDispatch(pending, key)
+  if (suppressed > 0) {
+    logger.debug('Coalesced browser deliveries', { key, suppressed })
+  }
+
+  // Re-arm only AFTER the dispatch settles, so one key never has two deliveries
+  // in flight. Re-arming first would let a slow pg_notify roundtrip overlap the
+  // next window and land an older payload last — the exact staleness coalescing
+  // exists to prevent. As a side effect the window self-extends under load,
+  // which is the right behavior for a throttle. Submissions arriving during the
+  // dispatch still queue on the entry, which is still in the map.
+  const current = entries.get(key)
+  if (!current) return
+  if (current.pending) current.timer = armTimer(key, intervalMs)
+  else entries.delete(key)
+}
+
+/**
+ * A deferred dispatch has no caller awaiting it, so its failure must be
+ * contained here — `bus.emit` already logs-and-continues on a synchronous
+ * publish failure, and one failed flush must not stop the next window.
+ */
+async function runDispatch(dispatch: BroadcastDispatch, key: string): Promise<void> {
+  try {
+    await dispatch()
+  } catch (error) {
+    logger.error('Coalesced broadcast dispatch failed', { key, err: error })
+  }
+}
+
+/**
+ * Submit a browser dispatch for `key`. Resolves once the caller's obligation is
+ * discharged: immediately-dispatched submissions resolve after delivery,
+ * superseded ones resolve as soon as they are queued.
+ */
+export async function submitBroadcast(
+  key: string,
+  dispatch: BroadcastDispatch,
+  options?: { intervalMs?: number },
+): Promise<void> {
+  const intervalMs = options?.intervalMs ?? resolveBroadcastCoalesceIntervalMs()
+  if (intervalMs <= 0) {
+    await dispatch()
+    return
+  }
+
+  const entries = getPendingBroadcasts()
+  const entry = entries.get(key)
+  if (!entry) {
+    entries.set(key, { pending: null, timer: armTimer(key, intervalMs), suppressed: 0 })
+    await dispatch()
+    return
+  }
+
+  if (entry.pending) entry.suppressed += 1
+  entry.pending = dispatch
+}
+
+/**
+ * Upper bound for a flush on the way out of a process. Fixed, and independent of
+ * and shorter than OM_BROADCAST_COALESCE_INTERVAL_MS's own window, so a stalled
+ * Postgres connection at exit degrades to the already-accepted dropped-tail case
+ * instead of hanging the exit.
+ */
+export const BROADCAST_FLUSH_DEADLINE_MS = 3000
+
+/**
+ * Deliver every survivor still awaiting its trailing flush. Wired into the
+ * process shutdown hook and the CLI exit path so a stop does not swallow the tail
+ * of a burst. Never rejects: every entry is settled on its own. With
+ * `deadlineMs`, resolves no later than that even if a dispatch hangs.
+ */
+export async function flushPendingBroadcasts(options?: { deadlineMs?: number }): Promise<void> {
+  const entries = getPendingBroadcasts()
+  const drained: Array<Promise<void>> = []
+  for (const [key, entry] of entries) {
+    if (entry.timer) clearTimeout(entry.timer)
+    const pending = entry.pending
+    entries.delete(key)
+    if (pending) drained.push(runDispatch(pending, key))
+  }
+  const settled = Promise.allSettled(drained).then(() => undefined)
+  const deadlineMs = options?.deadlineMs
+  if (deadlineMs === undefined) {
+    await settled
+    return
+  }
+  let expire: () => void = () => {}
+  const expired = new Promise<void>((resolve) => {
+    expire = resolve
+  })
+  const deadline = setTimeout(() => expire(), Math.max(0, deadlineMs))
+  if (typeof (deadline as { unref?: () => void }).unref === 'function') {
+    ;(deadline as { unref: () => void }).unref()
+  }
+  try {
+    await Promise.race([settled, expired])
+  } finally {
+    clearTimeout(deadline)
+  }
+}
+
+/** Drop all pending state without dispatching. Tests only. */
+export function resetBroadcastCoalescerForTests(): void {
+  const entries = getPendingBroadcasts()
+  for (const entry of entries.values()) {
+    if (entry.timer) clearTimeout(entry.timer)
+  }
+  entries.clear()
+}