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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.19.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 (344 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]")
@@ -740,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.19.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 (344 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]")
@@ -701,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.19.0 → gea_program-0.20.0}/gea/__init__.py

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

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

@@ -392,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)
@@ -915,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

{gea_program-0.19.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")
 
 
@@ -5996,6 +5997,105 @@ def section_bm_month_end(tmp: str) -> None:
        "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:
@@ -6064,6 +6164,7 @@ def main() -> int:
         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.19.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.19.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.19.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.19.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/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.19.0 → gea_program-0.20.0}/gea/helplib.py

@@ -50,6 +50,7 @@ INDEX: List[tuple] = [
     ('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

{gea_program-0.19.0 → gea_program-0.20.0}/gea/service.py

@@ -75,7 +75,7 @@ PBKDF2_ROUNDS = 200_000
 # Commands the page may run as jobs. Anything else is refused (never `serve`, never a shell).
 RUNNABLE = ('accept', 'fat-sat', 'sbom', 'permits', 'sla-report', 'model-cards', 'client-report', 'dashboard', 'workspace', 'drift-monitor',
             'well-test', 'alarms', 'notify', 'swaps', 'certificates', 'transient', 'housekeeping', 'store-forward', 'config', 'reconcile', 'ingest', 'opcua', 'mqtt', 'report', 'gamma', 'bench',
-            'service-life', 'telemetry', 'run', 'wells', 'survey', 'wits0', 'witsml', 'wits0-sim', 'etp', 'etp-sim', 'files', 'doctor', 'update', 'backup')
+            'service-life', 'telemetry', 'run', 'wells', 'survey', 'wits0', 'witsml', 'wits0-sim', 'etp', 'etp-sim', 'files', 'doctor', 'update', 'backup', 'soak')
 WEB_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'web')
 
 
@@ -1375,6 +1375,10 @@ class App:
             return self._job(['fat-sat', '--kind', 'SAT', '--out', os.path.join(self.ws.reports_dir)], user, 'SAT protocol')
         if what == 'sbom':
             return self._job(['sbom', '--out', self.ws.reports_dir], user, 'SBOM')
+        if what == 'soak':
+            n = max(1, len(self.patches.store.list()))        # the site's own patch count, never fewer than one
+            return self._job(['soak', '--patches', str(n), '--seconds', '900', '--outage-every', '120', '--outage-len', '20', '--with-service',
+                              '--out', os.path.join(self.ws.reports_dir, 'soak')], user, f'soak: {n} patch(es) through link outages for 15 min')
         if what == 'standalone':
             tool = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), 'tools', 'standalone_check.py')
             if not os.path.isfile(tool):