commitgate

Overview ¶

Package commitgate 环节终态的独占提交闸：同一环节的终态只允许被提交一次。

生命周期: Stable（v0.33.0 定级）——只允许 additive 变更（新增导出符号 / 新增方法且给零值默认实现 / 新增错误值）；改签名、改语义、改默认值、 删导出符号都算 breaking，判定规则与变更流程见 docs/api-compat.md， 逐包理由见 api-lifecycle.yaml。

它防的是什么 ¶

本仓的 statemachine 是**纯谓词**：CanTransition / MustTransition 只回答 「这次迁移合不合法」，不回答「有没有人已经提交过了」。当编排把一个环节拆成 两条并发分支推进时，两条分支会各自通过同一个纯谓词检查，各自把活干完， 各自提交终态——**没有任何一层会发现这件事发生过**。

这不是理论形态。eventbus 里有 EventChainParallel（并行子图起跑标记）， 并行分支的编排语义是宿主在跑的；一旦宿主并行化，「两个分支都以为自己赢了 同一个环节」就从「写不出来」变成「写得出来且无人拦截」。

checkpoint.SeqGate 挡不住这个：它按 RunID 排**快照序号**，只管「不倒退」。 两个分支先后提交 seq=5 与 seq=6 是完全合法的递增，两个都会被接受，后写的 覆盖先写的——而先写的那条分支的副作用早已发生。它能排序记录，排不出 「有两条分支都以为自己赢了」。

为什么不是放进 statemachine / checkpoint 里 ¶

• statemachine 自我声明是「纯函数件」，零依赖。给它加带锁的有状态闸， 是把两个性质相反的东西塞进一个包，调用方就无法再按性质选用。
• checkpoint 管的是**崩溃恢复**（快照存取 + 续跑判定）；本包管的是 **并发执行**。两者都在说「编排推进的正确性」，但故障形态与恢复手段 完全不同，混在一处会让两边都变得难推理。

与 checkpoint 的关系 ¶

两者互补，不是替代：SeqGate 管快照序号单调，本闸管终态独占。一个环节的 推进要先过本闸拿到终态独占权，再由 SeqGate 保证快照不倒退。

必须成对使用：Commit 与 Release ¶

与 SeqGate 同一处陷阱：**落库失败时必须 Release**，否则该环节的闸被永久占住， 这个环节从此再也无法提交终态——不是「多花一个序号」，是彻底卡死。

正确顺序（用 Acquire + ReleaseLease——凭唯一令牌释放，承诺无条件成立）：

lease, err := g.Acquire(c)              // 抢终态独占权
if err != nil {
    return err                          // 抢不到就别干后面的活
}
if err := store.Save(ctx, snap); err != nil {
    g.ReleaseLease(lease)               // 落库失败必须回滚
    return err
}

旧接口 Commit + Release(c Commit) 仍在，但它靠 (status, branch, seq) 认人， 而那三元组不唯一（并行分支同名、重试同一份快照时逐字相同）——迟到/重复的 Release 会把别人的闸放掉。分支可能同名或会重试的场景请用上面的凭证路径。

终态判定由宿主注入 ¶

环节状态的词表属宿主（statemachine 那一组常量只是本仓的一份示例实现）， 故 IsTerminal 由宿主注入。本包只管「独占」，不认任何状态取值。

状态在 Store 接缝之后（issue #145 多副本部署） ¶

闸的判定（词表、空引用、错误构造）在 Guard；已提交记录与原子占用在 Store 接缝之后——缺省进程内参考实现 NewMemoryStore，多副本宿主注入自己的 跨进程实现（NewGuardWithStore）。跨进程硬要求（Claim 原子、**令牌由存储 铸造**）见 store.go 文件头；判定逻辑不因换存储而有第二份。

store.go —— 终态记录存储接缝（issue #145 多副本部署）。

为什么要把状态抽出来 ¶

原实现把判定与状态焊在一起（mu + done map）：闸的判定语义正确，但状态只 活在本进程里——副本 A 抢到的终态独占，副本 B 看不见，两副本可以同时赢得 同一个环节的闸（「同一 (run, 环节) 终态只提交一次」只在单进程成立）。 抽成 Store 之后：**判定逻辑（词表判定、空引用拒绝、错误构造）留在 Guard， 跨进程状态与原子占用归存储**——与 sideeffect / coord 同一条分工。

跨进程实现的硬要求（原子性契约） ¶

• **Claim 必须原子**：多副本并发 Claim 同一 Ref，恰好一个 claimed=true。 DB 形态 = 唯一索引上的 `INSERT ... ON CONFLICT DO NOTHING`（或事务内 先查后插 + 唯一约束兜底）；「先查后插」的两步形态会把赢家电窗口 重新打开，正是本闸要防的那件事。
• **Token 由存储铸造**（Claim 返回的 Record 带出）：占用令牌必须跨进程 唯一，否则副本 B 铸出与副本 A 迟到的 ReleaseLease 相同的令牌时， A 的迟到释放会放掉 B 的闸——这与 commitgate 自己踩过的「三元组不唯一」 是同一个坑，只是从进程内挪到了进程间。DB 形态 = 序列/雪花 id。
• **ReleaseToken 条件删除**：只删令牌匹配的记录（`DELETE ... WHERE ref=? AND token=?`），不匹配返回 released=false。

进程内参考实现 ¶

NewMemoryStore：单进程成立，**不得上生产**（跨进程原子性与令牌全局唯一 它都给不了）。职责是把判定逻辑垫在契约之下让契约可测——与 coord 的内存 后端同口径。