di-bag 0.2.0 → 0.4.0

package/AGENTS.md

@@ -0,0 +1,150 @@
+# 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.
+   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.
+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
+   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`.
+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.
+Built for coding agents that ship 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).**
@@ -42,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({
@@ -100,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({
@@ -122,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({
@@ -161,32 +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. `inspectGraph()` lists every
-binding and the edges observed at runtime; declared edges come from the static
-graph tool. Observers track acquisition, not ordinary node calls. Use your graph
-framework for workflow checkpoints.
+## 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
 
@@ -213,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 and names them. Register with
+`DiBag.fromSyncFactory` / `DiBag.fromAsyncFactory` there, or configure a trusted
+classifier. See [portable mode](docs/guides/tutorial.md#portable-mode).
 
 ## Tradeoffs and limits
 
@@ -226,18 +235,23 @@ 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.
-- **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.
-  See the [compiler evidence](docs/benchmarks/typescript.md) for tested forms and limits.
+  at runtime, or before running by [`di-bag-graph`](tools/graph/README.md).
+- **Graph types have a compiler cost.** One fluent expression is bounded by the
+  compiler's recursion budget: classic TypeScript 6.0.3 accepts about 1,000
+  chained calls and overflows beyond that (about 950 for a bulk map followed by
+  individual replacements); native 7.0.2 has no such ceiling. Keep an
+  expression to 500 calls or fewer and use bulk registration, groups, or named
+  modules beyond that. See the [compiler evidence](docs/benchmarks/typescript.md).
 - **Framework integration belongs to the application.** DI Bag provides the
   composition and ownership primitives; the host connects request, job, or UI
-  lifecycles.
+  lifecycles. The [server guide](docs/guides/server-integration.md) and the
+  [React guide](docs/guides/react-integration.md) are tested recipes for both.
 
 ## Explore further
 
@@ -246,8 +260,11 @@ 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. |
-| [Static dependency graph](docs/guides/agent-harnesses-and-graphs.md#export-the-declared-dependency-graph) | Export every builder chain, declared edge, and cycle to JSON with `di-bag-graph`. |
+| [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. |
 | [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. |

package/dist/acquisition-context.d.ts

@@ -1,14 +1,43 @@
 import type { Provider } from './provider';
 import type { Factory } from './registration';
-import type { Acquired, AcquisitionMode, AutoOutput, NativeOutput, ModeOptions } from './acquisition-mode';
+import type { Acquired, AcquisitionMode, AsyncOutput, AutoOutput, NativeOutput, ModeOptions, SyncOutput } from './acquisition-mode';
 import type { TokenDependencyContract } from './token-types';
-/** Cooperative cancellation information supplied to a context-aware acquisition. */
+/**
+ * Why a pushed disposer is running: the factory never returned, or it did and the
+ * 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
+ */
+export interface DisposerContext {
+    /**
+     * `'factory-failed'`: the factory threw, rejected, or was cancelled; no service exists.
+     * `'no-service-disposer'`: the factory returned and no `withDisposal` owns that value.
+     * `'service-disposed'`: the service disposer ran without throwing.
+     * `'service-disposal-failed'`: the service disposer threw; pushed disposers still run.
+     */
+    readonly reason: 'factory-failed' | 'no-service-disposer' | 'service-disposed' | 'service-disposal-failed';
+}
+/**
+ * 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
+ */
 export interface AcquisitionContext {
     /** Aborted when the acquisition's owning scope begins closing. */
     readonly signal: 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.
+     */
+    pushDisposer(this: void, disposer: (this: void, disposerCtx: DisposerContext) => void | Promise<void>): void;
 }
-type ContextFactory = (this: void, deps: never, context: AcquisitionContext) => unknown;
-/** The named-dependency factory contract retained by an acquisition-context callback. */
+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
+ */
 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 +55,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 & AutoOutput<ReturnType<NoInfer<F>>, NoInfer<M>>, options: {
+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>>;
 /**
@@ -39,4 +68,50 @@ export declare function fromFactory<F extends (this: void, deps: never, context:
  * @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;
+};
+/**
+ * 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.
+ */
+export declare function fromAsyncFactory<F extends Factory>(callback: F & AsyncOutput<ReturnType<NoInfer<F>>>, options?: PortableFactoryOptions): Provider<F, Readonly<{}>, readonly [], TokenDependencyContract, Awaited<ReturnType<F>>>;
 export {};

package/dist/acquisition-context.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fromFactory = fromFactory;
+exports.fromSyncFactory = fromSyncFactory;
+exports.fromAsyncFactory = fromAsyncFactory;
 const errors_1 = require("./errors");
 const provider_1 = require("./provider");
 const provider_operations_1 = require("./provider-operations");
@@ -11,9 +13,35 @@ function fromFactory(callback, options) {
     const mode = (0, acquisition_mode_1.acquisitionMode)(options);
     if (options?.context !== undefined && options.context !== 'acquisition')
         throw (0, errors_1.libraryError)('DI_BAG_INVALID_FACTORY', 'fromFactory context must be acquisition', { operation: 'fromFactory' });
-    const contextual = options?.context === 'acquisition';
+    return factoryProvider(callback, mode, options?.context === 'acquisition');
+}
+/** Build the provider for one validated factory; `fromFactory` and both portable helpers end here. */
+function factoryProvider(callback, mode, contextual) {
     const handle = (0, provider_1.createProvider)();
-    const create = contextual ? ((deps, context) => callback(deps, context)) : callback;
+    const create = contextual ? ((deps, factoryCtx) => callback(deps, factoryCtx)) : callback;
     (0, provider_operations_1.retainDescription)(handle, (0, provider_operations_1.sourceDescription)(create, undefined, [], mode, contextual));
     return handle;
 }
+/** Validate a portable helper's options; the mode is the helper's, so `acquisitionMode` is refused. */
+function portableContext(operation, options) {
+    if (options === undefined)
+        return false;
+    if (typeof options !== 'object' || options === null)
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_FACTORY', `${operation} options must be an object`, { operation });
+    if ('acquisitionMode' in options)
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_FACTORY', `${operation} selects its acquisitionMode itself`, { operation });
+    const context = options.context;
+    if (context !== undefined && context !== 'acquisition')
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_FACTORY', `${operation} context must be acquisition`, { operation });
+    return context === 'acquisition';
+}
+function fromSyncFactory(callback, options) {
+    if (typeof callback !== 'function')
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_FACTORY', 'fromSyncFactory requires a function', { operation: 'fromSyncFactory' });
+    return factoryProvider(callback, 'raw', portableContext('fromSyncFactory', options));
+}
+function fromAsyncFactory(callback, options) {
+    if (typeof callback !== 'function')
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_FACTORY', 'fromAsyncFactory requires a function', { operation: 'fromAsyncFactory' });
+    return factoryProvider(callback, 'nativePromise', portableContext('fromAsyncFactory', options));
+}

package/dist/acquisition-mode.d.ts

@@ -1,11 +1,15 @@
 import type { LifecycleObservers } from './observers';
-import type { StructuralThenable, Unsatisfied } from './types';
+import type { IsAny, 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;
@@ -29,8 +33,17 @@ export type StageOptions<M extends AcquisitionMode> = 'auto' extends M ? [option
 }];
 export type NativeOutput<O, M extends AcquisitionMode> = 'nativePromise' extends M ? [O] extends [Promise<unknown>] ? unknown : Unsatisfied<'nativePromise acquisition requires a Promise output', {}> : unknown;
 /** Reject a structural thenable output when the stage would classify it automatically. */
-export type AutoOutput<O, M extends AcquisitionMode> = 'auto' extends M ? true extends StructuralThenable<O> ? Unsatisfied<'factory output is a structural thenable; return a native Promise or select acquisitionMode raw or nativePromise', {}> : unknown : unknown;
+export 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;
+type PromiseOutput<O> = O extends infer T & {} ? T extends Promise<unknown> ? true : false : false;
+/** Reject a Promise or thenable output where the helper declares the stage synchronous; `any` is exempt. */
+export type SyncOutput<O> = IsAny<O> extends true ? unknown : true extends PromiseOutput<O> | StructuralThenable<O> ? Unsatisfied<`fromSyncFactory output must not be a Promise or thenable; use fromAsyncFactory for a Promise, or fromFactory with acquisitionMode raw to make the Promise object the service${SeeErrors<'portable-factory-output'>}`, {}> : unknown;
+/** Require a Promise output where the helper declares the stage asynchronous. */
+export type AsyncOutput<O> = [O] extends [Promise<unknown>] ? unknown : Unsatisfied<`fromAsyncFactory requires a Promise output; use fromSyncFactory for a synchronous value${SeeErrors<'portable-factory-output'>}`, {}>;
 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 resolveClassifier(context: RuntimeContext): RuntimeContext | undefined;
+/** The graph has automatic stages and no classifier; `bindings` labels every such registration. */
+export declare function classifierRequired(bindings: readonly string[]): Error;
+export {};

package/dist/acquisition-mode.js

@@ -3,7 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.unconfigured = void 0;
 exports.runtimeContext = runtimeContext;
 exports.acquisitionMode = acquisitionMode;
-exports.requireClassificationCapability = requireClassificationCapability;
+exports.resolveClassifier = resolveClassifier;
+exports.classifierRequired = classifierRequired;
 const errors_1 = require("./errors");
 exports.unconfigured = Object.freeze({});
 function runtimeContext(options, previous = exports.unconfigured) {
@@ -25,11 +26,36 @@ 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 resolveClassifier(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();
+    return isNativePromise ? Object.freeze({ ...context, isNativePromise }) : undefined;
+}
+const namedBindings = 8;
+/** The graph has automatic stages and no classifier; `bindings` labels every such registration. */
+function classifierRequired(bindings) {
+    const sorted = [...bindings].sort();
+    const shown = sorted.slice(0, namedBindings).map(label => JSON.stringify(label)).join(', ');
+    const rest = sorted.length - Math.min(sorted.length, namedBindings);
+    const count = sorted.length === 1 ? '1 registration uses' : `${sorted.length} registrations use`;
+    return (0, errors_1.libraryError)('DI_BAG_CLASSIFIER_REQUIRED', `this host has no process.getBuiltinModule; ${count} automatic acquisition: ${shown}${rest ? `, and ${rest} more` : ''}; use DiBag.fromSyncFactory or DiBag.fromAsyncFactory (or an explicit acquisitionMode) for each, or configure DiBag.withConfiguration({ runtime: { isNativePromise } })`, { option: 'runtime.isNativePromise', bindings: Object.freeze(sorted) });
 }

package/dist/acquisition.d.ts

@@ -16,7 +16,6 @@ export declare class ScopeAcquisitions {
     private state;
     private closing;
     private controller;
-    private acquisitionContext;
     private cancellationStarted;
     private cancellationCause;
     private readonly shared;
@@ -39,7 +38,19 @@ export declare class ScopeAcquisitions {
     private assertAliasPath;
     assertOpen(): void;
     close(beforeDispose?: Promise<void>, cause?: unknown): Promise<void>;
-    private getContext;
+    /** Labels of this scope's running disposers and of acquisitions close is still draining. */
+    collectProgress(pending: string[], acquiring: string[]): void;
+    /** One controller per scope; every acquisition observes the same cancellation. */
+    private cancellationSignal;
+    /**
+     * The signal is scope-wide; deferred cleanup is local to this attempt, so each
+     * contextual acquisition receives its own frozen context. The context captures
+     * only its disposer stack, never the execution or this scope, so an
+     * application that retains it past `close()` retains nothing else. Built here
+     * rather than in `resolveBinding` for the same reason: every closure of a
+     * function shares one scope, and a factory can retain the dependency proxy.
+     */
+    private acquisitionContext;
     private resolveBinding;
     private eventFields;
     private observeAttempt;