bunqueue 2.8.60 → 2.9.2

package/dist/infrastructure/server/handlers/monitoring/workers.d.ts

@@ -1,6 +1,6 @@
 import type { ListWorkersCommand, RegisterWorkerCommand, UnregisterWorkerCommand } from '../../../../domain/types/command';
 import type { Response } from '../../../../domain/types/response';
 import type { HandlerContext } from '../../types';
-export declare function handleRegisterWorker(command: RegisterWorkerCommand, context: HandlerContext, requestId?: string): Response;
-export declare function handleUnregisterWorker(command: UnregisterWorkerCommand, context: HandlerContext, requestId?: string): Response;
-export declare function handleListWorkers(_command: ListWorkersCommand, context: HandlerContext, requestId?: string): Response;
+export declare function handleRegisterWorker(command: RegisterWorkerCommand, context: HandlerContext, requestId?: string): Response | Promise<Response>;
+export declare function handleUnregisterWorker(command: UnregisterWorkerCommand, context: HandlerContext, requestId?: string): Response | Promise<Response>;
+export declare function handleListWorkers(_command: ListWorkersCommand, context: HandlerContext, requestId?: string): Response | Promise<Response>;

package/dist/infrastructure/server/handlers/monitoring/workers.js

@@ -4,14 +4,15 @@ function computeWorkerStatus(lastSeen, now) {
     return now - lastSeen < WORKER_TIMEOUT_MS ? 'active' : 'stale';
 }
 export function handleRegisterWorker(command, context, requestId) {
-    const worker = context.queueManager.registerWorker(command.name, command.queues, command.concurrency, {
+    const manager = context.queueManager;
+    const options = {
         workerId: command.workerId,
         hostname: command.hostname,
         pid: command.pid,
         startedAt: command.startedAt,
         clientId: context.clientId,
-    });
-    return response.data({
+    };
+    const complete = (worker) => response.data({
         workerId: worker.id,
         name: worker.name,
         queues: worker.queues,
@@ -26,15 +27,24 @@ export function handleRegisterWorker(command, context, requestId) {
         failedJobs: worker.failedJobs,
         currentJob: worker.currentJob,
     }, requestId);
+    return manager.registerWorkerDurable
+        ? manager
+            .registerWorkerDurable(command.name, command.queues, command.concurrency, options)
+            .then(complete)
+        : complete(manager.registerWorker(command.name, command.queues, command.concurrency, options));
 }
 export function handleUnregisterWorker(command, context, requestId) {
-    return context.queueManager.unregisterWorker(command.workerId)
+    const manager = context.queueManager;
+    const complete = (removed) => removed
         ? response.data({ removed: true }, requestId)
         : response.error('Worker not found', requestId);
+    return manager.unregisterWorkerDurable
+        ? manager.unregisterWorkerDurable(command.workerId, context.clientId).then(complete)
+        : complete(manager.unregisterWorker(command.workerId));
 }
-export function handleListWorkers(_command, context, requestId) {
-    const workers = context.queueManager.workerManager.list();
+function workerListResponse(workers, requestId, lifetime) {
     const now = Date.now();
+    const active = workers.filter((worker) => computeWorkerStatus(worker.lastSeen, now) === 'active');
     return response.data({
         workers: workers.map((worker) => ({
             id: worker.id,
@@ -52,6 +62,20 @@ export function handleListWorkers(_command, context, requestId) {
             currentJob: worker.currentJob,
             uptime: now - worker.registeredAt,
         })),
-        stats: context.queueManager.workerManager.getStats(),
+        stats: {
+            total: workers.length,
+            active: active.length,
+            totalProcessed: lifetime?.totalProcessed ??
+                workers.reduce((sum, worker) => sum + worker.processedJobs, 0),
+            totalFailed: lifetime?.totalFailed ?? workers.reduce((sum, worker) => sum + worker.failedJobs, 0),
+            activeJobs: lifetime?.activeJobs ?? workers.reduce((sum, worker) => sum + worker.activeJobs, 0),
+            concurrencySlots: active.reduce((sum, worker) => sum + worker.concurrency, 0),
+        },
     }, requestId);
 }
+export function handleListWorkers(_command, context, requestId) {
+    const manager = context.queueManager;
+    return manager.listWorkersDurable
+        ? manager.listWorkersDurable().then((workers) => workerListResponse(workers, requestId))
+        : workerListResponse(manager.workerManager.list(), requestId, manager.workerManager.getStats());
+}

package/dist/infrastructure/server/handlers/pushBatchValidation.d.ts

@@ -6,6 +6,8 @@
  */
 import { type JobInput } from '../../../domain/types/job';
 import type { HandlerContext } from '../types';
+/** Validate PUSH dependencies against the authoritative engine when it exposes one. */
+export declare function validatePushDependencies(dependencies: readonly string[] | undefined, ctx: HandlerContext): string | null | Promise<string | null>;
 /**
  * Validate every job of a PUSHB batch. Returns an error message naming the
  * offending index, or null when the whole batch is valid.
@@ -20,4 +22,4 @@ import type { HandlerContext } from '../types';
  * can never resolve. jobIndex/completedJobs/depCompletions are hoisted out
  * of the loop because PUSHB is the bulk hot path.
  */
-export declare function validatePushBatchJobs(jobs: JobInput[], ctx: HandlerContext): string | null;
+export declare function validatePushBatchJobs(jobs: JobInput[], ctx: HandlerContext): string | null | Promise<string | null>;

package/dist/infrastructure/server/handlers/pushBatchValidation.js

@@ -4,8 +4,33 @@
  * validateJobData/validateJobOptions bounds and the same dependsOn
  * existence gate handlePush enforces (core.ts).
  */
-import { normalizeLegacyJobPayload } from '../../../domain/types/job';
-import { validateJobData, validateJobOptions } from '../protocol';
+import { jobId, normalizeLegacyJobPayload, } from '../../../domain/types/job';
+import { validateGroupId, validateJobData, validateJobOptions } from '../protocol';
+function dependencyExistsLocally(id, ctx) {
+    return (ctx.queueManager.getJobIndex().has(id) ||
+        ctx.queueManager.getCompletedJobs().has(id) ||
+        ctx.queueManager.getDepCompletions().has(id));
+}
+/** Validate PUSH dependencies against the authoritative engine when it exposes one. */
+export function validatePushDependencies(dependencies, ctx) {
+    if (!dependencies || dependencies.length === 0)
+        return null;
+    const manager = ctx.queueManager;
+    if (!manager.findMissingDependenciesDurable) {
+        for (const dependency of dependencies) {
+            if (!dependencyExistsLocally(jobId(dependency), ctx)) {
+                return `Dependency job not found: ${dependency}`;
+            }
+        }
+        return null;
+    }
+    const ids = dependencies.map(jobId);
+    return manager.findMissingDependenciesDurable(ids).then((missingIds) => {
+        const missing = new Set(missingIds.map(String));
+        const dependency = dependencies.find((id) => missing.has(String(id)));
+        return dependency === undefined ? null : `Dependency job not found: ${dependency}`;
+    });
+}
 /**
  * Validate every job of a PUSHB batch. Returns an error message naming the
  * offending index, or null when the whole batch is valid.
@@ -34,6 +59,24 @@ export function validatePushBatchJobs(jobs, ctx) {
             batchIds.add(job.customId);
         }
     }
+    const manager = ctx.queueManager;
+    if (manager.findMissingDependenciesDurable) {
+        const dependencies = jobs.flatMap((job) => (job.dependsOn ?? []).filter((id) => !(batchIds?.has(String(id)) ?? false)));
+        if (dependencies.length === 0) {
+            return validateJobs(jobs, { jobIndex, completedJobs, depCompletions, batchIds });
+        }
+        return manager.findMissingDependenciesDurable(dependencies).then((missingIds) => validateJobs(jobs, {
+            jobIndex,
+            completedJobs,
+            depCompletions,
+            batchIds,
+            missingDependencies: new Set(missingIds),
+        }));
+    }
+    return validateJobs(jobs, { jobIndex, completedJobs, depCompletions, batchIds });
+}
+function validateJobs(jobs, state) {
+    const { jobIndex, completedJobs, depCompletions, batchIds, missingDependencies } = state;
     for (let i = 0; i < jobs.length; i++) {
         const job = jobs[i];
         try {
@@ -45,6 +88,9 @@ export function validatePushBatchJobs(jobs, ctx) {
         const dataError = validateJobData(job.data);
         if (dataError)
             return `jobs[${i}]: ${dataError}`;
+        const groupError = validateGroupId(job.groupId);
+        if (groupError)
+            return `jobs[${i}]: ${groupError}`;
         const optionsError = validateJobOptions({
             priority: job.priority,
             delay: job.delay,
@@ -61,12 +107,14 @@ export function validatePushBatchJobs(jobs, ctx) {
                 if (key === job.customId) {
                     return `jobs[${i}]: Job cannot depend on itself: ${key}`;
                 }
-                const exists = jobIndex.has(depId) ||
-                    completedJobs.has(depId) ||
-                    // removeOnComplete parents leave only a bare completion id behind;
-                    // the gate must honor it exactly like PUSH does.
-                    depCompletions.has(depId) ||
-                    (batchIds?.has(key) ?? false);
+                const exists = missingDependencies
+                    ? !missingDependencies.has(depId)
+                    : jobIndex.has(depId) ||
+                        completedJobs.has(depId) ||
+                        // removeOnComplete parents leave only a bare completion id behind;
+                        // the gate must honor it exactly like PUSH does.
+                        depCompletions.has(depId) ||
+                        (batchIds?.has(key) ?? false);
                 if (!exists) {
                     return `jobs[${i}]: Dependency job not found: ${key}`;
                 }

package/dist/infrastructure/server/handlers/query.d.ts

@@ -16,7 +16,7 @@ export declare function handleGetState(cmd: Extract<Command, {
 /** Handle GetResult command */
 export declare function handleGetResult(cmd: Extract<Command, {
     cmd: 'GetResult';
-}>, ctx: HandlerContext, reqId?: string): Response;
+}>, ctx: HandlerContext, reqId?: string): Promise<Response>;
 /** Handle GetJobCounts command */
 export declare function handleGetJobCounts(cmd: Extract<Command, {
     cmd: 'GetJobCounts';

package/dist/infrastructure/server/handlers/query.js

@@ -6,6 +6,7 @@ import * as resp from '../../../domain/types/response';
 import { jobId } from '../../../domain/types/job';
 import { lastFailedReason } from '../../../domain/job/terminal';
 import { pausedView } from '../../../shared/pausedView';
+import { sanitizeServerError } from '../errors';
 function jobView(ctx, job, state) {
     return {
         ...job,
@@ -29,8 +30,8 @@ export async function handleGetState(cmd, ctx, reqId) {
     return { ok: true, id: cmd.id, state, reqId };
 }
 /** Handle GetResult command */
-export function handleGetResult(cmd, ctx, reqId) {
-    const result = ctx.queueManager.getResult(jobId(cmd.id));
+export async function handleGetResult(cmd, ctx, reqId) {
+    const result = await ctx.queueManager.getResultAsync(jobId(cmd.id));
     return { ok: true, id: cmd.id, result, reqId };
 }
 /** Handle GetJobCounts command */
@@ -86,7 +87,7 @@ export async function handleGetChildrenValues(cmd, ctx, reqId) {
         const values = await ctx.queueManager.getChildrenValues(jobId(cmd.id));
         return resp.data({ values }, reqId);
     }
-    catch {
-        return resp.data({ values: {} }, reqId);
+    catch (error) {
+        return resp.error(sanitizeServerError(error), reqId);
     }
 }

package/dist/infrastructure/server/http.js

@@ -10,6 +10,7 @@ import { WsHandler } from './wsHandler';
 import { jsonResponse, corsResponse, healthEndpoint, readinessEndpoint, gcEndpoint, heapStatsEndpoint, } from './httpEndpoints';
 import { loadTlsOptions } from './tls';
 import { routeHttpRequest } from './httpRouter';
+import { sanitizeServerError } from './errors';
 /**
  * Validate auth token against valid tokens set
  */
@@ -161,8 +162,7 @@ export function createHttpServer(queueManager, config) {
             return await routeHttpRequest(req, path, ctx, corsOrigins);
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : 'Internal error';
-            return jsonResponse({ ok: false, error: message }, 500);
+            return jsonResponse({ ok: false, error: sanitizeServerError(err) }, 500);
         }
     };
     // WebSocket handlers

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

@@ -3,7 +3,7 @@
  */
 import type { QueueManager } from '../../application/queueManager';
 /** Dashboard overview endpoint - aggregates all dashboard data in a single call */
-export declare function dashboardOverviewEndpoint(queueManager: QueueManager, corsOrigins?: Set<string>): Response;
+export declare function dashboardOverviewEndpoint(queueManager: QueueManager, corsOrigins?: Set<string>): Response | Promise<Response>;
 /** Dashboard queues endpoint - paginated queues with per-queue stats */
 export declare function dashboardQueuesEndpoint(queueManager: QueueManager, limit: number, offset: number, corsOrigins?: Set<string>): Response;
 /** Dashboard single queue detail endpoint */

package/dist/infrastructure/server/httpDashboardEndpoints.js

@@ -4,18 +4,31 @@
 import { latencyTracker } from '../../application/latencyTracker';
 import { throughputTracker } from '../../application/throughputTracker';
 import { pausedView } from '../../shared/pausedView';
+import { clientStorageStatus } from '../../shared/storageHealth';
 import { jsonResponse } from './httpResponse';
+const WORKER_TIMEOUT_MS = parseInt(Bun.env.WORKER_TIMEOUT_MS ?? '30000', 10);
 /** Dashboard overview endpoint - aggregates all dashboard data in a single call */
 export function dashboardOverviewEndpoint(queueManager, corsOrigins) {
+    const manager = queueManager;
+    if (manager.listWorkersDurable || manager.listCronsDurable) {
+        return Promise.all([
+            manager.listWorkersDurable
+                ? manager.listWorkersDurable()
+                : Promise.resolve(manager.workerManager.list()),
+            manager.listCronsDurable ? manager.listCronsDurable() : Promise.resolve(manager.listCrons()),
+        ]).then(([workers, crons]) => dashboardOverviewResponse(manager, workers, crons, corsOrigins));
+    }
+    return dashboardOverviewResponse(manager, manager.workerManager.list(), manager.listCrons(), corsOrigins);
+}
+function dashboardOverviewResponse(queueManager, workers, crons, corsOrigins) {
     const stats = queueManager.getStats();
     const rates = throughputTracker.getRates();
     const latencies = latencyTracker.getPercentiles();
     const avgLatencies = latencyTracker.getAverages();
     const memStats = queueManager.getMemoryStats();
-    const workers = queueManager.workerManager.list();
-    const workerStats = queueManager.workerManager.getStats();
-    const crons = queueManager.listCrons();
-    const storage = queueManager.getStorageStatus();
+    const now = Date.now();
+    const activeWorkers = workers.filter((worker) => now - worker.lastSeen < WORKER_TIMEOUT_MS);
+    const storage = clientStorageStatus(queueManager.getStorageStatus());
     const mem = process.memoryUsage();
     return jsonResponse({
         ok: true,
@@ -43,8 +56,8 @@ export function dashboardOverviewEndpoint(queueManager, corsOrigins) {
         },
         collections: memStats,
         workers: {
-            total: workerStats.total,
-            active: workerStats.active,
+            total: workers.length,
+            active: activeWorkers.length,
             list: workers
                 .slice(0, 100)
                 .map((w) => ({

package/dist/infrastructure/server/httpEndpoints.js

@@ -1,6 +1,7 @@
 /**
  * HTTP Endpoints - Health, diagnostics, and stats endpoints
  */
+import { clientStorageStatus, isStorageDegraded } from '../../shared/storageHealth';
 import { VERSION } from '../../shared/version';
 import { throughputTracker } from '../../application/throughputTracker';
 import { jsonResponse } from './httpResponse';
@@ -39,7 +40,8 @@ export function healthEndpoint(queueManager, wsCount, sseCount, tcpCount = 0) {
     const uptime = process.uptime();
     const memoryUsage = process.memoryUsage();
     const storageStatus = queueManager.getStorageStatus();
-    const isHealthy = !storageStatus.diskFull;
+    const clientStorage = clientStorageStatus(storageStatus);
+    const isHealthy = !isStorageDegraded(storageStatus);
     return jsonResponse({
         ok: isHealthy,
         status: isHealthy ? 'healthy' : 'degraded',
@@ -62,11 +64,11 @@ export function healthEndpoint(queueManager, wsCount, sseCount, tcpCount = 0) {
             heapTotal: Math.round(memoryUsage.heapTotal / 1024 / 1024),
             rss: Math.round(memoryUsage.rss / 1024 / 1024),
         },
-        ...(storageStatus.diskFull && {
+        ...(!isHealthy && {
             storage: {
-                diskFull: true,
-                error: storageStatus.error,
-                since: storageStatus.since,
+                diskFull: clientStorage.diskFull,
+                error: clientStorage.error,
+                since: clientStorage.since,
             },
         }),
     }, isHealthy ? 200 : 503);
@@ -74,11 +76,20 @@ export function healthEndpoint(queueManager, wsCount, sseCount, tcpCount = 0) {
 /** Readiness check - persistence failures must stop new traffic. */
 export function readinessEndpoint(queueManager, corsOrigins) {
     const storage = queueManager.getStorageStatus();
-    const ready = !storage.diskFull;
+    const clientStorage = clientStorageStatus(storage);
+    const ready = !isStorageDegraded(storage);
     return jsonResponse({
         ok: ready,
         ready,
-        ...(ready ? {} : { storage: { diskFull: true, error: storage.error, since: storage.since } }),
+        ...(ready
+            ? {}
+            : {
+                storage: {
+                    diskFull: clientStorage.diskFull,
+                    error: clientStorage.error,
+                    since: clientStorage.since,
+                },
+            }),
     }, ready ? 200 : 503, corsOrigins);
 }
 /** GC endpoint - force garbage collection */

package/dist/infrastructure/server/httpRouteQueues.js

@@ -13,6 +13,7 @@ const RE_QUEUE_CLEAN = /^\/queues\/([^/]+)\/clean$/;
 const RE_QUEUE_PROMOTE_JOBS = /^\/queues\/([^/]+)\/promote-jobs$/;
 const RE_QUEUE_RETRY_COMPLETED = /^\/queues\/([^/]+)\/retry-completed$/;
 const RE_QUEUE_WORKERS = /^\/queues\/([^/]+)\/workers$/;
+const WORKER_TIMEOUT_MS = parseInt(Bun.env.WORKER_TIMEOUT_MS ?? '30000', 10);
 export async function routeQueueRoutes(request, path, method, context, cors) {
     if (path === '/queues' && method === 'GET') {
         return jsonResponse(await handleCommand({ cmd: 'ListQueues' }, context), 200, cors);
@@ -26,7 +27,16 @@ export async function routeQueueRoutes(request, path, method, context, cors) {
     const queueWorkersMatch = path.match(RE_QUEUE_WORKERS);
     if (queueWorkersMatch && method === 'GET') {
         const queue = decodeURIComponent(queueWorkersMatch[1]);
-        const workers = context.queueManager.workerManager.getForQueue(queue);
+        const manager = context.queueManager;
+        let workers;
+        if (manager.listWorkersDurable) {
+            const durableWorkers = await manager.listWorkersDurable();
+            const now = Date.now();
+            workers = durableWorkers.filter((worker) => worker.queues.includes(queue) && now - worker.lastSeen < WORKER_TIMEOUT_MS);
+        }
+        else {
+            workers = manager.workerManager.getForQueue(queue);
+        }
         return jsonResponse({
             ok: true,
             workers: workers.map((worker) => ({

package/dist/infrastructure/server/protocol/validation.d.ts

@@ -1,4 +1,5 @@
 export declare function validateQueueName(name: string): string | null;
+export { validateGroupId } from '../../../domain/types/group';
 export declare function validateJobData(data: unknown): string | null;
 export declare function validateNumericField(value: unknown, name: string, options?: {
     min?: number;

package/dist/infrastructure/server/protocol/validation.js

@@ -7,6 +7,7 @@ export function validateQueueName(name) {
         return 'Queue name contains invalid characters';
     return null;
 }
+export { validateGroupId } from '../../../domain/types/group';
 export function validateJobData(data) {
     let json;
     try {

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

@@ -1,6 +1,6 @@
 export { createConnectionState, errorResponse, parseCommand, parseCommands, serializeResponse, } from './protocol/commands';
 export { FrameParser, FrameSizeError, MAX_FRAME_SIZE } from './protocol/frameParser';
 export { LineBuffer } from './protocol/lineBuffer';
-export { validateBackoffField, validateJobData, validateJobOptions, validateNumericField, validateQueueName, } from './protocol/validation';
+export { validateBackoffField, validateGroupId, validateJobData, validateJobOptions, validateNumericField, validateQueueName, } from './protocol/validation';
 export type { ConnectionState } from './types/protocol';
 export { validateWebhookUrl } from '../../shared/webhookValidation';

package/dist/infrastructure/server/protocol.js

@@ -1,5 +1,5 @@
 export { createConnectionState, errorResponse, parseCommand, parseCommands, serializeResponse, } from './protocol/commands';
 export { FrameParser, FrameSizeError, MAX_FRAME_SIZE } from './protocol/frameParser';
 export { LineBuffer } from './protocol/lineBuffer';
-export { validateBackoffField, validateJobData, validateJobOptions, validateNumericField, validateQueueName, } from './protocol/validation';
+export { validateBackoffField, validateGroupId, validateJobData, validateJobOptions, validateNumericField, validateQueueName, } from './protocol/validation';
 export { validateWebhookUrl } from '../../shared/webhookValidation';

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

@@ -0,0 +1,24 @@
+export interface ServerShutdownResources {
+    readonly shutdownTimeoutMs: number;
+    readonly stopStats: () => void;
+    readonly stopTcp: () => void;
+    readonly stopHttp: () => void;
+    readonly getActiveJobs: () => number;
+    readonly stopBackup?: () => void;
+    readonly emitShutdown: (signal: string) => void;
+    readonly stopCloud?: () => Promise<void>;
+    readonly shutdownStorage: () => Promise<void>;
+}
+export interface ServerShutdownRuntime {
+    readonly now: () => number;
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly stopRateLimiter: () => void;
+    readonly exit: (code: number) => void;
+    readonly info: (message: string, data?: Record<string, unknown>) => void;
+    readonly warn: (message: string, data?: Record<string, unknown>) => void;
+    readonly error: (message: string, data?: Record<string, unknown>) => void;
+    readonly cloudTimeoutMs: number;
+    readonly storageAttemptTimeoutMs: number;
+}
+/** Memoize the first shutdown so duplicate signals share one total cleanup task. */
+export declare function createServerShutdown(resources: ServerShutdownResources, overrides?: Partial<ServerShutdownRuntime>): (signal: string) => Promise<void>;

package/dist/infrastructure/server/shutdownCoordinator.js

@@ -0,0 +1,106 @@
+import { serverLog } from '../../shared/logger';
+import { stopRateLimiter } from './rateLimiter';
+const DEFAULT_RUNTIME = {
+    now: Date.now,
+    sleep: Bun.sleep,
+    stopRateLimiter,
+    exit: (code) => process.exit(code),
+    info: (message, data) => serverLog.info(message, data),
+    warn: (message, data) => serverLog.warn(message, data),
+    error: (message, data) => serverLog.error(message, data),
+    cloudTimeoutMs: 2_500,
+    storageAttemptTimeoutMs: 5_000,
+};
+function errorData(error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+}
+async function withTimeout(operation, timeoutMs, label) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+    });
+    try {
+        await Promise.race([Promise.resolve().then(operation), timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function bestEffort(label, operation, runtime) {
+    try {
+        await operation();
+    }
+    catch (error) {
+        runtime.warn(`${label} failed during shutdown`, errorData(error));
+    }
+}
+async function drainActiveJobs(resources, runtime) {
+    const startedAt = runtime.now();
+    while (runtime.now() - startedAt < resources.shutdownTimeoutMs) {
+        let active;
+        try {
+            active = resources.getActiveJobs();
+        }
+        catch (error) {
+            runtime.warn('Active-job inspection failed during shutdown', errorData(error));
+            return;
+        }
+        if (active === 0)
+            return;
+        runtime.info(`Waiting for ${active} active jobs...`);
+        await runtime.sleep(1_000);
+    }
+}
+async function shutdownStorage(resources, runtime) {
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        try {
+            await withTimeout(resources.shutdownStorage, runtime.storageAttemptTimeoutMs, `Storage shutdown attempt ${attempt}`);
+            return true;
+        }
+        catch (error) {
+            if (attempt === 1) {
+                runtime.warn('Storage shutdown failed; retrying once', errorData(error));
+            }
+            else {
+                runtime.error('Storage shutdown failed after retry', errorData(error));
+            }
+        }
+    }
+    return false;
+}
+async function performShutdown(signal, resources, runtime) {
+    let exitCode = 0;
+    runtime.info(`Received ${signal}, shutting down...`);
+    try {
+        await bestEffort('Statistics timer cleanup', resources.stopStats, runtime);
+        await bestEffort('Rate limiter cleanup', runtime.stopRateLimiter, runtime);
+        await bestEffort('TCP server stop', resources.stopTcp, runtime);
+        await bestEffort('HTTP server stop', resources.stopHttp, runtime);
+        if (resources.stopBackup) {
+            await bestEffort('Backup manager stop', resources.stopBackup, runtime);
+        }
+        await bestEffort('Active-job drain', () => drainActiveJobs(resources, runtime), runtime);
+        await bestEffort('Shutdown event emission', () => resources.emitShutdown(signal), runtime);
+        const stopCloud = resources.stopCloud;
+        if (stopCloud) {
+            await bestEffort('Cloud agent stop', () => withTimeout(stopCloud, runtime.cloudTimeoutMs, 'Cloud agent stop'), runtime);
+        }
+        if (!(await shutdownStorage(resources, runtime)))
+            exitCode = 1;
+    }
+    catch (error) {
+        exitCode = 1;
+        runtime.error('Unexpected shutdown coordinator failure', errorData(error));
+    }
+    finally {
+        runtime.info(exitCode === 0 ? 'Shutdown complete' : 'Shutdown completed with errors');
+        runtime.exit(exitCode);
+    }
+}
+/** Memoize the first shutdown so duplicate signals share one total cleanup task. */
+export function createServerShutdown(resources, overrides = {}) {
+    const runtime = { ...DEFAULT_RUNTIME, ...overrides };
+    let task = null;
+    return (signal) => (task ??= performShutdown(signal, resources, runtime));
+}

package/dist/infrastructure/server/sseHandler.js

@@ -54,7 +54,7 @@ export class SseHandler {
         }, SSE_HEARTBEAT_MS);
         this.statsInterval ??= setInterval(() => {
             if (this.clients.size > 0)
-                this.broadcastStats(qm);
+                void this.broadcastStats(qm);
         }, 5000);
         this.healthInterval ??= setInterval(() => {
             if (this.clients.size > 0)
@@ -180,8 +180,13 @@ export class SseHandler {
             this.clients.delete(clientId);
     }
     // ── Periodic broadcasts ────────────────────────────────────
-    broadcastStats(qm) {
-        this.sendTypedEvent('stats:snapshot', buildStatsSnapshot(qm));
+    async broadcastStats(qm) {
+        try {
+            this.sendTypedEvent('stats:snapshot', await buildStatsSnapshot(qm));
+        }
+        catch {
+            // A failed durable read must not be replaced by a stale local snapshot.
+        }
     }
     broadcastHealth(qm) {
         this.sendTypedEvent('health:status', buildHealthSnapshot(qm, this.clients.size, 'sse'));

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

@@ -0,0 +1,29 @@
+import type { QueueManager } from '../../application/queueManager';
+import type { ResolvedConfig } from '../../config';
+export type StorageDriver = ResolvedConfig['storageDriver'];
+/** Strategy boundary for one server persistence engine. */
+export interface ServerStorageAdapter {
+    readonly driver: StorageDriver;
+    startupError(config: ResolvedConfig): string | null;
+    create(config: ResolvedConfig): Promise<QueueManager>;
+    shutdown(manager: QueueManager): Promise<void>;
+    display(config: ResolvedConfig): string;
+}
+/** Immutable adapter registry: adding an engine does not change server bootstrap. */
+export declare class StorageAdapterRegistry {
+    private readonly adapters;
+    constructor(adapters: readonly ServerStorageAdapter[]);
+    resolve(driver: StorageDriver): ServerStorageAdapter;
+    drivers(): StorageDriver[];
+}
+/** Lifecycle facade that remembers which strategy owns each created manager. */
+export declare class ServerStorageManager {
+    private readonly registry;
+    private readonly owners;
+    private readonly shutdowns;
+    constructor(registry: StorageAdapterRegistry);
+    startupError(config: ResolvedConfig): string | null;
+    create(config: ResolvedConfig): Promise<QueueManager>;
+    shutdown(manager: QueueManager): Promise<boolean>;
+    display(config: ResolvedConfig): string;
+}