bunqueue 2.8.50 → 2.8.51

package/dist/application/types.d.ts

@@ -13,6 +13,7 @@ import type { WebhookManager } from './webhookManager';
 import type { WorkerManager } from './workerManager';
 import type { MonitoringState } from './monitoringChecks';
 import type { DependencyResultTracker } from './dependencyResultTracker';
+import type { DependencyCompletionTracker } from './dependencyCompletions';
 /** Queue Manager configuration */
 export interface QueueManagerConfig {
     dataPath?: string;
@@ -108,7 +109,8 @@ export interface BackgroundContext extends QueueManagerState {
     workerManager: WorkerManager;
     monitoringState: MonitoringState;
     completedJobsData: BoundedMap<JobId, Job>;
-    depCompletions?: BoundedSet<JobId>;
+    depCompletions?: DependencyCompletionTracker;
+    maxDependencyCompletions: number;
     timedOutJobs?: BoundedSet<JobId>;
 }
 /** Context for stats operations */

package/dist/client/flowPlan.js

@@ -36,8 +36,16 @@ function plannedId(node) {
     }
     return jobId(custom);
 }
+function validateQueueDefaults(options) {
+    for (const defaults of Object.values(options?.queuesOptions ?? {})) {
+        if (defaults.jobId !== undefined) {
+            throw new Error('jobId cannot be a queue default');
+        }
+    }
+}
 /** Compile one or more trees into a fully-resolved graph before contacting the broker. */
 export function planFlows(flows, options) {
+    validateQueueDefaults(options);
     const jobs = [];
     const ids = new Set();
     const seen = new WeakSet();

package/dist/client/flowTypes.d.ts

@@ -72,6 +72,6 @@ export interface GetFlowOpts {
  * Allows setting default job options per queue when adding flows.
  */
 export interface FlowOpts {
-    /** Default job options per queue name */
-    queuesOptions?: Record<string, Partial<JobOptions>>;
+    /** Default job options per queue name. Set `jobId` on the individual flow node. */
+    queuesOptions?: Record<string, Omit<Partial<JobOptions>, 'jobId'>>;
 }

package/dist/infrastructure/persistence/dependencyCompletionSchema.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Durable, payload-free evidence for completed jobs removed by
+ * `removeOnComplete`. Unreferenced rows follow the bounded FIFO retention
+ * window; rows owned by live dependency edges remain pinned until checkpoint.
+ */
+export declare const DEPENDENCY_COMPLETION_SCHEMA = "\nCREATE TABLE IF NOT EXISTS dependency_completions (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    job_id TEXT NOT NULL UNIQUE,\n    queue TEXT NOT NULL,\n    completed_at INTEGER NOT NULL,\n    pinned INTEGER NOT NULL DEFAULT 0\n);\nCREATE INDEX IF NOT EXISTS idx_dependency_completions_queue\n    ON dependency_completions(queue);\n";

package/dist/infrastructure/persistence/dependencyCompletionSchema.js

@@ -0,0 +1,16 @@
+/**
+ * Durable, payload-free evidence for completed jobs removed by
+ * `removeOnComplete`. Unreferenced rows follow the bounded FIFO retention
+ * window; rows owned by live dependency edges remain pinned until checkpoint.
+ */
+export const DEPENDENCY_COMPLETION_SCHEMA = `
+CREATE TABLE IF NOT EXISTS dependency_completions (
+    sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+    job_id TEXT NOT NULL UNIQUE,
+    queue TEXT NOT NULL,
+    completed_at INTEGER NOT NULL,
+    pinned INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_dependency_completions_queue
+    ON dependency_completions(queue);
+`;

package/dist/infrastructure/persistence/dependencyCompletionStore.d.ts

@@ -0,0 +1,38 @@
+import type { Database } from 'bun:sqlite';
+import type { JobId } from '../../domain/types/job';
+export interface DependencyCompletionRecord {
+    jobId: JobId;
+    queue: string;
+    completedAt: number;
+    pinned: boolean;
+}
+/**
+ * SQLite operations for payload-free `removeOnComplete` completion evidence.
+ * The owner supplies write-error handling and buffered-job coordination.
+ */
+export declare class DependencyCompletionStore {
+    private readonly db;
+    private readonly insert;
+    private readonly deleteJob;
+    private readonly deleteResult;
+    private readonly deleteFlowFailures;
+    private readonly pruneThrough;
+    private readonly maxSequence;
+    private readonly loadAll;
+    private readonly deleteOne;
+    private readonly pinOne;
+    private readonly unpinOne;
+    private readonly unpinAll;
+    private readonly loadQueue;
+    private readonly deleteQueue;
+    constructor(db: Database);
+    commit(record: DependencyCompletionRecord, retentionLimit: number): void;
+    load(): DependencyCompletionRecord[];
+    private loadRecords;
+    pin(jobIds: Iterable<JobId>): void;
+    unpin(jobIds: Iterable<JobId>, retentionLimit: number): DependencyCompletionRecord[];
+    reconcilePins(referenced: ReadonlySet<JobId>, retentionLimit: number): DependencyCompletionRecord[];
+    private prune;
+    delete(jobId: JobId): boolean;
+    deleteForQueue(queue: string): JobId[];
+}

package/dist/infrastructure/persistence/dependencyCompletionStore.js

@@ -0,0 +1,105 @@
+/**
+ * SQLite operations for payload-free `removeOnComplete` completion evidence.
+ * The owner supplies write-error handling and buffered-job coordination.
+ */
+export class DependencyCompletionStore {
+    db;
+    insert;
+    deleteJob;
+    deleteResult;
+    deleteFlowFailures;
+    pruneThrough;
+    maxSequence;
+    loadAll;
+    deleteOne;
+    pinOne;
+    unpinOne;
+    unpinAll;
+    loadQueue;
+    deleteQueue;
+    constructor(db) {
+        this.db = db;
+        this.insert = db.prepare(`INSERT INTO dependency_completions (job_id, queue, completed_at, pinned)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(job_id) DO UPDATE SET
+         queue=excluded.queue,
+         completed_at=excluded.completed_at,
+         pinned=MAX(dependency_completions.pinned, excluded.pinned)
+       RETURNING sequence`);
+        this.deleteJob = db.prepare('DELETE FROM jobs WHERE id = ?');
+        this.deleteResult = db.prepare('DELETE FROM job_results WHERE job_id = ?');
+        this.deleteFlowFailures = db.prepare('DELETE FROM flow_failures WHERE parent_id = ?');
+        this.pruneThrough = db.prepare('DELETE FROM dependency_completions WHERE pinned = 0 AND sequence <= ?');
+        this.maxSequence = db.prepare('SELECT COALESCE(MAX(sequence), 0) AS sequence FROM dependency_completions');
+        this.loadAll = db.prepare('SELECT job_id, queue, completed_at, pinned FROM dependency_completions ORDER BY sequence');
+        this.deleteOne = db.prepare('DELETE FROM dependency_completions WHERE job_id = ? AND pinned = 0');
+        this.pinOne = db.prepare('UPDATE dependency_completions SET pinned = 1 WHERE job_id = ?');
+        this.unpinOne = db.prepare('UPDATE dependency_completions SET pinned = 0 WHERE job_id = ?');
+        this.unpinAll = db.prepare('UPDATE dependency_completions SET pinned = 0');
+        this.loadQueue = db.prepare('SELECT job_id FROM dependency_completions WHERE queue = ? ORDER BY sequence');
+        this.deleteQueue = db.prepare('DELETE FROM dependency_completions WHERE queue = ?');
+    }
+    commit(record, retentionLimit) {
+        const limit = Math.max(1, Math.trunc(retentionLimit));
+        this.db.transaction(() => {
+            const inserted = this.insert.get(record.jobId, record.queue, record.completedAt, record.pinned ? 1 : 0);
+            if (!inserted)
+                throw new Error(`Failed to persist completion for ${String(record.jobId)}`);
+            this.pruneThrough.run(inserted.sequence - limit);
+            this.deleteJob.run(record.jobId);
+            this.deleteResult.run(record.jobId);
+            this.deleteFlowFailures.run(record.jobId);
+        })();
+    }
+    load() {
+        return this.loadRecords();
+    }
+    loadRecords() {
+        const rows = this.loadAll.all();
+        return rows.map((row) => ({
+            jobId: row.job_id,
+            queue: row.queue,
+            completedAt: row.completed_at,
+            pinned: row.pinned === 1,
+        }));
+    }
+    pin(jobIds) {
+        this.db.transaction(() => {
+            for (const jobId of jobIds)
+                this.pinOne.run(jobId);
+        })();
+    }
+    unpin(jobIds, retentionLimit) {
+        return this.db.transaction(() => {
+            for (const jobId of jobIds)
+                this.unpinOne.run(jobId);
+            this.prune(retentionLimit);
+            return this.loadRecords();
+        })();
+    }
+    reconcilePins(referenced, retentionLimit) {
+        return this.db.transaction(() => {
+            this.unpinAll.run();
+            for (const jobId of referenced)
+                this.pinOne.run(jobId);
+            this.prune(retentionLimit);
+            return this.loadRecords();
+        })();
+    }
+    prune(retentionLimit) {
+        const limit = Math.max(1, Math.trunc(retentionLimit));
+        const latest = this.maxSequence.get();
+        this.pruneThrough.run(latest.sequence - limit);
+    }
+    delete(jobId) {
+        const result = this.deleteOne.run(jobId);
+        return result.changes > 0;
+    }
+    deleteForQueue(queue) {
+        return this.db.transaction(() => {
+            const rows = this.loadQueue.all(queue);
+            this.deleteQueue.run(queue);
+            return rows.map((row) => row.job_id);
+        })();
+    }
+}

package/dist/infrastructure/persistence/schema.d.ts

@@ -1,13 +1,10 @@
-/**
- * SQLite schema and migrations
- */
 /** SQLite PRAGMA settings for optimal performance */
 export declare const PRAGMA_SETTINGS = "\nPRAGMA journal_mode = WAL;\nPRAGMA synchronous = NORMAL;\nPRAGMA cache_size = -64000;\nPRAGMA temp_store = MEMORY;\nPRAGMA mmap_size = 268435456;\nPRAGMA page_size = 4096;\nPRAGMA busy_timeout = 5000;\n";
 /** Main schema creation */
-export declare const SCHEMA = "\n-- Jobs table (using UUIDv7 for job IDs)\n-- Uses BLOB for data fields (MessagePack serialization for ~2-3x faster than JSON)\nCREATE TABLE IF NOT EXISTS jobs (\n    id TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    priority INTEGER NOT NULL DEFAULT 0,\n    created_at INTEGER NOT NULL,\n    run_at INTEGER NOT NULL,\n    started_at INTEGER,\n    completed_at INTEGER,\n    attempts INTEGER NOT NULL DEFAULT 0,\n    max_attempts INTEGER NOT NULL DEFAULT 3,\n    backoff INTEGER NOT NULL DEFAULT 1000,\n    ttl INTEGER,\n    timeout INTEGER,\n    unique_key TEXT,\n    custom_id TEXT,\n    depends_on BLOB,\n    parent_id TEXT,\n    children_ids BLOB,\n    tags BLOB,\n    state TEXT NOT NULL DEFAULT 'waiting',\n    lifo INTEGER NOT NULL DEFAULT 0,\n    group_id TEXT,\n    progress INTEGER DEFAULT 0,\n    progress_msg TEXT,\n    remove_on_complete INTEGER DEFAULT 0,\n    remove_on_fail INTEGER DEFAULT 0,\n    fail_parent_on_failure INTEGER NOT NULL DEFAULT 0,\n    remove_dependency_on_failure INTEGER NOT NULL DEFAULT 0,\n    continue_parent_on_failure INTEGER NOT NULL DEFAULT 0,\n    ignore_dependency_on_failure INTEGER NOT NULL DEFAULT 0,\n    stall_timeout INTEGER,\n    last_heartbeat INTEGER,\n    stall_count INTEGER NOT NULL DEFAULT 0,\n    timeline BLOB,\n    stacktrace BLOB\n);\n\n-- Indexes for common queries\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_state\n    ON jobs(queue, state);\n-- Stable createdAt/id pagination for unfiltered and logical-state queue views\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_created\n    ON jobs(queue, created_at, id);\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_state_created\n    ON jobs(queue, state, created_at, id);\nCREATE INDEX IF NOT EXISTS idx_jobs_run_at\n    ON jobs(run_at) WHERE state IN ('waiting', 'prioritized', 'waiting-children', 'delayed');\nCREATE INDEX IF NOT EXISTS idx_jobs_unique\n    ON jobs(queue, unique_key) WHERE unique_key IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_custom_id\n    ON jobs(custom_id) WHERE custom_id IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_parent\n    ON jobs(parent_id) WHERE parent_id IS NOT NULL;\n\n-- Durable outbox/state for terminal child failure propagation.\nCREATE TABLE IF NOT EXISTS flow_failures (\n    parent_id TEXT NOT NULL,\n    child_id TEXT NOT NULL,\n    child_queue TEXT NOT NULL,\n    mode TEXT NOT NULL,\n    error TEXT NOT NULL,\n    created_at INTEGER NOT NULL,\n    PRIMARY KEY (parent_id, child_id)\n);\nCREATE INDEX IF NOT EXISTS idx_flow_failures_parent ON flow_failures(parent_id);\n\n-- Job results storage (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS job_results (\n    job_id TEXT PRIMARY KEY,\n    result BLOB,\n    completed_at INTEGER NOT NULL\n);\n\n-- Dead letter queue (BLOB for MessagePack - stores full DlqEntry)\nCREATE TABLE IF NOT EXISTS dlq (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    job_id TEXT NOT NULL,\n    queue TEXT NOT NULL,\n    entry BLOB NOT NULL,\n    entered_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_dlq_queue ON dlq(queue);\nCREATE INDEX IF NOT EXISTS idx_dlq_job_id ON dlq(job_id);\nCREATE INDEX IF NOT EXISTS idx_dlq_entered_at ON dlq(entered_at);\n\n-- Performance indexes for high-throughput operations\n-- Stall detection: runs every 5s, needs fast lookup of active jobs by started_at\nCREATE INDEX IF NOT EXISTS idx_jobs_state_started\n    ON jobs(state, started_at) WHERE state = 'active';\n\n-- Group operations: fast lookup by group_id\nCREATE INDEX IF NOT EXISTS idx_jobs_group_id\n    ON jobs(group_id) WHERE group_id IS NOT NULL;\n\n-- Pending jobs: compound index for priority-ordered retrieval\nCREATE INDEX IF NOT EXISTS idx_jobs_pending_priority\n    ON jobs(queue, state, priority DESC, run_at ASC) WHERE state IN ('waiting', 'prioritized', 'waiting-children', 'delayed');\n\n-- Completed jobs: index for recovery ordering (issue #84)\nCREATE INDEX IF NOT EXISTS idx_jobs_completed_order\n    ON jobs(completed_at DESC) WHERE state = 'completed';\n\n-- Cron jobs (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS cron_jobs (\n    name TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    schedule TEXT,\n    repeat_every INTEGER,\n    priority INTEGER NOT NULL DEFAULT 0,\n    next_run INTEGER NOT NULL,\n    executions INTEGER NOT NULL DEFAULT 0,\n    max_limit INTEGER,\n    timezone TEXT,\n    unique_key TEXT,\n    dedup BLOB,\n    skip_missed_on_restart INTEGER NOT NULL DEFAULT 0,\n    skip_if_no_worker INTEGER NOT NULL DEFAULT 0,\n    prevent_overlap INTEGER NOT NULL DEFAULT 1,\n    job_options BLOB\n);\n\n-- Queue state persistence (optional)\nCREATE TABLE IF NOT EXISTS queue_state (\n    name TEXT PRIMARY KEY,\n    paused INTEGER NOT NULL DEFAULT 0,\n    rate_limit INTEGER,\n    concurrency_limit INTEGER,\n    rate_limit_duration INTEGER,\n    rate_limit_expires_at INTEGER,\n    stall_enabled INTEGER,\n    stall_interval INTEGER,\n    max_stalls INTEGER,\n    stall_grace_period INTEGER,\n    dlq_config BLOB\n);\n";
+export declare const SCHEMA = "\n-- Jobs table (using UUIDv7 for job IDs)\n-- Uses BLOB for data fields (MessagePack serialization for ~2-3x faster than JSON)\nCREATE TABLE IF NOT EXISTS jobs (\n    id TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    priority INTEGER NOT NULL DEFAULT 0,\n    created_at INTEGER NOT NULL,\n    run_at INTEGER NOT NULL,\n    started_at INTEGER,\n    completed_at INTEGER,\n    attempts INTEGER NOT NULL DEFAULT 0,\n    max_attempts INTEGER NOT NULL DEFAULT 3,\n    backoff INTEGER NOT NULL DEFAULT 1000,\n    ttl INTEGER,\n    timeout INTEGER,\n    unique_key TEXT,\n    custom_id TEXT,\n    depends_on BLOB,\n    parent_id TEXT,\n    children_ids BLOB,\n    tags BLOB,\n    state TEXT NOT NULL DEFAULT 'waiting',\n    lifo INTEGER NOT NULL DEFAULT 0,\n    group_id TEXT,\n    progress INTEGER DEFAULT 0,\n    progress_msg TEXT,\n    remove_on_complete INTEGER DEFAULT 0,\n    remove_on_fail INTEGER DEFAULT 0,\n    fail_parent_on_failure INTEGER NOT NULL DEFAULT 0,\n    remove_dependency_on_failure INTEGER NOT NULL DEFAULT 0,\n    continue_parent_on_failure INTEGER NOT NULL DEFAULT 0,\n    ignore_dependency_on_failure INTEGER NOT NULL DEFAULT 0,\n    stall_timeout INTEGER,\n    last_heartbeat INTEGER,\n    stall_count INTEGER NOT NULL DEFAULT 0,\n    timeline BLOB,\n    stacktrace BLOB\n);\n\n-- Indexes for common queries\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_state\n    ON jobs(queue, state);\n-- Stable createdAt/id pagination for unfiltered and logical-state queue views\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_created\n    ON jobs(queue, created_at, id);\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_state_created\n    ON jobs(queue, state, created_at, id);\nCREATE INDEX IF NOT EXISTS idx_jobs_run_at\n    ON jobs(run_at) WHERE state IN ('waiting', 'prioritized', 'waiting-children', 'delayed');\nCREATE INDEX IF NOT EXISTS idx_jobs_unique\n    ON jobs(queue, unique_key) WHERE unique_key IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_custom_id\n    ON jobs(custom_id) WHERE custom_id IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_parent\n    ON jobs(parent_id) WHERE parent_id IS NOT NULL;\n\n-- Durable outbox/state for terminal child failure propagation.\nCREATE TABLE IF NOT EXISTS flow_failures (\n    parent_id TEXT NOT NULL,\n    child_id TEXT NOT NULL,\n    child_queue TEXT NOT NULL,\n    mode TEXT NOT NULL,\n    error TEXT NOT NULL,\n    created_at INTEGER NOT NULL,\n    PRIMARY KEY (parent_id, child_id)\n);\nCREATE INDEX IF NOT EXISTS idx_flow_failures_parent ON flow_failures(parent_id);\n\n\nCREATE TABLE IF NOT EXISTS dependency_completions (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    job_id TEXT NOT NULL UNIQUE,\n    queue TEXT NOT NULL,\n    completed_at INTEGER NOT NULL,\n    pinned INTEGER NOT NULL DEFAULT 0\n);\nCREATE INDEX IF NOT EXISTS idx_dependency_completions_queue\n    ON dependency_completions(queue);\n\n\n-- Job results storage (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS job_results (\n    job_id TEXT PRIMARY KEY,\n    result BLOB,\n    completed_at INTEGER NOT NULL\n);\n\n-- Dead letter queue (BLOB for MessagePack - stores full DlqEntry)\nCREATE TABLE IF NOT EXISTS dlq (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    job_id TEXT NOT NULL,\n    queue TEXT NOT NULL,\n    entry BLOB NOT NULL,\n    entered_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_dlq_queue ON dlq(queue);\nCREATE INDEX IF NOT EXISTS idx_dlq_job_id ON dlq(job_id);\nCREATE INDEX IF NOT EXISTS idx_dlq_entered_at ON dlq(entered_at);\n\n-- Performance indexes for high-throughput operations\n-- Stall detection: runs every 5s, needs fast lookup of active jobs by started_at\nCREATE INDEX IF NOT EXISTS idx_jobs_state_started\n    ON jobs(state, started_at) WHERE state = 'active';\n\n-- Group operations: fast lookup by group_id\nCREATE INDEX IF NOT EXISTS idx_jobs_group_id\n    ON jobs(group_id) WHERE group_id IS NOT NULL;\n\n-- Pending jobs: compound index for priority-ordered retrieval\nCREATE INDEX IF NOT EXISTS idx_jobs_pending_priority\n    ON jobs(queue, state, priority DESC, run_at ASC) WHERE state IN ('waiting', 'prioritized', 'waiting-children', 'delayed');\n\n-- Completed jobs: index for recovery ordering (issue #84)\nCREATE INDEX IF NOT EXISTS idx_jobs_completed_order\n    ON jobs(completed_at DESC) WHERE state = 'completed';\n\n-- Cron jobs (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS cron_jobs (\n    name TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    schedule TEXT,\n    repeat_every INTEGER,\n    priority INTEGER NOT NULL DEFAULT 0,\n    next_run INTEGER NOT NULL,\n    executions INTEGER NOT NULL DEFAULT 0,\n    max_limit INTEGER,\n    timezone TEXT,\n    unique_key TEXT,\n    dedup BLOB,\n    skip_missed_on_restart INTEGER NOT NULL DEFAULT 0,\n    skip_if_no_worker INTEGER NOT NULL DEFAULT 0,\n    prevent_overlap INTEGER NOT NULL DEFAULT 1,\n    job_options BLOB\n);\n\n-- Queue state persistence (optional)\nCREATE TABLE IF NOT EXISTS queue_state (\n    name TEXT PRIMARY KEY,\n    paused INTEGER NOT NULL DEFAULT 0,\n    rate_limit INTEGER,\n    concurrency_limit INTEGER,\n    rate_limit_duration INTEGER,\n    rate_limit_expires_at INTEGER,\n    stall_enabled INTEGER,\n    stall_interval INTEGER,\n    max_stalls INTEGER,\n    stall_grace_period INTEGER,\n    dlq_config BLOB\n);\n";
 /** Migration version table */
 export declare const MIGRATION_TABLE = "\nCREATE TABLE IF NOT EXISTS migrations (\n    version INTEGER PRIMARY KEY,\n    applied_at INTEGER NOT NULL\n);\n";
 /** Current schema version */
-export declare const SCHEMA_VERSION = 27;
+export declare const SCHEMA_VERSION = 29;
 /** All migrations in order */
 export declare const MIGRATIONS: Record<number, string>;

package/dist/infrastructure/persistence/schema.js

@@ -1,6 +1,7 @@
 /**
  * SQLite schema and migrations
  */
+import { DEPENDENCY_COMPLETION_SCHEMA } from './dependencyCompletionSchema';
 /** SQLite PRAGMA settings for optimal performance */
 export const PRAGMA_SETTINGS = `
 PRAGMA journal_mode = WAL;
@@ -82,6 +83,8 @@ CREATE TABLE IF NOT EXISTS flow_failures (
 );
 CREATE INDEX IF NOT EXISTS idx_flow_failures_parent ON flow_failures(parent_id);
 
+${DEPENDENCY_COMPLETION_SCHEMA}
+
 -- Job results storage (BLOB for MessagePack)
 CREATE TABLE IF NOT EXISTS job_results (
     job_id TEXT PRIMARY KEY,
@@ -162,7 +165,7 @@ CREATE TABLE IF NOT EXISTS migrations (
 );
 `;
 /** Current schema version */
-export const SCHEMA_VERSION = 27;
+export const SCHEMA_VERSION = 29;
 /** All migrations in order */
 export const MIGRATIONS = {
     1: SCHEMA,
@@ -290,4 +293,6 @@ DROP INDEX IF EXISTS idx_jobs_pending_priority;
 CREATE INDEX idx_jobs_pending_priority
     ON jobs(queue, state, priority DESC, run_at ASC) WHERE state IN ('waiting', 'prioritized', 'waiting-children', 'delayed');
 `,
+    28: DEPENDENCY_COMPLETION_SCHEMA,
+    29: 'ALTER TABLE dependency_completions ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0;',
 };

package/dist/infrastructure/persistence/sqlite.d.ts

@@ -8,6 +8,7 @@ import type { FlowFailureRecord } from '../../domain/types/flow';
 import type { StallConfig } from '../../domain/types/stall';
 import type { CronJob } from '../../domain/types/cron';
 import { type DlqConfig, type DlqEntry } from '../../domain/types/dlq';
+import { type DependencyCompletionRecord } from './dependencyCompletionStore';
 /** Critical-loss callback: invoked when WriteBuffer drops jobs after exhausting retries. */
 export type SqliteCriticalLossCallback = (jobs: Job[], lastError: Error, attempts: number) => void;
 /** Record of a critical job loss event (jobs dropped after max retries). */
@@ -38,6 +39,7 @@ export declare class SqliteStorage {
     private readonly statements;
     private readonly batchManager;
     private readonly writeBuffer;
+    private readonly dependencyCompletionStore;
     private _diskFull;
     private _lastDiskFullError;
     private _lastDiskFullAt;
@@ -137,6 +139,15 @@ export declare class SqliteStorage {
     updateJobChildrenIds(jobId: JobId, childrenIds: JobId[]): void;
     /** Persist both sides of a legacy parent link in one SQLite transaction. */
     updateFlowLink(child: Pick<Job, 'id' | 'parentId' | 'data'>, parent: Pick<Job, 'id' | 'childrenIds' | 'dependsOn' | 'data'>, parentState: 'waiting-children' | 'waiting' | 'prioritized' | 'delayed'): void;
+    /**
+     * Persist a legacy SDK parent-id backpatch without changing parent state.
+     *
+     * A fast child can finish before the SDK sends UpdateParent. Completed jobs
+     * remain in `jobs`, while failed jobs live only in the serialized DLQ entry.
+     * The failure outbox is re-keyed in the same transaction so a crash between
+     * this write and in-memory propagation still targets the real parent.
+     */
+    backpatchFlowChild(child: Pick<Job, 'id' | 'parentId' | 'data'>, previousParentId: JobId | null): void;
     /** Persist both sides of a removed parent/child relationship atomically. */
     removeFlowLink(child: Pick<Job, 'id' | 'parentId' | 'data'>, parent: Pick<Job, 'id' | 'childrenIds' | 'dependsOn' | 'data' | 'runAt'>, parentState: 'waiting-children' | 'waiting' | 'prioritized'): void;
     /** Record terminal child propagation before applying its parent-side effect. */
@@ -144,7 +155,7 @@ export declare class SqliteStorage {
     loadFlowFailures(): FlowFailureRecord[];
     deleteFlowFailure(parentId: JobId, childId?: JobId): void;
     /** Persist dependency removal/promotion as one parent-side recovery checkpoint. */
-    updateFlowParentResolution(job: Pick<Job, 'id' | 'dependsOn' | 'runAt' | 'priority'>): void;
+    updateFlowParentResolution(job: Pick<Job, 'id' | 'dependsOn' | 'runAt' | 'priority' | 'timeline'>, stateOverride?: 'waiting-children' | 'waiting' | 'prioritized' | 'delayed'): void;
     getJob(id: JobId): Job | null;
     storeResult(jobId: JobId, result: unknown): void;
     getResult(jobId: JobId): unknown;
@@ -160,6 +171,14 @@ export declare class SqliteStorage {
     getJobStateRaw(jobId: JobId): string | null;
     /** Load all completed job IDs (for dependency recovery) */
     loadCompletedJobIds(): Set<JobId>;
+    /** Atomically replace a removed completed job with payload-free dependency evidence. */
+    commitRemovedCompletion(job: Pick<Job, 'id' | 'queue'>, retentionLimit: number, pinned: boolean, completedAt?: number): void;
+    loadDependencyCompletions(): DependencyCompletionRecord[];
+    pinDependencyCompletions(jobIds: Iterable<JobId>): void;
+    unpinDependencyCompletions(jobIds: Iterable<JobId>, retentionLimit: number): DependencyCompletionRecord[];
+    reconcileDependencyCompletionPins(referenced: ReadonlySet<JobId>, retentionLimit: number): DependencyCompletionRecord[];
+    deleteDependencyCompletion(jobId: JobId): boolean;
+    deleteDependencyCompletionsForQueue(queue: string): JobId[];
     /**
      * Insert batch of jobs. By default the jobs go through the write buffer.
      * When `durable` is true they bypass the buffer and are written to disk

package/dist/infrastructure/persistence/sqlite.js

@@ -10,6 +10,7 @@ import { prepareStatements, } from './statements';
 import { pack, persistedInitialState, persistedStallCount, reconstructDlqEntry, rowToJob, unpack, } from './sqliteSerializer';
 import { BatchInsertManager, WriteBuffer } from './sqliteBatch';
 import { storageLog } from '../../shared/logger';
+import { DependencyCompletionStore, } from './dependencyCompletionStore';
 /** Check if an error is a SQLITE_FULL (disk full) error */
 function isSqliteFullError(err) {
     if (!(err instanceof Error))
@@ -25,6 +26,7 @@ export class SqliteStorage {
     statements;
     batchManager;
     writeBuffer;
+    dependencyCompletionStore;
     _diskFull = false;
     _lastDiskFullError = null;
     _lastDiskFullAt = null;
@@ -48,6 +50,7 @@ export class SqliteStorage {
             });
         }
         this.migrate();
+        this.dependencyCompletionStore = new DependencyCompletionStore(this.db);
         this.statements = prepareStatements(this.db);
         this._onCriticalLoss = config.onCriticalLoss;
         // Initialize batch manager and write buffer
@@ -491,6 +494,62 @@ export class SqliteStorage {
             tx();
         });
     }
+    /**
+     * Persist a legacy SDK parent-id backpatch without changing parent state.
+     *
+     * A fast child can finish before the SDK sends UpdateParent. Completed jobs
+     * remain in `jobs`, while failed jobs live only in the serialized DLQ entry.
+     * The failure outbox is re-keyed in the same transaction so a crash between
+     * this write and in-memory propagation still targets the real parent.
+     */
+    backpatchFlowChild(child, previousParentId) {
+        this.flushIfBuffered(child.id);
+        this.safeWrite(() => {
+            const tx = this.db.transaction(() => {
+                let persisted = this.db
+                    .prepare('UPDATE jobs SET parent_id = ?, data = ? WHERE id = ?')
+                    .run(child.parentId, pack(child.data), child.id).changes > 0;
+                const dlqRows = this.db
+                    .query('SELECT id, entry FROM dlq WHERE job_id = ?')
+                    .all(String(child.id));
+                for (const row of dlqRows) {
+                    const entry = unpack(row.entry, null, `backpatchFlowChild:${String(child.id)}`);
+                    if (!entry?.job)
+                        continue;
+                    const updated = {
+                        ...entry,
+                        job: { ...entry.job, parentId: child.parentId, data: child.data },
+                    };
+                    this.db.prepare('UPDATE dlq SET entry = ? WHERE id = ?').run(pack(updated), row.id);
+                    persisted = true;
+                }
+                if (!persisted) {
+                    throw new Error(`Flow child is no longer persisted: ${String(child.id)}`);
+                }
+                if (previousParentId && child.parentId && previousParentId !== child.parentId) {
+                    const failure = this.db
+                        .query(`SELECT child_queue, mode, error, created_at
+               FROM flow_failures
+               WHERE parent_id = ? AND child_id = ?`)
+                        .get(String(previousParentId), String(child.id));
+                    if (failure) {
+                        this.db
+                            .prepare(`INSERT INTO flow_failures
+                 (parent_id, child_id, child_queue, mode, error, created_at)
+                 VALUES (?, ?, ?, ?, ?, ?)
+                 ON CONFLICT(parent_id, child_id) DO UPDATE SET
+                   child_queue=excluded.child_queue, mode=excluded.mode,
+                   error=excluded.error, created_at=excluded.created_at`)
+                            .run(child.parentId, child.id, failure.child_queue, failure.mode, failure.error, failure.created_at);
+                        this.db
+                            .prepare('DELETE FROM flow_failures WHERE parent_id = ? AND child_id = ?')
+                            .run(previousParentId, child.id);
+                    }
+                }
+            });
+            tx();
+        });
+    }
     /** Persist both sides of a removed parent/child relationship atomically. */
     removeFlowLink(child, parent, parentState) {
         this.flushIfBuffered(child.id);
@@ -551,19 +610,20 @@ export class SqliteStorage {
         });
     }
     /** Persist dependency removal/promotion as one parent-side recovery checkpoint. */
-    updateFlowParentResolution(job) {
+    updateFlowParentResolution(job, stateOverride) {
         this.flushIfBuffered(job.id);
-        const state = job.dependsOn.length > 0
-            ? 'waiting-children'
-            : job.runAt > Date.now()
-                ? 'delayed'
-                : job.priority > 0
-                    ? 'prioritized'
-                    : 'waiting';
+        const state = stateOverride ??
+            (job.dependsOn.length > 0
+                ? 'waiting-children'
+                : job.runAt > Date.now()
+                    ? 'delayed'
+                    : job.priority > 0
+                        ? 'prioritized'
+                        : 'waiting');
         this.safeWrite(() => {
             this.db
-                .prepare('UPDATE jobs SET depends_on = ?, run_at = ?, state = ? WHERE id = ?')
-                .run(job.dependsOn.length > 0 ? pack(job.dependsOn) : null, job.runAt, state, job.id);
+                .prepare('UPDATE jobs SET depends_on = ?, run_at = ?, state = ?, timeline = ? WHERE id = ?')
+                .run(job.dependsOn.length > 0 ? pack(job.dependsOn) : null, job.runAt, state, job.timeline.length > 0 ? pack(job.timeline) : null, job.id);
         });
     }
     getJob(id) {
@@ -617,18 +677,62 @@ export class SqliteStorage {
     }
     /** Load all completed job IDs (for dependency recovery) */
     loadCompletedJobIds() {
-        const rows = this.db.query('SELECT job_id FROM job_results').all();
-        const ids = new Set(rows.map((r) => r.job_id));
-        // A job acked with no/undefined result has state='completed' but NO job_results
-        // row. Include state='completed' ids so dependency recovery still sees it as
-        // done and unblocks dependents (instead of parking them forever).
+        // `jobs.state` is the completion authority. A result row can exist while its
+        // job is still active if a process dies between the two legacy writes, so it
+        // must never release a dependency by itself.
+        const ids = new Set();
         const stateRows = this.db
             .query("SELECT id FROM jobs WHERE state = 'completed'")
             .all();
         for (const r of stateRows)
             ids.add(r.id);
+        for (const record of this.dependencyCompletionStore.load())
+            ids.add(record.jobId);
         return ids;
     }
+    /** Atomically replace a removed completed job with payload-free dependency evidence. */
+    commitRemovedCompletion(job, retentionLimit, pinned, completedAt = Date.now()) {
+        this.writeBuffer.removePending(job.id);
+        this.safeWrite(() => {
+            this.dependencyCompletionStore.commit({ jobId: job.id, queue: job.queue, completedAt, pinned }, retentionLimit);
+        });
+    }
+    loadDependencyCompletions() {
+        return this.dependencyCompletionStore.load();
+    }
+    pinDependencyCompletions(jobIds) {
+        this.safeWrite(() => {
+            this.dependencyCompletionStore.pin(jobIds);
+        });
+    }
+    unpinDependencyCompletions(jobIds, retentionLimit) {
+        let records = [];
+        this.safeWrite(() => {
+            records = this.dependencyCompletionStore.unpin(jobIds, retentionLimit);
+        });
+        return records;
+    }
+    reconcileDependencyCompletionPins(referenced, retentionLimit) {
+        let records = [];
+        this.safeWrite(() => {
+            records = this.dependencyCompletionStore.reconcilePins(referenced, retentionLimit);
+        });
+        return records;
+    }
+    deleteDependencyCompletion(jobId) {
+        let deleted = false;
+        this.safeWrite(() => {
+            deleted = this.dependencyCompletionStore.delete(jobId);
+        });
+        return deleted;
+    }
+    deleteDependencyCompletionsForQueue(queue) {
+        let deleted = [];
+        this.safeWrite(() => {
+            deleted = this.dependencyCompletionStore.deleteForQueue(queue);
+        });
+        return deleted;
+    }
     // ============ Bulk Operations ============
     /**
      * Insert batch of jobs. By default the jobs go through the write buffer.

package/dist/infrastructure/persistence/sqliteSerializer.d.ts

@@ -32,6 +32,9 @@ export declare function persistedInitialState(job: Job, now?: number): string;
  * so it only exists on the in-memory Job for the duration of recovery.
  */
 export declare const CORRUPT_DEPENDS_ON: unique symbol;
+export type PersistedJobState = 'active' | 'completed' | 'delayed' | 'prioritized' | 'waiting' | 'waiting-children';
+/** Read the authoritative SQLite state carried by a recovered job. */
+export declare function persistedJobState(job: Job): PersistedJobState | undefined;
 /** True if a Job was recovered with a corrupt `depends_on` blob. */
 export declare function isCorruptDependsOn(job: Job): boolean;
 /** Convert database row to Job object */

package/dist/infrastructure/persistence/sqliteSerializer.js

@@ -57,6 +57,11 @@ export function persistedInitialState(job, now = Date.now()) {
  * so it only exists on the in-memory Job for the duration of recovery.
  */
 export const CORRUPT_DEPENDS_ON = Symbol('bunqueue.corruptDependsOn');
+const PERSISTED_JOB_STATE = Symbol('bunqueue.persistedJobState');
+/** Read the authoritative SQLite state carried by a recovered job. */
+export function persistedJobState(job) {
+    return job[PERSISTED_JOB_STATE];
+}
 /** True if a Job was recovered with a corrupt `depends_on` blob. */
 export function isCorruptDependsOn(job) {
     return job[CORRUPT_DEPENDS_ON] === true;
@@ -146,6 +151,11 @@ export function rowToJob(row) {
             ? unpack(row.stacktrace, null, `${jobContext}:stacktrace`)
             : null,
     };
+    Object.defineProperty(job, PERSISTED_JOB_STATE, {
+        value: row.state,
+        enumerable: false,
+        configurable: false,
+    });
     // Stamp a collision-proof corruption marker (non-enumerable Symbol, never
     // persisted) so the recovery path routes this job to the DLQ rather than
     // enqueuing it as ready. We keep dependsOn: [] here — the real deps are

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue",
-  "version": "2.8.50",
+  "version": "2.8.51",
   "description": "High-performance job queue for Bun & AI agents. SQLite persistence, cron scheduling, priorities, retries, DLQ, webhooks, native MCP server. Zero external infrastructure.",
   "type": "module",
   "main": "dist/main.js",