gea-program 0.1.0__py3-none-any.whl

gea/telemetry.py

@@ -0,0 +1,306 @@
+# 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/.
+"""telemetry — field-telemetry realism layer (v1.3.0 extension).
+
+The engine produces clean physics samples at an arbitrary internal step. Real
+permanent-gauge telemetry does not look like that: it arrives at a fixed
+cadence (one reading per minute is the permanent-quartz-gauge class), and it
+carries faults — telemetry-line burst dropouts (whole string goes dark),
+stuck gauges (electronics freeze, both channels repeat the last value), and
+single-sample spikes (electrical noise on the line). Historians tag every
+sample with a quality flag, and analysis pipelines are judged by how well
+they reject the garbage without touching the physics.
+
+This module wraps the engine in exactly that: timestamped fixed-cadence
+sampling, a fault injector with per-mode ground-truth masks, quality flags on
+every sample, a Hampel spike-rejection pass producing cleaned channels, and —
+because the injector KNOWS what it injected — a precision/recall score for
+the rejection filter. Exported CSVs look like real field data, so the module
+doubles as a test bench for downhole analysis pipelines.
+
+Headless-safe: numpy only, no display imports. Deterministic under a seed.
+"""
+
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+import numpy as np
+
+from .downhole_engine import DownholeEngine, SimulatorConfig
+
+
+@dataclass
+class TelemetryConfig:
+    sample_interval_s: float = 60.0                 # anchor: 1 sample/min permanent-gauge telemetry class
+    duration_hours: float = 24.0
+    start_time: str = "2026-01-01T00:00:00"         # timestamp origin for the field-style export
+    line_dropout_start_prob: float = 0.001          # per sample: telemetry-line burst dropout begins (string-wide)
+    line_dropout_len_samples: Tuple[int, int] = (1, 20)
+    gauge_stuck_start_prob: float = 0.0008          # per gauge per sample: electronics freeze begins
+    gauge_stuck_len_samples: Tuple[int, int] = (10, 120)
+    spike_prob: float = 0.002                       # per channel per sample: single-sample outlier
+    spike_sigma_psi: float = 250.0                  # spike excursion scale, pressure channel
+    spike_sigma_F: float = 25.0                     # spike excursion scale, temperature channel
+    hampel_window: int = 21                         # rejection filter: rolling window (odd; ~20 min context at 1/min)
+    hampel_n_sigma: float = 5.0                     # rejection filter: MAD threshold
+    common_mode_veto: bool = True                   # unflag multi-gauge excursions (well events, not gauge faults)
+    stuck_min_run: int = 3                          # frozen-value QC: identical consecutive samples = stuck
+    seed: Optional[int] = None
+
+
+class TelemetryRecorder:
+    """Records engine output as faulted, flagged, fixed-cadence field telemetry.
+
+    Quality flags per gauge per sample: OK, MISSING (line dropout), STUCK
+    (frozen electronics), SPIKE (outlier on P and/or T). Ground-truth fault
+    masks are kept so the rejection filter can be scored honestly.
+    """
+
+    def __init__(self, engine: DownholeEngine | None = None,
+                 config: TelemetryConfig | None = None):
+        self.engine = engine or DownholeEngine(SimulatorConfig())
+        self.cfg = config or TelemetryConfig()
+
+    # -- acquisition ----------------------------------------------------------
+    def run(self) -> "TelemetryRecorder":
+        cfg = self.cfg
+        rng = np.random.default_rng(cfg.seed)
+        if cfg.seed is not None:
+            # the engine's step() draws from the global RNGs (template-faithful);
+            # seed them too so a seeded telemetry run is fully reproducible
+            import random as _random
+            np.random.seed(cfg.seed)
+            _random.seed(cfg.seed)
+        n_g = len(self.engine.sensors)
+        n_s = int(cfg.duration_hours * 3600.0 / cfg.sample_interval_s)
+
+        self.time_s = np.arange(n_s) * cfg.sample_interval_s
+        self.P_raw = np.full((n_s, n_g), np.nan)
+        self.T_raw = np.full((n_s, n_g), np.nan)
+        self.flags: List[List[str]] = []
+        # ground-truth fault masks
+        self.mask_missing = np.zeros((n_s, n_g), dtype=bool)
+        self.mask_stuck = np.zeros((n_s, n_g), dtype=bool)
+        self.mask_spike_P = np.zeros((n_s, n_g), dtype=bool)
+        self.mask_spike_T = np.zeros((n_s, n_g), dtype=bool)
+
+        line_drop_left = 0
+        stuck_left = np.zeros(n_g, dtype=int)
+        stuck_P = np.zeros(n_g)
+        stuck_T = np.zeros(n_g)
+
+        for k in range(n_s):
+            self.engine.step(dt=cfg.sample_interval_s)
+            P = self.engine.P.copy()
+            T = self.engine.T.copy()
+            row_flags = ["OK"] * n_g
+
+            # telemetry-line burst dropout (string-wide)
+            if line_drop_left == 0 and rng.random() < cfg.line_dropout_start_prob:
+                line_drop_left = int(rng.integers(cfg.line_dropout_len_samples[0],
+                                                  cfg.line_dropout_len_samples[1] + 1))
+            if line_drop_left > 0:
+                line_drop_left -= 1
+                self.mask_missing[k, :] = True
+                self.flags.append(["MISSING"] * n_g)
+                continue    # nothing recorded this sample
+
+            for g in range(n_g):
+                # stuck electronics (per gauge, freezes both channels)
+                if stuck_left[g] == 0 and rng.random() < cfg.gauge_stuck_start_prob:
+                    stuck_left[g] = int(rng.integers(cfg.gauge_stuck_len_samples[0],
+                                                     cfg.gauge_stuck_len_samples[1] + 1))
+                    stuck_P[g], stuck_T[g] = P[g], T[g]
+                if stuck_left[g] > 0:
+                    stuck_left[g] -= 1
+                    P[g], T[g] = stuck_P[g], stuck_T[g]
+                    self.mask_stuck[k, g] = True
+                    row_flags[g] = "STUCK"
+                    continue    # a frozen gauge doesn't also spike
+                # single-sample spikes (per channel)
+                sp = rng.random() < cfg.spike_prob
+                st = rng.random() < cfg.spike_prob
+                if sp:
+                    P[g] += rng.normal(0.0, cfg.spike_sigma_psi)
+                    self.mask_spike_P[k, g] = True
+                if st:
+                    T[g] += rng.normal(0.0, cfg.spike_sigma_F)
+                    self.mask_spike_T[k, g] = True
+                if sp or st:
+                    row_flags[g] = "SPIKE"
+
+            self.P_raw[k, :] = P
+            self.T_raw[k, :] = T
+            self.flags.append(row_flags)
+
+        self._despike()
+        return self
+
+    # -- rejection filter (Hampel) --------------------------------------------
+    @staticmethod
+    def _hampel(series: np.ndarray, window: int, n_sigma: float):
+        """Rolling-median MAD despike. Returns (cleaned, detected_mask,
+        rolling_medians). NaNs (missing samples) pass through untouched and
+        undetected."""
+        x = series.copy()
+        n = len(x)
+        half = window // 2
+        detected = np.zeros(n, dtype=bool)
+        meds = series.copy()
+        for i in range(n):
+            if np.isnan(x[i]):
+                continue
+            lo, hi = max(0, i - half), min(n, i + half + 1)
+            w = series[lo:hi]
+            w = w[~np.isnan(w)]
+            if len(w) < 3:
+                continue
+            med = np.median(w)
+            meds[i] = med
+            mad = np.median(np.abs(w - med))
+            sigma = 1.4826 * mad
+            if sigma > 0 and abs(x[i] - med) > n_sigma * sigma:
+                detected[i] = True
+                x[i] = med
+        return x, detected, meds
+
+    @staticmethod
+    def _frozen_runs(series: np.ndarray, min_run: int) -> np.ndarray:
+        """Frozen-value QC (standard historian check): runs of identical
+        consecutive samples of length >= min_run are a stuck gauge — live
+        noise never repeats a float exactly."""
+        n = len(series)
+        detected = np.zeros(n, dtype=bool)
+        i = 0
+        while i < n - 1:
+            if not np.isnan(series[i]) and series[i + 1] == series[i]:
+                j = i
+                while j + 1 < n and series[j + 1] == series[j]:
+                    j += 1
+                if j - i + 1 >= min_run:
+                    detected[i:j + 1] = True
+                i = j + 1
+            else:
+                i += 1
+        return detected
+
+    def _despike(self) -> None:
+        n_s, n_g = self.P_raw.shape
+        self.P_clean = np.empty_like(self.P_raw)
+        self.T_clean = np.empty_like(self.T_raw)
+        self.detected_P = np.zeros((n_s, n_g), dtype=bool)
+        self.detected_T = np.zeros((n_s, n_g), dtype=bool)
+        # frozen-value detection first (gauge-level: P and T freeze together)
+        self.detected_stuck = np.zeros((n_s, n_g), dtype=bool)
+        for g in range(n_g):
+            self.detected_stuck[:, g] = (
+                self._frozen_runs(self.P_raw[:, g], self.cfg.stuck_min_run)
+                | self._frozen_runs(self.T_raw[:, g], self.cfg.stuck_min_run))
+        med_P = np.empty_like(self.P_raw)
+        med_T = np.empty_like(self.T_raw)
+        for g in range(n_g):
+            # stuck samples are excluded from the filter statistics (their
+            # zero-variance runs crush the MAD and flood the boundary with
+            # false spikes) and are never themselves despiked
+            p_stat = self.P_raw[:, g].copy()
+            t_stat = self.T_raw[:, g].copy()
+            p_stat[self.detected_stuck[:, g]] = np.nan
+            t_stat[self.detected_stuck[:, g]] = np.nan
+            self.P_clean[:, g], self.detected_P[:, g], med_P[:, g] = self._hampel(
+                p_stat, self.cfg.hampel_window, self.cfg.hampel_n_sigma)
+            self.T_clean[:, g], self.detected_T[:, g], med_T[:, g] = self._hampel(
+                t_stat, self.cfg.hampel_window, self.cfg.hampel_n_sigma)
+            st = self.detected_stuck[:, g]
+            self.P_clean[st, g] = self.P_raw[st, g]
+            self.T_clean[st, g] = self.T_raw[st, g]
+        if self.cfg.common_mode_veto and n_g >= 3:
+            # A gauge fault hits ONE gauge; a well transient hits the STRING.
+            # Two vetoes: (a) coincidence — independent faults essentially
+            # never hit two gauges on the same sample; (b) residual — at a
+            # flagged sample, if the OTHER gauges' median residual moved the
+            # same direction by a comparable amount, the excursion is physics
+            # (a well transient seen string-wide), not electronics.
+            for det, raw, clean, med in ((self.detected_P, self.P_raw, self.P_clean, med_P),
+                                         (self.detected_T, self.T_raw, self.T_clean, med_T)):
+                veto = np.sum(det, axis=1) >= 2
+                for k in np.where(np.any(det, axis=1) & ~veto)[0]:
+                    g = int(np.argmax(det[k, :]))
+                    r = raw[k, :] - med[k, :]
+                    others = np.delete(r, g)
+                    others = others[~np.isnan(others)]
+                    if len(others) >= 2:
+                        m = float(np.median(others))
+                        if m * r[g] > 0 and abs(m) >= 0.3 * abs(r[g]):
+                            veto[k] = True
+                for k in np.where(veto)[0]:
+                    clean[k, :] = raw[k, :]
+                    det[k, :] = False
+
+    # -- reporting -------------------------------------------------------------
+    @staticmethod
+    def _score(detected: np.ndarray, injected: np.ndarray) -> dict:
+        tp = int(np.sum(detected & injected))
+        fp = int(np.sum(detected & ~injected))
+        fn = int(np.sum(~detected & injected))
+        return {
+            'injected': int(np.sum(injected)),
+            'detected': int(np.sum(detected)),
+            'true_positives': tp,
+            'false_positives': fp,
+            'precision': round(tp / (tp + fp), 3) if (tp + fp) else None,
+            'recall': round(tp / (tp + fn), 3) if (tp + fn) else None,
+        }
+
+    def telemetry_summary(self) -> dict:
+        n_s, n_g = self.P_raw.shape
+        total = n_s * n_g
+        n_missing = int(np.sum(self.mask_missing))
+        return {
+            'samples': n_s,
+            'gauges': n_g,
+            'sample_interval_s': self.cfg.sample_interval_s,
+            'duration_hours': self.cfg.duration_hours,
+            'uptime_pct': round(100.0 * (1.0 - n_missing / total), 2),
+            'missing_samples': n_missing,
+            'stuck_samples': int(np.sum(self.mask_stuck)),
+            'stuck_score': self._score(self.detected_stuck, self.mask_stuck),
+            'spike_score_P': self._score(self.detected_P, self.mask_spike_P),
+            'spike_score_T': self._score(self.detected_T, self.mask_spike_T),
+        }
+
+    # -- export (field-style) --------------------------------------------------
+    def export_csv(self, path: str | None = None) -> Path:
+        """Field-historian-style CSV: ISO timestamp, then per gauge the raw
+        P/T, the quality flag, and the cleaned P/T. Missing samples are blank
+        with flag MISSING — exactly what a real export hands an analyst."""
+        if path is None:
+            path = "telemetry.csv"
+        p = Path(path)
+        t0 = datetime.fromisoformat(self.cfg.start_time)
+        names = [s.name for s in self.engine.sensors]
+        with p.open("w", newline="") as f:
+            w = csv.writer(f)
+            header = ["timestamp"]
+            for nm in names:
+                header += [f"P_raw_psi_{nm}", f"T_raw_F_{nm}", f"flag_{nm}",
+                           f"P_clean_psi_{nm}", f"T_clean_F_{nm}"]
+            w.writerow(header)
+            for k in range(len(self.time_s)):
+                row = [(t0 + timedelta(seconds=float(self.time_s[k]))).isoformat()]
+                for g in range(len(names)):
+                    if self.mask_missing[k, g]:
+                        row += ["", "", "MISSING", "", ""]
+                    else:
+                        row += [round(float(self.P_raw[k, g]), 2),
+                                round(float(self.T_raw[k, g]), 2),
+                                self.flags[k][g],
+                                round(float(self.P_clean[k, g]), 2),
+                                round(float(self.T_clean[k, g]), 2)]
+                w.writerow(row)
+        return p

gea/tool_library.py

@@ -0,0 +1,260 @@
+# 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/.
+"""tool_library — the downhole tool library (v1.7.0 extension).
+
+Generalizes the v1.5.0 gauge-spec discipline to the whole toolstring: a cited
+catalog of downhole and surface tools (`ToolSpec`), per-class drift/response
+models, a `ToolString` builder, and rating checks against real well
+conditions. Every entry declares the telemetry interface it speaks — the
+declaration the ports/plug-in layer will implement when the program taps
+running logging systems (the live-stream side of the two-stream design).
+
+Honesty rules (Rule 7 / PAPER_2149), same as gauge_specs:
+  * Every catalog entry carries a mandatory `source` citation.
+  * Where a tool's EXISTENCE and class are verified but its quantitative
+    parameters were not published on the fetched pages, the entry is marked
+    `PARAMETERS_USER_SUPPLIED`: its numbers are None, and asking it for a
+    drift model raises rather than inventing vendor data.
+  * The piezoresistive drift model's COEFFICIENTS are a representative
+    engineering fit (disclosed as such); its FORM is cited — the ChampionX
+    Quartzdyne performance page states verbatim that piezoresistive drift is
+    unpredictable and increases exponentially with increasing temperature,
+    while quartz drift is predictable and compensatable.
+
+Verified sources (fetched 2026-08-23):
+  * GEO PSI product catalog + GEOQ 177 public specification table
+    (geopsi.com/products/downhole-gauges/) — Quartzdyne-sensor quartz P/T
+    gauges (spec table), GEOP piezoresistive family, GEOVW 250 vibrating-wire,
+    GEOXTR 18pt thermocouple input card, GEOPulse fiber optics (DAS/DTS),
+    G6 interface card (Modbus RS485 + 4-20mA surface communications),
+    PSK downhole telemetry, up to 10 sensors per TEC line.
+  * ChampionX Quartzdyne performance page — quartz-vs-piezoresistive drift
+    character statement cited above.
+
+Headless-safe: numpy only.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, Optional, Tuple
+
+from .gauge_specs import GAUGE_SPECS, GaugeSpec
+from .quartz_hpht_extension import (
+    calculate_quartz_transducer_hpht_program,
+    conventional_drift,
+)
+
+# tool classes
+QUARTZ_PT = "QUARTZ_PT_GAUGE"
+PIEZO_PT = "PIEZORESISTIVE_PT_GAUGE"
+VIBRATING_WIRE = "VIBRATING_WIRE_GAUGE"
+THERMOCOUPLE = "THERMOCOUPLE_STRING"
+FIBER_DTS = "FIBER_DTS"
+SURFACE_INTERFACE = "SURFACE_INTERFACE"
+
+FULLY_SPECIFIED = "FULLY_SPECIFIED"
+PARAMETERS_USER_SUPPLIED = "PARAMETERS_USER_SUPPLIED"
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    """A catalog entry: what the tool is, what it measures, what it speaks.
+
+    `source` is mandatory citation prose (Rule 7). `spec_status` says whether
+    the numbers are published-and-verified or must come from the user's own
+    datasheet. `telemetry_interface` is the declaration the ports layer will
+    implement — the tool library names the protocol, the plug-in speaks it.
+    """
+    name: str
+    tool_class: str
+    source: str
+    measures: Tuple[str, ...]
+    telemetry_interface: str
+    spec_status: str = FULLY_SPECIFIED
+    temp_rating_C: Optional[float] = None
+    pressure_rating_psi: Optional[float] = None
+    gauge_spec: Optional[GaugeSpec] = None      # quartz tools wrap a v1.5.0 GaugeSpec
+    drift_model: Optional[str] = None           # 'quartz_program' | 'quartz_conventional' | 'piezoresistive'
+    params: dict = field(default_factory=dict)
+    notes: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Drift/response models
+# ---------------------------------------------------------------------------
+def piezoresistive_drift(temp_c: float,
+                         base_drift_pct_fs_yr: float = 0.1,
+                         ref_temp_C: float = 25.0,
+                         e_fold_C: float = 40.0) -> float:
+    """Piezoresistive P/T gauge drift (%FS/yr).
+
+    FORM (cited): ChampionX Quartzdyne performance page — "Piezoresistive
+    drift is unpredictable. Piezoresistive drift increases exponentially with
+    increasing temperature." Modeled as base * exp((T - T_ref)/e_fold).
+
+    COEFFICIENTS (disclosed, representative engineering fit — NOT vendor
+    data): 0.1 %FS/yr at 25 C reference with a 40 C e-folding scale. The
+    'unpredictable' character means real units scatter widely around this
+    curve; this is a class-typical envelope for simulation, not a spec bound.
+    """
+    return base_drift_pct_fs_yr * math.exp((temp_c - ref_temp_C) / e_fold_C)
+
+
+def drift_model_for(tool: ToolSpec) -> Callable[[float, float], float]:
+    """Return f(temp_c, pressure_psi) -> drift %FS/yr for a measuring tool.
+
+    Raises for PARAMETERS_USER_SUPPLIED entries (no invented vendor numbers)
+    and for non-measuring tools (surface interfaces have no drift model).
+    """
+    if tool.spec_status == PARAMETERS_USER_SUPPLIED:
+        raise ValueError(
+            f"{tool.name}: parameters are user-supplied - load your datasheet "
+            f"values (Rule 7: the library does not invent vendor numbers)")
+    if tool.drift_model == 'quartz_program':
+        def f(temp_c, pressure_psi, _s=tool.gauge_spec):
+            r = calculate_quartz_transducer_hpht_program(0.0, temp_c, pressure_psi, spec=_s)
+            return float(r['value']['drift_pct'])
+        return f
+    if tool.drift_model == 'quartz_conventional':
+        return lambda temp_c, pressure_psi, _s=tool.gauge_spec: conventional_drift(temp_c, pressure_psi, spec=_s)
+    if tool.drift_model == 'piezoresistive':
+        p = tool.params
+        return lambda temp_c, pressure_psi: piezoresistive_drift(
+            temp_c, p.get('base_drift_pct_fs_yr', 0.1),
+            p.get('ref_temp_C', 25.0), p.get('e_fold_C', 40.0))
+    raise ValueError(f"{tool.name}: no drift model (tool class {tool.tool_class})")
+
+
+# ---------------------------------------------------------------------------
+# The catalog — every entry cited
+# ---------------------------------------------------------------------------
+_GEOPSI = ("GEO PSI product catalog + GEOQ 177 public specification table "
+           "(Quartzdyne sensor), geopsi.com/products/downhole-gauges/, fetched 2026-08-23")
+_CHAMPIONX = ("ChampionX Quartzdyne performance page, championx.com, fetched 2026-08-23: "
+              "quartz drift predictable/compensatable; piezoresistive drift unpredictable, "
+              "increases exponentially with temperature")
+
+TOOL_LIBRARY: Dict[str, ToolSpec] = {
+    'quartz_pt_program_geoq177_30k': ToolSpec(
+        name='quartz_pt_program_geoq177_30k', tool_class=QUARTZ_PT,
+        source=_GEOPSI + "; GEA-conditioned leg (canonical suppression, PAPER_2256)",
+        measures=('pressure_psi', 'temperature_F'),
+        telemetry_interface='PSK downhole telemetry -> Modbus RS485 + 4-20mA via G6 interface card (GEOQ 177 spec table)',
+        temp_rating_C=177.0, pressure_rating_psi=30000.0,
+        gauge_spec=GAUGE_SPECS['geoq177_30k'], drift_model='quartz_program'),
+    'quartz_pt_conventional_geoq177_30k': ToolSpec(
+        name='quartz_pt_conventional_geoq177_30k', tool_class=QUARTZ_PT,
+        source=_GEOPSI + "; conventional reference leg (no GEA suppression)",
+        measures=('pressure_psi', 'temperature_F'),
+        telemetry_interface='PSK downhole telemetry -> Modbus RS485 + 4-20mA via G6 interface card (GEOQ 177 spec table)',
+        temp_rating_C=177.0, pressure_rating_psi=30000.0,
+        gauge_spec=GAUGE_SPECS['geoq177_30k'], drift_model='quartz_conventional'),
+    'quartz_pt_template_stressed': ToolSpec(
+        name='quartz_pt_template_stressed', tool_class=QUARTZ_PT,
+        source="22Aug2026 template thread (grok_cce7a73b): stressed-service quartz class, 0.215 %FS/yr baseline",
+        measures=('pressure_psi', 'temperature_F'),
+        telemetry_interface='per-site (template does not specify)',
+        temp_rating_C=200.0, pressure_rating_psi=30000.0,
+        gauge_spec=GAUGE_SPECS['template_generic'], drift_model='quartz_program'),
+    'piezoresistive_pt_class': ToolSpec(
+        name='piezoresistive_pt_class', tool_class=PIEZO_PT,
+        source=_CHAMPIONX + "; GEO PSI GEOP family existence (product catalog). "
+               "Model coefficients are a representative engineering fit, DISCLOSED, not vendor data.",
+        measures=('pressure_psi', 'temperature_F'),
+        telemetry_interface='per-site (GEOP family: downhole telemetry via TEC, surface via interface card)',
+        temp_rating_C=150.0,
+        drift_model='piezoresistive',
+        params={'base_drift_pct_fs_yr': 0.1, 'ref_temp_C': 25.0, 'e_fold_C': 40.0},
+        notes="cited FORM (exponential-in-T, unpredictable); representative coefficients"),
+    'vibrating_wire_geovw250': ToolSpec(
+        name='vibrating_wire_geovw250', tool_class=VIBRATING_WIRE,
+        source="GEO PSI GEOVW 250 product listing (existence + class), geopsi.com product catalog, "
+               "fetched 2026-08-23. Quantitative specs NOT published on the fetched page.",
+        measures=('pressure_psi',),
+        telemetry_interface='per-site (vibrating-wire frequency readout)',
+        spec_status=PARAMETERS_USER_SUPPLIED,
+        notes="user must supply datasheet parameters before this tool can be simulated"),
+    'thermocouple_string_geoxtr18': ToolSpec(
+        name='thermocouple_string_geoxtr18', tool_class=THERMOCOUPLE,
+        source="GEO PSI GEOXTR 18pt Thermocouple Input Card product listing (existence + 18-point class), "
+               "geopsi.com product catalog, fetched 2026-08-23. Per-point specs NOT published on the fetched page.",
+        measures=('temperature_F',) * 1,
+        telemetry_interface='GEOXTR 18pt thermocouple input card',
+        spec_status=PARAMETERS_USER_SUPPLIED,
+        params={'points': 18},
+        notes="18 temperature points along the string; user supplies accuracy/drift from datasheet"),
+    'fiber_dts_geopulse': ToolSpec(
+        name='fiber_dts_geopulse', tool_class=FIBER_DTS,
+        source="GEO PSI GEOPulse fiber-optics product family (existence + DAS/DTS class), "
+               "geopsi.com, fetched 2026-08-23. Spatial/thermal resolution NOT published on the fetched page.",
+        measures=('temperature_profile',),
+        telemetry_interface='fiber-optic interrogator (GEOPulse surface unit)',
+        spec_status=PARAMETERS_USER_SUPPLIED,
+        notes="distributed temperature along the whole bore; user supplies interrogator specs"),
+    'surface_interface_g6': ToolSpec(
+        name='surface_interface_g6', tool_class=SURFACE_INTERFACE,
+        source="GEO PSI GEOQ 177 spec table footnote (1): surface communications Modbus RS485 and "
+               "4-20mA output via G6 Interface Card; up to 10 sensors per TEC line (footnote 2). Fetched 2026-08-23.",
+        measures=(),
+        telemetry_interface='Modbus RS485 + 4-20mA analog out; PSK downhole side',
+        notes="THE PORT TARGET: the live-stream plug-in layer will speak this interface"),
+}
+
+
+# ---------------------------------------------------------------------------
+# Toolstring: composition + rating checks
+# ---------------------------------------------------------------------------
+@dataclass
+class ToolString:
+    """A composed string: (md_ft, tool_name) stations, validated against the
+    library. This is the object the reconciler will hang live streams on."""
+    stations: List[Tuple[float, str]]
+    name: str = "toolstring"
+
+    def __post_init__(self):
+        for md, tn in self.stations:
+            if tn not in TOOL_LIBRARY:
+                raise KeyError(f"unknown tool '{tn}' - not in TOOL_LIBRARY")
+
+    def summary(self) -> dict:
+        by_class: Dict[str, int] = {}
+        for _, tn in self.stations:
+            c = TOOL_LIBRARY[tn].tool_class
+            by_class[c] = by_class.get(c, 0) + 1
+        return {'name': self.name, 'stations': len(self.stations), 'by_class': by_class,
+                'interfaces': sorted({TOOL_LIBRARY[tn].telemetry_interface for _, tn in self.stations})}
+
+
+def rating_check(toolstring: ToolString,
+                 profile=None,
+                 deviation=None,
+                 surface_temp_F: float = 75.0,               # anchor: template surface ambient
+                 temp_gradient_F_per_ft: float = 0.018,      # anchor: template geothermal gradient
+                 surface_pressure_psi: float = 14.7,         # anchor: 1 atm
+                 pressure_gradient_psi_per_ft: float = 0.465 # anchor: industry hydrostatic
+                 ) -> List[dict]:
+    """Check every station's tool against the well conditions AT that station
+    (real profile or gradients; MD->TVD deviation honored). A tool over its
+    temperature or pressure rating is flagged - the check that catches a
+    177 C gauge hung in a 233 C kick zone before the well does."""
+    out = []
+    for md, tn in toolstring.stations:
+        tool = TOOL_LIBRARY[tn]
+        tvd = float(deviation.tvd_of(md)) if deviation is not None else float(md)
+        if profile is not None:
+            p_psi, t_F = profile.interp(tvd)
+        else:
+            p_psi = surface_pressure_psi + tvd * pressure_gradient_psi_per_ft
+            t_F = surface_temp_F + tvd * temp_gradient_F_per_ft
+        t_C = (t_F - 32.0) * 5.0 / 9.0
+        over_t = tool.temp_rating_C is not None and t_C > tool.temp_rating_C
+        over_p = tool.pressure_rating_psi is not None and p_psi > tool.pressure_rating_psi
+        out.append({'md_ft': round(float(md), 0), 'tool': tn,
+                    'station_temp_C': round(t_C, 1), 'station_pressure_psi': round(float(p_psi), 0),
+                    'temp_rating_C': tool.temp_rating_C, 'pressure_rating_psi': tool.pressure_rating_psi,
+                    'over_temp_rating': bool(over_t), 'over_pressure_rating': bool(over_p),
+                    'ok': not (over_t or over_p)})
+    return out