chore: production deploy

.agents/skills/effect/SKILL.md

@@ -12,6 +12,11 @@ Use current Effect v4 APIs and the production defaults in this skill. Establishe
 
 ## Source Rule
 
+Reviewed against Effect **4.0.0**, upstream commit
+[`6389d9ac6`](https://github.com/Effect-TS/effect/tree/6389d9ac64c0f62ccc8b575fb9afc65fc104e814).
+Read `references/V4_APIS.md` when upgrading from v3 or a v4 prerelease.
+The installed version takes precedence: prerelease APIs and import paths can differ.
+
 Check these before guessing:
 
 - the nearest `AGENTS.md` and any project-local Effect practices doc
@@ -47,7 +52,7 @@ If a task spans several branches, read all matching files before editing.
 - 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.
+- Decode unknown wire input with `Schema.decodeUnknownEffect(...)`; use `schema.makeEffect(...)` for typed constructor input with validation. Reserve throwing `schema.make(...)` for trusted construction, and never use casts to skip validation.
 
 ## Quick Selection Guide
 

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

@@ -13,6 +13,8 @@ Prefer `effect/Cache` over a `Map` + timestamp + prune-loop cache when its keyed
 - 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.
+- Lookup services are captured at construction by default. Use `requireServicesAt: "lookup"` only when callers should supply them on each lookup; this changes the cache's environment type.
+- `timeToLive` is optional and defaults to infinity. Specify it when freshness matters; capacity alone only bounds retained entries.
 - 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`.
 

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

@@ -10,9 +10,9 @@ 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));
+    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 });
   }),
@@ -23,8 +23,9 @@ export const layerFromEnvironment = Layer.effect(
 
 - `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.
+- Constructors are capitalized: `Config.String`, `Config.Boolean`, `Config.Int`, `Config.Duration`, `Config.URL`, and `Config.Redacted`. Combinators such as `Config.option` and `Config.withDefault` remain lowercase.
+- Use `Config.Redacted(...)` for credentials.
+- Use `Config.schema(...)` for refined values, or `Config.mapEffect(...)` for a transformation returning `Effect<B, Config.ConfigError>`; `Config.mapOrFail` is not a v4 API.
 - 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.

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

@@ -4,10 +4,14 @@ Use this when writing outgoing HTTP calls, Effect HttpClient adapters, status cl
 
 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`
+- `effect/http/HttpClient`
+- `effect/http/HttpClientRequest`
+- `effect/http/HttpClientResponse`
+- `effect/http/HttpClientError`
+
+The grouped import is `import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http"`.
+Current v4 exports no longer include the prerelease `effect/unstable/http` path.
+Individual APIs may still carry an `@stability unstable` annotation; import placement is not a stability guarantee.
 
 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.
 
@@ -39,7 +43,7 @@ Useful APIs:
 - `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.
+- `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. Set `times` to bound those retries (`0` disables them); the default is unlimited.
 
 ## Retry And Rate Limits
 

.agents/skills/effect/references/SCHEMA.md

@@ -20,12 +20,26 @@ Guidance:
 
 - Add `.annotate({ identifier: "User" })` only when tooling consumes it: HTTP API, RPC, OpenAPI/JSON Schema, docs, diagnostics, or codegen.
 - Use `schema.make(...)` when construction is trusted.
-- Use `schema.makeEffect(...)` when construction failure should stay in the Effect error channel.
+- Use `schema.makeEffect(...)` when construction failure should stay in the Effect error channel. It validates typed constructor input and fails with `SchemaIssue.Issue`, not `Schema.SchemaError`.
+- Use `schema.makeOption(...)` when constructor validation details may be discarded.
 - Decode unknown input at boundaries with `Schema.decodeUnknownEffect(...)` by default.
 - Use `Schema.decodeUnknownSync(...)` only in scripts, tests, or startup paths where throwing is acceptable.
 - Use `Schema.decodeUnknownOption(...)` only when mismatch details are intentionally discarded.
 - Use `Schema.decodeUnknownResult(...)` for pure code that wants explicit success/failure without Effect.
 
+### Construction Versus Decoding
+
+`make` / `makeEffect` apply constructor defaults and type-side validation. They are
+not decoders for an unknown encoded representation. For example, decode a wire
+timestamp through its string-to-DateTime codec rather than passing the string to
+the decoded value's constructor.
+
+- `Schema.decodeUnknownEffect(schema)(input)` fails with `Schema.SchemaError`.
+- `SchemaParser.decodeUnknownEffect(schema)(input)` exposes the raw `SchemaIssue.Issue` for low-level parser composition.
+- `schema.makeEffect(input)` also exposes `SchemaIssue.Issue`; wrap it explicitly with `Effect.mapError((issue) => new Schema.SchemaError(issue))` if the boundary needs `SchemaError`.
+- `schema.make(input)` throws a plain `Error` with the issue in `cause` on validation failure; do not assume it throws `SchemaError`.
+- `Schema.NumberFromString` coerces with `Number(s)`: empty or whitespace-only strings decode to `0` and trailing junk to `NaN`. Use `Schema.FiniteFromString` to reject non-numeric input, and add a non-blank check when empty input must fail.
+
 ## Field And Contract Reuse
 
 Reuse fields directly when contracts are semantically related.

.agents/skills/effect/references/TESTING.md

@@ -4,6 +4,15 @@ Use this when writing Effect tests, tests involving time, retry, schedules, conc
 
 ## Defaults
 
+```ts
+import { expect, it } from "@effect/vitest";
+import { Effect, Fiber } from "effect";
+import { TestClock } from "effect/testing";
+```
+
+Use a v4-compatible `@effect/vitest` version. `TestClock` is under
+`effect/testing`, not the root `effect` barrel or the old `effect/TestClock` path.
+
 - Use `it.effect` by default.
 - Use `it.live` only when real time or live runtime services are the behavior under test.
 - Use test layers and `ConfigProvider` rather than global mutation.
@@ -12,6 +21,16 @@ Use this when writing Effect tests, tests involving time, retry, schedules, conc
 - Avoid arbitrary `Effect.sleep(...)` in tests; it usually makes tests slow and flaky.
 - Assert typed failures, rollback, interruption, finalization, retry bounds, idempotency, concurrency laws, and malformed persistence where relevant.
 
+```ts
+it.effect("advances virtual time", () =>
+  Effect.gen(function* () {
+    const fiber = yield* Effect.sleep("1 second").pipe(Effect.as("done"), Effect.forkScoped);
+    yield* TestClock.adjust("1 second");
+    expect(yield* Fiber.join(fiber)).toBe("done");
+  }),
+);
+```
+
 ```ts
 it.effect("finds a user", () =>
   Effect.gen(function* () {

.agents/skills/effect/references/V4_APIS.md

@@ -0,0 +1,61 @@
+# Current v4 API Checkpoints
+
+Reviewed against Effect 4.0.0 at upstream commit
+[`6389d9ac6`](https://github.com/Effect-TS/effect/tree/6389d9ac64c0f62ccc8b575fb9afc65fc104e814).
+Always inspect the consuming project's pinned version before applying these changes.
+
+## Imports
+
+Current v4 groups modules by domain without the prerelease `unstable` segment:
+
+```ts
+import { Config, Context, Effect, Layer, Schema } from "effect";
+import { FetchHttpClient, HttpClient } from "effect/http";
+import { HttpApi, HttpApiBuilder } from "effect/http-api";
+import { SqlClient } from "effect/sql";
+import { Rpc, RpcGroup } from "effect/rpc";
+import { Atom } from "effect/reactivity";
+import { TestClock } from "effect/testing";
+```
+
+Direct imports such as `effect/http/HttpClient` also work. Check `effect/package.json`
+exports instead of mechanically moving every `@effect/*` package into `effect`:
+platform adapters, framework integrations, SQL drivers, and `@effect/vitest` still
+have separate packages. The root barrel does not re-export every domain module.
+
+## Common Migration Traps
+
+| Older API or assumption                              | Current v4                                                                             |
+| ---------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `Config.string`, `boolean`, `redacted`               | `Config.String`, `Boolean`, `Redacted`                                                 |
+| `Config.mapOrFail`                                   | `Config.mapEffect`; failure must be `Config.ConfigError`                               |
+| `effect/unstable/http`                               | `effect/http`                                                                          |
+| Root `TestClock` import                              | `effect/testing`                                                                       |
+| `Context.Tag` / `Effect.Service` service definitions | `Context.Service` plus explicit `Layer` implementations                                |
+| `Effect.catchAll`                                    | `Effect.catch`; prefer `catchTag` for selected tagged errors                           |
+| `Effect.fork` / `forkDaemon`                         | `Effect.forkChild` / `forkDetach`; prefer `forkScoped` for layer-owned work            |
+| `Either`                                             | `Result`; inspect constructors and payload fields rather than just renaming the import |
+| `Schema.makeEffect` failures are `SchemaError`       | Instance `schema.makeEffect` fails with `SchemaIssue.Issue`                            |
+
+## Validation Boundaries
+
+```ts
+const Port = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));
+
+const config = Config.schema(Port, "PORT");
+const constructed = Port.makeEffect(8080); // failure: SchemaIssue.Issue
+const decoded = Schema.decodeUnknownEffect(Port)(8080); // failure: Schema.SchemaError
+const wrapped = constructed.pipe(Effect.mapError((issue) => new Schema.SchemaError(issue)));
+```
+
+See `SCHEMA.md` for constructor defaults, wire decoding, and error handling;
+`CONFIG.md` for provider-based configuration; and `TESTING.md` for virtual time.
+
+## Upstream Sources
+
+- [Package exports](https://github.com/Effect-TS/effect/blob/6389d9ac64c0f62ccc8b575fb9afc65fc104e814/packages/effect/package.json)
+- [Generated v3-to-v4 migration reference](https://github.com/Effect-TS/effect/blob/6389d9ac64c0f62ccc8b575fb9afc65fc104e814/migration/v3-to-v4.md)
+- [Schema migration guide](https://github.com/Effect-TS/effect/blob/6389d9ac64c0f62ccc8b575fb9afc65fc104e814/migration/schema.md)
+
+Use source signatures and type-check representative call sites when updating this
+skill. A name appearing in a source comment is not evidence that it is exported.