@fnioc/di 1.0.0 → 2.0.0

package/dist/index.d.ts

@@ -1,8 +1,652 @@
-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
+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 | ((...args: 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[]): (value: Ctor$1, _context: 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;
+
+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 scope, hole → caller-supplied); a
+ * factory WITHOUT a record is the plugin-less escape hatch and is called with
+ * the live scope as its single argument (`(scope) => …`).
+ *
+ * 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 = (...args: 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 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. A structural subset of `Scope`: resolve further tokens
+ * and open child scopes.
+ *
+ * `resolve` has three shapes:
+ *   - `resolve<T>()`        — tokenless; the transformer lowers it to a token.
+ *   - `resolve<T>(token)`   — explicit token, typed return.
+ *   - `resolve(token)`      — explicit token, `unknown` return (dynamic).
+ */
+interface ResolveScope {
+    resolve<T>(): T;
+    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;
+    createScope(name: string): ResolveScope;
+}
+
+/**
+ * A node in the scope chain. Created from a `DiBuilder` (the root) or from a
+ * parent scope (`.createScope`). Holds the instances it owns and any local
+ * override registrations.
+ *
+ * The generic `Scopes` is the user's scope-name union, threaded so
+ * `.createScope` only accepts declared names.
+ */
+declare class Scope<Scopes extends string = string> implements ResolveScope {
+    /** This scope's name. The root scope's name is its lifetime. */
+    readonly name: Scopes;
+    /** The parent scope, or `undefined` for the root. */
+    private readonly parent;
+    /** The builder's base registration map (shared, walked last). */
+    private readonly baseRegistrations;
+    /**
+     * Local override registrations held at this scope (shadow ancestors). Each
+     * token maps to a LIST in registration order; the most-recent (last) entry
+     * wins, mirroring the builder's service collection.
+     */
+    private readonly localRegistrations;
+    /** Instances this scope owns and caches, keyed by token. */
+    private readonly instances;
+    /** Owned instances in construction order — disposed in reverse. */
+    private readonly ownedOrder;
+    private disposed;
+    constructor(
+    /** This scope's name. The root scope's name is its lifetime. */
+    name: Scopes, 
+    /** The parent scope, or `undefined` for the root. */
+    parent: Scope<Scopes> | undefined, 
+    /** The builder's base registration map (shared, walked last). */
+    baseRegistrations: ReadonlyMap<Token, Registration[]>);
+    /** Appends a registration to a token's list in the given map. */
+    private static appendTo;
+    /**
+     * Creates a parent-linked child scope with the given (declared) name. Scopes
+     * MUST nest — this parent chain IS the lifetime hierarchy. The root is minted
+     * by `DiBuilder.build()`; every other scope descends from one via this call.
+     */
+    createScope(childName: Scopes): Scope<Scopes>;
+    /**
+     * Appends a scopeless `class`/`factory` LOCAL override and returns the
+     * `.as(scope?)` continuation (mirrors `DiBuilder.appendScoped`). Local
+     * overrides shadow any ancestor or base registration for the same token, for
+     * this scope and its descendants only, most-recent-wins.
+     */
+    private appendScopedLocal;
+    /**
+     * Registers a scope-local CLASS override — shadows ancestors for this scope
+     * and its descendants. Returns the `.as(scope?)` continuation.
+     */
+    add(token: Token, ctor: Ctor): AddBuilder<Scopes>;
+    /**
+     * Registers a scope-local FACTORY override. Parameter injection follows the
+     * same metadata rule as a builder factory (record → inject; record-less →
+     * called with the live scope). Returns the `.as(scope?)` continuation.
+     */
+    addFactory(token: Token, factory: (scope: ResolveScope) => unknown): AddBuilder<Scopes>;
+    /** Registers a scope-local VALUE override — the instance itself, no lifetime. */
+    addValue(token: Token, value: unknown): this;
+    /**
+     * Resolves a token to an instance, walking the parent chain for both the
+     * registration and the owning scope. The public entry point starts a fresh
+     * cycle-detection stack.
+     */
+    resolve<T>(): T;
+    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;
+    /**
+     * Walks UP the chain (this scope's locals → ancestors' locals → base map),
+     * returning the nearest registration for `token`. Child shadows parent, and
+     * within any one scope's list the most-recent (last) registration wins — so a
+     * later `.add()`/`.add(...)` override beats an earlier one without deletion.
+     */
+    private lookup;
+    /**
+     * Finds the nearest ancestor scope (inclusive of this one) whose name matches
+     * `scope`, walking UP the chain. Returns `undefined` when none matches.
+     */
+    private findOwner;
+    /** The chain of scope names from this scope up to the root, for diagnostics. */
+    private chainNames;
+    /**
+     * The internal resolver. `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`. `owningScope` is the scope whose
+     * chain the dependencies are resolved against — THE critical rule. For a
+     * factory override that is the scope passed to the closure; for a class it is
+     * the scope its ctor deps resolve relative to.
+     */
+    private instantiate;
+    /**
+     * The resolution view a factory receives — `resolve` (overloaded; a tokenless
+     * authored `resolve<T>()` is lowered to a token before runtime),
+     * `resolveFactory`, and `createScope`, all continuing the active cycle
+     * `stack` and resolving relative to THIS (the owning) scope.
+     */
+    private makeScopeView;
+    /**
+     * Invokes a factory registration under the metadata-vs-scope rule:
+     *   - factory WITH a `defineDeps` record → resolve each slot (token →
+     *     resolved instance, `ScopeRef` → the live scope, `FactoryRef` → an
+     *     injected callable) and call `factory(...args)`;
+     *   - factory WITHOUT a record (the plugin-less escape hatch) → call
+     *     `factory(scopeView)` with the live scope as its sole argument.
+     * Deps resolve relative to `this` (the owning scope) — §5.4.
+     */
+    private invokeFactory;
+    /**
+     * Constructs a class instance on a DIRECT resolve, resolving its constructor
+     * dependencies relative to THIS scope (the owning scope). Performs greedy
+     * signature selection over the ctor's DepRecord, then fills each slot:
+     *
+     *   - a string token → resolved through this scope's chain (selection
+     *     guarantees every string-token slot here is resolvable);
+     *   - a `FactoryRef` → injected as a callable (see `makeFactory`);
+     *   - a `ScopeRef` → the live scope.
+     *
+     * A hole never reaches here on a direct resolve: it is an unresolvable token,
+     * so selection rejects any signature carrying one (falling to a shorter
+     * optional-overload, or throwing). Holes are filled by the caller only when
+     * the class is a factory target — see `buildPartitioned`.
+     */
+    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
+     * — no Ramda-style placeholders, no leaked constructor arity.
+     *
+     * Lifetime semantics:
+     *   - A ZERO-ARG factory (the target ctor has no holes / unregistered params)
+     *     routes the build through the normal `resolve` path, so it RESPECTS the
+     *     target's registered lifetime: a singleton target yields the same
+     *     instance on every call; a transient target yields a fresh one.
+     *   - A PARAMETERIZED factory (the target has holes / unregistered params
+     *     filled per call) constructs a FRESH instance on every call and BYPASSES
+     *     the instance cache. Caller args differ per call, so caching would be
+     *     wrong — two calls with different arguments must not collapse to one
+     *     cached instance.
+     *
+     * The closure captures `this` as the owning scope. §5.4 holds at call time:
+     * the target's deps resolve relative to the scope that owns the
+     * factory-holding instance, exactly as a direct resolve would — so a factory
+     * captured by a singleton that tries to build a request-scoped target still
+     * throws `MissingScopeError` when invoked.
+     */
+    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 scope; 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 (caller args differ
+     * per call). 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. The
+     *     factory's target need not be resolvable for the slot to count (an
+     *     unregistered target surfaces a `FactoryTargetError` when the factory is
+     *     built / called, not here);
+     *   - a `ScopeRef` — always satisfiable; filled with the live scope; or
+     *   - a string token whose registration is resolvable in this (the owning)
+     *     scope's chain.
+     *
+     * A `hole` (`null`) is NOT special — it is an unregistered token, so it is
+     * unsatisfiable on a direct resolve. A class with an optional/defaulted param
+     * carries a shorter "without that arg" overload (emitted by the transformer);
+     * greedy selection falls to it when the longer one can't be satisfied, so the
+     * default / `undefined` applies. A required unfilled param has no such shorter
+     * overload and surfaces a `NoSatisfiableSignatureError` (build it via a
+     * factory instead). A signature is satisfiable iff every string-token slot is
+     * resolvable.
+     *
+     * - Equal-arity ties break by registration order (the order signatures appear
+     *   in the DepRecord), which `sort`'s stability preserves.
+     * - 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 (`sort` stability). Always returns a signature (the
+     * caller has already checked `signatures.length > 0`).
+     */
+    private selectTargetSignature;
+    /**
+     * True when `slot` is a registered string token somewhere in this scope's
+     * chain. A hole (`null`), `FactoryRef`, or `ScopeRef` is not a registered
+     * token, so it is never "resolvable" in this sense.
+     */
+    private isResolvable;
+    /**
+     * Closes this scope synchronously, disposing the instances it owns in REVERSE
+     * construction order. Only native `Disposable` instances are disposed.
+     *
+     * 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 scope 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. Must name a declared scope.
+     *
+     * Two call shapes, by design (PRD §7):
+     *   - AUTHORED   `.as<"singleton">()` — the scope name is a TYPE argument; the
+     *     `S extends Scopes` bound is the compile-time captive-misconfiguration
+     *     guard. No value argument is passed; this form is never executed (the
+     *     transformer rewrites it before it runs).
+     *   - LOWERED    `.as("singleton")` — the transformer rewrites the type
+     *     argument to a value argument. This is the form the engine executes; the
+     *     runtime reads the scope from the value arg.
+     *
+     * `scope` is therefore OPTIONAL at the type level: the authored form supplies
+     * it as a type arg only, the lowered form as a value. A bare `.as()` with no
+     * type arg leaves `S = Scopes` and is a degenerate (scopeless) call — use the
+     * type arg.
+     */
+    as<S extends Scopes>(scope?: S): 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;
+    /**
+     * Type-only authoring overloads — the forms the transformer rewrites FROM:
+     *   - `add<I>(C)`  → `add("token", C)`            (class)
+     *   - `add<I>(fn)` → `addFactory("token", fn)`    (factory; the transformer
+     *     knows the arg is a function and routes it to `addFactory`).
+     * The ctor is typed `Ctor<any[], I>` (plain construct signature, so an
+     * abstract class is rejected); the factory is any `(...args) => I`. Neither
+     * runs post-transform — they exist purely so type-driven authoring
+     * type-checks before lowering.
+     */
+    add<I>(ctor: Ctor<any[], I>): AddBuilder<Root | Children>;
+    add<I>(factory: (...args: any[]) => I): AddBuilder<Root | Children>;
+    /**
+     * 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 `Scope.instantiate`): 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 scope — type it `(scope: ResolveScope)
+     * => T` and `scope.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: (scope: ResolveScope) => 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. Authoring `addValue<I>(v)` lowers to `addValue("token", v)`.
+     */
+    addValue<I>(value: I): void;
+    addValue(token: Token, value: unknown): void;
+    /**
+     * Mints the root scope. The root is a real, app-lifetime object — its name is
+     * `Root` (the lifetime that singletons, or whatever the app's longest
+     * lifetime is, bind to). No argument: `build()` owns the root name via the
+     * `Root` type parameter.
+     */
+    build(): Scope<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, UnregisteredTokenError, defineDeps, forCtor, hole, signature };
+export type { AddBuilder, ClassRegistration, Ctor, DepRecord, Factory, FactoryRegistration, ForCtorBuilder, Registration, ResolveScope, Token, ValueRegistration };