14-EFT.WP.Methods.Inference v1.0 | Appendix B: Implementation Bindings & Function Prototypes

Home ／ Docs-Technical WhitePaper ／ 14-EFT.WP.Methods.Inference v1.0

Appendix B: Implementation Bindings & Function Prototypes

I. Scope & Objectives

• Specify the I40-* implementation bindings — prototypes, inputs/outputs, idempotency and determinism contracts, observability and audit fields, and the exception model — so that inference is reproducibly identical across environments, devices, and versions.
• This appendix aligns with the measurement conventions, card schemas, and gate strategies in Chapters 3, 6, 7, 8, 9, 10, 11, 12, 13. All timestamps must be mapped to ts = alpha + beta * tau_mono prior to processing and publication.

II. Design Principles & Common Contracts

• Idempotency & determinism
  With EnvLock locked and a fixed anchor, the same input call returns equivalent outputs. If randomized operators are present, record rng.seed and rng_family, and provide a deterministic replay switch opts.det = true.
• Dimensions & safety
  Run check_dim(expr) on all inputs/outputs. Arguments to log/exp/ln must be dimensionless.
• Observability & audit
  Every I40-* call emits TS.latency_{p50,p95,p99}, TS.error, resource samples budget.cpu/gpu/mem, cost.per.req, and writes a verifiable fingerprint bound to the anchor.
• Errors & rollback
  Non-fatal exceptions surface using the enumeration in XV, and hooks for kill_switch and holdback integrate with Chapter 10’s alerting and self-healing.

III. Common Data Structures (summary)

• Graph
  Keys: sig:str, ops:list, inputs:spec, outputs:spec, dtype:dict, version:str.
• Runtime
  Keys: graph:Graph, artifacts:list, device:str, precision:str, EnvLock:dict, rng:{seed:int,family:str}.
• ScoreReport
  Keys: metrics:dict, R_emp:float, R_exp:float|None, ECE:float|None, MCE:float|None, NLL:float|None, confusion:dict|None, ts:str, fingerprint:str.
• CalibReport
  Keys: method:str, T_temp:float|None, iso_map:any|None, ECE_before:float, ECE_after:float, NLL_before:float, NLL_after:float, ts:str.
• DriftReport
  Keys: tests:{psi:float|None,ks:float|None,js:float|None}, p_value:float|None, decision:str, reasons:list, ts:str.
• ConsistencyReport
  Keys: delta_offon:float, R_infer:float, window:dict, policy:dict, decision:str, reasons:list, ts:str.
• Attribution
  Keys: method:str, importances:any, baseline:any|None, ts:str.

IV. I40-1 build_inference_graph(spec:dict) -> Graph

1. Input spec
   Required: inputs:spec, outputs:spec, ops:list, dtype:dict, precision:str, constraints:dict.
   Optional: quant:dict, fuse:bool, determinism:bool.
2. Contract
   If spec.determinism = true, nondeterministic ops are disallowed; check operator condition numbers and stability.
   Produce Graph.sig = hash(spec) and bind to anchor.
3. Failures & exceptions
   E_SCHEMA_MISMATCH, E_PRECISION_LOSS, E_NONDETERMINISM.
4. Pseudo-flow
   • Validate dtype/precision and dimensions.
   • Graph optimization (folding, fusion, quantization) with order-preservation guarantees.
   • Emit Graph and sig, record TS.*.

V. I40-2 load_artifacts(anchor:str) -> Runtime

• Input anchor
  Semantic: a joint reference to model weights, feature spec, and dependency hashes.
• Contract
  Runtime.EnvLock must pin drivers, libraries, and hardware capabilities; error if missing.
  Record rng.seed and rng_family (default from anchor).
• Failures & exceptions
  E_MODEL_MISMATCH, E_RESOURCE_EXCEEDED, E_TIMEBASE_SKEW.

VI. I40-3 run_inference(rt:Runtime, inputs:any, opts:dict) -> outputs:any

• Inputs
  inputs: follows Chapter 4 interfaces and Chapter 9 cards’ features.spec.
  opts: {batch:int, timeout_ms:int, det:bool, trace:bool}.
• Contract
  For each batch, return y_hat or distribution elements mean, var, quantile_q. If opts.det = true, force a fixed RNG.
  Attach TS.latency, TS.error, and resource samples; for streaming, append ts after mapping ts = alpha + beta * tau_mono.
• Failures & exceptions
  E_RESOURCE_EXCEEDED, E_PRECISION_LOSS, E_NONDETERMINISM.

VII. I40-4 score_predictions(y_true:any, y_pred:any, metrics:dict) -> ScoreReport

• Inputs
  Example metrics: {"acc":true,"auc":true,"ECE":{"K":15},"NLL":true,"reg":{"rmse":true}}.
• Contract
  Unified convention: R_emp = ( 1/N ) * Σ L( y_i, y_hat_i ). Classification threshold-scan ranges must be declared in metrics.
  Calibration metrics ECE, MCE, NLL follow Chapter 7.
• Failures & exceptions
  E_SCHEMA_MISMATCH, E_CALIBRATION_FAIL (e.g., missing distribution outputs).

VIII. I40-5 calibrate(runtime:Runtime, method:str, data:any) -> CalibReport

• Inputs
  method ∈ {"temperature","isotonic"}; data contains a validation set or online control window.
• Contract
  Temperature scaling learns T_temp > 0; post calibration require ECE_T <= ECE and NLL_after <= NLL_before as minimal pass gates.
  Persist a reversible mapping with versioning, write back artifacts, and update anchor.
• Failures & exceptions
  E_CALIBRATION_FAIL, E_RESOURCE_EXCEEDED.

IX. I40-6 estimate_uncertainty(runtime:Runtime, x:any) -> {mean:float, var:float, intervals:list}

• Inputs
  x: single sample or small batch; method inferred from runtime (e.g., ensemble, mc_dropout, quantile_reg).
• Contract
  Output at least mean, var and intervals, labeling confidence 1 - delta and the construction method.
  Provide post-calibration variants with _T suffix (e.g., var_T) per Chapter 7.
• Failures & exceptions
  E_MODEL_MISMATCH, E_RESOURCE_EXCEEDED.

X. I40-7 monitor_drift(stream:any, spec:dict) -> DriftReport

• Inputs
  Example spec: {"window":"W","tests":{"psi":true,"ks":true,"js":true},"tau":{"psi":0.2,"p":0.05}}.
• Contract
  Compute drift and return a decision decision ∈ {"ok","warn","block"}; map to the alert matrix in Chapter 10.
  If decision = "block", trigger kill_switch and log reasons.
• Failures & exceptions
  E_DRIFT_DETECTED (surfaced as a controllable exception).

XI. I40-8 align_timebase(trace:any, reference:any) -> {alpha:float, beta:float, fit:dict}

• Contract
  Fit the linear mapping ts = alpha + beta * tau_mono per postulate P41-2; prefer robust regression or RANSAC.
  Return fit with residual distribution and CI_{1-delta}. If |beta - 1| > tau_cons, report E_TIMEBASE_SKEW.
• Failures & exceptions
  E_TIMEBASE_SKEW.

XII. I40-9 explain(runtime:Runtime, x:any, method:str) -> Attribution

• Inputs
  method ∈ {"grad","intgrad","shap","lime"}.
• Contract
  Explanations may not alter the inference path; fix rng.seed for randomized approximations.
  Return importances and optional baseline; record TS.latency and resource usage to feed the score’s cost component.
• Failures & exceptions
  E_RESOURCE_EXCEEDED.

XIII. I40-10 compare_offline_online(off:any, on:any, policy:dict) -> ConsistencyReport

• Inputs
  policy: {"window":"W","tau_cons":0.01,"metrics":["delta_offon","ECE","NLL"]}.
• Contract
  Compute delta_offon = ( norm( y_hat_off - y_hat_on ) / norm( y_hat_off ) ) and R_infer = 1 - delta_offon.
  Replay windows and align ts; for distributional outputs, compare ECE/NLL per Chapter 7.
  Return decision ∈ {"pass","hold","rollback"} with reasons.
• Failures & exceptions
  E_TIMEBASE_SKEW, E_SCHEMA_MISMATCH.

XIV. Canonical State Machine & Rollback Hooks

1. States: INIT -> READY -> RUNNING -> DEGRADED -> ROLLBACK -> ARCHIVED.
2. Transitions
   • READY -> RUNNING: I40-10.decision = "pass" and score >= score_LCB.
   • RUNNING -> DEGRADED: TS.error > tau_error or I40-7.decision = "warn".
   • DEGRADED -> ROLLBACK: I40-7.decision = "block" or I40-10.decision = "rollback".
   • ROLLBACK -> READY: restored to previous anchor, ConsistencyReport passes.
3. Rollback actions
   Trigger kill_switch, cap q <= q_cap, apply holdback, and update RingMetrics.

XV. Exception Enumeration & Remedies

• E_MODEL_MISMATCH: graph/weight signatures disagree → rollback via load_artifacts to the previous anchor.
• E_SCHEMA_MISMATCH: I/O schema mismatch → fix features.spec and ParamCard.
• E_TIMEBASE_SKEW: time-base skew → run I40-8 and recompute ts.
• E_NONDETERMINISM: nondeterminism detected → set opts.det = true or replace the operator.
• E_CALIBRATION_FAIL: calibration diverges or degrades → switch method or enlarge the validation window.
• E_DRIFT_DETECTED: drift beyond gates → degrade and rollback.
• E_RESOURCE_EXCEEDED: budget overshoot → rate-limit, switch precision fp32/fp16/int8, or move devices.
• E_PRECISION_LOSS: numeric instability/underflow → rescale or raise precision.

XVI. Observability, Audit & Compliance Fields

• Observability keys: TS.latency_{p50,p95,p99}, TS.thrpt, TS.error, budget.cpu/gpu/mem, budget.power, cost.per.req.
• Audit keys: anchor, fingerprint, Graph.sig, EnvLock, rng.seed, rng.family, version, channel, PlanId, GateDecision, reasons.
• Time key: align all events to ts = alpha + beta * tau_mono before collection.

XVII. Cross-Domain / Cross-Device Hooks

• Device equivalence
  Emit delta_dev and attach CertEq; test precision/quant combinations per Chapter 11.
• Site heterogeneity
  I40-10 supports policy.site dimensions; aggregate by rings R = {R0,R1,R2,R3} and validate the score’s lower bound score_LCB.

XVIII. Versioning & Deprecation Strategy

• Versioning follows ver = major.minor.patch. Major changes may break compatibility and require a new ParamCard.version with meta.parent_fingerprint.
• Deprecation window
  Span at least two channel cycles (canary -> stable), and provide a compare_offline_online evidence chain.

XIX. Minimal Implementation Checklist (suggested order)

• Implement I40-1 / I40-2 and complete EnvLock / anchor management.
• Implement deterministic replay and TS.* observability in I40-3.
• Implement I40-4 / I40-5 to unlock Chapter 7 calibration and Chapter 8 scoring.
• Implement I40-10 and Chapter 6 consistency.
• Implement I40-7 and Chapter 10 alert matrix.
• Implement I40-8 time-base alignment and pre-acceptance checks.
• Optionally implement I40-6 / I40-9 for uncertainty and explainability.

XX. Cross-References

• Terms & symbols: Appendix A.
• Data & feature interfaces: Chapter 4.
• Calibration & uncertainty: Chapter 7.
• Performance metrics & SLO: Chapter 8.
• Pipeline & configuration cards: Chapter 9.
• Operations, monitoring & alerting: Chapter 10.
• Cross-domain/device: Chapter 11.
• Acceptance & scoring release: Chapter 12.
• Change management & canary strategy: Chapter 13.