opencode-effect-enforcer 0.2.8 → 0.3.0

package/docs/effect-4.0.0.md

@@ -0,0 +1,110 @@
+# Effect 4.0.0-rc.116 → 4.0.0
+
+## Provenance and release scope
+
+- Previous dependency: `effect@4.0.0-rc.116`.
+- Target: **`effect@4.0.0`, the first stable v4 release** and npm's `latest`
+  dist-tag, checked on 2026-10-02. The `rc` tag remains rc.118; it is not the target.
+- npm publication: 2026-10-01 at 03:11:28 UTC. The GitHub release is explicitly
+  non-prerelease, published at 01:47:13 UTC. The release commit is dated September 30.
+- Exact source: [`effect@4.0.0`](https://github.com/Effect-TS/effect/tree/effect%404.0.0),
+  commit `67ba4e46a11ccda0b6761578bfd22c04ae00167d`.
+- [Official release](https://github.com/Effect-TS/effect/releases/tag/effect%404.0.0).
+- [Complete source comparison](https://github.com/Effect-TS/effect/compare/effect%404.0.0-rc.116...effect%404.0.0).
+- [Full upstream release notes](effect-4.0.0-changelog.md): **93 complete release
+  sections across 31 packages**, including dependency-only entries and the stable
+  release overview. All rc.117, rc.118, and 4.0.0 sections are included; rc.116 is
+  excluded. Only trailing whitespace is normalized.
+- Previous audit: [rc.112 → rc.116](effect-4.0.0-rc.116.md).
+
+The moving source reference was already ahead of the release. Contracts were
+checked against the exact tag rather than importing subsequent main-branch fixes.
+The stable release overview describes some features introduced before rc.116;
+the individual entries and source comparison identify this migration's changes.
+
+## Alignment decisions
+
+| Area | Alignment |
+| --- | --- |
+| Packaging | Pin the dependency and lockfile to 4.0.0. Remove the `unstable` import segment throughout live examples, module augmentations, source references, and test fixtures. Use `effect/http-api`, root `Arbitrary`, and format-specific binary-text encoding modules. |
+| Stability | Stable package publication does not stabilize every API. `@stability unstable` APIs may break in minor releases; unmarked APIs follow semver. Directly consumed Effect-family packages use the same version. |
+| Schema | Rename range/string checks; document Unicode units and JSON Schema approximations, persisted check IDs, single/type-only brands, representation round trips, and current issue constructors. |
+| Configuration and CLI | Document dependent configuration, whole-group defaults, fallback-result semantics, and negative-number lexing. |
+| Lifetimes and concurrency | Align partition ordering, closeable scopes, cache waiter ownership, zero-TTL preloading, runtime disposal, queue terminal batches, PubSub completion, races, and bounded repetition. |
+| HTTP and RPC | Isolate entrypoint routers, place routes/protocols in the served app, share stateful services at the parent boundary, expose slot-specific parsing, preserve WebSocket exits, and distinguish missed pongs from connection-open retries. |
+| SQL and workflow | Review savepoint release, failed COMMIT behavior, PostgreSQL session retirement and row codecs, workflow execution-ID derivation, reset retries, and conditional reply clearing. |
+| AI and MCP | Align Toolkit service/error requirements, Decision probability options, streaming deltas, provider compatibility, object-root schemas, and version-specific MCP results/errors. |
+| Reactive state and telemetry | Review registry ownership, SWR refresh timing, concurrent atom calls, batching, SSR hydration, and OTLP response draining/flush lifetimes. |
+| Platform examples | Correct stale byte-size, error, scoped-resource, service-wiring, and process-output examples while retaining the platform abstraction boundaries. |
+| Pattern feedback | Update positive guidance and fixtures to current APIs. Correct construction, decoding, randomness, ordering, defect-handling, service-definition, and HTTP retry examples. Keep the existing detector inventory. |
+
+## Complete audit inventory
+
+Five independently assigned audits covered all **53 skill directories (54 Markdown
+files)**. The integration review covered all **45 pattern definitions**, all
+**four guidance documents**, the runtime's Effect references, dependency wiring,
+and detector fixtures. The historical essays remain conceptual material; current
+baseline and API policy live in the two active guidance documents.
+
+The following table accounts for every skill directory (`effect-` prefix omitted).
+Files with unchanged contracts were reviewed without cosmetic edits.
+
+| Skill directories | Review focus |
+| --- | --- |
+| schema-v4, schema-composition, domain-modeling, domain-predicates, pattern-matching, optics, typeclass-design, graph | Schema contracts, brands, predicates, transformations, representations, orders, and unchanged graph/optic APIs. |
+| config, cli, testing | Config source/fallback behavior, argument lexing, native Arbitrary, Vitest fixtures, and effectful TestSchema assertions. |
+| http-api, http-client, http-server, rpc-api, rpc-client, rpc-server, rpc-cluster, sql, workflow, socket | Router ownership, transport/protocol contracts, parsing, network address representation, transaction/session safety, and durable state compatibility. |
+| ai-chat, ai-language-model, ai-prompt, ai-provider, ai-streaming, ai-tool, mcp-server | Model/tool requirements, provider translations, response histories, streaming, and MCP protocol versions. |
+| atom-rpc, atom-state, react-composition, observability, wide-events | Reactive lifecycle, React peers, registry/hydration, exporters, and wide-event guidance including its accompanying article. |
+| cache, batching, layer-design, scope, service-implementation, context-witness, managed-runtime, incremental-migration | Acquisition/interruption, memoization, dependency capture, runtime ownership, and boundary integration. |
+| fiber, parallelization, concurrency-testing, pubsub-event-bus, stream, scheduling, error-handling | Partition order, cancellation/cleanup, queue completion, scheduling, typed failures, and defects. |
+| filesystem, path, platform-abstraction, platform-layers, command-executor | File and process services, portable paths, errors, byte sizes, test doubles, layer precedence, and output draining. |
+
+## Compatibility considerations
+
+- This plugin directly depends only on `effect` from the Effect family. Companion
+  libraries in examples are reviewed against 4.0.0 source; they are not added as
+  plugin runtime dependencies.
+- TypeScript 5.9 or newer is required. The repository already satisfies that
+  minimum. `@effect/vitest` and `@effect/doctest` require Vitest 5; this repository
+  uses plain Vitest without those adapters, so its runner need not change.
+- `@effect/atom-react` requires React 19. Deno adapters require Deno 2.8.3 or newer.
+- Removed module paths are not aliases. Update module augmentations and tooling
+  references along with source imports. HTTP API runtime identities and its
+  reserved streaming failure event use `http-api` too.
+- Schema check IDs in persisted representations changed with the check names;
+  type-only brands do not survive representation serialization. Reapply nominal
+  brands after rebuilding, and migrate stored check IDs where applicable.
+- Workflow execution IDs now hash length-prefixed tags/idempotency keys. Existing
+  persisted runs and deferred tokens need an explicit compatibility decision;
+  unchanged business idempotency strings do not imply unchanged execution IDs.
+- Hash values can change. Do not treat Effect hash output as a stable persisted
+  identifier or wire format.
+
+## Verification scope
+
+The documentation test checks core Effect import entrypoints and named exports
+in every TypeScript/TSX fence across skills, patterns, and guidance. It also
+compiles each explicitly marked, independent example with strict TypeScript
+options against the installed stable release. Illustrative fragments may rely
+on surrounding declarations or intentionally show unsupported code; they are
+not all standalone programs.
+
+Release-note completeness is checked against every package changelog at the
+target tag. Source-diff and removed-export scans complement the semantic audits.
+The detector tests retain bidirectional pattern inventory and README catalog
+coverage. Companion-package examples are source-reviewed rather than tested
+against live providers, databases, or OS transports.
+
+Final integration verification on 2026-10-02:
+
+- `bun run check` — passed formatting, lint, and project typechecking.
+- `bun run test` — **912 tests passed across 53 test files**.
+- Documentation compilation — **90 marked examples and 1,096 core Effect import
+  declarations** checked against installed `effect@4.0.0`.
+- `git diff --check` — passed.
+- Release-note comparison — all **93 section bodies across 31 packages** match
+  the exact tag, after trailing-whitespace normalization.
+- Live-content scans — no removed `effect/unstable/*` or `effect/httpapi` paths,
+  rc.116 baseline declarations, or renamed Schema check calls remain. Historical
+  audits and verbatim upstream changelogs retain their original references.

package/guidance/effect-first-development.md

@@ -2,9 +2,9 @@
 
 This document defines the working model behind Effect-first code using the Effect v4 ecosystem.
 
-Bundled baseline: **Effect 4.0.0-rc.116**. Check the consuming project's installed
+Bundled baseline: **Effect 4.0.0 (stable)**. Check the consuming project's installed
 version and inspect the matching upstream release tag before using newer APIs.
-The release changelog and migration audit are in `docs/effect-4.0.0-rc.116.md`.
+The release changelog and migration audit are in `docs/effect-4.0.0.md`.
 Source paths below are relative to the Effect source reference; locate symbols
 by name rather than relying on line numbers or a particular tool name.
 
@@ -141,12 +141,13 @@ export const decodeCreateTaskInput =
     - `import * as Eq from "effect/Equal"`
     - `import * as Bool from "effect/Boolean"`
 - Reserve root imports from `"effect"` for core combinators/types such as `Effect`, `Match`, `pipe`, and `flow`.
-- Keep unstable imports deliberate and local.
+- Import area modules from `effect/<area>` (for example `effect/http-api` and `effect/ai`). Keep APIs marked `@stability unstable` deliberate and local; they may break in minor releases. Use the same release version for `effect` and all directly used `@effect/*` packages.
 
 ### EF-5: Effect modules over native collection helpers
 
 - Use `Arr`, `R`, `Str`, `Eq`, `HashMap`, `HashSet`, `MutableHashMap`, `MutableHashSet`.
 - Sort with `Arr.sort(values, order)` and explicit `effect/Order` values (`Order.String`, `Order.Number`, `Order.mapInput`, etc.), never native array `.sort()`.
+- Partition/separate tuples put successes or predicate-passing values first: `[successes, failures]` / `[passes, fails]`. This applies to Array, Chunk, Effect, Record, Option's `partitionMap`, and Stream partitioning; do not assume a failures-first tuple.
 - Avoid domain usage of native `Object`, `Map`, `Set`, `Date`, and direct native string helpers.
 - Do not use imperative `for` / `for...of` loops in domain code. Use `Arr.map`, `Arr.filter`, `Arr.filterMap`, or `Arr.reduce` for pure transformations. For effectful iteration, use `Effect.forEach` (which also supports concurrency).
 - When behavior is unchanged, prefer the tersest helper form: direct helper refs over trivial wrapper lambdas, `flow(...)` over passthrough `pipe(...)` callbacks, and shared thunk helpers when already in scope.
@@ -561,7 +562,7 @@ const withConnection = <A, E, R>(
 - Keep retry policy close to the failing effect.
 - Retry only proven-idempotent operations at the narrowest boundary that can classify the failure.
 - Let exhausted failures remain visible unless the boundary has a truthful fallback.
-- Reference: `retry` in `packages/effect/src/Effect.ts` and the Schedule cookbook.
+- Reference: `retry` in `packages/effect/src/Effect.ts` and `ai-docs/src/06_schedule/10_schedules.ts` at the installed release tag.
 
 Example:
 
@@ -772,11 +773,12 @@ export class VersionSyncOptions extends Schema.Class<VersionSyncOptions>(
 
 - If a guard validates domain strings/paths/tags, define a branded schema and use `Schema.is(...)`.
 - If a domain constraint is named, reused, matched on, or structurally validated, model it as a schema first rather than a forest of ad-hoc predicate helpers.
-- Prefer built-in schema constructors/checks such as `Schema.NonEmptyString`, `Schema.NonEmptyArray`, `Schema.TupleWithRest`, `Schema.Union`, `Schema.isPattern`, and `Schema.isIncludes` before `Schema.makeFilter`.
+- Prefer built-in schema constructors/checks such as `Schema.NonEmptyString`, `Schema.NonEmptyArray`, `Schema.TupleWithRest`, `Schema.Union`, `Schema.isPattern`, and `Schema.isIncluding` before `Schema.makeFilter`.
 - Keep guard intent and reusable check intent in schema annotations and check metadata.
 - For internal literal domains, use `Schema.is(Schema.Literal(...))` for type guards, `Match` for exhaustive matching, and `Schema.Literal(...).annotate({...})` for annotated schema values.
 - Prefer named intermediate schemas; export and document them when reusable or when they materially clarify the module's domain model, otherwise keep them module-local.
 - Propagate branded schema types through the persistence layer (e.g., ORM column types: `text().$type<AccessToken>()`) to enforce compile-time safety across the entire stack and prevent parameter-swapping bugs.
+- `Schema.brand` is type-only and takes one concrete identifier; apply it repeatedly to compose brands. Put runtime invariants in checks. Brand identifiers are not stored in AST annotations or preserved by `SchemaRepresentation`; reapply brands after reconstruction when the TypeScript type is needed.
 
 Example:
 
@@ -790,7 +792,7 @@ import * as Str from 'effect/String';
 type TopicKind = 'plain' | 'scoped';
 
 const ContainsScopeSeparator = Schema.String.check(
-	Schema.isIncludes(':', {
+	Schema.isIncluding(':', {
 		identifier: 'ContainsScopeSeparatorCheck',
 		title: 'Contains Scope Separator',
 		description: 'A string that contains `:`.',

package/guidance/progressive-disclosure-guidance.md

@@ -1,9 +1,17 @@
 # Agent Rules
 
-The bundled guidance targets **Effect 4.0.0-rc.116**. Read the consuming project's
-version before applying an API: stable v3, older prereleases, and unreleased main
-can have different contracts. Keep directly used Effect-family packages on
-compatible release versions.
+The bundled guidance targets **Effect 4.0.0 (stable)**. Read the consuming project's
+version before applying an API: v3, v4 prereleases, and unreleased main can have
+different contracts. Use the same version of `effect` and every directly used
+`@effect/*` package; Effect packages are versioned and released together.
+
+Import area modules from `effect/<area>`: for example `effect/http`,
+`effect/http-api`, `effect/rpc`, `effect/ai`, and `effect/process`. Import
+`Arbitrary` from `effect/Arbitrary`, and binary-text codecs from
+`effect/encoding/{Base64,Base64Url,Hex,EncodingError}`. Check source stability
+annotations: `@stability unstable` APIs can break in minor releases even though
+their import paths have no `unstable` segment. APIs without that annotation
+follow semver. TypeScript 5.9 or newer is required.
 
 Before planning or writing Effect code, load the skills relevant to the APIs involved.
 For other tasks, load a skill only when its guidance is needed to answer or complete the task.
@@ -11,8 +19,8 @@ For other tasks, load a skill only when its guidance is needed to answer or comp
 When skills leave any ambiguity, or when you encounter unfamiliar APIs during implementation, read the OpenCode `effect` reference at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`. Treat this reference as the source of truth over `node_modules`, stale external docs, or memory.
 
 Check the reference revision too. For this baseline, inspect the
-`effect@4.0.0-rc.116` tag (for example with `git show
-effect@4.0.0-rc.116:packages/effect/src/Schema.ts`) when main has moved ahead.
+`effect@4.0.0` tag (for example with `git show
+effect@4.0.0:packages/effect/src/Schema.ts`) when main has moved ahead.
 Source symbols and signatures at that tag take precedence over stale prose or
 line-number links. Public exports marked `@internal` in source are not application APIs.
 
@@ -30,7 +38,7 @@ line-number links. Public exports marked `@internal` in source are not applicati
 - `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/packages/effect/MCP.md` — MCP server resources, prompts, tools, and transports.
 - `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/packages/effect/OPTIC.md` — `Optic` guide for lenses, prisms, optionals, traversals, and schema isos.
 - `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/packages/vitest/README.md` — `@effect/vitest` testing guide.
-- `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/cookbooks/schedule.md` — Schedule cookbook; read before designing retries, repeats, polling, backoff, jitter, timeouts, or recurrence limits.
+- `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/ai-docs/src/06_schedule/10_schedules.ts` — runnable Schedule guide at the stable tag; read alongside `Schedule.ts` before designing retries, repeats, polling, backoff, jitter, timeouts, or recurrence limits. The stable tag has no `cookbooks/schedule.md`.
 
 Do not use migration notes, Effect-repo contributor patterns, or in-repo specs as general application guidance. Read those only when the task is explicitly about migrating old Effect code or contributing to the Effect repository itself.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "opencode-effect-enforcer",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "OpenCode V2 plugin for Effect v4 skills, guidance, and pattern enforcement",
   "keywords": [
     "opencode",
@@ -46,7 +46,7 @@
     "@ast-grep/napi": "^0.42.3",
     "@opencode/plugin": "2.0.8",
     "diff": "^9.0.0",
-    "effect": "4.0.0-rc.116",
+    "effect": "4.0.0",
     "picomatch": "^4.0.3",
     "yaml": "^2.8.1"
   },

package/patterns/avoid-any.md

@@ -30,8 +30,8 @@ generics   :: ∀ a. Constraint a ⇒ a → F a
 bad  :: Unknown → T
 bad x = x `as` T                    -- trust me bro
 
-good :: Unknown → Either ParseError T
-good x = Schema.decode schemaT x    -- prove it
+good :: Unknown → Effect T SchemaError
+good x = Schema.decodeUnknownEffect schemaT x    -- decode and retain the proof
 ```
 
 Using `as any` bypasses type checking entirely. The `as unknown as T` pattern is equivalent—casting through `unknown` still erases type information. Note: `as const` is acceptable—it narrows to literal types without erasing type safety.

package/patterns/avoid-direct-json.md

@@ -30,8 +30,8 @@ encodeJson     :: Schema a → a → String
 bad :: String → IO User
 bad json = JSON.parse json        -- returns Any, throws on invalid
 
-good :: String → Either ParseError User
-good json = Schema.decodeUnknownSync(Schema.fromJsonString(User)) json
+good :: String → Effect User SchemaError
+good json = Schema.decodeUnknownEffect(Schema.fromJsonString(User)) json
 
 unknownJson = Schema.fromJsonString(Schema.Unknown)
 
@@ -41,11 +41,11 @@ data User = Schema.Class "User"
   , name :: Schema.String
   }
 
-decode :: String → Either ParseError User
-decode = Schema.decodeUnknownSync(Schema.fromJsonString(User))
+decode :: String → Effect User SchemaError
+decode = Schema.decodeUnknownEffect(Schema.fromJsonString(User))
 
-encode :: User → String
-encode = Schema.encodeSync(Schema.fromJsonString(User))
+encode :: User → Effect String SchemaError
+encode = Schema.encodeEffect(Schema.fromJsonString(User))
 ```
 
 `JSON.parse` returns `any` and throws on invalid input. `Schema.fromJsonString(...)` provides typed, validated JSON parsing and encoding. Use `Schema.fromJsonString(Schema.Unknown)` when the JSON shape is intentionally unknown; `Schema.UnknownFromJsonString` is internal in current Effect v4. Direct JSON methods remain reasonable at narrow logging/debugging boundaries.

package/patterns/avoid-native-fetch.md

@@ -33,29 +33,31 @@ good url = pipe(
 
 ```haskell
 -- Composable request building
-request :: Effect HttpClientRequest HttpBodyError
+request :: HttpClientRequest
 request = pipe(
-  HttpClientRequest.post("/api/users"),
-  HttpClientRequest.bodyJson({ name: "Alice" })
+  HttpClientRequest.get("https://api.example.com/users"),
+  HttpClientRequest.setHeader("accept", "application/json")
 )
 
 -- With retry, timeout, tracing
 resilient :: Effect Response HttpError (HttpClient | Scope)
 resilient = pipe(
-  request,
-  Effect.flatMap(HttpClient.execute),
+  HttpClient.execute(request),
   Effect.retry(Schedule.recurs(3)),
   Effect.timeout(Duration.seconds(10))
 )
 
 -- Platform layer at entry point
 main = program.pipe(
-  Effect.provide(BunHttpClient.layer)    -- or NodeHttpClient.layer
+  Effect.provide(BunHttpClient.layer)    -- or NodeHttpClient.layerUndici
 )
 ```
 
 Native `fetch` produces untyped Promise rejections. Use `HttpClientRequest`, `HttpClientResponse`, and `HttpClient` from Effect for typed errors, composable request building, and testability via layer substitution.
 
+Import the HTTP modules from `effect/http`. Retry only proven-idempotent requests;
+do not copy a retry policy onto ordinary non-idempotent POST/PATCH operations.
+
 Exception: an explicit low-level platform implementation that cannot use Effect HTTP. Keep it isolated, lift it with `Effect.tryPromise`, propagate the supplied `AbortSignal`, classify status before decoding, and decode unknown bodies with `Schema`.
 
 References: EF-9b, Checklist #42 in effect-first-development.md

package/patterns/avoid-node-imports.md

@@ -73,12 +73,12 @@ good = do
 | `node:fs/promises`   | `FileSystem.FileSystem`                                               |
 | `node:path`          | `Path.Path`                                                           |
 | `node:os`            | `FileSystem.makeTempFileScoped` / `Path.Path` / platform layer        |
-| `node:child_process` | `ChildProcessSpawner` + `ChildProcess` from `effect/unstable/process` |
+| `node:child_process` | `ChildProcessSpawner` + `ChildProcess` from `effect/process` |
 | `node:http`          | `HttpClient.HttpClient`                                               |
 | `node:https`         | `HttpClient.HttpClient`                                               |
 | `node:stream`        | `Stream` from effect                                                  |
 | `node:readline`      | `Terminal.Terminal`                                                   |
-| `node:crypto`        | `Crypto` from `effect/unstable/crypto` or a wrapped Effect service    |
+| `node:crypto`        | `Crypto.Crypto` from `effect/Crypto` or a wrapped Effect service |
 
 **Exceptions:**
 

package/patterns/avoid-non-null-assertion.md

@@ -37,8 +37,8 @@ safe :: User → Maybe Email
 safe user = user?.contact?.email ?? Nothing
 
 -- With Schema for external data
-validated :: Unknown → Either ParseError User
-validated = Schema.decode userSchema
+validated :: Unknown → Effect User SchemaError
+validated = Schema.decodeUnknownEffect User
 ```
 
 The `!` operator is "trust me, this isn't null"—if wrong, runtime crash. Use `?.`, `??`, `Option`, or type guards for safe null handling.

package/patterns/avoid-object-type.md

@@ -39,8 +39,8 @@ good :: User → Effect ()
 good user = doSomething user      -- clear structure, IDE support
 
 -- For unknown shapes
-decode :: Unknown → Either ParseError User
-decode = Schema.decode userSchema
+decode :: Unknown → Effect User SchemaError
+decode = Schema.decodeUnknownEffect User
 ```
 
 `Object` and `{}` provide no type safety—they accept any non-null value. Use explicit types, `Record<K,V>`, `unknown`, or Schema for validation.

package/patterns/avoid-platform-coupling.md

@@ -38,6 +38,6 @@ good = Layer.provide(platformLayer)          -- no platform coupling
 good = -- runtime provides ChildProcessSpawner, FileSystem, etc.
 ```
 
-Binding packages wrap external systems (CLIs, APIs, databases) and must be platform-agnostic. They should depend on abstract services from `effect` and its unstable namespaces, such as `FileSystem`, `Path`, `HttpClient`, and `ChildProcessSpawner`, but never on `@effect/platform-bun` or `@effect/platform-node` concrete implementations.
+Binding packages wrap external systems (CLIs, APIs, databases) and must be platform-agnostic. They should depend on abstract services from `effect` and its area entrypoints, such as `FileSystem`, `Path`, `HttpClient` from `effect/http`, and `ChildProcessSpawner` from `effect/process`, rather than hardwiring `@effect/platform-bun` or `@effect/platform-node` concrete implementations.
 
 Platform-specific layers (`BunServices.layer`, `NodeServices.layer`) belong in the runtime or CLI entry point, not in bindings. The runtime provides concrete implementations of abstract Effect services there.

package/patterns/avoid-process-env.md

@@ -29,13 +29,12 @@ Config.Redacted :: String -> Config Redacted -- for sensitive values
 bad :: Effect String
 bad = Effect.sync \_ -> process.env.API_KEY    -- raw side effect
 
-good :: Effect String ConfigError
+good :: Effect (Redacted String) ConfigError
 good = Config.Redacted "API_KEY"               -- typed, redacted
 
-better :: Effect String ConfigError
+better :: Effect Int ConfigError
 better = Config.Int("PORT")
-  & Config.withDefault "3000"
-  & Config.map Number.parse                    -- with transformation
+  & Config.withDefault 3000                    -- defaults use the decoded type
 ```
 
 `process.env` is a raw side effect with no type safety. Use `Config.*` for validated, composable, testable configuration.

package/patterns/avoid-ts-ignore.md

@@ -32,7 +32,7 @@ bad = do
 
 good :: Effect a
 good = do
-  x ← Schema.decode schema raw   -- prove correctness
+  x ← Schema.decodeUnknownEffect schema raw   -- prove correctness
 ```
 
 Suppressing errors masks bugs that surface at runtime. Fix the underlying type issue instead.

package/patterns/context-tag-extends.md

@@ -31,7 +31,7 @@ Use `Context.Service` for service definitions. Replace these legacy spellings:
 | Legacy API                  | Era       | Replacement                |
 | --------------------------- | --------- | -------------------------- |
 | `Context.Tag` / `GenericTag` | pre-v4    | `Context.Service`          |
-| `Effect.Service`            | early v4  | `Context.Service`          |
+| `Effect.Service`            | v3        | `Context.Service`          |
 | `ServiceMap.Service` / `.*` | prerelease | `Context.Service` / `Context.*` |
 
 ```haskell
@@ -47,21 +47,24 @@ class ParallelClient extends Effect.Service<ParallelClient>()(...)
 class MyService extends ServiceMap.Service<MyService>()("@app/MyService", { ... })
 
 -- Fix: Context.Service
-class ParallelClient extends Context.Service<ParallelClient>()(
+class ParallelClient extends Context.Service<ParallelClient, Interface>()(
   "@parallel/ParallelClient"
 )
 ```
 
+<!-- typecheck -->
 ```typescript
-// Concrete service (single implementation)
-export class ParallelClient extends Context.Service<ParallelClient>()(
+import { Context, Effect, Layer } from 'effect';
+
+class ParallelClient extends Context.Service<ParallelClient, {
+	readonly ping: Effect.Effect<string>;
+}>()(
 	'@parallel/ParallelClient'
 ) {}
 
-// Interface-style service (multiple implementations, config, infrastructure)
-export class Clipboard extends Context.Service<Clipboard>()(
-	'@Clipboard/Clipboard'
-) {}
+const layer = Layer.succeed(ParallelClient, {
+	ping: Effect.succeed('pong')
+});
 ```
 
 When migrating from `ServiceMap`, also update the corresponding module accessors:

package/patterns/effect-promise-vs-trypromise.md

@@ -16,7 +16,7 @@ suggestSkills:
 
 ```haskell
 -- Transformation
-promise    :: IO (Promise a) → Effect a ∅        -- rejection = defect (uncatchable)
+promise    :: IO (Promise a) → Effect a ∅        -- rejection = defect, outside typed E
 tryPromise :: IO (Promise a) → Effect a E        -- rejection = typed error (catchable)
 ```
 
@@ -24,7 +24,7 @@ tryPromise :: IO (Promise a) → Effect a E        -- rejection = typed error (c
 -- Pattern
 bad :: Effect User ∅
 bad = Effect.promise \_ → fetchUser id
-  -- rejection becomes Defect: can't catch, crashes fiber
+  -- rejection becomes a defect: catchTag does not handle it
 
 good :: Effect User FetchError
 good = Effect.tryPromise
@@ -37,11 +37,10 @@ good = Effect.tryPromise
 handle :: Effect User FetchError → Effect User ∅
 handle = catchTag "FetchError" \e → defaultUser
 
--- Defects bypass all handlers
-defect :: Effect a ∅ → Effect a E
-defect = id    -- can't recover from defects
+-- Defects require explicit cause/defect handling, not ordinary typed recovery
+inspectDefect = Effect.catchDefect
 ```
 
-`Effect.promise` converts rejections to uncatchable defects. Use `Effect.tryPromise` for typed, recoverable errors in the E channel.
+`Effect.promise` converts rejections to defects outside the typed error channel. `Effect.catchDefect` and cause-level handlers can observe them, but expected rejection belongs in `Effect.tryPromise` with a typed error.
 
-Any reference to `Effect.promise` is flagged — not just `yield* Effect.promise(...)`. Piping, passing, or returning `Effect.promise` propagates the same defect-conversion problem to the consumer and is equally wrong.
+Any reference to `Effect.promise` is flagged — not just `yield* Effect.promise(...)`. Review callbacks, returned helpers, and direct calls alike. An explicit boundary whose rejection genuinely represents a defect may intentionally use `Effect.promise`; explain that contract rather than relabeling expected failures as defects.

package/patterns/prefer-arr-sort.md

@@ -44,7 +44,7 @@ sorted = Arr.sort byNameThenAge
 
 -- Reverse
 descending :: [User] -> [User]
-descending = Arr.sort (Order.reverse byName)
+descending = Arr.sort (Order.flip byName)
 ```
 
 Native `.sort()` mutates the array in place and uses an untyped comparator. `Arr.sort` from `effect/Array` returns a new sorted array using a composable, typed `Order`.

package/patterns/prefer-effect-fn.md

@@ -84,74 +84,30 @@ Key details:
 
 ## Complete Before/After
 
+<!-- typecheck -->
 ```typescript
-// BEFORE — plain arrow functions, no tracing
-export class UserRepository extends Context.Service<UserRepository>()(
-	'@services/UserRepository',
-	{
-		make: Effect.gen(function* () {
-			const db = yield* DatabaseClient;
+import { Context, Effect, Layer } from 'effect';
+import * as Schema from 'effect/Schema';
 
-			return {
-				findById: (id: string): Effect.Effect<User, UserNotFound> =>
-					Effect.gen(function* () {
-						const row = yield* db.query(
-							'SELECT * FROM users WHERE id = ?',
-							id
-						);
-						if (!row)
-							return yield* new UserNotFound({
-								id,
-								message: `Not found: ${id}`
-							});
-						return row as User;
-					}),
-
-				create: (
-					data: CreateUserData
-				): Effect.Effect<User, DuplicateUser> =>
-					Effect.gen(function* () {
-						return yield* db.insert('users', data);
-					})
-			};
-		})
-	}
-) {}
-
-// AFTER — Effect.fn, every method gets a traced span
-export class UserRepository extends Context.Service<UserRepository>()(
-	'@services/UserRepository',
-	{
-		make: Effect.gen(function* () {
-			const db = yield* DatabaseClient;
-
-			const findById = Effect.fn('UserRepository.findById')(
-				(id: string): Effect.Effect<User, UserNotFound> =>
-					Effect.gen(function* () {
-						const row = yield* db.query(
-							'SELECT * FROM users WHERE id = ?',
-							id
-						);
-						if (!row)
-							return yield* new UserNotFound({
-								id,
-								message: `Not found: ${id}`
-							});
-						return row as User;
-					})
-			);
-
-			const create = Effect.fn('UserRepository.create')(
-				(data: CreateUserData): Effect.Effect<User, DuplicateUser> =>
-					Effect.gen(function* () {
-						return yield* db.insert('users', data);
-					})
-			);
-
-			return { findById, create };
-		})
-	}
+class User extends Schema.Class<User>('User')({ id: Schema.String }) {}
+class UserNotFound extends Schema.TaggedError<UserNotFound>()(
+	'UserNotFound', { id: Schema.String }
 ) {}
+class Database extends Context.Service<Database, {
+	readonly findUser: (id: string) => Effect.Effect<User, UserNotFound>;
+}>()('app/Database') {}
+class UserRepository extends Context.Service<UserRepository, {
+	readonly findById: (id: string) => Effect.Effect<User, UserNotFound>;
+}>()('app/UserRepository') {}
+
+const layer = Layer.effect(UserRepository, Effect.gen(function* () {
+	const db = yield* Database;
+	// Before: (id: string) => Effect.gen(function* () { ... })
+	const findById = Effect.fn('UserRepository.findById')(function* (id: string) {
+		return yield* db.findUser(id);
+	});
+	return UserRepository.of({ findById });
+}));
 ```
 
 ## When NOT to use Effect.fn

package/patterns/prefer-schema-class.md

@@ -16,7 +16,7 @@ suggestSkills:
 
 ```haskell
 -- Transformation
-Schema.Struct :: { fields } -> Schema { fields }     -- anonymous, no constructor
+Schema.Struct :: { fields } -> Schema { fields }     -- structural value with make helpers
 Schema.Class  :: String -> { fields } -> Class        -- named, constructable, extensible
 
 -- Pattern
@@ -25,7 +25,7 @@ bad = Schema.Struct({
   id: Schema.String,
   name: Schema.String
 })
--- anonymous type, no constructor, no instanceof
+-- structural type, make helpers, no class identity / instanceof
 
 good :: Schema
 good = class User extends Schema.Class<User>("User")({
@@ -49,6 +49,6 @@ extend = class Admin extends User.extend<Admin>("Admin")({
 }) {}
 ```
 
-`Schema.Struct` produces an anonymous schema without a constructor or `instanceof` support. `Schema.Class` provides a named type, constructor, extensibility, and optional annotation support when docs or introspection benefit from it. Prefer `Schema.Class` for decoded domain/API shapes, union members, and values that need identity. `Schema.Struct` remains appropriate for local structural composition, configuration internals, and schemas where class identity adds no value, so review this informational finding in context.
+Every schema, including `Schema.Struct`, has `make`, `makeOption`, and `makeEffect` construction helpers. `Schema.Class` additionally provides a named class, `new` / `instanceof` identity, and class extension. Prefer it for decoded domain/API shapes, union members, and values that need identity. `Schema.Struct` remains appropriate for local structural composition, configuration internals, and schemas where class identity adds no value, so review this informational finding in context.
 
 References: EF-3 in effect-first-development.md

package/patterns/throw-in-effect-gen.md

@@ -30,7 +30,7 @@ suggestSkills:
 
 ```haskell
 -- Transformation
-throw :: Error -> ⊥                        -- untyped, uncatchable by Effect
+throw :: Error -> ⊥                        -- defect, outside the typed error channel
 yield* Effect.fail :: TaggedError -> E ⊥ E  -- typed, catchable via catchTag
 ```
 

package/patterns/use-clock-service.md

@@ -43,3 +43,7 @@ test = do
 ```
 
 Direct `Date` usage is non-deterministic. Use `DateTime.now` or `Clock.currentTimeMillis` for testable time operations via `TestClock`.
+
+Use wall-clock time for timestamps and `Clock.monotonicTimeNanos` for elapsed
+durations; wall-clock adjustments must not
+change a measured interval.