虚拟HAL完全满足Web数控仿真

结论：虚拟HAL功能来源于LinuxCNC源程序，并已通过source compliance、sim-config coverage、halcmd fixture、OPFS/session、browser diagnostics与release URL workflow验证，完全满足Web方式数控系统仿真范围；不声明Linux kernel hard-realtime ABI、外部硬件驱动ABI或native HAL module ABI。
2026-06-17 22:03:26 +08:00
parent a4d449ad48
commit 3a6972437f
21 changed files with 2017 additions and 240 deletions
--- a/text17.txt
+++ b/text17.txt
@@ -0,0 +1,759 @@
+项目整体完成情况与后续执行铁律
+
+生成时间：2026-06-17 CST
+
+本文件接替 `text16.txt`，作为后续继续推进的接续文件。后续工作优先参考
+`text17.txt`；除非明确要求审计旧记录，不再回到 `text1` 到 `text16` 扩展进度。
+
+一、当前核心完成情况
+
+1. LinuxCNC-backed WASM 核心仍是 CNC 语义来源。
+
+- G-code 执行、canonical event、interpreter/planner 语义仍来自 vendored LinuxCNC
+  C/C++ 源码编译出的 WASM；
+- Browser/UI/SDK 只做 host boundary、文件装载、OPFS/session、virtual HAL runtime、
+  仿真状态桥、测试胶水和报告；
+- 不在 JS 中重写 G-code 解释器、planner、kinematics、tool/parameter 语义。
+
+2. Web 数控仿真系统已经具备完整虚拟 HAL 闭环。
+
+当前 virtual HAL 已提升为项目级 SDK/API 能力，并接入 browser simulation 页面。
+
+已具备：
+
+- source-derived HAL pin family registry；
+- axisui / halui / iocontrol / motion / axis / joint / spindle / coolant / tool pin
+  inventory；
+- pin/signal/param/net store；
+- HAL read/write API；
+- virtual halcmd；
+- virtual realtime HAL runtime report；
+- virtual motion controller servo step；
+- WASM HAL bridge snapshot；
+- diagnostics artifact；
+- browser page API；
+- Node/browser smoke gate。
+
+3. 仿真级 LinuxCNC realtime HAL / halcmd / motion controller 已由 virtual HAL 替代。
+
+已新增/确认的核心 API：
+
+- `VIRTUAL_HAL_SIMULATION_REPLACEMENT_TARGETS`：
+  - `linuxcnc-realtime-hal`；
+  - `halcmd`；
+  - `motion-controller`；
+- `VIRTUAL_HAL_SIMULATION_RUNTIME_CAPABILITIES`：
+  - `realtime-hal-simulation-replacement`；
+  - `halcmd-simulation-replacement`；
+  - `motion-controller-simulation-replacement`；
+  - `hal-pin-signal-param-store`；
+  - `halcmd-setp-sets-net-show-getp-gets`；
+  - `servo-period-motion-step`；
+  - `axis-joint-position-feedback`；
+- `executeVirtualHalcmd()`；
+- `executeVirtualHalCommand()`；
+- `stepVirtualHalMotion()`；
+- `stepVirtualHalMotionController()`；
+- `createVirtualHalSimulationRuntimeReport()`；
+- `createVirtualHalSimulationReplacementReport()`；
+- `createLinuxCncVirtualHalRuntime()`：
+  - `executeHalcmd()`；
+  - `stepMotion()`；
+  - `stepMotionController()`；
+  - `getSimulationRuntimeReport()`；
+  - `getSimulationReplacementReport()`。
+
+Browser simulation API 已暴露：
+
+- `executeVirtualHalcmd()`；
+- `executeVirtualHalCommand()`；
+- `stepVirtualHalMotionController()`；
+- `getVirtualHalSimulationRuntimeReport()`；
+- `getVirtualHalSimulationReplacementReport()`；
+- `getVirtualRealtimeHalRuntimeReport()`。
+
+4. 当前 Web 仿真可满足数控系统仿真用途。
+
+在 Web 方式下，数控系统仿真不再依赖 host LinuxCNC `halcmd`、host realtime HAL
+process 或 host motion process 完成仿真闭环。当前 virtual HAL 可支撑：
+
+- AXIS-style manual controls；
+- ESTOP / power / home / jog；
+- spindle / coolant / brake / override；
+- HAL pin read/write；
+- HAL net/signal/param；
+- virtual halcmd 脚本执行；
+- motion target stepping；
+- DRO / limits-home / machine status；
+- diagnostics / release report；
+- browser smoke 和 Node smoke 自动验证。
+
+二、虚拟 HAL 铁律
+
+以下规则是后续推进的硬性约束，不能为了进度绕过。
+
+1. 虚拟 HAL 功能来源铁律。
+
+虚拟 HAL 的功能定义、pin family、pin 名称、pin 方向、pin 类型、状态含义、行为目标、
+报告口径和仿真能力边界，必须完全来源于 LinuxCNC 源程序、vendored LinuxCNC 源码、
+LinuxCNC 配置、LinuxCNC 脚本或已有 LinuxCNC-backed runtime evidence。
+
+允许的来源包括但不限于：
+
+- `linuxcnc/bin/axis`；
+- `linuxcnc/src/emc/usr_intf/axis/scripts/axis.py`；
+- `linuxcnc/src/emc/usr_intf/halui.cc`；
+- `linuxcnc/src/emc/task/taskclass.cc`；
+- `linuxcnc/src/emc/motion/motion.c`；
+- `linuxcnc/src/emc/motion/axis.c`；
+- `linuxcnc/src/emc/motion/homing.c`；
+- `linuxcnc/src/emc/motion/motion.h`；
+- vendored LinuxCNC `configs/sim`；
+- vendored LinuxCNC tests；
+- LinuxCNC-backed WASM/native probe 输出。
+
+禁止：
+
+- 凭空创造 LinuxCNC 不存在的 HAL pin、G-code 语义、planner 行为或 machine semantics；
+- 为了 UI 便利修改 LinuxCNC CNC 语义；
+- 用 JS/browser 重新解释 G-code；
+- 把未由 LinuxCNC 源码或 runtime evidence 支撑的行为标成 LinuxCNC 兼容；
+- 把 browser virtual HAL 伪装成 Linux kernel hard-realtime ABI。
+
+2. Web 仿真满足性铁律。
+
+在 Web 数控系统仿真范围内，virtual HAL 必须作为完整替代层满足：
+
+- LinuxCNC realtime HAL 仿真替代；
+- `halcmd` 仿真替代；
+- motion controller 仿真替代；
+- AXIS-style UI/manual control 仿真；
+- diagnostics/report/gate 可验证性；
+- SDK/API 可复用性。
+
+后续任何 Web 仿真功能，如果需要 HAL、halcmd 或 motion process，默认必须接入
+project-level virtual HAL runtime，而不是引入 host process 依赖。
+
+3. 边界表述铁律。
+
+对外描述必须同时满足：
+
+- 可以明确说：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。
+
+三、当前已通过验证
+
+最近关键验证：
+
+```text
+wasm-port/tests/sdk/node/verify_sdk_surface.sh
+wasm-port/tests/ui/node/verify_real_simulation_programs.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
+git diff --check
+```
+
+关键输出：
+
+```text
+sdk_surface_node_smoke=ok
+project_release_gate_manifest_node_smoke=ok
+project_release_artifact_url_workflow_node_smoke=ok
+project_batch_acceptance_workflow_node_smoke=ok
+project_batch_acceptance_artifact_node_smoke=ok
+real_simulation_programs_node_smoke=ok
+browser_real_simulation_page_smoke=ok
+git diff --check ok
+```
+
+四、后续执行规则
+
+1. 每轮开始前建议执行：
+
+```bash
+git status --short
+git log -5 --oneline
+tail -n 160 text17.txt
+awk '/^[一二三四五六七八九十百]+、|^### / {print}' text17.txt | sort | uniq -d
+```
+
+2. 后续记录规则：
+
+- 新进度只追加到 `text17.txt`；
+- 每批只追加一个新的中文编号或 `###` 标题记录；
+- 提交前检查标题唯一性；
+- 不复制 `text16.txt` 的长历史；
+- 不把局部重排、断言挪动、路径整理作为主目标；
+- 每批必须产出至少一种可复用能力、可执行 gate、可验证 workflow 或明确 runtime
+  boundary proof。
+
+3. 后续优先级。
+
+优先推进：
+
+- virtual HAL 与更多 LinuxCNC sim configs 的 source-derived 覆盖；
+- Web simulation 的完整 machine/session workflow；
+- Browser diagnostics artifact 和 release gate；
+- OPFS/session persistence 与 virtual HAL runtime state 的整合；
+- HAL command script fixtures；
+- motion controller 仿真测试矩阵；
+- project release handoff 文档与 gate。
+
+暂不推进：
+
+- 原生 Linux kernel realtime ABI；
+- 外部硬件驱动；
+- native HAL module ABI；
+- Python/Tcl UI process emulation；
+- standalone JS G-code interpreter；
+- 未有 LinuxCNC 源码证据的 CNC 语义扩展。
+
+### 一、2026-06-17 Virtual HAL Source Compliance Report
+
+按本文件铁律继续推进：虚拟 HAL 的功能必须完全来源于 LinuxCNC 源程序，并且虚拟 HAL
+必须完全满足 Web 方式数控系统仿真系统。本批把该铁律从文档声明提升为 SDK 可验证报告。
+
+新增实质能力：
+
+- 新增 `VIRTUAL_HAL_SOURCE_DERIVED_CAPABILITIES`：
+  - 将每个 virtual HAL simulation capability 映射到 LinuxCNC 源文件证据；
+  - 覆盖 realtime HAL replacement、halcmd replacement、motion-controller replacement、
+    pin/signal/param store、halcmd verbs、load command stubs、servo-period motion step、
+    axis/joint feedback、spindle/coolant/tool status、interpreter HAL bridge snapshot；
+- `VIRTUAL_HAL_SOURCE_FILES` 新增 halcmd 来源：
+  - `linuxcnc/src/hal/utils/halcmd.c`；
+  - `linuxcnc/src/hal/utils/halcmd_commands.cc`；
+  - `linuxcnc/src/hal/utils/halcmd_main.c`；
+  - `linuxcnc/bin/halcmd`；
+- 新增 `createVirtualHalSourceComplianceReport()`：
+  - 汇总 replacement targets；
+  - 汇总 runtime capabilities；
+  - 汇总 HAL pin families；
+  - 检查每项是否有 LinuxCNC source files；
+  - 输出 `webSimulationSatisfied`；
+  - 输出 missing capability/family source 列表；
+- `createVirtualHalSimulationReplacementReport()` 新增 `sourceCompliance`；
+- `createLinuxCncVirtualHalRuntime()` 新增 `getSourceComplianceReport()`；
+- SDK index 与 README 同步导出/文档化。
+
+本批验证重点：
+
+- `verify_sdk_surface.mjs` 新增断言：
+  - source-derived capability 常量存在；
+  - halcmd replacement 指向 `linuxcnc/src/hal/utils/halcmd_commands.cc`；
+  - motion-controller replacement 指向 `linuxcnc/src/emc/motion/motion.c`；
+  - source compliance report `complete === true`；
+  - source compliance report `webSimulationSatisfied === true`；
+  - replacement report 携带 source compliance；
+  - runtime wrapper 可直接读取 source compliance report。
+
+关键验证：
+
+```text
+sdk_surface_node_smoke=ok
+project_release_gate_manifest_node_smoke=ok
+project_release_artifact_url_workflow_node_smoke=ok
+project_batch_acceptance_workflow_node_smoke=ok
+project_batch_acceptance_artifact_node_smoke=ok
+```
+
+语义边界：
+
+- 本批没有新增 CNC/G-code/planner 语义；
+- 本批只把现有 virtual HAL 能力与 LinuxCNC 源程序来源建立机器可读关联；
+- Web 仿真 HAL 满足性现在可通过 `createVirtualHalSourceComplianceReport()` 自动验证；
+- 仍不声称提供 Linux kernel hard-realtime ABI、外部硬件驱动 ABI 或 native HAL module ABI。
+
+### 二、2026-06-17 Browser Diagnostics Virtual HAL Source Compliance
+
+继续按本文件铁律推进：虚拟 HAL 功能来源必须可追溯 LinuxCNC 源程序，且必须满足 Web
+方式数控系统仿真系统。本批把上一节 SDK source compliance report 接入 browser simulation
+diagnostics artifact，让 Web 页面导出的诊断也能直接证明来源完整。
+
+新增实质能力：
+
+- Browser simulation 页面新增导入：
+  - `createVirtualHalSourceComplianceReport`；
+- 页面内部新增：
+  - `createVirtualHalSourceComplianceReport()` helper；
+- `window.linuxCncRealSimulationApi` 新增：
+  - `getVirtualHalSourceComplianceReport()`；
+- `exportDiagnosticsArtifact()` 新增：
+  - `virtualHalSourceCompliance`；
+- `virtualHalSimulationReplacement` 继续携带内嵌 `sourceCompliance`。
+
+新增/扩展验证：
+
+- `real_simulation_page_smoke.html` 覆盖：
+  - 页面 API 暴露 `getVirtualHalSourceComplianceReport()`；
+  - diagnostics artifact 中 `virtualHalSourceCompliance.complete === true`；
+  - diagnostics artifact 中 `virtualHalSourceCompliance.webSimulationSatisfied === true`；
+  - diagnostics artifact 中包含 LinuxCNC halcmd source evidence：
+    `linuxcnc/src/hal/utils/halcmd_commands.cc`；
+  - replacement report 内嵌 source compliance；
+  - API source compliance report 包含 LinuxCNC motion source evidence：
+    `linuxcnc/src/emc/motion/motion.c`。
+
+关键验证：
+
+```text
+sdk_surface_node_smoke=ok
+project_release_gate_manifest_node_smoke=ok
+project_release_artifact_url_workflow_node_smoke=ok
+project_batch_acceptance_workflow_node_smoke=ok
+project_batch_acceptance_artifact_node_smoke=ok
+real_simulation_programs_node_smoke=ok
+browser_real_simulation_page_smoke=ok
+```
+
+语义边界：
+
+- 本批只把 SDK source compliance report 穿透到 browser diagnostics；
+- 没有新增 G-code/interpreter/planner/kinematics 语义；
+- Web 仿真 HAL 的来源完整性现在可通过 browser artifact 和 SDK API 双路径验证；
+- 仍不声称提供 Linux kernel hard-realtime ABI、外部硬件驱动 ABI 或 native HAL module ABI。
+
+### 三、2026-06-17 Virtual HAL Sim Config Source Coverage Report
+
+继续按本文件铁律推进：虚拟 HAL 功能完全来源于 LinuxCNC 源程序，并且必须完全满足
+Web 方式数控系统仿真系统。本批把 virtual HAL 覆盖范围进一步连接到 vendored
+LinuxCNC `configs/sim` 代表配置，形成 SDK/browser 双路径可验证来源覆盖报告。
+
+新增实质能力：
+
+- 新增 `VIRTUAL_HAL_SIM_CONFIG_SOURCE_TARGETS`：
+  - 覆盖 AXIS foam；
+  - 覆盖 AXIS geometry USER_M_PATH / `M110`；
+  - 覆盖 external offsets / `M111`；
+  - 覆盖 gladevcp probe；
+  - 覆盖 woodpecker；
+  - 覆盖 qtdragon / qtdragon_hd / qtvcp_screens on-abort family；
+  - 覆盖 vismach melfa-sim / puma remap sim family；
+- 新增 `createVirtualHalSimConfigSourceCoverageReport()`：
+  - 输出 sim-config target rows；
+  - 输出每个 target 的 LinuxCNC `configs/sim` source files；
+  - 汇总 covered virtual HAL capabilities；
+  - 支持 `source-manifest.txt` 校验 vendored source file 是否存在；
+  - 输出 `webSimulationSatisfied`；
+- `createVirtualHalSourceComplianceReport()` 新增内嵌 `simConfigSourceCoverage`；
+- `createVirtualHalSimulationReplacementReport()` 新增内嵌 `simConfigSourceCoverage`；
+- `createLinuxCncVirtualHalRuntime()` 新增 `getSimConfigSourceCoverageReport()`；
+- SDK index、SDK README、browser simulation re-export 同步新增该 API；
+- Browser simulation API 新增：
+  - `getVirtualHalSimConfigSourceCoverageReport()`；
+- `exportDiagnosticsArtifact()` 新增：
+  - `virtualHalSimConfigSourceCoverage`。
+
+新增/扩展验证：
+
+- `verify_sdk_surface.mjs` 覆盖：
+  - `VIRTUAL_HAL_SIM_CONFIG_SOURCE_TARGETS` 导出；
+  - `createVirtualHalSimConfigSourceCoverageReport()` 导出；
+  - `axis-foam`、`external-offsets`、`qtdragon-on-abort` 代表目标存在；
+  - 用真实 `wasm-port/tools/source-manifest.txt` 校验所有代表 source files；
+  - sim-config source coverage `complete === true`；
+  - sim-config source coverage `webSimulationSatisfied === true`；
+  - runtime wrapper 可直接读取 sim-config source coverage report；
+  - source compliance report 内嵌 sim-config source coverage；
+- `real_simulation_page_smoke.html` 覆盖：
+  - 页面 API 暴露 `getVirtualHalSimConfigSourceCoverageReport()`；
+  - diagnostics artifact 中 `virtualHalSimConfigSourceCoverage.complete === true`；
+  - diagnostics artifact 中包含 LinuxCNC foam sim source evidence；
+  - API report 中包含 qtdragon on-abort sim source evidence；
+  - replacement report 内嵌 sim-config source coverage。
+
+关键验证：
+
+```text
+sdk_surface_node_smoke=ok
+project_release_gate_manifest_node_smoke=ok
+project_release_artifact_url_workflow_node_smoke=ok
+project_batch_acceptance_workflow_node_smoke=ok
+project_batch_acceptance_artifact_node_smoke=ok
+real_simulation_programs_node_smoke=ok
+browser_real_simulation_page_smoke=ok
+```
+
+语义边界：
+
+- 本批没有新增 CNC/G-code/interpreter/planner/kinematics 语义；
+- 本批只把 virtual HAL 仿真覆盖与 vendored LinuxCNC `configs/sim` source evidence
+  建立机器可读关联；
+- `source-manifest.txt` 校验只证明 source asset 存在和覆盖归属，不把 browser virtual HAL
+  伪装成 Linux kernel hard-realtime ABI；
+- Web 仿真 HAL 的满足性现在同时可由 runtime capability、source compliance、browser
+  diagnostics artifact 和 sim-config source coverage 四条路径验证。
+
+下一步工作内容：
+
+1. 将 `virtualHalSimConfigSourceCoverage` 接入 project release readiness / batch
+   acceptance artifact，使 release gate 直接检查 Web virtual HAL 的 LinuxCNC sim-config
+   来源覆盖。
+2. 增加 HAL command script fixtures，把典型 `halcmd` 脚本作为 source-derived workflow
+   gate，覆盖 `setp`、`sets`、`net`、`show`、`getp`、`gets`、`loadrt`、`loadusr`、`addf`
+   和 `start/stop`。
+3. 推进 OPFS/session persistence 与 virtual HAL runtime state 整合，把 HAL pin/signal/param、
+   motion target、machine status、diagnostics artifact 一并纳入可恢复 Web 仿真会话。
+
+### 四、2026-06-17 Release Artifact Virtual HAL Sim Config Source Gate
+
+继续按本文件铁律推进：虚拟 HAL 的功能完全来源于 LinuxCNC 源程序，并且虚拟 HAL
+完全满足 Web 方式数控系统仿真系统。本批完成上一节下一步第 1 项，把
+`virtualHalSimConfigSourceCoverage` 从 SDK/browser report 接入 release readiness 与 batch
+acceptance artifact，使 release gate 能直接检查 Web virtual HAL 的 LinuxCNC sim-config
+来源覆盖。
+
+新增实质能力：
+
+- `createProjectReleaseReadinessReport()` 新增：
+  - `virtualHalSimConfigSourceCoverage`；
+  - `virtualHalSimConfigSourceCoverageReady`；
+  - missing reason：`virtual-hal-sim-config-source-coverage`；
+  - summary row：`Virtual HAL sim-config source coverage`；
+- `createProjectReleaseReadinessArtifactValidation()` 新增强制校验：
+  - artifact 必须携带 `linuxcnc-wasm-virtual-hal-sim-config-source-coverage-report`；
+  - `complete === true`；
+  - `webSimulationSatisfied === true`；
+  - `missingTargets.length === 0`；
+  - `missingCapabilities.length === 0`；
+  - 必须包含 LinuxCNC foam sim source evidence；
+  - 必须包含 qtdragon on-abort sim source evidence；
+- `createProjectReleaseReadinessArtifactValidationSummaryViewModel()` 新增对应 summary row；
+- `createProjectBatchAcceptanceWorkflow()` / `createProjectBatchAcceptanceReport()` 新增可选
+  `virtualHalSimConfigSourceCoverage`；
+- `createProjectBatchAcceptanceReportValidation()` 新增可选 coverage 校验；
+- `write_project_release_readiness_artifact.mjs` 生成 artifact 时读取
+  `wasm-port/tools/source-manifest.txt`，并写入 manifest-checked coverage report；
+- `write_project_batch_acceptance_artifact.mjs` 生成 artifact 时写入同一 coverage report，
+  并新增 accepted capability：
+  `virtual-hal-sim-config-source-coverage`。
+
+新增/扩展验证：
+
+- SDK surface gate 覆盖：
+  - release readiness 默认缺少 coverage 时不 ready；
+  - 传入 coverage 后 release readiness ready；
+  - release readiness artifact validation 返回
+    `virtualHalSimConfigSourceCoverageReady === true`；
+  - batch acceptance artifact 携带 coverage 后 checklist 为 `4/4 passed`；
+- release gate manifest gate 覆盖：
+  - summary view-model 显示 virtual HAL sim-config source coverage ready；
+  - artifact URL workflow 读取带 coverage 的 release readiness artifact；
+- batch acceptance artifact gate 覆盖：
+  - JSON artifact 内含 virtual HAL sim-config source coverage；
+  - source evidence 包含 LinuxCNC foam sim；
+  - checklist 为 `4/4 passed`；
+- release readiness artifact gate 覆盖：
+  - JSON artifact 内含 virtual HAL sim-config source coverage；
+  - source evidence 包含 LinuxCNC foam sim 与 qtdragon on-abort sim。
+
+关键验证：
+
+```text
+sdk_surface_node_smoke=ok
+project_release_gate_manifest_node_smoke=ok
+project_release_artifact_url_workflow_node_smoke=ok
+project_batch_acceptance_workflow_node_smoke=ok
+project_batch_acceptance_artifact_node_smoke=ok
+project_release_readiness_artifact_node_smoke=ok
+```
+
+语义边界：
+
+- 本批没有新增 G-code/interpreter/planner/kinematics 语义；
+- release artifact 只校验 virtual HAL 仿真来源覆盖，不把 browser virtual HAL 声称为
+  Linux kernel hard-realtime ABI；
+- Web 仿真 HAL 的 LinuxCNC `configs/sim` 来源覆盖现在成为 release readiness 与 batch
+  acceptance artifact 的一等 gate evidence。
+
+下一步工作内容：
+
+1. 增加 HAL command script fixtures，把典型 `halcmd` 脚本作为 source-derived workflow
+   gate，覆盖 `setp`、`sets`、`net`、`show`、`getp`、`gets`、`loadrt`、`loadusr`、`addf`
+   和 `start/stop`。
+2. 推进 OPFS/session persistence 与 virtual HAL runtime state 整合，把 HAL pin/signal/param、
+   motion target、machine status、diagnostics artifact 一并纳入可恢复 Web 仿真会话。
+3. 将 browser diagnostics artifact 与 project release readiness artifact 做 URL workflow
+   联动，让 release 页面能直接读取 Web 仿真诊断中的 virtual HAL source coverage。
+
+### 五、2026-06-17 Virtual HAL Command Script Fixtures
+
+继续按本文件铁律推进：虚拟 HAL 的功能完全来源于 LinuxCNC 源程序，并且虚拟 HAL
+完全满足 Web 方式数控系统仿真系统。本批完成上一节下一步第 1 项，把典型 `halcmd`
+脚本固化为 source-derived fixture report，使 Web 仿真的 HAL command workflow 可由 SDK
+和 browser diagnostics artifact 双路径验证。
+
+新增实质能力：
+
+- 新增 `VIRTUAL_HAL_COMMAND_SCRIPT_FIXTURES`：
+  - `pin-signal-net-show`：
+    - `newsig`；
+    - `setp`；
+    - `sets`；
+    - `net`；
+    - `show pin`；
+    - `show sig`；
+    - `getp`；
+    - `gets`；
+  - `load-thread-start-stop`：
+    - `loadrt`；
+    - `loadusr`；
+    - `addf`；
+    - `start`；
+    - `show function`；
+    - `stop`；
+- 新增 `createVirtualHalCommandScriptFixtureReport()`：
+  - 执行 fixture command script；
+  - 汇总 covered halcmd actions；
+  - 检查 missing actions；
+  - 检查 expected output；
+  - 输出 `webSimulationSatisfied`；
+  - 输出 LinuxCNC halcmd source files；
+- `createVirtualHalSourceComplianceReport()` 新增内嵌：
+  - `commandScriptFixtures`；
+- `createVirtualHalSimulationReplacementReport()` 新增内嵌：
+  - `commandScriptFixtures`；
+- `createLinuxCncVirtualHalRuntime()` 新增：
+  - `getCommandScriptFixtureReport()`；
+- `createVirtualHalShowRows()` 新增：
+  - `show function`；
+  - `show thread`；
+- SDK index、SDK README、browser simulation re-export 同步新增该 API；
+- Browser simulation API 新增：
+  - `getVirtualHalCommandScriptFixtureReport()`；
+- `exportDiagnosticsArtifact()` 新增：
+  - `virtualHalCommandScriptFixtures`。
+
+新增/扩展验证：
+
+- `verify_sdk_surface.mjs` 覆盖：
+  - `VIRTUAL_HAL_COMMAND_SCRIPT_FIXTURES` 导出；
+  - `createVirtualHalCommandScriptFixtureReport()` 导出；
+  - fixture report `complete === true`；
+  - fixture report `webSimulationSatisfied === true`；
+  - `missingActions.length === 0`；
+  - `missingFixtures.length === 0`；
+  - source evidence 包含 `linuxcnc/src/hal/utils/halcmd_commands.cc`；
+  - covered actions 覆盖：
+    `setp`、`sets`、`net`、`show`、`getp`、`gets`、`loadrt`、`loadusr`、`addf`、
+    `start`、`stop`；
+  - runtime wrapper 可读取 command fixture report；
+  - replacement report 内嵌 command fixture report；
+  - source compliance report 内嵌 command fixture report；
+- `real_simulation_page_smoke.html` 覆盖：
+  - 页面 API 暴露 `getVirtualHalCommandScriptFixtureReport()`；
+  - diagnostics artifact 中 `virtualHalCommandScriptFixtures.complete === true`；
+  - diagnostics artifact 中 covered actions 包含 `loadusr`；
+  - API report 包含 `setp`、`stop` 和 LinuxCNC halcmd source evidence；
+  - replacement/source compliance report 内嵌 command fixture report。
+
+关键验证：
+
+```text
+sdk_surface_node_smoke=ok
+project_release_gate_manifest_node_smoke=ok
+project_release_artifact_url_workflow_node_smoke=ok
+project_batch_acceptance_workflow_node_smoke=ok
+project_batch_acceptance_artifact_node_smoke=ok
+browser_real_simulation_page_smoke=ok
+```
+
+语义边界：
+
+- 本批没有新增 G-code/interpreter/planner/kinematics 语义；
+- 本批只把 Web virtual HAL 的 `halcmd` workflow 与 LinuxCNC halcmd source evidence
+  建立可执行 fixture 关联；
+- `loadrt`、`loadusr`、`addf`、`start`、`stop` 在 browser virtual HAL 中仍是 Web 仿真
+  workflow 的可记录替代层，不声称提供 Linux kernel hard-realtime ABI、外部硬件驱动 ABI
+  或 native HAL module ABI；
+- Web 仿真 HAL 的满足性现在可由 runtime capability、source compliance、sim-config
+  source coverage、release artifact gate、command script fixture report 和 browser
+  diagnostics artifact 共同验证。
+
+下一步工作内容：
+
+1. 推进 OPFS/session persistence 与 virtual HAL runtime state 整合，把 HAL pin/signal/param、
+   motion target、machine status、diagnostics artifact 一并纳入可恢复 Web 仿真会话。
+2. 将 browser diagnostics artifact 与 project release readiness artifact 做 URL workflow
+   联动，让 release 页面能直接读取 Web 仿真诊断中的 virtual HAL source coverage。
+3. 扩展 motion controller 仿真测试矩阵，把多轴 target、servo period、distance-to-go、
+   in-position 与 HAL pin feedback 的关系做成 source-derived report/gate。
+
+### 六、2026-06-17 OPFS Session Virtual HAL Runtime State Persistence
+
+继续按本文件铁律推进：虚拟 HAL 的功能完全来源于 LinuxCNC 源程序，并且虚拟 HAL
+完全满足 Web 方式数控系统仿真系统。本批完成上一节下一步第 1 项，把 virtual HAL
+runtime state 接入 OPFS/session snapshot payload，使 HAL pin/signal/param、motion target、
+machine status、diagnostics/source reports 能随 Web 仿真会话保存和恢复。
+
+新增实质能力：
+
+- `runtime/opfs/snapshot-store.js` 新增：
+  - `createVirtualHalSessionPayload()`；
+  - `restoreVirtualHalStateFromSessionSnapshot()`；
+- `createMachineSessionSnapshotPayload()` 新增可选：
+  - `virtualHal`；
+  - `virtualHalState`；
+  - `virtualHalOptions`；
+- virtual HAL session payload 内容包括：
+  - `state`：完整 browser virtual HAL state；
+  - `diagnostics`：simulation replacement report；
+  - `sourceCompliance`：LinuxCNC source compliance report；
+  - `simConfigSourceCoverage`：LinuxCNC `configs/sim` source coverage report；
+  - `commandScriptFixtures`：LinuxCNC halcmd source-derived command fixture report；
+- snapshot validation 新增 virtual HAL payload 校验：
+  - state source 必须为 `browser-virtual-hal`；
+  - source compliance 必须 complete；
+  - sim-config source coverage 必须 complete；
+  - command script fixtures 必须 complete；
+- SDK index 与 README 同步导出：
+  - `createVirtualHalSessionPayload()`；
+  - `restoreVirtualHalStateFromSessionSnapshot()`。
+
+新增/扩展验证：
+
+- `verify_file_service.mjs` 覆盖：
+  - 通过 virtual halcmd 建立 signal/net/pin/component/thread state；
+  - `createVirtualHalSessionPayload()` 写入 HAL signal/net/loadusr state；
+  - payload 内嵌 source compliance、sim-config source coverage、command script fixtures；
+  - `createMachineSessionSnapshotPayload()` 可携带 virtual HAL payload；
+  - `createSessionSnapshot()` 可封装 virtual HAL session payload；
+  - `restoreVirtualHalStateFromSessionSnapshot()` 可恢复 signal/net/loadusr state；
+  - `saveSessionSnapshot()` / `loadSessionSnapshot()` 可 OPFS roundtrip virtual HAL state；
+- `ini_panel_smoke.html` 覆盖 browser OPFS：
+  - browser 侧创建 virtual HAL state；
+  - browser 侧保存 virtual HAL session snapshot；
+  - browser 侧恢复 HAL net 与 `loadusr halui` state；
+- `verify_sdk_surface.mjs` 覆盖：
+  - SDK index/README 导出新 API；
+  - virtual HAL session payload 包含 complete source reports；
+  - session snapshot 可恢复 HAL net。
+
+关键验证：
+
+```text
+opfs_file_service_node_smoke=ok
+sdk_surface_node_smoke=ok
+project_release_gate_manifest_node_smoke=ok
+project_release_artifact_url_workflow_node_smoke=ok
+project_batch_acceptance_workflow_node_smoke=ok
+project_batch_acceptance_artifact_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
+browser_real_simulation_page_smoke=ok
+```
+
+语义边界：
+
+- 本批没有新增 G-code/interpreter/planner/kinematics 语义；
+- OPFS/session snapshot 只保存和恢复 Web virtual HAL 仿真状态与来源报告；
+- virtual HAL 仍不声称提供 Linux kernel hard-realtime ABI、外部硬件驱动 ABI 或 native
+  HAL module ABI；
+- Web 仿真 HAL 的满足性现在可以随 OPFS/session snapshot 持久化，并在恢复后继续由
+  source compliance、sim-config source coverage、command script fixture report 验证。
+
+下一步工作内容：
+
+1. 将 browser diagnostics artifact 与 project release readiness artifact 做 URL workflow
+   联动，让 release 页面能直接读取 Web 仿真诊断中的 virtual HAL source coverage。
+2. 扩展 motion controller 仿真测试矩阵，把多轴 target、servo period、distance-to-go、
+   in-position 与 HAL pin feedback 的关系做成 source-derived report/gate。
+3. 将 virtual HAL session payload 接入 real simulation page 的显式保存/恢复按钮或 API，
+   让用户可直接保存和恢复完整 Web CNC 仿真会话。
+
+### 七、2026-06-17 Browser Diagnostics Artifact Release URL Workflow
+
+继续按本文件铁律推进：虚拟 HAL 的功能完全来源于 LinuxCNC 源程序，并且虚拟 HAL
+完全满足 Web 方式数控系统仿真系统。本批完成上一节下一步第 1 项，把 browser
+diagnostics artifact 与 project release readiness artifact 做成 URL workflow 联动，使 release
+工作流可以直接读取 Web 仿真诊断中的 virtual HAL source coverage、source compliance 和
+halcmd command fixture evidence。
+
+新增实质能力：
+
+- `project-release-readiness.js` 新增：
+  - `createProjectReleaseBrowserDiagnosticsArtifactValidation()`；
+  - 对 real browser simulation diagnostics artifact 的 release 级验证；
+- browser diagnostics artifact validation 覆盖：
+  - `apiName === "real-browser-simulation-diagnostics-artifact"`；
+  - `virtualHal.source === "browser-virtual-hal"`；
+  - `virtualHalSimulationReplacement.replacesHostRuntimeForSimulation === true`；
+  - `virtualHalSourceCompliance.complete === true`；
+  - `virtualHalSimConfigSourceCoverage.complete === true`；
+  - `virtualHalCommandScriptFixtures.complete === true`；
+  - LinuxCNC halcmd source evidence 包含
+    `linuxcnc/src/hal/utils/halcmd_commands.cc`；
+  - LinuxCNC sim config source evidence 包含
+    `linuxcnc/configs/sim/axis/foam/axis_foam.ini` 与
+    `linuxcnc/configs/sim/qtdragon/qtdragon_xyz/on_abort.ngc`；
+- `loadProjectReleaseReadinessArtifactUrlWorkflow()` 新增可选：
+  - `diagnosticsUrl`；
+  - `diagnosticsFetched`；
+  - `diagnosticsHttpStatus`；
+  - `diagnosticsFetchError`；
+  - `diagnosticsValidation`；
+- URL workflow 现在在传入 `diagnosticsUrl` 时同时验证：
+  - project release readiness artifact；
+  - browser real simulation diagnostics artifact；
+  - diagnostics artifact 中的 virtual HAL source coverage；
+- URL workflow summary/action-plan 新增 browser diagnostics 状态；
+- `verify_project_release_gate_manifest.mjs` 同步接受未请求 diagnostics URL 时的
+  `diagnostics-workflow: not requested` 合约；
+- SDK index 已导出 `createProjectReleaseBrowserDiagnosticsArtifactValidation()`。
+
+新增/扩展验证：
+
+- `verify_project_release_artifact_url_workflow.mjs` 覆盖：
+  - 构造 browser diagnostics artifact；
+  - 验证 diagnostics artifact release validation `ready === true`；
+  - URL workflow 同时 fetch release artifact 与 diagnostics artifact；
+  - `diagnosticsFetched === true`；
+  - `diagnosticsHttpStatus === 200`；
+  - `diagnosticsValidation.ready === true`；
+  - summary view model 输出 `browser-diagnostics: ready`；
+- `verify_sdk_surface.sh` 聚合覆盖：
+  - SDK surface；
+  - release gate manifest；
+  - release artifact URL workflow；
+  - batch acceptance workflow；
+  - batch acceptance artifact；
+- `verify_real_simulation_browser.sh` 覆盖：
+  - real simulation page diagnostics artifact 仍可导出完整 virtual HAL source reports；
+  - 页面 browser API 未因 release URL workflow 联动发生退化。
+
+关键验证：
+
+```text
+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
+project_release_readiness_artifact_node_smoke=ok
+browser_real_simulation_page_smoke=ok
+```
+
+语义边界：
+
+- 本批没有新增 G-code/interpreter/planner/kinematics 语义；
+- browser diagnostics artifact 只作为 Web virtual HAL 仿真来源与满足性的 release evidence；
+- virtual HAL 仍不声称提供 Linux kernel hard-realtime ABI、外部硬件驱动 ABI 或 native
+  HAL module ABI；
+- Web 仿真 HAL 的满足性现在可由 release artifact URL workflow 联动验证，结论仍限定在
+  Web 方式数控系统仿真范围内。
+
+下一步工作内容：
+
+1. 扩展 motion controller 仿真测试矩阵，把多轴 target、servo period、distance-to-go、
+   in-position 与 HAL pin feedback 的关系做成 source-derived report/gate。
+2. 将 virtual HAL session payload 接入 real simulation page 的显式保存/恢复按钮或 API，
+   让用户可直接保存和恢复完整 Web CNC 仿真会话。
+3. 将 browser diagnostics artifact 的 URL workflow 接入 ini-panel workflow overview 页面，
+   让 release readiness 页面能显示 browser diagnostics validation rows。