@trigger.dev/redis-worker 4.3.0 → 4.3.1

package/dist/index.js

@@ -6,9 +6,11 @@ import { Logger } from '@trigger.dev/core/logger';
 import { webcrypto } from 'node:crypto';
 import '@trigger.dev/core/v3/utils/flattenAttributes';
 import { calculateNextRetryDelay } from '@trigger.dev/core/v3';
-import { shutdownManager } from '@trigger.dev/core/v3/serverOnly';
+import { shutdownManager, jumpHash } from '@trigger.dev/core/v3/serverOnly';
 import { z } from 'zod';
 import { parseExpression } from 'cron-parser';
+import { setInterval as setInterval$1 } from 'node:timers/promises';
+import seedrandom from 'seedrandom';
 
 const require = createRequire(import.meta.url || process.cwd() + '/index.js');
 var __create = Object.create;
@@ -11721,6 +11723,3399 @@ var Worker = class _Worker {
   }
 };
 
-export { CronSchema, SimpleQueue, Worker };
+// src/fair-queue/concurrency.ts
+var ConcurrencyManager = class {
+  constructor(options) {
+    this.options = options;
+    this.redis = createRedisClient(options.redis);
+    this.keys = options.keys;
+    this.groups = options.groups;
+    this.groupsByName = new Map(options.groups.map((g) => [g.name, g]));
+    this.#registerCommands();
+  }
+  redis;
+  keys;
+  groups;
+  groupsByName;
+  // ============================================================================
+  // Public Methods
+  // ============================================================================
+  /**
+   * Check if a message can be processed given all concurrency constraints.
+   * Checks all configured groups and returns the first one at capacity.
+   */
+  async canProcess(queue) {
+    for (const group of this.groups) {
+      const groupId = group.extractGroupId(queue);
+      const isAtCapacity = await this.isAtCapacity(group.name, groupId);
+      if (isAtCapacity) {
+        const state = await this.getState(group.name, groupId);
+        return {
+          allowed: false,
+          blockedBy: state
+        };
+      }
+    }
+    return { allowed: true };
+  }
+  /**
+   * Reserve concurrency slots for a message across all groups.
+   * Atomic - either all groups are reserved or none.
+   *
+   * @returns true if reservation successful, false if any group is at capacity
+   */
+  async reserve(queue, messageId) {
+    const groupData = await Promise.all(
+      this.groups.map(async (group) => {
+        const groupId = group.extractGroupId(queue);
+        const limit = await group.getLimit(groupId);
+        return {
+          key: this.keys.concurrencyKey(group.name, groupId),
+          limit: limit || group.defaultLimit
+        };
+      })
+    );
+    const keys = groupData.map((g) => g.key);
+    const limits = groupData.map((g) => g.limit.toString());
+    const result = await this.redis.reserveConcurrency(keys.length, keys, messageId, ...limits);
+    return result === 1;
+  }
+  /**
+   * Release concurrency slots for a message across all groups.
+   */
+  async release(queue, messageId) {
+    const pipeline = this.redis.pipeline();
+    for (const group of this.groups) {
+      const groupId = group.extractGroupId(queue);
+      const key = this.keys.concurrencyKey(group.name, groupId);
+      pipeline.srem(key, messageId);
+    }
+    await pipeline.exec();
+  }
+  /**
+   * Get current concurrency for a specific group.
+   */
+  async getCurrentConcurrency(groupName, groupId) {
+    const key = this.keys.concurrencyKey(groupName, groupId);
+    return await this.redis.scard(key);
+  }
+  /**
+   * Get concurrency limit for a specific group.
+   */
+  async getConcurrencyLimit(groupName, groupId) {
+    const group = this.groupsByName.get(groupName);
+    if (!group) {
+      throw new Error(`Unknown concurrency group: ${groupName}`);
+    }
+    return await group.getLimit(groupId) || group.defaultLimit;
+  }
+  /**
+   * Check if a group is at capacity.
+   */
+  async isAtCapacity(groupName, groupId) {
+    const [current, limit] = await Promise.all([
+      this.getCurrentConcurrency(groupName, groupId),
+      this.getConcurrencyLimit(groupName, groupId)
+    ]);
+    return current >= limit;
+  }
+  /**
+   * Get full state for a group.
+   */
+  async getState(groupName, groupId) {
+    const [current, limit] = await Promise.all([
+      this.getCurrentConcurrency(groupName, groupId),
+      this.getConcurrencyLimit(groupName, groupId)
+    ]);
+    return {
+      groupName,
+      groupId,
+      current,
+      limit
+    };
+  }
+  /**
+   * Get all active message IDs for a group.
+   */
+  async getActiveMessages(groupName, groupId) {
+    const key = this.keys.concurrencyKey(groupName, groupId);
+    return await this.redis.smembers(key);
+  }
+  /**
+   * Force-clear concurrency for a group (use with caution).
+   * Useful for cleanup after crashes.
+   */
+  async clearGroup(groupName, groupId) {
+    const key = this.keys.concurrencyKey(groupName, groupId);
+    await this.redis.del(key);
+  }
+  /**
+   * Remove a specific message from concurrency tracking.
+   * Useful for cleanup.
+   */
+  async removeMessage(messageId, queue) {
+    await this.release(queue, messageId);
+  }
+  /**
+   * Get configured group names.
+   */
+  getGroupNames() {
+    return this.groups.map((g) => g.name);
+  }
+  /**
+   * Close the Redis connection.
+   */
+  async close() {
+    await this.redis.quit();
+  }
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+  #registerCommands() {
+    this.redis.defineCommand("reserveConcurrency", {
+      lua: `
+local numGroups = #KEYS
+local messageId = ARGV[1]
+
+-- Check all groups first
+for i = 1, numGroups do
+  local key = KEYS[i]
+  local limit = tonumber(ARGV[1 + i])  -- Limits start at ARGV[2]
+  local current = redis.call('SCARD', key)
+  
+  if current >= limit then
+    return 0  -- At capacity
+  end
+end
+
+-- All groups have capacity, add message to all
+for i = 1, numGroups do
+  local key = KEYS[i]
+  redis.call('SADD', key, messageId)
+end
+
+return 1
+      `
+    });
+  }
+};
+var MasterQueue = class {
+  constructor(options) {
+    this.options = options;
+    this.redis = createRedisClient(options.redis);
+    this.keys = options.keys;
+    this.shardCount = Math.max(1, options.shardCount);
+    this.#registerCommands();
+  }
+  redis;
+  keys;
+  shardCount;
+  // ============================================================================
+  // Public Methods
+  // ============================================================================
+  /**
+   * Get the shard ID for a queue.
+   * Uses consistent hashing based on queue ID.
+   */
+  getShardForQueue(queueId) {
+    return this.#hashToShard(queueId);
+  }
+  /**
+   * Add a queue to its master queue shard.
+   * Updates the score to the oldest message timestamp.
+   *
+   * @param queueId - The queue identifier
+   * @param oldestMessageTimestamp - Timestamp of the oldest message in the queue
+   */
+  async addQueue(queueId, oldestMessageTimestamp) {
+    const shardId = this.getShardForQueue(queueId);
+    const masterKey = this.keys.masterQueueKey(shardId);
+    await this.redis.zadd(masterKey, oldestMessageTimestamp, queueId);
+  }
+  /**
+   * Update a queue's score in the master queue.
+   * This is typically called after dequeuing to update to the new oldest message.
+   *
+   * @param queueId - The queue identifier
+   * @param newOldestTimestamp - New timestamp of the oldest message
+   */
+  async updateQueueScore(queueId, newOldestTimestamp) {
+    const shardId = this.getShardForQueue(queueId);
+    const masterKey = this.keys.masterQueueKey(shardId);
+    await this.redis.zadd(masterKey, newOldestTimestamp, queueId);
+  }
+  /**
+   * Remove a queue from its master queue shard.
+   * Called when a queue becomes empty.
+   *
+   * @param queueId - The queue identifier
+   */
+  async removeQueue(queueId) {
+    const shardId = this.getShardForQueue(queueId);
+    const masterKey = this.keys.masterQueueKey(shardId);
+    await this.redis.zrem(masterKey, queueId);
+  }
+  /**
+   * Get queues from a shard, ordered by oldest message (lowest score first).
+   *
+   * @param shardId - The shard to query
+   * @param limit - Maximum number of queues to return (default: 1000)
+   * @param maxScore - Maximum score (timestamp) to include (default: now)
+   */
+  async getQueuesFromShard(shardId, limit = 1e3, maxScore) {
+    const masterKey = this.keys.masterQueueKey(shardId);
+    const score = maxScore ?? Date.now();
+    const results = await this.redis.zrangebyscore(
+      masterKey,
+      "-inf",
+      score,
+      "WITHSCORES",
+      "LIMIT",
+      0,
+      limit
+    );
+    const queues = [];
+    for (let i = 0; i < results.length; i += 2) {
+      const queueId = results[i];
+      const scoreStr = results[i + 1];
+      if (queueId && scoreStr) {
+        queues.push({
+          queueId,
+          score: parseFloat(scoreStr),
+          tenantId: this.keys.extractTenantId(queueId)
+        });
+      }
+    }
+    return queues;
+  }
+  /**
+   * Get the number of queues in a shard.
+   */
+  async getShardQueueCount(shardId) {
+    const masterKey = this.keys.masterQueueKey(shardId);
+    return await this.redis.zcard(masterKey);
+  }
+  /**
+   * Get total queue count across all shards.
+   */
+  async getTotalQueueCount() {
+    const counts = await Promise.all(
+      Array.from({ length: this.shardCount }, (_, i) => this.getShardQueueCount(i))
+    );
+    return counts.reduce((sum, count) => sum + count, 0);
+  }
+  /**
+   * Atomically add a queue to master queue only if queue has messages.
+   * Uses Lua script for atomicity.
+   *
+   * @param queueId - The queue identifier
+   * @param queueKey - The actual queue sorted set key
+   * @returns Whether the queue was added to the master queue
+   */
+  async addQueueIfNotEmpty(queueId, queueKey) {
+    const shardId = this.getShardForQueue(queueId);
+    const masterKey = this.keys.masterQueueKey(shardId);
+    const result = await this.redis.addQueueIfNotEmpty(masterKey, queueKey, queueId);
+    return result === 1;
+  }
+  /**
+   * Atomically remove a queue from master queue only if queue is empty.
+   * Uses Lua script for atomicity.
+   *
+   * @param queueId - The queue identifier
+   * @param queueKey - The actual queue sorted set key
+   * @returns Whether the queue was removed from the master queue
+   */
+  async removeQueueIfEmpty(queueId, queueKey) {
+    const shardId = this.getShardForQueue(queueId);
+    const masterKey = this.keys.masterQueueKey(shardId);
+    const result = await this.redis.removeQueueIfEmpty(masterKey, queueKey, queueId);
+    return result === 1;
+  }
+  /**
+   * Close the Redis connection.
+   */
+  async close() {
+    await this.redis.quit();
+  }
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+  /**
+   * Map queue ID to shard using Jump Consistent Hash.
+   * Provides better distribution than djb2 and minimal reshuffling when shard count changes.
+   */
+  #hashToShard(queueId) {
+    return jumpHash(queueId, this.shardCount);
+  }
+  #registerCommands() {
+    this.redis.defineCommand("addQueueIfNotEmpty", {
+      numberOfKeys: 2,
+      lua: `
+local masterKey = KEYS[1]
+local queueKey = KEYS[2]
+local queueId = ARGV[1]
+
+-- Check if queue has any messages
+local count = redis.call('ZCARD', queueKey)
+if count == 0 then
+  return 0
+end
+
+-- Get the oldest message timestamp (lowest score)
+local oldest = redis.call('ZRANGE', queueKey, 0, 0, 'WITHSCORES')
+if #oldest == 0 then
+  return 0
+end
+
+local score = oldest[2]
+
+-- Add to master queue with the oldest message score
+redis.call('ZADD', masterKey, score, queueId)
+return 1
+      `
+    });
+    this.redis.defineCommand("removeQueueIfEmpty", {
+      numberOfKeys: 2,
+      lua: `
+local masterKey = KEYS[1]
+local queueKey = KEYS[2]
+local queueId = ARGV[1]
+
+-- Check if queue is empty
+local count = redis.call('ZCARD', queueKey)
+if count > 0 then
+  return 0
+end
+
+-- Remove from master queue
+redis.call('ZREM', masterKey, queueId)
+return 1
+      `
+    });
+  }
+};
+
+// src/fair-queue/telemetry.ts
+var FairQueueAttributes = {
+  QUEUE_ID: "fairqueue.queue_id",
+  TENANT_ID: "fairqueue.tenant_id",
+  MESSAGE_ID: "fairqueue.message_id",
+  SHARD_ID: "fairqueue.shard_id",
+  WORKER_QUEUE: "fairqueue.worker_queue",
+  CONSUMER_ID: "fairqueue.consumer_id",
+  ATTEMPT: "fairqueue.attempt",
+  CONCURRENCY_GROUP: "fairqueue.concurrency_group",
+  MESSAGE_COUNT: "fairqueue.message_count",
+  RESULT: "fairqueue.result"
+};
+var MessagingAttributes = {
+  SYSTEM: "messaging.system",
+  OPERATION: "messaging.operation",
+  MESSAGE_ID: "messaging.message_id",
+  DESTINATION_NAME: "messaging.destination.name"
+};
+var FairQueueTelemetry = class {
+  tracer;
+  meter;
+  metrics;
+  name;
+  constructor(options) {
+    this.tracer = options.tracer;
+    this.meter = options.meter;
+    this.name = options.name ?? "fairqueue";
+    if (this.meter) {
+      this.#initializeMetrics();
+    }
+  }
+  // ============================================================================
+  // Tracing
+  // ============================================================================
+  /**
+   * Create a traced span for an operation.
+   * Returns the result of the function, or throws any error after recording it.
+   */
+  async trace(name, fn, options) {
+    if (!this.tracer) {
+      return fn(noopSpan);
+    }
+    const spanOptions = {
+      kind: options?.kind,
+      attributes: {
+        [MessagingAttributes.SYSTEM]: this.name,
+        ...options?.attributes
+      }
+    };
+    return this.tracer.startActiveSpan(`${this.name}.${name}`, spanOptions, async (span) => {
+      try {
+        const result = await fn(span);
+        return result;
+      } catch (error) {
+        if (error instanceof Error) {
+          span.recordException(error);
+        } else {
+          span.recordException(new Error(String(error)));
+        }
+        throw error;
+      } finally {
+        span.end();
+      }
+    });
+  }
+  /**
+   * Synchronous version of trace.
+   */
+  traceSync(name, fn, options) {
+    if (!this.tracer) {
+      return fn(noopSpan);
+    }
+    const spanOptions = {
+      kind: options?.kind,
+      attributes: {
+        [MessagingAttributes.SYSTEM]: this.name,
+        ...options?.attributes
+      }
+    };
+    return this.tracer.startActiveSpan(`${this.name}.${name}`, spanOptions, (span) => {
+      try {
+        return fn(span);
+      } catch (error) {
+        if (error instanceof Error) {
+          span.recordException(error);
+        } else {
+          span.recordException(new Error(String(error)));
+        }
+        throw error;
+      } finally {
+        span.end();
+      }
+    });
+  }
+  // ============================================================================
+  // Metrics
+  // ============================================================================
+  /**
+   * Record a message enqueued.
+   */
+  recordEnqueue(attributes) {
+    this.metrics?.messagesEnqueued.add(1, attributes);
+  }
+  /**
+   * Record a batch of messages enqueued.
+   */
+  recordEnqueueBatch(count, attributes) {
+    this.metrics?.messagesEnqueued.add(count, attributes);
+  }
+  /**
+   * Record a message completed successfully.
+   */
+  recordComplete(attributes) {
+    this.metrics?.messagesCompleted.add(1, attributes);
+  }
+  /**
+   * Record a message processing failure.
+   */
+  recordFailure(attributes) {
+    this.metrics?.messagesFailed.add(1, attributes);
+  }
+  /**
+   * Record a message retry.
+   */
+  recordRetry(attributes) {
+    this.metrics?.messagesRetried.add(1, attributes);
+  }
+  /**
+   * Record a message sent to DLQ.
+   */
+  recordDLQ(attributes) {
+    this.metrics?.messagesToDLQ.add(1, attributes);
+  }
+  /**
+   * Record message processing time.
+   *
+   * @param durationMs - Processing duration in milliseconds
+   */
+  recordProcessingTime(durationMs, attributes) {
+    this.metrics?.processingTime.record(durationMs, attributes);
+  }
+  /**
+   * Record time a message spent waiting in queue.
+   *
+   * @param durationMs - Queue wait time in milliseconds
+   */
+  recordQueueTime(durationMs, attributes) {
+    this.metrics?.queueTime.record(durationMs, attributes);
+  }
+  /**
+   * Register observable gauge callbacks.
+   * Call this after FairQueue is initialized to register the gauge callbacks.
+   */
+  registerGaugeCallbacks(callbacks) {
+    if (!this.metrics) return;
+    if (callbacks.getQueueLength && callbacks.observedQueues) {
+      const getQueueLength = callbacks.getQueueLength;
+      const queues = callbacks.observedQueues;
+      this.metrics.queueLength.addCallback(async (observableResult) => {
+        for (const queueId of queues) {
+          const length = await getQueueLength(queueId);
+          observableResult.observe(length, {
+            [FairQueueAttributes.QUEUE_ID]: queueId
+          });
+        }
+      });
+    }
+    if (callbacks.getMasterQueueLength && callbacks.shardCount) {
+      const getMasterQueueLength = callbacks.getMasterQueueLength;
+      const shardCount = callbacks.shardCount;
+      this.metrics.masterQueueLength.addCallback(async (observableResult) => {
+        for (let shardId = 0; shardId < shardCount; shardId++) {
+          const length = await getMasterQueueLength(shardId);
+          observableResult.observe(length, {
+            [FairQueueAttributes.SHARD_ID]: shardId.toString()
+          });
+        }
+      });
+    }
+    if (callbacks.getInflightCount && callbacks.shardCount) {
+      const getInflightCount = callbacks.getInflightCount;
+      const shardCount = callbacks.shardCount;
+      this.metrics.inflightCount.addCallback(async (observableResult) => {
+        for (let shardId = 0; shardId < shardCount; shardId++) {
+          const count = await getInflightCount(shardId);
+          observableResult.observe(count, {
+            [FairQueueAttributes.SHARD_ID]: shardId.toString()
+          });
+        }
+      });
+    }
+    if (callbacks.getDLQLength && callbacks.observedTenants) {
+      const getDLQLength = callbacks.getDLQLength;
+      const tenants = callbacks.observedTenants;
+      this.metrics.dlqLength.addCallback(async (observableResult) => {
+        for (const tenantId of tenants) {
+          const length = await getDLQLength(tenantId);
+          observableResult.observe(length, {
+            [FairQueueAttributes.TENANT_ID]: tenantId
+          });
+        }
+      });
+    }
+  }
+  // ============================================================================
+  // Helper Methods
+  // ============================================================================
+  /**
+   * Create standard attributes for a message operation.
+   */
+  messageAttributes(params) {
+    const attrs = {};
+    if (params.queueId) attrs[FairQueueAttributes.QUEUE_ID] = params.queueId;
+    if (params.tenantId) attrs[FairQueueAttributes.TENANT_ID] = params.tenantId;
+    if (params.messageId) attrs[FairQueueAttributes.MESSAGE_ID] = params.messageId;
+    if (params.attempt !== void 0) attrs[FairQueueAttributes.ATTEMPT] = params.attempt;
+    if (params.workerQueue) attrs[FairQueueAttributes.WORKER_QUEUE] = params.workerQueue;
+    if (params.consumerId) attrs[FairQueueAttributes.CONSUMER_ID] = params.consumerId;
+    return attrs;
+  }
+  /**
+   * Check if telemetry is enabled.
+   */
+  get isEnabled() {
+    return !!this.tracer || !!this.meter;
+  }
+  /**
+   * Check if tracing is enabled.
+   */
+  get hasTracer() {
+    return !!this.tracer;
+  }
+  /**
+   * Check if metrics are enabled.
+   */
+  get hasMetrics() {
+    return !!this.meter;
+  }
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+  #initializeMetrics() {
+    if (!this.meter) return;
+    this.metrics = {
+      // Counters
+      messagesEnqueued: this.meter.createCounter(`${this.name}.messages.enqueued`, {
+        description: "Number of messages enqueued",
+        unit: "messages"
+      }),
+      messagesCompleted: this.meter.createCounter(`${this.name}.messages.completed`, {
+        description: "Number of messages completed successfully",
+        unit: "messages"
+      }),
+      messagesFailed: this.meter.createCounter(`${this.name}.messages.failed`, {
+        description: "Number of messages that failed processing",
+        unit: "messages"
+      }),
+      messagesRetried: this.meter.createCounter(`${this.name}.messages.retried`, {
+        description: "Number of message retries",
+        unit: "messages"
+      }),
+      messagesToDLQ: this.meter.createCounter(`${this.name}.messages.dlq`, {
+        description: "Number of messages sent to dead letter queue",
+        unit: "messages"
+      }),
+      // Histograms
+      processingTime: this.meter.createHistogram(`${this.name}.message.processing_time`, {
+        description: "Message processing time",
+        unit: "ms"
+      }),
+      queueTime: this.meter.createHistogram(`${this.name}.message.queue_time`, {
+        description: "Time message spent waiting in queue",
+        unit: "ms"
+      }),
+      // Observable gauges
+      queueLength: this.meter.createObservableGauge(`${this.name}.queue.length`, {
+        description: "Number of messages in a queue",
+        unit: "messages"
+      }),
+      masterQueueLength: this.meter.createObservableGauge(`${this.name}.master_queue.length`, {
+        description: "Number of queues in master queue shard",
+        unit: "queues"
+      }),
+      inflightCount: this.meter.createObservableGauge(`${this.name}.inflight.count`, {
+        description: "Number of messages currently being processed",
+        unit: "messages"
+      }),
+      dlqLength: this.meter.createObservableGauge(`${this.name}.dlq.length`, {
+        description: "Number of messages in dead letter queue",
+        unit: "messages"
+      })
+    };
+  }
+};
+var noopSpan = {
+  spanContext: () => ({
+    traceId: "",
+    spanId: "",
+    traceFlags: 0
+  }),
+  setAttribute: () => noopSpan,
+  setAttributes: () => noopSpan,
+  addEvent: () => noopSpan,
+  addLink: () => noopSpan,
+  addLinks: () => noopSpan,
+  setStatus: () => noopSpan,
+  updateName: () => noopSpan,
+  end: () => {
+  },
+  isRecording: () => false,
+  recordException: () => {
+  }
+};
+var noopTelemetry = new FairQueueTelemetry({});
+var VisibilityManager = class {
+  constructor(options) {
+    this.options = options;
+    this.redis = createRedisClient(options.redis);
+    this.keys = options.keys;
+    this.shardCount = options.shardCount;
+    this.defaultTimeoutMs = options.defaultTimeoutMs;
+    this.logger = options.logger ?? {
+      debug: () => {
+      },
+      error: () => {
+      }
+    };
+    this.#registerCommands();
+  }
+  redis;
+  keys;
+  shardCount;
+  defaultTimeoutMs;
+  logger;
+  // ============================================================================
+  // Public Methods
+  // ============================================================================
+  /**
+   * Claim a message for processing.
+   * Moves the message from its queue to the in-flight set with a visibility timeout.
+   *
+   * @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 message
+   * @param timeoutMs - Visibility timeout in milliseconds
+   * @returns Claim result with the message if successful
+   */
+  async claim(queueId, queueKey, queueItemsKey, consumerId, 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.claimMessage(
+      queueKey,
+      queueItemsKey,
+      inflightKey,
+      inflightDataKey,
+      queueId,
+      consumerId,
+      deadline.toString()
+    );
+    if (!result) {
+      return { claimed: false };
+    }
+    const [messageId, payloadJson] = result;
+    try {
+      const payload = JSON.parse(payloadJson);
+      const message = {
+        messageId,
+        queueId,
+        payload,
+        deadline,
+        consumerId
+      };
+      this.logger.debug("Message claimed", {
+        messageId,
+        queueId,
+        consumerId,
+        deadline
+      });
+      return { claimed: true, message };
+    } catch (error) {
+      this.logger.error("Failed to parse claimed message", {
+        messageId,
+        queueId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      await this.#removeFromInflight(shardId, messageId, queueId);
+      return { claimed: false };
+    }
+  }
+  /**
+   * Extend the visibility timeout for a message (heartbeat).
+   *
+   * @param messageId - The message ID
+   * @param queueId - The queue ID
+   * @param extendMs - Additional milliseconds to add to the deadline
+   * @returns true if the heartbeat was successful
+   */
+  async heartbeat(messageId, queueId, extendMs) {
+    const shardId = this.#getShardForQueue(queueId);
+    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 success = result === 1;
+    if (success) {
+      this.logger.debug("Heartbeat successful", {
+        messageId,
+        queueId,
+        newDeadline
+      });
+    }
+    return success;
+  }
+  /**
+   * Mark a message as successfully processed.
+   * Removes the message from in-flight tracking.
+   *
+   * @param messageId - The message ID
+   * @param queueId - The queue ID
+   */
+  async complete(messageId, queueId) {
+    const shardId = this.#getShardForQueue(queueId);
+    await this.#removeFromInflight(shardId, messageId, queueId);
+    this.logger.debug("Message completed", {
+      messageId,
+      queueId
+    });
+  }
+  /**
+   * Release a message back to its queue.
+   * Used when processing fails or consumer wants to retry later.
+   *
+   * @param messageId - The message ID
+   * @param queueId - The queue ID
+   * @param queueKey - The Redis key for the queue
+   * @param queueItemsKey - The Redis key for the queue items hash
+   * @param score - Optional score for the message (defaults to now)
+   */
+  async release(messageId, queueId, queueKey, queueItemsKey, score) {
+    const shardId = this.#getShardForQueue(queueId);
+    const inflightKey = this.keys.inflightKey(shardId);
+    const inflightDataKey = this.keys.inflightDataKey(shardId);
+    const member = this.#makeMember(messageId, queueId);
+    const messageScore = score ?? Date.now();
+    await this.redis.releaseMessage(
+      inflightKey,
+      inflightDataKey,
+      queueKey,
+      queueItemsKey,
+      member,
+      messageId,
+      messageScore.toString()
+    );
+    this.logger.debug("Message released", {
+      messageId,
+      queueId,
+      score: messageScore
+    });
+  }
+  /**
+   * Reclaim timed-out messages from a shard.
+   * Returns messages to their original queues.
+   *
+   * @param shardId - The shard to check
+   * @param getQueueKeys - Function to get queue keys for a queue ID
+   * @returns Number of messages reclaimed
+   */
+  async reclaimTimedOut(shardId, getQueueKeys) {
+    const inflightKey = this.keys.inflightKey(shardId);
+    const inflightDataKey = this.keys.inflightDataKey(shardId);
+    const now = Date.now();
+    const timedOut = await this.redis.zrangebyscore(
+      inflightKey,
+      "-inf",
+      now,
+      "WITHSCORES",
+      "LIMIT",
+      0,
+      100
+      // Process in batches
+    );
+    let reclaimed = 0;
+    for (let i = 0; i < timedOut.length; i += 2) {
+      const member = timedOut[i];
+      const originalScore = timedOut[i + 1];
+      if (!member || !originalScore) {
+        continue;
+      }
+      const { messageId, queueId } = this.#parseMember(member);
+      const { queueKey, queueItemsKey } = getQueueKeys(queueId);
+      try {
+        const score = parseFloat(originalScore) || now;
+        await this.redis.releaseMessage(
+          inflightKey,
+          inflightDataKey,
+          queueKey,
+          queueItemsKey,
+          member,
+          messageId,
+          score.toString()
+        );
+        reclaimed++;
+        this.logger.debug("Reclaimed timed-out message", {
+          messageId,
+          queueId,
+          originalScore
+        });
+      } catch (error) {
+        this.logger.error("Failed to reclaim message", {
+          messageId,
+          queueId,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    return reclaimed;
+  }
+  /**
+   * Get all in-flight messages for a shard.
+   */
+  async getInflightMessages(shardId) {
+    const inflightKey = this.keys.inflightKey(shardId);
+    const results = await this.redis.zrange(inflightKey, 0, -1, "WITHSCORES");
+    const messages = [];
+    for (let i = 0; i < results.length; i += 2) {
+      const member = results[i];
+      const deadlineStr = results[i + 1];
+      if (!member || !deadlineStr) {
+        continue;
+      }
+      const deadline = parseFloat(deadlineStr);
+      const { messageId, queueId } = this.#parseMember(member);
+      messages.push({ messageId, queueId, deadline });
+    }
+    return messages;
+  }
+  /**
+   * Get count of in-flight messages for a shard.
+   */
+  async getInflightCount(shardId) {
+    const inflightKey = this.keys.inflightKey(shardId);
+    return await this.redis.zcard(inflightKey);
+  }
+  /**
+   * Get total in-flight count across all shards.
+   */
+  async getTotalInflightCount() {
+    const counts = await Promise.all(
+      Array.from({ length: this.shardCount }, (_, i) => this.getInflightCount(i))
+    );
+    return counts.reduce((sum, count) => sum + count, 0);
+  }
+  /**
+   * Close the Redis connection.
+   */
+  async close() {
+    await this.redis.quit();
+  }
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+  /**
+   * Map queue ID to shard using Jump Consistent Hash.
+   * Must use same algorithm as MasterQueue for consistency.
+   */
+  #getShardForQueue(queueId) {
+    return jumpHash(queueId, this.shardCount);
+  }
+  #makeMember(messageId, queueId) {
+    return `${messageId}:${queueId}`;
+  }
+  #parseMember(member) {
+    const colonIndex = member.indexOf(":");
+    if (colonIndex === -1) {
+      return { messageId: member, queueId: "" };
+    }
+    return {
+      messageId: member.substring(0, colonIndex),
+      queueId: member.substring(colonIndex + 1)
+    };
+  }
+  async #removeFromInflight(shardId, messageId, queueId) {
+    const inflightKey = this.keys.inflightKey(shardId);
+    const inflightDataKey = this.keys.inflightDataKey(shardId);
+    const member = this.#makeMember(messageId, queueId);
+    const pipeline = this.redis.pipeline();
+    pipeline.zrem(inflightKey, member);
+    pipeline.hdel(inflightDataKey, messageId);
+    await pipeline.exec();
+  }
+  #registerCommands() {
+    this.redis.defineCommand("claimMessage", {
+      numberOfKeys: 4,
+      lua: `
+local queueKey = KEYS[1]
+local queueItemsKey = KEYS[2]
+local inflightKey = KEYS[3]
+local inflightDataKey = KEYS[4]
+
+local queueId = ARGV[1]
+local consumerId = ARGV[2]
+local deadline = tonumber(ARGV[3])
+
+-- Get oldest message from queue
+local items = redis.call('ZRANGE', queueKey, 0, 0)
+if #items == 0 then
+  return nil
+end
+
+local messageId = items[1]
+
+-- Get message data
+local payload = redis.call('HGET', queueItemsKey, messageId)
+if not payload then
+  -- Message data missing, remove from queue and return nil
+  redis.call('ZREM', queueKey, messageId)
+  return nil
+end
+
+-- 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)
+
+return {messageId, payload}
+      `
+    });
+    this.redis.defineCommand("releaseMessage", {
+      numberOfKeys: 4,
+      lua: `
+local inflightKey = KEYS[1]
+local inflightDataKey = KEYS[2]
+local queueKey = KEYS[3]
+local queueItemsKey = KEYS[4]
+
+local member = ARGV[1]
+local messageId = ARGV[2]
+local score = tonumber(ARGV[3])
+
+-- Get message data from in-flight
+local payload = redis.call('HGET', inflightDataKey, messageId)
+if not payload then
+  -- Message not in in-flight or already released
+  return 0
+end
+
+-- 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)
+
+return 1
+      `
+    });
+    this.redis.defineCommand("heartbeatMessage", {
+      numberOfKeys: 1,
+      lua: `
+local inflightKey = KEYS[1]
+local member = ARGV[1]
+local newDeadline = tonumber(ARGV[2])
+
+-- Check if member exists in the in-flight set
+local score = redis.call('ZSCORE', inflightKey, member)
+if not score then
+  return 0
+end
+
+-- Update the deadline
+redis.call('ZADD', inflightKey, 'XX', newDeadline, member)
+return 1
+      `
+    });
+  }
+};
+
+// src/fair-queue/workerQueue.ts
+var WorkerQueueManager = class {
+  constructor(options) {
+    this.options = options;
+    this.redis = createRedisClient(options.redis);
+    this.keys = options.keys;
+    this.logger = options.logger ?? {
+      debug: () => {
+      },
+      error: () => {
+      }
+    };
+    this.#registerCommands();
+  }
+  redis;
+  keys;
+  logger;
+  // ============================================================================
+  // Public Methods
+  // ============================================================================
+  /**
+   * Push a message key to a worker queue.
+   * Called after claiming a message from the message queue.
+   *
+   * @param workerQueueId - The worker queue identifier
+   * @param messageKey - The message key to push (typically "messageId:queueId")
+   */
+  async push(workerQueueId, messageKey) {
+    const workerQueueKey = this.keys.workerQueueKey(workerQueueId);
+    await this.redis.rpush(workerQueueKey, messageKey);
+    this.logger.debug("Pushed to worker queue", {
+      workerQueueId,
+      workerQueueKey,
+      messageKey
+    });
+  }
+  /**
+   * Push multiple message keys to a worker queue.
+   *
+   * @param workerQueueId - The worker queue identifier
+   * @param messageKeys - The message keys to push
+   */
+  async pushBatch(workerQueueId, messageKeys) {
+    if (messageKeys.length === 0) {
+      return;
+    }
+    const workerQueueKey = this.keys.workerQueueKey(workerQueueId);
+    await this.redis.rpush(workerQueueKey, ...messageKeys);
+    this.logger.debug("Pushed batch to worker queue", {
+      workerQueueId,
+      workerQueueKey,
+      count: messageKeys.length
+    });
+  }
+  /**
+   * Blocking pop from a worker queue.
+   * Waits until a message is available or timeout expires.
+   *
+   * @param workerQueueId - The worker queue identifier
+   * @param timeoutSeconds - Maximum time to wait (0 = wait forever)
+   * @param signal - Optional abort signal to cancel waiting
+   * @returns The message key, or null if timeout
+   */
+  async blockingPop(workerQueueId, timeoutSeconds, signal) {
+    const workerQueueKey = this.keys.workerQueueKey(workerQueueId);
+    const blockingClient = this.redis.duplicate();
+    try {
+      if (signal) {
+        const cleanup = () => {
+          blockingClient.disconnect();
+        };
+        signal.addEventListener("abort", cleanup, { once: true });
+        if (signal.aborted) {
+          return null;
+        }
+      }
+      const result = await blockingClient.blpop(workerQueueKey, timeoutSeconds);
+      if (!result) {
+        return null;
+      }
+      const [, messageKey] = result;
+      this.logger.debug("Blocking pop received message", {
+        workerQueueId,
+        workerQueueKey,
+        messageKey
+      });
+      return messageKey;
+    } catch (error) {
+      if (signal?.aborted) {
+        return null;
+      }
+      this.logger.error("Blocking pop error", {
+        workerQueueId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    } finally {
+      await blockingClient.quit().catch(() => {
+      });
+    }
+  }
+  /**
+   * Non-blocking pop from a worker queue.
+   *
+   * @param workerQueueId - The worker queue identifier
+   * @returns The message key and queue length, or null if empty
+   */
+  async pop(workerQueueId) {
+    const workerQueueKey = this.keys.workerQueueKey(workerQueueId);
+    const result = await this.redis.popWithLength(workerQueueKey);
+    if (!result) {
+      return null;
+    }
+    const [messageKey, queueLength] = result;
+    this.logger.debug("Non-blocking pop received message", {
+      workerQueueId,
+      workerQueueKey,
+      messageKey,
+      queueLength
+    });
+    return { messageKey, queueLength: Number(queueLength) };
+  }
+  /**
+   * Get the current length of a worker queue.
+   */
+  async getLength(workerQueueId) {
+    const workerQueueKey = this.keys.workerQueueKey(workerQueueId);
+    return await this.redis.llen(workerQueueKey);
+  }
+  /**
+   * Peek at all messages in a worker queue without removing them.
+   * Useful for debugging and tests.
+   */
+  async peek(workerQueueId) {
+    const workerQueueKey = this.keys.workerQueueKey(workerQueueId);
+    return await this.redis.lrange(workerQueueKey, 0, -1);
+  }
+  /**
+   * Remove a specific message from the worker queue.
+   * Used when a message needs to be removed without processing.
+   *
+   * @param workerQueueId - The worker queue identifier
+   * @param messageKey - The message key to remove
+   * @returns Number of removed items
+   */
+  async remove(workerQueueId, messageKey) {
+    const workerQueueKey = this.keys.workerQueueKey(workerQueueId);
+    return await this.redis.lrem(workerQueueKey, 0, messageKey);
+  }
+  /**
+   * Clear all messages from a worker queue.
+   */
+  async clear(workerQueueId) {
+    const workerQueueKey = this.keys.workerQueueKey(workerQueueId);
+    await this.redis.del(workerQueueKey);
+  }
+  /**
+   * Close the Redis connection.
+   */
+  async close() {
+    await this.redis.quit();
+  }
+  // ============================================================================
+  // Private - Register Commands
+  // ============================================================================
+  /**
+   * Initialize custom Redis commands.
+   */
+  #registerCommands() {
+    this.redis.defineCommand("popWithLength", {
+      numberOfKeys: 1,
+      lua: `
+local workerQueueKey = KEYS[1]
+
+-- Pop the first message
+local messageKey = redis.call('LPOP', workerQueueKey)
+if not messageKey then
+  return nil
+end
+
+-- Get remaining queue length
+local queueLength = redis.call('LLEN', workerQueueKey)
+
+return {messageKey, queueLength}
+      `
+    });
+  }
+  /**
+   * Register custom commands on an external Redis client.
+   * Use this when initializing FairQueue with worker queues.
+   */
+  registerCommands(redis) {
+    redis.defineCommand("popWithLength", {
+      numberOfKeys: 1,
+      lua: `
+local workerQueueKey = KEYS[1]
+
+-- Pop the first message
+local messageKey = redis.call('LPOP', workerQueueKey)
+if not messageKey then
+  return nil
+end
+
+-- Get remaining queue length
+local queueLength = redis.call('LLEN', workerQueueKey)
+
+return {messageKey, queueLength}
+      `
+    });
+  }
+};
+
+// src/fair-queue/keyProducer.ts
+var DefaultFairQueueKeyProducer = class {
+  prefix;
+  separator;
+  constructor(options = {}) {
+    this.prefix = options.prefix ?? "fq";
+    this.separator = options.separator ?? ":";
+  }
+  // ============================================================================
+  // Master Queue Keys
+  // ============================================================================
+  masterQueueKey(shardId) {
+    return this.#buildKey("master", shardId.toString());
+  }
+  // ============================================================================
+  // Queue Keys
+  // ============================================================================
+  queueKey(queueId) {
+    return this.#buildKey("queue", queueId);
+  }
+  queueItemsKey(queueId) {
+    return this.#buildKey("queue", queueId, "items");
+  }
+  // ============================================================================
+  // Concurrency Keys
+  // ============================================================================
+  concurrencyKey(groupName, groupId) {
+    return this.#buildKey("concurrency", groupName, groupId);
+  }
+  // ============================================================================
+  // In-Flight Keys
+  // ============================================================================
+  inflightKey(shardId) {
+    return this.#buildKey("inflight", shardId.toString());
+  }
+  inflightDataKey(shardId) {
+    return this.#buildKey("inflight", shardId.toString(), "data");
+  }
+  // ============================================================================
+  // Worker Queue Keys
+  // ============================================================================
+  workerQueueKey(consumerId) {
+    return this.#buildKey("worker", consumerId);
+  }
+  // ============================================================================
+  // Dead Letter Queue Keys
+  // ============================================================================
+  deadLetterQueueKey(tenantId) {
+    return this.#buildKey("dlq", tenantId);
+  }
+  deadLetterQueueDataKey(tenantId) {
+    return this.#buildKey("dlq", tenantId, "data");
+  }
+  // ============================================================================
+  // Extraction Methods
+  // ============================================================================
+  /**
+   * Extract tenant ID from a queue ID.
+   * Default implementation assumes queue IDs are formatted as: tenant:{tenantId}:...
+   * Override this method for custom queue ID formats.
+   */
+  extractTenantId(queueId) {
+    const parts = queueId.split(this.separator);
+    if (parts.length >= 2 && parts[0] === "tenant" && parts[1]) {
+      return parts[1];
+    }
+    return parts[0] ?? "";
+  }
+  /**
+   * Extract a group ID from a queue ID.
+   * Default implementation looks for pattern: {groupName}:{groupId}:...
+   * Override this method for custom queue ID formats.
+   */
+  extractGroupId(groupName, queueId) {
+    const parts = queueId.split(this.separator);
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (parts[i] === groupName) {
+        const nextPart = parts[i + 1];
+        if (nextPart) {
+          return nextPart;
+        }
+      }
+    }
+    return "";
+  }
+  // ============================================================================
+  // Helper Methods
+  // ============================================================================
+  #buildKey(...parts) {
+    return [this.prefix, ...parts].join(this.separator);
+  }
+};
+var CallbackFairQueueKeyProducer = class extends DefaultFairQueueKeyProducer {
+  tenantExtractor;
+  groupExtractor;
+  constructor(options) {
+    super({ prefix: options.prefix, separator: options.separator });
+    this.tenantExtractor = options.extractTenantId;
+    this.groupExtractor = options.extractGroupId;
+  }
+  extractTenantId(queueId) {
+    return this.tenantExtractor(queueId);
+  }
+  extractGroupId(groupName, queueId) {
+    return this.groupExtractor(groupName, queueId);
+  }
+};
+
+// src/fair-queue/scheduler.ts
+var BaseScheduler = class {
+  /**
+   * Called after processing a message to update scheduler state.
+   * Default implementation does nothing.
+   */
+  async recordProcessed(_tenantId, _queueId) {
+  }
+  /**
+   * Initialize the scheduler.
+   * Default implementation does nothing.
+   */
+  async initialize() {
+  }
+  /**
+   * Cleanup scheduler resources.
+   * Default implementation does nothing.
+   */
+  async close() {
+  }
+  /**
+   * Helper to group queues by tenant.
+   */
+  groupQueuesByTenant(queues) {
+    const grouped = /* @__PURE__ */ new Map();
+    for (const { queueId, tenantId } of queues) {
+      const existing = grouped.get(tenantId) ?? [];
+      existing.push(queueId);
+      grouped.set(tenantId, existing);
+    }
+    return grouped;
+  }
+  /**
+   * Helper to convert grouped queues to TenantQueues array.
+   */
+  toTenantQueuesArray(grouped) {
+    return Array.from(grouped.entries()).map(([tenantId, queues]) => ({
+      tenantId,
+      queues
+    }));
+  }
+  /**
+   * Helper to filter out tenants at capacity.
+   */
+  async filterAtCapacity(tenants, context2, groupName = "tenant") {
+    const filtered = [];
+    for (const tenant of tenants) {
+      const isAtCapacity = await context2.isAtCapacity(groupName, tenant.tenantId);
+      if (!isAtCapacity) {
+        filtered.push(tenant);
+      }
+    }
+    return filtered;
+  }
+};
+var NoopScheduler = class extends BaseScheduler {
+  async selectQueues(_masterQueueShard, _consumerId, _context) {
+    return [];
+  }
+};
+
+// src/fair-queue/schedulers/drr.ts
+var DRRScheduler = class extends BaseScheduler {
+  constructor(config) {
+    super();
+    this.config = config;
+    this.redis = createRedisClient(config.redis);
+    this.keys = config.keys;
+    this.quantum = config.quantum;
+    this.maxDeficit = config.maxDeficit;
+    this.logger = config.logger ?? {
+      debug: () => {
+      },
+      error: () => {
+      }
+    };
+    this.#registerCommands();
+  }
+  redis;
+  keys;
+  quantum;
+  maxDeficit;
+  logger;
+  // ============================================================================
+  // FairScheduler Implementation
+  // ============================================================================
+  /**
+   * Select queues for processing using DRR algorithm.
+   *
+   * Algorithm:
+   * 1. Get all queues from the master shard
+   * 2. Group by tenant
+   * 3. Filter out tenants at concurrency capacity
+   * 4. Add quantum to each tenant's deficit (atomically)
+   * 5. Select queues from tenants with deficit >= 1
+   * 6. Order tenants by deficit (highest first for fairness)
+   */
+  async selectQueues(masterQueueShard, consumerId, context2) {
+    const queues = await this.#getQueuesFromShard(masterQueueShard);
+    if (queues.length === 0) {
+      return [];
+    }
+    const queuesByTenant = this.groupQueuesByTenant(
+      queues.map((q) => ({ queueId: q.queueId, tenantId: q.tenantId }))
+    );
+    const tenantIds = Array.from(queuesByTenant.keys());
+    const deficits = await this.#addQuantumToTenants(tenantIds);
+    const tenantData = await Promise.all(
+      tenantIds.map(async (tenantId, index) => {
+        const isAtCapacity = await context2.isAtCapacity("tenant", tenantId);
+        return {
+          tenantId,
+          deficit: deficits[index] ?? 0,
+          queues: queuesByTenant.get(tenantId) ?? [],
+          isAtCapacity
+        };
+      })
+    );
+    const eligibleTenants = tenantData.filter(
+      (t) => !t.isAtCapacity && t.deficit >= 1
+    );
+    const blockedTenants = tenantData.filter((t) => t.isAtCapacity);
+    if (blockedTenants.length > 0) {
+      this.logger.debug("DRR: tenants blocked by concurrency", {
+        blockedCount: blockedTenants.length,
+        blockedTenants: blockedTenants.map((t) => t.tenantId)
+      });
+    }
+    eligibleTenants.sort((a, b) => b.deficit - a.deficit);
+    this.logger.debug("DRR: queue selection complete", {
+      totalQueues: queues.length,
+      totalTenants: tenantIds.length,
+      eligibleTenants: eligibleTenants.length,
+      topTenantDeficit: eligibleTenants[0]?.deficit
+    });
+    return eligibleTenants.map((t) => ({
+      tenantId: t.tenantId,
+      queues: t.queues
+    }));
+  }
+  /**
+   * Record that a message was processed from a tenant.
+   * Decrements the tenant's deficit.
+   */
+  async recordProcessed(tenantId, _queueId) {
+    await this.#decrementDeficit(tenantId);
+  }
+  async close() {
+    await this.redis.quit();
+  }
+  // ============================================================================
+  // Public Methods for Deficit Management
+  // ============================================================================
+  /**
+   * Get the current deficit for a tenant.
+   */
+  async getDeficit(tenantId) {
+    const key = this.#deficitKey();
+    const value = await this.redis.hget(key, tenantId);
+    return value ? parseFloat(value) : 0;
+  }
+  /**
+   * Reset deficit for a tenant.
+   * Used when a tenant has no more active queues.
+   */
+  async resetDeficit(tenantId) {
+    const key = this.#deficitKey();
+    await this.redis.hdel(key, tenantId);
+  }
+  /**
+   * Get all tenant deficits.
+   */
+  async getAllDeficits() {
+    const key = this.#deficitKey();
+    const data = await this.redis.hgetall(key);
+    const result = /* @__PURE__ */ new Map();
+    for (const [tenantId, value] of Object.entries(data)) {
+      result.set(tenantId, parseFloat(value));
+    }
+    return result;
+  }
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+  #deficitKey() {
+    return `${this.keys.masterQueueKey(0).split(":")[0]}:drr:deficit`;
+  }
+  async #getQueuesFromShard(shardKey) {
+    const now = Date.now();
+    const results = await this.redis.zrangebyscore(
+      shardKey,
+      "-inf",
+      now,
+      "WITHSCORES",
+      "LIMIT",
+      0,
+      1e3
+      // Limit for performance
+    );
+    const queues = [];
+    for (let i = 0; i < results.length; i += 2) {
+      const queueId = results[i];
+      const scoreStr = results[i + 1];
+      if (queueId && scoreStr) {
+        queues.push({
+          queueId,
+          score: parseFloat(scoreStr),
+          tenantId: this.keys.extractTenantId(queueId)
+        });
+      }
+    }
+    return queues;
+  }
+  /**
+   * Add quantum to multiple tenants atomically.
+   * Returns the new deficit values.
+   */
+  async #addQuantumToTenants(tenantIds) {
+    if (tenantIds.length === 0) {
+      return [];
+    }
+    const key = this.#deficitKey();
+    const results = await this.redis.drrAddQuantum(
+      key,
+      this.quantum.toString(),
+      this.maxDeficit.toString(),
+      ...tenantIds
+    );
+    return results.map((r) => parseFloat(r));
+  }
+  /**
+   * Decrement deficit for a tenant atomically.
+   */
+  async #decrementDeficit(tenantId) {
+    const key = this.#deficitKey();
+    const result = await this.redis.drrDecrementDeficit(key, tenantId);
+    return parseFloat(result);
+  }
+  #registerCommands() {
+    this.redis.defineCommand("drrAddQuantum", {
+      numberOfKeys: 1,
+      lua: `
+local deficitKey = KEYS[1]
+local quantum = tonumber(ARGV[1])
+local maxDeficit = tonumber(ARGV[2])
+local results = {}
+
+for i = 3, #ARGV do
+  local tenantId = ARGV[i]
+  
+  -- Add quantum to deficit
+  local newDeficit = redis.call('HINCRBYFLOAT', deficitKey, tenantId, quantum)
+  newDeficit = tonumber(newDeficit)
+  
+  -- Cap at maxDeficit
+  if newDeficit > maxDeficit then
+    redis.call('HSET', deficitKey, tenantId, maxDeficit)
+    newDeficit = maxDeficit
+  end
+  
+  table.insert(results, tostring(newDeficit))
+end
+
+return results
+      `
+    });
+    this.redis.defineCommand("drrDecrementDeficit", {
+      numberOfKeys: 1,
+      lua: `
+local deficitKey = KEYS[1]
+local tenantId = ARGV[1]
+
+local newDeficit = redis.call('HINCRBYFLOAT', deficitKey, tenantId, -1)
+newDeficit = tonumber(newDeficit)
+
+-- Floor at 0
+if newDeficit < 0 then
+  redis.call('HSET', deficitKey, tenantId, 0)
+  newDeficit = 0
+end
+
+return tostring(newDeficit)
+      `
+    });
+  }
+};
+var defaultBiases = {
+  concurrencyLimitBias: 0,
+  availableCapacityBias: 0,
+  queueAgeRandomization: 0
+};
+var WeightedScheduler = class extends BaseScheduler {
+  constructor(config) {
+    super();
+    this.config = config;
+    this.redis = createRedisClient(config.redis);
+    this.keys = config.keys;
+    this.rng = seedrandom(config.seed);
+    this.biases = config.biases ?? defaultBiases;
+    this.defaultTenantLimit = config.defaultTenantConcurrencyLimit ?? 100;
+    this.masterQueueLimit = config.masterQueueLimit ?? 100;
+    this.reuseSnapshotCount = config.reuseSnapshotCount ?? 0;
+    this.maximumTenantCount = config.maximumTenantCount ?? 0;
+  }
+  redis;
+  keys;
+  rng;
+  biases;
+  defaultTenantLimit;
+  masterQueueLimit;
+  reuseSnapshotCount;
+  maximumTenantCount;
+  // Snapshot cache
+  snapshotCache = /* @__PURE__ */ new Map();
+  // ============================================================================
+  // FairScheduler Implementation
+  // ============================================================================
+  async selectQueues(masterQueueShard, consumerId, context2) {
+    const snapshot = await this.#getOrCreateSnapshot(
+      masterQueueShard,
+      consumerId,
+      context2
+    );
+    if (snapshot.queues.length === 0) {
+      return [];
+    }
+    const shuffledTenants = this.#shuffleTenantsByWeight(snapshot);
+    return shuffledTenants.map((tenantId) => ({
+      tenantId,
+      queues: this.#orderQueuesForTenant(snapshot, tenantId)
+    }));
+  }
+  async close() {
+    this.snapshotCache.clear();
+    await this.redis.quit();
+  }
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+  async #getOrCreateSnapshot(masterQueueShard, consumerId, context2) {
+    const cacheKey = `${masterQueueShard}:${consumerId}`;
+    if (this.reuseSnapshotCount > 0) {
+      const cached = this.snapshotCache.get(cacheKey);
+      if (cached && cached.reuseCount < this.reuseSnapshotCount) {
+        this.snapshotCache.set(cacheKey, {
+          snapshot: cached.snapshot,
+          reuseCount: cached.reuseCount + 1
+        });
+        return cached.snapshot;
+      }
+    }
+    const snapshot = await this.#createSnapshot(masterQueueShard, context2);
+    if (this.reuseSnapshotCount > 0) {
+      this.snapshotCache.set(cacheKey, { snapshot, reuseCount: 0 });
+    }
+    return snapshot;
+  }
+  async #createSnapshot(masterQueueShard, context2) {
+    const now = Date.now();
+    let rawQueues = await this.#getQueuesFromShard(masterQueueShard, now);
+    if (rawQueues.length === 0) {
+      return { id: crypto.randomUUID(), tenants: /* @__PURE__ */ new Map(), queues: [] };
+    }
+    if (this.maximumTenantCount > 0) {
+      rawQueues = this.#selectTopTenantQueues(rawQueues);
+    }
+    const tenantIds = /* @__PURE__ */ new Set();
+    const queuesByTenant = /* @__PURE__ */ new Map();
+    for (const queue of rawQueues) {
+      tenantIds.add(queue.tenantId);
+      const tenantQueues = queuesByTenant.get(queue.tenantId) ?? [];
+      tenantQueues.push({
+        queueId: queue.queueId,
+        age: now - queue.score
+      });
+      queuesByTenant.set(queue.tenantId, tenantQueues);
+    }
+    const tenants = /* @__PURE__ */ new Map();
+    for (const tenantId of tenantIds) {
+      const [current, limit] = await Promise.all([
+        context2.getCurrentConcurrency("tenant", tenantId),
+        context2.getConcurrencyLimit("tenant", tenantId)
+      ]);
+      if (current >= limit) {
+        continue;
+      }
+      tenants.set(tenantId, {
+        tenantId,
+        concurrency: { current, limit },
+        queues: queuesByTenant.get(tenantId) ?? []
+      });
+    }
+    const queues = rawQueues.filter((q) => tenants.has(q.tenantId)).map((q) => ({
+      queueId: q.queueId,
+      tenantId: q.tenantId,
+      age: now - q.score
+    }));
+    return {
+      id: crypto.randomUUID(),
+      tenants,
+      queues
+    };
+  }
+  async #getQueuesFromShard(shardKey, maxScore) {
+    const results = await this.redis.zrangebyscore(
+      shardKey,
+      "-inf",
+      maxScore,
+      "WITHSCORES",
+      "LIMIT",
+      0,
+      this.masterQueueLimit
+    );
+    const queues = [];
+    for (let i = 0; i < results.length; i += 2) {
+      const queueId = results[i];
+      const scoreStr = results[i + 1];
+      if (queueId && scoreStr) {
+        queues.push({
+          queueId,
+          score: parseFloat(scoreStr),
+          tenantId: this.keys.extractTenantId(queueId)
+        });
+      }
+    }
+    return queues;
+  }
+  #selectTopTenantQueues(queues) {
+    const queuesByTenant = /* @__PURE__ */ new Map();
+    for (const queue of queues) {
+      const tenantQueues = queuesByTenant.get(queue.tenantId) ?? [];
+      tenantQueues.push(queue);
+      queuesByTenant.set(queue.tenantId, tenantQueues);
+    }
+    const tenantAges = Array.from(queuesByTenant.entries()).map(([tenantId, tQueues]) => {
+      const avgAge = tQueues.reduce((sum, q) => sum + q.score, 0) / tQueues.length;
+      return { tenantId, avgAge };
+    });
+    const maxAge = Math.max(...tenantAges.map((t) => t.avgAge));
+    const weightedTenants = maxAge === 0 ? tenantAges.map((t) => ({
+      tenantId: t.tenantId,
+      weight: 1 / tenantAges.length
+    })) : tenantAges.map((t) => ({
+      tenantId: t.tenantId,
+      weight: t.avgAge / maxAge
+    }));
+    const selectedTenants = /* @__PURE__ */ new Set();
+    let remaining = [...weightedTenants];
+    let totalWeight = remaining.reduce((sum, t) => sum + t.weight, 0);
+    while (selectedTenants.size < this.maximumTenantCount && remaining.length > 0) {
+      let random = this.rng() * totalWeight;
+      let index = 0;
+      while (random > 0 && index < remaining.length) {
+        const item = remaining[index];
+        if (item) {
+          random -= item.weight;
+        }
+        index++;
+      }
+      index = Math.max(0, index - 1);
+      const selected = remaining[index];
+      if (selected) {
+        selectedTenants.add(selected.tenantId);
+        totalWeight -= selected.weight;
+        remaining.splice(index, 1);
+      }
+    }
+    return queues.filter((q) => selectedTenants.has(q.tenantId));
+  }
+  #shuffleTenantsByWeight(snapshot) {
+    const tenantIds = Array.from(snapshot.tenants.keys());
+    if (tenantIds.length === 0) {
+      return [];
+    }
+    const { concurrencyLimitBias, availableCapacityBias } = this.biases;
+    if (concurrencyLimitBias === 0 && availableCapacityBias === 0) {
+      return this.#shuffle(tenantIds);
+    }
+    const maxLimit = Math.max(
+      ...tenantIds.map((id) => snapshot.tenants.get(id).concurrency.limit)
+    );
+    const weightedTenants = tenantIds.map((tenantId) => {
+      const tenant = snapshot.tenants.get(tenantId);
+      let weight = 1;
+      if (concurrencyLimitBias > 0) {
+        const normalizedLimit = maxLimit > 0 ? tenant.concurrency.limit / maxLimit : 0;
+        weight *= 1 + Math.pow(normalizedLimit * concurrencyLimitBias, 2);
+      }
+      if (availableCapacityBias > 0) {
+        const usedPercentage = tenant.concurrency.limit > 0 ? tenant.concurrency.current / tenant.concurrency.limit : 1;
+        const availableBonus = 1 - usedPercentage;
+        weight *= 1 + Math.pow(availableBonus * availableCapacityBias, 2);
+      }
+      return { tenantId, weight };
+    });
+    return this.#weightedShuffle(weightedTenants);
+  }
+  #orderQueuesForTenant(snapshot, tenantId) {
+    const tenant = snapshot.tenants.get(tenantId);
+    if (!tenant || tenant.queues.length === 0) {
+      return [];
+    }
+    const queues = [...tenant.queues];
+    const { queueAgeRandomization } = this.biases;
+    if (queueAgeRandomization === 0) {
+      return queues.sort((a, b) => b.age - a.age).map((q) => q.queueId);
+    }
+    const maxAge = Math.max(...queues.map((q) => q.age));
+    const ageDenom = maxAge === 0 ? 1 : maxAge;
+    const weightedQueues = queues.map((q) => ({
+      queue: q,
+      weight: 1 + q.age / ageDenom * queueAgeRandomization
+    }));
+    const result = [];
+    let remaining = [...weightedQueues];
+    let totalWeight = remaining.reduce((sum, q) => sum + q.weight, 0);
+    while (remaining.length > 0) {
+      let random = this.rng() * totalWeight;
+      let index = 0;
+      while (random > 0 && index < remaining.length) {
+        const item = remaining[index];
+        if (item) {
+          random -= item.weight;
+        }
+        index++;
+      }
+      index = Math.max(0, index - 1);
+      const selected = remaining[index];
+      if (selected) {
+        result.push(selected.queue.queueId);
+        totalWeight -= selected.weight;
+        remaining.splice(index, 1);
+      }
+    }
+    return result;
+  }
+  #shuffle(array) {
+    const result = [...array];
+    for (let i = result.length - 1; i > 0; i--) {
+      const j = Math.floor(this.rng() * (i + 1));
+      const temp = result[i];
+      const swapValue = result[j];
+      if (temp !== void 0 && swapValue !== void 0) {
+        result[i] = swapValue;
+        result[j] = temp;
+      }
+    }
+    return result;
+  }
+  #weightedShuffle(items) {
+    const result = [];
+    let remaining = [...items];
+    let totalWeight = remaining.reduce((sum, item) => sum + item.weight, 0);
+    while (remaining.length > 0) {
+      let random = this.rng() * totalWeight;
+      let index = 0;
+      while (random > 0 && index < remaining.length) {
+        const item = remaining[index];
+        if (item) {
+          random -= item.weight;
+        }
+        index++;
+      }
+      index = Math.max(0, index - 1);
+      const selected = remaining[index];
+      if (selected) {
+        result.push(selected.tenantId);
+        totalWeight -= selected.weight;
+        remaining.splice(index, 1);
+      }
+    }
+    return result;
+  }
+};
+
+// src/fair-queue/schedulers/roundRobin.ts
+var RoundRobinScheduler = class extends BaseScheduler {
+  constructor(config) {
+    super();
+    this.config = config;
+    this.redis = createRedisClient(config.redis);
+    this.keys = config.keys;
+    this.masterQueueLimit = config.masterQueueLimit ?? 1e3;
+  }
+  redis;
+  keys;
+  masterQueueLimit;
+  // ============================================================================
+  // FairScheduler Implementation
+  // ============================================================================
+  async selectQueues(masterQueueShard, consumerId, context2) {
+    const now = Date.now();
+    const queues = await this.#getQueuesFromShard(masterQueueShard, now);
+    if (queues.length === 0) {
+      return [];
+    }
+    const queuesByTenant = /* @__PURE__ */ new Map();
+    const tenantOrder = [];
+    for (const queue of queues) {
+      if (!queuesByTenant.has(queue.tenantId)) {
+        queuesByTenant.set(queue.tenantId, []);
+        tenantOrder.push(queue.tenantId);
+      }
+      queuesByTenant.get(queue.tenantId).push(queue.queueId);
+    }
+    const lastServedIndex = await this.#getLastServedIndex(masterQueueShard);
+    const rotatedTenants = this.#rotateArray(tenantOrder, lastServedIndex);
+    const eligibleTenants = [];
+    for (const tenantId of rotatedTenants) {
+      const isAtCapacity = await context2.isAtCapacity("tenant", tenantId);
+      if (!isAtCapacity) {
+        const tenantQueues = queuesByTenant.get(tenantId) ?? [];
+        eligibleTenants.push({
+          tenantId,
+          queues: tenantQueues
+        });
+      }
+    }
+    const firstEligible = eligibleTenants[0];
+    if (firstEligible) {
+      const firstTenantIndex = tenantOrder.indexOf(firstEligible.tenantId);
+      await this.#setLastServedIndex(masterQueueShard, firstTenantIndex + 1);
+    }
+    return eligibleTenants;
+  }
+  async close() {
+    await this.redis.quit();
+  }
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+  async #getQueuesFromShard(shardKey, maxScore) {
+    const results = await this.redis.zrangebyscore(
+      shardKey,
+      "-inf",
+      maxScore,
+      "WITHSCORES",
+      "LIMIT",
+      0,
+      this.masterQueueLimit
+    );
+    const queues = [];
+    for (let i = 0; i < results.length; i += 2) {
+      const queueId = results[i];
+      const scoreStr = results[i + 1];
+      if (queueId && scoreStr) {
+        queues.push({
+          queueId,
+          score: parseFloat(scoreStr),
+          tenantId: this.keys.extractTenantId(queueId)
+        });
+      }
+    }
+    return queues;
+  }
+  #lastServedKey(shardKey) {
+    return `${shardKey}:rr:lastServed`;
+  }
+  async #getLastServedIndex(shardKey) {
+    const key = this.#lastServedKey(shardKey);
+    const value = await this.redis.get(key);
+    return value ? parseInt(value, 10) : 0;
+  }
+  async #setLastServedIndex(shardKey, index) {
+    const key = this.#lastServedKey(shardKey);
+    await this.redis.set(key, index.toString());
+  }
+  #rotateArray(array, startIndex) {
+    if (array.length === 0) return [];
+    const normalizedIndex = startIndex % array.length;
+    return [...array.slice(normalizedIndex), ...array.slice(0, normalizedIndex)];
+  }
+};
+var ExponentialBackoffRetry = class {
+  maxAttempts;
+  options;
+  constructor(options) {
+    this.options = {
+      maxAttempts: options?.maxAttempts ?? 12,
+      factor: options?.factor ?? 2,
+      minTimeoutInMs: options?.minTimeoutInMs ?? 1e3,
+      maxTimeoutInMs: options?.maxTimeoutInMs ?? 36e5,
+      // 1 hour
+      randomize: options?.randomize ?? true
+    };
+    this.maxAttempts = this.options.maxAttempts ?? 12;
+  }
+  getNextDelay(attempt, _error) {
+    if (attempt >= this.maxAttempts) {
+      return null;
+    }
+    const delay = calculateNextRetryDelay(this.options, attempt);
+    return delay ?? null;
+  }
+};
+var FixedDelayRetry = class {
+  maxAttempts;
+  delayMs;
+  constructor(options) {
+    this.maxAttempts = options.maxAttempts;
+    this.delayMs = options.delayMs;
+  }
+  getNextDelay(attempt, _error) {
+    if (attempt >= this.maxAttempts) {
+      return null;
+    }
+    return this.delayMs;
+  }
+};
+var LinearBackoffRetry = class {
+  maxAttempts;
+  baseDelayMs;
+  maxDelayMs;
+  constructor(options) {
+    this.maxAttempts = options.maxAttempts;
+    this.baseDelayMs = options.baseDelayMs;
+    this.maxDelayMs = options.maxDelayMs ?? options.baseDelayMs * options.maxAttempts;
+  }
+  getNextDelay(attempt, _error) {
+    if (attempt >= this.maxAttempts) {
+      return null;
+    }
+    const delay = this.baseDelayMs * attempt;
+    return Math.min(delay, this.maxDelayMs);
+  }
+};
+var NoRetry = class {
+  maxAttempts = 1;
+  getNextDelay(_attempt, _error) {
+    return null;
+  }
+};
+var ImmediateRetry = class {
+  maxAttempts;
+  constructor(maxAttempts) {
+    this.maxAttempts = maxAttempts;
+  }
+  getNextDelay(attempt, _error) {
+    if (attempt >= this.maxAttempts) {
+      return null;
+    }
+    return 0;
+  }
+};
+var CustomRetry = class {
+  maxAttempts;
+  calculateDelay;
+  constructor(options) {
+    this.maxAttempts = options.maxAttempts;
+    this.calculateDelay = options.calculateDelay;
+  }
+  getNextDelay(attempt, error) {
+    if (attempt >= this.maxAttempts) {
+      return null;
+    }
+    return this.calculateDelay(attempt, error);
+  }
+};
+var defaultRetryOptions = {
+  maxAttempts: 12,
+  factor: 2,
+  minTimeoutInMs: 1e3,
+  maxTimeoutInMs: 36e5,
+  randomize: true
+};
+function createDefaultRetryStrategy() {
+  return new ExponentialBackoffRetry(defaultRetryOptions);
+}
+
+// src/fair-queue/index.ts
+var FairQueue = class {
+  constructor(options) {
+    this.options = options;
+    this.redis = createRedisClient(options.redis);
+    this.keys = options.keys;
+    this.scheduler = options.scheduler;
+    this.logger = options.logger ?? new Logger("FairQueue", "info");
+    this.abortController = new AbortController();
+    this.payloadSchema = options.payloadSchema;
+    this.validateOnEnqueue = options.validateOnEnqueue ?? false;
+    this.retryStrategy = options.retry?.strategy;
+    this.deadLetterQueueEnabled = options.retry?.deadLetterQueue ?? true;
+    this.shardCount = options.shardCount ?? 1;
+    this.consumerCount = options.consumerCount ?? 1;
+    this.consumerIntervalMs = options.consumerIntervalMs ?? 100;
+    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.cooloffEnabled = options.cooloff?.enabled ?? true;
+    this.cooloffThreshold = options.cooloff?.threshold ?? 10;
+    this.cooloffPeriodMs = options.cooloff?.periodMs ?? 1e4;
+    this.globalRateLimiter = options.globalRateLimiter;
+    this.telemetry = new FairQueueTelemetry({
+      tracer: options.tracer,
+      meter: options.meter,
+      name: options.name ?? "fairqueue"
+    });
+    this.masterQueue = new MasterQueue({
+      redis: options.redis,
+      keys: options.keys,
+      shardCount: this.shardCount
+    });
+    if (options.concurrencyGroups && options.concurrencyGroups.length > 0) {
+      this.concurrencyManager = new ConcurrencyManager({
+        redis: options.redis,
+        keys: options.keys,
+        groups: options.concurrencyGroups
+      });
+    }
+    this.visibilityManager = new VisibilityManager({
+      redis: options.redis,
+      keys: options.keys,
+      shardCount: this.shardCount,
+      defaultTimeoutMs: this.visibilityTimeoutMs,
+      logger: {
+        debug: (msg, ctx) => this.logger.debug(msg, ctx),
+        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.#registerCommands();
+    if (options.startConsumers !== false) {
+      this.start();
+    }
+  }
+  redis;
+  keys;
+  scheduler;
+  masterQueue;
+  concurrencyManager;
+  visibilityManager;
+  workerQueueManager;
+  telemetry;
+  logger;
+  // Configuration
+  payloadSchema;
+  validateOnEnqueue;
+  retryStrategy;
+  deadLetterQueueEnabled;
+  shardCount;
+  consumerCount;
+  consumerIntervalMs;
+  visibilityTimeoutMs;
+  heartbeatIntervalMs;
+  reclaimIntervalMs;
+  workerQueueEnabled;
+  workerQueueBlockingTimeoutSeconds;
+  workerQueueResolver;
+  // Cooloff state
+  cooloffEnabled;
+  cooloffThreshold;
+  cooloffPeriodMs;
+  queueCooloffStates = /* @__PURE__ */ new Map();
+  // Global rate limiter
+  globalRateLimiter;
+  // Runtime state
+  messageHandler;
+  isRunning = false;
+  abortController;
+  masterQueueConsumerLoops = [];
+  workerQueueConsumerLoops = [];
+  reclaimLoop;
+  // Queue descriptor cache for message processing
+  queueDescriptorCache = /* @__PURE__ */ new Map();
+  // ============================================================================
+  // Public API - Telemetry
+  // ============================================================================
+  /**
+   * Register observable gauge callbacks for telemetry.
+   * Call this after FairQueue is created to enable gauge metrics.
+   *
+   * @param options.observedTenants - List of tenant IDs to observe for DLQ metrics
+   */
+  registerTelemetryGauges(options) {
+    this.telemetry.registerGaugeCallbacks({
+      getMasterQueueLength: async (shardId) => {
+        return await this.masterQueue.getShardQueueCount(shardId);
+      },
+      getInflightCount: async (shardId) => {
+        return await this.visibilityManager.getInflightCount(shardId);
+      },
+      getDLQLength: async (tenantId) => {
+        return await this.getDeadLetterQueueLength(tenantId);
+      },
+      shardCount: this.shardCount,
+      observedTenants: options?.observedTenants
+    });
+  }
+  // ============================================================================
+  // Public API - Message Handler
+  // ============================================================================
+  /**
+   * Set the message handler for processing dequeued messages.
+   */
+  onMessage(handler) {
+    this.messageHandler = handler;
+  }
+  // ============================================================================
+  // Public API - Enqueueing
+  // ============================================================================
+  /**
+   * Enqueue a single message to a queue.
+   */
+  async enqueue(options) {
+    return this.telemetry.trace(
+      "enqueue",
+      async (span) => {
+        const messageId = options.messageId ?? nanoid();
+        const timestamp = options.timestamp ?? Date.now();
+        const queueKey = this.keys.queueKey(options.queueId);
+        const queueItemsKey = this.keys.queueItemsKey(options.queueId);
+        const shardId = this.masterQueue.getShardForQueue(options.queueId);
+        const masterQueueKey = this.keys.masterQueueKey(shardId);
+        if (this.validateOnEnqueue && this.payloadSchema) {
+          const result = this.payloadSchema.safeParse(options.payload);
+          if (!result.success) {
+            throw new Error(`Payload validation failed: ${result.error.message}`);
+          }
+        }
+        const descriptor = {
+          id: options.queueId,
+          tenantId: options.tenantId,
+          metadata: options.metadata ?? {}
+        };
+        this.queueDescriptorCache.set(options.queueId, descriptor);
+        const storedMessage = {
+          id: messageId,
+          queueId: options.queueId,
+          tenantId: options.tenantId,
+          payload: options.payload,
+          timestamp,
+          attempt: 1,
+          workerQueue: this.workerQueueResolver ? this.workerQueueResolver({
+            id: messageId,
+            queueId: options.queueId,
+            tenantId: options.tenantId,
+            payload: options.payload,
+            timestamp,
+            attempt: 1,
+            metadata: options.metadata
+          }) : options.queueId,
+          metadata: options.metadata
+        };
+        await this.redis.enqueueMessageAtomic(
+          queueKey,
+          queueItemsKey,
+          masterQueueKey,
+          options.queueId,
+          messageId,
+          timestamp.toString(),
+          JSON.stringify(storedMessage)
+        );
+        span.setAttributes({
+          [FairQueueAttributes.QUEUE_ID]: options.queueId,
+          [FairQueueAttributes.TENANT_ID]: options.tenantId,
+          [FairQueueAttributes.MESSAGE_ID]: messageId,
+          [FairQueueAttributes.SHARD_ID]: shardId.toString()
+        });
+        this.telemetry.recordEnqueue(
+          this.telemetry.messageAttributes({
+            queueId: options.queueId,
+            tenantId: options.tenantId,
+            messageId
+          })
+        );
+        this.logger.debug("Message enqueued", {
+          queueId: options.queueId,
+          messageId,
+          timestamp
+        });
+        return messageId;
+      },
+      {
+        kind: SpanKind.PRODUCER,
+        attributes: {
+          [MessagingAttributes.OPERATION]: "publish"
+        }
+      }
+    );
+  }
+  /**
+   * Enqueue multiple messages to a queue.
+   */
+  async enqueueBatch(options) {
+    return this.telemetry.trace(
+      "enqueueBatch",
+      async (span) => {
+        const queueKey = this.keys.queueKey(options.queueId);
+        const queueItemsKey = this.keys.queueItemsKey(options.queueId);
+        const shardId = this.masterQueue.getShardForQueue(options.queueId);
+        const masterQueueKey = this.keys.masterQueueKey(shardId);
+        const now = Date.now();
+        const descriptor = {
+          id: options.queueId,
+          tenantId: options.tenantId,
+          metadata: options.metadata ?? {}
+        };
+        this.queueDescriptorCache.set(options.queueId, descriptor);
+        const messageIds = [];
+        const args = [];
+        for (const message of options.messages) {
+          const messageId = message.messageId ?? nanoid();
+          const timestamp = message.timestamp ?? now;
+          if (this.validateOnEnqueue && this.payloadSchema) {
+            const result = this.payloadSchema.safeParse(message.payload);
+            if (!result.success) {
+              throw new Error(
+                `Payload validation failed for message ${messageId}: ${result.error.message}`
+              );
+            }
+          }
+          const storedMessage = {
+            id: messageId,
+            queueId: options.queueId,
+            tenantId: options.tenantId,
+            payload: message.payload,
+            timestamp,
+            attempt: 1,
+            workerQueue: this.workerQueueResolver ? this.workerQueueResolver({
+              id: messageId,
+              queueId: options.queueId,
+              tenantId: options.tenantId,
+              payload: message.payload,
+              timestamp,
+              attempt: 1,
+              metadata: options.metadata
+            }) : options.queueId,
+            metadata: options.metadata
+          };
+          messageIds.push(messageId);
+          args.push(messageId, timestamp.toString(), JSON.stringify(storedMessage));
+        }
+        await this.redis.enqueueBatchAtomic(
+          queueKey,
+          queueItemsKey,
+          masterQueueKey,
+          options.queueId,
+          ...args
+        );
+        span.setAttributes({
+          [FairQueueAttributes.QUEUE_ID]: options.queueId,
+          [FairQueueAttributes.TENANT_ID]: options.tenantId,
+          [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.logger.debug("Batch enqueued", {
+          queueId: options.queueId,
+          messageCount: messageIds.length
+        });
+        return messageIds;
+      },
+      {
+        kind: SpanKind.PRODUCER,
+        attributes: {
+          [MessagingAttributes.OPERATION]: "publish"
+        }
+      }
+    );
+  }
+  // ============================================================================
+  // Public API - Dead Letter Queue
+  // ============================================================================
+  /**
+   * Get messages from the dead letter queue for a tenant.
+   */
+  async getDeadLetterMessages(tenantId, limit = 100) {
+    if (!this.deadLetterQueueEnabled) {
+      return [];
+    }
+    const dlqKey = this.keys.deadLetterQueueKey(tenantId);
+    const dlqDataKey = this.keys.deadLetterQueueDataKey(tenantId);
+    const results = await this.redis.zrange(dlqKey, 0, limit - 1, "WITHSCORES");
+    const messages = [];
+    for (let i = 0; i < results.length; i += 2) {
+      const messageId = results[i];
+      const deadLetteredAtStr = results[i + 1];
+      if (!messageId || !deadLetteredAtStr) continue;
+      const dataJson = await this.redis.hget(dlqDataKey, messageId);
+      if (!dataJson) continue;
+      try {
+        const data = JSON.parse(dataJson);
+        data.deadLetteredAt = parseFloat(deadLetteredAtStr);
+        messages.push(data);
+      } catch {
+        this.logger.error("Failed to parse DLQ message", { messageId, tenantId });
+      }
+    }
+    return messages;
+  }
+  /**
+   * Redrive a message from DLQ back to its original queue.
+   */
+  async redriveMessage(tenantId, messageId) {
+    if (!this.deadLetterQueueEnabled) {
+      return false;
+    }
+    return this.telemetry.trace(
+      "redriveMessage",
+      async (span) => {
+        const dlqKey = this.keys.deadLetterQueueKey(tenantId);
+        const dlqDataKey = this.keys.deadLetterQueueDataKey(tenantId);
+        const dataJson = await this.redis.hget(dlqDataKey, messageId);
+        if (!dataJson) {
+          return false;
+        }
+        const dlqMessage = JSON.parse(dataJson);
+        await this.enqueue({
+          queueId: dlqMessage.queueId,
+          tenantId: dlqMessage.tenantId,
+          payload: dlqMessage.payload,
+          messageId: dlqMessage.id,
+          timestamp: Date.now()
+        });
+        const pipeline = this.redis.pipeline();
+        pipeline.zrem(dlqKey, messageId);
+        pipeline.hdel(dlqDataKey, messageId);
+        await pipeline.exec();
+        span.setAttributes({
+          [FairQueueAttributes.TENANT_ID]: tenantId,
+          [FairQueueAttributes.MESSAGE_ID]: messageId
+        });
+        this.logger.info("Redrived message from DLQ", { tenantId, messageId });
+        return true;
+      },
+      {
+        kind: SpanKind.PRODUCER,
+        attributes: {
+          [MessagingAttributes.OPERATION]: "redrive"
+        }
+      }
+    );
+  }
+  /**
+   * Redrive all messages from DLQ back to their original queues.
+   */
+  async redriveAll(tenantId) {
+    const messages = await this.getDeadLetterMessages(tenantId, 1e3);
+    let count = 0;
+    for (const message of messages) {
+      const success = await this.redriveMessage(tenantId, message.id);
+      if (success) count++;
+    }
+    return count;
+  }
+  /**
+   * Purge all messages from a tenant's DLQ.
+   */
+  async purgeDeadLetterQueue(tenantId) {
+    if (!this.deadLetterQueueEnabled) {
+      return 0;
+    }
+    const dlqKey = this.keys.deadLetterQueueKey(tenantId);
+    const dlqDataKey = this.keys.deadLetterQueueDataKey(tenantId);
+    const count = await this.redis.zcard(dlqKey);
+    const pipeline = this.redis.pipeline();
+    pipeline.del(dlqKey);
+    pipeline.del(dlqDataKey);
+    await pipeline.exec();
+    this.logger.info("Purged DLQ", { tenantId, count });
+    return count;
+  }
+  /**
+   * Get the number of messages in a tenant's DLQ.
+   */
+  async getDeadLetterQueueLength(tenantId) {
+    if (!this.deadLetterQueueEnabled) {
+      return 0;
+    }
+    const dlqKey = this.keys.deadLetterQueueKey(tenantId);
+    return await this.redis.zcard(dlqKey);
+  }
+  // ============================================================================
+  // Public API - Lifecycle
+  // ============================================================================
+  /**
+   * Start the consumer loops and reclaim loop.
+   */
+  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);
+        }
+      }
+    }
+    this.reclaimLoop = this.#runReclaimLoop();
+    this.logger.info("FairQueue started", {
+      consumerCount: this.consumerCount,
+      shardCount: this.shardCount,
+      workerQueueEnabled: this.workerQueueEnabled,
+      consumerIntervalMs: this.consumerIntervalMs
+    });
+  }
+  /**
+   * Stop the consumer loops gracefully.
+   */
+  async stop() {
+    if (!this.isRunning) {
+      return;
+    }
+    this.isRunning = false;
+    this.abortController.abort();
+    await Promise.allSettled([
+      ...this.masterQueueConsumerLoops,
+      ...this.workerQueueConsumerLoops,
+      this.reclaimLoop
+    ]);
+    this.masterQueueConsumerLoops = [];
+    this.workerQueueConsumerLoops = [];
+    this.reclaimLoop = void 0;
+    this.logger.info("FairQueue stopped");
+  }
+  /**
+   * Close all resources.
+   */
+  async close() {
+    await this.stop();
+    await Promise.all([
+      this.masterQueue.close(),
+      this.concurrencyManager?.close(),
+      this.visibilityManager.close(),
+      this.workerQueueManager?.close(),
+      this.scheduler.close?.(),
+      this.redis.quit()
+    ]);
+  }
+  // ============================================================================
+  // Public API - Inspection
+  // ============================================================================
+  /**
+   * Get the number of messages in a queue.
+   */
+  async getQueueLength(queueId) {
+    const queueKey = this.keys.queueKey(queueId);
+    return await this.redis.zcard(queueKey);
+  }
+  /**
+   * Get total queue count across all shards.
+   */
+  async getTotalQueueCount() {
+    return await this.masterQueue.getTotalQueueCount();
+  }
+  /**
+   * Get total in-flight message count.
+   */
+  async getTotalInflightCount() {
+    return await this.visibilityManager.getTotalInflightCount();
+  }
+  /**
+   * Get the shard ID for a queue.
+   */
+  getShardForQueue(queueId) {
+    return this.masterQueue.getShardForQueue(queueId);
+  }
+  // ============================================================================
+  // Private - Master Queue Consumer Loop (Two-Stage)
+  // ============================================================================
+  async #runMasterQueueConsumerLoop(shardId) {
+    const loopId = `master-shard-${shardId}`;
+    try {
+      for await (const _ of setInterval$1(this.consumerIntervalMs, null, {
+        signal: this.abortController.signal
+      })) {
+        try {
+          await this.#processMasterQueueShard(loopId, shardId);
+        } catch (error) {
+          this.logger.error("Master queue consumer error", {
+            loopId,
+            shardId,
+            error: error instanceof Error ? error.message : String(error)
+          });
+        }
+      }
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        this.logger.debug("Master queue consumer aborted", { loopId });
+        return;
+      }
+      throw error;
+    }
+  }
+  async #processMasterQueueShard(loopId, shardId) {
+    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) {
+      for (const queueId of queues) {
+        if (this.cooloffEnabled && this.#isInCooloff(queueId)) {
+          continue;
+        }
+        const processed = await this.#claimAndPushToWorkerQueue(loopId, queueId, tenantId, shardId);
+        if (processed) {
+          await this.scheduler.recordProcessed?.(tenantId, queueId);
+          this.#resetCooloff(queueId);
+        } else {
+          this.#incrementCooloff(queueId);
+        }
+      }
+    }
+  }
+  async #claimAndPushToWorkerQueue(loopId, queueId, tenantId, shardId) {
+    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 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 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
+          );
+          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)
+          });
+        }
+      }
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        this.logger.debug("Worker queue consumer aborted", { loopId });
+        return;
+      }
+      throw error;
+    }
+  }
+  async #processMessageFromWorkerQueue(loopId, 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;
+    }
+    let storedMessage;
+    try {
+      storedMessage = JSON.parse(dataJson);
+    } catch {
+      this.logger.error("Failed to parse message data", { messageId, queueId });
+      return;
+    }
+    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;
+    }
+  }
+  async #processDirectIteration(loopId, shardId) {
+    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;
+        }
+      }
+    }
+  }
+  async #processOneMessage(loopId, queueId, tenantId, shardId) {
+    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 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;
+      }
+    }
+    await this.#processMessage(loopId, message.payload, queueId);
+    return true;
+  }
+  // ============================================================================
+  // Private - Message Processing
+  // ============================================================================
+  async #processMessage(loopId, storedMessage, queueId) {
+    const startTime = Date.now();
+    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 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,
+      queueId,
+      queueKey,
+      queueItemsKey,
+      Date.now()
+      // Put at back of queue
+    );
+    if (this.concurrencyManager) {
+      await this.concurrencyManager.release(descriptor, storedMessage.id);
+    }
+    this.logger.debug("Message released", {
+      messageId: storedMessage.id,
+      queueId
+    });
+  }
+  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
+      })
+    );
+    if (this.retryStrategy) {
+      const nextDelay = this.retryStrategy.getNextDelay(storedMessage.attempt, error);
+      if (nextDelay !== null) {
+        const updatedMessage = {
+          ...storedMessage,
+          attempt: storedMessage.attempt + 1
+        };
+        await this.visibilityManager.release(
+          storedMessage.id,
+          queueId,
+          queueKey,
+          queueItemsKey,
+          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.logger.debug("Message scheduled for retry", {
+          messageId: storedMessage.id,
+          queueId,
+          attempt: storedMessage.attempt + 1,
+          delayMs: nextDelay
+        });
+        return;
+      }
+    }
+    await this.#moveToDeadLetterQueue(storedMessage, error?.message);
+    if (this.concurrencyManager) {
+      await this.concurrencyManager.release(descriptor, storedMessage.id);
+    }
+  }
+  async #moveToDeadLetterQueue(storedMessage, errorMessage) {
+    if (!this.deadLetterQueueEnabled) {
+      await this.visibilityManager.complete(storedMessage.id, storedMessage.queueId);
+      return;
+    }
+    const dlqKey = this.keys.deadLetterQueueKey(storedMessage.tenantId);
+    const dlqDataKey = this.keys.deadLetterQueueDataKey(storedMessage.tenantId);
+    this.masterQueue.getShardForQueue(storedMessage.queueId);
+    const dlqMessage = {
+      id: storedMessage.id,
+      queueId: storedMessage.queueId,
+      tenantId: storedMessage.tenantId,
+      payload: storedMessage.payload,
+      deadLetteredAt: Date.now(),
+      attempts: storedMessage.attempt,
+      lastError: errorMessage,
+      originalTimestamp: storedMessage.timestamp
+    };
+    await this.visibilityManager.complete(storedMessage.id, storedMessage.queueId);
+    const pipeline = this.redis.pipeline();
+    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.logger.info("Message moved to DLQ", {
+      messageId: storedMessage.id,
+      queueId: storedMessage.queueId,
+      tenantId: storedMessage.tenantId,
+      attempts: storedMessage.attempt,
+      error: errorMessage
+    });
+  }
+  // ============================================================================
+  // Private - Reclaim Loop
+  // ============================================================================
+  async #runReclaimLoop() {
+    try {
+      for await (const _ of setInterval$1(this.reclaimIntervalMs, null, {
+        signal: this.abortController.signal
+      })) {
+        try {
+          await this.#reclaimTimedOutMessages();
+        } catch (error) {
+          this.logger.error("Reclaim loop error", {
+            error: error instanceof Error ? error.message : String(error)
+          });
+        }
+      }
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        this.logger.debug("Reclaim loop aborted");
+        return;
+      }
+      throw error;
+    }
+  }
+  async #reclaimTimedOutMessages() {
+    let totalReclaimed = 0;
+    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)
+      }));
+      totalReclaimed += reclaimed;
+    }
+    if (totalReclaimed > 0) {
+      this.logger.info("Reclaimed timed-out messages", { count: totalReclaimed });
+    }
+  }
+  // ============================================================================
+  // Private - Cooloff State
+  // ============================================================================
+  #isInCooloff(queueId) {
+    const state = this.queueCooloffStates.get(queueId);
+    if (!state) return false;
+    if (state.tag === "cooloff") {
+      if (Date.now() >= state.expiresAt) {
+        this.queueCooloffStates.delete(queueId);
+        return false;
+      }
+      return true;
+    }
+    return false;
+  }
+  #incrementCooloff(queueId) {
+    const state = this.queueCooloffStates.get(queueId) ?? {
+      tag: "normal",
+      consecutiveFailures: 0
+    };
+    if (state.tag === "normal") {
+      const newFailures = state.consecutiveFailures + 1;
+      if (newFailures >= this.cooloffThreshold) {
+        this.queueCooloffStates.set(queueId, {
+          tag: "cooloff",
+          expiresAt: Date.now() + this.cooloffPeriodMs
+        });
+        this.logger.debug("Queue entered cooloff", {
+          queueId,
+          cooloffPeriodMs: this.cooloffPeriodMs,
+          consecutiveFailures: newFailures
+        });
+      } else {
+        this.queueCooloffStates.set(queueId, {
+          tag: "normal",
+          consecutiveFailures: newFailures
+        });
+      }
+    }
+  }
+  #resetCooloff(queueId) {
+    this.queueCooloffStates.delete(queueId);
+  }
+  // ============================================================================
+  // Private - Helpers
+  // ============================================================================
+  #createSchedulerContext() {
+    return {
+      getCurrentConcurrency: async (groupName, groupId) => {
+        if (!this.concurrencyManager) return 0;
+        return this.concurrencyManager.getCurrentConcurrency(groupName, groupId);
+      },
+      getConcurrencyLimit: async (groupName, groupId) => {
+        if (!this.concurrencyManager) return Infinity;
+        return this.concurrencyManager.getConcurrencyLimit(groupName, groupId);
+      },
+      isAtCapacity: async (groupName, groupId) => {
+        if (!this.concurrencyManager) return false;
+        return this.concurrencyManager.isAtCapacity(groupName, groupId);
+      },
+      getQueueDescriptor: (queueId) => {
+        return this.queueDescriptorCache.get(queueId) ?? {
+          id: queueId,
+          tenantId: this.keys.extractTenantId(queueId),
+          metadata: {}
+        };
+      }
+    };
+  }
+  // ============================================================================
+  // Private - Redis Commands
+  // ============================================================================
+  #registerCommands() {
+    this.redis.defineCommand("enqueueMessageAtomic", {
+      numberOfKeys: 3,
+      lua: `
+local queueKey = KEYS[1]
+local queueItemsKey = KEYS[2]
+local masterQueueKey = KEYS[3]
+
+local queueId = ARGV[1]
+local messageId = ARGV[2]
+local timestamp = tonumber(ARGV[3])
+local payload = ARGV[4]
+
+-- Add to sorted set (score = timestamp)
+redis.call('ZADD', queueKey, timestamp, messageId)
+
+-- Store payload in hash
+redis.call('HSET', queueItemsKey, messageId, payload)
+
+-- Update master queue with oldest message timestamp
+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("enqueueBatchAtomic", {
+      numberOfKeys: 3,
+      lua: `
+local queueKey = KEYS[1]
+local queueItemsKey = KEYS[2]
+local masterQueueKey = KEYS[3]
+
+local queueId = ARGV[1]
+
+-- Args after queueId are triples: [messageId, timestamp, payload, ...]
+for i = 2, #ARGV, 3 do
+  local messageId = ARGV[i]
+  local timestamp = tonumber(ARGV[i + 1])
+  local payload = ARGV[i + 2]
+  
+  -- Add to sorted set
+  redis.call('ZADD', queueKey, timestamp, messageId)
+  
+  -- Store payload in hash
+  redis.call('HSET', queueItemsKey, messageId, payload)
+end
+
+-- Update master queue with oldest message timestamp
+local oldest = redis.call('ZRANGE', queueKey, 0, 0, 'WITHSCORES')
+if #oldest >= 2 then
+  redis.call('ZADD', masterQueueKey, oldest[2], queueId)
+end
+
+return (#ARGV - 1) / 3
+      `
+    });
+    this.redis.defineCommand("updateMasterQueueIfEmpty", {
+      numberOfKeys: 2,
+      lua: `
+local masterQueueKey = KEYS[1]
+local queueKey = KEYS[2]
+local queueId = ARGV[1]
+
+local count = redis.call('ZCARD', queueKey)
+if count == 0 then
+  redis.call('ZREM', masterQueueKey, queueId)
+  return 1
+else
+  -- Update with oldest message timestamp
+  local oldest = redis.call('ZRANGE', queueKey, 0, 0, 'WITHSCORES')
+  if #oldest >= 2 then
+    redis.call('ZADD', masterQueueKey, oldest[2], queueId)
+  end
+  return 0
+end
+      `
+    });
+    if (this.workerQueueManager) {
+      this.workerQueueManager.registerCommands(this.redis);
+    }
+  }
+};
+
+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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map