qinglong/docs/adr/ADR-0041-postgresql-run-repository-contract-parity.md

ADR-0041：PostgreSQL Run Repository 契约对等

• 状态：Proposed
• 日期：2026-07-19
• 关联：QL-RFC-0001、ADR-0001、ADR-0037、ADR-0038、ADR-0039、ADR-0040

上下文

pg-0002-run-core 建立了 Run、RunAttempt 和 RunEvent，但应用层 RunRepository 还要求 durable RunRetryPolicy：

• 随 Run admission 保存重试安全声明；
• 按 version compare-and-set 推进下一次重试时间；
• 在控制面重启后继续判断 lost retry；
• 与 Run/Attempt/Event 处于同一数据库事务边界。

如果 PostgreSQL adapter 省略 RetryPolicy，cluster-control 只能实现一个缩小版 Repository。上层 service 会被迫按方言分叉，或在内存中保存唯一重试事实，两者都违反跨 Profile 的 Runtime Kernel 和数据库事实源不变量。

另一个差异是 SQLite 兼容 contract 默认构造 execution_owner=legacy，而 PostgreSQL cluster schema 正确地只允许 runtime。为了让 contract 真正跨方言，测试数据必须参数化 owner，不能放宽 cluster 约束。

决策

1. control-core v2 表示完整首版 RunRepository 存储能力

新增不可变 migration pg-0003-run-retry-policy，在同一 migration 事务中：

1. 创建 ql3.run_retry_policies；
2. 创建有界 due index 和 Run lost-retry index；
3. 只允许从精确的 control-core v1 推进到 v2；
4. 写入 capability：

{
  "contract_name": "control-core",
  "contract_version": 2,
  "migration_id": "pg-0003-run-retry-policy",
  "capabilities": {
    "run_core": 1,
    "run_retry_policy": 1
  }
}

若 v1 capability 的 version、migration ID 或 JSON 能力不精确匹配，migration 必须失败并回滚。不得修改 pg-0001/0002 的 SQL 或 checksum。

2. RetryPolicy 与领域约束保持一致

PostgreSQL 表固定保存：

• max_attempts 1–16；
• retry_on_lost；
• unknown/idempotent/deduplicated safety；
• 0–86400000 ms 且 max 不小于 base 的 backoff；
• nullable、非负的 next_attempt_at_ms；
• version、created/updated 时间与 Run 外键。

删除 Run 时 RetryPolicy 可级联删除；runtime role 对该表只有 SELECT/INSERT/UPDATE，没有 DELETE，常驻进程也不是 owner。

3. 公共端口不直接依赖 pg

@qinglong/runtime-core 提供 driver-neutral PostgresPool/Client/Queryable 结构接口、Run domain、Repository port 和稳定错误契约。独立 @qinglong/cluster-postgres 同时拥有 PostgreSQL SQL adapter 与真实 pg.Pool binding；公共 core 不含 SQL、driver 或具体 Profile。

因此：

• edge/standalone 根 importer 不安装或加载 pg；
• Repository SQL、row codec 和事务边界在 cluster adapter 内评审，稳定错误与端口语义由 runtime-core 定义；
• driver connection、TLS、pool sizing、type parser 和 shutdown 属于 cluster package。

4. 每次业务事务使用一个 client

transaction(work) 必须：

1. 从 Pool 取得一个 client；
2. BEGIN 并使用 READ COMMITTED；
3. 设置 transaction-local statement、lock 和 idle-transaction timeout；
4. 在同一 client 上完成全部 Repository work；
5. COMMIT，失败时 best-effort ROLLBACK；
6. 始终 release client。

work callback 抛出的业务错误必须原样返回；BEGIN/config/COMMIT 的 driver 错误映射为稳定 Repository error。不能在一个事务中混用 pool.query() 与 transaction client。

5. CAS、bigint 和唯一错误 fail closed

• Run CAS 精确匹配 id + expected version，新 version 必须恰好加一；
• Attempt CAS 精确匹配 id + status + callback_sequence；
• RetryPolicy CAS 精确匹配 run_id + expected version，新 version 必须恰好加一；
• affected rows 只能是 0 或 1，多行视为存储损坏；
• PostgreSQL bigint string 只能转换为 safe integer，越界或非法值不得静默截断；
• RunEvent JSON 必须是 object，序列化后仍受 16 KiB 上限；
• 只将已知 idempotency、Attempt number、Event sequence/dedupe constraint 映射为稳定 duplicate error；其他 SQLSTATE 23 归为 constraint error；serialization/deadlock/lock/connection shutdown 归为 retryable busy。

6. 共享 contract 必须覆盖完整端口

RunRepository contract 至少验证：

• Run/Attempt/Event 原子写入与失败回滚；
• Run/Attempt CAS；
• RetryPolicy insert/read/version CAS；
• 稳定 duplicate error；
• 有界 Event 与 cancellation recovery page；
• oversized payload 在 SQL 前拒绝。

contract 接受 defaultExecutionOwner：SQLite 兼容 adapter 使用 legacy，PostgreSQL 使用 runtime。不得建立删减 PostgreSQL 专属 contract 来规避端口能力。

当前孵化状态

next 已具备：

• pg-0003-run-retry-policy、control-core v2、6 表/18 索引严格 schema contract；
• readiness 对 capability v2、RetryPolicy 表和最小权限矩阵的检查；
• 本机一次性 PostgreSQL 13 对三条 migration、deferred history/capability 和最终表集合的真实 DDL/事务 smoke；
• 本机 PostgreSQL 服务端已对 Repository 生成的 13 条参数化读写/CAS SQL 执行 PREPARE，验证占位符和参数类型推断；该检查曾发现并推动 pg-0003 增量补齐 runs.legacy_cron_id；
• 独立 @qinglong/runtime-core 的 Run domain、RetryPolicy、Repository port 和稳定错误契约；
• 独立 @qinglong/cluster-postgres 的 PostgreSQL Run Repository、lazy openDatabase() 与 package-local fake-client tests；
• 独立 @qinglong/cluster-control 组合根已把 readiness、真实 Repository 创建、activation 与 Pool close ownership 串联；
• transaction/CAS/row codec/SQLSTATE/payload 的 fake-client 测试；
• 扩展后的 SQLite RunRepository contract，首次真实覆盖 RetryPolicy。

共享 contract 允许每个 adapter 注入自己的错误 constructor/常量，避免 legacy 根兼容副本与 runtime-core package 因 JavaScript class identity 不同而产生伪失败；默认仍保持 SQLite legacy contract 不变。独立 @qinglong/cluster-postgres 已在本机 PostgreSQL 13 上用真实 driver 运行完整共享 Repository contract 和 migration/runtime 双角色权限验证；PostgreSQL 16/18 × x64/arm64 matrix 已接入 CI。远端矩阵成功证据、双连接竞争/failover 和完整 production control-plane stack 仍未完成，因此 cluster-control 继续保持 production unreachable。

影响

正面影响：

• cluster-control 不需要缩小版 Repository 或内存 RetryPolicy；
• SQLite/PostgreSQL 共享同一应用层事务和 CAS 语义；
• bigint 与 driver error 不泄漏为不稳定平台行为；
• edge 依赖隔离不因 PostgreSQL adapter 进入核心源码而失效。

代价与风险：

• SQL row codec 字段较多，schema、migration 和 contract 必须保持 lockstep；
• fake client 只能证明编排和映射，不能替代真实 PostgreSQL 并发语义；
• READ COMMITTED 下的正确性依赖所有状态写继续使用显式 CAS；
• concrete Pool 必须配置连接级 read timeout/type parser/shutdown，并接受 PostgreSQL 16/18 矩阵验证。

未选择的方案

1. PostgreSQL 暂不保存 RetryPolicy：破坏端口和恢复事实源，拒绝。
2. 放宽 cluster execution owner 为 legacy：把 2.x 兼容 ownership 带入集群，拒绝。
3. 在核心根包直接依赖 pg：破坏 edge 安装隔离，拒绝。
4. 所有 bigint 直接 Number()：可能静默丢精度，拒绝。
5. 所有 23505 都映射为同一种 duplicate：掩盖主键或未知约束损坏，拒绝。
6. 用 SERIALIZABLE 代替所有 CAS：增加重试成本且不能替代领域 version/fencing，拒绝。

验证要求

• pg-0001/0002 checksum 不变，v1 数据库只能由 pg-0003 推进到 v2；
• capability 漂移时 pg-0003 全事务回滚且不留下 RetryPolicy 表/history；
• schema readiness 精确验证 6 表、18 索引、39 个 CHECK、7 个 FK 和六表权限矩阵；
• SQLite 与 PostgreSQL 均运行同一完整 RunRepository contract；
• PostgreSQL 16/18 上验证 transaction rollback、Run/Attempt/RetryPolicy CAS 和 duplicate mapping；
• 两个 Pool client 竞争时只有一个 CAS 获胜；
• statement/lock/idle timeout 和 serialization/deadlock 映射为 bounded retryable error；
• bigint 越界、非法 enum、非 object JSON 和多行 identity 结果全部 fail closed；
• edge import/tarball/SBOM 审计继续证明未包含 pg/Drizzle/cluster package。