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:

The UI saves machine INI, parameter, and tool-table text under linuxcnc/machines/<machine-id>/.
Optional G-code programs are saved under linuxcnc/gcode/.
A session snapshot is saved under linuxcnc/sessions/<session-id>/.
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.
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:

SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh

Required output:

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:

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:

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:

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.

5.6 KiB Raw Blame History