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:

```bash
wasm-port/tests/native/verify_native_probes.sh
```

The current WASM smoke validation command is:

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

The current WASM interpreter-core smoke validation command is:

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

The current OPFS host-boundary validation command is:

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

The current browser smoke validation command is:

```bash
wasm-port/tests/browser/verify_ini_panel_browser.sh
```

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

```bash
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`, and `namedparam_semantics`, plus the
`g1_zero_feed`, `arc_radius_mismatch`, `arc_zero_radius`, and
`g53_incremental` 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.