bunqueue 2.8.35 → 2.8.36

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    rate_limit_duration INTEGER,\n    rate_limit_expires_at 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 = 16;
+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
 );
@@ -129,7 +130,11 @@ CREATE TABLE IF NOT EXISTS queue_state (
     rate_limit INTEGER,
     concurrency_limit INTEGER,
     rate_limit_duration INTEGER,
-    rate_limit_expires_at INTEGER
+    rate_limit_expires_at INTEGER,
+    stall_enabled INTEGER,
+    stall_interval INTEGER,
+    max_stalls INTEGER,
+    stall_grace_period INTEGER
 );
 `;
 /** Migration version table */
@@ -140,7 +145,7 @@ CREATE TABLE IF NOT EXISTS migrations (
 );
 `;
 /** Current schema version */
-export const SCHEMA_VERSION = 16;
+export const SCHEMA_VERSION = 21;
 /** All migrations in order */
 export const MIGRATIONS = {
     1: SCHEMA,
@@ -212,5 +217,23 @@ 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:
@@ -210,6 +219,7 @@ export declare class SqliteStorage {
         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<{
@@ -219,6 +229,7 @@ export declare class SqliteStorage {
         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:
@@ -654,7 +693,11 @@ export class SqliteStorage {
         this.safeWrite(() => {
             this.statements
                 .get('upsertQueueState')
-                .run(name, state.paused ? 1 : 0, state.rateLimit, state.concurrencyLimit, state.rateLimitDuration ?? null, state.rateLimitExpiresAt ?? null);
+                .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). */
@@ -667,6 +710,17 @@ export class SqliteStorage {
             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;
 }
@@ -69,4 +70,8 @@ export interface DbQueueState {
     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, rate_limit_duration, rate_limit_expires_at) VALUES (?, ?, ?, ?, ?, ?)',
-    loadQueueState: 'SELECT name, paused, rate_limit, concurrency_limit, rate_limit_duration, rate_limit_expires_at 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue",
-  "version": "2.8.35",
+  "version": "2.8.36",
   "description": "High-performance job queue for Bun & AI agents. SQLite persistence, cron scheduling, priorities, retries, DLQ, webhooks, native MCP server. Zero external infrastructure.",
   "type": "module",
   "main": "dist/main.js",
@@ -57,7 +57,9 @@
     "build": "bun build --compile --minify src/main.ts --outfile dist/bunqueue",
     "build:lib": "tsc -p tsconfig.build.json",
     "test": "BUNQUEUE_EMBEDDED=1 bun test",
+    "test:model": "BUNQUEUE_EMBEDDED=1 bun test test/model-based/queue-model.test.ts",
     "test:sandbox": "bun run scripts/test-sandbox.ts",
+    "test:sandbox:sdk": "bun run scripts/test-sdk-sandbox.ts",
     "bench": "bun run bench/throughput.ts && bun run bench/latency.ts",
     "bench:throughput": "bun run bench/throughput.ts",
     "bench:latency": "bun run bench/latency.ts",
@@ -82,6 +84,7 @@
     "@types/bun": "^1.3.9",
     "bullmq": "^5.79.3",
     "elysia": "^1.4.25",
+    "fast-check": "^4.9.0",
     "ioredis": "^5.11.1",
     "typescript": "^5.9.3",
     "zod": "^4.3.6"