项目接续文件：OPFS/WASM hard block 移植优先级建议

生成时间：2026-06-19 CST

本文件接替 `text22.txt` 的“另开 milestone”建议，专门回答：

```text
在基于 OPFS、WASM 的数控系统仿真中，
L4-PYTHON-REMAP、L4-TOOL-DB、L4-USER-M-PROCESS 哪些可以移植，
以及应该先移植哪一个。
```

重要边界：

```text
本文件是 future runtime milestone 建议，不改变 text22.txt 的当前阶段铁律。
当前阶段仍不得解锁 L4-PYTHON-REMAP / L4-TOOL-DB / L4-USER-M-PROCESS；
Node inventory baseline 仍保持 executed=28 passed=28 skipped=131 unexpected_fail=0；
promotion_allowed 仍必须保持 0。
```

一、简要结论

三类 hard block 都可以“部分或项目定义下完整”移植到 OPFS/WASM 环境，但可移植方式不同。

推荐优先级：

```text
1. L4-TOOL-DB
2. L4-PYTHON-REMAP
3. L4-USER-M-PROCESS
```

建议先移植 `L4-TOOL-DB`，原因是：

- 当前只有 1 个 inventory row：`axis/db_demo/base.ngc`；
- 协议边界清晰：`DB_PROGRAM`、`v2.1`、`g`、`FINI`、`l`、`p`、`u`；
- OPFS 与 tool DB flat-file persistence 天然匹配；
- 可用 Worker / WASM Python runtime 隔离 `DB_PROGRAM`；
- 已有 `text20.txt` / `text21.txt` 规划和 machine-readable artifacts；
- 不需要一次性承诺完整 Python remap lifecycle 或 arbitrary external process；
- 成功后能形成第一个 hard-block runtime unlock 的可复用 proof pattern。

二、可移植性判断

| Family | 能否移植到 OPFS/WASM | 推荐优先级 | 主要原因 |
| --- | --- | ---: | --- |
| `L4-TOOL-DB` | 可以，建议先做 | 1 | 协议小、状态明确、OPFS 持久化适配自然、只有 1 个 row。 |
| `L4-PYTHON-REMAP` | 可以，但应分阶段做 | 2 | 覆盖面最大，价值高，但需要 LinuxCNC Python remap lifecycle、prolog/epilog、module loading、interpreter state binding。 |
| `L4-USER-M-PROCESS` | 只建议做受控子集，最后做 | 3 | 浏览器不能运行 arbitrary external process；必须把 external process 收束成 LinuxCNC-owned state transition proof。 |

三、为什么先做 L4-TOOL-DB

`L4-TOOL-DB` 当前 blocked row 是：

```text
axis/db_demo/base.ngc
```

当前阻塞原因不是 G-code 解释器本身，而是 INI 声明：

```text
[EMCIO]
DB_PROGRAM = ./db_nonran.py
```

这意味着 `.tbl` fallback 不能算 pass。必须证明 LinuxCNC tool DB process protocol：

```text
startup handshake: v2.1
get-all: g ... FINI
spindle load notify: l
tool offset notify: p
spindle unload notify: u
flat-file DB persistence
```

在 OPFS/WASM 环境中，推荐定义：

```text
ToolDbProcessPort
```

职责：

- 按 INI 中的 `DB_PROGRAM` 启动受控 runtime；
- 维持 line-based protocol；
- 记录 transcript；
- 将 DB flat file 映射到 OPFS；
- 导出 release/browser diagnostics。

不允许：

- 用 `.tbl` fallback 代替 DB_PROGRAM；
- 用 JS 直接构造 tool semantics；
- 跳过 `tooldb.py` / `db.py` 行为；
- 只靠 browser glue 声称 tool DB pass。

建议 first milestone：

```text
tool-db-opfs-wasm-milestone
```

最小完成定义：

1. Native `ENABLE_TOOL_DB_RUNTIME_PROBE=1` 可在完整 LinuxCNC host runtime 上通过；
2. WASM/Worker 能执行等价 DB protocol loop；
3. OPFS 能保存并恢复 DB flat-file state；
4. transcript 包含 `v2.1` / `g` / `FINI` / `l` / `p` / `u`；
5. browser diagnostics 输出 DB program path、OPFS DB path、transcript hash、state summary；
6. release artifact 标明 `.tbl fallback sufficient=false`；
7. 只有 native + WASM + browser proof 都齐后，才允许考虑把 `axis/db_demo/base.ngc` 从 `SKIP L4-TOOL-DB` 推进。

四、L4-PYTHON-REMAP 的移植建议

`L4-PYTHON-REMAP` 可以移植，但不应该作为第一个解锁对象。

原因：

- 当前涉及 53 个 skip/block rows；
- 覆盖 Python module loading、remap callable、prolog/epilog、NGC-only subpath、interpreter state、HAL/UI/HALUI assumptions；
- 一旦边界设计不严，很容易把 Python runtime 当作 JS/browser-owned CNC semantics；
- 需要比 tool DB 更深地嵌入 LinuxCNC interpreter Python plugin lifecycle。

推荐路线：

```text
先复用 tool DB milestone 中建立的 Python/WASM substrate；
再做最小 Python remap lifecycle fixture；
最后扩大到 family-level inventory。
```

首个 fixture 仍建议沿用已有 artifact 中的计划：

```text
axis/remap/stop-lookahead/nc_files
```

原因是它更适合作为 lifecycle proof：

- 有 Python runtime phase；
- 当前已有 native runtime fixture plan；
- 比完整 tool-change / five-axis Python remap family 更窄；
- 可以先证明 Python module import、callable dispatch、interpreter lifecycle 和 state observation。

Python remap milestone 的完成定义应至少包括：

1. `python-remap-native-runtime-readiness.tsv` host readiness clear；
2. `ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1` native lifecycle probe pass；
3. WASM Python runtime 能复现同一 lifecycle；
4. remap/prolog/epilog callable 来源绑定 LinuxCNC config/source；
5. browser diagnostics 明确 Python runtime mode；
6. 不把 NGC-only subroutine asset 当 standalone main program；
7. 不因为 Python runtime 可运行就批量解锁全部 53 rows。

五、L4-USER-M-PROCESS 的移植建议

`L4-USER-M-PROCESS` 在浏览器中最不适合按 native external process 语义原样移植。

当前代表 row：

```text
axis/vismach/millturn/example.ngc
```

核心阻塞是 external user-M process：

```text
M128 / M129 Tcl scripts
HAL pin state updates
kinstype guard
ini.[xyz].* soft-limit state transitions
```

浏览器/WASM 环境不能安全、通用地支持：

- arbitrary executable spawn；
- native Tcl process execution；
- host HAL daemon mutation；
- unrestricted process side effects。

因此不建议把 `L4-USER-M-PROCESS` 定义成“浏览器运行任意 USER_M_PATH executable”。

可行路线只能是受控子集：

```text
LinuxCNC-owned user-M state transition boundary
```

例如对 `millturn`：

- 读取 config-owned `M128` / `M129` source；
- 绑定 `M428 -> M128`、`M429 -> M129`；
- 证明 `kinstype.is-0` / `kinstype.is-1` guard；
- 证明 `ini.x.*` / `ini.y.*` / `ini.z.*` state target；
- browser 只执行已证明的 state-transition adapter；
- diagnostics 明确 `arbitrary_external_process=false`。

推荐把它放在第三优先级，原因是：

- 成功解锁只覆盖 1 个 row；
- 需要 HAL/Tcl/user-M process state proof；
- 不能形成通用 external process 支持；
- 安全边界和用户期望更容易误读。

六、总体推荐路线

推荐 roadmap：

```text
Phase A：继续保持 text22 lock
Phase B：L4-TOOL-DB OPFS/WASM proof
Phase C：复用 Python/WASM substrate，做最小 L4-PYTHON-REMAP lifecycle proof
Phase D：做受控 L4-USER-M-PROCESS state-transition proof
```

不要反过来做：

- 不要先做 `L4-USER-M-PROCESS`，因为它不是通用 browser process model；
- 不要直接批量做 `L4-PYTHON-REMAP`，因为 blast radius 太大；
- 不要用 `.tbl` fallback 解 `L4-TOOL-DB`；
- 不要用 virtual HAL 或 JS glue 替代 LinuxCNC CNC/runtime 语义。

七、建议的下一步文件/代码工作

如果要开启第一个 hard-block runtime milestone，建议创建：

```text
text24.txt
```

主题：

```text
L4-TOOL-DB OPFS/WASM runtime milestone execution plan
```

内容应包括：

1. `ToolDbProcessPort` API 草案；
2. Worker/Python runtime 选择；
3. OPFS DB file layout；
4. transcript schema；
5. native/WASM/browser proof gates；
6. release diagnostics fields；
7. promotion lock 更新条件；
8. rollback 条件。

八、最终建议

当前问题的直接答案：

```text
都可以研究移植；
第一个应该移植 L4-TOOL-DB；
第二个做 L4-PYTHON-REMAP；
第三个做 L4-USER-M-PROCESS 的受控 state-transition 子集。
```

当前阶段仍不应改变：

```text
L4-PYTHON-REMAP locked
L4-TOOL-DB locked
L4-USER-M-PROCESS locked
promotion_allowed=0
baseline=28/28/131/0
```