// Package urgency 定义 Cyrene 全局通用的「事件紧急度」词汇，以及事件生产者声明它
// 的契约。
//
// 它是一条**通用通道**：任何事件生产者 —— IoT（第一个使用者，规则表见
// internal/iot/safety.go）、其它外围插件、系统 / 能力模块 —— 都可以在发布到进程内
// bus 的载荷上实现 Declarer，声明「这次事件有多紧急」。backthink 在唯一一处
// （trigger.go 的 foldDeclared —— 由 triggerForEvent 与 selfWakeTrigger 共用）把该声明
// 与既有的 SystemEvent.Import 口径一起折算
// 进 Trigger.Import，因此安全域（critical）事件能穿透安静时段与工作 / 忙碌
// （design/12 §2 §6 安全域豁免，裁决 1.8 / 07.4.2），而 backthink 绝不需要认识任何
// 生产者（IoT 或插件）的专有字段。
//
// 本包刻意是叶子包（只依赖 fmt）：生产者不必为了声明紧急度而依赖 backthink
// （backthink 依赖 iot，那样会成环），backthink 也不必为每个生产者各加一条分支。
package urgency

import "fmt"

// Level 是一次事件的显式紧急度，由产生该事件的生产者 *显式* 声明。零值是
// LevelRoutine，因此未声明紧急度的事件一律落在例行档：本通道不会让常规事件获得
// 穿透安静时段的资格（默认保守，design/12 §6 安全域豁免的反面保证）。
//
// 它只回答「这次事件有多紧急」，不表达身份、权限或能力边界 —— 身份与权限永远由
// channel 层的 actor 元数据与策略引擎决定。
type Level int

const (
	// LevelRoutine 是例行变化（普通设备状态跃迁、低价值系统噪声）。它折算为
	// backthink 的 ImportanceNormal：安静时段照常扣下。
	LevelRoutine Level = iota
	// LevelWarning 是值得注意但非安全域的异常（设备离线、耗材将尽）。它折算为
	// ImportanceHigh：沿袭既有级联语义通过安静时段，但不穿透工作 / 忙碌。
	LevelWarning
	// LevelCritical 是安全域事件（入侵、门锁异常开启、烟雾 / 漏水告警）。
	// 它折算为 ImportanceCritical：穿透安静时段与工作 / 忙碌。
	LevelCritical
)

// String 返回用于日志与记录（审计轨迹、思考记录、前端小字）的稳定标签。
func (l Level) String() string {
	switch l {
	case LevelRoutine:
		return "routine"
	case LevelWarning:
		return "warning"
	case LevelCritical:
		return "critical"
	default:
		return fmt.Sprintf("urgency(%d)", int(l))
	}
}

// Declarer 是「事件载荷自带紧急度」的通用契约。事件载荷实现它，backthink 就会在
// 通用通道上承认其声明的紧急度，无需为该生产者另加分支 —— 生产者有多少个都不影响
// 判定侧的形状。
//
// 实现方应当保持保守：只有语义上确属安全域的事件才返回 LevelCritical，其余一律
// 落在零值 LevelRoutine（那样安静时段照常扣下）。
type Declarer interface {
	// Urgency 返回这次事件的紧急度；未声明时返回零值 LevelRoutine。
	Urgency() Level
}