qinglong/docs/adr/ADR-0234-single-identity-production-worker-process-and-deployment.md

# ADR-0234：单身份 Production Worker 进程与部署边界

- 状态：Accepted（生产进程、镜像依赖根、Kubernetes 单身份基线、macOS arm64 资源证据及真实 PostgreSQL 凭据在线轮换已实现；Linux cgroup、真实镜像 digest 与固定路由设备证据仍是发布 Gate）
- 日期：2026-07-30
- 关联 RFC：QL-RFC-0001 D-05、D-06、D-85、D-121、D-175、D-207、D-218
- 关联 ADR：ADR-0012、ADR-0057–ADR-0061、ADR-0110–ADR-0124、ADR-0185、ADR-0217、ADR-0231–ADR-0233、ADR-0235、ADR-0236

## 背景

ADR-0121/0122 已经提供单 journal owner、单 HTTPS Agent、单 cadence、Worker
Session、capacity oracle 和 execution plane，但仍只有可调用的 application
composition。部署者没有一个受审进程入口，也无法判断路由设备和 Kubernetes 节点应如何
保存 journal、装配 mTLS identity 或完成 drain。

把 Worker 当作普通无状态 Deployment 会产生更严重的问题：多个副本共享 Worker ID、
credential 和 PVC 时会竞争同一 Session 与执行事实；使用 `emptyDir` 会在重启后删除
spawn/completion 的唯一判定依据；直接读取 Kubernetes projected Secret 又会违反凭据
provider 对 direct file、`0700` parent、`0600` private material 和 `O_NOFOLLOW` 的约束。

## 决策

### 1. 一个进程只拥有一个 Worker 身份

`@qinglong/worker-runtime` 增加 package 内的显式 process subpath 和
`ql3-worker` binary，不新增 workspace package。进程只接受
`QL_DEPLOYMENT_PROFILE=worker` 与显式 `QL3_WORKER_RUNTIME_ENABLED=true`。
禁用态必须在读取 capability、storage path、certificate、private key 或 token 前返回。

启用态固定绑定一个 Worker ID、一个 canonical capability 文件、一个 control HTTPS
origin、一个 certificate store、一个 `ql3w` token 文件和一组 journal/log/receipt
目录。edge/node 只是同一进程的有界容量策略，不是两套 runtime：

- edge 默认 1 个并发 Run、2 秒 cadence、每页 4 条、journal 上限 64；
- node 默认 8 个并发 Run、500 ms cadence、执行页 16、supervision 页 32、
  journal 上限 256；
- 两者 Session lease 默认 45 秒、heartbeat 10 秒，并强制至少容纳两个
  heartbeat interval。

### 2. 凭据引导与 steady-state 必须分离

首次启动可从 direct bootstrap key/certificate 和 trust anchor 验证完整 leaf identity，
再原子安装到持久 certificate store，最多保留两代。相同证书的重启不得重复创建
generation。steady-state 每个请求重新读取 active generation、trust anchor 与 token，
因此 token/certificate replacement 不需要 watcher、cache、第二个 Agent 或常驻续期
进程。

private key、certificate、anchor 和 token Buffer 在验证/请求结束后必须清零。token
parent 必须为 `0700` direct directory，private files 必须为 `0600` 或更窄；symlink、
group/world permission、超限材料、credential ID drift 或无 active identity 均失败关闭。

### 3. 信号和 drain authority 先于 activation

进程必须在配置加载和 application start 前取得 SIGINT/SIGTERM ownership，避免
activation 窗口漏掉终止请求。启动只装配 ADR-0122 的一个 product application；不得再建
Session timer、Agent 或 execution owner。

收到信号后，进程反复调用同一 proof-bearing stop。只有结果为 `stopped` 才返回成功；
`drain_timed_out`、`recovery_required` 或 stop exception 必须保持现有 owner/Agent，
使用 ref'ed wait 后重试。进程事件只允许输出 Worker ID、capacity profile、生命周期
状态和枚举 diagnostic，不输出 origin、path、certificate、token、Secret、command 或
错误正文。

### 4. Worker 镜像是独立制品，不扩大 package 拓扑

Worker 镜像只构建和复制：

1. `@qinglong/runtime-core`；
2. `@qinglong/local-process`；
3. `@qinglong/worker-runtime`。

builder/runtime 使用从 workspace `pnpm-lock.yaml` 机械生成并校验的独立 npm v3 lock。
runtime 为 24 个外部 package，不包含 Cluster PostgreSQL/admin/control、Local
SQLite/application、AI、2.x server 或 UI。受审 POSIX launcher 必须显式复制并设为
`0555`，不能依赖源仓库文件 mode 或碰巧存在的 shell path。镜像固定 Node 24.18、
non-root UID/GID 65532 和绝对 entrypoint，不开放端口。

### 5. Kubernetes 使用单副本、单 PVC、私有 authority materialization

base Deployment 固定 `replicas=1`、`strategy=Recreate`、360 秒 termination grace、
read-only root、drop ALL、RuntimeDefault seccomp、无 ServiceAccount token和零入站
Service/port。journal/log/receipt/certificate store 必须进入同一 `ReadWriteOnce` PVC；
不得改为 `emptyDir`。

Secret/ConfigMap atomic-writer projection只作为 init 输入。init container 以相同 Worker
镜像在 fsGroup-writable 4 MiB tmpfs 中创建 UID 65532 自有的 `0700 private/` 子目录，
再把 CA、key、certificate、token 和 capability 复制为 direct files，同时创建 `0700`
state directories，最后把 authority tmpfs 只读挂给主进程。init 不尝试修改 root-owned
mount point。Secret rotation
必须更新 private overlay 的 digest 并执行 Recreate rollout；不得增加 watcher/sidecar。

一个 Deployment 不得 scale。横向扩容必须创建新的 Worker ID、certificate、token、
Session 和 PVC。Worker 没有面向流量的 Service，因此不伪造 readiness/liveness probe：
PID 存活不能证明 startup recovery 完成，自动 liveness kill 反而可能摧毁唯一 drain
owner。产品 readiness 是 Cluster 中的 durable Worker Session。

### 6. 路由设备直接运行 edge profile

非 Kubernetes 路由器/NAS 运行同一个 binary 和相同 direct-file/PVC 等价目录，不安装
Cluster 或 UI 闭包。当前 macOS arm64/Node 24.18 的真实进程+mTLS证据为：

- edge active RSS `67,616,768` bytes、peak `71,090,176` bytes；
- node active RSS `67,911,680` bytes、peak `71,286,784` bytes；
- 两档都只使用一个 TLS 1.3 mTLS socket并完成
  `register → draining → offline`。

因此 64 MiB 不能作为可信 Worker memory limit；在 Linux cgroup/固定设备证据取得前，
edge 部署至少按 96 MiB 运行预算规划。该数字是开发机上限 Gate，不是固定路由器发布
证明，也不代表执行用户脚本后的峰值。

## 被否决的替代方案

1. **多副本共享 Worker ID/PVC**：两个 owner 会竞争 Session、journal 和进程恢复。
2. **每个 Pod 动态生成 Worker ID**：Pod 重建会丢失稳定执行与凭据 authority。
3. **用 `emptyDir` 保存 journal**：重启会把未知 spawn outcome 错报为从未执行。
4. **主进程直接读取 projected Secret**：atomic-writer symlink/permission 与 direct
   private-file contract 冲突。
5. **sidecar 同步 Secret**：增加 watcher、进程、写竞态和 shutdown owner。
6. **使用 HTTP/PID 健康探针**：无法证明 Session/recovery readiness，并可能强杀 drain。
7. **为 process/config/deployment 新拆 package**：没有新的发布或 authority 边界，违反
   workspace package hard cap。
8. **把 Cluster Worker 与 control 放进同一镜像**：把 PostgreSQL/S3/control authority
   和供应链成本推给低配 Worker。

## 验收证据与剩余 Gate

已完成：

1. Worker process config/application/identity 定向测试通过，Worker 完整 133/133；新增真实
   子进程回归证明 active 后在 SIGTERM 前持续驻留，收到信号后正常 stop 并退出。
2. 真实 TLS 1.3 mTLS 进程资源基准覆盖 edge/node、file identity bootstrap、单 socket、
   register/drain/offline 和低敏事件。
3. Worker deployment audit 证明 3 个 workspace package、24 个 runtime external、
   单副本、PVC、private materialization、零 token、零端口、零伪 probe；同一 pinned
   Node 基础镜像的 non-root Docker tmpfs smoke 证明 UID/GID 65532 能在
   `root:65532/0770` mount 内创建并收窄自身 `65532:65532/0700 private/`。
4. edge/node Kustomize 均可合成，capacity profile与资源 patch 精确分离。
5. PostgreSQL 18.4 arm64 physical HA 再次通过 `remote_apply`、timeline 1→2、旧主
   fencing、`pg_rewind` 只读 sync rejoin、two fresh controls 和总
   `gates.passed=true`。
6. workspace 仍为 20 个 QL3 package；本切片不新增 production dependency、database、
   migration、timer、watcher、listener、sidecar 或 Pool。
7. ADR-0235 的 PostgreSQL 18.4 真实 production 纵切面已完成默认 Worker process →
   TLS 1.3 mTLS ingress → Session/Offer pull → credential A observed → 原子替换 B →
   B observed → A revoke → draining/offline；Session ID/generation 保持不变，角色边界
   与 PostgreSQL 明文排除成立。门禁同时发现并修复 Session transition bind parameter
   在 PostgreSQL 18 下的 `varchar` 类型歧义。
8. ADR-0236 已完成真实 Linux Run 的 Offer→starting→running→69 次 lease-control→
   31-byte artifact→completion，Run/Attempt succeeded、Lease completed；运行中凭据
   A→B 保持同一 Session，最终 offline。压力门同时修复 running ACK 参数类型和成功
   Worker 流量耗尽 authentication shield、以 429 饿死 heartbeat/completion 的问题。
9. ADR-0360 已在真实 K3s 中从当前源码构建并运行 production Worker 与 Cluster Worker
   ingress。它发现并修复 pending Promise 不保持 Node event loop、active Worker exit 0
   导致 CrashLoopBackOff 的 PID 1 缺陷；3 个 Pod/Session generation 均完成 online、
   heartbeat、draining、offline，credential 与 mTLS identity Recreate 共用同一 RWO PVC。

发布前仍必须完成：

1. Linux x64/arm64 image build、inventory/SBOM、non-root/read-only/cgroup resource gate
   与 immutable image digest；当前 `--network=none` 构建因本机 Docker cache 缺少 npm
   tarball而失败，不能声称镜像已生成。
2. 固定 96–128 MiB 路由设备的 idle、任务峰值、闪存写放大、断网、休眠、时钟跳变、
   断电和恢复证据。
3. Worker production certificate rotation 已由 ADR-0238 的 PostgreSQL/Linux 纵切面完成；
   ADR-0239/0360 已完成真实 K3s credential/identity generation、production image、
   Recreate 顺序、Session heartbeat/drain/offline 与单节点 PVC 恢复，但仍缺 CA overlap
   分区/回滚和对象存储故障/重试；Run 的
   Offer→starting→running→Artifact/completion/lease-control 已由 ADR-0236 完成，
   idle Session/Offer pull、credential revoke/replace 和 drain/offline 已由
   ADR-0235 完成。
4. 多节点 CSI PVC detach/reattach、物理节点丢失和 production 360 秒长 drain 的 live
   证据；ADR-0239 的单节点 local-path/强制删 Pod 不能替代这些 Gate，基础设施不得在
   360 秒后把未收敛副作用解释为安全停止。