chore(repo): sync develop into next

.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.

.github/MAINTAINERS.md

@@ -132,8 +132,9 @@ Full procedures live in the
 [ADR 0028](../docs/adr/0028-release-branches-and-maintenance-lines.md).
 
 **Resolving a sync PR.** When `Sync branches` cannot merge cleanly it opens
-`sync/<source>-into-<target>` (for example `sync/develop-into-next`). Further
-syncs for that pair skip while it is open. Merge the target into the sync
+`sync/<source>-into-<target>` (for example `sync/develop-into-next`); CODEOWNERS
+requests the CLI team, and for `main-into-develop` the release Slack channel is
+also told. Further syncs for that pair skip while it is open. Merge the target into the sync
 branch, resolve, and push; then **approve** the PR. Approval fast-forwards the
 target and deletes the branch. Never use the merge button. If the target or the
 source moved, the bot merges the latest target and source into the approved head and lands
@@ -155,7 +156,7 @@ Fast-forward PRs are the deploy PR (`develop` → `main`), the major cut
 
 **Dispatch guards.** `release.yml` refuses `channel=next` off `next`,
 `channel=maintenance` off `v<N>.x`, `beta`/`stable` on `next` or `v<N>.x`, a
-non-dry-run `stable` outside `main` and `hotfix/*`, and a `version` that is not
+non-dry-run `stable` outside `main`, and a `version` that is not
 `X.Y.Z[-prerelease]`.
 
 **`release-major` label.** The deploy fast-forward refuses a major version bump
@@ -180,6 +181,13 @@ Only security fixes and fixes for fundamentally broken behaviour go into
 must be cherry-picked to every active `v*.x` (see
 [Release infra and maintenance lines](../apps/cli/docs/release-process.md#release-infra-and-maintenance-lines)).
 
+**Hotfixes.** A stable fix that cannot wait for the weekly deploy is a
+`hotfix/*` PR into `main` titled `fix`, `perf`, or `revert`. Its checks,
+including the dry-run release rehearsal, run on every push. After it publishes,
+`Sync branches` merges `main` into `develop`; a conflict is announced in Slack.
+There is no rollback: ship a `revert:` hotfix instead. See
+[Hotfix release flow](../apps/cli/docs/release-process.md#hotfix-release-flow).
+
 **Manual setup (rulesets and labels).**
 
 - Create the `next` branch from `develop`, and the `release-major` label.

.github/actionlint.yaml → .github/jactionlint.yaml

@@ -1,9 +1,10 @@
+require-commit-hash: true # actions, reusable workflows and docker:// must be pinned to a full SHA / @sha256 digest
 self-hosted-runner:
   labels:
     - arm-runner
     - blacksmith-2vcpu-ubuntu-2404
     - blacksmith-4vcpu-ubuntu-2404
-    - blacksmith-32vcpu-ubuntu-2404
-    - blacksmith-8vcpu-ubuntu-2404
     - blacksmith-6vcpu-macos-latest
+    - blacksmith-8vcpu-ubuntu-2404
     - blacksmith-8vcpu-windows-2025
+    - blacksmith-32vcpu-ubuntu-2404