From 7ed7a08211a19f043fad5e8ae1f95567738d1648 Mon Sep 17 00:00:00 2001 From: whyour Date: Tue, 1 Sep 2026 19:02:44 +0800 Subject: [PATCH] docs(ql3): record reconciliation artifact delivery --- docs/QINGLONG_3_0_ARCHITECTURE_RFC.md | 2 +- .../ADR-0526-exact-post-write-reconciliation-capture.md | 7 ++++--- docs/operations/ql3-alpha-candidate.md | 4 +++- docs/operations/ql3-local-alpha-trial-kit.md | 2 ++ 4 files changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/QINGLONG_3_0_ARCHITECTURE_RFC.md b/docs/QINGLONG_3_0_ARCHITECTURE_RFC.md index 83d6bc2f..95b00ad5 100644 --- a/docs/QINGLONG_3_0_ARCHITECTURE_RFC.md +++ b/docs/QINGLONG_3_0_ARCHITECTURE_RFC.md @@ -1,6 +1,6 @@ # QingLong 3.0 Architecture RFC -- D-426c1/ADR-0526（源码与 exact artifact gate 已闭合，双架构阶段实物待交付）：downloadable `upgrade-cutover-rehearsal.sh` 保留既有 clean rollback 默认路径，并新增显式 `--capture-after-write <独立私有根>`。同一 reviewed stage/Owner/apply/target-active 链先通过正式 `task.put` 提交固定、无网络/Secret 的业务 Task，再要求 target stop 返回 `reconciliation_required`；随后以现有短生命周期 Operator 串行执行 reconciliation capture prepare/commit/verify，把 legacy、target、recovery、Application config、activation 与 exact stopped head/record 密封到外置 root。对 v4 adopted target，capture proof 必须以 stopped evidence 中的 exact baseline digest 重新加载并核对 durable post-apply baseline，不允许丢失 baseline 维度后再比较。成功 summary 固定 `reconciliation_captured`、`legacySource=unchanged`、`target=stopped`、`rollback=not_authorized`、`next=review_required`，不自动回退或应用。Trial Kit/verification/auditor 升为 `@v9/@v7/@v6`、manifest schemaVersion 10，并增加 required `legacyUpgradeReconciliationCapture=passed`；原生 artifact job 必须在保留 clean rollback 演练的同时，用独立目录/容器第二次实跑写后 capture 并验证 manifest/receipt/assets 后才能上传。该切片不修改核心 classifier、不新增 package/依赖/daemon/listener/timer/watcher/连接或稳态资源；低配路由器默认 headless 不变。它证明的是 active target 数据权威经 Owner 产品入口发生写入后的 fail-closed capture，不冒充普通 Local API listener、2.x 老面板、自动 reconciliation、生产升级或 Public Release。 +- D-426c1/ADR-0526（exact Console 双架构阶段实物已交付）：downloadable `upgrade-cutover-rehearsal.sh` 保留既有 clean rollback 默认路径，并新增显式 `--capture-after-write <独立私有根>`。同一 reviewed stage/Owner/apply/target-active 链先通过正式 `task.put` 提交固定、无网络/Secret 的业务 Task，再要求 target stop 返回 `reconciliation_required`；随后以现有短生命周期 Operator 串行执行 reconciliation capture prepare/commit/verify，把 legacy、target、recovery、Application config、activation 与 exact stopped head/record 密封到外置 root。对 v4 adopted target，capture proof 必须以 stopped evidence 中的 exact baseline digest 重新加载并核对 durable post-apply baseline，不允许丢失 baseline 维度后再比较。成功 summary 固定 `reconciliation_captured`、`legacySource=unchanged`、`target=stopped`、`rollback=not_authorized`、`next=review_required`，不自动回退或应用。Trial Kit/verification/auditor 升为 `@v9/@v7/@v6`、manifest schemaVersion 10，并增加 required `legacyUpgradeReconciliationCapture=passed`；原生 artifact job 必须在保留 clean rollback 演练的同时，用独立目录/容器第二次实跑写后 capture 并验证 manifest/receipt/assets 后才能上传。首次 artifact run `33467541901` 在真实 arm64 上走到 `reconciliation_required` 后暴露 adopted baseline 重算缺口，finalizer 正确未形成；修复提交 `0235973c9b54a2f22de09b6487ea9f184f0b8bfd` 的普通主 CI [run 33469372499](https://github.com/whyour/qinglong/actions/runs/33469372499) 为 41 success/3 expected skip/0 fail，Kubernetes [run 33469372500](https://github.com/whyour/qinglong/actions/runs/33469372500) 成功，显式 Console [run 33469435652](https://github.com/whyour/qinglong/actions/runs/33469435652) 为 42 success/2 scope skip/0 fail。该 run 交付 amd64/arm64/milestone artifact `9786301280`/`9786374284`/`9786520389`，大小 `226683392`/`222083072`/`6489` bytes，保留至 2026-10-01；两个原生 job 在上传前离线审计 exact bundle，finalizer 再下载并复核二者，本机重新下载的 milestone v5 通过 `SHA256SUMS` 与 auditor，返回 `compatible=true` 并绑定 `3.0.0-alpha.2`、`console`、同一 source/workflow/run/attempt。内部 Docker archive digest 为 amd64 `sha256:3c9f7dac623bacd4b88b933a3668cfe74526a9fc4fe73823f821535a11aba3f4`、arm64 `sha256:68ee76d6f0a20f876da4ccfef96bb58f08aa965969d44ed587f3df37536529db`。该切片不修改核心 classifier、不新增 package/依赖/daemon/listener/timer/watcher/连接或稳态资源；低配路由器默认 headless 不变。它证明的是 active target 数据权威经 Owner 产品入口发生写入后的 fail-closed capture，不冒充普通 Local API listener、2.x 老面板、自动 reconciliation、生产升级或 Public Release。 - D-426b2c/ADR-0525（exact Console 双架构阶段实物已交付）：Console adopted target 不再借用 fresh HTTP journey，也不以普通 Local API 启动破坏 clean rollback。`ql3-local-api` 新增显式 `--cutover-probe --config `：严格验证外层 loopback/deployment/Owner 配置后委托既有 Application 只读 probe，不绑定 listener、不读取 credential/pepper、不激活 recovery、scheduler、execution、plugin recovery 或产品管理面。Owner target command 可选绑定 Local API 宿主/容器配置路径，target evidence 同时摘要并校验外层 API、内层 Application、严格不同的 target path、exact read-only mounts 与 `['--cutover-probe','--config',expectedApiPath]`；省略该字段时 headless command/journal digest 不变。Trial Kit cutover summary 升为 v2，绑定 variant 与 `local-application|local-api` entrypoint；原生 workflow 对 headless/Console 均要求 `legacyUpgradeCutover=passed`，同时保留真实 Console listener/API/credential/Task journey 作为独立门。没有新增 workspace package、依赖、daemon、sidecar、timer、watcher、连接池或稳态资源；默认低配路由设备仍选择 headless，Cluster 不复用 Local POSIX/SQLite/Docker proof。Local API 80/80、Owner CLI 314 total/307 pass/7 conditional skip/0 fail、Trial Kit 12/12、Application 56 total/51 pass/5 conditional skip/0 fail，package/Cluster/Edge/image 审计 compatible。提交 `229c3cb4e826866a0c7c4d81cb5e52cdc3975eec` 的普通主 CI run `33462165722` 与 Kubernetes live run `33462165834` 成功；显式 Local Console artifact run `33463415938` 交付 amd64/arm64/milestone（artifact `9784212784`/`9784111987`/`9784288018`），三个重新下载的离线 auditor 均为 `compatible=true`，保留至 2026-10-01。正常 `ql3-local-api --config` 提供现有 3.0 Console，`--cutover-probe` 仅用于无写入的升级证据；这不声明 2.x 老面板 API 零改动兼容。 diff --git a/docs/adr/ADR-0526-exact-post-write-reconciliation-capture.md b/docs/adr/ADR-0526-exact-post-write-reconciliation-capture.md index 1239b9a1..e817f8aa 100644 --- a/docs/adr/ADR-0526-exact-post-write-reconciliation-capture.md +++ b/docs/adr/ADR-0526-exact-post-write-reconciliation-capture.md @@ -1,6 +1,6 @@ # ADR-0526：Exact 写后 Reconciliation Capture -- 状态：Accepted（源码与 artifact gate 已闭合；同源双架构阶段实物待独立 workflow 交付） +- 状态：Accepted（同源 exact Console 双架构阶段实物已交付） - 日期：2026-09-01 - 决策：D-426c1 - 关联：ADR-0476、ADR-0482、ADR-0483、ADR-0523、ADR-0524、ADR-0525 @@ -41,8 +41,9 @@ ADR-0524/0525 已让 downloadable Trial Kit 在 headless 与 Console 两种变 - 编辑前 GitNexus：Trial Kit verification/create 为 LOW，offline auditor 为 MEDIUM（5 direct、12 total、0 process），Operator workflow auditor 为 LOW；没有 HIGH/CRITICAL 编辑目标。Shell 模板未被索引，使用 backward-compatible 参数、`sh -n`、静态 contract 与原生 Docker artifact gate 约束。 - 聚焦 bundle/operator 静态回归为 18/18，证明 v9/v7/v6 schema、canonical script、required gate、exact `task.put`/capture command 与 workflow order 闭合。全部 18 个 `packages/ql3-*` 已重新编译并通过自身契约测试；后端脚本层全量回归为 1661 total / 1659 pass / 2 conditional skip / 0 fail。Package boundary（18 个 package、无 single/shallow source package）、Edge import、Cluster dependency 与 Local Operator image audit 全部 `compatible=true`。 -- 首次 exact Console artifact run `33467541901` 在 arm64 上已真实证明写入与 `reconciliation_required`，随后于 capture prepare 因 v4 adopted baseline 重算缺口失败，且未上传 Trial Kit，因而不计为交付。修复后 reconciliation 聚焦回归为 72 total / 70 pass / 2 conditional Docker skip / 0 fail，新增 adopted-baseline 正向与篡改失败关闭用例；Owner CLI 全量为 316 total / 309 pass / 7 conditional skip / 0 fail。仍必须以新 source commit 重跑原生双架构 workflow。 -- exact Docker 正向证据必须来自新的 workflow source commit；在该 run 与双架构 milestone 实际成功、重新下载并离线复核前，本 ADR 不宣称 D-426c1 已形成可下载阶段实物。 +- 首次 exact Console artifact run `33467541901` 在 arm64 上真实证明写入与 `reconciliation_required`，随后于 capture prepare 因 v4 adopted baseline 重算缺口失败，且未上传 Trial Kit，因而不计为交付。修复后 reconciliation 聚焦回归为 72 total / 70 pass / 2 conditional Docker skip / 0 fail，新增 adopted-baseline 正向与篡改失败关闭用例；Owner CLI 全量为 316 total / 309 pass / 7 conditional skip / 0 fail。 +- 修复提交 `0235973c9b54a2f22de09b6487ea9f184f0b8bfd` 的普通主 CI [run 33469372499](https://github.com/whyour/qinglong/actions/runs/33469372499) 为 41 success / 3 expected artifact-finalizer skip / 0 fail，同源 Kubernetes [run 33469372500](https://github.com/whyour/qinglong/actions/runs/33469372500) 成功。显式 Local Console [run 33469435652](https://github.com/whyour/qinglong/actions/runs/33469435652) 为 42 success / 2 scope skip / 0 fail；amd64、arm64 的 `Materialize and offline-audit the native Local Alpha trial kit`、上传步骤和最终 `Finalize the Local Alpha milestone` 全部成功。 +- 该 run 交付 artifact `9786301280`（amd64，226683392 bytes，GitHub ZIP `sha256:49e921cb251da8cec3dcee5308174dd8aca89ffa18a3df6e6c7d0f43095c6f70`）、`9786374284`（arm64，222083072 bytes，`sha256:4ff7d3fff5af16ca55350d0dbf14c35d8ddcdeecb7d395ba017a14081949e0e8`）与 `9786520389`（milestone，6489 bytes，`sha256:d69c769117268fe8559043bb62999549d215c12f353e34c51d32d22ce319dd4c`），均保留至 2026-10-01。finalizer 下载并重新审计两个 exact bundle 后才生成 milestone；本机重新下载的 milestone 通过 `SHA256SUMS`，v5 auditor 返回 `compatible=true`，绑定 `3.0.0-alpha.2`、`variant=console`、同一 source/workflow SHA/ref/run/attempt。milestone 记录的内部 Docker archive digest 为 amd64 `sha256:3c9f7dac623bacd4b88b933a3668cfe74526a9fc4fe73823f821535a11aba3f4`、arm64 `sha256:68ee76d6f0a20f876da4ccfef96bb58f08aa965969d44ed587f3df37536529db`。D-426c1 因此已形成可下载、可验真的 Alpha 阶段实物；它仍不是 Public Release，也不授权自动 reconciliation application、Legacy restart 或生产切换。 ## 后续 diff --git a/docs/operations/ql3-alpha-candidate.md b/docs/operations/ql3-alpha-candidate.md index f862fb8c..fd7da55d 100644 --- a/docs/operations/ql3-alpha-candidate.md +++ b/docs/operations/ql3-alpha-candidate.md @@ -34,7 +34,7 @@ | D-426a Side-by-side 暂存 | 同源 v7 Trial Kit 已交付 amd64/arm64 headless 阶段实物；reviewed-plan `upgrade-rehearsal.sh` 在新的私有 root 中执行 SQLite stage/verify/activation 与完整目录 stage/verify，legacy root 始终只读，summary 固定 `cutover=not_authorized`；exact artifact job 实跑且 milestone v4 离线审计闭合 | 不执行 transform/apply、目标启动、cutover 或回退；仍不是 Public Release | | D-426b2b Exact headless 切换链 | 同源 v8 Trial Kit 已交付 amd64/arm64 headless 阶段实物；exact 上传包完成 readiness、reviewed stage、Owner 强认证 transform/apply、真实 legacy stop、只读 target probe start/stop 与 clean `rollback_candidate`，milestone v5 和三个离线 auditor 均闭合 | 仅授权 fresh/隔离数据演练；不停止用户真实 2.x、不执行 Legacy restart、写后 reconciliation 或生产 cutover；仍不是 Public Release | | D-426b2c Console adopted entry | 同源 exact amd64/arm64 Console Trial Kit 与 milestone 已交付；Local API cutover probe 不启动 listener/credential/mutation，controller 绑定双层配置、exact command/mount，原生 CI 完整演练且三个下载产物离线审计通过 | 仅授权 fresh/隔离数据演练；正常 Console 启动与只读 cutover probe 是不同模式；不承诺 2.x 老面板 API 零改动兼容、真实生产停机或写后回退 | -| D-426c1 写后 reconciliation capture | Trial Kit v9 源码与 exact artifact gate 已闭合：active target 数据权威经 Owner `task.put` 发生业务写入后必须分类为 `reconciliation_required`，并在独立私有 root 完成 capture prepare/commit/verify | 同源 amd64/arm64 milestone 尚待显式 artifact run；停在 `review_required`，不自动 plan/review/apply/rollback/restart；不证明普通 Local API 流量接管 | +| D-426c1 写后 reconciliation capture | 同源 Console Trial Kit v9 的 amd64/arm64 实物与 milestone 已交付；active target 数据权威经 Owner `task.put` 发生业务写入后分类为 `reconciliation_required`，并在独立私有 root 完成 capture prepare/commit/verify；双架构原生审计和 milestone v5 均闭合 | 停在 `review_required`，不自动 plan/review/apply/rollback/restart；不证明普通 Local API 流量接管、用户真实 2.x 升级或 Public Release | D-421 已关闭 D-420 记录的“Web Task mutation 必须独立设计”缺口，而且没有改名复用 run `33173769047` 的旧 archive。修复提交 `dc1686bd6fb3505174dd9a14098ae5c2c92a1a7f` 的普通主 CI [run 33229592307](https://github.com/whyour/qinglong/actions/runs/33229592307) 为 41 success/3 expected artifact-finalizer skip/0 fail，同源 Kubernetes deployment [run 33229592293](https://github.com/whyour/qinglong/actions/runs/33229592293) 成功；随后显式 Local Console milestone [run 33230227006](https://github.com/whyour/qinglong/actions/runs/33230227006) 为 42 success/2 scope skip/0 fail。由此 Web 创建能力已进入新的阶段实物，而不再只是候选源码。 @@ -52,6 +52,8 @@ D-426b2b 已从“源码候选”升级为新的可交付 headless 阶段实物 D-426b2c 已从“源码候选”升级为新的可交付 Console 阶段实物。提交 `229c3cb4e826866a0c7c4d81cb5e52cdc3975eec` 的普通主 CI [run 33462165722](https://github.com/whyour/qinglong/actions/runs/33462165722) 与 Kubernetes live run [33462165834](https://github.com/whyour/qinglong/actions/runs/33462165834) 均成功；显式 Local Console [run 33463415938](https://github.com/whyour/qinglong/actions/runs/33463415938) 完成全部门禁及 finalizer。amd64/arm64/milestone artifact ID 分别为 `9784212784`、`9784111987`、`9784288018`，GitHub 压缩大小为 `226669830`、`222069510`、`6489` bytes，ZIP digest 分别为 `sha256:d967f89d901837fbfc7b3d0d7be0ceb0ae4c36d44fc3ec707da539c34edfe76b`、`sha256:20cc976303a2c1219c91a1d620a8900ae9dfc3e28aa130f5609cb1a2bd9a1a0e`、`sha256:62c955fb376aba978a56f02abb8df611f888f44a4ee58196cd61e07e9f7912ff`，保留至 2026-10-01。重新下载后的两个 Trial Kit auditor 与 milestone v5 auditor 均为 `compatible=true`，并绑定 `3.0.0-alpha.2`、`variant=console`、同一 source/run/attempt；内部 Docker archive digest 为 amd64 `sha256:2b60885d19ec6b3f62671cc9370ee5cef4f1be41150797c36610dbdeb0a6514b`、arm64 `sha256:19c2e24d16ece348672ec4cd2a1ac4374cf6338da7e6113e2c056f7c085c4c53`。这证明同一 Console image 可在升级阶段以无 listener 的只读入口参与 exact cutover 证据，并在接收流量后用正常入口提供现有 3.0 面板；它不声明 2.x 老面板 API 零改动兼容。 +D-426c1 已从失败关闭的源码候选升级为新的可交付 Console 阶段实物。首次 [run 33467541901](https://github.com/whyour/qinglong/actions/runs/33467541901) 在真实 arm64 上证明 `task.put` 与 `reconciliation_required` 后暴露 adopted baseline 重算缺口，finalizer 正确未形成；修复提交 `0235973c9b54a2f22de09b6487ea9f184f0b8bfd` 的普通主 CI [run 33469372499](https://github.com/whyour/qinglong/actions/runs/33469372499) 为 41 success/3 expected skip/0 fail，同源 Kubernetes [run 33469372500](https://github.com/whyour/qinglong/actions/runs/33469372500) 成功，显式 Console [run 33469435652](https://github.com/whyour/qinglong/actions/runs/33469435652) 为 42 success/2 scope skip/0 fail。amd64/arm64/milestone artifact ID 为 `9786301280`/`9786374284`/`9786520389`，大小为 `226683392`/`222083072`/`6489` bytes，GitHub ZIP digest 为 `sha256:49e921cb251da8cec3dcee5308174dd8aca89ffa18a3df6e6c7d0f43095c6f70`、`sha256:4ff7d3fff5af16ca55350d0dbf14c35d8ddcdeecb7d395ba017a14081949e0e8`、`sha256:d69c769117268fe8559043bb62999549d215c12f353e34c51d32d22ce319dd4c`，保留至 2026-10-01。两个原生 job 在上传前各自执行 exact bundle offline auditor；finalizer 再下载并复核二者。本机重新下载的 milestone 通过 checksum，auditor 返回 `compatible=true`，内部 Docker archive digest 为 amd64 `sha256:3c9f7dac623bacd4b88b933a3668cfe74526a9fc4fe73823f821535a11aba3f4`、arm64 `sha256:68ee76d6f0a20f876da4ccfef96bb58f08aa965969d44ed587f3df37536529db`。该产物已能 fresh 运行内置 3.0 Console，并证明隔离切换后的写入必须进入 capture/review；它仍不兼容 2.x 老面板协议、不自动应用 reconciliation，也不是生产升级包。 + 默认低配 headless v5 也已从“可生成”升级为独立阶段实物。绑定提交 `d459c3b45c36e856f4a1cb3ce5147905977d939d` 的显式 Local headless milestone [run 33258604609](https://github.com/whyour/qinglong/actions/runs/33258604609) 为 42 success/2 scope skip/0 fail，完整矩阵继续覆盖双架构资源、Local/Cluster image、PostgreSQL HA、CloudNativePG、Secret/provider rotation 与 Local Profiles。该 run 没有复用 Console archive；下载后的两个 `headless` Trial Kit 与 milestone 均通过 `SHA256SUMS` 和仓库 auditor，返回 `compatible=true`。 首份跨部署全范围阶段实物绑定提交 `97333da34cce48cdfcfa1bbd5e8d48340802d2ef` 与 [run 33265538836](https://github.com/whyour/qinglong/actions/runs/33265538836)，为 `44 success / 0 skip / 0 fail`。它生成 headless Local 双架构、Cluster control/control-ai/admin/worker 双架构、两个 milestone 与 `ql3-alpha-97333da34cce48cdfcfa1bbd5e8d48340802d2ef-stage-index`；三个小索引的 GitHub ZIP digest 分别为 Local `2e3bb8baeeadb40f34c130db68db8b1a7d6cf7a7c92a73a805e84990bf9875dc`、Cluster `292380a72f8b45233f6591624f6073154c2b7d2d00f62908af687193078524e2`、stage `2fbc67d478593df8bbb2ba362beb9f676be1882ac2e5386106057789906adece`，保留至 2026-09-28。下载后三个 `SHA256SUMS` 与仓库 auditor 全部 `compatible=true`；stage auditor 确认 `3.0.0-alpha.2`、同一 source/run/attempt、三种 Profile 和 10 个可选择 artifact。 diff --git a/docs/operations/ql3-local-alpha-trial-kit.md b/docs/operations/ql3-local-alpha-trial-kit.md index 9f50a584..ade41d9a 100644 --- a/docs/operations/ql3-local-alpha-trial-kit.md +++ b/docs/operations/ql3-local-alpha-trial-kit.md @@ -182,6 +182,8 @@ sh upgrade-cutover-rehearsal.sh \ 该写入由短生命周期 Owner Operator 提交到 active target 的数据权威，不经过普通 Local API listener，因此只证明写后分类与 capture，不证明浏览器/生产流量接管。原生 artifact job 会先执行默认 clean rollback，再用同一 unchanged fixture 独立实跑本模式；`verification-evidence.json.gates.legacyUpgradeReconciliationCapture` 必须为 `passed`。 +当前已闭合的 exact Console v9 阶段实物绑定源码 `0235973c9b54a2f22de09b6487ea9f184f0b8bfd` 与 [workflow run 33469435652](https://github.com/whyour/qinglong/actions/runs/33469435652)：amd64 artifact `9786301280`、arm64 artifact `9786374284`、双架构 milestone `9786520389`，均保留至 2026-10-01。两个原生架构在上传前分别完成 clean rollback、写后 capture 和 bundle offline audit；milestone finalizer 下载并再次审计两个 exact bundle。本机重新下载的 milestone v5 通过 `SHA256SUMS`，auditor 返回 `compatible=true`。这是 `3.0.0-alpha.2` 的隔离 Alpha 候选，不是 Public Release 或用户真实 2.x 数据的自动升级授权。 + ## 手工加载与最小 smoke 从 `manifest.json.archive.file` 找到 archive 后加载：