qinglong/docs/adr/ADR-0026-local-artifact-quota-and-retention.md

ADR-0026：本地 Artifact 硬配额、磁盘水位与可恢复 Retention

• 状态：Proposed
• 日期：2026-07-18
• 关联：QL-RFC-0001、ADR-0007、ADR-0021、ADR-0024、ADR-0025

2026-08-12：Local Run Attempt 日志 retention、durable tombstone、压力档位与 lifecycle 接线已由 ADR-0378 接受；本 ADR 仍保持 Proposed，仅表示其余通用 Artifact quota/跨 Profile 扩展尚未整体关闭。

上下文

ADR-0024 已建立 Attempt-scoped opaque Artifact 和 direct-file durable output，但未限制单次运行能够写入的字节数，也没有终态清理证据。对小型路由设备，这意味着一个失控脚本可以填满系统盘；只按 timer 删除目录又可能误删仍在运行、等待 completion receipt 或无法证明进程退出的日志。standalone/cluster 虽然容量更高，同样需要可审计的配额和生命周期语义。

durable LocalProcess 不能只依赖 Node ExecutionOutputSink：stdout/stderr 使用继承的文件描述符，控制面崩溃后 launcher 和用户进程仍继续写。Linux/POSIX 没有通用的 per-file-descriptor byte quota；RLIMIT_FSIZE 会错误影响任务自己打开的其他文件，并可能用 SIGXFSZ 改变业务退出结果。

决策

1. 每个 Attempt 必须显式声明容量策略

LocalArtifactCapacityPolicy 包含：

• maximumAttemptBytes：单 Attempt 日志硬上限，允许范围 64 KiB～1 GiB；
• minimumFreeBytes：不得被新 Attempt 消耗的磁盘保留水位。

默认 profile 建议为：

Profile	单 Attempt 上限	最小空闲保留
edge	4 MiB	32 MiB
standalone	64 MiB	256 MiB

3.0 本地 allocator 不再提供隐式无限配置。创建 Artifact 前先读取文件系统 bavail × bsize；只有 available bytes 至少覆盖 minimumFreeBytes + maximumAttemptBytes 才允许打开文件。检查发生在 Artifact 文件副作用前，失败返回稳定 capacity unavailable。它是 admission reserve，不是对同文件系统其他进程的空间租约，所以运行中写入仍必须处理 ENOSPC。

2. 普通 pipe 与 durable direct-file 共用同一硬上限

普通 pipe sink 串行维护剩余额度，越界 chunk 只写入尚可接受的前缀，绝不多写一个字节，然后返回 quota exceeded；Executor 继续排空 child stream 并产生 bounded output-sink diagnostic。

durable 模式把 maximumBytes 作为非枚举 adapter capability 交给 launcher。Node 仍以 O_APPEND|O_NOFOLLOW 安全打开日志并传递 FD；launcher 在同一私有 shard 创建确定性的 0600 FIFO，启动一个有界 drainer：

1. head -c remaining 只把剩余额度写到继承的安全 FD；
2. 同一 reader 用 wc -c 排空剩余字节，只根据计数判断是否真正达到 quota，不保存用户内容；
3. stream 关闭后始终发布固定格式、不可覆盖的 truncation fact，记录 Run/Attempt/Artifact、实际 quota、quotaReached=true|false 和 observation time；fact 缺失只能解释为 unknown，禁止推断为未截断；
4. 用户进程不会因 reader 退出收到 SIGPIPE，退出码和 completion receipt 语义不因日志截断改变；
5. launcher 等待 child 与 drainer，再删除 FIFO。控制面进程提前退出不会中断 launcher、drainer 或用户进程。

fact 不包含 callback token、命令、环境、Secret 或用户输出，也不能授权 completion、retention 或调度状态变化。launcher 通过同目录临时文件和 hard-link/no-replace 发布；本地 reader 只读取 canonical 私有 shard 中的普通非 symlink 文件。事实文件可以被日志 API 解释为 true|false|unknown，但不能作为进程退出证明。

这增加至多一个轻量 POSIX drainer，不增加每任务 Node sidecar、watcher 或 timer。Alpine 镜像已有 coreutils；Debian 必须在镜像契约中持续验证 head -c、wc -c 与 mkfifo。遗留 manual Primary 未提供 maximumBytes + logArtifactId 时保持旧 direct-file 路径，不被本切片静默切换。

3. Retention 只相信数据库终态和 receipt settlement

SQLite candidate source 只返回同时满足以下条件的记录：

• Run execution_owner=runtime，Run 与 Attempt 均为 succeeded|failed|cancelled|timed_out；
• Executor 为 local_process，log_artifact_id 是 canonical local-*；
• Attempt finished_at_ms 已超过当前 retention cutoff；
• 不存在 CompletionReceiptJournal，说明 completion receipt 已消费/隔离处理完成；
• 不存在该 Attempt 的 retention tombstone。

lost 明确排除：lost 只表示控制面无法证明 ownership，不证明底层进程已经退出。没有 durable execution settlement 证据时删除 lost Artifact 可能 unlink 一个仍被孤儿进程写入的 inode。以后若引入 execution_settled 事实，应通过独立 ADR 扩展，而不能从 error code 猜测。

候选按 (finished_at_ms, attempt_id) keyset 排序，默认 16、最多 64；每次 sweep 默认最多删除 8、最多 64。单页 service 无全目录扫描、递归分页、timer 或每 Task 状态；cadence 由后述显式 lifecycle 管理。

4. 低水位只能缩短到显式 pressure retention

Retention service 每个 sweep 只采样一次 clock 和 capacity：

• 空闲空间不低于水位时使用 normalRetentionMs；
• 低于水位时使用显式配置的 pressureRetentionMs，且必须在 1 分钟到 normal retention 之间；
• 即使磁盘承压，也只删除满足 terminal/receipt 条件的 Artifact，不删除 active、lost 或未知文件。

压力模式不是“扫目录删最老文件”。持续低水位必须产出指标/告警，并允许调度 admission 暂停低优先级任务或拒绝新任务。

5. Lifecycle 只运行单页并持久化 CAS cursor

0016-local-artifact-maintenance-cursor 增加单行 LocalArtifactMaintenanceCursors checkpoint，保存 (finished_at_ms,attempt_id)、version 和更新时间。lifecycle 每次 tick 只读取一个 checkpoint、执行一个 sweep page，再按 expected version CAS 推进或清空：

• page_complete|deletion_budget_exhausted 必须持久化 resume cursor；到达尾部后清空 cursor，下个 tick 从头重试此前失败候选；
• 当前 cursor 和目标 cursor 都为空时不写数据库，避免空闲路由器周期性改写 SQLite/WAL；
• CAS 失权只输出 fenced 摘要，不假装持有 cadence ownership；文件删除和 tombstone 本身仍按幂等协议收敛；
• 一个 unref timer、无重叠 cycle、显式 start/stop、stop wait 有上限；observer 只收到无 Attempt/Artifact ID 的聚合值，statfs bigint 转成十进制字符串以便 JSON exporter 安全处理。

默认资源建议为：

Profile	cadence	page	每周期最多删除	normal retention	pressure retention
edge	5 分钟	8	4	7 天	1 天
standalone	1 分钟	32	16	30 天	7 天

这些是代码级安全默认值，不替代 Project policy；当前 lifecycle 仍未接入生产 startup。

6. 删除后写 tombstone，崩溃可收敛

0015-local-artifact-retention 增加 LocalArtifactRetentions，每 Attempt 一条不可覆盖记录，保存 Artifact ID、finished/eligible/recorded time、deleted|already_absent 和 reclaimed bytes；同时为 RunAttempt terminal candidate 增加 (status, finished_at_ms, id) 索引。

操作顺序固定为：

1. 验证 root/shard 都是非 symlink 私有目录；日志与 truncation fact/temp 必须是有界普通文件，遗留 quota 辅助项必须是 FIFO；
2. 先删除日志，成功或已缺失后再删除 FIFO 与 truncation fact/temp，最后 fsync shard directory；日志删除失败时必须保留解释它的 truncation fact；
3. 写入 tombstone。

不能先写 tombstone：断电后数据库可能永久声称已清理，但文件仍存在。若在 unlink 后、tombstone 前崩溃，下一 sweep 将文件识别为 already absent 并补写 tombstone。并发清理时第一条同 Attempt/Artifact/finished identity 的证据获胜；身份不同稳定冲突。

Retention 不清空 RunAttempt.logArtifactId。历史 Run 仍保留 opaque ownership 和“已过期”解释能力，日志读取端可通过 tombstone 区分从未产生、暂时缺失和已执行 retention。

7. cluster 共享语义，不共享本地文件实现

• edge/standalone：SQLite candidate/tombstone + 私有本地文件 + statfs capacity；
• cluster-control：PostgreSQL metadata/fencing + object-store lifecycle/delete marker + Project policy；
• worker：本地 spool quota 与上传 ACK 必须先于删除，不能把控制面 tombstone 当作 Worker 本地清理证明。

对象存储 adapter 必须复用 terminal settlement、pressure policy、bounded page、delete-before-marker 和 immutable identity contract；共享挂载本地 Artifact root 不是 cluster 实现。

8. 当前保持 production unreachable

quota-aware 3.0 allocator、durable FIFO drainer、正/负 truncation fact、capacity probe、0015/0016 migration、SQLite candidate/tombstone/CAS checkpoint、文件 retirement、单页 service、profile policy 和显式 lifecycle 已实现，但没有接入默认 Dispatcher/Primary startup。生产启用前仍需：

• 配置/API 中的 Project/Profile policy 与变更审计；
• lifecycle startup/shutdown 装配、指标 exporter、持续低水位告警和 admission 联动；
• 真实 Alpine/Debian 多架构验证 head/wc/FIFO/信号/父进程退出；
• loopback/tmpfs 上的 ENOSPC、inode 耗尽、断电/fsync 和并发外部写入测试；
• 日志读取 API 对 tombstone、quotaReached=true|false|unknown 和权限的稳定响应；
• PostgreSQL/object store/Worker spool contract suite。

因此 migration 和 adapters 存在不代表 retention timer 已启动，也不改变现有 2.x/manual Primary 的日志策略。

影响

正面影响：

• 单 Attempt 无法把本地日志写过明确上限，durable 模式在控制面崩溃后仍受限；
• edge 在创建任务前保留系统盘安全余量，并能在低水位使用更短但显式的保留期；
• retention 不扫描未知目录，不误删 active/lost/未结算 receipt，并能从 unlink→DB 崩溃窗口恢复；
• 历史 Run 保留 opaque Artifact identity 和不可变清理证据。

代价与风险：

• durable quota 依赖 POSIX FIFO、head -c 和 mkfifo，必须持续进入镜像 contract；
• quota 后继续排空会消耗少量 CPU/pipe I/O，但避免改变用户任务退出结果；
• statfs admission 不是空间预留锁，其他进程仍可能导致 ENOSPC；
• tombstone 与 RunAttempt 同生命周期增长，未来删除 Run 时由外键级联，不能独立无限保留；
• lost Artifact 暂不自动清理，可能需要人工审计或后续 settlement 协议。

未选择的方案

1. 只限制 Node sink：控制面崩溃后的 durable FD 绕过，拒绝。
2. 使用 RLIMIT_FSIZE：影响任务自己的其他文件并可能改变退出结果，拒绝。
3. quota 达到后关闭 FIFO reader：向用户进程制造 SIGPIPE，拒绝。
4. 递归扫描日志目录并按 mtime 删除：没有 Run/Attempt/receipt ownership，拒绝。
5. 把 lost 当作可清理终态：无法证明孤儿进程退出，拒绝。
6. 先写 tombstone 再 unlink：断电可能形成永久泄漏，拒绝。
7. 低水位时删除 active 或无最短保留：破坏恢复和用户契约，拒绝。
8. cluster 共享本机目录/SQLite：无多副本 fencing 和对象生命周期，拒绝。

验证要求

• 普通 sink 和 durable launcher 对 oversized/replay 输出都精确停在最大字节；
• quota 后 child 继续完成、退出码/receipt 不变，capability 环境不进入 child；
• 未超额发布 quotaReached=false、超额发布 true、fact 缺失保持 unknown，不得从文件大小推断；
• capacity reserve 在创建日志文件前拒绝，非法 policy/snapshot fail closed；
• candidate 排除 active、legacy、non-local、pending receipt、tombstoned 和 lost；
• normal/pressure retention、stable cursor、page/delete budget 可重复验证；
• lifecycle 单 timer、无重叠、有界 stop、CAS fencing、idle 零 checkpoint 写和低敏 JSON-safe summary 可重复验证；
• symlink/非普通文件/非 FIFO 辅助项 fail closed，不影响外部目标；
• unlink 后 tombstone 失败可在下一 sweep 收敛为 already absent；
• migration、ownership、Node 22/24 全量测试通过；
• 真实 edge 文件系统补充 ENOSPC、inode、断电和写放大报告后才允许生产装配。