@open-mercato/queue 0.6.7 → 0.6.8-develop.6875.1.871a4afc94

package/dist/worker/runner.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/worker/runner.ts"],
-  "sourcesContent": ["import { createQueue } from '../factory'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport type { Queue, JobHandler, AsyncQueueOptions, QueueStrategyType } from '../types'\n\nconst logger = createLogger('queue').child({ component: 'worker' })\n\n/**\n * Options for running a queue worker.\n */\nexport type WorkerRunnerOptions<T = unknown> = {\n  /** Name of the queue to process */\n  queueName: string\n  /** Handler function to process each job */\n  handler: JobHandler<T>\n  /** Redis connection options (only used for async strategy) */\n  connection?: AsyncQueueOptions['connection']\n  /** Number of concurrent jobs to process */\n  concurrency?: number\n  /** Whether to set up graceful shutdown handlers */\n  gracefulShutdown?: boolean\n  /** If true, don't block - return immediately after starting processing (for multi-queue mode) */\n  background?: boolean\n  /** Queue strategy to use. Defaults to QUEUE_STRATEGY env var or 'local' */\n  strategy?: QueueStrategyType\n}\n\nconst managedQueues = new Set<Queue<unknown>>()\nconst managedShutdownHooks = new Set<() => Promise<void> | void>()\nlet shutdownHandlersRegistered = false\nlet shutdownInProgress = false\n\nfunction unregisterShutdownHandlers(sigtermHandler: () => void, sigintHandler: () => void): void {\n  process.off('SIGTERM', sigtermHandler)\n  process.off('SIGINT', sigintHandler)\n  shutdownHandlersRegistered = false\n}\n\nfunction registerShutdownHandlers(): void {\n  if (shutdownHandlersRegistered) return\n\n  const shutdown = async (signal: string) => {\n    if (shutdownInProgress) return\n    shutdownInProgress = true\n\n    logger.info('Received signal, shutting down gracefully', { signal })\n\n    let hasError = false\n    for (const queue of managedQueues) {\n      try {\n        await queue.close()\n      } catch (error) {\n        hasError = true\n        logger.error('Error during shutdown', { err: error })\n      }\n    }\n\n    managedQueues.clear()\n    for (const hook of managedShutdownHooks) {\n      try {\n        await hook()\n      } catch (error) {\n        hasError = true\n        logger.error('Error during shutdown hook', { err: error })\n      }\n    }\n    managedShutdownHooks.clear()\n    unregisterShutdownHandlers(sigtermHandler, sigintHandler)\n    shutdownInProgress = false\n\n    if (!hasError) {\n      logger.info('Worker closed successfully')\n    }\n\n    process.exit(hasError ? 1 : 0)\n  }\n\n  const sigtermHandler = () => {\n    void shutdown('SIGTERM')\n  }\n\n  const sigintHandler = () => {\n    void shutdown('SIGINT')\n  }\n\n  process.on('SIGTERM', sigtermHandler)\n  process.on('SIGINT', sigintHandler)\n  shutdownHandlersRegistered = true\n}\n\n/**\n * Register a process-local service that must stop before a worker exits.\n * The returned callback removes the hook when the service is stopped early.\n */\nexport function registerWorkerShutdownHook(hook: () => Promise<void> | void): () => void {\n  managedShutdownHooks.add(hook)\n  return () => managedShutdownHooks.delete(hook)\n}\n\n/**\n * Runs a queue worker that processes jobs continuously.\n *\n * This function:\n * 1. Creates an async queue instance\n * 2. Starts a BullMQ worker\n * 3. Sets up graceful shutdown on SIGTERM/SIGINT\n * 4. Keeps the process running until shutdown\n *\n * @template T - The job payload type\n * @param options - Worker configuration\n *\n * @example\n * ```typescript\n * import { runWorker } from '@open-mercato/queue/worker'\n *\n * await runWorker({\n *   queueName: 'events',\n *   handler: async (job, ctx) => {\n *     console.log(`Processing ${ctx.jobId}:`, job.payload)\n *   },\n *   connection: { url: process.env.REDIS_URL },\n *   concurrency: 5,\n * })\n * ```\n */\nexport async function runWorker<T = unknown>(\n  options: WorkerRunnerOptions<T>\n): Promise<void> {\n  const {\n    queueName,\n    handler,\n    connection,\n    concurrency = 1,\n    gracefulShutdown = true,\n    background = false,\n    strategy: strategyOption,\n  } = options\n\n  // Determine queue strategy from option, env var, or default to 'local'\n  const strategy: QueueStrategyType = strategyOption\n    ?? (process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local')\n\n  logger.info('Starting worker for queue', { queueName, strategy })\n\n  const queue = createQueue<T>(queueName, strategy, {\n    connection,\n    concurrency,\n  })\n\n  // Set up graceful shutdown\n  if (gracefulShutdown) {\n    managedQueues.add(queue as Queue<unknown>)\n    registerShutdownHandlers()\n  }\n\n  // Start processing\n  await queue.process(handler)\n\n  logger.info('Worker running', { concurrency })\n\n  if (background) {\n    // Return immediately for multi-queue mode\n    return\n  }\n\n  logger.info('Press Ctrl+C to stop')\n\n  // Keep the process alive (single-queue mode)\n  await new Promise(() => {\n    // This promise never resolves, keeping the worker running\n  })\n}\n\n/**\n * Creates a worker handler that routes jobs to specific handlers based on job type.\n *\n * @template T - Base job payload type (must include a 'type' field)\n * @param handlers - Map of job types to their handlers\n *\n * @example\n * ```typescript\n * const handler = createRoutedHandler({\n *   'user.created': async (job) => { ... },\n *   'order.placed': async (job) => { ... },\n * })\n *\n * await runWorker({ queueName: 'events', handler })\n * ```\n */\nexport function createRoutedHandler<T extends { type: string }>(\n  handlers: Record<string, JobHandler<T>>\n): JobHandler<T> {\n  return async (job, ctx) => {\n    const type = job.payload.type\n    const handler = handlers[type]\n\n    if (!handler) {\n      logger.warn('No handler registered for job type', { type })\n      return\n    }\n\n    await handler(job, ctx)\n  }\n}\n"],
-  "mappings": "AAAA,SAAS,mBAAmB;AAC5B,SAAS,oBAAoB;AAG7B,MAAM,SAAS,aAAa,OAAO,EAAE,MAAM,EAAE,WAAW,SAAS,CAAC;AAsBlE,MAAM,gBAAgB,oBAAI,IAAoB;AAC9C,MAAM,uBAAuB,oBAAI,IAAgC;AACjE,IAAI,6BAA6B;AACjC,IAAI,qBAAqB;AAEzB,SAAS,2BAA2B,gBAA4B,eAAiC;AAC/F,UAAQ,IAAI,WAAW,cAAc;AACrC,UAAQ,IAAI,UAAU,aAAa;AACnC,+BAA6B;AAC/B;AAEA,SAAS,2BAAiC;AACxC,MAAI,2BAA4B;AAEhC,QAAM,WAAW,OAAO,WAAmB;AACzC,QAAI,mBAAoB;AACxB,yBAAqB;AAErB,WAAO,KAAK,6CAA6C,EAAE,OAAO,CAAC;AAEnE,QAAI,WAAW;AACf,eAAW,SAAS,eAAe;AACjC,UAAI;AACF,cAAM,MAAM,MAAM;AAAA,MACpB,SAAS,OAAO;AACd,mBAAW;AACX,eAAO,MAAM,yBAAyB,EAAE,KAAK,MAAM,CAAC;AAAA,MACtD;AAAA,IACF;AAEA,kBAAc,MAAM;AACpB,eAAW,QAAQ,sBAAsB;AACvC,UAAI;AACF,cAAM,KAAK;AAAA,MACb,SAAS,OAAO;AACd,mBAAW;AACX,eAAO,MAAM,8BAA8B,EAAE,KAAK,MAAM,CAAC;AAAA,MAC3D;AAAA,IACF;AACA,yBAAqB,MAAM;AAC3B,+BAA2B,gBAAgB,aAAa;AACxD,yBAAqB;AAErB,QAAI,CAAC,UAAU;AACb,aAAO,KAAK,4BAA4B;AAAA,IAC1C;AAEA,YAAQ,KAAK,WAAW,IAAI,CAAC;AAAA,EAC/B;AAEA,QAAM,iBAAiB,MAAM;AAC3B,SAAK,SAAS,SAAS;AAAA,EACzB;AAEA,QAAM,gBAAgB,MAAM;AAC1B,SAAK,SAAS,QAAQ;AAAA,EACxB;AAEA,UAAQ,GAAG,WAAW,cAAc;AACpC,UAAQ,GAAG,UAAU,aAAa;AAClC,+BAA6B;AAC/B;AAMO,SAAS,2BAA2B,MAA8C;AACvF,uBAAqB,IAAI,IAAI;AAC7B,SAAO,MAAM,qBAAqB,OAAO,IAAI;AAC/C;AA4BA,eAAsB,UACpB,SACe;AACf,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA,cAAc;AAAA,IACd,mBAAmB;AAAA,IACnB,aAAa;AAAA,IACb,UAAU;AAAA,EACZ,IAAI;AAGJ,QAAM,WAA8B,mBAC9B,QAAQ,IAAI,mBAAmB,UAAU,UAAU;AAEzD,SAAO,KAAK,6BAA6B,EAAE,WAAW,SAAS,CAAC;AAEhE,QAAM,QAAQ,YAAe,WAAW,UAAU;AAAA,IAChD;AAAA,IACA;AAAA,EACF,CAAC;AAGD,MAAI,kBAAkB;AACpB,kBAAc,IAAI,KAAuB;AACzC,6BAAyB;AAAA,EAC3B;AAGA,QAAM,MAAM,QAAQ,OAAO;AAE3B,SAAO,KAAK,kBAAkB,EAAE,YAAY,CAAC;AAE7C,MAAI,YAAY;AAEd;AAAA,EACF;AAEA,SAAO,KAAK,sBAAsB;AAGlC,QAAM,IAAI,QAAQ,MAAM;AAAA,EAExB,CAAC;AACH;AAkBO,SAAS,oBACd,UACe;AACf,SAAO,OAAO,KAAK,QAAQ;AACzB,UAAM,OAAO,IAAI,QAAQ;AACzB,UAAM,UAAU,SAAS,IAAI;AAE7B,QAAI,CAAC,SAAS;AACZ,aAAO,KAAK,sCAAsC,EAAE,KAAK,CAAC;AAC1D;AAAA,IACF;AAEA,UAAM,QAAQ,KAAK,GAAG;AAAA,EACxB;AACF;",
+  "sourcesContent": ["import { createQueue } from '../factory'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport {\n  getTelemetryRuntime,\n  isTelemetryBackendEnabled,\n} from '@open-mercato/shared/lib/telemetry/runtime'\nimport type { Queue, JobHandler, AsyncQueueOptions, QueueStrategyType } from '../types'\n\nconst logger = createLogger('queue').child({ component: 'worker' })\n\n/**\n * Options for running a queue worker.\n */\nexport type WorkerRunnerOptions<T = unknown> = {\n  /** Name of the queue to process */\n  queueName: string\n  /** Handler function to process each job */\n  handler: JobHandler<T>\n  /** Redis connection options (only used for async strategy) */\n  connection?: AsyncQueueOptions['connection']\n  /** Number of concurrent jobs to process */\n  concurrency?: number\n  /** How long a job lock is held before the job counts as stalled, in ms. */\n  lockDuration?: number\n  /** Number of stalled-job recoveries BullMQ permits before failing a job. */\n  maxStalledCount?: number\n  /** Whether to set up graceful shutdown handlers */\n  gracefulShutdown?: boolean\n  /** If true, don't block - return immediately after starting processing (for multi-queue mode) */\n  background?: boolean\n  /** Queue strategy to use. Defaults to QUEUE_STRATEGY env var or 'local' */\n  strategy?: QueueStrategyType\n}\n\nconst managedQueues = new Set<Queue<unknown>>()\nconst managedShutdownHooks = new Set<() => Promise<void> | void>()\nlet shutdownHandlersRegistered = false\nlet shutdownInProgress = false\n\nfunction unregisterShutdownHandlers(sigtermHandler: () => void, sigintHandler: () => void): void {\n  process.off('SIGTERM', sigtermHandler)\n  process.off('SIGINT', sigintHandler)\n  shutdownHandlersRegistered = false\n}\n\nfunction registerShutdownHandlers(): void {\n  if (shutdownHandlersRegistered) return\n\n  const shutdown = async (signal: string) => {\n    if (shutdownInProgress) return\n    shutdownInProgress = true\n\n    logger.info('Received signal, shutting down gracefully', { signal })\n\n    let hasError = false\n    for (const queue of managedQueues) {\n      try {\n        await queue.close()\n      } catch (error) {\n        hasError = true\n        logger.error('Error during shutdown', { err: error })\n      }\n    }\n\n    managedQueues.clear()\n    for (const hook of managedShutdownHooks) {\n      try {\n        await hook()\n      } catch (error) {\n        hasError = true\n        logger.error('Error during shutdown hook', { err: error })\n      }\n    }\n    managedShutdownHooks.clear()\n    unregisterShutdownHandlers(sigtermHandler, sigintHandler)\n    shutdownInProgress = false\n\n    // Flush buffered spans/logs before the process dies. A worker never returns\n    // from run(), so bin.ts's post-run shutdownTelemetry() is unreachable on this\n    // path \u2014 without this, the BatchSpanProcessor's ~5s tail is dropped on every\n    // restart/redeploy. Idempotent and a no-op when telemetry is off; a flush\n    // failure must not turn a clean shutdown into a failed one.\n    try {\n      await getTelemetryRuntime()?.shutdown()\n    } catch (error) {\n      logger.error('Error flushing telemetry during shutdown', { err: error })\n    }\n\n    if (!hasError) {\n      logger.info('Worker closed successfully')\n    }\n\n    process.exit(hasError ? 1 : 0)\n  }\n\n  const sigtermHandler = () => {\n    void shutdown('SIGTERM')\n  }\n\n  const sigintHandler = () => {\n    void shutdown('SIGINT')\n  }\n\n  process.on('SIGTERM', sigtermHandler)\n  process.on('SIGINT', sigintHandler)\n  shutdownHandlersRegistered = true\n}\n\n/**\n * Register a process-local service that must stop before a worker exits.\n * The returned callback removes the hook when the service is stopped early.\n */\nexport function registerWorkerShutdownHook(hook: () => Promise<void> | void): () => void {\n  managedShutdownHooks.add(hook)\n  return () => managedShutdownHooks.delete(hook)\n}\n\n/**\n * Runs a queue worker that processes jobs continuously.\n *\n * This function:\n * 1. Creates an async queue instance\n * 2. Starts a BullMQ worker\n * 3. Sets up graceful shutdown on SIGTERM/SIGINT\n * 4. Keeps the process running until shutdown\n *\n * @template T - The job payload type\n * @param options - Worker configuration\n *\n * @example\n * ```typescript\n * import { runWorker } from '@open-mercato/queue/worker'\n *\n * await runWorker({\n *   queueName: 'events',\n *   handler: async (job, ctx) => {\n *     console.log(`Processing ${ctx.jobId}:`, job.payload)\n *   },\n *   connection: { url: process.env.REDIS_URL },\n *   concurrency: 5,\n * })\n * ```\n */\nexport async function runWorker<T = unknown>(\n  options: WorkerRunnerOptions<T>\n): Promise<void> {\n  const {\n    queueName,\n    handler,\n    connection,\n    concurrency = 1,\n    lockDuration,\n    maxStalledCount,\n    gracefulShutdown = true,\n    background = false,\n    strategy: strategyOption,\n  } = options\n\n  // Worker processes don't run Next's instrumentation hook, so initialize\n  // telemetry here \u2014 this is the single bootstrap every standalone worker passes\n  // through. Import the telemetry package only for an explicit enabled backend;\n  // with the default/unset backend the worker never evaluates the package.\n  if (!getTelemetryRuntime() && isTelemetryBackendEnabled()) {\n    const { initTelemetry } = await import('@open-mercato/telemetry')\n    await initTelemetry()\n  }\n\n  // Determine queue strategy from option, env var, or default to 'local'\n  const strategy: QueueStrategyType = strategyOption\n    ?? (process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local')\n\n  logger.info('Starting worker for queue', { queueName, strategy })\n\n  const queue = createQueue<T>(queueName, strategy, {\n    connection,\n    concurrency,\n    lockDuration,\n    maxStalledCount,\n  })\n\n  // Set up graceful shutdown\n  if (gracefulShutdown) {\n    managedQueues.add(queue as Queue<unknown>)\n    registerShutdownHandlers()\n  }\n\n  // Start processing\n  await queue.process(handler)\n\n  logger.info('Worker running', { concurrency })\n\n  if (background) {\n    // Return immediately for multi-queue mode\n    return\n  }\n\n  logger.info('Press Ctrl+C to stop')\n\n  // Keep the process alive (single-queue mode)\n  await new Promise(() => {\n    // This promise never resolves, keeping the worker running\n  })\n}\n\n/**\n * Creates a worker handler that routes jobs to specific handlers based on job type.\n *\n * @template T - Base job payload type (must include a 'type' field)\n * @param handlers - Map of job types to their handlers\n *\n * @example\n * ```typescript\n * const handler = createRoutedHandler({\n *   'user.created': async (job) => { ... },\n *   'order.placed': async (job) => { ... },\n * })\n *\n * await runWorker({ queueName: 'events', handler })\n * ```\n */\nexport function createRoutedHandler<T extends { type: string }>(\n  handlers: Record<string, JobHandler<T>>\n): JobHandler<T> {\n  return async (job, ctx) => {\n    const type = job.payload.type\n    const handler = handlers[type]\n\n    if (!handler) {\n      logger.warn('No handler registered for job type', { type })\n      return\n    }\n\n    await handler(job, ctx)\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/jest.config.cjs

@@ -26,5 +26,6 @@ module.exports = {
   passWithNoTests: true,
   moduleNameMapper: {
     '^@open-mercato/shared/(.*)$': '<rootDir>/../shared/src/$1',
+    '^@open-mercato/telemetry$': '<rootDir>/../telemetry/src/index.ts',
   },
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/queue",
-  "version": "0.6.7",
+  "version": "0.6.8-develop.6875.1.871a4afc94",
   "license": "MIT",
   "description": "Multi-strategy job queue with local and BullMQ support",
   "type": "module",
@@ -34,29 +34,35 @@
     }
   },
   "peerDependencies": {
-    "bullmq": "^5.0.0"
+    "bullmq": "^5.0.0 || ^6.0.0",
+    "bullmq-otel": "^1.3.0"
   },
   "peerDependenciesMeta": {
     "bullmq": {
       "optional": true
+    },
+    "bullmq-otel": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "@types/node": "^26.0.1",
+    "@types/node": "^26.1.2",
     "jest": "^30.4.2",
-    "ts-jest": "^29.4.11",
+    "ts-jest": "^29.4.12",
     "typescript": "7.0.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@open-mercato/shared": "0.6.7"
+    "@open-mercato/shared": "0.6.8-develop.6875.1.871a4afc94",
+    "@open-mercato/telemetry": "0.6.8-develop.6875.1.871a4afc94"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/open-mercato/open-mercato",
     "directory": "packages/queue"
-  }
+  },
+  "stableVersion": "0.6.7"
 }

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,
+      },
     })
   })
 
@@ -114,6 +139,38 @@ describe('Queue - async strategy', () => {
     await queue.close()
   })
 
+  it('threads queue retry, lock-duration and stalled-job options to BullMQ', async () => {
+    const queue = createQueue<{ value: number }>('test-queue', 'async', {
+      attempts: 5,
+      lockDuration: 120_000,
+      maxStalledCount: 10,
+    })
+
+    await queue.enqueue({ value: 42 })
+    await queue.process(async () => {})
+
+    expect(queueAdd).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({ payload: { value: 42 } }),
+      expect.objectContaining({ attempts: 5 }),
+    )
+    expect(workerCtor).toHaveBeenCalledWith(
+      'test-queue',
+      expect.any(Function),
+      expect.objectContaining({ lockDuration: 120_000, maxStalledCount: 10 }),
+    )
+  })
+
+  it('leaves BullMQ on its own lock and stall defaults when the options are unset', async () => {
+    const queue = createQueue<{ value: number }>('test-queue', 'async', {})
+
+    await queue.process(async () => {})
+
+    const workerOptions = workerCtor.mock.calls[0]?.[2] as Record<string, unknown>
+    expect(workerOptions).not.toHaveProperty('lockDuration')
+    expect(workerOptions).not.toHaveProperty('maxStalledCount')
+  })
+
   it('removeQueuedJobsByScope removes only queued jobs matching tenant scope', async () => {
     const removeMatching = jest.fn(async () => {})
     const removeAutoIndex = jest.fn(async () => {})

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/factory.ts

@@ -82,13 +82,16 @@ export function resolveQueueStrategy(): QueueStrategyType {
  */
 export function createModuleQueue<T = unknown>(
   name: string,
-  options?: { concurrency?: number },
+  options?: Pick<AsyncQueueOptions, 'attempts' | 'concurrency' | 'lockDuration' | 'maxStalledCount'>,
 ): Queue<T> {
   const strategy = resolveQueueStrategy()
   if (strategy === 'async') {
     return createAsyncQueue<T>(name, {
       connection: { url: getRedisUrlOrThrow('QUEUE') },
       concurrency: options?.concurrency,
+      attempts: options?.attempts,
+      lockDuration: options?.lockDuration,
+      maxStalledCount: options?.maxStalledCount,
     })
   }
   return createLocalQueue<T>(name, { concurrency: options?.concurrency })