@open-mercato/queue 0.6.7-develop.6828.1.ab1620a63e → 0.6.7-develop.6842.1.8cd8a8883c

package/src/__tests__/async.strategy.test.ts

@@ -18,6 +18,7 @@ const workerOn = jest.fn()
 
 jest.mock('@open-mercato/shared/lib/redis/connection', () => ({
   getRedisUrlOrThrow: jest.fn(),
+  parseRedisUrl: jest.requireActual('@open-mercato/shared/lib/redis/connection').parseRedisUrl,
 }))
 
 jest.mock('bullmq', () => {
@@ -60,7 +61,7 @@ describe('Queue - async strategy', () => {
     getRedisUrlOrThrowMock.mockReturnValue('rediss://default:secret@example.com:6380/1')
   })
 
-  it('passes the full Redis URL to BullMQ when using env-based async config', async () => {
+  it('passes parsed Redis connection fields to BullMQ for env-based async config', async () => {
     const queue = createQueue<{ value: number }>('test-queue', 'async', {
       concurrency: 3,
     })
@@ -69,19 +70,35 @@ describe('Queue - async strategy', () => {
     await queue.process(async () => {})
 
     expect(queueCtor).toHaveBeenCalledWith('test-queue', {
-      connection: { url: 'rediss://default:secret@example.com:6380/1' },
+      connection: {
+        host: 'example.com',
+        port: 6380,
+        username: 'default',
+        password: 'secret',
+        db: 1,
+        tls: {},
+        family: undefined,
+      },
     })
     expect(workerCtor).toHaveBeenCalledWith(
       'test-queue',
       expect.any(Function),
       {
-        connection: { url: 'rediss://default:secret@example.com:6380/1' },
+        connection: {
+          host: 'example.com',
+          port: 6380,
+          username: 'default',
+          password: 'secret',
+          db: 1,
+          tls: {},
+          family: undefined,
+        },
         concurrency: 3,
       },
     )
   })
 
-  it('preserves an explicit Redis URL without converting it to host/port fields', async () => {
+  it('preserves URL connection semantics when converting to BullMQ fields', async () => {
     const queue = createQueue<{ value: number }>('test-queue', 'async', {
       connection: {
         url: 'rediss://user:secret@example.com:6380/4?family=6',
@@ -91,7 +108,15 @@ describe('Queue - async strategy', () => {
     await queue.enqueue({ value: 42 })
 
     expect(queueCtor).toHaveBeenCalledWith('test-queue', {
-      connection: { url: 'rediss://user:secret@example.com:6380/4?family=6' },
+      connection: {
+        host: 'example.com',
+        port: 6380,
+        username: 'user',
+        password: 'secret',
+        db: 4,
+        tls: {},
+        family: 6,
+      },
     })
   })
 

package/src/__tests__/async.telemetry.test.ts

@@ -0,0 +1,123 @@
+// An OTLP backend must be active for the async strategy to delegate tracing to
+// bullmq-otel. Set before any module reads the (memoized) telemetry env, and
+// restored afterwards — process.env is shared across test files in the same
+// jest worker, and a leaked 'otlp' backend breaks sibling telemetry tests.
+const originalTelemetryBackend = process.env.TELEMETRY_BACKEND
+process.env.TELEMETRY_BACKEND = 'otlp'
+
+afterAll(() => {
+  if (originalTelemetryBackend === undefined) delete process.env.TELEMETRY_BACKEND
+  else process.env.TELEMETRY_BACKEND = originalTelemetryBackend
+})
+
+import { createQueue } from '../factory'
+import { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'
+import {
+  registerTelemetryRuntime,
+  resetTelemetryRuntime,
+} from '@open-mercato/shared/lib/telemetry/runtime'
+
+const queueCtor = jest.fn()
+const workerCtor = jest.fn()
+const queueAdd = jest.fn(async () => ({ id: 'bull-job-id' }))
+
+jest.mock('@open-mercato/shared/lib/redis/connection', () => ({
+  getRedisUrlOrThrow: jest.fn(),
+  parseRedisUrl: jest.requireActual('@open-mercato/shared/lib/redis/connection').parseRedisUrl,
+}))
+
+jest.mock('bullmq', () => {
+  class MockQueue<T> {
+    constructor(name: string, opts: unknown) {
+      queueCtor(name, opts)
+    }
+    add = queueAdd as unknown as (name: string, data: T, opts?: unknown) => Promise<{ id?: string }>
+    close = jest.fn(async () => {})
+    obliterate = jest.fn(async () => {})
+    getJobCounts = jest.fn(async () => ({ waiting: 0, active: 0, completed: 0, failed: 0 }))
+  }
+  class MockWorker<T> {
+    constructor(
+      name: string,
+      _processor: (job: { id?: string; data: T; attemptsMade: number }) => Promise<void>,
+      opts: unknown,
+    ) {
+      workerCtor(name, _processor, opts)
+    }
+    on = jest.fn()
+    close = jest.fn(async () => {})
+  }
+  return { Queue: MockQueue, Worker: MockWorker }
+})
+
+class MockBullMQOtel {
+  constructor(public readonly tracerName: string) {}
+}
+jest.mock('bullmq-otel', () => ({ BullMQOtel: MockBullMQOtel }))
+
+describe('Queue - async strategy telemetry wiring', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    ;(getRedisUrlOrThrow as jest.MockedFunction<typeof getRedisUrlOrThrow>).mockReturnValue(
+      'rediss://default:secret@example.com:6380/1',
+    )
+    registerTelemetryRuntime({
+      canUseGlobalTracePropagation: () => true,
+      captureTraceContext: () => ({}),
+      continueTrace: (_carrier, _name, fn) => fn(),
+      recordHttpDuration: () => {},
+      reportError: () => {},
+      shutdown: async () => {},
+    })
+  })
+
+  afterEach(() => {
+    resetTelemetryRuntime()
+  })
+
+  it('wires bullmq-otel into BOTH the queue and worker when they resolve concurrently', async () => {
+    const queue = createQueue<{ value: number }>('trace-queue', 'async', { concurrency: 3 })
+
+    // Resolve enqueue (Queue) and process (Worker) concurrently: both hit the
+    // shared telemetry resolution at once. The memoized in-flight promise must
+    // hand both the SAME bullmq-otel instance — never one with, one without.
+    await Promise.all([queue.enqueue({ value: 1 }), queue.process(async () => {})])
+
+    const queueOpts = queueCtor.mock.calls[0]?.[1] as { telemetry?: unknown }
+    const workerOpts = workerCtor.mock.calls[0]?.[2] as { telemetry?: unknown }
+    expect(queueOpts.telemetry).toBeInstanceOf(MockBullMQOtel)
+    expect(workerOpts.telemetry).toBeInstanceOf(MockBullMQOtel)
+    expect(queueOpts.telemetry).toBe(workerOpts.telemetry)
+  })
+
+  it('omits the metadata._trace carrier when bullmq-otel owns propagation', async () => {
+    const queue = createQueue<{ value: number }>('trace-queue', 'async')
+
+    await queue.enqueue({ value: 42 })
+
+    const jobData = queueAdd.mock.calls[0]?.[1] as Record<string, unknown>
+    expect(jobData).not.toHaveProperty('metadata')
+  })
+
+  it('uses the dedicated carrier when global propagation is not explicitly trusted', async () => {
+    resetTelemetryRuntime()
+    registerTelemetryRuntime({
+      canUseGlobalTracePropagation: () => false,
+      captureTraceContext: () => ({ traceparent: 'secure-carrier' }),
+      continueTrace: (_carrier, _name, fn) => fn(),
+      recordHttpDuration: () => {},
+      reportError: () => {},
+      shutdown: async () => {},
+    })
+    const queue = createQueue<{ value: number }>('secure-trace-queue', 'async')
+
+    await queue.enqueue({ value: 7 })
+
+    const queueOpts = queueCtor.mock.calls[0]?.[1] as { telemetry?: unknown }
+    const jobData = queueAdd.mock.calls[0]?.[1] as {
+      metadata?: { _trace?: { traceparent?: string } }
+    }
+    expect(queueOpts.telemetry).toBeUndefined()
+    expect(jobData.metadata?._trace?.traceparent).toBe('secure-carrier')
+  })
+})

package/src/__tests__/factory.test.ts

@@ -1,8 +1,9 @@
 import { resolveQueueStrategy, createModuleQueue } from '../factory'
-import { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'
+import { getRedisUrlOrThrow, parseRedisUrl } from '@open-mercato/shared/lib/redis/connection'
 
 jest.mock('@open-mercato/shared/lib/redis/connection', () => ({
   getRedisUrlOrThrow: jest.fn(),
+  parseRedisUrl: jest.fn(),
 }))
 
 jest.mock('bullmq', () => {
@@ -58,10 +59,12 @@ describe('resolveQueueStrategy', () => {
 describe('createModuleQueue', () => {
   const originalEnv = process.env.QUEUE_STRATEGY
   const getRedisUrlOrThrowMock = getRedisUrlOrThrow as jest.MockedFunction<typeof getRedisUrlOrThrow>
+  const parseRedisUrlMock = parseRedisUrl as jest.MockedFunction<typeof parseRedisUrl>
 
   beforeEach(() => {
     jest.clearAllMocks()
     getRedisUrlOrThrowMock.mockReturnValue('redis://localhost:6379')
+    parseRedisUrlMock.mockReturnValue({ host: 'localhost', port: 6379 })
   })
 
   afterEach(() => {
@@ -85,6 +88,7 @@ describe('createModuleQueue', () => {
     expect(queue.strategy).toBe('async')
     expect(queue.name).toBe('test-queue')
     expect(getRedisUrlOrThrowMock).toHaveBeenCalledWith('QUEUE')
+    expect(parseRedisUrlMock).toHaveBeenCalledWith('redis://localhost:6379')
   })
 
   it('passes concurrency to local strategy', () => {

package/src/__tests__/pending-probe.test.ts

@@ -2,7 +2,22 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { createQueue } from '../factory'
-import { getQueuePendingProbe } from '../pending-probe'
+import { __resetPendingProbeBullMQCache, getQueuePendingProbe } from '../pending-probe'
+
+const asyncQueueConstructor = jest.fn()
+const asyncQueueClose = jest.fn(async () => {})
+const asyncQueueGetJobCounts = jest.fn(async () => ({ waiting: 1, delayed: 0, active: 0 }))
+
+jest.mock('bullmq', () => ({
+  Queue: class MockQueue {
+    constructor(name: string, options: unknown) {
+      asyncQueueConstructor(name, options)
+    }
+
+    getJobCounts = asyncQueueGetJobCounts
+    close = asyncQueueClose
+  },
+}))
 
 describe('getQueuePendingProbe — local strategy', () => {
   const origCwd = process.cwd()
@@ -95,6 +110,11 @@ describe('getQueuePendingProbe — local strategy', () => {
 })
 
 describe('getQueuePendingProbe — async strategy', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    __resetPendingProbeBullMQCache()
+  })
+
   it('reports an error when QUEUE Redis URL is unset and no connection override is provided', async () => {
     const original = process.env.QUEUE_REDIS_URL
     const fallback = process.env.REDIS_URL
@@ -109,4 +129,23 @@ describe('getQueuePendingProbe — async strategy', () => {
       if (fallback !== undefined) process.env.REDIS_URL = fallback
     }
   })
+
+  it('converts a URL override to BullMQ connection fields', async () => {
+    const probe = await getQueuePendingProbe('async-probe', 'async', {
+      connection: { url: 'rediss://probe:secret@example.com:6380/3?family=6' },
+    })
+
+    expect(probe).toEqual(expect.objectContaining({ error: false, ready: 1 }))
+    expect(asyncQueueConstructor).toHaveBeenCalledWith('async-probe', {
+      connection: {
+        host: 'example.com',
+        port: 6380,
+        username: 'probe',
+        password: 'secret',
+        db: 3,
+        tls: {},
+        family: 6,
+      },
+    })
+  })
 })

package/src/__tests__/tracing.test.ts

@@ -0,0 +1,123 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { attachTraceMetadata, runJobInTrace } from '../tracing'
+import { createLocalQueue } from '../strategies/local'
+import { registerProvider, initTelemetry, shutdownTelemetry } from '@open-mercato/telemetry'
+import type { LogRecord, MetricPoint, Span, SpanOptions, TelemetryProvider, TraceCarrier } from '@open-mercato/telemetry'
+
+/**
+ * Verifies the enqueue → worker trace handoff: the active context is captured
+ * onto job metadata at enqueue, and the worker continues that trace at dispatch.
+ * Uses a recording provider under the explicitly enabled console seam rather
+ * than the real OTLP SDK.
+ */
+const spanNames: string[] = []
+const remoteCarriers: TraceCarrier[] = []
+
+function noopSpan(): Span {
+  return { setAttribute() {}, setAttributes() {}, recordException() {}, setStatus() {}, end() {} }
+}
+
+const recordingProvider: TelemetryProvider = {
+  name: 'console',
+  supports: ['traces'],
+  async start() {},
+  async shutdown() {},
+  runInSpan<T>(name: string, _o: SpanOptions, fn: (s: Span) => T): T {
+    spanNames.push(name)
+    return fn(noopSpan())
+  },
+  activeSpan: () => undefined,
+  activeTraceContext: () => undefined,
+  inject: (carrier) => {
+    carrier.traceparent = 'test-traceparent'
+  },
+  runInRemoteSpan<T>(carrier: TraceCarrier, name: string, _o: SpanOptions, fn: (s: Span) => T): T {
+    remoteCarriers.push(carrier)
+    spanNames.push(name)
+    return fn(noopSpan())
+  },
+  emitLog: (_r: LogRecord) => {},
+  recordMetric: (_p: MetricPoint) => {},
+}
+
+beforeAll(async () => {
+  process.env.TELEMETRY_BACKEND = 'console'
+  registerProvider(recordingProvider)
+  await initTelemetry()
+})
+
+afterAll(async () => {
+  await shutdownTelemetry()
+  delete process.env.TELEMETRY_BACKEND
+})
+
+describe('queue trace propagation', () => {
+  it('attaches the active trace carrier to job metadata at enqueue', () => {
+    const metadata = attachTraceMetadata(undefined)
+    expect(metadata).toEqual({ _trace: { traceparent: 'test-traceparent' } })
+  })
+
+  it('preserves existing metadata while attaching the trace carrier', () => {
+    const metadata = attachTraceMetadata({ foo: 'bar' })
+    expect(metadata).toMatchObject({ foo: 'bar', _trace: { traceparent: 'test-traceparent' } })
+  })
+
+  it('continues the producer trace from job metadata at dispatch', async () => {
+    const result = await runJobInTrace('orders-process', { _trace: { traceparent: 'tp-123' } }, () =>
+      Promise.resolve('done'),
+    )
+    expect(result).toBe('done')
+    expect(remoteCarriers).toContainEqual({ traceparent: 'tp-123' })
+    expect(spanNames).toContain('queue.orders-process')
+  })
+
+  it('runs jobs without a carrier under a fresh span (no crash)', async () => {
+    const result = await runJobInTrace('orders-process', undefined, () => Promise.resolve(42))
+    expect(result).toBe(42)
+  })
+})
+
+/**
+ * End-to-end through the REAL local strategy (file write + read + dispatch),
+ * proving the headline acceptance criterion: a queued job continues the
+ * enqueuing request's trace. This exercises the actual enqueue/dispatch wiring,
+ * not just the helpers above.
+ */
+describe('queue trace propagation (real local strategy)', () => {
+  let baseDir: string
+
+  beforeEach(() => {
+    baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'om-queue-trace-'))
+  })
+
+  afterEach(() => {
+    fs.rmSync(baseDir, { recursive: true, force: true })
+  })
+
+  it('persists the trace carrier on enqueue and continues it on dispatch', async () => {
+    const queue = createLocalQueue<{ orderId: string }>('orders-process', { baseDir })
+
+    await queue.enqueue({ orderId: 'o-1' })
+
+    // The carrier is written to the job's metadata — NOT the user payload.
+    const stored = JSON.parse(
+      fs.readFileSync(path.join(baseDir, 'orders-process', 'queue.json'), 'utf8'),
+    ) as Array<{ payload: unknown; metadata?: Record<string, unknown> }>
+    expect(stored[0].metadata).toEqual({ _trace: { traceparent: 'test-traceparent' } })
+    expect(stored[0].payload).toEqual({ orderId: 'o-1' })
+
+    let handlerRan = false
+    await queue.process((job) => {
+      handlerRan = true
+      // The handler still sees only its payload; the carrier is invisible to it.
+      expect(job.payload).toEqual({ orderId: 'o-1' })
+    })
+
+    expect(handlerRan).toBe(true)
+    // The worker continued the producer's trace under a `queue.<name>` span.
+    expect(remoteCarriers).toContainEqual({ traceparent: 'test-traceparent' })
+    expect(spanNames).toContain('queue.orders-process')
+  })
+})

package/src/__tests__/worker-shutdown-telemetry.test.ts

@@ -0,0 +1,80 @@
+import path from 'node:path'
+import fs from 'node:fs'
+import os from 'node:os'
+
+/**
+ * Regression: the worker's graceful shutdown used to close the queues
+ * and call process.exit() without flushing telemetry. A worker never returns
+ * from run(), so the CLI's post-run shutdownTelemetry() is unreachable — the
+ * BatchSpanProcessor's buffered tail (~5s of spans/logs) was dropped on every
+ * restart/redeploy. The shutdown handler must flush BEFORE exiting.
+ */
+
+import {
+  registerTelemetryRuntime,
+  resetTelemetryRuntime,
+  type TelemetryRuntime,
+} from '@open-mercato/shared/lib/telemetry/runtime'
+
+import { runWorker } from '../worker/runner'
+
+const mockCallOrder: string[] = []
+const runtime: TelemetryRuntime = {
+  canUseGlobalTracePropagation: () => false,
+  captureTraceContext: () => ({}),
+  continueTrace: (_carrier, _name, fn) => fn(),
+  recordHttpDuration: () => {},
+  reportError: () => {},
+  shutdown: jest.fn(async () => {
+    mockCallOrder.push('flush')
+  }),
+}
+
+describe('worker shutdown flushes telemetry', () => {
+  let tmpDir: string
+  let cwd: string
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'worker-shutdown-'))
+    cwd = process.cwd()
+    process.chdir(tmpDir)
+    mockCallOrder.length = 0
+    delete process.env.TELEMETRY_BACKEND
+    registerTelemetryRuntime(runtime)
+  })
+
+  afterEach(() => {
+    process.chdir(cwd)
+    resetTelemetryRuntime()
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('SIGTERM flushes telemetry before process.exit', async () => {
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+      mockCallOrder.push(`exit:${code ?? 0}`)
+      return undefined as never
+    }) as never)
+    const logSpy = jest.spyOn(console, 'log').mockImplementation(() => {})
+
+    try {
+      await runWorker({
+        queueName: 'shutdown-flush-test',
+        handler: async () => {},
+        strategy: 'local',
+        background: true,
+        gracefulShutdown: true,
+      })
+
+      process.emit('SIGTERM')
+      // The shutdown handler is async (close → flush → exit); let it settle.
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      expect(mockCallOrder).toContain('flush')
+      expect(mockCallOrder).toContain('exit:0')
+      expect(mockCallOrder.indexOf('flush')).toBeLessThan(mockCallOrder.indexOf('exit:0'))
+    } finally {
+      exitSpy.mockRestore()
+      logSpy.mockRestore()
+    }
+  })
+})

package/src/pending-probe.ts

@@ -149,14 +149,16 @@ async function probeAsyncQueue(
     return errorResult(queueName, 'async', new Error('bullmq is not installed'))
   }
 
-  const { getRedisUrl } = await import('@open-mercato/shared/lib/redis/connection')
+  const { getRedisUrl, parseRedisUrl } = await import('@open-mercato/shared/lib/redis/connection')
   let connection = options?.connection
   if (!connection) {
     const url = getRedisUrl('QUEUE')
     if (!url) {
       return errorResult(queueName, 'async', new Error('QUEUE Redis URL is not configured'))
     }
-    connection = { url }
+    connection = parseRedisUrl(url)
+  } else if (connection.url) {
+    connection = parseRedisUrl(connection.url)
   }
 
   let queue: InstanceType<BullMQModuleShape['Queue']> | null = null

package/src/strategies/async.ts

@@ -1,5 +1,7 @@
 import type { Queue, QueuedJob, JobHandler, AsyncQueueOptions, ProcessResult, EnqueueOptions, QueueJobScope } from '../types'
-import { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'
+import { getRedisUrlOrThrow, parseRedisUrl } from '@open-mercato/shared/lib/redis/connection'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { attachTraceMetadata, runJobInTrace } from '../tracing'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const packageLogger = createLogger('queue')
@@ -7,13 +9,13 @@ const packageLogger = createLogger('queue')
 // BullMQ interface types - we define the shape we use to maintain type safety
 // while keeping bullmq as an optional peer dependency
 type ConnectionOptions = {
-  url?: string
   host?: string
   port?: number
   username?: string
   password?: string
   db?: number
   tls?: Record<string, unknown>
+  family?: number
 }
 
 interface BullQueueInterface<T> {
@@ -43,14 +45,23 @@ interface BullWorkerInterface {
 }
 
 interface BullMQModule {
-  Queue: new <T>(name: string, opts: { connection: ConnectionOptions }) => BullQueueInterface<T>
+  Queue: new <T>(name: string, opts: { connection: ConnectionOptions; telemetry?: unknown }) => BullQueueInterface<T>
   Worker: new <T>(
     name: string,
     processor: (job: { id?: string; data: T; attemptsMade: number }) => Promise<void>,
-    opts: { connection: ConnectionOptions; concurrency: number; lockDuration?: number; maxStalledCount?: number }
+    opts: {
+      connection: ConnectionOptions
+      concurrency: number
+      telemetry?: unknown
+      lockDuration?: number
+      maxStalledCount?: number
+    }
   ) => BullWorkerInterface
 }
 
+/** The `bullmq-otel` package (optional). Loaded only when an OTLP backend is active. */
+type BullMQOtelModule = { BullMQOtel: new (tracerName: string) => object }
+
 const REMOVABLE_JOB_STATES = ['waiting', 'delayed', 'prioritized', 'paused', 'waiting-children']
 
 function payloadMatchesScope(payload: unknown, scope: QueueJobScope): boolean {
@@ -69,13 +80,13 @@ function payloadMatchesScope(payload: unknown, scope: QueueJobScope): boolean {
 /**
  * Resolves Redis connection options from various sources.
  *
- * BullMQ expects an ioredis-compatible connection object. Preserve the full
- * Redis URL under the `url` key so rediss://, username, database, and query
- * params are not lost in translation.
+ * BullMQ expects ioredis connection fields rather than a nested URL string.
+ * Parse URL-based configuration at this boundary while keeping the public
+ * queue API compatible with existing `{ url }` callers.
  */
 function resolveConnection(options?: AsyncQueueOptions['connection']): ConnectionOptions {
   if (options?.url) {
-    return { url: options.url }
+    return parseRedisUrl(options.url)
   }
 
   if (options?.host) {
@@ -86,10 +97,11 @@ function resolveConnection(options?: AsyncQueueOptions['connection']): Connectio
       password: options.password,
       db: options.db,
       tls: options.tls,
+      family: options.family,
     }
   }
 
-  return { url: getRedisUrlOrThrow('QUEUE') }
+  return parseRedisUrl(getRedisUrlOrThrow('QUEUE'))
 }
 
 /**
@@ -119,6 +131,10 @@ export function createAsyncQueue<T = unknown>(
   let bullQueue: BullQueueInterface<QueuedJob<T>> | null = null
   let bullWorker: BullWorkerInterface | null = null
   let bullmqModule: BullMQModule | null = null
+  // Resolved once: a BullMQOtel instance (delegate async tracing to BullMQ) or
+  // undefined (use our own metadata._trace carrier instead). Memoized as the
+  // in-flight promise so concurrent first-time callers share one resolution.
+  let telemetryPromise: Promise<object | undefined> | null = null
 
   // -------------------------------------------------------------------------
   // Lazy BullMQ initialization
@@ -137,10 +153,35 @@ export function createAsyncQueue<T = unknown>(
     return bullmqModule
   }
 
+  /**
+   * When an OTLP backend is active, delegate async-queue tracing to `bullmq-otel`
+   * (richer BullMQ-internal spans: add / process / wait / attempts). Returns
+   * `undefined` — meaning "use our own `metadata._trace` carrier" — when telemetry
+   * is off, a non-OTEL backend is selected, or `bullmq-otel` isn't installed. (The
+   * `local` strategy always uses our carrier; it isn't BullMQ, so `bullmq-otel`
+   * cannot instrument it.)
+   */
+  async function getQueueTelemetry(): Promise<object | undefined> {
+    if (!telemetryPromise) {
+      telemetryPromise = (async () => {
+        if (!getTelemetryRuntime()?.canUseGlobalTracePropagation()) return undefined
+        try {
+          const mod = (await import('bullmq-otel')) as unknown as BullMQOtelModule
+          return new mod.BullMQOtel('open-mercato')
+        } catch {
+          packageLogger.warn('bullmq-otel not available; using built-in trace carrier', { queue: name })
+          return undefined
+        }
+      })()
+    }
+    return telemetryPromise
+  }
+
   async function getQueue(): Promise<BullQueueInterface<QueuedJob<T>>> {
     if (!bullQueue) {
       const { Queue: BullQueueClass } = await getBullMQ()
-      bullQueue = new BullQueueClass<QueuedJob<T>>(name, { connection })
+      const telemetry = await getQueueTelemetry()
+      bullQueue = new BullQueueClass<QueuedJob<T>>(name, { connection, ...(telemetry ? { telemetry } : {}) })
     }
     return bullQueue
   }
@@ -151,10 +192,14 @@ export function createAsyncQueue<T = unknown>(
 
   async function enqueue(data: T, options?: EnqueueOptions): Promise<string> {
     const queue = await getQueue()
+    // When bullmq-otel handles propagation, don't also attach our carrier.
+    const telemetry = await getQueueTelemetry()
+    const metadata = telemetry ? undefined : attachTraceMetadata(undefined)
     const jobData: QueuedJob<T> = {
       id: crypto.randomUUID(),
       payload: data,
       createdAt: new Date().toISOString(),
+      ...(metadata ? { metadata } : {}),
     }
 
     const job = await queue.add(jobData.id, jobData, {
@@ -170,21 +215,31 @@ export function createAsyncQueue<T = unknown>(
 
   async function process(handler: JobHandler<T>): Promise<ProcessResult> {
     const { Worker } = await getBullMQ()
+    const telemetry = await getQueueTelemetry()
 
     // Create worker that processes jobs
     bullWorker = new Worker<QueuedJob<T>>(
       name,
       async (job) => {
         const jobData = job.data
-        await handler(jobData, {
+        const ctx = {
           jobId: job.id ?? jobData.id,
           attemptNumber: job.attemptsMade + 1,
           queueName: name,
-        })
+        }
+        // With bullmq-otel active, BullMQ owns the process span and active
+        // context (the handler's pg/undici spans nest under it). Otherwise
+        // continue the trace from our own carrier.
+        if (telemetry) {
+          await handler(jobData, ctx)
+        } else {
+          await runJobInTrace(name, jobData.metadata, () => handler(jobData, ctx))
+        }
       },
       {
         connection,
         concurrency,
+        ...(telemetry ? { telemetry } : {}),
         ...(lockDuration !== undefined ? { lockDuration } : {}),
         ...(maxStalledCount !== undefined ? { maxStalledCount } : {}),
       }