effect

# Effect Use current Effect v4 APIs and the production defaults in this skill. Established project conventions still take precedence unless the task is explicitly changing them. ## Source Rule Check these before guessing: - the nearest `AGENTS.md` and any project-local Effect practices doc - the project-pinned `effect` package source and version - current upstream Effect source when the installed package does not answer the question ## Branch Chooser Read only the branch references that match the task. - Data models, schemas, brands, variants, optional keys, or decoders: read `references/SCHEMA.md`. - Services, module surfaces, layers, runtime wiring, errors, `Effect.fn`, or test services: read `references/SERVICES_LAYERS.md`. - Runtime config, env variables, `ConfigProvider`, or `layerConfig`: read `references/CONFIG.md`. - Retry, repeat, polling, backoff, jitter, rate-limit-aware policies, or pass loops: read `references/SCHEDULING.md`. - Memoization, per-key TTL caches, deduplicating concurrent lookups, or request batching: read `references/CACHING.md`. - Streams, event sources, async iterables, queues/pubsubs, pagination, backpressure, or stream consumers: read `references/STREAMS.md`. - Outgoing HTTP calls, Effect HttpClient, status handling, or HTTP rate limiting: read `references/HTTP_CLIENTS.md`. - Effect tests, time, sleeps, concurrency synchronization, or fakes: read `references/TESTING.md`. If a task spans several branches, read all matching files before editing. ## Core Defaults - Compose workflows with `Effect.gen(function* () { ... })`. - Define public service methods and non-trivial internal service methods with `Effect.fn("Domain.operation")`. - Use `Effect.fnUntraced` only for internal helpers where stack-frame/span metadata is intentionally unnecessary. - Prefer `Context.Service` for application services when the codebase has not standardized on another current service-tag style. - Build real service implementations with `Layer.effect(Service, Effect.gen(...))` and return `Service.of({ ... })`. - Model records with `Schema.Struct(...)` plus a same-name `interface`. - Model typed Effect errors with `Schema.TaggedErrorClass`. - Read runtime config through `Config`, not direct `process.env` access in application logic. - Use `Schedule` for retry, repeat, polling, pacing, and backoff policies. - Use `Stream` for effectful sources that emit many values over time and need pull, backpressure, interruption, or transformation. - Prefer Effect HTTP client modules for outgoing HTTP in Effect applications when their typed errors, layers, and client transforms are useful. - Prefer Effect-aware tests, explicit layers, and deterministic synchronization over sleeps. - Prefer decoders and `schema.makeEffect(...)` at untrusted boundaries; reserve throwing `schema.make(...)` for trusted construction, and never use casts to skip validation. ## Quick Selection Guide - Ordinary object record: `Schema.Struct(...)` plus same-name `interface`. - Scalar ID/value object: constrained branded schema. - Internal workflow decision or state: `Data.TaggedEnum<...>` plus `Data.taggedEnum<...>()` constructors and exhaustive `$match`. - Reusable boundary-crossing tagged variant: `Schema.TaggedStruct(...)` plus same-name `interface`. - Boundary-crossing tagged union: `Schema.TaggedUnion(...)` with `.cases`, `.guards`, and `.match`. - External/custom discriminator such as `type`: `Schema.Struct({ type: Schema.tag("variant"), ... })` plus `Schema.toTaggedUnion("type")` when union helpers are needed. - Expected typed failure: `Schema.TaggedErrorClass`. - Unknown boundary payload: `Schema.decodeUnknownEffect(...)`. - Service boundary: `Context.Service<Service, Interface>()(...)` plus `Layer.effect(...)` plus `Service.of(...)`. - Public or non-trivial internal service method: `Effect.fn("Domain.operation")`. - Runtime configuration: `Config` recipes read in layers; override with `ConfigProvider` in tests. - Event source: `Stream` consumed with `Stream.runForEach(...)` and forked with `Effect.forkScoped` in the owning layer. - Queue-backed event source: `Queue` for the producer boundary, `Stream.fromQueue(...)` for consumers. - Broadcast event source: `PubSub` / `Stream.fromPubSub(...)` or `SubscriptionRef` for latest-value state. - Polling worker: `runPass().pipe(Effect.repeat(Schedule.spaced(...)))`, with typed pass failures handled before repeat. - Retry transient operation: `Effect.retry(...)` / `Effect.retryOrElse(...)` with a bounded `Schedule`. - Keyed lookup cache with TTL and concurrent-lookup dedupe: prefer `Cache.make(...)` / exit-aware `Cache.makeWith(...)` when their lifecycle and eviction model fit. - Memoize a single effect result: `Effect.cached(...)` / `Effect.cachedWithTTL(...)`. - Batch N keys into one backend call (only when a real batch endpoint exists): `Effect.request(...)` + `RequestResolver`. - HTTP request in an Effect application: prefer Effect `HttpClient` plus request/response schema decoding. - HTTP transient retry: `HttpClient.retryTransient(...)`. - Time-sensitive test: `TestClock`, not real sleeping. - Concurrent/background test synchronization: `Deferred`, `Queue`, `Latch`, `Ref`, or explicit test hooks. ## Boundary Rules - Keep HTTP handlers thin: decode input, read context, call services, map typed errors to transport responses. - Keep business rules in services or domain functions, not transport handlers. - Wrap HTTP clients, SDKs, CLIs, and external integrations in named effects at adapter boundaries. - Decode persisted rows with Schema or SQL-specific helpers when values are not trivially trusted. - Keep provider/network calls outside authoritative database transactions. - Catch or retry only when the current boundary has a truthful response. - Retry only when the operation has proven idempotency. - Let exhausted failures remain visible unless the boundary has a real fallback. ## Do Nots - Do not use `as any`, non-null assertions, or unchecked casts to silence Effect typing problems. - Do not introduce `Schema.Class` or `Schema.TaggedClass` as default app data-modeling patterns. - Do not hand-roll `_tag` error classes when `Schema.TaggedErrorClass` fits. - Do not use cause-level recovery when typed-error recovery is enough. - Do not use `Layer.mergeAll(...)` or `provideMerge(...)` as blind make-it-compile tools. - Do not hide required application authority, credentials, persistence, transports, or external services behind `Context.Reference` defaults. - Do not add arbitrary `Effect.sleep(...)` to tests when a deterministic synchronization primitive is available. - Do not hand-roll Map/TTL/prune caches or in-flight dedupe when `effect/Cache` fits.