di-bag 0.1.1 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,149 @@
+# DI Bag: notes for coding agents
+
+DI Bag composes TypeScript factories into a dependency graph that the compiler
+checks. Modules keep a feature's services private behind exported keys; a bag
+creates services on first use and releases what it owns when closed.
+
+This file ships in `node_modules/di-bag/`. Every call, with one way per task and an example:
+[docs/agent/api-card.md](docs/agent/api-card.md). Task recipes: [docs/agent/recipes.md](docs/agent/recipes.md).
+Every compiler and runtime message: [docs/agent/errors.md](docs/agent/errors.md).
+
+## Rules
+
+1. **Import from `di-bag`:** `import { DiBag } from 'di-bag';`. It configures
+   itself on Node, Bun, and Deno; `di-bag/node` is the same API in explicit form.
+   In browsers and workers `build()` throws
+   [`DI_BAG_CLASSIFIER_REQUIRED`](docs/agent/errors.md#di-bag-classifier-required)
+   for factories without an explicit `acquisitionMode`.
+2. **A factory declares its dependencies in the type of its one object
+   parameter; destructure it** (`({ clock }: { clock: Clock }) => ...`) or read
+   `deps.clock` directly. The object is a Proxy that resolves each property when
+   read: spreading it, `Object.keys`, `in`, and `JSON.stringify` throw
+   [`DI_BAG_INVALID_DEPENDENCY_ACCESS`](docs/agent/errors.md#di-bag-invalid-dependency-access).
+3. **Lifetimes.** The default is `scoped`: one instance per bag or child scope.
+   Mark a shared client `DiBag.withLifetime(factory, 'root')` only when nothing
+   it depends on is scoped; otherwise the compiler reports a
+   [root capture](docs/agent/errors.md#root-capture) naming both keys.
+   `'transient'` creates an instance on every read.
+4. **Async is explicit.** An async factory's service is its Promise. A consumer
+   declares `{ db: Promise<Db> }` and awaits it; nothing is awaited for you.
+5. **No thenables.** A factory that returns a non-Promise object with a `then`
+   method (query builders) is [rejected](docs/agent/errors.md#structural-thenable).
+   Return `Promise.resolve(builder)` or use `DiBag.fromFactory(create, { acquisitionMode: 'raw' })`.
+6. **Ownership.** `DiBag.withDisposal(factory, dispose)` makes the bag own the
+   value; `close()` runs disposers, dependents first. Close every scope and fork
+   you create. A parent closes its live scopes, never forks.
+7. **Replace dependencies in tests with `fork(keys, overrides)`**; each
+   override must satisfy the original contract.
+8. **Modules.** Register a feature's factories, then `buildModule(['exported'])`.
+   What its factories need and the module does not register becomes a
+   requirement: the host that calls `installModule(module)` must register it.
+   Pass `buildModule(keys, { label: 'billing' })` so messages name private
+   services `billing/store`.
+9. **Read a rejection at its name.** A graph error is an assignability error
+   whose type is `Unsatisfied<"message", details>`, reported where the builder
+   expression starts. `builder.verifyGraph() satisfies void;` reports the same
+   message on its own line; `"noErrorTruncation": true` prints the details.
+   Runtime errors carry `code` and `details`: branch on `code`, never on message
+   text. The section for a code is `docs/agent/errors.md#<code>`, lower-cased
+   with `_` replaced by `-`.
+
+## Module layout
+
+```text
+src/features/invoicing/
+  contract.ts        # exported service types and the requirements the host must supply
+  module.ts          # buildModule([...]) over the private factories
+  store.ts           # private services; free to use names other modules also use
+  check.ts           # type-checks this module alone; never imported, not built
+  tsconfig.json      # extends the root tsconfig and includes only this directory
+  invoicing.test.ts
+src/app.ts           # installs every module, one installModule call per line
+src/app.check.ts     # verifyGraph() on the application builder: the merge check
+```
+
+Inside a file, keep the same order: contract types, private factories, the
+sealed module, then the host. Exclude `check.ts` files and `src/app.check.ts`
+from an emitting build; they have no runtime purpose.
+
+A complete module:
+
+```ts
+// src/features/greeting/contract.ts
+export type Greeter = { greet(name: string): string };
+export type GreetingConfig = { greeting: string };
+```
+
+```ts
+// src/features/greeting/module.ts
+import { DiBag } from 'di-bag';
+import type { Greeter, GreetingConfig } from './contract.js';
+
+export const greetingModule = DiBag.createBuilder()
+  .register({
+    greeter: ({ config }: { config: GreetingConfig }): Greeter => ({
+      greet: name => `${config.greeting}, ${name}!`,
+    }),
+  })
+  .buildModule(['greeter']);
+```
+
+`check.ts` is one statement: install the module, register a typed fixture for
+each requirement, and verify.
+
+```ts
+// src/features/greeting/check.ts
+import { DiBag } from 'di-bag';
+import type { GreetingConfig } from './contract.js';
+import { greetingModule } from './module.js';
+
+DiBag.createBuilder()
+  .installModule(greetingModule)
+  .register({ config: (): GreetingConfig => ({ greeting: 'Hello' }) })
+  .verifyGraph() satisfies void;
+```
+
+## Check one module
+
+`src/features/<name>/tsconfig.json`:
+
+```json
+{
+  "extends": "../../../tsconfig.json",
+  "include": ["."]
+}
+```
+
+Type-check the module and its `check.ts` without the rest of the application:
+
+```sh
+npx tsc --noEmit -p src/features/<name>/tsconfig.json
+```
+
+A missing requirement fails with its key:
+`required service registrations are missing: config`.
+
+## Fast check
+
+Define `check:fast` in the consumer's `package.json` as the per-module
+type-check plus that module's tests, and run it after every edit:
+
+```json
+"check:fast": "tsc --noEmit -p src/features/$MODULE/tsconfig.json && tsx --test src/features/$MODULE/*.test.ts"
+```
+
+```sh
+MODULE=greeting npm run check:fast
+```
+
+Replace `tsx --test` with the project's test runner. Run the full type-check and
+test suite before merging: [review a merge](docs/agent/recipes.md#review-merge).
+
+## Recipes
+
+- [Add a request-scoped service with cleanup](docs/agent/recipes.md#add-scoped-service)
+- [Write a fixture test with `fork`](docs/agent/recipes.md#fixture-test)
+- [Split a feature into a module with private services](docs/agent/recipes.md#split-module)
+- [Debug a missing-dependency rejection](docs/agent/recipes.md#debug-missing-dependency)
+- [Add and consume an async client](docs/agent/recipes.md#async-client)
+- [Review a merge](docs/agent/recipes.md#review-merge)

package/README.md

@@ -1,18 +1,21 @@
 # DI Bag
 
-TypeScript dependency composition and resource ownership for agentic development, LLM harnesses, and agent graphs.
+TypeScript dependency composition and resource ownership for modular codebases,
+including the ones coding agents build one feature at a time.
 
-[Documentation](https://dany-fedorov.github.io/di-bag/) · [Quickstart](#quickstart) · [Agent harnesses](docs/guides/agent-harnesses-and-graphs.md) · [Comparison](#how-it-compares) · [Tutorial](docs/guides/tutorial.md) · [API reference](docs/guides/api-reference.md)
+[Documentation](https://dany-fedorov.github.io/di-bag/) · [Quickstart](#quickstart) · [Modules as units of work](#modules-as-units-of-work) · [Comparison](#how-it-compares) · [Tutorial](docs/guides/tutorial.md) · [API reference](docs/guides/api-reference.md)
 
 ## Why DI Bag?
 
 Compose ordinary TypeScript factories into reusable features. DI Bag checks
 declared dependencies, keeps module internals private, and manages resource
-creation and cleanup. Build services, tools, or graph nodes against explicit
-contracts, then replace their dependencies for tests.
+creation and cleanup. Build each feature against an explicit contract, test it
+with replaced dependencies, and let the compiler check the composition when
+independently developed features come together.
 
-- **[Reusable modules with private bindings](docs/guides/examples-modularity.md).**
-  Compose independently developed features without exposing their internals.
+- **[Modules a single owner can build in isolation](docs/guides/examples-modularity.md).**
+  A person or a coding agent implements one feature against its contract
+  without exposing its internals or reading another feature's source.
 - **[Compile-time wiring checks](docs/guides/examples-type-checking.md).**
   Catch missing dependencies and incompatible replacements before starting the app.
 - **[Metadata inspection without service startup](docs/guides/examples-extensibility.md).**
@@ -35,8 +38,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.
@@ -44,11 +45,11 @@ A **factory** creates a service. A **bag** holds those factories and gives each
 one access to the services it needs. Services are created when needed, and
 resources are cleaned up when you provide a disposer and close their bag.
 
-Use `di-bag/node` in Node or Bun. Here, `greeter` needs `config`. Its parameter
+Import from `di-bag`. Here, `greeter` needs `config`. Its parameter
 type describes that dependency, and its return value is the service it provides:
 
 ```ts
-import { DiBag } from 'di-bag/node';
+import { DiBag } from 'di-bag';
 
 const app = DiBag.createBuilder()
   .register({
@@ -102,7 +103,7 @@ An async factory provides a promise. Declare that promise in any dependent
 factory and await it where you need the value:
 
 ```ts
-import { DiBag } from 'di-bag/node';
+import { DiBag } from 'di-bag';
 
 const app = DiBag.createBuilder()
   .register({
@@ -124,7 +125,7 @@ factories keep returning ordinary values. See
 Wrap a factory with `withDisposal` to tell the bag how to release its result:
 
 ```ts
-import { DiBag } from 'di-bag/node';
+import { DiBag } from 'di-bag';
 
 const resources = DiBag.createBuilder()
   .register({
@@ -163,31 +164,37 @@ The [tutorial](docs/guides/tutorial.md) also covers modules with private service
 typed tokens, class and function adapters, optional and lazy dependencies,
 collections, startup, metadata, observers, and plugin validation.
 
-## LLM harnesses and agent graphs
-
-Compose an **LLM harness** from model clients, tools, context sources, and
-ordinary functions that serve as **agent graph** nodes.
-
-- **Explicit feature boundaries:** give each node or tool a small contract
-  and private implementation. Keep feature contracts and focused tests together;
-  select tools and context for the LLM in the harness.
-- **Contract checks and fixture tests:** check declared wiring before a model call,
-  then fork the composition with typed model and tool fixtures for deterministic
-  behavioral tests. Keep live-model evals for quality and task success.
-- **Inspectable capability descriptions:** describe public nodes and tools next
-  to their factories. Inspect that metadata without creating services, and use
-  it in application-defined catalogs, diagnostics, or dispatch policies.
-
-DI Bag's dependency graph describes how services are supplied. The agent graph
-describes execution: which node runs next and what state it receives. Your
-harness or graph framework owns routing, retries, persistence, and execution;
-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.
+## Modules as units of work
+
+A DI Bag **module** is the unit of work that one person or one coding agent can
+own: a directory with a small exported contract, private services, and its own
+tests. The composition is checked when the modules meet, so several modules can
+be developed in parallel and merged with confidence.
+
+- **A boundary an owner can hold.** `buildModule(keys)` seals a feature and
+  exports only the named services. Private services and their types stay
+  inside, and two modules can use the same private names without collision.
+- **Verification without the whole application.** A module type-checks
+  against the contracts it declares. `fork()` replaces its external
+  dependencies with typed fixtures for deterministic tests, so a module's tests
+  need neither the other modules nor live clients.
+- **Checks at merge time.** Installing every module into one builder is where
+  independently developed work meets. A missing requirement, an incompatible
+  replacement, or a contract that no longer matches its consumers fails at
+  `build()` or `verifyGraph()`. The `di-bag-graph` tool exports the declared
+  edges and cycles for review.
+
+For discovery, the directory layout is the map: one directory per module, the
+contract first. The [modularity guide](docs/guides/examples-modularity.md)
+describes the recommended layout and shows separately owned features, isolated
+tests, and contributed tools in three runnable programs.
+
+DI Bag's dependency graph describes how services are supplied, not what runs
+next. LLM harnesses and agent graphs are one application of the module pattern:
+model clients, tools, and context sources become modules, and the harness or
+graph framework owns routing, retries, persistence, and execution. The
+[agent harness and graph guide](docs/guides/agent-harnesses-and-graphs.md) is a
+complete example.
 
 ## How it compares
 
@@ -214,12 +221,13 @@ The package has **zero runtime dependencies** and two entry points:
 
 | Import | Purpose |
 | --- | --- |
-| `di-bag/node` | Ready-to-use factory composition in Node and Bun, with native Promise detection. |
-| `di-bag` | Portable core for other hosts, including Deno and bundled browsers. Use explicit acquisition modes or configure a trusted native Promise predicate. |
+| `di-bag` | The entry to use. Configures native Promise detection itself on Node, Bun, and Deno through `process.getBuiltinModule`; has no `node:` imports, so it also bundles for browsers. |
+| `di-bag/node` | The same API with detection configured explicitly at import, for Node and Bun. |
 
-The portable entry rejects automatic acquisition stages unless you configure a
-trusted classifier. See [portable mode](docs/guides/tutorial.md#portable-mode)
-for both setup options.
+On hosts without `process.getBuiltinModule` (browsers, workers), `build()`
+rejects automatic acquisition stages unless you configure a trusted classifier
+or give each stage an explicit acquisition mode. See
+[portable mode](docs/guides/tutorial.md#portable-mode) for both options.
 
 ## Tradeoffs and limits
 
@@ -227,11 +235,13 @@ for both setup options.
   boundaries, manage an agent's context window, or replace behavioral tests.
 - **Async dependencies are explicit.** A factory returning `Promise<T>` exposes
   that promise. Consumers declare and await it themselves.
-- **Cleanup waits for your work.** Cancellation is cooperative; a factory or
-  disposer that never settles can keep `close()` pending.
+- **Cleanup waits for your work by default.** Cancellation is cooperative; a
+  factory or disposer that never settles keeps `close()` pending. Pass
+  `close({ timeoutMs, signal })` to stop waiting: the rejection names the
+  disposers still running and cleanup continues in the background.
 - **Type safety follows the declared graph.** Casts, unchecked JavaScript, and
   unknown plugins need appropriate runtime checks. Dependency cycles are detected
-  at runtime.
+  at runtime, or before running by [`di-bag-graph`](tools/graph/README.md).
 - **Graph types have a compiler cost.** Very long fluent expressions can exceed
   compiler limits. Classic TypeScript still fails the recorded 1,000-call named
   registration and replacement cases; use bulk registration or smaller groups.
@@ -247,13 +257,15 @@ for both setup options.
 | [Complete tutorial](docs/guides/tutorial.md) | Learn every public API through examples, from first composition to advanced ownership. |
 | [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. |
+| [Radical modularity](docs/guides/examples-modularity.md) | The recommended module layout, separately owned features, isolated tests, and contributed tools. |
+| [Agent docs](AGENTS.md) | Rules, module layout, and check commands for coding agents, with [recipes](docs/agent/recipes.md) and [errors](docs/agent/errors.md). Shipped in the package. |
+| [Agent harnesses and graphs](docs/guides/agent-harnesses-and-graphs.md) | One worked application: model and tool modules, metadata inspection, and node tests with typed fixtures. |
+| [Static dependency graph](docs/agent/recipes.md#review-merge) | Export every builder chain, declared edge, and cycle to JSON with `di-bag-graph` for merge review and CI. |
 | [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,14 +1,20 @@
 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. */
+/**
+ * Cooperative cancellation information supplied to a context-aware acquisition.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#start-selected-services-and-cancel-cooperatively
+ */
 export interface AcquisitionContext {
     /** Aborted when the acquisition's owning scope begins closing. */
     readonly signal: AbortSignal;
 }
 type ContextFactory = (this: void, deps: never, context: AcquisitionContext) => unknown;
-/** The named-dependency factory contract retained by an acquisition-context callback. */
+/**
+ * The named-dependency factory contract retained by an acquisition-context callback.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#start-selected-services-and-cancel-cooperatively
+ */
 export type ContextualFactory<F extends ContextFactory> = (this: void, deps: Parameters<F> extends [] ? {} : Parameters<F>[0]) => ReturnType<F>;
 type FactoryOptions<M extends AcquisitionMode> = 'auto' extends M ? [options?: {
     readonly context?: never;
@@ -26,7 +32,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 +44,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,11 +1,15 @@
 import type { LifecycleObservers } from './observers';
-import type { Unsatisfied } from './types';
+import type { SeeErrors, StructuralThenable, Unsatisfied } from './types';
 /**
  * How an acquisition stage treats its returned value: configured classification,
  * the exact raw value, or an observed native Promise fulfillment.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#portable-mode
  */
 export type AcquisitionMode = 'auto' | 'raw' | 'nativePromise';
-/** Portable facade configuration for `auto` acquisition stages. */
+/**
+ * Portable facade configuration for `auto` acquisition stages.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#portable-mode
+ */
 export interface RuntimeOptions {
     /** Return true only for native Promises the host can observe without thenable assimilation. */
     readonly isNativePromise: (this: void, value: unknown) => boolean;
@@ -28,7 +32,10 @@ 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${SeeErrors<'structural-thenable'>}`, {}> : unknown : unknown;
 export declare function acquisitionMode(options: {
     readonly acquisitionMode?: AcquisitionMode;
 } | undefined, fallback?: AcquisitionMode): AcquisitionMode;
-export declare function requireClassificationCapability(modes: Iterable<AcquisitionMode>, context: RuntimeContext): void;
+/** Resolve the classifier when a graph first needs one; a configured classifier always wins. */
+export declare function requireClassifier(context: RuntimeContext): RuntimeContext;

package/dist/acquisition-mode.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.unconfigured = void 0;
 exports.runtimeContext = runtimeContext;
 exports.acquisitionMode = acquisitionMode;
-exports.requireClassificationCapability = requireClassificationCapability;
+exports.requireClassifier = requireClassifier;
 const errors_1 = require("./errors");
 exports.unconfigured = Object.freeze({});
 function runtimeContext(options, previous = exports.unconfigured) {
@@ -25,11 +25,29 @@ function acquisitionMode(options, fallback = 'auto') {
         throw (0, errors_1.libraryError)('DI_BAG_INVALID_ACQUISITION_MODE', 'invalid acquisitionMode: use auto, raw, or nativePromise', { option: 'acquisitionMode' });
     return mode;
 }
-function requireClassificationCapability(modes, context) {
+/**
+ * Read the host classifier through `process.getBuiltinModule` (Node, Bun, Deno). A call, not an
+ * import, keeps `node:` specifiers out of the root entry's module graph for bundlers and browsers.
+ */
+function hostClassifier() {
+    const host = globalThis.process;
+    if (typeof host !== 'object' || host === null)
+        return undefined;
+    const load = host.getBuiltinModule;
+    if (typeof load !== 'function')
+        return undefined;
+    const types = Reflect.apply(load, host, ['node:util/types']);
+    if (typeof types !== 'object' || types === null)
+        return undefined;
+    const { isPromise } = types;
+    return typeof isPromise === 'function' ? isPromise : undefined;
+}
+/** Resolve the classifier when a graph first needs one; a configured classifier always wins. */
+function requireClassifier(context) {
     if (context.isNativePromise)
-        return;
-    for (const mode of modes)
-        if (mode === 'auto') {
-            throw (0, errors_1.libraryError)('DI_BAG_CLASSIFIER_REQUIRED', 'Automatic acquisition classification requires DiBag.withConfiguration({ runtime }), di-bag/node, or explicit acquisitionMode options', { option: 'runtime.isNativePromise' });
-        }
+        return context;
+    const isNativePromise = hostClassifier();
+    if (isNativePromise)
+        return Object.freeze({ ...context, isNativePromise });
+    throw (0, errors_1.libraryError)('DI_BAG_CLASSIFIER_REQUIRED', 'this host has no process.getBuiltinModule; configure DiBag.withConfiguration({ runtime: { isNativePromise } }) or give each automatic registration an explicit acquisitionMode', { option: 'runtime.isNativePromise' });
 }

package/dist/acquisition.d.ts

@@ -32,9 +32,15 @@ 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>;
+    /** Labels of this scope's running disposers and of acquisitions close is still draining. */
+    collectProgress(pending: string[], acquiring: string[]): void;
     private getContext;
     private resolveBinding;
     private eventFields;

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))) });
@@ -137,6 +138,15 @@ class ScopeAcquisitions {
         });
         return this.closing;
     }
+    /** Labels of this scope's running disposers and of acquisitions close is still draining. */
+    collectProgress(pending, acquiring) {
+        for (const attempt of this.attempts.values()) {
+            if (attempt.state === 'disposing' || this.retired.has(attempt.id))
+                pending.push(attempt.label);
+            else if (attempt.state === 'creating' || attempt.state === 'pending')
+                acquiring.push(attempt.label);
+        }
+    }
     getContext() {
         if (!this.acquisitionContext) {
             this.controller = new AbortController();
@@ -239,8 +249,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 +263,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/alias-types.d.ts

@@ -6,14 +6,23 @@ import type { Singleton, Unsatisfied } from './types';
 export type AliasSelection = string | TokenBase;
 export type AliasAdmission<T> = Singleton<T> extends true ? unknown : ValidToken<T> extends true ? unknown : Unsatisfied<'alias requires one singleton name or genuine token', {}>;
 export type AliasTarget<R extends Registrations, T> = T extends string ? T extends keyof R ? unknown : Unsatisfied<'alias requires an existing named target', {}> : [WrongToken<T, R>] extends [never] ? unknown : Unsatisfied<'token dependency has an incompatible or opaque contract', {}>;
-/** Resolve the service type exposed by a possible alias target. */
+/**
+ * Resolve the service type exposed by a possible alias target.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#give-a-dependency-another-lookup-name
+ */
 export type AliasOutput<R extends Registrations, T> = T extends string ? T extends keyof R ? ProviderOutput<R[T]> : never : TokenService<T>;
 export type AliasDestination<R extends Registrations, D, T> = D extends TokenBase ? [AliasOutput<R, T>] extends [TokenService<D>] ? unknown : Unsatisfied<'alias output is not assignable to destination service', {}> : unknown;
-/** A provider contract that forwards a destination to a canonical target acquisition. */
+/**
+ * A provider contract that forwards a destination to a canonical target acquisition.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#give-a-dependency-another-lookup-name
+ */
 export type AliasRegistration<R extends Registrations, D, T> = Provider<(this: void, deps: T extends string ? Record<T, AliasOutput<R, T>> : Record<never, never>) => AliasOutput<R, T>, Readonly<object>, readonly unknown[], TokenDependencyContract<T extends TokenBase ? readonly [T] : readonly [], D extends TokenBase ? D : never> & {
     readonly alias: SelectionKey<T>;
 }, unknown>;
-/** The single registration-map entry introduced by an alias operation. */
+/**
+ * The single registration-map entry introduced by an alias operation.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#give-a-dependency-another-lookup-name
+ */
 export type AliasEntries<R extends Registrations, D, T> = Record<SelectionKey<D>, AliasRegistration<R, D, T>>;
 /** Reflected generic methods cannot introduce a checked singleton destination. */
 export type AliasEntry<R extends Registrations, D, T> = unknown extends AliasAdmission<D> & AliasAdmission<T> ? {

package/dist/composition-report.d.ts

@@ -0,0 +1,14 @@
+import type { Builder } from './di-bag';
+import type { CheckedLifetimes } from './lifetime-types';
+import type { CheckedConstraints, CompleteConstraints, NeedConstraint } from './module-types';
+import type { CheckDependencyCompatibility, CheckDependencyCompleteness, ConsumerReport, Entry, RegistrationsFromEntries } from './types';
+type ReportOf<Check> = unknown extends Check ? never : Check;
+type Reports<E extends Entry, C extends NeedConstraint> = ReportOf<ConsumerReport<CheckDependencyCompatibility<RegistrationsFromEntries<E>>>> | ReportOf<CheckDependencyCompleteness<RegistrationsFromEntries<E>>> | ReportOf<ConsumerReport<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>`.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#read-compile-time-rejections
+ */
+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 });