@fnioc/di 1.0.0 → 3.0.0

package/dist/index.d.ts

@@ -1,8 +1,633 @@
-export { DiBuilder } from "./builder.js";
-export type { AddBuilder } from "./builder.js";
-export { Scope } from "./scope.js";
-export type { Ctor, Factory, OverrideSpec, Registration, ClassRegistration, FactoryRegistration, ValueRegistration, ResolveScope, } from "./types.js";
-export { DiError, UnregisteredTokenError, MissingScopeError, MissingMetadataError, NoSatisfiableSignatureError, FactoryTargetError, CircularDependencyError, AsyncDisposalRequiredError, } from "./errors.js";
-export { signature, forCtor, hole } from "@fnioc/core";
-export type { Token, DepRecord, ForCtorBuilder } from "@fnioc/core";
-//# sourceMappingURL=index.d.ts.map
+type Func$1<in Args extends readonly any[] = any[], out Return = any> = (...args: Args) => Return;
+
+interface Ctor$1<in Args extends readonly any[] = any[], out Instance = any> {
+  new(...args: Args): Instance;
+  prototype: Instance;
+}
+
+/**
+ * The hole sentinel: marks a constructor parameter as caller-supplied rather
+ * than container-resolved.
+ *
+ * Used in signatures to communicate "this position is a hole — the factory
+ * caller supplies this argument, not the DI container." Detected by identity
+ * (`slot === hole`), and `null` is the sentinel value: it is exactly what the
+ * transformer emits for a hole slot, so the authoring surface and the lowered
+ * output agree on one representation.
+ *
+ * @example
+ * ```ts
+ * @signature("pkg:ILogger", hole, "pkg:IDb")
+ * class SqlRepo { constructor(log: ILogger, tableName: string, db: IDb) { ... } }
+ * ```
+ */
+declare const hole: null;
+
+/**
+ * Anything dependency metadata can be attached to: a class constructor (its
+ * deps are the ctor parameters) or a factory function (its deps are the call
+ * parameters). Both are objects, so both are valid global-WeakMap keys. The
+ * `never[]` rest keeps any concrete function assignable here regardless of its
+ * own parameter list.
+ */
+type DepTarget = Ctor$1 | Func$1<never[], unknown>;
+/**
+ * A stable string identifying an interface — the DI key.
+ *
+ * No branding, no literal types. Generated by the transformer from a TypeScript
+ * type at compile time; referenced by hand when using the manual authoring surfaces.
+ */
+type Token = string;
+/**
+ * Marks a constructor parameter to be injected as a *factory* producing the
+ * registered token `factory`, rather than a resolved instance. The factory's
+ * own call signature is the target ctor's unregistered params, partitioned at
+ * resolve time.
+ */
+interface FactoryRef {
+    readonly factory: Token;
+}
+/**
+ * Marks a parameter to be injected with the live resolution scope itself,
+ * rather than a resolved token. Emitted for a factory parameter whose type is
+ * `ResolveScope` — the engine fills the slot with the scope the factory is
+ * resolved into, so the factory body can `scope.resolve(...)` / `createScope`
+ * dynamically. Only meaningful on registration-level factory functions (a class
+ * ctor never receives the scope); on a ctor it would simply never match.
+ */
+interface ScopeRef {
+    readonly scope: true;
+}
+/**
+ * One positional slot in a constructor / factory signature:
+ *   - a `Token` string  — a container-resolved dependency,
+ *   - the `hole` sentinel — a caller-supplied parameter,
+ *   - a `FactoryRef` — a factory-injected parameter (see `FactoryRef`), or
+ *   - a `ScopeRef` — the live resolution scope (see `ScopeRef`).
+ */
+type DepSlot = Token | typeof hole | FactoryRef | ScopeRef;
+/**
+ * Per-constructor dependency metadata stored in the global WeakMap.
+ *
+ * `signatures` is an array of arrays: each element is one constructor signature
+ * (for overload support). `signatures[i][j]` is the `DepSlot` — a token, the
+ * `hole` sentinel, or a `FactoryRef` — for constructor parameter `j` of
+ * overload `i`.
+ */
+interface DepRecord {
+    readonly signatures: readonly (readonly DepSlot[])[];
+}
+
+/**
+ * The single write path into the global WeakMap.
+ *
+ * Both the transformer-emitted code and `@signature` / `forCtor` funnel through
+ * this function. No other code writes to the store.
+ *
+ * Merge semantics: appends each incoming signature to the ctor's existing
+ * DepRecord, deduping exact-equal signatures (same length + same elements in
+ * order). Creates the record from scratch if the ctor is not yet registered.
+ *
+ * @param target     The exact constructor OR factory function to annotate (no
+ *                   prototype-chain walk — subclasses do NOT inherit the
+ *                   parent's record).
+ * @param signatures An array of signatures; each signature is a positional array
+ *                   of DepSlot (Token | hole | FactoryRef | ScopeRef) parallel to
+ *                   the target's parameter list.
+ */
+declare function defineDeps(target: DepTarget, signatures: readonly (readonly DepSlot[])[]): void;
+
+/**
+ * TC39 class decorator factory that registers one constructor signature.
+ *
+ * Stacking multiple `@signature` decorators registers multiple overloads.
+ * TypeScript evaluates class decorators bottom-up, so the bottom-most
+ * `@signature` call runs first and appends first; tests should assert that
+ * ALL signatures are present rather than relying on a specific order.
+ *
+ * Returns `void` — does not replace the class.
+ *
+ * @example
+ * ```ts
+ * // Two overloads: one with a logger, one without
+ * @signature("pkg:ILogger", "pkg:IDb")
+ * @signature("pkg:IDb")
+ * class MyService {
+ *   constructor(logOrDb: ILogger | IDb, db?: IDb) { ... }
+ * }
+ * ```
+ */
+declare function signature(...tokens: readonly DepSlot[]): Func$1<[Ctor$1, ClassDecoratorContext], void>;
+
+/**
+ * The builder returned by `forCtor`. Chainable — each `.signature()` call
+ * appends one overload to the ctor's DepRecord.
+ */
+interface ForCtorBuilder {
+    /**
+     * Appends one constructor signature (a positional array of DepSlot —
+     * Token | hole | FactoryRef) to the ctor's dependency metadata. Returns
+     * `this` for chaining.
+     *
+     * Each `.signature(...)` call is one overload. Chaining two calls is
+     * equivalent to stacking two `@signature` decorators.
+     */
+    signature(...tokens: readonly DepSlot[]): ForCtorBuilder;
+}
+/**
+ * Fluent free-function for registering dependency metadata on a constructor
+ * without using a decorator — useful for third-party classes you do not own.
+ *
+ * @example
+ * ```ts
+ * forCtor(ThirdPartyService)
+ *   .signature("pkg:IDb")
+ *   .signature("pkg:ILogger", "pkg:IDb"); // second overload
+ * ```
+ */
+declare function forCtor(ctor: Ctor$1): ForCtorBuilder;
+
+type Func<in Args extends readonly any[] = any[], out Return = any> = (...args: Args) => Return;
+
+interface Ctor<in Args extends readonly any[] = any[], out Instance = any> {
+  new(...args: Args): Instance;
+  prototype: Instance;
+}
+
+/**
+ * A registration-level factory function. Its parameters are filled by the
+ * engine at resolve time, the same way a class constructor's are: a factory
+ * WITH a `defineDeps` record has each parameter resolved by its slot (token →
+ * resolved instance, `ScopeRef` → the live provider, hole → caller-supplied); a
+ * factory WITHOUT a record is the plugin-less escape hatch and is called with
+ * the live provider as its single argument (`(sp) => …`).
+ *
+ * May be async — it can return a `Promise<T>`. The container never awaits; the
+ * Promise flows through the sync resolution channel as a value (§"Async as
+ * values"). A consumer that depends on it declares `Promise<T>` and awaits.
+ */
+type Factory = Func<any[], unknown>;
+/** A class registration: a token bound to a concrete constructor. */
+interface ClassRegistration {
+    readonly kind: "class";
+    readonly ctor: Ctor;
+    /**
+     * The lifetime — the scope name that owns and caches the instance.
+     * `undefined` means transient (never cached; a fresh instance per resolve).
+     */
+    readonly scope: string | undefined;
+}
+/** A factory-function registration — its params are injected like a ctor's. */
+interface FactoryRegistration {
+    readonly kind: "factory";
+    readonly factory: Factory;
+    /**
+     * The lifetime — the scope name that owns and caches the result. `undefined`
+     * means transient (the factory runs on every resolve). Attached via `.as()`,
+     * exactly like a class registration.
+     */
+    readonly scope: string | undefined;
+}
+/** A value registration — an already-built instance, no lifetime. */
+interface ValueRegistration {
+    readonly kind: "value";
+    readonly useValue: unknown;
+}
+/** Any registration the engine can resolve. */
+type Registration = ClassRegistration | FactoryRegistration | ValueRegistration;
+/**
+ * The named lifetime tag for a registration. `"singleton"` and `"transient"`
+ * are the built-in names; `U` is the user-declared scope-name union (defaults
+ * to `"scoped"`). Transient is represented by the ABSENCE of a lifetime tag
+ * (`undefined` on the registration), not by the string `"transient"`.
+ */
+type Lifetime<U extends string = "scoped"> = "singleton" | "transient" | U;
+/**
+ * The minimal resolution surface — resolve tokens and get factories. Injected
+ * into factory parameters typed `Resolver` (and for the plugin-less escape
+ * hatch as the sole argument of a record-less factory).
+ *
+ * `resolve` has two published shapes (the tokenless authoring form
+ * `resolve<T>()` is a PURE TYPING contributed by the `@fnioc/transformer`
+ * augmentation, not part of di's published surface):
+ *   - `resolve<T>(token)`   — explicit token, typed return.
+ *   - `resolve(token)`      — explicit token, `unknown` return (dynamic).
+ */
+interface Resolver {
+    resolve<T>(token: Token): T;
+    resolve(token: Token): unknown;
+    /**
+     * Returns a FACTORY for the token rather than an instance — the resolve-site
+     * mirror of a `FactoryRef` ctor param. The authored `resolve<(a: A) => T>()`
+     * (a function-typed type arg) lowers to this.
+     */
+    resolveFactory(token: Token): unknown;
+}
+/**
+ * The scope-creation surface. Injected into factory parameters typed
+ * `ScopeFactory`, and implemented by `ServiceProvider`.
+ */
+interface ScopeFactory<S extends string = string> {
+    createScope(...args: "scoped" extends S ? [name?: S] : [name: S]): ServiceProvider<S>;
+}
+/**
+ * @deprecated Use `Resolver` instead. Kept for backwards compatibility.
+ *
+ * The resolution surface a factory receives — either as an injected `ScopeRef`
+ * parameter, or (plugin-less escape hatch) as the sole argument of a
+ * record-less factory.
+ */
+interface ResolveScope extends Resolver {
+    createScope(name: string): ServiceProvider;
+}
+
+/**
+ * A scope frame — a node in the parent-linked chain. Holds this scope's name,
+ * its instance cache, an ordered list for disposal, and an optional parent.
+ * It does NOT hold registrations (those live sealed on the ServiceProvider).
+ *
+ * The special "no frame" on the root ServiceProvider means transient-only /
+ * unscoped resolution — attempting to resolve a scoped registration from the
+ * root will throw MissingScopeError.
+ */
+declare class Scope {
+    /** This scope's name — must match the registration's lifetime tag. */
+    readonly name: string;
+    /** The parent scope, or omitted for the topmost frame. */
+    readonly parent?: Scope | undefined;
+    /** Instances this scope owns and caches, keyed by token. */
+    readonly cache: Map<Token, unknown>;
+    /** Owned instances in construction order — disposed in reverse. */
+    readonly owned: unknown[];
+    constructor(
+    /** This scope's name — must match the registration's lifetime tag. */
+    name: string, 
+    /** The parent scope, or omitted for the topmost frame. */
+    parent?: Scope | undefined);
+}
+/**
+ * The public container surface. Implements `Resolver` (resolve + resolveFactory)
+ * and `ScopeFactory` (createScope), plus native `Disposable`/`AsyncDisposable`.
+ *
+ * `S` is the user-declared scope-name union. The root (`DiBuilder.build()`)
+ * has an EMPTY scope slot — it acts as the unscoped root that owns singletons
+ * when the root name is "singleton", reached by the first `createScope("singleton")`.
+ * Wait — actually the root SP from build() DOES have a scope frame (named after
+ * the builder's rootName), exactly as before: `build()` creates a root SP
+ * with `new Scope(rootName)` as its frame.
+ */
+declare class ServiceProvider<S extends string = string> implements Resolver, ScopeFactory<S>, Disposable, AsyncDisposable {
+    /** The sealed registration map (shared across all providers in the tree). */
+    private readonly registrations;
+    private disposed;
+    /**
+     * The scope frame for this provider. `undefined` means this is the "unscoped"
+     * root — a sentinel that exists only for transient-only trees (no build()
+     * call sets this to undefined in normal usage; build() always sets a root name).
+     */
+    private readonly frame;
+    constructor(
+    /** The sealed registration map (shared across all providers in the tree). */
+    registrations: ReadonlyMap<Token, Registration[]>, 
+    /** This provider's scope frame, if any. */
+    frame?: Scope);
+    /**
+     * The name of this provider's scope frame. Throws if the provider has no
+     * frame (unscoped root). Kept for backwards-compatibility with tests that
+     * inspect `root.name`.
+     */
+    get name(): S;
+    /**
+     * Creates a child `ServiceProvider` whose scope frame is a new `Scope` named
+     * `name`, parented to this provider's frame (or a top-level frame if this
+     * provider is unscoped).
+     *
+     * Default name `"scoped"` is accepted only when `"scoped"` ∈ S (the
+     * conditional-rest-param type ensures this at the call site).
+     */
+    createScope(...args: "scoped" extends S ? [name?: S] : [name: S]): ServiceProvider<S>;
+    /**
+     * Resolves a token to an instance, walking the scope chain for the owning
+     * frame. The public entry point starts a fresh cycle-detection stack.
+     */
+    resolve<T>(token: Token): T;
+    resolve(token: Token): unknown;
+    /**
+     * Returns a FACTORY for `token` rather than an instance — the resolve-site
+     * mirror of a `FactoryRef` ctor param. The authored `resolve<(a: A) => T>()`
+     * lowers here. The returned callable exposes the target's UNREGISTERED /
+     * caller-supplied parameters in order (PRD §7 "Partial / positional
+     * factories"); a fully-resolvable target yields a zero-arg lazy factory that
+     * respects the target's registered lifetime.
+     */
+    resolveFactory(token: Token): unknown;
+    /**
+     * Returns the most-recent registration for `token` from the sealed map.
+     * The sealed map is shared across all providers in the tree; local overrides
+     * are not supported in the new model (scope-local registration is deleted).
+     */
+    private lookup;
+    /**
+     * Finds the nearest ancestor scope frame (inclusive) whose name matches
+     * `scopeName`, walking UP the chain. Returns `undefined` when none matches.
+     */
+    private static findOwner;
+    /** The chain of scope names from `vantage` up to the root, for diagnostics. */
+    private static chainNames;
+    /**
+     * The internal resolver. `vantage` is the scope frame the walk starts from.
+     * `stack` is the active resolution path (for cycle detection); it is shared
+     * across the whole `resolve()` call but never across separate calls.
+     */
+    private resolveWith;
+    /**
+     * Builds an instance for `registration`. `owningFrame` is the scope frame
+     * whose chain the dependencies are resolved against — THE critical rule.
+     */
+    private instantiate;
+    /**
+     * The resolution view injected for a `ScopeRef` parameter (`Resolver` or
+     * `ScopeFactory` typed param). Produces a ServiceProvider-like view that
+     * continues the active cycle `stack` and resolves relative to `owningFrame`.
+     */
+    private makeProviderView;
+    /**
+     * Invokes a factory registration under the metadata-vs-scope rule:
+     *   - factory WITH a `defineDeps` record → resolve each slot (token →
+     *     resolved instance, `ScopeRef` → the live provider view, `FactoryRef` →
+     *     an injected callable) and call `factory(...args)`;
+     *   - factory WITHOUT a record (the plugin-less escape hatch) → call
+     *     `factory(providerView)` with the live provider view as its sole argument.
+     * Deps resolve relative to `owningFrame` (the owning scope) — §5.4.
+     */
+    private invokeFactory;
+    /**
+     * Constructs a class instance, resolving its constructor dependencies
+     * relative to `owningFrame`. Performs greedy signature selection over the
+     * ctor's DepRecord, then fills each slot:
+     *
+     *   - a string token → resolved through the owning frame's chain (selection
+     *     guarantees every string-token slot here is resolvable);
+     *   - a `FactoryRef` → injected as a callable (see `makeFactory`);
+     *   - a `ScopeRef` → the live provider view.
+     */
+    private construct;
+    /**
+     * Builds the callable injected for a `FactoryRef` parameter.
+     *
+     * The target ctor's signature is partitioned at CALL time against the live
+     * registration map: each slot that is a registered token is resolved; each
+     * slot that is an unregistered token or a `hole` takes the next
+     * caller-supplied argument, positionally. The injected callable therefore
+     * exposes only the target's unregistered parameters, in their relative order.
+     *
+     * Lifetime semantics:
+     *   - A ZERO-ARG factory routes through the normal `resolve` path, so it
+     *     RESPECTS the target's registered lifetime.
+     *   - A PARAMETERIZED factory constructs a FRESH instance on every call and
+     *     BYPASSES the instance cache. Caller args differ per call, so caching
+     *     would be wrong.
+     *
+     * The closure captures `owningFrame`. §5.4 holds at call time: the target's
+     * deps resolve relative to the scope that owns the factory-holding instance.
+     */
+    private makeFactory;
+    /**
+     * Builds a factory target, partitioning its already-selected signature
+     * against the live registration map: a registered token is resolved; a
+     * `ScopeRef` is the live provider view; a `FactoryRef` is injected; an
+     * unregistered token or a `hole` takes the next caller-supplied argument
+     * positionally. A class target is `new`ed, a factory target is called.
+     * Always a fresh result — a parameterized factory bypasses the instance cache.
+     * Runs on a fresh cycle stack since the factory is invoked outside the
+     * original resolve.
+     */
+    private buildPartitioned;
+    /**
+     * Greedy signature selection. Scans signatures longest → shortest and returns
+     * the first SATISFIABLE one. A slot is satisfiable when it is:
+     *
+     *   - a `FactoryRef` — always satisfiable; injected as a callable;
+     *   - a `ScopeRef` — always satisfiable; filled with the live provider view; or
+     *   - a string token whose registration exists in the sealed map.
+     *
+     * A `hole` (`null`) is NOT satisfiable on a direct resolve. An unregistered
+     * string token is also not satisfiable. Equal-arity ties break by registration
+     * order. None satisfiable ⇒ throw naming the unsatisfiable tokens.
+     */
+    private selectSignature;
+    /**
+     * Greedy signature selection for a FACTORY TARGET. Unlike `selectSignature`,
+     * there is no resolvability gate: a target's unregistered tokens are not
+     * unsatisfiable — they are the factory's caller-supplied parameters. So the
+     * choice is purely the longest signature, equal-arity ties broken by
+     * registration order.
+     */
+    private selectTargetSignature;
+    /**
+     * True when `slot` is a registered string token in the sealed map. A hole
+     * (`null`), `FactoryRef`, or `ScopeRef` is not a registered token, so it is
+     * never "resolvable" in this sense.
+     */
+    private isResolvable;
+    /**
+     * Closes this provider synchronously, disposing the instances its scope frame
+     * owns in REVERSE construction order. Only native `Disposable` instances are
+     * disposed. NO cascade to child scopes.
+     *
+     * Throws `AsyncDisposalRequiredError` if any owned instance is a Promise
+     * (thenable) — a pending Promise cannot be disposed synchronously; the caller
+     * must use `disposeAsync()`. Idempotent: a second call is a no-op.
+     */
+    dispose(): void;
+    /**
+     * Closes this provider asynchronously. Awaits each owned Promise-valued
+     * instance first (so an async factory's result settles before teardown), then
+     * disposes owned instances in REVERSE construction order — honoring both
+     * `Symbol.asyncDispose` and `Symbol.dispose`. Idempotent.
+     */
+    disposeAsync(): Promise<void>;
+    /** Drops owned references after disposal so they can be collected. */
+    private clear;
+    /** Native `using` support — delegates to `dispose()`. */
+    [Symbol.dispose](): void;
+    /** Native `await using` support — delegates to `disposeAsync()`. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
+/**
+ * The continuation returned by a class `DiBuilder.add`. Carries the just-added
+ * registration so `.as()` can attach its lifetime in place. An `.add()` with no
+ * trailing `.as()` leaves the registration scopeless ⇒ transient.
+ *
+ * `Scopes` is threaded so `.as()` only accepts a declared scope name —
+ * compile-time captive-misconfiguration guard at the registration site.
+ */
+interface AddBuilder<Scopes extends string> {
+    /**
+     * Attaches the lifetime — the RUNTIME (lowered) form. Must name a declared
+     * scope.
+     *
+     * `.as("singleton")` is what the engine executes: the transformer rewrites the
+     * authored type-arg form (`.as<"singleton">()`) to this value-arg form before
+     * runtime, and a plugin-less caller writes it directly. The AUTHORED type-arg
+     * form (`.as<S extends Scopes>(): void`) is a PURE TYPING contributed by the
+     * `@fnioc/transformer` augmentation — it is not part of di's published surface,
+     * so it only type-checks when the transformer's types are in the program.
+     */
+    as(scope: Scopes): void;
+}
+/**
+ * The registration builder.
+ *
+ * `Root` is the root scope's name (the app-lifetime tag singletons bind to);
+ * `Children` is the union of declarable child-scope names. The scopes
+ * `.as()`/`.createScope` accept are `Root | Children`. `"transient"` is NOT a
+ * member — transient is the absence of a scope, not a scope.
+ *
+ * @example
+ * ```ts
+ * const services = new DiBuilder<"singleton", "request">();
+ * services.add("pkg:ILogger", ConsoleLogger).as("singleton"); // lowered form
+ * const root = services.build();                  // mints the "singleton" root
+ * const logger = root.resolve<ILogger>("pkg:ILogger");
+ * const req = root.createScope("request");        // nested child scope
+ * ```
+ */
+declare class DiBuilder<Root extends string = "singleton", Children extends string = never> {
+    /**
+     * The service collection: each token maps to a LIST of registrations in
+     * registration order. Registering a token appends; resolution picks the
+     * most-recent (last) registration. Earlier registrations are retained, which
+     * is what lets a later `.add()` override an earlier one without deletion.
+     */
+    private readonly registrations;
+    /**
+     * The root scope's runtime name. `Root` is erased at runtime, so the name is
+     * captured at construction (defaulting to `"singleton"`, matching the `Root`
+     * default). Most callers never set it — the default covers the common
+     * `DiBuilder<"singleton", …>` case; pass it only when `Root` is non-default.
+     */
+    private readonly rootName;
+    constructor(rootName?: Root);
+    /** Appends a registration to `token`'s list, creating the list on first use. */
+    private append;
+    /**
+     * Appends a scopeless `class`/`factory` base registration and returns the
+     * `.as(scope?)` continuation. `.as()` appends a fresh SCOPED copy so the
+     * array's last entry wins; a bare `.add(...)`/`.addFactory(...)` with no
+     * trailing `.as()` leaves the base (transient) registration in place.
+     */
+    private appendScoped;
+    /**
+     * Class registration — a string token bound to a concrete constructor. The
+     * runtime form: what the transformer emits for a class, and what a
+     * plugin-less caller writes directly. Returns the `.as(scope?)` continuation.
+     */
+    add(token: Token, ctor: Ctor): AddBuilder<Root | Children>;
+    /**
+     * Factory registration — a string token bound to a factory function. The
+     * runtime form the transformer emits for an authored `add<I>(fn)`, and what a
+     * plugin-less caller writes directly.
+     *
+     * Parameter injection follows the metadata rule (see `ServiceProvider`): a
+     * factory WITH a `defineDeps` record (emitted by the transformer) has each
+     * parameter injected by its slot; a record-less factory (the plugin-less
+     * escape hatch) is called with the live provider — type it `(sp: Resolver)
+     * => T` and `sp.resolve(...)` its own deps. Returns the `.as(scope?)`
+     * continuation so a factory caches at a named scope exactly like a class.
+     */
+    addFactory(token: Token, factory: Func<[Resolver], unknown>): AddBuilder<Root | Children>;
+    /**
+     * Value registration — an already-built instance, no deps and no lifetime.
+     * Separate from `add` because a value may itself be a function (a callable
+     * service), which is structurally indistinguishable from a factory inside one
+     * overload. The authoring form `addValue<I>(v)` (which lowers to
+     * `addValue("token", v)`) is a PURE TYPING contributed by the
+     * `@fnioc/transformer` augmentation, not part of di's published surface.
+     */
+    addValue(token: Token, value: unknown): void;
+    /**
+     * Mints the root ServiceProvider with a SEALED copy of the registration map.
+     * Sealing (deep-freezing the map and each per-token list) ensures that any
+     * `.add()` call on the builder after `build()` cannot mutate what the root
+     * and its descendants see — the container's view is fixed at construction time.
+     */
+    build(): ServiceProvider<Root | Children>;
+}
+
+/** Base class for every error the container raises. */
+declare class DiError extends Error {
+    constructor(message: string);
+}
+/**
+ * A token was requested but no registration exists for it anywhere in the
+ * resolving scope's chain (nor on the builder's base map).
+ */
+declare class UnregisteredTokenError extends DiError {
+    readonly token: Token;
+    constructor(token: Token);
+}
+/**
+ * A registration carries a lifetime scope, but no ancestor scope in the
+ * resolving chain has a matching name. This is the captive-dependency /
+ * misconfiguration detector — the engine never auto-creates a scope to satisfy
+ * the lifetime.
+ */
+declare class MissingScopeError extends DiError {
+    readonly token: Token;
+    readonly scope: string;
+    readonly availableScopes: readonly string[];
+    constructor(token: Token, scope: string, availableScopes: readonly string[]);
+}
+/**
+ * A constructor with parameters has no DepRecord in the WeakMap — the
+ * transformer never saw it and it was never hand-annotated.
+ */
+declare class MissingMetadataError extends DiError {
+    readonly token: Token;
+    readonly ctorName: string;
+    constructor(token: Token, ctorName: string);
+}
+/**
+ * A constructor has DepRecord signatures, but none of them is directly
+ * satisfiable in the owning scope (every signature names at least one token
+ * that is not registered, or contains a hole this phase cannot fill).
+ */
+declare class NoSatisfiableSignatureError extends DiError {
+    readonly token: Token;
+    readonly ctorName: string;
+    readonly unsatisfiable: readonly Token[];
+    constructor(token: Token, ctorName: string, unsatisfiable: readonly Token[]);
+}
+/**
+ * A token reappeared on the active resolution stack — the dependency graph has
+ * a cycle. The message includes the full path that closed the loop.
+ */
+declare class CircularDependencyError extends DiError {
+    readonly path: readonly Token[];
+    constructor(path: readonly Token[]);
+}
+/**
+ * A constructor parameter is typed as a factory of some token (a `FactoryRef`),
+ * but that token cannot be turned into a factory: either it is not registered,
+ * or it is registered as a `useValue` / `useFactory` override rather than a
+ * class. A factory injects a callable that constructs the target class on
+ * demand, so the target must be a class registration.
+ */
+declare class FactoryTargetError extends DiError {
+    readonly factoryToken: Token;
+    readonly reason: "unregistered" | "not-a-class";
+    constructor(factoryToken: Token, reason: "unregistered" | "not-a-class");
+}
+/**
+ * Sync `dispose()` was called on a scope that owns a Promise-valued (thenable)
+ * cached instance. A pending Promise cannot be disposed synchronously — the
+ * caller must use `disposeAsync()`.
+ */
+declare class AsyncDisposalRequiredError extends DiError {
+    constructor();
+}
+
+export { AsyncDisposalRequiredError, CircularDependencyError, DiBuilder, DiError, FactoryTargetError, MissingMetadataError, MissingScopeError, NoSatisfiableSignatureError, Scope, ServiceProvider, UnregisteredTokenError, defineDeps, forCtor, hole, signature };
+export type { AddBuilder, ClassRegistration, Ctor, DepRecord, Factory, FactoryRegistration, ForCtorBuilder, Lifetime, Registration, ResolveScope, Resolver, ScopeFactory, Token, ValueRegistration };