opencode-effect-enforcer 0.2.8 → 0.3.0

package/patterns/use-command-executor-service.md

@@ -35,7 +35,7 @@ ChildProcessSpawner :: Effect a ChildProcessSpawner  -- typed I/O, scoped lifeti
 ```
 
 ```haskell
--- Pattern (Effect v4 — effect/unstable/process)
+-- Pattern (Effect v4 — effect/process)
 bad :: () → IO String
 bad = exec "git" ["status"] (cb)              -- callback, untyped, no cancellation
 
@@ -46,7 +46,7 @@ good = do
   -- typed output, error channel, scoped lifetime
 ```
 
-Direct `child_process` imports give you callback APIs, manual lifecycle, and no error channel. Use `ChildProcessSpawner` and `ChildProcess` from `effect/unstable/process` for typed errors, scoped resource lifetime, and platform-agnostic process spawning.
+Direct `child_process` imports give you callback APIs, manual lifecycle, and no error channel. Use `ChildProcessSpawner` and `ChildProcess` from `effect/process` for typed errors, scoped resource lifetime, and platform-agnostic process spawning.
 
 **Exceptions:**
 

package/patterns/use-http-client-service.md

@@ -49,26 +49,28 @@ good url = pipe
 
 ```haskell
 -- Composable request building
-request :: Effect HttpClientRequest HttpBodyError
+request :: HttpClientRequest
 request = pipe
-  (HttpClientRequest.post "/api/users")
-  (HttpClientRequest.bodyJson { name: "Alice" })
+  (HttpClientRequest.get "https://api.example.com/users")
+  (HttpClientRequest.setHeader "accept" "application/json")
 
 -- With retry, timeout, tracing
 resilient :: Effect Response (HttpClient | HttpBodyError)
 resilient = pipe
-  request
-  (Effect.flatMap HttpClient.execute)
+  (HttpClient.execute request)
   (Effect.retry (Schedule.recurs 3))
   (Effect.timeout (Duration.seconds 10))
 
 -- Provide platform layer at entry point
 main = program
-  & provide BunHttpClient.layer    -- or NodeHttpClient.layer
+  & provide BunHttpClient.layer    -- or NodeHttpClient.layerUndici
 ```
 
 Direct `http` / `https` imports give you callback APIs, manual TLS plumbing, and no error channel. Use Effect's `HttpClient`, `HttpClientRequest`, and `HttpClientResponse` for typed errors, composable request building, declarative retry/timeout, and testability via layer substitution.
 
+Import these modules from `effect/http`. The retry example assumes an idempotent
+GET; only retry mutations when their idempotency is established by the contract.
+
 **Exceptions:**
 
 - Platform-specific layers that implement `HttpClient.HttpClient`

package/patterns/use-random-service.md

@@ -34,12 +34,11 @@ bad = floor (Math.random * 100)     -- R = ∅, untestable
 good :: Effect Int Random
 good = Random.nextIntBetween 0 100  -- R ⊃ Random, deterministic in tests
 
--- In tests
-test :: Effect () TestRandom
-test = do
-  TestRandom.feedInts [42, 7, 13]   -- deterministic sequence
-  result ← good
-  assert (result == 42)
+-- Repeatable sequence in tests
+seeded = good & Random.withSeed "example-seed"
 ```
 
-`Math.random()` is non-deterministic. Use `Random` service for reproducible randomness via `TestRandom.feed*` in tests.
+`Math.random()` bypasses Effect's random service. Use `Random.withSeed` for
+repeatable sequences in tests, or provide a controlled `Random.Random` service
+when the exact generated values matter. `Random.nextIntBetween(min, max)` includes
+both endpoints by default; pass `{ halfOpen: true }` to exclude the upper bound.

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

@@ -8,14 +8,17 @@ You are an Effect TypeScript expert specializing in the `Chat` module for statef
 ## 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>` in that checkout for this skill's baseline;
+main may be ahead. Keep `effect` and `@effect/*` packages on the same version.
+The `effect/ai` APIs are tagged `@stability unstable`: minor releases may break
+them even though the import path no longer contains `unstable`.
 
 Reference this for:
 
-- Chat module source: `packages/effect/src/unstable/ai/Chat.ts`
+- Chat module source: `packages/effect/src/ai/Chat.ts`
 - Chat usage examples: `ai-docs/src/71_ai/30_chat.ts`
 - Tool integration examples: `ai-docs/src/71_ai/20_tools.ts`
-- Prompt construction: `packages/effect/src/unstable/ai/Prompt.ts`
+- Prompt construction: `packages/effect/src/ai/Prompt.ts`
 
 ## Core Imports
 
@@ -28,7 +31,7 @@ import {
 	Tool,
 	Toolkit,
 	AiError
-} from 'effect/unstable/ai';
+} from 'effect/ai';
 ```
 
 ## What Chat Provides
@@ -122,7 +125,10 @@ yield* session.generateText({ prompt: [] });
 
 ## Streaming Text
 
-`streamText` returns a `Stream` of `Response.StreamPart` values. History is updated when the stream finalizes. Consume the stream to completion if the full assistant response should become history; if the stream is interrupted early, only the parts emitted before finalization are recorded.
+`streamText` returns a `Stream` of `Response.StreamPart` values. History is updated
+when the stream finalizes by folding the parts received so far. Consume to
+completion to preserve the full response: interrupted text/reasoning sequences
+without an end marker are not folded into history.
 
 ```ts
 yield*
@@ -215,7 +221,7 @@ const restored = yield* Chat.fromExport(data);
 For automatic persistence (save after every generation), use `Chat.Persistence`:
 
 ```ts
-import { Persistence } from 'effect/unstable/persistence';
+import { Persistence } from 'effect/persistence';
 
 // Create a persistence layer and provide a BackingPersistence implementation
 const PersistenceLayer = Chat.layerPersisted({ storeId: 'my-chats' }).pipe(
@@ -459,7 +465,7 @@ Each `Chat` instance uses an internal semaphore with 1 permit, ensuring that onl
 
 1. **Always provide `LanguageModel.LanguageModel`** — `generateText`, `streamText`, and `generateObject` all require it in context. Provide via `Effect.provide(modelLayer)`.
 2. **Use `prompt: []` in agentic loops** — After the initial prompt, pass an empty prompt to let the model respond based on accumulated history including tool results.
-3. **Import from `effect/unstable/ai`** — Chat, Prompt, Tool, Toolkit, LanguageModel, and AiError all come from this path.
+3. **Import from `effect/ai`** — Chat, Prompt, Tool, Toolkit, LanguageModel, and AiError all come from this path.
 4. **One session = one conversation** — Create separate `Chat` instances for independent conversations. Don't share a session across unrelated threads.
 5. **Export before shutdown** — Use `exportJson` to persist state. Restore with `Chat.fromJson`.
 6. **Provide toolkit handlers** — When using tools, the toolkit's handler layer must be provided (e.g., `Layer.provide(ToolsLayer)`).

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

@@ -7,16 +7,20 @@ description: Master the Effect AI LanguageModel service for text generation, str
 
 Pattern guide for working with the LanguageModel service from Effect AI for type-safe LLM interactions with Effect's functional patterns.
 
+Baseline: `effect@4.0.0`. Inspect that tag in the Effect source reference, not
+unreleased main. Keep Effect-family packages on the same version. `effect/ai`
+APIs carry `@stability unstable` and may change incompatibly in minor releases.
+
 ## Import Patterns
 
 **CRITICAL**: Always use namespace imports:
 
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
-import * as Prompt from 'effect/unstable/ai/Prompt';
-import * as Response from 'effect/unstable/ai/Response';
-import * as Toolkit from 'effect/unstable/ai/Toolkit';
-import * as Tool from 'effect/unstable/ai/Tool';
+import * as LanguageModel from 'effect/ai/LanguageModel';
+import * as Prompt from 'effect/ai/Prompt';
+import * as Response from 'effect/ai/Response';
+import * as Toolkit from 'effect/ai/Toolkit';
+import * as Tool from 'effect/ai/Tool';
 import * as Effect from 'effect/Effect';
 import * as Stream from 'effect/Stream';
 import * as Schema from 'effect/Schema';
@@ -56,7 +60,7 @@ LanguageModel ∈ R → Effect.gen(function*() {
 Basic text generation with optional tool calling:
 
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 import * as Effect from 'effect/Effect';
 
 // Simple text generation
@@ -104,6 +108,12 @@ For `Schema.NumberFromString`, manual calls contain `{ count: '3' }`.
 
 Pass those encoded params directly to `toolkit.handle(name, params, toolCallId)` when resolving manually. `Toolkit.handle` now accepts `Tool.ParametersEncoded<T>` and performs the decode before the handler receives `Tool.Parameters<T>`.
 
+Provide `Tool.HandlerServices<T>` to both the outer `handle` Effect and the
+returned Stream; parameter decoding can need services before streaming starts.
+The outer Effect can fail with `AiError`, and the Stream can fail with
+`Tool.HandlerError<T> | AiError`, including in `failureMode: 'return'` when
+result encoding fails.
+
 ### Response Accessors
 
 ```typescript
@@ -129,7 +139,7 @@ When converting `response.content` back into history, `Prompt.fromResponseParts`
 Force schema-validated output from the model:
 
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 import * as Schema from 'effect/Schema';
 import * as Effect from 'effect/Effect';
 
@@ -178,8 +188,9 @@ const extractEvent = LanguageModel.generateObject({
 
 Real-time streaming text generation:
 
+<!-- typecheck -->
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 import * as Stream from 'effect/Stream';
 import * as Effect from 'effect/Effect';
 import * as Console from 'effect/Console';
@@ -196,7 +207,7 @@ const program = streamStory.pipe(
 			return Console.log(part.delta);
 		}
 		if (part.type === 'tool-params-delta') {
-			return Console.log('Tool params:', part.paramsDelta);
+			return Console.log('Tool params:', part.delta);
 		}
 		return Effect.void;
 	})
@@ -214,7 +225,7 @@ Common StreamPart shapes include (non-exhaustive):
   | { type: "reasoning-delta", id, delta }
   | { type: "reasoning-end", id }
   | { type: "tool-params-start", id, name }
-  | { type: "tool-params-delta", id, paramsDelta }
+  | { type: "tool-params-delta", id, delta }
   | { type: "tool-params-end", id }
   | { type: "tool-call", id, name, params }
   | { type: "tool-result", id, name, result, isFailure, preliminary? }
@@ -289,7 +300,7 @@ toolChoice: {
 ## Error Handling
 
 ```typescript
-import * as AiError from 'effect/unstable/ai/AiError';
+import * as AiError from 'effect/ai/AiError';
 
 const robust = LanguageModel.generateText({
 	prompt: 'Analyze this...'
@@ -311,10 +322,22 @@ remain explicit and provider/validation failures use `AiError`. Classification
 requires at least two labels, rating requires at least two distinct ordered
 levels, and a definition requires at least one decision.
 
+`Decision.probability({ instructions })` estimates the probability of `true`.
+Its `criteria` is optional; when supplied it must describe both `false` and
+`true`. Guard `decision.criteria` before reading outcome descriptions.
+
+Custom adapters can set `DecisionModel.make({ decide, probabilityPrecision })`
+to accept rounding drift in classification/rating distributions. At precision
+`p`, the allowed sum drift is half a unit of the last decimal place per label
+(plus the core numerical tolerance); accepted drift is rescaled to sum to one.
+Zero sums, invalid probabilities, and larger drift still fail with
+`InvalidOutputError`. Omit the option for strict sum validation. OpenRouter and
+TypeSafe adapters use precision `2`.
+
 <!-- typecheck -->
 ```ts
 import * as Schema from 'effect/Schema';
-import { Decision, DecisionModel } from 'effect/unstable/ai';
+import { Decision, DecisionModel } from 'effect/ai';
 
 class Ticket extends Schema.Class<Ticket>('Ticket')({ body: Schema.String }) {}
 const triage = Decision.make({
@@ -323,7 +346,8 @@ const triage = Decision.make({
 		team: Decision.classify({
 			instructions: 'Choose the team responsible for this request',
 			criteria: { billing: 'Payments and invoices', support: 'Product support' }
-		})
+		}),
+		urgent: Decision.probability({ instructions: 'The ticket needs immediate attention' })
 	}
 });
 const result = DecisionModel.decide(triage, { input: new Ticket({ body: 'Invoice question' }) });
@@ -332,7 +356,7 @@ const result = DecisionModel.decide(triage, { input: new Ticket({ body: 'Invoice
 ## Type Extraction Utilities
 
 ```typescript
-import type * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import type * as LanguageModel from 'effect/ai/LanguageModel';
 
 // Extract error types from options
 type MyError = LanguageModel.ExtractError<typeof options>;
@@ -360,9 +384,14 @@ make :: ConstructorParams → Effect Service
 
 When implementing a custom LanguageModel provider, return encoded parts: `Array<Response.PartEncoded>` for `generateText` and `Stream<Response.StreamPartEncoded>` for `streamText`. If you emit `response-metadata`, encode timestamps as ISO strings. Providers that support provider-side conversations should honor `ProviderOptions.previousResponseId` and `ProviderOptions.incrementalPrompt`; providers that cannot should intentionally ignore them.
 
+`ProviderOptions.incrementalFallback` is `true` when the core retries a rejected
+incremental request with the full prompt. The fallback clears
+`previousResponseId` and `incrementalPrompt`; use that signal to reset adapter
+turn state without unnecessarily closing a healthy connection.
+
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
-import * as Response from 'effect/unstable/ai/Response';
+import * as LanguageModel from 'effect/ai/LanguageModel';
+import * as Response from 'effect/ai/Response';
 
 const makeCustomProvider = Effect.gen(function* () {
 	const service = yield* LanguageModel.make({
@@ -655,7 +684,7 @@ const generated = LanguageModel.generateText({ prompt: '...' }).pipe(
 Inside an effect that runs with a language model provider, you can retrieve the current provider name:
 
 ```typescript
-import * as Model from 'effect/unstable/ai/Model';
+import * as Model from 'effect/ai/Model';
 
 const program = Effect.gen(function* () {
 	const providerName = yield* Model.ProviderName;
@@ -672,7 +701,7 @@ const program = Effect.gen(function* () {
 
 ## References
 
-- Source: `packages/effect/src/unstable/ai/LanguageModel.ts`
-- Chat integration: `packages/effect/src/unstable/ai/Chat.ts`
-- Response types: `effect/unstable/ai/Response`
-- Tool system: `effect/unstable/ai/Tool`, `effect/unstable/ai/Toolkit`
+- Source: `packages/effect/src/ai/LanguageModel.ts`
+- Chat integration: `packages/effect/src/ai/Chat.ts`
+- Response types: `effect/ai/Response`
+- Tool system: `effect/ai/Tool`, `effect/ai/Toolkit`

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

@@ -7,13 +7,17 @@ description: Build prompts for Effect AI using messages, parts, and composition
 
 Master the Effect AI Prompt API for building type-safe conversations with language models.
 
+Baseline: `effect@4.0.0`; inspect that tag in the Effect source reference.
+`effect/ai` APIs remain `@stability unstable` and can break in minor releases.
+Keep provider packages on the same version as `effect`.
+
 ## Import Patterns
 
 **CRITICAL**: Always use namespace imports:
 
 ```typescript
-import * as Prompt from 'effect/unstable/ai/Prompt';
-import * as Response from 'effect/unstable/ai/Response';
+import * as Prompt from 'effect/ai/Prompt';
+import * as Response from 'effect/ai/Response';
 import { pipe } from 'effect';
 ```
 
@@ -54,12 +58,13 @@ The Effect v4 module also exports runtime schemas for every part and each role-s
 
 ## Message Types
 
-Each message has `role` and `content`. Content is an array of `Part` objects.
+Each message has `role` and `content`. System content is a string; other roles
+contain arrays of the parts allowed for that role.
 
 ### System Messages
 
 ```typescript
-import * as Prompt from 'effect/unstable/ai/Prompt';
+import * as Prompt from 'effect/ai/Prompt';
 
 // String content only
 const system = Prompt.makeMessage('system', {
@@ -368,7 +373,7 @@ const appended = pipe(prompt, Prompt.appendSystem(' Be concise.'));
 ### Convert AI Response to Prompt
 
 ```typescript
-import * as Response from 'effect/unstable/ai/Response';
+import * as Response from 'effect/ai/Response';
 
 const responseParts: ReadonlyArray<Response.AnyPart> = [
 	Response.makePart('text-start', { id: 'text_1' }),
@@ -400,7 +405,13 @@ const responseParts: ReadonlyArray<Response.AnyPart> = [
 const historyPrompt = Prompt.fromResponseParts(responseParts);
 ```
 
-`Prompt.fromResponseParts` folds streaming text/reasoning only when the matching start/delta/end parts are present in the same input, places tool calls and approval requests in assistant messages, and skips preliminary tool results. For final tool results it always uses `encodedResult`: framework-executed results (`providerExecuted: false`) become tool messages, while provider-executed results (`providerExecuted: true`) remain in the assistant message with that flag preserved.
+`Prompt.fromResponseParts` folds streaming text/reasoning by matching IDs and
+emits the accumulated part on its end marker. Pass complete start/delta/end
+sequences rather than isolated deltas. It places tool calls and approval requests
+in assistant messages and skips preliminary tool results. For final tool results
+it always uses `encodedResult`: framework-executed results
+(`providerExecuted: false`) become tool messages, while provider-executed results
+(`providerExecuted: true`) remain in the assistant message with that flag preserved.
 
 This distinction matters for hosted tools such as provider web search or code execution. Moving their results into a tool message changes the conversation shape expected by the provider.
 
@@ -426,7 +437,7 @@ This keeps prompt assembly inside the Effect graph instead of forcing Promise is
 ```typescript
 import { Effect } from 'effect';
 import * as SubscriptionRef from 'effect/SubscriptionRef';
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 
 const chat = Effect.gen(function* () {
 	const history = yield* SubscriptionRef.make(Prompt.empty);
@@ -456,7 +467,7 @@ const chat = Effect.gen(function* () {
 ### Generate Text
 
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 import { Effect } from 'effect';
 
 const program = Effect.gen(function* () {
@@ -474,7 +485,7 @@ const program = Effect.gen(function* () {
 ### Stream Text
 
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 import { Effect, Stream } from 'effect';
 
 const program = Effect.gen(function* () {
@@ -493,7 +504,7 @@ const program = Effect.gen(function* () {
 ### Generate Object
 
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 import { Effect, Schema } from 'effect';
 
 const Contact = Schema.Struct({
@@ -525,8 +536,8 @@ 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';
+import * as LanguageModel from 'effect/ai/LanguageModel';
+import * as Prompt from 'effect/ai/Prompt';
 
 const program = LanguageModel.generateText({
 	prompt: Prompt.make([
@@ -552,7 +563,7 @@ OpenAI client layer at the runtime boundary (see `effect-ai-provider`).
 
 ```typescript
 // Augment options interfaces via module augmentation
-declare module 'effect/unstable/ai/Prompt' {
+declare module 'effect/ai/Prompt' {
 	interface TextPartOptions {
 		readonly anthropic?: {
 			readonly cache_control?: {
@@ -703,7 +714,7 @@ const toolInteraction = Prompt.make([
 ## Type Guards
 
 ```typescript
-import * as Prompt from 'effect/unstable/ai/Prompt';
+import * as Prompt from 'effect/ai/Prompt';
 
 declare const value: unknown;
 

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

@@ -7,6 +7,11 @@ description: Configure and compose AI provider layers using @effect/ai packages.
 
 Configure AI provider layers for language model integration using Effect's AI ecosystem.
 
+Baseline: `effect@4.0.0`; inspect the matching tag in the Effect source reference.
+Keep `effect` and every `@effect/*` package on the same version. Core AI APIs and
+provider clients, models, and generated schemas carry `@stability unstable`:
+minor releases may include breaking changes, even with `effect/ai` import paths.
+
 ## When to Use This Skill
 
 Use this skill when:
@@ -34,7 +39,7 @@ import {
 	Stream
 } from 'effect';
 
-// From "effect/unstable/ai" — namespace imports
+// From "effect/ai" — namespace imports
 import {
 	AiError,
 	Chat,
@@ -43,13 +48,13 @@ import {
 	Prompt,
 	Tool,
 	Toolkit
-} from 'effect/unstable/ai';
+} from 'effect/ai';
 // Or individually:
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
-import * as Chat from 'effect/unstable/ai/Chat';
-import * as Model from 'effect/unstable/ai/Model';
-import * as Prompt from 'effect/unstable/ai/Prompt';
-import * as AiError from 'effect/unstable/ai/AiError';
+import * as LanguageModel from 'effect/ai/LanguageModel';
+import * as Chat from 'effect/ai/Chat';
+import * as Model from 'effect/ai/Model';
+import * as Prompt from 'effect/ai/Prompt';
+import * as AiError from 'effect/ai/AiError';
 
 // Anthropic
 import { AnthropicClient, AnthropicLanguageModel } from '@effect/ai-anthropic';
@@ -70,7 +75,7 @@ import {
 } from '@effect/ai-openrouter';
 
 // HTTP client (required by all providers)
-import { FetchHttpClient } from 'effect/unstable/http';
+import { FetchHttpClient } from 'effect/http';
 ```
 
 ## Provider Layer Pattern
@@ -96,7 +101,7 @@ ProviderClient.layerConfig :: { apiKey } → Layer Client HttpClient
 ```typescript
 import { AnthropicClient, AnthropicLanguageModel } from '@effect/ai-anthropic';
 import { Config, Layer } from 'effect';
-import { FetchHttpClient } from 'effect/unstable/http';
+import { FetchHttpClient } from 'effect/http';
 
 // Client layer (reusable across models)
 const AnthropicClientLayer = AnthropicClient.layerConfig({
@@ -115,6 +120,12 @@ const AnthropicLive = AnthropicLanguageModel.layer({
 
 Anthropic capability detection preserves the lower output limits and structured-output support of known legacy Claude models. Unknown and newly released model identifiers default to modern capabilities: native structured outputs and `128_000` output tokens. Override capability detection with `structuredOutputs: false` (or `true`) when a model or compatible endpoint differs from that default; set `max_tokens` separately when the provider's output limit differs.
 
+Anthropic-compatible gateways may omit `usage.inference_geo`. Malformed gateway
+4xx error bodies are classified by HTTP status (including 429 retry delays), not
+as `InvalidOutputError`. Direct `client.betaMessagesPost` calls expose
+`HttpClientError` for those responses; the language-model adapter maps them to
+`AiError` reasons.
+
 ```typescript
 const compatibleClaude = AnthropicLanguageModel.model('future-claude-model', {
 	structuredOutputs: false,
@@ -127,7 +138,7 @@ const compatibleClaude = AnthropicLanguageModel.model('future-claude-model', {
 ```typescript
 import { OpenAiClient, OpenAiLanguageModel } from '@effect/ai-openai';
 import { Config, Layer } from 'effect';
-import { FetchHttpClient } from 'effect/unstable/http';
+import { FetchHttpClient } from 'effect/http';
 
 const OpenAiClientLayer = OpenAiClient.layerConfig({
 	apiKey: Config.Redacted('OPENAI_API_KEY')
@@ -151,6 +162,10 @@ Public OpenAI modules:
 
 `OpenAiSchema.ResponseStreamEvent` accepts both flat OpenAI error events and compatible-provider events with details nested under `error`, normalizing both to the same decoded error event shape.
 
+For WebSocket turns, `previous_response_not_found` triggers a retry with the full
+prompt. An open socket is retained; custom adapters can inspect
+`ProviderOptions.incrementalFallback` to recognize the full-prompt retry.
+
 ```typescript
 const client = yield* OpenAiClient.OpenAiClient;
 const [body] = yield* client.createResponse({
@@ -176,14 +191,21 @@ const NativeTools = Toolkit.make(
 
 Available hosted/provider tools include `WebSearch`, `CodeInterpreter`, `FileSearch`, `ImageGeneration`, and `Mcp` (`customName: "OpenAiMcp"`). MCP tool approval requests/results use this canonical `OpenAiMcp` name and the normal Effect AI approval request/response parts. Handler-required local tools such as `Shell`, `LocalShell`, and `ApplyPatch` run in your environment; provide handlers only behind explicit sandboxing, authorization, and audit policy.
 
+Web-search calls may omit `action`. Narrow that optional field before reading
+action details; incomplete calls are preserved as failed tool results.
+
 ## OpenAI-Compatible Providers
 
-Use `apiUrl` with `@effect/ai-openai` for OpenAI-compatible APIs (Azure OpenAI, local models, etc.):
+Use `apiUrl` with `@effect/ai-openai` for APIs compatible with OpenAI Responses.
+For Chat Completions-compatible endpoints use `@effect/ai-openai-compat`
+(`OpenAiClient`, `OpenAiLanguageModel`), which preserves non-null text/tool
+argument fragments when other streamed delta fields are null. Both adapters
+preserve raw JSON Schema dynamic-tool arguments.
 
 ```typescript
 import { OpenAiClient, OpenAiConfig } from '@effect/ai-openai';
 import { Config, Layer } from 'effect';
-import { FetchHttpClient, HttpClient, HttpClientRequest } from 'effect/unstable/http';
+import { FetchHttpClient, HttpClient, HttpClientRequest } from 'effect/http';
 
 const CompatibleClientLayer = OpenAiClient.layerConfig({
 	apiKey: Config.Redacted('OPENAI_COMPAT_API_KEY'),
@@ -208,7 +230,7 @@ import {
 	OpenRouterLanguageModel
 } from '@effect/ai-openrouter';
 import { Config, Layer } from 'effect';
-import { FetchHttpClient } from 'effect/unstable/http';
+import { FetchHttpClient } from 'effect/http';
 
 const OpenRouterClientLayer = OpenRouterClient.layerConfig({
 	apiKey: Config.Redacted('OPENROUTER_API_KEY')
@@ -226,13 +248,13 @@ const routerModel = OpenRouterLanguageModel.model('anthropic/claude-sonnet-4');
 import { AnthropicClient, AnthropicLanguageModel } from '@effect/ai-anthropic';
 import { OpenAiClient, OpenAiLanguageModel } from '@effect/ai-openai';
 import { Effect, ExecutionPlan, Layer } from 'effect';
-import { LanguageModel } from 'effect/unstable/ai';
+import { LanguageModel } from 'effect/ai';
 
 // Try cheaper model first, fall back to more expensive one
 const DraftPlan = ExecutionPlan.make(
 	{
 		provide: OpenAiLanguageModel.model('gpt-5.2'),
-		attempts: 3 // retry up to 3 times before falling back
+		attempts: 3 // up to 3 total attempts before falling back
 	},
 	{
 		provide: AnthropicLanguageModel.model('claude-opus-4-6'),
@@ -278,7 +300,7 @@ Maintain conversation history with automatic context management:
 
 ```typescript
 import { Effect, Ref } from 'effect';
-import { Chat, Prompt } from 'effect/unstable/ai';
+import { Chat, Prompt } from 'effect/ai';
 
 // Create with system prompt
 const session =
@@ -361,7 +383,7 @@ OpenAI error classification distinguishes temporary rate limits from exhausted a
 Wrap provider layers with metadata. Takes 3 positional arguments: `(providerName, modelId, layer)`:
 
 ```typescript
-import { Model } from 'effect/unstable/ai';
+import { Model } from 'effect/ai';
 
 // This is what ProviderLanguageModel.model() calls internally:
 const Claude = Model.make(
@@ -437,7 +459,7 @@ Wrap `AiError` into domain-specific tagged errors:
 
 ```typescript
 import { Schema } from 'effect';
-import { AiError } from 'effect/unstable/ai';
+import { AiError } from 'effect/ai';
 
 export class MyAiError extends Schema.TaggedError<MyAiError>()(
 	'MyAiError',
@@ -459,7 +481,7 @@ export class MyAiError extends Schema.TaggedError<MyAiError>()(
 | ----------------------- | ------------- | ----------------------------------------------- |
 | `@effect/ai-anthropic`  | Anthropic     | Claude Opus 4, Claude Sonnet 4, etc.            |
 | `@effect/ai-openai`     | OpenAI        | GPT-5, GPT-4.1, o-series, etc.                  |
-| `@effect/ai-openai`     | OpenAI-Compat | Any OpenAI-compatible API via `apiUrl`          |
+| `@effect/ai-openai-compat` | OpenAI-Compat | Chat Completions-compatible APIs via `apiUrl` |
 | `@effect/ai-openrouter` | OpenRouter    | Multi-provider proxy (any model ID)             |
 
 **Note**: There are no `@effect/ai-google` or `@effect/ai-amazon-bedrock` packages. Use OpenRouter to access Google/Bedrock models.
@@ -488,8 +510,8 @@ import {
 	Model,
 	Prompt,
 	type Response
-} from 'effect/unstable/ai';
-import { FetchHttpClient } from 'effect/unstable/http';
+} from 'effect/ai';
+import { FetchHttpClient } from 'effect/http';
 
 // ---------------------------------------------------------------------------
 // Provider client layers
@@ -675,10 +697,16 @@ import { BedrockClient } from '@effect/ai-amazon-bedrock'; // Does NOT exist
 ## References
 
 Provider-neutral structured decisions use `Decision` / `DecisionModel` from
-`effect/unstable/ai`. `OpenRouterDecisionModel` targets OpenRouter's alpha Decisions
+`effect/ai`. `OpenRouterDecisionModel` targets OpenRouter's alpha Decisions
 API; `@effect/ai-typesafe` supplies a provider for TypeSafe System One. Custom
 OpenRouter client implementations include `createDecisions`.
 
+`OpenRouterDecisionModel` and the TypeSafe decision model configure
+`probabilityPrecision: 2`: rounded distributions such as `0.02 / 0.93 / 0.04`
+are accepted and rescaled. Custom `DecisionModel.make` adapters retain strict sum
+validation unless they opt in. `Decision.probability` allows omitted `criteria`;
+when present it must describe both boolean outcomes (see `effect-ai-language-model`).
+
 Use each branded service's same-name type (`LanguageModel.LanguageModel`,
 `EmbeddingModel.EmbeddingModel`, `Chat.Chat`) and its exported TypeId for custom
 implementations. Prefer provided constructors; do not hard-code marker strings.