Tianyi Cui
a6981c56f6
Traversal ordinals and first-owner paths gave shared persistence types unstable display names. Keep authored names and source locations as metadata, use structural digests for identity, and render complete kind/form groups with bounded array labels. Preserve historical rendering and stored graphs. Record supported source compatibility promises with their property binding, policy version, discriminator, preservation rule, and qualified kind set. The extractor and classifier require explicit opt-ins in both compared schemas; ordinary or unsupported changes retain strict classification. Policy-bearing graphs use the format-2 fingerprint domain while unannotated graphs keep their format-1 fingerprints. Runtime owners activate bindings only with the corresponding reader behavior; this tooling layer activates none and changes no package source or Session generation. Provide a read-only before/after review command that groups shared structural evidence without replacing authoritative compatibility diagnostics. Match changed alternatives only through unique literal discriminators and retain ambiguous additions and removals as independent facts. At the X baseline, all 61 roots and 472 schemas, digests, and source fields are unchanged. The inventory remains format 1 and removes only 296 synthetic names. Existing acknowledgement history still matches every root. All 195 focused tooling tests, Host build/full lint, and bilingual pairing pass.
6.4 KiB
description
| description |
|---|
| 审阅和维护已记录的会话持久化类型变更、对应 schema 快照以及兼容性决策。 |
持久化类型变更记录
English | 中文
概述
本参考文档用于检查已确认的会话持久化类型变更及其前驱。每条记录把兼容性决策绑定到精确的生成 schema。本地检查仅使用当前检出目录中的文件，将当前源码与记录历史比较。修改持久化类型时，从审阅实操手册开始。
较早的 tag 参见预发行版本归档。它重建 alpha/RC 类型差异，供历史阅读和格式校验使用；这些观察记录不作为当前兼容性确认。
按 Session 格式查看完整 schema 时，使用格式参考。其覆盖范围由写入器常量决定，包括没有发布 tag 的中间格式。
目录
文件与职责
生成的目录提供可读声明和摘要；schema 清单包含规范化类型。根覆盖逻辑会话头、物理 JSONL 头行、事件封装以及每个仓库内声明的事件。被引用类型的变更会传递到每个受影响根的摘要。
每条带日期的记录有四个同目录文件：
| 文件 | 职责 |
|---|---|
YYYY-MM-DD-slug.md |
英文确认文档，包含 kind: persistence-change、一份机器声明、兼容性说明和验证证据 |
YYYY-MM-DD-slug.zh.md |
中文对侧文件，包含相同的机器声明 |
YYYY-MM-DD-slug.i18n.yaml |
生成的双语一致性记录 |
YYYY-MM-DD-slug.schema.json |
生成的完整变更后 schema，覆盖受影响且仍然存在的根 |
记录模板定义人工编写的格式。创建记录时可以提供双语说明输入，由命令生成机器声明、快照、目录对和一致性记录。验证器从英文文件读取一次机器声明，并检查中文声明是否相同。声明列出每个受影响的根、其前驱记录、变更后摘要和兼容性决策。新根没有前驱；删除操作没有变更后 schema，并保留显式删除标记。
兼容性规则
每个检测到的结构变更都需要确认。创建和更新记录依据这些固定规则推断最低决策；显式 --decision 是受检查的断言。规则应用于整个变更，因此允许的变更不能掩盖同时发生的破坏性变更。
| 检测到的变更 | 最低决策要求 |
|---|---|
| 添加可选事件体属性，包括其完整子树 | same-version |
| 将必选事件体属性改为可选 | same-version |
| 添加普通事件类型 | same-version |
| 在前后 schema 均带有相同受支持策略的 user/developer 消息源字段中，添加显式声明为归属信息的 kind | same-version |
| 将可选属性改为必选、添加必选属性、更改已有类型，或删除／重命名属性或事件 | version-bump |
| 更改会话头或事件封装 | version-bump |
提取器接受核心拥有的 source 属性上针对 user 或 developer 字面量角色的显式 @persistenceSource 绑定，不会从未标记类型中推断绑定。生产者用 @persistenceAttribution 标记其 MessageSourceMap 成员。该标记承诺：读取器无需生产者即可保留未知 kind 及其 JSON 元数据，且该 kind 不引入校验、回放或权限要求。生产者可以检查自身 kind 来恢复去重状态；其他读取器必须无需该投影也能保留并派生已记录的消息。记录的 schema 保存绑定、策略版本、字面量 kind 判别字段、保留承诺及符合条件的 kind 集合。Inventory format 2 保存这些承诺；没有绑定策略的提取仍使用 format 1。Session 格式版本独立于此。比较双方的快照必须带有兼容的策略状态。已有 kind 分组仍进行常规结构比较；删除、未标记的添加、策略更改及无关破坏性变更继续采用严格规则。同一 wire kind 的多个上下文形式分支归为一组。
同版本说明须解释旧记录为何可以缺少新增内容，以及旧读取器为何可以忽略它而不改变回放。对于必选改可选的变更，说明须解释读取器如何处理缺失值。检查器验证类型分类；审阅者判断说明是否成立。升版本记录在同一转换中包含递增的头部版本，并遵循会话格式流程。
历史与限制
一条基线记录完整的初始清单。后续记录使用前驱的变更后 schema 作为变更前 schema。验证器拒绝缺失前驱、环、同一根的重复后继、摘要不匹配，以及当前根与最新记录不一致的情况。独立的根可以独立演进。同一前驱上的两个变更在集成后需要形成一条有序历史。
已接受记录描述历史转换；添加后继时须保留其机器声明和 schema 快照。尚未接受的末端记录可以显式刷新；命令拒绝基线及被依赖的记录。目录本身无法证明审阅接受状态。验证证明目录内的一致性，不证明历史从未被改写。基线不依赖 Git 引用、远端服务或已发布版本的检出目录。
摘要描述声明的持久化类型，不描述运行时验证或行为。普通注释、源码位置、别名名称和无语义变化的声明重排不影响摘要。兼容性标记是记录的策略数据，会影响摘要。不带标记的版本 1 快照保留原有规范化、指纹和严格分类；包含策略的图使用独立的指纹域。对象字段、联合类型分支、交叉类型操作数和索引签名可以在解析类型不变时重排；元组位置和数字枚举值仍然影响摘要。目录文本和源码位置仍可能变化，因此应重新生成陈旧产物，无需为未变的摘要添加确认记录。unknown 等不透明类型不提供可比较的内部结构。纯行为变更以及不透明值中隐藏的结构不在本机制范围内。决策记录说明这些取舍。
开发备注
维护者的工作上下文——点击展开
无。