26-EFT.WP.STG.Lensing v1.0 | Appendix A — Interface Reference (I71 Suite)

Home ／ Docs-Technical WhitePaper ／ 26-EFT.WP.STG.Lensing v1.0

Appendix A — Interface Reference (I71 Suite)

Goal: Enumerate and standardize the function prototypes, I/O contracts, and invariants for all implementation bindings I71-* in this volume, ensuring alignment between spectral and variational forms, auditable dimensional consistency, and manifest-ready deliverables.

I. Overview & Conventions

1. Naming & versioning
   • Interfaces are numbered I71-xx. Semantic versions (semver) are recorded in the manifest (see Chapter 15).
   • All inputs carry explicit unit/dimension metadata; fields that enter equations declare unit(field) and dim(field), and must pass check_dim( y - f(x) ).
2. Dual-form parallelism
   Any “apply/infer” interface must expose both spec (spectral) and var (variational) implementations; each must output delta_form.
3. Geometry & measure
   Paths and measures are explicit: e.g., spectral kernel realizations provide gamma(ell) or a graph measure M.
4. Error semantics
   Unified error codes E71-xxx (see §VIII). Every function returns status ∈ {ok, error} and an err field.

II. Core Types (abstract)

• GraphSpec = { V:int, E:int, edges:[(i,j,w)], L_type:str, B:str }, where L_type ∈ { L, L_norm, L_ani, L_vis }.
• MetricSpec = { name:str, params:dict } (e.g., an energy metric 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. Graph & Spectral Domain (I71-01 … I71-10)

• I71-01 build_graph(nodes, edges, L_type, B) -> { graph:GraphSpec, status, err }
  Inputs: node/edge lists, L_type, boundary B ∈ {dirichlet, neumann}.
  Invariants: L ≽ 0; non_decreasing(len(edges)).
• I71-02 build_metric(name, params) -> { M:MetricSpec, status, err }
  Defines E(x; M) = (1/2) * x^T M x; unit(E) = "[X]^2".
• I71-03 estimate_lambda_max(graph, L_type, tol) -> { lambda_max:float, u:float, iters:int, status }
  Power iteration / Chebyshev bounds; ensures rho(L) ≤ lambda_max.
• I71-04 laplacian_apply(graph, x) -> { y, status }
  Dimensions: dim(y) = dim(x); unit(y) = unit(x).
• I71-05 spectral_basis(graph, k) -> { U_k, Lambda_k, status }
  Offline validation only; runtime defaults to approximate bases.
• I71-06 check_dim(expr) -> { pass:bool, msg }
  Pre-flight check for any interface.
• I71-07 normalize_signal(x, mode) -> { x_norm, stats }
• I71-08 cache_chebyshev(graph, order) -> { cache_token, status }
• I71-09 graph_partition(graph, method) -> { parts, status }
• I71-10 bnd_embed(graph, B) -> { graph', mapping, status } (embed boundary conditions).

IV. Kernel Families & Responses (I71-11 … I71-20)

• I71-11 make_kernel_chebyshev(theta, order, lambda_max) -> { K:KernelSpec, status }
  Invariants: order ≥ 0; lambda_max > 0.
• I71-12 make_kernel_rational(num, den, stabilizer) -> { K, status }
  Stability: sup_λ | g(λ) | ≤ stabilizer.max_gain.
• I71-13 make_kernel_anisotropic(theta, order, lambda_max, A) -> { K, status }
  A is the anisotropy tensor; A ≻ 0.
• I71-14 kernel_response(K, lambda_grid) -> { resp, status }
  Outputs | g(λ) |; verify rho_bound = sup(resp).
• I71-15 calibrate_kernel_energy(K, M, x_ref) -> { T_trans, report, status }
  T_trans = E(K x_ref; M) / E(x_ref; M); assertions per C71-*.
• I71-16 kernel_diff(K, dtheta) -> { dK, status } (learning/sensitivity).
• 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 } (e.g., gating/residual fusion).

V. Composition & Dual-Form Application (I71-21 … I71-30)

• I71-21 compose_lens(kernels, topology, expr) -> { K_eff:LensStack, status }
  Invariants: topology ∈ { serial, parallel, residual, gated }; expr is reproducible.
• I71-22 apply_lens_spec(K_eff, x, graph, M, run) -> { y_spec, Telem, status }
  Spectral route: explicit bases or FFT-like; must pass check_dim(y_spec - x).
• I71-23 apply_lens_var(K_eff, x, graph, M, run) -> { y_var, Telem, status }
  Variational route: polynomial/iterative approximations; comparable to 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 }
  For inversion/learning; output dimensions/units match x.
• I71-27 invert_lens(y, K_eff, prior, reg) -> { x_hat, info, status }
  reg ∈ { l2, l1, tv, sparse }; returns iterations/residuals.
• 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 } (learning/validation budget).

VI. Visibility & View Domain (I71-31 … I71-40)

• I71-31 build_visibility(geom, occluders, los_algo) -> { vis, status }
  Output 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 } with alpha ∈ [0,1].
• I71-39 cast_shadow(graph, sources) -> { shadow_map, status }
• I71-40 vis_to_metric(vis) -> { M_vis:MetricSpec, status } (see Chapter 4).

VII. Learning & De-Lensing (I71-41 … I71-50)

• I71-41 train_supervised(ds, model, loss, contracts) -> { weights, metrics, status }
  Must emit: 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 } (see Chapter 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. Uncertainty & Contracts (I71-51 … I71-60)

• I71-51 estimate_uncertainty_mc(fn, x, N, seeds) -> { Uncertainty, status }
  Report U = k * u_c, coverage, and 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 } (if applicable).
• I71-60 robustness_sweep(noise_cards) -> { stress, status } (see Chapter 12).

IX. Runtime & Manifest (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 } (bypass / lower-order / damping).
• 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 } (privacy/minimum visibility).
• I71-79 diff_manifest(a, b) -> { delta, status }
• I71-80 import_artifacts(uris) -> { loaded, status }

X. Paneling & Telemetry (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. General Utilities (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. Global Invariants (caller & callee)

• 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 (anisotropy).
• Manifest core domains graph / kernel / compose / run / contracts must not be null.

XIII. Error Codes & Semantics (E71-xxx)

• E71-001 InvalidDim: units/dimensions mismatch (tripped by check_dim).
• E71-002 UnstableKernel: sup_λ | g(λ) | > bound or rho_bound > limit.
• E71-003 FormMismatch: delta_form > tol_form.
• E71-004 ManifestIncomplete: missing mandatory domains or signature verification failed.
• E71-005 ContractViolation: any C71-* not satisfied.
• E71-006 RuntimeHealthFail: runtime health check failed.
• E71-007 VisibilityInconsistent: cross-frame vis inconsistency beyond threshold.
• E71-008 ResourceExceeded: cpu/mem/latency beyond quotas.
• E71-009 SerializationError / E71-010 DeserializationError.

XIV. Versioning & Compatibility

• Minor versions must not break parameter names or defaults of I71-*; newly added fields must be optional and logged in manifest.changelog.
• Major (breaking) changes require a version bump and an automatic migration script via I71-79 diff_manifest.

XV. Reference Call Sequences (Executable Guides)

• Offline assembly & release:
  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 execution:
  runtime_open → runtime_cache_prime → runtime_exec(…)* → snapshot_panel → runtime_close.
• Inversion & de-lensing:
  invert_lens / deconvolve_primal_dual → estimate_uncertainty_gum → validate_contracts.

XVI. Cross-References

Summary

• This appendix specifies the full I71-* interface suite—prototypes, constraints, and error semantics.
• All implementations must support spec/var dual forms, explicit units/dimensions, signable manifests, and contract checks in parallel.
• The reference call sequences and global invariants provide end-to-end scaffolding for a reproducible, auditable, and rollback-capable lens system.