cnc_wams/wasm-port/docs/sim-configs-coverage-handoff.md

# Sim-config coverage release handoff

This document is the short release-gate handoff for
`linuxcnc/configs/sim` coverage in the LinuxCNC WASM/browser port. It points to
the detailed matrix, fixes the current machine-readable inventory baseline, and
records which skipped rows remain blocked instead of promoted.

Detailed references:

- `docs/sim-configs-coverage-matrix.md`
- `docs/sim-configs-completion-plan.md`
- `docs/full-process-boundary-design.md`
- `tests/wasm/node/verify_sim_configs_inventory_wasm.mjs`

## Current inventory baseline

The current Node/WASM inventory gate is:

```bash
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
```

Required output:

```text
sim_configs_wasm_node_inventory_executed=82
sim_configs_wasm_node_inventory_passed=82
sim_configs_wasm_node_inventory_skipped=77
sim_configs_wasm_node_inventory_unexpected_fail=0
sim_configs_wasm_node_inventory_skip_ASSET_ONLY=65
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
sim_configs_wasm_node_inventory=ok
```

The generated artifact baseline is:

- `build/wasm/sim-configs-inventory/summary.tsv`
- `build/wasm/sim-configs-inventory/skip-summary.tsv`
- `build/wasm/sim-configs-inventory/boundary-summary.tsv`
- `build/wasm/sim-configs-inventory/blocked-dependency-summary.tsv`
- `build/wasm/sim-configs-inventory/full-process-boundary-summary.tsv`
- `build/wasm/sim-configs-inventory/python-remap-boundary-summary.tsv`
- `build/wasm/sim-configs-inventory/promotion-candidates.tsv`
- `build/wasm/sim-configs-inventory/remaining-skip-main-program-promotion-audit.tsv`
- `build/wasm/sim-configs-inventory/remaining-skip-simulation-implementation-coverage.tsv`
- `build/wasm/sim-configs-inventory/evidence-expansion-candidates.tsv`
- `build/wasm/sim-configs-inventory/runtime-boundary-promotion-blockers.tsv`
- `build/wasm/sim-configs-inventory/runtime-boundary-host-readiness-rollup.tsv`
- `build/wasm/sim-configs-inventory/runtime-boundary-opt-in-probe-dispatch-rollup.tsv`

The current promotion-candidate artifact is evidence accounting only. It has
10 rows total: 8 `evidence-ready` rows with virtual HAL source-derived
browser/release evidence, and 2 `inventory-ready` skipped main-program rows.
Every row keeps `promotion_allowed=0`, so the inventory baseline is now
`82/82/77/0`. The companion `evidence-expansion-candidates.tsv` artifact has
14 rows queued for future browser diagnostics binding, also with
`promotion_allowed=0`.
`remaining-skip-main-program-promotion-audit.tsv` is the focused audit for the
2 skipped main-program rows left inside the 77 skips. It keeps both
`promotion_allowed=0`: `axis/vismach/millturn/example.ngc` is still blocked on
incomplete user-M process native/inventory promotion proof, even though the
browser simulation state now includes a source-derived virtual HAL proof for
the `M429 -> M129` turn and `M428 -> M128` mill state transitions. The TWP
`incremental_repetition_g533.ngc` row remains preserved upstream demo evidence.
`remaining-skip-simulation-implementation-coverage.tsv` is the companion
77-row source-derived implementation ledger for the entire skipped set. It does
not change baseline status; instead it records how each skipped row is already
covered in the CNC simulation system: 65 rows are LinuxCNC source assets used
as remap/subroutine dependencies, 10 rows are non-main macro/load class
coverage, 1 row is the designed-but-blocked LinuxCNC-owned user-M runtime
boundary with virtual HAL state proof, and 1 row is a preserved upstream demo
edge with invalid motion source.
The 2026-06-20 re-audit confirmed that there are no directly promotable
remaining skipped main-program rows:

```text
remaining_skip_count=77
remaining_skipped_main_program_rows=2
remaining_skipped_main_program_promotion_allowed=0
direct_inventory_promotion_rows=0
baseline_change_allowed=no
```

The 65 `ASSET-ONLY` rows and 10 `NON_MAIN_CLASS` rows remain non-main evidence
targets, not standalone browser main programs.

SDK and workflow-overview release URL summaries expose the current
`evidence-ready` layer as dashboard fields: `evidence-ready-candidate-rows=8`,
`evidence-ready-candidate-preview=qtdragon-multi-joint-on-abort`,
`evidence-ready-candidate-preview-gcode=linuxcnc/configs/sim/qtdragon/qtdragon_multi_joint/on_abort.ngc`,
`evidence-ready-candidate-promotion-allowed=0`, and
`evidence-ready-candidate-baseline-changing=no`. These fields are visibility
for existing source-derived browser/release evidence, not permission to change
the Node inventory baseline.

## Skip reason map

The TSV artifacts use hyphenated reason names. The shell output uses
underscore-safe metric names. Treat these as the same baseline:

| Artifact reason | Shell metric suffix | Count | Release decision |
| --- | --- | ---: | --- |
| `ASSET-ONLY` | `ASSET_ONLY` | 65 | Subroutine/support asset; not a standalone browser main-program target. |
| `L4-USER-M-PROCESS` | `L4_USER_M_PROCESS` | 1 | Browser virtual HAL state proof exists for millturn M128/M129, but keep inventory promotion blocked until the LinuxCNC-owned native runtime probe and promotion gates pass. |
| `NON_MAIN_CLASS` | `NON_MAIN_CLASS` | 10 | Covered by class representative or macro/load policy, not direct standalone promotion. |
| `UPSTREAM-DEMO` | `UPSTREAM_DEMO` | 1 | Preserved upstream demo edge; do not force pass. |

## Promotion policy

Rows may only move from skip/inventory to promoted coverage when all of these
are true:

1. The row has a LinuxCNC-owned runtime proof for the behavior being promoted.
2. Native proof passes first.
3. Node/WASM proof passes after native proof.
4. Browser/host proof passes after Node/WASM proof.
5. `verify_no_standalone_cnc_semantics.sh` still passes.
6. Generated inventory artifacts and docs agree on the new status.

Do not promote these runtime families from JavaScript glue alone:

- `L4-PYTHON-REMAP`
- `L4-TOOL-DB`
- `L4-USER-M-PROCESS`

`L4-TOOL-DB` is no longer counted in the current skip summary, but it remains
in the runtime-boundary proof ledger with `promotion_allowed=0`.

## Release gate

Use this gate when changing sim-config coverage, promotion state, or inventory
documentation:

```bash
git diff --check
wasm-port/tools/verify_vendor_sync.sh
wasm-port/tools/verify_no_standalone_cnc_semantics.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.sh
wasm-port/tests/host/verify_host_smokes.sh
```

The host aggregate must continue to include:

```text
sim_configs_wasm_node_inventory_executed=82
sim_configs_wasm_node_inventory_passed=82
sim_configs_wasm_node_inventory_skipped=77
sim_configs_wasm_node_inventory_unexpected_fail=0
opfs_session_docs_node_smoke=ok
sim_configs_coverage_docs_node_smoke=ok
host_wasm_opfs_browser_smokes=ok
```

## Blocked runtime probes

The opt-in runtime probes remain disabled on this host unless the required
LinuxCNC runtime processes are available:

```bash
ENABLE_MILLTURN_USER_M_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_millturn_user_m_runtime.sh
ENABLE_TOOL_DB_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_tool_db_runtime.sh
ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_python_remap_runtime.sh
```

These commands are proof gates for future work, not part of the current
release gate. The current inventory must continue to record the corresponding
families as blocked.