S10：Registry 与 Audit Trail 的版本生命周期

内容类型：预习教材（不代表已完成）
日期：2026-12-02
阶段：P2 · AI Systems Engineering 90
总路线：Day 100 / 360
周次 / 节奏：W2 · 周三引导练习
状态：教材已备；学习未完成
主题：agentRegistry、auditTrail、lifecycle、history

一句话定义

Registry 保存当前可解析的版本与状态，audit trail 保存状态为何、由谁、在何时改变；二者结合才能同时回答“现在是什么”和“怎样走到这里”。

学习目标

1. 能阅读 agentRegistry 或 auditTrail 的教学代码并识别实体、状态和事件。
2. 能画出 register→candidate→active→deprecated/rolled-back 生命周期。
3. 能区分 current state、immutable history 与 derived view。
4. 能说明版本切换时应关联哪些 actor、reason、evidence 和 previous version。

核心知识

Registry 常维护逻辑实体及多个 immutable version，再由 alias 或状态指出当前候选。Audit trail 应追加记录动作：注册、修改元数据、promotion、rollback、deprecation、权限拒绝等。若只保存当前值，便无法知道此前版本；若只保存事件而没有投影，查询当前状态又会复杂，因此很多系统用事件历史生成当前视图。

版本生命周期不是模型质量分数的同义词。candidate 说明准备比较，active 说明在某个环境或流量范围被采用，deprecated 说明不再推荐，archived 说明保留但不参与选择。一次 rollback 应产生新的审计事件，将 alias 指回已知版本；不应删除失败版本，否则丢失事故证据。

审计字段至少包括 event id、entity/version、action、actor、timestamp、reason、correlation id 与 evidence reference。真实系统还要防篡改、控制敏感数据和定义保留期。本日代码是内存或仓库教学实现，只用来观察语义，不能描述成受监管生产审计系统。

机制与推导

把 registry 当前状态视为事件折叠：

[ state_n=fold(reducer,state_0,[event_1,...,event_n]) ]

每个事件带 expected_previous_version 可实现乐观并发控制：若 alias 已被别人改动，本次切换拒绝或重新读取，避免 lost update。审计历史应 append-only；纠错通过追加 correction event，而非改写旧行。

Rollback 的状态转移是 alias: v3 → v2，但历史顺序不会倒退：新的事件编号仍在 v3 promotion 之后。因此“运行版本回退”和“审计时间回退”是两件事。

最小练习或观察步骤

1. 只读 src/agent/platform/agentRegistry.ts 与 src/aml/auditTrail.ts，标出哪些部分保存状态、哪些保存事件。
2. 不假设已运行；若可运行现有测试或例子，只记录真实输出。
3. 手工构造 v1 注册、v2 candidate、v2 active、回滚 v1 四个事件。
4. 画两个视图：当前 alias 和完整时间线，验证它们回答不同问题。
5. 为并发 promotion 写一个 expected current = v1 前置条件，分析冲突结果。

常见误区与边界

• Audit 记录只写“updated”，没有 previous/new value 与原因。
• Rollback 时删除失败版本，导致无法复盘。
• 把当前 registry 数据库备份当成完整审计历史。
• 允许原地修改 immutable version 内容，版本号不变而语义改变。
• 把教学内存结构夸大为高可用、不可篡改的生产 registry。

系统场景连接

在高风险决策系统中，监管或内部复盘会问：某日某时哪个 bundle 被采用，谁批准，依据哪个评测结果，为何随后回退。Registry 提供版本解析，audit trail 提供决策过程。若人工审批队列也关联同一 correlation id，就能连接系统变更与具体业务影响，而不需要在日志中保存敏感正文。

自检问题

1. Registry current state 与 audit history 为什么不能互相替代？
2. rollback 为什么是一个新事件，而不是删除后来版本？
3. optimistic concurrency 能避免哪类版本切换冲突？
4. 哪些字段可以支持“谁基于什么切换版本”的回答？

专业课程对齐

• 阅读 MLflow Model Registry 文档 中 model versions、aliases、tags 与 lifecycle 操作，映射到当前版本和可变 alias 的区别。
• 阅读 OpenLineage 官方文档 的 run event 与 facets，比较数据处理运行历史和 registry 生命周期事件的共同点与边界。
• 阅读 Stanford CS329S 的 deployment、monitoring 与 continual learning 主题，理解版本切换为何要连接线上反馈和回退路径。

深入学习提示

阅读代码时先画实体和事件，不急着评价类名。尝试从四个事件手算 current state，并检查删除任一事件会丢失什么解释。再制造并发反例：两个操作者都从 v1 promote 不同候选。观察 alias、不可变版本、审计事件与并发前置条件怎样协作。重点是生命周期语义，不是搭建 registry 服务。

学后填写区

• 实际阅读的代码路径：
• 识别出的状态与事件：
• 版本生命周期图：
• 一个并发切换问题：
• 教学实现尚不提供的保证：