qinglong/docs/adr/ADR-0178-concrete-local-headless-application-process.md

ADR-0178：Concrete Local Headless Application Process

• 状态：Accepted
• 日期：2026-07-27
• 关联：RFC D-37、D-40、D-65、D-138、D-167、D-168；ADR-0066、ADR-0140、ADR-0177

背景

@qinglong/local-application 已经拥有 adopted SQLite、Plugin Package 恢复、Secret preflight、Run reconciliation、execution control 和 scheduler，但此前仍要求调用方注入 一个 create(context)：

create → synthetic recover → synthetic lifecycle → synthetic admission → synthetic stop

仓库中没有生产实现，只有测试返回这一组方法。结果是 application 看似有组合根，实际 产品仍无法独立启动；新增 CLI 若继续注入一只 no-op Stack，只会把测试替身包装成 “可执行产品”。

另外，本机 scheduler 和 execution lifecycle 为了嵌入式/测试调用者都使用 unref timer。未决 Promise 不维持 Node.js 进程，因此 headless binary 还必须显式拥有一个 process lifetime handle。

决策

1. 删除没有生产实现的 Stack seam

移除 LocalApplicationStack、LocalApplicationAdmission、 LocalApplicationAssemblyContext、LocalApplicationRecoverySummary 和 enabled options 的 create factory。bootstrapLocalApplication 自身就是 concrete headless runtime，并直接拥有：

adopted storage/source fence
  → Plugin Package install recovery
  → Task publication recovery
  → Tool snapshot recovery
  → Secret keyring preflight
  → receipt-first Run recovery
  → execution control reconciliation
  → execution-control + scheduler lifecycle
  → active

停止顺序固定为 scheduler admission/drain → execution-control drain → adopted storage 与 source fence。启动失败按同一 ownership 逆序 best-effort 清理。这里没有 HTTP listener，因此不保留一只虚构的 transport admission object；未来 API host 必须作为 外层真实 transport composition 拥有自己的 admission/drain。

2. 在现有 package 内提供 executable

不新增 workspace package。在 @qinglong/local-application 内增加：

• ql3-local-application binary；
• /process-config 严格配置子路径；
• /process 可测试的 process composition 子路径。

配置只从一个规范化绝对路径的私有 JSON 文件读取。复用现有 @qinglong/local-command-file 的 POSIX identity、0600、regular-file、 O_NOFOLLOW、16 KiB 和打开前后 inode/size fence，不复制一份较弱的文件读取器。 配置 schema 为 qinglong/local-application-process@v1，采用 exact shape，并要求：

• 稳定且有界的 instanceId；
• edge|standalone Profile；
• 五个互不别名的 adoption/storage authority path；
• activation digest；
• receipt、Artifact、Secret keyring 与 Plugin Package roots；
• 显式 AI deployment state。

路径和 digest 不进入 stdout/stderr 事实。CLI 只接受 --config /absolute/private-config.json，不接受大量环境变量、明文 token 或任意 JSON override。

3. executable 必须选择产品 composition

进程统一调用 ADR-0177 的 AI-aware product composition：

• deployment=excluded 启动 base application，且不加载 AI runtime/provider；
• deployment=installed 必须获得受信 loadAiProviders authority；
• CLI 当前没有 provider ceremony，因此 installed 在触碰 storage 前失败关闭；
• schema absent/inactive/active 的后续裁决仍由 ADR-0177 durable head 执行。

这使 executable 不会绕过 durable 9007 head，也不会为了“先能跑”而从环境变量构造 明文 API token。provider binding/Policy/Secret material ceremony 是下一独立安全门。

4. 信号和 process lifetime 属于进程组合根

进程在 storage startup 前订阅 SIGINT/SIGTERM，内部 fence 只接受第一个信号，并 在 finally 解除订阅。收到信号后必须调用统一 stop()，将 timed_out 映射为非零 退出，不能直接依赖 Node 默认退出。

library timer 继续全部 unref。binary 额外持有一只最大 Node timer 周期 2_147_483_647 ms 的 referenced keepalive，正常/失败退出必定清理；它约 24.8 天才 可能唤醒一次，不给路由设备增加短周期轮询。真实 child-process 门验证 process 在 active 后不会因零 referenced handle 自行退出，并能接收 SIGTERM、完成 drain、释放 legacy source fence 后以 0 退出。

5. 恢复 source 不得伪造

嵌入式 host 可注入受信 PluginPackageStageProvider。通用 CLI 没有离线 bundle/OCI credential catalog authority，因此默认 provider 只在存在 queued stage work 时以 QL3_LOCAL_APPLICATION_PLUGIN_SOURCE_UNAVAILABLE 失败关闭；空队列不触碰 source。

不得返回伪造 stage evidence，也不得把“不知道如何恢复”当成 safe-to-admit。通用 ADR-0179 已补充通用 materialized offline/OCI recovery catalog；它只消费部署者预先 放入的本机签名 bundle，不给常驻 application Registry credential 或网络 authority。 catalog 的认证发布/GC、在线 OCI fetch、credential rotation 与管理入口仍属于后续 产品门。

6. 只输出低敏、机器可读事实

stdout 每行一个 schema v1 JSON fact，只包含 component、instance/profile、activation state、有界 recovery count、AI state、signal 和 stop result。启动错误只输出 name/code，不输出 Error message、路径、digest、SecretRef、credential 或堆栈。

拒绝方案

1. 保留 no-op Stack 并由 CLI 注入：把测试替身冒充生产 runtime，拒绝。
2. 再拆 local-application-process package：没有独立部署/依赖收益，加剧过细 importer，拒绝。
3. 把入口接进 back/app.ts：会让 2.x worker/master 成为 3.0 cutover authority， 破坏 side-by-side fence，拒绝。
4. 从环境变量直接读 provider token：绕过 Project SecretRef、binding、Policy 和 audit，拒绝。
5. 让未决 Promise 自然维持进程：Node.js 不提供该保证，真实门已证明会提前退出， 拒绝。
6. 对 queued Plugin Package 返回空 evidence：会在未知 source 下开放 admission， 拒绝。

当前证据

• local-application 29/29，包含 real SQLite/adoption/Secret/Run 启动、首信号、 installed-AI pre-storage fail-close、默认 Package source fail-close、CLI usage/脱敏， 以及真实 child process active → SIGTERM → drain → exit 0 → source fence released；
• dependency/source boundary 30/30，workspace 仍为 22 个 QL3 package；本增量只复用既有 单文件协议 primitive，没有新增 importer；
• 22-package clean build/test 全绿，legacy/back 兼容回归 802/802；disabled AI benchmark 只加载 1 个 AI module，storage/provider/management loader 均为 0；
• edge/standalone application 为 4,631,855/4,631,999 bytes、603 files、90 loaded modules；AI-inclusive application 为 5,309,676/5,309,832 bytes、647 files、 89 startup-loaded modules，全部通过既有预算；门禁同时验证 /process import、精确 bin manifest、离线安装后的 --help 和 ADR-0179 catalog subpath；
• edge import audit 为 121 modules，forbidden root dependency/import 均为空；
• PostgreSQL 18.4 arm64 physical HA 在本增量前已重跑，gates.passed=true；本决策 未修改 Cluster schema、migration 或进程。

后续门禁

1. provider binding/Policy/Secret material 的本机产品 ceremony，并让 installed AI CLI 可达；
2. ADR-0179 catalog 的认证发布/GC ceremony 与短生命周期 OCI fetcher；
3. 由独立 deployment/cutover controller 启动该 binary，完成 2.x 停机与 3.0 source fence 的外部证据闭环；
4. 真实 HTTP/Unix-socket API host 的 admission、认证、Policy、audit 与有界 drain；
5. 固定低配 Linux 路由器的冷启动、idle RSS、24h wakeup/write、断电、ENOSPC 和恢复 证据。