bunqueue 2.8.34 → 2.8.36

package/dist/domain/queue/limiterManager.js

@@ -34,20 +34,47 @@ export class LimiterManager {
         this.getState(name).paused = false;
     }
     // ============ Rate Limiting ============
-    /** Set rate limit for queue */
-    setRateLimit(queue, limit) {
-        this.rateLimiters.set(queue, new RateLimiter(limit));
-        this.getState(queue).rateLimit = limit;
+    /**
+     * Set rate limit for queue.
+     * @param durationMs window the limit applies to (default 1000ms): `limit`
+     *   tokens refill over `durationMs`. Non-finite or non-positive → default.
+     * @param ttlMs auto-expiry: the limit clears itself after this many ms
+     *   (lazy, checked on acquire/read). Non-finite or non-positive → permanent.
+     */
+    setRateLimit(queue, limit, durationMs, ttlMs) {
+        const duration = Number.isFinite(durationMs) && durationMs > 0 ? durationMs : null;
+        const ttl = Number.isFinite(ttlMs) && ttlMs > 0 ? ttlMs : null;
+        const windowSeconds = (duration ?? 1000) / 1000;
+        this.rateLimiters.set(queue, new RateLimiter(limit, limit / windowSeconds));
+        const state = this.getState(queue);
+        state.rateLimit = limit;
+        state.rateLimitDuration = duration;
+        state.rateLimitExpiresAt = ttl === null ? null : Date.now() + ttl;
     }
     /** Clear rate limit */
     clearRateLimit(queue) {
         this.rateLimiters.delete(queue);
         const state = this.queueState.get(queue);
-        if (state)
+        if (state) {
             state.rateLimit = null;
+            state.rateLimitDuration = null;
+            state.rateLimitExpiresAt = null;
+        }
+    }
+    /**
+     * Drop the rate limit if its TTL has elapsed. Lazy expiry: called from the
+     * acquire path and from limit reads, so no timer is needed and an expired
+     * limit can never throttle a pull.
+     */
+    expireRateLimitIfNeeded(queue) {
+        const expiresAt = this.queueState.get(queue)?.rateLimitExpiresAt;
+        if (expiresAt !== null && expiresAt !== undefined && Date.now() >= expiresAt) {
+            this.clearRateLimit(queue);
+        }
     }
     /** Try to acquire rate limit token */
     tryAcquireRateLimit(queue) {
+        this.expireRateLimitIfNeeded(queue);
         const limiter = this.rateLimiters.get(queue);
         return !limiter || limiter.tryAcquire();
     }

package/dist/domain/queue/shard.d.ts

@@ -69,8 +69,9 @@ export declare class Shard {
     isGroupActive(queue: string, groupId: string): boolean;
     activateGroup(queue: string, groupId: string): void;
     releaseGroup(queue: string, groupId: string): void;
-    setRateLimit(queue: string, limit: number): void;
+    setRateLimit(queue: string, limit: number, durationMs?: number, ttlMs?: number): void;
     clearRateLimit(queue: string): void;
+    expireRateLimitIfNeeded(queue: string): void;
     tryAcquireRateLimit(queue: string): boolean;
     setConcurrency(queue: string, limit: number): void;
     clearConcurrency(queue: string): void;
@@ -134,5 +135,5 @@ export declare class Shard {
         count: number;
         jobIds: JobId[];
     };
-    obliterate(queue: string): void;
+    obliterate(queue: string): JobId[];
 }

package/dist/domain/queue/shard.js

@@ -138,12 +138,15 @@ export class Shard {
         this.activeGroups.get(queue)?.delete(groupId);
     }
     // ============ Rate & Concurrency Limiting (delegated) ============
-    setRateLimit(queue, limit) {
-        this.limiterManager.setRateLimit(queue, limit);
+    setRateLimit(queue, limit, durationMs, ttlMs) {
+        this.limiterManager.setRateLimit(queue, limit, durationMs, ttlMs);
     }
     clearRateLimit(queue) {
         this.limiterManager.clearRateLimit(queue);
     }
+    expireRateLimitIfNeeded(queue) {
+        this.limiterManager.expireRateLimitIfNeeded(queue);
+    }
     tryAcquireRateLimit(queue) {
         return this.limiterManager.tryAcquireRateLimit(queue);
     }
@@ -361,13 +364,18 @@ export class Shard {
         return { count, jobIds };
     }
     obliterate(queue) {
+        const removed = new Set(this.dependencyTracker.removeQueue(queue));
         const q = this.queues.get(queue);
         if (q) {
             for (const job of q.values()) {
+                removed.add(job.id);
                 this.temporalManager.removeDelayed(job.id);
             }
             this.counters.adjustQueued(-q.size);
         }
+        for (const entry of this.dlqManager.getEntries(queue)) {
+            removed.add(entry.job.id);
+        }
         const dlqCount = this.dlqManager.deleteQueue(queue);
         if (dlqCount > 0) {
             this.counters.adjustDlq(-dlqCount);
@@ -378,5 +386,6 @@ export class Shard {
         this.uniqueKeyManager.clearQueue(queue);
         this.limiterManager.deleteQueue(queue);
         this.activeGroups.delete(queue);
+        return Array.from(removed);
     }
 }

package/dist/domain/types/command.d.ts

@@ -253,6 +253,10 @@ export interface RateLimitCommand extends BaseCommand {
     readonly cmd: 'RateLimit';
     readonly queue: string;
     readonly limit: number;
+    /** Window in ms the limit applies to (default 1000: `limit` per second). */
+    readonly duration?: number;
+    /** Auto-expiry in ms: the limit clears itself broker-side after this long. */
+    readonly ttl?: number;
 }
 export interface SetConcurrencyCommand extends BaseCommand {
     readonly cmd: 'SetConcurrency';

package/dist/domain/types/queue.d.ts

@@ -7,6 +7,10 @@ export interface QueueState {
     readonly name: string;
     paused: boolean;
     rateLimit: number | null;
+    /** Rate-limit window in ms (null = default 1000ms bucket). */
+    rateLimitDuration: number | null;
+    /** Epoch ms after which the rate limit self-expires (null = permanent). */
+    rateLimitExpiresAt: number | null;
     concurrencyLimit: number | null;
     activeCount: number;
 }

package/dist/domain/types/queue.js

@@ -8,6 +8,8 @@ export function createQueueState(name) {
         name,
         paused: false,
         rateLimit: null,
+        rateLimitDuration: null,
+        rateLimitExpiresAt: null,
         concurrencyLimit: null,
         activeCount: 0,
     };

package/dist/infrastructure/persistence/schema.d.ts

@@ -4,10 +4,10 @@
 /** SQLite PRAGMA settings for optimal performance */
 export declare const PRAGMA_SETTINGS = "\nPRAGMA journal_mode = WAL;\nPRAGMA synchronous = NORMAL;\nPRAGMA cache_size = -64000;\nPRAGMA temp_store = MEMORY;\nPRAGMA mmap_size = 268435456;\nPRAGMA page_size = 4096;\nPRAGMA busy_timeout = 5000;\n";
 /** Main schema creation */
-export declare const SCHEMA = "\n-- Jobs table (using UUIDv7 for job IDs)\n-- Uses BLOB for data fields (MessagePack serialization for ~2-3x faster than JSON)\nCREATE TABLE IF NOT EXISTS jobs (\n    id TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    priority INTEGER NOT NULL DEFAULT 0,\n    created_at INTEGER NOT NULL,\n    run_at INTEGER NOT NULL,\n    started_at INTEGER,\n    completed_at INTEGER,\n    attempts INTEGER NOT NULL DEFAULT 0,\n    max_attempts INTEGER NOT NULL DEFAULT 3,\n    backoff INTEGER NOT NULL DEFAULT 1000,\n    ttl INTEGER,\n    timeout INTEGER,\n    unique_key TEXT,\n    custom_id TEXT,\n    depends_on BLOB,\n    parent_id TEXT,\n    children_ids BLOB,\n    tags BLOB,\n    state TEXT NOT NULL DEFAULT 'waiting',\n    lifo INTEGER NOT NULL DEFAULT 0,\n    group_id TEXT,\n    progress INTEGER DEFAULT 0,\n    progress_msg TEXT,\n    remove_on_complete INTEGER DEFAULT 0,\n    remove_on_fail INTEGER DEFAULT 0,\n    stall_timeout INTEGER,\n    last_heartbeat INTEGER,\n    timeline BLOB,\n    stacktrace BLOB\n);\n\n-- Indexes for common queries\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_state\n    ON jobs(queue, state);\n-- Stable createdAt/id pagination for unfiltered and logical-state queue views\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_created\n    ON jobs(queue, created_at, id);\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_state_created\n    ON jobs(queue, state, created_at, id);\nCREATE INDEX IF NOT EXISTS idx_jobs_run_at\n    ON jobs(run_at) WHERE state IN ('waiting', 'delayed');\nCREATE INDEX IF NOT EXISTS idx_jobs_unique\n    ON jobs(queue, unique_key) WHERE unique_key IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_custom_id\n    ON jobs(custom_id) WHERE custom_id IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_parent\n    ON jobs(parent_id) WHERE parent_id IS NOT NULL;\n\n-- Job results storage (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS job_results (\n    job_id TEXT PRIMARY KEY,\n    result BLOB,\n    completed_at INTEGER NOT NULL\n);\n\n-- Dead letter queue (BLOB for MessagePack - stores full DlqEntry)\nCREATE TABLE IF NOT EXISTS dlq (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    job_id TEXT NOT NULL,\n    queue TEXT NOT NULL,\n    entry BLOB NOT NULL,\n    entered_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_dlq_queue ON dlq(queue);\nCREATE INDEX IF NOT EXISTS idx_dlq_job_id ON dlq(job_id);\nCREATE INDEX IF NOT EXISTS idx_dlq_entered_at ON dlq(entered_at);\n\n-- Performance indexes for high-throughput operations\n-- Stall detection: runs every 5s, needs fast lookup of active jobs by started_at\nCREATE INDEX IF NOT EXISTS idx_jobs_state_started\n    ON jobs(state, started_at) WHERE state = 'active';\n\n-- Group operations: fast lookup by group_id\nCREATE INDEX IF NOT EXISTS idx_jobs_group_id\n    ON jobs(group_id) WHERE group_id IS NOT NULL;\n\n-- Pending jobs: compound index for priority-ordered retrieval\nCREATE INDEX IF NOT EXISTS idx_jobs_pending_priority\n    ON jobs(queue, state, priority DESC, run_at ASC) WHERE state IN ('waiting', 'delayed');\n\n-- Completed jobs: index for recovery ordering (issue #84)\nCREATE INDEX IF NOT EXISTS idx_jobs_completed_order\n    ON jobs(completed_at DESC) WHERE state = 'completed';\n\n-- Cron jobs (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS cron_jobs (\n    name TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    schedule TEXT,\n    repeat_every INTEGER,\n    priority INTEGER NOT NULL DEFAULT 0,\n    next_run INTEGER NOT NULL,\n    executions INTEGER NOT NULL DEFAULT 0,\n    max_limit INTEGER,\n    timezone TEXT,\n    unique_key TEXT,\n    dedup BLOB,\n    skip_missed_on_restart INTEGER NOT NULL DEFAULT 0,\n    skip_if_no_worker INTEGER NOT NULL DEFAULT 0,\n    prevent_overlap INTEGER NOT NULL DEFAULT 1,\n    job_options BLOB\n);\n\n-- Queue state persistence (optional)\nCREATE TABLE IF NOT EXISTS queue_state (\n    name TEXT PRIMARY KEY,\n    paused INTEGER NOT NULL DEFAULT 0,\n    rate_limit INTEGER,\n    concurrency_limit INTEGER\n);\n";
+export declare const SCHEMA = "\n-- Jobs table (using UUIDv7 for job IDs)\n-- Uses BLOB for data fields (MessagePack serialization for ~2-3x faster than JSON)\nCREATE TABLE IF NOT EXISTS jobs (\n    id TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    priority INTEGER NOT NULL DEFAULT 0,\n    created_at INTEGER NOT NULL,\n    run_at INTEGER NOT NULL,\n    started_at INTEGER,\n    completed_at INTEGER,\n    attempts INTEGER NOT NULL DEFAULT 0,\n    max_attempts INTEGER NOT NULL DEFAULT 3,\n    backoff INTEGER NOT NULL DEFAULT 1000,\n    ttl INTEGER,\n    timeout INTEGER,\n    unique_key TEXT,\n    custom_id TEXT,\n    depends_on BLOB,\n    parent_id TEXT,\n    children_ids BLOB,\n    tags BLOB,\n    state TEXT NOT NULL DEFAULT 'waiting',\n    lifo INTEGER NOT NULL DEFAULT 0,\n    group_id TEXT,\n    progress INTEGER DEFAULT 0,\n    progress_msg TEXT,\n    remove_on_complete INTEGER DEFAULT 0,\n    remove_on_fail INTEGER DEFAULT 0,\n    stall_timeout INTEGER,\n    last_heartbeat INTEGER,\n    stall_count INTEGER NOT NULL DEFAULT 0,\n    timeline BLOB,\n    stacktrace BLOB\n);\n\n-- Indexes for common queries\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_state\n    ON jobs(queue, state);\n-- Stable createdAt/id pagination for unfiltered and logical-state queue views\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_created\n    ON jobs(queue, created_at, id);\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_state_created\n    ON jobs(queue, state, created_at, id);\nCREATE INDEX IF NOT EXISTS idx_jobs_run_at\n    ON jobs(run_at) WHERE state IN ('waiting', 'delayed');\nCREATE INDEX IF NOT EXISTS idx_jobs_unique\n    ON jobs(queue, unique_key) WHERE unique_key IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_custom_id\n    ON jobs(custom_id) WHERE custom_id IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_parent\n    ON jobs(parent_id) WHERE parent_id IS NOT NULL;\n\n-- Job results storage (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS job_results (\n    job_id TEXT PRIMARY KEY,\n    result BLOB,\n    completed_at INTEGER NOT NULL\n);\n\n-- Dead letter queue (BLOB for MessagePack - stores full DlqEntry)\nCREATE TABLE IF NOT EXISTS dlq (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    job_id TEXT NOT NULL,\n    queue TEXT NOT NULL,\n    entry BLOB NOT NULL,\n    entered_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_dlq_queue ON dlq(queue);\nCREATE INDEX IF NOT EXISTS idx_dlq_job_id ON dlq(job_id);\nCREATE INDEX IF NOT EXISTS idx_dlq_entered_at ON dlq(entered_at);\n\n-- Performance indexes for high-throughput operations\n-- Stall detection: runs every 5s, needs fast lookup of active jobs by started_at\nCREATE INDEX IF NOT EXISTS idx_jobs_state_started\n    ON jobs(state, started_at) WHERE state = 'active';\n\n-- Group operations: fast lookup by group_id\nCREATE INDEX IF NOT EXISTS idx_jobs_group_id\n    ON jobs(group_id) WHERE group_id IS NOT NULL;\n\n-- Pending jobs: compound index for priority-ordered retrieval\nCREATE INDEX IF NOT EXISTS idx_jobs_pending_priority\n    ON jobs(queue, state, priority DESC, run_at ASC) WHERE state IN ('waiting', 'delayed');\n\n-- Completed jobs: index for recovery ordering (issue #84)\nCREATE INDEX IF NOT EXISTS idx_jobs_completed_order\n    ON jobs(completed_at DESC) WHERE state = 'completed';\n\n-- Cron jobs (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS cron_jobs (\n    name TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    schedule TEXT,\n    repeat_every INTEGER,\n    priority INTEGER NOT NULL DEFAULT 0,\n    next_run INTEGER NOT NULL,\n    executions INTEGER NOT NULL DEFAULT 0,\n    max_limit INTEGER,\n    timezone TEXT,\n    unique_key TEXT,\n    dedup BLOB,\n    skip_missed_on_restart INTEGER NOT NULL DEFAULT 0,\n    skip_if_no_worker INTEGER NOT NULL DEFAULT 0,\n    prevent_overlap INTEGER NOT NULL DEFAULT 1,\n    job_options BLOB\n);\n\n-- Queue state persistence (optional)\nCREATE TABLE IF NOT EXISTS queue_state (\n    name TEXT PRIMARY KEY,\n    paused INTEGER NOT NULL DEFAULT 0,\n    rate_limit INTEGER,\n    concurrency_limit INTEGER,\n    rate_limit_duration INTEGER,\n    rate_limit_expires_at INTEGER,\n    stall_enabled INTEGER,\n    stall_interval INTEGER,\n    max_stalls INTEGER,\n    stall_grace_period INTEGER\n);\n";
 /** Migration version table */
 export declare const MIGRATION_TABLE = "\nCREATE TABLE IF NOT EXISTS migrations (\n    version INTEGER PRIMARY KEY,\n    applied_at INTEGER NOT NULL\n);\n";
 /** Current schema version */
-export declare const SCHEMA_VERSION = 14;
+export declare const SCHEMA_VERSION = 21;
 /** All migrations in order */
 export declare const MIGRATIONS: Record<number, string>;

package/dist/infrastructure/persistence/schema.js

@@ -44,6 +44,7 @@ CREATE TABLE IF NOT EXISTS jobs (
     remove_on_fail INTEGER DEFAULT 0,
     stall_timeout INTEGER,
     last_heartbeat INTEGER,
+    stall_count INTEGER NOT NULL DEFAULT 0,
     timeline BLOB,
     stacktrace BLOB
 );
@@ -127,7 +128,13 @@ CREATE TABLE IF NOT EXISTS queue_state (
     name TEXT PRIMARY KEY,
     paused INTEGER NOT NULL DEFAULT 0,
     rate_limit INTEGER,
-    concurrency_limit INTEGER
+    concurrency_limit INTEGER,
+    rate_limit_duration INTEGER,
+    rate_limit_expires_at INTEGER,
+    stall_enabled INTEGER,
+    stall_interval INTEGER,
+    max_stalls INTEGER,
+    stall_grace_period INTEGER
 );
 `;
 /** Migration version table */
@@ -138,7 +145,7 @@ CREATE TABLE IF NOT EXISTS migrations (
 );
 `;
 /** Current schema version */
-export const SCHEMA_VERSION = 14;
+export const SCHEMA_VERSION = 21;
 /** All migrations in order */
 export const MIGRATIONS = {
     1: SCHEMA,
@@ -199,5 +206,34 @@ CREATE INDEX IF NOT EXISTS idx_jobs_queue_created
     ON jobs(queue, created_at, id);
 CREATE INDEX IF NOT EXISTS idx_jobs_queue_state_created
     ON jobs(queue, state, created_at, id);
+`,
+    // Migrations 15-16: Rate-limit window (duration) + TTL auto-expiry on
+    // queue_state. One ALTER per migration ON PURPOSE: each runs in its own
+    // db.run with its own error-swallow, so a crash between the two leaves a
+    // retryable state (a two-ALTER string would abort at the first "duplicate
+    // column" on re-run and never execute the second statement).
+    15: `
+ALTER TABLE queue_state ADD COLUMN rate_limit_duration INTEGER;
+`,
+    16: `
+ALTER TABLE queue_state ADD COLUMN rate_limit_expires_at INTEGER;
+`,
+    // Migration 17: preserve the cumulative stall bound across restarts.
+    17: `
+ALTER TABLE jobs ADD COLUMN stall_count INTEGER NOT NULL DEFAULT 0;
+`,
+    // Migrations 18-21: persist the complete per-queue stall policy. One ALTER
+    // per version keeps interrupted upgrades retryable (same rule as 15-16).
+    18: `
+ALTER TABLE queue_state ADD COLUMN stall_enabled INTEGER;
+`,
+    19: `
+ALTER TABLE queue_state ADD COLUMN stall_interval INTEGER;
+`,
+    20: `
+ALTER TABLE queue_state ADD COLUMN max_stalls INTEGER;
+`,
+    21: `
+ALTER TABLE queue_state ADD COLUMN stall_grace_period INTEGER;
 `,
 };

package/dist/infrastructure/persistence/sqlite.d.ts

@@ -4,6 +4,7 @@
  * Uses MessagePack for ~2-3x faster serialization than JSON
  */
 import type { Job, JobId, JobTimelineEntry } from '../../domain/types/job';
+import type { StallConfig } from '../../domain/types/stall';
 import type { CronJob } from '../../domain/types/cron';
 import { type DlqEntry } from '../../domain/types/dlq';
 /** Critical-loss callback: invoked when WriteBuffer drops jobs after exhausting retries. */
@@ -101,12 +102,20 @@ export declare class SqliteStorage {
     deleteDlqEntry(jobId: JobId): void;
     /** Clear all DLQ entries for a queue */
     clearDlqQueue(queue: string): void;
+    /**
+     * Permanently purge terminal DLQ jobs in one transaction.
+     * Pending buffered inserts are removed first so a purged job cannot be
+     * written back after the transaction commits.
+     */
+    purgeDlqEntries(queue: string, dlqJobIds: readonly JobId[], terminalJobIds: readonly JobId[], clearQueue: boolean): void;
     /** Load all DLQ entries */
     loadDlq(): Map<string, DlqEntry[]>;
     updateForRetry(job: Job): void;
     deleteJob(jobId: JobId): void;
     /** Update a job's data blob (e.g. after adding __parentId) */
     updateJobData(jobId: JobId, data: unknown): void;
+    /** Persist priority ordering, including its LIFO tie-break, across recovery. */
+    updateJobPriority(jobId: JobId, priority: number, lifo: boolean): void;
     /**
      * Persist a delay change (moveToDelayed / changeDelay) so the new `run_at`
      * survives a restart. Without this the delay lives only in the in-memory heap:
@@ -204,13 +213,23 @@ export declare class SqliteStorage {
      * Persist a queue's control-state (paused / rate-limit / concurrency) so it
      * survives a server restart. Write-through on every pause/resume/limit change.
      */
-    saveQueueState(name: string, paused: boolean, rateLimit: number | null, concurrencyLimit: number | null): void;
+    saveQueueState(name: string, state: {
+        paused: boolean;
+        rateLimit: number | null;
+        concurrencyLimit: number | null;
+        rateLimitDuration?: number | null;
+        rateLimitExpiresAt?: number | null;
+        stallConfig?: StallConfig | null;
+    }): void;
     /** Load all persisted queue control-state rows (used by recover() on boot). */
     loadQueueState(): Array<{
         name: string;
         paused: boolean;
         rateLimit: number | null;
         concurrencyLimit: number | null;
+        rateLimitDuration: number | null;
+        rateLimitExpiresAt: number | null;
+        stallConfig: StallConfig | null;
     }>;
     /** Drop a queue's persisted control-state (e.g. on obliterate). */
     deleteQueueState(name: string): void;

package/dist/infrastructure/persistence/sqlite.js

@@ -7,7 +7,7 @@ import { Database } from 'bun:sqlite';
 import { createDlqEntry } from '../../domain/types/dlq';
 import { PRAGMA_SETTINGS, SCHEMA, MIGRATION_TABLE, SCHEMA_VERSION, MIGRATIONS } from './schema';
 import { prepareStatements, } from './statements';
-import { pack, unpack, rowToJob, reconstructDlqEntry } from './sqliteSerializer';
+import { pack, persistedStallCount, reconstructDlqEntry, rowToJob, unpack, } from './sqliteSerializer';
 import { BatchInsertManager, WriteBuffer } from './sqliteBatch';
 import { storageLog } from '../../shared/logger';
 /** Check if an error is a SQLITE_FULL (disk full) error */
@@ -251,7 +251,7 @@ export class SqliteStorage {
     runInsertJobStmt(job) {
         this.statements
             .get('insertJob')
-            .run(job.id, job.queue, pack(job.data), job.priority, job.createdAt, job.runAt, job.attempts, job.maxAttempts, job.backoff, job.ttl, job.timeout, job.uniqueKey, job.customId, job.dependsOn.length > 0 ? pack(job.dependsOn) : null, job.parentId, job.childrenIds.length > 0 ? pack(job.childrenIds) : null, job.tags.length > 0 ? pack(job.tags) : null, job.runAt > Date.now() ? 'delayed' : 'waiting', job.lifo ? 1 : 0, job.groupId, job.removeOnComplete ? 1 : 0, job.removeOnFail ? 1 : 0, job.stallTimeout, job.timeline.length > 0 ? pack(job.timeline) : null);
+            .run(job.id, job.queue, pack(job.data), job.priority, job.createdAt, job.runAt, job.attempts, job.maxAttempts, job.backoff, job.ttl, job.timeout, job.uniqueKey, job.customId, job.dependsOn.length > 0 ? pack(job.dependsOn) : null, job.parentId, job.childrenIds.length > 0 ? pack(job.childrenIds) : null, job.tags.length > 0 ? pack(job.tags) : null, job.runAt > Date.now() ? 'delayed' : 'waiting', job.lifo ? 1 : 0, job.groupId, job.removeOnComplete ? 1 : 0, job.removeOnFail ? 1 : 0, job.stallTimeout, persistedStallCount(job), job.timeline.length > 0 ? pack(job.timeline) : null);
     }
     /**
      * Ensure a job's buffered INSERT has been written to disk before issuing a
@@ -315,6 +315,35 @@ export class SqliteStorage {
             this.statements.get('clearDlqQueue').run(queue);
         });
     }
+    /**
+     * Permanently purge terminal DLQ jobs in one transaction.
+     * Pending buffered inserts are removed first so a purged job cannot be
+     * written back after the transaction commits.
+     */
+    purgeDlqEntries(queue, dlqJobIds, terminalJobIds, clearQueue) {
+        for (const jobId of terminalJobIds)
+            this.writeBuffer.removePending(jobId);
+        this.safeWrite(() => {
+            const deleteDlq = this.statements.get('deleteDlqEntryForQueue');
+            const clearDlq = this.statements.get('clearDlqQueue');
+            const deleteJob = this.statements.get('deleteJob');
+            const deleteResult = this.statements.get('deleteJobResult');
+            const tx = this.db.transaction(() => {
+                if (clearQueue) {
+                    clearDlq.run(queue);
+                }
+                else {
+                    for (const jobId of dlqJobIds)
+                        deleteDlq.run(jobId, queue);
+                }
+                for (const jobId of terminalJobIds) {
+                    deleteJob.run(jobId);
+                    deleteResult.run(jobId);
+                }
+            });
+            tx();
+        });
+    }
     /** Load all DLQ entries */
     loadDlq() {
         const rows = this.statements.get('loadDlq').all();
@@ -336,8 +365,8 @@ export class SqliteStorage {
     updateForRetry(job) {
         this.safeWrite(() => {
             this.db
-                .prepare('UPDATE jobs SET attempts = ?, run_at = ?, state = ?, timeline = ?, stacktrace = ? WHERE id = ?')
-                .run(job.attempts, job.runAt, 'waiting', job.timeline.length > 0 ? pack(job.timeline) : null, job.stacktrace && job.stacktrace.length > 0 ? pack(job.stacktrace) : null, job.id);
+                .prepare('UPDATE jobs SET attempts = ?, stall_count = ?, run_at = ?, state = ?, timeline = ?, stacktrace = ? WHERE id = ?')
+                .run(job.attempts, persistedStallCount(job), job.runAt, 'waiting', job.timeline.length > 0 ? pack(job.timeline) : null, job.stacktrace && job.stacktrace.length > 0 ? pack(job.stacktrace) : null, job.id);
         });
     }
     deleteJob(jobId) {
@@ -360,10 +389,20 @@ export class SqliteStorage {
     }
     /** Update a job's data blob (e.g. after adding __parentId) */
     updateJobData(jobId, data) {
+        this.flushIfBuffered(jobId);
         this.safeWrite(() => {
             this.db.prepare('UPDATE jobs SET data = ? WHERE id = ?').run(pack(data), jobId);
         });
     }
+    /** Persist priority ordering, including its LIFO tie-break, across recovery. */
+    updateJobPriority(jobId, priority, lifo) {
+        this.flushIfBuffered(jobId);
+        this.safeWrite(() => {
+            this.db
+                .prepare('UPDATE jobs SET priority = ?, lifo = ? WHERE id = ?')
+                .run(priority, lifo ? 1 : 0, jobId);
+        });
+    }
     /**
      * Persist a delay change (moveToDelayed / changeDelay) so the new `run_at`
      * survives a restart. Without this the delay lives only in the in-memory heap:
@@ -650,11 +689,15 @@ export class SqliteStorage {
      * Persist a queue's control-state (paused / rate-limit / concurrency) so it
      * survives a server restart. Write-through on every pause/resume/limit change.
      */
-    saveQueueState(name, paused, rateLimit, concurrencyLimit) {
+    saveQueueState(name, state) {
         this.safeWrite(() => {
             this.statements
                 .get('upsertQueueState')
-                .run(name, paused ? 1 : 0, rateLimit, concurrencyLimit);
+                .run(name, state.paused ? 1 : 0, state.rateLimit, state.concurrencyLimit, state.rateLimitDuration ?? null, state.rateLimitExpiresAt ?? null, state.stallConfig === null || state.stallConfig === undefined
+                ? null
+                : state.stallConfig.enabled
+                    ? 1
+                    : 0, state.stallConfig?.stallInterval ?? null, state.stallConfig?.maxStalls ?? null, state.stallConfig?.gracePeriod ?? null);
         });
     }
     /** Load all persisted queue control-state rows (used by recover() on boot). */
@@ -665,6 +708,19 @@ export class SqliteStorage {
             paused: row.paused === 1,
             rateLimit: row.rate_limit,
             concurrencyLimit: row.concurrency_limit,
+            rateLimitDuration: row.rate_limit_duration ?? null,
+            rateLimitExpiresAt: row.rate_limit_expires_at ?? null,
+            stallConfig: row.stall_enabled === null ||
+                row.stall_interval === null ||
+                row.max_stalls === null ||
+                row.stall_grace_period === null
+                ? null
+                : {
+                    enabled: row.stall_enabled === 1,
+                    stallInterval: row.stall_interval,
+                    maxStalls: row.max_stalls,
+                    gracePeriod: row.stall_grace_period,
+                },
         }));
     }
     /** Drop a queue's persisted control-state (e.g. on obliterate). */

package/dist/infrastructure/persistence/sqliteBatch.js

@@ -2,8 +2,8 @@
  * SQLite Batch Operations
  * High-performance batch insert with prepared statement caching
  */
-import { pack } from './sqliteSerializer';
-const COLS_PER_ROW = 24;
+import { pack, persistedStallCount } from './sqliteSerializer';
+const COLS_PER_ROW = 25;
 // SQLite has a limit of ~999 variables, so batch in chunks
 const MAX_ROWS_PER_INSERT = Math.floor(999 / COLS_PER_ROW);
 /**
@@ -75,7 +75,7 @@ export class BatchInsertManager {
     getBatchInsertStmt(size) {
         let stmt = this.cache.get(size);
         if (!stmt) {
-            const rowPlaceholder = '(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)';
+            const rowPlaceholder = '(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)';
             const placeholders = Array(size).fill(rowPlaceholder).join(', ');
             // ON CONFLICT(id) DO UPDATE (upsert): a colliding id overwrites in place instead
             // of failing the whole flush. Without it, one stale ORPHAN row (left when
@@ -86,7 +86,8 @@ export class BatchInsertManager {
             const sql = `INSERT INTO jobs (
         id, queue, data, priority, created_at, run_at, attempts, max_attempts,
         backoff, ttl, timeout, unique_key, custom_id, depends_on, parent_id,
-        children_ids, tags, state, lifo, group_id, remove_on_complete, remove_on_fail, stall_timeout, timeline
+        children_ids, tags, state, lifo, group_id, remove_on_complete, remove_on_fail,
+        stall_timeout, stall_count, timeline
       ) VALUES ${placeholders}
       ON CONFLICT(id) DO UPDATE SET
         queue=excluded.queue, data=excluded.data, priority=excluded.priority,
@@ -96,7 +97,8 @@ export class BatchInsertManager {
         depends_on=excluded.depends_on, parent_id=excluded.parent_id, children_ids=excluded.children_ids,
         tags=excluded.tags, state=excluded.state, lifo=excluded.lifo, group_id=excluded.group_id,
         remove_on_complete=excluded.remove_on_complete, remove_on_fail=excluded.remove_on_fail,
-        stall_timeout=excluded.stall_timeout, timeline=excluded.timeline,
+        stall_timeout=excluded.stall_timeout, stall_count=excluded.stall_count,
+        timeline=excluded.timeline,
         started_at=excluded.started_at, completed_at=excluded.completed_at,
         progress=excluded.progress, progress_msg=excluded.progress_msg,
         last_heartbeat=excluded.last_heartbeat, stacktrace=excluded.stacktrace`;
@@ -114,7 +116,7 @@ export class BatchInsertManager {
         // Flatten all values
         const values = [];
         for (const job of jobs) {
-            values.push(job.id, job.queue, pack(job.data), job.priority, job.createdAt, job.runAt, job.attempts, job.maxAttempts, job.backoff, job.ttl, job.timeout, job.uniqueKey, job.customId, job.dependsOn.length > 0 ? pack(job.dependsOn) : null, job.parentId, job.childrenIds.length > 0 ? pack(job.childrenIds) : null, job.tags.length > 0 ? pack(job.tags) : null, job.runAt > now ? 'delayed' : 'waiting', job.lifo ? 1 : 0, job.groupId, job.removeOnComplete ? 1 : 0, job.removeOnFail ? 1 : 0, job.stallTimeout, job.timeline.length > 0 ? pack(job.timeline) : null);
+            values.push(job.id, job.queue, pack(job.data), job.priority, job.createdAt, job.runAt, job.attempts, job.maxAttempts, job.backoff, job.ttl, job.timeout, job.uniqueKey, job.customId, job.dependsOn.length > 0 ? pack(job.dependsOn) : null, job.parentId, job.childrenIds.length > 0 ? pack(job.childrenIds) : null, job.tags.length > 0 ? pack(job.tags) : null, job.runAt > now ? 'delayed' : 'waiting', job.lifo ? 1 : 0, job.groupId, job.removeOnComplete ? 1 : 0, job.removeOnFail ? 1 : 0, job.stallTimeout, persistedStallCount(job), job.timeline.length > 0 ? pack(job.timeline) : null);
         }
         stmt.run(...values);
     }

package/dist/infrastructure/persistence/sqliteSerializer.d.ts

@@ -10,6 +10,12 @@ import type { DbJob } from './statements';
 export declare function pack(data: unknown): Uint8Array;
 /** Decode MessagePack buffer to data */
 export declare function unpack<T>(buffer: Uint8Array | null, fallback: T, context: string): T;
+/**
+ * Normalize jobs constructed by pre-stallCount integrations at the persistence
+ * boundary. The database keeps its NOT NULL invariant while an omitted legacy
+ * field receives the same zero default as a freshly created Job.
+ */
+export declare function persistedStallCount(job: Pick<Job, 'stallCount'>): number;
 /**
  * Symbol marker stamped on a Job whose `depends_on` blob failed to decode.
  *

package/dist/infrastructure/persistence/sqliteSerializer.js

@@ -22,6 +22,14 @@ export function unpack(buffer, fallback, context) {
         return fallback;
     }
 }
+/**
+ * Normalize jobs constructed by pre-stallCount integrations at the persistence
+ * boundary. The database keeps its NOT NULL invariant while an omitted legacy
+ * field receives the same zero default as a freshly created Job.
+ */
+export function persistedStallCount(job) {
+    return job.stallCount ?? 0;
+}
 /**
  * Symbol marker stamped on a Job whose `depends_on` blob failed to decode.
  *
@@ -104,7 +112,7 @@ export function rowToJob(row) {
         repeat: null,
         lastHeartbeat: row.last_heartbeat ?? row.created_at,
         stallTimeout: row.stall_timeout,
-        stallCount: 0,
+        stallCount: row.stall_count ?? 0,
         // BullMQ v5 additional fields (not persisted in DB, use defaults)
         stackTraceLimit: 10,
         keepLogs: null,

package/dist/infrastructure/persistence/statements.d.ts

@@ -4,7 +4,7 @@
  */
 import type { Database } from 'bun:sqlite';
 /** Statement names */
-export type StatementName = 'insertJob' | 'updateJobState' | 'completeJob' | 'deleteJob' | 'deleteJobResult' | 'getJob' | 'insertResult' | 'getResult' | 'insertDlq' | 'loadDlq' | 'deleteDlqEntry' | 'clearDlqQueue' | 'insertCron' | 'updateCron' | 'upsertQueueState' | 'loadQueueState' | 'deleteQueueState';
+export type StatementName = 'insertJob' | 'updateJobState' | 'completeJob' | 'deleteJob' | 'deleteJobResult' | 'getJob' | 'insertResult' | 'getResult' | 'insertDlq' | 'loadDlq' | 'deleteDlqEntry' | 'deleteDlqEntryForQueue' | 'clearDlqQueue' | 'insertCron' | 'updateCron' | 'upsertQueueState' | 'loadQueueState' | 'deleteQueueState';
 /** SQL statements */
 export declare const SQL_STATEMENTS: Record<StatementName, string>;
 /** Prepare all statements */
@@ -39,6 +39,7 @@ export interface DbJob {
     remove_on_fail: number;
     stall_timeout: number | null;
     last_heartbeat: number | null;
+    stall_count: number;
     timeline: Uint8Array | null;
     stacktrace: Uint8Array | null;
 }
@@ -67,4 +68,10 @@ export interface DbQueueState {
     paused: number;
     rate_limit: number | null;
     concurrency_limit: number | null;
+    rate_limit_duration: number | null;
+    rate_limit_expires_at: number | null;
+    stall_enabled: number | null;
+    stall_interval: number | null;
+    max_stalls: number | null;
+    stall_grace_period: number | null;
 }

package/dist/infrastructure/persistence/statements.js

@@ -15,12 +15,12 @@ export const SQL_STATEMENTS = {
       id, queue, data, priority, created_at, run_at, attempts,
       max_attempts, backoff, ttl, timeout, unique_key, custom_id,
       depends_on, parent_id, children_ids, tags, state, lifo, group_id,
-      remove_on_complete, remove_on_fail, stall_timeout, timeline
+      remove_on_complete, remove_on_fail, stall_timeout, stall_count, timeline
     ) VALUES (
       ?, ?, ?, ?, ?, ?, ?,
       ?, ?, ?, ?, ?, ?,
       ?, ?, ?, ?, ?, ?, ?,
-      ?, ?, ?, ?
+      ?, ?, ?, ?, ?
     )
     ON CONFLICT(id) DO UPDATE SET
       queue=excluded.queue, data=excluded.data, priority=excluded.priority,
@@ -30,7 +30,8 @@ export const SQL_STATEMENTS = {
       depends_on=excluded.depends_on, parent_id=excluded.parent_id, children_ids=excluded.children_ids,
       tags=excluded.tags, state=excluded.state, lifo=excluded.lifo, group_id=excluded.group_id,
       remove_on_complete=excluded.remove_on_complete, remove_on_fail=excluded.remove_on_fail,
-      stall_timeout=excluded.stall_timeout, timeline=excluded.timeline,
+      stall_timeout=excluded.stall_timeout, stall_count=excluded.stall_count,
+      timeline=excluded.timeline,
       -- Per-execution columns are NOT in the INSERT column list, so excluded.<col>
       -- resolves to each column's DEFAULT (NULL / 0) — i.e. the fresh-job value. Reset
       -- them too, otherwise an upsert over an ORPHAN row would leave a brand-new job
@@ -49,6 +50,7 @@ export const SQL_STATEMENTS = {
     insertDlq: 'INSERT INTO dlq (job_id, queue, entry, entered_at) VALUES (?, ?, ?, ?)',
     loadDlq: 'SELECT * FROM dlq ORDER BY entered_at',
     deleteDlqEntry: 'DELETE FROM dlq WHERE job_id = ?',
+    deleteDlqEntryForQueue: 'DELETE FROM dlq WHERE job_id = ? AND queue = ?',
     clearDlqQueue: 'DELETE FROM dlq WHERE queue = ?',
     insertCron: `
     INSERT OR REPLACE INTO cron_jobs
@@ -57,8 +59,8 @@ export const SQL_STATEMENTS = {
   `,
     updateCron: 'UPDATE cron_jobs SET executions = ?, next_run = ? WHERE name = ?',
     // Queue control-state persistence (#100): paused / rate-limit / concurrency.
-    upsertQueueState: 'INSERT OR REPLACE INTO queue_state (name, paused, rate_limit, concurrency_limit) VALUES (?, ?, ?, ?)',
-    loadQueueState: 'SELECT name, paused, rate_limit, concurrency_limit FROM queue_state',
+    upsertQueueState: 'INSERT OR REPLACE INTO queue_state (name, paused, rate_limit, concurrency_limit, rate_limit_duration, rate_limit_expires_at, stall_enabled, stall_interval, max_stalls, stall_grace_period) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    loadQueueState: 'SELECT name, paused, rate_limit, concurrency_limit, rate_limit_duration, rate_limit_expires_at, stall_enabled, stall_interval, max_stalls, stall_grace_period FROM queue_state',
     deleteQueueState: 'DELETE FROM queue_state WHERE name = ?',
 };
 /** Prepare all statements */

package/dist/infrastructure/scheduler/cronScheduler.d.ts

@@ -100,6 +100,11 @@ export declare class CronScheduler {
      */
     private tick;
     /** Fire a cron job with overlap and worker detection */
+    /**
+     * Reasons a due cron must not push right now. Evaluated BEFORE the
+     * executions increment in tick(), so skips never consume maxLimit budget.
+     */
+    private getSkipReason;
     private fireCronJob;
     /**
      * Get scheduler stats