@codefast/di 0.3.13 → 0.3.14-canary.1

package/dist/decorators/inject.mjs

@@ -1,7 +1,9 @@
 import { InternalError } from "../errors.mjs";
 import { CODEFAST_DI_ACCESSOR_INJECTIONS } from "../metadata/metadata-keys.mjs";
 //#region src/decorators/inject.ts
-/** Validates and normalises the `tag` option from {@link InjectOptions}; throws {@link InternalError} on bad input. */
+/**
+* Validates and normalises the `tag` option from {@link InjectOptions}; throws {@link InternalError} on bad input.
+*/
 function normalizeTag(tag) {
 	if (tag === void 0) return;
 	if (!Array.isArray(tag) || tag.length !== 2) throw new InternalError(`@inject tag must be a tuple [tagKey, value] with length 2; received ${String(tag)}`);
@@ -9,7 +11,9 @@ function normalizeTag(tag) {
 	if (typeof tagName !== "string") throw new InternalError(`@inject tag key must be a string; received ${typeof tagName}`);
 	return [tagName, value];
 }
-/** Builds an {@link InjectionDescriptor} from a token, optional flag, and raw inject options. */
+/**
+* Builds an {@link InjectionDescriptor} from a token, optional flag, and raw inject options.
+*/
 function toDescriptor(token, optional, options) {
 	const normalizedTag = normalizeTag(options?.tag);
 	if (options?.name !== void 0) return {
@@ -27,16 +31,34 @@ function toDescriptor(token, optional, options) {
 		optional
 	};
 }
-/** Type guard — returns `true` when `value` is a TC39 `ClassAccessorDecoratorContext` (accessor field). */
+/**
+* Type guard — returns `true` when `value` is a TC39 `ClassAccessorDecoratorContext` (accessor field).
+*/
 function isAccessorDecoratorContext(value) {
 	return typeof value === "object" && value !== null && "kind" in value && value.kind === "accessor";
 }
 /**
-* Creates an {@link InjectionDescriptor} for use in an `@injectable(deps)` array, or as an
-* `accessor` field decorator for post-construction property injection.
+* Dual-purpose injection helper:
+*
+* **1. As a deps-array entry** — returns an {@link InjectionDescriptor} carrying the token,
+* optional flag (`false`), and any name/tag hint. Used inside `@injectable([...deps])`.
+*
+* ```ts
+* @injectable([inject(Logger, { name: 'file' })])
+* class UserService { constructor(log: Logger) {} }
+* ```
+*
+* **2. As a Stage 3 accessor decorator** — writes accessor-injection metadata into
+* `Symbol.metadata` and returns a no-op sentinel. The container performs the actual
+* injection after construction.
 *
-* As a deps-array entry: `@injectable([inject(Logger, { name: 'file' })])`
-* As an accessor decorator: `@inject(Logger) accessor logger!: LoggerService`
+* ```ts
+* @inject(Logger) accessor logger!: LoggerService;
+* ```
+*
+* @param token - The injection key (token or constructor) to resolve.
+* @param optionsOrContext - Either an {@link InjectOptions} hint or the TC39
+*   `ClassAccessorDecoratorContext` automatically supplied by the runtime.
 */
 function inject(token, optionsOrContext) {
 	if (isAccessorDecoratorContext(optionsOrContext)) {
@@ -54,16 +76,33 @@ function inject(token, optionsOrContext) {
 	return toDescriptor(token, false, optionsOrContext);
 }
 /**
-* Same as {@link inject} but marks the dependency as optional — resolves to `undefined` instead
-* of throwing {@link TokenNotBoundError} when no binding exists.
+* Same as {@link inject} but marks the dependency as optional (`InjectionDescriptor.optional = true`).
+* During resolution, an unbound token resolves to `undefined` instead of throwing
+* {@link TokenNotBoundError}. Only usable as a deps-array entry (not as an accessor decorator).
 */
 function optional(token, options) {
 	return toDescriptor(token, true, options);
 }
-/** Type-guard — returns `true` when `value` is an {@link InjectionDescriptor}. */
+/**
+* Deps-array helper for `@injectable()`: injects **all** bindings registered for `token`
+* (same semantics as {@link Container.resolveAll} / {@link ResolutionContext.resolveAll}).
+* Use for multi-binding — constructor parameter type should be `T[]` (or a readonly array).
+*
+* Optional {@link InjectOptions.name} / `tag` narrow which bindings are collected (unusual; most
+* callers omit options and register disambiguators on each binding instead).
+*/
+function injectAll(token, options) {
+	return {
+		...toDescriptor(token, false, options),
+		all: true
+	};
+}
+/**
+* Type-guard — returns `true` when `value` is an {@link InjectionDescriptor}.
+*/
 function isInjectionDescriptor(value) {
 	if (typeof value !== "object" || value === null) return false;
 	return "token" in value && "optional" in value;
 }
 //#endregion
-export { inject, isInjectionDescriptor, optional };
+export { inject, injectAll, isInjectionDescriptor, optional };

package/dist/decorators/injectable.d.mts

@@ -6,7 +6,8 @@ import { InjectionDescriptor } from "../metadata/metadata-types.mjs";
 /**
  * A single entry in the `deps` array passed to `@injectable()`.
  * Can be a plain token/constructor (resolved with no hint) or an {@link InjectionDescriptor}
- * produced by {@link inject} / {@link optional} when name, tag, or optional semantics are needed.
+ * produced by `inject` / `optional` / `injectAll` when name, tag, optional, or resolve-all
+ * semantics are needed.
  */
 type InjectableDependency = Token<unknown> | Constructor<unknown> | InjectionDescriptor<unknown>;
 /**

package/dist/decorators/injectable.mjs

@@ -2,6 +2,11 @@ import { InternalError } from "../errors.mjs";
 import { CODEFAST_DI_CONSTRUCTOR_METADATA } from "../metadata/metadata-keys.mjs";
 import { isInjectionDescriptor } from "./inject.mjs";
 //#region src/decorators/injectable.ts
+/**
+* Global mutable registry of classes decorated with `@injectable({ autoRegister: true })`.
+* Populated at class-definition time (via `context.addInitializer`), drained by
+* {@link Container.loadAutoRegistered}. Entries accumulate for the lifetime of the process.
+*/
 const AUTO_REGISTER_REGISTRY = [];
 /**
 * Returns all classes decorated with `@injectable({ autoRegister: true })`.
@@ -10,14 +15,21 @@ const AUTO_REGISTER_REGISTRY = [];
 function getAutoRegistered() {
 	return AUTO_REGISTER_REGISTRY;
 }
-/** Converts a single `@injectable` deps-array entry into a {@link ParamMetadata} record. */
+/**
+* Normalises a single `@injectable` deps-array entry into the uniform {@link ParamMetadata}
+* shape used by the resolver's constructor-instantiation path.
+*
+* - {@link InjectionDescriptor} entries carry `optional`, `name`, and `tag` fields.
+* - Plain token / constructor entries are wrapped with `optional: false` and no hint.
+*/
 function toParamMetadata(dependency, index) {
 	if (isInjectionDescriptor(dependency)) return {
 		index,
 		token: dependency.token,
 		optional: dependency.optional,
 		name: dependency.name,
-		tag: dependency.tag
+		tag: dependency.tag,
+		all: dependency.all === true ? true : void 0
 	};
 	return {
 		index,

package/dist/decorators/lifecycle-decorators.d.mts

@@ -1,12 +1,24 @@
 //#region src/decorators/lifecycle-decorators.d.ts
 /**
- * Stage 3 method decorator: marks a method to be called after the class is instantiated by the container.
- * Order: construct → `@postConstruct()` → `.onActivation()` → cache.
+ * Stage 3 method decorator: marks a method to be called after the class is instantiated
+ * by the container and before the `onActivation` hook runs.
+ *
+ * Lifecycle order: `new Class(…)` → **`@postConstruct()`** → `onActivation()` → scope cache.
+ *
+ * Only one method per class may carry this decorator; a second application throws.
+ * If the decorated method returns a `Promise` during synchronous resolution,
+ * {@link AsyncResolutionError} is thrown — use `Container.resolveAsync()` instead.
  */
 declare function postConstruct(): (target: () => unknown, context: ClassMethodDecoratorContext) => void;
 /**
- * Stage 3 method decorator: marks a method to be called before the instance is destroyed by the container.
- * Order: `.onDeactivation()` → `@preDestroy()`.
+ * Stage 3 method decorator: marks a method to be called when the container disposes or
+ * unloads the owning binding.
+ *
+ * Lifecycle order: `onDeactivation()` → **`@preDestroy()`**.
+ *
+ * Only one method per class may carry this decorator; a second application throws.
+ * If the decorated method returns a `Promise` during synchronous disposal,
+ * an error is thrown — use `Container.disposeAsync()` instead.
  */
 declare function preDestroy(): (target: () => unknown, context: ClassMethodDecoratorContext) => void;
 //#endregion

package/dist/decorators/lifecycle-decorators.mjs

@@ -1,8 +1,14 @@
 import { CODEFAST_DI_LIFECYCLE_METADATA } from "../metadata/metadata-keys.mjs";
 //#region src/decorators/lifecycle-decorators.ts
 /**
-* Stage 3 method decorator: marks a method to be called after the class is instantiated by the container.
-* Order: construct → `@postConstruct()` → `.onActivation()` → cache.
+* Stage 3 method decorator: marks a method to be called after the class is instantiated
+* by the container and before the `onActivation` hook runs.
+*
+* Lifecycle order: `new Class(…)` → **`@postConstruct()`** → `onActivation()` → scope cache.
+*
+* Only one method per class may carry this decorator; a second application throws.
+* If the decorated method returns a `Promise` during synchronous resolution,
+* {@link AsyncResolutionError} is thrown — use `Container.resolveAsync()` instead.
 */
 function postConstruct() {
 	return (_target, context) => {
@@ -16,8 +22,14 @@ function postConstruct() {
 	};
 }
 /**
-* Stage 3 method decorator: marks a method to be called before the instance is destroyed by the container.
-* Order: `.onDeactivation()` → `@preDestroy()`.
+* Stage 3 method decorator: marks a method to be called when the container disposes or
+* unloads the owning binding.
+*
+* Lifecycle order: `onDeactivation()` → **`@preDestroy()`**.
+*
+* Only one method per class may carry this decorator; a second application throws.
+* If the decorated method returns a `Promise` during synchronous disposal,
+* an error is thrown — use `Container.disposeAsync()` instead.
 */
 function preDestroy() {
 	return (_target, context) => {

package/dist/dependency-graph.d.mts

@@ -3,27 +3,50 @@ import { Binding, BindingIdentifier, ResolveHint } from "./binding.mjs";
 import { MetadataReader } from "./metadata/metadata-types.mjs";
 
 //#region src/dependency-graph.d.ts
-/** A directed edge in the static dependency graph produced by {@link collectStaticDependencyEdges}. */
+/**
+ * A directed edge in the static dependency graph produced by {@link collectStaticDependencyEdges}.
+ */
 type StaticDependencyEdge = {
-  readonly fromBindingId: BindingIdentifier;
-  readonly toBindingId: BindingIdentifier;
-  readonly resolutionPath: readonly string[];
-  readonly edgeKind: "sync" | "async"; /** True when the resolved target binding carries a {@link BindingBuilder.when} predicate (runtime may skip this edge). */
-  readonly toBindingConditional: boolean; /** Constructor inject hint for this edge (named / tagged), when known statically. */
-  readonly injectHintLabel?: string; /** True when the consumer binding is an alias (rebind to another token). */
+  /** Binding id of the consumer node (edge source). */readonly fromBindingId: BindingIdentifier; /** Binding id of the dependency node (edge target). */
+  readonly toBindingId: BindingIdentifier; /** Resolution labels leading to this edge. */
+  readonly resolutionPath: readonly string[]; /** Edge execution kind inferred from binding strategies. */
+  readonly edgeKind: "sync" | "async";
+  /**
+   * True when the resolved target binding carries a {@link BindingBuilder.when} predicate (runtime may skip this edge).
+   */
+  readonly toBindingConditional: boolean;
+  /**
+   * Constructor inject hint for this edge (named / tagged), when known statically.
+   */
+  readonly injectHintLabel?: string;
+  /**
+   * True when the consumer binding is an alias (rebind to another token).
+   */
   readonly isAliasEdge: boolean;
 };
-/** A single resolved dependency entry produced by {@link listResolvedDependencies}. */
+/**
+ * A single resolved dependency entry produced by {@link listResolvedDependencies}.
+ */
 type ResolvedDependency = {
-  readonly binding: Binding<unknown>;
-  readonly path: readonly string[];
+  /** Effective dependency binding selected for this edge. */readonly binding: Binding<unknown>; /** Resolution labels from consumer to dependency. */
+  readonly path: readonly string[]; /** Optional name/tag label shown in graph outputs. */
   readonly injectHintLabel?: string;
 };
-/** Converts a {@link ResolveHint} to a human-readable edge label for graph output (`name: x` / `tag: k=v`). */
+/**
+ * Converts a {@link ResolveHint} to a human-readable edge label for graph output (`name: x` / `tag: k=v`).
+ */
 declare function injectHintLabelFromResolveHint(hint: ResolveHint | undefined): string | undefined;
 /**
- * Lists direct static dependencies (constructor metadata, `toResolved` tokens, alias targets).
- * Factories (`toDynamic` / `toAsyncDynamic`) have no enumerable dependency keys.
+ * Lists the direct static dependencies of `consumer` by inspecting binding metadata.
+ *
+ * - `constant` / `dynamic` / `async-dynamic` — no enumerable deps (empty array).
+ * - `alias` — single dependency on the alias target (chased through alias chains).
+ * - `resolved` — one dependency per entry in `dependencyTokens`; a missing binding
+ *   always throws {@link InternalError} (there is no optional concept for `resolved`).
+ * - `class` — one dependency per `@injectable()` constructor parameter
+ *   (requires a {@link MetadataReader}). Parameters marked `optional` whose token
+ *   has no binding are silently skipped; non-optional missing tokens throw
+ *   {@link InternalError}.
  */
 declare function listResolvedDependencies(consumer: Binding<unknown>, lookup: (key: RegistryKey) => readonly Binding<unknown>[] | undefined, reader: MetadataReader | undefined, pathPrefix: readonly string[]): readonly ResolvedDependency[];
 /**

package/dist/dependency-graph.mjs

@@ -1,7 +1,9 @@
 import { InternalError } from "./errors.mjs";
-import { registryKeyLabel, selectBindingForRegistry } from "./binding-select.mjs";
+import { filterMatchingBindings, registryKeyLabel, selectBindingForRegistry } from "./binding-select.mjs";
 //#region src/dependency-graph.ts
-/** Converts a tag value to a printable string for graph edge labels. */
+/**
+* Converts a tag value to a printable string for graph edge labels.
+*/
 function formatTagValueForGraph(value) {
 	if (typeof value === "string") return value;
 	try {
@@ -10,7 +12,9 @@ function formatTagValueForGraph(value) {
 		return String(value);
 	}
 }
-/** Converts a {@link ResolveHint} to a human-readable edge label for graph output (`name: x` / `tag: k=v`). */
+/**
+* Converts a {@link ResolveHint} to a human-readable edge label for graph output (`name: x` / `tag: k=v`).
+*/
 function injectHintLabelFromResolveHint(hint) {
 	if (hint === void 0) return;
 	if (hint.name !== void 0) return `name: ${hint.name}`;
@@ -19,7 +23,9 @@ function injectHintLabelFromResolveHint(hint) {
 		return `tag: ${tagKey}=${formatTagValueForGraph(tagValue)}`;
 	}
 }
-/** Returns `"async"` when either the consumer or dependency binding is an `async-dynamic` factory. */
+/**
+* Returns `"async"` when either the consumer or dependency binding is an `async-dynamic` factory.
+*/
 function edgeKindFor(consumer, dependency) {
 	if (consumer.kind === "async-dynamic" || dependency.kind === "async-dynamic") return "async";
 	return "sync";
@@ -37,7 +43,13 @@ function resolveDefaultBinding(lookup, depKey, pathPrefix) {
 }
 /**
 * Follows alias bindings until a non-alias binding is reached.
-* Returns the last reachable binding; stops if an alias target is unregistered.
+* Returns the last reachable binding; stops early if an alias target is unregistered.
+*
+* **Warning:** This is a static walk with no cycle detection (`visiting` set). If the
+* registry contains a cyclic alias chain (A → B → A), this function will loop
+* indefinitely. The runtime resolver prevents such cycles via its own `visiting`
+* guard, but callers invoking `expandAliasChain` on a manually-constructed or
+* corrupted registry must ensure alias chains are acyclic.
 */
 function expandAliasChain(lookup, start, pathPrefix) {
 	let current = start;
@@ -52,8 +64,16 @@ function expandAliasChain(lookup, start, pathPrefix) {
 	return current;
 }
 /**
-* Lists direct static dependencies (constructor metadata, `toResolved` tokens, alias targets).
-* Factories (`toDynamic` / `toAsyncDynamic`) have no enumerable dependency keys.
+* Lists the direct static dependencies of `consumer` by inspecting binding metadata.
+*
+* - `constant` / `dynamic` / `async-dynamic` — no enumerable deps (empty array).
+* - `alias` — single dependency on the alias target (chased through alias chains).
+* - `resolved` — one dependency per entry in `dependencyTokens`; a missing binding
+*   always throws {@link InternalError} (there is no optional concept for `resolved`).
+* - `class` — one dependency per `@injectable()` constructor parameter
+*   (requires a {@link MetadataReader}). Parameters marked `optional` whose token
+*   has no binding are silently skipped; non-optional missing tokens throw
+*   {@link InternalError}.
 */
 function listResolvedDependencies(consumer, lookup, reader, pathPrefix) {
 	switch (consumer.kind) {
@@ -90,6 +110,20 @@ function listResolvedDependencies(consumer, lookup, reader, pathPrefix) {
 				const tok = param.token;
 				const label = registryKeyLabel(tok);
 				const nextPath = [...pathPrefix, label];
+				const paramHint = param.name !== void 0 ? { name: param.name } : param.tag !== void 0 ? { tag: param.tag } : void 0;
+				if (param.all === true) {
+					const bindings = lookup(tok);
+					if (bindings === void 0 || bindings.length === 0) return [];
+					const candidates = filterMatchingBindings(bindings, paramHint, void 0);
+					if (candidates.length === 0) return [];
+					return candidates.map((binding) => {
+						return {
+							binding: expandAliasChain(lookup, binding, nextPath),
+							path: nextPath,
+							injectHintLabel: injectHintLabelFromResolveHint(paramHint)
+						};
+					});
+				}
 				const binding = resolveDefaultBinding(lookup, tok, pathPrefix);
 				if (binding === void 0) {
 					if (param.optional) return [];
@@ -98,7 +132,7 @@ function listResolvedDependencies(consumer, lookup, reader, pathPrefix) {
 				return [{
 					binding: expandAliasChain(lookup, binding, nextPath),
 					path: nextPath,
-					injectHintLabel: injectHintLabelFromResolveHint(param.name !== void 0 ? { name: param.name } : param.tag !== void 0 ? { tag: param.tag } : void 0)
+					injectHintLabel: injectHintLabelFromResolveHint(paramHint)
 				}];
 			});
 		}

package/dist/errors.d.mts

@@ -2,88 +2,199 @@ import { Binding, BindingIdentifier, BindingScope, ResolveHint } from "./binding
 
 //#region src/errors.d.ts
 /**
- * Base error for all `@codefast/di` failures. Subclasses expose a stable, machine-readable `code`.
+ * Formats a resolution path array into a human-readable `"A -> B -> C"` string.
+ */
+declare function formatResolutionPath(resolutionPath: readonly string[]): string;
+/**
+ * Base error for all `@codefast/di` failures.
+ *
+ * Every concrete subclass exposes a stable, machine-readable {@link DiError.code} property
+ * (e.g. `"TOKEN_NOT_BOUND"`) so consumers can `switch` on error type without relying
+ * on `instanceof` across package versions.
  */
 declare abstract class DiError extends Error {
+  /**
+   * Machine-readable error code, constant per subclass (e.g. `"TOKEN_NOT_BOUND"`).
+   */
   abstract readonly code: string;
   constructor(message: string, options?: ErrorOptions);
 }
 /**
  * Raised for internal programming errors — invalid library usage or unexpected state that
- * indicates a bug in the caller (e.g. accessing an uninitialized container, misconfigured binding).
+ * indicates a bug in the caller or the library itself.
+ *
+ * Examples: double `to*()` call on a {@link BindingBuilder}, ambiguous binding resolution
+ * with multiple candidates, or scope mutation on a constant binding.
+ *
+ * Code: `"INTERNAL_ERROR"`
  */
 declare class InternalError extends DiError {
   readonly code = "INTERNAL_ERROR";
 }
 /**
- * Raised when a name/tag filter matches no binding although other bindings exist for the token.
+ * Raised when bindings exist for the token but none match the provided name/tag hint.
+ * Distinguishes from {@link TokenNotBoundError} (no bindings at all).
+ *
+ * Thrown when a `{ name }` or `{ tag }` hint is specified but no registered binding satisfies it
+ * (e.g. `Container.resolve`, `Container.resolveAsync`, `Container.resolveOptional`,
+ * `Container.resolveAll`, `Container.resolveAllAsync`, and binding selection helpers such as
+ * {@link selectBindingForRegistry}).
+ *
+ * Code: `"NO_MATCHING_BINDING"`
  */
 declare class NoMatchingBindingError extends DiError {
   readonly code = "NO_MATCHING_BINDING";
+  /**
+   * The `Token.name` or `Constructor.name` that was resolved.
+   */
   readonly tokenName: string;
+  /**
+   * The name/tag hint that failed to match any binding.
+   */
   readonly hint: ResolveHint;
+  /**
+   * Label path from the resolution root to the failing token.
+   */
   readonly resolutionPath: readonly string[];
   constructor(tokenName: string, hint: ResolveHint, resolutionPath: readonly string[], options?: ErrorOptions);
 }
 /**
- * Raised when resolving a value for a token that has no binding.
+ * Raised when no binding exists for the requested token or constructor.
+ *
+ * Thrown by `Container.resolve`, `Container.resolveAsync`, and during transitive
+ * dependency resolution when a required token has never been registered.
+ *
+ * Note on optional resolution:
+ * - Root-level `Container.resolveOptional` returns `undefined` when **that key** has no
+ *   registry entries (it never throws this error for the root key in that case). Missing
+ *   **transitive** dependencies still throw during instantiation.
+ * - `ResolutionContext.resolveOptional` (used inside factories) catches this error
+ *   internally to return `undefined` for missing dependencies.
+ *
+ * Code: `"TOKEN_NOT_BOUND"`
  */
 declare class TokenNotBoundError extends DiError {
   readonly code = "TOKEN_NOT_BOUND";
+  /**
+   * The `Token.name` or `Constructor.name` that could not be found.
+   */
   readonly tokenName: string;
+  /**
+   * Label path from the resolution root to the missing token.
+   */
   readonly resolutionPath: readonly string[];
   constructor(tokenName: string, resolutionPath: readonly string[], options?: ErrorOptions);
 }
 /**
- * Raised when the dependency graph contains a cycle during resolution.
+ * Raised when a token is encountered a second time on the same resolution call stack,
+ * indicating a cyclic dependency (A → B → … → A).
+ *
+ * Also raised during module loading when `import()` forms a cycle between modules.
+ *
+ * Code: `"CIRCULAR_DEPENDENCY"`
  */
 declare class CircularDependencyError extends DiError {
   readonly code = "CIRCULAR_DEPENDENCY";
+  /**
+   * Full label path including the repeated token at the end.
+   */
   readonly resolutionPath: readonly string[];
+  /**
+   * Mutable copy of {@link resolutionPath} for consumer convenience.
+   */
   readonly cycle: string[];
   constructor(resolutionPath: readonly string[], options?: ErrorOptions);
 }
 /**
- * Raised when a class binding requires `@injectable()` / `Symbol.metadata` constructor metadata but none is present.
+ * Raised when the container's {@link MetadataReader} is **configured** and reports no
+ * constructor metadata for a `class` binding whose implementation has `arity > 0`.
+ *
+ * If `metadataReader` is `undefined`, the resolver calls `new ImplementationClass()` without
+ * this check — this error is **not** thrown in that configuration.
+ *
+ * Fix: add `@injectable([...deps])` on the class (so `getConstructorMetadata` returns params),
+ * or omit constructor parameters if you intentionally run without a reader.
+ *
+ * Code: `"MISSING_METADATA"`
  */
 declare class MissingMetadataError extends DiError {
   readonly code = "MISSING_METADATA";
+  /**
+   * Name of the class that is missing `@injectable()` metadata.
+   */
   readonly className: string;
+  /**
+   * Label path from the resolution root to the class binding.
+   */
   readonly resolutionPath: readonly string[];
   constructor(className: string, resolutionPath: readonly string[], options?: ErrorOptions);
 }
-/** Raised when `load()` is used with an async module. */
+/**
+ * Raised when the synchronous `Container.load()` is called with an {@link AsyncModule}.
+ * Use `Container.loadAsync()` or `Container.fromModulesAsync()` instead.
+ *
+ * Code: `"ASYNC_MODULE_LOAD"`
+ */
 declare class AsyncModuleLoadError extends DiError {
   readonly code = "ASYNC_MODULE_LOAD";
+  /**
+   * Name of the async module that was passed to the sync loader.
+   */
   readonly moduleName: string;
   constructor(moduleName: string, options?: ErrorOptions);
 }
 /**
- * Raised when `resolve()` is called on a binding chain that contains an async factory or
- * an async `onActivation` handler. Use `resolveAsync()` / `resolveAllAsync()` instead.
+ * Raised when synchronous `Container.resolve()` / `Container.resolveAll()` encounters an
+ * async operation: an `async-dynamic` factory, a `toDynamic` factory that returns a Promise,
+ * an `onActivation` handler that returns a Promise, or a `@postConstruct` method that
+ * returns a Promise.
+ *
+ * Fix: switch to `Container.resolveAsync()` / `Container.resolveAllAsync()`.
+ *
+ * Code: `"ASYNC_RESOLUTION"`
  */
 declare class AsyncResolutionError extends DiError {
   readonly code = "ASYNC_RESOLUTION";
+  /**
+   * Token or class name that triggered the async path.
+   */
   readonly tokenName: string;
+  /**
+   * Label path from the resolution root to the async binding.
+   */
   readonly resolutionPath: readonly string[];
+  /**
+   * Human-readable description of why async resolution was required.
+   */
   readonly reason: string;
   constructor(tokenName: string, resolutionPath: readonly string[], reason: string, options?: ErrorOptions);
 }
-/** Structured payload attached to {@link ScopeViolationError}. */
+/**
+ * Structured payload passed to the {@link ScopeViolationError} constructor.
+ * Carries identities and scopes of both the long-lived consumer and the shorter-lived dependency.
+ */
 type ScopeViolationDetails = {
-  readonly consumerBindingId: BindingIdentifier;
-  readonly consumerKind: Binding<unknown>["kind"];
-  readonly consumerScope: BindingScope;
-  readonly consumerLabel?: string;
-  readonly dependencyBindingId: BindingIdentifier;
-  readonly dependencyKind: Binding<unknown>["kind"];
-  readonly dependencyScope: BindingScope;
-  readonly dependencyLabel?: string;
+  /** Binding id of the long-lived consumer (typically singleton). */readonly consumerBindingId: BindingIdentifier; /** Binding strategy kind of the consumer. */
+  readonly consumerKind: Binding<unknown>["kind"]; /** Scope of the consumer binding. */
+  readonly consumerScope: BindingScope; /** Optional display label for consumer in error messages. */
+  readonly consumerLabel?: string; /** Binding id of the shorter-lived dependency. */
+  readonly dependencyBindingId: BindingIdentifier; /** Binding strategy kind of the dependency. */
+  readonly dependencyKind: Binding<unknown>["kind"]; /** Scope of the dependency binding. */
+  readonly dependencyScope: BindingScope; /** Optional display label for dependency in error messages. */
+  readonly dependencyLabel?: string; /** Resolution path captured at the violation point. */
   readonly resolutionPath: readonly string[];
 };
 /**
- * Raised when a long-lived binding would capture a shorter-lived (scoped or transient) dependency
- * (captive dependency). Constant value dependencies are excluded.
+ * Raised for a **captive dependency**: a singleton consumer resolves (or would resolve) a
+ * non-constant binding whose lifetime is `scoped` or `transient`. Constant bindings are exempt.
+ *
+ * - **Runtime:** each resolution step checks the parent on the materialization stack, so
+ *   violations are detected along the actual construction chain.
+ * - **`Container.validate()`:** {@link validateScopeRules} walks **direct** static edges from
+ *   {@link listResolvedDependencies} only — it does not recursively expand the whole graph,
+ *   so it may miss violations that appear only deeper in the dependency tree.
+ *
+ * Code: `"SCOPE_VIOLATION"`
  */
 declare class ScopeViolationError extends DiError {
   readonly code = "SCOPE_VIOLATION";
@@ -97,4 +208,4 @@ declare class ScopeViolationError extends DiError {
   constructor(details: ScopeViolationDetails, options?: ErrorOptions);
 }
 //#endregion
-export { AsyncModuleLoadError, AsyncResolutionError, CircularDependencyError, DiError, InternalError, MissingMetadataError, NoMatchingBindingError, ScopeViolationDetails, ScopeViolationError, TokenNotBoundError };
+export { AsyncModuleLoadError, AsyncResolutionError, CircularDependencyError, DiError, InternalError, MissingMetadataError, NoMatchingBindingError, ScopeViolationDetails, ScopeViolationError, TokenNotBoundError, formatResolutionPath };