better-effect 0.11.0 → 0.13.0

package/dist/{runtime-DnMn0X0X.mjs → runtime-C_55ofnL.mjs}

@@ -1,8 +1,9 @@
-import { a as ServiceTagCollisionError, c as ServiceNotFoundError, i as LayerRegistrationError, n as LayerDisposeError, o as CircularDependencyError, s as ServiceAcquisitionError, t as DuplicateServiceError } from "./errors-Dnjhzbt0.mjs";
-import { i as getRuntimeContext, l as makeRuntimeContext, u as runRuntimeContext } from "./context-BUEf1qjL.mjs";
-import { f as defaultRuntimeContextStorage, n as linkAbortSignals } from "./signal-B97cs85Z.mjs";
-import { n as runScoped, r as ScopeRuntime, t as Scope } from "./scope-GGnmTQck.mjs";
-import { t as assertServiceCompatibility } from "./internal-identity-DmUpBeeL.mjs";
+import { c as CircularDependencyError, f as captureServiceTag, i as LayerDisposeError, l as ServiceAcquisitionError, n as normalizeLayerRegistration, o as LayerRegistrationError, r as DuplicateServiceError, s as ServiceTagCollisionError, t as captureLayerRegistrationTag, u as ServiceNotFoundError } from "./registration-drnZk0SY.mjs";
+import { i as getRuntimeContext, l as makeRuntimeContext, u as runRuntimeContext } from "./context-BphfFUMO.mjs";
+import { s as defaultRuntimeContextStorage } from "./disposable-CP-Q2H3l.mjs";
+import { a as runScoped, i as Scope, o as ScopeRuntime, t as getProgramName } from "./program-metadata-BxjGkT17.mjs";
+import { t as assertServiceCompatibility } from "./internal-identity-CbXoZIfw.mjs";
+import { n as linkAbortSignals } from "./signal-nfgFyNCk.mjs";
 import { Err } from "better-result";
 //#region src/layer/map-layer-backend.ts
 /** Native map-backed Layer backend used by Runtime when no adapter is supplied. */
@@ -12,17 +13,18 @@ var MapLayerBackend = class {
 	pending = /* @__PURE__ */ new Map();
 	/** Register a provider, rejecting duplicate or colliding Service tags. */
 	register(registration) {
-		const tag = registration.service.serviceTag;
+		const normalized = normalizeLayerRegistration(registration);
+		const tag = captureLayerRegistrationTag(normalized);
 		const existing = this.providers.get(tag);
 		if (existing) {
-			if (existing.service !== registration.service) throw new ServiceTagCollisionError(existing.service, registration.service);
-			throw new DuplicateServiceError(registration.service);
+			if (existing.service !== normalized.service) throw new ServiceTagCollisionError(existing.service, normalized.service);
+			throw new DuplicateServiceError(normalized.service);
 		}
-		this.providers.set(tag, registration);
+		this.providers.set(tag, normalized);
 	}
 	/** Resolve and cache a provider instance by Service tag. */
 	async resolve(token) {
-		const tag = token.serviceTag;
+		const tag = captureServiceTag(token);
 		const provider = this.providers.get(tag);
 		if (!provider) throw new ServiceNotFoundError(token);
 		const validate = (instance) => {
@@ -97,21 +99,24 @@ const notifyRuntimeObservers = (observers, select, event) => {
 };
 //#endregion
 //#region src/layer/resolution.ts
-const findCycleStart = (path, token) => path.findIndex((current) => current.serviceTag === token.serviceTag);
+const findCycleStart = (path, tag) => path.findIndex((current) => captureServiceTag(current) === tag);
 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, observers = []) => {
 	const wrapped = { async resolve(token) {
+		const tag = captureServiceTag(token);
 		const context = getRuntimeContext(storage);
 		const path = context?.resolutionPath ?? [];
-		const cycleStart = findCycleStart(path, token);
+		const cycleStart = findCycleStart(path, tag);
 		const resolutionPath = [...path, token];
 		const notifyResolve = (outcome) => {
-			notifyRuntimeObservers(observers, (observer) => observer.onServiceResolve, {
+			const event = {
 				service: token,
 				resolutionPath,
 				outcome
-			});
+			};
+			if (context?.executionId !== void 0) Object.assign(event, { executionId: context.executionId });
+			notifyRuntimeObservers(observers, (observer) => observer.onServiceResolve, event);
 		};
 		if (cycleStart >= 0) {
 			const error = new CircularDependencyError([...path.slice(cycleStart), token]);
@@ -147,6 +152,34 @@ const createResolutionResolver = (resolver, storage = defaultRuntimeContextStora
 	return wrapped;
 };
 //#endregion
+//#region src/runtime/execution.ts
+const hostMonotonicNow = () => {
+	if (typeof globalThis.performance?.now === "function") {
+		const value = globalThis.performance.now();
+		if (Number.isFinite(value)) return value;
+	}
+	const wallClock = Date.now();
+	return Number.isFinite(wallClock) ? wallClock : 0;
+};
+const makeMonotonicClock = () => {
+	let previous = 0;
+	return () => {
+		previous = Math.max(previous, hostMonotonicNow());
+		return previous;
+	};
+};
+let fallbackExecutionSequence = 0;
+const makeExecutionIdGenerator = () => () => {
+	if (typeof globalThis.crypto?.randomUUID === "function") return globalThis.crypto.randomUUID();
+	fallbackExecutionSequence += 1;
+	return `execution-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}-${fallbackExecutionSequence.toString(36)}`;
+};
+/** Create isolated execution capabilities for one Runtime handle. */
+const makeRuntimeExecutionDependencies = (overrides = {}) => ({
+	createExecutionId: overrides.createExecutionId ?? makeExecutionIdGenerator(),
+	now: overrides.now ?? makeMonotonicClock()
+});
+//#endregion
 //#region src/layer/runtime.ts
 const SCOPE_SUCCESS = Object.freeze({ status: "success" });
 var RuntimeHandleDisposedError = class extends Error {
@@ -164,52 +197,90 @@ 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 copyExecutionAttributes = (attributes) => {
+	if (attributes === void 0) return;
+	if (typeof attributes !== "object" || attributes === null) throw new TypeError("Runtime execution attributes must be an object");
+	return Object.freeze({ ...attributes });
+};
+const prepareExecution = (program, options, dependencies, runtimeSignal, shutdownSignal) => ({
+	metadata: makeExecutionMetadata(program, options?.attributes, dependencies),
+	signalLink: linkAbortSignals(runtimeSignal, options?.signal, shutdownSignal)
+});
+const makeExecutionMetadata = (program, attributes, dependencies) => {
+	const name = getProgramName(program);
+	const copiedAttributes = copyExecutionAttributes(attributes);
+	const metadata = {
+		executionId: dependencies.createExecutionId(),
+		startedAt: dependencies.now()
+	};
+	if (name !== void 0) metadata.name = name;
+	if (copiedAttributes !== void 0) metadata.attributes = copiedAttributes;
+	return Object.freeze(metadata);
+};
+const executionDuration = (metadata, dependencies) => {
+	try {
+		const elapsed = dependencies.now() - metadata.startedAt;
+		return Number.isFinite(elapsed) ? Math.max(0, elapsed) : 0;
+	} catch {
+		return 0;
+	}
+};
 const notifyShutdownFailure = async (observer, diagnostic) => {
 	if (!observer) return;
 	try {
 		await observer(diagnostic);
 	} catch {}
 };
-const releaseLayerResource = async (service, release, outcome, observers) => {
+const releaseLayerResource = async (service, release, outcome, observers, executionId) => {
 	try {
 		await release(outcome);
-		notifyRuntimeObservers(observers, (observer) => observer.onResourceRelease, {
+		const event = {
 			service,
 			outcome
-		});
+		};
+		if (executionId !== void 0) Object.assign(event, { executionId });
+		notifyRuntimeObservers(observers, (observer) => observer.onResourceRelease, event);
 	} catch (cause) {
-		notifyRuntimeObservers(observers, (observer) => observer.onResourceRelease, {
+		const event = {
 			service,
 			outcome,
 			error: cause
-		});
+		};
+		if (executionId !== void 0) Object.assign(event, { executionId });
+		notifyRuntimeObservers(observers, (observer) => observer.onResourceRelease, event);
 		throw cause;
 	}
 };
-const bindProviderToScope = (provider, scope, contextStorage, resolver, observers) => ({
+const bindProviderToScope = (provider, scope, contextStorage, resolver, observers, ownerExecutionId) => ({
 	service: provider.service,
+	serviceTag: provider.serviceTag,
 	acquire: () => {
 		const current = getRuntimeContext(contextStorage);
+		const executionId = current?.executionId ?? ownerExecutionId;
 		const context = makeRuntimeContext(resolver, scope, current?.resolutionPath ?? [], current?.signal, current);
 		return runRuntimeContext(contextStorage, context, () => ScopeRuntime.run(scope, async () => {
 			const resolutionPath = current?.resolutionPath ?? [provider.service];
 			try {
-				const instance = provider.acquireWithRelease ? (await scope.acquire(provider.acquireWithRelease, (acquired, outcome) => releaseLayerResource(provider.service, acquired.release, outcome, observers))).instance : provider.release ? await scope.acquire(() => provider.acquire(), (resource, outcome) => releaseLayerResource(provider.service, (releaseOutcome) => provider.release(resource, releaseOutcome), outcome, observers)) : await provider.acquire();
-				notifyRuntimeObservers(observers, (observer) => observer.onServiceAcquire, {
+				const instance = provider.acquireWithRelease ? (await scope.acquire(provider.acquireWithRelease, (acquired, outcome) => releaseLayerResource(provider.service, acquired.release, outcome, observers, ownerExecutionId))).instance : provider.release ? await scope.acquire(() => provider.acquire(), (resource, outcome) => releaseLayerResource(provider.service, (releaseOutcome) => provider.release(resource, releaseOutcome), outcome, observers, ownerExecutionId)) : await provider.acquire();
+				const event = {
 					service: provider.service,
 					resolutionPath,
 					outcome: SCOPE_SUCCESS
-				});
+				};
+				if (executionId !== void 0) Object.assign(event, { executionId });
+				notifyRuntimeObservers(observers, (observer) => observer.onServiceAcquire, event);
 				return instance;
 			} catch (cause) {
-				notifyRuntimeObservers(observers, (observer) => observer.onServiceAcquire, {
+				const event = {
 					service: provider.service,
 					resolutionPath,
 					outcome: {
 						status: "failure",
 						cause
 					}
-				});
+				};
+				if (executionId !== void 0) Object.assign(event, { executionId });
+				notifyRuntimeObservers(observers, (observer) => observer.onServiceAcquire, event);
 				throw cause;
 			}
 		}, contextStorage));
@@ -225,11 +296,12 @@ var ExecutionLayerBackend = class {
 		this.root = root;
 	}
 	register(registration) {
-		this.localTags.add(registration.service.serviceTag);
+		this.localTags.add(captureLayerRegistrationTag(registration));
 		this.local.register(registration);
 	}
 	async resolve(token) {
-		if (this.localTags.has(token.serviceTag)) return await this.local.resolve(token);
+		const tag = captureServiceTag(token);
+		if (this.localTags.has(tag)) return await this.local.resolve(token);
 		return await this.root.resolve(token);
 	}
 	async disposeAll() {
@@ -246,12 +318,15 @@ var RuntimeHandleImpl = class {
 	signal;
 	observers;
 	services;
+	executionDependencies;
 	disposePromise;
 	warmupPromise;
 	executions = /* @__PURE__ */ new Set();
+	serviceTags;
 	shutdownController = new AbortController();
 	state = "active";
-	constructor(backend, resolver, rootScope, onCleanupFailure, contextStorage, signal, observers, services) {
+	warmupState = "idle";
+	constructor(backend, resolver, rootScope, onCleanupFailure, contextStorage, signal, observers, services, serviceTags, executionDependencies) {
 		this.backend = backend;
 		this.resolver = resolver;
 		this.rootScope = rootScope;
@@ -260,26 +335,80 @@ var RuntimeHandleImpl = class {
 		this.signal = signal;
 		this.observers = observers;
 		this.services = services;
+		this.executionDependencies = executionDependencies;
+		this.serviceTags = Object.freeze([...serviceTags]);
+	}
+	inspect() {
+		const executions = Object.freeze([...this.executions].map(({ metadata }) => {
+			const inspection = {
+				executionId: metadata.executionId,
+				startedAt: metadata.startedAt
+			};
+			if (metadata.name !== void 0) inspection.name = metadata.name;
+			return Object.freeze(inspection);
+		}));
+		return Object.freeze({
+			state: this.state,
+			warmup: this.warmupState,
+			activeExecutions: executions.length,
+			executions,
+			services: Object.freeze([...this.serviceTags]),
+			shutdownSignalAborted: this.shutdownController.signal.aborted
+		});
 	}
 	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));
+		let prepared;
+		try {
+			prepared = prepareExecution(program, options, this.executionDependencies, this.signal, this.shutdownController.signal);
+		} catch (cause) {
+			return Promise.reject(cause);
+		}
+		try {
+			this.assertActive();
+		} catch (cause) {
+			prepared.signalLink.dispose();
+			throw cause;
+		}
+		let executionScope;
+		try {
+			executionScope = this.rootScope.fork();
+		} catch (cause) {
+			prepared.signalLink.dispose();
+			throw cause;
+		}
+		return this.startExecution(prepared.signalLink, prepared.metadata, () => this.runExecution(executionScope, program, this.resolver, prepared.signalLink.signal, prepared.metadata));
 	}
 	runWith(layer, program, options) {
 		this.assertActive();
-		const executionScope = this.rootScope.fork();
+		let prepared;
+		try {
+			prepared = prepareExecution(program, options, this.executionDependencies, this.signal, this.shutdownController.signal);
+		} catch (cause) {
+			return Promise.reject(cause);
+		}
+		try {
+			this.assertActive();
+		} catch (cause) {
+			prepared.signalLink.dispose();
+			throw cause;
+		}
 		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 () => {
+		let executionScope;
+		try {
+			executionScope = this.rootScope.fork();
+		} catch (cause) {
+			prepared.signalLink.dispose();
+			throw cause;
+		}
+		return this.startExecution(prepared.signalLink, prepared.metadata, async () => {
 			try {
 				return await this.runExecution(executionScope, async () => {
-					for (const provider of layer.providers) backend.register(bindProviderToScope(provider, executionScope, this.contextStorage, resolver, this.observers));
+					for (const provider of layer.providers) backend.register(bindProviderToScope(provider, executionScope, this.contextStorage, resolver, this.observers, prepared.metadata.executionId));
 					return await program();
-				}, resolver, signalLink.signal);
+				}, resolver, prepared.signalLink.signal, prepared.metadata);
 			} finally {
 				await localBackend.disposeAll();
 			}
@@ -288,25 +417,41 @@ var RuntimeHandleImpl = class {
 	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.warmupState = "running";
+		let warmup;
+		try {
+			warmup = runRuntimeContext(this.contextStorage, makeRuntimeContext(this.resolver, this.rootScope, [], this.signal), async () => {
+				for (const service of this.services) await this.resolver.resolve(service);
+			});
+		} catch (cause) {
+			this.warmupState = "failed";
+			return Promise.reject(cause);
+		}
 		this.warmupPromise = warmup;
 		warmup.then(() => {
-			if (this.warmupPromise === warmup) this.warmupPromise = void 0;
+			if (this.warmupPromise === warmup) {
+				this.warmupState = "completed";
+				this.warmupPromise = void 0;
+			}
 		}, () => {
-			if (this.warmupPromise === warmup) this.warmupPromise = void 0;
+			if (this.warmupPromise === warmup) {
+				this.warmupState = "failed";
+				this.warmupPromise = void 0;
+			}
 		});
 		return warmup;
 	}
-	startExecution(signalLink, run) {
+	startExecution(signalLink, metadata, run) {
 		let resolveExecution;
 		let rejectExecution;
 		const execution = new Promise((resolve, reject) => {
 			resolveExecution = resolve;
 			rejectExecution = reject;
 		});
-		const activeExecution = { promise: execution };
+		const activeExecution = {
+			promise: execution,
+			metadata
+		};
 		this.executions.add(activeExecution);
 		execution.then(() => {
 			this.executions.delete(activeExecution);
@@ -316,7 +461,7 @@ var RuntimeHandleImpl = class {
 			signalLink.dispose();
 		});
 		try {
-			run().then((value) => {
+			run(metadata).then((value) => {
 				resolveExecution(value);
 			}, (cause) => {
 				rejectExecution(cause);
@@ -326,34 +471,60 @@ var RuntimeHandleImpl = class {
 		}
 		return execution;
 	}
-	runExecution(executionScope, program, resolver = this.resolver, signal = this.shutdownController.signal) {
+	runExecution(executionScope, program, resolver = this.resolver, signal = this.shutdownController.signal, metadata) {
 		let outcome;
+		let cleanupFailure;
 		const onOutcome = (determinedOutcome) => {
 			outcome = determinedOutcome;
 		};
-		const runOptions = this.onCleanupFailure ? {
+		const onExecutionCleanupFailure = async (diagnostic) => {
+			cleanupFailure = diagnostic.error;
+			if (this.onCleanupFailure !== void 0) await this.onCleanupFailure(diagnostic);
+		};
+		const runOptions = {
 			classify: classifyRuntimeOutcome,
 			onOutcome,
-			onCleanupFailure: this.onCleanupFailure
-		} : {
-			classify: classifyRuntimeOutcome,
-			onOutcome
+			onCleanupFailure: onExecutionCleanupFailure
 		};
-		notifyRuntimeObservers(this.observers, (observer) => observer.onExecutionStart, { scope: executionScope });
-		return runScoped(executionScope, program, {
-			...runOptions,
-			contextStorage: this.contextStorage,
-			context: makeRuntimeContext(resolver, executionScope, [], signal)
-		}).then((value) => {
-			notifyRuntimeObservers(this.observers, (observer) => observer.onExecutionEnd, {
+		const startEvent = Object.freeze({
+			...metadata,
+			scope: executionScope
+		});
+		notifyRuntimeObservers(this.observers, (observer) => observer.onExecutionStart, startEvent);
+		let ended = false;
+		const notifyEnd = (finalOutcome) => {
+			if (ended) return;
+			ended = true;
+			const endEvent = {
+				...metadata,
 				scope: executionScope,
-				outcome
+				outcome: finalOutcome,
+				durationMs: executionDuration(metadata, this.executionDependencies)
+			};
+			if (cleanupFailure !== void 0) Object.assign(endEvent, { cleanupFailure });
+			notifyRuntimeObservers(this.observers, (observer) => observer.onExecutionEnd, Object.freeze(endEvent));
+		};
+		let execution;
+		try {
+			execution = runScoped(executionScope, program, {
+				...runOptions,
+				contextStorage: this.contextStorage,
+				context: makeRuntimeContext(resolver, executionScope, [], signal, void 0, metadata.executionId)
+			});
+		} catch (cause) {
+			notifyEnd({
+				status: "failure",
+				cause
 			});
+			return Promise.reject(cause);
+		}
+		return execution.then((value) => {
+			notifyEnd(outcome ?? { status: "success" });
 			return value;
 		}, (cause) => {
-			notifyRuntimeObservers(this.observers, (observer) => observer.onExecutionEnd, {
-				scope: executionScope,
-				outcome
+			notifyEnd(outcome ?? {
+				status: "failure",
+				cause
 			});
 			throw cause;
 		});
@@ -417,11 +588,14 @@ var RuntimeHandleImpl = class {
 	}
 };
 /** Build a Runtime handle for a complete Layer and register its providers. */
-const createRuntimeHandle = async (layer, backend, options = {}) => {
+const createRuntimeHandle = async (layer, backend, options = {}, executionOverrides = {}) => {
+	const services = layer.providers.map((provider) => provider.service);
+	const serviceTags = layer.providers.map((provider) => captureLayerRegistrationTag(provider));
 	const rootScope = Scope.make();
 	const contextStorage = options.contextStorage ?? defaultRuntimeContextStorage;
 	const observers = options.observers ?? [];
 	const resolver = createResolutionResolver(backend, contextStorage, observers);
+	const executionDependencies = makeRuntimeExecutionDependencies(executionOverrides);
 	ScopeRuntime.bind(rootScope, contextStorage);
 	let current;
 	try {
@@ -455,7 +629,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, observers, layer.providers.map((provider) => provider.service));
+	return new RuntimeHandleImpl(backend, resolver, rootScope, options.onCleanupFailure, contextStorage, options.signal, observers, services, serviceTags, executionDependencies);
 };
 //#endregion
 //#region src/runtime/runtime.ts
@@ -525,7 +699,7 @@ var Runtime = class Runtime {
 		let executionFailed = false;
 		let executionFailure;
 		try {
-			value = await runtime.runUnchecked(program);
+			value = await runtime.runUnchecked(program, config.options);
 		} catch (cause) {
 			executionFailed = true;
 			executionFailure = cause;
@@ -585,6 +759,10 @@ var Runtime = class Runtime {
 			throw cause;
 		}
 	}
+	/** Return a detached diagnostic snapshot without changing Runtime state. */
+	inspect() {
+		return this.handle.inspect();
+	}
 	/** Run one execution in this Runtime's child Scope. */
 	run(program, options) {
 		return this.handle.run(program, options);
@@ -593,8 +771,8 @@ var Runtime = class Runtime {
 	runWith(layer, program, options) {
 		return this.handle.runWith(layer, program, options);
 	}
-	runUnchecked(program) {
-		return this.handle.run(program);
+	runUnchecked(program, options) {
+		return this.handle.run(program, options);
 	}
 	dispose(optionsOrOutcome) {
 		return this.handle.dispose(optionsOrOutcome);
@@ -610,4 +788,4 @@ var Runtime = class Runtime {
 //#endregion
 export { MapLayerBackend as i, RuntimeObserver as n, classifyRuntimeOutcome as r, Runtime as t };
 
-//# sourceMappingURL=runtime-DnMn0X0X.mjs.map
+//# sourceMappingURL=runtime-C_55ofnL.mjs.map