gea-program 0.1.0__py3-none-any.whl

gea/drift_monitor.py

@@ -0,0 +1,310 @@
+# 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/.
+"""drift_monitor — drift evaluation as a scheduled job with a log.
+
+The reconciler classifies; this module runs it on a cadence, keeps the
+record, ages the result into a staleness state, and turns a
+CALIBRATION_OFFSET into a change-log entry with before/after coefficients
+that a named approver applies - or that the annual re-fit cap blocks.
+
+State lives in one directory as append-only JSON lines plus one small JSON
+state file, so the client can read every evaluation and every change with
+any text tool:
+
+    <log_dir>/evaluations.jsonl   one line per station per evaluation
+    <log_dir>/change_log.jsonl    PROPOSED / APPLIED / REJECTED / BLOCKED entries
+    <log_dir>/state.json          applied offset corrections per station,
+                                  last evaluation, re-fit count per year
+
+Clock: every public method takes `now` (aware UTC datetime) so a scheduled
+run, a replay and an acceptance test are the same code path with an injected
+clock. Nothing here reads the wall clock unless `now` is omitted.
+
+SLA clocks (business days from the evaluation that detected drift):
+notify 1, fallback 2, re-fit/redeploy 10; evaluation cadence 24 h; safety
+models revert immediately (not modelled here - no safety model in scope).
+Re-fits per station per calendar year are capped (default 4, SOW 4.2.26);
+a proposal beyond the cap is logged BLOCKED_ANNUAL_LIMIT, never applied.
+
+Headless-safe: numpy only.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass, replace
+from datetime import datetime, timedelta, timezone
+from typing import Dict, List, Optional
+
+import numpy as np
+
+from .reconciler import Reconciler, ReconcilerConfig
+from .ports import LiveStream, StreamChannel
+
+EVALUATE_EVERY_H = 24.0
+NOTIFY_BD, FALLBACK_BD, REFIT_BD = 1, 2, 10
+MAX_REFITS_PER_YEAR = 4
+DRIFT_CLASSES = ('CALIBRATION_OFFSET', 'UNEXPLAINED_OFFSET', 'UNEXPLAINED_TREND')
+
+
+def _utc(dt: Optional[datetime]) -> datetime:
+    if dt is None:
+        return datetime.now(timezone.utc).replace(microsecond=0)
+    return dt.astimezone(timezone.utc) if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+
+
+def _iso(dt: datetime) -> str:
+    return dt.strftime('%Y-%m-%dT%H:%M:%SZ')
+
+
+def _parse(s: str) -> datetime:
+    s = s.strip()
+    if s.endswith('Z'):
+        s = s[:-1]
+    dt = datetime.fromisoformat(s)
+    return dt.replace(tzinfo=timezone.utc) if dt.tzinfo is None else dt.astimezone(timezone.utc)
+
+
+def business_days_after(start: datetime, n: int) -> datetime:
+    d, added = start, 0
+    while added < n:
+        d += timedelta(days=1)
+        if d.weekday() < 5:
+            added += 1
+    return d
+
+
+@dataclass
+class MonitorConfig:
+    evaluate_every_h: float = EVALUATE_EVERY_H
+    max_refits_per_year: int = MAX_REFITS_PER_YEAR
+    notify_bd: int = NOTIFY_BD
+    fallback_bd: int = FALLBACK_BD
+    refit_bd: int = REFIT_BD
+
+
+class DriftMonitor:
+    """One well's drift evaluations, on a cadence, with the record."""
+
+    def __init__(self, well_config, log_dir: str, config: MonitorConfig | None = None,
+                 reconciler_config: ReconcilerConfig | None = None, well_name: str = 'well'):
+        self.well = well_config
+        self.well_name = well_name
+        self.cfg = config or MonitorConfig()
+        self.rcfg = reconciler_config
+        self.log_dir = str(log_dir)
+        os.makedirs(self.log_dir, exist_ok=True)
+        self.state_path = os.path.join(self.log_dir, 'state.json')
+        self.eval_path = os.path.join(self.log_dir, 'evaluations.jsonl')
+        self.change_path = os.path.join(self.log_dir, 'change_log.jsonl')
+        self.state = self._load_state()
+
+    # -- state ----------------------------------------------------------------
+    def _load_state(self) -> dict:
+        if os.path.exists(self.state_path):
+            with open(self.state_path, encoding='utf-8') as f:
+                return json.load(f)
+        return {'well': self.well_name, 'corrections_psi': {}, 'last_evaluation': None,
+                'evaluation_count': 0, 'refits_applied': {}, 'next_entry_seq': 1}
+
+    def _save_state(self) -> None:
+        with open(self.state_path, 'w', encoding='utf-8') as f:
+            json.dump(self.state, f, indent=1, sort_keys=True)
+
+    def _append(self, path: str, entry: dict) -> None:
+        with open(path, 'a', encoding='utf-8') as f:
+            f.write(json.dumps(entry, sort_keys=True, default=str) + '\n')
+
+    def _read(self, path: str) -> List[dict]:
+        if not os.path.exists(path):
+            return []
+        with open(path, encoding='utf-8') as f:
+            return [json.loads(line) for line in f if line.strip()]
+
+    def _entry_id(self, prefix: str, now: datetime) -> str:
+        seq = self.state['next_entry_seq']
+        self.state['next_entry_seq'] = seq + 1
+        return f"{prefix}-{now.strftime('%Y%m%dT%H%M%SZ')}-{seq:04d}"
+
+    # -- corrections applied to the live leg ------------------------------------
+    def corrected_stream(self, stream: LiveStream) -> LiveStream:
+        """The live stream with every APPLIED offset correction subtracted
+        from its station channel (the correction is logged; the raw file is
+        never rewritten)."""
+        corr = self.state.get('corrections_psi', {})
+        if not corr:
+            return stream
+        channels: Dict[str, StreamChannel] = {}
+        for name, ch in stream.channels.items():
+            c = float(corr.get(name, 0.0))
+            channels[name] = replace(ch, values=np.asarray(ch.values, dtype=float) - c) if c else ch
+        meta = dict(stream.meta)
+        meta['corrections_applied_psi'] = json.dumps({k: v for k, v in corr.items() if k in stream.channels})
+        return LiveStream(name=stream.name, source_format=stream.source_format, index_kind=stream.index_kind,
+                          index=stream.index, channels=channels, meta=meta)
+
+    # -- scheduling ---------------------------------------------------------------
+    def next_due(self) -> Optional[datetime]:
+        last = self.state.get('last_evaluation')
+        if not last:
+            return None
+        return _parse(last['timestamp_utc']) + timedelta(hours=self.cfg.evaluate_every_h)
+
+    def staleness(self, now: Optional[datetime] = None) -> dict:
+        now = _utc(now)
+        last = self.state.get('last_evaluation')
+        if not last:
+            return {'status': 'NEVER_EVALUATED', 'age_h': None, 'cadence_h': self.cfg.evaluate_every_h,
+                    'next_due_utc': None, 'as_of_utc': _iso(now)}
+        age_h = (now - _parse(last['timestamp_utc'])).total_seconds() / 3600.0
+        due = self.next_due()
+        return {'status': 'CURRENT' if age_h <= self.cfg.evaluate_every_h else 'STALE',
+                'age_h': round(age_h, 2), 'cadence_h': self.cfg.evaluate_every_h,
+                'last_evaluation_utc': last['timestamp_utc'], 'last_evaluation_id': last['evaluation_id'],
+                'next_due_utc': _iso(due) if due else None,
+                'overdue_h': round(max(0.0, age_h - self.cfg.evaluate_every_h), 2), 'as_of_utc': _iso(now)}
+
+    def run_scheduled(self, stream: LiveStream, station_map: Optional[Dict[str, float]] = None,
+                      now: Optional[datetime] = None, force: bool = False) -> dict:
+        """The scheduled-job entry point: evaluate when due (or forced), else
+        record that the run was not due and return the staleness state."""
+        now = _utc(now)
+        due = self.next_due()
+        if force or due is None or now >= due:
+            return self.evaluate(stream, station_map, now=now)
+        return {'action': 'SKIPPED_NOT_DUE', 'as_of_utc': _iso(now), 'next_due_utc': _iso(due),
+                'staleness': self.staleness(now)}
+
+    # -- the evaluation -------------------------------------------------------------
+    def evaluate(self, stream: LiveStream, station_map: Optional[Dict[str, float]] = None,
+                 now: Optional[datetime] = None) -> dict:
+        now = _utc(now)
+        eval_id = self._entry_id('EVAL', now)
+        live = self.corrected_stream(stream)
+        rep = Reconciler(self.well, self.rcfg).reconcile(live, station_map=station_map)
+        drift_stations = [s for s in rep['stations'] if s['classification'] in DRIFT_CLASSES]
+        clocks = None
+        if drift_stations:
+            clocks = {'notify_due': business_days_after(now, self.cfg.notify_bd).strftime('%Y-%m-%d'),
+                      'fallback_due': business_days_after(now, self.cfg.fallback_bd).strftime('%Y-%m-%d'),
+                      'refit_due': business_days_after(now, self.cfg.refit_bd).strftime('%Y-%m-%d')}
+        proposals = []
+        for s in rep['stations']:
+            entry = {'evaluation_id': eval_id, 'timestamp_utc': _iso(now), 'well': self.well_name,
+                     'station': s['channel'], 'md_ft': s.get('md_ft'), 'classification': s['classification'],
+                     'n': s.get('n'), 'span_years': s.get('span_years'), 'bias_psi': s.get('bias_psi'),
+                     'slope_psi_yr': s.get('slope_psi_yr'), 'noise_sigma_psi': s.get('noise_sigma_psi'),
+                     'transient_count': s.get('transient_count'),
+                     'drift_envelope_psi_yr': s.get('drift_envelope_psi_yr'),
+                     'correction_in_force_psi': float(self.state['corrections_psi'].get(s['channel'], 0.0)),
+                     'drift_detected': s['classification'] in DRIFT_CLASSES}
+            self._append(self.eval_path, entry)
+            if s['classification'] == 'CALIBRATION_OFFSET':
+                proposals.append(self.propose_refit(s['channel'], float(s['bias_psi']), eval_id, now))
+            elif s['classification'] in ('UNEXPLAINED_OFFSET', 'UNEXPLAINED_TREND'):
+                proposals.append(self._log_change({'type': 'FALLBACK', 'station': s['channel'],
+                                                   'evaluation_id': eval_id, 'timestamp_utc': _iso(now),
+                                                   'status': 'PROPOSED', 'classification': s['classification'],
+                                                   'bias_psi': s.get('bias_psi'), 'slope_psi_yr': s.get('slope_psi_yr'),
+                                                   'detail': 'hold model output for this station; investigate'}, now))
+        self.state['last_evaluation'] = {'evaluation_id': eval_id, 'timestamp_utc': _iso(now),
+                                         'drift_detected': bool(drift_stations),
+                                         'classification_counts': rep['classification_counts']}
+        self.state['evaluation_count'] = int(self.state.get('evaluation_count', 0)) + 1
+        self._save_state()
+        return {'action': 'EVALUATED', 'evaluation_id': eval_id, 'timestamp_utc': _iso(now),
+                'evaluation': rep, 'drift_detected': bool(drift_stations), 'sla_clocks': clocks,
+                'proposals': proposals, 'staleness': self.staleness(now)}
+
+    # -- change log -----------------------------------------------------------------
+    def _log_change(self, entry: dict, now: datetime) -> dict:
+        entry = dict(entry)
+        entry.setdefault('entry_id', self._entry_id('CHG', now))
+        self._append(self.change_path, entry)
+        self._save_state()
+        return entry
+
+    def _refits_this_year(self, station: str, year: int) -> int:
+        return int(self.state.get('refits_applied', {}).get(station, {}).get(str(year), 0))
+
+    def propose_refit(self, station: str, bias_psi: float, evaluation_id: str,
+                      now: Optional[datetime] = None) -> dict:
+        """CALIBRATION_OFFSET -> PROPOSED offset correction with before/after.
+        Blocked (logged, not applied) beyond the annual cap."""
+        now = _utc(now)
+        before = float(self.state['corrections_psi'].get(station, 0.0))
+        after = round(before + bias_psi, 3)
+        used = self._refits_this_year(station, now.year)
+        entry = {'type': 'REFIT_OFFSET', 'station': station, 'evaluation_id': evaluation_id,
+                 'timestamp_utc': _iso(now), 'coefficient': 'offset_correction_psi',
+                 'before': before, 'after': after, 'measured_bias_psi': round(bias_psi, 3),
+                 'refits_applied_this_year': used, 'annual_cap': self.cfg.max_refits_per_year}
+        if used >= self.cfg.max_refits_per_year:
+            entry.update({'status': 'BLOCKED_ANNUAL_LIMIT',
+                          'detail': f'{used} re-fits already applied to {station} in {now.year}; cap {self.cfg.max_refits_per_year}'})
+        else:
+            entry.update({'status': 'PROPOSED', 'detail': 'awaiting approval'})
+        return self._log_change(entry, now)
+
+    def approve(self, entry_id: str, approver: str, now: Optional[datetime] = None,
+                decision: str = 'APPLIED', note: str = '') -> dict:
+        """Apply (or reject) a PROPOSED entry. Applying a REFIT_OFFSET writes
+        the correction into state and counts against the annual cap."""
+        now = _utc(now)
+        entries = self._read(self.change_path)
+        src = next((e for e in entries if e.get('entry_id') == entry_id), None)
+        if src is None:
+            raise KeyError(f'no change-log entry {entry_id}')
+        if src.get('status') != 'PROPOSED':
+            raise ValueError(f"entry {entry_id} is {src.get('status')}, not PROPOSED")
+        if decision not in ('APPLIED', 'REJECTED'):
+            raise ValueError('decision must be APPLIED or REJECTED')
+        if decision == 'APPLIED' and src.get('type') == 'REFIT_OFFSET':
+            st = src['station']
+            used = self._refits_this_year(st, now.year)
+            if used >= self.cfg.max_refits_per_year:
+                decision = 'BLOCKED_ANNUAL_LIMIT'
+            else:
+                self.state['corrections_psi'][st] = float(src['after'])
+                self.state.setdefault('refits_applied', {}).setdefault(st, {})[str(now.year)] = used + 1
+        out = dict(src)
+        out.update({'status': decision, 'approver': approver, 'decided_utc': _iso(now),
+                    'note': note, 'supersedes_entry_id': entry_id})
+        out['entry_id'] = self._entry_id('CHG', now)
+        return self._log_change(out, now)
+
+    # -- views ------------------------------------------------------------------------
+    def history(self, station: Optional[str] = None, last: int = 50) -> List[dict]:
+        rows = self._read(self.eval_path)
+        if station:
+            rows = [r for r in rows if r.get('station') == station]
+        return rows[-last:]
+
+    def change_log(self, last: int = 50) -> List[dict]:
+        return self._read(self.change_path)[-last:]
+
+    def open_proposals(self) -> List[dict]:
+        entries = self._read(self.change_path)
+        superseded = {e.get('supersedes_entry_id') for e in entries if e.get('supersedes_entry_id')}
+        return [e for e in entries if e.get('status') == 'PROPOSED' and e.get('entry_id') not in superseded]
+
+    def status(self, now: Optional[datetime] = None) -> dict:
+        now = _utc(now)
+        return {'well': self.well_name, 'as_of_utc': _iso(now), 'staleness': self.staleness(now),
+                'last_evaluation': self.state.get('last_evaluation'),
+                'evaluation_count': self.state.get('evaluation_count', 0),
+                'corrections_psi': dict(self.state.get('corrections_psi', {})),
+                'refits_applied': self.state.get('refits_applied', {}),
+                'open_proposals': self.open_proposals(),
+                'log_dir': self.log_dir,
+                'log_sha256': {os.path.basename(p): _sha(p) for p in (self.eval_path, self.change_path) if os.path.exists(p)}}
+
+
+def _sha(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, 'rb') as f:
+        h.update(f.read())
+    return h.hexdigest()[:16]

gea/earth_model.py

@@ -0,0 +1,230 @@
+# 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/.
+"""earth_model - Part 1 of the subsurface surveying tool: THE EARTH MODEL.
+
+v1.74.0 (Daniel's 2026-08-29 gap analysis: "we are making a geological
+subsurface surveying tool" - this is the container that holds the map).
+
+WHAT THIS IS
+    Every catalogue entry so far has been a 1-D column at a scattered site.
+    This module registers those sites into ONE geographic frame:
+
+      - sites are grouped by ARCHIVE-DECLARED coordinates (rounded to 0.01
+        deg, ~1.1 km - the grouping resolution, disclosed) so that multiple
+        entries drilled into the same ground become one Site with the union
+        of their measured properties;
+      - every value is placed on a COMMON VERTICAL FRAME where the archive
+        supplies a reference elevation: z_ref_m = site elevation - depth
+        (metres relative to sea level; marine sites carry negative seafloor
+        elevations, the Dome C ice sheet +3233 m, Retama's KB +227.4 m);
+      - per-value UNCERTAINTY is carried where the archive supplies it (a
+        channel whose name extends the property's with 'std'), and is None
+        - never invented - everywhere else;
+      - entries whose archives declare no coordinates are listed in
+        `unregistered` with the reason, never placed by guesswork.
+
+HONESTY RULES
+    - Coordinates come from the archives themselves (PANGAEA/IODP headers,
+      the Retama drag-report well block). Nothing is geolocated by memory.
+    - Sites without a reference elevation get vertical_frame
+      'DEPTH_ONLY_NO_DATUM' and their values stay in native depth.
+    - The model never interpolates between sites; it registers, measures
+      distances (haversine, WGS-84 mean radius), and reports.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+from .profile_catalog import CATALOG
+
+EARTH_RADIUS_KM = 6371.0088          # IUGG mean Earth radius
+GROUP_DECIMALS = 2                   # site-grouping resolution ~1.1 km (disclosed)
+FT_TO_M = 0.3048                     # exact definition
+
+
+def haversine_km(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    """Great-circle distance between two points, km."""
+    p1, p2 = math.radians(lat1), math.radians(lat2)
+    dp = math.radians(lat2 - lat1)
+    dl = math.radians(lon2 - lon1)
+    a = math.sin(dp / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2
+    return 2 * EARTH_RADIUS_KM * math.asin(math.sqrt(a))
+
+
+@dataclass
+class PropertyRecord:
+    """One measured property series at a site, vertically registered."""
+    property: str
+    unit: str
+    entry: str
+    depths_m: List[float]                 # native depth (m unless noted)
+    values: List[float]
+    z_ref_m: Optional[List[float]]        # elevation-referenced (m rel. sea level) or None
+    sigma: Optional[List[float]]          # archive-supplied uncertainty or None
+    depth_unit: str = "m"
+
+
+@dataclass
+class Site:
+    key: Tuple[float, float]
+    latitude: float
+    longitude: float
+    elevation_m: Optional[float]          # reference elevation (seafloor/surface/KB)
+    elevation_datum: str                  # e.g. 'archive elevation', 'KB (drag report)'
+    vertical_frame: str                   # 'ELEVATION_REFERENCED' | 'DEPTH_ONLY_NO_DATUM'
+    entries: List[str] = field(default_factory=list)
+    records: List[PropertyRecord] = field(default_factory=list)
+
+    def properties(self) -> List[str]:
+        return sorted({r.property for r in self.records})
+
+
+def _retama_coords() -> Optional[Tuple[float, float, float]]:
+    """Parse the Retama coordinates from the drag report's VERBATIM well
+    block (archive-sourced, not remembered). Returns (lat, lon, kb_m)."""
+    if 'retama_403h_drag_report' not in CATALOG:
+        return None
+    meta = CATALOG['retama_403h_drag_report'].stream().meta.get('well', '')
+    m = re.search(r'Latitude\s+([\-0-9.]+).*?Longitude\s+([\-0-9.]+)'
+                  r'.*?KB Elevation \(ft\)\s+([\-0-9.]+)', meta)
+    if not m:
+        return None
+    return float(m.group(1)), float(m.group(2)), float(m.group(3)) * FT_TO_M
+
+
+def _sigma_for(channels, name):
+    """Archive-supplied uncertainty channel for `name`, if one exists."""
+    for cn, ch in channels.items():
+        if cn != name and cn.startswith(name) and 'std' in cn.lower():
+            return [float(v) for v in ch.values]
+    return None
+
+
+class EarthModel:
+    """The registered library: sites in one frame, refusals with reasons."""
+
+    def __init__(self):
+        self.sites: Dict[Tuple[float, float], Site] = {}
+        self.unregistered: List[Tuple[str, str]] = []
+        self._build()
+
+    # -- construction ------------------------------------------------------
+    def _add_records(self, site: Site, entry_name: str, st, depth_unit="m",
+                     depth_scale=1.0, md_indexed=False) -> None:
+        """md_indexed=True marks DEVIATED wells whose index is MEASURED depth:
+        vertical registration then comes from the entry's own row-aligned TVD
+        channel (never from MD - a horizontal well's MD is not a height), and
+        entries without a TVD channel stay unregistered vertically (z=None).
+        Near-vertical scientific boreholes use index depth directly; that
+        approximation (depth-below-surface ~ true vertical depth) is the
+        model's stated assumption for hole inclinations < a few degrees."""
+        site.entries.append(entry_name)
+        if st.index_kind != 'depth':
+            return                       # ordinal/time entries register the site only
+        depths = [float(d) * depth_scale for d in st.index]
+        tvd_m = None
+        if md_indexed:
+            tvd_ch = next((ch for cn, ch in st.channels.items()
+                           if cn.upper().startswith('TVD')), None)
+            if tvd_ch is not None:
+                tvd_m = [float(v) * depth_scale for v in tvd_ch.values]
+        for cn, ch in st.channels.items():
+            if 'std' in cn.lower():
+                continue                 # uncertainty channels attach to their property
+            vals = [float(v) for v in ch.values]
+            if site.elevation_m is None:
+                z = None
+            elif md_indexed:
+                z = ([site.elevation_m - t for t in tvd_m]
+                     if tvd_m is not None else None)
+            else:
+                z = [site.elevation_m - d for d in depths]
+            site.records.append(PropertyRecord(
+                property=cn, unit=ch.unit, entry=entry_name,
+                depths_m=depths, values=vals, z_ref_m=z,
+                sigma=_sigma_for(st.channels, cn), depth_unit=depth_unit))
+
+    def _site_for(self, lat: float, lon: float, elev, datum: str) -> Site:
+        key = (round(lat, GROUP_DECIMALS), round(lon, GROUP_DECIMALS))
+        if key not in self.sites:
+            self.sites[key] = Site(
+                key=key, latitude=lat, longitude=lon,
+                elevation_m=(float(elev) if elev is not None else None),
+                elevation_datum=datum,
+                vertical_frame=('ELEVATION_REFERENCED' if elev is not None
+                                else 'DEPTH_ONLY_NO_DATUM'))
+        return self.sites[key]
+
+    def _build(self) -> None:
+        retama = _retama_coords()
+        for name, e in sorted(CATALOG.items()):
+            if name.startswith('retama_403h'):
+                if retama is None:
+                    self.unregistered.append((name, 'retama drag-report well block absent'))
+                    continue
+                lat, lon, kb = retama
+                site = self._site_for(lat, lon, kb, 'KB (drag-report well block, 746 ft)')
+                # operator survey depths are in FEET
+                self._add_records(site, name, e.stream(), depth_unit='ft->m',
+                                  depth_scale=FT_TO_M, md_indexed=True)
+                continue
+            try:
+                st = e.stream()
+            except Exception as ex:
+                self.unregistered.append((name, 'non-stream entry: %s' % type(ex).__name__))
+                continue
+            lat, lon = st.meta.get('latitude'), st.meta.get('longitude')
+            if not (lat and lon):
+                self.unregistered.append((name, 'archive declares no coordinates'))
+                continue
+            site = self._site_for(float(lat), float(lon), st.meta.get('elevation_m'),
+                                  'archive elevation')
+            self._add_records(site, name, st)
+
+    # -- geography ---------------------------------------------------------
+    def distance_km(self, a: Tuple[float, float], b: Tuple[float, float]) -> float:
+        sa, sb = self.sites[a], self.sites[b]
+        return haversine_km(sa.latitude, sa.longitude, sb.latitude, sb.longitude)
+
+    def nearest(self, lat: float, lon: float, k: int = 3):
+        ranked = sorted(self.sites.values(),
+                        key=lambda s: haversine_km(lat, lon, s.latitude, s.longitude))
+        return [(s.key, round(haversine_km(lat, lon, s.latitude, s.longitude), 1))
+                for s in ranked[:k]]
+
+    def span_km(self) -> Tuple[float, Tuple, Tuple]:
+        keys = list(self.sites)
+        best = (0.0, None, None)
+        for i, a in enumerate(keys):
+            for b in keys[i + 1:]:
+                d = self.distance_km(a, b)
+                if d > best[0]:
+                    best = (d, a, b)
+        return best
+
+    # -- reporting ---------------------------------------------------------
+    def census(self) -> dict:
+        n_rec = sum(len(s.records) for s in self.sites.values())
+        n_unc = sum(1 for s in self.sites.values() for r in s.records
+                    if r.sigma is not None)
+        span, a, b = self.span_km()
+        lats = [s.latitude for s in self.sites.values()]
+        return {
+            'sites': len(self.sites),
+            'registered_entries': sum(len(s.entries) for s in self.sites.values()),
+            'unregistered_entries': len(self.unregistered),
+            'property_records': n_rec,
+            'records_with_archive_uncertainty': n_unc,
+            'multi_entry_sites': sum(1 for s in self.sites.values() if len(s.entries) > 1),
+            'elevation_referenced_sites': sum(1 for s in self.sites.values()
+                                              if s.vertical_frame == 'ELEVATION_REFERENCED'),
+            'latitude_span_deg': round(max(lats) - min(lats), 2),
+            'great_circle_span_km': round(span, 1),
+            'span_endpoints': (a, b),
+            'grouping_resolution_deg': 10 ** -GROUP_DECIMALS,
+        }

gea/example_register_map.json

@@ -0,0 +1,14 @@
+{
+  "name": "EXAMPLE_TEST_FIXTURE_loopback_map",
+  "source": "EXAMPLE TEST FIXTURE ONLY (v1.11.0, 2026-08-24): describes the in-process pymodbus loopback server used to verify the tap - NOT a device register map. No public G6 register map exists in the fetched sources; obtain your site's map from the G6/site documentation and cite it here (Rule 7).",
+  "unit_id": 1,
+  "word_order": "big",
+  "table": "holding",
+  "registers": [
+    {"channel": "P_raw_psi_S1", "address": 0, "type": "float32", "unit": "psi"},
+    {"channel": "T_raw_F_S1", "address": 2, "type": "float32", "unit": "degF"},
+    {"channel": "P_raw_psi_S2", "address": 4, "type": "float32", "unit": "psi"},
+    {"channel": "T_raw_F_S2", "address": 6, "type": "float32", "unit": "degF"},
+    {"channel": "status_word", "address": 8, "type": "uint16", "unit": ""}
+  ]
+}

gea/fat_sat.py

@@ -0,0 +1,68 @@
+# 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/.
+"""fat_sat — the acceptance suite rendered as a Factory / Site Acceptance
+Test protocol (SOW 4.2.20 FAT; 4.2.21 SAT).
+
+The in-package acceptance suite already checks the product end to end; a
+client witnesses those checks as a numbered protocol: step, section, check,
+expected, actual (PASS / FAIL), witness. This module runs the selected
+sections through the suite's own `ok()` hook and renders the protocol with
+a signature block. A FAT is run on the build before delivery; a SAT runs the
+same steps on the installed environment and records that environment (from
+the SBOM). Checks whose wording belongs to the program's internal register
+are excluded from the client protocol and counted, so the protocol reads in
+the client's vocabulary without altering any check.
+
+Headless-safe: standard library only.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+
+# Sections offered to the client protocol, in run order: (key, function name, title)
+CLIENT_SECTIONS = [
+    ('A', 'section_a_cli', 'Headless command line: runs, exports, determinism, ingest round-trip'),
+    ('C', 'section_c_reconciler', 'Two-stream reconciliation and classification'),
+    ('F', 'section_f_ports', 'Ingest ports (historian CSV, LAS)'),
+    ('AA', 'section_aa_client_reports', 'Client report family: records, quality, drift, accuracy, monitor, well tests, alarms, model cards, resilience, configuration, SBOM, SLA, FAT/SAT, dashboard'),
+]
+
+
+def run_protocol(kind: str = 'FAT', sections: Optional[List[str]] = None) -> dict:
+    """Run the selected sections and return the protocol rows."""
+    from . import acceptance_tests as AT
+    from .client_reports import forbidden_terms
+    keys = [k for k, _, _ in CLIENT_SECTIONS] if not sections else sections
+    rows: List[dict] = []
+    excluded = 0
+    started = datetime.now(timezone.utc)
+    with tempfile.TemporaryDirectory() as tmp:
+        for key, fn, title in CLIENT_SECTIONS:
+            if key not in keys:
+                continue
+            before = len(AT._RESULTS)
+            f = getattr(AT, fn)
+            try:
+                f(tmp) if 'tmp' in f.__code__.co_varnames[:f.__code__.co_argcount] else f()
+            except Exception as ex:                      # a crash is a FAIL row, never a silent skip
+                AT._RESULTS.append((False, f'{key}: section raised {type(ex).__name__}: {ex}'))
+            for passed, msg in AT._RESULTS[before:]:
+                if forbidden_terms(msg):
+                    excluded += 1
+                    continue
+                rows.append({'step': len(rows) + 1, 'section': key, 'section_title': title, 'check': msg,
+                             'expected': 'PASS', 'actual': 'PASS' if passed else 'FAIL', 'witness': ''})
+    finished = datetime.now(timezone.utc)
+    n_fail = sum(1 for r in rows if r['actual'] == 'FAIL')
+    env = None
+    if kind.upper() == 'SAT':
+        from .sbom import generate
+        env = generate()
+    return {'kind': kind.upper(), 'started_utc': started.strftime('%Y-%m-%dT%H:%M:%SZ'),
+            'finished_utc': finished.strftime('%Y-%m-%dT%H:%M:%SZ'), 'sections': keys, 'rows': rows,
+            'n_steps': len(rows), 'n_pass': len(rows) - n_fail, 'n_fail': n_fail, 'internal_checks_excluded': excluded,
+            'result': 'ACCEPTED' if n_fail == 0 and rows else 'NOT ACCEPTED', 'environment': env}