pgstore

Overview ¶

board.go —— taskboard.Board 的 PostgreSQL 参考实现。

判据落库形态 ¶

• **认领是读-判-写不可分割**：一个事务里 SELECT … FOR UPDATE 锁任务行， 依次判（不存在 / 终态 / 依赖 / 被活持有），通过才写——两个进程同时认领 同一任务时，输家会在行锁上等到赢家提交，然后读到 claimed 状态 ⇒ ErrTaken。并发正确性由 taskboard.ConcurrentClaim 的共享套件判。
• **令牌与接管代次由存储铸造**：令牌用随机 128 位（跨进程不复用不重合， ABA 封死）；代次 = 该任务已见最大值 + 1，与令牌同一次写落库（同源）。
• **释放 / 完成 / 续期只认令牌**：条件更新 WHERE token = $2，影响行数为 0 即 ErrLeaseLost（迟到持有者放不掉别人的闸）。

到期时刻由**存储自己的时钟**算（可注入）：调用方的时钟与存储的时钟可能 对不上，跨进程时更不能假设一致。

Package pgstore 副作用闸 / 任务认领面 / 进度快照的 **PostgreSQL 参考实现**。

生命周期: Experimental（v0.33.0 定级）——参考实现，随契约套件与参考部署 演进，不承诺任何兼容，升级风险自负；定级理由见 api-lifecycle.yaml，分级 规则见 docs/api-compat.md。

它是什么、不是什么 ¶

这是 examples 里的**参考实现**，不是内核依赖：内核（sideeffect / taskboard / checkpoint）依旧只给契约与判据，不给存储。本包演示的是「把同样的判据落到 一个真实数据库的原子操作上」长什么样——宿主照抄它，比照着契约散文重写， 漂移的概率小一个量级。

它与 examples/reference-runtime（内存版参考实现）是一对：

• 内存版证明「判据本身是对的」（进程内互斥锁即可）；
• 本包证明「判据在**跨进程**下依然成立」（判据归存储，不归进程）—— 用内核的共享契约套件（sidetest / boardtest / RunSinkContract）在 真实 PostgreSQL 上原样跑通，不为任何实现开后门。

三套契约各自的落库形态 ¶

• sideeffect.Store：Acquire 的「三判合一」（已完成 > 结果未知 > 执行中 > 资源被占 > 授予）在一个事务里完成——SELECT … FOR UPDATE 行锁把 「读状态 → 判 → 写」钉成跨进程原子；执行意图与授予（令牌 + 持有者身份， sideeffect.MintHolder 在同一事务里铸造）写在同一事务里。Complete / Renew / MarkUncertain / Abandon / Release 全部三项联查（令牌 + 持有者 + 资源一致），缺一即拒（ErrFenceStale / ErrNotHolder / ErrResourceMismatch）。
• sideeffect.FencedSink：一条带条件的 INSERT … ON CONFLICT DO UPDATE （WHERE seen_fence <= presented）先原子预占，写入体在同一事务里执行； 写入体报错 ⇒ 整个事务回滚 ⇒ 不得部分写。
• taskboard.Board：认领是一个事务里的读-判-写（行锁），令牌与接管代次 在同一次操作里铸造；释放 / 完成 / 续期只认令牌。
• checkpoint.StoreCAS：一条带条件的 upsert（WHERE 持久化序号 < 本次序号）， 影响行数为 0 即判陈旧。

时钟 ¶

过期判定读可注入时钟（sidetest / boardtest 的硬要求）：缺省 time.Now， 经 UseClock 注入。跨进程部署时所有进程共享真实时钟即可；测试注入假时钟时， 存进数据库的时刻与比较用的「当前时刻」同源，判据不变。

数据库连接 ¶

构造函数直接收 *pgxpool.Pool 与 schema 名：本包不管理连接串与凭据， 那是宿主的接线责任。隔离方案是**每个实例一个 schema**（EnsureSchema 建 CREATE TABLE IF NOT EXISTS 一套表），契约套件每个子测试建一份全新实现 ——与「factory 每次构造全新实现」的套件约定对齐。

部署与验证入口 ¶

• 契约 + 故障恢复用例：GAK_PGREF_DSN=… go test ./examples/pgstore/… （见 examples/docker-compose.yml 与 Makefile 的 integration 目标）；
• 冒烟部署：docker compose -f examples/docker-compose.yml up（pgsmoke 服务）。

effect.go —— sideeffect.Store 的 PostgreSQL 参考实现：类型、事务骨架与行读写。

三条判据在库里的落法（与内存版 effectStore 逐条对应） ¶

1. **三项联查**：Complete / Release / Abandon / Renew / MarkUncertain 都在 同一个事务里校验「令牌仍是最新代 + 持有者身份一致 + 租约与动作的资源 一致」。校验与写入在同一事务 ⇒ 任何一步失败都发生在**任何状态被改之前** ——这正是 MarkUncertain「标记写失败必须保住执行意图」的落库形态。
2. **执行意图**：Acquire 的授予（令牌 + 持有者身份）与意图登记写在 同一事务里；意图过期未裁决 ⇒ 同一 Key 转入未知态而非重新授予。
3. **对账占用**：BeginReconcile 与裁决分表字段，占用过期可重入。

原子性来自哪里 ¶

每个方法 = 一个事务 = 若干条 `SELECT … FOR UPDATE` + 条件写。行锁把 「读状态 → 判 → 写」钉成跨进程原子：第二个进程在第一个提交前读到的 永远是旧状态，且会在行锁上等待。这与「一条带条件的 UPDATE」等价， 是契约点名认可的两种形态之一。

锁序恒为「资源行 → 动作行」：所有方法按同一顺序加锁，两个并发事务 不可能交叉持锁（交叉死锁在锁序一致时不存在）。

effect_acquire.go —— Acquire：三判合一的一个事务。

判定顺序是契约里最要紧的一行：**已完成 > 结果未知 > 执行中 > 资源被占 > 授予**。 顺序写反的代价是重复施加：把「结果未知」排到「资源被占」之后，调用方会拿到 contended（以为「晚点重试就行」），于是重试发生、重复施加随之发生。

为什么整段在一个事务里：三判合一的每一步都读同一份状态，行锁保证第二个 进程要么读到判定前的旧状态（然后在锁上等），要么读到判定后的新状态—— 不存在「两个进程同时读到没做过、资源空闲」的窗口。

effect_lease.go —— 凭据一族：Complete / Release / Abandon / Renew / MarkUncertain。

五个方法共用同一套纪律：

• 校验与写入在**同一个事务**里 ⇒ 校验失败即整体回滚，存储侧不剩半截状态；
• 资源行 → 动作行的固定锁序（见 effect.go）；
• 三项联查不过即拒（ErrFenceStale / ErrNotHolder / ErrResourceMismatch）， 拒绝时**不落任何一行**。

effect_reconcile.go —— 对账侧：ResolveUncertain 与 BeginReconcile。

裁决**不校验栅栏**（契约硬要求）：它的依据是**下游事实**，不是持有权—— 原持有者可能已经死亡、租约早已过期，而对账恰恰要在这种情况下进行。 占用与裁决的关系：占用过期可重入（对账者死亡不永久占住）；裁决成功即 清除占用（这次尝试已有结论）。

schema.go —— 连接池构造与建表。

表结构与判据的对应关系（每张表管一件事，见 doc.go）：

• pgref_effect_action Key 级状态（做过没有 / 结果未知 / 执行意图 / 对账占用）
• pgref_effect_resource 资源级状态（这个资源谁占着 / 发第几代令牌）
• pgref_downstream 下游资源（已见最大令牌 + 参考业务数据，FencedSink 的落点）
• pgref_board_task 任务认领面（taskboard.Board）
• pgref_snapshot 进度快照（checkpoint.StoreCAS）

sink.go —— sideeffect.FencedSink 的 PostgreSQL 参考实现（下游栅栏适配）。

原子性要求（实现这条契约的唯一要点） ¶

「比较与写入必须在**同一次原子操作**里完成」——本实现把它落成两件事：

1. **栅栏预占是一条带条件的 upsert**：INSERT … ON CONFLICT (resource) DO UPDATE SET seen_fence = EXCLUDED.seen_fence WHERE seen_fence <= presented。 影响行数为 0 ⇒ 令牌陈旧（ErrFenceStale），此刻**什么都没写**； 影响行数为 1 ⇒ 预占成功，且这行就是「比较 + 更新已见最大」本身。
2. **写入体在同一事务里执行**：ctx 里带上了事务句柄（TxFromContext）， 写入体的业务写入必须用 ExecWithin / QueryRowWithin 走这个事务。 写入体报错 ⇒ 整个事务回滚 ⇒ 预占与已写的业务数据一起消失—— **不得部分写**。

反面教材（为什么不能三步写） ¶

「先读已见最大 → 判断 → 再写入」三步各自独立提交时，两个持有者可以同时 读到同一个旧值、双双通过检查，然后先后写入——更旧的那次写入反而后落， 覆盖掉更新的。栅栏形同虚设。这条失败形态在 sideeffect 包内有确定性用例 （TestNonAtomicSinkIsCaught）与共享套件的并发场景双向钉住。

snapshot.go —— checkpoint.StoreCAS 的 PostgreSQL 参考实现。

契约只有两条，落库形态也是两条：

• SaveIfNewer：一条带条件的 upsert（WHERE 已持久化序号 < 本次序号）， 影响行数为 0 ⇒ 判陈旧（ErrStaleSeq），**不写入**；Seq == 0 一律先拒 （它不是一次真实提交，放它落库等于给了它唯一能覆盖既有快照的写）。 并发提交同一 run 时，两个进程的条件更新在行锁上排队，只有序号更大的 那个落库——单调闸在存储侧成立，不在进程侧。
• Load：无记录返回 ErrNotFound（**不得**返回零值 + nil——那会被上游 误判成「这个运行从没跑过」从而全量重跑）。