@codefast/di 0.3.13 → 0.3.14-canary.1

package/dist/metadata/metadata-types.d.mts

@@ -2,53 +2,77 @@ import { Token } from "../token.mjs";
 import { Constructor } from "../binding.mjs";
 
 //#region src/metadata/metadata-types.d.ts
-/** Metadata written per `accessor` field decorated with `@inject`; collected into `Symbol.metadata`. */
+/**
+ * Metadata written per `accessor` field decorated with `@inject`; collected into `Symbol.metadata`.
+ */
 type AccessorInjectionMetadata = {
-  readonly name: string;
-  readonly token: Token<unknown> | Constructor<unknown>;
-  readonly optional: boolean;
+  /** Accessor property name to inject after construction. */readonly name: string; /** Token/constructor resolved for this accessor. */
+  readonly token: Token<unknown> | Constructor<unknown>; /** Whether missing binding resolves to `undefined` instead of throwing. */
+  readonly optional: boolean; /** Optional name/tag filter forwarded to binding selection. */
   readonly resolveHint?: {
-    readonly name?: string;
+    /** Named-binding discriminator (`whenNamed`). */readonly name?: string; /** Tagged-binding discriminator (`whenTagged`). */
     readonly tag?: readonly [tag: string, value: unknown];
   };
 };
-/** Lifecycle method names written by `@postConstruct()` / `@preDestroy()` into `Symbol.metadata`. */
+/**
+ * Lifecycle method names written by `@postConstruct()` / `@preDestroy()` into `Symbol.metadata`.
+ */
 type LifecycleMetadata = {
-  readonly postConstruct?: string;
+  /** Method name marked with `@postConstruct()`. */readonly postConstruct?: string; /** Method name marked with `@preDestroy()`. */
   readonly preDestroy?: string;
-  readonly accessorInjections?: readonly AccessorInjectionMetadata[];
 };
 /**
  * Per-parameter injection description collected by `@injectable()`.
  */
 type ParamMetadata = {
-  readonly index: number;
-  readonly token: Token<unknown> | Constructor<unknown>;
-  readonly optional: boolean;
-  readonly name?: string;
+  /** Zero-based constructor parameter index. */readonly index: number; /** Token/constructor used to resolve this parameter. */
+  readonly token: Token<unknown> | Constructor<unknown>; /** Whether missing binding resolves to `undefined`. */
+  readonly optional: boolean; /** Optional named-binding discriminator. */
+  readonly name?: string; /** Optional tagged-binding discriminator. */
   readonly tag?: readonly [tag: string, value: unknown];
+  /**
+   * When true, the parameter receives every binding for `token` as an array (same semantics as
+   * `Container.resolveAll` / `ResolutionContext.resolveAll`), using `name` / `tag` as a filter when set.
+   */
+  readonly all?: boolean;
 };
 /**
  * Resolved form of an `inject()` / `optional()` call: token + optional flag + optional resolve hint.
  * Used both as a deps-array entry in `@injectable()` and as accessor-field injection metadata.
  */
 type InjectionDescriptor<Value = unknown> = {
-  readonly token: Token<Value> | Constructor<Value>;
-  readonly optional: boolean;
-  readonly name?: string;
-  readonly tag?: readonly [tag: string, value: unknown];
+  /** Token/constructor to resolve. */readonly token: Token<Value> | Constructor<Value>; /** Whether unbound token should resolve as `undefined`. */
+  readonly optional: boolean; /** Optional named-binding discriminator. */
+  readonly name?: string; /** Optional tagged-binding discriminator. */
+  readonly tag?: readonly [tag: string, value: unknown]; /** When true, resolve every binding for {@link InjectionDescriptor.token} into an array. */
+  readonly all?: boolean;
 };
 /**
  * Constructor injection shape stored on the class `Symbol.metadata` object.
  */
 type ConstructorMetadata = {
-  readonly params: readonly ParamMetadata[];
+  /** Ordered constructor dependency descriptors. */readonly params: readonly ParamMetadata[];
 };
 /**
- * Abstraction for reading DI metadata (section 6.4) without tying callers to `Symbol.metadata`.
+ * Abstraction for reading DI metadata without tying callers to `Symbol.metadata` directly.
+ * The {@link DependencyResolver} uses this to instantiate `class` bindings and read lifecycle hooks.
+ *
+ * The default implementation is {@link SymbolMetadataReader}; consumers can supply a custom
+ * reader (e.g. backed by a static config object) via `ResolverDependencies.metadataReader`.
  */
 type MetadataReader = {
+  /**
+   * Returns constructor parameter injection metadata for `implementationClass`, or `undefined`
+   * if the class has no own `@injectable()` metadata. When a {@link MetadataReader} is
+   * configured on the container, `undefined` here combined with `arity > 0` on the class
+   * causes {@link MissingMetadataError} during resolution; when no reader is configured, the
+   * resolver instantiates with zero arguments instead (see `DependencyResolver` class binding path).
+   */
   getConstructorMetadata(implementationClass: Constructor<unknown>): ConstructorMetadata | undefined;
+  /**
+   * Returns lifecycle method names (`@postConstruct` / `@preDestroy`), or `undefined` if none.
+   * Optional: when absent the resolver skips lifecycle hooks entirely.
+   */
   getLifecycleMetadata?(implementationClass: Constructor<unknown>): LifecycleMetadata | undefined;
 };
 //#endregion

package/dist/metadata/param-registry.mjs

@@ -1,4 +1,10 @@
 //#region src/metadata/param-registry.ts
+/**
+* WeakMap keyed by constructor → pending parameter metadata.
+* Entries are populated by legacy parameter decorators that fire *before* the
+* `@injectable()` class decorator runs, and consumed (via {@link takePendingMap})
+* by the class decorator to merge into the final {@link ConstructorMetadata}.
+*/
 const pendingByConstructor = /* @__PURE__ */ new WeakMap();
 /**
 * Returns the pending `ParamMetadata` map for `implementationClass`, creating it on first access.

package/dist/metadata/symbol-metadata-reader.d.mts

@@ -3,12 +3,29 @@ import { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "./metada
 
 //#region src/metadata/symbol-metadata-reader.d.ts
 /**
- * Reads {@link ConstructorMetadata} from the standard `Symbol.metadata` object.
+ * Default {@link MetadataReader} implementation backed by TC39 `Symbol.metadata`.
+ *
+ * Constructor metadata (`@injectable()`) is read with `Object.hasOwn` to prevent
+ * a subclass from silently inheriting a parent's dependency list — each class must
+ * declare its own `@injectable()` decorator or be constructed with zero arguments.
+ *
+ * Lifecycle metadata (`@postConstruct` / `@preDestroy`) *is* inherited through the
+ * prototype chain, matching the intent that a parent's lifecycle hook applies to children.
  */
 declare class SymbolMetadataReader implements MetadataReader {
-  /** Reads constructor param metadata written by `@injectable()`. Returns `undefined` if none present. */
+  /**
+   * Reads constructor param metadata written by `@injectable()`.
+   * Returns `undefined` if no own metadata is present on the class.
+   *
+   * @remarks
+   * Uses `Object.hasOwn` intentionally — TC39 `Symbol.metadata` prototype-chains from
+   * parent to child, so without this guard a subclass without `@injectable()` would
+   * silently inherit the parent's parameter list and inject the wrong dependency count.
+   */
   getConstructorMetadata(implementationClass: Constructor<unknown>): ConstructorMetadata | undefined;
-  /** Reads lifecycle method names written by `@postConstruct()` / `@preDestroy()`. Inherits from parent classes. */
+  /**
+   * Reads lifecycle method names written by `@postConstruct()` / `@preDestroy()`. Inherits from parent classes.
+   */
   getLifecycleMetadata(implementationClass: Constructor<unknown>): LifecycleMetadata | undefined;
 }
 //#endregion

package/dist/metadata/symbol-metadata-reader.mjs

@@ -1,15 +1,32 @@
 import { CODEFAST_DI_CONSTRUCTOR_METADATA, CODEFAST_DI_LIFECYCLE_METADATA, decoratorMetadataObjectSymbol } from "./metadata-keys.mjs";
 //#region src/metadata/symbol-metadata-reader.ts
-/** Type guard — returns `true` when `value` has the shape of a {@link ConstructorMetadata} object. */
+/**
+* Type guard — returns `true` when `value` has the shape of a {@link ConstructorMetadata} object.
+*/
 function isConstructorMetadata(value) {
 	if (typeof value !== "object" || value === null || !("params" in value)) return false;
 	return Array.isArray(value.params);
 }
 /**
-* Reads {@link ConstructorMetadata} from the standard `Symbol.metadata` object.
+* Default {@link MetadataReader} implementation backed by TC39 `Symbol.metadata`.
+*
+* Constructor metadata (`@injectable()`) is read with `Object.hasOwn` to prevent
+* a subclass from silently inheriting a parent's dependency list — each class must
+* declare its own `@injectable()` decorator or be constructed with zero arguments.
+*
+* Lifecycle metadata (`@postConstruct` / `@preDestroy`) *is* inherited through the
+* prototype chain, matching the intent that a parent's lifecycle hook applies to children.
 */
 var SymbolMetadataReader = class {
-	/** Reads constructor param metadata written by `@injectable()`. Returns `undefined` if none present. */
+	/**
+	* Reads constructor param metadata written by `@injectable()`.
+	* Returns `undefined` if no own metadata is present on the class.
+	*
+	* @remarks
+	* Uses `Object.hasOwn` intentionally — TC39 `Symbol.metadata` prototype-chains from
+	* parent to child, so without this guard a subclass without `@injectable()` would
+	* silently inherit the parent's parameter list and inject the wrong dependency count.
+	*/
 	getConstructorMetadata(implementationClass) {
 		const rawMetadata = implementationClass[decoratorMetadataObjectSymbol()];
 		if (typeof rawMetadata !== "object" || rawMetadata === null) return;
@@ -19,7 +36,9 @@ var SymbolMetadataReader = class {
 		if (!isConstructorMetadata(raw)) return;
 		return raw;
 	}
-	/** Reads lifecycle method names written by `@postConstruct()` / `@preDestroy()`. Inherits from parent classes. */
+	/**
+	* Reads lifecycle method names written by `@postConstruct()` / `@preDestroy()`. Inherits from parent classes.
+	*/
 	getLifecycleMetadata(implementationClass) {
 		const metadataObject = implementationClass[decoratorMetadataObjectSymbol()];
 		if (typeof metadataObject !== "object" || metadataObject === null) return;

package/dist/module.d.mts

@@ -3,17 +3,42 @@ import { BindingBuilder, Constructor } from "./binding.mjs";
 
 //#region src/module.d.ts
 /**
- * Builder passed to synchronous module setup: register bindings and import other sync modules.
+ * Builder passed to the setup callback of a synchronous {@link Module}.
+ * Use `import()` to declare module dependencies (sync modules only —
+ * passing an {@link AsyncModule} throws {@link InternalError}) and `bind()` to register tokens.
+ *
+ * **Single slot (last-wins)** — `bind(key).to*(...)` with no `whenNamed` / `whenTagged` / `when`
+ * *before* the `to*()` call replaces all prior bindings for `key` from this module pass.
+ *
+ * **Multi-binding** — put at least one disambiguator *before* `to*()` (e.g.
+ * `bind(key).whenNamed("a").to*(...)`, `whenTagged` before `to*()`, or `when` before `to*()`).
+ * Each such line **appends** another binding so {@link Container.resolveAll} can return every
+ * implementation. Use this order in modules; chaining `.to*(...).whenNamed()` only updates that
+ * binding in place and does not stack multiple registrations across lines.
  */
 type ModuleBuilder = {
+  /**
+   * Declares synchronous module dependencies to load before/alongside current setup.
+   */
   readonly import: (...modules: Module[]) => void;
+  /**
+   * Starts binding registration for a token/constructor within this module setup pass.
+   */
   readonly bind: <Value>(key: Token<Value> | Constructor<Value>) => BindingBuilder<Value>;
 };
 /**
- * Builder passed to async module setup.
+ * Builder passed to the setup callback of an {@link AsyncModule}.
+ * Unlike {@link ModuleBuilder}, `import()` accepts both sync and async modules.
+ * Async sub-imports are collected and awaited **after** the setup callback returns.
  */
 type AsyncModuleBuilder = {
+  /**
+   * Declares sync/async module dependencies to be loaded by the async module loader.
+   */
   readonly import: (...modules: (Module | AsyncModule)[]) => void;
+  /**
+   * Starts binding registration for a token/constructor within this async module setup pass.
+   */
   readonly bind: <Value>(key: Token<Value> | Constructor<Value>) => BindingBuilder<Value>;
 };
 /**
@@ -24,8 +49,17 @@ type AsyncModuleBuilder = {
  * binding ids each module produced; the module itself never sees a container reference.
  */
 declare class Module {
+  /**
+   * Human-readable label used in error messages, graph output, and module-cycle diagnostics.
+   */
   readonly name: string;
+  /**
+   * The user-supplied setup callback; invoked exactly once per `load()` call.
+   */
   private readonly syncSetup;
+  /**
+   * @internal Use {@link Module.create} instead.
+   */
   private constructor();
   /**
    * Defines a synchronous module.
@@ -46,9 +80,19 @@ declare class Module {
 /**
  * An async module whose setup callback may `await` before registering bindings.
  * Prefer {@link Module.createAsync} over constructing this class directly.
+ *
+ * Load via `Container.loadAsync()` or `Container.fromModulesAsync()`;
+ * passing an `AsyncModule` to the synchronous `Container.load()` throws
+ * {@link AsyncModuleLoadError}.
  */
 declare class AsyncModule {
+  /**
+   * Human-readable label used in error messages and graph output.
+   */
   readonly name: string;
+  /**
+   * The user-supplied async setup callback; invoked exactly once per `loadAsync()` call.
+   */
   private readonly asyncSetup;
   constructor(name: string, asyncSetup: (builder: AsyncModuleBuilder) => Promise<void>);
   /**

package/dist/module.mjs

@@ -7,8 +7,17 @@
 * binding ids each module produced; the module itself never sees a container reference.
 */
 var Module = class Module {
+	/**
+	* Human-readable label used in error messages, graph output, and module-cycle diagnostics.
+	*/
 	name;
+	/**
+	* The user-supplied setup callback; invoked exactly once per `load()` call.
+	*/
 	syncSetup;
+	/**
+	* @internal Use {@link Module.create} instead.
+	*/
 	constructor(name, syncSetup) {
 		this.name = name;
 		this.syncSetup = syncSetup;
@@ -38,9 +47,19 @@ var Module = class Module {
 /**
 * An async module whose setup callback may `await` before registering bindings.
 * Prefer {@link Module.createAsync} over constructing this class directly.
+*
+* Load via `Container.loadAsync()` or `Container.fromModulesAsync()`;
+* passing an `AsyncModule` to the synchronous `Container.load()` throws
+* {@link AsyncModuleLoadError}.
 */
 var AsyncModule = class {
+	/**
+	* Human-readable label used in error messages and graph output.
+	*/
 	name;
+	/**
+	* The user-supplied async setup callback; invoked exactly once per `loadAsync()` call.
+	*/
 	asyncSetup;
 	constructor(name, asyncSetup) {
 		this.name = name;

package/dist/registry.d.mts

@@ -7,15 +7,39 @@ import { Binding, BindingIdentifier, Constructor } from "./binding.mjs";
  */
 type RegistryKey = Token<unknown> | Constructor<unknown>;
 /**
- * Dumb storage for bindings keyed by token or constructor. Selection and construction logic live elsewhere.
+ * Flat, in-memory storage for {@link Binding} entries keyed by {@link RegistryKey}.
+ * Each key maps to an ordered list of bindings (multi-binding support).
+ *
+ * The registry is a "dumb" store — it does not perform selection, scope caching, or
+ * lifecycle management. Those concerns live in `DependencyResolver` and `ScopeManager`.
+ *
+ * Mutation styles:
+ * - `add` — append-only; never removes existing entries.
+ * - `replaceById` — swaps a single binding in place by ID; no removal callback.
+ * - `remove` / `removeById` — delete entries **without** notifying callers; the caller
+ *   is responsible for draining the scope cache before calling these.
+ * - `replaceKeyLastWins` — replaces all bindings for a key with a single new one **and**
+ *   invokes the `onReplaced` callback for each evicted binding, giving the caller
+ *   (typically the container or scope manager) a chance to run deactivation.
  */
 declare class BindingRegistry {
+  /**
+   * Primary index: registry key → ordered binding list.
+   * Reference equality on the key (i.e. the same {@link Token} or {@link Constructor} object).
+   */
   private readonly bindingsByKey;
-  /** Appends `binding` to the list for `key` (multi-binding: each call adds an entry). */
+  /**
+   * Appends `binding` to the list for `key` (multi-binding: each call adds an entry).
+   */
   add<Value>(key: Token<Value> | Constructor<Value>, binding: Binding<Value>): void;
-  /** Returns all bindings registered for `key`, or `undefined` if none exist. */
+  /**
+   * Returns all bindings registered for `key`, or `undefined` if none exist.
+   */
   get<Value>(key: Token<Value> | Constructor<Value>): readonly Binding<Value>[] | undefined;
-  /** Removes all bindings for `key` without running any deactivation hooks. */
+  /**
+   * Removes all bindings for `key`. Does **not** invoke any callback — the caller must
+   * drain the scope cache (run deactivation) for the affected bindings before calling this.
+   */
   remove(key: RegistryKey): void;
   /**
    * Returns owned registry rows (does not include parent containers).
@@ -24,13 +48,20 @@ declare class BindingRegistry {
     key: RegistryKey;
     bindings: readonly Binding<unknown>[];
   }[];
-  /** Removes the single binding with the given `id` across all keys. */
+  /**
+   * Removes the single binding whose `id` matches, scanning all keys.
+   * Like {@link remove}, does **not** invoke a removal callback.
+   */
   removeById(id: BindingIdentifier): void;
-  /** Swaps the binding with the given `id` in place, preserving its position in the list. */
+  /**
+   * Swaps the binding with the given `id` in place, preserving its position in the list.
+   */
   replaceById(id: BindingIdentifier, next: Binding<unknown>): void;
   /**
-   * Replaces all bindings for `key` with a single binding (module "last-wins" semantics).
-   * Invokes `onReplaced` for every removed binding so scopes can run deactivation.
+   * Replaces all bindings for `key` with a single new binding (module "last-wins" semantics).
+   * Unlike {@link remove} / {@link removeById}, this method invokes `onReplaced` for every
+   * evicted binding **before** inserting the replacement, giving the caller (e.g. the
+   * container's scope manager) a chance to release cached instances and run deactivation hooks.
    */
   replaceKeyLastWins<Value>(key: Token<Value> | Constructor<Value>, binding: Binding<Value>, onReplaced: (removed: Binding<unknown>) => void): void;
 }

package/dist/registry.mjs

@@ -1,10 +1,29 @@
 //#region src/registry.ts
 /**
-* Dumb storage for bindings keyed by token or constructor. Selection and construction logic live elsewhere.
+* Flat, in-memory storage for {@link Binding} entries keyed by {@link RegistryKey}.
+* Each key maps to an ordered list of bindings (multi-binding support).
+*
+* The registry is a "dumb" store — it does not perform selection, scope caching, or
+* lifecycle management. Those concerns live in `DependencyResolver` and `ScopeManager`.
+*
+* Mutation styles:
+* - `add` — append-only; never removes existing entries.
+* - `replaceById` — swaps a single binding in place by ID; no removal callback.
+* - `remove` / `removeById` — delete entries **without** notifying callers; the caller
+*   is responsible for draining the scope cache before calling these.
+* - `replaceKeyLastWins` — replaces all bindings for a key with a single new one **and**
+*   invokes the `onReplaced` callback for each evicted binding, giving the caller
+*   (typically the container or scope manager) a chance to run deactivation.
 */
 var BindingRegistry = class {
+	/**
+	* Primary index: registry key → ordered binding list.
+	* Reference equality on the key (i.e. the same {@link Token} or {@link Constructor} object).
+	*/
 	bindingsByKey = /* @__PURE__ */ new Map();
-	/** Appends `binding` to the list for `key` (multi-binding: each call adds an entry). */
+	/**
+	* Appends `binding` to the list for `key` (multi-binding: each call adds an entry).
+	*/
 	add(key, binding) {
 		const registryKey = key;
 		const nextBinding = binding;
@@ -12,11 +31,16 @@ var BindingRegistry = class {
 		const merged = existing === void 0 ? [nextBinding] : [...existing, nextBinding];
 		this.bindingsByKey.set(registryKey, merged);
 	}
-	/** Returns all bindings registered for `key`, or `undefined` if none exist. */
+	/**
+	* Returns all bindings registered for `key`, or `undefined` if none exist.
+	*/
 	get(key) {
 		return this.bindingsByKey.get(key);
 	}
-	/** Removes all bindings for `key` without running any deactivation hooks. */
+	/**
+	* Removes all bindings for `key`. Does **not** invoke any callback — the caller must
+	* drain the scope cache (run deactivation) for the affected bindings before calling this.
+	*/
 	remove(key) {
 		this.bindingsByKey.delete(key);
 	}
@@ -29,7 +53,10 @@ var BindingRegistry = class {
 			bindings
 		}));
 	}
-	/** Removes the single binding with the given `id` across all keys. */
+	/**
+	* Removes the single binding whose `id` matches, scanning all keys.
+	* Like {@link remove}, does **not** invoke a removal callback.
+	*/
 	removeById(id) {
 		for (const [registryKey, list] of [...this.bindingsByKey.entries()]) {
 			const filtered = list.filter((binding) => binding.id !== id);
@@ -38,7 +65,9 @@ var BindingRegistry = class {
 			else this.bindingsByKey.set(registryKey, filtered);
 		}
 	}
-	/** Swaps the binding with the given `id` in place, preserving its position in the list. */
+	/**
+	* Swaps the binding with the given `id` in place, preserving its position in the list.
+	*/
 	replaceById(id, next) {
 		for (const [registryKey, list] of this.bindingsByKey.entries()) {
 			const index = list.findIndex((binding) => binding.id === id);
@@ -50,8 +79,10 @@ var BindingRegistry = class {
 		}
 	}
 	/**
-	* Replaces all bindings for `key` with a single binding (module "last-wins" semantics).
-	* Invokes `onReplaced` for every removed binding so scopes can run deactivation.
+	* Replaces all bindings for `key` with a single new binding (module "last-wins" semantics).
+	* Unlike {@link remove} / {@link removeById}, this method invokes `onReplaced` for every
+	* evicted binding **before** inserting the replacement, giving the caller (e.g. the
+	* container's scope manager) a chance to release cached instances and run deactivation hooks.
 	*/
 	replaceKeyLastWins(key, binding, onReplaced) {
 		const registryKey = key;

package/dist/resolver.d.mts

@@ -5,29 +5,114 @@ import { MetadataReader } from "./metadata/metadata-types.mjs";
 import { ScopeManager } from "./scope.mjs";
 
 //#region src/resolver.d.ts
-/** Dependencies injected into {@link DependencyResolver} at construction time. */
+/**
+ * Dependencies injected into {@link DependencyResolver} at construction time.
+ */
 type ResolverDependencies = {
-  /** Looks up all bindings registered for a given registry key (own + parent containers). */readonly lookup: (key: RegistryKey) => readonly Binding<unknown>[] | undefined; /** Manages singleton/scoped instance caches and deactivation. */
-  readonly scopeManager: ScopeManager; /** Reads `@injectable()` and lifecycle metadata from constructors. Omit to disable decorator support. */
+  /**
+   * Looks up all bindings registered for a given registry key (own + parent containers).
+   */
+  readonly lookup: (key: RegistryKey) => readonly Binding<unknown>[] | undefined;
+  /**
+   * Manages singleton/scoped instance caches and deactivation.
+   */
+  readonly scopeManager: ScopeManager;
+  /**
+   * Reads `@injectable()` and lifecycle metadata from constructors. Omit to disable decorator support.
+   */
   readonly metadataReader?: MetadataReader;
 };
 /**
- * Walks the binding graph, manages circular-dependency detection, delegates caching to
- * {@link ScopeManager}, and calls lifecycle hooks. Used exclusively by the container.
+ * Stateless graph walker: selects a binding, checks for cycles and scope violations,
+ * delegates instance caching to `ScopeManager`, and runs lifecycle hooks.
+ *
+ * Resolution algorithm (per token):
+ * 1. Lookup all bindings for the registry key.
+ * 2. Apply name/tag hint and `when()` constraint filtering.
+ * 3. Circular-dependency check via a mutable `visiting` set (per call tree).
+ * 4. Captive-dependency check via the `materializationStack`.
+ * 5. Scope-cache hit → return cached instance.
+ * 6. Scope-cache miss → `materialize` → `@postConstruct` → `onActivation` → cache.
+ *
+ * Used exclusively by `DefaultContainer`; not part of the public API.
  */
 declare class DependencyResolver {
   private readonly deps;
   constructor(deps: ResolverDependencies);
-  /** Entry point for synchronous single-binding resolution (no path prefix). */
+  /**
+   * Entry point for synchronous single-binding resolution.
+   *
+   * @throws {@link TokenNotBoundError} — no binding registered for `key`, or a nested dependency is unbound.
+   * @throws {@link NoMatchingBindingError} — a name/tag `hint` was given for `key` but no binding matched it.
+   * @throws {@link InternalError} — multiple bindings matched for `key` after applying the hint (ambiguous).
+   * @throws {@link CircularDependencyError} — `key` or a nested token appears twice on the resolution stack.
+   * @throws {@link AsyncResolutionError} — an `async-dynamic` binding or async lifecycle/activation on the sync path.
+   * @throws {@link ScopeViolationError} — captive dependency (singleton → scoped/transient).
+   * @throws {@link MissingMetadataError} — `class` binding lacks injectable metadata when the reader requires it.
+   */
   resolveRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value;
-  /** Entry point for async single-binding resolution (no path prefix). */
+  /**
+   * Entry point for async single-binding resolution. Awaits `async-dynamic` factories
+   * and async lifecycle hooks that would cause {@link AsyncResolutionError} on the sync path.
+   *
+   * @throws {@link TokenNotBoundError} — no binding registered for `key`, or a nested dependency is unbound.
+   * @throws {@link NoMatchingBindingError} — a name/tag `hint` was given for `key` but no binding matched it.
+   * @throws {@link InternalError} — multiple bindings matched for `key` after applying the hint (ambiguous).
+   * @throws {@link CircularDependencyError} — `key` or a nested token appears twice on the resolution stack.
+   * @throws {@link ScopeViolationError} — captive dependency (singleton → scoped/transient).
+   * @throws {@link MissingMetadataError} — `class` binding lacks injectable metadata when the reader requires it.
+   */
   resolveAsyncRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Promise<Value>;
-  /** Returns `undefined` instead of throwing when no binding is found; still throws on circular deps or async factories. */
+  /**
+   * Optional resolution for the **requested key only**: returns `undefined` when that key has no
+   * bindings or every candidate is filtered out **without** a name/tag hint — without throwing
+   * {@link TokenNotBoundError} for those cases. Instantiating the selected binding still runs the
+   * normal sync resolution path for nested dependencies; an unregistered transitive dependency
+   * throws {@link TokenNotBoundError} as usual.
+   *
+   * Behavioral rules:
+   * 1. If the registry key is completely unbound → returns `undefined`.
+   * 2. If no candidate survives constraint filtering (without a hint) → returns `undefined`.
+   * 3. If a name/tag hint was provided but no binding matches it → throws {@link NoMatchingBindingError}.
+   * 4. Still throws on: circular dependencies, async operations on the sync path,
+   *    scope violations, ambiguous multi-binding matches, and {@link TokenNotBoundError} when a
+   *    required nested dependency is unbound.
+   */
   resolveOptionalRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value | undefined;
-  /** Resolves all bindings for `key` synchronously; throws on async factories. */
+  /**
+   * Resolves every matching binding for `key` synchronously into an array.
+   * Returns an empty array when no bindings exist (does not throw).
+   *
+   * @throws {@link AsyncResolutionError} — any candidate is `async-dynamic`.
+   * @throws {@link NoMatchingBindingError} — hint was specified but no binding matched it.
+   * @throws {@link TokenNotBoundError} — nested dependency unbound (same as {@link resolveRoot}).
+   * @throws {@link CircularDependencyError} — cycle while materializing a candidate.
+   * @throws {@link ScopeViolationError} — captive dependency during materialization.
+   * @throws {@link MissingMetadataError} — class binding lacks injectable metadata when required.
+   */
   resolveAllRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value[];
-  /** Resolves all bindings for `key`, awaiting any async factories in the set. */
+  /**
+   * Async counterpart of {@link resolveAllRoot}: resolves every matching binding for `key`,
+   * awaiting `async-dynamic` factories. Returns an empty array when no bindings exist.
+   *
+   * @throws {@link NoMatchingBindingError} — hint was specified but no binding matched it.
+   * @throws {@link TokenNotBoundError} — nested dependency unbound (same as {@link resolveAsyncRoot}).
+   * @throws {@link CircularDependencyError} — cycle while materializing a candidate.
+   * @throws {@link ScopeViolationError} — captive dependency during materialization.
+   * @throws {@link MissingMetadataError} — class binding lacks injectable metadata when required.
+   */
   resolveAllAsyncRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Promise<Value[]>;
+  /**
+   * Context-aware sync `resolveAll`: extends the current resolution path and preserves
+   * visiting/materialization stacks so nested multi-resolution participates in cycle and
+   * captive-dependency checks exactly like single-value {@link resolve}.
+   */
+  private resolveAll;
+  /**
+   * Async counterpart of {@link resolveAll}: keeps the current path and materialization stack
+   * so `when()` constraints and scope validation behave consistently for nested multi-resolution.
+   */
+  private resolveAllAsync;
   /**
    * Assembles the read-only {@link ConstraintContext} snapshot passed to `when()` predicates.
    * Extracts the top-of-stack frame as `parent` and the rest as `ancestors`.
@@ -46,6 +131,9 @@ declare class DependencyResolver {
    */
   private createContext;
   /**
+   * Core synchronous resolution: lookup → filter → cycle check → scope check → instantiate.
+   * Called recursively when a binding's dependencies need resolution.
+   *
    * @param key - Token or constructor being resolved.
    * @param hint - Optional name/tag filter for multi-binding selection.
    * @param pathLabels - Mutable label path accumulated during graph walk; extended in place.
@@ -54,6 +142,9 @@ declare class DependencyResolver {
    */
   private resolve;
   /**
+   * Core async resolution: same pipeline as {@link resolve} but awaits `async-dynamic`
+   * factories and async lifecycle hooks instead of throwing {@link AsyncResolutionError}.
+   *
    * @param key - Token or constructor being resolved.
    * @param hint - Optional name/tag filter for multi-binding selection.
    * @param pathLabels - Mutable label path accumulated during graph walk; extended in place.
@@ -77,8 +168,12 @@ declare class DependencyResolver {
    */
   private assertCaptiveDependencyFromMaterializationStack;
   /**
-   * Synchronously produces the raw instance for a binding without touching the scope cache.
-   * Dispatches on `binding.kind`; throws {@link AsyncResolutionError} for `async-dynamic` factories.
+   * Synchronously produces the raw instance for a binding **without** touching the scope cache
+   * or running lifecycle hooks. The caller ({@link instantiateBinding}) wraps this with
+   * cache logic and post-construction hooks.
+   *
+   * Dispatches on `binding.kind`; throws {@link AsyncResolutionError} if the binding is
+   * `async-dynamic` or if a `dynamic` / `resolved` factory returns a Promise.
    */
   private materialize;
   /**