import Spec.Prelude
import Spec.System.Run

/-!
# Lock —— 项目锁与排他不变式

ADR-0002 的核心:防止并发 Claude 执行同时改一个项目,而锁的 **owner 是当前
`AgentRun`**(不是 teacher / chat / session)。本模块把这条决策编码进类型,并钉死
likec4 画不出的那条语义不变式——**持锁者必为非终止 run**。
-/

namespace Spec.System

variable (I : Identifiers)

/--
项目级锁(`PINNED`, ADR-0002)。

`owner` 的类型是 `RunId` 而非 `SessionId`/`Principal`——这从类型上编码 ADR-0002
"lock owner = run_id":锁不可能被一个 session 或 teacher 持有。`scope` 为项目级
(一个项目一把锁,见 `LockTable`)。
-/
structure ProjectAgentLock where
  /-- 锁的作用域:项目级(`PINNED`, ADR-0002 `scope = project_id`)。 -/
  scope : I.ProjectId
  /-- 锁的持有者:一个 run(`PINNED`, ADR-0002 `owner = run_id`)。 -/
  owner : I.RunId

/--
锁表:每个项目当前的持锁 run(`PINNED` 排他性, ADR-0002)。

`Option` 编码"每项目至多一把锁":`none` = 无活动 run 占用,`some r` = run `r`
正持有。这个 `ProjectId → Option RunId` 的结构**本身**即排他——不可能为同一项目
登记两个并发 owner。
-/
def LockTable := I.ProjectId → Option I.RunId

/--
锁表良构:**持锁者必为非终止 run**(`PINNED` 平台核心不变式, ADR-0002)。

ADR-0002 说锁在 run 终止时释放。其逻辑等价物:任何时刻,若项目 `p` 的锁被 `r`
持有,则 `r` 不在终止态。`statusOf` 给出每个 run 的当前状态。

这条不变式把 **Lock 与 Run 两个实体耦合**起来——likec4 能画"run owns lock while
running"这条边,但画不出"终止即必须释放"这个**约束**;它正是契约相对结构图的增量。
-/
def LockTable.WellFormed
    (lt : LockTable I) (statusOf : I.RunId → RunState) : Prop :=
  ∀ p r, lt p = some r → ¬ (statusOf r).Terminal

end Spec.System