better-effect 0.12.0 → 0.14.0

package/README.md

@@ -11,8 +11,8 @@ 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. `bun run check` also deletes
+The repository uses the latest Bun release by default and the current Node.js
+LTS for interoperability smoke tests. `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.
 
@@ -149,6 +149,61 @@ const inspectDatabase = Effect.fn(async function* () {
 await runtime.run(inspectDatabase)
 ```
 
+Integration authors that need to trigger work later can capture the Runtime's
+non-owning executor capability from an execution or Layer acquisition:
+
+```ts
+const captureExecutor = Effect.fn(async function* () {
+  const executor = yield* Runtime.executor<Database>()
+  return Result.ok(executor)
+})
+
+const executor = (await runtime.run(captureExecutor)).unwrap()
+await executor.run(inspectDatabase)
+```
+
+`Runtime.Executor<R>` exposes `run`, `runWith`, and the opt-in
+`runWithManaged` capability. The first two start a child execution and resolve
+after its Scope closes; `runWithManaged` additionally separates readiness from
+completion for boundaries such as `WebEffect.streamWith`, while keeping the
+same request-local Services and Scope active until completion. The executor
+does not expose `dispose`, `warmup`, `inspect`, backend or Scope ownership.
+Applications normally use `runtime.run`; the contextual executor is mainly for
+framework adapters and long-lived components.
+
+For work that must live only as long as the current execution or lifecycle
+Scope, use `Effect.forkScoped`. It returns immediately with a small task handle;
+the task inherits the current Services and resolver, receives its own
+cooperative-cancellation signal, and is interrupted and awaited before the
+parent Scope releases its resources:
+
+```ts
+const pollOutbox = Effect.fn(async function* () {
+  const signal = yield* CurrentAbortSignal
+
+  while (!signal.aborted) {
+    await pollOnce()
+  }
+
+  return Result.ok(undefined)
+})
+
+const OutboxLive = Layer.effectDiscard(
+  Effect.fn(async function* () {
+    const task = yield* Effect.forkScoped(pollOutbox)
+    await task.awaitExit()
+
+    return Result.ok(undefined)
+  })
+)
+```
+
+Use `task.await()` when the child Result should be returned or its defect should
+be thrown. Use `task.awaitExit()` when interruption and defects must be
+inspected without throwing. `Runtime.inspect()` reports active scoped tasks,
+and Runtime observers receive task start/end events linked to their parent
+execution; scoped tasks do not create independent Runtime executions.
+
 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
@@ -344,9 +399,13 @@ 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. Execution events
-carry one matching `executionId`, the optional Program name, copied readonly
-attributes, and a monotonic `durationMs` measured through execution cleanup:
+events without coupling the core to an observability SDK. Service events carry
+an optional matching `executionId` only when they occur inside an active
+execution; warmup and Runtime-root activity omit it. Execution events carry one
+matching `executionId`, the optional Program name, copied readonly attributes,
+and a monotonic `durationMs` measured through execution cleanup. An end event
+keeps the primary program `outcome` and adds `cleanupFailure` when execution
+Scope cleanup fails:
 
 ```ts
 const runtime = await Runtime.make(AppLive, {
@@ -389,11 +448,12 @@ 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`.
+`active`, `quiescing`, `draining`, `aborting`, `releasing` 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.
+New executions are rejected as soon as quiescing begins.
 
 Missing, circular, and provider-construction failures use the logical Service
 tags in `ServiceNotFoundError`, `CircularDependencyError`, and
@@ -438,6 +498,108 @@ 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.
 
+### Optional OpenTelemetry tracing
+
+Install the OpenTelemetry API only when this subpath is used:
+
+```bash
+bun add better-effect @opentelemetry/api
+```
+
+`better-effect/opentelemetry` accepts either an existing `Tracer` or an existing
+`TracerProvider`. Its supported `@opentelemetry/api` peer range is
+`>=1.9.0 <1.10.0` (tested with 1.9.1). It never installs a global provider, SDK,
+context manager or exporter. The provider form only calls `getTracer`:
+
+```ts
+import { trace } from '@opentelemetry/api'
+import { OpenTelemetryRuntimeObserver } from 'better-effect/opentelemetry'
+
+const observer = OpenTelemetryRuntimeObserver.make({
+  // An existing provider can be passed instead with `provider` and `tracerName`.
+  tracer: trace.getTracer('acme.application'),
+  serviceResolution: 'events',
+  lifecycle: 'events',
+  shutdown: 'events',
+  recordFailures: true,
+  executionAttributeAllowlist: ['requestId'],
+  sanitizeFailure: (cause) =>
+    cause instanceof KnownDomainError ? { message: cause.code } : undefined
+})
+
+const runtime = await Runtime.make(AppLive, { observers: [observer] })
+```
+
+The same observer can be passed to `NodeRuntime.runMain` or
+`NodeRuntime.launch`. Executions started through `runtime.executor.run` and
+`runtime.executor.runWith` use the same execution pipeline and produce one
+execution span each; capturing an executor never creates a separate span.
+
+The adapter starts one span for each execution, keyed only by the Runtime's
+`executionId`. The Program name is the span name, with
+`better-effect.execution` as the stable fallback. Executions whose program and
+execution cleanup succeed use OpenTelemetry `OK`; typed `Result.err` values,
+thrown defects and execution cleanup failures use `ERROR`. The Runtime observer
+keeps cleanup failure separate from the primary program outcome, so the adapter
+can report the final execution status without turning cleanup into a program
+defect or serializing its cause by default.
+Span timing is supplied by OpenTelemetry's start/end clock; `durationMs` is not
+written as a second duration source.
+
+Service telemetry is explicit and defaults to `off`:
+
+- `off` creates no Service telemetry.
+- `events` adds resolution, acquisition and release events to an execution span
+  only when the Runtime event carries an explicit active execution ID. Warmup,
+  Runtime-root cleanup and other events without an owner use standalone spans.
+- `spans` creates child Service spans only for events with an explicit active
+  execution ID. Warmup and Runtime-root cleanup are represented by standalone
+  service spans (or generic event-carrier spans in `events` mode); ambient
+  OpenTelemetry context is never used to guess ownership.
+
+Service identity is always the logical `serviceTag`; constructor names and
+Service instances are never used. `RuntimeObserver.compose` can combine this
+adapter with recorded, graph and application observers, and a tracer failure is
+isolated from every Runtime result. Call `observer.dispose()` when an observer
+may outlive its Runtime to end state left by malformed or missing end events;
+normal execution spans are ended exactly once by their matching `executionId`.
+
+Lifecycle and shutdown telemetry are also explicit and default to `off`:
+
+- `lifecycle: 'events'` records activation and release on one
+  `better-effect.lifecycle` span; `lifecycle: 'spans'` creates phase spans
+  named `better-effect.lifecycle.activate` and
+  `better-effect.lifecycle.release`.
+- The public Runtime observer currently exposes lifecycle activation and
+  release, but not a per-entry quiesce callback. The adapter does not invent a
+  quiesce event; Runtime shutdown quiesce phases remain available through
+  `onShutdown`.
+- `shutdown: 'events'` records the public shutdown phases as events on one
+  root `better-effect.shutdown` span. `shutdown: 'spans'` keeps that root span
+  and adds bounded phase spans for quiesce, drain, abort and release.
+- Shutdown spans use an explicit root parent, never an arbitrary active
+  execution span. Shutdown failure marks the root span as `ERROR`; failure
+  details are recorded only when `recordFailures: true` and `sanitizeFailure`
+  returns them.
+
+All lifecycle and shutdown metadata is bounded and excludes resource
+instances, server handles, configuration, payloads and raw causes.
+
+Telemetry is privacy-preserving by default. The adapter records only bounded
+library, execution ID, Program/outcome, Service-tag and resolution-path data.
+It does not record causes, stacks, requests, arbitrary execution attributes or
+Service instances, and it never stringifies unknown values. Add attributes only
+through `executionAttributeAllowlist` or the explicit
+`sanitizeExecutionAttributes` callback; add failure details only through
+`sanitizeFailure` together with `recordFailures: true`. Unsupported values are
+dropped, strings are bounded, and default limits are 256 characters, 32
+attributes and 16 resolution-path tags (caller limits remain capped). Sanitizer
+callbacks should return only intentional scalar OpenTelemetry attributes.
+
+For distributed tracing, establish the caller's OpenTelemetry context before
+calling `runtime.run`; the adapter does not propagate context or instrument
+HTTP/database libraries automatically.
+
 For a startup view of the graph actually observed by a Runtime, compose the
 small graph observer and warm the Layer before accepting work:
 
@@ -476,9 +638,9 @@ 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:
+`NodeRuntime.runMain` validates its signal, callback and shutdown 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'
@@ -493,7 +655,11 @@ await NodeRuntime.runMain(AppLive, main, {
     console.error(error)
     return 1
   },
-  onSuccess: () => 0
+  onSuccess: () => 0,
+  shutdown: {
+    gracePeriod: 10_000,
+    abortAfterGracePeriod: true
+  }
 })
 ```
 
@@ -501,11 +667,21 @@ await NodeRuntime.runMain(AppLive, main, {
 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.
+immediately aborts `CurrentAbortSignal`; Runtime disposal then quiesces root
+resources and applies the configured drain policy. Listeners are removed in
+`finally`, repeated signals are ignored, and the helper never calls
+`process.exit()`.
+
+For long-lived applications whose startup and shutdown are completely
+represented by a Layer graph, `NodeRuntime.launch` owns the Runtime and waits
+for a process signal or caller `AbortSignal`:
+
+```ts
+await NodeRuntime.launch(AppLive, {
+  warmup: true,
+  shutdown: { gracePeriod: 10_000, abortAfterGracePeriod: true }
+})
+```
 
 For request-local context or overrides, add a Layer only to that execution:
 
@@ -518,32 +694,366 @@ 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.
 
+### Framework-neutral Web request boundaries
+
+The `better-effect/web` entrypoint provides a small Request-to-Response
+boundary without depending on Hono or another framework. Use it anywhere a
+framework gives you standard Web `Request` and `Response` values:
+
+```ts
+import { Result } from 'better-result'
+import { CurrentAbortSignal, Effect } from 'better-effect'
+import { CurrentRequest } from 'better-effect/standard-services'
+import { WebEffect } from 'better-effect/web'
+
+const handleRequest = (request: Request) =>
+  WebEffect.handleWith(
+    runtime.executor,
+    request,
+    Effect.fn(async function* () {
+      const currentRequest = yield* CurrentRequest
+      const signal = yield* CurrentAbortSignal
+      const user = yield* UserService
+      const result = yield* Result.await(user.find())
+
+      return Result.ok({
+        result,
+        url: (currentRequest.request as Request).url,
+        aborted: signal.aborted
+      })
+    })
+  )
+```
+
+`WebEffect.handleWith` supplies `CurrentRequest`, forwards `request.signal`, and
+runs one lazy Program in a child Scope. Request-local resources are released
+before the returned Promise resolves; Runtime-root resources remain owned by
+the Runtime. A `requestLayer` option can add per-request providers or
+intentionally override a compatible request tag.
+
+The default success policy passes through a Web `Response`, maps top-level
+`undefined` to 204, and wraps supported values as `{ data: value }` JSON. A
+non-`undefined`, non-`Response` value must be an acyclic graph of `null`,
+booleans, strings, finite numbers, dense arrays, and plain object records.
+Arrays must have only the own string properties `length` and one property for
+each index from `0` through `length - 1`; each index must be an enumerable data
+property. Symbol keys, extra own properties (including non-enumerable ones),
+sparse holes, and accessor elements are rejected. Object records must have
+`Object.prototype` or `null` as their prototype, and every own string-keyed
+property must be an enumerable data property. Own symbol keys,
+non-enumerable properties, accessors, custom prototypes, and other non-plain
+objects are rejected. Shared references in separate branches are serialized as
+repeated values. Nested `undefined`, `bigint`, functions, symbols, and
+non-finite numbers (`NaN` and infinities) are rejected with
+`WebEffectSerializationError` (a `TypeError`) instead of being silently dropped
+or coerced. Use an explicit `onSuccess` policy for other representations. The
+default failure policy passes through a standards-compatible `Response`
+failure and redacts every other typed failure to `{ error: 'Internal Server Error' }`
+with status 500. Custom
+`onSuccess`/`onFailure` policies may be asynchronous but must return a
+standards-compatible `Response`. The boundary checks that protocol structurally:
+`status` is an integer in `0` or `200` through `599`, `ok` matches the 2xx
+status range, `redirected` and `bodyUsed` are booleans, `statusText` and `url`
+are strings, `type` is a standard Response type, and
+`arrayBuffer()`, `blob()`, `bytes()`, `clone()`, `formData()`, `json()`, and
+`text()` are callable. `headers` must provide callable `append()`, `delete()`,
+`get()`, `getSetCookie()`, `has()`, `set()`, and `forEach()` operations. `body`
+must be `null` (including legitimate null-body Responses such as `204`) or a
+ReadableStream-compatible object with a boolean `locked` property and callable
+`cancel()`, `getReader()`, `pipeThrough()`, `pipeTo()`, and `tee()` methods.
+Native cross-realm Responses and other values satisfying this protocol are
+accepted without `instanceof Response`; missing capabilities and forged
+`Response.prototype` values fail with `TypeError`. Thrown defects remain
+rejected. The Program's Service and failure channels, request-Layer
+requirements, and override compatibility are checked at the TypeScript
+boundary.
+
+For a response whose body is still produced by request-scoped work, opt in to
+the managed streaming boundary with an explicit descriptor. The descriptor's
+metadata is committed immediately, while its lazy producer is pulled with
+backpressure in the same execution context:
+
+```ts
+const response = await WebEffect.streamWith(
+  runtime.executor,
+  request,
+  Effect.fn(async function* () {
+    const file = yield* FileService
+
+    return Result.ok<WebEffect.Stream>({
+      status: 200,
+      headers: { 'content-type': 'application/octet-stream' },
+      producer: async function* ({ signal }) {
+        yield* file.bytes({ signal })
+      }
+    })
+  }),
+  { unconsumedTimeoutMs: 30_000 }
+)
+```
+
+`WebEffect.streamWith` retains the request execution until EOF, downstream
+cancel/error, request abort, timeout, or Runtime shutdown. It accepts only the
+explicit descriptor—not an arbitrary `Response`—and never maps failures to a
+new status after headers have been committed.
+
+### Next.js App Router request boundaries
+
+The optional `better-effect/next` entrypoint adapts an application-owned
+Runtime to native Next.js App Router Route Handlers without importing Next.js
+from the core or main entrypoint:
+
+```ts
+import { Result } from 'better-result'
+import { Effect, Layer, Service } from 'better-effect'
+import { NextEffect } from 'better-effect/next'
+
+class UserService extends Service<UserService>()('UserService') {
+  find(id: string) {
+    return { id, name: 'Ada' }
+  }
+}
+
+const http = NextEffect.managed(Layer.make(UserService))
+
+export const GET = http.gen(async function* (_request, context: RouteContext<'/api/users/[id]'>) {
+  const { id } = await context.params
+  const users = yield* UserService
+
+  return Result.ok(users.find(id))
+})
+```
+
+Managed builders' `gen` and `handler` methods return the native
+`(request, context) => Promise<Response>` shape expected by App Router route
+files. The context is typed with Next's asynchronous `params`; `handler` is
+useful when the complete `Effect.fn` Program already exists.
+
+`managed` is lazy and host-owned: each manager creates at most one Runtime,
+shares concurrent first-request initialization, and keeps root Layer resources
+until explicit disposal. It never installs process signal handlers or creates a
+Runtime per request:
+
+```ts
+// app/runtime.ts
+export const appNext = NextEffect.managed(AppLive, {
+  runtime: { warmup: true }
+})
+
+// Call this from the actual host/server shutdown hook.
+export const initializeApp = (): Promise<void> => appNext.initialize()
+export const disposeApp = (): Promise<void> => appNext.dispose()
+```
+
+Route modules import the manager directly:
+
+```ts
+// app/api/users/[id]/route.ts
+import { appNext } from '@/app/runtime'
+
+export const GET = appNext.gen(async function* (
+  _request,
+  context: RouteContext<'/api/users/[id]'>
+) {
+  const { id } = await context.params
+  const users = yield* UserService
+
+  return Result.ok(users.find(id))
+})
+```
+
+For code already being built inside a better-effect Runtime, use the inert
+`fromCurrent` builder. Its `handler` and `gen` operations are yieldable, so
+route requirements become requirements of the surrounding Program:
+
+```ts
+const next = NextEffect.fromCurrent()
+
+const makeRoutes = Effect.fn(async function* () {
+  const GET = yield* next.gen(async function* (_request, context) {
+    const { id } = await context.params
+    const users = yield* UserService
+    return Result.ok(users.find(id))
+  })
+
+  return Result.ok(GET)
+})
+```
+
+`fromCurrent` does not create or own a Runtime and fails explicitly outside an
+active Runtime execution. `managed` is the App Router/module-scope mode. The
+adapter does not promise automatic HMR cleanup, Edge-runtime compatibility, or
+ownership of workers and other ingress resources in the supplied Layer.
+
+Each request creates one WebEffect execution and child Scope, installs
+`CurrentRequest` and `CurrentAbortSignal`, and releases request-local Layers
+before the handler Promise resolves. The request's
+`AbortSignal` is linked into the execution signal, and concurrent requests keep
+request Layers and context isolated.
+
+The default success policy passes through a returned `Response`; other values
+are encoded as `{ data: value }` JSON using the same strict serialization rules
+as `better-effect/web`. A route may select at most one success policy:
+`respond` handles a complete Response, `serialize` transforms a JSON-safe
+value, and route-level `onSuccess` replaces the shared success policy. Shared
+`onSuccess` and `onFailure` policies receive the native Request and route
+context. Typed
+`Result.err` failures use `onFailure` (or the redacted 500 default), while
+thrown defects remain rejected. Policies must return a standards-compatible
+`Response` and may be asynchronous. This adapter does not add Edge-runtime
+support; use it only in hosts supported by the configured better-effect
+Runtime.
+
+Install Next.js only when this subpath is used:
+
+```bash
+bun add better-effect better-result next
+```
+
+`next` is an optional peer dependency, and `better-effect/next` uses only the
+public native Route Handler shape, so the core and other entrypoints remain
+usable without Next.js.
+
+### Bun.serve fetch adapter
+
+For Bun applications, `better-effect/bun` is Layer-first. `BunEffect.handler`
+is a yieldable operation: it captures the active `Runtime.Executor` while its
+enclosing Layer is acquired, then uses that executor for each request.
+
+`BunEffect.server` owns one native `Bun.serve` instance in its `.layer`. The
+server is quiesced during Runtime shutdown, active executions are drained, and
+the same server stop Promise is awaited during release. There is no parallel
+Runtime or import-time server startup:
+
+```ts
+import { Result } from 'better-result'
+import { CurrentAbortSignal, Effect, Layer, Runtime, Service, ServiceRuntime } from 'better-effect'
+import { CurrentRequest } from 'better-effect/standard-services'
+import { BunEffect } from 'better-effect/bun'
+
+class AppService extends Service<AppService>()('AppService') {
+  handle(url: string) {
+    return url
+  }
+}
+
+const ApiServer = BunEffect.server('@app/ApiServer', async function* () {
+  const fetch = yield* BunEffect.handler(
+    {
+      onFailure: (_error, request) =>
+        Response.json({ error: 'Request failed', url: request.url }, { status: 500 })
+    },
+    (request, server) =>
+      Effect.fn(async function* () {
+        const app = yield* AppService
+        const currentRequest = yield* CurrentRequest
+        const signal = yield* CurrentAbortSignal
+
+        return Result.ok({
+          value: app.handle(request.url),
+          currentUrl: (currentRequest.request as Request).url,
+          port: server.port,
+          aborted: signal.aborted
+        })
+      })
+  )
+
+  return { port: 3000, fetch }
+})
+
+const runtime = await Runtime.make(Layer.merge(Layer.make(AppService), ApiServer.layer))
+const server = await runtime.run(() => ServiceRuntime.resolve(ApiServer))
+```
+
+`BunEffect.handler` invokes exactly one `WebEffect` request boundary. It
+supplies `CurrentRequest`, forwards the request signal to
+`CurrentAbortSignal`, composes request-local Layers, applies success/failure
+policies, keeps thrown defects rejected, and releases request resources before
+the handler Promise resolves.
+
+For an application-chosen server Service, use `BunEffect.layer(service,
+factory)`. Its factory returns `{ options, map }`; the adapter maps the one
+native server into your Service while retaining the same Runtime lifecycle.
+`BunEffect.server` is the convenience form whose Service is the raw
+`Bun.Server<Data>`.
+
+Dispose the Runtime once during application shutdown. It stops accepting new
+connections, drains active requests, then releases the server and root Layers;
+repeated disposal calls share one Promise:
+
+```ts
+await runtime.dispose()
+```
+
+This Bun-specific entrypoint makes no Node compatibility claim.
+
 ### Hono request boundaries
 
-The optional `better-effect/hono` entrypoint runs one Runtime execution and
-Scope around each request. Handlers can yield Services directly; the adapter
-provides `CurrentRequest`, forwards `Request.signal`, and converts Results to
-Responses in one policy:
+The optional `better-effect/hono` entrypoint supplies Hono's middleware,
+validator, and Context integration around the same Web request boundary used
+by `better-effect/web`. It adapts Hono's Context to a standard Web `Request`,
+then delegates the single `Runtime` execution, Result/defect handling, and
+request Scope cleanup to that shared boundary. You only need to configure one
+Hono middleware boundary per request; the adapter prevents duplicate
+registrations from opening another execution.
+
+`HonoEffect.app` creates a yieldable application Service and its `.layer`. The
+factory is acquired once when the application Layer is resolved, so the host
+owns Runtime composition and shutdown. Handlers can yield Services directly;
+the adapter provides `CurrentRequest`, forwards `Request.signal`, and converts
+Results to Responses in one policy:
 
 ```ts
 import { Hono } from 'hono'
+import { Effect, Layer, Runtime } from 'better-effect'
 import { Result } from 'better-result'
 import { HonoEffect } from 'better-effect/hono'
 
-const http = HonoEffect.make(runtime, {
-  onFailure: (_error, c) => c.json({ error: 'Request failed' }, 400)
-})
-const app = new Hono()
+const App = HonoEffect.app(
+  '@app/HonoApp',
+  {
+    onFailure: (_error, c) => c.json({ error: 'Request failed' }, 400)
+  },
+  async function* (http) {
+    const app = new Hono()
+
+    app.use('*', yield* http.middleware())
+    app.get(
+      '/work-orders',
+      yield* http.gen(async function* () {
+        const workOrders = yield* WorkOrderService
+        const items = yield* Result.await(workOrders.list())
+        return Result.ok(items)
+      })
+    )
+
+    return app
+  }
+)
 
-app.use('*', http.middleware())
-app.get(
-  '/work-orders',
-  http.gen(async function* () {
-    const workOrders = yield* WorkOrderService
-    const items = yield* Result.await(workOrders.list())
-    return Result.ok(items)
+const runtime = await Runtime.make(Layer.merge(AppLive, App.layer))
+const appResult = await runtime.run(
+  Effect.fn(async function* () {
+    return Result.ok(yield* App)
   })
 )
+if (Result.isError(appResult)) throw new Error(String(appResult.error))
+const app = appResult.value
+```
+
+Route examples below belong inside the `HonoEffect.app` factory. For an
+existing application Service, use `HonoEffect.layer(ServiceToken, options,
+factory)` and compose the returned Layer with the Runtime's other Layers.
+
+Use `HonoEffect.layer` when the application should be provided through an
+existing Service token instead of a generated one:
+
+```ts
+const AppLive = HonoEffect.layer(MyApplication, {}, async function* (http) {
+  const app = new Hono()
+  app.use('*', yield* http.middleware())
+  return MyApplication.of({ app })
+})
 ```
 
 One or more Hono validators can precede the generator or handler callback, in
@@ -664,6 +1174,47 @@ low-level provider metadata names.
 `Layer.complete(layer)` is a runtime identity that checks a composition root
 immediately, so missing Services are reported where the Layer is assembled.
 
+### Lifecycle-only Layers
+
+Use `Layer.scopedDiscard` for application components that need startup and
+shutdown ownership but are not themselves a Service:
+
+```ts
+const PollerLive = Layer.scopedDiscard(
+  () => startPoller(),
+  (poller, outcome) => poller.stop(outcome)
+)
+
+const ServerLive = Layer.scopedDiscard(() => startServer(), {
+  quiesce: (server) => server.stopAccepting(),
+  release: (server, outcome) => server.close(outcome)
+})
+
+const AppLive = Layer.complete(Layer.merge(ConfigLive, PollerLive))
+```
+
+The acquisition runs once when `Runtime.make` activates the Layer, after
+provider registration and optional warmup. The release belongs to the Runtime
+root Scope, runs in reverse activation order, and receives the final
+`ScopeOutcome`. A contextual acquisition can use `yield*` with
+`Layer.scopedDiscard` (or the explicit `Layer.scopedDiscardGen`) and retains
+those Service requirements even though the Layer provides `never`:
+
+```ts
+const PollerLive = Layer.scopedDiscard(
+  async function* () {
+    const config = yield* Config
+    return startPoller(config)
+  },
+  (poller, outcome) => poller.stop(outcome)
+)
+```
+
+For startup programs, `Layer.effectDiscard` accepts only
+`Effect.Program<void, never, R>`-compatible programs. A typed failure must be
+handled by the program before it is made a lifecycle entry; it is not silently
+converted into a Runtime defect.
+
 ---
 
 ## Why better-effect?
@@ -910,6 +1461,24 @@ Use `Config.schema(schema)` with `Config.layer(source)` or
 `Config.layerFromEnv(options)` when several descriptors should share an
 explicitly replaceable provider.
 
+When configuration should be consumed through a Service token, bind the schema
+to that token so `get` only accepts keys from the decoded schema output:
+
+```ts
+const AppConfig = Config.withSchema(EnvSchema)
+const AppConfigLive = AppConfig.layerFromEnv({ dotEnvPath: '.env' })
+
+const program = Effect.fn(async function* () {
+  const config = yield* AppConfig
+  return Result.ok(config.get('DATABASE_URL'))
+  //             ^ autocomplete is restricted to EnvSchema output keys
+})
+```
+
+`config.get(...)` reads the validated schema output, with the value type inferred
+from the selected key. Use `Config.schema(schema)` or
+`Config.fromEnv({ schema })` when the complete transformed output is needed.
+
 ---
 
 ## How it compares