323 lines
14 KiB
Markdown
323 lines
14 KiB
Markdown
# 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` 自动继承。
|