06-EFT.WP.Core.DataSpec v1.0 | 第3章 元数据与追溯链

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

第3章 元数据与追溯链

I. 目标与范围

• 建立以 manifest 与 Trace 为核心的元数据体系，保证数据的身份唯一、来龙去脉可审计、到达时两口径一致、量纲与单位可验证。
• 通过 hash_sha256(blob) 与 signature 实现内容寻址与不可抵赖；通过 Trace = [source -> method -> artifact] 串接证据链。
• 与《Core.Equations》《Core.Parameters》《Core.Metrology》保持锚点一致，尤其是 gamma(ell)、d ell、n_eff(x,t)、c_ref、T_arr。

II. 核心定义与符号

• manifest def= { dataset_id, schema_ref, schema_version, pk, idx, units, dim, created_ts, author, tool_rev, env, lineage, checksum, signature }。
• Trace def= [source -> method -> artifact]，其中 source、method、artifact 为节点，边表示处理或传输。
• checksum def= hash_sha256(canonical(ds))，signature def= Sign(checksum, keyref)。
• EvidenceChain def= <Trace, manifest, checksum, signature>。
• canon(ds) def= stable serialization of ds with order(pk) and normalized units。
• TraceID def= hash_sha256(canonical(Trace))。

III. manifest 最小必需集

• 身份与模式
  dataset_id、schema_ref、schema_version、pk、idx、fmt。
• 计量与单位
  units : { field -> unit(field) }、dim : { field -> dim(field) }、check_dim_status ∈ {"pass","fail"}。
• 生成环境
  created_ts、author、tool_rev、env = { os, cpu, gpu, libs, locale }。
• 追溯与指纹
  lineage = { parents : [checksum_i], TraceID }、checksum、signature、keyref。
• 到达时专属
  path = { pid, CRS, orientation, L_gamma }、integrand = { n_eff, c_ref }、measure = "d ell"、formulation = {"factored"|"general"}、delta_form。

IV. Trace 模型与证据链结构

1. 节点类型
   • source：原始采集或外部供给的 artifact；
   • method：确定性或随机性处理步骤，标注 version 与 params；
   • artifact：一次处理输出的数据对象，绑定 checksum 与 schema_ref。
2. 规范化要求
   • method 节点必须记录 code_rev 与 params；
   • 同一 artifact 的 checksum 唯一决定其内容，signature 绑定 keyref；
   • Trace 必须形成有向无环图；TraceID 以 hash_sha256 计算。
3. 证据链最小闭包
   EvidenceChain 在任一点应包含 parents 指纹、当前 checksum、signature 与 TraceID，且可回放到任意祖先。

V. 指纹、签名与可复现性

1. 指纹流程（对应 Mx-1）
   • 对数据 ds 按 order(pk) 与字段规范生成 canon(ds)；
   • 计算 checksum = hash_sha256(canon(ds))；
   • 生成 signature = Sign(checksum, keyref)；
   • 将 checksum、signature、keyref 写入 manifest，并追加 parents。
2. 复现三件套
   ReproTriple def= <checksum, schema_version, code_rev>；三者齐全方可视为强复现。
3. 校验步骤
   • 校验 signature 与 keyref；
   • 重算 hash_sha256(canon(ds)) 对比 checksum；
   • 验证 schema_version 与本地模式是否兼容；
   • 重放 Trace 中 method，期望重得到 checksum 一致。

VI. 元数据命名空间与字段字典

1. MD.core.*
   • MD.core.dataset_id : string
   • MD.core.schema_ref : string
   • MD.core.schema_version : string
   • MD.core.pk : array<string>
   • MD.core.idx : array<array<string>>
2. MD.env.*
   MD.env.os : string、MD.env.cpu : string、MD.env.gpu : string、MD.env.libs : array<string>、MD.env.locale : string
3. MD.trace.*
   MD.trace.parents : array<string>、MD.trace.TraceID : string、MD.trace.code_rev : string、MD.trace.params : string
4. MD.sec.*
   MD.sec.checksum_sha256 : string、MD.sec.signature : string、MD.sec.keyref : string
5. MD.quality.*
   MD.quality.q_score : float、MD.quality.drift : float、MD.quality.completeness : float
6. MD.arrival.*
   • MD.arrival.pid : string、MD.arrival.CRS : string、MD.arrival.orientation : {"forward"|"reverse"}
   • MD.arrival.L_gamma : float、MD.arrival.formulation : {"factored"|"general"}、MD.arrival.delta_form : float

VII. 与两口径到达时的一致性元数据

1. 口径声明
   • formulation="factored" 表示 T_arr = ( 1 / c_ref ) * ( ∫_gamma n_eff d ell )；
   • formulation="general" 表示 T_arr = ( ∫_gamma ( n_eff / c_ref ) d ell )。
2. 差异记录
   • delta_form = | ( 1 / c_ref ) * ( ∫_gamma n_eff d ell ) - ( ∫_gamma ( n_eff / c_ref ) d ell ) |；
   • manifest 必须包含 delta_form 与阈值 tol_Tarr，并在契约中断言 delta_form ≤ tol_Tarr。
3. 路径一致
   pid、ell 单调、CRS 明确、L_gamma = ( ∫_gamma 1 d ell ) 存档。

VIII. 可审计 manifest 模板（文本）

• dataset_id=<string>
• schema_ref=<string>; schema_version=<semver>
• pk=[<field>]; idx=[[<field>...]]; fmt=<jsonl|csv|parquet|nc|tfrecord>
• units={ field:unit(...) }; dim={ field:dim(...) }; check_dim_status=<pass|fail>
• created_ts=<ISO8601>; author=<string>; tool_rev=<string>
• env={ os, cpu, gpu, libs, locale }
• lineage={ parents:[<checksum>...], TraceID=<hash> }
• security={ checksum_sha256=<hash>, signature=<sig>, keyref=<kid> }
• arrival={ pid=<id>, CRS=<epsg>, orientation=<forward|reverse>, L_gamma=<float>, formulation=<factored|general>, delta_form=<float>, tol_Tarr=<float> }

IX. 契约映射与验证接口对照

1. assert_contract 典型断言
   • unique(dataset_id)；
   • non_decreasing(ts) 与 non_decreasing(ell)；
   • check_dim( y - f(x; theta) )；
   • range(q_score, 0, 1)；
   • delta_form ≤ tol_Tarr；
   • exists(MD.sec.checksum_sha256) 与 verify(signature, keyref)。
2. 与接口对照
   • attach_provenance(ds, trace) → 写入 MD.trace.* 与 TraceID；
   • compute_checksum(ds,"sha256") → 产生 checksum；
   • sign_data(ds,keyref) → 产生 signature；
   • export_manifest(ds) → 导出本章模板的键集合。

X. 漂移与质量元数据的纳入

1. 质量维度
   completeness = N_observed / N_expected、validity = N_valid / N_observed、consistency ∈ [0,1]、timeliness = now - created_ts。
2. 漂移记录
   • drift = monitor_drift(ds_ref, ds_new, fields, method="KL")["score"]；
   • 在 manifest 的 MD.quality.* 节中记录，并给出 ref_window 与 threshold。

XI. 到达时用例：端到端追溯

• 采集形成 artifact_0，记录 MD.core.* 与 MD.env.*；
• 生成 canon(artifact_0)，写入 checksum_0 与 signature_0；
• 基于 gamma(ell) 与 n_eff 计算 T_arr（按声明口径），得 artifact_1；
• 计算 delta_form 并断言 delta_form ≤ tol_Tarr；
• 构造 Trace = [artifact_0 -> method_compute_Tarr -> artifact_1]，生成 TraceID；
• artifact_1 写入 manifest：更新 parents=[checksum_0]、checksum_1、signature_1、MD.arrival.*。

XII. 治理、公设与合规要点

• P63-1 内容寻址公设：checksum 唯一决定数据实体，checksum 变化即视为新实体。
• P63-2 可复现公设：ReproTriple = <checksum, schema_version, code_rev> 必须齐备；缺失任一项不可宣称可复现。
• P63-3 不可抵赖公设：凡对外发布的数据工件必须具备 signature 与可追溯的 keyref。

XIII. 与跨卷绑定的实施清单

• bind_to_equations(ds, eqn_refs)：在 manifest.see 中列出 Sxx-? 与 Pxx-?；
• bind_to_parameters(ds, params)：记录参数版本与来源；
• enforce_arrival_time_convention(ds)：生成并校验 delta_form，落入 MD.arrival.*；
• 与《Core.Errors》衔接：当 check_dim_status="fail" 或 verify(signature) 失败时，返回 E.DataSpec.ContractViolation 并阻断发布。

XIV. 发布与冻结

• export_schema(SRef,"yaml") 与 export_manifest(ds) 出版；
• freeze_release(ds, tag) 锁定版本；
• 公布 ReproTriple 与 TraceID，入库审计。