di-bag 0.4.0 → 0.5.0

package/AGENTS.md

@@ -1,66 +1,63 @@
 # 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
+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 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.
-   For browsers and workers register with `DiBag.fromSyncFactory` / `fromAsyncFactory`
-   ([portable recipe](docs/agent/recipes.md#portable-graph)); a plain factory there fails
-   `build()` with [`DI_BAG_CLASSIFIER_REQUIRED`](docs/agent/errors.md#di-bag-classifier-required), which names it.
+   itself on Node, Bun, and Deno; use the same root import on every runtime.
+   For browsers and workers register synchronous factories with
+   `DiBag.createProvider(factory, { factoryReturnKind: 'sync-value' })`; use
+   `'native-promise'` for a factory that returns a native Promise
+   ([portable recipe](docs/agent/recipes.md#portable-graph)); an auto-detect factory there fails
+   `buildContainer()` with [`DI_BAG_CLASSIFIER_REQUIRED`](docs/agent/errors.md#di-bag-classifier-required), which names it.
 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
+   `dependencies.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.
+3. **Lifetimes.** The default is `'scoped:one-per-container'`. Mark a shared client
+   `'singleton:one-per-container-tree'` only when nothing it depends on is scoped.
+   A child may replace only scoped or transient services; use an independent container
+   to replace a singleton.
 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
-   returned value; `close()` runs disposers, dependents first. Close every scope and
-   fork you create; a parent closes its live scopes, never forks. Inside a factory,
-   [`factoryCtx.pushDisposer`](docs/agent/recipes.md#partial-acquisition) owns what it acquires on the way; if that is also the returned value, act only when `disposerCtx.reason !== 'service-disposed'`.
-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`.
+   Return `Promise.resolve(builder)` or use `DiBag.createProvider(create, { factoryReturnKind: 'uninspected' })`.
+6. **Ownership.** Use `DiBag.providerWithDisposal({ provider, disposeService })`.
+   `close()` runs disposers, dependents first. Close every child and
+   independent container; a parent closes its live children, never independent containers. Inside a factory,
+   [`factoryContext.pushDisposer`](docs/agent/recipes.md#partial-acquisition) owns what it acquires on the way; if that is also the returned value, act only when `disposerContext.reason !== 'service-disposed'`.
+7. **Replace dependencies in tests with `createIndependentContainer(keys, providers)`**; each provider must satisfy the original contract.
+8. **Modules.** Add factories with `withServices`, then
+   `buildModule({ exportedServiceKeys: ['exported'], moduleLabel: 'billing' })`.
+   Unregistered needs become requirements: the host supplies them after
+   `withInstalledModules([module])`. Rename colliding string requirements with module.withRenamedRequirement({ currentRequirementKey, newRequirementKey }); tokens keep their global identity.
 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 `-`.
+   expression starts. `builder.verifyGraphAtCompileTime() 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
+  module.ts          # buildModule({ exportedServiceKeys: [...] }) 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
+src/app.ts           # installs modules in one withInstalledModules([...]) list
+src/app.check.ts     # verifyGraphAtCompileTime() on the application builder: the merge check
 ```
 
 Inside a file, keep the same order: contract types, private factories, the
@@ -81,15 +78,15 @@ import { DiBag } from 'di-bag';
 import type { Greeter, GreetingConfig } from './contract.js';
 
 export const greetingModule = DiBag.createBuilder()
-  .register({
+  .withServices({
     greeter: ({ config }: { config: GreetingConfig }): Greeter => ({
       greet: name => `${config.greeting}, ${name}!`,
     }),
   })
-  .buildModule(['greeter']);
+  .buildModule({ exportedServiceKeys: ['greeter'] });
 ```
 
-`check.ts` is one statement: install the module, register a typed fixture for
+`check.ts` is one statement: install the module, add a typed fixture for
 each requirement, and verify.
 
 ```ts
@@ -99,9 +96,11 @@ import type { GreetingConfig } from './contract.js';
 import { greetingModule } from './module.js';
 
 DiBag.createBuilder()
-  .installModule(greetingModule)
-  .register({ config: (): GreetingConfig => ({ greeting: 'Hello' }) })
-  .verifyGraph() satisfies void;
+  .withInstalledModules([
+    greetingModule,
+  ])
+  .withServices({ config: (): GreetingConfig => ({ greeting: 'Hello' }) })
+  .verifyGraphAtCompileTime() satisfies void;
 ```
 
 ## Check one module
@@ -122,7 +121,7 @@ npx tsc --noEmit -p src/features/<name>/tsconfig.json
 ```
 
 A missing requirement fails with its key:
-`required service registrations are missing: config`.
+`required services are missing: config`.
 
 ## Fast check
 
@@ -143,7 +142,7 @@ 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)
+- [Write a fixture test with an independent container](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)

package/README.md

@@ -9,7 +9,7 @@ Built for coding agents that ship one feature at a time.
 
 Compose ordinary TypeScript factories into reusable features. DI Bag checks
 declared dependencies, keeps module internals private, and manages resource
-creation and cleanup. Build each feature against an explicit contract, test it
+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.
 
@@ -18,10 +18,10 @@ independently developed features come together.
   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).**
+- **[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—no decorators or base classes.
+  Supply functions, objects, clients, or promises without decorators or base classes.
 
 ## Install
 
@@ -31,19 +31,20 @@ Install [di-bag from npm](https://www.npmjs.com/package/di-bag):
 npm install di-bag
 ```
 
-The API is pre-1.0 and includes breaking changes, so review the changelog and
-migration guides when updating.
+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 Deno, see [runtime support](#runtime-support).
+For browsers and workers, see [runtime support](#runtime-support).
 
 ## Quickstart
 
 A **service** can be a configuration object, a database client, or a function.
-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.
+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:
@@ -52,7 +53,7 @@ type describes that dependency, and its return value is the service it provides:
 import { DiBag } from 'di-bag';
 
 const app = DiBag.createBuilder()
-  .register({
+  .withServices({
     config: () => ({ greeting: 'Hello' }),
     greeter: ({ config }: { config: { greeting: string } }) => ({
       greet(name: string) {
@@ -60,28 +61,37 @@ const app = DiBag.createBuilder()
       },
     }),
   })
-  .build();
+  .buildContainer();
 
 const greeter = app.resolve('greeter');
 console.log(greeter.greet('Ada')); // Hello, Ada!
+await app.close();
 ```
 
-`.register()` adds factories to an immutable builder, `.build()` checks the
-declared graph and creates the bag, and
-`resolve('greeter')` creates the greeter and the config it needs. Resolving
-`greeter` again returns the same instance. Registration order does not matter.
+`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.
 
 TypeScript knows that `greeter` has a `greet(name: string): string` method.
-Removing the `config` factory makes `.build()` a compile-time error. Changing
+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.
 
 ## Swap a dependency for a test
 
-Use `fork()` to create a separate bag with a replacement dependency.
-Continuing the [quickstart](#quickstart):
+Use `createIndependentContainer()` for a test with a replacement dependency.
+This example uses the graph from the [quickstart](#quickstart):
 
 ```ts
-const testApp = app.fork(['config'], {
+import { DiBag } from 'di-bag';
+
+const app = DiBag.createBuilder().withServices({
+  config: () => ({ greeting: 'Hello' }),
+  greeter: ({ config }: { config: { greeting: string } }) =>
+    ({ greet: (name: string) => `${config.greeting}, ${name}!` }),
+}).buildContainer();
+
+const testApp = app.createIndependentContainer(['config'], {
   config: () => ({ greeting: 'Hi' }),
 });
 
@@ -90,12 +100,13 @@ try {
   console.log(app.resolve('greeter').greet('Ada')); // Hello, Ada!
 } finally {
   await testApp.close();
+  await app.close();
 }
 ```
 
-The replacement must satisfy the original service contract. Each fork has
-independent acquisition and cleanup ownership; close it separately. Factories
-can still return shared objects captured outside the fork.
+The replacement must satisfy the original service contract. Each independent
+container owns its own acquisitions and disposal. Close it separately. Factories
+can still return shared objects captured outside the container.
 
 ## Work with async services
 
@@ -106,35 +117,36 @@ factory and await it where you need the value:
 import { DiBag } from 'di-bag';
 
 const app = DiBag.createBuilder()
-  .register({
+  .withServices({
     greeting: async () => 'Hello',
     message: async ({ greeting }: { greeting: Promise<string> }) =>
       `${await greeting}, Ada!`,
   })
-  .build();
+  .buildContainer();
 
 console.log(await app.resolve('message')); // Hello, Ada!
+await app.close();
 ```
 
-By default, repeated resolutions share the same in-flight promise. Synchronous
+Within one container, repeated resolutions share the same pending promise. Synchronous
 factories keep returning ordinary values. See
 [async behavior](docs/guides/tutorial.md#async-edges-are-explicit) for details.
 
 ## Give resources a clear owner
 
-Wrap a factory with `withDisposal` to tell the bag how to release its result:
+Use `DiBag.providerWithDisposal` to tell the container how to release a factory's result:
 
 ```ts
 import { DiBag } from 'di-bag';
 
 const resources = DiBag.createBuilder()
-  .register({
-    cache: DiBag.withDisposal(
-      () => new Map<string, string>(),
-      (cache) => cache.clear(),
-    ),
+  .withServices({
+    cache: DiBag.providerWithDisposal({
+      provider: () => new Map<string, string>(),
+      disposeService: cache => cache.clear(),
+    }),
   })
-  .build();
+  .buildContainer();
 
 try {
   resources.resolve('cache').set('answer', '42');
@@ -143,18 +155,21 @@ try {
 }
 ```
 
-The same pattern works for connections, clients, and subscriptions. Cleanup can
+The same pattern works for connections, clients, and subscriptions. Disposal can
 be asynchronous. Dependents close before their dependencies, and resources that
-were never created need no cleanup. Ordinary factories return borrowed values;
-having a `close()` method alone does not transfer ownership to the bag.
+were never created need no disposal. Ordinary factories return borrowed values.
+Having a `close()` method alone does not transfer ownership to the container.
 
-## Scopes and forks
+## Child and independent containers {#child-and-independent-containers}
 
 | Operation | What it creates | Who closes it? |
 | --- | --- | --- |
-| `bag.createScope()` | A tracked child with fresh scoped services; root services are shared | Close it when its work ends. The parent also closes live children. |
-| `bag.fork()` | An independent bag with the same registrations and fresh instances | The caller closes it separately. |
-| `bag.fork(keys, overrides)` | An independent bag with selected dependencies replaced | The caller closes it separately. |
+| `container.createChildContainer()` | A tracked child with its own scoped services | Close it when its work ends. The parent closes live children. |
+| `container.createChildContainer(keys, providers)` | A tracked child with selected scoped or transient services replaced | Close it when its work ends. The parent closes live children. |
+| `container.createIndependentContainer()` | A separate container with fresh instances | The caller closes it separately. |
+| `container.createIndependentContainer(keys, providers)` | A separate container with selected dependencies replaced | The caller closes it separately. |
+
+An unmarked provider is scoped. Choose singleton explicitly when child containers should share it.
 
 For request handling, checked test replacements, and loading dynamic features,
 see the [server guide](docs/guides/server-integration.md) and
@@ -162,7 +177,7 @@ see the [server guide](docs/guides/server-integration.md) and
 
 The [tutorial](docs/guides/tutorial.md) also covers modules with private services,
 typed tokens, class and function adapters, optional and lazy dependencies,
-collections, startup, metadata, observers, and plugin validation.
+collections, service readiness, metadata, observers, and plugin validation.
 
 ## Modules as units of work
 
@@ -171,19 +186,24 @@ 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
+- **A boundary an owner can hold.** `buildModule({ exportedServiceKeys })` 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.
+- **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.
 - **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
+  `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
@@ -204,30 +224,28 @@ async factories, and TypeScript support are also available in other libraries.
 
 | Alternative | Reasons to choose it | DI Bag's different emphasis |
 | --- | --- | --- |
-| Manual dependency injection | Direct function calls may be all a small application needs. TypeScript checks their arguments. | Adds lazy caching, graph-wide composition checks, scopes, and coordinated cleanup. |
+| Manual dependency injection | Direct function calls may be all a small application needs. TypeScript checks their arguments. | Adds lazy caching, graph-wide composition checks, child containers, and coordinated disposal. |
 | Awilix | Function and class registration, inferred cradle types, lifetime options, and runtime strict checks. | Checks declared factory requirements against the registrations at compile time. |
 | InversifyJS / TSyringe | Token and class-oriented containers; Inversify also offers decorator-free factory bindings and awaited async resolution. | Starts with object-parameter factories and immutable builders; checks accumulated graph contracts. |
-| Typed Inject | A close alternative with compile-time dependency checks, explicit dependency tuples, child injectors, and disposal. | Adds object-parameter dependencies, forward references, private module exports, and selected startup with rollback. |
-| Effect Context / Layer | Typed requirements, scoped resources, and composition within Effect's broader async and error model. | Keeps ordinary `T` and `Promise<T>` service values and explicit bag lifecycles. |
+| Typed Inject | A close alternative with compile-time dependency checks, explicit dependency tuples, child injectors, and disposal. | Adds object-parameter dependencies, forward references, private module exports, and selected service readiness with rollback. |
+| Effect Context / Layer | Typed requirements, scoped resources, and composition within Effect's broader async and error model. | Keeps ordinary `T` and `Promise<T>` service values and explicit container ownership. |
 | NestJS / Angular DI | Their native containers connect directly to framework components, testing tools, and lifecycles. | Provides standalone composition; applications supply the framework integration. |
 
 See the [comparison guide](docs/guides/comparison.md) for primary sources,
-differences in async and cleanup behavior, and the limits of these comparisons.
+differences in async and disposal behavior, and the limits of these comparisons.
 There is no verified performance ranking against these libraries.
 
 ## Runtime support
 
-The package has **zero runtime dependencies** and two entry points:
-
-| Import | Purpose |
-| --- | --- |
-| `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 package has **zero runtime dependencies** and one entry point: `di-bag`.
+The root import configures native Promise detection on Node, Bun, and Deno.
+It also bundles for browsers and workers because it has no `node:` imports.
 
-On hosts without `process.getBuiltinModule` (browsers, workers), `build()`
-rejects automatic acquisition stages and names them. Register with
-`DiBag.fromSyncFactory` / `DiBag.fromAsyncFactory` there, or configure a trusted
-classifier. See [portable mode](docs/guides/tutorial.md#portable-mode).
+In browsers and workers, `buildContainer()` names any factory that needs an
+explicit return kind. Register synchronous factories with
+`DiBag.createProvider(factory, { factoryReturnKind: 'sync-value' })` and native
+Promise factories with `'native-promise'`. See
+[portable mode](docs/guides/tutorial.md#portable-mode).
 
 ## Tradeoffs and limits
 
@@ -235,10 +253,10 @@ classifier. See [portable mode](docs/guides/tutorial.md#portable-mode).
   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 by default.** Cancellation is cooperative; a
+- **Disposal 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.
+  `close({ waitTimeoutMs, abortSignal })` to stop waiting. The rejection names the
+  disposers still running, and disposal 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, or before running by [`di-bag-graph`](tools/graph/README.md).
@@ -259,13 +277,13 @@ classifier. See [portable mode](docs/guides/tutorial.md#portable-mode).
 | --- | --- |
 | [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. |
+| [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. |
 | [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. |
+| [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. |
 | [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. |

package/dist/acquisition-context.d.ts

@@ -1,6 +1,6 @@
 import type { Provider } from './provider';
 import type { Factory } from './registration';
-import type { Acquired, AcquisitionMode, AsyncOutput, AutoOutput, NativeOutput, ModeOptions, SyncOutput } from './acquisition-mode';
+import type { Acquired, FactoryReturnKind, NativeOutput, AutoOutput, SyncOutput } from './acquisition-mode';
 import type { TokenDependencyContract } from './token-types';
 /**
  * Why a pushed disposer is running: the factory never returned, or it did and the
@@ -19,99 +19,48 @@ export interface DisposerContext {
 }
 /**
  * Cooperative cancellation and acquisition-local ownership supplied to a context-aware factory.
- * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#start-selected-services-and-cancel-cooperatively
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#make-selected-services-ready
  */
-export interface AcquisitionContext {
-    /** Aborted when the acquisition's owning scope begins closing. */
-    readonly signal: AbortSignal;
+export interface FactoryContext {
+    /** Aborted when the acquisition's owning container begins closing. */
+    readonly abortSignal: AbortSignal;
     /**
-     * Own a resource this factory has already acquired. Pushed disposers run exactly once, last
-     * pushed first: at once if the factory fails, otherwise at `close()` after every disposer of the
-     * service, with `disposerCtx.reason` saying which. `withDisposal` owns the returned value; push
-     * what is acquired on the way, and test `reason` before releasing the returned value itself.
-     * @param disposer - Releases the resource acquired immediately before this call.
+     * Own 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.
      */
-    pushDisposer(this: void, disposer: (this: void, disposerCtx: DisposerContext) => void | Promise<void>): void;
+    pushDisposer(this: void, disposer: (this: void, disposerContext: DisposerContext) => void | Promise<void>): void;
 }
-type ContextFactory = (this: void, deps: never, factoryCtx: AcquisitionContext) => unknown;
 /**
  * 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
+ * @typeParam F - The contextual callback whose named dependencies and return type are retained.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#make-selected-services-ready
  */
-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;
-    readonly acquisitionMode?: M;
-}] : [options: {
-    readonly context?: never;
-    readonly acquisitionMode: M;
-}];
-/**
- * Describe a named-dependency factory receiving its acquisition owner's cancellation signal.
- * Context allocation is opt-in through `context: 'acquisition'`, independent of callback arity.
- * @param callback - A receiver-free factory taking dependencies and acquisition context.
- * @param options - Context selection and result policy; acquisitionMode defaults to auto.
- * @returns A lazy provider preserving exact output and named dependencies; adds no ownership.
- * @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, factoryCtx: 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>>;
-/**
- * Describe a named-dependency factory with explicit or automatic result acquisition.
- * Raw mode preserves the exact acquired value; nativePromise observes Promise fulfillment.
- * @param callback - A receiver-free factory taking its named dependency object.
- * @param options - Optional result acquisitionMode, defaulting to auto.
- * @returns A lazy provider retaining exact output and dependency types without adding ownership.
- * @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>> & AutoOutput<ReturnType<NoInfer<F>>, NoInfer<M>>, ...options: FactoryOptions<M>): Provider<F, Readonly<{}>, readonly [], TokenDependencyContract, Acquired<ReturnType<F>, M>>;
-type PortableFactoryOptions = {
-    readonly context?: never;
-    readonly acquisitionMode?: never;
-};
-type ContextualPortableFactoryOptions = {
-    readonly context: 'acquisition';
-    readonly acquisitionMode?: never;
+export type ContextualFactory<F extends (this: void, dependencies: never, factoryContext: never) => unknown> = (this: void, dependencies: Parameters<F> extends [] ? {} : Parameters<F>[0]) => ReturnType<F>;
+type ReturnKindAdmission<Output, ReturnKind extends FactoryReturnKind> = NativeOutput<Output, NoInfer<ReturnKind>> & AutoOutput<Output, NoInfer<ReturnKind>> & SyncOutput<Output, NoInfer<ReturnKind>>;
+type CheckedReturnKindOptions<Output, ReturnKind extends FactoryReturnKind> = 'auto-detect' extends ReturnKind ? unknown extends NativeOutput<Output, NoInfer<ReturnKind>> & SyncOutput<Output, NoInfer<ReturnKind>> ? {
+    readonly factoryReturnKind?: ReturnKind & ReturnKindAdmission<Output, ReturnKind>;
+} : {
+    readonly factoryReturnKind: ReturnKind & ReturnKindAdmission<Output, ReturnKind>;
+} : {
+    readonly factoryReturnKind: ReturnKind & ReturnKindAdmission<Output, ReturnKind>;
 };
 /**
- * Describe a synchronous named-dependency factory that runs on every host: a `raw` stage whose
- * exact return value is the service, so `then` is never read and no Promise classifier is needed.
- * @param callback - A receiver-free factory taking its named dependency object and the acquisition context.
- * @param options - `context: 'acquisition'`; the acquisition mode is fixed and `acquisitionMode` is rejected.
- * @returns A lazy provider preserving exact output and named dependencies; adds no ownership.
- * @typeParam F - The complete callback signature, retaining dependency and output inference.
- */
-export declare function fromSyncFactory<F extends ContextFactory>(callback: F & SyncOutput<ReturnType<NoInfer<F>>>, options: ContextualPortableFactoryOptions): Provider<ContextualFactory<F>, Readonly<{}>, readonly [], TokenDependencyContract, ReturnType<F>>;
-/**
- * Describe a synchronous named-dependency factory that runs on every host: a `raw` stage whose
- * exact return value is the service. A Promise or thenable output is rejected at compile time;
- * use `fromAsyncFactory`, or `fromFactory` with `acquisitionMode: 'raw'` when the Promise object is the service.
- * @param callback - A receiver-free factory taking its named dependency object.
- * @param options - Optional; `acquisitionMode` is rejected because the helper fixes it.
- * @returns A lazy provider retaining exact output and dependency types without adding ownership.
- * @typeParam F - The exact factory signature and exposed result.
- */
-export declare function fromSyncFactory<F extends Factory>(callback: F & SyncOutput<ReturnType<NoInfer<F>>>, options?: PortableFactoryOptions): Provider<F, Readonly<{}>, readonly [], TokenDependencyContract, ReturnType<F>>;
-/**
- * Describe an asynchronous named-dependency factory that runs on every host: a `nativePromise`
- * stage whose service is the returned Promise and whose owners receive the fulfilled value.
- * @param callback - A receiver-free async factory taking its named dependency object and the acquisition context.
- * @param options - `context: 'acquisition'`; the acquisition mode is fixed and `acquisitionMode` is rejected.
- * @returns A lazy provider exposing the factory's own Promise; adds no ownership.
- * @typeParam F - The complete callback signature, retaining dependency and output inference.
- */
-export declare function fromAsyncFactory<F extends (this: void, deps: never, factoryCtx: AcquisitionContext) => Promise<unknown>>(callback: F, options: ContextualPortableFactoryOptions): Provider<ContextualFactory<F>, Readonly<{}>, readonly [], TokenDependencyContract, Awaited<ReturnType<F>>>;
-/**
- * Describe an asynchronous named-dependency factory that runs on every host: a `nativePromise`
- * stage whose service is the returned Promise and whose owners receive the fulfilled value.
- * A non-Promise output is rejected at compile time; a thenable that is not a native Promise fails the acquisition with a `TypeError`.
- * @param callback - A receiver-free factory returning a native Promise.
- * @param options - Optional; `acquisitionMode` is rejected because the helper fixes it.
- * @returns A lazy provider exposing the factory's own Promise; `withDisposal` receives its fulfilled value.
- * @typeParam F - The exact factory signature and exposed Promise.
+ * Create a provider from a named-dependency factory that also receives FactoryContext.
+ * @typeParam F - The exact callback signature and output.
+ * @typeParam ReturnKind - How its output is acquired.
  */
-export declare function fromAsyncFactory<F extends Factory>(callback: F & AsyncOutput<ReturnType<NoInfer<F>>>, options?: PortableFactoryOptions): Provider<F, Readonly<{}>, readonly [], TokenDependencyContract, Awaited<ReturnType<F>>>;
+export declare function createProvider<F extends (this: void, dependencies: never, factoryContext: FactoryContext) => any, ReturnKind extends FactoryReturnKind = 'auto-detect'>(factory: F & AutoOutput<ReturnType<NoInfer<F>>, NoInfer<ReturnKind>>, options: {
+    readonly factoryReceivesContext: true;
+} & CheckedReturnKindOptions<ReturnType<NoInfer<F>>, ReturnKind>): Provider<ContextualFactory<F>, Readonly<{}>, readonly [], TokenDependencyContract, Acquired<ReturnType<F>, ReturnKind>>;
+export declare function createProvider<F extends FactoryType, ReturnKind extends FactoryReturnKind = 'auto-detect'>(factory: F & AutoOutput<ReturnType<NoInfer<F>>, NoInfer<ReturnKind>>, ...options: {} extends CheckedReturnKindOptions<ReturnType<NoInfer<F>>, ReturnKind> ? [
+    options?: {
+        readonly factoryReceivesContext?: never;
+    } & CheckedReturnKindOptions<ReturnType<NoInfer<F>>, ReturnKind>
+] : [
+    options: {
+        readonly factoryReceivesContext?: never;
+    } & CheckedReturnKindOptions<ReturnType<NoInfer<F>>, ReturnKind>
+]): Provider<F, Readonly<{}>, readonly [], TokenDependencyContract, Acquired<ReturnType<F>, ReturnKind>>;
+type FactoryType = Factory;
 export {};