docs: 加一篇函数流走向

call-flow.md 讲的是三个阶段各自在做什么，缺的是**函数之间怎么串起来的**——
想改代码、想知道加一层该加在哪，没有一处能查。

docs/flow.md 七张图：

  全景            公开 API → 注册表 / 取 VM / 调用 三条链
  runner 三态     Script / Instance / staticTarget 的 acquire+finish 差别，
                  「同一实例串行」就是 acquire 到 finish 之间一直持着 i.mu
  newVM 内部      为什么 scope 是显式参数而不是从 ctx 嗅
  作用域进 VM      WithScope → vmGlobals → bind → lazyGlobal → freeze 五跳，
                  这是全库最容易看不清的一条链
  invoke 内部     含 defer 的注册顺序（finish → stop → recover，后进先出）
  lookup 三级     exports → ctor 静态 → 全局兜底，解释了 Script.Has 为什么
                  对静态方法也返回 true
  编译链          Prepared 为什么不是优化开关而是正确性要求

写的时候实地核对了每条断言，抓出三处我自己写错的：

  1. 图上把 Bundle → FinalizeBundle 画成两步，实际 Bundle 末尾自己就调了
  2. 把「省 44% 常驻内存」归因给惰性注入——那是关掉 console 的收益
  3. 「只读全局赋值静默失败」只对全局本身成立，freeze 拷出来的嵌套只读属性
     （store.Set = null）实测是抛错的

顺带修一处上一轮改名的残留：engine.go 的注释还指着 lazyglobal_test.go。

README.md

@@ -45,6 +45,7 @@ resource.GetDBTable(user, req.WithPermission(req.ResAll))
 
 | | |
 | --- | --- |
+| [docs/flow.md](docs/flow.md) | **函数流走向**：调用链怎么串的、作用域和扩展从哪一步进 VM、想加一层该加在哪 |
 | [docs/call-flow.md](docs/call-flow.md) | 执行流程：源码怎么变成可执行的、一次调用经过哪些环节、错误怎么分类 |
 | [docs/lifecycle.md](docs/lifecycle.md) | 生命周期：Engine / Script / VM / Instance / 作用域各活多久，状态该放哪 |
 

doc.go

@@ -38,6 +38,9 @@
 // 没有事件循环（定时器、网络、真正的异步都没有）、不提供沙箱隔离
 // （脚本能拿到你放行的 Go 对象，它们的方法是真能调的）。
 //
+// 想看函数之间怎么串起来的（调用链、作用域从哪一步进 VM、想加一层该加在哪），
+// 见 docs/flow.md。
+//
 // # 基本用法
 //
 //	loader, err := esm.NewLoader("app/src")

docs/flow.md

@@ -0,0 +1,291 @@
+# 函数流走向
+
+一次调用从公开 API 走到 goja 要经过哪些函数、作用域和扩展在哪一步进入 VM。
+
+`call-flow.md` 讲的是**三个阶段各自在做什么**（为什么要打包、错误怎么分类），
+这一篇讲的是**函数之间怎么串起来的**——想改代码、想知道加一层该加在哪，看这篇。
+
+---
+
+## 全景
+
+```mermaid
+flowchart TB
+    subgraph 公开API
+        N["jscriptx.New(opts...)"]
+        C["e.Compile(name, src)"]
+        S["e.Script(name)"]
+        EN["e.New(ctx, name, args...)"]
+        SC["s.Call / CallInto / WithCall"]
+        SN["s.New(ctx, args...)"]
+        ST["s.CallStatic / HasStatic"]
+        IC["i.Call / CallInto / WithCall"]
+    end
+
+    subgraph 脚本注册表
+        LL["loadLocked"]
+        CL["compileLocked"]
+        BD["Bundle（含 FinalizeBundle）"]
+        GC["goja.Compile → *Program"]
+    end
+
+    subgraph 取VM
+        BR["s.borrow"]
+        EQ["i.ensure"]
+        BS["s.borrowStatic"]
+        NV["**newVM**（唯一入口）"]
+        LD["s.load"]
+    end
+
+    subgraph 调用
+        CA["callAny / callInto"]
+        IV["invoke"]
+        LK["vm.lookup"]
+        FR["frame.callWith"]
+    end
+
+    N --> S
+    C --> CL
+    S --> LL --> CL --> BD --> GC
+    EN --> S
+    EN --> SN
+    SN --> EQ
+    SC --> CA
+    IC --> CA
+    ST --> CA
+    CA --> IV
+    IV -->|"r.acquire"| BR
+    IV -->|"r.acquire"| EQ
+    IV -->|"r.acquire"| BS
+    BR -->|"池里没有"| NV
+    EQ --> NV
+    BS --> NV
+    NV --> LD
+    IV --> LK --> FR
+```
+
+两个要点：
+
+- **编译和取 VM 是分开的两条链**。`*Program` 是 goja 编译产物，不绑任何 Runtime，
+  所有 VM 共用同一份。所以热更新（重编译）贵，建 VM 便宜——实测 213 μs vs 4 μs，
+  编译占 99.7%。
+- **取 VM 只有 `newVM` 一个入口**。三条路径（池化、实例、静态）都汇到它，
+  作用域注入和 `scoped` 标记的规则才只有一份。这两件事分散过，结果就是
+  `borrowStatic` 漏标了 `scoped`，带作用域的 VM 差点回池。
+
+---
+
+## 谁提供 VM：runner 三态
+
+`invoke` 不关心 VM 从哪来，只认这个接口（`invoke.go`）：
+
+```go
+type runner interface {
+	owner() *Script
+	acquire(ctx) (*vmHandle, error)
+	finish(inst *vmHandle, healthy bool)
+}
+```
+
+三个实现，差别全在「用完怎么处理」：
+
+| | `acquire` | `finish` | 语义 |
+| --- | --- | --- | --- |
+| `*Script` | `borrow` | `release` | 从池借，好的还回去，坏的丢 |
+| `*Instance` | 加锁 + `ensure` | 解锁，坏的置 nil | 独占一个 VM，**锁持到 finish**，所以同一实例串行 |
+| `staticTarget` | `borrowStatic` | 只记 `dropped` | 用完就丢，永不回池 |
+
+所以「同一个实例的调用是串行的」不是靠额外机制，就是 `acquire` 到 `finish`
+之间一直持着 `i.mu`。
+
+---
+
+## 建一个 VM：newVM 内部
+
+```mermaid
+flowchart TB
+    A["newVM(ctx, sc, ctorArgs, noInstance)"] --> B{"sc != nil"}
+    B -->|是| C["extra = sc.vmGlobals()"]
+    B -->|否| D["extra = nil"]
+    C --> E["goja.New()"]
+    D --> E
+    E --> F["SetMaxCallStackSize"]
+    F --> G["**engine.bind(rt, name, extra)**"]
+    G --> H["s.load(ctx, rt, ctorArgs, noInstance)"]
+    H --> I["vm.scoped = sc != nil"]
+    I --> J["*vmHandle"]
+```
+
+`sc` 是**显式参数，不是从 ctx 嗅的**。`Instance` 重建 VM 时要回到它**创建时**
+那个作用域，而不是当次调用 ctx 里的——对一个作用域实例调
+`Call(context.Background())` 不该把它的扩展弄丢。有测试守这条
+（`TestScope_实例重建VM后仍在原作用域`）。
+
+`vm.scoped` 决定 `release` 会不会把这个 VM 放回池子。带作用域的 VM 装着那个作用域的
+扩展，回池就会漏给下一个调用。
+
+---
+
+## 作用域和扩展怎么进 VM
+
+这是最容易看不清的一条链，从 `WithScope` 到 JS 全局变量一共五跳：
+
+```mermaid
+flowchart TB
+    W["WithScope(ctx, ScopeExtensions(st), ScopeGlobals(m), ScopeKey(k))"]
+    W --> SS["ctx 里存一个 *scope<br/>{key, exts, globals}"]
+    SS --> SO["scopeOf(ctx) 取回来"]
+    SO --> VG["**sc.vmGlobals()**<br/>拍平成 map[string]any"]
+    VG --> BI["engine.bind(rt, name, extra)"]
+    BI --> LG["lazyGlobal 逐个注入"]
+    LG --> FZ["首次读取时才 freeze"]
+    FZ --> JS["脚本里的全局变量"]
+```
+
+### `vmGlobals` 的拍平规则
+
+```go
+for _, ext := range sc.exts { g[ext.Name()] = ext.Bindings() }   // 扩展
+for k, v := range sc.globals { g[k] = v }                        // ScopeGlobals 盖扩展
+g["scope"] = map[string]any{"key": sc.key}                       // 身份
+```
+
+扩展交出去的是 `Bindings()` 返回的那张 `map[string]any`——**方法集，不是扩展对象本身**。
+所以脚本看到的 `store` 是一个由 Go 函数组成的对象，那些函数闭包捏着同一个 Go 侧实例，
+这才是「多个脚本共享状态」的实现方式：共享的是 Go 对象，不是共用 Runtime。
+
+`scope.key` 总会有（`WithScope` 不传 key 就随机生成），所以**只要 ctx 里有作用域，
+`extra` 就必然非空**——这也是「有作用域必然要单造 VM」的原因，池里的 VM 没装这些。
+
+### `bind` 的优先级
+
+```mermaid
+flowchart LR
+    A["e.globals<br/>（WithGlobals 白名单）"] -->|"同名时被跳过"| B["extra<br/>（作用域的）"]
+    B --> C["console<br/>（两边都没占用才注入）"]
+```
+
+顺序是刻意的：作用域的东西盖白名单，`console` 只在没被占用时才给。
+`WithLogger(nil)` 关掉 logger 就完全不注入 console。
+
+### 为什么注入是惰性的
+
+`lazyGlobal` 用 `DefineAccessorProperty` 装一个**只有 getter 没有 setter** 的属性：
+
+```mermaid
+flowchart LR
+    A["脚本第一次读 db"] --> B{"cached == nil"}
+    B -->|是| C["freeze(rt, val)"]
+    C --> D["缓存并返回"]
+    B -->|否| D
+    E["脚本没读过 db"] --> F["freeze 从没跑过"]
+```
+
+- **没有 setter** = 脚本改不动。脚本跑在非严格模式下，给只读全局赋值是**静默失败**，
+  不抛错（断言在 `engine_globals_test.go`）。注意这只说全局本身：`freeze` 拷出来的
+  嵌套只读属性（`store.Set = null`）实测是**抛错**的，两种行为不一样。
+- **惰性** = 脚本没读到的全局根本不转换。README 性能一节的内存表是「全都读到」的上界。
+
+### `freeze` 只对 map 深拷贝
+
+```mermaid
+flowchart TB
+    A["freeze(rt, val)"] --> B{"val 是 map[string]any"}
+    B -->|是| C["递归 freeze 每个值<br/>+ defineReadOnly"]
+    C --> D["各 VM 各持一份只读副本"]
+    B -->|否| E["rt.ToValue(val)"]
+    E --> F["**各 VM 共享同一个 Go 对象**"]
+```
+
+这一点常被误解成隔离保证。**放行结构体指针、slice、接口时，各个 VM 拿到的是同一个
+Go 对象**，脚本通过它的方法改到的东西是真改了。扩展走的正是这条路（`Bindings()` 返回的
+map 会被拷，但里面的函数闭包捏着同一个 Go 实例），要跨 VM 共享可变状态就该这么用。
+
+---
+
+## 一次调用：invoke 内部
+
+```mermaid
+flowchart TB
+    A["invoke(ctx, r, fn, args, do)"] --> B{"脚本已关闭"}
+    B -->|是| Z1["ErrClosed"]
+    B -->|否| C["**r.acquire(ctx)**"]
+    C --> D["defer r.finish(inst, healthy)"]
+    D --> E["**inst.lookup(fn)**"]
+    E -->|找不到| Z2["ErrFuncNotFound<br/>+ notFoundHint"]
+    E --> F["**guard(ctx, rt, timeout)**<br/>装超时哨兵"]
+    F --> G["defer stop()"]
+    G --> H["defer recover()<br/>healthy = false"]
+    H --> I["do(frame)"]
+    I --> J["frame.callWith(args)"]
+    J --> K["unwrapPromise"]
+    K --> L{"返回值是 JS 函数"}
+    L -->|是| Z3["ErrValueEscape"]
+    L -->|否| M["res.Export() 或 res.Into(out)"]
+```
+
+### defer 的顺序很关键
+
+注册顺序是 `finish` → `stop` → `recover`，执行是**后进先出**：
+
+1. `recover` 先跑，把 `healthy` 置成 false
+2. `stop` 清掉超时哨兵
+3. `finish` 最后才交还 VM——这时 `healthy` 已经是正确的值
+
+顺序错了的后果是：panic 过的 VM 带着不确定的状态回到池子里。
+
+### `lookup` 的三级查找
+
+```mermaid
+flowchart TB
+    A["lookup(fn)"] --> B{"fn == DefaultFunc"}
+    B -->|是| C["defFn<br/>（export default function）"]
+    B -->|否| D{"exports 上有"}
+    D -->|有| E["实例方法<br/>this = exports"]
+    D -->|没有| F{"ctor 上有"}
+    F -->|有| G["**静态方法**<br/>this = ctor"]
+    F -->|没有| H["全局函数兜底"]
+```
+
+这个顺序解释了两件事：
+
+- `Script.Has("Startup")` 对一个**静态**方法也返回 true——它走的是同一个 `lookup`
+- `HasStatic` 要额外判 `ctor != nil`，就是为了排除最后那个全局兜底分支
+
+---
+
+## 编译链：源码到 *Program
+
+```mermaid
+flowchart TB
+    A["e.Script(name)"] --> B{"缓存里有 && !autoReload"}
+    B -->|是| C["直接返回"]
+    B -->|否| D["**loadLocked**"]
+    D --> E["loader.Load(name)<br/>→ source, version"]
+    E --> F{"version 跟缓存一样"}
+    F -->|是| C
+    F -->|否| G["**compileLocked**"]
+    G --> H{"loader 实现了 Prepared"}
+    H -->|"是（esm.Loader）"| I["源码已打包，直接用"]
+    H -->|否| J["**Bundle**<br/>esbuild 内联 import + 转译 TS<br/>末尾自己调 FinalizeBundle<br/>把 ESM 改写成立即执行函数"]
+    I --> L["goja.Compile → *Program"]
+    J --> L
+    L --> M["*Script{prog, pool}"]
+```
+
+`Prepared` 不是优化开关而是**正确性要求**：打包产物里已经没有 `export` 了，
+再打一遍会被当死代码整段摇空。所以自定义 Loader 如果自己打过包，必须实现它。
+
+---
+
+## 想加一层该加在哪
+
+| 想做的事 | 该动哪 |
+| --- | --- |
+| 给脚本加一个全局对象 | 实现 `Extension`，通过 `ScopeExtensions` 进作用域 |
+| 全进程都有的全局 | `WithGlobals`（走 `e.globals`，被作用域同名项覆盖） |
+| 换脚本来源 | 实现 `Loader`；已自己打包的加 `Prepared` |
+| 多来源叠加 | `Overlay`（后面盖前面） |
+| 自定义回调签名 | `WithCall` + `Caller.Arity`，别改 `invoke` |
+| 改 VM 的建法 | 只改 `newVM`——三条路径都走它 |
+| 加一种新的 VM 来源 | 实现 `runner` 三个方法，别绕过 `invoke` |

engine.go

@@ -207,7 +207,7 @@ func (e *Engine) compileLocked(name, source, version string, prepared bool) (*Sc
 	//
 	// 注意产物里**没有** "use strict"：esbuild 输出 ESM 格式时不加这个指令，
 	// wrapESM 包成 IIFE 时也没加。所以脚本跑在非严格模式下，后果之一是给只读
-	// 全局赋值会**静默失败**而不是抛错（见 lazyglobal_test.go 的断言）。
+	// 全局赋值会**静默失败**而不是抛错（见 engine_globals_test.go 的断言）。
 	//
 	// 想改成严格模式就把这里传 true，但那是行为变更：脚本里任何依赖非严格语义的
 	// 写法（给未声明变量赋值、with、八进制字面量……）都会开始报错。