05-EFT.WP.Core.Errors v1.0 | Appendix A — Error Code Registry Schema

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

Appendix A — Error Code Registry Schema

I. Purpose and Scope

• Purpose: define a cross-volume, unified schema for error codes—standardizing code, severity, domain, message, remediation, and trace fields—to support implementation and validation of register_error_code, set_error_policy, and normalize_error.
• Scope: covers online/offline flows of the Metrology and Errors volumes, including T_arr two-form computation, calibration/verification, robust fitting, error propagation, data quality, and streaming pipelines.

II. Naming and Coding Conventions

1. Code structure: code = "E.<DOMAIN>.<GROUP>.<KEY>[.NNN]"
   • <DOMAIN>: top-level domain (e.g., METROLOGY, MEASUREMENT, NUMERICS, DATA_QUALITY, MODEL, PIPELINE, CALIBRATION, REFCOND, REPORT, IO, SECURITY).
   • <GROUP>: second-level grouping (e.g., UNIT, TRACE, INTEGRATION, OUTLIER, FIT, TIME, LINEAR, etc.).
   • <KEY>: specific fault key (UPPER_SNAKE_CASE, semantically stable).
   • Optional suffix .NNN: scenario split under the same key (starting from 001).
2. Regex constraint: ^E\.[A-Z][A-Z0-9_]*\.[A-Z][A-Z0-9_]*\.[A-Z][A-Z0-9_]*(\.[0-9]{3})?$.
3. Global uniqueness: code is unique across the registry; the version for a given code increases monotonically.
4. Semantic stability: the message template may evolve but must not change the root-cause/domain/severity semantics.

III. Field Dictionary and Required Items

1. Required
   • code:str (globally unique; see naming rules)
   • name:str (human-readable short title, English)
   • severity:str ∈ {INFO, WARN, ERROR, FATAL}
   • domain:str (matches <DOMAIN>)
   • message:str (templated with placeholders like {{var}})
   • remediation:str (preferred action, e.g., retry(policy={{pid}}), fallback(model={{mid}}), graceful_degradation(mode={{m}}), recalibrate(proc={{rid}}))
2. Recommended
   • see:list[str] (cross-volume anchors like I50-4, I40-9, S88-1)
   • tags:list[str] (keywords, e.g., ["T_arr","gamma(ell)","n_eff","c_ref"])
   • cause:str (direct cause)
   • effect:str (user impact, incl. SLI/SLO touchpoints)
   • detection:str (criteria, e.g., |z| > 3.5, chi2/dof > t0)
   • context_schema:list[str] (minimal context keys; see §IV)
   • metrics:list[str] (quantitative indicators to log, e.g., ["chi2","r_bar_max","latency_ms","pass_rate"])
   • policy_hint:str (strategy hint, e.g., prefer_robust_loss=Huber)
3. Lifecycle
   • version:str (semantic version, e.g., 1.0.0)
   • status:str ∈ {DRAFT, ACTIVE, DEPRECATED, RETIRED}
   • created_at:str, updated_at:str (ISO8601)
   • deprecates:list[str], replaces:list[str] (compatibility relations)

IV. Minimal Context Keys (Trace & Reproducibility)

• trace_id, span_id (trace linkage)
• inputs_hash (input fingerprint)
• model_id, loss_kind (model and robust-loss settings)
• gamma_spec, L_gamma, path_version (when gamma(ell) is involved)
• c_ref_version, unit_policy (units and reference-constant versions)
• refcond_id (identifier for RefCond)
• h, p_hat (step size and order)
• SLI_snapshot (metrics slice at trigger time)

V. Severity → Recommended Action Mapping

• INFO: observability only; default no-op, may include telemetry_only=true.
• WARN: quality risk but process may continue; default retry(policy={{pid}}) or switch_loss(kind=Huber).
• ERROR: current flow fails but can roll back; default fallback(model={{mid}}) or graceful_degradation(mode=partial).
• FATAL: unrecoverable system or semantic breakage; default abort and raise, and trigger recalibrate(proc={{rid}}).

VI. Normalization and Validation Rules

• Template completeness: every {{var}} in message must be supplied by the context with the same key.
• Text policy: message and name are English plain text; do not embed undeclared unit conversions or symbols.
• Dimensional consistency: if message contains a dimensional expression, it must pass check_dim (e.g., y - f(x; theta)).
• Association consistency: domain must match <DOMAIN> in code; severity must not conflict with policy_hint.
• Compatibility: ACTIVE→DEPRECATED allows only remediation strengthening; code/domain/severity must remain unchanged.

VII. Reference JSON Schema (Outline)

1. type: object
2. required: [ "code","name","severity","domain","message","remediation" ]
3. properties:
   • code: string, pattern ^E\.[A-Z][A-Z0-9_]*\.[A-Z][A-Z0-9_]*\.[A-Z][A-Z0-9_]*(\.[0-9]{3})?$
   • severity: string, enum [ "INFO","WARN","ERROR","FATAL" ]
   • domain: string
   • name: string
   • message: string
   • remediation: string
   • see: array(string)
   • tags: array(string)
   • cause: string
   • effect: string
   • detection: string
   • context_schema: array(string)
   • metrics: array(string)
   • policy_hint: string
   • version: string
   • status: string, enum [ "DRAFT","ACTIVE","DEPRECATED","RETIRED" ]
   • created_at: string (date-time)
   • updated_at: string (date-time)
   • deprecates: array(string)
   • replaces: array(string)

VIII. Implementation Bindings (I50- Correspondence)**

• register_error_code: validate against this schema and persist, returning ERef; reject duplicate code.
• set_error_policy: publish default severity→action mappings per domain, allowing per-code overrides.
• normalize_error: fold native exceptions/events into { code, message(fmt), context, severity }, and fill trace_id, span_id, inputs_hash.

IX. Example Entries (Cross-Domain Minimal Set)

• code=E.METROLOGY.UNIT.DIM_MISMATCH; name=Dimension mismatch; severity=ERROR; domain=METROLOGY; message=Expected dim(lhs)==dim(rhs) but got {{lhs}} vs {{rhs}}; remediation=abort and fix unit policy; see=["I40-2","S88-1"]; tags=["check_dim"].
• code=E.MEASUREMENT.TRACE.MISSING_CHAIN; name=Traceability chain missing; severity=ERROR; domain=MEASUREMENT; message=Missing traceability_chain for {{code}}; remediation=attach_traceability(report={{rid}},chain={{cid}}); see=["I40-4","I50-6"].
• code=E.REFCOND.OUT_OF_RANGE; name=RefCond out of range; severity=WARN; domain=REFCOND; message=RefCond deviates: p={{p}},Temp={{Temp}},humidity={{humidity}}; remediation=apply corr_env and elevate u_env; see=["I40-3"]; tags=["RefCond","corr_env"].
• code=E.NUMERICS.INTEGRATION.STEP_TOO_LARGE; name=Integration step too large; severity=WARN; domain=NUMERICS; message=h={{h}} exceeds bound; order={{order}}; remediation=retry(policy=refine_step); see=["I50-5"]; metrics=["h","p_hat"].
• code=E.NUMERICS.ROUNDING.CANCELLATION; name=Catastrophic cancellation; severity=ERROR; domain=NUMERICS; message=High cancellation risk; u_round={{u_round}}; remediation=fallback(model=KahanSum); see=["I50-5"].
• code=E.DATA_QUALITY.OUTLIER.DETECTED; name=Outlier detected; severity=WARN; domain=DATA_QUALITY; message=Outliers ratio={{ratio}} via {{method}}; remediation=mask and refit; see=["I50-3","I50-2"]; tags=["zscore","Hampel","RANSAC"].
• code=E.MODEL.FIT.NON_CONVERGENCE; name=Fit not converged; severity=ERROR; domain=MODEL; message=Solver failed; iter={{iter}}, tol={{tol}}; remediation=switch loss to Huber and retry; see=["I50-2"]; metrics=["chi2","r_bar_max"].
• code=E.PIPELINE.TIMEOUT.P95_EXCEEDED; name=Latency p95 exceeded; severity=WARN; domain=PIPELINE; message=latency_p95={{p95}}ms > {{limit}}ms; remediation=graceful_degradation(mode=partial); see=["I50-8","M8-3"].
• code=E.CALIBRATION.LINEAR.SLOPE_UNCERT_HIGH; name=Linear slope uncertainty high; severity=WARN; domain=CALIBRATION; message=u(a)={{ua}} exceeds {{limit}}; remediation=increase samples or robust loss; see=["M8-2"].
• code=E.REPORT.GUARD_BAND.MARGINAL; name=Guard band marginal; severity=INFO; domain=REPORT; message=Result within guard band; result={{x}}, U={{U}}, tol={{tol}}; remediation=record and monitor; see=["I40-6"].
• code=E.IO.READ.FAIL; name=I/O read failure; severity=ERROR; domain=IO; message=Failed to read {{uri}}; reason={{reason}}; remediation=retry(policy=io_backoff); tags=["io","retry"].
• code=E.SECURITY.PERM.DENIED; name=Permission denied; severity=FATAL; domain=SECURITY; message=Access denied for {{actor}} to {{resource}}; remediation=abort and escalate; tags=["authz"].
• code=E.T_ARR.CONSISTENCY.DUAL_FORM_MISMATCH; name=T_arr dual-form mismatch; severity=ERROR; domain=MEASUREMENT; message=Two conventions disagree by {{delta}}s; remediation=enforce_arrival_time_convention() and re-run; see=["I40-9","S88-1"]; tags=["T_arr","gamma(ell)","n_eff","c_ref"].

X. Maintenance and Governance

1. Version and status
   • New entries start as DRAFT; switch to ACTIVE after integration and regression pass.
   • When superseded, mark as DEPRECATED pointing to the new code; freeze the old entry allowing only remediation strengthening and see additions.
   • After migration, mark RETIRED; keep read-only for historical report parsing.
2. Change admission
   • Any severity change requires cross-volume review and updates to set_error_policy.
   • When adding message placeholders, extend context_schema and update producers.
   • Regression guard: verify deviations against baselines with compare_reports(a,b, metrics=["mean","U","pass_rate"]).

XI. Quick Pre-Registration Checklist

• code format and uniqueness pass; domain matches <DOMAIN>.
• severity has a default action mapping; remediation parses in the execution engine.
• All {{var}} in message exist in context_schema; placeholder and key casing match.
• If metrology expressions are involved (T_arr, check_dim), sample data pass validation and the two-form equivalence (|delta| ≤ eps_policy).
• see entries resolve to valid anchors in this volume or the companion white paper.

XII. Alignment with Metrology Anchors

• Anchor list: c_ref, gamma(ell), d ell, L_gamma, n_eff(x,t), T_arr.
• Reporting requirement: any error code touching these anchors must carry gamma_spec, L_gamma, c_ref_version, refcond_id, and include the corresponding anchor names in tags.

XIII. Deliverables and Operationalization

1. Deliverables
   • Standard schema files (export as both YAML and JSON), published via the same pipeline as export_units("yaml") and export_refcond("yaml").
   • An example library (≥ 20 entries to be extended during implementation), delivered with the default set_error_policy bundle.
2. Landing steps
   • Bulk-register core entries using this schema (prioritize METROLOGY, MEASUREMENT, NUMERICS, DATA_QUALITY).
   • Enable normalize_error in the integrated environment to unify log and report formats.
   • Link error codes to SLI/SLO gates to trigger automated chains of retry / fallback / graceful_degradation.