opencode-effect-enforcer 0.2.5 → 0.2.6

package/docs/effect-4.0.0-rc.116.md

@@ -0,0 +1,102 @@
+# Effect 4.0.0-rc.112 → 4.0.0-rc.116
+
+## Provenance and release scope
+
+- Previous dependency: `effect@4.0.0-rc.112`.
+- Target: `effect@4.0.0-rc.116`, npm's `rc` dist-tag checked on 2026-09-18.
+- npm's `latest` tag is the separate v3 line (`3.22.2`).
+- Exact source: [`effect@4.0.0-rc.116`](https://github.com/Effect-TS/effect/tree/effect%404.0.0-rc.116), commit `d62dd0d65252e5d3635538f0e41adc7c08aa9beb`.
+- [Complete source comparison](https://github.com/Effect-TS/effect/compare/effect%404.0.0-rc.112...effect%404.0.0-rc.116).
+- [Full upstream release notes](effect-4.0.0-rc.116-changelog.md): 121 complete release sections across 31 packages, including dependency-only entries.
+
+The interval includes rc.113, rc.114, rc.115, and rc.116. The changelog collection
+was checked section-by-section against every package `CHANGELOG.md` at the target
+tag. No upstream entry in that interval was omitted. Later releases supersede
+earlier changes; notably PostgreSQL timestamp decoding and unknown-OID behavior
+are documented using the final rc.116 contract.
+
+## Changes applied
+
+| Area | Alignment |
+| --- | --- |
+| Dependency and baseline | Pin Effect and lockfile to rc.116; update README and privileged baseline references. |
+| Config and CLI | PascalCase scalar constructors, explicit Boolean defaults, typed arrays/records and ByteSize configuration. Update secret-config detector and fixtures. |
+| Schema | Effectful transformations, standalone Getter combinators, native Arbitrary, parse options, class identity, revivers, AST contracts, template literals, JSON Schema and compilation. |
+| Socket | Scoped pull readers, batched values, Writer objects, typed closure, backpressure, TLS/STARTTLS, addresses, framing, and reconnect ownership. |
+| RPC and cluster | Replace MessagePack recommendations with SchemaBinary; preserve transport framing rules and codec selection; use cluster option `serialization: 'binary'`. |
+| Filesystem and HTTP | ByteSize counts versus numeric buffer lengths and bigint seek offsets; HTTP schemas in Schema; NetAddress, eager web-handler construction, file/range responses, upgrades, parsing and SSE options. |
+| PostgreSQL | Native PgConnection/PgPool, explicit JSON binding, preparation, registry codecs, final row representations, scoped notification queues, startup and TLS behavior. |
+| AI and MCP | Branded service interfaces, opaque/encoded parameter modes, failure-result codecs/origins, DecisionModel, protocol adapters, strict tools, instructions, prompt titles, and stderr logging. |
+| Streams and atoms | Lazy scan seeds, partition ordering/capacity, mapBoth names, targeted error handling, middleware errors, zero TTL, reactivity branding and dehydration. |
+| Lifetimes and scheduling | Cache TTL by Exit, LayerMap acquisition errors, observer error types, process cleanup, timeout fallback lifetime, repeat metadata, rate-limiter store contract, durable queue policy. |
+| Testing | Native Arbitrary sampling/property checks; adapter peer/runtime requirements; compiler-checked migration examples. |
+| Writing | Remove release-qualified behavior from live skills, patterns, and guidance; retain version history here and in upstream release notes. |
+
+## Content audit inventory
+
+The audit covered all 53 bundled skill directories (54 Markdown files), all 45
+pattern definitions, all four guidance documents, and the runtime source.
+Removed public exports were compared between the exact old and new tags and
+searched across the complete live content tree. Targeted scans also covered
+lowercase Config/CLI constructors, callback sockets, MessagePack, fast-check,
+service interface names, Stream scans, and filesystem sizes.
+
+The following grouping records every skill directory; unchanged skills were
+included in the compatibility scans rather than edited merely to mark an audit.
+
+| Skill directories (`effect-` prefix omitted) | Review focus |
+| --- | --- |
+| schema-v4, schema-composition, domain-modeling, domain-predicates, pattern-matching, optics | Schema syntax, transformations, predicates, tagged unions and issue contracts. |
+| config, cli | Constructor renames, defaults, prompts, collection configuration and secrets. |
+| socket, filesystem, path, platform-abstraction, platform-layers, command-executor | Platform boundaries, scoped I/O, byte counts, address types and process lifetime. |
+| http-api, http-client, http-server | HTTP schemas, parsing, server construction, transport errors, files, SSE and WebSocket upgrades. |
+| rpc-api, rpc-client, rpc-server, rpc-cluster | Schema-aware serialization, framing, cluster defaults, storage and peer compatibility. |
+| ai-chat, ai-language-model, ai-prompt, ai-provider, ai-streaming, ai-tool, mcp-server | Service types, provider responses, tool failures, decisions and MCP contracts. |
+| atom-rpc, atom-state, react-composition | RPC/HTTP error channels, TTL, stream scan, React peer and reactive service contracts. |
+| cache, batching, layer-design, scope, service-implementation, context-witness, managed-runtime, incremental-migration | Cached acquisition, service/layer patterns, resource ownership and runtime boundaries. |
+| fiber, parallelization, concurrency-testing, pubsub-event-bus, stream, scheduling | Structured concurrency, stream operators, timing, retry and test synchronization. |
+| testing, error-handling, observability, wide-events | Native property generation, error surfaces, logger configuration and instrumentation. |
+| sql, workflow, graph, typeclass-design | Native database adapters, durable processing, graph and dual-helper compatibility. |
+
+Patterns requiring content changes were `avoid-process-env`,
+`prefer-redacted-config`, `avoid-direct-tag-checks`, `context-tag-extends`, and
+`require-effect-concurrency`. The secret-config detector recognizes
+`Config.String` and `Config.NonEmptyString`; its examples and regression cases
+use the supported constructors. Bidirectional pattern/test inventory and README
+catalog coverage remain required checks.
+
+The active guidance baseline and examples were updated. Historical essays and
+the earlier rc.112 audit retain their historical context.
+
+## Compatibility decisions
+
+- Keep directly consumed Effect-family packages on compatible release versions.
+  This package directly depends only on `effect`; companion adapters are teaching
+  material, not additional runtime dependencies.
+- `@effect/vitest` requires Vitest `>=5.0.0 <6.0.0` and Node
+  `^22.12.0 || ^24.0.0 || >=26.0.0`. This repository uses plain Vitest 3 and does
+  not install that adapter; its own runner therefore remains unchanged.
+- SchemaBinary is a wire/persistence format change, not a transparent replacement
+  for existing MessagePack bytes. Coordinate peers and stored-data migration.
+- Native PostgreSQL is a driver change. Validate row decoding, custom OIDs,
+  preparation/pooler settings and notification recovery at consuming boundaries.
+- The source reference's moving main branch is not the baseline. The exact tag
+  takes precedence when source and prose disagree.
+
+## Verification
+
+- Changelog completeness: all 121 selected upstream sections matched the collected
+  text across 31 package changelogs.
+- Removed-export scan: no old-only qualified public Effect symbols remain in
+  skills, patterns, guidance or runtime source.
+- `bun run check`: passed formatting, lint (zero warnings/errors) and TypeScript
+  compilation.
+- `bun run test`: passed all 912 tests in 53 files, including detector cases,
+  inventory/catalog coverage, runtime tests and marked Markdown example
+  compilation against installed rc.116.
+- `git diff --check`: passed.
+
+The documentation compiler checks explicitly marked, independent TypeScript
+fences. It does not execute every illustrative fragment or verify integrations
+against live databases/providers. Companion-package examples were reviewed
+against tagged source rather than adding all companion dependencies here.

package/guidance/effect-first-development.md

@@ -2,9 +2,9 @@
 
 This document defines the working model behind Effect-first code using the Effect v4 ecosystem.
 
-Bundled baseline: **Effect 4.0.0-rc.112**. Check the consuming project's installed
+Bundled baseline: **Effect 4.0.0-rc.116**. Check the consuming project's installed
 version and inspect the matching upstream release tag before using newer APIs.
-The release changelog and migration audit are in `docs/effect-4.0.0-rc.112.md`.
+The release changelog and migration audit are in `docs/effect-4.0.0-rc.116.md`.
 Source paths below are relative to the Effect source reference; locate symbols
 by name rather than relying on line numbers or a particular tool name.
 
@@ -296,7 +296,7 @@ export type Tenant = typeof Tenant.Type;
 - Prefer `Schema.Class` for tagged union member schemas.
 - Use `Schema.TaggedUnion` only for canonical `_tag` object-union construction.
 - Reference: `packages/effect/SCHEMA.md`, sections `TaggedUnion` and `toTaggedUnion`.
-- In rc.112, both union forms offer `matchOrElse` for partial matching with a typed fallback. Prefer `match` when every variant must be handled separately. `toTaggedUnion` narrows fallback input to unmatched variants; direct `Schema.TaggedUnion` types it as the full union.
+- Both union forms offer `matchOrElse` for partial matching with a typed fallback. Prefer `match` when every variant must be handled separately. `toTaggedUnion` narrows fallback input to unmatched variants; direct `Schema.TaggedUnion` types it as the full union.
 
 Example:
 
@@ -420,6 +420,12 @@ const pollInterval = Duration.millis(250);
 const program = Effect.sleep(pollInterval).pipe(Effect.timeout(timeout));
 ```
 
+### EF-16b: Byte counts use `ByteSize`
+
+Use `ByteSize` and `ByteSize.Input` for byte counts and storage/network limits.
+Keep signed seek offsets as `bigint`. Parse external size strings before passing
+them to APIs, and preserve exact counts rather than coercing them to numbers.
+
 ### EF-17: Nullable/nullish schema fields should decode to `Option`
 
 - Use dedicated schema helpers for optional/null conversions:
@@ -467,7 +473,7 @@ const b = pipe('value', addPrefix('p:'));
 
 ### EF-19: JSON parse/stringify must use Schema
 
-- Use `Schema.fromJsonString(Schema.Unknown)` for unknown JSON payloads. `Schema.UnknownFromJsonString` is internal as of beta.103.
+- Use `Schema.fromJsonString(Schema.Unknown)` for unknown JSON payloads.
 - Use `Schema.fromJsonString(MySchema)` for typed JSON string boundaries.
 - Avoid direct `JSON.parse` / `JSON.stringify` in Effect-first code.
 - Reference: [`fromJsonString`](packages/effect/src/Schema.ts) in the Effect v4 source.
@@ -540,7 +546,7 @@ const readSdkValue = (client: ExternalSdk) =>
 - Prefer `Effect.scoped` for helper composition that allocates resources.
 - Do not manually open resources without an explicit finalization strategy.
 - Reference: `acquireUseRelease` and `scoped` in `packages/effect/src/Effect.ts`.
-- For pool checkouts in rc.112 use `Pool.use(pool, callback)` to return the item on every exit without adding a caller `Scope` requirement. Do not return an item from `Effect.scoped(Pool.get(pool))` and then use it after release.
+- For pool checkouts use `Pool.use(pool, callback)` to return the item on every exit without adding a caller `Scope` requirement. Do not return an item from `Effect.scoped(Pool.get(pool))` and then use it after release.
 
 Example:
 
@@ -615,7 +621,7 @@ const runWithHeartbeat = Effect.fn('Worker.run')(function* () {
 - For non-trivial fan-out, set concurrency in `Effect.forEach`, `Effect.all`, or `Effect.validate`.
 - Avoid implicit unbounded parallelism on large collections.
 - Concurrency should be part of API intent for throughput-sensitive paths.
-- Use an explicit number or `"unbounded"`. The `"inherit"` option and `Effect.withConcurrency` were removed in beta.102.
+- Use an explicit number or `"unbounded"`; pass concurrency policy directly to each combinator.
 - Reference: `Effect.forEach`, `Effect.all`, and `Types.Concurrency` in the Effect v4 source.
 
 Example:
@@ -640,16 +646,16 @@ Example:
 import { Config, Effect } from 'effect';
 
 const loadPort = Effect.fn('Config.loadPort')(function* () {
-	return yield* Config.int('PORT');
+	return yield* Config.Int('PORT');
 });
 ```
 
 ### EF-29: Secrets must stay redacted
 
-- Use `Config.redacted` for secret config values.
+- Use `Config.Redacted` for secret config values.
 - Use `Redacted.make` for sensitive values coming from non-config sources.
 - Never log secret values after unwrapping.
-- Reference: `Config.redacted` in `packages/effect/src/Config.ts` and `packages/effect/src/Redacted.ts`.
+- Reference: `Config.Redacted` in `packages/effect/src/Config.ts` and `packages/effect/src/Redacted.ts`.
 
 Example:
 
@@ -657,7 +663,7 @@ Example:
 import { Config, Effect } from 'effect';
 
 const loadApiKey = Effect.fn('Config.loadApiKey')(function* () {
-	const apiKey = yield* Config.redacted('API_KEY');
+	const apiKey = yield* Config.Redacted('API_KEY');
 	yield* Effect.logDebug(`apiKey=${String(apiKey)}`);
 	return apiKey;
 });
@@ -764,6 +770,8 @@ export class CreateOrderInput extends Schema.Class<CreateOrderInput>(
 - Use `Schema.withDecodingDefault` / `Schema.withDecodingDefaultKey` for decode-time defaults.
 - Constructor defaults may fail with `SchemaIssue.Issue`. Likewise, `MySchema.makeEffect(fields)` returns validation failures directly as `SchemaIssue.Issue`, not wrapped in `Schema.SchemaError`.
 - Constructor defaults (including `Schema.tag`) do not automatically apply during boundary decoding. Unknown input uses `Schema.decodeUnknownEffect`; `decodeSync` is not a constructor replacement.
+- Class `make`, `makeOption`, and `makeEffect` preserve an existing instance. Use `new` when a distinct instance is intended.
+- Pass parsing options to the decoder/encoder/constructor adapter. Model retained extra properties with `Record` or `StructWithRest`; use `onExcessProperty: "error"` for closed boundaries.
 
 Example:
 
@@ -925,6 +933,7 @@ const arraysEqual = (
 
 - If conversion is deterministic and type-shaping (path normalization, filename conversion, tagged-string normalization), model it with `Schema.decodeTo(..., SchemaTransformation.transform(...))`.
 - Prefer schema transformation helpers over ad-hoc conversion functions.
+- Use `SchemaGetter.transformEffect` / `SchemaTransformation.transformEffect` for effectful conversion. Compose getters with standalone `SchemaGetter.compose`, and transformation pairs with `SchemaTransformation.composeTransformation`.
 
 Example:
 
@@ -994,7 +1003,7 @@ const UnknownToString = Schema.Unknown.pipe(
 - For invalidatable caches, use `Effect.cachedInvalidateWithTTL(effect, Duration.infinity)` which returns a `[cachedEffect, invalidate]` tuple. Call `yield* invalidate` to force re-computation on next access.
 - For time-based caches, use `Effect.cachedWithTTL(effect, duration)`.
 - Prefer `Effect.cachedInvalidateWithTTL` with `Duration.infinity` over mutable `let` rebinding of cached effects.
-- For keyed scoped resources, rc.112 adds `RcMap.getOption` and `LayerMap.contextEffectOption`. They atomically retain already-cached entries and propagate acquisition failures; `None` means missing/closed, not failed. A `has` check followed by `get` is not equivalent.
+- For keyed scoped resources, use `RcMap.getOption` and `LayerMap.contextEffectOption` to atomically retain already-cached entries and propagate acquisition failures; `None` means missing/closed, not failed. A `has` check followed by `get` is not equivalent.
 
 Example:
 
@@ -1191,8 +1200,8 @@ export const resilientTask = task.pipe(
 import { Config, Effect } from 'effect';
 
 export const loadConfig = Effect.fn('Config.load')(function* () {
-	const port = yield* Config.int('PORT');
-	const apiKey = yield* Config.redacted('API_KEY');
+	const port = yield* Config.Int('PORT');
+	const apiKey = yield* Config.Redacted('API_KEY');
 	return { port, apiKey };
 });
 ```
@@ -1237,7 +1246,7 @@ Use this before submitting code:
 24. Forking intent is explicit (`forkChild` default; `forkDetach` justified).
 25. Large fan-out operations specify concurrency deliberately.
 26. Config values come from `Config` / `ConfigProvider`, not direct `process.env` in domain logic.
-27. Secrets are `Redacted` (`Config.redacted` / `Redacted.make`) and not logged raw.
+27. Secrets are `Redacted` (`Config.Redacted` / `Redacted.make`) and not logged raw.
 28. Recovery uses `catchTag` / `catchFilter` for targeted cases.
 29. Expected failures use `Effect.fail`; defects are reserved for invariants and discarding irrelevant upstream error types via `orDie`.
 30. Isolation-sensitive layer provisioning uses `{ local: true }` or `Layer.fresh`.

package/guidance/progressive-disclosure-guidance.md

@@ -1,6 +1,6 @@
 # Agent Rules
 
-The bundled guidance targets **Effect 4.0.0-rc.112**. Read the consuming project's
+The bundled guidance targets **Effect 4.0.0-rc.116**. Read the consuming project's
 version before applying an API: stable v3, older prereleases, and unreleased main
 can have different contracts. Keep directly used Effect-family packages on
 compatible release versions.
@@ -10,8 +10,8 @@ Load all relevant skills before writing or planning any code. Effect is a massiv
 When skills leave any ambiguity, or when you encounter unfamiliar APIs during implementation, read the OpenCode `effect` reference at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`. Treat this reference as the source of truth over `node_modules`, stale external docs, or memory.
 
 Check the reference revision too. For this baseline, inspect the
-`effect@4.0.0-rc.112` tag (for example with `git show
-effect@4.0.0-rc.112:packages/effect/src/Schema.ts`) when main has moved ahead.
+`effect@4.0.0-rc.116` tag (for example with `git show
+effect@4.0.0-rc.116:packages/effect/src/Schema.ts`) when main has moved ahead.
 Source symbols and signatures at that tag take precedence over stale prose or
 line-number links. Public exports marked `@internal` in source are not application APIs.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "opencode-effect-enforcer",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "OpenCode V2 plugin for Effect v4 skills, guidance, and pattern enforcement",
   "keywords": [
     "opencode",
@@ -46,7 +46,7 @@
     "@ast-grep/napi": "^0.42.3",
     "@opencode/plugin": "2.0.8",
     "diff": "^9.0.0",
-    "effect": "4.0.0-rc.112",
+    "effect": "4.0.0-rc.116",
     "picomatch": "^4.0.3",
     "yaml": "^2.8.1"
   },

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

@@ -55,6 +55,6 @@ 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
+keys beyond `_tag`. `.matchOrElse` provides 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-process-env.md

@@ -19,9 +19,9 @@ suggestSkills:
 processEnv :: String -> IO (Maybe String)    -- side effect, untyped, untestable
 
 -- Instead
-Config.string :: String -> Config String     -- typed, composable, testable
+Config.String :: String -> Config String     -- typed, composable, testable
 Config.withDefault :: a -> Config a -> Config a
-Config.redacted :: String -> Config Redacted -- for sensitive values
+Config.Redacted :: String -> Config Redacted -- for sensitive values
 ```
 
 ```haskell
@@ -30,10 +30,10 @@ bad :: Effect String
 bad = Effect.sync \_ -> process.env.API_KEY    -- raw side effect
 
 good :: Effect String ConfigError
-good = Config.string "API_KEY"                 -- typed, validated
+good = Config.Redacted "API_KEY"               -- typed, redacted
 
 better :: Effect String ConfigError
-better = Config.string("PORT")
+better = Config.Int("PORT")
   & Config.withDefault "3000"
   & Config.map Number.parse                    -- with transformation
 ```

package/patterns/context-tag-extends.md

@@ -26,13 +26,13 @@ suggestSkills:
 
 # Use `Context.Service` for All Service Definitions
 
-`Context.Service` is the single canonical service-definition API in Effect v4 (beta.46+). Three legacy spellings exist and must all be replaced:
+Use `Context.Service` for service definitions. Replace these legacy spellings:
 
 | Legacy API                  | Era       | Replacement                |
 | --------------------------- | --------- | -------------------------- |
 | `Context.Tag` / `GenericTag` | pre-v4    | `Context.Service`          |
 | `Effect.Service`            | early v4  | `Context.Service`          |
-| `ServiceMap.Service` / `.*` | beta.43    | `Context.Service` / `Context.*` |
+| `ServiceMap.Service` / `.*` | prerelease | `Context.Service` / `Context.*` |
 
 ```haskell
 -- Anti-pattern: *Tag suffix + Context.Tag — removed in v4
@@ -43,10 +43,10 @@ data ParallelClientService = ...
 -- Anti-pattern: Effect.Service — also removed in v4
 class ParallelClient extends Effect.Service<ParallelClient>()(...)
 
--- Anti-pattern: ServiceMap.* — removed before v4 beta.46 stabilized
+-- Anti-pattern: ServiceMap.*
 class MyService extends ServiceMap.Service<MyService>()("@app/MyService", { ... })
 
--- Fix: Context.Service (beta.46 API)
+-- Fix: Context.Service
 class ParallelClient extends Context.Service<ParallelClient>()(
   "@parallel/ParallelClient"
 )

package/patterns/prefer-redacted-config.md

@@ -3,13 +3,13 @@ action: context
 tool: (edit|write)
 event: after
 name: prefer-redacted-config
-description: Use Config.redacted or Schema.Redacted for secret-like configuration values
+description: Use Config.Redacted or Schema.Redacted for secret-like configuration values
 glob: '**/*.{ts,tsx}'
 detector: ast
 rule:
     any:
-        - pattern: Config.string($KEY)
-        - pattern: Config.nonEmptyString($KEY)
+        - pattern: Config.String($KEY)
+        - pattern: Config.NonEmptyString($KEY)
         - all:
               - kind: pair
               - has:
@@ -33,18 +33,18 @@ suggestSkills:
 
 ```haskell
 -- Transformation
-Config.string secretKey    :: String            -- easy to log accidentally
-Config.redacted secretKey  :: Redacted String   -- hidden from logs/toString
+Config.String secretKey    :: String            -- easy to log accidentally
+Config.Redacted secretKey  :: Redacted String   -- hidden from logs/toString
 ```
 
 ```typescript
 // Bad
-const apiKey = Config.string('API_KEY');
-const token = Config.nonEmptyString('GITHUB_TOKEN');
+const apiKey = Config.String('API_KEY');
+const token = Config.NonEmptyString('GITHUB_TOKEN');
 
 // Good
-const apiKey = Config.redacted('API_KEY');
-const token = Config.redacted('GITHUB_TOKEN');
+const apiKey = Config.Redacted('API_KEY');
+const token = Config.Redacted('GITHUB_TOKEN');
 ```
 
 For structured config schemas, wrap secret-like string fields in `Schema.Redacted`:
@@ -67,4 +67,4 @@ const AppConfig = Config.schema(
 );
 ```
 
-Secrets should remain redacted from the moment they enter the program. Use `Config.redacted` for primitive config values and `Schema.Redacted(Schema.String)` for schema-based config fields.
+Secrets should remain redacted from the moment they enter the program. Use `Config.Redacted` for primitive config values and `Schema.Redacted(Schema.String)` for schema-based config fields.

package/patterns/require-effect-concurrency.md

@@ -79,7 +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
+Effect.all(tasks, { concurrency: 'inherit' }); // unsupported ambient policy
 
 // Good
 Effect.forEach(items, processItem, { concurrency: 1 });

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

@@ -231,7 +231,7 @@ const program = Effect.gen(function* () {
 		timeToLive: '1 hour' // optional TTL
 	});
 
-	// chat is a `Chat.Persisted` — same API as Chat.Service but auto-saves
+	// chat is a `Chat.Persisted` — same API as Chat.Chat but auto-saves
 	const response = yield* chat
 		.generateText({
 			prompt: 'Hello!'
@@ -245,7 +245,7 @@ const program = Effect.gen(function* () {
 });
 ```
 
-The `Persisted` interface extends `Chat.Service` with:
+The `Persisted` interface extends `Chat.Chat` with:
 
 - `id: string` — the chat identifier in the store
 - `save: Effect<void, AiError | PersistenceError>` — manual save trigger

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

@@ -94,7 +94,13 @@ const manualTools = LanguageModel.generateText({
 });
 ```
 
-When `disableToolCallResolution: true`, tool-call `params` are preserved in the schema's **encoded** representation instead of being decoded and then returned. The response type reflects this as `GenerateTextResponse<Tools, true>` and `Response.ToolCallParts<Tools, true>`; streaming uses `Response.StreamPart<Tools, true>`. This matters for transformations such as `Schema.NumberFromString`: manual calls contain the wire value `{ count: '3' }`, not `{ count: 3 }`.
+With `disableToolCallResolution: true`, tool-call `params` retain the schema's
+**encoded** representation. Response generics use the mode `"encoded"`, for
+example `GenerateTextResponse<Tools, "encoded">` and
+`Response.StreamPart<Tools, "encoded">`. Automatic resolution uses `"opaque"`
+parameters (`unknown`), because invalid calls can also appear in responses.
+Only successfully decoded handler inputs have the decoded parameter type.
+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>`.
 
@@ -104,7 +110,7 @@ Pass those encoded params directly to `toolkit.handle(name, params, toolCallId)`
 const response = yield* LanguageModel.generateText({ prompt: '...' });
 
 response.text; // string - concatenated text content
-response.toolCalls; // decoded params normally; encoded params when resolution is disabled
+response.toolCalls; // opaque params normally; encoded params when resolution is disabled
 response.toolResults; // Array<ToolResultParts> - tool outputs
 response.finishReason; // "stop" | "length" | "content-filter" | "tool-calls" | "error" | "pause" | "unknown" | "other"
 response.usage; // Usage object with nested structure, e.g. response.usage.outputTokens.total
@@ -297,6 +303,32 @@ const robust = LanguageModel.generateText({
 );
 ```
 
+## Batched classification, rating, and probability
+
+Use `DecisionModel` for structured judgments over one schema-encoded input.
+Define named decisions once and send them in one call; input encoding services
+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.
+
+<!-- typecheck -->
+```ts
+import * as Schema from 'effect/Schema';
+import { Decision, DecisionModel } from 'effect/unstable/ai';
+
+class Ticket extends Schema.Class<Ticket>('Ticket')({ body: Schema.String }) {}
+const triage = Decision.make({
+	input: Ticket,
+	decisions: {
+		team: Decision.classify({
+			instructions: 'Choose the team responsible for this request',
+			criteria: { billing: 'Payments and invoices', support: 'Product support' }
+		})
+	}
+});
+const result = DecisionModel.decide(triage, { input: new Ticket({ body: 'Invoice question' }) });
+```
+
 ## Type Extraction Utilities
 
 ```typescript
@@ -308,8 +340,8 @@ type MyError = LanguageModel.ExtractError<typeof options>;
 // Extract service requirements from options
 type MyRequirements = LanguageModel.ExtractServices<typeof options>;
 
-// true only when options has literal disableToolCallResolution: true
-type EncodedParams = LanguageModel.ExtractEncodedToolParameters<typeof options>;
+// "encoded" for literal disableToolCallResolution: true; otherwise "opaque"
+type ParametersMode = LanguageModel.ExtractToolParametersMode<typeof options>;
 
 // Inferred based on:
 // - toolkit: Toolkit.WithHandler<Tools> → Tool.HandlerError<Tools> ∈ E

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

@@ -516,7 +516,7 @@ const program = Effect.gen(function* () {
 
 ## Provider-Specific Options
 
-### OpenAI Responses explicit cache breakpoints (rc.112)
+### OpenAI Responses explicit cache breakpoints
 
 With `@effect/ai-openai` loaded, system-message and text-part options accept
 `openai.promptCacheBreakpoint`. This requires GPT-5.6 or later; earlier models

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

@@ -100,7 +100,7 @@ import { FetchHttpClient } from 'effect/unstable/http';
 
 // Client layer (reusable across models)
 const AnthropicClientLayer = AnthropicClient.layerConfig({
-	apiKey: Config.redacted('ANTHROPIC_API_KEY')
+	apiKey: Config.Redacted('ANTHROPIC_API_KEY')
 }).pipe(Layer.provide(FetchHttpClient.layer));
 
 // Option A: model() — returns Model.Model (preferred)
@@ -130,7 +130,7 @@ import { Config, Layer } from 'effect';
 import { FetchHttpClient } from 'effect/unstable/http';
 
 const OpenAiClientLayer = OpenAiClient.layerConfig({
-	apiKey: Config.redacted('OPENAI_API_KEY')
+	apiKey: Config.Redacted('OPENAI_API_KEY')
 }).pipe(Layer.provide(FetchHttpClient.layer));
 
 // model() constructor (preferred)
@@ -186,7 +186,7 @@ import { Config, Layer } from 'effect';
 import { FetchHttpClient, HttpClient, HttpClientRequest } from 'effect/unstable/http';
 
 const CompatibleClientLayer = OpenAiClient.layerConfig({
-	apiKey: Config.redacted('OPENAI_COMPAT_API_KEY'),
+	apiKey: Config.Redacted('OPENAI_COMPAT_API_KEY'),
 	apiUrl: Config.succeed('https://my-provider.example.com/v1')
 }).pipe(Layer.provide(FetchHttpClient.layer));
 
@@ -211,7 +211,7 @@ import { Config, Layer } from 'effect';
 import { FetchHttpClient } from 'effect/unstable/http';
 
 const OpenRouterClientLayer = OpenRouterClient.layerConfig({
-	apiKey: Config.redacted('OPENROUTER_API_KEY')
+	apiKey: Config.Redacted('OPENROUTER_API_KEY')
 }).pipe(Layer.provide(FetchHttpClient.layer));
 
 // model() constructor — use provider-prefixed model IDs
@@ -420,7 +420,7 @@ export class AiWriter extends Context.Service<
 
 ## Custom Error Wrapping
 
-In rc.112, `AiError.AuthenticationError` accepts an optional `description` and
+`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
@@ -496,11 +496,11 @@ import { FetchHttpClient } from 'effect/unstable/http';
 // ---------------------------------------------------------------------------
 
 const AnthropicClientLayer = AnthropicClient.layerConfig({
-	apiKey: Config.redacted('ANTHROPIC_API_KEY')
+	apiKey: Config.Redacted('ANTHROPIC_API_KEY')
 }).pipe(Layer.provide(FetchHttpClient.layer));
 
 const OpenAiClientLayer = OpenAiClient.layerConfig({
-	apiKey: Config.redacted('OPENAI_API_KEY')
+	apiKey: Config.Redacted('OPENAI_API_KEY')
 }).pipe(Layer.provide(FetchHttpClient.layer));
 
 // ---------------------------------------------------------------------------
@@ -619,15 +619,15 @@ Effect.runPromise(program.pipe(Effect.provide(AiWriter.layer)));
 // WRONG: Hardcoded API keys
 AnthropicClient.layerConfig({ apiKey: 'sk-...' });
 
-// RIGHT: Config.redacted for secrets
-AnthropicClient.layerConfig({ apiKey: Config.redacted('ANTHROPIC_API_KEY') });
+// RIGHT: Config.Redacted for secrets
+AnthropicClient.layerConfig({ apiKey: Config.Redacted('ANTHROPIC_API_KEY') });
 
 // WRONG: Missing FetchHttpClient layer
-AnthropicClient.layerConfig({ apiKey: Config.redacted('KEY') });
+AnthropicClient.layerConfig({ apiKey: Config.Redacted('KEY') });
 // Will fail at runtime — providers require an HttpClient
 
 // RIGHT: Always provide an HTTP client layer
-AnthropicClient.layerConfig({ apiKey: Config.redacted('KEY') }).pipe(
+AnthropicClient.layerConfig({ apiKey: Config.Redacted('KEY') }).pipe(
 	Layer.provide(FetchHttpClient.layer)
 );
 
@@ -653,7 +653,7 @@ import { BedrockClient } from '@effect/ai-amazon-bedrock'; // Does NOT exist
 
 ## Quality Checklist
 
-- [ ] Use `Config.redacted` for API keys (never hardcode)
+- [ ] Use `Config.Redacted` for API keys (never hardcode)
 - [ ] Provide `FetchHttpClient.layer` to all client layers
 - [ ] Use `.model()` constructor for `ExecutionPlan` and `Effect.provide`
 - [ ] Use `ExecutionPlan` for multi-provider fallback with retry
@@ -674,6 +674,17 @@ 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
+API; `@effect/ai-typesafe` supplies a provider for TypeSafe System One. Custom
+OpenRouter client implementations include `createDecisions`.
+
+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.
+OpenAI web-search sources are a discriminated union: narrow `type` before reading
+`url` or `name`. Provider-executed tool failures remain failure results.
+
 - `packages/ai/anthropic/src/AnthropicLanguageModel.ts`
 - `packages/ai/openai/src/OpenAiLanguageModel.ts`
 - `packages/ai/openrouter/src/OpenRouterLanguageModel.ts`

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

@@ -208,6 +208,19 @@ type Error = Tool.Failure<typeof FindUser>;
 
 **Key Pattern: failureMode**
 
+Parameter validation follows the tool's `failureMode`. Failure results include
+`Tool.ExecutionFailure` for framework failures (AI errors, denial, interruption)
+as well as declared user errors. Select result codecs using `isFailure` and
+`Tool.failureResultSchema(tool)`; preserve `encodedResult` when storing or
+replaying response parts. A failure with `Schema.NumberFromString` is stored as
+a string, even when the success schema stores a number. Validation errors do not
+expose a `toolParams` field.
+
+`Toolkit.handle` accepts parse options for parameter decoding. Returned failures
+carry `failureOrigin`, also available through the `Toolkit.FailureOrigin` cause
+annotation and `Tool.FailureOrigin` type. Keep validation, declared handler, and
+internal failures distinct when presenting or reporting them.
+
 - `"error"` (default): Failures go to Effect error channel
 - `"return"`: Failures returned as tool result (captured, not thrown)
 

package/skills/effect-atom-rpc/SKILL.md

@@ -20,7 +20,7 @@ Use this skill when building React (or Atom-based) frontends that consume an exi
 For the underlying RPC definitions, see the `effect-rpc-cluster` skill.
 For Atom fundamentals (`Atom.make`, `family`, `keepAlive`, `AsyncResult`, hydration), see the `effect-atom-state` skill.
 
-The underlying RPC protocols require `codecFor` in rc.112. Built-in protocol
+The underlying RPC protocols require `codecFor`. Built-in protocol
 layers supply it; forward it when implementing a custom transport. You can pair
 `RpcSerialization.layerSchemaBinary` on client/server without changing query or
 mutation call sites; see `effect-rpc-client` for frame limits and compatibility.
@@ -29,6 +29,12 @@ type is `string`. This is distinct from the client's `{ discard: true }` option.
 
 ## Effect Source Reference
 
+Query and mutation errors include client middleware errors. AtomHttpApi stream
+successes retain transport, decoding, and SSE failures in the stream error channel;
+handle them when consuming the stream. An explicit zero `timeToLive` disables
+default idle retention, so unmount/remount may dispose and refetch. Omission uses
+the registry default. HttpApi calls accept per-call `sseOptions`.
+
 - `packages/effect/src/unstable/reactivity/AtomRpc.ts` — the whole API (~270 lines)
 - `packages/effect/test/reactivity/AtomRpc.test.ts` — minimal usage + serialization test
 - `packages/effect/src/unstable/reactivity/AtomHttpApi.ts` — the cousin pattern for `HttpApi` (same idea, same options)