补充 OPFS session persistence release gate 文档

wasm-port/README.md

@@ -130,5 +130,8 @@ Directory intent:
 - `tests/fixtures/`: stable simulation inputs shared by native and browser tests.
 - `build/` and `dist/`: generated outputs only; never hand-edited.
 
+Project-level OPFS/session persistence and release-gate handoff is documented in
+`docs/opfs-session-persistence.md`.
+
 The presence of this directory means the port is managed independently of the
 native LinuxCNC tree even though LinuxCNC remains the semantic source of truth.

wasm-port/docs/opfs-session-persistence.md

@@ -0,0 +1,160 @@
+# OPFS/session persistence and release gate
+
+This document is the project-level handoff for OPFS/session persistence in the
+LinuxCNC WASM/browser port. It links the stable SDK entrypoint, browser smoke,
+session snapshot helpers, machine-file helpers, host gate commands, and blocked
+runtime family policy in one place.
+
+## Supported surface
+
+Stable external imports come from `runtime/sdk/src/index.js`.
+
+OPFS text/file helpers:
+
+- `getOpfsRoot()`
+- `saveTextFile()`
+- `loadTextFile()`
+- `machineIniPath()`
+- `toolTablePath()`
+- `parameterFilePath()`
+- `gcodeProgramPath()`
+- `sessionSnapshotPath()`
+- `defaultMachinePaths()`
+- `normalizeOpfsPath()`
+
+Session snapshot helpers:
+
+- `createMachineSessionSnapshotPayload()`
+- `createSessionSnapshot()`
+- `saveSessionSnapshot()`
+- `saveMachineSessionSnapshot()`
+- `loadSessionSnapshot()`
+- `loadMachineSessionSnapshot()`
+- `validateSessionSnapshot()`
+
+Machine file and program helpers:
+
+- `machineFilePaths()`
+- `saveMachineTextFiles()`
+- `loadMachineTextFiles()`
+- `saveGcodeProgram()`
+- `loadGcodeProgram()`
+- `gcodeFilenameFromProgramPath()`
+
+LinuxCNC-backed OPFS bridges:
+
+- `restoreMachineParametersFromOpfs()`
+- `saveMachineParametersToOpfs()`
+- `loadMachineToolTableFromOpfs()`
+- `saveMachineToolTableToOpfs()`
+- `loadMachineSessionFromOpfs()`
+
+Browser UI/session helpers are documented in:
+
+- `docs/ui-session-summary-helpers.md`
+- `docs/ui-machine-file-helpers.md`
+- `docs/ui-run-summary-helpers.md`
+- `docs/ui-panel-state-summary.md`
+- `docs/panel-entry.md`
+
+## Persistence workflow
+
+The browser/UI persistence workflow is host-side only:
+
+1. The UI saves machine INI, parameter, and tool-table text under
+   `linuxcnc/machines/<machine-id>/`.
+2. Optional G-code programs are saved under `linuxcnc/gcode/`.
+3. A session snapshot is saved under `linuxcnc/sessions/<session-id>/`.
+4. `loadMachineSessionFromOpfs()` loads the persisted INI text, copies it into
+   the interpreter WASM filesystem, and uses the LinuxCNC-backed INI SDK to read
+   `[RS274NGC]PARAMETER_FILE`, `[EMCIO]TOOL_TABLE`, and
+   `[EMCIO]RANDOM_TOOLCHANGER` when explicit host options do not override them.
+5. Parameter and tool-table bridge helpers copy OPFS text into the interpreter
+   WASM filesystem and then call LinuxCNC-backed interpreter SDK methods such as
+   `restoreParameters()`, `saveParameters()`, `loadToolTable()`, and
+   `saveToolTable()`.
+
+This workflow stores host files and stages them into Emscripten FS. It does not
+implement G-code, tool-table, parameter-file, planner, remap, or kinematics
+semantics in JavaScript.
+
+## Verified browser workflows
+
+The aggregate browser gate is:
+
+```bash
+SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
+```
+
+Required output:
+
+```text
+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_ini_opfs_smoke=ok` covers real browser OPFS/session persistence,
+including INI text persistence, session snapshots, machine-file helpers,
+G-code program helpers, and the INI panel frame workflow.
+
+## Release gate
+
+Run the project-level gate before claiming a release-ready OPFS/session or SDK
+surface:
+
+```bash
+git diff --check
+wasm-port/tools/verify_vendor_sync.sh
+wasm-port/tools/verify_no_standalone_cnc_semantics.sh
+wasm-port/tests/sdk/node/verify_sdk_surface.sh
+wasm-port/tests/opfs/node/verify_file_service.sh
+wasm-port/tests/ui/node/verify_ui_node_smokes.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
+SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
+wasm-port/tests/host/verify_host_smokes.sh
+```
+
+The host aggregate must include:
+
+```text
+opfs_file_service_node_smoke=ok
+sdk_surface_node_smoke=ok
+ui_node_smokes=ok
+browser_ini_opfs_smoke=ok
+browser_ini_shell_integration_workflow_smoke=ok
+host_wasm_opfs_browser_smokes=ok
+```
+
+## Blocked runtime families
+
+OPFS/session persistence does not unblock full LinuxCNC runtime families. These
+remain blocked until a LinuxCNC-owned runtime proof exists and native,
+Node/WASM, browser, and host gates all pass in that order:
+
+- `L4-USER-M-PROCESS`
+- `L4-TOOL-DB`
+- `L4-PYTHON-REMAP`
+
+Do not run the opt-in runtime probes on a host that lacks the required LinuxCNC
+runtime processes:
+
+```bash
+ENABLE_MILLTURN_USER_M_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_millturn_user_m_runtime.sh
+ENABLE_TOOL_DB_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_tool_db_runtime.sh
+ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_python_remap_runtime.sh
+```
+
+## Failure modes
+
+- Missing OPFS support returns an OPFS availability error from `getOpfsRoot()`.
+- Invalid OPFS paths are rejected before storage access.
+- Invalid snapshot format, version, session id, payload, or machine id is
+  rejected by snapshot validation helpers.
+- Missing INI, parameter, or tool-table OPFS files remain host persistence
+  errors. JavaScript does not synthesize LinuxCNC machine state.
+- Tool, parameter, remap, planner, and kinematics behavior remains owned by
+  vendored LinuxCNC source and the C/WASM ABI.

wasm-port/tests/docs/node/verify_opfs_session_docs.mjs

@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "../../..");
+
+const docText = readFileSync(resolve(root, "docs/opfs-session-persistence.md"), "utf8");
+const readmeText = readFileSync(resolve(root, "README.md"), "utf8");
+const sdkReadmeText = readFileSync(resolve(root, "runtime/sdk/README.md"), "utf8");
+const hostSmokeText = readFileSync(resolve(root, "tests/host/verify_host_smokes.sh"), "utf8");
+const browserSmokeText = readFileSync(resolve(root, "tests/browser/verify_ini_panel_browser.sh"), "utf8");
+const trackerText = readFileSync(resolve(root, "../PROJECT_COMPLETION_TRACKER.md"), "utf8");
+
+for (const phrase of [
+  "OPFS/session persistence and release gate",
+  "runtime/sdk/src/index.js",
+  "createMachineSessionSnapshotPayload",
+  "loadMachineSessionFromOpfs",
+  "restoreMachineParametersFromOpfs",
+  "loadMachineToolTableFromOpfs",
+  "browser_ini_opfs_smoke=ok",
+  "sdk_surface_node_smoke=ok",
+  "host_wasm_opfs_browser_smokes=ok",
+  "verify_no_standalone_cnc_semantics.sh",
+  "L4-USER-M-PROCESS",
+  "L4-TOOL-DB",
+  "L4-PYTHON-REMAP",
+]) {
+  assert.match(docText, new RegExp(phrase.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+}
+
+assert.match(readmeText, /docs\/opfs-session-persistence\.md/);
+assert.match(sdkReadmeText, /OPFS\/session persistence exports/);
+assert.match(hostSmokeText, /verify_sdk_surface\.sh/);
+assert.match(hostSmokeText, /verify_file_service\.sh/);
+assert.match(browserSmokeText, /browser_ini_opfs_smoke=ok/);
+assert.match(trackerText, /OPFS\/session persistence/);
+
+console.log("opfs_session_docs_node_smoke=ok");

wasm-port/tests/docs/node/verify_opfs_session_docs.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/../../.." && pwd)"
+
+node "$ROOT_DIR/tests/docs/node/verify_opfs_session_docs.mjs"

wasm-port/tests/host/verify_host_smokes.sh

@@ -14,6 +14,7 @@ SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/wasm/node/verify_nc_files_wasm.sh"
 SKIP_TP_BUILD=1 "$ROOT_DIR/tests/wasm/node/verify_tp_wasm.sh"
 "$ROOT_DIR/tests/opfs/node/verify_file_service.sh"
 "$ROOT_DIR/tests/sdk/node/verify_sdk_surface.sh"
+"$ROOT_DIR/tests/docs/node/verify_opfs_session_docs.sh"
 "$ROOT_DIR/tests/ui/node/verify_ui_node_smokes.sh"
 SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/browser/verify_ini_panel_browser.sh"
 SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/browser/verify_interp_browser.sh"