bunqueue 2.8.42 → 2.8.44

package/dist/infrastructure/backup/s3BackupOperations.js

@@ -1,334 +1,214 @@
 /**
- * S3 Backup Operations
- * Core backup, restore, list, and cleanup operations
+ * S3 backup, restore, listing, and retention operations.
  */
 import { backupLog } from '../../shared/logger';
 import { VERSION } from '../../shared/version';
-const DEFAULT_S3_TIMEOUT_MS = 30_000;
-/** Race a promise against a timeout; rejects with a descriptive error on timeout */
-function withTimeout(promise, ms, label) {
-    return Promise.race([
-        promise,
-        new Promise((_, reject) => {
-            setTimeout(() => {
-                reject(new Error(`${label} timed out after ${ms}ms`));
-            }, ms);
-        }),
-    ]);
+import { createConsistentSnapshot, installDatabaseCandidate, removeDatabaseArtifacts, verifyDatabaseIntegrity, } from './sqliteBackupFiles';
+import { cleanupFailedPayload, DEFAULT_S3_TIMEOUT_MS, gunzipAsync, gzipAsync, retryWithTimeout, sha256, } from './s3BackupIo';
+function timeoutFor(config) {
+    return config.timeoutMs ?? DEFAULT_S3_TIMEOUT_MS;
 }
-/** Check if an error is transient and worth retrying */
-function isTransientError(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const lower = message.toLowerCase();
-    return (lower.includes('connection reset') ||
-        lower.includes('econnreset') ||
-        lower.includes('timeout') ||
-        lower.includes('etimedout') ||
-        lower.includes('econnrefused') ||
-        lower.includes('socket hang up') ||
-        lower.includes('network') ||
-        lower.includes('503') ||
-        lower.includes('500') ||
-        lower.includes('502') ||
-        lower.includes('504') ||
-        lower.includes('service unavailable') ||
-        lower.includes('internal server error') ||
-        lower.includes('bad gateway') ||
-        lower.includes('gateway timeout') ||
-        lower.includes('transient'));
+function backupKey(prefix) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return `${prefix}bunqueue-${timestamp}-${crypto.randomUUID()}.db`;
 }
-/** Retry an async operation with exponential backoff (500ms, 1000ms, 2000ms) */
-async function withRetry(fn, label, maxRetries = 3, baseDelayMs = 500) {
-    let lastError;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        try {
-            return await fn();
-        }
-        catch (error) {
-            lastError = error;
-            if (attempt < maxRetries && isTransientError(error)) {
-                const delay = baseDelayMs * Math.pow(2, attempt);
-                backupLog.warn(`${label} failed (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms`, { error: error instanceof Error ? error.message : String(error) });
-                await new Promise((resolve) => setTimeout(resolve, delay));
-            }
-            else {
-                throw error;
-            }
-        }
+function restoreCandidatePath(databasePath) {
+    return `${databasePath}.restore-${Date.now()}-${crypto.randomUUID()}.tmp`;
+}
+function isGzip(data) {
+    return data.byteLength >= 2 && data[0] === 0x1f && data[1] === 0x8b;
+}
+function validateMetadata(value, compressedSize) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('Backup metadata is invalid');
+    }
+    const metadata = value;
+    if (typeof metadata.timestamp !== 'string' ||
+        typeof metadata.version !== 'string' ||
+        !Number.isSafeInteger(metadata.size) ||
+        (metadata.size ?? -1) < 0 ||
+        !Number.isSafeInteger(metadata.compressedSize) ||
+        metadata.compressedSize !== compressedSize ||
+        typeof metadata.checksum !== 'string' ||
+        !/^[a-f0-9]{64}$/i.test(metadata.checksum) ||
+        metadata.compressed !== true) {
+        throw new Error('Backup metadata is invalid or does not match the payload');
     }
-    throw lastError;
+    return metadata;
 }
-/**
- * Verify database integrity via PRAGMA integrity_check.
- *
- * Validates the file at `databasePath` and throws on failure. This function
- * is intended to run against a TEMP file (never the live DB): on integrity
- * failure it deletes the file it inspected, so it must only ever be pointed
- * at a throwaway candidate, not the live database.
- */
-async function verifyDatabaseIntegrity(databasePath) {
-    const { Database } = await import('bun:sqlite');
-    let db = null;
+async function cleanupLocalArtifacts(path, label) {
+    if (!path)
+        return;
     try {
-        db = new Database(databasePath);
-        const result = db.query('PRAGMA integrity_check').get();
-        const status = result?.integrity_check ?? '';
-        if (status !== 'ok') {
-            throw new Error(`Database integrity check failed: ${status || 'unknown error'}`);
-        }
+        await removeDatabaseArtifacts(path);
     }
     catch (error) {
-        // Close before unlinking so the file handle is released.
-        try {
-            db?.close();
-        }
-        catch {
-            /* already closed */
-        }
-        db = null;
-        // Clean up the corrupt candidate file (this is a temp file, never the live DB).
-        try {
-            const { unlink } = await import('fs/promises');
-            await unlink(databasePath);
-        }
-        catch {
-            /* best effort */
-        }
-        if (error instanceof Error && error.message.includes('integrity check failed')) {
-            throw error;
-        }
-        throw new Error('Database integrity check failed: corrupt or invalid database', {
-            cause: error,
-        });
+        backupLog.warn(`Failed to clean ${label} artifacts`, { path, error: String(error) });
     }
-    finally {
-        try {
-            db?.close();
-        }
-        catch {
-            /* already closed */
-        }
-    }
-}
-/** Async gzip compress using Web Streams API (non-blocking) */
-async function gzipAsync(data) {
-    const stream = new Blob([data])
-        .stream()
-        .pipeThrough(new CompressionStream('gzip'));
-    return new Uint8Array(await new Response(stream).arrayBuffer());
-}
-/** Async gzip decompress using Web Streams API (non-blocking) */
-async function gunzipAsync(data) {
-    const stream = new Blob([data])
-        .stream()
-        .pipeThrough(new DecompressionStream('gzip'));
-    return new Uint8Array(await new Response(stream).arrayBuffer());
 }
-/**
- * Perform a backup to S3
- */
+/** Create and publish a consistent SQLite backup. */
 export async function performBackup(config, client) {
     const startTime = Date.now();
+    let snapshotPath = null;
+    let pendingPayloadKey = null;
     try {
-        // Check if database file exists
-        const dbFile = Bun.file(config.databasePath);
-        const exists = await dbFile.exists();
-        if (!exists) {
+        if (!(await Bun.file(config.databasePath).exists())) {
             throw new Error(`Database file not found: ${config.databasePath}`);
         }
-        // Checkpoint WAL to ensure all data is in the main database file
-        try {
-            const { Database } = await import('bun:sqlite');
-            const db = new Database(config.databasePath);
-            db.run('PRAGMA wal_checkpoint(TRUNCATE)');
-            db.close();
-        }
-        catch {
-            // Ignore - database might be locked or not in WAL mode
-        }
-        // Generate backup key with timestamp
-        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-        const key = `${config.prefix}bunqueue-${timestamp}.db`;
-        // Read database file
-        const data = await Bun.file(config.databasePath).arrayBuffer();
-        const originalSize = data.byteLength;
-        // Compress with gzip for efficient storage
-        const compressed = await gzipAsync(new Uint8Array(data));
-        const compressedSize = compressed.byteLength;
-        // Calculate checksum of original data (for integrity verification)
-        const hasher = new Bun.CryptoHasher('sha256');
-        hasher.update(new Uint8Array(data));
-        const checksum = hasher.digest('hex');
-        // Upload compressed backup to S3 (with retry and timeout)
-        const timeoutMs = config.timeoutMs ?? DEFAULT_S3_TIMEOUT_MS;
-        const s3File = client.file(key);
-        await withTimeout(withRetry(() => s3File.write(compressed, { type: 'application/gzip' }), 'S3 backup upload'), timeoutMs, 'S3 backup upload');
-        // Upload metadata (with retry for transient errors)
+        snapshotPath = await createConsistentSnapshot(config.databasePath);
+        const data = new Uint8Array(await Bun.file(snapshotPath).arrayBuffer());
+        const compressed = await gzipAsync(data);
+        const key = backupKey(config.prefix);
+        const metadataKey = `${key}.meta.json`;
+        const timeoutMs = timeoutFor(config);
         const metadata = {
             timestamp: new Date().toISOString(),
             version: VERSION,
-            size: originalSize,
-            compressedSize,
-            checksum,
+            size: data.byteLength,
+            compressedSize: compressed.byteLength,
+            checksum: sha256(data),
             compressed: true,
         };
-        const metadataKey = `${key}.meta.json`;
-        await withTimeout(withRetry(() => client
+        // Metadata is published first. The data object is the visibility/commit
+        // point, so every successfully published current-format backup is paired.
+        await retryWithTimeout(() => client
             .file(metadataKey)
-            .write(JSON.stringify(metadata, null, 2), { type: 'application/json' }), 'S3 metadata upload'), timeoutMs, 'S3 metadata upload');
-        const duration = Date.now() - startTime;
-        return { success: true, key, size: originalSize, duration };
+            .write(JSON.stringify(metadata, null, 2), { type: 'application/json' }), timeoutMs, 'S3 metadata upload');
+        pendingPayloadKey = key;
+        await retryWithTimeout(() => client.file(key).write(compressed, { type: 'application/gzip' }), timeoutMs, 'S3 backup upload');
+        pendingPayloadKey = null;
+        return {
+            success: true,
+            key,
+            size: data.byteLength,
+            compressedSize: compressed.byteLength,
+            duration: Date.now() - startTime,
+        };
     }
     catch (error) {
+        if (pendingPayloadKey) {
+            await cleanupFailedPayload(client, pendingPayloadKey, timeoutFor(config), error);
+        }
         const message = error instanceof Error ? error.message : String(error);
         backupLog.error('Backup failed', { error: message });
         return { success: false, error: message };
     }
+    finally {
+        await cleanupLocalArtifacts(snapshotPath, 'backup snapshot');
+    }
 }
-/**
- * List available backups
- */
+/** List every backup object under the configured prefix. */
 export async function listBackups(config, client) {
     try {
-        const allContents = [];
+        const contents = [];
+        const seenTokens = new Set();
+        const timeoutMs = timeoutFor(config);
         let continuationToken;
         do {
-            const result = await client.list({
+            const result = await retryWithTimeout(() => client.list({
                 prefix: config.prefix,
                 maxKeys: 100,
                 ...(continuationToken ? { continuationToken } : {}),
-            });
-            if (result.contents) {
-                allContents.push(...result.contents);
+            }), timeoutMs, 'S3 backup list');
+            if (result.contents)
+                contents.push(...result.contents);
+            if (!result.isTruncated) {
+                continuationToken = undefined;
+                continue;
+            }
+            const next = result.nextContinuationToken;
+            if (!next || seenTokens.has(next)) {
+                throw new Error('S3 backup list returned an invalid continuation token');
             }
-            continuationToken = result.isTruncated ? result.nextContinuationToken : undefined;
+            seenTokens.add(next);
+            continuationToken = next;
         } while (continuationToken);
-        return allContents
-            .filter((item) => typeof item.key === 'string' &&
-            item.key.endsWith('.db') &&
-            !item.key.endsWith('.meta.json'))
-            .map((item) => {
-            const lastMod = item.lastModified;
-            const lastModDate = lastMod ? new Date(lastMod) : new Date();
-            return {
-                key: item.key,
-                size: item.size ?? 0,
-                lastModified: lastModDate,
-            };
-        })
+        return contents
+            .filter((item) => typeof item.key === 'string' && item.key.endsWith('.db'))
+            .map((item) => ({
+            key: item.key,
+            size: item.size ?? 0,
+            lastModified: item.lastModified ? new Date(item.lastModified) : new Date(),
+        }))
             .sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
     }
     catch (error) {
-        backupLog.error('Failed to list backups', { error: String(error) });
-        return [];
+        const message = error instanceof Error ? error.message : String(error);
+        backupLog.error('Failed to list backups', { error: message });
+        throw new Error(`Failed to list backups: ${message}`, { cause: error });
     }
 }
-/**
- * Restore from a backup
- */
+/** Download, validate, and atomically install a backup. */
 export async function restoreBackup(key, config, client) {
     const startTime = Date.now();
+    const timeoutMs = timeoutFor(config);
+    let candidatePath = null;
     try {
-        // Verify backup exists
         const s3File = client.file(key);
-        const exists = await s3File.exists();
-        if (!exists) {
+        const exists = await retryWithTimeout(() => s3File.exists(), timeoutMs, 'S3 backup existence check');
+        if (!exists)
             throw new Error(`Backup not found: ${key}`);
-        }
-        // Download backup (with timeout)
-        const timeoutMs = config.timeoutMs ?? DEFAULT_S3_TIMEOUT_MS;
-        const compressedData = await withTimeout(s3File.arrayBuffer(), timeoutMs, 'S3 backup download');
-        // Check metadata to determine if backup is compressed
-        const metadataKey = `${key}.meta.json`;
-        const metadataFile = client.file(metadataKey);
-        const metadataExists = await metadataFile.exists();
-        let metadataRaw = null;
+        const downloaded = new Uint8Array(await retryWithTimeout(() => s3File.arrayBuffer(), timeoutMs, 'S3 backup download'));
+        const metadataFile = client.file(`${key}.meta.json`);
+        const metadataExists = await retryWithTimeout(() => metadataFile.exists(), timeoutMs, 'S3 metadata existence check');
+        let data;
         if (metadataExists) {
-            metadataRaw = (await metadataFile.json());
-        }
-        // Decompress if backup is compressed (new format) or try to detect gzip magic bytes
-        const isCompressed = metadataRaw?.compressed ??
-            (compressedData.byteLength >= 2 &&
-                new Uint8Array(compressedData)[0] === 0x1f &&
-                new Uint8Array(compressedData)[1] === 0x8b);
-        const data = isCompressed
-            ? await gunzipAsync(new Uint8Array(compressedData))
-            : new Uint8Array(compressedData);
-        // Verify checksum if metadata exists
-        if (metadataRaw?.checksum) {
-            const hasher = new Bun.CryptoHasher('sha256');
-            hasher.update(data);
-            const checksum = hasher.digest('hex');
-            if (checksum !== metadataRaw.checksum) {
+            const metadata = validateMetadata(await retryWithTimeout(() => metadataFile.json(), timeoutMs, 'S3 metadata download'), downloaded.byteLength);
+            data = await gunzipAsync(downloaded);
+            if (data.byteLength !== metadata.size) {
+                throw new Error('Backup size mismatch - file may be corrupted');
+            }
+            if (sha256(data) !== metadata.checksum) {
                 throw new Error('Backup checksum mismatch - file may be corrupted');
             }
         }
-        // Validate SQLite format
+        else {
+            if (isGzip(downloaded)) {
+                throw new Error('Compressed backup is invalid because metadata is missing');
+            }
+            data = downloaded;
+        }
         const header = new TextDecoder().decode(data.slice(0, 16));
         if (!header.startsWith('SQLite format 3')) {
             throw new Error('Restored data is not a valid SQLite database');
         }
-        // Atomic, validate-before-replace restore:
-        // Write the payload to a TEMP file next to the target, validate integrity
-        // on the temp file, and only swap the live DB into place on full success.
-        // On any failure the temp file is removed and the live DB is left untouched.
-        const tempPath = `${config.databasePath}.restore-${Date.now()}-${Math.random()
-            .toString(36)
-            .slice(2)}.tmp`;
-        try {
-            await Bun.write(tempPath, data);
-            // Verify integrity on the temp candidate (this deletes the temp file on failure).
-            await verifyDatabaseIntegrity(tempPath);
-            // Validation passed: atomically replace the live DB with the temp file.
-            const { rename } = await import('fs/promises');
-            await rename(tempPath, config.databasePath);
-        }
-        catch (error) {
-            // Best-effort cleanup of the temp file (may already be removed by the
-            // integrity check). The live DB at config.databasePath is never touched.
-            try {
-                const { unlink } = await import('fs/promises');
-                await unlink(tempPath);
-            }
-            catch {
-                /* best effort — temp file may not exist */
-            }
-            throw error;
-        }
-        const duration = Date.now() - startTime;
-        return { success: true, key, size: data.byteLength, duration };
+        candidatePath = restoreCandidatePath(config.databasePath);
+        await Bun.write(candidatePath, data);
+        verifyDatabaseIntegrity(candidatePath);
+        await installDatabaseCandidate(candidatePath, config.databasePath);
+        return {
+            success: true,
+            key,
+            size: data.byteLength,
+            ...(metadataExists && { compressedSize: downloaded.byteLength }),
+            duration: Date.now() - startTime,
+        };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         backupLog.error('Restore failed', { error: message });
         return { success: false, error: message };
     }
+    finally {
+        await cleanupLocalArtifacts(candidatePath, 'restore candidate');
+    }
 }
-/**
- * Clean up old backups based on retention policy
- */
+/** Delete backup pairs beyond the configured retention count. */
 export async function cleanupOldBackups(config, client) {
     try {
         const backups = await listBackups(config, client);
-        const retention = Math.max(config.retention, 1);
-        if (backups.length <= retention) {
-            return;
-        }
-        // Sort by date (newest first) and get backups to delete
-        const toDelete = backups.slice(retention);
+        const toDelete = backups.slice(Math.max(config.retention, 1));
+        const timeoutMs = timeoutFor(config);
         for (const backup of toDelete) {
             try {
-                // Delete backup file
-                await client.delete(backup.key);
-                // Delete metadata file if exists
-                const metadataKey = `${backup.key}.meta.json`;
-                const metadataFile = client.file(metadataKey);
-                if (await metadataFile.exists()) {
-                    await client.delete(metadataKey);
-                }
+                await retryWithTimeout(() => client.delete(backup.key), timeoutMs, 'S3 backup delete');
+                await retryWithTimeout(() => client.delete(`${backup.key}.meta.json`), timeoutMs, 'S3 metadata delete');
             }
             catch (error) {
-                backupLog.warn('Failed to delete old backup', { key: backup.key, error: String(error) });
+                backupLog.warn('Failed to delete old backup', {
+                    key: backup.key,
+                    error: String(error),
+                });
             }
         }
     }

package/dist/infrastructure/backup/sqliteBackupFiles.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SQLite snapshot creation, validation, and restore file transitions.
+ */
+/** Remove a database candidate and any sidecars SQLite may have created for it. */
+export declare function removeDatabaseArtifacts(databasePath: string): Promise<void>;
+/** Validate all SQLite database pages. */
+export declare function verifyDatabaseIntegrity(databasePath: string): void;
+/**
+ * Produce a transactionally consistent, standalone SQLite snapshot.
+ *
+ * VACUUM INTO reads through SQLite rather than copying the live main file, so
+ * committed WAL frames are included even when an older reader blocks a WAL
+ * checkpoint.
+ */
+export declare function createConsistentSnapshot(databasePath: string): Promise<string>;
+/**
+ * Install an already validated candidate while quarantining stale sidecars.
+ *
+ * The live main database is not touched until all sidecars have moved. If a
+ * pre-swap operation fails, moved sidecars are restored before returning.
+ */
+export declare function installDatabaseCandidate(candidatePath: string, databasePath: string): Promise<void>;

package/dist/infrastructure/backup/sqliteBackupFiles.js

@@ -0,0 +1,130 @@
+/**
+ * SQLite snapshot creation, validation, and restore file transitions.
+ */
+import { Database } from 'bun:sqlite';
+import { rename, rm } from 'node:fs/promises';
+import { backupLog } from '../../shared/logger';
+const SIDECAR_SUFFIXES = ['-wal', '-shm', '-journal'];
+function uniqueSiblingPath(databasePath, purpose) {
+    return `${databasePath}.${purpose}-${Date.now()}-${crypto.randomUUID()}.tmp`;
+}
+function quoteSqliteString(value) {
+    return value.replaceAll("'", "''");
+}
+async function removeIfPresent(path) {
+    await rm(path, { force: true });
+}
+/** Remove a database candidate and any sidecars SQLite may have created for it. */
+export async function removeDatabaseArtifacts(databasePath) {
+    await Promise.all([
+        removeIfPresent(databasePath),
+        ...SIDECAR_SUFFIXES.map((suffix) => removeIfPresent(`${databasePath}${suffix}`)),
+    ]);
+}
+/** Validate all SQLite database pages. */
+export function verifyDatabaseIntegrity(databasePath) {
+    let db = null;
+    try {
+        db = new Database(databasePath, { readonly: true });
+        const result = db.query('PRAGMA integrity_check').get();
+        const status = result?.integrity_check ?? '';
+        if (status !== 'ok') {
+            throw new Error(`Database integrity check failed: ${status || 'unknown error'}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('integrity check failed')) {
+            throw error;
+        }
+        throw new Error('Database integrity check failed: corrupt or invalid database', {
+            cause: error,
+        });
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch {
+            // The failed open or check may already have closed the handle.
+        }
+    }
+}
+/**
+ * Produce a transactionally consistent, standalone SQLite snapshot.
+ *
+ * VACUUM INTO reads through SQLite rather than copying the live main file, so
+ * committed WAL frames are included even when an older reader blocks a WAL
+ * checkpoint.
+ */
+export async function createConsistentSnapshot(databasePath) {
+    const snapshotPath = uniqueSiblingPath(databasePath, 'backup-snapshot');
+    let db = null;
+    try {
+        db = new Database(databasePath, { readonly: true });
+        db.exec('PRAGMA busy_timeout = 30000');
+        db.exec(`VACUUM INTO '${quoteSqliteString(snapshotPath)}'`);
+        db.close();
+        db = null;
+        verifyDatabaseIntegrity(snapshotPath);
+        return snapshotPath;
+    }
+    catch (error) {
+        try {
+            db?.close();
+        }
+        catch {
+            // The failed snapshot may already have closed the handle.
+        }
+        await removeDatabaseArtifacts(snapshotPath);
+        throw error;
+    }
+}
+/**
+ * Install an already validated candidate while quarantining stale sidecars.
+ *
+ * The live main database is not touched until all sidecars have moved. If a
+ * pre-swap operation fails, moved sidecars are restored before returning.
+ */
+export async function installDatabaseCandidate(candidatePath, databasePath) {
+    const quarantineId = `${Date.now()}-${crypto.randomUUID()}`;
+    const movedSidecars = [];
+    try {
+        for (const suffix of SIDECAR_SUFFIXES) {
+            const live = `${databasePath}${suffix}`;
+            if (!(await Bun.file(live).exists())) {
+                continue;
+            }
+            const quarantine = `${live}.restore-quarantine-${quarantineId}`;
+            await rename(live, quarantine);
+            movedSidecars.push({ live, quarantine });
+        }
+        await rename(candidatePath, databasePath);
+    }
+    catch (error) {
+        const rollbackErrors = [];
+        for (const moved of movedSidecars.reverse()) {
+            try {
+                await rename(moved.quarantine, moved.live);
+            }
+            catch (rollbackError) {
+                rollbackErrors.push(String(rollbackError));
+            }
+        }
+        if (rollbackErrors.length > 0) {
+            throw new Error(`Restore failed and sidecar rollback failed: ${rollbackErrors.join('; ')}`, {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+    const cleanup = await Promise.allSettled([
+        ...movedSidecars.map(({ quarantine }) => removeIfPresent(quarantine)),
+        ...SIDECAR_SUFFIXES.map((suffix) => removeIfPresent(`${candidatePath}${suffix}`)),
+    ]);
+    const failures = cleanup.filter((result) => result.status === 'rejected');
+    if (failures.length > 0) {
+        backupLog.warn('Restore committed but quarantine cleanup was incomplete', {
+            errors: failures.map(({ reason }) => String(reason)),
+        });
+    }
+}

package/dist/infrastructure/cloud/statsRefresh.d.ts

@@ -93,6 +93,7 @@ export declare function buildStatsRefresh(qm: QueueManager): {
         totalProcessed: number;
         totalFailed: number;
         activeJobs: number;
+        concurrencySlots: number;
     };
     cronCount: number;
     storage: {

package/dist/infrastructure/persistence/sqlite.js

@@ -203,7 +203,12 @@ export class SqliteStorage {
     }
     /** Flush write buffer to disk. Returns number of jobs flushed. */
     flushWriteBuffer() {
-        return this.writeBuffer.flush();
+        const flushed = this.writeBuffer.flush();
+        const pending = this.writeBuffer.pendingCount;
+        if (pending > 0) {
+            throw new Error(`Cannot create a consistent backup while ${pending} write${pending === 1 ? '' : 's'} remains buffered`);
+        }
+        return flushed;
     }
     migrate() {
         this.db.run(MIGRATION_TABLE);

package/dist/infrastructure/server/bootstrap.d.ts

@@ -5,5 +5,7 @@
  * agent, stats interval, crash handlers and graceful shutdown are always on.
  */
 import { type BunqueueConfig, type ResolvedConfig } from '../../config';
+/** Return a startup error when an enabled file backup has no file to snapshot. */
+export declare function backupStartupError(config: Pick<ResolvedConfig, 's3BackupEnabled' | 'dataPath'>): string | null;
 /** Boot the full server from resolved configuration. Runs until shutdown. */
 export declare function bootServer(fileConfig: BunqueueConfig | null, config: ResolvedConfig): void;