opencode-effect-enforcer 0.2.8 → 0.4.0

package/skills/effect-platform-layers/SKILL.md

@@ -7,6 +7,8 @@ description: Structure Effect platform layer provision for cross-platform applic
 
 Master Effect platform layer provision for cross-platform applications. Use this skill when structuring applications that use Effect platform abstractions to ensure portability across Node.js and Bun environments.
 
+Targets **Effect 4.0.0**. Keep `effect` and `@effect/*` packages on the same version and inspect the `effect@4.0.0` source tag. APIs explicitly marked `@stability unstable` can change in minor releases, including third-party client surfaces such as NodeRedis.
+
 ## The Golden Rule
 
 **Application code uses abstract interfaces. Platform-specific layers are provided either at the program entry point or inside a runtime-facing adapter module's `defaultLayer`.**
@@ -49,9 +51,10 @@ The important boundary is that downstream callers still depend on the abstract s
 
 For HTTP provider adapters, the abstract dependency is `HttpClient.HttpClient`. Keep it visible on the adapter's raw layer and name the adapter after the upstream it owns:
 
+<!-- typecheck -->
 ```typescript
 import { Context, Effect, Layer } from 'effect';
-import { FetchHttpClient, HttpClient } from 'effect/unstable/http';
+import { FetchHttpClient, HttpClient } from 'effect/http';
 
 export class ProviderGateway extends Context.Service<ProviderGateway, {
 	readonly health: Effect.Effect<void>;
@@ -120,9 +123,9 @@ Each platform context (`NodeServices.layer`, `BunServices.layer`) provides these
 | **Stdio**               | `Stdio.Stdio`                             | Standard I/O streams (stdin, stdout, stderr)        | `effect`                  |
 | **Terminal**            | `Terminal.Terminal`                       | Terminal/console I/O with ANSI support              | `effect`                  |
 | **Crypto**              | `Crypto.Crypto`                           | Cryptographic random bytes, UUIDs, and digests      | `effect`                  |
-| **ChildProcessSpawner** | `ChildProcessSpawner.ChildProcessSpawner` | Spawn and manage child processes                    | `effect/unstable/process` |
+| **ChildProcessSpawner** | `ChildProcessSpawner.ChildProcessSpawner` | Spawn and manage child processes                    | `effect/process` |
 
-`Crypto.Crypto` is included in the Node/Bun aggregate layers; browser applications can provide `BrowserCrypto.layer` when they need the crypto service. These aggregate layers are core service bundles: they do **not** provide specialized integrations such as HTTP clients/servers, sockets, workers, or Redis. For sockets, import `Socket.Socket` / `SocketServer.SocketServer` from `effect/unstable/socket` and provide socket-specific layers such as `NodeSocket.layerWebSocket(...)`, `NodeSocket.layerNet(...)`, `BunSocket.layerWebSocket(...)`, `BrowserSocket.layerWebSocket(...)`, or Node/Bun socket-server layers as appropriate.
+`Crypto.Crypto` is included in the Node/Bun aggregate layers; browser applications can provide `BrowserCrypto.layer` when they need the crypto service. These aggregate layers are core service bundles: they do **not** provide specialized integrations such as HTTP clients/servers, sockets, workers, or Redis. For sockets, import `Socket.Socket` / `SocketServer.SocketServer` from `effect/socket` and provide socket-specific layers such as `NodeSocket.layerWebSocket(...)`, `NodeSocket.layerNet(...)`, `BunSocket.layerWebSocket(...)`, `BrowserSocket.layerWebSocket(...)`, or Node/Bun socket-server layers as appropriate.
 
 Runtime application/provider HTTP belongs behind Effect `HttpClient`, not raw `fetch`. Only a named low-level platform transport adapter may use fetch directly, with a documented justification and full ownership of interruption, status-before-decode, schema decoding, and typed errors. Provider adapters also own redacted diagnostic evidence and retry exhaustion; provider calls run outside database transactions, and retries apply only to proven-idempotent operations. In particular, do not decorate a shared client with automatic retry when it can execute ordinary non-idempotent POST/PATCH requests.
 
@@ -142,9 +145,10 @@ The Node layer connects while it is built and therefore can fail with `Redis.Red
 
 ### Usage Example
 
+<!-- typecheck -->
 ```typescript
 import { Console, Crypto, Effect, FileSystem, Path, Stream, Terminal } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 
 const buildProject = Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
@@ -175,7 +179,7 @@ const buildProject = Effect.gen(function* () {
 		Stream.runForEach((line) => Console.log(`[build] ${line}`))
 	);
 	return yield* handle.exitCode;
-});
+}).pipe(Effect.scoped);
 ```
 
 ## Layer Composition Patterns
@@ -219,21 +223,23 @@ pipe(
 import { NodeServices, NodeRuntime } from '@effect/platform-node';
 import { Effect, FileSystem, Layer, pipe } from 'effect';
 
-declare const program: Effect.Effect<void, never, never>;
+declare const program: Effect.Effect<string, never, FileSystem.FileSystem>;
 
-// Custom FileSystem implementation
-const CustomFS = Layer.succeed(FileSystem.FileSystem, {
-	/* custom implementation */
-} as FileSystem.FileSystem);
+// A complete test double without asserting an incomplete object.
+const CustomFS = FileSystem.layerNoop({
+	readFileString: () => Effect.succeed('custom content')
+});
 
 pipe(
 	program,
+	Effect.provide(CustomFS), // Innermost provision wins for program reads
 	Effect.provide(NodeServices.layer),
-	Effect.provide(CustomFS), // Override after platform layer
 	NodeRuntime.runMain
 );
 ```
 
+Provision nests: `program.pipe(Effect.provide(A), Effect.provide(B))` builds A inside B, and A wins for overlapping services seen by `program`. An already-built aggregate such as `NodeServices.layer` wires its own internal dependencies; replacing the FileSystem seen by application code does not rewire its child-process spawner. Compose individual platform layers when those internal dependencies must also be replaced.
+
 ## Testing with Mock Layers
 
 **CRITICAL**: Prefer mock abstract services for unit tests. For runtime-adapter or layer-composition tests, it is acceptable to provide the real Node/Bun layers directly when that is the behavior under review.
@@ -242,12 +248,12 @@ pipe(
 
 ```typescript
 import { Effect, FileSystem, Layer } from 'effect';
-import { expect, test } from 'vitest';
+import { expect, it } from '@effect/vitest';
 
 declare const readConfig: Effect.Effect<string, never, FileSystem.FileSystem>;
 
-// Use FileSystem.makeNoop for testing — provides default "NotFound" stubs
-// for all methods, then override only the ones you need
+// makeNoop supplies NotFound for many operations, exists=false, remove=void,
+// and defects for directory/temp creation. Override each operation the test uses.
 const MockFileSystem = Layer.succeed(
 	FileSystem.FileSystem,
 	FileSystem.makeNoop({
@@ -256,18 +262,18 @@ const MockFileSystem = Layer.succeed(
 	})
 );
 
-test('should read config', () =>
+it.effect('should read config', () =>
 	Effect.gen(function* () {
 		const result = yield* readConfig;
 		expect(result).toContain('mock content');
-	}).pipe(Effect.provide(MockFileSystem), Effect.runPromise));
+	}).pipe(Effect.provide(MockFileSystem)));
 ```
 
 ### Mocking Multiple Services
 
 ```typescript
 import { Effect, FileSystem, Layer, Path, Terminal } from 'effect';
-import { test } from 'vitest';
+import { it } from '@effect/vitest';
 
 declare const program: Effect.Effect<
 	void,
@@ -276,38 +282,33 @@ declare const program: Effect.Effect<
 >;
 
 const TestContext = Layer.mergeAll(
-	Layer.succeed(FileSystem.FileSystem, {
+	FileSystem.layerNoop({
 		readFileString: () => Effect.succeed('test')
-		// ...
-	} as FileSystem.FileSystem),
+	}),
 
-	Layer.succeed(Path.Path, {
-		join: (...parts) => parts.join('/'),
-		normalize: (path) => path
-		// ...
-	} as Path.Path),
+	Path.layer, // Complete, deterministic POSIX path operations
 
 	Layer.succeed(
 		Terminal.Terminal,
 		Terminal.make({
 			columns: Effect.succeed(80),
 			rows: Effect.succeed(24),
-		readInput: Effect.die('readInput not used in this test'),
+			readInput: Effect.die('readInput not used in this test'),
 			readLine: Effect.succeed('test input'),
 			display: () => Effect.void
 		})
 	)
 );
 
-test('integration test', () =>
-	program.pipe(Effect.provide(TestContext), Effect.runPromise));
+it.effect('integration test', () =>
+	program.pipe(Effect.provide(TestContext)));
 ```
 
 ### Using layerNoop for Convenient Test Layers
 
 ```typescript
 import { Effect, FileSystem } from 'effect';
-import { test } from 'vitest';
+import { it } from '@effect/vitest';
 
 // FileSystem.layerNoop wraps makeNoop in a Layer for convenience
 const TestFS = FileSystem.layerNoop({
@@ -316,11 +317,11 @@ const TestFS = FileSystem.layerNoop({
 	exists: () => Effect.succeed(true)
 });
 
-test('with layerNoop', () =>
+it.effect('with layerNoop', () =>
 	Effect.gen(function* () {
 		const fs = yield* FileSystem.FileSystem;
 		yield* fs.writeFileString('test.txt', 'content');
-	}).pipe(Effect.provide(TestFS), Effect.runPromise));
+	}).pipe(Effect.provide(TestFS)));
 ```
 
 ## Architecture Patterns
@@ -339,24 +340,28 @@ src/
 
 ### Service Implementation
 
+<!-- typecheck -->
 ```typescript
 // services/ConfigService.ts
-import { Effect, FileSystem, Layer, Path, Schema, Context } from 'effect';
+import { Effect, FileSystem, Layer, Path, Context } from 'effect';
+import * as Schema from 'effect/Schema';
 
-interface Config {
-	readonly name: string;
-	readonly version: string;
-}
+class Config extends Schema.Class<Config>('Config')({
+	name: Schema.String,
+	version: Schema.String
+}) {}
 
-declare const ConfigSchema: Schema.Schema<Config>;
+const ConfigJson = Schema.fromJsonString(Config);
 
 class ConfigError extends Schema.TaggedError<ConfigError>()(
 	'ConfigError',
 	{
-		message: Schema.String
+		operation: Schema.Literals(['load', 'save']),
+		cause: Schema.Defect()
 	}
 ) {}
 
+/** Loads and saves schema-validated application configuration. */
 export class ConfigService extends Context.Service<
 	ConfigService,
 	{
@@ -365,6 +370,7 @@ export class ConfigService extends Context.Service<
 	}
 >()('ConfigService') {}
 
+/** Requires abstract file-system and path services; preserves boundary failures. */
 export const ConfigServiceLive = Layer.effect(
 	ConfigService,
 	Effect.gen(function* () {
@@ -374,15 +380,18 @@ export const ConfigServiceLive = Layer.effect(
 		const load = Effect.gen(function* () {
 			const configPath = path.join('config', 'app.json');
 			const content = yield* fs.readFileString(configPath);
-			return yield* Schema.decode(ConfigSchema)(JSON.parse(content));
-		});
+			return yield* Schema.decodeUnknownEffect(ConfigJson)(content);
+		}).pipe(Effect.mapError((cause) => new ConfigError({ operation: 'load', cause })));
 
-		const save = (config: Config) =>
-			Effect.gen(function* () {
+		const save = Effect.fn('Config.save')(
+			function* (config: Config) {
 				const configPath = path.join('config', 'app.json');
-				const content = JSON.stringify(config, null, 2);
+				const content = yield* Schema.encodeEffect(ConfigJson)(config);
+				yield* fs.makeDirectory(path.dirname(configPath), { recursive: true });
 				yield* fs.writeFileString(configPath, content);
-			});
+			},
+			Effect.mapError((cause) => new ConfigError({ operation: 'save', cause }))
+		);
 
 		return { load, save };
 	})
@@ -418,27 +427,23 @@ pipe(
 
 ## Common Patterns
 
-### Conditional Platform Loading
+### Runtime-Specific Entry Points
 
 ```typescript
+// main-node.ts
 import { NodeServices, NodeRuntime } from '@effect/platform-node';
-import { BunServices } from '@effect/platform-bun';
-import { Effect, pipe } from 'effect';
+import { Effect } from 'effect';
 
 declare const program: Effect.Effect<void, never, never>;
 
-const PlatformContext =
-	process.env.RUNTIME === 'bun' ? BunServices.layer : NodeServices.layer;
-
-pipe(
-	program,
-	Effect.provide(PlatformContext),
-	NodeRuntime.runMain // Runtime matches context
-);
+program.pipe(Effect.provide(NodeServices.layer), NodeRuntime.runMain);
 ```
 
+Use `BunServices.layer` with `BunRuntime.runMain` in the Bun entry point. Separate entry points avoid eagerly loading adapters for a different runtime or selecting a layer independently of its runner.
+
 ### Scoped Platform Resources
 
+<!-- typecheck -->
 ```typescript
 import { Effect, FileSystem, Path } from 'effect';
 
@@ -446,17 +451,13 @@ const withTempDirectory = Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 
-	const tempDir = yield* Effect.acquireRelease(
-		Effect.gen(function* () {
-			const dir = path.join('temp', `${Date.now()}`);
-			yield* fs.makeDirectory(dir, { recursive: true });
-			return dir;
-		}),
-		(dir) => fs.remove(dir, { recursive: true })
-	);
+	const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: 'app-' });
+	const file = path.join(tempDir, 'result.txt');
+	yield* fs.writeFileString(file, 'result');
 
-	return tempDir;
-});
+	// Return a durable value, not the path to a resource about to be deleted.
+	return yield* fs.readFileString(file);
+}).pipe(Effect.scoped);
 ```
 
 ## Anti-Patterns
@@ -506,8 +507,8 @@ export const myService = program.pipe(
 1. **Import abstractions, provide implementations**: Application code imports from `effect` (e.g. `FileSystem`, `Path`, `Terminal`), entry points provide platform-specific contexts
 2. **One platform layer per runtime**: Use exactly one of `NodeServices.layer` or `BunServices.layer`
 3. **Platform layer last**: Provide custom services first, platform context last
-4. **Mock in tests**: Use `Layer.succeed` with mock implementations, never import platform-specific modules in tests
-5. **Entry point decides platform**: Only `main.ts` (or equivalent entry) should import platform-specific modules
+4. **Test through services**: Use complete test layers for unit tests; real platform layers belong in runtime-adapter or composition tests
+5. **Own platform wiring**: Entry points and runtime-facing adapter `defaultLayer` exports may import platform-specific modules
 6. **Keep HTTP transport requirements visible**: Provider adapter `layer` requires `HttpClient.HttpClient`; an optional `defaultLayer` may provide the chosen transport
 7. **Make adapters own the boundary**: Named adapters classify status before schema decoding, map typed failures, retain redacted evidence, and expose retry exhaustion
 8. **Do not retry by accident**: Restrict retrying/rate-limited clients to proven-idempotent operations; non-idempotent calls need an explicit provider guarantee or idempotency key

package/skills/effect-pubsub-event-bus/SKILL.md

@@ -192,41 +192,48 @@ const make = Effect.gen(function* () {
 
 ## Pattern: Graceful Shutdown Event
 
-Publish a final event before shutting down PubSub channels so subscribers can perform cleanup:
+Use `PubSub.end(pubsub, finalEvent)` to deliver a terminal event after buffered
+messages. The terminal event occupies no capacity, cannot be dropped by a full
+bounded channel, and reaches future subscribers too (after any replay values).
+Pending backpressured publishers and later publishes return `false`.
 
-```typescript
-yield*
-	Effect.addFinalizer(() =>
-		Effect.gen(function* () {
-			// Notify all subscribers that the bus is shutting down
-			yield* PubSub.publish(
-				wildcard,
-				new InstanceDisposed({ reason: 'scope-closed' })
-			);
-			// Then shut down the channel
-			yield* PubSub.shutdown(wildcard);
-		})
-	);
-```
-
-Subscribers can detect this event and perform teardown:
+The terminal event is **sticky**: further `take` calls return it again. Raw
+subscribers must stop, and `Stream.fromPubSub` consumers must use a terminal
+predicate such as `Stream.takeUntil`. `take`, `takeAll`, and `takeBetween` deliver
+it; non-suspending `takeUpTo` does not.
 
+<!-- typecheck -->
 ```typescript
-yield*
-	bus.subscribeAll.pipe(
-		Stream.takeUntil((evt) => evt instanceof InstanceDisposed),
-		Stream.runForEach(handleEvent),
-		Effect.forkScoped
-);
+import { Effect, PubSub } from 'effect';
+
+const program = Effect.gen(function* () {
+	const pubsub = yield* PubSub.bounded<string>(1);
+	yield* Effect.addFinalizer(() => PubSub.shutdown(pubsub));
+	const subscription = yield* PubSub.subscribe(pubsub);
+	yield* PubSub.publish(pubsub, 'work');
+	yield* PubSub.end(pubsub, 'finished'); // succeeds even with the buffer full
+	const work = yield* PubSub.take(subscription);
+	const terminal = yield* PubSub.take(subscription);
+	const late = yield* PubSub.subscribe(pubsub);
+	const lateTerminal = yield* PubSub.take(late);
+	return { work, terminal, lateTerminal };
+}).pipe(Effect.scoped);
 ```
 
+For a domain bus, use a tagged terminal variant rather than a string sentinel.
+End the bus while consumers are still alive, then await their completion before
+closing their scope. `PubSub.shutdown` interrupts subscribers and discards their
+ability to drain; calling it immediately after publishing or ending does not
+guarantee the final event is handled. Keep shutdown as the final cleanup step,
+not the graceful notification mechanism.
+
 ## Redis Pub/Sub
 
 For cross-process pub/sub, use the portable `Redis.Redis` service rather than modeling Redis as an in-memory `PubSub`. `redis.subscribe(channel)` is scoped and returns a dequeue whose values contain both `channel` and `message`.
 
 ```typescript
 import { Effect, Stream } from 'effect';
-import { Redis } from 'effect/unstable/persistence';
+import { Redis } from 'effect/persistence';
 
 declare const handleRedisMessage: (
 	channel: string,
@@ -249,54 +256,38 @@ The subscription uses a dedicated client and is released when the enclosing scop
 
 ## Testing PubSub Services
 
-Testing PubSub subscriptions requires specific choreography:
-
-1. Fork the consumer fiber
-2. Wait for subscriber readiness explicitly when possible; otherwise use a tiny registration barrier
-3. Publish events
-4. Gate on a `Deferred` for synchronization
+Acquire the subscription before publishing, then fork consumption if needed.
+For a service that exposes only `Stream`, provide a test seam that signals actual
+subscription readiness. Starting a fiber, or signaling before the subscription
+is acquired, is not a registration barrier.
 
 ```typescript
-import { Deferred, Effect, PubSub, Stream } from 'effect';
+import { Effect, Fiber, PubSub, Stream } from 'effect';
+import * as Arr from 'effect/Array';
 
 it.effect('should receive published events', () =>
 	Effect.gen(function* () {
-		const bus = yield* Bus.Service;
-		const received: Array<string> = [];
-		const done = yield* Deferred.make<void>();
-
-		// 1. Fork the consumer
-		yield* bus.subscribe(FileChanged).pipe(
-			Stream.runForEach((evt) =>
-				Effect.gen(function* () {
-					received.push(evt.path);
-					if (received.length === 2) {
-						yield* Deferred.succeed(done, undefined);
-					}
-				})
-			),
-			Effect.forkScoped
+		const pubsub = yield* PubSub.unbounded<FileChanged>();
+		yield* Effect.addFinalizer(() => PubSub.shutdown(pubsub));
+		const subscription = yield* PubSub.subscribe(pubsub);
+		const consumer = yield* Stream.fromEffectRepeat(PubSub.take(subscription)).pipe(
+			Stream.take(2),
+			Stream.runCollect,
+			Effect.forkChild
 		);
 
-		// 2. Registration barrier
-		yield* Effect.sleep('10 millis');
-
-		// 3. Publish events
-		yield* bus.publish(new FileChanged({ path: 'a.ts', kind: 'modified' }));
-		yield* bus.publish(new FileChanged({ path: 'b.ts', kind: 'created' }));
-
-		// 4. Wait for events to be received
-		yield* Deferred.await(done);
-
-		expect(received).toEqual(['a.ts', 'b.ts']);
-	}).pipe(Effect.provide(Bus.layer))
+		yield* PubSub.publish(pubsub, new FileChanged({ path: 'a.ts', kind: 'modified' }));
+		yield* PubSub.publish(pubsub, new FileChanged({ path: 'b.ts', kind: 'created' }));
+		const received = yield* Fiber.join(consumer);
+		expect(Arr.map(received, (event) => event.path)).toEqual(['a.ts', 'b.ts']);
+	})
 );
 ```
 
 **Notes:**
 
-- The `runForEach` handler is effectful, so complete the gate with `yield* Deferred.succeed(done, undefined)`. There is no `Deferred.unsafeDone` in v4; reach for the low-level `Deferred.doneUnsafe(done, Effect.void)` only inside a truly synchronous callback that has no surrounding effect.
-- The tiny sleep above is an acceptable fallback for `Stream.fromPubSub` registration when no explicit readiness hook exists. If you control the consumer stream, prefer a readiness `Deferred` or latch instead.
+- `PubSub.subscribe` is already scoped; `it.effect` supplies its lifetime. No manual unsubscribe or sleeps are needed.
+- If a service uses a readiness `Deferred`, complete it only after `PubSub.subscribe` has returned. Acquiring a stream pull alone does not prove its lazy subscription has started.
 - To drain a `PubSub` subscription for assertions, prefer `PubSub.takeUpTo(sub, n)`: it returns immediately with whatever is buffered (possibly an empty array). `PubSub.takeAll(sub)` **suspends when the subscription is empty** and returns a `NonEmptyArray`, so it cannot be used to assert “no more events” — it would hang waiting for one.
 
 ## PubSub Configuration
@@ -330,6 +321,11 @@ Choose based on your use case:
 
 **PubSub is not an event log.** Messages are delivered to *active* subscribers only. A subscriber that attaches after a value was published does not see that value unless a `replay` buffer is configured, and `replay` only retains the most recent N values — it is bounded, recent-only, and not durable storage. If you need every consumer to observe the full history, subscribe before publishing (see the testing choreography above) or persist events separately.
 
+The final value passed to `PubSub.end` is the exception: every subscriber sees
+it even without replay. An `Infinity` capacity behaves as unbounded; use
+`PubSub.unbounded` when that is the intended policy. `PubSub.isPubSub(value)` is
+the runtime guard for unknown values.
+
 ## DO / DON'T
 
 ### DO: Use `Stream.fromPubSub` + `forkScoped` for subscriptions

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

@@ -7,15 +7,19 @@ description: Build composable React components using Effect Atom for state manag
 
 Build React UIs using compositional patterns, Effect Atom for state management, and the component module pattern. Use this skill when creating React applications that integrate with Effect's ecosystem.
 
+`@effect/atom-react@4.0.0` requires React `>=19.0.0 <20.0.0` and the same version
+of `effect`. Core `effect/reactivity` APIs remain `@stability unstable` and can
+change incompatibly in minor releases.
+
 ## 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>` there for this baseline; main may be ahead.
 
 Reference this for:
 
-- Atom reactivity: `packages/effect/src/unstable/reactivity/`
-- AsyncResult source: `packages/effect/src/unstable/reactivity/AsyncResult.ts`
+- Atom reactivity: `packages/effect/src/reactivity/`
+- AsyncResult source: `packages/effect/src/reactivity/AsyncResult.ts`
 - Effect source: `packages/effect/src/`
 
 ## When to Use This Skill
@@ -291,11 +295,20 @@ function ExternalButton() {
 
 Effect Atom provides reactive state management that integrates seamlessly with React.
 
+Share a `RegistryProvider` across components that should share atom state. Its
+registry options are initialization-only; changing them after first render does
+not rebuild the registry. Cleanup is delayed briefly on unmount and canceled on
+quick remount, supporting React's development lifecycle. Unused atoms follow
+their idle TTL/registry policy, so an unmount is not a synchronous reset signal.
+Use `Atom.keepAlive` intentionally for state that should outlive subscriptions,
+and keep external-resource cleanup in atom finalizers. See `effect-atom-state`
+for SWR, concurrent function atoms, and batching semantics.
+
 ### Pattern: Basic Atom State
 
 ```typescript
 // state/Cart.ts
-import * as Atom from 'effect/unstable/reactivity/Atom';
+import * as Atom from 'effect/reactivity/Atom';
 import { Effect } from 'effect';
 
 /**
@@ -496,7 +509,7 @@ Use `runtime.atom` and `Atom.family` for query-like data. The runtime wraps the
 
 ```typescript
 // state/User.ts
-import * as Atom from 'effect/unstable/reactivity/Atom';
+import * as Atom from 'effect/reactivity/Atom';
 import { Effect } from 'effect';
 import { UserService } from '@/services/UserService';
 
@@ -522,7 +535,7 @@ export const userData = Atom.family((userId: string) =>
 
 ```tsx
 import { useAtomValue } from '@effect/atom-react';
-import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
+import * as AsyncResult from 'effect/reactivity/AsyncResult';
 import * as User from '@/state/User';
 
 function UserProfile({ userId }: { userId: string }) {