forked from EduCraft/curriculum-project-hub
feat(spec): build out System layer and element schema model
Picture the whole framework, then pin the element-kind language layer. System platform layer — rebuild the semantics likec4 can't draw (ADR-0001..0004): - Prelude: opaque Identifiers carrier (ProjectId/RunId/SessionId/Principal) - System/Run: RunState + Terminal subset (set completeness left OPEN, no invented pending) - System/Lock: lock owner=run (typed), LockTable exclusivity, WellFormed invariant (a lock holder must be a non-terminal run — couples Lock and Run) - System/Permission: read<edit<manage role lattice, capability derivation, can_mono monotonicity theorem; force-release sits outside the lattice (admin-only) - System/Audit: intentionally thin (mostly plumbing, OPEN) Courseware product layer — split the single Lesson file into focused modules and fix doc tautology: Primitives / Element / Lesson / Render / Diagnostic, plus QuestionBank and Course skeletons (core relations OPEN, not invented). Diagnostic upgrades WarnsIgnored into a severity-tagged checker rule. Element schema + rich-content model (ADR-0006, ADR-0007): - docs/adr/0006: kind schema is declarative JSON Schema; field types are built-in scalars plus a `content` extension; a `content` value is typst source taken as module body; rich content must carry a VirtualPath (else click-to-jump and relative import break — verified against typst source); import boundary = within the engineering file + @package - docs/adr/0007: on-disk form is a real directory tree (agent/grep friendly); VirtualPath = real relative path; layout conventions deferred - spec/Courseware/RichContent: prose anchor for rich content (opaque VPath, RichContentRef); ElementData kept abstract — JSON/typst internals are implementation detail, not contract lake build green (18 jobs), no sorry, toolchain v4.31.0. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,27 @@
|
||||
import Spec.Prelude
|
||||
|
||||
/-!
|
||||
# Audit —— 审计日志(有意从简)
|
||||
|
||||
likec4 把 `AuditLog` 列为实体:`AgentRun -> AuditLog 'records lifecycle events'`,
|
||||
admin 经控制台审计。但**审计记录里装什么**(事件 schema、保留策略、可查询维度)
|
||||
在任何 ADR / 散文里都未决策,且大多是 plumbing——按分歧点测试**不入契约**:写明
|
||||
与否不会让开发者与 agent 各做不同假设。
|
||||
|
||||
故本模块**刻意几乎为空**:只固定一条已决策的关系——审计以 run 为主体记录其生命
|
||||
周期事件——其余 `OPEN`。这里留白本身是契约的一部分(承诺"此处尚无答案,勿填")。
|
||||
-/
|
||||
|
||||
namespace Spec.System
|
||||
|
||||
/--
|
||||
审计条目的最小骨架(关系 `PINNED` / 内容 `OPEN`, likec4 `records lifecycle events`)。
|
||||
|
||||
只承诺"一条审计记录关联到某个 run"。事件类型、时间、actor、详情等字段**未定**
|
||||
(`OPEN`),待出现真实分歧点(如"取消必须记录 actor")时再由对应 ADR 落定。
|
||||
-/
|
||||
structure AuditEntry (I : Identifiers) where
|
||||
/-- 该审计条目所属的 run(`PINNED` 关系, likec4)。 -/
|
||||
run : I.RunId
|
||||
|
||||
end Spec.System
|
||||
@@ -0,0 +1,51 @@
|
||||
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
|
||||
@@ -0,0 +1,99 @@
|
||||
import Spec.Prelude
|
||||
|
||||
/-!
|
||||
# Permission —— 角色、能力与授权
|
||||
|
||||
ADR-0004:权限走"飞书云文档式"——**协作者授权(grant)与操作设置(settings)
|
||||
分离**;grant 是 `resource + principal + role`,role 取自封闭的 `read / edit /
|
||||
manage`,且 **read ⊂ edit ⊂ manage** 累积赋能;强制释放锁是 **admin-only**,在
|
||||
role 体系之外。本模块把这套结构与"高 role 含低 role 全部能力"的单调性钉死。
|
||||
-/
|
||||
|
||||
namespace Spec.System
|
||||
|
||||
/--
|
||||
协作者角色(`PINNED` 封闭, ADR-0004 逐字 "roles are read, edit, or manage")。
|
||||
|
||||
与 element-kind / RunState 不同,这里 ADR **明示**只有三个 role,故 `inductive`
|
||||
是封闭授权,不是"尚未封闭"。
|
||||
-/
|
||||
inductive Role where
|
||||
| read
|
||||
| edit
|
||||
| manage
|
||||
|
||||
/--
|
||||
角色的**赋能层级**(`PINNED` 序, ADR-0004 read⊂edit⊂manage)。
|
||||
|
||||
把 ADR-0004 的累积包含关系数值化:read=0 ⊂ edit=1 ⊂ manage=2。它只服务于下面的
|
||||
`Role.le` 与能力推导,不对外承诺"层级就是个 `Nat`"。
|
||||
-/
|
||||
def Role.level : Role → Nat
|
||||
| .read => 0
|
||||
| .edit => 1
|
||||
| .manage => 2
|
||||
|
||||
/-- 角色偏序:`r₁ ≤ r₂` 即 `r₁` 赋能不强于 `r₂`(`PINNED`, ADR-0004)。 -/
|
||||
def Role.le (r₁ r₂ : Role) : Prop := r₁.level ≤ r₂.level
|
||||
|
||||
/--
|
||||
受 role 调控的操作能力(项 `PINNED` 取自 ADR-0004;**枚举完整性 `OPEN`**)。
|
||||
|
||||
逐项来源于 ADR-0004 对各 role 的展开:`view`(read);`discussComment` /
|
||||
`editArtifact` / `triggerAgent` / `answerChoiceCard`(edit);`manageCollaborators`
|
||||
/ `projectSettings` / `groupBinding` / `normalCancel`(manage)。
|
||||
|
||||
⚠ **完整性 OPEN**:这是 ADR 当前点名的能力,不保证穷尽;新增产品操作时可能扩。
|
||||
注意 **force-release 不在此列**——它是 admin-only override,见 `RequiresAdmin`。
|
||||
-/
|
||||
inductive Capability where
|
||||
| view
|
||||
| discussComment
|
||||
| editArtifact
|
||||
| triggerAgent
|
||||
| answerChoiceCard
|
||||
| manageCollaborators
|
||||
| projectSettings
|
||||
| groupBinding
|
||||
| normalCancel
|
||||
|
||||
/--
|
||||
某能力所**要求的最低角色**(`PINNED`, ADR-0004 各 role 的能力展开)。
|
||||
|
||||
read 级仅 `view`;edit 级是讨论/评论、编辑产物、触发 Claude、应答 choice card;
|
||||
manage 级是协作者管理、项目设置、群绑定、常规取消。授权判定 `Role.can` 据此定义,
|
||||
从而"谁能做什么"只有这一处真相。
|
||||
-/
|
||||
def Capability.requiredRole : Capability → Role
|
||||
| .view => .read
|
||||
| .discussComment | .editArtifact | .triggerAgent | .answerChoiceCard => .edit
|
||||
| .manageCollaborators | .projectSettings | .groupBinding | .normalCancel => .manage
|
||||
|
||||
/--
|
||||
角色 `r` **具备**能力 `c`(`PINNED`, ADR-0004)。
|
||||
|
||||
定义为"`c` 要求的最低角色 ≤ `r`"。这一处定义同时编码了 read⊂edit⊂manage 的累积性:
|
||||
manage 自动具备所有 edit / read 能力,无需逐条列举。
|
||||
-/
|
||||
def Role.can (r : Role) (c : Capability) : Prop := c.requiredRole |>.le r
|
||||
|
||||
/--
|
||||
**单调性**:角色越高,能力只增不减(`PINNED` 定理, ADR-0004 累积赋能)。
|
||||
|
||||
这是 read⊂edit⊂manage 的形式化保证:若 `r₁ ≤ r₂` 且 `r₁` 能做 `c`,则 `r₂` 也能。
|
||||
证明即偏序传递性——之所以成立得这么干净,正因为 `can` 是按"最低角色阈值"定义的。
|
||||
-/
|
||||
theorem Role.can_mono {r₁ r₂ : Role} {c : Capability}
|
||||
(h : r₁.le r₂) (hc : r₁.can c) : r₂.can c :=
|
||||
Nat.le_trans hc h
|
||||
|
||||
/--
|
||||
**强制释放锁**要求 admin,**在 role 体系之外**(`PINNED`, ADR-0004 admin-only override)。
|
||||
|
||||
ADR-0004 明确:force release 卡住的锁是异常操作,不是任何协作者 role 的能力——
|
||||
即便 `manage` 也不经由 `Role.can` 获得它。故它不是一个 `Capability`,而是这样一个
|
||||
独立谓词:仅当主体是 admin 时成立。`isAdmin` 由平台另行判定(本层不建 admin 模型)。
|
||||
-/
|
||||
def RequiresAdmin (isAdmin : Prop) : Prop := isAdmin
|
||||
|
||||
end Spec.System
|
||||
@@ -0,0 +1,47 @@
|
||||
/-!
|
||||
# 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
|
||||
Reference in New Issue
Block a user