Session versions follow reader compatibility
Session 版本取决于读取器兼容性
A structural schema difference does not establish that a Session needs a new integer version. An optional environment header field illustrates the cost: sessions that omit the feature can retain identical logs, while sessions that require it can be refused by older readers. A global bump also excludes feature-free sessions and requires a new generation and adjacent migration. Conversely, an unknown field or value doe
English
Problem
A structural schema difference does not establish that a Session needs a new integer version. An optional environment header field illustrates the cost: sessions that omit the feature can retain identical logs, while sessions that require it can be refused by older readers. A global bump also excludes feature-free sessions and requires a new generation and adjacent migration. Conversely, an unknown field or value does not establish safe refusal: permissive readers can ignore required meaning, and recovery can mistake unsupported records for damaged tails.
Decision
The user chose reader behavior as the version criterion. A same-version change is permitted when older readers either resume correctly, safely ignore optional features while preserving their records, or refuse required features before execution, mutation, or tail repair. Feature absence must preserve existing behavior. Required-feature refusal needs an upgrade diagnostic; already released binaries retain their existing diagnostics, so review identifies any limitation explicitly.
New readers preserve the meaning of supported historical records and accept valid mixtures of old and new representations within one Session. Removing a required field or changing its representation is not automatically a bump: the replacement must remain distinguishable, and released-reader behavior must satisfy the same admission requirements. A version increase is required when no effective existing discriminator prevents unsafe interpretation. Reusing a logged value with a different meaning is one example; missing admission checks are another.
The schema classifier identifies structural changes requiring compatibility review instead of declaring them inherently version-breaking. Every schema difference still needs an acknowledgement. Established safe cases infer same-version; other same-version changes require an explicit decision when recording or updating. The existing Compatibility and Verification sections record reader behavior and executed checks. The checker validates the decision and recorded schemas; it cannot prove that the explanation matches runtime behavior. An explicit version-bump decision still requires its own increasing SessionHeader.version. Accepted machine records and checkpoints remain immutable; prose remains outside checkpoint hashes.
The user treats a recorded same-version decision as explicit regardless of whether the CLI or an editor produced it. The CLI requires --decision same-version for flagged record and update operations; CI validates the saved decision against history, schemas, and header-version constraints. Neither mechanism attests that a human reviewed the transition. Reviewers use base/head inventory comparison rather than current-tree consistency checks to inspect already acknowledged changes.
This decision partially supersedes the structural bump criterion in the version-mechanism note and the automatic version floor in the persistence-type-history note. Their monotonic integer, required unknown-event default, type history, and immutable generation decisions remain active. The review procedure owns authoring and validation details.
Migration obligations
One codec per integer version and one migration per adjacent pair remain sufficient. A version's reader supports its released representations without changing established meanings; an eventual successor migration accepts that same historical range, including mixed records. Historical conversion can keep producing a valid older representation within the target version. Same-version reads do not run an adjacent migration, so a compatibility claim cannot depend on an unimplemented normalization step. Header and payload extensions still need feature-specific admission and preservation through their actual consumers.
Alternatives considered
Require bumps for header changes and other structural edits. This mechanically excludes safe refusal and optional features, imposing migration work even when existing discriminators already protect readers.
Treat every unknown field or value as a refusal mechanism. Released readers do not uniformly reject unknown values before recovery. Compatibility evidence must inspect the actual admission and mutation paths; a changed schema alone supplies no guarantee.
Permit same-version changes without recorded reader evidence. A schema graph cannot establish safe execution, lossless retention, historical interpretation, or mixed-record behavior. Explicit review preserves these obligations without making the classifier pretend to prove them.
Add a separate JSON review object and hash its evidence. The user rejected duplicating the existing Compatibility and Verification prose. Extra input fields and renewal rules add authoring work without establishing semantic safety. An explicit same-version choice and the existing acknowledgement keep the decision visible without a second evidence format.
Consequences
The rule reduces unnecessary version transitions while making old-reader and new-reader evidence explicit. It changes review and acknowledgement enforcement, not runtime admission, diagnostics, codecs, or migration behavior. The environment example motivates the policy; it does not add an env field. Unsupported-feature detection, payload readers, and any necessary migration work remain obligations of each feature change. Focused verification must cover feature absence, optional retention or required refusal, historical input, and mixed representations as applicable; a written review is not a substitute for those results.
中文
问题
schema 的结构差异不能证明 Session 需要新的整数版本。可选的环境头字段体现了这一成本：未使用该特性的会话可以保留完全相同的日志，需要该特性的会话则可以被旧读取器拒绝。全局升版本也会排除未使用特性的会话，并要求新的代际和相邻迁移。反过来，未知字段或值不能证明拒绝是安全的：宽松读取器可能忽略必需的含义，而恢复流程可能把不支持的记录误判为损坏的尾部。
决策
用户选择以读取器行为作为版本标准。当旧读取器能够正确恢复、安全忽略可选特性并保留其记录，或在执行、修改及尾部修复之前拒绝必需特性时，允许保持同一版本。未使用特性时必须保留现有行为。拒绝必需特性需要升级提示；已发布二进制保留其现有诊断，因此评审明确标出相关限制。
新读取器保留受支持历史记录的含义，并接受同一 Session 中新旧表示的有效混合。删除必需字段或改变其表示不自动要求升版本：替代表示必须可区分，已发布读取器的行为必须满足相同的准入要求。当不存在能够阻止不安全解释的有效既有判别标记时，必须升版本。将日志值复用于不同含义是一例；缺少准入检查是另一例。
schema 分类器标识需要兼容性评审的结构变更，而不将其直接判定为版本破坏。每项 schema 差异仍须确认。已明确安全的情形推断为同版本；其他同版本变更在记录或更新时要求显式决策。已有的兼容性与验证部分记录读取器行为和已执行检查。检查器验证决策与所记录的 schema，但无法证明说明与运行时行为一致。显式升版本决策仍须包含其自身递增的 SessionHeader.version。已接受的机器记录与检查点保持不可变；说明文字不参与检查点哈希。
用户将记录中的 same-version 决策视为显式选择，无论它由 CLI 还是编辑器产生。CLI 对被标记的记录与更新操作要求 --decision same-version；CI 按历史、schema 和头版本约束验证保存的决策。两种机制都不证明人类已评审转换。评审者使用 base/head 清单比较，而非当前目录一致性检查，来检查已确认的变更。
本决策部分取代版本机制说明中的结构性升版本标准，以及持久化类型历史说明中的自动最低版本要求。它们的单调整数、未知事件默认必需、类型历史与不可变代际决策仍然有效。评审流程负责记录编写与验证细节。
迁移义务
每个整数版本一个 codec、每组相邻版本一个迁移仍然足够。一个版本的读取器支持其已发布表示，且不改变已确立的含义；后继迁移接受相同的历史范围，包括混合记录。历史转换可以继续产生目标版本内有效的旧表示。同版本读取不运行相邻迁移，因此兼容性声明不能依赖尚未实现的规范化步骤。头部与载荷扩展仍须在实际消费方中实现各自的准入与保留。
考虑过的替代方案
对头部变更及其他结构编辑要求升版本。 这会机械地排除安全拒绝和可选特性，即使既有判别标记已能保护读取器，也强加迁移工作。
把每个未知字段或值都当作拒绝机制。 已发布读取器并不统一在恢复前拒绝未知值。兼容性证据必须检查实际准入与修改路径；schema 变化本身不提供保证。
允许同版本变更而不记录读取器证据。 schema 图无法证明安全执行、无损保留、历史解释或混合记录行为。明确评审保留这些义务，同时不让分类器假装已证明它们。
添加独立的 JSON 评审对象并对证据做哈希。 用户拒绝重复已有兼容性与验证说明。额外输入字段与更新规则增加编写工作，却不能证明语义安全性。显式同版本选择与已有确认记录使决策可见，无需第二种证据格式。
影响
该规则减少不必要的版本转换，同时明确要求旧读取器与新读取器的证据。它改变评审与确认校验，不改变运行时准入、诊断、codec 或迁移行为。环境示例说明政策动机，并未添加 env 字段。不支持特性的检测、载荷读取器及必要迁移仍由各项特性变更负责。针对性验证必须按需覆盖特性未使用、可选记录保留或必需特性拒绝、历史输入与混合表示；书面评审不能替代这些结果。