181 lines
6.1 KiB
Markdown
181 lines
6.1 KiB
Markdown
# 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()`
|
|
- `readMachineSessionReadiness()`
|
|
|
|
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()`.
|
|
|
|
External callers can run `readMachineSessionReadiness()` before step 4 to get a
|
|
structured `ready`/`blocked` report for persisted INI, parameter, tool-table,
|
|
optional G-code, and optional session snapshot files. This helper only checks
|
|
host file availability and snapshot envelope validity.
|
|
|
|
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
|
|
```
|
|
|
|
The dedicated OPFS/session browser workflow gate is:
|
|
|
|
```bash
|
|
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_opfs_session_workflow_browser.sh
|
|
```
|
|
|
|
Required output:
|
|
|
|
```text
|
|
browser_ini_opfs_smoke=ok
|
|
browser_opfs_session_workflow_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.
|
|
`browser_opfs_session_workflow_smoke=ok` isolates the save machine files ->
|
|
save G-code -> save session snapshot -> readiness -> load session into WASM ->
|
|
persistence summary workflow in a standalone browser gate.
|
|
|
|
## 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
|
|
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_opfs_session_workflow_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_opfs_session_workflow_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.
|
|
- `readMachineSessionReadiness()` reports missing files or invalid snapshots as
|
|
structured blocked checks before callers load a session into WASM.
|
|
- 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.
|