bunqueue 2.8.60 → 2.9.2

package/dist/application/postgres-queue-manager/state.js

@@ -0,0 +1,273 @@
+import { PostgresQueueStore, } from '../../infrastructure/persistence/postgres';
+import { QueueManager } from '../queueManager';
+import { stopBackgroundTasks } from '../backgroundTasks';
+import { PostgresDeferredWriteQueue, throwDeferredWriteErrors } from './deferredWrites';
+import { applyPostgresEventMetrics, hydratePostgresLifetimeMetrics, postgresEventType, } from './lifetimeMetrics';
+import { PostgresQueueSnapshot } from './snapshot';
+import { PostgresStartupEventBuffer } from './startupEventBuffer';
+import { PostgresOperationGate } from './operationGate';
+import { applyPostgresJobProjection, PostgresProjectionRefreshes } from './projectionRefreshes';
+export class PostgresQueueManagerState extends QueueManager {
+    postgresStore;
+    postgresSnapshot;
+    activeTokens = new Map();
+    postgresReady;
+    refreshes = new Map();
+    dirtyQueues = new Set();
+    queueEventVersions = new Map();
+    snapshotEventBuffer = new PostgresStartupEventBuffer();
+    terminalMetricBaselineCommitSeq = 0;
+    unsubscribeEvent;
+    unsubscribeInvalidation;
+    writes = new PostgresDeferredWriteQueue();
+    operations;
+    projectionRefreshes;
+    shutdownPromise = null;
+    shutdownComplete = false;
+    baseStopped = false;
+    stopQueueRefreshes = false;
+    constructor(config) {
+        const { postgres, ...baseConfig } = config;
+        super(baseConfig);
+        if (this.backgroundTaskHandles)
+            stopBackgroundTasks(this.backgroundTaskHandles);
+        this.postgresSnapshot = new PostgresQueueSnapshot(this.config.maxCompletedJobs, this.config.maxJobResults);
+        this.postgresStore = new PostgresQueueStore({
+            ...postgres,
+            maxQueueEvents: this.config.maxQueueEvents,
+            maxMetricDataPoints: this.config.maxMetricDataPoints,
+            maxCompletedJobs: this.config.maxCompletedJobs,
+            maxJobResults: this.config.maxJobResults,
+        });
+        this.operations = new PostgresOperationGate(this.postgresStore.config.maxConcurrentOperations, this.postgresStore.config.maxQueuedOperations);
+        this.projectionRefreshes = new PostgresProjectionRefreshes((requests) => this.postgresStore.loadJobProjections(requests), (id, projection) => applyPostgresJobProjection(this.postgresSnapshot, this.activeTokens, id, projection), (queue, id, error) => this.postgresStore.reportProjectionRefresh(queue, id, error), this.postgresStore.config.pollIntervalMs);
+        this.unsubscribeEvent = this.postgresStore.onEvent((event) => this.onStoreEvent(event));
+        this.unsubscribeInvalidation = this.postgresStore.onInvalidation((queue) => {
+            this.scheduleQueueRefresh(queue);
+        });
+        this.postgresReady = this.initializePostgres();
+    }
+    async waitUntilReady() {
+        await this.postgresReady;
+    }
+    async flushPostgresWrites() {
+        await this.postgresReady;
+        await this.writes.flush();
+    }
+    async shutdownPostgres() {
+        if (this.shutdownComplete)
+            return;
+        if (!this.shutdownPromise) {
+            const attempt = this.performPostgresShutdown()
+                .then(() => {
+                this.shutdownComplete = true;
+            })
+                .finally(() => {
+                if (this.shutdownPromise === attempt && !this.shutdownComplete) {
+                    this.shutdownPromise = null;
+                }
+            });
+            this.shutdownPromise = attempt;
+        }
+        await this.shutdownPromise;
+    }
+    shutdown() {
+        void this.shutdownPostgres().catch(() => undefined);
+    }
+    async performPostgresShutdown() {
+        this.stopQueueRefreshes = true;
+        this.dirtyQueues.clear();
+        this.projectionRefreshes.close();
+        const operationDrain = this.operations.closeAndDrain();
+        await operationDrain;
+        this.stopBaseRuntime();
+        this.unsubscribeEvent();
+        this.unsubscribeInvalidation();
+        const errors = await this.writes.closeAndDrain();
+        try {
+            await this.postgresReady;
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        await Promise.allSettled([...this.refreshes.values(), this.projectionRefreshes.drain()]);
+        try {
+            await this.postgresStore.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        throwDeferredWriteErrors(errors, 'PostgreSQL shutdown failed');
+    }
+    tokenFor(id, token) {
+        return token ?? this.activeTokens.get(id) ?? this.postgresSnapshot.get(id)?.token ?? null;
+    }
+    forgetToken(id) {
+        this.activeTokens.delete(id);
+    }
+    runPostgresOperation(operation) {
+        return this.operations.run(operation);
+    }
+    async refreshJob(id, queue) {
+        const targetQueue = queue ?? this.postgresSnapshot.get(id)?.job.queue ?? '';
+        try {
+            await this.projectionRefreshes.refreshNow(id, targetQueue);
+        }
+        catch {
+            this.projectionRefreshes.request(id, targetQueue);
+        }
+    }
+    async fetchPostgresJob(id) {
+        const queue = this.postgresSnapshot.get(id)?.job.queue ?? '';
+        return (await this.projectionRefreshes.refreshNow(id, queue)).row;
+    }
+    async refreshJobs(ids, queue) {
+        const requests = [...new Set(ids)].map((id) => ({
+            id,
+            queue: queue ?? this.postgresSnapshot.get(id)?.job.queue ?? '',
+        }));
+        try {
+            await this.projectionRefreshes.refreshManyNow(requests);
+        }
+        catch {
+            for (const request of requests)
+                this.projectionRefreshes.request(request.id, request.queue);
+        }
+    }
+    async refreshQueue(queue) {
+        const eventVersion = this.queueEventVersions.get(queue) ?? 0;
+        const { rows, state, exists, results } = await this.postgresStore.loadQueueReadModel(queue);
+        if (eventVersion !== (this.queueEventVersions.get(queue) ?? 0)) {
+            this.dirtyQueues.add(queue);
+            return false;
+        }
+        this.projectionRefreshes.supersedeQueue(queue);
+        if (!exists) {
+            for (const id of this.postgresSnapshot.removeQueue(queue))
+                this.activeTokens.delete(id);
+            return true;
+        }
+        this.postgresSnapshot.replaceQueue(queue, rows, state, results);
+        return true;
+    }
+    async refreshQueueAfterCommit(queue) {
+        try {
+            if (!(await this.refreshQueue(queue)))
+                this.scheduleQueueRefresh(queue);
+            else
+                this.postgresStore.reportQueueRefresh(queue, null);
+        }
+        catch (error) {
+            this.postgresStore.reportQueueRefresh(queue, error);
+            this.scheduleQueueRefresh(queue);
+        }
+    }
+    enqueueWrite(operation) {
+        this.writes.enqueue(operation);
+    }
+    async initializePostgres() {
+        await this.postgresStore.initialize();
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const buffer = this.snapshotEventBuffer;
+            if (!buffer)
+                return;
+            buffer.reset();
+            const { rows, results, crons, states } = await this.postgresStore.loadManagerSnapshot();
+            const events = buffer.take();
+            if (!events && attempt === 0)
+                continue;
+            this.postgresSnapshot.hydrate(rows);
+            this.postgresSnapshot.hydrateResults(results);
+            this.cronScheduler.load([...crons]);
+            for (const state of states)
+                this.postgresSnapshot.setQueueState(state);
+            for (const event of events ?? []) {
+                this.postgresSnapshot.apply(event);
+                applyPostgresEventMetrics(this.metrics, this.perQueueMetrics, event, false);
+            }
+            await this.postgresStore.finalizeLifetimeMetrics((lifetimeMetrics) => {
+                hydratePostgresLifetimeMetrics(this.metrics, this.perQueueMetrics, lifetimeMetrics);
+                this.terminalMetricBaselineCommitSeq = lifetimeMetrics.baselineCommitSeq;
+                this.snapshotEventBuffer = null;
+                this.projectionRefreshes.start();
+            });
+            return;
+        }
+    }
+    scheduleQueueRefresh(queue) {
+        if (this.stopQueueRefreshes)
+            return;
+        this.dirtyQueues.add(queue);
+        if (this.refreshes.has(queue))
+            return;
+        const refresh = this.postgresReady
+            .then(() => this.refreshDirtyQueue(queue))
+            .catch(() => {
+            this.dirtyQueues.delete(queue);
+        })
+            .finally(() => {
+            this.refreshes.delete(queue);
+            if (this.dirtyQueues.has(queue))
+                this.scheduleQueueRefresh(queue);
+        });
+        this.refreshes.set(queue, refresh);
+    }
+    async refreshDirtyQueue(queue) {
+        let retryDelay = this.postgresStore.config.pollIntervalMs;
+        while (!this.stopQueueRefreshes && this.dirtyQueues.delete(queue)) {
+            try {
+                const applied = await this.refreshQueue(queue);
+                if (!applied && !this.stopQueueRefreshes) {
+                    await Bun.sleep(this.postgresStore.config.pollIntervalMs);
+                }
+                this.postgresStore.reportQueueRefresh(queue, null);
+                retryDelay = this.postgresStore.config.pollIntervalMs;
+            }
+            catch (error) {
+                this.postgresStore.reportQueueRefresh(queue, error);
+                if (this.stopQueueRefreshes)
+                    return;
+                this.dirtyQueues.add(queue);
+                await Bun.sleep(retryDelay);
+                retryDelay = Math.min(retryDelay * 2, 1_000);
+            }
+        }
+    }
+    onStoreEvent(event) {
+        this.queueEventVersions.set(event.queue, (this.queueEventVersions.get(event.queue) ?? 0) + 1);
+        const startupBuffer = this.snapshotEventBuffer;
+        startupBuffer?.capture(event);
+        if (startupBuffer)
+            this.postgresSnapshot.apply(event);
+        if (startupBuffer?.overflowed)
+            this.scheduleQueueRefresh(event.queue);
+        else
+            this.projectionRefreshes.request(event.jobId, event.queue);
+        const mapped = postgresEventType(event.type);
+        if (!mapped)
+            return;
+        if (!startupBuffer) {
+            applyPostgresEventMetrics(this.metrics, this.perQueueMetrics, event, event.commitSeq > this.terminalMetricBaselineCommitSeq);
+        }
+        this.eventsManager.broadcast({
+            eventType: mapped,
+            queue: event.queue,
+            jobId: event.jobId,
+            timestamp: event.occurredAt,
+            ...(Object.hasOwn(event, 'result') && { data: event.result }),
+            ...(event.error !== undefined && { error: event.error }),
+            ...(mapped === 'failed' && { terminal: event.state === 'failed' }),
+        });
+    }
+    applyPostgresClaim(claim) {
+        this.projectionRefreshes.supersede(claim.job.id);
+        this.activeTokens.set(claim.job.id, claim.token);
+        this.postgresSnapshot.claim(claim);
+    }
+    stopBaseRuntime() {
+        if (this.baseStopped)
+            return;
+        this.baseStopped = true;
+        super.shutdown();
+    }
+}

package/dist/application/postgres-queue-manager/terminalDelivery.d.ts

@@ -0,0 +1,20 @@
+import { FailureReason } from '../../domain/types/dlq';
+import type { JobId } from '../../domain/types/job';
+import type { AckBatchOutcome, AckOutcome, CompletionOptions } from '../types/ack';
+import { PostgresQueueManagerQueries } from './queries';
+/** Terminal delivery transitions drained before the PostgreSQL pool closes. */
+export declare class PostgresQueueManagerTerminalDelivery extends PostgresQueueManagerQueries {
+    ack(id: JobId, result?: unknown, token?: string, options?: CompletionOptions): Promise<AckOutcome>;
+    ackBatch(ids: JobId[], tokens?: string[]): Promise<AckBatchOutcome>;
+    ackBatchWithResults(items: Array<{
+        id: JobId;
+        result: unknown;
+        token?: string;
+    } & CompletionOptions>): Promise<AckBatchOutcome>;
+    fail(id: JobId, error?: string, token?: string, unrecoverable?: boolean, stack?: string[], removeOnFail?: boolean): Promise<AckOutcome>;
+    failWithReason(id: JobId, error: string | undefined, reason: FailureReason): Promise<AckOutcome>;
+    private requireToken;
+    private ackPostgres;
+    private completeBatch;
+    private failPostgres;
+}

package/dist/application/postgres-queue-manager/terminalDelivery.js

@@ -0,0 +1,100 @@
+import { applyPostgresBatchCompletion } from './batchSnapshot';
+import { PostgresQueueManagerQueries } from './queries';
+/** Terminal delivery transitions drained before the PostgreSQL pool closes. */
+export class PostgresQueueManagerTerminalDelivery extends PostgresQueueManagerQueries {
+    async ack(id, result, token, options = {}) {
+        return await this.runPostgresOperation(() => this.ackPostgres(id, result, token, options));
+    }
+    async ackBatch(ids, tokens) {
+        return await this.runPostgresOperation(() => this.completeBatch(ids.map((id, index) => ({ id, token: tokens?.[index] }))));
+    }
+    async ackBatchWithResults(items) {
+        return await this.runPostgresOperation(() => this.completeBatch(items));
+    }
+    // oxlint-disable-next-line max-params -- public compatibility signature carries failure policy
+    async fail(id, error, token, unrecoverable = false, stack, removeOnFail) {
+        return await this.runPostgresOperation(() => this.failPostgres(id, error, token, { unrecoverable, stack, removeOnFail }));
+    }
+    async failWithReason(id, error, reason) {
+        return await this.runPostgresOperation(() => this.failPostgres(id, error, undefined, {
+            unrecoverable: reason === "timeout" /* FailureReason.Timeout */,
+            failureReason: reason,
+        }));
+    }
+    requireToken(id, supplied) {
+        const token = this.tokenFor(id, supplied);
+        if (!token)
+            throw new Error(`Lock token required for job ${String(id)}`);
+        return token;
+    }
+    async ackPostgres(id, result, token, options) {
+        await this.postgresReady;
+        const transition = await this.postgresStore.complete(id, this.requireToken(id, token), result, options.removeOnComplete);
+        this.forgetToken(id);
+        await this.refreshJob(id);
+        if (transition.applied)
+            return;
+        if (transition.alreadyFinalized)
+            return { applied: false, reason: 'already-finalized' };
+        throw new Error(`Invalid or expired lock token for job ${String(id)}`);
+    }
+    async completeBatch(items) {
+        if (items.length === 0)
+            return;
+        if (new Set(items.map((item) => String(item.id))).size === items.length) {
+            await this.postgresReady;
+            const transitions = await this.postgresStore.completeMany(items.map((item) => ({
+                id: item.id,
+                token: this.requireToken(item.id, item.token),
+                result: item.result,
+                removeOnComplete: item.removeOnComplete,
+            })));
+            const repeatQueues = new Set();
+            const ignoredIds = [];
+            const ignoredIndices = [];
+            for (let index = 0; index < transitions.length; index++) {
+                const transition = transitions[index];
+                this.forgetToken(items[index].id);
+                const repeatQueue = applyPostgresBatchCompletion(this.postgresSnapshot, items[index], transition);
+                if (repeatQueue)
+                    repeatQueues.add(repeatQueue);
+                if (!transition.applied) {
+                    ignoredIndices.push(index);
+                    ignoredIds.push(items[index].id);
+                }
+            }
+            await Promise.all([
+                ...ignoredIds.map((id) => this.refreshJob(id)),
+                ...[...repeatQueues].map((queue) => this.refreshQueueAfterCommit(queue)),
+            ]);
+            return ignoredIndices.length === 0
+                ? undefined
+                : { ignoredIndices, ignoredIds: ignoredIndices.map((index) => items[index].id) };
+        }
+        const ignoredIndices = [];
+        for (let index = 0; index < items.length; index++) {
+            const outcome = await this.ackPostgres(items[index].id, items[index].result, items[index].token, items[index]);
+            if (outcome)
+                ignoredIndices.push(index);
+        }
+        return ignoredIndices.length === 0
+            ? undefined
+            : { ignoredIndices, ignoredIds: ignoredIndices.map((index) => items[index].id) };
+    }
+    async failPostgres(id, error, token, options) {
+        await this.postgresReady;
+        const transition = await this.postgresStore.fail({
+            id,
+            token: this.requireToken(id, token),
+            error,
+            ...options,
+        });
+        this.forgetToken(id);
+        await this.refreshJob(id);
+        if (transition.applied)
+            return;
+        if (transition.alreadyFinalized)
+            return { applied: false, reason: 'already-finalized' };
+        throw new Error(`Invalid or expired lock token for job ${String(id)}`);
+    }
+}

package/dist/application/postgresQueueManager.d.ts

@@ -0,0 +1,2 @@
+export { PostgresQueueManagerOperations as PostgresQueueManager } from './postgres-queue-manager/operations';
+export type { PostgresQueueManagerConfig } from './postgres-queue-manager/config';

package/dist/application/postgresQueueManager.js

@@ -0,0 +1 @@
+export { PostgresQueueManagerOperations as PostgresQueueManager } from './postgres-queue-manager/operations';

package/dist/application/queue-manager/control.js

@@ -95,6 +95,7 @@ export class QueueManagerControl extends QueueManagerQueries {
         this.perQueueMetrics.delete(queue);
         this.telemetryJournal.clearQueue(queue);
         this.storage?.deleteQueueState(queue);
+        this.storage?.deleteGroupState(queue);
     }
     listQueues() {
         return Array.from(this.queueNamesCache);

package/dist/application/queue-manager/delivery.d.ts

@@ -1,17 +1,18 @@
 import type { Job, JobId, JobInput, JobLock } from '../../domain/types/job';
 import type { AtomicFlowBatchInput, AtomicFlowBatchResult } from '../../domain/types/flow';
+import type { GroupPullOptions } from '../../domain/types/group';
 import { QueueManagerState } from './state';
 export declare class QueueManagerDelivery extends QueueManagerState {
     push(queue: string, input: JobInput): Promise<Job>;
     pushBatch(queue: string, inputs: JobInput[]): Promise<JobId[]>;
     pushFlow(batch: AtomicFlowBatchInput): Promise<AtomicFlowBatchResult>;
-    pull(queue: string, timeoutMs?: number, signal?: AbortSignal): Promise<Job | null>;
-    pullWithLock(queue: string, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal): Promise<{
+    pull(queue: string, timeoutMs?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<Job | null>;
+    pullWithLock(queue: string, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<{
         job: Job | null;
         token: string | null;
     }>;
-    pullBatch(queue: string, count: number, timeoutMs?: number, signal?: AbortSignal): Promise<Job[]>;
-    pullBatchWithLock(queue: string, count: number, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal): Promise<{
+    pullBatch(queue: string, count: number, timeoutMs?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<Job[]>;
+    pullBatchWithLock(queue: string, count: number, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<{
         jobs: Job[];
         tokens: string[];
     }>;

package/dist/application/queue-manager/delivery.js

@@ -20,29 +20,36 @@ export class QueueManagerDelivery extends QueueManagerState {
     async pushFlow(batch) {
         return pushFlowBatch(batch, this.contextFactory.getPushContext());
     }
-    async pull(queue, timeoutMs = 0, signal) {
-        const job = await pullJob(queue, timeoutMs, this.contextFactory.getPullContext(), signal);
+    async pull(queue, timeoutMs = 0, signal, groupOptions) {
+        const job = await pullJob(queue, timeoutMs, this.contextFactory.getPullContext(), signal, groupOptions);
         if (job)
             this.scheduleJobTimeout(job);
         return job;
     }
-    async pullWithLock(queue, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal) {
-        const job = await pullJob(queue, timeoutMs, this.contextFactory.getPullContext(), signal);
+    // oxlint-disable-next-line max-params -- public API includes cancellation and lock policy
+    async pullWithLock(queue, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal, groupOptions) {
+        const job = await pullJob(queue, timeoutMs, this.contextFactory.getPullContext(), signal, groupOptions);
         if (!job)
             return { job: null, token: null };
         const token = lockMgr.createLock(job.id, owner, this.contextFactory.getLockContext(), lockTtl);
         this.scheduleJobTimeout(job);
         return { job, token };
     }
-    async pullBatch(queue, count, timeoutMs = 0, signal) {
-        const jobs = await pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext(), signal);
+    async pullBatch(queue, count, timeoutMs = 0, signal, groupOptions) {
+        const jobs = await pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext(), {
+            signal,
+            group: groupOptions,
+        });
         for (const job of jobs)
             this.scheduleJobTimeout(job);
         return jobs;
     }
     // oxlint-disable-next-line max-params -- public API includes cancellation and lock policy
-    async pullBatchWithLock(queue, count, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal) {
-        const jobs = await pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext(), signal);
+    async pullBatchWithLock(queue, count, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal, groupOptions) {
+        const jobs = await pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext(), {
+            signal,
+            group: groupOptions,
+        });
         const tokens = jobs.map((job) => lockMgr.createLock(job.id, owner, this.contextFactory.getLockContext(), lockTtl) ?? '');
         for (const job of jobs)
             this.scheduleJobTimeout(job);

package/dist/application/queue-manager/flow-failures.js

@@ -9,6 +9,10 @@ export class QueueManagerFlowFailures extends QueueManagerDependencyRuntime {
             this.jobIndex.delete(entry.job.id);
             this.jobResults.delete(entry.job.id);
             this.jobLogs.delete(entry.job.id);
+            this.dependencyResults.releaseConsumer(entry.job.id);
+            if (entry.job.customId && this.customIdMap.get(entry.job.customId) === entry.job.id) {
+                this.customIdMap.delete(entry.job.customId);
+            }
         }
         this.storage?.purgeDlqEntries(entry.job.queue, [entry.job.id], ownsTerminal ? [entry.job.id] : [], false);
     }

package/dist/application/queue-manager/limits.d.ts

@@ -1,7 +1,18 @@
 import type { Job, JobId } from '../../domain/types/job';
 import type { DlqEntry, DlqFilter, DlqStats } from '../../domain/types/dlq';
 import { QueueManagerControl } from './control';
+import { type GroupRateLimitOverride } from '../../domain/types/group';
 export declare class QueueManagerLimits extends QueueManagerControl {
+    getGroupJobsCount(queue: string, groupId: string): number | Promise<number>;
+    getGroupsJobsCount(queue: string): number | Promise<number>;
+    getGroupActiveCount(queue: string, groupId: string): number | Promise<number>;
+    setGroupRateLimit(queue: string, groupId: string, max: number, duration: number): void | Promise<void>;
+    getGroupRateLimit(queue: string, groupId: string): GroupRateLimitOverride | null | Promise<GroupRateLimitOverride | null>;
+    removeGroupRateLimit(queue: string, groupId: string): number | Promise<number>;
+    getGroupRateLimitTtl(queue: string, groupId: string, maxJobs?: number): number | Promise<number>;
+    setGroupConcurrency(queue: string, groupId: string, concurrency: number): void | Promise<void>;
+    getGroupConcurrency(queue: string, groupId: string): number | null | Promise<number | null>;
+    removeGroupConcurrency(queue: string, groupId: string): number | Promise<number>;
     getCountsPerPriority(queue: string): Record<number, number>;
     getJobs(queue: string, options?: {
         state?: string | string[];
@@ -16,6 +27,8 @@ export declare class QueueManagerLimits extends QueueManagerControl {
     retryDlq(queue: string, jobId?: JobId, limit?: number): number;
     retryDlqByFilter(queue: string, filter: DlqFilter): number;
     purgeDlq(queue: string): number;
+    /** Remove one terminal DLQ job without re-enqueuing it. */
+    removeDlqJob(queue: string, jobId: JobId): boolean;
     retryCompleted(queue: string, jobId?: JobId, options?: {
         limit?: number;
         timestamp?: number;

package/dist/application/queue-manager/limits.js

@@ -4,7 +4,68 @@ import { shardIndex, SHARD_COUNT } from '../../shared/hash';
 import * as dlqOps from '../dlqManager';
 import * as queryOps from '../operations/queryOperations';
 import { QueueManagerControl } from './control';
+import { assertGroupId, assertPositiveSafeInteger, } from '../../domain/types/group';
 export class QueueManagerLimits extends QueueManagerControl {
+    getGroupJobsCount(queue, groupId) {
+        assertGroupId(groupId);
+        return this.shards[shardIndex(queue)].getGroupJobsCount(queue, groupId);
+    }
+    getGroupsJobsCount(queue) {
+        return this.shards[shardIndex(queue)].getGroupsJobsCount(queue);
+    }
+    getGroupActiveCount(queue, groupId) {
+        assertGroupId(groupId);
+        return this.shards[shardIndex(queue)].getGroupActiveCount(queue, groupId);
+    }
+    setGroupRateLimit(queue, groupId, max, duration) {
+        assertGroupId(groupId);
+        assertPositiveSafeInteger(max, 'max');
+        assertPositiveSafeInteger(duration, 'duration');
+        const shard = this.shards[shardIndex(queue)];
+        this.storage?.saveGroupRateLimit(queue, groupId, max, duration);
+        shard.setGroupRateLimit(queue, groupId, max, duration);
+        shard.notifyBatch(queue, Math.max(1, shard.getGroupJobsCount(queue, groupId)));
+    }
+    getGroupRateLimit(queue, groupId) {
+        assertGroupId(groupId);
+        return this.shards[shardIndex(queue)].getGroupRateLimit(queue, groupId);
+    }
+    removeGroupRateLimit(queue, groupId) {
+        assertGroupId(groupId);
+        const shard = this.shards[shardIndex(queue)];
+        if (!shard.getGroupRateLimit(queue, groupId))
+            return 0;
+        this.storage?.removeGroupRateLimit(queue, groupId);
+        const removed = shard.removeGroupRateLimit(queue, groupId);
+        shard.notifyBatch(queue, Math.max(1, shard.getGroupJobsCount(queue, groupId)));
+        return removed;
+    }
+    getGroupRateLimitTtl(queue, groupId, maxJobs) {
+        assertGroupId(groupId);
+        return this.shards[shardIndex(queue)].getGroupRateLimitTtl(queue, groupId, maxJobs);
+    }
+    setGroupConcurrency(queue, groupId, concurrency) {
+        assertGroupId(groupId);
+        assertPositiveSafeInteger(concurrency, 'concurrency');
+        const shard = this.shards[shardIndex(queue)];
+        this.storage?.saveGroupConcurrency(queue, groupId, concurrency);
+        shard.setGroupConcurrency(queue, groupId, concurrency);
+        shard.notifyBatch(queue, Math.max(1, shard.getGroupJobsCount(queue, groupId)));
+    }
+    getGroupConcurrency(queue, groupId) {
+        assertGroupId(groupId);
+        return this.shards[shardIndex(queue)].getGroupConcurrency(queue, groupId);
+    }
+    removeGroupConcurrency(queue, groupId) {
+        assertGroupId(groupId);
+        const shard = this.shards[shardIndex(queue)];
+        if (shard.getGroupConcurrency(queue, groupId) === null)
+            return 0;
+        this.storage?.removeGroupConcurrency(queue, groupId);
+        const removed = shard.removeGroupConcurrency(queue, groupId);
+        shard.notifyBatch(queue, Math.max(1, shard.getGroupJobsCount(queue, groupId)));
+        return removed;
+    }
     getCountsPerPriority(queue) {
         const counts = this.shards[shardIndex(queue)].getCountsPerPriority(queue);
         return Object.fromEntries(counts);
@@ -37,6 +98,10 @@ export class QueueManagerLimits extends QueueManagerControl {
     purgeDlq(queue) {
         return dlqOps.purgeDlqJobs(queue, this.contextFactory.getDlqContext());
     }
+    /** Remove one terminal DLQ job without re-enqueuing it. */
+    removeDlqJob(queue, jobId) {
+        return dlqOps.removeDlqJob(queue, jobId, this.contextFactory.getDlqContext());
+    }
     retryCompleted(queue, jobId, options) {
         return dlqOps.retryCompletedJobs(queue, this.contextFactory.getRetryCompletedContext(), jobId, options);
     }

package/dist/application/queue-manager/observability.js

@@ -2,6 +2,7 @@ import * as logsOps from '../jobLogsManager';
 import { generatePrometheusMetrics } from '../metricsExporter';
 import { selectPrometheusQueues } from '../prometheusOperationalMetrics';
 import * as statsMgr from '../statsManager';
+import { isStorageDegraded } from '../../shared/storageHealth';
 import { QueueManagerStats } from './stats';
 export class QueueManagerObservability extends QueueManagerStats {
     getQueueMetrics(queue, type, start = 0, end = -1) {
@@ -25,9 +26,20 @@ export class QueueManagerObservability extends QueueManagerStats {
     getPrometheusMetrics() {
         const storageStatus = this.getStorageStatus();
         const memory = process.memoryUsage();
-        const queueSelection = selectPrometheusQueues(this.queueNamesCache, this.config.maxPrometheusQueues);
-        return generatePrometheusMetrics(this.getStats(), this.workerManager, this.webhookManager, statsMgr.getPerQueueStats(this.contextFactory.getStatsContext(), queueSelection.selected), {
-            storageDegraded: storageStatus.diskFull,
+        const queueSelection = selectPrometheusQueues(this.listQueues(), this.config.maxPrometheusQueues);
+        const countsByQueue = this.getQueueJobCountsBatch(queueSelection.selected);
+        const perQueueStats = new Map([...countsByQueue].map(([queue, counts]) => [
+            queue,
+            {
+                waiting: counts.waiting,
+                prioritized: counts.prioritized,
+                delayed: counts.delayed,
+                active: counts.active,
+                dlq: counts.failed,
+            },
+        ]));
+        return generatePrometheusMetrics(this.getStats(), this.workerManager, this.webhookManager, perQueueStats, {
+            storageDegraded: isStorageDegraded(storageStatus),
             storageDiskFull: storageStatus.diskFull,
             ...(this.storage && { sqliteDatabaseSizeBytes: this.storage.getSize() }),
             processHeapUsedBytes: memory.heapUsed,

package/dist/application/queue-manager/queries.d.ts

@@ -4,6 +4,13 @@ export declare class QueueManagerQueries extends QueueManagerLocks {
     getJob(jobId: JobId): Promise<Job | null>;
     getJobState(jobId: JobId): Promise<string>;
     getResult(jobId: JobId): unknown;
+    /** Distinguish a completed generation from a valid undefined result. */
+    getCompletionAsync(jobId: JobId): Promise<{
+        found: boolean;
+        result: unknown;
+    }>;
+    /** Async result port used by transports; memory and SQLite remain synchronous internally. */
+    getResultAsync(jobId: JobId): Promise<unknown>;
     getChildrenValues(parentJobId: JobId): Promise<Record<string, unknown>>;
     updateJobParent(childJobId: JobId, parentJobId: JobId): Promise<void>;
     getJobByCustomId(customId: string): Job | null;

package/dist/application/queue-manager/queries.js

@@ -14,6 +14,15 @@ export class QueueManagerQueries extends QueueManagerLocks {
     getResult(jobId) {
         return queryOps.getJobResult(jobId, this.contextFactory.getQueryContext());
     }
+    /** Distinguish a completed generation from a valid undefined result. */
+    async getCompletionAsync(jobId) {
+        const found = this.completedJobs.has(jobId);
+        return { found, result: found ? this.getResult(jobId) : undefined };
+    }
+    /** Async result port used by transports; memory and SQLite remain synchronous internally. */
+    async getResultAsync(jobId) {
+        return (await this.getCompletionAsync(jobId)).result;
+    }
     async getChildrenValues(parentJobId) {
         const job = await this.getJob(parentJobId);
         if (!job?.childrenIds || job.childrenIds.length === 0)