@codefast/di 0.5.0 → 0.6.1

package/dist/resolution/cache/class-introspector.js

@@ -0,0 +1,194 @@
+/**
+ * Per-class decorator metadata, cached by constructor.
+ *
+ * @remarks Metadata cannot change once a class is defined, so nothing here needs version stamping.
+ */
+import { runWithAmbientResolution } from "#/ambient/active-container";
+import { InvalidMetadataError } from "#/errors/errors";
+// Verified pairs, not verified classes: two readers may disagree about the same class, and a reader
+// that goes out of scope takes its record with it.
+const verifiedTargets = new WeakMap();
+const verifiedLifecycleTargets = new WeakMap();
+const verifiedAccessorTargets = new WeakMap();
+function isVerified(cache, reader, target) {
+    return cache.get(reader)?.has(target) ?? false;
+}
+function markVerified(cache, reader, target) {
+    let verified = cache.get(reader);
+    if (verified === undefined) {
+        verified = new WeakSet();
+        cache.set(reader, verified);
+    }
+    verified.add(target);
+}
+/**
+ * A reader's constructor metadata for a class, verified the first time this process asks.
+ *
+ * @remarks Metadata cannot change once a class is defined, so re-checking per container would charge
+ * every fresh container for a fact already established — a per-request child or a cold boot pays
+ * that repeatedly.
+ *
+ * @since 0.6.0
+ */
+export function verifyConstructorMetadata(reader, target) {
+    const metadata = reader.getConstructorMetadata(target);
+    if (metadata === undefined) {
+        return undefined;
+    }
+    if (isVerified(verifiedTargets, reader, target)) {
+        return metadata;
+    }
+    assertConstructorMetadata(metadata, target);
+    markVerified(verifiedTargets, reader, target);
+    return metadata;
+}
+/**
+ * Verifies what a reader claims about a class, since a `MetadataReader` is a public seam.
+ *
+ * @remarks Every path that reads constructor metadata comes through here, so a reader that answers
+ * wrongly is a named error at the class it described rather than a `TypeError` raised later inside a
+ * resolve. Only what a consumer dereferences is checked: `params` and each entry's `token`.
+ * `optional`/`multi` degrade to falsy without crashing, and `index` is decorative — dependencies are
+ * consumed positionally.
+ *
+ * @since 0.6.0
+ */
+export function assertConstructorMetadata(metadata, target) {
+    if (metadata === undefined) {
+        return undefined;
+    }
+    if (typeof metadata !== "object" || metadata === null) {
+        throw new InvalidMetadataError(target.name, `constructor metadata: expected an object, received ${typeof metadata}`);
+    }
+    const params = Reflect.get(metadata, "params");
+    if (!Array.isArray(params)) {
+        throw new InvalidMetadataError(target.name, "constructor metadata: params is not an array");
+    }
+    for (const [position, param] of params.entries()) {
+        if (typeof param !== "object" || param === null) {
+            throw new InvalidMetadataError(target.name, `constructor metadata: params[${String(position)}] is not an object`);
+        }
+        const dependency = Reflect.get(param, "token");
+        if (typeof dependency !== "object" && typeof dependency !== "function") {
+            throw new InvalidMetadataError(target.name, `constructor metadata: params[${String(position)}].token is not a token or a class`);
+        }
+    }
+    return metadata;
+}
+/**
+ * A reader's lifecycle metadata for a class, verified the first time this process asks.
+ *
+ * @since 0.6.0
+ */
+export function verifyLifecycleMetadata(reader, target) {
+    const metadata = reader.getLifecycleMetadata(target);
+    if (metadata === undefined || isVerified(verifiedLifecycleTargets, reader, target)) {
+        return metadata;
+    }
+    if (typeof metadata !== "object" || metadata === null) {
+        throw new InvalidMetadataError(target.name, `lifecycle metadata: expected an object, received ${typeof metadata}`);
+    }
+    for (const phase of ["postConstruct", "preDestroy"]) {
+        const methods = Reflect.get(metadata, phase);
+        if (methods === undefined) {
+            continue;
+        }
+        if (!Array.isArray(methods)) {
+            throw new InvalidMetadataError(target.name, `lifecycle metadata: ${phase} is not an array`);
+        }
+        for (const [position, name] of methods.entries()) {
+            if (typeof name !== "string") {
+                throw new InvalidMetadataError(target.name, `lifecycle metadata: ${phase}[${String(position)}] is not a string`);
+            }
+        }
+    }
+    markVerified(verifiedLifecycleTargets, reader, target);
+    return metadata;
+}
+/**
+ * A reader's accessor metadata for a class, verified the first time this process asks.
+ *
+ * @since 0.6.0
+ */
+export function verifyAccessorMetadata(reader, target) {
+    const metadata = reader.getAccessorMetadata?.(target);
+    if (metadata === undefined || isVerified(verifiedAccessorTargets, reader, target)) {
+        return metadata;
+    }
+    if (!Array.isArray(metadata)) {
+        throw new InvalidMetadataError(target.name, "accessor metadata: expected an array");
+    }
+    for (const [position, entry] of metadata.entries()) {
+        if (typeof entry !== "object" || entry === null) {
+            throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}] is not an object`);
+        }
+        const key = Reflect.get(entry, "key");
+        if (typeof key !== "string" && typeof key !== "symbol") {
+            throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}].key is not a string or symbol`);
+        }
+        const descriptor = Reflect.get(entry, "descriptor");
+        if (typeof descriptor !== "object" || descriptor === null) {
+            throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}].descriptor is not an object`);
+        }
+        const dependency = Reflect.get(descriptor, "token");
+        if (typeof dependency !== "object" && typeof dependency !== "function") {
+            throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}].descriptor.token is not a token or a class`);
+        }
+    }
+    markVerified(verifiedAccessorTargets, reader, target);
+    return metadata;
+}
+/**
+ * @since 0.5.0-canary.8
+ */
+export class ClassIntrospector {
+    // Unallocated until the container resolves its first class binding — a container bound entirely
+    // to constants, factories or aliases never introspects one.
+    #constructorMetadata;
+    #hasPostConstruct;
+    #needsActiveContainer;
+    #reader;
+    #container;
+    constructor(reader, container) {
+        this.#reader = reader;
+        this.#container = container;
+    }
+    constructorMetadata(target) {
+        const cached = this.#constructorMetadata?.get(target);
+        if (cached !== undefined) {
+            return cached === null ? undefined : cached;
+        }
+        const metadata = this.#reader.getConstructorMetadata(target);
+        (this.#constructorMetadata ??= new WeakMap()).set(target, metadata ?? null);
+        return metadata;
+    }
+    /**
+     * Whether the class has a `@postConstruct` hook, or `undefined` until {@link discoverPostConstruct}.
+     *
+     * @remarks Callers treat unknown as "assume it does", so the first activation settles it.
+     */
+    knownPostConstruct(target) {
+        return this.#hasPostConstruct?.get(target);
+    }
+    discoverPostConstruct(target) {
+        const lifecycle = this.#reader.getLifecycleMetadata(target);
+        (this.#hasPostConstruct ??= new WeakMap()).set(target, lifecycle !== undefined && lifecycle.postConstruct !== undefined && lifecycle.postConstruct.length > 0);
+    }
+    /** True when the class has accessor injection, which reads the container during construction. */
+    needsActiveContainer(target) {
+        let needsActiveContainer = this.#needsActiveContainer?.get(target);
+        if (needsActiveContainer === undefined) {
+            needsActiveContainer = (this.#reader.getAccessorMetadata?.(target)?.length ?? 0) > 0;
+            (this.#needsActiveContainer ??= new WeakMap()).set(target, needsActiveContainer);
+        }
+        return needsActiveContainer;
+    }
+    instantiate(target, deps, resolution) {
+        const invokable = target;
+        if (!this.needsActiveContainer(target)) {
+            return new invokable(...deps);
+        }
+        return runWithAmbientResolution(this.#container, resolution, () => new invokable(...deps));
+    }
+}
+//# sourceMappingURL=class-introspector.js.map

package/dist/resolution/cache/class-introspector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"class-introspector.js","sourceRoot":"","sources":["../../../src/resolution/cache/class-introspector.ts"],"names":[],"mappings":"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"}

package/dist/resolution/context.d.ts

@@ -0,0 +1,84 @@
+/** The `ResolutionContext` a factory is handed, and the callbacks the resolver answers it with. */
+import type { Token } from "#/core/token";
+import type { BindingIdentifier, BindingKind, BindingScope, ConstraintContext, Constructor, ResolutionFrame, ResolutionContext, ResolveOptions } from "#/core/types";
+import type { BranchDepth, OwnedBranchStack } from "#/resolution/path/resolution-path";
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ResolverCallbacks {
+    resolveFromContext<Value>(token: Token<Value> | Constructor<Value>, resolutionStack: Array<ResolutionFrame>): Value;
+    resolve<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Value;
+    resolveAsyncFromContext<Value>(token: Token<Value> | Constructor<Value>, resolutionStack: Array<ResolutionFrame>, branchDepth: BranchDepth): Promise<Value>;
+    /** Not one of the eight `Value`-naming entry points: its caller is, and casts once. */
+    resolveAsyncFromCascade(token: Token<unknown> | Constructor): Promise<unknown>;
+    resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Promise<Value>;
+    resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Value | undefined;
+    resolveOptionalAsync<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Promise<Value | undefined>;
+    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Array<Value>;
+    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Promise<Array<Value>>;
+}
+/**
+ * @since 0.3.16-canary.0
+ */
+export declare class DefaultResolutionContext implements ResolutionContext {
+    #private;
+    constructor(resolver: ResolverCallbacks, resolutionStack: Array<ResolutionFrame>, currentOptions: ResolveOptions | undefined);
+    get graph(): ConstraintContext;
+    reset(resolver: ResolverCallbacks, resolutionStack: Array<ResolutionFrame>, currentOptions: ResolveOptions | undefined): void;
+    resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value;
+    resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
+    resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
+    resolveOptionalAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value | undefined>;
+    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value>;
+    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>>;
+}
+/**
+ * One async level's resolution context, which is also its branch of the resolution stack.
+ *
+ * @remarks Separate from {@link DefaultResolutionContext} so the sync lane's pooled context keeps
+ * reading its stack as a plain field: only an async branch has a prefix to take, because an async
+ * level owns its branch of the stack.
+ *
+ * @since 0.5.0-canary.9
+ */
+export declare class AsyncLevelContext implements ResolutionContext {
+    #private;
+    /**
+     * @param resolver - the engine callbacks every request on this level goes through
+     * @param resolutionStack - this level's own branch; the depth is read off it rather than passed,
+     * so the two cannot disagree about where this level sits
+     * @param currentOptions - the options of the request that opened this level, if any
+     */
+    constructor(resolver: ResolverCallbacks, resolutionStack: OwnedBranchStack, currentOptions: ResolveOptions | undefined);
+    get graph(): ConstraintContext;
+    resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value;
+    resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
+    resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
+    resolveOptionalAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value | undefined>;
+    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value>;
+    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>>;
+}
+/**
+ * The one context every level of an open synchronous factory cascade shares.
+ *
+ * @remarks It carries no per-level state at all: while the cascade is open, the resolver's stack
+ * *is* this level's ancestor chain, so nothing has to be allocated per level.
+ *
+ * @since 0.5.0-canary.9
+ */
+export declare class AsyncCascadeContext implements ResolutionContext {
+    #private;
+    constructor(resolver: ResolverCallbacks, cascadeStack: Array<ResolutionFrame>);
+    get graph(): ConstraintContext;
+    resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value;
+    resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
+    resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
+    resolveOptionalAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value | undefined>;
+    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value>;
+    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>>;
+}
+/**
+ * @since 0.3.16-canary.0
+ */
+export declare function buildResolutionFrame(tokenName: string, scope: BindingScope, bindingId: BindingIdentifier, kind: BindingKind, slot: ResolutionFrame["slot"]): ResolutionFrame;
+//# sourceMappingURL=context.d.ts.map

package/dist/resolution/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/resolution/context.ts"],"names":[],"mappings":"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"}

package/dist/resolution/{environment.js → context.js}

@@ -1,55 +1,29 @@
-import { UNOWNED_BRANCH } from "#/resolution/resolution-path";
-// ── Active container ──────────────────────────────────────────────────────────
-let activeContainer;
-/**
- * @since 0.3.16-canary.0
- */
-export function runWithContainer(container, fn) {
-    const prev = activeContainer;
-    activeContainer = container;
-    try {
-        return fn();
-    }
-    finally {
-        activeContainer = prev;
-    }
-}
-/**
- * @since 0.3.16-canary.0
- */
-export function getActiveContainer() {
-    return activeContainer;
-}
+import { UNOWNED_BRANCH } from "#/resolution/path/resolution-path";
 /**
  * @since 0.3.16-canary.0
  */
 export class DefaultResolutionContext {
     #resolver;
-    #resolutionPath;
     #resolutionStack;
     #currentOptions;
-    constructor(resolver, resolutionPath, resolutionStack, currentOptions) {
+    constructor(resolver, resolutionStack, currentOptions) {
         this.#resolver = resolver;
-        this.#resolutionPath = resolutionPath;
         this.#resolutionStack = resolutionStack;
         this.#currentOptions = currentOptions;
     }
     #graph;
     get graph() {
         if (this.#graph === undefined) {
-            this.#graph = new DefaultConstraintContext(this.#resolutionPath, this.#resolutionStack, this.#currentOptions);
+            this.#graph = new DefaultConstraintContext(this.#resolutionStack, this.#currentOptions);
         }
         return this.#graph;
     }
-    reset(resolver, resolutionPath, resolutionStack, currentOptions) {
+    reset(resolver, resolutionStack, currentOptions) {
         // Compared before storing: a pooled context lives long enough to be in old space, so storing a
-        // pointer costs a write barrier, and a sync resolve hands every depth the same two arrays.
+        // pointer costs a write barrier, and a sync resolve hands every depth the same stack.
         if (this.#resolver !== resolver) {
             this.#resolver = resolver;
         }
-        if (this.#resolutionPath !== resolutionPath) {
-            this.#resolutionPath = resolutionPath;
-        }
         if (this.#resolutionStack !== resolutionStack) {
             this.#resolutionStack = resolutionStack;
         }
@@ -60,158 +34,158 @@ export class DefaultResolutionContext {
     }
     resolve(token, options) {
         if (options === undefined) {
-            return this.#resolver.resolveFromContext(token, this.#resolutionPath, this.#resolutionStack);
+            return this.#resolver.resolveFromContext(token, this.#resolutionStack);
         }
-        return this.#resolver.resolve(token, options, this.#resolutionPath, this.#resolutionStack);
+        return this.#resolver.resolve(token, options, this.#resolutionStack);
     }
     resolveAsync(token, options) {
         if (options === undefined) {
             // UNOWNED_BRANCH: this frame's array is a sync stack it will pop, so the lane must copy it.
-            return this.#resolver.resolveAsyncFromContext(token, this.#resolutionPath, this.#resolutionStack, UNOWNED_BRANCH);
+            return this.#resolver.resolveAsyncFromContext(token, this.#resolutionStack, UNOWNED_BRANCH);
         }
-        return this.#resolver.resolveAsync(token, options, this.#resolutionPath, this.#resolutionStack);
+        return this.#resolver.resolveAsync(token, options, this.#resolutionStack);
     }
     resolveOptional(token, options) {
-        return this.#resolver.resolveOptional(token, options, this.#resolutionPath, this.#resolutionStack);
+        return this.#resolver.resolveOptional(token, options, this.#resolutionStack);
     }
     resolveOptionalAsync(token, options) {
-        return this.#resolver.resolveOptionalAsync(token, options, this.#resolutionPath, this.#resolutionStack);
+        return this.#resolver.resolveOptionalAsync(token, options, this.#resolutionStack);
     }
     resolveAll(token, options) {
-        return this.#resolver.resolveAll(token, options, this.#resolutionPath, this.#resolutionStack);
+        return this.#resolver.resolveAll(token, options, this.#resolutionStack);
     }
     resolveAllAsync(token, options) {
-        return this.#resolver.resolveAllAsync(token, options, this.#resolutionPath, this.#resolutionStack);
+        return this.#resolver.resolveAllAsync(token, options, this.#resolutionStack);
     }
 }
 /**
- * One async level's resolution context, which is also its branch of the resolution path.
+ * One async level's resolution context, which is also its branch of the resolution stack.
  *
  * @remarks Separate from {@link DefaultResolutionContext} so the sync lane's pooled context keeps
- * reading its arrays as plain fields: only an async branch has a prefix to take. See
- * `ARCHITECTURE.md` — an async level owns its branch of the path.
+ * reading its stack as a plain field: only an async branch has a prefix to take, because an async
+ * level owns its branch of the stack.
  *
  * @since 0.5.0-canary.9
  */
 export class AsyncLevelContext {
     #resolver;
-    #resolutionPath;
     #resolutionStack;
     #currentOptions;
     #branchDepth;
     /**
-     * @param resolutionPath - this level's own branch; the depth is read off it rather than passed,
+     * @param resolver - the engine callbacks every request on this level goes through
+     * @param resolutionStack - this level's own branch; the depth is read off it rather than passed,
      * so the two cannot disagree about where this level sits
+     * @param currentOptions - the options of the request that opened this level, if any
      */
-    constructor(resolver, resolutionPath, resolutionStack, currentOptions) {
+    constructor(resolver, resolutionStack, currentOptions) {
         this.#resolver = resolver;
-        this.#resolutionPath = resolutionPath;
         this.#resolutionStack = resolutionStack;
         this.#currentOptions = currentOptions;
-        this.#branchDepth = resolutionPath.length;
+        this.#branchDepth = resolutionStack.length;
     }
     #graph;
-    #exactPathCache;
     #exactStackCache;
     get graph() {
         if (this.#graph === undefined) {
-            this.#graph = new DefaultConstraintContext(this.#exactPath(), this.#exactStack(), this.#currentOptions);
+            this.#graph = new DefaultConstraintContext(this.#exactStack(), this.#currentOptions);
         }
         return this.#graph;
     }
-    // The path is append-only and a descendant may already have grown it past this level, so every
+    // The stack is append-only and a descendant may already have grown it past this level, so every
     // caller but the async lane is handed this branch's prefix. It is fixed for the level's lifetime.
-    #exactPath() {
-        return (this.#exactPathCache ??= this.#resolutionPath.slice(0, this.#branchDepth));
-    }
     #exactStack() {
         return (this.#exactStackCache ??= this.#resolutionStack.slice(0, this.#branchDepth));
     }
     resolve(token, options) {
         if (options === undefined) {
-            return this.#resolver.resolveFromContext(token, this.#exactPath(), this.#exactStack());
+            return this.#resolver.resolveFromContext(token, this.#exactStack());
         }
-        return this.#resolver.resolve(token, options, this.#exactPath(), this.#exactStack());
+        return this.#resolver.resolve(token, options, this.#exactStack());
     }
     resolveAsync(token, options) {
         if (options === undefined) {
             // The hot lane: the resolver reads this branch by depth, so nothing is materialized.
-            return this.#resolver.resolveAsyncFromContext(token, this.#resolutionPath, this.#resolutionStack, this.#branchDepth);
+            return this.#resolver.resolveAsyncFromContext(token, this.#resolutionStack, this.#branchDepth);
         }
-        return this.#resolver.resolveAsync(token, options, this.#exactPath(), this.#exactStack());
+        return this.#resolver.resolveAsync(token, options, this.#exactStack());
     }
     resolveOptional(token, options) {
-        return this.#resolver.resolveOptional(token, options, this.#exactPath(), this.#exactStack());
+        return this.#resolver.resolveOptional(token, options, this.#exactStack());
     }
     resolveOptionalAsync(token, options) {
-        return this.#resolver.resolveOptionalAsync(token, options, this.#exactPath(), this.#exactStack());
+        return this.#resolver.resolveOptionalAsync(token, options, this.#exactStack());
     }
     resolveAll(token, options) {
-        return this.#resolver.resolveAll(token, options, this.#exactPath(), this.#exactStack());
+        return this.#resolver.resolveAll(token, options, this.#exactStack());
     }
     resolveAllAsync(token, options) {
-        return this.#resolver.resolveAllAsync(token, options, this.#exactPath(), this.#exactStack());
+        return this.#resolver.resolveAllAsync(token, options, this.#exactStack());
     }
 }
 /**
  * The one context every level of an open synchronous factory cascade shares.
  *
- * @remarks It carries no per-level state at all: while the cascade is open, the resolver's arrays
- * *are* this level's ancestor chain, so nothing has to be allocated per level. See
- * `ARCHITECTURE.md` — the cascade lane.
+ * @remarks It carries no per-level state at all: while the cascade is open, the resolver's stack
+ * *is* this level's ancestor chain, so nothing has to be allocated per level.
  *
  * @since 0.5.0-canary.9
  */
 export class AsyncCascadeContext {
     #resolver;
-    #cascadePath;
     #cascadeStack;
-    constructor(resolver, cascadePath, cascadeStack) {
+    constructor(resolver, cascadeStack) {
         this.#resolver = resolver;
-        this.#cascadePath = cascadePath;
         this.#cascadeStack = cascadeStack;
     }
     get graph() {
         // Not memoized: this context outlives every level, so a cached graph would describe whichever
-        // level asked first. The cascade arrays are only this level's ancestors while it is open.
-        return new DefaultConstraintContext(this.#cascadePath, this.#cascadeStack, undefined);
+        // level asked first. The cascade stack is only this level's ancestors while it is open.
+        return new DefaultConstraintContext(this.#cascadeStack, undefined);
     }
     resolve(token, options) {
         if (options === undefined) {
-            return this.#resolver.resolveFromContext(token, this.#cascadePath, this.#cascadeStack);
+            return this.#resolver.resolveFromContext(token, this.#cascadeStack);
         }
-        return this.#resolver.resolve(token, options, this.#cascadePath, this.#cascadeStack);
+        return this.#resolver.resolve(token, options, this.#cascadeStack);
     }
     resolveAsync(token, options) {
         if (options === undefined) {
             return this.#resolver.resolveAsyncFromCascade(token);
         }
-        return this.#resolver.resolveAsync(token, options, [...this.#cascadePath], [...this.#cascadeStack]);
+        return this.#resolver.resolveAsync(token, options, [...this.#cascadeStack]);
     }
     resolveOptional(token, options) {
-        return this.#resolver.resolveOptional(token, options, this.#cascadePath, this.#cascadeStack);
+        return this.#resolver.resolveOptional(token, options, this.#cascadeStack);
     }
     resolveOptionalAsync(token, options) {
-        return this.#resolver.resolveOptionalAsync(token, options, [...this.#cascadePath], [...this.#cascadeStack]);
+        return this.#resolver.resolveOptionalAsync(token, options, [...this.#cascadeStack]);
     }
     resolveAll(token, options) {
-        return this.#resolver.resolveAll(token, options, this.#cascadePath, this.#cascadeStack);
+        return this.#resolver.resolveAll(token, options, this.#cascadeStack);
     }
     resolveAllAsync(token, options) {
-        return this.#resolver.resolveAllAsync(token, options, [...this.#cascadePath], [...this.#cascadeStack]);
+        return this.#resolver.resolveAllAsync(token, options, [...this.#cascadeStack]);
     }
 }
 class DefaultConstraintContext {
-    resolutionPath;
     resolutionStack;
     parent;
     currentResolveOptions;
-    constructor(resolutionPath, resolutionStack, currentResolveOptions) {
-        this.resolutionPath = resolutionPath;
+    constructor(resolutionStack, currentResolveOptions) {
         this.resolutionStack = resolutionStack;
         this.parent = resolutionStack.at(-1);
         this.currentResolveOptions = currentResolveOptions;
     }
+    // Derived per read, never cached: the stack this context aliases may be live, and the names must
+    // report it as it stands — exactly as the dedicated name array did.
+    get resolutionPath() {
+        const names = new Array(this.resolutionStack.length);
+        for (let index = 0; index < this.resolutionStack.length; index += 1) {
+            names[index] = this.resolutionStack[index].tokenName;
+        }
+        return names;
+    }
     #ancestors;
     get ancestors() {
         if (this.#ancestors === undefined) {
@@ -226,4 +200,4 @@ class DefaultConstraintContext {
 export function buildResolutionFrame(tokenName, scope, bindingId, kind, slot) {
     return { tokenName, scope, bindingId, kind, slot };
 }
-//# sourceMappingURL=environment.js.map
+//# sourceMappingURL=context.js.map

package/dist/resolution/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/resolution/context.ts"],"names":[],"mappings":"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"}