gea-program 0.42.0__tar.gz → 0.44.0__tar.gz

{gea_program-0.42.0 → gea_program-0.44.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.42.0
+Version: 0.44.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
@@ -648,6 +648,33 @@ 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`.
 
+### The earthquake watch and the alerts
+
+While a well operates, the program reads the USGS earthquake catalogue
+every few minutes from the site's machine - the real-time feed USGS asks
+automated programs to use, and the catalogue service for any gap - and
+raises an alert when an earthquake near the well reaches the chosen
+regulator's protocol level; a revision to a higher level is a new alert,
+and a watch that cannot reach the catalogue says so. The same alerts cover
+what nobody watches by hand: a component's service interval used up, a
+penetrator check outside its rating, a signed dossier the workspace no
+longer matches. Every alert is listed on the Alarms tab and sent through
+the notification rules (email or a webhook). `gea seismicity --watch-once`,
+`gea alerts`, `gea help alerts`.
+
+### Report history and the signed dossier
+
+Every client report a workspace writes is kept, version by version, under
+`reports\history\` with each file's SHA-256, so pressing a report button
+again no longer loses the last one; the Reports tab lists every version.
+The signed dossier puts a well's - or the pad's - reports, declarations,
+audit log and source-record hashes in one zip, signed with the site's own
+Ed25519 key (made on the site's machine, never sent anywhere), with a
+checker inside that anyone can run with plain Python: VALID when the
+signature and every file's hash hold, and inside the workspace a check that
+the source records and the audit log still match what was signed.
+`gea dossier`, `gea reports-history`, `gea help dossier`.
+
 ### Operations and seismicity
 
 The Operations & Seismicity tab sets each well's drilling, completion and

{gea_program-0.42.0 → gea_program-0.44.0}/README.md

@@ -609,6 +609,33 @@ 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`.
 
+### The earthquake watch and the alerts
+
+While a well operates, the program reads the USGS earthquake catalogue
+every few minutes from the site's machine - the real-time feed USGS asks
+automated programs to use, and the catalogue service for any gap - and
+raises an alert when an earthquake near the well reaches the chosen
+regulator's protocol level; a revision to a higher level is a new alert,
+and a watch that cannot reach the catalogue says so. The same alerts cover
+what nobody watches by hand: a component's service interval used up, a
+penetrator check outside its rating, a signed dossier the workspace no
+longer matches. Every alert is listed on the Alarms tab and sent through
+the notification rules (email or a webhook). `gea seismicity --watch-once`,
+`gea alerts`, `gea help alerts`.
+
+### Report history and the signed dossier
+
+Every client report a workspace writes is kept, version by version, under
+`reports\history\` with each file's SHA-256, so pressing a report button
+again no longer loses the last one; the Reports tab lists every version.
+The signed dossier puts a well's - or the pad's - reports, declarations,
+audit log and source-record hashes in one zip, signed with the site's own
+Ed25519 key (made on the site's machine, never sent anywhere), with a
+checker inside that anyone can run with plain Python: VALID when the
+signature and every file's hash hold, and inside the workspace a check that
+the source records and the audit log still match what was signed.
+`gea dossier`, `gea reports-history`, `gea help dossier`.
+
 ### Operations and seismicity
 
 The Operations & Seismicity tab sets each well's drilling, completion and

{gea_program-0.42.0 → gea_program-0.44.0}/gea/__init__.py

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

{gea_program-0.42.0 → gea_program-0.44.0}/gea/__main__.py

@@ -563,9 +563,38 @@ def main(argv=None) -> int:
     p_os.add_argument("--kind", type=str, default=None, choices=("drilling", "completion", "disposal", "injection", "other"))
     p_os.add_argument("--remove-op", type=str, default=None)
     p_os.add_argument("--remove-catalog", type=str, default=None)
+    p_os.add_argument("--watch", type=str, default=None, choices=("on", "off"), help="turn the live earthquake watch on or off")
+    p_os.add_argument("--watch-every", type=float, default=None, help="the watch's interval in minutes (default 5)")
+    p_os.add_argument("--watch-mode", type=str, default=None, choices=("operations", "always"), help="poll only while an operation is under way (default), or always")
+    p_os.add_argument("--watch-once", action="store_true", help="poll the USGS catalogue now, from this machine, and say what came back")
     p_os.add_argument("--actor", type=str, default="cli")
     p_os.add_argument("--json", action="store_true")
 
+    p_al = sub.add_parser("alerts", help="the program's alerts: earthquakes near operating wells and the protocol levels they reach, the earthquake watch going quiet, components due for service, penetrator checks outside their ratings, dossiers the workspace no longer matches")
+    p_al.add_argument("--workspace", type=str, required=True)
+    p_al.add_argument("--check", action="store_true", help="check the motors, penetrators and dossiers now, sending what began or cleared through the notification rules")
+    p_al.add_argument("-n", type=int, default=30)
+    p_al.add_argument("--json", action="store_true")
+
+    p_dz = sub.add_parser("dossier", help="the signed dossier: a well's (or the pad's) reports, declarations, audit log and source hashes in one zip, signed with the site's Ed25519 key, with a checker anyone can run without this program")
+    p_dz.add_argument("--workspace", type=str, default=None)
+    p_dz.add_argument("--well", type=str, default=None, help="a well; without it, the pad (every well and the site reports)")
+    p_dz.add_argument("--include-sources", action="store_true", help="embed the source records (by default they are listed by hash)")
+    p_dz.add_argument("--verify", type=str, default=None, help="a dossier to check (with --workspace, also against this site)")
+    p_dz.add_argument("--sources", type=str, default="", help="with --verify: a folder holding the source records to check against their hashes")
+    p_dz.add_argument("--key", action="store_true", help="print this site's signing key fingerprint")
+    p_dz.add_argument("--list", action="store_true", help="list the dossiers this site has signed")
+    p_dz.add_argument("--actor", type=str, default="cli")
+    p_dz.add_argument("--json", action="store_true")
+
+    p_rh = sub.add_parser("reports-history", help="every version of every client report this workspace has written, kept under reports/history; --prune keeps the newest N")
+    p_rh.add_argument("--workspace", type=str, required=True)
+    p_rh.add_argument("--family", type=str, default=None, help="e.g. wells/Well-1/well_report or pad_report")
+    p_rh.add_argument("--prune", action="store_true")
+    p_rh.add_argument("--keep", type=int, default=0)
+    p_rh.add_argument("--apply", action="store_true", help="with --prune: remove (without it, list what would go)")
+    p_rh.add_argument("--json", action="store_true")
+
     p_sm = sub.add_parser("simulation", help="the simulation in words: the scenes (Volve 15/9-F-4 with its logs and interpretation, Volve F-5 and F-10 on the survey clock, every drilling-recorder well), and what the record says at a depth (the Simulation tab replays it)")
     p_sm.add_argument("--workspace", type=str, default=None)
     p_sm.add_argument("--scene", type=str, default=None, help="e.g. volve-f4, or well:Well-30636033")
@@ -2206,6 +2235,26 @@ def main(argv=None) -> int:
                 return 0
             if a.remove_op:
                 _OS.remove_operation(ws, a.actor, a.remove_op); print(f"removed {a.remove_op}"); return 0
+            if a.watch or a.watch_every is not None or a.watch_mode or a.watch_once:
+                from . import seismic_watch as _SW
+                if ws is None:
+                    raise SystemExit("seismicity: the watch needs --workspace")
+                if a.watch or a.watch_every is not None or a.watch_mode:
+                    _SW.set_settings(ws, a.actor, None if a.watch is None else a.watch == "on", a.watch_mode, a.watch_every)
+                if a.watch_once:
+                    from .notify import Notifier
+                    n_ = Notifier(ws.path); n_.reload()
+                    r_ = _SW.poll(ws, n_, force=True)
+                    if r_.get("ok"):
+                        print(f"reached the catalogue ({r_['how']}): {r_['in_circle']} earthquake(s) in the watch circle, {r_['new']} new; {len(r_['alerts'])} alert(s)")
+                        for al_ in r_["alerts"]:
+                            print(f"  {al_['event']}: {al_.get('detail', '')}")
+                    else:
+                        print(f"did not reach the catalogue: {r_.get('error') or r_.get('why')}")
+                st_ = _SW.status(ws)
+                print(f"watch: {st_['state']} - every {st_['settings']['every_min']:g} min, {st_['settings']['mode']}; last good poll {st_['last_ok_utc'] or 'never'}"
+                      + (f"; last error {st_['last_error']}" if st_.get('last_error') else ""))
+                return 0 if (not a.watch_once or r_.get("ok")) else 1
             if a.remove_catalog:
                 _OS.remove_catalog(ws, a.actor, a.remove_catalog); print(f"removed {a.remove_catalog}"); return 0
             over = {k: v for k, v in (("protocol", a.protocol), ("radius_km", a.radius_km), ("screen_km", a.screen_km), ("post_days", a.post_days), ("mc", a.mc)) if v is not None}
@@ -2226,6 +2275,91 @@ def main(argv=None) -> int:
             return 0
         print(_json.dumps(r, default=str) if a.json else _OS.text(r))
         return 0
+    elif a.cmd == "dossier":
+        import json as _json
+        from . import dossier as _DZ
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        ws = None
+        if a.workspace:
+            try:
+                ws = Workspace(a.workspace)
+            except WorkspaceError as e:
+                raise SystemExit(f"dossier: {e}")
+        if a.verify:
+            r = _DZ.verify(a.verify, ws, a.sources)
+            print(_json.dumps(r, default=str) if a.json else _DZ.text(r))
+            return 0 if r["status"] == "VALID" else 1
+        if ws is None:
+            raise SystemExit("dossier: give --workspace (or --verify FILE)")
+        if a.key:
+            k = _DZ.key_info(ws)
+            print(f"Ed25519 {k['fingerprint']} (public key {k['public_key']}, made {k['created_utc']})" if k else "no signing key yet: the first dossier makes one")
+            return 0
+        if a.list:
+            for e in reversed(_DZ.ledger(ws)):
+                print(f"{e['utc']}  {e['dossier_id']}  {e['display']:<24} {e['n_files']:>4} files  {e['path']}")
+            return 0
+        try:
+            e = _DZ.build(ws, a.actor, __version__, a.well, a.include_sources)
+        except (KeyError, ValueError) as ex:
+            raise SystemExit(f"dossier: {ex.args[0] if ex.args else ex}")
+        print(f"signed {e['dossier_id']}: {e['display']}, {e['n_files']} file(s), {e['n_sources']} source record(s) {'embedded' if e['sources_embedded'] else 'by hash'}")
+        print(f"  {os.path.join(ws.reports_dir, e['path'])}")
+        print(f"  key fingerprint {e['fingerprint']}")
+        return 0
+    elif a.cmd == "reports-history":
+        import json as _json
+        from . import report_history as _RH
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        try:
+            ws = Workspace(a.workspace)
+        except WorkspaceError as e:
+            raise SystemExit(f"reports-history: {e}")
+        if a.prune:
+            if a.keep < 1:
+                raise SystemExit("reports-history: --prune needs --keep N (at least 1)")
+            r = _RH.prune(ws.reports_dir, a.keep, a.family, a.apply)
+            print(f"{'removed' if r['applied'] else 'would remove'} {len(r['removed'])} version(s), {r['bytes_freed']:,} bytes" + ("" if r['applied'] else " - add --apply to remove them"))
+            return 0
+        sm = _RH.summary(ws.reports_dir)
+        if a.json:
+            print(_json.dumps(sm, default=str)); return 0
+        print(f"{sm['n_versions']} version(s) of {len(sm['families'])} report(s), {sm['bytes']:,} bytes under {os.path.join(ws.reports_dir, 'history')}")
+        for f_ in sm["families"]:
+            if a.family and f_["family"] != a.family:
+                continue
+            print(f"  {f_['family']}: {f_['n']} version(s)")
+            for v in f_["versions"][: (50 if a.family else 3)]:
+                print(f"      {v['utc']}  {v.get('report_id') or ''}  reports/{v['dir']}")
+        return 0
+    elif a.cmd == "alerts":
+        import json as _json
+        from . import alerts as _AL
+        from .cli import _safe_stdout
+        from .notify import Notifier
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        try:
+            ws = Workspace(a.workspace)
+        except WorkspaceError as e:
+            raise SystemExit(f"alerts: {e}")
+        if a.check:
+            n_ = Notifier(ws.path); n_.reload()
+            r_ = _AL.check_conditions(ws, n_, force=True)
+            print(f"checked: {len(r_)} alert(s) raised or cleared")
+        rows = _AL.recent(ws, a.n)
+        if a.json:
+            print(_json.dumps(rows, default=str)); return 0
+        for r in rows:
+            sent = ", ".join(f"{d['channel']}{'' if d['ok'] else ' (failed)'}" for d in r.get("delivered") or []) or "no channel set up"
+            print(f"{r['utc']}  {r['event']:<20} {r.get('well') or '':<16} {r.get('detail', '')}  [{sent}]")
+        if not rows:
+            print("no alerts yet")
+        return 0
     elif a.cmd == "simulation":
         import json as _json
         from . import simulation as _SIM