sideeffect

type Action struct {
	// Key 幂等键（必填，空串视为非法动作）。
	Key Key
	// Resource 动作作用的目标资源标识（必填）。
	// 租约按它判定独占：同一 Resource 上同一时刻至多一个持有者。
	Resource string
	// Payload 动作参数。内核不解释其内容（机制面不认识领域概念），
	// 但**结果记录需要能把它与结果对应起来**，故由宿主定义序列化方式。
	Payload []byte
	// RetrySafety 该动作在**施加失败**后的重试安全性（缺省 = 未声明 = 按最弱处理）。
	//
	// 声明放在 Action 而不是执行体上：重试安全性是**这个逻辑动作**的属性
	// （下游按不按幂等键去重），同一动作的多次重试必须是同一份声明——
	// 放在执行体上就变成「每次调用各说各话」，重试与首次施加口径不一致，
	// 于是「这次失败了能不能再来一次」的答案随调用点漂移。
	//
	// 零值 RetrySafetyUnknown 的含义：施加失败即**结果未知**，闸转入未知态，
	// 这个 Key 必须先对账才能再动。声明 RetrySafetySafe 则是断言
	// 「下游按幂等键去重，重试不会重复施加」——**断言错了就是重复施加**，
	// 故它只能是宿主的显式选择。
	RetrySafety RetrySafety
}

type Effect struct {
	// Prepare 准备阶段：算结果、构造请求，但**不施加副作用**。
	// 可为 nil（不需要准备阶段）。
	Prepare func(ctx context.Context) (any, error)
	// Apply 施加阶段：真正对外部世界动手。prepared 是 Prepare 的产出，
	// lease 是本次持有（含栅栏令牌）——把它传给下游。
	Apply func(ctx context.Context, prepared any, lease Lease) (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 Resolution struct {
	// Applied 确认动作**已生效**吗？
	//
	// true  → 闸把该 Key 记为已完成并留存 Result：后续同一 Key 的 Acquire
	//         返回 OutcomeReplayed + 该结果（重放而不是重做）。
	// false → 确认动作**未生效**：清除未知标记，该 Key 重新可被执行。
	Applied bool
	// Result 已生效时的动作结果（Applied=false 时忽略）。
	Result Result
	// Reason 裁决依据（留痕）。事后复盘时，「凭什么判定已生效」比
	// 「判定结果是什么」更有价值——前者能定位判据的薄弱处。
	Reason string
}

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

type RetrySafety int

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

type Store interface {
	// Acquire 一次原子判定，返回「能否执行」与「若能执行则用哪一代令牌」。
	//
	// ttl 是本次持有的有效期，**必须由调用方显式给出**：
	// 租约多长是「本次动作预计要多久」的业务判断，内核不知道，宿主也不知道——
	// 它只知道自己在编排什么动作。所以 TTL 走参数，不走实现里的硬编码常量
	// （硬编码的 TTL 要么太长（别人迟迟拿不到闸）要么太短
	// （自己的动作还没做完就被接管，栅栏令牌发得再准也拦不住重入）。
	//
	// 语义（存储侧必须保证）：
	//  1. 若该 Key 的动作**已完成** → 返回 OutcomeReplayed 与既有结果，
	//     不发放新令牌（已完成的动作不再需要令牌）。
	//  2. 否则若该 Key 处于**结果未知**态（MarkUncertain 标记的）→ 返回
	//     OutcomeUncertain，不发放令牌。
	//  3. 否则若该 Resource 正被他人持有且**租约未过期** → 返回
	//     OutcomeContended，不发放令牌。
	//  4. 否则 → 授予本次持有：令牌 = 该 Resource 上**已见过的最大值 + 1**
	//     （单调递增，不回退），并返回 OutcomeApplied。
	//
	// 已完成（1）的判定**优先于**占用（3）：动作已做完时，后来者应当拿到
	// 结果而不是被「资源正忙」挡住——否则调用方会把「早已完成」误判成
	// 「没轮上我」，而真相是「早就做完了」。
	//
	// 结果未知（2）**优先于**占用（3），但**次于**已完成（1）：未知态是
	// 这个 Key 头上的**硬阻塞**（再动它就是重复施加），而占用只是「等一等」。
	// 顺序写反的后果是：调用方拿到 contended 就以为「晚点重试就行」，
	// 而真相是「这个 Key 得先对账」——于是重试发生了，重复施加也就发生了。
	//
	// 第 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)

	// MarkUncertain 把该 Key 标记为「结果未知」。
	//
	// 存储侧必须保证：
	//  1. 该 Key 的下一次 Acquire 返回 OutcomeUncertain，**不得**返回
	//     OutcomeApplied——否则会盲目重试一个可能已经生效的动作。
	//  2. 标记是**按 Key** 的，与资源租约无关：闸可以释放（让别的动作用这个
	//     资源），但这个 Key 在被裁决之前**不得再被执行**。
	//  3. 幂等：重复标记同一 Key 不报错。
	//  4. 若本次持有的令牌已不是最新代（ErrFenceStale）→ **拒绝标记**。
	//     否则一个过期持有者会把新持有者刚做完的动作标成未知，
	//     而新持有者那边的结果是确定的——事实被写反了。
	MarkUncertain(ctx context.Context, act Action, lease Lease, reason string) error

	// ResolveUncertain 裁决「结果未知」的 Key。
	//
	// 存储侧必须保证：
	//  1. res.Applied == true → 把该 Key 记为已完成并留存 res.Result；
	//     之后同一 Key 的 Acquire 返回 OutcomeReplayed + 该结果
	//     （重放而不是重做）。
	//  2. res.Applied == false → 清除未知标记，该 Key 重新可被执行
	//     （之后同一 Key 的 Acquire 可返回 OutcomeApplied）。
	//  3. **先到者为准**（幂等）：同一 Key 的二次裁决不覆盖首次裁决。
	//  4. 该 Key 不在未知态时：若已完成 → 返回 OutcomeReplayed + 既有结果；
	//     否则 → 返回 ErrNotUncertain。
	//  5. 裁决**不校验栅栏**：它的依据是**下游事实**，不是持有权——
	//     原持有者可能已经死亡、租约早已过期，而对账恰恰要在这种情况下进行。
	//     （栅栏管的是「谁能写」，对账管的是「到底做没做」，两件事。）
	ResolveUncertain(ctx context.Context, act Action, res Resolution) (Outcome, Result, error)
}