35-EFT.WP.EDX.OrientedTension v1.0 | Chapter 12 Implementation Bindings & APIs (I)

Chapter 12 Implementation Bindings & APIs (I)

I. Abstract & Scope
This chapter defines the implementation bindings and external interface family I80-* / API v1 for Oriented Tension across CLI/SDK/HTTP layers: unified request–response contracts, unit & dimension (Unit/Dim) carriage, integration with DatasetCard/ModelCard/MetrologyCard/PipelineCard, reproducible execution of SimStack-OT, error semantics & quotas, and security & audit. Equations and symbols use English notation wrapped in backticks; SI units with 3 significant figures by default. Any ToA result must return both forms in parallel with explicit path gamma(ell) and measure d ell.

II. Dependencies & References

1. Geometry & orientation: Chapter 3 (S80-1/2).
2. Constitutive & dynamics: Chapter 4 (S80-3/4, P80-2/3/9/10).
3. Metrology: Chapter 5 (M80-1…4).
4. Couplings & media: Chapter 6 (S80-5/6).
5. Energy accounting: Chapter 7 (S80-7/8).
6. Numerical methods & simulation: Chapter 10 (SimStack-OT).
7. Data & pipelines: I75-*/M75-* (Chapter 14 conventions, reusing this volume’s card formats).

III. Normative Anchors (added in this chapter, I80-*)

8. I80-0 (Interface Layers): a single contract & error semantics across:
   • 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: compute oriented tension from the order tensor and deformation gradient; return Pa, symmetric & traceless-consistent.
10. I80-2 infer_Q_from_polarimetry(data, R_inst) -> {Q_ij, Cov_Q}: invert Q_ij and covariance from polarimetry/scattering while enforcing Tr(Q)=0.
11. I80-3 couple_transport(Q_ij, fields, params) -> {W_cpl, D_eff, eps_ij, mu_ij, C_eff}: produce coupling free energy and effective transport/wave tensors.
12. I80-4 edx_balance(T_fil_ij, W_orient, flows, fields) -> {P_in, P_mech, P_cpl, P_diss, Phi_E}: power decomposition and closure residuals.
13. I80-5 simulate_ot(SimCfg) -> {products, metrics}: run SimStack-OT for numerical simulations & benchmarks.
14. I80-6 fit_ot(bundle, model, priors) -> {posterior, evidence, masks}: joint fitting of OT constitutive/coupling parameters with evidence and dominance masks.
15. I80-7 export_cards(artifact) -> {DatasetCard|ModelCard|MetrologyCard|PipelineCard}: export standard cards from artifacts.
16. I80-8 metrics_validate(metrics, thresholds) -> {pass|fail, diff}: metric gates (incl. EDX-closure).
17. I80-9 (Contract & Units): all numeric fields MUST carry unit & dim; Phi(E) MUST include sr and energy dimension; Q_ij is dimensionless and traceless; tensor units & dimensions must close.
18. I80-10 (ToA Requirement): any request/response with T_arr MUST return T_arr^A/T_arr^B plus {gamma(ell), d ell} and delta_form.
19. I80-11 (Reproducibility): optional request seed; responses return {rng_state, code_hash, data_hash}; artifacts may be registered as benchmarks.

IV. Body Structure

I. API Layers & Styles

• HTTP endpoints (examples):
  /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: methods mirror I80-*; returns are unit/dimension-bearing structured objects.
• CLI: equivalent subcommands; defaults to products/ and metrics.json.

II. Contracts & Schemas (JSON examples)

• Request (/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

}

• Response (excerpt):

{

"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. Unit & Dimension Audits

• T_fil_ij: Pa, dim M L^-1 T^-2; Q_ij: 1 with Tr(Q)=0; D_eff: m^2·s^-1; ε_ij/μ_ij: F·m^-1/H·m^-1 (or relative) with mapping notes; Φ_E: W·m^-2.
• Failures (missing sr, nonzero trace, non-closed dims) return 422 UNIT_MISMATCH.

IV. Error Semantics & Quotas

• Error codes: 400 INVALID_ARGUMENT, 412 PRECONDITION_FAILED, 422 UNIT_MISMATCH, 409 CONFLICT, 429 RATE_LIMIT, 500 INTERNAL.
• Responses always include a trace_id and see: anchors for audit/repro.

V. Security, Audit & Quotas

• Auth: API key (Authorization: Bearer), optional HMAC-timestamp signing.
• Audit: log {who, when, where, code_hash, data_hash, rng_state} aligned with registry indices.
• Quotas: enforced by requests/min and compute-min/day; overage yields 429 and suggests DAG-based segmentation via PipelineCard.

VI. Workflows & Use Cases (M-series map)

• A. Observations → OT constitutive & couplings: 1) infer_Q_from_polarimetry, 2) oriented_tension + couple_transport, 3) fit_ot → {posterior, evidence, masks}, 4) metrics_validate.
• B. Energy ledger & closure audit: 1) edx_balance for {P_in,P_mech,P_cpl,P_diss,Phi_E}, 2) audit per Chapter 7, 3) export EDXLedger.npz.
• C. Simulate–synthesize–compare: 1) simulate_ot, 2) export_cards, 3) fit_ot on synthetic+observed for evidence & metrics.

VII. Cross-References

• Math/physics anchors: S80-1/2/3/4/5/6/7/8/15/16/17/18.
• Fitting & evidence: Chapter 9.
• Simulation & benchmarks: Chapter 10.
• Data & pipeline cards: Chapter 14 I75-*/M75-*.

VIII. Validation, Criteria & Counterexamples

• Positive criteria: all responses carry unit/dim; Q_ij symmetric & traceless; dual-form ToA present when relevant; gates (incl. EDX-closure) passed; reproducible hash/rng_state.
• Negative criteria: missing {gamma(ell), d ell} or single-form T_arr; UNIT_MISMATCH; Tr(Q)≠0; wrong dims for ε/μ/C; benchmark regression failures without remediation.
• Contrasts: call-graph & evidence comparisons for {orientation-only, coupling-only, orientation+coupling}; ToA {A only, B only, A+B} impacts; {one-zone, multi-zone} transport on the same data.

IX. Figures & Lists

• Tab. 12-1 Endpoint overview (HTTP).
• Tab. 12-2 Error codes & semantics.
• Tab. 12-3 SDK prototypes (Python, excerpt).
• Tab. 12-4 Contract fields & units (excerpt).