@fnioc/di 2.0.0 → 4.0.0

package/dist/index.d.ts

@@ -1,26 +1,10 @@
+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
@@ -28,7 +12,7 @@ declare const hole: null;
  * `never[]` rest keeps any concrete function assignable here regardless of its
  * own parameter list.
  */
-type DepTarget = Ctor$1 | ((...args: never[]) => unknown);
+type DepTarget = Ctor$1 | Func$1<never[], unknown>;
 /**
  * A stable string identifying an interface — the DI key.
  *
@@ -38,12 +22,16 @@ type DepTarget = Ctor$1 | ((...args: never[]) => unknown);
 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.
+ * registered type token, rather than a resolved instance. The factory's own
+ * call signature is determined by the caller-supplied `params` list.
+ *
+ * `type` is the token of the produced type T (replaces the former `.factory` field).
+ * `params` is the complete, authored-order list of caller-supplied parameter tokens;
+ * when present it pins the factory shape so it no longer drifts with registration state.
  */
 interface FactoryRef {
-    readonly factory: Token;
+    readonly type: Token;
+    readonly params?: readonly Token[];
 }
 /**
  * Marks a parameter to be injected with the live resolution scope itself,
@@ -56,20 +44,28 @@ interface FactoryRef {
 interface ScopeRef {
     readonly scope: true;
 }
+/**
+ * A set of alternative dependency slots tried in declaration order (first
+ * resolvable member wins). If no member is resolvable, resolution throws.
+ * Each member is itself a `DepSlot` — nesting is allowed.
+ */
+interface Union {
+    readonly union: readonly DepSlot[];
+}
 /**
  * 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`).
+ *   - a `FactoryRef`    — a factory-injected parameter (see `FactoryRef`),
+ *   - a `ScopeRef`      — the live resolution scope (see `ScopeRef`), or
+ *   - a `Union`         — member-level alternatives tried in order.
  */
-type DepSlot = Token | typeof hole | FactoryRef | ScopeRef;
+type DepSlot = Token | FactoryRef | ScopeRef | Union;
 /**
  * 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
+ * (for overload support). `signatures[i][j]` is the `DepSlot` — a token, a
+ * `FactoryRef`, a `ScopeRef`, or a `Union` — for constructor parameter `j` of
  * overload `i`.
  */
 interface DepRecord {
@@ -90,7 +86,7 @@ interface DepRecord {
  *                   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
+ *                   of DepSlot (Token | FactoryRef | ScopeRef | Union) parallel to
  *                   the target's parameter list.
  */
 declare function defineDeps(target: DepTarget, signatures: readonly (readonly DepSlot[])[]): void;
@@ -115,7 +111,7 @@ declare function defineDeps(target: DepTarget, signatures: readonly (readonly De
  * }
  * ```
  */
-declare function signature(...tokens: readonly DepSlot[]): (value: Ctor$1, _context: ClassDecoratorContext) => void;
+declare function signature(...tokens: readonly DepSlot[]): Func$1<[Ctor$1, ClassDecoratorContext], void>;
 
 /**
  * The builder returned by `forCtor`. Chainable — each `.signature()` call
@@ -124,8 +120,8 @@ declare function signature(...tokens: readonly DepSlot[]): (value: Ctor$1, _cont
 interface ForCtorBuilder {
     /**
      * Appends one constructor signature (a positional array of DepSlot —
-     * Token | hole | FactoryRef) to the ctor's dependency metadata. Returns
-     * `this` for chaining.
+     * Token | FactoryRef | ScopeRef | Union) 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.
@@ -145,6 +141,46 @@ interface ForCtorBuilder {
  */
 declare function forCtor(ctor: Ctor$1): ForCtorBuilder;
 
+/**
+ * @fnioc/core — the immutable substrate and dependency-metadata format.
+ *
+ * Exports:
+ *   - `Token`          — string alias for a DI key
+ *   - `FactoryRef`     — marks a signature slot as a factory-injected parameter
+ *   - `ScopeRef`       — marks a signature slot as the live resolution scope
+ *   - `Union`          — member-level alternative slots tried in declaration order
+ *   - `DepSlot`        — one positional slot: Token | FactoryRef | ScopeRef | Union
+ *   - `Inject`         — compile-time brand that pins a token for one arg
+ *   - `DepTarget`      — a ctor or factory function metadata attaches to
+ *   - `DepRecord`      — shape of per-constructor metadata in the WeakMap
+ *   - `defineDeps`     — the single write path into the global WeakMap
+ *   - `getDeps`        — the read path (consumed by @fnioc/di)
+ *   - `union`          — runtime helper: constructs a Union slot from member slots
+ *   - `isFactoryRef`   — type guard for FactoryRef slots
+ *   - `isScopeRef`     — type guard for ScopeRef slots
+ *   - `isUnionSlot`    — type guard for Union slots
+ *   - `signature`      — TC39 class decorator factory
+ *   - `ForCtorBuilder` — return type of `forCtor`
+ *   - `forCtor`        — fluent free-function for third-party classes
+ */
+
+/**
+ * Constructs a `Union` slot — a set of alternative dependency slots tried in
+ * declaration order. The first resolvable member wins; if none is resolvable,
+ * resolution throws.
+ *
+ * @example
+ * ```ts
+ * forCtor(Handler).signature(
+ *   union("pkg:IRedis", "pkg:IMemoryCache"),
+ *   "pkg:ILogger",
+ * );
+ * ```
+ */
+declare function union(...slots: DepSlot[]): Union;
+
+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;
@@ -154,15 +190,15 @@ interface Ctor<in Args extends readonly any[] = any[], out Instance = any> {
  * 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
+ * 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 scope as its single argument (`(scope) => …`).
+ * 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 = (...args: any[]) => unknown;
+type Factory = Func<any[], unknown>;
 /** A class registration: a token bound to a concrete constructor. */
 interface ClassRegistration {
     readonly kind: "class";
@@ -192,230 +228,240 @@ interface ValueRegistration {
 /** 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.
+ * 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 three shapes:
- *   - `resolve<T>()`        — tokenless; the transformer lowers it to a token.
+ * `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 ResolveScope {
-    resolve<T>(): T;
+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.
+     * Returns a FACTORY for `type` rather than an instance. When `params` is
+     * absent or empty, returns a strict zero-arg `() => T` — every ctor slot must
+     * resolve from the container. When `params` is present, it is the complete
+     * authored-order list of caller-supplied parameter tokens; the returned factory
+     * has shape `(...params) => T`. The authored `resolve<(a: A) => T>()` lowers
+     * to `resolveFactory("pkg:T", ["pkg:A"])`.
      */
-    resolveFactory(token: Token): unknown;
-    createScope(name: string): ResolveScope;
+    resolveFactory(type: Token, params?: readonly 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 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.
+ * 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 generic `Scopes` is the user's scope-name union, threaded so
- * `.createScope` only accepts declared names.
+ * 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<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;
+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. */
-    private readonly instances;
+    readonly cache: Map<Token, unknown>;
     /** Owned instances in construction order — disposed in reverse. */
-    private readonly ownedOrder;
-    private disposed;
+    readonly owned: unknown[];
     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>;
+    /** 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;
     /**
-     * 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.
+     * 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 appendScopedLocal;
+    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);
     /**
-     * Registers a scope-local CLASS override — shadows ancestors for this scope
-     * and its descendants. Returns the `.as(scope?)` continuation.
+     * 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`.
      */
-    add(token: Token, ctor: Ctor): AddBuilder<Scopes>;
+    get name(): S;
     /**
-     * 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.
+     * 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).
      */
-    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;
+    createScope(...args: "scoped" extends S ? [name?: S] : [name: S]): ServiceProvider<S>;
     /**
-     * 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.
+     * 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>(): 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.
+     * Returns a FACTORY for `type` rather than an instance. When `params` is
+     * absent or empty, returns a strict zero-arg `() => T` — every ctor slot must
+     * resolve from the container (an unresolvable slot throws). When `params` is
+     * present, it is the complete authored-order list of caller-supplied parameter
+     * tokens; the returned factory has shape `(...params) => T`. The authored
+     * `resolve<(a: A) => T>()` lowers to `resolveFactory("pkg:T", ["pkg:A"])`.
      */
-    resolveFactory(token: Token): unknown;
+    resolveFactory(type: Token, params?: readonly 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.
+     * 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 (inclusive of this one) whose name matches
-     * `scope`, walking UP the chain. Returns `undefined` when none matches.
+     * Finds the nearest ancestor scope frame (inclusive) whose name matches
+     * `scopeName`, 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;
+    private static findOwner;
+    /** The chain of scope names from `vantage` up to the root, for diagnostics. */
+    private static 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.
+     * 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`. `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.
+     * 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 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.
+     * 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 makeScopeView;
+    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 scope, `FactoryRef` → an
-     *     injected callable) and call `factory(...args)`;
+     *     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(scopeView)` with the live scope as its sole argument.
-     * Deps resolve relative to `this` (the owning scope) — §5.4.
+     *     `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 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:
+     * 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 this scope's chain (selection
+     *   - 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 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`.
+     *   - 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
-     * — no Ramda-style placeholders, no leaked constructor arity.
+     * When `ref.params` is absent or empty, the factory is STRICT: every ctor slot
+     * of the target must resolve from the container. An unresolvable slot throws at
+     * build time (via `selectSignature`). The result is a zero-arg `() => T` that
+     * respects the target's registered lifetime.
+     *
+     * When `ref.params` is present, it is the COMPLETE authored-order list of
+     * caller-supplied parameter tokens. The caller-supplied set is pinned to those
+     * tokens (by first-occurrence left-to-right matching against ctor slots). A
+     * slot token that appears in `params` is caller-supplied even if it is also
+     * registered (caller wins). A slot that is neither claimed by `params` nor
+     * resolvable from the container → error. The factory shape is exactly
+     * `(...params) => T`; a fresh instance is built on every call (bypassing the
+     * instance cache — caller args differ per call so caching would be wrong).
      *
      * 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.
+     *   - A ZERO-ARG (no-params) factory routes through the normal `resolve` path
+     *     and RESPECTS the target's registered lifetime.
+     *   - A PARAMETERIZED factory constructs a FRESH instance every call.
      *
-     * 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.
+     * 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 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.
+     * Builds a factory target with the params-driven caller-supplied partition.
+     *
+     * `callerParams` is the authored-order list of tokens whose values are
+     * supplied by the caller (from the `FactoryRef.params` list). Each ctor slot
+     * whose token appears in `callerParams` (first-occurrence left-to-right match)
+     * takes the corresponding `callArgs` value; every other slot resolves from the
+     * container. A slot that is neither claimed nor resolvable → error (the factory
+     * cannot be built). A claimed slot that is also registered → caller wins.
+     *
+     * Always builds 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.
+     *
+     * `signature` may be `undefined` when the target has no DepRecord (zero-arg
+     * ctor or record-less factory) — in that case args is empty.
      */
     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 `FactoryRef` — always satisfiable; injected as a callable;
+     *   - a `ScopeRef` — always satisfiable; filled with the live provider view;
+     *   - a `Union` — satisfiable iff at least one member is resolvable; or
+     *   - a string token whose registration exists in the sealed map.
      *
-     * 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.
+     * An unregistered string token is not satisfiable. Equal-arity ties break by
+     * registration order. None satisfiable ⇒ throw naming the unsatisfiable tokens.
      */
     private selectSignature;
     /**
@@ -423,19 +469,37 @@ declare class Scope<Scopes extends string = string> implements ResolveScope {
      * 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`).
+     * registration order.
      */
     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.
+     * True when `slot` is a registered string token in the sealed map. A
+     * `FactoryRef`, `ScopeRef`, or `Union` is not tested here — use
+     * `isResolvableSlot` for a full slot check.
      */
     private isResolvable;
     /**
-     * Closes this scope synchronously, disposing the instances it owns in REVERSE
-     * construction order. Only native `Disposable` instances are disposed.
+     * True when a slot is resolvable in ANY form:
+     *   - `FactoryRef` / `ScopeRef` — always satisfiable (injected);
+     *   - `Union` — satisfiable iff at least one member is resolvable (recursive);
+     *   - string token — registered in the sealed map.
+     */
+    private isResolvableSlot;
+    /**
+     * Resolves a `Union` slot: tries each member in declaration order and returns
+     * the first resolvable one. If no member is resolvable, throws
+     * `NoSatisfiableUnionError`.
+     */
+    private resolveUnion;
+    /**
+     * Resolves a single `DepSlot` to its value, dispatching on slot kind.
+     * Used by `resolveUnion` to recurse into members.
+     */
+    private resolveSlot;
+    /**
+     * 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
@@ -443,9 +507,9 @@ declare class Scope<Scopes extends string = string> implements ResolveScope {
      */
     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
+     * 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>;
@@ -467,23 +531,17 @@ declare class Scope<Scopes extends string = string> implements ResolveScope {
  */
 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.
+     * Attaches the lifetime — the RUNTIME (lowered) form. Must name a declared
+     * scope.
      *
-     * `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;
+     * `.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.
@@ -527,18 +585,6 @@ declare class DiBuilder<Root extends string = "singleton", Children extends stri
      * 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
@@ -550,29 +596,30 @@ declare class DiBuilder<Root extends string = "singleton", Children extends stri
      * 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
+     * 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 scope — type it `(scope: ResolveScope)
-     * => T` and `scope.resolve(...)` its own deps. Returns the `.as(scope?)`
+     * 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: (scope: ResolveScope) => unknown): AddBuilder<Root | Children>;
+    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. Authoring `addValue<I>(v)` lowers to `addValue("token", v)`.
+     * 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<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.
+     * 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(): Scope<Root | Children>;
+    build(): ServiceProvider<Root | Children>;
 }
 
 /** Base class for every error the container raises. */
@@ -639,6 +686,14 @@ declare class FactoryTargetError extends DiError {
     readonly reason: "unregistered" | "not-a-class";
     constructor(factoryToken: Token, reason: "unregistered" | "not-a-class");
 }
+/**
+ * A `Union` slot was encountered during resolution but none of its member slots
+ * was resolvable. Resolution cannot proceed without at least one registered member.
+ */
+declare class NoSatisfiableUnionError extends DiError {
+    readonly members: readonly DepSlot[];
+    constructor(members: readonly DepSlot[]);
+}
 /**
  * Sync `dispose()` was called on a scope that owns a Promise-valued (thenable)
  * cached instance. A pending Promise cannot be disposed synchronously — the
@@ -648,5 +703,5 @@ 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 };
+export { AsyncDisposalRequiredError, CircularDependencyError, DiBuilder, DiError, FactoryTargetError, MissingMetadataError, MissingScopeError, NoSatisfiableSignatureError, NoSatisfiableUnionError, Scope, ServiceProvider, UnregisteredTokenError, defineDeps, forCtor, signature, union };
+export type { AddBuilder, ClassRegistration, Ctor, DepRecord, Factory, FactoryRegistration, ForCtorBuilder, Lifetime, Registration, ResolveScope, Resolver, ScopeFactory, Token, Union, ValueRegistration };