bunsane 0.2.9 → 0.3.0

package/core/App.ts

@@ -1,5 +1,6 @@
 import ApplicationLifecycle, {
     ApplicationPhase,
+    type PhaseChangeEvent,
 } from "./ApplicationLifecycle";
 import {
     GenerateTableName,
@@ -26,6 +27,14 @@ import studioEndpoint from "../endpoints";
 import { type Middleware, composeMiddleware } from "./Middleware";
 import { deepHealthCheck, readinessCheck } from "./health";
 import { validateEnv } from "./validateEnv";
+import {
+    RemoteManager,
+    registerRemoteHandlers,
+    setRemoteManager,
+} from "./remote";
+import type { RemoteManagerConfig } from "./remote";
+import type { CacheConfig } from "../config/cache.config";
+import { createRequestContextPlugin } from "./RequestContext";
 
 export type CorsConfig = {
     origin?: string | string[] | ((origin: string) => boolean);
@@ -70,10 +79,22 @@ export default class App {
     private composedHandler: ((req: Request) => Promise<Response>) | null = null;
 
     private studioEnabled: boolean = false;
+    private remote: RemoteManager | null = null;
+    private remoteConfig: Partial<RemoteManagerConfig> | null = null;
     private server: ReturnType<typeof Bun.serve> | null = null;
     private isShuttingDown = false;
     private isReady = false;
+    private cacheConfig: Partial<CacheConfig> | null = null;
+    private requestContextPluginEnabled = true;
+    private phaseListener: ((event: PhaseChangeEvent) => void) | null = null;
+    private signalHandlersRegistered = false;
+    private processHandlersRegistered = false;
+    private sigTermHandler: (() => void) | null = null;
+    private sigIntHandler: (() => void) | null = null;
+    private unhandledRejectionHandler: ((reason: unknown, promise: Promise<unknown>) => void) | null = null;
+    private uncaughtExceptionHandler: ((error: Error) => void) | null = null;
     private graphqlMaxDepth: number = 10;
+    private graphqlMaxComplexity: number = 1000;
     private shutdownGracePeriod = 10_000;
     private maxRequestBodySize = 50 * 1024 * 1024; // 50MB default
 
@@ -117,6 +138,9 @@ export default class App {
     }
 
     public setCors(cors: CorsConfig) {
+        if (cors.origin === undefined) {
+            throw new Error('[CORS] `origin` is required. Pass an explicit string, array, function, or "*" if you truly want to allow everyone.');
+        }
         this.config.cors = cors;
         // Warn about invalid configuration
         if (cors.credentials && cors.origin === '*') {
@@ -125,19 +149,29 @@ export default class App {
     }
 
     async init() {
+        // Register process-level error handlers FIRST so failures during init
+        // (DB prep, component registration, schema build) are observable. If
+        // registration happens later (e.g. in start()) any boot-sequence
+        // unhandled rejection is silently discarded by the runtime.
+        this.registerProcessHandlers();
+
         validateEnv();
         logger.trace(`Initializing App`);
         ComponentRegistry.init();
         ServiceRegistry.init();
         
-        // Initialize CacheManager
+        // Initialize CacheManager with merged config. MUST await — initialize()
+        // is async and sets up pub/sub for cross-instance invalidation. Previously
+        // only getInstance() was called, silently skipping pub/sub setup and
+        // ignoring any app-supplied config (C04).
         try {
             const { CacheManager } = await import('./cache/CacheManager');
             const cacheManager = CacheManager.getInstance();
-            // CacheManager initializes with default config, can be customized later
-            logger.info({ scope: 'cache', component: 'App', msg: 'CacheManager initialized' });
+            await cacheManager.initialize(this.cacheConfig ?? {});
+            const config = cacheManager.getConfig();
+            logger.info({ scope: 'cache', component: 'App', msg: 'CacheManager initialized', provider: config.provider, enabled: config.enabled, strategy: config.strategy });
         } catch (error) {
-            logger.warn({ scope: 'cache', component: 'App', msg: 'Failed to initialize CacheManager', error });
+            logger.warn({ scope: 'cache', component: 'App', msg: 'Failed to initialize CacheManager', err: error });
         }
         
         // Plugin initialization
@@ -147,7 +181,12 @@ export default class App {
             }
         }
 
-        ApplicationLifecycle.addPhaseListener(async (event) => {
+        // Remove any previous listener so repeated init() calls (tests) don't
+        // stack handlers on the lifecycle singleton.
+        if (this.phaseListener) {
+            ApplicationLifecycle.removePhaseListener(this.phaseListener);
+        }
+        this.phaseListener = async (event: PhaseChangeEvent) => {
             const phase = event.detail;
             logger.info(`Application phase changed to: ${phase}`);
             // Notify plugins of phase change
@@ -209,23 +248,39 @@ export default class App {
                         if (envDepth) {
                             this.graphqlMaxDepth = parseInt(envDepth, 10);
                         }
+                        const envComplexity = process.env.GRAPHQL_MAX_COMPLEXITY;
+                        if (envComplexity) {
+                            const parsed = parseInt(envComplexity, 10);
+                            if (Number.isFinite(parsed) && parsed >= 0) {
+                                this.graphqlMaxComplexity = parsed;
+                            }
+                        }
 
                         const yogaOptions = {
                             cors: this.config.cors,
                             maxDepth: this.graphqlMaxDepth || undefined,
+                            maxComplexity: this.graphqlMaxComplexity,
                         };
 
+                        // Auto-apply RequestContext plugin by default so
+                        // apps using @BelongsTo / @HasMany get DataLoader
+                        // batching without opt-in. Prevents N+1 query
+                        // explosion. Opt out via disableRequestContextPlugin().
+                        const effectivePlugins: Plugin[] = this.requestContextPluginEnabled
+                            ? [createRequestContextPlugin(), ...this.yogaPlugins]
+                            : [...this.yogaPlugins];
+
                         if (schema) {
                             this.yoga = createYogaInstance(
                                 schema,
-                                this.yogaPlugins,
+                                effectivePlugins,
                                 wrappedContextFactory,
                                 yogaOptions
                             );
                         } else {
                             this.yoga = createYogaInstance(
                                 undefined,
-                                this.yogaPlugins,
+                                effectivePlugins,
                                 wrappedContextFactory,
                                 yogaOptions
                             );
@@ -254,6 +309,40 @@ export default class App {
                             `Registered scheduled tasks for ${services.length} services`
                         );
 
+                        // Initialize RemoteManager (opt-in via enableRemote())
+                        if (this.remoteConfig) {
+                            try {
+                                const rmConfig: RemoteManagerConfig = {
+                                    appName:
+                                        this.remoteConfig.appName ||
+                                        this.name,
+                                    ...this.remoteConfig,
+                                };
+                                this.remote = new RemoteManager(rmConfig);
+                                setRemoteManager(this.remote);
+                                await this.remote.start();
+
+                                for (const service of services) {
+                                    try {
+                                        registerRemoteHandlers(service);
+                                    } catch (error) {
+                                        logger.warn(
+                                            `Failed to register remote handlers for service ${service.constructor.name}`
+                                        );
+                                        logger.warn(error);
+                                    }
+                                }
+                                logger.info(
+                                    `RemoteManager initialized for app "${rmConfig.appName}"`
+                                );
+                            } catch (error) {
+                                logger.error(
+                                    "Failed to start RemoteManager:"
+                                );
+                                logger.error(error);
+                            }
+                        }
+
                         // Collect REST endpoints from all services
                         for (const service of services) {
                             const endpoints = (service.constructor as any)
@@ -360,8 +449,21 @@ export default class App {
                             ApplicationPhase.APPLICATION_READY
                         );
                     } catch (error) {
-                        logger.error("Error during SYSTEM_READY phase:");
-                        logger.error(error);
+                        // SYSTEM_READY failures must not be swallowed silently.
+                        // Without this, the app stays forever in SYSTEM_READY
+                        // (isReady=false, /health/ready → 503 forever) and k8s
+                        // rollout hangs with no observable cause. Surface the
+                        // failure so the readiness probe reports it and the
+                        // orchestrator can restart.
+                        this.isReady = false;
+                        logger.fatal({ scope: 'app', component: 'App', err: error }, 'Fatal error during SYSTEM_READY phase — marking app unready');
+                        // In production, exit so k8s can restart the pod.
+                        // In tests, rethrow so the test sees the failure.
+                        if (process.env.NODE_ENV === 'test') {
+                            throw error;
+                        }
+                        // Give the logger a chance to flush, then exit.
+                        setTimeout(() => process.exit(1), 100).unref?.();
                     }
                     break;
                 }
@@ -372,7 +474,8 @@ export default class App {
                     break;
                 }
             }
-        });
+        };
+        ApplicationLifecycle.addPhaseListener(this.phaseListener);
 
         if (
             ApplicationLifecycle.getCurrentPhase() ===
@@ -391,17 +494,31 @@ export default class App {
         }
     }
 
-    waitForAppReady(): Promise<void> {
-        return new Promise((resolve) => {
-            const interval = setInterval(() => {
-                if (
-                    ApplicationLifecycle.getCurrentPhase() >=
-                    ApplicationPhase.APPLICATION_READY
-                ) {
-                    clearInterval(interval);
+    /**
+     * Resolve once the application has reached APPLICATION_READY. Previously
+     * polled every 100ms with no exit condition — a boot failure would keep
+     * the interval timer alive forever (H-MEM-1). Now attaches a one-shot
+     * phase listener and self-cleans on first match. Bounded by `timeoutMs`
+     * so callers cannot hang indefinitely; default matches waitForPhase.
+     */
+    waitForAppReady(timeoutMs = 60_000): Promise<void> {
+        if (ApplicationLifecycle.getCurrentPhase() >= ApplicationPhase.APPLICATION_READY) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                ApplicationLifecycle.removePhaseListener(onPhase);
+                reject(new Error(`waitForAppReady timed out after ${timeoutMs}ms; current phase=${ApplicationLifecycle.getCurrentPhase()}`));
+            }, timeoutMs);
+            timer.unref?.();
+            const onPhase = (event: PhaseChangeEvent) => {
+                if (event.detail === ApplicationPhase.APPLICATION_READY) {
+                    clearTimeout(timer);
+                    ApplicationLifecycle.removePhaseListener(onPhase);
                     resolve();
                 }
-            }, 100);
+            };
+            ApplicationLifecycle.addPhaseListener(onPhase);
         });
     }
 
@@ -443,8 +560,12 @@ export default class App {
 
         const configOrigin = this.config.cors.origin;
 
-        // Wildcard allows all
-        if (configOrigin === '*' || configOrigin === undefined) {
+        // origin is required by setCors; undefined here would indicate a
+        // programming error. Treat as deny rather than silent wildcard.
+        if (configOrigin === undefined) return null;
+
+        // Explicit wildcard allows all
+        if (configOrigin === '*') {
             // If credentials enabled, cannot use wildcard - return actual origin
             return this.config.cors.credentials ? requestOrigin : '*';
         }
@@ -476,12 +597,16 @@ export default class App {
         // If origin not allowed, return empty (no CORS headers)
         if (requestOrigin && !allowedOrigin) return {};
 
+        // No allowedOrigin means request carried no Origin header. Skip
+        // Access-Control-Allow-Origin rather than falling back to '*'.
         const headers: Record<string, string> = {
-            'Access-Control-Allow-Origin': allowedOrigin || '*',
             'Access-Control-Allow-Methods': this.config.cors.methods?.join(', ') || 'GET, POST, PUT, DELETE, OPTIONS',
             'Access-Control-Allow-Headers': this.config.cors.allowedHeaders?.join(', ') || 'Content-Type, Authorization',
             'Vary': 'Origin',
         };
+        if (allowedOrigin) {
+            headers['Access-Control-Allow-Origin'] = allowedOrigin;
+        }
 
         if (this.config.cors.credentials) {
             headers['Access-Control-Allow-Credentials'] = 'true';
@@ -498,6 +623,27 @@ export default class App {
         return headers;
     }
 
+    /**
+     * Combine multiple AbortSignals into one that aborts when any input
+     * aborts. Uses `AbortSignal.any` when available (Node 20+/current Bun),
+     * falls back to a manual combiner for older runtimes.
+     */
+    private combineSignals(signals: AbortSignal[]): AbortSignal {
+        const anyFn = (AbortSignal as any).any;
+        if (typeof anyFn === 'function') {
+            return anyFn.call(AbortSignal, signals);
+        }
+        const controller = new AbortController();
+        for (const s of signals) {
+            if (s.aborted) {
+                controller.abort((s as any).reason);
+                return controller.signal;
+            }
+            s.addEventListener('abort', () => controller.abort((s as any).reason), { once: true });
+        }
+        return controller.signal;
+    }
+
     private addCorsHeaders(response: Response, req?: Request): Response {
         const corsHeaders = this.getCorsHeaders(req);
         if (Object.keys(corsHeaders).length === 0) return response;
@@ -527,18 +673,28 @@ export default class App {
             });
         }
 
-        // Add request timeout
+        // Request timeout — combine the framework wall-clock with the client's
+        // abort signal. The combined signal is attached to a cloned request
+        // that is passed to Yoga / REST handlers so downstream work (DB
+        // queries, resolvers) actually gets cancelled on timeout or client
+        // disconnect. Previously the signal was created but never propagated,
+        // so the timer only logged a warning while the request continued
+        // consuming resources (C05).
         const controller = new AbortController();
         const timeoutId = setTimeout(() => {
-            controller.abort();
+            controller.abort(new Error(`Request timeout after 30000ms: ${method} ${url.pathname}`));
             logger.warn(`Request timeout: ${method} ${url.pathname}`);
-        }, 30000); // 30 second timeout
+        }, 30000);
+        const combinedSignal = this.combineSignals([req.signal, controller.signal]);
+        // Rebind the request with the combined signal so handlers (Yoga, REST)
+        // see it via req.signal and can propagate cancellation.
+        req = new Request(req, { signal: combinedSignal });
 
         try {
             // Health check endpoint
             if (url.pathname === "/health") {
-                clearTimeout(timeoutId);
                 const health = await deepHealthCheck();
+                clearTimeout(timeoutId);
                 return this.addCorsHeaders(new Response(
                     JSON.stringify(health.result),
                     {
@@ -550,8 +706,8 @@ export default class App {
 
             // Metrics endpoint
             if (url.pathname === "/metrics") {
-                clearTimeout(timeoutId);
                 const metrics = await this.collectMetrics();
+                clearTimeout(timeoutId);
                 return this.addCorsHeaders(new Response(
                     JSON.stringify(metrics),
                     {
@@ -561,10 +717,36 @@ export default class App {
                 ), req);
             }
 
+            // Remote health check
+            if (url.pathname === "/health/remote") {
+                if (!this.remote) {
+                    clearTimeout(timeoutId);
+                    return this.addCorsHeaders(new Response(
+                        JSON.stringify({
+                            healthy: false,
+                            error: "Remote subsystem not enabled",
+                        }),
+                        {
+                            status: 503,
+                            headers: { "Content-Type": "application/json" },
+                        }
+                    ), req);
+                }
+                const health = await this.remote.health();
+                clearTimeout(timeoutId);
+                return this.addCorsHeaders(new Response(
+                    JSON.stringify(health),
+                    {
+                        status: health.healthy ? 200 : 503,
+                        headers: { "Content-Type": "application/json" },
+                    }
+                ), req);
+            }
+
             // Readiness probe
             if (url.pathname === "/health/ready") {
-                clearTimeout(timeoutId);
                 const ready = await readinessCheck(this.isReady, this.isShuttingDown);
+                clearTimeout(timeoutId);
                 return this.addCorsHeaders(new Response(
                     JSON.stringify(ready.result),
                     {
@@ -911,10 +1093,27 @@ export default class App {
         this.name = name;
     }
 
+    public getName(): string {
+        return this.name;
+    }
+
     public setVersion(version: string) {
         this.version = version;
     }
 
+    /**
+     * Enable remote cross-app communication over Redis Streams.
+     * Must be called before `init()` (initialization happens in SYSTEM_READY).
+     * `appName` defaults to the app name.
+     */
+    public enableRemote(config: Partial<RemoteManagerConfig> = {}) {
+        this.remoteConfig = config;
+    }
+
+    public getRemote(): RemoteManager | null {
+        return this.remote;
+    }
+
     public subscribeAppReady(callback: () => void) {
         this.appReadyCallbacks.push(callback);
     }
@@ -935,6 +1134,34 @@ export default class App {
         this.graphqlMaxDepth = depth;
     }
 
+    /**
+     * Set the maximum GraphQL query complexity. 0 disables.
+     * Complexity = sum of per-field costs, multiplied by `first`/`limit`/`take`
+     * arguments when present on each field.
+     */
+    public setGraphQLMaxComplexity(complexity: number) {
+        this.graphqlMaxComplexity = complexity;
+    }
+
+    /**
+     * Supply a cache configuration that will be merged with `defaultCacheConfig`
+     * and passed to `CacheManager.initialize()` during `init()`. Must be called
+     * before `init()`.
+     */
+    public setCacheConfig(config: Partial<CacheConfig>) {
+        this.cacheConfig = config;
+    }
+
+    /**
+     * Disable the auto-applied RequestContext plugin. Only do this if your
+     * app does not use `@BelongsTo` / `@HasMany` relations OR you are
+     * supplying your own DataLoader plugin. Without it, nested relation
+     * resolvers issue one DB query per row (N+1).
+     */
+    public disableRequestContextPlugin() {
+        this.requestContextPluginEnabled = false;
+    }
+
     /**
      * Set the grace period for draining connections during shutdown (ms).
      */
@@ -1014,7 +1241,9 @@ export default class App {
         try {
             const { CacheManager } = await import('./cache/CacheManager');
             cacheStats = await CacheManager.getInstance().getStats();
-        } catch {}
+        } catch (err) {
+            logger.warn({ err }, 'metrics: cache stats unavailable');
+        }
 
         return {
             timestamp: new Date().toISOString(),
@@ -1023,6 +1252,7 @@ export default class App {
             cache: cacheStats,
             scheduler: SchedulerManager.getInstance().getMetrics(),
             preparedStatements: preparedStatementCache.getStats(),
+            remote: this.remote ? this.remote.getMetrics() : null,
         };
     }
 
@@ -1066,84 +1296,178 @@ export default class App {
             )}`
         );
 
-        // Register signal handlers for graceful shutdown
-        process.on('SIGTERM', async () => {
-            logger.info({ scope: 'app', component: 'App', msg: 'Received SIGTERM' });
-            await this.shutdown();
-            process.exit(0);
-        });
+        // Signal handlers now registered in init() via registerProcessHandlers()
+        // so they cover the boot sequence (before start() runs).
+
+        this.isReady = true;
+        this.appReadyCallbacks.forEach((cb) => cb());
+    }
 
-        process.on('SIGINT', async () => {
+    /**
+     * Register process-level signal and error handlers. Called at the top of
+     * `init()` so that failures during boot (DB prep, component registration,
+     * schema build) are logged and don't silently crash the runtime.
+     *
+     * Uses `process.once` for signals so a double SIGTERM can't fire two
+     * concurrent shutdown paths racing each other to `process.exit`. Also
+     * idempotent — safe to call multiple times (e.g. in tests).
+     */
+    private registerProcessHandlers(): void {
+        if (this.processHandlersRegistered) return;
+
+        // Use arrow-bound handlers so `once` works cleanly.
+        this.sigTermHandler = () => {
+            logger.info({ scope: 'app', component: 'App', msg: 'Received SIGTERM' });
+            this.shutdown().finally(() => process.exit(0));
+        };
+        this.sigIntHandler = () => {
             logger.info({ scope: 'app', component: 'App', msg: 'Received SIGINT' });
-            await this.shutdown();
-            process.exit(0);
-        });
+            this.shutdown().finally(() => process.exit(0));
+        };
+        process.once('SIGTERM', this.sigTermHandler);
+        process.once('SIGINT', this.sigIntHandler);
 
-        // Global error handlers to prevent silent crashes
-        process.on('unhandledRejection', (reason, promise) => {
+        // Global error handlers to prevent silent crashes during init AND runtime.
+        this.unhandledRejectionHandler = (reason, promise) => {
             logger.error({ scope: 'app', component: 'App', reason, msg: 'Unhandled promise rejection' });
-        });
-
-        process.on('uncaughtException', (error) => {
-            logger.fatal({ scope: 'app', component: 'App', error, msg: 'Uncaught exception — shutting down' });
+        };
+        this.uncaughtExceptionHandler = (error) => {
+            logger.fatal({ scope: 'app', component: 'App', err: error, msg: 'Uncaught exception — shutting down' });
             this.shutdown().finally(() => process.exit(1));
-        });
+        };
+        process.on('unhandledRejection', this.unhandledRejectionHandler);
+        process.on('uncaughtException', this.uncaughtExceptionHandler);
 
-        this.isReady = true;
-        this.appReadyCallbacks.forEach((cb) => cb());
+        this.processHandlersRegistered = true;
+    }
+
+    private unregisterProcessHandlers(): void {
+        if (!this.processHandlersRegistered) return;
+        if (this.sigTermHandler) process.removeListener('SIGTERM', this.sigTermHandler);
+        if (this.sigIntHandler) process.removeListener('SIGINT', this.sigIntHandler);
+        if (this.unhandledRejectionHandler) process.removeListener('unhandledRejection', this.unhandledRejectionHandler);
+        if (this.uncaughtExceptionHandler) process.removeListener('uncaughtException', this.uncaughtExceptionHandler);
+        this.sigTermHandler = null;
+        this.sigIntHandler = null;
+        this.unhandledRejectionHandler = null;
+        this.uncaughtExceptionHandler = null;
+        this.processHandlersRegistered = false;
     }
 
     /**
-     * Gracefully shutdown the application
+     * Gracefully shutdown the application.
+     *
+     * Ordered drain: HTTP → scheduler → remote → cache → database. Each step
+     * awaits completion before the next begins so in-flight work always sees
+     * its dependencies still available. Total budget bounded by
+     * `shutdownGracePeriod`; per-step budgets fall back to reasonable defaults.
      */
     async shutdown(): Promise<void> {
         if (this.isShuttingDown) return;
         this.isShuttingDown = true;
         this.isReady = false;
 
-        logger.info({ scope: 'app', component: 'App', msg: 'Shutting down application' });
+        const shutdownStart = Date.now();
+        logger.info({ scope: 'app', component: 'App', msg: 'Shutting down application', gracePeriodMs: this.shutdownGracePeriod });
+
+        const budgetRemaining = () => Math.max(500, this.shutdownGracePeriod - (Date.now() - shutdownStart));
 
-        // Stop HTTP server — drain then force-close after grace period
+        // 1. Stop HTTP server: stop accepting new connections, wait for in-flight
+        //    requests to finish. Bun's server.stop(false) initiates graceful
+        //    drain but does not return a promise — we poll the server's
+        //    pendingRequests count, then force-close on deadline.
         if (this.server) {
             try {
-                logger.info({ scope: 'app', component: 'App', msg: 'Draining connections' });
+                logger.info({ scope: 'app', component: 'App', msg: 'Draining HTTP connections' });
                 this.server.stop(false);
-                const forceTimer = setTimeout(() => {
-                    logger.warn({ scope: 'app', component: 'App', msg: 'Grace period expired, forcing connection close' });
-                    try { this.server?.stop(true); } catch {}
-                }, this.shutdownGracePeriod);
-                forceTimer.unref?.();
+                await this.waitForHttpDrain(budgetRemaining());
+                try { this.server.stop(true); } catch {}
                 logger.info({ scope: 'app', component: 'App', msg: 'HTTP server stopped' });
             } catch (error) {
-                logger.warn({ scope: 'app', component: 'App', msg: 'HTTP server stop error', error });
+                logger.warn({ scope: 'app', component: 'App', msg: 'HTTP server stop error', err: error });
             }
         }
 
-        // Stop scheduler
+        // 2. Stop scheduler (awaits in-flight tasks internally, see C14).
         try {
-            await SchedulerManager.getInstance().stop();
+            await SchedulerManager.getInstance().stop(Math.min(budgetRemaining(), 15_000));
             logger.info({ scope: 'app', component: 'App', msg: 'Scheduler stopped' });
         } catch (error) {
-            logger.warn({ scope: 'app', component: 'App', msg: 'Scheduler stop error', error });
+            logger.warn({ scope: 'app', component: 'App', msg: 'Scheduler stop error', err: error });
+        }
+
+        // 3. Shutdown RemoteManager (after scheduler, before cache — DB still available).
+        if (this.remote) {
+            try {
+                await this.remote.shutdown();
+                setRemoteManager(null);
+                this.remote = null;
+                logger.info({ scope: 'app', component: 'App', msg: 'RemoteManager shutdown' });
+            } catch (error) {
+                logger.warn({ scope: 'app', component: 'App', msg: 'RemoteManager shutdown error', err: error });
+            }
         }
 
-        // Shutdown cache
+        // 4. Drain any fire-and-forget cache ops triggered by entity.set /
+        //    entity.remove before we disconnect the cache (H-CACHE-1).
+        try {
+            const { Entity } = await import('./Entity');
+            await Entity.drainPendingCacheOps(Math.min(budgetRemaining(), 5_000));
+        } catch (error) {
+            logger.warn({ scope: 'cache', component: 'App', msg: 'Entity cache op drain error', err: error });
+        }
+
+        // 5. Shutdown cache (flush pending writes, unsubscribe pub/sub, disconnect).
         try {
             const { CacheManager } = await import('./cache/CacheManager');
             await CacheManager.getInstance().shutdown();
             logger.info({ scope: 'cache', component: 'App', msg: 'Cache shutdown completed' });
         } catch (error) {
-            logger.warn({ scope: 'cache', component: 'App', msg: 'Cache shutdown error', error });
+            logger.warn({ scope: 'cache', component: 'App', msg: 'Cache shutdown error', err: error });
         }
 
-        // Close database pool (last step)
+        // 5. Close database pool (last — after all consumers done).
         try {
             db.close();
             logger.info({ scope: 'app', component: 'App', msg: 'Database pool closed' });
         } catch (error) {
-            logger.warn({ scope: 'app', component: 'App', msg: 'Database pool close error', error });
+            logger.warn({ scope: 'app', component: 'App', msg: 'Database pool close error', err: error });
         }
 
-        logger.info({ scope: 'app', component: 'App', msg: 'Application shutdown completed' });
+        // 6. Dispose lifecycle listeners so a subsequent init() (tests) doesn't
+        //    stack handlers on the singleton.
+        try {
+            if (this.phaseListener) {
+                ApplicationLifecycle.removePhaseListener(this.phaseListener);
+                this.phaseListener = null;
+            }
+            SchedulerManager.getInstance().disposeLifecycleIntegration();
+        } catch { /* ignore */ }
+
+        // 7. Unregister process handlers (signals + error handlers) last so
+        //    shutdown errors still surface via them above.
+        this.unregisterProcessHandlers();
+
+        logger.info({ scope: 'app', component: 'App', msg: 'Application shutdown completed', durationMs: Date.now() - shutdownStart });
+    }
+
+    /**
+     * Wait for pending HTTP requests to drain, bounded by `timeoutMs`.
+     * Bun's `Server` exposes `pendingRequests` for this poll. If the field is
+     * unavailable (older Bun), fall back to a fixed sleep.
+     */
+    private async waitForHttpDrain(timeoutMs: number): Promise<void> {
+        if (!this.server) return;
+        const deadline = Date.now() + timeoutMs;
+        // Poll pending request count. Bun exposes this on the Server object.
+        while (Date.now() < deadline) {
+            const pending = (this.server as any).pendingRequests ?? 0;
+            if (pending === 0) return;
+            await new Promise((r) => setTimeout(r, 50));
+        }
+        const leftover = (this.server as any).pendingRequests ?? -1;
+        if (leftover > 0) {
+            logger.warn({ scope: 'app', component: 'App', msg: 'HTTP drain timeout, pending requests remaining', pendingRequests: leftover });
+        }
     }
 }