di-bag 0.3.0 → 0.4.0

package/dist/provider-execution.js

@@ -1,7 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProviderExecution = exports.CompletedExecution = void 0;
+exports.ProviderExecution = exports.CompletedExecution = exports.DisposerStack = void 0;
 const errors_1 = require("./errors");
+/**
+ * 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.
+ */
+class DisposerStack {
+    disposers = [];
+    settled = false;
+    /** Own a resource the running factory already holds. */
+    push(disposer) {
+        if (typeof disposer !== 'function')
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_CLEANUP', 'pushDisposer requires a function', { operation: 'pushDisposer', provided: typeof disposer });
+        // A retained context is a leak, not a stack: registration closes with the factory.
+        if (this.settled)
+            throw (0, errors_1.libraryError)('DI_BAG_CLEANUP_AFTER_FACTORY', 'pushDisposer is only available while its factory is running', { operation: 'pushDisposer' });
+        this.disposers.push(disposer);
+    }
+    /** The factory settled; nothing more can be pushed. */
+    settle() { this.settled = true; }
+    get pending() { return this.disposers.length > 0; }
+    /** Take every pushed disposer, last pushed first, and close registration for good. */
+    drain() {
+        this.settled = true;
+        return this.disposers.splice(0).reverse();
+    }
+}
+exports.DisposerStack = DisposerStack;
 const observePromise = (Promise.prototype.then);
 const emptyFrames = Object.freeze([]);
 const emptyWork = Object.freeze([]);
@@ -11,6 +39,8 @@ class CompletedExecution {
     state = 'ready';
     sourceInFlight = false;
     hasOwnership = false;
+    rollingBack = false;
+    disposers = undefined;
     error = undefined;
     work = emptyWork;
     constructor(frames) {
@@ -34,6 +64,12 @@ class ProviderExecution {
     context;
     frames;
     stages = [];
+    /** Allocated only for a context-aware factory, which is the only source that can push disposers. */
+    disposers;
+    // The factory returned, so the bag owns what it pushed, below every accepted stage.
+    disposersOwned = false;
+    // The failure-path run of the stack, while it is in flight.
+    rollback;
     pending = new Set();
     result;
     cleaning;
@@ -45,12 +81,68 @@ class ProviderExecution {
         // Reserve every metadata frame before the source can reenter inspection.
         this.frames = description.operations.filter(operation => operation.kind === 'frame-sync' || operation.kind === 'frame-async')
             .map(() => Object.freeze({ present: false }));
+        if (description.contextual)
+            this.disposers = new DisposerStack();
     }
     inspectFrames() { return Object.freeze([...this.frames]); }
     get state() { return this.result?.state ?? 'failed'; }
     get error() { return this.result?.error; }
-    get hasOwnership() { return this.stages.length > 0; }
+    get hasOwnership() { return this.stages.length > 0 || this.disposersOwned; }
+    get rollingBack() { return this.rollback !== undefined; }
     get work() { return [...this.pending]; }
+    /**
+     * 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.
+     */
+    settleDisposers(state) {
+        if (!this.disposers)
+            return;
+        this.disposers.settle();
+        if (!this.disposers.pending)
+            return;
+        if (state === 'ready') {
+            this.disposersOwned = true;
+            this.events.accepted();
+            return;
+        }
+        const work = this.rollbackDisposers().then(() => {
+            this.rollback = undefined;
+            this.pending.delete(work);
+            if (!this.pending.size)
+                this.events.drained();
+        });
+        this.rollback = work;
+        this.pending.add(work);
+    }
+    async rollbackDisposers() {
+        // One microtask after the source settles: a synchronous failure never runs
+        // cleanup inline, and an unprojected attempt has already reported
+        // acquisition-failed. Under a projection the result settles later, so this
+        // run can precede both acquisition-failed and the consumer's rejection.
+        await undefined;
+        this.events.cleanupStarted?.();
+        const failed = await this.runDisposers('factory-failed');
+        this.events.cleanupCompleted?.(failed ? 'failure' : 'success');
+    }
+    /** Run every pushed disposer, last pushed first, all attempted; true when one threw. */
+    async runDisposers(reason) {
+        const disposerCtx = Object.freeze({ reason });
+        let failed = false;
+        for (const disposer of this.disposers?.drain() ?? []) {
+            const sequence = this.events.invoking();
+            try {
+                await disposer(disposerCtx);
+            }
+            catch (error) {
+                failed = true;
+                this.events.cleanupFailed(sequence, error);
+            }
+        }
+        return failed;
+    }
     /** Observe the selected stage, retaining its failure even after retirement. */
     async ready() {
         const result = this.result;
@@ -64,7 +156,13 @@ class ProviderExecution {
     compact() {
         if (this.state !== 'ready' || this.pending.size || this.hasOwnership)
             return this;
-        return this.frames.length ? new CompletedExecution(this.inspectFrames()) : completedWithoutFrames;
+        if (!this.frames.length)
+            return completedWithoutFrames;
+        // The copy owns the frames from here; a retained reference to this record
+        // must not keep the application's frame payloads alive.
+        const completed = new CompletedExecution(this.inspectFrames());
+        this.frames.length = 0;
+        return completed;
     }
     /** Classify/own only after the direct operation-free source call has returned. */
     publishSource(value, description) {
@@ -72,32 +170,39 @@ class ProviderExecution {
             this.sourceInFlight = false;
             this.result = { exposed: undefined, consumed: true, state: 'ready', value: undefined, error: undefined, owners: [] };
             if (description.dispose)
-                this.accept(0, value, description.dispose);
+                this.accept(0, value, description.dispose, true);
             return;
         }
         const stage = this.capture(() => value, true, description.acquisitionMode);
         if (description.dispose)
-            this.own(stage, 0, description.dispose);
+            this.own(stage, 0, description.dispose, true);
         this.result = stage;
         this.consume(stage);
         if (stage.state === 'failed')
             throw stage.error;
     }
-    evaluate(description, deps, acquisitionContext) {
+    evaluate(description, deps, context) {
         const { create, dispose } = description;
         let current = this.capture(() => description.contextual
-            ? Reflect.apply(create, undefined, [deps, acquisitionContext()])
+            ? Reflect.apply(create, undefined, [deps, context])
             : create(deps), true, description.acquisitionMode);
+        // A pending source settles its own rollback list from the promise handler.
+        if (current.state !== 'pending')
+            this.settleDisposers(current.state);
         let nextFrame = 0;
+        // Ownership attached before the first transform owns the value the factory
+        // returned; metadata frames preserve the value, so they do not end it.
+        let returned = true;
         if (dispose)
-            this.own(current, 0, dispose);
+            this.own(current, 0, dispose, true);
         description.operations.forEach((operation, offset) => {
             const inputStage = current;
             const index = offset + 1;
             if (operation.kind === 'owned') {
-                this.own(current, index, operation.dispose);
+                this.own(current, index, operation.dispose, returned);
             }
             else if (operation.kind === 'map-sync') {
+                returned = false;
                 if (current.state !== 'failed') {
                     const input = current.exposed;
                     const { project } = operation;
@@ -105,6 +210,7 @@ class ProviderExecution {
                 }
             }
             else if (operation.kind === 'map-async') {
+                returned = false;
                 const input = current;
                 const { project } = operation;
                 current = this.capture(async () => {
@@ -179,7 +285,7 @@ class ProviderExecution {
                     if (!stage.consumed)
                         stage.value = value;
                     for (const owner of stage.owners)
-                        this.accept(owner.index, value, owner.dispose);
+                        this.accept(owner.index, value, owner.dispose, owner.returned);
                     stage.owners.length = 0;
                     finish();
                 }, error => {
@@ -193,8 +299,10 @@ class ProviderExecution {
                 stage.settled = barrier;
                 this.pending.add(barrier);
                 const finish = () => {
-                    if (source)
+                    if (source) {
                         this.sourceInFlight = false;
+                        this.settleDisposers(stage.state === 'ready' ? 'ready' : 'failed');
+                    }
                     this.pending.delete(barrier);
                     settled();
                     if (this.result === stage)
@@ -214,14 +322,14 @@ class ProviderExecution {
             return { exposed: undefined, consumed: true, state: 'failed', value: undefined, error, owners: [] };
         }
     }
-    own(stage, index, dispose) {
+    own(stage, index, dispose, returned) {
         if (stage.state === 'ready')
-            this.accept(index, stage.value, dispose);
+            this.accept(index, stage.value, dispose, returned);
         else if (stage.state === 'pending')
-            stage.owners.push({ index, dispose });
+            stage.owners.push({ index, dispose, returned });
     }
-    accept(index, value, dispose) {
-        this.stages.push({ index, value, dispose, state: 'accepted' });
+    accept(index, value, dispose, returned) {
+        this.stages.push({ index, value, dispose, returned, state: 'accepted' });
         this.events.accepted();
     }
     dispose() {
@@ -237,12 +345,16 @@ class ProviderExecution {
         // All later acceptances must be known before reversing stable stage indices.
         while (this.pending.size)
             await Promise.all(this.pending);
-        const owned = this.stages.length > 0;
+        const owned = this.hasOwnership;
         let failed = false;
+        let returnedOwned = false;
+        let returnedFailed = false;
         if (owned)
             this.events.cleanupStarted?.();
         for (const stage of this.stages.sort((a, b) => b.index - a.index)) {
             stage.state = 'disposing';
+            if (stage.returned)
+                returnedOwned = true;
             const sequence = this.events.invoking();
             const { dispose, value } = stage;
             try {
@@ -250,20 +362,36 @@ class ProviderExecution {
             }
             catch (error) {
                 failed = true;
+                if (stage.returned)
+                    returnedFailed = true;
                 this.events.cleanupFailed(sequence, error);
             }
             finally {
                 stage.state = 'disposed';
             }
         }
+        // Pushed disposers are the bottom of the ownership stack: they run after every
+        // accepted stage and are told how the returned value's own disposer went. A
+        // projection owner belongs to whoever transformed the value; its outcome is
+        // reported through cleanup-failed, not through the reason.
+        if (this.disposersOwned) {
+            const reason = !returnedOwned ? 'no-service-disposer' : returnedFailed ? 'service-disposal-failed' : 'service-disposed';
+            if (await this.runDisposers(reason))
+                failed = true;
+            this.disposersOwned = false;
+        }
         if (owned)
             this.events.cleanupCompleted?.(failed ? 'failure' : 'success');
         this.stages.length = 0;
         this.result = undefined;
     }
+    // Reached only after every barrier and rollback has drained; draining the stack
+    // here is for a context the application retained, never for a running one.
     release() {
         this.frames.length = 0;
         this.stages.length = 0;
+        this.disposers?.drain();
+        this.disposersOwned = false;
         this.pending.clear();
         this.result = undefined;
     }

package/dist/runtime.d.ts

@@ -40,6 +40,7 @@ export declare class BindingGraph {
     /**
      * Return the context acquisitions use, resolving the host classifier before any factory runs.
      * Immutable graphs need explicit-mode validation only once; configured forks are O(1).
+     * A host without a classifier gets every automatic registration named, so the fix is one pass.
      */
     preflight(context: RuntimeContext): RuntimeContext;
     publicBinding(key: BindingKey): BindingId;

package/dist/runtime.js

@@ -126,14 +126,25 @@ class BindingGraph {
     /**
      * Return the context acquisitions use, resolving the host classifier before any factory runs.
      * Immutable graphs need explicit-mode validation only once; configured forks are O(1).
+     * A host without a classifier gets every automatic registration named, so the fix is one pass.
      */
     preflight(context) {
         if (context.isNativePromise || this.#explicitlyClassified)
             return context;
-        for (const [, { normalized: description }] of this.#bindings) {
-            if (description.acquisitionMode === 'auto' || description.operations.some(operation => 'acquisitionMode' in operation && operation.acquisitionMode === 'auto'))
-                return (0, acquisition_mode_1.requireClassifier)(context);
+        const automatic = [];
+        for (const [, { description, normalized }] of this.#bindings) {
+            if (normalized.acquisitionMode === 'auto' || normalized.operations.some(operation => 'acquisitionMode' in operation && operation.acquisitionMode === 'auto')) {
+                // The host answers once for the whole graph; only a host without a classifier needs the full list.
+                if (!automatic.length) {
+                    const resolved = (0, acquisition_mode_1.resolveClassifier)(context);
+                    if (resolved)
+                        return resolved;
+                }
+                automatic.push(description.label);
+            }
         }
+        if (automatic.length)
+            throw (0, acquisition_mode_1.classifierRequired)(automatic);
         this.#explicitlyClassified = true;
         return context;
     }

package/dist/startup.js

@@ -7,6 +7,15 @@ const runtime_1 = require("./runtime");
 const tokens_1 = require("./tokens");
 const errors_2 = require("./errors");
 /** Snapshot own cancellation options once, so getters and prototypes cannot change them later. */
+/**
+ * Format a timeout error's stack before handing it on. An unformatted stack keeps
+ * the frames that created it alive, and these are closures over the runtime; a
+ * startup timeout also becomes the reason on every signal the bag handed out.
+ */
+function formatted(error) {
+    void error.stack;
+    return error;
+}
 function snapshotOptions(options, operation, code, supported) {
     if (options === undefined)
         return {};
@@ -79,7 +88,7 @@ function closeRuntime(runtime, options) {
             if (settled || timeoutMs === undefined)
                 return;
             if (performance.now() - began >= timeoutMs) {
-                cancel('timeout', (0, errors_1.diagnostic)(new DOMException((0, errors_1.diagnosticMessage)('DI_BAG_CLOSE_TIMEOUT', 'Bag close timed out'), 'TimeoutError'), 'DI_BAG_CLOSE_TIMEOUT', { operation: 'close', timeoutMs }));
+                cancel('timeout', formatted((0, errors_1.diagnostic)(new DOMException((0, errors_1.diagnosticMessage)('DI_BAG_CLOSE_TIMEOUT', 'Bag close timed out'), 'TimeoutError'), 'DI_BAG_CLOSE_TIMEOUT', { operation: 'close', timeoutMs })));
                 return;
             }
             // Long deadlines must not wrap into an immediate timer on Node/Bun.
@@ -131,7 +140,7 @@ function startRuntime(graph, context, keys, options) {
         const checkCancellation = () => {
             aborted();
             if (!settled && timeoutMs !== undefined && performance.now() - began >= timeoutMs) {
-                cancel('timeout', (0, errors_1.diagnostic)(new DOMException((0, errors_1.diagnosticMessage)('DI_BAG_STARTUP_TIMEOUT', 'Bag startup timed out'), 'TimeoutError'), 'DI_BAG_STARTUP_TIMEOUT', { operation: 'buildAndStart', timeoutMs }));
+                cancel('timeout', formatted((0, errors_1.diagnostic)(new DOMException((0, errors_1.diagnosticMessage)('DI_BAG_STARTUP_TIMEOUT', 'Bag startup timed out'), 'TimeoutError'), 'DI_BAG_STARTUP_TIMEOUT', { operation: 'buildAndStart', timeoutMs })));
             }
             return settled;
         };

package/dist/types.d.ts

@@ -46,7 +46,7 @@ export interface DiBagPolicy {
 type StructuralThenablesAllowed = DiBagPolicy extends {
     readonly structuralThenables: 'allow';
 } ? true : false;
-type IsAny<T> = 0 extends 1 & T ? true : false;
+export type IsAny<T> = 0 extends 1 & T ? true : false;
 /** True for a declared output with a callable `then` that is not a native Promise; `any` is exempt. */
 export type StructuralThenable<O> = StructuralThenablesAllowed extends true ? false : IsAny<O> extends true ? false : O extends infer T & {} ? T extends Promise<unknown> ? false : T extends {
     then(...args: never[]): unknown;

package/docs/agent/api-card.md

@@ -12,6 +12,8 @@ An example without an import line uses `import { DiBag } from 'di-bag';`. The ru
 | --- | --- |
 | Start a graph | [`DiBag.createBuilder()`](#dibag-createbuilder) |
 | Register a service | [`builder.register(more)`](#builder-register) |
+| Register a synchronous factory for a browser or worker | [`DiBag.fromSyncFactory(callback, options)`](#dibag-fromsyncfactory) |
+| Register an async factory for a browser or worker | [`DiBag.fromAsyncFactory(callback, options)`](#dibag-fromasyncfactory) |
 | Attach cleanup | [`DiBag.withDisposal(create, dispose)`](#dibag-withdisposal) |
 | Choose a lifetime | [`DiBag.withLifetime(registration, lifetime)`](#dibag-withlifetime) |
 | Seal a module | [`builder.buildModule(keys, options?)`](#builder-buildmodule) |
@@ -40,6 +42,21 @@ type Query = { then(done: (rows: string[]) => void): void };
 const query = DiBag.fromFactory((): Query => ({ then: done => done([]) }), { acquisitionMode: 'raw' });
 ```
 
+### `DiBag.fromSyncFactory(callback, options)` {#dibag-fromsyncfactory}
+Describe a synchronous factory that runs on every host: the exact return value is the service and `then` is never read. Throws: [`DI_BAG_INVALID_FACTORY`](errors.md#di-bag-invalid-factory).
+```ts
+const config = DiBag.fromSyncFactory(() => ({ url: 'memory:' }));
+```
+
+### `DiBag.fromAsyncFactory(callback, options)` {#dibag-fromasyncfactory}
+Describe an asynchronous factory that runs on every host: the service is the returned native Promise and `withDisposal` receives its fulfilled value. Throws: [`DI_BAG_INVALID_FACTORY`](errors.md#di-bag-invalid-factory).
+```ts
+const db = DiBag.withDisposal(
+  DiBag.fromAsyncFactory(async ({ config }: { config: { url: string } }) => ({ url: config.url, end: async () => {} })),
+  db => db.end(),
+);
+```
+
 ### `DiBag.token(key)` {#dibag-token}
 Create a typed token from a unique symbol; `.of<Service>()` fixes its service type. Throws: [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token).
 ```ts

package/docs/agent/errors.md

@@ -190,6 +190,37 @@ DiBag.createBuilder()
 
 **Recipe:** [add and consume an async client](recipes.md#async-client).
 
+### Portable factory output {#portable-factory-output}
+
+**When:** `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; see https://dany-fedorov.github.io/di-bag/agent/errors.html#portable-factory-output`,
+or `fromAsyncFactory requires a Promise output; use fromSyncFactory for a synchronous value; see https://dany-fedorov.github.io/di-bag/agent/errors.html#portable-factory-output`.
+
+**Cause:** the helper fixes the acquisition mode from its name, so the factory's
+declared output must agree with it. `fromSyncFactory` is a `raw` stage that never
+reads `then`: an `async` function, a `Promise`-returning function, a union with a
+Promise member, or a thenable such as a query builder cannot be its service.
+`fromAsyncFactory` is a `nativePromise` stage: a plain value, a union, or a
+`PromiseLike` cannot be its service.
+
+**Fix:** pick the helper that matches the output. When the Promise object itself
+is the service, use `DiBag.fromFactory(create, { acquisitionMode: 'raw' })`.
+
+```ts
+// expect-error: fromSyncFactory output must not be a Promise or thenable
+import { DiBag } from 'di-bag';
+
+const config = DiBag.fromSyncFactory(async () => ({ url: 'memory:' }));
+```
+
+```ts
+import { DiBag } from 'di-bag';
+
+const config = DiBag.fromAsyncFactory(async () => ({ url: 'memory:' }));
+const ownedPromise = DiBag.fromFactory(() => Promise.resolve({ url: 'memory:' }), { acquisitionMode: 'raw' });
+```
+
+**Recipe:** [make a graph portable to browsers and workers](recipes.md#portable-graph).
+
 ### Wrong shape at a call {#wrong-shape}
 
 **When:** `register`, `installModule`, or `replace` reports
@@ -244,22 +275,59 @@ app.fork(['port'], { port: () => 'eighty' });
 `process.getBuiltinModule`: browsers, Web Workers, and other non-Node runtimes.
 Node, Bun, and Deno never raise it.
 
-**Cause:** a factory uses automatic acquisition, no native-Promise classifier
-is configured, and the host offers none.
+**Cause:** a registration uses automatic acquisition, no native-Promise classifier
+is configured, and the host offers none. The message and `details.bindings` name
+every such registration, sorted, with private module services as `<label>/<key>`;
+a direct `transformService` without an `acquisitionMode` counts under its
+registration's name.
 
-**Fix:** configure a trusted classifier with
-`withConfiguration({ runtime: { isNativePromise } })`, or give each automatic
-registration an explicit `acquisitionMode`.
+**Fix:** register each named service with `DiBag.fromSyncFactory` or
+`DiBag.fromAsyncFactory`; give `fromFunction`, `fromClass`, and direct
+`transformService` an explicit `acquisitionMode`; or configure a trusted
+classifier with `withConfiguration({ runtime: { isNativePromise } })`.
 
 ```ts
 import { DiBag } from 'di-bag';
 
 const app = DiBag.createBuilder()
-  .register({ answer: DiBag.fromFactory(() => 42, { acquisitionMode: 'raw' }) })
+  .register({
+    answer: DiBag.fromSyncFactory(() => 42),
+    later: DiBag.fromAsyncFactory(async ({ answer }: { answer: number }) => answer * 2),
+  })
   .build();
 ```
 
-**Recipe:** none; see [rule 1](../../AGENTS.md#rules).
+**Recipe:** [make a graph portable to browsers and workers](recipes.md#portable-graph).
+
+### DI_BAG_CLEANUP_AFTER_FACTORY {#di-bag-cleanup-after-factory}
+
+**When:** `factoryCtx.pushDisposer(disposer)` throws because the factory that
+owns the context has already returned or failed. Its projections may still be
+running; the factory is the boundary, not the whole acquisition.
+
+**Cause:** the acquisition context escaped its factory and was called later —
+from the service it produced, from a projection of the registration, or from
+inside a pushed disposer already running. A context belongs to one running
+factory, not to the service it produced.
+
+**Fix:** push inside the factory, immediately after acquiring the resource; own
+the returned value with `DiBag.withDisposal`, and give a pushed disposer for that
+same value a `reason` check.
+
+```ts
+import { DiBag } from 'di-bag';
+
+const handle = DiBag.withDisposal(
+  DiBag.fromFactory(async (_deps: {}, factoryCtx) => {
+    const socket = { close: async () => {} };
+    factoryCtx.pushDisposer(disposerCtx => { if (disposerCtx.reason !== 'service-disposed') return socket.close(); });
+    return socket;
+  }, { context: 'acquisition' }),
+  socket => socket.close(),
+);
+```
+
+**Recipe:** [own a resource a factory acquires on the way](recipes.md#partial-acquisition).
 
 ### DI_BAG_CLEANUP_FAILED {#di-bag-cleanup-failed}
 
@@ -390,7 +458,9 @@ await app.close();
 ### DI_BAG_CLOSING {#di-bag-closing}
 
 **When:** the same operations as [`DI_BAG_CLOSED`](#di-bag-closed), while
-`close()` is still in progress.
+`close()` is still in progress. Also the message of `factoryCtx.signal.reason`
+after `close()`: an `AbortError` that is the same object for every bag. A
+cancelled or failed startup aborts with its own cause instead.
 
 **Cause:** a request, timer, or factory started new resolution after shutdown
 began. Only a factory already running when `close()` started may still read its
@@ -543,6 +613,29 @@ const DiBag = CoreDiBag.withConfiguration({
 
 **Recipe:** none.
 
+### DI_BAG_INVALID_CLEANUP {#di-bag-invalid-cleanup}
+
+**When:** `factoryCtx.pushDisposer(disposer)` throws because `disposer` is not a
+function.
+
+**Cause:** a value was passed where a disposer callback belongs, usually the
+result of calling the release instead of passing it.
+
+**Fix:** pass a function: `factoryCtx.pushDisposer(() => socket.close())`, not
+`factoryCtx.pushDisposer(socket.close())`.
+
+```ts
+import { DiBag } from 'di-bag';
+
+const socket = DiBag.fromFactory(async (_deps: {}, factoryCtx) => {
+  const handle = { close: async () => {} };
+  factoryCtx.pushDisposer(() => handle.close());
+  return handle;
+}, { context: 'acquisition' });
+```
+
+**Recipe:** [own a resource a factory acquires on the way](recipes.md#partial-acquisition).
+
 ### DI_BAG_INVALID_CLOSE {#di-bag-invalid-close}
 
 **When:** `close(options)` rejects because options are not
@@ -650,13 +743,16 @@ const east = reports.renameExport('service', 'eastReports');
 
 ### DI_BAG_INVALID_FACTORY {#di-bag-invalid-factory}
 
-**When:** `DiBag.fromFactory(callback, options)` receives a non-function, or a
-`context` option other than `'acquisition'`.
+**When:** `DiBag.fromFactory`, `fromSyncFactory`, or `fromAsyncFactory` receives a
+non-function, or a `context` option other than `'acquisition'`; the two portable
+helpers also refuse an `acquisitionMode` option, because they fix it themselves.
 
-**Cause:** a value passed where a factory is expected.
+**Cause:** a value passed where a factory is expected, or a mode passed to a
+helper whose name already selects it.
 
 **Fix:** pass a function; use `{ context: 'acquisition' }` to receive the
-acquisition signal as the second argument.
+acquisition context as the second argument; choose `fromSyncFactory` or
+`fromAsyncFactory` instead of passing a mode to them.
 
 ```ts
 import { DiBag } from 'di-bag';