@codefast/di 0.5.0 → 0.6.0

package/src/container/container.ts

@@ -1,8 +1,25 @@
-import type { Binding, BindToBuilder } from "#/binding";
-import { NO_INSTANCE } from "#/binding";
 import type { BindingRegistration } from "#/container/binding-builders";
 import { BindingChain } from "#/container/binding-builders";
+import type { Binding, BindingBuilder, BindToBuilder, ConstantBinding } from "#/core/binding";
+import { NO_INSTANCE } from "#/core/binding";
+import { effectiveBindingScope } from "#/core/binding-scope";
+import { constraintRequirementOf } from "#/core/constraint-requirement";
+import type { AsyncModule, AsyncModuleBuilder, ModuleBuilder, SyncModule } from "#/core/module";
+import { isSyncModule, MODULE_SETUP } from "#/core/module";
+import { BindingRegistry } from "#/core/registry";
+import type { Token } from "#/core/token";
+import { tokenName } from "#/core/token";
+import type {
+  ActivationHandler,
+  BindingIdentifier,
+  BindingScope,
+  Constructor,
+  DeactivationHandler,
+  ResolveOptions,
+} from "#/core/types";
 import type { AutoRegisterRegistry } from "#/decorators/injectable";
+import type { ResolutionDiagnostics } from "#/errors/diagnostics";
+import { RESOLUTION_DIAGNOSTICS } from "#/errors/diagnostics";
 import {
   AsyncModuleLoadError,
   CircularDependencyError,
@@ -11,39 +28,25 @@ import {
   RebindUnboundTokenError,
   ScopeViolationError,
   SyncDisposalNotSupportedError,
-} from "#/errors";
+  UnreachableConstraintError,
+  UnreachableLifecycleHookError,
+} from "#/errors/errors";
+import type { DependencySlot } from "#/injection/resolve-options";
+import { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#/injection/resolve-options";
 import type { ContainerGraphJson, GraphOptions } from "#/introspection/dependency-graph";
 import { buildDependencyGraph } from "#/introspection/dependency-graph";
 import type { BindingSnapshot, ContainerSnapshot } from "#/introspection/inspector";
 import { Inspector } from "#/introspection/inspector";
+import { LifecycleManager } from "#/lifecycle/lifecycle-manager";
+import { ScopeManager } from "#/lifecycle/scope-manager";
 import { MetadataReaderToken } from "#/metadata/metadata-reader-token";
 import type { MetadataReader } from "#/metadata/metadata-types";
 import { defaultMetadataReader } from "#/metadata/symbol-metadata-reader";
-import type { AsyncModule, ModuleBuilder, SyncModule } from "#/module";
-import type { AsyncModuleBuilder } from "#/module";
-import { isSyncModule, MODULE_SETUP } from "#/module";
-import { BindingRegistry } from "#/registry";
-import { effectiveBindingScope } from "#/resolution/binding-scope";
-import type { ResolutionDiagnostics } from "#/resolution/diagnostics";
-import { RESOLUTION_DIAGNOSTICS } from "#/resolution/diagnostics";
-import { LifecycleManager } from "#/resolution/lifecycle";
-import { ROOT_BRANCH } from "#/resolution/resolution-path";
-import type { DependencySlot } from "#/resolution/resolve-options";
-import { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#/resolution/resolve-options";
+import { verifyingMetadataReader } from "#/metadata/verifying-metadata-reader";
+import { ROOT_BRANCH } from "#/resolution/path/resolution-path";
 import { DependencyResolver } from "#/resolution/resolver";
-import { ScopeManager } from "#/resolution/scope";
-import type { Token } from "#/token";
-import { tokenName } from "#/token";
-import type {
-  ActivationHandler,
-  BindingIdentifier,
-  BindingScope,
-  Constructor,
-  DeactivationHandler,
-  ResolveOptions,
-} from "#/types";
 
-// ── Container interface ────────────────────────────────────────────────────────
+// ── Container interface ──────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
@@ -51,12 +54,12 @@ import type {
 export interface Container {
   readonly isDisposed: boolean;
 
-  bind<const Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value>;
+  bind<Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value>;
   unbind(tokenOrId: Token<unknown> | Constructor | BindingIdentifier): void;
   unbindAsync(tokenOrId: Token<unknown> | Constructor | BindingIdentifier): Promise<void>;
   unbindAll(): void;
   unbindAllAsync(): Promise<void>;
-  rebind<const Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value>;
+  rebind<Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value>;
 
   load(...modules: Array<SyncModule>): void;
   loadAsync(...modules: Array<SyncModule | AsyncModule>): Promise<void>;
@@ -64,21 +67,18 @@ export interface Container {
   unloadAsync(...modules: Array<SyncModule | AsyncModule>): Promise<void>;
   loadAutoRegistered(registry: AutoRegisterRegistry): number;
 
-  onActivation<const Value>(token: Token<Value> | Constructor<Value>, handler: ActivationHandler<Value>): void;
-  onDeactivation<const Value>(token: Token<Value> | Constructor<Value>, handler: DeactivationHandler<Value>): void;
+  onActivation<Value>(token: Token<Value> | Constructor<Value>, handler: ActivationHandler<Value>): void;
+  onDeactivation<Value>(token: Token<Value> | Constructor<Value>, handler: DeactivationHandler<Value>): void;
 
-  resolve<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value;
-  resolveAsync<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
-  resolveOptional<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
-  resolveOptionalAsync<const Value>(
+  resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value;
+  resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
+  resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
+  resolveOptionalAsync<Value>(
     token: Token<Value> | Constructor<Value>,
     options?: ResolveOptions,
   ): Promise<Value | undefined>;
-  resolveAll<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value>;
-  resolveAllAsync<const Value>(
-    token: Token<Value> | Constructor<Value>,
-    options?: ResolveOptions,
-  ): Promise<Array<Value>>;
+  resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value>;
+  resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>>;
 
   createChild(): Container;
 
@@ -91,24 +91,56 @@ export interface Container {
 
   has(token: Token<unknown> | Constructor, options?: ResolveOptions): boolean;
   hasOwn(token: Token<unknown> | Constructor, options?: ResolveOptions): boolean;
-  lookupBindings<const Value>(token: Token<Value> | Constructor<Value>): ReadonlyArray<BindingSnapshot>;
+  lookupBindings<Value>(token: Token<Value> | Constructor<Value>): ReadonlyArray<BindingSnapshot>;
   inspect(): ContainerSnapshot;
   generateDependencyGraph(options?: GraphOptions): ContainerGraphJson;
 }
 
+/**
+ * What a container has to be told before it exists, as opposed to what it can be bound later.
+ *
+ * @since 0.6.0
+ */
+export interface ContainerOptions {
+  /**
+   * Reader the resolver consults for class metadata, replacing the decorator reader.
+   *
+   * @remarks Takes precedence over a {@link MetadataReaderToken} binding, and children inherit it.
+   * A resolver is handed its reader when it is built, so this is the only way to give the container
+   * you are creating a reader of your own.
+   */
+  readonly metadataReader?: MetadataReader | undefined;
+}
+
 /**
  * @since 0.3.16-canary.0
  */
 export interface ContainerStatic {
-  create(): Container;
+  create(options?: ContainerOptions): Container;
   fromModules(...modules: Array<SyncModule>): Container;
   fromModulesAsync(...modules: Array<SyncModule | AsyncModule>): Promise<Container>;
 }
 
-// ── DefaultContainer ──────────────────────────────────────────────────────────
+// A Record rather than an if-chain, so a new `BindingScope` is a compile error here instead of
+// silently landing in whichever branch happened to be last.
+const APPLY_BINDING_SCOPE: Record<BindingScope, (builder: BindingBuilder<unknown>) => void> = {
+  singleton: (builder) => {
+    builder.singleton();
+  },
+  scoped: (builder) => {
+    builder.scoped();
+  },
+  transient: (builder) => {
+    builder.transient();
+  },
+};
+
+// ── DefaultContainer ─────────────────────────────────────────────────────────────────────────────────────────────────
 
 class DefaultContainer implements Container {
   #disposed = false;
+  // The one teardown run — every dispose() call returns it once it exists.
+  #disposePromise: Promise<void> | undefined;
   readonly #registry: BindingRegistry;
   readonly #scope: ScopeManager;
   readonly #lifecycle: LifecycleManager;
@@ -124,12 +156,12 @@ class DefaultContainer implements Container {
   // One shared registration for every chain this container's own `bind()` creates.
   #registration: BindingRegistration | undefined;
 
-  constructor(parent?: DefaultContainer) {
+  constructor(parent?: DefaultContainer, options?: ContainerOptions) {
     this.#parent = parent;
     this.#registry = new BindingRegistry();
     this.#scope = new ScopeManager(parent !== undefined);
     this.#lifecycle = new LifecycleManager();
-    this.#initResolver();
+    this.#initResolver(options?.metadataReader);
   }
 
   #getInspector(): Inspector {
@@ -149,21 +181,27 @@ class DefaultContainer implements Container {
     if (this.#moduleRefs !== undefined || this.#moduleBindingIds !== undefined) {
       builtSubsystems.push("container.moduleTables");
     }
-    if (this.#registry.isBuilt) {
+    if (this.#registry.isNamedIndexBuilt) {
       builtSubsystems.push("registry.namedIndex");
     }
-    if (this.#scope.isBuilt) {
+    if (this.#registry.isTaggedIndexBuilt) {
+      builtSubsystems.push("registry.taggedIndex");
+    }
+    if (this.#scope.isScopedCacheBuilt) {
       builtSubsystems.push("scope.scoped");
     }
-    if (this.#lifecycle.isBuilt) {
+    if (this.#lifecycle.isActivationTableBuilt) {
       builtSubsystems.push("lifecycle.activationHooks");
     }
     return { ...this.#resolver.describeCaches(), scopedInstanceCount: this.#scope.scopedCount, builtSubsystems };
   }
 
-  #initResolver(): void {
-    const metadataReader = this.#getMetadataReader();
-    const parentResolver = this.#parent === undefined ? undefined : this.#parent.#resolver;
+  #initResolver(configuredReader: MetadataReader | undefined): void {
+    const parent = this.#parent;
+    const metadataReader = verifyingMetadataReader(
+      configuredReader ?? (parent === undefined ? defaultMetadataReader : parent.#readerForChild()),
+    );
+    const parentResolver = parent === undefined ? undefined : parent.#resolver;
     this.#resolver = new DependencyResolver(
       this.#registry,
       this.#scope,
@@ -174,47 +212,49 @@ class DefaultContainer implements Container {
     );
   }
 
-  #getMetadataReader(): MetadataReader {
-    // Check if a custom MetadataReader has been bound
-    const metaBindings = this.#registry.getAll(MetadataReaderToken);
-    if (metaBindings.length > 0) {
+  /** What a container being constructed under this one inherits: a reader bound here, else this one's. */
+  #readerForChild(): MetadataReader {
+    if (this.#registry.getAll(MetadataReaderToken).length > 0) {
       try {
-        return this.#resolver.resolve(MetadataReaderToken, undefined, [], []);
+        return this.#resolver.resolve(MetadataReaderToken, undefined, []);
       } catch {
-        // fall through to default
+        // An unresolvable reader binding is not worth failing a child over.
       }
     }
-    if (this.#parent !== undefined) {
-      return this.#parent.#getMetadataReader();
-    }
-    return defaultMetadataReader;
+    return this.#resolver.metadataReader;
+  }
+
+  /** One reader per container, fixed when its resolver was built — so every path agrees on it. */
+  #getMetadataReader(): MetadataReader {
+    return this.#resolver.metadataReader;
   }
 
   get isDisposed(): boolean {
     return this.#disposed;
   }
 
-  // ── Binding ──────────────────────────────────────────────────────────────
+  // ── Binding ────────────────────────────────────────────────────────────────────────────────────────────────────────
 
-  bind<const Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value> {
+  bind<Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value> {
     this.#assertNotDisposed();
     return this.#createBindToBuilder(token);
   }
 
   /** The registration every non-module chain shares, so `bind()` allocates only the builder. */
   #ownRegistration(): BindingRegistration {
-    return (this.#registration ??= { registry: this.#registry, moduleBindingIds: undefined });
+    return (this.#registration ??= { registry: this.#registry, scope: this.#scope, moduleBindingIds: undefined });
   }
 
   /** One registration per module load, holding that module's id list directly. */
   #moduleRegistration(moduleRef: object): BindingRegistration {
     return {
       registry: this.#registry,
+      scope: this.#scope,
       moduleBindingIds: (this.#moduleBindingIds ??= new Map()).getOrInsert(moduleRef, []),
     };
   }
 
-  #createBindToBuilder<const Value>(
+  #createBindToBuilder<Value>(
     token: Token<Value> | Constructor<Value>,
     registration: BindingRegistration = this.#ownRegistration(),
   ): BindToBuilder<Value> {
@@ -237,51 +277,88 @@ class DefaultContainer implements Container {
     return this.#drainSingletons(this.#registry.removeByToken(tokenOrId));
   }
 
-  /** Drain scope entries for already-removed bindings; only singletons yield deactivation pairs. */
+  /** Drain scope entries for already-removed bindings, and pair each one that still owes a deactivation. */
   #drainSingletons(bindings: ReadonlyArray<Binding>): Array<[Binding, unknown]> {
     const pairs: Array<[Binding, unknown]> = [];
     for (const binding of bindings) {
       if (binding.instance !== NO_INSTANCE) {
         pairs.push([binding, binding.instance]);
         this.#scope.deleteSingleton(binding);
+      } else if (this.#owesConstantDeactivation(binding)) {
+        pairs.push([binding, binding.value]);
       }
       this.#scope.deleteScoped(binding.id);
     }
     return pairs;
   }
 
-  #unbindSync(tokenOrId: Token<unknown> | Constructor | BindingIdentifier): void {
+  /**
+   * Whether a constant still owes its deactivation.
+   *
+   * @remarks A constant's value is handed in at bind time rather than built on demand, so its hook is
+   * owed whether or not anything ever resolved it. Callers check `instance` first: a constant that
+   * carries one was cached through activation and is deactivated with that value instead.
+   */
+  #owesConstantDeactivation(binding: Binding): binding is ConstantBinding<unknown> {
+    return (
+      binding.kind === "constant" &&
+      (binding.onDeactivation !== undefined || this.#lifecycle.hasDeactivationHandlers(binding.token))
+    );
+  }
+
+  /** Runs every pair's deactivation even when one throws, then reports what threw. */
+  #deactivatePairsSync(pairs: ReadonlyArray<[Binding, unknown]>): void {
+    if (pairs.length === 0) {
+      return;
+    }
     const reader = this.#getMetadataReader();
-    for (const [binding, instance] of this.#collectDeactivationPairs(tokenOrId)) {
-      this.#lifecycle.runDeactivationSync(binding, instance, reader);
+    const errors: Array<unknown> = [];
+    for (const [binding, instance] of pairs) {
+      try {
+        this.#lifecycle.runDeactivationSync(binding, instance, reader);
+      } catch (error) {
+        errors.push(error);
+      }
     }
+    throwCollected(errors, "unbind completed, but deactivation hooks threw");
   }
 
-  async unbindAsync(tokenOrId: Token<unknown> | Constructor | BindingIdentifier): Promise<void> {
-    this.#assertNotDisposed();
+  async #deactivatePairs(pairs: ReadonlyArray<[Binding, unknown]>): Promise<void> {
+    if (pairs.length === 0) {
+      return;
+    }
     const reader = this.#getMetadataReader();
-    for (const [binding, instance] of this.#collectDeactivationPairs(tokenOrId)) {
-      await this.#lifecycle.runDeactivation(binding, instance, reader);
+    const errors: Array<unknown> = [];
+    for (const [binding, instance] of pairs) {
+      try {
+        await this.#lifecycle.runDeactivation(binding, instance, reader);
+      } catch (error) {
+        errors.push(error);
+      }
     }
+    throwCollected(errors, "unbind completed, but deactivation hooks threw");
+  }
+
+  #unbindSync(tokenOrId: Token<unknown> | Constructor | BindingIdentifier): void {
+    this.#deactivatePairsSync(this.#collectDeactivationPairs(tokenOrId));
+  }
+
+  async unbindAsync(tokenOrId: Token<unknown> | Constructor | BindingIdentifier): Promise<void> {
+    this.#assertNotDisposed();
+    await this.#deactivatePairs(this.#collectDeactivationPairs(tokenOrId));
   }
 
   unbindAll(): void {
     this.#assertNotDisposed();
-    const reader = this.#getMetadataReader();
-    for (const [binding, instance] of this.#drainSingletons(this.#registry.clear())) {
-      this.#lifecycle.runDeactivationSync(binding, instance, reader);
-    }
+    this.#deactivatePairsSync(this.#drainSingletons(this.#registry.clear()));
   }
 
   async unbindAllAsync(): Promise<void> {
     this.#assertNotDisposed();
-    const reader = this.#getMetadataReader();
-    for (const [binding, instance] of this.#drainSingletons(this.#registry.clear())) {
-      await this.#lifecycle.runDeactivation(binding, instance, reader);
-    }
+    await this.#deactivatePairs(this.#drainSingletons(this.#registry.clear()));
   }
 
-  rebind<const Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value> {
+  rebind<Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value> {
     this.#assertNotDisposed();
     if (!this.#registry.has(token)) {
       throw new RebindUnboundTokenError(tokenName(token));
@@ -291,7 +368,7 @@ class DefaultContainer implements Container {
     return this.#createBindToBuilder(token);
   }
 
-  // ── Module ────────────────────────────────────────────────────────────────
+  // ── Module ─────────────────────────────────────────────────────────────────────────────────────────────────────────
 
   load(...modules: Array<SyncModule>): void {
     this.#assertNotDisposed();
@@ -314,17 +391,43 @@ class DefaultContainer implements Container {
       }
       moduleRefs.set(moduleRef, 1);
       const builder = this.#createModuleBuilder(moduleRef);
-      module[MODULE_SETUP](builder);
+      try {
+        module[MODULE_SETUP](builder);
+      } catch (error) {
+        throw this.#rollbackFailedLoadSync(moduleRef, error);
+      }
     }
   }
 
   async loadAsync(...modules: Array<SyncModule | AsyncModule>): Promise<void> {
     this.#assertNotDisposed();
-    for (const module of modules) {
+    // Deduped by identity like the sync lane, so `loadAsync(m, m)` ref-counts once.
+    for (const module of new Set(modules)) {
       await this.#loadOneModuleAsync(module);
     }
   }
 
+  /** Undo a failed load — bindings registered before the throw and the ref-count both roll back. */
+  #rollbackFailedLoadSync(moduleRef: object, cause: unknown): unknown {
+    const pairs = this.#removeModuleBindings(moduleRef);
+    try {
+      this.#deactivatePairsSync(pairs);
+    } catch (rollbackError) {
+      return new AggregateError([cause, rollbackError], "module load failed, and rolling it back threw too");
+    }
+    return cause;
+  }
+
+  async #rollbackFailedLoad(moduleRef: object, cause: unknown): Promise<unknown> {
+    const pairs = this.#removeModuleBindings(moduleRef);
+    try {
+      await this.#deactivatePairs(pairs);
+    } catch (rollbackError) {
+      return new AggregateError([cause, rollbackError], "module load failed, and rolling it back threw too");
+    }
+    return cause;
+  }
+
   async #loadOneModuleAsync(module: SyncModule | AsyncModule): Promise<void> {
     const moduleRef = module as object;
     const moduleRefs = (this.#moduleRefs ??= new Map());
@@ -337,14 +440,25 @@ class DefaultContainer implements Container {
 
     if (isSyncModule(module)) {
       const builder = this.#createModuleBuilder(moduleRef);
-      module[MODULE_SETUP](builder);
+      try {
+        module[MODULE_SETUP](builder);
+      } catch (error) {
+        throw this.#rollbackFailedLoadSync(moduleRef, error);
+      }
     } else {
       const importPromises: Array<Promise<void>> = [];
       const builder = this.#createAsyncModuleBuilder(moduleRef, importPromises);
-      await module[MODULE_SETUP](builder);
-      // Await nested async imports triggered inside the setup callback
-      if (importPromises.length > 0) {
-        await Promise.all(importPromises);
+      try {
+        await module[MODULE_SETUP](builder);
+        // Await nested async imports triggered inside the setup callback
+        if (importPromises.length > 0) {
+          await Promise.all(importPromises);
+        }
+      } catch (error) {
+        // Nested imports may still be registering — let them settle before rolling back, so no
+        // registration lands after the rejection and none becomes an unhandled rejection.
+        await Promise.allSettled(importPromises);
+        throw await this.#rollbackFailedLoad(moduleRef, error);
       }
     }
   }
@@ -352,7 +466,7 @@ class DefaultContainer implements Container {
   #createModuleBuilder(moduleRef: object): ModuleBuilder {
     const registration = this.#moduleRegistration(moduleRef);
     return {
-      bind: <const Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value> =>
+      bind: <Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value> =>
         this.#createBindToBuilder(token, registration),
       import: (...modules: Array<SyncModule>): void => {
         this.#loadSyncModules(modules);
@@ -363,7 +477,7 @@ class DefaultContainer implements Container {
   #createAsyncModuleBuilder(moduleRef: object, importPromises: Array<Promise<void>>): AsyncModuleBuilder {
     const registration = this.#moduleRegistration(moduleRef);
     return {
-      bind: <const Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value> =>
+      bind: <Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value> =>
         this.#createBindToBuilder(token, registration),
       import: (...modules: Array<SyncModule | AsyncModule>): void => {
         for (const module of modules) {
@@ -385,28 +499,20 @@ class DefaultContainer implements Container {
     this.#moduleRefs?.delete(ref);
     const ids = this.#moduleBindingIds?.get(ref) ?? [];
     this.#moduleBindingIds?.delete(ref);
-    const pairs: Array<[Binding, unknown]> = [];
+    const removed: Array<Binding> = [];
     for (const id of ids) {
-      const binding = this.#registry.getById(id);
+      const binding = this.#registry.removeById(id);
       if (binding !== undefined) {
-        this.#registry.removeById(id);
-        if (binding.instance !== NO_INSTANCE) {
-          pairs.push([binding, binding.instance]);
-          this.#scope.deleteSingleton(binding);
-        }
-        this.#scope.deleteScoped(binding.id);
+        removed.push(binding);
       }
     }
-    return pairs;
+    return this.#drainSingletons(removed);
   }
 
   #unloadModuleSync(ref: object): void {
     const count = this.#moduleRefs?.get(ref) ?? 0;
     if (count <= 1) {
-      const reader = this.#getMetadataReader();
-      for (const [binding, instance] of this.#removeModuleBindings(ref)) {
-        this.#lifecycle.runDeactivationSync(binding, instance, reader);
-      }
+      this.#deactivatePairsSync(this.#removeModuleBindings(ref));
     } else {
       this.#moduleRefs!.set(ref, count - 1);
     }
@@ -422,10 +528,7 @@ class DefaultContainer implements Container {
   async #unloadModuleAsync(ref: object): Promise<void> {
     const count = this.#moduleRefs?.get(ref) ?? 0;
     if (count <= 1) {
-      const reader = this.#getMetadataReader();
-      for (const [binding, instance] of this.#removeModuleBindings(ref)) {
-        await this.#lifecycle.runDeactivation(binding, instance, reader);
-      }
+      await this.#deactivatePairs(this.#removeModuleBindings(ref));
     } else {
       this.#moduleRefs!.set(ref, count - 1);
     }
@@ -435,112 +538,128 @@ class DefaultContainer implements Container {
     this.#assertNotDisposed();
     const entries = registry.entries();
     for (const { target, scope } of entries) {
-      const builder = this.#createBindToBuilder(target);
-      const bindingBuilder = builder.toSelf();
-      if (scope === "singleton") {
-        bindingBuilder.singleton();
-      } else if (scope === "scoped") {
-        bindingBuilder.scoped();
-      } else {
-        bindingBuilder.transient();
-      }
+      APPLY_BINDING_SCOPE[scope](this.#createBindToBuilder(target).toSelf());
     }
     return entries.length;
   }
 
-  // ── Lifecycle hooks ────────────────────────────────────────────────────────
+  // ── Lifecycle hooks ────────────────────────────────────────────────────────────────────────────────────────────────
 
-  onActivation<const Value>(token: Token<Value> | Constructor<Value>, handler: ActivationHandler<Value>): void {
+  onActivation<Value>(token: Token<Value> | Constructor<Value>, handler: ActivationHandler<Value>): void {
     this.#assertNotDisposed();
     this.#lifecycle.registerActivation(token, handler);
   }
 
-  onDeactivation<const Value>(token: Token<Value> | Constructor<Value>, handler: DeactivationHandler<Value>): void {
+  onDeactivation<Value>(token: Token<Value> | Constructor<Value>, handler: DeactivationHandler<Value>): void {
     this.#assertNotDisposed();
     this.#lifecycle.registerDeactivation(token, handler);
   }
 
-  // ── Resolution ────────────────────────────────────────────────────────────
+  // ── Resolution ─────────────────────────────────────────────────────────────────────────────────────────────────────
 
-  resolve<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
+  resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
     this.#assertNotDisposed();
     const rootStack = this.#resolver.rootStack;
-    // A resolve already holding the shared pair means this one is nested; it mints its own.
+    // A resolve already holding the shared stack means this one is nested; it mints its own.
     if (rootStack.length !== 0) {
       return options === undefined
-        ? this.#resolver.resolveFromContext(token, [], [])
-        : this.#resolver.resolve(token, options, [], []);
+        ? this.#resolver.resolveFromContext(token, [])
+        : this.#resolver.resolve(token, options, []);
     }
     if (options === undefined) {
-      return this.#resolver.resolveFromContext(token, this.#resolver.rootPath, rootStack);
+      return this.#resolver.resolveFromContext(token, rootStack);
     }
-    return this.#resolver.resolve(token, options, this.#resolver.rootPath, rootStack);
+    return this.#resolver.resolve(token, options, rootStack);
   }
 
-  resolveAsync<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
+  resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
     this.#assertNotDisposed();
     if (options === undefined) {
       return this.#resolver.resolveAsyncFromRoot(token) as Promise<Value>;
     }
-    return this.#resolver.resolveAsync(token, options, [], [], ROOT_BRANCH);
+    return this.#resolver.resolveAsync(token, options, [], ROOT_BRANCH);
   }
 
-  resolveOptional<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
+  resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
     this.#assertNotDisposed();
     const rootStack = this.#resolver.rootStack;
     return rootStack.length === 0
-      ? this.#resolver.resolveOptional(token, options, this.#resolver.rootPath, rootStack)
-      : this.#resolver.resolveOptional(token, options, [], []);
+      ? this.#resolver.resolveOptional(token, options, rootStack)
+      : this.#resolver.resolveOptional(token, options, []);
   }
 
-  resolveOptionalAsync<const Value>(
+  resolveOptionalAsync<Value>(
     token: Token<Value> | Constructor<Value>,
     options?: ResolveOptions,
   ): Promise<Value | undefined> {
     this.#assertNotDisposed();
-    return this.#resolver.resolveOptionalAsync(token, options, [], [], ROOT_BRANCH);
+    return this.#resolver.resolveOptionalAsync(token, options, [], ROOT_BRANCH);
   }
 
-  resolveAll<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
+  resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
     this.#assertNotDisposed();
     const rootStack = this.#resolver.rootStack;
     return rootStack.length === 0
-      ? this.#resolver.resolveAll(token, options, this.#resolver.rootPath, rootStack)
-      : this.#resolver.resolveAll(token, options, [], []);
+      ? this.#resolver.resolveAll(token, options, rootStack)
+      : this.#resolver.resolveAll(token, options, []);
   }
 
-  resolveAllAsync<const Value>(
-    token: Token<Value> | Constructor<Value>,
-    options?: ResolveOptions,
-  ): Promise<Array<Value>> {
+  resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>> {
     this.#assertNotDisposed();
-    return this.#resolver.resolveAllAsync(token, options, [], [], ROOT_BRANCH);
+    return this.#resolver.resolveAllAsync(token, options, [], ROOT_BRANCH);
   }
 
-  // ── Child ─────────────────────────────────────────────────────────────────
+  // ── Child ──────────────────────────────────────────────────────────────────────────────────────────────────────────
 
   createChild(): Container {
     this.#assertNotDisposed();
     return new DefaultContainer(this);
   }
 
-  // ── Dispose ───────────────────────────────────────────────────────────────
+  // ── Dispose ────────────────────────────────────────────────────────────────────────────────────────────────────────
 
-  async dispose(): Promise<void> {
-    if (this.#disposed) {
-      return;
-    }
+  dispose(): Promise<void> {
+    // One teardown, shared: a second caller awaits the same run instead of returning early while
+    // hooks from the first are still executing.
+    return (this.#disposePromise ??= this.#runDispose());
+  }
+
+  async #runDispose(): Promise<void> {
     this.#disposed = true;
+    // Refuses new materializations immediately; in-flight ones are drained just below.
+    this.#scope.markClosed();
+    await this.#scope.settleInflight();
 
-    // Deactivate all singletons in this container (own only)
     const reader = this.#getMetadataReader();
+    const errors: Array<unknown> = [];
     // Iterate a copy: a deactivation handler is user code, and the live list is what
-    // materializing or dropping a singleton mutates.
-    for (const binding of this.#scope.cachedSingletons().slice()) {
-      await this.#lifecycle.runDeactivation(binding, binding.instance, reader);
+    // materializing or dropping a singleton mutates. Reverse materialization order, so a
+    // dependent tears down before the dependencies it may still reach through.
+    const cached = this.#scope.cachedSingletons().slice();
+    for (let index = cached.length - 1; index >= 0; index -= 1) {
+      const binding = cached[index]!;
+      try {
+        await this.#lifecycle.runDeactivation(binding, binding.instance, reader);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    // A constant never reaches the singleton cache unless activation put it there, so its hook is
+    // owed from the registry instead — and only a container that has held one pays for looking.
+    if (this.#registry.hasHeldConstantBinding) {
+      for (const binding of this.#registry.allBindings()) {
+        if (binding.instance === NO_INSTANCE && this.#owesConstantDeactivation(binding)) {
+          try {
+            await this.#lifecycle.runDeactivation(binding, binding.value, reader);
+          } catch (error) {
+            errors.push(error);
+          }
+        }
+      }
     }
 
     this.#scope.clearAll();
+    throwCollected(errors, "dispose() completed, but deactivation hooks threw");
   }
 
   [Symbol.asyncDispose](): Promise<void> {
@@ -551,7 +670,7 @@ class DefaultContainer implements Container {
     throw new SyncDisposalNotSupportedError();
   }
 
-  // ── Initialization ────────────────────────────────────────────────────────
+  // ── Initialization ─────────────────────────────────────────────────────────────────────────────────────────────────
 
   async initializeAsync(): Promise<void> {
     this.#assertNotDisposed();
@@ -565,17 +684,22 @@ class DefaultContainer implements Container {
         if (binding.predicate !== undefined) {
           continue;
         }
-        // Has activation — need to resolve
-        if (binding.kind === "constant" && binding.onActivation === undefined) {
+        // A constant is already its own instance, so only an activation hook gives the warm-up
+        // something to run — and a container-level hook counts as one just as a per-binding hook does.
+        if (
+          binding.kind === "constant" &&
+          binding.onActivation === undefined &&
+          !this.#lifecycle.hasActivationHandlers(binding.token)
+        ) {
           continue;
         }
         const slotOptions = bindingSlotToResolveOptions(binding.slot);
-        await this.resolveAsync(binding.token as Token<unknown>, slotOptions);
+        await this.resolveAsync(binding.token, slotOptions);
       }
     }
   }
 
-  // ── Validate ──────────────────────────────────────────────────────────────
+  // ── Validate ───────────────────────────────────────────────────────────────────────────────────────────────────────
 
   validate(): void {
     this.#assertNotDisposed();
@@ -588,6 +712,54 @@ class DefaultContainer implements Container {
       }
       this.#validateSingletonBindingGraph(binding, reader);
     }
+
+    for (const [hookToken, phase] of this.#lifecycle.hookedTokens()) {
+      if (!this.#isBoundInChain(hookToken)) {
+        throw new UnreachableLifecycleHookError(tokenName(hookToken), phase);
+      }
+    }
+
+    this.#validateConstraintRequirements(allBindings);
+  }
+
+  /** A constraint waiting on a slot name no binding declares can never hold. */
+  #validateConstraintRequirements(allBindings: ReadonlyArray<Binding>): void {
+    let declaredSlotNames: Set<string> | undefined;
+
+    for (const binding of allBindings) {
+      const { predicate } = binding;
+      if (predicate === undefined) {
+        continue;
+      }
+      const requirement = constraintRequirementOf(predicate);
+      if (requirement === undefined) {
+        continue;
+      }
+      declaredSlotNames ??= this.#slotNamesInChain();
+      if (!declaredSlotNames.has(requirement.name)) {
+        throw new UnreachableConstraintError(tokenName(binding.token), requirement.name, requirement.helperName);
+      }
+    }
+  }
+
+  /** Every slot name declared anywhere a resolve through this container could reach. */
+  #slotNamesInChain(): Set<string> {
+    const names = this.#parent === undefined ? new Set<string>() : this.#parent.#slotNamesInChain();
+    for (const binding of this.#registry.allBindings()) {
+      if (binding.slot.name !== undefined) {
+        names.add(binding.slot.name);
+      }
+    }
+    return names;
+  }
+
+  // Ancestors count: a parent-owned binding is one this container can still resolve through.
+  #isBoundInChain(token: Token<unknown> | Constructor): boolean {
+    if (this.#registry.has(token)) {
+      return true;
+    }
+    const parent = this.#parent;
+    return parent !== undefined && parent.#isBoundInChain(token);
   }
 
   #isSingletonStaticAnalyzableBinding(binding: Binding): boolean {
@@ -599,13 +771,13 @@ class DefaultContainer implements Container {
 
   /**
    * DFS over explicit constructor / `toResolved*` dependency edges. Follows `toAlias` chains to the
-   * terminal binding for scope checks (SPEC §6.9).
+   * terminal binding for scope checks.
    *
    * @remarks A `toDynamic*` dependency is scope-checked like any other — its declared scope is what
    * makes it captive — but the DFS does not descend into the factory, whose body is opaque.
    */
   #validateSingletonBindingGraph(root: Binding, reader: MetadataReader): void {
-    const rootName = tokenName(root.token as Token<unknown>);
+    const rootName = tokenName(root.token);
 
     const dfs = (current: Binding, pathNames: Array<string>, pathBindingIds: Set<BindingIdentifier>): void => {
       if (pathBindingIds.has(current.id)) {
@@ -659,8 +831,8 @@ class DefaultContainer implements Container {
         throw new CircularDependencyError(cyclePath);
       }
       seenAliasIds.add(current.id);
-      cyclePath.push(tokenName(current.token as Token<unknown>));
-      const nextToken = current.target as Token<unknown> | Constructor;
+      cyclePath.push(tokenName(current.token));
+      const nextToken = current.target;
       const next = this.#resolver.peekBindingForValidate(nextToken, options);
       if (next === undefined) {
         return undefined;
@@ -682,7 +854,7 @@ class DefaultContainer implements Container {
   /** What a binding declares up front — a class's params, a factory's descriptors, else nothing. */
   #staticDependencies(binding: Binding, reader: MetadataReader): ReadonlyArray<DependencySlot> {
     if (binding.kind === "class") {
-      return reader.getConstructorMetadata(binding.target as Constructor)?.params ?? [];
+      return reader.getConstructorMetadata(binding.target)?.params ?? [];
     }
     if (binding.kind === "resolved" || binding.kind === "resolved-async") {
       return binding.deps;
@@ -705,7 +877,7 @@ class DefaultContainer implements Container {
       for (const candidate of this.#peekDependencyCandidates(dep, depOptions)) {
         const terminal = this.#followAliasChainToTerminal(candidate, depOptions);
         if (terminal !== undefined) {
-          edges.push({ terminal, depTokenName: tokenName(terminal.token as Token<unknown>) });
+          edges.push({ terminal, depTokenName: tokenName(terminal.token) });
         }
       }
     }
@@ -713,7 +885,7 @@ class DefaultContainer implements Container {
     return edges;
   }
 
-  // ── Introspection ─────────────────────────────────────────────────────────
+  // ── Introspection ──────────────────────────────────────────────────────────────────────────────────────────────────
 
   has(token: Token<unknown> | Constructor, options?: ResolveOptions): boolean {
     this.#assertNotDisposed();
@@ -725,7 +897,7 @@ class DefaultContainer implements Container {
     return this.#getInspector().hasOwn(token, options);
   }
 
-  lookupBindings<const Value>(token: Token<Value> | Constructor<Value>): ReadonlyArray<BindingSnapshot> {
+  lookupBindings<Value>(token: Token<Value> | Constructor<Value>): ReadonlyArray<BindingSnapshot> {
     this.#assertNotDisposed();
     return this.#getInspector().lookupBindings(token);
   }
@@ -745,7 +917,7 @@ class DefaultContainer implements Container {
     );
   }
 
-  // ── Internal ──────────────────────────────────────────────────────────────
+  // ── Internal ───────────────────────────────────────────────────────────────────────────────────────────────────────
 
   #assertNotDisposed(): void {
     if (this.#disposed) {
@@ -754,16 +926,29 @@ class DefaultContainer implements Container {
   }
 }
 
-// ── Container static ──────────────────────────────────────────────────────────
+/** Reports collected hook failures once teardown finished: the one error as itself, several aggregated. */
+function throwCollected(errors: ReadonlyArray<unknown>, message: string): void {
+  if (errors.length === 0) {
+    return;
+  }
+  if (errors.length === 1) {
+    throw errors[0];
+  }
+  throw new AggregateError(errors, message);
+}
+
+// ── Container static ─────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
  */
-export const Container: ContainerStatic & { create(): Container } = {
-  create(): Container {
-    return new DefaultContainer();
+export const Container: ContainerStatic = {
+  create(options?: ContainerOptions): Container {
+    return new DefaultContainer(undefined, options);
   },
 
+  // Variadic modules leave no room for an options argument. A container that needs both is
+  // `Container.create(options)` followed by `load(...)`, which is what these two do anyway.
   fromModules(...modules: Array<SyncModule>): Container {
     const container = new DefaultContainer();
     container.load(...modules);