@danieljvdm/dev-kit 0.2.0

package/skills/effect-ts/references/guide-layers.md

@@ -0,0 +1,1017 @@
+# Layers Guide
+
+This guide covers service ownership, service design, Layer construction,
+dependency visibility, composition, and provisioning.
+
+Key source files:
+
+- `packages/effect/src/Context.ts`
+- `packages/effect/src/Layer.ts`
+- `packages/effect/src/Effect.ts`
+- `packages/effect/src/ManagedRuntime.ts`
+
+## Mental Model
+
+A service is a typed dependency.
+
+A layer is a recipe for building one or more services, possibly using other services as dependencies.
+
+Effect's model is:
+
+- define service identifiers with `Context.Service` or `Context.Service(...)`
+- require services from effects with `Effect.service` or by yielding the service key directly
+- build implementations with `Layer`
+- provide layers at the program boundary or subsystem boundary
+
+`Layer<ROut, E, RIn>` means:
+
+- `ROut`: services produced by the layer
+- `E`: possible failures while constructing the layer
+- `RIn`: dependencies required to build it
+
+Repo references:
+
+- `packages/effect/src/Context.ts`
+- `packages/effect/src/Layer.ts`
+
+## Service Or Value Decision
+
+Treat a service as an authority seam: a cohesive capability whose requirements
+should propagate through the Effect environment.
+
+Create or retain a service when it owns persistence, credentials, external I/O,
+runtime resources, configuration, time, randomness, lifecycle, reusable
+effectful policy, or state with meaningful production and test variation.
+Prefer an existing Effect capability such as `Clock`, `Config`, `Random`,
+`HttpClient`, `FileSystem`, or `Path` when it already owns that authority.
+
+Keep parsed inputs, per-call request data, deterministic calculations,
+adapter-confined framework values, and forwarding wrappers as values or pure
+modules.
+
+Use the deletion test: if removing the service merely eliminates indirection,
+it is probably not an authority seam; if removal spreads resource ownership,
+policy, or implementation complexity into callers, it probably is. Test
+convenience by itself does not justify a service.
+
+## Services
+
+## What A Service Is
+
+A service is a typed key plus its implementation shape.
+
+In Effect, services are values in `Context`, not global singletons.
+
+This gives you:
+
+- explicit dependencies
+- easy substitution in tests
+- layer-based composition
+- multiple implementations for the same interface
+
+## Preferred Service Definition Style
+
+Prefer the class syntax with `Context.Service`.
+
+This matches the canonical source's current style.
+
+There are two good definition styles:
+
+- explicit service shape in the `Context.Service<...>` generic
+- inferred service shape from the `make` argument
+
+Example:
+
+```ts
+import { Context, Effect, Schema } from "effect"
+
+class UserRepoError extends Schema.TaggedErrorClass<UserRepoError>()(
+  "UserRepoError",
+  {
+    message: Schema.String
+  }
+) {}
+
+class UserRepo extends Context.Service<UserRepo, {
+  readonly getById: (id: string) => Effect.Effect<{ id: string; name: string }, UserRepoError>
+}>()("UserRepo") {}
+```
+
+Why this style is preferred:
+
+- the service identifier and shape live in one place
+- it works naturally with `yield* UserRepo`
+- it matches the patterns used across canonical `Effect-TS/effect` source
+
+Keep the tag and implementation layer together when one module owns both. If
+the application owns a port and a technology adapter owns its implementation,
+keep the contract beside the application operation and concrete construction
+in the adapter module.
+
+Prefer a static lowercase `layer` for the default implementation unless the
+repository already has a consistent `Live` convention. Use `layerNoDeps` when
+calling out dependency-free construction is useful. Avoid splitting
+`foo-service.ts` and `foo-service-live.ts` before there is a real ownership
+boundary.
+
+Repo reference:
+
+- `packages/effect/src/Context.ts`
+
+## Service Shape Inference With `make`
+
+When the implementation shape is clearer than the interface declaration, prefer using the `make` argument so the service shape is inferred from the implementation.
+
+```ts
+import { Context, Effect, Schema } from "effect"
+
+class UserRepoError extends Schema.TaggedErrorClass<UserRepoError>()(
+  "UserRepoError",
+  {
+    message: Schema.String
+  }
+) {}
+
+class UserRepo extends Context.Service<UserRepo>()("UserRepo", {
+  make: Effect.succeed({
+    getById: Effect.fn("UserRepo.getById")(function*(id: string) {
+      return yield* Effect.fail(
+        UserRepoError.make({ message: `User ${id} not found` })
+      )
+    })
+  })
+}) {}
+```
+
+Why this style is useful:
+
+- the implementation and inferred API stay together
+- TypeScript derives the service shape automatically
+- it avoids repeating the same method signatures twice
+
+Prefer this style when:
+
+- the implementation is small and obvious
+- the explicit service shape would only duplicate the implementation
+
+Prefer the explicit generic shape when:
+
+- you want the contract stated before the implementation
+- the API surface should be emphasized separately from the implementation
+
+## Service Example
+
+```ts
+import { Context, Effect, Schema } from "effect"
+
+class UserNotFound extends Schema.TaggedErrorClass<UserNotFound>()(
+  "UserNotFound",
+  {
+    userId: Schema.String
+  }
+) {}
+
+class UserRepo extends Context.Service<UserRepo, {
+  readonly getById: (id: string) => Effect.Effect<{ id: string; name: string }, UserNotFound>
+}>()("UserRepo") {}
+
+const loadUser = (userId: string) =>
+  Effect.gen(function*() {
+    const repo = yield* UserRepo
+    return yield* repo.getById(userId)
+  })
+```
+
+Key points:
+
+- `UserRepo` is both the identifier and a value you can yield from `Effect.gen`
+- the implementation shape is explicit in the service definition
+- the effect that uses it stays abstract over the implementation
+
+## When To Use `Context.Reference`
+
+Use `Context.Reference` for contextual values with defaults, not for full service APIs.
+
+Good use cases:
+
+- current configuration knobs
+- current request metadata
+- feature flags or tracing flags with defaults
+
+Repo reference:
+
+- `packages/effect/src/Context.ts`
+
+Use a full service instead when:
+
+- behavior matters more than data
+- you need multiple methods
+- you want a concrete test double or alternate implementation
+
+## Accessing Services
+
+Common patterns:
+
+```ts
+const program = Effect.gen(function*() {
+  const repo = yield* UserRepo
+  return yield* repo.getById("u_123")
+})
+```
+
+or:
+
+```ts
+const program = Effect.service(UserRepo).pipe(
+  Effect.flatMap((repo) => repo.getById("u_123"))
+)
+```
+
+Best practice:
+
+- use `yield* Service` or `Effect.service(Service)` inside business logic
+- do not manually thread service implementations through function arguments when they are real application dependencies
+
+## Service Encapsulation
+
+Prefer keeping service access inside the business operation that needs it rather than exporting thin accessor wrappers for every method.
+
+Avoid this pattern:
+
+```ts
+export const createTodo = Effect.fn(function*(title: string) {
+  const todos = yield* TodoService
+  return yield* todos.create(title)
+})
+```
+
+Why this is usually a bad pattern:
+
+- it leaks the service dependency into a second public API layer
+- it encourages a redundant accessor function per service method
+- it spreads dependency access patterns across the codebase
+- it weakens service encapsulation instead of improving it
+
+Prefer one of these patterns instead:
+
+1. Put the real business logic in a function that uses the service internally because it adds behavior beyond simple forwarding.
+2. Expose the service itself and call its methods from the module that owns the workflow.
+3. If you need a public operation, make it a real business operation, not a trivial alias of one service method.
+
+Good:
+
+```ts
+export const completeTodo = Effect.fn("completeTodo")(function*(id: number) {
+  const todos = yield* TodoService
+  const todo = yield* todos.getById(id)
+  if (todo.completed) {
+    return todo
+  }
+  return yield* todos.setCompleted(id, true)
+})
+```
+
+This is good because:
+
+- the exported function represents a business operation
+- the service remains an internal dependency of that operation
+- the function adds behavior rather than just forwarding one method call
+
+## Domain-Specific Service Abstractions
+
+When a repository provides a stronger domain-specific `Tag` helper, prefer it
+over plain `Context.Service`. The helper should wrap `Context.Service`, attach
+the canonical construction effect, and expose the default Layer so a named
+domain definition is declared once.
+
+Keep intrinsic definitions and canonical options inline in that declaration.
+Extract them only when they are reused, composed, tested independently, or
+selected dynamically.
+
+Avoid factories that return nested service namespaces and force callers to
+yield an inner tag or supply the canonical definition repeatedly. A reusable
+domain abstraction should expose its canonical tag, value constructor, and
+Layer directly. Use domain verbs such as `send`, `dispatch`, `snapshot`,
+`execute`, or `close`; reserve `request` for real request/response protocols.
+
+## Layers
+
+## What A Layer Is
+
+A layer constructs services from dependencies.
+
+Use a layer when:
+
+- service construction is effectful
+- the service depends on other services
+- the service owns resources that must be acquired and released safely
+- you want composition and reuse across modules
+
+## Preferred Layer Constructors
+
+### `Layer.succeed`
+
+Use for pure, already-constructed implementations.
+
+```ts
+const UserRepoTest = Layer.succeed(UserRepo)({
+  getById: (id) => Effect.succeed({ id, name: "Test User" })
+})
+```
+
+Use this when:
+
+- construction is pure
+- no dependencies are needed
+- no scoped resources are involved
+
+### `Layer.effect`
+
+Use when constructing a service requires effects, other services, or scoped resource acquisition.
+
+```ts
+class Config extends Context.Service<Config, {
+  readonly apiBaseUrl: string
+}>()("Config") {}
+
+const UserRepoLayer = Layer.effect(UserRepo)(
+  Effect.gen(function*() {
+    const config = yield* Config
+
+    return {
+      getById: (id) =>
+        Effect.succeed({
+          id,
+          name: `Fetched from ${config.apiBaseUrl}`
+        })
+    }
+  })
+)
+```
+
+Use this when:
+
+- construction is effectful
+- construction depends on other services
+- construction needs `Scope` and finalization
+- you want typed construction failure
+
+This is also the correct constructor for services that own resources with acquisition and release semantics. In this repo, `Layer.effect` replaces the old `Layer.scoped` API.
+
+Typical examples:
+
+- database pools
+- sockets
+- background worker processes
+- long-lived subscriptions
+
+### `Layer.effectDiscard`
+
+Use `Layer.effectDiscard` for scoped startup effects that do not provide a service.
+
+Good use cases:
+
+- starting background fibers in a layer
+- one-time scoped initialization side effects
+- subsystem startup hooks
+
+### `Layer.effectContext`
+
+Use when one effect constructs a full `Context` containing multiple services.
+
+This is useful for subsystem builders that provide several related services together.
+
+## Layer Composition
+
+These operators do different things. Do not treat them as interchangeable.
+
+### Composition Cheat Sheet
+
+- `Layer.mergeAll(a, b, ...)`: combine outputs of multiple layers
+- `Layer.provide(target, dependencies)`: feed dependency outputs into `target` and keep only `target` outputs
+- `Layer.provideMerge(target, dependencies)`: feed dependency outputs into `target` and keep both dependency outputs and target outputs
+- `Layer.flatMap(layer, f)`: choose the next layer based on the built service value
+
+### Example Services
+
+```ts
+import { Context, Effect, Layer } from "effect"
+
+class Config extends Context.Service<Config, {
+  readonly apiBaseUrl: string
+}>()("Config") {}
+
+class Logger extends Context.Service<Logger, {
+  readonly log: (message: string) => Effect.Effect<void>
+}>()("Logger") {}
+
+class UserRepo extends Context.Service<UserRepo, {
+  readonly getById: (id: string) => Effect.Effect<{ id: string; name: string }>
+}>()("UserRepo") {}
+
+const ConfigLayer = Layer.succeed(Config)({
+  apiBaseUrl: "https://api.example.com"
+})
+
+const LoggerLayer = Layer.succeed(Logger)({
+  log: (message) => Effect.sync(() => console.log(message))
+})
+
+const UserRepoLayer = Layer.effect(UserRepo)(
+  Effect.gen(function*() {
+    const config = yield* Config
+    const logger = yield* Logger
+
+    return {
+      getById: (id) =>
+        Effect.gen(function*() {
+          yield* logger.log(`loading ${id} from ${config.apiBaseUrl}`)
+          return { id, name: "Ada" }
+        })
+    }
+  })
+)
+```
+
+### `Layer.mergeAll`
+
+Use `Layer.mergeAll` to combine outputs of independent layers.
+
+```ts
+const Dependencies = Layer.mergeAll(
+  ConfigLayer,
+  LoggerLayer
+)
+```
+
+Use this when:
+
+- the layers provide different services
+- neither needs to transform the other directly
+
+Semantics:
+
+- inputs are combined
+- outputs are combined
+- no dependency feeding happens automatically
+
+Important:
+
+- `Layer.mergeAll(ConfigLayer, UserRepoLayer)` is wrong if `UserRepoLayer` requires `Config` and `Logger`
+- `mergeAll` does not satisfy `UserRepoLayer`'s requirements
+- it only places both layers side by side in the output graph
+
+Correct pattern:
+
+```ts
+const Dependencies = Layer.mergeAll(
+  ConfigLayer,
+  LoggerLayer
+)
+```
+
+### `Layer.provide`
+
+Use `Layer.provide` to satisfy a target layer's dependencies with another layer, while keeping only the target layer's outputs.
+
+```ts
+const Dependencies = Layer.mergeAll(
+  ConfigLayer,
+  LoggerLayer
+)
+
+const UserRepoLayerReady = Layer.provide(UserRepoLayer, Dependencies)
+```
+
+Interpretation:
+
+- `UserRepoLayer` requires `Config` and `Logger`
+- `Dependencies` provides those dependencies
+- the resulting layer provides only `UserRepo`
+- `Config` and `Logger` are used for construction but are not kept in the final output
+
+This is the operator to use when you want to hide construction dependencies behind a narrower public layer.
+
+Example program:
+
+```ts
+const program = Effect.gen(function*() {
+  const repo = yield* UserRepo
+  return yield* repo.getById("u_123")
+}).pipe(
+  Effect.provide(UserRepoLayerReady)
+)
+```
+
+### `Layer.provideMerge`
+
+Use `provideMerge` when you want to satisfy dependencies and retain both the dependency outputs and the target outputs.
+
+```ts
+const Dependencies = Layer.mergeAll(
+  ConfigLayer,
+  LoggerLayer
+)
+
+const AppLayer = Layer.provideMerge(UserRepoLayer, Dependencies)
+```
+
+Interpretation:
+
+- `UserRepoLayer` still gets `Config` and `Logger`
+- the resulting layer provides `UserRepo`, `Config`, and `Logger`
+
+This is useful for assembling larger application layers incrementally, especially when downstream code still needs access to the dependencies.
+
+Example program:
+
+```ts
+const program = Effect.gen(function*() {
+  const repo = yield* UserRepo
+  const logger = yield* Logger
+
+  const user = yield* repo.getById("u_123")
+  yield* logger.log(user.name)
+  return user
+}).pipe(
+  Effect.provide(AppLayer)
+)
+```
+
+Preferred rule:
+
+- use `provide` when you want to hide dependency details
+- use `provideMerge` when you want to keep dependency services available downstream
+
+### `Layer.mergeAll` vs `Layer.provide` vs `Layer.provideMerge`
+
+Think of them like this:
+
+- `mergeAll`: put layers next to each other
+- `provide`: plug one layer into another, expose only the target
+- `provideMerge`: plug one layer into another, expose both sides
+
+### Composition Style Best Practice
+
+Layers should almost always be fully composed locally before they are assembled into the final application layer.
+
+Preferred style:
+
+- define each service layer separately
+- define local subsystem dependency bundles separately
+- fully compose each subsystem locally with `Layer.provide` or `Layer.provideMerge`
+- assemble the final application layer with `Layer.mergeAll(...)`
+- apply top-level cross-cutting provisioning in a small number of explicit trailing steps
+
+Good pattern:
+
+```ts
+const UserDependencies = Layer.mergeAll(
+  ConfigLayer,
+  LoggerLayer
+)
+
+const UserLayer = Layer.provide(UserRepoLayer, UserDependencies)
+
+const BillingDependencies = Layer.mergeAll(
+  ConfigLayer,
+  LoggerLayer,
+  DatabaseLayer
+)
+
+const BillingLayer = Layer.provide(BillingServiceLayer, BillingDependencies)
+
+const AppLayer = Layer.mergeAll(
+  UserLayer,
+  BillingLayer,
+  HttpLayer
+).pipe(
+  Layer.provide(Telemetry),
+  Layer.provide(NodeSdk)
+)
+```
+
+Why this style is preferred:
+
+- subsystem wiring stays local to the subsystem
+- the final application layer reads as a high-level composition map
+- cross-cutting concerns such as telemetry stay visible at the top level
+- it avoids deeply nested inline layer expressions
+
+Avoid this style when a clearer local name would help:
+
+```ts
+const AppLayer = Layer.provide(
+  Layer.mergeAll(
+    Layer.provide(UserRepoLayer, Layer.mergeAll(ConfigLayer, LoggerLayer)),
+    Layer.provide(BillingServiceLayer, Layer.mergeAll(ConfigLayer, LoggerLayer, DatabaseLayer)),
+    HttpLayer
+  ),
+  Telemetry
+).pipe(Layer.provide(NodeSdk))
+```
+
+That style is harder to read because:
+
+- subsystem composition is hidden inside the final assembly
+- shared dependencies are harder to spot
+- it is harder to refactor or reuse subsystem layers
+
+### `Layer.flatMap`
+
+Use `flatMap` when the next layer depends on the actual constructed service value, not just its type-level requirement.
+
+Example:
+
+```ts
+const UserRepoLayerFromConfig = Layer.flatMap(ConfigLayer, (config) =>
+  Layer.succeed(UserRepo)({
+    getById: (id) => Effect.succeed({ id, name: config.apiBaseUrl })
+  })
+)
+```
+
+This is more specialized than `merge` or `provide`.
+
+Prefer simpler composition first:
+
+- `merge` for combining
+- `provide` for dependency satisfaction
+- `flatMap` only when construction logic truly depends on the built value
+
+## Providing Layers To Effects
+
+## Preferred Rule
+
+Provide layers at boundaries.
+
+Usually that means:
+
+- the application entrypoint
+- a subsystem entrypoint
+- a test boundary
+
+Avoid repeatedly providing layers deep inside business logic unless you are deliberately isolating a subsystem.
+
+### Anti-Pattern: Local `Effect.provide`
+
+`Effect.provide` should be used only once at the entry of your program in normal application code.
+
+Bad pattern:
+
+```ts
+const loadUser = (userId: string) =>
+  Effect.gen(function*() {
+    const repo = yield* UserRepo
+    return yield* repo.getById(userId)
+  }).pipe(
+    Effect.provide(UserRepoLayer)
+  )
+```
+
+Why this is an anti-pattern:
+
+- it hides dependency wiring inside business logic
+- it makes implementations harder to swap in tests
+- it prevents clean top-level composition
+- it encourages many small local runtimes instead of one coherent application graph
+- it makes shared cross-cutting services harder to reason about
+
+Preferred pattern:
+
+```ts
+const loadUser = (userId: string) =>
+  Effect.gen(function*() {
+    const repo = yield* UserRepo
+    return yield* repo.getById(userId)
+  })
+
+const program = loadUser("u_123").pipe(
+  Effect.provide(AppLayer)
+)
+```
+
+Rule of thumb:
+
+- business logic should require services
+- composition should happen in layers
+- `Effect.provide` should happen at the outermost entry boundary
+
+### Multiple Entry Points
+
+If your code integrates with a framework and has multiple entry points, prefer `ManagedRuntime` instead of repeatedly calling `Effect.provide` at many call sites.
+
+Typical examples:
+
+- HTTP handlers registered separately
+- queue consumers
+- cron jobs
+- framework lifecycle hooks
+- RPC handlers or worker callbacks
+
+Preferred pattern:
+
+```ts
+const runtime = ManagedRuntime.make(AppLayer)
+
+const handleRequest = (id: string) =>
+  runtime.runPromise(loadUser(id))
+```
+
+Why:
+
+- the layer graph is still composed once
+- services remain shared according to layer semantics
+- the framework integration gets a stable runtime boundary
+- resource lifecycle is explicit through `ManagedRuntime`
+
+Repo reference:
+
+- `packages/effect/src/ManagedRuntime.ts`
+
+## `Effect.provide`
+
+Use `Effect.provide` to satisfy an effect's dependencies with a layer or context.
+
+```ts
+const program = loadUser("u_123").pipe(
+  Effect.provide(UserRepoLayerReady)
+)
+```
+
+This is the main boundary provisioning operator.
+
+## `Effect.provideService`
+
+Use `provideService` for a single ad hoc implementation.
+
+```ts
+const program = loadUser("u_123").pipe(
+  Effect.provideService(UserRepo, {
+    getById: (id) => Effect.succeed({ id, name: "Inline User" })
+  })
+)
+```
+
+Good use cases:
+
+- small tests
+- one-off overrides
+- local customization
+
+Do not use this as the default replacement for real application layers.
+
+## `Effect.provideServiceEffect`
+
+Use `provideServiceEffect` when one service instance must be built effectfully without creating a reusable layer.
+
+This is useful for targeted overrides, but if the construction is reusable or part of application wiring, prefer a named `Layer.effect`.
+
+## Best Practices
+
+## 1. Keep service interfaces small and focused
+
+Prefer cohesive services over giant "everything" services.
+
+Good:
+
+- `UserRepo`
+- `Mailer`
+- `Clock`-like configuration or time abstractions
+
+Avoid:
+
+- large service shapes that mix unrelated responsibilities
+
+## 2. Prefer layers over manual wiring
+
+If construction has dependencies or effects, represent it as a layer.
+
+Avoid manually grabbing dependencies and assembling concrete objects all over the codebase.
+
+## 2.5 Prefer Effect-native integrations over raw runtime clients
+
+When Effect already provides a module for a capability, prefer the Effect-native integration over directly embedding a raw runtime client in service code.
+
+Examples:
+
+- prefer `effect/unstable/sql` modules over directly coupling business services to native SQL driver APIs
+- prefer Effect HTTP modules over direct ad hoc request clients when the project is already using Effect HTTP abstractions
+
+Why:
+
+- resource handling, tracing, and errors stay inside the Effect model
+- integrations compose better with layers and services
+- observability and transactions are easier to keep consistent
+
+## 3. Keep business logic abstract over implementations
+
+Business functions should require services, not construct them.
+
+Good:
+
+```ts
+const sendWelcomeEmail = (userId: string) =>
+  Effect.gen(function*() {
+    const repo = yield* UserRepo
+    const user = yield* repo.getById(userId)
+    return user
+  })
+```
+
+Avoid constructing `UserRepo` inside `sendWelcomeEmail`.
+
+Service methods take domain inputs only. Yield configuration, clients,
+databases, clocks, loggers, request context, platform bindings, and other
+runtime dependencies from the Effect environment. Do not recreate dependency
+injection through method, constructor, options-bag, or implementation-helper
+parameters; yield a dependency while constructing the service and close over
+it in the method implementation.
+
+## 4. Use `Layer.succeed` only for pure values
+
+Do not hide effectful initialization inside supposedly pure service objects.
+
+If initialization can fail, depends on effects, or needs scoped acquisition, use `Layer.effect`.
+
+## 5. Use `Layer.effect` for owned resources
+
+If the service opens something that must later close, model that lifecycle explicitly.
+
+This is one of the main reasons layers exist.
+
+## 6. Prefer top-level composition
+
+Compose major application layers once near the boundary.
+
+Good pattern:
+
+- define `ConfigLayer`
+- define `UserRepoLayer`
+- define `Dependencies = Layer.mergeAll(...)`
+- define `AppLayer` separately with `Layer.provide(...)` or `Layer.provideMerge(...)`
+- provide `AppLayer` to the top-level program
+
+Let the composition root choose concrete backends and own transport lifecycles.
+Do not hide request, websocket, worker, RPC, serialization, or server adapter
+Layers inside an exported domain service Layer merely because one entrypoint
+needs them.
+
+## 7. Use `Layer.fresh` only when you really need a new instance
+
+Layers are shared by default.
+
+That is usually what you want.
+
+Use `Layer.fresh` only when you intentionally need to bypass sharing and rebuild the layer.
+
+## 7.5 Understand Layer Memoization
+
+Layers are memoized by reference.
+
+That means:
+
+- reusing the same layer value preserves memoization and sharing
+- creating a new layer value creates a new memoization identity
+
+Prefer named Layer values. Layer constructors must not accept runtime
+dependencies or configuration:
+
+```ts
+// Avoid: requirements disappear from the Layer input channel.
+const makeUserRepoLayer = (config: Config, client: HttpClient) =>
+  Layer.effect(UserRepo)(makeUserRepo(config, client))
+```
+
+Model configuration, clients, databases, clocks, platform bindings, and
+backend selection as focused services. Yield them inside `Layer.effect` so
+requirements remain visible, and provide their concrete Layers once at the
+outer composition boundary:
+
+```ts
+const UserRepoLayer = Layer.effect(UserRepo)(
+  Effect.gen(function*() {
+    const config = yield* Config
+    const client = yield* HttpClient
+    return UserRepo.of(makeUserRepo(config, client))
+  })
+)
+
+const AppLayer = UserRepoLayer.pipe(
+  Layer.provide(ConfigLayer),
+  Layer.provide(HttpClientLayer)
+)
+```
+
+Arguments are acceptable only when they are intrinsic definitions that create
+a distinct named service instance, not runtime dependencies or configuration.
+If a Layer-producing function is genuinely needed, call it once during
+construction and reuse the resulting Layer value. Use `Layer.fresh` when a
+distinct instance is intentional.
+
+## 8. Treat `Layer.orDie` carefully
+
+`Layer.orDie` converts layer construction failures into defects.
+
+Only use it when failure is truly unrecoverable at that boundary.
+
+Do not use it to hide legitimate configuration or infrastructure failures.
+
+## 9. Use `ManagedRuntime.make` at true runtime boundaries
+
+If you need a reusable runtime built from a layer, `ManagedRuntime.make` is the edge tool for that.
+
+Good use cases:
+
+- embedding Effect into external frameworks
+- scripts or hosts that repeatedly run Effect programs
+
+Repo reference:
+
+- `packages/effect/src/ManagedRuntime.ts`
+
+## 10. Prefer explicit test layers
+
+For tests, prefer:
+
+- `Layer.succeed` for simple fakes
+- `Layer.mock` for partial mocks when appropriate
+
+This keeps test wiring explicit and close to production composition style.
+
+## Recommended Patterns
+
+## Pattern: service definition plus live layer
+
+```ts
+import { Context, Effect, Layer } from "effect"
+
+class Config extends Context.Service<Config, {
+  readonly apiBaseUrl: string
+}>()("Config") {}
+
+class UserRepo extends Context.Service<UserRepo, {
+  readonly getById: (id: string) => Effect.Effect<{ id: string; name: string }>
+}>()("UserRepo") {}
+
+const ConfigLayer = Layer.succeed(Config)({
+  apiBaseUrl: "https://api.example.com"
+})
+
+const UserRepoLayer = Layer.effect(UserRepo)(
+  Effect.gen(function*() {
+    const config = yield* Config
+
+    return {
+      getById: (id) =>
+        Effect.succeed({
+          id,
+          name: `Loaded via ${config.apiBaseUrl}`
+        })
+    }
+  })
+)
+
+const Dependencies = Layer.mergeAll(ConfigLayer)
+
+const AppLayer = Layer.provide(UserRepoLayer, Dependencies)
+```
+
+## Pattern: provide at the top level
+
+```ts
+const program = Effect.gen(function*() {
+  const repo = yield* UserRepo
+  return yield* repo.getById("u_123")
+}).pipe(
+  Effect.provide(AppLayer)
+)
+```
+
+## Pattern: single-service override in tests
+
+```ts
+const TestRepo = Layer.succeed(UserRepo)({
+  getById: (id) => Effect.succeed({ id, name: "Test" })
+})
+```
+
+## Anti-Patterns
+
+- constructing live services directly inside business logic
+- using `Layer.succeed` for values that actually require effectful initialization
+- providing the same large layer repeatedly throughout the call graph
+- collapsing unrelated responsibilities into one service
+- using `Layer.orDie` to hide normal initialization failures
+- bypassing layers entirely for resource-owning services
+
+## Good Repo Examples To Study
+
+- `packages/effect/src/Context.ts`
+- `packages/effect/src/Layer.ts`
+- `packages/effect/src/ManagedRuntime.ts`
+- `packages/effect/src/Stream.ts`
+- `packages/effect/src/unstable/sql/SqlClient.ts`
+- `packages/effect/src/unstable/persistence/Persistence.ts`
+- `packages/effect/src/unstable/rpc/RpcSerialization.ts`
+- `packages/effect/src/unstable/reactivity/Reactivity.ts`