di-bag 0.3.0 → 0.4.0

package/AGENTS.md

@@ -12,9 +12,9 @@ Every compiler and runtime message: [docs/agent/errors.md](docs/agent/errors.md)
 
 1. **Import from `di-bag`:** `import { DiBag } from 'di-bag';`. It configures
    itself on Node, Bun, and Deno; `di-bag/node` is the same API in explicit form.
-   In browsers and workers `build()` throws
-   [`DI_BAG_CLASSIFIER_REQUIRED`](docs/agent/errors.md#di-bag-classifier-required)
-   for factories without an explicit `acquisitionMode`.
+   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
@@ -31,8 +31,9 @@ Every compiler and runtime message: [docs/agent/errors.md](docs/agent/errors.md)
    method (query builders) is [rejected](docs/agent/errors.md#structural-thenable).
    Return `Promise.resolve(builder)` or use `DiBag.fromFactory(create, { acquisitionMode: 'raw' })`.
 6. **Ownership.** `DiBag.withDisposal(factory, dispose)` makes the bag own the
-   value; `close()` runs disposers, dependents first. Close every scope and fork
-   you create. A parent closes its live scopes, never forks.
+   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'])`.

package/README.md

@@ -1,7 +1,7 @@
 # DI Bag
 
-TypeScript dependency composition and resource ownership for modular codebases,
-including the ones coding agents build one feature at a time.
+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) · [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)
 
@@ -225,9 +225,9 @@ The package has **zero runtime dependencies** and two entry points:
 | `di-bag/node` | The same API with detection configured explicitly at import, for Node and Bun. |
 
 On hosts without `process.getBuiltinModule` (browsers, workers), `build()`
-rejects automatic acquisition stages unless you configure a trusted classifier
-or give each stage an explicit acquisition mode. See
-[portable mode](docs/guides/tutorial.md#portable-mode) for both options.
+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
 
@@ -242,13 +242,16 @@ or give each stage an explicit acquisition mode. See
 - **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).
-- **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.
+- **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
 
@@ -257,6 +260,7 @@ or give each stage an explicit acquisition mode. See
 | [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. |
+| [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. |

package/dist/acquisition-context.d.ts

@@ -1,16 +1,39 @@
 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;
+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
@@ -32,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>>;
 /**
@@ -45,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,5 +1,5 @@
 import type { LifecycleObservers } from './observers';
-import type { SeeErrors, 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.
@@ -34,8 +34,16 @@ 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${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;
 /** Resolve the classifier when a graph first needs one; a configured classifier always wins. */
-export declare function requireClassifier(context: RuntimeContext): RuntimeContext;
+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.requireClassifier = requireClassifier;
+exports.resolveClassifier = resolveClassifier;
+exports.classifierRequired = classifierRequired;
 const errors_1 = require("./errors");
 exports.unconfigured = Object.freeze({});
 function runtimeContext(options, previous = exports.unconfigured) {
@@ -43,11 +44,18 @@ function hostClassifier() {
     return typeof isPromise === 'function' ? isPromise : undefined;
 }
 /** Resolve the classifier when a graph first needs one; a configured classifier always wins. */
-function requireClassifier(context) {
+function resolveClassifier(context) {
     if (context.isNativePromise)
         return context;
     const isNativePromise = hostClassifier();
-    if (isNativePromise)
-        return Object.freeze({ ...context, isNativePromise });
-    throw (0, errors_1.libraryError)('DI_BAG_CLASSIFIER_REQUIRED', 'this host has no process.getBuiltinModule; configure DiBag.withConfiguration({ runtime: { isNativePromise } }) or give each automatic registration an explicit acquisitionMode', { option: 'runtime.isNativePromise' });
+    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;
@@ -41,7 +40,17 @@ export declare class ScopeAcquisitions {
     close(beforeDispose?: Promise<void>, cause?: unknown): Promise<void>;
     /** Labels of this scope's running disposers and of acquisitions close is still draining. */
     collectProgress(pending: string[], acquiring: string[]): void;
-    private getContext;
+    /** 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;

package/dist/acquisition.js

@@ -5,6 +5,19 @@ const errors_1 = require("./errors");
 const errors_2 = require("./errors");
 const provider_execution_1 = require("./provider-execution");
 const acquisition_family_1 = require("./acquisition-family");
+/**
+ * The reason a close() without a cause aborts with. Built once at load: an error
+ * created inside close() keeps an unformatted stack whose frames retain the
+ * closing callbacks, and through them the scope and its graph, on every signal an
+ * application kept after the bag closed. It stays a plain `AbortError`, so its
+ * legacy numeric `code` is what an automatic abort reason had; the message names
+ * the diagnostic.
+ */
+const closingReason = (() => {
+    const reason = new DOMException((0, errors_1.diagnosticMessage)('DI_BAG_CLOSING', 'bag is closing'), 'AbortError');
+    void reason.stack; // format the load-time frames now, so nothing is retained lazily
+    return Object.freeze(reason);
+})();
 /** Mutable, runtime-local attempts. Binding descriptions never carry ownership. */
 class ScopeAcquisitions {
     graph;
@@ -21,7 +34,6 @@ class ScopeAcquisitions {
     state = 'open';
     closing;
     controller;
-    acquisitionContext;
     cancellationStarted = false;
     cancellationCause;
     shared;
@@ -132,8 +144,8 @@ class ScopeAcquisitions {
         this.closing = Promise.resolve().then(() => {
             // Every descendant admission gate is closed before abort listeners run.
             this.cancellationStarted = true;
-            this.cancellationCause = cause;
-            this.controller?.abort(cause);
+            this.cancellationCause = cause === undefined ? closingReason : cause;
+            this.controller?.abort(this.cancellationCause);
             return this.disposeAll(beforeDispose);
         });
         return this.closing;
@@ -141,20 +153,34 @@ class ScopeAcquisitions {
     /** Labels of this scope's running disposers and of acquisitions close is still draining. */
     collectProgress(pending, acquiring) {
         for (const attempt of this.attempts.values()) {
-            if (attempt.state === 'disposing' || this.retired.has(attempt.id))
+            if (attempt.state === 'disposing' || this.retired.has(attempt.id) || attempt.execution.rollingBack)
                 pending.push(attempt.label);
             else if (attempt.state === 'creating' || attempt.state === 'pending')
                 acquiring.push(attempt.label);
         }
     }
-    getContext() {
-        if (!this.acquisitionContext) {
+    /** One controller per scope; every acquisition observes the same cancellation. */
+    cancellationSignal() {
+        if (!this.controller) {
             this.controller = new AbortController();
             if (this.cancellationStarted)
                 this.controller.abort(this.cancellationCause);
-            this.acquisitionContext = Object.freeze({ signal: this.controller.signal });
         }
-        return this.acquisitionContext;
+        return this.controller.signal;
+    }
+    /**
+     * 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.
+     */
+    acquisitionContext(disposers) {
+        return Object.freeze({
+            signal: this.cancellationSignal(),
+            pushDisposer: (disposer) => { disposers.push(disposer); },
+        });
     }
     resolveBinding(bindingId, from, path = []) {
         // Sharing an alias borrows its lexical parent graph before following targets.
@@ -271,6 +297,7 @@ class ScopeAcquisitions {
         this.observeAttempt(attempt, 'acquisition-started');
         this.family.enter(attempt);
         const directSource = !description.contextual && !description.operations.length;
+        const { disposers } = execution;
         try {
             let value;
             if (directSource) {
@@ -279,7 +306,7 @@ class ScopeAcquisitions {
                 execution.publishSource(value, description);
             }
             else {
-                value = execution.evaluate(description, deps, () => this.getContext());
+                value = execution.evaluate(description, deps, disposers && this.acquisitionContext(disposers));
             }
             attempt.exposed = value;
             attempt.state = attempt.execution.state;

package/dist/di-bag.d.ts

@@ -10,7 +10,7 @@ import type { CompositionReport } from './composition-report';
 import type { CheckedConstraints, CompleteConstraints, ExternalRequirements, IncrementalConstraints, ModulePublicProviders, ModuleSealedConstraints, NeedConstraint } from './module-types';
 import type { CheckedLifetimes, SealAdmission, WithoutExportObligations } from './lifetime-types';
 import { withLifetime } from './lifetime';
-import { fromFactory } from './acquisition-context';
+import { fromFactory, fromSyncFactory, fromAsyncFactory } from './acquisition-context';
 import type { ScopeOptions, DisjointScopeSelection, UnsharedAliases, ScopedAliases } from './scope-types';
 import type { CheckedScopeLifetimes } from './lifetime-types';
 import type { CloseOptions, StartupOptions } from './startup';
@@ -399,6 +399,29 @@ export interface DiBagApi {
      * ```
      */
     fromFactory: typeof fromFactory;
+    /**
+     * Describe a synchronous factory that runs on every host: the exact return value is the service and `then` is never read.
+     * A Promise or thenable output is rejected at compile time; use `fromAsyncFactory`, or `fromFactory` with `acquisitionMode: 'raw'` when the Promise object itself is the service.
+     * @throws `DI_BAG_INVALID_FACTORY` for a non-function, an unknown `context`, or an `acquisitionMode` option.
+     * @example
+     * ```ts
+     * const config = DiBag.fromSyncFactory(() => ({ url: 'memory:' }));
+     * ```
+     */
+    fromSyncFactory: typeof fromSyncFactory;
+    /**
+     * Describe an asynchronous factory that runs on every host: the service is the returned native Promise and `withDisposal` receives its 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`.
+     * @throws `DI_BAG_INVALID_FACTORY` for a non-function, an unknown `context`, or an `acquisitionMode` option.
+     * @example
+     * ```ts
+     * const db = DiBag.withDisposal(
+     *   DiBag.fromAsyncFactory(async ({ config }: { config: { url: string } }) => ({ url: config.url, end: async () => {} })),
+     *   db => db.end(),
+     * );
+     * ```
+     */
+    fromAsyncFactory: typeof fromAsyncFactory;
     /**
      * Create a typed token from a unique symbol; `.of<Service>()` fixes its service type.
      * @throws `DI_BAG_INVALID_TOKEN` when the key is not a symbol.
@@ -536,6 +559,6 @@ export interface DiBagApi {
 }
 /**
  * The immutable DI Bag facade. `auto` acquisition uses the host classifier where `process.getBuiltinModule`
- * exists; elsewhere configure one or use explicit modes.
+ * exists; elsewhere register with `fromSyncFactory` and `fromAsyncFactory`, use explicit modes, or configure a classifier.
  */
 export declare const DiBag: DiBagApi;

package/dist/di-bag.js

@@ -279,13 +279,13 @@ function facade(context) {
             }
             return facade(configured);
         },
-        fromFactory: acquisition_context_1.fromFactory, token: tokens_1.token, optional: dependency_references_1.optional, lazy: dependency_references_1.lazy, all: dependency_references_1.all, fromPlugin: plugins_1.fromPlugin, fromFunction: composition_1.fromFunction, fromClass: composition_1.fromClass,
+        fromFactory: acquisition_context_1.fromFactory, fromSyncFactory: acquisition_context_1.fromSyncFactory, fromAsyncFactory: acquisition_context_1.fromAsyncFactory, token: tokens_1.token, optional: dependency_references_1.optional, lazy: dependency_references_1.lazy, all: dependency_references_1.all, fromPlugin: plugins_1.fromPlugin, fromFunction: composition_1.fromFunction, fromClass: composition_1.fromClass,
         createBuilder: () => new Builder(new runtime_1.BindingGraph(), context),
         withDisposal: registration_1.withDisposal, withLifetime: lifetime_1.withLifetime, withMetadata: provider_1.withMetadata, transformService: provider_1.transformService,
     });
 }
 /**
  * The immutable DI Bag facade. `auto` acquisition uses the host classifier where `process.getBuiltinModule`
- * exists; elsewhere configure one or use explicit modes.
+ * exists; elsewhere register with `fromSyncFactory` and `fromAsyncFactory`, use explicit modes, or configure a classifier.
  */
 exports.DiBag = facade(acquisition_mode_1.unconfigured);

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export type { FactoryWithDisposal, Registration } from './registration';
 export type { Provider, ProviderFactory, ProviderGraphContract, ProviderOutput, ProviderAcquiredValue, ProviderNamedDependencies, ProviderRegistrationMetadata, ProviderAcquisitionMetadata, ProviderRequiredTokens, ProviderOptionalTokens, ProviderCollectionTokens } from './provider';
 export type { AcquisitionMode, RuntimeOptions } from './acquisition-mode';
 export type { Lifetime } from './lifetime';
-export type { AcquisitionContext, ContextualFactory } from './acquisition-context';
+export type { AcquisitionContext, ContextualFactory, DisposerContext } from './acquisition-context';
 export type { CloseOptions, StartupOptions } from './startup';
 export type { ScopeOptions, DisjointScopeSelection, UnsharedAliases, ScopedAliases, SharedAliasProviders } from './scope-types';
 export type { Token, TokenBase, TokenKey, TokenService } from './tokens';

package/dist/provider-execution.d.ts

@@ -1,8 +1,26 @@
 import type { normalize } from './provider-operations';
 import type { AcquisitionMetadataPresence } from './inspection';
 import type { RuntimeContext } from './acquisition-mode';
-import type { AcquisitionContext } from './acquisition-context';
+import type { AcquisitionContext, DisposerContext } from './acquisition-context';
 type RegistrationDescription = ReturnType<typeof normalize>;
+type PushedDisposer = (this: void, disposerCtx: DisposerContext) => void | Promise<void>;
+/**
+ * One factory's pushed disposers. It is held by the frozen acquisition context
+ * handed to that factory, so it deliberately references neither the execution
+ * nor its scope: a context the application retains must keep nothing but its
+ * own registrations alive.
+ */
+export declare class DisposerStack {
+    private readonly disposers;
+    private settled;
+    /** Own a resource the running factory already holds. */
+    push(disposer: PushedDisposer): void;
+    /** The factory settled; nothing more can be pushed. */
+    settle(): void;
+    get pending(): boolean;
+    /** Take every pushed disposer, last pushed first, and close registration for good. */
+    drain(): readonly PushedDisposer[];
+}
 interface ExecutionEvents {
     accepted(): void;
     settled(): void;
@@ -18,6 +36,8 @@ export declare class CompletedExecution {
     readonly state = "ready";
     readonly sourceInFlight = false;
     readonly hasOwnership = false;
+    readonly rollingBack = false;
+    readonly disposers: undefined;
     readonly error: undefined;
     readonly work: readonly Promise<void>[];
     constructor(frames: AcquisitionMetadataPresence<readonly unknown[]>);
@@ -32,6 +52,10 @@ export declare class ProviderExecution {
     private readonly context;
     private readonly frames;
     private readonly stages;
+    /** Allocated only for a context-aware factory, which is the only source that can push disposers. */
+    readonly disposers: DisposerStack | undefined;
+    private disposersOwned;
+    private rollback;
     private readonly pending;
     private result;
     private cleaning;
@@ -41,13 +65,25 @@ export declare class ProviderExecution {
     get state(): 'pending' | 'ready' | 'failed';
     get error(): unknown;
     get hasOwnership(): boolean;
+    get rollingBack(): boolean;
     get work(): readonly Promise<void>[];
+    /**
+     * The source stage settles the stack. A factory that returned hands what it
+     * pushed to the bag; a failed one releases it at once, as pending work of this
+     * execution. Anchoring on the source rather than on the attempt's result covers
+     * a direct projection that is already ready while its source is still running,
+     * which no retirement reaches.
+     */
+    private settleDisposers;
+    private rollbackDisposers;
+    /** Run every pushed disposer, last pushed first, all attempted; true when one threw. */
+    private runDisposers;
     /** Observe the selected stage, retaining its failure even after retirement. */
     ready(): Promise<void>;
     compact(): ProviderExecution | CompletedExecution;
     /** Classify/own only after the direct operation-free source call has returned. */
     publishSource(value: unknown, description: RegistrationDescription): void;
-    evaluate(description: RegistrationDescription, deps: unknown, acquisitionContext: () => AcquisitionContext): unknown;
+    evaluate(description: RegistrationDescription, deps: unknown, context: AcquisitionContext | undefined): unknown;
     private consume;
     private capture;
     private own;