@trigger.dev/redis-worker 4.3.0 → 4.3.2

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { Callback, Result, RedisOptions } from '@internal/redis';
+import { Callback, Result, RedisOptions, Redis } from '@internal/redis';
 import { Logger } from '@trigger.dev/core/logger';
 import { z } from 'zod';
-import { Tracer, Meter } from '@internal/tracing';
-import { RetryOptions } from '@trigger.dev/core/v3/schemas';
+import { Tracer, Meter, Counter, Histogram, ObservableGauge, Span, SpanKind, Attributes, Context } from '@internal/tracing';
+import { RetryOptions as RetryOptions$1 } from '@trigger.dev/core/v3/schemas';
 
 interface MessageCatalogSchema {
     [key: string]: z.ZodFirstPartySchemaTypes | z.ZodDiscriminatedUnion<any, any>;
@@ -101,7 +101,7 @@ type WorkerCatalog = {
     [key: string]: {
         schema: z.ZodFirstPartySchemaTypes | z.ZodDiscriminatedUnion<any, any>;
         visibilityTimeoutMs: number;
-        retry?: RetryOptions;
+        retry?: RetryOptions$1;
         cron?: string;
         jitterInMs?: number;
         /** Defaults to true. If false, errors will not be logged. */
@@ -229,4 +229,1698 @@ declare class Worker<TCatalog extends WorkerCatalog> {
     stop(): Promise<void>;
 }
 
-export { type AnyMessageCatalog, type AnyQueueItem, CronSchema, type JobHandler, type JobHandlerParams, type MessageCatalogKey, type MessageCatalogSchema, type MessageCatalogValue, type QueueItem, SimpleQueue, Worker, type WorkerCatalog, type WorkerConcurrencyOptions };
+/**
+ * Check if an error is an AbortError.
+ *
+ * This handles both:
+ * - Custom abort errors created with `new Error("AbortError")` (sets .message)
+ * - Native Node.js AbortError from timers/promises (sets .name)
+ */
+declare function isAbortError(error: unknown): boolean;
+
+/**
+ * RetryStrategy interface for pluggable retry logic.
+ */
+interface RetryStrategy {
+    /**
+     * Calculate the next retry delay in milliseconds.
+     * Return null to indicate the message should be sent to DLQ.
+     *
+     * @param attempt - Current attempt number (1-indexed)
+     * @param error - Optional error from the failed attempt
+     * @returns Delay in milliseconds, or null to send to DLQ
+     */
+    getNextDelay(attempt: number, error?: Error): number | null;
+    /**
+     * Maximum number of attempts before moving to DLQ.
+     */
+    maxAttempts: number;
+}
+/**
+ * Exponential backoff retry strategy.
+ *
+ * Uses the same algorithm as @trigger.dev/core's calculateNextRetryDelay.
+ */
+declare class ExponentialBackoffRetry implements RetryStrategy {
+    readonly maxAttempts: number;
+    private options;
+    constructor(options?: Partial<RetryOptions$1>);
+    getNextDelay(attempt: number, _error?: Error): number | null;
+}
+/**
+ * Fixed delay retry strategy.
+ *
+ * Always waits the same amount of time between retries.
+ */
+declare class FixedDelayRetry implements RetryStrategy {
+    readonly maxAttempts: number;
+    private delayMs;
+    constructor(options: {
+        maxAttempts: number;
+        delayMs: number;
+    });
+    getNextDelay(attempt: number, _error?: Error): number | null;
+}
+/**
+ * Linear backoff retry strategy.
+ *
+ * Delay increases linearly with each attempt.
+ */
+declare class LinearBackoffRetry implements RetryStrategy {
+    readonly maxAttempts: number;
+    private baseDelayMs;
+    private maxDelayMs;
+    constructor(options: {
+        maxAttempts: number;
+        baseDelayMs: number;
+        maxDelayMs?: number;
+    });
+    getNextDelay(attempt: number, _error?: Error): number | null;
+}
+/**
+ * No retry strategy.
+ *
+ * Messages go directly to DLQ on first failure.
+ */
+declare class NoRetry implements RetryStrategy {
+    readonly maxAttempts = 1;
+    getNextDelay(_attempt: number, _error?: Error): number | null;
+}
+/**
+ * Immediate retry strategy.
+ *
+ * Retries immediately without any delay.
+ */
+declare class ImmediateRetry implements RetryStrategy {
+    readonly maxAttempts: number;
+    constructor(maxAttempts: number);
+    getNextDelay(attempt: number, _error?: Error): number | null;
+}
+/**
+ * Custom retry strategy that uses a user-provided function.
+ */
+declare class CustomRetry implements RetryStrategy {
+    readonly maxAttempts: number;
+    private calculateDelay;
+    constructor(options: {
+        maxAttempts: number;
+        calculateDelay: (attempt: number, error?: Error) => number | null;
+    });
+    getNextDelay(attempt: number, error?: Error): number | null;
+}
+/**
+ * Default retry options matching @trigger.dev/core defaults.
+ */
+declare const defaultRetryOptions: RetryOptions$1;
+/**
+ * Create an exponential backoff retry strategy with default options.
+ */
+declare function createDefaultRetryStrategy(): RetryStrategy;
+
+/**
+ * Interface for a global rate limiter that limits processing across all consumers.
+ * When configured, consumers will check this before processing each message.
+ */
+interface GlobalRateLimiter {
+    /**
+     * Check if processing is allowed under the rate limit.
+     * @returns Object with allowed flag and optional resetAt timestamp (ms since epoch)
+     */
+    limit(): Promise<{
+        allowed: boolean;
+        resetAt?: number;
+    }>;
+}
+/**
+ * Descriptor for a queue in the fair queue system.
+ * Contains all the metadata needed to identify and route a queue.
+ */
+interface QueueDescriptor {
+    /** Unique queue identifier */
+    id: string;
+    /** Tenant this queue belongs to */
+    tenantId: string;
+    /** Additional metadata for concurrency group extraction */
+    metadata: Record<string, unknown>;
+}
+/**
+ * A message in the queue with its metadata.
+ */
+interface QueueMessage<TPayload = unknown> {
+    /** Unique message identifier */
+    id: string;
+    /** The queue this message belongs to */
+    queueId: string;
+    /** Message payload */
+    payload: TPayload;
+    /** Timestamp when message was enqueued */
+    timestamp: number;
+    /** Current attempt number (1-indexed, for retries) */
+    attempt: number;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Internal message format stored in Redis.
+ * Includes additional fields for tracking and routing.
+ */
+interface StoredMessage<TPayload = unknown> {
+    /** Message ID */
+    id: string;
+    /** Queue ID */
+    queueId: string;
+    /** Tenant ID */
+    tenantId: string;
+    /** Message payload */
+    payload: TPayload;
+    /** Timestamp when enqueued */
+    timestamp: number;
+    /** Current attempt number */
+    attempt: number;
+    /** Worker queue to route to */
+    workerQueue?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Queue with its score (oldest message timestamp) from the master queue.
+ */
+interface QueueWithScore {
+    /** Queue identifier */
+    queueId: string;
+    /** Score (typically oldest message timestamp) */
+    score: number;
+    /** Tenant ID extracted from queue */
+    tenantId: string;
+}
+/**
+ * Configuration for a concurrency group.
+ * Allows defining arbitrary levels of concurrency (tenant, org, project, etc.)
+ */
+interface ConcurrencyGroupConfig {
+    /** Group name (e.g., "tenant", "organization", "project") */
+    name: string;
+    /** Extract the group ID from a queue descriptor */
+    extractGroupId: (queue: QueueDescriptor) => string;
+    /** Get the concurrency limit for a specific group ID */
+    getLimit: (groupId: string) => Promise<number>;
+    /** Default limit if not specified */
+    defaultLimit: number;
+}
+/**
+ * Current concurrency state for a group.
+ */
+interface ConcurrencyState {
+    /** Group name */
+    groupName: string;
+    /** Group ID */
+    groupId: string;
+    /** Current active count */
+    current: number;
+    /** Configured limit */
+    limit: number;
+}
+/**
+ * Result of a concurrency check.
+ */
+interface ConcurrencyCheckResult {
+    /** Whether processing is allowed */
+    allowed: boolean;
+    /** If not allowed, which group is blocking */
+    blockedBy?: ConcurrencyState;
+}
+/**
+ * Queues grouped by tenant for the scheduler.
+ */
+interface TenantQueues {
+    /** Tenant identifier */
+    tenantId: string;
+    /** Queue IDs belonging to this tenant, in priority order */
+    queues: string[];
+}
+/**
+ * Context provided to the scheduler for making decisions.
+ */
+interface SchedulerContext {
+    /** Get current concurrency for a group */
+    getCurrentConcurrency(groupName: string, groupId: string): Promise<number>;
+    /** Get concurrency limit for a group */
+    getConcurrencyLimit(groupName: string, groupId: string): Promise<number>;
+    /** Check if a group is at capacity */
+    isAtCapacity(groupName: string, groupId: string): Promise<boolean>;
+    /** Get queue descriptor by ID */
+    getQueueDescriptor(queueId: string): QueueDescriptor;
+}
+/**
+ * Pluggable scheduler interface for fair queue selection.
+ */
+interface FairScheduler {
+    /**
+     * Select queues for processing from a master queue shard.
+     * Returns queues grouped by tenant, ordered by the fairness algorithm.
+     *
+     * @param masterQueueShard - The master queue shard key
+     * @param consumerId - The consumer making the request
+     * @param context - Context for concurrency checks
+     * @returns Queues grouped by tenant in priority order
+     */
+    selectQueues(masterQueueShard: string, consumerId: string, context: SchedulerContext): Promise<TenantQueues[]>;
+    /**
+     * Called after processing a message to update scheduler state.
+     * Optional - not all schedulers need to track state.
+     */
+    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.
+     * Optional - falls back to calling recordProcessed multiple times if not implemented.
+     */
+    recordProcessedBatch?(tenantId: string, queueId: string, count: number): Promise<void>;
+    /**
+     * Initialize the scheduler (called once on startup).
+     */
+    initialize?(): Promise<void>;
+    /**
+     * Cleanup scheduler resources.
+     */
+    close?(): Promise<void>;
+}
+/**
+ * An in-flight message being processed.
+ */
+interface InFlightMessage<TPayload = unknown> {
+    /** Message ID */
+    messageId: string;
+    /** Queue ID */
+    queueId: string;
+    /** Message payload */
+    payload: TPayload;
+    /** When visibility timeout expires */
+    deadline: number;
+    /** Consumer that claimed this message */
+    consumerId: string;
+}
+/**
+ * Result of claiming a message.
+ */
+interface ClaimResult<TPayload = unknown> {
+    /** Whether the claim was successful */
+    claimed: boolean;
+    /** The claimed message if successful */
+    message?: InFlightMessage<TPayload>;
+}
+/**
+ * Interface for generating Redis keys for the fair queue system.
+ * Implementations can customize key prefixes and structures.
+ */
+interface FairQueueKeyProducer {
+    /** Get the master queue key for a shard */
+    masterQueueKey(shardId: number): string;
+    /** Get the queue key for storing messages */
+    queueKey(queueId: string): string;
+    /** Get the queue items hash key */
+    queueItemsKey(queueId: string): string;
+    /** Get the concurrency set key for a group */
+    concurrencyKey(groupName: string, groupId: string): string;
+    /** Get the in-flight sorted set key for a shard */
+    inflightKey(shardId: number): string;
+    /** Get the in-flight message data hash key */
+    inflightDataKey(shardId: number): string;
+    /** Get the worker queue key for a consumer */
+    workerQueueKey(consumerId: string): string;
+    /** Get the dead letter queue key for a tenant */
+    deadLetterQueueKey(tenantId: string): string;
+    /** Get the dead letter queue data hash key for a tenant */
+    deadLetterQueueDataKey(tenantId: string): string;
+    /** Extract tenant ID from a queue ID */
+    extractTenantId(queueId: string): string;
+    /** Extract a specific group ID from a queue ID */
+    extractGroupId(groupName: string, queueId: string): string;
+}
+/**
+ * Worker queue configuration options.
+ * Worker queues are always enabled - FairQueue routes messages to worker queues,
+ * and external consumers are responsible for consuming from those queues.
+ */
+interface WorkerQueueOptions<TPayload = unknown> {
+    /**
+     * Function to resolve which worker queue a message should go to.
+     * This is called during the claim-and-push phase to determine the target queue.
+     */
+    resolveWorkerQueue: (message: StoredMessage<TPayload>) => string;
+}
+/**
+ * Retry and dead letter queue configuration.
+ */
+interface RetryOptions {
+    /** Retry strategy for failed messages */
+    strategy: RetryStrategy;
+    /** Whether to enable dead letter queue (default: true) */
+    deadLetterQueue?: boolean;
+}
+/**
+ * Queue cooloff configuration to avoid repeatedly polling concurrency-limited queues.
+ */
+interface CooloffOptions {
+    /** Whether cooloff is enabled (default: true) */
+    enabled?: boolean;
+    /** Number of consecutive empty dequeues before entering cooloff (default: 10) */
+    threshold?: number;
+    /** Duration of cooloff period in milliseconds (default: 10000) */
+    periodMs?: number;
+    /** Maximum number of cooloff state entries before triggering cleanup (default: 1000) */
+    maxStatesSize?: number;
+}
+/**
+ * Options for creating a FairQueue instance.
+ *
+ * @typeParam TPayloadSchema - Zod schema for message payload validation
+ */
+interface FairQueueOptions<TPayloadSchema extends z.ZodTypeAny = z.ZodUnknown> {
+    /** Redis connection options */
+    redis: RedisOptions;
+    /** Key producer for Redis keys */
+    keys: FairQueueKeyProducer;
+    /** Scheduler for fair queue selection */
+    scheduler: FairScheduler;
+    /** Zod schema for message payload validation */
+    payloadSchema?: TPayloadSchema;
+    /** Whether to validate payloads on enqueue (default: false) */
+    validateOnEnqueue?: boolean;
+    /** Number of master queue shards (default: 1) */
+    shardCount?: number;
+    /** Concurrency group configurations */
+    concurrencyGroups?: ConcurrencyGroupConfig[];
+    /**
+     * Worker queue configuration.
+     * FairQueue routes messages to worker queues; external consumers handle consumption.
+     */
+    workerQueue: WorkerQueueOptions<z.infer<TPayloadSchema>>;
+    /** Retry and dead letter queue configuration */
+    retry?: RetryOptions;
+    /** Visibility timeout in milliseconds (default: 30000) */
+    visibilityTimeoutMs?: number;
+    /** Heartbeat interval in milliseconds (default: visibilityTimeoutMs / 3) */
+    heartbeatIntervalMs?: number;
+    /** Interval for reclaiming timed-out messages (default: 5000) */
+    reclaimIntervalMs?: number;
+    /** Number of consumer loops to run (default: 1) */
+    consumerCount?: number;
+    /** Interval between consumer iterations in milliseconds (default: 100) */
+    consumerIntervalMs?: number;
+    /** Whether to start consumers on initialization (default: true) */
+    startConsumers?: boolean;
+    /** Maximum number of messages to claim in a single batch operation (default: 10) */
+    batchClaimSize?: number;
+    /** Maximum iterations before starting a new trace span (default: 500) */
+    consumerTraceMaxIterations?: number;
+    /** Maximum seconds before starting a new trace span (default: 60) */
+    consumerTraceTimeoutSeconds?: number;
+    /** Queue cooloff configuration */
+    cooloff?: CooloffOptions;
+    /** Logger instance */
+    logger?: Logger;
+    /** OpenTelemetry tracer */
+    tracer?: Tracer;
+    /** OpenTelemetry meter */
+    meter?: Meter;
+    /** Name for metrics/tracing (default: "fairqueue") */
+    name?: string;
+    /** Optional global rate limiter to limit processing across all consumers */
+    globalRateLimiter?: GlobalRateLimiter;
+}
+/**
+ * Context passed to the message handler.
+ */
+interface MessageHandlerContext<TPayload = unknown> {
+    /** The message being processed */
+    message: QueueMessage<TPayload>;
+    /** Queue descriptor */
+    queue: QueueDescriptor;
+    /** Consumer ID processing this message */
+    consumerId: string;
+    /** Extend the visibility timeout */
+    heartbeat(): Promise<boolean>;
+    /** Mark message as successfully processed */
+    complete(): Promise<void>;
+    /** Release message back to the queue for retry */
+    release(): Promise<void>;
+    /** Mark message as failed (triggers retry or DLQ) */
+    fail(error?: Error): Promise<void>;
+}
+/**
+ * Handler function for processing messages.
+ */
+type MessageHandler<TPayload = unknown> = (context: MessageHandlerContext<TPayload>) => Promise<void>;
+/**
+ * A message in the dead letter queue.
+ */
+interface DeadLetterMessage<TPayload = unknown> {
+    /** Message ID */
+    id: string;
+    /** Original queue ID */
+    queueId: string;
+    /** Tenant ID */
+    tenantId: string;
+    /** Message payload */
+    payload: TPayload;
+    /** Timestamp when moved to DLQ */
+    deadLetteredAt: number;
+    /** Number of attempts before DLQ */
+    attempts: number;
+    /** Last error message if available */
+    lastError?: string;
+    /** Original message timestamp */
+    originalTimestamp: number;
+}
+/**
+ * Cooloff state for a queue.
+ */
+type QueueCooloffState = {
+    tag: "normal";
+    consecutiveFailures: number;
+} | {
+    tag: "cooloff";
+    expiresAt: number;
+};
+/**
+ * Options for enqueueing a message.
+ */
+interface EnqueueOptions<TPayload = unknown> {
+    /** Queue to add the message to */
+    queueId: string;
+    /** Tenant ID for the queue */
+    tenantId: string;
+    /** Message payload */
+    payload: TPayload;
+    /** Optional message ID (auto-generated if not provided) */
+    messageId?: string;
+    /** Optional timestamp (defaults to now) */
+    timestamp?: number;
+    /** Optional metadata for concurrency group extraction */
+    metadata?: Record<string, string>;
+}
+/**
+ * Options for enqueueing multiple messages.
+ */
+interface EnqueueBatchOptions<TPayload = unknown> {
+    /** Queue to add messages to */
+    queueId: string;
+    /** Tenant ID for the queue */
+    tenantId: string;
+    /** Messages to enqueue */
+    messages: Array<{
+        payload: TPayload;
+        messageId?: string;
+        timestamp?: number;
+    }>;
+    /** Optional metadata for concurrency group extraction */
+    metadata?: Record<string, string>;
+}
+/**
+ * Configuration for the Deficit Round Robin scheduler.
+ */
+interface DRRSchedulerConfig {
+    /** Credits allocated per tenant per round */
+    quantum: number;
+    /** Maximum accumulated deficit (prevents starvation) */
+    maxDeficit: number;
+    /** Maximum queues to fetch from master queue (default: 1000) */
+    masterQueueLimit?: number;
+    /** Redis options for state storage */
+    redis: RedisOptions;
+    /** Key producer */
+    keys: FairQueueKeyProducer;
+    /** Optional logger */
+    logger?: {
+        debug: (message: string, context?: Record<string, unknown>) => void;
+        error: (message: string, context?: Record<string, unknown>) => void;
+    };
+}
+/**
+ * Bias configuration for weighted shuffle scheduler.
+ */
+interface WeightedSchedulerBiases {
+    /**
+     * How much to bias towards tenants with higher concurrency limits.
+     * 0 = no bias, 1 = full bias based on limit differences
+     */
+    concurrencyLimitBias: number;
+    /**
+     * How much to bias towards tenants with more available capacity.
+     * 0 = no bias, 1 = full bias based on available capacity
+     */
+    availableCapacityBias: number;
+    /**
+     * Controls randomization of queue ordering within tenants.
+     * 0 = strict age-based ordering (oldest first)
+     * 1 = completely random ordering
+     * Values between 0-1 blend between age-based and random ordering
+     */
+    queueAgeRandomization: number;
+}
+/**
+ * Configuration for the weighted shuffle scheduler.
+ */
+interface WeightedSchedulerConfig {
+    /** Redis options */
+    redis: RedisOptions;
+    /** Key producer */
+    keys: FairQueueKeyProducer;
+    /** Default tenant concurrency limit */
+    defaultTenantConcurrencyLimit?: number;
+    /** Maximum queues to consider from master queue */
+    masterQueueLimit?: number;
+    /** Bias configuration */
+    biases?: WeightedSchedulerBiases;
+    /** Number of iterations to reuse a snapshot */
+    reuseSnapshotCount?: number;
+    /** Maximum number of tenants to consider */
+    maximumTenantCount?: number;
+    /** Random seed for reproducibility */
+    seed?: string;
+    /** Optional tracer */
+    tracer?: Tracer;
+}
+
+/**
+ * Default key producer for the fair queue system.
+ * Uses a configurable prefix and standard key structure.
+ *
+ * Key structure:
+ * - Master queue: {prefix}:master:{shardId}
+ * - Queue: {prefix}:queue:{queueId}
+ * - Queue items: {prefix}:queue:{queueId}:items
+ * - Concurrency: {prefix}:concurrency:{groupName}:{groupId}
+ * - In-flight: {prefix}:inflight:{shardId}
+ * - In-flight data: {prefix}:inflight:{shardId}:data
+ * - Worker queue: {prefix}:worker:{consumerId}
+ */
+declare class DefaultFairQueueKeyProducer implements FairQueueKeyProducer {
+    #private;
+    private readonly prefix;
+    private readonly separator;
+    constructor(options?: {
+        prefix?: string;
+        separator?: string;
+    });
+    masterQueueKey(shardId: number): string;
+    queueKey(queueId: string): string;
+    queueItemsKey(queueId: string): string;
+    concurrencyKey(groupName: string, groupId: string): string;
+    inflightKey(shardId: number): string;
+    inflightDataKey(shardId: number): string;
+    workerQueueKey(consumerId: string): string;
+    deadLetterQueueKey(tenantId: string): string;
+    deadLetterQueueDataKey(tenantId: string): string;
+    /**
+     * Extract tenant ID from a queue ID.
+     * Default implementation assumes queue IDs are formatted as: tenant:{tenantId}:...
+     * Override this method for custom queue ID formats.
+     */
+    extractTenantId(queueId: string): string;
+    /**
+     * Extract a group ID from a queue ID.
+     * Default implementation looks for pattern: {groupName}:{groupId}:...
+     * Override this method for custom queue ID formats.
+     */
+    extractGroupId(groupName: string, queueId: string): string;
+}
+/**
+ * Key producer with custom extraction logic via callbacks.
+ * Useful when queue IDs don't follow a standard pattern.
+ */
+declare class CallbackFairQueueKeyProducer extends DefaultFairQueueKeyProducer {
+    private readonly tenantExtractor;
+    private readonly groupExtractor;
+    constructor(options: {
+        prefix?: string;
+        separator?: string;
+        extractTenantId: (queueId: string) => string;
+        extractGroupId: (groupName: string, queueId: string) => string;
+    });
+    extractTenantId(queueId: string): string;
+    extractGroupId(groupName: string, queueId: string): string;
+}
+
+interface MasterQueueOptions {
+    redis: RedisOptions;
+    keys: FairQueueKeyProducer;
+    shardCount: number;
+}
+/**
+ * Master queue manages the top-level queue of queues.
+ *
+ * Features:
+ * - Sharding for horizontal scaling
+ * - Consistent hashing for queue-to-shard assignment
+ * - Queues scored by oldest message timestamp
+ */
+declare class MasterQueue {
+    #private;
+    private options;
+    private redis;
+    private keys;
+    private shardCount;
+    constructor(options: MasterQueueOptions);
+    /**
+     * Get the shard ID for a queue.
+     * Uses consistent hashing based on queue ID.
+     */
+    getShardForQueue(queueId: string): number;
+    /**
+     * Add a queue to its master queue shard.
+     * Updates the score to the oldest message timestamp.
+     *
+     * @param queueId - The queue identifier
+     * @param oldestMessageTimestamp - Timestamp of the oldest message in the queue
+     */
+    addQueue(queueId: string, oldestMessageTimestamp: number): Promise<void>;
+    /**
+     * Update a queue's score in the master queue.
+     * This is typically called after dequeuing to update to the new oldest message.
+     *
+     * @param queueId - The queue identifier
+     * @param newOldestTimestamp - New timestamp of the oldest message
+     */
+    updateQueueScore(queueId: string, newOldestTimestamp: number): Promise<void>;
+    /**
+     * Remove a queue from its master queue shard.
+     * Called when a queue becomes empty.
+     *
+     * @param queueId - The queue identifier
+     */
+    removeQueue(queueId: string): Promise<void>;
+    /**
+     * Get queues from a shard, ordered by oldest message (lowest score first).
+     *
+     * @param shardId - The shard to query
+     * @param limit - Maximum number of queues to return (default: 1000)
+     * @param maxScore - Maximum score (timestamp) to include (default: now)
+     */
+    getQueuesFromShard(shardId: number, limit?: number, maxScore?: number): Promise<QueueWithScore[]>;
+    /**
+     * Get the number of queues in a shard.
+     */
+    getShardQueueCount(shardId: number): Promise<number>;
+    /**
+     * Get total queue count across all shards.
+     */
+    getTotalQueueCount(): Promise<number>;
+    /**
+     * Atomically add a queue to master queue only if queue has messages.
+     * Uses Lua script for atomicity.
+     *
+     * @param queueId - The queue identifier
+     * @param queueKey - The actual queue sorted set key
+     * @returns Whether the queue was added to the master queue
+     */
+    addQueueIfNotEmpty(queueId: string, queueKey: string): Promise<boolean>;
+    /**
+     * Atomically remove a queue from master queue only if queue is empty.
+     * Uses Lua script for atomicity.
+     *
+     * @param queueId - The queue identifier
+     * @param queueKey - The actual queue sorted set key
+     * @returns Whether the queue was removed from the master queue
+     */
+    removeQueueIfEmpty(queueId: string, queueKey: string): Promise<boolean>;
+    /**
+     * Close the Redis connection.
+     */
+    close(): Promise<void>;
+}
+declare module "@internal/redis" {
+    interface RedisCommander<Context> {
+        addQueueIfNotEmpty(masterKey: string, queueKey: string, queueId: string): Promise<number>;
+        removeQueueIfEmpty(masterKey: string, queueKey: string, queueId: string): Promise<number>;
+    }
+}
+
+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>;
+    /**
+     * 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>;
+    }
+}
+
+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 masterQueueKey - The Redis key for the master queue
+     * @param score - Optional score for the message (defaults to now)
+     */
+    release<TPayload = unknown>(messageId: string, queueId: string, queueKey: string, queueItemsKey: string, masterQueueKey: string, score?: number): 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 masterQueueKey - The Redis key for the master queue
+     * @param score - Optional score for the messages (defaults to now)
+     */
+    releaseBatch(messages: Array<{
+        messageId: string;
+    }>, queueId: string, queueKey: string, queueItemsKey: string, masterQueueKey: 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 Number of messages reclaimed
+     */
+    reclaimTimedOut(shardId: number, getQueueKeys: (queueId: string) => {
+        queueKey: string;
+        queueItemsKey: string;
+        masterQueueKey: string;
+    }): Promise<number>;
+    /**
+     * 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, masterQueueKey: string, member: string, messageId: string, score: string, queueId: string): Promise<number>;
+        releaseMessageBatch(inflightKey: string, inflightDataKey: string, queueKey: string, queueItemsKey: string, masterQueueKey: string, score: string, queueId: 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[]>;
+    /**
+     * 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>>;
+}
+declare module "@internal/redis" {
+    interface RedisCommander<Context> {
+        drrAddQuantum(deficitKey: string, quantum: string, maxDeficit: string, ...tenantIds: string[]): Promise<string[]>;
+        drrDecrementDeficit(deficitKey: string, tenantId: string): Promise<string>;
+        drrDecrementDeficitBatch(deficitKey: string, tenantId: string, count: string): Promise<string>;
+    }
+}
+
+/**
+ * Weighted Shuffle Scheduler.
+ *
+ * Uses weighted random selection to balance between:
+ * - Concurrency limit (higher limits get more weight)
+ * - Available capacity (tenants with more capacity get more weight)
+ * - Queue age (older queues get priority, with configurable randomization)
+ *
+ * Features:
+ * - Snapshot caching to reduce Redis calls
+ * - Configurable biases for fine-tuning
+ * - Maximum tenant count to limit iteration
+ */
+declare class WeightedScheduler extends BaseScheduler {
+    #private;
+    private config;
+    private redis;
+    private keys;
+    private rng;
+    private biases;
+    private defaultTenantLimit;
+    private masterQueueLimit;
+    private reuseSnapshotCount;
+    private maximumTenantCount;
+    private snapshotCache;
+    constructor(config: WeightedSchedulerConfig);
+    selectQueues(masterQueueShard: string, consumerId: string, context: SchedulerContext): Promise<TenantQueues[]>;
+    close(): Promise<void>;
+}
+
+interface RoundRobinSchedulerConfig {
+    redis: RedisOptions;
+    keys: FairQueueKeyProducer;
+    /** Maximum queues to fetch from master queue per iteration */
+    masterQueueLimit?: number;
+}
+/**
+ * Round Robin Scheduler.
+ *
+ * Simple scheduler that processes tenants in strict rotation order.
+ * Maintains a "last served" pointer in Redis to track position.
+ *
+ * Features:
+ * - Predictable ordering (good for debugging)
+ * - Fair rotation through all tenants
+ * - No weighting or bias
+ */
+declare class RoundRobinScheduler extends BaseScheduler {
+    #private;
+    private config;
+    private redis;
+    private keys;
+    private masterQueueLimit;
+    constructor(config: RoundRobinSchedulerConfig);
+    selectQueues(masterQueueShard: string, consumerId: string, context: SchedulerContext): Promise<TenantQueues[]>;
+    close(): Promise<void>;
+}
+
+/**
+ * Semantic attributes for fair queue messaging operations.
+ */
+declare const FairQueueAttributes: {
+    readonly QUEUE_ID: "fairqueue.queue_id";
+    readonly TENANT_ID: "fairqueue.tenant_id";
+    readonly MESSAGE_ID: "fairqueue.message_id";
+    readonly SHARD_ID: "fairqueue.shard_id";
+    readonly WORKER_QUEUE: "fairqueue.worker_queue";
+    readonly CONSUMER_ID: "fairqueue.consumer_id";
+    readonly ATTEMPT: "fairqueue.attempt";
+    readonly CONCURRENCY_GROUP: "fairqueue.concurrency_group";
+    readonly MESSAGE_COUNT: "fairqueue.message_count";
+    readonly RESULT: "fairqueue.result";
+};
+/**
+ * Standard messaging semantic attributes.
+ */
+declare const MessagingAttributes: {
+    readonly SYSTEM: "messaging.system";
+    readonly OPERATION: "messaging.operation";
+    readonly MESSAGE_ID: "messaging.message_id";
+    readonly DESTINATION_NAME: "messaging.destination.name";
+};
+/**
+ * FairQueue metrics collection.
+ */
+interface FairQueueMetrics {
+    messagesEnqueued: Counter;
+    messagesCompleted: Counter;
+    messagesFailed: Counter;
+    messagesRetried: Counter;
+    messagesToDLQ: Counter;
+    processingTime: Histogram;
+    queueTime: Histogram;
+    queueLength: ObservableGauge;
+    masterQueueLength: ObservableGauge;
+    inflightCount: ObservableGauge;
+    dlqLength: ObservableGauge;
+}
+/**
+ * Options for creating FairQueue telemetry.
+ */
+interface TelemetryOptions {
+    tracer?: Tracer;
+    meter?: Meter;
+    /** Custom name for metrics prefix */
+    name?: string;
+}
+/**
+ * Telemetry helper for FairQueue.
+ *
+ * Provides:
+ * - Span creation with proper attributes
+ * - Metric recording
+ * - Context propagation helpers
+ */
+declare class FairQueueTelemetry {
+    #private;
+    private tracer?;
+    private meter?;
+    private metrics?;
+    private name;
+    constructor(options: TelemetryOptions);
+    /**
+     * Create a traced span for an operation.
+     * Returns the result of the function, or throws any error after recording it.
+     */
+    trace<T>(name: string, fn: (span: Span) => Promise<T>, options?: {
+        kind?: SpanKind;
+        attributes?: Attributes;
+    }): Promise<T>;
+    /**
+     * Synchronous version of trace.
+     */
+    traceSync<T>(name: string, fn: (span: Span) => T, options?: {
+        kind?: SpanKind;
+        attributes?: Attributes;
+    }): T;
+    /**
+     * Record a message enqueued.
+     */
+    recordEnqueue(attributes?: Attributes): void;
+    /**
+     * Record a batch of messages enqueued.
+     */
+    recordEnqueueBatch(count: number, attributes?: Attributes): void;
+    /**
+     * Record a message completed successfully.
+     */
+    recordComplete(attributes?: Attributes): void;
+    /**
+     * Record a message processing failure.
+     */
+    recordFailure(attributes?: Attributes): void;
+    /**
+     * Record a message retry.
+     */
+    recordRetry(attributes?: Attributes): void;
+    /**
+     * Record a message sent to DLQ.
+     */
+    recordDLQ(attributes?: Attributes): void;
+    /**
+     * Record message processing time.
+     *
+     * @param durationMs - Processing duration in milliseconds
+     */
+    recordProcessingTime(durationMs: number, attributes?: Attributes): void;
+    /**
+     * Record time a message spent waiting in queue.
+     *
+     * @param durationMs - Queue wait time in milliseconds
+     */
+    recordQueueTime(durationMs: number, attributes?: Attributes): void;
+    /**
+     * Register observable gauge callbacks.
+     * Call this after FairQueue is initialized to register the gauge callbacks.
+     */
+    registerGaugeCallbacks(callbacks: {
+        getQueueLength?: (queueId: string) => Promise<number>;
+        getMasterQueueLength?: (shardId: number) => Promise<number>;
+        getInflightCount?: (shardId: number) => Promise<number>;
+        getDLQLength?: (tenantId: string) => Promise<number>;
+        shardCount?: number;
+        observedQueues?: string[];
+        observedTenants?: string[];
+    }): void;
+    /**
+     * Create standard attributes for a message operation (for spans/traces).
+     * Use this for span attributes where high cardinality is acceptable.
+     */
+    messageAttributes(params: {
+        queueId?: string;
+        tenantId?: string;
+        messageId?: string;
+        attempt?: number;
+        workerQueue?: string;
+        consumerId?: string;
+    }): Attributes;
+    /**
+     * Check if telemetry is enabled.
+     */
+    get isEnabled(): boolean;
+    /**
+     * Check if tracing is enabled.
+     */
+    get hasTracer(): boolean;
+    /**
+     * Check if metrics are enabled.
+     */
+    get hasMetrics(): boolean;
+}
+/**
+ * State for tracking a consumer loop's batched span.
+ */
+interface ConsumerLoopState {
+    /** Countdown of iterations before starting a new span */
+    perTraceCountdown: number;
+    /** When the current trace started */
+    traceStartedAt: Date;
+    /** The current batched span */
+    currentSpan?: Span;
+    /** The context for the current batched span */
+    currentSpanContext?: Context;
+    /** Number of iterations in the current span */
+    iterationsCount: number;
+    /** Total iterations across all spans */
+    totalIterationsCount: number;
+    /** Running duration in milliseconds for the current span */
+    runningDurationInMs: number;
+    /** Stats counters for the current span */
+    stats: Record<string, number>;
+    /** Flag to force span end on next iteration */
+    endSpanInNextIteration: boolean;
+}
+/**
+ * Configuration for the BatchedSpanManager.
+ */
+interface BatchedSpanManagerOptions {
+    /** The tracer to use for creating spans */
+    tracer?: Tracer;
+    /** Name prefix for spans */
+    name: string;
+    /** Maximum iterations before rotating the span */
+    maxIterations: number;
+    /** Maximum seconds before rotating the span */
+    timeoutSeconds: number;
+    /** Optional callback to get dynamic attributes when starting a new batched span */
+    getDynamicAttributes?: () => Attributes;
+}
+/**
+ * Manages batched spans for consumer loops.
+ *
+ * This allows multiple iterations to be grouped into a single parent span,
+ * reducing the volume of spans while maintaining observability.
+ */
+declare class BatchedSpanManager {
+    private tracer?;
+    private name;
+    private maxIterations;
+    private timeoutSeconds;
+    private loopStates;
+    private getDynamicAttributes?;
+    constructor(options: BatchedSpanManagerOptions);
+    /**
+     * Initialize state for a consumer loop.
+     */
+    initializeLoop(loopId: string): void;
+    /**
+     * Get the state for a consumer loop.
+     */
+    getState(loopId: string): ConsumerLoopState | undefined;
+    /**
+     * Increment a stat counter for a loop.
+     */
+    incrementStat(loopId: string, statName: string, value?: number): void;
+    /**
+     * Mark that the span should end on the next iteration.
+     */
+    markForRotation(loopId: string): void;
+    /**
+     * Check if the span should be rotated (ended and a new one started).
+     */
+    shouldRotate(loopId: string): boolean;
+    /**
+     * End the current span for a loop and record stats.
+     */
+    endCurrentSpan(loopId: string): void;
+    /**
+     * Start a new batched span for a loop.
+     */
+    startNewSpan(loopId: string, attributes?: Attributes): void;
+    /**
+     * Execute a function within the batched span context.
+     * Automatically handles span rotation and iteration tracking.
+     */
+    withBatchedSpan<T>(loopId: string, fn: (span: Span) => Promise<T>, options?: {
+        iterationSpanName?: string;
+        attributes?: Attributes;
+    }): Promise<T>;
+    /**
+     * Clean up state for a loop when it's stopped.
+     */
+    cleanup(loopId: string): void;
+    /**
+     * Clean up all loop states.
+     */
+    cleanupAll(): void;
+}
+/**
+ * No-op telemetry instance for when telemetry is disabled.
+ */
+declare const noopTelemetry: FairQueueTelemetry;
+
+/**
+ * FairQueue is the main orchestrator for fair queue message routing.
+ *
+ * FairQueue handles:
+ * - Master queue with sharding (using jump consistent hash)
+ * - Fair scheduling via pluggable schedulers
+ * - Multi-level concurrency limiting
+ * - Visibility timeouts with heartbeats
+ * - Routing messages to worker queues
+ * - Retry strategies with dead letter queue
+ * - OpenTelemetry tracing and metrics
+ *
+ * External consumers are responsible for:
+ * - Running their own worker queue consumer loops
+ * - Calling complete/release/fail APIs after processing
+ *
+ * @typeParam TPayloadSchema - Zod schema for message payload validation
+ */
+declare class FairQueue<TPayloadSchema extends z.ZodTypeAny = z.ZodUnknown> {
+    #private;
+    private options;
+    private redis;
+    private keys;
+    private scheduler;
+    private masterQueue;
+    private concurrencyManager?;
+    private visibilityManager;
+    private workerQueueManager;
+    private telemetry;
+    private logger;
+    private payloadSchema?;
+    private validateOnEnqueue;
+    private retryStrategy?;
+    private deadLetterQueueEnabled;
+    private shardCount;
+    private consumerCount;
+    private consumerIntervalMs;
+    private visibilityTimeoutMs;
+    private heartbeatIntervalMs;
+    private reclaimIntervalMs;
+    private workerQueueResolver;
+    private batchClaimSize;
+    private cooloffEnabled;
+    private cooloffThreshold;
+    private cooloffPeriodMs;
+    private maxCooloffStatesSize;
+    private queueCooloffStates;
+    private globalRateLimiter?;
+    private consumerTraceMaxIterations;
+    private consumerTraceTimeoutSeconds;
+    private batchedSpanManager;
+    private isRunning;
+    private abortController;
+    private masterQueueConsumerLoops;
+    private reclaimLoop?;
+    private queueDescriptorCache;
+    constructor(options: FairQueueOptions<TPayloadSchema>);
+    /**
+     * Register observable gauge callbacks for telemetry.
+     * Call this after FairQueue is created to enable gauge metrics.
+     *
+     * @param options.observedTenants - List of tenant IDs to observe for DLQ metrics
+     */
+    registerTelemetryGauges(options?: {
+        observedTenants?: string[];
+    }): void;
+    /**
+     * Enqueue a single message to a queue.
+     */
+    enqueue(options: EnqueueOptions<z.infer<TPayloadSchema>>): Promise<string>;
+    /**
+     * Enqueue multiple messages to a queue.
+     */
+    enqueueBatch(options: EnqueueBatchOptions<z.infer<TPayloadSchema>>): Promise<string[]>;
+    /**
+     * Get messages from the dead letter queue for a tenant.
+     */
+    getDeadLetterMessages(tenantId: string, limit?: number): Promise<DeadLetterMessage<z.infer<TPayloadSchema>>[]>;
+    /**
+     * Redrive a message from DLQ back to its original queue.
+     */
+    redriveMessage(tenantId: string, messageId: string): Promise<boolean>;
+    /**
+     * Redrive all messages from DLQ back to their original queues.
+     */
+    redriveAll(tenantId: string): Promise<number>;
+    /**
+     * Purge all messages from a tenant's DLQ.
+     */
+    purgeDeadLetterQueue(tenantId: string): Promise<number>;
+    /**
+     * Get the number of messages in a tenant's DLQ.
+     */
+    getDeadLetterQueueLength(tenantId: string): Promise<number>;
+    /**
+     * Get the size of the in-memory queue descriptor cache.
+     * This cache stores metadata for queues that have been enqueued.
+     * The cache is cleaned up when queues are fully processed.
+     */
+    getQueueDescriptorCacheSize(): number;
+    /**
+     * Get the size of the in-memory cooloff states cache.
+     * This cache tracks queues that are in cooloff due to repeated failures.
+     * The cache is cleaned up when queues are fully processed or cooloff expires.
+     */
+    getQueueCooloffStatesSize(): number;
+    /**
+     * Get all in-memory cache sizes for monitoring.
+     * Useful for adding as span attributes.
+     */
+    getCacheSizes(): {
+        descriptorCacheSize: number;
+        cooloffStatesSize: number;
+    };
+    /**
+     * Start the master queue consumer loops and reclaim loop.
+     * FairQueue claims messages and pushes them to worker queues.
+     * External consumers are responsible for consuming from worker queues.
+     */
+    start(): void;
+    /**
+     * Stop the consumer loops gracefully.
+     */
+    stop(): Promise<void>;
+    /**
+     * Close all resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Get the number of messages in a queue.
+     */
+    getQueueLength(queueId: string): Promise<number>;
+    /**
+     * Get total queue count across all shards.
+     */
+    getTotalQueueCount(): Promise<number>;
+    /**
+     * Get total in-flight message count.
+     */
+    getTotalInflightCount(): Promise<number>;
+    /**
+     * Get the shard ID for a queue.
+     */
+    getShardForQueue(queueId: string): number;
+    /**
+     * Get message data from in-flight storage.
+     * External consumers use this to retrieve the stored message after popping from worker queue.
+     *
+     * @param messageId - The ID of the message
+     * @param queueId - The queue ID the message belongs to
+     * @returns The stored message or null if not found
+     */
+    getMessageData(messageId: string, queueId: string): Promise<StoredMessage<z.infer<TPayloadSchema>> | null>;
+    /**
+     * Extend the visibility timeout for a message.
+     * External consumers should call this periodically during long-running processing.
+     *
+     * @param messageId - The ID of the message
+     * @param queueId - The queue ID the message belongs to
+     * @returns true if heartbeat was successful
+     */
+    heartbeatMessage(messageId: string, queueId: string): Promise<boolean>;
+    /**
+     * Mark a message as successfully processed.
+     * This removes the message from in-flight and releases concurrency.
+     *
+     * @param messageId - The ID of the message
+     * @param queueId - The queue ID the message belongs to
+     */
+    completeMessage(messageId: string, queueId: string): Promise<void>;
+    /**
+     * Release a message back to the queue for processing by another consumer.
+     * The message is placed at the back of the queue.
+     *
+     * @param messageId - The ID of the message
+     * @param queueId - The queue ID the message belongs to
+     */
+    releaseMessage(messageId: string, queueId: string): Promise<void>;
+    /**
+     * Mark a message as failed. This will trigger retry logic if configured,
+     * or move the message to the dead letter queue.
+     *
+     * @param messageId - The ID of the message
+     * @param queueId - The queue ID the message belongs to
+     * @param error - Optional error that caused the failure
+     */
+    failMessage(messageId: string, queueId: string, error?: Error): Promise<void>;
+}
+declare module "@internal/redis" {
+    interface RedisCommander<Context> {
+        enqueueMessageAtomic(queueKey: string, queueItemsKey: string, masterQueueKey: string, queueId: string, messageId: string, timestamp: string, payload: string): Promise<number>;
+        enqueueBatchAtomic(queueKey: string, queueItemsKey: string, masterQueueKey: string, queueId: string, ...args: string[]): Promise<number>;
+        updateMasterQueueIfEmpty(masterQueueKey: string, queueKey: string, queueId: string): Promise<number>;
+    }
+}
+
+export { type AnyMessageCatalog, type AnyQueueItem, BaseScheduler, BatchedSpanManager, type BatchedSpanManagerOptions, CallbackFairQueueKeyProducer, type ClaimResult, type ConcurrencyCheckResult, type ConcurrencyGroupConfig, ConcurrencyManager, type ConcurrencyManagerOptions, type ConcurrencyState, type ConsumerLoopState, type CooloffOptions, CronSchema, CustomRetry, DRRScheduler, type DRRSchedulerConfig, type DeadLetterMessage, DefaultFairQueueKeyProducer, type EnqueueBatchOptions, type EnqueueOptions, ExponentialBackoffRetry, FairQueue, FairQueueAttributes, type FairQueueKeyProducer, type FairQueueMetrics, type FairQueueOptions, FairQueueTelemetry, type FairScheduler, FixedDelayRetry, type GlobalRateLimiter, ImmediateRetry, type InFlightMessage, type JobHandler, type JobHandlerParams, LinearBackoffRetry, MasterQueue, type MasterQueueOptions, type MessageCatalogKey, type MessageCatalogSchema, type MessageCatalogValue, type MessageHandler, type MessageHandlerContext, MessagingAttributes, NoRetry, NoopScheduler, type QueueCooloffState, type QueueDescriptor, type QueueItem, type QueueMessage, type QueueWithScore, type RetryOptions, type RetryStrategy, RoundRobinScheduler, type SchedulerContext, SimpleQueue, type StoredMessage, type TelemetryOptions, type TenantQueues, VisibilityManager, type VisibilityManagerOptions, WeightedScheduler, type WeightedSchedulerBiases, type WeightedSchedulerConfig, Worker, type WorkerCatalog, type WorkerConcurrencyOptions, WorkerQueueManager, type WorkerQueueManagerOptions, type WorkerQueueOptions, createDefaultRetryStrategy, defaultRetryOptions, isAbortError, noopTelemetry };