cnc_wams/wasm-port/docs/compatibility-validation.md

Compatibility Validation

Purpose

This document records how the standalone LinuxCNC WASM port currently proves that migrated behavior remains tied to LinuxCNC source code and fixture semantics.

The primary native validation command is:

wasm-port/tests/native/verify_native_probes.sh

The current WASM smoke validation command is:

wasm-port/tests/wasm/node/verify_ini_wasm.sh

The current WASM interpreter-core smoke validation command is:

wasm-port/tests/wasm/node/verify_interp_wasm.sh

The current OPFS host-boundary validation command is:

wasm-port/tests/opfs/node/verify_file_service.sh

The current browser smoke validation command is:

wasm-port/tests/browser/verify_ini_panel_browser.sh

The current aggregate host/WASM/browser smoke command is:

wasm-port/tests/host/verify_host_smokes.sh

Validation Chain

The native validation script runs these checks in order:

1. tools/verify_upstream_baseline.sh Confirms ../linuxcnc is at the recorded upstream commit in tools/upstream-baseline.txt.
2. tools/verify_vendor_sync.sh Confirms every manifest file is present in vendor/linuxcnc/, no extra vendored file exists, and every vendored file is byte-identical to upstream.
3. tools/verify_no_standalone_cnc_semantics.sh Confirms standalone code has not reintroduced Interp::convert_g().
4. tools/verify_native_linuxcnc_fixture_baseline.sh Runs a side-by-side fixture baseline through upstream ../linuxcnc/bin/rs274 and compares normalized canonical events for fixtures that do not require standalone-only runtime adapters.
5. tools/build_native_probes.sh Builds native source probes and standalone harnesses from vendored LinuxCNC source plus narrow runtime wrappers.
6. tests/native/verify_native_probes.sh Checks probe exit codes, source-probe coverage, harness stdout, canonical fixture events, and expected error behavior.

The WASM INI smoke script builds runtime/ui/ini-panel/linuxcnc_ini.js and linuxcnc_ini.wasm from vendored LinuxCNC inifile.cc, then loads that module through runtime/sdk/src/linuxcnc-ini.js in Node and verifies INI queries against a file written to the Emscripten filesystem.

The WASM interpreter-core smoke script builds build/wasm/core/linuxcnc_interp.js and linuxcnc_interp.wasm from the same vendored LinuxCNC interpreter source set used by the native minimal interpreter harness. It loads the module in Node, runs the first WASM interpreter fixture group through Interp::execute(), and compares emitted canonical events plus required LinuxCNC _setup state readback with the matching files in tests/fixtures/canon/. It also writes selected G-code fixtures into the Emscripten filesystem and runs them through LinuxCNC Interp::open(), Interp::read(), and Interp::execute() to validate the file execution path.

The OPFS host-boundary script validates the JavaScript file-service adapter with a Node mock of the browser File System Access handles. It covers nested directory creation, text save/load, missing file behavior, invalid relative paths, unavailable OPFS storage, and the host-side OPFS path model for INI, tool table, parameter, G-code, preview-cache, and session-snapshot storage targets. It also validates the host-side session snapshot JSON envelope and round-trip store plus pure-text machine file and G-code stores without defining CNC machine-state or file-format semantics.

The browser smoke script serves wasm-port/ over localhost and runs Chromium headless against a test page that imports the JS SDK, loads the INI WASM module, queries vendored LinuxCNC INI parsing through the SDK, and performs an OPFS text-file, generic session snapshot, machine file, and G-code text round trip.

The aggregate host smoke script builds the INI and interpreter-core WASM artifacts once, then runs the Node WASM smokes, the Node OPFS mock smoke, and the Chromium browser smoke.

Source Coverage

Every .c and .cc entry in tools/source-manifest.txt must have a corresponding *_source_probe entry in build/native/source-probes.tsv. The validation fails if:

• a manifest source file lacks a source probe;
• a source probe references a file not listed in the manifest;
• a manifest file is duplicated;
• vendored files drift byte-for-byte from upstream LinuxCNC.

Current Native Harnesses

Harness	Purpose
linuxcnc_ini_probe	Validates vendored LinuxCNC INI parsing can be used standalone.
linuxcnc_interp_state_probe	Validates interpreter state constants and structs compile under the standalone boundary.
linuxcnc_emc_status_probe	Validates the standalone emcStatus machine-units status boundary used by vendored interpreter conversion and initialization code.
linuxcnc_namedparam_harness	Validates LinuxCNC named parameter behavior, _ini[...], and _hal[...] adapter resolution.
linuxcnc_interp_minimal_harness	Runs G-code fixtures through vendored LinuxCNC parser/execution/conversion code, captures canonical events, and validates feed-rate state readback across length-unit changes.
linuxcnc_parameter_file_harness	Validates LinuxCNC parameter file restore/save behavior and required/read-only parameter handling.
linuxcnc_interp_init_harness	Validates vendored LinuxCNC Interp::init() emits canonical initialization boundaries, reads metric/inch machine units, and synchronizes current/selected tool slots through standalone status adapters.
linuxcnc_indexer_harness	Validates vendored LinuxCNC single-axis rotary indexer dispatch emits lock/unlock and motion boundaries through the standalone event sink.
linuxcnc_tp_api_probe	Validates vendored LinuxCNC trajectory planner calls for linear, arc, and queued motion paths.
linuxcnc_kinematics_probe	Validates vendored LinuxCNC trivkins.c plus kins_util.c initialize and perform identity forward/inverse mapping through the standalone HAL/RTAPI boundary.
linuxcnc_5axis_kinematics_probe	Validates vendored LinuxCNC 5axiskins.c through switchkins.c, including 5-axis forward/inverse round-trip behavior and switching to identity kinematics.
linuxcnc_xyzac_trt_kinematics_probe	Validates vendored LinuxCNC XYZAC TRT kinematics through switchkins.c, including forward/inverse round-trip behavior and switching to identity kinematics.
linuxcnc_xyzbc_trt_kinematics_probe	Validates vendored LinuxCNC XYZBC TRT kinematics through switchkins.c, including forward/inverse round-trip behavior and switching to identity kinematics.
linuxcnc_corexy_kinematics_probe	Validates vendored LinuxCNC CoreXY forward/inverse behavior through the standalone HAL/RTAPI boundary.
linuxcnc_rotate_kinematics_probe	Validates vendored LinuxCNC rotated-axis forward/inverse behavior.
linuxcnc_rose_kinematics_probe	Validates vendored LinuxCNC rose kinematics forward/inverse behavior.
linuxcnc_max_kinematics_probe	Validates vendored LinuxCNC max kinematics forward/inverse behavior.
linuxcnc_lineardelta_kinematics_probe	Validates vendored LinuxCNC linear-delta inverse/forward pose round-trip behavior.
linuxcnc_rotarydelta_kinematics_probe	Validates vendored LinuxCNC rotary-delta inverse/forward pose round-trip behavior.
linuxcnc_scorbot_kinematics_probe	Validates vendored LinuxCNC Scorbot forward/inverse behavior and pose round-trip behavior.
linuxcnc_tripod_kinematics_probe	Validates vendored LinuxCNC tripod inverse/forward behavior, including below-platform flag behavior.
linuxcnc_scara_kinematics_probe	Validates vendored LinuxCNC SCARA forward/inverse behavior and switching to identity kinematics.
linuxcnc_puma_kinematics_probe	Validates vendored LinuxCNC PUMA forward/inverse behavior, pose round-trip behavior, and switching to identity kinematics.
linuxcnc_genser_kinematics_probe	Validates vendored LinuxCNC generic serial kinematics forward/inverse behavior and switching to identity kinematics.
linuxcnc_genhex_kinematics_probe	Validates vendored LinuxCNC generic hexapod inverse/forward behavior, including the switchkins iterative-forward warmup path.
linuxcnc_pentakins_kinematics_probe	Validates vendored LinuxCNC pentapod inverse/forward pose round-trip behavior.

Current WASM Harnesses

Harness	Purpose
tests/wasm/node/verify_ini_wasm.sh	Validates the browser-facing INI WASM module can be built from vendored LinuxCNC inifile.cc, loaded through the JS SDK in Node, and queried through the exported C ABI.
tests/wasm/node/verify_interp_wasm.sh	Validates the initial interpreter-core WASM module can be built from vendored LinuxCNC interpreter source, run the first fixture group through Interp::execute() and selected file fixtures through Interp::open()/read()/execute(), and match the native canonical event plus required state readback fixtures.
tests/opfs/node/verify_file_service.sh	Validates the host-owned OPFS text-file adapter, path model, session snapshot store, machine file store, and G-code text store used by the browser INI panel without moving file persistence into the WASM core.
tests/browser/verify_ini_panel_browser.sh	Validates the INI SDK, WASM module loading, OPFS text-file round trip, generic session snapshot round trip, machine file text round trip, and G-code text round trip in a real browser runtime.
tests/host/verify_host_smokes.sh	Runs the current host-side Node, WASM interpreter-core, OPFS, and browser smoke validation with shared WASM builds.

Fixture Coverage

Positive G-code fixtures currently cover:

• linear traverse/feed
• arc semantics
• modal absolute/incremental motion
• position parameters
• canned cycles
• coordinate offsets
• G53 machine-coordinate motion
• feed and motion control modes
• probing
• threading and rigid tap
• NURBS G5/G6
• spindle orient
• tool semantics
• tool table setup
• tool-data reload boundary
• interpreter state-tag boundary
• percent-delimited file FINISH boundary
• file-open ON_RESET boundary
• comment logging canonical calls
• named and numbered parameters
• O-word subroutines
• program-end modal reset
• canonical runtime edge calls

Negative fixtures currently cover:

• zero-feed G1
• arc radius mismatch
• zero-radius arc
• G53 incremental-mode rejection
• read-only named parameter writes
• read-only numbered parameter writes
• missing tool
• missing tool length offset

Validation Boundaries

Current full-core validation is native-only. WASM/SDK validation covers the INI parser smoke harness and an initial interpreter-core canonical event smoke for minimal_linear, arc_semantics, length_units, modal_incremental, plane_selection, coordinate_offsets, g53_machine_coordinates, feed_control_modes, position_params, probe_semantics, spindle_orient, comment_logging, numbered_params, tool_semantics, tool_table_setup, tool_reload, and namedparam_semantics, plus the g1_zero_feed, arc_radius_mismatch, arc_zero_radius, g53_incremental, tool_not_found, and tool_length_offset_not_found negative fixtures. The WASM interpreter file path additionally covers file_open_reset, percent_file_finish, and oword_subroutine. OPFS validation is limited to the JavaScript host-boundary adapter plus the INI browser smoke harness. Full browser coverage, full SDK coverage, and full machine-session validation remain future work.

The current fixture expectations validate standalone behavior against both the vendored LinuxCNC source path and an upstream rs274 side-by-side baseline for parser/conversion, arc geometry, offsets, feed-control and feed-state readback, comment/logging, numbered-parameter, probing, spindle-orient, file-open reset, file-finish, tool-reload, tool select/change/length-offset, canned-cycle, state-tag motion, tool-table setup, and O-word subroutine fixtures, plus threading/rigid tap, NURBS dispatch boundaries, and the comparable canonical runtime edge and program-end cleanup calls. Fixtures that depend on standalone-only runtime adapters, HAL/INI/tool-change state, upstream rs274 output gaps such as WAIT or hidden NURBS control-point detail, or richer machine session state still need dedicated native LinuxCNC baselines.

Remaining positive fixtures that are not in the upstream rs274 side-by-side baseline are intentionally held out until they get a dedicated native LinuxCNC baseline: namedparam_semantics depends on standalone INI/HAL adapter resolution. state_tag_motion now compares its motion events with upstream rs274, while UPDATE_TAG events remain a standalone state-tag capture boundary. tool_semantics now compares T/M6/G43/G49 canonical events with upstream rs274; M61 current-pocket host-state behavior remains covered by the standalone fixture expectation, and Interp::synch() current/selected tool slot reads are covered by the native init harness.

The kinematics probes currently cover LinuxCNC identity/trivial kinematics, the switchable 5axiskins XYZBCW bridge-mill model, TRT xyzac/xyzbc table-rotary models, CoreXY, rotated-axis, rose, max, linear-delta, rotary-delta, Scorbot, tripod, SCARA, PUMA, generic serial, generic hexapod, and pentapod models.