sideeffect

type Action struct {
	// Key 幂等键（必填，空串视为非法动作）。
	Key Key
	// Resource 动作作用的目标资源标识（必填）。
	// 租约按它判定独占：同一 Resource 上同一时刻至多一个持有者。
	Resource string
	// Payload 动作参数。内核不解释其内容（机制面不认识领域概念），
	// 但**结果记录需要能把它与结果对应起来**，故由宿主定义序列化方式。
	Payload []byte
}

type Effect struct {
	// Prepare 准备阶段：算结果、构造请求，但**不施加副作用**。
	// 可为 nil（不需要准备阶段）。
	Prepare func(ctx context.Context) (any, error)
	// Apply 施加阶段：真正对外部世界动手。prepared 是 Prepare 的产出。
	Apply func(ctx context.Context, prepared any) (Result, error)
}

type Fence uint64

type FencedSink interface {
	// WriteFenced 在资源上执行一次带栅栏令牌的写入。
	//
	// 语义（实现侧必须保证）：
	//  1. 若 presented **小于**该资源已见过的最大令牌 → **不执行**写入，
	//     返回 ErrFenceStale（这是一次过期持有者的迟到写入）；
	//  2. 否则执行写入，并把该资源已见过的最大令牌更新为 presented；
	//  3. 第 1 条的判定与第 2 条的写入（含令牌更新）必须在**同一次原子操作**里。
	//
	// 第 1 条用「小于」而非「不等于或小于」：**等于**是合法的
	// （同一代持有者的多次写入，如分批提交），只有**更小**才是陈旧。
	//
	// 返回 ErrFenceStale 时**必须没有发生任何写入**（不得部分写）。
	WriteFenced(ctx context.Context, resource string, presented Fence, write func(ctx context.Context) error) error
}

type Key string

type Lease struct {
	// Resource 被独占的资源标识。
	Resource string
	// Fence 本次持有对应的栅栏令牌（同一 Resource 上单调递增）。
	Fence Fence
	// TTL 本次持有的有效期。
	TTL time.Duration
}

type Outcome int

type Result struct {
	// Payload 动作产出的数据（宿主定义序列化方式）。
	Payload []byte
}

type Runner struct {
	// contains filtered or unexported fields
}

type Store interface {
	// Acquire 一次原子判定，返回「能否执行」与「若能执行则用哪一代令牌」。
	//
	// ttl 是本次持有的有效期，**必须由调用方显式给出**：
	// 租约多长是「本次动作预计要多久」的业务判断，内核不知道，宿主也不知道——
	// 它只知道自己在编排什么动作。所以 TTL 走参数，不走实现里的硬编码常量
	// （硬编码的 TTL 要么太长（别人迟迟拿不到闸）要么太短
	// （自己的动作还没做完就被接管，栅栏令牌发得再准也拦不住重入）。
	//
	// 语义（存储侧必须保证）：
	//  1. 若该 Key 的动作**已完成** → 返回 OutcomeReplayed 与既有结果，
	//     不发放新令牌（已完成的动作不再需要令牌）。
	//  2. 否则若该 Resource 正被他人持有且**租约未过期** → 返回
	//     OutcomeContended，不发放令牌。
	//  3. 否则 → 授予本次持有：令牌 = 该 Resource 上**已见过的最大值 + 1**
	//     （单调递增，不回退），并返回 OutcomeApplied。
	//
	// 已完成（1）的判定**优先于**占用（2）：动作已做完时，后来者应当拿到
	// 结果而不是被「资源正忙」挡住——否则调用方会把「早已完成」误判成
	// 「没轮上我」，而真相是「早就做完了」。
	//
	// 第 3 条的令牌分配必须与「标记该 Key 已完成」同处一个原子操作面
	// （可分两步但需同一事务/脚本内），否则会出现「发了令牌但没记住谁占着」。
	//
	// 返回的 Result 是**既有结果原样**（不做任何标记）：本次是否在重放
	// 由 Acquire 的 Outcome 表达，不靠结果里的一个标志位——
	// 同一件事只有一个真相。
	Acquire(ctx context.Context, act Action, ttl time.Duration) (Outcome, Lease, Result, error)

	// Complete 标记该 Key 的动作已完成并记录结果。
	//
	// 幂等：同一 Key 重复 Complete 不报错，返回首次记录的结果
	// （先到者的结果为准，不被后到者覆盖）。
	//
	// 必须带 Fence：存储侧**只在令牌仍是当前 Resource 的最新令牌时**才接受
	// 这次完成。过期持有者的迟到 Complete 会被拒（否则它会用旧结果覆盖
	// 新持有者刚写入的结果——更新的状态被旧状态覆盖，与栅栏要防的正是
	// 同一件事）。
	Complete(ctx context.Context, act Action, lease Lease, res Result) (Result, error)

	// Release 释放持有（提前结束，不必等到 TTL 自然过期）。
	//
	// 只释放**自己**的持有：存储侧须校验令牌是当前令牌才释放，
	// 否则一个过期持有者迟到的 Release 会把新持有者的闸放掉
	// （与 commitgate「凭令牌释放、不认内容」同一条纪律）。
	//
	// 释放**不**把该 Key 标记为已完成——动作没做完就是没做完，
	// 下次同一 Key 仍可获得执行权。
	Release(ctx context.Context, act Action, lease Lease) error

	// Renew 续期并**同时确认持有资格**。
	//
	// 它做两件事，缺一不可：
	//  1. 把本次持有的到期时刻推后 ttl（长动作不至于中途失去闸）；
	//  2. 校验本次令牌**仍是该 Resource 的最新代**——若已被他人接管，
	//     返回 ErrFenceStale，**不续期**。
	//
	// 第 2 条才是 Renew 的重点。只做第 1 条的「续期」是**假续期**：
	// 闸已经易主时，延长时间延的是别人的闸，持有者却以为延长的是自己的。
	// 于是持有者带着一份早已过期的租约继续施加副作用——
	// 而此时新持有者可能正在做同一件事。这就是「两份闸同时开着」。
	//
	// 因此 Renew 的语义是**「我还持有吗，顺便把有效期推后」**，
	// 不是纯心跳。宿主应在**施加副作用之前**调用它：
	// 那时若返回 ErrFenceStale，说明闸已易主，本次动作**必须放弃**——
	// 继续做就是与新持有者重复施加。
	//
	// 存储侧须保证：续期与资格校验在**同一次原子操作**里完成
	// （否则「校验通过」与「续期生效」之间仍有窗口）。
	Renew(ctx context.Context, act Action, lease Lease, ttl time.Duration) (Lease, error)
}