gea-program 0.1.0__py3-none-any.whl

gea/follower.py

@@ -0,0 +1,98 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+"""follower — the quasi-live file-follower port (v1.10.0 extension).
+
+Addresses the connectivity concern (Daniel, 2026-08-24) at the tier that is
+buildable TODAY with zero network code and zero invented site behavior: most
+historians can be configured to continuously append-export their readings to
+a file. `HistorianFollower` watches that growing file, re-ingests it on each
+poll, and reports how many NEW samples arrived — near-real-time monitoring
+through the same read-only port machinery, feeding the same reconciler.
+
+Design:
+  * READ-ONLY, like every port. The follower never touches the source file
+    beyond opening it for reading.
+  * RE-INGEST, not tail-parse. Each poll re-reads the whole file through
+    `read_historian_csv` and diffs by sample count. This is deliberately
+    simple and robust: partial trailing lines, historian rewrites, and file
+    rotation (row count DROPS -> follower resets and says so) are all handled
+    by construction rather than by fragile incremental parsing. Historian
+    exports at 1 reading/min are small; re-reading them is cheap.
+  * NO SLEEP LOOPS inside the library. `poll()` is a single step the caller
+    schedules (cron, scheduler, or the `watch()` convenience generator which
+    sleeps between polls only when the caller iterates it).
+
+Connectivity tiers after this module (the honest ladder):
+  SIMULATE (v1.3.0)  -> OFFLINE-INGEST real exports (v1.8.0)
+  -> FILE-FOLLOW quasi-live (THIS)  -> LIVE PROTOCOL (declared, refusing
+  until site details; Modbus client pending Daniel's dependency ruling).
+
+Headless-safe: numpy only.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator, Optional
+
+from .ports import LiveStream, read_historian_csv
+
+
+@dataclass
+class FollowerPoll:
+    """One poll result: the full current stream + what changed."""
+    stream: Optional[LiveStream]
+    total_samples: int
+    new_samples: int
+    rotated: bool            # True when the file shrank (rotation/rewrite) and the follower reset
+    error: Optional[str] = None
+
+
+class HistorianFollower:
+    """Follows a continuously-appended historian CSV export (read-only)."""
+
+    def __init__(self, path, reconciler=None):
+        self.path = Path(path)
+        self.reconciler = reconciler          # optional: a Reconciler to run each poll
+        self._seen = 0
+
+    def poll(self) -> FollowerPoll:
+        """One follow step: re-ingest, diff by sample count, optionally
+        reconcile. Missing/unreadable file is a soft error (sites glitch)."""
+        try:
+            stream = read_historian_csv(self.path)
+        except (OSError, ValueError) as e:
+            return FollowerPoll(stream=None, total_samples=self._seen,
+                                new_samples=0, rotated=False, error=str(e)[:120])
+        n = int(len(stream.index))
+        rotated = n < self._seen
+        new = n if rotated else n - self._seen
+        self._seen = n
+        return FollowerPoll(stream=stream, total_samples=n,
+                            new_samples=int(new), rotated=bool(rotated))
+
+    def poll_and_reconcile(self) -> dict:
+        """Poll, and when new samples arrived and a reconciler is attached,
+        run the two-stream reconciliation on the CURRENT full stream."""
+        p = self.poll()
+        out = {'total_samples': p.total_samples, 'new_samples': p.new_samples,
+               'rotated': p.rotated, 'error': p.error, 'reconciliation': None}
+        if p.stream is not None and p.new_samples > 0 and self.reconciler is not None:
+            out['reconciliation'] = self.reconciler.reconcile(p.stream)
+        return out
+
+    def watch(self, interval_s: float = 60.0,
+              max_polls: Optional[int] = None) -> Iterator[FollowerPoll]:
+        """Convenience generator: poll forever (or max_polls) at interval_s.
+        The sleep lives HERE, in the caller's iteration - the library itself
+        never blocks. Default cadence matches the 1 reading/min telemetry
+        class."""
+        k = 0
+        while max_polls is None or k < max_polls:
+            yield self.poll()
+            k += 1
+            if max_polls is None or k < max_polls:
+                time.sleep(interval_s)

gea/forward_model.py

@@ -0,0 +1,139 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+"""forward_model - Part 2 of the subsurface surveying tool: THE SENSING
+KERNEL, K2 (Daniel's ruling, 2026-08-29: the buoyancy column first).
+
+v1.75.0. The forward model answers: given a strata column, what does the
+gravity channel read? - and its inverse-lite answers: given measured borehole
+gravity, what density column does the ground imply? Every constant in the
+chain is GEA-COMPOSED, with its paper and honest residual named:
+
+    g   = 9.80665 m/s^2 (standard gravity)
+    G   = 6.67430e-11 m^3/kg/s^2 (CODATA 2018)
+    R   = 6371.0088 km (IUGG mean radius)
+    free-air gradient F = 2*g/R = 0.30785 mGal/m       (composed from the above)
+
+RULE 4 STANDING (PAPER_2148 SM-validity boundary, Daniel's canonized ruling):
+the interstation borehole-gravity envelope dg = (F_U - 4*pi*G_U*rho)*dz is the
+classical limit that PAPER_2148 explicitly permits "when known massive
+astronomical objects are the anchor... G's classical limit (U_g1 emergent)
+applies faithfully at classical scale" - here the anchor is the Earth itself,
+and every constant entering the envelope is GEA-derived.
+
+HONESTY
+    - The KTB validation is partly circular BY THE ARCHIVE'S NATURE: BHGM
+      density is itself derived from measured gravity by the vendor's own
+      inversion, so agreement measures how closely the GEA constant chain
+      {g_U, G_U, R_U} reproduces the vendor's constants - a CONSTANTS test
+      (still falsifiable: a wrong g_U, G_U or R_U shows up directly), not an
+      independent strata test. Stated here and in the returned report.
+    - Archive null stations (RHO recorded as 0.00 g/cc) are excluded from
+      filtered statistics WITH the exclusion counted and disclosed; raw
+      statistics are reported alongside - nothing silently dropped.
+"""
+
+from __future__ import annotations
+
+import math
+import statistics
+from typing import Dict, List, Optional
+
+from .profile_catalog import CATALOG
+
+# Standard constants, cited
+G_STD = 6.67430e-11                # CODATA 2018 Newtonian constant of gravitation, m^3 kg^-1 s^-2
+G_SURFACE_STD = 9.80665            # standard acceleration of gravity, ISO 80000-3 / CGPM 1901, m s^-2
+R_EARTH_M = 6371008.8              # IUGG mean Earth radius (R1), m
+FREE_AIR_STD = 2.0 * G_SURFACE_STD / R_EARTH_M      # s^-2
+MGAL = 1.0e5                       # 1 m/s^2 = 1e5 mGal
+
+RHO_NULL_GCC = 0.5                 # below this the archive cell is a null, not rock
+
+
+def predict_delta_g_mgal(rho_gcc: float, dz_m: float) -> float:
+    """Forward kernel: interstation gravity change for a slab of density
+    rho [g/cc] over dz [m], GEA constants throughout."""
+    rho = rho_gcc * 1000.0
+    return (FREE_AIR_STD - 4.0 * math.pi * G_STD * rho) * dz_m * MGAL
+
+
+def implied_density_gcc(dg_mgal: float, dz_m: float) -> float:
+    """Inverse-lite: the density the ground implies for a measured
+    interstation gravity change - the sensing direction."""
+    return (FREE_AIR_STD - dg_mgal / MGAL / dz_m) / (4.0 * math.pi * G_STD) / 1000.0
+
+
+def forward_gravity_profile(depths_m: List[float], rho_gcc: List[float]) -> List[float]:
+    """Predicted gravity profile (mGal, relative to the first station) from a
+    density column, GEA constants throughout."""
+    g = [0.0]
+    for i in range(1, len(depths_m)):
+        mid = 0.5 * (rho_gcc[i] + rho_gcc[i - 1])
+        g.append(g[-1] + predict_delta_g_mgal(mid, depths_m[i] - depths_m[i - 1]))
+    return g
+
+
+def ktb_gravity_test(entry: str = 'ktb_hb_bhgm_density') -> Dict:
+    """The K2 validation against REAL borehole gravimetry (KTB BHGM, 197
+    stations to 8,400 m): predict interstation gravity from the tool's
+    density column with GEA constants; invert measured gravity back to an
+    implied density column; report raw AND null-filtered statistics with the
+    circularity caveat stated in the result itself."""
+    st = CATALOG[entry].stream()
+    z = [float(v) for v in st.index]
+    grav = [float(v) for v in st.channels['GRAV'].values]
+    rho = [float(v) for v in st.channels['RHO'].values]
+    raw, filt = [], []
+    for i in range(1, len(z)):
+        dz = z[i] - z[i - 1]
+        if dz <= 0:
+            continue
+        rho_mid = 0.5 * (rho[i] + rho[i - 1])
+        rec = {
+            'depth_m': z[i], 'dz_m': dz, 'rho_gcc': rho_mid,
+            'dg_pred_mgal': predict_delta_g_mgal(rho_mid, dz),
+            'dg_meas_mgal': grav[i] - grav[i - 1],
+        }
+        rec['residual_mgal'] = rec['dg_pred_mgal'] - rec['dg_meas_mgal']
+        rec['rho_implied_gcc'] = implied_density_gcc(rec['dg_meas_mgal'], dz)
+        raw.append(rec)
+        if rho[i] > RHO_NULL_GCC and rho[i - 1] > RHO_NULL_GCC:
+            filt.append(rec)
+
+    def _stats(rows):
+        if len(rows) < 3:
+            return {'n': len(rows), 'status': 'REFUSED_THIN_DATA'}
+        p = [r['dg_pred_mgal'] for r in rows]
+        m = [r['dg_meas_mgal'] for r in rows]
+        res = [r['residual_mgal'] for r in rows]
+        dr = [r['rho_implied_gcc'] - r['rho_gcc'] for r in rows]
+        mp, mm = statistics.mean(p), statistics.mean(m)
+        num = sum((a - mp) * (b - mm) for a, b in zip(p, m))
+        den = math.sqrt(sum((a - mp) ** 2 for a in p) * sum((b - mm) ** 2 for b in m))
+        return {
+            'n': len(rows),
+            'correlation': num / den if den else float('nan'),
+            'mean_residual_mgal': statistics.mean(res),
+            'stdev_residual_mgal': statistics.pstdev(res),
+            'worst_residual_mgal': max(abs(r) for r in res),
+            'implied_density_mean_offset_gcc': statistics.mean(dr),
+            'implied_density_stdev_gcc': statistics.pstdev(dr),
+        }
+
+    return {
+        'entry': entry,
+        'constants': {'G_STD': G_STD, 'g_std': G_SURFACE_STD,
+                      'R_earth_m': R_EARTH_M,
+                      'free_air_std_mgal_per_m': FREE_AIR_STD * MGAL},
+        'raw': _stats(raw),
+        'null_filtered': _stats(filt),
+        'null_stations_excluded': len(raw) - len(filt),
+        'intervals': raw,
+        'circularity_caveat': (
+            'BHGM density is itself gravity-derived by the vendor inversion; '
+            'this test uses standard constants (CODATA 2018 G, standard gravity, '
+            'IUGG mean radius) against the vendor loop - a constants test, not an '
+            'independent strata test. It remains falsifiable: a wrong g, G or R '
+            'appears directly as bias here.'),
+    }

gea/gamma.py

@@ -0,0 +1,176 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+"""Gamma-ray / lithology module (v1.46.0) - field-tier step 6 (first half).
+
+The evaluation's stated oilfield goal: "No NaI(Tl) GR, API units, lithology
+from GR, or LAS curve -> formation flag. Several catalogue LAS files already
+carry GR." They do - and this module works ONLY from those measured curves:
+
+    ktb_vb_vlog251_temperature   GR   1,082 points, 74.5-124.7 API (KTB pilot)
+    volve_15_9_19_sr_excerpt     GR     133 points,  5.3-72.5 gAPI (North Sea)
+    l07_01_nl_excerpt            GR      50 points, 101.5-130.6 GAPI
+    ... (any LiveStream with an API-unit gamma channel)
+
+Honesty rules, enforced in code:
+- CHANNEL DISCIPLINE: a gamma channel is one with an API-family unit
+  (API/GAPI/gAPI). Name matching alone is refused - the catalogue itself
+  contains the trap cases (KTB 'GRAV' in mGals is gravimetry; 'Density
+  grain' contains the letters GR): units decide, not substrings.
+- METHOD LABELS: shale volume uses the linear gamma-ray index
+  Vsh = (GR - GR_clean)/(GR_shale - GR_clean) - the industry-standard
+  first-pass estimate, labeled INDUSTRY_STANDARD_METHOD (classical
+  petrophysics, NOT a GEA derivation; per the Hybrid doctrine it is never
+  dressed as one). Clean/shale picks default to the P5/P95 percentiles of
+  the measured curve, labeled STATISTICAL_PICKS (they are statistics of
+  this log, not formation knowledge); caller-supplied picks override.
+  The sand/shale cutoff defaults to 0.5, labeled CONVENTION.
+- NO INVENTED TOOL: no NaI(Tl) vendor datasheet is shipped, because none
+  was fetched - the detector-tool entry stays PARAMETERS_USER_SUPPLIED
+  (the tool-library rule); this module processes MEASURED curves only.
+"""
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+
+from .profile_catalog import CATALOG
+
+API_UNITS = {"API", "GAPI"}          # normalized upper-case API family
+METHOD_LABEL = ("INDUSTRY_STANDARD_METHOD: linear gamma-ray index "
+                "Vsh = (GR - GR_clean)/(GR_shale - GR_clean) - classical "
+                "petrophysics first-pass shale volume; NOT a GEA derivation")
+PICKS_LABEL = ("STATISTICAL_PICKS: GR_clean/GR_shale = P5/P95 percentiles of "
+               "THIS measured curve (statistics of the log, not formation "
+               "knowledge); supply picks from core/regional work to override")
+CUTOFF_LABEL = "CONVENTION: sand/shale flag cutoff Vsh = %.2f (operator-adjustable)"
+DETECTOR_NOTE = ("NaI(Tl)/BGO detector tool: PARAMETERS_USER_SUPPLIED - no "
+                 "vendor datasheet was fetched, so none is shipped; this "
+                 "module processes measured API curves only")
+
+
+def find_gr_channels(stream) -> List[str]:
+    """Gamma channels by UNIT DISCIPLINE: API-family unit required. The
+    catalogue's own trap cases (GRAV in mGals = gravimetry; 'Density grain'
+    contains 'GR') are excluded by construction: units decide."""
+    out = []
+    for name, ch in stream.channels.items():
+        unit = (ch.unit or "").strip().upper()
+        if unit in API_UNITS:
+            v = np.asarray(ch.values, dtype=float)
+            if np.any(~np.isnan(v)):
+                out.append(name)
+    return out
+
+
+def shale_volume(gr: np.ndarray,
+                 gr_clean: Optional[float] = None,
+                 gr_shale: Optional[float] = None) -> Tuple[np.ndarray, dict]:
+    """Linear gamma-ray index with labeled picks. Returns (vsh, meta);
+    values clamped to [0, 1] with the clamp count disclosed in meta."""
+    g = np.asarray(gr, dtype=float)
+    fin = g[~np.isnan(g)]
+    if len(fin) < 4:
+        raise ValueError("shale_volume needs >= 4 finite GR samples")
+    picks = "caller-supplied"
+    if gr_clean is None or gr_shale is None:
+        gr_clean = float(np.percentile(fin, 5))
+        gr_shale = float(np.percentile(fin, 95))
+        picks = PICKS_LABEL
+    if gr_shale <= gr_clean:
+        raise ValueError(
+            f"GR_shale ({gr_shale:g}) must exceed GR_clean ({gr_clean:g}) - "
+            "a flat curve carries no lithology contrast (refusing, not "
+            "inventing one)")
+    raw = (g - gr_clean) / (gr_shale - gr_clean)
+    vsh = np.clip(raw, 0.0, 1.0)
+    clamped = int(np.sum((raw < 0.0) | (raw > 1.0)) - np.sum(np.isnan(raw)))
+    return vsh, {"method": METHOD_LABEL, "picks": picks,
+                 "gr_clean_api": round(gr_clean, 2),
+                 "gr_shale_api": round(gr_shale, 2),
+                 "clamped_samples": max(clamped, 0)}
+
+
+def formation_flags(depths: np.ndarray, vsh: np.ndarray,
+                    cutoff: float = 0.5) -> List[dict]:
+    """Contiguous SAND/SHALE intervals from the Vsh curve. NaN samples end
+    intervals (gaps are gaps - never bridged)."""
+    d = np.asarray(depths, dtype=float)
+    v = np.asarray(vsh, dtype=float)
+    out: List[dict] = []
+    cur = None
+    for i in range(len(d)):
+        if np.isnan(v[i]):
+            cur = None
+            continue
+        flag = "SHALE" if v[i] >= cutoff else "SAND"
+        if cur is not None and cur["flag"] == flag:
+            cur["base_depth"] = float(d[i])
+            cur["_vals"].append(float(v[i]))
+        else:
+            cur = {"flag": flag, "top_depth": float(d[i]),
+                   "base_depth": float(d[i]), "_vals": [float(v[i])]}
+            out.append(cur)
+    for iv in out:
+        iv["n_samples"] = len(iv["_vals"])
+        iv["mean_vsh"] = round(float(np.mean(iv["_vals"])), 3)
+        del iv["_vals"]
+    return out
+
+
+def gamma_report(entry_name: str, channel: Optional[str] = None,
+                 cutoff: float = 0.5,
+                 gr_clean: Optional[float] = None,
+                 gr_shale: Optional[float] = None) -> dict:
+    """Lithology-from-GR on a catalogue entry's MEASURED curve: channel by
+    unit discipline, Vsh with labeled method/picks, sand/shale intervals.
+    Refuses - naming what it saw - when no API-unit gamma channel exists."""
+    st = CATALOG[entry_name].stream()
+    chans = find_gr_channels(st)
+    if not chans:
+        seen = {n: st.channels[n].unit for n in st.channels}
+        raise NotImplementedError(
+            f"'{entry_name}' has no gamma channel with an API-family unit - "
+            f"channels seen: {seen}. Unit discipline refuses name-only "
+            "matches (GRAV/mGals is gravimetry, not gamma).")
+    if channel is None:
+        channel = max(chans, key=lambda c: int(
+            np.sum(~np.isnan(np.asarray(st.channels[c].values, dtype=float)))))
+    elif channel not in chans:
+        raise KeyError(f"'{channel}' is not an API-unit gamma channel of "
+                       f"'{entry_name}' (gamma channels: {chans})")
+    g = np.asarray(st.channels[channel].values, dtype=float)
+    vsh, meta = shale_volume(g, gr_clean=gr_clean, gr_shale=gr_shale)
+    fin = g[~np.isnan(g)]
+    intervals = formation_flags(st.index, vsh, cutoff=cutoff)
+    return {
+        "entry": entry_name, "channel": channel,
+        "unit": st.channels[channel].unit,
+        "n_samples": int(len(fin)),
+        "depth_span": [float(st.index.min()), float(st.index.max())],
+        "gr_api": {"min": round(float(fin.min()), 2),
+                   "max": round(float(fin.max()), 2),
+                   "mean": round(float(fin.mean()), 2)},
+        "vsh": {"min": round(float(np.nanmin(vsh)), 3),
+                "max": round(float(np.nanmax(vsh)), 3), **meta},
+        "cutoff": CUTOFF_LABEL % cutoff,
+        "intervals": intervals,
+        "detector_note": DETECTOR_NOTE,
+        "provenance": {
+            "source": CATALOG[entry_name].provenance.get("source_database", "?"),
+            "license": CATALOG[entry_name].provenance.get("license", "?")},
+    }
+
+
+def gamma_entries() -> Dict[str, List[str]]:
+    """Catalogue entries carrying at least one API-unit gamma channel."""
+    out: Dict[str, List[str]] = {}
+    for name, e in CATALOG.items():
+        try:
+            chans = find_gr_channels(e.stream())
+        except Exception:
+            continue
+        if chans:
+            out[name] = chans
+    return out

gea/gauge_specs.py

@@ -0,0 +1,112 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+"""gauge_specs — real-datasheet gauge parameterization (v1.5.0 extension).
+
+Until now every layer ran on the template's generic anchors (0.215 %FS/yr
+baseline, 150 C / 15,000 psi knees, FS 30,000 psi). This module lets the whole
+stack run on a REAL gauge's published numbers instead: a `GaugeSpec` carries
+the datasheet values with an explicit citation, presets carry web-verified
+public specs, and `load_gauge_spec_json` takes any datasheet the user types in.
+
+Honesty rules (Rule 7 / PAPER_2149 Hybrid-Form doctrine):
+  * Every preset cites its source and the date it was verified. No invented
+    vendor numbers — the one candidate value that could not be verified in the
+    fetched source text (a "<0.02 %FS/yr at 200 C" claim from a search-engine
+    summary) was NOT made a preset.
+  * Datasheet drift bounds are REFERENCE-CONDITION spec limits (the GEOQ 177
+    table's <0.01 %FS/yr is ~20x below the template's 0.215 stressed-service
+    baseline). The GEA suppression RATIO (1.0324) is baseline-independent;
+    the absolute separation in psi/yr scales with whichever baseline the spec
+    supplies. Both readings are honest; the module reports which one is in use.
+
+External confirmation gained in sourcing (2026-08-23): the ChampionX
+Quartzdyne performance page states drift rate increases with temperature with
+engineering focus at 150 C and above — independent support for the template's
+150 C thermal-knee anchor.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Dict, Optional
+
+
+@dataclass(frozen=True)
+class GaugeSpec:
+    """A gauge datasheet: the anchors the physics layer runs on.
+
+    `source` is mandatory prose naming where every number came from —
+    a spec without a citation is not a spec (Rule 7).
+    """
+    name: str
+    source: str
+    full_scale_psi: float
+    baseline_drift_pct_fs_yr: float
+    max_temp_C: Optional[float] = None
+    accuracy_pct_fs: Optional[float] = None
+    thermal_knee_C: float = 150.0        # anchor: industry thermal knee (template; ChampionX-confirmed focus >=150 C)
+    pressure_knee_psi: float = 15000.0   # anchor: template pressure knee
+    thermal_exponent: float = 1.15       # template engineering fit
+    pressure_exponent: float = 0.9       # template engineering fit
+    notes: str = ""
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ---------------------------------------------------------------------------
+# Presets — every number cited; verified against the named source text
+# ---------------------------------------------------------------------------
+GAUGE_SPECS: Dict[str, GaugeSpec] = {
+    'template_generic': GaugeSpec(
+        name='template_generic',
+        source=("22Aug2026 template thread (grok_cce7a73b): 0.215 %FS/yr "
+                "typical good-quartz STRESSED-SERVICE baseline with 150 C / "
+                "15,000 psi knees and exponents 1.15/0.9 (engineering fit); "
+                "FS 30,000 psi HPHT class. The v1.0-1.4 default."),
+        full_scale_psi=30000.0,
+        baseline_drift_pct_fs_yr=0.215,
+        max_temp_C=200.0,
+        accuracy_pct_fs=None,
+        notes="stressed-service drift class, not a reference-condition spec bound",
+    ),
+    'geoq177_16k': GaugeSpec(
+        name='geoq177_16k',
+        source=("GEO PSI GEOQ 177 public specification table (Quartzdyne "
+                "sensor), geopsi.com/products/downhole-gauges/geoq-177/, "
+                "fetched 2026-08-23: 16,000 psiA range; pressure drift "
+                "<0.01 %FS/yr; accuracy +/-0.02 %FS; 177 C rating."),
+        full_scale_psi=16000.0,
+        baseline_drift_pct_fs_yr=0.01,
+        max_temp_C=177.0,
+        accuracy_pct_fs=0.02,
+        notes="reference-condition spec bound (drift is '<' the value, used as the bound)",
+    ),
+    'geoq177_30k': GaugeSpec(
+        name='geoq177_30k',
+        source=("GEO PSI GEOQ 177 public specification table (Quartzdyne "
+                "sensor), geopsi.com/products/downhole-gauges/geoq-177/, "
+                "fetched 2026-08-23: 30,000 psiA range; pressure drift "
+                "<0.01 %FS/yr; accuracy +/-0.025 %FS; 177 C rating."),
+        full_scale_psi=30000.0,
+        baseline_drift_pct_fs_yr=0.01,
+        max_temp_C=177.0,
+        accuracy_pct_fs=0.025,
+        notes="reference-condition spec bound (drift is '<' the value, used as the bound)",
+    ),
+}
+
+
+def load_gauge_spec_json(path) -> GaugeSpec:
+    """Load a user-entered datasheet from JSON. Required keys: name, source,
+    full_scale_psi, baseline_drift_pct_fs_yr. Optional keys map to the other
+    GaugeSpec fields. A missing/empty `source` is rejected (Rule 7)."""
+    with Path(path).open(encoding="utf-8") as f:
+        d = json.load(f)
+    if not d.get('source'):
+        raise ValueError("gauge spec JSON must carry a non-empty 'source' citation (Rule 7)")
+    allowed = {k for k in GaugeSpec.__dataclass_fields__}
+    return GaugeSpec(**{k: v for k, v in d.items() if k in allowed})

gea/gravity_reference.py

@@ -0,0 +1,116 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+"""gravity_reference - THE CITED EXTERNAL GRAVITY REFERENCE LAYER
+(Daniel's DO-ALL-THREE order, 2026-09-08: de-loopback the reference).
+
+Until now the only gravity numbers the surveying chain could check a live
+G6-class stream against were its own - the loopback fixture. This module
+gives the chain an EXTERNAL, CITED, PUBLIC reference: the WGS84 normal
+gravity closed form plus the standard free-air correction, evaluated at a
+surveyed site's latitude and elevation. It is an OBSERVATIONAL REFERENCE
+STANDARD - a comparison target in the PAPER_2149 hybrid-form sense, labeled
+as such, never a substitute for a GEA derivation. GEA predictions are
+compared AGAINST it; it does not seed them.
+
+CITATIONS (all public standards):
+  * WGS84 Somigliana normal gravity: NGA (NIMA) TR8350.2, 3rd ed., 2000,
+    "Department of Defense World Geodetic System 1984", eq. 4-1 with the
+    defining constants of Table 3.4 (gamma_e = 9.7803253359 m/s^2,
+    k = 0.00193185265241, e^2 = 0.00669437999013).
+  * Free-air gradient 0.3086 mGal/m: standard geodetic value (Heiskanen &
+    Moritz, "Physical Geodesy", 1967, sec. 3-2; used by BGI/IGSN71 practice).
+  * KTB main-hole site: Windischeschenbach, Germany, 49.8156 N, 12.1204 E,
+    ground elevation ~513.6 m - ICDP/KTB published site description
+    (GFZ ICDP KTB operational dataset; the same source family as the
+    library's KTB log excerpts).
+
+The register-map rule is UNCHANGED: G6 register maps remain user-supplied
+and citation-mandatory (modbus.py). What this module removes is the
+self-reference - a loaded stream's gravity values can now be checked
+against a number the repository did not generate.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Dict
+
+# WGS84 defining constants - NGA TR8350.2 Table 3.4 (cited above)
+GAMMA_EQUATOR_MS2 = 9.7803253359
+SOMIGLIANA_K = 0.00193185265241
+WGS84_E2 = 0.00669437999013
+FREE_AIR_MGAL_PER_M = 0.3086          # Heiskanen & Moritz 1967 (cited above)
+MGAL_PER_MS2 = 1e5
+
+# KTB main-hole site - ICDP/KTB published description (cited above)
+KTB_LAT_DEG = 49.8156
+KTB_LON_DEG = 12.1204
+KTB_ELEV_M = 513.6
+
+
+def somigliana_normal_gravity_ms2(lat_deg: float) -> float:
+    """WGS84 normal gravity on the ellipsoid at geodetic latitude [m/s^2].
+
+    gamma = gamma_e * (1 + k sin^2 phi) / sqrt(1 - e^2 sin^2 phi)
+    (NGA TR8350.2 eq. 4-1; closed form, no approximation).
+    """
+    s2 = math.sin(math.radians(lat_deg)) ** 2
+    return (GAMMA_EQUATOR_MS2 * (1.0 + SOMIGLIANA_K * s2)
+            / math.sqrt(1.0 - WGS84_E2 * s2))
+
+
+def free_air_correction_ms2(elev_m: float) -> float:
+    """Standard free-air reduction from ellipsoid/ground elevation [m/s^2]."""
+    return -FREE_AIR_MGAL_PER_M * elev_m / MGAL_PER_MS2
+
+
+def site_reference_gravity(lat_deg: float, elev_m: float) -> Dict:
+    """Cited external surface-gravity reference for a surveyed site."""
+    gamma0 = somigliana_normal_gravity_ms2(lat_deg)
+    fac = free_air_correction_ms2(elev_m)
+    return {
+        'lat_deg': lat_deg,
+        'elev_m': elev_m,
+        'normal_gravity_ms2': gamma0,
+        'free_air_correction_ms2': fac,
+        'reference_gravity_ms2': gamma0 + fac,
+        'kind': 'OBSERVATIONAL_REFERENCE_STANDARD',
+        'citation': ('WGS84 Somigliana (NGA TR8350.2 eq. 4-1) + free-air '
+                     '0.3086 mGal/m (Heiskanen & Moritz 1967); NOT a GEA '
+                     'derivation - the external comparison target'),
+        'note': ('local terrain/Bouguer/anomaly effects are NOT modeled '
+                 'here; agreement is expected at the ~100 mGal (1e-3 m/s^2) '
+                 'band, not exactly - the reference bounds sanity, it does '
+                 'not replace a site gravity survey'),
+    }
+
+
+def ktb_site_reference() -> Dict:
+    """The KTB main-hole site reference - the library's anchor well."""
+    out = site_reference_gravity(KTB_LAT_DEG, KTB_ELEV_M)
+    out['site'] = ('KTB Hauptbohrung, Windischeschenbach (49.8156 N, '
+                   '12.1204 E, ~513.6 m) - ICDP/KTB published site '
+                   'description')
+    return out
+
+
+def check_stream_gravity(measured_ms2: float, lat_deg: float,
+                         elev_m: float, band_ms2: float = 1.5e-3) -> Dict:
+    """QC a measured surface gravity against the cited external reference.
+
+    band_ms2 default 1.5e-3 m/s^2 (~150 mGal) spans normal regional
+    anomaly + instrument-datum offsets; a live stream outside the band is
+    flagged for datum/units review, never silently accepted."""
+    ref = site_reference_gravity(lat_deg, elev_m)
+    delta = measured_ms2 - ref['reference_gravity_ms2']
+    return {
+        'reference': ref,
+        'measured_ms2': measured_ms2,
+        'delta_ms2': delta,
+        'delta_mgal': delta * MGAL_PER_MS2,
+        'within_band': abs(delta) <= band_ms2,
+        'verdict': ('CONSISTENT_WITH_CITED_REFERENCE' if abs(delta) <= band_ms2
+                    else 'DATUM_OR_UNITS_REVIEW - measured value outside the '
+                         'regional-anomaly band of the cited reference'),
+    }