bunqueue 2.8.60 → 2.9.2

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

@@ -0,0 +1,205 @@
+import { createCronJob } from '../../../domain/types/cron';
+import { createJob, generateJobId } from '../../../domain/types/job';
+import { expandCronShortcut, getNextCronRun, getNextIntervalRun } from '../../scheduler/cronParser';
+import { assertPersistedCronSupported } from '../../scheduler/cron/persisted';
+import { assertValidCronInput } from '../../scheduler/cron/validation';
+import { postgresAdvisoryLockName } from './advisoryLocks';
+import { admitPostgresJob } from './admission';
+import { decodePostgresValue, encodePostgresValue } from './codec';
+import { databaseNow } from './context';
+import { hasActivePostgresWorker } from './workers';
+import { postgresBrokerStaleMs } from './brokerSessions';
+export function decodePostgresCron(row) {
+    const cron = decodePostgresValue(row.payload, null, `postgresCron:${row.name}`);
+    if (!cron)
+        throw new Error(`Corrupt PostgreSQL cron payload for ${row.name}`);
+    cron.nextRun = Number(row.next_run);
+    cron.executions = row.executions;
+    assertPersistedCronSupported(cron);
+    return cron;
+}
+function validateInput(input) {
+    assertValidCronInput(input);
+}
+function nextRun(input, now) {
+    if (input.schedule) {
+        return getNextCronRun(expandCronShortcut(input.schedule), now, input.timezone);
+    }
+    return getNextIntervalRun(input.repeatEvery, now);
+}
+export async function upsertPostgresCron(ctx, input) {
+    validateInput(input);
+    return await ctx.sql.begin(async (tx) => {
+        const existing = await tx `
+      SELECT name, payload, next_run, executions, max_limit
+      FROM bunqueue_crons
+      WHERE namespace = ${ctx.config.namespace} AND name = ${input.name}
+      FOR UPDATE
+    `;
+        const now = await databaseNow(tx);
+        const cron = createCronJob(input, input.immediately && !existing[0] ? now : nextRun(input, now));
+        cron.executions = existing[0]?.executions ?? 0;
+        await tx `
+      INSERT INTO bunqueue_crons
+        (namespace, name, payload, next_run, executions, max_limit, updated_at)
+      VALUES
+        (${ctx.config.namespace}, ${cron.name}, ${encodePostgresValue(cron)}, ${cron.nextRun},
+         ${cron.executions}, ${cron.maxLimit}, ${now})
+      ON CONFLICT (namespace, name) DO UPDATE SET
+        payload = excluded.payload,
+        next_run = excluded.next_run,
+        executions = excluded.executions,
+        max_limit = excluded.max_limit,
+        updated_at = excluded.updated_at
+    `;
+        return cron;
+    });
+}
+export async function getPostgresCron(ctx, name) {
+    const rows = await ctx.sql `
+    SELECT name, payload, next_run, executions, max_limit
+    FROM bunqueue_crons
+    WHERE namespace = ${ctx.config.namespace} AND name = ${name}
+  `;
+    return rows[0] ? decodePostgresCron(rows[0]) : undefined;
+}
+export async function listPostgresCrons(ctx, sql = ctx.sql) {
+    const rows = await sql `
+    SELECT name, payload, next_run, executions, max_limit
+    FROM bunqueue_crons
+    WHERE namespace = ${ctx.config.namespace}
+    ORDER BY name
+  `;
+    return rows.map(decodePostgresCron);
+}
+export async function removePostgresCron(ctx, name) {
+    const rows = await ctx.sql `
+    DELETE FROM bunqueue_crons
+    WHERE namespace = ${ctx.config.namespace} AND name = ${name}
+    RETURNING name
+  `;
+    return rows.length > 0;
+}
+function spawnedInput(cron) {
+    const uniqueKey = cron.uniqueKey ?? (cron.preventOverlap ? `cron:${cron.name}` : undefined);
+    const options = cron.jobOptions;
+    return {
+        name: cron.jobName,
+        data: cron.data,
+        priority: cron.priority,
+        uniqueKey,
+        dedup: cron.dedup ?? undefined,
+        maxAttempts: options?.maxAttempts,
+        backoff: options?.backoff,
+        timeout: options?.timeout,
+        delay: options?.delay,
+        stallTimeout: options?.stallTimeout,
+        removeOnComplete: options?.removeOnComplete,
+        removeOnFail: options?.removeOnFail,
+    };
+}
+function followingRun(cron, now) {
+    if (cron.schedule) {
+        return getNextCronRun(expandCronShortcut(cron.schedule), now, cron.timezone ?? undefined);
+    }
+    const interval = cron.repeatEvery;
+    const scheduled = getNextIntervalRun(interval, cron.nextRun);
+    return scheduled <= now ? getNextIntervalRun(interval, now) : scheduled;
+}
+/** Recalculate missed rows only on the oldest live broker for this namespace. */
+export async function reconcilePostgresCronsOnStartup(ctx) {
+    const lockName = postgresAdvisoryLockName('cron-startup', ctx.config.namespace);
+    return await ctx.sql.begin(async (tx) => {
+        await tx `
+      SELECT pg_advisory_xact_lock(hashtextextended(${lockName}, 0))
+    `;
+        const now = await databaseNow(tx);
+        const [leader] = await tx `
+      SELECT
+        broker_id = ${ctx.config.brokerId}
+          AND session_id IS NOT DISTINCT FROM ${ctx.config.brokerSessionId} AS elected
+      FROM bunqueue_brokers
+      WHERE namespace = ${ctx.config.namespace}
+        AND heartbeat_at > ${now - postgresBrokerStaleMs(ctx)}
+      ORDER BY started_at, broker_id, session_id NULLS FIRST
+      LIMIT 1
+    `;
+        if (!leader?.elected)
+            return 0;
+        const rows = await tx `
+      SELECT name, payload, next_run, executions, max_limit
+      FROM bunqueue_crons
+      WHERE namespace = ${ctx.config.namespace} AND next_run < ${now}
+      ORDER BY next_run, name
+      FOR UPDATE
+    `;
+        let reconciled = 0;
+        for (const row of rows) {
+            const cron = decodePostgresCron(row);
+            if (!cron.skipMissedOnRestart && !cron.skipIfNoWorker)
+                continue;
+            cron.nextRun = cron.schedule
+                ? getNextCronRun(expandCronShortcut(cron.schedule), now, cron.timezone ?? undefined)
+                : getNextIntervalRun(cron.repeatEvery, now);
+            await tx `
+        UPDATE bunqueue_crons
+        SET payload = ${encodePostgresValue(cron)}, next_run = ${cron.nextRun}, updated_at = ${now}
+        WHERE namespace = ${ctx.config.namespace} AND name = ${cron.name}
+      `;
+            reconciled++;
+        }
+        return reconciled;
+    });
+}
+async function fireCron(tx, ctx, row, now) {
+    const cron = decodePostgresCron(row);
+    const admitted = await admitPostgresJob(tx, ctx, createJob(generateJobId(), cron.queue, spawnedInput(cron), now), { linkParent: false });
+    if (!admitted.inserted && cron.preventOverlap) {
+        await skipCron(tx, ctx, cron, now);
+        return false;
+    }
+    cron.executions++;
+    cron.nextRun = followingRun(cron, now);
+    await tx `
+    UPDATE bunqueue_crons
+    SET payload = ${encodePostgresValue(cron)}, next_run = ${cron.nextRun},
+        executions = ${cron.executions}, updated_at = ${now}
+    WHERE namespace = ${ctx.config.namespace} AND name = ${cron.name}
+  `;
+    return true;
+}
+async function skipCron(tx, ctx, cron, now) {
+    cron.nextRun = followingRun(cron, now);
+    await tx `
+    UPDATE bunqueue_crons
+    SET payload = ${encodePostgresValue(cron)}, next_run = ${cron.nextRun}, updated_at = ${now}
+    WHERE namespace = ${ctx.config.namespace} AND name = ${cron.name}
+  `;
+}
+/** Advance and enqueue each due cron once under PostgreSQL row locks. */
+export async function processPostgresCrons(ctx, limit = 100) {
+    return await ctx.sql.begin(async (tx) => {
+        const now = await databaseNow(tx);
+        const rows = await tx `
+      SELECT name, payload, next_run, executions, max_limit
+      FROM bunqueue_crons
+      WHERE namespace = ${ctx.config.namespace}
+        AND next_run <= ${now}
+        AND (max_limit IS NULL OR executions < max_limit)
+      ORDER BY next_run, name
+      LIMIT ${Math.max(1, limit)}
+      FOR UPDATE SKIP LOCKED
+    `;
+        let fired = 0;
+        for (const row of rows) {
+            const cron = decodePostgresCron(row);
+            if (cron.skipIfNoWorker && !(await hasActivePostgresWorker(tx, ctx, cron.queue, now))) {
+                await skipCron(tx, ctx, cron, now);
+                continue;
+            }
+            if (await fireCron(tx, ctx, row, now))
+                fired++;
+        }
+        return fired;
+    });
+}

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

@@ -0,0 +1,9 @@
+import type { TransactionSQL } from 'bun';
+import { type PostgresContext } from './context';
+import type { PostgresJobRow, PostgresStoredJob } from './types';
+/** Clear a live deduplication owner and publish the new authoritative payload. */
+export declare function clearPostgresDeduplication(tx: TransactionSQL, ctx: PostgresContext, row: PostgresJobRow, now: number): Promise<PostgresStoredJob>;
+/** Persist a newer extend window so every broker observes the same deduplication metadata. */
+export declare function extendPostgresDeduplication(tx: TransactionSQL, ctx: PostgresContext, row: PostgresJobRow, ttl: number, now: number): Promise<PostgresStoredJob>;
+/** Publish deletion of a pending generation replaced within the same transaction. */
+export declare function recordPostgresDeduplicationRemoval(tx: TransactionSQL, ctx: PostgresContext, row: PostgresJobRow, now: number): Promise<void>;

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

@@ -0,0 +1,47 @@
+import { decodePostgresJob, encodePostgresValue } from './codec';
+import { recordPostgresEvent } from './context';
+/** Clear a live deduplication owner and publish the new authoritative payload. */
+export async function clearPostgresDeduplication(tx, ctx, row, now) {
+    const stored = decodePostgresJob(row);
+    const updatedJob = { ...stored.job, uniqueKey: null };
+    await tx `
+    UPDATE bunqueue_jobs
+    SET payload = ${encodePostgresValue(updatedJob)}, unique_key = NULL,
+        unique_expires_at = NULL, version = version + 1
+    WHERE namespace = ${ctx.config.namespace} AND id = ${row.id}
+  `;
+    await recordPostgresEvent(tx, ctx, {
+        queue: updatedJob.queue,
+        type: 'updated',
+        jobId: updatedJob.id,
+        occurredAt: now,
+        job: updatedJob,
+        state: row.state,
+    });
+    return { ...stored, job: updatedJob, version: stored.version + 1 };
+}
+/** Persist a newer extend window so every broker observes the same deduplication metadata. */
+export async function extendPostgresDeduplication(tx, ctx, row, ttl, now) {
+    const stored = decodePostgresJob(row);
+    const updatedJob = { ...stored.job, deduplicationTtl: ttl };
+    await tx `
+    UPDATE bunqueue_jobs
+    SET payload = ${encodePostgresValue(updatedJob)}, unique_expires_at = ${now + ttl},
+        version = version + 1
+    WHERE namespace = ${ctx.config.namespace} AND id = ${row.id}
+  `;
+    return { ...stored, job: updatedJob, version: stored.version + 1 };
+}
+/** Publish deletion of a pending generation replaced within the same transaction. */
+export async function recordPostgresDeduplicationRemoval(tx, ctx, row, now) {
+    const stored = decodePostgresJob(row);
+    await recordPostgresEvent(tx, ctx, {
+        queue: stored.job.queue,
+        type: 'removed',
+        jobId: stored.job.id,
+        occurredAt: now,
+        job: stored.job,
+        state: stored.state,
+        removed: true,
+    });
+}

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

@@ -0,0 +1,14 @@
+import type { TransactionSQL } from 'bun';
+import { type JobId } from '../../../domain/types/job';
+import type { PostgresContext } from './context';
+/** Acquire candidate identity locks in the same order as dependency admission. */
+export declare function lockPostgresDestructionIdentities(tx: TransactionSQL, ctx: PostgresContext, ids: readonly JobId[]): Promise<void>;
+/** Lock candidate rows and every live consumer row in deterministic order. */
+export declare function lockPostgresDestructionRows(tx: TransactionSQL, ctx: PostgresContext, ids: readonly JobId[]): Promise<void>;
+/** Acquire identity locks before any target or consumer row lock. */
+export declare function lockPostgresDestructionCandidates(tx: TransactionSQL, ctx: PostgresContext, ids: readonly JobId[]): Promise<void>;
+/** Split a revalidated delete set without orphaning consumers that survive the command. */
+export declare function partitionPostgresDestructionCandidates(tx: TransactionSQL, ctx: PostgresContext, ids: readonly JobId[], deletingConsumerIds?: readonly JobId[]): Promise<{
+    deletableIds: JobId[];
+    protectedIds: JobId[];
+}>;

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

@@ -0,0 +1,74 @@
+import { jobId } from '../../../domain/types/job';
+import { lockPostgresDependencyCompletions } from './dependencyPromotion';
+const LIVE_CONSUMER_STATES = [
+    'waiting',
+    'prioritized',
+    'delayed',
+    'waiting-children',
+    'active',
+];
+function uniqueIds(ids) {
+    return [...new Set(ids.map(String))].sort();
+}
+/** Acquire candidate identity locks in the same order as dependency admission. */
+export async function lockPostgresDestructionIdentities(tx, ctx, ids) {
+    const candidates = uniqueIds(ids);
+    if (candidates.length === 0)
+        return;
+    await lockPostgresDependencyCompletions(tx, ctx, candidates.map(jobId));
+}
+/** Lock candidate rows and every live consumer row in deterministic order. */
+export async function lockPostgresDestructionRows(tx, ctx, ids) {
+    const candidates = uniqueIds(ids);
+    if (candidates.length === 0)
+        return;
+    const consumers = await tx `
+    SELECT DISTINCT consumer.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')})
+    ORDER BY consumer.id
+  `;
+    const rowIds = [...new Set([...candidates, ...consumers.map((row) => row.id)])].sort();
+    await tx `
+    SELECT id FROM bunqueue_jobs
+    WHERE namespace = ${ctx.config.namespace}
+      AND id = ANY(${tx.array(rowIds, 'TEXT')})
+    ORDER BY id
+    FOR UPDATE
+  `;
+}
+/** Acquire identity locks before any target or consumer row lock. */
+export async function lockPostgresDestructionCandidates(tx, ctx, ids) {
+    await lockPostgresDestructionIdentities(tx, ctx, ids);
+    await lockPostgresDestructionRows(tx, ctx, ids);
+}
+/** Split a revalidated delete set without orphaning consumers that survive the command. */
+export async function partitionPostgresDestructionCandidates(tx, ctx, ids, deletingConsumerIds = ids) {
+    const candidates = uniqueIds(ids);
+    if (candidates.length === 0)
+        return { deletableIds: [], protectedIds: [] };
+    const deleting = uniqueIds(deletingConsumerIds);
+    const rows = await tx `
+    SELECT DISTINCT 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
+  `;
+    const protectedSet = new Set(rows.map((row) => row.dependency_id));
+    return {
+        deletableIds: candidates.filter((id) => !protectedSet.has(id)).map(jobId),
+        protectedIds: candidates.filter((id) => protectedSet.has(id)).map(jobId),
+    };
+}

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

@@ -0,0 +1,29 @@
+import type { TransactionSQL } from 'bun';
+import { type Job, type JobId } from '../../../domain/types/job';
+import type { PostgresContext } from './context';
+import type { PostgresJobState } from './types';
+type DependencyReadyState = Extract<PostgresJobState, 'waiting' | 'prioritized' | 'delayed'>;
+/** Serialize completion evidence readers and writers for the supplied generations. */
+export declare function lockPostgresDependencyCompletions(tx: TransactionSQL, ctx: PostgresContext, dependencyIds: readonly JobId[]): Promise<void>;
+/** Safely probe a late-discovered identity without inverting row/advisory lock order. */
+export declare function tryLockPostgresDependencyCompletions(tx: TransactionSQL, ctx: PostgresContext, dependencyIds: readonly JobId[]): Promise<boolean>;
+/** Reject dependency references that have no job row or durable completion evidence. */
+export declare function assertPostgresDependenciesExist(tx: TransactionSQL, ctx: PostgresContext, dependencyIds: readonly JobId[]): Promise<void>;
+/** Read dependency evidence while the caller holds every corresponding completion lock. */
+export declare function postgresDependenciesSatisfied(tx: TransactionSQL, ctx: PostgresContext, dependencyIds: readonly JobId[]): Promise<boolean>;
+/** Pure scheduling policy shared by completion-time promotion and pull-time repair. */
+export declare function postgresDependencyReadyState(job: Job, now: number): DependencyReadyState;
+/**
+ * Discover and serialize every dependency consumer before completion locks child rows.
+ * The returned immutable plan is safe to execute after completion evidence is stored.
+ */
+export declare function lockPostgresCompletionConsumers(tx: TransactionSQL, ctx: PostgresContext, dependencyIds: readonly JobId[]): Promise<readonly JobId[]>;
+/** Build a completion-scoped command after acquiring its parent locks. */
+export declare function planPostgresDependencyCompletion(tx: TransactionSQL, ctx: PostgresContext, dependencyIds: readonly JobId[]): Promise<{
+    promote(now: number): Promise<JobId[]>;
+}>;
+/** Promote all resolved members of a previously locked completion-consumer plan. */
+export declare function promotePostgresCompletionConsumers(tx: TransactionSQL, ctx: PostgresContext, parentIds: readonly JobId[], now: number): Promise<JobId[]>;
+/** Pull-time convergence path for rows left behind by interrupted or legacy writers. */
+export declare function repairResolvedPostgresDependencyConsumers(tx: TransactionSQL, ctx: PostgresContext, queue: string, now: number): Promise<JobId[]>;
+export {};

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

@@ -0,0 +1,212 @@
+import { jobId, MAX_TIMELINE_ENTRIES } from '../../../domain/types/job';
+import { postgresAdvisoryLockName } from './advisoryLocks';
+import { recordPostgresJobEvents } from './batchEvents';
+import { decodePostgresJob, encodePostgresValue, postgresByteaBase64 } from './codec';
+import { lockPostgresFlowParents } from './flowFailures';
+function uniqueIds(ids) {
+    return [...new Set(ids.map(String))].sort();
+}
+/** Serialize completion evidence readers and writers for the supplied generations. */
+export async function lockPostgresDependencyCompletions(tx, ctx, dependencyIds) {
+    const lockNames = uniqueIds(dependencyIds).map((id) => postgresAdvisoryLockName('dependency-completion', 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 dependency(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
+  `;
+}
+/** Safely probe a late-discovered identity without inverting row/advisory lock order. */
+export async function tryLockPostgresDependencyCompletions(tx, ctx, dependencyIds) {
+    const lockNames = uniqueIds(dependencyIds).map((id) => postgresAdvisoryLockName('dependency-completion', ctx.config.namespace, id));
+    if (lockNames.length === 0)
+        return true;
+    const [row] = await tx `
+    WITH ordered_ids AS MATERIALIZED (
+      SELECT DISTINCT hashtextextended(lock_name, 0) AS lock_key
+      FROM unnest(${tx.array(lockNames, 'TEXT')}) AS dependency(lock_name)
+      ORDER BY lock_key
+    ), locked_ids AS MATERIALIZED (
+      SELECT lock_key, pg_try_advisory_xact_lock(lock_key) AS acquired
+      FROM ordered_ids
+      ORDER BY lock_key
+    )
+    SELECT COALESCE(BOOL_AND(acquired), TRUE) AS acquired FROM locked_ids
+  `;
+    return row.acquired;
+}
+/** Reject dependency references that have no job row or durable completion evidence. */
+export async function assertPostgresDependenciesExist(tx, ctx, dependencyIds) {
+    const ids = [...new Set(dependencyIds.map(String))];
+    if (ids.length === 0)
+        return;
+    const rows = await tx `
+    WITH requested AS MATERIALIZED (
+      SELECT dependency_id, ordinal
+      FROM unnest(${tx.array(ids, 'TEXT')}) WITH ORDINALITY
+        AS dependency(dependency_id, ordinal)
+    )
+    SELECT requested.dependency_id
+    FROM requested
+    WHERE NOT EXISTS (
+      SELECT 1 FROM bunqueue_jobs AS job
+      WHERE job.namespace = ${ctx.config.namespace} AND job.id = requested.dependency_id
+    ) AND NOT EXISTS (
+      SELECT 1 FROM bunqueue_completions AS completion
+      WHERE completion.namespace = ${ctx.config.namespace}
+        AND completion.job_id = requested.dependency_id
+    )
+    ORDER BY requested.ordinal
+    LIMIT 1
+  `;
+    if (rows[0])
+        throw new Error(`Dependency job not found: ${rows[0].dependency_id}`);
+}
+/** Read dependency evidence while the caller holds every corresponding completion lock. */
+export async function postgresDependenciesSatisfied(tx, ctx, dependencyIds) {
+    const ids = uniqueIds(dependencyIds);
+    if (ids.length === 0)
+        return true;
+    const [row] = await tx `
+    SELECT COUNT(DISTINCT dependency_id)::bigint AS count
+    FROM (
+      SELECT job_id AS dependency_id
+      FROM bunqueue_completions
+      WHERE namespace = ${ctx.config.namespace}
+        AND job_id = ANY(${tx.array(ids, 'TEXT')})
+      UNION
+      SELECT id AS dependency_id
+      FROM bunqueue_jobs
+      WHERE namespace = ${ctx.config.namespace}
+        AND state = 'completed'
+        AND id = ANY(${tx.array(ids, 'TEXT')})
+    ) completed_dependencies
+  `;
+    return Number(row.count) === ids.length;
+}
+/** Pure scheduling policy shared by completion-time promotion and pull-time repair. */
+export function postgresDependencyReadyState(job, now) {
+    if (job.runAt > now)
+        return 'delayed';
+    return job.priority > 0 ? 'prioritized' : 'waiting';
+}
+function preparePromotion(row, now) {
+    const job = decodePostgresJob(row).job;
+    const state = postgresDependencyReadyState(job, now);
+    if (job.timeline.at(-1)?.state !== state && job.timeline.length < MAX_TIMELINE_ENTRIES) {
+        job.timeline.push({ state, timestamp: now });
+    }
+    return { job, state, payload: encodePostgresValue(job) };
+}
+async function consumerIdsForDependencies(tx, ctx, dependencyIds) {
+    const ids = uniqueIds(dependencyIds);
+    if (ids.length === 0)
+        return [];
+    const rows = await tx `
+    SELECT DISTINCT dependency.job_id AS parent_id
+    FROM bunqueue_dependencies AS dependency
+    JOIN bunqueue_jobs AS parent
+      ON parent.namespace = dependency.namespace AND parent.id = dependency.job_id
+    WHERE dependency.namespace = ${ctx.config.namespace}
+      AND dependency.dependency_id = ANY(${tx.array(ids, 'TEXT')})
+      AND parent.state = 'waiting-children'
+    ORDER BY dependency.job_id
+  `;
+    return rows.map((row) => jobId(row.parent_id));
+}
+async function resolvedRows(tx, ctx, parentIds) {
+    const ids = uniqueIds(parentIds);
+    if (ids.length === 0)
+        return [];
+    return await tx `
+    SELECT parent.*
+    FROM bunqueue_jobs AS parent
+    WHERE parent.namespace = ${ctx.config.namespace}
+      AND parent.id = ANY(${tx.array(ids, 'TEXT')})
+      AND parent.state = 'waiting-children'
+      AND NOT EXISTS (
+        SELECT 1
+        FROM bunqueue_dependencies AS dependency
+        WHERE dependency.namespace = parent.namespace
+          AND dependency.job_id = parent.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 parent.id
+    FOR UPDATE OF parent
+  `;
+}
+async function persistPromotions(tx, ctx, prepared) {
+    if (prepared.length === 0)
+        return;
+    await tx `
+    UPDATE bunqueue_jobs AS parent
+    SET payload = decode(batch.payload_base64, 'base64'),
+        state = batch.state,
+        version = parent.version + 1
+    FROM unnest(
+      ${tx.array(prepared.map(({ job }) => String(job.id)), 'TEXT')},
+      ${tx.array(prepared.map(({ payload }) => postgresByteaBase64(payload)), 'TEXT')},
+      ${tx.array(prepared.map(({ state }) => state), 'TEXT')}
+    ) AS batch(id, payload_base64, state)
+    WHERE parent.namespace = ${ctx.config.namespace} AND parent.id = batch.id
+  `;
+}
+/**
+ * Discover and serialize every dependency consumer before completion locks child rows.
+ * The returned immutable plan is safe to execute after completion evidence is stored.
+ */
+export async function lockPostgresCompletionConsumers(tx, ctx, dependencyIds) {
+    const parentIds = await consumerIdsForDependencies(tx, ctx, dependencyIds);
+    await lockPostgresFlowParents(tx, ctx, parentIds);
+    return parentIds;
+}
+/** Build a completion-scoped command after acquiring its parent locks. */
+export async function planPostgresDependencyCompletion(tx, ctx, dependencyIds) {
+    await lockPostgresDependencyCompletions(tx, ctx, dependencyIds);
+    const parentIds = await lockPostgresCompletionConsumers(tx, ctx, dependencyIds);
+    return {
+        promote: (now) => promotePostgresCompletionConsumers(tx, ctx, parentIds, now),
+    };
+}
+/** Promote all resolved members of a previously locked completion-consumer plan. */
+export async function promotePostgresCompletionConsumers(tx, ctx, parentIds, now) {
+    const prepared = (await resolvedRows(tx, ctx, parentIds)).map((row) => preparePromotion(row, now));
+    await persistPromotions(tx, ctx, prepared);
+    await recordPostgresJobEvents(tx, ctx, prepared.map(({ job, state }) => ({ job, type: 'retried', state })), now);
+    return prepared.map(({ job }) => job.id);
+}
+/** Pull-time convergence path for rows left behind by interrupted or legacy writers. */
+export async function repairResolvedPostgresDependencyConsumers(tx, ctx, queue, now) {
+    const rows = await tx `
+    SELECT parent.id AS parent_id
+    FROM bunqueue_jobs AS parent
+    WHERE parent.namespace = ${ctx.config.namespace}
+      AND parent.queue = ${queue}
+      AND parent.state = 'waiting-children'
+      AND NOT EXISTS (
+        SELECT 1 FROM bunqueue_dependencies AS dependency
+        WHERE dependency.namespace = parent.namespace AND dependency.job_id = parent.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 parent.id
+  `;
+    const parentIds = rows.map((row) => jobId(row.parent_id));
+    await lockPostgresFlowParents(tx, ctx, parentIds);
+    return await promotePostgresCompletionConsumers(tx, ctx, parentIds, now);
+}

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

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