26-EFT.WP.STG.Lensing v1.0 | 附录A 接口参考（I71 全集）

目录 ／ 文档-技术白皮书 ／ 26-EFT.WP.STG.Lensing v1.0

附录A 接口参考（I71 全集）

目标：枚举并规范本卷所有实现绑定 I71-* 的函数原型、输入输出与不变量，确保谱/变分两口径一致、量纲可校核、清单可落盘与可审计。

I. 总述与约定

1. 命名与版本
   • 接口统一编号 I71-xx，语义化版本以 semver 记录在清单（见第15章）。
   • 所有输入均为显式单位/量纲对象；进入方程的字段声明 unit(field) 与 dim(field)，通过 check_dim( y - f(x) )。
2. 两口径并行
   任一“应用/推断”接口均提供 spec 与 var 两实现；必须输出 delta_form。
3. 几何与测度
   路径与测度显式：如核的谱实现需提供 gamma(ell) 或图测度 M。
4. 错误语义
   统一错误码 E71-xxx（见VIII）；所有函数返回 status ∈ {ok,error} 与 err 字段。

II. 核心类型（抽象定义）

• GraphSpec = {V:int, E:int, edges:[(i,j,w)], L_type:str, B:str}，L_type ∈ {L, L_norm, L_ani, L_vis}。
• MetricSpec = {name:str, params:dict}（如能量度量 M）。
• KernelSpec = {family:str, order:int, theta:dict, lambda_max:float}。
• LensStack = {topology:str, kernels:[KernelSpec], expr:str}。
• RunConfig = {window:int, stride:int, cache:dict, passthrough_on_fail:bool, RefCond:dict}。
• Telem = {latency:float, cpu:float, mem:float, ts:int}。
• Uncertainty = {method:str, u:dict, U:dict, nu_eff:float, k:float}。
• ContractReport = {rule_id:str, pass:bool, msg:str}。

III. 图与谱域（I71-01…I71-10）

1. I71-01 build_graph(nodes, edges, L_type, B) -> {graph:GraphSpec, status, err}
   • 输入：节点/边列表，L_type，边界 B ∈ {dirichlet, neumann}。
   • 不变量：L ≽ 0；non_decreasing(len(edges))。
2. I71-02 build_metric(name, params) -> {M:MetricSpec, status, err}
   用于定义能量 E(x;M) = (1/2) * x^T M x；unit(E) = "[X]^2"。
3. I71-03 estimate_lambda_max(graph, L_type, tol) -> {lambda_max:float, u:float, iters:int, status}
   语义：幂迭代/切比雪夫边界；rho(L) ≤ lambda_max。
4. I71-04 laplacian_apply(graph, x) -> {y, status}
   量纲：dim(y) = dim(x)；unit(y) = unit(x)。
5. I71-05 spectral_basis(graph, k) -> {U_k, Lambda_k, status}
   仅用于离线验证；运行时默认近似基。
6. I71-06 check_dim(expr) -> {pass:bool, msg}
   任意接口前置检查。
7. I71-07 normalize_signal(x, mode) -> {x_norm, stats}
8. I71-08 cache_chebyshev(graph, order) -> {cache_token, status}
9. I71-09 graph_partition(graph, method) -> {parts, status}
10. I71-10 bnd_embed(graph, B) -> {graph', mapping, status}（边界条件嵌入）。

IV. 核族与响应（I71-11…I71-20）

• I71-11 make_kernel_chebyshev(theta, order, lambda_max) -> {K:KernelSpec, status}
  不变量：order ≥ 0；lambda_max > 0。
• I71-12 make_kernel_rational(num, den, stabilizer) -> {K, status}
  稳定性约束：sup_λ |g(λ)| ≤ stabilizer.max_gain。
• I71-13 make_kernel_anisotropic(theta, order, lambda_max, A) -> {K, status}
  A 为各向异性权张量；A ≻ 0。
• I71-14 kernel_response(K, lambda_grid) -> {resp, status}
  输出 |g(λ)|；校核 rho_bound = sup(resp)。
• I71-15 calibrate_kernel_energy(K, M, x_ref) -> {T_trans, report, status}
  T_trans = E(Kx_ref;M) / E(x_ref;M)；断言见 C71-*。
• I71-16 kernel_diff(K, dtheta) -> {dK, status}（用于学习/灵敏度）。
• I71-17 kernel_stability_margin(K) -> {margin, status}。
• I71-18 kernel_to_json(K) -> {json, status} / I71-19 kernel_from_json(json) -> {K, status}。
• I71-20 fuse_kernels(K_list, rule) -> {K_fused, status}（如门控/残差）。

V. 组合与两口径应用（I71-21…I71-30）

• I71-21 compose_lens(kernels, topology, expr) -> {K_eff:LensStack, status}
  不变量：拓扑 ∈ {serial, parallel, residual, gated}；expr 可复现。
• I71-22 apply_lens_spec(K_eff, x, graph, M, run) -> {y_spec, Telem, status}
  口径：显式谱基或 FFT-like；check_dim(y_spec - x)。
• I71-23 apply_lens_var(K_eff, x, graph, M, run) -> {y_var, Telem, status}
  口径：多项式/迭代近似；必须可与 spec 比对。
• I71-24 compare_forms(y_spec, y_var, tol) -> {delta_form:float, pass:bool, status}
  delta_form = || y_spec - y_var ||_2。
• I71-25 jvp_lens(K_eff, x, v) -> {Jv, status} / I71-26 vjp_lens(K_eff, x, w) -> {J_Tw, status}
  用于反演/学习；量纲与 x 一致。
• I71-27 invert_lens(y, K_eff, prior, reg) -> {x_hat, info, status}
  正则：reg ∈ {l2, l1, tv, sparse}；返回迭代/残差。
• I71-28 lens_energy_balance(x, y, M) -> {T_trans, status}
• I71-29 approx_error_bound(K_eff, graph, order) -> {eps_bound, status}
• I71-30 sample_complexity(K_eff, drift, risk) -> {n_min, status}（学习/验证样本量估计）。

VI. 可见性与视域（I71-31…I71-40）

• I71-31 build_visibility(geom, occluders, los_algo) -> {vis, status}
  输出 vis ∈ [0,1]^V；unit(vis)=1。
• I71-32 los_mask(geom, obstacles) -> {mask:{los:[], nlos:[]}, status}
• I71-33 shading_operator(light, brdf, geom) -> {S, status}
• I71-34 gate_by_visibility(K_eff, vis, rule) -> {K_gated, status}
• I71-35 occlusion_penalty(x, vis) -> {pen:float, status}
• I71-36 visibility_consistency(vis_t, vis_t1, tol) -> {pass, drift, status}
• I71-37 reproject_view(map, atlas) -> {map', status}
• I71-38 soft_occlusion(x, alpha) -> {x', status}（alpha ∈ [0,1]）。
• I71-39 cast_shadow(graph, sources) -> {shadow_map, status}
• I71-40 vis_to_metric(vis) -> {M_vis:MetricSpec, status}（见第4章）。

VII. 学习与去透镜（I71-41…I71-50）

• I71-41 train_supervised(ds, model, loss, contracts) -> {weights, metrics, status}
  强制输出：delta_form, rho_bound, T_trans。
• I71-42 train_selfsupervised(ds, objective, invariances) -> {weights, status}
• I71-43 train_causal_invariant(groups, confounds, loss) -> {weights, inv_test, status}
• I71-44 distill_to_kernel(model) -> {K_distilled, status}
• I71-45 sparsify_pathways(K_eff, budget) -> {K_sparse, report, status}
• I71-46 hyper_search(space, eval_fn, budget) -> {best_cfg, leaderboard}
• I71-47 regularize_physical(K_eff, constraints) -> {K_phys, gap, status}（见第10章物理一致）。
• I71-48 deconvolve_primal_dual(y, priors) -> {x_hat, dual, status}
• I71-49 simulate_lens(graph, K_eff, seeds) -> {dataset, stats}
• I71-50 export_onnx(model_or_K) -> {uri, status}

VIII. 不确定度与契约（I71-51…I71-60）

• I71-51 estimate_uncertainty_mc(fn, x, N, seeds) -> {Uncertainty, status}
  U = k * u_c；覆盖率与 nu_eff 必填。
• I71-52 estimate_uncertainty_gum(J, V_x, extras) -> {Uncertainty, status}
  u_c^2 = J V_x J^T + u^2(ε_approx)。
• I71-53 validate_contracts(results, rules) -> {reports:[ContractReport], pass_all:bool}
• I71-54 drift_detector(stream, refs, metrics) -> {alarms, status}
• I71-55 guardband_suggest(metric_hist, risk) -> {gb, status}
• I71-56 conf_int_quantile(samples, q) -> {ci, status}
• I71-57 reconcile_units(units) -> {map, pass}
• I71-58 coverage_report(pred, gt) -> {confmat, auc, status}
• I71-59 fairness_report(slices, metrics) -> {gaps, status}（若适用）。
• I71-60 robustness_sweep(noise_cards) -> {stress, status}（见第12章）。

IX. 运行时与清单（I71-61…I71-80）

• I71-61 runtime_open(K_eff, graph, run) -> {session, warm_stats, status}
• I71-62 runtime_exec(session, x) -> {y, Telem, status}
• I71-63 runtime_close(session) -> {final_stats, status}
• I71-64 runtime_cache_prime(session, cache_spec) -> {hit_ratio, status}
• I71-65 runtime_health(session) -> {ok:bool, diag}
• I71-66 throttle_policy(session, limits) -> {applied, status}
• I71-67 fallback_plan(session, policy) -> {armed:bool}（旁路/降阶/阻尼）。
• I71-71 build_manifest(K_eff, graph, run, metrics, U, contracts) -> {manifest, status}
• I71-72 canonicalize_manifest(manifest) -> {bytes, status}
• I71-73 sign_manifest(bytes, keyref) -> {signature, status}
• I71-74 publish_manifest(manifest, registry) -> {uri, status}
• I71-75 verify_manifest(manifest) -> {pass, issues}
• I71-76 rollback_plan(manifest, telemetry) -> {actions, status}
• I71-77 snapshot_panel(session) -> {panel_uri, status}
• I71-78 redact_manifest(manifest, policy) -> {manifest', status}（隐私/最小可见）。
• I71-79 diff_manifest(a, b) -> {delta, status}
• I71-80 import_artifacts(uris) -> {loaded, status}

X. 面板与遥测（I71-81…I71-90）

• I71-81 emit_panel(metrics, U, contracts) -> {ok, uri}
• I71-82 log_telem(session, Telem) -> {ok}
• I71-83 alert_on_contract(reports) -> {alerts}
• I71-84 record_ab_test(a_uri, b_uri, routes) -> {exp_id}
• I71-85 summarize_runtime(window) -> {P95,P99,drift,delta_form_p99}
• I71-86 export_time_series(series, uri) -> {ok}
• I71-87 register_dashboard(cards) -> {panel_uri}
• I71-88 attach_groundtruth(stream_uri) -> {binding}
• I71-89 tag_release(manifest, tag) -> {ok}
• I71-90 archive(manifest, retention) -> {ok}

XI. 通用工具（I71-91…I71-99）

• I71-91 check_dim(y_minus_fx) -> {pass, msg}
• I71-92 assert_invariants(state) -> {pass, violated:[str]}
• I71-93 hash_bytes(bytes, algo) -> {digest}
• I71-94 rng(seed) -> {sampler}
• I71-95 serialize(obj, fmt) -> {bytes} / I71-96 deserialize(bytes, fmt) -> {obj}
• I71-97 time_it(fn, *args) -> {ret, Telem}
• I71-98 map_device(obj, device) -> {obj'}
• I71-99 ensure_reproducible(cfg) -> {pass, diff}

XII. 不变量（全局约束，调用方与被调方共同遵守）

• two_forms_present == true；delta_form ≤ tol_form；rho_bound ≤ 1 + ε；E(y;M) ≥ 0。
• unit(T_trans)=1；dim(y) = dim(x)；lambda_max > 0；A ≻ 0（各向异性）。
• 所有清单核心域 graph/kernel/compose/run/contracts 不得为 null。

XIII. 错误码与语义（E71-xxx）

• E71-001 InvalidDim：量纲/单位不匹配（触发于 check_dim）。
• E71-002 UnstableKernel：sup_λ |g(λ)| > bound 或 rho_bound > limit。
• E71-003 FormMismatch：delta_form > tol_form。
• E71-004 ManifestIncomplete：缺失强制域或签名校验失败。
• E71-005 ContractViolation：任一 C71-* 未通过。
• E71-006 RuntimeHealthFail：运行态健康检查未通过。
• E71-007 VisibilityInconsistent：vis 跨帧不一致超阈。
• E71-008 ResourceExceeded：cpu/mem/latency 超配额。
• E71-009 SerializationError / E71-010 DeserializationError。

XIV. 版本与兼容性

• 次版本升级不得破坏 I71-* 的参数名与默认值；新增字段需可选并记录于 manifest.changelog。
• 破坏性变更需升级主版本并提供 I71-79 diff_manifest 的自动迁移脚本。

XV. 参考调用序（可执行指引）

• 离线组装与发布：build_graph → estimate_lambda_max → make_kernel_* → compose_lens → calibrate_kernel_energy → apply_lens_spec/var → compare_forms → estimate_uncertainty_* → validate_contracts → build_manifest → sign_manifest → publish_manifest。
• 运行时执行：runtime_open → runtime_cache_prime → runtime_exec(…)* → snapshot_panel → runtime_close。
• 反演与去透镜：invert_lens / deconvolve_primal_dual → estimate_uncertainty_gum → validate_contracts。

XVI. 交叉引用

小结

• 本附录给出 I71-* 接口全集的原型、约束与错误语义；
• 所有实现须并行支持 spec/var 两口径、显式单位/量纲、可签名清单与契约校核；
• 参考调用序与不变量为落地“可复现、可审计、可回退”的透镜系统提供端到端支撑。