@digital-alchemy/core 26.2.17 → 26.5.28

package/dist/services/scheduler.service.mjs

@@ -1,11 +1,31 @@
 import { CronJob } from "cron";
 import dayjs from "dayjs";
 import { BootstrapException, sleep } from "../index.mjs";
+/**
+ * Builder-style scheduler factory injected into every service via `TServiceParams`.
+ *
+ * @remarks
+ * Returns a function that accepts a `TContext` and produces the per-caller scheduler
+ * API (`cron`, `interval`, `sliding`, `setTimeout`, `setInterval`, `sleep`).
+ * This two-level shape is deliberate: the outer factory sets up lifecycle hooks
+ * shared across all callers; the inner function binds the per-caller context so
+ * every scheduled callback is associated with the service that created it.
+ *
+ * All schedules are registered against a shared `stop` set so a single
+ * `onPreShutdown` hook can cleanly cancel every outstanding timer in one pass.
+ * Schedules only start firing after the `onReady` lifecycle event; creating a
+ * scheduler before `onReady` is safe — the job is registered but does not run
+ * until the application is ready.
+ *
+ * Remove callbacks returned from each method are dual-arity:
+ * call them directly (`remove()`) or destructure `{ remove }` — both work.
+ */
 export function Scheduler({ logger, lifecycle, internal }) {
     const { is } = internal.utils;
     const stop = new Set();
     // #MARK: lifecycle events
     lifecycle.onPreShutdown(function onPreShutdown() {
+        // skip teardown work if nothing was ever scheduled for this instance
         if (is.empty(stop)) {
             return;
         }
@@ -17,6 +37,15 @@ export function Scheduler({ logger, lifecycle, internal }) {
     });
     return (context) => {
         // #MARK: cron
+        /**
+         * Run `exec` on one or more cron schedules.
+         *
+         * @remarks
+         * Accepts a single schedule string or an array; each schedule creates an
+         * independent `CronJob`. Jobs start on `onReady` and are registered in the
+         * shared `stop` set so they are cancelled during `onPreShutdown`.
+         * Returns a combined remove callback that cancels all jobs created by this call.
+         */
         function cron({ exec, schedule: scheduleList }) {
             const stopFunctions = [];
             [scheduleList].flat().forEach(cronSchedule => {
@@ -34,9 +63,18 @@ export function Scheduler({ logger, lifecycle, internal }) {
                 stopFunctions.push(stopFunction);
                 return stopFunction;
             });
+            // wrap all individual stop functions so a single call cancels every schedule
             return internal.removeFn(() => stopFunctions.forEach(stop => stop()));
         }
         // #MARK: interval
+        /**
+         * Run `exec` repeatedly at a fixed `interval` millisecond cadence.
+         *
+         * @remarks
+         * The underlying `setInterval` does not start until `onReady`. If the
+         * application is torn down before `onReady` fires the `stopped` guard
+         * prevents the timer from being created at all.
+         */
         function interval({ exec, interval }) {
             let runningInterval;
             lifecycle.onReady(() => {
@@ -52,6 +90,28 @@ export function Scheduler({ logger, lifecycle, internal }) {
             return stopFunction;
         }
         // #MARK: sliding
+        /**
+         * Schedule an execution at a time determined dynamically by a `next` callback.
+         *
+         * @remarks
+         * Unlike cron (fixed periods) or interval (fixed gaps), sliding lets the
+         * caller compute the *exact* next run time. `reset` is a cron expression
+         * that controls how often `next` is re-evaluated; `next` returns the target
+         * `Dayjs` moment for the actual `exec` call.
+         *
+         * Decision points:
+         * - If `next()` returns falsy the window is skipped — caller can signal
+         *   "nothing to do right now" without throwing.
+         * - If the computed time is already in the past at evaluation time, the
+         *   execution is skipped. This most commonly happens on first boot when the
+         *   slot has already passed for today; treating it as a no-op avoids an
+         *   immediate double-fire.
+         * - If `waitForNext` is called while a previous timeout is still pending,
+         *   it cancels the old one and schedules fresh — ensures the schedule stays
+         *   coherent if the reset cron fires more aggressively than expected.
+         *
+         * @throws {BootstrapException} `BAD_NEXT` if `next` or `exec` is not a function.
+         */
         function sliding({ exec, reset, next }) {
             if (!is.function(next)) {
                 throw new BootstrapException(context, "BAD_NEXT", "Did not provide next function to schedule.sliding");
@@ -61,20 +121,23 @@ export function Scheduler({ logger, lifecycle, internal }) {
             }
             let timeout;
             const waitForNext = () => {
+                // a pending timeout means the reset cron fired before the scheduled exec ran;
+                // cancel and reschedule so the next time is always freshly computed
                 if (timeout) {
                     logger.warn({ context, name: sliding }, `sliding schedule retrieving next execution time before previous ran`);
                     clearTimeout(timeout);
                 }
                 let nextTime = next();
+                // next() returning falsy is the caller's way of saying "skip this window"
                 if (!nextTime) {
-                    // nothing to do?
-                    // will try again next schedule
+                    logger.trace({ context, name: sliding }, "next returned falsy, skipping window");
                     return;
                 }
                 nextTime = dayjs(nextTime);
+                // if the target time is already past at evaluation, skip to avoid an immediate
+                // double-fire; most common on first boot when the slot passed earlier today
                 if (dayjs().isAfter(nextTime)) {
-                    // probably a result of boot
-                    // ignore
+                    logger.trace({ context, name: sliding }, "next time is in the past, skipping");
                     return;
                 }
                 if (nextTime) {
@@ -98,10 +161,20 @@ export function Scheduler({ logger, lifecycle, internal }) {
                 }
             });
         }
+        /**
+         * Fire `callback` once after `target` offset elapses.
+         *
+         * @remarks
+         * Wraps the native `setTimeout` with lifecycle awareness: the timer is not
+         * armed until `onReady`, and is automatically cancelled during shutdown via
+         * the shared `stop` set. If `remove()` is called before `onReady` the
+         * `stopped` flag prevents the timer from ever being created.
+         */
         function SetTimeout(callback, target) {
             let timer;
             let stopped = false;
             lifecycle.onReady(() => {
+                // guard against the case where remove() was called before onReady fired
                 if (stopped) {
                     return;
                 }
@@ -120,10 +193,20 @@ export function Scheduler({ logger, lifecycle, internal }) {
             stop.add(remove);
             return remove;
         }
+        /**
+         * Fire `callback` repeatedly at every `target` offset interval.
+         *
+         * @remarks
+         * Lifecycle-aware wrapper around `setInterval`. Timer starts on `onReady`
+         * and is cancelled during shutdown via the shared `stop` set. If `remove()`
+         * is called before `onReady`, the `stopped` guard prevents the interval
+         * from ever starting.
+         */
         function SetInterval(callback, target) {
             let timer;
             let stopped = false;
             lifecycle.onReady(() => {
+                // guard against the case where remove() was called before onReady fired
                 if (stopped) {
                     return;
                 }

package/dist/services/scheduler.service.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"scheduler.service.mjs","sourceRoot":"","sources":["../../src/services/scheduler.service.mts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scheduler.service.mjs","sourceRoot":"","sources":["../../src/services/scheduler.service.mts"],"names":[],"mappings":"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"}

package/dist/services/wiring.service.d.mts

@@ -8,6 +8,17 @@ export interface DeclaredEnvironments {
     test: true;
     local: true;
 }
+/**
+ * Construct a fresh `LIB_BOILERPLATE` library definition.
+ *
+ * @remarks
+ * Must remain in this file. Moving it to another module causes code-init race
+ * conditions because the boilerplate services depend on types that are only
+ * resolved after the module graph is fully settled. The library is recreated
+ * on every `bootstrap()` call so tests get a clean instance.
+ *
+ * @internal
+ */
 declare function createBoilerplate(): import("../index.mts").LibraryDefinition<{
     /**
      * [AsyncLocalStorage](https://nodejs.org/api/async_context.html) hooks
@@ -105,5 +116,22 @@ declare function createBoilerplate(): import("../index.mts").LibraryDefinition<{
     NODE_ENV: StringConfig<keyof DeclaredEnvironments>;
 }>;
 export declare let LIB_BOILERPLATE: ReturnType<typeof createBoilerplate>;
+/**
+ * Define an application and return a handle that can be bootstrapped.
+ *
+ * @remarks
+ * Does not start any services. Call `.bootstrap(options)` on the returned
+ * handle to wire services and run the lifecycle. Only one bootstrap per
+ * handle is allowed; a second call throws `DOUBLE_BOOT`.
+ *
+ * The returned handle also exposes `.teardown()` for orderly shutdown —
+ * this is the same path taken by the SIGINT/SIGTERM handlers.
+ *
+ * `priorityInit` controls which services are wired first within this
+ * application; all others are wired in declaration order after them.
+ *
+ * @throws {BootstrapException} `MISSING_PRIORITY_SERVICE` if a service listed
+ *   in `priorityInit` is not present in `services`.
+ */
 export declare function CreateApplication<S extends ServiceMap, C extends OptionalModuleConfiguration>({ name, services, libraries, configuration, priorityInit, ...extra }: ApplicationConfigurationOptions<S, C>): ApplicationDefinition<S, C>;
 export {};

package/dist/services/wiring.service.mjs

@@ -3,6 +3,8 @@ import { ACTIVE_SLEEPS, BootstrapException, buildSortOrder, COERCE_CONTEXT, Crea
 import { ALS } from "./als.service.mjs";
 import { Configuration, INITIALIZE, INJECTED_DEFINITIONS, LOAD_PROJECT, } from "./configuration.service.mjs";
 import { InternalDefinition } from "./internal.service.mjs";
+// direct import of `is` from its source file to avoid a circular dependency:
+// going through ../index.mts would force wiring.mts to resolve before is.service.mts
 import { is } from "./is.service.mjs";
 import { CreateLifecycle } from "./lifecycle.service.mjs";
 import { Logger } from "./logger.service.mjs";
@@ -11,6 +13,17 @@ const EXIT_ERROR = 1;
 const SIGINT = 130;
 const SIGTERM = 143;
 // #MARK: CreateBoilerplate
+/**
+ * Construct a fresh `LIB_BOILERPLATE` library definition.
+ *
+ * @remarks
+ * Must remain in this file. Moving it to another module causes code-init race
+ * conditions because the boilerplate services depend on types that are only
+ * resolved after the module graph is fully settled. The library is recreated
+ * on every `bootstrap()` call so tests get a clean instance.
+ *
+ * @internal
+ */
 function createBoilerplate() {
     // ! DO NOT MOVE TO ANOTHER FILE !
     // While it SEEMS LIKE this can be safely moved, it causes code init race conditions.
@@ -128,11 +141,19 @@ function createBoilerplate() {
         },
     });
 }
-// (re)defined at bootstrap
-// unclear if this variable even serves a purpose beyond types
+// (re)defined at bootstrap; exported so downstream code can reference its type
 export let LIB_BOILERPLATE;
 const RUNNING_APPLICATIONS = new Map();
 // #MARK: QuickShutdown
+/**
+ * Trigger teardown on every currently-running application.
+ *
+ * @remarks
+ * Called by the SIGINT/SIGTERM process event handlers so all applications
+ * go through their full shutdown lifecycle before the process exits.
+ *
+ * @internal
+ */
 async function quickShutdown(reason) {
     await each([...RUNNING_APPLICATIONS.values()], async (application) => {
         application.logger.warn({ reason }, `starting shutdown`);
@@ -140,6 +161,9 @@ async function quickShutdown(reason) {
     });
 }
 // #MARK: processEvents
+// SIGTERM is sent by orchestrators (e.g. Docker, Kubernetes) for graceful shutdown;
+// SIGINT is sent by the terminal (Ctrl-C); both should drain the lifecycle cleanly
+// before exiting rather than killing the process immediately
 const processEvents = new Map([
     [
         "SIGTERM",
@@ -161,8 +185,27 @@ const processEvents = new Map([
 const DECIMALS = 2;
 const BOILERPLATE = (internal) => internal.boot.loadedModules.get("boilerplate");
 // #MARK: CreateApplication
+/**
+ * Define an application and return a handle that can be bootstrapped.
+ *
+ * @remarks
+ * Does not start any services. Call `.bootstrap(options)` on the returned
+ * handle to wire services and run the lifecycle. Only one bootstrap per
+ * handle is allowed; a second call throws `DOUBLE_BOOT`.
+ *
+ * The returned handle also exposes `.teardown()` for orderly shutdown —
+ * this is the same path taken by the SIGINT/SIGTERM handlers.
+ *
+ * `priorityInit` controls which services are wired first within this
+ * application; all others are wired in declaration order after them.
+ *
+ * @throws {BootstrapException} `MISSING_PRIORITY_SERVICE` if a service listed
+ *   in `priorityInit` is not present in `services`.
+ */
 export function CreateApplication({ name, services = {}, libraries = [], configuration = {}, priorityInit = [], ...extra }) {
     let internal;
+    // validate priority list up front so misconfiguration fails loudly at definition
+    // time rather than silently during bootstrap when the service is just missing
     if (!is.empty(priorityInit)) {
         priorityInit.forEach(name => {
             if (!is.function(services[name])) {
@@ -180,6 +223,8 @@ export function CreateApplication({ name, services = {}, libraries = [], configu
                 serviceApis[service] = await wireService(name, service, services[service], internal.boot.lifecycle.events, internal);
             });
             const append = internal.boot.options?.appendService;
+            // appendService allows tests (and advanced users) to inject extra services
+            // without modifying the application definition
             if (!is.empty(append)) {
                 await eachSeries(Object.keys(append), async (service) => {
                     await wireService(name, service, append[service], internal.boot.lifecycle.events, internal);
@@ -189,6 +234,8 @@ export function CreateApplication({ name, services = {}, libraries = [], configu
         },
         booted: false,
         bootstrap: async (options) => {
+            // guard against accidentally bootstrapping the same application twice;
+            // this is always a programming error — each app should have a single entry point
             if (application.booted) {
                 throw new BootstrapException(WIRING_CONTEXT, "DOUBLE_BOOT", "Application is already booted! Cannot bootstrap again");
             }
@@ -208,6 +255,8 @@ export function CreateApplication({ name, services = {}, libraries = [], configu
         services,
         async teardown() {
             if (!application.booted) {
+                // remove signal handlers even for un-booted teardown so they don't
+                // accumulate across test re-runs
                 processEvents.forEach((callback, event) => process.removeListener(event, callback));
                 return;
             }
@@ -221,12 +270,29 @@ export function CreateApplication({ name, services = {}, libraries = [], configu
     return application;
 }
 // #MARK: WireService
+/**
+ * Instantiate a single service function and register it in the module registry.
+ *
+ * @remarks
+ * Builds the full `TServiceParams` injection object from the currently loaded
+ * modules and calls the service factory. The returned value is stored in
+ * `internal.boot.loadedModules` so subsequent services can reference it.
+ *
+ * Construction time is recorded for bootstrap stats (`showExtraBootStats`).
+ *
+ * If the factory throws, the error is treated as fatal — the process exits
+ * with code 1 because a failed constructor leaves the DI graph in a
+ * partially-initialized state with no safe recovery path.
+ *
+ * @internal
+ */
 async function wireService(project, service, definition, lifecycle, internal) {
     const mappings = internal.boot.moduleMappings.get(project) ?? {};
     mappings[service] = definition;
     internal.boot.moduleMappings.set(project, mappings);
     const context = COERCE_CONTEXT(`${project}:${service}`);
-    // logger gets defined first, so this really is only for the start of the start of bootstrapping
+    // logger is not yet available at the very start of bootstrap; only undefined briefly
+    // during boilerplate wiring before the logger service itself is initialized
     const boilerplate = BOILERPLATE(internal);
     const logger = boilerplate?.logger?.context(context);
     const loaded = internal.boot.loadedModules.get(project) ?? {};
@@ -234,6 +300,8 @@ async function wireService(project, service, definition, lifecycle, internal) {
     try {
         logger?.trace({ name: wireService }, `initializing`);
         const serviceStart = performance.now();
+        // snapshot all currently-loaded modules so each service sees siblings
+        // that were wired before it, but not ones that come after (no forward refs)
         const inject = Object.fromEntries([...internal.boot.loadedModules.keys()].map(project => [
             project,
             internal.boot.loadedModules.get(project),
@@ -248,8 +316,11 @@ async function wireService(project, service, definition, lifecycle, internal) {
             lifecycle,
             logger,
             params: undefined,
+            // scheduler is a builder; call it with context so the returned API
+            // tags every scheduled callback with this service's context string
             scheduler: boilerplate?.scheduler?.(context),
         };
+        // params.params is a self-reference so callers can spread the whole bundle
         serviceParams.params = serviceParams;
         loaded[service] = (await definition(serviceParams));
         const serviceDuration = performance.now() - serviceStart;
@@ -261,32 +332,81 @@ async function wireService(project, service, definition, lifecycle, internal) {
         return loaded[service];
     }
     catch (error) {
-        // Init errors at this level are considered blocking / fatal
+        // Default (app) mode: a constructor throw means the service graph is partially initialized
+        // and cannot recover, so fatalLog + exit is correct. But test/library consumers set
+        // customLogger to claim output and the rejection chain — the FATAL write leaks past their
+        // no-op logger and process.exit mangles the original error class through the test runner's
+        // interceptor. Short-circuit to a plain re-throw; app-mode fallthrough is unchanged.
+        if (internal.boot.options?.customLogger) {
+            throw error;
+        }
+        // constructor errors are blocking — a partially-initialized service graph
+        // cannot be safely recovered, so exit immediately
         fatalLog("initialization error", error);
         process.exit(EXIT_ERROR);
     }
 }
+/**
+ * Execute the `PreInit` lifecycle stage and mark it complete.
+ * @internal
+ */
 const runPreInit = async (internal) => {
     const duration = await internal.boot.lifecycle.exec("PreInit");
     internal.boot.completedLifecycleEvents.add("PreInit");
     return duration;
 };
+/**
+ * Execute the `PostConfig` lifecycle stage and mark it complete.
+ * @internal
+ */
 const runPostConfig = async (internal) => {
     const duration = await internal.boot.lifecycle.exec("PostConfig");
     internal.boot.completedLifecycleEvents.add("PostConfig");
     return duration;
 };
+/**
+ * Execute the `Bootstrap` lifecycle stage and mark it complete.
+ * @internal
+ */
 const runBootstrap = async (internal) => {
     const duration = await internal.boot.lifecycle.exec("Bootstrap");
     internal.boot.completedLifecycleEvents.add("Bootstrap");
     return duration;
 };
+/**
+ * Execute the `Ready` lifecycle stage and mark it complete.
+ * @internal
+ */
 const runReady = async (internal) => {
     const duration = await internal.boot.lifecycle.exec("Ready");
     internal.boot.completedLifecycleEvents.add("Ready");
     return duration;
 };
 // #MARK: Bootstrap
+/**
+ * Wire all services for an application, run the full lifecycle, and return
+ * the `TServiceParams` for the bootstrap service.
+ *
+ * @remarks
+ * Sequence:
+ * 1. Initialize a fresh `InternalDefinition.boot` record.
+ * 2. Wire boilerplate (als, configuration, logger, scheduler).
+ * 3. Register SIGINT/SIGTERM process event handlers for graceful shutdown.
+ * 4. Wire declared libraries in dependency-sorted order.
+ * 5. Wire the application services (or defer to after Bootstrap if
+ *    `bootLibrariesFirst` is set).
+ * 6. Apply any inline `options.configuration` overrides.
+ * 7. Run `PreInit → Configure (loaders) → PostConfig → Bootstrap → Ready`.
+ * 8. Resolve the returned `TServiceParams` promise via a synthetic
+ *    "bootstrap" service wire call so the caller can access the wired graph.
+ *
+ * When `customLogger` is supplied (library/test mode), bootstrap failures reject
+ * the returned promise with the original error instead of calling `fatalLog` and
+ * `process.exit`. App-mode callers (no `customLogger`) get the existing
+ * fail-fast behavior.
+ *
+ * @internal
+ */
 async function bootstrap(application, options, internal) {
     const initTime = performance.now();
     internal.boot = {
@@ -306,14 +426,16 @@ async function bootstrap(application, options, internal) {
         const STATS = {};
         const CONSTRUCT = {};
         // pre-create loaded module for boilerplate, so it can be attached to `internal`
-        // this allows it to be used as part of `internal` during boilerplate construction
-        // otherwise it'd only be there for everyone else
+        // before the boilerplate services themselves are wired; without this pre-seeding
+        // the boilerplate services would not find each other in the module map
         const api = {};
         internal.boilerplate = api;
         internal.boot.loadedModules.set("boilerplate", api);
         STATS.Construct = CONSTRUCT;
         // * Recreate base eventemitter
         internal.utils.event = new EventEmitter();
+        // unlimited listeners: every service can register lifecycle hooks, and the
+        // default cap of 10 would produce spurious MaxListenersExceededWarnings
         internal.utils.event.setMaxListeners(NONE);
         // * Generate a new boilerplate module
         LIB_BOILERPLATE = createBoilerplate();
@@ -321,20 +443,23 @@ async function bootstrap(application, options, internal) {
         let start = performance.now();
         await LIB_BOILERPLATE[WIRE_PROJECT](internal, wireService);
         CONSTRUCT.boilerplate = `${(performance.now() - start).toFixed(DECIMALS)}ms`;
-        // sync properties for convenience
+        // sync convenience aliases so downstream code reaches config via either path
         internal.config = api.configuration;
         // ~ configuration
         api.configuration?.[LOAD_PROJECT](LIB_BOILERPLATE.name, LIB_BOILERPLATE.configuration);
         const logger = api.logger.context(WIRING_CONTEXT);
         application.logger = logger;
         logger.debug({ name: bootstrap }, `[boilerplate] wiring complete`);
-        // * Wire in various shutdown events
+        // register signal handlers now that the logger is available so teardown
+        // log lines are visible; handlers are removed on teardown/un-booted teardown
         processEvents.forEach((callback, event) => {
             process.on(event, callback);
             logger.trace({ event, name: bootstrap }, "register shutdown event");
         });
         // * Add in libraries
         application.libraries ??= [];
+        // appendLibrary allows replacing a library at bootstrap time, which is
+        // the primary mechanism for injecting test doubles at the library level
         if (!is.undefined(options?.appendLibrary)) {
             const list = is.array(options.appendLibrary)
                 ? options.appendLibrary
@@ -342,7 +467,7 @@ async function bootstrap(application, options, internal) {
             list.forEach(append => {
                 application.libraries.some((library, index) => {
                     if (append.name === library.name) {
-                        // remove existing
+                        // remove existing entry so the appended version takes its slot
                         logger.warn({ name: append.name }, `replacing library`);
                         application.libraries.splice(index, SINGLE);
                         return true;
@@ -354,6 +479,7 @@ async function bootstrap(application, options, internal) {
                 application.libraries.push(append);
             });
         }
+        // sort libraries so each one is wired after its declared dependencies
         const order = buildSortOrder(application, logger);
         await eachSeries(order, async (i) => {
             start = performance.now();
@@ -365,7 +491,8 @@ async function bootstrap(application, options, internal) {
         // * Finally the application
         if (options?.bootLibrariesFirst) {
             logger.debug({ name: bootstrap }, `bootLibrariesFirst`);
-            // * preload config
+            // bootLibrariesFirst: skip application wiring here and run it later,
+            // between Bootstrap and Ready, so the app sees fully-initialized library services
             api.configuration[LOAD_PROJECT](application.name, application.configuration);
         }
         else {
@@ -374,7 +501,7 @@ async function bootstrap(application, options, internal) {
             await application[WIRE_PROJECT](internal, wireService);
             CONSTRUCT[application.name] = `${(performance.now() - start).toFixed(DECIMALS)}ms`;
         }
-        // ? Configuration values provided bootstrap take priority over module level
+        // ? Configuration values provided at bootstrap take priority over module-level defaults
         if (!is.empty(options?.configuration)) {
             api.configuration.merge(options?.configuration);
         }
@@ -391,12 +518,9 @@ async function bootstrap(application, options, internal) {
         logger.debug({ name: bootstrap }, `[Bootstrap] running lifecycle callbacks`);
         STATS.Bootstrap = await runBootstrap(internal);
         if (options?.bootLibrariesFirst) {
-            // * mental note
-            // running between bootstrap & ready seems most appropriate
-            // resources are expected to *technically* be ready at this point, but not finalized
-            // reference examples:
-            // - hass: socket is open & resources are ready
-            // - fastify: bindings are available but port isn't listening
+            // wire the application between Bootstrap and Ready so library resources are
+            // fully initialized (e.g. hass socket open, fastify bindings registered)
+            // but the app itself does not start accepting work until Ready fires
             logger.debug({ name: bootstrap }, `late init application`);
             start = performance.now();
             await application[WIRE_PROJECT](internal, wireService);
@@ -421,9 +545,19 @@ async function bootstrap(application, options, internal) {
             }
             : { Total: STATS.Total, name: bootstrap }, `[%s] application bootstrapped`, application.name);
         internal.boot.phase = "running";
+        // resolve the bootstrap promise by wiring a synthetic "bootstrap" service
+        // whose params object is the fully-wired TServiceParams the caller receives
         return new Promise(done => wireService(application.name, "bootstrap", i => done(i), internal.boot.lifecycle.events, internal));
     }
     catch (error) {
+        // Default (app) mode: a lifecycle-stage throw (Bootstrap/Ready/etc.) gets a FATAL line and
+        // exits, which is correct for production. But test/library consumers set customLogger to
+        // claim output and the rejection chain — the FATAL write leaks past their no-op logger and
+        // process.exit mangles the original error class through the test runner's interceptor.
+        // Short-circuit to a plain re-throw; app-mode fallthrough is unchanged.
+        if (options?.customLogger) {
+            throw error;
+        }
         if (options?.configuration?.boilerplate?.LOG_LEVEL !== "silent") {
             fatalLog("bootstrap failed", error);
         }
@@ -431,7 +565,23 @@ async function bootstrap(application, options, internal) {
     }
 }
 // #MARK: Teardown
+/**
+ * Run shutdown lifecycle stages and clean up process-level resources.
+ *
+ * @remarks
+ * Called by `.teardown()` on the application handle and indirectly by the
+ * SIGINT/SIGTERM handlers via `quickShutdown`. Idempotent at the phase check
+ * — only executes if the application is in the `"running"` phase.
+ *
+ * Sequence: `PreShutdown → ShutdownStart → (cancel active sleeps) →
+ * ShutdownComplete`. Any error during teardown is logged to stderr via
+ * `globalThis.console.error` because the logger itself may be in an
+ * indeterminate state at that point.
+ *
+ * @internal
+ */
 async function teardown(internal, logger) {
+    // skip if the app never fully started or has already been torn down
     if (internal.boot.phase !== "running") {
         return;
     }
@@ -448,14 +598,16 @@ async function teardown(internal, logger) {
         logger.debug({ name: teardown }, `[ShutdownStart] running lifecycle callbacks`);
         await internal.boot.lifecycle.exec("ShutdownStart");
         internal.boot.completedLifecycleEvents.add("ShutdownStart");
-        // - clean up active `sleep` calls (can keep tests open and stuff)
+        // cancel any in-flight sleep() calls; without this they keep the event loop
+        // alive and hang test runners / process exits
         ACTIVE_SLEEPS.forEach(i => i.kill("stop"));
         logger.debug({ name: teardown }, `[ShutdownComplete] running lifecycle callbacks`);
         await internal.boot.lifecycle.exec("ShutdownComplete");
         internal.boot.completedLifecycleEvents.add("ShutdownComplete");
     }
     catch (error) {
-        // ! oof
+        // teardown errors are logged via globalThis.console rather than logger because
+        // the logger service itself may have been partially torn down by this point
         globalThis.console.error({ error }, "error occurred during teardown, some lifecycle events may be incomplete");
     }
     // * Final resource cleanup, attempt to reset everything possible
@@ -463,6 +615,8 @@ async function teardown(internal, logger) {
         name: teardown,
         started_at: internal.utils.relativeDate(internal.boot.startup),
     }, `application terminated`);
+    // deregister signal handlers so they don't fire again if the process receives
+    // another signal after teardown completes
     processEvents.forEach((callback, event) => process.removeListener(event, callback));
 }
 //# sourceMappingURL=wiring.service.mjs.map