bunqueue 2.9.0 → 2.9.2

package/dist/infrastructure/persistence/jobOptionsBlob.js

@@ -1,3 +1,4 @@
+import { getGroupFifoOrder } from '../../domain/job/groupFifoOrder';
 import { storageLog } from '../../shared/logger';
 import { decodeMessagePack, encodeMessagePack } from '../../shared/msgpack';
 const DEFAULTS = {
@@ -12,10 +13,14 @@ const DEFAULTS = {
     debounceId: null,
     debounceTtl: null,
     durable: false,
+    groupFifoOrder: null,
 };
+function validStoredOrder(value) {
+    return typeof value === 'string' && /^[1-9]\d*$/.test(value) ? value : null;
+}
 /** Persist generation policies that do not have dedicated legacy columns. */
 export function encodeJobOptions(job) {
-    return encodeMessagePack({
+    const options = {
         backoffConfig: job.backoffConfig,
         repeat: job.repeat,
         stackTraceLimit: job.stackTraceLimit,
@@ -27,7 +32,9 @@ export function encodeJobOptions(job) {
         debounceId: job.debounceId,
         debounceTtl: job.debounceTtl,
         durable: job.durable ?? false,
-    });
+    };
+    const order = getGroupFifoOrder(job);
+    return encodeMessagePack(order === null ? options : { ...options, groupFifoOrder: String(order) });
 }
 /** Decode current blobs while giving pre-v34 rows their historical defaults. */
 export function decodeJobOptions(blob, context) {
@@ -47,6 +54,7 @@ export function decodeJobOptions(blob, context) {
             debounceId: decoded.debounceId ?? null,
             debounceTtl: decoded.debounceTtl ?? null,
             durable: decoded.durable ?? false,
+            groupFifoOrder: validStoredOrder(decoded.groupFifoOrder),
         };
     }
     catch (error) {

package/dist/infrastructure/persistence/migrations.js

@@ -117,4 +117,15 @@ CREATE INDEX IF NOT EXISTS idx_queue_metric_buckets_window
 `,
     // Persist repeat-chain and advanced per-generation job policies.
     34: 'ALTER TABLE jobs ADD COLUMN extended_options BLOB;',
+    // Persist per-group rate and concurrency overrides.
+    35: `
+CREATE TABLE IF NOT EXISTS group_state (
+    queue TEXT NOT NULL,
+    group_id TEXT NOT NULL,
+    rate_limit INTEGER,
+    rate_duration INTEGER,
+    concurrency_limit INTEGER,
+    PRIMARY KEY (queue, group_id)
+);
+`,
 };

package/dist/infrastructure/persistence/postgres/admission.js

@@ -75,14 +75,17 @@ async function insertRow(tx, ctx, job, state, now) {
     INSERT INTO bunqueue_jobs (
       namespace, id, queue, payload, state, priority, lifo, run_at, created_at,
       started_at, completed_at, attempts, max_attempts, ttl, timeout, unique_key,
-      unique_expires_at, custom_id, group_id, parent_id
+      unique_expires_at, custom_id, group_id, group_order, parent_id
     ) VALUES (
       ${ctx.config.namespace}, ${String(job.id)}, ${job.queue}, ${encodePostgresValue(job)},
       ${state}, ${job.priority}, ${job.lifo}, ${job.runAt}, ${job.createdAt},
       ${job.startedAt}, ${job.completedAt}, ${job.attempts}, ${job.maxAttempts}, ${job.ttl},
       ${job.timeout}, ${job.uniqueKey},
       ${job.uniqueKey && job.deduplicationTtl !== null ? now + job.deduplicationTtl : null},
-      ${job.customId}, ${job.groupId}, ${job.parentId}
+      ${job.customId}, ${job.groupId},
+      CASE WHEN CAST(${job.groupId} AS TEXT) IS NULL
+        THEN NULL ELSE nextval('bunqueue_group_order_seq') END,
+      ${job.parentId}
     )
   `;
     await insertDependencies(tx, ctx, job);

package/dist/infrastructure/persistence/postgres/batchAdmission.js

@@ -57,8 +57,8 @@ function prepareAdmissions(jobs, now) {
         return { job: preparedJob, state };
     });
 }
-function toRecords(prepared, namespace, now) {
-    return prepared.map(({ job, state }) => ({
+function toRecords(prepared, namespace, now, groupOrders) {
+    return prepared.map(({ job, state }, position) => ({
         namespace,
         id: String(job.id),
         queue: job.queue,
@@ -78,15 +78,33 @@ function toRecords(prepared, namespace, now) {
         unique_expires_at: job.uniqueKey && job.deduplicationTtl !== null ? now + job.deduplicationTtl : null,
         custom_id: job.customId,
         group_id: job.groupId,
+        group_order: groupOrders.get(position) ?? null,
     }));
 }
+async function allocateGroupOrders(tx, prepared) {
+    const positions = prepared.flatMap(({ job }, position) => job.groupId === null ? [] : [position]);
+    if (positions.length === 0)
+        return new Map();
+    const rows = await tx `
+    WITH ordered AS MATERIALIZED (
+      SELECT position
+      FROM unnest(${tx.array(positions, 'INTEGER')}) AS requested(position)
+      ORDER BY position
+    )
+    SELECT position, nextval('bunqueue_group_order_seq') AS group_order
+    FROM ordered
+    ORDER BY position
+  `;
+    return new Map(rows.map(({ position, group_order }) => [position, group_order]));
+}
 async function insertRows(tx, ctx, prepared, now) {
-    const records = toRecords(prepared, ctx.config.namespace, now);
+    const groupOrders = await allocateGroupOrders(tx, prepared);
+    const records = toRecords(prepared, ctx.config.namespace, now, groupOrders);
     let insertedCount = 0;
     for (let offset = 0; offset < records.length; offset += 1000) {
         const batch = records.slice(offset, offset + 1000);
         const inserted = await tx `
-      INSERT INTO bunqueue_jobs ${tx(batch, 'namespace', 'id', 'queue', 'payload', 'state', 'priority', 'lifo', 'run_at', 'created_at', 'started_at', 'completed_at', 'attempts', 'max_attempts', 'ttl', 'timeout', 'unique_key', 'unique_expires_at', 'custom_id', 'group_id')}
+      INSERT INTO bunqueue_jobs ${tx(batch, 'namespace', 'id', 'queue', 'payload', 'state', 'priority', 'lifo', 'run_at', 'created_at', 'started_at', 'completed_at', 'attempts', 'max_attempts', 'ttl', 'timeout', 'unique_key', 'unique_expires_at', 'custom_id', 'group_id', 'group_order')}
       ON CONFLICT DO NOTHING
       RETURNING id
     `;

package/dist/infrastructure/persistence/postgres/claimBatch.d.ts

@@ -1,4 +1,5 @@
 import type { TransactionSQL } from 'bun';
+import type { GroupPullOptions } from '../../../domain/types/group';
 import type { PostgresContext } from './context';
 import type { ClaimedPostgresJob } from './types';
 /** Claim one queue batch after its queue-state row has been locked. */
@@ -8,4 +9,6 @@ export declare function claimPostgresCandidates(tx: TransactionSQL, ctx: Postgre
     owner: string;
     requestedLeaseMs: number;
     now: number;
+    groupOptions?: GroupPullOptions;
+    groupSequence: number;
 }): Promise<ClaimedPostgresJob[]>;

package/dist/infrastructure/persistence/postgres/claimBatch.js

@@ -2,6 +2,7 @@ import { generateLockToken, MAX_TIMELINE_ENTRIES } from '../../../domain/types/j
 import { recordPostgresJobEvents } from './batchEvents';
 import { selectPostgresClaimCandidates } from './claimSelection';
 import { decodePostgresJob, encodePostgresValue, postgresByteaBase64 } from './codec';
+import { commitPostgresGroupClaims } from './groupClaims';
 function prepareClaims(rows, input) {
     const { owner, requestedLeaseMs, now, brokerId } = input;
     return rows.map((row) => {
@@ -42,15 +43,27 @@ async function persistClaims(tx, ctx, claimed, now) {
 }
 /** Claim one queue batch after its queue-state row has been locked. */
 export async function claimPostgresCandidates(tx, ctx, input) {
-    const { queue, capacity, owner, requestedLeaseMs, now } = input;
-    const rows = await selectPostgresClaimCandidates(tx, ctx, queue, now, capacity);
+    const { queue, capacity, owner, requestedLeaseMs, now, groupOptions, groupSequence } = input;
+    const rows = await selectPostgresClaimCandidates(tx, ctx, {
+        queue,
+        now,
+        capacity,
+        options: groupOptions,
+    });
     const claimed = prepareClaims(rows, {
         owner,
         requestedLeaseMs,
         now,
         brokerId: ctx.config.brokerId,
     });
-    if (claimed.length > 0)
+    if (claimed.length > 0) {
+        await commitPostgresGroupClaims(tx, ctx, {
+            queue,
+            rows,
+            options: groupOptions,
+            sequence: groupSequence,
+        });
         await persistClaims(tx, ctx, claimed, now);
+    }
     return claimed;
 }

package/dist/infrastructure/persistence/postgres/claimSelection.d.ts

@@ -1,4 +1,11 @@
 import type { TransactionSQL } from 'bun';
+import type { GroupPullOptions } from '../../../domain/types/group';
 import type { PostgresContext } from './context';
 import type { PostgresJobRow } from './types';
-export declare function selectPostgresClaimCandidates(tx: TransactionSQL, ctx: PostgresContext, queue: string, now: number, capacity: number): Promise<PostgresJobRow[]>;
+export declare function hasClaimablePostgresGroup(tx: TransactionSQL, ctx: PostgresContext, queue: string, now: number): Promise<boolean>;
+export declare function selectPostgresClaimCandidates(tx: TransactionSQL, ctx: PostgresContext, input: {
+    queue: string;
+    now: number;
+    capacity: number;
+    options?: GroupPullOptions;
+}): Promise<PostgresJobRow[]>;

package/dist/infrastructure/persistence/postgres/claimSelection.js

@@ -1,143 +1,75 @@
-async function hasClaimableGroupedJob(tx, ctx, queue, now) {
+export async function hasClaimablePostgresGroup(tx, ctx, queue, now) {
     const [row] = await tx `
     SELECT EXISTS (
-      SELECT 1
-      FROM bunqueue_jobs AS job
-      WHERE job.namespace = ${ctx.config.namespace}
-        AND job.queue = ${queue}
+      SELECT 1 FROM bunqueue_jobs AS job
+      WHERE job.namespace = ${ctx.config.namespace} AND job.queue = ${queue}
         AND job.group_id IS NOT NULL
         AND job.state IN ('waiting', 'prioritized', 'delayed')
         AND job.run_at <= ${now}
         AND (job.ttl IS NULL OR job.created_at + job.ttl >= ${now})
         AND NOT EXISTS (
-          SELECT 1
-          FROM bunqueue_dependencies AS dependency
-          WHERE dependency.namespace = job.namespace
-            AND dependency.job_id = job.id
+          SELECT 1 FROM bunqueue_dependencies AS dependency
+          WHERE dependency.namespace = job.namespace AND dependency.job_id = job.id
             AND NOT EXISTS (
               SELECT 1 FROM bunqueue_completions AS completion
               WHERE completion.namespace = dependency.namespace
                 AND completion.job_id = dependency.dependency_id
             )
         )
-        AND NOT EXISTS (
-          SELECT 1 FROM bunqueue_jobs AS active_group
-          WHERE active_group.namespace = job.namespace
-            AND active_group.queue = job.queue
-            AND active_group.group_id = job.group_id
-            AND active_group.state = 'active'
-            AND active_group.lease_until > ${now}
-        )
-    ) AS exists
-  `;
-    return row.exists;
-}
-async function hasClaimableLifoJob(tx, ctx, queue, now) {
-    const [row] = await tx `
-    SELECT EXISTS (
-      SELECT 1 FROM bunqueue_jobs AS job
-      WHERE job.namespace = ${ctx.config.namespace}
-        AND job.queue = ${queue}
-        AND job.group_id IS NULL
-        AND job.lifo
-        AND job.state IN ('waiting', 'prioritized', 'delayed')
-        AND job.run_at <= ${now}
-        AND (job.ttl IS NULL OR job.created_at + job.ttl >= ${now})
     ) AS exists
   `;
     return row.exists;
 }
-async function selectFifoCandidates(tx, ctx, queue, now, capacity) {
-    return await tx `
-    WITH selected AS (
-      SELECT job.id, job.priority, job.run_at
-      FROM bunqueue_jobs AS job
-      WHERE job.namespace = ${ctx.config.namespace}
-        AND job.queue = ${queue}
-        AND job.group_id IS NULL
-        AND NOT job.lifo
-        AND job.state IN ('waiting', 'prioritized', 'delayed')
-        AND job.run_at <= ${now}
-        AND (job.ttl IS NULL OR job.created_at + job.ttl >= ${now})
-        AND NOT EXISTS (
-          SELECT 1 FROM bunqueue_dependencies AS dependency
-          WHERE dependency.namespace = job.namespace
-            AND dependency.job_id = job.id
-            AND NOT EXISTS (
-              SELECT 1 FROM bunqueue_completions AS completion
-              WHERE completion.namespace = dependency.namespace
-                AND completion.job_id = dependency.dependency_id
-            )
-        )
-      ORDER BY job.priority DESC, job.run_at ASC, job.id ASC
-      LIMIT ${capacity}
-      FOR UPDATE OF job SKIP LOCKED
-    )
-    SELECT job.*
-    FROM bunqueue_jobs AS job
-    JOIN selected ON selected.id = job.id
-    WHERE job.namespace = ${ctx.config.namespace}
-    ORDER BY selected.priority DESC, selected.run_at ASC, selected.id ASC
-  `;
-}
 async function selectUngroupedCandidates(tx, ctx, queue, now, capacity) {
     return await tx `
     WITH selected AS (
       SELECT job.id, job.priority, job.lifo, job.run_at
       FROM bunqueue_jobs AS job
-      WHERE job.namespace = ${ctx.config.namespace}
-        AND job.queue = ${queue}
+      WHERE job.namespace = ${ctx.config.namespace} AND job.queue = ${queue}
         AND job.group_id IS NULL
         AND job.state IN ('waiting', 'prioritized', 'delayed')
         AND job.run_at <= ${now}
         AND (job.ttl IS NULL OR job.created_at + job.ttl >= ${now})
         AND NOT EXISTS (
           SELECT 1 FROM bunqueue_dependencies AS dependency
-          WHERE dependency.namespace = job.namespace
-            AND dependency.job_id = job.id
+          WHERE dependency.namespace = job.namespace AND dependency.job_id = job.id
             AND NOT EXISTS (
               SELECT 1 FROM bunqueue_completions AS completion
               WHERE completion.namespace = dependency.namespace
                 AND completion.job_id = dependency.dependency_id
             )
         )
-      ORDER BY
-        job.priority DESC,
-        CASE WHEN job.lifo THEN 0 ELSE 1 END ASC,
+      ORDER BY job.priority DESC,
+        CASE WHEN job.lifo THEN 0 ELSE 1 END,
         CASE WHEN job.lifo THEN job.id END DESC,
-        CASE WHEN NOT job.lifo THEN job.run_at END ASC,
-        job.id ASC
+        CASE WHEN NOT job.lifo THEN job.run_at END,
+        job.id
       LIMIT ${capacity}
       FOR UPDATE OF job SKIP LOCKED
     )
-    SELECT job.*
-    FROM bunqueue_jobs AS job
+    SELECT job.* FROM bunqueue_jobs AS job
     JOIN selected ON selected.id = job.id
     WHERE job.namespace = ${ctx.config.namespace}
-    ORDER BY
-      selected.priority DESC,
-      CASE WHEN selected.lifo THEN 0 ELSE 1 END ASC,
+    ORDER BY selected.priority DESC,
+      CASE WHEN selected.lifo THEN 0 ELSE 1 END,
       CASE WHEN selected.lifo THEN selected.id END DESC,
-      CASE WHEN NOT selected.lifo THEN selected.run_at END ASC,
-      selected.id ASC
+      CASE WHEN NOT selected.lifo THEN selected.run_at END,
+      selected.id
   `;
 }
-async function selectGroupedCandidates(tx, ctx, queue, now, capacity) {
+async function selectGroupedCandidates(tx, ctx, input) {
+    const { queue, now, capacity, options } = input;
+    const concurrency = options?.concurrency ?? null;
+    const rateMax = options?.limit?.max ?? null;
     return await tx `
-    WITH eligible AS (
-      SELECT job.id, job.priority, job.lifo, job.run_at,
+    WITH ready AS (
+      SELECT job.id, job.group_id,
         row_number() OVER (
-          PARTITION BY CASE
-            WHEN job.group_id IS NULL THEN 'job:' || job.id ELSE 'group:' || job.group_id
-          END
-          ORDER BY job.priority DESC,
-            CASE WHEN job.lifo THEN 0 ELSE 1 END ASC,
-            CASE WHEN job.lifo THEN job.id END DESC,
-            CASE WHEN NOT job.lifo THEN job.run_at END ASC, job.id ASC
+          PARTITION BY job.group_id ORDER BY job.run_at, job.group_order, job.id
         ) AS group_position
       FROM bunqueue_jobs AS job
-      WHERE job.namespace = ${ctx.config.namespace}
-        AND job.queue = ${queue}
+      WHERE job.namespace = ${ctx.config.namespace} AND job.queue = ${queue}
+        AND job.group_id IS NOT NULL
         AND job.state IN ('waiting', 'prioritized', 'delayed')
         AND job.run_at <= ${now}
         AND (job.ttl IS NULL OR job.created_at + job.ttl >= ${now})
@@ -150,49 +82,59 @@ async function selectGroupedCandidates(tx, ctx, queue, now, capacity) {
                 AND completion.job_id = dependency.dependency_id
             )
         )
-        AND (job.group_id IS NULL OR NOT EXISTS (
-          SELECT 1 FROM bunqueue_jobs AS active_group
-          WHERE active_group.namespace = job.namespace AND active_group.queue = job.queue
-            AND active_group.group_id = job.group_id AND active_group.state = 'active'
-            AND active_group.lease_until > ${now}
-        ))
+    ), active AS (
+      SELECT group_id, COUNT(*)::integer AS count
+      FROM bunqueue_jobs
+      WHERE namespace = ${ctx.config.namespace} AND queue = ${queue}
+        AND group_id IS NOT NULL AND state = 'active' AND lease_until > ${now}
+      GROUP BY group_id
+    ), capacities AS (
+      SELECT groups.group_id, groups.last_served,
+        LEAST(
+          ${capacity},
+          CASE WHEN CAST(${concurrency} AS BIGINT) IS NULL THEN ${capacity}
+            ELSE GREATEST(
+              0,
+              COALESCE(groups.concurrency_limit, CAST(${concurrency} AS BIGINT))
+                - COALESCE(active.count, 0)
+            )
+          END,
+          CASE WHEN CAST(${rateMax} AS BIGINT) IS NULL THEN ${capacity}
+            ELSE GREATEST(
+              0,
+              COALESCE(groups.rate_limit, CAST(${rateMax} AS BIGINT)) - groups.rate_count
+            )
+          END
+        ) AS available
+      FROM bunqueue_group_state AS groups
+      LEFT JOIN active ON active.group_id = groups.group_id
+      WHERE groups.namespace = ${ctx.config.namespace} AND groups.queue = ${queue}
+    ), selected AS (
+      SELECT ready.id, ready.group_id, ready.group_position, capacities.last_served
+      FROM ready JOIN capacities ON capacities.group_id = ready.group_id
+      WHERE ready.group_position <= capacities.available
+      ORDER BY ready.group_position, capacities.last_served NULLS FIRST, ready.group_id
+      LIMIT ${capacity}
     )
-    SELECT job.*
-    FROM bunqueue_jobs AS job
-    JOIN eligible ON eligible.id = job.id
+    SELECT job.* FROM bunqueue_jobs AS job
+    JOIN selected ON selected.id = job.id
     WHERE job.namespace = ${ctx.config.namespace}
-      AND eligible.group_position = 1
       AND job.state IN ('waiting', 'prioritized', 'delayed')
       AND job.run_at <= ${now}
-      AND (job.ttl IS NULL OR job.created_at + job.ttl >= ${now})
-      AND NOT EXISTS (
-        SELECT 1 FROM bunqueue_dependencies AS dependency
-        WHERE dependency.namespace = job.namespace AND dependency.job_id = job.id
-          AND NOT EXISTS (
-            SELECT 1 FROM bunqueue_completions AS completion
-            WHERE completion.namespace = dependency.namespace
-              AND completion.job_id = dependency.dependency_id
-          )
-      )
-      AND (job.group_id IS NULL OR NOT EXISTS (
-        SELECT 1 FROM bunqueue_jobs AS active_group
-        WHERE active_group.namespace = job.namespace AND active_group.queue = job.queue
-          AND active_group.group_id = job.group_id AND active_group.state = 'active'
-          AND active_group.lease_until > ${now}
-      ))
-    ORDER BY job.priority DESC,
-      CASE WHEN job.lifo THEN 0 ELSE 1 END ASC,
-      CASE WHEN job.lifo THEN job.id END DESC,
-      CASE WHEN NOT job.lifo THEN job.run_at END ASC, job.id ASC
-    LIMIT ${capacity}
+    ORDER BY selected.group_position, selected.last_served NULLS FIRST, selected.group_id
     FOR UPDATE OF job SKIP LOCKED
   `;
 }
-export async function selectPostgresClaimCandidates(tx, ctx, queue, now, capacity) {
-    if (await hasClaimableGroupedJob(tx, ctx, queue, now)) {
-        return await selectGroupedCandidates(tx, ctx, queue, now, capacity);
-    }
-    return (await hasClaimableLifoJob(tx, ctx, queue, now))
-        ? await selectUngroupedCandidates(tx, ctx, queue, now, capacity)
-        : await selectFifoCandidates(tx, ctx, queue, now, capacity);
+export async function selectPostgresClaimCandidates(tx, ctx, input) {
+    const { queue, now, capacity, options } = input;
+    const ungrouped = await selectUngroupedCandidates(tx, ctx, queue, now, capacity);
+    if (ungrouped.length >= capacity)
+        return ungrouped;
+    const grouped = await selectGroupedCandidates(tx, ctx, {
+        queue,
+        now,
+        capacity: capacity - ungrouped.length,
+        options,
+    });
+    return [...ungrouped, ...grouped];
 }

package/dist/infrastructure/persistence/postgres/claims.d.ts

@@ -1,3 +1,10 @@
+import type { GroupPullOptions } from '../../../domain/types/group';
 import { type PostgresContext } from './context';
 import type { ClaimedPostgresJob } from './types';
-export declare function claimPostgresJobs(ctx: PostgresContext, queue: string, count: number, owner: string, leaseDurationMs: number): Promise<ClaimedPostgresJob[]>;
+export declare function claimPostgresJobs(ctx: PostgresContext, input: {
+    queue: string;
+    count: number;
+    owner: string;
+    leaseDurationMs: number;
+    groupOptions?: GroupPullOptions;
+}): Promise<ClaimedPostgresJob[]>;

package/dist/infrastructure/persistence/postgres/claims.js

@@ -7,6 +7,8 @@ import { expirePendingPostgresJobs } from './expiry';
 import { repairResolvedPostgresDependencyConsumers } from './dependencyPromotion';
 import { lockPostgresBrokerSession } from './brokerSessions';
 import { runPostgresTransactionWithRetry } from './transactionRetry';
+import { hasClaimablePostgresGroup } from './claimSelection';
+import { ensurePostgresGroupStates, refreshPostgresGroupRateWindows } from './groupClaims';
 function toQueueState(row) {
     return {
         queue: row.queue,
@@ -19,20 +21,23 @@ function toQueueState(row) {
         concurrencyLimit: row.concurrency_limit,
         stallConfig: decodePostgresValue(row.stall_config, DEFAULT_STALL_CONFIG, 'stallConfig'),
         dlqConfig: decodePostgresValue(row.dlq_config, DEFAULT_DLQ_CONFIG, 'dlqConfig'),
+        groupSequence: Number(row.group_sequence),
     };
 }
 async function lockQueueState(tx, ctx, queue, exclusive) {
     const select = async () => exclusive
         ? await tx `
           SELECT queue, paused, rate_limit, rate_duration_ms, rate_window_started_at,
-                 rate_expires_at, rate_count, concurrency_limit, stall_config, dlq_config
+                 rate_expires_at, rate_count, concurrency_limit, stall_config, dlq_config,
+                 group_sequence
           FROM bunqueue_queue_state
           WHERE namespace = ${ctx.config.namespace} AND queue = ${queue}
           FOR UPDATE
         `
         : await tx `
           SELECT queue, paused, rate_limit, rate_duration_ms, rate_window_started_at,
-                 rate_expires_at, rate_count, concurrency_limit, stall_config, dlq_config
+                 rate_expires_at, rate_count, concurrency_limit, stall_config, dlq_config,
+                 group_sequence
           FROM bunqueue_queue_state
           WHERE namespace = ${ctx.config.namespace} AND queue = ${queue}
           FOR SHARE
@@ -92,7 +97,8 @@ async function activeCount(tx, ctx, queue, now) {
   `;
     return Number(row.count);
 }
-export async function claimPostgresJobs(ctx, queue, count, owner, leaseDurationMs) {
+export async function claimPostgresJobs(ctx, input) {
+    const { queue, count, owner, leaseDurationMs, groupOptions } = input;
     if (count <= 0)
         return [];
     await expirePendingPostgresJobs(ctx, queue);
@@ -114,12 +120,22 @@ export async function claimPostgresJobs(ctx, queue, count, owner, leaseDurationM
         if (capacity <= 0)
             return { claimed: [], retryExclusive: false };
         await repairResolvedPostgresDependencyConsumers(tx, ctx, queue, now);
+        const hasGroups = await hasClaimablePostgresGroup(tx, ctx, queue, now);
+        if (!exclusive && hasGroups)
+            return { claimed: [], retryExclusive: true };
+        let groupSequence = state.groupSequence;
+        if (hasGroups) {
+            groupSequence = await ensurePostgresGroupStates(tx, ctx, queue, groupSequence);
+            await refreshPostgresGroupRateWindows(tx, ctx, queue, groupOptions, now);
+        }
         const claimed = await claimPostgresCandidates(tx, ctx, {
             queue,
             capacity,
             owner,
             requestedLeaseMs: leaseDurationMs,
             now,
+            groupOptions,
+            groupSequence,
         });
         if (state.rateLimit !== null && claimed.length > 0) {
             await tx `

package/dist/infrastructure/persistence/postgres/eventCatchupCursors.d.ts

@@ -0,0 +1,32 @@
+import type { PostgresEventPruneWatermark } from './eventPruneWatermarks';
+/** Per-queue catch-up bookkeeping for commit-ordered durable event delivery. */
+export declare class PostgresEventCatchupCursors {
+    private readonly appliedCommitSeqs;
+    private readonly handledPruneWatermarks;
+    private baselineCommitSeq;
+    reset(baselineCommitSeq: number): void;
+    appliedThrough(queue: string): number;
+    applied(queue: string, commitSeq: number): void;
+    /** Record a prune watermark as accounted for and report whether it was new. */
+    remember(watermark: PostgresEventPruneWatermark): boolean;
+    /** Report whether a commit pruned its own events without this reader knowing. */
+    private hasUnhandledSelfPrune;
+    /**
+     * Report whether a prune watermark requires an authoritative queue refresh.
+     *
+     * Two cases need one. A reader at or behind the pruned frontier may have
+     * missed discarded history. And a commit that writes more queue events than
+     * the retained window prunes its own older events before any reader can
+     * observe them, so every reader must reload once per such commit, even one
+     * whose applied position has already moved past it. `self_pruned_commit_seq`
+     * carries that evidence forward per queue, so a superseding watermark does
+     * not drop it; queue destruction erases it with the queue itself, which is
+     * safe because the same transaction also invalidates the queue and commit
+     * sequence numbers never rewind. A watermark already accounted for never
+     * refreshes again. The `<=` comparison is deliberately wider than the
+     * observed cases: it also covers a commit split across drain batches, where
+     * the applied cursor already equals the pruned frontier while the rest of
+     * that commit is still unread.
+     */
+    requiresRefresh(watermark: PostgresEventPruneWatermark): boolean;
+}

package/dist/infrastructure/persistence/postgres/eventCatchupCursors.js

@@ -0,0 +1,66 @@
+/** Per-queue catch-up bookkeeping for commit-ordered durable event delivery. */
+export class PostgresEventCatchupCursors {
+    appliedCommitSeqs = new Map();
+    handledPruneWatermarks = new Map();
+    baselineCommitSeq = 0;
+    reset(baselineCommitSeq) {
+        this.baselineCommitSeq = baselineCommitSeq;
+        this.appliedCommitSeqs.clear();
+        this.handledPruneWatermarks.clear();
+    }
+    appliedThrough(queue) {
+        return this.appliedCommitSeqs.get(queue) ?? this.baselineCommitSeq;
+    }
+    applied(queue, commitSeq) {
+        this.appliedCommitSeqs.set(queue, Math.max(this.appliedThrough(queue), commitSeq));
+    }
+    /** Record a prune watermark as accounted for and report whether it was new. */
+    remember(watermark) {
+        const { queue, commitSeq, prunedThrough, selfPrunedCommitSeq } = watermark;
+        const handled = this.handledPruneWatermarks.get(queue);
+        if (handled !== undefined &&
+            handled.commitSeq >= commitSeq &&
+            handled.prunedThrough >= prunedThrough &&
+            handled.selfPrunedCommitSeq >= selfPrunedCommitSeq) {
+            return false;
+        }
+        this.handledPruneWatermarks.set(queue, {
+            commitSeq: Math.max(handled?.commitSeq ?? 0, commitSeq),
+            prunedThrough: Math.max(handled?.prunedThrough ?? 0, prunedThrough),
+            selfPrunedCommitSeq: Math.max(handled?.selfPrunedCommitSeq ?? 0, selfPrunedCommitSeq),
+        });
+        return true;
+    }
+    /** Report whether a commit pruned its own events without this reader knowing. */
+    hasUnhandledSelfPrune(watermark) {
+        const handled = this.handledPruneWatermarks.get(watermark.queue);
+        return watermark.selfPrunedCommitSeq > (handled?.selfPrunedCommitSeq ?? 0);
+    }
+    /**
+     * Report whether a prune watermark requires an authoritative queue refresh.
+     *
+     * Two cases need one. A reader at or behind the pruned frontier may have
+     * missed discarded history. And a commit that writes more queue events than
+     * the retained window prunes its own older events before any reader can
+     * observe them, so every reader must reload once per such commit, even one
+     * whose applied position has already moved past it. `self_pruned_commit_seq`
+     * carries that evidence forward per queue, so a superseding watermark does
+     * not drop it; queue destruction erases it with the queue itself, which is
+     * safe because the same transaction also invalidates the queue and commit
+     * sequence numbers never rewind. A watermark already accounted for never
+     * refreshes again. The `<=` comparison is deliberately wider than the
+     * observed cases: it also covers a commit split across drain batches, where
+     * the applied cursor already equals the pruned frontier while the rest of
+     * that commit is still unread.
+     */
+    requiresRefresh(watermark) {
+        const behind = this.appliedThrough(watermark.queue) <= watermark.prunedCommitSeq;
+        const selfPruned = this.hasUnhandledSelfPrune(watermark);
+        if (!this.remember(watermark))
+            return false;
+        if (!behind && !selfPruned)
+            return false;
+        this.applied(watermark.queue, watermark.commitSeq);
+        return true;
+    }
+}