Vitro 后端独立化与 wasm32 白箱化设计计划

现状注记（2026-10-07）：本文为 2026-09-11 时点的定位转型记录与 Phase 0~3 路线原件——排期权威已让位 MoonBit迁移总计划（2026-09-18 起）；路线实质演进：Phase 0 切割已执行、Phase 2a wasm 白箱 → wasm-gc 单出口（S7 gateway）、Phase 2b/3 capi 二三批 → U2 拍板裁不做（见wasm多实例并发模型与U2拍板）；「C/C++ 子集」表述中 C++ 已裁砍（2026-09-20）；所引 Rust 设施随 2026-10-05 删区退役。保留为定位决策档案。 记录日期：2026-09-11 决策依据：2026-09-06 全面代码审阅报告（docs/current/07-质量与裁定/代码审阅与修复追踪20260906.md）、SharpTutor 三个 Issue（A/B/C，2026-09-07）、前端切割战略讨论、wasm32 冒烟实测（2026-09-11） 取代：CIDE_MOBILE_TEACHING_THREE_LANGUAGE_PLAN.md 的"移动端优先"定位（该文档已于 2026-09-11 归档至 ../archive/ARCHIVE_CIDE_MOBILE_TEACHING_THREE_LANGUAGE_PLAN.md） 核心定位转型：从"移动端教学编辑器"到"教学 C/C++ 子集参考执行引擎（白箱）" 现状注记（2026-09-27）：本文为定位转型决策记录（宪法层）。其后两次演进未回写正文、以注记承接：① MoonBit 迁移（2026-09-18 起，总计划）——本文 §6 的 Rust 侧排期让位于总计划 S 系列；② U2 拍板（2026-09-19，wasm多实例并发模型与U2拍板）——§5.3 capi 第二/三批与 §6 Phase 2b/3 裁不做（详见各节注记）。

0. 决策摘要

1. 背景与动因

1.1 审阅报告的结构性结论

2026-09-06 全仓库审阅（137 条发现）完成后，已完成四批修复（详见报告第 0 节追踪表）：

• 第一批崩溃止血（8 项 P0）：递归深度防护、自含 struct 环检测、算术溢出家族、catch_unwind、乘法溢出、apply_fix 中文 panic；
• 第二批 CI 门禁（4 项 P0）：shadow 退出码 + clang 预检 fail fast、三层对账带牙齿——门禁化当天暴露 4 例被恒绿掩盖的存量差异；
• 第三批 codegen soundness（10 项）：全局初始化位模式、类型化自增、char 字节宽度、嵌套赋值槽位、static 隔离、ULL、enum 折叠、逻辑规范化；
• 提前插入的教学检测（V-P1-6/12/13）：栈缓冲区溢出 E3070、无效 free 三场景诊断、scanf 字符流化 + 第四批 Flutter 首批。

修复过程验证了两个关键事实：

1. 前后端接缝本来就是干净的——四批修复全部在后端完成，五层测试防线独立验证，未碰 Flutter；
2. 问题密度分布高度不均——后端问题修完即收敛（防线全绿、clippy 零警告），前端 30 条几乎全是架构级（渲染管线缓存、巨型 IdeState、自研编辑器 IME），需要的是重构而非修补。

1.2 现场证据：移动端取舍拖累桌面端

实际使用反馈确认：软键盘 IME、手势交互、触控目标（审查 P2 记录 <44px、无 Semantics）在移动端持续出问题；为兼容移动隐喻（悬浮球呼吸动画、小屏 Tab 布局）付出的设计折中直接拉低桌面体验。手机适合"看"（时间旅行回放、可视化），不适合"编辑"——而"看"恰恰是 wasm32 + Web 前端天然覆盖的场景。

1.3 外部信号：SharpTutor 三个 Issue

第三方教学 IDE（SharpTutor，WPF/.NET，三进程架构）主动提出把 Vitro 后端作为 C/C++ 执行引擎接入，并提交了三个高质量 Issue（复现步骤、对照用例、根因分析全部核实无误）：

• Issue A（bug，教学阻断）✅ 已修复（2026-09-11）：scanf 格式串空白指令不跳白——"%d %c %d" 读 3 + 4 时 %c 捕获空格。核实补充：sscanf 同样中招，根因在共享的 parse_scanf_specs 只提取 % 转换符、丢弃格式串空白字符，scanf/sscanf/fscanf 全族同病。锚点：vitro_vm/src/host/io.rs + parse_scanf_specs。修复：解析结果改为有序项序列 ScanfItem::{Spec, Whitespace}，空白指令只跳白不取参，参数计数按 Spec 项数统计。
• Issue B（bug，两个根因已定位）✅ 已修复（2026-09-11）：lambda 调用缺陷——B1 立即调用 [](..){..}(2,3) 编译错（vitro_typeck/src/expr/call.rs:100 的 lambda 分支依赖 lookup_var，Lambda 表达式节点查不到落到 :197 兜底）；B2 任何函数实参位置调用 lambda 运行时 StoreLocal 越界（补充发现：不限 printf，自定义函数同样触发；症状与审查报告 §7.2-7 临时槽位家族三起历史 bug 同构）；B3 :197 误用 E3045_CompoundAssignType 报调用错误（建议文本串行的真因，非 error_catalog 问题）。修复落点：typeck resolve_call_ptr 增加 Lambda callee 分支且与变量形式共用 rewrite_lambda_call（消除双轨）；新增错误码 E3066_CallNonFunction；codegen 新增 is_lambda_closure_type 单一判定——lambda 变量槽位与闭包对象保底 4 字节（B2 实测根因：无捕获闭包 size=0，帧内无槽位，StoreLocal 冲出 1MB 线性内存），实参一律按 1 word 地址压栈（双字段捕获闭包曾多压 1 word 致参数错位）。
• Issue C（提案）：为 headless 消费者提供机器可读边界。关键事实：capi 路线已有生产级先例——shadow 驱动（初为 Python ctypes，2026-09-13 起 Go 版 scripts/shadow_verify）自始就直调 C ABI，截至当日跑完 671 个用例。提案实质是"把已验证的边界补全"，不是新建边界。

结论：外部消费者已经出现，后端作为独立组件的定位是被需求推着成立的，切割是把这个事实固化。

2. 新定位：教学 C/C++ 子集参考执行引擎

定位扩展（2026-09-12 同步声明，CSharp前端引入计划.md §11 待办①）： 在 C/C++ 主轴之上新增 C# 教学子集作为第二前端（SharpTutor 锚定，启动时序 与批次见 CSharp前端引入计划.md）。本文件的 架构纪律（三出口一核心、防线体系、行为资产清单）对 C# 前端同等生效。

类比：quickjs 之于 JS 教学/嵌入——小、白箱、可嵌入、行为与标准对照诚实。

2.1 保持不变的资产

• 五层测试防线与"Golden 只能来自 Clang"原则；
• 教学诊断体系（错误码 + 修复建议 + 知识卡片）；
• 安全检测（E3070 栈溢出、E3060/E3061 UAF/Double-Free、E3072 循环包含、无效 free 三场景等）；
• C/C++ 教学子集及 *_FAILURES.md 诚实记录文化；
• 时间旅行/统一模式引擎（Phase 13 起）。

2.2 三出口一核心架构

vitro 引擎核心（Rust workspace，禁止平台 API 耦合）
│
├─ native cdylib / C ABI（capi）
│    第一消费者：vitro_cli、scripts/shadow_verify.go（已退役）（capi 直调，685 用例生产验证）
│    外部消费者：SharpTutor（.NET P/Invoke 子进程）、Python 工具链
│
├─ wasm32-unknown-unknown（.wasm + 薄 JS/TS 绑定）
│    浏览器前端（社区）、在线教学演示、移动浏览器"看"场景
│    冒烟已实证：零修改构建，C API 全链路 + E3070 在 wasm 下工作
│
└─ vitro_cli serve（JSON-lines 会话模式，新增）
     headless 交互：step/seek/breakpoint 的脚本化消费
     实现必须复用 capi 同一套入口函数——三出口一套语义，禁止第三套实现漂移

架构纪律（写进 AGENTS.md 编码约定）：

1. 新能力一律先落"语言中立 Rust 层"（session_api / engine::session_ops；原 flutter_bridge 已随重构批次 R2 整删），三个出口只做薄包装；
2. 复杂返回结构（StepPayload、内存区域、事件流）过边界统一走 JSON 字符串序列化，不搞扁平结构体数组（性能换稳定性与版本容忍度；ctypes 消费已证明字符串边界够用）；
3. capi 是公共 API，承诺即契约——补全同时引入 vitro_abi_version()。

2.3 移动端决策记录

• 放弃：Android 原生（cargo-ndk 双 ABI、adb/logcat 流水线）、移动交互隐喻；
• 保留：不做删除性动作——CideFlutter/ 整体迁出本仓库时按现状带走（社区若接手 Flutter 前端可用），本仓库 CI/脚本/文档全部去前端化；
• 覆盖"看"场景：wasm32 + 任何 Web 前端在移动浏览器天然可用；
• 诚实记录：这是战略转向，与立项愿景（移动教学）不同，原因如 §1.2。

3. 交互资产重构：协议先行

3.1 资产盘点（从 107 个 Dart 文件提炼，迁移时固化）

3.2 两层解耦：协议层 vs 引擎层

协议层（对外，Phase 1 内定稿 v0.1，SharpTutor 参与回放校验）——docs/spec/ 下定义语言中立 wire format：

2026-09-11 修订：schema 定稿从 Phase 3 前置到 Phase 1——第一批 vitro_step_next_json 的输出即 StepPayload，协议不可能晚于消费它的 API（SharpTutor 评审论据，已采纳）。CoW 等引擎内部优化仍以 schema v0.1 定稿为前置。

• StepPayload 稳定 schema：步号/行号/函数 display_name（教学可读）与 mangled 双字段/变量快照/输出增量/事件流（含差分编码 StepPayloadDelta 的既有机型）；
• 指针四状态（Valid/Freed/Null/Dangling）与 accessed_vars 读写的枚举值文档化；
• seek 语义（回退到第 N 步时各视图如何联动的一致性契约）+ frameCache 窗口语义文档化（窗口 2000 帧 / 驱逐最早 20% / 越窗 seek = 检查点恢复 + 正向重放）；
• 断点订阅、内存区域查询（kind: global|stack|heap + status + alloc_line，见 §5.3 第二批）、热力图查询的请求/响应格式；
• schema 版本化：字段只增不改语义，废弃走双写过渡期。

引擎层（对内，协议稳定后独立优化）——对应审查报告 §7.3-12/13 与 V-P1-9/4：

• 时间旅行每步全量 1MB memcpy 的 O(n²) 降为"最近检查点 + 脏页（MemoryImage::Delta 已有 4KB 分页机制）+ output/trace 截断式恢复"；
• 快照边界完整化：VFS（snapshot_files/restore_files 已存在未接线）、local_sym_map、伪时间（time() 改 step 派生确定性时钟）纳入快照闭环，文档化不可恢复项清单。

顺序纪律：schema 定稿 → 引擎 CoW。 协议与内部表示解耦后，两边互不阻塞。

3.3 vitro_cli serve 会话模式设计要点

• JSON-lines（NDJSON）：每行一个请求/响应，天然流式、可 jq、任意语言可消费；
• 请求带 id 字段做关联（异步竞态对账）、错误帧与响应帧同构（{"id":n,"error":{...}}）、提供 session.reset（长寿命防抖进程复用场景，避免高频重启进程）——SharpTutor 评审新增，已采纳；
• 会话生命周期镜像 capi：session.create / session.reset / compile / run / step.next / seek / breakpoints.set / memory.regions / payload.get / session.destroy；
• 与 capi 共用入口函数（见 §2.2 纪律 2）；
• 输出走结构化通道（OutputKind::Stdout/Stderr/Note + capi vitro_get_program_output* / vitro_get_engine_notes*）—— 原计划"复用 shadow 的清洗规则单一来源"已被更彻底的方案取代：审查 E-P1-5 的根因是引擎把程序 stdout 与 引擎附注写进同一条字节流，清洗规则散落十余处且会在程序打印同类文本时误删真实输出，故废除清洗、 改为源头打标。✅ 已完成（2026-09-11），详见 代码审阅与修复追踪20260906.md 第 5 条。

4. wasm32 白箱化：冒烟实证与路线

4.1 冒烟结果（2026-09-11 实测）

两个设计红利的兑现：VFS 内存沙盒使"无真实文件系统依赖"（wasm 移植头号死穴不存在）；catch_unwind 的 wasm32 cfg 预铺设直接生效（附带记录：wasm 下统一模式入口无 catch_unwind，panic 走 abort，为已知差异）。

4.2 唯一阻碍点与修复

实例化要求 __wbindgen_placeholder__ 等 import——flutter_rust_bridge 生成代码的 wasm-bindgen 残留。冒烟以 Proxy stub 证实 C API 路径完全不触碰它们。

修复：lib.rs 中 FRB 模块（frb_generated、api 层）加 #[cfg(not(target_arch = "wasm32"))] 门控——与前端切割同构的天然动作，小时级。冒烟脚本位于 %TEMP%/wasm_smoke/（smoke2.js、smoke_e3070.js），固化为 scripts/wasm_smoke/ 后进入 CI。

4.3 体积与优化（可选，后置）

3.75MB → 目标 2MB 内：wasm-opt（-O --strip-debug）+ LTO + opt-level = "z" 评估 + wee_alloc/默认分配器对比。教学场景一次加载后缓存，体积非首要矛盾。

5. 切割清单（Phase 0 执行手册 · ✅ 已于 2026-09-11 执行完毕）

以下清单保留为执行记录与验收依据；逐项落地结果见 CHANGELOG.md [Unreleased] Removed 段。

5.1 仓库拆分

5.2 许可证与治理

• 全仓库换 MIT（LICENSE + Cargo.toml license 字段）；
• 依赖许可证盘点：cargo deny（或手工 cargo tree 全量过一遍）确认传递依赖无 GPL 类污染，盘点结果记录入档；
• vitro_abi_version() 引入 + capi 变更日志（语义化版本：加函数=minor，改签名/语义=major）；
• FRB 生成代码随前端走，本仓库删除 flutter_rust_bridge 依赖（这也是 wasm 门控的一部分）。

5.3 capi 补全分批（Issue C 落地方案，已按 SharpTutor 评审修订，见 CAPI评审回复与实现状态.md）

横切契约（全部批次适用）：复杂返回 JSON 字符串 + rust-alloc 所有权（vitro_free_string 释放，废弃 caller-buffer 双轨）；所有新入口 catch_unwind；状态码 0=成功/负数=入参错误/正数=领域状态（1=trap、2=waiting_input）；Session 指针句柄非线程安全（跨线程需调用方同步）；UTF-8 输入输出契约。

运行时保险丝契约（SharpTutor 评审新增）：max_steps 与调用栈深度上限为会话级配置（教学内容 = 可控地撞上限并拿教学 trap，而非无限等待）；杀进程即安全退出（VFS 全内存、无文件锁/临时目录依赖）；JIT 与断点/热力图完整性从 V-P1-2 提级为行为契约（含断点的循环排除出 trace 编译，验收含全路径回归用例）。

6. 阶段规划（已按 SharpTutor 评审修订，2026-09-11）

排序修订说明：SharpTutor 建议 wasm 完全后置于第二批；上游采纳"schema 提前"但 wasm 改为并行而非后置——wasm 是社区前端生态的冷启动开关（浏览器 demo 承载"五分钟跑通"承诺），且与第二批无模块冲突。详见 CAPI评审回复与实现状态.md §7。 失效注记（2026-09-27）：Phase 2a（Rust wasm 白箱）→ 已由 MoonBit wasm-gc 单出口取代（总计划 F-5，MoonBit 侧 S7 gateway 片）；Phase 2b capi 第二批 → 已裁不做（U2 拍板）；Phase 3 时间旅行 CoW → 已被 2026-09-22 性能裁定取代（checkpoint + 写集 undo，见性能探究实录③）；完整 step 派生伪时钟 → MoonBit host 已以确定性时钟（恒 0）落地。本表保留为 2026-09-11 原始排期存档。

Issue A/B 可单独提前：与切割无依赖，纯后端修复 + 回归测试，半天量级。✅ 已于 2026-09-11 完成（A 与 B1/B2/B3 全部修复并进回归防线，详见 CHANGELOG [Unreleased]）。

Phase 1 实现进度（2026-09-11）：

• vitro_cli serve JSON-lines 会话模式 ✅ 已落地（native/src/bin/vitro_cli.rs::cmd_serve）——id 关联 / 错误帧同构 / session.reset / 与 capi 共用同一套入口语义；
• 语言中立层提炼 ✅ 部分落地：新增 native/src/session_api.rs，capi 第一批的 JSON 结果构造全部下沉，capi 与 serve 共用同一实现（防三出口漂移，纪律 §2.2-2）；
• StepPayload schema v0.1 ✅ 文档发布：docs/spec/STEP_PAYLOAD_SCHEMA_V0_1.md（含回放场景校验记录；字段冻结由 native/tests/step_payload_schema_v0_1_test.rs 机械保证）；对端三组回放场景仍待 SharpTutor 执行；
• 隔离预算会话配置 ✅ 经 capi（vitro_set_quarantine_budget）与 serve（config.set）双出口暴露。

6.1 验收标准（每阶段，已按评审补充）

• Phase 0：仓库无 Flutter 依赖可完整交付；防线全绿；LICENSE/README/AGENTS 就位；
• Phase 1：SharpTutor 用 capi 第一批（含 deterministic 最小形态）+ serve 跑通三进程架构集成，其 15 用例冒烟集全绿；StepPayload schema v0.1 文档发布（含双方回放场景校验记录）；重复编译内存有界固化为回归断言（实测基线：10000 次交替编译 RSS 平台期）；Issue A/B 回归用例进 crash_regression_tests.rs ✅（2026-09-11 已完成，10 个用例，Expect 值取自 Clang/Clang++ 实测 Golden）；
• Phase 2a：scripts/wasm_smoke/ 进 CI；社区用户 npm i vitro-wasm 五分钟跑通 hello world + 一次 E3070 演示；
• Phase 2b：内存地图三段式（global/stack/heap + freed 保留可见）经 SharpTutor WebView2 消费验证；错误码 JSON 导出 + 已知差异机器可读化上线；
• Phase 3：协议 schema 增量演进（只增不改语义）；10 万步程序的 seek 延迟较全量快照方案有量级改善（基准：benches/unified_perf_baseline.c，当前约 18,500 步/秒）。

7. 风险与诚实记录

1. 协议设计是单向门：StepPayload schema 发布后改语义成本极高，Phase 3 定稿前必须用现有 frameCache/StepStreamBatch 的真实消费场景回放校验；
2. 三出口漂移风险：serve 必须复用 capi 入口（纪律已在 §2.2），否则重蹈"typeck 与 codegen 双轨语义"覆辙（审查 §7.2-8 的既有教训）；
3. 前端真空期：切割后到社区前端成熟前，本项目自身无 GUI——vitro_cli（compile/run/step/unified）是过渡期唯一交互形态，其体验需要维护好；
4. SharpTutor 依赖协调（✅ 已完成，2026-09-11）：capi 第一批签名经 SharpTutor 完整评审并达成一致，逐条结论与六个开放问题的回答见 CAPI评审回复与实现状态.md（含三项实证：重复编译内存有界、alloc_line 已存在、frameCache 越窗行为；该档已归档——capi 后续批次经 U2 拍板裁不做，见《出口分档与宿主策略.md》）；其 §8 对等承诺（15 用例冒烟集 / capi/serve 骨架 PR / schema 回放场景）附 review 基线已接受；
5. wasm 已知差异：统一模式 panic 无 catch_unwind（abort）；time()/clock() 真实墙钟破坏重放确定性的存量问题（V-P2 记录）在 wasm 下同样存在——Rust 侧随 Phase 3 裁停冻结不修，MoonBit 侧已以确定性时钟（恒 0）随 host 落地；
6. 遗留 P1/P2 清单不因切割作废：审查报告 V-P1-1~14、T-P1 剩余项等仍按报告优先级排期，本计划不替代既有修复路线。

8. 与既有文档的关系

• 代码审阅与修复追踪20260906.md：继续作为修复进度权威追踪（第 0 节）；
• CAPI评审回复与实现状态.md：capi 签名定稿的评审依据（SharpTutor 诉求逐条回应 + 开放问题答案），实现 §5.3 第一批时对照执行；
• ../archive/ARCHIVE_CIDE_MOBILE_TEACHING_THREE_LANGUAGE_PLAN.md：移动端定位部分被本文档取代（2026-09-11 已归档），三语言服务目标（C/C++/信）不变；
• C语言子集规范.md / C++子集规范.md：子集规范不变，仍是行为契约；
• CLI使用手册.md：Phase 1 扩展 serve 命令后更新；
• 各 *_FAILURES.md：继续作为防线 5 双向监控的事实源（Phase 2b 错误码机器可读导出后与代码常量共同作为事实源）。