原计划的"翻转默认 + 旧形硬报错"不可行:`[键](集合)` 与 `[描述](实现)` 外形相同, 翻转会让 506 处取元静默变义,硬报错又拿不到证据。改为**按文件声明**。 一、per-file markup - frontmatter `markup: occlusion`(或 `标记: 遮蔽`)决定该文件模式 - load.rs 先取模式,用 parse::expr::with_markup(线程局部压栈)包住解析 - 同一进程可同时加载两种模式的文件(imports);MARQDO_MARKUP 仍作进程默认 - 好处:迁移逐文件、可增量、可回滚,不存在半迁移的静默错义 二、`marqdo migrate labels [--write|--json]` 改写规则: [键](集合) → [键](access(集合, "键")) [`名`](集合) → [名](access(集合, `名`)) - [项](集合) → - [项](遍历 集合 为 项) 安全模型:改写 → 重解析 → 证明等价 → 才写 - 原文件按 classic 解析得 AST-A;改写后按 occlusion 解析得 AST-B - 反归一化 B(标签与键同名且 payload 为 access 的遮蔽还原成 Index) - Debug(A) == Debug(反归一化(B))(抹掉行号)才写入,否则原文件一字不动 只改代码行(LineKind::Code);表格行只改 **…** 单元格,散文 markdown 链接不碰; 链式索引由内向外改写,已迁移的有守卫不二次改。 三、access 提升为宿主函数 HostFn::Access(u16 id 212) 与旧取元逐字一致(Map 按键 / List 1-based / 缺键 missing map key); 进 HostFn 是为了两个后端共用同一实现,interp 里的特例已删除。 四、顺带修的两处真实语义缺陷 1. payload 继承外层"文本模式":`f text=[k](access(c,k))` 中 access 不被当调用 → `()` 内永远允许 callee(args) 2. 遮蔽形状判定过宽:`[问候] ([格式化] "Bo")` 误判为遮蔽 → 要求 `]` 后紧跟 `(`,否则落回方括号调用 五、全仓迁移结果 migrate labels: 256 index, 23 loop, 80 file written;0 文件被等价性拒绝; 迁移后 cargo test --release → 604 passed / 0 failed;再跑迁移幂等。 等价性检查先后抓出 4 类改写 bug(表格散文链接、payload 文本模式、链式索引、 遮蔽与方括号调用混淆),每类都是先拦下再修工具,未污染文件。 测试:6 个单测 + 3 个集成(干跑不写盘 / 写入后运行输出不变且幂等 / 等价失败文件不动);全量 604 passed / 0 failed(M3 后 595 + 9);双后端一致。 文档:doc/design/change-m7-migration.md
5.5 KiB
5.5 KiB
变更记录:M7 迁移与版本门(per-file 标记 + migrate labels + 全仓迁移)
| 状态 | Implemented |
| 日期 | 2026-10-22 |
| 里程碑 | M7(occlusion-syntax.md §13) |
| 改动文件 | 新增 src/migrate.rs · src/load.rs · src/parse/mod.rs(expr) · src/host/dispatch.rs · 80 个语料文件 · 测试 |
| 影响面 | 语法模式按文件切换;全仓 256 处索引 + 23 处循环已迁移 |
1. 原计划的问题:同形换义
原设计想"翻转默认 + 对旧形硬报错"。但 [键](集合) 与 [描述](实现) 外形完全相同:
- 翻转默认 → 506 处取元静默变成"遮蔽整个集合",正是文档点名的最坏变更
- 硬报错 → 无法实现:解析器拿不到"这是旧写法"的证据(两种读法都合法)
结论:模式不能全局翻转,必须按文件声明。
2. 新方案:per-file markup:
---
markup: occlusion
---
| 文件 | 解析模式 | [a](b) 的含义 |
|---|---|---|
无 markup: |
classic(进程默认) | 取元 |
markup: occlusion |
纯度 | 遮蔽 |
实现:load.rs 先读 frontmatter 取出模式,用 parse::expr::with_markup(m, …)
(线程局部覆盖,压栈/出栈)包住解析。同一进程里可以同时加载两种模式的文件
(imports!),且 MARQDO_MARKUP=occlusion 仍可作为进程默认。
好处:迁移是逐文件、可增量、可回滚的;不存在"半迁移的静默错义"。
3. 迁移工具 marqdo migrate labels
marqdo migrate labels . # 干跑:列出将改什么
marqdo migrate labels . --write # 实际写入
marqdo migrate labels . --json # 机器可读
3.1 改写规则
| 旧 | 新 |
|---|---|
[键](集合) |
[键](access(集合, "键")) |
[`名`](集合) |
[名](access(集合, `名`)) |
- [项](集合) |
- [项](遍历 集合 为 项) |
access 是新增宿主函数(host_access,id 212),语义与旧取元逐字一致
(Map 按键 / List 1-based / 缺键 missing map key)。它进 HostFn 是有意的:
两个后端共用同一实现,不再有特例分支。
3.2 安全模型:改写 → 重解析 → 证明等价 → 才写
- 原文件按 classic 解析,得到 AST-A
- 文本改写后,按 occlusion 解析,得到 AST-B
- 反归一化 B:把"标签与键同名 + payload 为
access(x, k)"的遮蔽还原成Index - 比较
Debug(A)与Debug(反归一化(B))(抹掉行号,因为插入了 marker 行) - 只有相等才写入;否则原文件一字不动并报告
equivalence check failed
这条校验是真干活的:它先后抓出 4 类改写 bug(表格散文链接、payload 继承文本模式、
链式索引、[问候] (…) 与遮蔽混淆),每一类都是先被拦下、再修工具,没有污染文件。
3.3 只改代码行
用词法层的 LineKind::Code 限定范围;表格行只改 **…** 单元格
(散文里的 markdown 链接 [docs](https://…) 必须原样保留)。
3.4 由内向外
链式索引 [content]([1]([messages](req))) 必须最内层先改,
否则外层改写会让内层的位置失效;已迁移的 [k](access(…)) 有守卫,不会二次改写。
4. 全仓迁移结果
migrate labels: 256 index, 23 loop, 80 file written
- 覆盖
lib/ ext/ examples/ public/ cli/ tests/ - 0 文件被等价性检查拒绝
- 迁移后
cargo test --release→ 604 passed / 0 failed - 再跑一次迁移 → 幂等(只剩刻意保留的 classic 测试样例)
5. 顺带修的两处真实语义缺陷
| 缺陷 | 现象 | 修法 |
|---|---|---|
| payload 继承外层"文本模式" | f text=[k](access(c,k)) 里 access(...) 不被当调用 → 退化成插值文本 |
() 内永远允许 callee(args)(parse_occluded 临时置位) |
| 遮蔽形状判定过宽 | [问候] ([格式化] "Bo") 被误判为遮蔽 |
要求 ] 后紧跟 (;否则落回方括号调用 |
6. 版本门
- 旧写法不再被硬报错——因为无法与遮蔽区分;真正的门是 per-file 声明:
没写
markup: occlusion的文件按 classic 解析,行为不变。 - 需要"禁止新写旧形"的仓库可用
migrate labels干跑做 CI 门禁(有改动即失败)。
7. 测试
| 层 | 内容 | 结果 |
|---|---|---|
| 单元(6) | 静态键 / 动态键 / 嵌套三层 / 已迁移不重写 / 循环 / 非循环 | ✅ |
| 集成(3) | 干跑不写盘;写入后运行输出不变且幂等;等价失败则文件不动 | ✅ |
| 全量 | cargo test --release |
604 passed / 0 failed(M3 后 595 + 9) |
| 双后端 | gold 套件含 bytecode 变体 | ✅ |
8. 变更清单
| 文件 | 变更 |
|---|---|
src/migrate.rs |
新增:改写器、等价性证明、migrate_file / migrate_path |
src/load.rs |
frontmatter_markup + with_markup 包裹两处 parse_source |
src/parse/expr.rs |
with_markup 线程局部覆盖;() 内强制允许调用;occlusion_shape_ahead 严格判定 |
src/host/dispatch.rs |
HostFn::Access(enum / from_u16 212 / from_name / name / required_params / call_host) |
src/main.rs |
migrate labels 子命令 |
src/interp.rs |
移除 access 特例(改用 HostFn,单一实现) |
| 80 个语料文件 | 索引与循环迁移 + markup: occlusion 标记 |
tests/migrate.rs + src/migrate.rs 单测 |
9 个测试 |
doc/design/change-m7-migration.md |
本文件 |