bunqueue 2.8.60 → 2.9.0

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

@@ -0,0 +1,111 @@
+import { MAX_TIMELINE_ENTRIES } from '../../../domain/types/job';
+import { decodePostgresJob, encodePostgresValue } from './codec';
+import { databaseNow, recordPostgresEvent } from './context';
+import { lockPostgresDestructionCandidates, partitionPostgresDestructionCandidates, } from './dependencyDestruction';
+async function lockJob(tx, ctx, id) {
+    const rows = await tx `
+    SELECT * FROM bunqueue_jobs
+    WHERE namespace = ${ctx.config.namespace} AND id = ${String(id)}
+    FOR UPDATE
+  `;
+    return rows[0] ?? null;
+}
+function pendingState(job, now) {
+    if (job.dependsOn.length > 0)
+        return 'waiting-children';
+    if (job.runAt > now)
+        return 'delayed';
+    return job.priority > 0 ? 'prioritized' : 'waiting';
+}
+export async function removePostgresJob(ctx, id, token) {
+    return await ctx.sql.begin(async (tx) => {
+        await lockPostgresDestructionCandidates(tx, ctx, [id]);
+        const row = await lockJob(tx, ctx, id);
+        if (!row || (row.state === 'active' && row.lease_token !== token))
+            return false;
+        const { protectedIds } = await partitionPostgresDestructionCandidates(tx, ctx, [id], [id]);
+        if (protectedIds.length > 0)
+            return false;
+        const job = decodePostgresJob(row).job;
+        const now = await databaseNow(tx);
+        await tx `
+      DELETE FROM bunqueue_job_logs
+      WHERE namespace = ${ctx.config.namespace} AND job_id = ${String(id)}
+    `;
+        await tx `
+      DELETE FROM bunqueue_flow_failures
+      WHERE namespace = ${ctx.config.namespace} AND parent_id = ${String(id)}
+    `;
+        await tx `
+      DELETE FROM bunqueue_dependencies
+      WHERE namespace = ${ctx.config.namespace} AND job_id = ${String(id)}
+    `;
+        await tx `
+      DELETE FROM bunqueue_completions
+      WHERE namespace = ${ctx.config.namespace} AND job_id = ${String(id)}
+    `;
+        await tx `
+      DELETE FROM bunqueue_jobs
+      WHERE namespace = ${ctx.config.namespace} AND id = ${String(id)}
+    `;
+        await recordPostgresEvent(tx, ctx, {
+            queue: job.queue,
+            type: 'removed',
+            jobId: job.id,
+            occurredAt: now,
+            job,
+            state: row.state,
+        });
+        return true;
+    });
+}
+export async function retryPostgresTerminalJob(ctx, id, requestedTimestamp) {
+    return await ctx.sql.begin(async (tx) => {
+        await lockPostgresDestructionCandidates(tx, ctx, [id]);
+        const timestamp = requestedTimestamp ?? (await databaseNow(tx));
+        const row = await lockJob(tx, ctx, id);
+        if (!row || (row.state !== 'failed' && row.state !== 'completed'))
+            return false;
+        if (row.state === 'completed') {
+            const { protectedIds } = await partitionPostgresDestructionCandidates(tx, ctx, [id], [id]);
+            if (protectedIds.length > 0)
+                return false;
+        }
+        const job = decodePostgresJob(row).job;
+        job.attempts = 0;
+        job.stallCount = 0;
+        job.completedAt = null;
+        job.startedAt = null;
+        job.runAt = timestamp;
+        job.progress = 0;
+        job.progressMessage = null;
+        job.lastHeartbeat = timestamp;
+        if (job.timeline.length < MAX_TIMELINE_ENTRIES) {
+            job.timeline.push({ state: 'waiting', timestamp });
+        }
+        const state = pendingState(job, timestamp);
+        await tx `
+      DELETE FROM bunqueue_completions
+      WHERE namespace = ${ctx.config.namespace} AND job_id = ${String(id)}
+    `;
+        await tx `
+      UPDATE bunqueue_jobs
+      SET payload = ${encodePostgresValue(job)}, state = ${state}, run_at = ${timestamp},
+          started_at = NULL, completed_at = NULL, result = NULL, dlq_entry = NULL,
+          error = NULL, failure_reason = NULL, lease_owner = NULL, lease_token = NULL,
+          lease_broker_id = NULL, lease_broker_session_id = NULL,
+          lease_until = NULL, unique_key = NULL,
+          unique_expires_at = NULL, dlq_retry_state = NULL, version = version + 1
+      WHERE namespace = ${ctx.config.namespace} AND id = ${String(id)}
+    `;
+        await recordPostgresEvent(tx, ctx, {
+            queue: job.queue,
+            type: 'retried',
+            jobId: job.id,
+            occurredAt: timestamp,
+            job,
+            state,
+        });
+        return true;
+    });
+}

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

@@ -0,0 +1,13 @@
+import type { TransactionSQL } from 'bun';
+import { type JobId } from '../../../domain/types/job';
+import { type PostgresContext } from './context';
+export declare function recordPostgresDlqInvalidation(tx: TransactionSQL, ctx: PostgresContext, queue: string, occurredAt: number): Promise<void>;
+/** Enforce the same oldest-first bounded DLQ policy as the SQLite engine. */
+export declare function enforcePostgresDlqLimit(ctx: PostgresContext, queue: string, maxEntries: number): Promise<JobId[]>;
+export declare function enforcePostgresDlqLimitInTransaction(tx: TransactionSQL, ctx: PostgresContext, queue: string, maxEntries: number): Promise<JobId[]>;
+export interface PostgresDlqMaintenanceResult {
+    readonly retried: number;
+    readonly purged: number;
+}
+/** Claim due DLQ work with row locks so concurrent brokers execute it once. */
+export declare function maintainPostgresDlq(ctx: PostgresContext, limit?: number): Promise<PostgresDlqMaintenanceResult>;

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

@@ -0,0 +1,184 @@
+import { canAutoRetry, getDlqRetryState, isDlqEntryExpired, retainDlqRetryState, scheduleNextRetry, } from '../../../domain/types/dlq';
+import { MAX_TIMELINE_ENTRIES, jobId } from '../../../domain/types/job';
+import { decodePostgresJob, encodePostgresValue } from './codec';
+import { databaseNow, recordPostgresEvent } from './context';
+import { lockPostgresDestructionCandidates, partitionPostgresDestructionCandidates, } from './dependencyDestruction';
+import { postgresDependenciesSatisfied } from './dependencyPromotion';
+import { discoverPostgresDlqRetryPlan, lockPostgresDlqRetryBatch } from './dlqRetryPlan';
+export async function recordPostgresDlqInvalidation(tx, ctx, queue, occurredAt) {
+    await recordPostgresEvent(tx, ctx, {
+        queue,
+        type: 'queue-dlq-pruned',
+        jobId: jobId(`__queue__:${queue}`),
+        occurredAt,
+    });
+}
+async function deleteTerminalRows(tx, ctx, rows, occurredAt) {
+    if (rows.length === 0)
+        return;
+    const ids = rows.map((row) => row.id);
+    const values = tx.array([...ids], 'TEXT');
+    await tx `
+    DELETE FROM bunqueue_job_logs
+    WHERE namespace = ${ctx.config.namespace} AND job_id = ANY(${values})
+  `;
+    await tx `
+    DELETE FROM bunqueue_flow_failures
+    WHERE namespace = ${ctx.config.namespace} AND parent_id = ANY(${values})
+  `;
+    await tx `
+    DELETE FROM bunqueue_dependencies
+    WHERE namespace = ${ctx.config.namespace} AND job_id = ANY(${values})
+  `;
+    await tx `
+    DELETE FROM bunqueue_jobs
+    WHERE namespace = ${ctx.config.namespace} AND id = ANY(${values})
+  `;
+    const queues = [...new Set(rows.map((row) => row.queue))].sort();
+    for (const queue of queues) {
+        await recordPostgresDlqInvalidation(tx, ctx, queue, occurredAt);
+    }
+}
+/** Enforce the same oldest-first bounded DLQ policy as the SQLite engine. */
+export async function enforcePostgresDlqLimit(ctx, queue, maxEntries) {
+    return await ctx.sql.begin((tx) => enforcePostgresDlqLimitInTransaction(tx, ctx, queue, maxEntries));
+}
+export async function enforcePostgresDlqLimitInTransaction(tx, ctx, queue, maxEntries) {
+    const retained = Math.max(1, maxEntries);
+    const candidates = await tx `
+    SELECT id FROM bunqueue_jobs
+    WHERE namespace = ${ctx.config.namespace} AND queue = ${queue} AND state = 'failed'
+    ORDER BY completed_at DESC NULLS LAST, id DESC
+    OFFSET ${retained}
+  `;
+    const candidateIds = candidates.map((row) => jobId(row.id));
+    if (candidateIds.length === 0)
+        return [];
+    await lockPostgresDestructionCandidates(tx, ctx, candidateIds);
+    const rows = await tx `
+    WITH ranked AS (
+      SELECT id, queue,
+             ROW_NUMBER() OVER (ORDER BY completed_at DESC NULLS LAST, id DESC) AS position
+      FROM bunqueue_jobs
+      WHERE namespace = ${ctx.config.namespace} AND queue = ${queue} AND state = 'failed'
+    )
+    SELECT id, queue FROM ranked
+    WHERE position > ${retained}
+      AND id = ANY(${tx.array(candidateIds.map(String), 'TEXT')})
+    ORDER BY 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 removed = rows.filter((row) => deletable.has(row.id));
+    await deleteTerminalRows(tx, ctx, removed, await databaseNow(tx));
+    return removed.map((row) => jobId(row.id));
+}
+function pendingState(job, resolved, now) {
+    if (!resolved)
+        return 'waiting-children';
+    if (job.runAt > now)
+        return 'delayed';
+    return job.priority > 0 ? 'prioritized' : 'waiting';
+}
+async function retryEntry(tx, ctx, row, options) {
+    const { config, now, dependencyIds } = options;
+    const stored = decodePostgresJob(row);
+    const entry = stored.dlqEntry;
+    if (!entry)
+        return;
+    scheduleNextRetry(entry, config);
+    const job = stored.job;
+    retainDlqRetryState(job, entry);
+    job.attempts = 0;
+    job.runAt = now;
+    job.startedAt = null;
+    job.completedAt = null;
+    job.stallCount = 0;
+    job.lastHeartbeat = now;
+    if (job.timeline.length < MAX_TIMELINE_ENTRIES) {
+        job.timeline.push({ state: 'waiting', timestamp: now });
+    }
+    const state = pendingState(job, await postgresDependenciesSatisfied(tx, ctx, dependencyIds), now);
+    await tx `
+    UPDATE bunqueue_jobs
+    SET payload = ${encodePostgresValue(job)}, state = ${state}, attempts = 0,
+        run_at = ${now}, started_at = NULL, completed_at = NULL, result = NULL,
+        dlq_entry = NULL, dlq_retry_state = ${encodePostgresValue(getDlqRetryState(job))},
+        error = NULL, failure_reason = NULL, lease_owner = NULL, lease_broker_id = NULL,
+        lease_broker_session_id = NULL,
+        lease_token = NULL, lease_until = NULL, unique_key = NULL,
+        unique_expires_at = NULL, version = version + 1
+    WHERE namespace = ${ctx.config.namespace} AND id = ${row.id}
+  `;
+    await recordPostgresEvent(tx, ctx, {
+        queue: job.queue,
+        type: 'retried',
+        jobId: job.id,
+        occurredAt: now,
+        job,
+        state,
+        dlqEntry: null,
+        dlqRetryState: getDlqRetryState(job),
+    });
+}
+async function purgeExpiredEntries(ctx, ids, requestedNow) {
+    if (ids.length === 0)
+        return 0;
+    return await ctx.sql.begin(async (tx) => {
+        await lockPostgresDestructionCandidates(tx, ctx, ids);
+        const rows = await tx `
+      SELECT * FROM bunqueue_jobs
+      WHERE namespace = ${ctx.config.namespace}
+        AND state = 'failed' AND dlq_entry IS NOT NULL
+        AND id = ANY(${tx.array(ids.map(String), 'TEXT')})
+      ORDER BY id
+    `;
+        const expired = rows.filter((row) => {
+            const entry = decodePostgresJob(row).dlqEntry;
+            return entry !== null && isDlqEntryExpired(entry, requestedNow);
+        });
+        const plannedIds = expired.map((row) => jobId(row.id));
+        const { deletableIds } = await partitionPostgresDestructionCandidates(tx, ctx, plannedIds, plannedIds);
+        const deletable = new Set(deletableIds.map(String));
+        const removed = expired.filter((row) => deletable.has(row.id));
+        await deleteTerminalRows(tx, ctx, removed, requestedNow);
+        return removed.length;
+    });
+}
+/** Claim due DLQ work with row locks so concurrent brokers execute it once. */
+export async function maintainPostgresDlq(ctx, limit = 1000) {
+    const plan = await discoverPostgresDlqRetryPlan(ctx, limit);
+    const phase = await ctx.sql.begin(async (tx) => {
+        const batch = await lockPostgresDlqRetryBatch(tx, ctx, plan);
+        const now = await databaseNow(tx);
+        const expired = [];
+        let retried = 0;
+        for (const row of batch.rows) {
+            const stored = decodePostgresJob(row);
+            const entry = stored.dlqEntry;
+            if (!entry)
+                continue;
+            if (isDlqEntryExpired(entry, now)) {
+                expired.push(jobId(row.id));
+                continue;
+            }
+            const dlq = batch.policies.get(row.queue);
+            if (!dlq)
+                continue;
+            if (!canAutoRetry(entry, dlq, now))
+                continue;
+            await retryEntry(tx, ctx, row, {
+                config: dlq,
+                now,
+                dependencyIds: batch.dependencies.get(row.id) ?? [],
+            });
+            retried++;
+        }
+        return { retried, expired, now };
+    });
+    return {
+        retried: phase.retried,
+        purged: await purgeExpiredEntries(ctx, phase.expired, phase.now),
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { PostgresContext } from './context';
+import { type PostgresDlqMaintenanceResult } from './dlqLifecycle';
+/** Reconcile persisted queue limits after interrupted post-commit maintenance. */
+export declare function repairPostgresDlq(ctx: PostgresContext): Promise<number>;
+/** Periodic DLQ work also repairs any retention skipped by a stopped broker. */
+export declare function maintainPostgresDlq(ctx: PostgresContext, limit?: number): Promise<PostgresDlqMaintenanceResult>;

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

@@ -0,0 +1,36 @@
+import { enforcePostgresDlqLimitInTransaction, maintainPostgresDlq as maintainPostgresDlqLifecycle, } from './dlqLifecycle';
+import { decodePostgresDlqConfig } from './policies';
+/** Reconcile persisted queue limits after interrupted post-commit maintenance. */
+export async function repairPostgresDlq(ctx) {
+    const candidates = await ctx.sql `
+    SELECT jobs.queue, state.dlq_config, COUNT(*)::int AS failed_count
+    FROM bunqueue_jobs AS jobs
+    JOIN bunqueue_queue_state AS state
+      ON state.namespace = jobs.namespace AND state.queue = jobs.queue
+    WHERE jobs.namespace = ${ctx.config.namespace} AND jobs.state = 'failed'
+    GROUP BY jobs.queue, state.dlq_config
+    ORDER BY jobs.queue
+  `;
+    let removed = 0;
+    for (const candidate of candidates) {
+        const snapshotConfig = decodePostgresDlqConfig(candidate.queue, candidate.dlq_config);
+        if (candidate.failed_count <= snapshotConfig.maxEntries)
+            continue;
+        removed += await ctx.sql.begin(async (tx) => {
+            const [state] = await tx `
+        SELECT dlq_config FROM bunqueue_queue_state
+        WHERE namespace = ${ctx.config.namespace} AND queue = ${candidate.queue}
+        FOR SHARE
+      `;
+            const config = decodePostgresDlqConfig(candidate.queue, state?.dlq_config ?? null);
+            return (await enforcePostgresDlqLimitInTransaction(tx, ctx, candidate.queue, config.maxEntries)).length;
+        });
+    }
+    return removed;
+}
+/** Periodic DLQ work also repairs any retention skipped by a stopped broker. */
+export async function maintainPostgresDlq(ctx, limit = 1000) {
+    const result = await maintainPostgresDlqLifecycle(ctx, limit);
+    await repairPostgresDlq(ctx);
+    return result;
+}

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

@@ -0,0 +1,21 @@
+import type { TransactionSQL } from 'bun';
+import type { DlqConfig } from '../../../domain/types/dlq';
+import { type JobId } from '../../../domain/types/job';
+import type { PostgresContext } from './context';
+import type { PostgresJobRow } from './types';
+export interface PostgresDlqRetryPlan {
+    readonly candidates: ReadonlyArray<{
+        id: JobId;
+        queue: string;
+    }>;
+    readonly identityIds: readonly JobId[];
+}
+export interface LockedPostgresDlqRetryBatch {
+    readonly rows: readonly PostgresJobRow[];
+    readonly policies: ReadonlyMap<string, DlqConfig>;
+    readonly dependencies: ReadonlyMap<string, readonly JobId[]>;
+}
+/** Discover identities before taking any row lock so advisory locks stay first. */
+export declare function discoverPostgresDlqRetryPlan(ctx: PostgresContext, limit: number): Promise<PostgresDlqRetryPlan>;
+/** Lock policies and identities before rows, then reject any late dependency edge. */
+export declare function lockPostgresDlqRetryBatch(tx: TransactionSQL, ctx: PostgresContext, plan: PostgresDlqRetryPlan): Promise<LockedPostgresDlqRetryBatch>;

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

@@ -0,0 +1,92 @@
+import { jobId } from '../../../domain/types/job';
+import { lockPostgresDependencyCompletions } from './dependencyPromotion';
+import { decodePostgresDlqConfig } from './policies';
+/** Discover identities before taking any row lock so advisory locks stay first. */
+export async function discoverPostgresDlqRetryPlan(ctx, limit) {
+    const rows = await ctx.sql `
+    WITH candidates AS MATERIALIZED (
+      SELECT id, queue, completed_at
+      FROM bunqueue_jobs
+      WHERE namespace = ${ctx.config.namespace}
+        AND state = 'failed' AND dlq_entry IS NOT NULL
+      ORDER BY completed_at, id
+      LIMIT ${Math.max(1, Math.floor(limit))}
+    )
+    SELECT candidate.id, candidate.queue, dependency.dependency_id
+    FROM candidates AS candidate
+    LEFT JOIN bunqueue_dependencies AS dependency
+      ON dependency.namespace = ${ctx.config.namespace}
+      AND dependency.job_id = candidate.id
+    ORDER BY candidate.completed_at, candidate.id, dependency.dependency_id
+  `;
+    const candidates = new Map();
+    const identities = new Set();
+    for (const row of rows) {
+        if (!candidates.has(row.id)) {
+            candidates.set(row.id, { id: jobId(row.id), queue: row.queue });
+            identities.add(row.id);
+        }
+        if (row.dependency_id !== null)
+            identities.add(row.dependency_id);
+    }
+    return {
+        candidates: [...candidates.values()],
+        identityIds: [...identities].sort().map(jobId),
+    };
+}
+async function lockPolicies(tx, ctx, queues) {
+    const uniqueQueues = [...new Set(queues)].sort();
+    if (uniqueQueues.length === 0)
+        return new Map();
+    const rows = await tx `
+    SELECT queue, dlq_config
+    FROM bunqueue_queue_state
+    WHERE namespace = ${ctx.config.namespace}
+      AND queue = ANY(${tx.array(uniqueQueues, 'TEXT')})
+    ORDER BY queue
+    FOR SHARE
+  `;
+    const encoded = new Map(rows.map((row) => [row.queue, row.dlq_config]));
+    return new Map(uniqueQueues.map((queue) => [queue, decodePostgresDlqConfig(queue, encoded.get(queue) ?? null)]));
+}
+async function currentDependencies(tx, ctx, ids) {
+    if (ids.length === 0)
+        return new Map();
+    const rows = await tx `
+    SELECT job_id, dependency_id
+    FROM bunqueue_dependencies
+    WHERE namespace = ${ctx.config.namespace}
+      AND job_id = ANY(${tx.array([...ids], 'TEXT')})
+    ORDER BY job_id, dependency_id
+  `;
+    const result = new Map();
+    for (const row of rows) {
+        const values = result.get(row.job_id) ?? [];
+        values.push(jobId(row.dependency_id));
+        result.set(row.job_id, values);
+    }
+    return result;
+}
+/** Lock policies and identities before rows, then reject any late dependency edge. */
+export async function lockPostgresDlqRetryBatch(tx, ctx, plan) {
+    const policies = await lockPolicies(tx, ctx, plan.candidates.map((candidate) => candidate.queue));
+    await lockPostgresDependencyCompletions(tx, ctx, plan.identityIds);
+    const ids = plan.candidates.map((candidate) => String(candidate.id));
+    if (ids.length === 0)
+        return { rows: [], policies, dependencies: new Map() };
+    const plannedQueues = new Map(plan.candidates.map((candidate) => [String(candidate.id), candidate.queue]));
+    const rows = await tx `
+    SELECT job.*
+    FROM bunqueue_jobs AS job
+    WHERE job.namespace = ${ctx.config.namespace}
+      AND job.id = ANY(${tx.array(ids, 'TEXT')})
+      AND job.state = 'failed' AND job.dlq_entry IS NOT NULL
+    ORDER BY array_position(${tx.array(ids, 'TEXT')}, job.id)
+    FOR UPDATE OF job SKIP LOCKED
+  `;
+    const dependencies = await currentDependencies(tx, ctx, rows.map((row) => row.id));
+    const locked = new Set(plan.identityIds.map(String));
+    const revalidated = rows.filter((row) => plannedQueues.get(row.id) === row.queue &&
+        (dependencies.get(row.id) ?? []).every((dependencyId) => locked.has(String(dependencyId))));
+    return { rows: revalidated, policies, dependencies };
+}

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

@@ -0,0 +1,27 @@
+type EventCommitPruner = (batchSize: number, maxBatches: number) => Promise<number>;
+type MaintenanceReporter = (subsystem: string, error: unknown) => void;
+export interface PostgresEventCommitGcOptions {
+    readonly batchSize?: number;
+    readonly maxBatches?: number;
+    readonly idleDelayMs?: number;
+    readonly backlogDelayMs?: number;
+}
+/** Adapt journal GC frequency to backlog while keeping each database turn bounded. */
+export declare class PostgresEventCommitGc {
+    private readonly prune;
+    private readonly report;
+    private timer;
+    private active;
+    private closed;
+    private readonly batchSize;
+    private readonly maxBatches;
+    private readonly idleDelayMs;
+    private readonly backlogDelayMs;
+    constructor(prune: EventCommitPruner, report: MaintenanceReporter, options?: PostgresEventCommitGcOptions);
+    start(): void;
+    close(): void;
+    drain(): Promise<void>;
+    private schedule;
+    private runOnce;
+}
+export {};

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

@@ -0,0 +1,62 @@
+const DEFAULT_BATCH_SIZE = 10_000;
+const DEFAULT_MAX_BATCHES = 8;
+const DEFAULT_IDLE_DELAY_MS = 60_000;
+const DEFAULT_BACKLOG_DELAY_MS = 25;
+/** Adapt journal GC frequency to backlog while keeping each database turn bounded. */
+export class PostgresEventCommitGc {
+    prune;
+    report;
+    timer = null;
+    active = null;
+    closed = false;
+    batchSize;
+    maxBatches;
+    idleDelayMs;
+    backlogDelayMs;
+    constructor(prune, report, options = {}) {
+        this.prune = prune;
+        this.report = report;
+        this.batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+        this.maxBatches = options.maxBatches ?? DEFAULT_MAX_BATCHES;
+        this.idleDelayMs = options.idleDelayMs ?? DEFAULT_IDLE_DELAY_MS;
+        this.backlogDelayMs = options.backlogDelayMs ?? DEFAULT_BACKLOG_DELAY_MS;
+    }
+    start() {
+        this.schedule(this.idleDelayMs);
+    }
+    close() {
+        this.closed = true;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+    async drain() {
+        await this.active;
+    }
+    schedule(delayMs) {
+        if (this.closed || this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.active = this.runOnce().finally(() => {
+                this.active = null;
+            });
+        }, delayMs);
+    }
+    async runOnce() {
+        let nextDelay = this.idleDelayMs;
+        try {
+            const deleted = await this.prune(this.batchSize, this.maxBatches);
+            if (deleted >= this.batchSize * this.maxBatches)
+                nextDelay = this.backlogDelayMs;
+            this.report('event-commit-gc', null);
+        }
+        catch (error) {
+            nextDelay = this.backlogDelayMs;
+            this.report('event-commit-gc', error);
+        }
+        finally {
+            this.schedule(nextDelay);
+        }
+    }
+}

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

@@ -0,0 +1,18 @@
+import type { PostgresContext } from './context';
+import type { PostgresStoreEvent } from './types';
+export interface PostgresEventJournalCursor {
+    readonly commitSeq: number;
+    readonly eventId: number;
+}
+export interface PostgresJournalEvent {
+    readonly commitSeq: number;
+    readonly event: PostgresStoreEvent;
+}
+export declare function latestPostgresEventJournalBaseline(ctx: PostgresContext): Promise<{
+    commitSeq: number;
+    latestEventId: number;
+}>;
+/** Load events in commit order, independent of physical BIGSERIAL allocation. */
+export declare function loadPostgresJournalEventsAfter(ctx: PostgresContext, cursor: PostgresEventJournalCursor, limit?: number): Promise<PostgresJournalEvent[]>;
+/** Remove commit envelopes after every referenced event and watermark is gone. */
+export declare function prunePostgresEventCommits(ctx: PostgresContext, limit?: number, maxBatches?: number): Promise<number>;

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

@@ -0,0 +1,76 @@
+import { decodePostgresEvent, numeric } from './codec';
+export async function latestPostgresEventJournalBaseline(ctx) {
+    const [row] = await ctx.sql `
+    SELECT
+      (
+        SELECT MAX(commit_seq) FROM bunqueue_event_commits
+        WHERE namespace = ${ctx.config.namespace} AND commit_seq IS NOT NULL
+      ) AS commit_seq,
+      (
+        SELECT MAX(id) FROM bunqueue_events
+        WHERE namespace = ${ctx.config.namespace}
+      ) AS latest_event_id
+  `;
+    return {
+        commitSeq: numeric(row.commit_seq) ?? 0,
+        latestEventId: numeric(row.latest_event_id) ?? 0,
+    };
+}
+/** Load events in commit order, independent of physical BIGSERIAL allocation. */
+export async function loadPostgresJournalEventsAfter(ctx, cursor, limit = 1000) {
+    const rows = await ctx.sql `
+    SELECT event.id, event.queue, event.event_type, event.job_id,
+           event.occurred_at, event.payload, journal.commit_seq
+    FROM bunqueue_event_commits AS journal
+    JOIN bunqueue_events AS event
+      ON event.namespace = journal.namespace
+     AND event.transaction_id = journal.transaction_id
+    WHERE journal.namespace = ${ctx.config.namespace}
+      AND journal.commit_seq IS NOT NULL
+      AND (journal.commit_seq, event.id) > (${cursor.commitSeq}, ${cursor.eventId})
+    ORDER BY journal.commit_seq, event.id
+    LIMIT ${Math.max(1, limit)}
+  `;
+    return rows.map((row) => ({
+        commitSeq: numeric(row.commit_seq) ?? 0,
+        event: decodePostgresEvent(row),
+    }));
+}
+/** Remove commit envelopes after every referenced event and watermark is gone. */
+export async function prunePostgresEventCommits(ctx, limit = 10_000, maxBatches = 8) {
+    const batchSize = Math.max(1, limit);
+    const batchLimit = Math.max(1, maxBatches);
+    let total = 0;
+    for (let batch = 0; batch < batchLimit; batch++) {
+        const deleted = await ctx.sql `
+    WITH candidates AS MATERIALIZED (
+      SELECT journal.namespace, journal.transaction_id
+      FROM bunqueue_event_commits AS journal
+      WHERE journal.namespace = ${ctx.config.namespace}
+        AND journal.commit_seq IS NOT NULL
+        AND NOT EXISTS (
+          SELECT 1 FROM bunqueue_events AS event
+          WHERE event.namespace = journal.namespace
+            AND event.transaction_id = journal.transaction_id
+        )
+        AND NOT EXISTS (
+          SELECT 1 FROM bunqueue_event_prune_watermarks AS watermark
+          WHERE watermark.namespace = journal.namespace
+            AND watermark.transaction_id = journal.transaction_id
+        )
+      ORDER BY journal.commit_seq
+      LIMIT ${batchSize}
+      FOR UPDATE SKIP LOCKED
+    )
+    DELETE FROM bunqueue_event_commits AS journal
+    USING candidates
+    WHERE journal.namespace = candidates.namespace
+      AND journal.transaction_id = candidates.transaction_id
+    RETURNING journal.transaction_id
+  `;
+        total += deleted.length;
+        if (deleted.length < batchSize)
+            break;
+    }
+    return total;
+}