@codefast/di 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @codefast/di
 
+## 0.10.1
+
+### Patch Changes
+
+- [#892](https://github.com/codefastlabs/codefast/pull/892) [`4c97c5b`](https://github.com/codefastlabs/codefast/commit/4c97c5b8c2314f25ee9df7eac5a4b5dd723d6d90) Thanks [@thevuong](https://github.com/thevuong)! - Lower the monorepo's Node floor from 24 to 22.12, so the packages install and run on the active Node 22 LTS line.
+
+  `engines.node` becomes `>=22.12.0` across every package — the floor the shared toolchain (oxlint, Vite, Vitest, TanStack
+  Start) already requires. Development stays on the latest Node (`.node-version`) for speed, and a CI matrix exercises the
+  floor and the active LTS directly, so the floor is a contract CI proves rather than one everyone has to run.
+  `@types/node` is pinned to the floor's major (`^22`), with a workspace override holding the whole tree there so a dev
+  tool's `@types/node: "*"` peer can no longer pull a newer major and mask an API the floor lacks. The floor stays
+  mechanical, not advisory: `@codefast/di` keeps its own `Map` upsert helpers rather than the ES2025
+  `Map.prototype.getOrInsert` (which would raise the floor to 26) and its `lib` stays `ES2024`. `@codefast/cli`'s mirror
+  step now calls the `node:path` functions directly instead of aliasing them, which the floor's types correctly flag as
+  unbound methods.
+
+  The shared `@codefast/typescript-config` presets pin `lib` and `target` to `ES2024` (was `ESNext`) so the compiler's
+  ECMAScript surface matches the Node floor: an ES2025 builtin such as `Map.prototype.getOrInsert` now fails to type-check
+  rather than compiling and crashing on Node 22.12. `@codefast/di` and `@codefast/di-testing` already pinned `lib` and are
+  unchanged.
+
+  Internal subpath imports move from a `#/` prefix to a bare `#` (`#core/token`, not `#/core/token`), and the
+  `package.json#imports` keys become `#*`/`#tests/*`/`#examples/*` to match. Node's native ESM resolver rejects a
+  `#/`-prefixed specifier with `ERR_INVALID_MODULE_SPECIFIER` on the whole Node 22 line (and on Node 24 before 24.14), and
+  each package ships those specifiers verbatim inside its published `dist/*.js` for a consumer's Node to resolve — so this
+  rename is what actually lets the packages import on the new floor. Purely internal: a consumer's own import paths are
+  unchanged.
+
 ## 0.10.0
 
 ### Minor Changes

package/README.md

@@ -35,7 +35,7 @@ its keep as the dependency graph grows.
 pnpm add @codefast/di
 ```
 
-`@codefast/di` requires Node.js 24 or later and TypeScript 5.9 or later, with native Stage 3 decorators. Leave
+`@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.
 
@@ -224,7 +224,8 @@ predicates ship from the root entry:
 | `whenParentTaggedAll(criteria)`      | the parent's slot carries all criteria in the array     |
 | `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#slot-matching).
+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).
 
 ## Decorators
 

package/dist/ambient/active-container.d.ts

@@ -1,8 +1,8 @@
 /** The container an `@inject` accessor initializer resolves from when it has no other handle. */
-import type { Container } from "#/container/container";
-import type { ConstructorInvocation } from "#/core/constructor-type";
-import type { Token } from "#/core/token";
-import type { Constructor, ResolveOptions } from "#/core/types";
+import type { Container } from "#container/container";
+import type { ConstructorInvocation } from "#core/constructor-type";
+import type { Token } from "#core/token";
+import type { Constructor, ResolveOptions } from "#core/types";
 /**
  * Path-continuing resolution the engine installs while constructing a class with `@inject` accessors.
  *
@@ -27,11 +27,6 @@ export declare function runWithContainer<Result>(container: Container, fn: () =>
  * @since 0.6.0
  */
 export declare function runWithAmbientResolution<Result>(container: Container, resolution: AmbientResolution | undefined, fn: () => Result): Result;
-/**
- * Returns the ambient container for the construction in flight, if one is installed.
- *
- * @since 0.3.16-canary.0
- */
 /**
  * Constructs `target` with `container` and `resolution` ambient for the duration of its constructor.
  *
@@ -42,6 +37,8 @@ export declare function runWithAmbientResolution<Result>(container: Container, r
  */
 export declare function constructWithAmbientResolution(container: Container, resolution: AmbientResolution, target: ConstructorInvocation, deps: ReadonlyArray<unknown>): unknown;
 /**
+ * Returns the ambient container for the construction in flight, if one is installed.
+ *
  * @since 0.10.0
  */
 export declare function getActiveContainer(): Container | undefined;

package/dist/ambient/active-container.js

@@ -26,11 +26,6 @@ export function runWithAmbientResolution(container, resolution, fn) {
         activeResolution = previousResolution;
     }
 }
-/**
- * Returns the ambient container for the construction in flight, if one is installed.
- *
- * @since 0.3.16-canary.0
- */
 /**
  * Constructs `target` with `container` and `resolution` ambient for the duration of its constructor.
  *
@@ -53,6 +48,8 @@ export function constructWithAmbientResolution(container, resolution, target, de
     }
 }
 /**
+ * Returns the ambient container for the construction in flight, if one is installed.
+ *
  * @since 0.10.0
  */
 export function getActiveContainer() {

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

@@ -6,13 +6,13 @@
  * 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.
  */
-import type { AliasBindingBuilder, BindingBuilder, BindingSlot, BindToBuilder, ConstantBindingBuilder, ScopedBindingBuilder, SingletonBindingBuilder, SingletonLifecycleBuilder, TransientBindingBuilder } from "#/core/binding";
-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 { AliasBindingBuilder, BindingBuilder, BindingSlot, BindToBuilder, ConstantBindingBuilder, ScopedBindingBuilder, SingletonBindingBuilder, SingletonLifecycleBuilder, TransientBindingBuilder } from "#core/binding";
+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";
 /**
  * Where a chain registers, and on whose behalf.
  *

package/dist/container/binding-builders.js

@@ -1,9 +1,9 @@
-import { clearBindingFrame, createBindingSlot, DEFAULT_BINDING_SLOT, generateBindingId, NO_INSTANCE, } 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 { normalizeToDescriptor } from "#/injection/descriptor";
+import { clearBindingFrame, createBindingSlot, DEFAULT_BINDING_SLOT, generateBindingId, NO_INSTANCE, } 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 { normalizeToDescriptor } from "#injection/descriptor";
 /** One criterion per key: re-tagging the same key replaces it rather than asking for both values. */
 function updateSlotTag(slot, criterion) {
     const tags = [...slot.tags];
@@ -126,6 +126,24 @@ export class BindingChain {
         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) {
@@ -149,8 +167,7 @@ export class BindingChain {
         }
         // The frame reports the scope, so a resolve before this call memoized the previous one.
         clearBindingFrame(this.#binding);
-        this.#registration.registry.touch();
-        this.#versionAfterLastWrite = this.#registration.registry.version;
+        this.#touchAndRecordWrite();
         return this;
     }
     // SPEC calls a candidate a binding that passes *all* of a chain's predicates, and the chain type
@@ -162,13 +179,10 @@ export class BindingChain {
         const narrowed = previous === undefined
             ? predicate
             : mergingConstraintRequirements((ctx) => previous(ctx) && predicate(ctx), previous, predicate);
-        const { registry } = this.#registration;
-        // The slot is unchanged, so nothing has to be re-indexed or displaced. With the last registry
-        // write this chain's own and nothing parked, the binding is provably live and is rewritten in
-        // place; otherwise the re-slot path re-checks liveness and restores what the shape frees.
-        if (registry.version === this.#versionAfterLastWrite && this.#displacedByChain === undefined) {
-            registry.setPredicate(this.#binding, narrowed);
-            this.#versionAfterLastWrite = registry.version;
+        // 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);
@@ -191,14 +205,11 @@ export class BindingChain {
         if (this.isMany) {
             return this;
         }
-        const { registry } = this.#registration;
-        // With the last registry write this chain's own and nothing parked, the binding is provably live
-        // and displaced nobody, so membership is written in place and the registry only moves it out of
-        // the lone map. Otherwise it goes through the re-slot path, which re-checks liveness and restores
-        // an ordinary binding this chain's `to*()` displaced, now that the member frees its slot.
-        if (registry.version === this.#versionAfterLastWrite && this.#displacedByChain === undefined) {
-            registry.setMany(this.#binding);
-            this.#versionAfterLastWrite = registry.version;
+        // 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(() => {
@@ -224,15 +235,13 @@ export class BindingChain {
     onActivation(fn) {
         this.#requireRegistered();
         this.activationHook = fn;
-        this.#registration.registry.touch();
-        this.#versionAfterLastWrite = this.#registration.registry.version;
+        this.#touchAndRecordWrite();
         return this;
     }
     onDeactivation(fn) {
         this.#requireRegistered();
         this.deactivationHook = fn;
-        this.#registration.registry.touch();
-        this.#versionAfterLastWrite = this.#registration.registry.version;
+        this.#touchAndRecordWrite();
         return this;
     }
     id() {

package/dist/container/container.d.ts

@@ -1,11 +1,11 @@
-import type { BindToBuilder } from "#/core/binding";
-import type { AsyncModule, SyncModule } from "#/core/module";
-import type { Token } from "#/core/token";
-import type { ActivationHandler, BindingIdentifier, Constructor, DeactivationHandler, ResolveOptions } from "#/core/types";
-import type { AutoRegisterRegistry } from "#/decorators/injectable";
-import type { ContainerGraphJson, GraphOptions } from "#/introspection/dependency-graph";
-import type { BindingSnapshot, ContainerSnapshot } from "#/introspection/inspector";
-import type { MetadataReader } from "#/metadata/metadata-types";
+import type { BindToBuilder } from "#core/binding";
+import type { AsyncModule, SyncModule } from "#core/module";
+import type { Token } from "#core/token";
+import type { ActivationHandler, BindingIdentifier, Constructor, DeactivationHandler, ResolveOptions } from "#core/types";
+import type { AutoRegisterRegistry } from "#decorators/injectable";
+import type { ContainerGraphJson, GraphOptions } from "#introspection/dependency-graph";
+import type { BindingSnapshot, ContainerSnapshot } from "#introspection/inspector";
+import type { MetadataReader } from "#metadata/metadata-types";
 /**
  * The public surface: binding, resolving, modules, lifecycle hooks, child scopes, and disposal.
  *

package/dist/container/container.js

@@ -1,23 +1,23 @@
-import { BindingChain } from "#/container/binding-builders";
-import { NO_INSTANCE } from "#/core/binding";
-import { effectiveBindingScope } from "#/core/binding-scope";
-import { constraintRequirementsOf } from "#/core/constraint-requirement";
-import { getOrInsert, getOrInsertComputed } from "#/core/map-upsert";
-import { isSyncModule, MODULE_SETUP } from "#/core/module";
-import { BindingRegistry } from "#/core/registry";
-import { tokenName } from "#/core/token";
-import { RESOLUTION_DIAGNOSTICS } from "#/errors/diagnostics";
-import { AsyncModuleLoadError, CircularDependencyError, DisposedContainerError, InternalError, RebindUnboundTokenError, ScopeViolationError, SyncDisposalNotSupportedError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#/errors/errors";
-import { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#/injection/resolve-options";
-import { buildDependencyGraph } from "#/introspection/dependency-graph";
-import { Inspector } from "#/introspection/inspector";
-import { LifecycleManager } from "#/lifecycle/lifecycle-manager";
-import { ScopeManager } from "#/lifecycle/scope-manager";
-import { MetadataReaderToken } from "#/metadata/metadata-reader-token";
-import { defaultMetadataReader } from "#/metadata/symbol-metadata-reader";
-import { verifyingMetadataReader } from "#/metadata/verifying-metadata-reader";
-import { ROOT_BRANCH } from "#/resolution/path/resolution-path";
-import { DependencyResolver } from "#/resolution/resolver";
+import { BindingChain } from "#container/binding-builders";
+import { NO_INSTANCE } from "#core/binding";
+import { effectiveBindingScope } from "#core/binding-scope";
+import { constraintRequirementsOf } from "#core/constraint-requirement";
+import { getOrInsert, getOrInsertComputed } from "#core/map-upsert";
+import { isSyncModule, MODULE_SETUP } from "#core/module";
+import { BindingRegistry } from "#core/registry";
+import { tokenName } from "#core/token";
+import { RESOLUTION_DIAGNOSTICS } from "#errors/diagnostics";
+import { AsyncModuleLoadError, CircularDependencyError, DisposedContainerError, InternalError, RebindUnboundTokenError, ScopeViolationError, SyncDisposalNotSupportedError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors/errors";
+import { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#injection/resolve-options";
+import { buildDependencyGraph } from "#introspection/dependency-graph";
+import { Inspector } from "#introspection/inspector";
+import { LifecycleManager } from "#lifecycle/lifecycle-manager";
+import { ScopeManager } from "#lifecycle/scope-manager";
+import { MetadataReaderToken } from "#metadata/metadata-reader-token";
+import { defaultMetadataReader } from "#metadata/symbol-metadata-reader";
+import { verifyingMetadataReader } from "#metadata/verifying-metadata-reader";
+import { ROOT_BRANCH } from "#resolution/path/resolution-path";
+import { DependencyResolver } from "#resolution/resolver";
 /** Whether a requirement's name is declared — on its token when it names one, on any token otherwise. */
 function isSlotNameDeclared(declared, requirement) {
     if (requirement.tokenName !== undefined) {

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

@@ -1,5 +1,5 @@
-import type { Binding } from "#/core/binding";
-import type { BindingScope } from "#/core/types";
+import type { Binding } from "#core/binding";
+import type { BindingScope } from "#core/types";
 /**
  * The scope a binding resolves under.
  *

package/dist/core/binding.d.ts

@@ -1,7 +1,7 @@
-import type { BindingTag, TagKeyMask } from "#/core/tag";
-import type { Token } from "#/core/token";
-import type { ActivationHandler, BindingIdentifier, BindingScope, Constructor, DeactivationHandler, ResolutionContext, ResolutionFrame, BindingConstraint } from "#/core/types";
-import type { InjectableDependency, InjectionDescriptor, ResolvedDependencyValue } from "#/injection/descriptor";
+import type { BindingTag, TagKeyMask } from "#core/tag";
+import type { Token } from "#core/token";
+import type { ActivationHandler, BindingIdentifier, BindingScope, Constructor, DeactivationHandler, ResolutionContext, ResolutionFrame, BindingConstraint } from "#core/types";
+import type { InjectableDependency, InjectionDescriptor, ResolvedDependencyValue } from "#injection/descriptor";
 /**
  * The criterion set a binding registers under and a request matches against.
  *
@@ -61,8 +61,8 @@ interface BindingBase<Value> {
      *
      * @remarks Both cycle guards that can use an `O(1)` flag read this — the sync transient-dynamic
      * lane and the async cascade lane — because synchronous code does not interleave, so the flag *is*
-     * exact path membership. Not optional: `createBinding` always sets it, and a field that may be
-     * absent is a field that can cost the shared hidden class. Resolver-owned; callers never set it.
+     * exact path membership. Not optional: the binding builder always initializes it, and a field that
+     * may be absent is a field that can cost the shared hidden class. Resolver-owned; callers never set it.
      */
     inFlight: boolean;
     /**

package/dist/core/binding.js

@@ -1,4 +1,4 @@
-import { NO_TAG_KEYS, slotName, tagKeyMaskOf } from "#/core/tag";
+import { NO_TAG_KEYS, slotName, tagKeyMaskOf } from "#core/tag";
 /**
  * Builds a slot from its criterion set, deriving the name view and key mask.
  *

package/dist/core/constraint-requirement.d.ts

@@ -1,5 +1,5 @@
 /** What a constraint needs to exist before it can ever match, so `validate()` can check for it. */
-import type { BindingConstraint } from "#/core/types";
+import type { BindingConstraint } from "#core/types";
 /**
  * Key the requirement is attached under.
  *

package/dist/core/module.d.ts

@@ -1,6 +1,6 @@
-import type { BindToBuilder } from "#/core/binding";
-import type { Token } from "#/core/token";
-import type { Constructor } from "#/core/types";
+import type { BindToBuilder } from "#core/binding";
+import type { Token } from "#core/token";
+import type { Constructor } from "#core/types";
 declare const SYNC_MODULE_BRAND: unique symbol;
 declare const ASYNC_MODULE_BRAND: unique symbol;
 /**

package/dist/core/registry.d.ts

@@ -1,7 +1,7 @@
-import type { Binding } from "#/core/binding";
-import type { BindingTag } from "#/core/tag";
-import type { Token } from "#/core/token";
-import type { BindingConstraint, BindingIdentifier, Constructor } from "#/core/types";
+import type { Binding } from "#core/binding";
+import type { BindingTag } from "#core/tag";
+import type { Token } from "#core/token";
+import type { BindingConstraint, BindingIdentifier, Constructor } from "#core/types";
 /**
  * One container's binding store, indexed by token, binding id, and slot for fast lookup.
  *
@@ -27,8 +27,8 @@ export declare class BindingRegistry {
     /**
      * Adds or replaces a binding using slot-aware last-wins. Returns the displaced binding, if any.
      *
-     * @remarks The binding is stored by reference — it must come from `createBinding`, which is
-     * what guarantees the single hidden class the resolver's hot reads depend on.
+     * @remarks The binding is stored by reference — it must come from the one binding builder, which
+     * is what guarantees the single hidden class the resolver's hot reads depend on.
      */
     add(binding: Binding): Binding | undefined;
     /** Remove all bindings for a token. Returns removed bindings. */

package/dist/core/registry.js

@@ -1,6 +1,6 @@
-import { bindingSlotEquals, bindingSlotToString, writableMembership, writablePredicate } from "#/core/binding";
-import { getOrInsert } from "#/core/map-upsert";
-import { advanceStateEpoch } from "#/core/state-epoch";
+import { bindingSlotEquals, bindingSlotToString, writableMembership, writablePredicate } from "#core/binding";
+import { getOrInsert } from "#core/map-upsert";
+import { advanceStateEpoch } from "#core/state-epoch";
 const NO_BINDINGS = Object.freeze([]);
 /** One construction site, so every record shares a hidden class. */
 function createTokenRecord(bindings) {
@@ -69,8 +69,8 @@ export class BindingRegistry {
     /**
      * Adds or replaces a binding using slot-aware last-wins. Returns the displaced binding, if any.
      *
-     * @remarks The binding is stored by reference — it must come from `createBinding`, which is
-     * what guarantees the single hidden class the resolver's hot reads depend on.
+     * @remarks The binding is stored by reference — it must come from the one binding builder, which
+     * is what guarantees the single hidden class the resolver's hot reads depend on.
      */
     add(binding) {
         this.#bump();
@@ -299,19 +299,14 @@ export class BindingRegistry {
      */
     setMany(binding) {
         this.#bump();
-        const key = binding.token;
-        if (this.#lone.get(key) === binding) {
-            writableMembership(binding).isMany = true;
-            this.#lone.delete(key);
-            this.#createRecord(key, [binding]);
+        // Set before any (re)indexing so `#indexSlot` sees a member and leaves it out of every slot.
+        writableMembership(binding).isMany = true;
+        if (this.#promoteLoneToRecord(binding.token, binding)) {
             return;
         }
-        // A default occupant that becomes a member frees its slot, so drop the stale index entry.
-        const record = this.#records?.get(key);
-        if (record?.defaultOccupant === binding) {
-            record.defaultOccupant = undefined;
-        }
-        writableMembership(binding).isMany = true;
+        // A default occupant that becomes a member frees its slot, so drop the stale index entry. A
+        // member cannot collapse a record back to lone, so this path does not settle.
+        this.#clearDefaultOccupant(binding.token, binding);
     }
     /**
      * Adds a predicate to a live binding in place.
@@ -322,21 +317,38 @@ export class BindingRegistry {
      */
     setPredicate(binding, predicate) {
         this.#bump();
+        // Set before any (re)indexing: a predicate-only binding holds no default slot.
         writablePredicate(binding).predicate = predicate;
-        const key = binding.token;
-        if (this.#lone.get(key) === binding) {
-            this.#lone.delete(key);
-            this.#createRecord(key, [binding]);
+        if (this.#promoteLoneToRecord(binding.token, binding)) {
             return;
         }
+        // The binding may have vacated the default slot, and a narrowed record can collapse back to lone.
+        const record = this.#clearDefaultOccupant(binding.token, binding);
+        if (record !== undefined) {
+            this.#settle(binding.token, record);
+        }
+    }
+    /**
+     * Moves a binding still holding the lone seat into a fresh one-binding record, returning whether it did.
+     *
+     * @remarks Its field (`isMany` or `predicate`) is written before this call, so the founding
+     * `#indexSlot` files it under the slot it now holds.
+     */
+    #promoteLoneToRecord(key, binding) {
+        if (this.#lone.get(key) !== binding) {
+            return false;
+        }
+        this.#lone.delete(key);
+        this.#createRecord(key, [binding]);
+        return true;
+    }
+    /** Clears the default-slot index entry a binding has vacated, returning its record if one exists. */
+    #clearDefaultOccupant(key, binding) {
         const record = this.#records?.get(key);
-        // The binding is now predicate-only, so it no longer holds the default slot it may have held.
         if (record?.defaultOccupant === binding) {
             record.defaultOccupant = undefined;
         }
-        if (record !== undefined) {
-            this.#settle(key, record);
-        }
+        return record;
     }
     /** Summarize available slot strings for a token (for error messages). */
     availableSlotStrings(token) {

package/dist/core/token.d.ts

@@ -1,4 +1,4 @@
-import type { Constructor } from "#/core/constructor-type";
+import type { Constructor } from "#core/constructor-type";
 declare const TOKEN_BRAND: unique symbol;
 declare const TOKEN_NAMES_BRAND: unique symbol;
 /**

package/dist/core/types.d.ts

@@ -1,8 +1,8 @@
-import type { Constructor } from "#/core/constructor-type";
-import type { BindingTag, TagKeyMask } from "#/core/tag";
-import type { Token } from "#/core/token";
-export type { Constructor } from "#/core/constructor-type";
-export type { BindingTag, TagKey, TagKeyMask } from "#/core/tag";
+import type { Constructor } from "#core/constructor-type";
+import type { BindingTag, TagKeyMask } from "#core/tag";
+import type { Token } from "#core/token";
+export type { Constructor } from "#core/constructor-type";
+export type { BindingTag, TagKey, TagKeyMask } from "#core/tag";
 /**
  * Token or class constructor used as a binding / injection / resolve key.
  *

package/dist/decorators/inject.d.ts

@@ -1,7 +1,7 @@
 /** `@inject` — the accessor-decorator channel, resolving from the ambient container. */
-import type { Token } from "#/core/token";
-import type { Constructor } from "#/core/types";
-import type { InjectionDescriptor, InjectOptions } from "#/injection/descriptor";
+import type { Token } from "#core/token";
+import type { Constructor } from "#core/types";
+import type { InjectionDescriptor, InjectOptions } from "#injection/descriptor";
 type ClassAccessorDecorator<This, Value> = (target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>) => ClassAccessorDecoratorResult<This, Value> | void;
 /**
  * Creates a dual-role value: an injection descriptor that also works as a class accessor decorator.

package/dist/decorators/inject.js

@@ -1,8 +1,8 @@
-import { getActiveContainer, getAmbientResolution } from "#/ambient/active-container";
-import { MissingContainerContextError, StaticMemberDecoratorError } from "#/errors/errors";
-import { buildInjectionDescriptor } from "#/injection/descriptor";
-import { injectionSlotToResolveOptions } from "#/injection/resolve-options";
-import { INJECT_ACCESSOR_KEY } from "#/metadata/metadata-keys";
+import { getActiveContainer, getAmbientResolution } from "#ambient/active-container";
+import { MissingContainerContextError, StaticMemberDecoratorError } from "#errors/errors";
+import { buildInjectionDescriptor } from "#injection/descriptor";
+import { injectionSlotToResolveOptions } from "#injection/resolve-options";
+import { INJECT_ACCESSOR_KEY } from "#metadata/metadata-keys";
 /**
  * The name of the class being constructed, or `undefined` when there is none to report.
  *

package/dist/decorators/injectable.d.ts

@@ -1,5 +1,5 @@
-import type { BindingScope, Constructor } from "#/core/types";
-import type { InjectableDependency, ResolvedDependencyValue } from "#/injection/descriptor";
+import type { BindingScope, Constructor } from "#core/types";
+import type { InjectableDependency, ResolvedDependencyValue } from "#injection/descriptor";
 /**
  * The collector `@injectable` registers a class into, for a container to bind later.
  *

package/dist/decorators/injectable.js

@@ -1,5 +1,5 @@
-import { normalizeToDescriptor } from "#/injection/descriptor";
-import { INJECTABLE_KEY } from "#/metadata/metadata-keys";
+import { normalizeToDescriptor } from "#injection/descriptor";
+import { INJECTABLE_KEY } from "#metadata/metadata-keys";
 /**
  * Creates an empty auto-register registry.
  *

package/dist/decorators/lifecycle-decorators.js

@@ -1,5 +1,5 @@
-import { StaticMemberDecoratorError } from "#/errors/errors";
-import { LIFECYCLE_KEY } from "#/metadata/metadata-keys";
+import { StaticMemberDecoratorError } from "#errors/errors";
+import { LIFECYCLE_KEY } from "#metadata/metadata-keys";
 /** Records the decorated method under one lifecycle phase; both decorators differ only in that phase. */
 function recordLifecycleMethod(phase) {
     return function (target, context) {

package/dist/errors/errors.d.ts

@@ -1,5 +1,5 @@
-import type { ConstraintRequirement } from "#/core/constraint-requirement";
-import type { BindingIdentifier, BindingScope, ResolveOptions } from "#/core/types";
+import type { ConstraintRequirement } from "#core/constraint-requirement";
+import type { BindingIdentifier, BindingScope, ResolveOptions } from "#core/types";
 /**
  * Base class for every error the library throws, each carrying a machine-readable `code`.
  *
@@ -223,15 +223,6 @@ export declare class MissingContainerContextError extends DiError {
     readonly accessorName: string | symbol;
     constructor(className: string | undefined, accessorName: string | symbol);
 }
-/**
- * A fluent chain was refined before a `to*()` call gave it a binding to refine.
- *
- * @remarks The builder types make this unreachable from TypeScript — `bind()` returns
- * `BindToBuilder`, which exposes only `to*()`. It exists for JavaScript callers and for anyone who
- * casts past the types, so the misuse fails loudly instead of mutating nothing.
- *
- * @since 0.5.0-canary.8
- */
 /**
  * A second `to*()` on a chain that already registered its binding.
  *
@@ -259,6 +250,12 @@ export declare class ManyBindingSlotError extends DiError {
     constructor(tokenName: string);
 }
 /**
+ * A fluent chain was refined before a `to*()` call gave it a binding to refine.
+ *
+ * @remarks The builder types make this unreachable from TypeScript — `bind()` returns
+ * `BindToBuilder`, which exposes only `to*()`. It exists for JavaScript callers and for anyone who
+ * casts past the types, so the misuse fails loudly instead of mutating nothing.
+ *
  * @since 0.10.0
  */
 export declare class ChainNotRegisteredError extends DiError {