effect-v4

What this skill does

# Effect v4 (Beta) - Development & Migration

## Overview

Comprehensive guidance for Effect v4 development and migration from v3. This skill provides:

1. **v4 Core Patterns** - Guide to building new v4 code with `Context`, layers, generators, schema codecs
2. **v3 → v4 Migration** - Step-by-step migration guidance with API renames, behavior changes, and before/after examples

**Status:** Effect v4 is beta software under active development in [effect-smol](https://github.com/Effect-TS/effect-smol). The core programming model is stable, but `effect/unstable/*` modules may receive breaking changes in minor releases. For production use, review official v4 beta guidance and stability notes.

All bundled migration guides are sourced from the official effect-smol migration documentation.

## Upstream Changes Since February 22, 2026

The upstream beta changed substantially after this skill was last refreshed. Treat older examples that mention `ServiceMap` or `Schema.makeUnsafe` as stale. Current guidance should prefer:

- `Context.Service` / `Context.Reference` / `Context<R>` instead of `ServiceMap.*`
- `Schema.make(...)` instead of `Schema.makeUnsafe(...)`
- `Schema.makeEffect(...)` when constructor-style validation should fail in the error channel instead of throwing

## Quick Triage

### Building v4 Code

- Core Effect types and combinators (Result, Option, Chunk, Duration): `references/core-usage.md`
- Broader data types (DateTime, BigDecimal, HashSet, Redacted): `references/data-types-advanced.md`
- Equality, Order, Hash, Equivalence semantics: `references/behavior-traits.md`
- Expected errors vs defects, `catch*` combinators: `references/error-management.md`
- Sandboxing, Cause inspection, `catchCause`: `references/error-tooling.md`
- Exit and Cause structure, result inspection: `references/exit-cause.md`
- Services and dependency injection (`Context`, layers): `references/dependency-management.md`
- Layer construction, memoization, `{ local: true }`: `references/layer-patterns.md`
- Resource lifecycles, Scope, `acquireRelease`: `references/resource-management.md`
- Running effects, `Runtime` removal, run boundaries: `references/runtime-execution.md`
- Fibers, `forkChild`, `forkDetach`, fork options: `references/concurrency.md`
- References (replaces FiberRef), `Context.Reference`: `references/concurrency-advanced.md`
- Schedules, repetition, spaced/fixed/exponential: `references/scheduling.md`
- Retries, backoff, schedule composition: `references/scheduling-retry.md`
- Streams, queues, PubSub, STM: `references/streams-queues-stm.md`
- HTTP clients and external APIs: `references/http-client.md`
- HTTP servers and API definitions: `references/http-server.md`
- Request batching and data loaders: `references/request-resolver.md`
- Caching and memoization: `references/caching.md`
- Configuration and config providers: `references/configuration.md`
- Advanced config, redaction: `references/configuration-advanced.md`
- Logs, metrics, tracing: `references/observability.md`
- Logger/metrics/tracing setups and exporters: `references/observability-examples.md`
- Wiring log/metric/trace layers: `references/observability-wiring.md`
- Sequential workflows and yieldable patterns: `references/generators.md`
- Schema validation, parsing, encoding (codecs): `references/schema.md`
- Stream consumption with reducers (Sink): `references/sink.md`
- Deterministic time in tests (TestClock): `references/testing.md`
- Broader testing services and test layers: `references/testing-stack.md`
- Command, FileSystem, Path, Terminal, KeyValueStore: `references/platform-primitives.md`
- LLM workflows, planning, tool use via Effect AI: `references/ai.md`
- Bundle-size constrained runtimes (Micro): `references/micro.md`
- Migrating from Promise/async: `references/migration-async.md`
- Common pitfalls and runtime errors: `references/troubleshooting.md`
- Docs-to-guide map from `llms.txt`: `references/docs-index.md`

### Migrating from v3

- Full migration overview, quick-reference table, ordered checklist: `references/migration.md`
- Runtime and run functions: `references/migration/runtime.md`
- Error handling and error channel changes: `references/migration/error-handling.md`
- Cause flattening and new structure: `references/migration/cause.md`
- Services and environment changes (`Context.Tag` / `Effect.Service` → `Context.Service`): `references/migration/services.md`
- Fiber references and context locals: `references/migration/fiberref.md`
- Forking and fiber APIs (fork → forkChild, etc.): `references/migration/forking.md`
- Fiber keep-alive behavior changes: `references/migration/fiber-keep-alive.md`
- Scope and resource lifecycle patterns: `references/migration/scope.md`
- Layer memoization and Layer.fresh: `references/migration/layer-memoization.md`
- Generator and Effect.gen changes: `references/migration/generators.md`
- Yieldable protocol (non-Effect yieldables): `references/migration/yieldable.md`
- Equality and structural comparison: `references/migration/equality.md`

## Workflow

1. Ask which v3 APIs or files are in scope and which failures or regressions to avoid.
2. Open only the relevant migration notes from `references/migration/`.
3. Produce a mapping of v3 to v4 APIs, including before/after code snippets.
4. Call out behavior changes, edge cases, and test updates needed.
5. Provide a short, ordered migration checklist tailored to the code in question.

## Source of Truth

- Start with the bundled references in this skill.
- If the question depends on newer beta behavior, check the official docs and `effect-smol` changelogs next.
- Only inspect `effect-smol` source internals when the docs/changelogs are ambiguous, the user is asking about internals, or the behavior appears undocumented.
- Do not clone or read the repo source by default when the bundled references or official docs already answer the question.

## Example Requests

- "Migrate this v3 `Runtime` usage to v4 and explain the new run functions."
- "Update our v3 error handling to v4 and show before/after examples."
- "We use FiberRefs and forking; what needs to change in v4?"
- "Explain the generator/yieldable changes and update this Effect.gen usage."
- "Do we need to change any Scope or Layer memoization behavior in v4?"

## References - v4 Core

Comprehensive v4-specific guides (all updated for v4 APIs, no deprecated patterns):

- `references/core-usage.md` - Core Effect types and combinators (Result, Option, Chunk)
- `references/data-types-advanced.md` - DateTime, BigDecimal, HashSet, Redacted
- `references/behavior-traits.md` - Structural equality by default, Equal, Order, Hash
- `references/error-management.md` - `catch*` renames, `catchReason`, `catchEager`
- `references/error-tooling.md` - `catchCause`, sandboxing, Cause inspection
- `references/exit-cause.md` - Flattened Cause structure, Reason iteration
- `references/dependency-management.md` - Context, services, layers
- `references/layer-patterns.md` - Cross-provide memoization, `{ local: true }`
- `references/resource-management.md` - `Scope.provide` (was `Scope.extend`)
- `references/runtime-execution.md` - `Runtime<R>` removed, run* at the edge
- `references/concurrency.md` - `forkChild`/`forkDetach`, fork options, keep-alive
- `references/concurrency-advanced.md` - `Context.Reference` (was `FiberRef`)
- `references/scheduling.md` - Schedules and repetition
- `references/scheduling-retry.md` - Retries and backoff
- `references/streams-queues-stm.md` - Streams, queues, PubSub, STM
- `references/http-client.md` - HTTP clients
- `references/http-server.md` - HTTP servers
- `references/request-resolver.md` - Request batching
- `references/caching.md` - Caching and memoization
- `references/configuration.md` - Configuration
- `references/configuration-advanced.md` - Advanced config, redaction
- `references/observability.md` - Logs, metrics, tracing
- `references/observability-examples.md` - Concrete logger/metrics/tracing setups
- `references/obse