qinglong/docs/adr/ADR-0096-strong-bounded-legacy-adoption-decision-receipt.md

# ADR-0096：强认证且有界的 Legacy adoption 决策回执

- 状态：Accepted（纯回执契约、逐项流式验证、source/plan 复核、ADR-0097 私有 HMAC 载体及 ADR-0098 Policy/audit 同事务 publisher 已实现；产品 issuer ceremony 待完成）
- 日期：2026-07-22
- 关联 RFC：QL-RFC-0001 D-03、D-04、D-08、D-17、D-23、D-62、D-70、D-88、D-90、D-91、D-92、D-93、D-94、D-95、D-96
- 关联 ADR：ADR-0086、ADR-0087、ADR-0088、ADR-0091、ADR-0092、ADR-0093、ADR-0094、ADR-0095、ADR-0097

## 背景

ADR-0095 能把每个 Legacy Crontab 稳定分类并绑定到 plan v2，但分类不是处置。若未来 publisher 只检查 `mutationReady` 或接收一个全局“同意迁移”，它无法证明维护者是否看过 shell compatibility、unsupported、malformed 和显式排除项，也无法防止分页遗漏、重复、顺序错位或 source 更新后重放旧选择。

直接把最多 100,000 个 decision 放进 receipt 又会让路由设备承担无界 JSON/内存峰值，并让含有逐项信息的文件进入 activation 常驻路径。另一方面，仅有普通 SHA-256 不能证明调用方真的完成过认证；回执摘要只能证明内容未漂移，不能凭空创建 issuer authority。

## 决策

### 1. decision 与 classification 锁步，一行且只能一项

每个 decision 只包含 `rowOrdinal/sourceDigest/disposition/reason`。创建和验证回执时，decision iterable 与 classifier 的稳定诊断流同步前进：少一项、多一项、顺序不同、source digest 不同或 extensible shape 都立即失败关闭。classifier 仍执行最多 100,000 行的单遍 iterator scan，不缓存全表。

允许的 disposition 固定为：

- `adopt`：仅用于 `lossless + reviewed_lossless`；
- `adopt_shell_compatibility`：仅用于 `requires_shell_compatibility + reviewed_shell_compatibility`；
- `skip`：lossless/shell 可由 operator 或 security review 排除，manual 只能以 excluded/security/unsupported 跳过，malformed 只能以 `malformed_source` 跳过。

`requires_manual_action` 和 `malformed` 不能通过回执注入新的 command、cron 或 label 映射。要采用这些任务，必须先有受审的新语义或重新生成能 canonicalize 的 plan，不能把 arbitrary override 塞进 adoption authority。

### 2. receipt 只保存聚合证据，不保存 decision 数组

decision-set evidence 保存 row count、三类 disposition count 与域隔离 `decisionDigest`。摘要逐项覆盖 classifier 的 source digest、classification、reason codes、enabled、候选 task/trigger spec digest 以及最终 disposition/reason。receipt 再绑定 profile、plan digest、inventory digest、reviewer、时间和 decision-set evidence，并计算独立的域隔离 `receiptDigest`。

因此 receipt 大小与任务数无关；未来 publisher 必须同时取得 decision stream，并重算同一 digest。receipt 或 decision stream 任一方单独存在都不构成 mutation authority。

### 3. issuer 必须是最近强认证的 User

reviewer 使用共享 `SecurityPrincipal` exact contract。只接受 `user`，assurance 必须是 `local_console`、`multi_factor` 或 `hardware`；认证距 issuance 最多 5 分钟。receipt lifetime 最长 30 分钟，且不能超过 principal expiry。decision ID 必须是 lowercase UUIDv7。

该纯模块只验证受信 composition root 传入的 principal，不能验证 principal 的外部来源，也不把摘要描述成数字签名。ADR-0097 已以专用 key provider、HMAC-SHA-256 和私有 no-replace NDJSON 绑定完整 decision stream，但正式 publisher Gate 仍要求 local console/管理入口完成认证、Policy、撤权 fence 与 durable audit；在该 Gate 完成前，即使持有合法 authorization file 也不能获得写 authority。

### 4. 创建和验证都重新检查当前 source

公开 local-admin API 先以 `expectedPlanDigest` 重建 plan，再以同一 canonical timezone 打开 defensive/query-only source。decision scan 前后检查文件 identity；receipt 的 profile、plan digest 和 inventory digest 必须与当前 reviewed source 完全一致。验证还要求 observation time 落在 receipt 有效期内。

这意味着回执不能跨 plan、跨 Profile、跨 timezone 或跨 Crontab 内容复用。即使 receipt 自身摘要仍正确，source 漂移也会在进入 publisher 前失败。

### 5. review 模块保持短生命周期与 lazy boundary

decision receipt 是 `@qinglong/local-admin` 的内部模块，不新增 workspace package。它只按需加载 classifier 与 `runtime-core/security` subpath；`@qinglong/local-admin/runtime` 不载入 decision/classifier，也不创建 timer、watcher、连接池或 Scheduler。

## 被否决的替代方案

1. **一个全局 approve boolean**：不能证明逐项覆盖，拒绝。
2. **receipt 内嵌全部 decision**：任务数越大，JSON/内存越大，不适合路由设备，拒绝。
3. **manual 项携带任意 replacement command/spec**：绕过冻结 semantic registry 与 plan review，拒绝。
4. **允许单因素或 service principal 审阅 shell**：无法满足本机高风险接管边界，拒绝。
5. **摘要等同于签名或认证**：SHA-256 可由持有内容者重算，不能证明 issuer，拒绝。
6. **receipt 一生成就允许 publisher 写入**：即使 ADR-0097 已补 durable authenticated decision stream，Policy/audit 和共同事务仍未完成，拒绝。
7. **为回执新拆 package**：没有独立部署或供应链边界，拒绝。

## 验收证据

1. local-admin 测试覆盖四类诊断对应的 adopt/shell-adopt/skip 矩阵和低敏输出。
2. 测试覆盖 decision 缺失、额外、source digest 错位、classification 越权、弱认证、receipt tamper、expiry 与 source drift。
3. receipt create→JSON round-trip→verify 产生完全相同的 canonical receipt。
4. runtime import 测试证明 activation subpath不加载 migration SQL、classifier 或 decision receipt。
5. dependency audit 只允许 classifier 访问 Task/Trigger semantic subpath，只允许 decision receipt 访问 security subpath；ADR-0097 的 HMAC 载体另仅访问 local-secret provider contract。

## 后续约束

ADR-0097 已补 durable decision-set carrier 与 key-backed issuer capability；ADR-0098 已实现本机原子 publisher、Project/RoleBinding fence、allowed audit 和 batch ledger。publisher 在 fenced source 与同一 authenticated descriptor 上逐项锁步，并在目标单一 SQLite write transaction 中为每个 `adopt*` 项同成同败地创建 TaskDefinition、context recipe、execution revision 与 Trigger；`skip` 不创建 head。产品 issuer ceremony、Scheduler、Run admission、物理写放大与 legacy process cutover 仍保持独立 Gate。