bunsane 0.2.10 → 0.3.1

package/core/EntityHookManager.ts

@@ -15,7 +15,7 @@ import {
     type LifecycleEvent
 } from "./events/EntityLifecycleEvents";
 import { logger as MainLogger } from "./Logger";
-import ApplicationLifecycle, { ApplicationPhase } from "./ApplicationLifecycle";
+import ApplicationLifecycle, { ApplicationPhase, type PhaseChangeEvent } from "./ApplicationLifecycle";
 
 const logger = MainLogger.child({ scope: "EntityHookManager" });
 
@@ -99,6 +99,7 @@ class EntityHookManager {
     private hooks: Map<string, RegisteredHook[]> = new Map();
     private hookCounter: number = 0;
     private metrics: Map<string, HookMetrics> = new Map();
+    private phaseListener: ((event: PhaseChangeEvent) => void) | null = null;
     private globalMetrics: HookMetrics = {
         totalExecutions: 0,
         totalExecutionTime: 0,
@@ -117,7 +118,7 @@ class EntityHookManager {
      */
     private initializeLifecycleIntegration(): void {
         // Wait for components to be ready before allowing hook registration
-        ApplicationLifecycle.addPhaseListener((event) => {
+        this.phaseListener = (event: PhaseChangeEvent) => {
             const phase = event.detail;
             switch (phase) {
                 case ApplicationPhase.COMPONENTS_READY:
@@ -127,7 +128,15 @@ class EntityHookManager {
                     logger.info("EntityHookManager fully operational");
                     break;
             }
-        });
+        };
+        ApplicationLifecycle.addPhaseListener(this.phaseListener);
+    }
+
+    public dispose(): void {
+        if (this.phaseListener) {
+            ApplicationLifecycle.removePhaseListener(this.phaseListener);
+            this.phaseListener = null;
+        }
     }
 
     /**
@@ -293,14 +302,34 @@ class EntityHookManager {
 
             try {
                 if (hook.options.timeout && hook.options.timeout > 0) {
-                    // Execute with timeout
+                    // Execute with timeout. Timer handle is stored so the
+                    // normal-completion path clears it (no leaked pending
+                    // timers per successful hook). The underlying callback
+                    // promise is attached with a detached .catch so a late
+                    // rejection after timeout does not escape as unhandled
+                    // (H-HOOK-2 / H-MEM-2).
+                    let timerHandle: ReturnType<typeof setTimeout> | null = null;
                     const timeoutPromise = new Promise<never>((_, reject) => {
-                        setTimeout(() => reject(new Error(`Hook ${hook.id} timed out after ${hook.options.timeout}ms`)), hook.options.timeout);
+                        timerHandle = setTimeout(
+                            () => reject(new Error(`Hook ${hook.id} timed out after ${hook.options.timeout}ms`)),
+                            hook.options.timeout
+                        );
                     });
-                    await Promise.race([hook.callback(event), timeoutPromise]);
+                    const hookPromise = Promise.resolve().then(() => hook.callback(event));
+                    hookPromise.catch((err) => {
+                        logger.warn({ hookId: hook.id, err }, `Late rejection from hook after timeout`);
+                    });
+                    try {
+                        await Promise.race([hookPromise, timeoutPromise]);
+                    } finally {
+                        if (timerHandle) clearTimeout(timerHandle);
+                    }
                 } else {
-                    // Execute normally
-                    hook.callback(event);
+                    // Always await — callback may be an async function declared
+                    // with async:false by mistake. Without await, a rejection
+                    // from such a callback escapes as an unhandled rejection
+                    // and crashes the process under strict mode (C13).
+                    await hook.callback(event);
                 }
             } catch (error) {
                 logger.error(`Error executing sync hook ${hook.id} for event ${eventType}: ${error}`);
@@ -324,12 +353,26 @@ class EntityHookManager {
 
                 try {
                     if (hook.options.timeout && hook.options.timeout > 0) {
-                        // Execute with timeout
-                        const hookPromise = hook.callback(event);
+                        // Execute with timeout. See sync path for rationale —
+                        // clear the timer on normal completion and detach a
+                        // .catch on the hook promise so late rejections do
+                        // not escape (H-HOOK-2 / H-MEM-2).
+                        let timerHandle: ReturnType<typeof setTimeout> | null = null;
+                        const hookPromise = Promise.resolve().then(() => hook.callback(event));
+                        hookPromise.catch((err) => {
+                            logger.warn({ hookId: hook.id, err }, `Late rejection from hook after timeout`);
+                        });
                         const timeoutPromise = new Promise<never>((_, reject) => {
-                            setTimeout(() => reject(new Error(`Hook ${hook.id} timed out after ${hook.options.timeout}ms`)), hook.options.timeout);
+                            timerHandle = setTimeout(
+                                () => reject(new Error(`Hook ${hook.id} timed out after ${hook.options.timeout}ms`)),
+                                hook.options.timeout
+                            );
                         });
-                        await Promise.race([hookPromise, timeoutPromise]);
+                        try {
+                            await Promise.race([hookPromise, timeoutPromise]);
+                        } finally {
+                            if (timerHandle) clearTimeout(timerHandle);
+                        }
                     } else {
                         // Execute normally
                         await hook.callback(event);
@@ -467,14 +510,27 @@ class EntityHookManager {
 
                 try {
                     if (hook.options.timeout && hook.options.timeout > 0) {
-                        // Execute with timeout
+                        // Same cleanup pattern as single-event path (H-HOOK-2 / H-MEM-2).
+                        let timerHandle: ReturnType<typeof setTimeout> | null = null;
+                        const hookPromise = Promise.resolve().then(() => hook.callback(event));
+                        hookPromise.catch((err) => {
+                            logger.warn({ hookId: hook.id, err }, `Late rejection from hook after timeout`);
+                        });
                         const timeoutPromise = new Promise<never>((_, reject) => {
-                            setTimeout(() => reject(new Error(`Hook ${hook.id} timed out after ${hook.options.timeout}ms`)), hook.options.timeout);
+                            timerHandle = setTimeout(
+                                () => reject(new Error(`Hook ${hook.id} timed out after ${hook.options.timeout}ms`)),
+                                hook.options.timeout
+                            );
                         });
-                        await Promise.race([hook.callback(event), timeoutPromise]);
+                        try {
+                            await Promise.race([hookPromise, timeoutPromise]);
+                        } finally {
+                            if (timerHandle) clearTimeout(timerHandle);
+                        }
                     } else {
-                        // Execute normally
-                        hook.callback(event);
+                        // Await so async callbacks do not escape as unhandled
+                        // rejections (C13 parity).
+                        await hook.callback(event);
                     }
                 } catch (error) {
                     logger.error(`Error executing sync hook ${hook.id} for event ${eventType}: ${error}`);
@@ -518,12 +574,23 @@ class EntityHookManager {
                     (async () => {
                         try {
                             if (hook.options.timeout && hook.options.timeout > 0) {
-                                // Execute with timeout
-                                const hookPromise = hook.callback(event);
+                                // Same cleanup pattern (H-HOOK-2 / H-MEM-2).
+                                let timerHandle: ReturnType<typeof setTimeout> | null = null;
+                                const hookPromise = Promise.resolve().then(() => hook.callback(event));
+                                hookPromise.catch((err) => {
+                                    logger.warn({ hookId: hook.id, err }, `Late rejection from hook after timeout`);
+                                });
                                 const timeoutPromise = new Promise<never>((_, reject) => {
-                                    setTimeout(() => reject(new Error(`Hook ${hook.id} timed out after ${hook.options.timeout}ms`)), hook.options.timeout);
+                                    timerHandle = setTimeout(
+                                        () => reject(new Error(`Hook ${hook.id} timed out after ${hook.options.timeout}ms`)),
+                                        hook.options.timeout
+                                    );
                                 });
-                                await Promise.race([hookPromise, timeoutPromise]);
+                                try {
+                                    await Promise.race([hookPromise, timeoutPromise]);
+                                } finally {
+                                    if (timerHandle) clearTimeout(timerHandle);
+                                }
                             } else {
                                 // Execute normally
                                 await hook.callback(event);

package/core/EntityManager.ts

@@ -1,18 +1,27 @@
-import ApplicationLifecycle, { ApplicationPhase } from "./ApplicationLifecycle";
+import ApplicationLifecycle, { ApplicationPhase, type PhaseChangeEvent } from "./ApplicationLifecycle";
 import type { IEntity } from "./EntityInterface";
 
 class EntityManager {
     static #instance: EntityManager;
     private dbReady = false;
     private entityQueue: IEntity[] = [];
+    private phaseListener: ((event: PhaseChangeEvent) => void) | null = null;
 
     constructor() {
-        ApplicationLifecycle.addPhaseListener(async (event) => {
+        this.phaseListener = async (event: PhaseChangeEvent) => {
             if (event.detail === ApplicationPhase.DATABASE_READY) {
                 this.dbReady = true;
                 await this.savePendingEntities();
             }
-        });
+        };
+        ApplicationLifecycle.addPhaseListener(this.phaseListener);
+    }
+
+    public dispose(): void {
+        if (this.phaseListener) {
+            ApplicationLifecycle.removePhaseListener(this.phaseListener);
+            this.phaseListener = null;
+        }
     }
 
     public deleteEntity(entity: IEntity, force: boolean = false) {

package/core/Logger.ts

@@ -9,6 +9,10 @@ export const logger = pino({
             'config.password', '*.password', '*.secret', '*.token',
             '*.accessKeyId', '*.secretAccessKey', '*.sessionToken',
             'accessKeyId', 'secretAccessKey', 'sessionToken',
+            'headers.authorization', 'headers.cookie', 'headers["set-cookie"]',
+            'req.headers.authorization', 'req.headers.cookie',
+            '*.headers.authorization', '*.headers.cookie',
+            'redisUrl', '*.redisUrl', 'connectionString', '*.connectionString',
         ],
         censor: '[REDACTED]',
     },

package/core/RequestContext.ts

@@ -3,6 +3,7 @@ import { createRequestLoaders } from './RequestLoaders';
 import type { RequestLoaders } from './RequestLoaders';
 import db from '../database';
 import { CacheManager } from './cache/CacheManager';
+import { getRequestId } from './middleware/RequestId';
 
 declare module 'graphql-yoga' {
   interface Context {
@@ -26,7 +27,9 @@ export function createRequestContextPlugin(): Plugin {
       const cacheManager = CacheManager.getInstance();
       // Mount loaders at context.loaders to match ArcheType.ts resolver access pattern
       (args as any).contextValue.loaders = createRequestLoaders(db, cacheManager);
-      (args as any).contextValue.requestId = crypto.randomUUID();
+      // Prefer the HTTP-layer request id (from requestId() middleware's
+      // AsyncLocalStorage) so access log + GraphQL logs share the same id.
+      (args as any).contextValue.requestId = getRequestId() ?? crypto.randomUUID();
       (args as any).contextValue.cacheManager = cacheManager;
     },
   };

package/core/SchedulerManager.ts

@@ -1,5 +1,5 @@
 import { logger } from "./Logger";
-import ApplicationLifecycle, { ApplicationPhase } from "./ApplicationLifecycle";
+import ApplicationLifecycle, { ApplicationPhase, type PhaseChangeEvent } from "./ApplicationLifecycle";
 import {
     ScheduleInterval
 } from "../types/scheduler.types";
@@ -30,6 +30,8 @@ export class SchedulerManager {
     private eventListeners: SchedulerEventCallback[] = [];
     public config: SchedulerConfig;
     private distributedLock: DistributedLock;
+    private phaseListener: ((event: PhaseChangeEvent) => void) | null = null;
+    private inflightTasks: Set<Promise<any>> = new Set();
     private metrics: SchedulerMetrics = {
         totalTasks: 0,
         runningTasks: 0,
@@ -76,14 +78,22 @@ export class SchedulerManager {
     }
 
     private initializeLifecycleIntegration(): void {
-        ApplicationLifecycle.addPhaseListener((event) => {
+        this.phaseListener = (event) => {
             const phase = event.detail;
             if (phase === ApplicationPhase.APPLICATION_READY) {
                 if (this.config.runOnStart) {
                     this.start();
                 }
             }
-        });
+        };
+        ApplicationLifecycle.addPhaseListener(this.phaseListener);
+    }
+
+    public disposeLifecycleIntegration(): void {
+        if (this.phaseListener) {
+            ApplicationLifecycle.removePhaseListener(this.phaseListener);
+            this.phaseListener = null;
+        }
     }
 
     public registerTask(taskInfo: ScheduledTaskInfo): void {
@@ -99,12 +109,10 @@ export class SchedulerManager {
             throw error;
         }
 
-        // Validate query configuration
-        if (!taskInfo.options?.query && !taskInfo.options?.componentTarget && !taskInfo.componentTarget) {
-            const error = new Error(`Invalid task info: must provide either query function, componentTarget config, or legacy componentTarget`);
-            loggerInstance.error(`Failed to register task: ${error.message}`);
-            throw error;
-        }
+        // Time-based tasks (no query, no componentTarget) are allowed — they
+        // invoke the handler with no entity arguments on each tick. Useful
+        // for external polling, stats aggregation, or ad-hoc queries inside
+        // the callback.
 
         if (!taskInfo.service) {
             const error = new Error(`Task ${taskInfo.id} has no service instance`);
@@ -308,11 +316,34 @@ export class SchedulerManager {
     }
 
     private async executeTask(taskId: string): Promise<void> {
+        // Track this execution so stop() can await in-flight work before
+        // resources (DB pool, cache) are torn down. Without this, a task mid-
+        // write during SIGTERM hits a closed DB pool and silently corrupts
+        // or loses data.
+        const p = this.doExecuteTask(taskId);
+        this.inflightTasks.add(p);
+        p.finally(() => this.inflightTasks.delete(p));
+        return p;
+    }
+
+    private async doExecuteTask(taskId: string): Promise<void> {
         const taskInfo = this.tasks.get(taskId);
         if (!taskInfo || !taskInfo.enabled) {
             return;
         }
 
+        // Skip if the previous tick is still executing. Without this guard
+        // a slow task with interval < execution-time burns a lock-acquire
+        // round-trip every tick and floods the skipped-executions metric
+        // (H-SCHED-1). Cheap in-process check before reaching out to PG.
+        if (taskInfo.isRunning) {
+            this.metrics.skippedExecutions++;
+            if (this.config.enableLogging) {
+                loggerInstance.debug(`Task ${taskInfo.name} skipped - previous execution still running`);
+            }
+            return;
+        }
+
         if (this.metrics.runningTasks >= this.config.maxConcurrentTasks) {
             if (this.config.enableLogging) {
                 loggerInstance.warn(`Maximum concurrent tasks reached. Skipping execution of ${taskInfo.name}`);
@@ -362,7 +393,7 @@ export class SchedulerManager {
         try {
             // Create query based on targeting configuration
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            let query: Query<any>;
+            let query: Query<any> | null = null;
 
             if (taskInfo.options?.query) {
                 // Use custom query function (preferred approach)
@@ -374,16 +405,16 @@ export class SchedulerManager {
             } else if (taskInfo.componentTarget) {
                 // Use legacy single component targeting (deprecated - use query instead)
                 query = new Query().with(taskInfo.componentTarget);
-            } else {
-                throw new Error('No query function or component target specified');
             }
+            // else: time-based task — no entity selection. Handler invoked
+            // with no arguments on each tick.
 
             // Apply entity limit if specified (can be used with query function)
-            if (taskInfo.options?.maxEntitiesPerExecution) {
+            if (query && taskInfo.options?.maxEntitiesPerExecution) {
                 query.take(taskInfo.options.maxEntitiesPerExecution);
             }
 
-            const entities = await query.exec();
+            const entities = query ? await query.exec() : [];
 
             // Execute the scheduled method with the entities array
             const method = taskInfo.service[taskInfo.methodName];
@@ -391,9 +422,11 @@ export class SchedulerManager {
                 throw new Error(`Method ${taskInfo.methodName} not found on service`);
             }
 
-            // Execute with timeout
+            // Execute with timeout. Time-based tasks receive no entity arg.
             const result = await this.executeWithTimeout(
-                method.call(taskInfo.service, entities),
+                query
+                    ? method.call(taskInfo.service, entities)
+                    : method.call(taskInfo.service),
                 timeout,
                 taskInfo
             );
@@ -492,7 +525,7 @@ export class SchedulerManager {
         });
     }
 
-    public async stop(): Promise<void> {
+    public async stop(drainTimeoutMs: number = 15_000): Promise<void> {
         if (!this.isRunning) {
             loggerInstance.warn("Scheduler is not running");
             return;
@@ -500,16 +533,39 @@ export class SchedulerManager {
 
         this.isRunning = false;
 
-        // Clear all intervals and timeouts
+        // Clear all intervals and timeouts so no new executions start.
         for (const intervalId of this.intervals.values()) {
             clearInterval(intervalId);
             clearTimeout(intervalId as any);
         }
         this.intervals.clear();
 
+        // Drain in-flight tasks before releasing locks + returning control to
+        // App.shutdown (which will close the DB pool). Bounded by drainTimeoutMs
+        // so shutdown cannot hang forever on a stuck task.
+        if (this.inflightTasks.size > 0) {
+            const inflightSnapshot = [...this.inflightTasks];
+            if (this.config.enableLogging) {
+                loggerInstance.info(`Draining ${inflightSnapshot.length} in-flight scheduled task(s), timeout=${drainTimeoutMs}ms`);
+            }
+            const drainTimer = new Promise<'timeout'>((resolve) => {
+                const t = setTimeout(() => resolve('timeout'), drainTimeoutMs);
+                t.unref?.();
+            });
+            const result = await Promise.race([
+                Promise.allSettled(inflightSnapshot).then(() => 'drained' as const),
+                drainTimer,
+            ]);
+            if (result === 'timeout') {
+                loggerInstance.warn(`Scheduler drain timed out after ${drainTimeoutMs}ms with ${this.inflightTasks.size} task(s) still running`);
+            }
+        }
+
         // Release all distributed locks held by this instance
         await this.distributedLock.releaseAll();
 
+        this.disposeLifecycleIntegration();
+
         if (this.config.enableLogging) {
             loggerInstance.info("Scheduler stopped");
         }
@@ -621,12 +677,20 @@ export class SchedulerManager {
     }
 
     /**
-     * Execute a task with timeout enforcement
+     * Execute a task with timeout enforcement.
+     *
+     * Note: JS has no way to cancel an arbitrary Promise — on timeout the
+     * wrapper rejects but the underlying task continues. The second .catch
+     * below captures a late rejection after the wrapper already rejected,
+     * preventing an unhandled-rejection process crash (H-SCHED-5). The
+     * `settled` flag guards against double-settle.
      */
     private async executeWithTimeout<T>(task: Promise<T>, timeoutMs: number, taskInfo: ScheduledTaskInfo): Promise<T> {
         return new Promise((resolve, reject) => {
+            let settled = false;
             const timeoutId = setTimeout(() => {
-                clearTimeout(timeoutId);
+                if (settled) return;
+                settled = true;
                 this.metrics.timedOutTasks++;
                 this.updateTaskMetrics(taskInfo.id, {
                     timeoutCount: (this.metrics.taskMetrics[taskInfo.id]?.timeoutCount || 0) + 1
@@ -643,10 +707,20 @@ export class SchedulerManager {
 
             task
                 .then((result) => {
+                    if (settled) return;
+                    settled = true;
                     clearTimeout(timeoutId);
                     resolve(result);
                 })
                 .catch((error) => {
+                    if (settled) {
+                        // Late rejection after timeout. Log only — the wrapper
+                        // promise is already settled, so re-rejecting would be
+                        // a no-op but the rejection would escape as unhandled.
+                        loggerInstance.warn({ taskId: taskInfo.id, err: error }, 'Late rejection from scheduled task after timeout');
+                        return;
+                    }
+                    settled = true;
                     clearTimeout(timeoutId);
                     reject(error);
                 });
@@ -678,10 +752,19 @@ export class SchedulerManager {
                 loggerInstance.warn(`Task ${taskInfo.name} failed (attempt ${taskInfo.retryCount}/${maxRetries}), retrying in ${retryDelay}ms: ${error.message}`);
             }
 
-            // Schedule retry
-            setTimeout(async () => {
+            // Schedule retry. Track the timer handle in `intervals` under a
+            // unique key so `stop()` can clear it (H-SCHED-3); without this
+            // the retry fires post-shutdown against a closed DB pool. Also
+            // skip the retry if the scheduler is no longer running by the
+            // time the timer fires, and rely on the new isRunning guard in
+            // doExecuteTask (H-SCHED-1) to prevent retry/tick overlap.
+            const retryKey = `${taskInfo.id}:retry:${taskInfo.retryCount}`;
+            const retryHandle = setTimeout(async () => {
+                this.intervals.delete(retryKey);
+                if (!this.isRunning) return;
                 await this.executeTask(taskInfo.id);
             }, retryDelay);
+            this.intervals.set(retryKey, retryHandle as any);
 
             this.emitEvent({
                 type: 'task.retry',

package/core/cache/CacheFactory.ts

@@ -68,7 +68,9 @@ export class CacheFactory {
             lazyConnect: false,
             enableReadyCheck: true,
             connectTimeout: config.redis.connectTimeout,
-            commandTimeout: config.redis.commandTimeout
+            commandTimeout: config.redis.commandTimeout,
+            maxReconnectAttempts: config.redis.maxReconnectAttempts,
+            enableOfflineQueue: config.redis.enableOfflineQueue
         };
 
         const { password: _pw, ...safeConfig } = redisConfig;

package/core/cache/CacheManager.ts

@@ -201,27 +201,45 @@ export class CacheManager {
 
         try {
             const effectiveTTL = ttl ?? this.config.component.ttl;
-            
-            // Convert BaseComponent to ComponentData format for cache compatibility with DataLoader
+
+            // Convert BaseComponent to ComponentData format for cache
+            // compatibility with DataLoader. BaseComponent does not track
+            // createdAt/updatedAt today (data-model gap), but we preserve an
+            // existing cache entry's createdAt when available and stamp
+            // updatedAt=now, so consumers see monotonic update times rather
+            // than a reset on every write-through (H-CACHE-3 — full fix
+            // requires BaseComponent timestamp tracking).
             for (const component of components) {
                 const typeId = componentType || component.getTypeID();
                 const key = `component:${entityId}:${typeId}`;
-                
-                // Create ComponentData structure matching what DataLoader expects
+
+                const now = new Date();
+                let createdAt: Date = now;
+                try {
+                    const existing = await this.provider.get<ComponentData>(key);
+                    if (existing && existing.createdAt) {
+                        createdAt = existing.createdAt instanceof Date
+                            ? existing.createdAt
+                            : new Date(existing.createdAt);
+                    }
+                } catch {
+                    // Cache miss or provider error — fall through to now.
+                }
+
                 const componentData: ComponentData = {
                     id: component.id,
                     entityId: entityId,
                     typeId: typeId,
                     data: component.data(),
-                    createdAt: new Date(), // Component doesn't track this, use current time
-                    updatedAt: new Date(),
+                    createdAt,
+                    updatedAt: now,
                     deletedAt: null
                 };
-                
+
                 await this.provider.set(key, componentData, effectiveTTL);
             }
         } catch (error) {
-            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting components in cache', error });
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting components in cache', err: error });
         }
     }
 
@@ -266,6 +284,24 @@ export class CacheManager {
         }
     }
 
+    /**
+     * Invalidate cached state (entity + all components) for a batch of
+     * entity IDs. Call this after a raw-SQL write (db.unsafe) that bypasses
+     * Entity.set/save, so downstream reads observe fresh data instead of
+     * stale L1/L2 cache entries.
+     */
+    public async invalidateEntities(entityIds: string[]): Promise<void> {
+        if (!this.config.enabled || entityIds.length === 0) {
+            return;
+        }
+        await Promise.all(
+            entityIds.flatMap(id => [
+                this.invalidateEntity(id),
+                this.invalidateAllEntityComponents(id),
+            ])
+        );
+    }
+
     /**
      * Invalidate all components for a specific entity from cache
      * Uses pattern matching to efficiently clear all component caches for an entity
@@ -489,21 +525,40 @@ export class CacheManager {
     }
 
     /**
-     * Shutdown the current provider (disconnect Redis, stop Memory cleanup timer)
+     * Shutdown the current provider (disconnect Redis, stop Memory cleanup
+     * timer). For `MultiLevelCache`, descends into both L1 and L2 layers —
+     * previously the method only dispatched on the top-level provider, so a
+     * MultiLevelCache left its inner `MemoryCache` cleanup timer and Redis
+     * connection alive (H-CACHE-2).
      */
     private async shutdownProvider(): Promise<void> {
+        const shutdownOne = async (p: any) => {
+            try {
+                if (p && typeof p.disconnect === 'function') {
+                    await p.disconnect();
+                }
+                if (p && typeof p.stopCleanup === 'function') {
+                    p.stopCleanup();
+                }
+            } catch (error) {
+                logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error shutting down layer', err: error });
+            }
+        };
+
         try {
             const provider = this.provider as any;
-            // RedisCache has disconnect()
-            if (typeof provider.disconnect === 'function') {
-                await provider.disconnect();
-            }
-            // MemoryCache has stopCleanup()
-            if (typeof provider.stopCleanup === 'function') {
-                provider.stopCleanup();
+            // MultiLevelCache exposes getL1Cache / getL2Cache.
+            if (provider && typeof provider.getL1Cache === 'function') {
+                await shutdownOne(provider.getL1Cache());
+                if (typeof provider.getL2Cache === 'function') {
+                    await shutdownOne(provider.getL2Cache());
+                }
+                return;
             }
+            // Single-layer providers.
+            await shutdownOne(provider);
         } catch (error) {
-            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error shutting down provider', error });
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error shutting down provider', err: error });
         }
     }