ADR-0269：Profile-aware Local SQLite Readiness 诊断边界

状态：Accepted
日期：2026-08-04
关联 RFC：QL-RFC-0001 D-06、D-17、D-20、D-40、D-250
关联 ADR：ADR-0004、ADR-0063、ADR-0064、ADR-0086、ADR-0257

背景

仓库根命令 audit:schema:ql3 原先默认打开 data/db/database.sqlite，并用 back/migrations 的 legacy/Shadow ownership manifest 审计。该路径通常是用户的 2.x 数据库，而 fresh/adopted QingLong 3.0 的正式 SQLite authority 已经迁移到 @qinglong/local-sqlite 的独立 84 条 migration stream 与 capability v42。

旧命令虽然只读，但默认选择现网路径会产生三个问题：

把 2.x 数据库误称为 3.0 fresh schema，并稳定输出缺失表误报；
无法验证 edge DELETE 与 standalone WAL 的 Profile 差异；
让诊断结果与 application、Compose preflight 使用的 readiness authority 分叉。

决策

1. `audit:schema:ql3` 只表示正式 Local 3.0 readiness

根命令现在调用既有 @qinglong/local-owner-cli 中的 ql3-local-readiness。调用者必须显式提供 --database 与 --profile=edge|standalone；不存在默认数据库，也不从 cwd、环境变量或 2.x 配置猜测 authority。

诊断复用 @qinglong/local-sqlite/readiness-inspection，因此与启动/Compose preflight 共用同一 migration checksum、capability、required schema、foreign-key、quick-check 和 repository integrity 权威。edge 必须是 DELETE journal，standalone 必须是 WAL；不能用一个 Profile 的成功结果替另一个 Profile 背书。

2. 诊断入口保持短生命周期、只读和低敏

数据库必须是 canonical absolute path、当前 UID 所有、精确 0600、非 symlink regular file。诊断使用 Node 24 defensive/query-only SQLite，不执行 migration、repair、journal 切换或任何业务查询。成功只输出 contract name/version、migration/table 数、SQLite version 与 journal mode，不输出数据库路径、row、credential、digest 或 Secret。

失败输出只有稳定 code/name；底层可能包含路径的异常不能进入 stdout/stderr 产品结果。

3. legacy/Shadow 审计显式隔离

旧 ownership drift 工具保留为 audit:legacy-schema:ql3，供 2.x Shadow migration 兼容诊断使用。它必须显式传 --database；已删除隐式 data/db/database.sqlite 默认值，JSON 报告标记 mode=legacy-shadow。它不能作为 fresh/adopted 3.0 readiness 证据。

4. 不增加包或常驻成本

实现只在既有 @qinglong/local-owner-cli 增加一个 subpath/bin，复用已存在的 @qinglong/local-sqlite dependency。workspace 保持 19，不增加 dependency、migration、daemon、 listener、timer、watcher 或数据库连接池。诊断只在 operator 显式调用时加载。

替代方案

继续默认审计 data/db/database.sqlite：拒绝。会把 2.x 路径冒充 3.0 authority。
复制一份 schema manifest 到根脚本：拒绝。会与 application readiness 再次漂移。
诊断时自动 migration/切换 journal：拒绝。readiness 不能同时是隐式修复 authority。
为诊断新建 workspace package：拒绝。没有独立交付或 authority 价值，会突破包粒度约束。
从文件内容自动推断 Profile：拒绝。部署 Profile 是 operator intent，不应由当前 journal 状态反向猜测。

验证

pnpm --filter @qinglong/local-owner-cli test
node --test test/back/ql3ClusterDependencyAudit.test.cjs test/back/nodeSqliteSchemaCompatibility.test.cjs
pnpm audit:cluster-dependencies:ql3
pnpm audit:package-boundaries:ql3
edge/standalone fresh database 的 audit:schema:ql3 正向门；跨 Profile、重复参数、隐式路径和 0644 database 负向门。

当前证据为 Owner CLI 91/91、dependency/legacy 定向门 46/46、Worker Runtime 132/132、后端 1093 pass/2 条件 skip/0 fail；完整 package 门退出 0，workspace 仍为 19/19。正式 edge 实测输出为 capability v42、84 条 migration、76 张表和 DELETE journal，且不包含数据库路径。

影响

调用旧根命令但未传参数的开发脚本会失败关闭，需要明确选择 Local 3.0 或 legacy/Shadow 模式。这是一项有意的诊断兼容性收紧，不影响应用启动、migration 或用户数据。

4.3 KiB Raw Blame History Unescape Escape