bunqueue 2.8.60 → 2.9.2

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

@@ -0,0 +1,45 @@
+import type { PostgresContext } from './context';
+import type { PostgresDeliveredStoreEvent } from './types';
+type EventListener = (event: PostgresDeliveredStoreEvent) => void;
+type InvalidationListener = (queue: string) => void;
+type DrainStatusListener = (error: Error | null) => void;
+export declare function postgresEventDrainBatchSize(maxQueueEvents: number): number;
+/** Commit-ordered journal polling with LISTEN/NOTIFY used only as a wakeup hint. */
+export declare class PostgresEventStream {
+    private readonly ctx;
+    private subscription;
+    private pollTimer;
+    private readonly listeners;
+    private readonly invalidationListeners;
+    private readonly drainStatusListeners;
+    private readonly waiters;
+    private readonly queueCursors;
+    private readonly retentionQueues;
+    private journalCursor;
+    private cursor;
+    private checkpointScanRequested;
+    private drainRequested;
+    private draining;
+    private retentionRetryTimer;
+    private closed;
+    constructor(ctx: PostgresContext);
+    start(): Promise<void>;
+    subscribe(listener: EventListener): () => void;
+    subscribeInvalidation(listener: InvalidationListener): () => void;
+    subscribeDrainStatus(listener: DrainStatusListener): () => void;
+    close(): Promise<void>;
+    wait(queue: string, timeoutMs: number, signal?: AbortSignal): Promise<void>;
+    private handleNotification;
+    private wake;
+    private wakeAll;
+    private removeWaiter;
+    private drain;
+    private drainLoop;
+    private convergeEventRetention;
+    private scheduleRetentionRetry;
+    private applyEvent;
+    private invalidateQueue;
+    private scanPruneWatermarks;
+    private reportDrainStatus;
+}
+export {};

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

@@ -0,0 +1,276 @@
+import { latestPostgresEventJournalBaseline, loadPostgresJournalEventsAfter, } from './eventJournal';
+import { PostgresEventCatchupCursors } from './eventCatchupCursors';
+import { loadPostgresEventPruneWatermarks } from './eventPruneWatermarks';
+import { POSTGRES_EVENT_CHANNEL } from './schema';
+import { tryTrimPostgresQueueEvents } from './telemetry';
+const MIN_EVENT_DRAIN_BATCH = 1_000;
+const MAX_EVENT_DRAIN_BATCH = 4_096;
+export function postgresEventDrainBatchSize(maxQueueEvents) {
+    return Math.max(MIN_EVENT_DRAIN_BATCH, Math.min(MAX_EVENT_DRAIN_BATCH, maxQueueEvents));
+}
+function requiresQueueInvalidation(event) {
+    return event.type.startsWith('queue-') || (!event.job && event.state === null);
+}
+/** Commit-ordered journal polling with LISTEN/NOTIFY used only as a wakeup hint. */
+export class PostgresEventStream {
+    ctx;
+    subscription = null;
+    pollTimer = null;
+    listeners = new Set();
+    invalidationListeners = new Set();
+    drainStatusListeners = new Set();
+    waiters = new Map();
+    queueCursors = new PostgresEventCatchupCursors();
+    retentionQueues = new Set();
+    journalCursor = { commitSeq: 0, eventId: 0 };
+    cursor = 0;
+    checkpointScanRequested = false;
+    drainRequested = false;
+    draining = null;
+    retentionRetryTimer = null;
+    closed = false;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async start() {
+        const [baseline, watermarks] = await Promise.all([
+            latestPostgresEventJournalBaseline(this.ctx),
+            loadPostgresEventPruneWatermarks(this.ctx),
+        ]);
+        this.cursor = baseline.latestEventId;
+        this.journalCursor = { commitSeq: baseline.commitSeq, eventId: Number.MAX_SAFE_INTEGER };
+        this.queueCursors.reset(baseline.commitSeq);
+        for (const watermark of watermarks) {
+            if (watermark.commitSeq > baseline.commitSeq) {
+                this.queueCursors.applied(watermark.queue, watermark.commitSeq);
+            }
+            // `PostgresQueueManagerState` loads a full snapshot of every queue after
+            // this call, so recorded prunes are already covered and must not refresh
+            // the freshly loaded read model.
+            this.queueCursors.remember(watermark);
+        }
+        this.subscription = await this.ctx.sql.listen(POSTGRES_EVENT_CHANNEL, (payload) => this.handleNotification(payload), () => void this.drain());
+        this.pollTimer = setInterval(() => void this.drain(), this.ctx.config.pollIntervalMs);
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    subscribeInvalidation(listener) {
+        this.invalidationListeners.add(listener);
+        return () => this.invalidationListeners.delete(listener);
+    }
+    subscribeDrainStatus(listener) {
+        this.drainStatusListeners.add(listener);
+        return () => this.drainStatusListeners.delete(listener);
+    }
+    async close() {
+        this.closed = true;
+        if (this.pollTimer)
+            clearInterval(this.pollTimer);
+        this.pollTimer = null;
+        if (this.retentionRetryTimer)
+            clearTimeout(this.retentionRetryTimer);
+        this.retentionRetryTimer = null;
+        await this.subscription?.unlisten();
+        this.subscription = null;
+        for (const registrations of this.waiters.values()) {
+            for (const registration of [...registrations])
+                registration.resolve();
+        }
+        this.waiters.clear();
+        await this.draining;
+    }
+    wait(queue, timeoutMs, signal) {
+        if (this.closed || timeoutMs <= 0 || signal?.aborted)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const finish = () => {
+                this.removeWaiter(queue, registration);
+                resolve();
+            };
+            const onAbort = () => finish();
+            const registration = {
+                resolve: finish,
+                timer: setTimeout(finish, timeoutMs),
+                ...(signal && { signal, onAbort }),
+            };
+            let registrations = this.waiters.get(queue);
+            if (!registrations) {
+                registrations = new Set();
+                this.waiters.set(queue, registrations);
+            }
+            registrations.add(registration);
+            signal?.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    handleNotification(payload) {
+        try {
+            const parsed = JSON.parse(payload);
+            if (parsed.namespace !== this.ctx.config.namespace)
+                return;
+            if (parsed.queue)
+                this.wake(parsed.queue);
+            if (parsed.scanPruneWatermarks === true ||
+                (Number.isSafeInteger(parsed.prunedThrough) && parsed.prunedThrough > 0)) {
+                this.checkpointScanRequested = true;
+            }
+            if (parsed.queue && parsed.retentionRequested === true) {
+                this.retentionQueues.add(parsed.queue);
+            }
+        }
+        catch {
+            this.checkpointScanRequested = true;
+            this.wakeAll();
+        }
+        void this.drain(false);
+    }
+    wake(queue) {
+        const registrations = this.waiters.get(queue);
+        if (!registrations)
+            return;
+        for (const registration of [...registrations])
+            registration.resolve();
+    }
+    wakeAll() {
+        for (const queue of this.waiters.keys())
+            this.wake(queue);
+    }
+    removeWaiter(queue, registration) {
+        const registrations = this.waiters.get(queue);
+        registrations?.delete(registration);
+        if (registrations?.size === 0)
+            this.waiters.delete(queue);
+        clearTimeout(registration.timer);
+        if (registration.signal && registration.onAbort) {
+            registration.signal.removeEventListener('abort', registration.onAbort);
+        }
+    }
+    async drain(scanPruneWatermarks = true) {
+        if (scanPruneWatermarks)
+            this.checkpointScanRequested = true;
+        this.drainRequested = true;
+        if (this.closed)
+            return;
+        if (this.draining)
+            return this.draining;
+        this.draining = this.drainLoop()
+            .then(() => {
+            if (!this.closed && !this.retentionRetryTimer)
+                this.reportDrainStatus(null);
+        })
+            .catch((error) => {
+            this.reportDrainStatus(error instanceof Error ? error : new Error(String(error)));
+            this.scheduleRetentionRetry();
+        })
+            .finally(() => {
+            this.draining = null;
+            if (this.drainRequested && !this.closed)
+                void this.drain(false);
+        });
+        return this.draining;
+    }
+    async drainLoop() {
+        const batchSize = postgresEventDrainBatchSize(this.ctx.config.maxQueueEvents);
+        while (!this.closed) {
+            this.drainRequested = false;
+            await this.convergeEventRetention();
+            await this.scanPruneWatermarks();
+            const entries = await loadPostgresJournalEventsAfter(this.ctx, this.journalCursor, batchSize);
+            // Always re-check retention against the pre-batch position: a prune that
+            // committed after the previous scan can have removed queue history this
+            // batch does not contain, and applying the batch would hide the gap.
+            if (entries.length > 0)
+                this.checkpointScanRequested = true;
+            await this.scanPruneWatermarks();
+            for (const entry of entries)
+                this.applyEvent(entry);
+            if (entries.length >= batchSize || this.drainRequested)
+                continue;
+            return;
+        }
+    }
+    async convergeEventRetention() {
+        if (this.retentionRetryTimer)
+            return;
+        const maxLength = this.ctx.config.maxQueueEvents;
+        const queues = [...this.retentionQueues].sort();
+        for (const queue of queues) {
+            this.retentionQueues.delete(queue);
+            try {
+                const removed = await tryTrimPostgresQueueEvents(this.ctx, queue, maxLength);
+                if (removed === null) {
+                    this.retentionQueues.add(queue);
+                    this.scheduleRetentionRetry();
+                }
+            }
+            catch (error) {
+                this.retentionQueues.add(queue);
+                throw error;
+            }
+        }
+    }
+    scheduleRetentionRetry() {
+        if (this.closed || this.retentionRetryTimer || this.retentionQueues.size === 0)
+            return;
+        const delay = Math.min(this.ctx.config.pollIntervalMs, 250);
+        this.retentionRetryTimer = setTimeout(() => {
+            this.retentionRetryTimer = null;
+            if (!this.closed && this.retentionQueues.size > 0)
+                void this.drain(false);
+        }, delay);
+    }
+    applyEvent(entry) {
+        const { event, commitSeq } = entry;
+        this.journalCursor = { commitSeq, eventId: event.id };
+        this.cursor = Math.max(this.cursor, event.id);
+        this.queueCursors.applied(event.queue, commitSeq);
+        if (requiresQueueInvalidation(event))
+            this.invalidateQueue(event.queue);
+        const delivered = { ...event, commitSeq };
+        for (const listener of this.listeners) {
+            try {
+                listener(delivered);
+            }
+            catch {
+                // Listener isolation: one observer cannot stop durable cursor progress.
+            }
+        }
+    }
+    invalidateQueue(queue) {
+        for (const listener of this.invalidationListeners) {
+            try {
+                listener(queue);
+            }
+            catch {
+                // Invalidation observers cannot interrupt durable cursor progress.
+            }
+        }
+    }
+    async scanPruneWatermarks() {
+        if (!this.checkpointScanRequested)
+            return;
+        this.checkpointScanRequested = false;
+        try {
+            const watermarks = await loadPostgresEventPruneWatermarks(this.ctx);
+            for (const watermark of watermarks) {
+                if (this.queueCursors.requiresRefresh(watermark))
+                    this.invalidateQueue(watermark.queue);
+            }
+        }
+        catch (error) {
+            this.checkpointScanRequested = true;
+            throw error;
+        }
+    }
+    reportDrainStatus(error) {
+        for (const listener of this.drainStatusListeners) {
+            try {
+                listener(error);
+            }
+            catch {
+                // Diagnostics must not stop the next polling retry.
+            }
+        }
+    }
+}

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

@@ -0,0 +1,3 @@
+import { type PostgresContext } from './context';
+/** Delete pending jobs whose TTL elapsed, matching the existing SQLite pull semantics. */
+export declare function expirePendingPostgresJobs(ctx: PostgresContext, queue: string, requestedNow?: number): Promise<number>;

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

@@ -0,0 +1,74 @@
+import { jobId } from '../../../domain/types/job';
+import { decodePostgresJob } from './codec';
+import { databaseNow, recordPostgresEvent } from './context';
+import { lockPostgresDestructionCandidates, partitionPostgresDestructionCandidates, } from './dependencyDestruction';
+/** Delete pending jobs whose TTL elapsed, matching the existing SQLite pull semantics. */
+export async function expirePendingPostgresJobs(ctx, queue, requestedNow) {
+    return await ctx.sql.begin(async (tx) => {
+        const now = requestedNow ?? (await databaseNow(tx));
+        const candidates = await tx `
+      SELECT id FROM bunqueue_jobs
+      WHERE namespace = ${ctx.config.namespace}
+        AND queue = ${queue}
+        AND state IN ('waiting', 'prioritized', 'delayed')
+        AND ttl IS NOT NULL
+        AND created_at + ttl < ${now}
+      ORDER BY created_at, id
+      LIMIT 1000
+    `;
+        const candidateIds = candidates.map((row) => jobId(row.id));
+        if (candidateIds.length === 0)
+            return 0;
+        await lockPostgresDestructionCandidates(tx, ctx, candidateIds);
+        const rows = await tx `
+      SELECT * FROM bunqueue_jobs
+      WHERE namespace = ${ctx.config.namespace}
+        AND queue = ${queue}
+        AND state IN ('waiting', 'prioritized', 'delayed')
+        AND ttl IS NOT NULL
+        AND created_at + ttl < ${now}
+        AND id = ANY(${tx.array(candidateIds.map(String), 'TEXT')})
+      ORDER BY created_at, id
+    `;
+        const plannedIds = rows.map((row) => jobId(row.id));
+        const { deletableIds } = await partitionPostgresDestructionCandidates(tx, ctx, plannedIds, plannedIds);
+        const deletable = new Set(deletableIds.map(String));
+        const removedRows = rows.filter((row) => deletable.has(row.id));
+        if (removedRows.length === 0)
+            return 0;
+        const ids = removedRows.map((row) => row.id);
+        await tx `
+      DELETE FROM bunqueue_job_logs
+      WHERE namespace = ${ctx.config.namespace} AND job_id = ANY(${tx.array(ids, 'TEXT')})
+    `;
+        await tx `
+      DELETE FROM bunqueue_flow_failures
+      WHERE namespace = ${ctx.config.namespace}
+        AND parent_id = ANY(${tx.array(ids, 'TEXT')})
+    `;
+        await tx `
+      DELETE FROM bunqueue_dependencies
+      WHERE namespace = ${ctx.config.namespace}
+        AND job_id = ANY(${tx.array(ids, 'TEXT')})
+    `;
+        await tx `
+      DELETE FROM bunqueue_jobs
+      WHERE namespace = ${ctx.config.namespace}
+        AND id = ANY(${tx.array(ids, 'TEXT')})
+    `;
+        for (const row of removedRows) {
+            const job = decodePostgresJob(row).job;
+            await recordPostgresEvent(tx, ctx, {
+                queue,
+                type: 'removed',
+                jobId: job.id,
+                occurredAt: now,
+                job,
+                state: row.state,
+                error: 'Job TTL expired',
+                removed: true,
+            });
+        }
+        return removedRows.length;
+    });
+}

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

@@ -0,0 +1,17 @@
+import type { TransactionSQL } from 'bun';
+import { type Job, type JobId } from '../../../domain/types/job';
+import { type PostgresContext } from './context';
+export interface PostgresDlqLimitRequest {
+    readonly queue: string;
+    readonly maxEntries: number;
+}
+/** Serialize mutations involving one flow parent across brokers. */
+export declare function lockPostgresFlowParent(tx: TransactionSQL, ctx: PostgresContext, parentId: JobId): Promise<void>;
+/** Acquire a flow-parent batch in canonical order with one database round trip. */
+export declare function lockPostgresFlowParents(tx: TransactionSQL, ctx: PostgresContext, parentIds: readonly JobId[]): Promise<void>;
+/** Lock child attachment, then its current parent, before a terminal row mutation. */
+export declare function lockPostgresJobFlowParent(tx: TransactionSQL, ctx: PostgresContext, childId: JobId): Promise<void>;
+/** Apply a terminal child's configured parent policy in the same transaction. */
+export declare function applyPostgresFlowFailure(tx: TransactionSQL, ctx: PostgresContext, child: Job, errorValue: string | undefined, now: number): Promise<PostgresDlqLimitRequest | null>;
+export declare function clearPostgresParentFlowFailures(tx: TransactionSQL, ctx: PostgresContext, parentId: JobId): Promise<void>;
+export declare function getPostgresFlowFailureValues(ctx: PostgresContext, parentId: JobId, mode: 'ignore' | 'continue'): Promise<Record<string, string>>;

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

@@ -0,0 +1,199 @@
+import { createDlqEntry } from '../../../domain/types/dlq';
+import { MAX_TIMELINE_ENTRIES } from '../../../domain/types/job';
+import { postgresAdvisoryLockName } from './advisoryLocks';
+import { decodePostgresJob, encodePostgresValue } from './codec';
+import { recordPostgresEvent } from './context';
+import { getPostgresQueuePolicies } from './policies';
+import { lockPostgresDependencyCompletions } from './dependencyPromotion';
+const LINKABLE_STATES = [
+    'waiting',
+    'prioritized',
+    'delayed',
+    'waiting-children',
+];
+function failureMode(job) {
+    if (!job.parentId)
+        return null;
+    if (job.failParentOnFailure)
+        return 'fail';
+    if (job.continueParentOnFailure)
+        return 'continue';
+    if (job.ignoreDependencyOnFailure)
+        return 'ignore';
+    if (job.removeDependencyOnFailure)
+        return 'remove';
+    return null;
+}
+function readyState(job, now) {
+    if (job.runAt > now)
+        return 'delayed';
+    return job.priority > 0 ? 'prioritized' : 'waiting';
+}
+async function storeFailureValue(input, mode) {
+    const { tx, ctx, child, error, now } = input;
+    await tx `
+    INSERT INTO bunqueue_flow_failures
+      (namespace, parent_id, child_id, child_queue, mode, error, created_at)
+    VALUES
+      (${ctx.config.namespace}, ${String(child.parentId)}, ${String(child.id)}, ${child.queue},
+       ${mode}, ${error}, ${now})
+    ON CONFLICT (namespace, parent_id, child_id) DO UPDATE SET
+      child_queue = excluded.child_queue,
+      mode = excluded.mode,
+      error = excluded.error,
+      created_at = excluded.created_at
+  `;
+}
+async function unresolvedCount(tx, ctx, parentId) {
+    const [row] = await tx `
+    SELECT COUNT(*)::bigint AS count
+    FROM bunqueue_dependencies AS dependency
+    WHERE dependency.namespace = ${ctx.config.namespace}
+      AND dependency.job_id = ${String(parentId)}
+      AND NOT EXISTS (
+        SELECT 1 FROM bunqueue_completions AS completion
+        WHERE completion.namespace = dependency.namespace
+          AND completion.job_id = dependency.dependency_id
+      )
+  `;
+    return Number(row.count);
+}
+async function failParent(input) {
+    const { tx, ctx, parent, child, error, now } = input;
+    const message = `Child job ${String(child.id)} failed: ${error}`;
+    parent.completedAt = now;
+    if (parent.timeline.length < MAX_TIMELINE_ENTRIES) {
+        parent.timeline.push({ state: 'failed', timestamp: now, error: message });
+    }
+    const { dlq } = await getPostgresQueuePolicies(tx, ctx, parent.queue);
+    const entry = createDlqEntry(parent, "unknown" /* FailureReason.Unknown */, message, dlq, now);
+    await tx `
+    DELETE FROM bunqueue_dependencies
+    WHERE namespace = ${ctx.config.namespace} AND job_id = ${String(parent.id)}
+  `;
+    await tx `
+    DELETE FROM bunqueue_flow_failures
+    WHERE namespace = ${ctx.config.namespace} AND parent_id = ${String(parent.id)}
+  `;
+    await tx `
+    UPDATE bunqueue_jobs
+    SET payload = ${encodePostgresValue(parent)}, state = 'failed', completed_at = ${now},
+        error = ${message}, failure_reason = ${"unknown" /* FailureReason.Unknown */},
+        dlq_entry = ${encodePostgresValue(entry)}, dlq_retry_state = NULL,
+        version = version + 1
+    WHERE namespace = ${ctx.config.namespace} AND id = ${String(parent.id)}
+  `;
+    await recordPostgresEvent(tx, ctx, {
+        queue: parent.queue,
+        type: 'failed',
+        jobId: parent.id,
+        occurredAt: now,
+        job: parent,
+        state: 'failed',
+        error: message,
+        dlqEntry: entry,
+        dlqRetryState: null,
+    });
+    return { queue: parent.queue, maxEntries: dlq.maxEntries };
+}
+async function releaseDependencies(input, mode) {
+    const { tx, ctx, parent, child, now } = input;
+    if (mode === 'ignore' || mode === 'continue') {
+        await storeFailureValue(input, mode);
+    }
+    const released = mode === 'continue' ? [...parent.dependsOn] : [child.id];
+    const remaining = parent.dependsOn.filter((id) => !released.includes(id));
+    await tx `
+    DELETE FROM bunqueue_dependencies
+    WHERE namespace = ${ctx.config.namespace}
+      AND job_id = ${String(parent.id)}
+      AND dependency_id = ANY(${tx.array(released.map(String), 'TEXT')})
+  `;
+    const resolved = (await unresolvedCount(tx, ctx, parent.id)) === 0;
+    const updated = { ...parent, dependsOn: remaining };
+    const state = resolved ? readyState(updated, now) : 'waiting-children';
+    await tx `
+    UPDATE bunqueue_jobs
+    SET payload = ${encodePostgresValue(updated)}, state = ${state}, version = version + 1
+    WHERE namespace = ${ctx.config.namespace} AND id = ${String(parent.id)}
+  `;
+    if (resolved) {
+        await recordPostgresEvent(tx, ctx, {
+            queue: parent.queue,
+            type: 'retried',
+            jobId: parent.id,
+            occurredAt: now,
+            job: updated,
+            state,
+        });
+    }
+}
+/** Serialize mutations involving one flow parent across brokers. */
+export async function lockPostgresFlowParent(tx, ctx, parentId) {
+    await lockPostgresFlowParents(tx, ctx, [parentId]);
+}
+/** Acquire a flow-parent batch in canonical order with one database round trip. */
+export async function lockPostgresFlowParents(tx, ctx, parentIds) {
+    const lockNames = [...new Set(parentIds.map(String))].map((id) => postgresAdvisoryLockName('flow', ctx.config.namespace, id));
+    if (lockNames.length === 0)
+        return;
+    await tx `
+    WITH ordered_ids AS MATERIALIZED (
+      SELECT DISTINCT hashtextextended(lock_name, 0) AS lock_key
+      FROM unnest(${tx.array(lockNames, 'TEXT')}) AS parent(lock_name)
+      ORDER BY lock_key
+    ), locked_ids AS MATERIALIZED (
+      SELECT lock_key, pg_advisory_xact_lock(lock_key) AS acquired
+      FROM ordered_ids
+      ORDER BY lock_key
+    )
+    SELECT COUNT(*) FROM locked_ids
+  `;
+}
+/** Lock child attachment, then its current parent, before a terminal row mutation. */
+export async function lockPostgresJobFlowParent(tx, ctx, childId) {
+    await lockPostgresDependencyCompletions(tx, ctx, [childId]);
+    const [row] = await tx `
+    SELECT parent_id FROM bunqueue_jobs
+    WHERE namespace = ${ctx.config.namespace} AND id = ${String(childId)}
+  `;
+    if (row?.parent_id)
+        await lockPostgresFlowParent(tx, ctx, row.parent_id);
+}
+/** Apply a terminal child's configured parent policy in the same transaction. */
+export async function applyPostgresFlowFailure(tx, ctx, child, errorValue, now) {
+    const mode = failureMode(child);
+    if (!mode || !child.parentId)
+        return null;
+    const rows = await tx `
+    SELECT * FROM bunqueue_jobs
+    WHERE namespace = ${ctx.config.namespace} AND id = ${String(child.parentId)}
+    FOR UPDATE
+  `;
+    const row = rows[0];
+    if (!row || !LINKABLE_STATES.includes(row.state))
+        return null;
+    const parent = decodePostgresJob(row).job;
+    const error = errorValue ?? 'unknown error';
+    const input = { tx, ctx, parent, child, error, now };
+    if (mode === 'fail')
+        return await failParent(input);
+    await releaseDependencies(input, mode);
+    return null;
+}
+export async function clearPostgresParentFlowFailures(tx, ctx, parentId) {
+    await tx `
+    DELETE FROM bunqueue_flow_failures
+    WHERE namespace = ${ctx.config.namespace} AND parent_id = ${String(parentId)}
+  `;
+}
+export async function getPostgresFlowFailureValues(ctx, parentId, mode) {
+    const rows = await ctx.sql `
+    SELECT child_id, child_queue, error
+    FROM bunqueue_flow_failures
+    WHERE namespace = ${ctx.config.namespace}
+      AND parent_id = ${String(parentId)} AND mode = ${mode}
+    ORDER BY created_at, child_id
+  `;
+    return Object.fromEntries(rows.map((row) => [`${row.child_queue}:${row.child_id}`, row.error]));
+}

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

@@ -0,0 +1,15 @@
+import type { TransactionSQL } from 'bun';
+import type { GroupPullOptions } from '../../../domain/types/group';
+import type { PostgresContext } from './context';
+import type { PostgresJobRow } from './types';
+/** Assign durable rotation positions to every pending group lacking one. */
+export declare function ensurePostgresGroupStates(tx: TransactionSQL, ctx: PostgresContext, queue: string, sequence: number): Promise<number>;
+/** Reset fixed windows when they expire or a worker changes the effective defaults. */
+export declare function refreshPostgresGroupRateWindows(tx: TransactionSQL, ctx: PostgresContext, queue: string, options: GroupPullOptions | undefined, now: number): Promise<void>;
+/** Consume group budgets and move the durable round-robin cursor after row locks are secured. */
+export declare function commitPostgresGroupClaims(tx: TransactionSQL, ctx: PostgresContext, input: {
+    queue: string;
+    rows: readonly PostgresJobRow[];
+    options?: GroupPullOptions;
+    sequence: number;
+}): Promise<void>;