# 启动阅读顺序

> 全局类别目录与文档路由在 [[index]],本文件不重复;这里只给 MUST 启动顺序与升级提示。

## 每次任务的启动阅读顺序

1. **[[index]]** — 全局文档地图,确定你的问题该路由到哪篇。
2. **本文件(startup)** — 确认 MUST 启动顺序。
3. **MUST 文档**:
   - **[[design-premises]]** — 唯一的 MUST。四组不可妥协前提(列内核负载形状、Go runtime 四项税、五条贯穿原则、第一天值表示承诺)。任何技术判断前先过这一篇。

## 读完 MUST 之后该读什么(升级提示)

- 要理解**项目是什么、不做什么** → [[project-overview]]。
- 要理解**演进路线 / 阶段门槛 / 月相 tier** → [[evolution-roadmap]]。
- 要理解**值表示 / 内存 / GC 决策** → [[value-representation]]。
- 要理解**宿主如何嵌入、API 与 arena ABI** → [[embedding-contract]]。
- 遇到不认识的术语或想查参照项目 → [[glossary]]。

> 提醒:**P1(crescent 解释器)完整交付 + P2(bridge 分层桥)PB0-PB7 + 后续优化轮 #1-#4 + P3(gibbous/wasm 编译层)PW0-PW10 全卷已收口**(M0-M14 + P1 收尾轮 + P2 单会话冲刺 2026-06-13 + P3 翻译器到端到端总验收冲刺 + PW10 跨层调用税消除轮)。**P2 后续优化轮**(stdlib 白名单 + 阈值校准占位 + sync.Pool (C) + megamorphic;设计文档原称 `P2+`,**不是 P3**)已融入 P2 主交付。**P3 全卷已交付**:PW0 spike 检查(wazero call boundary 36.7ns<150ns)→ 包骨架 + arena 收养 wazero linear memory → 全 38 opcode 除 VARARG 外翻译成 Wasm(直线/算术/比较/控制流 relooper/表 IC inline 跳哈希/CALL·TAILCALL 跨层互调/CLOSURE·CLOSE/数值·泛型 for)→ 线程级 tier 规则(协程不升层)→ gcPending inline 回边零跨层 → V1-V18 端到端总验收(正确性轴层间逐字节 + 四 build + `-race`,性能轴 loop 核 2.58x over 解释器)。**PW10 消除 gibbous→gibbous 跨层调用税:R1/R2/R3/R3.5 + 零跨界 ①/基建-a/基建-b/③a/③b/④-i 骨架/顶层升层 callOnStack 全过线**(Phase 0 spike `spike/p3indirect/` S-A/S-B/S-C 裁定 Arch-2 共享 imported funcref 表而非 rebuild-all + R1 共享 funcref 表基建 + R2 CallInfo→linear-memory 迁移 = 长期延后的 **VS0-e**,4 word/帧 + R3 `call_indirect` 直接分派消 `code.Run` 重入 + R3c-fix 出错点就地标注 + R3.5 host helper `WithFunc`→`WithGoFunction` 消反射装箱 + 零跨界 ① top mirror 字基建 + 基建-a closure slot 缓存 + 基建-b proto cache 段 + ③a savedTop 基建 + ③b emitReturn 守卫快路径 + ④-i emitCall 守卫骨架 + fastCallHits mirror 字 + callOnStack 顶层升层 cl 直接走 enterGibbous + TopLevelUplift 探针 + emit 原语 i64.add/i64.or 保留供未来 ④-ii);**本机 Xeon 6982P 2s×3 count 实测基线(2026-06-16)**:**loop 2.95x(+10% over R3.5 2.67x,③ RETURN 拆帧真实收益)/ table 0.88x / call 0.52x / mixed 0.99x**;**call 0.52x 是 bench kernel 结构性架构边界**——profile `/tmp/call.prof` 实证四 kernel body 含 ReasonUnknownCall(F2-b 静态分析不能确定被调函数不 yield)→ body 不可升 → 顶层升层 + ④ emitCall fast body 均对 bench kernel 无显著效果;**④-ii fast body 未交付**(预估上限 0.57x 仍 <1x,实现复杂度 ~200 行 wasm 字节级 codegen,UAF 高,ROI/UAF 不利留 followup,emit 原语已保留);**PW10 收口为「已完成子里程碑 + 架构边界文档化」**,旧文档所述「四核全翻面」+「剩 R4/R5 待实现」失实须替换;**VS0-e 全量收口(2026-06-16)**——varargs 进栈下区子步 ①~④(`c22798b`/`4e50687`/`966318c`/`ed95020` + 反思 `b9a2c54`),官方 Lua 5.1 真栈布局 `[func | vararg | R(0)..]` 完成,退役 `ci.varargs` Go slice + `th.ciVarargs` 影子;**P4 设计文档集已扩展(2026-06-24)**——单文件 360 行 → 子目录 10 文件 ~8200 行(00-08 + implementation-progress,与 P2/P3 同档详细深度),含 PJ0-PJ11 里程碑预设 + V1-V22 验收口径 + 34 项跨文档回填请求登记(方案 A:P4 自管投机生命周期 / P2 三态枚举不变;原 RJ-8/9/10 撤回),设计稿状态由「架构决策深度」升级为「详细设计深度」;**P3 列内核 loop 形式已超 luajc 档:loop 2.95x over P1 = 7.2x over gopher-lua > luajc 档 4.4x over gopher-lua;但 table 0.88x / call 0.52x / mixed 0.99x 仍 ≪ luajc 档列内核形式——P4 立项动机不在 loop 而在非 loop 形式**;P5 仍是单文件架构决策深度。设计文档集仍是规范源,P1 实现现状与 P3 迁移留口见 `docs/design/p1-interpreter/implementation-progress.md` 对账表;P2 实施现状见 `docs/design/p2-bridge/implementation-progress.md`(PB0-PB7 + #1-#4 全部 ✅);P3 实施现状(PW0-PW9 ✅ + §11 PW9 验收对账 + §12 PW10 R1-R2 + §13 R3+R3.5 + §14 零跨界 RETURN 拆帧 + §14.8 ④-i + §14.9 顶层升层 + §14.10 ④-ii 架构边界 + 回填请求收口表 RW-1~11)见 `docs/design/p3-wasm-tier/implementation-progress.md`;**P4 实施现状(2026-06-28 多 PJ 已完成)见 `docs/design/p4-method-jit/implementation-progress.md`**(PJ0 包骨架 + PJ1 spike 检查 + PJ2 投机三形式 + PJ3 FORLOOP 字节级 inline 超 luajc 档 + PJ4 表 IC 完整六路径 + PJ5 CALL void 220 + TAILCALL 102 + SELF inline 完整 0..7 参 + p4SpecState 子状态机骨架 + PJ7 接上 ~25 类形式 + PJ8 arm64 字节级模板矩阵完整 + Compile 端接上 + PJ11 luajc 档突破 ✅;**PJ10 通用 per-op 翻译器初版交付(2026-06-30,21 commits / 80 e2e 全过)** ✅:Go 端回放 + 占位 mmap stub 物理路径(设计稿 §3 native amd64 multi-BB CFG emit 是性能前提非语义前提,留 followup);35/38 opcode 接住(VARARG 设计永不接 / JMP/TEST/LOADBOOL C!=0 需真 CFG 留 followup);**反思关键判据**:正确性 floor(语义覆盖 = Go 端回放)与性能 ceiling(native CFG emit)拆分,stop-hook 升压时先 profile/scope-check 区分「可达只是还没做」(PJ10 case)vs「真的不可达需止损」([[p3-pw10-architectural-ceiling-round]] PW10 case),见 [[2026-06-30-p4-pj10-perop-translator-round]];**PJ10 native emit 接上(2026-07-01,分支 `feat/pj10-native`,~20 commits)** ✅:35 opcode 双架构 emit + inline 18 op mmap-safe 子集(MOVE/LOADK/LOADBOOL/LOADNIL/ADD/SUB/MUL/DIV/NOT/EQ/LT/LE/TEST/TESTSET/JMP/FORPREP/FORLOOP/RETURN,mmap+morestack 物理不兼容硬约束)+ arch-aware `fixupKind` label resolver(amd64 rel32 / arm64 B26 / arm64 Cond19)+ `PreferNative` 多 BB + big-BB(非 entry)收窄门(精确匹配 shape-spec 打不着形式,防抢 25 个 PJ3/5/7 已调优测试)+ execute() TAILCALL case 内 tail-call gibbous dispatch(commit `0adaae6`);**V15b heavy 三本 P4 native > P3 wasm 达标**(HeavyArith 6.5x / HeavyRecursion 2.4x / HeavyFloatloop 3.0x,10 iter × 3 samples,amd64);V14 luajc 档无回归;arm64 runtime e2e 留 CI followup(需 linux/arm64 host,QEMU 不支持 mmap RWX→RX);反思见 [[2026-07-01-p4-pj10-native-round]];**PJ10 must-beat-P3 op 集扩面(2026-07-02,分支 `feat/p4-beat-p3`,30 commits `dc9baf0..79bd6dc`)** ✅:**exit-reason 协议**(`jitCtx.exitArg0` 打包 `(helperCode, a, b, c, pc)` + `ExitInlineHelper` RET + Go 端 `nativeCode.Run` dispatcher 循环)解 mmap+morestack 物理不兼容,opSupported 从 18 op(mmap-safe 子集)扩到 amd64 上覆盖 CALL(密度门 `totalOps/callCount>=16`)/ SETTABLE / NEWTABLE(IC gated)/ UNM / GETUPVAL / SETUPVAL / GETGLOBAL / SETGLOBAL(NodeHit-IC gated + inline gen-check 快路径 + 18-bit Bx 拆两 9-bit payload)/ 多值 RETURN(HelperReturn 终结);**三 fuzz 驱动正确性收口**:x86 SSE arith NaN 结果与 NaN-box tag 空间别名(inline arith 加 result guard 路由 `host.Arith`)/ `insertNewKey` Brent 重定位改 slot 但没 BumpGen(`internal/crescent/rawtable.go`,解释器 per-access 复验掩盖,gen-only inline 快路径立刻 UAF——**invariant 强度由最严 consumer 定义**)/ LT/LE inline 缺 IsNumber 守卫;**bridge/analyzer 三改**:safe stdlib alias dataflow 追踪(`funcState.localAliasAsts` 记 AST 非 name,`AnalyzeProtoWithOuter` 加 `outerAliases` + visitor `safeAliases` 处理 reassignment/shadowing)/ `MinPromotableLener` 可选接口(P4 实测 fixed Run 成本 ~111ns → 地板停 10)/ `considerPromotion` forceAll retry window;**性能**:25/27 P4-vs-P3 对基准 ≥+2%(多在 +10%~+85%),fannkuch 5.8ms→0.6ms,nbody 升层后 P4 44.2ms 赢,README perf 表整节更新;**已知 followup**:issue #37 arm64 exit-reason port、issue #39 P3 nbody 回归(共享 analyzer alias 改进副作用,43.5→89.7ms;per-backend 回归实证)、task #57;反思见 [[2026-07-02-p4-beat-p3-opset-round]];arm64 exit-reason port + archSupportsSpec=true 物理 runner 真的打开 + 段内 EmitCallInline + OSR exit 接上 + PJ9 双架构差分套留下一批;**其后状态推进(详 index.md P4 文档集节 + `p4-method-jit/implementation-progress.md` §14.6-§21)**:arm64 exit-reason 端口已收口(2026-07-03)、amd64+arm64 seg2seg CALL 分派已交付(2026-07-06)、opSupported 接受面经 #52/#68/#69 多轮扩展后 **issue #52 已收口(2026-07-09,PR #99)——TAILCALL/TFORLOOP/CLOSURE/CLOSE 双架构接入,白名单只剩 VARARG 一个永久设计门**,并顺带修复共享三层的 doTailCall 尾调用 host 函数丢多返回值存量 bug;**跨 arch CI(2026-06-29 PR #27)**:linux/arm64 检查翻 true ✅ + darwin/arm64 codepage 真实现(jitcgo 子包 forward 模式保主库零 cgo)+ macos-latest M1 接入 CI 安全子集,真 execute SIGSEGV 留 followup PR Mac 物理机调试,darwin/arm64 检查暂 false)+ 34 项 RJ 回填请求,方案 A)。设计文档集入口与路由见 [[index]] 的「设计文档集路由」节。**cgo oracle 差分 fuzz 轮(2026-07-12,PR #128)**:新增 `internal/oracle` in-process cgo-embedded PUC Lua 5.1.5(build tag `wangshu_oracle_cgo && cgo` 门控,默认 build 零 cgo)+ `FuzzOracleDiff` 差分 fuzz + 系统性 argsweep,一轮扫出并修复 35 处 P1 vs PUC 语义分歧(字符串共享 metatable / `tonumber` C99 `strtod` 接受面 / 表构造器字段源码顺序 / `string.format` C sprintf 语义等),PR 门禁 oracle-smoke + nightly p1 腿 45 分钟长时间运行,详见 index.md 工程化机制节与反思 [[2026-07-12-cgo-oracle-fuzz-round]]。
