better-effect 0.10.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
 
@@ -99,6 +101,40 @@ const AppLive = Layer.merge(DatabaseLive, UserRepositoryLive)
 const runtime = await Runtime.make(AppLive)
 ```
 
+Use `Layer.empty` when a composition root intentionally has no providers. It is
+stable and has the exact `Layer<never, never>` type:
+
+```ts
+const EmptyLive = Layer.empty
+const runtime = await Runtime.make(EmptyLive)
+await runtime.run(() => 'no Services required')
+```
+
+For a port/adapter boundary, `Layer.alias` exposes one compatible implementation
+under another Service token without constructing, cloning, or proxying it:
+
+```ts
+class SqlUserRepository extends Service<SqlUserRepository>()('SqlUserRepository') {
+  findById(id: string): string {
+    return `sql:${id}`
+  }
+}
+
+class UserRepository extends Service<UserRepository>()('UserRepository') {
+  declare findById: SqlUserRepository['findById']
+}
+
+const UserRepositoryPort = Layer.alias({
+  from: SqlUserRepository,
+  to: UserRepository
+})
+const ApplicationLive = Layer.merge(Layer.empty, Layer.make(SqlUserRepository), UserRepositoryPort)
+```
+
+The alias lazily resolves `from`, returns the same object under `to`, and checks
+that the source satisfies the target's `Service.Contract`. Its source remains an
+external Layer requirement until the source provider is composed.
+
 And the contract does not disappear after startup.
 
 A Runtime also knows which Services exist in its environment:
@@ -122,17 +158,130 @@ 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-
 started Programs are allowed to settle, and the deterministic primary failure remains selected;
 there is no cancellation or Fiber scheduler.
 
+Use `Program.forEach` when each item needs a lazy Program factory. The callback
+receives the item and its input index, and the returned Program produces a
+readonly collection in input order:
+
+```ts
+const synchronized = Program.forEach(userIds, (userId, index) => synchronizeUser(userId, index), {
+  concurrency: 8
+})
+
+const result = await runtime.run(synchronized)
+```
+
+Use `Program.allResults` when typed validation errors should be retained rather
+than short-circuiting. It returns every exact child `Result` as a successful
+collection element; defects still stop new work and reject the outer Program:
+
+```ts
+const validations = Program.allResults(
+  [validateIdentity, validateAddress, validateDocuments] as const,
+  { concurrency: 3 }
+)
+
+const results = await runtime.run(validations)
+```
+
+Both helpers use the same lazy bounded scheduler as `Program.all`: indexes are
+claimed in order, output order is stable, and already-started work is always
+allowed to settle.
+
+Use `Effect.*` to transform an already-created Result, and `Program.*` to compose
+an `Effect.fn` Program without starting it. `Program.map`, `mapError`, `tap`, and
+`tapError` preserve that laziness; `andThen` and `recover` accept an Effect, a
+Promise of an Effect, or another Program only after their matching Result branch
+is selected. `Program.andThen` unions its source and continuation error and
+Service requirement channels. `Program.recover` handles and removes the source
+`Err` channel, exposes the recovery error channel, and unions the source and
+recovery Service requirements. Taps preserve the original Result object on
+success.
+
 `Runtime.make(AppLive)` and `Runtime.run(AppLive, program)` use the built-in
 `MapLayerBackend`. Pass `{ backend: new ItiLayerBackend() }` when an external
 container is needed; `MemoryLayerBackend` remains its compatibility alias from
 `better-effect/testing`.
 
+### Verify custom adapters
+
+`better-effect/testing` provides runner-neutral conformance scenarios for
+third-party `LayerBackend` and `RuntimeContextStorage` implementations. Each
+scenario has a stable `name` and `run` callback, creates a fresh adapter, and
+runs the optional adapter cleanup after every assertion outcome. Backends must
+synchronously pass the actual readonly pending acquisition Promise collection to
+`disposeAll`'s `onPendingAcquisitions` hook, await the callback, then await the
+acquisitions before clearing state. Declare the backend's acquisition-failure
+policy explicitly: `MapLayerBackend` retries,
+while ITI keeps an asynchronous failure cached until disposal.
+
+Register the scenarios with Bun:
+
+```ts
+import { describe, test } from 'bun:test'
+import { MapLayerBackend } from 'better-effect'
+import { layerBackendContract } from 'better-effect/testing'
+
+describe('My backend', () => {
+  for (const scenario of layerBackendContract({
+    makeBackend: () => new MapLayerBackend(),
+    acquisitionFailure: 'retry'
+  })) {
+    test(scenario.name, scenario.run)
+  }
+})
+```
+
+The same scenarios work with Vitest without adding a runner dependency to the
+published entrypoint:
+
+```ts
+import { describe, it } from 'vitest'
+import { NodeRuntimeContextStorage } from 'better-effect/runtime/node'
+import { runtimeContextStorageContract } from 'better-effect/testing'
+
+describe('My context storage', () => {
+  for (const scenario of runtimeContextStorageContract({
+    makeStorage: () => new NodeRuntimeContextStorage(),
+    concurrency: 'concurrent'
+  })) {
+    it(scenario.name, scenario.run)
+  }
+})
+```
+
+Use `concurrency: 'sequential'` for a storage that rejects overlapping roots
+with `RuntimeContextOverlapError`; pass `makeCompanionStorage` to also verify
+that it does not leak frames into a Node or explicit storage. See the adapter
+guide for the complete `LayerBackend` contract.
+
 Runtimes are async disposables, so request-scoped code can use:
 
 ```ts
@@ -146,6 +295,42 @@ Or let `Runtime.use` own the lifetime:
 const result = await Runtime.use(AppLive, (runtime) => runtime.run(program))
 ```
 
+For isolated application tests, use the testing facade over that same Layer and
+Runtime. It installs only the controlled Services you pass, records lifecycle
+events, and disposes automatically:
+
+```ts
+import { ClockTest, LoggerTest, TestRuntime } from 'better-effect/testing'
+
+const logger = new LoggerTest()
+const result = await TestRuntime.use(
+  AppLive,
+  {
+    overrides: [DatabaseTest],
+    clock: new ClockTest(Date.UTC(2026, 0, 1)),
+    logger
+  },
+  async (test) => {
+    const value = await test.run(loadDashboard)
+    expect(test.observer.executionEnds).toHaveLength(1)
+    return value
+  }
+)
+
+expect(logger.events).toHaveLength(1)
+```
+
+A long-lived test boundary supports integration-style request Layers as well:
+
+```ts
+await using test = await TestRuntime.make(AppLive, { overrides: [DatabaseTest] })
+const result = await test.runWith(RequestLive, handleRequest)
+```
+
+`TestRuntime.use` preserves program-vs-cleanup failure precedence. The default
+recorder is available as `test.observer`; use `test.runtime` only when an
+advanced test explicitly needs the underlying Runtime.
+
 Layer providers remain lazy unless startup validation is requested. Warm them
 all before accepting work with either form:
 
@@ -159,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
@@ -176,6 +410,57 @@ const runtime = await Runtime.make(AppLive, {
 })
 ```
 
+For lifecycle assertions, `better-effect/testing` provides a recorder and a
+best-effort composition utility:
+
+```ts
+import { RecordedRuntimeObserver, RuntimeObserver } from 'better-effect/testing'
+
+const recorded = RecordedRuntimeObserver.make()
+const runtime = await Runtime.make(AppTest, {
+  observers: [
+    RuntimeObserver.compose(recorded, {
+      onExecutionEnd: ({ outcome }) => console.debug(outcome.status)
+    })
+  ]
+})
+
+await runtime.run(program)
+const snapshot = recorded.snapshot()
+expect(snapshot.executionEnds).toHaveLength(1)
+expect(snapshot.timeline).toContain(snapshot.executionEnds[0])
+
+await runtime.dispose()
+```
+
+`RecordedRuntimeObserver` preserves event identity in immutable category views
+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;
@@ -190,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
@@ -229,9 +546,9 @@ app.get(
 )
 ```
 
-Hono validators can precede the generator or handler callback. Their validated
-`c.req.valid(...)` inputs are combined and inferred without a manual `Input`
-helper:
+One or more Hono validators can precede the generator or handler callback, in
+the order they should run. Their validated `c.req.valid(...)` inputs are
+combined and inferred without a manual `Input` helper:
 
 ```ts
 import { sValidator } from '@hono/standard-validator'
@@ -408,7 +725,9 @@ Some dependencies are values.
 
 Others own connections, sessions, files or other resources.
 
-`Layer.scoped`, `Layer.scopedGen`, `Effect.acquireRelease`, `Effect.add` and `Scope` make their lifetime explicit.
+`Layer.scoped`, `Layer.scopedGen`, `Layer.scopedDisposable`, `Effect.acquireRelease`,
+`Effect.acquireReleaseResult`, `Effect.acquireDisposable`, `Effect.add` and `Scope` make their
+lifetime explicit.
 
 ```ts
 const DatabaseLive = Layer.scoped(
@@ -422,6 +741,35 @@ Runtime owns the application lifetime and safely releases scoped resources when
 
 Resources acquired during an individual execution belong to that execution instead.
 
+When an existing API already returns a `Result`, keep its typed failure channel while
+registering only successful acquisitions:
+
+```ts
+const connection =
+  yield *
+  Effect.acquireReleaseResult(
+    () => pool.connect(),
+    (connection, outcome) => connection.close(outcome)
+  )
+```
+
+An `Err` is returned unchanged and is never released. Thrown or rejected acquisition
+defects use the normal `UnhandledException` channel; release failures remain Scope
+cleanup failures rather than widening the acquisition error type.
+
+For values that implement JavaScript disposal, use the disposable helpers instead of
+repeating a release callback. Async disposal is preferred when both protocols exist:
+
+```ts
+const file = yield * Effect.acquireDisposable(() => openFile(path))
+
+const DatabaseLive = Layer.scopedDisposable(Database, () => Database.connect())
+```
+
+`Effect.acquireDisposable` belongs to the current execution Scope. `Layer.scopedDisposable`
+keeps the client alive across executions and disposes it with the Runtime root; the DI
+backend never owns that release.
+
 ### Keep your runtime choices
 
 `better-effect` is not a replacement implementation of Effect.
@@ -451,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:
@@ -572,7 +1006,26 @@ still rejects it when its Layer does not provide every required Service.
 
 Observation helpers such as `Effect.tap`, `Effect.tapError`, and `Effect.tapBoth`
 run only the active branch and return the original Result, so logging or metrics
-do not change the pipeline's value or requirement channel.
+do not change the pipeline's value or requirement channel. The async variants
+`Effect.tapAsync`, `Effect.tapErrorAsync`, and `Effect.tapBothAsync` accept
+`PromiseLike<void>` observers, always return a Promise, and preserve the source
+requirements. They delegate branch selection and defect handling to
+`better-result`; only the active observer runs, and a successful observation
+returns the exact original Result. They do not create a Scope or resolve
+Services inside the callback.
+
+```ts
+const audited = pipe(
+  loadUser(userId),
+  Effect.tapAsync((user) => metrics.recordUserLoaded(user.id)),
+  Effect.tapErrorAsync((error) => metrics.recordUserFailure(error))
+)
+```
+
+`Effect.matchError` exhaustively maps a tagged `Err` union, while
+`Effect.matchErrorPartial` maps selected tags and retains unhandled variants in
+the resulting error union. Both delegate to `better-result`'s tagged-error
+matchers and preserve the source success and requirement channels.
 
 Use `Effect.recover` or `Effect.recoverAsync` for an explicit fallback Result;
 the fallback is evaluated only when the input is an `Err`, and its Service

package/dist/adapters/iti.d.mts

@@ -1,6 +1,6 @@
-import { N as AnyServiceToken } from "../index-CULgSzUw.mjs";
-import "../index-C7KX5rAP.mjs";
-import { a as LayerRegistration, n as LayerBackend } from "../map-layer-backend-rNwfH0Bz.mjs";
+import { N as AnyServiceToken } from "../index-heuaRmXR.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.
@@ -24,7 +24,7 @@ declare class ItiLayerBackend implements LayerBackend {
   /** Resolve a registered Service through the ITI container. */
   resolve<T extends AnyServiceToken>(token: T): InstanceType<T> | PromiseLike<InstanceType<T>>;
   /** Reset container-owned ITI state; Scope owns Layer provider releases. */
-  disposeAll(): Promise<void>;
+  disposeAll(options?: LayerBackendDisposeOptions): Promise<void>;
 }
 //#endregion
 export { ItiLayerBackend };

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

@@ -1 +1 @@
-{"version":3,"file":"iti.d.mts","names":[],"sources":["../../src/adapters/iti.ts"],"mappings":";;;;;;;;;;cAsBa,2BAA2B;UAC9B;mBAES;mBAEA;;;;;;mBAOA;UAET;;EAgBR,SAAS,cAAc;;EAuBvB,QAAQ,UAAU,iBAAiB,OAAO,IAAI,aAAa,KAAK,YAAY,aAAa;;EAiCnF,cAAc"}
+{"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
 /**
@@ -18,9 +18,8 @@ var ItiLayerBackend = class {
 	* ITI caches rejected acquisitions; replacing the container is the explicit
 	* retry boundary for that sticky failure behavior.
 	*/
-	pending = /* @__PURE__ */ new Set();
-	keyFor(token) {
-		const tag = token.serviceTag;
+	pending = /* @__PURE__ */ new Map();
+	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);
@@ -50,17 +51,22 @@ var ItiLayerBackend = class {
 		};
 		if (isPromiseLike(resolved)) {
 			const pending = Promise.resolve(resolved).then(validate);
-			this.pending.add(pending);
+			this.pending.set(pending, registered);
 			pending.then(() => this.pending.delete(pending), () => this.pending.delete(pending));
 			return pending;
 		}
 		return validate(resolved);
 	}
 	/** Reset container-owned ITI state; Scope owns Layer provider releases. */
-	async disposeAll() {
+	async disposeAll(options) {
 		const container = this.container;
+		const acquisitions = [...this.pending.keys()];
 		try {
-			await Promise.allSettled(this.pending);
+			if (acquisitions.length > 0) {
+				const observePending = options?.onPendingAcquisitions;
+				if (observePending) await observePending(acquisitions);
+				await Promise.allSettled(acquisitions);
+			}
 			await container.disposeAll();
 		} finally {
 			this.container = createContainer();