linuxcncWebWASM/docs/linuxcnc-web-wasm-source-semantics.md

LinuxCNC Source Semantics Contract

This contract freezes source-derived configuration behavior for the future Web control panel. The machine-readable copy is coverage/linuxcnc-source-semantics-contract.json; the shared Worker/workspace implementation is web/workspace/linuxcnc-source-semantics.mjs.

Rules

• LinuxCNC AXIS reads [DISPLAY] OPEN_FILE as an initial UI hint. The source checks whether the selected file exists before opening it, so an empty or missing OPEN_FILE is optional_missing, not a startup resource failure.
• [DISPLAY] INTRO_GRAPHIC is also an optional display asset.
• Missing exact HAL/HALFILE paths are classified as BLOCKED_HAL; they must not be reported as generic resource failures.
• Other missing exact paths are BLOCKED_RESOURCE. The resolver never substitutes a same-basename file from another configuration directory.
• Parameter files and tool tables may use the existing explicit runtime-fixture policy. This is a deterministic simulation fixture, not a claim that a host file exists.
• linuxcnc/nc_files/lathe_pawn.ngc exists, while the path requested by lathe_multispindle.ini (.../nc_files/examples/lathe_pawn.ngc) does not. The mismatch remains an optional OPEN_FILE diagnostic rather than a fabricated alias.

Control Panel Boundary

The Web control panel is projection-only. It should consume Worker configuration/session snapshots and render state, status, diagnostics, resources, hal, optional_missing, runtime_fixtures, and state_hash. It must not infer readiness from file basenames, write task/motion authority, or turn BLOCKED_* into TASK_READY.

The startup states remain NEW -> MOUNTED -> PARSED -> RESOLVED -> CORE_CREATED -> HAL_READY -> TASK_READY, with BLOCKED as the fail-closed terminal state. The source semantics contract does not modify ABI, protocol, schema versions, context lock, or release blockers.

Source evidence: linuxcnc/src/emc/usr_intf/axis/scripts/axis.py around the OPEN_FILE startup path, linuxcnc/src/emc/rs274ngc/rs274ngc_pre.cc for parameter-file handling, and linuxcnc/src/emc/task/emctask.cc for program-prefix handling.