@zudojs/core 1.0.0 → 1.2.0

package/README.md

@@ -2,6 +2,12 @@
 
 Application lifecycle management, execution context propagation, and runtime orchestration for Zudojs applications.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-core](https://zudojs.oyinlola.site/docs/packages-core) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-core.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -43,6 +49,8 @@ await app.start(); // restart: a fresh runtime is created
 await app.shutdown(); // stop + dispose; cannot be restarted afterwards
 ```
 
+When `runtime.mode` is omitted, it is derived from `NODE_ENV` with `resolveEnvironment()` from `@zudojs/constants` (`prod` / `Production` → `"production"`, `staging` → `"production"`, `test` → `"test"`, unset → `"development"`).
+
 `createApplication` wires the standard graph (container, configuration manager, logger, module registry/loader/lifecycle, runtime, application lifecycle). Every piece can also be assembled by hand:
 
 ```typescript
@@ -66,6 +74,8 @@ const app = await Application.create({
 });
 ```
 
+A failed `lifecycle.start()` stops, in reverse order, every participant whose `start()` completed, so a retry starts from the first one again. `dispose()` only reaches participants whose `initialize()` ran.
+
 ## Runtime
 
 `createRuntime(dependencies, options)` returns a single-use runtime:
@@ -77,14 +87,14 @@ FAILED is reachable from every non-terminal state via fail() or a failure.
 
 - `start()` loads, initializes, and starts modules through the bootstrap pipeline; `getStatus().bootstrap` reports counts, errors, and duration.
 - `stop()` stops and destroys modules through the shutdown pipeline; `getStatus().shutdown` reports the same.
-- `startup.timeoutMs` / `shutdown.timeoutMs` abort the pipeline with a `RuntimeTimeoutError`; the abandoned pipeline can never surface an unhandled rejection.
+- `startup.timeoutMs` / `shutdown.timeoutMs` abort the pipeline with a `RuntimeTimeoutError`; the abandoned pipeline can never surface an unhandled rejection. A timed-out bootstrap starts no further phase or module hook; the hook still running finishes, and the runtime then stops and destroys whatever it brought up. `stop()` waits for that teardown.
 - `continueOnInitializeError` / `continueOnStartError` (and the stop/destroy equivalents) make the runtime finish with `success: false` and the failures listed instead of throwing.
 - Every error the runtime throws extends `RuntimeError` (which itself extends `RuntimeError` from `@zudojs/errors`), so `isRuntimeError()` from either package recognises it.
 - `runtime.context` is the runtime's immutable `RuntimeExecutionContext` (`executionId` = runtime id, `service` = runtime name, `metadata.runtimeId/runtimeName/runtimeMode/runtimeRole` plus `RuntimeOptions.metadata`); `runtime.timing` holds the state-transition timestamps; `runtime.contextStorage` is the `ContextStorage` the context is established in (`RuntimeDependencies.contextStorage`, default `getDefaultContextStorage()`).
 
 ### Signals
 
-When `signals.handleSigint` / `handleSigterm` / `handleSighup` are on (SIGINT and SIGTERM default to on), the runtime registers handlers on start and removes them on stop, failure, or dispose. The first signal triggers a graceful `stop()`. A second signal during shutdown is logged and ignored unless `signals.forceExitOnSecondSignal` is explicitly enabled, in which case the process exits with `signals.forceExitCode`. `handleUncaughtException` / `handleUnhandledRejection` mark the runtime failed and stop it. The runtime never calls `process.exit()` otherwise.
+When `signals.handleSigint` / `handleSigterm` / `handleSighup` are on (SIGINT and SIGTERM default to on), the runtime registers handlers on start and removes them on stop, failure, or dispose. The first signal triggers a graceful `stop()`. A second signal during shutdown exits the process with `signals.forceExitCode` (default 1); set `signals.forceExitOnSecondSignal: false` to log and ignore it instead. `handleUncaughtException` / `handleUnhandledRejection` mark the runtime failed, stop it, and then exit the process with code 1, because the installed handler suppresses Node's own crash and the process would otherwise end with code 0. `signals.fatalExitTimeout` (default 10000 ms) bounds a shutdown that hangs; set `signals.exitOnFatalError: false` to stop the runtime and keep the process running. The runtime never calls `process.exit()` otherwise.
 
 ## Modules
 
@@ -103,7 +113,7 @@ onInitialize → onReady → onShutdown → onDestroy
 
 `createConfigurationManager({ registry, schemas, loaderOptions, validationOptions, redactorOptions })` loads registered sources by priority, deep-merges them, applies schema defaults, validates, and exposes an immutable `Configuration`.
 
-- `manager.on(event, listener)` / `manager.off(...)` receive `initializing`, `loaded`, `validated`, `ready`, `failed`, `reloading`, and `reloaded` events.
+- `manager.on(type, listener)` / `manager.off(...)` receive the `configuration.initializing`, `configuration.loaded`, `configuration.validated`, `configuration.ready`, `configuration.failed`, `configuration.reloading`, and `configuration.reloaded` events (`"*"` subscribes to all of them).
 - `manager.getSection(name)` returns a scoped configuration for a registered section; `manager.reload()` keeps programmatic defaults and serialises overlapping reloads.
 - Values are deep-frozen; `toObject()` returns an independent deep copy. Path lookups never walk the prototype chain, and `getNumber` accepts only plain decimal numbers.
 - Secrets never reach errors or logs: validation, load, and source errors pass through the redactor, which matches whole key words (`password`, `secret`, `token`, `pwd`, `passphrase`, `auth`, `dsn`, `credential`, ...).
@@ -120,14 +130,14 @@ onInitialize → onReady → onShutdown → onDestroy
 
 ## Execution context
 
-There is one execution-context model: the immutable `ExecutionContext` (`createExecutionContext`, `deriveExecutionContext`, `withExecutionMetadata`) propagated by `ContextStorage`, which wraps `AsyncLocalStorage`. `run(context, fn)` and `runDerived(overrides, fn)` establish a context for the callback and everything it awaits, `runWithValues(values, fn)` adds request-scoped values, and `capture()` / `runSnapshot(snapshot, fn)` carry a context across queue or timer boundaries. `getDefaultContextStorage()` is the process-wide instance every component uses unless another is injected.
+There is one execution-context model: the immutable `ExecutionContext` (`createExecutionContext`, `deriveExecutionContext`, `withExecutionMetadata`) propagated by `ContextStorage`, which wraps `AsyncLocalStorage`. `run(context, fn)` and `runDerived(overrides, fn)` establish a context for the callback and everything it awaits, `runWithValues(context, values, fn)` additionally binds a `ContextValues` collection (read back with `getValues()`; `run()` starts a new execution without the enclosing execution's values, `runDerived()` keeps them), and `capture()` / `runSnapshot(snapshot, fn)` carry a context across queue or timer boundaries. `getDefaultContextStorage()` is the process-wide instance every component uses unless another is injected.
 
 Propagation is real at runtime:
 
 - `runtime.start()` and `runtime.stop()` run the bootstrap and shutdown pipelines inside `runtime.contextStorage.run(runtime.context, ...)`.
 - Each module hook (`onInitialize`, `onReady`, `onShutdown`, `onDestroy`) runs in a context derived from it: `module` is the module id, `operation` is the hook name, and `{ moduleId, phase }` is merged into `metadata`. `ModuleLifecycleOptions.contextStorage` selects the storage (default: the shared one).
 - `Application.start()` / `stop()` / `shutdown()` run lifecycle participants inside the runtime's context as well.
-- `createApplication` threads one storage (`CreateApplicationOptions.contextStorage`) through the `ApplicationContext` (`getContextStorage()`), the container's `currentScope` (so `"scoped"` providers resolve once per execution context), the module lifecycle, the runtime, and the logger.
+- `createApplication` threads one storage (`CreateApplicationOptions.contextStorage`) through the `ApplicationContext` (`getContextStorage()`), the container's `currentScope` (so `"scoped"` providers resolve once per execution context; resolving one outside any execution context, or from a singleton's factory, throws a `DependencyResolutionError`), the module lifecycle, the runtime, and the logger.
 
 ```typescript
 import { defineModule, getDefaultContextStorage } from "@zudojs/core";

package/dist/application/applicationContext.context.d.ts

@@ -5,7 +5,14 @@ import type { Logger } from "../logging/core/logger.js";
 import type { ContextStorage } from "../context/provider/contextStorage.storage.js";
 export interface ApplicationContextOptions {
     readonly container: Container;
-    readonly configuration: Configuration;
+    /**
+     * The application configuration, or a function returning the
+     * current one. Pass a function (for example
+     * `() => manager.getConfiguration()`) so that
+     * `getConfiguration()` reflects configuration reloads instead of
+     * the snapshot taken when the context was created.
+     */
+    readonly configuration: Configuration | (() => Configuration);
     readonly modules: ModuleRegistry;
     readonly logger: Logger;
     /**
@@ -34,6 +41,10 @@ export declare class ApplicationContext {
     getContainer(): Container;
     /**
      * Application configuration.
+     *
+     * When the context was created with a configuration accessor
+     * (as `createApplication` does), this returns the configuration
+     * manager's current configuration, including reloads.
      */
     getConfiguration(): Configuration;
     /**

package/dist/application/applicationContext.context.js

@@ -13,7 +13,11 @@ export class ApplicationContext {
     contextStorage;
     constructor(options) {
         this.container = options.container;
-        this.configuration = options.configuration;
+        const configuration = options.configuration;
+        this.configuration =
+            typeof configuration === "function"
+                ? configuration
+                : () => configuration;
         this.modules = options.modules;
         this.logger = options.logger;
         this.contextStorage = options.contextStorage ?? getDefaultContextStorage();
@@ -26,9 +30,13 @@ export class ApplicationContext {
     }
     /**
      * Application configuration.
+     *
+     * When the context was created with a configuration accessor
+     * (as `createApplication` does), this returns the configuration
+     * manager's current configuration, including reloads.
      */
     getConfiguration() {
-        return this.configuration;
+        return this.configuration();
     }
     /**
      * Registered application modules.

package/dist/application/createApplication.js

@@ -44,7 +44,12 @@ export async function createApplication(options = {}) {
     }
     const context = new ApplicationContext({
         container,
-        configuration: configuration.getConfiguration(),
+        /*
+         * An accessor rather than a snapshot: after
+         * `configuration.reload()` the application context must hand
+         * out the reloaded configuration, not the one captured here.
+         */
+        configuration: () => configuration.getConfiguration(),
         modules: moduleRegistry,
         logger,
         contextStorage,

package/dist/configuration/configurationManager.manager.d.ts

@@ -53,6 +53,7 @@ export declare class ConfigurationManager {
     private loadResult;
     private validationReport;
     private missingSetConfigurationWarned;
+    private inFlightReload;
     private stateValue;
     constructor(options?: ConfigurationManagerOptions);
     /**
@@ -72,7 +73,16 @@ export declare class ConfigurationManager {
      */
     getListenerErrors(): readonly unknown[];
     initialize(): Promise<ConfigurationManagerResult>;
+    /**
+     * Reloads configuration from the registered sources.
+     *
+     * Overlapping calls are serialised: a reload requested while one
+     * is already in progress shares that in-flight reload instead of
+     * failing with InvalidStateError. A manager that is not ready yet
+     * is initialized instead.
+     */
     reload(): Promise<ConfigurationManagerResult>;
+    private performReload;
     getConfiguration(): Configuration;
     getProvider(): ConfigurationProvider;
     getRegistry(): ConfigurationRegistry;

package/dist/configuration/configurationManager.manager.js

@@ -31,6 +31,7 @@ export class ConfigurationManager {
     loadResult;
     validationReport;
     missingSetConfigurationWarned = false;
+    inFlightReload;
     stateValue = ConfigurationManagerState.CREATED;
     constructor(options = {}) {
         this.loader =
@@ -104,9 +105,26 @@ export class ConfigurationManager {
             throw error;
         }
     }
+    /**
+     * Reloads configuration from the registered sources.
+     *
+     * Overlapping calls are serialised: a reload requested while one
+     * is already in progress shares that in-flight reload instead of
+     * failing with InvalidStateError. A manager that is not ready yet
+     * is initialized instead.
+     */
     async reload() {
+        if (this.inFlightReload)
+            return this.inFlightReload;
         if (this.stateValue !== ConfigurationManagerState.READY)
             return this.initialize();
+        const reload = this.performReload().finally(() => {
+            this.inFlightReload = undefined;
+        });
+        this.inFlightReload = reload;
+        return reload;
+    }
+    async performReload() {
         const previousConfiguration = this.configuration;
         const previousLoadResult = this.loadResult;
         const previousValidation = this.validationReport;
@@ -201,7 +219,7 @@ export class ConfigurationManager {
         }
         if (!this.missingSetConfigurationWarned) {
             this.missingSetConfigurationWarned = true;
-            console.warn("ConfigurationManager: the configured ConfigurationProvider does not implement setConfiguration(); loaded configuration will not be pushed into the provider.");
+            process.emitWarning("ConfigurationManager: the configured ConfigurationProvider does not implement setConfiguration(); loaded configuration will not be pushed into the provider.", { type: "ZudojsCoreWarning", code: "ZUDOJS_CONFIG_PROVIDER_NO_SET" });
         }
     }
     emit(event) {

package/dist/container/container.d.ts

@@ -12,8 +12,8 @@ export interface ContainerOptions {
      *   new Container({ currentScope: () => storage.get() })
      *
      * "scoped" providers resolve to one instance per returned object.
-     * When it returns undefined and no explicit scope is active, scoped
-     * providers behave as transient.
+     * When it returns undefined and no explicit scope is active, resolving
+     * a scoped provider throws a DependencyResolutionError.
      */
     readonly currentScope?: () => object | undefined;
 }
@@ -26,10 +26,11 @@ export interface ContainerOptions {
  */
 export declare class Container {
     private readonly providers;
-    private readonly scopedInstances;
     private readonly currentScope;
     private readonly resolving;
     private activeScope;
+    /** The singleton under construction, if any; see assertScopedResolvable. */
+    private captor;
     constructor(options?: ContainerOptions);
     /**
      * Registers a provider in the container.

package/dist/container/container.js

@@ -1,4 +1,5 @@
 import { ProviderNotFoundError, ProviderAlreadyRegisteredError, InvalidProviderError, DependencyResolutionError, } from "../errors/exceptions.js";
+import { assertScopedResolvable } from "./container.lifetime.js";
 /**
  * Dependency Injection container for Zudojs applications.
  *
@@ -8,10 +9,11 @@ import { ProviderNotFoundError, ProviderAlreadyRegisteredError, InvalidProviderE
  */
 export class Container {
     providers = new Map();
-    scopedInstances = new WeakMap();
     currentScope;
     resolving = [];
     activeScope;
+    /** The singleton under construction, if any; see assertScopedResolvable. */
+    captor;
     constructor(options = {}) {
         this.currentScope = options.currentScope;
     }
@@ -29,6 +31,7 @@ export class Container {
             provider: provider,
             scope,
             resolved: false,
+            scopedInstances: new WeakMap(),
         });
     }
     /**
@@ -80,10 +83,12 @@ export class Container {
         if (registration.scope === "singleton" && registration.resolved) {
             return registration.instance;
         }
+        if (registration.scope === "scoped") {
+            assertScopedResolvable(token, this.captor, scopeKey, this.resolving);
+        }
         if (registration.scope === "scoped" && scopeKey) {
-            const cache = this.scopedInstances.get(scopeKey);
-            if (cache?.has(token)) {
-                return cache.get(token);
+            if (registration.scopedInstances.has(scopeKey)) {
+                return registration.scopedInstances.get(scopeKey);
             }
         }
         const instance = this.createInstance(token, registration, scopeKey);
@@ -92,12 +97,7 @@ export class Container {
             registration.resolved = true;
         }
         else if (registration.scope === "scoped" && scopeKey) {
-            let cache = this.scopedInstances.get(scopeKey);
-            if (!cache) {
-                cache = new Map();
-                this.scopedInstances.set(scopeKey, cache);
-            }
-            cache.set(token, instance);
+            registration.scopedInstances.set(scopeKey, instance);
         }
         return instance;
     }
@@ -115,8 +115,12 @@ export class Container {
             return provider.useValue;
         }
         const previousScope = this.activeScope;
+        const previousCaptor = this.captor;
         this.resolving.push(token);
         this.activeScope = scopeKey;
+        if (registration.scope === "singleton") {
+            this.captor = token;
+        }
         try {
             if ("useFactory" in provider) {
                 return provider.useFactory(this);
@@ -131,6 +135,7 @@ export class Container {
         finally {
             this.resolving.pop();
             this.activeScope = previousScope;
+            this.captor = previousCaptor;
         }
     }
 }

package/dist/container/container.lifetime.d.ts

@@ -0,0 +1,21 @@
+import type { Token } from "./token.js";
+/**
+ * Rejects a "scoped" resolution that would outlive or escape its scope.
+ *
+ * - A scoped provider resolved (directly or transitively) while a
+ *   singleton is being constructed would be captured by that singleton
+ *   and served to every later scope: one request's user, tenant or
+ *   transaction leaking into all the others. This is the captive
+ *   dependency error mature DI containers raise.
+ * - A scoped provider resolved with no active scope has nothing to be
+ *   scoped to. It used to behave as transient, which hid the missing
+ *   scope; it now fails like `@zudojs/container`'s ScopedResolutionError.
+ *
+ * @param token - The scoped token being resolved.
+ * @param captor - The singleton currently under construction, if any.
+ * @param scopeKey - The active scope key, if any.
+ * @param chain - The current resolution chain, for the diagnostic.
+ * @throws DependencyResolutionError when either rule is broken.
+ */
+export declare function assertScopedResolvable(token: Token<unknown>, captor: Token<unknown> | undefined, scopeKey: object | undefined, chain: readonly Token<unknown>[]): void;
+//# sourceMappingURL=container.lifetime.d.ts.map

package/dist/container/container.lifetime.js

@@ -0,0 +1,39 @@
+import { DependencyResolutionError } from "../errors/exceptions.js";
+/**
+ * Rejects a "scoped" resolution that would outlive or escape its scope.
+ *
+ * - A scoped provider resolved (directly or transitively) while a
+ *   singleton is being constructed would be captured by that singleton
+ *   and served to every later scope: one request's user, tenant or
+ *   transaction leaking into all the others. This is the captive
+ *   dependency error mature DI containers raise.
+ * - A scoped provider resolved with no active scope has nothing to be
+ *   scoped to. It used to behave as transient, which hid the missing
+ *   scope; it now fails like `@zudojs/container`'s ScopedResolutionError.
+ *
+ * @param token - The scoped token being resolved.
+ * @param captor - The singleton currently under construction, if any.
+ * @param scopeKey - The active scope key, if any.
+ * @param chain - The current resolution chain, for the diagnostic.
+ * @throws DependencyResolutionError when either rule is broken.
+ */
+export function assertScopedResolvable(token, captor, scopeKey, chain) {
+    if (captor !== undefined) {
+        throw new DependencyResolutionError(`Captive dependency: singleton "${describe(captor)}" cannot depend on ` +
+            `scoped "${describe(token)}". Register the consumer as "scoped" or ` +
+            `"transient", or resolve the scoped dependency lazily per call.`, [...chain, token]);
+    }
+    if (scopeKey === undefined) {
+        throw new DependencyResolutionError(`Scoped provider "${describe(token)}" was resolved outside any scope. ` +
+            `Resolve it through container.createScope() or inside an execution ` +
+            `context.`, [...chain, token]);
+    }
+}
+function describe(token) {
+    if (typeof token === "function")
+        return token.name || "anonymous class";
+    if (typeof token === "symbol")
+        return token.description ?? token.toString();
+    return String(token);
+}
+//# sourceMappingURL=container.lifetime.js.map

package/dist/container/scope.d.ts

@@ -15,7 +15,9 @@ export type Scope =
  * example the current ExecutionContext of an HTTP request,
  * background job, message consumption, or RPC call).
  *
- * When no scope is active, scoped providers behave as transient.
+ * Resolving a scoped provider with no active scope, or from inside a
+ * singleton's construction (a captive dependency), throws a
+ * DependencyResolutionError.
  */
  | "scoped"
 /**

package/dist/context/provider/contextStorage.storage.d.ts

@@ -30,6 +30,14 @@ export declare class ContextStorage {
      *
      * The context is automatically available to all asynchronous
      * operations created within the callback.
+     *
+     * A new execution starts without ContextValues: values bound by an
+     * enclosing `runWithValues` belong to that execution (its tenant,
+     * user, transaction) and must not leak into an unrelated one started
+     * from inside its async scope, such as a listener or consumer created
+     * during a request. Re-entering the execution that is already current
+     * keeps its values. Use `runDerived` or `runWithValues` to carry
+     * values on purpose.
      */
     run<T>(context: ExecutionContext, callback: () => T): T;
     /**

package/dist/context/provider/contextStorage.storage.js

@@ -24,9 +24,20 @@ export class ContextStorage {
      *
      * The context is automatically available to all asynchronous
      * operations created within the callback.
+     *
+     * A new execution starts without ContextValues: values bound by an
+     * enclosing `runWithValues` belong to that execution (its tenant,
+     * user, transaction) and must not leak into an unrelated one started
+     * from inside its async scope, such as a listener or consumer created
+     * during a request. Re-entering the execution that is already current
+     * keeps its values. Use `runDerived` or `runWithValues` to carry
+     * values on purpose.
      */
     run(context, callback) {
-        return this.storage.run(context, callback);
+        if (context === this.storage.getStore()) {
+            return this.storage.run(context, callback);
+        }
+        return this.storage.run(context, () => this.valuesStorage.exit(callback));
     }
     /**
      * Returns the current execution context.

package/dist/lifecycle/core/lifecycle.d.ts

@@ -39,9 +39,12 @@ export interface LifecycleOptions {
  *
  *   CREATED → INITIALIZING → INITIALIZED → STARTING → RUNNING
  *   RUNNING → STOPPING → STOPPED → (STARTING → RUNNING) restart
- *   any phase failure → FAILED; initialize()/start() retry from FAILED
- *   resume with the participant that failed; stop() from FAILED unwinds
- *   whatever started.
+ *   any phase failure → FAILED; initialize() retries from FAILED resume
+ *   with the participant that failed. A failed start() is rolled back:
+ *   every participant whose start() completed is stopped in reverse
+ *   order, so a retry starts again from the first one. dispose() only
+ *   reaches participants whose initialize() ran (including one that
+ *   threw, which may have acquired resources before failing).
  *
  * Concurrent callers of the same phase share the in-flight promise.
  */
@@ -52,6 +55,8 @@ export declare class Lifecycle {
     private readonly continueOnShutdownError;
     private initializedCount;
     private startedCount;
+    /** Participants whose initialize() was invoked, whether or not it threw. */
+    private initializeAttempted;
     private disposed;
     private failedPhase;
     private initializePromise;

package/dist/lifecycle/core/lifecycle.js

@@ -1,4 +1,5 @@
 import { InvalidStateError } from "../../errors/exceptions.js";
+import { rollbackStartedParticipants } from "./lifecycle.rollback.js";
 /** Lifecycle states supported by the Zudojs application runtime. */
 export const LifecycleState = {
     CREATED: "created",
@@ -18,9 +19,12 @@ export const LifecycleState = {
  *
  *   CREATED → INITIALIZING → INITIALIZED → STARTING → RUNNING
  *   RUNNING → STOPPING → STOPPED → (STARTING → RUNNING) restart
- *   any phase failure → FAILED; initialize()/start() retry from FAILED
- *   resume with the participant that failed; stop() from FAILED unwinds
- *   whatever started.
+ *   any phase failure → FAILED; initialize() retries from FAILED resume
+ *   with the participant that failed. A failed start() is rolled back:
+ *   every participant whose start() completed is stopped in reverse
+ *   order, so a retry starts again from the first one. dispose() only
+ *   reaches participants whose initialize() ran (including one that
+ *   threw, which may have acquired resources before failing).
  *
  * Concurrent callers of the same phase share the in-flight promise.
  */
@@ -31,6 +35,8 @@ export class Lifecycle {
     continueOnShutdownError;
     initializedCount = 0;
     startedCount = 0;
+    /** Participants whose initialize() was invoked, whether or not it threw. */
+    initializeAttempted = 0;
     disposed = false;
     failedPhase;
     initializePromise;
@@ -194,7 +200,8 @@ export class Lifecycle {
         }
         this.disposed = true;
         const errors = [];
-        for (let i = this.participants.length - 1; i >= 0; i--) {
+        // A participant whose initialize() never ran has nothing to release.
+        for (let i = this.initializeAttempted - 1; i >= 0; i--) {
             const participant = this.participants[i];
             try {
                 this.logger?.debug("Disposing lifecycle participant", {
@@ -213,6 +220,7 @@ export class Lifecycle {
         }
         this.initializedCount = 0;
         this.startedCount = 0;
+        this.initializeAttempted = 0;
         if (errors.length > 0 && !this.continueOnShutdownError) {
             this.state = LifecycleState.FAILED;
             this.failedPhase = "dispose";
@@ -255,6 +263,7 @@ export class Lifecycle {
                 this.logger?.debug("Initializing lifecycle participant", {
                     participant: participant.name,
                 });
+                this.initializeAttempted = Math.max(this.initializeAttempted, i + 1);
                 await participant.initialize?.();
                 this.initializedCount = i + 1;
             }
@@ -285,9 +294,13 @@ export class Lifecycle {
             this.logger?.info("Application startup completed");
         }
         catch (error) {
+            this.logger?.error("Application startup failed", error);
+            // Roll back rather than leave earlier participants running until
+            // someone remembers to call shutdown().
+            await rollbackStartedParticipants(this.participants, this.startedCount, this.logger);
+            this.startedCount = 0;
             this.state = LifecycleState.FAILED;
             this.failedPhase = "start";
-            this.logger?.error("Application startup failed", error);
             throw error;
         }
     }

package/dist/lifecycle/core/lifecycle.rollback.d.ts

@@ -0,0 +1,18 @@
+import type { Logger } from "../../logging/core/logger.js";
+import type { LifecycleParticipant } from "./lifecycle.js";
+/**
+ * Stops, in reverse order, the first `count` participants after a
+ * failed start.
+ *
+ * Only participants whose `start()` completed are stopped; the one
+ * that threw is left to its own error handling, as `stop()` has always
+ * done. Stop failures are logged and returned; they never mask the
+ * start error.
+ *
+ * @param participants - Registered participants, in start order.
+ * @param count - How many leading participants started successfully.
+ * @param logger - Optional logger for rollback diagnostics.
+ * @returns The errors raised by `stop()` hooks during the rollback.
+ */
+export declare function rollbackStartedParticipants(participants: readonly LifecycleParticipant[], count: number, logger: Logger | undefined): Promise<readonly unknown[]>;
+//# sourceMappingURL=lifecycle.rollback.d.ts.map

package/dist/lifecycle/core/lifecycle.rollback.js

@@ -0,0 +1,34 @@
+/**
+ * Stops, in reverse order, the first `count` participants after a
+ * failed start.
+ *
+ * Only participants whose `start()` completed are stopped; the one
+ * that threw is left to its own error handling, as `stop()` has always
+ * done. Stop failures are logged and returned; they never mask the
+ * start error.
+ *
+ * @param participants - Registered participants, in start order.
+ * @param count - How many leading participants started successfully.
+ * @param logger - Optional logger for rollback diagnostics.
+ * @returns The errors raised by `stop()` hooks during the rollback.
+ */
+export async function rollbackStartedParticipants(participants, count, logger) {
+    const errors = [];
+    for (let i = count - 1; i >= 0; i--) {
+        const participant = participants[i];
+        try {
+            logger?.debug("Rolling back lifecycle participant", {
+                participant: participant.name,
+            });
+            await participant.stop?.();
+        }
+        catch (error) {
+            errors.push(error);
+            logger?.error("Failed to roll back lifecycle participant", error, {
+                participant: participant.name,
+            });
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=lifecycle.rollback.js.map

package/dist/logging/core/logEntry.entry.js

@@ -123,7 +123,18 @@ export function sanitizeLogValue(value, seen = new WeakSet(), depth = 0) {
         }
         const result = {};
         for (const [key, item] of Object.entries(objectValue)) {
-            result[key] = sanitizeLogValue(item, seen, depth + 1);
+            /*
+             * Assigning result["__proto__"] would replace the prototype
+             * (and drop the value from serialized output) instead of
+             * storing the key, so own "__proto__" keys — as produced by
+             * JSON.parse on untrusted input — are defined explicitly.
+             */
+            Object.defineProperty(result, key, {
+                value: sanitizeLogValue(item, seen, depth + 1),
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
         }
         return result;
     }

package/dist/modules/moduleLifecycle/index.d.ts

@@ -8,6 +8,6 @@
  * state maps) is internal to this subsystem and intentionally
  * not exported from this barrel.
  */
-export { type ModuleLifecyclePhase, type ModuleLifecycleState, type ModuleLifecycleHookName, type ModuleLifecycleStep, type ModuleLifecycleHooks, type ModuleLifecycleOptions, ModuleLifecycleError, type ModuleLifecycleResult, type ModuleLifecycleSkip, } from "./moduleLifecycle.type.js";
+export { type ModuleLifecyclePhase, type ModuleLifecycleState, type ModuleLifecycleHookName, type ModuleLifecycleStep, type ModuleLifecycleHooks, type ModuleLifecycleOptions, type ModuleLifecyclePhaseOptions, ModuleLifecycleError, type ModuleLifecycleResult, type ModuleLifecycleSkip, } from "./moduleLifecycle.type.js";
 export { ModuleLifecycleManager, createModuleLifecycleManager, } from "./moduleLifecycle.lifecycle.js";
 //# sourceMappingURL=index.d.ts.map