bunqueue 2.8.35 → 2.8.36

package/README.md

@@ -830,8 +830,20 @@ full feature parity, so producers and workers can live anywhere in your stack:
 
 | Where your code runs | Install | Status |
 | -------------------- | ------- | ------ |
-| **Node.js ≥ 20, Deno ≥ 2, Bun, Cloudflare Workers** | [`npm install bunqueue-client`](https://www.npmjs.com/package/bunqueue-client) | 100/100 e2e per runtime + 16/16 inside workerd |
-| **Python ≥ 3.9** | PyPI coming soon — today: `pip install "git+https://github.com/egeominotti/bunqueue.git#subdirectory=sdk/python"` | 78/78 e2e |
+| **Node.js ≥ 20, Deno ≥ 2, Bun, Cloudflare Workers** | [`npm install bunqueue-client`](https://www.npmjs.com/package/bunqueue-client) | Native integration/e2e + protocol conformance |
+| **Python ≥ 3.9** | PyPI coming soon — today: `pip install "git+https://github.com/egeominotti/bunqueue.git#subdirectory=sdk/python"` | Native integration/e2e + protocol conformance |
+| **PHP ≥ 8.1** | Packagist coming soon — today: use [`sdk/php`](./sdk/php) | Native e2e + protocol conformance |
+| **Go 1.26.5** | `go get github.com/egeominotti/bunqueue/sdk/go` | Native tests + protocol conformance |
+| **Rust ≥ 1.85** | crates.io coming soon — today: use [`sdk/rust`](./sdk/rust) as a path dependency | Native unit/integration + protocol conformance |
+| **Elixir ≥ 1.15** | Hex coming soon — today: use [`sdk/elixir`](./sdk/elixir) as a path dependency | ExUnit integration + protocol conformance |
+
+All six SDKs run the same production hardening matrix: independent-connection
+idempotency and single-lease races, generated payload invariants,
+malformed-input fuzz corpora, broker SIGKILL/reconnect durability, bounded
+spikes, structured telemetry, and 17 shared protocol checks. Weekly CI adds
+runtime compatibility, live dependency advisories, native Go race/fuzz checks,
+and a 15-minute sustained profile per SDK. See
+[`docs/testing.md`](./docs/testing.md#sdk-hardening-matrix).
 
 ```typescript
 // Node.js / Deno / Cloudflare Workers

package/dist/application/backgroundTasks.js

@@ -144,6 +144,8 @@ function performDlqMaintenance(ctx) {
     const dlqCtx = {
         shards: ctx.shards,
         jobIndex: ctx.jobIndex,
+        jobResults: ctx.jobResults,
+        jobLogs: ctx.jobLogs,
         storage: ctx.storage,
     };
     for (const queueName of ctx.queueNamesCache) {
@@ -198,6 +200,15 @@ export function recover(ctx) {
     // Load DLQ job IDs so Phase 1 can skip stale active rows for DLQ'd jobs
     // (legacy DBs predate the DLQ-row cleanup fix in failJob).
     const dlqJobIds = ctx.storage.loadDlqJobIds();
+    const queueStates = ctx.storage.loadQueueState();
+    // Recovery bounds are needed before Phase 1 classifies interrupted active
+    // jobs. Restore the stall policy first; paused/limiter state can wait until
+    // the queues themselves have been rebuilt below.
+    for (const qs of queueStates) {
+        if (qs.stallConfig) {
+            ctx.shards[shardIndex(qs.name)].setStallConfig(qs.name, qs.stallConfig);
+        }
+    }
     const now = Date.now();
     // === PHASE 1: Recover active jobs (were processing when server stopped) ===
     // These jobs are considered "stalled" and need to be retried or moved to DLQ
@@ -240,12 +251,24 @@ export function recover(ctx) {
             job.attempts++;
             job.startedAt = null;
             job.lastHeartbeat = now;
-            // Check if exceeded max stalls
+            // A crash consumes one processing attempt and one stall allowance. Both
+            // bounds are terminal: requeueing after either reaches its configured
+            // maximum would make attempts/stalls unbounded across restart loops.
             const maxStalls = stallConfig.maxStalls ?? 3;
-            if (job.stallCount >= maxStalls) {
+            const attemptsExhausted = job.attempts >= job.maxAttempts;
+            const stallsExhausted = maxStalls > 0 && job.stallCount >= maxStalls;
+            if (attemptsExhausted || stallsExhausted) {
                 // Move to DLQ
-                const entry = shard.addToDlq(job, "stalled" /* FailureReason.Stalled */, `Job stalled ${job.stallCount} times (recovered at startup)`);
-                ctx.jobIndex.set(job.id, { type: 'dlq', queueName: job.queue });
+                const reason = attemptsExhausted
+                    ? "max_attempts_exceeded" /* FailureReason.MaxAttemptsExceeded */
+                    : "stalled" /* FailureReason.Stalled */;
+                const error = attemptsExhausted
+                    ? `Job reached max attempts (${job.maxAttempts}) during startup recovery`
+                    : `Job stalled ${job.stallCount} times (recovered at startup)`;
+                // Persist only here; the later loadDlq() phase is the single in-memory
+                // restore path. Adding to the shard now and restoring the same row below
+                // would duplicate the DLQ entry after every terminal crash recovery.
+                const entry = createDlqEntry(job, reason, error, shard.getDlqConfig(job.queue));
                 ctx.storage.saveDlqEntry(entry);
                 ctx.storage.deleteJob(job.id);
             }
@@ -338,7 +361,7 @@ export function recover(ctx) {
     // Map; without this load every queue silently un-pauses and loses its limits
     // on restart. Applied directly to the owning shard (in-memory only — these
     // setters do not re-persist, so there is no write-back loop).
-    for (const qs of ctx.storage.loadQueueState()) {
+    for (const qs of queueStates) {
         const shard = ctx.shards[shardIndex(qs.name)];
         if (qs.paused)
             shard.pause(qs.name);

package/dist/application/contextFactory.js

@@ -141,6 +141,8 @@ export class ContextFactory {
             processingShards: this.deps.processingShards,
             processingLocks: this.deps.processingLocks,
             jobIndex: this.deps.jobIndex,
+            jobLocks: this.deps.jobLocks,
+            clientJobs: this.deps.clientJobs,
             webhookManager: this.deps.webhookManager,
             eventsManager: this.deps.eventsManager,
             repeatChain: this.deps.repeatChain,
@@ -164,6 +166,8 @@ export class ContextFactory {
         return {
             shards: this.deps.shards,
             jobIndex: this.deps.jobIndex,
+            jobResults: this.deps.jobResults,
+            jobLogs: this.deps.jobLogs,
             storage: this.deps.storage,
         };
     }
@@ -171,6 +175,7 @@ export class ContextFactory {
         return {
             shards: this.deps.shards,
             jobIndex: this.deps.jobIndex,
+            jobLogs: this.deps.jobLogs,
             storage: this.deps.storage,
             completedJobs: this.deps.completedJobs,
             jobResults: this.deps.jobResults,

package/dist/application/dlqManager.d.ts

@@ -11,6 +11,12 @@ import type { SqliteStorage } from '../infrastructure/persistence/sqlite';
 export interface DlqContext {
     shards: Shard[];
     jobIndex: Map<JobId, JobLocation>;
+    jobResults: {
+        delete(id: JobId): boolean;
+    };
+    jobLogs: {
+        delete(id: JobId): boolean;
+    };
     storage: SqliteStorage | null;
 }
 /** Get jobs from DLQ (backward compatible) */

package/dist/application/dlqManager.js

@@ -209,24 +209,45 @@ export function processAutoRetry(queue, ctx) {
 export function purgeExpiredDlq(queue, ctx) {
     const idx = shardIndex(queue);
     const shard = ctx.shards[idx];
-    // Get expired entries before purging (to delete from SQLite)
-    const expiredEntries = shard.getExpiredEntries(queue);
-    const count = shard.purgeExpired(queue);
-    // Delete from SQLite
-    if (ctx.storage && expiredEntries.length > 0) {
-        for (const entry of expiredEntries) {
-            ctx.storage.deleteDlqEntry(entry.job.id);
-        }
-    }
-    return count;
+    const now = Date.now();
+    // Use one timestamp for the snapshot and mutation so every purged entry is
+    // represented in the cleanup set.
+    const expiredEntries = shard.getExpiredEntries(queue, now);
+    if (expiredEntries.length === 0)
+        return 0;
+    cleanupPurgedEntries(queue, expiredEntries, ctx, false);
+    shard.purgeExpired(queue, now);
+    return expiredEntries.length;
 }
 /** Purge all jobs from DLQ */
 export function purgeDlqJobs(queue, ctx) {
     const idx = shardIndex(queue);
-    const count = ctx.shards[idx].clearDlq(queue);
-    // Clear from SQLite
-    ctx.storage?.clearDlqQueue(queue);
-    return count;
+    const shard = ctx.shards[idx];
+    const entries = shard.getDlqEntries(queue);
+    cleanupPurgedEntries(queue, entries, ctx, true);
+    shard.clearDlq(queue);
+    return entries.length;
+}
+/** Remove every durable and global reference owned by terminal DLQ entries. */
+function cleanupPurgedEntries(queue, entries, ctx, clearQueue) {
+    const jobIds = [...new Set(entries.map((entry) => entry.job.id))];
+    const terminalJobIds = jobIds.filter((jobId) => {
+        const location = ctx.jobIndex.get(jobId);
+        return location === undefined || (location.type === 'dlq' && location.queueName === queue);
+    });
+    // One SQLite transaction removes DLQ rows, any orphan jobs/result rows, and
+    // pending buffered inserts before in-memory references become unobservable.
+    // A newer live generation can reuse the same custom id; its jobs row and
+    // auxiliary state must survive cleanup of the stale terminal generation.
+    ctx.storage?.purgeDlqEntries(queue, jobIds, terminalJobIds, clearQueue);
+    for (const jobId of terminalJobIds) {
+        const location = ctx.jobIndex.get(jobId);
+        if (location?.type === 'dlq' && location.queueName === queue) {
+            ctx.jobIndex.delete(jobId);
+        }
+        ctx.jobResults.delete(jobId);
+        ctx.jobLogs.delete(jobId);
+    }
 }
 /** Configure DLQ for a queue */
 export function configureDlq(queue, ctx, config) {

package/dist/application/lockManager.js

@@ -92,10 +92,20 @@ function processExpiredLockInner(jobId, lock, job, shardIdx, procIdx, ctx, now)
     job.startedAt = null;
     job.lastHeartbeat = now;
     job.stallCount++;
-    // Check if max stalls exceeded
+    // A lost lock consumes both retry budgets. Never requeue beyond either bound.
     const stallConfig = shard.getStallConfig(job.queue);
-    if (stallConfig.maxStalls > 0 && job.stallCount >= stallConfig.maxStalls) {
-        handleMaxStallsExceeded({ jobId, job, lock, shard, ctx, now });
+    const attemptsExhausted = job.attempts >= job.maxAttempts;
+    const stallsExhausted = stallConfig.maxStalls > 0 && job.stallCount >= stallConfig.maxStalls;
+    if (attemptsExhausted || stallsExhausted) {
+        handleRecoveryBoundExceeded({
+            jobId,
+            job,
+            lock,
+            shard,
+            ctx,
+            now,
+            attemptsExhausted,
+        });
     }
     else {
         requeueExpiredJob({ jobId, job, lock, queue, idx: shardIdx, ctx, now });
@@ -108,14 +118,16 @@ function processExpiredLockInner(jobId, lock, job, shardIdx, procIdx, ctx, now)
         renewalCount: lock.renewalCount,
     });
 }
-/** Move job to DLQ when max stalls exceeded */
-function handleMaxStallsExceeded(opts) {
-    const { jobId, job, lock, shard, ctx, now } = opts;
+/** Move job to DLQ when either crash-recovery budget is exhausted. */
+function handleRecoveryBoundExceeded(opts) {
+    const { jobId, job, lock, shard, ctx, now, attemptsExhausted } = opts;
     // Release the concurrency slot (+group+uniqueKey) acquired at pull before
     // moving to DLQ — otherwise the slot leaks (mirrors
     // stallDetection.moveStalliedJobToDlq).
     shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId);
-    const entry = shard.addToDlq(job, "stalled" /* FailureReason.Stalled */, `Lock expired after ${lock.renewalCount} renewals`);
+    const entry = shard.addToDlq(job, attemptsExhausted ? "max_attempts_exceeded" /* FailureReason.MaxAttemptsExceeded */ : "stalled" /* FailureReason.Stalled */, attemptsExhausted
+        ? `Lock expired at max attempts (${job.maxAttempts})`
+        : `Lock expired after ${lock.renewalCount} renewals`);
     ctx.jobIndex.set(jobId, { type: 'dlq', queueName: job.queue });
     // Persist the DLQ move like the sibling paths (ack.moveFailedJobToDlq,
     // stallDetection.moveStalliedJobToDlq, backgroundTasks startup-recovery).
@@ -129,7 +141,9 @@ function handleMaxStallsExceeded(opts) {
         jobId,
         queue: job.queue,
         timestamp: now,
-        error: 'Lock expired (max stalls reached)',
+        error: attemptsExhausted
+            ? 'Lock expired (max attempts reached)'
+            : 'Lock expired (max stalls reached)',
     });
 }
 /** Requeue job for retry */

package/dist/application/operations/customId.d.ts

@@ -0,0 +1,31 @@
+import type { Shard } from '../../domain/queue/shard';
+import { type Job, type JobId, type JobInput } from '../../domain/types/job';
+import type { JobLocation } from '../../domain/types/queue';
+import type { SqliteStorage } from '../../infrastructure/persistence/sqlite';
+import type { MapLike, SetLike } from '../../shared/lru';
+export interface CustomIdContext {
+    storage: SqliteStorage | null;
+    shards: Shard[];
+    completedJobs: SetLike<JobId>;
+    completedJobsData: MapLike<JobId, Job>;
+    timedOutJobs?: SetLike<JobId>;
+    jobResults: MapLike<JobId, unknown>;
+    customIdMap: MapLike<string, JobId>;
+    jobIndex: Map<JobId, JobLocation>;
+}
+export type CustomIdResult = {
+    skip: true;
+    existingJob: Job;
+} | {
+    skip: true;
+    existingId: JobId;
+} | {
+    skip: false;
+    id: JobId;
+};
+/**
+ * Enforce custom-ID idempotency while the caller holds the target shard lock.
+ * Live generations are returned unchanged; terminal generations are retired
+ * before the deterministic ID is admitted again.
+ */
+export declare function handleCustomId(input: JobInput, ctx: CustomIdContext, lockedShardIndexes: ReadonlySet<number>): CustomIdResult;

package/dist/application/operations/customId.js

@@ -0,0 +1,59 @@
+import { generateJobId, jobId } from '../../domain/types/job';
+import { shardIndex } from '../../shared/hash';
+/**
+ * Enforce custom-ID idempotency while the caller holds the target shard lock.
+ * Live generations are returned unchanged; terminal generations are retired
+ * before the deterministic ID is admitted again.
+ */
+export function handleCustomId(input, ctx, lockedShardIndexes) {
+    if (!input.customId) {
+        return { skip: false, id: generateJobId() };
+    }
+    const id = jobId(input.customId);
+    const existing = ctx.customIdMap.get(input.customId);
+    if (existing && !ctx.completedJobs.has(id)) {
+        const location = ctx.jobIndex.get(existing);
+        if (location?.type === 'queue') {
+            if (!lockedShardIndexes.has(location.shardIdx)) {
+                throw new Error('Live custom ID shard must be locked before lookup');
+            }
+            const existingShard = ctx.shards[location.shardIdx];
+            const existingJob = existingShard.getQueue(location.queueName).find(existing);
+            if (existingJob) {
+                return { skip: true, existingJob };
+            }
+            if (existingShard.waitingDeps.has(existing)) {
+                return { skip: true, existingId: id };
+            }
+        }
+        else if (location?.type === 'processing') {
+            return { skip: true, existingId: id };
+        }
+    }
+    if (ctx.completedJobs.has(id)) {
+        ctx.completedJobs.delete(id);
+        ctx.completedJobsData.delete(id);
+        ctx.jobResults.delete(id);
+        ctx.jobIndex.delete(id);
+        ctx.storage?.deleteJob(id);
+    }
+    const terminalLocation = ctx.jobIndex.get(id);
+    if (terminalLocation?.type === 'dlq') {
+        const terminalShardIdx = shardIndex(terminalLocation.queueName);
+        if (!lockedShardIndexes.has(terminalShardIdx)) {
+            throw new Error('Terminal custom ID shard must be locked before reuse');
+        }
+        const terminalShard = ctx.shards[terminalShardIdx];
+        terminalShard.removeFromDlq(terminalLocation.queueName, id);
+        ctx.jobIndex.delete(id);
+        // deleteDlqEntry removes every persisted generation for this deterministic
+        // id. The fresh jobs row is inserted only after this retirement completes.
+        ctx.storage?.deleteDlqEntry(id);
+    }
+    // A durable jobs row may outlive its in-memory tracking after an interrupted
+    // cleanup. The storage insert upserts that orphan without adding a DELETE to
+    // every custom-ID push.
+    ctx.timedOutJobs?.delete(id);
+    ctx.customIdMap.set(input.customId, id);
+    return { skip: false, id };
+}

package/dist/application/operations/jobClaim.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Cleanup shared ownership state when a management operation claims an active
+ * job before its worker can ACK or FAIL it.
+ */
+import type { JobId, JobLock } from '../../domain/types/job';
+export interface JobClaimContext {
+    jobLocks: Map<JobId, JobLock>;
+    clientJobs: Map<string, Set<JobId>>;
+}
+/**
+ * Release the live lease and detach the job from its TCP client owner.
+ *
+ * Map/Set deletion is intentionally idempotent: management commands can race
+ * with disconnect cleanup, but ownership must be removed exactly once from the
+ * observable state.
+ */
+export declare function releaseClaimedJobOwnership(jobId: JobId, ctx: JobClaimContext): void;

package/dist/application/operations/jobClaim.js

@@ -0,0 +1,20 @@
+/**
+ * Cleanup shared ownership state when a management operation claims an active
+ * job before its worker can ACK or FAIL it.
+ */
+/**
+ * Release the live lease and detach the job from its TCP client owner.
+ *
+ * Map/Set deletion is intentionally idempotent: management commands can race
+ * with disconnect cleanup, but ownership must be removed exactly once from the
+ * observable state.
+ */
+export function releaseClaimedJobOwnership(jobId, ctx) {
+    ctx.jobLocks.delete(jobId);
+    for (const [clientId, jobs] of ctx.clientJobs) {
+        if (!jobs.delete(jobId))
+            continue;
+        if (jobs.size === 0)
+            ctx.clientJobs.delete(clientId);
+    }
+}

package/dist/application/operations/jobManagement.d.ts

@@ -2,13 +2,14 @@
  * Job Management Operations
  * Cancel, update progress, change priority, promote, move to delayed, discard
  */
-import type { Job, JobId } from '../../domain/types/job';
+import type { Job, JobId, JobLock } from '../../domain/types/job';
 import { type JobLocation } from '../../domain/types/queue';
 import type { Shard } from '../../domain/queue/shard';
 import type { SqliteStorage } from '../../infrastructure/persistence/sqlite';
 import type { WebhookManager } from '../webhookManager';
 import type { EventsManager } from '../eventsManager';
 import { type RWLock } from '../../shared/lock';
+export { discardJob, moveJobToDelayed } from './jobMoveOperations';
 /** Context for job management operations */
 export interface JobManagementContext {
     storage: SqliteStorage | null;
@@ -17,6 +18,8 @@ export interface JobManagementContext {
     processingShards: Map<JobId, Job>[];
     processingLocks: RWLock[];
     jobIndex: Map<JobId, JobLocation>;
+    jobLocks: Map<JobId, JobLock>;
+    clientJobs: Map<string, Set<JobId>>;
     webhookManager: WebhookManager;
     eventsManager: EventsManager;
     repeatChain?: Map<JobId, JobId>;
@@ -29,7 +32,3 @@ export declare function updateJobProgress(jobId: JobId, progress: number, ctx: J
 export declare function updateJobData(jobId: JobId, data: unknown, ctx: JobManagementContext): Promise<boolean>;
 /** Change job priority */
 export declare function changeJobPriority(jobId: JobId, priority: number, ctx: JobManagementContext, lifo?: boolean): Promise<boolean>;
-/** Move active job back to delayed */
-export declare function moveJobToDelayed(jobId: JobId, delay: number, ctx: JobManagementContext): Promise<boolean>;
-/** Discard job to DLQ */
-export declare function discardJob(jobId: JobId, ctx: JobManagementContext): Promise<boolean>;

package/dist/application/operations/jobManagement.js

@@ -2,9 +2,10 @@
  * Job Management Operations
  * Cancel, update progress, change priority, promote, move to delayed, discard
  */
-import { shardIndex, processingShardIndex } from '../../shared/hash';
+import { processingShardIndex } from '../../shared/hash';
 import { webhookLog } from '../../shared/logger';
 import { withWriteLock } from '../../shared/lock';
+export { discardJob, moveJobToDelayed } from './jobMoveOperations';
 /** Cancel a job (remove from queue) */
 export async function cancelJob(jobId, ctx) {
     const location = ctx.jobIndex.get(jobId);
@@ -108,6 +109,7 @@ export async function updateJobData(jobId, data, ctx) {
             const job = shard.getQueue(location.queueName).find(jobId) ?? shard.waitingDeps.get(jobId);
             if (job) {
                 job.data = data;
+                ctx.storage?.updateJobData(jobId, data);
                 return true;
             }
             return false;
@@ -119,6 +121,7 @@ export async function updateJobData(jobId, data, ctx) {
             const job = ctx.processingShards[procIdx].get(jobId);
             if (job) {
                 job.data = data;
+                ctx.storage?.updateJobData(jobId, data);
                 return true;
             }
             return false;
@@ -147,6 +150,7 @@ async function updateRepeatSuccessor(originalId, data, ctx) {
             .find(successorId);
         if (job) {
             job.data = data;
+            ctx.storage?.updateJobData(successorId, data);
             return true;
         }
         return false;
@@ -159,120 +163,15 @@ export async function changeJobPriority(jobId, priority, ctx, lifo) {
         return false;
     return withWriteLock(ctx.shardLocks[location.shardIdx], () => {
         const q = ctx.shards[location.shardIdx].getQueue(location.queueName);
-        return q.updatePriority(jobId, priority, lifo);
-    });
-}
-/** Move active job back to delayed */
-export async function moveJobToDelayed(jobId, delay, ctx) {
-    const location = ctx.jobIndex.get(jobId);
-    if (location?.type !== 'processing')
-        return false;
-    const procIdx = processingShardIndex(jobId);
-    // First remove from processing with lock
-    const job = await withWriteLock(ctx.processingLocks[procIdx], () => {
-        const job = ctx.processingShards[procIdx].get(jobId);
-        if (job) {
-            ctx.processingShards[procIdx].delete(jobId);
-        }
-        return job;
-    });
-    if (!job)
-        return false;
-    // Then add back to queue with lock
-    const now = Date.now();
-    job.runAt = now + delay;
-    job.startedAt = null;
-    const idx = shardIndex(job.queue);
-    const queueName = job.queue;
-    await withWriteLock(ctx.shardLocks[idx], () => {
-        const shard = ctx.shards[idx];
-        // Release the concurrency slot (+group+uniqueKey) acquired at pull before
-        // re-queueing, mirroring moveActiveToWait (jobStateTransitions.ts) --
-        // otherwise the slot leaks and setConcurrency(N) wedges after N moves.
-        // Dropping the uniqueKey reservation on requeue matches the sibling
-        // requeue paths (failJob retry, moveActiveToWait, requeueExpiredJob).
-        shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId);
-        shard.getQueue(job.queue).push(job);
-        // Update running counters for O(1) stats and temporal index (job is delayed since delay > 0)
-        const isDelayed = job.runAt > now;
-        shard.incrementQueued(jobId, isDelayed, job.createdAt, job.queue, job.runAt);
-        ctx.jobIndex.set(jobId, { type: 'queue', shardIdx: idx, queueName: job.queue });
-        // The freed slot may unblock waiting jobs for long-pollers.
-        shard.notify(job.queue);
-    });
-    // Persist the move so the delay survives a restart: the on-disk row was
-    // `state='active'` with the old run_at, which recovery would otherwise treat as a
-    // stalled active job. updateRunAt re-derives 'delayed' from the future run_at and
-    // clears started_at.
-    ctx.storage?.updateRunAt(jobId, job.runAt);
-    // Emit delayed event (BullMQ v5)
-    ctx.eventsManager.broadcast({
-        eventType: "delayed" /* EventType.Delayed */,
-        jobId,
-        queue: queueName,
-        timestamp: Date.now(),
-        delay,
-    });
-    return true;
-}
-/** Discard job to DLQ */
-export async function discardJob(jobId, ctx) {
-    const location = ctx.jobIndex.get(jobId);
-    if (!location)
-        return false;
-    let job = null;
-    if (location.type === 'queue') {
-        job = await withWriteLock(ctx.shardLocks[location.shardIdx], () => {
-            const shard = ctx.shards[location.shardIdx];
-            const removed = shard.getQueue(location.queueName).remove(jobId);
-            if (removed) {
-                // Update running counters for O(1) stats
-                shard.decrementQueued(jobId);
-            }
-            return removed;
-        });
-    }
-    else if (location.type === 'processing') {
-        const procIdx = processingShardIndex(jobId);
-        job = await withWriteLock(ctx.processingLocks[procIdx], () => {
-            const j = ctx.processingShards[procIdx].get(jobId) ?? null;
-            if (j)
-                ctx.processingShards[procIdx].delete(jobId);
-            return j;
-        });
-    }
-    if (job) {
-        const validJob = job; // Local reference for closure
-        const idx = shardIndex(validJob.queue);
-        const fromProcessing = location.type === 'processing';
-        const entry = await withWriteLock(ctx.shardLocks[idx], () => {
-            const shard = ctx.shards[idx];
-            if (fromProcessing) {
-                // The pull that activated this job acquired a concurrency slot (and
-                // possibly a FIFO group); return them before the DLQ move or the slot
-                // leaks and setConcurrency(N) wedges after N discards. The uniqueKey
-                // is freed too: every sibling terminal DLQ path releases the full
-                // reservation on entry (failJob, ack.ts; handleMaxStallsExceeded,
-                // lockManager.ts), so the DLQ entry never keeps it.
-                shard.releaseJobResources(validJob.queue, validJob.uniqueKey, validJob.groupId);
-                // The freed slot may unblock waiting jobs for long-pollers.
-                shard.notify(validJob.queue);
-            }
-            else if (validJob.uniqueKey) {
-                // Queue branch: the waiting job never acquired a slot or group at
-                // pull, so a full releaseJobResources would free a slot legitimately
-                // held by ANOTHER active job. Release only the uniqueKey reservation,
-                // matching cancelJob and the DLQ-entry semantics above.
-                shard.releaseUniqueKey(validJob.queue, validJob.uniqueKey);
-            }
-            // addToDlq already updates dlq counter and returns entry
-            const dlqEntry = shard.addToDlq(validJob);
-            ctx.jobIndex.set(jobId, { type: 'dlq', queueName: validJob.queue });
-            return dlqEntry;
-        });
-        ctx.storage?.saveDlqEntry(entry);
-        ctx.storage?.deleteJob(jobId);
+        if (!q.updatePriority(jobId, priority, lifo))
+            return false;
+        // updatePriority replaces the immutable Job held by the indexed heap.
+        // Persist the effective LIFO value from that replacement so an omitted
+        // optional argument preserves the existing tie-break across recovery.
+        const updatedJob = q.find(jobId);
+        if (!updatedJob)
+            return false;
+        ctx.storage?.updateJobPriority(jobId, updatedJob.priority, updatedJob.lifo);
         return true;
-    }
-    return false;
+    });
 }

package/dist/application/operations/jobMoveOperations.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Job move operations that claim active jobs for delayed or DLQ state.
+ */
+import type { JobId } from '../../domain/types/job';
+import type { JobManagementContext } from './jobManagement';
+/** Move active job back to delayed. */
+export declare function moveJobToDelayed(jobId: JobId, delay: number, ctx: JobManagementContext): Promise<boolean>;
+/** Discard a waiting or active job to the DLQ. */
+export declare function discardJob(jobId: JobId, ctx: JobManagementContext): Promise<boolean>;