better-effect 0.11.0 → 0.12.0

package/README.md

@@ -12,7 +12,9 @@ bun add better-effect better-result
 
 The published Runtime entrypoint is officially supported on Node.js and Bun.
 The tested runtime matrix is Node.js 24 and Bun 1.3.14, and the default runtime
-context uses Node/Bun async context propagation.
+context uses Node/Bun async context propagation. `bun run check` also deletes
+and rebuilds `dist`, packs the result into a temporary consumer, and runs the
+full Node/Bun `NodeRuntime` child-process suite.
 
 ## TypeScript knows what your application needs
 
@@ -156,6 +158,28 @@ Scope.
 Scope. `Effect.fn` captures the generator as a lazy `Program` for Runtime
 boundaries; the callback form remains supported for compatibility.
 
+Name a Program without executing it. The name is private diagnostic metadata,
+so the value remains an ordinary callable function and can be used with `pipe`:
+
+```ts
+const loadUser = pipe(
+  Effect.fn(async function* () {
+    return Result.ok(await userRepository.load(userId))
+  }),
+  Program.named('user.load')
+)
+
+const result = await runtime.run(loadUser, {
+  attributes: { userId, requestId }
+})
+```
+
+`Program.map`, `mapError`, `andThen`, `tap`, `tapError`, and `recover` preserve
+their source name. A later `Program.named` call overrides it. Collection
+Programs do not concatenate child names; give `Program.all`, `Program.forEach`,
+or `Program.allResults` an optional `{ name }` when the collection itself needs
+a diagnostic name.
+
 `Program.all` keeps a collection lazy until the returned Program is run. Pass
 `{ concurrency: n }` for a positive bounded FIFO worker pool; values retain
 input order. If a Program returns an error or throws, scheduling stops, already-
@@ -320,7 +344,56 @@ await runtime.warmup()
 Warmup failures include the Service and resolution path, release resources
 already acquired, dispose the backend and reject the Runtime. Optional
 observers expose Service resolution/acquisition, execution and Layer release
-events without coupling the core to an observability SDK:
+events without coupling the core to an observability SDK. Execution events
+carry one matching `executionId`, the optional Program name, copied readonly
+attributes, and a monotonic `durationMs` measured through execution cleanup:
+
+```ts
+const runtime = await Runtime.make(AppLive, {
+  observers: [
+    {
+      onExecutionStart: ({ executionId, name, attributes }) =>
+        console.debug('program.start', { executionId, name, attributes }),
+      onExecutionEnd: ({ executionId, outcome, durationMs }) =>
+        metrics.observe('program.duration_ms', durationMs, {
+          executionId,
+          outcome: outcome.status
+        })
+    }
+  ]
+})
+```
+
+The Runtime does not serialize or inspect attribute values. Attributes are
+shallow-copied and exposed as a readonly event view; do not attach secrets,
+large objects, or mutable application state. Keep sensitive values out of
+observer logs and metrics labels.
+
+For coarse, synchronous diagnostics, use `runtime.inspect()`:
+
+```ts
+const inspection = runtime.inspect()
+// {
+//   state: 'active',
+//   warmup: 'idle',
+//   activeExecutions: 0,
+//   executions: [],
+//   services: ['Database', 'UserRepository'],
+//   shutdownSignalAborted: false
+// }
+```
+
+The returned snapshot and its arrays are detached and immutable. It contains
+only public Service tags and execution IDs, names and start timestamps; it never
+resolves Services, warms the Runtime, creates Scopes, invokes observers or
+exposes providers, instances, signals, attributes or backend state. Execution
+entries remain present until their execution Scope cleanup settles. Warmup is
+reported as `idle`, `running`, `completed` or `failed`, and `state` reports
+`active`, `disposing` or `disposed`.
+
+`inspect()` is diagnostic information, not a lock, synchronization primitive or
+readiness guarantee. It cannot cancel or force shutdown of any execution; use
+`dispose()` and cooperative `AbortSignal` handling for lifecycle coordination.
 
 Missing, circular, and provider-construction failures use the logical Service
 tags in `ServiceNotFoundError`, `CircularDependencyError`, and
@@ -365,6 +438,29 @@ and its ordered `timeline`; call `clear()` to reuse it. Composition invokes
 observers in declaration order and isolates thrown or rejected observer
 failures from the Runtime result.
 
+For a startup view of the graph actually observed by a Runtime, compose the
+small graph observer and warm the Layer before accepting work:
+
+```ts
+import { Runtime } from 'better-effect'
+import { RuntimeGraphObserver } from 'better-effect/testing'
+
+const graph = RuntimeGraphObserver.make({ rootLabel: 'Runtime' })
+const runtime = await Runtime.make(AppLive, {
+  warmup: true,
+  observers: [graph]
+})
+
+console.log(graph.toJSON())
+console.log(graph.toMermaid())
+await runtime.dispose()
+```
+
+`RuntimeGraphObserver` uses only public resolution and acquisition events. Its
+snapshot is sorted, detached and immutable; it records Service tags and counts,
+not instances, scopes, causes or execution attributes. Providers that are never
+resolved remain absent, and `clear()` starts a new diagnostic session.
+
 Cancellation is cooperative and uses `AbortSignal`; no scheduler or fibers are
 created. Pass a signal to one execution and read it from the program when an
 I/O operation supports cancellation. Runtime disposal waits for active work;
@@ -379,6 +475,38 @@ const cancellableProgram = Effect.fn(async function* () {
 })
 ```
 
+For a Node.js or Bun CLI, use the host-specific `better-effect/node` entrypoint.
+`NodeRuntime.runMain` validates its signal and callback options before installing
+`SIGINT`/`SIGTERM` listeners, links the first signal to `CurrentAbortSignal`,
+and disposes the Runtime exactly once:
+
+```ts
+import { NodeRuntime } from 'better-effect/node'
+
+const main = Effect.fn(async function* () {
+  const signal = yield* CurrentAbortSignal
+  return Result.ok(await runCommand({ signal }))
+})
+
+await NodeRuntime.runMain(AppLive, main, {
+  onFailure: (error) => {
+    console.error(error)
+    return 1
+  },
+  onSuccess: () => 0
+})
+```
+
+`Result.err` uses `onFailure` (or exit code `1` by default), while thrown defects
+remain rejected and may be reported with `onDefect`. Cleanup-only failures use
+`onCleanupFailure`, remain observable, and still set a non-zero
+`process.exitCode` after successful work. The first `SIGINT` or `SIGTERM`
+immediately aborts `CurrentAbortSignal`; Runtime disposal then waits
+cooperatively for the main execution. Listeners are removed in `finally`,
+repeated signals are ignored, and the helper never calls `process.exit()`.
+The Node boundary intentionally does not expose a second grace-period policy;
+use `Runtime.dispose` directly when a managed Runtime needs one.
+
 For request-local context or overrides, add a Layer only to that execution:
 
 ```ts
@@ -671,10 +799,96 @@ const now = await runtime.run(async () => ServiceRuntime.resolve(Clock))
 await runtime.dispose()
 ```
 
-The entrypoint also provides `Random`/`RandomSeeded`, `Logger`/`LoggerTest`,
-`Config`, `CurrentRequest`, and the compatible `CurrentAbortSignal` bridge. None
-is installed implicitly; compose a normal Layer or use the provided test
-helpers.
+`IdGenerator` uses the host's cryptographic `crypto.randomUUID()` and is also
+opt-in. Use `IdGeneratorTest` to make entity creation deterministic without
+introducing a domain-specific ID type:
+
+```ts
+import { Result } from 'better-result'
+import { Effect, Layer, Service } from 'better-effect'
+import { IdGenerator } from 'better-effect/standard-services'
+import { IdGeneratorTest, TestRuntime } from 'better-effect/testing'
+
+class User extends Service<User>()('User') {
+  constructor(readonly id: string) {
+    super()
+  }
+}
+
+const createUser = Effect.fn(async function* () {
+  const ids = yield* IdGenerator
+  return Result.ok(new User(ids.next()))
+})
+
+const result = await TestRuntime.use(
+  Layer.merge(),
+  { idGenerator: new IdGeneratorTest(['user-1']) },
+  (test) => test.run(createUser)
+)
+// Result.ok(User { id: 'user-1' })
+```
+
+`IdGeneratorTest.from((index) => ...)` provides an unbounded deterministic
+sequence; its first factory index is zero and increases monotonically. The
+entrypoint also provides `Random`/`RandomSeeded`, `Logger`/`LoggerTest`, `Config`,
+`CurrentRequest`, and the compatible `CurrentAbortSignal` bridge. None is
+installed implicitly; compose a normal Layer or use the provided test helpers.
+
+`Clock.sleep` keeps the original `clock.sleep(milliseconds)` form and accepts
+an optional `AbortSignal`. Invalid delays still throw synchronously. Aborted
+sleeps clear their timer and listener; a supplied `signal.reason` is rejected
+unchanged, otherwise the rejection is an `AbortError`-named `DOMException`.
+
+Use the same signal in polling, retry delays and expiration checks:
+
+```ts
+const poll = async (clock: Clock, signal: AbortSignal) => {
+  while (true) {
+    const status = await readStatus()
+    if (status.ready) return status
+    await clock.sleep(1_000, { signal })
+  }
+}
+
+const retry = async <A>(operation: () => Promise<A>, clock: Clock, signal: AbortSignal) => {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await operation()
+    } catch (error) {
+      if (attempt === 2) throw error
+      await clock.sleep(100 * 2 ** attempt, { signal })
+    }
+  }
+}
+
+const waitUntilExpired = async (clock: Clock, expiresAt: number, signal: AbortSignal) => {
+  while (clock.now().getTime() < expiresAt) {
+    await clock.sleep(Math.min(expiresAt - clock.now().getTime(), 1_000), { signal })
+  }
+}
+```
+
+`ClockTest` orders sleeps by absolute deadline and FIFO for equal deadlines.
+`pendingSleeps` is a readonly count. `advanceToNext()` returns `false` when
+there is no pending sleep; `runAll({ maxSteps })` advances repeatedly and
+awaits one microtask checkpoint between deadlines so resumed code can schedule
+its next wait:
+
+```ts
+const clock = new ClockTest(0)
+const task = (async () => {
+  await clock.sleep(100)
+  await clock.sleep(50)
+})()
+
+await clock.runAll({ maxSteps: 10 })
+await task
+// clock.now().getTime() === 150
+```
+
+`setTime` may move backward. Pending sleeps keep their absolute deadlines and
+resolve only when reached. `ClockTest` does not virtualize `Date`, global
+`setTimeout` or the JavaScript microtask queue.
 
 For typed environment configuration, bind a Standard Schema directly to a
 reusable descriptor:

package/dist/adapters/iti.d.mts

@@ -1,5 +1,6 @@
 import { N as AnyServiceToken } from "../index-heuaRmXR.mjs";
-import { v as LayerBackend, x as LayerRegistration, y as LayerBackendDisposeOptions } from "../index-rQhZk3Nt.mjs";
+import { S as LayerRegistration, b as LayerBackendDisposeOptions, y as LayerBackend } from "../outcome-CB43bnFW.mjs";
+import "../index-BMdU_Z72.mjs";
 //#region src/adapters/iti.d.ts
 /**
  * ITI-backed Layer backend.

package/dist/adapters/iti.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"iti.d.mts","names":[],"sources":["../../src/adapters/iti.ts"],"mappings":";;;;;;;;;cAuBa,2BAA2B;UAC9B;mBAES;mBAEA;;;;;;mBAOA;UAET;;EAgBR,SAAS,cAAc;;EAuBvB,QAAQ,UAAU,iBAAiB,OAAO,IAAI,aAAa,KAAK,YAAY,aAAa;;EAiCnF,WAAW,UAAU,6BAA6B"}
+{"version":3,"file":"iti.d.mts","names":[],"sources":["../../src/adapters/iti.ts"],"mappings":";;;;;;;;;;cAyBa,2BAA2B;UAC9B;mBAES;mBAEA;;;;;;mBAOA;UAET;;EAeR,SAAS,cAAc;;EAwBvB,QAAQ,UAAU,iBAAiB,OAAO,IAAI,aAAa,KAAK,YAAY,aAAa;;EAkCnF,WAAW,UAAU,6BAA6B"}

package/dist/adapters/iti.mjs

@@ -1,6 +1,6 @@
-import { a as ServiceTagCollisionError, c as ServiceNotFoundError, t as DuplicateServiceError } from "../errors-Dnjhzbt0.mjs";
+import { f as captureServiceTag, n as normalizeLayerRegistration, r as DuplicateServiceError, s as ServiceTagCollisionError, t as captureLayerRegistrationTag, u as ServiceNotFoundError } from "../registration-drnZk0SY.mjs";
 import { t as isPromiseLike } from "../runtime-CDcCF5cb.mjs";
-import { t as assertServiceCompatibility } from "../internal-identity-DmUpBeeL.mjs";
+import { t as assertServiceCompatibility } from "../internal-identity-CbXoZIfw.mjs";
 import { createContainer } from "iti";
 //#region src/adapters/iti.ts
 /**
@@ -19,8 +19,7 @@ var ItiLayerBackend = class {
 	* retry boundary for that sticky failure behavior.
 	*/
 	pending = /* @__PURE__ */ new Map();
-	keyFor(token) {
-		const tag = token.serviceTag;
+	keyFor(tag) {
 		const existing = this.keys.get(tag);
 		if (existing) return existing;
 		const key = `better-effect:${tag}`;
@@ -29,20 +28,22 @@ var ItiLayerBackend = class {
 	}
 	/** Register a Layer provider under its deterministic Service-tag key. */
 	register(registration) {
-		const token = registration.service;
-		const tag = token.serviceTag;
+		const normalized = normalizeLayerRegistration(registration);
+		const token = normalized.service;
+		const tag = captureLayerRegistrationTag(normalized);
 		const existing = this.registered.get(tag);
 		if (existing === token) throw new DuplicateServiceError(token);
 		if (existing) throw new ServiceTagCollisionError(existing, token);
-		const key = this.keyFor(token);
-		this.container = this.container.add({ [key]: registration.acquire });
+		const key = this.keyFor(tag);
+		this.container = this.container.add({ [key]: normalized.acquire });
 		this.registered.set(tag, token);
 	}
 	/** Resolve a registered Service through the ITI container. */
 	resolve(token) {
-		const registered = this.registered.get(token.serviceTag);
+		const tag = captureServiceTag(token);
+		const registered = this.registered.get(tag);
 		if (registered === void 0) throw new ServiceNotFoundError(token);
-		const key = this.keyFor(token);
+		const key = this.keyFor(tag);
 		const resolved = this.container.get(key);
 		const validate = (instance) => {
 			assertServiceCompatibility(token, registered, instance);

package/dist/adapters/iti.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"iti.mjs","names":[],"sources":["../../src/adapters/iti.ts"],"sourcesContent":["import { createContainer } from 'iti'\n\nimport {\n  DuplicateServiceError,\n  ServiceTagCollisionError,\n  type LayerBackend,\n  type LayerBackendDisposeOptions,\n  type LayerRegistration\n} from '../layer'\n\nimport { ServiceNotFoundError, type AnyServiceToken } from '../service'\n\nimport { assertServiceCompatibility } from '../layer/internal-identity'\nimport { isPromiseLike } from '../utils/runtime'\n\ntype LayerAcquiredValue = Awaited<ReturnType<LayerRegistration['acquire']>>\n\n/**\n * ITI-backed Layer backend.\n *\n * Install `iti` as the optional peer dependency and pass an instance to\n * `Runtime.make` when using ITI's container implementation.\n */\nexport class ItiLayerBackend implements LayerBackend {\n  private container: any = createContainer()\n\n  private readonly keys = new Map<string, string>()\n\n  private readonly registered = new Map<string, AnyServiceToken>()\n\n  /**\n   * Track async gets so disposal cannot reset ITI while a provider is acquiring.\n   * ITI caches rejected acquisitions; replacing the container is the explicit\n   * retry boundary for that sticky failure behavior.\n   */\n  private readonly pending = new Map<Promise<unknown>, AnyServiceToken>()\n\n  private keyFor(token: AnyServiceToken): string {\n    const tag = token.serviceTag\n    const existing = this.keys.get(tag)\n\n    if (existing) {\n      return existing\n    }\n\n    const key = `better-effect:${tag}`\n\n    this.keys.set(tag, key)\n\n    return key\n  }\n\n  /** Register a Layer provider under its deterministic Service-tag key. */\n  register(registration: LayerRegistration): void {\n    const token = registration.service\n    const tag = token.serviceTag\n    const existing = this.registered.get(tag)\n\n    if (existing === token) {\n      throw new DuplicateServiceError(token)\n    }\n\n    if (existing) {\n      throw new ServiceTagCollisionError(existing, token)\n    }\n\n    const key = this.keyFor(token)\n\n    this.container = this.container.add({\n      [key]: registration.acquire\n    })\n\n    this.registered.set(tag, token)\n  }\n\n  /** Resolve a registered Service through the ITI container. */\n  resolve<T extends AnyServiceToken>(token: T): InstanceType<T> | PromiseLike<InstanceType<T>> {\n    const registered = this.registered.get(token.serviceTag)\n\n    if (registered === undefined) {\n      throw new ServiceNotFoundError(token)\n    }\n\n    const key = this.keyFor(token)\n    const resolved = this.container.get(key)\n\n    const validate = (instance: LayerAcquiredValue): InstanceType<T> => {\n      assertServiceCompatibility(token, registered, instance)\n\n      // SAFETY: The registered tag and compatibility check establish the constructor-to-instance relationship after ITI erases it.\n      return instance as InstanceType<T>\n    }\n\n    if (isPromiseLike(resolved)) {\n      const pending = Promise.resolve(resolved).then(validate)\n\n      this.pending.set(pending, registered)\n      void pending.then(\n        () => this.pending.delete(pending),\n        () => this.pending.delete(pending)\n      )\n\n      return pending\n    }\n\n    return validate(resolved)\n  }\n\n  /** Reset container-owned ITI state; Scope owns Layer provider releases. */\n  async disposeAll(options?: LayerBackendDisposeOptions): Promise<void> {\n    const container = this.container\n    const acquisitions = [...this.pending.keys()]\n\n    try {\n      if (acquisitions.length > 0) {\n        const observePending = options?.onPendingAcquisitions\n\n        if (observePending) {\n          await observePending(acquisitions)\n        }\n\n        await Promise.allSettled(acquisitions)\n      }\n      await container.disposeAll()\n    } finally {\n      this.container = createContainer()\n      this.registered.clear()\n      this.keys.clear()\n      this.pending.clear()\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;AAuBA,IAAa,kBAAb,MAAqD;CACnD,YAAyB,gBAAgB;CAEzC,uBAAwB,IAAI,IAAoB;CAEhD,6BAA8B,IAAI,IAA6B;;;;;;CAO/D,0BAA2B,IAAI,IAAuC;CAEtE,OAAe,OAAgC;EAC7C,MAAM,MAAM,MAAM;EAClB,MAAM,WAAW,KAAK,KAAK,IAAI,GAAG;EAElC,IAAI,UACF,OAAO;EAGT,MAAM,MAAM,iBAAiB;EAE7B,KAAK,KAAK,IAAI,KAAK,GAAG;EAEtB,OAAO;CACT;;CAGA,SAAS,cAAuC;EAC9C,MAAM,QAAQ,aAAa;EAC3B,MAAM,MAAM,MAAM;EAClB,MAAM,WAAW,KAAK,WAAW,IAAI,GAAG;EAExC,IAAI,aAAa,OACf,MAAM,IAAI,sBAAsB,KAAK;EAGvC,IAAI,UACF,MAAM,IAAI,yBAAyB,UAAU,KAAK;EAGpD,MAAM,MAAM,KAAK,OAAO,KAAK;EAE7B,KAAK,YAAY,KAAK,UAAU,IAAI,GACjC,MAAM,aAAa,QACtB,CAAC;EAED,KAAK,WAAW,IAAI,KAAK,KAAK;CAChC;;CAGA,QAAmC,OAA0D;EAC3F,MAAM,aAAa,KAAK,WAAW,IAAI,MAAM,UAAU;EAEvD,IAAI,eAAe,KAAA,GACjB,MAAM,IAAI,qBAAqB,KAAK;EAGtC,MAAM,MAAM,KAAK,OAAO,KAAK;EAC7B,MAAM,WAAW,KAAK,UAAU,IAAI,GAAG;EAEvC,MAAM,YAAY,aAAkD;GAClE,2BAA2B,OAAO,YAAY,QAAQ;GAGtD,OAAO;EACT;EAEA,IAAI,cAAc,QAAQ,GAAG;GAC3B,MAAM,UAAU,QAAQ,QAAQ,QAAQ,CAAC,CAAC,KAAK,QAAQ;GAEvD,KAAK,QAAQ,IAAI,SAAS,UAAU;GACpC,QAAa,WACL,KAAK,QAAQ,OAAO,OAAO,SAC3B,KAAK,QAAQ,OAAO,OAAO,CACnC;GAEA,OAAO;EACT;EAEA,OAAO,SAAS,QAAQ;CAC1B;;CAGA,MAAM,WAAW,SAAqD;EACpE,MAAM,YAAY,KAAK;EACvB,MAAM,eAAe,CAAC,GAAG,KAAK,QAAQ,KAAK,CAAC;EAE5C,IAAI;GACF,IAAI,aAAa,SAAS,GAAG;IAC3B,MAAM,iBAAiB,SAAS;IAEhC,IAAI,gBACF,MAAM,eAAe,YAAY;IAGnC,MAAM,QAAQ,WAAW,YAAY;GACvC;GACA,MAAM,UAAU,WAAW;EAC7B,UAAU;GACR,KAAK,YAAY,gBAAgB;GACjC,KAAK,WAAW,MAAM;GACtB,KAAK,KAAK,MAAM;GAChB,KAAK,QAAQ,MAAM;EACrB;CACF;AACF"}
+{"version":3,"file":"iti.mjs","names":[],"sources":["../../src/adapters/iti.ts"],"sourcesContent":["import { createContainer } from 'iti'\n\nimport {\n  DuplicateServiceError,\n  ServiceTagCollisionError,\n  type LayerBackend,\n  type LayerBackendDisposeOptions,\n  type LayerRegistration\n} from '../layer'\n\nimport { ServiceNotFoundError, type AnyServiceToken } from '../service'\nimport { captureServiceTag } from '../service/tag'\n\nimport { assertServiceCompatibility } from '../layer/internal-identity'\nimport { captureLayerRegistrationTag, normalizeLayerRegistration } from '../layer/registration'\nimport { isPromiseLike } from '../utils/runtime'\n\ntype LayerAcquiredValue = Awaited<ReturnType<LayerRegistration['acquire']>>\n\n/**\n * ITI-backed Layer backend.\n *\n * Install `iti` as the optional peer dependency and pass an instance to\n * `Runtime.make` when using ITI's container implementation.\n */\nexport class ItiLayerBackend implements LayerBackend {\n  private container: any = createContainer()\n\n  private readonly keys = new Map<string, string>()\n\n  private readonly registered = new Map<string, AnyServiceToken>()\n\n  /**\n   * Track async gets so disposal cannot reset ITI while a provider is acquiring.\n   * ITI caches rejected acquisitions; replacing the container is the explicit\n   * retry boundary for that sticky failure behavior.\n   */\n  private readonly pending = new Map<Promise<unknown>, AnyServiceToken>()\n\n  private keyFor(tag: string): string {\n    const existing = this.keys.get(tag)\n\n    if (existing) {\n      return existing\n    }\n\n    const key = `better-effect:${tag}`\n\n    this.keys.set(tag, key)\n\n    return key\n  }\n\n  /** Register a Layer provider under its deterministic Service-tag key. */\n  register(registration: LayerRegistration): void {\n    const normalized = normalizeLayerRegistration(registration)\n    const token = normalized.service\n    const tag = captureLayerRegistrationTag(normalized)\n    const existing = this.registered.get(tag)\n\n    if (existing === token) {\n      throw new DuplicateServiceError(token)\n    }\n\n    if (existing) {\n      throw new ServiceTagCollisionError(existing, token)\n    }\n\n    const key = this.keyFor(tag)\n\n    this.container = this.container.add({\n      [key]: normalized.acquire\n    })\n\n    this.registered.set(tag, token)\n  }\n\n  /** Resolve a registered Service through the ITI container. */\n  resolve<T extends AnyServiceToken>(token: T): InstanceType<T> | PromiseLike<InstanceType<T>> {\n    const tag = captureServiceTag(token)\n    const registered = this.registered.get(tag)\n\n    if (registered === undefined) {\n      throw new ServiceNotFoundError(token)\n    }\n\n    const key = this.keyFor(tag)\n    const resolved = this.container.get(key)\n\n    const validate = (instance: LayerAcquiredValue): InstanceType<T> => {\n      assertServiceCompatibility(token, registered, instance)\n\n      // SAFETY: The registered tag and compatibility check establish the constructor-to-instance relationship after ITI erases it.\n      return instance as InstanceType<T>\n    }\n\n    if (isPromiseLike(resolved)) {\n      const pending = Promise.resolve(resolved).then(validate)\n\n      this.pending.set(pending, registered)\n      void pending.then(\n        () => this.pending.delete(pending),\n        () => this.pending.delete(pending)\n      )\n\n      return pending\n    }\n\n    return validate(resolved)\n  }\n\n  /** Reset container-owned ITI state; Scope owns Layer provider releases. */\n  async disposeAll(options?: LayerBackendDisposeOptions): Promise<void> {\n    const container = this.container\n    const acquisitions = [...this.pending.keys()]\n\n    try {\n      if (acquisitions.length > 0) {\n        const observePending = options?.onPendingAcquisitions\n\n        if (observePending) {\n          await observePending(acquisitions)\n        }\n\n        await Promise.allSettled(acquisitions)\n      }\n      await container.disposeAll()\n    } finally {\n      this.container = createContainer()\n      this.registered.clear()\n      this.keys.clear()\n      this.pending.clear()\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;AAyBA,IAAa,kBAAb,MAAqD;CACnD,YAAyB,gBAAgB;CAEzC,uBAAwB,IAAI,IAAoB;CAEhD,6BAA8B,IAAI,IAA6B;;;;;;CAO/D,0BAA2B,IAAI,IAAuC;CAEtE,OAAe,KAAqB;EAClC,MAAM,WAAW,KAAK,KAAK,IAAI,GAAG;EAElC,IAAI,UACF,OAAO;EAGT,MAAM,MAAM,iBAAiB;EAE7B,KAAK,KAAK,IAAI,KAAK,GAAG;EAEtB,OAAO;CACT;;CAGA,SAAS,cAAuC;EAC9C,MAAM,aAAa,2BAA2B,YAAY;EAC1D,MAAM,QAAQ,WAAW;EACzB,MAAM,MAAM,4BAA4B,UAAU;EAClD,MAAM,WAAW,KAAK,WAAW,IAAI,GAAG;EAExC,IAAI,aAAa,OACf,MAAM,IAAI,sBAAsB,KAAK;EAGvC,IAAI,UACF,MAAM,IAAI,yBAAyB,UAAU,KAAK;EAGpD,MAAM,MAAM,KAAK,OAAO,GAAG;EAE3B,KAAK,YAAY,KAAK,UAAU,IAAI,GACjC,MAAM,WAAW,QACpB,CAAC;EAED,KAAK,WAAW,IAAI,KAAK,KAAK;CAChC;;CAGA,QAAmC,OAA0D;EAC3F,MAAM,MAAM,kBAAkB,KAAK;EACnC,MAAM,aAAa,KAAK,WAAW,IAAI,GAAG;EAE1C,IAAI,eAAe,KAAA,GACjB,MAAM,IAAI,qBAAqB,KAAK;EAGtC,MAAM,MAAM,KAAK,OAAO,GAAG;EAC3B,MAAM,WAAW,KAAK,UAAU,IAAI,GAAG;EAEvC,MAAM,YAAY,aAAkD;GAClE,2BAA2B,OAAO,YAAY,QAAQ;GAGtD,OAAO;EACT;EAEA,IAAI,cAAc,QAAQ,GAAG;GAC3B,MAAM,UAAU,QAAQ,QAAQ,QAAQ,CAAC,CAAC,KAAK,QAAQ;GAEvD,KAAK,QAAQ,IAAI,SAAS,UAAU;GACpC,QAAa,WACL,KAAK,QAAQ,OAAO,OAAO,SAC3B,KAAK,QAAQ,OAAO,OAAO,CACnC;GAEA,OAAO;EACT;EAEA,OAAO,SAAS,QAAQ;CAC1B;;CAGA,MAAM,WAAW,SAAqD;EACpE,MAAM,YAAY,KAAK;EACvB,MAAM,eAAe,CAAC,GAAG,KAAK,QAAQ,KAAK,CAAC;EAE5C,IAAI;GACF,IAAI,aAAa,SAAS,GAAG;IAC3B,MAAM,iBAAiB,SAAS;IAEhC,IAAI,gBACF,MAAM,eAAe,YAAY;IAGnC,MAAM,QAAQ,WAAW,YAAY;GACvC;GACA,MAAM,UAAU,WAAW;EAC7B,UAAU;GACR,KAAK,YAAY,gBAAgB;GACjC,KAAK,WAAW,MAAM;GACtB,KAAK,KAAK,MAAM;GAChB,KAAK,QAAQ,MAAM;EACrB;CACF;AACF"}

package/dist/{effect-2ZcGZI8A.mjs → effect-CK4YZaX0.mjs}

@@ -1,5 +1,5 @@
 import { t as isPromiseLike } from "./runtime-CDcCF5cb.mjs";
-import { t as Scope } from "./scope-GGnmTQck.mjs";
+import { i as Scope, n as inheritProgramName, r as setProgramName } from "./program-metadata-DhQCCirO.mjs";
 import { Err, Result, matchError, matchErrorPartial } from "better-result";
 //#region src/effect/combinators.ts
 const asResult = (value) => {
@@ -227,10 +227,22 @@ const recoverRuntime = (effect, recover) => {
 	if (isAsyncEffect(effect)) return Promise.resolve(effect).then((result) => Result.tryRecoverAsync(result, continueWith));
 	return Result.tryRecoverAsync(effect, continueWith);
 };
-const mapProgram = (program, fn) => asProgram(() => mapRuntime(program(), fn));
-const mapErrorProgram = (program, fn) => asProgram(() => mapErrorRuntime(program(), fn));
-const tapProgram = (program, fn) => asProgram(() => tapRuntime(program(), fn));
-const tapErrorProgram = (program, fn) => asProgram(() => tapErrorRuntime(program(), fn));
+const mapProgram = (program, fn) => {
+	const mapped = asProgram(() => mapRuntime(program(), fn));
+	return inheritProgramName(program, mapped);
+};
+const mapErrorProgram = (program, fn) => {
+	const mapped = asProgram(() => mapErrorRuntime(program(), fn));
+	return inheritProgramName(program, mapped);
+};
+const tapProgram = (program, fn) => {
+	const tapped = asProgram(() => tapRuntime(program(), fn));
+	return inheritProgramName(program, tapped);
+};
+const tapErrorProgram = (program, fn) => {
+	const tapped = asProgram(() => tapErrorRuntime(program(), fn));
+	return inheritProgramName(program, tapped);
+};
 function map(first, second) {
 	if (second === void 0) return (program) => {
 		return mapProgram(program, first);
@@ -244,8 +256,13 @@ function mapError(first, second) {
 	return mapErrorProgram(first, second);
 }
 function andThen(first, second) {
-	if (second === void 0) return (program) => () => andThenRuntime(program(), first);
-	return () => andThenRuntime(first(), second);
+	if (second === void 0) return (program) => {
+		const chained = () => andThenRuntime(program(), first);
+		return inheritProgramName(program, chained);
+	};
+	const source = first;
+	const chained = () => andThenRuntime(source(), second);
+	return inheritProgramName(source, chained);
 }
 function tap(first, second) {
 	if (second === void 0) return (program) => {
@@ -260,8 +277,13 @@ function tapError(first, second) {
 	return tapErrorProgram(first, second);
 }
 function recover(first, second) {
-	if (second === void 0) return (program) => () => recoverRuntime(program(), first);
-	return () => recoverRuntime(first(), second);
+	if (second === void 0) return (program) => {
+		const recovered = () => recoverRuntime(program(), first);
+		return inheritProgramName(program, recovered);
+	};
+	const source = first;
+	const recovered = () => recoverRuntime(source(), second);
+	return inheritProgramName(source, recovered);
 }
 //#endregion
 //#region src/effect/program-scheduler.ts
@@ -326,6 +348,14 @@ function fn(body) {
 	const program = () => runResultGenerator(body);
 	return program;
 }
+const validateProgramName = (name) => {
+	if (typeof name !== "string") throw new TypeError("Program name must be a string");
+};
+function programNamed(name, program) {
+	validateProgramName(name);
+	if (program === void 0) return (source) => setProgramName(source, name);
+	return setProgramName(program, name);
+}
 const runShortCircuitingCollection = async (length, task, concurrency) => {
 	const outcome = await runProgramCollection(length, task, {
 		concurrency,
@@ -348,26 +378,42 @@ const runAllResultsCollection = async (length, task, concurrency) => {
 /** Build a lazy Program collection with optional bounded concurrency. */
 function programAll(programs, options = {}) {
 	const concurrency = options.concurrency;
+	const name = options?.name;
 	validateProgramConcurrency(concurrency);
 	const program = () => runShortCircuitingCollection(programs.length, (index) => programs[index](), concurrency);
+	if (name !== void 0) {
+		validateProgramName(name);
+		setProgramName(program, name);
+	}
 	return program;
 }
 /** Build a lazy Program collection from an input array and Program factory. */
 function programForEach(items, makeProgram, options = {}) {
 	const concurrency = options.concurrency;
+	const name = options?.name;
 	validateProgramConcurrency(concurrency);
 	const program = () => runShortCircuitingCollection(items.length, (index) => makeProgram(items[index], index)(), concurrency);
+	if (name !== void 0) {
+		validateProgramName(name);
+		setProgramName(program, name);
+	}
 	return program;
 }
 /** Build a lazy Program collection that retains every child Result. */
 function programAllResults(programs, options = {}) {
 	const concurrency = options.concurrency;
+	const name = options?.name;
 	validateProgramConcurrency(concurrency);
 	const program = () => runAllResultsCollection(programs.length, (index) => programs[index](), concurrency);
+	if (name !== void 0) {
+		validateProgramName(name);
+		setProgramName(program, name);
+	}
 	return program;
 }
 /** Value-level namespace for lazy Program combinators. */
 const Program = {
+	named: programNamed,
 	all: programAll,
 	forEach: programForEach,
 	allResults: programAllResults,
@@ -510,4 +556,4 @@ const Effect = {
 //#endregion
 export { Program as n, Effect as t };
 
-//# sourceMappingURL=effect-2ZcGZI8A.mjs.map
+//# sourceMappingURL=effect-CK4YZaX0.mjs.map