# 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 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 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 WASM artifact once, then runs
the Node WASM smoke, 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/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, OPFS, and browser smoke validation with a single INI WASM build. |

## 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 is limited to
the INI parser smoke harness. 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.