50-参数注册卡 Template v1.0 | 第6章 版本与新鲜度（有效期/状态机）

目录 ／ 文档-技术白皮书 ／ 50-参数注册卡 Template v1.0

第6章 版本与新鲜度（有效期/状态机）

I. 目的与范围（Purpose & Scope）

• 规定参数卡的版本语义（SemVer）、状态机（draft/stable/deprecated）与新鲜度/有效期策略，确保跨链路参数在变更、发布与回滚中的一致性与可追溯。
• 涉及路径量（到达时/相位）时，正文显式 gamma(ell) 与测度 d ell，并在卡片数据侧记录 delta_form ∈ {general, factored}；发布要求 p_dim = 1.0。

II. 版本语义（Versioning, SemVer）

• MAJOR：字段语义/单位/量纲发生破坏性变更（如 unit 由 m 改为 cm 或派生关系改变）。
• MINOR：向后兼容的新增字段（如补充 freshness.policy、aliases[]）。
• PATCH：修复/勘误，不改动字段语义（如更正默认值小数位）。
• 标签：预发布用 -rc.N、元数据用 +build.N；注册表中仅允许稳定版或经批准的 rc。

III. 状态机（Status Machine）

1. draft → stable → deprecated；其中：
   • draft：内部评审期，仅测试环境可见，禁止外发与锚点引用。
   • stable：通过校验与签名，可外发与跨卷锚点引用。
   • deprecated：声明替代项 replaced_by，保留至少一个 MINOR 周期，最终下线。
2. 状态迁移需在 audit.jsonl 记录操作者、时间戳与变更说明。

IV. 新鲜度与有效期（Freshness & Validity）

• 字段：freshness{ valid_from, valid_to, policy{ tau_calib_s_max, clock_state } }。
• 判定：满足 |ts_now − calib.timestamp| ≤ tau_calib_s_max 且 clock_state="locked" 视为新鲜；否则进入限制模式或触发再标定。
• 滚动更新：在 valid_to 前生成下一版本卡，注册表无缝切换；旧版保留用于追溯与回滚。
• 到期策略：过期后禁止作为上游依赖参与派生；仅允许历史复算并标注 [Restricted]。

V. 变更控制与冲突解决（Change Control & Conflicts）

• 变更票据：每次版本提升需附变更说明（影响范围、向后兼容性、测试结果）。
• 单位/量纲变更：必须为 MAJOR；提供自动迁移脚本或换算规则。
• 别名与重命名：新增 aliases[] 仅做内部解析，对外以 symbol 为准；重命名需 MINOR 并保留旧别名至少一周期。
• 冲突检测：param_id 唯一，checksum 不重复；跨卡依赖的单位/域兼容性通过 I70-dim_check 与模式校验。

VI. 回滚与锁定（Rollback & Locking）

• 使用 I27-lock_version(param_id, semver) 生成不可变标签；
• 回滚操作在 audit.jsonl 中登记“回滚自/至”与原因；
• 发布包 report_manifest.yaml 中列出锁定版本与签名信息 SIGNATURE.asc。

VII. 合规与质量门（Compliance & Gates）

• G4｜量纲闭合：版本变更后再次通过 I70-dim_check，随附 check_dim_report.json，p_dim = 1.0。
• G5｜新鲜度：valid_to 未过期，clock_state="locked"；过期触发再标定或进入限制模式。
• G2｜引用合规：see[]/references[] 使用“卷名+版本+锚点（P/S/M/I）”，锚点直指率 ≥ 90%。
• G8｜唯一性：注册表无重复 param_id/checksum，血缘图无环。

VIII. 规范示例（Normative Examples）

# A) 从 draft 升级至 stable（MINOR 增补 freshness.policy）

version: "1.1.0"

status: "stable"

param_id: "CAL-01-τ_sys"

symbol: "τ_sys"

freshness:

valid_from: "2025-09-24T00:00:00Z"

valid_to: "2025-10-24T00:00:00Z"

policy: { tau_calib_s_max: 86400, clock_state: "locked" }

see: ["Metrology.Sync v1.0:PPS","EFT.WP.Core.Metrology v1.0:check_dim"]

# B) 单位变更（MAJOR，含迁移说明）

version: "2.0.0"

status: "stable"

param_id: "GEO-02-fov_deg"

symbol: "FOV"

domain:

type: "real"

unit: "rad" # 原 "deg" → MAJOR

range: [0.0, 3.1416]

default: 0.0174533

migration: { from_unit: "deg", to_unit: "rad", rule: "rad = deg * π/180" }

see: ["PTN.Template v1.0:Ch.5","EFT.WP.Core.Metrology v1.0:check_dim"]

# C) 弃用并替代（DEPRECATED）

version: "1.2.0"

status: "deprecated"

param_id: "ALG-05-huber_delta"

replaced_by: "ALG-07-cauchy_c"

deprecation_note: "robust scheme migrated to cauchy"

valid_to: "2026-12-31T23:59:59Z"

IX. 模式片段（Schema Snippet）

{

"type": "object",

"required": ["version","status","freshness"],

"properties": {

"version": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:[-+].*)?$" },

"status": { "enum": ["draft","stable","deprecated"] },

"freshness": {

"type": "object",

"required": ["valid_from","valid_to","policy"],

"properties": {

"valid_from": { "type": "string", "format": "date-time" },

"valid_to": { "type": "string", "format": "date-time" },

"policy": {

"type": "object",

"required": ["tau_calib_s_max","clock_state"],

"properties": {

"tau_calib_s_max": { "type": "integer" },

"clock_state": { "enum": ["locked","holdover","free"] }

}

}

}

}

}

}

X. 交叉引用（Cross-References）

• 参数分类与命名：见第3章；
• 域、单位与默认：见第4章；
• 数据契约与发布：见 EFT.WP.Core.DataSpec v1.0:TARR、PTN Template 第5/11章；
• 质量门映射：见误差预算卡第9章；
• 同步/新鲜度：见 Metrology.Sync v1.0。

XI. 执行勾选清单（Checklist）

• 版本号符合 SemVer，状态机为 draft/stable/deprecated 之一并有审计记录。
• freshness.valid_from/valid_to 与 policy{tau_calib_s_max, clock_state} 合规且未过期。
• 变更票据完整：影响范围、兼容性、测试与迁移（如有单位变更）。
• 通过 I70-dim_check，check_dim_report.json 已更新，p_dim = 1.0。
• 锚点引用合规，锚点直指率 ≥ 90%，注册表唯一性通过；血缘图无环。
• 必要时设置回滚点 I27-lock_version，发布包含签名与 checksum。