di-bag 0.2.0 → 0.3.0

package/dist/dependency-references.d.ts

@@ -7,13 +7,25 @@ declare class ReferenceBase {
 declare class DependencyHandle<T extends TokenBase, K extends 'optional' | 'lazy' | 'all'> extends ReferenceBase {
     readonly [referenceInvariant]: (value: [T, K]) => [T, K];
 }
-/** A positional dependency that yields the token service or `undefined` when unbound. */
+/**
+ * A positional dependency that yields the token service or `undefined` when unbound.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#declare-optional-and-lazy-dependencies
+ */
 export type OptionalDependency<T extends TokenBase> = DependencyHandle<T, 'optional'>;
-/** A positional dependency that yields all contributions for a token as a readonly array. */
+/**
+ * A positional dependency that yields all contributions for a token as a readonly array.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#compose-an-ordered-collection
+ */
 export type CollectionDependency<T extends TokenBase> = DependencyHandle<T, 'all'>;
-/** A positional dependency that yields a function which resolves the token on demand. */
+/**
+ * A positional dependency that yields a function which resolves the token on demand.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#declare-optional-and-lazy-dependencies
+ */
 export type LazyDependency<T extends TokenBase> = DependencyHandle<T, 'lazy'>;
-/** A typed token or one of the positional dependency-reference handles. */
+/**
+ * A typed token or one of the positional dependency-reference handles.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#adapt-classes-and-positional-functions
+ */
 export type DependencyReference = TokenBase | ReferenceBase;
 type ReferenceParts<R> = R extends {
     readonly [referenceInvariant]: (...args: never[]) => [infer T extends TokenBase, infer K];

package/dist/di-bag.d.ts

@@ -5,15 +5,15 @@ import { optional, lazy, all } from './dependency-references';
 import { withDisposal } from './registration';
 import type { FactoryWithDisposal, Factory, Registration, Registrations } from './registration';
 import { BindingGraph, BagRuntime } from './runtime';
-import type { Module } from './module';
+import type { Module, ModuleOptions } from './module';
 import type { CompositionReport } from './composition-report';
 import type { CheckedConstraints, CompleteConstraints, ExternalRequirements, IncrementalConstraints, ModulePublicProviders, ModuleSealedConstraints, NeedConstraint } from './module-types';
-import type { CheckedLifetimes } from './lifetime-types';
+import type { CheckedLifetimes, SealAdmission, WithoutExportObligations } from './lifetime-types';
 import { withLifetime } from './lifetime';
 import { fromFactory } from './acquisition-context';
 import type { ScopeOptions, DisjointScopeSelection, UnsharedAliases, ScopedAliases } from './scope-types';
 import type { CheckedScopeLifetimes } from './lifetime-types';
-import type { StartupOptions } from './startup';
+import type { CloseOptions, StartupOptions } from './startup';
 import { withMetadata, transformService } from './provider';
 import { fromFunction, fromClass } from './composition';
 import type { RuntimeContext, RuntimeOptions } from './acquisition-mode';
@@ -24,7 +24,7 @@ import type { PluginProviderFactory } from './plugins';
 import type { TokenBase, TokenKey, TokenService } from './tokens';
 import type { TokenBinding, BindingOutput, TokenMember, TokenTupleAdmission, SelectionKey, ReboundSelection } from './token-types';
 import type { BuilderReplacementRegistration, ReplacementAdmission, ReplacedEntries, ZeroDependencyAdmission } from './replacement-types';
-import type { CheckDependencyCompatibility, CheckDependencyCompleteness, RegistrationEntries, Entry, EntryKeys, OverrideFactoryContext, RegistrationsFromEntries, IncrementalChecked, Introduces, IntroducesKeys, OverrideRegistrations, Overrides, ServicesOf, ReplacementKeyOf, ReplacementOutput, SelectedRegistrations, Selection, NamedAdmission, ThenableAdmission } from './types';
+import type { CheckDependencyCompatibility, CheckDependencyCompleteness, RegistrationEntries, Entry, EntryKeys, ExportedServices, OverrideFactoryContext, RegistrationsFromEntries, IncrementalChecked, Introduces, IntroducesKeys, OverrideRegistrations, Overrides, ServicesOf, ReplacementKeyOf, ReplacementOutput, SelectedRegistrations, Selection, NamedAdmission, ThenableAdmission } from './types';
 type ReplacementFactory<O> = (this: void) => O;
 declare const constraintInvariant: unique symbol;
 /**
@@ -32,39 +32,71 @@ declare const constraintInvariant: unique symbol;
  *
  * Create bags through {@link DiBagApi.createBuilder} followed by {@link Builder.build} or
  * {@link Builder.buildAndStart}; the class is exported as a type and has no public constructor.
+ * @see https://dany-fedorov.github.io/di-bag/agent/api-card.html#bag
  */
 declare class Bag<R extends Registrations, C extends NeedConstraint = never> {
     #private;
-    private readonly context;
     /** @internal */
     readonly [constraintInvariant]: (value: C) => C;
+    private readonly context;
     constructor(graph: BindingGraph, context: RuntimeContext, runtime?: BagRuntime);
     /**
      * Resolve a named or typed-token service, acquiring it lazily when needed.
      * Scoped and root services are cached according to their lifetime; transient services
      * create a new acquisition for each call. Promise-valued services keep their identity.
+     * An async factory's service is its Promise; nothing is awaited for you.
      * @param token - An existing public string name or typed token.
      * @returns The service exposed by the selected registration.
-     * @throws If the bag is closing, the token is invalid, acquisition fails, or a runtime cycle is found.
+     * @throws `DI_BAG_CLOSING` or `DI_BAG_CLOSED` after `close()`; `DI_BAG_INVALID_TOKEN` or `DI_BAG_MISSING_REGISTRATION` for a bad selection;
+     * during acquisition `DI_BAG_MISSING_DEPENDENCY`, `DI_BAG_CYCLE`, `DI_BAG_LIFETIME_DEPENDENCY`, `DI_BAG_INVALID_DEPENDENCY_ACCESS`,
+     * `DI_BAG_STRUCTURAL_THENABLE`, `DI_BAG_INVALID_CLASSIFIER_RESULT`, `DI_BAG_INVALID_METADATA`, `DI_BAG_PLUGIN_VALIDATION`,
+     * or the factory's own error.
+     * @example
+     * ```ts
+     * const bag = DiBag.createBuilder().register({ greeting: () => 'hello' }).build();
+     * const greeting: string = bag.resolve('greeting');
+     * ```
      */
     resolve<K extends (keyof R & string) | TokenBase>(token: K & ([K] extends [string] ? unknown : TokenMember<R, K>)): ServicesOf<R>[SelectionKey<K> & keyof R];
     /**
      * Resolve every contribution for a typed token in declaration and installation order.
      * @param token - The collection token whose contributions to acquire.
      * @returns A fresh frozen array; an unpopulated collection returns an empty array.
-     * @throws If the bag is closing, the token is invalid, or a contribution fails.
+     * @throws `DI_BAG_CLOSING` or `DI_BAG_CLOSED` after `close()`; `DI_BAG_INVALID_TOKEN` for a bad token;
+     * a contribution's acquisition errors as listed for {@link Bag.resolve}.
+     * @example
+     * ```ts
+     * const toolsKey = Symbol('tools');
+     * const tools = DiBag.token(toolsKey).of<string>();
+     * const bag = DiBag.createBuilder().contribute(tools, () => 'search').contribute(tools, () => 'fetch').build();
+     * const names: readonly string[] = bag.resolveAll(tools);
+     * ```
      */
     resolveAll<T extends TokenBase>(token: T & TokenTupleAdmission<readonly [T]> & CollectionMember<T, C>, ...invalid: [T] extends [never] ? [never] : []): ReadonlyArray<TokenService<T>>;
     /**
      * Inspect every contribution for a token without running its factories.
      * @param token - The collection token to inspect.
      * @returns Frozen snapshots in contribution order.
+     * @throws `DI_BAG_INVALID_TOKEN` for a bad token.
+     * @example
+     * ```ts
+     * const toolsKey = Symbol('tools');
+     * const tools = DiBag.token(toolsKey).of<string>();
+     * const bag = DiBag.createBuilder().contribute(tools, () => 'search').build();
+     * const labels = bag.inspectAll(tools).map(snapshot => snapshot.label);
+     * ```
      */
     inspectAll<T extends TokenBase>(token: T & TokenTupleAdmission<readonly [T]> & CollectionMember<T, C>, ...invalid: [T] extends [never] ? [never] : []): readonly RegistrationSnapshot<object, readonly unknown[]>[];
     /**
      * Inspect static metadata and copied acquisition state without resolving a service.
      * @param token - An existing public string name or typed token.
      * @returns A frozen point-in-time snapshot. Application-owned metadata payloads are not frozen.
+     * @throws `DI_BAG_INVALID_TOKEN` or `DI_BAG_MISSING_REGISTRATION` for a bad selection; `DI_BAG_CYCLE` for an alias cycle.
+     * @example
+     * ```ts
+     * const bag = DiBag.createBuilder().register({ greeting: () => 'hello' }).build();
+     * const acquired = bag.inspect('greeting').acquisitions.length;
+     * ```
      */
     inspect<K extends (keyof R & string) | TokenBase>(token: K & ([K] extends [string] ? unknown : TokenMember<R, K>)): RegistrationSnapshot<ProviderRegistrationMetadata<R[SelectionKey<K> & keyof R]>, ProviderAcquisitionMetadata<R[SelectionKey<K> & keyof R]>>;
     /**
@@ -72,12 +104,19 @@ declare class Bag<R extends Registrations, C extends NeedConstraint = never> {
      * Nothing is acquired. Named dependencies declared on factory parameters are not visible
      * until the factory runs; the static graph tool reports them from source.
      * @returns A frozen point-in-time snapshot; application-owned metadata payloads are not frozen.
+     * @example
+     * ```ts
+     * const bag = DiBag.createBuilder().register({ greeting: () => 'hello' }).build();
+     * const labels = bag.inspectGraph().bindings.map(binding => binding.label);
+     * ```
      */
     inspectGraph(): GraphSnapshot;
     /**
      * Create a tracked child that borrows selected parent acquisitions.
      * @param options - A checked selection of non-transient services to share lazily.
      * @returns A child owned by this bag; closing the parent closes the child first.
+     * @throws `DI_BAG_INVALID_SCOPE` for a malformed or transient share selection; `DI_BAG_INVALID_TOKEN` for a bad token;
+     * `DI_BAG_CLOSING` or `DI_BAG_CLOSED` after `close()`.
      */
     createScope<const S extends readonly unknown[]>(options: ScopeOptions<R, S>): Bag<ScopedAliases<R, R, S>, C>;
     /**
@@ -86,35 +125,67 @@ declare class Bag<R extends Registrations, C extends NeedConstraint = never> {
      * @param overrides - Own registration properties for every selected key.
      * @param options - A disjoint selection of non-transient parent acquisitions to share.
      * @returns A child with fresh scoped acquisitions and ownership for unshared services.
-     * @throws If the runtime selections, overrides, or sharing options are invalid.
+     * @throws `DI_BAG_INVALID_SCOPE` for invalid selections, overrides, or sharing; `DI_BAG_INVALID_TOKEN` or `DI_BAG_INVALID_REGISTRATION`
+     * for malformed input; `DI_BAG_CLOSING` or `DI_BAG_CLOSED` after `close()`; `DI_BAG_CLASSIFIER_REQUIRED` as for {@link Builder.build}.
      */
-    createScope<const K extends readonly unknown[], O extends OverrideFactoryContext<R, K, O>, const S extends readonly unknown[] = readonly []>(keys: K & Selection<R, K, 'createScope'>, overrides: O & object & Record<SelectionKey<K[number]>, Registration> & Overrides<R, SelectedRegistrations<K, O>> & CheckDependencyCompatibility<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckDependencyCompleteness<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckedConstraints<C, OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CompleteConstraints<C, OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckedScopeLifetimes<NoInfer<ScopedAliases<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>, R, S>>, NoInfer<SelectedRegistrations<K, O>>, C>, options?: ScopeOptions<R, S> & DisjointScopeSelection<K, S>): Bag<ScopedAliases<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>, R, S>, C>;
+    createScope<const K extends readonly unknown[], O extends OverrideFactoryContext<R, K, O>, const S extends readonly unknown[] = readonly []>(keys: K & Selection<R, K, 'createScope'>, overrides: O & object & Record<SelectionKey<K[number]>, Registration> & Overrides<R, SelectedRegistrations<K, O>> & CheckDependencyCompatibility<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckDependencyCompleteness<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckedConstraints<C, OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CompleteConstraints<C, OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckedScopeLifetimes<NoInfer<ScopedAliases<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>, R, S>>, NoInfer<SelectedRegistrations<K, O>>, WithoutExportObligations<C, SelectionKey<K[number]>>>, options?: ScopeOptions<R, S> & DisjointScopeSelection<K, S>): Bag<ScopedAliases<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>, R, S>, WithoutExportObligations<C, SelectionKey<K[number]>>>;
     /**
      * Create a tracked child with the same graph and fresh scoped acquisitions.
+     * Close every scope you create, typically one per request; closing the parent closes its live scopes first.
      * @returns A child that is closed before its parent finishes closing.
+     * @throws `DI_BAG_CLOSING` or `DI_BAG_CLOSED` after `close()`.
+     * @example
+     * ```ts
+     * const app = DiBag.createBuilder().register({ requestId: () => Math.random() }).build();
+     * const request = app.createScope();
+     * const id: number = request.resolve('requestId');
+     * await request.close();
+     * ```
      */
     createScope(): Bag<UnsharedAliases<R>, C>;
     /**
      * Create an independent bag with the same graph and fresh instances.
      * @returns A new ownership family that must be closed separately.
+     * @throws `DI_BAG_CLOSING` or `DI_BAG_CLOSED` after `close()`.
      */
     fork(this: Bag<R, C> & CheckedLifetimes<UnsharedAliases<R>, C>): Bag<UnsharedAliases<R>, C>;
     /**
-     * Create an independent bag with selected replacements.
+     * Create an independent bag with selected replacements, the way tests substitute dependencies.
+     * Each override must satisfy the original contract; close the fork, since its parent does not.
      * @param keys - Existing names or tokens to replace.
      * @param overrides - Own registration properties for every selected key.
      * @returns A fresh ownership family whose graph uses the checked replacements.
-     * @throws If a selected key is absent or lacks an own override.
+     * @throws `DI_BAG_INVALID_OVERRIDE` for an absent key or a missing own override; `DI_BAG_INVALID_TOKEN` or `DI_BAG_INVALID_REGISTRATION`
+     * for malformed input; `DI_BAG_CLOSING` or `DI_BAG_CLOSED` after `close()`; `DI_BAG_CLASSIFIER_REQUIRED` as for {@link Builder.build}.
+     * @example
+     * ```ts
+     * type Clock = { now(): number };
+     * const app = DiBag.createBuilder().register({ clock: (): Clock => ({ now: () => Date.now() }) }).build();
+     * const test = app.fork(['clock'], { clock: (): Clock => ({ now: () => 0 }) });
+     * await test.close();
+     * ```
      */
-    fork<const K extends readonly unknown[], O extends OverrideFactoryContext<R, K, O>>(keys: K & Selection<R, K>, overrides: O & object & Record<SelectionKey<K[number]>, Registration> & Overrides<R, SelectedRegistrations<K, O>> & CheckDependencyCompatibility<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckDependencyCompleteness<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckedConstraints<C, OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CompleteConstraints<C, OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckedLifetimes<UnsharedAliases<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>>, C>): Bag<UnsharedAliases<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>>, C>;
+    fork<const K extends readonly unknown[], O extends OverrideFactoryContext<R, K, O>>(keys: K & Selection<R, K>, overrides: O & object & Record<SelectionKey<K[number]>, Registration> & Overrides<R, SelectedRegistrations<K, O>> & CheckDependencyCompatibility<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckDependencyCompleteness<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckedConstraints<C, OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CompleteConstraints<C, OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckedLifetimes<UnsharedAliases<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>>, WithoutExportObligations<C, SelectionKey<K[number]>>>): Bag<UnsharedAliases<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>>, WithoutExportObligations<C, SelectionKey<K[number]>>>;
     /**
      * Close this bag, drain in-flight work, and dispose owned resources once.
      * Dependents are disposed before dependencies; remaining independent acquisitions use
-     * reverse acquisition order. Repeated calls return the same promise.
-     * @returns The shared shutdown promise.
-     * @throws {@link DiBagCleanupError} when one or more disposers fail after all cleanup is attempted.
+     * reverse acquisition order. Without options the promise waits for cleanup however long it
+     * takes, and repeated calls return the same promise. With `timeoutMs` or `signal`, cleanup
+     * starts the same way but the returned promise stops waiting when either fires; scopes and
+     * forks accept the same options. Close every scope and fork you create; a parent closes its live scopes, never forks.
+     * @param options - An optional deadline and abort signal bounding the wait, not the cleanup.
+     * @returns The shared shutdown promise, or a bounded wait on it when options are given.
+     * @throws {@link DiBagCleanupError} (`DI_BAG_CLEANUP_FAILED`) when one or more disposers fail after all cleanup is attempted;
+     * `DI_BAG_CLOSE_FAILED` for other shutdown failures;
+     * {@link DiBagCloseCancelledError} (`DI_BAG_CLOSE_TIMEOUT` or `DI_BAG_CLOSE_ABORTED`) when the wait stops first,
+     * naming unfinished disposers in `details.pending`; `DI_BAG_INVALID_CLOSE` for malformed options.
+     * @example
+     * ```ts
+     * const bag = DiBag.createBuilder().register({ value: () => 1 }).build();
+     * await bag.close({ timeoutMs: 10_000, signal: AbortSignal.timeout(15_000) });
+     * ```
      */
-    close(): Promise<void>;
+    close(options?: CloseOptions): Promise<void>;
 }
 /**
  * An immutable, type-checked graph builder. Every operation returns a new builder.
@@ -122,6 +193,7 @@ declare class Bag<R extends Registrations, C extends NeedConstraint = never> {
  * {@link Builder.build} a bag once its graph is complete, or
  * {@link Builder.buildModule} a reusable module whose unmet dependencies become
  * requirements the installing host must satisfy.
+ * @see https://dany-fedorov.github.io/di-bag/agent/api-card.html#builder
  */
 declare class Builder<E extends Entry, C extends NeedConstraint = never> {
     #private;
@@ -131,9 +203,17 @@ declare class Builder<E extends Entry, C extends NeedConstraint = never> {
     constructor(graph: BindingGraph, context: RuntimeContext);
     /**
      * Add new string-named registrations.
+     * A factory declares its dependencies in the type of its one object parameter; destructure it or read `deps.name`, never spread it.
      * @param more - A finite object whose own string keys are service names and values are registrations.
      * @returns A new builder containing snapshots of the supplied registrations.
-     * @throws If the input is malformed, contains a non-string key, or duplicates a public name.
+     * @throws `DI_BAG_INVALID_REGISTRATION` for a malformed object or value; `DI_BAG_DUPLICATE_REGISTRATION` for a name already registered.
+     * @example
+     * ```ts
+     * type Clock = { now(): number };
+     * const builder = DiBag.createBuilder()
+     *   .register({ clock: (): Clock => ({ now: () => Date.now() }) })
+     *   .register({ stamp: ({ clock }: { clock: Clock }) => clock.now() });
+     * ```
      */
     register<N extends {
         [K in keyof N]: Registration;
@@ -143,6 +223,8 @@ declare class Builder<E extends Entry, C extends NeedConstraint = never> {
      * @param token - A new typed token identity.
      * @param registration - A registration whose exposed output satisfies the token service type.
      * @returns A new builder retaining the provider's metadata, lifetime, dependencies, and ownership stages.
+     * @throws `DI_BAG_INVALID_TOKEN` for a bad token; `DI_BAG_DUPLICATE_REGISTRATION` when it is already registered;
+     * `DI_BAG_INVALID_REGISTRATION` for an invalid registration.
      */
     register<T extends TokenBase, V extends Registration>(token: T & TokenTupleAdmission<readonly [T]> & IntroducesKeys<EntryKeys<E>, TokenKey<T>>, registration: V & Registration & BindingOutput<NoInfer<T>, NoInfer<V>> & ThenableAdmission<Record<TokenKey<T>, NoInfer<V>>> & IncrementalChecked<E, Record<TokenKey<T>, TokenBinding<NoInfer<T>, NoInfer<V>>>> & CheckedConstraints<C, OverrideRegistrations<RegistrationsFromEntries<E>, Record<TokenKey<T>, TokenBinding<NoInfer<T>, NoInfer<V>>>>>): Builder<E | {
         key: TokenKey<T>;
@@ -153,6 +235,12 @@ declare class Builder<E extends Entry, C extends NeedConstraint = never> {
      * @param destination - A new string name or typed token.
      * @param target - The existing name or token whose canonical acquisition is reused.
      * @returns A new builder; aliases add no cache or ownership of their own.
+     * @throws `DI_BAG_INVALID_TOKEN` for a bad token; `DI_BAG_DUPLICATE_REGISTRATION` when the destination exists;
+     * `DI_BAG_INVALID_ALIAS` for an absent named target.
+     * @example
+     * ```ts
+     * const builder = DiBag.createBuilder().register({ clock: () => Date.now() }).alias('now', 'clock');
+     * ```
      */
     alias<const D extends AliasSelection, const T extends AliasSelection>(destination: D & (unknown extends AliasAdmission<D> ? Introduces<RegistrationsFromEntries<E>, AliasEntries<RegistrationsFromEntries<E>, D, T>> : AliasAdmission<D>), target: T & AliasAdmission<T> & (unknown extends AliasAdmission<T> ? AliasTarget<RegistrationsFromEntries<E>, T> & AliasDestination<RegistrationsFromEntries<E>, NoInfer<D>, T> : unknown) & (unknown extends AliasAdmission<D> & AliasAdmission<T> ? IncrementalChecked<E, AliasEntries<RegistrationsFromEntries<E>, NoInfer<D>, NoInfer<T>>> & CheckedConstraints<C, OverrideRegistrations<RegistrationsFromEntries<E>, AliasEntries<RegistrationsFromEntries<E>, NoInfer<D>, NoInfer<T>>>> : unknown), ...invalid: [D] extends [never] ? [never] : [T] extends [never] ? [never] : []): Builder<E | AliasEntry<RegistrationsFromEntries<E>, D, T>, C>;
     /**
@@ -160,6 +248,13 @@ declare class Builder<E extends Entry, C extends NeedConstraint = never> {
      * @param token - The collection's typed token.
      * @param registration - A registration whose output satisfies the token service type.
      * @returns A new builder preserving contribution order.
+     * @throws `DI_BAG_INVALID_TOKEN` for a bad token; `DI_BAG_INVALID_REGISTRATION` for an invalid registration.
+     * @example
+     * ```ts
+     * const toolsKey = Symbol('tools');
+     * const tools = DiBag.token(toolsKey).of<string>();
+     * const builder = DiBag.createBuilder().contribute(tools, () => 'search').contribute(tools, () => 'fetch');
+     * ```
      */
     readonly contribute: BuilderContribute<E, C>;
     /**
@@ -168,24 +263,39 @@ declare class Builder<E extends Entry, C extends NeedConstraint = never> {
      * @param registration - The replacement, checked against every surviving consumer.
      * @returns A new builder with the replacement.
      * @typeParam V - The exact replacement factory or disposable-factory type.
+     * @throws `DI_BAG_INVALID_REPLACEMENT` for an absent key; `DI_BAG_INVALID_REGISTRATION` for an invalid registration.
+     * @example
+     * ```ts
+     * const builder = DiBag.createBuilder().register({ clock: () => Date.now() }).replace('clock', () => 0);
+     * ```
      */
     replace<const K extends string, V extends (ReplacementFactory<ReplacementOutput<NoInfer<RegistrationsFromEntries<E>>, K, C>>) | FactoryWithDisposal<ReplacementFactory<ReplacementOutput<NoInfer<RegistrationsFromEntries<E>>, K, C>>>>(key: K & ReplacementKeyOf<EntryKeys<E>, K>, registration: V & (Factory | FactoryWithDisposal<Factory>) & ZeroDependencyAdmission<NoInfer<V>> & CheckedConstraints<C, OverrideRegistrations<RegistrationsFromEntries<E>, Record<K, NoInfer<V>>>>): Builder<Exclude<E, {
         key: K;
     }> | {
         key: K;
         registration: V;
-    }, C>;
+    }, WithoutExportObligations<C, K>>;
     /**
      * Replace an existing named or typed-token registration.
      * @param key - The single existing name or token to replace.
      * @param registration - A replacement compatible with the token and known consumers.
      * @returns A new builder with the replacement and its inferred service type.
+     * @throws `DI_BAG_INVALID_REPLACEMENT` for an absent key; `DI_BAG_INVALID_TOKEN` or `DI_BAG_INVALID_REGISTRATION` for malformed input.
      */
-    replace<const K extends string | TokenBase, V extends Registration>(key: K & NoInfer<ReplacementAdmission<RegistrationsFromEntries<E>, K>>, registration: V & Registration & BuilderReplacementRegistration<E, C, NoInfer<K>, V>): Builder<ReplacedEntries<E, K, V>, C>;
+    replace<const K extends string | TokenBase, V extends Registration>(key: K & NoInfer<ReplacementAdmission<RegistrationsFromEntries<E>, K>>, registration: V & Registration & BuilderReplacementRegistration<E, C, NoInfer<K>, V>): Builder<ReplacedEntries<E, K, V>, WithoutExportObligations<C, SelectionKey<K>>>;
     /**
      * Install a sealed module, allocating fresh private bindings for this installation.
+     * The installing host must register every requirement the module does not register itself.
      * @param module - A module whose public names do not collide and whose external requirements remain checkable.
      * @returns A new builder exposing only the module's selected exports.
+     * @throws `DI_BAG_INVALID_MODULE` for a value not made by `buildModule`; `DI_BAG_DUPLICATE_REGISTRATION` when an export name is already registered.
+     * @example
+     * ```ts
+     * const greeting = DiBag.createBuilder()
+     *   .register({ greet: ({ name }: { name: string }) => `hello, ${name}` })
+     *   .buildModule(['greet']);
+     * const bag = DiBag.createBuilder().installModule(greeting).register({ name: () => 'Ada' }).build();
+     * ```
      */
     installModule<P extends object, R extends object, MC extends NeedConstraint, D extends Registrations>(module: Module<P, R, MC, D> & IntroducesKeys<EntryKeys<E>, keyof D> & IncrementalChecked<E, D> & IncrementalConstraints<C, MC, RegistrationsFromEntries<E>, D>): Builder<E | RegistrationEntries<D>, C | MC>;
     /**
@@ -193,6 +303,11 @@ declare class Builder<E extends Entry, C extends NeedConstraint = never> {
      * Write `builder.verifyGraph() satisfies void;` so a rejected graph fails on that line with
      * the complete message and details, instead of at the start of the builder expression.
      * @returns `void` for a buildable graph; otherwise the failure that `build()` would report.
+     * @example
+     * ```ts
+     * const builder = DiBag.createBuilder().register({ greeting: () => 'hello' });
+     * builder.verifyGraph() satisfies void;
+     * ```
      */
     verifyGraph<Self extends Builder<E, C>>(this: Self): CompositionReport<Self>;
     /**
@@ -201,14 +316,33 @@ declare class Builder<E extends Entry, C extends NeedConstraint = never> {
      * become requirements of the module. Installed modules nest: their private
      * bindings and retained constraints are re-scoped inside this module.
      * @param keys - A finite tuple of existing names or tokens; an empty tuple is allowed.
+     * @param options - An optional `label`; each installation names its private bindings `<label>/<key>` in
+     * error messages, cycle paths, `inspectGraph()`, and observer events, and nested labels compose as `outer/inner/key`.
      * @returns An immutable module that can be renamed or installed in another builder.
-     * @throws If the selection is not a tuple or contains an absent name or token.
+     * @throws `DI_BAG_INVALID_EXPORT` if the selection is not a tuple, contains an absent name or token, or the label is not a non-empty string;
+     * `DI_BAG_INVALID_TOKEN` for a value that is not a genuine token.
+     * @example
+     * ```ts
+     * const orders = DiBag.createBuilder()
+     *   .register({ repository: () => new Map<string, number>() })
+     *   .register({ placeOrder: ({ repository }: { repository: Map<string, number> }) => (id: string) => repository.set(id, 1) })
+     *   .buildModule(['placeOrder'], { label: 'orders' });
+     * // Errors and inspectGraph() name the private binding 'orders/repository'.
+     * const app = DiBag.createBuilder().installModule(orders).build();
+     * ```
      */
-    buildModule<const K extends readonly unknown[]>(keys: K & Selection<RegistrationsFromEntries<E>, K, 'buildModule'>): Module<Pick<ServicesOf<RegistrationsFromEntries<E>>, Extract<SelectionKey<K[number]>, keyof RegistrationsFromEntries<E>>>, ExternalRequirements<ModuleSealedConstraints<E, C, Extract<SelectionKey<K[number]>, keyof RegistrationsFromEntries<E>>>>, ModuleSealedConstraints<E, C, Extract<SelectionKey<K[number]>, keyof RegistrationsFromEntries<E>>>, ModulePublicProviders<RegistrationsFromEntries<E>, Extract<SelectionKey<K[number]>, keyof RegistrationsFromEntries<E>>>>;
+    buildModule<const K extends readonly unknown[]>(keys: K & Selection<RegistrationsFromEntries<E>, K, 'buildModule'> & SealAdmission<RegistrationsFromEntries<E>, Extract<SelectionKey<K[number]>, keyof RegistrationsFromEntries<E>>, C>, options?: ModuleOptions): Module<ExportedServices<ServicesOf<RegistrationsFromEntries<E>>, Extract<SelectionKey<K[number]>, keyof RegistrationsFromEntries<E>>>, ExternalRequirements<ModuleSealedConstraints<E, C, Extract<SelectionKey<K[number]>, keyof RegistrationsFromEntries<E>>>>, ModuleSealedConstraints<E, C, Extract<SelectionKey<K[number]>, keyof RegistrationsFromEntries<E>>>, ModulePublicProviders<RegistrationsFromEntries<E>, Extract<SelectionKey<K[number]>, keyof RegistrationsFromEntries<E>>>>;
     /**
      * Finish a complete graph as a lazy bag.
+     * The bag owns what it acquires; close it when done.
      * @returns A fresh bag that owns the acquisitions it creates.
-     * @throws At runtime if automatic acquisition is used without a configured Promise classifier.
+     * @throws `DI_BAG_CLASSIFIER_REQUIRED` when a registration uses `auto` acquisition, the facade has no Promise
+     * classifier, and the host has no `process.getBuiltinModule`.
+     * @example
+     * ```ts
+     * const bag = DiBag.createBuilder().register({ greeting: () => 'hello' }).build();
+     * await bag.close();
+     * ```
      */
     build(this: Builder<E, C> & CheckDependencyCompleteness<RegistrationsFromEntries<E>> & CompleteConstraints<C, RegistrationsFromEntries<E>> & CheckedLifetimes<RegistrationsFromEntries<E>, C>): Bag<RegistrationsFromEntries<E>, C>;
     /**
@@ -216,47 +350,192 @@ declare class Builder<E extends Entry, C extends NeedConstraint = never> {
      * @param keys - A finite tuple of existing names or typed tokens to make ready.
      * @param options - Optional cancellation signal, positive timeout, and parallel, sequential, or positive safe integer bounded scheduling.
      * @returns A promise for the new bag after every selected final stage is ready.
-     * @throws {@link DiBagStartupError} after rollback on acquisition failure, or
-     * {@link DiBagStartupCancelledError} promptly on abort or timeout.
+     * @throws {@link DiBagStartupError} (`DI_BAG_STARTUP_FAILED`) after rollback on acquisition failure;
+     * {@link DiBagStartupCancelledError} (`DI_BAG_STARTUP_CANCELLED`) promptly on abort or timeout;
+     * `DI_BAG_INVALID_STARTUP` for malformed keys or options; `DI_BAG_INVALID_TOKEN` for a bad token;
+     * `DI_BAG_CLASSIFIER_REQUIRED` as for {@link Builder.build}. Each arrives as a rejection.
+     * @example
+     * ```ts
+     * const bag = await DiBag.createBuilder()
+     *   .register({ db: async () => ({ ping: () => true }) })
+     *   .buildAndStart(['db'], { timeoutMs: 5_000 });
+     * ```
      */
     buildAndStart<const K extends readonly unknown[]>(this: Builder<E, C> & CheckDependencyCompleteness<RegistrationsFromEntries<E>> & CompleteConstraints<C, RegistrationsFromEntries<E>> & CheckedLifetimes<RegistrationsFromEntries<E>, C>, keys: K & Selection<RegistrationsFromEntries<E>, K, 'buildAndStart'>, options?: StartupOptions): Promise<Bag<RegistrationsFromEntries<E>, C>>;
 }
 export type { Bag, Builder };
-/** Immutable facade configuration. Observers append in the supplied order. */
+/**
+ * Immutable facade configuration. Observers append in the supplied order.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#observe-lifecycle-transitions
+ */
 export interface ConfigurationOptions {
     readonly runtime?: RuntimeOptions;
     readonly observers?: readonly ObserverOptions[];
 }
-/** The immutable public entry surface used by {@link DiBag} and derived facades. */
+/**
+ * The immutable public entry surface used by {@link DiBag} and derived facades.
+ * @see https://dany-fedorov.github.io/di-bag/agent/api-card.html#dibag-facade
+ */
 export interface DiBagApi {
-    /** Return a facade with inherited runtime settings and appended observers. */
+    /**
+     * Return a facade with inherited runtime settings and appended observers.
+     * @throws `DI_BAG_INVALID_CONFIGURATION` for a non-object, a runtime without `isNativePromise`, or malformed observers.
+     * @example
+     * ```ts
+     * const Observed = DiBag.withConfiguration({
+     *   observers: [{ onEvent: event => console.log(event.kind), onError: failure => console.error(failure.error) }],
+     * });
+     * ```
+     */
     withConfiguration: (options: ConfigurationOptions) => DiBagApi;
-    /** Describe a named-dependency factory, optionally receiving acquisition context. */
+    /**
+     * Describe a named-dependency factory with an explicit acquisition mode or the acquisition's abort signal.
+     * A factory that returns a non-Promise object with a `then` method needs `acquisitionMode: 'raw'` or must return `Promise.resolve(value)`.
+     * @throws `DI_BAG_INVALID_FACTORY` for a non-function or an unknown `context`; `DI_BAG_INVALID_ACQUISITION_MODE` for an unknown mode.
+     * @example
+     * ```ts
+     * type Query = { then(done: (rows: string[]) => void): void };
+     * const query = DiBag.fromFactory((): Query => ({ then: done => done([]) }), { acquisitionMode: 'raw' });
+     * ```
+     */
     fromFactory: typeof fromFactory;
-    /** Create a nominal typed token with a diagnostic label. */
+    /**
+     * Create a typed token from a unique symbol; `.of<Service>()` fixes its service type.
+     * @throws `DI_BAG_INVALID_TOKEN` when the key is not a symbol.
+     * @example
+     * ```ts
+     * const clockKey = Symbol('clock');
+     * const clock = DiBag.token(clockKey).of<{ now(): number }>();
+     * ```
+     */
     token: typeof token;
-    /** Create a positional dependency that yields undefined only when unregistered. */
+    /**
+     * Create a positional dependency that yields `undefined` only when the token is unregistered.
+     * @throws `DI_BAG_INVALID_TOKEN` for a value that is not a genuine token.
+     * @example
+     * ```ts
+     * const clockKey = Symbol('clock');
+     * const clock = DiBag.token(clockKey).of<{ now(): number }>();
+     * const stamp = DiBag.fromFunction([DiBag.optional(clock)], source => source?.now() ?? 0);
+     * ```
+     */
     optional: typeof optional;
-    /** Create a positional dependency resolved on demand by the receiving service. */
+    /**
+     * Create a positional dependency supplied as a function that resolves the token when called.
+     * @throws `DI_BAG_INVALID_TOKEN` for a value that is not a genuine token.
+     * @example
+     * ```ts
+     * const clockKey = Symbol('clock');
+     * const clock = DiBag.token(clockKey).of<{ now(): number }>();
+     * const stamp = DiBag.fromFunction([DiBag.lazy(clock)], getClock => () => getClock().now());
+     * ```
+     */
     lazy: typeof lazy;
-    /** Create a positional dependency containing ordered collection contributions. */
+    /**
+     * Create a positional dependency containing every contribution to a collection token, in order.
+     * @throws `DI_BAG_INVALID_TOKEN` for a value that is not a genuine token.
+     * @example
+     * ```ts
+     * const toolsKey = Symbol('tools');
+     * const tools = DiBag.token(toolsKey).of<string>();
+     * const menu = DiBag.fromFunction([DiBag.all(tools)], names => names.join(', '));
+     * ```
+     */
     all: typeof all;
-    /** Validate an unknown plugin descriptor and its acquired output at a checked boundary. */
+    /**
+     * Validate an unknown plugin descriptor now and its acquired output at acquisition.
+     * @throws `DI_BAG_INVALID_TOKEN` for a malformed dependency tuple; `DI_BAG_INVALID_PLUGIN_OPTIONS` for malformed options;
+     * {@link DiBagPluginValidationError} (`DI_BAG_PLUGIN_VALIDATION`) for an invalid descriptor, or at acquisition for rejected output.
+     * @example
+     * ```ts
+     * declare const descriptor: unknown;
+     * const greeter = DiBag.fromPlugin([], descriptor, {
+     *   acquisitionMode: 'raw',
+     *   validate: (value): value is () => string => typeof value === 'function',
+     * });
+     * ```
+     */
     fromPlugin: PluginProviderFactory;
-    /** Adapt a positional function with strict dependency tuple and argument checking. */
+    /**
+     * Adapt a positional function whose parameters receive the listed tokens' services.
+     * @throws `DI_BAG_INVALID_TOKEN` for a malformed token tuple; `DI_BAG_INVALID_FUNCTION` for a non-function;
+     * `DI_BAG_INVALID_ACQUISITION_MODE` for an unknown mode.
+     * @example
+     * ```ts
+     * const clockKey = Symbol('clock');
+     * const clock = DiBag.token(clockKey).of<{ now(): number }>();
+     * const stamp = DiBag.fromFunction([clock], source => new Date(source.now()).toISOString());
+     * ```
+     */
     fromFunction: typeof fromFunction;
-    /** Adapt a concrete constructor with positional dependency injection. */
+    /**
+     * Adapt a class whose constructor parameters receive the listed tokens' services.
+     * @throws `DI_BAG_INVALID_TOKEN` for a malformed token tuple; `DI_BAG_INVALID_CONSTRUCTOR` for a non-constructable value;
+     * `DI_BAG_INVALID_ACQUISITION_MODE` for an unknown mode.
+     * @example
+     * ```ts
+     * class Greeter { constructor(readonly greeting: string) {} }
+     * const greetingKey = Symbol('greeting');
+     * const greeter = DiBag.fromClass([DiBag.token(greetingKey).of<string>()], Greeter);
+     * ```
+     */
     fromClass: typeof fromClass;
-    /** Begin an empty immutable graph; build creates its owning bag, buildModule seals a reusable module. */
+    /**
+     * Begin an empty immutable graph; `build` creates its owning bag, `buildModule` seals a reusable module.
+     * @example
+     * ```ts
+     * const bag = DiBag.createBuilder().register({ greeting: () => 'hello' }).build();
+     * ```
+     */
     createBuilder: () => Builder<never>;
-    /** Attach owned-value cleanup while retaining earlier disposal stages. */
+    /**
+     * Make the bag own a factory's value and run `dispose` on it when the bag closes.
+     * `close()` runs disposers, dependents first; close every scope and fork you create.
+     * @throws `DI_BAG_INVALID_REGISTRATION` when the registration is neither a function nor a provider.
+     * @example
+     * ```ts
+     * const bag = DiBag.createBuilder()
+     *   .register({ controller: DiBag.withDisposal(() => new AbortController(), controller => controller.abort()) })
+     *   .build();
+     * await bag.close();
+     * ```
+     */
     withDisposal: typeof withDisposal;
-    /** Select root, scoped, or transient caching within an ownership family. */
+    /**
+     * Select `root`, `scoped` (the default), or `transient` caching for a registration.
+     * Mark a shared client `root` only when nothing it depends on is scoped.
+     * @throws `DI_BAG_INVALID_LIFETIME` for an unknown lifetime or malformed options; `DI_BAG_INVALID_REGISTRATION` for an invalid registration.
+     * @example
+     * ```ts
+     * const bag = DiBag.createBuilder()
+     *   .register({ cache: DiBag.withLifetime(() => new Map<string, string>(), 'root') })
+     *   .build();
+     * ```
+     */
     withLifetime: typeof withLifetime;
-    /** Attach registration metadata and ordered acquisition metadata in direct or awaited mode. */
+    /**
+     * Attach static registration metadata, or per-acquisition metadata in direct or awaited mode.
+     * @throws `DI_BAG_INVALID_METADATA` for malformed options or, at acquisition, a describe result that is not a plain record;
+     * `DI_BAG_DUPLICATE_METADATA` for a repeated key; `DI_BAG_INVALID_REGISTRATION` for an invalid registration.
+     * @example
+     * ```ts
+     * const greeting = DiBag.withMetadata(() => 'hello', { static: { owner: 'greeting' } });
+     * ```
+     */
     withMetadata: typeof withMetadata;
-    /** Transform the exposed service while retaining dependencies, metadata, lifetime, and existing ownership. */
+    /**
+     * Transform the exposed service while retaining dependencies, metadata, lifetime, and existing ownership.
+     * @throws `DI_BAG_INVALID_TRANSFORM` for a bad mode or callback; `DI_BAG_INVALID_ACQUISITION_MODE` for an unknown mode;
+     * `DI_BAG_INVALID_REGISTRATION` for an invalid registration.
+     * @example
+     * ```ts
+     * const shout = DiBag.transformService(() => 'hello', { mode: 'direct', transform: text => text.toUpperCase() });
+     * ```
+     */
     transformService: typeof transformService;
 }
-/** The portable, immutable DI Bag facade. Configure `auto` acquisition or use explicit modes. */
+/**
+ * The immutable DI Bag facade. `auto` acquisition uses the host classifier where `process.getBuiltinModule`
+ * exists; elsewhere configure one or use explicit modes.
+ */
 export declare const DiBag: DiBagApi;