bunqueue 2.8.60 → 2.9.2

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

@@ -0,0 +1,153 @@
+import { DEFAULT_DLQ_CONFIG } from '../../../domain/types/dlq';
+import { DEFAULT_STALL_CONFIG } from '../../../domain/types/stall';
+import { claimPostgresCandidates } from './claimBatch';
+import { decodePostgresValue } from './codec';
+import { databaseNow } from './context';
+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,
+        paused: row.paused,
+        rateLimit: row.rate_limit,
+        rateDurationMs: row.rate_duration_ms === null ? null : Number(row.rate_duration_ms),
+        rateWindowStartedAt: row.rate_window_started_at === null ? null : Number(row.rate_window_started_at),
+        rateExpiresAt: row.rate_expires_at === null ? null : Number(row.rate_expires_at),
+        rateCount: row.rate_count,
+        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,
+                 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,
+                 group_sequence
+          FROM bunqueue_queue_state
+          WHERE namespace = ${ctx.config.namespace} AND queue = ${queue}
+          FOR SHARE
+        `;
+    let rows = await select();
+    if (rows.length === 0) {
+        await tx `
+      INSERT INTO bunqueue_queue_state (namespace, queue)
+      VALUES (${ctx.config.namespace}, ${queue})
+      ON CONFLICT DO NOTHING
+    `;
+        rows = await select();
+    }
+    const [row] = rows;
+    if (!row)
+        throw new Error(`Missing PostgreSQL queue state for ${queue}`);
+    return toQueueState(row);
+}
+async function refreshRateWindow(tx, ctx, state, now) {
+    if (state.rateLimit === null)
+        return state;
+    if (state.rateExpiresAt !== null && state.rateExpiresAt <= now) {
+        await tx `
+      UPDATE bunqueue_queue_state
+      SET rate_limit = NULL, rate_duration_ms = NULL, rate_window_started_at = NULL,
+          rate_expires_at = NULL, rate_count = 0
+      WHERE namespace = ${ctx.config.namespace} AND queue = ${state.queue}
+    `;
+        return {
+            ...state,
+            rateLimit: null,
+            rateDurationMs: null,
+            rateWindowStartedAt: null,
+            rateExpiresAt: null,
+            rateCount: 0,
+        };
+    }
+    const duration = state.rateDurationMs ?? 1000;
+    if (state.rateWindowStartedAt !== null && now < state.rateWindowStartedAt + duration) {
+        return state;
+    }
+    await tx `
+    UPDATE bunqueue_queue_state
+    SET rate_window_started_at = ${now}, rate_count = 0
+    WHERE namespace = ${ctx.config.namespace} AND queue = ${state.queue}
+  `;
+    return { ...state, rateWindowStartedAt: now, rateCount: 0 };
+}
+async function activeCount(tx, ctx, queue, now) {
+    const [row] = await tx `
+    SELECT COUNT(*)::bigint AS count
+    FROM bunqueue_jobs
+    WHERE namespace = ${ctx.config.namespace}
+      AND queue = ${queue}
+      AND state = 'active'
+      AND lease_until > ${now}
+  `;
+    return Number(row.count);
+}
+export async function claimPostgresJobs(ctx, input) {
+    const { queue, count, owner, leaseDurationMs, groupOptions } = input;
+    if (count <= 0)
+        return [];
+    await expirePendingPostgresJobs(ctx, queue);
+    const claimWithLock = async (exclusive) => await runPostgresTransactionWithRetry(ctx, async (tx) => {
+        await lockPostgresBrokerSession(tx, ctx);
+        const now = await databaseNow(tx);
+        let state = await lockQueueState(tx, ctx, queue, exclusive);
+        if (!exclusive && (state.rateLimit !== null || state.concurrencyLimit !== null)) {
+            return { claimed: [], retryExclusive: true };
+        }
+        if (exclusive)
+            state = await refreshRateWindow(tx, ctx, state, now);
+        if (state.paused)
+            return { claimed: [], retryExclusive: false };
+        const active = state.concurrencyLimit === null ? 0 : await activeCount(tx, ctx, queue, now);
+        const concurrencyCapacity = state.concurrencyLimit === null ? count : Math.max(0, state.concurrencyLimit - active);
+        const rateCapacity = state.rateLimit === null ? count : Math.max(0, state.rateLimit - state.rateCount);
+        const capacity = Math.min(count, concurrencyCapacity, rateCapacity);
+        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 `
+          UPDATE bunqueue_queue_state
+          SET rate_count = rate_count + ${claimed.length}
+          WHERE namespace = ${ctx.config.namespace} AND queue = ${queue}
+        `;
+        }
+        return { claimed, retryExclusive: false };
+    });
+    const sharedAttempt = await claimWithLock(false);
+    if (!sharedAttempt.retryExclusive)
+        return sharedAttempt.claimed;
+    return (await claimWithLock(true)).claimed;
+}

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

@@ -0,0 +1,26 @@
+import type { CronJob } from '../../../domain/types/cron';
+import type { JobLogEntry, Worker } from '../../../domain/types/worker';
+import type { PostgresContext } from './context';
+import type { PostgresCompletionResult, PostgresJobState, PostgresQueueState, PostgresStoredJob } from './types';
+export interface PostgresCloudQueueCount {
+    readonly queue: string;
+    readonly state: PostgresJobState;
+    readonly count: number;
+}
+export interface PostgresCloudQueueTotal {
+    readonly queue: string;
+    readonly metricType: 'completed' | 'failed';
+    readonly count: bigint;
+}
+export interface PostgresCloudReadModel {
+    readonly jobs: readonly PostgresStoredJob[];
+    readonly queueStates: readonly PostgresQueueState[];
+    readonly counts: readonly PostgresCloudQueueCount[];
+    readonly totals: readonly PostgresCloudQueueTotal[];
+    readonly results: readonly PostgresCompletionResult[];
+    readonly logs: ReadonlyMap<string, readonly JobLogEntry[]>;
+    readonly workers: readonly Worker[];
+    readonly crons: readonly CronJob[];
+}
+/** Read one coherent, bounded Cloud view from the durable PostgreSQL source. */
+export declare function loadPostgresCloudReadModel(ctx: PostgresContext): Promise<PostgresCloudReadModel>;

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

@@ -0,0 +1,123 @@
+import { decodePostgresJob, decodePostgresValue } from './codec';
+import { decodePostgresQueueState } from './control';
+import { decodePostgresCron } from './crons';
+import { jobId } from '../../../domain/types/job';
+/** Read one coherent, bounded Cloud view from the durable PostgreSQL source. */
+export async function loadPostgresCloudReadModel(ctx) {
+    return await ctx.sql.begin('isolation level repeatable read read only', async (tx) => {
+        const [jobRows, stateRows, countRows, totalRows, resultRows, workerRows, cronRows] = await Promise.all([
+            tx `
+          WITH ranked_live AS MATERIALIZED (
+            SELECT job.*, row_number() OVER (
+              PARTITION BY queue, state ORDER BY created_at, id
+            ) AS cloud_rank
+            FROM bunqueue_jobs AS job
+            WHERE namespace = ${ctx.config.namespace} AND state <> 'completed'
+          ), retained_completed AS MATERIALIZED (
+            SELECT job.*, 1::bigint AS cloud_rank
+            FROM bunqueue_jobs AS job
+            WHERE namespace = ${ctx.config.namespace} AND state = 'completed'
+            ORDER BY completed_at DESC NULLS LAST, id DESC
+            LIMIT ${ctx.config.maxCompletedJobs}
+          )
+          SELECT cloud_jobs.*
+          FROM (
+            SELECT * FROM ranked_live WHERE cloud_rank <= 1000
+            UNION ALL SELECT * FROM retained_completed
+          ) AS cloud_jobs
+          ORDER BY created_at, id
+        `,
+            tx `
+          SELECT queue, paused, rate_limit, rate_duration_ms, rate_window_started_at,
+                 rate_expires_at, rate_count, concurrency_limit, stall_config, dlq_config
+          FROM bunqueue_queue_state
+          WHERE namespace = ${ctx.config.namespace}
+          ORDER BY queue
+        `,
+            tx `
+          SELECT queue, state, COUNT(*)::bigint AS count
+          FROM bunqueue_jobs
+          WHERE namespace = ${ctx.config.namespace}
+          GROUP BY queue, state ORDER BY queue, state
+        `,
+            tx `
+          SELECT queue, metric_type, total_count
+          FROM bunqueue_metric_totals
+          WHERE namespace = ${ctx.config.namespace}
+          ORDER BY queue, metric_type
+        `,
+            tx `
+          SELECT job_id, queue, result
+          FROM bunqueue_completions
+          WHERE namespace = ${ctx.config.namespace}
+          ORDER BY completed_at DESC, job_id DESC
+          LIMIT ${ctx.config.maxJobResults}
+        `,
+            tx `
+          SELECT id, payload, last_seen FROM bunqueue_workers
+          WHERE namespace = ${ctx.config.namespace}
+          ORDER BY id
+        `,
+            tx `
+          SELECT name, payload, next_run, executions, max_limit
+          FROM bunqueue_crons
+          WHERE namespace = ${ctx.config.namespace}
+          ORDER BY name
+        `,
+        ]);
+        const ids = jobRows.map((row) => row.id);
+        const logRows = ids.length === 0
+            ? []
+            : await tx `
+            SELECT job_id, timestamp, level, message
+            FROM bunqueue_job_logs
+            WHERE namespace = ${ctx.config.namespace}
+              AND job_id = ANY(${tx.array(ids, 'TEXT')})
+            ORDER BY job_id, id
+          `;
+        return decodeCloudReadModel({
+            jobRows,
+            stateRows,
+            countRows,
+            totalRows,
+            resultRows,
+            logRows,
+            workerRows,
+            cronRows,
+        });
+    });
+}
+function decodeCloudReadModel(rows) {
+    const { jobRows, stateRows, countRows, totalRows, resultRows, logRows, workerRows, cronRows } = rows;
+    const logs = new Map();
+    for (const { job_id, timestamp, level, message } of logRows) {
+        const entries = logs.get(job_id) ?? [];
+        entries.push({ timestamp: Number(timestamp), level, message });
+        logs.set(job_id, entries);
+    }
+    return {
+        jobs: jobRows.map(decodePostgresJob),
+        queueStates: stateRows.map((row) => decodePostgresQueueState(row.queue, row)),
+        counts: countRows.map((row) => ({ ...row, count: Number(row.count) })),
+        totals: totalRows.map((row) => ({
+            queue: row.queue,
+            metricType: row.metric_type,
+            count: BigInt(row.total_count),
+        })),
+        results: resultRows.map((row) => ({
+            jobId: jobId(row.job_id),
+            queue: row.queue,
+            result: decodePostgresValue(row.result, null, `postgresCloudResult:${row.job_id}`),
+            pinned: false,
+        })),
+        logs,
+        workers: workerRows.map((row) => {
+            const worker = decodePostgresValue(row.payload, null, `postgresCloudWorker:${row.id}`);
+            if (!worker)
+                throw new Error(`Corrupt PostgreSQL worker payload for ${row.id}`);
+            worker.lastSeen = Number(row.last_seen);
+            return worker;
+        }),
+        crons: cronRows.map(decodePostgresCron),
+    };
+}

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

@@ -0,0 +1,30 @@
+import { type DlqEntry, type DlqRetryState } from '../../../domain/types/dlq';
+import type { Job, JobId } from '../../../domain/types/job';
+import type { PostgresJobRow, PostgresStoredJob, PostgresStoreEvent, PostgresJobState } from './types';
+export declare function numeric(value: number | string | bigint | null): number | null;
+export declare function encodePostgresValue(value: unknown): Uint8Array;
+export declare function postgresByteaBase64(value: Uint8Array): string;
+export declare function decodePostgresValue<T>(value: Uint8Array | null, fallback: T, context: string): T;
+export declare function decodePostgresJob(row: PostgresJobRow): PostgresStoredJob;
+interface EventPayload {
+    job?: Job;
+    invalidationQueue?: string;
+    state?: PostgresJobState;
+    result?: unknown;
+    error?: string;
+    removed?: boolean;
+    dlqEntry?: DlqEntry | null;
+    dlqRetryState?: DlqRetryState | null;
+}
+export declare function decodePostgresEvent(row: {
+    id: number | string | bigint;
+    queue: string;
+    event_type: string;
+    job_id: string;
+    occurred_at: number | string | bigint;
+    payload: Uint8Array | null;
+}): PostgresStoreEvent;
+export declare function postgresStateForJob(job: Job, dependenciesSatisfied: boolean, now?: number): Extract<PostgresJobState, 'waiting' | 'prioritized' | 'delayed' | 'waiting-children'>;
+export declare function eventPayload(input: EventPayload): Uint8Array;
+export declare function asJobId(value: string): JobId;
+export {};

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

@@ -0,0 +1,82 @@
+import { setDlqRetryState } from '../../../domain/types/dlq';
+import { Buffer } from 'node:buffer';
+import { jobId } from '../../../domain/types/job';
+import { pack, unpack } from '../sqliteSerializer';
+export function numeric(value) {
+    if (value === null)
+        return null;
+    const converted = Number(value);
+    if (!Number.isSafeInteger(converted)) {
+        throw new Error(`PostgreSQL integer is outside the JavaScript safe range: ${String(value)}`);
+    }
+    return converted;
+}
+export function encodePostgresValue(value) {
+    return pack(value);
+}
+export function postgresByteaBase64(value) {
+    return Buffer.from(value).toString('base64');
+}
+export function decodePostgresValue(value, fallback, context) {
+    return value ? unpack(value, fallback, context) : fallback;
+}
+export function decodePostgresJob(row) {
+    const job = decodePostgresValue(row.payload, null, `postgresJob:${row.id}`);
+    if (!job)
+        throw new Error(`Corrupt PostgreSQL payload for job ${row.id}`);
+    const dlqRetryState = decodePostgresValue(row.dlq_retry_state, null, `postgresDlqRetry:${row.id}`);
+    const normalizedJob = { ...job, id: jobId(String(job.id)) };
+    setDlqRetryState(normalizedJob, dlqRetryState);
+    return {
+        job: normalizedJob,
+        state: row.state,
+        result: decodePostgresValue(row.result, null, `postgresResult:${row.id}`),
+        error: row.error,
+        dlqEntry: decodePostgresValue(row.dlq_entry, null, `postgresDlq:${row.id}`),
+        dlqRetryState,
+        token: row.lease_token,
+        leaseOwner: row.lease_owner,
+        leaseBrokerId: row.lease_broker_id,
+        leaseUntil: numeric(row.lease_until),
+        leaseRenewals: row.lease_renewals,
+        version: numeric(row.version) ?? 0,
+    };
+}
+export function decodePostgresEvent(row) {
+    const payload = decodePostgresValue(row.payload, {}, `postgresEvent:${row.id}`);
+    const dlqEntry = payload.dlqEntry
+        ? {
+            ...payload.dlqEntry,
+            job: { ...payload.dlqEntry.job, id: jobId(String(payload.dlqEntry.job.id)) },
+        }
+        : payload.dlqEntry;
+    return {
+        id: numeric(row.id) ?? 0,
+        queue: payload.invalidationQueue ?? row.queue,
+        type: row.event_type,
+        jobId: jobId(row.job_id),
+        occurredAt: numeric(row.occurred_at) ?? 0,
+        job: payload.job ? { ...payload.job, id: jobId(String(payload.job.id)) } : null,
+        state: payload.state ?? null,
+        ...(Object.hasOwn(payload, 'result') && { result: payload.result }),
+        ...(payload.error !== undefined && { error: payload.error }),
+        ...(payload.removed !== undefined && { removed: payload.removed }),
+        ...(Object.hasOwn(payload, 'dlqEntry') && { dlqEntry }),
+        ...(Object.hasOwn(payload, 'dlqRetryState') && {
+            dlqRetryState: payload.dlqRetryState,
+        }),
+    };
+}
+export function postgresStateForJob(job, dependenciesSatisfied, now = Date.now()) {
+    if (!dependenciesSatisfied)
+        return 'waiting-children';
+    if (job.runAt > now)
+        return 'delayed';
+    return job.priority > 0 ? 'prioritized' : 'waiting';
+}
+export function eventPayload(input) {
+    return encodePostgresValue(input);
+}
+export function asJobId(value) {
+    return jobId(value);
+}

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

@@ -0,0 +1,11 @@
+import type { TransactionSQL } from 'bun';
+import type { Job } from '../../../domain/types/job';
+import type { PostgresContext } from './context';
+interface CompletionEventInput {
+    readonly job: Job;
+    readonly result: unknown;
+    readonly removed: boolean;
+}
+/** Persist one completion event per job while amortizing queue-level bookkeeping. */
+export declare function recordPostgresCompletionEvents(tx: TransactionSQL, ctx: PostgresContext, inputs: readonly CompletionEventInput[], now: number): Promise<void>;
+export {};

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

@@ -0,0 +1,21 @@
+import { recordPostgresJobEvents } from './batchEvents';
+import { recordPostgresMetricAdditions } from './metricWrites';
+async function updateMetrics(tx, ctx, inputs, now) {
+    const counts = new Map();
+    for (const input of inputs)
+        counts.set(input.job.queue, (counts.get(input.job.queue) ?? 0) + 1);
+    await recordPostgresMetricAdditions(tx, ctx, 'completed', [...counts].map(([queue, count]) => ({ queue, count })), now);
+}
+/** Persist one completion event per job while amortizing queue-level bookkeeping. */
+export async function recordPostgresCompletionEvents(tx, ctx, inputs, now) {
+    if (inputs.length === 0)
+        return;
+    await recordPostgresJobEvents(tx, ctx, inputs.map((input) => ({
+        job: input.job,
+        type: 'completed',
+        state: 'completed',
+        result: input.result,
+        removed: input.removed,
+    })), now);
+    await updateMetrics(tx, ctx, inputs, now);
+}

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

@@ -0,0 +1,11 @@
+import type { TransactionSQL } from 'bun';
+import { type JobId } from '../../../domain/types/job';
+import { type PostgresContext } from './context';
+/** Reject retirement while any non-terminal consumer still owns the old generation. */
+export declare function assertNoLivePostgresCompletionConsumers(tx: TransactionSQL, ctx: PostgresContext, ids: readonly JobId[], deletingConsumerIds?: readonly JobId[]): Promise<void>;
+/** Remove completion evidence for IDs that are about to start a new generation. */
+export declare function retirePostgresCompletionGenerations(tx: TransactionSQL, ctx: PostgresContext, ids: readonly JobId[], deletingConsumerIds?: readonly JobId[]): Promise<string[]>;
+/** Delete queue-owned completion-only rows inside an already serialized obliterate. */
+export declare function deletePostgresQueueCompletions(tx: TransactionSQL, ctx: PostgresContext, queue: string): Promise<JobId[]>;
+/** Bound unreferenced removeOnComplete tombstones without pruning live dependency evidence. */
+export declare function prunePostgresCompletionTombstones(ctx: PostgresContext): Promise<number>;

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

@@ -0,0 +1,145 @@
+import { jobId } from '../../../domain/types/job';
+import { postgresAdvisoryLockName } from './advisoryLocks';
+import { databaseNow, recordPostgresEvent } from './context';
+import { lockPostgresDependencyCompletions } from './dependencyPromotion';
+const LIVE_CONSUMER_STATES = [
+    'waiting',
+    'prioritized',
+    'delayed',
+    'waiting-children',
+    'active',
+];
+const COMPLETION_PRUNE_BATCH_SIZE = 1000;
+function uniqueIds(ids) {
+    return [...new Set(ids.map(String))].sort();
+}
+/** Reject retirement while any non-terminal consumer still owns the old generation. */
+export async function assertNoLivePostgresCompletionConsumers(tx, ctx, ids, deletingConsumerIds = []) {
+    const candidates = uniqueIds(ids);
+    if (candidates.length === 0)
+        return;
+    const deleting = uniqueIds(deletingConsumerIds);
+    const rows = await tx `
+    SELECT dependency.dependency_id
+    FROM bunqueue_dependencies AS dependency
+    JOIN bunqueue_jobs AS consumer
+      ON consumer.namespace = dependency.namespace AND consumer.id = dependency.job_id
+    WHERE dependency.namespace = ${ctx.config.namespace}
+      AND dependency.dependency_id = ANY(${tx.array(candidates, 'TEXT')})
+      AND consumer.state = ANY(${tx.array([...LIVE_CONSUMER_STATES], 'TEXT')})
+      AND (
+        ${deleting.length} = 0
+        OR consumer.id <> ALL(${tx.array(deleting, 'TEXT')})
+      )
+    ORDER BY dependency.dependency_id, consumer.id
+    LIMIT 1
+  `;
+    if (rows[0]) {
+        throw new Error(`Custom ID ${rows[0].dependency_id} still has unresolved dependency consumers`);
+    }
+}
+/** Remove completion evidence for IDs that are about to start a new generation. */
+export async function retirePostgresCompletionGenerations(tx, ctx, ids, deletingConsumerIds = []) {
+    const candidates = uniqueIds(ids);
+    if (candidates.length === 0)
+        return [];
+    const existing = await tx `
+    SELECT job_id FROM bunqueue_completions
+    WHERE namespace = ${ctx.config.namespace}
+      AND job_id = ANY(${tx.array(candidates, 'TEXT')})
+    ORDER BY job_id
+  `;
+    if (existing.length === 0)
+        return [];
+    await assertNoLivePostgresCompletionConsumers(tx, ctx, existing.map((row) => jobId(row.job_id)), deletingConsumerIds);
+    const rows = await tx `
+    DELETE FROM bunqueue_completions
+    WHERE namespace = ${ctx.config.namespace}
+      AND job_id = ANY(${tx.array(existing.map((row) => row.job_id), 'TEXT')})
+    RETURNING job_id
+  `;
+    return rows.map((row) => row.job_id);
+}
+/** Delete queue-owned completion-only rows inside an already serialized obliterate. */
+export async function deletePostgresQueueCompletions(tx, ctx, queue) {
+    const rows = await tx `
+    DELETE FROM bunqueue_completions
+    WHERE namespace = ${ctx.config.namespace} AND queue = ${queue}
+    RETURNING job_id
+  `;
+    return rows.map((row) => jobId(row.job_id));
+}
+async function prunePostgresCompletionTombstoneBatch(ctx) {
+    const lockName = postgresAdvisoryLockName('completion-retention', ctx.config.namespace);
+    return await ctx.sql.begin(async (tx) => {
+        await tx `
+      SELECT pg_advisory_xact_lock(hashtextextended(${lockName}, 0))
+    `;
+        const candidates = await tx `
+      SELECT completion.job_id
+      FROM bunqueue_completions AS completion
+      WHERE completion.namespace = ${ctx.config.namespace}
+        AND NOT EXISTS (
+          SELECT 1 FROM bunqueue_jobs AS retained
+          WHERE retained.namespace = completion.namespace
+            AND retained.id = completion.job_id
+        )
+        AND NOT EXISTS (
+          SELECT 1
+          FROM bunqueue_dependencies AS dependency
+          JOIN bunqueue_jobs AS consumer
+            ON consumer.namespace = dependency.namespace AND consumer.id = dependency.job_id
+          WHERE dependency.namespace = completion.namespace
+            AND dependency.dependency_id = completion.job_id
+            AND consumer.state = ANY(${tx.array([...LIVE_CONSUMER_STATES], 'TEXT')})
+      )
+      ORDER BY completion.completed_at DESC, completion.job_id DESC
+      OFFSET ${ctx.config.maxCompletedJobs}
+      LIMIT ${COMPLETION_PRUNE_BATCH_SIZE}
+    `;
+        const ids = candidates.map((row) => jobId(row.job_id));
+        if (ids.length === 0)
+            return { selected: 0, removed: 0 };
+        await lockPostgresDependencyCompletions(tx, ctx, ids);
+        const removed = await tx `
+      DELETE FROM bunqueue_completions AS completion
+      WHERE completion.namespace = ${ctx.config.namespace}
+        AND completion.job_id = ANY(${tx.array(ids.map(String), 'TEXT')})
+        AND NOT EXISTS (
+          SELECT 1 FROM bunqueue_jobs AS retained
+          WHERE retained.namespace = completion.namespace
+            AND retained.id = completion.job_id
+        )
+        AND NOT EXISTS (
+          SELECT 1
+          FROM bunqueue_dependencies AS dependency
+          JOIN bunqueue_jobs AS consumer
+            ON consumer.namespace = dependency.namespace AND consumer.id = dependency.job_id
+          WHERE dependency.namespace = completion.namespace
+            AND dependency.dependency_id = completion.job_id
+            AND consumer.state = ANY(${tx.array([...LIVE_CONSUMER_STATES], 'TEXT')})
+        )
+      RETURNING completion.job_id, completion.queue
+    `;
+        const now = await databaseNow(tx);
+        for (const queue of [...new Set(removed.map((row) => row.queue))].sort()) {
+            await recordPostgresEvent(tx, ctx, {
+                queue,
+                type: 'queue-completions-pruned',
+                jobId: jobId(`__queue__:${queue}`),
+                occurredAt: now,
+            });
+        }
+        return { selected: ids.length, removed: removed.length };
+    });
+}
+/** Bound unreferenced removeOnComplete tombstones without pruning live dependency evidence. */
+export async function prunePostgresCompletionTombstones(ctx) {
+    let removed = 0;
+    while (true) {
+        const batch = await prunePostgresCompletionTombstoneBatch(ctx);
+        removed += batch.removed;
+        if (batch.selected === 0)
+            return removed;
+    }
+}

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

@@ -0,0 +1,4 @@
+import { type JobId } from '../../../domain/types/job';
+import { type PostgresContext } from './context';
+import type { PostgresTransitionResult } from './types';
+export declare function completePostgresJob(ctx: PostgresContext, id: JobId, token: string, result: unknown, removeOnComplete?: boolean): Promise<PostgresTransitionResult>;