toolfail

type Class string

type Failure struct {
	// Class 失败类别，决定重试策略。
	Class Class

	// Code 稳定机读码（如 "rate_limited"）。跨版本稳定，用于聚合与判定，
	// 不得写入具体数值、标识或耗时等每次都变的内容。
	Code string

	// Message 人读文案（进日志与上报，不参与判定）。
	Message string

	// RemediationOverride 该次失败专有的模型指引；为空时取 PolicyOf(Class).Remediation。
	//
	// 为什么允许逐次覆盖：处置指引的下一步动作常常取决于**具体是哪个**参数非法、
	// 哪个标识没找到，逐次覆盖比让模型去猜更快也更准。
	RemediationOverride string

	// Idempotency 宿主对本次调用的幂等性表态；未表态时按类别默认取值。
	//
	// 为什么要宿主逐次声明：同一个类别下不同工具的幂等性可以完全相反
	//（同样是 transient，一个只读查询重发毫无风险，另一个创建接口重发就重复了）。
	// 类别只能给缺省，逐次表态才是准确的。
	Idempotency Idempotency

	// RetryAfter 服务端建议的等待时长；0 表示无此提示。
	// 仅在 PolicyOf(Class).SurfaceDelay 为真时有意义。
	RetryAfter time.Duration

	// Err 可选根因（底层错误）。保留供 errors.Is/As 判定与排查，
	// 不参与策略判定——策略只看 Class。
	Err error
}

type Idempotency int

type Policy struct {
	// Class 该策略对应的类别。
	Class Class

	// Retryable 原样重试是否有意义。
	Retryable bool

	// Backoff 是否建议退避后重试（重试有收益但不该立刻打）。
	//
	// 与 Retryable 分开是因为「立刻重试」与「退避重试」是两种不同代价：
	// 限流立刻重试只会立刻再被限流，把一次退避能吸收的拥塞放大成重试风暴。
	Backoff bool

	// SurfaceDelay 是否应把服务端给的等待时长向上层暴露（限流类才有此信息）。
	SurfaceDelay bool

	// NeedsOperator 是否需要人工介入（改凭证/放权限，机器自己无能为力）。
	NeedsOperator bool

	// SafeToResubmit 该类失败**默认**能否原样重发（不产生重复副作用）。
	//
	// 与 Retryable 正交，组合起来才完整表达自动重试的决策：
	//   - 两者皆真  → 直接重发；
	//   - 可重试但不可重发 → 重发前必须确认上次是否已生效（典型的超时类）；
	//   - 不可重试 → 换处置路径（改参数 / 找人工 / 收口）。
	//
	// 取值一律保守：只有**能证明服务端未受理本次调用**的类别才置真
	// （限流即如此——请求根本没进业务逻辑）。超时类不给真：超时的定义就是
	// 「不知道对方执行到哪」，把它当成安全重发是把一次调用放大成两次。
	SafeToResubmit bool

	// Remediation 面向**模型**的处置说明（回答「这是什么情况、我该改什么」）。
	//
	// 与 Failure.Message 刻意分开：Message 是给人看的（进日志与上报），
	// 会被改写、含具体数值；提示词里要的是可执行的指引，不是现场描述。
	// 取值不得包含具体标识、数值与业务词面——它会原样进入提示词。
	//
	// **不得自带重试结论**（不要写「重试」「等待 N 秒」「需要人工」）：
	// 那是 Guidance 的机械判定，写在这里会与之重复，个别类别还会直接矛盾
	//（自报类文案写「可以直接重试」，而其 SafeToResubmit 为假，Guidance 会说
	//「先确认上一次是否已生效」——同一段提示词里两个相反的指令，模型无从取舍）。
	// 该约束由 TestRemediationCarriesNoRetryVerdict 钉住。
	Remediation string
}

type RetryableReporter interface {
	// Retryable 这次失败原样重试是否有意义。
	//
	// 实现约定：接收者可能为 nil（错误链上挂着 typed-nil 指针），此时必须返回
	// false 而非解引用——本包对链上每一环都直接调方法，不替你防 panic。
	Retryable() bool
}