@codefast/di 0.11.0 → 0.12.0

package/dist/lifecycle/{lifecycle-manager.js → hooks.js}

@@ -1,7 +1,7 @@
 import { getOrInsert } from "#core/map-upsert";
 import { advanceStateEpoch } from "#core/state-epoch";
 import { tokenName } from "#core/token";
-import { AsyncActivationError, AsyncDeactivationError, InvalidMetadataError } from "#errors/errors";
+import { AsyncActivationError, AsyncDeactivationError, InvalidMetadataError } from "#errors";
 /**
  * One container's registry of container-level activation and deactivation hooks, keyed by token.
  *
@@ -17,6 +17,10 @@ export class LifecycleManager {
     // and registration is the only thing that can change the answer.
     #cachedToken;
     #cachedHooks;
+    // The class whose hooks were read last, and through which reader: a teardown walks many bindings of one class.
+    #lastLifecycleTarget;
+    #lastLifecycleReader;
+    #lastLifecycle;
     registerActivation(token, handler) {
         this.#activationVersion += 1;
         advanceStateEpoch();
@@ -69,34 +73,39 @@ export class LifecycleManager {
         }
         return hooked;
     }
-    async runActivation(resolutionContext, binding, instance, metadataReader) {
-        let activatedInstance = instance;
+    /**
+     * Runs the activation pipeline on the async lane: the activated instance, or its promise once a
+     * hook has returned one.
+     *
+     * @remarks A level yields only where a hook does, so a synchronous pipeline hands the instance
+     * back in the caller's own tick and a singleton it activates is cached before any sibling reads it.
+     */
+    runActivation(resolutionContext, binding, instance, metadataReader) {
+        let activated = instance;
         // 1. @postConstruct() — after TC39 construction (constructor + accessor addInitializer callbacks)
-        for (const methodName of lifecycleMethods(binding, metadataReader, "postConstruct")) {
-            const hookResult = callHook(activatedInstance, methodName);
-            if (hookResult instanceof Promise) {
-                await hookResult;
-            }
+        for (const methodName of this.#lifecycleMethods(binding, metadataReader, "postConstruct")) {
+            activated = afterActivationStep(activated, (current) => {
+                const hookResult = callHook(current, methodName);
+                return hookResult instanceof Promise ? hookResult.then(() => current) : current;
+            });
         }
         // 2. per-binding onActivation
         if (binding.kind !== "alias" && binding.activationHook !== undefined) {
-            const activationResult = binding.activationHook(resolutionContext, activatedInstance);
-            activatedInstance = activationResult instanceof Promise ? await activationResult : activationResult;
+            activated = afterActivationStep(activated, (current) => binding.activationHook(resolutionContext, current));
         }
         // 3. container-level onActivation
         const containerHooks = this.#activationHooks?.get(binding.token);
         if (containerHooks !== undefined) {
             for (const hook of containerHooks) {
-                const activationResult = hook(resolutionContext, activatedInstance);
-                activatedInstance = (activationResult instanceof Promise ? await activationResult : activationResult);
+                activated = afterActivationStep(activated, (current) => hook(resolutionContext, current));
             }
         }
-        return activatedInstance;
+        return activated;
     }
     runActivationSync(resolutionContext, binding, instance, metadataReader) {
         let activatedInstance = instance;
         // 1. @postConstruct() — must be sync (instance fully constructed per TC39 order)
-        for (const methodName of lifecycleMethods(binding, metadataReader, "postConstruct")) {
+        for (const methodName of this.#lifecycleMethods(binding, metadataReader, "postConstruct")) {
             const hookResult = callHook(activatedInstance, methodName);
             if (hookResult instanceof Promise) {
                 // The hook has already run; adopt its rejection so a failing async hook cannot become an
@@ -115,14 +124,13 @@ export class LifecycleManager {
             activatedInstance = activationResult;
         }
         // 3. container-level onActivation (must be sync)
-        const tokenDisplayName = tokenName(binding.token);
         const containerHooks = this.#activationHooks?.get(binding.token);
         if (containerHooks !== undefined) {
             for (const hook of containerHooks) {
                 const activationResult = hook(resolutionContext, activatedInstance);
                 if (activationResult instanceof Promise) {
                     void activationResult.catch(() => { });
-                    throw new AsyncActivationError(tokenDisplayName, "onActivation");
+                    throw new AsyncActivationError(tokenName(binding.token), "onActivation");
                 }
                 activatedInstance = activationResult;
             }
@@ -149,7 +157,7 @@ export class LifecycleManager {
             }
         }
         // 3. @preDestroy() — all methods in declaration order
-        for (const methodName of lifecycleMethods(binding, metadataReader, "preDestroy")) {
+        for (const methodName of this.#lifecycleMethods(binding, metadataReader, "preDestroy")) {
             const hookResult = callHook(instance, methodName);
             if (hookResult instanceof Promise) {
                 await hookResult;
@@ -157,7 +165,6 @@ export class LifecycleManager {
         }
     }
     runDeactivationSync(binding, instance, metadataReader) {
-        const tokenDisplayName = tokenName(binding.token);
         const tokenKey = binding.token;
         // 1. container-level onDeactivation
         const containerHooks = this.#deactivationHooks?.get(tokenKey);
@@ -168,7 +175,7 @@ export class LifecycleManager {
                     // The hook has already run; adopt its rejection so a failing async hook cannot become an
                     // unhandled rejection that ends the process, then report the sync-lane violation.
                     void hookResult.catch(() => { });
-                    throw new AsyncDeactivationError(tokenDisplayName);
+                    throw new AsyncDeactivationError(tokenName(binding.token));
                 }
             }
         }
@@ -177,30 +184,40 @@ export class LifecycleManager {
             const hookResult = binding.deactivationHook(instance);
             if (hookResult instanceof Promise) {
                 void hookResult.catch(() => { });
-                throw new AsyncDeactivationError(tokenDisplayName);
+                throw new AsyncDeactivationError(tokenName(binding.token));
             }
         }
         // 3. @preDestroy()
-        for (const methodName of lifecycleMethods(binding, metadataReader, "preDestroy")) {
+        for (const methodName of this.#lifecycleMethods(binding, metadataReader, "preDestroy")) {
             const hookResult = callHook(instance, methodName);
             if (hookResult instanceof Promise) {
                 void hookResult.catch(() => { });
-                throw new AsyncDeactivationError(tokenDisplayName);
+                throw new AsyncDeactivationError(tokenName(binding.token));
             }
         }
     }
+    /** The `@postConstruct` / `@preDestroy` methods a binding declares — only a class can declare any. */
+    #lifecycleMethods(binding, metadataReader, phase) {
+        if (binding.kind !== "class") {
+            return NO_METHODS;
+        }
+        const target = binding.target;
+        if (target !== this.#lastLifecycleTarget || metadataReader !== this.#lastLifecycleReader) {
+            this.#lastLifecycle = metadataReader.getLifecycleMetadata(target);
+            this.#lastLifecycleTarget = target;
+            this.#lastLifecycleReader = metadataReader;
+        }
+        return this.#lastLifecycle?.[phase] ?? NO_METHODS;
+    }
     /** Whether the deferred activation-hook table has had to be built. */
     get isActivationTableBuilt() {
         return this.#activationHooks !== undefined;
     }
 }
 const NO_METHODS = [];
-/** The `@postConstruct` / `@preDestroy` methods a binding declares — only a class can declare any. */
-function lifecycleMethods(binding, metadataReader, phase) {
-    if (binding.kind !== "class") {
-        return NO_METHODS;
-    }
-    return metadataReader.getLifecycleMetadata(binding.target)?.[phase] ?? NO_METHODS;
+/** Applies one activation step now, or once the step before it has settled. */
+function afterActivationStep(activated, step) {
+    return activated instanceof Promise ? activated.then(step) : step(activated);
 }
 /**
  * Invokes a lifecycle hook by name.

package/dist/lifecycle/{scope-manager.d.ts → scopes.d.ts}

@@ -17,8 +17,6 @@ export declare class ScopeManager {
     /** Every binding in this container holding a cached singleton. */
     cachedSingletons(): ReadonlyArray<Binding<unknown>>;
     deleteSingleton<Value>(binding: Binding<Value>): boolean;
-    /** Swaps a re-slotted binding's tracked entry, so teardown pairs the instance with the live object. */
-    replaceSingleton(previous: Binding, next: Binding): void;
     getInflight(id: BindingIdentifier): Promise<unknown> | undefined;
     setInflight(id: BindingIdentifier, promise: Promise<unknown>): void;
     clearInflight(id: BindingIdentifier): void;
@@ -28,11 +26,11 @@ export declare class ScopeManager {
      * @remarks One map read answers both existence and value; a cached `undefined` is the only
      * shape that pays for a second, and it is the rare one.
      */
-    readScoped(id: BindingIdentifier): unknown;
+    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. A scoped instance has no deactivation. */
-    deleteScoped(id: BindingIdentifier): void;
+    /** Releases a removed binding's scoped instance, by its scoped cache key. A scoped instance has no deactivation. */
+    deleteScoped(key: BindingIdentifier): void;
     /** Scoped instances currently cached — a structural count for diagnostics. */
     get scopedCount(): number;
     clearAll(): void;

package/dist/lifecycle/{scope-manager.js → scopes.js}

@@ -1,6 +1,6 @@
 import { NO_INSTANCE } from "#core/binding";
 import { tokenName } from "#core/token";
-import { MissingScopeContextError } from "#errors/errors";
+import { MissingScopeContextError } from "#errors";
 /**
  * One container's instance caches — singletons, in-flight async creations, and the scoped cache.
  *
@@ -74,17 +74,6 @@ export class ScopeManager {
         this.#compacted = false;
         return true;
     }
-    /** Swaps a re-slotted binding's tracked entry, so teardown pairs the instance with the live object. */
-    replaceSingleton(previous, next) {
-        const tracked = this.#singletonBindings;
-        if (tracked === undefined) {
-            return;
-        }
-        const index = tracked.indexOf(previous);
-        if (index !== -1) {
-            tracked[index] = next;
-        }
-    }
     getInflight(id) {
         return this.#inflight?.get(id);
     }
@@ -100,27 +89,27 @@ export class ScopeManager {
      * @remarks One map read answers both existence and value; a cached `undefined` is the only
      * shape that pays for a second, and it is the rare one.
      */
-    readScoped(id) {
+    readScoped(key) {
         const scoped = this.#scoped;
         if (scoped === undefined) {
             return SCOPED_MISS;
         }
-        const cached = scoped.get(id);
+        const cached = scoped.get(key);
         if (cached !== undefined) {
             return cached;
         }
-        return scoped.has(id) ? undefined : SCOPED_MISS;
+        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) {
         if (!this.isChild) {
             throw new MissingScopeContextError(tokenName(binding.token));
         }
-        (this.#scoped ??= new Map()).set(binding.identifier, instance);
+        (this.#scoped ??= new Map()).set(binding.scopedCacheKey, instance);
     }
-    /** Releases a removed binding's scoped instance. A scoped instance has no deactivation. */
-    deleteScoped(id) {
-        this.#scoped?.delete(id);
+    /** Releases a removed binding's scoped instance, by its scoped cache key. A scoped instance has no deactivation. */
+    deleteScoped(key) {
+        this.#scoped?.delete(key);
     }
     /** Scoped instances currently cached — a structural count for diagnostics. */
     get scopedCount() {

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

@@ -1,5 +1,5 @@
 import type { Token } from "#core/token";
-import type { MetadataReader } from "#metadata/metadata-types";
+import type { MetadataReader } from "#metadata/types";
 /**
  * The token a custom `MetadataReader` is bound to for a container to pick up.
  *

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

@@ -1,6 +1,6 @@
 import type { Constructor } from "#core/types";
 import type { InjectionDescriptor } from "#injection/descriptor";
-import type { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "#metadata/metadata-types";
+import type { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "#metadata/types";
 type AccessorEntry = {
     readonly key: string | symbol;
     readonly descriptor: InjectionDescriptor;

package/dist/metadata/{symbol-metadata-reader.js → symbol-reader.js}

@@ -1,4 +1,4 @@
-import { INJECT_ACCESSOR_KEY, INJECTABLE_KEY, LIFECYCLE_KEY, METADATA_SYMBOL } from "#metadata/metadata-keys";
+import { INJECT_ACCESSOR_KEY, INJECTABLE_KEY, LIFECYCLE_KEY, METADATA_SYMBOL } from "#metadata/keys";
 /**
  * The default `MetadataReader`, reading decorator metadata stored under `Symbol.metadata`.
  *

package/dist/metadata/{metadata-types.d.ts → types.d.ts}

@@ -1,6 +1,6 @@
 import type { Constructor } from "#core/types";
+import type { DependencySlot } from "#injection/dependency-slot";
 import type { InjectionDescriptor } from "#injection/descriptor";
-import type { DependencySlot } from "#injection/resolve-options";
 /**
  * One constructor parameter's declaration.
  *

package/dist/metadata/types.js

@@ -0,0 +1 @@
+export {};

package/dist/metadata/verify.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Verification of what a foreign `MetadataReader` claims about a class, done once per reader and class.
+ */
+import type { Constructor } from "#core/types";
+import type { InjectionDescriptor } from "#injection/descriptor";
+import type { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "#metadata/types";
+/**
+ * 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 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;

package/dist/metadata/verify.js

@@ -0,0 +1,133 @@
+import { InvalidMetadataError } from "#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;
+    }
+    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`);
+            }
+        }
+    });
+}

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

@@ -2,7 +2,7 @@
  * Wraps a foreign {@link MetadataReader} so its answers are verified before anything dereferences
  * 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 and memoized when it came from outside.
  *

package/dist/metadata/{verifying-metadata-reader.js → verifying-reader.js}

@@ -2,8 +2,8 @@
  * 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-metadata-reader";
-import { verifyAccessorMetadata, verifyConstructorMetadata, verifyLifecycleMetadata, } from "#resolution/cache/class-introspector";
+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.

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.

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

@@ -48,7 +48,11 @@ 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);

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

@@ -3,57 +3,44 @@
  *
  * @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.
      *
@@ -74,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;
 }