/-!
# Run —— AgentRun 状态机

一次 `@Claude` 创建一个 `AgentRun`(ADR-0001),它在生命周期里经历若干状态,并在
**终止时释放项目锁**(ADR-0002)。本模块固定 run 的**状态**与**终止判定**——后者
是 Lock 排他不变式(见 `Spec.System.Lock`)的依赖。

完整的合法转移关系**未在任何 ADR / likec4 散文里定下**,故本模块不臆造转移边,
只刻画状态本身与"何为终止"。
-/

namespace Spec.System

/--
AgentRun 的运行状态(状态名 `PINNED` 取自 ADR-0001..0003 + likec4 散文;
**集合完整性 `OPEN`**)。

各状态来源:`active`(run 进行中)、`waitingForUser`(likec4 Run Orchestrator
"等待用户")、`completed` / `failed` / `timedOut` / `canceled`(ADR-0002 列出的
释放锁时机)。

⚠ **完整性是 OPEN**:散文从未声明"状态恰好这些"。这里用 `inductive` 是为了能
谈终止判定与不变式,**不等于**封闭授权——若实现侧发现还需要别的状态(如排队中
的 pending),那是一个待 surface 的分歧点,**不得**默认本枚举已穷尽。这与
element-kind 那种**明示开放**的宇宙性质不同:那里"开放"是决策,这里"未封闭"是
尚未决策。
-/
inductive RunState where
  | active
  | waitingForUser
  | completed
  | failed
  | timedOut
  | canceled

/--
run 处于**终止态**(`PINNED`, ADR-0002)。

ADR-0002 钉死:锁在 run `completes / fails / times out / is canceled` 时释放。
这四个状态即终止态;锁的释放时机由它定义(见 `Spec.System.Lock.LockTable.WellFormed`)。
`active` 与 `waitingForUser` 非终止——后者虽在等待,run 仍占用项目(锁未释放)。
-/
def RunState.Terminal : RunState → Prop
  | .completed | .failed | .timedOut | .canceled => True
  | .active | .waitingForUser => False

end Spec.System