269 lines
14 KiB
Markdown
269 lines
14 KiB
Markdown
# 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.
|