@codefast/di 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,116 @@
 # @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

package/README.md

@@ -169,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
 ```
@@ -180,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
 ```
 
@@ -193,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
 ```
 
@@ -230,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
 
@@ -367,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.
@@ -465,18 +477,20 @@ Every error extends `DiError` and carries a stable `code`, so you can branch on
 
 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
 
@@ -487,7 +501,7 @@ 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.
 - [`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;

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

@@ -1,17 +1,17 @@
-import { clearBindingFrame, NO_ACTIVATION_STAMP, DEFAULT_BINDING_SLOT, generateBindingId, NO_INSTANCE, UNREGISTERED_ORDER, withSlotCriterion, } from "#core/binding";
+import { clearBindingFrame, NO_ACTIVATION_STAMP, DEFAULT_BINDING_SLOT, generateBindingId, NO_INSTANCE, withSlotCriterion, } from "#core/binding";
 import { mergingConstraintRequirements } from "#core/constraint-requirement";
 import { slotName } from "#core/tag";
 import { tokenName } from "#core/token";
-import { ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, SelfBindingRequiresClassError, } from "#errors/errors";
+import { ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, SelfBindingRequiresClassError, } from "#errors";
 import { normalizeToDescriptor } from "#injection/descriptor";
 // ── BindingChain ─────────────────────────────────────────────────────────────────────────────────────────────────────
 /**
  * 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
  */
@@ -23,8 +23,8 @@ export class BindingChain {
     frame = undefined;
     rootContext = undefined;
     activationStamp = NO_ACTIVATION_STAMP;
-    registrationOrder = UNREGISTERED_ORDER;
     instance = NO_INSTANCE;
+    scopedCacheKey = this.identifier;
     token;
     slot = DEFAULT_BINDING_SLOT;
     predicate = undefined;
@@ -38,10 +38,6 @@ export class BindingChain {
     deactivationHook = undefined;
     // The chain. Set by the first `to*()`, which is the only one a chain accepts.
     #isRegistered = false;
-    // Allocated only by a chain that actually displaces something — most never do.
-    #displacedByChain;
-    // Registry version after this chain's last write — a mismatch means someone else wrote in between.
-    #versionAfterLastWrite = -1;
     #registration;
     constructor(token, registration) {
         this.token = token;
@@ -51,13 +47,13 @@ export class BindingChain {
     get #binding() {
         return this;
     }
-    /** Loud failure for a refinement before `to*()`. */
+    /** Loud failure for a scope, a hook or `id()` before `to*()`. */
     #requireRegistered() {
         if (!this.#isRegistered) {
             throw new ChainNotRegisteredError(tokenName(this.token));
         }
     }
-    /** Loud failure for a second `to*()`, raised before the first one's fields can be overwritten. */
+    /** Loud failure for a slot step or a second `to*()` once registered, raised before a field is overwritten. */
     #requireUnregistered() {
         if (this.#isRegistered) {
             throw new ChainAlreadyRegisteredError(tokenName(this.token));
@@ -67,32 +63,22 @@ export class BindingChain {
         this.kind = kind;
         this.scope = scope;
         this.#isRegistered = true;
-        // A fresh registration parks nothing yet and restores nothing: one add, then the version.
         const registration = this.#registration;
-        const registry = registration.registry;
-        const displaced = registry.add(this.#binding);
+        const displaced = registration.registry.add(this.#binding);
         if (displaced !== undefined) {
             if (registration.deactivateDisplaced !== undefined) {
                 registration.deactivateDisplaced(displaced);
             }
             else {
-                this.#displacedByChain = [displaced];
                 registration.onDisplaced?.(displaced);
             }
         }
         if (registration.moduleBindingIds !== undefined) {
             registration.moduleBindingIds.push(this.identifier);
         }
-        this.#versionAfterLastWrite = registry.version;
         return this;
     }
-    /**
-     * 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, registration) {
         const { registry, moduleBindingIds, deactivateDisplaced, onDisplaced } = registration;
         for (let index = 0; index < declarations.length; index += 1) {
@@ -177,102 +163,67 @@ export class BindingChain {
         this.target = target;
         return this.#register("alias", "transient");
     }
-    // ── Refinement ─────────────────────────────────────────────────────────────────────────────────────────────────────
-    /**
-     * Whether this chain provably still owns the registry's last write with nothing parked.
-     *
-     * @remarks When it does, a refinement rewrites the live binding in place; otherwise `#reslot`
-     * re-checks liveness and restores what the new shape frees.
-     */
-    get #isProvablyLive() {
-        return this.#registration.registry.version === this.#versionAfterLastWrite && this.#displacedByChain === undefined;
-    }
-    /** Stamps this chain's last-write version after a mutation it made in place. */
-    #recordWrite() {
-        this.#versionAfterLastWrite = this.#registration.registry.version;
-    }
-    /** Bumps the registry for an index-neutral mutation (scope, hook) and records this chain's write. */
-    #touchAndRecordWrite() {
-        this.#registration.registry.touch();
-        this.#recordWrite();
-    }
-    // Slot and predicate are what the registry indexes on, so a re-slot takes the binding out of the
-    // registry, rewrites the two fields while it is out, and registers it again — same object, same id.
-    #reslot(slot, predicate) {
-        this.#requireRegistered();
-        this.#commit(() => {
-            this.slot = slot;
-            this.predicate = predicate;
-            // The frame reports the slot, so a resolve before this call memoized the previous one.
-            clearBindingFrame(this.#binding);
-        });
-        return this;
-    }
-    #withScope(scope) {
-        this.#requireRegistered();
-        if (this.scope !== scope) {
-            // An instance cached under the old scope must not survive the change — a later flip back
-            // to that scope would resurrect it.
-            this.#registration.scope.deleteSingleton(this.#binding);
-            this.#registration.scope.deleteScoped(this.identifier);
-            this.scope = scope;
-        }
-        // The frame reports the scope, so a resolve before this call memoized the previous one.
-        clearBindingFrame(this.#binding);
-        this.#touchAndRecordWrite();
-        return this;
-    }
-    // SPEC calls a candidate a binding that passes *all* of a chain's predicates, and the chain type
-    // reads as refinement, so a second `when()` narrows rather than replaces.
+    // ── Slot ───────────────────────────────────────────────────────────────────────────────────────────────────────────
+    // SPEC calls a candidate a binding that passes *all* of a chain's predicates, so a second `when()`
+    // narrows rather than replaces.
     when(predicate) {
-        this.#requireRegistered();
+        this.#requireUnregistered();
         const previous = this.predicate;
         // The composite carries both sides' requirements, so validate() still sees them.
-        const narrowed = previous === undefined
-            ? predicate
-            : mergingConstraintRequirements((ctx) => previous(ctx) && predicate(ctx), previous, predicate);
-        // The slot is unchanged, so a provably-live binding just takes the predicate in place.
-        if (this.#isProvablyLive) {
-            this.#registration.registry.setPredicate(this.#binding, narrowed);
-            this.#recordWrite();
-            return this;
-        }
-        return this.#reslot(this.slot, narrowed);
+        this.predicate =
+            previous === undefined
+                ? predicate
+                : mergingConstraintRequirements((ctx) => previous(ctx) && predicate(ctx), previous, predicate);
+        return this;
     }
     whenNamed(name) {
         return this.whenTagged(slotName.of(name));
     }
     whenTagged(criterion) {
-        this.#requireRegistered();
+        this.#requireUnregistered();
         if (this.isMany) {
             throw new ManyBindingSlotError(tokenName(this.token));
         }
-        return this.#reslot(withSlotCriterion(this.slot, criterion), this.predicate);
+        this.slot = withSlotCriterion(this.slot, criterion);
+        return this;
     }
     many() {
-        this.#requireRegistered();
+        this.#requireUnregistered();
         if (this.slot.tags.length !== 0) {
             throw new ManyBindingSlotError(tokenName(this.token));
         }
-        if (this.isMany) {
-            return this;
-        }
-        // A provably-live binding takes membership in place; the registry only moves it out of the lone
-        // map. Otherwise `#commit` re-checks liveness and restores what the freed slot lets back in.
-        if (this.#isProvablyLive) {
-            this.#registration.registry.setMany(this.#binding);
-            this.#recordWrite();
-            return this;
-        }
-        this.#commit(() => {
-            this.isMany = true;
-        });
+        this.isMany = true;
         return this;
     }
     whenDefault() {
-        // The default slot is what a fresh registration already has, so there is nothing to re-slot —
-        // but an unregistered chain must fail here exactly as it does in every other refinement.
+        // The default slot is what a fresh chain already has; the check keeps it a slot step like the others.
+        this.#requireUnregistered();
+        return this;
+    }
+    // ── Scope and lifecycle ────────────────────────────────────────────────────────────────────────────────────────────
+    #withScope(scope) {
         this.#requireRegistered();
+        // Nothing a cache, a frame or the version answers for depends on a scope that did not change.
+        if (this.scope === scope) {
+            return this;
+        }
+        // An instance cached under the old scope must not survive the change — a later flip back to that
+        // scope would resurrect it. A child's scoped cache is out of reach here, so leaving `scoped` retires
+        // the key every child filed its instance under.
+        const registration = this.#registration;
+        if (this.instance !== NO_INSTANCE) {
+            registration.scope.deleteSingleton(this.#binding);
+        }
+        if (this.scope === "scoped") {
+            registration.scope.deleteScoped(this.scopedCacheKey);
+            this.scopedCacheKey = generateBindingId();
+        }
+        this.scope = scope;
+        // The frame reports the scope, so a resolve before this call memoized the previous one.
+        if (this.frame !== undefined || this.rootContext !== undefined) {
+            clearBindingFrame(this.#binding);
+        }
+        registration.registry.touch();
         return this;
     }
     singleton() {
@@ -287,78 +238,17 @@ export class BindingChain {
     onActivation(fn) {
         this.#requireRegistered();
         this.activationHook = fn;
-        this.#touchAndRecordWrite();
+        this.#registration.registry.touch();
         return this;
     }
     onDeactivation(fn) {
         this.#requireRegistered();
         this.deactivationHook = fn;
-        this.#touchAndRecordWrite();
+        this.#registration.registry.touch();
         return this;
     }
     id() {
         this.#requireRegistered();
         return this.identifier;
     }
-    // ── Registry ───────────────────────────────────────────────────────────────────────────────────────────────────────
-    /**
-     * Registers this binding; with `rewrite` given, first takes the live binding out, rewrites it, and
-     * registers it again.
-     *
-     * @remarks A `when*()` that follows `to*()` re-slots an already-live binding and can displace one
-     * the final shape would never conflict with. Those stay parked in `#displacedByChain` until the
-     * chain settles, then get restored.
-     */
-    #commit(rewrite) {
-        const { registry, moduleBindingIds } = this.#registration;
-        const registered = this.#binding;
-        if (rewrite !== undefined) {
-            // A registry someone else wrote since this chain's last write invalidates the parked
-            // snapshot: restoring it could undo an unbind or shadow a newer binding.
-            if (registry.version !== this.#versionAfterLastWrite) {
-                this.#displacedByChain = undefined;
-            }
-            if (!registry.reslot(registered, rewrite)) {
-                // The chain's binding is no longer live (unbound or displaced) — a refinement must not
-                // resurrect it, so the chain goes inert against the registry.
-                this.#displacedByChain = undefined;
-                this.#versionAfterLastWrite = registry.version;
-                return;
-            }
-        }
-        else {
-            // Each `to*()` starts its own registration, so anything a previous one displaced is not this
-            // registration's to restore.
-            this.#displacedByChain = undefined;
-        }
-        const displaced = registry.add(registered);
-        if (displaced !== undefined) {
-            if (this.#registration.deactivateDisplaced !== undefined && rewrite === undefined) {
-                this.#registration.deactivateDisplaced(displaced);
-            }
-            else {
-                (this.#displacedByChain ??= []).push(displaced);
-                this.#registration.onDisplaced?.(displaced);
-            }
-        }
-        if (rewrite !== undefined && this.#displacedByChain !== undefined) {
-            this.#restoreNonConflicting(this.#displacedByChain);
-        }
-        if (rewrite === undefined && moduleBindingIds !== undefined) {
-            moduleBindingIds.push(this.identifier);
-        }
-        this.#versionAfterLastWrite = registry.version;
-    }
-    #restoreNonConflicting(displaced) {
-        for (let index = displaced.length - 1; index >= 0; index -= 1) {
-            const candidate = displaced[index];
-            // A restore must never displace: a slot that has been re-occupied keeps its occupant, and
-            // the candidate stays parked.
-            if (!this.#registration.registry.hasSlotOccupant(candidate)) {
-                this.#registration.registry.add(candidate);
-                this.#registration.onRestored?.(candidate);
-                displaced.splice(index, 1);
-            }
-        }
-    }
 }