@codefast/di 0.10.1 → 0.12.0

package/dist/metadata/{verifying-metadata-reader.d.ts → verifying-reader.d.ts}

@@ -1,14 +1,15 @@
 /**
  * Wraps a foreign {@link MetadataReader} so its answers are verified before anything dereferences
- * them.
+ * them, and asked for once per class.
  */
-import type { MetadataReader } from "#metadata/metadata-types";
+import type { MetadataReader } from "#metadata/types";
 /**
- * The reader a container should hand its resolver: verified when it came from outside.
+ * The reader a container should hand its resolver: verified and memoized when it came from outside.
  *
  * @remarks The decorator reader writes the metadata it later reads, so there is nothing to check and
  * nothing to pay — a container that supplies no reader of its own is left on the same code path it
- * has always taken. A supplied reader is a claim, and only its callers can be charged for checking.
+ * has always taken. A supplied reader is a claim, and only its callers can be charged for checking;
+ * it is asked about a class once, however many containers read through it.
  *
  * @since 0.6.0
  */

package/dist/metadata/verifying-reader.js

@@ -0,0 +1,53 @@
+/**
+ * Wraps a foreign {@link MetadataReader} so its answers are verified before anything dereferences
+ * them, and asked for once per class.
+ */
+import { defaultMetadataReader } from "#metadata/symbol-reader";
+import { verifyAccessorMetadata, verifyConstructorMetadata, verifyLifecycleMetadata } from "#metadata/verify";
+// Wrapping a wrapper would stack a layer per child container, so each one is remembered.
+const verifyingReaders = new WeakSet();
+// One wrapper per foreign reader, so every container handed that reader shares its answers.
+const wrapperByReader = new WeakMap();
+// `null` records a verified "no metadata", so an absent answer is not asked for again either.
+function memoized(ask) {
+    const answers = new WeakMap();
+    return (target) => {
+        const known = answers.get(target);
+        if (known !== undefined) {
+            return known === null ? undefined : known;
+        }
+        // Stored only after `ask` returns, so an answer that fails verification is asked for, and fails, again.
+        const answer = ask(target);
+        answers.set(target, answer ?? null);
+        return answer;
+    };
+}
+/**
+ * The reader a container should hand its resolver: verified and memoized when it came from outside.
+ *
+ * @remarks The decorator reader writes the metadata it later reads, so there is nothing to check and
+ * nothing to pay — a container that supplies no reader of its own is left on the same code path it
+ * has always taken. A supplied reader is a claim, and only its callers can be charged for checking;
+ * it is asked about a class once, however many containers read through it.
+ *
+ * @since 0.6.0
+ */
+export function verifyingMetadataReader(reader) {
+    if (reader === defaultMetadataReader || verifyingReaders.has(reader)) {
+        return reader;
+    }
+    const existing = wrapperByReader.get(reader);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const verifying = {
+        getConstructorMetadata: memoized((target) => verifyConstructorMetadata(reader, target)),
+        getLifecycleMetadata: memoized((target) => verifyLifecycleMetadata(reader, target)),
+        ...(reader.getAccessorMetadata === undefined
+            ? {}
+            : { getAccessorMetadata: memoized((target) => verifyAccessorMetadata(reader, target)) }),
+    };
+    verifyingReaders.add(verifying);
+    wrapperByReader.set(reader, verifying);
+    return verifying;
+}

package/dist/resolution/async-fan-out.d.ts

@@ -0,0 +1,12 @@
+/** Settles the concurrent dependencies of one async level and reports a failure in declaration order. */
+/**
+ * Applies `apply` to every dependency's settled value, or rejects with the first failure in declaration order.
+ *
+ * @remarks Siblings start concurrently, and `Promise.all` alone would report whichever rejection
+ * settles first — a fact about microtask depth, not about the graph. The synchronous lanes report
+ * the first failing dependency in declaration order, so this does too: the happy path is `Promise.all`,
+ * and only a failure waits for every sibling to settle and then picks the earliest one that did not.
+ *
+ * @since 0.11.0
+ */
+export declare function settleInOrder<Result>(pending: ReadonlyArray<unknown>, apply: (values: Array<unknown>) => Result): Promise<Result>;

package/dist/resolution/async-fan-out.js

@@ -0,0 +1,26 @@
+/** Settles the concurrent dependencies of one async level and reports a failure in declaration order. */
+/**
+ * Applies `apply` to every dependency's settled value, or rejects with the first failure in declaration order.
+ *
+ * @remarks Siblings start concurrently, and `Promise.all` alone would report whichever rejection
+ * settles first — a fact about microtask depth, not about the graph. The synchronous lanes report
+ * the first failing dependency in declaration order, so this does too: the happy path is `Promise.all`,
+ * and only a failure waits for every sibling to settle and then picks the earliest one that did not.
+ *
+ * @since 0.11.0
+ */
+export function settleInOrder(pending, apply) {
+    return Promise.all(pending).then(apply, () => firstRejectionInOrder(pending));
+}
+function firstRejectionInOrder(pending) {
+    return Promise.allSettled(pending).then((results) => {
+        for (let index = 0; index < results.length; index += 1) {
+            const result = results[index];
+            if (result.status === "rejected") {
+                throw result.reason;
+            }
+        }
+        // Unreachable: this branch only runs once `Promise.all` has rejected, so a rejection is settled.
+        throw new Error("settleInOrder: a rejected fan-out settled with no rejection");
+    });
+}

package/dist/resolution/cache/activation-need.d.ts

@@ -6,7 +6,7 @@
  */
 import type { Binding } from "#core/binding";
 import type { BindingRegistry } from "#core/registry";
-import type { LifecycleManager } from "#lifecycle/lifecycle-manager";
+import type { LifecycleManager } from "#lifecycle/hooks";
 import type { ClassIntrospector } from "#resolution/cache/class-introspector";
 /**
  * A per-binding cache of whether activation work — hooks or `@postConstruct` — is needed on resolve.
@@ -17,7 +17,6 @@ export declare class ActivationNeedCache {
     #private;
     constructor(lifecycle: LifecycleManager, classes: ClassIntrospector, registry: BindingRegistry);
     /** Whether an answer the early returns could not give has had to allocate the memo. */
-    get isMemoBuilt(): boolean;
     needsActivation<Value>(binding: Binding<Value>): boolean;
     /**
      * Settles a class binding's answer once its lifecycle metadata has actually been read, which

package/dist/resolution/cache/activation-need.js

@@ -1,13 +1,10 @@
+import { NO_ACTIVATION_STAMP } from "#core/binding";
 /**
  * A per-binding cache of whether activation work — hooks or `@postConstruct` — is needed on resolve.
  *
  * @since 0.5.0-canary.8
  */
 export class ActivationNeedCache {
-    // Allocated by the first answer the early returns cannot give, so a hook-free container that
-    // resolves no class or alias never pays for it.
-    #needByBindingId;
-    #version = -1;
     #lifecycle;
     #classes;
     #registry;
@@ -17,9 +14,6 @@ export class ActivationNeedCache {
         this.#registry = registry;
     }
     /** Whether an answer the early returns could not give has had to allocate the memo. */
-    get isMemoBuilt() {
-        return this.#needByBindingId !== undefined;
-    }
     needsActivation(binding) {
         // The chain writes a binding's own hook in place with no version anything here can see, so it
         // is read fresh on every call; the memo covers only container hooks and lifecycle metadata.
@@ -32,19 +26,18 @@ export class ActivationNeedCache {
         if (lifecycleVersion === 0 && binding.kind !== "class" && binding.kind !== "alias") {
             return false;
         }
-        // The registry version evicts entries for binding ids a rebind has retired.
-        const version = lifecycleVersion + this.#registry.version;
-        if (this.#version !== version) {
-            this.#needByBindingId?.clear();
-            this.#version = version;
+        // The stamp is the version pair the answer was computed under, doubled, plus the answer: a
+        // registry or lifecycle mutation moves the version and retires every stamp at once.
+        const stampBase = (lifecycleVersion + this.#registry.version) * 2;
+        const stamp = binding.activationStamp;
+        if (stamp === stampBase) {
+            return false;
         }
-        const memo = (this.#needByBindingId ??= new Map());
-        const cached = memo.get(binding.identifier);
-        if (cached !== undefined) {
-            return cached;
+        if (stamp === stampBase + 1) {
+            return true;
         }
         const needsActivation = binding.kind === "class" ? this.#classNeedsActivation(binding) : this.#nonClassNeedsActivation(binding);
-        memo.set(binding.identifier, needsActivation);
+        binding.activationStamp = needsActivation ? stampBase + 1 : stampBase;
         return needsActivation;
     }
     /**
@@ -55,11 +48,15 @@ export class ActivationNeedCache {
      * conservative `true`.
      */
     refreshAfterFirstInstantiation(binding, needsActivation) {
-        if (binding.kind !== "class" || this.#classes.knownPostConstruct(binding.target) !== undefined) {
+        // A class binding answers `false` only once its lifecycle metadata is known, so only a conservative
+        // `true` can still settle, and a `false` needs no second look at the class.
+        if (!needsActivation ||
+            binding.kind !== "class" ||
+            this.#classes.knownPostConstruct(binding.target) !== undefined) {
             return needsActivation;
         }
         this.#classes.discoverPostConstruct(binding.target);
-        this.#needByBindingId?.delete(binding.identifier);
+        binding.activationStamp = NO_ACTIVATION_STAMP;
         return this.needsActivation(binding);
     }
     // Own hooks are answered before the memo, so both computations cover the memoizable rest only.

package/dist/resolution/cache/class-introspector.d.ts

@@ -3,57 +3,55 @@
  *
  * @remarks Metadata cannot change once a class is defined, so nothing here needs version stamping.
  */
-import type { AmbientResolution } from "#ambient/active-container";
+import type { AmbientResolution } from "#ambient-container";
 import type { Container } from "#container/container";
 import type { Constructor } from "#core/types";
-import type { InjectionDescriptor } from "#injection/descriptor";
-import type { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "#metadata/metadata-types";
+import type { ConstructorMetadata, MetadataReader, ParamMetadata } from "#metadata/types";
 /**
- * A reader's constructor metadata for a class, verified the first time this process asks.
+ * What one reader has answered about one class so far, each field unknown until first asked.
  *
- * @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.
+ * @remarks One record per class, so a cold resolve looks the class up once and hands the record down
+ * rather than asking a map per fact.
  *
- * @since 0.6.0
+ * @since 0.12.0
  */
-export declare function verifyConstructorMetadata(reader: MetadataReader, target: Constructor): ConstructorMetadata | undefined;
-/**
- * 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 declare function assertConstructorMetadata(metadata: unknown, target: Constructor): ConstructorMetadata | undefined;
-/**
- * A reader's lifecycle metadata for a class, verified the first time this process asks.
- *
- * @since 0.6.0
- */
-export declare function verifyLifecycleMetadata(reader: MetadataReader, target: Constructor): LifecycleMetadata | undefined;
-/**
- * A reader's accessor metadata for a class, verified the first time this process asks.
- *
- * @since 0.6.0
- */
-export declare function verifyAccessorMetadata(reader: MetadataReader, target: Constructor): ReadonlyArray<{
-    readonly key: string | symbol;
-    readonly descriptor: InjectionDescriptor;
-}> | undefined;
+export interface ClassFacts {
+    /** The reader's constructor metadata, `null` once it answered that it knows nothing about the class. */
+    constructorMetadata: ConstructorMetadata | null | undefined;
+    /** Unknown until the first instantiation reads lifecycle metadata; callers read unknown as "it does". */
+    hasPostConstruct: boolean | undefined;
+    needsActiveContainer: boolean | undefined;
+    /** The parameters an instantiation injects, settled by the first one that succeeds. */
+    params: ReadonlyArray<ParamMetadata> | undefined;
+}
 /**
  * A per-class cache of constructor metadata and the activation facts derived from it.
  *
+ * @remarks A child inheriting its parent's reader takes the parent's facts too, and resolves a class
+ * the parent already met without reading its metadata again; a root finds them by reader on its first
+ * question.
+ *
  * @since 0.5.0-canary.8
  */
 export declare class ClassIntrospector {
     #private;
     constructor(reader: MetadataReader, container: Container, inherited: ClassIntrospector | undefined);
+    /** The record of what this reader has answered about a class, allocated on the class's first question. */
+    facts(target: Constructor): ClassFacts;
     constructorMetadata(target: Constructor): ConstructorMetadata | undefined;
+    /** The constructor metadata of a class whose facts the caller already holds. */
+    constructorMetadataOf(target: Constructor, facts: ClassFacts): ConstructorMetadata | undefined;
+    /**
+     * The nearest ancestor's own constructor metadata, for a subclass that declares none of its own.
+     *
+     * @remarks Constructor metadata is never borrowed down the chain, so a subclass with an implicit
+     * constructor would be built with zero arguments; this lets the resolver name the base whose
+     * declared deps the subclass silently drops.
+     */
+    inheritedConstructorMetadata(target: Constructor): {
+        base: Constructor;
+        metadata: ConstructorMetadata;
+    } | undefined;
     /**
      * Whether the class has a `@postConstruct` hook, or `undefined` until {@link discoverPostConstruct}.
      *
@@ -63,5 +61,9 @@ export declare class ClassIntrospector {
     discoverPostConstruct(target: Constructor): void;
     /** True when the class has accessor injection, which reads the container during construction. */
     needsActiveContainer(target: Constructor): boolean;
+    /** Whether a class whose facts the caller already holds reads the container during construction. */
+    needsActiveContainerOf(target: Constructor, facts: ClassFacts): boolean;
     instantiate(target: Constructor, deps: Array<unknown>, resolution?: AmbientResolution): unknown;
+    /** Builds an instance whose accessor need the caller already knows; an empty `deps` is a call with no arguments. */
+    construct(target: Constructor, deps: ReadonlyArray<unknown>, needsActiveContainer: boolean, resolution: AmbientResolution | undefined): unknown;
 }

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

@@ -3,175 +3,87 @@
  *
  * @remarks Metadata cannot change once a class is defined, so nothing here needs version stamping.
  */
-import { constructWithAmbientResolution, 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);
-}
-/**
- * Runs `validate` against a reader's metadata the first time this process sees the pair, then remembers it.
- *
- * @remarks An absent metadata answer needs no check; a verified pair is returned untouched, so the
- * shape assertion runs once per `(reader, target)` rather than per container.
- */
-function verifyOnce(cache, reader, target, metadata, validate) {
-    if (metadata === undefined || isVerified(cache, reader, target)) {
-        return metadata;
+import { constructWithAmbientResolution, runWithAmbientResolution } from "#ambient-container";
+// A reader answers from the class alone, so its facts are shared by every container reading through it.
+const factsByReader = new WeakMap();
+function factsFor(reader) {
+    let byClass = factsByReader.get(reader);
+    if (byClass === undefined) {
+        byClass = new WeakMap();
+        factsByReader.set(reader, byClass);
     }
-    validate(metadata);
-    markVerified(cache, reader, target);
-    return metadata;
-}
-/**
- * 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) {
-    return verifyOnce(verifiedTargets, reader, target, reader.getConstructorMetadata(target), (metadata) => {
-        assertConstructorMetadata(metadata, target);
-    });
-}
-/**
- * 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) {
-    return verifyOnce(verifiedLifecycleTargets, reader, target, reader.getLifecycleMetadata(target), (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`);
-                }
-            }
-        }
-    });
-}
-/**
- * A reader's accessor metadata for a class, verified the first time this process asks.
- *
- * @since 0.6.0
- */
-export function verifyAccessorMetadata(reader, target) {
-    return verifyOnce(verifiedAccessorTargets, reader, target, reader.getAccessorMetadata?.(target), (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`);
-            }
-        }
-    });
-}
-const cachesByReader = new WeakMap();
-function cachesFor(reader) {
-    let caches = cachesByReader.get(reader);
-    if (caches === undefined) {
-        caches = { constructorMetadata: undefined, hasPostConstruct: undefined, needsActiveContainer: undefined };
-        cachesByReader.set(reader, caches);
-    }
-    return caches;
+    return byClass;
 }
 /**
  * A per-class cache of constructor metadata and the activation facts derived from it.
  *
+ * @remarks A child inheriting its parent's reader takes the parent's facts too, and resolves a class
+ * the parent already met without reading its metadata again; a root finds them by reader on its first
+ * question.
+ *
  * @since 0.5.0-canary.8
  */
 export class ClassIntrospector {
-    #caches;
+    #byClass;
+    // The class asked about last and its record: a cold resolve asks about one class several times in a row.
+    #lastTarget;
+    #lastFacts;
     #reader;
     #container;
     constructor(reader, container, inherited) {
-        this.#caches = inherited !== undefined && inherited.#reader === reader ? inherited.#caches : undefined;
+        this.#byClass = inherited !== undefined && inherited.#reader === reader ? inherited.#byClass : undefined;
         this.#reader = reader;
         this.#container = container;
     }
-    #shared() {
-        return (this.#caches ??= cachesFor(this.#reader));
+    /** The record of what this reader has answered about a class, allocated on the class's first question. */
+    facts(target) {
+        if (target === this.#lastTarget) {
+            return this.#lastFacts;
+        }
+        const byClass = (this.#byClass ??= factsFor(this.#reader));
+        let facts = byClass.get(target);
+        if (facts === undefined) {
+            facts = {
+                constructorMetadata: undefined,
+                hasPostConstruct: undefined,
+                needsActiveContainer: undefined,
+                params: undefined,
+            };
+            byClass.set(target, facts);
+        }
+        this.#lastTarget = target;
+        this.#lastFacts = facts;
+        return facts;
     }
     constructorMetadata(target) {
-        const caches = this.#shared();
-        const cached = caches.constructorMetadata?.get(target);
-        if (cached !== undefined) {
-            return cached === null ? undefined : cached;
+        return this.constructorMetadataOf(target, this.facts(target));
+    }
+    /** The constructor metadata of a class whose facts the caller already holds. */
+    constructorMetadataOf(target, facts) {
+        let metadata = facts.constructorMetadata;
+        if (metadata === undefined) {
+            metadata = this.#reader.getConstructorMetadata(target) ?? null;
+            facts.constructorMetadata = metadata;
+        }
+        return metadata === null ? undefined : metadata;
+    }
+    /**
+     * The nearest ancestor's own constructor metadata, for a subclass that declares none of its own.
+     *
+     * @remarks Constructor metadata is never borrowed down the chain, so a subclass with an implicit
+     * constructor would be built with zero arguments; this lets the resolver name the base whose
+     * declared deps the subclass silently drops.
+     */
+    inheritedConstructorMetadata(target) {
+        let current = Object.getPrototypeOf(target);
+        while (typeof current === "function" && current !== Function.prototype) {
+            const metadata = this.constructorMetadata(current);
+            if (metadata !== undefined) {
+                return { base: current, metadata };
+            }
+            current = Object.getPrototypeOf(current);
         }
-        const metadata = this.#reader.getConstructorMetadata(target);
-        (caches.constructorMetadata ??= new WeakMap()).set(target, metadata ?? null);
-        return metadata;
+        return undefined;
     }
     /**
      * Whether the class has a `@postConstruct` hook, or `undefined` until {@link discoverPostConstruct}.
@@ -179,26 +91,34 @@ export class ClassIntrospector {
      * @remarks Callers treat unknown as "assume it does", so the first activation settles it.
      */
     knownPostConstruct(target) {
-        return this.#shared().hasPostConstruct?.get(target);
+        return this.facts(target).hasPostConstruct;
     }
     discoverPostConstruct(target) {
         const lifecycle = this.#reader.getLifecycleMetadata(target);
-        (this.#shared().hasPostConstruct ??= new WeakMap()).set(target, lifecycle !== undefined && lifecycle.postConstruct !== undefined && lifecycle.postConstruct.length > 0);
+        this.facts(target).hasPostConstruct =
+            lifecycle !== undefined && lifecycle.postConstruct !== undefined && lifecycle.postConstruct.length > 0;
     }
     /** True when the class has accessor injection, which reads the container during construction. */
     needsActiveContainer(target) {
-        const caches = this.#shared();
-        let needsActiveContainer = caches.needsActiveContainer?.get(target);
+        return this.needsActiveContainerOf(target, this.facts(target));
+    }
+    /** Whether a class whose facts the caller already holds reads the container during construction. */
+    needsActiveContainerOf(target, facts) {
+        let needsActiveContainer = facts.needsActiveContainer;
         if (needsActiveContainer === undefined) {
             needsActiveContainer = (this.#reader.getAccessorMetadata?.(target)?.length ?? 0) > 0;
-            (caches.needsActiveContainer ??= new WeakMap()).set(target, needsActiveContainer);
+            facts.needsActiveContainer = needsActiveContainer;
         }
         return needsActiveContainer;
     }
     instantiate(target, deps, resolution) {
+        return this.construct(target, deps, this.needsActiveContainer(target), resolution);
+    }
+    /** Builds an instance whose accessor need the caller already knows; an empty `deps` is a call with no arguments. */
+    construct(target, deps, needsActiveContainer, resolution) {
         const invokable = target;
-        if (!this.needsActiveContainer(target)) {
-            return new invokable(...deps);
+        if (!needsActiveContainer) {
+            return deps.length === 0 ? new invokable() : new invokable(...deps);
         }
         if (resolution === undefined) {
             return runWithAmbientResolution(this.#container, undefined, () => new invokable(...deps));

package/dist/resolution/cache/{binding-lookup-cache.d.ts → lookup.d.ts}

@@ -25,7 +25,8 @@ export interface DefaultLookupEntry<Owner> {
  *
  * @remarks `values` is kept only while every member is a hook-free constant or a hook-free singleton
  * whose instance is cached, and `activationVersion` is the chain's activation version that promise was
- * made under.
+ * made under. It is settled on the read that repeats the first, which `readBefore` records, so a
+ * container read once never builds it.
  *
  * @since 0.10.0
  */
@@ -33,14 +34,8 @@ export interface CollectionEntry {
     readonly candidates: ReadonlyArray<Binding>;
     values: ReadonlyArray<unknown> | undefined;
     activationVersion: number;
+    readBefore: boolean;
 }
-/**
- * Alias folding gives up past this many hops and defers to the full resolve loop, whose
- * Set-based traversal detects genuine cycles exactly rather than by an arbitrary cap.
- *
- * @since 0.5.0-canary.8
- */
-export declare const ALIAS_HOP_LIMIT = 32;
 /**
  * A version-stamped cache of binding lookups by token and criterion across the container chain.
  *
@@ -72,6 +67,9 @@ export declare class BindingLookupCache<Owner> {
     namedTaggedEntry(token: Token<unknown> | Constructor, nameCriterion: BindingTag, tag: BindingTag): DefaultLookupEntry<Owner> | null;
     /** The memoized root-level collection for a token, or `undefined` once the chain changed since it was stored. */
     collection(token: Token<unknown> | Constructor): CollectionEntry | undefined;
-    /** Stores a root-level collection under the chain version the last `collection()` read stamped. */
+    /**
+     * Stores a root-level collection under the chain version the last `collection()` read stamped, so a
+     * predicate that binds during the gather leaves the entry stale rather than current.
+     */
     rememberCollection(token: Token<unknown> | Constructor, entry: CollectionEntry): void;
 }