lsp-mcp/EFFECT.md

# Effect 4 notes for this repo

Effect `4.0.0-rc.115` (pinned in `package.json`; `repos/effect` is the same version, check
`repos/effect/packages/effect/package.json` if either is bumped). The API differs from Effect 3
in places, and the type stripper gives no hints, so agents kept re-verifying the same shapes.
This file records what has been verified against the source so the next agent does not have to.

When something is not listed here, grep the source, not `node_modules`:
`grep -n "^export const NAME" repos/effect/packages/effect/src/MODULE.ts` shows the signature
and implementation; `repos/effect/packages/effect/test/` has usage examples. Add what you learn.

## Renames from Effect 3 (the things that bite)

- `Effect.async` → `Effect.callback`; `Effect.catchAll` → `Effect.catch`; `Effect.catchAllCause` → `Effect.catchCause`.
- Every `unsafeX` is `xUnsafe`: `Deferred.doneUnsafe`, `Deferred.isDoneUnsafe`, `PubSub.publishUnsafe`,
  `SubscriptionRef.getUnsafe`, `Latch.openUnsafe`, `Scope.makeUnsafe`.
- `Context.Tag` classes are `Context.Service<Self, Shape>()("id")`; layers are built with `Layer.effect(Tag, make)`.
- `Schema.Union([A, B])` and `Schema.Literals(["a", "b"])` take an array. Filters are `.check(Schema.isInt(),
  Schema.isGreaterThanOrEqualTo(0))`, not `.pipe(Schema.int())`. `.annotate({ description, message })`.
  `Schema.TaggedError<Self>()("Tag", fields)`; `Schema.NumberFromString`; `Schema.fromJsonString(Schema.Json)`.
- `Duration.isGreaterThan` / `isLessThan` (not `greaterThan`); `Duration.format(d)` prints `1s 500ms`.
- `Effect.timeout` / `timeoutOption` / `timeoutOrElse`; `Stream.runHead` returns an `Option`.
- `Effect.forkScoped(effect, { startImmediately?, uninterruptible? })`; `Effect.forkIn(scope)`; `Effect.forkDetach`.
- `Effect.tap` accepts an effect or a function; `Effect.when(condition)` returns an `Option`.
- `Effect.fn("name")(function* (...) {})` for traced generator functions (used everywhere in `src/lsp/`).

## Schedule (reshaped in v4)

- Constructors: `exponential(base, factor)`, `spaced`, `fixed`, `recurs(n)`, `forever`, `jittered`, `cron`.
- Limits: `Schedule.upTo({ times, duration })` (replaces `intersect(recurs(n))`); `Schedule.while(meta => boolean | Effect)`
  replaces `whileInput` / `whileOutput` / `recurWhile`; `Schedule.modifyDelay(meta => Duration.Input)`; `Schedule.tap(meta => ...)`;
  `Schedule.passthrough`. Combinators: `Schedule.max(a, b)` recurs while both do, with the slower delay (Effect 3
  `intersect`); `Schedule.min` recurs while either does, with the faster delay (`union`); `Schedule.concat` runs one
  then the other (`andThen`). There is no `resetAfter`: write a step with its own state instead (below).
- `Metadata` given to those callbacks: `{ input, output, duration, attempt, start, now, elapsed, elapsedSincePrevious }`.
  `elapsedSincePrevious` is the time between consecutive steps (between crashes, for a restart policy).
- Custom schedules: `Schedule.fromStepWithMetadata(Effect.sync(() => (meta: InputMetadata<Input>) => ...))`, where the step
  returns `Effect.succeed([output, delay])` to continue or `Cause.done(output)` to stop. `Effect.sync` runs once per `retry`,
  so closure state (a crash streak) is per run. See `restarts` in `src/lsp/LanguageServer.ts`.
- `Effect.retry` takes `{ while, until, times, schedule }`, a `Schedule`, or a builder `($) => ...`. `Effect.retryOrElse(schedule,
  (lastError, output) => ...)` runs the fallback once the schedule stops. The effect under retry/repeat sees
  `Schedule.CurrentMetadata` as a service.

## Concurrency primitives (as expected, with v4 names)

- `Deferred.make<A, E>()`, `await`, `succeed`, `fail`, `done(exit)`, `isDone`; the `*Unsafe` variants are synchronous and return
  `boolean` (whether this call completed it). Waiters of `Deferred.await` resume synchronously inside `doneUnsafe`.
- `PubSub.unbounded<A>({ replay? })`, `publish`, `publishUnsafe`, `subscribe`, `Stream.fromPubSub`, `Stream.fromSubscription`.
- `SubscriptionRef.make/get/set/update/changes`; `changes` emits the current value first (replay 1).
- `Latch.make(open?)` with `.open`, `.close`, `.await`, `.release`, `.whenOpen(effect)`.
- `Semaphore.make(n)`, `.withPermits(n)(effect)`; `FiberSet.makeRuntime<R>()` / `makeRuntimePromise` to run effects from callbacks.
- `ScopedCache.makeWith({ capacity, timeToLive: (exit) => Duration, lookup })`, `get`, `has`, `invalidate`, `keys`, `values`, `entries`.
- `Cause.done(value)` is the halt signal used by `Pull`, `Schedule` and `Stream` internals; `Cause.hasInterruptsOnly(cause)`.

## `effect/unstable/cli`

- `Command.make(name, { flag: Flag..., arg: Argument... }, Effect.fn(function* (config) {}))`, `Command.withDescription`,
  `Command.withExamples([{ command, description }])`, `Command.run({ version })`.
- `Flag.String/Int/Boolean/Directory(name, { mustExist })/KeyValuePair/Literals(name, [...])`; `Flag.withSchema(schema)`
  (decodes from the flag's type, so `Schema.NumberFromString` for a string flag), `withDescription`, `withDefault`, `withAlias`,
  `withMetavar("never|always|N")`, `optional` (→ `Option`), `map`, `orElse`. `Argument.String`, `Argument.variadic`.
- Help does not print default values; put them in the description. Schema failures print `Invalid value for flag --x: "v".
  Expected: Schema validation failed: <message annotation or issue>`.

## `effect/unstable/ai` MCP (see `src/Server.ts`, `src/Tools.ts`, `src/Resources.ts`)

- `McpServer.layerStdio(info)` / `layerHttp({ ...info, path })` served with `HttpRouter.serve`; `McpServer.registerToolkit(toolkit)`
  after `Toolkit.toLayer(handlers)`; `McpServer.registerResource({ uri | template, name, description, mimeType, content, completion })`.
- `Tool.make(name, { description, parameters, success, failure, dependencies }).annotate(Tool.Readonly, ...)`.
- `McpServer.McpServer` service exposes `notifications["notifications/message" | "notifications/resources/updated"]`.

## `@effect/vitest`

- `it.effect` / `it.live` tests run inside a `Scope`; `it.layer(layer, { excludeTestServices: true })("name", (it) => ...)` shares the
  layer across the block and, with that option, uses the real clock (`Stream.debounce` and timeouts hang under `TestClock`).
- Real processes and `Effect.sleep` need real time, so every fixture-server test uses `excludeTestServices` or `it.live`.

## `vscode-jsonrpc` (not Effect, but verified the same way)

- Loss of the peer: `connection.onClose` fires on transport close and on `dispose()`; pending requests reject with
  `ResponseError` codes `ConnectionInactive` (-32096), `PendingResponseRejected` (-32097) or `MessageWriteError` (-32099).
- Writing to a dead child's stdin rejects a promise nobody handles (EPIPE crashes the process). `LanguageServer.ts` writes through
  a `PassThrough` piped into stdin and listens for stdin errors instead.
- `connection.onRequest((method, params) => ...)` registers a catch-all ("star") handler; handlers registered per type are
  consulted first.