opencode-effect-enforcer 0.2.6 → 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.
 
@@ -46,6 +46,8 @@ At boundaries:
 
 ## Laws and Conventions
 
+Keep types sound: no `any`, type assertions, `@ts-ignore`, or non-null assertions.
+
 ### EF-1: Errors are data, not side effects
 
 - If logic can fail, return `Effect.Effect<A, E, R>` with a typed error `E`.
@@ -103,8 +105,9 @@ const toDisplayName = (rawName: string | null | undefined) =>
 
 - Unknown or external data must be decoded at the boundary.
 - Prefer `Schema.decodeUnknownEffect` for effectful paths and `Schema.decodeUnknownSync` only where sync failure handling is explicit.
-- Never use `JSON.parse` / `JSON.stringify`; use schema JSON codecs (`Schema.fromJsonString`, `Schema.decodeUnknown*`, `Schema.encode*`). For unknown JSON, use `Schema.fromJsonString(Schema.Unknown)`.
 - Prefer `Schema.Class` over `Schema.Struct` for all decoded shapes — including HTTP response bodies, API payloads, and ephemeral wire formats, not just domain models. Named `Schema.Class` types enable `instanceof` discrimination (e.g., `Schema.Union([SuccessResponse, ErrorResponse])` then `if (parsed instanceof ErrorResponse)`), which is compile-time safe.
+- Use `Schema.Class` for shapes discriminated via `instanceof` or participating in a `Schema.Union`.
+- Prefer schema constructors over plain `type` / `interface` for property-based domain shapes; derive types from schemas rather than maintaining parallel models. Keep plain types for shapes schema cannot represent cleanly, such as complex type-level transforms, utility types, and overload-only surfaces.
 - Do not name schemas with a `Schema` suffix; schema constants should be named after the domain type.
 - For non-class schemas, export type aliases with the same identifier name as the schema value.
 
@@ -138,11 +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.
@@ -206,7 +211,6 @@ const summarizeAttempts = (attempts: ReadonlyArray<number>) =>
 
 ### EF-8: Services use explicit tags + `Layer`
 
-- Service identity comes from a unique string key.
 - Honor a current Effect service-tag style already standardized by the project; otherwise default to `Context.Service`.
 - Service constructors are explicit and layered.
 - Dependency wiring happens in Layer composition, not hidden global state.
@@ -276,14 +280,6 @@ export const TenantHeader = Tenant.annotate({
 export type Tenant = typeof Tenant.Type;
 ```
 
-### EF-12b: Schema-first internal domain building blocks
-
-- If an intermediate domain concept is named, reused, matched on, or structurally validated, model it as a schema first instead of an ad-hoc boolean helper.
-- Prefer built-in schema constructors/checks such as `Schema.NonEmptyString`, `Schema.NonEmptyArray`, `Schema.TupleWithRest`, `Schema.Union`, `Schema.isPattern`, and `Schema.isIncludes` before reaching for `Schema.makeFilter`.
-- Derive domain guards with `Schema.is(SomeSchema)`.
-- If an internal literal domain needs type guards, use `Schema.is(Schema.Literal(...))`. For exhaustive matching over literals, use `Match`. For annotation-bearing schema values, use `Schema.Literal(...).annotate({...})`.
-- 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.
-
 ### EF-12c: Reusable schema checks carry metadata
 
 - Reusable `Schema.makeFilter`, `Schema.makeFilterGroup`, and reusable built-in check blocks must include `identifier`, `title`, and `description`.
@@ -504,6 +500,7 @@ You are not done if these fail:
 
 ### EF-21: Runtime execution stays at the boundary
 
+- Runtime source uses Effect `FileSystem`, `Path`, and process services instead of `node:fs`, `node:path`, or `node:child_process`.
 - Application entrypoints and tests may execute effects with `Effect.run*`.
 - Library and domain exports should return `Effect` values.
 - Keep runtime execution in one place so wiring, logging, and lifecycle behavior stay auditable.
@@ -565,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:
 
@@ -739,30 +736,6 @@ const runIsolated = program.pipe(
 );
 ```
 
-### EF-33: Schema-first development for domain models
-
-- If a data shape is decoded from external input, will be discriminated via `instanceof`, or participates in a `Schema.Union`, define it as `Schema.Class` first — regardless of whether it is a "domain model" or an ephemeral HTTP response shape.
-- Prefer `Schema.Class` (or another schema constructor) over plain `type` / `interface` for property-based domain shapes.
-- Derive runtime types from schema definitions instead of duplicating parallel `type` / `interface` models.
-- Keep plain `type` / `interface` for cases schema cannot represent cleanly (complex type-level transforms, utility types, overload-only surfaces).
-
-Example:
-
-```ts
-import * as Schema from 'effect/Schema';
-
-// Prefer schema-first over plain interfaces for domain payloads.
-export class CreateOrderInput extends Schema.Class<CreateOrderInput>(
-	'CreateOrderInput'
-)(
-	{
-		orderId: Schema.String,
-		customerId: Schema.String
-	},
-	{ description: 'Input payload for creating an order.' }
-) {}
-```
-
 ### EF-34: Schema defaults over fallback object logic
 
 - Put defaults in schema definitions, not in handler/service fallback object literals.
@@ -800,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 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 them only when reusable or when they materially clarify the module's domain model.
+- 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:
 
@@ -818,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 `:`.',
@@ -955,25 +929,6 @@ const NativePathToPosixPath = Schema.String.pipe(
 );
 ```
 
-### EF-38: Never use native array sort in Effect-first code
-
-- Use `Arr.sort(values, order)` from `effect/Array`.
-- Define ordering with `effect/Order` (`Order.String`, `Order.Number`, `Order.mapInput`, etc.).
-- Do not call native `.sort()` directly on arrays.
-
-Example:
-
-```ts
-import { Order } from 'effect';
-import * as Arr from 'effect/Array';
-
-const byName = Order.mapInput(
-	Order.String,
-	(item: { readonly name: string }) => item.name
-);
-const sorted = Arr.sort(items, byName);
-```
-
 ### EF-39: Avoid ad-hoc `String(...)` coercion for domain comparisons
 
 - When unknown/scalar data must normalize to domain strings, model the conversion with schema transformations.
@@ -1022,248 +977,3 @@ const [cachedConfig, invalidate] =
 	);
 // Later: yield* invalidate to force reload on next access
 ```
-
-## Copy-Paste Templates
-
-### Template: Tagged error
-
-```ts
-import * as Schema from 'effect/Schema';
-
-class DomainError extends Schema.TaggedError<DomainError>()(
-	'DomainError',
-	{
-		message: Schema.String
-	},
-	{ description: 'Domain failure' }
-) {}
-```
-
-### Template: Safe nullable boundary conversion
-
-```ts
-import { pipe } from 'effect';
-import * as Option from 'effect/Option';
-
-const fromNullableName = (name: string | null | undefined) =>
-	pipe(
-		Option.fromNullishOr(name),
-		Option.filter((value) => value.length > 0)
-	);
-```
-
-### Template: Decode unknown at API edge
-
-```ts
-import * as Schema from 'effect/Schema';
-
-export class Payload extends Schema.Class<Payload>('Payload')({
-	query: Schema.String
-}) {}
-
-const decodePayload = Schema.decodeUnknownEffect(Payload);
-```
-
-### Template: Schema naming + type alias (no `Schema` suffix)
-
-```ts
-import * as Schema from 'effect/Schema';
-
-export const OrderId = Schema.String;
-export type OrderId = typeof OrderId.Type;
-```
-
-### Template: Schema-first replacement for interface
-
-```ts
-import * as Schema from 'effect/Schema';
-
-export class UserProfile extends Schema.Class<UserProfile>('UserProfile')(
-	{
-		id: Schema.String,
-		displayName: Schema.String
-	},
-	{ description: 'User profile model used in domain workflows.' }
-) {}
-```
-
-### Template: Match over switch
-
-```ts
-import { Match } from 'effect';
-import * as Arr from 'effect/Array';
-
-type Phase = 'draft' | 'running' | 'done';
-
-const phaseLabel = (phase: Phase) =>
-	Match.value(phase).pipe(
-		Match.when('draft', () => 'draft'),
-		Match.when('running', () => 'running'),
-		Match.when('done', () => 'done'),
-		Match.exhaustive
-	);
-
-const summarize = (items: ReadonlyArray<string>) =>
-	Arr.match(items, {
-		onEmpty: () => 'none',
-		onNonEmpty: (values) => `count:${Arr.length(values)}`
-	});
-```
-
-### Template: Effect-returning function constructor
-
-```ts
-import { Effect } from 'effect';
-
-export const runTask = Effect.fn('Task.run')(function* (taskId: string) {
-	yield* Effect.logInfo('run task', taskId);
-	return taskId;
-});
-```
-
-### Template: Option schema from nullish/optional
-
-```ts
-import * as Schema from 'effect/Schema';
-
-export class Input extends Schema.Class<Input>('Input')({
-	maybeName: Schema.OptionFromNullishOr(Schema.String),
-	maybeEmail: Schema.OptionFromOptionalKey(Schema.String)
-}) {}
-```
-
-### Template: Dual helper (data-first + data-last)
-
-```ts
-import { dual } from 'effect/Function';
-
-export const rename: {
-	(
-		to: string
-	): (self: { readonly name: string }) => { readonly name: string };
-	(self: { readonly name: string }, to: string): { readonly name: string };
-} = dual(2, (self, to) => ({ ...self, name: to }));
-```
-
-### Template: JSON boundary without native JSON APIs
-
-```ts
-import * as Schema from 'effect/Schema';
-
-export class Payload extends Schema.Class<Payload>('Payload')({
-	query: Schema.String
-}) {}
-
-const PayloadJson = Schema.fromJsonString(Payload);
-
-export const decodePayloadJson = Schema.decodeUnknownEffect(PayloadJson);
-export const encodePayloadJson = Schema.encodeUnknownEffect(PayloadJson);
-```
-
-### Template: Runtime boundary execution
-
-```ts
-import { Effect } from 'effect';
-
-export const buildReport = Effect.fn('Report.build')(function* () {
-	return 'ok';
-});
-
-// runtime boundary only
-// Effect.runPromise(buildReport())
-```
-
-### Template: Scoped resource helper
-
-```ts
-import { Effect } from 'effect';
-
-export const withResource = <A, E, R>(
-	use: (resource: Resource) => Effect.Effect<A, E, R>
-) => Effect.acquireUseRelease(acquireResource, use, releaseResource);
-```
-
-### Template: Retry + timeout
-
-```ts
-import { Duration, Effect, Schedule } from 'effect';
-
-export const resilientTask = task.pipe(
-	Effect.retry(Schedule.recurs(3)),
-	Effect.timeoutOption(Duration.seconds(5))
-);
-```
-
-### Template: Config + redacted secret
-
-```ts
-import { Config, Effect } from 'effect';
-
-export const loadConfig = Effect.fn('Config.load')(function* () {
-	const port = yield* Config.Int('PORT');
-	const apiKey = yield* Config.Redacted('API_KEY');
-	return { port, apiKey };
-});
-```
-
-### Template: Isolated layer provide
-
-```ts
-import { Effect, Layer } from 'effect';
-
-export const runIsolated = program.pipe(
-	Effect.provide(Layer.fresh(AppLayer), { local: true })
-);
-```
-
-## LLM Review Checklist
-
-Use this before submitting code:
-
-1. No `any`, no type assertions, no `@ts-ignore`, no non-null assertions.
-2. No untyped error throwing in domain logic.
-3. Nullish converted to `Option` at boundaries.
-4. Unknown input decoded with `Schema`.
-5. Canonical namespace imports (`Option`, `Schema`, `Arr`, `P`, `R`, etc.) present and used.
-6. No native `Object/Map/Set/Date/String` helpers in domain logic.
-7. Branching logic is exhaustive where appropriate (`Match.exhaustive`, schema `.match`, and `Arr.match` for array emptiness).
-8. No new schema constants end with `Schema`.
-9. For non-class schemas, new schema constants expose `export type X = typeof X.Type`.
-10. Schema annotations are used only where they materially improve docs, errors, or introspection.
-11. `Effect`-returning reusable functions are created with `Effect.fn`/`Effect.fnUntraced`.
-12. Critical flows include logs/spans/metrics instrumentation.
-13. Durations/time windows use `Duration` values.
-14. Nullish schema fields use `Schema.OptionFrom*` helpers when representing absence as `Option`.
-15. Exported helper combinators support dual API via `dual`.
-16. No `JSON.parse` / `JSON.stringify` in Effect-first domain paths.
-17. Prefer `Schema.Class` over `Schema.Struct` for all decoded shapes (domain models, HTTP responses, API payloads).
-18. Required verification commands are green.
-19. `Effect.run*` appears only in runtime boundaries (entrypoint/test harness).
-20. Promise-based APIs are lifted with `Effect.tryPromise`.
-21. Acquired resources use `Effect.acquireUseRelease` or `Effect.scoped`.
-22. Retries are declared with `Effect.retry` + `Schedule`.
-23. Timeouts use `Effect.timeoutOption` / `Effect.timeoutOrElse`.
-24. Forking intent is explicit (`forkChild` default; `forkDetach` justified).
-25. Large fan-out operations specify concurrency deliberately.
-26. Config values come from `Config` / `ConfigProvider`, not direct `process.env` in domain logic.
-27. Secrets are `Redacted` (`Config.Redacted` / `Redacted.make`) and not logged raw.
-28. Recovery uses `catchTag` / `catchFilter` for targeted cases.
-29. Expected failures use `Effect.fail`; defects are reserved for invariants and discarding irrelevant upstream error types via `orDie`.
-30. Isolation-sensitive layer provisioning uses `{ local: true }` or `Layer.fresh`.
-31. All decoded shapes (domain models, HTTP responses, API payloads) are schema-first with `Schema.Class`; plain `type` / `interface` is used only when schema is not a practical fit.
-32. Literal-string discriminant unions use `Schema.Union` + `Schema.toTaggedUnion`. For exhaustive matching over literals, use `Match`. For type guards, use `Schema.is(Schema.Literal(...))`.
-33. Schema defaults use `Schema.withConstructorDefault` / `Schema.withDecodingDefault*`, not ad-hoc fallback objects in handlers/services.
-34. Named or reused domain constraints are modeled as schemas first; built-in schema constructors/checks are preferred before `Schema.makeFilter`.
-35. Guard helpers for domain strings/paths/tags come from branded schemas with `Schema.is(...)`, not ad-hoc `regex.test(...)` predicates.
-36. Reusable schema checks and filter groups carry `identifier`, `title`, and `description`.
-37. Intermediate schemas are exported only when reusable or materially clarifying; otherwise they stay module-local.
-38. Schema-modeled comparisons use `Schema.toEquivalence(...)` where practical.
-39. Deterministic format conversions use `Schema.decodeTo(..., SchemaTransformation.transform(...))`.
-40. Trivial helper wrapper lambdas are collapsed to direct helper refs where safe, and passthrough `pipe(...)` callbacks are expressed with `flow(...)`.
-41. Runtime source avoids `node:fs` / `node:path` / `node:child_process`; use Effect `FileSystem` / `Path` / process services.
-42. Runtime source avoids native `fetch`; HTTP boundaries use `effect/unstable/http` + platform layers (`BunHttpClient.layer`, etc.).
-43. Runtime sorting uses `Arr.sort` with explicit `Order`, not native `Array.prototype.sort`.
-44. Boolean branching prefers `Bool.match` over ad-hoc `if/else` when branching on booleans.
-45. HTTP request/response composition uses Effect HTTP modules (`HttpClientRequest`, `HttpClientResponse`, `Headers`, `UrlParams`, `HttpMethod`, `HttpBody`).
-46. Retried operations have proven idempotency, and exhausted failures remain visible unless a truthful fallback exists.
-47. Provider/network calls do not run inside authoritative database transactions.

package/guidance/progressive-disclosure-guidance.md

@@ -1,35 +1,29 @@
 # 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.
-
-Load all relevant skills before writing or planning any code. Effect is a massive ecosystem — without loading skills you will write outdated v3 code or miss high-leverage libraries. Load AT LEAST 4 `effect-*` skills before any Effect work.
+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.
 
 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.
 
-## Skill routing
-
-Load every branch that the task crosses:
-
-- Schemas, brands, variants, optionality, or decoding: `effect-schema-v4`, `effect-schema-composition`, and `effect-domain-modeling`.
-- Binary schema codecs and framed binary streams: `effect-schema-composition` and `effect-stream`; RPC serialization also needs `effect-rpc-client` / `effect-rpc-server`.
-- Services, layers, runtime wiring, or scoped lifetimes: `effect-service-implementation`, `effect-layer-design`, `effect-scope`, and `effect-fiber`.
-- Configuration or secrets: `effect-config`.
-- Retry, repeat, polling, backoff, pacing, or recurrence: `effect-scheduling` plus the relevant error, HTTP, or testing skill.
-- Memoization, keyed caches, or request batching: `effect-cache` and `effect-batching`.
-- Retained keyed resources or pooled checkout: `effect-cache`, `effect-layer-design`, and `effect-scope`.
-- Streams, queues, pubsubs, pagination, or backpressure: `effect-stream` and the relevant concurrency skill.
-- Outgoing HTTP: `effect-http-client` plus the relevant platform-layer skill.
-- Effect tests, virtual time, or concurrent synchronization: `effect-testing` and `effect-concurrency-testing`.
-
 ## Start here
 
 - `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/LLMS.md` — generated task-oriented guide for Effect v4, with links to examples.
@@ -44,7 +38,7 @@ Load every branch that the task crosses:
 - `~/.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.6",
+  "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.