51-管线卡 Template v1.0 | 第11章 接口与实现绑定（API/函数原型）

目录 ／ 文档-技术白皮书（V5.05） ／ 51-管线卡 Template v1.0

第11章 接口与实现绑定（API/函数原型）

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

• 定义管线与阶段的**外部接口（API）与实现绑定（Implementation Bindings）**之统一口径，涵盖函数原型、错误语义、幂等与重试、鉴权与审计、OpenAPI/gRPC/CLI 约定与制品导出。
• 涉及路径量（到达时/相位）之接口，正文显式 gamma(ell) 与测度 d ell，数据侧记录 delta_form ∈ {general, factored}；发布要求 p_dim = 1.0。

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

• DAG/状态机：pipeline_graph.json 与 state_machine.yaml 已定义（见第3章）。
• 契约与阶段：contract.yaml/schema.json 与 stage.yaml 完整（见第4/6章），并通过 I70-dim_check。
• 时基与同步：满足第5章门限（clock_state="locked"、σ_y(τ)、|δt_abs|/|Δτ_ch|）。
• UQ 与协方差：与第10章及误差预算卡一致，cov_group/coverage 对齐。
• 引用与版本：所有接口文档使用“卷名 + 版本 + 锚点（P/S/M/I）”，锚点直指率 ≥ 90%。

III. 错误语义与返回约定（Error Model & Return Envelope）

• 错误分类：E_INPUT｜E_DIM｜E_GATE｜E_SYNC｜E_UQ｜E_INTERNAL。
• 统一返回信封：

{

"status": "OK|ERROR",

"code": 0,

"error": { "type": "E_*", "message": "...", "details": {...} },

"payload": {...},

"metrics": {"latency_ms":123,"retries":0},

"anchors": ["EFT.WP.Core.Equations v1.1:S20-1"],

"version": "1.0.0",

"checksum": "sha256:..."

}

IV. 幂等、重试与审计（Idempotency, Retry & Audit）

• 幂等键：idempotency_key = f(run_id, partition, window, …)；同键多次调用输出不变。
• 重试策略：retry_policy = { max_retries, backoff ∈ {const, exp, jitter}, deadline }；重试不改变 idempotency_key 与输入快照。
• 审计：所有写入端点在 audit.jsonl 记录时间戳、操作者、input_hashes[]、重试计数、签名与 checksum。

V. 核心函数原型（Implementation Bindings, I60–I69）

1. I60-stage_exec(ctx, x) -> y | err
   • in：ctx{idempotency_key,retry_policy,window,partition}；x 为阶段输入（与 TARR 对齐）。
   • out：阶段输出 y 与指标 metrics{latency,throughput}。
   • errors：E_INPUT/E_DIM/E_GATE/E_SYNC/E_UQ/E_INTERNAL。
   • see：EFT.WP.Core.Equations v1.1:S20-1、EFT.WP.Core.Metrology v1.0:check_dim。
2. I61-validate_gate(card, gates[]) -> report.json
   • in：阶段或管线描述 card、门集合 ["G1".."G8"]。
   • out：{gates:{G1:true|0.93,...},stops_triggered:[],links{check_dim_report,audit}}。
   • see：本卷第9章。
3. I62-export_artifacts(fmt) -> {manifest, checksums}
   • in：fmt ∈ {zip, tgz}；
   • out：report_manifest.yaml、checksums[]。
4. I63-path_align(path,inplace=false) -> path'
   • in：path{gamma_ell[],d_ell[],n_eff[],delta_form}。
   • out：对齐/补齐后的路径；保证 len(gamma_ell)=len(d_ell)=len(n_eff)。
   • see：第5/6章。
5. I64-derive_arrival(path,c_ref) -> T_arr
   • form：T_arr = ( ∫ ( n_eff / c_ref ) d ell )；或 T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )。
   • req：正文显式 gamma(ell)、d ell；数据记录 delta_form；p_dim = 1.0。
6. I65-derive_phase(path,lambda_ref) -> Phi
   form：Phi = ( 2π / λ_ref ) * ( ∫ n_eff d ell )。
7. I66-uq_delta(J, Sigma) -> {u, u_c, U}
   • in：J=∂f/∂x|_{x̂}、Σ=Cov(x)；
   • out：标准不确定度与扩展不确定度；与第10章口径一致。
8. I67-cov_blocks_merge(blocks[]) -> Σ
   功能：块协方差拼接；验证 PD（必要时加抖动）。
9. I68-stage_replay(subgraph, checkpoint) -> report
   约束：拓扑倒序回放；通过 G1–G8；一致性校核输出哈希。
10. I69-emit_audit(event) -> OK
    event：{ts,event,stage_id,idempotency_key,input_hashes,attempt,...}。

VI. OpenAPI（REST）契约（节选）

openapi: 3.0.3

info: { title: "Pipeline API", version: "1.0.0" }

servers: [{ url: "https://api.example.com/v1" }]

components:

securitySchemes: { bearerAuth: { type: http, scheme: bearer } }

schemas:

StageExecRequest:

type: object

required: [ctx, x]

properties:

ctx:

type: object

properties:

idempotency_key: { type: string }

retry_policy: { type: object }

window: { type: string }

partition: { type: string }

x: { $ref: "#/components/schemas/StageInput" }

StageExecResponse:

type: object

properties:

status: { type: string }

code: { type: integer }

payload: { $ref: "#/components/schemas/StageOutput" }

metrics: { type: object }

anchors: { type: array, items: { type: string } }

version: { type: string }

checksum: { type: string }

paths:

/stages/{id}/exec:

post:

security: [{ bearerAuth: [] }]

summary: "Execute a stage (idempotent)"

parameters: [{ in: path, name: id, required: true, schema: { type: string } }]

requestBody:

required: true

content: { application/json: { schema: { $ref: "#/components/schemas/StageExecRequest" } } }

responses:

"200": { description: "OK", content: { application/json: { schema: { $ref: "#/components/schemas/StageExecResponse" } } } }

"409": { description: "Idempotency conflict" }

/validate:

post:

summary: "Validate gates"

requestBody: { required: true, content: { application/json: { schema: { type: object, properties: { gates: { type: array, items: { type: string } } } } } } }

responses: { "200": { description: "Validation report" } }

/artifacts/export:

post:

summary: "Export artifacts"

responses: { "200": { description: "Manifest & checksums" } }

VII. gRPC 接口（节选，proto）

syntax = "proto3";

package pipeline.v1;

​

message Ctx {

string idempotency_key = 1;

string window = 2;

string partition = 3;

}

​

message StageExecRequest {

Ctx ctx = 1;

bytes x = 2; // Avro/Parquet/JSON payload

}

​

message StageExecResponse {

string status = 1;

int32 code = 2;

bytes payload = 3;

map<string,string> metrics = 4;

repeated string anchors = 5;

string version = 6;

string checksum = 7;

}

​

service StageService {

rpc Exec(StageExecRequest) returns (StageExecResponse);

rpc Validate(ValidateRequest) returns (ValidateResponse);

rpc ExportArtifacts(ExportRequest) returns (ExportResponse);

}

VIII. CLI 约定（节选）

# 幂等执行

pipeline stage exec stage-30-arrival \

--ctx.idempotency_key run42+p010+win001 \

--in path.gamma_ell=@gamma.npy --in path.d_ell=@d_ell.npy \

--in medium.n_eff_profile=@n.npy --in ref.c_ref=2.9979e8

​

# 门校验

pipeline validate --gates G1 G2 G3 G4 G5 G6 G7 G8 --out reports/validate_report.json

​

# 导出制品

pipeline artifacts export --fmt tgz --out PTN_EXPORT/artifacts.tgz

IX. 安全与访问控制（Security & Access Control）

• 鉴权：Bearer 或 mTLS；最小权限原则，读写分离。
• 审计必需：所有写操作需审计并保存签名与 checksum。
• 数据保护：敏感字段加密/脱敏；日志不落敏感原文。

X. 路径阶段专属规范（Path-Specific Rules）

• 必备输入：gamma(ell)、d ell、n_eff(ell)、c_ref、（相位类）λ_ref；接口响应须回显 delta_form。
• 统一口径：
  T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )；T_arr = ( ∫ ( n_eff / c_ref ) d ell )；
  Phi = ( 2π / λ_ref ) * ( ∫ n_eff d ell )。
• 量纲闭合：接口实现必须在返回前完成 I70-dim_check，保证 p_dim = 1.0。

XI. 机读示例与反例（Machine-Readable Examples / Anti-Patterns）
A. 正例：阶段执行请求/响应

{"ctx":{"idempotency_key":"run42+p010+win001"},"x":{"path":{"gamma_ell":[...],"d_ell":[...],"delta_form":"general"},"ref":{"c_ref":2.9979e8},"medium":{"n_eff_profile":[...]}}}

{"status":"OK","code":0,"payload":{"obs":{"T_arr":1.23e-8}},"metrics":{"latency_ms":87},"anchors":["EFT.WP.Core.Equations v1.1:S20-1"],"version":"1.0.0","checksum":"sha256:..."}

B. 反例：缺少 d ell 与括号

{"x":{"path":{"gamma_ell":[...]}, "control":{"form":"T_arr = ∫ n_eff / c_ref d ell"}}} // 应拒绝

XII. 发布与目录结构（Release & Layout）

PTN_EXPORT/

api/

openapi.yaml

grpc.proto

bindings/

stage-30-arrival.yaml

stage-40-phase.yaml

reports/

check_dim_report.json

validate_report.json

audit.jsonl

figs/

api_topology.svg

report_manifest.yaml

SIGNATURE.asc

XIII. 执行勾选清单（Checklist）

• I60–I69 接口与错误语义落库；幂等键与重试策略已配置。
• 所有涉及路径量的接口显式 gamma/measure/delta_form；控制式括号化，I70-dim_check 通过，p_dim = 1.0。
• OpenAPI/gRPC/CLI 三端一致；鉴权、最小权限与审计生效。
• /validate 返回 G1–G8 状态与 stops_triggered；制品导出含 report_manifest.yaml 与签名。
• 引用与版本锁定合规（锚点直指率 ≥ 90%）；与第5/6/9/10章配置一致。