@codefast/di 0.12.0 → 0.13.0

package/dist/errors.d.ts

@@ -28,7 +28,9 @@ export declare class TokenNotBoundError extends DiError {
     readonly name = "TokenNotBoundError";
     readonly code = "TOKEN_NOT_BOUND";
     readonly tokenName: string;
-    constructor(tokenName: string);
+    /** The token names from the outermost request down to the unbound one, which is last. */
+    readonly path: ReadonlyArray<string>;
+    constructor(tokenName: string, path?: ReadonlyArray<string>);
 }
 /**
  * A token that has bindings, none of whose slots match the given `ResolveOptions`.
@@ -41,7 +43,9 @@ export declare class NoMatchingBindingError extends DiError {
     readonly tokenName: string;
     readonly options: ResolveOptions;
     readonly availableSlots: Array<string>;
-    constructor(tokenName: string, options: ResolveOptions, availableSlots: Array<string>);
+    /** The token names from the outermost request down to the unmatched one, which is last. */
+    readonly path: ReadonlyArray<string>;
+    constructor(tokenName: string, options: ResolveOptions, availableSlots: Array<string>, path?: ReadonlyArray<string>);
 }
 /**
  * Two or more candidate bindings that matched without the more-specific rule deciding a winner.
@@ -162,7 +166,7 @@ export declare class UnreachableLifecycleHookError extends DiError {
     readonly code = "UNREACHABLE_LIFECYCLE_HOOK";
     readonly tokenName: string;
     readonly phase: "onActivation" | "onDeactivation";
-    /** Nothing binds the token, or — for a deactivation hook — every binding it has is transient or scoped. */
+    /** Nothing binds the token, or — for a deactivation hook — every binding it has is transient. */
     readonly reason: "unbound" | "no-deactivatable-binding";
     constructor(tokenName: string, phase: "onActivation" | "onDeactivation", reason?: "unbound" | "no-deactivatable-binding");
 }
@@ -207,16 +211,6 @@ export declare class AsyncModuleLoadError extends DiError {
     readonly moduleName: string;
     constructor(moduleName: string);
 }
-/**
- * A synchronous disposal attempt on a container whose `onDeactivation` handlers may be async.
- *
- * @since 0.3.16-canary.0
- */
-export declare class SyncDisposalNotSupportedError extends DiError {
-    readonly name = "SyncDisposalNotSupportedError";
-    readonly code = "SYNC_DISPOSAL_NOT_SUPPORTED";
-    constructor();
-}
 /**
  * A `scoped` binding resolved from a container with no child scope context.
  *
@@ -342,6 +336,21 @@ export declare class SymbolKeyedLifecycleError extends DiError {
     readonly memberName: string;
     constructor(decoratorName: string, memberName: string);
 }
+/**
+ * A `@postConstruct` or `@preDestroy` on a private method, which the lifecycle reader cannot call by name.
+ *
+ * @remarks Reported at decoration rather than at resolve, so the error points at the declaration
+ * instead of a `MetadataReader` the caller never configured.
+ *
+ * @since 0.13.0
+ */
+export declare class PrivateLifecycleMethodError extends DiError {
+    readonly name = "PrivateLifecycleMethodError";
+    readonly code = "PRIVATE_LIFECYCLE_METHOD";
+    readonly decoratorName: string;
+    readonly memberName: string;
+    constructor(decoratorName: string, memberName: string);
+}
 /**
  * A decorator handed no metadata object, because the runtime has no `Symbol.metadata` to key one by.
  *

package/dist/errors.js

@@ -18,6 +18,10 @@ export class InternalError extends DiError {
         super(message);
     }
 }
+// A path of one token only repeats the name the message already opens with.
+function pathSuffix(path) {
+    return path.length > 1 ? ` Path: ${path.join(" → ")}` : "";
+}
 /**
  * A token with no binding at all, even after walking the parent container chain.
  *
@@ -27,9 +31,12 @@ export class TokenNotBoundError extends DiError {
     name = "TokenNotBoundError";
     code = "TOKEN_NOT_BOUND";
     tokenName;
-    constructor(tokenName) {
-        super(`No binding found for token '${tokenName}'. Did you forget container.bind(${tokenName})?`);
+    /** The token names from the outermost request down to the unbound one, which is last. */
+    path;
+    constructor(tokenName, path = [tokenName]) {
+        super(`No binding found for token '${tokenName}'. Did you forget container.bind(${tokenName})?${pathSuffix(path)}`);
         this.tokenName = tokenName;
+        this.path = path;
     }
 }
 // Options carry caller values a tag may hold — a bigint or a circular object must not make the
@@ -78,13 +85,16 @@ export class NoMatchingBindingError extends DiError {
     tokenName;
     options;
     availableSlots;
-    constructor(tokenName, options, availableSlots) {
+    /** The token names from the outermost request down to the unmatched one, which is last. */
+    path;
+    constructor(tokenName, options, availableSlots, path = [tokenName]) {
         const optionsString = describeResolveOptions(options);
         const slotsStr = availableSlots.join(", ");
-        super(`No binding for '${tokenName}' matching ${optionsString}. Available slots: [${slotsStr}].`);
+        super(`No binding for '${tokenName}' matching ${optionsString}. Available slots: [${slotsStr}].${pathSuffix(path)}`);
         this.tokenName = tokenName;
         this.options = options;
         this.availableSlots = availableSlots;
+        this.path = path;
     }
 }
 /**
@@ -225,12 +235,12 @@ export class UnreachableLifecycleHookError extends DiError {
     code = "UNREACHABLE_LIFECYCLE_HOOK";
     tokenName;
     phase;
-    /** Nothing binds the token, or — for a deactivation hook — every binding it has is transient or scoped. */
+    /** Nothing binds the token, or — for a deactivation hook — every binding it has is transient. */
     reason;
     constructor(tokenName, phase, reason = "unbound") {
         super(reason === "unbound"
             ? `${phase}() is registered for '${tokenName}', which nothing is bound to in this container or its ancestors, so the hook can never run. Bind the token, or — if '${tokenName}' is a class you bound as an implementation via .to(${tokenName}) — register the hook against the token you bound instead.`
-            : `${phase}() is registered for '${tokenName}', whose every binding in this container and its ancestors is transient or scoped, so the hook can never run: only a singleton or a constant is deactivated. Make one of its bindings a singleton, or drop the hook.`);
+            : `${phase}() is registered for '${tokenName}', whose every binding in this container and its ancestors is transient, so the hook can never run: a transient instance is never deactivated. Make one of its bindings a singleton or scoped, or drop the hook.`);
         this.tokenName = tokenName;
         this.phase = phase;
         this.reason = reason;
@@ -286,18 +296,6 @@ export class AsyncModuleLoadError extends DiError {
         this.moduleName = moduleName;
     }
 }
-/**
- * A synchronous disposal attempt on a container whose `onDeactivation` handlers may be async.
- *
- * @since 0.3.16-canary.0
- */
-export class SyncDisposalNotSupportedError extends DiError {
-    name = "SyncDisposalNotSupportedError";
-    code = "SYNC_DISPOSAL_NOT_SUPPORTED";
-    constructor() {
-        super("Container cannot be disposed synchronously because onDeactivation handlers may be async. Use `await using` or call container.dispose() explicitly.");
-    }
-}
 /**
  * A `scoped` binding resolved from a container with no child scope context.
  *
@@ -456,6 +454,25 @@ export class SymbolKeyedLifecycleError extends DiError {
         this.memberName = memberName;
     }
 }
+/**
+ * A `@postConstruct` or `@preDestroy` on a private method, which the lifecycle reader cannot call by name.
+ *
+ * @remarks Reported at decoration rather than at resolve, so the error points at the declaration
+ * instead of a `MetadataReader` the caller never configured.
+ *
+ * @since 0.13.0
+ */
+export class PrivateLifecycleMethodError extends DiError {
+    name = "PrivateLifecycleMethodError";
+    code = "PRIVATE_LIFECYCLE_METHOD";
+    decoratorName;
+    memberName;
+    constructor(decoratorName, memberName) {
+        super(`@${decoratorName}() does not support a private method ('${memberName}'). Make the lifecycle method public, and call the private code from it.`);
+        this.decoratorName = decoratorName;
+        this.memberName = memberName;
+    }
+}
 /**
  * A decorator handed no metadata object, because the runtime has no `Symbol.metadata` to key one by.
  *

package/dist/index.d.ts

@@ -29,7 +29,7 @@ export { MetadataReaderToken } from "#metadata/reader-token";
 export type { ConstructorMetadata, LifecycleMetadata, MetadataReader, MutableLifecycleMetadata, ParamMetadata, } from "#metadata/types";
 export { defaultMetadataReader, SymbolMetadataReader } from "#metadata/symbol-reader";
 export { whenAnyAncestorIs, whenAnyAncestorNamed, whenAnyAncestorTagged, whenAnyAncestorTaggedAll, whenNoAncestorIs, whenNoParentIs, whenParentIs, whenParentNamed, whenParentTagged, whenParentTaggedAll, } from "#resolution/select/constraints";
-export { AmbiguousBindingError, AsyncActivationError, AsyncDeactivationError, AsyncModuleLoadError, AsyncResolutionError, ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, CircularDependencyError, DiError, DisposedContainerError, InternalError, InvalidBindingDeclarationError, InvalidMetadataError, MissingContainerContextError, MissingDecoratorMetadataError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, RebindUnboundTokenError, ScopeViolationError, SelfBindingRequiresClassError, StaticMemberDecoratorError, SymbolKeyedLifecycleError, SyncDisposalNotSupportedError, EmptyTagCriteriaError, TokenNotBoundError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors";
+export { AmbiguousBindingError, AsyncActivationError, AsyncDeactivationError, AsyncModuleLoadError, AsyncResolutionError, ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, CircularDependencyError, DiError, DisposedContainerError, InternalError, InvalidBindingDeclarationError, InvalidMetadataError, MissingContainerContextError, MissingDecoratorMetadataError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, RebindUnboundTokenError, ScopeViolationError, SelfBindingRequiresClassError, PrivateLifecycleMethodError, StaticMemberDecoratorError, SymbolKeyedLifecycleError, EmptyTagCriteriaError, TokenNotBoundError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors";
 export type { ScopeViolationDetails } from "#errors";
 export { toDotGraph } from "#introspection/graph-adapters/dot";
 export { toCytoscapeGraph } from "#introspection/graph-adapters/cytoscape";

package/dist/index.js

@@ -26,7 +26,7 @@ export { defaultMetadataReader, SymbolMetadataReader } from "#metadata/symbol-re
 // Constraints — contextual injection predicates for .when()
 export { whenAnyAncestorIs, whenAnyAncestorNamed, whenAnyAncestorTagged, whenAnyAncestorTaggedAll, whenNoAncestorIs, whenNoParentIs, whenParentIs, whenParentNamed, whenParentTagged, whenParentTaggedAll, } from "#resolution/select/constraints";
 // Errors
-export { AmbiguousBindingError, AsyncActivationError, AsyncDeactivationError, AsyncModuleLoadError, AsyncResolutionError, ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, CircularDependencyError, DiError, DisposedContainerError, InternalError, InvalidBindingDeclarationError, InvalidMetadataError, MissingContainerContextError, MissingDecoratorMetadataError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, RebindUnboundTokenError, ScopeViolationError, SelfBindingRequiresClassError, StaticMemberDecoratorError, SymbolKeyedLifecycleError, SyncDisposalNotSupportedError, EmptyTagCriteriaError, TokenNotBoundError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors";
+export { AmbiguousBindingError, AsyncActivationError, AsyncDeactivationError, AsyncModuleLoadError, AsyncResolutionError, ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, CircularDependencyError, DiError, DisposedContainerError, InternalError, InvalidBindingDeclarationError, InvalidMetadataError, MissingContainerContextError, MissingDecoratorMetadataError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, RebindUnboundTokenError, ScopeViolationError, SelfBindingRequiresClassError, PrivateLifecycleMethodError, StaticMemberDecoratorError, SymbolKeyedLifecycleError, EmptyTagCriteriaError, TokenNotBoundError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors";
 // Graph adapters — render `generateDependencyGraph()` output for common viewers
 export { toDotGraph } from "#introspection/graph-adapters/dot";
 export { toCytoscapeGraph } from "#introspection/graph-adapters/cytoscape";

package/dist/introspection/explanation.js

@@ -3,7 +3,7 @@ import { tokenName } from "#core/token";
 import { AmbiguousBindingError, CircularDependencyError, InternalError, NoMatchingBindingError, TokenNotBoundError, } from "#errors";
 import { snapshotOf } from "#introspection/inspector";
 import { DefaultConstraintContext } from "#resolution/context";
-import { buildResolutionFrame } from "#resolution/path";
+import { buildResolutionFrame, missPathOf } from "#resolution/path";
 import { candidateRuleOf, chooseCandidate, matchesSlot } from "#resolution/select/candidates";
 // ── Explanation ──────────────────────────────────────────────────────────────────────────────────────────────────────
 /**
@@ -21,7 +21,7 @@ export function explainRequest(registries, token, options) {
     for (const ancestor of options?.ancestors ?? []) {
         const walk = walkLookup(registries, ancestor, undefined, stack);
         if (walk.binding === undefined) {
-            throw lookupError(registries, walk);
+            throw lookupError(registries, ancestor, walk, stack);
         }
         stack.push(buildResolutionFrame(walk.binding, tokenName(walk.binding.token)));
     }
@@ -57,15 +57,32 @@ function walkLookup(registries, token, request, stack) {
                 lastToken: current,
                 ambiguity: found.eligible,
                 cycle: undefined,
+                aliasHops: visited,
             };
         }
         if (found.kind === "none") {
             const outcome = registries.some((registry) => registry.getAll(current).length > 0) ? "unmatched" : "unbound";
-            return { steps, binding: undefined, outcome, lastToken: current, ambiguity: undefined, cycle: undefined };
+            return {
+                steps,
+                binding: undefined,
+                outcome,
+                lastToken: current,
+                ambiguity: undefined,
+                cycle: undefined,
+                aliasHops: visited,
+            };
         }
         const binding = found.binding;
         if (binding.kind !== "alias") {
-            return { steps, binding, outcome: "selected", lastToken: current, ambiguity: undefined, cycle: undefined };
+            return {
+                steps,
+                binding,
+                outcome: "selected",
+                lastToken: current,
+                ambiguity: undefined,
+                cycle: undefined,
+                aliasHops: visited,
+            };
         }
         // An alias hop restarts at the container asked, as `resolve` does, and a revisited token is a cycle.
         const target = binding.target;
@@ -78,6 +95,7 @@ function walkLookup(registries, token, request, stack) {
                 lastToken: current,
                 ambiguity: undefined,
                 cycle: [...visited, target],
+                aliasHops: visited,
             };
         }
         visited.add(target);
@@ -133,8 +151,8 @@ function verdictOf(binding, request, ctx) {
     const predicate = binding.predicate;
     return predicate === undefined || predicate(ctx) ? "eligible" : "predicate-refused";
 }
-/** The error `resolve` throws for a lookup that ended without a binding. */
-function lookupError(registries, walk) {
+/** The error `resolve` throws for a lookup that ended without a binding, named along the path it was made from. */
+function lookupError(registries, requested, walk, stack) {
     const name = tokenName(walk.lastToken);
     switch (walk.outcome) {
         case "ambiguous":
@@ -142,9 +160,9 @@ function lookupError(registries, walk) {
         case "alias-cycle":
             return new CircularDependencyError((walk.cycle ?? []).map((entry) => tokenName(entry)));
         case "unmatched":
-            return new NoMatchingBindingError(name, {}, registries.flatMap((registry) => registry.getAll(walk.lastToken).map((binding) => bindingSlotToString(binding.slot))));
+            return new NoMatchingBindingError(name, {}, registries.flatMap((registry) => registry.getAll(walk.lastToken).map((binding) => bindingSlotToString(binding.slot))), missPathOf(stack, requested, walk.aliasHops));
         case "unbound":
-            return new TokenNotBoundError(name);
+            return new TokenNotBoundError(name, missPathOf(stack, requested, walk.aliasHops));
         case "selected":
             return new InternalError("a lookup that selected a binding has no error");
     }

package/dist/lifecycle/hooks.d.ts

@@ -17,6 +17,8 @@ export declare class LifecycleManager {
     registerDeactivation<Value>(token: Token<Value> | Constructor<Value>, handler: DeactivationHandler<Value>): void;
     /** Asked only while tearing down, so it reads the map directly rather than caching like activation. */
     hasDeactivationHandlers<Value>(token: Token<Value> | Constructor<Value>): boolean;
+    /** Whether deactivating an instance of a binding runs anything: a container hook, the binding's own, or `@preDestroy()`. */
+    owesDeactivation(binding: Binding, metadataReader: MetadataReader): boolean;
     /** Every token carrying a container-level hook, paired with the phase that registered it. */
     hookedTokens(): Array<[DependencyKey, "onActivation" | "onDeactivation"]>;
     /**

package/dist/lifecycle/hooks.js

@@ -62,6 +62,12 @@ export class LifecycleManager {
         const list = this.#deactivationHooks?.get(token);
         return list !== undefined && list.length > 0;
     }
+    /** Whether deactivating an instance of a binding runs anything: a container hook, the binding's own, or `@preDestroy()`. */
+    owesDeactivation(binding, metadataReader) {
+        return (this.hasDeactivationHandlers(binding.token) ||
+            (binding.kind !== "alias" && binding.deactivationHook !== undefined) ||
+            this.#lifecycleMethods(binding, metadataReader, "preDestroy").length > 0);
+    }
     /** Every token carrying a container-level hook, paired with the phase that registered it. */
     hookedTokens() {
         const hooked = [];

package/dist/lifecycle/scopes.d.ts

@@ -1,5 +1,15 @@
 import type { Binding } from "#core/binding";
 import type { BindingIdentifier } from "#core/types";
+/**
+ * What deactivates a scoped instance: the resolver owning its binding, which activated it.
+ *
+ * @remarks Answers `undefined` when the binding owes no teardown, so disposing a per-request child awaits nothing.
+ *
+ * @since 0.13.0
+ */
+export interface ScopedInstanceOwner {
+    deactivateScoped(binding: Binding, instance: unknown): Promise<void> | undefined;
+}
 /**
  * One container's instance caches — singletons, in-flight async creations, and the scoped cache.
  *
@@ -28,9 +38,18 @@ export declare class ScopeManager {
      */
     readScoped(key: BindingIdentifier): unknown;
     /** Takes the binding rather than its id, so a failure here can name the token — as `setSingleton` does. */
-    setScoped(binding: Binding, instance: unknown): void;
-    /** Releases a removed binding's scoped instance, by its scoped cache key. A scoped instance has no deactivation. */
+    setScoped(binding: Binding, instance: unknown, owner: ScopedInstanceOwner): void;
+    /** Drops the instance cached under a scoped cache key, owing it nothing — what a binding leaving `scoped` retires. */
     deleteScoped(key: BindingIdentifier): void;
+    /** Removes the instance cached under a scoped cache key and hands it back, or {@link SCOPED_MISS} when none is. */
+    takeScoped(key: BindingIdentifier): unknown;
+    /**
+     * Deactivates every cached scoped instance through its owner, the latest cached first and one at a time, collecting
+     * each failure into `errors` — or answers `undefined` when no owner had a teardown to run.
+     *
+     * @remarks A binding cached again after its instance was taken is listed twice; only its current instance is owed.
+     */
+    deactivateScoped(errors: Array<unknown>): Promise<void> | undefined;
     /** Scoped instances currently cached — a structural count for diagnostics. */
     get scopedCount(): number;
     clearAll(): void;

package/dist/lifecycle/scopes.js

@@ -13,6 +13,12 @@ export class ScopeManager {
     #inflight;
     // Scoped cache — only a child container resolving a `scoped` binding ever needs it.
     #scoped;
+    // Scoped bindings in the order their instances were cached, each beside its owner, so disposal can deactivate them
+    // latest first. The first sits in fields: a per-request child caching one scoped instance allocates nothing for it.
+    #firstScopedBinding;
+    #firstScopedOwner;
+    #laterScopedBindings;
+    #laterScopedOwners;
     // Set once by the owning container's dispose — refuses new materializations into torn-down state.
     #closed = false;
     isChild;
@@ -101,16 +107,90 @@ export class ScopeManager {
         return scoped.has(key) ? undefined : SCOPED_MISS;
     }
     /** Takes the binding rather than its id, so a failure here can name the token — as `setSingleton` does. */
-    setScoped(binding, instance) {
+    setScoped(binding, instance, owner) {
         if (!this.isChild) {
             throw new MissingScopeContextError(tokenName(binding.token));
         }
         (this.#scoped ??= new Map()).set(binding.scopedCacheKey, instance);
+        if (this.#firstScopedBinding === undefined) {
+            this.#firstScopedBinding = binding;
+            this.#firstScopedOwner = owner;
+        }
+        else {
+            (this.#laterScopedBindings ??= []).push(binding);
+            (this.#laterScopedOwners ??= []).push(owner);
+        }
     }
-    /** Releases a removed binding's scoped instance, by its scoped cache key. A scoped instance has no deactivation. */
+    /** Drops the instance cached under a scoped cache key, owing it nothing — what a binding leaving `scoped` retires. */
     deleteScoped(key) {
         this.#scoped?.delete(key);
     }
+    /** Removes the instance cached under a scoped cache key and hands it back, or {@link SCOPED_MISS} when none is. */
+    takeScoped(key) {
+        const scoped = this.#scoped;
+        if (scoped === undefined || !scoped.has(key)) {
+            return SCOPED_MISS;
+        }
+        const instance = scoped.get(key);
+        scoped.delete(key);
+        return instance;
+    }
+    /**
+     * Deactivates every cached scoped instance through its owner, the latest cached first and one at a time, collecting
+     * each failure into `errors` — or answers `undefined` when no owner had a teardown to run.
+     *
+     * @remarks A binding cached again after its instance was taken is listed twice; only its current instance is owed.
+     */
+    deactivateScoped(errors) {
+        if (this.#firstScopedBinding === undefined) {
+            return undefined;
+        }
+        return this.#deactivateScopedFrom(this.#laterScopedBindings?.length ?? 0, errors);
+    }
+    // Positions count down from the latest: `position - 1` in the later lists while positive, then the first at 0.
+    #deactivateScopedFrom(position, errors) {
+        for (let current = position; current >= 0; current -= 1) {
+            const pending = this.#deactivateScopedAt(current, errors);
+            if (pending !== undefined) {
+                return this.#finishDeactivatingScoped(pending, current - 1, errors);
+            }
+        }
+        return undefined;
+    }
+    // The rest of the walk once a teardown is pending: each one settles before the next starts.
+    async #finishDeactivatingScoped(pending, position, errors) {
+        let current = pending;
+        for (let next = position;; next -= 1) {
+            if (current !== undefined) {
+                try {
+                    await current;
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            if (next < 0) {
+                return;
+            }
+            current = this.#deactivateScopedAt(next, errors);
+        }
+    }
+    #deactivateScopedAt(position, errors) {
+        const binding = position === 0 ? this.#firstScopedBinding : this.#laterScopedBindings[position - 1];
+        const owner = position === 0 ? this.#firstScopedOwner : this.#laterScopedOwners[position - 1];
+        // The first is read last, so only a later entry can find a key cached twice; taking it leaves the rest a miss.
+        const instance = position === 0 ? this.readScoped(binding.scopedCacheKey) : this.takeScoped(binding.scopedCacheKey);
+        if (instance === SCOPED_MISS) {
+            return undefined;
+        }
+        try {
+            return owner.deactivateScoped(binding, instance);
+        }
+        catch (error) {
+            errors.push(error);
+            return undefined;
+        }
+    }
     /** Scoped instances currently cached — a structural count for diagnostics. */
     get scopedCount() {
         return this.#scoped?.size ?? 0;
@@ -126,6 +206,10 @@ export class ScopeManager {
         }
         this.#inflight?.clear();
         this.#scoped?.clear();
+        this.#firstScopedBinding = undefined;
+        this.#firstScopedOwner = undefined;
+        this.#laterScopedBindings = undefined;
+        this.#laterScopedOwners = undefined;
     }
     /** Whether the deferred scoped-instance cache has had to be built. */
     get isScopedCacheBuilt() {

package/dist/metadata/keys.d.ts

@@ -17,7 +17,7 @@ export declare const LIFECYCLE_KEY: unique symbol;
  */
 export declare const INJECT_ACCESSOR_KEY: unique symbol;
 /**
- * The symbol TC39 Stage 3 decorator transforms store class metadata under.
+ * The symbol standard decorator transforms store class metadata under.
  *
  * @remarks Falls back to the global-registry symbol, which is what Babel and esbuild emit until
  * a runtime ships `Symbol.metadata` natively.

package/dist/metadata/keys.js

@@ -17,7 +17,7 @@ export const LIFECYCLE_KEY = Symbol("di:lifecycle");
  */
 export const INJECT_ACCESSOR_KEY = Symbol("di:inject-accessor");
 /**
- * The symbol TC39 Stage 3 decorator transforms store class metadata under.
+ * The symbol standard decorator transforms store class metadata under.
  *
  * @remarks Falls back to the global-registry symbol, which is what Babel and esbuild emit until
  * a runtime ships `Symbol.metadata` natively.

package/dist/resolution/path.d.ts

@@ -1,5 +1,6 @@
 import type { Binding } from "#core/binding";
-import type { ResolutionFrame } from "#core/types";
+import type { Token } from "#core/token";
+import type { Constructor, ResolutionFrame } from "#core/types";
 /**
  * Creates the resolution-stack frame for one in-flight resolve of a binding.
  *
@@ -17,11 +18,20 @@ export declare function buildResolutionFrame(binding: Binding, tokenName: string
  */
 export declare function bindingsOf(frames: ReadonlyArray<ResolutionFrame>): Array<Binding>;
 /**
- * The token names along a stack plus the frame that closed the cycle — built only to throw.
+ * The token names along a stack plus the one ending the path, a cycle's closing frame or a miss — built only to throw.
  *
  * @since 0.6.0
  */
 export declare function cycleNamesOf(resolutionStack: ReadonlyArray<ResolutionFrame>, closingName: string): Array<string>;
+/**
+ * The token names from the outermost request to a lookup that selected nothing, its alias hops included.
+ *
+ * @remarks `aliasHops` is the set an alias walk keeps, which starts at `requested` — the name the path already
+ * ends on.
+ *
+ * @since 0.13.0
+ */
+export declare function missPathOf(resolutionStack: ReadonlyArray<ResolutionFrame>, requested: Token<unknown> | Constructor, aliasHops: ReadonlySet<Token<unknown> | Constructor> | undefined): Array<string>;
 /**
  * Marks a level in flight on a synchronous path and pushes its frame, throwing if its binding already is.
  *

package/dist/resolution/path.js

@@ -1,4 +1,5 @@
-/** Cycle-detection bookkeeping carried on the resolution stack itself. */
+import { tokenName } from "#core/token";
+/** The resolution path: cycle bookkeeping carried on the stack itself, and the names an error prints. */
 import { CircularDependencyError } from "#errors";
 /** The key under which a resolver-built frame carries its binding, for marking a seeded path. */
 const FRAME_BINDING = Symbol("di:frame-binding");
@@ -38,7 +39,7 @@ export function bindingsOf(frames) {
     return bindings;
 }
 /**
- * The token names along a stack plus the frame that closed the cycle — built only to throw.
+ * The token names along a stack plus the one ending the path, a cycle's closing frame or a miss — built only to throw.
  *
  * @since 0.6.0
  */
@@ -50,6 +51,25 @@ export function cycleNamesOf(resolutionStack, closingName) {
     names[resolutionStack.length] = closingName;
     return names;
 }
+/**
+ * The token names from the outermost request to a lookup that selected nothing, its alias hops included.
+ *
+ * @remarks `aliasHops` is the set an alias walk keeps, which starts at `requested` — the name the path already
+ * ends on.
+ *
+ * @since 0.13.0
+ */
+export function missPathOf(resolutionStack, requested, aliasHops) {
+    const path = cycleNamesOf(resolutionStack, tokenName(requested));
+    if (aliasHops !== undefined) {
+        for (const hop of aliasHops) {
+            if (hop !== requested) {
+                path.push(tokenName(hop));
+            }
+        }
+    }
+    return path;
+}
 /**
  * Marks a level in flight on a synchronous path and pushes its frame, throwing if its binding already is.
  *

package/dist/resolution/resolver.d.ts

@@ -3,6 +3,7 @@ import type { Binding } from "#core/binding";
 import type { BindingRegistry } from "#core/registry";
 import type { Token } from "#core/token";
 import type { BindingTag, Constructor, ResolutionFrame, ResolveOptions } from "#core/types";
+import { NoMatchingBindingError, TokenNotBoundError } from "#errors";
 import type { ResolutionDiagnostics } from "#introspection/diagnostics";
 import type { LifecycleManager } from "#lifecycle/hooks";
 import type { ScopeManager } from "#lifecycle/scopes";
@@ -39,6 +40,17 @@ export declare class DependencyResolver implements ResolverCallbacks {
      * Mirrors {@link DependencyResolver.resolveAll} candidate selection only (no instantiation).
      */
     peekCandidateBindingsForValidate(token: Token<unknown> | Constructor, options: ResolveOptions | undefined): ReadonlyArray<Binding>;
+    /**
+     * The error `resolve` raises for a request nothing selects, or `undefined` while a `when()` candidate leaves it open.
+     *
+     * @remarks A predicate reads the resolution path, which a static walk does not have, so a slot-matching candidate
+     * that carries one may still be selected when the request is really made.
+     */
+    missForValidate(token: Token<unknown> | Constructor, options: ResolveOptions | undefined, path: ReadonlyArray<string>): TokenNotBoundError | NoMatchingBindingError | undefined;
+    /** The resolver whose chain a binding this one can see resolves its dependencies from, as a singleton does. */
+    ownerForValidate(binding: Binding): DependencyResolver;
+    /** Deactivates a scoped instance of a binding this resolver owns, with its hooks and reader, when it owes a teardown. */
+    deactivateScoped(binding: Binding, instance: unknown): Promise<void> | undefined;
     resolveFromContext<Value>(token: Token<Value> | Constructor<Value>, resolutionStack: Array<ResolutionFrame>): Value;
     resolve<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>, precomputedCriterion?: BindingTag | null): Value;
     resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>, precomputedCriterion?: BindingTag | null): Value | undefined;