# 25-04 Host Runtime Opt-In Promotion Evidence Gate 落地蓝图

> 后续状态：evidence schema、状态机、release/promotion separation 和 Web 字段已由 `29` 实施完成；人工 promotion lock、realtime 和 hardware 边界不变。

## 定位

本文件落实 `ACC-037/INT-024`：在 `22-04-Full-Process-Realtime-Runtime-Proof实现缺口复核.md` 已经区分 Web/WASM simulation runtime 与宿主能力之后，继续把宿主 User-M、Tool DB、Python remap、实时内核、硬件驱动和完整 native process topology 的 opt-in、证据接受、人工解锁与晋级规则固定为可机读合同。

严格口径：项目发布 gate 通过、host 命令齐全、允许手工 dispatch、probe 默认禁用或某个单 fixture native pass，都不能自动等价为宿主能力已晋级。宿主能力必须拥有独立 evidence、独立 promotion lock 和独立人工审查结果。

## LinuxCNC 权威边界

| 能力 | LinuxCNC 权威来源 | 必须证明的宿主行为 |
| --- | --- | --- |
| User-M 外部进程 | `src/emc/task/emctask.cc` 的 `USER_M_PATH`/`USER_DEFINED_FUNCTION_ADD`；`emctaskmain.cc` 的 `EMC_SYSTEM_CMD`、`fork/exec/waitpid` | 搜索、注册、启动、退出状态、异常/中止和配置副作用均由 LinuxCNC-owned runtime 执行 |
| Tool DB 外部进程 | `src/emc/task/taskclass.cc`、`src/emc/tooldata/tooldata_db.cc`、`configs/sim/axis/db_demo` | `DB_PROGRAM` 启动、v2.1 handshake、g/p/l/u 协议、持久状态与失败路径 |
| Python remap | `src/emc/rs274ngc` Python plugin/remap 路径、`tests/remap`、代表 `configs/sim` fixture | Python runtime 生命周期、callable lookup、generator/yield、解释器状态绑定和异常传播 |
| Linux realtime/HAL thread | `src/rtapi`、`src/hal/hal_lib.c`、`src/emc/motion/motion.c`、`control.c` | `rtapi_app_main`、真实 HAL thread、周期调度、motion controller/command handler 和实时属性 |
| 硬件驱动 | `src/hal/drivers`、设备特定模块、真实 IO/HAL pin | 明确硬件环境、驱动加载、IO 回读、故障和安全策略 |
| 完整 native process topology | Task/NML/Motion/HAL/IO/RTAPI 进程与共享状态 | 进程启动顺序、NML/共享内存、状态机、退出/恢复和跨进程一致性 |

## 当前机器可读事实

### Host readiness 与 dispatch

`wasm-port/build/wasm/sim-configs-inventory/runtime-boundary-host-readiness-rollup.tsv` 当前记录：

```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
execution_enabled=0
promotion_allowed=0
```

`runtime-boundary-opt-in-probe-dispatch-rollup.tsv` 当前记录：

```text
dispatch_status=dispatch_allowed_for_all_opt_in_native_probes
dispatch_allowed_count=3
dispatch_blocked_count=0
execution_enabled=0
promotion_allowed=0
```

结论：host ready 和 dispatch allowed 只表示可以手工考虑运行 probe；二者都不是执行证据，更不是 promotion。

### 三个 runtime family

| Family | 当前 probe status | Native evidence | Node/Browser | Promotion |
| --- | --- | --- | --- | --- |
| `L4-USER-M-PROCESS` | `ready_disabled_by_default` | `pending_until_native_pass` | 等待 native pass | `0` |
| `L4-TOOL-DB` | `ready_disabled_by_default` | `pending_until_native_pass` | 等待 native pass | `0` |
| `L4-PYTHON-REMAP` stop-lookahead fixture | `runtime_lifecycle_probe_passed` | `native_pass_evidence_accepted` | 对应 fixture gate 完成 | 仍为 `0`，等待 manual lock review |

因此：

- `ready_disabled_by_default` 不是 pass。
- `runtime_lifecycle_probe_passed` 只属于具体 Python fixture，不能批量晋级 53 个 Python remap rows。
- `evidence_acceptance_allowed=1` 不是 `promotion_allowed=1`。
- `promotion_lock_active=1` 时任何自动化都不得改写状态。

### Project release readiness

`wasm-port/build/project-release-readiness.json` 当前可以同时出现：

```text
phase=ready
ready=true
releaseGate.passed=true
blockedRuntimeFamilies=[L4-USER-M-PROCESS,L4-PYTHON-REMAP]
promotedRuntimeFamilies=[]
promotedBlockedFamilies=[]
```

其中 Tool DB Web/WASM proof 可以 `ready=true`，但其 summary 仍明确：

```text
nativeRuntimeRequiredForPromotion=true
promotionAllowed=false
executionEnabled=false
```

结论：项目发布 readiness 证明当前已声明范围可发布，不证明所有 blocked runtime family 已解除。

### Web 代表应用

目标 Web 项目当前固定：

```text
promotionScope=web_simulation_only
hardwareDrive=false
hostRealtimeKernel=false
hostExternalUserMProcessReady=false
hostToolDbProcessReady=false
arbitraryUserMExecution=false
```

Web 中 `externalUserMProcessReady=true` 或 `toolDbProcessReady=true` 只能与 `Scope=web_simulation_only` 同时成立，不得映射为 host process ready。

`native-task-hal-audit.js` 允许 `ready_disabled_by_default` 或 `skipped_missing_host_runtime` 作为“Web blocked boundary 表达一致”的可接受默认状态，但这只用于证明 host promotion 没有被意外打开；不得把该 `nativeProbeOk` 内部判断解释成 native runtime pass。

## 状态机

每个宿主 family 必须按下列状态推进，不允许跳级：

```text
host_unavailable
  -> host_ready
  -> dispatch_allowed
  -> ready_disabled_by_default
  -> probe_running
  -> native_probe_passed
  -> native_evidence_accepted
  -> node_gate_complete
  -> browser_gate_complete
  -> manual_review_required
  -> promotion_allowed
```

失败/旁路状态：

| 状态 | 含义 | Promotion |
| --- | --- | --- |
| `skipped_missing_host_runtime` | 缺命令、库、权限或环境 | 禁止 |
| `blocked_existing_linuxcnc_runtime` | 已有 LinuxCNC process graph 冲突 | 禁止，不得终止用户进程抢占环境 |
| `blocked_missing_source` | LinuxCNC/config source 不完整 | 禁止 |
| `probe_failed` | 运行或断言失败 | 禁止 |
| `native_probe_passed` | 仅 native probe 已通过 | 仍禁止自动晋级 |
| `native_evidence_accepted` | Native evidence schema/来源已接受 | 仍需 Node/Browser 和人工解锁 |
| `manual_review_required` | 自动 gate 已完成，锁仍生效 | 禁止自动晋级 |

## `host_runtime_opt_in_evidence` Schema

建议生成位置：

```text
wasm-port/build/evidence/host-runtime-opt-in-evidence.json
web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/host-runtime-opt-in-evidence.json
```

顶层最小字段：

| 字段 | 规则 |
| --- | --- |
| `apiName` | 固定为 `host_runtime_opt_in_evidence` |
| `schemaVersion` | 固定为 `1` |
| `upstreamCommit` | 锁定 LinuxCNC commit |
| `generatedAt` | UTC 时间 |
| `projectReleaseReady` | 与 host promotion 分离记录 |
| `webSimulationPromotionAllowed` | 只对应 Web simulation boundary |
| `hostPromotionAllowed` | 只有全部指定 family 完成且人工解锁才可为 `true` |
| `families[]` | User-M、Tool DB、Python fixture；未来 realtime/hardware 单独增加 |
| `integrity.complete` | schema 和 artifact hash 完整性 |

`families[]` 每项最小字段：

| 字段 | 规则 |
| --- | --- |
| `boundaryClass` | `L4-USER-M-PROCESS`、`L4-TOOL-DB`、`L4-PYTHON-REMAP` 等 |
| `target` | 精确 fixture/profile，不允许写成模糊 family 后批量继承 |
| `linuxCncReferences[]` | 源码、配置、测试路径 |
| `optInEnv` | 明确的单一 opt-in 环境变量 |
| `hostReady` | 命令/库/权限可用 |
| `dispatchAllowed` | 安全前置检查允许手工运行 |
| `executionEnabled` | 默认必须为 `false` |
| `probeStatus` | 使用本文件状态枚举 |
| `nativeEvidenceStatus` | pending/observed/accepted/rejected |
| `nativeEvidenceArtifacts[]` | stdout/stderr/TSV/JSON 与 SHA-256 |
| `nodeGateComplete` | 布尔值 |
| `browserGateComplete` | 布尔值 |
| `promotionLockActive` | 默认 `true` |
| `manualReview` | reviewer、decision、timestamp、reason；未审查时为空 |
| `promotionAllowed` | 不得由 probe 脚本直接写成 `true` |
| `blockers[]` | 全部未满足条件 |

## Opt-In 安全合同

### 默认行为

- 所有宿主 probe 默认不运行，只输出 `ready_disabled_by_default` 或明确 skip/block 状态。
- CI、browser smoke、release gate 和普通 Node gate 不得设置 opt-in 环境变量。
- probe 不得静默启动硬件驱动、占用设备、修改系统配置或终止既有 LinuxCNC 进程。
- probe 输出必须始终保留 `execution_enabled=0`、`promotion_allowed=0`；实际晋级由独立人工审查 artifact 完成。

### User-M

允许的手工命令：

```bash
ENABLE_MILLTURN_USER_M_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_millturn_user_m_runtime.sh
```

必须证明：LinuxCNC-owned `USER_M_PATH -> EMC_SYSTEM_CMD -> M128/M129` 执行，进程退出状态，以及 `ini.[xyz].*` HAL pin 的切换前后值。若发现已有 `linuxcncsvr`/`rtapi_app`，必须返回 `blocked_existing_linuxcnc_runtime`。

### Tool DB

允许的手工命令：

```bash
ENABLE_TOOL_DB_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_tool_db_runtime.sh
```

必须证明：LinuxCNC Tool DB child process、协议 handshake、命令/reply、持久状态和异常关闭。Web Worker/Python-WASM proof 不能替代 native DB_PROGRAM pass。

### Python remap

允许的手工命令：

```bash
ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_python_remap_runtime.sh
```

必须按 fixture 保存 lifecycle evidence。stop-lookahead pass 只能晋级 stop-lookahead；批量 family promotion 必须逐 fixture 或由等价覆盖矩阵证明，且仍需 manual lock review。

### Realtime 与硬件

当前三个 opt-in probe 不覆盖 Linux realtime kernel 或真实硬件。以下字段必须保持：

```text
hostRealtimeKernel=false
hardwareDrive=false
```

要解除它们，必须另建专用任务和安全合同，至少包括：

- 独立测试主机/容器或实验设备标识。
- realtime kernel/RTAPI backend、latency/period/deadline 证据。
- 真实 HAL driver/module、设备白名单和 IO loopback。
- 急停、限位、故障注入和清理恢复。
- 明确人工授权，不能继承本文件三个 process probe 的 opt-in 权限。

## Promotion 判定

单个 family 的 `promotionAllowed=true` 必须满足全部条件：

```text
hostReady
&& dispatchAllowed
&& probeStatus == expectedPassStatus
&& nativeEvidenceStatus == accepted
&& nodeGateComplete
&& browserGateComplete
&& noUnexpectedFailures
&& sourceGuardPassed
&& promotionLockActive == false
&& manualReview.decision == approved
```

全局 `hostPromotionAllowed=true` 还必须声明 promotion scope。单个 Python fixture 通过时，不得写成整个 Python runtime family 通过。

项目 release gate 必须增加反向断言：

- `ready=true` 时允许存在 `blockedRuntimeFamilies`，但必须完整列出。
- `promotedBlockedFamilies` 必须为空，除非存在已批准的 family evidence。
- `hostPromotionAllowed=false` 时 Web UI 必须显示 host process/realtime/hardware false。
- `ready_disabled_by_default`、`skipped_*`、`blocked_*` 不得被 accepted status 集合当作 native pass。

## 建议 Gate

### `wasm-port`

建议新增：

```text
wasm-port/tests/host/verify_host_runtime_opt_in_evidence.mjs
wasm-port/tests/host/verify_host_runtime_promotion_state_machine.mjs
wasm-port/tests/host/verify_project_release_vs_host_promotion.mjs
```

最低输出：

```text
host_runtime_opt_in_evidence_schema=ok
host_runtime_promotion_state_machine=ok
project_release_host_promotion_separation=ok
disabled_probe_not_native_pass=ok
single_fixture_not_bulk_promotion=ok
realtime_hardware_remain_blocked=ok
```

### Web 代表应用

目标 Web evidence 应增加：

```text
hostRuntimeOptInEvidence
hostPromotionSummary
blockedRuntimeFamilies
```

Browser gate 必须验证：

- `promotionScope=web_simulation_only`。
- host User-M/Tool DB、realtime、hardware 均显示 false。
- Web simulation ready 与 host promotion false 可以同时正确显示。
- 任何 host family 状态变化必须来自签名/哈希匹配的 evidence artifact，不得由 UI toggle 直接修改。

## 当前严格状态

| 能力 | 当前状态 | 晋级条件 |
| --- | --- | --- |
| Web/WASM task-motion-HAL simulation | 可按 `22` 晋级 | 保持 host/realtime/hardware false |
| User-M native external process | `ready_disabled_by_default`，Blocked | 手工 native pass、evidence accepted、Node/Browser、manual unlock |
| Tool DB native process | `ready_disabled_by_default`，Blocked | native protocol pass、evidence accepted、Node/Browser、manual unlock |
| Python stop-lookahead fixture | native evidence accepted，仍锁定 | manual review；只允许 fixture scope |
| Python remap family | Blocked | 覆盖矩阵、逐 fixture evidence、manual unlock |
| Linux realtime kernel | Blocked/非 Web 目标 | 独立 realtime 安全任务与专用证据 |
| 真实硬件驱动 | Blocked/非 Web 目标 | 独立硬件实验环境、安全授权和 IO evidence |
| 完整 native process topology | Blocked/条件通过 | Task/NML/Motion/HAL/IO/RTAPI 全链路独立 proof |

## 与现有文件的关系

- `22-04-Full-Process-Realtime-Runtime-Proof实现缺口复核.md`：定义 Web simulation promotion 边界。
- `wasm-port/docs/host-runtime-boundary-handoff.md`：现有 host family、TSV、opt-in 命令和 promotion rule。
- 本文件：把状态机、JSON schema、release/promotion 分离、人工解锁和 realtime/hardware 非继承规则纳入总控。
- 后续实际实现 gate 后，必须回填 `05-验收证据.md`，并只更新对应 fixture/family 的状态。

## 结论

`ACC-037/INT-024` 已完成 Host Runtime Opt-In Promotion Evidence Gate 落地蓝图。当前 host 已具备运行三个 opt-in probe 的前置条件，但 `execution_enabled=0`、`promotion_allowed=0` 仍是正确状态；User-M/Tool DB 默认未运行，Python stop-lookahead 只有单 fixture native evidence accepted，实时内核和硬件完全不在这三个 opt-in probe 的覆盖范围。任何后续晋级必须经过独立 evidence、Node/Browser gate 和人工解锁，不能由项目 release `ready=true` 自动继承。