@trigger.dev/redis-worker 4.5.0-rc.7 → 4.5.1

package/dist/index.d.ts

@@ -64,6 +64,22 @@ declare class SimpleQueue<TMessageCatalog extends MessageCatalogSchema> {
     size({ includeFuture }?: {
         includeFuture?: boolean;
     }): Promise<number>;
+    /**
+     * Age (in ms) of the oldest *overdue* message — the oldest item whose scheduled
+     * time has already passed (score <= now). Returns 0 when the queue is empty or
+     * only holds future/delayed or in-flight (future-scored) items.
+     *
+     * Resolves the candidate against the `items` hash so orphaned `queue` entries
+     * (a member whose payload is missing — the same stale state `dequeueItems`
+     * cleans up) don't report a phantom stall for work that can't be dequeued. The
+     * Lua scans due items oldest-first and returns the first score whose payload
+     * still exists.
+     *
+     * This is the generic stall signal: it stays at 0 while a queue drains healthily
+     * and rises only when due work sits undrained (poison block, dead consumer,
+     * backpressure).
+     */
+    oldestMessageAge(): Promise<number>;
     getJob(id: string): Promise<QueueItem<TMessageCatalog> | null>;
     moveToDeadLetterQueue(id: string, errorMessage: string): Promise<void>;
     sizeOfDeadLetterQueue(): Promise<number>;
@@ -80,6 +96,7 @@ declare module "@internal/redis" {
         moveToDeadLetterQueue(queue: string, items: string, dlq: string, dlqItems: string, id: string, errorMessage: string, callback?: Callback<number>): Result<number, Context>;
         enqueueItemOnce(queue: string, items: string, id: string, score: number, serializedItem: string, callback?: Callback<number>): Result<number, Context>;
         getJob(queue: string, items: string, id: string, callback?: Callback<[string, string, string] | null>): Result<[string, string, string] | null, Context>;
+        getOldestDueScore(queue: string, items: string, now: number, callback?: Callback<string | number>): Result<string | number, Context>;
     }
 }
 
@@ -893,6 +910,101 @@ interface WeightedSchedulerConfig {
     tracer?: Tracer;
 }
 
+interface ConcurrencyManagerOptions {
+    redis: RedisOptions;
+    keys: FairQueueKeyProducer;
+    groups: ConcurrencyGroupConfig[];
+}
+/**
+ * ConcurrencyManager handles multi-level concurrency tracking and limiting.
+ *
+ * Features:
+ * - Multiple concurrent concurrency groups (tenant, org, project, etc.)
+ * - Atomic reserve/release operations using Lua scripts
+ * - Efficient batch checking of all groups
+ */
+declare class ConcurrencyManager {
+    #private;
+    private options;
+    private redis;
+    private keys;
+    private groups;
+    private groupsByName;
+    constructor(options: ConcurrencyManagerOptions);
+    /**
+     * Check if a message can be processed given all concurrency constraints.
+     * Checks all configured groups and returns the first one at capacity.
+     */
+    canProcess(queue: QueueDescriptor): Promise<ConcurrencyCheckResult>;
+    /**
+     * 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
+     */
+    reserve(queue: QueueDescriptor, messageId: string): Promise<boolean>;
+    /**
+     * Release concurrency slots for a message across all groups.
+     */
+    release(queue: QueueDescriptor, messageId: string): Promise<void>;
+    /**
+     * Release concurrency slots for multiple messages in a single pipeline.
+     * More efficient than calling release() multiple times.
+     */
+    releaseBatch(messages: Array<{
+        queue: QueueDescriptor;
+        messageId: string;
+    }>): Promise<void>;
+    /**
+     * Get current concurrency for a specific group.
+     */
+    getCurrentConcurrency(groupName: string, groupId: string): Promise<number>;
+    /**
+     * Get available capacity for a queue across all concurrency groups.
+     * Returns the minimum available capacity across all groups.
+     */
+    getAvailableCapacity(queue: QueueDescriptor): Promise<number>;
+    /**
+     * Get concurrency limit for a specific group.
+     */
+    getConcurrencyLimit(groupName: string, groupId: string): Promise<number>;
+    /**
+     * Check if a group is at capacity.
+     */
+    isAtCapacity(groupName: string, groupId: string): Promise<boolean>;
+    /**
+     * Get full state for a group.
+     */
+    getState(groupName: string, groupId: string): Promise<ConcurrencyState>;
+    /**
+     * Get all active message IDs for a group.
+     */
+    getActiveMessages(groupName: string, groupId: string): Promise<string[]>;
+    /**
+     * Force-clear concurrency for a group (use with caution).
+     * Useful for cleanup after crashes.
+     */
+    clearGroup(groupName: string, groupId: string): Promise<void>;
+    /**
+     * Remove a specific message from concurrency tracking.
+     * Useful for cleanup.
+     */
+    removeMessage(messageId: string, queue: QueueDescriptor): Promise<void>;
+    /**
+     * Get configured group names.
+     */
+    getGroupNames(): string[];
+    /**
+     * Close the Redis connection.
+     */
+    close(): Promise<void>;
+}
+declare module "@internal/redis" {
+    interface RedisCommander<Context> {
+        reserveConcurrency(numKeys: number, keys: string[], messageId: string, ...limits: string[]): Promise<number>;
+    }
+}
+
 /**
  * Default key producer for the fair queue system.
  * Uses a configurable prefix and standard key structure.
@@ -1051,479 +1163,132 @@ declare module "@internal/redis" {
     }
 }
 
-interface ConcurrencyManagerOptions {
-    redis: RedisOptions;
-    keys: FairQueueKeyProducer;
-    groups: ConcurrencyGroupConfig[];
-}
 /**
- * ConcurrencyManager handles multi-level concurrency tracking and limiting.
- *
- * Features:
- * - Multiple concurrent concurrency groups (tenant, org, project, etc.)
- * - Atomic reserve/release operations using Lua scripts
- * - Efficient batch checking of all groups
+ * Base class for scheduler implementations.
+ * Provides common utilities and default implementations.
  */
-declare class ConcurrencyManager {
-    #private;
-    private options;
-    private redis;
-    private keys;
-    private groups;
-    private groupsByName;
-    constructor(options: ConcurrencyManagerOptions);
+declare abstract class BaseScheduler implements FairScheduler {
     /**
-     * Check if a message can be processed given all concurrency constraints.
-     * Checks all configured groups and returns the first one at capacity.
+     * Select queues for processing from a master queue shard.
+     * Must be implemented by subclasses.
      */
-    canProcess(queue: QueueDescriptor): Promise<ConcurrencyCheckResult>;
+    abstract selectQueues(masterQueueShard: string, consumerId: string, context: SchedulerContext): Promise<TenantQueues[]>;
     /**
-     * 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
+     * Called after processing a message to update scheduler state.
+     * Default implementation does nothing.
      */
-    reserve(queue: QueueDescriptor, messageId: string): Promise<boolean>;
+    recordProcessed(_tenantId: string, _queueId: string): Promise<void>;
     /**
-     * Release concurrency slots for a message across all groups.
+     * Called after processing multiple messages to update scheduler state.
+     * Batch variant for efficiency - reduces Redis calls when processing multiple messages.
+     * Default implementation does nothing.
      */
-    release(queue: QueueDescriptor, messageId: string): Promise<void>;
+    recordProcessedBatch(_tenantId: string, _queueId: string, _count: number): Promise<void>;
     /**
-     * Release concurrency slots for multiple messages in a single pipeline.
-     * More efficient than calling release() multiple times.
+     * Initialize the scheduler.
+     * Default implementation does nothing.
      */
-    releaseBatch(messages: Array<{
-        queue: QueueDescriptor;
-        messageId: string;
-    }>): Promise<void>;
+    initialize(): Promise<void>;
     /**
-     * Get current concurrency for a specific group.
+     * Cleanup scheduler resources.
+     * Default implementation does nothing.
      */
-    getCurrentConcurrency(groupName: string, groupId: string): Promise<number>;
+    close(): Promise<void>;
     /**
-     * Get available capacity for a queue across all concurrency groups.
-     * Returns the minimum available capacity across all groups.
+     * Helper to group queues by tenant.
      */
-    getAvailableCapacity(queue: QueueDescriptor): Promise<number>;
+    protected groupQueuesByTenant(queues: Array<{
+        queueId: string;
+        tenantId: string;
+    }>): Map<string, string[]>;
     /**
-     * Get concurrency limit for a specific group.
+     * Helper to convert grouped queues to TenantQueues array.
      */
-    getConcurrencyLimit(groupName: string, groupId: string): Promise<number>;
+    protected toTenantQueuesArray(grouped: Map<string, string[]>): TenantQueues[];
     /**
-     * Check if a group is at capacity.
+     * Helper to filter out tenants at capacity.
      */
-    isAtCapacity(groupName: string, groupId: string): Promise<boolean>;
+    protected filterAtCapacity(tenants: TenantQueues[], context: SchedulerContext, groupName?: string): Promise<TenantQueues[]>;
+}
+/**
+ * Simple noop scheduler that returns empty results.
+ * Useful for testing or disabling scheduling.
+ */
+declare class NoopScheduler extends BaseScheduler {
+    selectQueues(_masterQueueShard: string, _consumerId: string, _context: SchedulerContext): Promise<TenantQueues[]>;
+}
+
+/**
+ * Deficit Round Robin (DRR) Scheduler.
+ *
+ * DRR ensures fair processing across tenants by:
+ * - Allocating a "quantum" of credits to each tenant per round
+ * - Accumulating unused credits as "deficit"
+ * - Processing from tenants with available deficit
+ * - Capping deficit to prevent starvation
+ *
+ * Key improvements over basic implementations:
+ * - Atomic deficit operations using Lua scripts
+ * - Efficient iteration through tenants
+ * - Automatic deficit cleanup for inactive tenants
+ */
+declare class DRRScheduler extends BaseScheduler {
+    #private;
+    private config;
+    private redis;
+    private keys;
+    private quantum;
+    private maxDeficit;
+    private masterQueueLimit;
+    private logger;
+    constructor(config: DRRSchedulerConfig);
     /**
-     * Get full state for a group.
+     * 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)
      */
-    getState(groupName: string, groupId: string): Promise<ConcurrencyState>;
+    selectQueues(masterQueueShard: string, consumerId: string, context: SchedulerContext): Promise<TenantQueues[]>;
     /**
-     * Get all active message IDs for a group.
+     * 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
      */
-    getActiveMessages(groupName: string, groupId: string): Promise<string[]>;
+    selectQueuesFromDispatch(dispatchShardKey: string, consumerId: string, context: DispatchSchedulerContext): Promise<TenantQueues[]>;
     /**
-     * Force-clear concurrency for a group (use with caution).
-     * Useful for cleanup after crashes.
+     * Record that a message was processed from a tenant.
+     * Decrements the tenant's deficit.
      */
-    clearGroup(groupName: string, groupId: string): Promise<void>;
+    recordProcessed(tenantId: string, _queueId: string): Promise<void>;
     /**
-     * Remove a specific message from concurrency tracking.
-     * Useful for cleanup.
+     * Record that multiple messages were processed from a tenant.
+     * Decrements the tenant's deficit by count atomically.
      */
-    removeMessage(messageId: string, queue: QueueDescriptor): Promise<void>;
+    recordProcessedBatch(tenantId: string, _queueId: string, count: number): Promise<void>;
+    close(): Promise<void>;
     /**
-     * Get configured group names.
+     * Get the current deficit for a tenant.
      */
-    getGroupNames(): string[];
+    getDeficit(tenantId: string): Promise<number>;
     /**
-     * Close the Redis connection.
+     * Reset deficit for a tenant.
+     * Used when a tenant has no more active queues.
      */
-    close(): Promise<void>;
-}
-declare module "@internal/redis" {
-    interface RedisCommander<Context> {
-        reserveConcurrency(numKeys: number, keys: string[], messageId: string, ...limits: string[]): Promise<number>;
-    }
-}
-
-interface VisibilityManagerOptions {
-    redis: RedisOptions;
-    keys: FairQueueKeyProducer;
-    shardCount: number;
-    defaultTimeoutMs: number;
-    logger?: {
-        debug: (message: string, context?: Record<string, unknown>) => void;
-        error: (message: string, context?: Record<string, unknown>) => void;
-    };
-}
-/**
- * VisibilityManager handles message visibility timeouts for safe message processing.
- *
- * Features:
- * - Claim messages with visibility timeout
- * - Heartbeat to extend timeout
- * - Automatic reclaim of timed-out messages
- * - Per-shard in-flight tracking
- *
- * Data structures:
- * - In-flight sorted set: score = deadline timestamp, member = "{messageId}:{queueId}"
- * - In-flight data hash: field = messageId, value = JSON message data
- */
-declare class VisibilityManager {
-    #private;
-    private options;
-    private redis;
-    private keys;
-    private shardCount;
-    private defaultTimeoutMs;
-    private logger;
-    constructor(options: VisibilityManagerOptions);
-    /**
-     * 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
-     */
-    claim<TPayload = unknown>(queueId: string, queueKey: string, queueItemsKey: string, consumerId: string, timeoutMs?: number): Promise<ClaimResult<TPayload>>;
-    /**
-     * Claim multiple messages for processing (batch claim).
-     * Moves up to maxCount messages from the queue to the in-flight set.
-     *
-     * @param queueId - The queue to claim from
-     * @param queueKey - The Redis key for the queue sorted set
-     * @param queueItemsKey - The Redis key for the queue items hash
-     * @param consumerId - ID of the consumer claiming the messages
-     * @param maxCount - Maximum number of messages to claim
-     * @param timeoutMs - Visibility timeout in milliseconds
-     * @returns Array of claimed messages
-     */
-    claimBatch<TPayload = unknown>(queueId: string, queueKey: string, queueItemsKey: string, consumerId: string, maxCount: number, timeoutMs?: number): Promise<Array<InFlightMessage<TPayload>>>;
-    /**
-     * 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
-     */
-    heartbeat(messageId: string, queueId: string, extendMs: number): Promise<boolean>;
-    /**
-     * Mark a message as successfully processed.
-     * Removes the message from in-flight tracking.
-     *
-     * @param messageId - The message ID
-     * @param queueId - The queue ID
-     */
-    complete(messageId: string, queueId: string): Promise<void>;
-    /**
-     * 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 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)
-     */
-    release<TPayload = unknown>(messageId: string, queueId: string, queueKey: string, queueItemsKey: string, tenantQueueIndexKey: string, dispatchKey: string, tenantId: string, score?: number, updatedData?: string): Promise<void>;
-    /**
-     * Release multiple messages back to their queue in a single operation.
-     * Used when processing fails or consumer wants to retry later.
-     * All messages must belong to the same queue.
-     *
-     * @param messages - Array of messages to release (must all have same queueId)
-     * @param queueId - The queue ID
-     * @param queueKey - The Redis key for the queue
-     * @param queueItemsKey - The Redis key for the queue items hash
-     * @param 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)
-     */
-    releaseBatch(messages: Array<{
-        messageId: string;
-    }>, queueId: string, queueKey: string, queueItemsKey: string, tenantQueueIndexKey: string, dispatchKey: string, tenantId: string, score?: number): Promise<void>;
-    /**
-     * 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 Array of reclaimed message info for concurrency release
-     */
-    reclaimTimedOut(shardId: number, getQueueKeys: (queueId: string) => {
-        queueKey: string;
-        queueItemsKey: string;
-        tenantQueueIndexKey: string;
-        dispatchKey: string;
-        tenantId: string;
-    }): Promise<ReclaimedMessageInfo[]>;
-    /**
-     * Get all in-flight messages for a shard.
-     */
-    getInflightMessages(shardId: number): Promise<Array<{
-        messageId: string;
-        queueId: string;
-        deadline: number;
-    }>>;
-    /**
-     * Get count of in-flight messages for a shard.
-     */
-    getInflightCount(shardId: number): Promise<number>;
-    /**
-     * Get total in-flight count across all shards.
-     */
-    getTotalInflightCount(): Promise<number>;
-    /**
-     * Close the Redis connection.
-     */
-    close(): Promise<void>;
-}
-declare module "@internal/redis" {
-    interface RedisCommander<Context> {
-        claimMessage(queueKey: string, queueItemsKey: string, inflightKey: string, inflightDataKey: string, queueId: string, consumerId: string, deadline: string): Promise<[string, string] | null>;
-        claimMessageBatch(queueKey: string, queueItemsKey: string, inflightKey: string, inflightDataKey: string, queueId: string, deadline: string, maxCount: string): Promise<string[]>;
-        releaseMessage(inflightKey: string, inflightDataKey: string, queueKey: string, queueItemsKey: string, tenantQueueIndexKey: string, dispatchKey: string, member: string, messageId: string, score: string, queueId: string, updatedData: string, tenantId: string): Promise<number>;
-        releaseMessageBatch(inflightKey: string, inflightDataKey: string, queueKey: string, queueItemsKey: string, tenantQueueIndexKey: string, dispatchKey: string, score: string, queueId: string, tenantId: string, ...membersAndMessageIds: string[]): Promise<number>;
-        heartbeatMessage(inflightKey: string, member: string, newDeadline: string): Promise<number>;
-    }
-}
-
-interface WorkerQueueManagerOptions {
-    redis: RedisOptions;
-    keys: FairQueueKeyProducer;
-    logger?: {
-        debug: (message: string, context?: Record<string, unknown>) => void;
-        error: (message: string, context?: Record<string, unknown>) => void;
-    };
-}
-/**
- * WorkerQueueManager handles the intermediate worker queue layer.
- *
- * This provides:
- * - Low-latency message delivery via blocking pop (BLPOP)
- * - Routing of messages to specific workers/consumers
- * - Efficient waiting without polling
- *
- * Flow:
- * 1. Master queue consumer claims message from message queue
- * 2. Message key is pushed to worker queue
- * 3. Worker queue consumer does blocking pop to receive message
- */
-declare class WorkerQueueManager {
-    #private;
-    private options;
-    private redis;
-    private keys;
-    private logger;
-    constructor(options: WorkerQueueManagerOptions);
-    /**
-     * 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")
-     */
-    push(workerQueueId: string, messageKey: string): Promise<void>;
-    /**
-     * Push multiple message keys to a worker queue.
-     *
-     * @param workerQueueId - The worker queue identifier
-     * @param messageKeys - The message keys to push
-     */
-    pushBatch(workerQueueId: string, messageKeys: string[]): Promise<void>;
-    /**
-     * 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
-     */
-    blockingPop(workerQueueId: string, timeoutSeconds: number, signal?: AbortSignal): Promise<string | null>;
-    /**
-     * Non-blocking pop from a worker queue.
-     *
-     * @param workerQueueId - The worker queue identifier
-     * @returns The message key and queue length, or null if empty
-     */
-    pop(workerQueueId: string): Promise<{
-        messageKey: string;
-        queueLength: number;
-    } | null>;
-    /**
-     * Get the current length of a worker queue.
-     */
-    getLength(workerQueueId: string): Promise<number>;
-    /**
-     * Peek at all messages in a worker queue without removing them.
-     * Useful for debugging and tests.
-     */
-    peek(workerQueueId: string): Promise<string[]>;
-    /**
-     * 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
-     */
-    remove(workerQueueId: string, messageKey: string): Promise<number>;
-    /**
-     * Clear all messages from a worker queue.
-     */
-    clear(workerQueueId: string): Promise<void>;
-    /**
-     * Close the Redis connection.
-     */
-    close(): Promise<void>;
-    /**
-     * Register custom commands on an external Redis client.
-     * Use this when initializing FairQueue with worker queues.
-     */
-    registerCommands(redis: Redis): void;
-}
-declare module "@internal/redis" {
-    interface RedisCommander<Context> {
-        popWithLength(workerQueueKey: string): Promise<[string, string] | null>;
-    }
-}
-
-/**
- * Base class for scheduler implementations.
- * Provides common utilities and default implementations.
- */
-declare abstract class BaseScheduler implements FairScheduler {
-    /**
-     * Select queues for processing from a master queue shard.
-     * Must be implemented by subclasses.
-     */
-    abstract selectQueues(masterQueueShard: string, consumerId: string, context: SchedulerContext): Promise<TenantQueues[]>;
-    /**
-     * Called after processing a message to update scheduler state.
-     * Default implementation does nothing.
-     */
-    recordProcessed(_tenantId: string, _queueId: string): Promise<void>;
-    /**
-     * Called after processing multiple messages to update scheduler state.
-     * Batch variant for efficiency - reduces Redis calls when processing multiple messages.
-     * Default implementation does nothing.
-     */
-    recordProcessedBatch(_tenantId: string, _queueId: string, _count: number): Promise<void>;
-    /**
-     * Initialize the scheduler.
-     * Default implementation does nothing.
-     */
-    initialize(): Promise<void>;
-    /**
-     * Cleanup scheduler resources.
-     * Default implementation does nothing.
-     */
-    close(): Promise<void>;
-    /**
-     * Helper to group queues by tenant.
-     */
-    protected groupQueuesByTenant(queues: Array<{
-        queueId: string;
-        tenantId: string;
-    }>): Map<string, string[]>;
-    /**
-     * Helper to convert grouped queues to TenantQueues array.
-     */
-    protected toTenantQueuesArray(grouped: Map<string, string[]>): TenantQueues[];
-    /**
-     * Helper to filter out tenants at capacity.
-     */
-    protected filterAtCapacity(tenants: TenantQueues[], context: SchedulerContext, groupName?: string): Promise<TenantQueues[]>;
-}
-/**
- * Simple noop scheduler that returns empty results.
- * Useful for testing or disabling scheduling.
- */
-declare class NoopScheduler extends BaseScheduler {
-    selectQueues(_masterQueueShard: string, _consumerId: string, _context: SchedulerContext): Promise<TenantQueues[]>;
-}
-
-/**
- * Deficit Round Robin (DRR) Scheduler.
- *
- * DRR ensures fair processing across tenants by:
- * - Allocating a "quantum" of credits to each tenant per round
- * - Accumulating unused credits as "deficit"
- * - Processing from tenants with available deficit
- * - Capping deficit to prevent starvation
- *
- * Key improvements over basic implementations:
- * - Atomic deficit operations using Lua scripts
- * - Efficient iteration through tenants
- * - Automatic deficit cleanup for inactive tenants
- */
-declare class DRRScheduler extends BaseScheduler {
-    #private;
-    private config;
-    private redis;
-    private keys;
-    private quantum;
-    private maxDeficit;
-    private masterQueueLimit;
-    private logger;
-    constructor(config: DRRSchedulerConfig);
-    /**
-     * 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)
-     */
-    selectQueues(masterQueueShard: string, consumerId: string, context: SchedulerContext): Promise<TenantQueues[]>;
-    /**
-     * 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
-     */
-    selectQueuesFromDispatch(dispatchShardKey: string, consumerId: string, context: DispatchSchedulerContext): Promise<TenantQueues[]>;
-    /**
-     * Record that a message was processed from a tenant.
-     * Decrements the tenant's deficit.
-     */
-    recordProcessed(tenantId: string, _queueId: string): Promise<void>;
-    /**
-     * Record that multiple messages were processed from a tenant.
-     * Decrements the tenant's deficit by count atomically.
-     */
-    recordProcessedBatch(tenantId: string, _queueId: string, count: number): Promise<void>;
-    close(): Promise<void>;
-    /**
-     * Get the current deficit for a tenant.
-     */
-    getDeficit(tenantId: string): Promise<number>;
-    /**
-     * Reset deficit for a tenant.
-     * Used when a tenant has no more active queues.
-     */
-    resetDeficit(tenantId: string): Promise<void>;
-    /**
-     * Get all tenant deficits.
-     */
-    getAllDeficits(): Promise<Map<string, number>>;
+    resetDeficit(tenantId: string): Promise<void>;
+    /**
+     * Get all tenant deficits.
+     */
+    getAllDeficits(): Promise<Map<string, number>>;
 }
 declare module "@internal/redis" {
     interface RedisCommander<Context> {
@@ -1925,6 +1690,258 @@ declare class TenantDispatch {
     close(): Promise<void>;
 }
 
+interface VisibilityManagerOptions {
+    redis: RedisOptions;
+    keys: FairQueueKeyProducer;
+    shardCount: number;
+    defaultTimeoutMs: number;
+    logger?: {
+        debug: (message: string, context?: Record<string, unknown>) => void;
+        error: (message: string, context?: Record<string, unknown>) => void;
+    };
+}
+/**
+ * VisibilityManager handles message visibility timeouts for safe message processing.
+ *
+ * Features:
+ * - Claim messages with visibility timeout
+ * - Heartbeat to extend timeout
+ * - Automatic reclaim of timed-out messages
+ * - Per-shard in-flight tracking
+ *
+ * Data structures:
+ * - In-flight sorted set: score = deadline timestamp, member = "{messageId}:{queueId}"
+ * - In-flight data hash: field = messageId, value = JSON message data
+ */
+declare class VisibilityManager {
+    #private;
+    private options;
+    private redis;
+    private keys;
+    private shardCount;
+    private defaultTimeoutMs;
+    private logger;
+    constructor(options: VisibilityManagerOptions);
+    /**
+     * 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
+     */
+    claim<TPayload = unknown>(queueId: string, queueKey: string, queueItemsKey: string, consumerId: string, timeoutMs?: number): Promise<ClaimResult<TPayload>>;
+    /**
+     * Claim multiple messages for processing (batch claim).
+     * Moves up to maxCount messages from the queue to the in-flight set.
+     *
+     * @param queueId - The queue to claim from
+     * @param queueKey - The Redis key for the queue sorted set
+     * @param queueItemsKey - The Redis key for the queue items hash
+     * @param consumerId - ID of the consumer claiming the messages
+     * @param maxCount - Maximum number of messages to claim
+     * @param timeoutMs - Visibility timeout in milliseconds
+     * @returns Array of claimed messages
+     */
+    claimBatch<TPayload = unknown>(queueId: string, queueKey: string, queueItemsKey: string, consumerId: string, maxCount: number, timeoutMs?: number): Promise<Array<InFlightMessage<TPayload>>>;
+    /**
+     * 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
+     */
+    heartbeat(messageId: string, queueId: string, extendMs: number): Promise<boolean>;
+    /**
+     * Mark a message as successfully processed.
+     * Removes the message from in-flight tracking.
+     *
+     * @param messageId - The message ID
+     * @param queueId - The queue ID
+     */
+    complete(messageId: string, queueId: string): Promise<void>;
+    /**
+     * 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 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)
+     */
+    release<_TPayload = unknown>(messageId: string, queueId: string, queueKey: string, queueItemsKey: string, tenantQueueIndexKey: string, dispatchKey: string, tenantId: string, score?: number, updatedData?: string): Promise<void>;
+    /**
+     * Release multiple messages back to their queue in a single operation.
+     * Used when processing fails or consumer wants to retry later.
+     * All messages must belong to the same queue.
+     *
+     * @param messages - Array of messages to release (must all have same queueId)
+     * @param queueId - The queue ID
+     * @param queueKey - The Redis key for the queue
+     * @param queueItemsKey - The Redis key for the queue items hash
+     * @param 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)
+     */
+    releaseBatch(messages: Array<{
+        messageId: string;
+    }>, queueId: string, queueKey: string, queueItemsKey: string, tenantQueueIndexKey: string, dispatchKey: string, tenantId: string, score?: number): Promise<void>;
+    /**
+     * 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 Array of reclaimed message info for concurrency release
+     */
+    reclaimTimedOut(shardId: number, getQueueKeys: (queueId: string) => {
+        queueKey: string;
+        queueItemsKey: string;
+        tenantQueueIndexKey: string;
+        dispatchKey: string;
+        tenantId: string;
+    }): Promise<ReclaimedMessageInfo[]>;
+    /**
+     * Get all in-flight messages for a shard.
+     */
+    getInflightMessages(shardId: number): Promise<Array<{
+        messageId: string;
+        queueId: string;
+        deadline: number;
+    }>>;
+    /**
+     * Get count of in-flight messages for a shard.
+     */
+    getInflightCount(shardId: number): Promise<number>;
+    /**
+     * Get total in-flight count across all shards.
+     */
+    getTotalInflightCount(): Promise<number>;
+    /**
+     * Close the Redis connection.
+     */
+    close(): Promise<void>;
+}
+declare module "@internal/redis" {
+    interface RedisCommander<Context> {
+        claimMessage(queueKey: string, queueItemsKey: string, inflightKey: string, inflightDataKey: string, queueId: string, consumerId: string, deadline: string): Promise<[string, string] | null>;
+        claimMessageBatch(queueKey: string, queueItemsKey: string, inflightKey: string, inflightDataKey: string, queueId: string, deadline: string, maxCount: string): Promise<string[]>;
+        releaseMessage(inflightKey: string, inflightDataKey: string, queueKey: string, queueItemsKey: string, tenantQueueIndexKey: string, dispatchKey: string, member: string, messageId: string, score: string, queueId: string, updatedData: string, tenantId: string): Promise<number>;
+        releaseMessageBatch(inflightKey: string, inflightDataKey: string, queueKey: string, queueItemsKey: string, tenantQueueIndexKey: string, dispatchKey: string, score: string, queueId: string, tenantId: string, ...membersAndMessageIds: string[]): Promise<number>;
+        heartbeatMessage(inflightKey: string, member: string, newDeadline: string): Promise<number>;
+    }
+}
+
+interface WorkerQueueManagerOptions {
+    redis: RedisOptions;
+    keys: FairQueueKeyProducer;
+    logger?: {
+        debug: (message: string, context?: Record<string, unknown>) => void;
+        error: (message: string, context?: Record<string, unknown>) => void;
+    };
+}
+/**
+ * WorkerQueueManager handles the intermediate worker queue layer.
+ *
+ * This provides:
+ * - Low-latency message delivery via blocking pop (BLPOP)
+ * - Routing of messages to specific workers/consumers
+ * - Efficient waiting without polling
+ *
+ * Flow:
+ * 1. Master queue consumer claims message from message queue
+ * 2. Message key is pushed to worker queue
+ * 3. Worker queue consumer does blocking pop to receive message
+ */
+declare class WorkerQueueManager {
+    #private;
+    private options;
+    private redis;
+    private keys;
+    private logger;
+    constructor(options: WorkerQueueManagerOptions);
+    /**
+     * 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")
+     */
+    push(workerQueueId: string, messageKey: string): Promise<void>;
+    /**
+     * Push multiple message keys to a worker queue.
+     *
+     * @param workerQueueId - The worker queue identifier
+     * @param messageKeys - The message keys to push
+     */
+    pushBatch(workerQueueId: string, messageKeys: string[]): Promise<void>;
+    /**
+     * 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
+     */
+    blockingPop(workerQueueId: string, timeoutSeconds: number, signal?: AbortSignal): Promise<string | null>;
+    /**
+     * Non-blocking pop from a worker queue.
+     *
+     * @param workerQueueId - The worker queue identifier
+     * @returns The message key and queue length, or null if empty
+     */
+    pop(workerQueueId: string): Promise<{
+        messageKey: string;
+        queueLength: number;
+    } | null>;
+    /**
+     * Get the current length of a worker queue.
+     */
+    getLength(workerQueueId: string): Promise<number>;
+    /**
+     * Peek at all messages in a worker queue without removing them.
+     * Useful for debugging and tests.
+     */
+    peek(workerQueueId: string): Promise<string[]>;
+    /**
+     * 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
+     */
+    remove(workerQueueId: string, messageKey: string): Promise<number>;
+    /**
+     * Clear all messages from a worker queue.
+     */
+    clear(workerQueueId: string): Promise<void>;
+    /**
+     * Close the Redis connection.
+     */
+    close(): Promise<void>;
+    /**
+     * Register custom commands on an external Redis client.
+     * Use this when initializing FairQueue with worker queues.
+     */
+    registerCommands(redis: Redis): void;
+}
+declare module "@internal/redis" {
+    interface RedisCommander<Context> {
+        popWithLength(workerQueueKey: string): Promise<[string, string] | null>;
+    }
+}
+
 /**
  * FairQueue is the main orchestrator for fair queue message routing.
  *