06-EFT.WP.Core.DataSpec v1.0 | 第4章 数据契约与校验

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

第4章 数据契约与校验

I. 范围与目标

• 定义数据契约为对 D 在给定 S 下需满足的可执行约束集合，覆盖字段、记录、数据集与路径 gamma(ell) 层面的属性、关系与容差。
• 通过 validate_dataset 与 assert_contract 建立质量闸门，统一落盘到 manifest，并与《Core.Equations》《Core.Parameters》《Core.Metrology》之锚点保持一致（n_eff(x,t)、c_ref、gamma(ell)、d ell、T_arr）。
• 提供失败处置策略与严重性映射，确保契约失败的可追溯、可降级、可回滚。

II. 契约模型与语义

• Contract 元组：Contract def= <scope, rules, severity, actions, metrics>。
• scope ∈ {"record","dataset","partition","path"}；rules 为断言列表；severity ∈ {"info","warn","error","critical"}；actions 为失败处置；metrics 为通过率与覆盖度。
• 契约的判定对象为 canon(D)（经 order(pk) 与单位归一化的稳定序列化），结果写入 manifest 与 Trace。

III. 公设（P64-*）

• P64-1 可执行公设：每个对外发布的数据集必须随附机器可执行契约与 schema_version。
• P64-2 量纲一致公设：凡参与模型或方程的字段，check_dim(expr) 必须通过，否则禁止绑定至《Core.Equations》。
• P64-3 时间与路径有序公设：时间序列字段 ts 以及路径坐标 ell 必须非降；违反视为顺序错误。
• P64-4 到达时一致公设：凡涉及 T_arr 的数据集，必须同时记录两口径计算并满足差异阈值约束。

IV. 规则类型与标准表达

• 类型与形状
  type(field_i) ∈ {int,float,string,bool,tensor,bytes}；nullable(field_i) ∈ {0,1}；shape(field_i)=<dims>。
• 域与范围
  数值范围：min(field_i) ≤ field_i ≤ max(field_i)；集合枚举：field_i ∈ EnumSet；正则：regex(field_i, pattern)。
• 唯一性与参照
  主键：unique(pk)；外键：foreign_key(child.keys) -> parent.pk。
• 缺失与完整性
  缺失显式：m ∈ {0,1}；覆盖度：completeness = N_observed / N_expected。
• 单位与量纲
  unit(field_i) 与 dim(field_i) 按 S 绑定；表达式约束：check_dim( y - f(x; theta) )。
• 时间与采样
  单调：non_decreasing(ts)；固定采样：fs approx 1/Delta_t 且 |Δts - Delta_t| ≤ tol_ts。
• 空间与坐标
  CRS 声明；lat ∈ [-90, 90]，lon ∈ [-180, 180]；alt 容差约束。
• 路径与到达时
  delta_form = | ( 1 / c_ref ) * ( ∫_gamma n_eff d ell ) - ( ∫_gamma ( n_eff / c_ref ) d ell ) |，并断言 delta_form ≤ tol_Tarr。non_decreasing(ell)；路径长度：L_gamma = ( ∫_gamma 1 d ell )；两口径差异：
• 不确定度与质量
  u(x) ≤ u_max；q_score ∈ [0,1] 且 q_score ≥ q_min。
• 漂移与稳定性
  drift ≤ drift_threshold（如 method="KL" 的得分）。

V. 断言库模板（与 I60 2 对齐）

• 记录级（record）
  range(field, a, b)；regex(field, pat)；enum(field, set)；not_null(field)。
• 数据集级（dataset）
  unique(keys)；non_decreasing(field)；fixed_interval(ts, Delta_t, tol_ts)；latlon_bounds(lat, lon)。
• 跨字段（cross-field）
  implies(A,B)；sum_equals(w*x, y, tol)；check_dim( y - f(x; theta) )。
• 路径与到达时（path）
  monotone(ell)；arrival_forms(delta_form, tol_Tarr)；length_equals(L_gamma, ref, tol_L)。

VI. 契约示例（文本片段）

1. scope=dataset
2. tests=
   • - unique: ["pk"]
   • - non_decreasing: "ts"
   • - fixed_interval: { field:"ts", Delta_t:0.01, tol_ts:1e-4 }
   • - latlon_bounds: { lat:"lat", lon:"lon" }
   • - enum: { field:"mode", set:["A","B","C"] }
   • - range: { field:"q_score", min:0.0, max:1.0 }
   • - check_dim: "y - f(x; theta)"
   • - arrival_forms: { delta_form_field:"delta_form", tol_Tarr:1e-6 }
3. severity_map=
   range->error; unique->critical; non_decreasing->error; check_dim->critical; arrival_forms->error
4. actions=
   on_error="quarantine"; on_critical="fail_release"; on_warn="annotate_only"

VII. 校验流程（Mx-2 数据契约闸门）

1. 读取 manifest 与 Contract，对 canon(D) 构建校验上下文（单位归一化、CRS 绑定、pk 与 idx 生效）。
2. 逐条执行 tests：
   • 记录级断言先行，支持 stream_records(ds, batch) 流式校验；
   • 数据集级断言在索引与统计准备完成后执行；
   • 路径与到达时断言在聚合 pid 与 ell 后执行。
3. 汇总 metrics = { pass_rate, tested_count, violated, by_rule }，写回 manifest 的质量节。
4. 根据 severity_map 应用 actions：隔离、重试、回滚、降级或仅注释。
5. 生成 trace_event = log("DS.CONTRACT", level, context) 并附加 TraceID。

VIII. 失败处置与严重性映射

• info：annotate_only（记录至 manifest 与日志，允许发布）。
• warn：mark_low_confidence（降级 q_score，触发后续复核）。
• error：quarantine_records 或 quarantine_partitions，禁止进入 freeze_release。
• critical：fail_release 与 rollback(tag_prev)，触发告警与审计。

IX. 到达时两口径的契约化

1. 计算两口径：
   • 常量外提：T_arr = ( 1 / c_ref ) * ( ∫_gamma n_eff d ell )。
   • 一般口径：T_arr = ( ∫_gamma ( n_eff / c_ref ) d ell )。
2. 断言与记录：
   • delta_form = | T_arr(factored) - T_arr(general) |；
   • 契约项 arrival_forms(delta_form, tol_Tarr) 必填；
   • manifest.arrival.formulation 与 manifest.arrival.delta_form 同步更新。

X. 与接口的对照实现

1. validate_dataset(SRef, ds, strict=True) -> report：执行模式级检查（类型、单位、量纲、可空性）。
2. assert_contract(ds, tests) -> dict：执行本章定义的断言并返回逐项结果与 metrics。
3. 参考调用序列：
   • rep_schema = validate_dataset(SRef, ds)；
   • rep_contract = assert_contract(ds, tests)；
   • attach_provenance(ds, trace)；export_manifest(ds)；freeze_release(ds, tag)（若通过）。

XI. 质量度量与覆盖

• 通过率：pass_rate = 1 - violated / tested_count。
• 覆盖度：coverage = tested_rows / N（流式校验时需报告采样率）。
• 断言耗时：t_assert_total 与 per_rule_stats，用于持续优化契约执行。

XII. 采样与规模化建议

• 大规模数据建议 stratified_sampling(keys=["pid","sid"], rate=r) 先行预校验；关键断言（unique(pk)、non_decreasing(ts)、arrival_forms）必须对全量执行。
• 对窗口性断言（固定采样、漂移检测）采用滑动窗口并行计算，窗口宽度 Delta_t 与步长需在契约中显式声明。

XIII. 治理与合规联动

• 与隐私策略联动：契约可包含 mask_required(fields) 与 anonymize(policy) 的前置断言，未满足则直接 fail_release。
• 与《Core.Errors》联动：将违反项映射为 E.DataSpec.ContractViolation.*，并在 log_event(code, level, context) 中记录 rule_id、rid、pid。

XIV. 变更与兼容性

• 契约版本化：contract_version 与 schema_version 同步管理；破坏性修改需 major+1，并提供 diff 与兼容适配规则。
• 回放保障：旧版本契约须可在 canon(D) 上重放，确保历史数据可审计。

XV. 最小清单（应纳入 manifest 的契约键）

• contract_version
• tests（标准化断言列表）
• severity_map 与 actions
• metrics（pass_rate、coverage、per_rule_stats）
• arrival 节（formulation、delta_form、tol_Tarr）
• quality 节（q_score、completeness、drift）