ripple-di 1.0.0

package/dist/index.mjs

@@ -0,0 +1,948 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { isPromise } from "node:util/types";
+//#region src/errors.ts
+/** Base class for errors thrown by Ripple DI. */
+var RippleError = class extends Error {};
+/** The dependency was requested without a provider or built-in factory. */
+var MissingProviderError = class extends RippleError {
+	dependencyName;
+	path;
+	constructor(dependencyName, path) {
+		super(path.length > 1 ? `Dependency "${dependencyName}" has no provider while resolving ${path.join(" → ")}.` : `Dependency "${dependencyName}" has no provider.`);
+		this.dependencyName = dependencyName;
+		this.path = path;
+		this.name = "MissingProviderError";
+	}
+};
+/** A dependency was used with a different runtime than the one that defined it. */
+var CrossRuntimeDependencyError = class extends RippleError {
+	dependencyName;
+	dependencyRuntimeName;
+	requestedRuntimeName;
+	constructor(dependencyName, dependencyRuntimeName, requestedRuntimeName) {
+		super(dependencyRuntimeName === requestedRuntimeName ? `Dependency "${dependencyName}" belongs to a different runtime instance also named "${dependencyRuntimeName}".` : `Dependency "${dependencyName}" belongs to runtime "${dependencyRuntimeName}" and cannot be used in runtime "${requestedRuntimeName}".`);
+		this.dependencyName = dependencyName;
+		this.dependencyRuntimeName = dependencyRuntimeName;
+		this.requestedRuntimeName = requestedRuntimeName;
+		this.name = "CrossRuntimeDependencyError";
+	}
+};
+/** `install()` was called while another installation or scope was unfinished. */
+var InstallationConflictError = class extends RippleError {
+	runtimeName;
+	reason;
+	scopeNames;
+	constructor(runtimeName, reason, scopeNames = []) {
+		super(reason === "active-installation" ? `Runtime "${runtimeName}" already has an active installation. Close it before calling install() again.` : reason === "closing-installation" ? `Runtime "${runtimeName}" is still closing its previous installation. Await Installation.close() before calling install() again.` : `Runtime "${runtimeName}" still has unfinished ${scopeNames.length === 1 ? "scope" : "scopes"}: ${scopeNames.map((name) => `"${name}"`).join(", ")}. Close ${scopeNames.length === 1 ? "it" : "them"} before calling install().`);
+		this.runtimeName = runtimeName;
+		this.reason = reason;
+		this.scopeNames = scopeNames;
+		this.name = "InstallationConflictError";
+	}
+};
+/** The same dependency appears more than once in one provision list. */
+var DuplicateProviderError = class extends RippleError {
+	dependencyName;
+	constructor(dependencyName) {
+		super(`Dependency "${dependencyName}" has more than one provision in the same scope.`);
+		this.dependencyName = dependencyName;
+		this.name = "DuplicateProviderError";
+	}
+};
+/** One owned-value provision was installed for more than one owner. */
+var OwnedProvisionReuseError = class extends RippleError {
+	dependencyName;
+	constructor(dependencyName) {
+		super(`The owned-value provision for dependency "${dependencyName}" has already been installed in a scope or installation.`);
+		this.dependencyName = dependencyName;
+		this.name = "OwnedProvisionReuseError";
+	}
+};
+/** Dependency factories called one another in a cycle. */
+var DependencyCycleError = class extends RippleError {
+	path;
+	constructor(path) {
+		super(`Dependency cycle: ${path.join(" → ")}.`);
+		this.path = path;
+		this.name = "DependencyCycleError";
+	}
+};
+/** A dependency factory returned a `Promise` instead of the value. */
+var AsyncFactoryError = class extends RippleError {
+	dependencyName;
+	path;
+	constructor(dependencyName, path) {
+		super(`Factory for dependency "${dependencyName}" returned a Promise while resolving ${path.join(" → ")}. Factories are synchronous because dependency reads made after an await are not tracked. Wrap the result in asValue() when the promise itself is the value.`);
+		this.dependencyName = dependencyName;
+		this.path = path;
+		this.name = "AsyncFactoryError";
+	}
+};
+/** A dependency factory threw an error available through this error's `cause`. */
+var FactoryError = class extends RippleError {
+	dependencyName;
+	path;
+	constructor(dependencyName, path, cause) {
+		super(`Factory for dependency "${dependencyName}" failed while resolving ${path.join(" → ")}.`, { cause });
+		this.dependencyName = dependencyName;
+		this.path = path;
+		this.name = "FactoryError";
+	}
+};
+/** An operation tried to use a scope that is retiring, closing, or closed. */
+var ScopeClosedError = class extends RippleError {
+	targetName;
+	scopeName;
+	scopeId;
+	state;
+	constructor(targetName, scopeName, scopeId, state) {
+		super(`Scope "${scopeName}" (#${scopeId}) is ${state}; cannot use "${targetName}".`);
+		this.targetName = targetName;
+		this.scopeName = scopeName;
+		this.scopeId = scopeId;
+		this.state = state;
+		this.name = "ScopeClosedError";
+	}
+};
+/** A factory tried to read explicitly from a different scope. */
+var CrossScopeResolutionError = class extends RippleError {
+	dependencyName;
+	factoryScopeName;
+	requestedScopeName;
+	constructor(dependencyName, factoryScopeName, requestedScopeName) {
+		super(`Factory in scope "${factoryScopeName}" cannot explicitly resolve "${dependencyName}" from scope "${requestedScopeName}".`);
+		this.dependencyName = dependencyName;
+		this.factoryScopeName = factoryScopeName;
+		this.requestedScopeName = requestedScopeName;
+		this.name = "CrossScopeResolutionError";
+	}
+};
+/** A dependency factory tried to manage runtime context or lifecycle. */
+var FactoryScopeOperationError = class extends RippleError {
+	dependencyName;
+	operation;
+	constructor(dependencyName, operation) {
+		super(`Factory for dependency "${dependencyName}" cannot call ${operation}.`);
+		this.dependencyName = dependencyName;
+		this.operation = operation;
+		this.name = "FactoryScopeOperationError";
+	}
+};
+/** Code running in or started by a disposer used the runtime being closed. */
+var DisposerContextError = class extends RippleError {
+	targetName;
+	scopeName;
+	scopeId;
+	constructor(targetName, scopeName, scopeId) {
+		super(`Cannot use "${targetName}" from code running in or started by a disposer for scope "${scopeName}" (#${scopeId}).`);
+		this.targetName = targetName;
+		this.scopeName = scopeName;
+		this.scopeId = scopeId;
+		this.name = "DisposerContextError";
+	}
+};
+/**
+* A `withOverrides` callback created child scopes and returned without closing
+* them.
+*
+* Ripple DI force-closes the leaked scopes before throwing this error.
+*/
+var LeakedChildScopeError = class extends RippleError {
+	scopeName;
+	leakedChildCount;
+	constructor(scopeName, leakedChildCount) {
+		super(`Scope "${scopeName}" leaked ${leakedChildCount} child ${leakedChildCount === 1 ? "scope" : "scopes"}.`);
+		this.scopeName = scopeName;
+		this.leakedChildCount = leakedChildCount;
+		this.name = "LeakedChildScopeError";
+	}
+};
+//#endregion
+//#region src/dependency.ts
+let nextDependencyId = 1;
+const dependencyNodes = /* @__PURE__ */ new WeakMap();
+/** Fully initialized metadata object captured by its own callable dependency. */
+var DependencyNodeImpl = class {
+	id = nextDependencyId++;
+	name;
+	runtime;
+	defaultFactory;
+	dispose;
+	dependency;
+	constructor(definition) {
+		this.name = definition.name ?? `dependency#${this.id}`;
+		this.runtime = definition.runtime;
+		this.defaultFactory = definition.defaultFactory;
+		this.dispose = definition.dispose;
+		this.dependency = (() => this.runtime.readCallable(this));
+	}
+};
+/** Creates a property-free callable whose metadata lives only in a `WeakMap`. */
+function createDependency(definition) {
+	const node = new DependencyNodeImpl(definition);
+	dependencyNodes.set(node.dependency, node);
+	return node.dependency;
+}
+function nodeOf(dependency) {
+	const node = dependencyNodes.get(dependency);
+	if (!node) throw new TypeError("Value is not a dependency created by this copy of ripple-di. If it came from ripple-di, the package may be installed or bundled more than once.");
+	return node;
+}
+//#endregion
+//#region src/value.ts
+const markedValues = /* @__PURE__ */ new WeakMap();
+/**
+* Uses a factory result as the dependency value even when it is a `Promise`.
+*
+* A factory that returns a promise is normally rejected, because dependency
+* reads made after an `await` are not tracked.
+* Wrap the result when the promise itself is the value the dependency holds.
+* A value that merely implements `then`, such as a query builder, is an
+* ordinary value and does not need this.
+*/
+function asValue(value) {
+	const marked = {};
+	markedValues.set(marked, { value });
+	return marked;
+}
+/** Returns the boxed payload, or `undefined` for an ordinary factory result. */
+function markedValueOf(result) {
+	return typeof result === "object" && result !== null ? markedValues.get(result) : void 0;
+}
+//#endregion
+//#region src/provide.ts
+const provisionRecords = /* @__PURE__ */ new WeakMap();
+const claimedOwnedProvisions = /* @__PURE__ */ new WeakSet();
+function createProvision(dependency, spec) {
+	nodeOf(dependency);
+	const provision = {};
+	provisionRecords.set(provision, {
+		dependency,
+		spec
+	});
+	return provision;
+}
+function provisionOf(provision) {
+	const record = provisionRecords.get(provision);
+	if (!record) throw new TypeError("Value is not a provision created by this copy of ripple-di. If it came from ripple-di, the package may be installed or bundled more than once.");
+	return record;
+}
+/** Reads provision input as the list the rest of the library works with. */
+function provisionListOf(input) {
+	return Array.isArray(input) ? input : [input];
+}
+/**
+* Transfers each owned-value provision to one owner after list validation.
+*
+* Checking the complete list before recording claims keeps failed scope
+* creation atomic.
+*/
+function claimOwnedProvisions(provisions) {
+	const owned = provisions.filter((provision) => provisionOf(provision).spec.kind === "owned-value");
+	for (const provision of owned) if (claimedOwnedProvisions.has(provision)) throw new OwnedProvisionReuseError(nodeOf(provisionOf(provision).dependency).name);
+	for (const provision of owned) claimedOwnedProvisions.add(provision);
+}
+/**
+* Uses an existing value for a dependency in a scope or installation.
+*
+* Ripple DI cleans up the value only when `options.dispose` is provided.
+* Pass `true` to reuse cleanup configured by `defineDependency`, or pass a
+* callback to override it.
+* A function passed as the value remains a value rather than becoming a factory.
+* A provision that transfers ownership can be used in only one scope or
+* installation.
+*/
+function provide(dependency, value, options = {}) {
+	if (markedValueOf(value)) throw new TypeError(`Dependency "${nodeOf(dependency).name}" was given an asValue() marker instead of a value. Pass the value itself to provide(), or return the marker from provideFactory().`);
+	if (options.dispose) {
+		const node = nodeOf(dependency);
+		const dispose = options.dispose === true ? node.dispose : options.dispose;
+		if (!dispose) throw new TypeError(`Dependency "${node.name}" has no dispose callback to reuse.`);
+		return createProvision(dependency, {
+			kind: "owned-value",
+			value,
+			dispose
+		});
+	}
+	return createProvision(dependency, {
+		kind: "value",
+		value
+	});
+}
+/**
+* Creates a dependency override on demand in the receiving scope or
+* installation.
+*
+* The factory must be synchronous.
+* Calls to other dependencies inside it are tracked automatically.
+* The receiving scope or installation owns the created value.
+* When the dependency has a configured `dispose` callback, that callback
+* cleans up the override when its owner closes.
+*/
+function provideFactory(dependency, factory) {
+	return createProvision(dependency, {
+		kind: "factory",
+		factory
+	});
+}
+//#endregion
+//#region src/evaluation.ts
+const evaluationStack = [];
+function currentEvaluation() {
+	return evaluationStack.at(-1);
+}
+/** Rejects scope management while a synchronous factory frame is active. */
+function assertOutsideEvaluation(runtime, operation) {
+	const frame = currentEvaluation();
+	if (frame?.runtime === runtime) throw new FactoryScopeOperationError(frame.node.name, operation);
+}
+function pushEvaluation(frame) {
+	evaluationStack.push(frame);
+}
+function popEvaluation(frame) {
+	if (evaluationStack.pop() !== frame) throw new Error("ripple-di evaluation stack became inconsistent.");
+}
+function cycleStart(node, providerStamp) {
+	return evaluationStack.findIndex((frame) => frame.node === node && frame.providerStamp.identity === providerStamp.identity);
+}
+function resolutionPath(ending) {
+	const path = evaluationStack.map((frame) => frame.node.name);
+	if (ending && evaluationStack.at(-1)?.node !== ending) path.push(ending.name);
+	return path;
+}
+function framesFrom(index) {
+	return evaluationStack.slice(index);
+}
+//#endregion
+//#region src/graph.ts
+/** Internal key for traversing scope ancestry without exposing parent handles. */
+const scopeParent = Symbol("scope-parent");
+//#endregion
+//#region src/resolution.ts
+/** Internal resolution failure that must not be attributed to a user factory. */
+var ResolutionInvariantError = class extends RippleError {
+	constructor(message) {
+		super(`Internal ripple-di resolution invariant failed: ${message}`);
+		this.name = "ResolutionInvariantError";
+	}
+};
+/** Public and callable reads are tracked against the frame that initiated them. */
+function resolveTracked(scope, node) {
+	const consumerFrame = currentEvaluation();
+	try {
+		assertCompatible(scope, node);
+		if (consumerFrame && consumerFrame.runtime !== scope.runtime) throw new CrossRuntimeDependencyError(node.name, node.runtime.name, consumerFrame.runtime.name);
+		assertPubliclyReadable(scope, node.name);
+		if (consumerFrame && consumerFrame.scope !== scope) throw new CrossScopeResolutionError(node.name, consumerFrame.scope.name, scope.name);
+		const resolved = resolveUntracked(scope, node);
+		if (consumerFrame) recordDependency(consumerFrame, node, resolved.stamp);
+		return resolved.value;
+	} catch (error) {
+		if (consumerFrame) consumerFrame.hasFailedDependencyRead = true;
+		throw error;
+	}
+}
+/**
+* Resolves without creating a dependency edge.
+*
+* Ancestor validation uses this path so implementation reads never become
+* dependencies of the consumer factory currently on the synchronous stack.
+*/
+function resolveUntracked(requestedScope, node) {
+	assertCompatible(requestedScope, node);
+	const cached = requestedScope.viewCache.get(asUnknownNode(node));
+	if (cached) {
+		const typed = cached;
+		assertUsableRef(typed, node, requestedScope);
+		return typed;
+	}
+	const provider = findEffectiveProvider(requestedScope, node);
+	if (!provider) throw new MissingProviderError(node.name, resolutionPath(asUnknownNode(node)));
+	if (provider.spec.kind === "value" || provider.spec.kind === "owned-value") {
+		const resolved = {
+			value: provider.spec.value,
+			stamp: provider.stamp
+		};
+		requestedScope.viewCache.set(asUnknownNode(node), resolved);
+		return resolved;
+	}
+	const reusable = findReusableAncestorCell(requestedScope, node, provider);
+	if (reusable) {
+		requestedScope.viewCache.set(asUnknownNode(node), reusable);
+		return reusable;
+	}
+	return materialize(requestedScope, node, provider);
+}
+function findEffectiveProvider(scope, node) {
+	for (let cursor = scope; cursor; cursor = cursor[scopeParent]) {
+		const explicit = cursor.bindings.get(asUnknownNode(node));
+		if (explicit) return explicit;
+	}
+	return scope.runtime.getDefaultProvider(node);
+}
+function findReusableAncestorCell(requestedScope, node, provider) {
+	for (let cursor = requestedScope[scopeParent]; cursor; cursor = cursor[scopeParent]) {
+		const candidate = cursor.ownedCells.get(asUnknownNode(node));
+		if (candidate && isReusable(candidate, provider, requestedScope)) return candidate;
+	}
+}
+function isReusable(cell, provider, requestedScope) {
+	if (cell.state !== "ready" || !cell.reusable || cell.owner.state !== "active" && cell.owner.state !== "retiring" || cell.providerStamp.identity !== provider.stamp.identity) return false;
+	for (const record of cell.dependencies) try {
+		if (resolveUntracked(requestedScope, nodeOf(record.dependency)).stamp.identity !== record.stamp.identity) return false;
+	} catch {
+		return false;
+	}
+	return true;
+}
+function materialize(requestedScope, node, provider) {
+	if (provider.spec.kind !== "factory") throw new Error("ripple-di attempted to materialize a non-factory provider.");
+	const start = cycleStart(asUnknownNode(node), provider.stamp);
+	if (start >= 0) throw new DependencyCycleError([...framesFrom(start).map((frame) => frame.node.name), node.name]);
+	const frame = {
+		runtime: requestedScope.runtime,
+		scope: requestedScope,
+		node: asUnknownNode(node),
+		providerStamp: provider.stamp,
+		dependencies: /* @__PURE__ */ new Map(),
+		hasFailedDependencyRead: false
+	};
+	pushEvaluation(frame);
+	let value;
+	try {
+		const produced = provider.spec.factory();
+		const marked = markedValueOf(produced);
+		if (marked) value = marked.value;
+		else if (isPromise(produced)) throw new AsyncFactoryError(node.name, resolutionPath());
+		else value = produced;
+	} catch (error) {
+		if (error instanceof RippleError) throw error;
+		throw new FactoryError(node.name, resolutionPath(), error);
+	} finally {
+		popEvaluation(frame);
+	}
+	const dependencies = [...frame.dependencies].map(([dependencyNode, stamp]) => ({
+		dependency: dependencyNode.dependency,
+		stamp
+	}));
+	const reusable = !frame.hasFailedDependencyRead;
+	const owner = !reusable ? requestedScope : deepestScope([provider.stamp.home, ...dependencies.map((record) => record.stamp.home)]);
+	if (!isAncestorOrSelf(owner, requestedScope)) throw new Error(`ripple-di owner invariant failed for dependency "${node.name}".`);
+	const cell = {
+		dependency: node.dependency,
+		node,
+		value,
+		owner,
+		stamp: {
+			kind: "cell",
+			identity: Symbol(`${node.name}:cell`),
+			dependency: node.dependency,
+			home: owner
+		},
+		providerStamp: provider.stamp,
+		dependencies,
+		reusable,
+		state: "ready"
+	};
+	owner.publish(cell, requestedScope);
+	return cell;
+}
+function recordDependency(frame, node, stamp) {
+	const unknownNode = asUnknownNode(node);
+	const previous = frame.dependencies.get(unknownNode);
+	if (previous && previous.identity !== stamp.identity) throw new ResolutionInvariantError(`Dependency "${node.name}" changed identity while evaluating "${frame.node.name}".`);
+	frame.dependencies.set(unknownNode, stamp);
+}
+function assertCompatible(scope, node) {
+	if (scope.runtime !== node.runtime) throw new CrossRuntimeDependencyError(node.name, node.runtime.name, scope.runtime.name);
+}
+function assertPubliclyReadable(scope, dependencyName) {
+	const owner = scope.runtime.teardown.getStore();
+	if (owner) throw new DisposerContextError(dependencyName, owner.name, owner.id);
+	if (scope.state !== "active") throw new ScopeClosedError(dependencyName, scope.name, scope.id, scope.state);
+}
+function assertUsableRef(resolved, node, requestedScope) {
+	if (resolved.stamp.kind !== "cell") return;
+	const cell = resolved;
+	if (cell.state !== "ready" || cell.owner.state !== "active" && cell.owner.state !== "retiring") throw new ScopeClosedError(node.name, requestedScope.name, requestedScope.id, requestedScope.state);
+}
+function deepestScope(scopes) {
+	return scopes.reduce((deepest, scope) => scope.depth > deepest.depth ? scope : deepest);
+}
+function isAncestorOrSelf(ancestor, scope) {
+	for (let cursor = scope; cursor; cursor = cursor[scopeParent]) if (cursor === ancestor) return true;
+	return false;
+}
+function asUnknownNode(node) {
+	return node;
+}
+//#endregion
+//#region src/scope.ts
+let nextScopeId = 1;
+/**
+* Immutable binding overlay and physical owner of locally published cells.
+*
+* The binding Map is populated only during construction, while caches,
+* children, finalizers, and lifecycle state evolve until teardown completes.
+*/
+var ScopeImpl = class ScopeImpl {
+	runtime;
+	id = nextScopeId++;
+	name;
+	depth;
+	bindings = /* @__PURE__ */ new Map();
+	viewCache = /* @__PURE__ */ new Map();
+	ownedCells = /* @__PURE__ */ new Map();
+	finalizers = [];
+	children = /* @__PURE__ */ new Set();
+	state = "active";
+	lifecycle = createDeferred();
+	closingStarted = false;
+	[scopeParent];
+	constructor(runtime, parent, records) {
+		this.runtime = runtime;
+		this[scopeParent] = parent;
+		this.depth = parent ? parent.depth + 1 : 0;
+		this.name = `${runtime.name}/scope-${this.id}`;
+		for (const record of records) this.install(record);
+		parent?.children.add(this);
+	}
+	resolve(dependency) {
+		const node = nodeOf(dependency);
+		return resolveTracked(this, node);
+	}
+	createScope(provisions = []) {
+		this.runtime.assertScopeManagementAllowed("Scope.createScope");
+		this.assertActive("<createScope>");
+		const records = validateProvisions(this.runtime, provisionListOf(provisions));
+		return new ScopeImpl(this.runtime, this, records);
+	}
+	run(callback) {
+		this.runtime.assertScopeManagementAllowed("Scope.run");
+		this.assertActive("<run>");
+		return this.runtime.ambient.run(this, callback);
+	}
+	withOverrides(provisions, callback) {
+		this.runtime.assertScopeManagementAllowed("Scope.withOverrides");
+		return withChildScope(this, provisions, callback);
+	}
+	retire() {
+		this.runtime.assertScopeManagementAllowed("Scope.retire");
+		if (this.state === "active") {
+			this.state = "retiring";
+			if (this.children.size === 0) this.beginClose(false);
+		}
+		return this.lifecycle.promise;
+	}
+	close() {
+		this.runtime.assertScopeManagementAllowed("Scope.close");
+		if (this.state !== "closed" && this.state !== "closing") {
+			this.state = "closing";
+			this.beginClose(true);
+		}
+		return this.lifecycle.promise;
+	}
+	publish(cell, requestedScope) {
+		if (this.state !== "active" && this.state !== "retiring") throw new ScopeClosedError(cell.node.name, this.name, this.id, this.state);
+		this.ownedCells.set(cell.node, cell);
+		this.viewCache.set(cell.node, cell);
+		requestedScope.viewCache.set(cell.node, cell);
+		if (cell.node.dispose) {
+			const dispose = cell.node.dispose;
+			this.finalizers.push({
+				cell,
+				run: () => dispose(cell.value)
+			});
+		}
+	}
+	install(record) {
+		const node = nodeOf(record.dependency);
+		const bound = {
+			spec: record.spec,
+			stamp: {
+				kind: "binding",
+				identity: Symbol(`${node.name}:binding`),
+				dependency: record.dependency,
+				home: this
+			}
+		};
+		this.bindings.set(node, bound);
+		if (record.spec.kind === "owned-value") {
+			const { dispose, value } = record.spec;
+			this.finalizers.push({ run: () => dispose(value) });
+		}
+	}
+	assertActive(operation) {
+		if (this.state !== "active") throw new ScopeClosedError(operation, this.name, this.id, this.state);
+	}
+	beginClose(force) {
+		if (this.closingStarted) return;
+		this.closingStarted = true;
+		this.state = "closing";
+		this.performClose(force);
+	}
+	async performClose(force) {
+		const errors = [];
+		try {
+			if (force) for (const child of [...this.children]) try {
+				await child.close();
+			} catch (error) {
+				collectError(errors, error);
+			}
+			for (let index = this.finalizers.length - 1; index >= 0; index -= 1) {
+				const finalizer = this.finalizers[index];
+				if (!finalizer) continue;
+				if (finalizer.cell) finalizer.cell.state = "disposing";
+				try {
+					await this.runtime.ambient.run(this, () => this.runtime.teardown.run(this, () => finalizer.run()));
+				} catch (error) {
+					collectError(errors, error);
+				} finally {
+					if (finalizer.cell) finalizer.cell.state = "disposed";
+				}
+			}
+		} finally {
+			this.finalizers.length = 0;
+			this.viewCache.clear();
+			this.ownedCells.clear();
+			this.bindings.clear();
+			this.state = "closed";
+			this[scopeParent]?.childClosed(this);
+		}
+		if (errors.length > 0) this.lifecycle.reject(new AggregateError(errors, `Errors while closing scope "${this.name}".`));
+		else this.lifecycle.resolve();
+	}
+	childClosed(child) {
+		this.children.delete(child);
+		if (this.state === "retiring" && this.children.size === 0) this.beginClose(false);
+	}
+};
+/**
+* Resolves and validates the complete provision list before scope construction.
+*
+* This boundary prevents duplicate or foreign input from acquiring membership,
+* installing bindings, or registering owned-value finalizers partially.
+*/
+function validateProvisions(runtime, provisions) {
+	const records = provisions.map(provisionOf);
+	const seen = /* @__PURE__ */ new Set();
+	for (const record of records) {
+		const node = nodeOf(record.dependency);
+		if (node.runtime !== runtime) throw new CrossRuntimeDependencyError(node.name, node.runtime.name, runtime.name);
+		if (seen.has(node)) throw new DuplicateProviderError(node.name);
+		seen.add(node);
+	}
+	claimOwnedProvisions(provisions);
+	return records;
+}
+/**
+* Executes a callback in a temporary ambient child and guarantees force cleanup.
+*
+* Callback errors, leaked children, and teardown failures are preserved together
+* when more than one condition occurs.
+*/
+async function withChildScope(parent, provisions, callback) {
+	const child = parent.createScope(provisions);
+	const errors = [];
+	let callbackFailed = false;
+	let result;
+	try {
+		result = await child.run(() => callback(child));
+	} catch (error) {
+		callbackFailed = true;
+		errors.push(error);
+	}
+	if (child.children.size > 0) errors.push(new LeakedChildScopeError(child.name, child.children.size));
+	try {
+		await child.close();
+	} catch (error) {
+		collectError(errors, error);
+	}
+	if (errors.length === 1) throw errors[0];
+	if (errors.length > 1) throw new AggregateError(errors, `Errors in scoped callback "${child.name}".`);
+	if (callbackFailed) throw new Error("ripple-di lost a scoped callback error.");
+	return result;
+}
+function createDeferred() {
+	let settle;
+	let reject;
+	return {
+		promise: new Promise((resolve, rejectPromise) => {
+			settle = resolve;
+			reject = rejectPromise;
+		}),
+		resolve: settle,
+		reject
+	};
+}
+function collectError(errors, error) {
+	if (error instanceof AggregateError) errors.push(...error.errors);
+	else errors.push(error);
+}
+//#endregion
+//#region src/overrides.ts
+/** Immutable layer that knows the layers it was extended from. */
+var OverrideRunnerImpl = class {
+	runtime;
+	base;
+	factory;
+	constructor(runtime, base, factory) {
+		this.runtime = runtime;
+		this.base = base;
+		this.factory = factory;
+	}
+	run(callback) {
+		this.runtime.assertScopeManagementAllowed("OverrideRunner.run");
+		return this.enterLayers(this.runtime.currentAmbientScope(), callback);
+	}
+	wrap(callback) {
+		const runner = this;
+		return function wrapped(...args) {
+			return runner.run(() => callback.apply(this, args));
+		};
+	}
+	extend(factory) {
+		return createRunner(this.runtime, this, factory);
+	}
+	/**
+	* Enters the extended layers from the outside in.
+	*
+	* Staying async keeps a failing provision factory a rejection instead of a
+	* synchronous throw, exactly like an invalid provision list.
+	*/
+	async enterLayers(parent, callback) {
+		const enter = (scope) => withChildScope(scope, this.factory(), callback);
+		return this.base ? this.base.enterLayers(parent, enter) : enter(parent);
+	}
+};
+function createRunner(runtime, base, factory) {
+	if (typeof factory !== "function") throw new TypeError("An override runner needs a function returning provisions, so that every call builds its provisions again.");
+	return new OverrideRunnerImpl(runtime, base, factory);
+}
+/** Creates the first layer of a runner for one runtime. */
+function createOverrideRunnerFor(runtime, factory) {
+	return createRunner(runtime, void 0, factory);
+}
+/** Creates a value override bound to one dependency of one runtime. */
+function createValueOverrideFor(runtime, dependency, options) {
+	return (value, callback) => {
+		runtime.assertScopeManagementAllowed("ValueOverride");
+		return withChildScope(runtime.currentAmbientScope(), provide(dependency, value, options), callback);
+	};
+}
+//#endregion
+//#region src/runtime.ts
+let nextRuntimeId = 1;
+/** Concrete owner of one independent dependency graph. */
+var RuntimeImpl = class {
+	id = nextRuntimeId++;
+	name;
+	ambient = new AsyncLocalStorage();
+	teardown = new AsyncLocalStorage();
+	root;
+	defaults = /* @__PURE__ */ new Map();
+	activeInstallation;
+	closingInstallation;
+	constructor(options = {}) {
+		this.name = options.name ?? `runtime-${this.id}`;
+		this.root = new ScopeImpl(this, void 0, []);
+	}
+	defineDependency(factoryOrOptions, maybeOptions) {
+		const isFactory = typeof factoryOrOptions === "function";
+		const factory = isFactory ? factoryOrOptions : void 0;
+		const options = (isFactory ? maybeOptions : factoryOrOptions) ?? {};
+		return createDependency({
+			name: options.name,
+			runtime: this,
+			defaultFactory: factory,
+			dispose: options.dispose
+		});
+	}
+	install(provisions) {
+		this.assertScopeManagementAllowed("Runtime.install");
+		if (this.root.state !== "active") throw new ScopeClosedError("Runtime.install", this.root.name, this.root.id, this.root.state);
+		if (this.activeInstallation) throw new InstallationConflictError(this.name, "active-installation");
+		if (this.closingInstallation) throw new InstallationConflictError(this.name, "closing-installation");
+		if (this.root.children.size > 0) throw new InstallationConflictError(this.name, "live-scopes", [...this.root.children].map((scope) => scope.name));
+		const installation = new InstallationImpl(this, this.root.createScope(provisions));
+		this.activeInstallation = installation;
+		return installation;
+	}
+	resolve(dependency) {
+		const node = nodeOf(dependency);
+		this.assertOwnDependency(node);
+		return resolveTracked(this.currentScope(node.name), node);
+	}
+	createScope(provisions = []) {
+		this.assertScopeManagementAllowed("Runtime.createScope");
+		return this.currentAmbientScope().createScope(provisions);
+	}
+	withOverrides(provisions, callback) {
+		this.assertScopeManagementAllowed("Runtime.withOverrides");
+		return withChildScope(this.currentAmbientScope(), provisions, callback);
+	}
+	createOverrideRunner(factory) {
+		return createOverrideRunnerFor(this, factory);
+	}
+	createValueOverride(dependency, options = {}) {
+		this.assertOwnDependency(nodeOf(dependency));
+		return createValueOverrideFor(this, dependency, options);
+	}
+	dispose() {
+		this.assertScopeManagementAllowed("Runtime.dispose");
+		this.activeInstallation = void 0;
+		return this.root.close();
+	}
+	closeInstallation(installation) {
+		if (this.activeInstallation === installation) {
+			this.activeInstallation = void 0;
+			this.closingInstallation = installation;
+			return installation.scope.close().then(() => {
+				this.finishClosingInstallation(installation);
+			}, (error) => {
+				this.finishClosingInstallation(installation);
+				throw error;
+			});
+		}
+		return installation.scope.close();
+	}
+	assertScopeManagementAllowed(operation) {
+		assertOutsideEvaluation(this, operation);
+		const owner = this.teardown.getStore();
+		if (owner) throw new DisposerContextError(operation, owner.name, owner.id);
+	}
+	currentAmbientScope() {
+		return this.ambient.getStore() ?? this.baseScope();
+	}
+	readCallable(node) {
+		const frame = currentEvaluation();
+		if (frame) {
+			if (frame.runtime !== this) {
+				frame.hasFailedDependencyRead = true;
+				throw new CrossRuntimeDependencyError(node.name, this.name, frame.runtime.name);
+			}
+			return resolveTracked(frame.scope, node);
+		}
+		return resolveTracked(this.ambient.getStore() ?? this.baseScope(), node);
+	}
+	getDefaultProvider(node) {
+		if (!node.defaultFactory) return;
+		const unknownNode = node;
+		let provider = this.defaults.get(unknownNode);
+		if (!provider) {
+			provider = {
+				spec: {
+					kind: "factory",
+					factory: node.defaultFactory
+				},
+				stamp: {
+					kind: "binding",
+					identity: Symbol(`${node.name}:default-binding`),
+					dependency: node.dependency,
+					home: this.root
+				}
+			};
+			this.defaults.set(unknownNode, provider);
+		}
+		return provider;
+	}
+	currentScope(operation) {
+		const frame = currentEvaluation();
+		if (frame) {
+			if (frame.runtime !== this) {
+				frame.hasFailedDependencyRead = true;
+				throw new CrossRuntimeDependencyError(operation, this.name, frame.runtime.name);
+			}
+			return frame.scope;
+		}
+		return this.ambient.getStore() ?? this.baseScope();
+	}
+	baseScope() {
+		return this.activeInstallation?.scope ?? this.root;
+	}
+	finishClosingInstallation(installation) {
+		if (this.closingInstallation === installation) this.closingInstallation = void 0;
+	}
+	assertOwnDependency(node) {
+		if (node.runtime !== this) throw new CrossRuntimeDependencyError(node.name, node.runtime.name, this.name);
+	}
+};
+var InstallationImpl = class {
+	runtime;
+	scope;
+	closePromise;
+	constructor(runtime, scope) {
+		this.runtime = runtime;
+		this.scope = scope;
+	}
+	close() {
+		this.runtime.assertScopeManagementAllowed("Installation.close");
+		this.closePromise ??= this.runtime.closeInstallation(this);
+		return this.closePromise;
+	}
+};
+/**
+* Creates an independent dependency graph.
+*
+* Define its dependencies through the methods on the returned runtime.
+*/
+function createRuntime(options = {}) {
+	return new RuntimeImpl(options);
+}
+const globalRuntime = new RuntimeImpl({ name: "global" });
+function defineDependency(factoryOrOptions, maybeOptions) {
+	if (typeof factoryOrOptions === "function") return globalRuntime.defineDependency(factoryOrOptions, maybeOptions);
+	return globalRuntime.defineDependency(factoryOrOptions);
+}
+/**
+* Installs long-lived providers for module-level dependencies.
+*
+* Scoped overrides still take priority. Close the returned installation to
+* remove its providers and clean up everything created from them.
+*/
+function install(provisions) {
+	return globalRuntime.install(provisions);
+}
+/** Returns a dependency value from the current scope. */
+function resolve(dependency) {
+	return globalRuntime.resolve(dependency);
+}
+/** Creates a manually managed scope with optional dependency overrides. */
+function createScope(provisions = []) {
+	return globalRuntime.createScope(provisions);
+}
+/**
+* Runs a callback with temporary dependency overrides.
+*
+* Overrides remain active across `await`, stay isolated from concurrent
+* callbacks, and are cleaned up when the callback finishes.
+*/
+function withOverrides(provisions, callback) {
+	return globalRuntime.withOverrides(provisions, callback);
+}
+/**
+* Prepares dependency overrides that are applied again to each call of the
+* returned runner.
+*
+* The factory runs again for every call, so a call can own the values it
+* provides.
+*/
+function createOverrideRunner(factory) {
+	return globalRuntime.createOverrideRunner(factory);
+}
+/**
+* Prepares a helper that replaces one dependency with a value for one callback.
+*
+* Use it for a dependency that application code supplies the same way in many
+* places, such as a client or a request context.
+* Ownership options given here apply to every value the helper receives.
+*/
+function createValueOverride(dependency, options) {
+	return globalRuntime.createValueOverride(dependency, options);
+}
+/** Closes every scope and cleans up every owned value. */
+function dispose() {
+	return globalRuntime.dispose();
+}
+//#endregion
+export { AsyncFactoryError, CrossRuntimeDependencyError, CrossScopeResolutionError, DependencyCycleError, DisposerContextError, DuplicateProviderError, FactoryError, FactoryScopeOperationError, InstallationConflictError, LeakedChildScopeError, MissingProviderError, OwnedProvisionReuseError, RippleError, ScopeClosedError, asValue, createOverrideRunner, createRuntime, createScope, createValueOverride, defineDependency, dispose, install, provide, provideFactory, resolve, withOverrides };