# Sim Config Coverage Promotion Analysis

This analysis records how the completed virtual HAL changes the next
`linuxcnc/configs/sim` coverage-promotion work. It is intentionally an analysis
document only: it does not promote rows, change inventory counts, or relax any
blocked runtime family.

## Current Baseline

Current machine-readable inventory remains:

```text
sim_configs_wasm_node_inventory_executed=28
sim_configs_wasm_node_inventory_passed=28
sim_configs_wasm_node_inventory_skipped=131
sim_configs_wasm_node_inventory_unexpected_fail=0
sim_configs_wasm_node_inventory_skip_ASSET_ONLY=65
sim_configs_wasm_node_inventory_skip_L4_PYTHON_REMAP=53
sim_configs_wasm_node_inventory_skip_L4_TOOL_DB=1
sim_configs_wasm_node_inventory_skip_L4_USER_M_PROCESS=1
sim_configs_wasm_node_inventory_skip_NON_MAIN_CLASS=10
sim_configs_wasm_node_inventory_skip_UPSTREAM_DEMO=1
```

The current generated inventory has no skipped main-program row whose hard
block is already empty. That matters: virtual HAL maturity should not be used
as a blanket reason to reduce `skipped=131`. The next useful promotions are
case promotions from Node inventory or representative coverage into browser,
diagnostics, and release evidence.

## What Virtual HAL Unlocks

The virtual HAL is now a source-derived Web simulation replacement for these
runtime surfaces:

- LinuxCNC realtime HAL simulation replacement;
- `halcmd` simulation replacement;
- motion controller simulation replacement;
- HAL pin/signal/param store;
- `setp`, `sets`, `net`, `show`, `getp`, `gets`, `loadrt`, `loadusr`, `addf`,
  `start`, and `stop` command workflow;
- servo-period motion stepping;
- axis/joint position feedback;
- source-compliance, sim-config source coverage, command fixture, and motion
  matrix reports;
- OPFS/session persistence and release diagnostics evidence.

That means Web coverage can now promote additional cases when their remaining
dependency is HAL, HALUI, deterministic virtual `halcmd`, machine state, or
motion feedback. It does not unlock rows whose defining behavior is Python
remap runtime, tool database process protocol, external user-M process state,
or upstream-invalid demo code.

## Promotion Rules After Virtual HAL

A sim-config case can move forward only when all of these are true:

1. LinuxCNC source/config evidence owns the behavior.
2. Native or current Node inventory evidence already passes, or the row is a
   macro/load or subroutine class with an explicit non-main validation plan.
3. Dependencies are limited to virtual HAL, HALUI, deterministic UI process
   declarations, machine files, tool tables, remap subroutine assets, or
   motion/kinematics evidence already covered by LinuxCNC-backed runtime.
4. Browser evidence can export virtual HAL source compliance, sim-config
   source coverage, command fixtures, and manifest-backed motion matrix.
5. The row is not `L4-PYTHON-REMAP`, `L4-TOOL-DB`, `L4-USER-M-PROCESS`, or
   `UPSTREAM-DEMO`.
6. `verify_no_standalone_cnc_semantics.sh` remains green.

Promotion should mean a stronger evidence tier, not necessarily a lower skip
count. For example, a row may move from Node `INV` to browser diagnostics
evidence while the inventory baseline remains `executed=28`.

## Recommended Promotion Candidates

### Tier 1: Browser Evidence For Existing Node INV Rows

These rows already pass Node inventory and have no hard runtime block. Virtual
HAL makes them good candidates for browser diagnostics/release evidence rather
than only shared representative coverage.

| Candidate | Current coverage | Why it is now promotable |
| --- | --- | --- |
| `qtdragon/qtdragon_multi_joint/on_abort.ngc` | Node `INV`, browser delegated to `woodpecker` | Requires HAL/UI declarations and multi-joint machine context; virtual HAL motion matrix already maps `qtdragon-on-abort` and `qtdragon_xyyz.ini`. |
| `qtdragon/qtdragon_xyz/on_abort.ngc` | Node `INV`, browser delegated to `woodpecker` | Same on-abort family, already part of virtual HAL sim-config source coverage evidence. |
| `qtdragon/qtdragon_xyz45/on_abort.ngc` | Node `INV`, browser delegated to `woodpecker` | Adds rotary-axis machine context without requiring Python remap or external process runtime. |
| `qtdragon_hd/qtdragon_hd_xyz/on_abort.ngc` | Node `INV`, browser delegated to `woodpecker` | Deterministic UI/HAL family, suitable for browser diagnostics artifact evidence. |
| `qtdragon_hd/qtdragon_hd_z_compensation/on_abort.ngc` | Node `INV`, browser delegated to `woodpecker` | HAL/UI machine state case; should be promoted only with explicit source evidence for the z-compensation INI. |
| `qtvcp_screens/qtdragon/on_abort.ngc` | Node `INV`, browser delegated to `woodpecker` | QTVCP on-abort surface, no Python-remap hard block in inventory. |
| `axis/vismach/puma/puma_seam_weld.ngc` | Node `INV`, browser represented by `puma_cube.ngc` | Same vendored PUMA machine context; virtual HAL motion matrix already includes `vismach-remap-sims` and `puma.ini`. |
| `axis/rose_engine/rcone_demo.ngc` | Node `INV` | HAL process only, no hard block; useful as a non-Qt/non-vismach browser diagnostics candidate. |

Expected next artifact shape:

- extend a source-derived candidate list in SDK or docs;
- add browser diagnostics fixture rows, not a JS CNC interpretation path;
- assert virtual HAL source compliance, sim-config source coverage, command
  fixtures, and motion matrix remain complete;
- update matrix notes from delegated browser representative to explicit browser
  evidence only after the browser gate exists.

### Tier 2: Existing REP Rows Worth Splitting Into More Cases

These are already promoted as representative coverage. The next work is not to
prove the class exists; it is to split representative buckets into more
specific cases now that virtual HAL can carry machine state evidence.

| Candidate | Current coverage | Promotion goal |
| --- | --- | --- |
| `axis/vismach/5axis/bridgemill/5axisgui.ngc` | Node/browser `REP` | Add explicit HALUI MDI and W-axis diagnostics evidence. |
| `axis/vismach/5axis/table-dual-rotary/demos/xyzab-tdr-demo.ngc` | Node/browser `REP` | Add dual-rotary ABC/AB feedback evidence in motion matrix rows. |
| `axis/vismach/5axis/table-rotary-tilting/demos/boat-xyzac.ngc` | Node/browser `REP` | Add TRT machine-family diagnostics evidence separate from generic 5-axis class. |
| `axis/vismach/melfa-sim/example.ngc` | Node/browser `REP` | Add robot/Genser remap-machine evidence with source files and session diagnostics. |
| `axis/vismach/puma/puma_cube.ngc` | Node/browser `REP` | Keep as PUMA representative but pair with `puma_seam_weld.ngc` Node `INV` evidence. |

### Tier 3: Macro/Load Rows With No Hard Runtime Block

These rows are not standalone main-program targets, so they should not be
promoted by executing them as browser main programs. They can move forward as
explicit macro/load fixtures if the gate names them as non-main class evidence.

| Candidate | Current status | Promotion goal |
| --- | --- | --- |
| `axis/external_offsets/queuebuster.ngc` | `NON_MAIN_CLASS` | Add external-offset macro/load source fixture next to `circles.ngc`. |
| `axis/lathe-fanucy/toolchange.ngc` | `NON_MAIN_CLASS` | Add macro/load fixture if the lathe-fanucy INI/tool context is vendored. |
| `axis/rose_engine/rcone.ngc` | inventory-only macro/load | Pair with `rcone_demo.ngc` to prove rose-engine support assets load. |
| `gscreen/industrial_lathe_wear/toolchange.ngc` | inventory-only macro/load | Candidate only if kept as macro/load evidence, not UI process emulation. |
| `gscreen/silverdragon/macros/*.ngc` | inventory-only macro/load | Candidate for a small macro fixture subset, not all macros at once. |
| `qtvcp_screens/industrial_lathe_wear/toolchange.ngc` | inventory-only macro/load | Candidate only as non-main fixture evidence. |

## Rows Still Not Promotable

Virtual HAL does not change these blocked decisions:

- `L4-PYTHON-REMAP`: still requires LinuxCNC-owned Python remap runtime proof.
  Examples include laser, many `axis/remap/*`, gmoccapy macro families, and
  table-rotary-spindle-nutating TWP demos.
- `L4-TOOL-DB`: `axis/db_demo/base.ngc` still requires tool database process
  protocol proof, not only HAL state.
- `L4-USER-M-PROCESS`: `axis/vismach/millturn/example.ngc` still requires
  external `USER_M_PATH` process state proof for `M128`/`M129`.
- `UPSTREAM-DEMO`: `incremental_repetition_g533.ngc` remains a preserved
  upstream demo edge and must not be forced to pass by standalone semantics.
- `ASSET-ONLY`: remap subroutines remain validated by parse/remap or owning
  main-program context, not standalone browser execution.

## Proposed Next Batch

The next implementation batch should avoid changing the inventory baseline.
It should add a promotion-candidate report and one or two browser evidence
fixtures.

Recommended first slice:

1. Add a machine-readable candidate report for Tier 1 rows:
   `qtdragon-on-abort`, `puma-seam-weld`, and `rose-engine`.
2. Require every row to name LinuxCNC source files, INI files, G-code files,
   dependency class, current Node status, and target browser evidence.
3. Add Node gate assertions that no candidate is in `L4-PYTHON-REMAP`,
   `L4-TOOL-DB`, `L4-USER-M-PROCESS`, `UPSTREAM-DEMO`, or `ASSET-ONLY`.
4. Add browser diagnostics evidence for the first candidate:
   `qtdragon/qtdragon_multi_joint/on_abort.ngc`.
5. Keep `sim_configs_wasm_node_inventory_executed=28`,
   `sim_configs_wasm_node_inventory_passed=28`, and
   `sim_configs_wasm_node_inventory_skipped=131` unchanged until a deliberate
   inventory-promotion patch is made.

Recommended gates:

```bash
git diff --check
wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
wasm-port/tests/sdk/node/verify_sdk_surface.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
```

## 2026-06-18 QtDragon Family Promotion Evidence

The first promotion-candidate gate has now been extended from a single
`qtdragon/qtdragon_multi_joint/on_abort.ngc` row to the full QtDragon
on-abort family:

- `qtdragon/qtdragon_multi_joint/on_abort.ngc`
- `qtdragon/qtdragon_xyz/on_abort.ngc`
- `qtdragon/qtdragon_xyz45/on_abort.ngc`
- `qtdragon_hd/qtdragon_hd_xyz/on_abort.ngc`
- `qtdragon_hd/qtdragon_hd_z_compensation/on_abort.ngc`
- `qtvcp_screens/qtdragon/on_abort.ngc`

The implementation remains a diagnostics/evidence promotion, not an inventory
baseline change. The rows still report Node inventory `PASS` with matrix
`INV`, but the virtual HAL promotion candidate report and real browser
diagnostics artifact now require every QtDragon candidate to be complete, to
name its LinuxCNC INI and G-code source files, to keep `currentNodeInventoryStatus
=== "PASS"`, and to target `explicit-browser-diagnostics`.

The virtual HAL sim-config source coverage target also includes the previously
missing QtDragon `qtdragon_xyz45` and `qtdragon_hd_z_compensation` INI/program
source files. This keeps the report source-derived from vendored LinuxCNC
machine files rather than browser-owned CNC behavior.

Inventory baseline remains:

```text
sim_configs_wasm_node_inventory_executed=28
sim_configs_wasm_node_inventory_passed=28
sim_configs_wasm_node_inventory_skipped=131
sim_configs_wasm_node_inventory_unexpected_fail=0
```

## 2026-06-18 Non-Qt Promotion Evidence

The promotion-candidate release gate has now been extended beyond QtDragon to
the two Tier 1 non-Qt candidates:

- `axis/vismach/puma/puma_seam_weld.ngc`
- `axis/rose_engine/rcone_demo.ngc`

The required candidate set now covers all eight source-derived Tier 1 rows:
the six QtDragon on-abort candidates, PUMA seam weld, and rose-engine cone
demo. Release diagnostics validation requires the PUMA row to include
`puma.ini`, `puma_seam_weld.ngc`, and the LinuxCNC remap subroutine source
`remap_subs/428remap.ngc`. It also requires the rose-engine row to include
`rose_engine.ini` and `rcone_demo.ngc`.

This still does not change inventory promotion counts. Both rows remain Node
inventory `PASS` with matrix `INV`; the added value is explicit browser
diagnostics evidence and release-gate enforcement that the virtual HAL reports
are complete for non-Qt sim-config families.

## 2026-06-18 Macro/Load Non-Main Fixture Evidence

The virtual HAL diagnostics evidence now includes an explicit macro/load
fixture report:

- `VIRTUAL_HAL_SIM_CONFIG_MACRO_LOAD_FIXTURES`
- `createVirtualHalSimConfigMacroLoadFixtureReport()`

The first required non-main fixtures are:

- `axis/rose_engine/rcone.ngc`
- `axis/external_offsets/queuebuster.ngc`

The rose-engine fixture is paired with `rcone_demo.ngc` and keeps `rcone.ngc`
as a non-main macro/load asset. The external-offsets fixture records
`queuebuster.ngc` as a declared `NGCGUI_SUBFILE` through `eoffsets.ini`; the
fixture path is preserved for diagnostics, while the manifest-backed source
evidence is the owning INI and paired LinuxCNC program source. This avoids
pretending that `queuebuster.ngc` is a standalone browser main program.

Release diagnostics validation now requires
`virtualHalSimConfigMacroLoadFixtures` to be present and ready. The report must
keep `inventoryBaselineUnchanged === true`, every row must have
`nonMainFixture === true`, and `standaloneMainViolations` must stay empty.

The next practical slice is to extend this report with one more non-main family
such as `gscreen/silverdragon/macros/tool_sensor.ngc`, after proving the owning
machine files and UI/process boundary do not cross into Python UI emulation.

## Boundary Statement

This analysis relies on the improved virtual HAL only for Web simulation
runtime surfaces. It does not claim Linux kernel hard-realtime ABI support,
external hardware driver ABI support, native HAL module ABI support, Python UI
process emulation, tool database process emulation, or external user-M process
execution. G-code, interpreter, planner, kinematics, canonical motion, machine
INI, tool table, parameter, and remap semantics remain LinuxCNC-backed.