@fnioc/di 2.0.0 → 3.0.0

package/README.md

@@ -58,7 +58,7 @@ services.add("pkg:ICache", {
 
 A `useFactory` with `scope: "singleton"` runs once and caches the result; without a `scope` it runs on every resolve (transient). `useValue` is always the same reference.
 
-The same two specs are available scope-locally via `scope.add(token, spec)`, so a single scope (e.g. a test scope) can swap an implementation without rebuilding the builder.
+To override a registration for a specific context (e.g. a test double), register a later spec for the same token on the `DiBuilder` before calling `build()`. The registration map is append-only and last-registration-wins, so a later `.add(token, ...)` / `.addFactory(token, ...)` / `.addValue(token, ...)` call shadows the earlier one without deleting it. The map seals at `build()` — no post-build mutation is possible.
 
 ---
 
@@ -272,16 +272,19 @@ Note: `FactoryTargetError` is thrown when the factory callable is constructed (a
 | `add<I>(Concrete)` | `(ctor: new (...) => I) => AddBuilder` | Register a concrete class against interface `I`. |
 | `.as<S>()` | `(scope: S) → void` | Set the lifetime scope. No call → transient. |
 | `add(token, ctor)` | `(token: string, ctor) => AddBuilder` | Class registration (lowered form). |
-| `add(token, spec)` | `(token: string, { useFactory, scope? } \| { useValue }) => this` | Factory / value registration. No dep metadata required. |
-| `build()` | `() => Scope<Root \| Children>` | Mint the root scope (named `Root`). No argument. |
+| `addFactory(token, factory)` | `(token: string, factory: (sp: Resolver) => T) => AddBuilder` | Factory registration. No dep metadata required — the factory receives the live `Resolver`. |
+| `addValue(token, value)` | `(token: string, value: unknown) => void` | Value registration. A pre-built instance, re-used as-is. |
+| `build()` | `() => ServiceProvider<Root \| Children>` | Seal the registration map and mint the root `ServiceProvider`. No post-build mutation is possible. |
 
-### `Scope<Scopes>`
+### `ServiceProvider<Scopes>`
+
+Implements `Resolver` + `ScopeFactory` + `Disposable` / `AsyncDisposable`.
 
 | Member | Signature | Description |
 |---|---|---|
-| `createScope(name)` | `(name: Scopes) => Scope<Scopes>` | Create a nested child scope. |
-| `add(token, spec)` | `(token, { useFactory, scope? } \| { useValue }) => this` | Scope-local override registration. |
 | `resolve<T>(token)` | `(token: string) => T` | Resolve an instance. Throws on captive-dep violation, missing scope ancestor, or cycle. |
+| `resolveFactory(token)` | `(token: string) => (...args) => T` | Resolve a factory callable for the token rather than an instance. |
+| `createScope(name)` | `(name: Scopes) => ServiceProvider<Scopes>` | Create a nested child scope. |
 | `dispose()` | `() => void` | Sync close. Throws if any owned instance has async-only disposal. |
 | `disposeAsync()` | `() => Promise<void>` | Async close. |
 | `[Symbol.dispose]()` | — | Native `using` support. |

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+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;
@@ -28,7 +30,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.
  *
@@ -115,7 +117,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
@@ -145,6 +147,8 @@ interface ForCtorBuilder {
  */
 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;
@@ -154,15 +158,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,18 +196,24 @@ 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;
     /**
@@ -212,76 +222,94 @@ interface ResolveScope {
      * (a function-typed type arg) lowers to this.
      */
     resolveFactory(token: Token): unknown;
-    createScope(name: string): ResolveScope;
+}
+/**
+ * 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;
     /**
@@ -294,63 +322,54 @@ declare class Scope<Scopes extends string = string> implements ResolveScope {
      */
     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.
+     * 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;
     /**
@@ -360,62 +379,41 @@ declare class Scope<Scopes extends string = string> implements ResolveScope {
      * 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.
+     * exposes only the target's unregistered parameters, in their relative order.
      *
      * 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 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 `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.
+     * `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. 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.
+     *   - 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.
      *
-     * - 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.
+     * 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;
     /**
@@ -423,19 +421,19 @@ 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 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.
+     * 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 +441,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 +465,17 @@ declare class Scope<Scopes extends string = string> implements ResolveScope {
  */
 interface AddBuilder<Scopes extends string> {
     /**
-     * Attaches the lifetime. Must name a declared scope.
+     * Attaches the lifetime — the RUNTIME (lowered) form. 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;
+     * `.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 +519,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 +530,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. */
@@ -648,5 +629,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, Scope, ServiceProvider, UnregisteredTokenError, defineDeps, forCtor, hole, signature };
+export type { AddBuilder, ClassRegistration, Ctor, DepRecord, Factory, FactoryRegistration, ForCtorBuilder, Lifetime, Registration, ResolveScope, Resolver, ScopeFactory, Token, ValueRegistration };

package/dist/index.js

@@ -160,98 +160,65 @@ function isScopeRef2(slot) {
 class Scope {
   name;
   parent;
-  baseRegistrations;
-  localRegistrations = new Map;
-  instances = new Map;
-  ownedOrder = [];
-  disposed = false;
-  constructor(name, parent, baseRegistrations) {
+  cache = new Map;
+  owned = [];
+  constructor(name, parent) {
     this.name = name;
     this.parent = parent;
-    this.baseRegistrations = baseRegistrations;
   }
-  static appendTo(map, token, registration) {
-    const existing = map.get(token);
-    if (existing === undefined) {
-      map.set(token, [registration]);
-    } else {
-      existing.push(registration);
+}
+
+class ServiceProvider {
+  registrations;
+  disposed = false;
+  frame;
+  constructor(registrations, frame) {
+    this.registrations = registrations;
+    this.frame = frame;
+  }
+  get name() {
+    if (this.frame === undefined) {
+      throw new TypeError("This ServiceProvider has no scope frame (unscoped root).");
     }
+    return this.frame.name;
   }
-  createScope(childName) {
-    return new Scope(childName, this, this.baseRegistrations);
-  }
-  appendScopedLocal(token, base) {
-    Scope.appendTo(this.localRegistrations, token, base);
-    const map = this.localRegistrations;
-    return {
-      as(scope) {
-        if (scope === undefined)
-          return;
-        Scope.appendTo(map, token, { ...base, scope });
-      }
-    };
-  }
-  add(token, ctor) {
-    return this.appendScopedLocal(token, {
-      kind: "class",
-      ctor,
-      scope: undefined
-    });
-  }
-  addFactory(token, factory) {
-    return this.appendScopedLocal(token, {
-      kind: "factory",
-      factory,
-      scope: undefined
-    });
-  }
-  addValue(token, value) {
-    Scope.appendTo(this.localRegistrations, token, {
-      kind: "value",
-      useValue: value
-    });
-    return this;
+  createScope(...args) {
+    const name = args[0] ?? "scoped";
+    const childFrame = new Scope(name, this.frame);
+    return new ServiceProvider(this.registrations, childFrame);
   }
   resolve(token) {
     if (token === undefined) {
       throw new TypeError("resolve<T>() requires the @fnioc/transformer plugin (no token at " + "runtime). Without it, resolve with an explicit token: " + 'resolve<T>("my:token").');
     }
-    return this.resolveWith(token, []);
+    return this.resolveWith(token, this.frame, []);
   }
   resolveFactory(token) {
-    return this.makeFactory({ factory: token });
+    return this.makeFactory({ factory: token }, this.frame);
   }
   lookup(token) {
-    let node = this;
-    while (node !== undefined) {
-      const local = node.localRegistrations.get(token);
-      if (local !== undefined && local.length > 0)
-        return local[local.length - 1];
-      node = node.parent;
-    }
-    const base = this.baseRegistrations.get(token);
-    return base !== undefined && base.length > 0 ? base[base.length - 1] : undefined;
+    const list = this.registrations.get(token);
+    return list !== undefined && list.length > 0 ? list[list.length - 1] : undefined;
   }
-  findOwner(scope) {
-    let node = this;
+  static findOwner(vantage, scopeName) {
+    let node = vantage;
     while (node !== undefined) {
-      if (node.name === scope)
+      if (node.name === scopeName)
         return node;
       node = node.parent;
     }
     return;
   }
-  chainNames() {
+  static chainNames(vantage) {
     const names = [];
-    let node = this;
+    let node = vantage;
     while (node !== undefined) {
       names.push(node.name);
       node = node.parent;
     }
     return names;
   }
-  resolveWith(token, stack) {
+  resolveWith(token, vantage, stack) {
     if (stack.includes(token)) {
       throw new CircularDependencyError([...stack, token]);
     }
@@ -265,65 +232,68 @@ class Scope {
     if (registration.scope === undefined) {
       stack.push(token);
       try {
-        return this.instantiate(token, registration, this, stack);
+        return this.instantiate(token, registration, vantage, stack);
       } finally {
         stack.pop();
       }
     }
-    const owner = this.findOwner(registration.scope);
+    const owner = ServiceProvider.findOwner(vantage, registration.scope);
     if (owner === undefined) {
-      throw new MissingScopeError(token, registration.scope, this.chainNames());
+      throw new MissingScopeError(token, registration.scope, ServiceProvider.chainNames(vantage));
     }
-    if (owner.instances.has(token)) {
-      return owner.instances.get(token);
+    if (owner.cache.has(token)) {
+      return owner.cache.get(token);
     }
     stack.push(token);
     try {
-      const instance = owner.instantiate(token, registration, owner, stack);
-      owner.instances.set(token, instance);
-      owner.ownedOrder.push(instance);
+      const instance = this.instantiate(token, registration, owner, stack);
+      owner.cache.set(token, instance);
+      owner.owned.push(instance);
       return instance;
     } finally {
       stack.pop();
     }
   }
-  instantiate(token, registration, owningScope, stack) {
+  instantiate(token, registration, owningFrame, stack) {
     if (registration.kind === "factory") {
-      return owningScope.invokeFactory(token, registration.factory, stack);
+      return this.invokeFactory(token, registration.factory, owningFrame, stack);
     }
-    return owningScope.construct(token, registration.ctor, stack);
+    return this.construct(token, registration.ctor, owningFrame, stack);
   }
-  makeScopeView(stack) {
-    const owner = this;
-    const view = {
+  makeProviderView(owningFrame, stack) {
+    const sp = this;
+    return {
       resolve: (depToken) => {
         if (depToken === undefined) {
           throw new TypeError("resolve<T>() requires the @fnioc/transformer plugin (no token at " + "runtime).");
         }
-        return owner.resolveWith(depToken, stack);
+        return sp.resolveWith(depToken, owningFrame, stack);
       },
-      resolveFactory: (depToken) => owner.makeFactory({ factory: depToken }),
-      createScope: (name) => owner.createScope(name)
+      resolveFactory: (depToken) => sp.makeFactory({ factory: depToken }, owningFrame),
+      createScope: (...args) => {
+        const name = args[0] ?? "scoped";
+        const childFrame = new Scope(name, owningFrame);
+        return new ServiceProvider(sp.registrations, childFrame);
+      }
     };
-    return view;
   }
-  invokeFactory(token, factory, stack) {
-    const scopeView = this.makeScopeView(stack);
+  invokeFactory(token, factory, owningFrame, stack) {
+    const providerView = this.makeProviderView(owningFrame, stack);
     const record = getDeps(factory);
     if (record === undefined || record.signatures.length === 0) {
-      return factory(scopeView);
+      return factory(providerView);
     }
-    const signature2 = this.selectSignature(token, factory.name, record.signatures);
+    const signature2 = this.selectSignature(token, factory.name, record.signatures, owningFrame);
     const args = signature2.map((slot) => {
       if (isScopeRef2(slot))
-        return scopeView;
+        return providerView;
       if (isFactoryRef2(slot))
-        return this.makeFactory(slot);
-      return this.resolveWith(slot, stack);
+        return this.makeFactory(slot, owningFrame);
+      return this.resolveWith(slot, owningFrame, stack);
     });
     return factory(...args);
   }
-  construct(token, ctor, stack) {
+  construct(token, ctor, owningFrame, stack) {
     const record = getDeps(ctor);
     if (record === undefined || record.signatures.length === 0) {
       if (ctor.length > 0) {
@@ -331,52 +301,54 @@ class Scope {
       }
       return new ctor;
     }
-    const signature2 = this.selectSignature(token, ctor.name, record.signatures);
+    const signature2 = this.selectSignature(token, ctor.name, record.signatures, owningFrame);
+    const providerView = this.makeProviderView(owningFrame, stack);
     const args = signature2.map((slot) => {
       if (isScopeRef2(slot)) {
-        return this.makeScopeView(stack);
+        return providerView;
       }
       if (isFactoryRef2(slot)) {
-        return this.makeFactory(slot);
+        return this.makeFactory(slot, owningFrame);
       }
-      return this.resolveWith(slot, stack);
+      return this.resolveWith(slot, owningFrame, stack);
     });
     return new ctor(...args);
   }
-  makeFactory(ref) {
-    const owningScope = this;
+  makeFactory(ref, owningFrame) {
+    const sp = this;
     const target = this.lookup(ref.factory);
     if (target === undefined) {
       throw new FactoryTargetError(ref.factory, "unregistered");
     }
     if (target.kind === "value") {
-      return () => owningScope.resolveWith(ref.factory, []);
+      return () => sp.resolveWith(ref.factory, owningFrame, []);
     }
     const depTarget = target.kind === "class" ? target.ctor : target.factory;
     const record = getDeps(depTarget);
-    const targetSignature = record === undefined || record.signatures.length === 0 ? undefined : owningScope.selectTargetSignature(record.signatures);
-    const parameterized = targetSignature !== undefined && targetSignature.some((slot) => !isFactoryRef2(slot) && !isScopeRef2(slot) && !owningScope.isResolvable(slot));
+    const targetSignature = record === undefined || record.signatures.length === 0 ? undefined : sp.selectTargetSignature(record.signatures);
+    const parameterized = targetSignature !== undefined && targetSignature.some((slot) => !isFactoryRef2(slot) && !isScopeRef2(slot) && !sp.isResolvable(slot));
     if (!parameterized) {
-      return () => owningScope.resolveWith(ref.factory, []);
+      return () => sp.resolveWith(ref.factory, owningFrame, []);
     }
-    return (...callArgs) => owningScope.buildPartitioned(target, targetSignature, callArgs);
+    return (...callArgs) => sp.buildPartitioned(target, targetSignature, callArgs, owningFrame);
   }
-  buildPartitioned(target, signature2, callerArgs) {
+  buildPartitioned(target, signature2, callerArgs, owningFrame) {
     const stack = [];
+    const providerView = this.makeProviderView(owningFrame, stack);
     let nextCallerArg = 0;
     const args = signature2.map((slot) => {
       if (isScopeRef2(slot))
-        return this.makeScopeView(stack);
+        return providerView;
       if (isFactoryRef2(slot))
-        return this.makeFactory(slot);
+        return this.makeFactory(slot, owningFrame);
       if (!this.isResolvable(slot)) {
         return callerArgs[nextCallerArg++];
       }
-      return this.resolveWith(slot, stack);
+      return this.resolveWith(slot, owningFrame, stack);
     });
     return target.kind === "class" ? new target.ctor(...args) : target.factory(...args);
   }
-  selectSignature(token, targetName, signatures) {
+  selectSignature(token, targetName, signatures, _owningFrame) {
     const ordered = signatures.map((sig, index) => ({ sig, index })).sort((a, b) => b.sig.length !== a.sig.length ? b.sig.length - a.sig.length : a.index - b.index);
     const unsatisfiable = new Set;
     for (const { sig } of ordered) {
@@ -404,14 +376,15 @@ class Scope {
   dispose() {
     if (this.disposed)
       return;
-    for (const instance of this.ownedOrder) {
+    const owned = this.frame?.owned ?? [];
+    for (const instance of owned) {
       if (isThenable(instance)) {
         throw new AsyncDisposalRequiredError;
       }
     }
     this.disposed = true;
-    for (let i = this.ownedOrder.length - 1;i >= 0; i--) {
-      const instance = this.ownedOrder[i];
+    for (let i = owned.length - 1;i >= 0; i--) {
+      const instance = owned[i];
       if (isDisposable(instance)) {
         instance[Symbol.dispose]();
       }
@@ -422,8 +395,9 @@ class Scope {
     if (this.disposed)
       return;
     this.disposed = true;
+    const owned = this.frame?.owned ?? [];
     const settled = [];
-    for (const instance of this.ownedOrder) {
+    for (const instance of owned) {
       settled.push(isThenable(instance) ? await instance : instance);
     }
     for (let i = settled.length - 1;i >= 0; i--) {
@@ -437,8 +411,10 @@ class Scope {
     this.clear();
   }
   clear() {
-    this.instances.clear();
-    this.ownedOrder.length = 0;
+    if (this.frame) {
+      this.frame.cache.clear();
+      this.frame.owned.length = 0;
+    }
   }
   [Symbol.dispose]() {
     this.dispose();
@@ -500,7 +476,13 @@ class DiBuilder {
     this.append(token, { kind: "value", useValue: value });
   }
   build() {
-    return new Scope(this.rootName, undefined, this.registrations);
+    const sealed = new Map;
+    for (const [token, list] of this.registrations) {
+      sealed.set(token, Object.freeze([...list]));
+    }
+    Object.freeze(sealed);
+    const rootFrame = new Scope(this.rootName);
+    return new ServiceProvider(sealed, rootFrame);
   }
 }
 export {
@@ -509,6 +491,7 @@ export {
   forCtor,
   defineDeps,
   UnregisteredTokenError,
+  ServiceProvider,
   Scope,
   NoSatisfiableSignatureError,
   MissingScopeError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fnioc/di",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "The ioc runtime engine: DiBuilder, scopes, resolution, captive-dependency protection, factories, and native disposal.",
   "keywords": [
     "dependency-injection",