reconcile

package
v0.45.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 6 Imported by: 0

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),差别全在「凭什么说它死了」:

  1. **启动锚点路**(RecoverBootOrphans):进程启动即替代同 instanceID 的 上一具尸体——此刻名下 running 会话**定义性地是孤儿**(上一进程已死, 不会再产出任何事件),所以**无须等事件静默**(常规路缺省 10m)才定性。 旧路径下这段窗口正是「后继输入排队死锁」的体验来源:会话卡 running、 注入只进队列无人消费。判据只剩一条:最后事件早于本进程启动锚点 (boot 后仍有事件产生 = 本进程或同标识存活进程在推进,**天然免检**)。
  2. **常规路·事件静默子路**(owner=本副本/空):没有启动锚点可借(进程 活着、可能正是它自己在推进),只能等「超阈无任何事件」——活跃编排即 使在长步骤期间也有进度事件在持续产生,静默超阈才是死亡证据。本副本 **不适用**心跳免检:心跳新鲜的「新进程」没有旧编排的取消句柄,自副本 走静默恰是重启孤儿的安全网。
  3. **常规路·心跳租约子路**(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

View Source
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:他副本心跳租约——**主动续约**面,让存活副本名下的会话不再被 按静默阈值误收(长步骤期间事件可能静默数分钟,心跳不会)。
View Source
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

func OrphanAtBoot(last, boot time.Time, bootGrace time.Duration) bool

OrphanAtBoot 启动锚点判据:最后事件早于「启动锚点 − 额外宽限」即孤儿。

语义(与另两路的差异见包头):进程启动即替代同 instanceID 的上一具尸体, 此刻名下会话定义性地是孤儿——**无须等事件静默**。反向的免检条件同样在 判据里:boot 后仍有事件产生 = 本进程或同标识存活进程在推进,天然免检。

总函数(零值/关闭态返回 false,不 panic):boot 零值 = 没有启动事实、 bootGrace < 0 = 显式关闭——两者都不得把「无法判定」写成「是孤儿」。 边界:last 恰等于 cutoff **不算**孤儿(Before 严格小于),宽限窗的语义是 「往回收敛的方向再多留一格」。

func Stalled

func Stalled(last, now time.Time, threshold time.Duration) bool

Stalled 事件静默判据:now − last >= threshold 即静默超阈(判定编排已死)。

边界是**含等号**:恰等于阈值就算超(宿主原实现 `now.Sub(last) < threshold 才跳过` 的反面)。threshold <= 0 视为立即超阈——那是「关闭静默窗」的危险 方向,Config 不提供该入口(Stall/DeadOwner 只接受正值覆盖),此处置写明 是为了判据本身是总函数,不是给宿主开的口子。

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

type Pub func(sessionID, caseID string, stepID *uint64, typ, level string, payload map[string]any)

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 New

func New(store Store, pub Pub, cfg Config) *Reconciler

New 构造(时钟取 time.Now)。

func NewWithClock

func NewWithClock(store Store, pub Pub, cfg Config, now func() time.Time) *Reconciler

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 返回,由内核聚合留痕。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL