di-bag 0.2.0 → 0.3.0

package/dist/di-bag.js

@@ -23,15 +23,17 @@ const plugins_1 = require("./plugins");
  *
  * Create bags through {@link DiBagApi.createBuilder} followed by {@link Builder.build} or
  * {@link Builder.buildAndStart}; the class is exported as a type and has no public constructor.
+ * @see https://dany-fedorov.github.io/di-bag/agent/api-card.html#bag
  */
 class Bag {
-    context;
     #graph;
     #runtime;
+    context;
     constructor(graph, context, runtime) {
-        this.context = context;
         this.#graph = graph;
         this.#runtime = runtime ?? new runtime_1.BagRuntime(graph, context);
+        // Scopes and forks reuse the classifier the runtime resolved, so detection runs once per build.
+        this.context = this.#runtime.context;
     }
     resolve(token) {
         return this.#runtime.resolve(typeof token === 'string' ? token : (0, tokens_1.readTokenKey)(token));
@@ -46,6 +48,11 @@ class Bag {
      * Nothing is acquired. Named dependencies declared on factory parameters are not visible
      * until the factory runs; the static graph tool reports them from source.
      * @returns A frozen point-in-time snapshot; application-owned metadata payloads are not frozen.
+     * @example
+     * ```ts
+     * const bag = DiBag.createBuilder().register({ greeting: () => 'hello' }).build();
+     * const labels = bag.inspectGraph().bindings.map(binding => binding.label);
+     * ```
      */
     inspectGraph() { return this.#runtime.inspectGraph(); }
     createScope(...args) {
@@ -92,12 +99,24 @@ class Bag {
     /**
      * Close this bag, drain in-flight work, and dispose owned resources once.
      * Dependents are disposed before dependencies; remaining independent acquisitions use
-     * reverse acquisition order. Repeated calls return the same promise.
-     * @returns The shared shutdown promise.
-     * @throws {@link DiBagCleanupError} when one or more disposers fail after all cleanup is attempted.
+     * reverse acquisition order. Without options the promise waits for cleanup however long it
+     * takes, and repeated calls return the same promise. With `timeoutMs` or `signal`, cleanup
+     * starts the same way but the returned promise stops waiting when either fires; scopes and
+     * forks accept the same options. Close every scope and fork you create; a parent closes its live scopes, never forks.
+     * @param options - An optional deadline and abort signal bounding the wait, not the cleanup.
+     * @returns The shared shutdown promise, or a bounded wait on it when options are given.
+     * @throws {@link DiBagCleanupError} (`DI_BAG_CLEANUP_FAILED`) when one or more disposers fail after all cleanup is attempted;
+     * `DI_BAG_CLOSE_FAILED` for other shutdown failures;
+     * {@link DiBagCloseCancelledError} (`DI_BAG_CLOSE_TIMEOUT` or `DI_BAG_CLOSE_ABORTED`) when the wait stops first,
+     * naming unfinished disposers in `details.pending`; `DI_BAG_INVALID_CLOSE` for malformed options.
+     * @example
+     * ```ts
+     * const bag = DiBag.createBuilder().register({ value: () => 1 }).build();
+     * await bag.close({ timeoutMs: 10_000, signal: AbortSignal.timeout(15_000) });
+     * ```
      */
-    close() {
-        return this.#runtime.close();
+    close(options) {
+        return (0, startup_1.closeRuntime)(this.#runtime, options);
     }
 }
 /**
@@ -106,6 +125,7 @@ class Bag {
  * {@link Builder.build} a bag once its graph is complete, or
  * {@link Builder.buildModule} a reusable module whose unmet dependencies become
  * requirements the installing host must satisfy.
+ * @see https://dany-fedorov.github.io/di-bag/agent/api-card.html#builder
  */
 class Builder {
     context;
@@ -129,6 +149,12 @@ class Builder {
      * @param destination - A new string name or typed token.
      * @param target - The existing name or token whose canonical acquisition is reused.
      * @returns A new builder; aliases add no cache or ownership of their own.
+     * @throws `DI_BAG_INVALID_TOKEN` for a bad token; `DI_BAG_DUPLICATE_REGISTRATION` when the destination exists;
+     * `DI_BAG_INVALID_ALIAS` for an absent named target.
+     * @example
+     * ```ts
+     * const builder = DiBag.createBuilder().register({ clock: () => Date.now() }).alias('now', 'clock');
+     * ```
      */
     alias(destination, target, ...invalid) {
         const [key, registration] = (0, aliases_1.aliasEntry)(destination, target, key => this.#graph.hasPublic(key));
@@ -139,6 +165,13 @@ class Builder {
      * @param token - The collection's typed token.
      * @param registration - A registration whose output satisfies the token service type.
      * @returns A new builder preserving contribution order.
+     * @throws `DI_BAG_INVALID_TOKEN` for a bad token; `DI_BAG_INVALID_REGISTRATION` for an invalid registration.
+     * @example
+     * ```ts
+     * const toolsKey = Symbol('tools');
+     * const tools = DiBag.token(toolsKey).of<string>();
+     * const builder = DiBag.createBuilder().contribute(tools, () => 'search').contribute(tools, () => 'fetch');
+     * ```
      */
     // A named callable keeps extracted generic methods nameable in consumer declarations.
     contribute = ((token, registration) => {
@@ -155,8 +188,17 @@ class Builder {
     }
     /**
      * Install a sealed module, allocating fresh private bindings for this installation.
+     * The installing host must register every requirement the module does not register itself.
      * @param module - A module whose public names do not collide and whose external requirements remain checkable.
      * @returns A new builder exposing only the module's selected exports.
+     * @throws `DI_BAG_INVALID_MODULE` for a value not made by `buildModule`; `DI_BAG_DUPLICATE_REGISTRATION` when an export name is already registered.
+     * @example
+     * ```ts
+     * const greeting = DiBag.createBuilder()
+     *   .register({ greet: ({ name }: { name: string }) => `hello, ${name}` })
+     *   .buildModule(['greet']);
+     * const bag = DiBag.createBuilder().installModule(greeting).register({ name: () => 'Ada' }).build();
+     * ```
      */
     installModule(module) {
         return new Builder(this.#graph.withInstallation((0, module_1.moduleGraph)(module)), this.context);
@@ -168,16 +210,35 @@ class Builder {
      * become requirements of the module. Installed modules nest: their private
      * bindings and retained constraints are re-scoped inside this module.
      * @param keys - A finite tuple of existing names or tokens; an empty tuple is allowed.
+     * @param options - An optional `label`; each installation names its private bindings `<label>/<key>` in
+     * error messages, cycle paths, `inspectGraph()`, and observer events, and nested labels compose as `outer/inner/key`.
      * @returns An immutable module that can be renamed or installed in another builder.
-     * @throws If the selection is not a tuple or contains an absent name or token.
+     * @throws `DI_BAG_INVALID_EXPORT` if the selection is not a tuple, contains an absent name or token, or the label is not a non-empty string;
+     * `DI_BAG_INVALID_TOKEN` for a value that is not a genuine token.
+     * @example
+     * ```ts
+     * const orders = DiBag.createBuilder()
+     *   .register({ repository: () => new Map<string, number>() })
+     *   .register({ placeOrder: ({ repository }: { repository: Map<string, number> }) => (id: string) => repository.set(id, 1) })
+     *   .buildModule(['placeOrder'], { label: 'orders' });
+     * // Errors and inspectGraph() name the private binding 'orders/repository'.
+     * const app = DiBag.createBuilder().installModule(orders).build();
+     * ```
      */
-    buildModule(keys) {
-        return (0, module_1.sealModule)(this.#graph, keys);
+    buildModule(keys, options) {
+        return (0, module_1.sealModule)(this.#graph, keys, options);
     }
     /**
      * Finish a complete graph as a lazy bag.
+     * The bag owns what it acquires; close it when done.
      * @returns A fresh bag that owns the acquisitions it creates.
-     * @throws At runtime if automatic acquisition is used without a configured Promise classifier.
+     * @throws `DI_BAG_CLASSIFIER_REQUIRED` when a registration uses `auto` acquisition, the facade has no Promise
+     * classifier, and the host has no `process.getBuiltinModule`.
+     * @example
+     * ```ts
+     * const bag = DiBag.createBuilder().register({ greeting: () => 'hello' }).build();
+     * await bag.close();
+     * ```
      */
     build() {
         return new Bag(this.#graph, this.context);
@@ -187,8 +248,16 @@ class Builder {
      * @param keys - A finite tuple of existing names or typed tokens to make ready.
      * @param options - Optional cancellation signal, positive timeout, and parallel, sequential, or positive safe integer bounded scheduling.
      * @returns A promise for the new bag after every selected final stage is ready.
-     * @throws {@link DiBagStartupError} after rollback on acquisition failure, or
-     * {@link DiBagStartupCancelledError} promptly on abort or timeout.
+     * @throws {@link DiBagStartupError} (`DI_BAG_STARTUP_FAILED`) after rollback on acquisition failure;
+     * {@link DiBagStartupCancelledError} (`DI_BAG_STARTUP_CANCELLED`) promptly on abort or timeout;
+     * `DI_BAG_INVALID_STARTUP` for malformed keys or options; `DI_BAG_INVALID_TOKEN` for a bad token;
+     * `DI_BAG_CLASSIFIER_REQUIRED` as for {@link Builder.build}. Each arrives as a rejection.
+     * @example
+     * ```ts
+     * const bag = await DiBag.createBuilder()
+     *   .register({ db: async () => ({ ping: () => true }) })
+     *   .buildAndStart(['db'], { timeoutMs: 5_000 });
+     * ```
      */
     async buildAndStart(keys, options) {
         const runtime = await (0, startup_1.startRuntime)(this.#graph, this.context, keys, options);
@@ -215,5 +284,8 @@ function facade(context) {
         withDisposal: registration_1.withDisposal, withLifetime: lifetime_1.withLifetime, withMetadata: provider_1.withMetadata, transformService: provider_1.transformService,
     });
 }
-/** The portable, immutable DI Bag facade. Configure `auto` acquisition or use explicit modes. */
+/**
+ * The immutable DI Bag facade. `auto` acquisition uses the host classifier where `process.getBuiltinModule`
+ * exists; elsewhere configure one or use explicit modes.
+ */
 exports.DiBag = facade(acquisition_mode_1.unconfigured);

package/dist/errors.d.ts

@@ -1,22 +1,45 @@
-/** Stable category for a diagnostic created by DI Bag itself. */
+/**
+ * Stable category for a diagnostic created by DI Bag itself.
+ * @see https://dany-fedorov.github.io/di-bag/agent/errors.html#runtime-codes
+ */
 export type DiBagErrorCode = `DI_BAG_${string}`;
-/** Structured library diagnostics. Application-owned payloads retain their identity. */
+/**
+ * Structured library diagnostics. Application-owned payloads retain their identity.
+ * @see https://dany-fedorov.github.io/di-bag/agent/errors.html#runtime-codes
+ */
 export interface DiBagDiagnostic {
     readonly code: DiBagErrorCode;
     readonly details: Readonly<Record<string, unknown>>;
 }
-/** Attach only at library-owned error creation sites; never modify application errors. */
+/** Prefix the code and append the errors-page section so a stack trace names both. */
+export declare function diagnosticMessage(code: DiBagErrorCode, message: string): string;
+/** Attach only at library-owned error creation sites whose message came from {@link diagnosticMessage}; never modify application errors. */
 export declare function diagnostic<E extends Error>(error: E, code: DiBagErrorCode, details?: Readonly<Record<string, unknown>>): E & DiBagDiagnostic;
 export declare function libraryError(code: DiBagErrorCode, message: string, details?: Readonly<Record<string, unknown>>): Error & DiBagDiagnostic;
 export declare function libraryTypeError(code: DiBagErrorCode, message: string, details?: Readonly<Record<string, unknown>>): TypeError & DiBagDiagnostic;
-/** One disposer failure, associated with the acquisition that owned it. */
+/**
+ * One disposer failure, associated with the acquisition that owned it.
+ * @see https://dany-fedorov.github.io/di-bag/agent/errors.html#di-bag-cleanup-failed
+ */
 export interface CleanupFailure {
     readonly acquisitionId: symbol;
     readonly bindingId: symbol;
     readonly label: string;
     readonly error: unknown;
 }
-/** A plugin descriptor or produced value crossed the checked plugin boundary. */
+/**
+ * A plugin descriptor or its acquired output failed validation at the checked plugin boundary.
+ * @example
+ * ```ts
+ * import { DiBag, DiBagPluginValidationError } from 'di-bag';
+ *
+ * try {
+ *   DiBag.fromPlugin([], { apiVersion: 2 }, { acquisitionMode: 'raw', validate: (value): value is string => typeof value === 'string' });
+ * } catch (error) {
+ *   if (error instanceof DiBagPluginValidationError) console.error(error.phase, error.reason);
+ * }
+ * ```
+ */
 export declare class DiBagPluginValidationError extends Error {
     readonly phase: 'descriptor' | 'output';
     readonly reason: string;
@@ -28,7 +51,19 @@ export declare class DiBagPluginValidationError extends Error {
      */
     constructor(phase: 'descriptor' | 'output', reason: string);
 }
-/** Original cleanup causes and detached acquisition diagnostics, in attempt order. */
+/**
+ * One or more disposers failed during `close()`; every cleanup was still attempted.
+ * `failures` lists each original error with the label of the service it belonged to, in attempt order.
+ * @example
+ * ```ts
+ * import { DiBag, DiBagCleanupError } from 'di-bag';
+ *
+ * const bag = DiBag.createBuilder().register({ value: () => 1 }).build();
+ * await bag.close().catch((error: unknown) => {
+ *   if (error instanceof DiBagCleanupError) for (const failure of error.failures) console.error(failure.label, failure.error);
+ * });
+ * ```
+ */
 export declare class DiBagCleanupError extends AggregateError {
     readonly code: 'DI_BAG_CLEANUP_FAILED';
     readonly details: Readonly<Record<string, unknown>>;
@@ -37,7 +72,21 @@ export declare class DiBagCleanupError extends AggregateError {
     /** @param failures - Structured failures whose original errors also populate `AggregateError.errors`. */
     constructor(failures: readonly CleanupFailure[]);
 }
-/** Acquisition failure after the new bag has finished releasing its resources. */
+/**
+ * `buildAndStart` failed to acquire a selected service; the new bag has already released its resources.
+ * `cause` is the original failure and `cleanupFailures` lists disposers that failed during rollback.
+ * @example
+ * ```ts
+ * import { DiBag, DiBagStartupError } from 'di-bag';
+ *
+ * const builder = DiBag.createBuilder().register({ db: async (): Promise<number> => { throw new Error('offline'); } });
+ * try {
+ *   await builder.buildAndStart(['db']);
+ * } catch (error) {
+ *   if (error instanceof DiBagStartupError) console.error(error.cause, error.cleanupFailures);
+ * }
+ * ```
+ */
 export declare class DiBagStartupError extends Error {
     readonly cleanupError?: unknown | undefined;
     readonly code: 'DI_BAG_STARTUP_FAILED';
@@ -51,7 +100,21 @@ export declare class DiBagStartupError extends Error {
      */
     constructor(cause: unknown, cleanupFailures: readonly CleanupFailure[], cleanupError?: unknown | undefined);
 }
-/** Prompt cancellation; cleanup remains awaitable for uncooperative factories. */
+/**
+ * `buildAndStart` stopped waiting on abort or timeout; `cleanupPromise` settles when the partial bag is released.
+ * On timeout, `cause` carries `DI_BAG_STARTUP_TIMEOUT`.
+ * @example
+ * ```ts
+ * import { DiBag, DiBagStartupCancelledError } from 'di-bag';
+ *
+ * const builder = DiBag.createBuilder().register({ db: () => new Promise<number>(() => {}) });
+ * try {
+ *   await builder.buildAndStart(['db'], { timeoutMs: 1_000 });
+ * } catch (error) {
+ *   if (error instanceof DiBagStartupCancelledError) await error.cleanupPromise;
+ * }
+ * ```
+ */
 export declare class DiBagStartupCancelledError extends Error {
     readonly reason: 'aborted' | 'timeout';
     readonly cleanupPromise: Promise<void>;
@@ -64,3 +127,47 @@ export declare class DiBagStartupCancelledError extends Error {
      */
     constructor(reason: 'aborted' | 'timeout', cause: unknown, cleanupPromise: Promise<void>);
 }
+/**
+ * What a close deadline or abort interrupted: labels still in progress when the wait stopped.
+ * @see https://dany-fedorov.github.io/di-bag/agent/errors.html#di-bag-close-timeout
+ */
+export interface CloseProgress {
+    /** Labels of disposers that started and had not completed. */
+    readonly pending: readonly string[];
+    /** Labels of acquisitions close was still draining before running disposers. */
+    readonly acquiring: readonly string[];
+}
+/**
+ * A `close({ timeoutMs, signal })` wait stopped before cleanup finished; cleanup keeps running.
+ * `code` is `DI_BAG_CLOSE_TIMEOUT` for the deadline and `DI_BAG_CLOSE_ABORTED` for the signal.
+ * @example
+ * ```ts
+ * import { DiBag, DiBagCloseCancelledError } from 'di-bag';
+ *
+ * const bag = DiBag.createBuilder().register({ value: () => 1 }).build();
+ * try {
+ *   await bag.close({ timeoutMs: 5_000 });
+ * } catch (error) {
+ *   if (error instanceof DiBagCloseCancelledError) console.error(error.details.pending);
+ *   throw error;
+ * }
+ * ```
+ */
+export declare class DiBagCloseCancelledError extends Error {
+    readonly reason: 'aborted' | 'timeout';
+    readonly cleanupPromise: Promise<void>;
+    readonly code: 'DI_BAG_CLOSE_TIMEOUT' | 'DI_BAG_CLOSE_ABORTED';
+    readonly details: Readonly<{
+        operation: 'close';
+        reason: 'aborted' | 'timeout';
+        timeoutMs?: number;
+    } & CloseProgress>;
+    /**
+     * @param reason - Whether an external abort or the close deadline stopped the wait.
+     * @param cause - The abort reason, or a `TimeoutError` DOMException for the deadline.
+     * @param cleanupPromise - The bag's shared shutdown promise; it settles when cleanup eventually finishes.
+     * @param progress - Labels still in progress when the wait stopped.
+     * @param timeoutMs - The deadline that elapsed, for `reason: 'timeout'`.
+     */
+    constructor(reason: 'aborted' | 'timeout', cause: unknown, cleanupPromise: Promise<void>, progress: CloseProgress, timeoutMs?: number);
+}

package/dist/errors.js

@@ -1,10 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DiBagStartupCancelledError = exports.DiBagStartupError = exports.DiBagCleanupError = exports.DiBagPluginValidationError = void 0;
+exports.DiBagCloseCancelledError = exports.DiBagStartupCancelledError = exports.DiBagStartupError = exports.DiBagCleanupError = exports.DiBagPluginValidationError = void 0;
+exports.diagnosticMessage = diagnosticMessage;
 exports.diagnostic = diagnostic;
 exports.libraryError = libraryError;
 exports.libraryTypeError = libraryTypeError;
-/** Attach only at library-owned error creation sites; never modify application errors. */
+// The one place the errors page URL lives; fragments follow the site's heading slugs.
+const errorsPage = 'https://dany-fedorov.github.io/di-bag/agent/errors.html';
+/** Prefix the code and append the errors-page section so a stack trace names both. */
+function diagnosticMessage(code, message) {
+    return `${code}: ${message}; see ${errorsPage}#${code.toLowerCase().replaceAll('_', '-')}`;
+}
+/** Attach only at library-owned error creation sites whose message came from {@link diagnosticMessage}; never modify application errors. */
 function diagnostic(error, code, details = {}) {
     Object.defineProperties(error, {
         code: { value: code, enumerable: true },
@@ -13,12 +20,24 @@ function diagnostic(error, code, details = {}) {
     return error;
 }
 function libraryError(code, message, details = {}) {
-    return diagnostic(new Error(message), code, details);
+    return diagnostic(new Error(diagnosticMessage(code, message)), code, details);
 }
 function libraryTypeError(code, message, details = {}) {
-    return diagnostic(new TypeError(message), code, details);
+    return diagnostic(new TypeError(diagnosticMessage(code, message)), code, details);
 }
-/** A plugin descriptor or produced value crossed the checked plugin boundary. */
+/**
+ * A plugin descriptor or its acquired output failed validation at the checked plugin boundary.
+ * @example
+ * ```ts
+ * import { DiBag, DiBagPluginValidationError } from 'di-bag';
+ *
+ * try {
+ *   DiBag.fromPlugin([], { apiVersion: 2 }, { acquisitionMode: 'raw', validate: (value): value is string => typeof value === 'string' });
+ * } catch (error) {
+ *   if (error instanceof DiBagPluginValidationError) console.error(error.phase, error.reason);
+ * }
+ * ```
+ */
 class DiBagPluginValidationError extends Error {
     phase;
     reason;
@@ -27,7 +46,7 @@ class DiBagPluginValidationError extends Error {
      * @param reason - A stable description of the rejected boundary condition.
      */
     constructor(phase, reason) {
-        super(`Invalid plugin ${phase}: ${reason}`);
+        super(diagnosticMessage('DI_BAG_PLUGIN_VALIDATION', `Invalid plugin ${phase}: ${reason}`));
         this.phase = phase;
         this.reason = reason;
         this.name = 'DiBagPluginValidationError';
@@ -35,21 +54,47 @@ class DiBagPluginValidationError extends Error {
     }
 }
 exports.DiBagPluginValidationError = DiBagPluginValidationError;
-/** Original cleanup causes and detached acquisition diagnostics, in attempt order. */
+/**
+ * One or more disposers failed during `close()`; every cleanup was still attempted.
+ * `failures` lists each original error with the label of the service it belonged to, in attempt order.
+ * @example
+ * ```ts
+ * import { DiBag, DiBagCleanupError } from 'di-bag';
+ *
+ * const bag = DiBag.createBuilder().register({ value: () => 1 }).build();
+ * await bag.close().catch((error: unknown) => {
+ *   if (error instanceof DiBagCleanupError) for (const failure of error.failures) console.error(failure.label, failure.error);
+ * });
+ * ```
+ */
 class DiBagCleanupError extends AggregateError {
     /** Frozen cleanup failures in finalizer invocation order. */
     failures;
     /** @param failures - Structured failures whose original errors also populate `AggregateError.errors`. */
     constructor(failures) {
         const snapshot = Object.freeze(failures.map(item => Object.freeze({ ...item })));
-        super(snapshot.map(item => item.error), `Failed to run ${snapshot.length} disposal callback(s)`);
+        super(snapshot.map(item => item.error), diagnosticMessage('DI_BAG_CLEANUP_FAILED', `Failed to run ${snapshot.length} disposal callback(s)`));
         this.name = 'DiBagCleanupError';
         diagnostic(this, 'DI_BAG_CLEANUP_FAILED', { operation: 'close', failedCallbacks: snapshot.length, failures: snapshot });
         this.failures = snapshot;
     }
 }
 exports.DiBagCleanupError = DiBagCleanupError;
-/** Acquisition failure after the new bag has finished releasing its resources. */
+/**
+ * `buildAndStart` failed to acquire a selected service; the new bag has already released its resources.
+ * `cause` is the original failure and `cleanupFailures` lists disposers that failed during rollback.
+ * @example
+ * ```ts
+ * import { DiBag, DiBagStartupError } from 'di-bag';
+ *
+ * const builder = DiBag.createBuilder().register({ db: async (): Promise<number> => { throw new Error('offline'); } });
+ * try {
+ *   await builder.buildAndStart(['db']);
+ * } catch (error) {
+ *   if (error instanceof DiBagStartupError) console.error(error.cause, error.cleanupFailures);
+ * }
+ * ```
+ */
 class DiBagStartupError extends Error {
     cleanupError;
     /** Frozen rollback disposal failures in invocation order. */
@@ -60,7 +105,7 @@ class DiBagStartupError extends Error {
      * @param cleanupError - The complete shutdown error, when rollback itself rejected.
      */
     constructor(cause, cleanupFailures, cleanupError) {
-        super('Failed to start bag', { cause });
+        super(diagnosticMessage('DI_BAG_STARTUP_FAILED', 'Failed to start bag'), { cause });
         this.cleanupError = cleanupError;
         this.name = 'DiBagStartupError';
         this.cleanupFailures = Object.freeze(cleanupFailures.map(item => Object.freeze({ ...item })));
@@ -68,7 +113,21 @@ class DiBagStartupError extends Error {
     }
 }
 exports.DiBagStartupError = DiBagStartupError;
-/** Prompt cancellation; cleanup remains awaitable for uncooperative factories. */
+/**
+ * `buildAndStart` stopped waiting on abort or timeout; `cleanupPromise` settles when the partial bag is released.
+ * On timeout, `cause` carries `DI_BAG_STARTUP_TIMEOUT`.
+ * @example
+ * ```ts
+ * import { DiBag, DiBagStartupCancelledError } from 'di-bag';
+ *
+ * const builder = DiBag.createBuilder().register({ db: () => new Promise<number>(() => {}) });
+ * try {
+ *   await builder.buildAndStart(['db'], { timeoutMs: 1_000 });
+ * } catch (error) {
+ *   if (error instanceof DiBagStartupCancelledError) await error.cleanupPromise;
+ * }
+ * ```
+ */
 class DiBagStartupCancelledError extends Error {
     reason;
     cleanupPromise;
@@ -78,7 +137,7 @@ class DiBagStartupCancelledError extends Error {
      * @param cleanupPromise - Eventual shutdown of the partially started bag; cancellation does not await it.
      */
     constructor(reason, cause, cleanupPromise) {
-        super(`Bag startup ${reason}`, { cause });
+        super(diagnosticMessage('DI_BAG_STARTUP_CANCELLED', `Bag startup ${reason}`), { cause });
         this.reason = reason;
         this.cleanupPromise = cleanupPromise;
         this.name = 'DiBagStartupCancelledError';
@@ -87,3 +146,45 @@ class DiBagStartupCancelledError extends Error {
     }
 }
 exports.DiBagStartupCancelledError = DiBagStartupCancelledError;
+/**
+ * A `close({ timeoutMs, signal })` wait stopped before cleanup finished; cleanup keeps running.
+ * `code` is `DI_BAG_CLOSE_TIMEOUT` for the deadline and `DI_BAG_CLOSE_ABORTED` for the signal.
+ * @example
+ * ```ts
+ * import { DiBag, DiBagCloseCancelledError } from 'di-bag';
+ *
+ * const bag = DiBag.createBuilder().register({ value: () => 1 }).build();
+ * try {
+ *   await bag.close({ timeoutMs: 5_000 });
+ * } catch (error) {
+ *   if (error instanceof DiBagCloseCancelledError) console.error(error.details.pending);
+ *   throw error;
+ * }
+ * ```
+ */
+class DiBagCloseCancelledError extends Error {
+    reason;
+    cleanupPromise;
+    /**
+     * @param reason - Whether an external abort or the close deadline stopped the wait.
+     * @param cause - The abort reason, or a `TimeoutError` DOMException for the deadline.
+     * @param cleanupPromise - The bag's shared shutdown promise; it settles when cleanup eventually finishes.
+     * @param progress - Labels still in progress when the wait stopped.
+     * @param timeoutMs - The deadline that elapsed, for `reason: 'timeout'`.
+     */
+    constructor(reason, cause, cleanupPromise, progress, timeoutMs) {
+        const code = reason === 'timeout' ? 'DI_BAG_CLOSE_TIMEOUT' : 'DI_BAG_CLOSE_ABORTED';
+        const waiting = progress.pending.length ? `; disposers still running: ${progress.pending.join(', ')}`
+            : progress.acquiring.length ? `; acquisitions still pending: ${progress.acquiring.join(', ')}` : '';
+        super(diagnosticMessage(code, `Bag close ${reason === 'timeout' ? `timed out after ${timeoutMs}ms` : 'aborted'}${waiting}`), { cause });
+        this.reason = reason;
+        this.cleanupPromise = cleanupPromise;
+        this.name = 'DiBagCloseCancelledError';
+        diagnostic(this, code, {
+            operation: 'close', reason, ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            pending: Object.freeze([...progress.pending]), acquiring: Object.freeze([...progress.acquiring]),
+        });
+        void cleanupPromise.catch(() => { });
+    }
+}
+exports.DiBagCloseCancelledError = DiBagCloseCancelledError;

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { DiBag } from './di-bag';
-export { DiBagCleanupError, DiBagPluginValidationError, DiBagStartupError, DiBagStartupCancelledError } from './errors';
-export type { CleanupFailure, DiBagErrorCode, DiBagDiagnostic } from './errors';
+export { DiBagCleanupError, DiBagCloseCancelledError, DiBagPluginValidationError, DiBagStartupError, DiBagStartupCancelledError } from './errors';
+export type { CleanupFailure, CloseProgress, DiBagErrorCode, DiBagDiagnostic } from './errors';
 export type { Bag, Builder, DiBagApi, ConfigurationOptions } from './di-bag';
-export type { Module } from './module';
+export type { Module, ModuleOptions } from './module';
 export type { CompositionReport } from './composition-report';
 export type { ModuleExportedServices, ModuleRequiredServices, ModuleConstraints, ModuleSealedConstraints, SealedConstraints, PublicProviders, ModulePublicProviders, Renamed } from './module-types';
 export type { FactoryWithDisposal, Registration } from './registration';
@@ -10,11 +10,11 @@ export type { Provider, ProviderFactory, ProviderGraphContract, ProviderOutput,
 export type { AcquisitionMode, RuntimeOptions } from './acquisition-mode';
 export type { Lifetime } from './lifetime';
 export type { AcquisitionContext, ContextualFactory } from './acquisition-context';
-export type { StartupOptions } from './startup';
+export type { CloseOptions, StartupOptions } from './startup';
 export type { ScopeOptions, DisjointScopeSelection, UnsharedAliases, ScopedAliases, SharedAliasProviders } from './scope-types';
 export type { Token, TokenBase, TokenKey, TokenService } from './tokens';
 export type { TokenBinding, TokenMember, TokenDependencyContract, ReboundProviders, ReboundSelection, SelectionKey } from './token-types';
-export type { CheckedLifetimes, CheckedScopeLifetimes, LexicalContext, ModuleScope, Enclosed, RenamedContext, RenamedLifetimeObligation, EnclosedLifetimeObligation, RenamedLifetimeProviders } from './lifetime-types';
+export type { CheckedLifetimes, CheckedScopeLifetimes, LifetimeObligation, Reach } from './lifetime-types';
 export type { DiBagPolicy } from './types';
 export type { CheckDependencyCompatibility, CheckDependencyCompleteness, RegistrationEntries, OverrideFactoryContext, RegistrationsFromEntries, OverrideRegistrations, Overrides, ServicesOf, SelectedRegistrations, Selection } from './types';
 export type { Presence, AcquisitionMetadataPresence, AcquisitionSnapshot, RegistrationSnapshot, BindingSnapshot, GraphSnapshot } from './inspection';

package/dist/index.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DiBagStartupCancelledError = exports.DiBagStartupError = exports.DiBagPluginValidationError = exports.DiBagCleanupError = exports.DiBag = void 0;
+exports.DiBagStartupCancelledError = exports.DiBagStartupError = exports.DiBagPluginValidationError = exports.DiBagCloseCancelledError = exports.DiBagCleanupError = exports.DiBag = void 0;
 var di_bag_1 = require("./di-bag");
 Object.defineProperty(exports, "DiBag", { enumerable: true, get: function () { return di_bag_1.DiBag; } });
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "DiBagCleanupError", { enumerable: true, get: function () { return errors_1.DiBagCleanupError; } });
+Object.defineProperty(exports, "DiBagCloseCancelledError", { enumerable: true, get: function () { return errors_1.DiBagCloseCancelledError; } });
 Object.defineProperty(exports, "DiBagPluginValidationError", { enumerable: true, get: function () { return errors_1.DiBagPluginValidationError; } });
 Object.defineProperty(exports, "DiBagStartupError", { enumerable: true, get: function () { return errors_1.DiBagStartupError; } });
 Object.defineProperty(exports, "DiBagStartupCancelledError", { enumerable: true, get: function () { return errors_1.DiBagStartupCancelledError; } });

package/dist/inspection.d.ts

@@ -1,17 +1,26 @@
 import type { AcquisitionMode } from './acquisition-mode';
 import type { Lifetime } from './lifetime';
-/** Structural optional presence; payloads are application-owned and not frozen. */
+/**
+ * Structural optional presence; payloads are application-owned and not frozen.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#attach-metadata-and-inspect-without-resolving
+ */
 export type Presence<T> = {
     readonly present: false;
 } | {
     readonly present: true;
     readonly value: T;
 };
-/** A readonly tuple indicating whether each acquisition-stage frame is available. */
+/**
+ * A readonly tuple indicating whether each acquisition-stage frame is available.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#attach-metadata-and-inspect-without-resolving
+ */
 export type AcquisitionMetadataPresence<A extends readonly unknown[]> = {
     readonly [I in keyof A]: Presence<A[I]>;
 };
-/** A frozen point-in-time view of one acquisition attempt. */
+/**
+ * A frozen point-in-time view of one acquisition attempt.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#attach-metadata-and-inspect-without-resolving
+ */
 export interface AcquisitionSnapshot<A extends readonly unknown[] = readonly []> {
     /** Stable identity for this attempt; retries receive a new symbol. */
     readonly acquisitionId: symbol;
@@ -20,7 +29,10 @@ export interface AcquisitionSnapshot<A extends readonly unknown[] = readonly []>
     /** Ordered presence records for metadata captured during acquisition. */
     readonly acquisitionMetadata: AcquisitionMetadataPresence<A>;
 }
-/** A frozen registration description and copied acquisition state returned by bag inspection. */
+/**
+ * A frozen registration description and copied acquisition state returned by bag inspection.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#attach-metadata-and-inspect-without-resolving
+ */
 export interface RegistrationSnapshot<M = Readonly<{}>, A extends readonly unknown[] = readonly []> {
     /** Stable identity for the canonical graph binding. */
     readonly bindingId: symbol;
@@ -36,7 +48,10 @@ export interface RegistrationSnapshot<M = Readonly<{}>, A extends readonly unkno
     /** Point-in-time attempts; inspection does not retain failed-attempt history. */
     readonly acquisitions: readonly AcquisitionSnapshot<A>[];
 }
-/** One binding of a bag's graph, described without acquiring it. */
+/**
+ * One binding of a bag's graph, described without acquiring it.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#attach-metadata-and-inspect-without-resolving
+ */
 export interface BindingSnapshot<M = Readonly<{}>, A extends readonly unknown[] = readonly []> extends RegistrationSnapshot<M, A> {
     /** Public names or token symbols that select this binding, in registration order; empty for a private module binding. */
     readonly keys: readonly (string | symbol)[];
@@ -54,6 +69,7 @@ export interface BindingSnapshot<M = Readonly<{}>, A extends readonly unknown[]
  * A frozen description of every binding a bag can resolve, plus the edges observed so far.
  * Named dependencies read from a factory's object parameter are not knowable until the factory
  * runs; `observedEdges` records them after acquisition. Use the static graph tool for declared edges.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#attach-metadata-and-inspect-without-resolving
  */
 export interface GraphSnapshot {
     readonly scopeId: symbol;