qinglong/docs/adr/ADR-0292-local-sqlite-run-persistence-support-module.md

# ADR-0292：Local SQLite Run Persistence Support 内部模块

- 状态：Accepted
- 日期：2026-08-09
- 关联：D-85、D-87、D-213、D-257、ADR-0007、ADR-0069、ADR-0280、ADR-0290、ADR-0291

## 上下文

ADR-0291 已把具名 `LocalSqliteRunReader` 移到独立文件，但 `runRepository.ts` 仍同时持有 Run/Attempt/Event/Retry
列声明、SELECT/INSERT/UPDATE SQL builder、row codec、SQLite driver error mapping、有界 query helper、Transaction、
Security/Secret 映射和产品 Facade。Reader 为避免复制，通过一个冻结 support 对象从 Facade 文件接收这些函数；这只是
安全的过渡边界，并没有消除反向依赖。

强制完整 GitNexus 索引表明五个 scalar/JSON codec 为 CRITICAL，最大 13 direct/88 total、2 processes/7 modules；
`mapSqliteError`、`queryRows`、`singleRow` 和 SQLite code/number 解码为 HIGH，最大 17 direct/46 total、1 process/
4 modules。Facade 仍为 CRITICAL（30 direct/63 total），Reader 为 HIGH（15/40），Transaction 为 HIGH（15/37）。
因此本批次必须是逐字语义保留的模块抽取，不能同时泛化不同领域的 SQLite codec。

## 决策

1. 在既有 `@qinglong/local-sqlite/src/run/` 下新增 package-private `runPersistence.ts`，集中：
   - Run/Attempt/Event/Retry column metadata 和 SELECT/INSERT/UPDATE SQL 常量；
   - write value normalization、row scalar/JSON/enum/blob/boolean codec 与 Run record 映射；
   - SQLite error code/number/message 分类、`mapSqliteError`、event payload 上限；
   - `queryRows` 和 duplicate-identity `singleRow`。
2. 所有被迁移函数体、错误类型、错误文本、NULL/undefined/empty-string 处理、JSON parsing、enum 集合、column 顺序、
   SQL 文本和 payload byte 计算逐字保持。不得借重构修改协议或“统一”错误。
3. `LocalSqliteRunReader` 直接导入 persistence support，不再接收函数对象；构造器恢复只接收同一 `DatabaseSync`。
   `LocalSqliteRunTransaction` 继续继承 Reader，Facade 继续通过唯一 `LocalSqliteOperationAuthority` 调度两者。
4. `LocalSqliteRunRepository`、Transaction 和现有 Security/Secret 映射只改为 import 同一 support。公开构造器、
   runtime-core ports、root/subpath exports、事务边界、close/error mapping 和消费者不变。
5. 新模块不得从 `package.json#exports`、`index.ts` 或 `runtime.ts` 导出，也不得创建 connection、transaction、queue、
   timer、watcher、cache、listener 或后台工作。
6. Completion Receipt、Task Definition、Owner、Tool 等模块的相似 helper 具有不同 empty/null/error 语义，本批次不合并；
   后续只有在先冻结共同 contract 后才可共享，不能按函数名相同机械去重。
7. 不新增 workspace package、生产 dependency、migration、表、索引、进程或部署单元；19-package ledger 与 Edge/
   Standalone 制品和 RSS 上限保持不变。

## 被拒绝的方案

- **建立 package-wide 万能 row codec**：不同领域对空字符串、NULL、错误类型和错误文本要求不同，会造成静默语义漂移。
- **继续由 Facade 向 Reader 注入函数对象**：可以运行，但让只读模块的基础依赖反向由产品 Facade 组装，长期难以演进。
- **复制 support 到 Reader/Transaction**：会复制列顺序、SQL projection 和 normalization，读写路径可能分叉。
- **把 support 拆成新 workspace package**：没有独立部署、权限、依赖或消费者 closure，只增加低配设备 importer/SBOM。
- **同时移动 Transaction 或 Security/Secret authority**：会把机械 support 抽取扩大为事务 ownership 重构，无法归因回归。

## 接受条件

1. 原 support 函数和常量只存在于 `runPersistence.ts`，Reader/Fascade/Transaction 没有复制；源码与错误文本保持等价。
2. Reader 恢复单参数构造，Transaction 写方法与 Facade BEGIN/COMMIT/ROLLBACK、enqueue/close 完全不变。
3. Run、startup recovery、dispatch/control、Security Audit、Project Policy、Local Secret 和 corruption/error 定向测试通过；
   Local SQLite 全量零回归。
4. 完整 19-package clean build/test、backend、六项架构/部署审计及十档 artifact/RSS 门通过；package 仍为 19 个、
   `singleSourcePackages=[]`，公开 exports、依赖与 migration chain 不变。
5. 强制完整 GitNexus 索引后重查全部 CRITICAL/HIGH helper、Facade/Reader/Transaction 和执行流，再运行
   `detect_changes` all/compare `develop`。如果 support 丢失可索引性、生产流程扩散或风险上升，ADR 不得 Accepted。

## 接受证据

- `runPersistence.ts` 为 551 行，成为 Run 子域唯一的 column/SQL/codec/error/query support；`runRepository.ts`
  从 1,990 行降至 1,457 行，`runReader.ts` 从 762 行降至 667 行。Reader 恢复只接收同一 `DatabaseSync`，旧
  `LocalSqliteRunReaderSupport` 注入对象已删除；Transaction 写方法、BEGIN/COMMIT/ROLLBACK、Facade enqueue/close、
  runtime-core port 和 package exports 均未改变。
- 跨 Run/Startup/Dispatch/Control/Execution Revision/Security Audit/Policy/Secret 的定向回归 74/74、Local SQLite
  192/192、完整 19-package clean build/test 与 backend 1,110（1,108 pass/2 skip）通过；cluster dependency、package
  boundary、Edge import、cluster deployment、CloudNativePG 与 local image 六项审计均 `compatible:true`。
- workspace 保持 19 个 package、765 个 source、49 个受审根入口和 716 个领域内嵌套实现，
  `singleSourcePackages=[]`；Local SQLite 为 153/3/150。没有新增生产 dependency、migration、表、索引、进程、
  部署单元或公开 specifier。
- 十档制品/RSS 门全部 compatible。最小 Edge 为 3,623,406 bytes/329 files/45 loaded modules，RSS delta
  11,599,872 bytes；最大 Standalone Application AI 为 6,111,027 bytes/488 files/101 loaded modules，RSS delta
  21,250,048 bytes，均低于硬上限。
- 强制完整索引为 43,173 nodes/98,227 edges/1,693 clusters/265 flows。五个既有 scalar/JSON helper 仍为 CRITICAL，
  最大 `requiredString` 17 direct/108 total、`requiredInteger` 19/107；`mapSqliteError`、`queryRows` 和 SQLite
  code/number decoder 仍为 HIGH，最大 20/70，`singleRow` 为 MEDIUM（13/42）。直接调用数比 support-object 基线更
  完整，是删除间接注入后图谱恢复可见性，不是新消费者或执行流；其风险等级没有升级。Facade 为 CRITICAL（30/64）、
  Reader 为 HIGH（15/40）、Transaction 为 HIGH（15/38），全部仍为 0 affected process；其余 persistence helper
  最高 MEDIUM。
- 本批次只改变 Local SQLite package 内源码组织，未触及 PostgreSQL、Cluster、migration 或 HA 状态，因此不重复执行
  与变更无关的物理 PostgreSQL HA；对应结构、依赖和部署审计已覆盖其不变性。
- `detect_changes` all/compare `develop` 分别为 12 files/31 symbols 与 14/34，均为 low/0 affected process；QL3
  孵化树大部分仍 untracked，因此该结果只作为逐符号 impact、完整测试、审计与制品门的补充证据。

## 后续边界

- Security/Secret authority 仍在 Run Facade 内是下一项真实职责问题，但必须先按共同授权事实和事务围栏建模。
- 其他领域的重复 scalar helper 只能按明确 contract 分组迁移，不能把本 ADR 当成全 package 泛化授权。