qinglong/docs/adr/ADR-0064-side-by-side-legacy-sqlite-adoption.md

ADR-0064：2.x SQLite 旁路孵化、恢复点与显式切换

• 状态：Proposed
• 日期：2026-07-20
• 关联 RFC：QL-RFC-0001 D-05、D-17、D-37、D-40、D-42、D-62、D-63、D-64、D-65
• 关联 ADR：ADR-0004、ADR-0038、ADR-0042、ADR-0044、ADR-0062、ADR-0063、ADR-0065、ADR-0066

上下文

QingLong 2.x 的 database.sqlite 同时包含用户的定时任务、环境变量、认证配置、插件扩展表和逐步加入的 3.0 孵化表。旧启动路径还会先执行多次 Sequelize Model.sync()，再自动运行 SchemaMigrations stream。QingLong 3.0 的本机 adapter 则拥有独立的 QingLong3SchemaMigrations stream、受审约束和 node:sqlite authority。

把两条 stream 直接拼接或在启动时原地升级有三个不可接受的后果：

1. 旧进程可能仍在写库，备份、DDL 和切换之间没有可证明的一致边界；
2. preview 期间形成的旧 Runs 表与最终 3.0 CHECK/FK/index contract 可能同名但不同义，CREATE IF NOT EXISTS 会把不兼容结构误判为成功；
3. migration 失败、磁盘耗尽或新版本回退时，用户只剩一份被修改过的数据库。

因此 adoption 首先必须是可撤销的数据面操作，而不是启动过程中的便利副作用。

决策

1. 禁止自动原地接管

3.0 runtime、edge/standalone 组合根和普通启动脚本不得修改 2.x database.sqlite，也不得因为看到 legacy 表就自动补 migration。adoption 只能由独立、短生命周期的 @qinglong/local-admin authority 显式执行。

local-admin 不进入 base edge/standalone production closure，只能导入 @qinglong/local-sqlite/runtime 与 @qinglong/local-sqlite/migration 两个受审入口，不得加载 legacy 根、Sequelize、sqlite3、cluster、Worker 或 Drizzle。显式 adopted 产物只允许从 @qinglong/local-admin/runtime 取得无 DDL 的 activation 能力，dependency audit 和 require-cache 测试必须证明常驻入口没有加载 executable migration SQL。

2. 先检查并冻结 adoption plan

只读检查至少验证：

• source 是绝对路径下的普通文件，父目录和目标都不是 symlink；
• quick_check 与 foreign_key_check 成功；
• Auths(id,type,info)、Crontabs(id,command,schedule)、Envs(id,name,value) 三组 2.x sentinel 存在；
• schema object 数量和 SQL 总字节受硬上限保护；
• 不存在 Runs、RunAttempts、RunEvents、RunRetryPolicies 或 QingLong3Schema* 等冲突对象；
• file identity、catalog digest、Profile 和 plan payload 形成确定性的 SHA-256 planDigest。

真正 staging 时必须显式提交该 expectedPlanDigest，并重新检查 source。任何 inode、大小、mtime 或 catalog 漂移都在创建输出前拒绝。

3. adoption 是 side-by-side staging

staging 固定生成三个全新、互不重名且不得预先存在的文件：

1. recoveryPath：通过 Node 24 SQLite Online Backup 得到的只读逻辑恢复点；
2. targetPath：从恢复点复制后，仅在这份副本上运行 3.0 reviewed migration；
3. manifestPath：记录 plan、source identity、catalog、恢复点和目标库 SHA-256/字节、migration manifest、readiness evidence 的 0600 JSON。

原 2.x source 不执行 DDL、不写 adoption marker、不改变 journal。恢复点必须在 migration 前通过同一 legacy catalog 检查；目标必须在 migration 后通过完整 local-sqlite readiness。未知插件表、列、索引和行保留在恢复点与目标中。

所有输出使用 no-overwrite 创建和 0600 权限。失败时只清理本次调用已经创建的精确文件，不递归删除目录；source 永远不属于清理集合。manifest 使用严格、不可扩展 shape，校验时重新计算自身 digest、两个数据库 digest/字节、恢复点 catalog 和目标 readiness。

4. activation 是数据库级接管凭证，不是进程停机证明

staged manifest 只证明“存在一份可恢复的 2.x 快照和一份已迁移的 3.0 候选库”，不能直接启动 adopted Profile。短生命周期 authority 必须显式提交已审阅的 manifest digest，并按 source → target 的固定顺序对两库取得 BEGIN IMMEDIATE 写栅栏。在栅栏窗口内再次使用 Online Backup 证明 source 内容与 recovery 完全一致、再次严格校验 target 初始 SHA-256/readiness，然后以 no-overwrite、0600 文件写入严格 state: prepared activation document。

activation 绑定 adoption/plan/source/recovery/初始 target digest，并额外绑定 target 的绝对路径 digest、device 和 inode。它证明凭证生成时两库均无并发 writer，但不能证明旧进程已退出，也不能证明其网络请求、子进程或其他数据库外副作用已静默。部署 supervisor 仍必须先停止并确认 2.x application，再允许 adopted Profile 取得 activation；不得把一次 SQLite 锁成功包装成完整进程 cutover。

5. 常驻接管校验必须允许目标库演进

@qinglong/local-adopted-profile 只由 edge-adopted/standalone-adopted 显式组合且默认关闭。启用时固定执行：验证 expected activation digest → 校验不可变 manifest/recovery → 校验 target readiness 与稳定路径/device/inode → 对 source 取得完整生命周期写栅栏并以新 Online Backup 复核 → 打开目标 storage → 再次复核 target identity → 发布 adopted_storage_ready。

target 在 activation 后是 3.0 可写事实源，因此重启不能继续要求它与初始 staged SHA-256 相同；该 digest 只用于 lineage 和“尚未发生目标写入”的判断。常驻路径必须继续严格校验 recovery 和 manifest，但对 target 使用 readiness + stable identity。用另一个即使 readiness 合法的文件替换同一路径也必须 fail closed。停止顺序固定为先关闭 target storage，再释放 source 写栅栏；失败路径同样不得泄漏栅栏。

这里的 readiness 分成两个明确阶段。staging、显式 verifier 和 activation preparation 仍要求 初始 target 的完整 readiness 与 manifest 精确相等；常驻 activation acquisition 则要求 contractName、contractVersion、sqliteVersion、核心 migrationIds 与 journalMode 精确一致，并要求当前 tableCount 不低于 staged 基线。这样默认关闭的可选 Feature 可以在 activation 后通过独立 migration 只增表，且下一次启动不会被初始表数误拒；删除已审阅的 legacy/plugin 表、改变核心 stream、契约或 journal mode 仍会作为 readiness drift 拒绝。 这不是对任意 schema 漂移的放行：当前数据库还必须先通过完整 local-sqlite quick check、 foreign-key check、migration history、capability、必需 schema 与领域完整性审计。

该状态只装配 storage authority，不启动 scheduler、executor、HTTP admission 或自动 legacy projection。旧进程的完整停止证明和应用栈接管由部署 supervisor 的后续 gate 负责。

6. 回退分为“未写 target”和“已写 target”

若 target 仍与 activation 记录的初始 SHA-256/字节完全一致，可以证明 3.0 尚未产生新数据库事实；在 supervisor 保证两边应用均停止的前提下，关闭 adopted storage、释放 source 栅栏并重新启动未修改的 2.x source，不需要逆向 migration。

一旦 target 产生任何合法 3.0 写入，回到旧 source 会丢失切换后的新事实。此时系统不得声称“自动无损 rollback”，也不得用旧 source 覆盖 target；必须进入显式 reconciliation/export 流程，列出受影响的数据域、冲突和不可逆事实，由操作员选择继续 3.0、接受有损回退或执行受审数据回灌。当前 storage-only 切片保留 source 作为灾难恢复资产，但不实现写后自动合并。

被否决的替代方案

1. 在 3.0 启动时直接 migrate 旧库：把常驻 runtime 变成 DDL/admin authority，拒绝。
2. 只复制数据库主文件：WAL 中已提交内容可能丢失，拒绝；必须使用 SQLite Online Backup。
3. 用 CREATE IF NOT EXISTS 兼容 preview 表：同名不代表同 contract，拒绝。
4. migration 成功后覆盖原文件：失去稳定恢复点且 rename 不能证明旧 writer 已停止，拒绝。
5. 只保存 schema dump：不能恢复认证、任务、插件数据和未知对象，拒绝。
6. 把 staged manifest 当作安全 cutover token：它没有证明旧 writer 停止，拒绝。
7. 每次重启都要求 target 等于 staged hash：正常 3.0 写入会让合法目标永久无法重启，拒绝；运行期绑定稳定文件身份和 readiness。
8. target 已写后仍自动回到旧 source：会静默丢失 3.0 新事实，拒绝；必须显式 reconciliation。

影响

正向影响：

• 2.x 数据源始终保留；target 未写时回退不依赖逆向 migration；
• 备份、migration、readiness 和 manifest 各有独立证据；
• preview 同名表会 fail closed，不会被静默接管；
• 插件未知数据被保留，且不迫使 3.0 理解所有插件 schema；
• base edge/standalone 常驻产物不支付 admin/backup 代码成本，adopted 变体只在显式选择时支付 activation runtime 成本。

代价与限制：

• staging 至少需要约两份额外数据库空间；大库哈希和 Online Backup 是短生命周期 I/O；
• 当前只识别有三组稳定 sentinel 的 2.x baseline，更老或损坏的数据库需要单独兼容评审；
• SQLite 写栅栏不能停止旧进程的数据库外副作用，完整切换仍依赖部署 supervisor；
• target 写入后没有通用、自动且无损的 3.0 → 2.x 数据合并；
• Keyv SQLite、日志、配置文件和 Secret key 不在本 ADR 的单数据库恢复点内，完整升级仍需要多资产 backup manifest。

验证

1. 两次只读检查对未变化 source 生成相同 plan digest，且 source 字节不变。
2. plan 审阅后 source schema 漂移时，在创建任何输出前拒绝。
3. recovery 不含 3.0 migration 表，target 同时保留 legacy/插件行并通过 3.0 readiness。
4. source、recovery、target 和 manifest 的 hash/mode/不可覆盖语义均由测试覆盖。
5. 缺 sentinel、同名 3.0 对象、symlink、畸形或可扩展 manifest 均 fail closed。
6. activation 只能在 source/target 双写栅栏和最终快照复核内生成；source 漂移、target 替换或凭证 digest 漂移均 fail closed。
7. activation 生命周期内旧 source writer 被阻断，stop 后释放；目标 storage 打开后还会复核 inode，失败不泄漏 connection 或 source 栅栏。
8. target 发生合法 3.0 写入或可选 Feature 只增表后仍可按 stable identity/readiness 重启， 严格 staged verifier 会明确拒绝把它误判为“未写快照”；表基线减少、核心契约、 migration、SQLite version 或 journal mode 漂移仍 fail closed。
9. dependency audit 证明 local-admin 只访问两个 local-sqlite 管理入口，adopted composition 只能访问 local-admin runtime 子入口；四个本机产物集合与导入闭包均受门禁。
10. supervisor 停机证明、完整应用接管和写后 reconciliation 未落地前，最多宣称 adopted_storage_ready，不能宣称生产 cutover 或无损自动 rollback。