better-effect 0.9.31 → 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Alves
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,6 +10,10 @@ Use Services directly inside `Effect.fn` Programs (or eager `Effect.gen` workflo
 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.
+
 ## TypeScript knows what your application needs
 
 ```ts
@@ -95,6 +99,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:
@@ -109,20 +147,117 @@ const inspectDatabase = Effect.fn(async function* () {
 await runtime.run(inspectDatabase)
 ```
 
+Runtime boundaries inspect only nominal `better-result` values: `Result.err`
+becomes a failed execution, while a plain object with `status: 'error'` is
+still a successful value. Intermediate Results do not close the execution
+Scope.
+
 `Effect.gen` remains eager for code that already runs inside a resolver and
 Scope. `Effect.fn` captures the generator as a lazy `Program` for Runtime
 boundaries; the callback form remains supported for compatibility.
 
 `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, and already-started Programs remain owned by the enclosing Runtime
-execution when one returns an error.
+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
@@ -136,6 +271,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:
 
@@ -166,9 +337,38 @@ 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.
+
 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:
+I/O operation supports cancellation. Runtime disposal waits for active work;
+it does not forcibly terminate arbitrary Promises:
 
 ```ts
 const result = await runtime.run(program, { signal: request.signal })
@@ -186,7 +386,9 @@ const result = await runtime.runWith(RequestLive, handleRequest)
 ```
 
 The request Layer may use root Services, while its scoped providers are closed
-with the execution Scope and never change the shared Runtime environment.
+with the execution Scope and never change the shared Runtime environment. Its
+external requirements must be provided by the Runtime, and the Hono failure
+handler/request-Layer types are checked at the adapter boundary.
 
 ### Hono request boundaries
 
@@ -201,7 +403,7 @@ import { Result } from 'better-result'
 import { HonoEffect } from 'better-effect/hono'
 
 const http = HonoEffect.make(runtime, {
-  onFailure: (error, c) => c.json({ error: String(error) }, 400)
+  onFailure: (_error, c) => c.json({ error: 'Request failed' }, 400)
 })
 const app = new Hono()
 
@@ -216,9 +418,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'
@@ -258,12 +460,21 @@ own `Response` when validation fails. `http.handler` accepts the same ordered
 validator arguments followed by the program factory and options.
 
 Install `hono` only when this subpath is used. The main entrypoint does not
-load the framework.
-
-Service and Scope access share one `RuntimeContext`. Node/Bun uses
-`AsyncLocalStorage` by default; hosts without transparent async context can
-pass `contextStorage: new ExplicitRuntimeContextStorage()` from
-`better-effect/runtime/explicit`.
+load the framework. The default Hono failure policy redacts every non-`Response`
+failure value to `{ error: 'Internal Server Error' }` with status 500. An
+explicitly returned `Response` failure is intentionally passed through
+unchanged. A custom `onFailure` policy should serialize only safe, intentional
+domain details.
+
+Service and Scope access share one `RuntimeContext`. The published Runtime
+entrypoint is officially supported on Node.js and Bun, where `AsyncLocalStorage`
+is the default context storage. The `better-effect/runtime/explicit` subpath
+provides `ExplicitRuntimeContextStorage` as a manually managed, sequential
+strategy only when the package entrypoint and host can load it. One instance
+supports one non-overlapping async flow and rejects concurrent overlap. Using
+it does not make the package generally usable in browsers, Deno, Cloudflare
+Workers, or other non-Node hosts; separate explicit instances are not a general
+concurrent-isolation strategy.
 
 If a program asks that Runtime for a Service its environment does not provide, TypeScript rejects the call.
 
@@ -386,7 +597,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(
@@ -400,6 +613,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.
@@ -550,7 +792,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,5 @@
-import { N as AnyServiceToken } from "../index-1NLNdkJy.mjs";
-import "../index-EJlskfAW.mjs";
-import { a as LayerRegistration, n as LayerBackend } from "../map-layer-backend-DMJauecV.mjs";
+import { N as AnyServiceToken } from "../index-heuaRmXR.mjs";
+import { v as LayerBackend, x as LayerRegistration, y as LayerBackendDisposeOptions } from "../index-rQhZk3Nt.mjs";
 //#region src/adapters/iti.d.ts
 /**
  * ITI-backed Layer backend.
@@ -12,13 +11,19 @@ declare class ItiLayerBackend implements LayerBackend {
   private container;
   private readonly keys;
   private readonly registered;
+  /**
+   * Track async gets so disposal cannot reset ITI while a provider is acquiring.
+   * ITI caches rejected acquisitions; replacing the container is the explicit
+   * retry boundary for that sticky failure behavior.
+   */
+  private readonly pending;
   private keyFor;
   /** Register a Layer provider under its deterministic Service-tag key. */
   register(registration: LayerRegistration): void;
   /** Resolve a registered Service through the ITI container. */
   resolve<T extends AnyServiceToken>(token: T): InstanceType<T> | PromiseLike<InstanceType<T>>;
-  /** Dispose all ITI-managed provider instances. */
-  disposeAll(): Promise<void>;
+  /** Reset container-owned ITI state; Scope owns Layer provider releases. */
+  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;UAET;;EAgBR,SAAS,cAAc;;EAuBvB,QAAQ,UAAU,iBAAiB,OAAO,IAAI,aAAa,KAAK,YAAY,aAAa;;EAyBnF,cAAc"}
+{"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"}

package/dist/adapters/iti.mjs

@@ -1,6 +1,6 @@
 import { a as ServiceTagCollisionError, c as ServiceNotFoundError, t as DuplicateServiceError } from "../errors-Dnjhzbt0.mjs";
-import { t as assertServiceCompatibility } from "../internal-identity-DmUpBeeL.mjs";
 import { t as isPromiseLike } from "../runtime-CDcCF5cb.mjs";
+import { t as assertServiceCompatibility } from "../internal-identity-DmUpBeeL.mjs";
 import { createContainer } from "iti";
 //#region src/adapters/iti.ts
 /**
@@ -13,6 +13,12 @@ var ItiLayerBackend = class {
 	container = createContainer();
 	keys = /* @__PURE__ */ new Map();
 	registered = /* @__PURE__ */ new Map();
+	/**
+	* Track async gets so disposal cannot reset ITI while a provider is acquiring.
+	* ITI caches rejected acquisitions; replacing the container is the explicit
+	* retry boundary for that sticky failure behavior.
+	*/
+	pending = /* @__PURE__ */ new Map();
 	keyFor(token) {
 		const tag = token.serviceTag;
 		const existing = this.keys.get(tag);
@@ -42,12 +48,31 @@ var ItiLayerBackend = class {
 			assertServiceCompatibility(token, registered, instance);
 			return instance;
 		};
-		if (isPromiseLike(resolved)) return Promise.resolve(resolved).then(validate);
+		if (isPromiseLike(resolved)) {
+			const pending = Promise.resolve(resolved).then(validate);
+			this.pending.set(pending, registered);
+			pending.then(() => this.pending.delete(pending), () => this.pending.delete(pending));
+			return pending;
+		}
 		return validate(resolved);
 	}
-	/** Dispose all ITI-managed provider instances. */
-	async disposeAll() {
-		await this.container.disposeAll();
+	/** Reset container-owned ITI state; Scope owns Layer provider releases. */
+	async disposeAll(options) {
+		const container = this.container;
+		const acquisitions = [...this.pending.keys()];
+		try {
+			if (acquisitions.length > 0) {
+				const observePending = options?.onPendingAcquisitions;
+				if (observePending) await observePending(acquisitions);
+				await Promise.allSettled(acquisitions);
+			}
+			await container.disposeAll();
+		} finally {
+			this.container = createContainer();
+			this.registered.clear();
+			this.keys.clear();
+			this.pending.clear();
+		}
 	}
 };
 //#endregion

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 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  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      return Promise.resolve(resolved).then(validate)\n    }\n\n    return validate(resolved)\n  }\n\n  /** Dispose all ITI-managed provider instances. */\n  async disposeAll(): Promise<void> {\n    await this.container.disposeAll()\n  }\n}\n"],"mappings":";;;;;;;;;;;AAsBA,IAAa,kBAAb,MAAqD;CACnD,YAAyB,gBAAgB;CAEzC,uBAAwB,IAAI,IAAoB;CAEhD,6BAA8B,IAAI,IAA6B;CAE/D,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,GACxB,OAAO,QAAQ,QAAQ,QAAQ,CAAC,CAAC,KAAK,QAAQ;EAGhD,OAAO,SAAS,QAAQ;CAC1B;;CAGA,MAAM,aAA4B;EAChC,MAAM,KAAK,UAAU,WAAW;CAClC;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'\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"}

package/dist/context-BUEf1qjL.mjs

@@ -0,0 +1,152 @@
+import { t as isPromiseLike } from "./runtime-CDcCF5cb.mjs";
+//#region src/runtime/errors.ts
+/** Thrown when no RuntimeContext is active in the selected storage. */
+var RuntimeContextNotConfiguredError = class extends Error {
+	constructor() {
+		super("No RuntimeContext is available in the current execution context");
+		this.name = "RuntimeContextNotConfiguredError";
+	}
+};
+/** Thrown when ExplicitRuntimeContextStorage cannot safely overlap lineages. */
+var RuntimeContextOverlapError = class extends Error {
+	constructor() {
+		super("ExplicitRuntimeContextStorage does not support overlapping root or derived context runs; use NodeRuntimeContextStorage for concurrent async branches");
+		this.name = "RuntimeContextOverlapError";
+	}
+};
+//#endregion
+//#region src/runtime/context.ts
+const unconfiguredRuntimeContextStorage = {
+	run: (_context, program) => program(),
+	current: () => {
+		throw new RuntimeContextNotConfiguredError();
+	}
+};
+const contextLineages = /* @__PURE__ */ new WeakMap();
+/** Associate a derived context with the root context of its execution lineage. */
+const inheritRuntimeContextLineage = (context, parent) => {
+	const lineage = contextLineages.get(parent) ?? parent;
+	contextLineages.set(context, lineage);
+	return context;
+};
+/** Return the root context associated with a contextual value, when known. */
+const getRuntimeContextLineage = (context) => contextLineages.get(context);
+/** Associate a newly-entered root context with itself. */
+const setRuntimeContextLineage = (context) => {
+	contextLineages.set(context, context);
+	return context;
+};
+const hasPathPrefix = (parent, child) => child.length >= parent.length && parent.every((token, index) => child[index] === token);
+/** Recognize contexts created by a nested Service, Scope, or Layer operation. */
+const isDerivedRuntimeContext = (parent, child) => parent.resolver !== void 0 && child.resolver === parent.resolver && parent.resolutionPath.length > 0 && hasPathPrefix(parent.resolutionPath, child.resolutionPath) && (child.resolutionPath.length > parent.resolutionPath.length || child.scope !== parent.scope);
+function makeRuntimeContext(resolver, scope, resolutionPath, signal, parent) {
+	const context = { resolutionPath };
+	if (resolver !== void 0) Object.assign(context, { resolver });
+	if (scope !== void 0) Object.assign(context, { scope });
+	if (signal !== void 0) Object.assign(context, { signal });
+	if (parent !== void 0) inheritRuntimeContextLineage(context, parent);
+	return context;
+}
+let defaultStorage = unconfiguredRuntimeContextStorage;
+let fallbackFrame;
+const fallbackFrames = /* @__PURE__ */ new Set();
+const settleWithRuntimeStorage = (value, restore) => {
+	let promiseLike;
+	try {
+		promiseLike = isPromiseLike(value);
+	} catch (cause) {
+		restore();
+		throw cause;
+	}
+	if (!promiseLike) {
+		restore();
+		return value;
+	}
+	try {
+		return Promise.resolve(value).then((resolved) => {
+			restore();
+			return resolved;
+		}, (cause) => {
+			restore();
+			throw cause;
+		});
+	} catch (cause) {
+		restore();
+		throw cause;
+	}
+};
+const restoreFallbackFrame = (frame) => {
+	fallbackFrames.delete(frame);
+	if (fallbackFrame !== frame) return;
+	let parent = frame.parent;
+	while (parent !== void 0 && !fallbackFrames.has(parent)) parent = parent.parent;
+	fallbackFrame = parent;
+};
+const fallbackRuntimeContextFrameCarrier = {
+	run(frame, program) {
+		fallbackFrames.add(frame);
+		fallbackFrame = frame;
+		const restore = () => restoreFallbackFrame(frame);
+		try {
+			return settleWithRuntimeStorage(program(), restore);
+		} catch (cause) {
+			restore();
+			throw cause;
+		}
+	},
+	current: () => fallbackFrame
+};
+let runtimeContextFrameCarrier = fallbackRuntimeContextFrameCarrier;
+/** Install host async-context propagation for Runtime context frames. */
+const setRuntimeContextFrameCarrier = (carrier) => {
+	runtimeContextFrameCarrier = carrier;
+};
+/** Return whether a host async-context carrier has been installed. */
+const isRuntimeContextFrameCarrierInstalled = () => runtimeContextFrameCarrier !== fallbackRuntimeContextFrameCarrier;
+/** Return the frame associated with the executing callback. */
+const currentRuntimeContextFrame = () => runtimeContextFrameCarrier.current();
+/** Install the host default used by the main Runtime entrypoint. */
+const setDefaultRuntimeContextStorage = (storage) => {
+	defaultStorage = storage;
+};
+/** Return the storage currently associated with the executing callback. */
+const activeRuntimeContextStorage = () => currentRuntimeContextFrame()?.storage ?? defaultStorage;
+/** Return the active context, or undefined when the storage has not been entered. */
+const getRuntimeContext = (storage = activeRuntimeContextStorage()) => {
+	const frame = currentRuntimeContextFrame();
+	if (frame?.storage === storage) return frame.context;
+	try {
+		return storage.current();
+	} catch (cause) {
+		if (cause instanceof RuntimeContextNotConfiguredError) return;
+		throw cause;
+	}
+};
+/** Return the active context or throw the storage's standard missing-context error. */
+const currentRuntimeContext = () => {
+	return currentRuntimeContextFrame()?.context ?? defaultStorage.current();
+};
+/** Keep a storage discoverable to Service and Scope compatibility bridges. */
+const withActiveRuntimeContextStorage = (storage, context, program) => {
+	const current = currentRuntimeContextFrame();
+	if (current?.storage === storage && current.context === context) return program();
+	const frame = current === void 0 ? {
+		storage,
+		context
+	} : {
+		storage,
+		context,
+		parent: current
+	};
+	return runtimeContextFrameCarrier.run(frame, program);
+};
+/** Run a callback in a context while keeping the selected storage discoverable to bridges. */
+const runRuntimeContext = (storage, context, program) => {
+	const current = getRuntimeContext(storage);
+	const contextual = current !== void 0 && isDerivedRuntimeContext(current, context) ? inheritRuntimeContextLineage(context, current) : context;
+	return storage.run(contextual, () => withActiveRuntimeContextStorage(storage, contextual, program));
+};
+//#endregion
+export { getRuntimeContextLineage as a, isRuntimeContextFrameCarrierInstalled as c, setDefaultRuntimeContextStorage as d, setRuntimeContextFrameCarrier as f, RuntimeContextOverlapError as g, RuntimeContextNotConfiguredError as h, getRuntimeContext as i, makeRuntimeContext as l, withActiveRuntimeContextStorage as m, currentRuntimeContext as n, inheritRuntimeContextLineage as o, setRuntimeContextLineage as p, currentRuntimeContextFrame as r, isDerivedRuntimeContext as s, activeRuntimeContextStorage as t, runRuntimeContext as u };
+
+//# sourceMappingURL=context-BUEf1qjL.mjs.map