接入虚拟HAL仿真配置promotion证据

2026-06-18 04:47:30 +08:00
parent abf858641f
commit 0bc6896b36
24 changed files with 2879 additions and 108 deletions
--- a/text18.txt
+++ b/text18.txt
@@ -0,0 +1,518 @@
+项目接续文件：sim config coverage promotion 后续推进计划
+
+生成时间：2026-06-18 CST
+
+本文件接替 `text17.txt`，作为后续继续推进的接续文件。后续工作优先参考
+`text18.txt`；除非明确要求审计旧记录，不再回到 `text1` 到 `text17` 扩展进度。
+
+一、当前完成情况摘要
+
+1. LinuxCNC-backed WASM 核心仍是 CNC 语义来源。
+
+- G-code / interpreter / planner / kinematics / canonical motion 语义仍来自 vendored
+  LinuxCNC C/C++ 源码；
+- Browser / UI / SDK 只做 host boundary、文件装载、OPFS/session、virtual HAL runtime、
+  仿真状态桥、测试胶水和报告；
+- 不在 JS 中重写 G-code 解释器、planner、kinematics、tool/parameter 语义。
+
+2. virtual HAL 已完全满足 Web 方式数控系统仿真系统。
+
+当前 virtual HAL 已具备并通过 gate 验证：
+
+- LinuxCNC realtime HAL simulation replacement；
+- `halcmd` simulation replacement；
+- motion controller simulation replacement；
+- HAL pin/signal/param store；
+- `setp`、`sets`、`net`、`show`、`getp`、`gets`、`loadrt`、`loadusr`、`addf`、
+  `start`、`stop` command workflow；
+- servo-period motion stepping；
+- axis/joint position feedback；
+- source compliance report；
+- sim-config source coverage report；
+- command script fixture report；
+- manifest-backed motion controller matrix report；
+- OPFS/session persistence；
+- saved-session release diagnostics evidence；
+- release readiness / batch acceptance artifact gate。
+
+3. release gate 已接入 virtual HAL motion matrix。
+
+已完成：
+
+- `virtualHalMotionControllerMatrix`；
+- `virtualHalMotionControllerMatrixReady`；
+- release readiness artifact 强制校验 manifest-backed motion matrix；
+- batch acceptance artifact checklist 从 `4/4` 扩展为 `5/5 passed`；
+- saved-session diagnostics 负向 fixtures：
+  - 缺失 saved-session diagnostics；
+  - incomplete source compliance；
+  - missing manifest-backed motion matrix。
+
+4. sim config coverage promotion 已先形成分析文档。
+
+新增分析文档：
+
+```text
+wasm-port/docs/sim-config-coverage-promotion-analysis.md
+```
+
+该文档已纳入：
+
+```text
+wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.sh
+```
+
+当前结论：
+
+- 当前 generated inventory 中没有“hard block 已清空但仍 SKIP 的 main program”；
+- 因此不应因为 virtual HAL 完善就直接降低 `skipped=131`；
+- 下一步应推进“case promotion”：把已有 Node `INV` 或代表覆盖案例推进到 browser
+  diagnostics / release evidence；
+- blocked runtime families 仍不能由 virtual HAL 或 JS glue 直接解锁。
+
+二、当前 sim config inventory baseline
+
+当前必须保持的 baseline：
+
+```text
+sim_configs_wasm_node_inventory_executed=28
+sim_configs_wasm_node_inventory_passed=28
+sim_configs_wasm_node_inventory_skipped=131
+sim_configs_wasm_node_inventory_unexpected_fail=0
+sim_configs_wasm_node_inventory_skip_ASSET_ONLY=65
+sim_configs_wasm_node_inventory_skip_L4_PYTHON_REMAP=53
+sim_configs_wasm_node_inventory_skip_L4_TOOL_DB=1
+sim_configs_wasm_node_inventory_skip_L4_USER_M_PROCESS=1
+sim_configs_wasm_node_inventory_skip_NON_MAIN_CLASS=10
+sim_configs_wasm_node_inventory_skip_UPSTREAM_DEMO=1
+```
+
+后续任何改动，只要涉及 inventory baseline，必须明确说明：
+
+- 哪些 row 从何种状态变更；
+- 为什么 LinuxCNC source/runtime evidence 已满足；
+- 为什么不是 JS/browser 自行补语义；
+- 为什么没有破坏 blocked runtime promotion lock。
+
+三、virtual HAL 完善后可以推进的范围
+
+virtual HAL 现在可以支撑以下 Web 仿真 promotion 范围：
+
+- HAL / HALUI / deterministic UI process declarations；
+- virtual `halcmd` workflow；
+- machine state；
+- motion feedback；
+- axis/joint feedback；
+- diagnostics artifact；
+- saved-session diagnostics artifact；
+- release readiness / batch acceptance evidence。
+
+virtual HAL 仍不能解锁：
+
+- 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。
+
+四、promotion 铁律
+
+后续 sim config coverage promotion 必须满足：
+
+1. LinuxCNC source/config evidence owns the behavior。
+2. Native 或当前 Node inventory evidence 已经通过；或者 row 是 macro/load /
+   remap_subroutine，且有明确非主程序验证计划。
+3. 依赖仅限于 virtual HAL、HALUI、deterministic UI process declarations、machine
+   files、tool tables、remap subroutine assets 或已由 LinuxCNC-backed runtime 覆盖的
+   motion/kinematics evidence。
+4. Browser evidence 必须能导出：
+   - virtual HAL source compliance；
+   - sim-config source coverage；
+   - command script fixtures；
+   - manifest-backed motion matrix；
+   - diagnostics artifact；
+   - 如涉及 session，必须导出 saved-session diagnostics。
+5. row 不能属于：
+   - `L4-PYTHON-REMAP`；
+   - `L4-TOOL-DB`；
+   - `L4-USER-M-PROCESS`；
+   - `UPSTREAM-DEMO`；
+   - standalone-main 执行语境下的 `ASSET-ONLY`。
+6. `verify_no_standalone_cnc_semantics.sh` 必须保持通过。
+
+五、继续推进计划
+
+### 1. 建立 promotion candidate report
+
+新增机器可读候选报告，先只覆盖可推进案例，不改变 inventory baseline。
+
+首批候选：
+
+- `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`。
+
+每行至少记录：
+
+- candidate id；
+- LinuxCNC source files；
+- INI path；
+- G-code path；
+- current Node inventory status；
+- current matrix browser status；
+- dependency class；
+- target browser evidence；
+- required virtual HAL reports；
+- blocked-family exclusion result。
+
+建议 API / report 名称：
+
+- `VIRTUAL_HAL_SIM_CONFIG_PROMOTION_CANDIDATES`；
+- `createVirtualHalSimConfigPromotionCandidateReport()`；
+- report `apiName`：
+  `linuxcnc-wasm-virtual-hal-sim-config-promotion-candidate-report`。
+
+### 2. 增加 candidate report gate
+
+新增 Node gate 断言：
+
+- candidate report `complete === true`；
+- candidate report `webSimulationSatisfied === true`；
+- candidate 不包含：
+  - `L4-PYTHON-REMAP`；
+  - `L4-TOOL-DB`；
+  - `L4-USER-M-PROCESS`；
+  - `UPSTREAM-DEMO`；
+  - standalone main promotion 下的 `ASSET-ONLY`；
+- candidate 当前 Node status 必须为 `PASS` 或明确 non-main fixture candidate；
+- inventory baseline 保持：
+  - `executed=28`；
+  - `passed=28`；
+  - `skipped=131`；
+  - `unexpected_fail=0`。
+
+建议接入：
+
+- `verify_sdk_surface.mjs`；
+- `verify_sim_configs_coverage_docs.mjs`；
+- 后续可接入 release readiness artifact，但第一批先作为 SDK/docs gate。
+
+### 3. 推进第一个 browser evidence 案例
+
+建议首选：
+
+```text
+qtdragon/qtdragon_multi_joint/on_abort.ngc
+```
+
+选择原因：
+
+- 当前 Node `INV`；
+- 无 hard runtime block；
+- 依赖 HAL/UI declarations 与 multi-joint machine context；
+- virtual HAL motion matrix 已映射 `qtdragon-on-abort`；
+- source evidence 已包含：
+  `linuxcnc/configs/sim/qtdragon/qtdragon_multi_joint/qtdragon_xyyz.ini`；
+- 可验证 virtual HAL 对 Web CNC 仿真系统的完整满足性。
+
+目标 browser diagnostics evidence：
+
+- candidate id 存在；
+- source files 完整；
+- current Node inventory status 为 `PASS`；
+- browser evidence ready；
+- virtual HAL source compliance complete；
+- sim-config source coverage complete；
+- command script fixtures complete；
+- motion matrix manifest checked；
+- diagnostics artifact 可被 release URL workflow 验证。
+
+### 4. 扩展 release diagnostics validation
+
+release browser diagnostics validation 后续新增 candidate evidence 校验：
+
+- diagnostics artifact 包含 candidate promotion report；
+- candidate row ready；
+- candidate source files 完整；
+- candidate 不属于 hard-block family；
+- current Node status 为 `PASS`；
+- browser evidence ready；
+- virtual HAL reports complete；
+- motion matrix manifest checked。
+
+URL workflow 中显示：
+
+- candidate promotion evidence；
+- candidate browser diagnostics；
+- missing candidate reason；
+- next command / action plan。
+
+### 5. 更新 coverage matrix 注释
+
+只在 browser gate 通过后更新 matrix。
+
+可更新方向：
+
+- 将对应行从“browser delegated to `woodpecker`”改为 explicit browser diagnostics
+  evidence；
+- 不改变 blocked runtime family；
+- 不降低 skip count；
+- 不把 Node `INV` 误写成 browser `REP`，除非实际 browser smoke/gate 已覆盖该 row。
+
+首批可能更新：
+
+```text
+qtdragon/qtdragon_multi_joint/on_abort.ngc
+```
+
+### 6. 推进 QtDragon family 全组
+
+在第一个 QtDragon multi-joint candidate 通过后，继续推进：
+
+- `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`。
+
+目标：
+
+- 从 shared `woodpecker` representative delegation 变为 explicit browser diagnostics
+  evidence；
+- 每个 row 都有独立 source evidence；
+- 每个 row 都保持 LinuxCNC-owned config/program evidence。
+
+### 7. 推进 vismach / rose_engine 案例
+
+后续候选：
+
+- `axis/vismach/puma/puma_seam_weld.ngc`
+  - 当前 Node `INV`；
+  - 与 `puma_cube.ngc` 共用 PUMA machine context；
+  - 目标是形成 PUMA 双案例 browser diagnostics evidence。
+- `axis/rose_engine/rcone_demo.ngc`
+  - 当前 Node `INV`；
+  - HAL process only；
+  - 适合作为非 Qt、非复杂 vismach remap 的轻量 browser diagnostics 案例。
+
+### 8. 设计 macro/load 非主程序 promotion
+
+不要把 macro/load 当 browser main program 执行。
+
+候选只作为 non-main fixture evidence：
+
+- `axis/external_offsets/queuebuster.ngc`；
+- `axis/rose_engine/rcone.ngc`；
+- `gscreen/silverdragon/macros/tool_sensor.ngc`；
+- `gscreen/industrial_lathe_wear/toolchange.ngc`；
+- `qtvcp_screens/industrial_lathe_wear/toolchange.ngc`。
+
+需要新增独立报告，而不是复用 main-program promotion：
+
+- `createVirtualHalSimConfigMacroLoadFixtureReport()`；
+- 或将其作为 promotion candidate report 的 `nonMainFixture` 分类。
+
+### 9. 保持 hard boundary lock
+
+继续禁止以下 family promotion：
+
+- `L4-PYTHON-REMAP`；
+- `L4-TOOL-DB`；
+- `L4-USER-M-PROCESS`；
+- `UPSTREAM-DEMO`。
+
+这些只能通过 LinuxCNC-owned runtime proof 解锁，不能由 virtual HAL、browser UI、
+SDK glue 或 JS fixture 解锁。
+
+六、建议下一批实际执行目标
+
+下一批建议只做一个完整闭环：
+
+1. 新增 promotion candidate report；
+2. 新增 candidate report Node gate；
+3. 将 `qtdragon/qtdragon_multi_joint/on_abort.ngc` 纳入 browser diagnostics evidence；
+4. release diagnostics validation 增加 candidate evidence ready 校验；
+5. docs / matrix 只做最小同步；
+6. inventory baseline 不变。
+
+七、建议验证命令
+
+每批至少运行：
+
+```bash
+git diff --check
+wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.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
+SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
+```
+
+如涉及 release artifact / URL workflow，再运行：
+
+```bash
+wasm-port/tests/sdk/node/verify_project_release_artifact_url_workflow.sh
+wasm-port/tests/host/verify_project_release_readiness_artifact.sh
+wasm-port/tests/sdk/node/verify_project_batch_acceptance_artifact.sh
+```
+
+如涉及 ini-panel workflow overview，再运行：
+
+```bash
+SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
+wasm-port/tests/ui/node/verify_ui_node_smokes.sh
+```
+
+八、后续记录规则
+
+- 后续进度只追加到 `text18.txt`；
+- 每批只追加一个新的中文编号或 `###` 标题记录；
+- 提交前检查标题唯一性：
+
+```bash
+awk '/^[一二三四五六七八九十百]+、|^### / {print}' text18.txt | sort | uniq -d
+```
+
+- 不复制 `text17.txt` 的长历史；
+- 不把局部重排、断言挪动、路径整理作为主目标；
+- 每批必须产出至少一种可复用能力、可执行 gate、可验证 workflow 或明确 runtime
+  boundary proof；
+- 对外表述必须同时说明：
+  - virtual HAL 已完全满足 Web 方式数控系统仿真系统；
+  - 在仿真范围内，virtual HAL 已替代 LinuxCNC realtime HAL / halcmd /
+    motion controller；
+  - 它不是 Linux kernel hard-realtime ABI；
+  - 它不替代外部硬件驱动 ABI、native HAL module ABI；
+  - G-code/interpreter/planner/canonical motion 语义仍来自 LinuxCNC-backed WASM。
+
+### 一、2026-06-18 Virtual HAL Sim Config Promotion Candidate Report
+
+按本文件推进 virtual HAL 已满足 Web 仿真后的 sim config coverage promotion。本批完成
+“下一批实际执行目标”的第 1 到第 4 项：新增 source-derived promotion candidate report，
+新增 Node/browser gate，并把 `qtdragon/qtdragon_multi_joint/on_abort.ngc` 纳入 browser
+diagnostics / release validation evidence。inventory baseline 保持不变。
+
+新增实质能力：
+
+- 新增 `VIRTUAL_HAL_SIM_CONFIG_PROMOTION_CANDIDATES`：
+  - `qtdragon-multi-joint-on-abort`；
+  - `qtdragon-xyz-on-abort`；
+  - `qtdragon-xyz45-on-abort`；
+  - `qtdragon-hd-xyz-on-abort`；
+  - `qtdragon-hd-z-compensation-on-abort`；
+  - `qtvcp-screens-qtdragon-on-abort`；
+  - `puma-seam-weld`；
+  - `rose-engine-rcone-demo`；
+- 每个 candidate row 记录：
+  - LinuxCNC INI source file；
+  - LinuxCNC G-code source file；
+  - current Node inventory status；
+  - current matrix browser status；
+  - dependency class；
+  - target browser evidence；
+  - required virtual HAL reports；
+  - blocked-family exclusion；
+- 新增 `createVirtualHalSimConfigPromotionCandidateReport()`：
+  - 输出 `linuxcnc-wasm-virtual-hal-sim-config-promotion-candidate-report`；
+  - 校验 source manifest；
+  - 校验 candidate 不属于 `L4-PYTHON-REMAP` / `L4-TOOL-DB` /
+    `L4-USER-M-PROCESS` / `UPSTREAM-DEMO`；
+  - 校验 current Node inventory status 为 `PASS`；
+  - 校验 required virtual HAL reports complete：
+    source compliance、sim-config source coverage、command fixtures、
+    manifest-backed motion matrix；
+  - 显式输出 `inventoryBaselineUnchanged === true`；
+- `createLinuxCncVirtualHalRuntime()` 新增：
+  - `getSimConfigPromotionCandidateReport()`；
+- SDK index、SDK README、browser simulation re-export 同步导出新常量和新 report API；
+- real simulation page 新增：
+  - `getVirtualHalSimConfigPromotionCandidateReport()`；
+  - diagnostics artifact 字段 `virtualHalSimConfigPromotionCandidates`；
+- release diagnostics validation 新增 candidate evidence 识别：
+  - `hasPromotionCandidates`；
+  - `promotionCandidatesReady`；
+  - validation row：`sim-config-promotion-candidates`；
+  - 如果 diagnostics artifact 携带 candidate report，则必须 complete；
+  - 首批要求 `qtdragon-multi-joint-on-abort` candidate ready，且包含
+    `qtdragon_xyyz.ini` 与 `on_abort.ngc` source evidence；
+- release URL workflow fixtures、ini-panel workflow fixtures 同步携带 candidate evidence。
+
+新增/扩展验证：
+
+- `verify_sdk_surface.mjs` 覆盖：
+  - 新常量导出；
+  - 新 report API 导出；
+  - SDK README 文档化；
+  - candidate report complete；
+  - `inventoryBaselineUnchanged === true`；
+  - blocked candidate 为 0；
+  - missing manifest files 为 0；
+  - missing required virtual HAL reports 为 0；
+  - `qtdragon-multi-joint-on-abort` row ready；
+  - runtime wrapper 可读取 candidate report；
+  - release browser diagnostics validation 识别 candidate evidence ready；
+- `real_simulation_page_smoke.html` 覆盖：
+  - browser API 暴露 `getVirtualHalSimConfigPromotionCandidateReport()`；
+  - diagnostics artifact 内嵌 complete candidate report；
+  - candidate report 包含 `qtdragon-multi-joint-on-abort`；
+  - candidate row current Node status 为 `PASS`；
+  - candidate row target browser evidence 为 `explicit-browser-diagnostics`；
+- `verify_project_release_artifact_url_workflow.mjs` 覆盖：
+  - diagnostics artifact 携带 candidate evidence；
+  - URL workflow diagnostics validation `hasPromotionCandidates === true`；
+  - URL workflow diagnostics validation `promotionCandidatesReady === true`；
+- `verify_ini_panel_ui_shell.mjs` 覆盖：
+  - ini-panel URL workflow diagnostics validation 识别 candidate evidence；
+  - diagnostics validation candidate evidence ready；
+- `ini_panel_workflow_overview_smoke.html` 使用带 candidate evidence 的 diagnostics fixture。
+
+关键验证：
+
+```text
+sim_configs_coverage_docs_node_smoke=ok
+project_release_artifact_url_workflow_node_smoke=ok
+sdk_surface_node_smoke=ok
+project_release_gate_manifest_node_smoke=ok
+project_batch_acceptance_workflow_node_smoke=ok
+project_batch_acceptance_artifact_node_smoke=ok
+browser_real_simulation_page_smoke=ok
+ini_panel_ui_shell_node_smoke=ok
+browser_ini_opfs_smoke=ok
+browser_ini_control_page_smoke=ok
+browser_ini_launch_smoke=ok
+browser_ini_workflow_overview_smoke=ok
+browser_ini_shell_integration_workflow_smoke=ok
+git diff --check ok
+```
+
+语义边界：
+
+- 本批没有降低 inventory skip count；
+- 当前 baseline 仍是 `executed=28`、`passed=28`、`skipped=131`、
+  `unexpected_fail=0`；
+- 本批没有新增 G-code/interpreter/planner/kinematics/remap 语义；
+- candidate report 只把已有 Node `PASS` / source-derived virtual HAL evidence 推进到
+  browser diagnostics / release validation；
+- `L4-PYTHON-REMAP`、`L4-TOOL-DB`、`L4-USER-M-PROCESS`、`UPSTREAM-DEMO` 仍保持
+  locked，不能由 virtual HAL 或 JS glue 解锁；
+- virtual HAL 仍不声称提供 Linux kernel hard-realtime ABI、外部硬件驱动 ABI 或
+  native HAL module ABI；
+- G-code/interpreter/planner/canonical motion 语义仍来自 LinuxCNC-backed WASM。
+
+下一步工作内容：
+
+1. 将 `qtdragon/qtdragon_multi_joint/on_abort.ngc` 的 explicit browser diagnostics evidence
+   同步到 coverage matrix 注释，把它从 delegated representative 记录为已具备 browser
+   diagnostics evidence。
+2. 推进 QtDragon family 其余 candidate：
+   `qtdragon_xyz`、`qtdragon_xyz45`、`qtdragon_hd_xyz`、
+   `qtdragon_hd_z_compensation`、`qtvcp_screens/qtdragon`。
+3. 将 `axis/vismach/puma/puma_seam_weld.ngc` 与 `axis/rose_engine/rcone_demo.ngc`
+   纳入 browser diagnostics candidate evidence，形成非 QtDragon 的 promotion 案例。