@rhombus-std/di.core 0.0.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,775 @@
+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;
+}
+
+/**
+ * Anything a dependency signature can describe: a class constructor (its deps
+ * are the ctor parameters) or a factory function (its deps are the call
+ * parameters). The `never[]` rest keeps any concrete function assignable here
+ * regardless of its own parameter list.
+ */
+type DepTarget = Ctor | Func<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 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 type: Token;
+    readonly params?: readonly Token[];
+}
+/**
+ * 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[];
+}
+/**
+ * A SINGULAR (non-union) type that supplies its value directly — no container
+ * lookup. Emitted for:
+ *   - a non-union literal param (`"dev"`, `42`, `true`, `1n`) → its value, and
+ *   - a whole-type `void` / `undefined` → `undefined`; a whole-type `null` →
+ *     `null` (a singleton type has exactly one inhabitant, so it is supplied
+ *     directly, NOT tokenized — Rule 2).
+ * The engine injects `value` verbatim. A LITERAL/typed UNION (`"a" | "b"`,
+ * `Foo | undefined`) is NOT a `LiteralRef`: a literal union stays a resolved
+ * token, and a nullish union is stripped by the optional/overload path. Always
+ * satisfiable — the value is self-supplying.
+ *
+ * NOTE: `value` may legitimately be `undefined` (the `void`/`undefined` case),
+ * so a `LiteralRef` is identified by the PRESENCE of the `value` key, never by
+ * `value !== undefined`. See `isLiteralRef`.
+ */
+interface LiteralRef {
+    readonly value: string | number | boolean | bigint | undefined | null;
+}
+/**
+ * Marks a parameter to be injected with the TOKEN STRING of one of the
+ * registration's type arguments — the `typeof(T)` analog for open-generic
+ * templates. `typeArg` is the 1-based hole number (`{ typeArg: 1 }` names the
+ * argument bound to `$1`). At close time, substitution replaces the slot with
+ * a `LiteralRef` carrying the substituted argument's token string; a raw
+ * (unsubstituted) `TypeArgRef` reaching resolution is an error.
+ */
+interface TypeArgRef {
+    readonly typeArg: number;
+}
+/**
+ * One positional slot in a constructor / factory signature:
+ *   - a `Token` string  — a container-resolved dependency (a plain `Resolver`
+ *     token resolves to the live provider view — see `RESOLVER_TOKEN`),
+ *   - a `FactoryRef`    — a factory-injected parameter (see `FactoryRef`),
+ *   - a `Union`         — member-level alternatives tried in order,
+ *   - a `LiteralRef`    — a singular literal supplying its value directly, or
+ *   - a `TypeArgRef`    — the token string of a type argument (see `TypeArgRef`).
+ */
+type DepSlot = Token | FactoryRef | Union | LiteralRef | TypeArgRef;
+/**
+ * Per-constructor dependency metadata carried on a registration.
+ *
+ * `signatures` is an array of arrays: each element is one constructor signature
+ * (for overload support). `signatures[i][j]` is the `DepSlot` — a token, a
+ * `FactoryRef`, a `Union`, or a `LiteralRef` — for constructor parameter `j` of
+ * overload `i`.
+ */
+interface DepRecord {
+    readonly signatures: readonly (readonly DepSlot[])[];
+}
+/**
+ * The result of parsing a closed-generic token `base<arg1,arg2>` into its base
+ * and top-level args. A pure data shape (the parse routine that produces it is a
+ * runtime helper that lives in `@rhombus-std/di`); kept here so the type surface a
+ * consumer references stays in the types-only substrate.
+ */
+interface ParsedToken {
+    readonly base: Token;
+    readonly args: readonly Token[];
+}
+
+/**
+ * Compile-time phantom brand that pins a specific token for one constructor or
+ * factory parameter, overriding the token the transformer would normally derive.
+ *
+ * The value type stays `T` — a plain `T` is assignable because the brand
+ * property is optional. Zero runtime footprint.
+ *
+ * @example
+ * ```ts
+ * class Handler {
+ *   constructor(
+ *     cache: Inject<ICache, "pkg:redis-cache">,  // pinned token
+ *     log: ILogger,                              // derived normally
+ *   ) {}
+ * }
+ * ```
+ */
+declare const TOK: unique symbol;
+type Inject<T, K extends Token> = T & {
+    readonly [TOK]?: K;
+};
+/**
+ * Compile-time skolem standing in for the `N`th type argument of an open
+ * template (1-based). Writing `add<IRepository<$<1>>>(SqlRepository<$<1>>)` binds
+ * the hole; the transformer derives `$N` wherever a Hole-branded type appears.
+ *
+ * `C` is the constraint carrier: `Hole<1, Entity>` IS an `Entity` (the brand
+ * property is optional, so the intersection stays assignable to `C`), which
+ * lets a constrained implementation `class Repo<T extends Entity>` accept a
+ * hole as its type argument. Zero runtime footprint.
+ */
+declare const HOLE: unique symbol;
+type Hole<N extends number, C = unknown> = C & {
+    readonly [HOLE]?: N;
+};
+/**
+ * Unbounded sugar for the common unconstrained hole: `$<1>`, `$<2>`, … `$<N>`.
+ * `$<N>` is exactly `Hole<N>`; reach for `Hole<N, C>` when the impl's type
+ * parameter carries a constraint the skolem must satisfy.
+ */
+type $<N extends number> = Hole<N>;
+/**
+ * Compile-time phantom brand marking a constructor parameter that receives the
+ * TOKEN STRING of type argument `T` — the `typeof(T)` analog (hence the name).
+ * The value type stays `Token` (a plain string is assignable; the brand
+ * property is optional).
+ *
+ * `Typeof<T>` is type-driven: the transformer infers the hole from `T`. The
+ * manual counterpart `typeArg(n)` is positional — a plugin-less author names
+ * the hole by number.
+ *
+ * When `T` is a Hole, the transformer emits an open `{ typeArg: N }` slot that
+ * substitution closes per registration; when `T` is concrete, it emits the
+ * derived token directly as a literal value slot. Zero runtime footprint.
+ *
+ * @example
+ * ```ts
+ * class SqlRepository<T> {
+ *   constructor(readonly entityToken: Typeof<T>) {}
+ * }
+ * ```
+ */
+declare const ARG: unique symbol;
+type Typeof<T> = Token & {
+    readonly [ARG]?: T;
+};
+
+/**
+ * ONE overload's own non-call properties, carried across the peeling recursion so
+ * a callable-with-statics keeps them. `Pick<T, keyof T>` is `{}` for a bare
+ * function type and the static side for a constructor type.
+ */
+type OverloadProps<T> = Pick<T, keyof T>;
+/**
+ * Peel an intersection of call signatures (an overloaded function type) into a
+ * UNION of its individual signatures. The technique (Vojtěch Mašek / type-fest):
+ * `infer` matches the LAST signature and emits it, then recurses with the
+ * accumulator intersected back in so the next match resolves to the PRECEDING
+ * overload. Bounded — each step strips one signature, terminating once the
+ * accumulator already subsumes the whole overload set (`TAccumulator extends
+ * TOverload`).
+ */
+type OverloadUnionRecursive<TOverload, TAccumulator = unknown> = TOverload extends (...args: infer TArgs) => infer TReturn ? TAccumulator extends TOverload ? never : OverloadUnionRecursive<TAccumulator & TOverload, TAccumulator & ((...args: TArgs) => TReturn) & OverloadProps<TOverload>> | ((...args: TArgs) => TReturn) : never;
+/**
+ * The UNION of a function type's individual call-signature overloads. Seeds the
+ * recursion with a `() => never` overload hoisted to the FRONT of the
+ * intersection (required for the bounded recursion to fire), then excludes that
+ * sentinel from the result unless `T` genuinely is `() => never`.
+ */
+type OverloadUnion<T extends (...args: any[]) => any> = Exclude<OverloadUnionRecursive<(() => never) & T>, T extends () => never ? never : () => never>;
+/**
+ * Every overload's parameter tuple for a function type `T`, as a union — the
+ * overload-faithful analog of the builtin `Parameters<T>`. For a `T` with
+ * signatures `(a: A)` and `(a: B, b: C)` this is `[a: A] | [a: B, b: C]`; a
+ * single-overload function yields its one tuple.
+ */
+type OverloadedParameters<T extends (...args: any[]) => any> = Parameters<OverloadUnion<T>>;
+/** The construct-signature counterpart of {@link OverloadProps} — the static side. */
+type ConstructorOverloadProps<T> = Pick<T, keyof T>;
+/**
+ * The construct-signature counterpart of {@link OverloadUnionRecursive}: peels an
+ * intersection of CONSTRUCT signatures (an overloaded constructor type) into a
+ * union of its individual signatures. A concrete `new` is used, NOT `abstract
+ * new`: intersecting an abstract construct signature with a concrete class's
+ * `new` signatures derails overload inference (it collapses to `any`), and the
+ * sole consumer — a factory that does `new C(...args)` — needs a concrete
+ * constructor anyway.
+ */
+type ConstructorOverloadUnionRecursive<TOverload, TAccumulator = unknown> = TOverload extends new (...args: infer TArgs) => infer TReturn ? TAccumulator extends TOverload ? never : ConstructorOverloadUnionRecursive<TAccumulator & TOverload, TAccumulator & (new (...args: TArgs) => TReturn) & ConstructorOverloadProps<TOverload>> | (new (...args: TArgs) => TReturn) : never;
+/** The construct-signature counterpart of {@link OverloadUnion}. */
+type ConstructorOverloadUnion<T extends new (...args: any[]) => any> = Exclude<ConstructorOverloadUnionRecursive<(new () => never) & T>, T extends new () => never ? never : new () => never>;
+/**
+ * Every construct-overload's parameter tuple for a constructor type `T`, as a
+ * union — the overload-faithful analog of the builtin `ConstructorParameters<T>`.
+ * For a `C` with constructors `(a: A)` and `(a: B, b: C)`,
+ * `OverloadedConstructorParameters<typeof C>` is `[a: A] | [a: B, b: C]`; a
+ * single-overload ctor yields its one tuple and a zero-arg ctor yields `[]`.
+ * Constrained to a concrete (`new`-able) constructor — an abstract class has no
+ * constructible instance, and the factory that consumes this must `new` its
+ * argument.
+ */
+type OverloadedConstructorParameters<T extends new (...args: any[]) => any> = ConstructorParameters<ConstructorOverloadUnion<T>>;
+
+/**
+ * The continuation returned by a class `ServiceManifest.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 guard at the registration site. The authored type-arg form
+ * `.as<"scope">()` is DECLARATION-MERGED onto this interface by the
+ * `@rhombus-std/di.transformer` augmentation — a pure typing that surfaces only
+ * when the transformer is in the program.
+ */
+interface AddBuilder<Scopes extends string> {
+    /**
+     * Attaches the lifetime — the RUNTIME (lowered) form. Must name a declared
+     * scope.
+     *
+     * `.as("singleton")` is what the engine executes: the transformer rewrites the
+     * authored type-arg form (`.as<"singleton">()`) to this value-arg form before
+     * runtime, and a plugin-less caller writes it directly. The AUTHORED type-arg
+     * form (`.as<S extends Scopes>(): void`) is a PURE TYPING contributed by the
+     * `@rhombus-std/di.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 AUTHORING INTERFACE for the registration collection — the base surface a
+ * lib author types a setup function against, and the interface the concrete
+ * `ServiceManifestClass` (in this same package) implements. It names the three
+ * runtime registration methods (`add` / `addFactory` / `addValue`) plus `build`.
+ *
+ * It is also the interface-first public surface a di consumer holds: di's public
+ * `ServiceManifest` type is `ServiceManifestBase<S, ServiceProvider<S>>` (not the
+ * impl class), so the type-driven authoring forms (`add<I>(C)`, `addFactory<I>(fn)`,
+ * `addValue<I>(v)`) the `@rhombus-std/di.transformer` DECLARATION-MERGES onto this
+ * interface surface on a consumer's `services.add<I>(...)`. An interface picks up
+ * those merged overloads; the impl class would not — the same reason the provider
+ * surface is an interface.
+ *
+ * `Provider` is the type `build()` returns. A core-only lib author never calls
+ * `build()` (the application does), so it defaults to `unknown`; `@rhombus-std/di`
+ * binds it to the concrete `ServiceProvider<Scopes>` when its class implements
+ * this interface. Keeping it generic is what lets this interface live in the
+ * types-only substrate without referencing di's runtime provider type.
+ */
+interface ServiceManifestBase<Scopes extends string = "singleton", Provider = unknown> {
+    /**
+     * Class registration — a string token bound to a concrete constructor. The
+     * optional third `signatures` arg carries the positional dep signatures ON the
+     * registration (a lib author authors them as plain `DepSlot` data literals).
+     */
+    add(token: Token, ctor: Ctor, signatures?: readonly (readonly DepSlot[])[]): AddBuilder<Scopes>;
+    /**
+     * Factory registration — a string token bound to a factory function, its call
+     * parameters injected by the optional third `signatures` arg.
+     */
+    addFactory(token: Token, factory: Func<any[], unknown>, signatures?: readonly (readonly DepSlot[])[]): AddBuilder<Scopes>;
+    /** Value registration — an already-built instance, no deps and no lifetime. */
+    addValue(token: Token, value: unknown): void;
+    /** Seals the collection and returns the built provider. */
+    build(): Provider;
+}
+
+/**
+ * The minimal resolution surface — resolve tokens and get factories. A factory
+ * (or ctor) parameter typed `Resolver` is injected with the live provider view:
+ * the type derives the intrinsic provider token (`RESOLVER_TOKEN`), which the
+ * engine resolves to the view relative to the resolving frame — "I want the
+ * provider" is plain DI, no dedicated slot kind.
+ *
+ * `resolve` has two published shapes here; the tokenless authoring form
+ * `resolve<T>()` (and the factory form `resolve<F>()`) is a PURE TYPING the
+ * `@rhombus-std/di.transformer` DECLARATION-MERGES onto THIS interface (via
+ * `declare module "@rhombus-std/di.core"`), so it lights up only when the
+ * transformer is in the TypeScript program. Merging onto the interface (rather
+ * than a separate carrier) is what lets both a factory parameter typed `Resolver`
+ * AND the `ServiceProvider` interface a consumer holds pick up the authored form
+ * — an interface inherits a base interface's merged overloads; a class would not,
+ * which is exactly why the public provider surface is this interface, not the
+ * impl class.
+ *   - `resolve<T>(token)`   — explicit token, typed return.
+ *   - `resolve(token)`      — explicit token, `unknown` return (dynamic).
+ */
+interface Resolver {
+    resolve<T>(token: Token): T;
+    resolve(token: Token): unknown;
+    /**
+     * Resolves asynchronously — the only path that may satisfy `T` via a
+     * `Promise<T>` registration. Always returns a Promise; a lookup miss whose
+     * honest `Promise<T>` registration exists is awaited and delivers `T`.
+     */
+    resolveAsync<T>(token: Token): Promise<T>;
+    resolveAsync(token: Token): Promise<unknown>;
+    /**
+     * Non-throwing resolve — returns the resolved instance, or `undefined` when
+     * `token` is UNREGISTERED. Mirrors the reference DI's nullable `GetService<T>`
+     * against `resolve`'s throwing `GetRequiredService` (#25). A bare nullable, not
+     * a tuple: a resolved service is always a truthy instance, so `undefined`
+     * unambiguously means "not registered".
+     *
+     * Only an unregistered TOKEN yields `undefined`. A registered token whose
+     * construction fails for another reason (a missing dependency, a cycle, an
+     * async-only construction) throws exactly as `resolve` would — `tryResolve`
+     * softens the "is it registered?" miss, nothing else.
+     *
+     * The tokenless authoring form `tryResolve<T>()` is the pure typing the
+     * `@rhombus-std/di.transformer` DECLARATION-MERGES onto this interface.
+     *   - `tryResolve<T>(token)` — explicit token, typed nullable return.
+     *   - `tryResolve(token)`    — explicit token, `unknown` return (dynamic).
+     */
+    tryResolve<T>(token: Token): T | undefined;
+    tryResolve(token: Token): unknown;
+    /**
+     * A token-based registration predicate — `true` when `token` would resolve
+     * (a registration exists, directly or via an open-generic closing), `false`
+     * otherwise. Mirrors the reference DI's `IServiceProviderIsService.IsService`
+     * (#23); being token-based, it also covers the keyed case in one method. Does
+     * NOT attempt construction — a registered token whose dependencies are missing
+     * still reports `true` (it IS a service; building it is a separate concern).
+     *
+     * The tokenless authoring form `isService<T>()` is the pure typing the
+     * `@rhombus-std/di.transformer` DECLARATION-MERGES onto this interface.
+     */
+    isService(token: Token): boolean;
+    /**
+     * 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(type: Token, params?: readonly Token[]): unknown;
+}
+/**
+ * The scope-creation surface. Injected into factory parameters typed
+ * `ScopeFactory`, and implemented by the provider impl. `createScope` returns
+ * the `ServiceProvider` INTERFACE (the abstractions seam), never the impl class.
+ */
+interface ScopeFactory<S extends string = string> {
+    createScope(...args: "scoped" extends S ? [name?: S] : [name: S]): ServiceProvider<S>;
+}
+/**
+ * The PUBLIC container surface a consumer holds — the abstractions seam mirroring
+ * MEDI's `IServiceProvider`. Composes the resolution surface (`Resolver`, which
+ * carries the tokenless authoring forms via `ResolverAuthoring`), scope creation
+ * (`ScopeFactory`), and native `Disposable` / `AsyncDisposable`. The concrete
+ * `ServiceProviderClass` in `@rhombus-std/di` implements this; `build()` and
+ * `createScope()` return it rather than the class so consumers program against
+ * the interface.
+ *
+ * `S` is the user-declared scope-name union.
+ */
+interface ServiceProvider<S extends string = string> extends Resolver, ScopeFactory<S>, Disposable, AsyncDisposable {
+    /**
+     * The name of this provider's open scope frame. Throws if the provider is
+     * frameless (no scope open — e.g. the provider straight from `build()`).
+     */
+    readonly name: S;
+    /**
+     * Closes this provider synchronously, disposing the instances its scope frame
+     * owns in reverse construction order. Throws `AsyncDisposalRequiredError` if an
+     * owned instance is a pending Promise. Idempotent.
+     */
+    dispose(): void;
+    /**
+     * Closes this provider asynchronously, awaiting owned Promise-valued instances
+     * before disposing them in reverse construction order. Idempotent.
+     */
+    disposeAsync(): Promise<void>;
+}
+/**
+ * @deprecated Use `Resolver` instead. Kept for backwards compatibility.
+ *
+ * The resolution surface a factory receives when it declares a provider-typed
+ * parameter. Like `Resolver`, its token is intrinsic — the engine fills the
+ * parameter with the live provider view — with `createScope` added.
+ */
+interface ResolveScope extends Resolver {
+    createScope(name: string): ServiceProvider;
+}
+/**
+ * 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;
+
+/**
+ * A registration-level factory function. Its parameters are filled by the
+ * engine at resolve time, the same way a class constructor's are: each parameter
+ * is resolved by its slot (token → resolved instance, provider token → the live
+ * provider view, hole → caller-supplied). A factory with no signatures runs with
+ * no injected args — it declares the deps it wants, nothing is auto-supplied.
+ *
+ * May be async — it can return a `Promise<T>`. The container never awaits; the
+ * Promise flows through the sync resolution channel as a value (§"Async as
+ * values"). A consumer that depends on it declares `Promise<T>` and awaits.
+ */
+type Factory = Func<any[], unknown>;
+/**
+ * Builds an instance from its resolved positional args. The single normalized
+ * form the three authoring kinds collapse into at registration time:
+ *   - class   → `(...a) => new Ctor(...a)`
+ *   - value   → `() => value`
+ *   - factory → the factory function itself
+ */
+type Producer = Func<any[], unknown>;
+/**
+ * A single normalized registration — ONE "producer" shape for all three
+ * authoring kinds (class / value / factory). The builder wraps each into a
+ * `produce` closure at registration time (see `Producer`); the engine dispatches
+ * on this one shape, calling `produce(...args)` uniformly rather than switching
+ * on a `kind` discriminant.
+ */
+interface Registration {
+    /** Builds the instance from the resolved positional args (see `Producer`). */
+    readonly produce: Producer;
+    /**
+     * The lifetime — the scope name that owns and caches the instance. `undefined`
+     * means transient (never cached; produced fresh per resolve). A value is
+     * always transient: a value IS its instance, so ownership/caching is moot and
+     * a value that is itself a `Promise` is returned raw, never awaited.
+     */
+    readonly scope: string | undefined;
+    /**
+     * Registration-carried dep signatures — the positional slots that feed
+     * `produce`, and the sole signature channel now that the global metadata store
+     * is retired. Emitted inline by the transformer (`add`/`addFactory` third arg)
+     * and hand-fed by a plugin-less caller. Absent or empty means `produce` takes
+     * no injected args (a zero-arg ctor, a value, or a signature-less factory).
+     */
+    readonly signatures?: readonly (readonly DepSlot[])[];
+    /**
+     * The producer's diagnostic name — the ctor / factory name, carried EXPLICITLY
+     * because a wrapper closure (`(...a) => new Ctor(...a)`) reports `""` for its
+     * own `.name`. Empty string for a value. Feeds the `MissingMetadataError` /
+     * `NoSatisfiableSignatureError` diagnostics.
+     */
+    readonly name: string;
+    /**
+     * The original constructor arity (`Ctor.length`), carried EXPLICITLY because a
+     * rest-param wrapper reports `0` for its own `.length`. Drives the
+     * missing-metadata signal: a signature-less producer whose `arity` is nonzero
+     * (a class ctor that needs args) throws `MissingMetadataError`. `0` for a value
+     * or a factory — a signature-less factory simply runs with no injected args.
+     */
+    readonly arity: number;
+}
+/**
+ * An OPEN registration — a class bound to an open template token whose type
+ * arguments are all holes (`pkg:IRepo<$1>`). It never resolves directly;
+ * resolving a closed token that misses the exact map matches against these
+ * (base + arity + repeated-hole equality, last registered wins), substitutes
+ * the closing's arg tokens through the carried signatures, and synthesizes an
+ * ordinary class `Registration` (a ctor-wrapping producer) memoized per closed
+ * token.
+ */
+interface OpenRegistration {
+    /** The full template token as registered (`pkg:IRepo<$1>`). */
+    readonly template: Token;
+    /** The template's base (`pkg:IRepo`) — the open-table key. */
+    readonly base: Token;
+    /**
+     * The parsed top-level args of the template — each exactly a hole (`$N`).
+     * Length is the arity; repeated holes (`["$1","$1"]`) constrain a match to
+     * equal arg tokens.
+     */
+    readonly pattern: readonly Token[];
+    readonly ctor: Ctor;
+    /** The lifetime tag, applied per closing. `undefined` means transient. */
+    readonly scope: string | undefined;
+    /**
+     * The template dep signatures (holes and `TypeArgRef`s still open) —
+     * substituted per closing. When absent, the closing has no template to
+     * substitute (a zero-arg ctor closes to a bare `new Ctor()`).
+     */
+    readonly signatures?: readonly (readonly DepSlot[])[];
+}
+/**
+ * The sealed, immutable snapshot a `ServiceManifestClass` hands to the engine.
+ * `ServiceManifestClass.seal()` deep-freezes its registration tables into this
+ * shape; `@rhombus-std/di`'s `build()` extension reads it to construct the
+ * provider (the engine-constructing half stays in the runtime package). This is
+ * the seam that lets the collection live in di.core while provider construction
+ * lives in di.
+ */
+interface SealedManifest {
+    readonly registrations: ReadonlyMap<Token, readonly Registration[]>;
+    readonly openRegistrations: ReadonlyMap<Token, readonly OpenRegistration[]>;
+}
+
+/**
+ * The registration builder.
+ *
+ * `Scopes` is the union of declarable scope names — the tags `.as()` and
+ * `.createScope()` accept (default `"singleton"`). There is no root: scopes are
+ * uniform tags, and `"singleton"` is just a tag you happen to open once at the
+ * top. `"transient"` is NOT a member — transient is the absence of a scope, not
+ * a scope. A registration whose tagged scope is not open at resolution time
+ * resolves transiently (fresh instance, no cache).
+ *
+ * @example
+ * ```ts
+ * const services = new ServiceManifest<"singleton" | "request">();
+ * services.add("pkg:ILogger", ConsoleLogger).as("singleton"); // lowered form
+ * const provider = services.build();              // no frame pre-opened
+ * const app = provider.createScope("singleton");  // open the singleton frame
+ * const logger = app.resolve<ILogger>("pkg:ILogger");
+ * const req = app.createScope("request");         // nested child scope
+ * ```
+ *
+ * NOTE: this is the IMPLEMENTATION class. The public `ServiceManifest` TYPE
+ * (below) is the interface consumers hold; the public `ServiceManifest` VALUE
+ * (`new ServiceManifest<S>()`) lives in `@rhombus-std/di`, which also patches
+ * `build()` onto this prototype. The class is exported so cross-package fluent
+ * augmentations can prototype-patch it (their authored typings merge onto the
+ * di.core interfaces, never onto this class directly).
+ */
+declare class ServiceManifestClass<Scopes extends string = "singleton"> implements ServiceManifestBase<Scopes, ServiceProvider<Scopes>> {
+    #private;
+    constructor();
+    /**
+     * 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.
+     *
+     * The optional third `signatures` param carries the dep signatures ON the
+     * registration record — the sole signature channel now that the global
+     * metadata store is retired. The transformer emits it inline for every
+     * constructed class (`add(token, ctor, [[...]])`); a plugin-less caller
+     * hand-feeds it directly. Keying signatures on the registration (not on the
+     * ctor object) is what lets one JS class close differently per registration —
+     * an open template and its closings never collide.
+     *
+     * An OPEN template token (`pkg:IRepo<$1>` — every type arg a hole) routes
+     * into the open-registration table instead of the exact map; resolution
+     * closes it per requested token. Mixing concrete args and holes in the
+     * service token throws (v1 all-holes rule).
+     */
+    add(token: Token, ctor: Ctor, signatures?: readonly (readonly DepSlot[])[]): AddBuilder<Scopes>;
+    /**
+     * Factory registration — a string token bound to a factory function. The
+     * runtime form the transformer emits for an authored `add<I>(fn)` /
+     * `addFactory<I>(fn)`, and what a plugin-less caller writes directly.
+     *
+     * Parameter injection follows the metadata rule (see `ServiceProvider`): each
+     * parameter is injected by its slot from the registration-carried signatures
+     * (the optional third arg, emitted inline by the transformer). A factory that
+     * wants the live provider declares it as an ordinary parameter (a provider-typed
+     * slot); a signature-less factory simply runs with no injected args — nothing is
+     * auto-supplied. Returns the `.as(scope?)` continuation so a factory caches at a
+     * named scope exactly like a class.
+     *
+     * The implementation signature admits the single-arg authoring form
+     * (`addFactory<I>(fn)`) so the `@rhombus-std/di.transformer` overload merges onto it —
+     * that form never runs post-transform, and the runtime guard below fails a
+     * plugin-less call loud rather than registering junk (mirrors `add`).
+     */
+    addFactory(token: Token, factory: Factory, signatures?: readonly (readonly DepSlot[])[]): AddBuilder<Scopes>;
+    /**
+     * Value registration — an already-built instance, no deps and no lifetime.
+     * Separate from `add` because a value may itself be a function (a callable
+     * service), which is structurally indistinguishable from a factory inside one
+     * overload. The authoring form `addValue<I>(v)` (which lowers to
+     * `addValue("token", v)`) is a PURE TYPING contributed by the
+     * `@rhombus-std/di.transformer` augmentation, not part of di's published surface.
+     */
+    addValue(token: Token, value: unknown): void;
+    /**
+     * Seals the collection into an immutable snapshot — the SEALING half of
+     * `build()`. Deep-freezing the maps and each per-token list ensures that any
+     * `.add()` call on the builder after sealing cannot mutate what the provider
+     * and its descendants see — the container's view is fixed at build time.
+     *
+     * This is the collection's own concern, so it lives here in di.core. The
+     * ENGINE-CONSTRUCTING half — turning this snapshot into a `ServiceProvider` —
+     * is a `@rhombus-std/di` extension (`build()` below), because it needs the
+     * runtime resolution engine di.core deliberately does not depend on.
+     */
+    seal(): SealedManifest;
+    /**
+     * Seals the collection and returns the built `ServiceProvider`.
+     *
+     * The IMPLEMENTATION lives in `@rhombus-std/di`, not here — mirroring the
+     * reference DI split where the collection ships in the abstractions package
+     * but the provider-building entry is a runtime-package extension. Importing
+     * `@rhombus-std/di` PROTOTYPE-PATCHES this method onto `ServiceManifestClass`
+     * at load time (`services.seal()` → `new ServiceProviderClass(...)`), exactly
+     * how a cross-package fluent-authoring augmentation patches the concrete
+     * builder. The stub below is what runs if the runtime was never imported.
+     *
+     * NO frame is pre-opened: the returned provider is frameless. There is no
+     * root scope — resolving a tagged registration with no matching frame open
+     * yields a transient instance, and an untagged registration is transient as
+     * always. Open a scope explicitly with `createScope(name)` when you want a
+     * tagged registration to cache.
+     */
+    build(): ServiceProvider<Scopes>;
+}
+/**
+ * The public registration-builder INTERFACE a di consumer holds — the
+ * `ServiceManifestBase` interface bound to the concrete provider `build()`
+ * returns (the ME `IServiceCollection` analog). Interface-first (not the impl
+ * class) so the `@rhombus-std/di.transformer` augmentation — which merges the
+ * authored `add<I>()` / `.as<"scope">()` forms onto `ServiceManifestBase` —
+ * surfaces on a consumer typing against `ServiceManifest<S>`. A class would not
+ * inherit those augmented overloads; the interface does.
+ *
+ * The constructor side (`ServiceManifestCtor`) and the constructible
+ * `ServiceManifest` VALUE live in `@rhombus-std/di`, alongside the `build()`
+ * prototype-patch that makes `new ServiceManifest().build()` produce a provider.
+ */
+type ServiceManifest<S extends string = "singleton"> = ServiceManifestBase<S, ServiceProvider<S>>;
+
+/** True when `slot` is a `FactoryRef` (carries a `.type` token). */
+declare function isFactoryRef(slot: DepSlot): slot is FactoryRef;
+/** True when `slot` is a `Union` (carries a `.union` array of member slots). */
+declare function isUnionSlot(slot: DepSlot): slot is Union;
+/**
+ * True when `slot` is a `LiteralRef` — an object slot carrying a `value` key.
+ * The value supplies a singular literal directly (`"dev"`, `42`, `true`, `1n`)
+ * OR the lone inhabitant of `void` / `undefined` / `null`.
+ *
+ * Identified by the PRESENCE of the `value` key (`"value" in slot`), never by
+ * `value !== undefined` — `value` is legitimately `undefined` for the
+ * `void`/`undefined` case. No other slot kind (FactoryRef `.type`, Union
+ * `.union`) carries a `value` key, so this is unambiguous.
+ */
+declare function isLiteralRef(slot: DepSlot): slot is LiteralRef;
+/**
+ * True when `slot` is a `TypeArgRef` — an object slot carrying a numeric
+ * `typeArg` key (the 1-based hole number). Key-disjoint from every other slot
+ * kind (FactoryRef `.type`, Union `.union`, LiteralRef `.value`), so the check
+ * is unambiguous.
+ */
+declare function isTypeArgRef(slot: DepSlot): slot is TypeArgRef;
+
+/**
+ * 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
+ * services.add("pkg:IHandler", Handler, [[
+ *   union("pkg:IRedis", "pkg:IMemoryCache"),
+ *   "pkg:ILogger",
+ * ]]);
+ * ```
+ */
+declare function union(...slots: DepSlot[]): Union;
+/**
+ * Constructs a `TypeArgRef` slot — a parameter that receives the TOKEN STRING
+ * of the registration's `n`th type argument (1-based, matching `$n`). Used on
+ * the manual authoring surface for hole-template signatures; substitution
+ * closes it into a literal value slot per closing.
+ *
+ * @example
+ * ```ts
+ * services.add("app/IRepo<$1>", SqlRepository, [[typeArg(1), "app/IDb"]]);
+ * ```
+ */
+declare function typeArg(n: number): TypeArgRef;
+
+/**
+ * Renders the canonical closed-generic form `base<arg1,arg2>`. With no args,
+ * returns `base` unchanged. Args may themselves be closed-generic tokens
+ * (nesting) or holes (`$N` — producing an open template).
+ */
+declare function closeToken(base: Token, ...args: Token[]): Token;
+/**
+ * Parses a closed-generic token into its base and top-level args.
+ *
+ * Returns `undefined` for non-generic tokens (no top-level `<`) AND for
+ * malformed input (empty base, unbalanced brackets, empty arg, trailing text
+ * after the closing `>`, unterminated quote) — callers fall through to their
+ * exact-match / unregistered-token handling either way.
+ *
+ * The scan is depth-tracked over `<` / `>` and quote-aware for double quotes
+ * (backslash escapes honored), so literal-type args like `"a,b" | "<c>"` split
+ * correctly.
+ */
+declare function parseToken(token: Token): ParsedToken | undefined;
+/**
+ * True when `token` contains a hole (`$N`) at any depth — i.e. it is an open
+ * template rather than a resolvable token. Grammar-aware: a `$N` inside a
+ * quoted literal arg is NOT a hole.
+ */
+declare function isOpenToken(token: Token): boolean;
+/**
+ * Substitutes hole nodes in an open template with the supplied argument tokens
+ * (1-based: `$1` → `args[0]`). Grammar-aware and recursive — a node that is
+ * exactly `$N` is replaced by the arg token (which may itself be
+ * closed-generic); this is NOT a naive string replace, so a `$N` inside a
+ * quoted literal arg survives untouched.
+ *
+ * Throws `RangeError` when the template references a hole beyond the supplied
+ * args — callers match arity before substituting.
+ */
+declare function substituteToken(template: Token, args: readonly Token[]): Token;
+/**
+ * Substitutes the supplied argument tokens through every slot of every
+ * signature, producing the closed signatures for one closing of an open
+ * registration:
+ *   - a string token     → `substituteToken`,
+ *   - a `FactoryRef`     → `type` and each `params` token substituted,
+ *   - a `Union`          → members substituted recursively,
+ *   - a `TypeArgRef`     → a `LiteralRef` carrying `args[typeArg - 1]` (the
+ *                          substituted argument's token string),
+ *   - a `LiteralRef`     → unchanged.
+ */
+declare function substituteSignatures(signatures: readonly (readonly DepSlot[])[], args: readonly Token[]): readonly (readonly DepSlot[])[];
+
+/**
+ * The token a `Resolver`-typed parameter derives to. The engine resolves it to
+ * the live provider view (the scope-generic-free `Resolver` surface, per #24)
+ * relative to the resolving frame, rather than to a registration. Exported so a
+ * plugin-less author can hand-feed it in a signature (`[[RESOLVER_TOKEN]]`)
+ * without spelling the package-qualified string by hand.
+ */
+declare const RESOLVER_TOKEN: Token;
+/**
+ * True when `token` is an intrinsic provider token — one the engine resolves to
+ * the live provider view instead of a registration. Always satisfiable during
+ * signature selection, and reported as a service by `isService`.
+ */
+declare function isProviderToken(token: Token): boolean;
+
+/** Base class for every error the container raises. */
+declare class DiError extends Error {
+    constructor(message: string);
+}
+/**
+ * An open template token was passed to a registration method that cannot
+ * accept one: `addValue`/`addFactory` (open registrations are class-only), or
+ * `add` with a template whose type arguments are not ALL holes (v1 forbids
+ * mixing concrete args and holes in the service token).
+ */
+declare class OpenTokenRegistrationError extends DiError {
+    readonly token: Token;
+    readonly method: "add" | "addFactory" | "addValue";
+    constructor(token: Token, method: "add" | "addFactory" | "addValue");
+}
+
+export { DiError, OpenTokenRegistrationError, RESOLVER_TOKEN, ServiceManifestClass, closeToken, isFactoryRef, isLiteralRef, isOpenToken, isProviderToken, isTypeArgRef, isUnionSlot, parseToken, substituteSignatures, substituteToken, typeArg, union };
+export type { $, AddBuilder, Ctor, DepRecord, DepSlot, DepTarget, Factory, FactoryRef, Hole, Inject, Lifetime, LiteralRef, OpenRegistration, OverloadedConstructorParameters, OverloadedParameters, ParsedToken, Producer, Registration, ResolveScope, Resolver, ScopeFactory, SealedManifest, ServiceManifest, ServiceManifestBase, ServiceProvider, Token, TypeArgRef, Typeof, Union };