opencode-effect-enforcer 0.2.8 → 0.4.0

package/skills/effect-http-api/SKILL.md

@@ -7,8 +7,8 @@ You are an Effect TypeScript expert specializing in the HttpApi module for build
 
 ## Effect Source Reference
 
-Use `HttpApi.ParseOptions` annotations at API, group, or endpoint scope to
-configure client and server codecs. `HttpApiBuilder.handler` defines a reusable
+Use `HttpApi.ParseOptions` as the fallback for client and server codecs;
+per-slot annotations override it (see below). `HttpApiBuilder.handler` defines a reusable
 endpoint callback with inferred request, success, error, and service types.
 Generated clients and AtomHttpApi calls accept per-call `sseOptions`.
 SSE IDs may be absent: model them with `Schema.optional(Schema.String)`.
@@ -22,13 +22,13 @@ the generator also accepts OpenAPI 3.2's native `query` operation.
 Generated multipart binary fields use `File | Blob` and dedicated `*Multipart`
 component exports. Keep generated imports aligned with the chosen transport.
 
-The Effect v4 source is available at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`. Browse and read files there directly to look up APIs, types, and implementations.
+The Effect v4 source is available at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`. Inspect the `effect@4.0.0` tag for this skill; main may be newer. These APIs remain `@stability unstable` and may break in minor releases despite their shorter import paths. Keep `effect` and companion packages on the same release.
 
 Key reference files:
 
 - `packages/effect/HTTPAPI.md` — canonical HttpApi documentation
-- `packages/effect/src/unstable/httpapi/*.ts` — module sources
-- `packages/effect/typetest/unstable/httpapi/*.tst.ts` — type-level contracts
+- `packages/effect/src/http-api/*.ts` — module sources
+- `packages/effect/typetest/http-api/*.tst.ts` — type-level contracts
 - `packages/platform/node/test/HttpApi.test.ts` — comprehensive runtime tests
 - `ai-docs/src/51_http-server/` — server walkthrough with fixtures
 - `ai-docs/src/50_http-client/` — HttpClient walkthrough
@@ -51,7 +51,7 @@ import {
 	HttpApiSwagger,
 	HttpApiTest,
 	OpenApi
-} from 'effect/unstable/httpapi';
+} from 'effect/http-api';
 
 // HTTP primitives (router, server, client, multipart)
 import {
@@ -66,7 +66,7 @@ import {
 	HttpServerResponse,
 	HttpStatus,
 	Multipart
-} from 'effect/unstable/http';
+} from 'effect/http';
 
 // Platform server (Node.js — Bun has @effect/platform-bun/BunHttpServer)
 import { NodeHttpServer, NodeRuntime } from '@effect/platform-node';
@@ -103,12 +103,14 @@ HttpApiEndpoint.delete('name', '/path', { ... });
 HttpApiEndpoint.head('name', '/path', { ... });
 HttpApiEndpoint.options('name', '/path', { ... });
 
-// Escape hatch for arbitrary methods (PROPFIND, MOVE, etc.)
-const link = HttpApiEndpoint.make('LINK');
-link('name', '/path', { ... });
+HttpApiEndpoint.query('name', '/path', { ... });
+
+// Generic factory for a supported HttpMethod
+const query = HttpApiEndpoint.make('QUERY');
+query('name', '/path', { ... });
 ```
 
-The first argument is the endpoint name (used as the method name in the generated client). The second is the route path. The third is an options object with schemas. For methods with no body (`get`, `head`, `options`, `delete`), the `payload` option is treated as a query-string-encoded record of fields.
+The first argument is the endpoint name (used as the method name in the generated client). The second is the route path. The third is an options object with schemas. For methods with no body (`GET`, `HEAD`, `OPTIONS`, `TRACE`), the `payload` option is treated as a query-string-encoded record of fields. `DELETE` and `QUERY` can carry bodies; `make` accepts the closed `HttpMethod` union, not arbitrary method strings.
 
 ### Endpoint Options
 
@@ -258,6 +260,42 @@ Group- and API-level prefixing are described below.
 
 ## Schema Annotations
 
+### Per-slot parse options
+
+Annotate the API, group, or endpoint with `HttpApi.ParamsParseOptions`,
+`QueryParseOptions`, `HeadersParseOptions`, `PayloadParseOptions`,
+`SuccessParseOptions`, or `ErrorParseOptions`. Each controls both sides of that
+codec: server decoding/client encoding for inputs, the reverse for outputs.
+Success options cover streamed/SSE bodies too; header options cover request
+headers and `WithHeaders` response headers independently of their bodies.
+
+For the same annotation, endpoint overrides group, which overrides API. A slot
+annotation at **any** level wins over fallback `ParseOptions` at **every** level.
+Objects replace rather than merge. Annotate before constructing handler groups.
+Real HTTP headers include transport fields: strict fallback parsing otherwise
+rejects them, while `onExcessProperty: 'preserve'` retains them in decoded values.
+Use an explicit empty header override to retain Schema defaults:
+
+<!-- typecheck -->
+```ts
+import { HttpApi, HttpApiEndpoint, HttpApiGroup } from 'effect/http-api';
+import * as Schema from 'effect/Schema';
+
+class CreateUser extends Schema.Class<CreateUser>('CreateUser')({
+	name: Schema.String
+}) {}
+
+const Api = HttpApi.make('StrictApi').add(
+	HttpApiGroup.make('users').add(
+		HttpApiEndpoint.post('create', '/users', {
+			headers: { 'x-api-key': Schema.String },
+			payload: CreateUser
+		})
+	)
+).annotate(HttpApi.ParseOptions, { onExcessProperty: 'error' })
+	.annotate(HttpApi.HeadersParseOptions, {});
+```
+
 ### Status Codes
 
 ```ts
@@ -281,7 +319,7 @@ class UserNotFound extends Schema.TaggedError<UserNotFound>()(
 
 `HttpApiSchema.StatusLiteral` is the exported keyof type for the literal form. The full set covers the standard codes (`Continue`, `OK`, `Created`, `Accepted`, `NoContent`, `MovedPermanently`, `Found`, `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`, `MethodNotAllowed`, `NotAcceptable`, `RequestTimeout`, `Conflict`, `Gone`, `UnprocessableEntity`, `TooManyRequests`, `InternalServerError`, `NotImplemented`, `BadGateway`, `ServiceUnavailable`, `GatewayTimeout`, etc.). Unannotated success schemas default to 200, and unannotated error schemas default to 500. If you omit `success`, the endpoint defaults to `HttpApiSchema.NoContent` (204). `success: Schema.Void` is an empty 200 response unless you annotate it or use `HttpApiSchema.NoContent`.
 
-The literal mapping is centralized in `HttpStatus` from `effect/unstable/http`. Use `HttpStatus.fromLiteral` when plain HTTP code needs the corresponding numeric literal type; `HttpApiSchema.status` uses the same mapping internally:
+The literal mapping is centralized in `HttpStatus` from `effect/http`. Use `HttpStatus.fromLiteral` when plain HTTP code needs the corresponding numeric literal type; `HttpApiSchema.status` uses the same mapping internally:
 
 ```ts
 HttpStatus.fromLiteral('OK'); // 200
@@ -638,7 +676,7 @@ const AllRoutes = Layer.mergeAll(ApiRoutes, DocsRoute);
 If you forget to provide a group's handler layer you'll get a clear runtime defect:
 
 ```
-HttpApiGroup "users" not found (key: "effect/httpapi/HttpApiGroup/users").
+HttpApiGroup "users" not found (key: "effect/http-api/HttpApiGroup/users").
 Did you forget to provide HttpApiBuilder.group(api, "users", ...)?
 Available groups: <list>
 ```
@@ -668,6 +706,12 @@ export const { handler, dispose } = HttpRouter.toWebHandler(
 
 `HttpRouter.serve` and `HttpRouter.toWebHandler` both also accept `routerConfig` (passed to find-my-way) and `middleware` (a wrap function applied to the entire HTTP server pipeline).
 
+`HttpRouter.serve` and `toHttpEffect` build with a fresh router in a forked layer
+memo map. Pass registration layers directly to them; do not pre-provide
+`HttpRouter.layer` to `ApiRoutes`. Services first built inside these entrypoints
+are private; provide services shared with siblings outside them. `toWebHandler`
+owns a separate build by default, but an explicit `memoMap` is used as supplied.
+
 > There is no `HttpApiBuilder.toWebHandler` — always go through `HttpRouter.toWebHandler` (or `HttpRouter.serve` for a long-running server).
 
 ## Errors
@@ -1240,6 +1284,12 @@ const spec = OpenApi.fromApi(Api);
 // spec is OpenAPI 3.1.0
 ```
 
+Parameters and response headers are documented from their **encoded** object
+representation, preserving property annotations. Decode-defaulted optional keys
+remain optional on the wire (path parameters still must be required by OpenAPI).
+Text bodies preserve encoded string literals and exportable checks such as
+patterns, including when opaque schemas or component references are involved.
+
 `fromApi` caches by both the `HttpApi` instance and the identity of the options object, but every call returns a fresh mutable spec copy. Mutating one returned spec does not contaminate later calls. Reuse one immutable options object to reuse the cache; mutating that options object does not invalidate an existing entry. The clone preserves frozen `JSON.rawJSON` values rather than flattening them into ordinary objects.
 
 The options accept the Schema representation `referencePolicy`. It runs at the canonical JSON-encoded AST boundary and controls which schemas become OpenAPI component references; by default only schemas with resolved identifiers are extracted, while anonymous non-recursive schemas remain inline:
@@ -1420,7 +1470,7 @@ For multipart streaming, see `HttpApiSchema.asMultipartStream` above.
 `HttpApiTest.groups(api, groupNames, { baseUrl? })` builds a fully typed `HttpApiClient` that runs against your real handler layers in memory — no HTTP server, no port. List the groups whose handlers you want to exercise; all other groups are auto-stubbed with `Effect.die`. The default `baseUrl` is `http://localhost:3000`; pass `{ baseUrl }` when tests rely on URL construction.
 
 ```ts
-import { HttpApiTest } from 'effect/unstable/httpapi';
+import { HttpApiTest } from 'effect/http-api';
 import { NodeHttpServer } from '@effect/platform-node';
 import { Effect, Layer } from 'effect';
 import { it } from '@effect/vitest';
@@ -1467,7 +1517,7 @@ it.effect('GET /users responds 200', () =>
 
 ## Reactive Integration
 
-For React/Atom-driven UIs, `effect/unstable/reactivity/AtomHttpApi` builds a service that exposes typed `query` and `mutation` atoms generated from an HttpApi:
+For React/Atom-driven UIs, `effect/reactivity/AtomHttpApi` builds a service that exposes typed `query` and `mutation` atoms generated from an HttpApi:
 
 ```ts
 class ApiAtom extends AtomHttpApi.Service<ApiAtom>()('app/ApiAtom', {
@@ -1499,7 +1549,7 @@ import {
 	HttpClient,
 	HttpClientRequest,
 	HttpClientResponse
-} from 'effect/unstable/http';
+} from 'effect/http';
 
 class Todo extends Schema.Class<Todo>('Todo')({
 	userId: Schema.Number,
@@ -1573,7 +1623,7 @@ export class Unauthorized extends Schema.TaggedError<Unauthorized>()(
 
 // --- api/Authorization.ts ---
 import { Context, Schema } from 'effect';
-import { HttpApiMiddleware, HttpApiSecurity } from 'effect/unstable/httpapi';
+import { HttpApiMiddleware, HttpApiSecurity } from 'effect/http-api';
 
 export class CurrentUser extends Context.Service<CurrentUser, User>()(
 	'app/CurrentUser'
@@ -1590,7 +1640,7 @@ export class Authorization extends HttpApiMiddleware.Service<
 
 // --- api/Users.ts ---
 import { Schema } from 'effect';
-import { HttpApiEndpoint, HttpApiGroup } from 'effect/unstable/httpapi';
+import { HttpApiEndpoint, HttpApiGroup } from 'effect/http-api';
 
 export class UsersApi extends HttpApiGroup.make('users')
 	.add(
@@ -1623,7 +1673,7 @@ export class SystemApi extends HttpApiGroup.make('system', {
 ) {}
 
 // --- api/Api.ts ---
-import { HttpApi, OpenApi } from 'effect/unstable/httpapi';
+import { HttpApi, OpenApi } from 'effect/http-api';
 
 export class Api extends HttpApi.make('app')
 	.add(UsersApi)
@@ -1663,7 +1713,7 @@ export const AuthorizationLayer = Layer.effect(
 
 // --- server/users.ts ---
 import { Effect, Layer } from 'effect';
-import { HttpApiBuilder } from 'effect/unstable/httpapi';
+import { HttpApiBuilder } from 'effect/http-api';
 
 export const UsersHandlers = HttpApiBuilder.group(
 	Api,
@@ -1692,8 +1742,8 @@ export const SystemHandlers = HttpApiBuilder.group(
 // --- server/main.ts ---
 import { NodeHttpServer, NodeRuntime } from '@effect/platform-node';
 import { Layer } from 'effect';
-import { HttpRouter } from 'effect/unstable/http';
-import { HttpApiBuilder, HttpApiScalar } from 'effect/unstable/httpapi';
+import { HttpRouter } from 'effect/http';
+import { HttpApiBuilder, HttpApiScalar } from 'effect/http-api';
 import { createServer } from 'node:http';
 
 const ApiRoutes = HttpApiBuilder.layer(Api, {

package/skills/effect-http-client/SKILL.md

@@ -3,9 +3,9 @@ name: effect-http-client
 description: Make outgoing HTTP requests with Effect's HttpClient — HttpClientRequest builders, schema-decoded HttpClientResponse bodies, the HttpClientError taxonomy, retryTransient/rate limiting/cookies/redirects, streaming uploads and downloads, and FetchHttpClient/NodeHttpClient transport layers. Use when calling external REST/JSON APIs, uploading or downloading files and streams, adding retries/auth/tracing to outbound HTTP, or mocking HTTP responses in tests.
 ---
 
-You are an Effect TypeScript expert specializing in outgoing HTTP with `effect/unstable/http` (`HttpClient`, `HttpClientRequest`, `HttpClientResponse`).
+You are an Effect TypeScript expert specializing in outgoing HTTP with `effect/http` (`HttpClient`, `HttpClientRequest`, `HttpClientResponse`).
 
-In v4 there is no `@effect/platform` package — the HTTP client lives in the `effect` package under `effect/unstable/http`. Only the platform transports (`NodeHttpClient`, `BunHttpClient`) live in `@effect/platform-*` packages.
+In v4 there is no `@effect/platform` package — the HTTP client lives in the `effect` package under `effect/http`. Only the platform transports (`NodeHttpClient`, `BunHttpClient`) live in `@effect/platform-*` packages.
 
 ## Effect Source Reference
 
@@ -18,23 +18,23 @@ for HTTP value schemas. Import Undici-specific APIs from
 `@effect/platform-node/Undici`; the transport layer owns their initialization.
 HTTP `QUERY` is supported; configure CORS `allowedMethods` explicitly if needed.
 
-The Effect v4 source is at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`. Read it directly when in doubt — these modules are `unstable` and change between betas.
+The Effect v4 source is at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`. Read the `effect@4.0.0` tag for this skill; main may be newer. APIs tagged `@stability unstable`, including these HTTP modules and Undici integration, may break in minor releases. Keep Effect-family packages on the same release.
 
 Key files:
 
-- `packages/effect/src/unstable/http/HttpClient.ts` — the `HttpClient` service, `make`/`makeWith`, every client combinator (`mapRequest`, `transform`, `filterStatus*`, `retry`, `retryTransient`, `withRateLimiter`, `withCookiesRef`, `withScope`, `followRedirects`, `catch*`, `tap*`), tracing references
-- `packages/effect/src/unstable/http/HttpClientRequest.ts` — immutable request model, method constructors, URL/param/header/body combinators, `toWeb`/`fromWeb`
-- `packages/effect/src/unstable/http/HttpClientResponse.ts` — response model, `schemaJson`/`schemaNoBody`, `matchStatus`, `filterStatus(Ok)`, `stream`
-- `packages/effect/src/unstable/http/HttpIncomingMessage.ts` — shared body accessors plus `JsonOptions`, `schemaBodyJson`, `schemaBodyUrlParams`, `schemaHeaders` (re-exported by HttpClientResponse)
-- `packages/effect/src/unstable/http/HttpClientError.ts` — `HttpClientError` wrapper and its `reason` union
-- `packages/effect/src/unstable/http/HttpBody.ts` — body variants (`Empty`, `Raw`, `Uint8Array`, `FormData`, `Stream`) and constructors (`json`, `jsonSchema`, `text`, `urlParams`, `formDataRecord`, `stream`, `file`)
-- `packages/effect/src/unstable/http/FetchHttpClient.ts` — fetch transport: `layer`, `Fetch` reference, `RequestInit` service
-- `packages/effect/src/unstable/http/UrlParams.ts` — ordered query-param model, coercion rules, schemas
-- `packages/effect/src/unstable/http/Url.ts` — immutable helpers over the native `URL`
-- `packages/effect/src/unstable/http/Cookies.ts` — cookie model, `fromSetCookie`, `toCookieHeader`, `getValue`
-- `packages/effect/src/unstable/http/Headers.ts` — header model, `Input` forms, `CurrentRedactedNames`
+- `packages/effect/src/http/HttpClient.ts` — the `HttpClient` service, `make`/`makeWith`, every client combinator (`mapRequest`, `transform`, `filterStatus*`, `retry`, `retryTransient`, `withRateLimiter`, `withCookiesRef`, `withScope`, `followRedirects`, `catch*`, `tap*`), tracing references
+- `packages/effect/src/http/HttpClientRequest.ts` — immutable request model, method constructors, URL/param/header/body combinators, `toWeb`/`fromWeb`
+- `packages/effect/src/http/HttpClientResponse.ts` — response model, `schemaJson`/`schemaNoBody`, `matchStatus`, `filterStatus(Ok)`, `stream`
+- `packages/effect/src/http/HttpIncomingMessage.ts` — shared body accessors plus `JsonOptions`, `schemaBodyJson`, `schemaBodyUrlParams`, `schemaHeaders` (re-exported by HttpClientResponse)
+- `packages/effect/src/http/HttpClientError.ts` — `HttpClientError` wrapper and its `reason` union
+- `packages/effect/src/http/HttpBody.ts` — body variants (`Empty`, `Raw`, `Uint8Array`, `FormData`, `Stream`) and constructors (`json`, `jsonSchema`, `text`, `urlParams`, `formDataRecord`, `stream`, `file`)
+- `packages/effect/src/http/FetchHttpClient.ts` — fetch transport: `layer`, `Fetch` reference, `RequestInit` service
+- `packages/effect/src/http/UrlParams.ts` — ordered query-param model, coercion rules, schemas
+- `packages/effect/src/http/Url.ts` — immutable helpers over the native `URL`
+- `packages/effect/src/http/Cookies.ts` — cookie model, `fromSetCookie`, `toCookieHeader`, `getValue`
+- `packages/effect/src/http/Headers.ts` — header model, `Input` forms, `CurrentRedactedNames`
 - `packages/platform/node/src/NodeHttpClient.ts` — Node transports: undici, node:http, fetch re-export
-- `packages/effect/test/unstable/http/HttpClient.test.ts` — retryTransient, withRateLimiter, abort semantics
+- `packages/effect/test/http/HttpClient.test.ts` — retryTransient, withRateLimiter, abort semantics
 - `ai-docs/src/50_http-client/10_basics.ts` — canonical "wrap a configured client in a service" lesson
 
 ## Core Model
@@ -69,7 +69,7 @@ import {
 	HttpClientRequest,
 	HttpClientResponse,
 	UrlParams
-} from 'effect/unstable/http';
+} from 'effect/http';
 ```
 
 For Node-specific transports:
@@ -215,7 +215,7 @@ HttpClientRequest.trace('/debug');
 HttpClientRequest.get('/search', { urlParams: { q: 'effect' }, acceptJson: true });
 ```
 
-These come from the generic factory `HttpClientRequest.make(method)`; `HttpClientRequest.setMethod` swaps the method on an existing request. `HttpMethod` is a closed union of these eight verbs — there is no path for custom methods like `REPORT`.
+These come from the generic factory `HttpClientRequest.make(method)`; `HttpClientRequest.setMethod` swaps the method on an existing request. `HttpMethod` is a closed union of nine verbs, including body-carrying `QUERY` (`HttpClientRequest.query`, `client.query`, `HttpClient.query`) — there is no path for custom methods like `REPORT`.
 
 ### URL combinators
 
@@ -442,6 +442,10 @@ const lines = HttpClientResponse.stream(client.get('/logs')).pipe(
 
 Every client failure is a single tagged error, `HttpClientError`, wrapping a `reason` union:
 
+For unknown boundary values, use the module guards rather than inspecting private
+type IDs. Body construction failures have `HttpBody.isHttpBodyError`; cookie
+construction failures have `Cookies.isCookiesError`.
+
 | `reason._tag` | When | Has `response`? |
 |---|---|---|
 | `TransportError` | network/connection failure while sending | no |
@@ -620,12 +624,12 @@ The undici transport neutralizes undici's own timeouts (`headersTimeout` one hou
 
 ### `HttpClient.withRateLimiter`
 
-Client-side rate limiting backed by the `RateLimiter` service from `effect/unstable/persistence`. It delays requests past the limit, **automatically retries 429s** (responses or `StatusCodeError`s) back through the limiter honoring `retry-after`, and by default updates its limit/window from `ratelimit-*` / `x-ratelimit-*` response headers.
+Client-side rate limiting backed by the `RateLimiter` service from `effect/persistence`. It delays requests past the limit, **automatically retries 429s** (responses or `StatusCodeError`s) back through the limiter honoring `retry-after`, and by default updates its limit/window from `ratelimit-*` / `x-ratelimit-*` response headers.
 
 Because `withRateLimiter` retries 429 responses independently of the HTTP method, apply it with `times > 0` only to a client restricted to proven-idempotent operations. For a mixed or non-idempotent client, set `times: 0` and handle the returned 429 as a visible typed failure.
 
 ```ts
-import { RateLimiter } from 'effect/unstable/persistence';
+import { RateLimiter } from 'effect/persistence';
 
 const limitedReads = Effect.gen(function* () {
 	const limiter = yield* RateLimiter.RateLimiter;
@@ -828,7 +832,7 @@ For declarative API clients derived from an `HttpApi` definition, see the effect
 
 ```ts
 import { Context, Effect, flow, Layer, Schedule, Schema } from 'effect';
-import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse } from 'effect/unstable/http';
+import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse } from 'effect/http';
 
 class Todo extends Schema.Class<Todo>('Todo')({
 	userId: Schema.Number,
@@ -978,7 +982,7 @@ const makeGithubReads = Effect.gen(function* () {
 
 ## Common Mistakes
 
-1. **v3 imports** — `@effect/platform/HttpClient` and friends no longer exist. Import `HttpClient`, `HttpClientRequest`, `HttpClientResponse`, `FetchHttpClient`, etc. from `effect/unstable/http`; only `NodeHttpClient` comes from `@effect/platform-node`.
+1. **v3 imports** — `@effect/platform/HttpClient` and friends no longer exist. Import `HttpClient`, `HttpClientRequest`, `HttpClientResponse`, `FetchHttpClient`, etc. from `effect/http`; only `NodeHttpClient` comes from `@effect/platform-node`.
 2. **Calling body accessors as methods** — `response.text`, `response.json`, `response.stream` are property getters returning Effects/Streams. `yield* response.json`, not `await response.json()`.
 3. **`HttpClientRequest.del` does not exist** — the request constructor is `HttpClientRequest.delete`; the client/service method and accessor are `client.del` / `HttpClient.del`.
 4. **Catching v3 error tags** — there are no top-level `RequestError`/`ResponseError` tags anymore. Everything is one tag, `HttpClientError`; branch on `error.reason._tag` (`TransportError`, `StatusCodeError`, `DecodeError`, ...).

package/skills/effect-http-server/SKILL.md

@@ -1,29 +1,29 @@
 ---
 name: effect-http-server
-description: Build HTTP servers with effect/unstable/http — HttpRouter routes and middleware, HttpServerRequest schema decoding, HttpServerResponse constructors, multipart uploads, websocket upgrades, static files, NodeHttpServer/BunHttpServer layers, and in-memory web handlers. Use when serving raw HTTP routes, reading request bodies/cookies/uploads, writing server middleware, streaming responses, or testing handlers without a real port.
+description: Build HTTP servers with effect/http — HttpRouter routes and middleware, HttpServerRequest schema decoding, HttpServerResponse constructors, multipart uploads, websocket upgrades, static files, NodeHttpServer/BunHttpServer layers, and in-memory web handlers. Use when serving raw HTTP routes, reading request bodies/cookies/uploads, writing server middleware, streaming responses, or testing handlers without a real port.
 ---
 
-You are an Effect TypeScript expert specializing in HTTP servers built with `effect/unstable/http` — `HttpRouter`, `HttpServer`, `HttpServerRequest`, `HttpServerResponse`, `HttpMiddleware`, and the platform server layers.
+You are an Effect TypeScript expert specializing in HTTP servers built with `effect/http` — `HttpRouter`, `HttpServer`, `HttpServerRequest`, `HttpServerResponse`, `HttpMiddleware`, and the platform server layers.
 
 This skill covers the imperative HTTP server primitives. For the declarative, schema-first `HttpApi`/OpenAPI layer see the `effect-http-api` skill; for HTTP clients see `effect-http-client`; for raw TCP/WebSocket sockets see `effect-socket`.
 
 ## Effect Source Reference
 
-The Effect v4 source is at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`. Read it directly when in doubt — these modules are unstable and change between betas.
+The Effect v4 source is at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`. Read the `effect@4.0.0` tag for this skill; main may be newer. These modules remain `@stability unstable` and may break in minor releases. Keep Effect-family packages on the same release.
 
 Key files:
 
-- `packages/effect/src/unstable/http/HttpRouter.ts` — router service, `add`/`addAll`/`route`/`use`, `serve`, `toWebHandler`, schema decoders, `middleware`, `cors`, `provideRequest`, `RouterConfig`
-- `packages/effect/src/unstable/http/HttpServer.ts` — `HttpServer` service, `serve`/`serveEffect`, address helpers, `layerTestClient`, `layerServices`
-- `packages/effect/src/unstable/http/HttpServerRequest.ts` — request model, body accessors, `schemaBodyJson`/`schemaBodyForm`/etc., `ParsedSearchParams`, `upgrade`, `MaxBodySize`
-- `packages/effect/src/unstable/http/HttpServerResponse.ts` — every response constructor and combinator, `toWeb`/`fromWeb`
-- `packages/effect/src/unstable/http/HttpMiddleware.ts` — `logger`, `tracer`, `cors`, `xForwardedHeaders`, `searchParamsParser`, tracing config references
-- `packages/effect/src/unstable/http/HttpEffect.ts` — `toWebHandler*`, `fromWebHandler`, `toHandled`, pre-response handlers, request scope management
-- `packages/effect/src/unstable/http/HttpServerError.ts` — `HttpServerError` + reasons, `causeResponse`, `ClientAbort`
-- `packages/effect/src/unstable/http/HttpServerRespondable.ts` — the error-to-response protocol
-- `packages/effect/src/unstable/http/HttpBody.ts` — body variants (`Empty`/`Raw`/`Uint8Array`/`FormData`/`Stream`) and constructors
-- `packages/effect/src/unstable/http/Headers.ts`, `Cookies.ts`, `Multipart.ts` — header/cookie/multipart models and limits
-- `packages/effect/src/unstable/http/HttpStaticServer.ts` — static file serving
+- `packages/effect/src/http/HttpRouter.ts` — router service, `add`/`addAll`/`route`/`use`, `serve`, `toWebHandler`, schema decoders, `middleware`, `cors`, `provideRequest`, `RouterConfig`
+- `packages/effect/src/http/HttpServer.ts` — `HttpServer` service, `serve`/`serveEffect`, address helpers, `layerTestClient`, `layerServices`
+- `packages/effect/src/http/HttpServerRequest.ts` — request model, body accessors, `schemaBodyJson`/`schemaBodyForm`/etc., `ParsedSearchParams`, `upgrade`, `MaxBodySize`
+- `packages/effect/src/http/HttpServerResponse.ts` — every response constructor and combinator, `toWeb`/`fromWeb`
+- `packages/effect/src/http/HttpMiddleware.ts` — `logger`, `tracer`, `cors`, `xForwardedHeaders`, `searchParamsParser`, tracing config references
+- `packages/effect/src/http/HttpEffect.ts` — `toWebHandler*`, `fromWebHandler`, `toHandled`, pre-response handlers, request scope management
+- `packages/effect/src/http/HttpServerError.ts` — `HttpServerError` + reasons, `causeResponse`, `ClientAbort`
+- `packages/effect/src/http/HttpServerRespondable.ts` — the error-to-response protocol
+- `packages/effect/src/http/HttpBody.ts` — body variants (`Empty`/`Raw`/`Uint8Array`/`FormData`/`Stream`) and constructors
+- `packages/effect/src/http/Headers.ts`, `Cookies.ts`, `Multipart.ts` — header/cookie/multipart models and limits
+- `packages/effect/src/http/HttpStaticServer.ts` — static file serving
 - `packages/platform/node/src/NodeHttpServer.ts` — Node server adapter, `layer`, `layerTest`, graceful shutdown
 - `packages/platform/bun/src/BunHttpServer.ts` — Bun equivalent
 - `packages/platform/node/test/NodeHttpServer.test.ts` — the best end-to-end reference for real route/middleware/multipart wiring
@@ -55,7 +55,7 @@ import {
 	HttpStatus,
 	HttpStaticServer,
 	Multipart
-} from 'effect/unstable/http';
+} from 'effect/http';
 import { NodeHttpServer, NodeRuntime } from '@effect/platform-node';
 import { createServer } from 'node:http';
 ```
@@ -86,7 +86,7 @@ Layer.launch(Main).pipe(NodeRuntime.runMain);
 HttpRouter.add(method, path, handler, options?): Layer<never, never, HttpRouter | ...>
 ```
 
-- `method`: `'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | '*'` (`'*'` matches all methods; `HEAD` requests automatically fall back to the matching `GET` route with the body stripped)
+- `method`: `HttpMethod | '*'`, including `HEAD`, `TRACE`, and body-carrying `QUERY` (`'*'` matches all methods; `HEAD` requests automatically fall back to the matching `GET` route with the body stripped)
 - `path`: `PathInput` — must start with `/`, or be `*`. `:name` captures a path param; a trailing `/*` is a wildcard (and also matches the bare prefix: `'/files/*'` matches `/files` too)
 - `options`: `{ uninterruptible?: boolean }` — handlers are interruptible by default (client disconnect interrupts the fiber); set `true` for must-complete handlers
 
@@ -159,7 +159,7 @@ const { id: pathOnly } = yield* HttpRouter.schemaPathParams(IdParams); // path p
 
 ### Router configuration
 
-The matcher is `find-my-way-ts`. Configure via the `RouterConfig` reference or the `routerConfig` option of `serve`/`toWebHandler`:
+The matcher is the bundled `FindMyWay` module. Configure via the `RouterConfig` reference or the `routerConfig` option of `serve`/`toWebHandler`:
 
 ```ts
 Layer.succeed(HttpRouter.RouterConfig)({
@@ -170,6 +170,9 @@ Layer.succeed(HttpRouter.RouterConfig)({
 });
 ```
 
+Route parameter construction does not require string code generation (`new
+Function`), so routing works under CSP restrictions on dynamic code evaluation.
+
 ---
 
 ## 2. Reading the Request
@@ -310,6 +313,11 @@ handler.pipe(
 
 The Effect v4 parser stops consuming input as soon as a part-count, part-size, or field-size limit is exceeded. Active file-part streams are terminated with the multipart failure when a limit is exceeded or the body ends unexpectedly, so consumers fail promptly instead of hanging. Keep consuming or supervising every exposed file stream so that failure is observed.
 
+Buffered parts produced while a file is being read are emitted before pulling
+more input. Use `Multipart.isMultipartError` for unknown boundary failures;
+`HttpBody.isHttpBodyError` and `Cookies.isCookiesError` guard their corresponding
+construction errors.
+
 ---
 
 ## 4. Building Responses
@@ -585,6 +593,17 @@ yield* HttpEffect.appendPreResponseHandler((request, response) =>
 
 ## 7. Serving
 
+`HttpRouter.serve` and `toHttpEffect` isolate entrypoints with a fresh router and
+forked layer memo map. Reusing an app layer in two such entrypoints builds it
+separately; routes and global middleware do not leak between them. Layers first
+built inside an app are private to that entrypoint. Build/provide services that
+siblings must share outside `serve`/`toHttpEffect`. `toWebHandler` has a separate
+build by default, but its explicit `memoMap` option is passed through as supplied;
+sharing that map intentionally shares memoized layers, including the router.
+Pass route registration layers to each entrypoint with their `HttpRouter`
+requirement intact; pre-providing `HttpRouter.layer` registers on a different
+router and leaves the served router empty.
+
 ### Node
 
 ```ts
@@ -654,6 +673,14 @@ yield* HttpServer.serveEffect(httpEffect);
 
 ## 8. WebSocket Upgrades
 
+Node and Bun HTTP upgrade adapters close server WebSockets according to the
+owning scope's exit: `1000` on success, `1001` for interruption-only failure, and
+`1011` for other failures (including mixed failure/interruption causes). Explicit
+close codes already sent by the application are preserved. HTTP error-to-response
+handling and observation middleware retain the original handler failure for
+request-scope finalizers; mapping an error to an HTTP response does not turn that
+scope exit into success.
+
 In `@effect/platform-bun`, outgoing WebSocket messages are compressed when
 per-message deflate is configured **and negotiated**. The server option
 `websocket.compressionThreshold` sets the minimum byte size (default `1024`);
@@ -661,7 +688,7 @@ smaller messages stay uncompressed. Configure it alongside
 `websocket.perMessageDeflate` on `BunHttpServer.layer` rather than pre-compressing
 application payloads. See `packages/platform/bun/src/BunHttpServer.ts`.
 
-`request.upgrade` yields a `Socket` (from `effect/unstable/socket`) once the connection is upgraded. Both `NodeHttpServer` and `BunHttpServer` handle the platform `upgrade` events for you — just write a normal route:
+`request.upgrade` yields a `Socket` (from `effect/socket`) once the connection is upgraded. Both `NodeHttpServer` and `BunHttpServer` handle the platform `upgrade` events for you — just write a normal route:
 
 ```ts
 const WsRoute = HttpRouter.add('GET', '/ws', Effect.gen(function* () {
@@ -755,6 +782,9 @@ const { handler: appHandler, dispose: disposeApp } = HttpRouter.toWebHandler(
 
 Every request runs in a fresh `Scope` closed after the response is sent — `Effect.addFinalizer` in a handler runs post-response. Streaming bodies transfer the scope to the stream (`HttpEffect.scopeTransferToStream`, applied automatically by the adapters), so it closes when the body finishes streaming. If the client disconnects mid-request, the handler fiber is interrupted with the `ClientAbort` annotation (logged as `499`).
 
+For failed handlers, request-scope finalizers receive the original failure even
+when boundary handling successfully sends an error response.
+
 ### Integration tests on an ephemeral port
 
 `NodeHttpServer.layerTest` starts a real server on port 0 and provides an `HttpClient` whose requests are rewritten to it:
@@ -762,7 +792,7 @@ Every request runs in a fresh `Scope` closed after the response is sent — `Eff
 ```ts
 import { NodeHttpServer } from '@effect/platform-node';
 import { describe, expect, it } from '@effect/vitest';
-import { HttpClient, HttpClientResponse } from 'effect/unstable/http';
+import { HttpClient, HttpClientResponse } from 'effect/http';
 
 describe('todos', () => {
 	it.effect('GET /todos/:id', () =>
@@ -798,7 +828,7 @@ import {
 	HttpServerRespondable,
 	HttpServerResponse,
 	HttpStaticServer
-} from 'effect/unstable/http';
+} from 'effect/http';
 import { NodeHttpServer, NodeRuntime } from '@effect/platform-node';
 import { createServer } from 'node:http';
 
@@ -930,7 +960,7 @@ describe('health', () => {
 ## Common Mistakes
 
 1. **Using the v3 value-style router** — `HttpRouter.empty.pipe(HttpRouter.get('/x', app))` no longer exists. The v4 router is a service: register routes with `HttpRouter.add(...)` Layers (or `router.add` inside `HttpRouter.use`) and run with `HttpRouter.serve(appLayer)`.
-2. **Importing from `@effect/platform`** — gone in v4. Everything is `effect/unstable/http`; only the platform adapters live in `@effect/platform-node` / `@effect/platform-bun`.
+2. **Importing from `@effect/platform`** — gone in v4. Everything is `effect/http`; only the platform adapters live in `@effect/platform-node` / `@effect/platform-bun`.
 3. **Treating `HttpServerResponse.json` as synchronous** — it returns `Effect<HttpServerResponse, HttpBodyError>`. `yield*` it, or use `jsonUnsafe` for known-serializable values. Same for `schemaJson` (which is also curried: `schemaJson(schema)(value, options)`).
 4. **Expecting `HttpServerResponse.empty()` to be 200** — the default status is `204`. Pass `{ status: 200 }` if you need it.
 5. **Modifying the response in `HttpRouter.serve`'s `middleware` option** — that middleware wraps the chain *after* response sending; changes are silently dropped. Use `HttpRouter.middleware(..., { global: true })` or route-scoped `HttpRouter.middleware` instead.

package/skills/effect-incremental-migration/SKILL.md

@@ -85,7 +85,7 @@ export namespace MyModule {
 				return yield* db.findById(cfg.table, id);
 			});
 
-			const list = Effect.fn('MyModule.list')(function* () {
+			const list = Effect.gen(function* () {
 				const cfg = yield* config.get();
 				return yield* db.listAll(cfg.table);
 			});
@@ -127,6 +127,7 @@ export const defaultLayer = Layer.suspend(() =>
 
 A shared `memoMap` ensures layers are deduplicated across all per-service runtimes. Define the bridge utility once and reuse it across migrated modules.
 
+<!-- typecheck -->
 ```typescript
 import { Layer, ManagedRuntime } from 'effect';
 import type { Effect, Context } from 'effect';
@@ -137,13 +138,13 @@ export function makeRuntime<I, S, E>(
 	service: Context.Service<I, S>,
 	layer: Layer.Layer<I, E>
 ) {
-	let rt: ManagedRuntime.ManagedRuntime<I, E> | undefined;
-	const getRuntime = () => (rt ??= ManagedRuntime.make(layer, { memoMap }));
+	const runtime = ManagedRuntime.make(layer, { memoMap });
 	return {
 		runPromise: <A, Err>(fn: (svc: S) => Effect.Effect<A, Err, I>) =>
-			getRuntime().runPromise(service.use(fn)),
+			runtime.runPromise(service.use(fn)),
 		runSync: <A, Err>(fn: (svc: S) => Effect.Effect<A, Err, I>) =>
-			getRuntime().runSync(service.use(fn))
+			runtime.runSync(service.use(fn)),
+		dispose: () => runtime.dispose()
 	};
 }
 ```
@@ -151,9 +152,15 @@ export function makeRuntime<I, S, E>(
 Then in the module namespace, create the bridge from the service and its default layer:
 
 ```typescript
-const { runPromise } = makeRuntime(MyModule.Service, MyModule.defaultLayer);
+const { runPromise, dispose } = makeRuntime(MyModule.Service, MyModule.defaultLayer);
 ```
 
+`ManagedRuntime.make` builds the layer lazily on first use, so no separate lazy
+runtime variable is needed. The host owns the bridge: stop admitting work and
+await `dispose()` on shutdown. Disposal interrupts managed fibers and waits for
+their cleanup before releasing layer resources. A shared memo map deduplicates
+acquisition, but does not remove each runtime's disposal obligation.
+
 > **Memo-map nuance:** Keep the bridge `memoMap` shared (the root `Layer.makeMemoMapUnsafe()` above) so every per-service runtime reuses the same layer allocations. Do not `Layer.forkMemoMap` it unless a specific child runtime intentionally needs isolated allocations — a forked memo map can read the parent's existing allocations but builds new ones in isolation, which defeats the deduplication this bridge exists to provide.
 
 ### Step 6: Keep Boundary Facades Only When Still Needed
@@ -297,7 +304,7 @@ export namespace Items {
 				});
 			});
 
-			const list = Effect.fn('Items.list')(function* () {
+			const list = Effect.gen(function* () {
 				const cfg = yield* config.load();
 				const res = yield* Effect.tryPromise({
 					try: () => fetch(`${cfg.apiUrl}/items`),
@@ -321,7 +328,9 @@ export namespace Items {
 	);
 
 	// Step 5: Runtime bridge
-	const { runPromise } = makeRuntime(Service, defaultLayer);
+	const runtime = makeRuntime(Service, defaultLayer);
+	const { runPromise } = runtime;
+	export const dispose = runtime.dispose; // host awaits this at shutdown
 
 	// Step 6: Async facades (remove once all callers migrate)
 	export async function get(id: string): Promise<Item> {

package/skills/effect-layer-design/SKILL.md

@@ -467,6 +467,14 @@ const program = Effect.all([
 error type. Preloading a LayerMap does not make future resource acquisition
 infallible; its accessors retain the resource error channel.
 
+Construct keyed layers with a lookup function and options:
+`LayerMap.make(lookup, { preloadKeys, idleTimeToLive })`.
+`fromRecord` and `LayerMap.Service` also support preloading. In all forms, keys
+with zero idle TTL are skipped, including when TTL is omitted. Set a non-zero
+`idleTimeToLive` to eagerly acquire and validate preloaded keys during
+construction; otherwise errors surface on first access. Preloaded resources
+remain retained only for that idle TTL, not forever.
+
 Handle construction errors:
 
 ```typescript

package/skills/effect-managed-runtime/SKILL.md

@@ -124,6 +124,12 @@ Return `Exit<A, E | ER>` instead of throwing — useful when you want to inspect
 
 ManagedRuntime **owns the scope** of the layers it builds. When you dispose the runtime, all resources acquired during layer construction (database pools, HTTP clients, file handles, etc.) are released.
 
+Disposal first interrupts managed fibers and **waits for their finalizers**, then
+releases layer resources. Request cleanup can therefore still use its database
+or other layer services. Layer finalization runs uninterruptibly by default;
+await `dispose()` / `disposeEffect` before treating shutdown as complete. This
+ordering does not supervise work deliberately detached from the runtime.
+
 ### Disposing the runtime
 
 ```ts