gea-program 0.26.0__tar.gz → 0.28.0__tar.gz

{gea_program-0.26.0/gea_program.egg-info → gea_program-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.26.0
+Version: 0.28.0
 Summary: GEA-Program: downhole gauge monitoring - canonical measurement records, quality rules, drift evaluation with a re-fit change log, well-test validation, alarm management, model cards, store-and-forward, monthly SLA measurement, FAT/SAT protocols and a dashboard, generated from live objects in the client's reporting outline.
 Author: Daniel T. Murphy
 License: MPL-2.0
@@ -125,7 +125,7 @@ gea dashboard --catalog-well volve_f12_f14_production_excerpt:15/9-F-12:10000 --
 gea client-report --report accuracy --out client_report
 gea model-cards --out model_cards
 gea sbom --out sbom
-gea accept                     # the product gate (365 checks)
+gea accept                     # the product gate (368 checks)
 gea help drift                 # the help library, by the job (16 pages; the same text is on every dashboard page)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")
@@ -648,6 +648,30 @@ against it; `gea seedlink --config ... --hello` prints what a server says of
 itself; `gea help seedlink`. A TexNet station is served by EarthScope at
 `rtserve.iris.washington.edu:18000`, network `TX`.
 
+### Tools and ports
+
+The Tools & ports tab (`#/tools`, `gea tools`) is the program's two
+registers in one place: the tool library - every downhole and surface tool
+with its source citation, ratings, what it measures, the telemetry interface
+it declares and its datasheet aging rate where the vendor published one -
+and the ports, the file formats read and the eleven live protocols spoken,
+each with what it speaks to, what the site must supply and what to rehearse
+against. Tools whose declared interface no port in this build speaks are
+listed by name. The rating check hangs a tool string in a well and reports
+each station's tool against the conditions there, with the basis stated:
+`gea tools --rating --station 16000:quartz_pt_geoq177_16k` exits 1 when a
+station is over a rating. `gea help tools`.
+
+### ComCat
+
+The seismicity response plan reads a TexNet export; it reads the FDSN text
+export of USGS ComCat - or any FDSN event service - the same way, with the
+contributor and magnitude type on every event. `gea comcat --lat --lon
+--radius-km --start --end` prints the query to open; `gea comcat --file`
+reads the answer; `sra-report --catalog` takes it. Proven on two verbatim
+public-domain extracts (the Delaware Basin, September 2026; the 2011
+Youngstown sequence with its M 4.0), kept as fixtures with their provenance.
+
 ### Slip tendency on the mapped faults
 
 The stress state the site declares - the three gradients and the ambient

{gea_program-0.26.0 → gea_program-0.28.0}/README.md

@@ -86,7 +86,7 @@ gea dashboard --catalog-well volve_f12_f14_production_excerpt:15/9-F-12:10000 --
 gea client-report --report accuracy --out client_report
 gea model-cards --out model_cards
 gea sbom --out sbom
-gea accept                     # the product gate (365 checks)
+gea accept                     # the product gate (368 checks)
 gea help drift                 # the help library, by the job (16 pages; the same text is on every dashboard page)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")
@@ -609,6 +609,30 @@ against it; `gea seedlink --config ... --hello` prints what a server says of
 itself; `gea help seedlink`. A TexNet station is served by EarthScope at
 `rtserve.iris.washington.edu:18000`, network `TX`.
 
+### Tools and ports
+
+The Tools & ports tab (`#/tools`, `gea tools`) is the program's two
+registers in one place: the tool library - every downhole and surface tool
+with its source citation, ratings, what it measures, the telemetry interface
+it declares and its datasheet aging rate where the vendor published one -
+and the ports, the file formats read and the eleven live protocols spoken,
+each with what it speaks to, what the site must supply and what to rehearse
+against. Tools whose declared interface no port in this build speaks are
+listed by name. The rating check hangs a tool string in a well and reports
+each station's tool against the conditions there, with the basis stated:
+`gea tools --rating --station 16000:quartz_pt_geoq177_16k` exits 1 when a
+station is over a rating. `gea help tools`.
+
+### ComCat
+
+The seismicity response plan reads a TexNet export; it reads the FDSN text
+export of USGS ComCat - or any FDSN event service - the same way, with the
+contributor and magnitude type on every event. `gea comcat --lat --lon
+--radius-km --start --end` prints the query to open; `gea comcat --file`
+reads the answer; `sra-report --catalog` takes it. Proven on two verbatim
+public-domain extracts (the Delaware Basin, September 2026; the 2011
+Youngstown sequence with its M 4.0), kept as fixtures with their provenance.
+
 ### Slip tendency on the mapped faults
 
 The stress state the site declares - the three gradients and the ambient

{gea_program-0.26.0 → gea_program-0.28.0}/gea/__init__.py

@@ -123,7 +123,7 @@ from .profile_catalog import (
     read_pangaea_txt,
 )
 
-__version__ = "0.26.0"
+__version__ = "0.28.0"
 __all__ = [
     "aging_rate", "rate_psi_yr", "accuracy_psi",
     "Sensor", "SimulatorConfig", "DownholeEngine",

{gea_program-0.26.0 → gea_program-0.28.0}/gea/__main__.py

@@ -278,6 +278,18 @@ def main(argv=None) -> int:
         p_lp.add_argument("--stream-csv", type=str, default=None, help="also write a historian-style CSV the other commands ingest")
         p_lp.add_argument("--selftest", action="store_true", help="etp: the codec round-trip and a session against the simulated store on the loopback")
 
+    p_tl = sub.add_parser("tools", help="the tool library and the port registry: every tool with its citation, ratings and the interface it declares; every file format and live protocol; --rating checks a tool string")
+    p_tl.add_argument("--json", action="store_true")
+    p_tl.add_argument("--list", action="store_true", help="just the tool names")
+    p_tl.add_argument("--rating", action="store_true", help="check a tool string: --station <md_ft>:<tool> (repeatable)")
+    p_tl.add_argument("--station", type=str, action="append", default=None, help="a station as <measured depth in feet>:<tool name>")
+    p_tl.add_argument("--surface-temp-f", type=float, default=75.0); p_tl.add_argument("--temp-gradient-f-ft", type=float, default=0.018)
+    p_tl.add_argument("--surface-pressure-psi", type=float, default=14.7); p_tl.add_argument("--pressure-gradient-psi-ft", type=float, default=0.465)
+    p_cc = sub.add_parser("comcat", help="USGS ComCat / any FDSN event service: --lat --lon --radius-km --start --end prints the text-format query to open; --file reads the export it returns")
+    p_cc.add_argument("--lat", type=float, default=None); p_cc.add_argument("--lon", type=float, default=None); p_cc.add_argument("--radius-km", type=float, default=25.0)
+    p_cc.add_argument("--start", type=str, default=None); p_cc.add_argument("--end", type=str, default=None); p_cc.add_argument("--min-mag", type=float, default=1.0)
+    p_cc.add_argument("--file", type=str, default=None, help="an FDSN text export to read and summarise")
+    p_cc.add_argument("--json", action="store_true")
     p_sl = sub.add_parser("slip", help="slip tendency on the mapped faults of a layer at a position, from declared gradients: --layer --lat --lon --depth-ft --sv --shmin --shmax (--shmax-azimuth or --wsm)")
     p_sl.add_argument("--layer", type=str, required=True); p_sl.add_argument("--member", type=str, default=None); p_sl.add_argument("--feature-kind", type=str, choices=["fault", "fold"], default=None)
     p_sl.add_argument("--lat", type=float, required=True); p_sl.add_argument("--lon", type=float, required=True); p_sl.add_argument("--radius-km", type=float, default=25.0)
@@ -2351,6 +2363,66 @@ def main(argv=None) -> int:
             stop.set()
             print("etp-sim: stopped")
         return 0
+    elif a.cmd == "tools":
+        import json as _json
+        from . import tool_catalog as _TC
+        if a.rating or a.station:
+            stations = []
+            for spec in (a.station or []):
+                if ":" not in spec:
+                    raise SystemExit(f"--station takes <measured depth in feet>:<tool name>, got {spec!r}")
+                md, _, nm = spec.partition(":")
+                try:
+                    stations.append((float(md), nm.strip()))
+                except ValueError:
+                    raise SystemExit(f"--station depth is not a number: {md!r}")
+            try:
+                r = _TC.check_string(stations, surface_temp_F=a.surface_temp_f, temp_gradient_F_per_ft=a.temp_gradient_f_ft,
+                                     surface_pressure_psi=a.surface_pressure_psi, pressure_gradient_psi_per_ft=a.pressure_gradient_psi_ft)
+            except ValueError as e:
+                raise SystemExit(f"tools: {e}")
+            if a.json:
+                print(_json.dumps(r, indent=1)); return 0 if not r["n_over_rating"] else 1
+            for line in r["lines"]:
+                print(line)
+            return 0 if not r["n_over_rating"] else 1
+        if a.list:
+            for t in _TC.tools():
+                print(t["name"])
+            return 0
+        if a.json:
+            print(_json.dumps(_TC.catalog(), indent=1)); return 0
+        print(_TC.text())
+        return 0
+    elif a.cmd == "comcat":
+        import json as _json
+        from . import sra as _SR
+        from . import geodesy as _GD
+        if a.file:
+            c = _SR.read_catalog(a.file)
+            if c.get("format") != "fdsn-text":
+                print(f"comcat: {a.file} is not an FDSN text export (it read as a {c.get('basis', '')[:60]}...)"); return 1
+            ev = c["events"]
+            if a.lat is not None and a.lon is not None:
+                for e in ev:
+                    dm = _GD.geodesic_m(a.lat, a.lon, e["lat"], e["lon"])["distance_m"]
+                    e["distance_km"] = round(dm / 1000.0, 2) if dm is not None else None
+            if a.json:
+                print(_json.dumps(c, indent=1, default=str)); return 0
+            big = max(ev, key=lambda e: e["magnitude"]) if ev else None
+            ts = sorted(e["time"] for e in ev)
+            print(f"comcat: {c['n_events']} event(s) ({c['n_skipped']} skipped) from {ts[0][:10] if ts else '-'} to {ts[-1][:10] if ts else '-'}; "
+                  f"contributors {', '.join(c['contributors'])}; magnitude types {', '.join(c['magnitude_types'])}")
+            if big:
+                print(f"  largest: M {big['magnitude']:.1f} {big['mag_type']} {big['time']} at {big['lat']:.4f}, {big['lon']:.4f}, {big['depth_km']} km - {big['place']} ({big['event_id']})")
+            for e in sorted(ev, key=lambda x: x["time"])[:40]:
+                print(f"  {e['time'][:19]}  M {e['magnitude']:>4.1f} {e['mag_type']:<6s} {e['lat']:9.4f} {e['lon']:10.4f} {str(e['depth_km']):>7s} km " + (f"{e['distance_km']:7.2f} km  " if e.get("distance_km") is not None else "") + f"{e['place']}")
+            return 0
+        if a.lat is None or a.lon is None or not a.start or not a.end:
+            raise SystemExit("comcat needs --lat --lon --start --end (--radius-km, --min-mag), or --file <export>")
+        print(_SR.comcat_url(a.lat, a.lon, a.radius_km, a.start, a.end, a.min_mag))
+        print("  open it in a browser (this machine may not reach the service) and save the text it returns; `gea comcat --file <saved>` reads it, and sra-report --catalog takes it.")
+        return 0
     elif a.cmd == "slip":
         import json as _json
         from . import shapefile as _SF, slip as _SL, friction_priors as _FP

{gea_program-0.26.0 → gea_program-0.28.0}/gea/acceptance_tests.py

@@ -7274,6 +7274,161 @@ def section_bt_slip(tmp: str) -> None:
        + (f" [failed: {', '.join(failed3)}]" if failed3 else ""))
 
 
+def section_bu_comcat(tmp: str) -> None:
+    """Section BU - the USGS ComCat / FDSN text export read as a catalogue, proven on two verbatim public-domain
+    extracts kept as fixtures (the Delaware Basin, September 2026; the Youngstown 2011 sequence); the SRA seismicity
+    on the real Youngstown sequence; the query builder; the CLI."""
+    import subprocess as _sp
+    from . import sra as SR
+    from . import geodesy as GD
+    pkg = Path(__file__).parent
+    d = Path(tmp, "bu"); d.mkdir()
+    fx = pkg / "fixtures"
+    de = SR.read_catalog(str(fx / "comcat_delaware_basin_2026-09.txt"))
+    yo = SR.read_catalog(str(fx / "comcat_youngstown_2011-2012.txt"))
+    big = max(yo["events"], key=lambda e: e["magnitude"])
+    url = SR.comcat_url(41.1, -80.68, 25.0, "2011-03-01", "2012-03-01", 1.5)
+    # the Youngstown sequence against an SRA-shaped area around the Northstar 1 site: 10 km, M 2.0 threshold, plan date 2011-12-01
+    sra = SR.define("Youngstown", 41.12, -80.69, 10.0, "2011-12-01", threshold_m=2.0, formation_boundary="base of the Knox")
+    from datetime import datetime as _dt, timezone as _tz
+    se = SR.seismicity(sra, yo, as_of=_dt(2012, 2, 1, tzinfo=_tz.utc))
+    far = next(e for e in yo["events"] if e["event_id"] == "ld60004308")
+    dist_far = GD.geodesic_m(41.12, -80.69, far["lat"], far["lon"])["distance_m"] / 1000.0
+    r_file = _sp.run([sys.executable, "-m", "gea", "comcat", "--file", str(fx / "comcat_youngstown_2011-2012.txt"), "--lat", "41.1", "--lon", "-80.68"], capture_output=True, text=True)
+    r_url = _sp.run([sys.executable, "-m", "gea", "comcat", "--lat", "31.42", "--lon", "-103.5", "--radius-km", "30", "--start", "2026-09-01", "--end", "2026-10-01", "--min-mag", "2.5"], capture_output=True, text=True)
+    r_bad = _sp.run([sys.executable, "-m", "gea", "comcat", "--file", str(pkg / "catalog" / "collingwood_1_28_ks_complete.las")], capture_output=True, text=True)
+    help_md = (pkg / "help" / "sra.md").read_text(encoding="utf-8")
+    c1 = {
+        "delaware": de["format"] == "fdsn-text" and de["n_events"] == 28 and de["n_skipped"] == 0 and de["contributors"] == ["tx", "us"] and de["magnitude_types"] == ["mb_lg", "ml"]
+                    and max(e["magnitude"] for e in de["events"]) == 3.4 and de["events"][0]["event_id"] == "tx2026tgiogl" and de["events"][0]["time"] == "2026-09-30T13:35:58Z"
+                    and de["events"][0]["depth_km"] == 6.2024 and "mixes scales" in de["basis"] and sum(1 for e in de["events"] if e["contributor"] == "us") == 4,
+        "youngstown": yo["n_events"] == 9 and big["event_id"] == "ld60029101" and big["magnitude"] == 4.0 and big["time"] == "2011-12-31T20:05:01Z" and big["lat"] == 41.1215 and big["lon"] == -80.6843333
+                      and big["place"] == "3 km NW of Youngstown, Ohio" and yo["contributors"] == ["ld"],
+        "seismicity": se["n_inside"] == 9 and se["largest"]["event_id"] == "ld60029101" and se["largest"]["magnitude"] == 4.0 and se["n_at_or_above"] == 6 and dist_far < 10.0
+                      and se["trigger"]["status"] == "TRIGGERED" and se["trigger"]["respond_by"] == "2012-01-02T20:05:01Z" and se["goal"]["clock_started"] == "2011-12-31",
+        "url": url == "https://earthquake.usgs.gov/fdsnws/event/1/query?format=text&starttime=2011-03-01&endtime=2012-03-01&latitude=41.1000&longitude=-80.6800&maxradiuskm=25&minmagnitude=1.5&orderby=time-asc",
+        "cli": r_file.returncode == 0 and "largest: M 4.0 ml 2011-12-31T20:05:01Z at 41.1215, -80.6843" in r_file.stdout and "1.68 km" in r_file.stdout
+               and r_url.returncode == 0 and "maxradiuskm=30&minmagnitude=2.5" in r_url.stdout and r_bad.returncode == 1 and "not an FDSN text export" in r_bad.stdout,
+        "help_and_fixtures": "gea comcat" in help_md and (fx / "README.md").read_text(encoding="utf-8").count("earthquake.usgs.gov/fdsnws/event/1/query") == 2,
+    }
+    failed1 = [k for k, v in c1.items() if not v]
+    ok(not failed1,
+       "BU1 the FDSN text export read as a catalogue with contributors and magnitude types: the Delaware Basin window of September 2026 (28 events, TexNet "
+       "and NEIC, ML and mb_Lg, largest M 3.4) and the Youngstown 2011 sequence (9 events, the M 4.0 of 2011-12-31 3 km NW of Youngstown); the SRA seismicity "
+       "on the real sequence inside a 10 km area (six at or above M 2.0, the M 4.0 TRIGGERED, the goal clock from 2011-12-31); the query builder; `gea comcat --file` with distances and `--lat --lon --start --end` printing the query; "
+       "a LAS refused; the help and the fixtures' provenance"
+       + (f" [failed: {', '.join(failed1)}]" if failed1 else ""))
+
+
+def section_bv_tools(tmp: str) -> None:
+    """Section BV - the tool library and the port registry as one register: every tool with its citation, ratings,
+    declared interface and published aging rate (or the reason there is none); every file format and live protocol
+    with what the site must supply; the tools no port speaks named; the rating check; the API, the page, the CLI, the help."""
+    import http.cookiejar
+    import subprocess as _sp
+    import urllib.request
+    import urllib.error
+    from . import tool_catalog as TC
+    from . import helplib as H
+    from .ports import PORT_REGISTRY
+    from .tool_library import PARAMETERS_USER_SUPPLIED, TOOL_LIBRARY
+    from .telemetry import TelemetryRecorder, TelemetryConfig
+    from .downhole_engine import DownholeEngine, SimulatorConfig
+    from .workspace import Workspace
+    from .service import Service, Users
+    pkg = Path(__file__).parent
+    d = Path(tmp, "bv"); d.mkdir()
+
+    c = TC.catalog()
+    by = {t["name"]: t for t in c["tools"]}
+    q30, piezo, g6 = by["quartz_pt_geoq177_30k"], by["piezoresistive_pt_class"], by["surface_interface_g6"]
+    rate = TC.check_string([(500.0, "quartz_pt_geoq177_30k"), (16000.0, "quartz_pt_geoq177_16k")])
+    deep = rate["stations"][1]
+    ok_all = TC.check_string([(500.0, "quartz_pt_geoq177_30k")])
+    bad_tool = empty = None
+    try:
+        TC.check_string([(100.0, "no_such_tool")])
+    except ValueError as e:
+        bad_tool = str(e)
+    try:
+        TC.check_string([])
+    except ValueError as e:
+        empty = str(e)
+    c1 = {
+        "tools": c["counts"]["tools"] == len(TOOL_LIBRARY) and c["counts"]["fully_specified"] + c["counts"]["user_supplied"] == len(TOOL_LIBRARY)
+                 and all(t["source"] for t in c["tools"]) and q30["aging_rate_pct_fs_yr"] is not None and q30["aging_note"].startswith("the datasheet")
+                 and q30["temp_rating_C"] == 177.0 and q30["pressure_rating_psi"] == 30000.0 and q30["gauge_spec"]["full_scale_psi"] == 30000.0,
+        "user_supplied_named": piezo["spec_status"] == PARAMETERS_USER_SUPPLIED and piezo["aging_rate_pct_fs_yr"] is None
+                               and "does not invent vendor numbers" in piezo["aging_note"] and g6["measures"] == [],
+        "ports": c["counts"]["file_ports"] == len(PORT_REGISTRY) and {p["name"] for p in c["ports"]["live"]} >= {"wits0", "witsml", "etp", "opcua", "mqtt", "modbus_g6", "modbus_rtu", "dnp3", "hartip", "piwebapi", "seedlink"}
+                 and all(p["needs"] and p["speaks"] and p["rehearse"] for p in c["ports"]["live"]) and any(p["status"] == "IMPLEMENTED" for p in c["ports"]["files"])
+                 and any(p["name"] == "dlis" for p in c["ports"]["files"]),
+        "interfaces": "modbus_rtu" in q30["ports"] and not piezo["ports"] and {u["tool"] for u in c["unmatched"]} == {t["name"] for t in c["tools"] if not t["ports"]}
+                      and "piezoresistive_pt_class" in {u["tool"] for u in c["unmatched"]},
+        "rating": rate["n_over_rating"] == 1 and deep["over_temp_rating"] and not deep["over_pressure_rating"] and abs(deep["station_temp_C"] - 183.9) < 0.2
+                  and "OVER its 177 C rating" in rate["lines"][2] and "declared gradients" in rate["basis"] and "no survey given" in rate["deviation"]
+                  and ok_all["n_over_rating"] == 0 and bad_tool and "not in the tool library" in bad_tool and empty and "at least one station" in empty,
+    }
+    failed1 = [k for k, v in c1.items() if not v]
+    ok(not failed1,
+       f"BV1 the register: all {len(TOOL_LIBRARY)} tools with their citations, the quartz gauge's datasheet aging rate and ratings, the piezoresistive "
+       "class carrying no rate and saying why, the interface card measuring nothing; every file port of the registry and all eleven live protocols with "
+       "what each needs from the site and what to rehearse against; the tools no port in this build speaks named; the rating check flagging a 177 C gauge "
+       "at 16,000 ft and clearing a shallow one, an unknown tool and an empty string refused"
+       + (f" [failed: {', '.join(failed1)}]" if failed1 else ""))
+
+    hist = str(d / "hist.csv")
+    TelemetryRecorder(engine=DownholeEngine(SimulatorConfig()), config=TelemetryConfig(duration_hours=0.5, seed=3)).run().export_csv(hist)
+    wsp = str(d / "ws"); ws = Workspace.create(wsp, "Pad 3", actor="tester")
+    ws.add_well_file(hist, display="SWD 1", actor="tester")
+    users = Users(str(Path(wsp, "users.json"))); users.add("v", "viewer-pass-1", "viewer")
+    svc = Service(wsp, port=0, scheduler=False).start()
+    base_url = svc.url.rstrip("/")
+    opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()))
+
+    def call(method, path, body=None):
+        req = urllib.request.Request(base_url + path, method=method, data=(json.dumps(body).encode() if body is not None else None))
+        req.add_header("Content-Type", "application/json"); req.add_header("X-GEA-Action", "1")
+        try:
+            with opener.open(req, timeout=120) as rr_:
+                return rr_.status, json.loads(rr_.read())
+        except urllib.error.HTTPError as e:
+            return e.code, json.loads(e.read())
+    try:
+        st_anon = call("GET", "/api/tools")[0]
+        call("POST", "/api/login", {"name": "v", "password": "viewer-pass-1"})
+        st_g, got = call("GET", "/api/tools")
+        st_r, rr = call("POST", "/api/tools/rating", {"stations": [{"md_ft": 500, "tool": "quartz_pt_geoq177_30k"}, {"md_ft": 16000, "tool": "quartz_pt_geoq177_16k"}]})
+        st_bad = call("POST", "/api/tools/rating", {"stations": [{"md_ft": 100, "tool": "nope"}]})[0]
+        st_bad2 = call("POST", "/api/tools/rating", {"stations": [{"tool": "quartz_pt_geoq177_30k"}]})[0]
+    finally:
+        svc.stop()
+    page_src = (pkg / "web" / "app.html").read_text(encoding="utf-8")
+    help_md = (pkg / "help" / "tools.md").read_text(encoding="utf-8")
+    r_txt = _sp.run([sys.executable, "-m", "gea", "tools"], capture_output=True, text=True)
+    r_list = _sp.run([sys.executable, "-m", "gea", "tools", "--list"], capture_output=True, text=True)
+    r_json = _sp.run([sys.executable, "-m", "gea", "tools", "--json"], capture_output=True, text=True)
+    r_rate = _sp.run([sys.executable, "-m", "gea", "tools", "--rating", "--station", "500:quartz_pt_geoq177_30k", "--station", "16000:quartz_pt_geoq177_16k"], capture_output=True, text=True)
+    r_badst = _sp.run([sys.executable, "-m", "gea", "tools", "--rating", "--station", "500"], capture_output=True, text=True)
+    c2 = {
+        "api": st_anon == 401 and st_g == 200 and got["counts"]["tools"] == len(TOOL_LIBRARY) and st_r == 200 and rr["n_over_rating"] == 1
+               and rr["stations"][1]["over_temp_rating"] and st_bad == 400 and st_bad2 == 400,
+        "page": "VIEWS.tools" in page_src and "'#/tools', 'Tools & ports'" in page_src and "/api/tools/rating" in page_src
+                and "Tools no live port in this build speaks" in page_src and "Rating check" in page_src,
+        "cli": r_txt.returncode == 0 and "file ports:" in r_txt.stdout and "live ports:" in r_txt.stdout and "does not invent vendor numbers" in r_txt.stdout
+               and r_list.returncode == 0 and r_list.stdout.split() == sorted(TOOL_LIBRARY) and r_json.returncode == 0 and json.loads(r_json.stdout)["counts"]["live_ports"] == 11
+               and r_rate.returncode == 1 and "OVER its 177 C rating" in r_rate.stdout and r_badst.returncode != 0 and "<measured depth in feet>:<tool name>" in (r_badst.stderr + r_badst.stdout),
+        "help": any(t["topic"] == "tools" for t in H.topics()) and not H.check("tools") and H.VIEW_TOPIC.get("tools") == "tools"
+                and "not a promise the tool survives" in help_md.split("will not call a measurement")[1],
+    }
+    failed2 = [k for k, v in c2.items() if not v]
+    ok(not failed2,
+       "BV2 the Tools & ports tab: the API refuses an anonymous caller and answers a viewer, runs the rating check and refuses an unknown tool and a "
+       "station with no depth; the page carries the tab, the unmatched-tools table and the rating-check form; `gea tools`, `--list`, `--json` and "
+       "`--rating --station` (exit 1 when a station is over a rating, and a malformed station named); the help page and its view mapping"
+       + (f" [failed: {', '.join(failed2)}]" if failed2 else ""))
+
+
 def main() -> int:
     print("GEA-Program - ACCEPTANCE SUITE (the product gate)")
     # a handle a job subprocess still holds at the end must not turn a finished gate into a traceback on Windows:
@@ -7349,6 +7504,8 @@ def main() -> int:
         section_br_logs_historian(tmp)
         section_bs_catalog(tmp)
         section_bt_slip(tmp)
+        section_bu_comcat(tmp)
+        section_bv_tools(tmp)
     if _FAILS:
         print(f"[ACCEPTANCE] {len(_FAILS)} FAILURES ({_PASS} passed):")
         for f in _FAILS:

gea_program-0.28.0/gea/fixtures/README.md

@@ -0,0 +1,10 @@
+# fixtures
+
+Small, verbatim, public-domain extracts kept so the gate can prove a reader on real records without a network.
+
+- `comcat_delaware_basin_2026-09.txt` - USGS ComCat, FDSN event web service text output, fetched 2026-10-12:
+  `https://earthquake.usgs.gov/fdsnws/event/1/query?format=text&starttime=2026-09-01&endtime=2026-10-01&minlatitude=30.5&maxlatitude=32.5&minlongitude=-104.5&maxlongitude=-102.0&minmagnitude=2.5&orderby=time`
+  (28 events M >= 2.5, Delaware and Midland basins; contributors tx = TexNet, us = NEIC). US Government work, public domain.
+- `comcat_youngstown_2011-2012.txt` - the same service, fetched 2026-10-12:
+  `https://earthquake.usgs.gov/fdsnws/event/1/query?format=text&starttime=2011-03-01&endtime=2012-03-01&latitude=41.1&longitude=-80.68&maxradiuskm=25&minmagnitude=1.5&orderby=time-asc`
+  (9 events within 25 km of Youngstown, Ohio: the 2011 sequence that ended with the M 4.0 of 2011-12-31; contributor ld = Lamont-Doherty). Public domain.

gea_program-0.28.0/gea/fixtures/comcat_delaware_basin_2026-09.txt

@@ -0,0 +1,29 @@
+#EventID|Time|Latitude|Longitude|Depth/km|Author|Catalog|Contributor|ContributorID|MagType|Magnitude|MagAuthor|EventLocationName
+tx2026tgiogl|2026-09-30T13:35:58.370|31.618|-104.363|6.2024|tx|tx|tx|tx2026tgiogl|ml|2.9|tx|61 km S of Whites City, New Mexico
+tx2026tfzcgy|2026-09-30T08:50:13.448|31.624|-104.364|6.9714|tx|tx|tx|tx2026tfzcgy|ml|3.3|tx|61 km S of Whites City, New Mexico
+tx2026tbppja|2026-09-27T23:45:52.397|31.617|-104.312|8.4583|tx|tx|tx|tx2026tbppja|ml|2.5|tx|59 km NW of Toyah, Texas
+tx2026sxmsve|2026-09-25T18:01:21.042|31.379|-103.705|6.228|tx|tx|tx|tx2026sxmsve|ml|2.6|tx|11 km NE of Toyah, Texas
+tx2026svkhwu|2026-09-24T14:39:26.649|30.831|-103.394|3.3569|tx|tx|tx|tx2026svkhwu|ml|2.9|tx|37 km ESE of Balmorhea, Texas
+tx2026ssvrgl|2026-09-23T05:08:42.441|32.401|-102.046|7.1533|tx|tx|tx|tx2026ssvrgl|ml|3|tx|34 km WSW of Ackerly, Texas
+tx2026sspzfy|2026-09-23T02:16:59.235|32.436|-102.098|6.958|tx|tx|tx|tx2026sspzfy|ml|2.8|tx|35 km SSW of Los Ybanez, Texas
+tx2026srxfgq|2026-09-22T16:50:40.191|31.668|-104.402|6.0999|tx|tx|tx|tx2026srxfgq|ml|2.6|tx|56 km S of Whites City, New Mexico
+tx2026srvtwi|2026-09-22T16:07:21.955|31.605|-103.933|7.7533|tx|tx|tx|tx2026srvtwi|ml|2.5|tx|33 km WSW of Mentone, Texas
+tx2026srfrih|2026-09-22T08:04:38.331|31.666|-104.25|6.0999|tx|tx|tx|tx2026srfrih|ml|3.1|tx|57 km SSE of Whites City, New Mexico
+us7000tisq|2026-09-20T19:23:14.330|32.2823|-103.7703|7.6|us|us|us|us7000tisq|mb_lg|2.9|us|29 km ENE of Malaga, New Mexico
+tx2026sngzur|2026-09-20T04:23:40.180|31.668|-104.362|7.1765|tx|tx|tx|tx2026sngzur|ml|3.2|tx|56 km S of Whites City, New Mexico
+tx2026sipbbo|2026-09-17T15:04:16.188|32.074|-103.679|7.7533|tx|tx|tx|tx2026sipbbo|ml|2.7|tx|40 km ESE of Malaga, New Mexico
+tx2026siects|2026-09-17T09:34:33.358|31.665|-104.453|6.0999|tx|tx|tx|tx2026siects|ml|2.5|tx|57 km S of Whites City, New Mexico
+tx2026sfaiyw|2026-09-15T16:27:44.534|31.615|-104.113|6.0999|tx|tx|tx|tx2026sfaiyw|ml|2.6|tx|45 km NW of Toyah, Texas
+tx2026selaoc|2026-09-15T08:48:29.775|31.657|-104.135|6.1127|tx|tx|tx|tx2026selaoc|ml|3.3|tx|49 km NW of Toyah, Texas
+tx2026sawssd|2026-09-13T10:20:00.004|31.661|-104.432|6.0999|tx|tx|tx|tx2026sawssd|ml|3.4|tx|57 km S of Whites City, New Mexico
+tx2026sapxnl|2026-09-13T06:54:23.103|31.661|-104.432|6.0999|tx|tx|tx|tx2026sapxnl|ml|2.9|tx|57 km S of Whites City, New Mexico
+tx2026saectr|2026-09-13T00:58:24.306|31.751|-104.336|7.074|tx|tx|tx|tx2026saectr|ml|2.9|tx|47 km S of Whites City, New Mexico
+us7000tgvj|2026-09-12T00:22:12.507|32.2629|-103.2847|7.91|us|us|us|us7000tgvj|mb_lg|2.6|us|18 km NNW of Jal, New Mexico
+tx2026rupmzs|2026-09-10T00:15:33.655|31.64|-104.408|6.3306|tx|tx|tx|tx2026rupmzs|ml|3|tx|59 km S of Whites City, New Mexico
+us7000tg2k|2026-09-09T16:00:21.180|32.3229|-104.4961|3.897|us|us|us|us7000tg2k|ml|2.5|us|19 km NW of Whites City, New Mexico
+tx2026rqcbab|2026-09-07T13:11:15.952|32.005|-103.24|6.0999|tx|tx|tx|tx2026rqcbab|ml|2.7|tx|12 km SSW of Jal, New Mexico
+tx2026roctny|2026-09-06T11:24:04.550|31.542|-104.128|8.8428|tx|tx|tx|tx2026roctny|ml|2.5|tx|40 km NW of Toyah, Texas
+us7000tegw|2026-09-05T03:41:56.500|32.3519|-104.4998|5|us|us|us|us7000tegw|ml|2.7|us|22 km NNW of Whites City, New Mexico
+tx2026rliwah|2026-09-04T23:14:17.831|31.667|-104.37|6.9202|tx|tx|tx|tx2026rliwah|ml|2.5|tx|56 km S of Whites City, New Mexico
+tx2026rjxsxm|2026-09-04T04:35:25.328|31.542|-104.129|8.5095|tx|tx|tx|tx2026rjxsxm|ml|3.1|tx|40 km NW of Toyah, Texas
+tx2026rjmsif|2026-09-03T23:02:00.297|31.656|-104.387|6.0999|tx|tx|tx|tx2026rjmsif|ml|2.5|tx|57 km S of Whites City, New Mexico

gea_program-0.28.0/gea/fixtures/comcat_youngstown_2011-2012.txt

@@ -0,0 +1,10 @@
+#EventID|Time|Latitude|Longitude|Depth/km|Author|Catalog|Contributor|ContributorID|MagType|Magnitude|MagAuthor|EventLocationName
+ld60004308|2011-03-17T10:53:11.670|41.126|-80.6056667|3.54|ld|ld|ld|ld60004308|ml|2.1|ld|2 km WSW of Maplewood Park, Ohio
+ld60007303|2011-08-22T08:00:32.640|41.1303333|-80.7081667|5|ld|ld|ld|ld60007303|ml|1.87|ld|2 km SSW of Girard, Ohio
+ld60009603|2011-09-26T01:06:10.840|41.115|-80.6823333|5|ld|ld|ld|ld60009603|ml|2.12|ld|3 km WNW of Youngstown, Ohio
+ld60009803|2011-09-30T00:52:38.710|41.1346667|-80.6845|5|ld|ld|ld|ld60009803|ml|2.44|ld|2 km SSE of Girard, Ohio
+ld60010908|2011-10-20T22:41:10.820|41.1253333|-80.704|6.39|ld|ld|ld|ld60010908|ml|2.04|ld|3 km S of Girard, Ohio
+ld60012603|2011-11-25T06:47:28.250|41.124|-80.6771667|5|ld|ld|ld|ld60012603|ml|1.79|ld|3 km NW of Youngstown, Ohio
+ld60013703|2011-12-24T06:24:58.810|41.1225|-80.7046667|5|ld|ld|ld|ld60013703|ml|2.37|ld|3 km S of Girard, Ohio
+ld60029101|2011-12-31T20:05:01.060|41.1215|-80.6843333|5|ld|ld|ld|ld60029101|ml|4|ld|3 km NW of Youngstown, Ohio
+ld60014118|2012-01-13T22:29:35.120|41.1245|-80.6923333|5.79|ld|ld|ld|ld60014118|ml|1.74|ld|3 km SSE of Girard, Ohio

{gea_program-0.26.0 → gea_program-0.28.0}/gea/help/sra.md

@@ -8,7 +8,7 @@
 
 **The number to check**: `Response:` in section "Seismicity against the plan" - TRIGGERED names the event, its magnitude and the deadline for the response group's meeting; NOT TRIGGERED names why. `Goal:` gives the days without a threshold event and the date the plan's goal falls on. The packet's front says COMPLETE or INCOMPLETE with the count of gaps.
 
-**What this page will not call a measurement**: which earthquakes are aftershocks - the operator declares them with `--aftershocks` and they are shown as exempt, never decided here. A volume read off a pressure gauge - a well with no rate channel has no volume and no maximum rate, and the packet says NOT RECORDED. A depth tier from depth alone - the tier is stratigraphic, above or below the named formation base, and is declared. The TexNet reporting tool's own upload template - the export carries the Notice's parameter names and the mapping is the operator's step. A catalogue nobody handed in - the catalogue is a file the operator exports from TexNet, and its export date is on the packet.
+**What this page will not call a measurement**: which earthquakes are aftershocks - the operator declares them with `--aftershocks` and they are shown as exempt, never decided here. A volume read off a pressure gauge - a well with no rate channel has no volume and no maximum rate, and the packet says NOT RECORDED. A depth tier from depth alone - the tier is stratigraphic, above or below the named formation base, and is declared. The TexNet reporting tool's own upload template - the export carries the Notice's parameter names and the mapping is the operator's step. A catalogue nobody handed in - the catalogue is a file the operator exports from TexNet, or the FDSN text export of USGS ComCat (`gea comcat --lat --lon --radius-km --start --end` prints the query; the file it returns reads directly, with its contributors and magnitude types on the packet), and its export date is on the packet.
 
 The shape is the Commission's: the operator-led response plans on file (Gardendale, Northern Culberson-Reeves, Stanton) - a circle of about 9 km, a plan written against M 3.5, an 18-month goal, a response group meeting within 48 hours of a threshold event, quarterly checkpoints with Commission staff, and disposal wells in two tiers by the base of the Wolfcamp - and the December 2023 Notice to Operators on disposal-well monitoring and reporting in the Permian Basin, which names the four daily parameters and the three bottomhole-pressure methods. A downhole gauge this program monitors is the Notice's permanent probe.
 

gea_program-0.28.0/gea/help/tools.md

@@ -0,0 +1,11 @@
+# Tools and ports
+
+> What this program knows how to measure with, and what it knows how to speak. The tool library is the downhole and surface tools - each with the citation its numbers came from, the conditions it is rated for, and the telemetry interface it declares; the port registry is the file formats and live protocols that bring a tool's readings in. The page draws the line between them: a tool declares an interface, a port speaks one, and a tool whose interface no port in this build speaks is named rather than hidden.
+
+**The command**: the page is Tools & ports on the dashboard; `gea tools` prints the same register at the command line (`--json` for the machine record, `--rating --station <ft>:<tool> ...` for the rating check). A tool whose vendor published no numbers is listed as PARAMETERS_USER_SUPPLIED: `gea config` takes your own datasheet (`load_gauge_spec_json`) and the tool is then simulated and aged from it. The live protocols each name what the site must supply before they run and what to rehearse against - `gea wits0-sim`, `gea etp-sim`, `gea seedlink-sim`, or the stand-in slave, outstation, device and historian the field ports ship with.
+
+**What it writes**: nothing to the workspace - this page is a register, not a record. It states, per tool: the class, what it measures, the temperature and pressure ratings, the published aging rate in %FS/yr where the datasheet gives one (and the reason there is none where it does not), the interface it declares, the ports that can carry it, and its source. Per port: the transport, the status (IMPLEMENTED, or DECLARED_SITE_DETAILS_REQUIRED with what is missing), and what it speaks to. The rating check returns, per station, the temperature and pressure at that depth, the tool's ratings and whether the station is within them, with the basis of the conditions printed beside the answer.
+
+**The number to check**: the aging rate against your own datasheet before you trust a drift report built on it, and the rating check's per-station temperature against the tool's rating - the check that catches a 177 °C gauge hung in a 233 °C zone before the well does.
+
+**What this page will not call a measurement**: a vendor number nobody published - a tool with no datasheet rate carries none and raises rather than inventing one, and the page says PARAMETERS_USER_SUPPLIED. A rating as a prediction - a station within its ratings is arithmetic on the vendor's number and the declared conditions, not a promise the tool survives. The conditions themselves - without a well profile they are the gradients declared on the page, and the answer prints which basis it used. A port as a connection - a port listed here speaks a protocol; whether the site's own device answers is what the Patch panel shows.

{gea_program-0.26.0 → gea_program-0.28.0}/gea/helplib.py

@@ -42,6 +42,7 @@ INDEX: List[tuple] = [
     ('catalog', 'The catalogue', 'every shipped public dataset, what in this program reads it or that nothing does; the measured friction envelope; the core check; any log through the survey'),
     ('dlis', 'The DLIS log', 'a well log as it is delivered (API RP66 V1), read as the standard lays it out: the frames, the channels, what was skipped; into the strata survey'),
     ('historian', 'The historian pull', 'an operator\'s gauge history out of the PI System through PI Web API, read-only, every value with its archive time and flags'),
+    ('tools', 'Tools and ports', 'the downhole and surface tools this program knows, each with its citation and ratings, the formats and protocols that bring their readings in, and the rating check on a tool string'),
     ('field-ports', 'The field ports', 'Modbus RTU on the serial line, DNP3 from the pad RTU, HART-IP from the transmitter itself - read-only, polled, with the stand-ins to rehearse against'),
     ('slip', 'Slip tendency on the mapped faults', 'the declared stress state resolved on each mapped fault around a well: the slip tendency, the pressure to slip, the World Stress Map as the SHmax source, the published Hennings values beside'),
     ('interval', 'The interval against the mapped tops', 'the declared disposal interval, subsea, beside each formation-top bracket; the depth tier against the mapped base; the catalogue events against the mapped faults'),
@@ -66,7 +67,7 @@ REQUIRED_LINES = ('**The command**', '**What it writes**', '**The number to chec
 VIEW_TOPIC: Dict[str, str] = {
     'home': 'start', 'wells': 'data-in', 'well': 'drift', 'live': 'patches', 'patch': 'patches', 'files': 'files', 'alarms': 'alarms',
     'approvals': 'well-tests', 'config': 'site', 'reports': 'drift', 'verify': 'start', 'survey': 'data-in', 'jobs': 'site',
-    'admin': 'site', 'prefs': 'site', 'search': 'start', 'welcome': 'start', 'seismic': 'seismic', 'seismic_station': 'seismic', 'track': 'seismic', 'sar': 'seismic', 'sites': 'sites', 'audit': 'audit-update',
+    'admin': 'site', 'prefs': 'site', 'search': 'start', 'welcome': 'start', 'seismic': 'seismic', 'seismic_station': 'seismic', 'track': 'seismic', 'sar': 'seismic', 'sites': 'sites', 'audit': 'audit-update', 'tools': 'tools',
 }
 
 

{gea_program-0.26.0 → gea_program-0.28.0}/gea/service.py

@@ -1637,6 +1637,9 @@ def make_handler(app: App):
                         raise ApiError(404, str(e))
                 if path == '/api/stress':
                     return self._json(200, {'stress': app.ws.stress(), 'stress_map': app.ws.stress_map()})
+                if path == '/api/tools':
+                    from . import tool_catalog as _TC
+                    return self._json(200, _TC.catalog())
                 if path == '/api/stress/wsm':
                     try:
                         lat, lon = float(qs['lat'][0]), float(qs['lon'][0]); rad = float(qs.get('radius_km', ['100'])[0])
@@ -1839,6 +1842,22 @@ def make_handler(app: App):
                                                                 depth_ft=(float(b['depth_ft']) if b.get('depth_ft') is not None else None), actor=user['name']))
                     except WorkspaceError as e:
                         raise ApiError(404, str(e))
+                if path == '/api/tools/rating':
+                    from . import tool_catalog as _TC
+                    b = body or {}
+                    try:
+                        stations = [(float(x['md_ft']), str(x['tool'])) for x in (b.get('stations') or [])]
+                    except (KeyError, TypeError, ValueError):
+                        raise ApiError(400, 'each station needs md_ft and tool')
+                    try:                                        # the conditions are the declared gradients, and the answer says so
+                        return self._json(200, _TC.check_string(stations, profile=None, deviation=None,
+                                                                surface_temp_F=float(b.get('surface_temp_F', 75.0)),
+                                                                temp_gradient_F_per_ft=float(b.get('temp_gradient_F_per_ft', 0.018)),
+                                                                surface_pressure_psi=float(b.get('surface_pressure_psi', 14.7)),
+                                                                pressure_gradient_psi_per_ft=float(b.get('pressure_gradient_psi_per_ft', 0.465)),
+                                                                name=str(b.get('name', 'toolstring'))))
+                    except (ValueError, KeyError) as e:
+                        raise ApiError(400, str(e))
                 if path == '/api/stress':
                     App.require(user, 'operator')
                     try:

{gea_program-0.26.0 → gea_program-0.28.0}/gea/sra.py

@@ -340,6 +340,10 @@ def read_catalog(path: str, mapping: Optional[Dict[str, str]] = None) -> dict:
     """A TexNet earthquake-catalogue export (CSV). The columns are found by name; a mapping wins. Every event
     keeps its own id so a claim in the packet can be traced to the catalogue line it came from."""
     from .permits import read_table, _float
+    with open(path, encoding='utf-8-sig', errors='replace') as f:
+        first = f.readline()
+    if first.startswith('#EventID|') or first.startswith('EventID|Time|'):
+        return read_fdsn_text(path)
     header, rows = read_table(path)
     cols = _detect(header, mapping)
     events, skipped = [], 0
@@ -364,6 +368,45 @@ def read_catalog(path: str, mapping: Optional[Dict[str, str]] = None) -> dict:
             'datum': 'WGS84', 'basis': 'the TexNet earthquake catalogue as exported by the operator; positions WGS84, magnitudes ML'}
 
 
+def read_fdsn_text(path: str) -> dict:
+    """The FDSN event web service's text format - USGS ComCat (earthquake.usgs.gov/fdsnws/event/1/query?format=text), and every
+    FDSN-compliant catalogue service: `#EventID|Time|Latitude|Longitude|Depth/km|Author|Catalog|Contributor|ContributorID|MagType|
+    Magnitude|MagAuthor|EventLocationName`. The contributor (tx = TexNet, us = NEIC, ld = Lamont-Doherty) and the magnitude type ride
+    on each event, since a ComCat window mixes networks and magnitude scales."""
+    from .permits import _float
+    events, skipped, n_rows = [], 0, 0
+    with open(path, encoding='utf-8-sig', errors='replace') as f:
+        header = [h.strip().lstrip('#') for h in f.readline().rstrip('\n').split('|')]
+        idx = {h.lower(): i for i, h in enumerate(header)}
+        for line in f:
+            if not line.strip() or line.startswith('#'):
+                continue
+            n_rows += 1
+            parts = line.rstrip('\n').split('|')
+            def g(name):
+                i = idx.get(name)
+                return parts[i].strip() if i is not None and i < len(parts) else ''
+            t = _parse_dt(g('time').replace('T', ' ').split('.')[0]) if g('time') else None
+            m, la, lo = _float(g('magnitude')), _float(g('latitude')), _float(g('longitude'))
+            if t is None or m is None or la is None or lo is None:
+                skipped += 1; continue
+            events.append({'event_id': g('eventid') or f'row{n_rows}', 'time': _utc(t), 'magnitude': m, 'lat': la, 'lon': lo, 'depth_km': _float(g('depth/km')),
+                           'mag_type': g('magtype'), 'contributor': g('contributor'), 'catalog': g('catalog'), 'place': g('eventlocationname')})
+    contribs = sorted({e['contributor'] for e in events if e['contributor']})
+    mtypes = sorted({e['mag_type'] for e in events if e['mag_type']})
+    return {'path': os.path.abspath(path), 'export_mtime_utc': _utc(datetime.fromtimestamp(os.path.getmtime(path), timezone.utc)),
+            'columns': {h.lower(): h for h in header}, 'n_rows': n_rows, 'n_events': len(events), 'n_skipped': skipped, 'events': events, 'datum': 'WGS84',
+            'format': 'fdsn-text', 'contributors': contribs, 'magnitude_types': mtypes,
+            'basis': f"an FDSN event-service text export (USGS ComCat or another FDSN catalogue); positions WGS84; contributors {', '.join(contribs) or '?'}; "
+                     f"magnitude types {', '.join(mtypes) or '?'} - a window across networks mixes scales, and the plan's threshold is read as the catalogue's reported magnitude"}
+
+
+def comcat_url(lat: float, lon: float, radius_km: float, start: str, end: str, min_magnitude: float = 1.0, fmt: str = 'text') -> str:
+    """The ComCat query for a circle and a window - the URL to open in a browser or hand to a machine that can reach the service."""
+    return ('https://earthquake.usgs.gov/fdsnws/event/1/query?format=' + fmt + f'&starttime={start}&endtime={end}&latitude={lat:.4f}&longitude={lon:.4f}'
+            f'&maxradiuskm={radius_km:g}&minmagnitude={min_magnitude:g}&orderby=time-asc')
+
+
 def _detect(header: Sequence[str], mapping: Optional[Dict[str, str]]) -> Dict[str, Optional[str]]:
     from .permits import _norm
     norm = {_norm(h): h for h in header}