Docs that contradict the code: MCP.md's adapter list, RcMap capacity eviction, `disableChecks`, an unbounded "max attempts" retry example, the `@effect/vitest` logging example, and names v4 does not have

This is ten separate doc corrections, each naming its file and line range, so split them up and take one first: the disableChecks JSDoc in src/Schema.ts or the forkDetach JSDoc in src/Effect.ts. Check each claim against the cited code before editing, since the issue links pin 4.0.5. Done means each listed wording is corrected in its own file, and for the item 4 retry example, the attempt bound is verified under TestClock. Items 1 and 4 also touch packages/effect/MCP.md and ai-docs/src/06_schedule/10_schedules.ts.

What is the type of issue?

Documentation is incorrect, Documentation is missing

What is the issue?

These docs in 4.0.5 disagree with the code. #9331 did not touch them, and each is unchanged on main (c9a1e72). Links are pinned to the 4.0.5 tag.

Behaviour described wrongly

1. MCP.md lists three protocol adapters (MCP.md#L82-L83): "This release supports McpProtocol.v2024_11_05, McpProtocol.v2025_03_26, and McpProtocol.v2025_06_18."

   • McpProtocol also exports v2025_11_25 and v2026_07_28 (McpProtocol.ts#L211-L254).
   • layerStdio and layerHttp accept any of the five (McpServer.ts#L1520, #L1657), and ProtocolAdapters.test.ts builds layerHttp with all five.
   • layerHttpRequestScoped accepts only v2026_07_28 (#L1713-L1715), which the sentence leaves out.
   • The same paragraph (MCP.md#L88-L89) says logs go to stderr through Logger.consolePretty({ stderr: true }). #8074 removed that option (Logger.ts#L823-L829). #8079 then moved the example to Layer.succeed(Logger.LogToStderr, true) (MCP.md#L64-L65), but left this sentence.
   • Fix: list all five adapters, note that layerHttpRequestScoped accepts only v2026_07_28, and name Logger.LogToStderr.

2. RcMap's module header (RcMap.ts#L6-L8) says that when the last scope for a key closes, the resource can be "removed by capacity limits".

   • Capacity evicts nothing. Once the map is full, get for a new key fails with ExceededCapacityError (#L358-L361), and idle entries count toward the limit.
   • Example: with capacity: 1 and idleTimeToLive: "1 hour", borrow and release "a", then get "b". The get fails with ExceededCapacityError, and "a" is neither removed nor released.
   • Fix: "…released, kept alive for its idle time to live, or removed by invalidate. capacity caps how many keys are held, idle ones included; once it is reached, get for a new key fails with ExceededCapacityError."

3. disableChecks is described as disabling validation: "to skip validation" (Schema.ts#L126), "Whether to disable validation for the schema" (#L142), and, in the Class Gotchas, "skips constructor validation" (#L16054).

   • It skips only checks. Types and structure are still parsed.
     • Schema.Int.make(1.5, { disableChecks: true }) returns 1.5.
     • Schema.Int.make("a" as any, { disableChecks: true }) throws "Schema validation failed".
     • So does a Class constructor given a string for a Schema.Int field.
   • ParseOptions already states this precisely (SchemaAST.ts#L492-L493).
   • The first two sentences predate the rename from disableValidation in Effect-TS/effect-smol#1842. That rename made construction parse with checks off, instead of skipping parsing.
   • Fix: "skips the schema's checks (filters such as isInt); constructor defaults still apply, and input of the wrong type or shape is still rejected."

4. ai-docs productionRetrySchedule (10_schedules.ts#L8-L18) is commented "capped exponential backoff with jitter and max attempts". loadUserWithRetry refers to "exhausting the schedule" (#L47-L48).

   • Nothing bounds the attempts. Schedule.min continues while either schedule does, and neither exponential nor spaced ends, so Schedule.while(retryable) is the only stop.
   • Against an always-retryable HttpError under TestClock, it makes about 8,650 attempts in 24 hours and keeps going.
   • The file ships in the package and is linked from its AGENTS.md.
   • Fix: add Schedule.upTo({ times: 5 }) after Schedule.jittered (6 attempts, then the error), or wrap the schedule in Schedule.max([…, Schedule.recurs(5)]), as #L75-L81 does. Putting Schedule.recurs(5) inside the min array does not bound it.

5. @effect/vitest's README Logging example (README.md#L291-L297) says an it.effect test that provides Logger.layer([Logger.consolePretty()]) displays its log, and the intro (#L277) offers a custom logger for this. It does not: it.effect provides TestConsole (internal.ts#L59), so the line lands in TestConsole.logLines.

   • Fix: use it.live, or provide Effect.provideService(Console.Console, globalThis.console).

6. Effect.forkDetach (Effect.ts#L8894-L8896) says the fiber is "attached to the global scope". v4 has no global scope: a detached fiber has no parent and no scope.

   • Fix: "Forks the effect into a new fiber with no parent and no scope. It keeps running after the forking fiber ends, until it completes or is interrupted through its handle."

Names v4 does not have

7. Effect.forkChild (Effect.ts#L8755-L8756) suggests "higher-level methods, such as raceWith, zipPar". Neither exists in v4.

   • Fix: point to Effect.race, Effect.raceFirst, or Effect.all with concurrency.
   • The Sink.raceWith migration note (effect__Sink.yaml#L177, rendered into v3-to-v4.md) also suggests "Effect.raceWith on the run effects".
   • The Sink.raceBoth note (effect__Sink.yaml#L174) suggests Effect.raceBoth, which v4 does not have either. Effect.race or Effect.raceFirst fits both notes.

8. Effect.runFork's example (Effect.ts#L9054-L9060) annotates program as Effect<number, never, never> and the fiber as RuntimeFiber<number, never>.

   • program ends in Effect.as("done"), so it is Effect<string, never, never>.
   • runFork returns Fiber<string, never> (#L9070).

Behaviour not documented

9. ManagedRuntime.make keeps a failed layer build for its lifetime (ManagedRuntime.ts#L316-L330): every later run fails with the first build error and the layer is never rebuilt, so one transient failure on first use disables a long-lived runtime. Its docs (#L245-L246) cover only success.

   • Fix: say so, and point to retrying inside the layer.

10. useAtomSet and useAtom with mode: "promise" or "promiseExit" (Hooks.ts#L185-L194) settle with the atom's next result, not their own write's. When writes to one Atom.fn overlap, the first promise gets the second run's result (concurrent: true: both get the first's). Solid and Vue match.

• Fix: a Gotchas note on the setter.

Where did you find it?

JSDoc in the effect 4.0.5 sources, plus packages/effect/MCP.md, packages/vitest/README.md, ai-docs/ and migration/ (links above). Each line is the same on main at c9a1e72.