# LinuxCNC Simulation Case Parity Plan

This plan is the execution queue for making one exact source case behave like
LinuxCNC in the browser. It supplements the implementation roadmap with
case-level acceptance rules and keeps source resource blockers explicit.

The only active target is specified in
[`linuxcnc-web-wasm-3axis-tutorial-parity.md`](linuxcnc-web-wasm-3axis-tutorial-parity.md).
Its `TUTORIAL-00..10` tasks are the required functional, process, Vismach and AXIS UI
parity slice for `linuxcnc/configs/sim/axis/vismach/3axis-tutorial`.
No later task may switch to another case; a new case requires a separate approved
plan and must not change this continuation scope.

## Baseline

- Locked source: LinuxCNC `2.10.0~pre0`, commit `239dcf4284762ad7e9c65d390bc5524d855c2f8e`.
- Case catalog: 235 INI entrypoints and 2,080 exact files under `configs/sim` plus LinuxCNC HAL support files.
- Existing matrix: 264 registered configuration entries, 233 entrypoints, 56 static-ready and 208 blocked.
- Browser entrypoint: exact-path case loader, Worker startup diagnostics, G-code/MDI/manual controls and machine view are implemented by S8-01.
- Real LinuxCNC condition evidence: `coverage/native-linuxcnc-case-conditions.report.json`.
- Current hard blocker: source-owned `sim.var`, `linuxcnc.var` and `tool.tbl` contents are absent for the selected minimal/CoreXY cases; S8-02 remains blocked.

## Parity Contract

An individual case is `verified` only when all of these records exist for the same locked source and case hash:

1. Exact INI/include/resource graph with no basename substitution.
2. Native LinuxCNC run using the same case files and an explicit runtime directory policy.
3. WASM core and Worker startup state, diagnostic code, source line and state hash.
4. Fixed-tick golden covering load, home, jog, MDI, run, pause/resume, abort, estop, IO and recovery as applicable.
5. HAL graph/component status and all unsupported host operations classified.
6. Frontend control mapping from the case's `DISPLAY`, VCP/PyVCP/GladeVCP/QtVCP/Gscreen/Touchy/VisMach declarations to authoritative Worker state.
7. Checkpoint/replay endpoint equality and a self-hashed case report.

`STATIC READY` is only an index classification. It never promotes a case to
runtime `TASK_READY` without the native and Worker startup records above.

## Queue

### S8-02: Close One Real Case

Status: `verified`.

The user-authorized runtime fixture contract is complete. Real LinuxCNC
execution supplied `sim.var`, generated `minimal_xyz_cmds.hal`,
`linuxcnc.var`, and the selected sim tool table. Their target paths and SHA-256
values are recorded in `coverage/sim-case-startup-s8-02.report.json`.
Minimal XYZ and CoreXY both reach Worker `TASK_READY`; same-basename files from
unrelated cases remain forbidden.

### S8-03: Lock Runtime Resource Inputs

Status: `verified`, depends on S8-02.

- Pin the native LinuxCNC package/source version used as oracle.
- Decide and record whether parameter files and tool tables are source-owned,
  generated-at-startup, or approved deterministic fixtures.
- Store every accepted fixture with source path, generator/command, bytes,
  SHA-256 and mutation policy.
- Extend the browser workspace transaction to model LinuxCNC parameter-file
  creation/update without host filesystem access.
- Re-run minimal and CoreXY native cases in isolated writable directories.

Exit: no unresolved resource input for the selected XZ batch; report
`coverage/sim-case-batch-s8-03.report.json` records all three TASK_READY states.

### S8-04: Minimal XYZ Vertical Slice

Status: `verified`, depends on S8-03.

- Native/WASM/Worker startup reaches `TASK_READY` for `minimal_xyz.ini`.
- Compare a fixed G-code program, MDI, home, XYZ jog, feed override, pause,
  abort, estop/recover and checkpoint restore.
- Drive the frontend case panel and machine view from Worker snapshots only.
- Preserve LinuxCNC's generated `sim.var` semantics as a workspace transaction.

Evidence: `coverage/minimal-xyz-vertical-s8-04.report.json`.

### S8-05: CoreXY Dual Path

Status: `verified`, depends on S8-03 and S8-04.

- Verify both `corexy_by_kins.ini` and `corexy_by_hal.ini`.
- Compare CoreXY kinematics joints, HAL signal graph, home behavior and
  following-error/limit boundaries.
- Keep the HAL implementation path distinct from the kinematics path in the
  case report and UI diagnostics.

Evidence: `coverage/corexy-dual-path-s8-05.report.json`.

### S8-06: Resource and Startup Matrix

Status: `verified`, depends on S8-04 and S8-05.

- Execute all 235 browser case bundles with exact resource closure.
- Re-run native LinuxCNC for every case whose resources are complete.
- Classify each case as `TASK_READY`, `BLOCKED_RESOURCE`,
  `BLOCKED_HOST_CAPABILITY`, `BLOCKED_SOURCE_ORACLE` or `ERROR`.
- Record the first divergent startup phase, source line and missing capability;
  never collapse failures into a single count.

Evidence: `coverage/sim-case-matrix-s8-06.report.json`.

### S8-07: Display and Control Families

Status: `queued`, depends on S8-06.

Implement and verify case-declared frontend behavior in separate families:

- Axis: DRO, mode, jog, homing, overrides, program/run controls and plot.
- QtVCP/Gscreen: VCP pins, dialogs, tool/probe/spindle panels and custom tabs.
- GladeVCP/PyVCP: declared pins/widgets and explicit host-loader boundaries.
- Touchy/halui: touchscreen jog/MDI and mode controls.
- VisMach: kinematics-specific machine geometry, joints, toolpath and stock.

Each family must consume Worker authoritative state and retain unsupported
GUI/plugin actions as diagnostics rather than silently dropping them.

### S8-08: Machine Families

Status: `verified`, depends on S8-06.

Close representative cases for Cartesian, lathe, gantry, CoreXY, Delta,
Tripod, Pentapod, Hexapod, 5-axis/TRT, SCARA/PUMA/GenSer and wrapped rotary.
Use the existing native/WASM kinematics tests as golden inputs, then add the
case-specific INI/HAL/resource/startup and frontend evidence.

Current evidence: `coverage/machine-families-s8-08.report.json` covers the
real lineardelta/rdelta cases; remaining listed families continue in later
slices.

### S8-09: Program and Runtime Extensions

Status: `verified`, depends on S8-06.

Cover real cases using remap/Python, O-word/subroutines, filters, ClassicLadder,
tool changers, spindle orient, external offsets, probing and IO acknowledgements.
Every host-only operation must have an explicit capability result and a
browser-equivalent path where one is supported.

Evidence: `coverage/runtime-extensions-s8-09.report.json`.

### S8-10: Full Case Acceptance

Status: `queued`, depends on S8-07, S8-08 and S8-09.

- Run the 235-case matrix in deterministic batches.
- Compare native and Worker endpoint/checkpoint/event hashes.
- Run the browser control matrix at the supported browser versions.
- Publish accepted/blocked/error rows with input and report hashes.
- Keep official oracle, license, browser and owner/release blockers separate
  from implementation coverage.

## Resume Gate

The next executable action is S8-03 only after the missing parameter/tool
inputs are supplied or explicitly approved as deterministic fixtures. Until
then, the project remains implementation-capable but not a complete
LinuxCNC-parity release candidate.