解锁L4-TOOL-DB主机运行环境
结论：已识别RIP版LinuxCNC主机运行时，Tool DB native protocol probe可通过，inventory baseline保持28/28/131/0且promotion继续锁定。
This commit is contained in:
414
text24.txt
Normal file
414
text24.txt
Normal file
@@ -0,0 +1,414 @@
|
||||
项目接续文件：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。
|
||||
```
|
||||
Reference in New Issue
Block a user