opencode-effect-enforcer 0.2.8 → 0.3.0

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

@@ -3,25 +3,25 @@ name: effect-rpc-server
 description: Serve RpcGroup contracts with Effect's RpcServer — handler layers (RpcGroup.toLayer/toLayerHandler), protocol layers (HTTP, WebSocket, TCP, stdio, worker), RpcSerialization, server middleware, streaming results, interruption and shutdown semantics, RpcTest. Use when implementing the server side of an Effect RPC API, mounting RPC on an HttpRouter or existing HTTP app, choosing a wire format, implementing RpcMiddleware, handling client aborts, or testing RPC handlers.
 ---
 
-You are an Effect TypeScript expert specializing in serving RPC groups with `RpcServer` from `effect/unstable/rpc`.
+You are an Effect TypeScript expert specializing in serving RPC groups with `RpcServer` from `effect/rpc`.
 
-Everything ships from the `effect` package under `effect/unstable/rpc` — there is no `@effect/rpc` package in v4. This skill covers the **server side**: implementing handlers, transports, serialization, middleware, and lifecycle. For defining `Rpc`/`RpcGroup` contracts see the `effect-rpc-api` skill; for building clients see the `effect-rpc-client` skill; for cluster entities see the `effect-rpc-cluster` skill; for `HttpRouter`/`HttpServer` fundamentals see the `effect-http-server` skill.
+Everything ships from the `effect` package under `effect/rpc` — there is no `@effect/rpc` package in v4. This skill covers the **server side**: implementing handlers, transports, serialization, middleware, and lifecycle. For defining `Rpc`/`RpcGroup` contracts see the `effect-rpc-api` skill; for building clients see the `effect-rpc-client` skill; for cluster entities see the `effect-rpc-cluster` skill; for `HttpRouter`/`HttpServer` fundamentals see the `effect-http-server` skill.
 
 ## 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 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 APIs remain `@stability unstable` and may break in minor releases. Keep Effect-family packages on the same release.
 
 Key files:
 
-- `packages/effect/src/unstable/rpc/RpcServer.ts` — `make`, `makeNoSerialization`, `layer`, `layerHttp`, every `layerProtocol*` / `makeProtocol*`, `toHttpEffect*`, the `Protocol` service
-- `packages/effect/src/unstable/rpc/RpcGroup.ts` — `toLayer`, `toLayerHandler`, `toHandlers`, `accessHandler`, `of`, handler type derivation
-- `packages/effect/src/unstable/rpc/Rpc.ts` — `ServerClient`, `Handler`, `ToHandlerFn`, `ResultFrom`, `fork`, `uninterruptible`, `ServicesServer`
-- `packages/effect/src/unstable/rpc/RpcMiddleware.ts` — `Service` constructor, server middleware function shape, `layerClient`
-- `packages/effect/src/unstable/rpc/RpcSerialization.ts` — JSON, NDJSON, JSON-RPC, and SchemaBinary parsers and layers
-- `packages/effect/src/unstable/rpc/RpcMessage.ts` — the wire vocabulary (`Request`, `Ack`, `Interrupt`, `Eof`, `Chunk`, `Exit`, `Defect`, `ClientEnd`)
-- `packages/effect/src/unstable/rpc/RpcWorker.ts` — `InitialMessage` for worker transports
-- `packages/effect/src/unstable/rpc/RpcTest.ts` — in-process test client
-- `packages/effect/src/unstable/rpc/RpcSchema.ts` — `ClientAbort` cause annotation, stream schema markers
+- `packages/effect/src/rpc/RpcServer.ts` — `make`, `makeNoSerialization`, `layer`, `layerHttp`, every `layerProtocol*` / `makeProtocol*`, `toHttpEffect*`, the `Protocol` service
+- `packages/effect/src/rpc/RpcGroup.ts` — `toLayer`, `toLayerHandler`, `toHandlers`, `accessHandler`, `of`, handler type derivation
+- `packages/effect/src/rpc/Rpc.ts` — `ServerClient`, `Handler`, `ToHandlerFn`, `ResultFrom`, `fork`, `uninterruptible`, `ServicesServer`
+- `packages/effect/src/rpc/RpcMiddleware.ts` — `Service` constructor, server middleware function shape, `layerClient`
+- `packages/effect/src/rpc/RpcSerialization.ts` — JSON, NDJSON, JSON-RPC, and SchemaBinary parsers and layers
+- `packages/effect/src/rpc/RpcMessage.ts` — the wire vocabulary (`Request`, `Ack`, `Interrupt`, `Eof`, `Chunk`, `Exit`, `Defect`, `ClientEnd`)
+- `packages/effect/src/rpc/RpcWorker.ts` — `InitialMessage` for worker transports
+- `packages/effect/src/rpc/RpcTest.ts` — in-process test client
+- `packages/effect/src/rpc/RpcSchema.ts` — `ClientAbort` cause annotation, stream schema markers
 - `packages/platform/node/test/RpcServer.test.ts` + `test/fixtures/rpc-{schemas,e2e}.ts` — the best end-to-end reference for real wiring across http/ws/tcp transports and every serialization
 - `packages/platform/browser/test/fixtures/rpc-worker.ts` — minimal worker-side server entrypoint
 
@@ -60,7 +60,7 @@ Imports used throughout:
 
 ```ts
 import { Cause, Context, Deferred, Effect, Layer, Queue, Schema, Stream } from 'effect';
-import { Headers, HttpRouter } from 'effect/unstable/http';
+import { Headers, HttpRouter } from 'effect/http';
 import {
 	Rpc,
 	RpcGroup,
@@ -71,7 +71,7 @@ import {
 	RpcServer,
 	RpcTest,
 	RpcWorker
-} from 'effect/unstable/rpc';
+} from 'effect/rpc';
 ```
 
 Running example group (definition details belong to the `effect-rpc-api` skill):
@@ -255,6 +255,14 @@ const ServerLayer = RpcServer.layerHttp({
 
 The protocol layers register routes on `HttpRouter`; `HttpRouter.serve` provides the router and turns it into an HTTP app:
 
+Keep the protocol/server composition inside the app passed to `serve` (or
+`toWebHandler`/`toHttpEffect`). `serve` and `toHttpEffect` build a fresh router in a
+forked layer memo map; `toWebHandler` builds separately by default but uses any
+explicit `memoMap` as supplied. Do not pre-provide `HttpRouter.layer` to the RPC route layer;
+that registers on a router the entrypoint does not serve. If sibling servers need
+the same stateful handler dependencies, provide those services outside their
+entrypoints; layers first built inside an app are private to that app.
+
 ```ts
 import { createServer } from 'node:http';
 import { NodeHttpServer, NodeRuntime } from '@effect/platform-node';
@@ -268,6 +276,27 @@ NodeRuntime.runMain(Layer.launch(Main));
 
 See the `effect-http-server` skill for `HttpRouter.serve` options (middleware, `disableLogger`, `disableListenLog`) and adding sibling routes.
 
+The same route composition can be built without any platform dependency:
+
+<!-- typecheck -->
+```ts
+import { Effect, Layer } from 'effect';
+import * as Schema from 'effect/Schema';
+import { HttpRouter } from 'effect/http';
+import { Rpc, RpcGroup, RpcSerialization, RpcServer } from 'effect/rpc';
+
+const Pings = RpcGroup.make(Rpc.make('Ping', { success: Schema.String }));
+const Handlers = Pings.toLayer({ Ping: () => Effect.succeed('pong') });
+const Routes = RpcServer.layerHttp({
+	group: Pings,
+	path: '/rpc',
+	protocol: 'http'
+}).pipe(Layer.provide([Handlers, RpcSerialization.layerNdjson]));
+
+// Keep this construction scope alive while using the returned HTTP effect.
+const makeHttpEffect = HttpRouter.toHttpEffect(Routes);
+```
+
 ---
 
 ## 3. Protocol Layers — Picking a Transport
@@ -386,6 +415,12 @@ Rules, verified against the protocol implementations and the e2e matrix:
 
 Client and server must use the **same** serialization.
 
+NDJSON skips malformed lines so later frames still decode; JSON-RPC skips
+non-object messages and checks notification method types before interpreting
+internal messages. Continue validating procedure payloads through the contract.
+Custom encoded-interrupt consumers must allow `fiberId: null` as well as
+`undefined`, matching JSON-encoded `RpcMessage.ExitEncoded` values.
+
 ---
 
 ## 5. Embedding in an Existing HTTP App
@@ -512,7 +547,7 @@ StreamUsers: Effect.fnUntraced(function* (payload) {
 Semantics, verified against `RpcServer.makeNoSerialization`:
 
 - The server batches available values into `Chunk` messages (`Stream.runForEachArray` / `Queue.takeAll`), so one message can carry many elements.
-- **Backpressure** exists only on ack-supporting transports (everything except plain HTTP): after writing a chunk the server waits for the client's `Ack` before pulling more. Over plain HTTP the producer is never throttled.
+- **RPC acknowledgment backpressure** exists on ack-supporting transports: after writing a chunk the server waits for the client's `Ack` before pulling more. Framed HTTP has no RPC acks but still backpressures producers through its bounded response queue (`streamBufferSize`, default 16).
 - **Ending**: a `Stream` ending ends the response; for the queue form call `Queue.end(queue)` — `Cause.Done` is the end-of-stream signal, and `Queue.end` only typechecks when the queue's error channel includes it, so create the queue as `Queue.bounded<User, Cause.Done>(16)`. The client then sees the stream complete with a final void `Exit`.
 - **Failures**: failing the stream with the rpc's declared error fails the client's stream with that typed error.
 - The client consumes the result as a `Stream` by default or a `Queue.Dequeue` with `{ asQueue: true }` — see the `effect-rpc-client` skill.
@@ -545,6 +580,7 @@ Never: () =>
 
 - **HTTP**: if the request's scope closes before responses finish (client went away), the protocol sends an `Interrupt` for every request id from that HTTP call.
 - **Sockets/WebSockets**: a closed connection is pushed to the protocol's `disconnects` queue; the server interrupts all of that client's in-flight fibers.
+- **HTTP WebSocket upgrades**: Node/Bun scope cleanup sends `1000` on success, `1001` for interruption-only exits, or `1011` on failure, preserving an explicit close code already sent. The HTTP request scope retains the handler failure through error-response handling and observation middleware.
 - An `Interrupt` for an unknown/finished request id is answered with `Exit.interrupt()` — interruption is idempotent.
 
 ### `Rpc.uninterruptible`
@@ -572,7 +608,7 @@ Worker entrypoint (browser shown; for Node use `NodeWorkerRunner.layer` from `@e
 // worker.ts
 import { BrowserWorkerRunner } from '@effect/platform-browser';
 import { Effect, Layer } from 'effect';
-import { RpcServer } from 'effect/unstable/rpc';
+import { RpcServer } from 'effect/rpc';
 
 const MainLive = RpcServer.layer(UserRpcs).pipe(
 	Layer.provide(UsersLive),
@@ -609,7 +645,7 @@ Wires `RpcServer.makeNoSerialization` to a no-serialization client. Requests, st
 
 ```ts
 import { assert, it } from '@effect/vitest';
-import { RpcClient } from 'effect/unstable/rpc';
+import { RpcClient } from 'effect/rpc';
 
 class UsersClient extends Context.Service<
 	UsersClient,
@@ -684,8 +720,8 @@ The decoded core with no transport at all: you push `FromClient<Rpcs>` messages
 import { createServer } from 'node:http';
 import { NodeHttpServer, NodeRuntime } from '@effect/platform-node';
 import { Effect, Layer } from 'effect';
-import { HttpRouter } from 'effect/unstable/http';
-import { RpcSerialization, RpcServer } from 'effect/unstable/rpc';
+import { HttpRouter } from 'effect/http';
+import { RpcSerialization, RpcServer } from 'effect/rpc';
 import { SecureRpcs } from '../domain/rpc.ts';
 
 const UsersLive = SecureRpcs.toLayer(
@@ -773,7 +809,7 @@ const ServerLayer = RpcServer.layer(StoreRpcs, { concurrency: 1 }).pipe(
 
 ## Common Mistakes
 
-1. **Importing from `@effect/rpc`.** v3 habit; the package does not exist in v4. Everything is `effect/unstable/rpc` (and platform layers come from `@effect/platform-node` / `-bun` / `-browser`).
+1. **Importing from `@effect/rpc`.** v3 habit; the package does not exist in v4. Everything is `effect/rpc` (and platform layers come from `@effect/platform-node` / `-bun` / `-browser`).
 2. **Forgetting `protocol: 'http'` on `layerHttp`.** The default is `'websocket'` — your `POST /rpc` curl returns 404 and only a `GET` upgrade route exists. Also note `layerHttp` takes `{ group, path, ... }` as one options bag, while `layer(group, options)` takes the group positionally.
 3. **Providing handlers/middleware but no `Protocol` or `RpcSerialization`.** `RpcServer.layer` requires all of: handler layer(s), middleware implementation layers, a `layerProtocol*`, and (for non-worker protocols) a `RpcSerialization.layer*`. Missing ones surface as unresolved layer requirements.
 4. **`layerJson` on a raw TCP socket server.** Sockets need `layerNdjson`, `layerNdJsonRpc()`, or `layerSchemaBinary()` for framing. WebSocket supplies its own framing and supports `layerJson`.

package/skills/effect-scheduling/SKILL.md

@@ -7,7 +7,11 @@ You are an Effect TypeScript expert specializing in `Schedule`, retry, repeat, p
 
 ## Source Of Truth
 
-Verify APIs against `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/packages/effect/src/Schedule.ts` and `Effect.ts`. In Effect v4, `Schedule.concat` is current, `Schedule.tapInput` is absent, and `Schedule.tap` receives full metadata.
+Verify APIs against `packages/effect/src/Schedule.ts` and `Effect.ts` at the
+installed release tag in `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`.
+The `effect@4.0.0` tag has no `cookbooks/schedule.md`; its runnable schedule guide
+is `ai-docs/src/06_schedule/10_schedules.ts`. In Effect v4, `Schedule.concat` is
+current, `Schedule.tapInput` is absent, and `Schedule.tap` receives full metadata.
 
 ## Semantics
 
@@ -22,12 +26,14 @@ incorrect delay, retryAfter, and resetAfter values.
 - `Effect.repeat` reruns successes. A typed failure stops repetition unless the pass handles it first.
 - The source effect runs once before the schedule is stepped.
 - `Schedule.recurs(3)` permits three recurrences after the initial evaluation: at most four evaluations total.
+- `Schedule.once` permits one immediate recurrence and outputs `void` on both recurrence and completion. `Effect.repeat(task, Schedule.once)` evaluates `task` twice, not once.
 - Schedules can require services and fail; schedule errors join the resulting effect's error channel.
 - Retry only the narrowest idempotent operation. Never retry non-idempotent writes unless an idempotency key, transaction, or equivalent guarantee makes replay safe.
 
 ## Policy Chooser
 
 - Counter only: `Schedule.recurs(n)`.
+- One immediate recurrence, no counter output: `Schedule.once` (a value, not a function).
 - Delay after each completed run: `Schedule.spaced(duration)`.
 - Cadence aligned to time boundaries: `Schedule.fixed(interval)`; slow work may make the next run immediate, and missed ticks are not replayed.
 - Backoff: `Schedule.exponential(base)` or `Schedule.fibonacci(base)`.
@@ -75,6 +81,28 @@ const numericDates = mixed.pipe(
 
 ## Polling And Item Failure Policy
 
+### Bounded repetition and refinement
+
+With predicate-only `Effect.repeat`, an `until` refinement narrows the final
+result to the matched type; a `while` refinement excludes the continuing type.
+Adding `times` or `schedule` preserves the **full source result type** because
+the bound can stop repetition before the predicate does. This also applies when
+`times` is optional in the options type. Check the returned value before using
+fields that only exist on the desired terminal variant.
+
+<!-- typecheck -->
+```ts
+import { Effect, Schedule } from 'effect';
+import * as Option from 'effect/Option';
+
+declare const poll: Effect.Effect<Option.Option<string>>;
+
+const bounded: Effect.Effect<Option.Option<string>> = poll.pipe(
+	Effect.repeat({ until: Option.isSome, times: 3 })
+);
+const twice = Effect.repeat(Effect.succeed('tick'), Schedule.once);
+```
+
 Use `Effect.repeat(pass, Schedule.spaced(...))` for a worker that emits no meaningful values. Use `Stream.fromEffectSchedule` when each result is part of a stream pipeline.
 
 Decide failures at the correct granularity:

package/skills/effect-schema-composition/SKILL.md

@@ -164,13 +164,13 @@ import { Schema } from 'effect';
 Schema.String.check(Schema.isMaxLength(5));
 Schema.String.check(Schema.isMinLength(5));
 Schema.String.check(Schema.isNonEmpty()); // non-empty string
-Schema.String.check(Schema.isLengthBetween(2, 4));
+Schema.String.check(Schema.isBetweenLength(2, 4));
 
 // Pattern matching
 Schema.String.check(Schema.isPattern(/^[a-z]+$/));
-Schema.String.check(Schema.isStartsWith('prefix'));
-Schema.String.check(Schema.isEndsWith('suffix'));
-Schema.String.check(Schema.isIncludes('substring'));
+Schema.String.check(Schema.isStartingWith('prefix'));
+Schema.String.check(Schema.isEndingWith('suffix'));
+Schema.String.check(Schema.isIncluding('substring'));
 
 // Case and whitespace validation
 Schema.String.check(Schema.isTrimmed()); // No leading/trailing whitespace
@@ -185,6 +185,16 @@ Schema.String.check(Schema.isBase64());
 Schema.String.check(Schema.isBase64Url());
 ```
 
+For string length, choose the unit deliberately: `isMinLength`, `isMaxLength`,
+and `isBetweenLength` count UTF-16 code units; `isMinCodePoints`,
+`isMaxCodePoints`, and `isBetweenCodePoints` count Unicode code points, not
+grapheme clusters. The latter match JSON Schema length semantics and guide
+native Arbitrary generation. Cardinality bounds must be finite.
+
+JSON Schema export can approximate runtime checks. Use the Effect decoder as
+the final authority; see `effect-schema-v4` for exact/approximate check exporters,
+Unicode patterns, and `oneOf` fallback semantics.
+
 ### Number Filters
 
 ```typescript
@@ -220,7 +230,7 @@ import { Schema } from 'effect';
 
 Schema.Array(Schema.Number).check(Schema.isMinLength(2));
 Schema.Array(Schema.Number).check(Schema.isMaxLength(5));
-Schema.Array(Schema.Number).check(Schema.isLengthBetween(2, 5));
+Schema.Array(Schema.Number).check(Schema.isBetweenLength(2, 5));
 ```
 
 ### Combining Multiple Filters
@@ -329,6 +339,7 @@ const MyForm = Schema.Struct({
 
 Use `SchemaGetter.checkEffect` for async validation inside a `Schema.decode` transformation:
 
+<!-- typecheck -->
 ```typescript
 import {
 	Effect,
@@ -345,14 +356,14 @@ async function validateUsername(username: string) {
 
 const ValidUsername = Schema.String.pipe(
 	Schema.decode({
-		decode: SchemaGetter.checkEffect((username) =>
+		decode: SchemaGetter.checkEffect((username, options) =>
 			Effect.promise(() =>
 				validateUsername(username).then((valid) =>
 					valid
 						? undefined
-						: new SchemaIssue.InvalidValue(Option.some(username), {
-								title: 'Invalid username'
-							})
+						: new SchemaIssue.InvalidValue(
+								{ message: 'Invalid username' }, username, options
+							)
 				)
 			)
 		),
@@ -467,7 +478,7 @@ function split(separator: string) {
 
 ### Schema-derived binary boundaries
 
-Use `SchemaBinary.toCodec(schema)` from `effect/unstable/encoding` for a compact
+Use `SchemaBinary.toCodec(schema)` from `effect/encoding` for a compact
 `Uint8Array` representation. It derives the wire layout from the schema's
 **encoded side**, preserving transformations, checks, and decoding/encoding
 services. Use public Schema encode/decode adapters; `toCodecDirect` and the
@@ -477,7 +488,7 @@ module's internal fast-path functions are not application APIs.
 ```ts
 import { Effect } from 'effect';
 import * as Schema from 'effect/Schema';
-import { SchemaBinary } from 'effect/unstable/encoding';
+import { SchemaBinary } from 'effect/encoding';
 
 class Reading extends Schema.Class<Reading>('Reading')({
 	id: Schema.String,
@@ -539,6 +550,7 @@ const BooleanFromString = Schema.Literals(['on', 'off']).pipe(
 
 Use `SchemaTransformation.transformEffect` when transformation might fail:
 
+<!-- typecheck -->
 ```typescript
 import {
 	Effect,
@@ -551,11 +563,11 @@ import {
 
 const NumberFromString = Schema.String.pipe(
 	Schema.decodeTo(Schema.Number, {
-		decode: SchemaGetter.transformEffect((s) =>
+		decode: SchemaGetter.transformEffect((s, options) =>
 			Option.match(Number.parse(s), {
 				onNone: () =>
 					Effect.fail(
-						new SchemaIssue.InvalidValue(Option.some(s))
+						new SchemaIssue.InvalidValue({ expected: 'a number' }, s, options)
 					),
 				onSome: (n) => Effect.succeed(n)
 			})
@@ -945,6 +957,12 @@ const AuthToken = Schema.TemplateLiteralParser(authTemplate.parts);
 
 ### Branded Types
 
+Brands are type-only: `Schema.brand` does not add checks or change the runtime
+AST. Pass a single concrete string literal and apply it repeatedly to compose
+brands. `Schema.fromBrand` additionally applies a constructor's checks, and its
+identifier must be that constructor's sole brand key. Representation round trips
+preserve checks, but not nominal brands; reapply brands after rebuilding.
+
 ```typescript
 import { Schema } from 'effect';
 

package/skills/effect-schema-v4/SKILL.md

@@ -35,7 +35,7 @@ schema helpers so concrete schema operations are retained.
 | `typeSchema(schema)`          | `toType(schema)`                    |                                           |
 | `asSchema(schema)`            | `revealCodec(schema)`               |                                           |
 | `equivalence()`               | `toEquivalence()`                   |                                           |
-| `arbitrary()`                 | `Arbitrary.schema(schema)`          | Native `effect/unstable/arbitrary`; fast-check bridge removed |
+| `arbitrary()`                 | `Arbitrary.schema(schema)`          | Native `effect/Arbitrary`; fast-check bridge removed |
 | `pretty()`                    | `toFormatter()`                     |                                           |
 | `parseJson()`                 | `fromJsonString(Schema.Unknown)`    | Public unknown-JSON codec |
 | `parseJson(schema)`           | `fromJsonString(schema)`            | With-schema version                       |
@@ -145,10 +145,35 @@ Schema.Number.check(Schema.isGreaterThan(0));
 | `finite`                  | `isFinite()`                      |
 | `minLength(n)`            | `isMinLength(n)`                  |
 | `maxLength(n)`            | `isMaxLength(n)`                  |
-| `length(n)`               | `isLengthBetween(n, n)`           |
+| `length(n)`               | `isBetweenLength(n, n)`           |
 | `pattern(regex)`          | `isPattern(regex)`                |
 | `nonEmptyString`          | `isNonEmpty()`                    |
 
+Use `isBetweenLength`, `isBetweenCodePoints`, `isBetweenSize`, and
+`isBetweenProperties` for range checks, and `isStartingWith`, `isEndingWith`,
+and `isIncluding` for string checks. Their `SchemaRepresentation.*Reviver`
+exports and persisted `effect/schema/...` check IDs use these same names;
+update persisted representations as well as source calls.
+
+### String length semantics
+
+`isMinLength`, `isMaxLength`, and `isBetweenLength` count UTF-16 code units on
+strings and elements on arrays. Use `isMinCodePoints`, `isMaxCodePoints`, and
+`isBetweenCodePoints` for Unicode code point counts, matching JSON Schema length
+keywords. Code points are not grapheme clusters; these checks do not normalize
+strings, and unpaired surrogates each count as one code point. Cardinality bounds
+must be finite; they are rounded down and clamped to zero.
+
+<!-- typecheck -->
+```ts
+import * as Schema from 'effect/Schema';
+
+const OneCodePoint = Schema.String.check(Schema.isBetweenCodePoints(1, 1));
+const OneCodeUnit = Schema.String.check(Schema.isBetweenLength(1, 1));
+Schema.is(OneCodePoint)('😀'); // true
+Schema.is(OneCodeUnit)('😀'); // false
+```
+
 ### Removed Filters (no v4 equivalent)
 
 `positive`, `negative`, `nonNegative`, `nonPositive` — build these yourself:
@@ -252,11 +277,11 @@ import {
 
 const NumberFromString = Schema.String.pipe(
 	Schema.decodeTo(Schema.Number, {
-		decode: SchemaGetter.transformEffect((s) =>
+		decode: SchemaGetter.transformEffect((s, options) =>
 			Option.match(Number.parse(s), {
 				onNone: () =>
 					Effect.fail(
-						new SchemaIssue.InvalidValue(Option.some(s))
+						new SchemaIssue.InvalidValue({ expected: 'a number' }, s, options)
 					),
 				onSome: (n) => Effect.succeed(n)
 			})
@@ -278,6 +303,35 @@ Schema.Literal(0).transform('a');
 Schema.Literals([0, 1]).transform(['a', 'b']);
 ```
 
+### Brands are type-only
+
+`Schema.brand('UserId')` adds a nominal TypeScript distinction, not a runtime
+check or AST annotation. Apply checks before branding. The identifier must be
+one concrete string literal: widened strings, unions, and open template literal
+types are rejected. Compose distinct brands by applying `brand` repeatedly.
+For an enum key, pass the enum member rather than its underlying string value.
+
+`Schema.fromBrand(identifier, constructor)` requires the constructor's sole
+concrete brand key and applies its checks. Compose distinct constructors through
+repeated `fromBrand` calls; use `Schema.Union` for alternatives.
+
+Representations and generated schema code do not retain type-only brands.
+Reapply branding after rebuilding a schema when the nominal type is required;
+checks supplied by `fromBrand` remain represented. Use an explicit `identifier`
+annotation for reference naming instead of relying on the brand name.
+
+<!-- typecheck -->
+```ts
+import * as Schema from 'effect/Schema';
+
+const UserId = Schema.NonEmptyString.pipe(Schema.brand('UserId'));
+const TenantUserId = UserId.pipe(Schema.brand('TenantScoped'));
+type TenantUserId = typeof TenantUserId.Type;
+
+const id: TenantUserId = Schema.decodeUnknownSync(TenantUserId)('user-1');
+// Both brands are static distinctions; runtime validation is NonEmptyString.
+```
+
 ## 5. Schema.Data Removal
 
 `Schema.Data` is **removed** in v4. No replacement needed — `Equal.equals` now does deep structural comparison on plain objects by default.
@@ -387,7 +441,7 @@ const fallback = SchemaGetter.withDefault(Effect.succeed('viewer'));
 - `Schema.resolveAnnotationsKey(schema)` returns key-level annotations.
 - `Schema.annotateEncoded({...})` annotates the encoded side of a transformed schema; use `Schema.annotate({...})` for the decoded Type side.
 - Schemas are directly extendable as classes.
-- Derive native generators with `Arbitrary.schema(schema)` from `effect/unstable/arbitrary`. See `effect-testing` for sampling, bounded generation, shrinking, and replay.
+- Derive native generators with `Arbitrary.schema(schema)` from `effect/Arbitrary`. See `effect-testing` for sampling, bounded generation, shrinking, and replay.
 - New built-in schemas:
     - `Schema.DateFromString`
     - `Schema.BigIntFromString`
@@ -404,7 +458,7 @@ const fallback = SchemaGetter.withDefault(Effect.succeed('viewer'));
 
 ```ts
 import { Effect, Schema } from 'effect';
-import { Arbitrary } from 'effect/unstable/arbitrary';
+import * as Arbitrary from 'effect/Arbitrary';
 
 class UserName extends Schema.NonEmptyString {
 	static readonly decodeUnknownSync = Schema.decodeUnknownSync(this);
@@ -509,13 +563,40 @@ Neither matcher decodes unknown input. See `effect-pattern-matching` for a check
 
 ### JSON Schema import, conversion, and Standard Schema
 
+- `Schema.toJsonSchemaDocument(schema)` describes the encoded side of
+  `Schema.toCodecJson(schema)`. Decode matching JSON through that codec: for
+  example, its optional string field accepts JSON `null` as `undefined`, while
+  the original `Schema.optional(Schema.String)` rejects `null`.
+- Export is best-effort, and successful JSON Schema validation is not proof that
+  Effect decoding will succeed. Known approximate branches cause `oneOf` to
+  export as `anyOf`; unions with only exact branches retain `oneOf`. Approximation propagates
+  through nested schemas, check dependencies, and recursive references.
+- Custom check `toJsonSchema` callbacks return a fragment for exact semantics,
+  `[fragment, true]` for a safe, looser approximation, or `[{}, true]` to omit a
+  constraint. The compiler trusts that declaration. Approximate record-key
+  patterns cannot select `patternProperties` values; with excess-property mode
+  `"error"`, generated `propertyNames` and permissive candidate value schemas
+  still leave exact key/value associations to the Effect decoder.
+- String code-unit minima export as `Math.ceil(minimum / 2)` code points, and
+  maxima use the same numeric bound but count code points. Code-point checks
+  export exact string bounds. Direct `isPattern` exports omit patterns unless
+  the regex has `u` and only optional `d`, `g`, or `y` flags; sticky patterns are
+  anchored at the start. Casing, safe integers, size, uniqueness, and non-number
+  ranges may also have looser or omitted exported constraints.
 - `SchemaRepresentation.fromJsonSchemaDocument` rejects unsupported references,
   validation keywords, object/array `const` or `enum` values, and intersections
   it cannot represent faithfully. Do not discard the failing constraint to make
   an import succeed.
 - A keyword such as `minLength` does not imply `type: 'string'`. Constraints beside
-  `const`, `enum`, and `$ref` are applied. Imported `oneOf` remains `oneOf` on export,
-  and tuple imports preserve `minItems` even when `prefixItems` alone is insufficient.
+  `const`, `enum`, and `$ref` are applied. Imports preserve `oneOf` mode; re-export
+  follows the approximation rules above. Tuple imports preserve `minItems` even
+  when `prefixItems` alone is insufficient.
+- Imports assume a valid Draft 2020-12 document, without meta-schema validation,
+  and JSON-compatible instance values. Imported string lengths count code points;
+  `patterns: "apply"` compiles in ECMAScript Unicode (`u`) mode and rejects patterns
+  invalid in that mode with their source path. Patterns default to rejection;
+  ignoring them can also reject valid inputs by creating overlapping `oneOf`
+  branches. Import/re-export is not a lossless equivalence guarantee.
 - `JsonSchema` dialect conversion preserves custom keywords and representable
   conditionals, contains, dependencies, identifiers, and tuples; it relocates
   local references and throws for unsupported conversions. These synchronous
@@ -523,7 +604,7 @@ Neither matcher decodes unknown input. See `effect-pattern-matching` for a check
 - Import vendored V1 interoperability types from `effect/StandardSchema`, for
   example `StandardSchemaV1` and `StandardJSONSchemaV1`. Continue to adapt Effect
   schemas with `Schema.toStandardSchemaV1`; the new module is not a schema builder.
-- Binary encoding is available from `effect/unstable/encoding` as `SchemaBinary`.
+- Binary encoding is available from `effect/encoding` as `SchemaBinary`.
   See `effect-schema-composition` for codecs and `effect-stream` for framing.
 
 ## Parsing and compilation contracts
@@ -540,6 +621,9 @@ Neither matcher decodes unknown input. See `effect-pattern-matching` for a check
 - Declared fields may be inherited and are copied to own output properties;
   dynamic record keys remain own-only and `__proto__` remains own-only. Enforce
   ownership at the boundary when the protocol requires own declared fields.
+  Excess-property checks ignore non-enumerable own properties; dynamic string
+  and symbol index signatures skip them too. Declare a field explicitly or make
+  it enumerable when it must survive decoding or encoding.
 - Class `make`, `makeOption`, and `makeEffect` preserve existing instances. Use
   `new MyClass(fields)` for a distinct instance. Class equivalence now compares
   declared fields, excluding unrelated runtime properties.
@@ -562,7 +646,7 @@ Neither matcher decodes unknown input. See `effect-pattern-matching` for a check
   `$id` are rejected; flatten references or explicitly choose to ignore constraints.
 
 Experimental JIT/AOT compilation uses the existing `SchemaParser` APIs. Opt in
-globally with `effect/unstable/schema/SchemaJITCompiler/enable` or selectively with
+globally with `effect/schema/SchemaJITCompiler/enable` or selectively with
 `SchemaJITCompiler.enable(ast)`. AOT's `SchemaAOTCompiler/Build` discovers direct
 schema exports from explicit loaders and writes a self-installing module via
 FileSystem/Path. Choose prepared operations explicitly: omitted operations use

package/skills/effect-scope/SKILL.md

@@ -51,6 +51,7 @@ The `Scope` object itself:
 ```ts
 interface Scope {
 	readonly strategy: 'sequential' | 'parallel';
+	readonly parent: Scope | undefined;
 	state: State.Open | State.Closed | State.Empty;
 }
 interface Closeable extends Scope {} // can be passed to Scope.close
@@ -58,6 +59,11 @@ interface Closeable extends Scope {} // can be passed to Scope.close
 
 `Scope.Scope` is also the `Context` tag for the current scope, so `yield* Scope.Scope` and `yield* Effect.scope` both return it.
 
+`Scope.close` and `Scope.closeUnsafe` require **`Scope.Closeable`**, obtained from
+`Scope.make` / `Scope.fork` (or their unsafe constructors). An ambient
+`Scope.Scope` grants finalizer registration, not authority to close its owner.
+Keep owned scope fields typed `Scope.Closeable`; do not cast a borrowed scope.
+
 Imports used throughout this skill:
 
 ```ts
@@ -181,7 +187,7 @@ Selective variants: `Effect.onExitIf(self, predicate, f)`, `Effect.onExitFilter(
 
 Semantics:
 
-- Finalizers attached with `onExit`/`ensuring` run in an **uninterruptible region** (unless you reach for the low-level `Effect.onExitPrimitive(self, f, interruptible)`, which also allows returning `undefined` to skip finalization).
+- Finalizers attached with `onExit`/`ensuring` run in an **uninterruptible region** by default. Use public combinators rather than internal runtime primitives.
 - If an `onExit` finalizer fails (`f` may have an error channel `XE`), its error joins the result error channel. If both the source and finalizer fail, their causes are combined rather than one replacing the other.
 - `Effect.ensuring` deliberately requires `Effect<X, never, R1>` as its finalizer, so typed finalizer errors must be handled before attachment. A finalizer defect can still occur at runtime and is combined with an existing source failure.
 - These only fire if the effect **starts** executing.
@@ -289,8 +295,8 @@ Constructors and operations (all verified against `Scope.ts`):
 | `Scope.makeUnsafe` | `(strategy?) => Closeable` | synchronous |
 | `Scope.addFinalizer` | `(scope, finalizer: Effect<unknown>) => Effect<void>` | exit-blind |
 | `Scope.addFinalizerExit` | `(scope, (exit) => Effect<unknown>) => Effect<void>` | exit-aware |
-| `Scope.close` | `(scope, exit: Exit<A, E>) => Effect<void>` | idempotent |
-| `Scope.closeUnsafe` | `(scope, exit) => Effect<void> \| undefined` | low-level; **you must run the returned effect** or finalizers are skipped |
+| `Scope.close` | `(scope: Closeable, exit: Exit<A, E>) => Effect<void>` | idempotent; finalizes uninterruptibly by default |
+| `Scope.closeUnsafe` | `(scope: Closeable, exit) => Effect<void> \| undefined` | low-level; **run the returned effect uninterruptibly** or cleanup can be skipped |
 | `Scope.fork` | `(scope, strategy?) => Effect<Closeable>` | child scope, see section 5 |
 | `Scope.forkUnsafe` | `(scope, strategy?) => Closeable` | synchronous |
 | `Scope.provide` / `Scope.use` | dual | see section 3 |
@@ -299,6 +305,7 @@ Close semantics (from `internal/effect.ts` `scopeCloseFinalizers`):
 
 - Finalizers run in **reverse registration order** (LIFO).
 - `'sequential'` (default): one at a time, each awaited. `'parallel'`: all started concurrently, then awaited together.
+- `Scope.close` runs finalizers uninterruptibly by default: interruption of the closing fiber waits for cleanup. A finalizer can explicitly restore interruptibility; avoid doing so unless abandoning that cleanup is intentional.
 - **Every finalizer always runs** — a failing finalizer does not prevent the others. All failures are collected and combined into a single `Cause`; `Scope.close` then fails with that combined cause.
 - When scoped work and scope finalization both fail, the work cause and combined finalizer cause are merged.
 - Closing an already-closed scope is a no-op.
@@ -339,7 +346,7 @@ const program = Effect.gen(function* () {
 `Scope.fork(parent)` creates a `Closeable` child registered with the parent:
 
 - Closing the **parent** closes the child with the same `Exit`.
-- Closing the **child** first detaches it from the parent (the parent no longer tracks it).
+- Closing the **child** first detaches it from the parent before cleanup runs, even if cleanup throws or is interrupted. The readonly `child.parent` still identifies its parent; it is not a liveness indicator.
 - Forking from an **already-closed** parent returns an already-closed child — finalizers added to it run immediately.
 
 This is the splitting primitive: hand part of a lifetime to other code while keeping an upper bound.
@@ -492,6 +499,7 @@ yield* ScopedRef.set(
 Semantics (verified in `ScopedRef.ts` and its tests):
 
 - Constructing requires `Scope.Scope`: when the *outer* scope closes, the currently-held value's scope is closed too.
+- The owner also closes in-flight replacement scopes. `make`, `fromAcquire`, and `set` interrupt if their owning scope has closed; they cannot return or install a resource from a closed generation. Replacements retain the reference's original position in the owner's finalizer order.
 - `set` is **synchronized** (internal semaphore — one replacement at a time) and **uninterruptible**.
 - `set` acquires the replacement first. If acquisition fails, its new scope is closed, the error propagates, and the current value remains alive and unchanged.
 - After successful acquisition, `set` closes the old scope before installing the replacement. If the old finalizer defects, the replacement scope is also closed and the reference is not switched, preventing the newly acquired resource from leaking.
@@ -707,6 +715,6 @@ class Plugin {
 11. **Using `acquireUseRelease` and swallowing release errors unknowingly — or the opposite.** Its release *can* fail; a release failure fails the whole effect after successful `use`, and combines with the use cause after failed `use`. Conversely `acquireRelease`'s release is typed `never` — convert errors inside it.
 12. **Acquiring per-request resources in a `Layer.effect` constructor.** Layer finalizers run when the layer scope closes (shutdown), not per call. Acquire per-request resources inside the request handler under `Effect.scoped`, or fork a child scope per item (section 5).
 13. **v3 fork names**: `Effect.fork` → `Effect.forkChild`, `Effect.forkDaemon` → `Effect.forkDetach`. `forkScoped`/`forkIn` keep their names and now accept `{ startImmediately?, uninterruptible? }`.
-14. **Calling `Scope.closeUnsafe` and dropping the result.** It returns `Effect | undefined`; ignoring the returned effect skips every finalizer. Use `Scope.close` unless you are writing low-level machinery.
+14. **Calling `Scope.closeUnsafe` and dropping or interrupting the result.** It requires `Closeable` and returns `Effect | undefined`; run a returned effect uninterruptibly. The scope is already marked closed, so retrying close cannot recover skipped finalizers. Prefer `Scope.close`.
 15. **Expecting interruption to skip cleanup.** Finalizers receive `Exit.failCause` with an interrupt cause and still run (uninterruptibly). Use exit-aware finalizers (`addFinalizer`, `acquireRelease`'s `(a, exit) =>`) to branch on success/failure/interrupt — don't split cleanup across `onError` + success paths.
 16. **Splitting acquire and `Effect.addFinalizer` into separate yields.** Interruption between the two steps leaks the resource. `acquireRelease` wraps acquisition and finalizer registration in a single `uninterruptibleMask` precisely to close this window — use it whenever cleanup is tied to an acquired value.

package/skills/effect-service-implementation/SKILL.md

@@ -291,7 +291,7 @@ Promote it into its own service when any of these are true:
 
 ```typescript
 // git.ts
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 import { Context, Effect, Layer } from 'effect';
 
 export interface Interface {