opencode-effect-enforcer 0.2.6 → 0.3.0

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,9 +44,9 @@ 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`.
 
-References: EF-38 in effect-first-development.md
+References: EF-5 in effect-first-development.md

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, EF-33 in effect-first-development.md
+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.

package/patterns/use-command-executor-service.md

@@ -35,7 +35,7 @@ ChildProcessSpawner :: Effect a ChildProcessSpawner  -- typed I/O, scoped lifeti
 ```
 
 ```haskell
--- Pattern (Effect v4 — effect/unstable/process)
+-- Pattern (Effect v4 — effect/process)
 bad :: () → IO String
 bad = exec "git" ["status"] (cb)              -- callback, untyped, no cancellation
 
@@ -46,7 +46,7 @@ good = do
   -- typed output, error channel, scoped lifetime
 ```
 
-Direct `child_process` imports give you callback APIs, manual lifecycle, and no error channel. Use `ChildProcessSpawner` and `ChildProcess` from `effect/unstable/process` for typed errors, scoped resource lifetime, and platform-agnostic process spawning.
+Direct `child_process` imports give you callback APIs, manual lifecycle, and no error channel. Use `ChildProcessSpawner` and `ChildProcess` from `effect/process` for typed errors, scoped resource lifetime, and platform-agnostic process spawning.
 
 **Exceptions:**
 

package/patterns/use-http-client-service.md

@@ -49,26 +49,28 @@ 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 (HttpClient | HttpBodyError)
 resilient = pipe
-  request
-  (Effect.flatMap HttpClient.execute)
+  (HttpClient.execute request)
   (Effect.retry (Schedule.recurs 3))
   (Effect.timeout (Duration.seconds 10))
 
 -- Provide platform layer at entry point
 main = program
-  & provide BunHttpClient.layer    -- or NodeHttpClient.layer
+  & provide BunHttpClient.layer    -- or NodeHttpClient.layerUndici
 ```
 
 Direct `http` / `https` imports give you callback APIs, manual TLS plumbing, and no error channel. Use Effect's `HttpClient`, `HttpClientRequest`, and `HttpClientResponse` for typed errors, composable request building, declarative retry/timeout, and testability via layer substitution.
 
+Import these modules from `effect/http`. The retry example assumes an idempotent
+GET; only retry mutations when their idempotency is established by the contract.
+
 **Exceptions:**
 
 - Platform-specific layers that implement `HttpClient.HttpClient`

package/patterns/use-random-service.md

@@ -34,12 +34,11 @@ bad = floor (Math.random * 100)     -- R = ∅, untestable
 good :: Effect Int Random
 good = Random.nextIntBetween 0 100  -- R ⊃ Random, deterministic in tests
 
--- In tests
-test :: Effect () TestRandom
-test = do
-  TestRandom.feedInts [42, 7, 13]   -- deterministic sequence
-  result ← good
-  assert (result == 42)
+-- Repeatable sequence in tests
+seeded = good & Random.withSeed "example-seed"
 ```
 
-`Math.random()` is non-deterministic. Use `Random` service for reproducible randomness via `TestRandom.feed*` in tests.
+`Math.random()` bypasses Effect's random service. Use `Random.withSeed` for
+repeatable sequences in tests, or provide a controlled `Random.Random` service
+when the exact generated values matter. `Random.nextIntBetween(min, max)` includes
+both endpoints by default; pass `{ halfOpen: true }` to exclude the upper bound.

package/skills/effect-ai-chat/SKILL.md

@@ -8,14 +8,17 @@ You are an Effect TypeScript expert specializing in the `Chat` module for statef
 ## Effect Source Reference
 
 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.
+Use `git show effect@4.0.0:<path>` in that checkout for this skill's baseline;
+main may be ahead. Keep `effect` and `@effect/*` packages on the same version.
+The `effect/ai` APIs are tagged `@stability unstable`: minor releases may break
+them even though the import path no longer contains `unstable`.
 
 Reference this for:
 
-- Chat module source: `packages/effect/src/unstable/ai/Chat.ts`
+- Chat module source: `packages/effect/src/ai/Chat.ts`
 - Chat usage examples: `ai-docs/src/71_ai/30_chat.ts`
 - Tool integration examples: `ai-docs/src/71_ai/20_tools.ts`
-- Prompt construction: `packages/effect/src/unstable/ai/Prompt.ts`
+- Prompt construction: `packages/effect/src/ai/Prompt.ts`
 
 ## Core Imports
 
@@ -28,7 +31,7 @@ import {
 	Tool,
 	Toolkit,
 	AiError
-} from 'effect/unstable/ai';
+} from 'effect/ai';
 ```
 
 ## What Chat Provides
@@ -122,7 +125,10 @@ yield* session.generateText({ prompt: [] });
 
 ## Streaming Text
 
-`streamText` returns a `Stream` of `Response.StreamPart` values. History is updated when the stream finalizes. Consume the stream to completion if the full assistant response should become history; if the stream is interrupted early, only the parts emitted before finalization are recorded.
+`streamText` returns a `Stream` of `Response.StreamPart` values. History is updated
+when the stream finalizes by folding the parts received so far. Consume to
+completion to preserve the full response: interrupted text/reasoning sequences
+without an end marker are not folded into history.
 
 ```ts
 yield*
@@ -215,7 +221,7 @@ const restored = yield* Chat.fromExport(data);
 For automatic persistence (save after every generation), use `Chat.Persistence`:
 
 ```ts
-import { Persistence } from 'effect/unstable/persistence';
+import { Persistence } from 'effect/persistence';
 
 // Create a persistence layer and provide a BackingPersistence implementation
 const PersistenceLayer = Chat.layerPersisted({ storeId: 'my-chats' }).pipe(
@@ -459,7 +465,7 @@ Each `Chat` instance uses an internal semaphore with 1 permit, ensuring that onl
 
 1. **Always provide `LanguageModel.LanguageModel`** — `generateText`, `streamText`, and `generateObject` all require it in context. Provide via `Effect.provide(modelLayer)`.
 2. **Use `prompt: []` in agentic loops** — After the initial prompt, pass an empty prompt to let the model respond based on accumulated history including tool results.
-3. **Import from `effect/unstable/ai`** — Chat, Prompt, Tool, Toolkit, LanguageModel, and AiError all come from this path.
+3. **Import from `effect/ai`** — Chat, Prompt, Tool, Toolkit, LanguageModel, and AiError all come from this path.
 4. **One session = one conversation** — Create separate `Chat` instances for independent conversations. Don't share a session across unrelated threads.
 5. **Export before shutdown** — Use `exportJson` to persist state. Restore with `Chat.fromJson`.
 6. **Provide toolkit handlers** — When using tools, the toolkit's handler layer must be provided (e.g., `Layer.provide(ToolsLayer)`).