33-EFT.WP.Cosmo.EarlyObjects v1.0 | Chapter 10 — Implementation Bindings & API Specification

Chapter 10 — Implementation Bindings & API Specification

I. One-Sentence Goal

Bind the physical formalism of this volume—Catalog / Seeds / Trajectory, Phi_T / grad_Phi_T, L_nu / LC, n_eff, segmentation and Delta_T_sigma, and the two arrival-time forms T_arr / Delta_T_arr—into a reusable API consistent with the template v0.1 interface family, standardizing I70-* prototypes, data objects, dimension/unit checks, error codes, logging, and reproducibility, so that cross-team implementations are consistent, auditable, and replayable.

II. Scope & Non-Goals

Covered: interface layering and function prototypes (aligned with the template family; concrete I70-* bindings), minimal data structures, dimension/unit and parameter validation, error codes and exception semantics, concurrency & reproducibility, logging & audit, exemplar workflows, and publication norms.
Not covered: re-deriving the equations/numerics of Chs. 3–9; hardware/observatory specifics; substituting the verification and uncertainty processes of Chs. 11–12.

III. Minimal Terms & Symbols

1. Objects & state: Catalog, Seeds, Trajectory; state = { M, R, J, a_bh, SFR, Z, … }.
2. Fields & environment: T_fil(x,t), Phi_T(x,t)=G(T_fil), grad_Phi_T(x,t); SeaProfile / Sigma_env.
3. Propagation & forms: n_eff(x,t,f) (dimensionless, n_eff ≥ 1), c_ref, gamma(ell), d ell, endpoints { ell_i }.
   • Constant pull-out: T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
   • General form: T_arr = ( ∫ ( n_eff / c_ref ) d ell )
4. Energy closure & naming isolation: R_env + T_trans + A_sigma = 1; T_fil ≠ T_trans, n ≠ n_eff.

IV. Interface Layering & Function Prototypes

(aligned to template v0.1; recommended I70-* bindings)

A. Catalog / Causation / Evolution (template: I.Build.*)

• I70-1 build_early_object_catalog(params) -> Catalog
  Produce object inventory, types, z_form / z_obs, environment references, and hashes.
• I70-2 seed_and_trigger(Phi_T, env, priors) -> Seeds
  Sample seed from priors & environment; instantiate trigger process handles (supports inhomogeneous Poisson).
• I70-3 evolve_object_state(O, env, tgrid) -> Trajectory
  Numerically advance S70-7 … S70-10; apply Trigger at event times.

B. Radiation & Propagation (template: I.Build.*, I.Arrival.*)

• I70-4 synthesize_spectrum(O, state, fgrid) -> L_nu
• I70-5 couple_to_sea(O, SeaProfile, params) -> EnvCoupled (optional; hooks to LayeredSea)
• I70-6 predict_arrival_signature(n_eff, gamma, mode, c_ref) -> { T_arr, Delta_T_arr }
  mode ∈ {constant, general}; segmentation & Delta_T_sigma are supplied at entry or assembled in the n_eff layer.

C. Interfaces & Energy (template: I.Interface.*, I.RT.Estimate)

• detect_interfaces(gamma, Sigma_env or SeaProfile) -> { ell_i, labels }
• interface_correction_sea(gamma, SeaProfile, params) -> Delta_T_sigma (thin-layer optional)
• I70-7 estimate_energy_triplet(data, Sigma_env) -> { R_env, T_trans, A_sigma }

D. Metrology / Consistency / Uncertainty (template: I.Consistency.*, I.Uncertainty.*)

• check_dual_arrival_consistency(inputs) -> eta_T
• consistency_thin_vs_thick_EO(inputs) -> tau_report
• propagate_uncertainty_GUM(inputs) -> u_c
• propagate_uncertainty_MC(inputs, Nsamples, seed) -> dist

E. Reporting & Logging (template: I.Report.*)

• emit_measurement_report(contract, logs, artifacts) -> Report
• log_artifacts_EO(meta, hashes, metrics) -> Log

Unified constraints (all entries): dimension checks check_dimension, enforce T_arr ≥ L_path / c_ref and R_env + T_trans + A_sigma = 1, naming isolation (T_fil vs T_trans, n vs n_eff), and explicit inclusion of segment endpoints { ell_i }—no cross-interface interpolation.

V. Data Structures (Minimal Definitions)

• Contract: spec_version, coords_spec, units_spec, metric_spec, mode, tolerances:{eps_T,eta_T,eta_w,tau_switch}, hash(*), SolverCfg, seed.
• Catalog: { id, type, z_form, z_obs, env_ref, seed_ref }, hash(Catalog).
• Seeds / Triggers: priors, samples & seed_rng, trigger events & timestamps, hash(Seeds).
• Trajectory: time series state(t) plus event log, hash(Trajectory).
• Field: name ∈ {Phi_T, grad_Phi_T, n_eff}, storage ∈ {grid, trajectory}, coords_spec / units_spec.
• SeaProfile / Interfaces: layer params, Sigma_env labels, { ell_i } tolerances, hash(SeaProfile).
• Spectral / Obs: L_nu(f), F_nu(f), LC(t), T_arr / Delta_T_arr with uncertainties.
• RTParams: band curves & confidence bands for R_env(f), T_trans(f), A_sigma(f).
• Report / Log: metrics, thresholds, falsification samples, hashes, and environmental metadata.

VI. Parameter Validation & Units / Dimensions

• Bindings: dim(T_arr) = [T], dim(c_ref) = [L][T^-1], dim(d ell) = [L], dim(n_eff) = 1, dim(Delta_T_sigma) = [T]; specify dim(L_nu) and dim(F_nu) in Contract.
• Coordinates / metric: metric_spec is mandatory and must provide the chi → d ell mapping; all entries carry consistent coords_spec / units_spec.
• Clamping: n_eff ∈ [1, n_max]; out-of-range ⇒ reject and record a falsification sample.
• Two forms: record mode and rationale; general form requires a c_ref(x,t,f) model with uncertainty.

VII. Error Codes & Exceptions (mapped to the template family)

• E-DIM-001 dimension mismatch or missing units
• E-GAUGE-002 gauge not fixed or conflicting conventions
• E-NEFF-003 n_eff < 1 or assembly failure
• E-PATH-004 invalid path discretization or measure mismatch
• E-INTF-005 interface matching failure or parameter out of bounds
• E-QAD-006 quadrature non-convergence or unmet eps_T
• E-CREF-007 c_ref calibration unsolved/unstable
• E-CONSIST-008 two-form consistency failure (eta_T over gate)
• E-EO-010 thin/thick consistency failure or Delta_T_sigma vs volume integral mismatch beyond gate

Handling: return error objects that preserve intermediate logs and RNG seed; output falsification samples and back-trace guidance (form choice, segmentation, SeaProfile, step size).

VIII. Concurrency, Determinism & Reproducibility

• Determinism: keep core pipeline pure-function where possible; for MC, log seed, sampling policy, and hashes.
• Concurrency: parallelize across object × band × path; evaluate local layer windows concurrently; avoid mutable shared state.
• Reproducibility: record hash(Catalog / Seeds / Trajectory / SeaProfile / Phi_T / n_eff / gamma / code) at entry; reports carry SolverCfg and metric_spec snapshots.

IX. Logging & Audit (minimal fields)

• Runtime: timestamp, platform, library versions, spec_version, SolverCfg.
• Physics & geometry: hash(Catalog / Seeds / Trajectory / SeaProfile / Phi_T / n_eff / gamma), Sigma_env labels and { ell_i } tolerances.
• Forms & thresholds: mode, eps_T, eta_T, eta_c, eta_w, tau_switch, lower-bound margin T_arr − L_path / c_ref.
• Energy & differential: R_env / T_trans / A_sigma residuals, Delta_T_sigma trigger stats, Delta_T_arr linear-regime diagnostics and OOB leakage ratio.
• Uncertainty & replay: u_stat, u_sys, u_c, k, seed, coords_spec / units_spec / metric_spec, hash manifests, falsification list.

X. Example Workflows (aligned with the template family)

A. Catalog → Causation → Evolution → Spectrum → Propagation (end-to-end)

• Catalog = build_early_object_catalog(params)
• Seeds = seed_and_trigger(Phi_T, env, priors)
• Trajectory = evolve_object_state(O, env, tgrid)
• L_nu = synthesize_spectrum(O, state, fgrid)
• T_arr, Delta_T_arr = predict_arrival_signature(n_eff, gamma, mode, c_ref)
• emit_measurement_report(…) (includes eta_T, tau_switch, energy closure and lower-bound audits)

B. Interfaces & Energy Closure

• ell_i = detect_interfaces(gamma, Sigma_env or SeaProfile)
• T_arr = segment_integrals(n_eff, gamma, { ell_i }, mode) [+ Delta_T_sigma]
• { R_env, T_trans, A_sigma } = estimate_energy_triplet(data, Sigma_env)
• log_artifacts_EO(…)

C. Uncertainty & Consistency

• u_c = propagate_uncertainty_GUM(inputs) / dist = propagate_uncertainty_MC(inputs, Nsamples, seed)
• eta_T = check_dual_arrival_consistency(inputs)
• tau_report = consistency_thin_vs_thick_EO(inputs)

XI. Cross-References

• EFT.WP.Cosmo.EarlyObjects v1.0: Ch. 3 (minimal equations), Ch. 4 (seed/trigger), Ch. 5 (coupling & growth), Ch. 6 (radiation & propagation), Ch. 7 (metrology), Ch. 9 (numerical implementation), Ch. 11 (verification), Ch. 12 (uncertainty budget).
• Template v0.1: interface family and I/O contract layering.
• EFT.WP.Cosmo.LayeredSea v1.0: segmentation, matching, consistency.
• EFT.WP.Propagation.TensionPotential v1.0: two-form, differential, path rules.
• EFT.WP.Core.*: Equations / Metrology / Errors.

XII. Deliverables

• API reference inventory: I70-* prototypes, inputs/outputs, units & dimensions, error semantics (aligned with template v0.1).
• Contract templates: field norms for Contract / Catalog / Seeds / Trajectory / Field / SeaProfile / RTParams / Report.
• Audit & reproducibility packs: logs, hashes, and replay manifests for workflows A/B/C.