qinglong/docs/adr/ADR-0280-local-sqlite-storage-and-administration-composition-layout.md

ADR-0280：Local SQLite Storage 与 Administration Composition 布局

• 状态：Accepted
• 日期：2026-08-07
• 关联：D-07、D-87、D-257、ADR-0087、ADR-0088、ADR-0276

上下文

@qinglong/local-sqlite 已按 Run、Security、Plugin Package、Tool Execution、Migration、Local Owner 等 领域组织 148 个源码文件，但 src/ 根层仍有七个文件。其中 bootstrap.ts 与既有 storage/config.ts、database.ts、schema.ts 共同拥有数据库打开和最小 bootstrap authority； packageManagement.ts、pluginPackageWorkflowAdministration.ts、secretAdministration.ts 则都是 受认证、短生命周期、显式 subpath 才可取得的管理 composition entry。

继续把这四个文件留在根层会让“公共 export 就必须物理平铺”成为惯例；为每个文件单独建立目录或拆成 workspace package，又会制造用户担心的微目录/微包。此次调整必须保持 public package specifier、export 集合、依赖、事务、Policy fence、SQLite authority 与低配制品边界不变。

决策

1. bootstrap.ts 进入既有 src/storage/bootstrap.ts，与 config/database/schema 形成数据库 opening、 readiness 与最小 bootstrap repository 的 Storage composition；公开 @qinglong/local-sqlite/bootstrap specifier 不变。
2. package management、Workflow administration 与 Secret administration 三个文件共同进入 src/administration/。该目录表达“受认证、短生命周期、不能进入普通 runtime 的管理数据库组合”， 不是按一个能力建立一个单文件目录。
3. @qinglong/local-sqlite/package-management、authenticated-management、 optional-feature-runtime、plugin-package-workflow-administration 与 secret-administration 的公开 specifier 和 API 保持不变，只让 package exports 直接指向新的 dist/administration/*。
4. 根层只保留 index.ts、runtime.ts 与 adoption.ts。前两者是 package root/runtime composition； 后者是 738 行的独立 Legacy Adoption 公共领域入口。不得为了把根文件数做成零而给 adoption 建立缺乏 同域成员的装饰性目录。
5. schema v2 边界账本将 Local SQLite root hard cap 从 7 收紧到 3，并逐名冻结三个合法根文件。clean build 必须证明旧根 source、JavaScript、declaration 和 source map 均不存在。
6. 本决策只移动路径和改写显式 import/export，不修改函数体、SQL、transaction、credential/Policy fence、Run/Workflow、Secret、exact replay、错误码或关闭顺序。

被拒绝的方案

• 为四个入口建立四个目录：会把根文件问题变成单文件微目录问题，没有形成领域聚合。
• 把管理入口并回 runtime.ts 或 root export：会让普通 Edge/Standalone runtime 获得短生命周期管理 authority，并扩大低配设备加载面。
• 拆成 bootstrap/management/workflow/secret workspace package：没有独立部署、依赖或生命周期价值， 会突破 19-package 收敛边界。
• 保留旧根 facade 兼容层：public package specifier 本来就稳定，旧源码路径不是公共契约；facade 只会 让 stale dist 继续进入制品。
• 把 adoption 强行放入单文件目录：它已经是明确且大型的公共领域入口，没有同域成员可形成聚合。

接受证据

• Local SQLite 保持 148 个源码文件/46,996 行，root 7→3、nested 141→145、hard cap 7→3；package-boundary schema v2 报告 workspace=19/hard cap=19、compatible=true。
• root/runtime/bootstrap/package-management/Workflow administration/Secret administration 的 export count/digest 分别保持 15/f1884fabfa37efd5、12/daf0cfe03a52f442、 2/868eb03aaaa678a4、9/11d78ae9a2c4066a、1/cbec651a9e47ee76、 1/448b760a835d2b2b。六个 public self-reference 均可解析；clean build 后四组旧根 source/dist/声明/source-map 路径为零。
• 编辑前 55 个 function/class/method 为 4 HIGH/1 MEDIUM/50 LOW、94 direct/206 impacted/4 process hits；编辑后为 5 HIGH/2 MEDIUM/48 LOW、91 direct/150 impacted/4 process hits。风险标签变化来自目录聚类 重分配；最高共享 fence error 仍为 29 direct/32 impacted/0 process，Workflow 流程命中仍只在测试链。
• Local SQLite 192/192；完整 19-package 门退出 0；后端 1,101 tests、1,099 pass/2 skip/0 fail。Edge import、cluster dependency、package boundary、cluster deployment、worker deployment 与 local image 六项审计全部 compatible。
• 十档 artifact 的 package/file/module closure 均未增加，每档仅因嵌套路径增加 345 bytes：Edge/ Standalone 3,549,039/3,549,087，Adopted 4,147,741/4,147,825，Application 4,635,214/4,635,358，AI 4,883,961/4,884,021，Application AI 5,970,208/5,970,364 bytes；最大档距 6 MiB 仍有 321,092 bytes，RSS 全部在对应预算内。
• PostgreSQL 18.4 arm64 physical-streaming HA passed=true：remote_apply、timeline 1→2、旧主 fencing、 pg_rewind 只读同步重入、两个 fresh control replica 与全部 Workflow/Tool/AI gate 全绿， ql3-ha-* container/network/volume 零残留。
• 刷新后 GitNexus 为 42,538 nodes/96,512 edges/1,675 clusters/261 flows；detect-changes all/compare develop 分别为 12 files/31 symbols 与 14/34，均 low/0 affected production process。

后续边界

• adoption.ts、runtime.ts 与 index.ts 是明确公共入口，不以“根文件越少越好”为理由继续移动。
• @qinglong/cluster-postgres 的十个根文件同样是分角色 composition exports；只有出现多个同域成员或公共 specifier 可以直接映射嵌套实现时，才应继续收敛。
• x64/arm64 CI matrix 已定义并有静态负向门，但远端 runner 的实际执行结果仍必须来自 GitHub CI，不能由 本机 arm64 证据替代。
• 联网 production dependency vulnerability audit 因依赖元数据外发权限未获批准，本轮不重跑。