@codefast/di 0.11.0 → 0.13.0

package/dist/core/registry.js

@@ -1,4 +1,4 @@
-import { bindingSlotEquals, UNREGISTERED_ORDER, writableMembership, writablePredicate } from "#core/binding";
+import { bindingSlotEquals } from "#core/binding";
 import { getOrInsert } from "#core/map-upsert";
 import { advanceStateEpoch } from "#core/state-epoch";
 const NO_BINDINGS = Object.freeze([]);
@@ -21,8 +21,8 @@ function createTokenRecord(bindings) {
  * that only ever resolves through its parent — every per-request child — allocates no map.
  */
 const EMPTY_LONE = new Map();
-// Process-wide, so registration order compares across every registry a binding could be restored into.
-let registrationCounter = 0;
+const HELD_CONSTANT = 1;
+const HELD_ALIAS = 2;
 /**
  * @since 0.11.0
  */
@@ -35,18 +35,14 @@ export class BindingRegistry {
     // Every other token — several bindings, a tagged slot, a predicate — has a record here, and a
     // token is in exactly one of the two maps. Allocated by the first token that needs a record.
     #records;
-    // The binding the last `add` placed and where it landed: the fluent chain refines what it just
-    // registered, so a refinement that follows its own add re-slots without a map probe.
-    #lastAdded;
-    #lastAddedRecord;
     // Built on the first id-keyed read and maintained from then on: a bind-and-resolve container
     // never asks by id, so it never pays for the second map.
     #byId;
     // Set when the first tagged slot lands and never cleared, like the tagged maps it stands for.
     #taggedIndexBuilt = false;
-    // Set on the first constant registered and never cleared. Teardown only needs the negative answer
-    // to be exact, and that is what lets a container holding no constant skip its sweep entirely.
-    #heldConstantBinding = false;
+    // Kinds registered here at least once, never cleared: only the negative answers must be exact, so a
+    // container holding no constant skips its teardown sweep and one holding no alias skips its forwarding probe.
+    #heldKinds = 0;
     /** Monotonic version — increments on every mutation. */
     get version() {
         return this.#version;
@@ -59,7 +55,11 @@ export class BindingRegistry {
     }
     /** Whether a constant has ever been registered here, and so whether teardown has anything to sweep. */
     get hasHeldConstantBinding() {
-        return this.#heldConstantBinding;
+        return (this.#heldKinds & HELD_CONSTANT) !== 0;
+    }
+    /** Whether an alias has ever been registered here, and so whether a candidate list can hold one. */
+    get hasHeldAlias() {
+        return (this.#heldKinds & HELD_ALIAS) !== 0;
     }
     /** Whether the deferred tagged-slot index has had to be built. */
     get isTaggedIndexBuilt() {
@@ -88,25 +88,21 @@ export class BindingRegistry {
      */
     add(binding) {
         this.#bump();
-        if (binding.registrationOrder === UNREGISTERED_ORDER) {
-            registrationCounter += 1;
-            binding.registrationOrder = registrationCounter;
-        }
         if (binding.kind === "constant") {
-            this.#heldConstantBinding = true;
+            this.#heldKinds |= HELD_CONSTANT;
+        }
+        else if (binding.kind === "alias") {
+            this.#heldKinds |= HELD_ALIAS;
         }
         const key = binding.token;
         const records = this.#records;
         if (records !== undefined) {
             const record = records.get(key);
             if (record !== undefined) {
-                this.#lastAdded = binding;
-                this.#lastAddedRecord = record;
                 return this.#addToRecord(key, record, binding);
             }
         }
         const occupant = this.#lone.get(key);
-        this.#lastAdded = binding;
         if (occupant === undefined) {
             // The common bind: a fresh token taking the lone seat, one probe and one write.
             if (this.#byId !== undefined) {
@@ -114,33 +110,30 @@ export class BindingRegistry {
             }
             if (isDefaultSlotBinding(binding)) {
                 this.#setLone(key, binding);
-                this.#lastAddedRecord = undefined;
             }
             else {
-                this.#lastAddedRecord = this.#createRecord(key, [binding]);
+                this.#createRecord(key, [binding]);
             }
             return undefined;
         }
         // Same slot, last wins: the newcomer takes the lone seat and nothing else moves.
         if (isDefaultSlotBinding(binding)) {
             this.#setLone(key, binding);
-            this.#lastAddedRecord = undefined;
             if (this.#byId !== undefined) {
                 this.#byId.delete(occupant.identifier);
                 this.#byId.set(binding.identifier, binding);
             }
             return occupant;
         }
-        // A second shape joins the token, which is what a record is for.
+        // A second shape joins the token, which is what a record is for; every add is the newest, so it goes last.
         this.#deleteLone(key);
         this.#byId?.set(binding.identifier, binding);
-        this.#lastAddedRecord = this.#createRecord(key, occupant.registrationOrder < binding.registrationOrder ? [occupant, binding] : [binding, occupant]);
+        this.#createRecord(key, [occupant, binding]);
         return undefined;
     }
     /** Remove all bindings for a token. Returns removed bindings. */
     removeByToken(token) {
         this.#bump();
-        this.#lastAdded = undefined;
         const lone = this.#lone.get(token);
         if (lone !== undefined) {
             this.#deleteLone(token);
@@ -168,7 +161,6 @@ export class BindingRegistry {
             return undefined;
         }
         this.#bump();
-        this.#lastAdded = undefined;
         byId.delete(id);
         const key = binding.token;
         if (this.#lone.get(key)?.identifier === id) {
@@ -236,28 +228,12 @@ export class BindingRegistry {
     /** Remove all bindings. Returns all removed. */
     clear() {
         this.#bump();
-        this.#lastAdded = undefined;
         const all = this.allBindings();
         this.#clearLone();
         this.#records?.clear();
         this.#byId?.clear();
         return all;
     }
-    /** Whether a slot-based binding currently occupies `binding`'s slot, so adding it would displace. */
-    hasSlotOccupant(binding) {
-        if (isPurePredicateBinding(binding)) {
-            return false;
-        }
-        if (this.#lone.has(binding.token)) {
-            // The lone seat is the default slot, so only a default-slot newcomer collides with it.
-            return binding.slot.tags.length === 0;
-        }
-        const record = this.#records?.get(binding.token);
-        if (record === undefined) {
-            return false;
-        }
-        return this.#slotOccupant(record, binding.slot) !== undefined;
-    }
     /**
      * The binding indexed under one criterion.
      *
@@ -304,109 +280,22 @@ export class BindingRegistry {
     getDefaultSlotBinding(token) {
         return this.#lone.get(token) ?? this.#records?.get(token)?.defaultOccupant;
     }
-    /** A token's lone default-slot binding — the first read of every synchronous resolve. */
-    getFastDefault(token) {
-        return this.#lone.get(token);
-    }
-    /**
-     * Takes a live binding out of every index, lets `rewrite` change its slot or predicate, and reports
-     * whether it was live; the caller registers it again with `add`.
-     *
-     * @remarks The binding keeps its object and its id, so the id index needs no touch and nothing
-     * that holds the object has to be told. `false` means the binding was unbound or displaced since
-     * it registered, and a refinement must not resurrect it.
-     */
-    reslot(binding, rewrite) {
-        const key = binding.token;
-        if (this.#lone.get(key) === binding) {
-            this.#bump();
-            this.#lastAdded = undefined;
-            this.#deleteLone(key);
-        }
-        else {
-            const record = this.#records?.get(key);
-            const index = record === undefined ? -1 : record.bindings.indexOf(binding);
-            if (record === undefined || index === -1) {
-                return false;
-            }
-            this.#bump();
-            this.#lastAdded = undefined;
-            // Replaced, never spliced: a walk holding the current array must not lose its place.
-            record.bindings = record.bindings.toSpliced(index, 1);
-            this.#deindexSlot(record, binding);
-            this.#settle(key, record);
-        }
-        rewrite();
-        return true;
-    }
-    /**
-     * Marks a live binding as a collection member in place, moving it out of the lone map: a member is
-     * never the token's lone default answer, and nothing else indexes on membership.
-     */
-    setMany(binding) {
-        this.#bump();
-        // Set before any (re)indexing so `#indexSlot` sees a member and leaves it out of every slot.
-        writableMembership(binding).isMany = true;
-        if (binding === this.#lastAdded) {
-            // The chain refining what it just added: where the binding sits is known without a probe.
-            const record = this.#lastAddedRecord;
-            if (record === undefined) {
-                this.#deleteLone(binding.token);
-                this.#lastAddedRecord = this.#createRecord(binding.token, [binding]);
-            }
-            else if (record.defaultOccupant === binding) {
-                record.defaultOccupant = undefined;
-            }
-            return;
-        }
-        if (this.#promoteLoneToRecord(binding.token, binding)) {
-            return;
-        }
-        // 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.
+     * The token's default-slot alias, which forwards a request's criteria to its target, or `undefined`.
      *
-     * @remarks Only ever narrows — `when()` composes with any existing predicate — so the argument is
-     * never absent. Nothing indexes on the predicate, so the binding object and its id stay; a lone
-     * binding moves to a record because the lone map holds default-slot bindings with no predicate.
+     * @remarks A registry that never held an alias answers without probing, so a request missing every slot of a
+     * token pays for forwarding only where forwarding can happen.
      */
-    setPredicate(binding, predicate) {
-        this.#bump();
-        // Set before any (re)indexing: a predicate-only binding holds no default slot.
-        writablePredicate(binding).predicate = predicate;
-        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;
+    defaultSlotAlias(token) {
+        if ((this.#heldKinds & HELD_ALIAS) === 0) {
+            return undefined;
         }
-        this.#deleteLone(key);
-        this.#createRecord(key, [binding]);
-        return true;
+        const occupant = this.getDefaultSlotBinding(token);
+        return occupant !== undefined && occupant.kind === "alias" ? occupant : undefined;
     }
-    /** 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);
-        if (record?.defaultOccupant === binding) {
-            record.defaultOccupant = undefined;
-        }
-        return record;
+    /** A token's lone default-slot binding — the first read of every synchronous resolve. */
+    getFastDefault(token) {
+        return this.#lone.get(token);
     }
     #createRecord(key, bindings) {
         const record = createTokenRecord(bindings);
@@ -445,7 +334,7 @@ export class BindingRegistry {
         if (displacedBinding !== undefined) {
             record.bindings = record.bindings.filter((candidate) => candidate !== displacedBinding);
         }
-        insertInRegistrationOrder(record, binding);
+        record.bindings.push(binding);
         this.#byId?.set(binding.identifier, binding);
         this.#indexSlot(record, binding);
         this.#settle(key, record);
@@ -544,20 +433,6 @@ export class BindingRegistry {
  * Places a binding in its record by registration order: a fresh registration appends, and a binding a
  * chain took out and put back returns to its place.
  */
-function insertInRegistrationOrder(record, binding) {
-    const { bindings } = record;
-    const order = binding.registrationOrder;
-    if (bindings.length === 0 || bindings.at(-1).registrationOrder < order) {
-        bindings.push(binding);
-        return;
-    }
-    let index = bindings.length - 1;
-    while (index > 0 && bindings[index - 1].registrationOrder > order) {
-        index -= 1;
-    }
-    // Replaced, never spliced: a walk holding the current array must not lose its place.
-    record.bindings = bindings.toSpliced(index, 0, binding);
-}
 /** A binding nothing has to be matched against: the default slot, no predicate, not a collection member. */
 function isDefaultSlotBinding(binding) {
     return binding.slot.tags.length === 0 && binding.predicate === undefined && !binding.isMany;

package/dist/core/tag.js

@@ -1,6 +1,6 @@
 /** Tag keys and the interned pairs they mint — the one way a slot criterion is built. */
 /**
- * The bits a tag-key mask holds: the width of a 32-bit integer, a constant of the machine.
+ * The bits a tag-key mask holds: the width of a 32-bit integer.
  *
  * @remarks Ids past this wrap, so two keys can share a bit. The mask is a prefilter only — a shared
  * bit costs a false positive that the identity comparison then rejects, never a false negative.

package/dist/decorators/inject.d.ts

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

package/dist/decorators/inject.js

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

package/dist/decorators/injectable.js

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

package/dist/decorators/lifecycle.d.ts

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

package/dist/decorators/{lifecycle-decorators.js → lifecycle.js}

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

package/dist/decorators/{decorator-metadata.js → metadata-record.js}

@@ -1,7 +1,7 @@
 /**
  * The metadata record a decorator writes into, checked once for every decorator the library ships.
  */
-import { MissingDecoratorMetadataError } from "#errors/errors";
+import { MissingDecoratorMetadataError } from "#errors";
 /**
  * Returns the metadata record a decorator context carries.
  *

package/dist/{errors/errors.d.ts → errors.d.ts}

@@ -28,7 +28,9 @@ export declare class TokenNotBoundError extends DiError {
     readonly name = "TokenNotBoundError";
     readonly code = "TOKEN_NOT_BOUND";
     readonly tokenName: string;
-    constructor(tokenName: string);
+    /** The token names from the outermost request down to the unbound one, which is last. */
+    readonly path: ReadonlyArray<string>;
+    constructor(tokenName: string, path?: ReadonlyArray<string>);
 }
 /**
  * A token that has bindings, none of whose slots match the given `ResolveOptions`.
@@ -41,7 +43,9 @@ export declare class NoMatchingBindingError extends DiError {
     readonly tokenName: string;
     readonly options: ResolveOptions;
     readonly availableSlots: Array<string>;
-    constructor(tokenName: string, options: ResolveOptions, availableSlots: Array<string>);
+    /** The token names from the outermost request down to the unmatched one, which is last. */
+    readonly path: ReadonlyArray<string>;
+    constructor(tokenName: string, options: ResolveOptions, availableSlots: Array<string>, path?: ReadonlyArray<string>);
 }
 /**
  * Two or more candidate bindings that matched without the more-specific rule deciding a winner.
@@ -162,7 +166,7 @@ export declare class UnreachableLifecycleHookError extends DiError {
     readonly code = "UNREACHABLE_LIFECYCLE_HOOK";
     readonly tokenName: string;
     readonly phase: "onActivation" | "onDeactivation";
-    /** Nothing binds the token, or — for a deactivation hook — every binding it has is transient or scoped. */
+    /** Nothing binds the token, or — for a deactivation hook — every binding it has is transient. */
     readonly reason: "unbound" | "no-deactivatable-binding";
     constructor(tokenName: string, phase: "onActivation" | "onDeactivation", reason?: "unbound" | "no-deactivatable-binding");
 }
@@ -207,16 +211,6 @@ export declare class AsyncModuleLoadError extends DiError {
     readonly moduleName: string;
     constructor(moduleName: string);
 }
-/**
- * A synchronous disposal attempt on a container whose `onDeactivation` handlers may be async.
- *
- * @since 0.3.16-canary.0
- */
-export declare class SyncDisposalNotSupportedError extends DiError {
-    readonly name = "SyncDisposalNotSupportedError";
-    readonly code = "SYNC_DISPOSAL_NOT_SUPPORTED";
-    constructor();
-}
 /**
  * A `scoped` binding resolved from a container with no child scope context.
  *
@@ -246,10 +240,11 @@ export declare class MissingContainerContextError extends DiError {
     constructor(className: string | undefined, accessorName: string | symbol);
 }
 /**
- * A second `to*()` on a chain that already registered its binding.
+ * A slot step or a second `to*()` on a chain that already registered its binding.
  *
- * @remarks A chain is its binding, so it registers exactly once; a token bound twice is two `bind()`
- * calls, the second of which displaces the first under slot last-wins.
+ * @remarks A chain is its binding and registers exactly once, in its final shape, so its slot is
+ * settled by `to*()`; a token bound twice is two `bind()` calls, the second of which displaces the
+ * first under slot last-wins.
  *
  * @since 0.10.0
  */
@@ -274,11 +269,11 @@ export declare class ManyBindingSlotError extends DiError {
     constructor(tokenName: string);
 }
 /**
- * A fluent chain was refined before a `to*()` call gave it a binding to refine.
+ * A scope, a lifecycle hook or `id()` asked of a fluent chain before a `to*()` call registered its binding.
  *
  * @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.
+ * `BindToBuilder`, which exposes only the slot steps and `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
  */
@@ -341,6 +336,21 @@ export declare class SymbolKeyedLifecycleError extends DiError {
     readonly memberName: string;
     constructor(decoratorName: string, memberName: string);
 }
+/**
+ * A `@postConstruct` or `@preDestroy` on a private method, which the lifecycle reader cannot call by name.
+ *
+ * @remarks Reported at decoration rather than at resolve, so the error points at the declaration
+ * instead of a `MetadataReader` the caller never configured.
+ *
+ * @since 0.13.0
+ */
+export declare class PrivateLifecycleMethodError extends DiError {
+    readonly name = "PrivateLifecycleMethodError";
+    readonly code = "PRIVATE_LIFECYCLE_METHOD";
+    readonly decoratorName: string;
+    readonly memberName: string;
+    constructor(decoratorName: string, memberName: string);
+}
 /**
  * A decorator handed no metadata object, because the runtime has no `Symbol.metadata` to key one by.
  *

package/dist/{errors/errors.js → errors.js}

@@ -18,6 +18,10 @@ export class InternalError extends DiError {
         super(message);
     }
 }
+// A path of one token only repeats the name the message already opens with.
+function pathSuffix(path) {
+    return path.length > 1 ? ` Path: ${path.join(" → ")}` : "";
+}
 /**
  * A token with no binding at all, even after walking the parent container chain.
  *
@@ -27,9 +31,12 @@ export class TokenNotBoundError extends DiError {
     name = "TokenNotBoundError";
     code = "TOKEN_NOT_BOUND";
     tokenName;
-    constructor(tokenName) {
-        super(`No binding found for token '${tokenName}'. Did you forget container.bind(${tokenName})?`);
+    /** The token names from the outermost request down to the unbound one, which is last. */
+    path;
+    constructor(tokenName, path = [tokenName]) {
+        super(`No binding found for token '${tokenName}'. Did you forget container.bind(${tokenName})?${pathSuffix(path)}`);
         this.tokenName = tokenName;
+        this.path = path;
     }
 }
 // Options carry caller values a tag may hold — a bigint or a circular object must not make the
@@ -78,13 +85,16 @@ export class NoMatchingBindingError extends DiError {
     tokenName;
     options;
     availableSlots;
-    constructor(tokenName, options, availableSlots) {
+    /** The token names from the outermost request down to the unmatched one, which is last. */
+    path;
+    constructor(tokenName, options, availableSlots, path = [tokenName]) {
         const optionsString = describeResolveOptions(options);
         const slotsStr = availableSlots.join(", ");
-        super(`No binding for '${tokenName}' matching ${optionsString}. Available slots: [${slotsStr}].`);
+        super(`No binding for '${tokenName}' matching ${optionsString}. Available slots: [${slotsStr}].${pathSuffix(path)}`);
         this.tokenName = tokenName;
         this.options = options;
         this.availableSlots = availableSlots;
+        this.path = path;
     }
 }
 /**
@@ -225,12 +235,12 @@ export class UnreachableLifecycleHookError extends DiError {
     code = "UNREACHABLE_LIFECYCLE_HOOK";
     tokenName;
     phase;
-    /** Nothing binds the token, or — for a deactivation hook — every binding it has is transient or scoped. */
+    /** Nothing binds the token, or — for a deactivation hook — every binding it has is transient. */
     reason;
     constructor(tokenName, phase, reason = "unbound") {
         super(reason === "unbound"
             ? `${phase}() is registered for '${tokenName}', which nothing is bound to in this container or its ancestors, so the hook can never run. Bind the token, or — if '${tokenName}' is a class you bound as an implementation via .to(${tokenName}) — register the hook against the token you bound instead.`
-            : `${phase}() is registered for '${tokenName}', whose every binding in this container and its ancestors is transient or scoped, so the hook can never run: only a singleton or a constant is deactivated. Make one of its bindings a singleton, or drop the hook.`);
+            : `${phase}() is registered for '${tokenName}', whose every binding in this container and its ancestors is transient, so the hook can never run: a transient instance is never deactivated. Make one of its bindings a singleton or scoped, or drop the hook.`);
         this.tokenName = tokenName;
         this.phase = phase;
         this.reason = reason;
@@ -286,18 +296,6 @@ export class AsyncModuleLoadError extends DiError {
         this.moduleName = moduleName;
     }
 }
-/**
- * A synchronous disposal attempt on a container whose `onDeactivation` handlers may be async.
- *
- * @since 0.3.16-canary.0
- */
-export class SyncDisposalNotSupportedError extends DiError {
-    name = "SyncDisposalNotSupportedError";
-    code = "SYNC_DISPOSAL_NOT_SUPPORTED";
-    constructor() {
-        super("Container cannot be disposed synchronously because onDeactivation handlers may be async. Use `await using` or call container.dispose() explicitly.");
-    }
-}
 /**
  * A `scoped` binding resolved from a container with no child scope context.
  *
@@ -337,10 +335,11 @@ export class MissingContainerContextError extends DiError {
     }
 }
 /**
- * A second `to*()` on a chain that already registered its binding.
+ * A slot step or a second `to*()` on a chain that already registered its binding.
  *
- * @remarks A chain is its binding, so it registers exactly once; a token bound twice is two `bind()`
- * calls, the second of which displaces the first under slot last-wins.
+ * @remarks A chain is its binding and registers exactly once, in its final shape, so its slot is
+ * settled by `to*()`; a token bound twice is two `bind()` calls, the second of which displaces the
+ * first under slot last-wins.
  *
  * @since 0.10.0
  */
@@ -349,7 +348,7 @@ export class ChainAlreadyRegisteredError extends DiError {
     code = "CHAIN_ALREADY_REGISTERED";
     tokenName;
     constructor(tokenName) {
-        super(`The binding for token '${tokenName}' is already registered on this chain. Call bind() again to register another binding for the token.`);
+        super(`The binding for token '${tokenName}' is already registered on this chain, so its slot is final. Declare when*() and many() before to*(), or call bind() again to register another binding for the token.`);
         this.tokenName = tokenName;
     }
 }
@@ -371,11 +370,11 @@ export class ManyBindingSlotError extends DiError {
     }
 }
 /**
- * A fluent chain was refined before a `to*()` call gave it a binding to refine.
+ * A scope, a lifecycle hook or `id()` asked of a fluent chain before a `to*()` call registered its binding.
  *
  * @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.
+ * `BindToBuilder`, which exposes only the slot steps and `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
  */
@@ -455,6 +454,25 @@ export class SymbolKeyedLifecycleError extends DiError {
         this.memberName = memberName;
     }
 }
+/**
+ * A `@postConstruct` or `@preDestroy` on a private method, which the lifecycle reader cannot call by name.
+ *
+ * @remarks Reported at decoration rather than at resolve, so the error points at the declaration
+ * instead of a `MetadataReader` the caller never configured.
+ *
+ * @since 0.13.0
+ */
+export class PrivateLifecycleMethodError extends DiError {
+    name = "PrivateLifecycleMethodError";
+    code = "PRIVATE_LIFECYCLE_METHOD";
+    decoratorName;
+    memberName;
+    constructor(decoratorName, memberName) {
+        super(`@${decoratorName}() does not support a private method ('${memberName}'). Make the lifecycle method public, and call the private code from it.`);
+        this.decoratorName = decoratorName;
+        this.memberName = memberName;
+    }
+}
 /**
  * A decorator handed no metadata object, because the runtime has no `Symbol.metadata` to key one by.
  *