原理：类型如何追踪一切

2.0运行时全景：一个解释器

先建立全局图景。一个 Effect 值本质是一棵描述树（一串 flatMap 步骤）。run* 启动一个 Fiber，runtime 像解释器一样逐步遍历这棵树；遍历到外部依赖时从 Context 取实现；走完产出一个 Exit。后面五节就是放大这张图的各个部件。

2.1惰性与引用透明

Effect 是个值，意味着它引用透明：可以被取名、传递、放进数组、去重。"重试三次"不需要特殊机制——把同一个值跑三次即可；"超时"就是 effect.pipe(Effect.timeout("1s"))，给值套一层包装，得到一个新值。Promise 做不到：它一构造就在飞，你拿到的是进行中的结果，没法"再来一次"。

2.2错误如何被类型追踪

这是 Effect 最核心、也最反直觉的机制。错误是被返回的值，不是被抛出的异常——所以类型系统能看见它。

累积与相减

当 flatMap/gen 把两个 effect 串起来，E 通道取并集：串联 Effect<_, HttpError> 和 Effect<_, ParseError>，得到 E = HttpError | ParseError。恢复算子则做减法：catchTag("HttpError", ...) 把这一项从并集里去掉，catchAll 把整个 E collapse 成 never。所以签名是一份精确、静态可查的"还能怎么失败"清单。

import { Effect, Data } from "effect"

class HttpError extends Data.TaggedError("HttpError")<{ status: number }> {}
class ParseError extends Data.TaggedError("ParseError")<{ raw: string }> {}

declare const get: Effect.Effect<string, HttpError>
declare const parse: (s: string) => Effect.Effect<number, ParseError>

const pipeline = Effect.gen(function* () {
  const body = yield* get          // 可能 HttpError
  return yield* parse(body)         // 可能 ParseError
})
// pipeline: Effect<number, HttpError | ParseError>  ← 并集，自动累积

const recovered = pipeline.pipe(
  Effect.catchTag("HttpError", () => Effect.succeed(0)),
)
// recovered: Effect<number, ParseError>  ← HttpError 被减掉，只剩 ParseError

失败 vs 缺陷：两种性质完全不同的"错"

失败（failure）= 预期内、可恢复，进入 E 通道；缺陷（defect）= 意料外的 bug，不进 E 通道。

只有 Effect.fail(x) 产生的失败才进 E。一个真正 throw 出来的异常（或 Effect.die）是缺陷——E 通道保持 never，因为"枚举所有可能的 bug"是不现实的。两者可以互转：Effect.orDie 把失败降级成缺陷（从 E 移除）；Effect.exit / catchAllCause / sandbox 把缺陷捞成可检视的值。

Cause 与 Exit：比 Error 多保留的信息

一个 fiber 结束时得到 Exit<A, E> = Success(A) 或 Failure(Cause<E>)。注意失败侧装的是 Cause，不是裸 E——Cause 是完整的失败树，能表达 try/catch 结构上表达不了的东西：同时发生的多个失败。两个并发分支都炸了，Cause 用 Parallel 把两个都留着；try/catch 只能抓到一个，另一个被吞。

2.3Layer：编译期的依赖注入

R 通道是一个编译期需求集：每个 yield* SomeTag 往里加一项，每个 provide 去掉对应项。effect 不到 R = never 不能运行——编译器在替你确认"所有依赖都接好了"。运行时这边，Context 就是一个不可变的 Map<Tag, 实现>。

Layer<ROut, E, RIn> 是"如何构建服务"的配方：它能自己有依赖（RIn）和构建期错误（E）。Layer.provide 把一个 layer 接到另一个 layer 上（接线服务之间的依赖），Effect.provide 把构建好的 layer 接到 effect 上。

2.4Fiber 运行时：协作式调度

fiber 是 runtime 模拟的轻量虚拟线程（绿色线程）：不是 OS 线程（JS 单线程），不是 Promise；惰性、可观测、可中断。

runtime 是个解释器，逐步遍历 effect 这棵描述树，flatMap/gen 的边界就是一"步"。调度是协作式的：一个 fiber 一直跑，直到撞上异步挂起点（Effect.sleep、一个 async effect）或主动让出，runtime 才在事件循环上步进别的 fiber。关键在于——因为 runtime 掌控每一步，它能在步与步之间插入检查点。这就是为什么中断既便宜又安全：永远不会在一个同步块中途被打断，不会有撕裂状态、不需要锁。

2.5结构化并发与中断

Effect.fork 把子 fiber 挂到父 fiber 的作用域上。父终止时，子自动终止——"不会有 fiber 在你不知情时还在跑"。要让 fiber 活得比父久，得显式 forkDaemon（全局作用域）或 forkScoped（挂到某个外层 Scope）。这就是"结构化"：fiber 的生命周期像调用树一样嵌套。

中断的机制：Fiber.interrupt 发出信号，runtime 在效应之间的边界观察到它（不会在同步块中途），展开执行栈，按注册的反序运行所有 finalizer / onInterrupt，最后得到一个 Cause: Interrupt(fiberId) 的 Exit。

import { Effect, Console } from "effect"

// acquireRelease：acquire 与 release 都不可中断；release 注册为 scope finalizer
const useConn = Effect.acquireRelease(
  Console.log("① 打开连接").pipe(Effect.as("conn")),  // acquire
  () => Console.log("③ 关闭连接（必跑：成功/失败/中断都跑）"), // release
)

const program = Effect.gen(function* () {
  const conn = yield* useConn
  yield* Console.log("② 用连接做事")
  yield* Effect.interrupt          // 主动中断
}).pipe(Effect.scoped)             // scoped 圈定 finalizer 的生命周期

Effect.runPromiseExit(program)
// 输出顺序：① ② ③，最终 Exit.Failure，Cause 是 Interrupt
// —— 即使被中断，③ 关闭连接也照常执行

2.6跨机制综合：一行代码里五个机制

把五节串起来。看这一行：

const result = fetchWeather("Tokyo").pipe(Effect.timeout("1 second"))
// fetchWeather(city): Effect<Weather, HttpError, HttpClient>
// result:            Effect<Weather, HttpError | TimeoutException, HttpClient>

这一个表达式同时动用了全部五个机制：

1. 惰性（2.1）：result 还是个值，什么都没跑；timeout 只是给原值套了层包装得到新值。
2. 错误类型（2.2）：E 通道自动并入 TimeoutException——签名诚实地多出一种失败。
3. 依赖（2.3）：R 仍是 HttpClient，没 provide 就编译不过、跑不了。
4. Fiber（2.4）：run 时 timeout 把 fetchWeather 与一个 1 秒的 sleep race，各跑在自己的 fiber 上。
5. 中断（2.5）：若 sleep 先赢，fetchWeather 的 fiber 在下一个边界被中断，它的 acquireRelease 清理（关连接）照跑，结果是 TimeoutException 失败、Cause 里带 Interrupt。