@codefast/di 0.3.13 → 0.3.14-canary.1

package/dist/binding-select.d.mts

@@ -3,19 +3,30 @@ import { RegistryKey } from "./registry.mjs";
 import { Binding, ConstraintContext, Constructor, ResolveHint } from "./binding.mjs";
 
 //#region src/binding-select.d.ts
-/** Returns a human-readable label for a token or constructor (used in error messages and graph output). */
+/**
+ * Returns a human-readable label for a token or constructor (used in error messages and graph output).
+ */
 declare function registryKeyLabel(key: Token<unknown> | Constructor<unknown>): string;
 /**
- * Applies resolve hints and optional constraint predicates to a binding list.
+ * Narrows a binding list by applying name/tag hints and `when()` constraint predicates.
+ *
+ * Filtering order: name filter → tag filter → constraint predicate. Bindings without a
+ * constraint predicate always pass the constraint stage. Returns the surviving candidates
+ * (may be empty).
  */
-declare function filterMatchingBindings(bindings: readonly Binding<unknown>[], hint: ResolveHint | undefined, constraintCtx: ConstraintContext | undefined): Binding<unknown>[];
+declare function filterMatchingBindings(bindings: readonly Binding<unknown>[], hint: ResolveHint | undefined, constraintCtx: ConstraintContext | undefined): readonly Binding<unknown>[];
 /**
- * Picks the binding that would be used for resolution with the given hint (same rules as {@link DependencyResolver}).
- * When `constraintCtx` is set, bindings with a {@link BindingBuilder.when} predicate must pass it.
+ * Selects exactly one binding from the provided list, applying hint and constraint filtering.
+ *
+ * @throws {@link TokenNotBoundError} — `bindings` list is empty, or no candidate survives
+ *   filtering without a name/tag hint.
+ * @throws {@link NoMatchingBindingError} — a name/tag hint was provided but no candidate matched.
+ * @throws {@link InternalError} — multiple candidates survive filtering (ambiguous binding).
  */
 declare function selectBindingForRegistry(bindings: readonly Binding<unknown>[], hint: ResolveHint | undefined, tokenLabel: string, pathLabels: readonly string[], constraintCtx: ConstraintContext | undefined): Binding<unknown>;
 /**
- * Resolves the effective binding for a registry key using the default (no-hint) selection rules.
+ * Convenience wrapper: looks up bindings for `key` and selects the default (no-hint,
+ * no-constraint) binding. Throws {@link TokenNotBoundError} if the key is unregistered.
  */
 declare function selectDefaultBindingForKey(lookup: (key: RegistryKey) => readonly Binding<unknown>[] | undefined, key: RegistryKey, pathPrefix: readonly string[]): Binding<unknown>;
 //#endregion

package/dist/binding-select.mjs

@@ -1,15 +1,21 @@
 import { InternalError, NoMatchingBindingError, TokenNotBoundError } from "./errors.mjs";
 //#region src/binding-select.ts
-/** Returns a human-readable label for a token or constructor (used in error messages and graph output). */
+/**
+* Returns a human-readable label for a token or constructor (used in error messages and graph output).
+*/
 function registryKeyLabel(key) {
 	if (typeof key === "function") return key.name.length > 0 ? key.name : "(anonymous class)";
 	return key.name.trim().length > 0 ? key.name : "(anonymous token)";
 }
 /**
-* Applies resolve hints and optional constraint predicates to a binding list.
+* Narrows a binding list by applying name/tag hints and `when()` constraint predicates.
+*
+* Filtering order: name filter → tag filter → constraint predicate. Bindings without a
+* constraint predicate always pass the constraint stage. Returns the surviving candidates
+* (may be empty).
 */
 function filterMatchingBindings(bindings, hint, constraintCtx) {
-	let candidates = [...bindings];
+	let candidates = bindings;
 	if (hint?.name !== void 0) candidates = candidates.filter((binding) => binding.bindingName === hint.name);
 	if (hint?.tag !== void 0) {
 		const [tagKey, tagValue] = hint.tag;
@@ -19,8 +25,12 @@ function filterMatchingBindings(bindings, hint, constraintCtx) {
 	return candidates;
 }
 /**
-* Picks the binding that would be used for resolution with the given hint (same rules as {@link DependencyResolver}).
-* When `constraintCtx` is set, bindings with a {@link BindingBuilder.when} predicate must pass it.
+* Selects exactly one binding from the provided list, applying hint and constraint filtering.
+*
+* @throws {@link TokenNotBoundError} — `bindings` list is empty, or no candidate survives
+*   filtering without a name/tag hint.
+* @throws {@link NoMatchingBindingError} — a name/tag hint was provided but no candidate matched.
+* @throws {@link InternalError} — multiple candidates survive filtering (ambiguous binding).
 */
 function selectBindingForRegistry(bindings, hint, tokenLabel, pathLabels, constraintCtx) {
 	if (bindings.length === 0) throw new TokenNotBoundError(tokenLabel, [...pathLabels]);
@@ -37,7 +47,8 @@ function selectBindingForRegistry(bindings, hint, tokenLabel, pathLabels, constr
 	throw new InternalError(`Ambiguous binding for "${tokenLabel}": ${String(candidates.length)} candidates matched after applying ResolveHint (resolution path: ${pathLabels.join(" -> ")})`);
 }
 /**
-* Resolves the effective binding for a registry key using the default (no-hint) selection rules.
+* Convenience wrapper: looks up bindings for `key` and selects the default (no-hint,
+* no-constraint) binding. Throws {@link TokenNotBoundError} if the key is unregistered.
 */
 function selectDefaultBindingForKey(lookup, key, pathPrefix) {
 	const label = registryKeyLabel(key);

package/dist/binding.d.mts

@@ -17,25 +17,37 @@ declare function createBindingIdentifier(): BindingIdentifier;
  * Runtime constructor token used as a registry key (no reflection metadata).
  */
 type Constructor<Value> = abstract new (...args: never[]) => Value;
-/** Lifetime strategy for a resolved instance. */
+/**
+ * Lifetime strategy for a resolved instance.
+ */
 type BindingScope = "singleton" | "transient" | "scoped";
 /**
  * Hint for disambiguating multi-bindings registered against the same token or constructor.
  */
 type ResolveHint = {
-  readonly name?: string;
+  /** Matches bindings configured with `.whenNamed(name)`. */readonly name?: string; /** Matches bindings configured with `.whenTagged(tagKey, value)`. */
   readonly tag?: readonly [tag: string, value: unknown];
 };
+/**
+ * Public alias for {@link ResolveHint} — the `hint` parameter accepted by
+ * `Container.resolve`, `Container.resolveAsync`, and related methods.
+ * Passes `name` and/or `tag` to select among multi-bindings.
+ */
 type ResolveOptions = ResolveHint;
 /**
  * Snapshot of a binding on the materialization stack (for {@link ConstraintContext}).
  */
 type ConstraintBindingKind = "constant" | "class" | "dynamic" | "async-dynamic" | "resolved" | "alias";
+/**
+ * Snapshot of a single binding on the materialization stack during resolution.
+ * Each frame captures enough identity to implement contextual constraints
+ * ({@link whenParentIs}, {@link whenAnyAncestorIs}) and captive-dependency detection.
+ */
 type ConstraintParentFrame = {
-  readonly registryKey: RegistryKey;
-  readonly bindingId: BindingIdentifier;
-  readonly bindingKind: ConstraintBindingKind;
-  readonly tags: ReadonlyMap<string, unknown>;
+  /** Registry key (token/constructor) that selected this binding. */readonly registryKey: RegistryKey; /** Stable identifier of the materialized binding. */
+  readonly bindingId: BindingIdentifier; /** Discriminant of the selected binding strategy. */
+  readonly bindingKind: ConstraintBindingKind; /** Immutable tag map present on the selected binding. */
+  readonly tags: ReadonlyMap<string, unknown>; /** Effective scope of the selected binding. */
   readonly scope: BindingScope;
 };
 /**
@@ -46,10 +58,10 @@ type MaterializationFrame = ConstraintParentFrame;
  * Context for {@link BindingBuilder.when} predicates: path, ancestor metadata, and the current resolve hint.
  */
 type ConstraintContext = {
-  readonly resolutionPath: readonly string[];
-  readonly materializationStack: readonly ConstraintParentFrame[];
-  readonly parent: ConstraintParentFrame | undefined;
-  readonly ancestors: readonly ConstraintParentFrame[];
+  /** Resolution labels from root request to current key. */readonly resolutionPath: readonly string[]; /** Full chain of materialized parent frames (oldest → newest). */
+  readonly materializationStack: readonly ConstraintParentFrame[]; /** Immediate parent frame, if the current resolution has one. */
+  readonly parent: ConstraintParentFrame | undefined; /** Parent chain excluding the immediate parent frame. */
+  readonly ancestors: readonly ConstraintParentFrame[]; /** Name/tag hint used for the current lookup, if provided. */
   readonly currentResolveHint: ResolveHint | undefined;
 };
 /**
@@ -60,11 +72,20 @@ type ConstraintContext = {
  * context-sensitive bindings such as `whenParentIs` or `whenAnyAncestorIs`.
  */
 type ResolutionContext = {
-  readonly resolve: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Value;
-  readonly resolveAsync: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Promise<Value>;
-  readonly resolveOptional: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Value | undefined; /** Dependency-graph navigation context — path, materialization stack, parent/ancestor frames. */
+  /** Resolves one binding synchronously using current path/stack context. */readonly resolve: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Value; /** Async variant of {@link ResolutionContext.resolve}. */
+  readonly resolveAsync: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Promise<Value>; /** Returns `undefined` when the requested root key is unbound. */
+  readonly resolveOptional: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Value | undefined; /** Resolves every binding registered for `token` (multi-binding). */
+  readonly resolveAll: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Value[]; /** Async variant of {@link ResolutionContext.resolveAll}. */
+  readonly resolveAllAsync: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Promise<Value[]>;
+  /**
+   * Dependency-graph navigation context — path, materialization stack, parent/ancestor frames.
+   */
   readonly graph: ConstraintContext;
 };
+/**
+ * Lifecycle and constraint fields shared by every concrete {@link Binding} variant.
+ * Separated from {@link BindingBase} so the builder can accumulate them independently of `id` / `scope`.
+ */
 type BindingLifecycle = {
   readonly bindingName?: string;
   readonly tags: ReadonlyMap<string, unknown>;
@@ -85,36 +106,51 @@ type ActivationHandler<Value> = (ctx: ResolutionContext, instance: Value) => Val
 type DeactivationHandler<Value> = (instance: Value) => void | Promise<void>;
 type BindingBase = BindingLifecycle & {
   readonly id: BindingIdentifier;
-  readonly scope: BindingScope; /** Set when the binding was registered from {@link Module} / {@link AsyncModule} setup. */
+  readonly scope: BindingScope;
+  /**
+   * Set when the binding was registered from {@link Module} / {@link AsyncModule} setup.
+   */
   readonly moduleId?: string;
 };
-/** Binding backed by a pre-existing constant value; always singleton, no construction cost. */
+/**
+ * Binding backed by a pre-existing constant value; always singleton, no construction cost.
+ */
 type ConstantBinding<Value> = BindingBase & {
   readonly kind: "constant";
   readonly value: Value;
 };
-/** Binding that constructs `implementationClass` via the container's metadata-driven instantiation. */
+/**
+ * Binding that constructs `implementationClass` via the container's metadata-driven instantiation.
+ */
 type ClassBinding<Value> = BindingBase & {
   readonly kind: "class";
   readonly implementationClass: Constructor<Value>;
 };
-/** Binding backed by a synchronous factory that receives a {@link ResolutionContext}. */
+/**
+ * Binding backed by a synchronous factory that receives a {@link ResolutionContext}.
+ */
 type DynamicBinding<Value> = BindingBase & {
   readonly kind: "dynamic";
   readonly factory: (ctx: ResolutionContext) => Value;
 };
-/** Binding backed by an async factory; must be resolved via `resolveAsync` / `resolveAllAsync`. */
+/**
+ * Binding backed by an async factory; must be resolved via `resolveAsync` / `resolveAllAsync`.
+ */
 type AsyncDynamicBinding<Value> = BindingBase & {
   readonly kind: "async-dynamic";
   readonly factory: (ctx: ResolutionContext) => Promise<Value>;
 };
-/** Binding whose dependencies are declared statically and pre-resolved before the factory is called. */
+/**
+ * Binding whose dependencies are declared statically and pre-resolved before the factory is called.
+ */
 type ResolvedBinding<Value> = BindingBase & {
   readonly kind: "resolved";
   readonly dependencyTokens: readonly (Token<unknown> | Constructor<unknown>)[];
   readonly factory: (...args: unknown[]) => Value;
 };
-/** Binding that forwards resolution to `targetToken`; the container resolves whatever is bound there. */
+/**
+ * Binding that forwards resolution to `targetToken`; the container resolves whatever is bound there.
+ */
 type AliasBinding<Value> = BindingBase & {
   readonly kind: "alias";
   readonly targetToken: Token<Value>;
@@ -132,53 +168,134 @@ type RegistryCallbacks<Value> = {
   readonly register?: (binding: Binding<Value>) => void;
   readonly update?: (binding: Binding<Value>) => void;
 };
+/**
+ * Fluent builder for registering a single binding against a {@link Token} or {@link Constructor}.
+ *
+ * A builder has two phases:
+ * 1. **Strategy selection** — exactly one `to*()` call (`to`, `toSelf`, `toConstantValue`,
+ *    `toDynamic`, `toDynamicAsync`, `toResolved`, `toAlias`) that determines how the value is produced.
+ * 2. **Refinement chain** — optional calls to `singleton()`, `transient()`, `scoped()`,
+ *    `onActivation()`, `onDeactivation()`, `whenNamed()`, `whenTagged()`, `when()`, and `id()`.
+ *
+ * Calling a second `to*()` method throws {@link InternalError}.
+ *
+ * The builder is created by {@link Container.bind} or by `bind` on {@link ModuleBuilder}.
+ * The container injects {@link RegistryCallbacks} so that every strategy selection and
+ * refinement is immediately reflected in the live registry.
+ */
 declare class BindingBuilder<Value> {
   protected readonly bindingKey: Token<Value> | Constructor<Value>;
+  /**
+   * Current resolution strategy; starts as `"unset"` until a `to*()` method is called.
+   */
   private strategy;
+  /**
+   * Lifetime scope applied to the next binding snapshot; defaults to `"transient"`.
+   */
   private scope;
+  /**
+   * True after an explicit `.singleton()` / `.transient()` / `.scoped()` call (prevents constant scope change).
+   */
   private isScopeExplicit;
+  /**
+   * Pre-allocated binding ID set via `id(identifier)` before the first `to*()` call.
+   */
   private explicitId;
+  /**
+   * Resolve-hint name filter set by `.whenNamed()`.
+   */
   private bindingName;
+  /**
+   * Tag filters accumulated by successive `.whenTagged()` calls.
+   */
   private readonly tags;
+  /**
+   * Custom constraint predicates accumulated by `.when()`; all must pass for this binding to be selected.
+   */
   private readonly constraintPredicates;
+  /**
+   * Latest `onActivation` hook provided by `.onActivation(...)`.
+   * Applied to emitted binding snapshots until replaced.
+   */
   private onActivationHandler;
+  /**
+   * Latest `onDeactivation` hook provided by `.onDeactivation(...)`.
+   * Emitted only on builder variants that expose deactivation support.
+   */
   private onDeactivationHandler;
+  /**
+   * Set when this binding was created inside a {@link Module} / {@link AsyncModule} setup callback.
+   */
   private readonly moduleId;
+  /**
+   * The most recently emitted {@link Binding} snapshot; `undefined` before the first `to*()` call.
+   */
   private currentBinding;
+  /**
+   * Container-injected hooks that sync builder mutations into the live registry.
+   */
   private readonly callbacks;
   constructor(bindingKey: Token<Value> | Constructor<Value>, moduleId?: string, callbacks?: RegistryCallbacks<Value>);
-  /** Binds the token to a concrete implementation class; the container constructs it on demand. */
+  /**
+   * Binds the token to a concrete implementation class; the container constructs it on demand.
+   */
   to<C extends Constructor<Value>>(implementationClass: C): TransientBindingBuilder<Value>;
-  /** Binds the class key to itself — only valid when the key is a constructor. */
+  /**
+   * Binds the class key to itself — only valid when the key is a constructor.
+   */
   toSelf(): TransientBindingBuilder<Value>;
-  /** Binds the token to a pre-existing value; always resolved as singleton, no construction. */
+  /**
+   * Binds the token to a pre-existing value; always resolved as singleton, no construction.
+   */
   toConstantValue<const ConcreteValue extends Value>(value: ConcreteValue): ConstantBindingBuilder<Value>;
-  /** Binds to a synchronous factory; `ctx` provides nested resolution within the same path. */
+  /**
+   * Binds to a synchronous factory; `ctx` provides nested resolution within the same path.
+   */
   toDynamic(factory: (ctx: ResolutionContext) => Value): TransientBindingBuilder<Value>;
-  /** Binds to an async factory; must be resolved via `resolveAsync` / `resolveAllAsync`. */
+  /**
+   * Binds to an async factory; must be resolved via `resolveAsync` / `resolveAllAsync`.
+   */
   toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): TransientBindingBuilder<Value>;
   /**
    * Binds to a factory whose dependencies are declared explicitly in `deps` and pre-resolved by
    * the container before the factory is called — no `ResolutionContext` needed inside the factory.
    */
   toResolved<Deps extends readonly (Token<unknown> | Constructor<unknown>)[]>(factory: (...args: { [Index in keyof Deps]: TokenValue<Deps[Index]> }) => Value, deps: Deps): TransientBindingBuilder<Value>;
-  /** Redirects resolution to `targetToken`; the container resolves whatever is bound there. */
+  /**
+   * Redirects resolution to `targetToken`; the container resolves whatever is bound there.
+   */
   toAlias(targetToken: Token<Value>): TransientBindingBuilder<Value>;
-  /** One instance per container; supports `onDeactivation`. */
+  /**
+   * One instance per container; supports `onDeactivation`.
+   */
   singleton(): SingletonBindingBuilder<Value>;
-  /** New instance on every resolution (default scope). */
+  /**
+   * New instance on every resolution (default scope).
+   */
   transient(): TransientBindingBuilder<Value>;
-  /** One instance per child container scope. */
+  /**
+   * One instance per child container scope.
+   */
   scoped(): ScopedBindingBuilder<Value>;
-  /** Called with the resolved instance after construction; the return value replaces the instance. */
+  /**
+   * Called with the resolved instance after construction; the return value replaces the instance.
+   */
   onActivation(handler: ActivationHandler<Value>): this;
-  /** @internal Keep public for runtime correctness; hidden from transient/scoped builders via type aliases. */
+  /**
+   * @internal Keep public for runtime correctness; hidden from transient/scoped builders via type aliases.
+   */
   onDeactivation(handler: DeactivationHandler<Value>): this;
-  /** This binding only resolves when the caller passes `{ name }` as the resolve hint. */
+  /**
+   * This binding only resolves when the caller passes `{ name }` as the resolve hint.
+   */
   whenNamed(name: string): this;
-  /** This binding only resolves when the caller passes `{ tag: [tag, tagValue] }` as the resolve hint. */
+  /**
+   * This binding only resolves when the caller passes `{ tag: [tag, tagValue] }` as the resolve hint.
+   */
   whenTagged(tag: string, tagValue: unknown): this;
-  /** Adds a custom predicate; all predicates must pass for the binding to be selected. */
+  /**
+   * Adds a custom predicate; all predicates must pass for the binding to be selected.
+   */
   when(constraint: (ctx: ConstraintContext) => boolean): this;
   /**
    * Returns the binding's stable ID, allocating one if needed.
@@ -187,9 +304,25 @@ declare class BindingBuilder<Value> {
    */
   id(): BindingIdentifier;
   id(identifier: BindingIdentifier): BindingIdentifier;
+  /**
+   * Records the chosen strategy and emits the first {@link Binding} snapshot.
+   * Throws {@link InternalError} if a strategy was already selected (double `to*()` call).
+   */
   private registerWithStrategy;
+  /**
+   * Re-creates the {@link Binding} snapshot from the current builder state and pushes
+   * the update to the registry. No-op if no strategy has been set yet.
+   */
   private refreshRegisteredBinding;
+  /**
+   * Guards against calling `.singleton()` / `.transient()` / `.scoped()` on a constant binding,
+   * which is locked to `"singleton"` scope by invariant.
+   */
   private assertScopeMutable;
+  /**
+   * Produces an immutable {@link Binding} snapshot from the current builder fields.
+   * Called by both {@link registerWithStrategy} and {@link refreshRegisteredBinding}.
+   */
   private createBinding;
 }
 /**

package/dist/binding.mjs

@@ -6,25 +6,80 @@ import { InternalError } from "./errors.mjs";
 function createBindingIdentifier() {
 	return globalThis.crypto.randomUUID();
 }
+/**
+* Fluent builder for registering a single binding against a {@link Token} or {@link Constructor}.
+*
+* A builder has two phases:
+* 1. **Strategy selection** — exactly one `to*()` call (`to`, `toSelf`, `toConstantValue`,
+*    `toDynamic`, `toDynamicAsync`, `toResolved`, `toAlias`) that determines how the value is produced.
+* 2. **Refinement chain** — optional calls to `singleton()`, `transient()`, `scoped()`,
+*    `onActivation()`, `onDeactivation()`, `whenNamed()`, `whenTagged()`, `when()`, and `id()`.
+*
+* Calling a second `to*()` method throws {@link InternalError}.
+*
+* The builder is created by {@link Container.bind} or by `bind` on {@link ModuleBuilder}.
+* The container injects {@link RegistryCallbacks} so that every strategy selection and
+* refinement is immediately reflected in the live registry.
+*/
 var BindingBuilder = class {
+	/**
+	* Current resolution strategy; starts as `"unset"` until a `to*()` method is called.
+	*/
 	strategy = { type: "unset" };
+	/**
+	* Lifetime scope applied to the next binding snapshot; defaults to `"transient"`.
+	*/
 	scope = "transient";
+	/**
+	* True after an explicit `.singleton()` / `.transient()` / `.scoped()` call (prevents constant scope change).
+	*/
 	isScopeExplicit = false;
+	/**
+	* Pre-allocated binding ID set via `id(identifier)` before the first `to*()` call.
+	*/
 	explicitId;
+	/**
+	* Resolve-hint name filter set by `.whenNamed()`.
+	*/
 	bindingName;
+	/**
+	* Tag filters accumulated by successive `.whenTagged()` calls.
+	*/
 	tags = /* @__PURE__ */ new Map();
+	/**
+	* Custom constraint predicates accumulated by `.when()`; all must pass for this binding to be selected.
+	*/
 	constraintPredicates = [];
+	/**
+	* Latest `onActivation` hook provided by `.onActivation(...)`.
+	* Applied to emitted binding snapshots until replaced.
+	*/
 	onActivationHandler;
+	/**
+	* Latest `onDeactivation` hook provided by `.onDeactivation(...)`.
+	* Emitted only on builder variants that expose deactivation support.
+	*/
 	onDeactivationHandler;
+	/**
+	* Set when this binding was created inside a {@link Module} / {@link AsyncModule} setup callback.
+	*/
 	moduleId;
+	/**
+	* The most recently emitted {@link Binding} snapshot; `undefined` before the first `to*()` call.
+	*/
 	currentBinding;
+	/**
+	* Container-injected hooks that sync builder mutations into the live registry.
+	*/
 	callbacks;
 	constructor(bindingKey, moduleId, callbacks) {
 		this.bindingKey = bindingKey;
 		this.moduleId = moduleId;
 		this.callbacks = callbacks ?? {};
 	}
-	/** Binds the token to a concrete implementation class; the container constructs it on demand. */
+	/**
+	* Binds the token to a concrete implementation class; the container constructs it on demand.
+	*/
 	to(implementationClass) {
 		this.registerWithStrategy({
 			type: "class",
@@ -32,7 +87,9 @@ var BindingBuilder = class {
 		});
 		return this;
 	}
-	/** Binds the class key to itself — only valid when the key is a constructor. */
+	/**
+	* Binds the class key to itself — only valid when the key is a constructor.
+	*/
 	toSelf() {
 		if (typeof this.bindingKey !== "function") throw new InternalError("toSelf() requires the binding key to be a constructor; use bind(SomeClass) or call to(Class) instead.");
 		this.registerWithStrategy({
@@ -41,7 +98,9 @@ var BindingBuilder = class {
 		});
 		return this;
 	}
-	/** Binds the token to a pre-existing value; always resolved as singleton, no construction. */
+	/**
+	* Binds the token to a pre-existing value; always resolved as singleton, no construction.
+	*/
 	toConstantValue(value) {
 		this.scope = "singleton";
 		this.registerWithStrategy({
@@ -50,7 +109,9 @@ var BindingBuilder = class {
 		});
 		return this;
 	}
-	/** Binds to a synchronous factory; `ctx` provides nested resolution within the same path. */
+	/**
+	* Binds to a synchronous factory; `ctx` provides nested resolution within the same path.
+	*/
 	toDynamic(factory) {
 		this.registerWithStrategy({
 			type: "dynamic",
@@ -58,7 +119,9 @@ var BindingBuilder = class {
 		});
 		return this;
 	}
-	/** Binds to an async factory; must be resolved via `resolveAsync` / `resolveAllAsync`. */
+	/**
+	* Binds to an async factory; must be resolved via `resolveAsync` / `resolveAllAsync`.
+	*/
 	toDynamicAsync(factory) {
 		this.registerWithStrategy({
 			type: "async-dynamic",
@@ -78,7 +141,9 @@ var BindingBuilder = class {
 		});
 		return this;
 	}
-	/** Redirects resolution to `targetToken`; the container resolves whatever is bound there. */
+	/**
+	* Redirects resolution to `targetToken`; the container resolves whatever is bound there.
+	*/
 	toAlias(targetToken) {
 		this.registerWithStrategy({
 			type: "alias",
@@ -86,7 +151,9 @@ var BindingBuilder = class {
 		});
 		return this;
 	}
-	/** One instance per container; supports `onDeactivation`. */
+	/**
+	* One instance per container; supports `onDeactivation`.
+	*/
 	singleton() {
 		this.assertScopeMutable();
 		this.scope = "singleton";
@@ -94,7 +161,9 @@ var BindingBuilder = class {
 		this.refreshRegisteredBinding();
 		return this;
 	}
-	/** New instance on every resolution (default scope). */
+	/**
+	* New instance on every resolution (default scope).
+	*/
 	transient() {
 		this.assertScopeMutable();
 		this.scope = "transient";
@@ -102,7 +171,9 @@ var BindingBuilder = class {
 		this.refreshRegisteredBinding();
 		return this;
 	}
-	/** One instance per child container scope. */
+	/**
+	* One instance per child container scope.
+	*/
 	scoped() {
 		this.assertScopeMutable();
 		this.scope = "scoped";
@@ -110,31 +181,41 @@ var BindingBuilder = class {
 		this.refreshRegisteredBinding();
 		return this;
 	}
-	/** Called with the resolved instance after construction; the return value replaces the instance. */
+	/**
+	* Called with the resolved instance after construction; the return value replaces the instance.
+	*/
 	onActivation(handler) {
 		this.onActivationHandler = handler;
 		this.refreshRegisteredBinding();
 		return this;
 	}
-	/** @internal Keep public for runtime correctness; hidden from transient/scoped builders via type aliases. */
+	/**
+	* @internal Keep public for runtime correctness; hidden from transient/scoped builders via type aliases.
+	*/
 	onDeactivation(handler) {
 		this.onDeactivationHandler = handler;
 		this.refreshRegisteredBinding();
 		return this;
 	}
-	/** This binding only resolves when the caller passes `{ name }` as the resolve hint. */
+	/**
+	* This binding only resolves when the caller passes `{ name }` as the resolve hint.
+	*/
 	whenNamed(name) {
 		this.bindingName = name;
 		this.refreshRegisteredBinding();
 		return this;
 	}
-	/** This binding only resolves when the caller passes `{ tag: [tag, tagValue] }` as the resolve hint. */
+	/**
+	* This binding only resolves when the caller passes `{ tag: [tag, tagValue] }` as the resolve hint.
+	*/
 	whenTagged(tag, tagValue) {
 		this.tags.set(tag, tagValue);
 		this.refreshRegisteredBinding();
 		return this;
 	}
-	/** Adds a custom predicate; all predicates must pass for the binding to be selected. */
+	/**
+	* Adds a custom predicate; all predicates must pass for the binding to be selected.
+	*/
 	when(constraint) {
 		this.constraintPredicates.push(constraint);
 		this.refreshRegisteredBinding();
@@ -152,6 +233,10 @@ var BindingBuilder = class {
 		this.explicitId = this.explicitId ?? createBindingIdentifier();
 		return this.explicitId;
 	}
+	/**
+	* Records the chosen strategy and emits the first {@link Binding} snapshot.
+	* Throws {@link InternalError} if a strategy was already selected (double `to*()` call).
+	*/
 	registerWithStrategy(next) {
 		if (this.strategy.type !== "unset") throw new InternalError("A binding strategy was already selected; only one to*(...) chain is allowed per builder.");
 		this.strategy = next;
@@ -160,15 +245,27 @@ var BindingBuilder = class {
 		this.currentBinding = binding;
 		this.callbacks.register?.(binding);
 	}
+	/**
+	* Re-creates the {@link Binding} snapshot from the current builder state and pushes
+	* the update to the registry. No-op if no strategy has been set yet.
+	*/
 	refreshRegisteredBinding() {
 		if (this.currentBinding === void 0 || this.strategy.type === "unset") return;
 		const next = this.createBinding(this.currentBinding.id, this.strategy);
 		this.currentBinding = next;
 		this.callbacks.update?.(next);
 	}
+	/**
+	* Guards against calling `.singleton()` / `.transient()` / `.scoped()` on a constant binding,
+	* which is locked to `"singleton"` scope by invariant.
+	*/
 	assertScopeMutable() {
 		if (this.strategy.type === "constant") throw new InternalError("Constant bindings are always singleton and do not support scope changes.");
 	}
+	/**
+	* Produces an immutable {@link Binding} snapshot from the current builder fields.
+	* Called by both {@link registerWithStrategy} and {@link refreshRegisteredBinding}.
+	*/
 	createBinding(id, strategy) {
 		const constraint = this.constraintPredicates.length === 0 ? void 0 : (ctx) => this.constraintPredicates.every((predicate) => predicate(ctx));
 		const lifecycle = {