di-bag 0.5.0 → 0.5.2

package/AGENTS.md

@@ -4,8 +4,8 @@ DI Bag composes TypeScript factories into a dependency graph that the compiler
 checks. Modules keep a feature's services private behind exported keys; a container
 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).
+This file and `docs/agent/` ship in `node_modules/di-bag/`; the guides live at https://dany-fedorov.github.io/di-bag/, where `llms.txt` indexes these agent pages.
+Every call, one way per task, with 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
 

package/README.md

@@ -1,53 +1,66 @@
 # DI Bag
 
-TypeScript dependency composition and resource ownership for modular codebases.
-Built for coding agents that ship one feature at a time.
+Dependency injection for TypeScript where the compiler checks the wiring.
+A module keeps a feature's services private behind named exports; a container
+creates services on first use and releases what it owns when closed.
+
+[![CI](https://github.com/dany-fedorov/di-bag/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/dany-fedorov/di-bag/actions/workflows/ci.yml)
+[![Runtime dependencies: 0](https://img.shields.io/badge/runtime_dependencies-0-2563eb)](package.json)
+[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](LICENSE)
 
 [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)
 
+Using a coding agent? The rules, the API card, the recipes, and every error
+message ship in the package. Paste this into your agent:
+
+```text
+If di-bag is installed: read node_modules/di-bag/AGENTS.md first and follow its rules.
+Use node_modules/di-bag/docs/agent/api-card.md for a call's signature and example,
+node_modules/di-bag/docs/agent/recipes.md for a task, and
+node_modules/di-bag/docs/agent/errors.md for a compiler or runtime message.
+
+If di-bag is not installed: evaluate it from these pages before deciding.
+- https://dany-fedorov.github.io/di-bag/ : what it does, the compiler check, a module in one screen
+- https://dany-fedorov.github.io/di-bag/llms-full.txt : AGENTS.md, the API card, recipes, and errors in one file
+- https://dany-fedorov.github.io/di-bag/guides/examples-modularity.html : the module layout and three runnable programs
+- https://dany-fedorov.github.io/di-bag/guides/comparison.html : how it differs from Awilix, InversifyJS, TSyringe, Typed Inject, Effect, and NestJS
+To install: npm install di-bag. It needs TypeScript 6.0.3 or later with "strict": true and has no
+runtime dependencies. Node, Bun, and Deno need nothing else; in browsers and workers, pass
+factoryReturnKind to each factory. After installing, read node_modules/di-bag/AGENTS.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 disposal. 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.
-
-- **[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 creating services](docs/guides/examples-extensibility.md).**
-  Build capability catalogs without running factories or opening clients.
-- **[Inject anything with a simple factory function](docs/guides/examples-plain-services.md).**
-  Supply functions, objects, clients, or promises without decorators or base classes.
+- **A missing dependency is a type error, not a crash on the first request.**
+  Delete a factory and `tsc` names the missing service. Change a contract and
+  `tsc` rejects the consumer that no longer fits. [See it](#what-the-compiler-catches).
+- **One feature is one directory that type-checks alone.** A module exports
+  only the services it names; everything else stays private, so modules written
+  separately can reuse the same internal names without colliding. A one-statement
+  check file and a per-module `tsconfig.json` verify the module without the rest
+  of the application. [See a module](#a-module-in-one-screen).
+- **Resources have one owner.** Attach a disposer to a factory and `close()`
+  runs it, dependents first. A child container per request releases what the
+  request acquired. [See ownership](#give-resources-a-clear-owner).
+
+No decorators, no reflection metadata, no base classes, and zero runtime
+dependencies. Runs on Node, Bun, Deno, browsers, and workers.
 
 ## Install
 
-Install [di-bag from npm](https://www.npmjs.com/package/di-bag):
-
 ```sh
 npm install di-bag
 ```
 
-The API is pre-1.0 and includes breaking changes. Run the 0.4-to-0.5 codemod
-before upgrading, then review the changelog and the
-[0.5 migration guide](docs/guides/migrating-to-0.5.md).
-
-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 workers, see [runtime support](#runtime-support).
+TypeScript 6.0.3 or later with `strict` enabled. Browsers and workers need one
+extra option per factory; see [runtime support](#runtime-support). Coming from
+0.4? See [upgrading](#upgrading).
 
 ## Quickstart
 
-A **service** can be a configuration object, a database client, or a function.
-A **factory** creates a service. A **container** resolves its factories' declared
-dependencies. Services are created when needed. The container disposes owned
-resources when you close it.
-
-Import from `di-bag`. Here, `greeter` needs `config`. Its parameter
-type describes that dependency, and its return value is the service it provides:
+A **factory** creates a **service**. The type of a factory's one object
+parameter declares what it depends on. A **container** calls factories on first
+use:
 
 ```ts
 import { DiBag } from 'di-bag';
@@ -68,14 +81,80 @@ console.log(greeter.greet('Ada')); // Hello, Ada!
 await app.close();
 ```
 
-`withServices({...})` adds factories to an immutable builder. `buildContainer()`
-checks the declared graph and creates a container. `resolve('greeter')` creates
-the greeter and its config on first use. The default scoped lifetime returns the
-same greeter on later resolutions in this container. Provider order does not matter.
+`resolve('greeter')` creates the greeter and its config the first time, and
+returns the same greeter afterwards. TypeScript knows that `greeter` has a
+`greet(name: string): string` method, with no cast and no token.
+
+## What the compiler catches
+
+Remove the `config` factory. `buildContainer()` no longer type-checks, and the
+message names the missing service:
+
+```ts
+import { DiBag } from 'di-bag';
+
+const incomplete = DiBag.createBuilder().withServices({
+  greeter: ({ config }: { config: { greeting: string } }) => ({
+    greet(name: string) {
+      return `${config.greeting}, ${name}!`;
+    },
+  }),
+});
+
+// @ts-expect-error required services are missing: config
+incomplete.buildContainer();
+```
+
+```text
+required services are missing: config; see https://dany-fedorov.github.io/di-bag/agent/errors.html#missing-service
+```
+
+Change `greeting` to a number and, with default settings, the message is
+`provided service does not satisfy its consumer dependency`. With
+`"noErrorTruncation": true` in `tsconfig.json`, the details name the consumer,
+the dependency, the expected type, and the provided type. The
+[error index](https://dany-fedorov.github.io/di-bag/agent/errors.html#compile-time) lists every message with its
+cause and fix. The directive above is not decoration: this repository compiles
+the block in CI, and an unused `@ts-expect-error` fails the build.
+
+## A module in one screen
+
+A module is a builder sealed with the names it exports. The host supplies what
+the module requires. In a project each comment below is a file; the layout and
+the per-module check command are in [AGENTS.md](AGENTS.md#module-layout).
 
-TypeScript knows that `greeter` has a `greet(name: string): string` method.
-Removing the `config` factory makes `buildContainer()` a compile-time error. Changing
-`greeting` to a number also fails the type check because the greeter needs a string.
+```ts
+import { DiBag } from 'di-bag';
+
+// src/features/greeting/contract.ts: what the module exports and what it needs
+type Greeter = { greet(name: string): string };
+type GreetingConfig = { greeting: string };
+
+// src/features/greeting/module.ts: private factories, named exports
+const greetingModule = DiBag.createBuilder()
+  .withServices({
+    template: ({ config }: { config: GreetingConfig }) => config.greeting,
+    greeter: ({ template }: { template: string }): Greeter => ({
+      greet: name => `${template}, ${name}!`,
+    }),
+  })
+  .buildModule({ exportedServiceKeys: ['greeter'], moduleLabel: 'greeting' });
+
+// src/app.ts: the host supplies config; template stays private
+const app = DiBag.createBuilder()
+  .withInstalledModules([greetingModule])
+  .withServices({ config: (): GreetingConfig => ({ greeting: 'Hello' }) })
+  .buildContainer();
+
+console.log(app.resolve('greeter').greet('Ada')); // Hello, Ada!
+await app.close();
+```
+
+`app.resolve('template')` is a type error: the module did not export it. Leave
+out the `config` factory and the host fails with
+`required services are missing: config`. Another module may also call a private
+service `template`; the names never meet. [Modules as units of work](#modules-as-units-of-work)
+explains the layout, the check file, and the merge check.
 
 ## Swap a dependency for a test
 
@@ -160,7 +239,7 @@ be asynchronous. Dependents close before their dependencies, and resources that
 were never created need no disposal. Ordinary factories return borrowed values.
 Having a `close()` method alone does not transfer ownership to the container.
 
-## Child and independent containers {#child-and-independent-containers}
+## Child and independent containers
 
 | Operation | What it creates | Who closes it? |
 | --- | --- | --- |
@@ -173,48 +252,42 @@ An unmarked provider is scoped. Choose singleton explicitly when child container
 
 For request handling, checked test replacements, and loading dynamic features,
 see the [server guide](docs/guides/server-integration.md) and
-[integration recipes](docs/guides/enterprise-integration.md).
+[Integration patterns](docs/guides/enterprise-integration.md).
 
-The [tutorial](docs/guides/tutorial.md) also covers modules with private services,
+The [tutorial](docs/guides/tutorial.md) also covers
 typed tokens, class and function adapters, optional and lazy dependencies,
 collections, service readiness, metadata, observers, and plugin validation.
 
 ## 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 module is the unit of work one person or one coding agent can own: a
+directory with a small exported contract, private services, and its own tests.
+Composition is checked when the modules meet, so several can be developed in
+parallel and merged with confidence.
 
-- **A boundary an owner can hold.** `buildModule({ exportedServiceKeys })` seals a feature and
+- **A boundary an owner can hold.** `buildModule({ exportedServiceKeys })`
   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 declares what its host
-  must supply. A small check file installs the module with typed fixtures and calls
-  `verifyGraphAtCompileTime()`. Tests can use `createIndependentContainer(keys, providers)`
-  for checked replacements without live clients.
+  inside, and two modules can use the same private names.
+- **Verification without the whole application.** A module declares what its
+  host must supply. A one-statement check file installs the module with typed
+  fixtures and calls `verifyGraphAtCompileTime()`; tests use
+  `createIndependentContainer(keys, providers)` for checked replacements.
 - **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
-  `buildContainer()` or `verifyGraphAtCompileTime()`. The `di-bag-graph` tool exports the declared
-  edges and cycles for review.
-
-Install modules with `withInstalledModules([...])`. If two modules require the
-same name for different contracts, rename each requirement before installation
-with `withRenamedRequirement({ currentRequirementKey, newRequirementKey })`. Use
-`withRenamedExport({ currentExportKey, newExportKey })` for colliding exports.
-
-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.
+  independently developed work meets. A missing requirement or a contract that
+  no longer matches its consumers fails at `buildContainer()` or
+  `verifyGraphAtCompileTime()`; `di-bag-graph` exports the declared edges and
+  cycles for review.
+
+If two modules require the same name for different contracts, rename each
+requirement at the install site with
+`withRenamedRequirement({ currentRequirementKey, newRequirementKey })`, and
+colliding exports with `withRenamedExport({ currentExportKey, newExportKey })`.
+
+The directory layout is the map: one directory per module, the contract first.
+The [modules guide](docs/guides/examples-modularity.md) shows the layout and
+three runnable programs. LLM harnesses and agent graphs are one application of
+the pattern; the [agent harness guide](docs/guides/agent-harnesses-and-graphs.md)
+is a complete example.
 
 ## How it compares
 
@@ -269,7 +342,7 @@ Promise factories with `'native-promise'`. See
 - **Framework integration belongs to the application.** DI Bag provides the
   composition and ownership primitives; the host connects request, job, or UI
   lifecycles. The [server guide](docs/guides/server-integration.md) and the
-  [React guide](docs/guides/react-integration.md) are tested recipes for both.
+  [React guide](docs/guides/react-integration.md) are recipes for both; the React recipe runs in CI, the server recipes compile where they import only `di-bag` and `node:*`.
 
 ## Explore further
 
@@ -279,22 +352,18 @@ Promise factories with `'native-promise'`. See
 | [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 containers, service readiness, and shutdown. |
 | [React guide](docs/guides/react-integration.md) | Browser applications: one app runtime at bootstrap, project runtimes owned from effects, Strict Mode, cancellation, bounded teardown, and `useSyncExternalStore`. |
-| [Radical modularity](docs/guides/examples-modularity.md) | The recommended module layout, separately owned features, isolated tests, and contributed tools. |
+| [Modules as units of work](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, child containers, and provider metadata. |
-| [Integration guide](docs/guides/enterprise-integration.md) | Tested recipes for request ownership, substitutions, and dynamic features. |
+| [Static dependency graph](https://dany-fedorov.github.io/di-bag/agent/recipes.html#review-merge) | Export every builder chain, declared edge, and cycle to JSON with `di-bag-graph` for merge review and CI. |
+| [Runnable examples](examples/README.md) | One program per topic: modules, tokens, composition, collections, plugins, observers, child containers, and provider metadata. |
+| [Integration patterns](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. |
 | [Development and verification](docs/guides/development.md) | Full checks, portable runtime testing, compiler scale, and performance evidence. |
 | [Documentation map](docs/README.md) | Every guide, the generated reference, and the contributor documents. |
 
 ## Working on DI Bag
 
-[![CI](https://github.com/dany-fedorov/di-bag/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/dany-fedorov/di-bag/actions/workflows/ci.yml)
-[![Runtime dependencies: 0](https://img.shields.io/badge/runtime_dependencies-0-2563eb)](package.json)
-[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](LICENSE)
-
 After `npm ci`, run the main checks with Node and Bun installed:
 
 ```sh
@@ -307,6 +376,17 @@ Run an example with `bun run examples/composition.ts`. The
 [development guide](docs/guides/development.md) covers the remaining compiler,
 platform, and packaging checks and their tool requirements.
 
+## Upgrading
+
+The API is pre-1.0 and includes breaking changes. Run the 0.4-to-0.5 codemod
+before upgrading, while the 0.4 types are still installed, then read the
+[0.5 migration guide](docs/guides/migrating-to-0.5.md) and the
+[changelog](CHANGELOG.md):
+
+```sh
+npx di-bag-codemod --project tsconfig.json --write
+```
+
 ## License
 
 [MIT](LICENSE) © Dany Fedorov

package/dist/acquisition-context.d.ts

@@ -7,6 +7,22 @@ import type { TokenDependencyContract } from './token-types';
  * service disposer — the `withDisposal` on the value this factory returned — has
  * just run. Ownership a consumer attaches to a transformed value does not count.
  * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#release-partial-acquisition
+ * @example
+ * ```ts
+ * type Socket = { close(): Promise<void> };
+ * declare function open(url: string): Promise<Socket>;
+ * declare function authenticate(connection: Socket): Promise<void>;
+ * const socket = DiBag.providerWithDisposal({
+ *   provider: DiBag.createProvider(async ({ url }: { url: string }, factoryContext) => {
+ *     const connection = await open(url);
+ *     // Runs at once if authenticate() rejects; at close() it sees 'service-disposed' and does nothing.
+ *     factoryContext.pushDisposer(async disposerContext => { if (disposerContext.reason !== 'service-disposed') await connection.close(); });
+ *     await authenticate(connection);
+ *     return connection;
+ *   }, { factoryReceivesContext: true }),
+ *   disposeService: connection => connection.close(),
+ * });
+ * ```
  */
 export interface DisposerContext {
     /**
@@ -22,12 +38,39 @@ export interface DisposerContext {
  * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#make-selected-services-ready
  */
 export interface FactoryContext {
-    /** Aborted when the acquisition's owning container begins closing. */
+    /**
+     * Return the signal that aborts when the acquisition's owning container begins closing.
+     * @example
+     * ```ts
+     * declare function fetchCatalog(signal: AbortSignal): Promise<string[]>;
+     * const catalog = DiBag.createProvider(async (_dependencies: {}, factoryContext) => fetchCatalog(factoryContext.abortSignal), {
+     *   factoryReceivesContext: true, factoryReturnKind: 'native-promise',
+     * });
+     * const container = DiBag.createBuilder().withServices({ catalog }).buildContainer();
+     * const names: Promise<string[]> = container.resolve('catalog'); // close() aborts the signal while fetchCatalog is pending
+     * await container.close();
+     * ```
+     */
     readonly abortSignal: AbortSignal;
     /**
-     * Own a resource acquired during this factory call; pushed disposers run once in reverse order.
+     * Attach a disposer for a resource acquired during this factory call; pushed disposers run once in reverse order.
      * Pass the release callback itself, such as `() => socket.close()`, rather than calling it here.
      * @param disposer - Releases the acquired resource when the factory fails or the container closes.
+     * @throws `DI_BAG_DISPOSER_PUSHED_AFTER_FACTORY` when called after the factory settled.
+     * @example
+     * ```ts
+     * declare function openLock(name: string): Promise<{ release(): Promise<void> }>;
+     * declare function verify(name: string): Promise<void>;
+     * const worker = DiBag.createProvider(async ({ name }: { name: string }, factoryContext) => {
+     *   const lock = await openLock(name);
+     *   factoryContext.pushDisposer(() => lock.release()); // released at close(), or at once if verify() rejects
+     *   await verify(name);
+     *   return { name };
+     * }, { factoryReceivesContext: true });
+     * const container = DiBag.createBuilder().withServices({ name: () => 'nightly', worker }).buildContainer();
+     * const started: Promise<{ name: string }> = container.resolve('worker');
+     * await container.close(); // runs lock.release() after the worker settled
+     * ```
      */
     pushDisposer(this: void, disposer: (this: void, disposerContext: DisposerContext) => void | Promise<void>): void;
 }

package/dist/di-bag.d.ts

@@ -79,6 +79,7 @@ declare class Container<ServiceRegistrations extends Registrations, Constraints
      * ```ts
      * const container = DiBag.createBuilder().withServices({ greeting: () => 'hello' }).buildContainer();
      * const snapshot = container.serviceSnapshot('greeting');
+     * console.log(snapshot.bindingLabel, snapshot.acquisitions.length); // greeting 0
      * await container.close();
      * ```
      */
@@ -108,8 +109,12 @@ declare class Container<ServiceRegistrations extends Registrations, Constraints
      * @returns A frozen point-in-time graph snapshot without acquiring services.
      * @example
      * ```ts
-     * const container = DiBag.createBuilder().withServices({ greeting: () => 'hello' }).buildContainer();
-     * const labels = container.graphSnapshot().bindings.map(binding => binding.bindingLabel);
+     * const billing = DiBag.createBuilder().withServices({ ledger: () => new Map<string, number>() })
+     *   .buildModule({ exportedServiceKeys: ['ledger'], moduleLabel: 'billing' });
+     * const container = DiBag.createBuilder().withInstalledModules([billing]).buildContainer();
+     * const graph = container.graphSnapshot();
+     * const installation = graph.moduleInstallations[0]!; // { installationId, moduleLabel: 'billing', parentInstallationId: undefined }
+     * const owned = graph.bindings.filter(binding => binding.moduleInstallationId === installation.installationId).map(binding => binding.bindingLabel); // ['ledger']
      * await container.close();
      * ```
      */

package/dist/di-bag.js

@@ -129,8 +129,12 @@ class Container {
      * @returns A frozen point-in-time graph snapshot without acquiring services.
      * @example
      * ```ts
-     * const container = DiBag.createBuilder().withServices({ greeting: () => 'hello' }).buildContainer();
-     * const labels = container.graphSnapshot().bindings.map(binding => binding.bindingLabel);
+     * const billing = DiBag.createBuilder().withServices({ ledger: () => new Map<string, number>() })
+     *   .buildModule({ exportedServiceKeys: ['ledger'], moduleLabel: 'billing' });
+     * const container = DiBag.createBuilder().withInstalledModules([billing]).buildContainer();
+     * const graph = container.graphSnapshot();
+     * const installation = graph.moduleInstallations[0]!; // { installationId, moduleLabel: 'billing', parentInstallationId: undefined }
+     * const owned = graph.bindings.filter(binding => binding.moduleInstallationId === installation.installationId).map(binding => binding.bindingLabel); // ['ledger']
      * await container.close();
      * ```
      */

package/dist/index.d.ts

@@ -18,7 +18,7 @@ export type { ReboundProviders, ReboundSelection } from './types';
 export type { CanonicalLifetime, ChildReplacementAdmission, CheckedChildContainerLifetimes, CheckedLifetimes, LifetimeObligation, Reach } 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, BindingSnapshot, GraphSnapshot } from './inspection';
+export type { Presence, AcquisitionMetadataPresence, AcquisitionSnapshot, RegistrationSnapshot, BindingSnapshot, ModuleInstallationSnapshot, GraphSnapshot } from './inspection';
 export type { PositionalFactoryArguments, PositionalFactoryFunction } from './composition';
 export type { OptionalDependency, LazyDependency, DependencyReference } from './dependency-references';
 export type { PluginOutputValidator, PluginProvider } from './plugins';

package/dist/inspection.d.ts

@@ -53,6 +53,8 @@ export interface RegistrationSnapshot<M = Readonly<{}>, A extends readonly unkno
  * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#attach-metadata-and-inspect-without-resolving
  */
 export interface BindingSnapshot<M = Readonly<{}>, A extends readonly unknown[] = readonly []> extends RegistrationSnapshot<M, A> {
+    /** Innermost module installation that introduced this binding; absent for host declarations and host replacements. */
+    readonly moduleInstallationId: symbol | undefined;
     /** Public names or token symbols that select this binding, in service key order; empty for a private module binding. */
     readonly serviceKeys: readonly (string | symbol)[];
     readonly lifetime: Lifetime;
@@ -65,6 +67,15 @@ export interface BindingSnapshot<M = Readonly<{}>, A extends readonly unknown[]
         readonly dependencyKind: 'required' | 'optional' | 'lazy';
     }[];
 }
+/** One occurrence of a sealed module in a container graph. */
+export interface ModuleInstallationSnapshot {
+    /** Stable identity for this occurrence in the graph. */
+    readonly installationId: symbol;
+    /** Exact label supplied when the module was sealed, if any. */
+    readonly moduleLabel: string | undefined;
+    /** Enclosing installation, if this module was installed inside another module. */
+    readonly parentInstallationId: symbol | undefined;
+}
 /**
  * A frozen description of every binding a container can resolve, plus the edges observed so far.
  * Named dependencies read from a factory's object parameter are not knowable until the factory
@@ -73,6 +84,8 @@ export interface BindingSnapshot<M = Readonly<{}>, A extends readonly unknown[]
  */
 export interface GraphSnapshot {
     readonly containerId: symbol;
+    /** Module occurrences in installation order, with each parent preceding its contiguous descendants. */
+    readonly moduleInstallations: readonly ModuleInstallationSnapshot[];
     /** Public bindings in service key order, then contributions in group order, then remaining private bindings. */
     readonly bindings: readonly BindingSnapshot<object, readonly unknown[]>[];
     readonly contributions: readonly {

package/dist/module.d.ts

@@ -39,6 +39,16 @@ declare class Module<ExportedServices extends object, RequiredServices extends o
     /** @internal */
     readonly [moduleInvariant]: (value: [ExportedServices, RequiredServices, Constraints, PublicProviders]) => [ExportedServices, RequiredServices, Constraints, PublicProviders];
     constructor(description: ModuleDescription);
+    /**
+     * Return the exact label supplied when this module was sealed, if any. Reading it never acquires a service.
+     * @example
+     * ```ts
+     * const feature = DiBag.createBuilder().withServices({ answer: () => 42 })
+     *   .buildModule({ exportedServiceKeys: ['answer'], moduleLabel: 'answers' });
+     * const label: string | undefined = feature.moduleLabel; // 'answers'
+     * ```
+     */
+    get moduleLabel(): string | undefined;
     /**
      * Return a module view with one string-named export renamed through an options object.
      * @param options - The current export and its noncolliding new name.
@@ -49,6 +59,9 @@ declare class Module<ExportedServices extends object, RequiredServices extends o
      * const feature = DiBag.createBuilder().withServices({ service: () => 1 })
      *   .buildModule({ exportedServiceKeys: ['service'] });
      * const renamed = feature.withRenamedExport({ currentExportKey: 'service', newExportKey: 'featureService' });
+     * const app = DiBag.createBuilder().withInstalledModules([renamed]).buildContainer();
+     * const value: number = app.resolve('featureService');
+     * await app.close();
      * ```
      */
     withRenamedExport<const CurrentExportKey extends string, const NewExportKey extends string>(options: {

package/dist/module.js

@@ -27,6 +27,18 @@ class Module {
         });
         Object.freeze(this);
     }
+    /**
+     * Return the exact label supplied when this module was sealed, if any. Reading it never acquires a service.
+     * @example
+     * ```ts
+     * const feature = DiBag.createBuilder().withServices({ answer: () => 42 })
+     *   .buildModule({ exportedServiceKeys: ['answer'], moduleLabel: 'answers' });
+     * const label: string | undefined = feature.moduleLabel; // 'answers'
+     * ```
+     */
+    get moduleLabel() {
+        return descriptions.get(this).label;
+    }
     /**
      * Return a module view with one string-named export renamed through an options object.
      * @param options - The current export and its noncolliding new name.
@@ -37,6 +49,9 @@ class Module {
      * const feature = DiBag.createBuilder().withServices({ service: () => 1 })
      *   .buildModule({ exportedServiceKeys: ['service'] });
      * const renamed = feature.withRenamedExport({ currentExportKey: 'service', newExportKey: 'featureService' });
+     * const app = DiBag.createBuilder().withInstalledModules([renamed]).buildContainer();
+     * const value: number = app.resolve('featureService');
+     * await app.close();
      * ```
      */
     withRenamedExport(options) {
@@ -171,6 +186,19 @@ function moduleGraph(value, index) {
         throw (0, errors_1.libraryError)('DI_BAG_INVALID_MODULE', `withInstalledModules requires genuine modules: element ${index} is not one`, { operation: 'withInstalledModules', index });
     }
     const { graph, exports, label, requirementRenames } = description;
+    const installationId = Symbol('module installation');
+    const remapped = new Map();
+    for (const nested of graph.moduleInstallations ?? [])
+        remapped.set(nested.installationId, Symbol('module installation'));
+    const moduleInstallations = [
+        { installationId, moduleLabel: label, parentInstallationId: undefined },
+        ...(graph.moduleInstallations ?? []).map(nested => ({
+            installationId: remapped.get(nested.installationId),
+            moduleLabel: nested.moduleLabel,
+            parentInstallationId: nested.parentInstallationId === undefined
+                ? installationId : remapped.get(nested.parentInstallationId),
+        })),
+    ];
     const exported = new Set();
     for (const localKey of exports.values())
         exported.add(graph.publicSlots.get(localKey));
@@ -219,6 +247,8 @@ function moduleGraph(value, index) {
         bindings.set(fresh, {
             id: fresh, label: labelOf(id, binding), registration: binding.registration,
             localNames: localNamesFor(binding),
+            moduleInstallationId: binding.moduleInstallationId === undefined
+                ? installationId : remapped.get(binding.moduleInstallationId),
         });
     }
     const publicSlots = new Map();
@@ -232,5 +262,6 @@ function moduleGraph(value, index) {
         publicSlots,
         contributions,
         tokenKinds: new Map(graph.tokenKinds ?? []),
+        moduleInstallations,
     };
 }

package/dist/runtime.d.ts

@@ -1,7 +1,7 @@
 import { ScopeAcquisitions } from './acquisition';
 import { normalize } from './registration';
 import type { ProviderOrFactory, Registrations } from './registration';
-import type { GraphSnapshot, RegistrationSnapshot } from './inspection';
+import type { GraphSnapshot, ModuleInstallationSnapshot, RegistrationSnapshot } from './inspection';
 import type { RuntimeContext } from './acquisition-mode';
 import { type TokenKind } from './tokens';
 import type { LifetimeKind } from './lifetime';
@@ -19,12 +19,14 @@ export interface BindingDescription {
     readonly label: string;
     readonly registration: ProviderOrFactory;
     readonly localNames: ReadonlyMap<BindingKey, BindingRef>;
+    readonly moduleInstallationId?: symbol;
 }
 export interface GraphDescription {
     readonly bindings: ReadonlyMap<BindingId, BindingDescription>;
     readonly publicSlots: ReadonlyMap<BindingKey, BindingId>;
     readonly contributions?: ReadonlyMap<symbol, readonly BindingId[]>;
     readonly tokenKinds?: ReadonlyMap<symbol, TokenKind>;
+    readonly moduleInstallations?: readonly ModuleInstallationSnapshot[];
 }
 type Normalized = Readonly<ReturnType<typeof normalize>>;
 /** Immutable descriptions and path-copied lookup storage. Retained maps never escape. */
@@ -60,6 +62,8 @@ export declare class BindingGraph {
     registration(id: BindingId): Normalized;
     private requireRegistration;
     label(id: BindingId): string;
+    moduleInstallationId(id: BindingId): symbol | undefined;
+    moduleInstallations(): readonly ModuleInstallationSnapshot[];
     withPublicRegistrations(registrations: Registrations, operation?: string): BindingGraph;
     /** Replace ordered slots and prune only unreferenced public replacement history. */
     withPublicBindings(entries: readonly (readonly [BindingKey, ProviderOrFactory])[], operation?: string): BindingGraph;

package/dist/runtime.js

@@ -12,6 +12,7 @@ const tokens_1 = require("./tokens");
 const lifetime_1 = require("./lifetime");
 const emptyContributions = Object.freeze([]);
 const emptyNames = new Map();
+const emptyModuleInstallations = Object.freeze([]);
 /** Immutable descriptions and path-copied lookup storage. Retained maps never escape. */
 class BindingGraph {
     #bindings = new persistent_map_1.PersistentMap();
@@ -32,12 +33,16 @@ class BindingGraph {
     // First public registration order by key, for module snapshots. Keys are
     // never unregistered, so this retains nothing a graph would otherwise drop.
     #publicOrder;
+    #moduleInstallations;
     #bindingCache = new Map();
     #registrationCache = new Map();
     #publicCache = new Map();
     #contributionCache = new Map();
     #explicitlyClassified = false;
     constructor(description = { bindings: new Map(), publicSlots: new Map() }) {
+        if (description.moduleInstallations?.length) {
+            this.#moduleInstallations = { values: Object.freeze(description.moduleInstallations.map(record => Object.freeze({ ...record }))) };
+        }
         const declaredKinds = description.tokenKinds ?? new Map();
         const lexicalSnapshots = new Map();
         for (const [id, binding] of description.bindings) {
@@ -59,7 +64,10 @@ class BindingGraph {
             this.#lexicalUsers = this.#lexicalUsers.set(lexical.id, (this.#lexicalUsers.get(lexical.id) ?? 0) + 1);
             const entry = {
                 lexical,
-                description: Object.freeze({ id: binding.id, label: binding.label, registration: binding.registration, localNames: lexical.names }),
+                description: Object.freeze({
+                    id: binding.id, label: binding.label, registration: binding.registration, localNames: lexical.names,
+                    ...(binding.moduleInstallationId === undefined ? {} : { moduleInstallationId: binding.moduleInstallationId }),
+                }),
                 normalized: Object.freeze((0, registration_1.normalize)(binding.registration)),
             };
             this.retainBindingTokenKinds(entry, 'withInstalledModules');
@@ -98,6 +106,7 @@ class BindingGraph {
         graph.#tokenKindOwners = this.#tokenKindOwners;
         graph.#directTokenKinds = this.#directTokenKinds;
         graph.#publicOrder = this.#publicOrder;
+        graph.#moduleInstallations = this.#moduleInstallations;
         return graph;
     }
     entry(id) {
@@ -253,6 +262,12 @@ class BindingGraph {
         return registration;
     }
     label(id) { return (this.#bindingCache.get(id) ?? this.entry(id)?.description)?.label ?? String(id); }
+    moduleInstallationId(id) {
+        return (this.#bindingCache.get(id) ?? this.entry(id)?.description)?.moduleInstallationId;
+    }
+    moduleInstallations() {
+        return this.#moduleInstallations ? (0, persistent_sequence_1.materialize)(this.#moduleInstallations) : emptyModuleInstallations;
+    }
     withPublicRegistrations(registrations, operation = 'register') {
         return this.withPublicBindings(Object.keys(registrations).map(key => [key, registrations[key]]), operation);
     }
@@ -360,7 +375,7 @@ class BindingGraph {
         for (const [key, kind] of this.#tokenKinds) {
             tokenKinds.set(key, kind);
         }
-        return { bindings, publicSlots, contributions, tokenKinds };
+        return { bindings, publicSlots, contributions, tokenKinds, moduleInstallations: this.moduleInstallations() };
     }
     /** Every retained binding in `describe()` order, with the public keys that select it. */
     bindingSummaries() {
@@ -396,6 +411,9 @@ class BindingGraph {
             this.assertTokenKind(key, kind, operation);
         }
         const graph = this.copy();
+        if (description.moduleInstallations?.length) {
+            graph.#moduleInstallations = (0, persistent_sequence_1.append)(graph.#moduleInstallations, installation.#moduleInstallations);
+        }
         const pending = [];
         // Publish all incoming protection before releasing overwritten descriptions.
         for (const [id, count] of installation.#lexicalUsers)
@@ -485,6 +503,7 @@ class BagRuntime {
             const description = this.graph.registration(id);
             return Object.freeze({
                 ...this.inspectBinding(id),
+                moduleInstallationId: this.graph.moduleInstallationId(id),
                 serviceKeys: keys,
                 lifetime: (0, lifetime_1.publicLifetime)(description.lifetime.kind),
                 factoryReturnKind: description.factoryReturnKind,
@@ -494,6 +513,7 @@ class BagRuntime {
         });
         return Object.freeze({
             containerId: this.acquisitions.ownerId,
+            moduleInstallations: this.graph.moduleInstallations(),
             bindings: Object.freeze(bindings),
             contributions: this.graph.contributionGroups(),
             observedEdges: this.acquisitions.observedEdges(),

package/docs/agent/api-card.md

@@ -12,9 +12,14 @@ An example without an import line uses `import { DiBag } from 'di-bag';`. The ru
 | --- | --- |
 | Start a graph | [`DiBag.createBuilder()`](#dibag-createbuilder) |
 | Register services by name | [`builder.withServices(providersByName)`](#builder-withservices) |
+| Register the service of a typed token | [`builder.withTokenService(token, provider)`](#builder-withtokenservice) |
 | Create a collection token | [`DiBag.createToken(symbol)`](#dibag-createtoken) |
 | Contribute a collection member | [`builder.withCollectionContribution(options)`](#builder-withcollectioncontribution) |
+| Give a service a second name | [`builder.withServiceAlias(options)`](#builder-withservicealias) |
+| Replace a provider in a builder | [`builder.withReplacedService(serviceKey, provider)`](#builder-withreplacedservice) |
 | Register a portable factory | [`DiBag.createProvider(factory, options)`](#dibag-createprovider) |
+| Adapt a class to positional dependencies | [`DiBag.createProviderFromClass(options)`](#dibag-createproviderfromclass) |
+| Adapt a positional function | [`DiBag.createProviderFromFunction(options)`](#dibag-createproviderfromfunction) |
 | Attach disposal | [`DiBag.providerWithDisposal(options)`](#dibag-providerwithdisposal) |
 | Choose a lifetime | [`DiBag.providerWithLifetime(options)`](#dibag-providerwithlifetime) |
 | Attach registration metadata | [`DiBag.providerWithRegistrationMetadata(options)`](#dibag-providerwithregistrationmetadata) |
@@ -23,6 +28,8 @@ An example without an import line uses `import { DiBag } from 'di-bag';`. The ru
 | Seal a module | [`builder.buildModule(options)`](#builder-buildmodule) |
 | Install modules | [`builder.withInstalledModules(modules)`](#builder-withinstalledmodules) |
 | Rename a module requirement | [`module.withRenamedRequirement(options)`](#module-withrenamedrequirement) |
+| Rename a module export | [`module.withRenamedExport(options)`](#module-withrenamedexport) |
+| Read the label a module was sealed with | [`module.moduleLabel`](#module-modulelabel) |
 | Check the graph on its own line | [`builder.verifyGraphAtCompileTime()`](#builder-verifygraphatcompiletime) |
 | Build a container | [`builder.buildContainer()`](#builder-buildcontainer) |
 | Wait for services before accepting work | [`container.ensureServicesReady(serviceKeys, options?)`](#container-ensureservicesready) |
@@ -30,7 +37,11 @@ An example without an import line uses `import { DiBag } from 'di-bag';`. The ru
 | Open a child container | [`container.createChildContainer(options?)`](#container-createchildcontainer) |
 | Resolve | [`container.resolve(token)`](#container-resolve) |
 | Resolve a collection | [`container.resolveCollection(token)`](#container-resolvecollection) |
+| Inspect one service without resolving it | [`container.serviceSnapshot(serviceKey)`](#container-servicesnapshot) |
+| Inspect every binding and module installation | [`container.graphSnapshot()`](#container-graphsnapshot) |
 | Close | [`container.close(options?)`](#container-close) |
+| Own a resource acquired inside a factory | [`factoryContext.pushDisposer(disposer)`](#factorycontext-pushdisposer) |
+| Stop factory work when the container closes | [`factoryContext.abortSignal`](#factorycontext-abortsignal) |
 
 ## DiBag facade {#dibag-facade}
 
@@ -203,6 +214,25 @@ await app.close();
 
 ## Module {#module}
 
+### `module.moduleLabel` {#module-modulelabel}
+Return the exact label supplied when this module was sealed, if any.
+```ts
+const feature = DiBag.createBuilder().withServices({ answer: () => 42 })
+  .buildModule({ exportedServiceKeys: ['answer'], moduleLabel: 'answers' });
+const label: string | undefined = feature.moduleLabel; // 'answers'
+```
+
+### `module.withRenamedExport(options)` {#module-withrenamedexport}
+Return a module view with one string-named export renamed through an options object. Throws: [`DI_BAG_INVALID_ARGUMENT`](errors.md#di-bag-invalid-argument), [`DI_BAG_UNKNOWN_SERVICE_KEY`](errors.md#di-bag-unknown-service-key).
+```ts
+const feature = DiBag.createBuilder().withServices({ service: () => 1 })
+  .buildModule({ exportedServiceKeys: ['service'] });
+const renamed = feature.withRenamedExport({ currentExportKey: 'service', newExportKey: 'featureService' });
+const app = DiBag.createBuilder().withInstalledModules([renamed]).buildContainer();
+const value: number = app.resolve('featureService');
+await app.close();
+```
+
 ### `module.withRenamedRequirement(options)` {#module-withrenamedrequirement}
 Return a module view that asks its host for a requirement under a new name. Throws: [`DI_BAG_INVALID_ARGUMENT`](errors.md#di-bag-invalid-argument), [`DI_BAG_UNKNOWN_SERVICE_KEY`](errors.md#di-bag-unknown-service-key), [`DI_BAG_DUPLICATE_SERVICE_KEY`](errors.md#di-bag-duplicate-service-key).
 ```ts
@@ -239,14 +269,19 @@ Inspect a service binding through any supported public key without resolving it.
 ```ts
 const container = DiBag.createBuilder().withServices({ greeting: () => 'hello' }).buildContainer();
 const snapshot = container.serviceSnapshot('greeting');
+console.log(snapshot.bindingLabel, snapshot.acquisitions.length); // greeting 0
 await container.close();
 ```
 
 ### `container.graphSnapshot()` {#container-graphsnapshot}
 Describe every resolvable binding and the dependency edges observed so far.
 ```ts
-const container = DiBag.createBuilder().withServices({ greeting: () => 'hello' }).buildContainer();
-const labels = container.graphSnapshot().bindings.map(binding => binding.bindingLabel);
+const billing = DiBag.createBuilder().withServices({ ledger: () => new Map<string, number>() })
+  .buildModule({ exportedServiceKeys: ['ledger'], moduleLabel: 'billing' });
+const container = DiBag.createBuilder().withInstalledModules([billing]).buildContainer();
+const graph = container.graphSnapshot();
+const installation = graph.moduleInstallations[0]!; // { installationId, moduleLabel: 'billing', parentInstallationId: undefined }
+const owned = graph.bindings.filter(binding => binding.moduleInstallationId === installation.installationId).map(binding => binding.bindingLabel); // ['ledger']
 await container.close();
 ```
 
@@ -288,6 +323,36 @@ const container = DiBag.createBuilder().withServices({ value: () => 1 }).buildCo
 await container.close({ waitTimeoutMs: 10_000, abortSignal: AbortSignal.timeout(15_000) });
 ```
 
+## Factory context {#factory-context}
+
+### `factoryContext.abortSignal` {#factorycontext-abortsignal}
+Return the signal that aborts when the acquisition's owning container begins closing.
+```ts
+declare function fetchCatalog(signal: AbortSignal): Promise<string[]>;
+const catalog = DiBag.createProvider(async (_dependencies: {}, factoryContext) => fetchCatalog(factoryContext.abortSignal), {
+  factoryReceivesContext: true, factoryReturnKind: 'native-promise',
+});
+const container = DiBag.createBuilder().withServices({ catalog }).buildContainer();
+const names: Promise<string[]> = container.resolve('catalog'); // close() aborts the signal while fetchCatalog is pending
+await container.close();
+```
+
+### `factoryContext.pushDisposer(disposer)` {#factorycontext-pushdisposer}
+Attach a disposer for a resource acquired during this factory call; pushed disposers run once in reverse order. Throws: [`DI_BAG_DISPOSER_PUSHED_AFTER_FACTORY`](errors.md#di-bag-disposer-pushed-after-factory).
+```ts
+declare function openLock(name: string): Promise<{ release(): Promise<void> }>;
+declare function verify(name: string): Promise<void>;
+const worker = DiBag.createProvider(async ({ name }: { name: string }, factoryContext) => {
+  const lock = await openLock(name);
+  factoryContext.pushDisposer(() => lock.release()); // released at close(), or at once if verify() rejects
+  await verify(name);
+  return { name };
+}, { factoryReceivesContext: true });
+const container = DiBag.createBuilder().withServices({ name: () => 'nightly', worker }).buildContainer();
+const started: Promise<{ name: string }> = container.resolve('worker');
+await container.close(); // runs lock.release() after the worker settled
+```
+
 ## Errors {#errors}
 
 ### `DiBagPluginValidationError` {#dibagpluginvalidationerror}

package/docs/agent/errors.md

@@ -828,7 +828,7 @@ functions that only throw. `details.removed` names the old call and
 
 **Fix:** write the replacement. For a whole project, run `npx di-bag-codemod`
 BEFORE upgrading, while the 0.4.0 types are still installed; see the
-[migration guide](../guides/migrating-to-0.5.md).
+[migration guide](https://dany-fedorov.github.io/di-bag/guides/migrating-to-0.5.html).
 
 ```ts
 import { DiBag } from 'di-bag';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "di-bag",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "DI container for agent-built codebases: the compiler checks the wiring, modules stay private, resources get cleaned up.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",