cnc_wams/wasm-port/docs/drift-report.md

Drift Report

Current Status

As of the current upstream baseline, no byte-level drift is allowed between files listed in tools/source-manifest.txt and the matching files under ../linuxcnc/.

The enforced upstream baseline is:

60597ee0718873d2449058c824262a275e5e4bad

tools/verify_vendor_sync.sh enforces this by comparing every manifest file against upstream during native validation.

Allowed Standalone Boundaries

The following differences are intentional runtime boundaries, not LinuxCNC semantic rewrites:

Boundary	Standalone treatment
RTAPI	Minimal compatibility shim in runtime/core/shims/rtapi.h.
HAL lookup	Standalone HAL adapter for _hal[...] named parameter reads.
INI lookup	Standalone INI adapter around vendored LinuxCNC INI parser behavior, including boolean conversion through LinuxCNC iniFindBool() and string lookup for INI-declared machine file names.
Canonical output	Canonical calls are captured as test events instead of driving hardware.
Feed-rate state	SET_FEED_RATE updates standalone canonical runtime state so vendored convert_length_units() can read it back through GET_EXTERNAL_FEED_RATE() during G20/G21 changes.
Tool-data reload	LinuxCNC RELOAD_TOOLDATA is captured as a canonical test event; browser/native tool-table reload plumbing remains a future host/runtime adapter.
Tool table storage	Vendored LinuxCNC tooldata_common.cc owns tool-table parsing and formatting; the standalone boundary only supplies the in-memory tooldata_get()/tooldata_put() callbacks, exposes load/save through the WASM C ABI, and forwards the host random-toolchanger flag to LinuxCNC tooldata_init().
Tool slot status	Standalone tool adapter state supplies GET_EXTERNAL_TOOL_SLOT() and GET_EXTERNAL_SELECTED_TOOL_SLOT() for vendored Interp::synch(); linuxcnc_interp_init_harness guards current/selected slot synchronization.
Interpreter state tags	LinuxCNC UPDATE_TAG callbacks are captured from the state tags packed by vendored interpreter code; standalone code does not derive modal state.
Rotary indexer lock state	LinuxCNC UNLOCK_ROTARY and LOCK_ROTARY callbacks are captured from the vendored single-axis indexer path; standalone code does not implement rotary-indexing semantics.
File flush	LinuxCNC FINISH is captured as a canonical test event on the vendored %-delimited file-reading path.
WASM parameter-file backup	LinuxCNC save_parameters() calls link() to create the .bak parameter-file backup; runtime/core/linuxcnc_wrap/linuxcnc_wasm_posix_stubs.cpp maps that WASM/MEMFS edge to a file copy so the vendored save path can run unchanged.
Interpreter reset	LinuxCNC ON_RESET is captured as a canonical test event on the vendored interpreter reset/file-open path.
Interpreter init	LinuxCNC INIT_CANON and the canonical initialization sequence from vendored Interp::init() are captured as test events.
Comment logging	LinuxCNC LOGOPEN, LOG, LOGAPPEND, and LOGCLOSE callbacks are captured as canonical test events instead of writing host log files.
EMC status machine units	A narrow standalone emcStatus shim exposes the machine-units field used by vendored interpreter conversion and initialization code; linuxcnc_emc_status_probe and linuxcnc_interp_init_harness guard the inch/mm boundary.
Python/remap	Python/remap hooks are stubbed at the runtime edge.
Dynamic interpreter path	interp_base.cc probe uses standalone EMC2_HOME compile-time path boundary.
Realtime scheduler	TP probes seed deterministic status/config data instead of running LinuxCNC realtime process topology.
Kinematics component lifecycle	Kinematics modules are initialized through LinuxCNC module entry points where native runtime probes exist, while HAL component init/ready/exit, HAL pin allocation, and RTAPI module metadata are handled by standalone shims.
Go math C/C++ linkage	genserkins runtime probing compiles vendored gomath.c through a narrow C++ wrapper so LinuxCNC genserfuncs.c can link to the upstream Go math symbols without editing vendored source.
Switchkins iterative forward	genhexkins runtime probing follows LinuxCNC switchkins iterative-forward behavior, including the first-call warmup path before asserting roundtrip convergence.
Browser storage	OPFS remains outside the native core; runtime/opfs/file-service.js owns browser text-file persistence, runtime/opfs/path-model.js owns host-side storage paths for INI, tool table, parameter, G-code, preview-cache, and session-snapshot content, runtime/opfs/snapshot-store.js owns generic JSON session snapshot persistence, runtime/opfs/machine-file-store.js owns pure-text machine-file and G-code persistence, runtime/opfs/linuxcnc-parameter-bridge.js only copies parameter files between OPFS text storage and the LinuxCNC-backed WASM parameter-file ABI, runtime/opfs/linuxcnc-tool-table-bridge.js only copies tool tables between OPFS text storage and the LinuxCNC-backed WASM tool-table ABI, and runtime/opfs/linuxcnc-machine-session-bridge.js groups INI, parameter, and tool-table loading while using the LinuxCNC-backed INI SDK for [EMCIO]RANDOM_TOOLCHANGER, [RS274NGC]PARAMETER_FILE, and [EMCIO]TOOL_TABLE when available; explicit host session file-name options take precedence over INI-derived file names, and path validation remains owned by the OPFS path model, including rejection of traversal or nested path segments from INI-derived file names.

Enforced Non-Drift Rules

• Do not edit ../linuxcnc/.
• Do not patch vendored files without adding a patch under patches/ and documenting the reason.
• Do not add standalone Interp::... member definitions outside the documented Python/remap runtime-edge stubs.
• Do not add .c or .cc manifest files without a source compile probe.
• Do not sync from a different upstream commit without updating tools/upstream-baseline.txt and docs/scope-and-baseline.md.

Known Gaps

• No browser/full-core WASM parity tests yet. The INI parser now has Node and Chromium smoke harnesses against vendored LinuxCNC inifile.cc.
• JS SDK validation now covers the INI WASM wrapper around vendored LinuxCNC inifile.cc and the interpreter-core SDK wrapper around the existing exported C ABI. The interpreter SDK only manages strings, Emscripten file writes, and calls into vendored LinuxCNC execution paths, including parameter-file restore/save and tool-table load/save.
• OPFS validation covers a Node mock of the file-service adapter, the host-side path model, generic session snapshot storage, pure-text machine file and G-code storage, parameter/tool-table bridge copying into the interpreter SDK filesystem, grouped machine-session loading, explicit session file-name overrides, invalid INI-derived machine file names, generic session snapshot custom filenames plus envelope/path rejection paths, and a Chromium localhost round trip for those persistence paths.
• Host-side smoke validation is aggregated by tests/host/verify_host_smokes.sh so Node, WASM, OPFS, and browser checks run from one command.
• Identity/trivial, 5axiskins, TRT xyzac/xyzbc, delta, SCARA, PUMA, serial, hexapod, pentapod, and related kinematics sources now have native source-probe coverage.
• Full machine baselines beyond the current identity/trivial, 5axiskins, TRT, delta, SCARA, PUMA, serial genserkins, hexapod genhexkins, pentapod pentakins, and other existing runtime probes are not established.
• Positive cutter-compensated motion and cutter compensation rejection paths now have standalone interpreter fixture coverage through vendored LinuxCNC source.
• Fixture expectations are checked against the standalone vendored source path. The upstream rs274 side-by-side baseline now covers simple motion, arc geometry, offsets, feed-control, comment/logging, numbered-parameter, probing, spindle-orient, file-open reset, file-finish, tool-reload, and tool select/change/length-offset, canned-cycle, state-tag motion, tool-table setup, and O-word subroutine fixtures; it also covers threading/rigid tap, NURBS dispatch boundaries, and comparable canonical runtime edge and program-end cleanup calls. Adapter-heavy fixtures, standalone modal-state assertions, and upstream rs274 output gaps such as WAIT or hidden NURBS control-point detail still need dedicated native LinuxCNC baselines.
• canned_cycles is now in the upstream rs274 side-by-side baseline after the minimal interpreter harness was aligned with LinuxCNC Interp::init() default G73/G83 peck-clearance values for millimeter units.
• tool_table_setup is now in the upstream rs274 side-by-side baseline using a dedicated rs274 -t tool table and -i millimeter-unit INI boundary.
• tool_semantics now compares its T/M6/G43/G49 canonical subset with upstream rs274 -t -i; M61 current-pocket host-state behavior remains a standalone fixture expectation.

Current Drift Conclusion

Within the native extracted-core scope, the port currently has no permitted byte-level drift from vendored LinuxCNC source files. All current behavior coverage is guarded by upstream baseline validation, vendor sync validation, source compile probes, native harnesses, and fixture checks.