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 validation command is:

wasm-port/tests/native/verify_native_probes.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/build_native_probes.sh Builds native source probes and standalone harnesses from vendored LinuxCNC source plus narrow runtime wrappers.
5. tests/native/verify_native_probes.sh Checks probe exit codes, source-probe coverage, harness stdout, canonical fixture events, and expected error behavior.

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_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 and captures canonical events.
linuxcnc_parameter_file_harness	Validates LinuxCNC parameter file restore/save behavior and required/read-only parameter handling.
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.

Fixture Coverage

Positive G-code fixtures currently cover:

• linear traverse/feed
• arc semantics
• modal absolute/incremental motion
• position parameters
• canned cycles
• coordinate offsets
• feed and motion control modes
• probing
• threading and rigid tap
• NURBS G5/G6
• spindle orient
• tool semantics
• tool table setup
• 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
• read-only named parameter writes
• read-only numbered parameter writes
• missing tool
• missing tool length offset

Validation Boundaries

Current validation is native-only. WASM, browser, SDK, OPFS, and full machine-session validation remain future work.

The current fixture expectations validate standalone behavior against the vendored LinuxCNC source path. They do not yet run a side-by-side native LinuxCNC executable comparison for each fixture.

The kinematics probe currently covers LinuxCNC identity/trivial kinematics only. Non-trivial and 5-axis kinematics still need dedicated machine baselines.