06-EFT.WP.Core.DataSpec v1.0 | 第7章 版本、发布与变更

目录 ／ 文档-技术白皮书 ／ 06-EFT.WP.Core.DataSpec v1.0

第7章 版本、发布与变更

I. 范围与目标

• 本章定义 schema_version 与数据发布语义（semver），规定 diff/patch/freeze_release 的流程与判定，并给出兼容性矩阵、回滚与迁移适配的最小要求。
• 覆盖 D、S、manifest、pk/idx_k、Trace、hash_sha256、signature，以及跨卷锚点 T_arr、gamma(ell)、n_eff(x,t)、c_ref 的版本协同。

II. 术语与符号

• semver def= major.minor.patch，均为非负整数。
• schema_version 绑定到 S；data_release 绑定到 D。
• BC（backward compatibility），“向后兼容”；DC（downward compatibility），“向前运行于旧读者”。
• A \ B（set difference），keys(r) def= 字段集合。

III. 公设（P67-*)

• P67-1 语义化版本公设：schema_version 与 data_release 必采用 semver，并在 manifest 明确记录。
• P67-2 冻结不可变公设：一旦 freeze_release(D, tag) 成功，该发布的内容、统计与指纹在全局不可变；任何更正以新 data_release 执行。
• P67-3 可重现公设：给定 {schema_version, data_release, manifest, Trace}，应可重建同一 hash_sha256(blob)。
• P67-4 契约优先公设：凡经 assert_contract 校验失败的候选发布不得进入“冻结”状态。
• P67-5 到达时一致公设：含 T_arr 字段的数据版本必须记录两口径与 delta_form，并声明 tol_Tarr；若 delta_form > tol_Tarr，发布失败。

IV. 版本语义与比较（S67-1）

1. semver_compare(a,b) 以字典序比较 major, minor, patch。
2. 兼容条件：
   • BC(schema vX.Y.Z -> vX.Y'.Z') 若且仅若 major 相同且所有变更为“加法或可忽略”。
   • DC 无强制要求，需显式声明支持的读者下限版本 reader_min.
3. 推荐绑定：
   • schema_version 推进：major+1 用于破坏性变更；minor+1 用于加字段或非破坏性索引；patch+1 用于描述修正。
   • data_release 推进：任何数据位、更正或回填均至少 patch+1。

V. 变更分类与判定

1. 加法非破坏（minor）：
   • 新增字段 f_new 且 nullable(f_new)=True 或提供确定默认；
   • 新增二级索引、区段统计、Bloom 过滤；
   • 新增 manifest.notes、Trace 元素。
2. 条件非破坏（minor，需适配层）：
   • 将 unit(f) 改为等价量纲的显式单位（提供 corr_env(x; RefCond) 与转换函数）；
   • 将 pk 的物理聚簇顺序调整但保持 pk 语义与唯一性。
3. 破坏性（major）：
   • 修改 pk 定义或字段类型不可上行兼容（如 int32 -> string 且无单射映射）；
   • 删除字段且无别名回填；
   • 分区键 K 或路径 pid/ell_bucket 方案变更导致旧路径不可解析；
   • CRS 变更且未提供自动重投影。
4. 数据层修正（data patch）：
   值修正、缺失回填、迟到窗口回写、T_arr 重算（两口径与 delta_form 必同步）。

VI. 差异模型（S67-2）

• 记录差异：diff_R = { r | r ∈ R_new \ R_old } union { r | r ∈ R_old \ R_new } union { r | keys(r) 相同但值不同 }。
• 模式差异：diff_S = (Fields_add, Fields_drop, Type_change, Unit_change, Constraint_change)。
• 索引差异：diff_I = (Index_add, Index_drop, Index_rebuild)。
• 变更摘要：changelog = { scope ∈ {schema, data, index} -> diff_* }。

VII. 补丁与外放（S67-3）

1. patch_dataset(ds, patch) 的最小操作集合：
   • op=ADD_FIELD(name, type, default|nullable)
   • op=DROP_FIELD(name)
   • op=ALTER_FIELD(name, type|unit|dim)
   • op=UPSERT_RECORD(pk, values)
   • op=DELETE_RECORD(pk)
   • op=REINDEX(keys)
2. 约束：补丁后必须满足 validate_dataset(..., strict=True) 与 assert_contract 全通过；若失败，补丁回滚。

VIII. 发布流程 Mx-2

1. 准备阶段：
   • 完成候选数据集与 manifest，更新 schema_version 与 data_release（bump_version）。
   • 附着追溯：attach_provenance(D, Trace)；计算 hash_sha256(blob)。
2. 校验阶段：
   • 运行 validate_dataset 与 assert_contract；
   • 针对 T_arr：计算两口径与 delta_form，断言 delta_form <= tol_Tarr。
3. 指标门控：
   quality_metrics(D) 达到阈值；关键查询延迟与分区裁剪率达到基线。
4. 索引与统计：
   执行 build_index(D, keys)，刷新区段统计与 distinct_est。
5. 签名与冻结：
   sign_data(D, keyref)；freeze_release(D, tag)；标记不可变。
6. 发布与公告：
   更新注册表与兼容矩阵；生成 changelog 与迁移指南；开始观测期与回滚窗口。

IX. 回滚与冻结策略

• 冷冻结（hard freeze）：仅允许添加“旁路”发布，不允许覆盖；tag 永久保留。
• 暖冻结（soft freeze）：在观测窗口内允许 patch+1 的热修复，但新 tag 必指向新工件。
• 回滚原则：rollback(tag_prev) 应恢复到上一个可用 data_release，并更新消费者路由（读者指向 tag_prev）。

X. 兼容性矩阵（示意规则）

1. 维度：reader(schema_version) × dataset(schema_version) × data_release。
2. 规则：
   • reader.major == dataset.major 则默认兼容；
   • 若 reader.minor < dataset.minor 且新增了必需字段，则需适配层；
   • 不同 CRS 或 K 需要转换器或路由规则；
   • pk 改动必为 major，需同步升级读者。

XI. 迁移与适配层

• 字段别名：通过 register_field(..., aliases=[...]) 与 normalize_field 提供逐字段兼容。
• 单位与量纲：提供 unit/ dim 转换函数并在 manifest.transforms 记录 corr_env(x; RefCond)。
• 分区/路径：提供旧 K -> K' 的查询重写与路由表，直至历史回填完成。
• 索引：当 idx_k 变更时提供“写新读旧”窗口与双写标志位。

XII. manifest 扩展（版本与发布）

• versioning：{ schema_version, data_release, prev_release, reader_min, notes }
• changelog：{ diff_S, diff_R, diff_I, breaking: bool }
• integrity：{ hash_sha256, signature, signed_by, signed_at }
• freeze：{ tag, frozen_at, immutable: true }
• adapters：{ fields_alias, unit_converters, routing_rules }

XIII. 与跨卷锚点的对齐（T_arr 示例）

1. 字段集合：{ pid, ell, n_eff, c_ref, T_arr_factored, T_arr_general, delta_form }。
2. 变更规则：
   • 若 c_ref 参考更新但可由 corr_env(x; RefCond) 还原，属非破坏（minor）；
   • 若路径参数化 ell 或测度 d ell 定义更新，则为破坏（major），并需 schema_version.major+1 与迁移脚本。

XIV. 实现绑定（I60 7 对齐）

• bump_version(schema:SRef, semver:str) -> None：更新 schema_version 或 data_release 并写入 manifest.versioning。
• diff_datasets(a:any, b:any, keys:list[str]) -> dict：返回 diff_R/diff_S/diff_I 与 breaking 标志。
• patch_dataset(ds:any, patch:any) -> any：执行 S67-3 的操作集合并强校验。
• freeze_release(ds:any, tag:str) -> None：完成签名、指纹与不可变标记。

XV. 审计与治理

• 留存：enforce_retention(ds, ttl_days) 对临时发布执行清理，不影响冻结工件。
• 可追溯：Trace 至少包含 { source -> method -> artifact } 与版本指纹。
• 合规：signature 与 hash_sha256 必在发布页与 manifest 双处可见。

XVI. 发布清单（执行摘要）

• Inputs：D,S,manifest,Trace,semver,target_tag
• Checks：validate_dataset、assert_contract、quality_metrics、T_arr delta_form <= tol_Tarr
• Artifacts：tagged dataset、manifest.versioning、indexes、signature、changelog
• Post：兼容矩阵更新、读者路由切换、观测与回滚窗口设定