补充 OPFS session persistence release gate 文档
This commit is contained in:
160
wasm-port/docs/opfs-session-persistence.md
Normal file
160
wasm-port/docs/opfs-session-persistence.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user