Documentation
¶
Overview ¶
finalize.go —— 终态写入 + 终态事件的同事务与 Outbox 补做(issue #272)。
复现结论(先复现再定性) ¶
旧路径的动作序是「ConvergeCAS → CloseBracket → Pub」。ConvergeCAS 的 宿主实现原子完成终态写入与结算,但 Pub 是 fire-and-forget:发布失败时 会话已经终态、事件永久缺失,而会话不再出现在 running 列表里,下一轮 扫描也不会再发。TestSettlementEventSplitReproduced 把这条分裂钉成可跑 事实 ⇒ **坐实**(只实现 Store 的宿主)。
修法:Finalize Intent + Outbox ¶
- FinalizeStore.Finalize:条件迁移 + 结算 + 终态事件行**同一事务**; 返回 false = 他方已处理(零写入,不重复写 Outbox 行);
- FlushFinalizeOutbox:逐行投递,成功才标记已投递;投递/标记失败时行 保留,下一轮或进程重启后补做;
- FinalizeEvent.ID 稳定(finalize:<session>:<terminal-status>),重放 使用同一 ID ⇒ 订阅方可按 ID 去重,投递是至少一次而不是「可能丢」。
未实现 FinalizeStore 时 ¶
仍走旧路径(ConvergeCAS + Pub),但 FinalizeGuarantee 如实报告 Atomic=false / ConfirmedDelivery=false。这是**显式降级**:本包不假装 「终态事件归宿主」就等于边界清楚——状态与事件的分裂可以被观测到。
Package reconcile 启动孤儿对账与心跳租约死主回收:非计划死之后,上一具 进程尸体名下的在途编排会话怎么收敛(issue #165)。
生命周期: Experimental(v0.38.0 定级)——三路判定与 Store 接缝刚下沉, 形状会随宿主适配(bianque recovery 三入口)的接线反馈调整;升级风险自负。
问题形态 ¶
多副本部署下进程死掉后,它名下 running 的会话**不会自行推进**——会话卡 running、后继输入只进队列无人消费(上一进程已死,没人再消费队列)。drain 的包注释两处明写「强制路径按宿主的进程停机分支处理(不写终态,**留给启动 对账**)」「排水超时:强制中断(**留启动对账收敛**)」——本包正是 drain 显式留给宿主、内核至今空缺的那半边:**drain = 计划内停机,reconcile = 非计划死,成对件**。
三路判定的语义差异 ¶
三路收敛动作完全一致(见 reclaim),差别全在「凭什么说它死了」:
- **启动锚点路**(RecoverBootOrphans):进程启动即替代同 instanceID 的 上一具尸体——此刻名下 running 会话**定义性地是孤儿**(上一进程已死, 不会再产出任何事件),所以**无须等事件静默**(常规路缺省 10m)才定性。 旧路径下这段窗口正是「后继输入排队死锁」的体验来源:会话卡 running、 注入只进队列无人消费。判据只剩一条:最后事件早于本进程启动锚点 (boot 后仍有事件产生 = 本进程或同标识存活进程在推进,**天然免检**)。
- **常规路·事件静默子路**(owner=本副本/空):没有启动锚点可借(进程 活着、可能正是它自己在推进),只能等「超阈无任何事件」——活跃编排即 使在长步骤期间也有进度事件在持续产生,静默超阈才是死亡证据。本副本 **不适用**心跳免检:心跳新鲜的「新进程」没有旧编排的取消句柄,自副本 走静默恰是重启孤儿的安全网。
- **常规路·心跳租约子路**(owner=他副本):先看心跳租约——心跳新鲜 (含租约刚过期的重启重打宽限窗)则**免检**(活编排名下不等静默); 租约过期则**不等事件静默立即回收**(死副本的回收从「等满 30m 静默」 提前到「租约过期+宽限」);无心跳行(存量版本副本/心跳面读失败降级) 回落事件静默(更宽的 DeadOwner 阈值)。长步骤期间事件可能静默数分钟, 心跳是**主动续约**——租约路存在的意义就是让存活副本名下的会话不被他 副本按静默阈值误收。
误收面(如实声明,issue (e) 原文) ¶
双进程重叠窗口的静默长步骤存在误收面(常规路径有 recoverStall 缓冲)—— 生产单副本 rsync 发版(杀旧起新无重叠)不受影响;conf cluster.recover_boot_grace 正值=额外宽限(last_event < boot-grace 才收), 负=整体关闭(回落纯静默路径)。
closed_by 归因 ¶
每次收敛都带一个归因标识(Cause.By,与宿主 turn 括号的 closed_by 同值): `boot-reconcile` / `recovery` / `recovery:dead-owner` / `recovery:dead-lease`。 它回答「这次是谁、按哪条路把它收掉的」——审计与排障靠它分辨「发版重启的 正常收割」与「他副本心跳丢失的死主回收」,**不许把四条路写成同一个标识**。
终态事件与结算:FinalizeStore + Outbox(issue #272) ¶
旧 Store 路径能保证「终态写入 + 结算」原子(ConvergeCAS 的宿主实现), 但终态事件是 **ConvergeCAS 之后** 的独立 Pub:发布失败时状态已终态、 事件永久缺失,而会话已不在 running,下一轮扫描不会再发——本包用 TestSettlementEventSplitReproduced 把这条分裂钉成可跑事实(结论:坐实)。
修法不是给 Pub 加重试(进程死了重试也无处可存),而是把**终态事件变成 与终态写入同一事务的 Outbox 行**:
- Store 可选实现 FinalizeStore:Finalize 原子完成「条件迁移 + 结算 + Outbox 行写入」,返回 false = 他方已处理(零写入);
- 投递由 FlushFinalizeOutbox 承担:成功才 MarkFinalEventDelivered; 投递/标记失败时行保留,下一轮或进程重启后幂等补做(Event.ID 稳定, 订阅方按 ID 去重 ⇒ 至少一次投递、不丢不重复生效);
- 未实现 FinalizeStore 的宿主仍走旧路径,FinalizeGuarantee 会如实报 Atomic=false / ConfirmedDelivery=false——**降级必须是可查事实**, 不能把「终态事件归宿主」写成一句注释就当作边界清楚。
CloseBracket(turn 括号)仍不在这条事务里:它是审计面的轮边界,不是 终态事实本身;失败并回聚合错误,但终态事件不因它停摆(issue #184 口径)。
划界(与既有同域包互指;issue #165 划界段逐条) ¶
- **vs `checkpoint`**(AGENTS.md 已定案不接,恢复语义相反):checkpoint 是「续跑而非重放」;本包是 **deny-by-default 收敛为 failed、不重放 任何步骤**(重放=重复环节与二次审批)。方向相反、互不替代——本包不做 快照存取与 BuildPlan,checkpoint 也答不了「boot 锚点 / 事件静默 / 心跳租约」三路判定。是**补充**。
- **vs `drain`**:见上「成对件」。drain=计划内、reconcile=非计划死。
- **vs `worker.Recover`**:worker 接管任务板上过期认领的任务并**重跑**; 本包收敛的是**编排在途会话**,语义是**不重跑、只落 failed 终态**。 对象(任务 vs 会话轮)与动作(重跑 vs 收敛)都不同。
- **vs `sideeffect`/`coord` 的「对账」**:那是「结果未知的副作用裁决」; 本包是「在途编排工作的孤儿收敛」——同词不同域。
- **vs `pending`**:pending 只是挂起态列载体,生命周期外包给宿主,无任何 对账机制。
边界:挂起审批路不在本下沉面 ¶
现象里提到的 waiting_approval 搁浅收敛(宿主的 RecoverApproved:每 15s 扫、 自带 30s 决策宽限)**不在本包**——它要重入执行尾段(受审执行是宿主治域), 与本包「只收敛不重跑」的方向不同,issue #165 的 (a) 范围也没点它。
装配与依赖 ¶
全部存储事实经 Store 接缝注入(包零 gorm/DB 依赖,与 taskboard 同范式: 语义归包、落库归宿主);状态词表复用 contract(终态语义不定义两次而漂移); 收尾事件走 eventbus 词表与宿主的 Pub(落库+广播同一路)。时钟可注入 (NewWithClock):租约过期与静默窗判定要能被确定性测,不靠 sleep。
Index ¶
- Constants
- func OrphanAtBoot(last, boot time.Time, bootGrace time.Duration) bool
- func Stalled(last, now time.Time, threshold time.Duration) bool
- type Cause
- type Config
- type FinalizeDispatcher
- type FinalizeEvent
- type FinalizeGuarantee
- type FinalizeStore
- type LeaseState
- type Pub
- type Reconciler
- type Session
- type Store
Constants ¶
const ( // DefaultStall 事件静默阈值(缺省 10m):running 会话超过该时长无任何事件 // 即判定编排已死。 DefaultStall = 10 * time.Minute // DefaultDeadOwner 他副本死主回落阈值(缺省 30m,Stall 的 3 倍)。 DefaultDeadOwner = 30 * time.Minute // DefaultLeaseTTL 心跳租约缺省 TTL(缺省 60s):打点间隔 15s 的容忍 3 拍丢失。 DefaultLeaseTTL = 60 * time.Second // GraceWindow 决策/续约宽限窗(30s):判定时间在该窗口内视为「活流程可能 // 仍在处理」,不介入;租约判定里它是「租约刚过期的重启重打窗口」。 GraceWindow = 30 * time.Second )
宽限窗与三阈值(bianque recovery.go:104-176 的常量原样下沉;宿主经 Config 调档,0=取这里的缺省)。
三阈值量的是三件不同的事,**不许互相顶替**:
- Stall:本副本会话「多久没事件才算死」——活跃编排即使在长步骤期间也有 进度事件在持续产生,这是死亡的**唯一**证据(本副本无心跳可借);
- DeadOwner:他副本无心跳行时的回落静默——是 Stall 的 3 倍,给慢步骤与 网络抖动留余量;活跃副本会持续打事件,不会误伤;
- LeaseTTL:他副本心跳租约——**主动续约**面,让存活副本名下的会话不再被 按静默阈值误收(长步骤期间事件可能静默数分钟,心跳不会)。
const ( // ByBootReconcile 启动锚点路(进程启动对账收割的孤儿)。 ByBootReconcile = eventbus.ClosedByBootReconcile // ByRecovery 常规路·本副本/无主会话的事件静默收敛。 ByRecovery = eventbus.ClosedByRecovery // ByDeadOwner 常规路·他副本、无心跳行回落事件静默的收敛。 ByDeadOwner = eventbus.ClosedByDeadOwner // ByDeadLease 常规路·他副本心跳租约过期的立即回收。 ByDeadLease = eventbus.ClosedByDeadLease )
归因标识(Cause.By;宿主 turn 括号的 closed_by 与事件载荷按此分辨收敛路径)。 四条路各一个标识——审计靠它分辨「发版重启的正常收割」与「死主回收」。
取值全部引用 eventbus 的 closed_by 词表(issue #391):本包是生产方、 watchdog 是消费方,两包各抄一份时后者只认 loop/recovery/boot-reconcile/panic, 把 dead-owner / dead-lease 的合法收敛报成「无归因」。词表只有一份,加归因 先加 eventbus.ClosedBy* 并同步 ClosedByDefaults。
Variables ¶
This section is empty.
Functions ¶
func OrphanAtBoot ¶
OrphanAtBoot 启动锚点判据:最后事件早于「启动锚点 − 额外宽限」即孤儿。
语义(与另两路的差异见包头):进程启动即替代同 instanceID 的上一具尸体, 此刻名下会话定义性地是孤儿——**无须等事件静默**。反向的免检条件同样在 判据里:boot 后仍有事件产生 = 本进程或同标识存活进程在推进,天然免检。
总函数(零值/关闭态返回 false,不 panic):boot 零值 = 没有启动事实、 bootGrace < 0 = 显式关闭——两者都不得把「无法判定」写成「是孤儿」。 边界:last 恰等于 cutoff **不算**孤儿(Before 严格小于),宽限窗的语义是 「往回收敛的方向再多留一格」。
Types ¶
type Cause ¶
type Cause struct {
// By 归因标识(ByXxx 常量;与宿主 turn 括号的 closed_by 同值)。
By string
// Reason 机制事实描述(判定路 + 阈值 + 观测时刻),由本包生成。
Reason string
}
Cause 一次收敛的结构化归因(机制事实;**报告文案由宿主生成**——领域文案 不进内核,宿主拿 By/Reason 拼自己的恢复说明报告)。
type Config ¶
type Config struct {
// InstanceID 本副本标识(必填):owner 判定的「本副本」零点。
InstanceID string
// Boot 进程启动锚点(RecoverBootOrphans 的判据零点;构造时定格)。
// 零值 = 没有启动事实 ⇒ 启动路整体不跑(防零值锚点误收全量)。
Boot time.Time
// Stall 事件静默阈值(0=DefaultStall;<=0 一律取缺省——静默路不可关,
// 关掉它等于没有任何死亡证据)。仅作用于 owner=本副本/空的会话。
Stall time.Duration
// DeadOwner 他副本无心跳行时的回落静默阈值(0=DefaultDeadOwner)。
DeadOwner time.Duration
// LeaseTTL 心跳租约缺省 TTL(0=DefaultLeaseTTL;**负=关闭心跳判定**,
// 不读 ListBeats、全体回落事件静默)。
LeaseTTL time.Duration
// BootGrace 启动路额外宽限(>0=更保守,last < boot-grace 才收;
// 0=无额外宽限;**负=整体关闭启动路**,回落纯静默路径)。
BootGrace time.Duration
// FinalizeDispatch 终态事件的可确认投递面(issue #272 Outbox 补做)。
//
// 返回 error = 未投递(Outbox 行保留,下一轮/进程重启后补做);
// 返回 nil = 已投递(内核随后 MarkFinalEventDelivered)。未配置时回退
// 到 Pub(fire-and-forget,行直接标记已投递)——FinalizeGuarantee 会
// 如实报告 ConfirmedDelivery=false,不把降级伪装成保证。
FinalizeDispatch FinalizeDispatcher
}
Config 装配配置(构造时定值;阈值 0=取包内缺省,与宿主 conf 旋钮同语义)。
type FinalizeDispatcher ¶ added in v0.43.0
type FinalizeDispatcher func(ctx context.Context, ev FinalizeEvent) error
FinalizeDispatcher 可确认投递的终态事件发布面(issue #272)。
返回 error = 未投递(Outbox 行保留待补做);nil = 已投递。与 Pub 的 区别只有一件事:**失败可被判**。未配置时内核回退到 Pub,并把该行的 投递视作已完成(fire-and-forget)——这是显式降级,由 FinalizeGuarantee 的 ConfirmedDelivery 字段报告。
type FinalizeEvent ¶ added in v0.43.0
type FinalizeEvent struct {
// ID 稳定事件标识(幂等键;重放不重复生效的依据)。
ID string
// SessionID 会话标识。
SessionID string
// CaseID 案例标识(旧 Pub 的透传字段;可为空)。
CaseID string
// Type 事件类型(eventbus 词表;终态恒为 session_finished)。
Type string
// Level 事件级别(与旧路径一致:"error")。
Level string
// Payload 事件载荷(至少含 by 归因)。
Payload map[string]any
}
FinalizeEvent 一条终态事件(Outbox 行的逻辑载荷)。
ID 由内核生成且稳定(同一会话的同一终态迁移恒为同一 ID);宿主落库时 应把它作为唯一键。Type/Level/Payload 与旧 Pub 发送的 session_finished 逐字一致,订阅方不需要区分两条路径。
type FinalizeGuarantee ¶ added in v0.43.0
type FinalizeGuarantee struct {
// Atomic 终态写入与终态事件是否同一事务(Store 实现 FinalizeStore)。
Atomic bool
// ConfirmedDelivery 投递结果是否可确认(配置了 FinalizeDispatch)。
// false 时事件行仍可能同事务落库,但「已投递」只能按调用成功推定。
ConfirmedDelivery bool
}
FinalizeGuarantee 终态事件的交付保证形态(可查事实,不是散文)。
type FinalizeStore ¶ added in v0.43.0
type FinalizeStore interface {
Store
Finalize(ctx context.Context, sessionID, from, to string, cause Cause, ev FinalizeEvent) (bool, error)
PendingFinalEvents(ctx context.Context, limit int) ([]FinalizeEvent, error)
MarkFinalEventDelivered(ctx context.Context, eventID string) error
}
FinalizeStore Store 的可选能力:终态写入与终态事件同一事务(issue #272)。
实现本接口 = 声明下面三件事:
- Finalize **原子**:from→to 条件迁移、宿主侧的恢复报告/排队结算/ 悬挂环节收口(与 Store.ConvergeCAS 同义)与 ev 的 Outbox 行写在 一次事务里;false = 他方已处理(零写入,不得写第二行);
- PendingFinalEvents 返回**未投递**的 Outbox 行(按写入序,limit 有界);
- MarkFinalEventDelivered **幂等**:同一 ID 重复标记不报错、不产生 第二行(已投递的行不再出现在 Pending 里)。
不实现本接口的 Store 仍可用:Reconciler 走旧路径,FinalizeGuarantee 报降级。
type LeaseState ¶
type LeaseState int
LeaseState 心跳租约判定结论(仅对 owner=他副本的会话有意义)。
const ( // LeaseNoRow 无心跳行(存量版本副本 / 心跳面读失败降级 / 心跳判定已关闭): // **回落事件静默**——以更宽的 DeadOwner 阈值近似存活,不误伤活跃副本。 LeaseNoRow LeaseState = iota // LeaseLive 心跳新鲜,或租约刚过期仍在重打宽限窗内:**免检**(活编排 // 名下不等事件静默——长步骤的静默是常态,不是死亡证据)。 LeaseLive // LeaseExpired 租约过期(含宽限窗):**不等事件静默立即回收**。 LeaseExpired )
func JudgeLease ¶
func JudgeLease(beats map[string]time.Time, owner string, now time.Time, lease, grace time.Duration) LeaseState
JudgeLease 心跳租约判据(仅他副本名下;本副本走 Stall 静默,见包头)。
- beats 为 nil、lease <= 0(心跳判定关闭)或 owner 无心跳行 → LeaseNoRow (回落事件静默);
- now − beat < lease + GraceWindow → LeaseLive:心跳新鲜,或租约刚过期但 仍在「重启副本重打」宽限窗内——活编排名下**免检**;
- 否则 LeaseExpired:租约过期,不等事件静默立即回收。
宽限窗必须加在租约上:副本重启后要花一拍(15s)才重建心跳,没有这 30s, 每次重启都会被他副本按「租约过期」误收一波。
type Pub ¶
Pub 收尾事件发布接缝(宿主的落库+广播同一路;与 watchdog.Pub 同形)。
本包经它发 session_finished(turn_ended 归 CloseBracket,见 Store 注释)。 事件词表用 eventbus 的既有常量,不另立事件模型。
接缝约束三条(#400):
- 不得重入:不得回调 Reconciler 的 Recover*(收尾只属于赢下 CAS 的那一次, 重入会制造同会话的重复收尾)。
- 不得阻塞:发布在收敛路径上同步调用;实现须自行设超时/上界,不得无限 等待(终态事实已成立,发布慢只应慢自己,不该拖住对账协程)。
- panic 隔离:本包不 recover Pub——实现不得 panic(panic 会掀翻调用方的 对账协程);失败请经返回值/自有留痕处理。
type Reconciler ¶
type Reconciler struct {
// contains filtered or unexported fields
}
Reconciler 三路扫描与收敛编排(零值不可用,用 New / NewWithClock 构造)。
并发安全面:自身无可变状态(Config 构造时定值),多次 Recover* 可并发调—— 收敛的互斥由宿主的 ConvergeCAS 条件迁移保证(本包只判结果不加锁)。
func NewWithClock ¶
NewWithClock 构造并**注入时钟**(ticket.NewWithClock 同款):租约过期、 静默超阈、启动锚点三个判定全依赖 now,读真实时间的过期用例恒不触发—— 判据会退化成一组空断言(全绿但什么都没验)。
接缝契约(issue #369) ¶
@seam: no-reentry no-blocking panic-caller
- **不得重入**:回调内不得再次触发会读取本 Reconciler 时钟的判定路径 (会递归);只读回查是安全的(Reconciler 自身无锁,时钟在判定路径上取)。
- **不得阻塞**:回调在每轮对账的到期判定前被调用,必须立即返回。
- **panic 由调用方兜**(panic-caller):内核不 recover 该回调的 panic。
store / pub / InstanceID 任一缺失即 panic:装配期 fail fast,不留到运行时 (没有存储的对账无从判定,没有 InstanceID 会把他副本名下判成反面)。
func (*Reconciler) FinalizeGuarantee ¶ added in v0.43.0
func (r *Reconciler) FinalizeGuarantee() FinalizeGuarantee
FinalizeGuarantee 报告本 Reconciler 的终态事件交付形态(issue #272)。
宿主启动自检可断言它为 (true, true);只拿到 (false, false) 的部署必须 接受「终态后事件可能缺失」的旧口径,或补 FinalizeStore + FinalizeDispatch。
func (*Reconciler) FlushFinalizeOutbox ¶ added in v0.43.0
func (r *Reconciler) FlushFinalizeOutbox(ctx context.Context) (int, error)
FlushFinalizeOutbox 幂等补做终态事件 Outbox(issue #272)。
语义:
- 只有 Store 实现 FinalizeStore 时有事可做;否则返回 (0, nil);
- 逐行投递(保序):一条失败就停在它,不越过它投后面的行;
- 投递成功后才标记已投递;标记失败时行保留(下一轮重投,ID 稳定);
- 已投递的行不再出现在 PendingFinalEvents 里,重放不会重复发送。
返回实际标记成功的行数与聚合错误(投递/标记失败都在里面)。
RecoverBootOrphans / RecoverInterrupted 每轮开始时也会先调用一次:进程 重启或上一轮「Finalize 已提交、Flush 未完成」留下的行无需宿主额外接线 就会重试(宿主也可按自己的节奏单独调用,两者幂等)。
func (*Reconciler) RecoverBootOrphans ¶
func (r *Reconciler) RecoverBootOrphans(ctx context.Context) (int, error)
RecoverBootOrphans 启动孤儿对账(一次性扫描;宿主在进程启动时调一次)。
语义与免检条件见包头「三路判定的语义差异」与 OrphanAtBoot:owner=本副本/ 空 + running + 最后事件早于启动锚点(减 BootGrace)⇒ 定义性孤儿,立即收, 无须等 Stall 事件静默。他副本名下的会话**不在本路**(归 RecoverInterrupted 的租约/静默判定管)。
两个关闭态:BootGrace < 0(conf 显式关闭)与 Boot 零值(无启动事实,防 零值锚点误收全量)——都直接返回,不碰存储。
返回 (收敛数, 聚合错误):单会话的读事实失败/收敛失败**不中止整轮扫描** (一个会话的问题不该让其余孤儿滞留),错误经 errors.Append 聚合带出, 由宿主留痕;ListRunning 失败则整轮无从扫起,立即返回。
func (*Reconciler) RecoverInterrupted ¶
func (r *Reconciler) RecoverInterrupted(ctx context.Context) (int, error)
RecoverInterrupted running 搁浅回收(周期扫描;宿主按自己的节奏循环调)。
语义取 deny by default:**不做步骤级重放**(重放会产生重复环节与二次审批, 执行段可能有副作用),收敛为 failed 并写明恢复路径。判定分两路(见包头):
- owner=本副本/空:事件静默(Stall)——本副本不适用心跳免检,自副本走 静默恰是重启孤儿的安全网;
- owner=他副本:先看心跳租约(JudgeLease)——租约过期立即回收、心跳新鲜 免检、无心跳行回落事件静默(DeadOwner 阈值)。
心跳面读失败**降级不停车**:全体走事件静默判定(恢复不因观测面抖动停摆), 错误随返回值带出留痕。LeaseTTL < 0(conf 关闭心跳面)则根本不读 ListBeats。
type Session ¶
type Session struct {
// ID 会话标识(收敛与事件的主键)。
ID string
// CaseID 案例标识(事件载荷透传;宿主无此概念可置空)。
CaseID string
// Owner 归属副本标识;空 = 无主(无主行归本副本判定面)。
Owner string
// CreatedAt 创建时刻:无事件行(首个事件落库前即中断)时的锚点。
CreatedAt time.Time
}
Session 在途会话的判定所需最小面(宿主 running 行的投影;领域字段不进本包)。
type Store ¶
type Store interface {
// ListRunning 列出 running 态会话(owner 语义见上)。
ListRunning(ctx context.Context, owner string) ([]Session, error)
// LastActivity 最后事件时刻(零值 = 无事件行)。
LastActivity(ctx context.Context, sessionID string) (time.Time, error)
// ListBeats 副本心跳表(instanceID → 最后打点时刻)。
ListBeats(ctx context.Context) (map[string]time.Time, error)
// ConvergeCAS 条件收敛(from→to,原子带报告与结算;false = 他方已处理)。
//
// 注意:本方法**不包含终态事件**——终态事件与状态同事务要靠 FinalizeStore
// (issue #272)。只实现 Store 的宿主走旧路径:状态终态后事件发布失败
// 没有补做入口(见 FinalizeGuarantee 的降级声明)。
ConvergeCAS(ctx context.Context, sessionID, from, to string, cause Cause) (bool, error)
// CloseBracket 关闭开放的 turn 括号(closedBy = Cause.By)。
// 返回 error = 关闭失败(内核并入聚合错误带出,不吞)。
CloseBracket(ctx context.Context, sessionID, closedBy string) error
}
Store 存储接缝(宿主实现;形态与 taskboard/eventbus 的接缝同风格: 判定留包内、状态归存储、包零 DB 依赖)。
契约八条(五条语义 + #400 的三条接缝约束):
- **ListRunning 是扫描面提示,不是判定权威**:owner=="" 列出全部 running 会话(常规路要判他副本,必须看全量);owner==instanceID 可收窄到该实例 名下(启动路的优化面),但**不得漏 Owner 为空的行**(无主行归任何实例 的判定面)。判定权恒在内核——按 Session.Owner 复核,收窄必须是超集;
- **LastActivity 是只读事实**:返回最后事件时刻,零值 = 无事件行(内核 回落 CreatedAt 锚定)。返回 error = 该会话**不可判**,内核跳过不收 (读不到事实就不许收敛,宁可留给下一轮/另一条路);
- **ListBeats 读失败由内核降级**:error ⇒ 全体走事件静默判定(恢复不因 观测面抖动停摆),错误随扫描返回值带出留痕;
- **ConvergeCAS 是一次原子收敛**:条件迁移(from→to)+ 恢复说明报告 + 排队输入结算 + 悬挂环节收口——宿主侧等价于「条件 UPDATE + 终态报告 + 结算」同事务完成(bianque FinalizeSession + Settle + FailSteps 的宿主 等价物)。返回 (false, nil) = 他方已处理(条件迁移零行),内核不再发 任何收尾动作;返回 error = 内核带出留痕;
- **CloseBracket 关闭该会话仍开放的 turn 括号**,以 closedBy 归因留痕。 宿主的典型实现即落 turn_ended 事件(载荷带 closed_by)——「有 start 无 end」的开放括号是中断轮的可检测孤儿态,关不掉它审计就读不出轮边界。 本包不重复发 turn_ended(那会与宿主实现双写)。返回 error = 括号没关成, 内核**并入聚合错误带出留痕**(issue #184:签名吞错误连「失败了」都 表达不了,宿主拿到错误才能补偿修复);session_finished 照发——终态 事实已由 ConvergeCAS 成立,事件驱动收尾的下游不因审计面故障停摆。
- **不得重入**:实现不得回调 Reconciler 的 Recover*(收敛互斥由 ConvergeCAS 条件迁移保证;重入只会制造同会话的重复收尾动作)。
- **不得阻塞**:五个方法都在扫描/收敛路径上同步调用;实现须遵守 ctx 的超时/取消并自设上界,不得无限等待(一个会话卡住会拖住整轮扫描)。
- **panic 隔离**:本包不 recover 宿主实现——实现不得 panic(panic 会 掀翻调用方的对账协程);失败一律经 error 返回,由内核聚合留痕。