@trigger.dev/redis-worker 4.3.1 → 4.3.3

package/dist/index.js

@@ -10826,6 +10826,9 @@ var SpanStatusCode;
   SpanStatusCode2[SpanStatusCode2["ERROR"] = 2] = "ERROR";
 })(SpanStatusCode || (SpanStatusCode = {}));
 
+// ../../node_modules/.pnpm/@opentelemetry+api@1.9.0/node_modules/@opentelemetry/api/build/esm/context-api.js
+var context = ContextAPI.getInstance();
+
 // ../../node_modules/.pnpm/@opentelemetry+api@1.9.0/node_modules/@opentelemetry/api/build/esm/metrics/NoopMeterProvider.js
 var NoopMeterProvider = (
   /** @class */
@@ -11723,6 +11726,11 @@ var Worker = class _Worker {
   }
 };
 
+// src/utils.ts
+function isAbortError(error) {
+  return error instanceof Error && (error.name === "AbortError" || error.message === "AbortError");
+}
+
 // src/fair-queue/concurrency.ts
 var ConcurrencyManager = class {
   constructor(options) {
@@ -11799,6 +11807,37 @@ var ConcurrencyManager = class {
     const key = this.keys.concurrencyKey(groupName, groupId);
     return await this.redis.scard(key);
   }
+  /**
+   * Get available capacity for a queue across all concurrency groups.
+   * Returns the minimum available capacity across all groups.
+   */
+  async getAvailableCapacity(queue) {
+    if (this.groups.length === 0) {
+      return 0;
+    }
+    const groupData = this.groups.map((group) => ({
+      group,
+      groupId: group.extractGroupId(queue)
+    }));
+    const [currents, limits] = await Promise.all([
+      Promise.all(
+        groupData.map(
+          ({ group, groupId }) => this.redis.scard(this.keys.concurrencyKey(group.name, groupId))
+        )
+      ),
+      Promise.all(
+        groupData.map(
+          ({ group, groupId }) => group.getLimit(groupId).then((limit) => limit || group.defaultLimit)
+        )
+      )
+    ]);
+    let minCapacity = Infinity;
+    for (let i = 0; i < groupData.length; i++) {
+      const available = Math.max(0, limits[i] - currents[i]);
+      minCapacity = Math.min(minCapacity, available);
+    }
+    return minCapacity === Infinity ? 0 : minCapacity;
+  }
   /**
    * Get concurrency limit for a specific group.
    */
@@ -12305,7 +12344,8 @@ var FairQueueTelemetry = class {
   // Helper Methods
   // ============================================================================
   /**
-   * Create standard attributes for a message operation.
+   * Create standard attributes for a message operation (for spans/traces).
+   * Use this for span attributes where high cardinality is acceptable.
    */
   messageAttributes(params) {
     const attrs = {};
@@ -12391,6 +12431,187 @@ var FairQueueTelemetry = class {
     };
   }
 };
+var BatchedSpanManager = class {
+  tracer;
+  name;
+  maxIterations;
+  timeoutSeconds;
+  loopStates = /* @__PURE__ */ new Map();
+  getDynamicAttributes;
+  constructor(options) {
+    this.tracer = options.tracer;
+    this.name = options.name;
+    this.maxIterations = options.maxIterations;
+    this.timeoutSeconds = options.timeoutSeconds;
+    this.getDynamicAttributes = options.getDynamicAttributes;
+  }
+  /**
+   * Initialize state for a consumer loop.
+   */
+  initializeLoop(loopId) {
+    this.loopStates.set(loopId, {
+      perTraceCountdown: this.maxIterations,
+      traceStartedAt: /* @__PURE__ */ new Date(),
+      iterationsCount: 0,
+      totalIterationsCount: 0,
+      runningDurationInMs: 0,
+      stats: {},
+      endSpanInNextIteration: false
+    });
+  }
+  /**
+   * Get the state for a consumer loop.
+   */
+  getState(loopId) {
+    return this.loopStates.get(loopId);
+  }
+  /**
+   * Increment a stat counter for a loop.
+   */
+  incrementStat(loopId, statName, value = 1) {
+    const state = this.loopStates.get(loopId);
+    if (state) {
+      state.stats[statName] = (state.stats[statName] ?? 0) + value;
+    }
+  }
+  /**
+   * Mark that the span should end on the next iteration.
+   */
+  markForRotation(loopId) {
+    const state = this.loopStates.get(loopId);
+    if (state) {
+      state.endSpanInNextIteration = true;
+    }
+  }
+  /**
+   * Check if the span should be rotated (ended and a new one started).
+   */
+  shouldRotate(loopId) {
+    const state = this.loopStates.get(loopId);
+    if (!state) return true;
+    return state.perTraceCountdown <= 0 || Date.now() - state.traceStartedAt.getTime() > this.timeoutSeconds * 1e3 || state.currentSpanContext === void 0 || state.endSpanInNextIteration;
+  }
+  /**
+   * End the current span for a loop and record stats.
+   */
+  endCurrentSpan(loopId) {
+    const state = this.loopStates.get(loopId);
+    if (!state?.currentSpan) return;
+    for (const [statName, count] of Object.entries(state.stats)) {
+      state.currentSpan.setAttribute(`stats.${statName}`, count);
+    }
+    state.currentSpan.end();
+    state.currentSpan = void 0;
+    state.currentSpanContext = void 0;
+  }
+  /**
+   * Start a new batched span for a loop.
+   */
+  startNewSpan(loopId, attributes) {
+    if (!this.tracer) return;
+    const state = this.loopStates.get(loopId);
+    if (!state) return;
+    this.endCurrentSpan(loopId);
+    const traceDurationInMs = state.traceStartedAt ? Date.now() - state.traceStartedAt.getTime() : void 0;
+    const iterationsPerSecond = traceDurationInMs && traceDurationInMs > 0 ? state.iterationsCount / (traceDurationInMs / 1e3) : void 0;
+    const dynamicAttributes = this.getDynamicAttributes?.() ?? {};
+    state.currentSpan = this.tracer.startSpan(
+      `${this.name}.consumerLoop`,
+      {
+        kind: 1,
+        // SpanKind.CONSUMER
+        attributes: {
+          loop_id: loopId,
+          max_iterations: this.maxIterations,
+          timeout_seconds: this.timeoutSeconds,
+          previous_iterations: state.iterationsCount,
+          previous_duration_ms: traceDurationInMs,
+          previous_iterations_per_second: iterationsPerSecond,
+          total_iterations: state.totalIterationsCount,
+          ...dynamicAttributes,
+          ...attributes
+        }
+      },
+      ROOT_CONTEXT
+    );
+    state.currentSpanContext = trace.setSpan(ROOT_CONTEXT, state.currentSpan);
+    state.perTraceCountdown = this.maxIterations;
+    state.traceStartedAt = /* @__PURE__ */ new Date();
+    state.iterationsCount = 0;
+    state.runningDurationInMs = 0;
+    state.stats = {};
+    state.endSpanInNextIteration = false;
+  }
+  /**
+   * Execute a function within the batched span context.
+   * Automatically handles span rotation and iteration tracking.
+   */
+  async withBatchedSpan(loopId, fn, options) {
+    let state = this.loopStates.get(loopId);
+    if (!state) {
+      this.initializeLoop(loopId);
+      state = this.loopStates.get(loopId);
+    }
+    if (this.shouldRotate(loopId)) {
+      this.startNewSpan(loopId);
+    }
+    const startTime = performance.now();
+    try {
+      if (!this.tracer || !state.currentSpanContext) {
+        return await fn(noopSpan);
+      }
+      return await context.with(state.currentSpanContext, async () => {
+        const iterationSpanName = options?.iterationSpanName ?? "iteration";
+        return await this.tracer.startActiveSpan(
+          `${this.name}.${iterationSpanName}`,
+          {
+            attributes: {
+              loop_id: loopId,
+              iteration: state.iterationsCount,
+              ...options?.attributes
+            }
+          },
+          async (iterationSpan) => {
+            try {
+              return await fn(iterationSpan);
+            } catch (error) {
+              if (error instanceof Error) {
+                iterationSpan.recordException(error);
+                state.currentSpan?.recordException(error);
+              }
+              iterationSpan.setStatus({ code: SpanStatusCode.ERROR });
+              state.endSpanInNextIteration = true;
+              throw error;
+            } finally {
+              iterationSpan.end();
+            }
+          }
+        );
+      });
+    } finally {
+      const duration = performance.now() - startTime;
+      state.runningDurationInMs += duration;
+      state.iterationsCount++;
+      state.totalIterationsCount++;
+      state.perTraceCountdown--;
+    }
+  }
+  /**
+   * Clean up state for a loop when it's stopped.
+   */
+  cleanup(loopId) {
+    this.endCurrentSpan(loopId);
+    this.loopStates.delete(loopId);
+  }
+  /**
+   * Clean up all loop states.
+   */
+  cleanupAll() {
+    for (const loopId of this.loopStates.keys()) {
+      this.cleanup(loopId);
+    }
+  }
+};
 var noopSpan = {
   spanContext: () => ({
     traceId: "",
@@ -12490,6 +12711,71 @@ var VisibilityManager = class {
       return { claimed: false };
     }
   }
+  /**
+   * Claim multiple messages for processing (batch claim).
+   * Moves up to maxCount messages from the queue to the in-flight set.
+   *
+   * @param queueId - The queue to claim from
+   * @param queueKey - The Redis key for the queue sorted set
+   * @param queueItemsKey - The Redis key for the queue items hash
+   * @param consumerId - ID of the consumer claiming the messages
+   * @param maxCount - Maximum number of messages to claim
+   * @param timeoutMs - Visibility timeout in milliseconds
+   * @returns Array of claimed messages
+   */
+  async claimBatch(queueId, queueKey, queueItemsKey, consumerId, maxCount, timeoutMs) {
+    const timeout = timeoutMs ?? this.defaultTimeoutMs;
+    const deadline = Date.now() + timeout;
+    const shardId = this.#getShardForQueue(queueId);
+    const inflightKey = this.keys.inflightKey(shardId);
+    const inflightDataKey = this.keys.inflightDataKey(shardId);
+    const result = await this.redis.claimMessageBatch(
+      queueKey,
+      queueItemsKey,
+      inflightKey,
+      inflightDataKey,
+      queueId,
+      deadline.toString(),
+      maxCount.toString()
+    );
+    if (!result || result.length === 0) {
+      return [];
+    }
+    const messages = [];
+    for (let i = 0; i < result.length; i += 2) {
+      const messageId = result[i];
+      const payloadJson = result[i + 1];
+      if (!messageId || !payloadJson) {
+        continue;
+      }
+      try {
+        const payload = JSON.parse(payloadJson);
+        messages.push({
+          messageId,
+          queueId,
+          payload,
+          deadline,
+          consumerId
+        });
+      } catch (error) {
+        this.logger.error("Failed to parse claimed message in batch", {
+          messageId,
+          queueId,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        await this.#removeFromInflight(shardId, messageId, queueId);
+      }
+    }
+    if (messages.length > 0) {
+      this.logger.debug("Batch claimed messages", {
+        queueId,
+        consumerId,
+        count: messages.length,
+        deadline
+      });
+    }
+    return messages;
+  }
   /**
    * Extend the visibility timeout for a message (heartbeat).
    *
@@ -12503,11 +12789,7 @@ var VisibilityManager = class {
     const inflightKey = this.keys.inflightKey(shardId);
     const member = this.#makeMember(messageId, queueId);
     const newDeadline = Date.now() + extendMs;
-    const result = await this.redis.heartbeatMessage(
-      inflightKey,
-      member,
-      newDeadline.toString()
-    );
+    const result = await this.redis.heartbeatMessage(inflightKey, member, newDeadline.toString());
     const success = result === 1;
     if (success) {
       this.logger.debug("Heartbeat successful", {
@@ -12541,9 +12823,10 @@ var VisibilityManager = class {
    * @param queueId - The queue ID
    * @param queueKey - The Redis key for the queue
    * @param queueItemsKey - The Redis key for the queue items hash
+   * @param masterQueueKey - The Redis key for the master queue
    * @param score - Optional score for the message (defaults to now)
    */
-  async release(messageId, queueId, queueKey, queueItemsKey, score) {
+  async release(messageId, queueId, queueKey, queueItemsKey, masterQueueKey, score) {
     const shardId = this.#getShardForQueue(queueId);
     const inflightKey = this.keys.inflightKey(shardId);
     const inflightDataKey = this.keys.inflightDataKey(shardId);
@@ -12554,9 +12837,11 @@ var VisibilityManager = class {
       inflightDataKey,
       queueKey,
       queueItemsKey,
+      masterQueueKey,
       member,
       messageId,
-      messageScore.toString()
+      messageScore.toString(),
+      queueId
     );
     this.logger.debug("Message released", {
       messageId,
@@ -12564,6 +12849,45 @@ var VisibilityManager = class {
       score: messageScore
     });
   }
+  /**
+   * Release multiple messages back to their queue in a single operation.
+   * Used when processing fails or consumer wants to retry later.
+   * All messages must belong to the same queue.
+   *
+   * @param messages - Array of messages to release (must all have same queueId)
+   * @param queueId - The queue ID
+   * @param queueKey - The Redis key for the queue
+   * @param queueItemsKey - The Redis key for the queue items hash
+   * @param masterQueueKey - The Redis key for the master queue
+   * @param score - Optional score for the messages (defaults to now)
+   */
+  async releaseBatch(messages, queueId, queueKey, queueItemsKey, masterQueueKey, score) {
+    if (messages.length === 0) {
+      return;
+    }
+    const shardId = this.#getShardForQueue(queueId);
+    const inflightKey = this.keys.inflightKey(shardId);
+    const inflightDataKey = this.keys.inflightDataKey(shardId);
+    const messageScore = score ?? Date.now();
+    const messageIds = messages.map((m) => m.messageId);
+    const members = messages.map((m) => this.#makeMember(m.messageId, queueId));
+    await this.redis.releaseMessageBatch(
+      inflightKey,
+      inflightDataKey,
+      queueKey,
+      queueItemsKey,
+      masterQueueKey,
+      messageScore.toString(),
+      queueId,
+      ...members,
+      ...messageIds
+    );
+    this.logger.debug("Batch messages released", {
+      queueId,
+      count: messages.length,
+      score: messageScore
+    });
+  }
   /**
    * Reclaim timed-out messages from a shard.
    * Returns messages to their original queues.
@@ -12594,7 +12918,7 @@ var VisibilityManager = class {
         continue;
       }
       const { messageId, queueId } = this.#parseMember(member);
-      const { queueKey, queueItemsKey } = getQueueKeys(queueId);
+      const { queueKey, queueItemsKey, masterQueueKey } = getQueueKeys(queueId);
       try {
         const score = parseFloat(originalScore) || now;
         await this.redis.releaseMessage(
@@ -12602,9 +12926,11 @@ var VisibilityManager = class {
           inflightDataKey,
           queueKey,
           queueItemsKey,
+          masterQueueKey,
           member,
           messageId,
-          score.toString()
+          score.toString(),
+          queueId
         );
         reclaimed++;
         this.logger.debug("Reclaimed timed-out message", {
@@ -12738,17 +13064,67 @@ redis.call('HSET', inflightDataKey, messageId, payload)
 return {messageId, payload}
       `
     });
-    this.redis.defineCommand("releaseMessage", {
+    this.redis.defineCommand("claimMessageBatch", {
       numberOfKeys: 4,
       lua: `
+local queueKey = KEYS[1]
+local queueItemsKey = KEYS[2]
+local inflightKey = KEYS[3]
+local inflightDataKey = KEYS[4]
+
+local queueId = ARGV[1]
+local deadline = tonumber(ARGV[2])
+local maxCount = tonumber(ARGV[3])
+
+-- Get up to maxCount oldest messages from queue
+local items = redis.call('ZRANGE', queueKey, 0, maxCount - 1)
+if #items == 0 then
+  return {}
+end
+
+local results = {}
+
+for i, messageId in ipairs(items) do
+  -- Get message data
+  local payload = redis.call('HGET', queueItemsKey, messageId)
+  
+  if payload then
+    -- Remove from queue
+    redis.call('ZREM', queueKey, messageId)
+    redis.call('HDEL', queueItemsKey, messageId)
+    
+    -- Add to in-flight set with deadline
+    local member = messageId .. ':' .. queueId
+    redis.call('ZADD', inflightKey, deadline, member)
+    
+    -- Store message data for potential release
+    redis.call('HSET', inflightDataKey, messageId, payload)
+    
+    -- Add to results
+    table.insert(results, messageId)
+    table.insert(results, payload)
+  else
+    -- Message data missing, remove from queue
+    redis.call('ZREM', queueKey, messageId)
+  end
+end
+
+return results
+      `
+    });
+    this.redis.defineCommand("releaseMessage", {
+      numberOfKeys: 5,
+      lua: `
 local inflightKey = KEYS[1]
 local inflightDataKey = KEYS[2]
 local queueKey = KEYS[3]
 local queueItemsKey = KEYS[4]
+local masterQueueKey = KEYS[5]
 
 local member = ARGV[1]
 local messageId = ARGV[2]
 local score = tonumber(ARGV[3])
+local queueId = ARGV[4]
 
 -- Get message data from in-flight
 local payload = redis.call('HGET', inflightDataKey, messageId)
@@ -12765,9 +13141,67 @@ redis.call('HDEL', inflightDataKey, messageId)
 redis.call('ZADD', queueKey, score, messageId)
 redis.call('HSET', queueItemsKey, messageId, payload)
 
+-- Update master queue with oldest message timestamp
+-- This ensures delayed messages don't push the queue priority to the future
+-- when there are other ready messages in the queue
+local oldest = redis.call('ZRANGE', queueKey, 0, 0, 'WITHSCORES')
+if #oldest >= 2 then
+  redis.call('ZADD', masterQueueKey, oldest[2], queueId)
+end
+
 return 1
       `
     });
+    this.redis.defineCommand("releaseMessageBatch", {
+      numberOfKeys: 5,
+      lua: `
+local inflightKey = KEYS[1]
+local inflightDataKey = KEYS[2]
+local queueKey = KEYS[3]
+local queueItemsKey = KEYS[4]
+local masterQueueKey = KEYS[5]
+
+local score = tonumber(ARGV[1])
+local queueId = ARGV[2]
+
+-- Remaining args are: members..., messageIds...
+-- Calculate how many messages we have
+local numMessages = (table.getn(ARGV) - 2) / 2
+local membersStart = 3
+local messageIdsStart = membersStart + numMessages
+
+local releasedCount = 0
+
+for i = 0, numMessages - 1 do
+  local member = ARGV[membersStart + i]
+  local messageId = ARGV[messageIdsStart + i]
+  
+  -- Get message data from in-flight
+  local payload = redis.call('HGET', inflightDataKey, messageId)
+  if payload then
+    -- Remove from in-flight
+    redis.call('ZREM', inflightKey, member)
+    redis.call('HDEL', inflightDataKey, messageId)
+    
+    -- Add back to queue
+    redis.call('ZADD', queueKey, score, messageId)
+    redis.call('HSET', queueItemsKey, messageId, payload)
+    
+    releasedCount = releasedCount + 1
+  end
+end
+
+-- Update master queue with oldest message timestamp (only once at the end)
+if releasedCount > 0 then
+  local oldest = redis.call('ZRANGE', queueKey, 0, 0, 'WITHSCORES')
+  if #oldest >= 2 then
+    redis.call('ZADD', masterQueueKey, oldest[2], queueId)
+  end
+end
+
+return releasedCount
+      `
+    });
     this.redis.defineCommand("heartbeatMessage", {
       numberOfKeys: 1,
       lua: `
@@ -12855,11 +13289,11 @@ var WorkerQueueManager = class {
   async blockingPop(workerQueueId, timeoutSeconds, signal) {
     const workerQueueKey = this.keys.workerQueueKey(workerQueueId);
     const blockingClient = this.redis.duplicate();
+    const cleanup = signal ? () => {
+      blockingClient.disconnect();
+    } : null;
     try {
-      if (signal) {
-        const cleanup = () => {
-          blockingClient.disconnect();
-        };
+      if (signal && cleanup) {
         signal.addEventListener("abort", cleanup, { once: true });
         if (signal.aborted) {
           return null;
@@ -12886,6 +13320,9 @@ var WorkerQueueManager = class {
       });
       throw error;
     } finally {
+      if (cleanup && signal) {
+        signal.removeEventListener("abort", cleanup);
+      }
       await blockingClient.quit().catch(() => {
       });
     }
@@ -13117,6 +13554,13 @@ var BaseScheduler = class {
    */
   async recordProcessed(_tenantId, _queueId) {
   }
+  /**
+   * Called after processing multiple messages to update scheduler state.
+   * Batch variant for efficiency - reduces Redis calls when processing multiple messages.
+   * Default implementation does nothing.
+   */
+  async recordProcessedBatch(_tenantId, _queueId, _count) {
+  }
   /**
    * Initialize the scheduler.
    * Default implementation does nothing.
@@ -13179,6 +13623,7 @@ var DRRScheduler = class extends BaseScheduler {
     this.keys = config.keys;
     this.quantum = config.quantum;
     this.maxDeficit = config.maxDeficit;
+    this.masterQueueLimit = config.masterQueueLimit ?? 1e3;
     this.logger = config.logger ?? {
       debug: () => {
       },
@@ -13191,6 +13636,7 @@ var DRRScheduler = class extends BaseScheduler {
   keys;
   quantum;
   maxDeficit;
+  masterQueueLimit;
   logger;
   // ============================================================================
   // FairScheduler Implementation
@@ -13256,6 +13702,13 @@ var DRRScheduler = class extends BaseScheduler {
   async recordProcessed(tenantId, _queueId) {
     await this.#decrementDeficit(tenantId);
   }
+  /**
+   * Record that multiple messages were processed from a tenant.
+   * Decrements the tenant's deficit by count atomically.
+   */
+  async recordProcessedBatch(tenantId, _queueId, count) {
+    await this.#decrementDeficitBatch(tenantId, count);
+  }
   async close() {
     await this.redis.quit();
   }
@@ -13305,8 +13758,7 @@ var DRRScheduler = class extends BaseScheduler {
       "WITHSCORES",
       "LIMIT",
       0,
-      1e3
-      // Limit for performance
+      this.masterQueueLimit
     );
     const queues = [];
     for (let i = 0; i < results.length; i += 2) {
@@ -13347,6 +13799,14 @@ var DRRScheduler = class extends BaseScheduler {
     const result = await this.redis.drrDecrementDeficit(key, tenantId);
     return parseFloat(result);
   }
+  /**
+   * Decrement deficit for a tenant by a count atomically.
+   */
+  async #decrementDeficitBatch(tenantId, count) {
+    const key = this.#deficitKey();
+    const result = await this.redis.drrDecrementDeficitBatch(key, tenantId, count.toString());
+    return parseFloat(result);
+  }
   #registerCommands() {
     this.redis.defineCommand("drrAddQuantum", {
       numberOfKeys: 1,
@@ -13390,6 +13850,25 @@ if newDeficit < 0 then
   newDeficit = 0
 end
 
+return tostring(newDeficit)
+      `
+    });
+    this.redis.defineCommand("drrDecrementDeficitBatch", {
+      numberOfKeys: 1,
+      lua: `
+local deficitKey = KEYS[1]
+local tenantId = ARGV[1]
+local count = tonumber(ARGV[2])
+
+local newDeficit = redis.call('HINCRBYFLOAT', deficitKey, tenantId, -count)
+newDeficit = tonumber(newDeficit)
+
+-- Floor at 0
+if newDeficit < 0 then
+  redis.call('HSET', deficitKey, tenantId, 0)
+  newDeficit = 0
+end
+
 return tostring(newDeficit)
       `
     });
@@ -13897,18 +14376,30 @@ var FairQueue = class {
     this.visibilityTimeoutMs = options.visibilityTimeoutMs ?? 3e4;
     this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? this.visibilityTimeoutMs / 3;
     this.reclaimIntervalMs = options.reclaimIntervalMs ?? 5e3;
-    this.workerQueueEnabled = options.workerQueue?.enabled ?? false;
-    this.workerQueueBlockingTimeoutSeconds = options.workerQueue?.blockingTimeoutSeconds ?? 10;
-    this.workerQueueResolver = options.workerQueue?.resolveWorkerQueue;
+    this.workerQueueResolver = options.workerQueue.resolveWorkerQueue;
+    this.batchClaimSize = options.batchClaimSize ?? 10;
     this.cooloffEnabled = options.cooloff?.enabled ?? true;
     this.cooloffThreshold = options.cooloff?.threshold ?? 10;
     this.cooloffPeriodMs = options.cooloff?.periodMs ?? 1e4;
+    this.maxCooloffStatesSize = options.cooloff?.maxStatesSize ?? 1e3;
     this.globalRateLimiter = options.globalRateLimiter;
+    this.consumerTraceMaxIterations = options.consumerTraceMaxIterations ?? 500;
+    this.consumerTraceTimeoutSeconds = options.consumerTraceTimeoutSeconds ?? 60;
     this.telemetry = new FairQueueTelemetry({
       tracer: options.tracer,
       meter: options.meter,
       name: options.name ?? "fairqueue"
     });
+    this.batchedSpanManager = new BatchedSpanManager({
+      tracer: options.tracer,
+      name: options.name ?? "fairqueue",
+      maxIterations: this.consumerTraceMaxIterations,
+      timeoutSeconds: this.consumerTraceTimeoutSeconds,
+      getDynamicAttributes: () => ({
+        "cache.descriptor_size": this.queueDescriptorCache.size,
+        "cache.cooloff_states_size": this.queueCooloffStates.size
+      })
+    });
     this.masterQueue = new MasterQueue({
       redis: options.redis,
       keys: options.keys,
@@ -13931,16 +14422,14 @@ var FairQueue = class {
         error: (msg, ctx) => this.logger.error(msg, ctx)
       }
     });
-    if (this.workerQueueEnabled) {
-      this.workerQueueManager = new WorkerQueueManager({
-        redis: options.redis,
-        keys: options.keys,
-        logger: {
-          debug: (msg, ctx) => this.logger.debug(msg, ctx),
-          error: (msg, ctx) => this.logger.error(msg, ctx)
-        }
-      });
-    }
+    this.workerQueueManager = new WorkerQueueManager({
+      redis: options.redis,
+      keys: options.keys,
+      logger: {
+        debug: (msg, ctx) => this.logger.debug(msg, ctx),
+        error: (msg, ctx) => this.logger.error(msg, ctx)
+      }
+    });
     this.#registerCommands();
     if (options.startConsumers !== false) {
       this.start();
@@ -13966,22 +14455,24 @@ var FairQueue = class {
   visibilityTimeoutMs;
   heartbeatIntervalMs;
   reclaimIntervalMs;
-  workerQueueEnabled;
-  workerQueueBlockingTimeoutSeconds;
   workerQueueResolver;
+  batchClaimSize;
   // Cooloff state
   cooloffEnabled;
   cooloffThreshold;
   cooloffPeriodMs;
+  maxCooloffStatesSize;
   queueCooloffStates = /* @__PURE__ */ new Map();
   // Global rate limiter
   globalRateLimiter;
+  // Consumer tracing
+  consumerTraceMaxIterations;
+  consumerTraceTimeoutSeconds;
+  batchedSpanManager;
   // Runtime state
-  messageHandler;
   isRunning = false;
   abortController;
   masterQueueConsumerLoops = [];
-  workerQueueConsumerLoops = [];
   reclaimLoop;
   // Queue descriptor cache for message processing
   queueDescriptorCache = /* @__PURE__ */ new Map();
@@ -14010,15 +14501,6 @@ var FairQueue = class {
     });
   }
   // ============================================================================
-  // Public API - Message Handler
-  // ============================================================================
-  /**
-   * Set the message handler for processing dequeued messages.
-   */
-  onMessage(handler) {
-    this.messageHandler = handler;
-  }
-  // ============================================================================
   // Public API - Enqueueing
   // ============================================================================
   /**
@@ -14061,7 +14543,7 @@ var FairQueue = class {
             timestamp,
             attempt: 1,
             metadata: options.metadata
-          }) : options.queueId,
+          }) : void 0,
           metadata: options.metadata
         };
         await this.redis.enqueueMessageAtomic(
@@ -14079,13 +14561,7 @@ var FairQueue = class {
           [FairQueueAttributes.MESSAGE_ID]: messageId,
           [FairQueueAttributes.SHARD_ID]: shardId.toString()
         });
-        this.telemetry.recordEnqueue(
-          this.telemetry.messageAttributes({
-            queueId: options.queueId,
-            tenantId: options.tenantId,
-            messageId
-          })
-        );
+        this.telemetry.recordEnqueue();
         this.logger.debug("Message enqueued", {
           queueId: options.queueId,
           messageId,
@@ -14147,7 +14623,7 @@ var FairQueue = class {
               timestamp,
               attempt: 1,
               metadata: options.metadata
-            }) : options.queueId,
+            }) : void 0,
             metadata: options.metadata
           };
           messageIds.push(messageId);
@@ -14166,13 +14642,7 @@ var FairQueue = class {
           [FairQueueAttributes.MESSAGE_COUNT]: messageIds.length,
           [FairQueueAttributes.SHARD_ID]: shardId.toString()
         });
-        this.telemetry.recordEnqueueBatch(
-          messageIds.length,
-          this.telemetry.messageAttributes({
-            queueId: options.queueId,
-            tenantId: options.tenantId
-          })
-        );
+        this.telemetry.recordEnqueueBatch(messageIds.length);
         this.logger.debug("Batch enqueued", {
           queueId: options.queueId,
           messageCount: messageIds.length
@@ -14299,40 +14769,54 @@ var FairQueue = class {
     const dlqKey = this.keys.deadLetterQueueKey(tenantId);
     return await this.redis.zcard(dlqKey);
   }
-  // ============================================================================
-  // Public API - Lifecycle
-  // ============================================================================
   /**
-   * Start the consumer loops and reclaim loop.
+   * Get the size of the in-memory queue descriptor cache.
+   * This cache stores metadata for queues that have been enqueued.
+   * The cache is cleaned up when queues are fully processed.
    */
-  start() {
-    if (this.isRunning) {
-      return;
-    }
-    this.isRunning = true;
-    this.abortController = new AbortController();
-    if (this.workerQueueEnabled && this.workerQueueManager) {
-      for (let shardId = 0; shardId < this.shardCount; shardId++) {
-        const loop = this.#runMasterQueueConsumerLoop(shardId);
-        this.masterQueueConsumerLoops.push(loop);
-      }
-      for (let consumerId = 0; consumerId < this.consumerCount; consumerId++) {
-        const loop = this.#runWorkerQueueConsumerLoop(consumerId);
-        this.workerQueueConsumerLoops.push(loop);
-      }
-    } else {
-      for (let consumerId = 0; consumerId < this.consumerCount; consumerId++) {
-        for (let shardId = 0; shardId < this.shardCount; shardId++) {
-          const loop = this.#runDirectConsumerLoop(consumerId, shardId);
-          this.masterQueueConsumerLoops.push(loop);
-        }
-      }
+  getQueueDescriptorCacheSize() {
+    return this.queueDescriptorCache.size;
+  }
+  /**
+   * Get the size of the in-memory cooloff states cache.
+   * This cache tracks queues that are in cooloff due to repeated failures.
+   * The cache is cleaned up when queues are fully processed or cooloff expires.
+   */
+  getQueueCooloffStatesSize() {
+    return this.queueCooloffStates.size;
+  }
+  /**
+   * Get all in-memory cache sizes for monitoring.
+   * Useful for adding as span attributes.
+   */
+  getCacheSizes() {
+    return {
+      descriptorCacheSize: this.queueDescriptorCache.size,
+      cooloffStatesSize: this.queueCooloffStates.size
+    };
+  }
+  // ============================================================================
+  // Public API - Lifecycle
+  // ============================================================================
+  /**
+   * Start the master queue consumer loops and reclaim loop.
+   * FairQueue claims messages and pushes them to worker queues.
+   * External consumers are responsible for consuming from worker queues.
+   */
+  start() {
+    if (this.isRunning) {
+      return;
+    }
+    this.isRunning = true;
+    this.abortController = new AbortController();
+    for (let shardId = 0; shardId < this.shardCount; shardId++) {
+      const loop = this.#runMasterQueueConsumerLoop(shardId);
+      this.masterQueueConsumerLoops.push(loop);
     }
     this.reclaimLoop = this.#runReclaimLoop();
     this.logger.info("FairQueue started", {
       consumerCount: this.consumerCount,
       shardCount: this.shardCount,
-      workerQueueEnabled: this.workerQueueEnabled,
       consumerIntervalMs: this.consumerIntervalMs
     });
   }
@@ -14345,13 +14829,8 @@ var FairQueue = class {
     }
     this.isRunning = false;
     this.abortController.abort();
-    await Promise.allSettled([
-      ...this.masterQueueConsumerLoops,
-      ...this.workerQueueConsumerLoops,
-      this.reclaimLoop
-    ]);
+    await Promise.allSettled([...this.masterQueueConsumerLoops, this.reclaimLoop]);
     this.masterQueueConsumerLoops = [];
-    this.workerQueueConsumerLoops = [];
     this.reclaimLoop = void 0;
     this.logger.info("FairQueue stopped");
   }
@@ -14360,11 +14839,12 @@ var FairQueue = class {
    */
   async close() {
     await this.stop();
+    this.batchedSpanManager.cleanupAll();
     await Promise.all([
       this.masterQueue.close(),
       this.concurrencyManager?.close(),
       this.visibilityManager.close(),
-      this.workerQueueManager?.close(),
+      this.workerQueueManager.close(),
       this.scheduler.close?.(),
       this.redis.quit()
     ]);
@@ -14402,49 +14882,148 @@ var FairQueue = class {
   // ============================================================================
   async #runMasterQueueConsumerLoop(shardId) {
     const loopId = `master-shard-${shardId}`;
+    this.batchedSpanManager.initializeLoop(loopId);
     try {
-      for await (const _ of setInterval$1(this.consumerIntervalMs, null, {
-        signal: this.abortController.signal
-      })) {
+      while (this.isRunning) {
+        if (this.abortController.signal.aborted) {
+          break;
+        }
+        let hadWork = false;
         try {
-          await this.#processMasterQueueShard(loopId, shardId);
+          hadWork = await this.batchedSpanManager.withBatchedSpan(
+            loopId,
+            async (span) => {
+              span.setAttribute("shard_id", shardId);
+              return await this.#processMasterQueueShard(loopId, shardId, span);
+            },
+            {
+              iterationSpanName: "processMasterQueueShard",
+              attributes: { shard_id: shardId }
+            }
+          );
         } catch (error) {
           this.logger.error("Master queue consumer error", {
             loopId,
             shardId,
             error: error instanceof Error ? error.message : String(error)
           });
+          this.batchedSpanManager.markForRotation(loopId);
         }
+        const waitMs = hadWork ? 1 : this.consumerIntervalMs;
+        await new Promise((resolve, reject) => {
+          const abortHandler = () => {
+            clearTimeout(timeout);
+            reject(new Error("AbortError"));
+          };
+          const timeout = setTimeout(() => {
+            this.abortController.signal.removeEventListener("abort", abortHandler);
+            resolve();
+          }, waitMs);
+          this.abortController.signal.addEventListener("abort", abortHandler, { once: true });
+        });
       }
     } catch (error) {
-      if (error instanceof Error && error.name === "AbortError") {
+      if (isAbortError(error)) {
         this.logger.debug("Master queue consumer aborted", { loopId });
+        this.batchedSpanManager.cleanup(loopId);
         return;
       }
       throw error;
+    } finally {
+      this.batchedSpanManager.cleanup(loopId);
     }
   }
-  async #processMasterQueueShard(loopId, shardId) {
+  async #processMasterQueueShard(loopId, shardId, parentSpan) {
     const masterQueueKey = this.keys.masterQueueKey(shardId);
-    const context2 = this.#createSchedulerContext();
-    const tenantQueues = await this.scheduler.selectQueues(masterQueueKey, loopId, context2);
+    const masterQueueSize = await this.masterQueue.getShardQueueCount(shardId);
+    parentSpan?.setAttribute("master_queue_size", masterQueueSize);
+    this.batchedSpanManager.incrementStat(loopId, "master_queue_size_sum", masterQueueSize);
+    const schedulerContext = this.#createSchedulerContext();
+    const tenantQueues = await this.telemetry.trace(
+      "selectQueues",
+      async (span) => {
+        span.setAttribute(FairQueueAttributes.SHARD_ID, shardId.toString());
+        span.setAttribute(FairQueueAttributes.CONSUMER_ID, loopId);
+        span.setAttribute("master_queue_size", masterQueueSize);
+        const result = await this.scheduler.selectQueues(masterQueueKey, loopId, schedulerContext);
+        span.setAttribute("tenant_count", result.length);
+        span.setAttribute(
+          "queue_count",
+          result.reduce((acc, t) => acc + t.queues.length, 0)
+        );
+        return result;
+      },
+      { kind: SpanKind.INTERNAL }
+    );
     if (tenantQueues.length === 0) {
-      return;
+      this.batchedSpanManager.incrementStat(loopId, "empty_iterations");
+      return false;
     }
+    this.batchedSpanManager.incrementStat(loopId, "tenants_selected", tenantQueues.length);
+    this.batchedSpanManager.incrementStat(
+      loopId,
+      "queues_selected",
+      tenantQueues.reduce((acc, t) => acc + t.queues.length, 0)
+    );
+    let messagesProcessed = 0;
     for (const { tenantId, queues } of tenantQueues) {
       for (const queueId of queues) {
         if (this.cooloffEnabled && this.#isInCooloff(queueId)) {
+          this.batchedSpanManager.incrementStat(loopId, "cooloff_skipped");
           continue;
         }
-        const processed = await this.#claimAndPushToWorkerQueue(loopId, queueId, tenantId, shardId);
-        if (processed) {
-          await this.scheduler.recordProcessed?.(tenantId, queueId);
-          this.#resetCooloff(queueId);
+        if (this.concurrencyManager) {
+          const isAtCapacity = await this.concurrencyManager.isAtCapacity("tenant", tenantId);
+          if (isAtCapacity) {
+            this.batchedSpanManager.incrementStat(loopId, "tenant_capacity_skipped");
+            break;
+          }
+        }
+        const processedFromQueue = await this.telemetry.trace(
+          "claimAndPushToWorkerQueue",
+          async (span) => {
+            span.setAttribute(FairQueueAttributes.QUEUE_ID, queueId);
+            span.setAttribute(FairQueueAttributes.TENANT_ID, tenantId);
+            span.setAttribute(FairQueueAttributes.SHARD_ID, shardId.toString());
+            const count = await this.#claimAndPushToWorkerQueue(loopId, queueId, tenantId, shardId);
+            span.setAttribute("messages_claimed", count);
+            return count;
+          },
+          { kind: SpanKind.INTERNAL }
+        );
+        if (processedFromQueue > 0) {
+          messagesProcessed += processedFromQueue;
+          this.batchedSpanManager.incrementStat(loopId, "messages_claimed", processedFromQueue);
+          if (this.scheduler.recordProcessedBatch) {
+            await this.telemetry.trace(
+              "recordProcessedBatch",
+              async (span) => {
+                span.setAttribute(FairQueueAttributes.QUEUE_ID, queueId);
+                span.setAttribute(FairQueueAttributes.TENANT_ID, tenantId);
+                span.setAttribute("count", processedFromQueue);
+                await this.scheduler.recordProcessedBatch(tenantId, queueId, processedFromQueue);
+              },
+              { kind: SpanKind.INTERNAL }
+            );
+          } else if (this.scheduler.recordProcessed) {
+            for (let i = 0; i < processedFromQueue; i++) {
+              await this.telemetry.trace(
+                "recordProcessed",
+                async (span) => {
+                  span.setAttribute(FairQueueAttributes.QUEUE_ID, queueId);
+                  span.setAttribute(FairQueueAttributes.TENANT_ID, tenantId);
+                  await this.scheduler.recordProcessed(tenantId, queueId);
+                },
+                { kind: SpanKind.INTERNAL }
+              );
+            }
+          }
         } else {
-          this.#incrementCooloff(queueId);
+          this.batchedSpanManager.incrementStat(loopId, "claim_skipped");
         }
       }
     }
+    return messagesProcessed > 0;
   }
   async #claimAndPushToWorkerQueue(loopId, queueId, tenantId, shardId) {
     const queueKey = this.keys.queueKey(queueId);
@@ -14455,11 +15034,14 @@ var FairQueue = class {
       tenantId,
       metadata: {}
     };
+    let maxClaimCount = this.batchClaimSize;
     if (this.concurrencyManager) {
-      const check = await this.concurrencyManager.canProcess(descriptor);
-      if (!check.allowed) {
-        return false;
+      const availableCapacity = await this.concurrencyManager.getAvailableCapacity(descriptor);
+      if (availableCapacity === 0) {
+        this.#incrementCooloff(queueId);
+        return 0;
       }
+      maxClaimCount = Math.min(maxClaimCount, availableCapacity);
     }
     if (this.globalRateLimiter) {
       const result = await this.globalRateLimiter.limit();
@@ -14471,377 +15053,209 @@ var FairQueue = class {
         }
       }
     }
-    const claimResult = await this.visibilityManager.claim(
-      queueId,
-      queueKey,
-      queueItemsKey,
-      loopId,
-      this.visibilityTimeoutMs
-    );
-    if (!claimResult.claimed || !claimResult.message) {
-      await this.redis.updateMasterQueueIfEmpty(masterQueueKey, queueKey, queueId);
-      return false;
-    }
-    const { message } = claimResult;
-    if (this.concurrencyManager) {
-      const reserved = await this.concurrencyManager.reserve(descriptor, message.messageId);
-      if (!reserved) {
-        await this.visibilityManager.release(message.messageId, queueId, queueKey, queueItemsKey);
-        return false;
+    const claimedMessages = await this.visibilityManager.claimBatch(queueId, queueKey, queueItemsKey, loopId, maxClaimCount, this.visibilityTimeoutMs);
+    if (claimedMessages.length === 0) {
+      const removed = await this.redis.updateMasterQueueIfEmpty(masterQueueKey, queueKey, queueId);
+      if (removed === 1) {
+        this.queueDescriptorCache.delete(queueId);
+        this.queueCooloffStates.delete(queueId);
       }
+      return 0;
     }
-    const workerQueueId = message.payload.workerQueue ?? queueId;
-    const messageKey = `${message.messageId}:${queueId}`;
-    await this.workerQueueManager.push(workerQueueId, messageKey);
-    return true;
-  }
-  // ============================================================================
-  // Private - Worker Queue Consumer Loop (Two-Stage)
-  // ============================================================================
-  async #runWorkerQueueConsumerLoop(consumerId) {
-    const loopId = `worker-${consumerId}`;
-    const workerQueueId = loopId;
-    try {
-      while (this.isRunning) {
-        if (!this.messageHandler) {
-          await new Promise((resolve) => setTimeout(resolve, this.consumerIntervalMs));
-          continue;
-        }
-        try {
-          const messageKey = await this.workerQueueManager.blockingPop(
-            workerQueueId,
-            this.workerQueueBlockingTimeoutSeconds,
-            this.abortController.signal
+    let processedCount = 0;
+    for (let i = 0; i < claimedMessages.length; i++) {
+      const message = claimedMessages[i];
+      if (this.concurrencyManager) {
+        const reserved = await this.concurrencyManager.reserve(descriptor, message.messageId);
+        if (!reserved) {
+          await this.visibilityManager.releaseBatch(
+            claimedMessages.slice(i),
+            queueId,
+            queueKey,
+            queueItemsKey,
+            masterQueueKey
           );
-          if (!messageKey) {
-            continue;
-          }
-          const colonIndex = messageKey.indexOf(":");
-          if (colonIndex === -1) {
-            this.logger.error("Invalid message key format", { messageKey });
-            continue;
-          }
-          const messageId = messageKey.substring(0, colonIndex);
-          const queueId = messageKey.substring(colonIndex + 1);
-          await this.#processMessageFromWorkerQueue(loopId, messageId, queueId);
-        } catch (error) {
-          if (this.abortController.signal.aborted) {
-            break;
-          }
-          this.logger.error("Worker queue consumer error", {
-            loopId,
-            error: error instanceof Error ? error.message : String(error)
-          });
+          break;
         }
       }
-    } catch (error) {
-      if (error instanceof Error && error.name === "AbortError") {
-        this.logger.debug("Worker queue consumer aborted", { loopId });
-        return;
-      }
-      throw error;
+      const workerQueueId = this.workerQueueResolver(message.payload);
+      const messageKey = `${message.messageId}:${queueId}`;
+      await this.workerQueueManager.push(workerQueueId, messageKey);
+      processedCount++;
+    }
+    if (processedCount > 0) {
+      this.#resetCooloff(queueId);
     }
+    return processedCount;
   }
-  async #processMessageFromWorkerQueue(loopId, messageId, queueId) {
+  // ============================================================================
+  // Public API - Message Lifecycle (for external consumers)
+  // ============================================================================
+  /**
+   * Get message data from in-flight storage.
+   * External consumers use this to retrieve the stored message after popping from worker queue.
+   *
+   * @param messageId - The ID of the message
+   * @param queueId - The queue ID the message belongs to
+   * @returns The stored message or null if not found
+   */
+  async getMessageData(messageId, queueId) {
     const shardId = this.masterQueue.getShardForQueue(queueId);
     const inflightDataKey = this.keys.inflightDataKey(shardId);
     const dataJson = await this.redis.hget(inflightDataKey, messageId);
     if (!dataJson) {
-      this.logger.error("Message not found in in-flight data", { messageId, queueId });
-      return;
+      return null;
     }
-    let storedMessage;
     try {
-      storedMessage = JSON.parse(dataJson);
+      return JSON.parse(dataJson);
     } catch {
       this.logger.error("Failed to parse message data", { messageId, queueId });
-      return;
+      return null;
     }
-    await this.#processMessage(loopId, storedMessage, queueId);
   }
-  // ============================================================================
-  // Private - Direct Consumer Loop (No Worker Queue)
-  // ============================================================================
-  async #runDirectConsumerLoop(consumerId, shardId) {
-    const loopId = `consumer-${consumerId}-shard-${shardId}`;
-    try {
-      for await (const _ of setInterval$1(this.consumerIntervalMs, null, {
-        signal: this.abortController.signal
-      })) {
-        if (!this.messageHandler) {
-          continue;
-        }
-        try {
-          await this.#processDirectIteration(loopId, shardId);
-        } catch (error) {
-          this.logger.error("Direct consumer iteration error", {
-            loopId,
-            error: error instanceof Error ? error.message : String(error)
-          });
-        }
-      }
-    } catch (error) {
-      if (error instanceof Error && error.name === "AbortError") {
-        this.logger.debug("Direct consumer loop aborted", { loopId });
-        return;
-      }
-      throw error;
-    }
+  /**
+   * Extend the visibility timeout for a message.
+   * External consumers should call this periodically during long-running processing.
+   *
+   * @param messageId - The ID of the message
+   * @param queueId - The queue ID the message belongs to
+   * @returns true if heartbeat was successful
+   */
+  async heartbeatMessage(messageId, queueId) {
+    return this.visibilityManager.heartbeat(messageId, queueId, this.heartbeatIntervalMs);
   }
-  async #processDirectIteration(loopId, shardId) {
+  /**
+   * Mark a message as successfully processed.
+   * This removes the message from in-flight and releases concurrency.
+   *
+   * @param messageId - The ID of the message
+   * @param queueId - The queue ID the message belongs to
+   */
+  async completeMessage(messageId, queueId) {
+    const shardId = this.masterQueue.getShardForQueue(queueId);
+    const queueKey = this.keys.queueKey(queueId);
     const masterQueueKey = this.keys.masterQueueKey(shardId);
-    const context2 = this.#createSchedulerContext();
-    const tenantQueues = await this.scheduler.selectQueues(masterQueueKey, loopId, context2);
-    if (tenantQueues.length === 0) {
-      return;
-    }
-    for (const { tenantId, queues } of tenantQueues) {
-      let availableSlots = 1;
-      if (this.concurrencyManager) {
-        const [current, limit] = await Promise.all([
-          this.concurrencyManager.getCurrentConcurrency("tenant", tenantId),
-          this.concurrencyManager.getConcurrencyLimit("tenant", tenantId)
-        ]);
-        availableSlots = Math.max(1, limit - current);
-      }
-      let slotsUsed = 0;
-      queueLoop: for (const queueId of queues) {
-        while (slotsUsed < availableSlots) {
-          if (this.cooloffEnabled && this.#isInCooloff(queueId)) {
-            break;
-          }
-          const processed = await this.#processOneMessage(loopId, queueId, tenantId, shardId);
-          if (processed) {
-            await this.scheduler.recordProcessed?.(tenantId, queueId);
-            this.#resetCooloff(queueId);
-            slotsUsed++;
-          } else {
-            this.#incrementCooloff(queueId);
-            break;
-          }
-        }
-        if (slotsUsed >= availableSlots) {
-          break queueLoop;
-        }
+    const inflightDataKey = this.keys.inflightDataKey(shardId);
+    const dataJson = await this.redis.hget(inflightDataKey, messageId);
+    let storedMessage = null;
+    if (dataJson) {
+      try {
+        storedMessage = JSON.parse(dataJson);
+      } catch {
       }
     }
+    const descriptor = storedMessage ? this.queueDescriptorCache.get(queueId) ?? {
+      id: queueId,
+      tenantId: storedMessage.tenantId,
+      metadata: storedMessage.metadata ?? {}
+    } : { id: queueId, tenantId: "", metadata: {} };
+    await this.visibilityManager.complete(messageId, queueId);
+    if (this.concurrencyManager && storedMessage) {
+      await this.concurrencyManager.release(descriptor, messageId);
+    }
+    const removed = await this.redis.updateMasterQueueIfEmpty(masterQueueKey, queueKey, queueId);
+    if (removed === 1) {
+      this.queueDescriptorCache.delete(queueId);
+      this.queueCooloffStates.delete(queueId);
+    }
+    this.telemetry.recordComplete();
+    this.logger.debug("Message completed", {
+      messageId,
+      queueId
+    });
   }
-  async #processOneMessage(loopId, queueId, tenantId, shardId) {
+  /**
+   * Release a message back to the queue for processing by another consumer.
+   * The message is placed at the back of the queue.
+   *
+   * @param messageId - The ID of the message
+   * @param queueId - The queue ID the message belongs to
+   */
+  async releaseMessage(messageId, queueId) {
+    const shardId = this.masterQueue.getShardForQueue(queueId);
     const queueKey = this.keys.queueKey(queueId);
     const queueItemsKey = this.keys.queueItemsKey(queueId);
     const masterQueueKey = this.keys.masterQueueKey(shardId);
-    const descriptor = this.queueDescriptorCache.get(queueId) ?? {
-      id: queueId,
-      tenantId,
-      metadata: {}
-    };
-    if (this.concurrencyManager) {
-      const check = await this.concurrencyManager.canProcess(descriptor);
-      if (!check.allowed) {
-        return false;
-      }
-    }
-    if (this.globalRateLimiter) {
-      const result = await this.globalRateLimiter.limit();
-      if (!result.allowed && result.resetAt) {
-        const waitMs = Math.max(0, result.resetAt - Date.now());
-        if (waitMs > 0) {
-          this.logger.debug("Global rate limit reached, waiting", { waitMs, loopId });
-          await new Promise((resolve) => setTimeout(resolve, waitMs));
-        }
+    const inflightDataKey = this.keys.inflightDataKey(shardId);
+    const dataJson = await this.redis.hget(inflightDataKey, messageId);
+    let storedMessage = null;
+    if (dataJson) {
+      try {
+        storedMessage = JSON.parse(dataJson);
+      } catch {
       }
     }
-    const claimResult = await this.visibilityManager.claim(
+    const descriptor = storedMessage ? this.queueDescriptorCache.get(queueId) ?? {
+      id: queueId,
+      tenantId: storedMessage.tenantId,
+      metadata: storedMessage.metadata ?? {}
+    } : { id: queueId, tenantId: "", metadata: {} };
+    await this.visibilityManager.release(
+      messageId,
       queueId,
       queueKey,
       queueItemsKey,
-      loopId,
-      this.visibilityTimeoutMs
+      masterQueueKey,
+      Date.now()
+      // Put at back of queue
     );
-    if (!claimResult.claimed || !claimResult.message) {
-      await this.redis.updateMasterQueueIfEmpty(masterQueueKey, queueKey, queueId);
-      return false;
-    }
-    const { message } = claimResult;
-    if (this.concurrencyManager) {
-      const reserved = await this.concurrencyManager.reserve(descriptor, message.messageId);
-      if (!reserved) {
-        await this.visibilityManager.release(message.messageId, queueId, queueKey, queueItemsKey);
-        return false;
-      }
+    if (this.concurrencyManager && storedMessage) {
+      await this.concurrencyManager.release(descriptor, messageId);
     }
-    await this.#processMessage(loopId, message.payload, queueId);
-    return true;
+    this.logger.debug("Message released", {
+      messageId,
+      queueId
+    });
   }
-  // ============================================================================
-  // Private - Message Processing
-  // ============================================================================
-  async #processMessage(loopId, storedMessage, queueId) {
-    const startTime = Date.now();
+  /**
+   * Mark a message as failed. This will trigger retry logic if configured,
+   * or move the message to the dead letter queue.
+   *
+   * @param messageId - The ID of the message
+   * @param queueId - The queue ID the message belongs to
+   * @param error - Optional error that caused the failure
+   */
+  async failMessage(messageId, queueId, error) {
+    const shardId = this.masterQueue.getShardForQueue(queueId);
     const queueKey = this.keys.queueKey(queueId);
     const queueItemsKey = this.keys.queueItemsKey(queueId);
-    const shardId = this.masterQueue.getShardForQueue(queueId);
     const masterQueueKey = this.keys.masterQueueKey(shardId);
+    const inflightDataKey = this.keys.inflightDataKey(shardId);
+    const dataJson = await this.redis.hget(inflightDataKey, messageId);
+    if (!dataJson) {
+      this.logger.error("Cannot fail message: not found in in-flight data", { messageId, queueId });
+      return;
+    }
+    let storedMessage;
+    try {
+      storedMessage = JSON.parse(dataJson);
+    } catch {
+      this.logger.error("Cannot fail message: failed to parse stored message", {
+        messageId,
+        queueId
+      });
+      return;
+    }
     const descriptor = this.queueDescriptorCache.get(queueId) ?? {
       id: queueId,
       tenantId: storedMessage.tenantId,
       metadata: storedMessage.metadata ?? {}
     };
-    let payload;
-    if (this.payloadSchema) {
-      const result = this.payloadSchema.safeParse(storedMessage.payload);
-      if (!result.success) {
-        this.logger.error("Payload validation failed on dequeue", {
-          messageId: storedMessage.id,
-          queueId,
-          error: result.error.message
-        });
-        await this.#moveToDeadLetterQueue(storedMessage, "Payload validation failed");
-        if (this.concurrencyManager) {
-          try {
-            await this.concurrencyManager.release(descriptor, storedMessage.id);
-          } catch (releaseError) {
-            this.logger.error("Failed to release concurrency slot after payload validation failure", {
-              messageId: storedMessage.id,
-              queueId,
-              error: releaseError instanceof Error ? releaseError.message : String(releaseError)
-            });
-          }
-        }
-        return;
-      }
-      payload = result.data;
-    } else {
-      payload = storedMessage.payload;
-    }
-    const queueMessage = {
-      id: storedMessage.id,
-      queueId,
-      payload,
-      timestamp: storedMessage.timestamp,
-      attempt: storedMessage.attempt,
-      metadata: storedMessage.metadata
-    };
-    const queueTime = startTime - storedMessage.timestamp;
-    this.telemetry.recordQueueTime(
-      queueTime,
-      this.telemetry.messageAttributes({
-        queueId,
-        tenantId: storedMessage.tenantId,
-        messageId: storedMessage.id
-      })
-    );
-    const handlerContext = {
-      message: queueMessage,
-      queue: descriptor,
-      consumerId: loopId,
-      heartbeat: async () => {
-        return this.visibilityManager.heartbeat(
-          storedMessage.id,
-          queueId,
-          this.heartbeatIntervalMs
-        );
-      },
-      complete: async () => {
-        await this.#completeMessage(storedMessage, queueId, queueKey, masterQueueKey, descriptor);
-        this.telemetry.recordComplete(
-          this.telemetry.messageAttributes({
-            queueId,
-            tenantId: storedMessage.tenantId,
-            messageId: storedMessage.id
-          })
-        );
-        this.telemetry.recordProcessingTime(
-          Date.now() - startTime,
-          this.telemetry.messageAttributes({
-            queueId,
-            tenantId: storedMessage.tenantId,
-            messageId: storedMessage.id
-          })
-        );
-      },
-      release: async () => {
-        await this.#releaseMessage(storedMessage, queueId, queueKey, queueItemsKey, descriptor);
-      },
-      fail: async (error) => {
-        await this.#handleMessageFailure(
-          storedMessage,
-          queueId,
-          queueKey,
-          queueItemsKey,
-          masterQueueKey,
-          descriptor,
-          error
-        );
-      }
-    };
-    try {
-      await this.telemetry.trace(
-        "processMessage",
-        async (span) => {
-          span.setAttributes({
-            [FairQueueAttributes.QUEUE_ID]: queueId,
-            [FairQueueAttributes.TENANT_ID]: storedMessage.tenantId,
-            [FairQueueAttributes.MESSAGE_ID]: storedMessage.id,
-            [FairQueueAttributes.ATTEMPT]: storedMessage.attempt,
-            [FairQueueAttributes.CONSUMER_ID]: loopId
-          });
-          await this.messageHandler(handlerContext);
-        },
-        {
-          kind: SpanKind.CONSUMER,
-          attributes: {
-            [MessagingAttributes.OPERATION]: "process"
-          }
-        }
-      );
-    } catch (error) {
-      this.logger.error("Message handler error", {
-        messageId: storedMessage.id,
-        queueId,
-        error: error instanceof Error ? error.message : String(error)
-      });
-      await handlerContext.fail(error instanceof Error ? error : new Error(String(error)));
-    }
-  }
-  async #completeMessage(storedMessage, queueId, queueKey, masterQueueKey, descriptor) {
-    this.masterQueue.getShardForQueue(queueId);
-    await this.visibilityManager.complete(storedMessage.id, queueId);
-    if (this.concurrencyManager) {
-      await this.concurrencyManager.release(descriptor, storedMessage.id);
-    }
-    await this.redis.updateMasterQueueIfEmpty(masterQueueKey, queueKey, queueId);
-    this.logger.debug("Message completed", {
-      messageId: storedMessage.id,
-      queueId
-    });
-  }
-  async #releaseMessage(storedMessage, queueId, queueKey, queueItemsKey, descriptor) {
-    await this.visibilityManager.release(
-      storedMessage.id,
+    await this.#handleMessageFailure(
+      storedMessage,
       queueId,
       queueKey,
       queueItemsKey,
-      Date.now()
-      // Put at back of queue
+      masterQueueKey,
+      descriptor,
+      error
     );
-    if (this.concurrencyManager) {
-      await this.concurrencyManager.release(descriptor, storedMessage.id);
-    }
-    this.logger.debug("Message released", {
-      messageId: storedMessage.id,
-      queueId
-    });
   }
+  // ============================================================================
+  // Private - Message Processing Helpers
+  // ============================================================================
   async #handleMessageFailure(storedMessage, queueId, queueKey, queueItemsKey, masterQueueKey, descriptor, error) {
-    this.telemetry.recordFailure(
-      this.telemetry.messageAttributes({
-        queueId,
-        tenantId: storedMessage.tenantId,
-        messageId: storedMessage.id,
-        attempt: storedMessage.attempt
-      })
-    );
+    this.telemetry.recordFailure();
     if (this.retryStrategy) {
       const nextDelay = this.retryStrategy.getNextDelay(storedMessage.attempt, error);
       if (nextDelay !== null) {
@@ -14854,20 +15268,14 @@ var FairQueue = class {
           queueId,
           queueKey,
           queueItemsKey,
+          masterQueueKey,
           Date.now() + nextDelay
         );
         await this.redis.hset(queueItemsKey, storedMessage.id, JSON.stringify(updatedMessage));
         if (this.concurrencyManager) {
           await this.concurrencyManager.release(descriptor, storedMessage.id);
         }
-        this.telemetry.recordRetry(
-          this.telemetry.messageAttributes({
-            queueId,
-            tenantId: storedMessage.tenantId,
-            messageId: storedMessage.id,
-            attempt: storedMessage.attempt + 1
-          })
-        );
+        this.telemetry.recordRetry();
         this.logger.debug("Message scheduled for retry", {
           messageId: storedMessage.id,
           queueId,
@@ -14905,14 +15313,7 @@ var FairQueue = class {
     pipeline.zadd(dlqKey, dlqMessage.deadLetteredAt, storedMessage.id);
     pipeline.hset(dlqDataKey, storedMessage.id, JSON.stringify(dlqMessage));
     await pipeline.exec();
-    this.telemetry.recordDLQ(
-      this.telemetry.messageAttributes({
-        queueId: storedMessage.queueId,
-        tenantId: storedMessage.tenantId,
-        messageId: storedMessage.id,
-        attempt: storedMessage.attempt
-      })
-    );
+    this.telemetry.recordDLQ();
     this.logger.info("Message moved to DLQ", {
       messageId: storedMessage.id,
       queueId: storedMessage.queueId,
@@ -14938,7 +15339,7 @@ var FairQueue = class {
         }
       }
     } catch (error) {
-      if (error instanceof Error && error.name === "AbortError") {
+      if (isAbortError(error)) {
         this.logger.debug("Reclaim loop aborted");
         return;
       }
@@ -14950,7 +15351,8 @@ var FairQueue = class {
     for (let shardId = 0; shardId < this.shardCount; shardId++) {
       const reclaimed = await this.visibilityManager.reclaimTimedOut(shardId, (queueId) => ({
         queueKey: this.keys.queueKey(queueId),
-        queueItemsKey: this.keys.queueItemsKey(queueId)
+        queueItemsKey: this.keys.queueItemsKey(queueId),
+        masterQueueKey: this.keys.masterQueueKey(this.masterQueue.getShardForQueue(queueId))
       }));
       totalReclaimed += reclaimed;
     }
@@ -14974,6 +15376,13 @@ var FairQueue = class {
     return false;
   }
   #incrementCooloff(queueId) {
+    if (this.queueCooloffStates.size >= this.maxCooloffStatesSize) {
+      this.logger.warn("Cooloff states cache hit size cap, clearing all entries", {
+        size: this.queueCooloffStates.size,
+        cap: this.maxCooloffStatesSize
+      });
+      this.queueCooloffStates.clear();
+    }
     const state = this.queueCooloffStates.get(queueId) ?? {
       tag: "normal",
       consecutiveFailures: 0
@@ -15116,6 +15525,6 @@ end
   }
 };
 
-export { BaseScheduler, CallbackFairQueueKeyProducer, ConcurrencyManager, CronSchema, CustomRetry, DRRScheduler, DefaultFairQueueKeyProducer, ExponentialBackoffRetry, FairQueue, FairQueueAttributes, FairQueueTelemetry, FixedDelayRetry, ImmediateRetry, LinearBackoffRetry, MasterQueue, MessagingAttributes, NoRetry, NoopScheduler, RoundRobinScheduler, SimpleQueue, VisibilityManager, WeightedScheduler, Worker, WorkerQueueManager, createDefaultRetryStrategy, defaultRetryOptions, noopTelemetry };
+export { BaseScheduler, BatchedSpanManager, CallbackFairQueueKeyProducer, ConcurrencyManager, CronSchema, CustomRetry, DRRScheduler, DefaultFairQueueKeyProducer, ExponentialBackoffRetry, FairQueue, FairQueueAttributes, FairQueueTelemetry, FixedDelayRetry, ImmediateRetry, LinearBackoffRetry, MasterQueue, MessagingAttributes, NoRetry, NoopScheduler, RoundRobinScheduler, SimpleQueue, VisibilityManager, WeightedScheduler, Worker, WorkerQueueManager, createDefaultRetryStrategy, defaultRetryOptions, isAbortError, noopTelemetry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map