ADR-0204：物理 Edge Native Application 首次 Active 候选证据

状态：Accepted
日期：2026-07-29
关联 RFC：QL-RFC-0001 D-86、D-87、D-175、D-194
关联 ADR：ADR-0088、ADR-0090、ADR-0178、ADR-0193、ADR-0194

背景

物理 Edge 基础报告仍缺少 cold_start_and_first_ready。现有 ql3-local-image-live-contract 会在 Docker 中等待 45 秒内出现 active，但它不记录物理设备、boot、artifact closure、启动时延或进程资源；模块 import 和 Executor benchmark 更不能证明完整 application 已开放 admission。

同时，很多低配路由器使用 OpenRC/native Node，并不安装 Docker。把 Compose 容器作为唯一冷启动证据会排除主要 Edge 用户。另一方面，Node 编写的 recorder 自身已经加载 Node runtime，安全的 artifact tree preflight 也会预热目录/inode metadata；该数据不能被命名为完整 power-on cold start。

决策

1. 三阶段、无常驻资源的 native recorder

根命令 evidence:physical-edge-application-start 提供：

inspect：建立 production release closure 与 Node binary inventory；
prepare：准备 fresh native Edge deployment并发布跨 boot session；
resume：在新 boot 启动正式 application CLI、计量并发布 report。

它是 repository script，不新增 workspace package、生产依赖、daemon、timer、 watcher、端口或 service installation。工具不会 reboot/poweroff，也不会指向或修改生产 deployment。

2. 只接受最终 AI-excluded production closure

artifact root 必须是 canonical、无 symlink、无 hard link、只含 trusted owner （root 或 recorder UID）且 group/other 不可写的 regular tree。上限为 768 files、 256 directories、8 MiB。顶层安装包必须精确等于：

10 个受审 @qinglong/local-*/runtime-core application runtime package；
croner；
semver。

@qinglong/local-application 必须是 3.0.0-alpha.0，Node engine 为 >=24.18.0 <25，bin 精确指向 dist/cli.js。inventory digest 覆盖每个相对 path、mode、bytes 和 file SHA-256；manifest 固定 artifact digest/files/bytes 与 Node binary SHA-256。

当前 production packlist 的真实门禁结果为 12 packages、5,045,360 bytes、627 files、90 loaded modules，仍低于既有 application artifact budget。

3. Prepare 使用正式 deployment API

prepare 要求 Linux、匹配 device architecture/filesystem、当前 UID 的 canonical 0700 data path，以及位于其内的 session path。它通过正式 prepareLocalDeployment 创建 .ql3-application-start-<UUID> fresh Edge deployment，service descriptor 使用真实 Node 和 artifact entrypoint，kind 为 OpenRC-compatible；application config、SQLite v35、Secret/keyring 和 runtime directories 均来自产品准备路径。

session 以 0600、no-replace、fsync 和 SHA-256 发布，绑定 manifest、artifact、 Node、UID、prepare boot、data/deployment/config/entrypoint 的确定性路径，并绑定每个 entry 的 device/inode/size/mode/uid/gid/link/mtime/ctime metadata digest。随后必须由 operator 在工具外重启。

4. Resume 只裁决 warm-Node application closure 到 active

resume 要求：

boot ID 与 prepare 不同；
boot age 不超过 manifest 的 10 秒至 10 分钟显式上限；
UID、Node path/version、architecture、filesystem 和全部路径未漂移；
artifact metadata 在启动前仍无 symlink/不可信 mode，file count 未变化。

计时点从 recorder 调用 spawn 前开始，到 stdout 首次收到唯一正式事件：

{
  "schemaVersion": 1,
  "component": "qinglong3-local-application",
  "level": "info",
  "event": "active",
  "profile": "edge",
  "aiStatus": "deployment_excluded"
}

manifest 为 first-active latency、sampled RSS 和 10–1000 ms sample interval 设置显式预算。/proc/<pid> identity 必须保持同一 Node executable、UID、PID start ticks；I/O 只计算首个成功 sample 到 active sample 的非负差值。active 后发送 SIGTERM，要求单一 shutdown/stopped 事件、exit 0、无 signal、零 stderr，再通过 production SQLite snapshot inspector 验证 contract v35。最后才读取并重算完整 artifact/Node content，以避免 application closure 在计时前被 recorder 主动读热。

5. 结论必须保持窄作用域

报告永久 supported:false，明确不证明：

Node runtime 或 dynamic linker 的 cold cache；
artifact directory/inode cold cache或 exclusive page-cache provenance；
首个 /proc sample 之前的 I/O、采样间 RSS peak；
firmware power-on 到 service manager、OpenRC/systemd supervisor latency；
Compose/container cold start、突然断电、整机 wakeup/flash 写放大；
release archive signature/attestation、Standalone 或 Cluster。

统一 aggregator 成功导入后增加 post_reboot_warm_node_native_application_start_to_active，并把 cold_start_and_first_ready 细化为仍未完成的 power_on_cold_node_and_service_manager_start_to_first_ready。这不是把 broad Gate 标记为完成。

验收证据

recorder manifest/phase/artifact/session/event/report 纯契约 8/8；
aggregator 私有文件、same-device/current-boot binding 与 remaining Gate 细化；
recorder + aggregator 专项 21/21；
production edge-application packlist 门通过，精确 12 packages；
没有新增 package、生产依赖或常驻资源。

macOS 开发机没有物理 Linux boot/proc 语义，因此未运行真实 prepare/resume。 Accepted 表示协议、采集器和失败关闭门已实现，不表示某个路由器已有启动支持数字。

被拒绝的替代方案

只记录模块 import 时间：没有启动 storage/recovery/scheduler/application。
只跑 Docker 镜像：排除没有容器运行时的 Edge 路由器。
把 recorder Node 启动算进 cold Node：recorder 已经预热同一 binary。
在启动前重算全部 artifact SHA：主动读热 application closure。
自动 drop caches/reboot：需要危险的整机 authority，且影响其他服务。
把 sampled RSS 称为绝对 peak：采样间峰值不可见。
新增 benchmark package/agent：没有独立交付边界并增加 Edge 常驻成本。

6.2 KiB Raw Blame History Unescape Escape