# 无损遍历

*构建元模型 · 第 3 课，共 6 课 · 约 15 分钟*

## 你将学到

遍历契约（ARCH-017）：模型如何保证任何读者都能访问到每一个文件、知道每一个文件的含义，并证明没有遗漏。

## 为什么"全部读完"需要一份契约

一个模型的可信程度，取决于读者能否确知自己已经看完了它。没有契约，每个读者都在即兴发挥：略读一些目录，漏掉另一些，凭猜测判断文件含义。智能体更糟：一个悄悄跳过某个目录的智能体，会像没跳过一样自信作答。ARCH-017 把勤勉变成了机制。

## 遍历声明

遍历顺序是数据，自上而下声明：

- 仓库清单声明**有序的包列表**（按依赖顺序，基础在前；存在环即不合规）。
- 每个包声明它有序的层；每个层枚举其内容，并给出**种类**与一行含义。
- 文件名按约定已携带种类的仓库，可以改为在清单中声明**集中式规则**：有序的 glob 模式映射到种类，首个匹配胜出，并带有 `{prefix}` 占位符，于是像 `kind: "object/{prefix}"` 这样一条规则就能分类整套命名约定。

给定同一个仓库版本，两个遍历器必须以相同顺序访问相同文件：规范遍历是确定性的。

## 完备性规则

仓库中的每个文件都恰好落入三类之一：

1. **已枚举**：与某条声明或分类规则匹配；
2. **约定位置**：位于保留位置（canon/、raw/、artifacts/、bootstrap）并继承其含义；
3. **已排除**：被明确列为不承载模型含义（版本控制内部文件、编辑器配置）。

遍历器会把完整的递归文件清单与这三类的并集作比较。不属于任何一类的文件是**孤儿**；同时属于两类的则是歧义；两者都算结构校验失败。为了通过检查而排除语义内容属于不合规：排除清单是一份声明，不是垃圾堆。

## 种类与来源

每个已分类的文件都带有一个**种类**（它*在模型中*是什么：对象、事件、契约、正典、原始、制品、文档、工具……）与一个**来源**：撰写、采集或生成。来源决定可编辑性：撰写型文件就地编辑；采集型与生成型文件永远不可：修改属于源头或生成器。正是这一条区分，让后来的数据主权归属得以强制执行。

## 跑遍历器是什么感觉

两个生产模型都随附了遍历器（`tools/mu-walk.ps1`），它执行规范遍历并把报告写入 `artifacts/`。来自一线：

- Orkestron.AI 模型：613 个文件，0 个孤儿。首次运行什么也没查出来：一个小而自律的仓库。
- DevTeam.Games 模型：磁盘上 2613 个文件，包括被 git 忽略的证据和 146 MB 挂接的源码镜像。首次运行找出了 **47 个真正的孤儿**：没有人声明过的设计原型与界面素材，以及一条记录，它的种类前缀（`i18n`）打破了一个过于天真的分类正则。每一个孤儿都变成了一条*规则*，而不是一个例外：地图因此更接近真相。
- 两个遍历器都做了反向测试：放进一个游离文件，遍历就以退出码 1 失败并点名它。

这就是回报："什么都没丢"不再是一种指望，而成为你在信任一个模型之前可以要求看到的绿灯，也是你能以绿色状态交给下一场会话的东西。

## 要点

- 顺序被声明，分类是全覆盖的，覆盖率会被检查：孤儿会让构建失败。
- 种类说明文件是什么；来源（撰写/采集/生成）说明你是否可以编辑它。
- 真实仓库都能通过：遗留布局、二进制素材与巨大的镜像，都能用少数几条规则分类。

## 深入阅读

- [模型遍历与约定位置（ARCH-017）](/spec/#02-architecture/Model-Traversal-and-Layout.md)
- [校验级别 V0-V5](/spec/#02-architecture/Validation.md)

下一课：[数据主权归属](04-mastership.md)