qinglong/docs/adr/ADR-0294-local-sqlite-domain-neutral-persistence-primitives.md

# ADR-0294：Local SQLite 领域中立 Persistence Primitives

- 状态：Accepted
- 日期：2026-08-09
- 关联：D-85、D-87、D-213、D-257、ADR-0276、ADR-0280、ADR-0292、ADR-0293

## 上下文

ADR-0293 已把 Project Policy、Security Audit 与 Local Secret 的状态和事务 authority 从 Run Facade 移到
`src/security/`，但 Security persistence 仍从 `run/runPersistence.ts` 导入 row scalar、query、single-row 和 SQLite
错误映射函数。该依赖不表示 Security 属于 Run，只是历史上这些无状态 SQLite primitive 首先在 Run 文件中出现；继续保留
会让源码目录重新形成 `security -> run` 的领域反向依赖，并使以后调整 Run corruption contract 时意外影响 Security。

当前 primitive 不能直接移动或改名。强制完整 GitNexus 基线为 43,207 nodes/98,365 edges/1,695 clusters/270 flows；
`requiredString`、`requiredInteger` 分别为 CRITICAL（17 direct/125 total、19/124），`queryRows`、
`mapSqliteError`、`singleRow` 也均为 CRITICAL（20/81、17/87、13/67），覆盖既有 Secret `put` 执行流及最多
9 个 module。现有调用方还依赖精确的 `RunRepository*Error` 类型、错误文本、NULL/empty/JSON/Blob 语义和 SQLite busy/
constraint 分类。

## 决策

1. 在既有 `@qinglong/local-sqlite/src/storage/` 下增加 package-private 的
   `sqlitePersistence.ts`。它只依赖 `node:sqlite`，提供 `SqliteQueryRow`、查询参数类型、SQLite driver 错误观察，以及由调用边界
   注入错误 contract 的 scalar/query/single-row primitive factory。
2. 中立层不得导入 Runtime Core 的 Run、Security、Secret 或 Policy 类型，不定义产品级错误，不包含表名、SQL、事务、queue、
   connection 生命周期或领域 normalization。
3. `run/runPersistence.ts` 保留既有导出函数名与签名，作为 Run corruption contract 的兼容适配层；它使用中立 primitive，
   仍逐字产生原有 `RunRepository*Error` 和错误文本。Run Reader/Repository 的调用点不迁移。
4. `security/securityPersistence.ts` 建立独立 Security-side 适配实例，并向 Security Authority Store 提供其所需的 package-private
   helper。为保持 ADR-0293 已冻结的可观察兼容性，本批仍映射成原有 `RunRepository*Error`；这是显式兼容边界，不再来自
   `src/run/`。未来如切换到 `ProjectPolicyUnavailableError`、`SecurityAuditUnavailableError` 或
   `LocalSecretUnavailableError`，必须另立错误迁移 ADR 和 consumer 证据。
5. Security source 不得再 import `../run/runPersistence`。Run 与 Security 可以共享中立实现，但各自拥有错误 contract、row
   mapper、SQL 和领域 normalization。
6. 不新增 workspace package、公开 export、生产 dependency、migration、表、索引、进程、timer、watcher、cache、queue 或
   connection；中立 factory 只创建冻结的函数集合，不持有可变状态。
7. 本批不顺带泛化 Local Owner、Completion Receipt、Plugin Package 或其他目录内同名 helper；是否共享必须按各自 corruption
   contract 单独证明，不能按函数名机械合并。

## 被拒绝的方案

- **把现有 Run helper 原样搬到 `storage/`**：文件路径变了，但中立目录仍泄漏 Run 错误与文本，隐藏而不是消除错误 ownership。
- **让 Security 永久继续 import Run 文件**：保持短期测试通过，却把错误演进和目录依赖绑定在错误领域。
- **复制 helper 到 Security**：会产生两套 SQLite driver 分类和 scalar 行为，后续漂移难以审计。
- **本批立即更换 Security 对外错误类型**：会把依赖方向修复与公开 corruption contract 迁移混在同一批，无法证明行为兼容。
- **新建 workspace storage-common package**：没有独立部署、权限、版本或消费者责任，只会扩大低配设备 importer、lockfile 和
  SBOM。

## 接受条件

1. `src/security/` 对 `src/run/` 的生产 import 为零；中立 primitive 对 Runtime Core 领域 import 为零。
2. Run helper 的导出名、签名、错误类型、错误文本、NULL/empty/JSON/Blob 和 SQLite busy/constraint/operation 行为不变；
   Security 的既有可观察行为也不变。
3. Project Policy、Security Audit、Local Secret、Run Reader/Repository 的定向 corruption/replay/transaction 测试通过，
   Local SQLite 全量、完整 package 与 backend 回归通过。
4. package-boundary、cluster dependency、Edge import、cluster deployment、CloudNativePG 与 local-image 审计通过；19-package
   ledger、公开 exports、生产依赖和部署 closure 不变。
5. 十档 artifact/RSS 门通过；不得为共享 primitive 引入常驻资源或超过 Edge/Standalone 预算。
6. 强制完整 GitNexus 后重查新中立 factory、Run 兼容 adapter、Security adapter 及既有高风险 mapper，并运行
   `detect_changes` all/compare `develop`；出现新产品执行流或影响扩大时不得 Accepted。

## 接受证据

- 新增 169 行 package-private `storage/sqlitePersistence.ts`，只导入 `node:sqlite`；它定义领域中立 row/query value、
  driver error observation 和注入错误 contract 的冻结 primitive 集合。`src/security/` 到 `src/run/` 的生产 import 为零，
  中立文件到 Runtime Core 的 import 为零。
- `runPersistence.ts` 从 551 行收敛到 529 行并保留全部既有导出函数；`securityPersistence.ts` 为 350 行，通过显式薄函数
  暴露 Security-side adapter，使调用图可追踪而不以函数对象 alias 隐藏消费者。新增 4 项 contract 测试逐字验证
  Run/Security 的 scalar、NULL/empty、JSON、Blob copy、duplicate identity、busy/constraint/operation 类型和错误文本。
- Local SQLite 196/196、Local Admin 83/83、Local Owner CLI 104/104、完整 19-package clean build/test 与 backend
  1,110（1,108 pass/2 skip）通过。第一次受限运行中的 loopback `EPERM` 只来自沙箱网络限制；在允许本机 loopback 的同一
  最终源码上完整重跑已全绿。
- cluster dependency、package boundary、Edge import、cluster deployment、CloudNativePG 与 local image 六项审计均
  `compatible:true`。workspace 仍为 19 个 package、768 个 production source、49 个受审根入口和 719 个领域内嵌套实现，
  `singleSourcePackages=[]`；Local SQLite 为 156/3/153。公开 exports、生产依赖、migration、表、索引、进程和部署单元
  均未改变。
- 十档制品/RSS 门全部 compatible。最小 Edge 为 3,635,004 bytes/332 files/48 loaded modules，RSS delta
  12,206,080 bytes；最大 Standalone Application AI 为 6,122,625 bytes/491 files/104 loaded modules，RSS delta
  21,299,200 bytes，均低于各自硬上限。
- 强制完整索引为 43,262 nodes/98,457 edges/1,695 clusters/269 flows。中立 factory 为 LOW（2 direct/19 total，
  0 process）；Run `requiredString`/`requiredInteger` 从混合领域 CRITICAL 降为 MEDIUM（10/24，0 process），Security
  adapter 分别为 CRITICAL（5/99、8/99），风险归属清晰。Run/Security `queryRows` 合计仍为 20 direct/81 total，
  `singleRow` 合计仍为 13/67，没有扩大原基线；全局 flow 从 270 收敛到 269，没有新增产品入口、状态机或运行资源。
- `detect_changes` all/compare `develop` 分别为 12 files/31 symbols 与 14/34，均为 low/0 affected process；QL3
  孵化树大部分仍 untracked，因此以逐符号 impact、完整测试、审计和制品证据为主。
- 按额外授权重新运行 PostgreSQL 18.4 arm64 physical HA Docker 门，`gates.passed=true`：`remote_apply`、timeline
  1→2、旧主先 fencing、双新 control ready、`pg_rewind` 回归同步及完整 Cluster/AI/Workflow gates 全绿；运行后
  `ql3-ha-*` container、volume、network 均为空。该结果是跨部署基线复验，不改变本批 Local SQLite ownership 范围。