35-EFT.WP.EDX.OrientedTension v1.0 | 第12章 实现绑定与 API（I）

目录 ／ 文档-技术白皮书 ／ 35-EFT.WP.EDX.OrientedTension v1.0

第12章 实现绑定与 API（I）

I. 摘要与范围
本章定义取向张力（Oriented Tension, OT）在 CLI/SDK/HTTP 三层的实现绑定与对外接口族 I80-* / API v1：统一请求—响应契约、单位与量纲（Unit/Dim）携带、DatasetCard/ModelCard/MetrologyCard/PipelineCard 对接、SimStack-OT 的可复现执行、错误语义与配额、安全与审计。公式与符号统一用英文记号并以反引号包裹，单位采用 SI（默认 3 位有效数字）。凡涉及 ToA 的返回，一律并行两口径并显式声明路径 gamma(ell) 与测度 d ell。

II. 依赖与引用

1. 几何与取向：第3章（S80-1/2）。
2. 构成与动力学：第4章（S80-3/4，P80-2/3/9/10）。
3. 度量学：第5章（M80-1…4）。
4. 耦合与介质：第6章（S80-5/6）。
5. 能量收支：第7章（S80-7/8）。
6. 数值方法与仿真：第10章（SimStack-OT）。
7. 数据与管线：I75-*/M75-*（第14章体系，沿用本卷卡片口径）。

III. 规范锚点（本章新增，I80-*）

8. I80-0（接口层次）：三层绑定共享统一契约与错误语义：
   • CLI：ot <command> [--flags]；
   • SDK（Python）：from ot import api；
   • HTTP/JSON：POST /v1/...。
9. I80-1 oriented_tension(Q_ij, grad_u) -> T_fil_ij：由序参与形变梯度计算取向张力；返回 Pa、对称且迹零一致。
10. I80-2 infer_Q_from_polarimetry(data, R_inst) -> {Q_ij, Cov_Q}：由偏振/散射数据反演 Q_ij 与协方差，保持 Tr(Q)=0。
11. I80-3 couple_transport(Q_ij, fields, params) -> {W_cpl, D_eff, eps_ij, mu_ij, C_eff}：生成耦合自由能与传输/波有效张量。
12. I80-4 edx_balance(T_fil_ij, W_orient, flows, fields) -> {P_in, P_mech, P_cpl, P_diss, Phi_E}：能量收支分解与闭合残差。
13. I80-5 simulate_ot(SimCfg) -> {products, metrics}：调用 SimStack-OT 执行数值仿真与基准。
14. I80-6 fit_ot(bundle, model, priors) -> {posterior, evidence, masks}：联合拟合 OT 构成/耦合参数并返回证据与占优掩码。
15. I80-7 export_cards(artifact) -> {DatasetCard|ModelCard|MetrologyCard|PipelineCard}：从产物导出标准卡片。
16. I80-8 metrics_validate(metrics, thresholds) -> {pass|fail, diff}：指标与门限核验（含 EDX-closure）。
17. I80-9（合同与单位）：所有数值字段强制携带 unit 与 dim；Phi(E) 必含 sr 与能量维度；Q_ij 为无量纲且迹零；张量单位与量纲闭合。
18. I80-10（ToA 强制）：凡涉及 T_arr 的请求/响应，必须并行返回 T_arr^A/T_arr^B，并附 {gamma(ell), d ell} 与 delta_form。
19. I80-11（可复现性）：请求可选 seed；响应回传 {rng_state, code_hash, data_hash}；产物可注册为基准。

IV. 正文结构

I. API 层次与接口风格

• HTTP 端点（示例）：
  /v1/ot/constitutive/oriented_tension、/v1/ot/infer_Q、/v1/ot/coupling/transport、/v1/ot/edx/balance、/v1/ot/simulate、/v1/ot/fit、/v1/cards/export、/v1/metrics/validate。
• SDK：方法名与 I80-* 一致；返回带 unit/dim 的结构化对象。
• CLI：与 SDK 等价子命令；默认输出 products/ 与 metrics.json。

II. 契约与模式（JSON 示例）

• 请求（/v1/ot/fit）：

{

"bundle": {"datasets": ["cards/dataset_pol.json","cards/dataset_mech.json"], "unit": "SI"},

"model": {"card": "cards/model_ot.json"},

"priors": {"tau_relax": {"type":"LogNormal","mu":-2.3,"sigma":0.5}},

"seed": 1729

}

• 响应（节选）：

{

"posterior": {

"tau_relax": {"mean": 0.12, "sd": 0.02, "unit": "s"},

"D_Q": {"mean": 1.6e-11, "sd": 0.3e-11, "unit": "m^2·s^-1"}

},

"evidence": {"Z": 2.1e3, "logZ": 7.65},

"masks": {"eta_dom": [{"band":"EM-1","E_min":"1e-2 eV","E_max":"1 eV","channel":"EM-coupling"}]},

"rng_state": "...",

"hash": {"code_hash":"sha256:...","data_hash":"sha256:..."}

}

III. 单位与量纲审计

• T_fil_ij：Pa，维 M L^-1 T^-2；Q_ij：1 且 Tr(Q)=0；D_eff：m^2·s^-1；ε_ij/μ_ij：F·m^-1/H·m^-1（或以相对量给出）并标注维度映射；Φ_E：能量通量（W·m^-2）。
• 审计失败（如缺 sr、迹非零、维不闭合）返回 422 UNIT_MISMATCH。

IV. 错误语义与配额

1. 错误码：
   • 400 INVALID_ARGUMENT（字段缺失/类型不符）；
   • 412 PRECONDITION_FAILED（缺少 {gamma(ell), d ell} 或 delta_form）；
   • 422 UNIT_MISMATCH（单位/量纲不闭合或 Tr(Q)≠0）；
   • 409 CONFLICT（hash/版本冲突）；
   • 429 RATE_LIMIT（超配额）；
   • 500 INTERNAL（内部错误）。
2. 返回一律包含 trace_id 与 see: 锚点，便于审计与复现。

V. 安全、审计与配额

• 认证：API Key（Authorization: Bearer），可选 HMAC 时间戳签名。
• 审计：记录 {who, when, where, code_hash, data_hash, rng_state} 并与注册表索引对齐。
• 配额：按 requests/min 与 compute-min/day 配置；触发配额返回 429 并建议以 PipelineCard DAG 分段执行。

VI. 工作流与用例（M-系列映射）

1. 用例 A：从观测到 OT 构成与耦合
   • infer_Q_from_polarimetry 得 Q_ij；
   • oriented_tension 与 couple_transport 得 T_fil_ij 与有效张量；
   • fit_ot 返 {posterior, evidence, masks}；metrics_validate 过门限。
2. 用例 B：能量账本与闭合审计
   • edx_balance 计算 {P_in,P_mech,P_cpl,P_diss,Phi_E}；
   • 结合第7章核验闭合残差；
   • 导出 EDXLedger.npz 与报告。
3. 用例 C：仿真—合成—对照
   • simulate_ot 生成产物；
   • export_cards 产出卡片；
   • 将合成观测与实测经 fit_ot 联合评估证据与指标。

VII. 与本卷/他卷的交叉引用

• 数学与物理锚点：S80-1/2/3/4/5/6/7/8/15/16/17/18。
• 拟合与证据：第9章（不确定度与证据）；
• 仿真与基准：第10章（SimStack-OT）；
• 数据与管线卡：第14章 I75-*/M75-*。

VIII. 验证、判据与反例

1. 阳性判据：
   • 响应字段带 unit/dim 并通过量纲审计；Q_ij 保对称与迹零；
   • 若涉及 ToA，双口径 T_arr^A/T_arr^B 与 delta_form、路径/测度齐备；
   • metrics_validate 达到门限（含 EDX-closure）；可复现实验 hash/rng_state 一致。
2. 阴性判据：
   • 省略 {gamma(ell), d ell} 或仅返回单一 T_arr；
   • UNIT_MISMATCH、Tr(Q)≠0 或 ε/μ/C 维度映射错误；
   • 基准注册后回归不通过且无修复说明。
3. 对照设计：
   • {仅取向, 仅耦合, 取向+耦合} 的调用图与证据对比；
   • {Form A only, Form B only, A+B} 的 ToA 返回对证据的影响；
   • {one-zone, multi-zone} 传输求解对同一数据的差异。

IX. 图表与清单

• 表 12-1 端点一览（HTTP）

• 表 12-2 错误码与语义

• 表 12-3 SDK 原型（Python，节选）

• 表 12-4 契约字段与单位（摘录）

X. 小结
本章以 I80-* / API v1 统一 OT 的 CLI/SDK/HTTP 三层接口、Unit/Dim 携带、ToA 双口径强制、复现与审计、错误与配额，并将本卷 3–11 章的物理与数值锚点落到可执行契约之上，支撑工程与科学场景的稳健对接与发布。