bunqueue 2.8.60 → 2.9.0

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

@@ -0,0 +1,126 @@
+import { decodePostgresValue, encodePostgresValue } from './codec';
+import { databaseNow } from './context';
+import { lockPostgresBrokerSession } from './brokerSessions';
+export async function savePostgresWorker(ctx, worker) {
+    await ctx.sql.begin(async (tx) => {
+        await lockPostgresBrokerSession(tx, ctx);
+        worker.lastSeen = await databaseNow(tx);
+        await tx `
+      INSERT INTO bunqueue_workers
+        (namespace, id, broker_id, broker_session_id, client_id, queues, payload, last_seen)
+      VALUES
+        (${ctx.config.namespace}, ${worker.id}, ${ctx.config.brokerId},
+         ${ctx.config.brokerSessionId}, ${worker.clientId},
+         ${tx.array(worker.queues, 'TEXT')}, ${encodePostgresValue(worker)}, ${worker.lastSeen})
+      ON CONFLICT (namespace, id) DO UPDATE SET
+        broker_id = excluded.broker_id,
+        broker_session_id = excluded.broker_session_id,
+        client_id = excluded.client_id,
+        queues = excluded.queues,
+        payload = excluded.payload,
+        last_seen = excluded.last_seen
+    `;
+    });
+}
+export async function removePostgresWorker(ctx, id, clientId) {
+    const expectedClientId = clientId ?? null;
+    const rows = await ctx.sql `
+    DELETE FROM bunqueue_workers
+    WHERE namespace = ${ctx.config.namespace} AND id = ${id}
+      AND broker_id = ${ctx.config.brokerId}
+      AND broker_session_id = ${ctx.config.brokerSessionId}
+      AND (${expectedClientId}::text IS NULL OR client_id IS NOT DISTINCT FROM ${expectedClientId})
+    RETURNING id
+  `;
+    return rows.length > 0;
+}
+export async function heartbeatPostgresWorker(ctx, id, stats, clientId) {
+    return await ctx.sql.begin(async (tx) => {
+        await lockPostgresBrokerSession(tx, ctx);
+        const expectedClientId = clientId ?? null;
+        const rows = await tx `
+      SELECT id, payload FROM bunqueue_workers
+      WHERE namespace = ${ctx.config.namespace} AND id = ${id}
+        AND broker_id = ${ctx.config.brokerId}
+        AND broker_session_id = ${ctx.config.brokerSessionId}
+        AND (${expectedClientId}::text IS NULL OR client_id IS NOT DISTINCT FROM ${expectedClientId})
+      FOR UPDATE
+    `;
+        const row = rows[0];
+        if (!row)
+            return false;
+        const worker = decodePostgresValue(row.payload, null, `postgresWorker:${row.id}`);
+        if (!worker)
+            throw new Error(`Corrupt PostgreSQL worker payload for ${row.id}`);
+        worker.lastSeen = await databaseNow(tx);
+        if (stats?.activeJobs !== undefined)
+            worker.activeJobs = stats.activeJobs;
+        if (stats?.processed !== undefined)
+            worker.processedJobs = stats.processed;
+        if (stats?.failed !== undefined)
+            worker.failedJobs = stats.failed;
+        if (clientId !== undefined)
+            worker.clientId = clientId;
+        await tx `
+      UPDATE bunqueue_workers
+      SET broker_id = ${ctx.config.brokerId},
+          broker_session_id = ${ctx.config.brokerSessionId}, client_id = ${worker.clientId},
+          payload = ${encodePostgresValue(worker)}, last_seen = ${worker.lastSeen}
+      WHERE namespace = ${ctx.config.namespace} AND id = ${id}
+        AND broker_id = ${ctx.config.brokerId}
+        AND broker_session_id = ${ctx.config.brokerSessionId}
+        AND (${expectedClientId}::text IS NULL OR client_id IS NOT DISTINCT FROM ${expectedClientId})
+    `;
+        return true;
+    });
+}
+export async function removePostgresClientWorkers(ctx, clientId) {
+    const rows = await ctx.sql `
+    DELETE FROM bunqueue_workers
+    WHERE namespace = ${ctx.config.namespace}
+      AND broker_id = ${ctx.config.brokerId} AND client_id = ${clientId}
+      AND broker_session_id = ${ctx.config.brokerSessionId}
+    RETURNING id
+  `;
+    return rows.length;
+}
+export async function removePostgresBrokerWorkers(ctx) {
+    const rows = await ctx.sql `
+    DELETE FROM bunqueue_workers
+    WHERE namespace = ${ctx.config.namespace} AND broker_id = ${ctx.config.brokerId}
+      AND broker_session_id = ${ctx.config.brokerSessionId}
+    RETURNING id
+  `;
+    return rows.length;
+}
+export async function listPostgresWorkers(ctx) {
+    const rows = await ctx.sql `
+    SELECT id, payload FROM bunqueue_workers
+    WHERE namespace = ${ctx.config.namespace}
+    ORDER BY id
+  `;
+    return rows.flatMap((row) => {
+        const worker = decodePostgresValue(row.payload, null, `postgresWorker:${row.id}`);
+        return worker ? [worker] : [];
+    });
+}
+export async function hasActivePostgresWorker(sql, ctx, queue, now, timeoutMs = 30_000) {
+    const rows = await sql `
+    SELECT EXISTS (
+      SELECT 1 FROM bunqueue_workers
+      WHERE namespace = ${ctx.config.namespace}
+        AND ${queue} = ANY(queues)
+        AND last_seen > ${now - timeoutMs}
+    ) AS found
+  `;
+    return rows[0]?.found ?? false;
+}
+export async function purgeStalePostgresWorkers(ctx, requestedNow, staleMs = 90_000) {
+    const now = requestedNow ?? (await databaseNow(ctx.sql));
+    const rows = await ctx.sql `
+    DELETE FROM bunqueue_workers
+    WHERE namespace = ${ctx.config.namespace} AND last_seen <= ${now - staleMs}
+    RETURNING id
+  `;
+    return rows.length;
+}

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

@@ -0,0 +1,2 @@
+export { PostgresQueueStore } from './postgres/store';
+export type { ClaimedPostgresJob, PostgresCompletionResult, PostgresCounts, PostgresDeliveredStoreEvent, PostgresFailureInput, PostgresQueueState, PostgresStorageConfig, PostgresStorageHealth, PostgresStoreEvent, PostgresStoredJob, PostgresJobState, } from './postgres/types';

package/dist/infrastructure/persistence/postgres.js

@@ -0,0 +1 @@
+export { PostgresQueueStore } from './postgres/store';

package/dist/infrastructure/persistence/sqlite/jobs.js

@@ -132,6 +132,7 @@ export class SqliteJobs extends SqliteAdmission {
             const clearDlq = this.statements.get('clearDlqQueue');
             const deleteJob = this.statements.get('deleteJob');
             const deleteResult = this.statements.get('deleteJobResult');
+            const deleteFlowFailures = this.db.prepare('DELETE FROM flow_failures WHERE parent_id = ?');
             const transaction = this.db.transaction(() => {
                 if (clearQueue)
                     clearDlq.run(queue);
@@ -141,6 +142,7 @@ export class SqliteJobs extends SqliteAdmission {
                 for (const jobId of terminalJobIds) {
                     deleteJob.run(jobId);
                     deleteResult.run(jobId);
+                    deleteFlowFailures.run(jobId);
                 }
             });
             transaction();

package/dist/infrastructure/scheduler/cron/persisted.d.ts

@@ -0,0 +1,5 @@
+import { type CronJob } from '../../../domain/types/cron';
+/** Reject persisted Croner-only syntax before any scheduler state is mutated. */
+export declare function assertPersistedCronSupported(cron: CronJob): void;
+/** Validate a persisted collection atomically before loading any definition. */
+export declare function assertPersistedCronsSupported(crons: readonly CronJob[]): void;

package/dist/infrastructure/scheduler/cron/persisted.js

@@ -0,0 +1,27 @@
+import { assertValidCronTiming } from '../../../domain/types/cron';
+import { expandCronShortcut, validateCronExpression } from '../cronParser';
+const NATIVE_CRON_MIGRATION_VERSION = '2.9.0';
+/** Reject persisted Croner-only syntax before any scheduler state is mutated. */
+export function assertPersistedCronSupported(cron) {
+    try {
+        assertValidCronTiming(cron);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Persisted cron ${JSON.stringify(cron.name)} has invalid timing: ${message}. ` +
+            `Update or remove it before upgrading to bunqueue ${NATIVE_CRON_MIGRATION_VERSION}.`);
+    }
+    if (!cron.schedule)
+        return;
+    const error = validateCronExpression(expandCronShortcut(cron.schedule), cron.timezone ?? undefined);
+    if (!error)
+        return;
+    throw new Error(`Persisted cron ${JSON.stringify(cron.name)} uses unsupported schedule ${JSON.stringify(cron.schedule)}. ` +
+        `Update or remove it before upgrading to bunqueue ${NATIVE_CRON_MIGRATION_VERSION}. ` +
+        `Bun.cron validation failed: ${error}`);
+}
+/** Validate a persisted collection atomically before loading any definition. */
+export function assertPersistedCronsSupported(crons) {
+    for (const cron of crons)
+        assertPersistedCronSupported(cron);
+}

package/dist/infrastructure/scheduler/cron/runtime.js

@@ -1,6 +1,8 @@
 import { createCronJob } from '../../../domain/types/cron';
 import { MinHeap } from '../../../shared/minHeap';
-import { expandCronShortcut, getNextCronRun, getNextIntervalRun, validateCronExpression, } from '../cronParser';
+import { expandCronShortcut, getNextCronRun, getNextIntervalRun } from '../cronParser';
+import { assertPersistedCronsSupported } from './persisted';
+import { assertValidCronInput } from './validation';
 const SAFETY_FALLBACK_MS = 60_000;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 /** Registry, timers, and schedule mutation shared with cron execution. */
@@ -52,15 +54,7 @@ export class CronRuntime {
         }
     }
     add(input) {
-        if (!input.schedule && !input.repeatEvery) {
-            throw new Error('Cron job must have either schedule or repeatEvery');
-        }
-        if (input.schedule) {
-            const expanded = expandCronShortcut(input.schedule);
-            const error = validateCronExpression(expanded, input.timezone);
-            if (error)
-                throw new Error(`Invalid cron expression: ${error}`);
-        }
+        assertValidCronInput(input);
         const now = Date.now();
         const nextRun = input.schedule
             ? getNextCronRun(expandCronShortcut(input.schedule), now, input.timezone)
@@ -97,6 +91,7 @@ export class CronRuntime {
         return Array.from(this.cronJobs.values()).map((entry) => entry.cron);
     }
     load(crons) {
+        assertPersistedCronsSupported(crons);
         const now = Date.now();
         const entries = [];
         for (const cron of crons) {

package/dist/infrastructure/scheduler/cron/validation.d.ts

@@ -0,0 +1,3 @@
+import { type CronJobInput } from '../../../domain/types/cron';
+/** Reject invalid timing, calendar syntax, and timezones before state mutation. */
+export declare function assertValidCronInput(input: CronJobInput): void;

package/dist/infrastructure/scheduler/cron/validation.js

@@ -0,0 +1,11 @@
+import { assertValidCronTiming } from '../../../domain/types/cron';
+import { expandCronShortcut, validateCronExpression } from '../cronParser';
+/** Reject invalid timing, calendar syntax, and timezones before state mutation. */
+export function assertValidCronInput(input) {
+    assertValidCronTiming(input);
+    if (!input.schedule)
+        return;
+    const error = validateCronExpression(expandCronShortcut(input.schedule), input.timezone);
+    if (error)
+        throw new Error(`Invalid cron expression: ${error}`);
+}

package/dist/infrastructure/scheduler/cronParser.d.ts

@@ -1,6 +1,6 @@
 /**
  * Cron Expression Parser
- * Parses 5-6 field cron expressions and calculates next run time
+ * Parses 5-6 field cron expressions and calculates next run time with Bun.cron
  */
 /**
  * Validate a cron expression

package/dist/infrastructure/scheduler/cronParser.js

@@ -1,8 +1,102 @@
 /**
  * Cron Expression Parser
- * Parses 5-6 field cron expressions and calculates next run time
+ * Parses 5-6 field cron expressions and calculates next run time with Bun.cron
  */
-import { Cron } from 'croner';
+const CRON_FIELD_COUNT = 5;
+const CRON_WITH_SECONDS_FIELD_COUNT = 6;
+const MINUTE_MS = 60_000;
+const SECOND_MS = 1_000;
+function invalidSeconds(field, reason) {
+    throw new TypeError(`Invalid cron seconds field "${field}": ${reason}`);
+}
+function parseNumber(value, field, label) {
+    if (!/^\d+$/.test(value))
+        invalidSeconds(field, `${label} must be an integer`);
+    return Number(value);
+}
+/** Parse the leading seconds field supported by bunqueue's six-field contract. */
+function parseSeconds(field) {
+    const selected = new Set();
+    for (const segment of field.split(',')) {
+        if (!segment)
+            invalidSeconds(field, 'list entries cannot be empty');
+        const stepParts = segment.split('/');
+        if (stepParts.length > 2 || !stepParts[0] || stepParts[1] === '') {
+            invalidSeconds(field, `invalid segment "${segment}"`);
+        }
+        const base = stepParts[0];
+        const hasStep = stepParts.length === 2;
+        const step = hasStep ? parseNumber(stepParts[1], field, 'step') : 1;
+        if (step < 1 || step > 60)
+            invalidSeconds(field, 'step must be between 1 and 60');
+        let start;
+        let end;
+        if (base === '*') {
+            start = 0;
+            end = 59;
+        }
+        else if (base.includes('-')) {
+            const range = base.split('-');
+            if (range.length !== 2 || !range[0] || !range[1]) {
+                invalidSeconds(field, `invalid range "${base}"`);
+            }
+            start = parseNumber(range[0], field, 'range start');
+            end = parseNumber(range[1], field, 'range end');
+        }
+        else {
+            if (hasStep) {
+                invalidSeconds(field, 'steps require a wildcard or range');
+            }
+            start = parseNumber(base, field, 'value');
+            end = start;
+        }
+        if (start < 0 || start > 59 || end < 0 || end > 59) {
+            invalidSeconds(field, 'values must be between 0 and 59');
+        }
+        if (start > end)
+            invalidSeconds(field, 'range start must not exceed range end');
+        for (let value = start; value <= end; value += step)
+            selected.add(value);
+    }
+    return [...selected].sort((a, b) => a - b);
+}
+function parseCronExpression(expression) {
+    const trimmed = expression.trim();
+    if (trimmed.startsWith('@') && !/\s/.test(trimmed)) {
+        return { calendar: trimmed, seconds: null };
+    }
+    const fields = trimmed ? trimmed.split(/\s+/) : [];
+    if (fields.length === CRON_FIELD_COUNT) {
+        return { calendar: fields.join(' '), seconds: null };
+    }
+    if (fields.length === CRON_WITH_SECONDS_FIELD_COUNT) {
+        return { calendar: fields.slice(1).join(' '), seconds: parseSeconds(fields[0]) };
+    }
+    throw new TypeError('Cron expression must have 5 fields, or 6 fields with leading seconds');
+}
+function parseNativeCron(calendar, fromTime, timezone) {
+    return Bun.cron.parse(calendar, fromTime, timezone ? { tz: timezone } : undefined);
+}
+function getNextParsedRun(parsed, fromTime, timezone) {
+    if (parsed.seconds === null) {
+        return parseNativeCron(parsed.calendar, fromTime, timezone)?.getTime() ?? 0;
+    }
+    const currentMinute = Math.floor(fromTime / MINUTE_MS) * MINUTE_MS;
+    let matchingMinute = parseNativeCron(parsed.calendar, currentMinute - 1, timezone);
+    while (matchingMinute) {
+        const minuteStart = matchingMinute.getTime();
+        for (const second of parsed.seconds) {
+            const candidate = minuteStart + second * SECOND_MS;
+            if (candidate > fromTime)
+                return candidate;
+        }
+        const nextMinute = parseNativeCron(parsed.calendar, minuteStart, timezone);
+        if (!nextMinute || nextMinute.getTime() <= minuteStart)
+            return 0;
+        matchingMinute = nextMinute;
+    }
+    return 0;
+}
 /**
  * Validate a cron expression
  * @param expression - Cron expression (5 or 6 fields)
@@ -11,7 +105,10 @@ import { Cron } from 'croner';
  */
 export function validateCronExpression(expression, timezone) {
     try {
-        new Cron(expression, { timezone });
+        const parsed = parseCronExpression(expression);
+        if (getNextParsedRun(parsed, Date.now(), timezone) === 0) {
+            return 'Cron expression has no future occurrences';
+        }
         return null;
     }
     catch (err) {
@@ -26,9 +123,7 @@ export function validateCronExpression(expression, timezone) {
  * @returns Next run timestamp in milliseconds
  */
 export function getNextCronRun(expression, fromTime = Date.now(), timezone) {
-    const cron = new Cron(expression, { timezone });
-    const nextDate = cron.nextRun(new Date(fromTime));
-    return nextDate ? nextDate.getTime() : 0;
+    return getNextParsedRun(parseCronExpression(expression), fromTime, timezone);
 }
 /**
  * Calculate next run time from repeatEvery interval
@@ -72,20 +167,58 @@ export function expandCronShortcut(expression) {
  */
 export function describeCron(expression) {
     const expanded = expandCronShortcut(expression);
-    const parts = expanded.split(/\s+/);
-    if (parts.length < 5) {
+    const rawParts = expanded.trim().split(/\s+/);
+    const hasSeconds = rawParts.length === CRON_WITH_SECONDS_FIELD_COUNT;
+    const secondsField = hasSeconds ? rawParts[0] : null;
+    let seconds = null;
+    if (secondsField) {
+        try {
+            seconds = parseSeconds(secondsField);
+        }
+        catch {
+            return 'Invalid cron expression';
+        }
+    }
+    const parts = hasSeconds ? rawParts.slice(1) : rawParts;
+    if (parts.length !== CRON_FIELD_COUNT) {
         return 'Invalid cron expression';
     }
     const [minute, hour, dayOfMonth, month, dayOfWeek] = parts;
+    const everyCalendarMinute = parts.every((part) => part === '*');
+    if (secondsField === '*' && everyCalendarMinute)
+        return 'Every second';
+    if (secondsField &&
+        /^\d+$/.test(secondsField) &&
+        /^\d+$/.test(minute) &&
+        /^\d+$/.test(hour) &&
+        dayOfMonth === '*' &&
+        month === '*' &&
+        dayOfWeek === '*') {
+        return `Every day at ${hour.padStart(2, '0')}:${minute.padStart(2, '0')}:${secondsField.padStart(2, '0')}`;
+    }
+    const usesCalendarShortcuts = seconds === null || (seconds.length === 1 && seconds[0] === 0);
     // Common patterns
-    if (minute === '0' && hour === '0' && dayOfMonth === '*' && month === '*' && dayOfWeek === '*') {
+    if (usesCalendarShortcuts &&
+        minute === '0' &&
+        hour === '0' &&
+        dayOfMonth === '*' &&
+        month === '*' &&
+        dayOfWeek === '*') {
         return 'Every day at midnight';
     }
-    if (minute === '0' && hour === '*' && dayOfMonth === '*' && month === '*' && dayOfWeek === '*') {
+    if (usesCalendarShortcuts &&
+        minute === '0' &&
+        hour === '*' &&
+        dayOfMonth === '*' &&
+        month === '*' &&
+        dayOfWeek === '*') {
         return 'Every hour';
     }
-    if (minute === '*' && hour === '*' && dayOfMonth === '*' && month === '*' && dayOfWeek === '*') {
+    if (usesCalendarShortcuts && everyCalendarMinute) {
         return 'Every minute';
     }
+    if (secondsField) {
+        return `At second ${secondsField}, minute ${minute}, hour ${hour} on day ${dayOfMonth} of ${month}, day of week ${dayOfWeek}`;
+    }
     return `At ${minute} ${hour} on day ${dayOfMonth} of ${month}, day of week ${dayOfWeek}`;
 }

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

@@ -5,7 +5,6 @@
  * 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;
+export { backupStartupError } from './storageManager';
 /** Boot the full server from resolved configuration. Runs until shutdown. */
-export declare function bootServer(fileConfig: BunqueueConfig | null, config: ResolvedConfig): void;
+export declare function bootServer(fileConfig: BunqueueConfig | null, config: ResolvedConfig): Promise<void>;

package/dist/infrastructure/server/bootstrap.js

@@ -4,24 +4,17 @@
  * `bunqueue start` via the CLI) so they cannot drift: S3 backup, cloud
  * agent, stats interval, crash handlers and graceful shutdown are always on.
  */
-import { QueueManager } from '../../application/queueManager';
 import { createTcpServer } from './tcp';
 import { createHttpServer } from './http';
 import { Logger, serverLog, statsLog } from '../../shared/logger';
-import { stopRateLimiter } from './rateLimiter';
 import { VERSION } from '../../shared/version';
 import { S3BackupManager } from '../backup';
 import { CloudAgent } from '../cloud';
 import { SHARD_COUNT } from '../../shared/hash';
 import { resolveCloudConfig, resolveBackupConfig, resolveTlsServerOptions, } from '../../config';
-/** Return a startup error when an enabled file backup has no file to snapshot. */
-export function backupStartupError(config) {
-    if (config.s3BackupEnabled && !config.dataPath) {
-        return ('S3 backup requires persistent SQLite storage. Set BUNQUEUE_DATA_PATH ' +
-            'or storage.dataPath before enabling S3_BACKUP_ENABLED.');
-    }
-    return null;
-}
+import { backupStartupError, createServerQueueManager, shutdownServerQueueManager, storageDisplay, storageStartupError, } from './storageManager';
+import { createServerShutdown } from './shutdownCoordinator';
+export { backupStartupError } from './storageManager';
 /** Print startup banner */
 function printBanner(config, cloudUrl) {
     const dim = '\x1b[2m';
@@ -46,9 +39,7 @@ function printBanner(config, cloudUrl) {
     const socketDisplay = hasUnixSockets
         ? `${green}enabled${reset} ${dim}(${config.tcpSocketPath ? 'TCP' : ''}${config.tcpSocketPath && config.httpSocketPath ? '+' : ''}${config.httpSocketPath ? 'HTTP' : ''})${reset}`
         : `${dim}disabled${reset}`;
-    const storageDisplay = config.dataPath
-        ? `${bold}SQLite${reset} ${dim}·${reset} ${config.dataPath}`
-        : `in-memory ${dim}· ephemeral${reset}`;
+    const persistenceDisplay = storageDisplay(config);
     console.log(`
 ${magenta}        (\\(\\        ${reset}
 ${magenta}        ( -.-)      ${bold}bunqueue${reset} ${dim}v${VERSION}${reset}
@@ -59,7 +50,7 @@ ${dim}────────────────────────
 ${row(active, 'TCP', tcpDisplay)}
 ${row(active, 'HTTP', httpDisplay)}
 ${row(hasUnixSockets ? active : inactive, 'Unix socket', socketDisplay)}
-${row(info, 'Storage', storageDisplay)}
+${row(info, 'Storage', persistenceDisplay)}
 ${row(config.s3BackupEnabled ? active : inactive, 'S3 Backup', config.s3BackupEnabled ? `${green}enabled${reset}` : `${dim}disabled${reset}`)}
 ${row(config.tlsCertFile ? active : inactive, 'TLS', config.tlsCertFile ? `${green}enabled${reset}` : `${dim}disabled${reset}`)}
 ${row(config.authTokens.length > 0 ? active : inactive, 'Auth', config.authTokens.length > 0 ? `${green}enabled${reset}` : `${dim}disabled${reset}`)}
@@ -71,7 +62,7 @@ ${dim}────────────────────────
 `);
 }
 /** Boot the full server from resolved configuration. Runs until shutdown. */
-export function bootServer(fileConfig, config) {
+export async function bootServer(fileConfig, config) {
     // Apply logging config before anything else
     const logFormat = fileConfig?.logging?.format ?? Bun.env.LOG_FORMAT;
     const logLevel = fileConfig?.logging?.level ?? Bun.env.LOG_LEVEL?.toLowerCase();
@@ -82,9 +73,9 @@ export function bootServer(fileConfig, config) {
         if (validLevels.includes(logLevel))
             Logger.setLevel(logLevel);
     }
-    const backupError = backupStartupError(config);
-    if (backupError) {
-        serverLog.error(backupError);
+    const startupError = storageStartupError(config) ?? backupStartupError(config);
+    if (startupError) {
+        serverLog.error(startupError);
         process.exitCode = 1;
         return;
     }
@@ -99,12 +90,18 @@ export function bootServer(fileConfig, config) {
         serverLog.error(err instanceof Error ? err.message : String(err));
         process.exit(1);
     }
+    let queueManager;
+    try {
+        queueManager = await createServerQueueManager(config);
+    }
+    catch (error) {
+        serverLog.error('Failed to initialize storage', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        process.exitCode = 1;
+        return;
+    }
     printBanner(config, cloudConfig?.url);
-    // Create queue manager
-    const queueManager = new QueueManager({
-        dataPath: config.dataPath,
-        maxPrometheusQueues: config.maxPrometheusQueues,
-    });
     // Start TCP + HTTP servers; a bind failure must not leave a half-started process
     let tcpServer;
     let httpServer;
@@ -129,12 +126,12 @@ export function bootServer(fileConfig, config) {
     catch (err) {
         const msg = err instanceof Error ? err.message : 'Unknown error';
         console.error(`Failed to start server: ${msg}`);
-        queueManager.shutdown();
+        await shutdownServerQueueManager(queueManager);
         process.exit(1);
     }
     // Initialize S3 backup manager
     let backupManager = null;
-    if (config.dataPath) {
+    if (config.storageDriver === 'sqlite' && config.dataPath) {
         const backupConfig = resolveBackupConfig(fileConfig, config.dataPath);
         backupManager = new S3BackupManager({
             ...backupConfig,
@@ -171,40 +168,17 @@ export function bootServer(fileConfig, config) {
         httpPort: config.httpPort,
         shards: SHARD_COUNT,
     });
-    // Graceful shutdown
-    let shuttingDown = false;
-    const shutdown = async (signal) => {
-        if (shuttingDown)
-            return;
-        shuttingDown = true;
-        serverLog.info(`Received ${signal}, shutting down...`);
-        // Stop stats interval immediately
-        clearInterval(statsInterval);
-        tcpServer.stop();
-        httpServer.stop();
-        const shutdownTimeout = config.shutdownTimeoutMs;
-        const start = Date.now();
-        while (Date.now() - start < shutdownTimeout) {
-            const stats = queueManager.getStats();
-            if (stats.active === 0)
-                break;
-            serverLog.info(`Waiting for ${stats.active} active jobs...`);
-            await Bun.sleep(1000);
-        }
-        // Stop backup manager
-        if (backupManager) {
-            backupManager.stop();
-        }
-        // Stop Cloud agent (sends final shutdown snapshot)
-        if (cloudAgent) {
-            await cloudAgent.stop();
-        }
-        queueManager.emitDashboardEvent('server:shutdown', { signal });
-        queueManager.shutdown();
-        stopRateLimiter();
-        serverLog.info('Shutdown complete');
-        process.exit(0);
-    };
+    const shutdown = createServerShutdown({
+        shutdownTimeoutMs: config.shutdownTimeoutMs,
+        stopStats: () => clearInterval(statsInterval),
+        stopTcp: () => tcpServer.stop(),
+        stopHttp: () => httpServer.stop(),
+        getActiveJobs: () => queueManager.getStats().active,
+        ...(backupManager && { stopBackup: () => backupManager.stop() }),
+        emitShutdown: (signal) => queueManager.emitDashboardEvent('server:shutdown', { signal }),
+        ...(cloudAgent && { stopCloud: () => cloudAgent.stop() }),
+        shutdownStorage: () => shutdownServerQueueManager(queueManager),
+    });
     process.on('SIGINT', () => void shutdown('SIGINT'));
     process.on('SIGTERM', () => void shutdown('SIGTERM'));
     process.on('uncaughtException', (err) => {

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

@@ -0,0 +1,4 @@
+/** Preserve actionable domain errors while redacting storage and network diagnostics. */
+export declare function sanitizeServerError(error: unknown): string;
+/** Keep bounded local diagnostics for redacted infrastructure failures. */
+export declare function serverErrorDiagnostics(error: unknown): Record<string, unknown>;