@codefast/di 0.3.13-canary.4

package/dist/module.mjs

@@ -0,0 +1,57 @@
+//#region src/module.ts
+/**
+* Immutable description of a bundle of bindings. A {@link Module} holds no runtime state and the
+* same instance may be loaded into any number of containers independently (spec §7.3).
+*
+* The owning container is responsible for tracking which modules have been loaded and which
+* binding ids each module produced; the module itself never sees a container reference.
+*/
+var Module = class Module {
+	name;
+	syncSetup;
+	constructor(name, syncSetup) {
+		this.name = name;
+		this.syncSetup = syncSetup;
+	}
+	/**
+	* Defines a synchronous module.
+	* @param name - Human-readable label used in error messages and debug output.
+	* @param setup - Callback that registers bindings via the {@link ModuleBuilder}.
+	*/
+	static create(name, setup) {
+		return new Module(name, setup);
+	}
+	/**
+	* Defines an async module — use when setup requires awaiting (e.g. reading config, dynamic imports).
+	* Load with {@link Container.loadAsync} or {@link Container.fromModulesAsync}.
+	*/
+	static createAsync(name, setup) {
+		return new AsyncModule(name, setup);
+	}
+	/**
+	* @internal Invoked by the container while loading this module.
+	*/
+	runSyncSetup(builder) {
+		this.syncSetup(builder);
+	}
+};
+/**
+* An async module whose setup callback may `await` before registering bindings.
+* Prefer {@link Module.createAsync} over constructing this class directly.
+*/
+var AsyncModule = class {
+	name;
+	asyncSetup;
+	constructor(name, asyncSetup) {
+		this.name = name;
+		this.asyncSetup = asyncSetup;
+	}
+	/**
+	* @internal Invoked by the container while loading this module.
+	*/
+	async runAsyncSetup(builder) {
+		await this.asyncSetup(builder);
+	}
+};
+//#endregion
+export { AsyncModule, Module };

package/dist/registry.d.mts

@@ -0,0 +1,38 @@
+import { Token } from "./token.mjs";
+import { Binding, BindingIdentifier, Constructor } from "./binding.mjs";
+
+//#region src/registry.d.ts
+/**
+ * Key used to group {@link Binding} instances in the registry (reference equality for tokens).
+ */
+type RegistryKey = Token<unknown> | Constructor<unknown>;
+/**
+ * Dumb storage for bindings keyed by token or constructor. Selection and construction logic live elsewhere.
+ */
+declare class BindingRegistry {
+  private readonly bindingsByKey;
+  /** 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. */
+  get<Value>(key: Token<Value> | Constructor<Value>): readonly Binding<Value>[] | undefined;
+  /** Removes all bindings for `key` without running any deactivation hooks. */
+  remove(key: RegistryKey): void;
+  /**
+   * Returns owned registry rows (does not include parent containers).
+   */
+  listEntries(): readonly {
+    key: RegistryKey;
+    bindings: readonly Binding<unknown>[];
+  }[];
+  /** Removes the single binding with the given `id` across all keys. */
+  removeById(id: BindingIdentifier): void;
+  /** 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.
+   */
+  replaceKeyLastWins<Value>(key: Token<Value> | Constructor<Value>, binding: Binding<Value>, onReplaced: (removed: Binding<unknown>) => void): void;
+}
+//#endregion
+export { BindingRegistry, RegistryKey };

package/dist/registry.mjs

@@ -0,0 +1,65 @@
+//#region src/registry.ts
+/**
+* Dumb storage for bindings keyed by token or constructor. Selection and construction logic live elsewhere.
+*/
+var BindingRegistry = class {
+	bindingsByKey = /* @__PURE__ */ new Map();
+	/** Appends `binding` to the list for `key` (multi-binding: each call adds an entry). */
+	add(key, binding) {
+		const registryKey = key;
+		const nextBinding = binding;
+		const existing = this.bindingsByKey.get(registryKey);
+		const merged = existing === void 0 ? [nextBinding] : [...existing, nextBinding];
+		this.bindingsByKey.set(registryKey, merged);
+	}
+	/** 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. */
+	remove(key) {
+		this.bindingsByKey.delete(key);
+	}
+	/**
+	* Returns owned registry rows (does not include parent containers).
+	*/
+	listEntries() {
+		return [...this.bindingsByKey.entries()].map(([key, bindings]) => ({
+			key,
+			bindings
+		}));
+	}
+	/** Removes the single binding with the given `id` across all keys. */
+	removeById(id) {
+		for (const [registryKey, list] of [...this.bindingsByKey.entries()]) {
+			const filtered = list.filter((binding) => binding.id !== id);
+			if (filtered.length === list.length) continue;
+			if (filtered.length === 0) this.bindingsByKey.delete(registryKey);
+			else this.bindingsByKey.set(registryKey, filtered);
+		}
+	}
+	/** 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);
+			if (index === -1) continue;
+			const updated = [...list];
+			updated[index] = next;
+			this.bindingsByKey.set(registryKey, updated);
+			return;
+		}
+	}
+	/**
+	* Replaces all bindings for `key` with a single binding (module "last-wins" semantics).
+	* Invokes `onReplaced` for every removed binding so scopes can run deactivation.
+	*/
+	replaceKeyLastWins(key, binding, onReplaced) {
+		const registryKey = key;
+		const nextBinding = binding;
+		const existing = this.bindingsByKey.get(registryKey);
+		if (existing !== void 0) for (const removed of existing) onReplaced(removed);
+		this.bindingsByKey.set(registryKey, [nextBinding]);
+	}
+};
+//#endregion
+export { BindingRegistry };

package/dist/resolver.d.mts

@@ -0,0 +1,102 @@
+import { Token } from "./token.mjs";
+import { RegistryKey } from "./registry.mjs";
+import { Binding, Constructor, ResolveHint } from "./binding.mjs";
+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. */
+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. */
+  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.
+ */
+declare class DependencyResolver {
+  private readonly deps;
+  constructor(deps: ResolverDependencies);
+  /** Entry point for synchronous single-binding resolution (no path prefix). */
+  resolveRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value;
+  /** Entry point for async single-binding resolution (no path prefix). */
+  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. */
+  resolveOptionalRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value | undefined;
+  /** Resolves all bindings for `key` synchronously; throws on async factories. */
+  resolveAllRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value[];
+  /** Resolves all bindings for `key`, awaiting any async factories in the set. */
+  resolveAllAsyncRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Promise<Value[]>;
+  /**
+   * Assembles the read-only {@link ConstraintContext} snapshot passed to `when()` predicates.
+   * Extracts the top-of-stack frame as `parent` and the rest as `ancestors`.
+   */
+  private buildConstraintContext;
+  /**
+   * Throws {@link ScopeViolationError} when the immediate consumer on the stack is a singleton
+   * and the dependency has `"scoped"` or `"transient"` lifetime (captive dependency).
+   * Constants are exempt — they have no scope cache.
+   */
+  private assertDependencyScopeAllowed;
+  /**
+   * Builds a {@link ResolutionContext} for use inside factories and lifecycle hooks.
+   * The `resolve` / `resolveAsync` / `resolveOptional` closures carry the current path and
+   * materialization stack forward so nested calls inherit captive-dependency checks.
+   */
+  private createContext;
+  /**
+   * @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.
+   * @param visiting - Registry keys currently on the call stack; used for circular-dependency detection.
+   * @param materializationStack - Bindings along the current construction chain; used to block singleton→scoped/transient.
+   */
+  private resolve;
+  /**
+   * @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.
+   * @param visiting - Registry keys currently on the call stack; used for circular-dependency detection.
+   * @param materializationStack - Same captive-dependency chain as {@link resolve}.
+   */
+  private resolveAsync;
+  /**
+   * Handles scope-cache lookup / storage and lifecycle hooks (`@postConstruct`, `onActivation`)
+   * around a synchronous call to {@link materialize}.
+   */
+  private instantiateBinding;
+  /**
+   * Async counterpart of {@link instantiateBinding}: delegates to {@link materializeAsync}
+   * and awaits `@postConstruct` and `onActivation` hooks.
+   */
+  private instantiateBindingAsync;
+  /**
+   * Duplicate captive-dependency guard applied at instantiation time (after scope-cache miss),
+   * checking the top of the materialization stack rather than the raw `ConstraintContext`.
+   */
+  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.
+   */
+  private materialize;
+  /**
+   * Async counterpart of {@link materialize}; awaits `async-dynamic` factories and
+   * recursively resolves `resolved`-binding dependencies with {@link resolveAsync}.
+   */
+  private materializeAsync;
+  /**
+   * Reads `@injectable()` constructor metadata and synchronously resolves each parameter,
+   * then calls `new ImplementationClass(...deps)`. Throws {@link MissingMetadataError} when
+   * the class has constructor parameters but no metadata.
+   */
+  private instantiateClassBinding;
+  /**
+   * Async counterpart of {@link instantiateClassBinding}: resolves constructor dependencies
+   * with {@link resolveAsync} so `async-dynamic` parameters are awaited in order.
+   */
+  private instantiateClassBindingAsync;
+}
+//#endregion
+export { DependencyResolver, ResolverDependencies };

package/dist/resolver.mjs

@@ -0,0 +1,361 @@
+import { AsyncResolutionError, CircularDependencyError, InternalError, MissingMetadataError, NoMatchingBindingError, ScopeViolationError, TokenNotBoundError } from "./errors.mjs";
+import { filterMatchingBindings, registryKeyLabel, selectBindingForRegistry } from "./binding-select.mjs";
+import { runActivation, runActivationAsync, runPostConstruct, runPostConstructAsync } from "./lifecycle.mjs";
+//#region src/resolver.ts
+/** Converts a registry key + binding into a {@link MaterializationFrame} for the captive-dependency stack. */
+function bindingToMaterializationFrame(registryKey, binding) {
+	return {
+		registryKey,
+		bindingId: binding.id,
+		bindingKind: binding.kind,
+		tags: binding.tags,
+		scope: binding.scope
+	};
+}
+/**
+* Walks the binding graph, manages circular-dependency detection, delegates caching to
+* {@link ScopeManager}, and calls lifecycle hooks. Used exclusively by the container.
+*/
+var DependencyResolver = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** Entry point for synchronous single-binding resolution (no path prefix). */
+	resolveRoot(key, hint) {
+		return this.resolve(key, hint, [], /* @__PURE__ */ new Set(), []);
+	}
+	/** Entry point for async single-binding resolution (no path prefix). */
+	resolveAsyncRoot(key, hint) {
+		return this.resolveAsync(key, hint, [], /* @__PURE__ */ new Set(), []);
+	}
+	/** Returns `undefined` instead of throwing when no binding is found; still throws on circular deps or async factories. */
+	resolveOptionalRoot(key, hint) {
+		const registryKey = key;
+		const label = registryKeyLabel(key);
+		const pathLabels = [label];
+		const bindings = this.deps.lookup(registryKey);
+		if (bindings === void 0 || bindings.length === 0) return;
+		const candidates = filterMatchingBindings(bindings, hint, this.buildConstraintContext(pathLabels, [], hint));
+		if (candidates.length === 0) {
+			if (hint !== void 0 && (hint.name !== void 0 || hint.tag !== void 0)) throw new NoMatchingBindingError(label, hint, pathLabels);
+			return;
+		}
+		if (candidates.length !== 1) throw new InternalError(`Ambiguous binding for "${label}": ${String(candidates.length)} candidates matched (resolution path: ${pathLabels.join(" -> ")})`);
+		const binding = candidates[0];
+		if (binding === void 0) throw new InternalError(`Internal: expected single binding candidate for "${label}" (resolution path: ${pathLabels.join(" -> ")})`);
+		this.assertDependencyScopeAllowed(binding, pathLabels, []);
+		if (binding.kind === "async-dynamic") throw new AsyncResolutionError(label, pathLabels, "encountered async-dynamic factory during synchronous resolution");
+		const visiting = /* @__PURE__ */ new Set();
+		visiting.add(registryKey);
+		try {
+			return this.instantiateBinding(binding, registryKey, hint, pathLabels, visiting, []);
+		} finally {
+			visiting.delete(registryKey);
+		}
+	}
+	/** Resolves all bindings for `key` synchronously; throws on async factories. */
+	resolveAllRoot(key, hint) {
+		const registryKey = key;
+		const label = registryKeyLabel(key);
+		const basePath = [label];
+		const bindings = this.deps.lookup(registryKey);
+		if (bindings === void 0 || bindings.length === 0) return [];
+		const candidates = filterMatchingBindings(bindings, hint, this.buildConstraintContext(basePath, [], hint));
+		if (candidates.length === 0) {
+			if (hint !== void 0 && (hint.name !== void 0 || hint.tag !== void 0)) throw new NoMatchingBindingError(label, hint, basePath);
+			return [];
+		}
+		const results = [];
+		for (const binding of candidates) {
+			this.assertDependencyScopeAllowed(binding, basePath, []);
+			if (binding.kind === "async-dynamic") throw new AsyncResolutionError(label, basePath, "encountered async-dynamic factory during synchronous resolveAll");
+			const visiting = /* @__PURE__ */ new Set();
+			visiting.add(registryKey);
+			try {
+				results.push(this.instantiateBinding(binding, registryKey, hint, basePath, visiting, []));
+			} finally {
+				visiting.delete(registryKey);
+			}
+		}
+		return results;
+	}
+	/** Resolves all bindings for `key`, awaiting any async factories in the set. */
+	async resolveAllAsyncRoot(key, hint) {
+		const registryKey = key;
+		const label = registryKeyLabel(key);
+		const basePath = [label];
+		const bindings = this.deps.lookup(registryKey);
+		if (bindings === void 0 || bindings.length === 0) return [];
+		const candidates = filterMatchingBindings(bindings, hint, this.buildConstraintContext(basePath, [], hint));
+		if (candidates.length === 0) {
+			if (hint !== void 0 && (hint.name !== void 0 || hint.tag !== void 0)) throw new NoMatchingBindingError(label, hint, basePath);
+			return [];
+		}
+		const results = [];
+		for (const binding of candidates) {
+			this.assertDependencyScopeAllowed(binding, basePath, []);
+			const visiting = /* @__PURE__ */ new Set();
+			visiting.add(registryKey);
+			try {
+				results.push(await this.instantiateBindingAsync(binding, registryKey, hint, basePath, visiting, []));
+			} finally {
+				visiting.delete(registryKey);
+			}
+		}
+		return results;
+	}
+	/**
+	* Assembles the read-only {@link ConstraintContext} snapshot passed to `when()` predicates.
+	* Extracts the top-of-stack frame as `parent` and the rest as `ancestors`.
+	*/
+	buildConstraintContext(resolutionPath, materializationStack, currentResolveHint) {
+		return {
+			resolutionPath,
+			materializationStack,
+			parent: materializationStack.length > 0 ? materializationStack[materializationStack.length - 1] : void 0,
+			ancestors: materializationStack.slice(0, -1),
+			currentResolveHint
+		};
+	}
+	/**
+	* Throws {@link ScopeViolationError} when the immediate consumer on the stack is a singleton
+	* and the dependency has `"scoped"` or `"transient"` lifetime (captive dependency).
+	* Constants are exempt — they have no scope cache.
+	*/
+	assertDependencyScopeAllowed(dependencyBinding, resolutionPath, materializationStack) {
+		const consumer = materializationStack[materializationStack.length - 1];
+		if (consumer === void 0) return;
+		if (consumer.scope !== "singleton") return;
+		if (dependencyBinding.kind === "constant") return;
+		if (dependencyBinding.scope === "transient" || dependencyBinding.scope === "scoped") {
+			const dependencyLabel = resolutionPath[resolutionPath.length - 1];
+			const consumerLabel = resolutionPath.length >= 2 ? resolutionPath[resolutionPath.length - 2] : void 0;
+			throw new ScopeViolationError({
+				consumerBindingId: consumer.bindingId,
+				consumerKind: consumer.bindingKind,
+				consumerScope: consumer.scope,
+				consumerLabel,
+				dependencyBindingId: dependencyBinding.id,
+				dependencyKind: dependencyBinding.kind,
+				dependencyScope: dependencyBinding.scope,
+				dependencyLabel,
+				resolutionPath: [...resolutionPath]
+			});
+		}
+	}
+	/**
+	* Builds a {@link ResolutionContext} for use inside factories and lifecycle hooks.
+	* The `resolve` / `resolveAsync` / `resolveOptional` closures carry the current path and
+	* materialization stack forward so nested calls inherit captive-dependency checks.
+	*/
+	createContext(pathLabels, visiting, materializationStack, currentResolveHint) {
+		return {
+			resolve: (token, hint) => this.resolve(token, hint, [...pathLabels], visiting, materializationStack),
+			resolveAsync: (token, hint) => this.resolveAsync(token, hint, [...pathLabels], visiting, materializationStack),
+			resolveOptional: (token, hint) => {
+				try {
+					return this.resolve(token, hint, [...pathLabels], visiting, materializationStack);
+				} catch (caughtError) {
+					if (caughtError instanceof TokenNotBoundError) return;
+					throw caughtError;
+				}
+			},
+			graph: this.buildConstraintContext(pathLabels, materializationStack, currentResolveHint)
+		};
+	}
+	/**
+	* @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.
+	* @param visiting - Registry keys currently on the call stack; used for circular-dependency detection.
+	* @param materializationStack - Bindings along the current construction chain; used to block singleton→scoped/transient.
+	*/
+	resolve(key, hint, pathLabels, visiting, materializationStack) {
+		const registryKey = key;
+		const label = registryKeyLabel(key);
+		const nextPath = [...pathLabels, label];
+		if (visiting.has(registryKey)) throw new CircularDependencyError(nextPath);
+		const bindings = this.deps.lookup(registryKey);
+		if (bindings === void 0 || bindings.length === 0) throw new TokenNotBoundError(label, nextPath);
+		const binding = selectBindingForRegistry(bindings, hint, label, nextPath, this.buildConstraintContext(nextPath, materializationStack, hint));
+		this.assertDependencyScopeAllowed(binding, nextPath, materializationStack);
+		if (binding.kind === "async-dynamic") throw new AsyncResolutionError(label, nextPath, "encountered async-dynamic factory during synchronous resolution");
+		visiting.add(registryKey);
+		try {
+			return this.instantiateBinding(binding, registryKey, hint, nextPath, visiting, materializationStack);
+		} finally {
+			visiting.delete(registryKey);
+		}
+	}
+	/**
+	* @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.
+	* @param visiting - Registry keys currently on the call stack; used for circular-dependency detection.
+	* @param materializationStack - Same captive-dependency chain as {@link resolve}.
+	*/
+	async resolveAsync(key, hint, pathLabels, visiting, materializationStack) {
+		const registryKey = key;
+		const label = registryKeyLabel(key);
+		const nextPath = [...pathLabels, label];
+		if (visiting.has(registryKey)) throw new CircularDependencyError(nextPath);
+		const bindings = this.deps.lookup(registryKey);
+		if (bindings === void 0 || bindings.length === 0) throw new TokenNotBoundError(label, nextPath);
+		const binding = selectBindingForRegistry(bindings, hint, label, nextPath, this.buildConstraintContext(nextPath, materializationStack, hint));
+		this.assertDependencyScopeAllowed(binding, nextPath, materializationStack);
+		visiting.add(registryKey);
+		try {
+			return await this.instantiateBindingAsync(binding, registryKey, hint, nextPath, visiting, materializationStack);
+		} finally {
+			visiting.delete(registryKey);
+		}
+	}
+	/**
+	* Handles scope-cache lookup / storage and lifecycle hooks (`@postConstruct`, `onActivation`)
+	* around a synchronous call to {@link materialize}.
+	*/
+	instantiateBinding(binding, registryKey, hint, pathLabels, visiting, materializationStack) {
+		this.assertCaptiveDependencyFromMaterializationStack(binding, pathLabels, materializationStack);
+		return this.deps.scopeManager.getOrCreate(binding, () => {
+			const frame = bindingToMaterializationFrame(registryKey, binding);
+			const extendedStack = [...materializationStack, frame];
+			const ctx = this.createContext(pathLabels, visiting, extendedStack, hint);
+			const instance = this.materialize(binding, hint, ctx, pathLabels, visiting, extendedStack);
+			if (binding.kind === "class") runPostConstruct(binding.implementationClass, instance, pathLabels);
+			return runActivation(binding, instance, ctx, pathLabels);
+		});
+	}
+	/**
+	* Async counterpart of {@link instantiateBinding}: delegates to {@link materializeAsync}
+	* and awaits `@postConstruct` and `onActivation` hooks.
+	*/
+	async instantiateBindingAsync(binding, registryKey, hint, pathLabels, visiting, materializationStack) {
+		this.assertCaptiveDependencyFromMaterializationStack(binding, pathLabels, materializationStack);
+		return this.deps.scopeManager.getOrCreateAsync(binding, async () => {
+			const frame = bindingToMaterializationFrame(registryKey, binding);
+			const extendedStack = [...materializationStack, frame];
+			const ctx = this.createContext(pathLabels, visiting, extendedStack, hint);
+			const instance = await this.materializeAsync(binding, hint, ctx, pathLabels, visiting, extendedStack);
+			if (binding.kind === "class") await runPostConstructAsync(binding.implementationClass, instance);
+			return await runActivationAsync(binding, instance, ctx, pathLabels);
+		});
+	}
+	/**
+	* Duplicate captive-dependency guard applied at instantiation time (after scope-cache miss),
+	* checking the top of the materialization stack rather than the raw `ConstraintContext`.
+	*/
+	assertCaptiveDependencyFromMaterializationStack(dependencyBinding, resolutionPath, materializationStack) {
+		const parentFrame = materializationStack[materializationStack.length - 1];
+		if (parentFrame === void 0) return;
+		if (parentFrame.scope !== "singleton") return;
+		if (dependencyBinding.kind === "constant") return;
+		if (dependencyBinding.scope === "scoped" || dependencyBinding.scope === "transient") {
+			const dependencyLabel = resolutionPath[resolutionPath.length - 1];
+			const consumerLabel = resolutionPath.length >= 2 ? resolutionPath[resolutionPath.length - 2] : void 0;
+			throw new ScopeViolationError({
+				consumerBindingId: parentFrame.bindingId,
+				consumerKind: parentFrame.bindingKind,
+				consumerScope: parentFrame.scope,
+				consumerLabel,
+				dependencyBindingId: dependencyBinding.id,
+				dependencyKind: dependencyBinding.kind,
+				dependencyScope: dependencyBinding.scope,
+				dependencyLabel,
+				resolutionPath: [...resolutionPath]
+			});
+		}
+	}
+	/**
+	* Synchronously produces the raw instance for a binding without touching the scope cache.
+	* Dispatches on `binding.kind`; throws {@link AsyncResolutionError} for `async-dynamic` factories.
+	*/
+	materialize(binding, hint, ctx, pathLabels, visiting, materializationStack) {
+		switch (binding.kind) {
+			case "constant": return binding.value;
+			case "class": return this.instantiateClassBinding(binding, pathLabels, visiting, materializationStack);
+			case "dynamic": {
+				const factoryResult = binding.factory(ctx);
+				if (typeof factoryResult === "object" && factoryResult !== null && "then" in factoryResult && typeof factoryResult.then === "function") throw new AsyncResolutionError(pathLabels[pathLabels.length - 1] ?? "(unknown)", pathLabels, "dynamic factory returned a Promise during synchronous resolution");
+				return factoryResult;
+			}
+			case "async-dynamic": throw new AsyncResolutionError(pathLabels[pathLabels.length - 1] ?? "(unknown)", pathLabels, "async-dynamic factory cannot be materialized synchronously");
+			case "resolved": {
+				const deps = [];
+				for (const depToken of binding.dependencyTokens) deps.push(this.resolve(depToken, void 0, pathLabels, visiting, materializationStack));
+				const resolvedValue = binding.factory(...deps);
+				if (typeof resolvedValue === "object" && resolvedValue !== null && "then" in resolvedValue && typeof resolvedValue.then === "function") throw new AsyncResolutionError(pathLabels[pathLabels.length - 1] ?? "(unknown)", pathLabels, "resolved factory returned a Promise during synchronous resolution");
+				return resolvedValue;
+			}
+			case "alias": return this.resolve(binding.targetToken, hint, pathLabels, visiting, materializationStack);
+			default: return binding;
+		}
+	}
+	/**
+	* Async counterpart of {@link materialize}; awaits `async-dynamic` factories and
+	* recursively resolves `resolved`-binding dependencies with {@link resolveAsync}.
+	*/
+	async materializeAsync(binding, hint, ctx, pathLabels, visiting, materializationStack) {
+		switch (binding.kind) {
+			case "constant": return binding.value;
+			case "class": return this.instantiateClassBindingAsync(binding, pathLabels, visiting, materializationStack);
+			case "dynamic": return binding.factory(ctx);
+			case "async-dynamic": return await binding.factory(ctx);
+			case "resolved": {
+				const deps = [];
+				for (const depToken of binding.dependencyTokens) deps.push(await this.resolveAsync(depToken, void 0, pathLabels, visiting, materializationStack));
+				return binding.factory(...deps);
+			}
+			case "alias": return this.resolveAsync(binding.targetToken, hint, pathLabels, visiting, materializationStack);
+			default: return binding;
+		}
+	}
+	/**
+	* Reads `@injectable()` constructor metadata and synchronously resolves each parameter,
+	* then calls `new ImplementationClass(...deps)`. Throws {@link MissingMetadataError} when
+	* the class has constructor parameters but no metadata.
+	*/
+	instantiateClassBinding(binding, pathLabels, visiting, materializationStack) {
+		const reader = this.deps.metadataReader;
+		const ImplementationClass = binding.implementationClass;
+		if (reader === void 0) return new ImplementationClass();
+		const meta = reader.getConstructorMetadata(binding.implementationClass);
+		if (ImplementationClass.length > 0 && meta === void 0) throw new MissingMetadataError(registryKeyLabel(binding.implementationClass), pathLabels);
+		if (meta === void 0 || meta.params.length === 0) return new ImplementationClass();
+		return new ImplementationClass(...meta.params.map((param) => {
+			const paramHint = param.name !== void 0 ? { name: param.name } : param.tag !== void 0 ? { tag: param.tag } : void 0;
+			if (param.optional) try {
+				return this.resolve(param.token, paramHint, pathLabels, visiting, materializationStack);
+			} catch (caughtError) {
+				if (caughtError instanceof TokenNotBoundError) return;
+				throw caughtError;
+			}
+			return this.resolve(param.token, paramHint, pathLabels, visiting, materializationStack);
+		}));
+	}
+	/**
+	* Async counterpart of {@link instantiateClassBinding}: resolves constructor dependencies
+	* with {@link resolveAsync} so `async-dynamic` parameters are awaited in order.
+	*/
+	async instantiateClassBindingAsync(binding, pathLabels, visiting, materializationStack) {
+		const reader = this.deps.metadataReader;
+		const ImplementationClass = binding.implementationClass;
+		if (reader === void 0) return new ImplementationClass();
+		const meta = reader.getConstructorMetadata(binding.implementationClass);
+		if (ImplementationClass.length > 0 && meta === void 0) throw new MissingMetadataError(registryKeyLabel(binding.implementationClass), pathLabels);
+		if (meta === void 0 || meta.params.length === 0) return new ImplementationClass();
+		const deps = [];
+		for (const param of meta.params) {
+			const paramHint = param.name !== void 0 ? { name: param.name } : param.tag !== void 0 ? { tag: param.tag } : void 0;
+			if (param.optional) try {
+				deps.push(await this.resolveAsync(param.token, paramHint, pathLabels, visiting, materializationStack));
+			} catch (caughtError) {
+				if (caughtError instanceof TokenNotBoundError) deps.push(void 0);
+				else throw caughtError;
+			}
+			else deps.push(await this.resolveAsync(param.token, paramHint, pathLabels, visiting, materializationStack));
+		}
+		return new ImplementationClass(...deps);
+	}
+};
+//#endregion
+export { DependencyResolver };

package/dist/scope-validation.d.mts

@@ -0,0 +1,20 @@
+import { RegistryKey } from "./registry.mjs";
+import { Binding } from "./binding.mjs";
+import { MetadataReader } from "./metadata/metadata-types.mjs";
+
+//#region src/scope-validation.d.ts
+/**
+ * Walks every binding in the registry and throws {@link ScopeViolationError} on the first
+ * captive-dependency violation found: a singleton that directly or transitively depends on a
+ * scoped or transient binding. Constant bindings are exempt (no stateful instance to capture).
+ *
+ * Called by {@link Container.validate} and automatically after each `load()` in non-production
+ * environments.
+ */
+declare function validateScopeRules(context: {
+  collectAllRegistryKeys(): readonly RegistryKey[];
+  lookupBindings(key: RegistryKey): readonly Binding<unknown>[] | undefined;
+  getMetadataReader(): MetadataReader | undefined;
+}): void;
+//#endregion
+export { validateScopeRules };