cnc_wams/wasm-port/docs/host-runtime-boundary-handoff.md

# Host/runtime boundary release handoff

This document is the short release-gate handoff for blocked LinuxCNC runtime
families in the WASM/browser port. It summarizes current host readiness,
promotion blockers, opt-in probe dispatch state, native evidence acceptance, and
the rule that blocked runtime families remain blocked on this host.

Detailed references:

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

## Current runtime boundary families

The current runtime-boundary proof families are:

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

The current Node inventory skip/block summary now has `L4-USER-M-PROCESS=1`. `L4-TOOL-DB` is no longer a skipped inventory row,
but it remains represented in the runtime-boundary proof ledger with
`promotion_allowed=0`.

Current host readiness is summarized by:

- `build/wasm/sim-configs-inventory/runtime-boundary-host-readiness-rollup.tsv`
- `build/wasm/sim-configs-inventory/runtime-boundary-promotion-blockers.tsv`
- `build/wasm/sim-configs-inventory/runtime-boundary-opt-in-probe-dispatch-rollup.tsv`
- `build/wasm/sim-configs-inventory/runtime-boundary-native-evidence-acceptance-gate.tsv`
- `build/wasm/sim-configs-inventory/runtime-boundary-opt-in-probe-skip-evidence-rollup.tsv`
- `build/wasm/sim-configs-inventory/blocked-runtime-promotion-lock.tsv`

Current rollup state:

```text
host_readiness_status=host_ready_for_all_opt_in_native_probes
family_count=3
host_ready_family_count=3
host_blocked_family_count=0
blocked_families=-
missing_host_requirements=-
ready_opt_in_command_count=3
execution_enabled=0
promotion_allowed=0
```

Manual `L4-USER-M-PROCESS` opt-in status on the current workstation:

```text
ENABLE_MILLTURN_USER_M_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_millturn_user_m_runtime.sh
millturn_user_m_runtime_probe_status=blocked_existing_linuxcnc_runtime
millturn_user_m_missing_requirements=exclusive_linuxcnc_runtime
```

The conflicting runtime was an already-running `linuxcncsvr -ini .../axis.ini`
plus `rtapi_app load tpmod`. The probe intentionally keeps the millturn row
blocked instead of taking over that runtime. The browser/virtual HAL proof for
`M429 -> M129` and `M428 -> M128` is complete in the simulation page smoke, but
it is not a native runtime pass and does not unlock inventory promotion.

## Promotion blockers

Each blocked family currently has `promotion_ready=0`, `execution_enabled=0`,
and `promotion_allowed=0`.

For `L4-USER-M-PROCESS` and `L4-TOOL-DB`, the current generated blocker keys are:

```text
native_runtime_probe_not_passed
native_pass_evidence_not_ready
node_inventory_gate_not_complete
browser_smoke_gate_not_complete
promotion_lock_active
manual_lock_update_required
```

For the first Python remap fixture, `axis/remap/stop-lookahead/nc_files`, the
native lifecycle evidence has been accepted and the Node/browser lifecycle
gates are complete:

```text
current_probe_status=runtime_lifecycle_probe_passed
native_evidence_status=native_pass_evidence_observed
node_inventory_gate_complete=1
browser_smoke_gate_complete=1
node_gate_status=node_inventory_promotion_gate_complete
browser_gate_status=browser_smoke_promotion_gate_complete
blocking_reason=promotion_lock_active_manual_review_required
next_unblock_action=manual_lock_review_required
```

The Python row still has `promotion_ready=0`, `execution_enabled=0`, and
`promotion_allowed=0`; the remaining blockers are `promotion_lock_active` and
`manual_lock_update_required`. This proof-chain state does not promote any of
the 53 `L4-PYTHON-REMAP` rows.

For rows that still lack native evidence, the next unblock action is to provide
the missing host runtime requirements for the relevant family. Providing host
commands is not enough to promote a row; it only allows the next opt-in probe
gate to be considered.
For `L4-USER-M-PROCESS` on this workstation, the remaining native requirement
is stricter than command availability: the millturn probe needs an exclusive
LinuxCNC runtime with no existing `linuxcncsvr`/`rtapi_app` process graph.

## Opt-in probe dispatch

The current dispatch rollup is:

```text
dispatch_status=dispatch_allowed_for_all_opt_in_native_probes
probe_count=3
dispatch_allowed_count=3
dispatch_blocked_count=0
dispatch_actions=ready_for_manual_opt_in_native_probe
execution_enabled=0
promotion_allowed=0
```

These commands are opt-in only and must never run implicitly:

```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
```

Only run them deliberately when updating native proof evidence. A passing probe
does not enable execution or promotion by itself.

## Native evidence acceptance

For rows still blocked before native evidence,
`runtime-boundary-native-evidence-acceptance-gate.tsv` currently records:

- `current_probe_status=ready_disabled_by_default`
- `native_evidence_status=pending_until_native_pass`
- `skip_evidence_status=skip_contract_not_applicable_dispatch_allowed`
- `node_gate_status=blocked_until_native_pass_evidence`
- `browser_gate_status=blocked_until_node_gate_complete`
- `native_evidence_gate=blocked_until_native_pass_evidence`
- `evidence_acceptance_allowed=0`

A disabled opt-in probe is not a native pass. It only proves that this host is
not executing the family-specific runtime probe by default.

For `L4-PYTHON-REMAP`, the same artifact records accepted native lifecycle
evidence for the stop-lookahead fixture:

- `current_probe_status=runtime_lifecycle_probe_passed`
- `native_evidence_status=native_pass_evidence_observed`
- `skip_evidence_status=native_pass_evidence_observed_skip_contract_closed`
- `node_gate_status=node_inventory_promotion_gate_complete`
- `browser_gate_status=browser_smoke_promotion_gate_complete`
- `native_evidence_gate=native_pass_evidence_accepted`
- `evidence_acceptance_allowed=1`

This is evidence acceptance only. It does not change `promotion_allowed=0`.

## Release gate

Use this gate when touching blocked runtime family reports, host readiness, or
promotion policy:

```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_host_runtime_boundary_docs.sh
wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.sh
wasm-port/tests/host/verify_host_smokes.sh
```

The host aggregate must include:

```text
sim_configs_wasm_node_inventory=ok
host_runtime_boundary_docs_node_smoke=ok
sim_configs_coverage_docs_node_smoke=ok
host_wasm_opfs_browser_smokes=ok
```

## Promotion rule

No blocked family may be promoted until all of these are true:

1. Host readiness allows the family-specific opt-in probe.
2. The explicit opt-in probe passes natively with LinuxCNC-owned runtime
   behavior.
3. Native evidence acceptance allows the pass evidence.
4. Node/WASM inventory proof passes after native evidence.
5. Browser/host proof passes after Node/WASM proof.
6. `verify_no_standalone_cnc_semantics.sh` still passes.
7. `blocked-runtime-promotion-lock.tsv`, docs, and tracker records are updated
   deliberately.

Until then, `L4-USER-M-PROCESS`, `L4-TOOL-DB`, and `L4-PYTHON-REMAP` remain
locked in the runtime-boundary proof ledger with `promotion_allowed=0`; only
the inventory rows explicitly eligible for Node/WASM execution may run.