@codefast/di 0.10.1 → 0.12.0

package/dist/introspection/inspector.js

@@ -1,6 +1,7 @@
-import { effectiveBindingScope } from "#core/binding-scope";
+import { effectiveBindingScope } from "#core/binding";
 import { tokenName } from "#core/token";
-import { selectAllBindings } from "#resolution/select/binding-select";
+import { DefaultConstraintContext } from "#resolution/context";
+import { selectAllBindings } from "#resolution/select/candidates";
 // ── Inspector ────────────────────────────────────────────────────────────────────────────────────────────────────────
 /**
  * The read-only introspection surface behind a container's `inspect()`.
@@ -20,7 +21,7 @@ export class Inspector {
     }
     inspect() {
         return {
-            ownBindings: this.#registry.allBindings().map((binding) => this.#toSnapshot(binding)),
+            ownBindings: this.#registry.allBindings().map((binding) => snapshotOf(binding)),
             cachedSingletonCount: this.#scope.cachedSingletons().length,
             hasParent: this.#hasParent,
             isDisposed: this.#isDisposed(),
@@ -28,7 +29,7 @@ export class Inspector {
     }
     lookupBindings(token) {
         const bindings = this.#registry.getAll(token);
-        return bindings.map((binding) => this.#toSnapshot(binding));
+        return bindings.map((binding) => snapshotOf(binding));
     }
     /** Whether this container's own registry holds a binding the request could select. */
     hasOwn(token, options) {
@@ -38,31 +39,32 @@ export class Inspector {
         }
         const bindings = this.#registry.getAll(token);
         // An existence probe answers ambiguity with `true` — several matches still exist; only
-        // resolution has to pick one.
-        return bindings.length > 0 && selectAllBindings(bindings, options, this.#makeConstraintContext(options)).length > 0;
+        // resolution has to pick one. A default-slot alias answers any criteria by forwarding them.
+        return (bindings.length > 0 &&
+            (selectAllBindings(bindings, options, this.#makeConstraintContext(options)).length > 0 ||
+                this.#registry.defaultSlotAlias(token) !== undefined));
     }
     #makeConstraintContext(options) {
-        return {
-            resolutionPath: [],
-            resolutionStack: [],
-            parent: undefined,
-            ancestors: [],
-            currentResolveOptions: options,
-        };
-    }
-    #toSnapshot(binding) {
-        // Aliased, not copied: slot tags are frozen where they are built, so a caller's write throws
-        // instead of corrupting the registry — and the snapshot skips an allocation per binding.
-        const slot = binding.slot.name !== undefined
-            ? { name: binding.slot.name, tags: binding.slot.tags }
-            : { tags: binding.slot.tags };
-        return {
-            tokenName: tokenName(binding.token),
-            kind: binding.kind,
-            scope: effectiveBindingScope(binding),
-            slot,
-            id: binding.identifier,
-            isMany: binding.isMany,
-        };
+        return new DefaultConstraintContext([], options);
     }
+}
+/**
+ * The public snapshot of one binding, the shape every introspection read reports a binding in.
+ *
+ * @since 0.12.0
+ */
+export function snapshotOf(binding) {
+    // Aliased, not copied: slot tags are frozen where they are built, so a caller's write throws
+    // instead of corrupting the registry — and the snapshot skips an allocation per binding.
+    const slot = binding.slot.name !== undefined
+        ? { name: binding.slot.name, tags: binding.slot.tags }
+        : { tags: binding.slot.tags };
+    return {
+        tokenName: tokenName(binding.token),
+        kind: binding.kind,
+        scope: effectiveBindingScope(binding),
+        slot,
+        id: binding.identifier,
+        isMany: binding.isMany,
+    };
 }

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

@@ -1,7 +1,7 @@
 import type { Binding } from "#core/binding";
 import type { Token } from "#core/token";
 import type { ActivationHandler, Constructor, DeactivationHandler, DependencyKey, ResolutionContext } from "#core/types";
-import type { MetadataReader } from "#metadata/metadata-types";
+import type { MetadataReader } from "#metadata/types";
 /**
  * One container's registry of container-level activation and deactivation hooks, keyed by token.
  *
@@ -19,7 +19,14 @@ export declare class LifecycleManager {
     hasDeactivationHandlers<Value>(token: Token<Value> | Constructor<Value>): boolean;
     /** Every token carrying a container-level hook, paired with the phase that registered it. */
     hookedTokens(): Array<[DependencyKey, "onActivation" | "onDeactivation"]>;
-    runActivation<Value>(resolutionContext: ResolutionContext, binding: Binding<Value>, instance: Value, metadataReader: MetadataReader): Promise<Value>;
+    /**
+     * 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<Value>(resolutionContext: ResolutionContext, binding: Binding<Value>, instance: Value, metadataReader: MetadataReader): Value | Promise<Value>;
     runActivationSync<Value>(resolutionContext: ResolutionContext, binding: Binding<Value>, instance: Value, metadataReader: MetadataReader): Value;
     runDeactivation<Value>(binding: Binding<Value>, instance: Value, metadataReader: MetadataReader): Promise<void>;
     runDeactivationSync<Value>(binding: Binding<Value>, instance: Value, metadataReader: MetadataReader): void;

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,35 +73,44 @@ 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")) {
-            if (callHook(activatedInstance, methodName) instanceof Promise) {
+        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
+                // unhandled rejection that ends the process, then report the sync-lane violation.
+                void hookResult.catch(() => { });
                 throw new AsyncActivationError(tokenName(binding.token), "postConstruct", methodName);
             }
         }
@@ -105,18 +118,19 @@ export class LifecycleManager {
         if (binding.kind !== "alias" && binding.activationHook !== undefined) {
             const activationResult = binding.activationHook(resolutionContext, activatedInstance);
             if (activationResult instanceof Promise) {
+                void activationResult.catch(() => { });
                 throw new AsyncActivationError(tokenName(binding.token), "onActivation");
             }
             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) {
-                    throw new AsyncActivationError(tokenDisplayName, "onActivation");
+                    void activationResult.catch(() => { });
+                    throw new AsyncActivationError(tokenName(binding.token), "onActivation");
                 }
                 activatedInstance = activationResult;
             }
@@ -143,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;
@@ -151,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);
@@ -159,7 +172,10 @@ export class LifecycleManager {
             for (const hook of containerHooks) {
                 const hookResult = hook(instance);
                 if (hookResult instanceof Promise) {
-                    throw new AsyncDeactivationError(tokenDisplayName);
+                    // 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(tokenName(binding.token));
                 }
             }
         }
@@ -167,28 +183,41 @@ export class LifecycleManager {
         if (binding.kind !== "alias" && binding.deactivationHook !== undefined) {
             const hookResult = binding.deactivationHook(instance);
             if (hookResult instanceof Promise) {
-                throw new AsyncDeactivationError(tokenDisplayName);
+                void hookResult.catch(() => { });
+                throw new AsyncDeactivationError(tokenName(binding.token));
             }
         }
         // 3. @preDestroy()
-        for (const methodName of lifecycleMethods(binding, metadataReader, "preDestroy")) {
-            if (callHook(instance, methodName) instanceof Promise) {
-                throw new AsyncDeactivationError(tokenDisplayName);
+        for (const methodName of this.#lifecycleMethods(binding, metadataReader, "preDestroy")) {
+            const hookResult = callHook(instance, methodName);
+            if (hookResult instanceof Promise) {
+                void hookResult.catch(() => { });
+                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.
  *
@@ -39,35 +39,41 @@ export class ScopeManager {
         }
         binding.instance = instance;
     }
+    // A removal only clears the instance; the list keeps its entry until a read compacts it, so a
+    // teardown of a hundred singletons is a hundred field writes, not a hundred splices.
+    #compacted = true;
     /** Every binding in this container holding a cached singleton. */
     cachedSingletons() {
-        return this.#singletonBindings ?? EMPTY_BINDINGS;
+        const tracked = this.#singletonBindings;
+        if (tracked === undefined) {
+            return EMPTY_BINDINGS;
+        }
+        if (!this.#compacted) {
+            // Latest materialization wins the position: walk from the end keeping each live binding once.
+            const seen = new Set();
+            const live = [];
+            for (let index = tracked.length - 1; index >= 0; index -= 1) {
+                const binding = tracked[index];
+                if (binding.instance !== NO_INSTANCE && !seen.has(binding)) {
+                    seen.add(binding);
+                    live.push(binding);
+                }
+            }
+            live.reverse();
+            this.#singletonBindings = live;
+            this.#compacted = true;
+            return live;
+        }
+        return tracked;
     }
     deleteSingleton(binding) {
         if (binding.instance === NO_INSTANCE) {
             return false;
         }
         binding.instance = NO_INSTANCE;
-        const tracked = this.#singletonBindings;
-        if (tracked !== undefined) {
-            const index = tracked.indexOf(binding);
-            if (index !== -1) {
-                tracked.splice(index, 1);
-            }
-        }
+        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);
     }
@@ -83,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() {
@@ -112,10 +118,11 @@ export class ScopeManager {
     clearAll() {
         const tracked = this.#singletonBindings;
         if (tracked !== undefined) {
-            for (const binding of tracked) {
-                binding.instance = NO_INSTANCE;
+            for (let index = 0; index < tracked.length; index += 1) {
+                tracked[index].instance = NO_INSTANCE;
             }
             tracked.length = 0;
+            this.#compacted = true;
         }
         this.#inflight?.clear();
         this.#scoped?.clear();

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`);
+            }
+        }
+    });
+}