06-EFT.WP.Core.DataSpec v1.0 | Appendix B — Contract Test Templates and Examples

Home ／ Docs-Technical WhitePaper ／ 06-EFT.WP.Core.DataSpec v1.0

Appendix B — Contract Test Templates and Examples

I. Purpose and Scope

• Provide standard, copy-ready examples for assert_contract(ds; tests) that cover uniqueness, non-null checks, ranges, regex, enum membership, cross-field relations, monotonicity, dimensional checks, dual-form consistency, completeness gates, and drift thresholds.
• Reuse this volume’s symbols and the cross-volume anchors uniformly: gamma(ell), d ell, T_arr, n_eff(x,t), c_ref, check_dim(expr), Trace, hash_sha256, signature, etc.

II. TestSpec Structure (aligned with ConstraintSpec)

1. Minimum required fields:
   • kind : str ∈ {"unique","not_null","range","regex","enum_set","cross_field","referential","monotonic","dim_check","arrivaltime_dualform","custom"}
   • expr : str (the constraint expression)
   • params : dict (optional)
   • severity : str ∈ {"ERROR","WARN","INFO"}
   • message : str
   • see : list[str] (optional cross-volume references to S/P/M/I)
2. Return contract (summary):
   • summary = { passed:int, failed:int, severity_max:str, metrics:dict }
   • violations = [ { kind, expr, sample:dict, msg } ]

III. General Contract Template Library (reusable snippets)

# U1 Primary key uniqueness

- kind: "unique"

expr: "unique(<k1>,<k2>,...)"

severity: "ERROR"

message: "primary key must be unique"

# N1 Not-null

- kind: "not_null"

expr: "not_null(<field>)"

severity: "ERROR"

message: "<field> must be not null"

# R1 Numeric range

- kind: "range"

expr: "<field> in [min,max]"

params: { min: <min>, max: <max> }

severity: "ERROR"

message: "<field> out of range"

# G1 Regex match

- kind: "regex"

expr: "match(<field>, <pattern>)"

params: { pattern: "^EPSG:[0-9]+$" }

severity: "ERROR"

message: "<field> regex mismatch"

# E1 Enum membership

- kind: "enum_set"

expr: "<field> in {<v1>,<v2>,...}"

severity: "ERROR"

message: "<field> not in enum set"

# C1 Cross-field relation

- kind: "cross_field"

expr: "<f_right> >= <f_left>"

severity: "ERROR"

message: "cross-field inequality violated"

# M1 Monotonicity (within group)

- kind: "monotonic"

expr: "groupby(<key>).monotonic(<field>, mode='nondecreasing')"

severity: "ERROR"

message: "<field> must be nondecreasing within group <key>"

# D1 Dimensional check

- kind: "dim_check"

expr: "check_dim(<field>)=='<DIM>'"

severity: "ERROR"

message: "dimension of <field> must be <DIM>"

# Q1 Completeness threshold (custom gate)

- kind: "custom"

expr: "quality_metrics(ds).completeness >= p_min"

params: { p_min: 0.98 }

severity: "ERROR"

message: "dataset completeness below threshold"

# H1 Fingerprint and signature presence

- kind: "regex"

expr: "match(hash_sha256, '^[a-f0-9]{64}$')"

severity: "ERROR"

message: "invalid sha256 checksum format"

# F1 Foreign key / reference check

- kind: "referential"

expr: "exists_in(parameters, c_ref_ref)"

severity: "ERROR"

message: "c_ref_ref not resolvable in Core.Parameters"

# K1 Drift gate (custom)

- kind: "custom"

expr: "monitor_drift(ds_ref, ds_new, ['<field1>','<field2>'], method='KL').score <= d_max"

params: { d_max: 0.02 }

severity: "WARN"

message: "drift exceeds recommended band"

IV. Arrival-Time Dual-Form Templates

• Physical definitions (text):
  T_arr_const = ( 1 / c_ref_value ) * ( ∫_gamma n_eff d ell )
  T_arr_integrand = ( ∫_gamma ( n_eff / c_ref_value ) d ell )
  delta_form = | T_arr_const - T_arr_integrand |
• Contract templates

# A1 Dual-form consistency

- kind: "arrivaltime_dualform"

expr: "delta_form <= tol_Tarr"

params: { tol_Tarr: "1e-9 s" }

severity: "WARN"

message: "dual-form gap exceeds tolerance"

# A2 Dimensional closure

- kind: "dim_check"

expr: "check_dim(T_arr_const)=='T'"

severity: "ERROR"

message: "dim(T_arr_const) must be T"

- kind: "dim_check"

expr: "check_dim(T_arr_integrand)=='T'"

severity: "ERROR"

message: "dim(T_arr_integrand) must be T"

V. DS.TARR.PathIntegral v1 Contract Example (complete list)

# Primary keys and basics

- { kind: "unique", expr: "unique(pid, seg_id)", severity: "ERROR", message: "pk (pid,seg_id) must be unique" }

- { kind: "not_null", expr: "not_null(pid)", severity: "ERROR", message: "pid required" }

- { kind: "not_null", expr: "not_null(seg_id)", severity: "ERROR", message: "seg_id required" }

- { kind: "not_null", expr: "not_null(ts)", severity: "ERROR", message: "ts required" }

- { kind: "regex", expr: "match(CRS, '^EPSG:[0-9]+$')", severity: "ERROR", message: "CRS must be EPSG code" }

# Time series and path

- { kind: "monotonic", expr: "groupby(pid).monotonic(ts, mode='nondecreasing')", severity: "ERROR", message: "ts must be nondecreasing per pid" }

- { kind: "cross_field", expr: "ell_end >= ell_start", severity: "ERROR", message: "ell_end must be >= ell_start" }

# Physical ranges

- { kind: "range", expr: "c_ref_value in (0, +inf)", params: { min: 0.0, max: null }, severity: "ERROR", message: "c_ref_value must be > 0" }

- { kind: "range", expr: "n_eff_mean in [1.0, 3.5]", params: { min: 1.0, max: 3.5 }, severity: "WARN", message: "n_eff_mean out of typical bounds" }

# Dual-form and dimensions

- { kind: "dim_check", expr: "check_dim(T_arr_const)=='T'", severity: "ERROR", message: "dim(T_arr_const)=T" }

- { kind: "dim_check", expr: "check_dim(T_arr_integrand)=='T'", severity: "ERROR", message: "dim(T_arr_integrand)=T" }

- { kind: "arrivaltime_dualform", expr: "delta_form <= tol_Tarr", params: { tol_Tarr: "1e-9 s" }, severity: "WARN", message: "dual-form mismatch" }

# Provenance and references

- { kind: "regex", expr: "match(hash_sha256, '^[a-f0-9]{64}$')", severity: "ERROR", message: "invalid sha256" }

- { kind: "referential", expr: "exists_in(parameters, c_ref_ref)", severity: "ERROR", message: "c_ref_ref unresolved" }

# Quality gates

- { kind: "custom", expr: "quality_metrics(ds).completeness >= p_min", params: { p_min: 0.98 }, severity: "ERROR", message: "completeness below 0.98" }

- { kind: "custom", expr: "quality_metrics(ds).validity >= v_min", params: { v_min: 0.99 }, severity: "ERROR", message: "validity below 0.99" }

- { kind: "custom", expr: "monitor_drift(ds_ref, ds_new, ['n_eff_mean'], method='KL').score <= d_max", params: { d_max: 0.02 }, severity: "WARN", message: "n_eff_mean drift high" }

VI. Cross-Volume Binding Assertions (with Core.Parameters and Core.Equations)

• Parameter binding: bind_to_parameters(ds, ['c_ref_ref']) == True.
• Equation binding: bind_to_equations(ds, ['S610-1','S610-2']) == True.
• Dual-form constraint: see A1; when A1 persists as WARN and delta_form shows systematic bias, revisit the n_eff(x,t) modeling and c_ref resolution.

VII. Time and Window Rules Templates

# W1 Timestamp falls within manifest-declared window

- kind: "range"

expr: "ts in [manifest.t0, manifest.t1]"

params: { }

severity: "ERROR"

message: "ts out of declared window"

# W2 Resampling policy declaration

- kind: "custom"

expr: "resample_policy in {'mean','sum','median','first','last'} and Delta_t > 0"

severity: "ERROR"

message: "invalid resample policy or Delta_t"

VIII. Privacy and Governance Check Templates

# P1 Retention period (advisory)

- kind: "custom"

expr: "governance.retention_days >= 365"

severity: "INFO"

message: "retention shorter than recommended"

# P2 Classification completeness

- kind: "custom"

expr: "forall(f in fields) -> pii_level(f) in {'none','low','moderate','high'}"

severity: "ERROR"

message: "pii_level missing or invalid"

IX. Example Execution Result (Summary Structure)

summary:

passed: 23

failed: 2

severity_max: "ERROR"

metrics: { completeness: 0.985, validity: 0.996, drift_KL_n_eff_mean: 0.011 }

violations:

- kind: "range"

expr: "n_eff_mean in [1.0, 3.5]"

sample: { pid: "p-007", seg_id: 12, n_eff_mean: 3.62 }

msg: "n_eff_mean out of typical bounds"

- kind: "arrivaltime_dualform"

expr: "delta_form <= tol_Tarr"

sample: { pid: "p-019", delta_form: "1.35e-9 s", tol_Tarr: "1e-9 s" }

msg: "dual-form mismatch"

X. Failure Handling Map (Quality Gates)

• ERROR: block release; cancel freeze_release; emit remediation work item; rollback to prior tag if required.
• WARN: allow release with q_score downgrade; enter observation; treat k consecutive identical WARNs as an ERROR.
• INFO: record in Trace; no impact on release.

XI. Minimal Usable Pack (placeholders—copy then fill)

# Contract Test Pack (skeleton)

- { kind: "unique", expr: "unique(<k...>)", severity: "ERROR", message: "pk unique" }

- { kind: "not_null", expr: "not_null(<f>)", severity: "ERROR", message: "<f> required" }

- { kind: "range", expr: "<f> in [min,max]", params: { min: <m1>, max: <m2> }, severity: "ERROR", message: "range" }

- { kind: "regex", expr: "match(<f>, '<re>')", severity: "ERROR", message: "regex" }

- { kind: "enum_set", expr: "<f> in {<v...>}", severity: "ERROR", message: "enum" }

- { kind: "cross_field", expr: "<f2> >= <f1>", severity: "ERROR", message: "cross" }

- { kind: "monotonic", expr: "groupby(<k>).monotonic(<f>, mode='nondecreasing')", severity: "ERROR", message: "mono" }

- { kind: "dim_check", expr: "check_dim(<f>)=='<DIM>'", severity: "ERROR", message: "dim" }

- { kind: "custom", expr: "quality_metrics(ds).completeness >= <p_min>", params: { p_min: 0.98 }, severity: "ERROR", message: "completeness" }

- { kind: "custom", expr: "monitor_drift(ds_ref, ds_new, ['<f>'], method='KL').score <= <d_max>", params: { d_max: 0.02 }, severity: "WARN", message: "drift" }

XII. Alignment with the Rest of this Volume

• Consistent with Chapter 4: kind/expr/params are exactly the inputs for assert_contract; pre/post execution should emit quality-gate metrics and failure-handling decisions.
• Consistent with Appendix A: templates like arrivaltime_dualform, dim_check, referential apply directly to DS.TARR.PathIntegral, enforcing T_arr_const and T_arr_integrand agreement within tol_Tarr, with dim(T_arr_*) = T.
• Fixed cross-volume citation style: e.g., “see Energy Threads White Paper Chapter 6 §S610…”.