33-EFT.WP.Cosmo.EarlyObjects v1.0 | Appendix D — Reference Implementation & Test Script Inventory

Appendix D — Reference Implementation & Test Script Inventory

I. One-line Aim

Provide a minimal, template-aligned (v0.1) reference implementation and a concrete list of test scripts—covering directory layout, entrypoints, configuration, execution, and audit rules—so that end-to-end flows for Catalog/Seeds/Trajectory, Phi_T/grad_Phi_T, L_nu/LC, n_eff, { ell_i }, Delta_T_sigma, {R_env,T_trans,A_sigma}, and both arrival-time forms T_arr/Delta_T_arr are deployable, reproducible, and auditable.

II. Scope & Non-Goals

III. Directory Layout (recommended)

ref_eo/ # reference implementation root

core/ # physics & numerics core

catalog.py # I.Build.Catalog → build_early_object_catalog

seed.py # I.Build.Seeds|Triggers → seed_and_trigger

evolve.py # I.Build.* → evolve_object_state

sed.py # spectra/fields → synthesize_spectrum

transport.py # I.Arrival.Constant|General|Delta → predict_arrival_signature

interfaces.py # I.Interface.ApplyMatching|I.Path.Segment|I.Path.InterfaceCorrection

rt.py # I.RT.Estimate → estimate_energy_triplet

metrics.py # I.Consistency.*, I.Uncertainty.* (eta_T, tau_switch, GUM/MC)

io/

contract.py # Contract I/O + validation + DimReport

dataio.py # read/write Catalog/Seeds/Trajectory/SeaProfile/Path/Observations

hashing.py # content hashes for Catalog/Seeds/Trajectory/SeaProfile/Phi_T/n_eff/gamma/code

utils/

solvercfg.py # quadrature/step rules/concurrency policies

logger.py # I.Report.Log|Emit → log_artifacts_EO, emit_measurement_report

rng.py # seeded RNG for MC reproducibility

scripts/ # benchmarks & tests (see §V)

configs/ # runnable configs & samples (see §VII)

artifacts/ # results & audits (logs, reports, hash manifests, replay lists)

Naming isolation (hard-guard): never conflate T_fil with T_trans, nor n with n_eff. Every entry must pass n_eff ≥ 1 and dimensional checks at ingress.

IV. Core Interfaces (Template API Family → this volume I70-*)

Unified constraints (all ingress): run check_dimension; enforce T_arr ≥ L_path / c_ref and R_env + T_trans + A_sigma = 1; include explicit segment endpoints { ell_i }; no cross-interface interpolation.

V. Script Inventory & Purpose (minimal set)

VI. Run Examples (CLI)

Catalog → Seeds → Evolution (basics)

python scripts/run_catalog.py --contract configs/eo.contract.json --out artifacts/catalog/

python scripts/run_seed.py --contract configs/eo.contract.json --priors configs/priors.json --out artifacts/seeds/

python scripts/run_evolve.py --contract configs/eo.contract.json --catalog artifacts/catalog/catalog.json --seeds artifacts/seeds/sd.json --out artifacts/traj/

Spectra → Transport → Consistency

python scripts/run_spectrum.py --contract configs/eo.contract.json --traj artifacts/traj/trajectory.jsonl --fgrid configs/fgrid.json --out artifacts/sed/

python scripts/run_transport.py --contract configs/eo.contract.json --path paths/p001.path.jsonl --phi fields/phi_t.zarr --gphi fields/grad_phi_t.zarr --sea seaprofile/sea.v1.json --out artifacts/transport/

python scripts/run_dual_consistency.py --contract configs/eo.contract.json --path paths/p001.path.jsonl --neff fields/neff.zarr --cref calib/c_ref.json --out artifacts/consistency/

Differential / Thin–Thick / Uncertainty

python scripts/run_dispersion.py --contract configs/eo.contract.json --obs obs/p001.obs.jsonl --fgrid configs/fgrid.json --out artifacts/dispersion/

python scripts/run_thin_vs_thick.py --contract configs/eo.contract.json --path paths/p001.path.jsonl --sea seaprofile/sea.v1.json --out artifacts/switch/

python scripts/run_uncertainty_gum.py --contract configs/eo.contract.json --inputs artifacts/transport/results.json --out artifacts/uncertainty/gum/

python scripts/run_uncertainty_mc.py --contract configs/eo.contract.json --inputs artifacts/transport/results.json --nsamples 20000 --seed 20250905 --out artifacts/uncertainty/mc/

Reporting

python scripts/run_report.py --manifest artifacts/manifest.json --out artifacts/report/

VII. Sample Config (minimal)

configs/eo.contract.json

JSON json
{
  "spec_version": "EFT.WP.Cosmo.EarlyObjects 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" },
  "tolerances": { "eps_T": 1e-09, "eta_T": 5e-10, "eta_w": 0.03, "tau_switch": 5e-12 }
}

configs/priors.json

JSON json
{
  "BHSeed": {
    "M0": { "dist": "lognormal", "mu": 20000.0, "sigma": 0.3 },
    "a_bh0": { "dist": "uniform", "low": 0.1, "high": 0.9 }
  }
}

configs/solver.eo.json

JSON json
{
  "quad": "adaptive_simpson",
  "step_rule": "curvature_medium_layer",
  "tau_geom": 0.02,
  "tau_medium": 0.01,
  "tau_sea": 0.005,
  "convergence": { "levels": [ 1.0, 0.5, 0.25 ], "eps_T": 1e-09 },
  "parallel": { "freq": "threads", "paths": "threads" }
}

configs/fgrid.json

JSON json
{
  "f0": 1000000000.0,
  "band": [ -50000000.0, 50000000.0 ],
  "nodes": [ 950000000.0, 1000000000.0, 1050000000.0 ]
}

VIII. Outputs & Audit (minimum set)

IX. Reproducibility (one-click replay)

python scripts/run_report.py --manifest artifacts/manifest.json --out artifacts/report/

X. Security & Integrity

XI. Template API Family Quick Map (anchored to template v0.1)

XII. Cross-References

XIII. Deliverables