@zintrust/core 1.5.4 → 1.5.5

package/src/boot/registry/runtime.js

@@ -11,7 +11,7 @@ import { Logger } from '../../config/logger.js';
 import notificationConfig from '../../config/notification.js';
 import { StartupConfigValidator } from '../../config/StartupConfigValidator.js';
 import { ErrorFactory } from '../../exceptions/ZintrustError.js';
-import { isNonEmptyString } from '../../helper/index.js';
+import { isNonEmptyString, ShutdownTrace } from '../../helper/index.js';
 import { existsSync } from '../../node-singletons/fs.js';
 import * as path from '../../node-singletons/path.js';
 import { pathToFileURL } from '../../node-singletons/url.js';
@@ -23,6 +23,7 @@ import { SocketFeature } from '../../sockets/SocketRuntime.js';
 import { SocketRuntimeRegistry } from '../../sockets/SocketRuntimeRegistry.js';
 import { registerBroadcastersFromRuntimeConfig } from '../../tools/broadcast/BroadcastRuntimeRegistration.js';
 import { registerNotificationChannelsFromRuntimeConfig } from '../../tools/notification/NotificationRuntimeRegistration.js';
+import { QueueReliabilityOrchestrator } from '../../tools/queue/QueueReliabilityOrchestrator.js';
 import { registerQueuesFromRuntimeConfig } from '../../tools/queue/QueueRuntimeRegistration.js';
 import { registerDisksFromRuntimeConfig } from '../../tools/storage/StorageRuntimeRegistration.js';
 const importFromExistingCandidates = async (moduleCandidates) => {
@@ -332,6 +333,10 @@ const initializeQueueMonitor = async (router) => {
         knownQueues: resolveKnownQueues,
         redis: redisConfig,
     });
+    runtimeQueueMonitor = monitor;
+    ShutdownTrace.logHandles('runtime.queue-monitor.created', {
+        basePath: monitorConfig.basePath ?? '',
+    });
     try {
         monitor.registerRoutes(router);
     }
@@ -341,6 +346,7 @@ const initializeQueueMonitor = async (router) => {
     Logger.info(`Queue Monitor routes registered at http://127.0.0.1:${appConfig.port}${monitorConfig.basePath ?? ''}`);
     Logger.info(`Queue Monitor enqueue endpoint at http://127.0.0.1:${appConfig.port}/test/enqueue`);
 };
+let runtimeQueueMonitor = null;
 const initializeWorkers = async (router) => {
     const workers = await loadWorkersModule({ allowWhenDisabled: true });
     if (workers?.WorkerInit !== undefined && typeof workers.registerWorkerRoutes === 'function') {
@@ -528,7 +534,12 @@ export const createLifecycle = (params) => {
         initializeSockets(params.router);
         await initializeSystemTrace(params.router);
         if (Cloudflare.getWorkersEnv() === null && appConfig.dockerWorker === false) {
-            await initializeWorkers(params.router);
+            if (appConfig.worker === true) {
+                await initializeWorkers(params.router);
+            }
+            else {
+                Logger.info('Skipping worker route registration (WORKER_ENABLED=false).');
+            }
             await initializeQueueMonitor(params.router);
             if (appConfig.worker === true) {
                 await initializeQueueHttpGateway(params.router);
@@ -548,11 +559,34 @@ export const createLifecycle = (params) => {
     };
     const shutdown = async () => {
         Logger.info('🛑 Shutting down application...');
+        ShutdownTrace.logHandles('runtime.lifecycle.shutdown.start');
+        QueueReliabilityOrchestrator.stop();
+        ShutdownTrace.logHandles('runtime.lifecycle.shutdown.after-queue-reliability-stop');
+        if (runtimeQueueMonitor !== null && typeof runtimeQueueMonitor.close === 'function') {
+            try {
+                ShutdownTrace.log('runtime.lifecycle.shutdown.queue-monitor-close.start');
+                await runtimeQueueMonitor.close();
+                ShutdownTrace.logHandles('runtime.lifecycle.shutdown.queue-monitor-close.complete');
+            }
+            catch (error) {
+                Logger.warn('Queue Monitor shutdown failed', error);
+                ShutdownTrace.logHandles('runtime.lifecycle.shutdown.queue-monitor-close.failed', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            finally {
+                runtimeQueueMonitor = null;
+            }
+        }
         try {
             await params.shutdownManager.run();
+            ShutdownTrace.logHandles('runtime.lifecycle.shutdown.after-hooks');
         }
         catch (error) {
             Logger.error('Shutdown hook failed:', error);
+            ShutdownTrace.logHandles('runtime.lifecycle.shutdown.hooks-failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
         }
         // Ensure FileLogWriter.flush is attempted even if dynamic registration failed.
         try {
@@ -563,6 +597,7 @@ export const createLifecycle = (params) => {
             /* best-effort */
         }
         params.setBooted(false);
+        ShutdownTrace.logHandles('runtime.lifecycle.shutdown.complete');
     };
     return { boot, shutdown };
 };

package/src/boot/registry/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../../src/boot/registry/worker.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGvD;;GAEG;AACH,eAAO,MAAM,0BAA0B,GACrC,iBAAiB,gBAAgB,KAChC,OAAO,CAAC,IAAI,CA0Cd,CAAC"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../../src/boot/registry/worker.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGvD;;GAEG;AACH,eAAO,MAAM,0BAA0B,GACrC,iBAAiB,gBAAgB,KAChC,OAAO,CAAC,IAAI,CA2Cd,CAAC"}

package/src/boot/registry/worker.js

@@ -5,7 +5,8 @@ import { loadWorkersModule } from '../../runtime/WorkersModule.js';
  * Helper: Register Worker management system shutdown hook
  */
 export const registerWorkerShutdownHook = async (shutdownManager) => {
-    if (Env.getBool('WORKER_SHUTDOWN_ON_APP_EXIT', true) === false ||
+    if (appConfig.worker !== true ||
+        Env.getBool('WORKER_SHUTDOWN_ON_APP_EXIT', true) === false ||
         appConfig.dockerWorker === true) {
         return Promise.resolve(); // NOSONAR - Skip worker shutdown hook registration
     }
@@ -17,7 +18,7 @@ export const registerWorkerShutdownHook = async (shutdownManager) => {
             const mod = (await loadWorkersModule());
             const isShuttingDown = typeof mod.WorkerShutdown.isShuttingDown === 'function'
                 ? mod.WorkerShutdown.isShuttingDown()
-                : mod.WorkerShutdown.getShutdownState?.().isShuttingDown ?? false;
+                : (mod.WorkerShutdown.getShutdownState?.().isShuttingDown ?? false);
             const completedAt = mod.WorkerShutdown.getShutdownState?.().completedAt ?? null;
             if (isShuttingDown || completedAt !== null)
                 return;

package/src/cli/utils/spawn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../../../src/cli/utils/spawn.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AA8HD,eAAO,MAAM,SAAS;wBACM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;EA2F7D,CAAC"}
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../../../src/cli/utils/spawn.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAyYD,eAAO,MAAM,SAAS;wBACM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;EA8E7D,CAAC"}

package/src/cli/utils/spawn.js

@@ -4,6 +4,36 @@ import { spawn } from '../../node-singletons/child-process.js';
 import { existsSync } from '../../node-singletons/fs.js';
 import * as path from '../../node-singletons/path.js';
 import { fileURLToPath } from '../../node-singletons/url.js';
+const CLI_SPAWN_TRACE_ENV_KEYS = ['CLI_SPAWN_TRACE', 'ZIN_SPAWN_TRACE'];
+const getCliSpawnTracePid = () => {
+    if (typeof process === 'undefined')
+        return undefined;
+    return process.pid;
+};
+const isCliSpawnTraceEnabled = () => {
+    if (typeof process === 'undefined')
+        return false;
+    return CLI_SPAWN_TRACE_ENV_KEYS.some((key) => {
+        const raw = process.env[key];
+        if (typeof raw !== 'string')
+            return false;
+        const normalized = raw.trim().toLowerCase();
+        return (normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on');
+    });
+};
+const writeCliSpawnTrace = (label, details = {}) => {
+    if (!isCliSpawnTraceEnabled())
+        return;
+    const line = JSON.stringify({
+        trace: 'cli-spawn',
+        label,
+        pid: getCliSpawnTracePid(),
+        details,
+    });
+    if (typeof process !== 'undefined' && typeof process.stderr?.write === 'function') {
+        process.stderr.write(`${line}\n`);
+    }
+};
 const getExitCode = (exitCode, signal) => {
     if (typeof exitCode === 'number')
         return exitCode;
@@ -48,35 +78,210 @@ const buildCommandNotFoundMessage = (command) => {
 const waitForChildExit = async (child, onExit) => {
     return new Promise((resolve, reject) => {
         let settled = false;
-        const finish = (result) => {
+        let childResult = {
+            exitCode: null,
+            signal: null,
+        };
+        const finish = () => {
             if (settled)
                 return;
             settled = true;
+            writeCliSpawnTrace('spawn.wait.finish', {
+                childPid: child.pid,
+                exitCode: childResult.exitCode,
+                signal: childResult.signal,
+            });
             child.off?.('exit', onExitEvent);
             child.off?.('close', onCloseEvent);
             onExit();
-            resolve(result);
+            resolve(childResult);
         };
         const onExitEvent = (code, signal) => {
-            finish({ exitCode: code, signal });
+            writeCliSpawnTrace('spawn.child.exit', {
+                childPid: child.pid,
+                exitCode: code,
+                signal,
+            });
+            childResult = { exitCode: code, signal };
         };
         const onCloseEvent = (code, signal) => {
-            finish({ exitCode: code, signal });
+            writeCliSpawnTrace('spawn.child.close', {
+                childPid: child.pid,
+                exitCode: code,
+                signal,
+            });
+            childResult = {
+                exitCode: childResult.exitCode ?? code,
+                signal: childResult.signal ?? signal,
+            };
+            finish();
         };
         child.once('error', (error) => {
+            writeCliSpawnTrace('spawn.child.error', {
+                childPid: child.pid,
+                error: error instanceof Error ? error.message : String(error),
+            });
             reject(error);
         });
         child.once('exit', onExitEvent);
         child.once('close', onCloseEvent);
     });
 };
+const resolveSignalHandling = (input) => {
+    const forwardSignals = typeof input.forwardSignals === 'boolean' ? input.forwardSignals : !process.stdin.isTTY;
+    const ttySignalForwardDelayMs = process.stdin.isTTY === true && forwardSignals === false
+        ? Math.max(0, input.ttySignalForwardDelayMs ?? 0)
+        : 0;
+    return {
+        forwardSignals,
+        ttySignalForwardDelayMs,
+    };
+};
+const spawnChildProcess = (input) => {
+    writeCliSpawnTrace('spawn.child.start', {
+        command: input.command,
+        args: input.args,
+        cwd: input.cwd,
+        shell: input.shell,
+    });
+    const child = spawn(input.command, input.args, {
+        cwd: input.cwd,
+        env: input.env,
+        stdio: ['inherit', 'pipe', 'pipe'],
+        shell: input.shell,
+    });
+    child.stdout?.on('data', (chunk) => {
+        writeCliSpawnTrace('spawn.child.stdout.data', {
+            childPid: child.pid,
+            bytes: typeof chunk === 'string' ? Buffer.byteLength(chunk) : chunk.length,
+        });
+        process.stdout.write(chunk);
+    });
+    child.stdout?.on('end', () => {
+        writeCliSpawnTrace('spawn.child.stdout.end', {
+            childPid: child.pid,
+        });
+    });
+    child.stdout?.on('close', () => {
+        writeCliSpawnTrace('spawn.child.stdout.close', {
+            childPid: child.pid,
+        });
+    });
+    child.stderr?.on('data', (chunk) => {
+        writeCliSpawnTrace('spawn.child.stderr.data', {
+            childPid: child.pid,
+            bytes: typeof chunk === 'string' ? Buffer.byteLength(chunk) : chunk.length,
+        });
+        process.stderr.write(chunk);
+    });
+    child.stderr?.on('end', () => {
+        writeCliSpawnTrace('spawn.child.stderr.end', {
+            childPid: child.pid,
+        });
+    });
+    child.stderr?.on('close', () => {
+        writeCliSpawnTrace('spawn.child.stderr.close', {
+            childPid: child.pid,
+        });
+    });
+    writeCliSpawnTrace('spawn.child.started', {
+        childPid: child.pid,
+        command: input.command,
+    });
+    return child;
+};
+const createForwardSignal = (input) => {
+    return (signal) => {
+        writeCliSpawnTrace('spawn.signal.forward.attempt', {
+            childPid: input.child.pid,
+            signal,
+        });
+        try {
+            input.child.kill(signal);
+            writeCliSpawnTrace('spawn.signal.forward.complete', {
+                childPid: input.child.pid,
+                signal,
+            });
+        }
+        catch (error) {
+            writeCliSpawnTrace('spawn.signal.forward.failed', {
+                childPid: input.child.pid,
+                signal,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            const wrapped = ErrorFactory.createTryCatchError('Failed to forward signal to child process', error);
+            try {
+                process.stderr.write(`${String(wrapped.message)}\n`);
+            }
+            catch {
+                // ignore
+            }
+            throw wrapped;
+        }
+    };
+};
+const createSignalHandlers = (input) => {
+    const onSigint = () => {
+        writeCliSpawnTrace('spawn.signal.received', {
+            signal: 'SIGINT',
+            forwardSignals: input.forwardSignals,
+        });
+        if (input.forwardSignals) {
+            input.forwardSignal('SIGINT');
+            return;
+        }
+        input.delayedSignalForwarder.schedule('SIGINT');
+    };
+    const onSigterm = () => {
+        writeCliSpawnTrace('spawn.signal.received', {
+            signal: 'SIGTERM',
+            forwardSignals: input.forwardSignals,
+        });
+        if (input.forwardSignals) {
+            input.forwardSignal('SIGTERM');
+            return;
+        }
+        input.delayedSignalForwarder.schedule('SIGTERM');
+    };
+    return { onSigint, onSigterm };
+};
 const createDelayedSignalForwarder = (input) => {
     let delayedSignalTimer;
+    let escalationTimer;
+    const clearEscalation = () => {
+        if (escalationTimer === undefined)
+            return;
+        clearTimeout(escalationTimer);
+        escalationTimer = undefined;
+    };
     const clear = () => {
-        if (delayedSignalTimer === undefined)
+        if (delayedSignalTimer !== undefined) {
+            clearTimeout(delayedSignalTimer);
+            delayedSignalTimer = undefined;
+        }
+        clearEscalation();
+        writeCliSpawnTrace('spawn.signal.delay.clear');
+    };
+    const scheduleEscalation = (signal) => {
+        if (escalationTimer !== undefined || input.isChildClosed())
             return;
-        clearTimeout(delayedSignalTimer);
-        delayedSignalTimer = undefined;
+        const nextSignal = signal === 'SIGINT' ? 'SIGTERM' : signal;
+        const escalationDelayMs = Math.max(250, Math.min(1000, input.ttySignalForwardDelayMs));
+        escalationTimer = globalThis.setTimeout(() => {
+            escalationTimer = undefined;
+            if (input.isChildClosed())
+                return;
+            try {
+                writeCliSpawnTrace('spawn.signal.escalation.fire', {
+                    signal: nextSignal,
+                });
+                input.forwardSignal(nextSignal);
+            }
+            catch {
+                // best-effort fallback for interactive watch processes
+            }
+        }, escalationDelayMs);
+        escalationTimer.unref?.();
     };
     const schedule = (signal) => {
         if (input.ttySignalForwardDelayMs <= 0 ||
@@ -89,12 +294,20 @@ const createDelayedSignalForwarder = (input) => {
             if (input.isChildClosed())
                 return;
             try {
+                writeCliSpawnTrace('spawn.signal.delay.fire', {
+                    signal,
+                });
                 input.forwardSignal(signal);
+                scheduleEscalation(signal);
             }
             catch {
                 // best-effort fallback for interactive watch processes
             }
         }, input.ttySignalForwardDelayMs);
+        writeCliSpawnTrace('spawn.signal.delay.schedule', {
+            signal,
+            delayMs: input.ttySignalForwardDelayMs,
+        });
         delayedSignalTimer.unref?.();
     };
     return { clear, schedule };
@@ -103,64 +316,57 @@ export const SpawnUtil = Object.freeze({
     async spawnAndWait(input) {
         const cwd = input.cwd ?? process.cwd();
         const resolvedCommand = input.shell === true ? input.command : resolveLocalBin(input.command, cwd);
-        const child = spawn(resolvedCommand, input.args, {
+        const signalHandling = resolveSignalHandling(input);
+        writeCliSpawnTrace('spawn.and-wait.start', {
+            command: resolvedCommand,
+            args: input.args,
+            cwd,
+            shell: input.shell === true,
+            forwardSignals: signalHandling.forwardSignals,
+            ttySignalForwardDelayMs: signalHandling.ttySignalForwardDelayMs,
+        });
+        const child = spawnChildProcess({
+            command: resolvedCommand,
+            args: input.args,
             cwd,
             env: input.env ?? appConfig.getSafeEnv(),
-            stdio: 'inherit',
             shell: input.shell === true,
         });
         // In interactive shells, the foreground process group already receives SIGINT
         // (and often SIGTERM) so forwarding can cause duplicates. `tsx watch` is
         // especially sensitive here and can print "Previous process hasn't exited yet. Force killing...".
-        const forwardSignals = typeof input.forwardSignals === 'boolean' ? input.forwardSignals : !process.stdin.isTTY;
-        const ttySignalForwardDelayMs = process.stdin.isTTY === true && forwardSignals === false
-            ? Math.max(0, input.ttySignalForwardDelayMs ?? 0)
-            : 0;
+        const forwardSignals = signalHandling.forwardSignals;
+        const ttySignalForwardDelayMs = signalHandling.ttySignalForwardDelayMs;
         let childClosed = false;
-        const forwardSignal = (signal) => {
-            try {
-                child.kill(signal);
-            }
-            catch (error) {
-                const wrapped = ErrorFactory.createTryCatchError('Failed to forward signal to child process', error);
-                // Best-effort logging; then rethrow (tests/assertions rely on this behavior).
-                try {
-                    process.stderr.write(`${String(wrapped.message)}\n`);
-                }
-                catch {
-                    // ignore
-                }
-                throw wrapped;
-            }
-        };
+        const forwardSignal = createForwardSignal({ child });
         const delayedSignalForwarder = createDelayedSignalForwarder({
             ttySignalForwardDelayMs,
             isChildClosed: () => childClosed,
             forwardSignal,
         });
-        const onSigint = () => {
-            if (forwardSignals) {
-                forwardSignal('SIGINT');
-                return;
-            }
-            // In interactive TTY mode, let the child receive the terminal SIGINT directly first.
-            // If it is still alive after a short grace period, send one fallback signal so the
-            // watcher exits without requiring a second Ctrl+C from the user.
-            delayedSignalForwarder.schedule('SIGINT');
-        };
-        const onSigterm = () => {
-            if (forwardSignals) {
-                forwardSignal('SIGTERM');
-                return;
-            }
-            delayedSignalForwarder.schedule('SIGTERM');
-        };
+        const { onSigint, onSigterm } = createSignalHandlers({
+            forwardSignals,
+            delayedSignalForwarder,
+            forwardSignal,
+        });
         process.on('SIGINT', onSigint);
         process.on('SIGTERM', onSigterm);
+        writeCliSpawnTrace('spawn.signal.handlers.registered', {
+            childPid: child.pid,
+        });
         try {
             const result = await waitForChildExit(child, () => {
                 childClosed = true;
                 delayedSignalForwarder.clear();
+                writeCliSpawnTrace('spawn.child.mark-closed', {
+                    childPid: child.pid,
+                });
+            });
+            writeCliSpawnTrace('spawn.and-wait.result', {
+                childPid: child.pid,
+                exitCode: result.exitCode,
+                signal: result.signal,
+                normalizedExitCode: getExitCode(result.exitCode, result.signal),
             });
             return getExitCode(result.exitCode, result.signal);
         }
@@ -175,6 +381,9 @@ export const SpawnUtil = Object.freeze({
             delayedSignalForwarder.clear();
             process.off('SIGINT', onSigint);
             process.off('SIGTERM', onSigterm);
+            writeCliSpawnTrace('spawn.signal.handlers.removed', {
+                childPid: child.pid,
+            });
         }
     },
 });

package/src/helper/ShutdownTrace.d.ts

@@ -0,0 +1,9 @@
+type ShutdownTraceDetails = Record<string, unknown>;
+export declare const ShutdownTrace: Readonly<{
+    isEnabled: () => boolean;
+    log: (label: string, details?: ShutdownTraceDetails) => void;
+    logHandles: (label: string, details?: ShutdownTraceDetails) => void;
+    logBullMQWorker: (label: string, worker: unknown, details?: ShutdownTraceDetails) => void;
+}>;
+export {};
+//# sourceMappingURL=ShutdownTrace.d.ts.map

package/src/helper/ShutdownTrace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShutdownTrace.d.ts","sourceRoot":"","sources":["../../../src/helper/ShutdownTrace.ts"],"names":[],"mappings":"AAKA,KAAK,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAwMpD,eAAO,MAAM,aAAa;qBAlLJ,OAAO;iBAwFT,MAAM,YAAW,oBAAoB,KAAQ,IAAI;wBAY1C,MAAM,YAAW,oBAAoB,KAAQ,IAAI;6BA6CnE,MAAM,UACL,OAAO,YACN,oBAAoB,KAC5B,IAAI;EAmCL,CAAC"}

package/src/helper/ShutdownTrace.js

@@ -0,0 +1,165 @@
+const TRACE_ENV_KEYS = ['SHUTDOWN_TRACE', 'DEBUG_SHUTDOWN_TRACE', 'WORKER_SHUTDOWN_TRACE'];
+const MAX_HANDLE_DETAILS = 20;
+const writeLine = (line) => {
+    const nodeProcess = getNodeProcess();
+    if (nodeProcess?.stderr && typeof nodeProcess.stderr.write === 'function') {
+        nodeProcess.stderr.write(`${line}\n`);
+        return;
+    }
+    if (typeof console !== 'undefined' && typeof console.info === 'function') {
+        console.info(line);
+    }
+};
+const getNodeProcess = () => {
+    if (typeof process === 'undefined')
+        return null;
+    return process;
+};
+const isEnabled = () => {
+    const nodeProcess = getNodeProcess();
+    if (nodeProcess === null)
+        return false;
+    return TRACE_ENV_KEYS.some((key) => {
+        const raw = nodeProcess.env[key];
+        if (typeof raw !== 'string')
+            return false;
+        const normalized = raw.trim().toLowerCase();
+        return (normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on');
+    });
+};
+const getConstructorName = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return typeof value;
+    const constructorValue = value.constructor;
+    return typeof constructorValue?.name === 'string' ? constructorValue.name : 'Unknown';
+};
+const hasFunction = (value, key) => {
+    return (typeof value === 'object' &&
+        value !== null &&
+        key in value &&
+        typeof value[key] === 'function');
+};
+const getOptionalValue = (value, key) => {
+    if (typeof value !== 'object' || value === null || !(key in value))
+        return undefined;
+    return value[key];
+};
+const summarizeHandle = (handle) => {
+    const constructorName = getConstructorName(handle);
+    const summary = {
+        type: constructorName,
+    };
+    const fd = getOptionalValue(handle, 'fd');
+    if (typeof fd === 'number') {
+        summary['fd'] = fd;
+    }
+    const localPort = getOptionalValue(handle, 'localPort');
+    if (typeof localPort === 'number') {
+        summary['localPort'] = localPort;
+    }
+    const remotePort = getOptionalValue(handle, 'remotePort');
+    if (typeof remotePort === 'number') {
+        summary['remotePort'] = remotePort;
+    }
+    const repeat = getOptionalValue(handle, '_repeat');
+    if (typeof repeat === 'number') {
+        summary['repeatMs'] = repeat;
+    }
+    const destroyed = getOptionalValue(handle, 'destroyed');
+    if (typeof destroyed === 'boolean') {
+        summary['destroyed'] = destroyed;
+    }
+    if (hasFunction(handle, 'hasRef')) {
+        try {
+            summary['hasRef'] = handle.hasRef();
+        }
+        catch {
+            summary['hasRef'] = 'error';
+        }
+    }
+    return summary;
+};
+const countTypes = (items) => {
+    return items.reduce((counts, item) => {
+        const type = getConstructorName(item);
+        counts[type] = (counts[type] ?? 0) + 1;
+        return counts;
+    }, {});
+};
+const log = (label, details = {}) => {
+    if (!isEnabled())
+        return;
+    writeLine(JSON.stringify({
+        level: 'info',
+        trace: 'shutdown',
+        label,
+        details,
+    }));
+};
+const logHandles = (label, details = {}) => {
+    if (!isEnabled())
+        return;
+    const nodeProcess = getNodeProcess();
+    if (nodeProcess === null) {
+        writeLine(JSON.stringify({
+            level: 'info',
+            trace: 'shutdown',
+            label,
+            details: {
+                ...details,
+                available: false,
+                reason: 'process unavailable',
+            },
+        }));
+        return;
+    }
+    const handles = typeof nodeProcess._getActiveHandles === 'function' ? nodeProcess._getActiveHandles() : [];
+    const requests = typeof nodeProcess._getActiveRequests === 'function' ? nodeProcess._getActiveRequests() : [];
+    writeLine(JSON.stringify({
+        level: 'info',
+        trace: 'shutdown',
+        label,
+        details: {
+            ...details,
+            available: true,
+            handleCount: handles.length,
+            requestCount: requests.length,
+            handleTypes: countTypes(handles),
+            requestTypes: countTypes(requests),
+            handles: handles.slice(0, MAX_HANDLE_DETAILS).map((handle) => summarizeHandle(handle)),
+            requests: requests.slice(0, MAX_HANDLE_DETAILS).map((request) => summarizeHandle(request)),
+        },
+    }));
+};
+const logBullMQWorker = (label, worker, details = {}) => {
+    if (!isEnabled())
+        return;
+    const name = getOptionalValue(worker, 'name');
+    const opts = getOptionalValue(worker, 'opts');
+    const connection = getOptionalValue(opts, 'connection');
+    const prefix = getOptionalValue(opts, 'prefix');
+    const concurrency = getOptionalValue(opts, 'concurrency');
+    const autorun = getOptionalValue(opts, 'autorun');
+    const closing = getOptionalValue(worker, 'closing');
+    writeLine(JSON.stringify({
+        level: 'info',
+        trace: 'shutdown',
+        label,
+        details: {
+            ...details,
+            workerType: getConstructorName(worker),
+            queueName: typeof name === 'string' ? name : undefined,
+            prefix: typeof prefix === 'string' ? prefix : undefined,
+            concurrency: typeof concurrency === 'number' ? concurrency : undefined,
+            autorun: typeof autorun === 'boolean' ? autorun : undefined,
+            connectionType: getConstructorName(connection),
+            closingState: closing === undefined ? 'idle' : getConstructorName(closing),
+        },
+    }));
+};
+export const ShutdownTrace = Object.freeze({
+    isEnabled,
+    log,
+    logHandles,
+    logBullMQWorker,
+});