12-EFT.WP.Methods.Repro v1.0 | Chapter 2 Terminology, Boundaries, and Object Model

Home ／ Docs-Technical WhitePaper ／ 12-EFT.WP.Methods.Repro v1.0

Chapter 2 Terminology, Boundaries, and Object Model

I. Scope and Objectives

1. This chapter unifies the terminology used throughout the volume, establishes a four-layer object model — Env / Data / Algo / Metrics — and specifies the interfaces and minimal manifests at the boundaries between layers.
2. Objectives
   • Define reproducibility-related core quantities and collision names to ensure cross-volume gauge consistency.
   • Use the object model to clarify inputs/outputs, immutability, and traceability, and to list the minimal field set.
   • Specify inter-layer contracts and compliance gates that support automated validation and publication via gate.rep.

II. Terms and Symbols

1. Reproducibility tiers and levels
   • reproducible: same site, same EnvLock, same seed; outputs satisfy the delta_rep gate.
   • replicable: cross-site or with small environmental deltas; satisfy statistical and spectral consistency gates.
   • portable: across hardware/OS/accelerators; interfaces remain stable and thresholds unchanged.
2. Objects and identifiers
   • EnvLock: frozen environment snapshot (OS, kernel, driver, accel, libs, compiler, etc.).
   • PipelineCard: pipeline card describing the execution graph, versions, and dependencies.
   • ParamCard: parameter card describing tunables and constraints (units, dimensions, domains).
   • oid = hash(bytes(obj)): object identifier; fingerprint aggregates code + parameters + environment.
   • Result-hash composite: fp = hash( bytes(code) || bytes(params) || bytes(env) ).
3. Time base and randomness
   • tau_mono internal monotonic time; ts published time; mapping ts = alpha + beta * tau_mono.
   • seed random seed; rng_family, rng_device identify RNG family and device source.
4. Reproducibility metrics and gates
   • delta_rep = ( norm( y_new - y_ref ) / max( norm( y_ref ), eps_floor ) )
   • R_coef = 1 - delta_rep; eps_floor > 0.
   • Spectral consistency: var( x ) ≈ ( ∫ S_xx(f) df ) with window energy U_w and ENBW reported.
   • Gate set gate.rep = { tau_rep, tau_psd, tau_tb, ... }.
5. Path and arrival time (cross-volume constraint)
   • Path and measure: gamma(ell), d ell.
   • Dual-gauge in parallel: T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell ) and T_arr = ( ∫ ( n_eff / c_ref ) d ell ); discrepancy delta_form must be reported.
6. Collision mandate
   T_fil denotes tension only; T_trans denotes transmission coefficient only. Do not mix n and n_eff.

III. Postulates and Minimal Equations

• P31-1 Deterministic replay postulate
  With fixed EnvLock and seed, the same pipeline on the same inputs yields identically distributed outputs; in fully deterministic cases, hash(outputs) is equal.
• P31-2 Interface invariance postulate
  Inter-layer interface signatures are semantically stable; version upgrades must keep input/output sets and dimensions unchanged or provide explicit migrations.
• P31-3 Immutability and traceability postulate
  Ingested objects are content-addressed oid = hash(bytes(obj)); any modification generates a new oid and new fingerprint.
• S32-1 Result delta and reproducibility coefficient
  delta_rep = ( norm( y_new - y_ref ) / max( norm( y_ref ), eps_floor ) ), R_coef = 1 - delta_rep.
• S32-2 Time-base mapping
  ts = alpha + beta * tau_mono; alpha, beta are obtained by calibration and remain stable within a window.
• S32-3 Fingerprint composition
  fp = hash( bytes(code) || bytes(params) || bytes(env) || bytes(inputs.meta) ), used for rapid equivalence checks and audits.

IV. Data and Manifest Gauges

1. Minimal fields (cross-layer common)
   • Identifiers: project_id, dataset_id, schema.version, submit_ts, oid, fingerprint
   • Time base: alpha, beta, tau_mono_origin, ts_origin
   • Randomness: seed, rng_family, rng_device
   • Window: window = [t0, t1], fs, window_fn, U_w, ENBW
   • Path: when path integrals are involved, provide gamma(ell) parameterization & support, and the measure d ell
   • Metrics: delta_rep, R_coef, tau_rep, tau_psd, pass (bool)
2. Units and dimensions
   Run check_dim(expr) before publication; declare units for all fields. Dimensionless fields include delta_rep, R_coef, alpha, beta.
3. Cross-volume field mapping and gauge inheritance
   • With Core.DataSpec: prefer prefix DS.*; include schema.version and evolution strategy.
   • With Core.Threads: runtime observations use TS.* metrics (hb, bp, makespan, etc.).
   • With Core.Metrology: spectral gauge fields MET.psd.* with windowing, leakage, and calibration factors.
   • Arrival time and medium fields inherit from Core.Sea and Core.Density: c_ref, n_eff, path gamma(ell).

V. Algorithms and Implementation Bindings

1. Object-layer interfaces (contract highlights)
   • Env → Algo
     1. Input: EnvLock
     2. Contract: declare the determinism domain and list nondeterministic operators; expose rng_family and accelerator backends.
   • Algo → Data
     1. Input: PipelineCard, ParamCard, inputs
     2. Contract: pure-function assumption holds under EnvLock; outputs are content-addressed by oid.
   • Data → Metrics
     1. Input: data manifest and window gauges
     2. Contract: PSD and statistics must report U_w, ENBW, and any bias-correction gauges.
   • Metrics → Gate
     1. Input: delta_rep, R_coef, spectral indicators
     2. Contract: make a boolean decision for gate.rep and emit audit entries.
2. Reference prototypes (as in Appendix B)
   • I30-1 freeze_environment(config:dict) -> EnvLock
   • I30-2 emit_pipeline_card(state:any) -> dict
   • I30-3 run_benchmark_suite(card:dict) -> BenchReport
   • I30-4 verify_reproduction(golden:any, candidate:any, metrics:dict) -> RepReport
   • I30-6 align_timebase(trace:any, reference:any) -> {alpha:float, beta:float, fit:dict}
3. Idempotency and exceptions
   • Idempotency: repeated calls must yield the same oid or explicit no-ops.
   • Exceptions: E_ENV_DRIFT, E_DATA_MISMATCH, E_TIMEBASE_SKEW, E_NONDETERMINISM, E_SEED_INVALID, E_SCHEMA_MISMATCH.

VI. Metrology Workflow and Run Graph

1. Mx-31 Environment freeze & registry
   • Capture hardware/OS/driver/library versions to build EnvLock.
   • Record rng_family, seed policy, and accelerator backend.
2. Mx-32 Interface and gauge checks
   • Validate units and dimensions in PipelineCard and ParamCard.
   • When path integrals are present, register gamma(ell) and d ell.
3. Mx-33 Time-base & spectral calibration
   • Align alpha, beta; verify ts = alpha + beta * tau_mono.
   • Apply Core.Metrology windowing and leakage corrections for spectral gauges.
4. Mx-34 Repro gate evaluation
   • Compute delta_rep, R_coef, and spectral consistency.
   • Produce RepReport and append it to the audit trail.

VII. Verification and Test Matrix

1. Minimum required
   • Interface stability: after version transitions, PipelineCard and ParamCard semantics remain unchanged.
   • Deterministic regression: with fixed EnvLock and seed, expect delta_rep = 0 (deterministic pipelines).
   • Spectral consistency: | var(x) - ( ∫ S_xx(f) df ) | <= tau_psd.
2. Boundary and extreme cases
   • Floating-point precision switches (float32 ↔ float64).
   • Thread reduction ordering and GPU backend changes.
   • Sampling drift, packet loss, and window mismatch.
3. Pass gates and confidence
   tau_rep, tau_psd, tau_tb are project-level configurations; statistical power and significance per Core.Errors.

VIII. Cross-References and Dependencies

• Core.DataSpec: manifest & schema evolution; content-addressing norms.
• Core.Threads: TS.* metrics, hb, bp, throttling, and fallback.
• Core.Metrology: S_xx(f), U_w, ENBW measurement and bias correction.
• Core.Sea, Core.Density: time bases, media and reference speed c_ref; path gamma(ell) and measure d ell.
• Core.Equations, Core.DrawingKinetics: when T_arr is involved, dual-gauge publication and delta_form reporting.

IX. Risks, Limits, and Open Questions

• Sources of nondeterminism (thread scheduling, GPU kernels, atomic order) are hard to eliminate; rely on statistical gates and explicit manifest flags.
• The fingerprint fp cannot prove semantic equivalence; it only signals high-probability consistency. delta_rep and spectral gates remain authoritative.
• Long-term environment drift (microcode, compilers) may undermine EnvLock rebuildability; maintain LTS binaries and rebuild playbooks.
• Open questions: cross-accelerator numerical equivalence, and mixed-precision budgeting within gate.rep.

X. Deliverables and Versioning

1. Outputs
   • This chapter’s terminology and object-model specification.
   • Inter-layer interface spec and minimal field checklist.
   • Validation scripts and gate configuration samples (for gate.rep).
2. Version policy
   • Semantic versioning for interfaces and manifests; any breaking change must ship a migration playbook.
   • Dual-run comparison: run pre- and post-upgrade in parallel, compute delta_rep, R_coef, and spectral deltas; rollback on failure.
   • Audit trail: for every release, record fingerprint, oid, thresholds, and decision logs.