wangdequan
626bcfe8e3
结论：完成 LinuxCNC kinematics WASM ABI 覆盖，并将 web-rtcp-5axis-sim-plan 的 RTCP frame/boundary adapter 接到 xyzac-trt kinematics SDK；Node、build、browser smoke 验证通过。
415 lines
9.1 KiB
Plaintext
415 lines
9.1 KiB
Plaintext
项目接续文件：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。
|
||
```
|