better-effect 0.7.0 → 0.9.1

package/dist/index.mjs

@@ -1,226 +1,9 @@
-import { a as LayerRegistrationError, c as ServiceAcquisitionError, i as LayerGeneratorYieldError, l as ServiceNotFoundError, n as DuplicateServiceError, o as ServiceTagCollisionError, r as LayerDisposeError, s as CircularDependencyError, u as ServiceRuntimeNotConfiguredError } from "./internal-identity-Cm4-KIUj.mjs";
-import { a as runRuntimeContext, c as RuntimeContextNotConfiguredError, i as makeRuntimeContext, n as currentRuntimeContext, o as setDefaultRuntimeContextStorage, r as getRuntimeContext, t as activeRuntimeContextStorage } from "./context-B4yO5LaH.mjs";
-import { nodeRuntimeContextStorage } from "./runtime/node.mjs";
-import { t as MapLayerBackend } from "./map-layer-backend-BodcEeNA.mjs";
+import { a as ServiceTagCollisionError, c as ServiceNotFoundError, i as LayerRegistrationError, l as ServiceRuntimeNotConfiguredError, n as LayerDisposeError, o as CircularDependencyError, r as LayerGeneratorYieldError, s as ServiceAcquisitionError, t as DuplicateServiceError } from "./errors-Dnjhzbt0.mjs";
+import { a as runRuntimeContext, c as RuntimeContextNotConfiguredError, i as makeRuntimeContext, n as currentRuntimeContext, r as getRuntimeContext, t as activeRuntimeContextStorage } from "./context-B4yO5LaH.mjs";
+import { a as ServiceRuntime, i as Service, n as linkAbortSignals, o as defaultRuntimeContextStorage, r as Layer, t as CurrentAbortSignal } from "./signal-BgUtPQj5.mjs";
+import { t as MapLayerBackend } from "./map-layer-backend-gal-mcRv.mjs";
 import { t as isPromiseLike } from "./runtime-CDcCF5cb.mjs";
 import { Result, TaggedError } from "better-result";
-//#region src/runtime/default.ts
-/** The Node/Bun storage used by the main Runtime entrypoint. */
-const defaultRuntimeContextStorage = nodeRuntimeContextStorage;
-setDefaultRuntimeContextStorage(defaultRuntimeContextStorage);
-//#endregion
-//#region src/service/runtime.ts
-/** Provides the resolver context used by Service tokens during execution. */
-var ServiceRuntime = class ServiceRuntime {
-	/**
-	* Run a callback with a resolver available to `yield* Service` expressions.
-	*
-	* The context is scoped to the callback and is restored afterward.
-	*
-	* @example
-	* ```ts
-	* const value = ServiceRuntime.run(resolver, () => {
-	*   return ServiceRuntime.resolve(Database)
-	* })
-	* ```
-	*/
-	static run(resolver, program, storage = defaultRuntimeContextStorage) {
-		const current = getRuntimeContext(storage);
-		const context = makeRuntimeContext(resolver, current?.scope, current?.resolver === resolver ? current.resolutionPath : [], current?.signal);
-		return runRuntimeContext(storage, context, program);
-	}
-	/** Return the resolver active in the current execution context. */
-	static current() {
-		let context;
-		try {
-			context = currentRuntimeContext();
-		} catch {
-			throw new ServiceRuntimeNotConfiguredError();
-		}
-		if (!context.resolver) throw new ServiceRuntimeNotConfiguredError();
-		return context.resolver;
-	}
-	/** Resolve a Service token using the active resolver. */
-	static async resolve(token) {
-		return await ServiceRuntime.current().resolve(token);
-	}
-};
-//#endregion
-//#region src/service/service.ts
-/**
-* Declare a class-backed Service with a stable string-literal identity.
-*
-* The returned class is simultaneously the implementation type, the runtime
-* dependency token, and the value yielded by `yield*` in an Effect generator.
-* The explicit self type preserves exact instance inference, while the second
-* call captures the tag as a literal for Layer composition and diagnostics.
-*
-* @example
-* ```ts
-* class Database extends Service<Database>()('Database') {
-*   query(): string {
-*     return 'ok'
-*   }
-* }
-*
-* const database = yield* Database
-* database.query()
-* ```
-*
-* @typeParam Self The instance type implemented by the declared Service.
-*/
-function Service() {
-	return function(tag) {
-		if (tag.length === 0) throw new TypeError("Service tags must not be empty");
-		class BaseService {
-			/** The stable logical identity used by Layers and resolver backends. */
-			static serviceTag = tag;
-			/**
-			* Type-check a structural implementation of this Service.
-			*
-			* This is an identity helper. It returns the supplied value unchanged
-			* and does not invoke a constructor or modify its prototype.
-			*
-			* @example
-			* ```ts
-			* class Database extends Service<Database>()('Database') {
-			*   query(sql: string): string {
-			*     return sql
-			*   }
-			* }
-			*
-			* const database = Database.of({
-			*   query: (sql) => `Result: ${sql}`
-			* })
-			*
-			* database.query('SELECT 1')
-			* // 'Result: SELECT 1'
-			* // database is the original object, not an instance of Database
-			* ```
-			*/
-			static of(implementation) {
-				return implementation;
-			}
-			/** Resolve this Service from the resolver active in the current runtime. */
-			static async *[Symbol.asyncIterator]() {
-				return await ServiceRuntime.resolve(this);
-			}
-		}
-		return BaseService;
-	};
-}
-//#endregion
-//#region src/layer/internal.ts
-const runLayerGenerator = async (service, factory) => {
-	const iterator = factory();
-	const state = await iterator.next();
-	if (!state.done) try {
-		await iterator.return(void 0);
-	} finally {
-		throw new LayerGeneratorYieldError(service);
-	}
-	return state.value;
-};
-//#endregion
-//#region src/layer/layer.ts
-/**
-* Declarative collection of Service providers.
-*
-* A Layer describes how to acquire implementations; it does not execute
-* providers until a `Runtime` is created. Use `merge` to compose distinct
-* providers and `override` when replacing an existing provider intentionally.
-*
-* @example
-* ```ts
-* const AppLive = Layer.merge(
-*   Layer.succeed(Database, database),
-*   Layer.make(UserRepository)
-* )
-*
-* const runtime = await Runtime.make(AppLive, backend)
-* ```
-*/
-var Layer = class Layer {
-	/** The provider registrations retained by this Layer. */
-	providers;
-	constructor(providers) {
-		this.providers = Object.freeze([...providers]);
-	}
-	static make(service, acquire) {
-		const defaultAcquire = () => {
-			return new service();
-		};
-		const normalizedAcquire = normalizeAcquire(acquire ?? defaultAcquire);
-		return new Layer([{
-			service,
-			acquire: normalizedAcquire
-		}]);
-	}
-	/** Create a Layer from an already-constructed Service instance. */
-	static succeed(service, instance) {
-		const normalizedAcquire = normalizeAcquire(() => instance);
-		return new Layer([{
-			service,
-			acquire: normalizedAcquire
-		}]);
-	}
-	/** Define a provider with Runtime-root cleanup. */
-	static scoped(service, acquire, release) {
-		return new Layer([{
-			service,
-			acquire: normalizeAcquire(acquire),
-			release: (instance, outcome) => {
-				return release(instance, outcome);
-			}
-		}]);
-	}
-	/** Define a provider whose acquisition can yield contextual Services. */
-	static scopedGen(service, factory, release) {
-		return new Layer([{
-			service,
-			acquire: () => runLayerGenerator(service, factory),
-			release: (instance, outcome) => {
-				return release(instance, outcome);
-			}
-		}]);
-	}
-	/** Define a provider whose acquisition can yield contextual Services. */
-	static gen(service, factory) {
-		return new Layer([{
-			service,
-			acquire: () => runLayerGenerator(service, factory)
-		}]);
-	}
-	/** Compose Layers without replacing providers. */
-	static merge(...layers) {
-		const providers = /* @__PURE__ */ new Map();
-		for (const layer of layers) for (const provider of layer.providers) {
-			const service = provider.service;
-			const existing = providers.get(service.serviceTag);
-			if (existing) {
-				if (existing.service !== service) throw new ServiceTagCollisionError(existing.service, service);
-				throw new DuplicateServiceError(service);
-			}
-			providers.set(service.serviceTag, provider);
-		}
-		return new Layer([...providers.values()]);
-	}
-	/** Mark a Layer composition root as complete without changing its runtime value. */
-	static complete(layer) {
-		return layer;
-	}
-	/** Replace providers in a base Layer, using tag identity and compatible contracts. */
-	static override(base, ...overrides) {
-		const providers = /* @__PURE__ */ new Map();
-		for (const provider of base.providers) providers.set(provider.service.serviceTag, provider);
-		for (const layer of overrides) for (const provider of layer.providers) providers.set(provider.service.serviceTag, provider);
-		return new Layer([...providers.values()]);
-	}
-};
-const normalizeAcquire = (acquire) => () => {
-	return acquire();
-};
-//#endregion
 //#region src/scope/errors.ts
 /** Thrown when Scope context is accessed outside an active Scope execution. */
 var ScopeRuntimeNotConfiguredError = class extends Error {
@@ -473,6 +256,9 @@ const Scope = {
 };
 //#endregion
 //#region src/effect/combinators.ts
+const asResult = (value) => {
+	return value;
+};
 const mapResult = (result, fn) => {
 	return Result.map(result, fn);
 };
@@ -537,6 +323,83 @@ function andThenAsync(first, second) {
 	});
 	return andThenAsyncResult(first, next);
 }
+const tapResult = (result, fn) => Result.tap(result, fn);
+const tapErrorResult = (result, fn) => Result.tapError(result, fn);
+const tapBothResult = (result, handlers) => Result.tapBoth(result, handlers);
+const recoverResult = (result, fn) => Result.tryRecover(result, fn);
+const recoverAsyncResult = (result, fn) => Result.tryRecoverAsync(result, (error) => Promise.resolve(fn(error)));
+const flattenResult = (result) => Result.flatten(result);
+const matchResult = (result, handlers) => Result.match(result, handlers);
+const allResult = (results) => Result.all(results);
+function tap(first, second) {
+	if (first instanceof Function && second === void 0) {
+		const callback = first;
+		return (effect) => tap(effect, callback);
+	}
+	if (second === void 0) throw new TypeError("Effect.tap requires a callback");
+	const fn = second;
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => tapResult(asResult(result), fn));
+	return tapResult(asResult(first), fn);
+}
+function tapError(first, second) {
+	if (first instanceof Function && second === void 0) {
+		const callback = first;
+		return (effect) => tapError(effect, callback);
+	}
+	if (second === void 0) throw new TypeError("Effect.tapError requires a callback");
+	const fn = second;
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => tapErrorResult(asResult(result), fn));
+	return tapErrorResult(asResult(first), fn);
+}
+function tapBoth(first, second) {
+	if (second === void 0) return (effect) => tapBoth(effect, first);
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => tapBothResult(result, second));
+	return tapBothResult(asResult(first), second);
+}
+function recover(first, second) {
+	if (first instanceof Function && second === void 0) {
+		const callback = first;
+		return (effect) => recover(effect, callback);
+	}
+	if (second === void 0) throw new TypeError("Effect.recover requires a callback");
+	const fn = second;
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => recoverResult(asResult(result), fn));
+	return recoverResult(asResult(first), fn);
+}
+function recoverAsync(first, second) {
+	if (first instanceof Function && second === void 0) {
+		const callback = first;
+		return (effect) => recoverAsync(effect, callback);
+	}
+	if (second === void 0) throw new TypeError("Effect.recoverAsync requires a callback");
+	const fn = second;
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => recoverAsyncResult(asResult(result), fn));
+	return recoverAsyncResult(asResult(first), fn);
+}
+/** Remove one nested Result/Effect layer. */
+function flatten(effect) {
+	return flattenResult(asResult(effect));
+}
+function as(first, second) {
+	if (arguments.length < 2) return (effect) => as(effect, first);
+	return mapResult(asResult(first), () => second);
+}
+/** Replace a successful value with void. */
+function asVoid(effect) {
+	return mapResult(asResult(effect), () => void 0);
+}
+function match(first, second) {
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => match(asResult(result), second));
+	return matchResult(asResult(first), second);
+}
+/** Collect already-created Effects in input order. */
+function all(results) {
+	return allResult(results);
+}
+/** Combine two already-created Effects in input order. */
+function zip(left, right) {
+	return Result.all([left, right]);
+}
 //#endregion
 //#region src/effect/effect.ts
 const runResultGenerator = Result.gen;
@@ -547,6 +410,40 @@ function fn(body) {
 	const program = () => runResultGenerator(body);
 	return program;
 }
+const validateProgramConcurrency = (concurrency) => {
+	if (concurrency !== void 0 && (!Number.isFinite(concurrency) || !Number.isInteger(concurrency) || concurrency <= 0)) throw new RangeError("Program.all concurrency must be a positive integer");
+};
+/** Build a lazy Program collection with optional bounded concurrency. */
+function programAll(programs, options = {}) {
+	validateProgramConcurrency(options.concurrency);
+	const concurrency = options.concurrency;
+	const program = async () => {
+		const results = Array.from({ length: programs.length });
+		const failures = Array.from({ length: programs.length }, () => false);
+		const causes = Array.from({ length: programs.length });
+		let nextIndex = 0;
+		const worker = async () => {
+			while (true) {
+				const index = nextIndex++;
+				if (index >= programs.length) return;
+				try {
+					results[index] = await programs[index]();
+				} catch (cause) {
+					failures[index] = true;
+					causes[index] = cause;
+				}
+			}
+		};
+		const workers = Math.min(concurrency ?? programs.length, programs.length);
+		await Promise.all(Array.from({ length: workers }, () => worker()));
+		const failureIndex = failures.findIndex(Boolean);
+		if (failureIndex >= 0) throw causes[failureIndex];
+		return Result.all(results);
+	};
+	return program;
+}
+/** Value-level namespace for lazy Program combinators. */
+const Program = { all: programAll };
 /**
 * Acquire a resource in the current Scope and register its release callback.
 *
@@ -582,12 +479,6 @@ function add(resource) {
 	const scope = Scope.current();
 	return Result.await(Result.tryPromise(() => scope.add(resource)));
 }
-/**
-* Effect namespace containing generator, resource, and Result combinators.
-*
-* Prefer these helpers when a program needs typed Service requirements or
-* Scope-aware acquisition and cleanup.
-*/
 const Effect = {
 	/** Compose a generator-based Effect program. */
 	gen,
@@ -604,7 +495,29 @@ const Effect = {
 	/** Chain a synchronous Effect result. */
 	andThen,
 	/** Chain an asynchronous Effect result. */
-	andThenAsync
+	andThenAsync,
+	/** Observe successful values without changing the Result. */
+	tap,
+	/** Observe error values without changing the Result. */
+	tapError,
+	/** Observe the active Result branch without changing the Result. */
+	tapBoth,
+	/** Recover an error with another Effect. */
+	recover,
+	/** Recover an error asynchronously with another Effect. */
+	recoverAsync,
+	/** Remove one nested Effect layer. */
+	flatten,
+	/** Replace a successful value. */
+	as,
+	/** Replace a successful value with void. */
+	asVoid,
+	/** Match either Result branch. */
+	match,
+	/** Collect Effects in input order. */
+	all,
+	/** Zip two Effects in input order. */
+	zip
 };
 //#endregion
 //#region src/function/pipe.ts
@@ -702,24 +615,62 @@ const classifyRuntimeOutcome = (value) => {
 	return { status: "success" };
 };
 //#endregion
+//#region src/runtime/observer.ts
+const notifyRuntimeObservers = (observers, select, event) => {
+	for (const observer of observers) {
+		const callback = select(observer);
+		if (!callback) continue;
+		try {
+			Promise.resolve(callback(event)).catch(() => {});
+		} catch {}
+	}
+};
+//#endregion
 //#region src/layer/resolution.ts
 const findCycleStart = (path, token) => path.findIndex((current) => current.serviceTag === token.serviceTag);
 const shouldPreserve = (cause) => cause instanceof CircularDependencyError || cause instanceof ServiceAcquisitionError || cause instanceof ServiceNotFoundError || cause instanceof ServiceTagCollisionError;
 /** Wrap a backend with Runtime-local resolution paths and acquisition errors. */
-const createResolutionResolver = (resolver, storage = defaultRuntimeContextStorage) => {
+const createResolutionResolver = (resolver, storage = defaultRuntimeContextStorage, observers = []) => {
 	const wrapped = { async resolve(token) {
 		const context = getRuntimeContext(storage);
-		const path = context?.resolver === wrapped ? context.resolutionPath : [];
+		const path = context?.resolutionPath ?? [];
 		const cycleStart = findCycleStart(path, token);
-		if (cycleStart >= 0) throw new CircularDependencyError([...path.slice(cycleStart), token]);
 		const resolutionPath = [...path, token];
+		const notifyResolve = (outcome) => {
+			notifyRuntimeObservers(observers, (observer) => observer.onServiceResolve, {
+				service: token,
+				resolutionPath,
+				outcome
+			});
+		};
+		if (cycleStart >= 0) {
+			const error = new CircularDependencyError([...path.slice(cycleStart), token]);
+			notifyResolve({
+				status: "failure",
+				cause: error
+			});
+			throw error;
+		}
 		const nextContext = makeRuntimeContext(wrapped, context?.scope, resolutionPath, context?.signal);
 		return await runRuntimeContext(storage, nextContext, async () => {
 			try {
-				return await resolver.resolve(token);
+				const instance = await resolver.resolve(token);
+				notifyResolve({ status: "success" });
+				return instance;
 			} catch (cause) {
-				if (shouldPreserve(cause)) throw cause;
-				throw new ServiceAcquisitionError(token, resolutionPath, cause);
+				if (shouldPreserve(cause)) {
+					notifyResolve({
+						status: "failure",
+						cause
+					});
+					throw cause;
+				}
+				const error = new ServiceAcquisitionError(token, resolutionPath, cause);
+				notifyResolve({
+					status: "failure",
+					cause: error
+				});
+				throw error;
 			}
 		});
 	} };
@@ -738,19 +689,83 @@ const normalizeDisposeCauses = (cause) => {
 	if (cause instanceof AggregateError) return [...cause.errors];
 	return [cause];
 };
+const isScopeOutcome = (input) => input !== void 0 && "status" in input;
+const validateDisposeOptions = (options) => {
+	const { gracePeriod } = options;
+	if (gracePeriod !== void 0 && (!Number.isFinite(gracePeriod) || gracePeriod < 0)) throw new RangeError("Runtime dispose gracePeriod must be a finite non-negative number");
+};
 const notifyShutdownFailure = async (observer, diagnostic) => {
 	if (!observer) return;
 	try {
 		await observer(diagnostic);
 	} catch {}
 };
-const bindProviderToScope = (provider, rootScope, contextStorage) => ({
+const bindProviderToScope = (provider, scope, contextStorage, resolver, observers) => ({
 	service: provider.service,
-	acquire: () => ScopeRuntime.run(rootScope, async () => {
-		if (!provider.release) return await provider.acquire();
-		return await rootScope.acquire(() => provider.acquire(), (resource, outcome) => provider.release(resource, outcome));
-	}, contextStorage)
+	acquire: () => {
+		const current = getRuntimeContext(contextStorage);
+		const context = makeRuntimeContext(resolver, scope, current?.resolutionPath ?? [], current?.signal);
+		return runRuntimeContext(contextStorage, context, () => ScopeRuntime.run(scope, async () => {
+			const resolutionPath = current?.resolutionPath ?? [provider.service];
+			try {
+				const instance = provider.release ? await scope.acquire(() => provider.acquire(), async (resource, outcome) => {
+					try {
+						await provider.release(resource, outcome);
+						notifyRuntimeObservers(observers, (observer) => observer.onResourceRelease, {
+							service: provider.service,
+							outcome
+						});
+					} catch (cause) {
+						notifyRuntimeObservers(observers, (observer) => observer.onResourceRelease, {
+							service: provider.service,
+							outcome,
+							error: cause
+						});
+						throw cause;
+					}
+				}) : await provider.acquire();
+				notifyRuntimeObservers(observers, (observer) => observer.onServiceAcquire, {
+					service: provider.service,
+					resolutionPath,
+					outcome: SCOPE_SUCCESS
+				});
+				return instance;
+			} catch (cause) {
+				notifyRuntimeObservers(observers, (observer) => observer.onServiceAcquire, {
+					service: provider.service,
+					resolutionPath,
+					outcome: {
+						status: "failure",
+						cause
+					}
+				});
+				throw cause;
+			}
+		}, contextStorage));
+	}
 });
+/** Resolve request-local providers first, then fall back to the Runtime root. */
+var ExecutionLayerBackend = class {
+	local;
+	root;
+	localTags = /* @__PURE__ */ new Set();
+	constructor(local, root) {
+		this.local = local;
+		this.root = root;
+	}
+	register(registration) {
+		this.localTags.add(registration.service.serviceTag);
+		this.local.register(registration);
+	}
+	async resolve(token) {
+		if (this.localTags.has(token.serviceTag)) return await this.local.resolve(token);
+		return await this.root.resolve(token);
+	}
+	async disposeAll() {
+		await this.local.disposeAll();
+		this.localTags.clear();
+	}
+};
 var RuntimeHandleImpl = class {
 	backend;
 	resolver;
@@ -758,34 +773,79 @@ var RuntimeHandleImpl = class {
 	onCleanupFailure;
 	contextStorage;
 	signal;
+	observers;
+	services;
 	disposePromise;
+	warmupPromise;
 	executions = /* @__PURE__ */ new Set();
+	shutdownController = new AbortController();
 	state = "active";
-	constructor(backend, resolver, rootScope, onCleanupFailure, contextStorage, signal) {
+	constructor(backend, resolver, rootScope, onCleanupFailure, contextStorage, signal, observers, services) {
 		this.backend = backend;
 		this.resolver = resolver;
 		this.rootScope = rootScope;
 		this.onCleanupFailure = onCleanupFailure;
 		this.contextStorage = contextStorage;
 		this.signal = signal;
+		this.observers = observers;
+		this.services = services;
 	}
-	run(program) {
+	run(program, options) {
 		this.assertActive();
 		const executionScope = this.rootScope.fork();
+		const signalLink = linkAbortSignals(this.signal, options?.signal, this.shutdownController.signal);
+		return this.startExecution(signalLink, () => this.runExecution(executionScope, program, this.resolver, signalLink.signal));
+	}
+	runWith(layer, program, options) {
+		this.assertActive();
+		const executionScope = this.rootScope.fork();
+		const localBackend = new MapLayerBackend();
+		const backend = new ExecutionLayerBackend(localBackend, this.backend);
+		const resolver = createResolutionResolver(backend, this.contextStorage, this.observers);
+		const signalLink = linkAbortSignals(this.signal, options?.signal, this.shutdownController.signal);
+		return this.startExecution(signalLink, async () => {
+			try {
+				return await this.runExecution(executionScope, async () => {
+					for (const provider of layer.providers) backend.register(bindProviderToScope(provider, executionScope, this.contextStorage, resolver, this.observers));
+					return await program();
+				}, resolver, signalLink.signal);
+			} finally {
+				await localBackend.disposeAll();
+			}
+		});
+	}
+	warmup() {
+		this.assertActive();
+		if (this.warmupPromise) return this.warmupPromise;
+		const warmup = runRuntimeContext(this.contextStorage, makeRuntimeContext(this.resolver, this.rootScope, [], this.signal), async () => {
+			for (const service of this.services) await this.resolver.resolve(service);
+		});
+		this.warmupPromise = warmup;
+		warmup.then(() => {
+			if (this.warmupPromise === warmup) this.warmupPromise = void 0;
+		}, () => {
+			if (this.warmupPromise === warmup) this.warmupPromise = void 0;
+		});
+		return warmup;
+	}
+	startExecution(signalLink, run) {
 		let resolveExecution;
 		let rejectExecution;
 		const execution = new Promise((resolve, reject) => {
 			resolveExecution = resolve;
 			rejectExecution = reject;
 		});
-		this.executions.add(execution);
+		const activeExecution = { promise: execution };
+		this.executions.add(activeExecution);
 		execution.then(() => {
-			this.executions.delete(execution);
+			this.executions.delete(activeExecution);
+			signalLink.dispose();
 		}, () => {
-			this.executions.delete(execution);
+			this.executions.delete(activeExecution);
+			signalLink.dispose();
 		});
 		try {
-			this.runExecution(executionScope, program).then((value) => {
+			run().then((value) => {
 				resolveExecution(value);
 			}, (cause) => {
 				rejectExecution(cause);
@@ -795,29 +855,54 @@ var RuntimeHandleImpl = class {
 		}
 		return execution;
 	}
-	runExecution(executionScope, program) {
+	runExecution(executionScope, program, resolver = this.resolver, signal = this.shutdownController.signal) {
 		const options = this.onCleanupFailure ? {
 			classify: classifyRuntimeOutcome,
 			onCleanupFailure: this.onCleanupFailure
 		} : { classify: classifyRuntimeOutcome };
+		notifyRuntimeObservers(this.observers, (observer) => observer.onExecutionStart, { scope: executionScope });
 		return runScoped(executionScope, program, {
 			...options,
 			contextStorage: this.contextStorage,
-			context: makeRuntimeContext(this.resolver, executionScope, [], this.signal)
+			context: makeRuntimeContext(resolver, executionScope, [], signal)
+		}).then((value) => {
+			notifyRuntimeObservers(this.observers, (observer) => observer.onExecutionEnd, {
+				scope: executionScope,
+				outcome: classifyRuntimeOutcome(value)
+			});
+			return value;
+		}, (cause) => {
+			notifyRuntimeObservers(this.observers, (observer) => observer.onExecutionEnd, {
+				scope: executionScope,
+				outcome: {
+					status: "failure",
+					cause
+				}
+			});
+			throw cause;
 		});
 	}
-	dispose(outcome = SCOPE_SUCCESS) {
+	dispose(input) {
 		if (this.disposePromise) return this.disposePromise;
+		const outcome = isScopeOutcome(input) || input === void 0 ? input ?? SCOPE_SUCCESS : SCOPE_SUCCESS;
+		const options = isScopeOutcome(input) || input === void 0 ? {} : input;
+		validateDisposeOptions(options);
 		this.state = "disposing";
 		const executions = [...this.executions];
-		this.disposePromise = this.performDispose(executions, outcome);
+		this.disposePromise = this.performDispose(executions, outcome, options);
 		return this.disposePromise;
 	}
-	async performDispose(executions, outcome) {
+	async performDispose(executions, outcome, options) {
 		const failures = [];
-		await Promise.allSettled(executions);
+		await Promise.allSettled(this.warmupPromise ? [this.warmupPromise] : []);
+		await this.waitForExecutions(executions, options);
 		try {
-			await runRuntimeContext(this.contextStorage, makeRuntimeContext(this.resolver, this.rootScope, [], this.signal), () => this.rootScope.close(outcome));
+			const signalLink = linkAbortSignals(this.signal, this.shutdownController.signal);
+			try {
+				await runRuntimeContext(this.contextStorage, makeRuntimeContext(this.resolver, this.rootScope, [], signalLink.signal), () => this.rootScope.close(outcome));
+			} finally {
+				signalLink.dispose();
+			}
 		} catch (cause) {
 			failures.push(cause);
 		}
@@ -836,6 +921,21 @@ var RuntimeHandleImpl = class {
 			throw error;
 		}
 	}
+	async waitForExecutions(executions, options) {
+		const settled = Promise.allSettled(executions.map((execution) => execution.promise));
+		if (options.abortAfterGracePeriod !== true || executions.length === 0) {
+			await settled;
+			return;
+		}
+		const gracePeriod = options.gracePeriod ?? 0;
+		let timer;
+		const timedOut = await Promise.race([settled.then(() => false), new Promise((resolve) => {
+			timer = setTimeout(() => resolve(true), gracePeriod);
+		})]);
+		if (timer !== void 0) clearTimeout(timer);
+		if (timedOut && !this.shutdownController.signal.aborted) this.shutdownController.abort(/* @__PURE__ */ new Error("Runtime shutdown grace period exceeded"));
+		await settled;
+	}
 	assertActive() {
 		if (this.state !== "active") throw new RuntimeHandleDisposedError();
 	}
@@ -844,13 +944,14 @@ var RuntimeHandleImpl = class {
 const createRuntimeHandle = async (layer, backend, options = {}) => {
 	const rootScope = Scope.make();
 	const contextStorage = options.contextStorage ?? defaultRuntimeContextStorage;
-	const resolver = createResolutionResolver(backend, contextStorage);
+	const observers = options.observers ?? [];
+	const resolver = createResolutionResolver(backend, contextStorage, observers);
 	ScopeRuntime.bind(rootScope, contextStorage);
 	let current;
 	try {
 		for (const provider of layer.providers) {
 			current = provider;
-			await backend.register(bindProviderToScope(provider, rootScope, contextStorage));
+			await backend.register(bindProviderToScope(provider, rootScope, contextStorage, resolver, observers));
 		}
 	} catch (registrationCause) {
 		const outcome = {
@@ -878,7 +979,7 @@ const createRuntimeHandle = async (layer, backend, options = {}) => {
 		const cleanupCause = cleanupCauses.length === 1 ? cleanupCauses[0] : cleanupCauses.length > 1 ? new LayerDisposeError(cleanupCauses.flatMap(normalizeDisposeCauses)) : void 0;
 		throw new LayerRegistrationError(current?.service, registrationCause, cleanupCause);
 	}
-	return new RuntimeHandleImpl(backend, resolver, rootScope, options.onCleanupFailure, contextStorage, options.signal);
+	return new RuntimeHandleImpl(backend, resolver, rootScope, options.onCleanupFailure, contextStorage, options.signal, observers, layer.providers.map((provider) => provider.service));
 };
 //#endregion
 //#region src/runtime/runtime.ts
@@ -917,7 +1018,9 @@ var Runtime = class Runtime {
 	static async make(layer, backendOrOptions, legacyOptions) {
 		const { backend, options } = resolveRuntimeConfig(backendOrOptions, legacyOptions);
 		const handle = await createRuntimeHandle(layer, backend, options);
-		return new Runtime(handle);
+		const runtime = new Runtime(handle);
+		if (options.warmup) await runtime.warmup();
+		return runtime;
 	}
 	static async run(layer, backendOrProgramOrOptions, programOrOptions, legacyOptions) {
 		let program;
@@ -997,16 +1100,33 @@ var Runtime = class Runtime {
 		if (executionFailed) throw executionFailure;
 		return value;
 	}
+	/** Resolve every Layer provider and dispose the Runtime if warmup fails. */
+	async warmup() {
+		try {
+			await this.handle.warmup();
+		} catch (cause) {
+			try {
+				await this.handle.dispose({
+					status: "failure",
+					cause
+				});
+			} catch {}
+			throw cause;
+		}
+	}
 	/** Run one execution in this Runtime's child Scope. */
-	run(program) {
-		return this.handle.run(program);
+	run(program, options) {
+		return this.handle.run(program, options);
+	}
+	/** Run one execution with a Layer owned by that execution's child Scope. */
+	runWith(layer, program, options) {
+		return this.handle.runWith(layer, program, options);
 	}
 	runUnchecked(program) {
 		return this.handle.run(program);
 	}
-	/** Stop new executions and release the Runtime's Layer resources. */
-	dispose() {
-		return this.handle.dispose();
+	dispose(optionsOrOutcome) {
+		return this.handle.dispose(optionsOrOutcome);
 	}
 	/** Release Runtime-owned resources through JavaScript's async disposal protocol. */
 	async [Symbol.asyncDispose]() {
@@ -1017,6 +1137,6 @@ var Runtime = class Runtime {
 	}
 };
 //#endregion
-export { CircularDependencyError, DuplicateServiceError, Effect, Layer, LayerDisposeError, LayerGeneratorYieldError, LayerRegistrationError, MapLayerBackend, Resource, ResourceNotDisposableError, ResourceReleaseFailure, Runtime, RuntimeContextNotConfiguredError, Scope, ScopeCloseError, ScopeClosedError, ScopeRuntimeNotConfiguredError, Service, ServiceAcquisitionError, ServiceNotFoundError, ServiceRuntime, ServiceRuntimeNotConfiguredError, ServiceTagCollisionError, pipe };
+export { CircularDependencyError, CurrentAbortSignal, DuplicateServiceError, Effect, Layer, LayerDisposeError, LayerGeneratorYieldError, LayerRegistrationError, MapLayerBackend, Program, Resource, ResourceNotDisposableError, ResourceReleaseFailure, Runtime, RuntimeContextNotConfiguredError, Scope, ScopeCloseError, ScopeClosedError, ScopeRuntimeNotConfiguredError, Service, ServiceAcquisitionError, ServiceNotFoundError, ServiceRuntime, ServiceRuntimeNotConfiguredError, ServiceTagCollisionError, pipe };
 
 //# sourceMappingURL=index.mjs.map