cnc_wams/wasm-port/docs/sim-config-coverage-promotion-analysis.md

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:

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:

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

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.