opencode-effect-enforcer 0.2.8 → 0.3.0

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