按推荐建议,继续执行

结论:新增 compatibility-validation 与 drift-report,记录当前 native 验证链路、fixture 覆盖、无漂移规则和已知缺口,继续约束移植行为跟随 LinuxCNC 源程序。
This commit is contained in:
2026-06-07 18:41:25 +08:00
parent 8713bf523e
commit d5c5b0852f
3 changed files with 160 additions and 0 deletions

View File

@@ -0,0 +1,95 @@
# 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:
```bash
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. |
## 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.

View File

@@ -0,0 +1,60 @@
# 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:
```text
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. |
| Canonical output | Canonical calls are captured as test events instead of driving hardware. |
| 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. |
| Browser storage | OPFS remains outside the native core and is not yet connected. |
## 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::convert_g()`.
- 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/WASM parity tests yet.
- No JS SDK validation yet.
- No OPFS persistence validation yet.
- Full kinematics implementation files are not yet extracted.
- Full 3-axis, non-trivial kinematics, and 5-axis machine baselines are not
established.
- Fixture expectations are currently checked against the standalone vendored
source path, not by running a native LinuxCNC binary for every fixture.
## 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.

View File

@@ -500,6 +500,11 @@ Current verified progress:
- `docs/source-reuse-map.md` records the current vendored LinuxCNC source - `docs/source-reuse-map.md` records the current vendored LinuxCNC source
reuse matrix and dependency matrix, tying each extracted group to its reuse matrix and dependency matrix, tying each extracted group to its
standalone runtime boundary and validation path. standalone runtime boundary and validation path.
- `docs/compatibility-validation.md` records the current validation chain,
source coverage requirements, native harnesses, fixture coverage, and
validation boundaries.
- `docs/drift-report.md` records current no-drift enforcement, allowed
standalone runtime boundaries, known gaps, and the current drift conclusion.
## Phase 4: Port INI Parsing Without Editing Upstream ## Phase 4: Port INI Parsing Without Editing Upstream