gea-program 0.1.0__py3-none-any.whl

gea/segy.py

@@ -0,0 +1,181 @@
+# 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/.
+"""segy - Part 6 of the subsurface surveying tool: SEISMIC INGEST
+(v1.83.0). SEG-Y is the industry's seismic interchange format; this reader
+brings the first WAVEFIELD modality into the read-only ingestion family.
+
+STATUS, honestly: READER_VALIDATED_BY_ROUND_TRIP; AWAITING_FIELD_SEGY.
+No field SEG-Y exists in the catalogue yet, so validation is by exact
+round-trip against a minimal spec-conformant writer (used ONLY for
+validation - the writer never touches archives). The day a licensed field
+volume lands, this reader is its door; until then no seismic claim is made.
+
+SCOPE (SEG-Y rev 1, the working subset):
+  - 3200-byte textual header (EBCDIC auto-detected and transcoded, or ASCII)
+  - 400-byte binary file header: sample interval (bytes 3217-3218),
+    samples/trace (3221-3222), data format code (3225-3226)
+  - traces: 240-byte trace headers (inline/crossline at the rev1 standard
+    byte positions 189/193, source coords at 73/77 with the scalar at 71)
+    + samples in format 5 (IEEE float32 big-endian) or format 1 (IBM
+    float32, converted exactly)
+  - anything else REFUSES with the format code named - no guessing
+
+READ-ONLY doctrine unchanged: ingest never writes, never modifies, never
+'fixes' a volume. Byte-swapped or nonconforming files refuse visibly.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+SUPPORTED_FORMATS = {1: 'IBM float32', 5: 'IEEE float32'}
+
+
+def _ibm_to_float(b: bytes) -> float:
+    """Exact IBM System/360 hexadecimal float -> Python float."""
+    (u,) = struct.unpack('>I', b)
+    if u == 0:
+        return 0.0
+    sign = -1.0 if u >> 31 else 1.0
+    exponent = ((u >> 24) & 0x7F) - 64
+    mantissa = (u & 0x00FFFFFF) / float(0x1000000)
+    return sign * mantissa * (16.0 ** exponent)
+
+
+def _float_to_ibm(x: float) -> bytes:
+    """Exact inverse for the round-trip validator (writer is test-only)."""
+    if x == 0.0:
+        return b'\x00\x00\x00\x00'
+    sign = 0x80000000 if x < 0 else 0
+    x = abs(x)
+    exponent = 64
+    while x >= 1.0:
+        x /= 16.0
+        exponent += 1
+    while x < 0.0625 and exponent > 0:
+        x *= 16.0
+        exponent -= 1
+    mantissa = int(x * 0x1000000) & 0x00FFFFFF
+    return struct.pack('>I', sign | (exponent << 24) | mantissa)
+
+
+@dataclass
+class SegyTrace:
+    inline: int
+    crossline: int
+    source_x: float
+    source_y: float
+    samples: List[float] = field(default_factory=list)
+
+
+@dataclass
+class SegyVolume:
+    textual_header: str
+    encoding: str                    # 'EBCDIC' | 'ASCII'
+    sample_interval_us: int
+    n_samples: int
+    format_code: int
+    format_name: str
+    traces: List[SegyTrace] = field(default_factory=list)
+    status: str = 'READER_VALIDATED_BY_ROUND_TRIP; AWAITING_FIELD_SEGY'
+
+    def summary(self) -> Dict:
+        return {'n_traces': len(self.traces),
+                'n_samples': self.n_samples,
+                'sample_interval_us': self.sample_interval_us,
+                'trace_length_ms': self.n_samples * self.sample_interval_us / 1000.0,
+                'format': self.format_name, 'encoding': self.encoding,
+                'status': self.status}
+
+
+def read_segy(path: str) -> SegyVolume:
+    """Read a SEG-Y rev1 file (see module scope). Refuses unsupported
+    format codes and truncated files by name, never by guess."""
+    with open(path, 'rb') as f:
+        raw_text = f.read(3200)
+        if len(raw_text) < 3200:
+            raise ValueError('SEG-Y refused: file shorter than the 3200-byte '
+                             'textual header')
+        if raw_text[:1] == b'C':
+            text, enc = raw_text.decode('ascii', 'replace'), 'ASCII'
+        else:
+            text, enc = raw_text.decode('cp037', 'replace'), 'EBCDIC'
+        bin_hdr = f.read(400)
+        if len(bin_hdr) < 400:
+            raise ValueError('SEG-Y refused: truncated binary file header')
+        (interval,) = struct.unpack('>H', bin_hdr[16:18])
+        (n_samples,) = struct.unpack('>H', bin_hdr[20:22])
+        (fmt,) = struct.unpack('>H', bin_hdr[24:26])
+        if fmt not in SUPPORTED_FORMATS:
+            raise ValueError('SEG-Y refused: data format code %d is outside '
+                             'the supported subset %s - no guessing'
+                             % (fmt, sorted(SUPPORTED_FORMATS)))
+        if n_samples == 0:
+            raise ValueError('SEG-Y refused: binary header declares zero '
+                             'samples per trace')
+        vol = SegyVolume(textual_header=text, encoding=enc,
+                         sample_interval_us=interval, n_samples=n_samples,
+                         format_code=fmt, format_name=SUPPORTED_FORMATS[fmt])
+        trace_bytes = n_samples * 4
+        while True:
+            th = f.read(240)
+            if not th:
+                break
+            if len(th) < 240:
+                raise ValueError('SEG-Y refused: truncated trace header at '
+                                 'trace %d' % (len(vol.traces) + 1))
+            data = f.read(trace_bytes)
+            if len(data) < trace_bytes:
+                raise ValueError('SEG-Y refused: truncated samples at trace '
+                                 '%d' % (len(vol.traces) + 1))
+            (scal,) = struct.unpack('>h', th[70:72])
+            (sx,) = struct.unpack('>i', th[72:76])
+            (sy,) = struct.unpack('>i', th[76:80])
+            (il,) = struct.unpack('>i', th[188:192])
+            (xl,) = struct.unpack('>i', th[192:196])
+            k = (abs(scal) if scal else 1)
+            factor = (1.0 / k) if scal < 0 else float(k)
+            if fmt == 5:
+                samples = list(struct.unpack('>%df' % n_samples, data))
+            else:
+                samples = [_ibm_to_float(data[i:i + 4])
+                           for i in range(0, trace_bytes, 4)]
+            vol.traces.append(SegyTrace(
+                inline=il, crossline=xl,
+                source_x=sx * factor, source_y=sy * factor,
+                samples=samples))
+        return vol
+
+
+def write_segy_minimal(path: str, traces: List[List[float]],
+                       sample_interval_us: int = 2000,
+                       fmt: int = 5) -> None:
+    """TEST-ONLY minimal spec-conformant writer: exists solely so the reader
+    can be validated by exact round-trip in the absence of licensed field
+    data. Never used on archives; never part of ingestion."""
+    n_samples = len(traces[0])
+    with open(path, 'wb') as f:
+        header_line = ('C 1 segy round-trip validation volume - '
+                       'TEST ONLY, not field data').ljust(80)
+        f.write((header_line + ' ' * (3200 - 80)).encode('ascii')[:3200])
+        bin_hdr = bytearray(400)
+        bin_hdr[16:18] = struct.pack('>H', sample_interval_us)
+        bin_hdr[20:22] = struct.pack('>H', n_samples)
+        bin_hdr[24:26] = struct.pack('>H', fmt)
+        f.write(bytes(bin_hdr))
+        for t_i, samples in enumerate(traces):
+            th = bytearray(240)
+            th[70:72] = struct.pack('>h', 1)
+            th[72:76] = struct.pack('>i', 1000 + t_i)
+            th[76:80] = struct.pack('>i', 2000 + t_i)
+            th[188:192] = struct.pack('>i', 10 + t_i)
+            th[192:196] = struct.pack('>i', 20 + t_i)
+            f.write(bytes(th))
+            if fmt == 5:
+                f.write(struct.pack('>%df' % n_samples, *samples))
+            else:
+                for s in samples:
+                    f.write(_float_to_ibm(s))

gea/service_life.py

@@ -0,0 +1,173 @@
+# 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/.
+"""service_life — long-horizon drift accumulation (v1.2.0 extension).
+
+The v1.0/1.1 layers report drift as an instantaneous RATE (%FS/yr). This module
+integrates that rate over months/years of simulated service, twin-leg at every
+station (GEA-stabilized vs conventional), producing the DIVERGENCE CURVES a
+real bench test or field trial would record: two error traces separating at
+exactly the rate the canonical suppression predicts. Adds optional periodic
+recalibration resets (workover/recal events) and a small random-walk component
+for realism (defaults chosen so the deterministic rate dominates).
+
+This is the full simulation instrument for the PAPER_2250 LABORATORY-tier
+quartz bench test (PAPER_2256 sec 5): the separation you'd measure, not just
+the ratio you'd predict.
+
+Headless-safe: numpy only, no display imports.
+"""
+
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+import numpy as np
+
+from .downhole_engine import DownholeEngine, SimulatorConfig
+from .quartz_hpht_extension import (
+    calculate_quartz_transducer_hpht_program,
+    canonical_suppression,
+    conventional_drift,
+)
+
+
+@dataclass
+class ServiceLifeConfig:
+    years: float = 5.0                                # simulated service horizon
+    dt_days: float = 7.0                              # accumulation step (one reading per week class)
+    full_scale_psi: float = 30000.0                   # anchor: HPHT quartz-gauge full-scale class (industry)
+    error_budget_pct_fs: float = 0.5                  # anchor: typical permanent-gauge total-error spec budget
+    recalibration_interval_years: Optional[float] = None   # None = never recalibrated (permanent install)
+    random_walk_pct_fs_per_sqrt_yr: float = 0.002     # small stochastic component (realism; 0 = deterministic)
+    seed: Optional[int] = None                        # rng seed (deterministic runs for tests)
+
+
+class ServiceLifeSimulator:
+    """Accumulates twin-leg gauge error over simulated service years.
+
+    Rates are evaluated once per sensor at the engine's base station T/P
+    (permanent-install conditions); both legs share the same industry baseline
+    and stress dressing, differing ONLY by the canonical suppression — so the
+    accumulated-error ratio converges to the suppression composition and the
+    separation grows linearly at the predicted rate.
+    """
+
+    def __init__(self, engine: DownholeEngine | None = None,
+                 config: ServiceLifeConfig | None = None):
+        self.engine = engine or DownholeEngine(SimulatorConfig())
+        self.cfg = config or ServiceLifeConfig()
+        spec = getattr(self.engine.cfg, 'gauge_spec', None)   # v1.5.0: engine's datasheet spec
+        if spec is not None:
+            from dataclasses import replace as _replace
+            self.cfg = _replace(self.cfg, full_scale_psi=float(spec.full_scale_psi))
+        n = len(self.engine.sensors)
+        # Per-sensor rates (%FS/yr) at base station conditions
+        self.rate = np.zeros(n)
+        self.conv_rate = np.zeros(n)
+        for i, s in enumerate(self.engine.sensors):
+            temp_C = (float(self.engine.base_T[i]) - 32.0) * 5.0 / 9.0
+            p_psi = float(self.engine.base_P[i])
+            r = calculate_quartz_transducer_hpht_program(
+                depth_m=s.depth_ft / 3.28084, temp_c=temp_C, pressure_psi=p_psi,
+                k_structural_trim=s.k_structural_trim,
+                phi_coupling_trim=s.phi_coupling_trim,
+                spec=spec)
+            self.rate[i] = r["value"]["drift_pct"]
+            self.conv_rate[i] = conventional_drift(temp_C, p_psi, spec=spec)
+        self._reset_history()
+
+    def _reset_history(self) -> None:
+        n = len(self.engine.sensors)
+        self.time_years: List[float] = [0.0]
+        self.err: List[np.ndarray] = [np.zeros(n)]   # accumulated error, %FS
+        self.conv_err: List[np.ndarray] = [np.zeros(n)]
+        self.recal_times: List[float] = []
+
+    # -- run ------------------------------------------------------------------
+    def run(self) -> "ServiceLifeSimulator":
+        """Integrate accumulated error over the configured horizon."""
+        self._reset_history()
+        n = len(self.engine.sensors)
+        dt = self.cfg.dt_days / 365.25
+        rng = np.random.default_rng(self.cfg.seed)
+        rw = self.cfg.random_walk_pct_fs_per_sqrt_yr
+        t = 0.0
+        uq = np.zeros(n)
+        cv = np.zeros(n)
+        since_recal = 0.0
+        while t < self.cfg.years - 1e-12:
+            t += dt
+            since_recal += dt
+            uq = uq + self.rate * dt + rng.normal(0.0, rw * np.sqrt(dt), n)
+            cv = cv + self.conv_rate * dt + rng.normal(0.0, rw * np.sqrt(dt), n)
+            if (self.cfg.recalibration_interval_years is not None
+                    and since_recal >= self.cfg.recalibration_interval_years - 1e-12):
+                uq = np.zeros(n)                    # recal zeroes both legs
+                cv = np.zeros(n)
+                since_recal = 0.0
+                self.recal_times.append(round(t, 6))
+            self.time_years.append(round(t, 6))
+            self.err.append(uq.copy())
+            self.conv_err.append(cv.copy())
+        return self
+
+    # -- reporting --------------------------------------------------------------
+    def divergence_summary(self) -> dict:
+        """The bench-test report: predicted vs measured separation, ratio check,
+        and the service-life arithmetic (time to error budget, extra years)."""
+        fs = self.cfg.full_scale_psi
+        budget = self.cfg.error_budget_pct_fs
+        sep_rate = self.conv_rate - self.rate                 # %FS/yr
+        uq_final = self.err[-1]
+        cv_final = self.conv_err[-1]
+        with np.errstate(divide='ignore', invalid='ignore'):
+            ratio_final = np.where(uq_final > 0, cv_final / uq_final, np.nan)
+        t_budget_program = budget / self.rate                    # yr to spec budget
+        t_budget_conv = budget / self.conv_rate
+        return {
+            'horizon_years': self.cfg.years,
+            'full_scale_psi': fs,
+            'rate_pct_fs_yr': [round(float(r), 4) for r in self.rate],
+            'conv_rate_pct_fs_yr': [round(float(r), 4) for r in self.conv_rate],
+            'predicted_separation_rate_pct_fs_yr': [round(float(r), 5) for r in sep_rate],
+            'predicted_separation_rate_psi_yr': [round(float(r) * fs / 100.0, 2) for r in sep_rate],
+            'final_separation_psi': [round(float(cv_final[i] - uq_final[i]) * fs / 100.0, 2)
+                                     for i in range(len(sep_rate))],
+            'measured_ratio_final': [round(float(r), 4) for r in ratio_final],
+            'predicted_ratio_suppression': round(canonical_suppression(
+                self.engine.cfg.global_k_structural_trim,
+                self.engine.cfg.global_phi_coupling_trim), 4),
+            'error_budget_pct_fs': budget,
+            'years_to_budget_program': [round(float(t), 2) for t in t_budget_program],
+            'years_to_budget_conventional': [round(float(t), 2) for t in t_budget_conv],
+            'extra_service_life_years': [round(float(t_budget_program[i] - t_budget_conv[i]), 2)
+                                         for i in range(len(sep_rate))],
+            'recalibrations': self.recal_times,
+        }
+
+    def export_csv(self, path: str | None = None) -> Path:
+        """Divergence curves: per-sensor accumulated error (psi) for both legs
+        plus the separation, one row per accumulation step."""
+        if path is None:
+            path = "service_life.csv"
+        p = Path(path)
+        fs = self.cfg.full_scale_psi
+        names = [s.name for s in self.engine.sensors]
+        with p.open("w", newline="") as f:
+            w = csv.writer(f)
+            header = ["time_years"]
+            for nm in names:
+                header += [f"err_psi_{nm}", f"conv_err_psi_{nm}", f"separation_psi_{nm}"]
+            w.writerow(header)
+            for i, t in enumerate(self.time_years):
+                row = [round(t, 4)]
+                for j in range(len(names)):
+                    uq = float(self.err[i][j]) * fs / 100.0
+                    cv = float(self.conv_err[i][j]) * fs / 100.0
+                    row += [round(uq, 3), round(cv, 3), round(cv - uq, 3)]
+                w.writerow(row)
+        return p

gea/shell.py

@@ -0,0 +1,107 @@
+# 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/.
+"""gea.shell - the desktop window (desktop extra): Wells | Reports | Geology.
+
+Everything the window shows is the same machinery the command line uses;
+the window never computes anything of its own. Wells browses the catalogue
+with each entry's provenance; Reports runs the report family for a selected
+well into a folder and opens the dashboard; Geology is the operator surface
+from the survey track when its renderers are installed.
+"""
+from __future__ import annotations
+
+import os
+import sys
+import webbrowser
+
+
+def _require_qt() -> bool:
+    try:
+        from PyQt6 import QtWidgets  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+def main() -> int:
+    if not _require_qt():
+        print('gea gui needs PyQt6:  pip install "gea-program[desktop]"')
+        return 3
+    from PyQt6.QtWidgets import (QApplication, QMainWindow, QTabWidget, QWidget, QVBoxLayout, QHBoxLayout,
+                                 QListWidget, QTextEdit, QPushButton, QLabel, QFileDialog, QLineEdit)
+    from . import __version__
+    from .profile_catalog import CATALOG
+
+    app = QApplication(sys.argv)
+    win = QMainWindow()
+    win.setWindowTitle(f'GEA {__version__} - downhole gauge monitoring')
+    tabs = QTabWidget()
+
+    # ---- Wells: the catalogue with provenance ----
+    wells = QWidget(); wl = QHBoxLayout(wells)
+    wlist = QListWidget(); wlist.addItems(sorted(CATALOG))
+    wdetail = QTextEdit(); wdetail.setReadOnly(True)
+
+    def show_well(item):
+        e = CATALOG[item.text()]
+        wdetail.setPlainText('\n'.join(f'{k}: {v}' for k, v in sorted(e.provenance.items())))
+    wlist.itemClicked.connect(show_well)
+    wl.addWidget(wlist, 1); wl.addWidget(wdetail, 2)
+    tabs.addTab(wells, 'Wells')
+
+    # ---- Reports: run the family for a well and open the dashboard ----
+    rep = QWidget(); rl = QVBoxLayout(rep)
+    info = QLabel('Production wells in the catalogue carry downhole pressure; give the well tag and the gauge station depth (ft).')
+    entry = QLineEdit('volve_f12_f14_production_excerpt'); entry.setPlaceholderText('catalogue entry')
+    tag = QLineEdit('15/9-F-12'); tag.setPlaceholderText('well tag inside the entry')
+    md = QLineEdit('10000'); md.setPlaceholderText('station MD, ft (from completion records)')
+    td = QLineEdit('10500'); td.setPlaceholderText('total depth, ft')
+    hist = QLineEdit(); hist.setPlaceholderText('optional: historian CSV for alarms and resilience')
+    pick = QPushButton('Choose historian CSV...')
+    run = QPushButton('Generate reports and open the dashboard')
+    out = QTextEdit(); out.setReadOnly(True)
+
+    def choose():
+        p, _ = QFileDialog.getOpenFileName(win, 'Historian CSV', '', 'CSV (*.csv)')
+        if p:
+            hist.setText(p)
+
+    def do_run():
+        from .__main__ import main as sub
+        folder = QFileDialog.getExistingDirectory(win, 'Output folder for the reports')
+        if not folder:
+            return
+        args = ['dashboard', '--catalog-well', f'{entry.text()}:{tag.text()}:{md.text()}', '--td', td.text(),
+                '--name', tag.text(), '--out', folder]
+        if hist.text():
+            args += ['--file', hist.text()]
+        out.setPlainText('running: gea ' + ' '.join(args)); app.processEvents()
+        import io, contextlib
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            rc = sub(args)
+        out.setPlainText(buf.getvalue() + f'\nexit {rc}')
+        idx = os.path.join(folder, 'index.html')
+        if rc == 0 and os.path.exists(idx):
+            webbrowser.open('file://' + os.path.abspath(idx))
+    pick.clicked.connect(choose); run.clicked.connect(do_run)
+    for w in (info, entry, tag, md, td, hist, pick, run, out):
+        rl.addWidget(w)
+    tabs.addTab(rep, 'Reports')
+
+    # ---- Geology: the survey-track operator surface, when its renderers exist ----
+    try:
+        from .project import build_geology_tab
+        tabs.addTab(build_geology_tab(), 'Geology')
+    except Exception:
+        pass
+
+    win.setCentralWidget(tabs)
+    win.resize(1100, 700)
+    win.show()
+    return app.exec()
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

gea/sla_report.py

@@ -0,0 +1,199 @@
+# 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/.
+"""sla_report — the monthly SLA measurement from the program's own records
+(SLA 2.0 measurement; 5.0 post-implementation; drift and staleness SLA;
+1.0 latency definitions; SOW 4.2.26 re-fit cap).
+
+Inputs are the record files the other components already write; nothing is
+typed in:
+    drift monitor log dir      evaluations.jsonl, change_log.jsonl
+    store-and-forward result   the Data Resilience machine JSON (+ records CSV)
+    alarm event log            JSON lines from the alarm engine
+    well-test record dir       approvals.jsonl
+    accuracy statement JSON    the Accuracy Statement machine JSON
+    config store               versions and rollbacks in the window
+
+Every SLA line is measured / target / status; a line whose input is absent
+is NOT MEASURED, never assumed met. Business-day arithmetic matches the
+drift monitor's.
+
+Headless-safe: numpy only.
+"""
+
+from __future__ import annotations
+
+import calendar
+import csv
+import json
+import os
+from datetime import datetime, timedelta, timezone
+from typing import Dict, List, Optional
+
+import numpy as np
+
+from .sample_record import parse_utc
+from .drift_monitor import business_days_after
+
+
+def month_window(month: str) -> tuple:
+    y, m = int(month[:4]), int(month[5:7])
+    start = datetime(y, m, 1, tzinfo=timezone.utc)
+    end = datetime(y, m, calendar.monthrange(y, m)[1], 23, 59, 59, tzinfo=timezone.utc)
+    return start, end
+
+
+def _lines(path: Optional[str]) -> List[dict]:
+    if not path or not os.path.exists(path):
+        return []
+    with open(path, encoding='utf-8') as f:
+        return [json.loads(l) for l in f if l.strip()]
+
+
+def _in(ts: str, a: datetime, b: datetime) -> bool:
+    try:
+        t = parse_utc(ts)
+    except Exception:
+        return False
+    return a <= t <= b
+
+
+def _bd_between(a: str, b: str) -> int:
+    ta, tb = parse_utc(a), parse_utc(b)
+    n, d = 0, ta
+    while d.date() < tb.date():
+        d += timedelta(days=1)
+        if d.weekday() < 5:
+            n += 1
+    return n
+
+
+def measure(month: str, monitor_log_dir: Optional[str] = None, store_forward_json: Optional[str] = None,
+            alarm_log: Optional[str] = None, well_test_dir: Optional[str] = None, accuracy_json: Optional[str] = None,
+            config_dir: Optional[str] = None, refit_cap_per_year: int = 4) -> dict:
+    a, b = month_window(month)
+    days = (b - a).days + 1
+    lines: List[dict] = []
+
+    def line(area, metric, measured, target, status, note=''):
+        lines.append({'area': area, 'metric': metric, 'measured': measured, 'target': target, 'status': status, 'note': note})
+
+    # --- drift and staleness SLA ------------------------------------------------------
+    evs = [e for e in _lines(os.path.join(monitor_log_dir, 'evaluations.jsonl')) if _in(e['timestamp_utc'], a, b)] if monitor_log_dir else []
+    chg = [e for e in _lines(os.path.join(monitor_log_dir, 'change_log.jsonl'))] if monitor_log_dir else []
+    if monitor_log_dir and (evs or chg):
+        eval_days = {parse_utc(e['timestamp_utc']).date() for e in evs}
+        first_eval = min((parse_utc(e['timestamp_utc']) for e in evs), default=None)
+        # adherence counted from the first evaluation in the month (a site commissioned mid-month is not penalised for the days before)
+        days_due = (b.date() - first_eval.date()).days + 1 if first_eval else days
+        adherence = round(100.0 * len(eval_days) / days_due, 1) if days_due else 0.0
+        line('Model drift', 'Drift evaluation cadence (days with an evaluation / days due)', f'{len(eval_days)} / {days_due} ({adherence} %)',
+             '>= 1 evaluation every 24 h', 'MET' if adherence >= 100.0 else 'NOT MET')
+        detections = sorted({e['evaluation_id'] for e in evs if e.get('drift_detected')})
+        line('Model drift', 'Evaluations with drift detected', f'{len(detections)} of {len({e["evaluation_id"] for e in evs})}', 'reported', 'REPORTED')
+        proposals = [c for c in chg if c.get('status') == 'PROPOSED' and _in(c['timestamp_utc'], a, b)]
+        decided = [c for c in chg if c.get('status') in ('APPLIED', 'REJECTED', 'BLOCKED_ANNUAL_LIMIT') and c.get('decided_utc') and _in(c['decided_utc'], a, b)]
+        refits = [c for c in decided if c.get('type') == 'REFIT_OFFSET' and c['status'] == 'APPLIED']
+        late = [c for c in refits if _bd_between(c['timestamp_utc'], c['decided_utc']) > 10]
+        line('Model drift', 'Re-fit / redeploy within 10 business days of detection', f'{len(refits) - len(late)} of {len(refits)} within',
+             '<= 10 business days', ('MET' if not late else 'NOT MET') if refits else 'NOT MEASURED', 'no re-fit in the month' if not refits else '')
+        fall = [c for c in chg if c.get('type') == 'FALLBACK' and c.get('decided_utc') and _in(c['decided_utc'], a, b)]
+        late_f = [c for c in fall if _bd_between(c['timestamp_utc'], c['decided_utc']) > 2]
+        line('Model drift', 'Fallback decided within 2 business days', f'{len(fall) - len(late_f)} of {len(fall)} within', '<= 2 business days',
+             ('MET' if not late_f else 'NOT MET') if fall else 'NOT MEASURED', 'no fallback in the month' if not fall else '')
+        year_refits: Dict[str, int] = {}
+        for c in chg:
+            if c.get('type') == 'REFIT_OFFSET' and c.get('status') == 'APPLIED' and c.get('decided_utc') and parse_utc(c['decided_utc']).year == a.year:
+                year_refits[c['station']] = year_refits.get(c['station'], 0) + 1
+        worst = max(year_refits.values()) if year_refits else 0
+        line('Model drift', f'Re-fits per station in {a.year} (year to date)', f'max {worst}', f'<= {refit_cap_per_year} per year', 'MET' if worst <= refit_cap_per_year else 'NOT MET')
+        open_props = [c for c in proposals if not any(d.get('supersedes_entry_id') == c.get('entry_id') for d in chg)]
+        line('Model drift', 'Proposals awaiting decision at month end', str(len(open_props)), '0', 'MET' if not open_props else 'ATTENTION')
+    else:
+        line('Model drift', 'Drift evaluation cadence', '-', '>= 1 evaluation every 24 h', 'NOT MEASURED', 'no monitor log supplied')
+
+    # --- latency and remote-site availability ----------------------------------------------
+    if store_forward_json and os.path.exists(store_forward_json):
+        sim = json.load(open(store_forward_json, encoding='utf-8')).get('simulation', {})
+        gr = sim.get('gap_report', {})
+        rec_csv = store_forward_json.replace('.json', '_records.csv')
+        lat = []
+        if os.path.exists(rec_csv):
+            with open(rec_csv, newline='', encoding='utf-8') as f:
+                for r in csv.DictReader(f):
+                    if r.get('ingest_timestamp_utc') and _in(r['timestamp_utc'], a, b):
+                        lat.append((parse_utc(r['ingest_timestamp_utc']) - parse_utc(r['timestamp_utc'])).total_seconds())
+        lat = np.array(lat, dtype=float)
+        if len(lat):
+            p95, p99 = float(np.percentile(lat, 95)), float(np.percentile(lat, 99))
+            w2, w5 = 100.0 * float(np.mean(lat <= 120)), 100.0 * float(np.mean(lat <= 300))
+            line('Latency', 'End-to-end latency p95 (field edge to OT lake)', f'{p95:.0f} s', '<= 120 s (95 %)', 'MET' if p95 <= 120 else 'NOT MET',
+                 'includes outage replay; SLA 7.0 exclusion applies to documented telecom outages')
+            line('Latency', 'End-to-end latency p99', f'{p99:.0f} s', '<= 300 s (99 %)', 'MET' if p99 <= 300 else 'NOT MET')
+            line('Latency', 'Records within 2 min / within 5 min', f'{w2:.2f} % / {w5:.2f} %', '95 % / 99 %', 'MET' if (w2 >= 95 and w5 >= 99) else 'NOT MET')
+        outs = sim.get('outages', [])
+        tot_h = sum(o['duration_h'] for o in outs)
+        hours = days * 24.0
+        avail = 100.0 * (1 - tot_h / hours)
+        line('Remote site', 'Link availability (outage hours / month hours)', f'{avail:.3f} % ({tot_h:.2f} h down)', '>= 99 %', 'MET' if avail >= 99.0 else 'NOT MET')
+        st = sim.get('stats', {})
+        line('Remote site', 'Store-and-forward: samples lost over capacity', str(st.get('dropped_over_capacity', 0)), '0 (72 h buffer)', 'MET' if not st.get('dropped_over_capacity') else 'NOT MET')
+        dup = sum(v.get('duplicates_in_delivery', 0) for v in gr.values())
+        line('Remote site', 'Duplicates in delivered stream', str(dup), '0', 'MET' if dup == 0 else 'NOT MET')
+        line('Remote site', 'Chronological replay', 'verified' if all(v.get('chronological_replay') for v in gr.values()) else 'VIOLATED', 'required',
+             'MET' if all(v.get('chronological_replay') for v in gr.values()) else 'NOT MET')
+    else:
+        line('Latency', 'End-to-end latency', '-', '95 % <= 2 min; 99 % <= 5 min', 'NOT MEASURED', 'no store-and-forward record supplied')
+        line('Remote site', 'Link availability', '-', '>= 99 %', 'NOT MEASURED')
+
+    # --- alarms ---------------------------------------------------------------------------------
+    al = [e for e in _lines(alarm_log) if _in(e['timestamp_utc'], a, b)] if alarm_log else []
+    if al:
+        acts = [e for e in al if e['event'] == 'ACTIVATED']
+        acked = [e for e in al if e['event'] == 'ACKNOWLEDGED']
+        rtn_un = [e for e in al if e['event'] == 'RTN_UNACKED']
+        line('Alarms', 'Activations in the month', str(len(acts)), 'reported', 'REPORTED')
+        line('Alarms', 'Alarms that returned to normal unacknowledged', f'{len(rtn_un)} of {len(acts)}', '0', 'MET' if not rtn_un else 'ATTENTION')
+        p1 = [e for e in acts if e['priority'] == 'P1']
+        line('Alarms', 'P1 activations', str(len(p1)), 'each with a documented response', 'REPORTED')
+    else:
+        line('Alarms', 'Activations in the month', '-', 'reported', 'NOT MEASURED', 'no alarm event log supplied')
+
+    # --- well tests ------------------------------------------------------------------------------
+    ap = [e for e in _lines(os.path.join(well_test_dir, 'approvals.jsonl')) if _in(e['timestamp_utc'], a, b)] if well_test_dir else []
+    if ap:
+        tests = {e['test_id'] for e in ap}
+        line('Well tests', 'Well tests with approval activity', str(len(tests)), 'reported', 'REPORTED')
+        line('Well tests', 'Approval decisions recorded', str(len(ap)), 'timestamped, named', 'MET' if all(e.get('approver') for e in ap) else 'NOT MET')
+    else:
+        line('Well tests', 'Well tests approved', '-', 'reported', 'NOT MEASURED', 'no approval trail supplied')
+
+    # --- accuracy --------------------------------------------------------------------------------
+    if accuracy_json and os.path.exists(accuracy_json):
+        bt = json.load(open(accuracy_json, encoding='utf-8')).get('backtest', {})
+        bands = bt.get('bands', {})
+        n_ok = bt.get('n_ok', 0)
+        line('Accuracy', 'Quantities meeting >= 95 % at the conservative 90 % CI end', f"{bands.get('MEETS_TARGET', 0)} of {n_ok}", 'all claimed quantities >= 95 %',
+             'MET' if bands.get('MEETS_TARGET', 0) == n_ok else 'PARTIAL', 'quantities below target are excluded from any claim')
+        line('Accuracy', 'Quantities NOT ACCEPTABLE (< 85 %)', str(bands.get('NOT_ACCEPTABLE', 0)), '0 among claimed quantities', 'REPORTED')
+    else:
+        line('Accuracy', 'Accuracy statement', '-', '>= 95 % at 90 % CI', 'NOT MEASURED', 'no accuracy statement supplied')
+
+    # --- change and continuity ------------------------------------------------------------------------
+    if config_dir and os.path.isdir(config_dir):
+        from .config_versioning import ConfigStore
+        cs = ConfigStore(config_dir)
+        changes = [e for n in cs.names() for e in cs.history(n) if _in(e['timestamp_utc'], a, b)]
+        line('Change & continuity', 'Configuration versions committed in the month', str(len(changes)), 'every change versioned with author and diff',
+             'MET' if all(e.get('author') for e in changes) else 'NOT MET')
+        line('Change & continuity', 'Rollbacks in the month', str(sum(1 for e in changes if e.get('rollback_of'))), 'reported', 'REPORTED')
+    else:
+        line('Change & continuity', 'Configuration versions', '-', 'every change versioned', 'NOT MEASURED', 'no config store supplied')
+
+    status_counts: Dict[str, int] = {}
+    for l in lines:
+        status_counts[l['status']] = status_counts.get(l['status'], 0) + 1
+    return {'month': month, 'window': [a.strftime('%Y-%m-%dT%H:%M:%SZ'), b.strftime('%Y-%m-%dT%H:%M:%SZ')], 'lines': lines,
+            'status_counts': status_counts,
+            'inputs': {'monitor_log_dir': monitor_log_dir, 'store_forward_json': store_forward_json, 'alarm_log': alarm_log,
+                       'well_test_dir': well_test_dir, 'accuracy_json': accuracy_json, 'config_dir': config_dir}}