effect

# Effect Ground every recommendation in the target project. Inspect repository instructions, the pinned `effect` version, installed package source, and local conventions before choosing APIs. Prefer project evidence over remembered signatures. ## Choose the Relevant Guidance Read only the references needed for the task, and combine them when concerns overlap: - Schema, records, variants, brands, and typed errors: `references/SCHEMA.md` - Services, layers, modules, scope ownership, and `Effect.fn`: `references/SERVICES_LAYERS.md` - Configuration and providers: `references/CONFIG.md` - Schedules, retry, repeat, polling, and pacing: `references/SCHEDULING.md` - Cache, memoization, in-flight dedupe, and request batching: `references/CACHING.md` - Streams, queues, PubSub, SubscriptionRef, and long-lived consumers: `references/STREAMS.md` - HTTP clients, decoding, retries, and rate limits: `references/HTTP_CLIENTS.md` - Effect-aware tests, TestClock, layers, and synchronization: `references/TESTING.md` ## Model Data and Failures - Use `Schema.Struct(...)` for application records. - Use brands for scalar IDs and constrained values. - Use tagged Schema variants and unions for values that cross boundaries. - Decode unknown boundary data with `Schema.decodeUnknownEffect(...)`. - Model expected failures with `Schema.TaggedErrorClass`. - Never use casts or throwing construction to skip validation at untrusted boundaries. ## Build Explicit Services and Layers - Keep business rules in named workflows and services. - Represent dependencies explicitly in the Effect environment. - Build implementations with layers that own resource lifetime. - Keep HTTP and transport handlers focused on decoding, context, invocation, and response mapping. - Wrap public or non-trivial service methods with named `Effect.fn` calls. - Do not hide required authority, credentials, persistence, or transports behind defaults. ## Choose Runtime Primitives by Meaning - Use `Config` for runtime configuration and override it with providers in tests. - Use `Schedule` for retry, repeat, polling, pacing, and backoff. - Use `Cache` or Effect memoization when their ownership and eviction model fit. - Use request batching only when the backend exposes a real batch operation. - Use Queue, PubSub, SubscriptionRef, and Stream according to producer, consumer, broadcast, and backpressure needs. - Keep long-lived fibers scoped to the layer or resource that owns them. ## Keep Boundaries Truthful - Wrap HTTP clients, SDKs, CLIs, and external systems in named Effect boundaries. - Decode persisted and external values before treating them as domain data. - Preserve distinct transport, status, decode, and domain failures. - Retry only proven transient failures on idempotent operations with a bounded policy. - Keep exhausted failures visible unless the boundary has a real fallback. - Keep provider and network calls outside authoritative database transactions. ## Test Deterministically - Use Effect-aware tests and explicit test layers. - Fork time-dependent work before advancing `TestClock`. - Coordinate concurrent work with Deferred, Queue, Latch, Ref, fibers, or explicit hooks. - Never add arbitrary real sleeps when deterministic synchronization can express the condition. ## Preserve Types and Dependencies Solve missing requirements through explicit service and layer composition. Do not use `as any`, non-null assertions, broad cause recovery, `Layer.mergeAll`, `provideMerge`, or default authority merely to make code compile. ## Before Editing 1. Identify every Effect concern in the task. 2. Read the matching references and project-local source. 3. Choose APIs supported by the pinned version. 4. Make the smallest architecture-preserving change. 5. Run the project's typecheck and focused tests.