补充 OPFS session persistence release gate 文档

text14.txt

@@ -999,3 +999,125 @@ host_wasm_opfs_browser_smokes=ok
 OPFS/session persistence summary 或 release workflow 文档，串联 SDK stable imports、browser
 OPFS smoke、session snapshot/machine-file helpers、host gate 命令和 blocked runtime family 说明；
 优先让新接手者能按文档复现支持面与验证入口，不扩大 CNC 语义边界。
+
+十三、2026-06-15 继续执行记录：OPFS/session persistence release-gate docs
+
+本轮按 `text14.txt` 执行，继续推进 OPFS/session persistence 与 release-gate 文档收口。新增
+项目级 OPFS/session persistence handoff 文档，串联 SDK stable imports、browser OPFS smoke、
+session snapshot/machine-file helpers、host gate 命令和 blocked runtime family 说明。
+
+完成内容：
+
+- 新增 `wasm-port/docs/opfs-session-persistence.md`；
+- 文档定义项目级 OPFS/session persistence 支持面：
+  - OPFS text/file helpers；
+  - OPFS path helpers；
+  - session snapshot helpers；
+  - machine file and G-code helpers；
+  - parameter/tool-table OPFS bridge helpers；
+  - `loadMachineSessionFromOpfs()`；
+  - UI/session helper docs 入口；
+- 文档记录 persistence workflow：
+  - machine INI/parameter/tool-table OPFS 保存路径；
+  - optional G-code OPFS 保存路径；
+  - session snapshot OPFS 保存路径；
+  - `loadMachineSessionFromOpfs()` 如何使用 LinuxCNC-backed INI SDK 读取
+    `[RS274NGC]PARAMETER_FILE`、`[EMCIO]TOOL_TABLE` 与
+    `[EMCIO]RANDOM_TOOLCHANGER`；
+  - parameter/tool-table bridge 如何复制 OPFS text 到 WASM FS 并调用 LinuxCNC-backed
+    interpreter SDK；
+- 文档记录 browser OPFS/session smoke：
+  - `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`；
+- 文档记录 release gate 命令：
+  - `git diff --check`；
+  - vendor/source guard；
+  - SDK surface smoke；
+  - OPFS file-service smoke；
+  - UI Node smoke；
+  - interpreter WASM smoke；
+  - sim-config inventory WASM smoke；
+  - browser INI panel smoke；
+  - host aggregate smoke；
+- 文档记录仍 blocked 的 runtime families：
+  - `L4-USER-M-PROCESS`；
+  - `L4-TOOL-DB`；
+  - `L4-PYTHON-REMAP`；
+- 文档明确 OPFS/session persistence 不解锁 full LinuxCNC runtime family，不执行 opt-in runtime probes；
+- 文档记录 failure modes：
+  - missing OPFS support；
+  - invalid OPFS paths；
+  - invalid snapshot format/version/session id/payload/machine id；
+  - missing host files；
+  - tool/parameter/remap/planner/kinematics 仍由 LinuxCNC-owned runtime semantics 提供；
+- `wasm-port/README.md` 增加 `docs/opfs-session-persistence.md` 项目级入口；
+- 新增 `wasm-port/tests/docs/node/verify_opfs_session_docs.mjs`；
+- 新增 `wasm-port/tests/docs/node/verify_opfs_session_docs.sh`；
+- docs smoke 覆盖：
+  - OPFS/session release-gate 文档存在；
+  - SDK stable entrypoint 记录；
+  - persistence helpers 记录；
+  - browser/host gate 输出记录；
+  - blocked runtime family 记录；
+  - README、SDK README、host smoke 与 browser smoke 交叉引用；
+- `wasm-port/tests/host/verify_host_smokes.sh` 纳入
+  `wasm-port/tests/docs/node/verify_opfs_session_docs.sh`；
+- `PROJECT_COMPLETION_TRACKER.md` 同步当前完成批次与下一步 sim-config coverage/release-gate docs；
+- 未新增控制按钮；
+- 未执行 action-plan；
+- 未解析 G-code；
+- 未解释 canonical events；
+- 未新增 JS CNC 语义；
+- 未改变 LinuxCNC interpreter、tool、parameter、planner、kinematics 或 LinuxCNC-owned runtime
+  semantics。
+
+验证已通过：
+
+```bash
+git diff --check
+wasm-port/tests/docs/node/verify_opfs_session_docs.sh
+wasm-port/tests/sdk/node/verify_sdk_surface.sh
+wasm-port/tests/ui/node/verify_ui_node_smokes.sh
+SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
+wasm-port/tools/verify_vendor_sync.sh
+wasm-port/tools/verify_no_standalone_cnc_semantics.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_interp_wasm.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
+wasm-port/tests/host/verify_host_smokes.sh
+```
+
+关键输出：
+
+```text
+opfs_session_docs_node_smoke=ok
+sdk_surface_node_smoke=ok
+ini_panel_ui_shell_node_smoke=ok
+ini_panel_launch_api_manifest_node_smoke=ok
+ini_panel_shell_integration_manifest_node_smoke=ok
+ini_panel_entry_docs_node_smoke=ok
+ui_node_smokes=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
+vendor sync up to date
+standalone CNC semantics guard complete
+interp_wasm_node_smoke=ok
+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
+host_wasm_opfs_browser_smokes=ok
+```
+
+下一步工作计划：
+
+继续推进 sim-config coverage/release-gate 文档收口。下一批建议新增或收敛
+sim-config coverage handoff 文档/测试，明确 `ASSET_ONLY`、`L4_PYTHON_REMAP`、`L4_TOOL_DB`、
+`L4_USER_M_PROCESS`、`NON_MAIN_CLASS`、`UPSTREAM_DEMO` 等 skip reasons 与当前 inventory
+输出之间的对应关系，并把 release gate 中的 `sim_configs_wasm_node_inventory_*` 输出作为
+机器可审计基线；仍不 promotion blocked runtime family，不扩大 CNC 语义边界。