项目接续文件：利用 virtual HAL 成果推进 sim config baseline promotion

生成时间：2026-06-18 CST

本文件接替 `text18.txt`。后续继续推进时优先参考 `text19.txt`；除非明确要求审计
旧记录，不再回到 `text1` 到 `text18` 扩展历史实现。

一、方向纠偏

上一版表述容易被误读为“转向非 virtual HAL，不再使用 virtual HAL 成果”。正确方向是：

```text
virtual HAL runtime capability 已收尾；后续不继续扩展 virtual HAL 新功能，
但要利用已完成的 virtual HAL source-derived evidence、browser diagnostics、
release gate 和 motion matrix，继续推进 sim config coverage / baseline promotion。
```

执行含义：

- 不新增 virtual HAL runtime capability；
- 不新增 unrelated virtual HAL UI 面板、filter、drilldown 类功能；
- 不把 virtual HAL 当成 JS CNC 语义替代品；
- 允许并且应该复用 virtual HAL 已有成果作为 promotion evidence：
  - source compliance；
  - sim-config source coverage；
  - promotion candidate report；
  - macro/load fixture report；
  - command script fixtures；
  - manifest-backed motion controller matrix；
  - browser diagnostics artifact；
  - release readiness / URL workflow / batch acceptance evidence。

二、当前 baseline

当前 Node inventory baseline 仍为：

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

当前已经完成的 virtual HAL promotion evidence 不等同于 inventory skip count 下降。它已经把
一批 Node `INV` / representative rows 推进到了 browser diagnostics / release evidence 层，
但如果要让 `executed/passed/skipped` 变化，仍必须修改并运行真实 inventory execution path。

三、已具备的 promotion evidence

当前 SDK / browser / release gate 已覆盖 Tier 1 promotion candidate report：

- `qtdragon/qtdragon_multi_joint/on_abort.ngc`
- `qtdragon/qtdragon_xyz/on_abort.ngc`
- `qtdragon/qtdragon_xyz45/on_abort.ngc`
- `qtdragon_hd/qtdragon_hd_xyz/on_abort.ngc`
- `qtdragon_hd/qtdragon_hd_z_compensation/on_abort.ngc`
- `qtvcp_screens/qtdragon/on_abort.ngc`
- `axis/vismach/puma/puma_seam_weld.ngc`
- `axis/rose_engine/rcone_demo.ngc`

这些 row 的当前性质：

- LinuxCNC source/config evidence 完整；
- current Node inventory status 为 `PASS`；
- blocked kind 为 `-`；
- target browser evidence 为 `explicit-browser-diagnostics`；
- release diagnostics validation 已要求 promotion candidate summary；
- inventory baseline 保持不变。

当前 macro/load 非主程序 evidence 已覆盖：

- `axis/rose_engine/rcone.ngc`
- `axis/external_offsets/queuebuster.ngc`

这些只能作为 non-main fixture diagnostics evidence，不作为 standalone main program promotion。

四、不可突破边界

以下 family 仍不能靠 virtual HAL、JS glue 或 browser UI 伪装解锁：

- Linux kernel hard-realtime ABI；
- 外部硬件驱动 ABI；
- native HAL module ABI；
- Python UI process emulation；
- Python remap runtime；
- tool database process protocol；
- external user-M process execution；
- upstream-invalid demo code。

因此以下 blocked kind 仍保持 locked：

- `L4-PYTHON-REMAP`
- `L4-TOOL-DB`
- `L4-USER-M-PROCESS`
- `UPSTREAM-DEMO`
- standalone-main 语境下的 `ASSET-ONLY`

五、下一步主线目标

目标仍是从：

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

推进到更高完成度。第一阶段建议目标：

```text
executed >= 35
passed == executed
skipped <= 124
unexpected_fail=0
```

但推进方式应是：

1. 先复用 virtual HAL 已建立的 source-derived evidence，确认候选 family 的 browser/release
   evidence 已 ready；
2. 再找出当前 inventory 中还没有执行、但依赖已被 virtual HAL / HALUI / deterministic
   UI declarations / machine files / tool tables / remap asset staging 覆盖的 main program；
3. 只把 LinuxCNC-backed runtime 能真实执行通过的 row 纳入 inventory；
4. 同步更新 docs、release artifact fixture、SDK/host gate baseline 断言。

六、候选选择原则

优先方向：

- Tier 1 已有 promotion evidence 周边 family：
  - QtDragon on-abort family；
  - PUMA / vismach remap family；
  - rose-engine family；
- 当前 matrix 中 `blocked=-`、`class=main`、native `PASS`、但尚未进入 browser explicit evidence
  或 inventory execution 的 row；
- 已有 tool-table fallback、vendored INI/G-code/source evidence、无 Python/process hard block 的 row；
- 已有 virtual HAL command/motion matrix 可以解释 HAL/UI/motion 依赖的 row。

禁止方向：

- 不把 Python remap pass 当作 browser/Node full promotion；
- 不把 tool DB native pass 当作 WASM process protocol pass；
- 不把 external user-M process pass 当作 virtual HAL deterministic M110/M111 边界；
- 不把 macro/load asset 当 standalone main；
- 不靠改 docs 声称 skipped 降低。

七、建议执行步骤

### 第一步：复核当前 virtual HAL promotion gate

最小命令：

```text
wasm-port/tests/sdk/node/verify_sdk_surface.sh
wasm-port/tests/sdk/node/verify_project_release_gate_manifest.sh
```

确认：

- `VIRTUAL_HAL_SIM_CONFIG_PROMOTION_CANDIDATES` 仍包含 8 个 Tier 1 row；
- candidate report `complete === true`；
- `webSimulationSatisfied === true`；
- `inventoryBaselineUnchanged === true`；
- blocked candidate count 为 0；
- release gate / URL workflow 仍要求 candidate summary。

### 第二步：生成真实 inventory promotion candidate 清单

不要只列 hard-block skipped main row；应输出两个层级：

- evidence-ready candidates：已有 virtual HAL/browser/release evidence，适合继续升 browser/release
  覆盖；
- inventory-ready candidates：确实可从 skipped 推进到 executed 的 main program。

建议输出：

```text
wasm-port/build/wasm/sim-configs-inventory/promotion-candidates.tsv
```

字段至少包含：

- path；
- ini；
- current inventory status；
- matrix layer4 node/browser status；
- class；
- native status；
- blocked kind；
- dependency class；
- virtual HAL evidence ready；
- inventory promotion allowed；
- block reason；
- recommended next command。

### 第三步：推进第一批真实 inventory rows

一次只推进 5 到 8 个 row。每个 row 必须说明：

- LinuxCNC source/config/runtime evidence；
- 为什么已有 virtual HAL evidence 能覆盖 HAL/UI/motion 依赖；
- 为什么不是 JS/browser 自行补 CNC 语义；
- 为什么不属于 `L4-PYTHON-REMAP`、`L4-TOOL-DB`、`L4-USER-M-PROCESS`、
  `UPSTREAM-DEMO` 或 standalone `ASSET-ONLY`；
- 执行后 baseline 如何变化。

### 第四步：同步 release packaging

baseline 真变化后，同步更新：

- generated sim-config inventory artifact；
- `wasm-port/docs/sim-configs-coverage-matrix.md`；
- `wasm-port/docs/sim-config-coverage-promotion-analysis.md`；
- release readiness artifact fixture；
- SDK / host gate 的 baseline 断言；
- browser diagnostics / URL workflow 中的 baseline 文案。

八、验收标准

一次真实 baseline promotion 完成条件：

1. 新 baseline artifact 真实生成；
2. `executed` 和 `passed` 同步增加；
3. `skipped` 同步减少；
4. `unexpected_fail` 仍为 `0`；
5. 新增 rows 不属于 blocked family；
6. virtual HAL evidence 是 source-derived support，不是 CNC 语义替代；
7. `verify_no_standalone_cnc_semantics.sh` 仍通过；
8. 最小相关 gate 通过；
9. 文档记录变更前/后 baseline、新增 rows、blocked family lock 状态和验证命令。

建议最小验证命令：

```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 页面，再额外运行：

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

九、下一步工作内容

下一轮建议直接做：

```text
基于现有 virtual HAL promotion candidate report，生成 evidence-ready / inventory-ready
双层 promotion-candidates.tsv；然后从 blocked=-、native PASS、class=main 的 row 中筛出
第一批 5-8 个可真实进入 inventory execution 的候选，试运行并更新 baseline。
```

优先候选 family：

- QtDragon on-abort family 周边；
- PUMA / vismach remap family；
- rose-engine family；
- 其他已 vendored、无 Python/process hard block、可由 virtual HAL 解释 HAL/UI/motion 依赖的
  main program。