In-tree persistence-type history
目录内的持久化类型历史
A persisted event can retain the same payload type expression while a referenced type changes. Reviewing declaration text alone does not expose every nested structural change. A digest detects a difference but cannot explain whether it adds optional data or changes an existing property. Regenerating a catalog also does not establish that the author reviewed the persistence consequences.
English
Problem
A persisted event can retain the same payload type expression while a referenced type changes. Reviewing declaration text alone does not expose every nested structural change. A digest detects a difference but cannot explain whether it adds optional data or changes an existing property. Regenerating a catalog also does not establish that the author reviewed the persistence consequences.
Decision
The reader-compatibility review decision supersedes the automatic version floor. This note owns normalized type history, per-root acknowledgements, and accepted checkpoint preservation.
One normalized type model supplies the readable persistence catalog, the complete schema inventory, and transitive per-root digests. Roots identify the logical Session header, the physical JSONL header line, the event envelope, and every repository-declared event. Source locations, alias names, ordinary comments, and property order are presentation details outside the digest. Explicit compatibility annotations carry fingerprinted policy data under the source-attribution policy. Historical records retain source file paths without line numbers because their selected source trees differ from the current checkout. Referenced and recursive types participate in structural comparison; opaque values retain explicit coverage limits.
The dedicated persistence-change records bind acknowledgement to the after digest of each affected root. A generated companion stores complete after schemas. The initial record covers all roots; later records name each root's predecessor. A predecessor's after schema supplies the next before schema. Verification rejects ambiguous history and requires current source to match the terminal recorded state without consulting Git history or remote services.
Automatic classification permits optional body additions, required-to-optional body changes, and ordinary event additions within one version. The scoped source-attribution policy also permits qualified new producer kinds when both saved schemas opt in. The event-payload version rule admits higher numeric payload versions when every old alternative remains readable and records the older-reader limitation. Other structural changes require an explicit same-version choice in the recording CLI or an increasing header version. Every structural difference needs an acknowledgement; its Compatibility and Verification sections explain both reader directions and executed checks. CI validates saved decisions without inferring how they were authored. The format-version procedure owns adjacent migration work when a bump is required.
The persistence-change document kind preserves compatibility reasoning and evidence for a historical type transition. Agent Notes retain mechanism-level decisions; they do not become a growing inventory of individual acknowledgements. Machine declarations remain identical across the bilingual pair and are parsed once.
Retrospective release comparisons use a separate persistence-release kind and pinned tag manifest. They retain changed after schemas and reconstruct adjacent releases, including unchanged tags. Earlier releases predate these acknowledgement rules, so their classifications are informational and their observed versions are not rewritten to satisfy a modern version floor. Historical parsing preserves optional surface operations; the current parser and acknowledgement chain remain strict. This separation permits approximate backfills without turning them into authorization for current changes.
The format references preserve complete inventories for every historical integer below the writer constant. The current writer retains the existing generated catalog. Coverage is derived from the constant rather than a hand-maintained version manifest, so advancing the writer requires archiving its predecessor. The archive command copies the validated current inventory, retains its root-reachable definitions, removes source line numbers, and refuses to overwrite an existing snapshot. Source checkpoints remain explicit because event additions and optional payload changes can occur within one format; these snapshots do not authorize current changes or claim migration safety. Historical identifiers and source package paths are retained in machine schemas and exactly generated schema regions, while current terminology and package-path checks still cover the surrounding authored prose and current catalogs.
Record commands generate the bilingual catalog and consistency records from repository-owned templates. Authors can supply the two languages' summary, compatibility reasoning, and actual verification evidence as structured input. Generation supplies identifiers, digests, and snapshots; it never invents a compatibility explanation or test result. Structured check output retains a nonzero failure exit status and reports stable change kinds independently of human-readable descriptions.
Explicit update refreshes an unaccepted terminal record without deleting its authored prose. It recomputes the transition against the remaining history and rejects the baseline, any record with dependants, or a finalized record. Review acceptance outside finalized checkpoints is not inferred from the tree, so authors preserve accepted records and add successors.
Finalized checkpoints
Finalization records acceptance independently of publication. The status record requires a complete compatibility checkpoint that locks accepted machine declarations and after schemas. Further schema changes need new acknowledgements; an explicit version-bump decision must contain its own header increase and cannot reuse an accepted transition. The checkpoint adds no runtime field, does not change unknown-event handling, and cannot detect behavior changes hidden behind unchanged declarations. Coordinated edits to the in-tree authority and checkpoint still require review.
Alternatives considered
Hash the displayed declarations. Referenced definitions can change without altering the displayed expression. Normalized transitive types make those changes visible while omitting source-file and alias churn.
Bind every acknowledgement to one overall digest. An unrelated event change would invalidate a reviewed acknowledgement. Per-root history limits invalidation to the affected header or event while the complete inventory retains coverage.
Compare with the PR merge-base or a release checkout. Those inputs require history outside the current tree. Retained after schemas provide the comparison input to local checks and CI alike. A hash without its schema cannot support automatic structural classification.
Treat every changed digest as a version bump. Optional body additions, required-to-optional changes, and ordinary event additions do not always require a new persistence version. Conservative classification distinguishes these cases and leaves the compatibility explanation to review.
Infer behavior from types or require proof of human review. A type graph cannot establish replay semantics, and a recorded choice cannot establish how it was authored. The checker validates declared transitions and header-version constraints. Reviewers inspect actual reader behavior and the acknowledgement’s explanation independently.
Consequences
Authors retain one snapshot per affected root per accepted transition and resolve history forks when integrating competing changes to that root. Independent roots can advance without rewriting unrelated acknowledgements. The cookbook provides the local authoring and verification procedure.
The checks prove current-tree consistency, not that accepted history was never rewritten or that an explanation is semantically correct. Hidden structures inside unknown and similar opaque values remain undetectable. This mechanism adds no runtime digest or Session-format field. Existing versioning and released-generation migration decisions retain their independent runtime guarantees.
中文
问题
持久化事件可以保留相同的载荷类型表达式，但其引用的类型已经改变。只审阅声明文本无法暴露所有嵌套结构变更。摘要能检测差异，却不能说明它是添加可选数据还是更改已有属性。重新生成目录也不能证明作者已审阅持久化方面的影响。
决策
读取器兼容性评审决策取代自动最低版本要求。本说明负责规范化类型历史、逐根确认与已接受检查点保留。
一个规范化类型模型提供可读持久化目录、完整 schema 清单和包含传递引用的逐根摘要。根标识逻辑会话头、物理 JSONL 头行、事件封装以及每个仓库内声明的事件。源码位置、别名名称、普通注释和属性顺序属于摘要之外的展示细节。历史记录保留源码文件路径而不包含行号，因为其选定的源码树与当前工作树不同。被引用类型和递归类型参与结构比较；不透明值保留明确的覆盖限制。显式兼容性标记依照消息源归属策略携带纳入指纹的策略数据。
专用的持久化变更记录将确认绑定到每个受影响根的变更后摘要。生成的伴随文件保存完整的变更后 schema。初始记录覆盖所有根；后续记录为每个根指定前驱。前驱的变更后 schema 提供下一次的变更前 schema。验证拒绝有歧义的历史，并要求当前源码匹配最终记录状态，无需查询 Git 历史或远端服务。
自动分类允许可选事件体新增、事件体属性从必选改为可选，以及普通事件新增保持同一版本。当双方保存的 schema 均声明支持时，受限的消息源归属策略也允许添加符合条件的生产者 kind。事件载荷版本规则允许在每个旧分支仍可读取时增加更高的数字载荷版本，并记录旧读取器限制。其他结构变更要求在记录 CLI 中显式选择同版本，或递增头版本。每个结构差异都需要确认；其兼容性与验证部分说明两个方向的读取器行为及已执行检查。CI 验证保存的决策，不推断其编写方式。需要升版本时，格式版本流程负责相邻迁移工作。
持久化变更文档类型保留历史类型转换的兼容性说明和证据。Agent Note 保留机制层面的决策，不积累单次确认清单。双语对中的机器声明保持相同，且只解析一次。
回溯性的发行版本比较使用独立的 persistence-release 类型和固定 tag 清单。它们保留变化后的 schema，并重建相邻版本，包括未变的 tag。早期版本先于这些确认规则，因此其分类只提供信息，观察到的版本号不会为满足当前最低版本要求而被改写。历史解析保留可选的 surface 操作；当前解析器和确认链仍保持严格。这一区分允许近似回填，同时不会将其变成当前变更的授权。
格式参考为低于写入器常量的每个历史整数版本保留完整目录。当前写入器继续使用现有生成目录。覆盖范围由常量推导，而非手工维护的版本清单，因此推进写入器必须归档其前驱。归档命令复制已验证的当前目录，保留从根类型可达的定义，移除源码行号，并拒绝覆盖已有快照。同一格式内可能新增事件或改变可选载荷，因此来源检查点保持明确；这些快照不授权当前变更，也不声称迁移安全。机器 schema 与精确生成的 schema 区间保留历史标识符和源码包路径；当前术语与包路径检查仍覆盖周围的人工说明和当前目录。
记录命令从仓库内模板生成双语目录和一致性记录。作者可以将两种语言的概述、兼容性说明和实际验证证据作为结构化输入。生成过程提供标识符、摘要和快照，不编造兼容性说明或测试结果。结构化检查输出保留非零失败退出码，并报告独立于可读描述的稳定变更种类。
显式更新可刷新尚未接受的末端记录，无需删除其人工说明。它根据剩余历史重新计算转换，并拒绝基线、已有依赖方的记录或已定稿记录。目录不会推断定稿检查点之外的审阅接受状态，因此作者保留已接受记录并添加后继。
定稿检查点
定稿独立于发布事实记录接受状态。状态记录要求完整兼容性检查点，锁定已接受的机器声明与变更后 schema。后续 schema 变化需要新的确认；显式升版本决策必须包含自身的头版本递增，不能复用已接受转换。检查点不添加运行时字段，不改变未知事件处理，也不能检测未变声明后隐藏的行为变化。对目录内真源与检查点的协同修改仍须审阅。
考虑过的替代方案
对展示的声明计算哈希。 被引用的定义可能改变，而展示的表达式保持不变。规范化传递类型使这些变更可见，同时排除源文件和别名调整。
将每次确认绑定到一个整体摘要。 无关事件的变更会使已审阅的确认失效。逐根历史将失效范围限制在受影响的头部或事件，完整清单仍然保留覆盖范围。
与 PR 的 merge-base 或发布版本检出目录比较。 这些输入需要当前目录之外的历史。保留的变更后 schema 为本地检查和 CI 提供相同的比较输入。没有 schema 的哈希无法支持自动结构分类。
把每次摘要变化都视为升版本。 可选事件体新增、必选改可选，以及普通事件新增不一定需要新的持久化版本。保守分类区分这些情况，并将兼容性说明交给审阅。
从类型推断行为，或要求人类评审证明。 类型图无法证明回放语义，所记录的选择也无法证明其编写方式。检查器验证声明的转换与头版本约束。评审者独立检查实际读取器行为与确认说明。
影响
作者为每次已接受转换中的每个受影响根保留一份快照，并在集成该根的竞争变更时解决历史分叉。独立根可以演进而不改写无关确认。实操手册提供本地编写与验证流程。
检查证明当前目录的一致性，不证明已接受历史从未被改写，也不证明说明在语义上正确。unknown 等不透明值内部的隐藏结构仍然无法检测。本机制不添加运行时摘要或会话格式字段。现有版本机制和已发布代际迁移决策保留其独立的运行时保证。