gea-program 0.41.0__tar.gz → 0.43.0__tar.gz

{gea_program-0.41.0 → gea_program-0.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.41.0
+Version: 0.43.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`.
 
+### 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
+disposal windows against the earthquake catalogue around it: every event
+within the screening distance by its distance and time, whether it fell
+during an operation or in the months after, what the rig was doing when a
+drilling record covers it, the level a regulator's protocol would reach
+(British Columbia, Alberta, Oklahoma, Ohio, Texas, each with its
+document), and the exact test of whether the rate near the well is higher
+while it works than in the rest of the record. The Mahoning Valley, Ohio -
+the 2011 Youngstown sequence against the Northstar 1 injection year, the
+2014 Poland Township events against a stimulation - ships as a worked
+example from the public record. `gea seismicity`, `gea help opseis`.
+
 ### The declarations sheet
 
 Everything the operator declares about a pad comes in from one spreadsheet:

{gea_program-0.41.0 → gea_program-0.43.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`.
 
+### 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
+disposal windows against the earthquake catalogue around it: every event
+within the screening distance by its distance and time, whether it fell
+during an operation or in the months after, what the rig was doing when a
+drilling record covers it, the level a regulator's protocol would reach
+(British Columbia, Alberta, Oklahoma, Ohio, Texas, each with its
+document), and the exact test of whether the rate near the well is higher
+while it works than in the rest of the record. The Mahoning Valley, Ohio -
+the 2011 Youngstown sequence against the Northstar 1 injection year, the
+2014 Poland Township events against a stimulation - ships as a worked
+example from the public record. `gea seismicity`, `gea help opseis`.
+
 ### The declarations sheet
 
 Everything the operator declares about a pad comes in from one spreadsheet:

{gea_program-0.41.0 → gea_program-0.43.0}/gea/__init__.py

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

{gea_program-0.41.0 → gea_program-0.43.0}/gea/__main__.py

@@ -539,6 +539,52 @@ def main(argv=None) -> int:
     p_pn.add_argument("--actor", type=str, default="cli")
     p_pn.add_argument("--json", action="store_true")
 
+    p_os = sub.add_parser("seismicity", help="operations and seismicity: each well's drilling, completion and disposal windows against the earthquake catalogue around it - the events during and after each, the levels a regulator's protocol would reach, and the rate during operations against the rest of the record; the Mahoning Valley worked example")
+    p_os.add_argument("--workspace", type=str, default=None)
+    p_os.add_argument("--scene", type=str, default=None, choices=("workspace", "mahoning"), help="your wells (the default with --workspace) or the public worked example")
+    p_os.add_argument("--protocol", type=str, default=None, help="a protocol id (--protocols lists them)")
+    p_os.add_argument("--radius-km", type=float, default=None, help="the association radius (default 5 km)")
+    p_os.add_argument("--screen-km", type=float, default=None, help="the screening distance (default 20 km)")
+    p_os.add_argument("--post-days", type=float, default=None, help="the association window after an operation ends (default 90 days)")
+    p_os.add_argument("--mc", type=float, default=None, help="the completeness magnitude counted in the rate (default the catalogue's minimum)")
+    p_os.add_argument("--set", action="store_true", help="keep --protocol, --radius-km, --screen-km, --post-days and --mc as this workspace's settings")
+    p_os.add_argument("--protocols", action="store_true", help="list the protocols and their levels")
+    p_os.add_argument("--query", action="store_true", help="print the ComCat query for the workspace's wells (run it where the catalogue service is reachable)")
+    p_os.add_argument("--attach", type=str, default=None, help="a catalogue export to attach (with --start --end --min-magnitude --lat --lon --catalog-radius-km --source)")
+    p_os.add_argument("--start", type=str, default=None)
+    p_os.add_argument("--end", type=str, default=None)
+    p_os.add_argument("--min-magnitude", type=float, default=None)
+    p_os.add_argument("--lat", type=float, default=None)
+    p_os.add_argument("--lon", type=float, default=None)
+    p_os.add_argument("--catalog-radius-km", type=float, default=None)
+    p_os.add_argument("--source", type=str, default="")
+    p_os.add_argument("--declare-op", action="store_true", help="declare an operation window (with --well --kind --start [--end] --source)")
+    p_os.add_argument("--well", type=str, default=None)
+    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("--actor", type=str, default="cli")
+    p_os.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")
@@ -2144,6 +2190,122 @@ def main(argv=None) -> int:
             raise SystemExit(f"penetrator: {e.args[0] if e.args else e}")
         print(_json.dumps(p, default=str) if a.json else _PN.text(p))
         return 0
+    elif a.cmd == "seismicity":
+        import json as _json
+        from . import op_seismicity as _OS
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        if a.protocols:
+            for p_ in _OS.protocols()["protocols"]:
+                print(f"{p_['id']}: {p_['name']} - within {p_['radius_km'] if p_['radius_km'] is not None else 'the permit distance'} km of {p_['radius_from']}; covers {', '.join(p_['applies_to'])}")
+                for lv in p_["levels"]:
+                    print(f"    M {lv['m']:g}{' (' + lv['condition'] + ')' if lv.get('condition') else ''}: {lv['action']}")
+                print(f"    {p_['document']} - {p_['url']}{' (a secondary summary)' if p_['source_kind'] == 'secondary' else ''}")
+            return 0
+        ws = None
+        if a.workspace:
+            try:
+                ws = Workspace(a.workspace)
+            except WorkspaceError as e:
+                raise SystemExit(f"seismicity: {e}")
+        try:
+            if a.attach:
+                if ws is None:
+                    raise SystemExit("seismicity: --attach needs --workspace")
+                with open(a.attach, "rb") as f:
+                    r = _OS.attach_catalog(ws, a.actor, os.path.basename(a.attach), f.read(), a.start, a.end, a.min_magnitude, a.lat, a.lon, a.catalog_radius_km, a.source)
+                print(f"attached {r['file']}: {r['n_events']} event(s), {r['start']} to {r['end']}, M >= {r['min_magnitude']:g}")
+                return 0
+            if a.declare_op:
+                if ws is None or not a.well or not a.kind:
+                    raise SystemExit("seismicity: --declare-op needs --workspace, --well and --kind")
+                r = _OS.save_operation(ws, a.actor, a.well, a.kind, a.start, a.end, a.source)
+                print(f"declared {r['id']}: {r['kind']} on {r['well_id']}, {r['start']} to {r['end'] or 'open'}")
+                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.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}
+            if a.set:
+                if ws is None:
+                    raise SystemExit("seismicity: --set needs --workspace")
+                s_ = _OS.set_settings(ws, a.actor, over.get("protocol"), over.get("radius_km"), over.get("screen_km"), over.get("post_days"), over.get("mc"))
+                print("settings: " + ", ".join(f"{k} {v}" for k, v in s_.items()))
+                return 0
+            if over.get("protocol"):
+                _OS.protocol(over["protocol"])
+            r = _OS.page(ws, a.scene or ("workspace" if ws is not None else "mahoning"), over or None)
+        except (ValueError, KeyError, OSError) as e:
+            raise SystemExit(f"seismicity: {e.args[0] if e.args else e}")
+        if a.query:
+            q = r.get("query")
+            print(q["url"] if q else "no well of the workspace has a surface position yet: declare one first")
+            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 == "simulation":
         import json as _json
         from . import simulation as _SIM