qinglong/docs/adr/ADR-0024-local-context-secret-and-artifact-boundary.md

# ADR-0024：Local Context、Secret 与 Artifact 边界

- 状态：Proposed
- 日期：2026-07-18
- 关联：QL-RFC-0001、ADR-0003、ADR-0007、ADR-0022、ADR-0023

## 上下文

不可变 Task revision 只能保存执行模板和 opaque `contextRef`。真正启动 Attempt 时还需要环境、Secret、stdout/stderr Artifact 和 completion capability。这些数据生命周期不同：public 环境和 Secret 引用可以随 revision 保留，Secret 明文只能短暂存在于可信内存，Artifact 必须与 Attempt 绑定并在控制面重启后仍可定位。

QingLong 同时运行在小型路由设备和 cluster 节点。edge 不能为每个任务常驻队列、sidecar、Collector 或对象存储，但也不能继续把日志路径、Secret 和当前 Crontab 状态临时拼接后直接 spawn。cluster 则不能复用本机文件和 SQLite 作为共享能力。

## 决策

### 1. Context recipe 只保存 public 值和 Secret 引用

`LocalExecutionContextRecipe` 是按环境变量名排序的 canonical bindings：

- `public` binding 保存明确可持久化的普通字符串；
- `secret` binding 只保存 bounded `secretRef`，不保存解析值；
- 环境名唯一，最多 256 项，并继续受 ExecutionContext 的单值 64 KiB、总计 256 KiB 边界约束；
- `contextRef` 是 `localctx:sha256:<digest>` 内容地址，digest 只覆盖 canonical bindings。

`0013-local-execution-context-recipes` 以 `context_ref` 为主键，保存 canonical recipe、独立 digest 和首次创建时间。Repository 是 append-only：同内容重放幂等，不提供 update/delete；非法 JSON、非 canonical 顺序、非内容地址或 digest 损坏均 fail closed。

recipe 不包含 Secret 明文、Run/Attempt identity、callback token、Worker lease、PID/handle 或日志路径。

### 2. 发布顺序阻止可执行的悬空引用

本地发布器固定先插入 context recipe，再插入引用它的 Task execution revision，并要求两个 `contextRef` 完全相同：

- recipe 写入失败时绝不创建 revision；
- 两次 append-only 写之间断电最多留下不可执行的孤儿 recipe；
- 不会留下已经可调度但 recipe 不存在的 revision；
- 并发重放由两个 repository 各自收敛为 inserted/idempotent。

当前没有通用删除接口。未来清理孤儿 recipe 或 revision 前，必须建立引用证明、保留窗口和备份门禁。

### 3. Secret provider 只在 Attempt 物化时批量解析

materializer 先精确读取 `contextRef`，再把去重后的 Secret refs 与冻结 candidate 交给可信 provider。provider 返回与 refs 位置一一对应的内存值：

- recipe 或任一 Secret unavailable 时返回 plan unavailable；
- 缺失或非法结果在 Artifact 分配和 Executor 副作用前拒绝；
- 明文不写回 recipe、revision、RunEvent、普通日志或异常消息；
- 解析后的环境立即通过共享大小/NUL/prototype 边界规范化并冻结。

ADR-0025 已进一步提供 production-unreachable 的 AES-256-GCM envelope、append-only SQLite repository、私有文件 keyring 和批量 environment provider，并且没有把 Legacy `Envs` 表直接宣称为 3.0 SecretStore。权限/审计/API、自动 key 生成与备份、历史 rekey/退役证明和 cluster Secret provider 仍需独立实现。

### 4. 每个 Attempt 获得一个 opaque 本地 Artifact

本地文件 allocator 从 `(runId, attemptId)` 派生 36 字符 opaque Artifact ID，不在 ID 或日志路径暴露 Task 名、命令或 Secret。文件位于受控 root 的固定 shard，目录强制 `0700`、文件强制 `0600`，append 打开使用 `O_NOFOLLOW`，symlink target fail closed。

同一 Attempt 重放得到相同 ID 并追加同一文件，不同 Attempt 必须得到不同 ID。普通 pipe 模式下 output sink 串行已接受写入；durable LocalProcess 模式通过非枚举 adapter capability 把绝对文件路径和 receipt root 交给 launcher，常规 context 序列化看不到路径。

Artifact ID 由 local Dispatcher 随 claimed activation 传入，并在 spawn 前的 `attempt.starting` 事务中持久化。非法/path-like ID 在 Run 状态变化前拒绝；已有 claimed Attempt 若夹带 Artifact identity 被视为 stale authority。这样 Reconciler、日志 API 和 retention 不必从文件名或进程推测所有权。

### 5. 清理只释放 capability，不提前删除历史日志

plan 校验、激活竞争或启动失败时会等待可选异步 dispose；成功激活后在 completion settle 后释放。dispose 关闭当前进程持有的文件 descriptor，并等待已经接受的写入，不删除 Artifact 内容。

删除策略必须独立依据 terminal Attempt、receipt 清理、保留期、容量水位和 revision fencing。ADR-0026 已提供 production-unreachable 的单 Attempt hard quota、statfs admission reserve、压力 retention、SQLite tombstone 和安全文件 retirement；生产启用前仍必须完成 lifecycle/cursor、容量告警、durable truncation fact 与真实 edge ENOSPC/inode/断电测试。

### 6. edge 与 cluster 共享语义，不共享存储实现

- edge/standalone：SQLite immutable recipe + 本地 Secret provider + 私有文件 Artifact；
- cluster-control：PostgreSQL recipe/revision metadata + 集中 Secret provider + 对象 Artifact；
- worker：只接收已授权的 Attempt-scoped capability，不读取控制面的 SQLite 或 Secret 表。

cluster adapter 必须复用 canonical digest vectors、exact resolve、batch Secret、Attempt Artifact identity 和 fail-closed 规则。共享挂载 `database.sqlite` 或本机 Artifact root 不是 cluster 实现。

## 影响

正面影响：

- 自动重试能重建同一 public/Secret 引用意图，同时为 Attempt N+1 分配新 Artifact；
- Secret 明文与静态 revision、recipe、日志 metadata 分离；
- edge 每个 revision/recipe 各一次单行写，每个 Attempt 只持有有界数量的文件 descriptor；
- Artifact ownership 在 spawn 前持久化，重启恢复不依赖内存映射。

代价与风险：

- 需要把 ADR-0025 的本地 SecretStore 补齐权限、审计、key lifecycle 和轮换产品入口后才能生产接入；
- 本地日志仍需要把 ADR-0026 adapters 接入受控 lifecycle，并完成 ENOSPC/告警/截断事实的运维闭环；
- 两步发布可能留下孤儿 recipe，必须用引用感知维护任务清理，不能盲删；
- context 环境仍驻留进程内存，诊断和 heap dump 策略必须避免泄漏。

## 未选择的方案

1. **把 Secret 明文写入 recipe/revision**：静态泄漏与备份扩散，拒绝。
2. **启动时读取当前全局 Envs 并全部继承**：不可复现且权限过宽，拒绝。
3. **先写 revision、后写 recipe**：断电会留下可调度悬空引用，拒绝。
4. **日志文件名使用 Task 名或命令**：泄漏且存在路径边界风险，拒绝。
5. **Artifact ID 只存在内存**：重启后无法证明日志属于哪个 Attempt，拒绝。
6. **plan dispose 删除日志**：激活竞争与 completion 时机无法证明 retention，拒绝。
7. **cluster 复用本地文件/SQLite adapter**：多副本一致性和权限模型错误，拒绝。

## 验证要求

- recipe canonical 顺序、内容地址和 digest 有固定 vectors；
- recipe 并发同内容写入恰好一次 inserted，其余 idempotent；
- 非 canonical、任意 ref、非法 JSON 和 digest 损坏 fail closed；
- recipe 失败时 revision repository 不被调用；
- Secret refs 去重批量解析，missing/错位/越界值在 Artifact 前拒绝；
- 本地 Secret current/exact 版本、CAS/mutation 幂等、密文损坏和跨 Project fail-closed 通过 ADR-0025 contract；
- Artifact ID 对同 Attempt 稳定、跨 Attempt 不同且长度有界；
- 目录/文件权限、symlink、late write、异步 dispose 和 replay append 有真实文件测试；
- Artifact ID 在 spawn 前持久化，invalid ID 不改变 queued Run；
- manual Primary 未传 Artifact ID 时行为不变；
- SQLite adapters 拒绝 cluster dialect，生产启动链保持不可达；
- Node 22、Node 24 全量回归通过。