---
name: effect-v4
description: >-
  Use when writing, debugging, or reviewing Effect-TS v4 (4.0.0-beta) code in this
  repo — resolving an Effect API, verifying a signature/error shape, or finding
  idiomatic usage. v4 is a fast-moving beta whose web docs are outdated; this skill
  points you at the vendored Effect source (repos/effect) so you read real
  implementations instead of guessing or applying stale v3 patterns. Trigger on any
  uncertainty about an `effect` import, module, type, or `effect/unstable/*` API.
---

# Effect v4 source reference

This repo runs **Effect v4 (`4.0.0-beta.70`)**. Public docs lag the real APIs, and v3
patterns frequently do **not** apply. The complete Effect v4 source is vendored at
**`repos/effect`** (a `git subtree` of **`Effect-TS/effect-smol`**, the v4 dev repo,
pinned to the `effect@4.0.0-beta.70` tag — it matches the installed version exactly).
v4 lives in `effect-smol`, NOT `Effect-TS/effect` (still v3). Treat it as the
authoritative reference — read it instead of guessing or trusting web search.

## Golden rule

**Don't assume — read the source.** If you are about to write an Effect v4 API call
and you are not 100% certain of its current shape, look it up in `repos/effect` first.
The cost of a grep is far lower than the cost of a wrong v3-flavored guess.

## Where things live

All under `repos/effect/packages/effect/src/`. Module name maps 1:1 to the import:

| Import | Source |
|--------|--------|
| `effect` (e.g. `Context`, `Effect`, `Layer`, `Schema`, `Data`, `DateTime`) | `src/<Module>.ts` |
| `effect/unstable/http` | `src/unstable/http/` |
| `effect/unstable/httpapi` | `src/unstable/httpapi/` |
| `effect/unstable/rpc` | `src/unstable/rpc/` |
| `effect/unstable/sql` | `src/unstable/sql/` |
| `effect/unstable/reactivity` (Atom) | `src/unstable/reactivity/` |

`@effect/sql-pg` and `@effect/atom-react` live under `repos/effect/packages/`.

## How to use it

- **Resolve / verify an API:** open `repos/effect/packages/effect/src/<Module>.ts` and
  read the exported `declare const` / class / interface. Grep for the symbol:
  `rg "export (declare const|class|interface) <Name>" repos/effect/packages/effect/src`
- **Find idiomatic usage:** search tests and examples —
  `rg "<api>" repos/effect/packages/effect/test repos/effect/packages/effect/examples`
- **Confirm an error/option shape** before constructing it (constructors changed a lot
  between betas).

## Hard rules

- `repos/effect` is **read-only reference material**. Never edit it, never import from
  it, never copy its files into `packages/` or `apps/`.
- App/package code depends on the **published `effect` package** via the
  `pnpm-workspace.yaml` catalog — not the vendored tree.
- It's excluded from search/auto-import/watching (`.vscode/settings.json`) and from the
  pnpm / tsc / vitest workspaces, so it won't interfere with builds.
- To refresh it:
  `git subtree pull --prefix=repos/effect https://github.com/Effect-TS/effect-smol.git effect@4.0.0-beta.70 --squash`
  (re-pin the tag to whatever version the catalog uses; use `main` for the latest)

## Known v4 deltas (verify against source if in doubt)

- **`ServiceMap` → `Context`**: the module was renamed back to `Context`. Use
  `Context.Service<Self, Shape>()("Id")`, `Context.Reference<T>("Id", { defaultValue })`,
  `Context.make(key, value)`, `Context.add`, `Context.get`.
- **`SqlError`** wraps a structured reason:
  `new SqlError.SqlError({ reason: new SqlError.UnknownError({ cause }) })` (the `cause`
  field is now derived, not a constructor arg).
- Service keys are yieldable directly: `const db = yield* Database` (no `FiberRef.get`).
- See `CLAUDE.md` → "Effect v4 — Vendored Source Reference" for the project-level summary.