补充 host runtime boundary release gate 文档

wasm-port/README.md

@@ -134,6 +134,8 @@ Project-level OPFS/session persistence and release-gate handoff is documented in
 `docs/opfs-session-persistence.md`.
 Sim-config inventory coverage and release-gate handoff is documented in
 `docs/sim-configs-coverage-handoff.md`.
+Host/runtime boundary release-gate handoff is documented in
+`docs/host-runtime-boundary-handoff.md`.
 
 The presence of this directory means the port is managed independently of the
 native LinuxCNC tree even though LinuxCNC remains the semantic source of truth.

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

@@ -0,0 +1,146 @@
+# 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 blocked runtime families
+
+The current hard blocked families are:
+
+- `L4-USER-M-PROCESS`
+- `L4-TOOL-DB`
+- `L4-PYTHON-REMAP`
+
+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_blocked_for_all_opt_in_native_probes
+family_count=3
+host_ready_family_count=0
+host_blocked_family_count=3
+blocked_families=L4-PYTHON-REMAP,L4-TOOL-DB,L4-USER-M-PROCESS
+missing_host_requirements=halcmd,halrun,linuxcnc,milltask
+ready_opt_in_command_count=0
+execution_enabled=0
+promotion_allowed=0
+```
+
+## Promotion blockers
+
+Each blocked family currently has `promotion_ready=0`, `execution_enabled=0`,
+and `promotion_allowed=0`.
+
+The current blocker keys are:
+
+```text
+host_runtime_requirements_missing
+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
+```
+
+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.
+
+## Opt-in probe dispatch
+
+The current dispatch rollup is:
+
+```text
+dispatch_status=dispatch_blocked_for_all_opt_in_native_probes
+probe_count=3
+dispatch_allowed_count=0
+dispatch_blocked_count=3
+dispatch_actions=skip_missing_host_requirements
+execution_enabled=0
+promotion_allowed=0
+```
+
+These commands remain blocked on this host:
+
+```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
+```
+
+Do not run them unless the generated preflight, family readiness, dispatch
+plan, and dispatch rollup all permit the specific family.
+
+## Native evidence acceptance
+
+`runtime-boundary-native-evidence-acceptance-gate.tsv` currently records:
+
+- `current_probe_status=skipped_missing_host_runtime`
+- `native_evidence_status=pending_until_native_pass`
+- `skip_evidence_status=skip_valid_until_host_requirements_available`
+- `node_gate_status=blocked_until_native_pass_evidence`
+- `browser_gate_status=blocked_until_node_gate_complete`
+- `native_evidence_gate=blocked_until_host_requirements_available`
+- `evidence_acceptance_allowed=0`
+
+A skipped opt-in probe is not a native pass. It only proves that this host is
+correctly blocked until the required LinuxCNC runtime commands are available.
+
+## 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
+blocked, inventory-only runtime families.

wasm-port/tests/docs/node/verify_host_runtime_boundary_docs.mjs

@@ -0,0 +1,100 @@
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "../../..");
+
+function literalRegExp(text) {
+  return new RegExp(text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+}
+
+function parseTsv(text) {
+  const [headerLine, ...lines] = text.trim().split(/\r?\n/);
+  const headers = headerLine.split("\t");
+  return lines.map((line) => {
+    const cells = line.split("\t");
+    return Object.fromEntries(headers.map((header, index) => [header, cells[index] ?? ""]));
+  });
+}
+
+const docText = readFileSync(resolve(root, "docs/host-runtime-boundary-handoff.md"), "utf8");
+const fullProcessText = readFileSync(resolve(root, "docs/full-process-boundary-design.md"), "utf8");
+const simHandoffText = readFileSync(resolve(root, "docs/sim-configs-coverage-handoff.md"), "utf8");
+const inventoryTestText = readFileSync(
+  resolve(root, "tests/wasm/node/verify_sim_configs_inventory_wasm.mjs"),
+  "utf8",
+);
+const hostSmokeText = readFileSync(resolve(root, "tests/host/verify_host_smokes.sh"), "utf8");
+const readmeText = readFileSync(resolve(root, "README.md"), "utf8");
+const trackerText = readFileSync(resolve(root, "../PROJECT_COMPLETION_TRACKER.md"), "utf8");
+
+for (const phrase of [
+  "Host/runtime boundary release handoff",
+  "runtime-boundary-host-readiness-rollup.tsv",
+  "runtime-boundary-promotion-blockers.tsv",
+  "runtime-boundary-opt-in-probe-dispatch-rollup.tsv",
+  "runtime-boundary-native-evidence-acceptance-gate.tsv",
+  "blocked-runtime-promotion-lock.tsv",
+  "host_readiness_status=host_blocked_for_all_opt_in_native_probes",
+  "missing_host_requirements=halcmd,halrun,linuxcnc,milltask",
+  "dispatch_status=dispatch_blocked_for_all_opt_in_native_probes",
+  "current_probe_status=skipped_missing_host_runtime",
+  "native_evidence_status=pending_until_native_pass",
+  "evidence_acceptance_allowed=0",
+  "ENABLE_MILLTURN_USER_M_RUNTIME_PROBE=1",
+  "ENABLE_TOOL_DB_RUNTIME_PROBE=1",
+  "ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1",
+  "L4-USER-M-PROCESS",
+  "L4-TOOL-DB",
+  "L4-PYTHON-REMAP",
+  "host_runtime_boundary_docs_node_smoke=ok",
+]) {
+  assert.match(docText, literalRegExp(phrase));
+}
+
+for (const phrase of [
+  "runtime-boundary-host-readiness-rollup.tsv",
+  "runtime-boundary-opt-in-probe-dispatch-rollup.tsv",
+  "runtime-boundary-native-evidence-acceptance-gate.tsv",
+]) {
+  assert.match(fullProcessText, literalRegExp(phrase));
+  assert.match(inventoryTestText, literalRegExp(phrase));
+  assert.match(docText, literalRegExp(phrase));
+}
+
+assert.match(simHandoffText, /L4-PYTHON-REMAP/);
+assert.match(hostSmokeText, /verify_host_runtime_boundary_docs\.sh/);
+assert.match(readmeText, /docs\/host-runtime-boundary-handoff\.md/);
+assert.match(trackerText, /Host\/runtime boundary/);
+
+const hostRollupPath = resolve(
+  root,
+  "build/wasm/sim-configs-inventory/runtime-boundary-host-readiness-rollup.tsv",
+);
+if (existsSync(hostRollupPath)) {
+  const [row] = parseTsv(readFileSync(hostRollupPath, "utf8"));
+  assert.equal(row.host_readiness_status, "host_blocked_for_all_opt_in_native_probes");
+  assert.equal(row.family_count, "3");
+  assert.equal(row.host_ready_family_count, "0");
+  assert.equal(row.host_blocked_family_count, "3");
+  assert.equal(row.missing_host_requirements, "halcmd,halrun,linuxcnc,milltask");
+  assert.equal(row.execution_enabled, "0");
+  assert.equal(row.promotion_allowed, "0");
+}
+
+const dispatchRollupPath = resolve(
+  root,
+  "build/wasm/sim-configs-inventory/runtime-boundary-opt-in-probe-dispatch-rollup.tsv",
+);
+if (existsSync(dispatchRollupPath)) {
+  const [row] = parseTsv(readFileSync(dispatchRollupPath, "utf8"));
+  assert.equal(row.dispatch_status, "dispatch_blocked_for_all_opt_in_native_probes");
+  assert.equal(row.dispatch_allowed_count, "0");
+  assert.equal(row.dispatch_blocked_count, "3");
+  assert.equal(row.execution_enabled, "0");
+  assert.equal(row.promotion_allowed, "0");
+}
+
+console.log("host_runtime_boundary_docs_node_smoke=ok");

wasm-port/tests/docs/node/verify_host_runtime_boundary_docs.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/../../.." && pwd)"
+
+node "$ROOT_DIR/tests/docs/node/verify_host_runtime_boundary_docs.mjs"

wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.mjs

@@ -68,7 +68,7 @@ for (const reason of [
 assert.match(inventoryTestText, /sim_configs_wasm_node_inventory_skip_/);
 assert.match(hostSmokeText, /verify_sim_configs_inventory_wasm\.sh/);
 assert.match(hostSmokeText, /verify_sim_configs_coverage_docs\.sh/);
-assert.match(trackerText, /sim-config coverage/);
+assert.match(trackerText, /Sim config coverage|sim-config coverage/);
 
 const skipSummaryPath = resolve(root, "build/wasm/sim-configs-inventory/skip-summary.tsv");
 if (existsSync(skipSummaryPath)) {

wasm-port/tests/host/verify_host_smokes.sh

@@ -16,6 +16,7 @@ SKIP_TP_BUILD=1 "$ROOT_DIR/tests/wasm/node/verify_tp_wasm.sh"
 "$ROOT_DIR/tests/sdk/node/verify_sdk_surface.sh"
 "$ROOT_DIR/tests/docs/node/verify_opfs_session_docs.sh"
 "$ROOT_DIR/tests/docs/node/verify_sim_configs_coverage_docs.sh"
+"$ROOT_DIR/tests/docs/node/verify_host_runtime_boundary_docs.sh"
 "$ROOT_DIR/tests/ui/node/verify_ui_node_smokes.sh"
 SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/browser/verify_ini_panel_browser.sh"
 SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/browser/verify_interp_browser.sh"