05-EFT.WP.Core.Errors v1.0 | Chapter 1 — Error System and Naming

Home ／ Docs-Technical WhitePaper ／ 05-EFT.WP.Core.Errors v1.0

Chapter 1 — Error System and Naming

I. Chapter Scope and Applicability

• Define the error domains, severity levels, and a coding scheme to form a cross-volume, traceable error lexicon and registration standard that supports register_error_code, normalize_error, log_event, and retry / fallback implementation bindings.
• Applicability spans five families of error—observation, modeling, data, numerical, and runtime—kept consistent with Core.Metrology, Core.Parameters, and Core.Equations at the levels of dimensions, priors, and governing equations.

II. Error Domain Taxonomy and Boundaries

• MET (Metrology): calibration drift, dimensional inconsistency, missing reference conditions; tightly bound to check_dim(expr), RefCond, U = k * u_c.
• MOD (Model): model misspecification, prior conflicts, broken equivalence constraints; related to r = y - f(x; theta), prior(theta), C_eq / C_ineq.
• DAT (Data): missingness, mislabeling, outliers and drift; related to m ∈ {0,1}, mask_outlier ∈ {0,1}, drift_score.
• NUM (Numerical): rounding and truncation, divergence and overflow; related to u_round, O(h^p), richardson_extrapolate.
• OPS (Operations): interface timeouts, resource exhaustion, version incompatibility; related to traceability_chain, scenario and version governance.
• INT (Interop): cross-volume or cross-service interoperation errors such as unit policy mismatches, resolve_ref failures, or mixed arrival-time conventions.
• Boundary rule: assign by primary cause; when multiple are triggered, classify to the primary domain and link secondary causes via see.

III. Severity Levels and Action Matrix

1. Levels: severity ∈ {info, warn, minor, major, critical}.
2. Impact dimensions: safety, scientific_validity, latency, availability, cost.
3. Action matrix (summary):
   • info: log and visualize; no automatic action.
   • warn: log, sample report, advisory retry.
   • minor: retry(policy) once; fallback if needed.
   • major: enforce fallback(models, "weighted") or graceful_degradation; mark sample mask_outlier=1.
   • critical: cut the path immediately, preserve state, raise alerts and roll back; block non-compliant reports (e.g., failed check_dim).

IV. Postulates P71-1…P71-3 (Error Naming and Severity)

• P71-1 (Uniqueness & Stability): each error is uniquely identified by the triple (domain, class, code); the textual message may evolve, but the semantic scope and trigger conditions remain invariant.
• P71-2 (Dimensional Priority): any error involving physical quantities must first fall into the MET/INT domains and must provide evidence comparing dim(lhs) and dim(rhs); a failed check_dim is critical.
• P71-3 (Separation of Impact and Remedy): severity expresses impact and does not encode remediation; remediation is a policy suggestion that may evolve with environment and strategy libraries—both dimensions evolve independently.

V. Coding Scheme and Field Specification

1. Syntax: E-<DOMAIN>-<CLASS>-<NNN>[@vMAJOR]
   • <DOMAIN> ∈ {MET, MOD, DAT, NUM, OPS, INT}.
   • <CLASS> is UPPER_SNAKE_CASE English, e.g., DIMENSION, CALIB, PRIOR, MISSING, OUTLIER, ROUNDING, TIMEOUT.
   • <NNN> is a three-digit sequence, incremented per domain; @vMAJOR is optional for declaring a compatibility breakpoint.
2. Registration fields (aligned with register_error_code):
   code, name (lower_snake_case, e.g., dimension_mismatch), severity, domain, message, remediation, see.
3. Requirements:
   • message must be English-only with interpolable placeholders (e.g., {unit_from}->{unit_to}).
   • When arrival time appears, write full path and measure: T_arr = ( ∫ ( n_eff / c_ref ) d ell ), and specify gamma(ell) and d ell.
   • Do not use non-ASCII characters, unit symbols, or spaces in code or name.

VI. Workflow M71-1: Error Normalization and Handling

• Capture: intercept exceptions or rule-triggered violations at model/pipeline/interface boundaries.
• Normalize: map to standard fields and code with normalize_error(err).
• Classify: compute severity from context and set_error_policy(domain, policy).
• Record: call log_event(code, level, context) and attach a traceability_chain.
• Decide: select retry / fallback / graceful_degradation per the action matrix.
• Report: annotate metrology/scientific outputs with impacts (e.g., inflate U, lower confidence, set mask_outlier).
• Regress: include in regression baselines and adapt thresholds over time (drift_score monitoring).

VII. Canonical Code Catalog (Excerpt)

• E-MET-DIM-001 name: dimension_mismatch severity: critical message: dim(lhs)!=dim(rhs) remediation: fix_unit_or_expr; run check_dim see: I40 2。
• E-MET-CALIB-002 name: calibration_expired severity: major message: RefCond/CMC out-of-date remediation: recalibrate; recompute U = k*u_c see: I40 5。
• E-INT-ARR-003 name: arrival_time_convention_mixed severity: major message: mixed conventions for T_arr remediation: enforce single convention see: enforce_arrival_time_convention。
• E-MOD-PRIOR-004 name: prior_incompatible_bounds severity: major message: prior support outside [lb,ub] remediation: align prior with bounds see: I30 3。
• E-MOD-CONSTR-005 name: constraint_violation_eq severity: major message: C_eq(theta)!=0 remediation: project_to_feasible see: I30 2。
• E-DAT-MISS-006 name: missing_values_detected severity: minor message: m=1 fraction exceeds threshold remediation: impute_or_drop。
• E-DAT-OUTLIER-007 name: outlier_excess severity: major message: |z|>t0 or MAD rule remediation: mask_and_refit see: I50 3。
• E-NUM-ROUND-008 name: catastrophic_cancellation severity: major message: loss of significance remediation: rescale_or_kahan。
• E-NUM-DIVERGE-009 name: solver_divergence severity: major message: no convergence within tol remediation: adjust_step_or_precond。
• E-OPS-TIMEOUT-010 name: rpc_timeout severity: minor message: downstream exceeded SLA remediation: retry(policy)。
• E-OPS-VERSION-011 name: scenario_incompatible severity: major message: scenario diff incompatible remediation: migrate_or_pin see: diff_scenarios。
• E-INT-UNIT-012 name: unit_policy_mismatch severity: major message: convert() policy conflict remediation: bind_to_equation(unit_policy)。

VIII. Example: Arrival-Time Error Naming Consistency

1. If a path integral mixes the two conventions or omits path and measure, trigger:
   • E-INT-ARR-003 (mixed conventions);
   • E-MET-DIM-001 (dimensional check failed, e.g., when ( n_eff / c_ref ) * d ell is not rendered dimensionless).
2. Residual convention: for arrival-time observation y = T_arr_meas and model f(x; theta), define r def= y - f(x; theta); units and dimensions must match. A failed check_dim( y - f(x; theta) ) is critical.

IX. Compatibility and Version Governance

• Version breakpoints are denoted with @vMAJOR and are raised only when semantics or trigger conditions change incompatibly; minor text edits or fixes do not change code.
• Scenario integration: upon create_scenario / activate_scenario, error policies are loaded via set_error_policy from the scenario-specific profile; regression uses compare_reports(..., ["mean","U","pass_rate"]) to monitor quality slippage.

X. Chapter Summary and Outputs

• Outputs: error-domain lexicon; severity–action matrix; postulates P71-1…P71-3; coding syntax E-<DOMAIN>-<CLASS>-<NNN>; workflow M71-1; canonical registration list.
• Next steps: before proceeding, bulk-register your project’s error catalog via register_error_code, and wire compute_residual, loss_rho, psi_weight, and zscore_detect / hampel_filter into your fitting and evaluation flows.