opencode-effect-enforcer 0.2.3 → 0.2.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "opencode-effect-enforcer",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "OpenCode V2 plugin for Effect v4 skills, guidance, and pattern enforcement",
   "keywords": [
     "opencode",
@@ -29,6 +29,7 @@
     "skills",
     "guidance",
     "patterns",
+    "docs",
     "README.md",
     "LICENSE"
   ],
@@ -45,7 +46,7 @@
     "@ast-grep/napi": "^0.42.3",
     "@opencode-ai/plugin": "0.0.0-next-17148",
     "diff": "^9.0.0",
-    "effect": "4.0.0-rc.111",
+    "effect": "4.0.0-rc.112",
     "picomatch": "^4.0.3",
     "yaml": "^2.8.1"
   },

package/patterns/avoid-direct-tag-checks.md

@@ -21,7 +21,7 @@ suggestSkills:
 ```haskell
 -- Transformation
 directCheck :: Event → Bool
-directCheck e = e._tag == "FactRecorded"   -- fragile, poor narrowing
+directCheck e = e._tag == "FactRecorded"   -- narrows, but not exhaustive
 
 -- Instead
 $is   :: Tag → Event → Bool                -- from TaggedEnum
@@ -51,4 +51,10 @@ isFactRecorded = $is "FactRecorded"
 -- Refactoring-safe: rename tag in one place
 ```
 
-Direct `_tag` checks don't narrow types correctly. Use `$is` for predicates or `$match` for exhaustive pattern matching via `Data.taggedEnum`.
+TypeScript correctly narrows literal `_tag` checks. Prefer exported guards and
+matching helpers for consistent semantics and exhaustiveness as variants evolve.
+For schema-first models use union `.guards`, `.match`, or `Schema.is`; class
+variants can also use `instanceof`. `Schema.toTaggedUnion` supports discriminator
+keys beyond `_tag`. In rc.112, `.matchOrElse` adds partial matching with a typed
+fallback. For trusted `Data.taggedEnum` values use `$is` / `$match`; `$is` checks
+only the tag and is not structural validation of unknown input.

package/patterns/avoid-react-hooks.md

@@ -3,7 +3,7 @@ action: context
 tool: (edit|write)
 event: after
 name: avoid-react-hooks
-description: React hooks (useState, useEffect, useReducer, etc.) should be avoided - use View Models with Effect Atom instead
+description: Review React hooks (useState, useEffect, useReducer, etc.) for state and effects better expressed with Effect Atom
 glob: '**/*.{ts,tsx}'
 detector: ast
 pattern:
@@ -29,45 +29,26 @@ pattern:
     - 'useInsertionEffect($$$)'
 level: high
 suggestSkills:
-    - effect-react-vm
+    - effect-atom-state
 ---
 
-# Avoid React Hooks - Use View Models
+# Review React Hooks - Prefer Effect Atom for Shared State
 
-```haskell
--- Transformation
-useState     :: a → (a, a → ())          -- scattered state, untestable
-useEffect    :: (() → ()) → [a] → ()     -- cleanup error-prone
+Keep shared state in atoms and application effects in typed Effect services.
+Components subscribe with `useAtomValue` and trigger actions with `useAtomSet`
+or `useAtom`. Organize atoms in ordinary state modules alongside the feature.
 
--- Instead: View Model pattern
-data VM = VM
-  { state$  :: Atom State               -- reactive state
-  , action  :: () → Effect ()           -- effectful actions
-  }
+| Hook usage | Effect Atom alternative |
+| --- | --- |
+| `useState` / `useReducer` for shared state | Writable `Atom.make` values |
+| `useMemo` for shared derived state | `Atom.map` or a derived `Atom.make` |
+| `useEffect` to fetch data | `Atom.runtime(layer).atom(effect)` |
+| Async action callbacks with manual loading state | `Atom.fn` or runtime actions with `AsyncResult` |
+| External subscriptions owned by an atom | `Atom.make` with `get.addFinalizer` |
+| URL search state | `Atom.searchParam` |
 
--- Component is pure renderer
-component :: VM → JSX
-component vm = useAtomValue (state$ vm)  -- only reads atoms
-```
+The detector is advisory: hooks for DOM refs, layout, React scheduling, stable
+IDs, or local component behavior may be appropriate. Review the hook's role
+before replacing it; atoms are not substitutes for React-specific lifecycle APIs.
 
-```haskell
--- Replacements
-useState      → vmAtom :: Atom a
-useEffect     → vmAction :: Effect ()
-useCallback   → derivedAtom :: Atom (a → b)
-useMemo       → derivedAtom :: Atom a
-useRef (DOM)  → pass from parent ∨ VM trigger
-useSearchParams → Atom.searchParam
-useEffect (cleanup) → Atom.make with get.addFinalizer
-
--- Architecture
-data Component = Component
-  { view :: VM → JSX           -- pure renderer
-  , vm   :: Layer VM           -- testable, injectable
-  }
-
--- Invoke skill for implementation
-invoke "react-vm"
-```
-
-React hooks scatter state across components. Use View Models: state in atoms, effects in actions, components as pure renderers.
+Load `effect-atom-state` for implementation guidance.

package/patterns/effect-run-in-body.md

@@ -44,7 +44,7 @@ good = do
 
 -- Entry points only
 main :: IO ()
-main = Effect.runMain program              -- ✓ application boundary
+main = BunRuntime.runMain program          -- ✓ application boundary (@effect/platform-bun)
 
 handler :: Request → IO Response
 handler req = Effect.runPromise (handle req)  -- ✓ API boundary

package/patterns/require-effect-concurrency.md

@@ -55,8 +55,14 @@ constraints:
                 - kind: object
                 - has:
                       regex: '\bconcurrency\b'
+                - not:
+                      has:
+                          all:
+                              - kind: pair
+                              - regex: '^\s*["\x27]?concurrency["\x27]?\s*:\s*["\x27]inherit["\x27]\s*$'
 level: warning
 suggestSkills:
+    - effect-parallelization
     - effect-concurrency-testing
 ---
 
@@ -73,6 +79,7 @@ Effect.forEach xs f opts      -- concurrency intent explicit
 Effect.forEach(items, processItem);
 Effect.all(tasks);
 Effect.validate(inputs, validateInput, { discard: true });
+Effect.all(tasks, { concurrency: 'inherit' }); // removed in beta.102
 
 // Good
 Effect.forEach(items, processItem, { concurrency: 1 });
@@ -81,3 +88,7 @@ Effect.validate(inputs, validateInput, { concurrency: 4, discard: true });
 ```
 
 Even sequential execution is a concurrency decision. Specify `concurrency` on `Effect.forEach`, `Effect.all`, and `Effect.validate` so throughput and ordering intent are reviewable at the call site.
+
+Current v4 accepts a number or `'unbounded'` (`Types.Concurrency`), not `'inherit'`.
+The detector also flags that removed literal in an explicit options object;
+TypeScript remains authoritative for computed or indirect option values.

package/patterns/use-console-service.md

@@ -47,8 +47,13 @@ structured = do
 test :: Effect () TestConsole
 test = do
   program
-  logs ← TestConsole.output
+  logs ← TestConsole.logLines
   assert (logs `contains` "expected message")
 ```
 
 `console.*` in Effect code breaks the paradigm. Use `Console` service or `Effect.log*` for structured, testable logging.
+
+`TestConsole.logLines` captures `Console.log` with `TestConsole.layer` provided;
+`errorLines` captures `Console.error`. Structured `Effect.log*` records should be
+asserted through a test logger (`Logger.make` / `Logger.layer`), rather than
+assuming every logger writes to the test console.

package/skills/effect-ai-language-model/SKILL.md

@@ -226,12 +226,12 @@ Streaming text, reasoning, and tool parameters use matching `id` values across s
 const collectText = streamText.pipe(
 	Stream.filter((part) => part.type === 'text-delta'),
 	Stream.map((part) => part.delta),
-	Stream.runFold('', (acc, delta) => acc + delta)
+	Stream.runFold(() => '', (acc, delta) => acc + delta)
 );
 
 // Process chunks efficiently
 const processChunks = streamText.pipe(
-	Stream.mapChunksEffect((chunk) =>
+	Stream.mapArrayEffect((chunk) =>
 		Effect.gen(function* () {
 			const parts = Array.from(chunk);
 			// Process batch of parts
@@ -241,20 +241,14 @@ const processChunks = streamText.pipe(
 	)
 );
 
-// Aggregate response with side effects
-let combined: Array<StreamPart> = [];
-const aggregated = streamText.pipe(
-	Stream.mapChunks((chunk) => {
-		combined = [...combined, ...chunk];
-		return chunk;
-	}),
-	Stream.ensuring(
-		Effect.sync(() => {
-			// Finalization logic with full response
-			console.log('Total parts:', combined.length);
-		})
-	)
-);
+// Allocate per stream run; keep side effects in tap/mapArrayEffect.
+const aggregated = Stream.suspend(() => {
+	let count = 0;
+	return streamText.pipe(
+		Stream.tap(() => Effect.sync(() => { count += 1; })),
+		Stream.ensuring(Effect.suspend(() => Effect.logDebug('Total parts:', count)))
+	);
+});
 ```
 
 ## toolChoice Options

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

@@ -431,7 +431,7 @@ import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
 const chat = Effect.gen(function* () {
 	const history = yield* SubscriptionRef.make(Prompt.empty);
 
-	function* generateText(userInput: string) {
+	const generateText = Effect.fn('Chat.generateText')(function* (userInput: string) {
 		const currentHistory = yield* SubscriptionRef.get(history);
 		const prompt = pipe(currentHistory, Prompt.concat(userInput));
 
@@ -445,7 +445,7 @@ const chat = Effect.gen(function* () {
 		yield* SubscriptionRef.set(history, newHistory);
 
 		return response;
-	}
+	});
 
 	return { generateText };
 });
@@ -516,6 +516,40 @@ const program = Effect.gen(function* () {
 
 ## Provider-Specific Options
 
+### OpenAI Responses explicit cache breakpoints (rc.112)
+
+With `@effect/ai-openai` loaded, system-message and text-part options accept
+`openai.promptCacheBreakpoint`. This requires GPT-5.6 or later; earlier models
+may reject it. Provider config uses snake_case; Prompt metadata uses camelCase.
+
+```typescript
+import { OpenAiLanguageModel } from '@effect/ai-openai';
+import { Effect } from 'effect';
+import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as Prompt from 'effect/unstable/ai/Prompt';
+
+const program = LanguageModel.generateText({
+	prompt: Prompt.make([
+		Prompt.systemMessage({
+			content: 'Stable instructions',
+			options: { openai: { promptCacheBreakpoint: { mode: 'explicit' } } }
+		}),
+		Prompt.userMessage({
+			content: [Prompt.textPart({ text: 'Question for this turn' })]
+		})
+	])
+}).pipe(Effect.provide(OpenAiLanguageModel.model('gpt-5.6', {
+	prompt_cache_key: 'assistant:v1',
+	prompt_cache_options: { mode: 'explicit', ttl: '30m' }
+})));
+```
+
+A text part can carry the same breakpoint after reusable user context. The
+adapter forwards it as `prompt_cache_breakpoint` on input text. Supply the
+OpenAI client layer at the runtime boundary (see `effect-ai-provider`).
+
+### Other provider metadata
+
 ```typescript
 // Augment options interfaces via module augmentation
 declare module 'effect/unstable/ai/Prompt' {

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

@@ -420,6 +420,19 @@ export class AiWriter extends Context.Service<
 
 ## Custom Error Wrapping
 
+In rc.112, `AiError.AuthenticationError` accepts an optional `description` and
+appends it after the kind-based remediation message. Anthropic, OpenAI,
+OpenAI-compatible, and OpenRouter adapters propagate provider error text from
+401/403 responses. Preserve this reason rather than replacing it with a generic
+authentication string. `AiError.buildErrorDescription` is available to adapter
+authors; inspect its signature before building custom provider mappings.
+Authentication failures generally require corrected credentials/permissions,
+not a blanket transient retry. Keep redacted credentials out of logs.
+
+OpenAI Responses additionally supports GPT-5.6+ explicit prompt cache breakpoints
+through `Prompt` metadata and `prompt_cache_options` model config; see
+`effect-ai-prompt` for the complete construction example.
+
 Wrap `AiError` into domain-specific tagged errors:
 
 ```typescript

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

@@ -81,34 +81,27 @@ Accumulate stream parts incrementally using mutable state for efficiency:
 import * as Stream from 'effect/Stream';
 import * as Effect from 'effect/Effect';
 import * as Prompt from 'effect/unstable/ai/Prompt';
+import * as Response from 'effect/unstable/ai/Response';
+import * as SubscriptionRef from 'effect/SubscriptionRef';
 
-const accumulated: Array<StreamPart> = [];
-let combined = Prompt.empty;
-
-stream.pipe(
-	Stream.mapChunksEffect(
-		Effect.fnUntraced(function* (chunk) {
-			const parts = Array.from(chunk);
-
-			// Append to mutable accumulator
-			accumulated.push(...parts);
-
-			// Fold the accumulated response so start/delta/end IDs are visible together
-			combined = Prompt.fromResponseParts(accumulated);
-
-			// Update history incrementally
-			yield* SubscriptionRef.set(
-				history,
-				Prompt.concat(checkpoint, combined)
-			);
-
-			return chunk;
-		})
-	)
-);
+const streamWithHistory = Stream.suspend(() => {
+	const accumulated: Array<Response.AnyPart> = [];
+	return stream.pipe(
+		Stream.mapArrayEffect(
+			Effect.fnUntraced(function* (parts) {
+				accumulated.push(...parts);
+
+				// Fold accumulated parts so start/delta/end IDs are visible together.
+				const combined = Prompt.fromResponseParts(accumulated);
+				yield* SubscriptionRef.set(history, Prompt.concat(checkpoint, combined));
+				return parts;
+			})
+		)
+	);
+});
 ```
 
-Key insight: `Stream.mapChunksEffect` enables side-effectful accumulation while preserving stream semantics.
+Key insight: `Stream.mapArrayEffect` enables side-effectful accumulation while preserving stream semantics. Its input/output batches are non-empty arrays, not v3 Chunks. Allocate mutable accumulators inside `Stream.suspend` so separate stream runs do not share history.
 
 ## Resource-Safe Streaming
 
@@ -121,19 +114,23 @@ import * as Stream from 'effect/Stream';
 
 const streamWithProtection = Stream.fromChannel(
 	Channel.acquireUseRelease(
-		// Acquire: Take semaphore, get checkpoint
-		semaphore.take(1).pipe(
-			Effect.zipRight(SubscriptionRef.get(history)),
-			Effect.map((hist) => Prompt.concat(hist, newPrompt)),
-			Effect.tap((checkpoint) => SubscriptionRef.set(history, checkpoint))
-		),
-
-		// Use: Stream with accumulation
-		(checkpoint) =>
-			LanguageModel.streamText({ prompt: checkpoint }).pipe(
-				Stream.mapChunksEffect(accumulateAndUpdate),
-				Stream.toChannel
-			),
+		// Acquire only the permit so release covers checkpoint setup too.
+		semaphore.take(1),
+
+		// Use: Prepare history, then stream with per-run accumulation.
+		() => Stream.unwrap(Effect.gen(function* () {
+			const checkpoint = Prompt.concat(yield* SubscriptionRef.get(history), newPrompt);
+			yield* SubscriptionRef.set(history, checkpoint);
+			const accumulated: Array<Response.AnyPart> = [];
+			return LanguageModel.streamText({ prompt: checkpoint }).pipe(
+				Stream.mapArrayEffect(Effect.fnUntraced(function* (parts) {
+					accumulated.push(...parts);
+					yield* SubscriptionRef.set(history,
+						Prompt.concat(checkpoint, Prompt.fromResponseParts(accumulated)));
+					return parts;
+				}))
+			);
+		})).pipe(Stream.toChannel),
 
 		// Release: Always release semaphore
 		() => semaphore.release(1)
@@ -150,6 +147,9 @@ Resource acquisition order:
 5. Stream response (with incremental updates)
 6. Release semaphore (guaranteed via `acquireUseRelease`)
 
+Keep steps 2–5 in the use phase. If checkpoint setup fails after acquisition,
+the finalizer must already own the permit.
+
 ## Consumption Patterns
 
 runForEach :: (A → Effect<R, E>) → Stream<A, E, R> → Effect<Unit, E, R>
@@ -173,7 +173,7 @@ stream.pipe(Stream.tap(logPart), Stream.runDrain);
 
 // Get final accumulated value
 stream.pipe(
-	Stream.runFold(initialState, (acc, part) => merge(acc, part)),
+	Stream.runFold(() => initialState, (acc, part) => merge(acc, part)),
 	Effect.map(Option.some)
 );
 ```
@@ -183,28 +183,21 @@ stream.pipe(
 Incremental merge strategy for conversation history:
 
 ```typescript
-Prompt.concat :: Prompt → Prompt → Prompt
-Prompt.fromResponseParts :: Array<StreamPart> → Prompt
-
-// Pattern: checkpoint + accumulated response fold
-const accumulated: Array<StreamPart> = []
-let combined = Prompt.empty
-
-Stream.mapChunksEffect(function* (chunk) {
-  const parts = Array.from(chunk)
-  accumulated.push(...parts)
-
-  // Fold accumulated parts, not only this chunk, so start/delta/end IDs align
-  combined = Prompt.fromResponseParts(accumulated)
-
-  // Update history: base checkpoint + accumulated response
-  yield* SubscriptionRef.set(
-    history,
-    Prompt.concat(filteredCheckpoint, combined)
-  )
-
-  return chunk
-})
+// Prompt.concat: (Prompt, RawInput) → Prompt
+// Prompt.fromResponseParts: ReadonlyArray<Response.AnyPart> → Prompt
+
+// Pattern: checkpoint + accumulated response fold, scoped to each stream run.
+const streamWithHistory = Stream.suspend(() => {
+  const accumulated: Array<Response.AnyPart> = [];
+  return stream.pipe(Stream.mapArrayEffect(Effect.fnUntraced(function* (parts) {
+    accumulated.push(...parts);
+
+    // Fold accumulated parts, not only this batch, so start/delta/end IDs align.
+    const combined = Prompt.fromResponseParts(accumulated);
+    yield* SubscriptionRef.set(history, Prompt.concat(filteredCheckpoint, combined));
+    return parts;
+  })));
+});
 ```
 
 Why checkpoint-based merging:
@@ -224,11 +217,13 @@ Why checkpoint-based merging:
 
 ## Complete Example
 
+<!-- typecheck -->
 ```typescript
 import * as Prompt from 'effect/unstable/ai/Prompt';
 import * as Response from 'effect/unstable/ai/Response';
 import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
 import * as Stream from 'effect/Stream';
+import * as Channel from 'effect/Channel';
 import * as Effect from 'effect/Effect';
 import * as SubscriptionRef from 'effect/SubscriptionRef';
 import * as Semaphore from 'effect/Semaphore';
@@ -241,46 +236,21 @@ const Chat = Effect.gen(function* () {
 	const streamText = (prompt: string) =>
 		Stream.fromChannel(
 			Channel.acquireUseRelease(
-				// Acquire
-				semaphore.take(1).pipe(
-					Effect.zipRight(SubscriptionRef.get(history)),
-					Effect.map((hist) =>
-						Prompt.concat(hist, Prompt.make(prompt))
-					),
-					Effect.tap((checkpoint) => {
-						combined = Prompt.empty;
-						return SubscriptionRef.set(history, checkpoint);
-					})
-				),
-
-				// Use
-				(checkpoint) => {
-					let combined = Prompt.empty;
-					const accumulated: Array<Response.StreamPart> = [];
-
-					return LanguageModel.streamText({
-						prompt: checkpoint
-					}).pipe(
-						Stream.mapChunksEffect(
-							Effect.fnUntraced(function* (chunk) {
-								const parts = Array.from(chunk);
-								accumulated.push(...parts);
-
-								combined = Prompt.fromResponseParts(accumulated);
-
-								yield* SubscriptionRef.set(
-									history,
-									Prompt.concat(checkpoint, combined)
-								);
-
-								return chunk;
-							})
-						),
-						Stream.toChannel
+				// Acquire only the permit; all following work is covered by release.
+				semaphore.take(1),
+				() => Stream.unwrap(Effect.gen(function* () {
+					const checkpoint = Prompt.concat(yield* SubscriptionRef.get(history), prompt);
+					yield* SubscriptionRef.set(history, checkpoint);
+					const accumulated: Array<Response.AnyPart> = [];
+					return LanguageModel.streamText({ prompt: checkpoint }).pipe(
+						Stream.mapArrayEffect(Effect.fnUntraced(function* (parts) {
+							accumulated.push(...parts);
+							yield* SubscriptionRef.set(history,
+								Prompt.concat(checkpoint, Prompt.fromResponseParts(accumulated)));
+							return parts;
+						}))
 					);
-				},
-
-				// Release
+				})).pipe(Stream.toChannel),
 				() => semaphore.release(1)
 			)
 		);
@@ -288,20 +258,23 @@ const Chat = Effect.gen(function* () {
 	return { streamText };
 });
 
-// Consume stream
-chat.streamText('Hello').pipe(
+// Consume with a LanguageModel layer provided by the application.
+const consume = Effect.gen(function* () {
+	const chat = yield* Chat;
+	yield* chat.streamText('Hello').pipe(
 	Stream.runForEach((part) =>
 		Match.value(part).pipe(
 			Match.when({ type: 'text-delta' }, ({ delta }) =>
-				Effect.sync(() => console.log(delta))
+				Effect.logInfo(delta)
 			),
 			Match.when({ type: 'finish' }, ({ usage }) =>
-				Effect.sync(() => console.log(usage))
+				Effect.logDebug(usage)
 			),
 			Match.orElse(() => Effect.void)
 		)
 	)
-);
+	);
+});
 ```
 
 ## Anti-Patterns
@@ -335,8 +308,8 @@ Stream.map((chunk) => {
   return chunk
 })
 
-// ✓ Use Stream.mapChunksEffect
-Stream.mapChunksEffect(Effect.fnUntraced(function* (chunk) {
+// ✓ Use Stream.mapArrayEffect
+Stream.mapArrayEffect(Effect.fnUntraced(function* (chunk) {
   accumulated.push(...chunk)
   yield* updateHistory()
   return chunk
@@ -382,7 +355,7 @@ Set `preventFallbackOnPartialStream: true` when a provider failure after emitted
 
 - [ ] Use start/delta/end protocol for streaming content
 - [ ] Match stream parts with `Match.when({ type: ... })` or direct `part.type` checks (NOT `Match.tag` — parts use `type`, not `_tag`)
-- [ ] Accumulate using Stream.mapChunksEffect (not Stream.map)
+- [ ] Accumulate using Stream.mapArrayEffect (not a side-effecting Stream.map)
 - [ ] Use SubscriptionRef for reactive history updates
 - [ ] Protect concurrent streams with Semaphore
 - [ ] Use Channel.acquireUseRelease for resource safety