bunqueue 2.8.60 → 2.9.2

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

@@ -1,8 +1,27 @@
-import type { JobId } from '../../types/job';
+import type { Job, JobId } from '../../types/job';
+import type { GroupPullOptions, GroupRateLimitOverride } from '../../types/group';
+import type { GroupCandidate } from '../groupScheduler';
 import type { QueueState } from '../../types/queue';
 import { ShardKeys } from './keys';
 /** Queue rate, concurrency, and resource ownership operations. */
 export declare class ShardLimits extends ShardKeys {
+    hasGroupScheduler(queue: string): boolean;
+    assignGroupFifoOrder(job: Job): void;
+    observeGroupFifoOrder(job: Job): void;
+    peekGroupCandidate(queue: string, now: number, options?: GroupPullOptions): GroupCandidate;
+    acquireGroup(queue: string, groupId: string, options?: GroupPullOptions, now?: number): boolean;
+    advanceGroup(queue: string, groupId: string): void;
+    getGroupJobsCount(queue: string, groupId: string): number;
+    getGroupsJobsCount(queue: string): number;
+    cleanExpiredGroupWindows(now: number): void;
+    clearEmptyGroupRuntime(queue: string): void;
+    setGroupRateLimit(queue: string, groupId: string, max: number, duration: number): void;
+    getGroupRateLimit(queue: string, groupId: string): GroupRateLimitOverride | null;
+    removeGroupRateLimit(queue: string, groupId: string): number;
+    getGroupRateLimitTtl(queue: string, groupId: string, maxJobs?: number): number;
+    setGroupConcurrency(queue: string, groupId: string, concurrency: number): void;
+    getGroupConcurrency(queue: string, groupId: string): number | null;
+    removeGroupConcurrency(queue: string, groupId: string): number;
     setRateLimit(queue: string, limit: number, durationMs?: number, ttlMs?: number): void;
     clearRateLimit(queue: string): void;
     expireRateLimitIfNeeded(queue: string): void;

package/dist/domain/queue/shard/limits.js

@@ -1,6 +1,62 @@
 import { ShardKeys } from './keys';
 /** Queue rate, concurrency, and resource ownership operations. */
 export class ShardLimits extends ShardKeys {
+    hasGroupScheduler(queue) {
+        return this.groupScheduler.isActive(queue);
+    }
+    assignGroupFifoOrder(job) {
+        this.groupScheduler.assignFifoOrder(job);
+    }
+    observeGroupFifoOrder(job) {
+        this.groupScheduler.observeFifoOrder(job);
+    }
+    peekGroupCandidate(queue, now, options) {
+        return this.groupScheduler.peek(queue, now, (groupId) => this.groupLimiterManager.status(queue, groupId, options, this.getGroupActiveCount(queue, groupId), now));
+    }
+    acquireGroup(queue, groupId, options, now) {
+        const acquired = this.groupLimiterManager.acquire(queue, groupId, options, this.getGroupActiveCount(queue, groupId), now);
+        if (acquired)
+            this.activateGroup(queue, groupId);
+        return acquired;
+    }
+    advanceGroup(queue, groupId) {
+        this.groupScheduler.advance(queue, groupId);
+    }
+    getGroupJobsCount(queue, groupId) {
+        return this.groupScheduler.getGroupJobsCount(queue, groupId);
+    }
+    getGroupsJobsCount(queue) {
+        return this.groupScheduler.getGroupsJobsCount(queue);
+    }
+    cleanExpiredGroupWindows(now) {
+        this.groupLimiterManager.pruneExpiredWindows(now);
+    }
+    clearEmptyGroupRuntime(queue) {
+        this.groupScheduler.clearQueue(queue);
+        this.activeGroups.delete(queue);
+        this.activeGroupCounts.delete(queue);
+    }
+    setGroupRateLimit(queue, groupId, max, duration) {
+        this.groupLimiterManager.setRateLimit(queue, groupId, max, duration);
+    }
+    getGroupRateLimit(queue, groupId) {
+        return this.groupLimiterManager.getRateLimit(queue, groupId);
+    }
+    removeGroupRateLimit(queue, groupId) {
+        return this.groupLimiterManager.removeRateLimit(queue, groupId);
+    }
+    getGroupRateLimitTtl(queue, groupId, maxJobs) {
+        return this.groupLimiterManager.getRateLimitTtl(queue, groupId, maxJobs);
+    }
+    setGroupConcurrency(queue, groupId, concurrency) {
+        this.groupLimiterManager.setConcurrency(queue, groupId, concurrency);
+    }
+    getGroupConcurrency(queue, groupId) {
+        return this.groupLimiterManager.getConcurrency(queue, groupId);
+    }
+    removeGroupConcurrency(queue, groupId) {
+        return this.groupLimiterManager.removeConcurrency(queue, groupId);
+    }
     setRateLimit(queue, limit, durationMs, ttlMs) {
         this.limiterManager.setRateLimit(queue, limit, durationMs, ttlMs);
     }

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

@@ -4,6 +4,8 @@ import { DependencyTracker } from '../dependencyTracker';
 import { DlqShard } from '../dlqShard';
 import { LimiterManager } from '../limiterManager';
 import { IndexedPriorityQueue } from '../priorityQueue';
+import { GroupLimiterManager } from '../groupLimiterManager';
+import { GroupScheduler } from '../groupScheduler';
 import { ShardCounters } from '../shardCounters';
 import { TemporalManager } from '../temporalManager';
 import { UniqueKeyManager } from '../uniqueKeyManager';
@@ -12,9 +14,12 @@ import { WaiterManager } from '../waiterManager';
 export declare class ShardState {
     readonly queues: Map<string, IndexedPriorityQueue>;
     readonly activeGroups: Map<string, Set<string>>;
+    readonly activeGroupCounts: Map<string, Map<string, number>>;
     protected readonly uniqueKeyManager: UniqueKeyManager;
     protected readonly dlqManager: DlqShard;
     protected readonly limiterManager: LimiterManager;
+    protected readonly groupLimiterManager: GroupLimiterManager;
+    protected readonly groupScheduler: GroupScheduler;
     protected readonly dependencyTracker: DependencyTracker;
     protected readonly temporalManager: TemporalManager;
     protected readonly waiterManager: WaiterManager;

package/dist/domain/queue/shard/state.js

@@ -2,6 +2,8 @@ import { DependencyTracker } from '../dependencyTracker';
 import { DlqShard } from '../dlqShard';
 import { LimiterManager } from '../limiterManager';
 import { IndexedPriorityQueue } from '../priorityQueue';
+import { GroupLimiterManager } from '../groupLimiterManager';
+import { GroupScheduler } from '../groupScheduler';
 import { ShardCounters } from '../shardCounters';
 import { TemporalManager } from '../temporalManager';
 import { UniqueKeyManager } from '../uniqueKeyManager';
@@ -10,9 +12,12 @@ import { WaiterManager } from '../waiterManager';
 export class ShardState {
     queues = new Map();
     activeGroups = new Map();
+    activeGroupCounts = new Map();
     uniqueKeyManager = new UniqueKeyManager();
     dlqManager;
     limiterManager = new LimiterManager();
+    groupLimiterManager = new GroupLimiterManager();
+    groupScheduler = new GroupScheduler();
     dependencyTracker = new DependencyTracker();
     temporalManager = new TemporalManager();
     waiterManager = new WaiterManager();
@@ -49,7 +54,10 @@ export class ShardState {
     getQueue(name) {
         let queue = this.queues.get(name);
         if (!queue) {
-            queue = new IndexedPriorityQueue();
+            queue = new IndexedPriorityQueue({
+                onInsert: (job) => this.groupScheduler.insert(name, job, () => this.queues.get(name)?.values() ?? []),
+                onRemove: (job) => this.groupScheduler.remove(name, job),
+            });
             this.queues.set(name, queue);
         }
         return queue;

package/dist/domain/types/commands/core.d.ts

@@ -1,5 +1,6 @@
 import type { AtomicFlowJobInput } from '../flow';
 import type { JobInput } from '../job';
+import type { GroupPullOptions } from '../group';
 import type { BaseCommand } from './base';
 export interface PushCommand extends BaseCommand {
     readonly cmd: 'PUSH';
@@ -72,6 +73,7 @@ export interface PullCommand extends BaseCommand {
     readonly owner?: string;
     readonly lockTtl?: number;
     readonly detach?: boolean;
+    readonly group?: GroupPullOptions;
 }
 export interface PullBatchCommand extends BaseCommand {
     readonly cmd: 'PULLB';
@@ -80,6 +82,7 @@ export interface PullBatchCommand extends BaseCommand {
     readonly timeout?: number;
     readonly owner?: string;
     readonly lockTtl?: number;
+    readonly group?: GroupPullOptions;
 }
 export interface AckCommand extends BaseCommand {
     readonly cmd: 'ACK';

package/dist/domain/types/commands/dlq.d.ts

@@ -21,6 +21,11 @@ export interface PurgeDlqCommand extends BaseCommand {
     readonly cmd: 'PurgeDlq';
     readonly queue: string;
 }
+export interface RemoveDlqJobCommand extends BaseCommand {
+    readonly cmd: 'RemoveDlqJob';
+    readonly queue: string;
+    readonly jobId: string;
+}
 export interface RetryCompletedCommand extends BaseCommand {
     readonly cmd: 'RetryCompleted';
     readonly queue: string;

package/dist/domain/types/commands/limits.d.ts

@@ -52,3 +52,44 @@ export interface GetStallConfigCommand extends BaseCommand {
     readonly cmd: 'GetStallConfig';
     readonly queue: string;
 }
+interface GroupCommand extends BaseCommand {
+    readonly queue: string;
+    readonly groupId: string;
+}
+export interface GetGroupJobsCountCommand extends GroupCommand {
+    readonly cmd: 'GetGroupJobsCount';
+}
+export interface GetGroupsJobsCountCommand extends BaseCommand {
+    readonly cmd: 'GetGroupsJobsCount';
+    readonly queue: string;
+    readonly maxCount?: number;
+}
+export interface GetGroupActiveCountCommand extends GroupCommand {
+    readonly cmd: 'GetGroupActiveCount';
+}
+export interface SetGroupRateLimitCommand extends GroupCommand {
+    readonly cmd: 'SetGroupRateLimit';
+    readonly max: number;
+    readonly duration: number;
+}
+export interface GetGroupRateLimitCommand extends GroupCommand {
+    readonly cmd: 'GetGroupRateLimit';
+}
+export interface RemoveGroupRateLimitCommand extends GroupCommand {
+    readonly cmd: 'RemoveGroupRateLimit';
+}
+export interface GetGroupRateLimitTtlCommand extends GroupCommand {
+    readonly cmd: 'GetGroupRateLimitTtl';
+    readonly maxJobs?: number;
+}
+export interface SetGroupConcurrencyCommand extends GroupCommand {
+    readonly cmd: 'SetGroupConcurrency';
+    readonly concurrency: number;
+}
+export interface GetGroupConcurrencyCommand extends GroupCommand {
+    readonly cmd: 'GetGroupConcurrency';
+}
+export interface RemoveGroupConcurrencyCommand extends GroupCommand {
+    readonly cmd: 'RemoveGroupConcurrency';
+}
+export {};

package/dist/domain/types/commands/union.d.ts

@@ -9,5 +9,5 @@ import type * as Monitoring from './monitoring';
 import type * as Protocol from './protocol';
 import type * as Query from './query';
 import type * as Workers from './workers';
-export type Command = Core.PushCommand | Core.PushBatchCommand | Core.PushFlowCommand | Core.PullCommand | Core.PullBatchCommand | Core.AckCommand | Core.AckBatchCommand | Core.FailCommand | Query.GetJobCommand | Query.GetStateCommand | Query.GetResultCommand | Query.GetJobsCommand | Query.GetJobCountsCommand | Query.GetCountsPerPriorityCommand | Query.GetJobByCustomIdCommand | Query.CountCommand | Query.GetProgressCommand | Query.GetChildrenValuesCommand | Management.CancelCommand | Management.ProgressCommand | Management.UpdateCommand | Management.ChangePriorityCommand | Management.PromoteCommand | Management.WaitJobCommand | Management.MoveToDelayedCommand | Management.DiscardCommand | Management.PauseCommand | Management.ResumeCommand | Management.IsPausedCommand | Management.DrainCommand | Management.ObliterateCommand | Management.ListQueuesCommand | Management.CleanCommand | Dlq.DlqCommand | Dlq.GetDlqStatsCommand | Dlq.RetryDlqCommand | Dlq.PurgeDlqCommand | Dlq.RetryCompletedCommand | Dlq.SetDlqConfigCommand | Dlq.GetDlqConfigCommand | Limits.GetQueueLimitsCommand | Limits.GetDeduplicationJobIdCommand | Limits.RemoveDeduplicationKeyCommand | Limits.RemoveJobDeduplicationKeyCommand | Limits.MoveToWaitingChildrenCommand | Limits.RateLimitCommand | Limits.SetConcurrencyCommand | Limits.RateLimitClearCommand | Limits.ClearConcurrencyCommand | Limits.SetStallConfigCommand | Limits.GetStallConfigCommand | Cron.CronCommand | Cron.CronDeleteCommand | Cron.CronListCommand | Cron.CronGetCommand | Monitoring.AddLogCommand | Monitoring.GetLogsCommand | Monitoring.AddWebhookCommand | Monitoring.RemoveWebhookCommand | Monitoring.ListWebhooksCommand | Monitoring.StatsCommand | Monitoring.MetricsCommand | Monitoring.TrimEventsCommand | Monitoring.PrometheusCommand | Monitoring.StorageStatusCommand | Workers.HeartbeatCommand | Workers.JobHeartbeatCommand | Workers.JobHeartbeatBatchCommand | Workers.PingCommand | Workers.RegisterWorkerCommand | Workers.UnregisterWorkerCommand | Workers.ListWorkersCommand | Extended.ClearLogsCommand | Extended.ExtendLockCommand | Extended.ExtendLocksCommand | Extended.ChangeDelayCommand | Extended.SetWebhookEnabledCommand | Extended.CompactMemoryCommand | Extended.UpdateParentCommand | Extended.GetFailedChildrenValuesCommand | Extended.GetIgnoredChildrenFailuresCommand | Extended.RemoveChildDependencyCommand | Extended.RemoveUnprocessedChildrenCommand | Extended.MoveToWaitCommand | Extended.PromoteJobsCommand | Dashboard.DashboardOverviewCommand | Dashboard.DashboardQueuesCommand | Dashboard.DashboardQueueCommand | Protocol.AuthCommand | Protocol.HelloCommand | Protocol.SubscribeEventsCommand | Protocol.UnsubscribeEventsCommand;
+export type Command = Core.PushCommand | Core.PushBatchCommand | Core.PushFlowCommand | Core.PullCommand | Core.PullBatchCommand | Core.AckCommand | Core.AckBatchCommand | Core.FailCommand | Query.GetJobCommand | Query.GetStateCommand | Query.GetResultCommand | Query.GetJobsCommand | Query.GetJobCountsCommand | Query.GetCountsPerPriorityCommand | Query.GetJobByCustomIdCommand | Query.CountCommand | Query.GetProgressCommand | Query.GetChildrenValuesCommand | Management.CancelCommand | Management.ProgressCommand | Management.UpdateCommand | Management.ChangePriorityCommand | Management.PromoteCommand | Management.WaitJobCommand | Management.MoveToDelayedCommand | Management.DiscardCommand | Management.PauseCommand | Management.ResumeCommand | Management.IsPausedCommand | Management.DrainCommand | Management.ObliterateCommand | Management.ListQueuesCommand | Management.CleanCommand | Dlq.DlqCommand | Dlq.GetDlqStatsCommand | Dlq.RetryDlqCommand | Dlq.PurgeDlqCommand | Dlq.RemoveDlqJobCommand | Dlq.RetryCompletedCommand | Dlq.SetDlqConfigCommand | Dlq.GetDlqConfigCommand | Limits.GetQueueLimitsCommand | Limits.GetDeduplicationJobIdCommand | Limits.RemoveDeduplicationKeyCommand | Limits.RemoveJobDeduplicationKeyCommand | Limits.MoveToWaitingChildrenCommand | Limits.RateLimitCommand | Limits.SetConcurrencyCommand | Limits.RateLimitClearCommand | Limits.ClearConcurrencyCommand | Limits.SetStallConfigCommand | Limits.GetStallConfigCommand | Limits.GetGroupJobsCountCommand | Limits.GetGroupsJobsCountCommand | Limits.GetGroupActiveCountCommand | Limits.SetGroupRateLimitCommand | Limits.GetGroupRateLimitCommand | Limits.RemoveGroupRateLimitCommand | Limits.GetGroupRateLimitTtlCommand | Limits.SetGroupConcurrencyCommand | Limits.GetGroupConcurrencyCommand | Limits.RemoveGroupConcurrencyCommand | Cron.CronCommand | Cron.CronDeleteCommand | Cron.CronListCommand | Cron.CronGetCommand | Monitoring.AddLogCommand | Monitoring.GetLogsCommand | Monitoring.AddWebhookCommand | Monitoring.RemoveWebhookCommand | Monitoring.ListWebhooksCommand | Monitoring.StatsCommand | Monitoring.MetricsCommand | Monitoring.TrimEventsCommand | Monitoring.PrometheusCommand | Monitoring.StorageStatusCommand | Workers.HeartbeatCommand | Workers.JobHeartbeatCommand | Workers.JobHeartbeatBatchCommand | Workers.PingCommand | Workers.RegisterWorkerCommand | Workers.UnregisterWorkerCommand | Workers.ListWorkersCommand | Extended.ClearLogsCommand | Extended.ExtendLockCommand | Extended.ExtendLocksCommand | Extended.ChangeDelayCommand | Extended.SetWebhookEnabledCommand | Extended.CompactMemoryCommand | Extended.UpdateParentCommand | Extended.GetFailedChildrenValuesCommand | Extended.GetIgnoredChildrenFailuresCommand | Extended.RemoveChildDependencyCommand | Extended.RemoveUnprocessedChildrenCommand | Extended.MoveToWaitCommand | Extended.PromoteJobsCommand | Dashboard.DashboardOverviewCommand | Dashboard.DashboardQueuesCommand | Dashboard.DashboardQueueCommand | Protocol.AuthCommand | Protocol.HelloCommand | Protocol.SubscribeEventsCommand | Protocol.UnsubscribeEventsCommand;
 export type CommandType = Command['cmd'];

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

@@ -78,6 +78,11 @@ export interface CronJobInput {
     /** Job options applied to each spawned job (retry/cleanup policy, etc.) */
     jobOptions?: CronJobOptions;
 }
+/** Validate the calendar/interval timing fields before scheduler mutation. */
+export declare function assertValidCronTiming(input: {
+    readonly schedule?: string | null;
+    readonly repeatEvery?: number | null;
+}): void;
 /** Create a new cron job */
 export declare function createCronJob(input: CronJobInput, nextRun: number): CronJob;
 /** Check if cron job has reached its execution limit */

package/dist/domain/types/cron.js

@@ -2,11 +2,22 @@
  * Cron job domain types
  */
 import { normalizeJobPayload } from '../job/payload';
-/** Create a new cron job */
-export function createCronJob(input, nextRun) {
-    if (!input.schedule && !input.repeatEvery) {
+/** Validate the calendar/interval timing fields before scheduler mutation. */
+export function assertValidCronTiming(input) {
+    if (input.repeatEvery !== undefined && input.repeatEvery !== null) {
+        if (typeof input.repeatEvery !== 'number' ||
+            !Number.isSafeInteger(input.repeatEvery) ||
+            input.repeatEvery < 1) {
+            throw new Error('Cron repeatEvery must be a positive safe integer number of milliseconds');
+        }
+    }
+    if (!input.schedule && (input.repeatEvery === undefined || input.repeatEvery === null)) {
         throw new Error('Cron job must have either schedule or repeatEvery');
     }
+}
+/** Create a new cron job */
+export function createCronJob(input, nextRun) {
+    assertValidCronTiming(input);
     const payload = normalizeJobPayload({ name: input.jobName, data: input.data });
     return {
         name: input.name,

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

@@ -89,7 +89,7 @@ export interface DlqConfig {
 /** Default DLQ configuration */
 export declare const DEFAULT_DLQ_CONFIG: DlqConfig;
 /** Create a DLQ entry from a failed job */
-export declare function createDlqEntry(job: Job, reason: FailureReason, error: string | null, config?: DlqConfig): DlqEntry;
+export declare function createDlqEntry(job: Job, reason: FailureReason, error: string | null, config?: DlqConfig, now?: number): DlqEntry;
 /** Add attempt record to existing DLQ entry */
 export declare function addAttemptRecord(entry: DlqEntry, reason: FailureReason, error: string | null): void;
 /** Check if DLQ entry is expired */

package/dist/domain/types/dlq.js

@@ -63,8 +63,7 @@ export const DEFAULT_DLQ_CONFIG = {
     maxEntries: 10000,
 };
 /** Create a DLQ entry from a failed job */
-export function createDlqEntry(job, reason, error, config = DEFAULT_DLQ_CONFIG) {
-    const now = Date.now();
+export function createDlqEntry(job, reason, error, config = DEFAULT_DLQ_CONFIG, now = Date.now()) {
     const retained = getDlqRetryState(job);
     const alreadyEntered = retained?.enteredAt !== null && retained?.enteredAt !== undefined;
     const attemptRecord = createAttemptRecord(job, reason, error, now);

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

@@ -0,0 +1,21 @@
+export interface GroupRateLimit {
+    readonly max: number;
+    readonly duration: number;
+}
+/** Worker-side defaults enforced authoritatively by the broker. */
+export interface GroupPullOptions {
+    readonly concurrency?: number;
+    readonly limit?: GroupRateLimit;
+}
+export interface GroupRateLimitOverride extends GroupRateLimit {
+}
+/** Validate the canonical string form shared by every broker and persistence backend. */
+export declare function validateGroupId(value: unknown, required?: boolean): string | null;
+export declare function assertGroupId(value: unknown): asserts value is string;
+export declare function assertOptionalGroupId(value: unknown): asserts value is string | undefined;
+/** Normalize BullMQ-compatible numeric IDs without accepting arbitrary coercion. */
+export declare function normalizeGroupId(value: unknown): string;
+export declare function validatePositiveSafeInteger(value: unknown, name: string): string | null;
+export declare function assertPositiveSafeInteger(value: unknown, name: string): asserts value is number;
+export declare function validateGroupPullOptions(options: unknown): string | null;
+export declare function assertGroupPullOptions(options: unknown): asserts options is GroupPullOptions;

package/dist/domain/types/group.js

@@ -0,0 +1,78 @@
+/** Validate the canonical string form shared by every broker and persistence backend. */
+export function validateGroupId(value, required = false) {
+    if (value === undefined)
+        return required ? 'groupId is required' : null;
+    if (typeof value !== 'string')
+        return 'groupId must be a string';
+    if (value.length === 0)
+        return 'groupId must be a non-empty string';
+    if (value.length > 256)
+        return 'groupId must be at most 256 characters';
+    if (value.includes('\0'))
+        return 'groupId must not contain NUL characters';
+    return null;
+}
+export function assertGroupId(value) {
+    const error = validateGroupId(value, true);
+    if (error)
+        throw new Error(error);
+}
+export function assertOptionalGroupId(value) {
+    const error = validateGroupId(value);
+    if (error)
+        throw new Error(error);
+}
+/** Normalize BullMQ-compatible numeric IDs without accepting arbitrary coercion. */
+export function normalizeGroupId(value) {
+    if (typeof value !== 'string' && typeof value !== 'number') {
+        throw new Error('groupId must be a string or number');
+    }
+    if (typeof value === 'number' && !Number.isSafeInteger(value)) {
+        throw new Error('numeric groupId must be a safe integer');
+    }
+    const groupId = String(value);
+    assertGroupId(groupId);
+    return groupId;
+}
+export function validatePositiveSafeInteger(value, name) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+        return `${name} must be a positive safe integer`;
+    }
+    return null;
+}
+export function assertPositiveSafeInteger(value, name) {
+    const error = validatePositiveSafeInteger(value, name);
+    if (error)
+        throw new Error(error);
+}
+export function validateGroupPullOptions(options) {
+    if (options === undefined)
+        return null;
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        return 'group must be an object';
+    }
+    const group = options;
+    if (group.concurrency !== undefined) {
+        const error = validatePositiveSafeInteger(group.concurrency, 'group.concurrency');
+        if (error)
+            return error;
+    }
+    if (group.limit !== undefined) {
+        if (!group.limit || typeof group.limit !== 'object' || Array.isArray(group.limit)) {
+            return 'group.limit must be an object';
+        }
+        const limit = group.limit;
+        const maxError = validatePositiveSafeInteger(limit.max, 'group.limit.max');
+        if (maxError)
+            return maxError;
+        const durationError = validatePositiveSafeInteger(limit.duration, 'group.limit.duration');
+        if (durationError)
+            return durationError;
+    }
+    return null;
+}
+export function assertGroupPullOptions(options) {
+    const error = validateGroupPullOptions(options);
+    if (error)
+        throw new Error(error);
+}

package/dist/domain/types/jobs/model.d.ts

@@ -83,7 +83,7 @@ export interface Job {
     readonly deduplicationReplace: boolean;
     readonly debounceId: string | null;
     readonly debounceTtl: number | null;
-    /** Whether each generation bypasses the persistence write buffer. */
+    /** Whether SQLite admission bypasses its write buffer; PostgreSQL is always transactional. */
     readonly durable?: boolean;
     timeline: JobTimelineEntry[];
 }

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

@@ -5,6 +5,7 @@ export interface HeapEntry {
     runAt: number;
     lifo: boolean;
     generation: bigint;
+    groupFifoOrder?: bigint;
 }
 export interface IndexedJob {
     job: Job;

package/dist/infrastructure/cloud/commandHandler.js

@@ -7,6 +7,8 @@
  */
 import { cloudLog } from './logger';
 import { COMMANDS } from './commands';
+import { resolveCloudQueueAdapter } from './queueAdapter/registry';
+import { sanitizeServerError } from '../server/errors';
 /**
  * Normalize object keys: PascalCase/UpperCase → camelCase.
  * Skips user data fields (data, result, backoffConfig, repeat) — those are passed as-is.
@@ -51,7 +53,7 @@ export async function handleCommand(queueManager, cmd, context) {
                 type: 'command_result',
                 id: cmd.id,
                 success: false,
-                error: err instanceof Error ? err.message : String(err),
+                error: sanitizeServerError(err),
             };
         }
     }
@@ -66,7 +68,7 @@ export async function handleCommand(queueManager, cmd, context) {
         };
     }
     try {
-        const raw = await handler(queueManager, cmd, context);
+        const raw = await handler(resolveCloudQueueAdapter(queueManager), cmd, context);
         const data = camelKeys(raw);
         cloudLog.info('Remote command executed', { action: cmd.action, id: cmd.id });
         return { type: 'command_result', id: cmd.id, success: true, data };
@@ -81,7 +83,7 @@ export async function handleCommand(queueManager, cmd, context) {
             type: 'command_result',
             id: cmd.id,
             success: false,
-            error: err instanceof Error ? err.message : String(err),
+            error: sanitizeServerError(err),
         };
     }
 }

package/dist/infrastructure/cloud/commands/integrations.js

@@ -1,7 +1,7 @@
 export const INTEGRATION_COMMANDS = {
-    'cron:upsert': (queueManager, command) => {
-        queueManager.removeCron(command.name ?? '');
-        const cron = queueManager.addCron({
+    'cron:upsert': async (adapter, command) => {
+        await adapter.removeCron(command.name ?? '');
+        const cron = await adapter.addCron({
             name: command.name ?? '',
             jobName: 'default',
             queue: command.queue ?? '',
@@ -10,18 +10,18 @@ export const INTEGRATION_COMMANDS = {
         });
         return { name: cron.name, nextRun: cron.nextRun };
     },
-    'cron:delete': (queueManager, command) => ({
-        deleted: queueManager.removeCron(command.name ?? ''),
+    'cron:delete': async (adapter, command) => ({
+        deleted: await adapter.removeCron(command.name ?? ''),
     }),
-    'webhook:add': (queueManager, command) => {
-        const webhook = queueManager.webhookManager.add(command.url ?? '', command.events ?? [], command.queue ?? undefined, command.secret ?? undefined);
+    'webhook:add': (adapter, command) => {
+        const webhook = adapter.manager.webhookManager.add(command.url ?? '', command.events ?? [], command.queue ?? undefined, command.secret ?? undefined);
         return { id: webhook.id, url: webhook.url, events: webhook.events };
     },
-    'webhook:remove': (queueManager, command) => ({
-        removed: queueManager.webhookManager.remove(command.webhookId ?? ''),
+    'webhook:remove': (adapter, command) => ({
+        removed: adapter.manager.webhookManager.remove(command.webhookId ?? ''),
     }),
-    'webhook:set-enabled': (queueManager, command) => ({
-        updated: queueManager.webhookManager.setEnabled(command.webhookId ?? '', command.enabled ?? true),
+    'webhook:set-enabled': (adapter, command) => ({
+        updated: adapter.manager.webhookManager.setEnabled(command.webhookId ?? '', command.enabled ?? true),
     }),
     's3:backup': async (_queueManager, _command, context) => {
         if (!context?.triggerBackup)