qinglong/docs/adr/ADR-0298-local-sqlite-root-runtime-and-adoption-ownership.md

# ADR-0298：Local SQLite 根 Runtime 与 Adoption 实现归属

- 状态：Accepted
- 日期：2026-08-09
- 关联：D-05、D-06、D-17、D-85、D-87、D-97、D-213、D-257、ADR-0063、ADR-0098、ADR-0276、ADR-0296、ADR-0297

## 上下文

schema v4 根行数棘轮显示 `@qinglong/local-sqlite` 仍有 3 个 root source、1,203 个审计行。`index.ts` 只有 31 个审计行，
是聚合公开导出的真实门面；`runtime.ts` 与 `adoption.ts` 分别有 432 与 738 个可见代码行，承载长期 Runtime Database
Composition 和短生命周期 Legacy Adoption Authority。两者有明确的权限、生命周期与领域归属，却继续以“公开入口”为由平铺在
package root，会让目录结构掩盖常驻与短生命周期 authority 的隔离关系。

这两个能力已经通过 `@qinglong/local-sqlite/runtime` 与 `@qinglong/local-sqlite/adoption` 两个稳定 subpath 暴露，物理 `dist`
路径并不是调用方契约。它们也不具备独立部署、依赖或版本生命周期，另拆 workspace package 会扩大路由设备的 importer、packlist、
SBOM 和构建拓扑。

移动前 GitNexus 显示 `LocalSqliteRuntimeDatabase` 为 MEDIUM（10 direct/24 total/0 process），
`openLocalSqliteRuntimeDatabase` 为 LOW（1/3/0）；`LocalSqliteLegacyAdoptionPublisher` 与
`openLocalSqliteAdoptionDatabase` 均为 LOW（2/6/0 与 1/1/0）。没有 HIGH 或 CRITICAL 风险。

## 决策

1. 保留根 `src/index.ts` 作为唯一聚合门面；Runtime composition 原样归入
   `src/runtime/runtimeDatabase.ts`，Legacy Adoption authority 原样归入
   `src/adoption/legacyAdoptionDatabase.ts`。
2. 不保留根 wrapper。`package.json#exports` 直接把公开 `/runtime` 与 `/adoption` subpath 映射到嵌套编译产物；公开
   specifier、导出 symbol、错误 class identity、lazy loading 和运行行为保持不变。
3. `src/storage/database.ts` 作为开发工具兼容入口直接导出新的 Runtime domain module。package tests 通过公开 self-reference
   验证 Runtime 入口；仓库根物理 Edge 脚本不是 workspace importer，显式绑定新嵌套产物。
4. package ledger 将 Local SQLite 的 `rootSourceFileHardCap` 从 3 降为 1、`rootSourceLineHardCap` 从 1,203 降为 31；
   回归测试同时冻结 source/root/nested 计数、manifest targets 与旧根文件不存在。
5. 不新增 workspace package、生产依赖、migration、数据库对象、connection、transaction、queue、timer、watcher、listener、进程或
   部署单元。

## 被拒绝的方案

- **保留两个根 facade**：会留下无独立语义的转发文件，使根文件数棘轮失去约束力。
- **按 Runtime 与 Adoption 各拆一个 package**：二者仍共享同一 SQLite adapter、operation authority 与发布节奏；拆包只增加低配设备成本。
- **本批同时拆分 738 行 Adoption publisher**：目录归位能证明路径之外零行为变化；同时重排事务、validation 和 row codec 会扩大授权与原子性审查面。
- **继续容忍 1,203 行 hard cap**：公开 subpath 不要求实现位于根目录，提高或冻结旧上限没有架构价值。

## 接受条件

1. Local SQLite 保持 156 个 source，root 仅有 `index.ts`/31 审计行，nested 153→155；workspace 保持 19 package、768 source，
   root 45→43、nested 723→725。
2. `/runtime`、`/adoption` 和根 export symbol 保持，Local SQLite 及完整生产消费者通过 clean build/test。
3. Runtime lazy import、migration exclusion、Adoption 单事务/围栏/重放行为继续由既有测试覆盖，旧根私有产物引用清零。
4. 完整 packages/backend、四项架构审计和十档 artifact/RSS compatible；基础 Edge 不获得 Adoption authority。
5. GitNexus 不出现新增产品流程，`detect_changes` 保持 low/0 affected process。

## 接受证据

- package boundary schema v4 报告 Local SQLite 为 156 source、1 root/31 root lines/155 nested；workspace 仍为 19 package、
  768 source、43 root、725 nested，`singleSourcePackages=[]`。边界 fixture 明确验证两个公开 target 与旧根文件不存在。
- Local SQLite 196/196，完整 19-package clean build/test 通过；backend 1,112 项为 1,110 pass/2 skip/0 fail。cluster
  dependency、package boundary、Edge import、local image 四项审计 compatible。
- 十档 artifact/RSS 全部 compatible。基础 Edge 为 3,635,197 bytes/332 files/48 loaded modules；最大 Standalone
  Application AI 为 6,123,790/491/104，均低于门限。clean build 后旧根 `dist/runtime*`、`dist/adoption*` 不进入 packlist。
- 强制 GitNexus 为 43,302 nodes/98,525 edges/1,696 clusters/269 flows。嵌套 manifest subpath 不被当前索引器反向解析为
  跨包 direct edge，因此移动后的四个关键符号均显示 LOW/0 process，不把降低后的 direct count 作为兼容证据；移动前 blast radius、
  完整 consumer 测试与制品门共同承担验证。`detect_changes` all/compare `develop` 分别为 12 files/31 symbols 与 14/34，
  均 low/0 affected process。
- 本批没有修改 SQL、migration checksum、生产 dependency 或 Cluster 状态；按维护者额外授权，仍重跑 PostgreSQL 18.4 arm64
  physical HA Docker 门，`gates.passed=true`。证据覆盖 `remote_apply`、timeline 1→2、旧主 promotion 前 fencing、
  `pg_rewind` 后只读 synchronous rejoin 与两个新 control ready；结束后 `ql3-ha-*` container、volume、network 均为空。