项目接续文件：L4-TOOL-DB OPFS/WASM runtime milestone 执行计划

生成时间：2026-06-19 CST

本文件接替 `text23.txt`，回答“第一个先做 `L4-TOOL-DB`，具体如何做”。

重要边界：

```text
本文件是单独 hard-block runtime milestone 的执行计划。
不是 text22.txt 当前 evidence-based promotion 阶段的一部分。
在本 milestone 完成前：
axis/db_demo/base.ngc 仍必须保持 SKIP L4-TOOL-DB；
promotion_allowed=0；
baseline 仍保持 executed=28 passed=28 skipped=131 unexpected_fail=0。
```

一、目标

目标不是让 `axis/db_demo/base.ngc` 通过 `.tbl` fallback，也不是用 JavaScript 重新实现 tool semantics。

目标是证明：

```text
LinuxCNC-owned tool DB protocol + DB_PROGRAM behavior + OPFS persistence
可以在 native / WASM / browser proof chain 中成立。
```

最小目标 row：

```text
axis/db_demo/base.ngc
ini=axis/db_demo/db_nonran.ini
blocked=L4-TOOL-DB
DB_PROGRAM=./db_nonran.py
```

必须保留的协议：

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

二、当前已有基础

已有 source/protocol accounting：

```text
wasm-port/build/wasm/sim-configs-inventory/tool-db-process-boundary-summary.tsv
wasm-port/build/wasm/sim-configs-inventory/tool-db-process-protocol-gates.tsv
wasm-port/build/wasm/sim-configs-inventory/tool-db-process-transaction-plan.tsv
wasm-port/build/wasm/sim-configs-inventory/tool-db-process-native-protocol-alignment.tsv
wasm-port/build/wasm/sim-configs-inventory/tool-db-process-native-runtime-readiness.tsv
wasm-port/build/wasm/sim-configs-inventory/tool-db-process-native-runtime-probe-gate.tsv
```

当前 probe 状态：

```text
python3=1
axis/db_demo/db_nonran.py=1
linuxcnc.so=1
tooldb.py=1
linuxcnc=0
milltask=0
halcmd=0
runtime_ready=0
source_proof_ready=1
gate_status=blocked_missing_host_runtime
promotion_allowed=0
```

已有 native probe 入口：

```text
wasm-port/tests/native/probe_tool_db_runtime.sh
```

三、Phase 1：native protocol proof 先闭环

目的：先证明项目记录的 tool DB transaction contract 与真实 LinuxCNC DB runtime 一致。

1. 准备完整 LinuxCNC host runtime。

需要 PATH 上存在：

```text
python3
linuxcnc
milltask
halcmd
```

需要 Python 模块可 import：

```bash
python3 -c "import linuxcnc; import tooldb; print('linuxcnc_tooldb_python_modules=ok')"
```

2. 先跑 readiness，不启用执行。

```bash
wasm-port/tests/native/probe_tool_db_runtime.sh
```

可接受输出：

```text
tool_db_runtime_probe_status=ready_disabled_by_default
```

如果仍输出：

```text
tool_db_runtime_probe_status=skipped_missing_host_runtime
```

则先修 host/container runtime，不改项目 fallback。

3. 显式启用 native runtime probe。

```bash
ENABLE_TOOL_DB_RUNTIME_PROBE=1 wasm-port/tests/native/probe_tool_db_runtime.sh
```

必须看到：

```text
tool_db_runtime_probe_status=runtime_protocol_probe_passed
```

该 probe 必须证明：

- `db_nonran.py` 启动并返回 `v2.1`；
- `g` 返回 `T10..T19` 并以 `FINI` 结束；
- 初始 pocket 是 `tno+100`；
- `p t11 p111 d0.33 z0.11` 后 get-all 能看到状态更新；
- `l t14 p0` 后 `T14` 进入 spindle pocket `P0`；
- `u t0 p0` 后 `T14` 回到 `P114`；
- DB savefile 包含 mutation；
- 输出仍保持 `tool_db_execution_enabled=0`、`tool_db_promotion_allowed=0`。

4. 刷新 inventory artifacts。

```bash
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
```

预期仍不改变 baseline：

```text
executed=28
passed=28
skipped=131
unexpected_fail=0
```

但 tool DB runtime artifacts 应进入 “native proof ready, waiting for Node/browser proof” 类型状态。

四、Phase 2：定义 WASM ToolDbProcessPort

目的：把 native child-process edge 改成可在 WASM/browser 中验证的协议端口。

建议新增抽象：

```text
ToolDbProcessPort
```

建议 API：

```text
createLinuxCncToolDbProcessPort({
  dbProgramPath,
  sourceFiles,
  opfsRoot,
  runtimeMode,
})

start()
writeLine(line)
readLine()
runTransactionPlan(plan)
exportTranscript()
close()
```

职责：

- 按 INI 的 `DB_PROGRAM` 定位 DB program；
- 提供 line-based protocol I/O；
- 记录 transcript；
- 将 DB flat-file 映射到 OPFS；
- 导出 diagnostics artifact。

不允许：

- 解析 `.tbl` 作为 pass；
- JS 直接构造 tool table semantics；
- 跳过 `tooldb.py`；
- 不跑 `db.py` / `db_nonran.py` 回调；
- 只用 fixture transcript 假装 runtime pass。

五、Phase 3：选择 DB_PROGRAM runtime

推荐首选：

```text
Web Worker + WASM Python runtime
```

Worker 内加载：

```text
configs/sim/axis/db_demo/db_nonran.py
configs/sim/axis/db_demo/db.py
lib/python/tooldb.py
minimal linuxcnc Python integration shim
OPFS-backed DB flat file
```

注意：

```text
minimal linuxcnc shim 只能覆盖 DB demo 必需 integration surface，
例如 linuxcnc.command().load_tool_table 的同步边界记录。
不能承载 tool semantics。
```

如果暂时没有 Python/WASM runtime，不要直接改成 JS 版 DB program。可以先做：

```text
tool-db-process-port contract tests
transcript schema
OPFS persistence store
browser diagnostics shell
```

但仍保持：

```text
runtime_execution_ready=0
promotion_allowed=0
```

六、Phase 4：OPFS persistence layout

建议 OPFS 路径：

```text
/machines/<machine-id>/tool-db/db_nonran_file
/machines/<machine-id>/tool-db/transcripts/<run-id>.json
```

必须验证：

1. 初次启动可创建 DB file；
2. `p` / `l` / `u` 后 DB file 更新；
3. 关闭 session 后重新加载仍能读回状态；
4. diagnostics 导出：

```text
db_program_path
opfs_db_path
transcript_hash
db_file_hash
startup_tool_count
mutation_count
tbl_fallback_sufficient=false
promotion_allowed=0
```

七、Phase 5：Node/WASM proof

新增 Node gate 建议：

```text
wasm-port/tests/wasm/node/verify_tool_db_process_port_wasm.sh
```

该 gate 要证明：

- 从 INI 解析到 `DB_PROGRAM=./db_nonran.py`；
- ToolDbProcessPort 可启动 runtime；
- transcript 包含 `v2.1` / `g` / `FINI` / `p` / `l` / `u`；
- OPFS-equivalent store 可 roundtrip DB file；
- `.tbl fallback sufficient=false`；
- 输出 `tool_db_process_port_wasm=ok`；
- 不改 `verify_sim_configs_inventory_wasm.sh` baseline。

八、Phase 6：browser diagnostics proof

新增 browser gate 建议：

```text
wasm-port/tests/browser/verify_tool_db_process_browser.sh
```

browser diagnostics 应显示：

```text
tool_db_runtime_mode=wasm-tool-db-protocol-worker
db_program=./db_nonran.py
opfs_db_path=/machines/<machine-id>/tool-db/db_nonran_file
protocol_transcript_ready=true
opfs_persistence_ready=true
tbl_fallback_sufficient=false
promotion_allowed=0
```

UI 只展示状态和 transcript evidence，不实现 tool semantics。

九、Phase 7：release artifact / promotion lock

在 native + Node/WASM + browser proof 都通过前，release artifact 只能显示：

```text
L4-TOOL-DB locked
tool_db_native_protocol_ready=<0|1>
tool_db_wasm_protocol_ready=<0|1>
tool_db_browser_protocol_ready=<0|1>
promotion_allowed=0
```

只有三层 proof 都为 ready 后，才能另起变更更新：

```text
runtime-boundary-promotion-readiness.tsv
runtime-boundary-promotion-blockers.tsv
runtime-boundary-post-native-pass-gates.tsv
blocked-runtime-promotion-lock.tsv
promotion-candidates.tsv
```

即使到那一步，也要单独 review 是否允许：

```text
axis/db_demo/base.ngc: SKIP L4-TOOL-DB -> PASS
```

十、验收命令建议

milestone 初期最小验证：

```bash
git diff --check
wasm-port/tests/native/probe_tool_db_runtime.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
wasm-port/tests/sdk/node/verify_project_release_gate_manifest.sh
```

具备 host runtime 后：

```bash
ENABLE_TOOL_DB_RUNTIME_PROBE=1 wasm-port/tests/native/probe_tool_db_runtime.sh
```

实现 WASM/OPFS port 后追加：

```bash
wasm-port/tests/wasm/node/verify_tool_db_process_port_wasm.sh
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_tool_db_process_browser.sh
```

十一、首个代码切入点建议

建议第一批代码不要直接改 inventory pass/fail，而是新增只读 protocol/runtime 层：

```text
wasm-port/runtime/sdk/src/tool-db-process-port.js
wasm-port/runtime/opfs/tool-db-store.js
wasm-port/tests/sdk/node/verify_tool_db_process_port.mjs
wasm-port/tests/opfs/node/verify_tool_db_store.mjs
```

第一批只做：

- transaction plan parser；
- transcript schema；
- OPFS/path model；
- DB file hash；
- diagnostics export；
- `.tbl fallback sufficient=false` guard。

第二批再接 Python/WASM Worker runtime。

这样可以先建立可测试边界，同时避免误把 JS helper 当作 tool DB runtime pass。

十二、结论

`L4-TOOL-DB` 的正确做法是：

```text
先 native protocol proof；
再 ToolDbProcessPort；
再 WASM/Worker DB_PROGRAM runtime；
再 OPFS persistence；
再 browser diagnostics；
最后才考虑 promotion lock 更新。
```

当前不要做：

```text
不要 .tbl fallback；
不要 JS tool semantics；
不要直接改 baseline；
不要把 protocol contract 当 runtime pass。
```