cnc_wams/完善wasm/working/25-04-Host-Runtime-Opt-In-Promotion-Evidence-Gate落地蓝图.md

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 当前记录：

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 当前记录：

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 当前可以同时出现：

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 仍明确：

nativeRuntimeRequiredForPromotion=true
promotionAllowed=false
executionEnabled=false

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

Web 代表应用

目标 Web 项目当前固定：

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 必须按下列状态推进，不允许跳级：

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

建议生成位置：

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

允许的手工命令：

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

允许的手工命令：

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

允许的手工命令：

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 或真实硬件。以下字段必须保持：

hostRealtimeKernel=false
hardwareDrive=false

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

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

Promotion 判定

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

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

建议新增：

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

最低输出：

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 应增加：

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 自动继承。