@codefast/di 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,381 @@
 # @codefast/di
 
+## 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
+
+- [#933](https://github.com/codefastlabs/codefast/pull/933) A default-slot alias is a transparent pointer: a request whose criteria no slot of the alias's own token matches is
+  forwarded, criteria and all, to its target — `resolve(AbstractLogger, { name: "file" })` reaches `Logger`'s `"file"`
+  binding. An exact slot on the alias's token still wins, the nearest container still answers first, and `has` agrees;
+  `resolveAll` keeps filtering by the alias token's own slots.
+
+- [#896](https://github.com/codefastlabs/codefast/pull/896) Retire the async cascade lane: every `resolveAsync` now runs on the branch lane, so a factory's context answers from its
+  own ancestors before and after an `await`. A `whenParentIs` binding requested after an `await` is now selected as the
+  sync lane selects it, `ctx.graph.resolutionPath` names the level's own ancestors, and a cycle formed entirely from
+  post-`await` edges is named from the true root. A transient class or factory root with a statically visible graph is
+  answered by the compiled async plan. `AsyncCascadeContext` and `resolveAsyncFromCascade` are removed from
+  `resolution/context`; `ResolutionDiagnostics.builtSubsystems` reports `resolver.asyncRootLevel` once the async lane has
+  been entered.
+
+- [#937](https://github.com/codefastlabs/codefast/pull/937) Add declared modules: `Module.fromBindings(name, [binding(key, definition), …])` (also `SyncModule.fromBindings`) builds
+  a `SyncModule` from a list, each `binding()` stating one binding with the fluent chain's own vocabulary — `to`,
+  `toSelf: true`, `toConstantValue`, `toDynamic`, `toDynamicAsync`, `toResolved` / `toResolvedAsync` with `deps`,
+  `toAlias`, then `whenNamed`, `whenTagged` (one criterion or several), `when`, `many: true`, `scope` and the lifecycle
+  hooks. A definition is typed exactly as the chain is — the key alone decides the value type and the slot names, and the
+  compiler rejects a second strategy, a scope on a constant or an alias, a hook on an alias, `onDeactivation` off a
+  singleton, and a slot on a collection member. `binding()` checks the same rules at runtime for plain JavaScript and
+  throws the new `InvalidBindingDeclarationError` (`INVALID_BINDING_DECLARATION`, with `tokenName` and `reason`), or
+  `ManyBindingSlotError` / `SelfBindingRequiresClassError` as the chain does.
+
+  A declared module loads, unloads, ref-counts and imports exactly as the equivalent `Module.create` setup would, and
+  registers each binding already in its final shape, so a binding with a slot, a scope or a hook skips the chain steps a
+  fluent setup pays on every load. Nothing a resolve reads changes. `SyncModule`'s `MODULE_SETUP` member now holds either
+  the setup callback or the declarations.
+
+- [#925](https://github.com/codefastlabs/codefast/pull/925) A constant that a plain last-wins `bind()` displaces now still runs its `onDeactivation` hook at `dispose()`. A
+  displaced constant left the registry — so the dispose sweep, which walks the registry, never reached it — and, carrying
+  no cached instance, it was absent from the singleton cache too, falling between the two. The container now records a
+  displaced constant that still owes a deactivation and drains it at dispose; a refinement that restores the binding (a
+  `when*()` that moves the winner off the slot) takes it back out of that set, so nothing deactivates twice. The
+  park-and-restore behaviour of `bind()` is otherwise unchanged.
+
+- [#931](https://github.com/codefastlabs/codefast/pull/931) Disposing a container now reaches its descendants. A child whose parent (or any ancestor) has been disposed is itself
+  disposed: `isDisposed` reads `true`, and every `resolve`, `has` and mutation is refused with `DisposedContainerError`,
+  including the child's own bindings — previously a child kept building transients and constants from a torn-down chain,
+  and `child.has` and `child.resolve` disagreed. The guard keeps the resolve path cheap: a root still reads only its own
+  `#disposed` field, and a child adds one call-free compare of a dedicated dispose-epoch cell against the epoch at which
+  its chain was last confirmed live — the ancestor walk runs only after some container in the process is disposed. The
+  dispose epoch is separate from the state epoch, so a per-request child's dispose does not invalidate the chain-version
+  memo that keeps deep resolves cheap, and `createChild()` is untouched. `resolveAsync` refuses a disposed chain with a
+  synchronous throw at the entry, matching how it already guarded a self-disposed container, and `dispose()` stays ungated
+  so an `await using` child of a disposed ancestor still tears down cleanly.
+
+- [#933](https://github.com/codefastlabs/codefast/pull/933) `generateDependencyGraph({ includeParent: true })` follows resolution's own walk up the chain: every ancestor's bindings
+  join the graph, a single dependency connects to the nearest container holding a binding its slot matches — a child
+  binding the request cannot select no longer hides the parent's — and an `injectAll` fans out across the whole chain.
+  `buildDependencyGraph` takes the ancestor registries, nearest first, in place of the parent registry.
+
+- [#921](https://github.com/codefastlabs/codefast/pull/921) A subclass that inherits declared constructor dependencies but declares none of its own — the natural
+  `class Derived extends Base {}` with an implicit constructor — is now rejected with `MissingMetadataError` instead of
+  being built with `undefined` arguments. Constructor metadata is opt-in per class, so an implicit constructor previously
+  slipped through the `target.length === 0` check and produced a silently-broken instance. The error names the base and
+  how many dependencies it declares. A subclass whose own `@injectable([])` declares zero deps is unaffected — it is built
+  with zero arguments, as declared.
+
+- [#933](https://github.com/codefastlabs/codefast/pull/933) Decorators report a runtime without `Symbol.metadata` as `MissingDecoratorMetadataError` at the declaration, naming the
+  decorator and the fix (`(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata")` in a module
+  imported first), instead of failing with a bare `TypeError` on the first metadata write. TypeScript compiles
+  `context.metadata` to `undefined` on such a runtime; the library does not install the symbol itself, since the package
+  declares no side effects.
+
+- [#926](https://github.com/codefastlabs/codefast/pull/926) Module `unload` is now symmetric with `import`, and `unbindAll` resets module bookkeeping. An `import` inside a module's
+  setup incremented the imported module's ref-count but nothing ever decremented it, so `unload(A)` left a module `A`
+  imported behind bound forever — the container now records each module's imports and, when a module's own ref-count
+  reaches 0, releases the imports it took, unbinding an imported module only when its ref-count reaches 0. And
+  `unbindAll()` / `unbindAllAsync()` now clear the module ref-count, binding-id and import tables after deactivation, so a
+  module loaded before `unbindAll` can be `load()`ed again instead of being silently skipped as already-loaded.
+
+- [#933](https://github.com/codefastlabs/codefast/pull/933) A sync `rebind()` whose old binding owes an async deactivation now fails exactly like a sync `unbind()` whatever shape
+  the token has: `rebind()` itself throws `AsyncDeactivationError`, the old bindings are removed, and nothing is
+  committed. A lone default binding used to let `rebind()` pass and then throw from `.to*()` after the replacement was
+  already registered.
+
+- [#929](https://github.com/codefastlabs/codefast/pull/929) `runWithContainer` is now typed as synchronous-only. The ambient container lives in a module-level variable restored in
+  a `finally`, so it lasts only the callback's synchronous run — it does not survive an `await`. A callback returning a
+  `Promise` was silently accepted and lost the context; its return type is now
+  `Result extends Promise<unknown> ? never : Result`, so an async callback resolves to `never`.
+  `MissingContainerContextError` now says the context does not survive an `await`, and the TSDoc, README and SPEC state
+  the sync-only constraint. The engine internals are unchanged — they only ever ran synchronous callbacks.
+
+- [#894](https://github.com/codefastlabs/codefast/pull/894) Four size thresholds are gone, each replaced by the algorithm it approximated: alias chains fold exactly to any length
+  (`ALIAS_HOP_LIMIT` is removed from `resolution/cache/binding-lookup-cache`); a generated plan is one statement per node
+  and inlines to any depth; every synchronous lane checks a cycle by the binding's in-flight flag at any depth
+  (`RESOLUTION_SET_THRESHOLD` and `enterResolutionPath` are removed from `resolution/path/resolution-path`); a
+  multi-criterion request is selected by one scan at any binding count. `PLAN_CODEGEN_THRESHOLD` is 1024, the measured
+  break-even of generating a plan against running its closure.
+
+- [#933](https://github.com/codefastlabs/codefast/pull/933) `UnreachableLifecycleHookError` carries a `reason` — `"unbound"` or `"no-deactivatable-binding"` — and an
+  `onDeactivation` hook on a token whose every binding is transient or scoped is reported as that, rather than as a token
+  nothing is bound to.
+
+- [#933](https://github.com/codefastlabs/codefast/pull/933) `validate()` checks an `optional()` dependency whenever it is bound, so a singleton capturing a bound transient or
+  scoped dependency through `optional()` is a `ScopeViolationError`; an optional dependency that is not bound still
+  imposes nothing.
+
+- [#976](https://github.com/codefastlabs/codefast/pull/976) `engines.node` is now `>=24.0.0`, up from `>=22.12.0`, and Node 22 is no longer supported. Node 24.0.0 is the first
+  release with explicit resource management built in (`using`, `await using`, `DisposableStack`, `AsyncDisposableStack`,
+  `SuppressedError`) and all of ES2025, so the packages use both as the platform ships them instead of shimming them for
+  an older line, and the CI matrix runs the unit suite on 24.0.0 itself. Move to Node 24, or stay on the current minor
+  while a deployment still runs Node 22.
+
+### Patch Changes
+
+- [#977](https://github.com/codefastlabs/codefast/pull/977) The README states the browser floor: Chrome and Edge 136, Firefox 136, and Safari 18.4 or later, the first releases that
+  ship every ES2025 builtin. `@codefast/di`'s README also says what a browser program without explicit resource management
+  does: it keeps `skipLibCheck` on and calls `dispose()` instead of `await using`.
+
+- [#922](https://github.com/codefastlabs/codefast/pull/922) A lifecycle hook that returns a rejecting `Promise` when reached from a synchronous lane no longer crashes the process.
+  `runActivationSync` and `runDeactivationSync` call each hook before they can tell it is async, so on discovering a
+  returned `Promise` they now adopt its rejection (a no-op `.catch`) before throwing `AsyncActivationError` /
+  `AsyncDeactivationError` — a rejecting `@postConstruct`, `onActivation`, `onDeactivation` or `@preDestroy` can no longer
+  become an unhandled rejection that ends the process. The hook has still run; retry on `resolveAsync` / `unbindAsync` to
+  await it properly.
+
+- [#896](https://github.com/codefastlabs/codefast/pull/896) An async level with several dependencies, and a `resolveAllAsync` collection, report the first failing dependency in
+  declaration order — the order the sync lanes report — instead of whichever rejection happened to settle first. Every
+  dependency still starts before anything is reported. A node with one dependency awaits it directly, with no fan-out to
+  settle.
+
+- [#924](https://github.com/codefastlabs/codefast/pull/924) `child.has(token)` no longer throws when a parent container is disposed but the child is not. `has` recursed through the
+  parent's **public** `has`, which asserts the container is live, so a live child that could still `resolve` a
+  parent-owned token threw `DisposedContainerError` from `has` alone — breaking the `if (c.has(token)) c.resolve(token)`
+  guard on a healthy container. It now recurses through an internal `#hasInChain` that reads the parent's registry
+  directly, keeping the disposed-guard on the public entry point of the container being called.
+
+- [#894](https://github.com/codefastlabs/codefast/pull/894) The cold path allocates only what it uses: a container builds its lookup memo, class introspector, context pools and
+  lone map on first use; a root's plan is compiled on the request that repeats it, so a container that resolves a root
+  once never compiles; a binding's activation need is stamped on the binding instead of memoized in a per-resolver map
+  (`ResolutionDiagnostics.builtSubsystems` no longer lists `resolver.activationNeedMemo`); teardown clears instances
+  without splicing the singleton list or pairing each binding; a rebind of a lone token is one registration whose
+  displaced binding is deactivated on the spot; a fresh registration is one probe and one write; a chain's own `.many()`
+  re-slots without probing the registry; each error class names itself with a literal.
+
+- [#933](https://github.com/codefastlabs/codefast/pull/933) A reader passed through `ContainerOptions.metadataReader` now outranks a `MetadataReaderToken` binding for that
+  container's children too, at every depth, as it already did for the container itself; a token binding still reaches the
+  children of a container given no reader.
+
+- [#920](https://github.com/codefastlabs/codefast/pull/920) `resolveOptional`, `resolveOptionalAsync`, `resolveAll` and `resolveAllAsync` no longer throw when they reach an alias
+  whose chain ends at a token nothing matches. An alias is a transparent pointer, so a dangling chain is the same miss the
+  target itself would be: the optional lanes return `undefined`, and a dangling alias member is skipped from a collection
+  rather than failing the whole fan-out. A required `resolve` / `resolveAsync` still throws, and an alias **cycle** still
+  throws `CircularDependencyError` — a cycle has no absent reading.
+
+- [#976](https://github.com/codefastlabs/codefast/pull/976) The README states what a program needs for the declarations' disposal members: the explicit resource management types,
+  which no numbered `lib` declares before ES2027. `@types/node` 24 or later loads them, and so does `ESNext.Disposable` in
+  `lib`. Without either, TypeScript 7 fails inside `container.d.ts` with TS2550 under `skipLibCheck: false`, and at
+  `await using` with TS2318. `@codefast/di-testing` drops a `/// <reference lib="esnext.disposable" />` that TypeScript 7
+  stripped from its emitted declarations anyway, and takes the lib from its `tsconfig.json` instead.
+
+- [#933](https://github.com/codefastlabs/codefast/pull/933) A dependency slot declaring `tags: []` states no criterion, as a binding slot already did:
+  `injectionSlotToResolveOptions` answers `undefined` for it, and such a dependency no longer escapes a compiled plan.
+
+- [#933](https://github.com/codefastlabs/codefast/pull/933) A `MetadataReader` passed through `ContainerOptions` is asked about a class once for the life of the reader: its answers
+  are memoized per class, and every container handed the same reader shares one verifying wrapper. Lifecycle metadata used
+  to be read on every activation, and each root container asked again.
+
+- [#894](https://github.com/codefastlabs/codefast/pull/894) The React Flow graph export lays its nodes out on a square grid derived from the node count rather than a fixed five
+  columns.
+
+- [#934](https://github.com/codefastlabs/codefast/pull/934) `MissingMetadataError` for a subclass that inherits declared constructor dependencies no longer advises giving it an
+  explicit constructor, which is rejected the same way. It points at `@injectable([...deps])` — `@injectable([])` for a
+  class that takes none — or a `toDynamic()`/`toResolved()` binding.
+
+- [#894](https://github.com/codefastlabs/codefast/pull/894) Every resolution lane now answers a graph identically. A per-request child that misses a token its parent's bindings all
+  declined reports `NoMatchingBindingError` as the parent does, not `TokenNotBoundError`; a sibling on the async
+  interpreted lane is selected against its own path rather than the earlier sibling's frame; a dynamic factory that
+  resolves its own token from its synchronous prefix is reported as a cycle before it runs a second time.
+
+- [#905](https://github.com/codefastlabs/codefast/pull/905) The chain-versioned lookup memo answers a repeated token from a method small enough for its hot callers to inline: the
+  hit is the whole of `defaultEntry`, and everything that fills the memo is the miss. An alias resolve, a parent-owned
+  resolve from a child and every other lookup that reaches the memo pays one inlined compare where it paid a call.
+
+- [#938](https://github.com/codefastlabs/codefast/pull/938) A constant with an `onDeactivation` hook that a bind inside a module load displaces now runs that hook at `dispose()`,
+  as it already did when a plain `container.bind()` displaced it. A module's chains registered without the container's
+  displacement bookkeeping, so the displaced constant left the registry untracked and nothing ever tore it down; this held
+  for `Module.create` setups and declared modules (`Module.fromBindings`) alike. Unloading the displacing module still
+  does not restore the displaced binding — its deactivation stays owed to `dispose()`.
+
+- [#918](https://github.com/codefastlabs/codefast/pull/918) A `{ name, tag }` request now selects the same binding as its `{ tags: [slotName.of(n), tag] }` spelling, closing two
+  selection bugs. A name that has been interned nowhere in the process no longer makes the request a miss: the request's
+  criteria can still be a superset of a slot's, so an index miss falls through to the scan and the parent walk instead of
+  returning early — the answer no longer depends on whether unrelated code has ever called `whenNamed` with that string.
+  And the name-plus-tag fast lane now declines to full selection whenever the token carries any `when()` predicate
+  candidate, so the more-specific rule's predicate step is honoured on this lane as on every other.
+
+- [#896](https://github.com/codefastlabs/codefast/pull/896) Every binding predicate now reads one `ConstraintContext` shape: the shared root context, the context a selection builds
+  over a live path, an async level's prefix and the inspector's probe are all `DefaultConstraintContext`, exported from
+  `resolution/context`. A predicate's call site stays monomorphic, and the per-selection object literal with its eager
+  `ancestors` slice is gone — `ancestors` is now sliced on first read, as `ctx.graph` already did.
+
+- [#916](https://github.com/codefastlabs/codefast/pull/916) `LEARNING.md` is removed, and with it the Learning page the docs site rendered for this package. What a shape is and
+  what it guarantees stays in `ARCHITECTURE.md`, the behavioural contract in `SPEC.md`, and usage in `README.md`, whose
+  document list no longer points at the removed file.
+
+- [#933](https://github.com/codefastlabs/codefast/pull/933) `resolveAll` returns a token's bindings in registration order however a chain refines its own binding. Binding a default
+  and then a named, tagged, member or predicate binding used to list the later one first, because the refinement re-added
+  what it had displaced behind it; each binding now keeps the place its first registration gave it.
+
+- [#902](https://github.com/codefastlabs/codefast/pull/902) A transient factory root resolved with `resolveAsync()` is handed one resolution context per binding, built on the first
+  resolve and reused by every later one — its path is its own frame alone and the request carries no options, so the
+  context is a function of the binding. The root allocated an array and a context per resolve; it allocates nothing now,
+  and a concurrent root reads the same, correct, path after an `await`.
+
+- [#919](https://github.com/codefastlabs/codefast/pull/919) A `NoMatchingBindingError`'s "Available slots" diagnostic no longer throws when a bound slot carries a tag value that
+  cannot be stringified — a bigint, a null-prototype object, or one whose `toString` throws. `bindingSlotToString` (and
+  the dependency-graph edge label) now render such a value as `<unprintable>` through a shared `stringifyTagValue` guard,
+  so the real `NoMatchingBindingError` surfaces instead of a masking `TypeError`, matching the guard the request-side
+  diagnostic already had.
+
+- [#932](https://github.com/codefastlabs/codefast/pull/932) `SPEC.md` carries the behavioural contract and nothing else. The source-tree listing, the copied export barrel, the
+  build configuration and the roadmap of already-shipped work are gone — a reader can now rename any file under `src/`
+  without contradicting the spec. `Public API` states the surface as a rule instead of a second copy of `index.ts`, which
+  had already drifted from it, and `Scope and requirements` states the runtime, module format and TypeScript floor a
+  consumer must bring. New `DECISIONS.md` takes the background and the whole InversifyJS v8 comparison, `README.md` takes
+  the testing patterns with the `MetadataReader` example corrected to `Container.create({ metadataReader })`, and
+  `CONTRIBUTING.md` takes the packaging and decorator-toolchain notes.
+
+  Checking the spec against the source turned up four public names it never described: `BindingSnapshot.isMany`, the
+  `DependencySlot` that both `InjectionDescriptor` and `ParamMetadata` extend, and `bindingSlotToResolveOptions`, which
+  turns a snapshot's slot back into the `ResolveOptions` that selects it. All three are specified now, and the claim that
+  `toAlias()` returns the one builder with no type parameter is corrected — it has no _value_ type parameter, but it does
+  carry the token's slot names.
+
+- [#927](https://github.com/codefastlabs/codefast/pull/927) `@postConstruct` / `@preDestroy` on a symbol-keyed method now fail at the declaration with the new
+  `SymbolKeyedLifecycleError`, instead of a misleading `InvalidMetadataError` at resolve that blamed a `MetadataReader`
+  the caller never configured. The lifecycle reader keys methods by their string name, so a symbol-keyed method could
+  never be found again; the decorator now rejects it up front, where the mistake is.
+
+- [#957](https://github.com/codefastlabs/codefast/pull/957) `MissingDecoratorMetadataError` suggests installing `Symbol.metadata` as
+  `(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata")`, which type-checks in a `.ts` file; the
+  bare `Symbol.metadata ??= …` it quoted failed with TS2540, since TypeScript declares the symbol `readonly`.
+
+- [#933](https://github.com/codefastlabs/codefast/pull/933) A rejected async `onActivation` on a transient `toDynamic` binding — per-binding or container-level — no longer surfaces
+  as an unhandled rejection: the sync resolve still throws `AsyncActivationError`, and the hook's promise is adopted as it
+  already was on every other lane.
+
+- [#965](https://github.com/codefastlabs/codefast/pull/965) The documented TypeScript floor is now 7, up from 5.9: TypeScript 7 is the one compiler that type-checks the package and
+  emits its published declarations, so it is the floor they support. `README.md`, `SPEC.md` and `DECISIONS.md` state it;
+  no code or declaration changed.
+
+- [#940](https://github.com/codefastlabs/codefast/pull/940) `unbind(id)` and `unbindAsync(id)` now tear down a binding that a later last-wins bind displaced: its cached singleton
+  is deactivated, and a displaced constant runs its `onDeactivation`, at that call instead of waiting for `dispose()`. The
+  id lookup asked only the registry, which a displaced binding had already left, so the call did nothing. The unbind also
+  invalidates what the displacing chain holds parked, so a later `when*()` refinement of that chain can no longer restore
+  the unbound binding.
+
+- [#939](https://github.com/codefastlabs/codefast/pull/939) Unloading a module now tears down a binding it registered that a later last-wins bind displaced: a displaced cached
+  singleton is deactivated, and a displaced constant runs its `onDeactivation`, at that `unload()`/`unloadAsync()` instead
+  of waiting for `dispose()`. Unload looked each of the module's bindings up in the registry, which a displaced binding
+  had already left, so it was skipped. The unload also invalidates what the displacing chain holds parked, so a later
+  `when*()` refinement of that chain can no longer restore a binding of the unloaded module.
+
+- [#923](https://github.com/codefastlabs/codefast/pull/923) `validate()` now reports a container-level `onDeactivation` hook that can never run. The builder type blocks
+  `onDeactivation` on `scoped`/`transient` bindings, but `container.onDeactivation(token, handler)` takes any token with
+  no such gate, so a hook keyed to a token whose every binding is scoped or transient used to pass validation silently.
+  `validate()` now raises `UnreachableLifecycleHookError` for it, reusing the mechanism that already catches a hook on an
+  unbound token. A token that also has a singleton or constant binding, and any `onActivation` hook, stay valid.
+
 ## 0.10.1
 
 ### Patch Changes

package/README.md

@@ -35,9 +35,14 @@ its keep as the dependency graph grows.
 pnpm add @codefast/di
 ```
 
-`@codefast/di` requires Node.js 22.12 or later and TypeScript 5.9 or later, with native Stage 3 decorators. Leave
-`experimentalDecorators` off — it's off by default. The package is 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.
+`@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
+`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,
+which has not shipped it, keeps `skipLibCheck` on and calls `dispose()` instead of `await using`. The package is
+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.
 
 ## Quick start
 
@@ -164,8 +169,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
 ```
@@ -175,7 +180,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
 ```
 
@@ -188,7 +193,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
 ```
 
@@ -225,7 +230,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
 
@@ -282,7 +287,8 @@ const byHand = runWithContainer(container, () => new Controller());
 
 An accessor resolves from the container that's constructing the instance. When something else owns the `new` — a router,
 an ORM, a test helper — open that context with `runWithContainer`. Without one, the accessor throws
-`MissingContainerContextError`. `getActiveContainer()` reads the open context.
+`MissingContainerContextError`. `getActiveContainer()` reads the open context. `runWithContainer` is **synchronous
+only**: the context does not survive an `await`, so a callback returning a `Promise` resolves to `never`.
 
 ### Auto-registration
 
@@ -361,6 +367,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.
@@ -384,6 +402,62 @@ const container = Container.fromModules(AppModule);
 `Container.fromModulesAsync` or `container.loadAsync`. Modules are ref-counted: loading one twice counts once, and
 `unload` removes its bindings only when the count reaches zero.
 
+A module with no logic of its own can be written as a list instead. Each `binding()` states one binding with the fluent
+chain's own vocabulary, is typed exactly as the chain is, and is checked where it is written:
+
+```ts
+import { binding, Module } from "@codefast/di";
+
+const InfrastructureModule = Module.fromBindings("app:Infra", [
+  binding(LoggerToken, { toConstantValue: console }),
+  binding(UserRepository, { toSelf: true, scope: "singleton" }),
+  binding(CacheToken, { toDynamic: () => new Map(), whenNamed: "session", scope: "scoped" }),
+]);
+```
+
+It loads exactly as the equivalent `Module.create` would, and never slower: each binding registers in its final shape,
+so one with a slot, a scope or a hook skips the chain steps a fluent setup pays on every load. A declared module mixes
+into a fluent one with `api.import(...)`.
+
+## Testing
+
+Give every test its own container and dispose it afterwards. A container shared across tests carries cached singletons
+from one into the next.
+
+```ts
+let container: Container;
+
+beforeEach(() => {
+  container = Container.create();
+});
+
+afterEach(async () => {
+  await container.dispose();
+});
+```
+
+To swap one binding out of a module you already loaded, bind it at a **child** container — the child has no binding of
+its own yet, and resolution prefers the child over its parent:
+
+```ts
+const testContainer = Container.fromModules(AppModule).createChild();
+testContainer.bind(DbToken).toConstantValue(fakeDatabase);
+```
+
+`rebind()` is for replacing a binding that already exists in the **same** container — it throws
+`RebindUnboundTokenError` when the token is only bound at a parent, so it is the wrong tool for the override above.
+
+To construct a class the container was never told about — plain JavaScript, generated code, a class you cannot decorate
+— supply the metadata yourself. Pass the reader to `Container.create`: a reader bound through `MetadataReaderToken` on
+the container you are about to use is read too late, because the resolver was built with the container.
+
+```ts
+const container = Container.create({ metadataReader: customReader });
+```
+
+For unit tests where every collaborator should be a mock, [`@codefast/di-testing`](../di-testing/README.md) builds the
+mocks from the class's own declared dependencies, through a real container.
+
 ## Errors
 
 Every error extends `DiError` and carries a stable `code`, so you can branch on the code rather than the message:
@@ -402,18 +476,21 @@ Every error extends `DiError` and carries a stable `code`, so you can branch on
 | `DisposedContainerError`       | `DISPOSED_CONTAINER`        | A disposed container is used                                               |
 
 The full taxonomy — including `MissingMetadataError`, `InvalidMetadataError`, `RebindUnboundTokenError`,
-`AsyncModuleLoadError`, and the rest — is exported from the root entry and from `@codefast/di/errors/errors`.
+`AsyncModuleLoadError`, `InvalidBindingDeclarationError`, and the rest — is exported from the root entry and from
+`@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
 
@@ -424,9 +501,9 @@ alongside the method that produced them. Run it yourself rather than taking any
 ## 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.
-- [`LEARNING.md`](./LEARNING.md) — a guided tour of the techniques the engine applies, pointing at the code.
+- [`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.
 - [`CONTRIBUTING.md`](./CONTRIBUTING.md) — the package workflow: build, exports mirror, tests, and the perf guard.
 - [`CHANGELOG.md`](./CHANGELOG.md) — release history.

package/dist/{ambient/active-container.d.ts → ambient-container.d.ts}

@@ -16,11 +16,16 @@ export interface AmbientResolution {
     resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
 }
 /**
- * Runs a callback with the given container installed as the ambient one and returns its result.
+ * Runs a synchronous callback with the given container installed as the ambient one and returns its result.
+ *
+ * @remarks The context lives in a module-level variable restored in a `finally`, so it lasts only the
+ * synchronous run of `fn` — it does not survive an `await`. A callback returning a `Promise` is a
+ * mistake the return type flags: it resolves to `never`, and the ambient context would already be torn
+ * down by the time the promise settled.
  *
  * @since 0.3.16-canary.0
  */
-export declare function runWithContainer<Result>(container: Container, fn: () => Result): Result;
+export declare function runWithContainer<Result>(container: Container, fn: () => Result): Result extends Promise<unknown> ? never : Result;
 /**
  * Engine-internal variant of {@link runWithContainer} that also installs a path-continuing resolver.
  *

package/dist/{ambient/active-container.js → ambient-container.js}

@@ -1,7 +1,12 @@
 let activeContainer;
 let activeResolution;
 /**
- * Runs a callback with the given container installed as the ambient one and returns its result.
+ * Runs a synchronous callback with the given container installed as the ambient one and returns its result.
+ *
+ * @remarks The context lives in a module-level variable restored in a `finally`, so it lasts only the
+ * synchronous run of `fn` — it does not survive an `await`. A callback returning a `Promise` is a
+ * mistake the return type flags: it resolves to `never`, and the ambient context would already be torn
+ * down by the time the promise settled.
  *
  * @since 0.3.16-canary.0
  */