继续完成 web-rtcp-5axis-sim-plan
结论：完成 LinuxCNC kinematics WASM ABI 覆盖，并将 web-rtcp-5axis-sim-plan 的 RTCP frame/boundary adapter 接到 xyzac-trt kinematics SDK；Node、build、browser smoke 验证通过。
This commit is contained in:
538
textbak/text21.txt
Normal file
538
textbak/text21.txt
Normal file
@@ -0,0 +1,538 @@
|
||||
项目接续文件：WASM + OPFS 环境下 tool DB 完全解锁可行性与实施步骤
|
||||
|
||||
生成时间：2026-06-18 CST
|
||||
|
||||
本文件接替 `text20.txt`，进一步回答：在以 WASM 和 OPFS 为技术基础的 Web 技术环境下，
|
||||
`L4-TOOL-DB` 是否可以完全解锁，以及怎样以可实现、可验证、不过度伪装的方式解锁。
|
||||
|
||||
重要状态说明：本文件是 future feasibility / architecture note，不是当前阶段执行计划。
|
||||
当前阶段必须按铁律收束：virtual HAL 成果只作为 sim config promotion 证据基础；
|
||||
`L4-PYTHON-REMAP`、`L4-TOOL-DB`、`L4-USER-M-PROCESS` 仍保持 hard block，不做解锁。
|
||||
本文件中的 WASM + OPFS tool DB 解锁路线只能作为后续专门 milestone 使用，不能用于
|
||||
当前 baseline promotion。
|
||||
|
||||
一、结论
|
||||
|
||||
可以实现“项目定义下的完全解锁”，但不能通过浏览器原生 spawn LinuxCNC native process
|
||||
的方式实现。
|
||||
|
||||
更准确地说：
|
||||
|
||||
```text
|
||||
如果“完全解锁”要求浏览器直接启动 native linuxcnc/milltask/halcmd/DB_PROGRAM 进程，
|
||||
答案是不可以。
|
||||
|
||||
如果“完全解锁”定义为：在 WASM + OPFS 中保留 LinuxCNC-owned tool DB protocol、
|
||||
执行配置声明的 DB_PROGRAM 行为、持久化 DB state、并通过 native/WASM/browser/release
|
||||
proof chain 证明行为等价，答案是可以。
|
||||
```
|
||||
|
||||
因此可行路线不是 `.tbl` fallback，也不是 JS 手写 tool semantics，而是：
|
||||
|
||||
```text
|
||||
WASM 内运行 LinuxCNC tooldata DB protocol owner + WASM/Worker 隔离的 DB_PROGRAM runtime +
|
||||
OPFS-backed flat-file persistence + source-derived proof gates。
|
||||
```
|
||||
|
||||
二、必须保持的语义边界
|
||||
|
||||
`axis/db_demo/base.ngc` 的 LinuxCNC-owned 行为来自：
|
||||
|
||||
- `db_nonran.ini` 中的 `DB_PROGRAM = ./db_nonran.py`；
|
||||
- LinuxCNC task/tooldata DB mode；
|
||||
- `tooldata_db.cc` 的 DB process protocol；
|
||||
- `tooldb.py` 的 protocol loop；
|
||||
- `db.py` / `db_nonran.py` 的 callback/state behavior；
|
||||
- flat-file database persistence。
|
||||
|
||||
WASM + OPFS 解锁时必须保持：
|
||||
|
||||
- `v2.1` startup handshake；
|
||||
- `g` get-all until `FINI`；
|
||||
- `l` spindle load notify；
|
||||
- `u` spindle unload notify；
|
||||
- `p` tool offset notify；
|
||||
- nonrandom `T10..T19` startup state；
|
||||
- DB file persistence；
|
||||
- `DB_PROGRAM` 是配置声明的 runtime dependency；
|
||||
- `.tbl` fallback 仍然标记为 insufficient。
|
||||
|
||||
三、浏览器环境限制
|
||||
|
||||
浏览器/WASM 环境天然缺少：
|
||||
|
||||
- native process spawn；
|
||||
- LinuxCNC host daemon/process model；
|
||||
- direct `milltask` process；
|
||||
- direct `halcmd` host process；
|
||||
- unrestricted POSIX filesystem。
|
||||
|
||||
但浏览器/WASM 环境具备：
|
||||
|
||||
- WASM module execution；
|
||||
- Web Worker 隔离执行单元；
|
||||
- MessageChannel / stream-style protocol；
|
||||
- OPFS 持久文件系统；
|
||||
- Emscripten FS 与 OPFS bridge；
|
||||
- 可移植 Python/WASM runtime 选项；
|
||||
- release/browser diagnostics artifact。
|
||||
|
||||
所以解锁方法必须把 native process boundary 改写为“协议等价 boundary”，而不是假装浏览器
|
||||
可以直接运行 native child process。
|
||||
|
||||
四、推荐总体架构
|
||||
|
||||
### 1. Tool DB protocol owner 仍在 LinuxCNC/WASM core
|
||||
|
||||
将 LinuxCNC tooldata DB protocol owner 保持在 C/C++ WASM 侧：
|
||||
|
||||
- 复用/移植 `tooldata_db.cc`；
|
||||
- 复用/移植 `tooldata_common.cc`；
|
||||
- 保留 protocol message 生成与解析；
|
||||
- 只把 process I/O edge 抽象为 host adapter。
|
||||
|
||||
建议新增抽象：
|
||||
|
||||
```text
|
||||
ToolDbProcessPort
|
||||
```
|
||||
|
||||
职责：
|
||||
|
||||
- start configured DB program；
|
||||
- write protocol line；
|
||||
- read reply line；
|
||||
- close / cleanup；
|
||||
- expose protocol transcript for diagnostics。
|
||||
|
||||
不允许职责：
|
||||
|
||||
- 自行解释 tool table；
|
||||
- 自行构造 `T10..T19`；
|
||||
- 跳过 `tooldb.py`；
|
||||
- 用 `.tbl` fallback。
|
||||
|
||||
### 2. DB_PROGRAM 在 Web Worker / WASM Python runtime 中运行
|
||||
|
||||
推荐把 `db_nonran.py` 放进独立 Web Worker，使用 WASM Python runtime 执行。
|
||||
|
||||
可选实现：
|
||||
|
||||
- CPython/WASM；
|
||||
- Pyodide；
|
||||
- 项目内裁剪 Python/WASM runtime；
|
||||
- 后续若项目已有 Python-remap runtime，可复用同一个 Python runtime substrate。
|
||||
|
||||
Worker 内需要挂载：
|
||||
|
||||
- `db_nonran.py`；
|
||||
- `db.py`；
|
||||
- `tooldb.py`；
|
||||
- minimal `linuxcnc` Python compatibility module；
|
||||
- OPFS-backed DB flat file。
|
||||
|
||||
这里的 minimal `linuxcnc` module 只能覆盖 DB demo 必需的 integration surface，例如：
|
||||
|
||||
- `linuxcnc.command().load_tool_table`
|
||||
|
||||
并且必须作为 process integration shim 记录，不允许承载 tool semantics。
|
||||
|
||||
### 3. OPFS 负责 DB persistence
|
||||
|
||||
将 DB demo 的 flat-file database 映射到 OPFS，例如：
|
||||
|
||||
```text
|
||||
/machines/<machine-id>/tool-db/db_nonran_file
|
||||
```
|
||||
|
||||
要求：
|
||||
|
||||
- startup 前可加载已有 OPFS DB file；
|
||||
- protocol mutation 后写回 OPFS；
|
||||
- reload session 后 DB state 保持；
|
||||
- diagnostics artifact 导出 DB file hash / state summary / transcript hash；
|
||||
- tests 能验证 persistence roundtrip。
|
||||
|
||||
### 4. Browser diagnostics 只证明，不伪装
|
||||
|
||||
browser UI / diagnostics 需要记录：
|
||||
|
||||
- DB runtime mode：`wasm-tool-db-protocol-worker`；
|
||||
- DB program path；
|
||||
- protocol transcript；
|
||||
- OPFS DB file path；
|
||||
- source files；
|
||||
- `.tbl fallback sufficient = false`；
|
||||
- Python-only sufficient = false；
|
||||
- native proof status；
|
||||
- WASM proof status；
|
||||
- browser proof status。
|
||||
|
||||
五、分阶段实施路线
|
||||
|
||||
### Phase 0：保持当前 lock，不改 baseline
|
||||
|
||||
当前状态仍是：
|
||||
|
||||
```text
|
||||
axis/db_demo/base.ngc SKIP L4-TOOL-DB
|
||||
executed=28
|
||||
passed=28
|
||||
skipped=131
|
||||
unexpected_fail=0
|
||||
```
|
||||
|
||||
先不要改成 PASS。
|
||||
|
||||
保留：
|
||||
|
||||
- `promotion_allowed=0`
|
||||
- `execution_enabled=0`
|
||||
- `promotion_lock_active=1`
|
||||
|
||||
### Phase 1：native proof 先闭环
|
||||
|
||||
目的：证明 source-derived protocol contract 与真实 LinuxCNC DB runtime 一致。
|
||||
|
||||
在完整 LinuxCNC host runtime 中执行：
|
||||
|
||||
```text
|
||||
wasm-port/tests/native/probe_tool_db_runtime.sh
|
||||
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
|
||||
```
|
||||
|
||||
然后刷新：
|
||||
|
||||
```text
|
||||
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
|
||||
```
|
||||
|
||||
预期 artifact 转为：
|
||||
|
||||
```text
|
||||
source_proof_ready=1
|
||||
runtime_ready=1
|
||||
native_evidence_ready=1
|
||||
gate_status=native_probe_passed_waiting_for_node_browser_promotion_proof
|
||||
promotion_allowed=0
|
||||
```
|
||||
|
||||
### Phase 2：设计 WASM tool DB process port
|
||||
|
||||
新增 C/C++ 或 JS/WASM bridge 层，但协议 owner 必须保留 LinuxCNC source-derived 逻辑。
|
||||
|
||||
建议新增文件范围：
|
||||
|
||||
```text
|
||||
wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_tool_db_process_port.*
|
||||
wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_tool_db_protocol_harness.*
|
||||
wasm-port/runtime/sdk/src/linuxcnc-tool-db.js
|
||||
wasm-port/runtime/opfs/linuxcnc-tool-db-store.js
|
||||
```
|
||||
|
||||
核心 API 草案：
|
||||
|
||||
```text
|
||||
createLinuxCncToolDbRuntime({
|
||||
dbProgramPath,
|
||||
sourceFiles,
|
||||
opfsRoot,
|
||||
pythonRuntime,
|
||||
})
|
||||
|
||||
startToolDbProgram()
|
||||
sendToolDbProtocolMessage(line)
|
||||
readToolDbProtocolReply()
|
||||
runToolDbTransactionPlan(plan)
|
||||
exportToolDbDiagnostics()
|
||||
```
|
||||
|
||||
验证要求：
|
||||
|
||||
- API 返回 protocol transcript；
|
||||
- transcript 包含 `v2.1` / `g` / `FINI` / `l` / `p` / `u`；
|
||||
- DB state 不能来自 JS fixture hardcode；
|
||||
- source file hash 必须可追踪。
|
||||
|
||||
### Phase 3：WASM Python / DB_PROGRAM runtime
|
||||
|
||||
新增或接入 Python/WASM runtime。
|
||||
|
||||
最低目标不是完整 Python remap runtime，而是 tool DB demo runtime：
|
||||
|
||||
- 能 import `tooldb.py`；
|
||||
- 能 import `db.py` / `db_nonran.py`；
|
||||
- 能读写 OPFS-backed DB file；
|
||||
- 能通过 stdin/stdout 或 MessageChannel 模拟 process protocol；
|
||||
- 能提供 minimal `linuxcnc.command().load_tool_table` integration shim。
|
||||
|
||||
必须新增 negative tests：
|
||||
|
||||
- 没有 `db_nonran.py` 时 fail；
|
||||
- 没有 `tooldb.py` 时 fail；
|
||||
- 只有 `python3` / Python runtime 但没有 protocol transcript 时 fail；
|
||||
- 使用 `.tbl` fallback 时 fail；
|
||||
- JS 直接返回 `T10..T19` 而没有 DB_PROGRAM transcript 时 fail。
|
||||
|
||||
### Phase 4：WASM protocol transaction tests
|
||||
|
||||
新增 Node/WASM tests，先不改 full inventory baseline。
|
||||
|
||||
建议新增：
|
||||
|
||||
```text
|
||||
wasm-port/tests/wasm/node/verify_tool_db_process_wasm.sh
|
||||
wasm-port/tests/wasm/node/verify_tool_db_process_wasm.mjs
|
||||
```
|
||||
|
||||
测试内容：
|
||||
|
||||
1. stage `db_nonran.ini` / `db_nonran.py` / `db.py` / `tooldb.py`；
|
||||
2. start WASM DB program runtime；
|
||||
3. verify startup `v2.1`；
|
||||
4. send `g` and verify `T10..T19` plus `FINI`；
|
||||
5. send `l` load notify and verify pocket/spindle state；
|
||||
6. send `p` offset/update notify and verify DB mutation；
|
||||
7. send `u` unload notify and verify unload state；
|
||||
8. persist to OPFS-backed store；
|
||||
9. reload and verify state survives；
|
||||
10. export transcript artifact。
|
||||
|
||||
输出建议：
|
||||
|
||||
```text
|
||||
tool_db_process_wasm_protocol=ok
|
||||
tool_db_process_wasm_persistence=ok
|
||||
tool_db_process_wasm_no_tbl_fallback=ok
|
||||
```
|
||||
|
||||
### Phase 5：接入 inventory pre-promotion artifacts
|
||||
|
||||
在不改 baseline 的前提下，新增或扩展 artifact：
|
||||
|
||||
```text
|
||||
tool-db-process-wasm-protocol-proof.tsv
|
||||
tool-db-process-opfs-persistence-proof.tsv
|
||||
tool-db-process-browser-proof-gate.tsv
|
||||
```
|
||||
|
||||
字段建议：
|
||||
|
||||
- path；
|
||||
- ini；
|
||||
- db_program；
|
||||
- protocol_transcript_hash；
|
||||
- opfs_db_file；
|
||||
- startup_handshake_passed；
|
||||
- get_all_passed；
|
||||
- load_notify_passed；
|
||||
- offset_notify_passed；
|
||||
- unload_notify_passed；
|
||||
- persistence_passed；
|
||||
- tbl_fallback_sufficient；
|
||||
- python_only_sufficient；
|
||||
- source_derived；
|
||||
- execution_enabled；
|
||||
- promotion_allowed。
|
||||
|
||||
在这一阶段：
|
||||
|
||||
```text
|
||||
execution_enabled=0
|
||||
promotion_allowed=0
|
||||
```
|
||||
|
||||
仍保持 lock。
|
||||
|
||||
### Phase 6：Browser proof
|
||||
|
||||
新增 browser proof，但只证明 protocol runtime 和 OPFS persistence，不直接宣称 inventory pass。
|
||||
|
||||
建议新增或扩展：
|
||||
|
||||
```text
|
||||
wasm-port/tests/browser/verify_real_simulation_browser.sh
|
||||
wasm-port/tests/browser/real_simulation_page_smoke.html
|
||||
```
|
||||
|
||||
验证：
|
||||
|
||||
- browser 可以启动 tool DB Worker；
|
||||
- browser diagnostics 包含 DB protocol transcript summary；
|
||||
- OPFS persistence roundtrip 成功；
|
||||
- `.tbl fallback sufficient=false`；
|
||||
- `python_only_sufficient=false`；
|
||||
- release artifact URL workflow 能显示 tool DB proof；
|
||||
- missing DB proof negative fixture 会 fail。
|
||||
|
||||
### Phase 7：关闭 promotion lock 前的三方对齐
|
||||
|
||||
只有以下全部满足，才能准备关闭 lock：
|
||||
|
||||
```text
|
||||
native_db_process_protocol_probe_passed=1
|
||||
wasm_tool_db_protocol_passed=1
|
||||
browser_tool_db_protocol_proof_passed=1
|
||||
opfs_persistence_passed=1
|
||||
tbl_fallback_sufficient=0
|
||||
python_only_sufficient=0
|
||||
source_derived=1
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```text
|
||||
runtime-boundary-promotion-readiness.tsv
|
||||
runtime-boundary-promotion-blockers.tsv
|
||||
runtime-boundary-post-native-pass-gates.tsv
|
||||
runtime-boundary-native-evidence-acceptance-gate.tsv
|
||||
blocked-runtime-promotion-lock.tsv
|
||||
promotion-candidates.tsv
|
||||
```
|
||||
|
||||
目标状态：
|
||||
|
||||
```text
|
||||
native_evidence_ready=1
|
||||
node_inventory_gate_complete=1
|
||||
browser_smoke_gate_complete=1
|
||||
promotion_lock_active=0
|
||||
promotion_ready=1
|
||||
promotion_allowed=1
|
||||
```
|
||||
|
||||
### Phase 8：正式 inventory baseline promotion
|
||||
|
||||
更新 `verify_sim_configs_inventory_wasm.mjs`，允许 `axis/db_demo/base.ngc` 走 tool DB
|
||||
protocol execution path。
|
||||
|
||||
要求：
|
||||
|
||||
- 执行时必须通过 WASM tool DB protocol runtime；
|
||||
- 不能直接使用 `.tbl`；
|
||||
- 失败时不能降级为 SKIP；
|
||||
- protocol proof 缺失时必须 FAIL，而不是 silent fallback。
|
||||
|
||||
预期 `summary.tsv`：
|
||||
|
||||
```text
|
||||
axis/db_demo/base.ngc PASS - main PASS -
|
||||
```
|
||||
|
||||
预期 baseline：
|
||||
|
||||
```text
|
||||
executed=29
|
||||
passed=29
|
||||
skipped=130
|
||||
unexpected_fail=0
|
||||
```
|
||||
|
||||
同步更新：
|
||||
|
||||
```text
|
||||
VIRTUAL_HAL_SIM_CONFIG_INVENTORY_BASELINE
|
||||
project release readiness fixture
|
||||
coverage matrix Current Node inventory
|
||||
compatibility validation current gate text
|
||||
skip-summary expected count
|
||||
promotion candidate expected status
|
||||
release readiness artifact
|
||||
batch acceptance artifact
|
||||
```
|
||||
|
||||
六、可实现性的关键判断
|
||||
|
||||
### 可以实现的部分
|
||||
|
||||
1. WASM 内保存 LinuxCNC tool DB protocol owner。
|
||||
2. Web Worker 作为 DB_PROGRAM process boundary 等价层。
|
||||
3. WASM Python runtime 执行 `db_nonran.py` / `tooldb.py`。
|
||||
4. OPFS 保存 DB flat-file。
|
||||
5. Node/WASM/browser 三层 proof。
|
||||
6. release artifact 记录 proof chain。
|
||||
7. inventory baseline 从 `28/28/131/0` 推进到 `29/29/130/0`。
|
||||
|
||||
### 不应承诺的部分
|
||||
|
||||
1. 浏览器直接运行 native `milltask`。
|
||||
2. 浏览器直接运行 host `halcmd`。
|
||||
3. 浏览器直接 spawn OS child process。
|
||||
4. 不经 Python DB program 而直接伪造 DB state。
|
||||
5. 用 `.tbl` 替代 `DB_PROGRAM`。
|
||||
|
||||
七、推荐实施顺序
|
||||
|
||||
最务实顺序：
|
||||
|
||||
```text
|
||||
1. 先在 native host 上跑通 ENABLE_TOOL_DB_RUNTIME_PROBE=1。
|
||||
2. 加 tool DB WASM protocol proof，不改 baseline。
|
||||
3. 加 OPFS persistence proof，不改 baseline。
|
||||
4. 加 browser diagnostics proof，不改 baseline。
|
||||
5. 更新 promotion readiness / lock。
|
||||
6. 最后才把 axis/db_demo/base.ngc 纳入 inventory PASS。
|
||||
```
|
||||
|
||||
八、最小验证命令
|
||||
|
||||
native：
|
||||
|
||||
```text
|
||||
wasm-port/tests/native/probe_tool_db_runtime.sh
|
||||
ENABLE_TOOL_DB_RUNTIME_PROBE=1 wasm-port/tests/native/probe_tool_db_runtime.sh
|
||||
```
|
||||
|
||||
WASM/Node：
|
||||
|
||||
```text
|
||||
wasm-port/tests/wasm/node/verify_tool_db_process_wasm.sh
|
||||
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
|
||||
```
|
||||
|
||||
Browser：
|
||||
|
||||
```text
|
||||
SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
|
||||
```
|
||||
|
||||
Release：
|
||||
|
||||
```text
|
||||
wasm-port/tests/sdk/node/verify_sdk_surface.sh
|
||||
wasm-port/tests/sdk/node/verify_project_release_gate_manifest.sh
|
||||
wasm-port/tests/host/verify_project_release_readiness_artifact.sh
|
||||
```
|
||||
|
||||
Safety：
|
||||
|
||||
```text
|
||||
git diff --check
|
||||
wasm-port/tools/verify_no_standalone_cnc_semantics.sh
|
||||
```
|
||||
|
||||
九、下一步工作内容
|
||||
|
||||
下一轮建议不要直接改 `axis/db_demo/base.ngc` 的 inventory status。先做最小可行
|
||||
WASM proof：
|
||||
|
||||
```text
|
||||
新增 verify_tool_db_process_wasm.mjs / .sh，证明 tool DB protocol transcript 和 OPFS
|
||||
persistence 可以在 WASM + OPFS 环境中闭环，同时继续保持 promotion_allowed=0。
|
||||
```
|
||||
|
||||
该 proof 的完成标准：
|
||||
|
||||
- `db_nonran.py` / `tooldb.py` 被真实加载；
|
||||
- protocol transcript 中出现 `v2.1`、`g`、`FINI`、`l`、`p`、`u`；
|
||||
- OPFS persistence roundtrip 通过；
|
||||
- `.tbl fallback` negative fixture 失败；
|
||||
- artifact 明确记录 `promotion_allowed=0`。
|
||||
|
||||
完成后再进入 browser proof 和 promotion lock 更新。
|
||||
Reference in New Issue
Block a user