gea-program 0.18.0__tar.gz → 0.20.0__tar.gz

{gea_program-0.18.0 → gea_program-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.18.0
+Version: 0.20.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 (342 checks)
+gea accept                     # the product gate (347 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]")
@@ -710,6 +710,24 @@ after the report was written - and "Update every report from its source"
 dashboard for every well, then every seismic station, errors collected and
 listed, never hidden.
 
+### The month-end packet
+
+A client's month was five or six commands and a walk through the reports
+folder. `gea workspace --path C:\site --action month-end --period 2026-09`
+(or `--period previous`) runs the refresh for the period and collects every
+report the program writes - each well's drift report, alarm month, well-test
+validation, shut-in report, data resilience, machine vibration and the
+certificate register's ISO/IEC 17025 7.8 conformity; each site's SRA packet
+for the period and site report; every seismic station and track; the
+accuracy statement, the SLA month, the FAT/SAT protocol, the model cards and
+the SBOM - into `reports/month_end/<period>/` with `INDEX` (html, md, json:
+every item INCLUDED with its files or NOT AVAILABLE with the reason that
+names what the site lacks; every failed step; OPEN for a month that has not
+ended) and `MANIFEST.json` (every file's SHA-256), zipped beside it. Nothing
+is recomputed in the index. On the Reports page: the packets on record,
+Assemble as a job, and Schedule monthly (day and hour, the previous month).
+`gea help month-end`.
+
 ### Before a site goes live
 
 `deploy/README.md` is the checklist: keep the service on the loopback
@@ -722,6 +740,14 @@ headers on every response, and `gea housekeeping --workspace C:\site --apply`
 than truncating them and prunes finished job folders and old recordings. `gea
 loadtest --patches 16 --seconds 60 --with-service` tells you whether the site
 machine carries the patches it will be given, with the page still answering.
+`gea soak --hours 72 --patches 4 --with-service --out C:\site\reports\soak`
+runs the site's patch count, an ETP patch and a SeedLink station through
+link relays that are cut on a schedule, and writes the Soak Report from the
+supervisor's own numbers: seconds to reconnect per source after every
+outage, what each protocol lost while the link was down (WITS0 has no
+replay; SeedLink resumes by sequence number, so its gap count must be
+zero), and the page's answer time through it; Verification runs a 15-minute
+one from the page. `gea help soak`.
 `gea backup --workspace C:\site --out D:\gea-backups --keep 14` copies the
 whole site into one dated archive with a manifest of every file's hash, onto
 another disk or a share; schedule it daily from Audit / Update, verify an

{gea_program-0.18.0 → gea_program-0.20.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 (342 checks)
+gea accept                     # the product gate (347 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]")
@@ -671,6 +671,24 @@ after the report was written - and "Update every report from its source"
 dashboard for every well, then every seismic station, errors collected and
 listed, never hidden.
 
+### The month-end packet
+
+A client's month was five or six commands and a walk through the reports
+folder. `gea workspace --path C:\site --action month-end --period 2026-09`
+(or `--period previous`) runs the refresh for the period and collects every
+report the program writes - each well's drift report, alarm month, well-test
+validation, shut-in report, data resilience, machine vibration and the
+certificate register's ISO/IEC 17025 7.8 conformity; each site's SRA packet
+for the period and site report; every seismic station and track; the
+accuracy statement, the SLA month, the FAT/SAT protocol, the model cards and
+the SBOM - into `reports/month_end/<period>/` with `INDEX` (html, md, json:
+every item INCLUDED with its files or NOT AVAILABLE with the reason that
+names what the site lacks; every failed step; OPEN for a month that has not
+ended) and `MANIFEST.json` (every file's SHA-256), zipped beside it. Nothing
+is recomputed in the index. On the Reports page: the packets on record,
+Assemble as a job, and Schedule monthly (day and hour, the previous month).
+`gea help month-end`.
+
 ### Before a site goes live
 
 `deploy/README.md` is the checklist: keep the service on the loopback
@@ -683,6 +701,14 @@ headers on every response, and `gea housekeeping --workspace C:\site --apply`
 than truncating them and prunes finished job folders and old recordings. `gea
 loadtest --patches 16 --seconds 60 --with-service` tells you whether the site
 machine carries the patches it will be given, with the page still answering.
+`gea soak --hours 72 --patches 4 --with-service --out C:\site\reports\soak`
+runs the site's patch count, an ETP patch and a SeedLink station through
+link relays that are cut on a schedule, and writes the Soak Report from the
+supervisor's own numbers: seconds to reconnect per source after every
+outage, what each protocol lost while the link was down (WITS0 has no
+replay; SeedLink resumes by sequence number, so its gap count must be
+zero), and the page's answer time through it; Verification runs a 15-minute
+one from the page. `gea help soak`.
 `gea backup --workspace C:\site --out D:\gea-backups --keep 14` copies the
 whole site into one dated archive with a manifest of every file's hash, onto
 another disk or a share; schedule it daily from Audit / Update, verify an

{gea_program-0.18.0 → gea_program-0.20.0}/gea/__init__.py

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

{gea_program-0.18.0 → gea_program-0.20.0}/gea/__main__.py

@@ -285,7 +285,7 @@ def main(argv=None) -> int:
                                "add-seismic", "refresh-seismic", "remove-seismic", "sar-film", "refresh-all", "add-track", "refresh-track", "remove-track",
                                "seismic-dataset", "seismic-field", "add-site", "sites", "site-report", "remove-site", "rename",
                                "set-well", "sra-define", "sra-report", "associate", "osdu-export", "quakeml-export", "well-identity", "vibration-report",
-                               "add-live-station", "live-fold", "live-run"])
+                               "add-live-station", "live-fold", "live-run", "month-end"])
     p_ws.add_argument("--stations", type=str, nargs="+", default=None, help="add-track: two or more array station ids of this workspace")
     p_ws.add_argument("--site", type=str, default=None, help="site-report/remove-site: the site id")
     p_ws.add_argument("--api", type=str, default=None, help="set-well: the API number")
@@ -307,7 +307,7 @@ def main(argv=None) -> int:
     p_ws.add_argument("--checkpoint-months", type=int, default=3, help="sra-define: months between checkpoints with Commission staff (3)")
     p_ws.add_argument("--formation-boundary", type=str, default="base of the Wolfcamp", help="sra-define: the stratigraphic boundary between the two tiers")
     p_ws.add_argument("--triggering-event", type=str, default="", help="sra-define: the catalogue id of the event the plan answers")
-    p_ws.add_argument("--catalog", type=str, default=None, help="sra-report: a TexNet earthquake-catalogue export (CSV)")
+    p_ws.add_argument("--catalog", type=str, default=None, help="sra-report / month-end: a TexNet earthquake-catalogue export (CSV)")
     p_ws.add_argument("--aftershocks", type=str, nargs="*", default=None, help="sra-report: catalogue ids the operator declares as aftershocks (exempt)")
     p_ws.add_argument("--start", type=str, default=None, help="sra-report: first day of the record, YYYY-MM-DD")
     p_ws.add_argument("--end", type=str, default=None, help="sra-report: last day of the record, YYYY-MM-DD")
@@ -359,6 +359,8 @@ def main(argv=None) -> int:
     p_ws.add_argument("--seedlink-config", type=str, default=None, help="add-live-station: the SeedLink config JSON (gea seedlink --write-example-config)")
     p_ws.add_argument("--include-open", action="store_true", help="live-fold: fold the current day's files too (they are still being written)")
     p_ws.add_argument("--seconds", type=float, default=None, help="live-run: how long to run (default: until Ctrl+C)")
+    p_ws.add_argument("--period", type=str, default="previous", help="month-end: the month, YYYY-MM, or 'previous' (the last closed month)")
+    p_ws.add_argument("--no-refresh", action="store_true", help="month-end: collect the reports as they stand without refreshing first")
     p_ws.add_argument("--name", type=str, default=None, help="init: site name; add-*: display name")
     p_ws.add_argument("--file", type=str, default=None, help="add-file: the client's data file; add-live: the port configuration JSON")
     p_ws.add_argument("--entry", type=str, default=None, help="add-catalog: catalogue entry")
@@ -390,6 +392,19 @@ def main(argv=None) -> int:
     p_hk.add_argument("--actor", type=str, default="housekeeping")
     p_hk.add_argument("--json", action="store_true")
 
+    p_sk = sub.add_parser("soak", help="the patches through link outages for hours, measured: N WITS0 patches, an ETP patch and a SeedLink station through relays that are cut on a schedule; the Soak Report")
+    p_sk.add_argument("--hours", type=float, default=None, help="how long (72 for the go-live soak); or --seconds")
+    p_sk.add_argument("--seconds", type=float, default=None)
+    p_sk.add_argument("--patches", type=int, default=2, help="WITS0 patches (the site's own count)")
+    p_sk.add_argument("--no-etp", action="store_true"); p_sk.add_argument("--no-seedlink", action="store_true")
+    p_sk.add_argument("--outage-every", type=float, default=600.0, help="seconds between link outages")
+    p_sk.add_argument("--outage-len", type=float, default=60.0, help="seconds each outage lasts")
+    p_sk.add_argument("--interval", type=float, default=1.0, help="simulator frame interval (s)")
+    p_sk.add_argument("--reconnect-budget", type=float, default=90.0, help="seconds a source may take to be back and receiving after the link returns")
+    p_sk.add_argument("--with-service", action="store_true", help="also serve the page and time its answers through the outages")
+    p_sk.add_argument("--out", type=str, default=None, help="where soak.json and the Soak Report go (default: the throw-away workspace's reports/soak)")
+    p_sk.add_argument("--keep", action="store_true", help="keep the throw-away workspace")
+    p_sk.add_argument("--json", action="store_true")
     p_lt = sub.add_parser("loadtest", help="how many supervised patches this machine carries: N WITS0 simulators and patches for a while, with the service answering")
     p_lt.add_argument("--patches", type=int, default=8)
     p_lt.add_argument("--seconds", type=float, default=30.0)
@@ -913,6 +928,15 @@ def main(argv=None) -> int:
             for x in r['records_removed'][:20]:
                 print(f"  record  {x['well_id']}/{x['file']}  {x['age_days']} d")
         return 0
+    elif a.cmd == "soak":
+        import json as _json
+        from .soak import run as _soak
+        secs = a.seconds if a.seconds is not None else (a.hours * 3600.0 if a.hours is not None else 600.0)
+        r = _soak(seconds=secs, patches=a.patches, etp=not a.no_etp, seedlink=not a.no_seedlink, outage_every_s=a.outage_every, outage_s=a.outage_len,
+                  interval_s=a.interval, with_service=a.with_service, keep=a.keep, out_dir=a.out, reconnect_budget_s=a.reconnect_budget, verbose=not a.json)
+        if a.json:
+            print(_json.dumps({k: v for k, v in r.items() if k != "samples_timeline"}, indent=1, default=str))
+        return 0 if r["ok"] else 1
     elif a.cmd == "loadtest":
         import json as _json
         from .loadtest import run as _lt
@@ -1944,6 +1968,10 @@ def main(argv=None) -> int:
                     raise SystemExit("well-identity needs --well <id>")
                 r = ws.well_identity(a.well)
                 print(_ppdm_text(r)); return 0
+            elif a.action == "month-end":
+                from .month_end import report_text as _me_text
+                r = ws.month_end(a.period, actor=a.actor, refresh=not a.no_refresh, catalog_csv=a.catalog)
+                print(_me_text(r)); return 0 if not r["errors"] else 1
             elif a.action == "add-live-station":
                 if not a.seedlink_config or not a.name:
                     raise SystemExit("add-live-station needs --name <display> and --seedlink-config <json>")

{gea_program-0.18.0 → gea_program-0.20.0}/gea/acceptance_tests.py

@@ -646,7 +646,7 @@ def section_s_correlation() -> None:
        and all("continuity" in r["continuity_claim"].lower()
                or r["continuity_claim"] == "TWIN_HOLE_ELIGIBLE"
                for r in df["refused"] + df["ok"])
-       and "honest census" in df["finding"],
+       and "census as it stands" in df["finding"],
        "S2 correlation: every cross-site pair carries a continuity claim "
        "bounded by distance, and thin pairs refuse with counts")
 
@@ -767,26 +767,27 @@ def section_y_survey() -> None:
     """Section Y - the one-command user path: gea survey."""
     from .survey_cmd import run_survey
     txt, d = run_survey(demo=True)
-    ok('one honest answer' in txt and d['n_stations'] == 65
-       and d['exclusions']['washout_or_null_stations'] == 46,
+    from .client_reports import forbidden_terms
+    ok('one answer with its provenance' in txt and d['n_stations'] == 65
+       and d['exclusions']['washout_or_null_stations'] == 46 and not forbidden_terms(txt),
        "Y1 survey demo: end-to-end on the bundled KTB excerpt - 65 "
-       "stations, 46 exclusions DISCLOSED, one readable report")
+       "stations, 46 exclusions DISCLOSED, one readable report that passes the same internal-register guard every client report passes")
     ok('vp_m_s' in d and abs(d.get('vp_cross_check_pct', 99)) < 5.0,
        "Y2 survey self-grading: the file carries its own sonic and the "
        "estimate lands within 5 pct of measured (demo: ~+0.7 pct) - the "
        "tool grades itself when the data allows")
-    ok('ASSUMPTION' in txt and 'refused to guess' in txt,
-       "Y3 survey honesty: the prior-family assumption is printed where "
-       "it acts and the refusals section is always present")
+    ok('ASSUMPTION' in txt and 'does not call a measurement' in txt,
+       "Y3 survey: the prior-family assumption is printed where "
+       "it acts and the what-this-tool-does-not-call-a-measurement section is always present")
     import tempfile, os as _os
     with tempfile.TemporaryDirectory() as td:
         f = _os.path.join(td, 'empty.las')
         open(f, 'w').write('~Version\n VERS. 2.0:\n~Well\n~Curve\n'
                            'DEPT.M : depth\n~ASCII\n1.0\n2.0\n')
         txt2, d2 = run_survey(path=f)
-        ok(d2['refusals'] and 'REFUSED' in txt2,
-           "Y4 survey refusal: a LAS with no density and no gravity gets "
-           "an honest refusal naming the unlocking channel, not an "
+        ok(d2['refusals'] and 'NOT ESTIMATED' in txt2 and not forbidden_terms(txt2),
+           "Y4 survey: a LAS with no density and no gravity gets "
+           "NOT ESTIMATED naming the unlocking channel, not an "
            "invented answer")
 
 
@@ -5872,6 +5873,229 @@ def section_bl_backup(tmp: str) -> None:
        "`--verify` says OK or names the tampered file, `--restore` brings the accounts back; the help page says a backup never restored is a hope"
        + (f" [failed: {', '.join(failed2)}; r_st0={r_st0.stdout[-120:]!r} {r_st0.stderr[-120:]!r}]" if failed2 else ""))
 
+
+def section_bm_month_end(tmp: str) -> None:
+    """Section BM - the month-end packet: the refresh for the period, every report collected with INCLUDED or NOT
+    AVAILABLE and the reason, the index and the manifest, the archive, the records; the page, the job and the
+    monthly schedule."""
+    import http.cookiejar
+    import subprocess as _sp
+    import urllib.request
+    import urllib.error
+    import zipfile
+    from . import month_end as ME
+    from . import helplib as H
+    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, "bm"); d.mkdir()
+    hist = str(d / "hist.csv")
+    TelemetryRecorder(engine=DownholeEngine(SimulatorConfig()), config=TelemetryConfig(duration_hours=2.0, seed=5)).run().export_csv(hist)
+    wsp = str(d / "ws"); ws = Workspace.create(wsp, "Pad 3", actor="tester")
+    w = ws.add_well_file(hist, display="SWD 1", actor="tester")
+    site = ws.add_site("Pad 3 site", wells=[w["id"]], actor="tester")
+    bad_period = None
+    try:
+        ME.period_bounds("2026-9")
+    except ValueError as e:
+        bad_period = str(e)
+    pb = ME.period_bounds("2026-02")
+    rec = ME.assemble(ws, "2026-09", actor="tester")
+    idx = json.loads((Path(rec["folder"]) / "INDEX.json").read_text(encoding="utf-8"))
+    man = json.loads((Path(rec["folder"]) / "MANIFEST.json").read_text(encoding="utf-8"))
+    by_name = {i["name"]: i for i in idx["items"]}
+    v_folder = ME.verify(rec["folder"]); v_zip = ME.verify(rec["archive"])
+    with zipfile.ZipFile(rec["archive"]) as z:
+        znames = set(z.namelist())
+    # a second assembly of the same period rebuilds whole; a future month is OPEN
+    rec2 = ME.assemble(ws, "2026-09", actor="tester", refresh=False)
+    from datetime import datetime as _dt, timezone as _tz
+    now = _dt.now(_tz.utc)
+    cur = f"{now.year:04d}-{now.month:02d}"
+    rec3 = ME.assemble(ws, cur, actor="tester", refresh=False)
+    pk = ME.packets(ws)
+    audit = [a["action"] for a in ws.audit_log()]
+    c1 = {
+        "period_checked": bool(bad_period) and "YYYY-MM" in bad_period and pb["days"] == 28 and pb["start"] == "2026-02-01T00:00:00Z" and pb["end"] == "2026-02-28T23:59:59Z" and pb["closed"] is True,
+        "included": by_name["SWD 1: gauge drift report"]["status"] == "INCLUDED" and by_name["SWD 1: alarm event report"]["status"] == "INCLUDED"
+                    and by_name["SLA month 2026-09"]["status"] == "INCLUDED" and by_name["Accuracy statement"]["status"] == "INCLUDED"
+                    and by_name["Pad 3 site: site report"]["status"] == "INCLUDED" and by_name["Model cards and SBOM"]["status"] == "INCLUDED",
+        "not_available_with_reason": by_name["SWD 1: machine vibration"]["status"] == "NOT AVAILABLE" and "no machine record" in by_name["SWD 1: machine vibration"]["reason"]
+                    and by_name["Pad 3 site: SRA packet for 2026-09"]["status"] == "NOT AVAILABLE" and "no Seismicity Response Area" in by_name["Pad 3 site: SRA packet for 2026-09"]["reason"]
+                    and "no certificate register" in by_name["SWD 1: certificate conformity (ISO/IEC 17025 7.8)"]["reason"],
+        "files_hashed": all(f["sha256"] and f["bytes"] > 0 for i in idx["items"] for f in i["files"]) and man["n_files"] == len(man["files"]) and man["n_files"] >= 20
+                    and "wells/SWD-1/gauge_drift_report.html" in man["files"] and "site/sla_report_2026-09.html" in man["files"] and "INDEX.html" in man["files"],
+        "record": rec["included"] == len([i for i in idx["items"] if i["status"] == "INCLUDED"]) and rec["closed"] is True and rec["errors"] == [] and os.path.isfile(rec["archive"])
+                    and os.path.isfile(rec["archive"] + "") and rec["archive"].endswith("month_end_Pad-3_2026-09.zip"),
+        "verify": v_folder["status"] == "OK" and v_zip["status"] == "OK" and v_zip["n_files"] == man["n_files"] and "MANIFEST.json" in znames and "INDEX.html" in znames,
+        "rebuilt_whole_and_open": rec2["generated_utc"] >= rec["generated_utc"] and rec2["refresh"] is False and rec3["closed"] is False and "OPEN" in (Path(rec3["folder"]) / "INDEX.md").read_text(encoding="utf-8")
+                    and len(pk) == 3 and all(p["present"] for p in pk) and pk[-1]["period"] == cur,
+        "audited": audit.count("month_end.assemble") == 3 and "dashboard.refresh" in audit and "site.report" in audit,
+        "not_a_measurement": "does not call a measurement" in (Path(rec["folder"]) / "INDEX.md").read_text(encoding="utf-8"),
+    }
+    failed1 = [k for k, v in c1.items() if not v]
+    ok(not failed1,
+       "BM1 the month-end packet: the period checked (YYYY-MM; February's 28 days; a past month closed), the refresh run for it, every report "
+       "collected - the well's drift and alarm reports, the SLA month, the accuracy statement, the site report, the model cards - INCLUDED with "
+       "hashed files, and the vibration report, the SRA packet and the certificate conformity NOT AVAILABLE with the reason that names what the "
+       "site lacks; INDEX and MANIFEST written, the archive verifies against the manifest, a second assembly rebuilds the period whole, the "
+       "current month is marked OPEN, every packet on record, every assembly in the audit"
+       + (f" [failed: {', '.join(failed1)}]" if failed1 else ""))
+
+    # -- the page, the job, the schedule, the CLI, the help --------------------------------------------------------
+    users = Users(str(Path(wsp, "users.json"))); users.add("op", "operator-pass-1", "operator"); users.add("adm", "admin-pass-1", "admin")
+    svc = Service(wsp, port=0, scheduler=False).start()
+    base = 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 + 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=300) as rr_:
+                return rr_.status, json.loads(rr_.read())
+        except urllib.error.HTTPError as e:
+            return e.code, json.loads(e.read())
+    try:
+        call("POST", "/api/login", {"name": "op", "password": "operator-pass-1"})
+        st_l, lst = call("GET", "/api/month-end")
+        st_bad = call("POST", "/api/month-end/run", {"period": "Sept 2026"})[0]
+        st_sched_op = call("POST", "/api/month-end/schedule", {"day": 1, "at": "03:00"})[0]
+        st_run, job = call("POST", "/api/month-end/run", {"period": "2026-08", "no_refresh": True})
+        done = svc.app.runner.wait(job["id"], 300)
+        st_l2, lst2 = call("GET", "/api/month-end")
+        req = urllib.request.Request(base + "/reports/month_end/2026-08/INDEX.html"); req.add_header("X-GEA-Action", "1")
+        with opener.open(req, timeout=60) as rr_:
+            html_ok = rr_.status == 200 and b"Month-End Packet" in rr_.read()
+        call("POST", "/api/login", {"name": "adm", "password": "admin-pass-1"})
+        st_sched_bad = call("POST", "/api/month-end/schedule", {"day": 31, "at": "03:00"})[0]
+        st_sched, sch = call("POST", "/api/month-end/schedule", {"day": 2, "at": "03:15"})
+        st_l3, lst3 = call("GET", "/api/month-end")
+    finally:
+        svc.stop()
+    page_src = (pkg / "web" / "app.html").read_text(encoding="utf-8")
+    help_md = (pkg / "help" / "month-end.md").read_text(encoding="utf-8")
+    r_cli = _sp.run([sys.executable, "-m", "gea", "workspace", "--path", wsp, "--action", "month-end", "--period", "2026-07", "--no-refresh"], capture_output=True, text=True)
+    r_prev = _sp.run([sys.executable, "-m", "gea", "workspace", "--path", wsp, "--action", "month-end", "--no-refresh"], capture_output=True, text=True)
+    c2 = {
+        "list": st_l == 200 and len(lst["packets"]) == 3 and lst["previous"] == ME.previous_period() and lst["schedule"] is None,
+        "refusals": st_bad == 400 and st_sched_op == 403 and st_sched_bad == 400,
+        "job": st_run == 200 and done["status"] == "DONE" and st_l2 == 200 and any(p["period"] == "2026-08" and p["present"] for p in lst2["packets"]) and html_ok,
+        "schedule": st_sched == 200 and sch["name"] == "month-end-monthly" and sch["monthly_day"] == 2 and sch["daily_at"] == "03:15" and "previous" in sch["args"]
+                    and st_l3 == 200 and lst3["schedule"]["name"] == "month-end-monthly",
+        "page": "Month-end packet" in page_src and "/api/month-end/run" in page_src and "/api/month-end/schedule" in page_src,
+        "cli": r_cli.returncode == 0 and "month-end 2026-07 (closed)" in r_cli.stdout and r_prev.returncode == 0 and f"month-end {ME.previous_period()} (closed)" in r_prev.stdout,
+        "help": any(t["topic"] == "month-end" for t in H.topics()) and not H.check("month-end") and "does not recompute" in help_md.split("will not call a measurement")[1],
+    }
+    failed2 = [k for k, v in c2.items() if not v]
+    ok(not failed2,
+       "BM2 the Reports page carries the packet card: the packets on record with their index and archive, the period defaulting to the last closed "
+       "month, Assemble as a job (a malformed period refused) whose INDEX the page then serves, Schedule monthly for an administrator only (day 1..28) "
+       "as the `month-end-monthly` entry for the previous month; `gea workspace --action month-end` with a period or with 'previous'; the help page "
+       "says the index collects and does not recompute"
+       + (f" [failed: {', '.join(failed2)}; cli={r_cli.stdout[-200:]!r} {r_cli.stderr[-200:]!r}]" if failed2 else ""))
+
+
+def section_bn_soak(tmp: str) -> None:
+    """Section BN - the soak: the link relay cuts and restores a connection; the patches, the ETP store and the
+    SeedLink station through relays under scheduled outages, every one back and receiving, SeedLink without a gap,
+    the page answering; the Soak Report; the CLI, the page row, the guard on plain-text deliverables."""
+    import socket as _socket
+    import subprocess as _sp
+    from . import soak as SK
+    from . import helplib as H
+    from .client_reports import forbidden_terms, guard_text
+    pkg = Path(__file__).parent
+    d = Path(tmp, "bn"); d.mkdir()
+
+    # -- the relay alone: bytes through, a cut severs, a restore accepts again on the same port -------------------------
+    echo = _socket.socket(); echo.setsockopt(_socket.SOL_SOCKET, _socket.SO_REUSEADDR, 1); echo.bind(("127.0.0.1", 0)); echo.listen(4); echo.settimeout(5)
+    eport = echo.getsockname()[1]
+
+    def echo_once():
+        try:
+            c, _ = echo.accept(); c.settimeout(5)
+            while True:
+                b = c.recv(4096)
+                if not b:
+                    break
+                c.sendall(b.upper())
+        except OSError:
+            pass
+    threading.Thread(target=echo_once, daemon=True).start()
+    rl = SK.LinkRelay(("127.0.0.1", eport)); rl.start()
+    cl = _socket.create_connection(("127.0.0.1", rl.port), timeout=5); cl.sendall(b"ping"); back = cl.recv(16)
+    rl.cut()
+    severed = False
+    try:
+        cl.settimeout(2); cl.sendall(b"x"); r_ = cl.recv(16); severed = r_ == b""
+    except OSError:
+        severed = True
+    refused = False
+    try:
+        _socket.create_connection(("127.0.0.1", rl.port), timeout=1).close()
+    except OSError:
+        refused = True
+    threading.Thread(target=echo_once, daemon=True).start()
+    rl.restore(); time.sleep(0.3)
+    cl2 = _socket.create_connection(("127.0.0.1", rl.port), timeout=5); cl2.sendall(b"again"); back2 = cl2.recv(16); cl2.close()
+    rl.stop(); echo.close()
+    ok(back == b"PING" and severed and refused and back2 == b"AGAIN" and rl.stats["cuts"] >= 1 and rl.stats["connections"] == 2 and rl.stats["bytes_to_target"] >= 9,
+       "BN1 the link relay: bytes flow both ways to the target; a cut closes the listener and severs every carried connection (a client's next "
+       "read sees the link gone and a new connection is refused); a restore listens again on the same port and carries a new connection")
+
+    # -- the soak itself, short: two WITS0 patches, the ETP store, the SeedLink station, two outages, the page ----------
+    res = SK.run(seconds=75, patches=2, etp=True, seedlink=True, outage_every_s=22, outage_s=5, interval_s=0.5, with_service=True, out_dir=str(d / "out"),
+                 reconnect_budget_s=30, verbose=False)
+    per = {p["protocol"]: p for p in res["per_source"]}
+    rep_md = (d / "out" / "soak_report.md").read_text(encoding="utf-8") if (d / "out" / "soak_report.md").exists() else ""
+    c = {
+        "ran_two_outages": len(res["outages"]) >= 2 and all(o["connections_cut"] >= 4 for o in res["outages"]),
+        "every_source_back": all(o["all_back"] for o in res["outages"]) and res["checks"]["every_outage_recovered"],
+        "down_during": all(set(o["down_during"]) >= {"station"} or len(o["down_during"]) >= 1 for o in res["outages"]),
+        "wits0_loss_counted": per["wits0"]["lost"] is not None and per["wits0"]["lost"] >= 1 and ("no replay" in per["wits0"]["resume"] or "gone" in per["wits0"]["resume"]),
+        "etp_no_replay_named": per["etp"]["lost"] is None and "store" in per["etp"]["resume"] and per["etp"]["received"] > 0,
+        "seedlink_resumed": per["seedlink"]["gaps"] == 0 and per["seedlink"]["lost"] == 0 and per["seedlink"]["reconnects"] >= 1 and "sequence" in per["seedlink"]["resume"],
+        "all_connected_at_end": res["checks"]["all_connected_at_end"] and all(p["status"] == "CONNECTED" for p in res["per_source"]),
+        "page_answered": res["service"]["probes_during_outage"] >= 2 and res["checks"]["page_answered_through_outages"],
+        "verdict_ok": res["ok"] and "OK" in res["verdict"] and "no gap" in res["verdict"],
+        "report_written": res.get("report") and os.path.isfile(res["report"]) and "Outages and recovery" in rep_md and "does not call a measurement" in rep_md
+                           and not forbidden_terms(rep_md) and os.path.isfile(d / "out" / "soak.json"),
+    }
+    failed = [k for k, v in c.items() if not v]
+    ok(not failed,
+       "BN2 the soak: two WITS0 patches, the ETP store and the SeedLink station through relays, the link cut twice on schedule - every source "
+       "down during the cut and back, CONNECTED and receiving, within the budget after it; WITS0's loss counted as the protocol's own (no replay), "
+       "the ETP store's new session named, SeedLink resumed by sequence number with no gap; the page answered through the outages; all connected "
+       "at the end; the Soak Report written with the outage table and what it does not call a measurement, clean of internal-register terms"
+       + (f" [failed: {', '.join(failed)}; verdict={res['verdict']!r}; outages={json.dumps(res['outages'], default=str)[:600]}]" if failed else ""))
+
+    # -- the CLI, the page, the help, the guard on plain text -----------------------------------------------------------
+    r_cli = _sp.run([sys.executable, "-m", "gea", "soak", "--seconds", "30", "--patches", "1", "--no-etp", "--no-seedlink", "--outage-every", "10", "--outage-len", "3", "--json"],
+                    capture_output=True, text=True)
+    try:
+        cli = json.loads(r_cli.stdout)
+    except ValueError:
+        cli = {}
+    page_src = (pkg / "web" / "app.html").read_text(encoding="utf-8")
+    help_md = (pkg / "help" / "soak.md").read_text(encoding="utf-8")
+    guard_err = None
+    try:
+        guard_text("a line that calls itself honest", "a test text")
+    except ValueError as e:
+        guard_err = str(e)
+    from .survey_cmd import run_survey
+    txt, _ = run_survey(demo=True)
+    ok(r_cli.returncode == 0 and cli.get("ok") is True and len(cli.get("outages", [])) >= 1 and cli["config"]["patches_wits0"] == 1 and cli["config"]["seedlink"] is False
+       and "data-v=\"soak\"" in page_src and "Soak" in page_src and "172 checks" not in page_src
+       and any(t["topic"] == "soak" for t in H.topics()) and not H.check("soak") and "declared, not observed" in help_md.split("will not call a measurement")[1]
+       and guard_err and "internal-register" in guard_err and not forbidden_terms(txt) and "does not call a measurement" in txt,
+       "BN3 `gea soak --json` runs the schedule and exits 0 on OK; the Verification page carries the soak row and button and no longer names a "
+       "gate count typed by hand; `gea help soak`; `guard_text` is the client-report guard for plain text, and the strata survey's report passes it "
+       "(its closing line and its NOT ESTIMATED section reworded)")
+
 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:
@@ -5939,6 +6163,8 @@ def main() -> int:
         section_bj_etp(tmp)
         section_bk_seedlink(tmp)
         section_bl_backup(tmp)
+        section_bm_month_end(tmp)
+        section_bn_soak(tmp)
     if _FAILS:
         print(f"[ACCEPTANCE] {len(_FAILS)} FAILURES ({_PASS} passed):")
         for f in _FAILS:

{gea_program-0.18.0 → gea_program-0.20.0}/gea/blind_harness.py

@@ -103,6 +103,6 @@ def accuracy_report() -> Dict:
             'worst_mae_pct': (ok[-1]['mae_pct'] if ok else None),
             'median_coverage': (statistics.median(cov) if cov else None),
             'method': ('leave-one-out over the same machinery clients get; '
-                         'coverage targets ~0.68 (honest 1-sigma); refusals '
+                         'coverage targets ~0.68 (a true 1-sigma); refusals '
                          'listed, never hidden; regenerated live so the '
                          'accuracy table can never be a stale snapshot')}

{gea_program-0.18.0 → gea_program-0.20.0}/gea/client_reports.py

@@ -1784,6 +1784,15 @@ def forbidden_terms(text: str) -> List[str]:
     return [t for t in FORBIDDEN_TERMS if t in low]
 
 
+def guard_text(text: str, what: str = 'a client deliverable') -> str:
+    """The guard `write` applies to rendered reports, for any other text the program hands a client - a plain-text
+    report, a printed summary: raise if an internal-register term is in it. Returns the text unchanged."""
+    bad = forbidden_terms(text)
+    if bad:
+        raise ValueError(f'{what} contains internal-register terms: {sorted(set(bad))}')
+    return text
+
+
 def write(doc: Document, out_dir: str, basename: str = 'gauge_drift_report') -> dict:
     """Write markdown, HTML, the machine JSON, the records CSV and the tag
     catalogue CSV. Returns the paths. Raises if the rendered report contains

{gea_program-0.18.0 → gea_program-0.20.0}/gea/correlation.py

@@ -151,5 +151,5 @@ def depth_frame_pairs(em: EarthModel = None, target_bins: int = TARGET_BINS,
             'n_refused': len(refused),
             'finding': ('the library currently supports %d cross-site '
                         'depth-frame correlations; %d candidate pairs '
-                        'refused thin - the honest census, not a failure'
+                        'refused thin - the census as it stands, not a failure'
                         % (len(ok), len(refused)))}

{gea_program-0.18.0 → gea_program-0.20.0}/gea/help/TESTER_GUIDE.md

@@ -57,7 +57,7 @@ BROWSER" below. `verify.cmd` runs the full test from the kit.
 
 16. In a few seconds a report appears that starts with:
 
-        GEA SURVEY - one well, one honest answer
+        GEA SURVEY - one well, one answer with its provenance
 
 ## PART 5 — YOU'RE DONE. CHECK THESE THREE THINGS:
 
@@ -65,7 +65,7 @@ BROWSER" below. `verify.cmd` runs the full test from the kit.
     scientific well, public archive).
 18. Find the line starting with **CROSS-CHECK**. The program checks its own
     answer against the well's real measurement — it should say about **+0.7%**.
-19. Find the section **"what this tool refused to guess."** That is on
+19. Find the section **"what this tool does not call a measurement."** That is on
     purpose. This program tells you when it doesn't know something instead
     of making it up.
 

gea_program-0.20.0/gea/help/month-end.md

@@ -0,0 +1,11 @@
+# The month-end packet
+
+> A client's month was five or six commands and a walk through the reports folder. The packet is that month assembled once: the refresh for the period, then every report the program writes for every well, site, station and track, collected into one dated folder and one archive, with an index that says item by item what is there and what is not, and a manifest of every file's hash.
+
+**The command**: `gea workspace --path C:\site --action month-end --period 2026-09` (or `--period previous`, the last closed month; `--no-refresh` collects the reports as they stand; `--catalog` hands the regulator's catalogue CSV to the SRA packet). On the dashboard: Reports -> Month-end packet -> the period and Assemble (a job), and for an administrator Schedule monthly (a schedule entry, `month-end-monthly`, on the day and hour given, for the previous month). The result is `reports/month_end/<period>/` with `INDEX.html` / `.md` / `.json` and `MANIFEST.json`, and `reports/month_end/month_end_<site>_<period>.zip`; each packet is logged in `records/month_end.jsonl` and in the audit (`month_end.assemble`).
+
+**What it writes**: for the site - the dashboard index, the accuracy statement, the SLA month for that period, the FAT/SAT protocol, the model cards and the SBOM; for every well - the gauge drift report, the alarm event report, the well-test validation, the shut-in / build-up report, the data resilience report, the machine vibration report, and the certificate register's conformity against ISO/IEC 17025 7.8 as it stands; for every site - the SRA packet for the period (when a Seismicity Response Area is defined) and the site report; for every seismic station and track - their reports. Each item is INCLUDED with its files or NOT AVAILABLE with the reason (no machine record, no SRA defined, no certificate register, no well test detected, never refreshed); every step that failed is listed; a month that has not ended is marked OPEN.
+
+**The number to check**: `N INCLUDED, M NOT AVAILABLE, 0 FAILED` on the index's front page, and `closed: yes` for a month that has ended.
+
+**What this page will not call a measurement**: an item that is NOT AVAILABLE - the reason names what the site lacks, and the packet never stands in for it. A number in any of the reports - each carries its own method and declarations; the index collects and does not recompute. A month that has not ended - the packet says OPEN and the one assembled after the month closes supersedes it. A packet whose files no longer match its manifest - `MANIFEST.json` is the check, and a packet is rebuilt whole, never merged.

gea_program-0.20.0/gea/help/soak.md

@@ -0,0 +1,11 @@
+# The soak
+
+> The load test says whether the machine carries the site's patches with the page still answering. The soak says what happens to those patches when the link goes down and comes back, again and again, over hours - how long each protocol takes to reconnect, what it loses while the link is down, whether the resume leaves a gap, whether the page keeps answering - with the supervisor's own numbers, not a model's.
+
+**The command**: `gea soak --hours 72 --patches 4 --outage-every 600 --outage-len 60 --with-service --out C:\site\reports\soak` runs N WITS0 patches, an ETP patch and a SeedLink live station through link relays on this machine, cuts every relay for the declared seconds on the declared interval, and writes `soak.json` and the Soak Report into `--out`; `--patches` is the site's own patch count. On the dashboard, Verification -> Soak (15 min) runs a short one as a job at the site's patch count with outages of 20 s every 2 min; the 72-hour run is a command-line job for the machine that will serve the site. `gea help soak`.
+
+**What it writes**: per outage - when the link was cut, for how long, how many connections it carried, which sources were down during it, and how many seconds after the link came back each source was CONNECTED and receiving again (or NOT BACK within the budget); per source - received, produced, lost (WITS0's frames sent while the link was down, which the protocol does not replay), gaps (SeedLink's, which must be zero: the resume by sequence number is the proof), reconnection attempts, latency p95, and how the protocol resumes; the page's answer time outside and during the outages when `--with-service`; the checks - all connected at the start and at the end, every outage recovered within the budget, no SeedLink gap, the page answering - and the verdict.
+
+**The number to check**: `every source back within N s`, with N under the budget; `SeedLink resumed with no gap`; the page p95 during outages under a second; `OK`.
+
+**What this page will not call a measurement**: the field link - these are relays on the loopback and the outage lengths were declared, not observed. A protocol's loss recovered - WITS0 and ETP frames sent while the link was down are gone by the protocol's nature; they are counted, never recovered, and the store-and-forward buffer the Data Resilience report models is the answer to that, not this soak. A soak shorter than asked - the summary says how long it ran. A site's real patch count - run it at the number the site will carry.

{gea_program-0.18.0 → gea_program-0.20.0}/gea/helplib.py

@@ -46,9 +46,11 @@ INDEX: List[tuple] = [
     ('conformance', 'Conformity, in the standards\' words', 'certificates against ISO/IEC 17025 7.8 and the bias against its class under a named ILAC-G8 decision rule'),
     ('etp', 'WITSML 2.x over ETP', 'the live port on Energistics ETP v1.2: subscribe to the store\'s channels and it pushes'),
     ('seedlink', 'Live stations (SeedLink)', 'the seismic leg\'s live port: a station\'s records as it writes them, resumed by sequence number, folded into its record list'),
+    ('month-end', 'The month-end packet', 'the month\'s deliverable assembled once: every report collected, INCLUDED or NOT AVAILABLE with the reason, hashed'),
     ('backup', 'The backup', 'the site copied off the machine, verified, and restored once before it is trusted'),
     ('doctor', 'Which code is running', 'gea doctor and the serve start-up gate'),
     ('audit-update', 'Audit / Update', 'the whole audit log with filters, the program against PyPI, every report against its source'),
+    ('soak', 'The soak', 'the patches through link outages for hours: reconnection, resume, loss by protocol, the page answering - measured, not modelled'),
     ('upkeep', 'Upkeep', 'housekeeping, sessions, the TLS proxy, the load test'),
 ]
 # the four lines every page must carry, in this order