mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-20 16:07:11 +08:00
feat(ql3): plan reconciliation application
This commit is contained in:
whyour
@@ -11,6 +11,25 @@
|
||||
|
||||
最新增量证据（2026-08-21）：
|
||||
|
||||
- D-392/ADR-0485（已接受）：D-391 的 signed review 不能直接获得通用 DML authority；表级 `adopt_legacy/retain_both` 也不能证明
|
||||
Automation 行级 command/trigger 兼容，更不能覆盖 Secret custody、append-only history、Plugin/AI 外部资产与 Identity/Policy 语义。
|
||||
因此既有 Local Owner 新增 `reconciliation.application.prepare|commit|verify`，以
|
||||
`reconciliation_reviewed → reconciliation_application_prepared → reconciliation_application_planned` CAS 建立唯一领域执行根。coordinator
|
||||
重新验证 sealed review、issuer HMAC、decision-set 与 instance head，只用固定 counters 生成八领域、Legacy/Target 双侧、content-free 的
|
||||
disposition/action plan；plan 不包含名称、路径、fact digest、row value、command、Secret、reviewer identity，且上限 64 KiB。Legacy fact
|
||||
现拒绝 `retain_target`，Target fact 拒绝 `adopt_legacy/exclude_legacy`，修复了 D-391 的数据库方向语义缺口。intent/plan/receipt/seal/head
|
||||
全部 no-replace exact replay，terminal 收敛为 `0400/0500`，专用只读 reader 不放宽通用 `0600` command-file policy。prepare/commit/verify
|
||||
均不打开 SQLite、不执行 SQL/DML、Secret 解密、service/Docker/network，也不授予 restart/completion。实现位于既有
|
||||
`deployment/reconciliation/application/` 的 contract/plan/coordinator 三个职责文件，没有新增 package、dependency、binary、daemon 或
|
||||
`src/` 根平铺。聚焦套件 `35 total / 33 pass / 2 conditional Docker skip / 0 fail`，完整 Local Owner
|
||||
`257 total / 250 pass / 7 conditional skip / 0 fail`，Git 跟踪 backend
|
||||
`1541 total / 1539 pass / 2 conditional skip / 0 fail`；包含用户未提交测试的工作区 backend 也以 `1542/1540/2/0` 通过。18-package clean
|
||||
build/逐包测试、八项架构/部署审计、真实 Docker readonly reconciliation `2/2` 与十四档 artifact audit 全通过。workspace 仍为 18
|
||||
packages、`singleSourcePackages=[]`、`shallowSourcePackages=[]`；Local Owner 为 `158 source / 157 nested / 1 root binary entry`。基础
|
||||
Edge/Standalone 精确保持 `2,611,978 / 2,612,056 bytes`、319 files、58 modules。虽无 SQL/Cluster 变更，仍额外重跑 PostgreSQL 18.6
|
||||
arm64 physical HA：146 gates、timeline `1 → 2`，private evidence SHA-256
|
||||
`632d71f2a5b33cf657476fbe41702064b609b12cdf2382bcddaef06f4d08279f`，独立审计无 finding，Docker 资源已清理。D-393 才能以独立 ADR
|
||||
定义首个 Automation 行级 adapter、写前 backup、重新认证、幂等冲突、commit/replay 与 rollback。
|
||||
- D-391/ADR-0484（已接受）：既有 Local Owner 已完整实现
|
||||
`reconciliation.review.prepare|diagnostics|commit|verify`，以
|
||||
`reconciliation_planned → reconciliation_review_prepared → reconciliation_reviewed` CAS 建立唯一 review fence。diagnostics 每次只把一个
|
||||
|
||||
@@ -0,0 +1,191 @@
|
||||
# ADR-0485：Reconciliation 应用协调器与领域 Adapter 边界
|
||||
|
||||
- 状态：Accepted（D-392 已实现并完成门禁）
|
||||
- 日期：2026-08-21
|
||||
- 关联 RFC：QL-RFC-0001 D-05、D-06、D-17、D-64、D-87、D-184、D-259、D-383、D-389、D-390、D-391、D-392
|
||||
- 关联 ADR：ADR-0482、ADR-0483、ADR-0484
|
||||
- 细化：ADR-0484 的签名人工裁决消费边界
|
||||
|
||||
## 背景
|
||||
|
||||
ADR-0484 已把密封 reconciliation plan 转换为逐事实、强认证 User 签名的 review authorization，但该 authorization 仍只表达
|
||||
operator 对 schema object/table 事实的选择。它没有定义任何领域的行级兼容、幂等键、写入顺序、备份、回滚或外部资产语义。
|
||||
|
||||
直接让通用导入器消费 review 会产生错误的授权提升。例如 Automation 表被选择为 `adopt_legacy`，并不意味着表内每个 Legacy shell
|
||||
command 都能转换为 3.0 TaskDefinition，也不能证明目标 task id、timezone、disabled state 和 trigger 没有冲突。Secret、Run history、
|
||||
Plugin package、AI/Tool 与 Identity/Policy/Audit 的安全语义差异更大，不存在一套可信的通用 DML。
|
||||
|
||||
D-392 因此只建立一个持久、内容无关的应用顺序根。它把签名 decision stream 汇总成固定八领域计划，为后续 adapter 提供唯一 fence，
|
||||
但不执行迁移。
|
||||
|
||||
## 决策
|
||||
|
||||
### 1. 增加独立 application coordinator 状态机
|
||||
|
||||
既有 `ql3-local-deploy` 增加三个显式私有命令：
|
||||
|
||||
```text
|
||||
local.deployment.reconciliation.application.prepare
|
||||
local.deployment.reconciliation.application.commit
|
||||
local.deployment.reconciliation.application.verify
|
||||
```
|
||||
|
||||
状态以 instance head CAS 推进：
|
||||
|
||||
```text
|
||||
reconciliation_reviewed
|
||||
→ reconciliation_application_prepared
|
||||
→ reconciliation_application_planned
|
||||
```
|
||||
|
||||
`application.prepare` 必须绑定 exact `reviewId`、`reviewDigest` 和 reviewed head digest。它建立唯一 application fence 后，以 no-replace
|
||||
方式发布 intent。第二个 application、旧 review replay、rollback、restart 或越级 commit 都必须失败关闭。
|
||||
|
||||
`reconciliation_application_planned` 只表示领域执行顺序已固定，不表示 reconciliation 完成、数据库已迁移或 target 可以重启。
|
||||
|
||||
### 2. Application plan 固定为八领域内容无关摘要
|
||||
|
||||
coordinator 重新验证 D-391 的 sealed review directory、authorization HMAC、issuer keyring、review/receipt binding 和 decision-set digest，
|
||||
并在读取签名 NDJSON 时以固定 counter 统计：
|
||||
|
||||
```text
|
||||
schema_lineage
|
||||
automation
|
||||
secret_and_config
|
||||
run_history
|
||||
plugin_package
|
||||
ai_and_tool
|
||||
identity_policy_audit
|
||||
unknown
|
||||
```
|
||||
|
||||
每个领域只保存 Legacy/Target 两侧的 decision count、固定 disposition counts、summary digest 与 action：
|
||||
|
||||
```text
|
||||
no_effect | adapter_required | manual_external | adapter_and_manual
|
||||
```
|
||||
|
||||
总体 outcome 为：
|
||||
|
||||
```text
|
||||
no_effect_ready | adapter_required |
|
||||
manual_required | adapter_and_manual_required
|
||||
```
|
||||
|
||||
plan 不保存对象名、表名、路径、fact digest、row value、command、schedule、Secret、credential、Prompt/Tool payload、Artifact、日志或 reviewer
|
||||
identity。它最多 64 KiB，domain 数固定为 8，内存只使用固定 counters 与 64 KiB 读取缓冲。
|
||||
|
||||
### 3. 修正 disposition 的数据库方向语义
|
||||
|
||||
D-391 已限制 blocked domain，但原始校验没有拒绝数据库方向矛盾的选择。D-392 明确：
|
||||
|
||||
- Legacy fact 不允许 `retain_target`；
|
||||
- Target fact 不允许 `adopt_legacy` 或 `exclude_legacy`；
|
||||
- `retain_both`、`defer` 与 `manual_external` 仍受既有 domain/blocked 规则约束；
|
||||
- informational fact 仍不得出现在 decision stream。
|
||||
|
||||
该规则在签名发布前对重新派生的 canonical fact 生效，不依赖 diagnostics page。
|
||||
|
||||
### 4. 持久化、封存与崩溃恢复
|
||||
|
||||
`applicationRoot` 必须与 deployment、capture、plan、review root 两两不重叠；issuer keyring 必须位于 deployment root 的真后代。catalog 最多
|
||||
保留 64 个 application directory，每个目录只含：
|
||||
|
||||
```text
|
||||
intent.json
|
||||
plan.json
|
||||
receipt.json
|
||||
staging/
|
||||
```
|
||||
|
||||
intent、plan、receipt 使用 no-replace publication、stable file identity、file/directory fsync 和 digest binding。prepare head、plan、receipt、
|
||||
terminal seal 与 planned head 后的 response loss 均必须 exact replay；冲突内容不允许覆盖或自动清理。terminal 文件收敛为 `0400`，目录与
|
||||
空 staging 收敛为 `0500`。专用 terminal reader 在读取前后复核 owner、mode、link count、device/inode、size、mtime/ctime，不放宽通用
|
||||
`0600` command-file policy。
|
||||
|
||||
### 5. Verify 完全只读
|
||||
|
||||
verify 只读取 sealed application evidence、sealed review authorization、issuer verification key 与 instance head。它不创建、替换、修复或
|
||||
清理文件，不打开 Legacy/Target SQLite，不执行 checkpoint、SQL/DML、Secret 解密、Docker/init/service/network 或后台 retry。
|
||||
|
||||
应用 coordinator 的 prepare/commit 同样不得打开 SQLite。它消费的是 D-391 已签名、内容完整性受保护的 decision stream，而不是重新读取
|
||||
数据库。每个未来 adapter 在写入前仍必须重新验证 exact application plan/head 和自己的领域输入。
|
||||
|
||||
### 6. 领域 Adapter 必须独立授权和回滚
|
||||
|
||||
D-392 不提供通用 apply。后续每个 adapter 至少要单独定义：
|
||||
|
||||
- 可接受的 source/target row schema 与兼容矩阵；
|
||||
- Project/Policy/Owner authority 与需要重新认证的操作；
|
||||
- 幂等 identity、冲突规则、写入顺序和 response-loss replay；
|
||||
- 写前 backup、失败保全、rollback 与不可逆边界；
|
||||
- Secret custody、append-only history、外部文件/OCI/KMS 等领域特有语义；
|
||||
- Edge 的 RSS/I/O/磁盘峰值与 Cluster 的并发、租约和 HA 语义。
|
||||
|
||||
第一候选为 Automation adapter，但它必须先生成逐行、可审查、可回滚的 TaskDefinition/Trigger 转换计划，不能把 D-391 的表级选择直接解释为
|
||||
批量 INSERT/UPDATE。
|
||||
|
||||
### 7. Package 与部署边界
|
||||
|
||||
实现内聚在既有 `@qinglong/local-owner-cli/src/deployment/reconciliation/application/`，按 contract、plan、coordinator 三个职责文件组织。
|
||||
不新增 workspace package、production dependency、binary、daemon、timer、watcher、listener 或 socket，也不把文件平铺到 package `src/`
|
||||
根。基础 Edge/Standalone runtime artifact 不应携带一次性 application authority；Cluster/PostgreSQL/Kubernetes 不读取 Local application root。
|
||||
|
||||
## 当前实现进度
|
||||
|
||||
D-392 已实现三条命令、两阶段 instance CAS、八领域 content-free plan、signed authorization domain counters、数据库方向校验、`0400/0500`
|
||||
terminal seal、完整 response-loss replay 和只读 verify。聚焦 reconciliation 套件为
|
||||
`35 total / 33 pass / 2 conditional Docker skip / 0 fail`；完整 Local Owner 为
|
||||
`257 total / 250 pass / 7 conditional skip / 0 fail`；Git 跟踪 backend 为
|
||||
`1541 total / 1539 pass / 2 conditional skip / 0 fail`。包含用户未提交测试的当前工作区 backend 也以
|
||||
`1542 total / 1540 pass / 2 conditional skip / 0 fail` 通过。18-package clean build/逐包测试、八项架构/部署审计与真实 Docker readonly
|
||||
reconciliation `2/2` 全部通过。
|
||||
|
||||
十四档 artifact audit 全部 `compatible`；基础 Edge/Standalone 精确保持
|
||||
`2,611,978 / 2,612,056 bytes`、319 files、58 loaded modules，证明一次性 application authority 未进入低配常驻闭包。workspace 仍为 18
|
||||
packages，`singleSourcePackages=[]`、`shallowSourcePackages=[]`；Local Owner 为
|
||||
`158 source / 157 nested / 1 root binary entry`。新增 3 个生产源码全部位于既有 `deployment/reconciliation/application/`，没有新增 package、
|
||||
dependency、binary 或常驻对象。
|
||||
|
||||
本切片没有 SQL、SQLite open、数据库 schema、PostgreSQL driver/ACL/role/Pool、Cluster deployment 或 HA 拓扑改动；仍按 operator 授权额外
|
||||
重跑 PostgreSQL 18.6 arm64 physical HA，以 146 gates、timeline `1 → 2` 通过。private evidence SHA-256 为
|
||||
`632d71f2a5b33cf657476fbe41702064b609b12cdf2382bcddaef06f4d08279f`，独立 evidence audit 无 finding，临时 Docker container/network 已
|
||||
清理。该证明是额外回归证据，不把 Local application coordinator 解释为 Cluster reconciliation authority。
|
||||
|
||||
## 被拒绝的替代方案
|
||||
|
||||
### 让 D-391 review 直接调用 Automation adoption
|
||||
|
||||
拒绝。D-391 是 schema/table fact 授权，既有 adoption 是逐行首次接管协议；二者的冲突、幂等和 rollback 语义不等价。
|
||||
|
||||
### 为八个领域立即各建一个 package
|
||||
|
||||
拒绝。尚未形成独立发布、依赖或生命周期边界，会制造单文件/浅层 package。领域 adapter 先在现有 owner composition 的嵌套目录孵化，只有
|
||||
出现稳定复用边界后才考虑拆包。
|
||||
|
||||
### 把全部 decision 加载成内存 JSON
|
||||
|
||||
拒绝。Edge 路由设备不能让内存随 schema 规模增长；签名验证与 domain summary 必须流式、固定缓冲。
|
||||
|
||||
### 把 application plan 当作 restart authority
|
||||
|
||||
拒绝。计划没有证明任何 adapter 已成功执行，也没有证明 Secret、历史或外部资产已收敛。
|
||||
|
||||
## 验收条件
|
||||
|
||||
1. 只有 exact reviewed head/review digest 可建立唯一 application fence；第二 application、rollback 与 restart 被阻断。
|
||||
2. signed authorization 被重新验证并汇总为固定八领域、双数据库、固定 disposition counters；全局与领域计数严格守恒。
|
||||
3. Legacy/Target 的方向矛盾 disposition 在签名前失败；blocked/informational 规则不回退。
|
||||
4. application plan/receipt 不包含名称、路径、fact digest、row value、command、Secret 或 reviewer identity，且 plan 不超过 64 KiB。
|
||||
5. prepare、plan、receipt、seal、head 的全部 response-loss 窗口 exact replay，竞争 application 失败关闭。
|
||||
6. terminal 文件为 `0400`、目录为 `0500`；verify 只读且不打开 SQLite、不写数据库、不调用服务或网络。
|
||||
7. 不新增 package/dependency/binary/常驻对象，不平铺 package `src/`；Edge 基础 closure 不增长。
|
||||
8. 聚焦、Local Owner、tracked backend、18-package、架构、Docker 与十四档 artifact 门通过后，ADR 才可改为 Accepted 并阶段提交。
|
||||
|
||||
## 未包含
|
||||
|
||||
- Automation 或其他领域的行级转换、SQL/DML、备份与 rollback；
|
||||
- Secret 解密/重加密、Run history 合并、Plugin/AI 外部资产复制；
|
||||
- reconciliation completion、target restart 或 Legacy source 删除；
|
||||
- Cluster/PostgreSQL/Kubernetes reconciliation；
|
||||
- 固定物理 Edge/NAS 的断电、FTL 写放大与迁移峰值证明。
|
||||
Reference in New Issue
Block a user