di-bag 0.1.1 → 0.2.0

package/README.md

@@ -35,8 +35,6 @@ The minimum supported TypeScript version is **6.0.3**; enable `strict` in your
 `tsconfig.json`. The repository checks classic TypeScript 6.0.3 and native 7.0.2.
 For browsers and Deno, see [runtime support](#runtime-support).
 
-For an older checkout, follow the [single builder](docs/migrations/single-builder.md) and [API renaming](docs/migrations/api-renaming.md) migration guides.
-
 ## Quickstart
 
 A **service** can be a configuration object, a database client, or a function.
@@ -185,9 +183,10 @@ DI Bag supplies checked composition and resource ownership.
 
 The [agent harness and graph guide](docs/guides/agent-harnesses-and-graphs.md)
 combines private feature modules, an LLM-backed node, metadata inspection, and
-fork-based fixture tests in one runnable example. Inspection describes selected
-registrations, not complete dependency edges; observers track acquisition, not
-ordinary node calls. Use your graph framework for workflow checkpoints.
+fork-based fixture tests in one runnable example. `inspectGraph()` lists every
+binding and the edges observed at runtime; declared edges come from the static
+graph tool. Observers track acquisition, not ordinary node calls. Use your graph
+framework for workflow checkpoints.
 
 ## How it compares
 
@@ -248,12 +247,12 @@ for both setup options.
 | [API reference](docs/guides/api-reference.md) | Exact generated signatures, overloads, type parameters, and API inventories. |
 | [Server guide](docs/guides/server-integration.md) | Node HTTP, Express, Fastify, Bun, and Deno: shared services, request scopes, startup, and shutdown. |
 | [Agent harnesses and graphs](docs/guides/agent-harnesses-and-graphs.md) | Compose model and tool dependencies, inspect metadata, and test nodes with typed fixtures. |
+| [Static dependency graph](docs/guides/agent-harnesses-and-graphs.md#export-the-declared-dependency-graph) | Export every builder chain, declared edge, and cycle to JSON with `di-bag-graph`. |
 | [Runnable examples](examples) | Modules, tokens, composition, collections, plugins, observers, scopes, and provider metadata. |
 | [Integration guide](docs/guides/enterprise-integration.md) | Tested recipes for request ownership, substitutions, and dynamic features. |
 | [Comparison with alternatives](docs/guides/comparison.md) | When DI Bag or another approach may be a better fit, with primary sources. |
-| [Migration guides](docs/migrations/single-builder.md) | Before/after examples for the single builder and the [earlier API renaming](docs/migrations/api-renaming.md). |
 | [Development and verification](docs/guides/development.md) | Full checks, portable runtime testing, compiler scale, and performance evidence. |
-| [Documentation map](docs/README.md) | Current guides, migration history, and archived research and design notes. |
+| [Documentation map](docs/README.md) | Every guide, the generated reference, and the contributor documents. |
 
 ## Working on DI Bag
 

package/dist/acquisition-context.d.ts

@@ -1,6 +1,6 @@
 import type { Provider } from './provider';
 import type { Factory } from './registration';
-import type { Acquired, AcquisitionMode, NativeOutput, ModeOptions } from './acquisition-mode';
+import type { Acquired, AcquisitionMode, AutoOutput, NativeOutput, ModeOptions } from './acquisition-mode';
 import type { TokenDependencyContract } from './token-types';
 /** Cooperative cancellation information supplied to a context-aware acquisition. */
 export interface AcquisitionContext {
@@ -26,7 +26,7 @@ type FactoryOptions<M extends AcquisitionMode> = 'auto' extends M ? [options?: {
  * @typeParam F - The complete callback signature, retaining dependency and output inference.
  * @typeParam M - The raw, nativePromise, or configured auto acquisition policy.
  */
-export declare function fromFactory<F extends (this: void, deps: never, context: AcquisitionContext) => ('nativePromise' extends M ? Promise<unknown> : unknown), M extends AcquisitionMode = 'auto'>(callback: F, options: {
+export declare function fromFactory<F extends (this: void, deps: never, context: AcquisitionContext) => ('nativePromise' extends M ? Promise<unknown> : unknown), M extends AcquisitionMode = 'auto'>(callback: F & AutoOutput<ReturnType<NoInfer<F>>, NoInfer<M>>, options: {
     readonly context: 'acquisition';
 } & ModeOptions<M>): Provider<ContextualFactory<F>, Readonly<{}>, readonly [], TokenDependencyContract, Acquired<ReturnType<F>, M>>;
 /**
@@ -38,5 +38,5 @@ export declare function fromFactory<F extends (this: void, deps: never, context:
  * @typeParam F - The exact factory signature and exposed result.
  * @typeParam M - The raw, nativePromise, or configured auto acquisition policy.
  */
-export declare function fromFactory<F extends Factory, M extends AcquisitionMode = 'auto'>(callback: F & NativeOutput<ReturnType<NoInfer<F>>, NoInfer<M>>, ...options: FactoryOptions<M>): Provider<F, Readonly<{}>, readonly [], TokenDependencyContract, Acquired<ReturnType<F>, M>>;
+export declare function fromFactory<F extends Factory, M extends AcquisitionMode = 'auto'>(callback: F & NativeOutput<ReturnType<NoInfer<F>>, NoInfer<M>> & AutoOutput<ReturnType<NoInfer<F>>, NoInfer<M>>, ...options: FactoryOptions<M>): Provider<F, Readonly<{}>, readonly [], TokenDependencyContract, Acquired<ReturnType<F>, M>>;
 export {};

package/dist/acquisition-family.d.ts

@@ -26,6 +26,11 @@ export declare class AcquisitionFamily {
     leave(): void;
     ancestry(bindingId: BindingId, ownerId: symbol, label: string, from?: AttemptIdentity): AcquisitionHistory | undefined;
     dependencyPath(from: AttemptIdentity, dependency: string): readonly string[];
+    /** Distinct consumer-to-dependency binding edges recorded by live attempts, in attempt order. */
+    observedEdges(): readonly {
+        readonly from: BindingId;
+        readonly to: BindingId;
+    }[];
     retireIncoming(attempt: AttemptIdentity): void;
     recordEdge(from: AttemptIdentity, to: AttemptIdentity): void;
     private path;

package/dist/acquisition-family.js

@@ -78,6 +78,26 @@ class AcquisitionFamily {
         history.reverse();
         return Object.freeze([...history, from.label, dependency]);
     }
+    /** Distinct consumer-to-dependency binding edges recorded by live attempts, in attempt order. */
+    observedEdges() {
+        const seen = new Map();
+        const edges = [];
+        for (const attempt of this.attempts.values()) {
+            for (const dependency of attempt.dependencies) {
+                const target = this.attempts.get(dependency);
+                if (!target)
+                    continue;
+                let targets = seen.get(attempt.bindingId);
+                if (!targets)
+                    seen.set(attempt.bindingId, targets = new Set());
+                if (targets.has(target.bindingId))
+                    continue;
+                targets.add(target.bindingId);
+                edges.push(Object.freeze({ from: attempt.bindingId, to: target.bindingId }));
+            }
+        }
+        return Object.freeze(edges);
+    }
     retireIncoming(attempt) {
         const consumers = this.incoming.get(attempt.id);
         if (!consumers)

package/dist/acquisition-mode.d.ts

@@ -1,5 +1,5 @@
 import type { LifecycleObservers } from './observers';
-import type { Unsatisfied } from './types';
+import type { StructuralThenable, Unsatisfied } from './types';
 /**
  * How an acquisition stage treats its returned value: configured classification,
  * the exact raw value, or an observed native Promise fulfillment.
@@ -28,6 +28,8 @@ export type StageOptions<M extends AcquisitionMode> = 'auto' extends M ? [option
     readonly acquisitionMode: M;
 }];
 export type NativeOutput<O, M extends AcquisitionMode> = 'nativePromise' extends M ? [O] extends [Promise<unknown>] ? unknown : Unsatisfied<'nativePromise acquisition requires a Promise output', {}> : unknown;
+/** Reject a structural thenable output when the stage would classify it automatically. */
+export type AutoOutput<O, M extends AcquisitionMode> = 'auto' extends M ? true extends StructuralThenable<O> ? Unsatisfied<'factory output is a structural thenable; return a native Promise or select acquisitionMode raw or nativePromise', {}> : unknown : unknown;
 export declare function acquisitionMode(options: {
     readonly acquisitionMode?: AcquisitionMode;
 } | undefined, fallback?: AcquisitionMode): AcquisitionMode;

package/dist/acquisition.d.ts

@@ -32,6 +32,10 @@ export declare class ScopeAcquisitions {
     isTransient(bindingId: BindingId, path?: readonly BindingId[]): boolean;
     /** Relationship uses the effective owner graph; frames use canonical attempts. */
     inspectDescription(bindingId: BindingId): Pick<RegistrationSnapshot<object, readonly unknown[]>, 'registrationMetadata' | 'aliasTarget'>;
+    observedEdges(): readonly {
+        readonly from: BindingId;
+        readonly to: BindingId;
+    }[];
     private assertAliasPath;
     assertOpen(): void;
     close(beforeDispose?: Promise<void>, cause?: unknown): Promise<void>;

package/dist/acquisition.js

@@ -115,6 +115,7 @@ class ScopeAcquisitions {
         const owner = this.owner(bindingId);
         return owner === this ? { registrationMetadata: description.metadata } : owner.inspectDescription(bindingId);
     }
+    observedEdges() { return this.family.observedEdges(); }
     assertAliasPath(bindingId, path) {
         if (path.includes(bindingId))
             throw (0, errors_1.libraryError)('DI_BAG_CYCLE', `alias cycle: ${[...path, bindingId].map(id => this.graph.label(id)).join(' -> ')}`, { path: Object.freeze([...path, bindingId].map(id => this.graph.label(id))) });
@@ -239,8 +240,12 @@ class ScopeAcquisitions {
             return target === undefined ? undefined : this.takeExposed(this.resolveBinding(target, attempt));
         };
         const references = new Map(description.references.map(reference => [reference.slot, reference]));
+        const invalidAccess = (access) => (0, errors_1.libraryError)('DI_BAG_INVALID_DEPENDENCY_ACCESS', `Cannot inspect the dependencies of ${JSON.stringify(attempt.label)}: ${access} is not supported. Read each named dependency directly; the dependency object resolves lazily.`, { operation: 'resolve', consumer: attempt.label, access });
         const deps = new Proxy(Object.create(null), {
             get: (_, key) => {
+                // JSON.stringify probes toJSON through get before enumerating; name the real operation.
+                if (key === 'toJSON')
+                    throw invalidAccess('JSON.stringify');
                 const reference = typeof key === 'symbol' ? references.get(key) : undefined;
                 if (reference)
                     return reference.kind === 'lazy' ? () => read(reference.key)
@@ -249,6 +254,10 @@ class ScopeAcquisitions {
                     return undefined;
                 return read(key);
             },
+            // Only `get` is lazy and checked; every other reflection would silently report an empty object.
+            has: (_, key) => { throw invalidAccess(`'${String(key)}' in deps`); },
+            ownKeys: () => { throw invalidAccess('enumeration (Object.keys, spread, JSON.stringify)'); },
+            getOwnPropertyDescriptor: (_, key) => { throw invalidAccess(`descriptor of '${String(key)}'`); },
         });
         this.observeAttempt(attempt, 'acquisition-started');
         this.family.enter(attempt);

package/dist/composition-report.d.ts

@@ -0,0 +1,13 @@
+import type { Builder } from './di-bag';
+import type { CheckedLifetimes } from './lifetime-types';
+import type { CheckedConstraints, CompleteConstraints, NeedConstraint } from './module-types';
+import type { CheckDependencyCompatibility, CheckDependencyCompleteness, Entry, RegistrationsFromEntries } from './types';
+type ReportOf<Check> = unknown extends Check ? never : Check;
+type Reports<E extends Entry, C extends NeedConstraint> = ReportOf<CheckDependencyCompatibility<RegistrationsFromEntries<E>>> | ReportOf<CheckDependencyCompleteness<RegistrationsFromEntries<E>>> | ReportOf<CheckedConstraints<C, RegistrationsFromEntries<E>>> | ReportOf<CompleteConstraints<C, RegistrationsFromEntries<E>>> | ReportOf<CheckedLifetimes<RegistrationsFromEntries<E>, C>>;
+/**
+ * The compile-time verdict for a builder: `void` when `build()` would be accepted,
+ * otherwise the same failure `build()` reports, including its details.
+ * Read it through `builder.verifyGraph() satisfies void;` or as `CompositionReport<typeof builder>`.
+ */
+export type CompositionReport<B> = B extends Builder<infer E, infer C> ? [Reports<E, C>] extends [never] ? void : Reports<E, C> : never;
+export {};

package/dist/composition-report.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/composition.d.ts

@@ -1,4 +1,4 @@
-import type { Acquired, AcquisitionMode, NativeOutput, StageOptions } from './acquisition-mode';
+import type { Acquired, AcquisitionMode, AutoOutput, NativeOutput, StageOptions } from './acquisition-mode';
 import type { Provider } from './provider';
 import type { DependencyReference } from './dependency-references';
 import type { TokenArguments, ReferenceGraph, DependencyTupleAdmission } from './token-types';
@@ -19,7 +19,7 @@ export type CompositionFunction<T extends readonly DependencyReference[], O = un
  * @returns A lazy provider retaining the dependency graph and exact return type.
  * @typeParam F - The exact positional function signature retained by the provider.
  */
-export declare function fromFunction<const T extends readonly DependencyReference[], F extends CompositionFunction<NoInfer<T>, 'nativePromise' extends M ? Promise<unknown> : unknown>, M extends AcquisitionMode = 'auto'>(tokens: T & DependencyTupleAdmission<T>, callback: F & CompositionArguments<TokenArguments<NoInfer<T>>, Parameters<NoInfer<F>>> & NativeOutput<ReturnType<NoInfer<F>>, NoInfer<M>>, ...modeOptions: StageOptions<M>): Provider<OutputFactory<ReturnType<F>>, Readonly<{}>, readonly [], ReferenceGraph<T>, Acquired<ReturnType<F>, M>>;
+export declare function fromFunction<const T extends readonly DependencyReference[], F extends CompositionFunction<NoInfer<T>, 'nativePromise' extends M ? Promise<unknown> : unknown>, M extends AcquisitionMode = 'auto'>(tokens: T & DependencyTupleAdmission<T>, callback: F & CompositionArguments<TokenArguments<NoInfer<T>>, Parameters<NoInfer<F>>> & NativeOutput<ReturnType<NoInfer<F>>, NoInfer<M>> & AutoOutput<ReturnType<NoInfer<F>>, NoInfer<M>>, ...modeOptions: StageOptions<M>): Provider<OutputFactory<ReturnType<F>>, Readonly<{}>, readonly [], ReferenceGraph<T>, Acquired<ReturnType<F>, M>>;
 /**
  * Adapt a positional function whose parameters exactly match the selected dependency values.
  * @param tokens - A finite tuple of typed tokens and dependency references.
@@ -28,7 +28,7 @@ export declare function fromFunction<const T extends readonly DependencyReferenc
  * @returns A reusable provider; no dependency or result is implicitly awaited.
  * @typeParam F - The exact positional function signature retained by the provider.
  */
-export declare function fromFunction<const T extends readonly DependencyReference[], F extends CompositionFunction<NoInfer<T>>, M extends AcquisitionMode = 'auto'>(tokens: T & DependencyTupleAdmission<T>, callback: F & CompositionArguments<TokenArguments<NoInfer<T>>, Parameters<NoInfer<F>>> & NativeOutput<ReturnType<NoInfer<F>>, NoInfer<M>>, ...modeOptions: StageOptions<M>): Provider<OutputFactory<ReturnType<F>>, Readonly<{}>, readonly [], ReferenceGraph<T>, Acquired<ReturnType<F>, M>>;
+export declare function fromFunction<const T extends readonly DependencyReference[], F extends CompositionFunction<NoInfer<T>>, M extends AcquisitionMode = 'auto'>(tokens: T & DependencyTupleAdmission<T>, callback: F & CompositionArguments<TokenArguments<NoInfer<T>>, Parameters<NoInfer<F>>> & NativeOutput<ReturnType<NoInfer<F>>, NoInfer<M>> & AutoOutput<ReturnType<NoInfer<F>>, NoInfer<M>>, ...modeOptions: StageOptions<M>): Provider<OutputFactory<ReturnType<F>>, Readonly<{}>, readonly [], ReferenceGraph<T>, Acquired<ReturnType<F>, M>>;
 /**
  * Adapt a concrete constructor while preserving its prototype, private fields, and `new.target`.
  * @param tokens - A finite tuple whose dependency values match the constructor parameters.
@@ -37,5 +37,5 @@ export declare function fromFunction<const T extends readonly DependencyReferenc
  * @returns A lazy provider that constructs one instance per acquisition attempt.
  * @throws When the supplied runtime value is not constructable.
  */
-export declare function fromClass<const T extends readonly DependencyReference[], C extends new (...args: TokenArguments<NoInfer<T>>) => unknown, M extends AcquisitionMode = 'auto'>(tokens: T & DependencyTupleAdmission<T>, constructor: C & CompositionArguments<TokenArguments<NoInfer<T>>, ConstructorParameters<NoInfer<C>>> & NativeOutput<InstanceType<NoInfer<C>>, NoInfer<M>>, ...modeOptions: StageOptions<M>): Provider<() => InstanceType<C>, Readonly<{}>, readonly [], ReferenceGraph<T>, Acquired<InstanceType<C>, M>>;
+export declare function fromClass<const T extends readonly DependencyReference[], C extends new (...args: TokenArguments<NoInfer<T>>) => unknown, M extends AcquisitionMode = 'auto'>(tokens: T & DependencyTupleAdmission<T>, constructor: C & CompositionArguments<TokenArguments<NoInfer<T>>, ConstructorParameters<NoInfer<C>>> & NativeOutput<InstanceType<NoInfer<C>>, NoInfer<M>> & AutoOutput<InstanceType<NoInfer<C>>, NoInfer<M>>, ...modeOptions: StageOptions<M>): Provider<() => InstanceType<C>, Readonly<{}>, readonly [], ReferenceGraph<T>, Acquired<InstanceType<C>, M>>;
 export {};

package/dist/di-bag.d.ts

@@ -6,6 +6,7 @@ import { withDisposal } from './registration';
 import type { FactoryWithDisposal, Factory, Registration, Registrations } from './registration';
 import { BindingGraph, BagRuntime } from './runtime';
 import type { Module } 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 { withLifetime } from './lifetime';
@@ -17,13 +18,13 @@ import { withMetadata, transformService } from './provider';
 import { fromFunction, fromClass } from './composition';
 import type { RuntimeContext, RuntimeOptions } from './acquisition-mode';
 import type { ProviderRegistrationMetadata, ProviderAcquisitionMetadata } from './provider';
-import type { RegistrationSnapshot } from './inspection';
+import type { GraphSnapshot, RegistrationSnapshot } from './inspection';
 import { token } from './tokens';
 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 } from './types';
+import type { CheckDependencyCompatibility, CheckDependencyCompleteness, RegistrationEntries, Entry, EntryKeys, 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;
 /**
@@ -66,6 +67,13 @@ declare class Bag<R extends Registrations, C extends NeedConstraint = never> {
      * @returns A frozen point-in-time snapshot. Application-owned metadata payloads are not frozen.
      */
     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]>>;
+    /**
+     * Describe every binding this bag can resolve and the dependency edges observed so far.
+     * 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.
+     */
+    inspectGraph(): GraphSnapshot;
     /**
      * Create a tracked child that borrows selected parent acquisitions.
      * @param options - A checked selection of non-transient services to share lazily.
@@ -129,14 +137,14 @@ declare class Builder<E extends Entry, C extends NeedConstraint = never> {
      */
     register<N extends {
         [K in keyof N]: Registration;
-    }>(more: N & Registrations & ([N] extends [never] ? never : NamedAdmission<N> & IntroducesKeys<EntryKeys<E>, keyof N> & IncrementalChecked<E, N> & CheckedConstraints<C, OverrideRegistrations<RegistrationsFromEntries<E>, N>>)): Builder<E | RegistrationEntries<N>, C>;
+    }>(more: N & Registrations & ([N] extends [never] ? never : NamedAdmission<N> & ThenableAdmission<N> & IntroducesKeys<EntryKeys<E>, keyof N> & IncrementalChecked<E, N> & CheckedConstraints<C, OverrideRegistrations<RegistrationsFromEntries<E>, N>>)): Builder<E | RegistrationEntries<N>, C>;
     /**
      * Register a provider to a typed token.
      * @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.
      */
-    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>> & 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 | {
+    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>;
         registration: TokenBinding<T, V>;
     }, C>;
@@ -180,6 +188,13 @@ declare class Builder<E extends Entry, C extends NeedConstraint = never> {
      * @returns A new builder exposing only the module's selected exports.
      */
     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>;
+    /**
+     * Report at the type level why this graph would not build; the runtime call does nothing.
+     * 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.
+     */
+    verifyGraph<Self extends Builder<E, C>>(this: Self): CompositionReport<Self>;
     /**
      * Seal this graph as a reusable module and select its public names and typed tokens.
      * Unselected registrations stay private to each installation; unmet dependencies

package/dist/di-bag.js

@@ -41,6 +41,13 @@ class Bag {
     inspect(token) {
         return this.#runtime.inspect(typeof token === 'string' ? token : (0, tokens_1.readTokenKey)(token));
     }
+    /**
+     * Describe every binding this bag can resolve and the dependency edges observed so far.
+     * 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.
+     */
+    inspectGraph() { return this.#runtime.inspectGraph(); }
     createScope(...args) {
         this.#runtime.assertOpen();
         const { graph, shared } = (0, scope_selection_1.selectScope)(this.#graph, args, key => this.#runtime.isTransient(key));
@@ -154,6 +161,7 @@ class Builder {
     installModule(module) {
         return new Builder(this.#graph.withInstallation((0, module_1.moduleGraph)(module)), this.context);
     }
+    verifyGraph() { return undefined; }
     /**
      * Seal this graph as a reusable module and select its public names and typed tokens.
      * Unselected registrations stay private to each installation; unmet dependencies

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { DiBagCleanupError, DiBagPluginValidationError, DiBagStartupError, DiBag
 export type { CleanupFailure, DiBagErrorCode, DiBagDiagnostic } from './errors';
 export type { Bag, Builder, DiBagApi, ConfigurationOptions } from './di-bag';
 export type { Module } from './module';
+export type { CompositionReport } from './composition-report';
 export type { ModuleExportedServices, ModuleRequiredServices, ModuleConstraints, ModuleSealedConstraints, SealedConstraints, PublicProviders, ModulePublicProviders, Renamed } from './module-types';
 export type { FactoryWithDisposal, Registration } from './registration';
 export type { Provider, ProviderFactory, ProviderGraphContract, ProviderOutput, ProviderAcquiredValue, ProviderNamedDependencies, ProviderRegistrationMetadata, ProviderAcquisitionMetadata, ProviderRequiredTokens, ProviderOptionalTokens, ProviderCollectionTokens } from './provider';
@@ -14,8 +15,9 @@ export type { ScopeOptions, DisjointScopeSelection, UnsharedAliases, ScopedAlias
 export type { Token, TokenBase, TokenKey, TokenService } from './tokens';
 export type { TokenBinding, TokenMember, TokenDependencyContract, ReboundProviders, ReboundSelection, SelectionKey } from './token-types';
 export type { CheckedLifetimes, CheckedScopeLifetimes, LexicalContext, ModuleScope, Enclosed, RenamedContext, RenamedLifetimeObligation, EnclosedLifetimeObligation, RenamedLifetimeProviders } from './lifetime-types';
+export type { DiBagPolicy } from './types';
 export type { CheckDependencyCompatibility, CheckDependencyCompleteness, RegistrationEntries, OverrideFactoryContext, RegistrationsFromEntries, OverrideRegistrations, Overrides, ServicesOf, SelectedRegistrations, Selection } from './types';
-export type { Presence, AcquisitionMetadataPresence, AcquisitionSnapshot, RegistrationSnapshot } from './inspection';
+export type { Presence, AcquisitionMetadataPresence, AcquisitionSnapshot, RegistrationSnapshot, BindingSnapshot, GraphSnapshot } from './inspection';
 export type { CompositionArguments, CompositionFunction } from './composition';
 export type { OptionalDependency, LazyDependency, CollectionDependency, DependencyReference } from './dependency-references';
 export type { PluginProviderFactory, PluginAcquisitionMode, PluginOptions, PluginOutputValidator, PluginProvider } from './plugins';

package/dist/inspection.d.ts

@@ -1,3 +1,5 @@
+import type { AcquisitionMode } from './acquisition-mode';
+import type { Lifetime } from './lifetime';
 /** Structural optional presence; payloads are application-owned and not frozen. */
 export type Presence<T> = {
     readonly present: false;
@@ -34,3 +36,36 @@ export interface RegistrationSnapshot<M = Readonly<{}>, A extends readonly unkno
     /** Point-in-time attempts; inspection does not retain failed-attempt history. */
     readonly acquisitions: readonly AcquisitionSnapshot<A>[];
 }
+/** One binding of a bag's graph, described without acquiring it. */
+export interface BindingSnapshot<M = Readonly<{}>, A extends readonly unknown[] = readonly []> extends RegistrationSnapshot<M, A> {
+    /** Public names or token symbols that select this binding, in registration order; empty for a private module binding. */
+    readonly keys: readonly (string | symbol)[];
+    readonly lifetime: Lifetime;
+    readonly acquisitionMode: AcquisitionMode;
+    /** True when some stage of the provider accepts ownership through a disposer. */
+    readonly owned: boolean;
+    /** Typed-token dependencies declared positionally through tokens, `optional`, `lazy`, or `all` references. */
+    readonly tokenDependencies: readonly {
+        readonly key: symbol;
+        readonly kind: 'required' | 'optional' | 'lazy' | 'all';
+    }[];
+}
+/**
+ * A frozen description of every binding a bag can resolve, plus the edges observed so far.
+ * Named dependencies read from a factory's object parameter are not knowable until the factory
+ * runs; `observedEdges` records them after acquisition. Use the static graph tool for declared edges.
+ */
+export interface GraphSnapshot {
+    readonly scopeId: symbol;
+    /** Public bindings in registration order, then contributions in group order, then remaining private bindings. */
+    readonly bindings: readonly BindingSnapshot<object, readonly unknown[]>[];
+    readonly contributions: readonly {
+        readonly token: symbol;
+        readonly bindingIds: readonly symbol[];
+    }[];
+    /** Consumer-to-dependency edges recorded by acquisitions in this bag's ownership family. */
+    readonly observedEdges: readonly {
+        readonly from: symbol;
+        readonly to: symbol;
+    }[];
+}

package/dist/lifetime-types.d.ts

@@ -3,8 +3,17 @@ import type { Registration, Registrations } from './registration';
 import type { Provider, ProviderFactory, ProviderGraphContract, ProviderNamedDependencies, ProviderRequiredTokens, ProviderOptionalTokens, ProviderCollectionTokens, ProviderRegistrationMetadata, ProviderAcquisitionMetadata, ProviderAcquiredValue } from './provider';
 import type { GraphContract } from './token-types';
 import type { TokenKey } from './tokens';
-import type { CheckDependencyCompatibility, CheckDependencyCompleteness, Unsatisfied } from './types';
+import type { CheckDependencyCompatibility, CheckDependencyCompleteness, NameText, Unsatisfied } from './types';
 import type { CheckedConstraints, CompleteConstraints, NeedConstraint, Renamed } from './module-types';
+type SiteText<S> = S extends {
+    readonly key: infer K;
+} ? NameText<K> : S extends {
+    readonly kind: 'contribution';
+} ? 'contribution' : never;
+type CaptiveText<C> = C extends {
+    readonly root: infer R;
+    readonly dependency: infer D;
+} ? `${SiteText<R>} -> ${SiteText<D>}` : never;
 /**
  * A module provider's retained local registrations and public-to-local export mapping.
  * Contexts chain through `parent` when a module was sealed inside another module:
@@ -178,13 +187,13 @@ type OverrideCaptives<R extends Registrations, O extends Registrations, G> = {
 /** Reject root providers introduced by a scope override when they capture scoped dependencies. */
 export type CheckedScopeLifetimes<R extends Registrations, O extends Registrations, G = never> = [
     OverrideCaptives<R, O, G>
-] extends [never] ? unknown : Unsatisfied<'root lifetime cannot capture scoped dependency', {
+] extends [never] ? unknown : Unsatisfied<`root lifetime cannot capture scoped dependency: ${CaptiveText<OverrideCaptives<R, O, G>>}`, {
     readonly captives: OverrideCaptives<R, O, G>;
 }>;
 /** Reject strict root providers that transitively capture scoped dependencies. */
 export type CheckedLifetimes<R extends Registrations, C extends NeedConstraint> = [
     Captives<R, C>
-] extends [never] ? unknown : unknown extends CheckDependencyCompatibility<R> & CheckDependencyCompleteness<R> & CheckedConstraints<C, R> & CompleteConstraints<C, R> ? Unsatisfied<'root lifetime cannot capture scoped dependency', {
+] extends [never] ? unknown : unknown extends CheckDependencyCompatibility<R> & CheckDependencyCompleteness<R> & CheckedConstraints<C, R> & CompleteConstraints<C, R> ? Unsatisfied<`root lifetime cannot capture scoped dependency: ${CaptiveText<Captives<R, C>>}`, {
     readonly captives: Captives<R, C>;
 }> : unknown;
 type PolicyEnclosing<H extends Registrations, C, K, Visited> = C extends {

package/dist/module-types.d.ts

@@ -1,7 +1,7 @@
 import type { ContributionConstraint, CheckedContributions, CompleteContributions, RenamedContribution, ModuleContributionConstraints } from './contribution-types';
 import type { Module } from './module';
 import type { Registrations } from './registration';
-import type { Entry, Needs, RegistrationsFromEntries, ServicesOf, Singleton, Unsatisfied } from './types';
+import type { Entry, NameText, Needs, RegistrationsFromEntries, ServicesOf, Singleton, Unsatisfied } from './types';
 import type { MetadataKeyUnion, Provider, ProviderOutput, ProviderNamedDependencies, ProviderRegistrationMetadata, ProviderAcquisitionMetadata, ProviderAcquiredValue, ProviderGraphContract, ProviderRequiredTokens, ProviderOptionalTokens, ProviderCollectionTokens, BoundToken } from './provider';
 import type { TokenDependencyContract, WrongToken, MissingToken } from './token-types';
 import type { TokenBase, TokenKey, TokenService } from './tokens';
@@ -76,7 +76,7 @@ export type IncrementalConstraints<C extends NeedConstraint, MC extends NeedCons
 }>] extends [never] ? unknown extends CheckedConstraints<C, Incoming> ? CheckedConstraints<MC, import('./types').OverrideRegistrations<Old, Incoming>> : CheckedConstraints<C, Incoming> : CheckedConstraints<C | MC, import('./types').OverrideRegistrations<Old, Incoming>>;
 export type CompleteConstraints<C extends NeedConstraint, A extends Registrations> = [
     MissingConstraint<C, ServicesOf<A>> | MissingTokenConstraint<C, A>
-] extends [never] ? CompleteContributions<C, A> : Unsatisfied<'required service registrations are missing', {
+] extends [never] ? CompleteContributions<C, A> : Unsatisfied<`required service registrations are missing: ${NameText<MissingConstraint<C, ServicesOf<A>> | MissingTokenConstraint<C, A>>}`, {
     missing: MissingConstraint<C, ServicesOf<A>> | MissingTokenConstraint<C, A>;
     relationships: MissingConstraintRelationships<C, ServicesOf<A>>;
 }>;

package/dist/runtime.d.ts

@@ -1,7 +1,7 @@
 import { ScopeAcquisitions } from './acquisition';
 import { normalize } from './registration';
 import type { Registration, Registrations } from './registration';
-import type { RegistrationSnapshot } from './inspection';
+import type { GraphSnapshot, RegistrationSnapshot } from './inspection';
 import type { RuntimeContext } from './acquisition-mode';
 export type BindingId = symbol;
 export type BindingKey = string | symbol;
@@ -60,6 +60,16 @@ export declare class BindingGraph {
      * is kept to produce this order.
      */
     describe(): GraphDescription;
+    /** Every retained binding in `describe()` order, with the public keys that select it. */
+    bindingSummaries(): readonly {
+        readonly id: BindingId;
+        readonly keys: readonly BindingKey[];
+    }[];
+    /** Every contribution group with its member bindings in contribution order. */
+    contributionGroups(): readonly {
+        readonly token: symbol;
+        readonly bindingIds: readonly BindingId[];
+    }[];
     /** Install disjoint public slots atomically, retaining lexical private refs. */
     withInstallation(description: GraphDescription): BindingGraph;
 }
@@ -80,6 +90,7 @@ export declare class BagRuntime {
     acquire(key: BindingKey): Promise<void>;
     isTransient(key: BindingKey): boolean;
     inspect(key: BindingKey): RegistrationSnapshot<object, readonly unknown[]>;
+    inspectGraph(): GraphSnapshot;
     private inspectBinding;
     assertOpen(): void;
     scope(graph?: BindingGraph, shared?: readonly BindingId[]): BagRuntime;

package/dist/runtime.js

@@ -267,6 +267,28 @@ class BindingGraph {
             publicSlots.set(key, id);
         return { bindings, publicSlots, contributions };
     }
+    /** Every retained binding in `describe()` order, with the public keys that select it. */
+    bindingSummaries() {
+        const keysById = new Map();
+        if (this.#publicOrder)
+            for (const key of (0, persistent_sequence_1.materialize)(this.#publicOrder)) {
+                const id = this.#publicSlots.get(key);
+                if (id === undefined)
+                    continue;
+                const keys = keysById.get(id) ?? [];
+                if (!keys.includes(key))
+                    keys.push(key);
+                keysById.set(id, keys);
+            }
+        return Object.freeze([...this.describe().bindings.keys()].map(id => Object.freeze({ id, keys: Object.freeze(keysById.get(id) ?? []) })));
+    }
+    /** Every contribution group with its member bindings in contribution order. */
+    contributionGroups() {
+        const groups = [];
+        for (const [key] of this.#contributions)
+            groups.push(Object.freeze({ token: key, bindingIds: this.contributionBindings(key) }));
+        return Object.freeze(groups);
+    }
     /** Install disjoint public slots atomically, retaining lexical private refs. */
     withInstallation(description) {
         for (const key of description.publicSlots.keys()) {
@@ -338,6 +360,25 @@ class BagRuntime {
     inspect(key) {
         return this.inspectBinding(this.graph.publicBinding(key));
     }
+    inspectGraph() {
+        const bindings = this.graph.bindingSummaries().map(({ id, keys }) => {
+            const description = this.graph.registration(id);
+            return Object.freeze({
+                ...this.inspectBinding(id),
+                keys,
+                lifetime: description.lifetime.kind,
+                acquisitionMode: description.acquisitionMode,
+                owned: description.dispose !== undefined || description.operations.some(operation => operation.kind === 'owned'),
+                tokenDependencies: Object.freeze(description.references.map(reference => Object.freeze({ key: reference.key, kind: reference.kind }))),
+            });
+        });
+        return Object.freeze({
+            scopeId: this.acquisitions.ownerId,
+            bindings: Object.freeze(bindings),
+            contributions: this.graph.contributionGroups(),
+            observedEdges: this.acquisitions.observedEdges(),
+        });
+    }
     inspectBinding(bindingId) {
         return Object.freeze({
             bindingId,

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { FactoryWithDisposal, Registration, Registrations } from './registration';
+import type { Factory, FactoryWithDisposal, Registration, Registrations } from './registration';
 import type { ProviderContext, ProviderNamedDependencies, ProviderOutput, ProviderGraphContract, ProviderRequiredTokens, ProviderOptionalTokens } from './provider';
 import type { InvalidGraphs, MissingTokens, SelectionKey, TokenMember, ValidToken, TokenDependencyContract, WrongToken } from './token-types';
 export type Needs<R extends Registration> = ProviderNamedDependencies<R>;
@@ -24,6 +24,33 @@ export type RegistrationsFromEntries<E extends Entry> = {
 };
 /** Replace overlapping registrations in `F` with registrations from `N`. */
 export type OverrideRegistrations<F extends Registrations, N extends Registrations> = Omit<F, keyof N> & N;
+/**
+ * Project-wide compile-time policy switches. Augment it to relax a check:
+ * `declare module 'di-bag' { interface DiBagPolicy { readonly structuralThenables: 'allow' } }`.
+ */
+export interface DiBagPolicy {
+}
+type StructuralThenablesAllowed = DiBagPolicy extends {
+    readonly structuralThenables: 'allow';
+} ? true : false;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/** True for a declared output with a callable `then` that is not a native Promise; `any` is exempt. */
+export type StructuralThenable<O> = StructuralThenablesAllowed extends true ? false : IsAny<O> extends true ? false : O extends infer T & {} ? T extends Promise<unknown> ? false : T extends {
+    then(...args: never[]): unknown;
+} ? true : false : false;
+type ThenableOutputs<R extends Registrations> = {
+    [K in keyof R]: R[K] extends Factory | FactoryWithDisposal<Factory> ? true extends StructuralThenable<ProviderOutput<R[K]>> ? K : never : never;
+}[keyof R];
+/** Reject plain or disposable factories whose declared output auto acquisition would reject at runtime. */
+export type ThenableAdmission<R extends Registrations> = [ThenableOutputs<R>] extends [never] ? unknown : Unsatisfied<`factory output is a structural thenable: ${NameText<ThenableOutputs<R>>}; return a native Promise or use DiBag.fromFactory with acquisitionMode raw or nativePromise`, {
+    tokens: ThenableOutputs<R>;
+}>;
+/**
+ * Render dependency names inside diagnostic messages; typed tokens have no printable name.
+ * Use it only in checks that run once per graph (build, module completeness, lifetimes, key selection):
+ * per-call wrong-shape checks stay plain because templates there cost instantiations on valid graphs.
+ */
+export type NameText<K> = K extends string ? K : K extends number ? `${K}` : 'typed token';
 declare const diBagTypeError: unique symbol;
 export type Unsatisfied<Message extends string, Details> = {
     readonly [diBagTypeError]: Message;
@@ -107,7 +134,7 @@ export type CheckDependencyCompleteness<R extends Registrations> = [
     Exclude<RequiredOf<R>, keyof R> | MissingTokens<CompletionMap<R>>
 ] extends [never] ? [InvalidGraphs<CompletionMap<R>>] extends [never] ? unknown : Unsatisfied<'token dependency has an incompatible or opaque contract', {
     tokens: InvalidGraphs<CompletionMap<R>>;
-}> : Unsatisfied<'required service registrations are missing', {
+}> : Unsatisfied<`required service registrations are missing: ${NameText<Exclude<RequiredOf<R>, keyof R> | MissingTokens<CompletionMap<R>>>}`, {
     missing: Exclude<RequiredOf<R>, keyof R> | MissingTokens<CompletionMap<R>>;
     relationships: MissingRelationships<R>;
 }>;
@@ -117,9 +144,9 @@ type BadOverrides<F extends Registrations, O extends Registrations> = {
 /** Admit overrides only for existing keys whose service values remain assignable. */
 export type Overrides<F extends Registrations, O extends Registrations> = [
     Exclude<keyof O, keyof F>
-] extends [never] ? [BadOverrides<F, O>] extends [never] ? unknown : Unsatisfied<'override value is not assignable to the original token', {
+] extends [never] ? [BadOverrides<F, O>] extends [never] ? unknown : Unsatisfied<`override value is not assignable to the original token: ${NameText<BadOverrides<F, O>>}`, {
     tokens: BadOverrides<F, O>;
-}> : Unsatisfied<'fork accepts existing names or typed tokens only', {
+}> : Unsatisfied<`fork accepts existing names or typed tokens only: unknown ${NameText<Exclude<keyof O, keyof F>>}`, {
     extra: Exclude<keyof O, keyof F>;
 }>;
 export type Introduces<F extends Registrations, N extends Registrations> = [
@@ -132,14 +159,14 @@ export type IntroducesKeys<Known extends PropertyKey, New extends PropertyKey> =
     duplicates: Known & New;
 }>;
 export type Singleton<K> = [K] extends [never] ? false : [K] extends [string] ? true extends IsUnion<K> ? false : [NonFiniteKeys<Record<K & string, never>>] extends [never] ? true : false : false;
-export type ReplacementKey<R extends Registrations, K extends string> = Singleton<K> extends true ? K extends keyof R ? unknown : Unsatisfied<'replace requires one existing singleton string-literal key', {
+export type ReplacementKey<R extends Registrations, K extends string> = Singleton<K> extends true ? K extends keyof R ? unknown : Unsatisfied<`replace requires one existing singleton string-literal key: ${NameText<K>}`, {
     key: K;
-}> : Unsatisfied<'replace requires one existing singleton string-literal key', {
+}> : Unsatisfied<`replace requires one existing singleton string-literal key: ${NameText<K>}`, {
     key: K;
 }>;
-export type ReplacementKeyOf<Keys extends PropertyKey, K extends string> = Singleton<K> extends true ? K extends Keys ? unknown : Unsatisfied<'replace requires one existing singleton string-literal key', {
+export type ReplacementKeyOf<Keys extends PropertyKey, K extends string> = Singleton<K> extends true ? K extends Keys ? unknown : Unsatisfied<`replace requires one existing singleton string-literal key: ${NameText<K>}`, {
     key: K;
-}> : Unsatisfied<'replace requires one existing singleton string-literal key', {
+}> : Unsatisfied<`replace requires one existing singleton string-literal key: ${NameText<K>}`, {
     key: K;
 }>;
 type ReplacementRequirement<N, K extends PropertyKey> = K extends keyof N ? (value: N[K]) => void : never;
@@ -157,7 +184,7 @@ type InvalidElements<K extends readonly unknown[]> = {
 }[number];
 type InvalidMembers<R extends Registrations, T> = T extends string ? never : unknown extends TokenMember<R, T> ? never : T;
 /** Validate a finite tuple of existing singleton names or genuine typed tokens. */
-export type Selection<R extends Registrations, K extends readonly unknown[], Operation extends string = 'fork'> = true extends IsUnion<K> ? InvalidSelection<Operation> : number extends K['length'] ? InvalidSelection<Operation> : K extends Required<K> ? [InvalidElements<K>] extends [never] ? [Exclude<SelectionKey<K[number]>, keyof R> | InvalidMembers<R, K[number]>] extends [never] ? unknown : Unsatisfied<`${Operation} accepts existing names or typed tokens only`, {
+export type Selection<R extends Registrations, K extends readonly unknown[], Operation extends string = 'fork'> = true extends IsUnion<K> ? InvalidSelection<Operation> : number extends K['length'] ? InvalidSelection<Operation> : K extends Required<K> ? [InvalidElements<K>] extends [never] ? [Exclude<SelectionKey<K[number]>, keyof R> | InvalidMembers<R, K[number]>] extends [never] ? unknown : Unsatisfied<`${Operation} accepts existing names or typed tokens only: unknown ${NameText<Exclude<SelectionKey<K[number]>, keyof R> | InvalidMembers<R, K[number]>>}`, {
     extra: Exclude<SelectionKey<K[number]>, keyof R> | InvalidMembers<R, K[number]>;
 }> : InvalidSelection<Operation> : InvalidSelection<Operation>;
 type InvalidSelection<Operation extends string> = Unsatisfied<`${Operation} requires a finite tuple of singleton string-literal names or typed tokens`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "di-bag",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Type-checked dependency composition, private modules, and resource ownership for TypeScript apps and LLM harnesses.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,7 +18,9 @@
     "dist"
   ],
   "scripts": {
-    "test": "bun test tests",
+    "test": "npm run test:fast && npm run test:compiler",
+    "test:fast": "node scripts/test-lane.mjs fast",
+    "test:compiler": "node scripts/test-lane.mjs compiler",
     "typecheck": "tsc6 -p tsconfig.json",
     "typecheck:native": "tsc -p tsconfig.json",
     "build:native": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
@@ -33,6 +35,7 @@
     "check:platform": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON scripts/platform-evidence.ts --required",
     "docs:generate": "node tools/docs/generate.mjs",
     "docs:check": "node --test --test-isolation=none tools/docs/test/*.test.mjs && node tools/docs/generate.mjs --check && node tools/docs/site.mjs check",
+    "graph:check": "node --test tools/graph/test/*.test.mjs",
     "docs:build": "node tools/docs/site.mjs build",
     "docs:dev": "node tools/docs/site.mjs dev",
     "docs:preview": "node tools/docs/site.mjs preview",