chore(repo): share Effect skill across the monorepo

.agents/skills/effect/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: effect
+description: |
+  Opinionated guide for building production TypeScript applications with Effect v4. Use when implementing Effect workflows, services, layers, schemas, configuration, schedules, caches, streams, HTTP clients, or tests.
+license: MIT
+compatibility: Requires Effect v4. Examples are reviewed against the version documented in this repository.
+---
+
+# 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.TaggedError`.
+- 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.TaggedError`.
+- 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.TaggedError` 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.

.agents/skills/effect/references/CACHING.md

@@ -0,0 +1,75 @@
+# Caching, Memoization, And Request Dedupe
+
+Use this when memoizing expensive lookups, caching per-key results with TTL, deduplicating concurrent identical calls, or considering request batching.
+
+Prefer `effect/Cache` over a `Map` + timestamp + prune-loop cache when its keyed memoization, TTL, capacity, lifecycle, and eviction semantics fit.
+
+## Core Rules
+
+- `Cache.make({ capacity, lookup, timeToLive })` caches per-key lookups with one fixed TTL for all entries.
+- `Cache.makeWith(lookup, { capacity, timeToLive(exit, key) })` computes TTL per entry from the lookup's `Exit` — the tool for "cache successes, not failures".
+- Concurrent `Cache.get` calls for the same missing key share one pending lookup — dedupe is built in; do not add your own in-flight tracking.
+- `capacity` is required and bounds the cache; stop writing manual prune/evict loops.
+- Return a zero TTL (`0` or `"0 millis"`) from `timeToLive` to avoid caching transient failures or degraded fallbacks without failing the caller. A short negative-cache TTL can be appropriate for stable failures such as not-found results.
+- `Cache.invalidate(cache, key)` / `Cache.refresh(cache, key)` handle explicit staleness; `Cache.has` checks without triggering a lookup.
+- Cache construction is effectful. Build the cache once in the owning layer/scope and share the handle; a cache built per call caches nothing.
+- For a single value (no key), use `Effect.cached(effect)` or `Effect.cachedWithTTL(effect, ttl)` instead of a one-key Cache.
+- For cached resources that need cleanup (connections, clients), use `ScopedCache`.
+
+## Exit-Aware TTL (cache successes, skip degraded results)
+
+```ts
+import { Cache, Duration, Effect, Exit } from "effect";
+
+const makeResolver = Effect.gen(function* () {
+  const cache = yield* Cache.makeWith(
+    (channelRef: string) => resolveUncached(channelRef), // never-failing, returns { where, cacheable }
+    {
+      capacity: 300,
+      timeToLive: (exit) =>
+        Exit.isSuccess(exit) && exit.value.cacheable ? "10 minutes" : Duration.zero,
+    },
+  );
+  return (channelRef: string) =>
+    Cache.get(cache, channelRef).pipe(Effect.map((resolved) => resolved.where));
+});
+```
+
+This replaces a hand-rolled `Map<string, { value, expiresAtMs }>` plus prune logic, and upgrades it: repeated rows pointing at the same key during one burst share a single provider call.
+
+## Expensive Client Acquisition Belongs In The Layer, Not The Lookup
+
+A cache cannot fix a lookup that pays a scoped acquisition per call, such as SDK client construction or authentication. Acquire clients once via the owning layer (`Layer.build` inside a `Layer.unwrap(Effect.gen(...))` composition, or a service dependency) so the cached lookup is a plain call:
+
+```ts
+// Bad: every cache miss acquires a fresh client
+const lookup = (id: string) => getRecord(id).pipe(Effect.provide(apiClientLayer(options)));
+
+// Good: client built once for the layer's lifetime; misses are one API call
+// Layer.build requires Scope.Scope; acquire this inside the owning layer's scope.
+const context = yield * Layer.build(apiClientLayer(options));
+const lookup = (id: string) => Context.get(context, ApiClient).getRecord(id);
+```
+
+## Request Batching (`Effect.request` + `RequestResolver`)
+
+Batching exists for backends with a real batch endpoint: the resolver receives an array of pending requests and can collapse them into one wire call.
+
+- Use it when the API can answer N keys in one call (SQL `IN (...)`, DataLoader-style endpoints, batch GET).
+- Do not reach for it when the backend only has per-item endpoints (most REST provider APIs): a batched resolver still loops one call per entry, so it buys nothing over `Effect.forEach(items, f, { concurrency })` plus `Cache` for dedupe/memoization.
+- `RequestResolver.batchN(resolver, n)` bounds batch size; `RequestResolver.makeGrouped` groups requests that must resolve through different targets.
+
+Selection guide:
+
+- Same key requested repeatedly over time → `Cache`.
+- Same key requested concurrently in one burst → `Cache` (shared pending lookup).
+- Many distinct keys, backend has a batch endpoint → `Effect.request` + `RequestResolver`.
+- Many distinct keys, per-item endpoint only → `Effect.forEach(..., { concurrency: n })`, optionally through a `Cache`.
+
+## Do Nots
+
+- Do not hand-roll Map/TTL/prune caches, in-flight dedupe maps, or LRU logic when `Cache` fits.
+- Choose failure TTLs by semantics. Skip transient failures and degraded fallbacks by default; bounded negative caching can protect an upstream from repeated stable failures.
+- Do not build a cache inside the request handler or per call — hoist it to the owning layer.
+- Do not adopt `RequestResolver` batching for per-item REST endpoints just because "batching" sounds faster.
+- Do not put scoped client acquisition inside the cache lookup; acquire once in the layer.

.agents/skills/effect/references/CONFIG.md

@@ -0,0 +1,60 @@
+# Config
+
+Use this when reading runtime configuration, env vars, `.env` files, provider-specific settings, or writing `layerConfig(...)` helpers.
+
+Read runtime configuration through Effect `Config` recipes and provider layers, not direct `process.env` access inside application logic.
+
+```ts
+export const dataDirectoryConfig = Config.schema(AbsolutePath, "APP_DATA_DIR");
+
+export const layerFromEnvironment = Layer.effect(
+  Configuration.Service,
+  Effect.gen(function* () {
+    const apiKey = yield* Config.redacted("API_KEY");
+    const optionalModel = yield* Config.option(Config.string("MODEL"));
+    const enabled = yield* Config.boolean("FEATURE_ENABLED").pipe(Config.withDefault(false));
+
+    return Configuration.Service.of({ apiKey, optionalModel, enabled });
+  }),
+);
+```
+
+## Config Recipes
+
+- `Config<T>` is yieldable and reads the current `ConfigProvider` reference.
+- The default provider is `ConfigProvider.fromEnv()`.
+- Use `Config.redacted(...)` for credentials.
+- Use `Config.schema(...)` or `Config.mapOrFail(...)` for refined values.
+- Use `Config.option(...)` for semantic absence.
+- Use `Config.withDefault(...)` for missing-data defaults only; malformed values still fail.
+- Use `Config.orElse(...)` only when intentionally catching any config parse failure.
+- Use `Config.unwrap(...)` / `Config.Wrap<T>` for `layerConfig(...)` helpers.
+
+## Providers
+
+- Use `ConfigProvider.layer(provider)` to replace the active provider for an app or suite.
+- Use `ConfigProvider.layerAdd(provider)` for fallbacks; pass `{ asPrimary: true }` when the added provider must override the current provider.
+- Use `ConfigProvider.fromUnknown(...)` for deterministic test config.
+- Use `ConfigProvider.fromEnv(...)` for environment variables.
+- Use `ConfigProvider.constantCase` when camelCase schema keys should read `SCREAMING_SNAKE_CASE` env vars.
+- Use `ConfigProvider.nested(...)` to scope a provider under a prefix.
+- Treat `.env`, directory, and environment providers as startup/boundary sources, not business-workflow reads.
+
+## Layer Config Helpers
+
+Library-style layers often expose both concrete `layer(options)` and config-backed `layerConfig(options: Config.Wrap<Options>)`.
+
+```ts
+export const layerConfig = (config: Config.Wrap<ClientOptions>) =>
+  Layer.effect(
+    Client.Service,
+    Config.unwrap(config).pipe(
+      Effect.flatMap(makeClient),
+      Effect.map((client) => Client.Service.of(client)),
+    ),
+  );
+```
+
+Use this pattern when a service naturally supports runtime config while still allowing tests to pass concrete values.
+
+Use `Layer.succeed(AppConfiguration.Service, testConfig)` when the app already wraps environment config in an application service and the test does not need to exercise Config decoding itself.

.agents/skills/effect/references/HTTP_CLIENTS.md

@@ -0,0 +1,101 @@
+# HTTP Clients
+
+Use this when writing outgoing HTTP calls, Effect HttpClient adapters, status classification, HTTP retries, or rate limiting.
+
+Use Effect HTTP client modules for outgoing HTTP in app/provider code:
+
+- `effect/unstable/http/HttpClient`
+- `effect/unstable/http/HttpClientRequest`
+- `effect/unstable/http/HttpClientResponse`
+- `effect/unstable/http/HttpClientError`
+
+Prefer Effect HttpClient in Effect application and provider code when its typed errors, layers, and transforms are useful. Raw `fetch` remains reasonable for browser or edge constraints, small adapters, platform transports, and libraries that intentionally avoid unstable Effect HTTP APIs.
+
+## Boundary Shape
+
+HTTP adapter methods should be named effects that own the full boundary:
+
+- construct request
+- attach auth and headers
+- execute request
+- classify status
+- decode response body
+- map transport/status/decode failures to typed domain errors
+- apply retry/rate-limit policy where idempotent
+
+Keep raw provider/network effects outside business services and database transactions.
+
+## Effect HttpClient
+
+Useful APIs:
+
+- `HttpClient.get(...)`, `post(...)`, `put(...)`, `patch(...)`, `del(...)`, `execute(...)` for service accessors.
+- `HttpClient.mapRequest(...)` / `mapRequestEffect(...)` for configured client transforms.
+- `HttpClientRequest.prependUrl(...)` for base URLs.
+- `HttpClientRequest.bearerToken(...)` for bearer auth.
+- `HttpClientRequest.acceptJson` for JSON accept headers.
+- `HttpClientRequest.bodyJson(...)` for effectful JSON body encoding.
+- `HttpClientRequest.schemaBodyJson(...)` for schema-backed JSON body encoding.
+- `HttpClient.filterStatusOk` / `HttpClientResponse.filterStatusOk` before decoding when non-2xx responses are failures.
+- `HttpClientResponse.schemaBodyJson(...)` for body-only decoding, `schemaJson(...)` for status/headers/body decoding, and `schemaNoBody(...)` for status/headers decoding.
+- `HttpClient.retryTransient(...)` for common transient HTTP failures.
+- `HttpClient.withRateLimiter(...)` for proactive pacing and learning from rate-limit headers. It requires a `RateLimiter` plus initial window, limit, and key options; it adds `RateLimiterError` to the error channel and retries `429` responses by default.
+
+## Retry And Rate Limits
+
+Use `HttpClient.retryTransient(...)` for common transient HTTP failures:
+
+- transport errors
+- timeouts
+- `408`
+- `429`
+- `500`
+- `502`
+- `503`
+- `504`
+
+Use `HttpClient.withRateLimiter(...)` when the client should proactively pace requests and learn from rate-limit / `Retry-After` headers.
+
+Use operation-level `Effect.retry(...)` when retry depends on domain-specific typed errors, provider payloads, or idempotency rules. Read `SCHEDULING.md` for custom schedules and `retryAfterMs` typed-provider patterns.
+
+## Raw Fetch Exception
+
+Use raw `fetch` deliberately when implementing a platform transport, adapting an API that cannot use Effect HttpClient, or targeting a runtime/library boundary where the unstable Effect HTTP modules are not an appropriate dependency.
+
+If a temporary raw `fetch` boundary is unavoidable, keep it inside an adapter service and still use Effect boundary discipline.
+
+```ts
+const request = Effect.fn("Provider.request")(function* (input: RequestInput) {
+  const response = yield* Effect.tryPromise({
+    try: (signal) => fetch(input.url, { signal, headers: input.headers }),
+    catch: (cause) => new ProviderError({ operation: "Provider.request", cause }),
+  });
+
+  if (!response.ok) {
+    return yield* Effect.fail(
+      new ProviderRejected({
+        operation: "Provider.request",
+        status: response.status,
+      }),
+    );
+  }
+
+  const json = yield* Effect.tryPromise({
+    try: () => response.json(),
+    catch: (cause) => new ProviderError({ operation: "Provider.decodeJson", cause }),
+  });
+
+  return yield* Schema.decodeUnknownEffect(ResponseSchema)(json).pipe(
+    Effect.mapError((cause) => new ProviderError({ operation: "Provider.decodeResponse", cause })),
+  );
+});
+```
+
+Guidance:
+
+- Prefer replacing this with Effect HttpClient before adding more behavior.
+- Wire `AbortSignal` from `Effect.tryPromise` into `fetch` when raw fetch is unavoidable.
+- Classify HTTP status before decoding successful payloads.
+- Decode unknown response bodies with Schema at the boundary.
+- Preserve provider evidence needed for diagnosis, but redact secrets and private payloads.
+- Apply retry only for idempotent operations.