qinglong/docs/adr/ADR-0378-local-run-attempt-log-retention-and-tombstones.md

ADR-0378：Local Run Attempt 日志有界保留与 durable tombstone

• 状态：Accepted
• 日期：2026-08-12
• 关联 RFC：QL-RFC-0001 D-290
• 前置决策：ADR-0026、ADR-0027、ADR-0377

上下文

ADR-0377 已让 Local/Cluster 能在 Project、Run、Attempt、executor 与 Artifact identity 全部可信后读取日志，但故意没有把缺失文件解释成 retention。若没有 durable tombstone，文件被清理、文件损坏、错误路径和未发布 Artifact 对读取方都是同一个 missing；若只在删除前写标记，又会把仍存在的数据错误暴露为已清理。

Local Profile 还必须覆盖两类差异很大的设备：128 MiB/64 PID 级路由设备不能承担目录全扫、每任务定时器或无界删除；Standalone 可以提高吞吐，但仍应复用单连接和既有 lifecycle。Cluster 的 PostgreSQL 多副本 claim、S3 条件删除和外部网络失败语义与本机 unlink 不同，不能为了表面复用而塞进同一个事务或 adapter。

决策

1. 共享不可变证据，不共享删除实现

runtime-core 在既有 Run 能力内增加 qinglong/run-attempt-log-retirement@v1，不创建新 package。每条记录精确绑定：

• projectId、runId、attemptId、logArtifactId；
• executorType、finishedAtMs、eligibleAtMs、retiredAtMs；
• deleted | already_absent；
• 删除前观测到的 byteLength 与 true | false | unknown truncation；
• 覆盖全部语义字段的 canonical SHA-256 recordDigest。

读取 repository 必须重新计算摘要并验证精确身份；持久化行被原地修改时失败关闭。already_absent 的 byteLength 固定为 0，不伪造回收字节。

2. 读取与删除竞态

读取仍先完成 HTTP authentication、Policy、durable audit、credential confirmation 和 Run/Attempt metadata 验证。获得 canonical Artifact identity 后：

1. 在访问文件/对象前检查 tombstone；
2. 已 retired 直接返回 410 artifact retired，不触碰存储；
3. active 时执行原有 Range read；
4. 存储返回 missing 后再次检查 tombstone；
5. 二次检查发现 retired 返回 410，否则保持 503 unavailable/pending 语义。

打开文件后发生 unlink 的并发读取可完成该已打开快照；这是以安全打开的 inode 为线性化点。删除完成但 tombstone 尚未提交的极短崩溃窗口由下次 already_absent sweep 收敛，不能预写“已删除”tombstone。

对外 retired 只包含 Project/Run/Attempt、retired time、原 byte length 与 truncation，不返回路径、Artifact ID、bucket 或 key。Policy deny、不存在和跨 Project 继续在此之前遮蔽为 404。

3. Local SQLite 44 号契约

追加 0087-run-attempt-log-retention 与 0088-capability-v44：

• QingLong3RunAttemptLogArtifactTombstones 保存不可变精确证据；
• QingLong3RunAttemptLogRetentionState 保存唯一 Local maintenance cursor；
• RunAttempts 增加局部候选索引；
• runtime readiness 仍只读取冻结 manifest，不加载可执行 DDL。

候选必须同时满足：

• Run executionOwner=runtime；
• Run 和 Attempt 都是 succeeded | failed | cancelled | timed_out，明确排除 lost；
• Attempt 为 local_process 且绑定 canonical local-* 日志；
• Run/Attempt 都有终态时间且早于当前 retention cutoff；
• 不存在任何 completion receipt journal；
• 不存在同 Attempt 或 Artifact 的 tombstone。

删除后写 tombstone 的事务会重新验证上述持久化事实。若 receipt 或状态在文件删除后改变，写入失败，后续 sweep 以 absent 重新收敛，不能绕过 completion 协议。

4. 私有文件删除顺序

Local store 只接受：

• 绝对且非文件系统根的 Artifact root；
• 当前 owner、模式 0700、非 symlink 的 root/shard；
• 当前 owner、模式 0600、普通文件、单 hard link、最大 1 GiB 的主日志；
• 唯一允许的 .<artifact>.log.truncated.json helper，且其 identity 与主记录完全一致。

顺序固定为：验证目录和 fact → 打开并验证主日志 inode → 删除主日志 → 删除允许的 fact → fsync shard directory → SQLite 写 tombstone。禁止递归删除、扫描任意目录、跟随 symlink 或清理未知 helper。若主日志已不存在但 exact fact 仍在，只删除该 fact、fsync 并记录 already_absent。

5. Edge 与 Standalone 资源档位

每次 sweep 先用 statfs 采样可用空间，根目录尚未创建时只检查最近存在父目录，不主动创建路径。

Profile	正常保留	压力保留	压力阈值	page	最大删除
Edge	7 天	24 小时	64 MiB	4	2
Standalone	30 天	24 小时	256 MiB	16	8

cursor 持久化到 SQLite；失败候选会被本轮越过，并在游标回绕后重试，避免一个坏文件永久阻塞队首。容量证据以十进制字符串进入 lifecycle summary，避免 JSON 对 BigInt 失败。

6. 不新增常驻资源

Artifact sweep 复用 LocalExecutionControlLifecycle 已有 completion cleanup cadence：先清 completion receipt，再做一次有界 Artifact sweep。它不新增 timer、listener、SQLite connection、watcher、cache 或 background thread；stop drain 不额外执行 Artifact 删除，避免扩大关停超时。

7. Cluster 留给 D-291

Cluster 路由和共享读取服务已经能注入 retention state 并映射 410，但 D-290 不授予 S3 DeleteObject 权限、不新增 PostgreSQL tombstone/claim，也不宣称 Cluster retention 已完成。D-291 必须独立解决：

• 多副本 durable claim、lease/backoff 与 bounded scheduler budget；
• validated HEAD 后基于 ETag/version 的条件删除；
• PostgreSQL 事务不得跨 S3 网络调用；
• delete 成功/对象已不存在后的 exact tombstone finalize；
• MinIO/S3 失败矩阵与 PostgreSQL HA failover。

被否决的替代方案

1. 删除前写 tombstone：可能把仍存在的数据声明为已删除，拒绝。
2. 把 missing 直接映射 410：无法区分损坏、误配和 retention，拒绝。
3. 递归扫描 Artifact root：I/O 无界且目录内容成为隐式 authority，拒绝。
4. 每个 Run/Attempt 启动 retention timer：常驻资源随任务数增长，拒绝。
5. Local/Cluster 共用一个删除事务 adapter：会把外部 S3 调用放入数据库事务并模糊多副本 ownership，拒绝。
6. 新建 retention 微包：现有 runtime-core、local-sqlite、local-execution ownership 已足够，拒绝。

验收

1. 共享 contract 覆盖 digest tamper、精确 identity、压力策略、删除预算和 durable cursor；
2. 读取覆盖 tombstone-before-storage 与 missing-after-storage 二次检查；
3. SQLite migration、typed schema、readiness、candidate、receipt fence、replay/tamper 全部通过；
4. 文件 adapter 覆盖权限、symlink/hard-link、fact drift、unlink-before-tombstone 与 statfs；
5. 完整 Local application 证明启动 sweep 删除真实文件、写 tombstone，并在产品读取前返回 retired；
6. Runtime Core、Local SQLite/Execution/API/Application/Admin/Owner CLI、Cluster Control 与完整 18-package/backend/boundary/Profile/Local image 门全部通过后才改为 Accepted。

2026-08-12 验收完成：Runtime Core 498/498、Local SQLite 220/220、Local Execution 39/39、Local API 45/45、Local Application 46 pass/4 skip、Local Admin 91/91、Local Owner CLI 157 pass/5 skip、Cluster Control 216 pass/2 skip；完整 18-package 门退出 0，backend 1,163 pass/2 skip/0 fail。package boundary 保持 18 个 workspace package，singleSourcePackages=[]、shallowSourcePackages=[]；dependency 与 Edge import 审计 均 compatible。14 个 Local Profile artifact 全部在文件数、体积与 RSS 预算内，最小 Edge 为 2,450,378 bytes， Edge Application 为 3,482,708 bytes，未引入 Cluster/PostgreSQL/AWS SDK 闭包。

真实 arm64 Local image 以 repo digest sha256:73a93094ebc53effbbe619e29ea866e59872211bf840db86509c011389ed10b8 完成 Edge/Standalone Compose preflight，均观测 SQLite contract v44；两档 rollout 的备份、恢复、响应丢失重放、证据收集与优雅清理 全部 compatible。PostgreSQL 18.4 arm64 HA 回归通过 112 gates、timeline 1→2，私有报告 SHA-256 为 6a205d8bc596097f91a900d7cdabef21c6ff3ad61152e8dfb31291cb8a356b12，独立审计 compatible=true/findings=[]。发布镜像、静态审计和 CI 的 SQLite compatibility label 已统一为 v44。