# ADR-0216：实例 Owner 围栏化、有界的 Local Security Audit 诊断压缩

- 状态：Accepted
- 日期：2026-07-29
- 关联 RFC：QL-RFC-0001 D-05、D-27、D-37、D-65、D-72、D-73、D-175、
  D-198、D-201、D-205、D-206
- 关联 ADR：ADR-0049、ADR-0074、ADR-0211、ADR-0215

## 背景

ADR-0215 完成了有界、脱敏的本机安全审计查询，但 Edge/Standalone 的
`QingLong3SecurityAuditEvents` 仍只增不减。低容量路由设备不能依赖人工直接 SQL，
也不能承担常驻 retention daemon、定时器或无界扫描。

安全审计又不是可以按时间一刀切的日志。大量 mutation、dispatch、execution、
credential 与 package receipt 通过外键或语义 identity 引用 audit event。删除这些
行会破坏 exact replay、恢复、取证或启动围栏。当前 schema 还没有覆盖全部语义引用的
统一外键，因此 v1 不能声称提供通用审计保留期。

## 决策

### 1. 复用既有 package、binary 和 authority

在既有 package 内新增：

- `@qinglong/runtime-core/local-security-audit-retention`；
- `@qinglong/local-sqlite/security-audit-retention`；
- `@qinglong/local-admin/security-audit-retention`；
- 既有 `ql3-audit` 的 `security.audit.compact` operation。

不新增 workspace package、binary、生产依赖、daemon、timer、watcher、listener、
连接池、缓存或端口。命令一次启动、执行一个有界 batch 后退出。

### 2. v1 只压缩可证明安全的诊断事件

候选行必须早于显式 `eligibleBeforeMs`，并满足以下二者之一：

1. outcome 不是 `allowed`；
2. outcome 为 `allowed`，且 operation 在精确只读白名单：
   `identity.inspect`、`credential.inspect`、`policy.project.inspect`、
   `policy.project.list`、`policy.role_binding.inspect`、
   `policy.role_binding.list`、`security.audit.list`。

同时，候选行不得被任何已知外键或语义 ledger 引用。实现显式排除：

- Credential administration/delivery；
- Identity administration/provisioning；
- legacy adoption；
- Owner bootstrap/recovery/acknowledgement GC/pepper GC；
- Plugin Package admission；
- Project administration；
- Tool execution audit/start barrier；
- security audit compaction receipt。

允许的 mutation、dispatch、execution 和 package operation 即使超过期限也保留。
这是“诊断审计压缩”，不是通用审计销毁或合规 retention。

### 3. 保留期、batch 和资源硬上限

- retention 只能为 30 天至 10 年；
- `eligibleBeforeMs + retentionMs` 不得晚于受信时钟；
- Edge 每 batch 最多 64 条；
- Standalone 每 batch 最多 512 条；
- 删除摘要的规范 payload 最多 16 MiB；
- 排序固定为 `(occurredAtMs ASC,eventId ASC)`；
- 不支持 offset、任意 SQL、模糊条件或调用方排序。

需要继续收敛时，operator 使用新的 mutation/request/failure identity 重复执行，直到
`deletedCount` 为 0。不存在后台自动循环。

### 4. 删除、allowed audit 与不可变 receipt 原子提交

SQLite 在同一 `BEGIN IMMEDIATE` 内：

1. 重验 authenticated credential、Identity、pepper、instance authority anchor、
   authority Project 和 actor 最新 Owner binding；
2. 检查 exact replay；
3. 有界选择候选行；
4. 对规范化的完整候选记录计算 domain-separated SHA-256 与 payload bytes；
5. 写 `security.audit.compact` allowed audit；
6. 写不可变 compaction receipt；
7. 删除精确候选 event ID；
8. commit。

receipt 保存 mutation/request/authority、retention/cutoff/limit、删除数量/bytes、
首尾 cursor、records digest、audit event 与创建时间。receipt 外键引用本次 allowed
audit，因此压缩证据本身不可成为候选。

相同 mutation 只有在 request、authority、retention、cutoff、limit 和 audit 语义完全
一致时返回 `existing`；任意漂移均冲突。失败使用独立 `failureAuditEventId`，避免一次
拒绝占用未来可成功重放的 mutation identity。

### 5. SQLite contract 升至 v38

新增：

- `0075-security-audit-compactions`；
- `0076-capability-v38`；
- `QingLong3SecurityAuditCompactions`；
- capability `local_security_audit_compaction`。

镜像、预检、rollout 写契约和物理 Edge evidence 必须统一要求 v38。Edge 继续使用
rollback journal，Standalone 继续使用 bounded WAL。

### 6. 不自动执行 VACUUM

删除后的 SQLite page 可由后续写入复用，但文件大小可能不会立即下降。命令不执行
`VACUUM`、`auto_vacuum` 切换或长事务 rewrite。需要物理缩容时必须走独立、可备份、
可恢复、具备空间预检的离线维护 RFC。

## 不采用方案

### 按时间删除全部 audit

拒绝。当前存在未统一为外键的 mutation/event 语义引用，会破坏 exact replay、恢复和
安全取证。

### 只依赖数据库外键发现引用

拒绝。外键只能覆盖直接关系，Tool start barrier 和多个领域 ledger 还存在语义 identity
引用。v1 使用“诊断 operation 白名单 + 显式引用排除”的双重保守策略。

### 常驻 retention daemon 或启动时自动清理

拒绝。它增加低配设备空闲 RSS、启动路径失败面和不可预测 I/O，并在没有 operator
选择的情况下销毁证据。

### 每次压缩后 VACUUM

拒绝。VACUUM 的额外空间、持续时间和写放大不适合作为路由设备在线管理动作。

## 影响

正向影响：

- Edge/Standalone 可通过受支持产品入口回收可证明安全的诊断审计；
- 每次最多 64/512 条，内存、锁时长和终端输出有硬上限；
- authority、credential 与 Policy TOCTOU 在最终事务内再次收敛；
- digest、首尾 cursor 与 immutable receipt 为删除 batch 提供可重放证据；
- 低配设备没有新增常驻进程或空闲资源开销。

代价与限制：

- allowed mutation/execution/package 审计仍会增长；
- 删除后文件不保证立即变小；
- compaction receipt 和本次 allowed audit 会新增少量永久记录；
- 当前不提供签名 export、远端归档、合规销毁证明或 Cluster retention。

## 验证

- SQLite 临时真库迁移到 contract v38，67 张受审表，capability 绑定
  `0075-security-audit-compactions`；
- 隔离 strict TypeScript 通过；
- runtime digest 3/3；
- local-admin authority/retention/failure fence 4/4；
- 真实 SQLite 4/4，覆盖诊断白名单、允许 mutation 保留、外键引用保留、
  cutoff、receipt、digest、exact replay、drift、batch 推进和 foreign authority；
- Owner CLI 5/5，覆盖原查询回归、压缩低敏输出、Edge 65 拒绝和独立 failure identity；
- SQLite rollout 7/7；database 契约已同步 v38；
- workspace 仍为 22 package，本能力未增加 package；
- 完整 package closure 与 PostgreSQL HA Docker 门仍受未物化锁定依赖阻断。