@codefast/di 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @codefast/di
 
+## 0.13.0
+
+### Minor Changes
+
+- [#1022](https://github.com/codefastlabs/codefast/pull/1022) **Breaking:** `Container` no longer declares `[Symbol.dispose]`, and `SyncDisposalNotSupportedError` is removed. A
+  deactivation hook may be async, so a container disposes through `await using` or `dispose()` only, and a synchronous
+  `using` on one is now a compile error instead of a `SyncDisposalNotSupportedError` at runtime. Replace `using` with
+  `await using`, and drop any `instanceof SyncDisposalNotSupportedError` check.
+
+- [#1024](https://github.com/codefastlabs/codefast/pull/1024) **Breaking:** `@postConstruct()` and `@preDestroy()` now reject a private (`#name`) method, as they already rejected a
+  static or symbol-keyed one. The lifecycle manager calls a hook by name on the instance, so a private hook passed
+  `validate()` and then failed at resolve with an `InvalidMetadataError` that blamed the metadata reader, or at
+  `dispose()` for `@preDestroy()`. Decorating one now throws the new `PrivateLifecycleMethodError` when the class is
+  defined. The decorators' types also accept only a public, instance, string-named method, and `@inject` only an instance
+  accessor, so TypeScript reports all of these at the decoration site (TS1240, TS1241). To run private code from a hook,
+  call it from a public one.
+
+- [#1022](https://github.com/codefastlabs/codefast/pull/1022) `TokenNotBoundError` and `NoMatchingBindingError` now carry `path`: the token names from the outermost request down to
+  the one that missed, alias hops included. A miss below the token asked for ends its message with that path —
+  `Path: UserService → UserRepository → Database → app:Logger` — so a deep graph says which consumer needed the binding; a
+  miss on the token asked for keeps its message as it was. Every lane reports the same path: sync and async, generated
+  plans, factory bodies, and `explain()` for an ancestor that selects nothing.
+
+- [#1022](https://github.com/codefastlabs/codefast/pull/1022) **Breaking:** a `scoped` instance is now deactivated with the child container that cached it. Disposing that child runs
+  the binding's `onDeactivation`, the container-level `onDeactivation` hooks of the container that owns the binding, and
+  `@preDestroy()` for every scoped instance it cached, latest first and before its own singletons; unbinding a scoped
+  binding on the child that cached it deactivates that instance too. `.scoped()` now offers `onDeactivation`, and
+  `Module.fromBindings` accepts `onDeactivation` with `scope: "scoped"`, so per-request resources — a transaction, a
+  connection — can be released where they are declared. `validate()` no longer reports a deactivation hook on a
+  scoped-only token as unreachable. Code that relied on a scoped instance never being torn down, or that closed one by
+  hand after `dispose()`, should drop the manual close.
+
+- [#1022](https://github.com/codefastlabs/codefast/pull/1022) **Breaking:** `validate()` now throws the error `resolve()` would for a singleton graph that cannot resolve — a required
+  dependency nothing binds (`TokenNotBoundError`), a slot nothing matches (`NoMatchingBindingError`), or a cycle
+  (`CircularDependencyError`) — with the path from that singleton down to the problem. A parent-owned singleton reached
+  from a child is now read from the parent's chain, as `resolve` reads it. It still leaves alone what it cannot decide: a
+  transient or scoped consumer, whose dependencies a child container may bind, and a request only a `when()` candidate
+  matches. A container that passed `validate()` while holding such a graph now fails it; bind the missing dependency, or
+  mark it `optional()` when it may be absent.
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # @codefast/di
 
-Lightweight, type-safe dependency injection for TypeScript applications, built on TC39 Stage 3 decorators with no
+Type-safe dependency injection for TypeScript applications, with zero dependencies, built on standard decorators with no
 `reflect-metadata` and no `experimentalDecorators`.
 
 [![npm version](https://img.shields.io/npm/v/@codefast/di)](https://www.npmjs.com/package/@codefast/di)
@@ -20,12 +20,12 @@ its keep as the dependency graph grows.
 
 - **Typed tokens.** `Token<Value>` flows through every `bind → resolve` path, so `resolve()` returns exactly the type
   you registered.
-- **Native Stage 3 decorators.** `@injectable`, `inject`, `optional`, `injectAll`, `@postConstruct`, and `@preDestroy`
-  declare dependencies explicitly — no runtime reflection.
+- **Standard decorators.** `@injectable`, `inject`, `optional`, `injectAll`, `@postConstruct`, and `@preDestroy` declare
+  dependencies explicitly — no runtime reflection.
 - **Fluent bindings.** Constants, classes, sync and async factories, aliases, named/tagged/predicate constraints, and
   lifecycle hooks compose in one invariant chain order.
 - **Scopes with validation.** Choose `singleton`, `scoped`, or `transient`, and call `validate()` to catch captive
-  dependencies before the first request.
+  dependencies, missing bindings and cycles before the first request.
 - **Modules and introspection.** Bundle bindings into reusable modules, and inspect a container or render its dependency
   graph as DOT, Mermaid, Cytoscape, or React Flow.
 
@@ -36,7 +36,7 @@ pnpm add @codefast/di
 ```
 
 `@codefast/di` runs on Node.js 24 or later and in Chrome and Edge 136, Firefox 136, or Safari 18.4 or later
-([support policy](../../SUPPORT.md#browsers)). It requires TypeScript 7 or later, with native Stage 3 decorators. Leave
+([support policy](../../SUPPORT.md#browsers)). It requires TypeScript 7 or later, with standard decorators. Leave
 `experimentalDecorators` off — it's off by default. Its declarations use explicit resource management, which no numbered
 `lib` declares yet, so your program needs those types: `@types/node` 24 or later loads them, and any other program adds
 `ESNext.Disposable` to `lib` once its runtime ships explicit resource management. A browser program that targets Safari,
@@ -44,6 +44,67 @@ which has not shipped it, keeps `skipLibCheck` on and calls `dispose()` instead
 published on 0.x and versioned on its own track: breaking changes ship as minor versions, so pin the minor version when
 you need stability.
 
+### Toolchain
+
+No JavaScript engine runs decorators natively yet — the TC39 proposal went back to Stage 2.7 in May 2026 — so a
+decorated class always passes through a transform that lowers it. What that takes depends on the toolchain:
+
+| Toolchain                 | What it needs                                                                                               |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| tsx                       | Nothing: it lowers standard decorators for the Node it runs on.                                             |
+| esbuild                   | A `target` below `esnext`, such as `es2024` or `node24`: at its default, `esnext`, decorators pass through. |
+| Vite 8, and Vitest on it  | The Babel decorators plugin: their Oxc transform lowers only `experimentalDecorators`.                      |
+| SWC 1.15.21 or later      | `jsc.parser.decorators: true` and `jsc.transform.decoratorVersion: "2023-11"`.                              |
+| `tsc`, then Node directly | A `target` below `ESNext`, and `Symbol.metadata` installed before any decorated class is defined.           |
+
+For Vite and Vitest, add `@babel/core`, `@babel/plugin-proposal-decorators` and `@rolldown/plugin-babel` as dev
+dependencies, then the decorators preset to the config — `vitest.config.ts` takes the same one:
+
+```ts
+// vite.config.ts
+import babel, { defineRolldownBabelPreset } from "@rolldown/plugin-babel";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    babel({
+      presets: [
+        defineRolldownBabelPreset({
+          preset: () => ({ plugins: [["@babel/plugin-proposal-decorators", { version: "2023-11" }]] }),
+          // Every decorator holds an `@`, so Babel skips only files that cannot hold one.
+          rolldown: { filter: { code: "@" } },
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+The filter is what keeps Babel off the files without decorators; the plugin applies it only when every preset carries
+one and `plugins` is left empty. Keep it the plain `"@"`: a narrower pattern can miss a legal position such as
+`export @injectable() class`, and a missed file ships its decorators raw. Beside other presets, list this one last,
+since Babel runs presets last to first.
+
+> **Warning.** Without the plugin the decorators pass through untouched, and nothing flags it at build time:
+> `vite build` succeeds, then the bundle throws `SyntaxError: Invalid or unexpected token` as it loads — the same error
+> Vitest reports for a test file that imports a decorated class.
+
+`tsc` leaves decorators in its output at `target: "ESNext"`. At any lower target it lowers them, but on a runtime
+without `Symbol.metadata` it hands them no metadata object, which every decorator here reports as
+`MissingDecoratorMetadataError`. Install the symbol in a module the entry point imports first:
+
+```ts
+(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");
+```
+
+Not every toolchain lowers them yet. Node's own type stripping rejects decorators; Next.js cannot select the `2023-11`
+version (vercel/next.js#96328 adds it); and Bun 1.4.2 and earlier inject the wrong values, silently, into a module that
+holds two decorated classes (oven-sh/bun#28316).
+
+[The specification → tsconfig setup](./spec/decorators.md#tsconfig-setup) covers the compiler options. And
+[decorators](#decorators) are optional: an app wired through `toResolved`, `toDynamic` and `Module.fromBindings` needs
+none of this.
+
 ## Quick start
 
 ```ts
@@ -98,9 +159,9 @@ A class constructor works as a key too: `container.bind(UserService).toSelf()`,
 
 ## Bindings
 
-A binding describes how the container produces a value for a token. You declare it as a chain, in one fixed order: a
-strategy (the `to*` step, which produces the value), then optional constraints, a scope, and lifecycle hooks. Only
-`container.bind(key).to*(…)` is required; everything after it is optional.
+A binding describes how the container produces a value for a token. You declare it as a chain, in one fixed order:
+optional [constraints](#constraints), then a strategy (the `to*` step, which produces the value and registers the
+binding), then an optional scope and lifecycle hooks. Only `container.bind(key).to*(…)` is required.
 
 | Strategy                          | Produces                                                          |
 | --------------------------------- | ----------------------------------------------------------------- |
@@ -134,7 +195,7 @@ no scope produces a new instance every time.
 | Scope          | Lifetime                                                                                 |
 | -------------- | ---------------------------------------------------------------------------------------- |
 | `.singleton()` | One instance for the container that owns the binding; children resolve the same instance |
-| `.scoped()`    | One instance per child container — resolving from a container with no child scope throws |
+| `.scoped()`    | One instance per child container, deactivated with it — resolving outside a child throws |
 | `.transient()` | A new instance on every resolution — the default                                         |
 
 ```ts
@@ -148,9 +209,10 @@ container.bind(RequestContextToken).toSelf().scoped();
 ### Lifecycle hooks
 
 A lifecycle hook runs your code as an instance is created or torn down. `.onActivation(fn)` runs right after an instance
-is created, and may replace it; `.onDeactivation(fn)` runs when the owning container is disposed or the binding is
-unbound. Both are also available container-wide, through `container.onActivation(token, fn)` and
-`container.onDeactivation(token, fn)`:
+is created, and may replace it; `.onDeactivation(fn)` runs as the instance's lifetime ends — a singleton's when its
+container is disposed or the binding is unbound, a scoped instance's when the child container that cached it is
+disposed. A transient instance has no deactivation. Both hooks are also available container-wide, through
+`container.onActivation(token, fn)` and `container.onDeactivation(token, fn)`:
 
 ```ts
 container
@@ -212,6 +274,19 @@ container.resolve(StorageToken, { tag: Provider.of("s3") }); // → S3Storage
 `injectAll` alike. Chain `.whenTagged(...)` once per criterion a slot carries, and request several at once with
 `{ tags: [...] }`.
 
+**One binding per slot; a collection with `many()`.** Binding a token again in a slot it already fills replaces the
+earlier binding — `bind` is last-wins per slot, so `resolveAll` then finds only the newer one. To register several
+implementations for `resolveAll` and `injectAll` to gather, mark each one a collection member with `.many()`:
+
+```ts
+container.bind(PluginToken).many().to(AuditPlugin);
+container.bind(PluginToken).many().to(MetricsPlugin);
+
+container.resolveAll(PluginToken); // → an AuditPlugin and a MetricsPlugin, in registration order
+```
+
+A member keeps the default slot and is never what a single `resolve` selects.
+
 **Predicate constraints — graph-aware selection.** When a slot isn't enough — when you need to choose based on _who_ is
 resolving — pass a predicate to `.when(ctx => boolean)`. It runs at resolve time, after slot matching. These ready-made
 predicates ship from the root entry:
@@ -252,7 +327,7 @@ class UserRepository {
   constructor(
     private readonly db: Database,
     private readonly cache: Cache | undefined,
-    private readonly plugins: Array<Plugin>,
+    private readonly plugins: ReadonlyArray<Plugin>,
     private readonly audit: Logger,
   ) {}
 
@@ -349,17 +424,21 @@ parent's singletons, while each `scoped` binding gets a fresh instance per child
 
 A captive dependency is a long-lived binding that holds a shorter-lived one — a `singleton` that depends on a `scoped`
 or `transient` binding — which silently freezes that dependency for the singleton's whole life. `validate()` fails fast
-on captive dependencies, and on constraints no request can satisfy, before the first resolve.
+on captive dependencies, and on constraints no request can satisfy, before the first resolve. It also throws the error
+`resolve()` would for a singleton graph that cannot resolve: a required dependency nothing binds, a slot nothing
+matches, or a cycle.
 
 ```ts
-container.validate(); // throws ScopeViolationError on the first violation
+container.validate(); // throws on the first violation — ScopeViolationError, TokenNotBoundError, …
 ```
 
+A transient or scoped consumer's dependencies are left to `resolve()`, because a child container may still bind them.
+
 ### Disposal
 
 `Container` implements `AsyncDisposable`, so `await using` runs every deactivation hook automatically as the block
-exits. Synchronous `using` isn't supported — `onDeactivation` may be async — and `Symbol.dispose` throws
-`SyncDisposalNotSupportedError`.
+exits, and disposing a child deactivates the scoped instances it cached. Synchronous `using` is a compile error: a
+deactivation hook may be async, so the container implements `Symbol.asyncDispose` only.
 
 ### Introspection
 
@@ -475,6 +554,9 @@ Every error extends `DiError` and carries a stable `code`, so you can branch on
 | `MissingContainerContextError` | `MISSING_CONTAINER_CONTEXT` | An `@inject` accessor initializes with no container open                   |
 | `DisposedContainerError`       | `DISPOSED_CONTAINER`        | A disposed container is used                                               |
 
+A miss below the token you asked for names its path: `TokenNotBoundError` and `NoMatchingBindingError` carry `path`, and
+the message ends with it — `Path: UserService → UserRepository → app:Logger`.
+
 The full taxonomy — including `MissingMetadataError`, `InvalidMetadataError`, `RebindUnboundTokenError`,
 `AsyncModuleLoadError`, `InvalidBindingDeclarationError`, and the rest — is exported from the root entry and from
 `@codefast/di/errors`.
@@ -495,8 +577,9 @@ introspection under `introspection/*`: `@codefast/di/introspection/inspector`, `
 ## Benchmarks
 
 A first-party benchmark suite lives in the monorepo, at [`benchmarks/di`](../../benchmarks/di). It runs the same
-workloads through `@codefast/di`, InversifyJS, Awilix, and tsyringe, and its `RESULTS.md` ledger records the numbers
-alongside the method that produced them. Run it yourself rather than taking any figure on faith.
+workloads through `@codefast/di`, InversifyJS, Awilix, tsyringe, Brandi, ditox, and injection-js, and its `RESULTS.md`
+ledger records the numbers alongside the method that produced them. Run it yourself rather than taking any figure on
+faith.
 
 ## Documentation
 

package/dist/container/container.d.ts

@@ -36,7 +36,6 @@ export interface Container {
     createChild(): Container;
     dispose(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
-    [Symbol.dispose](): never;
     initializeAsync(): Promise<void>;
     validate(): void;
     has<Names extends string = string>(token: Token<unknown, Names> | Constructor, options?: NoInfer<ResolveOptions<Names>>): boolean;

package/dist/container/container.js

@@ -6,14 +6,14 @@ import { isSyncModule, MODULE_SETUP } from "#core/module";
 import { BindingRegistry } from "#core/registry";
 import { advanceDisposeEpoch, disposeEpochRef } from "#core/state-epoch";
 import { tokenName } from "#core/token";
-import { AsyncModuleLoadError, CircularDependencyError, DisposedContainerError, InternalError, RebindUnboundTokenError, ScopeViolationError, SyncDisposalNotSupportedError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors";
+import { AsyncModuleLoadError, CircularDependencyError, DisposedContainerError, InternalError, RebindUnboundTokenError, ScopeViolationError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors";
 import { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#injection/dependency-slot";
 import { buildDependencyGraph } from "#introspection/dependency-graph";
 import { RESOLUTION_DIAGNOSTICS } from "#introspection/diagnostics";
 import { explainRequest } from "#introspection/explanation";
 import { Inspector } from "#introspection/inspector";
 import { LifecycleManager } from "#lifecycle/hooks";
-import { ScopeManager } from "#lifecycle/scopes";
+import { SCOPED_MISS, ScopeManager } from "#lifecycle/scopes";
 import { MetadataReaderToken } from "#metadata/reader-token";
 import { defaultMetadataReader } from "#metadata/symbol-reader";
 import { verifyingMetadataReader } from "#metadata/verifying-reader";
@@ -223,7 +223,10 @@ class DefaultContainer {
         else if (this.#owesConstantDeactivation(binding)) {
             (pairs ??= []).push(binding, binding.value);
         }
-        this.#scope.deleteScoped(binding.scopedCacheKey);
+        const scopedInstance = this.#scope.takeScoped(binding.scopedCacheKey);
+        if (scopedInstance !== SCOPED_MISS) {
+            (pairs ??= []).push(binding, scopedInstance);
+        }
         return pairs;
     }
     /**
@@ -637,6 +640,11 @@ class DefaultContainer {
         await this.#scope.settleInflight();
         const reader = this.#getMetadataReader();
         const errors = [];
+        // A scoped instance may hold this container's singletons and never the reverse, so it goes first, latest first.
+        const scopedTeardown = this.#scope.deactivateScoped(errors);
+        if (scopedTeardown !== undefined) {
+            await scopedTeardown;
+        }
         // Iterate a copy: a deactivation handler is user code, and the live list is what
         // materializing or dropping a singleton mutates. Reverse materialization order, so a
         // dependent tears down before the dependencies it may still reach through.
@@ -684,9 +692,6 @@ class DefaultContainer {
     [Symbol.asyncDispose]() {
         return this.dispose();
     }
-    [Symbol.dispose]() {
-        throw new SyncDisposalNotSupportedError();
-    }
     // ── Initialization ─────────────────────────────────────────────────────────────────────────────────────────────────
     async initializeAsync() {
         this.#assertNotDisposed();
@@ -729,8 +734,8 @@ class DefaultContainer {
             if (!this.#isBoundInChain(hookToken)) {
                 throw new UnreachableLifecycleHookError(tokenName(hookToken), phase);
             }
-            // A deactivation only ever runs for a singleton or constant, so a hook on a token whose every
-            // binding is scoped or transient can never fire — the builder blocks it, `container.onDeactivation` cannot.
+            // A deactivation never runs for a transient, so a hook on a token whose every binding is transient
+            // can never fire — the builder blocks it, `container.onDeactivation` cannot.
             if (phase === "onDeactivation" && !this.#hasDeactivatableBindingInChain(hookToken)) {
                 throw new UnreachableLifecycleHookError(tokenName(hookToken), phase, "no-deactivatable-binding");
             }
@@ -776,10 +781,10 @@ class DefaultContainer {
         const parent = this.#parent;
         return parent !== undefined && parent.#isBoundInChain(token);
     }
-    // Whether the token has a binding a deactivation hook can run for — a singleton or a constant.
+    // Whether the token has a binding a deactivation hook can run for — anything but a transient.
     #hasDeactivatableBindingInChain(token) {
         for (const binding of this.#registry.getAll(token)) {
-            if (effectiveBindingScope(binding) === "singleton") {
+            if (effectiveBindingScope(binding) !== "transient") {
                 return true;
             }
         }
@@ -793,22 +798,21 @@ class DefaultContainer {
         return binding.kind === "class" || binding.kind === "resolved" || binding.kind === "resolved-async";
     }
     /**
-     * DFS over explicit constructor / `toResolved*` dependency edges. Follows `toAlias` chains to the
-     * terminal binding for scope checks.
+     * DFS over explicit constructor / `toResolved*` dependency edges, following `toAlias` chains to the terminal binding.
      *
-     * @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.
+     * @remarks Every binding reached is a singleton resolved from its owner's chain, so a required miss or a repeat
+     * on one path fails however the graph is entered; a `toDynamic*` edge is scope-checked, its factory not descended.
      */
     #validateSingletonBindingGraph(root, reader) {
         const rootName = tokenName(root.token);
-        const dfs = (current, pathNames, pathBindingIds) => {
+        const dfs = (current, view, pathNames, pathBindingIds) => {
             if (pathBindingIds.has(current.identifier)) {
-                return;
+                throw new CircularDependencyError(pathNames);
             }
             const extendedPathIds = new Set(pathBindingIds);
             extendedPathIds.add(current.identifier);
-            for (const edge of this.#collectStaticDependencyEdges(current, reader)) {
-                const { terminal, depTokenName } = edge;
+            for (const edge of this.#collectStaticDependencyEdges(current, view, reader, pathNames)) {
+                const { terminal, owner, depTokenName } = edge;
                 const depScope = this.#validationScopeFromTerminal(terminal);
                 if (depScope !== "singleton") {
                     throw new ScopeViolationError({
@@ -820,11 +824,11 @@ class DefaultContainer {
                     });
                 }
                 if (terminal.kind === "class" || terminal.kind === "resolved" || terminal.kind === "resolved-async") {
-                    dfs(terminal, [...pathNames, depTokenName], extendedPathIds);
+                    dfs(terminal, owner, [...pathNames, depTokenName], extendedPathIds);
                 }
             }
         };
-        dfs(root, [rootName], new Set());
+        dfs(root, this.#resolver, [rootName], new Set());
     }
     /**
      * The scope this edge is judged against.
@@ -839,32 +843,35 @@ class DefaultContainer {
         }
         return terminal.scope;
     }
-    #followAliasChainToTerminal(binding, options) {
+    /** Where an alias chain ends as `resolve` walks it from `view`: its terminal binding, or the names up to a miss. */
+    #followAliasChainToTerminal(entry, view, options) {
         const cyclePath = [];
         const seenAliasIds = new Set();
-        let current = binding;
-        while (current !== undefined && current.kind === "alias") {
-            if (seenAliasIds.has(current.identifier)) {
+        let current = entry;
+        while (current.binding.kind === "alias") {
+            const alias = current.binding;
+            if (seenAliasIds.has(alias.identifier)) {
                 throw new CircularDependencyError(cyclePath);
             }
-            seenAliasIds.add(current.identifier);
-            cyclePath.push(tokenName(current.token));
-            const nextToken = current.target;
-            const next = this.#resolver.peekBindingForValidate(nextToken, options);
+            seenAliasIds.add(alias.identifier);
+            cyclePath.push(tokenName(alias.token));
+            const next = view.peekBindingForValidate(alias.target, options);
             if (next === undefined) {
-                return undefined;
+                return { found: false, missingToken: alias.target, hopNames: cyclePath };
             }
-            current = next.binding;
+            current = next;
         }
-        return current;
+        return { found: true, terminal: current.binding, owner: current.owner };
     }
-    /** What one dependency could resolve to: every candidate for `injectAll`, else at most one. */
-    #peekDependencyCandidates(dep, options) {
+    /** What one dependency could resolve to from `view`: every candidate for `injectAll`, else at most one. */
+    #peekDependencyCandidates(dep, view, options) {
         if (dep.multi) {
-            return this.#resolver.peekCandidateBindingsForValidate(dep.token, options);
+            return view
+                .peekCandidateBindingsForValidate(dep.token, options)
+                .map((binding) => ({ binding, owner: view.ownerForValidate(binding) }));
         }
-        const found = this.#resolver.peekBindingForValidate(dep.token, options);
-        return found === undefined ? [] : [found.binding];
+        const found = view.peekBindingForValidate(dep.token, options);
+        return found === undefined ? [] : [found];
     }
     /** What a binding declares up front — a class's params, a factory's descriptors, else nothing. */
     #staticDependencies(binding, reader) {
@@ -876,15 +883,39 @@ class DefaultContainer {
         }
         return [];
     }
-    #collectStaticDependencyEdges(binding, reader) {
+    /**
+     * The bindings a singleton's declared dependencies resolve to, throwing the error `resolve` would for a required one
+     * nothing selects.
+     */
+    #collectStaticDependencyEdges(binding, view, reader, pathNames) {
         const edges = [];
         for (const dep of this.#staticDependencies(binding, reader)) {
             // An optional dependency that is absent peeks no candidate; one that is bound is captured like any other.
             const depOptions = injectionSlotToResolveOptions(dep);
-            for (const candidate of this.#peekDependencyCandidates(dep, depOptions)) {
-                const terminal = this.#followAliasChainToTerminal(candidate, depOptions);
-                if (terminal !== undefined) {
-                    edges.push({ terminal, depTokenName: tokenName(terminal.token) });
+            // A collection may be empty and an optional dependency absent, so only a required one can miss.
+            const required = !dep.multi && !dep.optional;
+            const candidates = this.#peekDependencyCandidates(dep, view, depOptions);
+            if (required && candidates.length === 0) {
+                const miss = view.missForValidate(dep.token, depOptions, [...pathNames, tokenName(dep.token)]);
+                if (miss !== undefined) {
+                    throw miss;
+                }
+            }
+            for (const candidate of candidates) {
+                const end = this.#followAliasChainToTerminal(candidate, view, depOptions);
+                if (end.found) {
+                    edges.push({ terminal: end.terminal, owner: end.owner, depTokenName: tokenName(end.terminal.token) });
+                    continue;
+                }
+                if (required) {
+                    const miss = view.missForValidate(end.missingToken, depOptions, [
+                        ...pathNames,
+                        ...end.hopNames,
+                        tokenName(end.missingToken),
+                    ]);
+                    if (miss !== undefined) {
+                        throw miss;
+                    }
                 }
             }
         }

package/dist/core/binding-builders.d.ts

@@ -96,11 +96,14 @@ export interface TransientBindingBuilder<Value> {
     id(): BindingIdentifier;
 }
 /**
- * The fluent chain after `scoped()`, sharing the `transient()` surface.
+ * The fluent chain after `scoped()`, where both lifecycle hooks stay available: a child deactivates what it cached.
  *
  * @since 0.3.16-canary.0
  */
-export interface ScopedBindingBuilder<Value> extends TransientBindingBuilder<Value> {
+export interface ScopedBindingBuilder<Value> {
+    onActivation(fn: ActivationHandler<Value>): this;
+    onDeactivation(fn: DeactivationHandler<Value>): this;
+    id(): BindingIdentifier;
 }
 /**
  * The fluent chain a constant enters once a lifecycle hook is added.

package/dist/core/binding-declaration.d.ts

@@ -23,11 +23,11 @@ type SlotDefinition<Names extends string> = ({
 } & Never<"whenNamed" | "whenTagged">);
 /** How long an instance lives, and the hooks that lifetime allows. */
 type LifetimeDefinition<Value> = {
-    readonly scope: "singleton";
+    readonly scope: "singleton" | "scoped";
     readonly onActivation?: ActivationHandler<Value> | undefined;
     readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 } | ({
-    readonly scope?: "transient" | "scoped" | undefined;
+    readonly scope?: "transient" | undefined;
     readonly onActivation?: ActivationHandler<Value> | undefined;
 } & Never<"onDeactivation">);
 type BuiltDefinition<Value, Deps extends ReadonlyArray<InjectableDependency>> = ({

package/dist/core/binding-declaration.js

@@ -157,8 +157,8 @@ export function binding(key, definition) {
     if (kind === "alias" && (onActivation !== undefined || onDeactivation !== undefined)) {
         throw new InvalidBindingDeclarationError(name, "`toAlias` takes no lifecycle hook");
     }
-    if (onDeactivation !== undefined && kind !== "constant" && scope !== "singleton") {
-        throw new InvalidBindingDeclarationError(name, '`onDeactivation` needs `scope: "singleton"`');
+    if (onDeactivation !== undefined && kind !== "constant" && scope === "transient") {
+        throw new InvalidBindingDeclarationError(name, '`onDeactivation` needs `scope: "singleton"` or `scope: "scoped"`');
     }
     if (definition.many !== undefined && definition.many !== true) {
         throw new InvalidBindingDeclarationError(name, "`many` takes `true`");

package/dist/decorators/inject.d.ts

@@ -2,7 +2,9 @@
 import type { Token } from "#core/token";
 import type { Constructor } from "#core/types";
 import type { InjectionDescriptor, InjectOptions } from "#injection/descriptor";
-type ClassAccessorDecorator<This, Value> = (target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>) => ClassAccessorDecoratorResult<This, Value> | void;
+type ClassAccessorDecorator<This, Value> = (target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value> & {
+    readonly static: false;
+}) => ClassAccessorDecoratorResult<This, Value> | void;
 /**
  * Creates a dual-role value: an injection descriptor that also works as a class accessor decorator.
  *

package/dist/decorators/lifecycle.d.ts

@@ -1,14 +1,20 @@
-type MethodDecorator = (target: unknown, context: ClassMethodDecoratorContext) => void;
+/** The only method a hook can be: the lifecycle reader calls it on the instance by its string name. */
+type LifecycleMethodContext = ClassMethodDecoratorContext & {
+    readonly static: false;
+    readonly private: false;
+    readonly name: string;
+};
+type LifecycleMethodDecorator = (target: unknown, context: LifecycleMethodContext) => void;
 /**
  * Marks an instance method to run after the container constructs and wires the instance.
  *
  * @since 0.3.16-canary.0
  */
-export declare function postConstruct(): MethodDecorator;
+export declare function postConstruct(): LifecycleMethodDecorator;
 /**
  * Marks an instance method to run when the instance's container or scope is disposed.
  *
  * @since 0.3.16-canary.0
  */
-export declare function preDestroy(): MethodDecorator;
+export declare function preDestroy(): LifecycleMethodDecorator;
 export {};

package/dist/decorators/lifecycle.js

@@ -1,12 +1,16 @@
 import { decoratorMetadataOf } from "#decorators/metadata-record";
-import { StaticMemberDecoratorError, SymbolKeyedLifecycleError } from "#errors";
+import { PrivateLifecycleMethodError, StaticMemberDecoratorError, SymbolKeyedLifecycleError } from "#errors";
 import { LIFECYCLE_KEY } from "#metadata/keys";
 /** Records the decorated method under one lifecycle phase; both decorators differ only in that phase. */
 function recordLifecycleMethod(phase) {
+    // Typed wide on purpose: the checks below are what an untyped caller meets instead of the compiler.
     return function (target, context) {
         if (context.static) {
             throw new StaticMemberDecoratorError(phase, String(context.name));
         }
+        if (context.private) {
+            throw new PrivateLifecycleMethodError(phase, String(context.name));
+        }
         // The lifecycle reader keys methods by their string name, so a symbol-keyed method can never be
         // found again — fail here, where the declaration is, rather than at resolve.
         if (typeof context.name === "symbol") {