di-bag 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Danylo Fedorov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,280 @@
+# DI Bag
+
+Dependency injection for agentic development.
+
+[Documentation](https://dany-fedorov.github.io/di-bag/) · [Quickstart](#quickstart) · [Comparison](#how-it-compares) · [Tutorial](docs/guides/tutorial.md) · [API reference](docs/guides/api-reference.md)
+
+## Why DI Bag?
+
+DI Bag is designed to make modular applications easier for coding agents to
+work on. Modularity is a practical context-engineering technique: clear
+feature boundaries can reduce the code and dependencies an agent needs to
+consider for a task. DI Bag is a TypeScript dependency injection library built
+around that idea—helping you define those boundaries, replace dependencies in
+tests, and check how the pieces fit together.
+
+- **[Radical modularity for agentic development](docs/guides/examples-modularity.md).**
+  Compose small features with private internals and explicit contracts. Give
+  humans and coding agents focused units to implement, replace, and test
+  independently, then check their composition together.
+- **[TypeScript-first composition](docs/guides/examples-type-checking.md).**
+  Catch missing dependencies, incompatible service contracts, and invalid
+  replacements at compile time—not just incorrect arguments at the call site.
+  Coding agents can shorten their evaluation loop by checking wiring without
+  starting the app or running integration tests.
+- **[A programmable DI layer for custom tooling](docs/guides/examples-extensibility.md).**
+  Give agents the building blocks to create the tooling your workflow needs:
+  custom inspectors, diagnostics, metadata-driven actions, and lifecycle tools.
+  Combine application-defined metadata, composable provider wrappers, and
+  configurable observers without changing your services.
+- **[Inject anything with a simple factory function](docs/guides/examples-plain-services.md).**
+  DI Bag is TypeScript-first, but injecting services is as simple as writing an
+  ordinary JavaScript function: receive dependencies and return a value.
+  Functions, class instances, configuration, clients, or promises—no decorators,
+  reflection metadata, or special base classes required.
+
+Each guide above contains three complete application examples. Lazy creation,
+configurable lifetimes, scopes, and dependency-ordered cleanup support these
+patterns; the [tutorial](docs/guides/tutorial.md) explains how.
+
+For a small graph, passing dependencies directly is often simpler. Other DI
+libraries also offer typed composition and resource management; the
+[comparison below](#how-it-compares) explains the tradeoffs.
+
+## Install
+
+This checkout is a pre-1.0 release candidate, currently versioned `0.1.0`.
+It includes breaking API changes, so expect to review migrations when updating.
+These instructions install the current checkout without assuming an npm release
+is available. Build a local package with Node 24 and npm:
+
+```sh
+git clone https://github.com/dany-fedorov/di-bag.git
+cd di-bag
+npm ci
+npm pack
+```
+
+Then, from your application, install the generated archive using its local path:
+
+```sh
+npm install /path/to/di-bag/di-bag-0.1.0.tgz
+```
+
+The minimum supported TypeScript version is **6.0.3**; enable `strict` in your
+`tsconfig.json`. The repository checks classic TypeScript 6.0.3 and native 7.0.2.
+For browsers and Deno, see [runtime support](#runtime-support).
+
+For an older checkout, follow the [single builder](docs/migrations/single-builder.md) and [API renaming](docs/migrations/api-renaming.md) migration guides.
+
+## Quickstart
+
+A **service** can be a configuration object, a database client, or a function.
+A **factory** creates a service. A **bag** holds those factories and gives each
+one access to the services it needs. Services are created when needed, and
+resources are cleaned up when you provide a disposer and close their bag.
+
+Use `di-bag/node` in Node or Bun. 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';
+
+const app = DiBag.createBuilder()
+  .register({
+    config: () => ({ greeting: 'Hello' }),
+    greeter: ({ config }: { config: { greeting: string } }) => ({
+      greet(name: string) {
+        return `${config.greeting}, ${name}!`;
+      },
+    }),
+  })
+  .build();
+
+const greeter = app.resolve('greeter');
+console.log(greeter.greet('Ada')); // Hello, Ada!
+```
+
+`.register()` adds factories to an immutable builder, `.build()` checks the
+declared graph and creates the bag, and
+`resolve('greeter')` creates the greeter and the config it needs. Resolving
+`greeter` again returns the same instance. Registration order does not matter.
+
+TypeScript knows that `greeter` has a `greet(name: string): string` method.
+Removing the `config` factory makes `.build()` a compile-time error. Changing
+`greeting` to a number also fails the type check because the greeter needs a string.
+
+## Swap a dependency for a test
+
+Use `fork()` to create a separate bag with a replacement dependency.
+Continuing the [quickstart](#quickstart):
+
+```ts
+const testApp = app.fork(['config'], {
+  config: () => ({ greeting: 'Hi' }),
+});
+
+try {
+  console.log(testApp.resolve('greeter').greet('Ada')); // Hi, Ada!
+  console.log(app.resolve('greeter').greet('Ada')); // Hello, Ada!
+} finally {
+  await testApp.close();
+}
+```
+
+The replacement must satisfy the original service contract. Each fork creates
+its own instances and owns its own cleanup; close it separately.
+
+## Work with async services
+
+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';
+
+const app = DiBag.createBuilder()
+  .register({
+    greeting: async () => 'Hello',
+    message: async ({ greeting }: { greeting: Promise<string> }) =>
+      `${await greeting}, Ada!`,
+  })
+  .build();
+
+console.log(await app.resolve('message')); // Hello, Ada!
+```
+
+By default, repeated resolutions share the same in-flight promise. Synchronous
+factories keep returning ordinary values. See
+[async behavior](docs/guides/tutorial.md#async-edges-are-explicit) for details.
+
+## Give resources a clear owner
+
+Wrap a factory with `withDisposal` to tell the bag how to release its result:
+
+```ts
+import { DiBag } from 'di-bag/node';
+
+const resources = DiBag.createBuilder()
+  .register({
+    cache: DiBag.withDisposal(
+      () => new Map<string, string>(),
+      (cache) => cache.clear(),
+    ),
+  })
+  .build();
+
+try {
+  resources.resolve('cache').set('answer', '42');
+} finally {
+  await resources.close();
+}
+```
+
+The same pattern works for connections, clients, and subscriptions. Cleanup can
+be asynchronous. Dependents close before their dependencies, and resources that
+were never created need no cleanup. Ordinary factories return borrowed values;
+having a `close()` method alone does not transfer ownership to the bag.
+
+## Scopes and forks
+
+| Operation | What it creates | Who closes it? |
+| --- | --- | --- |
+| `bag.createScope()` | A tracked child with fresh scoped services; root services are shared | Close it when its work ends. The parent also closes live children. |
+| `bag.fork()` | An independent bag with the same registrations and fresh instances | The caller closes it separately. |
+| `bag.fork(keys, overrides)` | An independent bag with selected dependencies replaced | The caller closes it separately. |
+
+For request handling, checked test replacements, and loading dynamic features,
+see the [server guide](docs/guides/server-integration.md) and
+[integration recipes](docs/guides/enterprise-integration.md).
+
+The [tutorial](docs/guides/tutorial.md) also covers modules with private services,
+typed tokens, class and function adapters, optional and lazy dependencies,
+collections, startup, metadata, observers, and plugin validation.
+
+## How it compares
+
+DI Bag's appeal is the combination of object-parameter factories, checks across
+the declared graph, and explicit resource ownership. Decorator-free composition,
+async factories, and TypeScript support are also available in other libraries.
+
+| Alternative | Reasons to choose it | DI Bag's different emphasis |
+| --- | --- | --- |
+| Manual dependency injection | Direct function calls may be all a small application needs. TypeScript checks their arguments. | Adds lazy caching, graph-wide composition checks, scopes, and coordinated cleanup. |
+| Awilix | Function and class registration, inferred cradle types, lifetime options, and runtime strict checks. | Checks declared factory requirements against the registrations at compile time. |
+| InversifyJS / TSyringe | Token and class-oriented containers; Inversify also offers decorator-free factory bindings and awaited async resolution. | Starts with object-parameter factories and immutable builders; checks accumulated graph contracts. |
+| Typed Inject | A close alternative with compile-time dependency checks, explicit dependency tuples, child injectors, and disposal. | Adds object-parameter dependencies, forward references, private module exports, and selected startup with rollback. |
+| Effect Context / Layer | Typed requirements, scoped resources, and composition within Effect's broader async and error model. | Keeps ordinary `T` and `Promise<T>` service values and explicit bag lifecycles. |
+| NestJS / Angular DI | Their native containers connect directly to framework components, testing tools, and lifecycles. | Provides standalone composition; applications supply the framework integration. |
+
+See the [comparison guide](docs/guides/comparison.md) for primary sources,
+differences in async and cleanup behavior, and the limits of these comparisons.
+There is no verified performance ranking against these libraries.
+
+## Runtime support
+
+The package has **zero runtime dependencies** and two entry points:
+
+| Import | Purpose |
+| --- | --- |
+| `di-bag/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. |
+
+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.
+
+## Tradeoffs and limits
+
+- **Agent context is still your responsibility.** DI Bag does not choose module
+  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.
+- **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.
+- **Framework integration belongs to the application.** DI Bag provides the
+  composition and ownership primitives; the host connects request, job, or UI
+  lifecycles.
+
+## Explore further
+
+| Resource | What you'll find |
+| --- | --- |
+| [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. |
+| [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. |
+| [Migration guides](docs/migrations/single-builder.md) | Before/after examples for the single builder and the [earlier API renaming](docs/migrations/api-renaming.md). |
+| [Development and verification](docs/guides/development.md) | Full checks, portable runtime testing, compiler scale, and performance evidence. |
+| [Documentation map](docs/README.md) | Current guides, migration history, and archived research and design notes. |
+
+## Working on DI Bag
+
+[![CI](https://github.com/dany-fedorov/di-bag/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/dany-fedorov/di-bag/actions/workflows/ci.yml)
+[![Runtime dependencies: 0](https://img.shields.io/badge/runtime_dependencies-0-2563eb)](package.json)
+[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](LICENSE)
+
+After `npm ci`, run the main checks with Node and Bun installed:
+
+```sh
+npm run platform:pin
+npm run check
+npm run check:native
+```
+
+Run an example with `bun run examples/composition.ts`. The
+[development guide](docs/guides/development.md) covers the remaining compiler,
+platform, and packaging checks and their tool requirements.
+
+## License
+
+[MIT](LICENSE) © Dany Fedorov

package/dist/acquisition-context.d.ts

@@ -0,0 +1,42 @@
+import type { Provider } from './provider';
+import type { Factory } from './registration';
+import type { Acquired, AcquisitionMode, NativeOutput, ModeOptions } from './acquisition-mode';
+import type { TokenDependencyContract } from './token-types';
+/** Cooperative cancellation information supplied to a context-aware acquisition. */
+export interface AcquisitionContext {
+    /** Aborted when the acquisition's owning scope begins closing. */
+    readonly signal: AbortSignal;
+}
+type ContextFactory = (this: void, deps: never, context: AcquisitionContext) => unknown;
+/** The named-dependency factory contract retained by an acquisition-context callback. */
+export type ContextualFactory<F extends ContextFactory> = (this: void, deps: Parameters<F> extends [] ? {} : Parameters<F>[0]) => ReturnType<F>;
+type FactoryOptions<M extends AcquisitionMode> = 'auto' extends M ? [options?: {
+    readonly context?: never;
+    readonly acquisitionMode?: M;
+}] : [options: {
+    readonly context?: never;
+    readonly acquisitionMode: M;
+}];
+/**
+ * Describe a named-dependency factory receiving its acquisition owner's cancellation signal.
+ * Context allocation is opt-in through `context: 'acquisition'`, independent of callback arity.
+ * @param callback - A receiver-free factory taking dependencies and acquisition context.
+ * @param options - Context selection and result policy; acquisitionMode defaults to auto.
+ * @returns A lazy provider preserving exact output and named dependencies; adds no ownership.
+ * @typeParam F - The complete callback signature, retaining dependency and output inference.
+ * @typeParam M - The raw, nativePromise, or configured auto acquisition policy.
+ */
+export declare function fromFactory<F extends (this: void, deps: never, context: AcquisitionContext) => ('nativePromise' extends M ? Promise<unknown> : unknown), M extends AcquisitionMode = 'auto'>(callback: F, options: {
+    readonly context: 'acquisition';
+} & ModeOptions<M>): Provider<ContextualFactory<F>, Readonly<{}>, readonly [], TokenDependencyContract, Acquired<ReturnType<F>, M>>;
+/**
+ * Describe a named-dependency factory with explicit or automatic result acquisition.
+ * Raw mode preserves the exact acquired value; nativePromise observes Promise fulfillment.
+ * @param callback - A receiver-free factory taking its named dependency object.
+ * @param options - Optional result acquisitionMode, defaulting to auto.
+ * @returns A lazy provider retaining exact output and dependency types without adding ownership.
+ * @typeParam F - The exact factory signature and exposed result.
+ * @typeParam M - The raw, nativePromise, or configured auto acquisition policy.
+ */
+export declare function fromFactory<F extends Factory, M extends AcquisitionMode = 'auto'>(callback: F & NativeOutput<ReturnType<NoInfer<F>>, NoInfer<M>>, ...options: FactoryOptions<M>): Provider<F, Readonly<{}>, readonly [], TokenDependencyContract, Acquired<ReturnType<F>, M>>;
+export {};

package/dist/acquisition-context.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromFactory = fromFactory;
+const errors_1 = require("./errors");
+const provider_1 = require("./provider");
+const provider_operations_1 = require("./provider-operations");
+const acquisition_mode_1 = require("./acquisition-mode");
+function fromFactory(callback, options) {
+    if (typeof callback !== 'function')
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_FACTORY', 'fromFactory requires a function', { operation: 'fromFactory' });
+    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';
+    const handle = (0, provider_1.createProvider)();
+    const create = contextual ? ((deps, context) => callback(deps, context)) : callback;
+    (0, provider_operations_1.retainDescription)(handle, (0, provider_operations_1.sourceDescription)(create, undefined, [], mode, contextual));
+    return handle;
+}

package/dist/acquisition-family.d.ts

@@ -0,0 +1,32 @@
+import type { BindingId } from './runtime';
+export type AcquisitionId = symbol;
+export interface AcquisitionHistory {
+    readonly id: AcquisitionId;
+    readonly previous: AcquisitionHistory | undefined;
+}
+export interface AttemptIdentity {
+    readonly id: AcquisitionId;
+    readonly bindingId: BindingId;
+    readonly ownerId: symbol;
+    readonly label: string;
+    readonly dependencies: Set<AcquisitionId>;
+    readonly ancestry: AcquisitionHistory | undefined;
+    state: 'creating' | 'pending' | 'ready' | 'failed' | 'disposing' | 'disposed';
+}
+/** Family-wide identity and traversal only; finalizers stay with their owner. */
+export declare class AcquisitionFamily {
+    private readonly attempts;
+    private readonly incoming;
+    private readonly constructing;
+    private readonly active;
+    add(attempt: AttemptIdentity): void;
+    deactivate(attempt: AttemptIdentity): void;
+    release(attempt: AttemptIdentity): void;
+    enter(attempt: AttemptIdentity): void;
+    leave(): void;
+    ancestry(bindingId: BindingId, ownerId: symbol, label: string, from?: AttemptIdentity): AcquisitionHistory | undefined;
+    dependencyPath(from: AttemptIdentity, dependency: string): readonly string[];
+    retireIncoming(attempt: AttemptIdentity): void;
+    recordEdge(from: AttemptIdentity, to: AttemptIdentity): void;
+    private path;
+}

package/dist/acquisition-family.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AcquisitionFamily = void 0;
+const errors_1 = require("./errors");
+/** Family-wide identity and traversal only; finalizers stay with their owner. */
+class AcquisitionFamily {
+    attempts = new Map();
+    incoming = new Map();
+    constructing = [];
+    // Only constructing/pending attempts can repeat an active binding+owner.
+    active = new Map();
+    add(attempt) {
+        this.attempts.set(attempt.id, attempt);
+        if (attempt.state !== 'creating' && attempt.state !== 'pending')
+            return;
+        let owners = this.active.get(attempt.bindingId);
+        if (!owners)
+            this.active.set(attempt.bindingId, owners = new Map());
+        let ids = owners.get(attempt.ownerId);
+        if (!ids)
+            owners.set(attempt.ownerId, ids = new Set());
+        ids.add(attempt.id);
+    }
+    deactivate(attempt) {
+        const owners = this.active.get(attempt.bindingId);
+        const ids = owners?.get(attempt.ownerId);
+        if (!ids)
+            return;
+        ids.delete(attempt.id);
+        if (!ids.size)
+            owners.delete(attempt.ownerId);
+        if (!owners.size)
+            this.active.delete(attempt.bindingId);
+    }
+    release(attempt) {
+        this.deactivate(attempt);
+        // Remove this consumer from reverse indexes before its outgoing edges clear.
+        for (const dependency of attempt.dependencies) {
+            const consumers = this.incoming.get(dependency);
+            consumers?.delete(attempt.id);
+            if (consumers?.size === 0)
+                this.incoming.delete(dependency);
+        }
+        this.incoming.delete(attempt.id);
+        this.attempts.delete(attempt.id);
+    }
+    enter(attempt) { this.constructing.push(attempt.id); }
+    leave() { this.constructing.pop(); }
+    ancestry(bindingId, ownerId, label, from) {
+        const source = from ?? this.attempts.get(this.constructing.at(-1));
+        const ancestry = source ? { id: source.id, previous: source.ancestry } : undefined;
+        // Most cold reads introduce an unrelated binding. Share history in O(1),
+        // materializing the original label order only for a possible active cycle.
+        if (!this.active.get(bindingId)?.has(ownerId))
+            return ancestry;
+        const history = [];
+        for (let entry = ancestry; entry; entry = entry.previous)
+            history.push(entry.id);
+        history.reverse();
+        // A public synchronous resolve has no proxy edge, but is still construction.
+        const active = [...new Set([...history, ...this.constructing])]
+            .map(id => this.attempts.get(id))
+            .filter((attempt) => !!attempt && (attempt.state === 'creating' || attempt.state === 'pending'));
+        const repeated = active.findIndex(attempt => attempt.bindingId === bindingId && attempt.ownerId === ownerId);
+        if (repeated !== -1)
+            throw (0, errors_1.libraryError)('DI_BAG_CYCLE', `cycle: ${[...active.slice(repeated).map(attempt => attempt.label), label].join(' -> ')}`, { path: Object.freeze([...active.slice(repeated).map(attempt => attempt.label), label]) });
+        return ancestry;
+    }
+    dependencyPath(from, dependency) {
+        // Linked histories stay shared on successful acquisition; only diagnostics
+        // materialize the consumer path in root-to-leaf order.
+        const history = [];
+        for (let entry = from.ancestry; entry; entry = entry.previous) {
+            const label = this.attempts.get(entry.id)?.label;
+            if (label !== undefined)
+                history.push(label);
+        }
+        history.reverse();
+        return Object.freeze([...history, from.label, dependency]);
+    }
+    retireIncoming(attempt) {
+        const consumers = this.incoming.get(attempt.id);
+        if (!consumers)
+            return;
+        for (const id of consumers)
+            this.attempts.get(id)?.dependencies.delete(attempt.id);
+        this.incoming.delete(attempt.id);
+    }
+    recordEdge(from, to) {
+        // A retained failed proxy may be used again, but its retired ID stays dead.
+        if (!this.attempts.has(from.id))
+            return;
+        // Re-reading an existing edge cannot introduce a new cycle.
+        if (from.dependencies.has(to.id))
+            return;
+        const path = this.path(to.id, from.id);
+        if (path) {
+            const labels = [...path, to.id].map(id => this.attempts.get(id).label);
+            throw (0, errors_1.libraryError)('DI_BAG_CYCLE', `cycle: ${labels.join(' -> ')}`, { path: Object.freeze(labels) });
+        }
+        from.dependencies.add(to.id);
+        const consumers = this.incoming.get(to.id) ?? new Set();
+        consumers.add(from.id);
+        this.incoming.set(to.id, consumers);
+    }
+    path(from, to) {
+        const attempt = this.attempts.get(from);
+        if (!attempt)
+            return undefined;
+        if (from === to)
+            return [from];
+        if (attempt.dependencies.size === 0)
+            return undefined;
+        const seen = new Set([from]);
+        const stack = [{ id: from, dependencies: attempt.dependencies.values() }];
+        while (stack.length) {
+            const next = stack[stack.length - 1].dependencies.next();
+            if (next.done) {
+                stack.pop();
+                continue;
+            }
+            const dependency = this.attempts.get(next.value);
+            if (!dependency)
+                continue;
+            if (next.value === to)
+                return [...stack.map(frame => frame.id), to];
+            if (seen.has(next.value))
+                continue;
+            seen.add(next.value);
+            stack.push({ id: next.value, dependencies: dependency.dependencies.values() });
+        }
+        return undefined;
+    }
+}
+exports.AcquisitionFamily = AcquisitionFamily;

package/dist/acquisition-mode.d.ts

@@ -0,0 +1,34 @@
+import type { LifecycleObservers } from './observers';
+import type { Unsatisfied } from './types';
+/**
+ * How an acquisition stage treats its returned value: configured classification,
+ * the exact raw value, or an observed native Promise fulfillment.
+ */
+export type AcquisitionMode = 'auto' | 'raw' | 'nativePromise';
+/** Portable facade configuration for `auto` acquisition stages. */
+export interface RuntimeOptions {
+    /** Return true only for native Promises the host can observe without thenable assimilation. */
+    readonly isNativePromise: (this: void, value: unknown) => boolean;
+}
+export interface RuntimeContext {
+    readonly isNativePromise?: RuntimeOptions['isNativePromise'];
+    readonly observers?: LifecycleObservers;
+}
+export declare const unconfigured: RuntimeContext;
+export declare function runtimeContext(options: RuntimeOptions, previous?: RuntimeContext): RuntimeContext;
+export type Acquired<O, M extends AcquisitionMode> = M extends 'raw' ? O : Awaited<O>;
+export type ModeOptions<M extends AcquisitionMode, Default extends AcquisitionMode = 'auto'> = Default extends M ? {
+    readonly acquisitionMode?: M;
+} : {
+    readonly acquisitionMode: M;
+};
+export type StageOptions<M extends AcquisitionMode> = 'auto' extends M ? [options?: {
+    readonly acquisitionMode: M;
+}] : [options: {
+    readonly acquisitionMode: M;
+}];
+export type NativeOutput<O, M extends AcquisitionMode> = 'nativePromise' extends M ? [O] extends [Promise<unknown>] ? unknown : Unsatisfied<'nativePromise acquisition requires a Promise output', {}> : unknown;
+export declare function acquisitionMode(options: {
+    readonly acquisitionMode?: AcquisitionMode;
+} | undefined, fallback?: AcquisitionMode): AcquisitionMode;
+export declare function requireClassificationCapability(modes: Iterable<AcquisitionMode>, context: RuntimeContext): void;

package/dist/acquisition-mode.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unconfigured = void 0;
+exports.runtimeContext = runtimeContext;
+exports.acquisitionMode = acquisitionMode;
+exports.requireClassificationCapability = requireClassificationCapability;
+const errors_1 = require("./errors");
+exports.unconfigured = Object.freeze({});
+function runtimeContext(options, previous = exports.unconfigured) {
+    if (typeof options !== 'object' || options === null)
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_CONFIGURATION', 'withConfiguration runtime requires isNativePromise', { operation: 'withConfiguration' });
+    const { isNativePromise } = options;
+    if (typeof isNativePromise !== 'function')
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_CONFIGURATION', 'withConfiguration runtime requires isNativePromise', { operation: 'withConfiguration' });
+    return Object.freeze({ ...previous, isNativePromise });
+}
+function acquisitionMode(options, fallback = 'auto') {
+    if (options === undefined)
+        return fallback;
+    if (typeof options !== 'object' || options === null)
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_ACQUISITION_MODE', 'invalid acquisition options', { option: 'acquisitionMode' });
+    const selected = options.acquisitionMode;
+    const mode = selected === undefined ? fallback : selected;
+    if (mode !== 'auto' && mode !== 'raw' && mode !== 'nativePromise')
+        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) {
+    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' });
+        }
+}

package/dist/acquisition.d.ts

@@ -0,0 +1,44 @@
+import type { BindingGraph, BindingId, BindingKey } from './runtime';
+import type { RegistrationSnapshot, AcquisitionSnapshot } from './inspection';
+import type { RuntimeContext } from './acquisition-mode';
+/** Mutable, runtime-local attempts. Binding descriptions never carry ownership. */
+export declare class ScopeAcquisitions {
+    private readonly graph;
+    private readonly context;
+    private readonly parent?;
+    readonly ownerId: symbol;
+    private readonly cache;
+    private readonly attempts;
+    private readonly retired;
+    private readonly failures;
+    private invocationSequence;
+    private readonly owned;
+    private state;
+    private closing;
+    private controller;
+    private acquisitionContext;
+    private cancellationStarted;
+    private cancellationCause;
+    private readonly shared;
+    private readonly family;
+    constructor(graph: BindingGraph, context: RuntimeContext, parent?: ScopeAcquisitions | undefined, shared?: readonly BindingId[]);
+    private owner;
+    resolve(key: BindingKey): unknown;
+    resolveAll(key: symbol): readonly unknown[];
+    private resolveCollection;
+    acquire(key: BindingKey): Promise<void>;
+    private takeExposed;
+    inspect(bindingId: BindingId, path?: readonly BindingId[]): readonly AcquisitionSnapshot<readonly unknown[]>[];
+    isTransient(bindingId: BindingId, path?: readonly BindingId[]): boolean;
+    /** Relationship uses the effective owner graph; frames use canonical attempts. */
+    inspectDescription(bindingId: BindingId): Pick<RegistrationSnapshot<object, readonly unknown[]>, 'registrationMetadata' | 'aliasTarget'>;
+    private assertAliasPath;
+    assertOpen(): void;
+    close(beforeDispose?: Promise<void>, cause?: unknown): Promise<void>;
+    private getContext;
+    private resolveBinding;
+    private eventFields;
+    private observeAttempt;
+    private retire;
+    private disposeAll;
+}