项目接续文件：tool DB 解锁步骤与方法

生成时间：2026-06-18 CST

本文件接替 `text19.txt` 中关于 blocked runtime family 的后续推进说明，专门规划
`L4-TOOL-DB` / `axis/db_demo/base.ngc` 的解锁路径。当前目标不是绕过 tool DB，
而是在已有 source-derived evidence、transaction contract、native readiness gate 和
promotion lock 框架基础上，把 tool database process protocol 证明补齐，然后再允许
真实 inventory promotion。

重要状态说明：本文件是未来解锁研究计划，不是当前阶段实施范围。当前阶段铁律仍是
“virtual HAL 成果作为 sim config promotion 证据基础”，同时明确不解锁
`L4-PYTHON-REMAP`、`L4-TOOL-DB`、`L4-USER-M-PROCESS` 这些 hard block。
因此在当前交付中，`axis/db_demo/base.ngc` 必须继续保持 `SKIP L4-TOOL-DB`，
`promotion_allowed=0`，`promotion_lock_active=1`。

一、当前已完成条件

当前项目已经具备以下基础，不需要重做：

1. source/config ownership 已明确。

- `axis/db_demo/base.ngc` 当前 blocked kind 为 `L4-TOOL-DB`；
- owning INI 为 `axis/db_demo/db_nonran.ini`；
- INI 声明：

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

- LinuxCNC source owner 已记录：
  - `configs/sim/axis/db_demo/db_nonran.ini`
  - `configs/sim/axis/db_demo/db.py`
  - `src/emc/task/taskclass.cc`
  - `src/emc/tooldata/tooldata_db.cc`
  - `lib/python/tooldb.py`

2. machine-readable artifacts 已有。

当前已有并通过 inventory gate 的 tool DB 相关 artifact：

```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
```

3. transaction contract 已明确。

`tool-db-process-transaction-plan.tsv` 已把 DB protocol 拆成以下 pending proof：

- `startup_handshake`：启动后返回 `v2.1`；
- `initial_get_all`：发送 `g`，读取直到 `FINI`；
- `spindle_load_notify`：发送/验证 `l`；
- `tool_offset_notify`：发送/验证 `p`；
- `spindle_unload_notify`：发送/验证 `u`。

4. 当前 readiness 状态已明确。

当前 `tool-db-process-native-runtime-readiness.tsv` / probe gate 显示：

```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
proof_status=pending
execution_enabled=0
promotion_allowed=0
```

这说明当前缺的不是 source evidence，也不是 Python 文件本身，而是完整 LinuxCNC
task/tooldata DB host runtime。

二、解锁原则

tool DB 解锁必须遵守以下规则：

1. 不允许用 `.tbl` fallback 解锁。

`DB_PROGRAM` 模式明确替代普通 tool table path。用 `.tbl` 让程序跑通会绕过
LinuxCNC tool database process protocol，属于错误 promotion。

2. 不允许用 JS/virtual HAL 重新实现 tool DB 语义。

virtual HAL 可以继续作为 HAL/motion/browser diagnostics evidence，但不能替代：

- `DB_PROGRAM` 子进程启动；
- `tooldb.py` protocol loop；
- `v2.1` / `g` / `l` / `u` / `p` protocol；
- nonrandom DB state mutation；
- flat-file persistence。

3. native proof 必须先于 Node/browser promotion。

只有 native runtime probe 明确通过以后，才允许更新 Node/browser promotion gate。

4. promotion lock 必须手动更新。

即使 native probe 通过，也不能自动把 `axis/db_demo/base.ngc` 从 skipped 改为 executed。
必须明确更新 promotion readiness、blockers、post-native-pass gate 和 lock artifact。

三、第一阶段：准备 host runtime

目标：让 tool DB runtime readiness 从：

```text
runtime_ready=0
missing_requirements=linuxcnc,milltask,halcmd
```

变为：

```text
runtime_ready=1
missing_requirements=-
```

需要准备的命令/模块：

```text
python3
linuxcnc
milltask
halcmd
axis/db_demo/db_nonran.py
linuxcnc.so
tooldb.py
```

当前已有：

```text
python3
axis/db_demo/db_nonran.py
linuxcnc.so
tooldb.py
```

当前缺失：

```text
linuxcnc
milltask
halcmd
```

建议方法：

1. 在具备完整 LinuxCNC userspace runtime 的 host / container 中执行。
2. 确保 `linuxcnc`、`milltask`、`halcmd` 在 `PATH` 上。
3. 确保 LinuxCNC Python 模块路径能被 `db_nonran.py` import：

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

4. 重新运行 native probes / inventory gate 以刷新 readiness artifacts：

```text
wasm-port/tests/native/probe_tool_db_runtime.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
```

预期中间状态：

- 如果 host runtime 仍缺失：

```text
tool_db_runtime_probe_status=skipped_missing_host_runtime
```

- 如果 host runtime 已满足但未显式启用 probe：

```text
tool_db_runtime_probe_status=ready_disabled_by_default
```

四、第二阶段：执行 native DB protocol probe

目标：证明 LinuxCNC-owned DB process protocol 真实可运行。

执行命令：

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

该 probe 必须证明：

1. `db_nonran.py` 按 `DB_PROGRAM` 配置启动；
2. startup handshake 返回 `v2.1`；
3. `g` get-all 返回 expected nonrandom startup tools；
4. startup state 覆盖 `T10..T19` / `tno+100` pockets；
5. `l` load notify 触发 spindle load state；
6. `p` tool offset notify 触发 DB update path；
7. `u` unload notify 触发 spindle unload state；
8. flat-file persistence 能反映 state mutation；
9. probe 输出：

```text
tool_db_runtime_probe_status=runtime_protocol_probe_passed
```

失败处理：

- 如果失败在 import `linuxcnc` / `tooldb`：修 Python module path，不改项目语义；
- 如果失败在 `linuxcnc` / `milltask` / `halcmd`：修 host runtime，不改 Node/browser fallback；
- 如果失败在 protocol message：先对齐 native `db_nonran.py` / `tooldb.py` 行为和
  `tool-db-process-transaction-plan.tsv`，不允许用简化协议绕过；
- 如果失败在 persistence：修 probe 环境的临时 DB 文件隔离和 cleanup，不把 persistence
  检查删除。

五、第三阶段：刷新 native/runtime artifacts

native probe pass 后，重新生成并验证 artifacts：

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

预期变化方向：

```text
tool-db-process-native-runtime-readiness.tsv:
  runtime_ready=1
  missing_requirements=-

tool-db-process-native-runtime-probe-gate.tsv:
  gate_status=native_probe_passed_waiting_for_node_browser_promotion_proof
  proof_status=passed
  source_proof_ready=1
```

注意：这个阶段仍不应直接让 `promotion_allowed=1`。native pass 只是打开下一步
Node/browser proof 的条件。

六、第四阶段：更新 promotion readiness / blocker / lock

native pass 后，需要更新以下 gate 的逻辑和 fixtures：

```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
next-boundary-recommendations.tsv
promotion-candidates.tsv
```

目标状态：

1. `native_evidence_ready=1`；
2. `node_inventory_gate_complete=0`，直到 Node inventory row 真实执行；
3. `browser_smoke_gate_complete=0`，直到 browser proof 真实通过；
4. `promotion_lock_active=1`，直到人工明确解锁；
5. blocker 从 `missing_host_runtime` 转为：

```text
pending_node_inventory_promotion_gate
pending_browser_smoke_gate
promotion_lock_active
```

这一步的重点是：native proof 已经完成，但还没有完成 Node/browser promotion，因此
blocked family 不能直接消失。

七、第五阶段：设计 Node inventory execution path

只有 native DB protocol probe 通过后，才允许考虑让 `axis/db_demo/base.ngc` 进入
Node inventory execution。

可接受方向：

1. 通过 LinuxCNC-owned tooldata DB protocol wrapper 执行；
2. 保留 `DB_PROGRAM = ./db_nonran.py` 的行为边界；
3. Node/WASM 侧只做 file staging、protocol bridge、result capture；
4. 所有 tool DB state 来自 LinuxCNC protocol / db.py 行为，而不是 JS 自行解释。

不可接受方向：

1. 把 `axis/sim.tbl` 或任意 `.tbl` 当作 DB fallback；
2. 在 JS 中手写 `T10..T19` tool DB state；
3. 跳过 `v2.1` / `g` / `l` / `u` / `p` protocol；
4. 只因为 native `bin/rs274` 能 parse `base.ngc` 就标记 Node inventory PASS；
5. 把 virtual HAL readiness 当作 tool DB process readiness。

如果 Node/WASM 当前无法启动 Python DB process，则应保持：

```text
node_inventory_gate_complete=0
promotion_allowed=0
```

并把下一步限定为“设计 tool DB protocol bridge”，而不是直接改 baseline。

八、第六阶段：Browser proof

Browser proof 只能在 Node inventory gate 真实完成后做。

Browser proof 至少需要：

- diagnostics artifact 记录 tool DB protocol proof status；
- release URL workflow 显示 `axis/db_demo/base.ngc` 的 DB proof；
- 明确 `tool_table_fallback_sufficient=0`；
- 明确 `python3_sufficient=0`；
- 明确 source owner 是 LinuxCNC DB protocol；
- browser 只呈现 proof / workflow / artifact，不自行执行 tool DB semantics。

九、第七阶段：真实 inventory baseline promotion

只有满足以下条件后，才允许把 `axis/db_demo/base.ngc` 从 skipped 变为 executed：

1. native DB runtime probe passed；
2. Node inventory execution path 通过 LinuxCNC-owned DB protocol；
3. browser proof / release diagnostics gate 已通过；
4. promotion lock 手动关闭；
5. `promotion-candidates.tsv` 中对应行从：

```text
candidate_kind=inventory-ready
current_status=SKIP
skip_kind=L4-TOOL-DB
promotion_allowed=0
```

变为真实可 promotion 状态，并有明确 proof chain；
6. `summary.tsv` 中 `axis/db_demo/base.ngc` 变为：

```text
inventory_status=PASS
skip_or_fail_reason=-
```

预期 baseline 变化：

```text
executed: 28 -> 29
passed:   28 -> 29
skipped:  131 -> 130
unexpected_fail: 0
```

十、需要同步更新的文件/断言

baseline 真实变化后，至少同步：

```text
wasm-port/docs/sim-configs-coverage-matrix.md
wasm-port/docs/sim-config-coverage-promotion-analysis.md
wasm-port/docs/compatibility-validation.md
wasm-port/runtime/sdk/src/linuxcnc-hal.js
wasm-port/runtime/sdk/src/project-release-readiness.js
wasm-port/tests/fixtures/project-release-readiness-ready.json
wasm-port/tests/sdk/node/verify_sdk_surface.mjs
wasm-port/tests/sdk/node/verify_project_release_gate_manifest.mjs
wasm-port/tests/host/verify_project_release_readiness_artifact.mjs
wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.mjs
```

需要同步更新的固定 baseline：

```text
VIRTUAL_HAL_SIM_CONFIG_INVENTORY_BASELINE
project release readiness fixture simConfigInventory
coverage matrix Current Node inventory
compatibility validation current gate text
promotion candidate expected status
skip-summary expected count
```

十一、最小验证命令

host runtime 准备阶段：

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

native runtime proof 阶段：

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

artifact / inventory 阶段：

```text
git diff --check
wasm-port/tools/verify_no_standalone_cnc_semantics.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
wasm-port/tests/sdk/node/verify_sdk_surface.sh
wasm-port/tests/sdk/node/verify_project_release_gate_manifest.sh
```

browser / release proof 阶段：

```text
SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
wasm-port/tests/host/verify_project_release_readiness_artifact.sh
```

十二、下一步工作内容

当前机器 artifact 显示缺少：

```text
linuxcnc
milltask
halcmd
```

因此下一步不是改 Node inventory baseline，而是：

1. 在具备完整 LinuxCNC host runtime 的环境中运行：

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

2. 如果状态变为 `ready_disabled_by_default`，继续运行：

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

3. 拿到 `runtime_protocol_probe_passed` 后，刷新 inventory artifacts：

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

4. 再进入 promotion readiness / lock 更新，而不是直接把
   `axis/db_demo/base.ngc` 改成 PASS。

十三、简要结论

tool DB 的解锁关键不是 virtual HAL 能力不足，而是还缺 LinuxCNC task/tooldata DB
process runtime proof。当前 source evidence、contract、readiness artifact、probe gate
都已铺好；真正的第一步是补齐 host runtime 并跑通
`ENABLE_TOOL_DB_RUNTIME_PROBE=1 wasm-port/tests/native/probe_tool_db_runtime.sh`。