opencode-effect-enforcer 0.2.8 → 0.3.0

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

@@ -7,20 +7,20 @@ description: Implement reactive state management with Effect Atom for React appl
 
 Effect Atom is a reactive state management library for Effect that seamlessly integrates with React.
 
-`@effect/atom-react` supports React `>=19.0.0 <20.0.0` (the peer range
-was relaxed). This does not add React 18 support. Keep the adapter aligned with
-the Effect release; core atoms still live in `effect/unstable/reactivity`, and
+`@effect/atom-react@4.0.0` requires React `>=19.0.0 <20.0.0`.
+Keep the adapter at the same version as `effect`; core atoms live in `effect/reactivity`, and
 React bindings live in `@effect/atom-react` (`packages/atom/react` upstream).
+Core reactivity APIs carry `@stability unstable` and may break in minor releases.
 
 ## 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.
+Inspect `git show effect@4.0.0:<path>` there for this baseline; main may be ahead.
 
 Reference this for:
 
-- Atom reactivity: `packages/effect/src/unstable/reactivity/`
-- AsyncResult source: `packages/effect/src/unstable/reactivity/AsyncResult.ts`
+- Atom reactivity: `packages/effect/src/reactivity/`
+- AsyncResult source: `packages/effect/src/reactivity/AsyncResult.ts`
 - Effect source: `packages/effect/src/`
 
 ## Core Concepts
@@ -36,7 +36,7 @@ explicit for state that must survive SSR dehydration.
 Atoms work **by reference** - they are stable containers for reactive state:
 
 ```typescript
-import * as Atom from 'effect/unstable/reactivity/Atom';
+import * as Atom from 'effect/reactivity/Atom';
 
 // Atoms are created once and referenced throughout the app
 export const counterAtom = Atom.make(0);
@@ -47,10 +47,13 @@ export const counterAtom = Atom.make(0);
 
 ### Automatic Cleanup
 
-Atoms automatically reset when no subscribers remain (unless marked with `keepAlive`):
+Registry nodes become eligible for disposal when unused by subscribers and
+dependent atoms. Disposal follows the atom's idle TTL or registry default; it is
+not necessarily synchronous with the last React unmount. `keepAlive` retains the
+node until its registry is reset/disposed:
 
 ```typescript
-// Resets when last subscriber unmounts
+// Disposed after becoming unused, according to the registry's idle policy
 export const temporaryState = Atom.make(initialValue);
 
 // Persists across component lifecycles
@@ -61,10 +64,15 @@ export const persistentState = Atom.make(initialValue).pipe(Atom.keepAlive);
 
 Atom values are computed on-demand when subscribers access them.
 
+Tracked dependencies remain retained while a node is stale and are reconciled
+on its next build. Register cleanup with `get.addFinalizer` or scoped effects so
+superseded builds release resources. Observed failed builds can recover when a
+dependency changes; avoid manual reset workarounds for stale-node propagation.
+
 ## Pattern: Basic Atoms
 
 ```typescript
-import * as Atom from 'effect/unstable/reactivity/Atom';
+import * as Atom from 'effect/reactivity/Atom';
 
 // Simple atom
 export const count = Atom.make(0);
@@ -132,19 +140,29 @@ export const userAtoms = Atom.family((userId: string) =>
 	Atom.make<User | null>(null).pipe(Atom.keepAlive)
 );
 
-// Usage - always returns the same atom for a given ID
+// Reuses the cached live atom for a given ID
 const userAtom = userAtoms(userId);
 ```
 
+Family caches use weak references where supported. Identity is reused while the
+cached atom is live; it is not a permanent store of every key ever requested.
+An old atom's finalizer does not evict a newer cached atom for the same key.
+
 ## Pattern: Atom.fn for Async Actions
 
 Use `Atom.fn` with `Effect.fnUntraced` for async operations:
 
 - Reading gives `AsyncResult<Success, Error>` with automatic `.waiting` flag
 - Triggering via `useAtomSet` runs the effect
+- The callback takes one application argument plus an `Atom.FnContext`; bundle
+  multiple inputs into an object. The second argument is not another payload.
+- By default a new write replaces the current run. Use `{ concurrent: true }`
+  deliberately for overlapping Effect executions. Synchronous successes and
+  failures are retained in concurrent mode; it still exposes one `AsyncResult`,
+  not a per-invocation result log.
 
 ```typescript
-import * as Atom from "effect/unstable/reactivity/Atom"
+import * as Atom from "effect/reactivity/Atom"
 import { useAtomValue, useAtomSet } from "@effect/atom-react"
 import { Effect, Exit } from "effect"
 
@@ -278,7 +296,7 @@ Atom.runtime.addGlobalLayer(
 Atoms can return `AsyncResult` types for explicit error handling:
 
 ```tsx
-import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
+import * as AsyncResult from 'effect/reactivity/AsyncResult';
 
 export const userData = Atom.make<AsyncResult.AsyncResult<User, Error>>(
 	AsyncResult.initial()
@@ -354,7 +372,7 @@ Use `Atom.kvs` for persisted state:
 
 ```typescript
 import { BrowserKeyValueStore as BrowserKvs } from '@effect/platform-browser';
-import * as Atom from 'effect/unstable/reactivity/Atom';
+import * as Atom from 'effect/reactivity/Atom';
 import * as Schema from 'effect/Schema';
 
 export const userSettings = Atom.kvs({
@@ -452,7 +470,7 @@ export const wsConnection = Atom.make(
 2. **Never Manual Void Wrappers**: Don't wrap Effects in void functions—you lose `waiting` control
 3. **Reference Stability**: Use `Atom.family` for dynamically generated atom sets
 4. **Lazy Evaluation**: Values computed on-demand when accessed
-5. **Automatic Cleanup**: Atoms reset when unused (unless `keepAlive`)
+5. **Automatic Cleanup**: Unused atoms follow idle retention; `keepAlive` lasts until registry reset/disposal
 6. **Derive, Don't Coordinate**: Use computed atoms to derive state
 7. **Result Types**: Handle errors explicitly with AsyncResult.match
 8. **Services in Runtime**: Wrap layers once, use in multiple atoms
@@ -467,7 +485,7 @@ export const wsConnection = Atom.make(
 Use `Atom.fn` with `Effect.fnUntraced` which automatically provides `AsyncResult` with `.waiting` flag:
 
 ```typescript
-import * as Atom from "effect/unstable/reactivity/Atom"
+import * as Atom from "effect/reactivity/Atom"
 import { useAtomValue, useAtomSet } from "@effect/atom-react"
 import { Effect } from "effect"
 
@@ -496,7 +514,7 @@ function UserProfile() {
 
 ```typescript
 export const updateItem = runtime.fn(
-	Effect.fnUntraced(function* (id: string, updates: Partial<Item>) {
+	Effect.fnUntraced(function* ({ id, updates }: { id: string; updates: Partial<Item> }) {
 		const current = yield* Atom.get(itemsAtom);
 
 		// Optimistic update
@@ -569,12 +587,32 @@ Atom.batch(() => {
 	registry.set(ageAtom, 30);
 	registry.set(statusAtom, 'active');
 });
-// Subscribers notified once, not three times
+// Dependents observe the final batched state
 ```
 
 Outside Effect/Atom contexts, use an `AtomRegistry` (`registry.set(...)`) inside the batch. Inside an atom or write context, use that context (`ctx.set(...)`) in the same pattern. `Atom.batch` only batches notifications; it does not introduce a free `set` function.
 
-Use when multiple atoms must update atomically to avoid intermediate renders.
+Batch synchronous writes to avoid intermediate notifications. Writes made by
+commit listeners are processed in subsequent commit work rather than dropped,
+so do not promise exactly one callback when listeners themselves write.
+Batching is not rollback: writes made before a thrown exception are still
+committed and notified, then the first failure is rethrown. Async work after an
+`await` is outside the batch.
+
+## Stale-while-revalidate reads
+
+Wrap an `AsyncResult` query atom with `Atom.swr({ staleTime: '30 seconds' })`.
+Reads return the current result and defer stale-source refresh until after the
+read. The scheduled refresh is skipped if the source becomes fresh or the
+wrapper is disposed; a one-shot unmounted read does not keep background work
+alive. Mount/subscribe for a continuing query lifetime.
+
+`revalidateOnMount` controls initial stale refreshes. `revalidateOnFocus: true`
+respects `staleTime`, while `'always'` forces a refresh. Manual refresh always
+forwards to the source. `staleTime` is a freshness window, distinct from idle TTL.
+Create the wrapper once (module scope, `Atom.family`, or `useMemo`) rather than
+on every render. `swr` returns `WithoutSerializable<R>`; retain the serializable
+source atom for hydration or explicitly serialize the wrapper under its own key.
 
 ## AsyncResult.builder
 

package/skills/effect-batching/SKILL.md

@@ -14,7 +14,7 @@ Reference this for:
 
 - `Request` and `Request.Class` definitions (`packages/effect/src/Request.ts`)
 - `RequestResolver` constructors and combinators (`packages/effect/src/RequestResolver.ts`)
-- `SqlResolver` for SQL-specific batching (`packages/effect/src/unstable/sql/SqlResolver.ts`)
+- `SqlResolver` for SQL-specific batching (`packages/effect/src/sql/SqlResolver.ts`)
 - Batching tutorial (`ai-docs/src/05_batching/10_request-resolver.ts`)
 
 ## The N+1 Problem
@@ -440,10 +440,12 @@ class Users extends Context.Service<
 
 ## SQL Integration with SqlResolver
 
-`SqlResolver` (from `effect/unstable/sql`) provides schema-validated, batched SQL resolvers. Import:
+`SqlResolver` (from `effect/sql`) provides schema-validated, batched SQL resolvers.
+It remains marked `@stability unstable` even though its import path has no
+`unstable` segment; check its release-specific contract when upgrading. Import:
 
 ```typescript
-import { SqlResolver } from 'effect/unstable/sql';
+import { SqlResolver } from 'effect/sql';
 ```
 
 ### SqlResolver.ordered

package/skills/effect-cache/SKILL.md

@@ -15,6 +15,9 @@ the yielded service and `get` / `contextEffect` / `contextEffectOption`: an entr
 can fail when reacquired after successful preloading. Invalidating an active
 RcMap/LayerMap entry releases it after its last borrower closes; a replacement
 entry remains independently owned.
+Preload keys with zero `idleTimeToLive` are skipped, including the default TTL.
+Set a non-zero TTL when construction must eagerly acquire and validate them;
+otherwise acquisition failures surface on first use.
 
 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.
@@ -47,7 +50,7 @@ interface Cache<Key, A, E = never, R = never> {
 How to think about it:
 
 - **Entries store the lookup `Exit`** — successes *and failures* are cached. A failed lookup keeps failing from cache until the entry expires, is invalidated, or is refreshed.
-- **Concurrent `get`s of the same missing key share one lookup.** The first caller runs the lookup on its own fiber; the rest await the same `Deferred`.
+- **Concurrent `get`s of the same missing key share one lookup fiber.** Each caller waits independently; interrupting one waiter does not cancel work still needed by another. The last departing waiter interrupts a pending lookup.
 - **Insertion-ordered map = LRU.** Reads move the entry to the back; when capacity is exceeded the oldest entries are evicted.
 - **TTL is computed per entry** from the lookup `Exit` and the key, against the fiber's `Clock` — `TestClock` works. Expiry is lazy: entries are removed when next touched.
 - **`ScopedCache`** is the same model where each entry additionally owns a `Scope`: resources acquired during the lookup live exactly as long as the entry is cached.
@@ -191,7 +194,7 @@ If an older in-flight lookup is interrupted after `set` installs a newer value,
 yield* Cache.invalidate(cache, 'k'); // remove one key; no-op if absent
 yield* Cache.invalidateAll(cache); // clear everything
 
-// Conditional: removes only a *resolved successful* value matching the predicate.
+// Conditional: awaits a pending entry, then removes a successful value matching the predicate.
 // Returns false for missing, expired, failed, or non-matching entries.
 const removed: boolean = yield* Cache.invalidateWhen(cache, 'k', (v) => v.stale);
 ```
@@ -205,7 +208,7 @@ const fresh = yield* Cache.refresh(cache, 'k');
 - Always invokes the lookup, even for an unexpired entry, and resets the TTL from the new exit.
 - For an **existing** key, the old entry keeps serving `get` callers until the new lookup completes — built-in stale-while-revalidate.
 - For a **missing** key, a pending entry is inserted immediately; concurrent `get`s wait on it.
-- Concurrent `refresh` calls are **not deduplicated** — each runs the lookup independently (only `get` dedups).
+- `Cache.refresh` calls are **not deduplicated** — each runs the lookup independently. `ScopedCache.refresh` of a missing key delegates to `get` and shares that pending lookup; refreshes of existing keys run independently.
 
 ---
 
@@ -234,6 +237,11 @@ yield* Cache.get(cache, 'd'); // evicts 'b'
 - `Duration.infinity` (the default) means no expiry. `Duration.zero` means the entry expires immediately — effectively "do not cache this result".
 - `refresh` and re-`get`-after-expiry both restart the TTL clock; plain `get` hits do not extend it (no sliding expiration).
 
+`Cache.get` does not retain a zero-TTL result after completion. A synchronous
+zero-TTL lookup does not occupy capacity and evict a live entry; a pending lookup
+still occupies capacity while it is shared. `ScopedCache` has the distinct lazy
+resource-release behavior described in section 8.
+
 Per-key and per-result TTL via `makeWith`:
 
 ```ts
@@ -274,7 +282,7 @@ const robust = yield* Cache.makeWith(fetchUser, {
 });
 ```
 
-**Interruption poisons entries the same way**: the lookup runs on the fiber of the caller that triggered the miss. If that fiber is interrupted mid-lookup, the entry's deferred completes with the interrupt exit — concurrent waiters fail with it, and with an infinite TTL later `get`s keep replaying the interrupt instead of retrying. The exit-aware TTL above also fixes this, because an interrupt is a non-success exit (`Exit.isSuccess(exit) === false`) and gets a zero/short TTL.
+**Interruption is not cached.** Missing-key lookups run in daemon fibers, shared by their waiters. One caller's interruption leaves the lookup alive while another caller is waiting. When the last waiter leaves before completion, the lookup is interrupted and its entry removed; a later `get` starts again. `ScopedCache` also closes that lookup's entry scope. Children forked with `forkChild` inside the lookup end with the lookup fiber, not with the requesting caller; use the entry scope for resource-lifetime background work.
 
 `getSuccess`, `values`, and `entries` skip failed entries; `getOption` and `get` propagate the cached error; `invalidateWhen` returns `false` for failed entries (the predicate only sees successes).
 
@@ -341,6 +349,10 @@ The entry's scope is closed — releasing everything the lookup acquired — whe
 4. **replaced** (`set` over an existing key; `refresh` closes the old entry's scope after the new lookup completes),
 5. **orphaned by cache close** (the owning scope closes).
 
+A pending shared lookup also closes its entry scope when its last waiter leaves.
+Interrupting an existing-key `refresh` closes the replacement scope and leaves
+the previous entry intact.
+
 ```ts
 const tracker: Array<string> = [];
 const cache = yield* ScopedCache.make({
@@ -434,7 +446,7 @@ const cacheB = yield* Cache.make({
 const row = yield* Cache.get(cacheB, 1).pipe(Effect.provideService(Db, dbImpl));
 ```
 
-At runtime the lookup always sees the construction-time context merged with the caller's context (the caller's services win on conflicts). Tracing is connected: the lookup runs on the calling fiber, so spans created inside the lookup are children of the caller's current span. Remember the lookup runs **once per miss** — only the first caller's context matters for a given entry.
+At runtime the lookup sees the construction-time context merged with the initiating caller's context (the caller's services win on conflicts). The shared lookup fiber inherits that caller's tracing context. Remember the lookup runs **once per miss** — later waiters do not replace the context for a pending entry.
 
 The same option exists on `ScopedCache.make`/`makeWith`.
 
@@ -597,9 +609,9 @@ it.effect('expires entries after the TTL', () =>
 2. **v4 renames type parameters, it does not reorder them** — v3's `Cache<Key, Value, Error>` becomes `Cache<Key, A, E, R>`: same value-before-error order with a services parameter appended. Only the pre-v3 `@effect/io` era used `Cache<Key, Error, Value>`.
 3. **`Cache.makeWith(lookup, options)` vs `ScopedCache.makeWith({ lookup, ...options })`** — `Cache.makeWith` takes the lookup as a separate first argument; `ScopedCache.makeWith` (and both `make`s) take one options object containing `lookup`.
 4. **Failures are cached with the default infinite TTL** — one transient lookup error fails that key forever. Use `makeWith` with an exit-aware TTL (`Exit.isSuccess(exit) ? ttl : Duration.zero`).
-5. **Interrupting the fiber that started a lookup poisons the entry** — the lookup runs on the first caller's fiber; if it is interrupted, the interrupt exit is cached and replayed to waiters and later `get`s. The exit-aware TTL in (4) also covers interrupts.
+5. **Confusing caller cancellation with lookup cancellation** — a shared missing-key lookup survives while any waiter remains. The last departing waiter interrupts pending work; interrupted entries are removed, and `ScopedCache` closes their scopes. Failure TTL policy is still needed for ordinary failures.
 6. **`timeToLive` in `make` is a `Duration.Input` value, not a function** — the `(exit, key) => Duration.Input` form only exists on `makeWith`; passing a function to `make` won't compile.
-7. **`refresh` is not deduplicated** — concurrent `refresh` calls each run the lookup; only `get` shares in-flight lookups. Serialize refreshes yourself if the lookup is expensive.
+7. **Assuming all refreshes deduplicate** — `Cache.refresh` and existing-key `ScopedCache.refresh` run independently. Only missing-key `ScopedCache.refresh` delegates to the shared `get` path. Serialize expensive refreshes if needed.
 8. **Don't mutate key objects after first use** — plain objects compare structurally in v4 (equal-content literals do hit), but `Equal`/`Hash` cache their results per object, so a mutated key misbehaves silently. Prefer primitives or immutable `Data.Class`/`Schema.Class` keys.
 9. **Don't `Effect.acquireRelease` inside a plain `Cache` lookup** — `Scope` leaks into `R` and finalizers attach to whatever outer scope is around, not to the entry: nothing is released on eviction/invalidation. Use `ScopedCache`, which provides a per-entry scope.
 10. **ScopedCache values die with their entry** — after `invalidate`/eviction/expiry-purge the value's finalizers have run. Don't hold the value beyond the entry's lifetime; use `effect/Pool` for checkout semantics.

package/skills/effect-cli/SKILL.md

@@ -20,8 +20,11 @@ scalars containing colon-whitespace or a trailing colon: quote those values.
 
 ## Import Pattern
 
+The CLI APIs are marked `@stability unstable` even at the stable package release.
+Inspect `effect@4.0.0:packages/effect/src/cli/` for this baseline's contracts.
+
 ```typescript
-import { Argument, Command, Flag, Prompt } from 'effect/unstable/cli';
+import { Argument, Command, Flag, Prompt } from 'effect/cli';
 ```
 
 Platform services and runtime for the entry point:
@@ -37,7 +40,7 @@ Positional arguments are parsed in order. Use `Flag.Boolean` for toggles or `Arg
 ### Constructors
 
 ```typescript
-import { Argument } from 'effect/unstable/cli';
+import { Argument } from 'effect/cli';
 
 Argument.String('name'); // string
 Argument.Int('count'); // number (integer)
@@ -64,7 +67,7 @@ Argument.FileSchema('config', MySchema); // reads and validates file via Schema
 ### Combinators
 
 ```typescript
-import { Argument } from 'effect/unstable/cli';
+import { Argument } from 'effect/cli';
 
 // Description for help text
 Argument.String('file').pipe(Argument.withDescription('Input file'));
@@ -121,10 +124,16 @@ Argument.Int('count').pipe(
 
 Flags are named options with `--name` or `-alias` syntax.
 
+Negative numeric tokens such as `-3`, `-3.70`, `-.5`, and `-1e-3` are values,
+not short-option bundles: `--lon -3.70` works with `Flag.Finite('lon')`.
+Use `--` to pass trailing operands that otherwise look like options; a lone
+`-` is also retained as a value. Numeric lexing does not replace the chosen
+primitive's validation.
+
 ### Constructors
 
 ```typescript
-import { Flag } from 'effect/unstable/cli';
+import { Flag } from 'effect/cli';
 
 Flag.Boolean('verbose'); // required: --verbose / --no-verbose; omission fails
 Flag.String('config'); // --config value
@@ -152,7 +161,7 @@ Flag.KeyValuePair('env'); // --env FOO=bar → Record<string, string>
 ### Combinators
 
 ```typescript
-import { Flag } from 'effect/unstable/cli';
+import { Flag } from 'effect/cli';
 
 // Alias
 Flag.Boolean('verbose').pipe(
@@ -217,7 +226,7 @@ Bare boolean flags are required. `--verbose` produces `true`, `--no-verbose` pro
 <!-- typecheck -->
 ```typescript
 import { Effect } from 'effect';
-import { Prompt } from 'effect/unstable/cli';
+import { Prompt } from 'effect/cli';
 
 Prompt.Int({ message: 'Count', default: 42 });
 Prompt.File({ message: 'Pick file', default: '/workspace/config.json' });
@@ -253,7 +262,7 @@ choice values rather than pre-escaping your domain values.
 
 ```typescript
 import { Console, Effect } from 'effect';
-import { Argument, Command, Flag } from 'effect/unstable/cli';
+import { Argument, Command, Flag } from 'effect/cli';
 
 // Simple command (no config, no handler)
 const version = Command.make('version');
@@ -509,7 +518,7 @@ Command.provideSync(MyService, (config) => makeMyService(config.env));
 ```typescript
 import { NodeRuntime, NodeServices } from '@effect/platform-node';
 import { Effect } from 'effect';
-import { Command, Flag } from 'effect/unstable/cli';
+import { Command, Flag } from 'effect/cli';
 
 const myCommand = Command.make(
 	'myapp',