接入虚拟HAL会话保存恢复

结论：real simulation page 已提供显式 Save/Restore HAL Session 按钮与 browser API，使用 OPFS session snapshot 保存和恢复 virtual HAL runtime state，并随 payload 校验 source compliance、sim-config coverage、halcmd fixtures 与 motion controller matrix，证明虚拟HAL可恢复地满足Web方式数控系统仿真范围。

text17.txt

@@ -866,3 +866,87 @@ git diff --check ok
    让 release readiness 页面能显示 browser diagnostics validation rows。
 3. 扩展 motion matrix 与 LinuxCNC sim configs 的关联，把 external-offsets、QtDragon
    multi-joint、vismach remap sims 的 motion source evidence 显式映射到 matrix fixture rows。
+
+### 九、2026-06-17 Real Simulation Virtual HAL Session Save/Restore
+
+继续按本文件铁律推进：虚拟 HAL 的功能完全来源于 LinuxCNC 源程序，并且虚拟 HAL
+完全满足 Web 方式数控系统仿真系统。本批完成上一节下一步第 1 项，把 virtual HAL
+session payload 接入 real simulation page 的显式保存/恢复按钮与 browser API，让用户可在
+Web CNC 仿真页面直接保存和恢复完整 virtual HAL runtime state。
+
+新增实质能力：
+
+- `runtime/opfs/snapshot-store.js` 扩展 virtual HAL session payload：
+  - 新增 `motionControllerMatrix`；
+  - payload validation 要求 motion controller matrix complete；
+  - `createVirtualHalSessionPayload()` 默认生成 motion matrix evidence；
+- real simulation page 新增 Machine Session 面板控件：
+  - `Save HAL Session`；
+  - `Restore HAL Session`；
+  - `Virtual HAL session` 状态行；
+- Browser simulation API 新增：
+  - `getVirtualHalSessionState()`；
+  - `saveVirtualHalSessionSnapshot(options)`；
+  - `restoreVirtualHalSessionSnapshot(options)`；
+- 保存流程：
+  - 使用当前 `virtualHalState` 创建 `createVirtualHalSessionPayload()`；
+  - 使用 `createMachineSessionSnapshotPayload()` 封装 machine/session payload；
+  - 使用 `saveSessionSnapshot()` 写入 OPFS；
+  - snapshot metadata 记录 `real-browser-simulation-virtual-hal-session` 与 HAL revision；
+- 恢复流程：
+  - 使用 `loadSessionSnapshot()` 读取 OPFS snapshot；
+  - 使用 `restoreVirtualHalStateFromSessionSnapshot()` 恢复 virtual HAL state；
+  - 重新渲染 HAL machine state、statusbar 和 session 状态；
+- SDK README OPFS/session persistence section 同步说明：
+  - `createVirtualHalSessionPayload()`；
+  - `restoreVirtualHalStateFromSessionSnapshot()`；
+  - payload 包含 source compliance、sim-config coverage、halcmd fixtures、motion
+    controller matrix evidence。
+
+新增/扩展验证：
+
+- `verify_file_service.mjs` 覆盖：
+  - virtual HAL session payload 内含 motion controller matrix complete；
+  - machine session snapshot payload 内含 motion matrix LinuxCNC source evidence；
+- `verify_sdk_surface.mjs` 覆盖：
+  - virtual HAL session payload 内含 motion controller matrix complete；
+- `real_simulation_page_smoke.html` 覆盖：
+  - 页面存在显式保存/恢复按钮；
+  - browser API 暴露保存/恢复方法；
+  - 保存当前 HAL net、loaded component、function、source reports、motion matrix；
+  - 保存后修改 HAL pin 与 loadusr state；
+  - 恢复后 `axis.x.pos-cmd` 回到保存值；
+  - 恢复后临时 `post-save-component` 不再存在；
+  - 恢复后 `motion-controller` function 仍存在；
+  - DOM/body dataset 显示 saved/restored 状态。
+
+关键验证：
+
+```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_real_simulation_page_smoke=ok
+git diff --check ok
+```
+
+语义边界：
+
+- 本批没有新增 G-code/interpreter/planner/kinematics 语义；
+- session snapshot 只保存和恢复 Web virtual HAL runtime state、source reports 和
+  diagnostics evidence；
+- virtual HAL 仍不声称提供 Linux kernel hard-realtime ABI、外部硬件驱动 ABI 或 native
+  HAL module ABI；
+- Web 仿真 HAL 的满足性现在可在 real simulation page 中由用户显式保存、恢复并继续验证。
+
+下一步工作内容：
+
+1. 将 browser diagnostics artifact 的 URL workflow 接入 ini-panel workflow overview 页面，
+   让 release readiness 页面能显示 browser diagnostics validation rows。
+2. 扩展 motion matrix 与 LinuxCNC sim configs 的关联，把 external-offsets、QtDragon
+   multi-joint、vismach remap sims 的 motion source evidence 显式映射到 matrix fixture rows。
+3. 将 real simulation page 的 virtual HAL session snapshot 与 release diagnostics artifact
+   做联动，使保存的 Web CNC 仿真会话可直接输出 release-ready diagnostics evidence。