opencode-effect-enforcer 0.2.8 → 0.4.0

package/skills/effect-concurrency-testing/SKILL.md

@@ -16,12 +16,15 @@ This skill provides patterns for testing Effect's concurrency primitives: fibers
 | Simple fiber yield                | `Effect.yieldNow`                                                                     |
 | Wait for subscriber ready         | `Deferred.make()` + `Deferred.await`                                                  |
 | Wait for stream element           | `Latch.make()` + `Stream.tap(() => latch.open)`                                       |
-| Passive subscription registration | explicit readiness signal if possible; otherwise a tiny one-tick yield/sleep fallback |
+| Passive subscription registration | acquire `PubSub.subscribe` before publishing, or expose a readiness signal             |
 | Time-dependent behavior           | `TestClock.adjust`                                                                    |
 | Verify events published           | `PubSub.subscribe` + `PubSub.takeUpTo`                                                |
 | Check fiber status                | `fiber.pollUnsafe()`                                                                  |
 
-For `Stream.fromPubSub` subscription registration, prefer an explicit readiness signal when you control the stream. If the API offers no readiness hook and you only need registration to settle before publishing, a tiny `Effect.yieldNow()` or very short sleep is an acceptable last resort. Avoid broad polling or arbitrary delays.
+For `Stream.fromPubSub` registration, signal readiness after acquiring the actual
+subscription, not merely before starting the stream. A scheduler yield is not a
+general readiness guarantee; a sleep under `it.effect` also needs `TestClock`
+advancement. Prefer a subscription-first test seam to arbitrary delays.
 
 ## Fiber Coordination Patterns
 
@@ -39,7 +42,7 @@ it.effect('fiber polling with yieldNow', () =>
 
 		const fiber = yield* latch.await.pipe(Effect.forkChild);
 
-		yield* Effect.yieldNow();
+		yield* Effect.yieldNow;
 
 		expect(fiber.pollUnsafe()).toBeUndefined();
 
@@ -67,7 +70,7 @@ it.effect('latch coordination', () =>
 			return 'completed';
 		}).pipe(Effect.forkChild);
 
-		yield* Effect.yieldNow();
+		yield* Effect.yieldNow;
 		expect(fiber.pollUnsafe()).toBeUndefined();
 
 		yield* latch.open;
@@ -436,6 +439,23 @@ it.effect('should run finalizers', () =>
 
 ## Interruption Testing
 
+Test cancellation at the resource-owning boundary, using a `Deferred` to prove
+work has started before interrupting it:
+
+- Shared `ScopedCache` lookup: cancel one of two waiters and let the other
+  finish; then cancel the last waiter on another pending lookup and verify its
+  resource finalizer ran and a later `get` reacquires.
+- `race` / `raceFirst` / iterable variants: assert loser cleanup is complete when
+  the race returns, including cancellation while contenders are starting.
+- `Scope.close`: gate a finalizer, interrupt the closing fiber, release the gate,
+  and verify remaining finalizers still run.
+- `ManagedRuntime.dispose`: verify request cleanup can use layer services before
+  those services are released.
+- Queue batches: offer fewer than `takeN` requests, verify the taker remains
+  pending, then `end` or `fail` and assert the short final batch precedes the
+  terminal outcome. For PubSub, test the `end` value with `take`, not `takeUpTo`,
+  including a late subscriber and a full dropping buffer.
+
 ### Testing Fiber Interruption
 
 ```typescript
@@ -518,7 +538,7 @@ Effect.gen(function* () {
 // GOOD - Use yieldNow for simple yielding
 Effect.gen(function* () {
 	const fiber = yield* someEffect.pipe(Effect.forkChild);
-	yield* Effect.yieldNow();
+	yield* Effect.yieldNow;
 	yield* Fiber.join(fiber);
 });
 ```
@@ -538,7 +558,7 @@ while (fiber.pollUnsafe() === undefined) {
 // GOOD - Yield between polls or use Fiber.await
 Effect.gen(function* () {
 	while (fiber.pollUnsafe() === undefined) {
-		yield* Effect.yieldNow();
+		yield* Effect.yieldNow;
 	}
 });
 

package/skills/effect-config/SKILL.md

@@ -89,9 +89,36 @@ const host = Config.String('HOST').pipe(
 );
 ```
 
+The fallback result replaces the original failure. If the fallback is absent,
+an outer `withDefault` or `option` can recover it even when the primary input
+was invalid. If the fallback fails, its error propagates. `Config.fail(error)`
+has type `Config<never>` and does not widen a composed result to `unknown`.
+
+### `Config.flatMap` — Select a Dependent Config
+
+Use `map` for a pure value transformation, `mapEffect` for a transformation that
+may fail with `ConfigError`, and `flatMap` when the parsed value selects another
+`Config`. The selected config uses the same provider and nesting prefix; the
+callback runs only after successful resolution of the first config.
+
+<!-- typecheck -->
+```ts
+import { Config, ConfigProvider } from 'effect';
+
+const host = Config.Literals(['development', 'production'], 'MODE').pipe(
+	Config.flatMap((mode) => Config.NonEmptyString(
+		mode === 'development' ? 'DEV_HOST' : 'PROD_HOST'
+	)),
+	Config.nested('APP')
+);
+const parsed = host.parse(ConfigProvider.fromUnknown({
+	APP: { MODE: 'production', PROD_HOST: 'api.example.com' }
+}));
+```
+
 ### `Config.all` — Combine Multiple Configs
 
-Accepts a record or a tuple:
+Accepts a record, tuple, or iterable of configs:
 
 ```ts
 // As a record
@@ -105,6 +132,28 @@ const appConfig = Config.all({
 const pair = Config.all([Config.String('a'), Config.Int('b')]);
 ```
 
+A group is absent when any child is absent and no child fails, even if other
+children have supplied values. `Config.option(group)` then returns `None`;
+`Config.withDefault(group, fallback)` replaces the **whole group**. Put defaults
+on individual children to retain supplied siblings. Validation and source
+errors still propagate. Use `Config.schema(Schema.Struct(...))` when an existing
+but incomplete object must fail validation rather than default.
+
+<!-- typecheck -->
+```ts
+import { Config, ConfigProvider, Effect } from 'effect';
+
+const group = Config.all({
+	host: Config.String('HOST'),
+	port: Config.Int('PORT')
+}).pipe(Config.withDefault({ host: 'localhost', port: 3000 }));
+
+const result = Effect.runSync(group.parse(
+	ConfigProvider.fromUnknown({ HOST: 'supplied.example.com' })
+));
+// { host: 'localhost', port: 3000 } — the supplied host is replaced too.
+```
+
 ### `Config.nested` — Scope Under a Prefix
 
 Prepends a path segment to every key the inner config reads. With environment variables, nesting uses `_` as separator.
@@ -346,7 +395,9 @@ const defaults = ConfigProvider.fromUnknown({
 const combined = ConfigProvider.orElse(envProvider, defaults);
 ```
 
-At the `Config` level, `Config.orElse` preserves evidence that the primary branch read provider input. Consequently, an outer `Config.withDefault` or `Config.option` does not hide a partially supplied `Config.all` group.
+At the `Config` level, `Config.orElse` handles missing data and all `ConfigError`s;
+its fallback determines whether an outer default or option can recover. Provider
+fallback only chooses a source and does not perform that error recovery.
 
 ### `ConfigProvider.nested` — Prefix All Lookups
 

package/skills/effect-context-witness/SKILL.md

@@ -36,7 +36,7 @@ export const PaymentIntent = Schema.Struct({
 Field **removed from schema**, only injected in code:
 
 ```typescript
-import { Schema, Context, Effect, Logger } from 'effect';
+import { Schema, Context, Effect } from 'effect';
 
 declare const generateId: () => string;
 
@@ -56,7 +56,7 @@ const createPaymentIntent = (amount: bigint) =>
 
 		// Use serial in business logic, logging, etc.
 		// but it's not part of the persisted data
-		yield* Logger.info(`Creating payment intent ${serial}`);
+		yield* Effect.logInfo(`Creating payment intent ${serial}`);
 
 		return PaymentIntent.make({ id: generateId(), amount });
 	});
@@ -177,7 +177,7 @@ Good fits:
 Witnesses are trivial to provide:
 
 ```typescript
-import { Effect } from 'effect';
+import { Context, Effect } from 'effect';
 
 declare const myProgram: Effect.Effect<unknown, never, Serial>;
 declare class Serial extends Context.Service<Serial, string>()('Serial') {}
@@ -188,7 +188,7 @@ const test = myProgram.pipe(Effect.provideService(Serial, 'test-serial-123'));
 Capabilities need implementation:
 
 ```typescript
-import { Effect } from 'effect';
+import { Context, Effect } from 'effect';
 
 declare const myProgram: Effect.Effect<unknown, never, SerialService>;
 declare class SerialService extends Context.Service<
@@ -217,7 +217,7 @@ const test = myProgram.pipe(
 - **Yes** → Keep in schema
 
 ```typescript
-import { Schema, Context, Effect, Logger, Clock } from 'effect';
+import { Schema, Context, Effect, Clock } from 'effect';
 
 declare const LineItem: Schema.Schema<any>;
 declare const generateId: () => string;
@@ -245,7 +245,7 @@ const createOrder = (items: Array<Schema.Schema.Type<typeof LineItem>>) =>
 		const requestId = yield* RequestId; // For logging
 		const timestamp = yield* Clock.currentTimeMillis; // For timestamp
 
-		yield* Logger.info({
+		yield* Effect.logInfo({
 			message: 'Creating order',
 			correlationId, // Used for tracing
 			requestId, // Used for logging

package/skills/effect-domain-modeling/SKILL.md

@@ -13,7 +13,7 @@ and `effect-typeclass-design` for reusable predicate/order APIs.
 
 ## Source Reference
 
-Baseline: **Effect 4.0.0-rc.116**. In the Effect source reference, consult
+Baseline: **Effect 4.0.0**. In the Effect source reference, consult
 `packages/effect/SCHEMA.md` and `packages/effect/src/{Schema,Match,DateTime,Order}.ts`.
 Verify the installed version and source tag before applying newer APIs.
 
@@ -38,6 +38,13 @@ when encoded values or service requirements matter; do not erase them with `any`
 
 ## Complete Model: Task Lifecycle
 
+`Schema.brand` is a type-only distinction with no runtime AST metadata or extra
+checks. Each call takes one concrete string literal (not a widened string,
+union, or open template); compose brands with repeated calls. A brand does not
+prove a domain invariant unless the underlying schema checks it. Representations
+and generated schema code omit brands, so reapply them after rebuilding a model.
+`Schema.fromBrand` preserves constructor checks and requires its sole brand key.
+
 This module demonstrates brands, class variants, exhaustive/partial matching,
 schema guards, equivalence, orders, dual helpers, and legal transitions.
 

package/skills/effect-error-handling/SKILL.md

@@ -89,7 +89,7 @@ Reference this for:
 
 ## Core Error Handling Philosophy
 
-Effect distinguishes between two types of failures:
+Effect distinguishes expected errors from defects:
 
 1. **Expected Errors (Error Channel)** - Business logic failures that should be handled
     - Type-safe and tracked in the effect signature: `Effect<A, E, R>`
@@ -101,6 +101,12 @@ Effect distinguishes between two types of failures:
     - Result from programming mistakes (null refs, unhandled cases, assertions)
     - Usually should NOT be caught; use catchDefect only at boundaries
 
+Interruption is cancellation, a separate `Cause` reason rather than a typed
+business error. A cause can retain several reasons: if work fails and its
+finalizer throws, both the original failure and the finalizer defect remain.
+Inspect the full `Cause` at supervision boundaries rather than assuming one
+reason or discarding cancellation during cleanup.
+
 ### Runtime Adapter Boundaries and Invariants
 
 Do not force every impossible or adapter-internal failure into a tagged error just to satisfy a blanket rule.
@@ -1047,6 +1053,13 @@ The `instanceof` guard prevents double-wrapping when an upstream operation alrea
 
 ## Error Recovery Patterns
 
+For per-item typed outcomes, `Effect.partition(items, work, { concurrency })`
+returns `[successes, failures]`, in that order. Both arrays preserve input order.
+`Effect.all(..., { mode: 'result' })` instead preserves the input structure with
+one `Result` per slot. Their `never` error channel means typed failures are
+collected; defects and interruption still propagate. Use `Effect.validate` when
+any item failure must fail the entire batch with all typed errors.
+
 Retry timing and recurrence design belong in the dedicated effect-scheduling skill. This skill determines which failures are typed and recoverable; scheduling determines whether, when, and how often an idempotent operation is retried.
 
 ### Translate at Service Boundaries
@@ -1388,7 +1401,7 @@ Model ambiguous HTTP responses (where the body structure differs for success vs
 
 ```typescript
 import { Effect, Schema } from 'effect';
-import { HttpClientResponse } from 'effect/unstable/http';
+import { HttpClientResponse } from 'effect/http';
 
 class TokenSuccess extends Schema.Class<TokenSuccess>('TokenSuccess')({
 	access_token: AccessToken,

package/skills/effect-fiber/SKILL.md

@@ -346,7 +346,7 @@ const detached = Effect.gen(function* () {
 
 Whichever lifetime you pick, **a forked fiber's failure is observed by nobody unless you arrange it**: `join`/`await` the fiber, supervise it via `FiberHandle`/`FiberMap`/`FiberSet` `join`, or attach `Effect.catchCause`/`Effect.onError` plus logging inside the forked effect. v4 removed `Effect.forkWithErrorHandler`, and the runtime does not log unhandled fiber failures.
 
-`Effect.awaitAllChildren` only waits for children forked while the wrapped effect runs — children that existed beforehand are not awaited.
+`Effect.awaitAllChildren` only waits for children forked while the wrapped effect runs — children that existed beforehand are not awaited. The child wait respects the surrounding interruptibility. If interrupted while waiting after the wrapped effect failed, the resulting cause retains both the original failure and interruption; an enclosing uninterruptible region keeps the wait uninterruptible.
 
 `forkIn`/`forkScoped` register an interruption finalizer on the scope and remove it when the fiber completes on its own. Forking into an already-closed scope interrupts the new fiber immediately. The same applies to `Fiber.runIn(fiber, scope)`, which only registers the finalizer — it does not wait for the fiber.
 
@@ -380,7 +380,7 @@ const program = Effect.gen(function* () {
 }).pipe(Effect.scoped);
 ```
 
-`run` options: `{ onlyIfMissing?: boolean; propagateInterruption?: boolean }`. The type also accepts `startImmediately`, but it is a no-op — collection fibers are forked via `Effect.runForkWith` and always start synchronously (see "How collection fibers relate to the caller" in section 8).
+`run` options: `{ onlyIfMissing?: boolean; propagateInterruption?: boolean; startImmediately?: boolean }`. Startup is immediate by default; `startImmediately: false` defers it (see "How collection fibers relate to the caller" in section 8).
 
 ### join vs awaitEmpty
 
@@ -462,7 +462,7 @@ const program = Effect.gen(function* () {
 }).pipe(Effect.scoped);
 ```
 
-`run` options are the same as FiberHandle's: `{ onlyIfMissing?, propagateInterruption? }` (`startImmediately` is in the type but is a no-op here too). `set`/`setUnsafe` install existing fibers under a key with `{ onlyIfMissing?, propagateInterruption? }`.
+`run` options are the same as FiberHandle's: `{ onlyIfMissing?, propagateInterruption?, startImmediately? }`. Startup defaults to immediate; `false` defers it. `set`/`setUnsafe` install existing fibers under a key with `{ onlyIfMissing?, propagateInterruption? }`.
 
 Runtime helpers take the key as the first runner argument:
 
@@ -482,7 +482,7 @@ Closed-map behavior matches FiberHandle: `FiberMap.run` interrupts the caller; r
 
 ## 8. FiberSet — Grow-Only Fiber Collections
 
-`FiberSet<A, E>` tracks an unkeyed set of fibers. No replacement semantics — every `run`/`add` grows the set; completed fibers remove themselves; scope close interrupts all. Nothing limits admission: unbounded `run` calls on a production ingest path are a hazard — gate them with a `Semaphore` (see the bounded pattern under Key Patterns).
+`FiberSet<A, E>` tracks an unkeyed set of fibers. No replacement semantics — every `run`/`add` grows the set; completed fibers remove themselves; scope close interrupts all. Nothing limits admission. For a finite work list, prefer bounded `Effect.forEach`; for ongoing ingestion, use a bounded queue with a fixed set of workers.
 
 ```ts
 const program = Effect.gen(function* () {
@@ -504,7 +504,7 @@ const program = Effect.gen(function* () {
 }).pipe(Effect.scoped);
 ```
 
-`run` options: `{ propagateInterruption? }` (no `onlyIfMissing` — there is no key; `startImmediately` is in the type but is a no-op). On a closed set, `FiberSet.run` returns an already-interrupted fiber (it does **not** interrupt the caller, unlike FiberHandle/FiberMap).
+`run` options: `{ propagateInterruption?, startImmediately? }` (no `onlyIfMissing` — there is no key). Startup defaults to immediate; `false` defers it. On a closed set, `FiberSet.run` returns an already-interrupted fiber (it does **not** interrupt the caller, unlike FiberHandle/FiberMap).
 
 Runtime helpers mirror the others in shape. `FiberSet.runtime` and `runtimePromise` forward `propagateInterruption` when registering the managed fiber:
 
@@ -519,11 +519,14 @@ const runPromise2 = yield* FiberSet.makeRuntimePromise();
 
 ### How collection fibers relate to the caller
 
-Fibers forked via `FiberHandle/FiberMap/FiberSet.run` (and the runtime runners) are created with `Effect.runForkWith(parent.context)` — they are **root fibers carrying the caller's services, not children of the calling fiber**. Consequences:
+Fibers forked via `FiberHandle/FiberMap/FiberSet.run` carry the caller's context but are **detached from its child lifetime** and owned by the collection. Consequences:
 
-- They start executing **immediately and synchronously** up to their first suspension (no lazy start, unlike `Effect.forkChild`).
+- `run` starts them **immediately** by default; pass `{ startImmediately: false }` to defer startup. This differs from `Effect.forkChild`, whose default is deferred.
 - The calling fiber's completion does not interrupt them — only key replacement, `remove`/`clear`, or the collection's scope close does.
 
+The captured `runtime()` runners instead use `Effect.runForkWith` at the callback
+boundary. Those runners start synchronously and do not expose `startImmediately`.
+
 ---
 
 ## 9. Running Fibers at the Program Edge
@@ -647,27 +650,19 @@ const webhookProcessor = Effect.gen(function* () {
 
 To fail fast when any background task crashes, run the service's main loop against `FiberSet.join(tasks)` (it fails with the first non-interruption failure).
 
-### Bounded background task set (FiberSet + Semaphore)
+### Bounded work lists
 
-`FiberSet` never applies backpressure on its own. Bound admission by taking a semaphore permit before `run` and releasing it when the task fiber settles:
+`FiberSet` never applies backpressure on its own. For a work list, let
+`Effect.forEach` own both admission and cleanup. A manual `Semaphore.take`
+followed by `FiberSet.run` has an interruption gap, and a closed collection or a
+fiber interrupted before startup may never install the intended release handler.
 
 ```ts
 const boundedProcessor = Effect.gen(function* () {
-	const tasks = yield* FiberSet.make<void, WebhookError>();
-	const permits = yield* Semaphore.make(16); // at most 16 in flight
-
-	for (const event of events) {
-		yield* Semaphore.take(permits, 1); // waits while 16 tasks are in flight
-		yield* FiberSet.run(
-			tasks,
-			handleWebhook(event).pipe(
-				// runs on success, failure, AND interruption — permits never leak
-				Effect.ensuring(Semaphore.release(permits, 1))
-			)
-		);
-	}
-
-	yield* FiberSet.awaitEmpty(tasks);
+	yield* Effect.forEach(events, handleWebhook, {
+		concurrency: 16,
+		discard: true
+	});
 }).pipe(Effect.scoped);
 ```
 
@@ -723,7 +718,7 @@ const handoff = Effect.gen(function* () {
 9. **Expecting external interruption to fail `join`** — by default it doesn't. Pass `{ propagateInterruption: true }` to `run`/`set`/`add`; the collection's own internal interruptions (replacement, `clear`, scope close) never fail `join` either way.
 10. **Expecting `onlyIfMissing: true` to error when occupied** — it succeeds, returning a shared already-interrupted fiber while keeping the existing one. Check `Exit.hasInterrupts(yield* Fiber.await(fiber))` to detect the rejected start.
 11. **Calling `run` on a closed collection** — `FiberHandle.run`/`FiberMap.run` interrupt the *calling* fiber; `FiberSet.run` and all `runtime()` runners return a pre-interrupted fiber instead. Neither throws.
-12. **Assuming collection fibers are children of the caller** — they are root fibers created via `Effect.runForkWith` with the caller's context: they start immediately and survive the calling fiber; only the collection (scope close, replacement, remove/clear) interrupts them.
+12. **Assuming collection fibers are children of the caller** — they carry the caller's context but survive its completion; the collection owns their lifetime. `run` starts immediately by default and honors `startImmediately: false`; callback runtime runners start synchronously.
 13. **Relying on `Effect.runFork`/`runPromise` to keep Node alive** — a fiber suspended on `Deferred.await`/`Effect.never` won't hold the process open. Use `NodeRuntime.runMain` (built on `Runtime.makeRunMain`).
 14. **Letting interruption leak through acquire/release** — wrap the whole sequence in `Effect.uninterruptibleMask` and `restore` only the use phase; pending interruption is delivered as soon as the region ends, so cleanup still runs exactly once.
 15. **Leaving collection type parameters off** — `FiberHandle.make()` defaults to `<unknown, unknown>`, making `join` surface `unknown` errors. Always pass them: `FiberHandle.make<A, E>()`, `FiberMap.make<K, A, E>()`, `FiberSet.make<A, E>()`.

package/skills/effect-filesystem/SKILL.md

@@ -7,6 +7,8 @@ description: Use Effect FileSystem for platform-abstract file I/O with Node.js/B
 
 Use `effect` FileSystem for platform-abstract file I/O. Stock layers are provided for Node.js and Bun; `@effect/platform-browser` does not provide a FileSystem layer, so browser code needs a custom/injected implementation.
 
+Targets **Effect 4.0.0**. Match platform package versions to `effect`; verify APIs against the `effect@4.0.0` source tag rather than unreleased `main`.
+
 ## Basic Pattern
 
 ```typescript
@@ -195,6 +197,7 @@ const removeDir = Effect.gen(function* () {
 
 ### Open File Handle
 
+<!-- typecheck -->
 ```typescript
 import { FileSystem } from 'effect';
 import { Effect } from 'effect';
@@ -265,36 +268,38 @@ const createDir = Effect.gen(function* () {
 });
 ```
 
-### Make Temp Directory
+### Make Temp Directory with Explicit Ownership
 
+<!-- typecheck -->
 ```typescript
-import { FileSystem } from 'effect';
-import { Effect } from 'effect';
+import { Effect, FileSystem, Path } from 'effect';
 
 const useTempDir = Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
-	const tempPath = yield* fs.makeTempDirectory();
-
-	// Use tempPath
-	yield* fs.writeFileString(`${tempPath}/temp-file.txt`, 'data');
-
-	// Manual cleanup required
-	yield* fs.remove(tempPath, { recursive: true });
+	const path = yield* Path.Path;
+	return yield* Effect.acquireUseRelease(
+		fs.makeTempDirectory(),
+		(tempPath) => fs.writeFileString(path.join(tempPath, 'temp-file.txt'), 'data'),
+		(tempPath) => fs.remove(tempPath, { recursive: true }).pipe(Effect.orDie)
+	);
 });
 ```
 
+Release runs on success, failure, and interruption. Cleanup failure is surfaced as a defect here; prefer the built-in scoped variant for ordinary temporary work.
+
 ### Make Temp Directory (Scoped)
 
+<!-- typecheck -->
 ```typescript
-import { FileSystem } from 'effect';
-import { Effect } from 'effect';
+import { Effect, FileSystem, Path } from 'effect';
 
 const useScopedTempDir = Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
 	const tempPath = yield* fs.makeTempDirectoryScoped();
 
 	// Use tempPath within scope
-	yield* fs.writeFileString(`${tempPath}/temp-file.txt`, 'data');
+	yield* fs.writeFileString(path.join(tempPath, 'temp-file.txt'), 'data');
 
 	// Automatically cleaned up when scope exits
 }).pipe(Effect.scoped);
@@ -304,6 +309,7 @@ const useScopedTempDir = Effect.gen(function* () {
 
 ### Stat (File Info)
 
+<!-- typecheck -->
 ```typescript
 import { FileSystem } from 'effect';
 import { Effect, Console } from 'effect';
@@ -395,14 +401,15 @@ const changeOwner = Effect.gen(function* () {
 
 ### Update Times (utimes)
 
+<!-- typecheck -->
 ```typescript
-import { FileSystem } from 'effect';
-import { Effect } from 'effect';
+import { Clock, Effect, FileSystem } from 'effect';
 
 const updateTimes = Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
-	const now = new Date();
-	yield* fs.utimes('file.txt', now, now); // atime, mtime
+	const nowMillis = yield* Clock.currentTimeMillis;
+	// Numeric utimes inputs are epoch seconds, not milliseconds.
+	yield* fs.utimes('file.txt', nowMillis / 1000, nowMillis / 1000);
 });
 ```
 
@@ -436,6 +443,7 @@ const createSymlink = Effect.gen(function* () {
 
 ### Watch Files/Directories
 
+<!-- typecheck -->
 ```typescript
 import { FileSystem } from 'effect';
 import { Effect, Stream, Console, pipe } from 'effect';
@@ -466,28 +474,31 @@ Directory watching is non-recursive by default. Pass `{ recursive: true }` to in
 
 ## Size Helpers
 
+<!-- typecheck -->
 ```typescript
-import { FileSystem } from 'effect';
-import { Effect } from 'effect';
-
-const { Size, KiB, MiB, GiB, TiB, PiB } = FileSystem;
+import { ByteSize, Effect, FileSystem } from 'effect';
+import * as Schema from 'effect/Schema';
 
 // Create size values
-const oneKb = Size(1024);
-const tenKb = KiB(10);
-const oneMb = MiB(1);
-const fiveGb = GiB(5);
-const oneTb = TiB(1);
-const onePb = PiB(1);
+const oneKb = ByteSize.bytes(1024);
+const tenKb = ByteSize.kibibytes(10);
+const oneMb = ByteSize.mebibytes(1);
+const fiveGb = ByteSize.gibibytes(5);
+const oneTb = ByteSize.tebibytes(1);
+const onePb = ByteSize.pebibytes(1);
+
+class FileTooLarge extends Schema.TaggedError<FileTooLarge>()('FileTooLarge', {
+	path: Schema.String
+}) {}
 
 // Use with file operations
 const checkFileSize = Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const info = yield* fs.stat('large-file.bin');
 
-	const maxSize = MiB(100);
+	const maxSize = ByteSize.mebibytes(100);
 	if (info.size > maxSize) {
-		yield* Effect.fail(new Error('File too large'));
+		return yield* Effect.fail(new FileTooLarge({ path: 'large-file.bin' }));
 	}
 });
 ```
@@ -496,7 +507,7 @@ const checkFileSize = Effect.gen(function* () {
 
 ### SystemErrorTag Values
 
-FileSystem operations fail with `PlatformError` containing a `SystemErrorTag`:
+FileSystem operations fail with `PlatformError`. Its `reason` is `BadArgument` or `SystemError`. In **4.0.0**, `SystemError._tag` is the normalized category below; match `error.reason._tag` directly (there is no `reason.tag` field):
 
 - `AlreadyExists` - File/directory already exists
 - `BadResource` - Invalid file descriptor or handle
@@ -510,8 +521,11 @@ FileSystem operations fail with `PlatformError` containing a `SystemErrorTag`:
 - `WouldBlock` - Operation would block
 - `WriteZero` - Write operation wrote zero bytes
 
+For an unknown error at a boundary, `PlatformError.isPlatformError(value)` narrows it to the wrapper before inspecting `reason`.
+
 ### Error Handling Pattern
 
+<!-- typecheck -->
 ```typescript
 import { FileSystem } from 'effect';
 import { Effect, pipe } from 'effect';
@@ -525,11 +539,7 @@ const readConfigWithFallback = pipe(
 		if (error.reason._tag === 'NotFound') {
 			return Effect.succeed('{}');
 		}
-		if (error.reason._tag === 'PermissionDenied') {
-			return Effect.fail(
-				new Error('Cannot read config: permission denied')
-			);
-		}
+		// Permission and other failures remain visible to the caller.
 		return Effect.fail(error);
 	})
 );
@@ -537,6 +547,7 @@ const readConfigWithFallback = pipe(
 
 ### Typed Error Recovery
 
+<!-- typecheck -->
 ```typescript
 import { FileSystem } from 'effect';
 import { Effect, Schema, pipe } from 'effect';
@@ -548,50 +559,51 @@ class ConfigNotFound extends Schema.TaggedError<ConfigNotFound>()(
 	}
 ) {}
 
-class ConfigInvalid extends Schema.TaggedError<ConfigInvalid>()(
-	'ConfigInvalid',
+class ConfigReadFailed extends Schema.TaggedError<ConfigReadFailed>()(
+	'ConfigReadFailed',
 	{
 		path: Schema.String,
 		reason: Schema.String
 	}
 ) {}
 
-const readConfig = (path: string) =>
-	Effect.gen(function* () {
-		const fs = yield* FileSystem.FileSystem;
+const readConfig = Effect.fn('Config.read')(function* (path: string) {
+	const fs = yield* FileSystem.FileSystem;
 
-		const content = yield* pipe(
-			fs.readFileString(path),
-			Effect.mapError((error) =>
-				error.reason._tag === 'NotFound'
-					? new ConfigNotFound({ path })
-					: new ConfigInvalid({ path, reason: error.message })
-			)
-		);
+	const content = yield* pipe(
+		fs.readFileString(path),
+		Effect.mapError((error) =>
+			error.reason._tag === 'NotFound'
+				? new ConfigNotFound({ path })
+				: new ConfigReadFailed({ path, reason: error.message })
+		)
+	);
 
-		return content;
-	});
+	return content;
+});
 ```
 
 ## Scoped Resources Pattern
 
+<!-- typecheck -->
 ```typescript
-import { FileSystem } from 'effect';
-import { Effect } from 'effect';
+import { Effect, FileSystem, Path } from 'effect';
+import * as Str from 'effect/String';
 
 const processInTempDir = Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
 
 	// Create temp directory with automatic cleanup
 	const tempDir = yield* fs.makeTempDirectoryScoped();
 
 	// Do work in temp directory
-	const inputPath = `${tempDir}/input.txt`;
-	const outputPath = `${tempDir}/output.txt`;
+	const inputPath = path.join(tempDir, 'input.txt');
+	const outputPath = path.join(tempDir, 'output.txt');
 
 	yield* fs.writeFileString(inputPath, 'data');
 	const content = yield* fs.readFileString(inputPath);
-	yield* fs.writeFileString(outputPath, content.toUpperCase());
+	yield* fs.writeFileString(outputPath, Str.toUpperCase(content));
 
 	const result = yield* fs.readFileString(outputPath);
 
@@ -638,10 +650,10 @@ Effect.runPromise(runnable);
 
 - Import from `effect`
 - Use `yield* FileSystem.FileSystem` for service injection
-- Provide platform layer at entry point only
+- Provide platform layers at entry points or runtime-facing adapter `defaultLayer` exports
 - Use scoped temp directories with `makeTempDirectoryScoped`
 - Handle `PlatformError` with `catchTag("PlatformError", ...)`
-- Use size helpers: `Size()`, `KiB()`, `MiB()`, `GiB()`, `TiB()`, `PiB()`
+- Use `ByteSize.bytes`, `ByteSize.kibibytes`, `ByteSize.mebibytes`, and other ByteSize constructors; the old FileSystem size helpers are removed
 - Stream large files with `stream()` and `sink()`
 
 ## DON'T