32-EFT.WP.Cosmo.LayeredSea v1.0 | Appendix B — Data Standards & I/O

Home ／ Docs-Technical WhitePaper ／ 32-EFT.WP.Cosmo.LayeredSea v1.0

Appendix B — Data Standards & I/O

I. One-Sentence Objective
Anchor all data for the layered Energy Sea to template v0.1 (EFT Technical White Paper & Tech Memo Template · Complete Checklist v0.1). Define objects, fields and units, serialization and directory layout, I/O contracts and error semantics, so that SeaProfile, W_k / Xi_k, Phi_T / grad_Phi_T, n_eff, { ell_i }, Delta_T_sigma, R_sea / T_trans / A_sigma, and both T_arr / ΔT_arr formulations form a deployable, reproducible, and auditable data flow.

II. Applicability & Non-Goals

• Covers: object model and primary keys; fields and units; serialization and directory layout; input/output contracts; quality checks and consistency tests; alignment with the template interface family; sample snippets and workflow mapping.
• Does not cover: physical/numerical derivations; device-level hardware conventions; private or non-verifiable formats.

III. Global Constraints & Conventions

1. Coordinates/metric/units: coords_spec, metric_spec, and units_spec are mandatory; normalize all inputs to SI on entry. If inputs include km/ms, they must be mapped to m/s and the mapping must be logged.
2. Inline symbols: always wrap inline symbols in backticks — e.g., T_arr, n_eff, c_ref, gamma(ell), Sigma_sea, Delta_T_sigma.
3. Name isolation: T_fil ≠ T_trans; n ≠ n_eff.
4. Dimensions & lower bound: run check_dimension on entry to enforce dim(T_arr)=[T], dim(n_eff)=1, dim(c_ref)=[L][T^-1]. Any output must satisfy T_arr ≥ L_path / c_ref (equivalently embedded in the general formulation).
5. Energy consistency: at every interface event R_sea + T_trans + A_sigma = 1, with in-band curves and residuals.
6. Two formulations (mode ∈ {constant, general}):
   • Constant-factored: T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
   • General: T_arr = ( ∫ ( n_eff / c_ref ) d ell )

IV. Data Objects & Primary Keys (minimum fields)

1. Contract (metrology contract)
   • Required: id, spec_version, coords_spec, units_spec, metric_spec, mode, gauge:{x_ref,t_ref}, boundary_config, tolerances:{eps_T,eta_T,eta_w,tau_switch}
   • Dependencies: n_eff_dependencies (e.g., F(Phi_T, grad_Phi_T, rho, f))
   • Hashes: hash(SeaProfile), hash(Phi_T), hash(grad_Phi_T), hash(n_eff), hash(gamma), hash(code)
2. SeaProfile (layer profile)
   • Required: model_k ∈ {tanh, logistic, spline}, chi_k, Delta_k, sigma_k (if applicable), eta_w
   • Optional: angular coefficients a_{lm}^{(k)}, bandlimit L
   • Derived: implicit-surface/grid approximation of Sigma_sea, hash(SeaProfile)
3. Path
   • Required: path_id, gamma:[…] (coordinate points), Δell:[…] (line elements, equal length spacing), optional t_hat:[…]
   • Interfaces: interface_marks:[idx…] (discrete indices or interpolation locations aligned to { ell_i })
4. Field
   • Required: name ∈ {Phi_T, grad_Phi_T, n_eff}, storage ∈ {grid, trajectory}, coords_spec, units_spec
   • Grid: grid_axes:{x:[],y:[],z:[]}; Trajectory: samples:{path_id:[…]}
5. NeffParams
   Required: a0,a1,a2; Optional: u0_k,u1_k,b1,b1_n,c_m:{m:coef}, n_min=1, n_max
6. RTParams
   Required: sampled/interpolated models and clamps for R_sea(f), T_trans(f), A_sigma(f)
7. Interfaces (Sigma_sea)
   • Required: sigma_id, type ∈ {continuous, jump_phi, jump_flux, anisotropic}, location (coordinates or implicit-function parameters)
   • Optional: C_sigma, J_sigma, event-level R_sea,T_trans,A_sigma
8. Observations
   • Required: obs_id, path_id, f_hz, T_arr_obs_s, u_stat_s, u_sys_s, timestamp (ISO-8601, UTC)
   • Optional: env_block (temperature/humidity, timebase, etc.)
9. CalibCref
   Required: gamma_ref_id, T_arr_ref_s, n_eff_ref_hash, c_ref_est, u_stat, u_sys, env_block
10. Report/Log
    Required: run_id, contract_id, hashes, metrics:{eps_T,eta_T,eta_c,eta_w,tau_switch,GB,u_c}, notes

V. Serialization & Directory Layout

1. Formats: use JSONL/Parquet for static data; Zarr/NetCDF for large grid fields (field names must still follow this spec).
2. Suggested layout
   • /contracts/ : *.contract.json
   • /seaprofile/ : *.sea.json
   • /paths/ : *.path.jsonl
   • /fields/ : phi_t.*, grad_phi_t.*, neff.*
   • /interfaces/ : sigma_sea.*
   • /obs/ : *.obs.jsonl
   • /calib/ : c_ref.*
   • /rtparams/ : rt.*
   • /artifacts/ : reports, logs, hash manifests, and replay scripts
3. File naming: <object>-<id>-<hash8>.<ext>, where <hash8> is the first 8 chars of a content hash.

VI. Field & Unit Conventions (key fields)

• f_hz: Hz = s^-1; T_arr_obs_s: s; Δell: m; c_ref: m·s^-1
• n_eff, n_common, n_path, R_sea, T_trans, A_sigma: dimensionless
• Phi_T may be nondimensionalized; if not, the Contract must declare Phi_ref; grad_Phi_T units are dim(Phi_T)[L^-1]
• Delta_T_sigma, tau_switch: seconds (s)
• Coordinates/metric/units must match the Contract; any cross-system data require explicit mappings and logs.

VII. I/O Contracts (aligned with the template interface family)
Note: This section anchors to the template interface family, not to an implementation. An engineering map “template family → I60-” may be attached in a separate manual.*

1. Arrival-time computation (both formulations)
   • Inputs: Contract, Path, and either n_eff or (Phi_T + grad_Phi_T + NeffParams + SeaProfile), plus c_ref or CalibCref
   • Interfaces: I.Path.Capture, I.Path.Segment, I.Build.Phi, I.Build.Neff, I.Arrival.Constant|General, I.Path.InterfaceCorrection (optional for thin layers)
   • Outputs: T_arr_mod_s, optional Delta_T_sigma_s, eta_T, hashes, Log
2. SeaProfile inversion
   • Inputs: Observations (multi-band / multi-path), Phi_T/grad_Phi_T (or surrogate), Contract
   • Interfaces: I.Fit.Profile, I.RT.Estimate, I.Consistency.DualMode, I.Consistency.ThinThick, I.Report.Emit
   • Outputs: SeaProfile(theta_hat, Cov), RTParams, consistency and falsification register
3. Interface matching & energy consistency
   • Inputs: SeaProfile, Interfaces, Path, Fields, Contract
   • Interfaces: I.Interface.ApplyMatching, I.Path.Segment, I.Path.InterfaceCorrection, I.RT.Estimate, I.Report.Log
   • Outputs: one-sided n_eff^± summary, R_sea/T_trans/A_sigma residual curves, Log

VIII. Data Quality & Consistency Checks (DQC, automated)

• DQC-1 Dimensional checks: check_dimension covers both formulations, piecewise discrete forms, and layer terms (see Appendix A).
• DQC-2 Unit agreement: ensure Δell, gamma, and c_ref share units; if not, map at entry and log.
• DQC-3 Lower bound: enforce T_arr_obs ≥ L_path / c_ref. Edge samples may lie within −k·u_c but must be flagged.
• DQC-4 Two-formulation agreement: when both are applicable, eta_T ≤ threshold.
• DQC-5 Energy consistency: at each interface/band, R_sea + T_trans + A_sigma = 1.
• DQC-6 Thin/thick agreement: tau_switch = | T_arr^{thick} − ( T_arr^{thin} + Delta_T_sigma ) | ≤ limit.
• DQC-7 Differencing consistency: for same-path multi-frequency differencing, reuse the same { gamma[k], Δell[k] } and the same Delta_T_sigma configuration.
• DQC-8 Clamping statistics: log trigger rate and impact for n_eff ∈ [1,n_max].
• DQC-9 Reproducibility: include SolverCfg, random seed, hash(*), and replay commands.

IX. Error Semantics (aligned with the template error family)

• E-DIM-001: dimensional inconsistency or missing units (reject)
• E-GAUGE-002: gauge not fixed or conflicting (request gauge)
• E-NEFF-003: n_eff < 1 or decomposition failure (reject and register a falsification sample)
• E-PATH-004: illegal path discretization or measure mismatch (ask to rebuild {gamma, Δell})
• E-INTF-005: interface matching failure or parameter out of bounds (reject, include Sigma_sea labels)
• E-QAD-006: segment quadrature not converged or eps_T unmet (return local-error details)
• E-CREF-007: c_ref calibration unsolved or unstable (return env_block)
• E-CONSIST-008: two-formulation consistency failure
• E-LS-010: thin/thick consistency failure or Delta_T_sigma vs. volumetrics over threshold

X. JSONL Examples (minimal usable samples)

• Contract (/contracts/ls.contract.json)

{

"id": "ct-ls-001",

"spec_version": "EFT.WP.Cosmo.LayeredSea v1.0",

"coords_spec": "Comoving-Spherical",

"units_spec": {"length":"m","time":"s","speed":"m·s^-1","frequency":"Hz"},

"metric_spec": {"type":"FLRW-like","S_k":"sin","a_ref":1.0},

"mode": "constant",

"gauge": {"x_ref":[0,0,0], "t_ref":"2025-01-01T00:00:00Z"},

"boundary_config": {"type":"Dirichlet","Phi_T_far":0},

"tolerances": {"eps_T":1e-9,"eta_T":5e-10,"eta_w":0.03,"tau_switch":5e-12},

"n_eff_dependencies": "F(Phi_T, grad_Phi_T, rho, f)",

"hashes": {"hash(SeaProfile)":"aa22bb33","hash(Phi_T)":"ab12cd34","hash(grad_Phi_T)":"de98fa76","hash(gamma)":"ef56ab78","hash(code)":"aa11bb22"}

}

• SeaProfile (/seaprofile/layered.v1.sea.json)

{

"layers": [

{"model":"tanh","chi_k":1.2e3,"Delta_k":2.0e2,"sigma_k":1.0e2},

{"model":"spline","chi_k":2.1e3,"Delta_k":3.0e2,"spline_nodes":[[1.95e3,0.05],[2.1e3,0.5],[2.25e3,0.95]]}

],

"eta_w": 0.03,

"Sigma_sea_meta": {"implicit":"W_k(chi)-0.5=0","grid_hash":"22cc99aa"},

"hash(SeaProfile)": "77cc11dd"

}

• Path (/paths/p001.path.jsonl)

{"path_id":"p001","gamma":[[0,0,1.1e3],[0,0,1.3e3],[0,0,2.3e3]],"Δell":[2.0e2,1.0e3],"t_hat":[[0,0,1],[0,0,1]],"interface_marks":[1]}

• Interfaces (/interfaces/sigma_sea.jsonl)

{"sigma_id":"s001","type":"jump_phi","location":{"implicit":"W_1(chi)-0.5=0"},"C_sigma":0.08,"J_sigma":0.0}

• Observations (/obs/p001.obs.jsonl)

{"obs_id":"o001","path_id":"p001","f_hz":1.0e9,"T_arr_obs_s":6.2001e-3,"u_stat_s":2.0e-6,"u_sys_s":3.0e-6,"timestamp":"2025-01-01T00:00:00Z"}

{"obs_id":"o002","path_id":"p001","f_hz":1.05e9,"T_arr_obs_s":6.2008e-3,"u_stat_s":2.0e-6,"u_sys_s":3.0e-6,"timestamp":"2025-01-01T00:00:01Z"}

• RTParams (/rtparams/rt.p001.json)

{"R_sea":[["9.5e8",0.18],["1.0e9",0.20],["1.05e9",0.19]],"T_trans":[["9.5e8",0.77],["1.0e9",0.76],["1.05e9",0.78]],"A_sigma":[["9.5e8",0.05],["1.0e9",0.04],["1.05e9",0.03]]}

• CalibCref (/calib/c_ref.json)

{"gamma_ref_id":"p_ref","T_arr_ref_s":6.2000e-3,"n_eff_ref_hash":"99aa33bb","c_ref_est":2.99792458e8,"u_stat":5.0e3,"u_sys":1.0e3,"env_block":{"temp_C":20.0,"clock":"UTC"}}

XI. Typical I/O Workflow Mapping (aligned with the template family)
Use the template family as the source of truth; an engineering map “template → I60-” may be attached separately.*

A. Arrival-time computation (constant-factored / general)

• Path acquisition: I.Path.Capture → { gamma[k], Δell[k] }; I.Path.Segment → { ell_i }
• Field & effective-index assembly: I.Build.Phi, I.Build.Neff
• Interface correction (optional for thin layers): I.Path.InterfaceCorrection
• Arrival-time evaluation: I.Arrival.Constant|General
• Recording & audit: I.Report.Log|Emit

B. SeaProfile inversion

• Data arrangement: I.Path.Capture|Segment; I.Build.Phi|Neff
• Inversion: I.Fit.Profile
• Energy triplet: I.RT.Estimate
• Consistency checks: I.Consistency.DualMode|ThinThick
• Report archiving: I.Report.Emit

C. Interface matching & energy consistency

• Matching & one-sided limits: I.Interface.ApplyMatching; I.Build.Neff
• Segmentation & corrections: I.Path.Segment|InterfaceCorrection
• Energy consistency: I.RT.Estimate
• Logging: I.Report.Log

D. Band differencing & path-term isolation

• Decomposition & differencing: I.Arrival.Delta
• Leakage & agreement: I.Consistency.DualMode / I.Report.Log

XII. Data Quality & Audit Checklist (pre-release self-check)

• DimReport present; Δell / c_ref units aligned; explicit metric_spec
• { ell_i } endpoints included explicitly; no cross-interface interpolation
• eta_T, tau_switch, lower-bound margin, and energy-consistency residuals meet targets
• Differencing reuses the exact same path discretization and correction configuration; leakage ratio is logged
• Clamping trigger rates logged; hash(*), SolverCfg, seed, and replay commands are complete

XIII. Security & Integrity

• Read-only mounts: recommend read-only mounts for /contracts, /obs, /interfaces
• Content hashes: use content hashes (excluding filename/timestamp) for cross-environment consistency
• Minimal metadata: logs should record only necessary metrics and hashes to avoid leaking sensitive path information
• Integrity checks: store sha256 and file size for critical objects; verify again before import

XIV. Cross-Volume Alignment (data side)

• With EFT.WP.Propagation.TensionPotential v1.0: fields for the two formulations, Path/Field naming and units align
• With EFT.WP.Core.Metrology v1.0: units_spec, coords_spec, metric_spec, and traceability align
• With EFT.WP.Core.Errors v1.0: naming and reporting conventions for u_stat / u_sys / u_c align
• With EFT.WP.Metrology.PathCorrection v1.0: reuse field keys and semantics for path corrections

XV. Deliverables

• Data-architecture checklist: fields and sample sets for Contract / SeaProfile / Path / Field / NeffParams / RTParams / Interfaces / Observations / CalibCref / Report
• I/O contract specimen: input/output fields, units, requiredness, and error-semantics mapping (per the template family)
• Audit-package template: hash manifest, DimReport, SolverCfg, run logs, and falsification sample register