Documentation
¶
Overview ¶
turn.go —— INV3 轮级括号配对(issue #171)。
INV1/INV2(watchdog.go)是**工具调用级**配对:声明↔结果。本文件是它的外层—— **轮级**配对:turn_started 开括号、turn_ended 闭括号。任何以事件流呈现轮生命 周期的宿主都有这对括号,且都面对同一组异常态:无归因的闭合、重复闭合、停机留 开放(**合法**)、开放超时(泄漏)。
只告警不裁决 ¶
与既有 INV 同一章程:本文件只登记、校验与归因告警,**闭合动作仍由宿主恢复 路径执行**(recovery/boot-reconcile/panic 各自发 closed_by 的 turn_ended)。
判得了什么,判不了什么(刻意写明的边界) ¶
- 判得了:闭合有没有归因(closed_by ∈ 词表)、status 是否在 contract 终态 词表内、闭合有没有对应的开括号、开放括号是否超 TTL。
- 判不了:「闭合 status 与会话终态一致」。那需要会话存储面(本轮到底收敛成 什么),watchdog 没有存储面,也不该有——语义裁决归宿主恢复路径。本包只判 词表成员与配对/归因,**不判断归因内容对不对**(例如 recovery 是否真的由 恢复循环发起)。
停机留开放 = 合法 ¶
进程停机路径刻意不落 turn_ended,让括号保持开放、由下次启动的对账/恢复关闭。 因此 Run 因 ctx 取消退出时**不做扫尾告警**:扫尾只在进程存活、事件持续到达时 按 TTL 触发。否则每个宿主的正常停机都会误报一片泄漏。
Package watchdog 被动配对不变量监视(spec 2026-09-15-tool-identity-otel-guard-design P3):
生命周期: Stable(v0.33.0 定级)——只允许 additive 变更(新增导出符号 / 新增方法且给零值默认实现 / 新增错误值);改签名、改语义、改默认值、 删导出符号都算 breaking,判定规则与变更流程见 docs/api-compat.md, 逐包理由见 api-lifecycle.yaml。
订阅事件总线校验配对不变量——只告警,不裁决(热路径裁决在 IdentityGuard)。 INV1 环节收口仍有未执行声明 → reason=declared_not_executed; INV2 结果无对应声明(重复/幽灵结果)→ reason=unpaired_result。 INV3(issue #171)是工具配对的外层——轮级括号 turn_started/turn_ended 的 配对、闭合归因(closed_by)与 status 终态词表校验,见 turn.go。 注意命名撞车:spec 2026-09-15-tool-identity-otel-guard-design §8 的「INV3 (事件面 checksum 抽验)」是另一条不变量,本包仍不实现它——tool_result 载荷 截断到 2000 字符,无法重算 checksum,内容级校验由守卫在源头全量覆盖。
Index ¶
Constants ¶
const ( // ClosedByLoop 收尾漏斗正常出口(宿主编排循环自己闭合)。 ClosedByLoop = "loop" // ClosedByRecovery 恢复循环归因(中断会话的统一收敛体)。 ClosedByRecovery = "recovery" // ClosedByBootReconcile 启动对账归因(发版重启后的孤儿回收)。 ClosedByBootReconcile = "boot-reconcile" // ClosedByPanic 编排 panic 归因(recoverPanic 就地收口)。 ClosedByPanic = "panic" )
闭合归因(closed_by)缺省词表。宿主可在 Config.ClosedBy 里扩充, 内核只判「有没有(在册的)归因」,不判归因语义。
const ( // ReasonTurnEndUnattributed 闭合无归因,或归因不在宿主注册的词表内。 ReasonTurnEndUnattributed = "turn_end_unattributed" // ReasonTurnEndUnknownStatus 闭合携带的 status 不在 contract 终态词表内 // (含缺失)。语义裁决归宿主,这里只判词表成员。 ReasonTurnEndUnknownStatus = "turn_end_unknown_status" // ReasonTurnEndUnopened 闭合没有对应的开括号(重复闭合 / 事件乱序丢开括号)。 ReasonTurnEndUnopened = "turn_end_unopened" // ReasonTurnOpenLeak 开放括号超 TTL 未闭合(进程存活时按 TTL 清扫)。 // 停机退出不触发——停机留开放是合法态。 ReasonTurnOpenLeak = "turn_open_leak" )
轮括号告警 reason 词表(EventTurnBracketViolation 的 payload["reason"])。
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶ added in v0.38.0
type Config struct {
// ClosedBy 宿主注册的闭合归因词表。缺省(空)时使用 defaultClosedBy;
// 填了则在缺省词表基础上**扩充**(不是替换)——缺省四值是所有宿主共有的
// 收尾路径,只增不减才能避免「宿主少写一个值就把合法归因判成红」。
ClosedBy []string
// OpenTTL 开放括号的泄漏判定阈值;缺省(<=0)复用 openIdleTTL。
OpenTTL time.Duration
// SweepEvery 清扫间隔;缺省(<=0)复用 sweepEvery。
SweepEvery time.Duration
}
Config INV3 轮括号的可选配置。零值 = 缺省语义(New 即零值配置)。
type Watcher ¶
type Watcher struct {
// contains filtered or unexported fields
}
Watcher 配对不变量监视器。Run 单协程消费事件通道,无需加锁。
func New ¶
New 构造(pub 必填;nil 时告警静默丢弃——不阻塞事件流)。
缺省配置:closed_by 四值(loop|recovery|boot-reconcile|panic)+ 2h 开放 TTL。
func NewWithConfig ¶ added in v0.38.0
NewWithConfig 带 INV3 配置的构造(additive:New(pub) 的调用面与缺省语义不变)。
cfg 的零值 = New 的缺省语义;ClosedBy 在缺省四值上**扩充**,OpenTTL / SweepEvery <=0 时复用既有 openIdleTTL / sweepEvery。