@open-mercato/queue 0.6.7-develop.6827.1.a575bebce9 → 0.6.7-develop.6834.1.e76f4b8cbc

package/.turbo/turbo-build.log

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

package/dist/strategies/async.js

@@ -1,4 +1,6 @@
 import { getRedisUrlOrThrow } from "@open-mercato/shared/lib/redis/connection";
+import { getTelemetryRuntime } from "@open-mercato/shared/lib/telemetry/runtime";
+import { attachTraceMetadata, runJobInTrace } from "../tracing.js";
 import { createLogger } from "@open-mercato/shared/lib/logger";
 const packageLogger = createLogger("queue");
 const REMOVABLE_JOB_STATES = ["waiting", "delayed", "prioritized", "paused", "waiting-children"];
@@ -40,6 +42,7 @@ function createAsyncQueue(name, options) {
   let bullQueue = null;
   let bullWorker = null;
   let bullmqModule = null;
+  let telemetryPromise = null;
   async function getBullMQ() {
     if (!bullmqModule) {
       try {
@@ -52,19 +55,38 @@ function createAsyncQueue(name, options) {
     }
     return bullmqModule;
   }
+  async function getQueueTelemetry() {
+    if (!telemetryPromise) {
+      telemetryPromise = (async () => {
+        if (!getTelemetryRuntime()?.canUseGlobalTracePropagation()) return void 0;
+        try {
+          const mod = await import("bullmq-otel");
+          return new mod.BullMQOtel("open-mercato");
+        } catch {
+          packageLogger.warn("bullmq-otel not available; using built-in trace carrier", { queue: name });
+          return void 0;
+        }
+      })();
+    }
+    return telemetryPromise;
+  }
   async function getQueue() {
     if (!bullQueue) {
       const { Queue: BullQueueClass } = await getBullMQ();
-      bullQueue = new BullQueueClass(name, { connection });
+      const telemetry = await getQueueTelemetry();
+      bullQueue = new BullQueueClass(name, { connection, ...telemetry ? { telemetry } : {} });
     }
     return bullQueue;
   }
   async function enqueue(data, options2) {
     const queue = await getQueue();
+    const telemetry = await getQueueTelemetry();
+    const metadata = telemetry ? void 0 : attachTraceMetadata(void 0);
     const jobData = {
       id: crypto.randomUUID(),
       payload: data,
-      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...metadata ? { metadata } : {}
     };
     const job = await queue.add(jobData.id, jobData, {
       delay: options2?.delayMs && options2.delayMs > 0 ? options2.delayMs : void 0,
@@ -77,19 +99,26 @@ function createAsyncQueue(name, options) {
   }
   async function process(handler) {
     const { Worker } = await getBullMQ();
+    const telemetry = await getQueueTelemetry();
     bullWorker = new Worker(
       name,
       async (job) => {
         const jobData = job.data;
-        await handler(jobData, {
+        const ctx = {
           jobId: job.id ?? jobData.id,
           attemptNumber: job.attemptsMade + 1,
           queueName: name
-        });
+        };
+        if (telemetry) {
+          await handler(jobData, ctx);
+        } else {
+          await runJobInTrace(name, jobData.metadata, () => handler(jobData, ctx));
+        }
       },
       {
         connection,
         concurrency,
+        ...telemetry ? { telemetry } : {},
         ...lockDuration !== void 0 ? { lockDuration } : {},
         ...maxStalledCount !== void 0 ? { maxStalledCount } : {}
       }

package/dist/strategies/async.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/strategies/async.ts"],
-  "sourcesContent": ["import type { Queue, QueuedJob, JobHandler, AsyncQueueOptions, ProcessResult, EnqueueOptions, QueueJobScope } from '../types'\nimport { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\n\nconst packageLogger = createLogger('queue')\n\n// BullMQ interface types - we define the shape we use to maintain type safety\n// while keeping bullmq as an optional peer dependency\ntype ConnectionOptions = {\n  url?: string\n  host?: string\n  port?: number\n  username?: string\n  password?: string\n  db?: number\n  tls?: Record<string, unknown>\n}\n\ninterface BullQueueInterface<T> {\n  add: (\n    name: string,\n    data: T,\n    opts?: {\n      removeOnComplete?: boolean\n      removeOnFail?: number\n      delay?: number\n      attempts?: number\n      backoff?: { type: string; delay: number }\n    },\n  ) => Promise<{ id?: string }>\n  obliterate: (opts?: { force?: boolean }) => Promise<void>\n  close: () => Promise<void>\n  getJobCounts: (...states: string[]) => Promise<Record<string, number>>\n  getJobs: (types: string[], start?: number, end?: number) => Promise<Array<{\n    data?: T\n    remove: () => Promise<void>\n  }>>\n}\n\ninterface BullWorkerInterface {\n  on: (event: string, handler: (...args: unknown[]) => void) => void\n  close: () => Promise<void>\n}\n\ninterface BullMQModule {\n  Queue: new <T>(name: string, opts: { connection: ConnectionOptions }) => BullQueueInterface<T>\n  Worker: new <T>(\n    name: string,\n    processor: (job: { id?: string; data: T; attemptsMade: number }) => Promise<void>,\n    opts: { connection: ConnectionOptions; concurrency: number; lockDuration?: number; maxStalledCount?: number }\n  ) => BullWorkerInterface\n}\n\nconst REMOVABLE_JOB_STATES = ['waiting', 'delayed', 'prioritized', 'paused', 'waiting-children']\n\nfunction payloadMatchesScope(payload: unknown, scope: QueueJobScope): boolean {\n  if (!payload || typeof payload !== 'object') return false\n  const scopedPayload = payload as { tenantId?: unknown; organizationId?: unknown; jobType?: unknown }\n  if (scopedPayload.tenantId !== scope.tenantId) return false\n  if (scope.organizationId !== undefined) {\n    if ((scopedPayload.organizationId ?? null) !== scope.organizationId) return false\n  }\n  if (scope.jobTypes?.length) {\n    return typeof scopedPayload.jobType === 'string' && scope.jobTypes.includes(scopedPayload.jobType)\n  }\n  return true\n}\n\n/**\n * Resolves Redis connection options from various sources.\n *\n * BullMQ expects an ioredis-compatible connection object. Preserve the full\n * Redis URL under the `url` key so rediss://, username, database, and query\n * params are not lost in translation.\n */\nfunction resolveConnection(options?: AsyncQueueOptions['connection']): ConnectionOptions {\n  if (options?.url) {\n    return { url: options.url }\n  }\n\n  if (options?.host) {\n    return {\n      host: options.host,\n      port: options.port ?? 6379,\n      username: options.username,\n      password: options.password,\n      db: options.db,\n      tls: options.tls,\n    }\n  }\n\n  return { url: getRedisUrlOrThrow('QUEUE') }\n}\n\n/**\n * Creates a BullMQ-based async queue.\n *\n * This strategy provides:\n * - Persistent job storage in Redis\n * - Automatic retries with exponential backoff\n * - Concurrent job processing\n * - Job prioritization and scheduling\n *\n * @template T - The payload type for jobs\n * @param name - Queue name\n * @param options - Async queue options\n */\nexport function createAsyncQueue<T = unknown>(\n  name: string,\n  options?: AsyncQueueOptions\n): Queue<T> {\n  const connection = resolveConnection(options?.connection)\n  const concurrency = options?.concurrency ?? 1\n  const attempts = options?.attempts ?? 3\n  const lockDuration = options?.lockDuration\n  const maxStalledCount = options?.maxStalledCount\n  const logger = packageLogger.child({ queue: name })\n\n  let bullQueue: BullQueueInterface<QueuedJob<T>> | null = null\n  let bullWorker: BullWorkerInterface | null = null\n  let bullmqModule: BullMQModule | null = null\n\n  // -------------------------------------------------------------------------\n  // Lazy BullMQ initialization\n  // -------------------------------------------------------------------------\n\n  async function getBullMQ(): Promise<BullMQModule> {\n    if (!bullmqModule) {\n      try {\n        bullmqModule = await import('bullmq') as unknown as BullMQModule\n      } catch {\n        throw new Error(\n          'BullMQ is required for async queue strategy. Install it with: npm install bullmq'\n        )\n      }\n    }\n    return bullmqModule\n  }\n\n  async function getQueue(): Promise<BullQueueInterface<QueuedJob<T>>> {\n    if (!bullQueue) {\n      const { Queue: BullQueueClass } = await getBullMQ()\n      bullQueue = new BullQueueClass<QueuedJob<T>>(name, { connection })\n    }\n    return bullQueue\n  }\n\n  // -------------------------------------------------------------------------\n  // Queue Implementation\n  // -------------------------------------------------------------------------\n\n  async function enqueue(data: T, options?: EnqueueOptions): Promise<string> {\n    const queue = await getQueue()\n    const jobData: QueuedJob<T> = {\n      id: crypto.randomUUID(),\n      payload: data,\n      createdAt: new Date().toISOString(),\n    }\n\n    const job = await queue.add(jobData.id, jobData, {\n      delay: options?.delayMs && options.delayMs > 0 ? options.delayMs : undefined,\n      removeOnComplete: true,\n      removeOnFail: 1000,\n      attempts,\n      backoff: { type: 'exponential', delay: 1000 },\n    })\n\n    return job.id ?? jobData.id\n  }\n\n  async function process(handler: JobHandler<T>): Promise<ProcessResult> {\n    const { Worker } = await getBullMQ()\n\n    // Create worker that processes jobs\n    bullWorker = new Worker<QueuedJob<T>>(\n      name,\n      async (job) => {\n        const jobData = job.data\n        await handler(jobData, {\n          jobId: job.id ?? jobData.id,\n          attemptNumber: job.attemptsMade + 1,\n          queueName: name,\n        })\n      },\n      {\n        connection,\n        concurrency,\n        ...(lockDuration !== undefined ? { lockDuration } : {}),\n        ...(maxStalledCount !== undefined ? { maxStalledCount } : {}),\n      }\n    )\n\n    // Set up event handlers\n    bullWorker.on('completed', (job) => {\n      const jobWithId = job as { id?: string }\n      logger.info('Job completed', { jobId: jobWithId.id })\n    })\n\n    bullWorker.on('failed', (job, err) => {\n      const jobWithId = job as { id?: string } | undefined\n      const error = err as Error\n      logger.error('Job failed', { jobId: jobWithId?.id, err: error })\n    })\n\n    // A stalled job is redelivered under the same id while the previous worker\n    // may still be running it, so this is the signal that a handler is about to\n    // be executed twice. BullMQ's docs require surfacing it: without this line\n    // duplicate processing is invisible.\n    bullWorker.on('stalled', (jobId) => {\n      logger.warn('Job stalled and will be redelivered \u2014 the handler may run concurrently with a previous delivery', {\n        jobId: typeof jobId === 'string' ? jobId : null,\n      })\n    })\n\n    bullWorker.on('error', (err) => {\n      const error = err as Error\n      logger.error('Worker error', { err: error })\n    })\n\n    logger.info('Worker started', { concurrency })\n\n    // For async strategy, return a sentinel result indicating worker mode\n    // processed=-1 signals that this is a continuous worker, not a batch process\n    return { processed: -1, failed: -1, lastJobId: undefined }\n  }\n\n  async function clear(): Promise<{ removed: number }> {\n    const queue = await getQueue()\n\n    // Obliterate removes all jobs from the queue\n    await queue.obliterate({ force: true })\n\n    return { removed: -1 } // BullMQ obliterate doesn't return count\n  }\n\n  async function removeQueuedJobsByScope(scope: QueueJobScope): Promise<{ removed: number }> {\n    const queue = await getQueue()\n    const jobs = await queue.getJobs(REMOVABLE_JOB_STATES, 0, -1)\n    let removed = 0\n\n    for (const job of jobs) {\n      if (!payloadMatchesScope(job.data?.payload, scope)) continue\n      try {\n        await job.remove()\n        removed++\n      } catch {\n        // The job may have started between enumeration and removal. In-flight\n        // cancellation is handled by the caller's lock/heartbeat contract.\n      }\n    }\n\n    return { removed }\n  }\n\n  async function close(): Promise<void> {\n    if (bullWorker) {\n      await bullWorker.close()\n      bullWorker = null\n    }\n    if (bullQueue) {\n      await bullQueue.close()\n      bullQueue = null\n    }\n  }\n\n  async function getJobCounts(): Promise<{\n    waiting: number\n    active: number\n    completed: number\n    failed: number\n  }> {\n    const queue = await getQueue()\n    const counts = await queue.getJobCounts('waiting', 'active', 'completed', 'failed')\n    return {\n      waiting: counts.waiting ?? 0,\n      active: counts.active ?? 0,\n      completed: counts.completed ?? 0,\n      failed: counts.failed ?? 0,\n    }\n  }\n\n  return {\n    name,\n    strategy: 'async',\n    enqueue,\n    process,\n    clear,\n    removeQueuedJobsByScope,\n    close,\n    getJobCounts,\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import type { Queue, QueuedJob, JobHandler, AsyncQueueOptions, ProcessResult, EnqueueOptions, QueueJobScope } from '../types'\nimport { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'\nimport { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'\nimport { attachTraceMetadata, runJobInTrace } from '../tracing'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\n\nconst packageLogger = createLogger('queue')\n\n// BullMQ interface types - we define the shape we use to maintain type safety\n// while keeping bullmq as an optional peer dependency\ntype ConnectionOptions = {\n  url?: string\n  host?: string\n  port?: number\n  username?: string\n  password?: string\n  db?: number\n  tls?: Record<string, unknown>\n}\n\ninterface BullQueueInterface<T> {\n  add: (\n    name: string,\n    data: T,\n    opts?: {\n      removeOnComplete?: boolean\n      removeOnFail?: number\n      delay?: number\n      attempts?: number\n      backoff?: { type: string; delay: number }\n    },\n  ) => Promise<{ id?: string }>\n  obliterate: (opts?: { force?: boolean }) => Promise<void>\n  close: () => Promise<void>\n  getJobCounts: (...states: string[]) => Promise<Record<string, number>>\n  getJobs: (types: string[], start?: number, end?: number) => Promise<Array<{\n    data?: T\n    remove: () => Promise<void>\n  }>>\n}\n\ninterface BullWorkerInterface {\n  on: (event: string, handler: (...args: unknown[]) => void) => void\n  close: () => Promise<void>\n}\n\ninterface BullMQModule {\n  Queue: new <T>(name: string, opts: { connection: ConnectionOptions; telemetry?: unknown }) => BullQueueInterface<T>\n  Worker: new <T>(\n    name: string,\n    processor: (job: { id?: string; data: T; attemptsMade: number }) => Promise<void>,\n    opts: {\n      connection: ConnectionOptions\n      concurrency: number\n      telemetry?: unknown\n      lockDuration?: number\n      maxStalledCount?: number\n    }\n  ) => BullWorkerInterface\n}\n\n/** The `bullmq-otel` package (optional). Loaded only when an OTLP backend is active. */\ntype BullMQOtelModule = { BullMQOtel: new (tracerName: string) => object }\n\nconst REMOVABLE_JOB_STATES = ['waiting', 'delayed', 'prioritized', 'paused', 'waiting-children']\n\nfunction payloadMatchesScope(payload: unknown, scope: QueueJobScope): boolean {\n  if (!payload || typeof payload !== 'object') return false\n  const scopedPayload = payload as { tenantId?: unknown; organizationId?: unknown; jobType?: unknown }\n  if (scopedPayload.tenantId !== scope.tenantId) return false\n  if (scope.organizationId !== undefined) {\n    if ((scopedPayload.organizationId ?? null) !== scope.organizationId) return false\n  }\n  if (scope.jobTypes?.length) {\n    return typeof scopedPayload.jobType === 'string' && scope.jobTypes.includes(scopedPayload.jobType)\n  }\n  return true\n}\n\n/**\n * Resolves Redis connection options from various sources.\n *\n * BullMQ expects an ioredis-compatible connection object. Preserve the full\n * Redis URL under the `url` key so rediss://, username, database, and query\n * params are not lost in translation.\n */\nfunction resolveConnection(options?: AsyncQueueOptions['connection']): ConnectionOptions {\n  if (options?.url) {\n    return { url: options.url }\n  }\n\n  if (options?.host) {\n    return {\n      host: options.host,\n      port: options.port ?? 6379,\n      username: options.username,\n      password: options.password,\n      db: options.db,\n      tls: options.tls,\n    }\n  }\n\n  return { url: getRedisUrlOrThrow('QUEUE') }\n}\n\n/**\n * Creates a BullMQ-based async queue.\n *\n * This strategy provides:\n * - Persistent job storage in Redis\n * - Automatic retries with exponential backoff\n * - Concurrent job processing\n * - Job prioritization and scheduling\n *\n * @template T - The payload type for jobs\n * @param name - Queue name\n * @param options - Async queue options\n */\nexport function createAsyncQueue<T = unknown>(\n  name: string,\n  options?: AsyncQueueOptions\n): Queue<T> {\n  const connection = resolveConnection(options?.connection)\n  const concurrency = options?.concurrency ?? 1\n  const attempts = options?.attempts ?? 3\n  const lockDuration = options?.lockDuration\n  const maxStalledCount = options?.maxStalledCount\n  const logger = packageLogger.child({ queue: name })\n\n  let bullQueue: BullQueueInterface<QueuedJob<T>> | null = null\n  let bullWorker: BullWorkerInterface | null = null\n  let bullmqModule: BullMQModule | null = null\n  // Resolved once: a BullMQOtel instance (delegate async tracing to BullMQ) or\n  // undefined (use our own metadata._trace carrier instead). Memoized as the\n  // in-flight promise so concurrent first-time callers share one resolution.\n  let telemetryPromise: Promise<object | undefined> | null = null\n\n  // -------------------------------------------------------------------------\n  // Lazy BullMQ initialization\n  // -------------------------------------------------------------------------\n\n  async function getBullMQ(): Promise<BullMQModule> {\n    if (!bullmqModule) {\n      try {\n        bullmqModule = await import('bullmq') as unknown as BullMQModule\n      } catch {\n        throw new Error(\n          'BullMQ is required for async queue strategy. Install it with: npm install bullmq'\n        )\n      }\n    }\n    return bullmqModule\n  }\n\n  /**\n   * When an OTLP backend is active, delegate async-queue tracing to `bullmq-otel`\n   * (richer BullMQ-internal spans: add / process / wait / attempts). Returns\n   * `undefined` \u2014 meaning \"use our own `metadata._trace` carrier\" \u2014 when telemetry\n   * is off, a non-OTEL backend is selected, or `bullmq-otel` isn't installed. (The\n   * `local` strategy always uses our carrier; it isn't BullMQ, so `bullmq-otel`\n   * cannot instrument it.)\n   */\n  async function getQueueTelemetry(): Promise<object | undefined> {\n    if (!telemetryPromise) {\n      telemetryPromise = (async () => {\n        if (!getTelemetryRuntime()?.canUseGlobalTracePropagation()) return undefined\n        try {\n          const mod = (await import('bullmq-otel')) as unknown as BullMQOtelModule\n          return new mod.BullMQOtel('open-mercato')\n        } catch {\n          packageLogger.warn('bullmq-otel not available; using built-in trace carrier', { queue: name })\n          return undefined\n        }\n      })()\n    }\n    return telemetryPromise\n  }\n\n  async function getQueue(): Promise<BullQueueInterface<QueuedJob<T>>> {\n    if (!bullQueue) {\n      const { Queue: BullQueueClass } = await getBullMQ()\n      const telemetry = await getQueueTelemetry()\n      bullQueue = new BullQueueClass<QueuedJob<T>>(name, { connection, ...(telemetry ? { telemetry } : {}) })\n    }\n    return bullQueue\n  }\n\n  // -------------------------------------------------------------------------\n  // Queue Implementation\n  // -------------------------------------------------------------------------\n\n  async function enqueue(data: T, options?: EnqueueOptions): Promise<string> {\n    const queue = await getQueue()\n    // When bullmq-otel handles propagation, don't also attach our carrier.\n    const telemetry = await getQueueTelemetry()\n    const metadata = telemetry ? undefined : attachTraceMetadata(undefined)\n    const jobData: QueuedJob<T> = {\n      id: crypto.randomUUID(),\n      payload: data,\n      createdAt: new Date().toISOString(),\n      ...(metadata ? { metadata } : {}),\n    }\n\n    const job = await queue.add(jobData.id, jobData, {\n      delay: options?.delayMs && options.delayMs > 0 ? options.delayMs : undefined,\n      removeOnComplete: true,\n      removeOnFail: 1000,\n      attempts,\n      backoff: { type: 'exponential', delay: 1000 },\n    })\n\n    return job.id ?? jobData.id\n  }\n\n  async function process(handler: JobHandler<T>): Promise<ProcessResult> {\n    const { Worker } = await getBullMQ()\n    const telemetry = await getQueueTelemetry()\n\n    // Create worker that processes jobs\n    bullWorker = new Worker<QueuedJob<T>>(\n      name,\n      async (job) => {\n        const jobData = job.data\n        const ctx = {\n          jobId: job.id ?? jobData.id,\n          attemptNumber: job.attemptsMade + 1,\n          queueName: name,\n        }\n        // With bullmq-otel active, BullMQ owns the process span and active\n        // context (the handler's pg/undici spans nest under it). Otherwise\n        // continue the trace from our own carrier.\n        if (telemetry) {\n          await handler(jobData, ctx)\n        } else {\n          await runJobInTrace(name, jobData.metadata, () => handler(jobData, ctx))\n        }\n      },\n      {\n        connection,\n        concurrency,\n        ...(telemetry ? { telemetry } : {}),\n        ...(lockDuration !== undefined ? { lockDuration } : {}),\n        ...(maxStalledCount !== undefined ? { maxStalledCount } : {}),\n      }\n    )\n\n    // Set up event handlers\n    bullWorker.on('completed', (job) => {\n      const jobWithId = job as { id?: string }\n      logger.info('Job completed', { jobId: jobWithId.id })\n    })\n\n    bullWorker.on('failed', (job, err) => {\n      const jobWithId = job as { id?: string } | undefined\n      const error = err as Error\n      logger.error('Job failed', { jobId: jobWithId?.id, err: error })\n    })\n\n    // A stalled job is redelivered under the same id while the previous worker\n    // may still be running it, so this is the signal that a handler is about to\n    // be executed twice. BullMQ's docs require surfacing it: without this line\n    // duplicate processing is invisible.\n    bullWorker.on('stalled', (jobId) => {\n      logger.warn('Job stalled and will be redelivered \u2014 the handler may run concurrently with a previous delivery', {\n        jobId: typeof jobId === 'string' ? jobId : null,\n      })\n    })\n\n    bullWorker.on('error', (err) => {\n      const error = err as Error\n      logger.error('Worker error', { err: error })\n    })\n\n    logger.info('Worker started', { concurrency })\n\n    // For async strategy, return a sentinel result indicating worker mode\n    // processed=-1 signals that this is a continuous worker, not a batch process\n    return { processed: -1, failed: -1, lastJobId: undefined }\n  }\n\n  async function clear(): Promise<{ removed: number }> {\n    const queue = await getQueue()\n\n    // Obliterate removes all jobs from the queue\n    await queue.obliterate({ force: true })\n\n    return { removed: -1 } // BullMQ obliterate doesn't return count\n  }\n\n  async function removeQueuedJobsByScope(scope: QueueJobScope): Promise<{ removed: number }> {\n    const queue = await getQueue()\n    const jobs = await queue.getJobs(REMOVABLE_JOB_STATES, 0, -1)\n    let removed = 0\n\n    for (const job of jobs) {\n      if (!payloadMatchesScope(job.data?.payload, scope)) continue\n      try {\n        await job.remove()\n        removed++\n      } catch {\n        // The job may have started between enumeration and removal. In-flight\n        // cancellation is handled by the caller's lock/heartbeat contract.\n      }\n    }\n\n    return { removed }\n  }\n\n  async function close(): Promise<void> {\n    if (bullWorker) {\n      await bullWorker.close()\n      bullWorker = null\n    }\n    if (bullQueue) {\n      await bullQueue.close()\n      bullQueue = null\n    }\n  }\n\n  async function getJobCounts(): Promise<{\n    waiting: number\n    active: number\n    completed: number\n    failed: number\n  }> {\n    const queue = await getQueue()\n    const counts = await queue.getJobCounts('waiting', 'active', 'completed', 'failed')\n    return {\n      waiting: counts.waiting ?? 0,\n      active: counts.active ?? 0,\n      completed: counts.completed ?? 0,\n      failed: counts.failed ?? 0,\n    }\n  }\n\n  return {\n    name,\n    strategy: 'async',\n    enqueue,\n    process,\n    clear,\n    removeQueuedJobsByScope,\n    close,\n    getJobCounts,\n  }\n}\n"],
+  "mappings": "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",
   "names": ["options"]
 }

package/dist/strategies/local.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
 import { createLogger } from "@open-mercato/shared/lib/logger";
+import { attachTraceMetadata, runJobInTrace } from "../tracing.js";
 const packageLogger = createLogger("queue");
 function payloadMatchesScope(payload, scope) {
   if (!payload || typeof payload !== "object") return false;
@@ -118,11 +119,13 @@ function createLocalQueue(name, options) {
   }
   async function enqueue(data, options2) {
     const availableAt = options2?.delayMs && options2.delayMs > 0 ? new Date(Date.now() + options2.delayMs).toISOString() : void 0;
+    const metadata = attachTraceMetadata(void 0);
     const job = {
       id: generateId(),
       payload: data,
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-      ...availableAt ? { availableAt } : {}
+      ...availableAt ? { availableAt } : {},
+      ...metadata ? { metadata } : {}
     };
     await withFileLock(async () => {
       const jobs = await readQueue();
@@ -155,12 +158,16 @@ function createLocalQueue(name, options) {
       for (const job of jobsToProcess) {
         const attemptNumber = (job.attemptCount ?? 0) + 1;
         try {
-          await Promise.resolve(
-            handler(job, {
-              jobId: job.id,
-              attemptNumber,
-              queueName: name
-            })
+          await runJobInTrace(
+            name,
+            job.metadata,
+            () => Promise.resolve(
+              handler(job, {
+                jobId: job.id,
+                attemptNumber,
+                queueName: name
+              })
+            )
           );
           processed++;
           lastJobId = job.id;

package/dist/strategies/local.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/strategies/local.ts"],
-  "sourcesContent": ["import fs from 'node:fs'\nimport path from 'node:path'\nimport crypto from 'node:crypto'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport type { Queue, QueuedJob, JobHandler, LocalQueueOptions, ProcessOptions, ProcessResult, EnqueueOptions, QueueJobScope } from '../types'\n\nconst packageLogger = createLogger('queue')\n\ntype LocalState = {\n  lastProcessedId?: string\n  completedCount?: number\n  failedCount?: number\n}\n\ntype StoredJob<T> = QueuedJob<T> & {\n  availableAt?: string\n  attemptCount?: number\n}\n\nfunction payloadMatchesScope(payload: unknown, scope: QueueJobScope): boolean {\n  if (!payload || typeof payload !== 'object') return false\n  const scopedPayload = payload as { tenantId?: unknown; organizationId?: unknown; jobType?: unknown }\n  if (scopedPayload.tenantId !== scope.tenantId) return false\n  if (scope.organizationId !== undefined) {\n    if ((scopedPayload.organizationId ?? null) !== scope.organizationId) return false\n  }\n  if (scope.jobTypes?.length) {\n    return typeof scopedPayload.jobType === 'string' && scope.jobTypes.includes(scopedPayload.jobType)\n  }\n  return true\n}\n\n/** Default polling interval in milliseconds */\nconst DEFAULT_POLL_INTERVAL = 1000\nconst DEFAULT_LOCAL_QUEUE_BASE_DIR = '.mercato/queue'\nconst DEFAULT_MAX_ATTEMPTS = 3\nconst RETRY_BACKOFF_BASE_MS = 1000\n\nconst fsp = fs.promises\n\n/**\n * Creates a file-based local queue.\n *\n * Jobs are stored in JSON files within a directory structure:\n * - `.mercato/queue/<name>/queue.json` - Array of queued jobs\n * - `.mercato/queue/<name>/state.json` - Processing state (last processed ID)\n *\n * **Limitations:**\n * - Jobs are processed sequentially (concurrency option is for logging/compatibility only)\n * - Not suitable for production or multi-process environments\n *\n * Failed jobs are retried up to `DEFAULT_MAX_ATTEMPTS` times with exponential backoff.\n * **This strategy keeps no failed-job store**: once attempts are exhausted the job is\n * removed from `queue.json` and only counted in `state.failedCount`, so the payload is\n * lost and the failure survives solely as an error log line. The `async` strategy keeps\n * only a bounded inspection window: `removeOnFail: 1000` retains the most recent 1000\n * failures and removes older ones as later failures arrive. Workflows that require\n * no-loss persistence must write their own durable record before enqueueing, regardless\n * of strategy.\n *\n * `DEFAULT_MAX_ATTEMPTS` is a module constant, not a per-job option \u2014 callers cannot\n * request a different attempt count. (`async` likewise hard-codes `attempts: 3`.)\n * See the retry handling in `process()` below.\n *\n * All file I/O is asynchronous (`fs.promises.*`) so queue operations do not\n * block the Node.js event loop. A per-queue promise chain serializes\n * read-modify-write sequences to preserve the atomicity guarantees the\n * previous synchronous implementation relied on.\n *\n * @template T - The payload type for jobs\n * @param name - Queue name (used for directory naming)\n * @param options - Local queue options\n */\nexport function createLocalQueue<T = unknown>(\n  name: string,\n  options?: LocalQueueOptions\n): Queue<T> {\n  const nodeProcess = (globalThis as typeof globalThis & { process?: NodeJS.Process }).process\n  const queueBaseDirFromEnv = nodeProcess?.env?.QUEUE_BASE_DIR\n  const baseDir = options?.baseDir\n    ?? path.resolve(queueBaseDirFromEnv || DEFAULT_LOCAL_QUEUE_BASE_DIR)\n  const queueDir = path.join(baseDir, name)\n  const queueFile = path.join(queueDir, 'queue.json')\n  const stateFile = path.join(queueDir, 'state.json')\n  const logger = packageLogger.child({ queue: name })\n  // Note: concurrency is stored for logging/compatibility but jobs are processed sequentially\n  const concurrency = options?.concurrency ?? 1\n  const pollInterval = options?.pollInterval ?? DEFAULT_POLL_INTERVAL\n\n  // Worker state for continuous polling\n  let pollingTimer: ReturnType<typeof setInterval> | null = null\n  let isProcessing = false\n  let activeHandler: JobHandler<T> | null = null\n  const inFlightJobIds = new Set<string>()\n\n  // Per-queue mutex. Serializes read-modify-write segments so async fs calls\n  // cannot interleave and clobber each other's writes.\n  let fileOpChain: Promise<unknown> = Promise.resolve()\n  function withFileLock<R>(fn: () => Promise<R>): Promise<R> {\n    const run = fileOpChain.then(() => fn(), () => fn())\n    fileOpChain = run.then(\n      () => undefined,\n      () => undefined,\n    )\n    return run\n  }\n\n  // -------------------------------------------------------------------------\n  // File Operations\n  // -------------------------------------------------------------------------\n\n  async function ensureDir(): Promise<void> {\n    try {\n      await fsp.mkdir(queueDir, { recursive: true })\n    } catch (e: unknown) {\n      const error = e as NodeJS.ErrnoException\n      if (error.code !== 'EEXIST') throw error\n    }\n\n    // Initialize queue file with exclusive create flag\n    try {\n      await fsp.writeFile(queueFile, '[]', { encoding: 'utf8', flag: 'wx' })\n    } catch (e: unknown) {\n      const error = e as NodeJS.ErrnoException\n      if (error.code !== 'EEXIST') throw error\n    }\n\n    // Initialize state file with exclusive create flag\n    try {\n      await fsp.writeFile(stateFile, '{}', { encoding: 'utf8', flag: 'wx' })\n    } catch (e: unknown) {\n      const error = e as NodeJS.ErrnoException\n      if (error.code !== 'EEXIST') throw error\n    }\n  }\n\n  async function backupCorruptedQueueFile(content: string): Promise<string> {\n    const backupFile = path.join(queueDir, `queue.corrupted.${Date.now()}.json`)\n    await fsp.writeFile(backupFile, content, 'utf8')\n    await fsp.writeFile(queueFile, '[]', 'utf8')\n    return backupFile\n  }\n\n  async function readQueue(): Promise<StoredJob<T>[]> {\n    await ensureDir()\n    let content: string\n\n    try {\n      content = await fsp.readFile(queueFile, 'utf8')\n    } catch (error: unknown) {\n      const readError = error as NodeJS.ErrnoException\n      if (readError.code === 'ENOENT') {\n        return []\n      }\n      logger.error('Failed to read queue file', { err: readError })\n      throw new Error(`Queue file unreadable: ${readError.message}`)\n    }\n\n    try {\n      const parsed = JSON.parse(content) as unknown\n\n      if (!Array.isArray(parsed)) {\n        throw new Error('Queue file must contain a JSON array')\n      }\n\n      return parsed as StoredJob<T>[]\n    } catch (error: unknown) {\n      const parseError = error as Error\n      logger.error('Failed to parse queue file', { err: parseError })\n      const backupFile = await backupCorruptedQueueFile(content)\n      logger.error('Backed up corrupted queue file and recreated queue.json', { backupFile })\n      return []\n    }\n  }\n\n  async function writeQueue(jobs: StoredJob<T>[]): Promise<void> {\n    await ensureDir()\n    await fsp.writeFile(queueFile, JSON.stringify(jobs, null, 2), 'utf8')\n  }\n\n  async function readState(): Promise<LocalState> {\n    await ensureDir()\n    try {\n      const content = await fsp.readFile(stateFile, 'utf8')\n      return JSON.parse(content) as LocalState\n    } catch {\n      return {}\n    }\n  }\n\n  async function writeState(state: LocalState): Promise<void> {\n    await ensureDir()\n    await fsp.writeFile(stateFile, JSON.stringify(state, null, 2), 'utf8')\n  }\n\n  function generateId(): string {\n    return crypto.randomUUID()\n  }\n\n  // -------------------------------------------------------------------------\n  // Queue Implementation\n  // -------------------------------------------------------------------------\n\n  async function enqueue(data: T, options?: EnqueueOptions): Promise<string> {\n    const availableAt = options?.delayMs && options.delayMs > 0\n      ? new Date(Date.now() + options.delayMs).toISOString()\n      : undefined\n    const job: StoredJob<T> = {\n      id: generateId(),\n      payload: data,\n      createdAt: new Date().toISOString(),\n      ...(availableAt ? { availableAt } : {}),\n    }\n    await withFileLock(async () => {\n      const jobs = await readQueue()\n      jobs.push(job)\n      await writeQueue(jobs)\n    })\n    return job.id\n  }\n\n  /**\n   * Process pending jobs in a single batch (internal helper).\n   */\n  async function processBatch(\n    handler: JobHandler<T>,\n    options?: ProcessOptions\n  ): Promise<ProcessResult> {\n    const { state, jobs } = await withFileLock(async () => {\n      const stateRead = await readState()\n      const jobsRead = await readQueue()\n      return { state: stateRead, jobs: jobsRead }\n    })\n\n    const pendingJobs = jobs.filter((job) => {\n      if (!job.availableAt) return true\n      return new Date(job.availableAt).getTime() <= Date.now()\n    })\n    const jobsToProcess = options?.limit\n      ? pendingJobs.slice(0, options.limit)\n      : pendingJobs\n\n    for (const job of jobsToProcess) {\n      inFlightJobIds.add(job.id)\n    }\n\n    let processed = 0\n    let failed = 0\n    let lastJobId: string | undefined\n    const completedJobIds = new Set<string>()\n    const deadJobIds = new Set<string>()\n    const retryUpdates = new Map<string, StoredJob<T>>()\n\n    try {\n      for (const job of jobsToProcess) {\n        const attemptNumber = (job.attemptCount ?? 0) + 1\n        try {\n          await Promise.resolve(\n            handler(job, {\n              jobId: job.id,\n              attemptNumber,\n              queueName: name,\n            })\n          )\n          processed++\n          lastJobId = job.id\n          completedJobIds.add(job.id)\n          logger.info('Job completed', { jobId: job.id })\n        } catch (error) {\n          logger.error('Job failed', { jobId: job.id, attemptNumber, maxAttempts: DEFAULT_MAX_ATTEMPTS, err: error })\n          failed++\n          lastJobId = job.id\n          if (attemptNumber >= DEFAULT_MAX_ATTEMPTS) {\n            logger.error('Job exhausted all attempts; dropping it (no dead-letter store)', { jobId: job.id, maxAttempts: DEFAULT_MAX_ATTEMPTS })\n            deadJobIds.add(job.id)\n          } else {\n            const backoffMs = RETRY_BACKOFF_BASE_MS * Math.pow(2, attemptNumber - 1)\n            retryUpdates.set(job.id, {\n              ...job,\n              attemptCount: attemptNumber,\n              availableAt: new Date(Date.now() + backoffMs).toISOString(),\n            })\n          }\n        }\n      }\n\n      const hasChanges = completedJobIds.size > 0 || deadJobIds.size > 0 || retryUpdates.size > 0\n      if (hasChanges) {\n        await withFileLock(async () => {\n          // Re-read so jobs enqueued during handler execution are preserved.\n          const currentJobs = await readQueue()\n          const updatedJobs = currentJobs\n            .filter((j) => !completedJobIds.has(j.id) && !deadJobIds.has(j.id))\n            .map((j) => retryUpdates.get(j.id) ?? j)\n          await writeQueue(updatedJobs)\n\n          const newState: LocalState = {\n            lastProcessedId: lastJobId,\n            completedCount: (state.completedCount ?? 0) + processed,\n            failedCount: (state.failedCount ?? 0) + deadJobIds.size,\n          }\n          await writeState(newState)\n        })\n      }\n\n      return { processed, failed, lastJobId }\n    } finally {\n      for (const job of jobsToProcess) {\n        inFlightJobIds.delete(job.id)\n      }\n    }\n  }\n\n  /**\n   * Poll for and process new jobs.\n   */\n  async function pollAndProcess(): Promise<void> {\n    // Skip if already processing to avoid concurrent file access\n    if (isProcessing || !activeHandler) return\n\n    isProcessing = true\n    try {\n      await processBatch(activeHandler)\n    } catch (error) {\n      logger.error('Polling error', { err: error })\n    } finally {\n      isProcessing = false\n    }\n  }\n\n  async function process(\n    handler: JobHandler<T>,\n    options?: ProcessOptions\n  ): Promise<ProcessResult> {\n    // If limit is specified, do a single batch (backward compatibility)\n    if (options?.limit) {\n      return processBatch(handler, options)\n    }\n\n    // Start continuous polling mode (like BullMQ Worker)\n    activeHandler = handler\n\n    // Process any pending jobs immediately\n    await processBatch(handler)\n\n    // Start polling interval for new jobs\n    pollingTimer = setInterval(() => {\n      pollAndProcess().catch((err) => {\n        logger.error('Poll cycle error', { err })\n      })\n    }, pollInterval)\n\n    logger.info('Worker started', { concurrency })\n\n    // Return sentinel value indicating continuous worker mode (like async strategy)\n    return { processed: -1, failed: -1, lastJobId: undefined }\n  }\n\n  async function clear(): Promise<{ removed: number }> {\n    return withFileLock(async () => {\n      const jobs = await readQueue()\n      const removed = jobs.length\n      await writeQueue([])\n      // Reset state but preserve counts for historical tracking\n      const state = await readState()\n      await writeState({\n        completedCount: state.completedCount,\n        failedCount: state.failedCount,\n      })\n      return { removed }\n    })\n  }\n\n  async function removeQueuedJobsByScope(scope: QueueJobScope): Promise<{ removed: number }> {\n    return withFileLock(async () => {\n      const jobs = await readQueue()\n      const retainedJobs = jobs.filter((job) => inFlightJobIds.has(job.id) || !payloadMatchesScope(job.payload, scope))\n      const removed = jobs.length - retainedJobs.length\n      if (removed > 0) {\n        await writeQueue(retainedJobs)\n      }\n      return { removed }\n    })\n  }\n\n  async function close(): Promise<void> {\n    // Stop polling timer\n    if (pollingTimer) {\n      clearInterval(pollingTimer)\n      pollingTimer = null\n    }\n    activeHandler = null\n\n    // Wait for any in-progress processing to complete (with timeout)\n    const SHUTDOWN_TIMEOUT = 5000\n    const startTime = Date.now()\n\n    while (isProcessing) {\n      if (Date.now() - startTime > SHUTDOWN_TIMEOUT) {\n        logger.warn('Force closing after shutdown timeout', { timeoutMs: SHUTDOWN_TIMEOUT })\n        break\n      }\n      await new Promise((resolve) => setTimeout(resolve, 50))\n    }\n  }\n\n  async function getJobCounts(): Promise<{\n    waiting: number\n    active: number\n    completed: number\n    failed: number\n  }> {\n    return withFileLock(async () => {\n      const state = await readState()\n      const jobs = await readQueue()\n\n      return {\n        waiting: jobs.length, // All jobs in queue are waiting (processed ones are removed)\n        active: 0, // Local strategy doesn't track active jobs\n        completed: state.completedCount ?? 0,\n        failed: state.failedCount ?? 0,\n      }\n    })\n  }\n\n  return {\n    name,\n    strategy: 'local',\n    enqueue,\n    process,\n    clear,\n    removeQueuedJobsByScope,\n    close,\n    getJobCounts,\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import fs from 'node:fs'\nimport path from 'node:path'\nimport crypto from 'node:crypto'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport type { Queue, QueuedJob, JobHandler, LocalQueueOptions, ProcessOptions, ProcessResult, EnqueueOptions, QueueJobScope } from '../types'\nimport { attachTraceMetadata, runJobInTrace } from '../tracing'\n\nconst packageLogger = createLogger('queue')\n\ntype LocalState = {\n  lastProcessedId?: string\n  completedCount?: number\n  failedCount?: number\n}\n\ntype StoredJob<T> = QueuedJob<T> & {\n  availableAt?: string\n  attemptCount?: number\n}\n\nfunction payloadMatchesScope(payload: unknown, scope: QueueJobScope): boolean {\n  if (!payload || typeof payload !== 'object') return false\n  const scopedPayload = payload as { tenantId?: unknown; organizationId?: unknown; jobType?: unknown }\n  if (scopedPayload.tenantId !== scope.tenantId) return false\n  if (scope.organizationId !== undefined) {\n    if ((scopedPayload.organizationId ?? null) !== scope.organizationId) return false\n  }\n  if (scope.jobTypes?.length) {\n    return typeof scopedPayload.jobType === 'string' && scope.jobTypes.includes(scopedPayload.jobType)\n  }\n  return true\n}\n\n/** Default polling interval in milliseconds */\nconst DEFAULT_POLL_INTERVAL = 1000\nconst DEFAULT_LOCAL_QUEUE_BASE_DIR = '.mercato/queue'\nconst DEFAULT_MAX_ATTEMPTS = 3\nconst RETRY_BACKOFF_BASE_MS = 1000\n\nconst fsp = fs.promises\n\n/**\n * Creates a file-based local queue.\n *\n * Jobs are stored in JSON files within a directory structure:\n * - `.mercato/queue/<name>/queue.json` - Array of queued jobs\n * - `.mercato/queue/<name>/state.json` - Processing state (last processed ID)\n *\n * **Limitations:**\n * - Jobs are processed sequentially (concurrency option is for logging/compatibility only)\n * - Not suitable for production or multi-process environments\n *\n * Failed jobs are retried up to `DEFAULT_MAX_ATTEMPTS` times with exponential backoff.\n * **This strategy keeps no failed-job store**: once attempts are exhausted the job is\n * removed from `queue.json` and only counted in `state.failedCount`, so the payload is\n * lost and the failure survives solely as an error log line. The `async` strategy keeps\n * only a bounded inspection window: `removeOnFail: 1000` retains the most recent 1000\n * failures and removes older ones as later failures arrive. Workflows that require\n * no-loss persistence must write their own durable record before enqueueing, regardless\n * of strategy.\n *\n * `DEFAULT_MAX_ATTEMPTS` is a module constant, not a per-job option \u2014 callers cannot\n * request a different attempt count. (`async` likewise hard-codes `attempts: 3`.)\n * See the retry handling in `process()` below.\n *\n * All file I/O is asynchronous (`fs.promises.*`) so queue operations do not\n * block the Node.js event loop. A per-queue promise chain serializes\n * read-modify-write sequences to preserve the atomicity guarantees the\n * previous synchronous implementation relied on.\n *\n * @template T - The payload type for jobs\n * @param name - Queue name (used for directory naming)\n * @param options - Local queue options\n */\nexport function createLocalQueue<T = unknown>(\n  name: string,\n  options?: LocalQueueOptions\n): Queue<T> {\n  const nodeProcess = (globalThis as typeof globalThis & { process?: NodeJS.Process }).process\n  const queueBaseDirFromEnv = nodeProcess?.env?.QUEUE_BASE_DIR\n  const baseDir = options?.baseDir\n    ?? path.resolve(queueBaseDirFromEnv || DEFAULT_LOCAL_QUEUE_BASE_DIR)\n  const queueDir = path.join(baseDir, name)\n  const queueFile = path.join(queueDir, 'queue.json')\n  const stateFile = path.join(queueDir, 'state.json')\n  const logger = packageLogger.child({ queue: name })\n  // Note: concurrency is stored for logging/compatibility but jobs are processed sequentially\n  const concurrency = options?.concurrency ?? 1\n  const pollInterval = options?.pollInterval ?? DEFAULT_POLL_INTERVAL\n\n  // Worker state for continuous polling\n  let pollingTimer: ReturnType<typeof setInterval> | null = null\n  let isProcessing = false\n  let activeHandler: JobHandler<T> | null = null\n  const inFlightJobIds = new Set<string>()\n\n  // Per-queue mutex. Serializes read-modify-write segments so async fs calls\n  // cannot interleave and clobber each other's writes.\n  let fileOpChain: Promise<unknown> = Promise.resolve()\n  function withFileLock<R>(fn: () => Promise<R>): Promise<R> {\n    const run = fileOpChain.then(() => fn(), () => fn())\n    fileOpChain = run.then(\n      () => undefined,\n      () => undefined,\n    )\n    return run\n  }\n\n  // -------------------------------------------------------------------------\n  // File Operations\n  // -------------------------------------------------------------------------\n\n  async function ensureDir(): Promise<void> {\n    try {\n      await fsp.mkdir(queueDir, { recursive: true })\n    } catch (e: unknown) {\n      const error = e as NodeJS.ErrnoException\n      if (error.code !== 'EEXIST') throw error\n    }\n\n    // Initialize queue file with exclusive create flag\n    try {\n      await fsp.writeFile(queueFile, '[]', { encoding: 'utf8', flag: 'wx' })\n    } catch (e: unknown) {\n      const error = e as NodeJS.ErrnoException\n      if (error.code !== 'EEXIST') throw error\n    }\n\n    // Initialize state file with exclusive create flag\n    try {\n      await fsp.writeFile(stateFile, '{}', { encoding: 'utf8', flag: 'wx' })\n    } catch (e: unknown) {\n      const error = e as NodeJS.ErrnoException\n      if (error.code !== 'EEXIST') throw error\n    }\n  }\n\n  async function backupCorruptedQueueFile(content: string): Promise<string> {\n    const backupFile = path.join(queueDir, `queue.corrupted.${Date.now()}.json`)\n    await fsp.writeFile(backupFile, content, 'utf8')\n    await fsp.writeFile(queueFile, '[]', 'utf8')\n    return backupFile\n  }\n\n  async function readQueue(): Promise<StoredJob<T>[]> {\n    await ensureDir()\n    let content: string\n\n    try {\n      content = await fsp.readFile(queueFile, 'utf8')\n    } catch (error: unknown) {\n      const readError = error as NodeJS.ErrnoException\n      if (readError.code === 'ENOENT') {\n        return []\n      }\n      logger.error('Failed to read queue file', { err: readError })\n      throw new Error(`Queue file unreadable: ${readError.message}`)\n    }\n\n    try {\n      const parsed = JSON.parse(content) as unknown\n\n      if (!Array.isArray(parsed)) {\n        throw new Error('Queue file must contain a JSON array')\n      }\n\n      return parsed as StoredJob<T>[]\n    } catch (error: unknown) {\n      const parseError = error as Error\n      logger.error('Failed to parse queue file', { err: parseError })\n      const backupFile = await backupCorruptedQueueFile(content)\n      logger.error('Backed up corrupted queue file and recreated queue.json', { backupFile })\n      return []\n    }\n  }\n\n  async function writeQueue(jobs: StoredJob<T>[]): Promise<void> {\n    await ensureDir()\n    await fsp.writeFile(queueFile, JSON.stringify(jobs, null, 2), 'utf8')\n  }\n\n  async function readState(): Promise<LocalState> {\n    await ensureDir()\n    try {\n      const content = await fsp.readFile(stateFile, 'utf8')\n      return JSON.parse(content) as LocalState\n    } catch {\n      return {}\n    }\n  }\n\n  async function writeState(state: LocalState): Promise<void> {\n    await ensureDir()\n    await fsp.writeFile(stateFile, JSON.stringify(state, null, 2), 'utf8')\n  }\n\n  function generateId(): string {\n    return crypto.randomUUID()\n  }\n\n  // -------------------------------------------------------------------------\n  // Queue Implementation\n  // -------------------------------------------------------------------------\n\n  async function enqueue(data: T, options?: EnqueueOptions): Promise<string> {\n    const availableAt = options?.delayMs && options.delayMs > 0\n      ? new Date(Date.now() + options.delayMs).toISOString()\n      : undefined\n    const metadata = attachTraceMetadata(undefined)\n    const job: StoredJob<T> = {\n      id: generateId(),\n      payload: data,\n      createdAt: new Date().toISOString(),\n      ...(availableAt ? { availableAt } : {}),\n      ...(metadata ? { metadata } : {}),\n    }\n    await withFileLock(async () => {\n      const jobs = await readQueue()\n      jobs.push(job)\n      await writeQueue(jobs)\n    })\n    return job.id\n  }\n\n  /**\n   * Process pending jobs in a single batch (internal helper).\n   */\n  async function processBatch(\n    handler: JobHandler<T>,\n    options?: ProcessOptions\n  ): Promise<ProcessResult> {\n    const { state, jobs } = await withFileLock(async () => {\n      const stateRead = await readState()\n      const jobsRead = await readQueue()\n      return { state: stateRead, jobs: jobsRead }\n    })\n\n    const pendingJobs = jobs.filter((job) => {\n      if (!job.availableAt) return true\n      return new Date(job.availableAt).getTime() <= Date.now()\n    })\n    const jobsToProcess = options?.limit\n      ? pendingJobs.slice(0, options.limit)\n      : pendingJobs\n\n    for (const job of jobsToProcess) {\n      inFlightJobIds.add(job.id)\n    }\n\n    let processed = 0\n    let failed = 0\n    let lastJobId: string | undefined\n    const completedJobIds = new Set<string>()\n    const deadJobIds = new Set<string>()\n    const retryUpdates = new Map<string, StoredJob<T>>()\n\n    try {\n      for (const job of jobsToProcess) {\n        const attemptNumber = (job.attemptCount ?? 0) + 1\n        try {\n          await runJobInTrace(name, job.metadata, () =>\n            Promise.resolve(\n              handler(job, {\n                jobId: job.id,\n                attemptNumber,\n                queueName: name,\n              })\n            )\n          )\n          processed++\n          lastJobId = job.id\n          completedJobIds.add(job.id)\n          logger.info('Job completed', { jobId: job.id })\n        } catch (error) {\n          logger.error('Job failed', { jobId: job.id, attemptNumber, maxAttempts: DEFAULT_MAX_ATTEMPTS, err: error })\n          failed++\n          lastJobId = job.id\n          if (attemptNumber >= DEFAULT_MAX_ATTEMPTS) {\n            logger.error('Job exhausted all attempts; dropping it (no dead-letter store)', { jobId: job.id, maxAttempts: DEFAULT_MAX_ATTEMPTS })\n            deadJobIds.add(job.id)\n          } else {\n            const backoffMs = RETRY_BACKOFF_BASE_MS * Math.pow(2, attemptNumber - 1)\n            retryUpdates.set(job.id, {\n              ...job,\n              attemptCount: attemptNumber,\n              availableAt: new Date(Date.now() + backoffMs).toISOString(),\n            })\n          }\n        }\n      }\n\n      const hasChanges = completedJobIds.size > 0 || deadJobIds.size > 0 || retryUpdates.size > 0\n      if (hasChanges) {\n        await withFileLock(async () => {\n          // Re-read so jobs enqueued during handler execution are preserved.\n          const currentJobs = await readQueue()\n          const updatedJobs = currentJobs\n            .filter((j) => !completedJobIds.has(j.id) && !deadJobIds.has(j.id))\n            .map((j) => retryUpdates.get(j.id) ?? j)\n          await writeQueue(updatedJobs)\n\n          const newState: LocalState = {\n            lastProcessedId: lastJobId,\n            completedCount: (state.completedCount ?? 0) + processed,\n            failedCount: (state.failedCount ?? 0) + deadJobIds.size,\n          }\n          await writeState(newState)\n        })\n      }\n\n      return { processed, failed, lastJobId }\n    } finally {\n      for (const job of jobsToProcess) {\n        inFlightJobIds.delete(job.id)\n      }\n    }\n  }\n\n  /**\n   * Poll for and process new jobs.\n   */\n  async function pollAndProcess(): Promise<void> {\n    // Skip if already processing to avoid concurrent file access\n    if (isProcessing || !activeHandler) return\n\n    isProcessing = true\n    try {\n      await processBatch(activeHandler)\n    } catch (error) {\n      logger.error('Polling error', { err: error })\n    } finally {\n      isProcessing = false\n    }\n  }\n\n  async function process(\n    handler: JobHandler<T>,\n    options?: ProcessOptions\n  ): Promise<ProcessResult> {\n    // If limit is specified, do a single batch (backward compatibility)\n    if (options?.limit) {\n      return processBatch(handler, options)\n    }\n\n    // Start continuous polling mode (like BullMQ Worker)\n    activeHandler = handler\n\n    // Process any pending jobs immediately\n    await processBatch(handler)\n\n    // Start polling interval for new jobs\n    pollingTimer = setInterval(() => {\n      pollAndProcess().catch((err) => {\n        logger.error('Poll cycle error', { err })\n      })\n    }, pollInterval)\n\n    logger.info('Worker started', { concurrency })\n\n    // Return sentinel value indicating continuous worker mode (like async strategy)\n    return { processed: -1, failed: -1, lastJobId: undefined }\n  }\n\n  async function clear(): Promise<{ removed: number }> {\n    return withFileLock(async () => {\n      const jobs = await readQueue()\n      const removed = jobs.length\n      await writeQueue([])\n      // Reset state but preserve counts for historical tracking\n      const state = await readState()\n      await writeState({\n        completedCount: state.completedCount,\n        failedCount: state.failedCount,\n      })\n      return { removed }\n    })\n  }\n\n  async function removeQueuedJobsByScope(scope: QueueJobScope): Promise<{ removed: number }> {\n    return withFileLock(async () => {\n      const jobs = await readQueue()\n      const retainedJobs = jobs.filter((job) => inFlightJobIds.has(job.id) || !payloadMatchesScope(job.payload, scope))\n      const removed = jobs.length - retainedJobs.length\n      if (removed > 0) {\n        await writeQueue(retainedJobs)\n      }\n      return { removed }\n    })\n  }\n\n  async function close(): Promise<void> {\n    // Stop polling timer\n    if (pollingTimer) {\n      clearInterval(pollingTimer)\n      pollingTimer = null\n    }\n    activeHandler = null\n\n    // Wait for any in-progress processing to complete (with timeout)\n    const SHUTDOWN_TIMEOUT = 5000\n    const startTime = Date.now()\n\n    while (isProcessing) {\n      if (Date.now() - startTime > SHUTDOWN_TIMEOUT) {\n        logger.warn('Force closing after shutdown timeout', { timeoutMs: SHUTDOWN_TIMEOUT })\n        break\n      }\n      await new Promise((resolve) => setTimeout(resolve, 50))\n    }\n  }\n\n  async function getJobCounts(): Promise<{\n    waiting: number\n    active: number\n    completed: number\n    failed: number\n  }> {\n    return withFileLock(async () => {\n      const state = await readState()\n      const jobs = await readQueue()\n\n      return {\n        waiting: jobs.length, // All jobs in queue are waiting (processed ones are removed)\n        active: 0, // Local strategy doesn't track active jobs\n        completed: state.completedCount ?? 0,\n        failed: state.failedCount ?? 0,\n      }\n    })\n  }\n\n  return {\n    name,\n    strategy: 'local',\n    enqueue,\n    process,\n    clear,\n    removeQueuedJobsByScope,\n    close,\n    getJobCounts,\n  }\n}\n"],
+  "mappings": "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",
   "names": ["options"]
 }

package/dist/tracing.js

@@ -0,0 +1,27 @@
+import { getTelemetryRuntime } from "@open-mercato/shared/lib/telemetry/runtime";
+const TRACE_META_KEY = "_trace";
+function attachTraceMetadata(metadata) {
+  const carrier = getTelemetryRuntime()?.captureTraceContext() ?? {};
+  if (Object.keys(carrier).length === 0) return metadata;
+  return { ...metadata ?? {}, [TRACE_META_KEY]: carrier };
+}
+function runJobInTrace(queueName, metadata, fn) {
+  const runtime = getTelemetryRuntime();
+  if (!runtime) return fn();
+  return runtime.continueTrace(
+    readTraceCarrier(metadata),
+    `queue.${queueName}`,
+    fn,
+    { kind: "consumer" }
+  );
+}
+function readTraceCarrier(metadata) {
+  const raw = metadata?.[TRACE_META_KEY];
+  if (!raw || typeof raw !== "object") return void 0;
+  return raw;
+}
+export {
+  attachTraceMetadata,
+  runJobInTrace
+};
+//# sourceMappingURL=tracing.js.map

package/dist/tracing.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/tracing.ts"],
+  "sourcesContent": ["import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'\n\n/**\n * Distributed-trace propagation across the enqueue \u2192 worker boundary.\n *\n * The W3C trace carrier rides on the job's `metadata._trace` (a first-class\n * metadata channel, not the user payload). Both halves are automatic \u2014 the\n * strategies call `attachTraceMetadata` at enqueue and `runJobInTrace` at\n * dispatch \u2014 so a worker joins the enqueuing request's trace with no per-worker\n * code. Everything here is a cheap no-op when telemetry is off.\n *\n * This also covers anything that rides the queue: persistent event subscribers\n * (the event bus enqueues) and outbound webhook delivery (queued) become part of\n * the originating request's trace for free.\n */\nconst TRACE_META_KEY = '_trace'\n\n/**\n * Attach the active trace context to a job's metadata. Returns `metadata`\n * unchanged when telemetry is off (no active span \u2192 empty carrier), so jobs stay\n * clean unless tracing is active.\n */\nexport function attachTraceMetadata(\n  metadata: Record<string, unknown> | undefined,\n): Record<string, unknown> | undefined {\n  const carrier = getTelemetryRuntime()?.captureTraceContext() ?? {}\n  if (Object.keys(carrier).length === 0) return metadata\n  return { ...(metadata ?? {}), [TRACE_META_KEY]: carrier }\n}\n\n/**\n * Run a job handler inside a span (`queue.<queueName>`) that continues the\n * producer's trace from the carrier on `metadata`. With no carrier (or telemetry\n * off) it runs `fn` under a fresh root span \u2014 and a no-op when off. The span\n * ends when `fn` settles (sync or async).\n */\nexport function runJobInTrace<T>(\n  queueName: string,\n  metadata: Record<string, unknown> | undefined,\n  fn: () => T,\n): T {\n  const runtime = getTelemetryRuntime()\n  if (!runtime) return fn()\n  return runtime.continueTrace(\n    readTraceCarrier(metadata),\n    `queue.${queueName}`,\n    fn,\n    { kind: 'consumer' },\n  )\n}\n\nfunction readTraceCarrier(\n  metadata: Record<string, unknown> | undefined,\n): Record<string, string> | undefined {\n  const raw = metadata?.[TRACE_META_KEY]\n  if (!raw || typeof raw !== 'object') return undefined\n  return raw as Record<string, string>\n}\n"],
+  "mappings": "AAAA,SAAS,2BAA2B;AAepC,MAAM,iBAAiB;AAOhB,SAAS,oBACd,UACqC;AACrC,QAAM,UAAU,oBAAoB,GAAG,oBAAoB,KAAK,CAAC;AACjE,MAAI,OAAO,KAAK,OAAO,EAAE,WAAW,EAAG,QAAO;AAC9C,SAAO,EAAE,GAAI,YAAY,CAAC,GAAI,CAAC,cAAc,GAAG,QAAQ;AAC1D;AAQO,SAAS,cACd,WACA,UACA,IACG;AACH,QAAM,UAAU,oBAAoB;AACpC,MAAI,CAAC,QAAS,QAAO,GAAG;AACxB,SAAO,QAAQ;AAAA,IACb,iBAAiB,QAAQ;AAAA,IACzB,SAAS,SAAS;AAAA,IAClB;AAAA,IACA,EAAE,MAAM,WAAW;AAAA,EACrB;AACF;AAEA,SAAS,iBACP,UACoC;AACpC,QAAM,MAAM,WAAW,cAAc;AACrC,MAAI,CAAC,OAAO,OAAO,QAAQ,SAAU,QAAO;AAC5C,SAAO;AACT;",
+  "names": []
+}

package/dist/worker/runner.js

@@ -1,5 +1,9 @@
 import { createQueue } from "../factory.js";
 import { createLogger } from "@open-mercato/shared/lib/logger";
+import {
+  getTelemetryRuntime,
+  isTelemetryBackendEnabled
+} from "@open-mercato/shared/lib/telemetry/runtime";
 const logger = createLogger("queue").child({ component: "worker" });
 const managedQueues = /* @__PURE__ */ new Set();
 const managedShutdownHooks = /* @__PURE__ */ new Set();
@@ -37,6 +41,11 @@ function registerShutdownHandlers() {
     managedShutdownHooks.clear();
     unregisterShutdownHandlers(sigtermHandler, sigintHandler);
     shutdownInProgress = false;
+    try {
+      await getTelemetryRuntime()?.shutdown();
+    } catch (error) {
+      logger.error("Error flushing telemetry during shutdown", { err: error });
+    }
     if (!hasError) {
       logger.info("Worker closed successfully");
     }
@@ -68,6 +77,10 @@ async function runWorker(options) {
     background = false,
     strategy: strategyOption
   } = options;
+  if (!getTelemetryRuntime() && isTelemetryBackendEnabled()) {
+    const { initTelemetry } = await import("@open-mercato/telemetry");
+    await initTelemetry();
+  }
   const strategy = strategyOption ?? (process.env.QUEUE_STRATEGY === "async" ? "async" : "local");
   logger.info("Starting worker for queue", { queueName, strategy });
   const queue = createQueue(queueName, strategy, {

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  /** 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    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  // 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": "AAAA,SAAS,mBAAmB;AAC5B,SAAS,oBAAoB;AAG7B,MAAM,SAAS,aAAa,OAAO,EAAE,MAAM,EAAE,WAAW,SAAS,CAAC;AA0BlE,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;AAAA,IACA;AAAA,IACA,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,IACA;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-develop.6827.1.a575bebce9",
+  "version": "0.6.7-develop.6834.1.e76f4b8cbc",
   "license": "MIT",
   "description": "Multi-strategy job queue with local and BullMQ support",
   "type": "module",
@@ -34,11 +34,15 @@
     }
   },
   "peerDependencies": {
-    "bullmq": "^5.0.0"
+    "bullmq": "^5.0.0",
+    "bullmq-otel": "^1.3.0"
   },
   "peerDependenciesMeta": {
     "bullmq": {
       "optional": true
+    },
+    "bullmq-otel": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -52,7 +56,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@open-mercato/shared": "0.6.7-develop.6827.1.a575bebce9"
+    "@open-mercato/shared": "0.6.7-develop.6834.1.e76f4b8cbc",
+    "@open-mercato/telemetry": "0.6.7-develop.6834.1.e76f4b8cbc"
   },
   "repository": {
     "type": "git",

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

@@ -0,0 +1,122 @@
+// 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(),
+}))
+
+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__/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/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 { 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')
@@ -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 {
@@ -119,6 +130,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 +152,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 +191,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 +214,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 } : {}),
       }

package/src/strategies/local.ts

@@ -3,6 +3,7 @@ import path from 'node:path'
 import crypto from 'node:crypto'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 import type { Queue, QueuedJob, JobHandler, LocalQueueOptions, ProcessOptions, ProcessResult, EnqueueOptions, QueueJobScope } from '../types'
+import { attachTraceMetadata, runJobInTrace } from '../tracing'
 
 const packageLogger = createLogger('queue')
 
@@ -205,11 +206,13 @@ export function createLocalQueue<T = unknown>(
     const availableAt = options?.delayMs && options.delayMs > 0
       ? new Date(Date.now() + options.delayMs).toISOString()
       : undefined
+    const metadata = attachTraceMetadata(undefined)
     const job: StoredJob<T> = {
       id: generateId(),
       payload: data,
       createdAt: new Date().toISOString(),
       ...(availableAt ? { availableAt } : {}),
+      ...(metadata ? { metadata } : {}),
     }
     await withFileLock(async () => {
       const jobs = await readQueue()
@@ -255,12 +258,14 @@ export function createLocalQueue<T = unknown>(
       for (const job of jobsToProcess) {
         const attemptNumber = (job.attemptCount ?? 0) + 1
         try {
-          await Promise.resolve(
-            handler(job, {
-              jobId: job.id,
-              attemptNumber,
-              queueName: name,
-            })
+          await runJobInTrace(name, job.metadata, () =>
+            Promise.resolve(
+              handler(job, {
+                jobId: job.id,
+                attemptNumber,
+                queueName: name,
+              })
+            )
           )
           processed++
           lastJobId = job.id

package/src/tracing.ts

@@ -0,0 +1,58 @@
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+
+/**
+ * Distributed-trace propagation across the enqueue → worker boundary.
+ *
+ * The W3C trace carrier rides on the job's `metadata._trace` (a first-class
+ * metadata channel, not the user payload). Both halves are automatic — the
+ * strategies call `attachTraceMetadata` at enqueue and `runJobInTrace` at
+ * dispatch — so a worker joins the enqueuing request's trace with no per-worker
+ * code. Everything here is a cheap no-op when telemetry is off.
+ *
+ * This also covers anything that rides the queue: persistent event subscribers
+ * (the event bus enqueues) and outbound webhook delivery (queued) become part of
+ * the originating request's trace for free.
+ */
+const TRACE_META_KEY = '_trace'
+
+/**
+ * Attach the active trace context to a job's metadata. Returns `metadata`
+ * unchanged when telemetry is off (no active span → empty carrier), so jobs stay
+ * clean unless tracing is active.
+ */
+export function attachTraceMetadata(
+  metadata: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  const carrier = getTelemetryRuntime()?.captureTraceContext() ?? {}
+  if (Object.keys(carrier).length === 0) return metadata
+  return { ...(metadata ?? {}), [TRACE_META_KEY]: carrier }
+}
+
+/**
+ * Run a job handler inside a span (`queue.<queueName>`) that continues the
+ * producer's trace from the carrier on `metadata`. With no carrier (or telemetry
+ * off) it runs `fn` under a fresh root span — and a no-op when off. The span
+ * ends when `fn` settles (sync or async).
+ */
+export function runJobInTrace<T>(
+  queueName: string,
+  metadata: Record<string, unknown> | undefined,
+  fn: () => T,
+): T {
+  const runtime = getTelemetryRuntime()
+  if (!runtime) return fn()
+  return runtime.continueTrace(
+    readTraceCarrier(metadata),
+    `queue.${queueName}`,
+    fn,
+    { kind: 'consumer' },
+  )
+}
+
+function readTraceCarrier(
+  metadata: Record<string, unknown> | undefined,
+): Record<string, string> | undefined {
+  const raw = metadata?.[TRACE_META_KEY]
+  if (!raw || typeof raw !== 'object') return undefined
+  return raw as Record<string, string>
+}

package/src/worker/runner.ts

@@ -1,5 +1,9 @@
 import { createQueue } from '../factory'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import {
+  getTelemetryRuntime,
+  isTelemetryBackendEnabled,
+} from '@open-mercato/shared/lib/telemetry/runtime'
 import type { Queue, JobHandler, AsyncQueueOptions, QueueStrategyType } from '../types'
 
 const logger = createLogger('queue').child({ component: 'worker' })
@@ -71,6 +75,17 @@ function registerShutdownHandlers(): void {
     unregisterShutdownHandlers(sigtermHandler, sigintHandler)
     shutdownInProgress = false
 
+    // Flush buffered spans/logs before the process dies. A worker never returns
+    // from run(), so bin.ts's post-run shutdownTelemetry() is unreachable on this
+    // path — without this, the BatchSpanProcessor's ~5s tail is dropped on every
+    // restart/redeploy. Idempotent and a no-op when telemetry is off; a flush
+    // failure must not turn a clean shutdown into a failed one.
+    try {
+      await getTelemetryRuntime()?.shutdown()
+    } catch (error) {
+      logger.error('Error flushing telemetry during shutdown', { err: error })
+    }
+
     if (!hasError) {
       logger.info('Worker closed successfully')
     }
@@ -141,6 +156,15 @@ export async function runWorker<T = unknown>(
     strategy: strategyOption,
   } = options
 
+  // Worker processes don't run Next's instrumentation hook, so initialize
+  // telemetry here — this is the single bootstrap every standalone worker passes
+  // through. Import the telemetry package only for an explicit enabled backend;
+  // with the default/unset backend the worker never evaluates the package.
+  if (!getTelemetryRuntime() && isTelemetryBackendEnabled()) {
+    const { initTelemetry } = await import('@open-mercato/telemetry')
+    await initTelemetry()
+  }
+
   // Determine queue strategy from option, env var, or default to 'local'
   const strategy: QueueStrategyType = strategyOption
     ?? (process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local')