@codefast/di 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,156 @@
 # @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
+
+- [#1010](https://github.com/codefastlabs/codefast/pull/1010) **Breaking:** `resolveAsync`, `resolveOptionalAsync` and `resolveAllAsync` on a disposed container — or on a child of
+  one — now return a promise rejected with `DisposedContainerError` instead of throwing it, and `resolveAllAsync(token)`
+  likewise rejects when a `when()` predicate throws or an alias cycle is followed, so every async method reports its
+  failure through the promise it returns. Code that awaits these calls, or chains `.catch()`, behaves as before or better;
+  only a caller that wrapped the call itself in `try`/`catch` without awaiting it no longer sees the error there, and
+  should await it instead.
+
+- [#995](https://github.com/codefastlabs/codefast/pull/995) Add `container.explain(token, options)`, which answers why a request selects the binding it does without instantiating
+  anything. It reads the container chain the way `resolve` does and decides by the same rules, so its answer is the
+  engine's own. It reports each registry it read with every candidate and its verdict (`eligible`, `slot-mismatch`,
+  `predicate-refused`, `collection-member`), the rule that decided (`sole-candidate`, `sole-predicate`, `most-criteria`,
+  `default-alias`, `ambiguous`), the binding the request ends on after every alias, and an `outcome` naming the error
+  `resolve` would throw when it ends on none. `when()` predicates run as they would in `resolve`, and `options.ancestors`
+  explains a request made from inside other resolutions, so a predicate that reads the parent sees the one it would.
+
+- [#999](https://github.com/codefastlabs/codefast/pull/999) **Breaking:** a binding's slot is declared before its strategy —
+  `bind(Logger).whenNamed("file").to(FileLogger).singleton()`. `when()`, `whenNamed()`, `whenTagged()`, `whenDefault()`
+  and `many()` now come before `to*()` and are refused after it with `ChainAlreadyRegisteredError`, so a binding registers
+  once, in its final slot, and no later step moves it, displaces something else or brings back what it displaced. Scope
+  and lifecycle hooks stay after `to*()`. To migrate, move each chain's slot steps in front of its `to*()` call.
+
+  The registry no longer parks the bindings a re-slot displaced or restores them, so a bind with a name or a tag costs a
+  quarter to two fifths less. `BindingBuilder`, `ConstantBindingBuilder` and `AliasBindingBuilder` lose their `Names` type
+  parameter, since the slot is settled before they exist.
+
+- [#1005](https://github.com/codefastlabs/codefast/pull/1005) **Breaking for deep subpath imports only** — the root entry `@codefast/di` is unchanged. `src/` now follows three rules,
+  and the published subpaths follow `src/` with no exception: a directory names a family of two or more modules and a lone
+  module sits flat at its layer; a directory carries the topic and a file its role, so no file repeats its directory's
+  name; and the exports map is the source tree, so the `strip` that kept the introspection modules at flat specifiers is
+  gone.
+
+  Moves: the `MetadataReader` verification leaves `resolution/cache/class-introspector` for `metadata/verify` — it was the
+  one value import pointing up from `metadata/` into `resolution/`; the `RESOLUTION_DIAGNOSTICS` channel leaves `errors/`
+  for `introspection/diagnostics`; the fluent chain's contract leaves `core/binding` for `core/binding-builders`, and the
+  class implementing it is `container/binding-chain`; `effectiveBindingScope` folds into `core/binding`.
+
+  Renamed specifiers: `./errors/errors` → `./errors`; `./errors/diagnostics` → `./introspection/diagnostics`;
+  `./ambient/active-container` → `./ambient-container`; `./container/binding-builders` → `./container/binding-chain`;
+  `./core/binding-scope` → gone (`effectiveBindingScope` is in `./core/binding`); `./injection/resolve-options` →
+  `./injection/dependency-slot`;
+  `./metadata/{metadata-keys,metadata-types,metadata-reader-token,symbol-metadata-reader,verifying-metadata-reader}` →
+  `./metadata/{keys,types,reader-token,symbol-reader,verifying-reader}`; `./lifecycle/{lifecycle-manager,scope-manager}` →
+  `./lifecycle/{hooks,scopes}`; `./decorators/{lifecycle-decorators,decorator-metadata}` →
+  `./decorators/{lifecycle,metadata-record}`; `./resolution/path/resolution-path` → `./resolution/path`;
+  `./resolution/plan/{instantiation-plan,plan-codegen}` → `./resolution/plan/{compiler,codegen}`;
+  `./resolution/select/binding-select` → `./resolution/select/candidates`; `./resolution/cache/binding-lookup-cache` →
+  `./resolution/cache/lookup`; `./{inspector,explanation,dependency-graph,graph-adapters/*}` →
+  `./introspection/{inspector,explanation,dependency-graph,graph-adapters/*}`. New: `./core/binding-builders`,
+  `./metadata/verify`.
+
+  `@codefast/di-testing` follows the one specifier it imports, `metadata/verifying-reader`.
+
+### Patch Changes
+
+- [#996](https://github.com/codefastlabs/codefast/pull/996) A request with criteria that matches no slot is fast again when the container holds no alias: `resolveOptional()` of a
+  missing tagged slot no longer probes for a default-slot alias to forward to in a registry that never held one.
+
+- [#1009](https://github.com/codefastlabs/codefast/pull/1009) `resolveAsync` no longer rejects with `AsyncResolutionError` when a later sibling reads a singleton or scoped binding
+  synchronously — a `toDynamic` factory's `ctx.resolve`, an `@inject` accessor, a top-level `resolve` — while the async
+  lane is still materialising it from an earlier sibling. A level of the async lane now yields only where a dependency or
+  hook really awaits, so an instance built without yielding is cached before the next sibling starts, and only a
+  materialisation that is genuinely pending is published in flight.
+
+- [#994](https://github.com/codefastlabs/codefast/pull/994) A scope refinement costs less at bind time. `singleton()`, `transient()` and `scoped()` now do nothing when the scope
+  does not change, and release only what exists when it does, so `bind(T).to(X).singleton()` straight after registration
+  no longer calls into the scope manager.
+
+- [#997](https://github.com/codefastlabs/codefast/pull/997) Every read on a child container is cheaper. The child's check that no ancestor was disposed is now one epoch compare
+  that V8 inlines into each entry point, the walk up the chain runs only after some container was disposed, and a new
+  child starts confirmed live, so a per-request child skips the walk on its first read.
+
+- [#994](https://github.com/codefastlabs/codefast/pull/994) Resolving a class binding for the first time is cheaper. The metadata cache now keeps one record per class, which a cold
+  resolve looks up once instead of reading a separate map for each fact, and a class with no constructor parameters is
+  built without allocating an empty argument list. This mostly speeds up containers that bind and resolve many class
+  singletons at startup.
+
+- [#1001](https://github.com/codefastlabs/codefast/pull/1001) The first resolve of a class binding is cheaper. The class's parameter list, and the check that a subclass is not
+  dropping its base's declared dependencies, are settled once per class instead of once per instantiation, and the class
+  asked about last is answered without a map lookup, so a hundred singletons of one class bind and materialize about a
+  fifth faster.
+
+- [#994](https://github.com/codefastlabs/codefast/pull/994) A root-level `resolveAll()` read in a loop over the same token, as an event bus does for every event, is cheaper: the
+  lookup cache keeps the last collection in front of its map, so a repeat read skips the map lookup.
+
+- [#997](https://github.com/codefastlabs/codefast/pull/997) A container that reads a collection once no longer builds a value list it never reads again. A root-level `resolveAll`
+  keeps its stable value list from the second read on, the way an instantiation plan compiles on repeat, so a fresh
+  container per request pays only for the members it resolves.
+
+- [#996](https://github.com/codefastlabs/codefast/pull/996) A resolve that carries options on a root container gets back much of the speed 0.11.0 took from it. The check that
+  refuses a disposed chain grew in that release enough that V8 stopped inlining the lookup behind that entry point; a live
+  root now pays two field reads for it, and only a child reads the dispose epoch.
+
+- [#998](https://github.com/codefastlabs/codefast/pull/998) A root container's `resolve(token, options)` no longer pays for the check a child makes that no ancestor was disposed.
+  Each container is created with the `resolve` of its role, so the root's never carries the child's path and the rule that
+  a disposed ancestor refuses its descendants stays as it was.
+
+- [#994](https://github.com/codefastlabs/codefast/pull/994) A scoped binding whose scope changes stops handing children the instance they cached before the change. A binding
+  registered on a parent, resolved from a child, then refined `scoped()` → `transient()` → `scoped()` gave that child its
+  old scoped instance back, because only the registering container's cache was cleared. Every container now files a scoped
+  instance under a key the binding replaces when it leaves `scoped`, so the cached instance is never found again.
+
+- [#1003](https://github.com/codefastlabs/codefast/pull/1003) A teardown reads a class's `@preDestroy` methods once for a run of bindings of that class, instead of once per binding,
+  and names the token only when a hook fails.
+
+- [#1002](https://github.com/codefastlabs/codefast/pull/1002) A rebind that owes no teardown allocates nothing for the binding it displaces, and a collection read skips its scan for
+  dangling aliases in a chain that never held one.
+
 ## 0.11.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
@@ -169,8 +231,8 @@ constraints is its slot — think of a slot as a labelled variant of the token.
 `{ name }`:
 
 ```ts
-container.bind(LoggerToken).toConstantValue(consoleLogger).whenNamed("console");
-container.bind(LoggerToken).toConstantValue(fileLogger).whenNamed("file");
+container.bind(LoggerToken).whenNamed("console").toConstantValue(consoleLogger);
+container.bind(LoggerToken).whenNamed("file").toConstantValue(fileLogger);
 
 container.resolve(LoggerToken, { name: "file" }); // → fileLogger
 ```
@@ -180,7 +242,7 @@ Declare the names on the token and they become checked, completable literals at
 ```ts
 const LoggerToken = token<Logger, "console" | "file">("app:Logger");
 
-container.bind(LoggerToken).toConstantValue(fileLogger).whenNamed("file");
+container.bind(LoggerToken).whenNamed("file").toConstantValue(fileLogger);
 container.resolve(LoggerToken, { name: "file" }); // { name: "fiel" } is a compile error
 ```
 
@@ -193,7 +255,7 @@ import { tag } from "@codefast/di";
 
 const Provider = tag<"s3" | "gcs">("app:provider");
 
-container.bind(StorageToken).to(S3Storage).whenTagged(Provider.of("s3"));
+container.bind(StorageToken).whenTagged(Provider.of("s3")).to(S3Storage);
 container.resolve(StorageToken, { tag: Provider.of("s3") }); // → S3Storage
 ```
 
@@ -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:
@@ -230,7 +305,7 @@ predicates ship from the root entry:
 | `whenAnyAncestorTaggedAll(criteria)` | some ancestor's slot carries all criteria in the array  |
 
 For the exact matching and most-specific-wins rules, see
-[`SPEC.md` → Slots and last-wins](./SPEC.md#slots-and-last-wins--the-exact-definition).
+[the specification → Slots and last-wins](./spec/binding.md#slots-and-last-wins--the-exact-definition).
 
 ## Decorators
 
@@ -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
 
@@ -367,6 +446,18 @@ exits. Synchronous `using` isn't supported — `onDeactivation` may be async —
 token's bindings; and `container.generateDependencyGraph()` returns a JSON graph. Adapters render that graph for common
 viewers: `toDotGraph`, `toMermaidGraph`, `toCytoscapeGraph`, and `toReactFlowGraph`.
 
+`container.explain(token, options)` answers why a request selects the binding it does, without instantiating anything:
+every candidate each registry offered and what selection made of it, the rule that decided, and the binding it ends on.
+It evaluates `when()` predicates the way `resolve` does, and `options.ancestors` explains a request made from inside
+other resolutions, so a predicate that reads the parent sees the one it would:
+
+```ts
+const explanation = container.explain(Logger, { ancestors: [Settlement] });
+
+explanation.selected?.id; // the binding `resolve` would answer with
+explanation.steps[0]?.rule; // "sole-predicate": the only candidate with a `when()` beat the rest
+```
+
 ## Modules
 
 A module is a reusable, stateless bundle of related bindings. Group them once, then load them into any container.
@@ -463,31 +554,37 @@ 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/errors`.
+`@codefast/di/errors`.
 
 ## Subpath exports
 
 Prefer the root entry: it re-exports the whole public API. Reach for a subpath only to trim a bundle, or to pull in
 something the root doesn't surface.
 
-Every module is also published as a subpath that mirrors the source layout: the model under `@codefast/di/core/*`
-(`core/token`, `core/tag`, `core/module`, …), errors under `errors/*`, the runtime under `container/*`, `injection/*`,
-`lifecycle/*`, and `resolution/*` (for example `@codefast/di/resolution/select/constraints`), and decorators and
-metadata under `decorators/*` and `metadata/*`. Introspection ships at flat specifiers: `@codefast/di/inspector`,
-`@codefast/di/dependency-graph`, and `@codefast/di/graph-adapters/{dot,mermaid,cytoscape,reactflow}`.
+Every module is also published as a subpath that is its source path, with no exception: the model under
+`@codefast/di/core/*` (`core/token`, `core/tag`, `core/module`, …), the error taxonomy at `@codefast/di/errors`, the
+runtime under `container/*`, `injection/*`, `lifecycle/*`, and `resolution/*` (for example
+`@codefast/di/resolution/select/constraints`), decorators and metadata under `decorators/*` and `metadata/*`, and
+introspection under `introspection/*`: `@codefast/di/introspection/inspector`, `@codefast/di/introspection/explanation`,
+`@codefast/di/introspection/dependency-graph`, and
+`@codefast/di/introspection/graph-adapters/{dot,mermaid,cytoscape,reactflow}`.
 
 ## 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
 
 - [Rendered docs on codefastlabs.com](https://codefastlabs.com/docs/di)
-- [`SPEC.md`](./SPEC.md) — the behavioural contract: public API, semantics, and errors.
+- [`spec/`](./spec/README.md) — the behavioural contract: public API, semantics, and errors, one document per API area.
 - [`ARCHITECTURE.md`](./ARCHITECTURE.md) — the internal shape and the invariants the hot paths depend on.
 - [`DECISIONS.md`](./DECISIONS.md) — why the API looks like this, and what it did not take from InversifyJS v8.
 - [`examples/`](./examples/README.md) — runnable examples from basic tokens to a multi-file Ports & Adapters app.

package/dist/container/{binding-builders.d.ts → binding-chain.d.ts}

@@ -3,17 +3,18 @@
  *
  * @remarks One object plays every role: each builder step, the record the registry stores, and the
  * binding the resolver reads. The binding fields are declared first and in a fixed order, so every
- * binding in the process shares one hidden class; the return type of each step is what pins the
- * chain's order, so no runtime check has to.
+ * binding in the process shares one hidden class; the return type of each step pins the chain's
+ * order, slot before strategy, so the binding registers once and is never re-slotted.
  */
-import type { AliasBindingBuilder, Binding, BindingBuilder, BindingSlot, BindToBuilder, ConstantBindingBuilder, ScopedBindingBuilder, SingletonBindingBuilder, SingletonLifecycleBuilder, TransientBindingBuilder } from "#core/binding";
+import type { Binding, BindingSlot } from "#core/binding";
+import type { AliasBindingBuilder, BindingBuilder, BindToBuilder, ConstantBindingBuilder, ScopedBindingBuilder, SingletonBindingBuilder, SingletonLifecycleBuilder, TransientBindingBuilder } from "#core/binding-builders";
 import type { DeclaredBinding } from "#core/binding-declaration";
 import type { BindingRegistry } from "#core/registry";
 import type { BindingTag } from "#core/tag";
 import type { Token } from "#core/token";
 import type { ActivationHandler, BindingConstraint, BindingIdentifier, BindingKind, BindingScope, Constructor, DeactivationHandler, ResolutionContext, ResolutionFrame } from "#core/types";
 import type { InjectableDependency, InjectionDescriptor, ResolvedDependencyValue } from "#injection/descriptor";
-import type { ScopeManager } from "#lifecycle/scope-manager";
+import type { ScopeManager } from "#lifecycle/scopes";
 /**
  * Where a chain registers, and on whose behalf.
  *
@@ -26,24 +27,22 @@ export interface BindingRegistration {
     readonly registry: BindingRegistry;
     readonly scope: ScopeManager;
     readonly moduleBindingIds: Array<BindingIdentifier> | undefined;
-    /** Runs for a binding this registration displaces, instead of parking it for a later restore. */
+    /** Runs for a binding this registration displaces, deactivating it on the spot. */
     readonly deactivateDisplaced?: ((binding: Binding) => void) | undefined;
-    /** Notes a parked displaced binding so the container can still tear it down if no restore reclaims it. */
+    /** Notes a displaced binding so the container can still tear it down, when nothing deactivates it on the spot. */
     readonly onDisplaced?: ((binding: Binding) => void) | undefined;
-    /** Undoes {@link BindingRegistration.onDisplaced} when a refinement restores the binding to the registry. */
-    readonly onRestored?: ((binding: Binding) => void) | undefined;
 }
 /**
  * The one builder behind `bind()` and every `to*()` return type — and the binding it registers.
  *
  * @remarks The binding fields come first, in the order every binding shares, and the chain's own
- * bookkeeping follows as private fields; `to*()` fills the fields in place and hands this object to
- * the registry, so a plain bind is one allocation. Refinements write the registered object: a scope
- * or hook in place, a slot or predicate through the registry so its indexes follow.
+ * bookkeeping follows as a private field. The slot steps write the fields before anything registers;
+ * `to*()` fills the strategy in place and hands this object to the registry once, so a bind is one
+ * allocation and one add. A scope or hook afterwards writes the registered object in place.
  *
  * @since 0.5.0-canary.8
  */
-export declare class BindingChain<Value, Names extends string = string> implements AliasBindingBuilder<Names>, BindingBuilder<Value, Names>, BindToBuilder<Value, Names>, ConstantBindingBuilder<Value, Names>, ScopedBindingBuilder<Value>, SingletonBindingBuilder<Value>, SingletonLifecycleBuilder<Value>, TransientBindingBuilder<Value> {
+export declare class BindingChain<Value, Names extends string = string> implements AliasBindingBuilder, BindingBuilder<Value>, BindToBuilder<Value, Names>, ConstantBindingBuilder<Value>, ScopedBindingBuilder<Value>, SingletonBindingBuilder<Value>, SingletonLifecycleBuilder<Value>, TransientBindingBuilder<Value> {
     #private;
     kind: BindingKind;
     readonly identifier: BindingIdentifier;
@@ -51,8 +50,8 @@ export declare class BindingChain<Value, Names extends string = string> implemen
     frame: ResolutionFrame | undefined;
     rootContext: ResolutionContext | undefined;
     activationStamp: number;
-    registrationOrder: number;
     instance: unknown;
+    scopedCacheKey: BindingIdentifier;
     readonly token: Token<Value, Names> | Constructor<Value>;
     slot: BindingSlot;
     predicate: BindingConstraint | undefined;
@@ -65,26 +64,20 @@ export declare class BindingChain<Value, Names extends string = string> implemen
     activationHook: ActivationHandler<Value> | undefined;
     deactivationHook: DeactivationHandler<Value> | undefined;
     constructor(token: Token<Value, Names> | Constructor<Value>, registration: BindingRegistration);
-    /**
-     * Registers a declared module's bindings in list order, each a chain of its own that no step
-     * will ever refine.
-     *
-     * @remarks A displaced binding is handled as `to*()` handles it, never parked: nothing refines the
-     * chain, so nothing could restore it.
-     */
+    /** Registers a declared module's bindings in list order, each a chain of its own, handled as `to*()` handles one. */
     static registerDeclared(declarations: ReadonlyArray<DeclaredBinding>, registration: BindingRegistration): void;
-    to(type: Constructor<Value>): BindingBuilder<Value, Names>;
-    toSelf(): BindingBuilder<Value, Names>;
-    toConstantValue(value: Value): ConstantBindingBuilder<Value, Names>;
-    toDynamic(factory: (ctx: ResolutionContext) => Value): BindingBuilder<Value, Names>;
-    toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): BindingBuilder<Value, Names>;
+    to(type: Constructor<Value>): BindingBuilder<Value>;
+    toSelf(): BindingBuilder<Value>;
+    toConstantValue(value: Value): ConstantBindingBuilder<Value>;
+    toDynamic(factory: (ctx: ResolutionContext) => Value): BindingBuilder<Value>;
+    toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): BindingBuilder<Value>;
     toResolved<const Deps extends ReadonlyArray<InjectableDependency>>(factory: (...args: {
         [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]>;
-    }) => Value, deps: Deps): BindingBuilder<Value, Names>;
+    }) => Value, deps: Deps): BindingBuilder<Value>;
     toResolvedAsync<const Deps extends ReadonlyArray<InjectableDependency>>(factory: (...args: {
         [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]>;
-    }) => Promise<Value>, deps: Deps): BindingBuilder<Value, Names>;
-    toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder<Names>;
+    }) => Promise<Value>, deps: Deps): BindingBuilder<Value>;
+    toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder;
     when(predicate: BindingConstraint): this;
     whenNamed(name: Names): this;
     whenTagged(criterion: BindingTag): this;