48-实验协议卡 Template v1.0 | 第7章 数据记录与契约

目录 ／ 文档-技术白皮书 ／ 48-实验协议卡 Template v1.0

第7章 数据记录与契约

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

• 统一数据对象的字段、单位与量纲、引用与版本锁定、导出工件与审计轨，确保可复现与可审计。
• 适用：timing / imaging / spectral / mixed 模式；涉及到达时/相位时，路径量显式 gamma(ell) 与测度 d ell，并记录 delta_form。

II. 前置条件与输入（Prerequisites & Inputs）

• 引用与版本：正文与数据侧 see[]/references[] 使用“卷名 + 版本 + 锚点（P/S/M/I）”；对外仅 v1.*。
• 量纲闭合：通过 check_dim；p_dim = 1.0。
• 路径一致性：len(gamma_ell) = len(d_ell) = len(n_eff) ≥ 2；Δell 满足采样约束。
• 同步与校准：clock_state=locked；|ts_start − calib.timestamp| ≤ τ_calib。

III. 字段字典（Field Dictionary，最小必备）

字段名用蛇形；所有数值字段须带 unit 或在 see[] 指向量纲锚点；禁用中文符号。

1. 采集与标识

• record_id: string（ULID/UUIDv4）
• acq.ts_start/acq.ts_end: string（ISO-8601, tz）
• instrument.id/mode: string（imaging|spectral|timing|mixed）
• calib.version: string（SemVer），calib.timestamp: string（ISO-8601）

2. 路径与介质

• path.gamma_ell: array<number>（m）
• path.d_ell: array<number>（m）
• medium.n_eff_profile: array<number>（1）
• ref.c_ref: number（m/s）

3. 观测量与相位

• obs.T_arr: number（s，记录 delta_form）
• obs.Phi: number（rad），lambda_ref: number（m）

4. 质量与不确定度

• quality.flags: array<string>，quality.score_Q: number（[0,1]）
• uncertainty.obs_T_arr: number（s），uncertainty.obs_Phi: number（rad）

5. 引用与版本

• see: array<string>（“卷名+版本+锚点”）
• references: array<string>
• version: string（SemVer）
• checksum.sha256: string（64 hex）

IV. 数据契约（Data Contract，规范要求）

1. 一致性约束

• path.gamma_ell.length = path.d_ell.length = medium.n_eff_profile.length ≥ 2。
• 若存在 obs.Phi，则 lambda_ref 必填。
• 禁止裸用 c、T、n；分别使用 c_ref、T_arr（或具体量名）、n_eff（或 n 且明示单位）。

2. 量纲与公式口径（两种等价到达时 + 相位）

• T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
• T_arr = ( ∫ ( n_eff / c_ref ) d ell )
• Phi = ( 2π / λ_ref ) * ( ∫ n_eff d ell )

文中显式 gamma(ell) 与 d ell；数据/元数据记录 delta_form ∈ {general, factored}；导出随附 check_dim_report.json。

3. 缺失与异常

• 数值缺失记 null（JSON）；不得以文本 NaN/Inf 代替。
• 异常以 quality.flags 标注；剔除规则须在分析计划中预注册。

V. 导出工件与目录结构（Exports & Layout）

1. 必交付：
   • manifest.yaml（dataset_id/version/see[]/references[]/checksum/licenses/created_at/producer）
   • schema.json（JSON Schema）
   • observations.parquet，paths.parquet
   • check_dim_report.json，quality_report.json，audit.jsonl（含阈值事件与哈希）
2. 建议目录：

PTN_EXPORT/

manifest.yaml

data/

observations.parquet

paths.parquet

schema/

schema.json

reports/

check_dim_report.json

quality_report.json

audit.jsonl

README.md

SIGNATURE.asc

VI. 机读样例（Machine-Readable Examples）

A. manifest.yaml

dataset_id: "ptn-demo"

version: "1.0.0"

created_at: "2025-09-24T16:00:00Z"

producer: "PTN.Workgroup.Core"

see:

- "EFT.WP.Core.Equations v1.1:S20-1"

- "EFT.WP.Core.Metrology v1.0:check_dim"

- "EFT.WP.Core.DataSpec v1.0:TARR"

references:

- "EFT.WP.Core.Terms v1.0:P10-3"

checksum: { algo: "sha256", value: "<64-hex>" }

release_tier: "public"

B. schema.json（节选）

{

"$schema": "https://json-schema.org/draft/2020-12/schema",

"title": "PTN Data Object v1.0.0",

"type": "object",

"required": ["record_id","acq","path","medium","ref","obs","version","see","references"],

"properties": {

"record_id": { "type": "string" },

"acq": {

"type": "object",

"required": ["ts_start","ts_end"],

"properties": {

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

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

}

},

"path": {

"type": "object",

"required": ["gamma_ell","d_ell"],

"properties": {

"gamma_ell": { "type": "array", "items": { "type": "number" }, "minItems": 2 },

"d_ell": { "type": "array", "items": { "type": "number" }, "minItems": 2 }

}

},

"medium": {

"type": "object",

"required": ["n_eff_profile"],

"properties": {

"n_eff_profile": { "type": "array", "items": { "type": "number" }, "minItems": 2 }

}

},

"ref": {

"type": "object",

"required": ["c_ref"],

"properties": { "c_ref": { "type": "number", "minimum": 2.9e8, "maximum": 3.1e8 } }

},

"obs": {

"type": "object",

"properties": { "T_arr": { "type": "number" }, "Phi": { "type": "number" } }

},

"see": { "type": "array", "items": { "type": "string" }, "minItems": 1 },

"references": { "type": "array", "items": { "type": "string" }, "minItems": 1 },

"version": { "type": "string" }

}

}

C. paths.parquet 字段示意（表头）

record_id,gamma_ell[],d_ell[],n_eff[],unit_gamma,unit_dell,unit_n

01H..., [..], [..], [..], m, m, 1

D. audit.jsonl（一行示例）

{
  "run_id": "01JXYZABCD0EFG...",
  "started_at": "2025-09-24T16:10:00Z",
  "tools": [ { "name": "ptn-cli", "version": "1.4.2" } ],
  "random_seeds": [ 20250924 ],
  "input_hashes": [ "sha256:..." ],
  "events": [ { "ts": "...", "clock_state": "locked", "delta_t_abs_ns": 23, "allan_1s": 1.2e-11 } ],
  "references": [ "EFT.WP.Core.Equations v1.1:S20-1" ],
  "version": "1.0.0"
}

VII. 质量门与停止准则（Quality Gates & Stops）

• G1｜Schema 完整；G2｜引用 合规且锚点直指率 ≥ 90%；G3｜路径–测度 对齐且 ≥2；
• G4｜量纲闭合：T_arr 为 s、Phi 为 rad、p_dim=1.0；
• G5｜校准新鲜度 合规；G6｜噪声残差 在许可带；G8｜唯一性：record_id 唯一、checksum 不重复。
• 任一核心门失败即暂停导出并进入修复/回退流程（限制模式 [Restricted] 仅发布定性结果）。

VIII. 引用与版本（Citations & Versioning）

• 固定写法：见《<卷名> vX.Y》<章节> <锚点>；优先 P/S/M/I；正文与 see[]/references[] 一致。
• 规范锚点：EFT.WP.Core.Equations v1.1:S20-1/S21-2、EFT.WP.Core.Metrology v1.0:check_dim、EFT.WP.Core.DataSpec v1.0:TARR。
• 对外仅 v1.*；如引用 v0.*，显著标注“草案/非承诺”。

IX. 执行勾选清单（Checklist）

• 字段与单位/量纲完整；禁止裸用 c、T、n；不混用 T_fil/T_trans、n/n_eff。
• 路径型表达显式 gamma(ell)、d ell；delta_form 已记录。
• p_dim = 1.0，clock_state=locked，τ_calib 合规。
• 导出清单齐备（manifest/schema/data/reports/audit）；checksum 与签名就绪。
• see[]/references[] 合规且锚点直指率 ≥ 90%；版本锁定一致。