@trigger.dev/redis-worker 4.4.0 → 4.4.2

package/dist/index.js

@@ -11161,6 +11161,8 @@ var Worker = class _Worker {
   shutdownTimeoutMs;
   // The p-limit limiter to control overall concurrency.
   limiters = {};
+  // Batch accumulators: one per batch-enabled job type
+  batchAccumulators = /* @__PURE__ */ new Map();
   async #updateQueueSizeMetric(observableResult) {
     const queueSize = await this.queue.size();
     observableResult.observe(queueSize, {
@@ -11363,6 +11365,31 @@ var Worker = class _Worker {
   async getJob(id) {
     return this.queue.getJob(id);
   }
+  /**
+   * Returns true if the given job type has batch config in the catalog.
+   */
+  isBatchJob(jobType) {
+    const catalogItem = this.options.catalog[jobType];
+    return !!catalogItem?.batch;
+  }
+  /**
+   * Returns the batch config for a job type, or undefined if not batch-enabled.
+   */
+  getBatchConfig(jobType) {
+    const catalogItem = this.options.catalog[jobType];
+    return catalogItem?.batch;
+  }
+  /**
+   * The max dequeue count: the largest batch maxSize across catalog entries,
+   * falling back to tasksPerWorker for non-batch catalogs.
+   */
+  get maxDequeueCount() {
+    const batchSizes = Object.values(this.options.catalog).filter((entry) => !!entry.batch).map((entry) => entry.batch.maxSize);
+    if (batchSizes.length > 0) {
+      return Math.max(...batchSizes);
+    }
+    return this.concurrency.tasksPerWorker;
+  }
   /**
    * The main loop that each worker runs. It repeatedly polls for items,
    * processes them, and then waits before the next iteration.
@@ -11386,6 +11413,7 @@ var Worker = class _Worker {
       concurrencyOptions: this.concurrency
     });
     while (!this.isShuttingDown) {
+      await this.flushTimedOutBatches(workerId, limiter);
       if (limiter.activeCount + limiter.pendingCount >= this.concurrency.limit) {
         this.logger.debug("Worker at capacity, waiting", {
           workerId,
@@ -11397,9 +11425,10 @@ var Worker = class _Worker {
         continue;
       }
       const $taskCount = Math.min(
-        taskCount,
+        this.maxDequeueCount,
         this.concurrency.limit - limiter.activeCount - limiter.pendingCount
       );
+      let itemsFound = false;
       try {
         const items = await this.withHistogram(
           this.metrics.dequeueDuration,
@@ -11409,7 +11438,8 @@ var Worker = class _Worker {
             task_count: $taskCount
           }
         );
-        if (items.length === 0) {
+        itemsFound = items.length > 0;
+        if (items.length === 0 && this.batchAccumulators.size === 0) {
           this.logger.debug("No items to dequeue", {
             workerId,
             concurrencyOptions: this.concurrency,
@@ -11419,29 +11449,226 @@ var Worker = class _Worker {
           await _Worker.delay(pollIntervalMs);
           continue;
         }
-        this.logger.debug("Dequeued items", {
-          workerId,
-          itemCount: items.length,
-          concurrencyOptions: this.concurrency,
-          activeCount: limiter.activeCount,
-          pendingCount: limiter.pendingCount
-        });
-        for (const item of items) {
-          limiter(
-            () => this.processItem(item, items.length, workerId, limiter)
-          ).catch((err) => {
-            this.logger.error("Unhandled error in processItem:", { error: err, workerId, item });
+        if (items.length > 0) {
+          this.logger.debug("Dequeued items", {
+            workerId,
+            itemCount: items.length,
+            concurrencyOptions: this.concurrency,
+            activeCount: limiter.activeCount,
+            pendingCount: limiter.pendingCount
           });
         }
+        for (const item of items) {
+          const queueItem = item;
+          if (this.isBatchJob(queueItem.job)) {
+            this.addToAccumulator(queueItem);
+            const batchConfig = this.getBatchConfig(queueItem.job);
+            const accumulator = this.batchAccumulators.get(queueItem.job);
+            if (accumulator && accumulator.items.length >= batchConfig.maxSize) {
+              await this.flushBatch(queueItem.job, workerId, limiter);
+            }
+          } else {
+            limiter(
+              () => this.processItem(queueItem, items.length, workerId, limiter)
+            ).catch((err) => {
+              this.logger.error("Unhandled error in processItem:", {
+                error: err,
+                workerId,
+                item
+              });
+            });
+          }
+        }
       } catch (error) {
         this.logger.error("Error dequeuing items:", { name: this.options.name, error });
         await _Worker.delay(pollIntervalMs);
         continue;
       }
-      await _Worker.delay(immediatePollIntervalMs);
+      if (itemsFound || this.batchAccumulators.size > 0) {
+        await _Worker.delay(immediatePollIntervalMs);
+      } else {
+        await _Worker.delay(pollIntervalMs);
+      }
     }
+    await this.flushAllBatches(workerId, limiter);
     this.logger.info("Worker loop finished", { workerId });
   }
+  /**
+   * Adds an item to the batch accumulator for its job type.
+   */
+  addToAccumulator(item) {
+    let accumulator = this.batchAccumulators.get(item.job);
+    if (!accumulator) {
+      accumulator = { items: [], firstItemAt: Date.now() };
+      this.batchAccumulators.set(item.job, accumulator);
+    }
+    accumulator.items.push(item);
+  }
+  /**
+   * Flushes any batch accumulators that have exceeded their maxWaitMs.
+   */
+  async flushTimedOutBatches(workerId, limiter) {
+    const now = Date.now();
+    for (const [jobType, accumulator] of this.batchAccumulators) {
+      const batchConfig = this.getBatchConfig(jobType);
+      if (!batchConfig) continue;
+      if (now - accumulator.firstItemAt >= batchConfig.maxWaitMs) {
+        await this.flushBatch(jobType, workerId, limiter);
+      }
+    }
+  }
+  /**
+   * Flushes all batch accumulators (used during shutdown).
+   */
+  async flushAllBatches(workerId, limiter) {
+    for (const jobType of this.batchAccumulators.keys()) {
+      await this.flushBatch(jobType, workerId, limiter);
+    }
+  }
+  /**
+   * Flushes the batch accumulator for a specific job type.
+   * Removes items from the accumulator and submits them to the limiter as a single batch.
+   */
+  async flushBatch(jobType, workerId, limiter) {
+    const accumulator = this.batchAccumulators.get(jobType);
+    if (!accumulator || accumulator.items.length === 0) return;
+    const items = accumulator.items;
+    this.batchAccumulators.delete(jobType);
+    this.logger.debug("Flushing batch", {
+      jobType,
+      batchSize: items.length,
+      workerId,
+      accumulatedMs: Date.now() - accumulator.firstItemAt
+    });
+    limiter(() => this.processBatch(items, jobType, workerId, limiter)).catch((err) => {
+      this.logger.error("Unhandled error in processBatch:", {
+        error: err,
+        workerId,
+        jobType,
+        batchSize: items.length
+      });
+    });
+  }
+  /**
+   * Processes a batch of items for a batch-enabled job type.
+   */
+  async processBatch(items, jobType, workerId, limiter) {
+    const catalogItem = this.options.catalog[jobType];
+    const handler = this.jobs[jobType];
+    if (!handler) {
+      this.logger.error(`Worker no handler found for batch job type: ${jobType}`);
+      return;
+    }
+    if (!catalogItem) {
+      this.logger.error(`Worker no catalog item found for batch job type: ${jobType}`);
+      return;
+    }
+    const batchParams = items.map((item) => ({
+      id: item.id,
+      payload: item.item,
+      visibilityTimeoutMs: item.visibilityTimeoutMs,
+      attempt: item.attempt,
+      deduplicationKey: item.deduplicationKey
+    }));
+    await startSpan(
+      this.tracer,
+      "processBatch",
+      async () => {
+        await this.withHistogram(this.metrics.jobDuration, handler(batchParams), {
+          worker_id: workerId,
+          batch_size: items.length,
+          job_type: jobType
+        });
+        await Promise.all(items.map((item) => this.queue.ack(item.id, item.deduplicationKey)));
+      },
+      {
+        kind: SpanKind.CONSUMER,
+        attributes: {
+          job_type: jobType,
+          batch_size: items.length,
+          worker_id: workerId,
+          worker_name: this.options.name
+        }
+      }
+    ).catch(async (error) => {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const shouldLogError = catalogItem.logErrors ?? true;
+      if (shouldLogError) {
+        this.logger.error(`Worker error processing batch`, {
+          name: this.options.name,
+          jobType,
+          batchSize: items.length,
+          error,
+          errorMessage
+        });
+      } else {
+        this.logger.info(`Worker failed to process batch`, {
+          name: this.options.name,
+          jobType,
+          batchSize: items.length,
+          error,
+          errorMessage
+        });
+      }
+      for (const item of items) {
+        try {
+          const newAttempt = item.attempt + 1;
+          const retrySettings = {
+            ...defaultRetrySettings,
+            ...catalogItem?.retry
+          };
+          const retryDelay = calculateNextRetryDelay(retrySettings, newAttempt);
+          if (!retryDelay) {
+            if (shouldLogError) {
+              this.logger.error(`Worker batch item reached max attempts. Moving to DLQ.`, {
+                name: this.options.name,
+                id: item.id,
+                jobType,
+                attempt: newAttempt
+              });
+            } else {
+              this.logger.info(`Worker batch item reached max attempts. Moving to DLQ.`, {
+                name: this.options.name,
+                id: item.id,
+                jobType,
+                attempt: newAttempt
+              });
+            }
+            await this.queue.moveToDeadLetterQueue(item.id, errorMessage);
+            continue;
+          }
+          const retryDate = new Date(Date.now() + retryDelay);
+          this.logger.info(`Worker requeuing failed batch item with delay`, {
+            name: this.options.name,
+            id: item.id,
+            jobType,
+            retryDate,
+            retryDelay,
+            attempt: newAttempt
+          });
+          await this.queue.enqueue({
+            id: item.id,
+            job: item.job,
+            item: item.item,
+            availableAt: retryDate,
+            attempt: newAttempt,
+            visibilityTimeoutMs: item.visibilityTimeoutMs
+          });
+        } catch (requeueError) {
+          this.logger.error(
+            `Worker failed to requeue batch item. It will be retried after the visibility timeout.`,
+            {
+              name: this.options.name,
+              id: item.id,
+              jobType,
+              visibilityTimeoutMs: item.visibilityTimeoutMs,
+              error: requeueError
+            }
+          );
+        }
+      }
+    });
+  }
   /**
    * Processes a single item.
    */
@@ -12152,6 +12379,135 @@ return 1
     });
   }
 };
+var TenantDispatch = class {
+  constructor(options) {
+    this.options = options;
+    this.redis = createRedisClient(options.redis);
+    this.keys = options.keys;
+    this.shardCount = Math.max(1, options.shardCount);
+  }
+  redis;
+  keys;
+  shardCount;
+  /**
+   * Get the dispatch shard ID for a tenant.
+   * Uses jump consistent hash on the tenant ID so each tenant
+   * always maps to exactly one dispatch shard.
+   */
+  getShardForTenant(tenantId) {
+    return jumpHash(tenantId, this.shardCount);
+  }
+  /**
+   * Get eligible tenants from a dispatch shard (Level 1).
+   * Returns tenants ordered by oldest message (lowest score first).
+   */
+  async getTenantsFromShard(shardId, limit = 1e3, maxScore) {
+    const dispatchKey = this.keys.dispatchKey(shardId);
+    const score = maxScore ?? Date.now();
+    const results = await this.redis.zrangebyscore(
+      dispatchKey,
+      "-inf",
+      score,
+      "WITHSCORES",
+      "LIMIT",
+      0,
+      limit
+    );
+    const tenants = [];
+    for (let i = 0; i < results.length; i += 2) {
+      const tenantId = results[i];
+      const scoreStr = results[i + 1];
+      if (tenantId && scoreStr) {
+        tenants.push({
+          tenantId,
+          score: parseFloat(scoreStr)
+        });
+      }
+    }
+    return tenants;
+  }
+  /**
+   * Get queues for a specific tenant (Level 2).
+   * Returns queues ordered by oldest message (lowest score first).
+   */
+  async getQueuesForTenant(tenantId, limit = 1e3, maxScore) {
+    const tenantQueueKey = this.keys.tenantQueueIndexKey(tenantId);
+    const score = maxScore ?? Date.now();
+    const results = await this.redis.zrangebyscore(
+      tenantQueueKey,
+      "-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
+        });
+      }
+    }
+    return queues;
+  }
+  /**
+   * Get the number of tenants in a dispatch shard.
+   */
+  async getShardTenantCount(shardId) {
+    const dispatchKey = this.keys.dispatchKey(shardId);
+    return await this.redis.zcard(dispatchKey);
+  }
+  /**
+   * Get total tenant count across all dispatch shards.
+   * Note: tenants may appear in multiple shards, so this may overcount.
+   */
+  async getTotalTenantCount() {
+    const counts = await Promise.all(
+      Array.from({ length: this.shardCount }, (_, i) => this.getShardTenantCount(i))
+    );
+    return counts.reduce((sum, count) => sum + count, 0);
+  }
+  /**
+   * Get the number of queues for a tenant.
+   */
+  async getTenantQueueCount(tenantId) {
+    const tenantQueueKey = this.keys.tenantQueueIndexKey(tenantId);
+    return await this.redis.zcard(tenantQueueKey);
+  }
+  /**
+   * Remove a tenant from a specific dispatch shard.
+   */
+  async removeTenantFromShard(shardId, tenantId) {
+    const dispatchKey = this.keys.dispatchKey(shardId);
+    await this.redis.zrem(dispatchKey, tenantId);
+  }
+  /**
+   * Add a tenant to a dispatch shard with the given score.
+   */
+  async addTenantToShard(shardId, tenantId, score) {
+    const dispatchKey = this.keys.dispatchKey(shardId);
+    await this.redis.zadd(dispatchKey, score, tenantId);
+  }
+  /**
+   * Remove a queue from a tenant's queue index.
+   */
+  async removeQueueFromTenant(tenantId, queueId) {
+    const tenantQueueKey = this.keys.tenantQueueIndexKey(tenantId);
+    await this.redis.zrem(tenantQueueKey, queueId);
+  }
+  /**
+   * Close the Redis connection.
+   */
+  async close() {
+    await this.redis.quit();
+  }
+};
 
 // src/fair-queue/telemetry.ts
 var FairQueueAttributes = {
@@ -12333,6 +12689,18 @@ var FairQueueTelemetry = class {
         }
       });
     }
+    if (callbacks.getDispatchLength && callbacks.shardCount) {
+      const getDispatchLength = callbacks.getDispatchLength;
+      const shardCount = callbacks.shardCount;
+      this.metrics.dispatchLength.addCallback(async (observableResult) => {
+        for (let shardId = 0; shardId < shardCount; shardId++) {
+          const length = await getDispatchLength(shardId);
+          observableResult.observe(length, {
+            [FairQueueAttributes.SHARD_ID]: shardId.toString()
+          });
+        }
+      });
+    }
     if (callbacks.getInflightCount && callbacks.shardCount) {
       const getInflightCount = callbacks.getInflightCount;
       const shardCount = callbacks.shardCount;
@@ -12435,9 +12803,13 @@ var FairQueueTelemetry = class {
         unit: "messages"
       }),
       masterQueueLength: this.meter.createObservableGauge(`${this.name}.master_queue.length`, {
-        description: "Number of queues in master queue shard",
+        description: "Number of queues in legacy master queue shard (draining)",
         unit: "queues"
       }),
+      dispatchLength: this.meter.createObservableGauge(`${this.name}.dispatch.length`, {
+        description: "Number of tenants in dispatch index shard",
+        unit: "tenants"
+      }),
       inflightCount: this.meter.createObservableGauge(`${this.name}.inflight.count`, {
         description: "Number of messages currently being processed",
         unit: "messages"
@@ -12841,10 +13213,12 @@ var VisibilityManager = class {
    * @param queueId - The queue ID
    * @param queueKey - The Redis key for the queue
    * @param queueItemsKey - The Redis key for the queue items hash
-   * @param masterQueueKey - The Redis key for the master queue
+   * @param tenantQueueIndexKey - The Redis key for the tenant queue index (Level 2)
+   * @param dispatchKey - The Redis key for the dispatch index (Level 1)
+   * @param tenantId - The tenant ID
    * @param score - Optional score for the message (defaults to now)
    */
-  async release(messageId, queueId, queueKey, queueItemsKey, masterQueueKey, score) {
+  async release(messageId, queueId, queueKey, queueItemsKey, tenantQueueIndexKey, dispatchKey, tenantId, score, updatedData) {
     const shardId = this.#getShardForQueue(queueId);
     const inflightKey = this.keys.inflightKey(shardId);
     const inflightDataKey = this.keys.inflightDataKey(shardId);
@@ -12855,11 +13229,14 @@ var VisibilityManager = class {
       inflightDataKey,
       queueKey,
       queueItemsKey,
-      masterQueueKey,
+      tenantQueueIndexKey,
+      dispatchKey,
       member,
       messageId,
       messageScore.toString(),
-      queueId
+      queueId,
+      updatedData ?? "",
+      tenantId
     );
     this.logger.debug("Message released", {
       messageId,
@@ -12876,10 +13253,12 @@ var VisibilityManager = class {
    * @param queueId - The queue ID
    * @param queueKey - The Redis key for the queue
    * @param queueItemsKey - The Redis key for the queue items hash
-   * @param masterQueueKey - The Redis key for the master queue
+   * @param tenantQueueIndexKey - The Redis key for the tenant queue index (Level 2)
+   * @param dispatchKey - The Redis key for the dispatch index (Level 1)
+   * @param tenantId - The tenant ID
    * @param score - Optional score for the messages (defaults to now)
    */
-  async releaseBatch(messages, queueId, queueKey, queueItemsKey, masterQueueKey, score) {
+  async releaseBatch(messages, queueId, queueKey, queueItemsKey, tenantQueueIndexKey, dispatchKey, tenantId, score) {
     if (messages.length === 0) {
       return;
     }
@@ -12894,9 +13273,11 @@ var VisibilityManager = class {
       inflightDataKey,
       queueKey,
       queueItemsKey,
-      masterQueueKey,
+      tenantQueueIndexKey,
+      dispatchKey,
       messageScore.toString(),
       queueId,
+      tenantId,
       ...members,
       ...messageIds
     );
@@ -12936,7 +13317,7 @@ var VisibilityManager = class {
         continue;
       }
       const { messageId, queueId } = this.#parseMember(member);
-      const { queueKey, queueItemsKey, masterQueueKey } = getQueueKeys(queueId);
+      const { queueKey, queueItemsKey, tenantQueueIndexKey, dispatchKey, tenantId } = getQueueKeys(queueId);
       try {
         const dataJson = await this.redis.hget(inflightDataKey, messageId);
         let storedMessage = null;
@@ -12952,11 +13333,14 @@ var VisibilityManager = class {
           inflightDataKey,
           queueKey,
           queueItemsKey,
-          masterQueueKey,
+          tenantQueueIndexKey,
+          dispatchKey,
           member,
           messageId,
           score.toString(),
-          queueId
+          queueId,
+          "",
+          tenantId
         );
         if (storedMessage) {
           reclaimedMessages.push({
@@ -13157,18 +13541,21 @@ return results
       `
     });
     this.redis.defineCommand("releaseMessage", {
-      numberOfKeys: 5,
+      numberOfKeys: 6,
       lua: `
 local inflightKey = KEYS[1]
 local inflightDataKey = KEYS[2]
 local queueKey = KEYS[3]
 local queueItemsKey = KEYS[4]
-local masterQueueKey = KEYS[5]
+local tenantQueueIndexKey = KEYS[5]
+local dispatchKey = KEYS[6]
 
 local member = ARGV[1]
 local messageId = ARGV[2]
 local score = tonumber(ARGV[3])
 local queueId = ARGV[4]
+local updatedData = ARGV[5]
+local tenantId = ARGV[6]
 
 -- Get message data from in-flight
 local payload = redis.call('HGET', inflightDataKey, messageId)
@@ -13177,6 +13564,12 @@ if not payload then
   return 0
 end
 
+-- Use updatedData if provided (e.g. incremented attempt count for retries),
+-- otherwise use the original in-flight data
+if updatedData and updatedData ~= "" then
+  payload = updatedData
+end
+
 -- Remove from in-flight
 redis.call('ZREM', inflightKey, member)
 redis.call('HDEL', inflightDataKey, messageId)
@@ -13185,33 +13578,39 @@ redis.call('HDEL', inflightDataKey, messageId)
 redis.call('ZADD', queueKey, score, messageId)
 redis.call('HSET', queueItemsKey, messageId, payload)
 
--- Update master queue with oldest message timestamp
--- This ensures delayed messages don't push the queue priority to the future
--- when there are other ready messages in the queue
+-- Update tenant queue index (Level 2) with queue's oldest message
 local oldest = redis.call('ZRANGE', queueKey, 0, 0, 'WITHSCORES')
 if #oldest >= 2 then
-  redis.call('ZADD', masterQueueKey, oldest[2], queueId)
+  redis.call('ZADD', tenantQueueIndexKey, oldest[2], queueId)
+end
+
+-- Update dispatch index (Level 1) with tenant's oldest across all queues
+local tenantOldest = redis.call('ZRANGE', tenantQueueIndexKey, 0, 0, 'WITHSCORES')
+if #tenantOldest >= 2 then
+  redis.call('ZADD', dispatchKey, tenantOldest[2], tenantId)
 end
 
 return 1
       `
     });
     this.redis.defineCommand("releaseMessageBatch", {
-      numberOfKeys: 5,
+      numberOfKeys: 6,
       lua: `
 local inflightKey = KEYS[1]
 local inflightDataKey = KEYS[2]
 local queueKey = KEYS[3]
 local queueItemsKey = KEYS[4]
-local masterQueueKey = KEYS[5]
+local tenantQueueIndexKey = KEYS[5]
+local dispatchKey = KEYS[6]
 
 local score = tonumber(ARGV[1])
 local queueId = ARGV[2]
+local tenantId = ARGV[3]
 
 -- Remaining args are: members..., messageIds...
 -- Calculate how many messages we have
-local numMessages = (table.getn(ARGV) - 2) / 2
-local membersStart = 3
+local numMessages = (table.getn(ARGV) - 3) / 2
+local membersStart = 4
 local messageIdsStart = membersStart + numMessages
 
 local releasedCount = 0
@@ -13219,27 +13618,33 @@ local releasedCount = 0
 for i = 0, numMessages - 1 do
   local member = ARGV[membersStart + i]
   local messageId = ARGV[messageIdsStart + i]
-  
+
   -- Get message data from in-flight
   local payload = redis.call('HGET', inflightDataKey, messageId)
   if payload then
     -- Remove from in-flight
     redis.call('ZREM', inflightKey, member)
     redis.call('HDEL', inflightDataKey, messageId)
-    
+
     -- Add back to queue
     redis.call('ZADD', queueKey, score, messageId)
     redis.call('HSET', queueItemsKey, messageId, payload)
-    
+
     releasedCount = releasedCount + 1
   end
 end
 
--- Update master queue with oldest message timestamp (only once at the end)
+-- Update dispatch indexes (only once at the end)
 if releasedCount > 0 then
+  -- Update tenant queue index (Level 2)
   local oldest = redis.call('ZRANGE', queueKey, 0, 0, 'WITHSCORES')
   if #oldest >= 2 then
-    redis.call('ZADD', masterQueueKey, oldest[2], queueId)
+    redis.call('ZADD', tenantQueueIndexKey, oldest[2], queueId)
+  end
+  -- Update dispatch index (Level 1)
+  local tenantOldest = redis.call('ZRANGE', tenantQueueIndexKey, 0, 0, 'WITHSCORES')
+  if #tenantOldest >= 2 then
+    redis.call('ZADD', dispatchKey, tenantOldest[2], tenantId)
   end
 end
 
@@ -13527,6 +13932,15 @@ var DefaultFairQueueKeyProducer = class {
     return this.#buildKey("worker", consumerId);
   }
   // ============================================================================
+  // Tenant Dispatch Keys (Two-Level Index)
+  // ============================================================================
+  dispatchKey(shardId) {
+    return this.#buildKey("dispatch", shardId.toString());
+  }
+  tenantQueueIndexKey(tenantId) {
+    return this.#buildKey("tenantq", tenantId);
+  }
+  // ============================================================================
   // Dead Letter Queue Keys
   // ============================================================================
   deadLetterQueueKey(tenantId) {
@@ -13739,6 +14153,44 @@ var DRRScheduler = class extends BaseScheduler {
       queues: t.queues
     }));
   }
+  /**
+   * Select queues using the two-level tenant dispatch index.
+   *
+   * Algorithm:
+   * 1. ZRANGEBYSCORE on dispatch index (gets only tenants with queues - much smaller)
+   * 2. Add quantum to each tenant's deficit (atomically)
+   * 3. Check capacity as safety net (dispatch should only have tenants with capacity)
+   * 4. Select tenants with deficit >= 1, sorted by deficit (highest first)
+   * 5. For each tenant, fetch their queues from Level 2 index
+   */
+  async selectQueuesFromDispatch(dispatchShardKey, consumerId, context2) {
+    const tenants = await this.#getTenantsFromDispatch(dispatchShardKey);
+    if (tenants.length === 0) {
+      return [];
+    }
+    const tenantIds = tenants.map((t) => t.tenantId);
+    const deficits = await this.#addQuantumToTenants(tenantIds);
+    const candidates = tenantIds.map((tenantId, index) => ({ tenantId, deficit: deficits[index] ?? 0 })).filter((t) => t.deficit >= 1);
+    candidates.sort((a, b) => b.deficit - a.deficit);
+    for (const { tenantId, deficit } of candidates) {
+      const isAtCapacity = await context2.isAtCapacity("tenant", tenantId);
+      if (isAtCapacity) continue;
+      const queueLimit = Math.ceil(deficit);
+      const queues = await context2.getQueuesForTenant(tenantId, queueLimit);
+      if (queues.length > 0) {
+        this.logger.debug("DRR dispatch: selected tenant", {
+          dispatchTenants: tenants.length,
+          candidates: candidates.length,
+          selectedTenant: tenantId,
+          deficit,
+          queueLimit,
+          queuesReturned: queues.length
+        });
+        return [{ tenantId, queues: queues.map((q) => q.queueId) }];
+      }
+    }
+    return [];
+  }
   /**
    * Record that a message was processed from a tenant.
    * Decrements the tenant's deficit.
@@ -13793,6 +14245,30 @@ var DRRScheduler = class extends BaseScheduler {
   #deficitKey() {
     return `${this.keys.masterQueueKey(0).split(":")[0]}:drr:deficit`;
   }
+  async #getTenantsFromDispatch(dispatchKey) {
+    const now = Date.now();
+    const results = await this.redis.zrangebyscore(
+      dispatchKey,
+      "-inf",
+      now,
+      "WITHSCORES",
+      "LIMIT",
+      0,
+      this.masterQueueLimit
+    );
+    const tenants = [];
+    for (let i = 0; i < results.length; i += 2) {
+      const tenantId = results[i];
+      const scoreStr = results[i + 1];
+      if (tenantId && scoreStr) {
+        tenants.push({
+          tenantId,
+          score: parseFloat(scoreStr)
+        });
+      }
+    }
+    return tenants;
+  }
   async #getQueuesFromShard(shardKey) {
     const now = Date.now();
     const results = await this.redis.zrangebyscore(
@@ -14426,7 +14902,8 @@ var FairQueue = class {
     this.cooloffThreshold = options.cooloff?.threshold ?? 10;
     this.cooloffPeriodMs = options.cooloff?.periodMs ?? 1e4;
     this.maxCooloffStatesSize = options.cooloff?.maxStatesSize ?? 1e3;
-    this.globalRateLimiter = options.globalRateLimiter;
+    this.workerQueueMaxDepth = options.workerQueueMaxDepth ?? 0;
+    this.workerQueueDepthCheckId = options.workerQueueDepthCheckId;
     this.consumerTraceMaxIterations = options.consumerTraceMaxIterations ?? 500;
     this.consumerTraceTimeoutSeconds = options.consumerTraceTimeoutSeconds ?? 60;
     this.telemetry = new FairQueueTelemetry({
@@ -14449,6 +14926,11 @@ var FairQueue = class {
       keys: options.keys,
       shardCount: this.shardCount
     });
+    this.tenantDispatch = new TenantDispatch({
+      redis: options.redis,
+      keys: options.keys,
+      shardCount: this.shardCount
+    });
     if (options.concurrencyGroups && options.concurrencyGroups.length > 0) {
       this.concurrencyManager = new ConcurrencyManager({
         redis: options.redis,
@@ -14507,8 +14989,9 @@ var FairQueue = class {
   cooloffPeriodMs;
   maxCooloffStatesSize;
   queueCooloffStates = /* @__PURE__ */ new Map();
-  // Global rate limiter
-  globalRateLimiter;
+  // Worker queue backpressure
+  workerQueueMaxDepth;
+  workerQueueDepthCheckId;
   // Consumer tracing
   consumerTraceMaxIterations;
   consumerTraceTimeoutSeconds;
@@ -14520,6 +15003,8 @@ var FairQueue = class {
   reclaimLoop;
   // Queue descriptor cache for message processing
   queueDescriptorCache = /* @__PURE__ */ new Map();
+  // Two-level tenant dispatch
+  tenantDispatch;
   // ============================================================================
   // Public API - Telemetry
   // ============================================================================
@@ -14534,6 +15019,9 @@ var FairQueue = class {
       getMasterQueueLength: async (shardId) => {
         return await this.masterQueue.getShardQueueCount(shardId);
       },
+      getDispatchLength: async (shardId) => {
+        return await this.tenantDispatch.getShardTenantCount(shardId);
+      },
       getInflightCount: async (shardId) => {
         return await this.visibilityManager.getInflightCount(shardId);
       },
@@ -14558,8 +15046,9 @@ var FairQueue = class {
         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);
+        const dispatchShardId = this.tenantDispatch.getShardForTenant(options.tenantId);
+        const tenantQueueIndexKey = this.keys.tenantQueueIndexKey(options.tenantId);
+        const dispatchKey = this.keys.dispatchKey(dispatchShardId);
         if (this.validateOnEnqueue && this.payloadSchema) {
           const result = this.payloadSchema.safeParse(options.payload);
           if (!result.success) {
@@ -14590,20 +15079,22 @@ var FairQueue = class {
           }) : void 0,
           metadata: options.metadata
         };
-        await this.redis.enqueueMessageAtomic(
+        await this.redis.enqueueMessageAtomicV2(
           queueKey,
           queueItemsKey,
-          masterQueueKey,
+          tenantQueueIndexKey,
+          dispatchKey,
           options.queueId,
           messageId,
           timestamp.toString(),
-          JSON.stringify(storedMessage)
+          JSON.stringify(storedMessage),
+          options.tenantId
         );
         span.setAttributes({
           [FairQueueAttributes.QUEUE_ID]: options.queueId,
           [FairQueueAttributes.TENANT_ID]: options.tenantId,
           [FairQueueAttributes.MESSAGE_ID]: messageId,
-          [FairQueueAttributes.SHARD_ID]: shardId.toString()
+          [FairQueueAttributes.SHARD_ID]: dispatchShardId.toString()
         });
         this.telemetry.recordEnqueue();
         this.logger.debug("Message enqueued", {
@@ -14630,8 +15121,9 @@ var FairQueue = class {
       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 dispatchShardId = this.tenantDispatch.getShardForTenant(options.tenantId);
+        const tenantQueueIndexKey = this.keys.tenantQueueIndexKey(options.tenantId);
+        const dispatchKey = this.keys.dispatchKey(dispatchShardId);
         const now = Date.now();
         const descriptor = {
           id: options.queueId,
@@ -14673,18 +15165,20 @@ var FairQueue = class {
           messageIds.push(messageId);
           args.push(messageId, timestamp.toString(), JSON.stringify(storedMessage));
         }
-        await this.redis.enqueueBatchAtomic(
+        await this.redis.enqueueBatchAtomicV2(
           queueKey,
           queueItemsKey,
-          masterQueueKey,
+          tenantQueueIndexKey,
+          dispatchKey,
           options.queueId,
+          options.tenantId,
           ...args
         );
         span.setAttributes({
           [FairQueueAttributes.QUEUE_ID]: options.queueId,
           [FairQueueAttributes.TENANT_ID]: options.tenantId,
           [FairQueueAttributes.MESSAGE_COUNT]: messageIds.length,
-          [FairQueueAttributes.SHARD_ID]: shardId.toString()
+          [FairQueueAttributes.SHARD_ID]: dispatchShardId.toString()
         });
         this.telemetry.recordEnqueueBatch(messageIds.length);
         this.logger.debug("Batch enqueued", {
@@ -14886,6 +15380,7 @@ var FairQueue = class {
     this.batchedSpanManager.cleanupAll();
     await Promise.all([
       this.masterQueue.close(),
+      this.tenantDispatch.close(),
       this.concurrencyManager?.close(),
       this.visibilityManager.close(),
       this.workerQueueManager.close(),
@@ -14904,10 +15399,14 @@ var FairQueue = class {
     return await this.redis.zcard(queueKey);
   }
   /**
-   * Get total queue count across all shards.
+   * Get total tenant count across dispatch shards plus any legacy queues still draining.
    */
   async getTotalQueueCount() {
-    return await this.masterQueue.getTotalQueueCount();
+    const [dispatchCount, legacyCount] = await Promise.all([
+      this.tenantDispatch.getTotalTenantCount(),
+      this.masterQueue.getTotalQueueCount()
+    ]);
+    return dispatchCount + legacyCount;
   }
   /**
    * Get total in-flight message count.
@@ -14938,7 +15437,7 @@ var FairQueue = class {
             loopId,
             async (span) => {
               span.setAttribute("shard_id", shardId);
-              return await this.#processMasterQueueShard(loopId, shardId, span);
+              return await this.#processShardIteration(loopId, shardId, span);
             },
             {
               iterationSpanName: "processMasterQueueShard",
@@ -14977,32 +15476,142 @@ var FairQueue = class {
       this.batchedSpanManager.cleanup(loopId);
     }
   }
-  async #processMasterQueueShard(loopId, shardId, parentSpan) {
+  /**
+   * Process a shard iteration. Runs both the new tenant dispatch path
+   * and the legacy master queue drain path.
+   */
+  async #processShardIteration(loopId, shardId, parentSpan) {
+    let hadWork = false;
+    hadWork = await this.#processDispatchShard(loopId, shardId, parentSpan);
+    const legacyCount = await this.masterQueue.getShardQueueCount(shardId);
+    if (legacyCount > 0) {
+      const drainHadWork = await this.#drainLegacyMasterQueueShard(loopId, shardId, parentSpan);
+      hadWork = hadWork || drainHadWork;
+    }
+    return hadWork;
+  }
+  /**
+   * Main path: process queues using the two-level tenant dispatch index.
+   * Level 1: dispatch index → tenantIds. Level 2: per-tenant → queueIds.
+   */
+  async #processDispatchShard(loopId, shardId, parentSpan) {
+    const dispatchKey = this.keys.dispatchKey(shardId);
+    const dispatchSize = await this.tenantDispatch.getShardTenantCount(shardId);
+    parentSpan?.setAttribute("dispatch_size", dispatchSize);
+    this.batchedSpanManager.incrementStat(loopId, "dispatch_size_sum", dispatchSize);
+    const schedulerContext = {
+      ...this.#createSchedulerContext(),
+      getQueuesForTenant: async (tenantId, limit) => {
+        return this.tenantDispatch.getQueuesForTenant(tenantId, limit);
+      }
+    };
+    let tenantQueues;
+    if (this.scheduler.selectQueuesFromDispatch) {
+      tenantQueues = await this.telemetry.trace(
+        "selectQueuesFromDispatch",
+        async (span) => {
+          span.setAttribute(FairQueueAttributes.SHARD_ID, shardId.toString());
+          span.setAttribute(FairQueueAttributes.CONSUMER_ID, loopId);
+          span.setAttribute("dispatch_size", dispatchSize);
+          const result = await this.scheduler.selectQueuesFromDispatch(
+            dispatchKey,
+            loopId,
+            schedulerContext
+          );
+          span.setAttribute("tenant_count", result.length);
+          span.setAttribute(
+            "queue_count",
+            result.reduce((acc, t) => acc + t.queues.length, 0)
+          );
+          return result;
+        },
+        { kind: SpanKind.INTERNAL }
+      );
+    } else {
+      tenantQueues = await this.#fallbackDispatchToLegacyScheduler(
+        loopId,
+        shardId,
+        schedulerContext,
+        parentSpan
+      );
+    }
+    if (tenantQueues.length === 0) {
+      this.batchedSpanManager.incrementStat(loopId, "empty_iterations");
+      return false;
+    }
+    return this.#processSelectedQueues(loopId, shardId, tenantQueues);
+  }
+  /**
+   * Drain path: process remaining messages from the legacy master queue shard.
+   * Uses simple ZRANGEBYSCORE without DRR - just flushing pre-deploy messages.
+   */
+  async #drainLegacyMasterQueueShard(loopId, shardId, parentSpan) {
     const masterQueueKey = this.keys.masterQueueKey(shardId);
-    const masterQueueSize = await this.masterQueue.getShardQueueCount(shardId);
-    parentSpan?.setAttribute("master_queue_size", masterQueueSize);
-    this.batchedSpanManager.incrementStat(loopId, "master_queue_size_sum", masterQueueSize);
-    const schedulerContext = this.#createSchedulerContext();
-    const tenantQueues = await this.telemetry.trace(
-      "selectQueues",
-      async (span) => {
-        span.setAttribute(FairQueueAttributes.SHARD_ID, shardId.toString());
-        span.setAttribute(FairQueueAttributes.CONSUMER_ID, loopId);
-        span.setAttribute("master_queue_size", masterQueueSize);
-        const result = await this.scheduler.selectQueues(masterQueueKey, loopId, schedulerContext);
-        span.setAttribute("tenant_count", result.length);
-        span.setAttribute(
-          "queue_count",
-          result.reduce((acc, t) => acc + t.queues.length, 0)
-        );
-        return result;
-      },
-      { kind: SpanKind.INTERNAL }
+    const now = Date.now();
+    const results = await this.redis.zrangebyscore(
+      masterQueueKey,
+      "-inf",
+      now,
+      "WITHSCORES",
+      "LIMIT",
+      0,
+      100
     );
+    if (results.length === 0) {
+      return false;
+    }
+    const byTenant = /* @__PURE__ */ new Map();
+    for (let i = 0; i < results.length; i += 2) {
+      const queueId = results[i];
+      const _score = results[i + 1];
+      if (queueId && _score) {
+        const tenantId = this.keys.extractTenantId(queueId);
+        const existing = byTenant.get(tenantId) ?? [];
+        existing.push(queueId);
+        byTenant.set(tenantId, existing);
+      }
+    }
+    const tenantQueues = [];
+    for (const [tenantId, queueIds] of byTenant) {
+      if (this.concurrencyManager) {
+        const atCapacity = await this.concurrencyManager.isAtCapacity("tenant", tenantId);
+        if (atCapacity) continue;
+      }
+      tenantQueues.push({ tenantId, queues: queueIds });
+    }
     if (tenantQueues.length === 0) {
-      this.batchedSpanManager.incrementStat(loopId, "empty_iterations");
       return false;
     }
+    parentSpan?.setAttribute("drain_tenants", tenantQueues.length);
+    this.batchedSpanManager.incrementStat(loopId, "drain_tenants", tenantQueues.length);
+    return this.#processSelectedQueues(loopId, shardId, tenantQueues);
+  }
+  /**
+   * Fallback for schedulers that don't implement selectQueuesFromDispatch.
+   * Reads dispatch index, fetches per-tenant queues, groups by tenant,
+   * and filters at-capacity tenants. No DRR deficit tracking in this path.
+   */
+  async #fallbackDispatchToLegacyScheduler(loopId, shardId, context2, parentSpan) {
+    const tenants = await this.tenantDispatch.getTenantsFromShard(shardId);
+    if (tenants.length === 0) return [];
+    const tenantQueues = [];
+    for (const { tenantId } of tenants) {
+      if (this.concurrencyManager) {
+        const atCapacity = await this.concurrencyManager.isAtCapacity("tenant", tenantId);
+        if (atCapacity) continue;
+      }
+      const queues = await this.tenantDispatch.getQueuesForTenant(tenantId);
+      if (queues.length > 0) {
+        tenantQueues.push({ tenantId, queues: queues.map((q) => q.queueId) });
+      }
+    }
+    return tenantQueues;
+  }
+  /**
+   * Shared claim loop: process selected queues from either dispatch or drain path.
+   * Claims messages and pushes to worker queues.
+   */
+  async #processSelectedQueues(loopId, shardId, tenantQueues) {
     this.batchedSpanManager.incrementStat(loopId, "tenants_selected", tenantQueues.length);
     this.batchedSpanManager.incrementStat(
       loopId,
@@ -15069,10 +15678,10 @@ var FairQueue = class {
     }
     return messagesProcessed > 0;
   }
-  async #claimAndPushToWorkerQueue(loopId, queueId, tenantId, shardId) {
+  async #claimAndPushToWorkerQueue(loopId, queueId, tenantId, _consumerShardId) {
+    const dispatchShardId = this.tenantDispatch.getShardForTenant(tenantId);
     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,
@@ -15082,28 +15691,23 @@ var FairQueue = class {
     if (this.concurrencyManager) {
       const availableCapacity = await this.concurrencyManager.getAvailableCapacity(descriptor);
       if (availableCapacity === 0) {
-        this.#incrementCooloff(queueId);
         return 0;
       }
       maxClaimCount = Math.min(maxClaimCount, availableCapacity);
     }
-    if (this.globalRateLimiter) {
-      const result = await this.globalRateLimiter.limit();
-      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));
-        }
+    if (this.workerQueueMaxDepth > 0 && this.workerQueueDepthCheckId) {
+      const depth = await this.workerQueueManager.getLength(this.workerQueueDepthCheckId);
+      if (depth >= this.workerQueueMaxDepth) {
+        return 0;
       }
+      const remainingCapacity = this.workerQueueMaxDepth - depth;
+      maxClaimCount = Math.min(maxClaimCount, remainingCapacity);
     }
     const claimedMessages = await this.visibilityManager.claimBatch(queueId, queueKey, queueItemsKey, loopId, maxClaimCount, this.visibilityTimeoutMs);
     if (claimedMessages.length === 0) {
-      const removed = await this.redis.updateMasterQueueIfEmpty(masterQueueKey, queueKey, queueId);
-      if (removed === 1) {
-        this.queueDescriptorCache.delete(queueId);
-        this.queueCooloffStates.delete(queueId);
-      }
+      await this.#updateAllIndexesAfterDequeue(queueId, tenantId);
+      this.queueDescriptorCache.delete(queueId);
+      this.queueCooloffStates.delete(queueId);
       return 0;
     }
     let processedCount = 0;
@@ -15112,12 +15716,16 @@ var FairQueue = class {
       if (this.concurrencyManager) {
         const reserved = await this.concurrencyManager.reserve(descriptor, message.messageId);
         if (!reserved) {
+          const tenantQueueIndexKey = this.keys.tenantQueueIndexKey(tenantId);
+          const dispatchKey = this.keys.dispatchKey(dispatchShardId);
           await this.visibilityManager.releaseBatch(
             claimedMessages.slice(i),
             queueId,
             queueKey,
             queueItemsKey,
-            masterQueueKey
+            tenantQueueIndexKey,
+            dispatchKey,
+            tenantId
           );
           break;
         }
@@ -15177,8 +15785,6 @@ var FairQueue = class {
    */
   async completeMessage(messageId, queueId) {
     const shardId = this.masterQueue.getShardForQueue(queueId);
-    const queueKey = this.keys.queueKey(queueId);
-    const masterQueueKey = this.keys.masterQueueKey(shardId);
     const inflightDataKey = this.keys.inflightDataKey(shardId);
     const dataJson = await this.redis.hget(inflightDataKey, messageId);
     let storedMessage = null;
@@ -15192,13 +15798,16 @@ var FairQueue = class {
       id: queueId,
       tenantId: storedMessage.tenantId,
       metadata: storedMessage.metadata ?? {}
-    } : { id: queueId, tenantId: "", metadata: {} };
+    } : { id: queueId, tenantId: this.keys.extractTenantId(queueId), metadata: {} };
     await this.visibilityManager.complete(messageId, queueId);
     if (this.concurrencyManager && storedMessage) {
       await this.concurrencyManager.release(descriptor, messageId);
     }
-    const removed = await this.redis.updateMasterQueueIfEmpty(masterQueueKey, queueKey, queueId);
-    if (removed === 1) {
+    const { queueEmpty } = await this.#updateAllIndexesAfterDequeue(
+      queueId,
+      descriptor.tenantId
+    );
+    if (queueEmpty) {
       this.queueDescriptorCache.delete(queueId);
       this.queueCooloffStates.delete(queueId);
     }
@@ -15219,7 +15828,6 @@ var FairQueue = class {
     const shardId = this.masterQueue.getShardForQueue(queueId);
     const queueKey = this.keys.queueKey(queueId);
     const queueItemsKey = this.keys.queueItemsKey(queueId);
-    const masterQueueKey = this.keys.masterQueueKey(shardId);
     const inflightDataKey = this.keys.inflightDataKey(shardId);
     const dataJson = await this.redis.hget(inflightDataKey, messageId);
     let storedMessage = null;
@@ -15233,13 +15841,18 @@ var FairQueue = class {
       id: queueId,
       tenantId: storedMessage.tenantId,
       metadata: storedMessage.metadata ?? {}
-    } : { id: queueId, tenantId: "", metadata: {} };
+    } : { id: queueId, tenantId: this.keys.extractTenantId(queueId), metadata: {} };
+    const dispatchShardId = this.tenantDispatch.getShardForTenant(descriptor.tenantId);
+    const tenantQueueIndexKey = this.keys.tenantQueueIndexKey(descriptor.tenantId);
+    const dispatchKey = this.keys.dispatchKey(dispatchShardId);
     await this.visibilityManager.release(
       messageId,
       queueId,
       queueKey,
       queueItemsKey,
-      masterQueueKey,
+      tenantQueueIndexKey,
+      dispatchKey,
+      descriptor.tenantId,
       Date.now()
       // Put at back of queue
     );
@@ -15263,7 +15876,6 @@ var FairQueue = class {
     const shardId = this.masterQueue.getShardForQueue(queueId);
     const queueKey = this.keys.queueKey(queueId);
     const queueItemsKey = this.keys.queueItemsKey(queueId);
-    const masterQueueKey = this.keys.masterQueueKey(shardId);
     const inflightDataKey = this.keys.inflightDataKey(shardId);
     const dataJson = await this.redis.hget(inflightDataKey, messageId);
     if (!dataJson) {
@@ -15285,12 +15897,13 @@ var FairQueue = class {
       tenantId: storedMessage.tenantId,
       metadata: storedMessage.metadata ?? {}
     };
+    const dispatchShardId = this.tenantDispatch.getShardForTenant(descriptor.tenantId);
     await this.#handleMessageFailure(
       storedMessage,
       queueId,
       queueKey,
       queueItemsKey,
-      masterQueueKey,
+      dispatchShardId,
       descriptor,
       error
     );
@@ -15298,7 +15911,7 @@ var FairQueue = class {
   // ============================================================================
   // Private - Message Processing Helpers
   // ============================================================================
-  async #handleMessageFailure(storedMessage, queueId, queueKey, queueItemsKey, masterQueueKey, descriptor, error) {
+  async #handleMessageFailure(storedMessage, queueId, queueKey, queueItemsKey, dispatchShardId, descriptor, error) {
     this.telemetry.recordFailure();
     if (this.retryStrategy) {
       const nextDelay = this.retryStrategy.getNextDelay(storedMessage.attempt, error);
@@ -15307,15 +15920,19 @@ var FairQueue = class {
           ...storedMessage,
           attempt: storedMessage.attempt + 1
         };
+        const tenantQueueIndexKey = this.keys.tenantQueueIndexKey(descriptor.tenantId);
+        const dispatchKey = this.keys.dispatchKey(dispatchShardId);
         await this.visibilityManager.release(
           storedMessage.id,
           queueId,
           queueKey,
           queueItemsKey,
-          masterQueueKey,
-          Date.now() + nextDelay
+          tenantQueueIndexKey,
+          dispatchKey,
+          descriptor.tenantId,
+          Date.now() + nextDelay,
+          JSON.stringify(updatedMessage)
         );
-        await this.redis.hset(queueItemsKey, storedMessage.id, JSON.stringify(updatedMessage));
         if (this.concurrencyManager) {
           await this.concurrencyManager.release(descriptor, storedMessage.id);
         }
@@ -15393,28 +16010,36 @@ var FairQueue = class {
   async #reclaimTimedOutMessages() {
     let totalReclaimed = 0;
     for (let shardId = 0; shardId < this.shardCount; shardId++) {
-      const reclaimedMessages = await this.visibilityManager.reclaimTimedOut(shardId, (queueId) => ({
-        queueKey: this.keys.queueKey(queueId),
-        queueItemsKey: this.keys.queueItemsKey(queueId),
-        masterQueueKey: this.keys.masterQueueKey(this.masterQueue.getShardForQueue(queueId))
-      }));
-      if (this.concurrencyManager && reclaimedMessages.length > 0) {
-        try {
-          await this.concurrencyManager.releaseBatch(
-            reclaimedMessages.map((msg) => ({
-              queue: {
-                id: msg.queueId,
-                tenantId: msg.tenantId,
-                metadata: msg.metadata ?? {}
-              },
-              messageId: msg.messageId
-            }))
-          );
-        } catch (error) {
-          this.logger.error("Failed to release concurrency for reclaimed messages", {
-            count: reclaimedMessages.length,
-            error: error instanceof Error ? error.message : String(error)
-          });
+      const reclaimedMessages = await this.visibilityManager.reclaimTimedOut(shardId, (queueId) => {
+        const tenantId = this.keys.extractTenantId(queueId);
+        const dispatchShardId = this.tenantDispatch.getShardForTenant(tenantId);
+        return {
+          queueKey: this.keys.queueKey(queueId),
+          queueItemsKey: this.keys.queueItemsKey(queueId),
+          tenantQueueIndexKey: this.keys.tenantQueueIndexKey(tenantId),
+          dispatchKey: this.keys.dispatchKey(dispatchShardId),
+          tenantId
+        };
+      });
+      if (reclaimedMessages.length > 0) {
+        if (this.concurrencyManager) {
+          try {
+            await this.concurrencyManager.releaseBatch(
+              reclaimedMessages.map((msg) => ({
+                queue: {
+                  id: msg.queueId,
+                  tenantId: msg.tenantId,
+                  metadata: msg.metadata ?? {}
+                },
+                messageId: msg.messageId
+              }))
+            );
+          } catch (error) {
+            this.logger.error("Failed to release concurrency for reclaimed messages", {
+              count: reclaimedMessages.length,
+              error: error instanceof Error ? error.message : String(error)
+            });
+          }
         }
       }
       totalReclaimed += reclaimedMessages.length;
@@ -15476,6 +16101,32 @@ var FairQueue = class {
   // ============================================================================
   // Private - Helpers
   // ============================================================================
+  /**
+   * Update both old master queue and new dispatch indexes after a dequeue/complete.
+   * Both calls are idempotent - ZREM on a non-existent member is a no-op.
+   * This handles the transition period where queues may exist in either or both indexes.
+   */
+  async #updateAllIndexesAfterDequeue(queueId, tenantId) {
+    const queueShardId = this.masterQueue.getShardForQueue(queueId);
+    const dispatchShardId = this.tenantDispatch.getShardForTenant(tenantId);
+    const queueKey = this.keys.queueKey(queueId);
+    const masterQueueKey = this.keys.masterQueueKey(queueShardId);
+    const tenantQueueIndexKey = this.keys.tenantQueueIndexKey(tenantId);
+    const dispatchKey = this.keys.dispatchKey(dispatchShardId);
+    const removedFromMaster = await this.redis.updateMasterQueueIfEmpty(
+      masterQueueKey,
+      queueKey,
+      queueId
+    );
+    const removedFromDispatch = await this.redis.updateDispatchIndexes(
+      queueKey,
+      tenantQueueIndexKey,
+      dispatchKey,
+      queueId,
+      tenantId
+    );
+    return { queueEmpty: removedFromMaster === 1 || removedFromDispatch === 1 };
+  }
   #createSchedulerContext() {
     return {
       getCurrentConcurrency: async (groupName, groupId) => {
@@ -15515,13 +16166,9 @@ 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)
@@ -15539,20 +16186,14 @@ 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)
@@ -15572,11 +16213,119 @@ local count = redis.call('ZCARD', queueKey)
 if count == 0 then
   redis.call('ZREM', masterQueueKey, queueId)
   return 1
+end
+
+-- Queue still has messages but don't re-add to legacy master queue.
+-- New enqueues go through the V2 dispatch path, so we only drain here.
+-- Just remove it so it doesn't linger.
+redis.call('ZREM', masterQueueKey, queueId)
+return 0
+      `
+    });
+    this.redis.defineCommand("enqueueMessageAtomicV2", {
+      numberOfKeys: 4,
+      lua: `
+local queueKey = KEYS[1]
+local queueItemsKey = KEYS[2]
+local tenantQueueIndexKey = KEYS[3]
+local dispatchKey = KEYS[4]
+
+local queueId = ARGV[1]
+local messageId = ARGV[2]
+local timestamp = tonumber(ARGV[3])
+local payload = ARGV[4]
+local tenantId = ARGV[5]
+
+-- Add to per-queue storage (same as before)
+redis.call('ZADD', queueKey, timestamp, messageId)
+redis.call('HSET', queueItemsKey, messageId, payload)
+
+-- Update tenant queue index (Level 2) with queue's oldest message
+local oldest = redis.call('ZRANGE', queueKey, 0, 0, 'WITHSCORES')
+if #oldest >= 2 then
+  redis.call('ZADD', tenantQueueIndexKey, oldest[2], queueId)
+end
+
+-- Update dispatch index (Level 1) with tenant's oldest across all queues
+local tenantOldest = redis.call('ZRANGE', tenantQueueIndexKey, 0, 0, 'WITHSCORES')
+if #tenantOldest >= 2 then
+  redis.call('ZADD', dispatchKey, tenantOldest[2], tenantId)
+end
+
+return 1
+      `
+    });
+    this.redis.defineCommand("enqueueBatchAtomicV2", {
+      numberOfKeys: 4,
+      lua: `
+local queueKey = KEYS[1]
+local queueItemsKey = KEYS[2]
+local tenantQueueIndexKey = KEYS[3]
+local dispatchKey = KEYS[4]
+
+local queueId = ARGV[1]
+local tenantId = ARGV[2]
+
+-- Args after queueId and tenantId are triples: [messageId, timestamp, payload, ...]
+for i = 3, #ARGV, 3 do
+  local messageId = ARGV[i]
+  local timestamp = tonumber(ARGV[i + 1])
+  local payload = ARGV[i + 2]
+  redis.call('ZADD', queueKey, timestamp, messageId)
+  redis.call('HSET', queueItemsKey, messageId, payload)
+end
+
+-- Update tenant queue index (Level 2)
+local oldest = redis.call('ZRANGE', queueKey, 0, 0, 'WITHSCORES')
+if #oldest >= 2 then
+  redis.call('ZADD', tenantQueueIndexKey, oldest[2], queueId)
+end
+
+-- Update dispatch index (Level 1)
+local tenantOldest = redis.call('ZRANGE', tenantQueueIndexKey, 0, 0, 'WITHSCORES')
+if #tenantOldest >= 2 then
+  redis.call('ZADD', dispatchKey, tenantOldest[2], tenantId)
+end
+
+return (#ARGV - 2) / 3
+      `
+    });
+    this.redis.defineCommand("updateDispatchIndexes", {
+      numberOfKeys: 3,
+      lua: `
+local queueKey = KEYS[1]
+local tenantQueueIndexKey = KEYS[2]
+local dispatchKey = KEYS[3]
+local queueId = ARGV[1]
+local tenantId = ARGV[2]
+
+local count = redis.call('ZCARD', queueKey)
+if count == 0 then
+  -- Queue is empty: remove from tenant queue index
+  redis.call('ZREM', tenantQueueIndexKey, queueId)
+
+  -- Check if tenant has any queues left
+  local tenantQueueCount = redis.call('ZCARD', tenantQueueIndexKey)
+  if tenantQueueCount == 0 then
+    -- No more queues: remove tenant from dispatch
+    redis.call('ZREM', dispatchKey, tenantId)
+  else
+    -- Update dispatch score to tenant's new oldest
+    local tenantOldest = redis.call('ZRANGE', tenantQueueIndexKey, 0, 0, 'WITHSCORES')
+    if #tenantOldest >= 2 then
+      redis.call('ZADD', dispatchKey, tenantOldest[2], tenantId)
+    end
+  end
+  return 1
 else
-  -- Update with oldest message timestamp
+  -- Queue still has messages: update scores
   local oldest = redis.call('ZRANGE', queueKey, 0, 0, 'WITHSCORES')
   if #oldest >= 2 then
-    redis.call('ZADD', masterQueueKey, oldest[2], queueId)
+    redis.call('ZADD', tenantQueueIndexKey, oldest[2], queueId)
+  end
+  local tenantOldest = redis.call('ZRANGE', tenantQueueIndexKey, 0, 0, 'WITHSCORES')
+  if #tenantOldest >= 2 then
+    redis.call('ZADD', dispatchKey, tenantOldest[2], tenantId)
   end
   return 0
 end
@@ -15588,6 +16337,6 @@ end
   }
 };
 
-export { BaseScheduler, BatchedSpanManager, CallbackFairQueueKeyProducer, ConcurrencyManager, CronSchema, CustomRetry, DRRScheduler, DefaultFairQueueKeyProducer, ExponentialBackoffRetry, FairQueue, FairQueueAttributes, FairQueueTelemetry, FixedDelayRetry, ImmediateRetry, LinearBackoffRetry, MasterQueue, MessagingAttributes, NoRetry, NoopScheduler, RoundRobinScheduler, SimpleQueue, VisibilityManager, WeightedScheduler, Worker, WorkerQueueManager, createDefaultRetryStrategy, defaultRetryOptions, isAbortError, noopTelemetry };
+export { BaseScheduler, BatchedSpanManager, CallbackFairQueueKeyProducer, ConcurrencyManager, CronSchema, CustomRetry, DRRScheduler, DefaultFairQueueKeyProducer, ExponentialBackoffRetry, FairQueue, FairQueueAttributes, FairQueueTelemetry, FixedDelayRetry, ImmediateRetry, LinearBackoffRetry, MasterQueue, MessagingAttributes, NoRetry, NoopScheduler, RoundRobinScheduler, SimpleQueue, TenantDispatch, VisibilityManager, WeightedScheduler, Worker, WorkerQueueManager, createDefaultRetryStrategy, defaultRetryOptions, isAbortError, noopTelemetry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map