gea-program 0.31.0__tar.gz → 0.32.0__tar.gz

{gea_program-0.31.0 → gea_program-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.31.0
+Version: 0.32.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 (380 checks)
+gea accept                     # the product gate (383 checks)
 gea help drift                 # the help library, by the job (16 pages; the same text is on every dashboard page)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")
@@ -648,6 +648,23 @@ 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 setup checklist
+
+The Setup tab (`#/setup`, `gea checklist --workspace C:\site`) says what a
+workspace still needs before its reports can be handed over, read from the
+workspace as it stands: an administrator, the wells, a site record naming
+the client, a backup folder off the machine, a current backup, the daily
+schedule, current reports, and for each well its surface location and
+datum, its reference elevation with its source, and its US Well Number.
+Each item carries its own form or button - declare the position, take the
+ground level from USGS 3DEP to check, create the site, back up now - and,
+where every value is already known, the command to paste. The tab's badge
+counts the required items still to do and the Home page names the next
+one. A drilling record's depth events are confirmed by a person against
+the daily drilling reports, with a note; the confirmation stops counting
+if the record changes. `gea checklist` exits 0 when everything required is
+done. `gea help setup`.
+
 ### Tools and ports
 
 The Tools & ports tab (`#/tools`, `gea tools`) opens on the **downhole tool

{gea_program-0.31.0 → gea_program-0.32.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 (380 checks)
+gea accept                     # the product gate (383 checks)
 gea help drift                 # the help library, by the job (16 pages; the same text is on every dashboard page)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")
@@ -609,6 +609,23 @@ 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 setup checklist
+
+The Setup tab (`#/setup`, `gea checklist --workspace C:\site`) says what a
+workspace still needs before its reports can be handed over, read from the
+workspace as it stands: an administrator, the wells, a site record naming
+the client, a backup folder off the machine, a current backup, the daily
+schedule, current reports, and for each well its surface location and
+datum, its reference elevation with its source, and its US Well Number.
+Each item carries its own form or button - declare the position, take the
+ground level from USGS 3DEP to check, create the site, back up now - and,
+where every value is already known, the command to paste. The tab's badge
+counts the required items still to do and the Home page names the next
+one. A drilling record's depth events are confirmed by a person against
+the daily drilling reports, with a note; the confirmation stops counting
+if the record changes. `gea checklist` exits 0 when everything required is
+done. `gea help setup`.
+
 ### Tools and ports
 
 The Tools & ports tab (`#/tools`, `gea tools`) opens on the **downhole tool

{gea_program-0.31.0 → gea_program-0.32.0}/gea/__init__.py

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

{gea_program-0.31.0 → gea_program-0.32.0}/gea/__main__.py

@@ -468,6 +468,13 @@ def main(argv=None) -> int:
     p_ws.add_argument("--sat", action="store_true", help="refresh: also run the SAT protocol")
     p_ws.add_argument("--outage", action="append", default=None, help="refresh: outage window start/end (ISO), repeatable")
 
+    p_ck = sub.add_parser("checklist", help="the setup checklist: what this workspace still needs before its reports can be handed over - read from the workspace as it stands")
+    p_ck.add_argument("--workspace", type=str, default=None, help="the workspace folder, e.g. C:\\site")
+    p_ck.add_argument("--json", action="store_true")
+    p_ck.add_argument("--confirm", type=str, default=None, help="record a person's check of a confirmation item, e.g. events:Well-30636033")
+    p_ck.add_argument("--note", type=str, default="", help="--confirm: what it was checked against (required)")
+    p_ck.add_argument("--actor", type=str, default="cli")
+
     p_sv = sub.add_parser("serve", help="serve the dashboard over a workspace: the page, the reports and the JSON API (standard library HTTP)")
     p_sv.add_argument("--workspace", type=str, required=True, help="the workspace folder (gea workspace --action init)")
     p_sv.add_argument("--host", type=str, default="127.0.0.1", help="bind address; 0.0.0.0 exposes it on the site network (put TLS in front)")
@@ -1890,6 +1897,31 @@ def main(argv=None) -> int:
     elif a.cmd == "update":
         from .doctor import update as _update
         return _update(check_only=a.check, extras=a.extras, as_json=a.json)
+    elif a.cmd == "checklist":
+        import json as _json
+        from . import setup_checklist as _SC
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        if not a.workspace:
+            raise SystemExit("checklist needs --workspace, e.g. --workspace C:\\site")
+        try:
+            ws = Workspace(a.workspace)
+        except WorkspaceError as e:
+            raise SystemExit(f"checklist: {e}")
+        if a.confirm:
+            try:
+                rec = _SC.confirm(ws, a.confirm, a.actor, a.note)
+            except ValueError as e:
+                raise SystemExit(f"checklist: {e}")
+            print(f"confirmed {a.confirm} by {rec['by']} at {rec['utc']}: {rec['note']}")
+            return 0
+        r = _SC.checklist(ws)
+        if a.json:
+            print(_json.dumps(r, indent=1))
+        else:
+            print(_SC.text(r))
+        return 0 if r["ready"] else 2
     elif a.cmd == "serve":
         from .service import Service
         from .workspace import WorkspaceError
@@ -2078,16 +2110,19 @@ def main(argv=None) -> int:
                     print(f"3DEP ground elevation {r['elev_ft']:,.2f} ft ({r['source']})")
                 elif a.ref_elev_ft is not None or a.ref_elev_datum or a.ref_elev_source:
                     surface["elevation"] = {"ft": a.ref_elev_ft, "datum": a.ref_elev_datum, "source": a.ref_elev_source}
-                disposal = {k: v for k, v in {"api_number": a.api, "uic_number": a.uic, "depth_tier": a.depth_tier, "formation_basis": a.formation,
+                identity = {"api_number": a.api} if a.api else {}
+                disposal = {k: v for k, v in {"uic_number": a.uic, "depth_tier": a.depth_tier, "formation_basis": a.formation,
                                               "channel_pressure": a.channel_pressure, "channel_rate": a.channel_rate, "rate_unit": a.rate_unit,
                                               "bhp_method": a.bhp_method, "channel_bhp": a.channel_bhp, "top_interval_ft": a.top_interval_ft,
                                               "base_interval_ft": a.base_interval_ft, "depth_reference": a.depth_ref,
                                               "gradient_psi_ft": a.gradient_psi_ft}.items() if v is not None}
-                if not surface and not disposal:
+                if a.api and (disposal or (ws.well(a.well).get("disposal") or {})):
+                    disposal["api_number"] = a.api          # a disposal well keeps its number in the block the SRA packet reads too
+                if not surface and not disposal and not identity:
                     raise SystemExit("set-well: nothing to declare (give --lat/--lon, --ref-elev-ft, or any of --api --uic --depth-tier --top-interval-ft ...)")
                 surface = surface or None
-                w = ws.set_well(a.well, surface=surface, disposal=disposal or None, actor=a.actor)
-                print(f"well {a.well}: surface {w.get('surface')}; disposal {w.get('disposal')}"); return 0
+                w = ws.set_well(a.well, surface=surface, disposal=disposal or None, identity=identity or None, actor=a.actor)
+                print(f"well {a.well}: surface {w.get('surface')}; identity {w.get('identity')}; disposal {w.get('disposal')}"); return 0
             elif a.action == "sra-define":
                 if not a.site or not a.name or a.lat is None or a.lon is None or a.radius_km is None or not a.plan_date:
                     raise SystemExit("sra-define needs --site, --name, --lat, --lon, --radius-km and --plan-date")

{gea_program-0.31.0 → gea_program-0.32.0}/gea/acceptance_tests.py

@@ -8005,6 +8005,171 @@ def section_bz_tool_library(tmp: str) -> None:
        "a placeholder; the help page"
        + (f" [failed: {', '.join(failed3)}]" if failed3 else ""))
 
+
+def section_ca_setup_checklist(tmp: str) -> None:
+    """Section CA - the setup checklist: what a workspace still needs before its reports can be handed over, read from
+    the workspace as it stands, each item with its form, button or command; a producing well's US Well Number declared as
+    its identity, not as a disposal well's; a drilling record with depth events written through the client-report guard."""
+    import http.cookiejar
+    import subprocess as _sp
+    import urllib.request
+    import urllib.error
+    from . import edr as E
+    from . import backup as BK
+    from . import ppdm as PP
+    from . import helplib as H
+    from . import setup_checklist as SC
+    from .client_reports import FORBIDDEN_TERMS
+    from .workspace import Workspace
+    from .service import Service, Users
+    pkg = Path(__file__).parent
+    d = Path(tmp, "ca"); d.mkdir()
+
+    def _raises(fn, exc, words=""):
+        try:
+            fn()
+        except exc as e:
+            return words in str(e)
+        return False
+
+    ev = E.selftest_events(str(d))
+    wsp = str(d / "ws"); ws = Workspace.create(wsp, "Pad 3", actor="tester")
+    w = ws.add_well_file(ev["path"], display="Well 30693545", actor="tester")
+    ws.refresh_dashboard(actor="tester")
+    rdir = Path(wsp, "reports", "wells", w["id"])
+    rec = json.loads((rdir / "drilling_record.json").read_text(encoding="utf-8")) if (rdir / "drilling_record.json").is_file() else {}
+    flat_msg = ""
+    try:
+        E.gamma_lithology(E.gamma_log(E.read(ev["path"]), keep=E._keep_masks(E.read(ev["path"]), E.depth_events(E.read(ev["path"])))[1]))
+    except ValueError as e:
+        flat_msg = str(e)
+    flat_lith = (rec.get("gamma") or {}).get("lithology") or {}
+    Users(str(Path(wsp, "users.json"))).add("admin1", "admin-pass-12", "admin")
+    r0 = SC.checklist(ws)
+    ids = {i["id"]: i for i in r0["items"]}
+    r_cli0 = _sp.run([sys.executable, "-m", "gea", "checklist", "--workspace", wsp], capture_output=True, text=True)
+    c1 = {
+        "edr_record": rec.get("total_depth_md_ft") == 5750.0 and len(rec.get("depth_events") or []) == 4 and not (rdir / "drilling_record_not_written.json").exists()
+                      and not any(t in json.dumps(rec).lower() for t in FORBIDDEN_TERMS),
+        "items": {"accounts", "wells", "site", "backup_folder", "backup_taken", "backup_schedule", "reports_current", "fleet", "stress", "layers",
+                  f"surface:{w['id']}", f"elevation:{w['id']}", f"api:{w['id']}", f"events:{w['id']}"} == set(ids)
+                 and r0["counts"]["required"] == 10 and r0["counts"]["required_done"] == 3 and r0["next"] == "site" and not r0["ready"]
+                 and ids["accounts"]["status"] == "DONE" and ids["wells"]["status"] == "DONE" and ids["reports_current"]["status"] == "DONE"
+                 and ids[f"surface:{w['id']}"]["status"] == "TO DO" and ids[f"events:{w['id']}"]["level"] == "recommended"
+                 and ids[f"elevation:{w['id']}"]["action"]["needs_surface"] is True,
+        "commands": all("<" not in (i.get("cli") or "") for i in r0["items"]) and ids["reports_current"]["cli"] == f"gea workspace --path {wsp} --action refresh"
+                    and ids[f"surface:{w['id']}"]["cli"] is None and "survey plat" in " ".join(ids[f"surface:{w['id']}"]["needs"]),
+        "text": "3 of 10 required done" in SC.text(r0) and "[ ] Surface location and its datum" in SC.text(r0) and "needs: latitude and longitude" in SC.text(r0)
+                and "Next: A site record ties the wells to the client." in SC.text(r0),
+        "cli": r_cli0.returncode == 2 and "Setup checklist - Pad 3: 3 of 10 required done" in r_cli0.stdout,
+        "confirm_rules": _raises(lambda: SC.confirm(ws, f"events:{w['id']}", "tester", ""), ValueError, "needs a note")
+                         and _raises(lambda: SC.confirm(ws, "site", "tester", "x"), ValueError, "not an item"),
+        "flat_gamma": bool(flat_msg) and "none is invented" in flat_msg and not any(t in flat_msg.lower() for t in FORBIDDEN_TERMS)
+                      and "none is invented" in str(flat_lith.get("why", "")),
+    }
+    SC.confirm(ws, f"events:{w['id']}", "tester", "daily drilling reports 1-3 Jul 2026")
+    c_ok = {i["id"]: i for i in SC.checklist(ws)["items"]}[f"events:{w['id']}"]
+    cf = json.loads(Path(wsp, "config", "checklist.json").read_text(encoding="utf-8"))
+    cf["confirmed"][f"events:{w['id']}"]["basis"] = "2 event(s), TD 5000.0"
+    Path(wsp, "config", "checklist.json").write_text(json.dumps(cf), encoding="utf-8")
+    c_stale = {i["id"]: i for i in SC.checklist(ws)["items"]}[f"events:{w['id']}"]
+    c1["confirm"] = (c_ok["status"] == "DONE" and "confirmed by tester" in c_ok["detail"] and "daily drilling reports 1-3 Jul 2026" in c_ok["detail"]
+                     and c_stale["status"] == "TO DO" and "check again" in c_stale["detail"] and '"checklist.confirm"' in Path(wsp, "records", "audit.jsonl").read_text(encoding="utf-8"))
+    SC.confirm(ws, f"events:{w['id']}", "tester", "daily drilling reports 1-3 Jul 2026")
+    failed1 = [k for k, v in c1.items() if not v]
+    ok(not failed1,
+       "CA1 the checklist read from the workspace: ten required items for a workspace with one drilling-recorder well (the accounts, the wells, a site "
+       "record with the client, the backup folder, a current backup, the daily schedule, current reports, and the well's surface location, reference "
+       "elevation and US Well Number), the fleet and the depth-event check recommended, stress and layers optional; the next item named; a command "
+       "printed only where it can be pasted as it stands; `gea checklist` exits 2 until it is ready; a confirmation needs its note, is kept with the "
+       "name and time, and stops counting when the drilling record changes; a flat gamma curve's message, and the drilling record that carries it, pass "
+       "the client-report guard"
+       + (f" [failed: {', '.join(failed1)}]" if failed1 else ""))
+
+    # the well number: a producing well's identity, not a disposal well's
+    w2 = ws.add_well_file(ev["path"], display="Producer 2", actor="tester")
+    r_api = _sp.run([sys.executable, "-m", "gea", "workspace", "--path", wsp, "--action", "set-well", "--well", w2["id"], "--api", "42-109-33456"], capture_output=True, text=True)
+    w2r = ws.well(w2["id"])
+    ws.set_well(w2["id"], disposal={"uic_number": "000123"}, actor="tester")
+    r_api2 = _sp.run([sys.executable, "-m", "gea", "workspace", "--path", wsp, "--action", "set-well", "--well", w2["id"], "--api", "42-109-33457"], capture_output=True, text=True)
+    w2d = ws.well(w2["id"])
+    ident = PP.well_identity(w2r)
+    ws.remove_well(w2["id"], actor="tester")
+    users = Users(str(Path(wsp, "users.json"))); users.add("op", "operator-pass-1", "operator"); users.add("v", "viewer-pass-1", "viewer")
+    out_dir = str(d / "backups")
+    svc = Service(wsp, port=0, scheduler=False).start()
+    base_url = svc.url.rstrip("/")
+
+    def session(name, pw):
+        o = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()))
+
+        def call(method, path, body=None):
+            req = urllib.request.Request(base_url + path, method=method, data=(json.dumps(body).encode() if body is not None else None))
+            req.add_header("Content-Type", "application/json"); req.add_header("X-GEA-Action", "1")
+            try:
+                with o.open(req, timeout=120) as rr_:
+                    return rr_.status, json.loads(rr_.read())
+            except urllib.error.HTTPError as e:
+                return e.code, json.loads(e.read())
+        call("POST", "/api/login", {"name": name, "password": pw})
+        return call
+    try:
+        view, op, adm = session("v", "viewer-pass-1"), session("op", "operator-pass-1"), session("admin1", "admin-pass-12")
+        st_ck, ck = view("GET", "/api/setup/checklist")
+        st_b0, b0 = view("GET", "/api/badges")
+        st_sv, _ = view("POST", "/api/sites/add", {"display": "Pad 3", "client": "Acme", "wells": [w["id"]]})
+        st_s, site = op("POST", "/api/sites/add", {"display": "Pad 3", "client": "Acme Operating", "wells": [w["id"]]})
+        st_s2, s2 = op("POST", "/api/sites/add", {"display": "Empty", "client": "Acme", "wells": []})
+        st_d1, _ = op("POST", f"/api/wells/{w['id']}/declare", {"surface": {"lat": 31.84, "lon": -104.21, "datum": "NAD83"}})
+        st_d2, _ = op("POST", f"/api/wells/{w['id']}/declare", {"surface": {"elevation": {"ft": 3532.5, "datum": "KB", "source": "completion report W-2"}}})
+        st_d3, wd3 = op("POST", f"/api/wells/{w['id']}/declare", {"identity": {"api_number": "42-109-33456"}})
+        st_bc, _ = adm("POST", "/api/backup/config", {"out_dir": out_dir})
+        st_bs, _ = adm("POST", "/api/backup/schedule", {})
+        st_cv, _ = view("POST", "/api/setup/confirm", {"item": f"events:{w['id']}", "note": "x"})
+        BK.make(wsp, out_dir, actor="tester")
+        st_ck2, ck2 = view("GET", "/api/setup/checklist")
+        st_b1, b1 = view("GET", "/api/badges")
+    finally:
+        svc.stop()
+    r_cli1 = _sp.run([sys.executable, "-m", "gea", "checklist", "--workspace", wsp], capture_output=True, text=True)
+    c2 = {
+        "identity": r_api.returncode == 0 and (w2r.get("identity") or {}).get("api_number") == "42-109-33456" and "disposal" not in w2r
+                    and not any("no US Well Number" in g for g in ident["gaps"]) and PP.declared_api(w2r) == "42-109-33456"
+                    and r_api2.returncode == 0 and (w2d.get("disposal") or {}).get("api_number") == "42-109-33457" and (w2d.get("identity") or {}).get("api_number") == "42-109-33457",
+        "api": st_ck == 200 and ck["counts"]["required"] == 10 and st_b0 == 200 and b0.get("setup_todo") == 7
+               and st_sv == 403 and st_s == 200 and site["client"] == "Acme Operating" and st_s2 == 400 and "nothing in it" in s2.get("error", "")
+               and st_d1 == 200 and st_d2 == 200 and st_d3 == 200 and wd3["identity"]["api_number"] == "42-109-33456" and "disposal" not in wd3
+               and st_bc == 200 and st_bs == 200 and st_cv == 403,
+        "ready": st_ck2 == 200 and ck2["ready"] and ck2["counts"]["required_done"] == 10 and st_b1 == 200 and b1.get("setup_todo") == 0
+                 and r_cli1.returncode == 0 and "Ready to hand over." in r_cli1.stdout and "[x] US Well Number (API)" in r_cli1.stdout
+                 and "42-109-33456 - Texas, county 109" in r_cli1.stdout,
+    }
+    failed2 = [k for k, v in c2.items() if not v]
+    if "ready" in failed2:
+        failed2.append("left: " + ", ".join(i["id"] for i in ck2.get("items", []) if i["level"] == "required" and i["status"] != "DONE"))
+    ok(not failed2,
+       "CA2 done through the page's own calls: a site created with its client (an operator's act, not a viewer's; a site with no wells turned away), "
+       "the surface location, the reference elevation and the US Well Number declared, the backup folder set and the daily backup scheduled by an "
+       "administrator, a backup taken - and the checklist ready, the Setup badge at zero, `gea checklist` exiting 0; a US Well Number declared for "
+       "a producing well is its identity and does not make it a disposal well, while a disposal well's number stays where the SRA packet reads it"
+       + (f" [failed: {', '.join(failed2)}]" if failed2 else ""))
+
+    page_src = (pkg / "web" / "app.html").read_text(encoding="utf-8")
+    help_md = (pkg / "help" / "setup.md").read_text(encoding="utf-8")
+    c3 = {
+        "page": all(x in page_src for x in ("VIEWS.setup", "['#/setup', 'Setup']", "'#/setup': b => [b.setup_todo", "/api/setup/checklist", "/api/setup/confirm",
+                                             "/api/sites/add", 'data-kind="surface"', 'data-kind="elevation"', 'data-kind="api"', 'data-kind="site"',
+                                             'data-kind="backup_folder"', 'data-kind="confirm"', "Go to the next item", 'role="progressbar"', "Ground level from 3DEP",
+                                             "ck-home", "Show done items")),
+        "help": any(t["topic"] == "setup" for t in H.topics()) and not H.check("setup") and H.VIEW_TOPIC.get("setup") == "setup"
+                and "a done item as a correct one" in help_md.split("will not call a measurement")[1],
+    }
+    failed3 = [k for k, v in c3.items() if not v]
+    ok(not failed3,
+       "CA3 the Setup tab with its badge, the Home page's next item, each item's form or button, the progress bar, the done items folded away on "
+       "request; the help page and its view mapping"
+       + (f" [failed: {', '.join(failed3)}]" if failed3 else ""))
+
 def main() -> int:
     print("GEA-Program - ACCEPTANCE SUITE (the product gate)")
     # a handle a job subprocess still holds at the end must not turn a finished gate into a traceback on Windows:
@@ -8086,6 +8251,7 @@ def main() -> int:
         section_bx_pasteable(tmp)
         section_by_edr(tmp)
         section_bz_tool_library(tmp)
+        section_ca_setup_checklist(tmp)
     if _FAILS:
         print(f"[ACCEPTANCE] {len(_FAILS)} FAILURES ({_PASS} passed):")
         for f in _FAILS:

{gea_program-0.31.0 → gea_program-0.32.0}/gea/gamma.py

@@ -81,8 +81,8 @@ def shale_volume(gr: np.ndarray,
     if gr_shale <= gr_clean:
         raise ValueError(
             f"GR_shale ({gr_shale:g}) must exceed GR_clean ({gr_clean:g}) - "
-            "a flat curve carries no lithology contrast (refusing, not "
-            "inventing one)")
+            "a flat curve carries no lithology contrast, and none is "
+            "invented")
     raw = (g - gr_clean) / (gr_shale - gr_clean)
     vsh = np.clip(raw, 0.0, 1.0)
     clamped = int(np.sum((raw < 0.0) | (raw > 1.0)) - np.sum(np.isnan(raw)))

gea_program-0.32.0/gea/help/setup.md

@@ -0,0 +1,11 @@
+# The setup checklist
+
+> What this workspace still needs before its reports can be handed over, read from the workspace as it stands. An item is done because what it asks for is there - a declared surface location, a backup on the disk, a site record naming the client - and to do otherwise, with what is missing named. Required items are counted; recommended and optional ones are shown beside them. The Setup tab carries a badge with the required items still to do, and the Home page says which one is next.
+
+**The command**: the page is Setup on the dashboard. Each item carries its own form or button: the surface location and its datum, the reference elevation (kelly bushing, ground level or derrick floor) with its source - or the ground level from the USGS 3DEP point service at the declared position, to check before declaring - and the US Well Number for each well; Create the site with its client and its wells; the backup folder, Back up now and the daily schedule; Refresh the reports. "Go to the next item" takes you to the first required item not done. At the command line, `gea checklist --workspace C:\site` prints the list and exits 0 when every required item is done, 2 when one is not; `--json` is the machine record. Where every value is known the item prints the command to run as it stands; where the operator must supply a value it names the values and where they come from instead. A drilling record's depth events are confirmed by a person against the daily drilling reports: on the page, or `gea checklist --workspace C:\site --confirm events:Well-30636033 --note "daily drilling reports, 30 Jun to 12 Jul"`.
+
+**What it writes**: the checklist itself writes nothing - it is read fresh each time. Its actions write what they always write: a declaration into the well's record (`set-well`), a site record, the backup configuration, a backup, a schedule entry, the refreshed reports, each in the audit log. A confirmation is kept in `config\checklist.json` with the name, the time and the note, and in the audit log; when the drilling record changes - a different number of events or a different total depth - the confirmation no longer counts and the item says to check again. A US Well Number is declared as the well's identity; it no longer marks a producing well as a disposal well.
+
+**The number to check**: the count of required items done against the count required; each well's declared position against the survey plat, its datum against the plat's, its reference elevation against the completion report, and its US Well Number against the permit - the checklist says a value is declared, not that it is right.
+
+**What this page will not call a measurement**: a declaration - a position, an elevation or a well number is what the operator stated, recorded with who stated it; a 3DEP ground elevation as the kelly bushing - it is the ground at the declared position, NAVD88, and is offered only as ground level; a confirmation as a check the program made - it is a person's, with their note; a done item as a correct one.

{gea_program-0.31.0 → gea_program-0.32.0}/gea/helplib.py

@@ -43,6 +43,7 @@ INDEX: List[tuple] = [
     ('edr', 'The drilling recorder', 'the rig\'s one-second EDR export read as delivered - sections, depths, hours on bottom, the rate of penetration, the recorder\'s MD-TVD table - and what the record will not say'),
     ('dlis', 'The DLIS log', 'a well log as it is delivered (API RP66 V1), read as the standard lays it out: the frames, the channels, what was skipped; into the strata survey'),
     ('historian', 'The historian pull', 'an operator\'s gauge history out of the PI System through PI Web API, read-only, every value with its archive time and flags'),
+    ('setup', 'The setup checklist', 'what this workspace still needs before its reports can be handed over - each well\'s location, elevation and number, the client site, the backup, the reports - read from the workspace as it stands, each with its form or button'),
     ('tools', 'Tools and ports', 'every class of downhole tool in use across the industry with a hover description and a pop-open tutorial, your own fleet with its datasheets, the gauges this program reads with their citations and ratings, the formats and protocols that bring readings in, and the rating check on a tool string'),
     ('field-ports', 'The field ports', 'Modbus RTU on the serial line, DNP3 from the pad RTU, HART-IP from the transmitter itself - read-only, polled, with the stand-ins to rehearse against'),
     ('slip', 'Slip tendency on the mapped faults', 'the declared stress state resolved on each mapped fault around a well: the slip tendency, the pressure to slip, the World Stress Map as the SHmax source, the published Hennings values beside'),
@@ -68,7 +69,7 @@ REQUIRED_LINES = ('**The command**', '**What it writes**', '**The number to chec
 VIEW_TOPIC: Dict[str, str] = {
     'home': 'start', 'wells': 'data-in', 'well': 'drift', 'live': 'patches', 'patch': 'patches', 'files': 'files', 'alarms': 'alarms',
     'approvals': 'well-tests', 'config': 'site', 'reports': 'drift', 'verify': 'start', 'survey': 'data-in', 'jobs': 'site',
-    'admin': 'site', 'prefs': 'site', 'search': 'start', 'welcome': 'start', 'seismic': 'seismic', 'seismic_station': 'seismic', 'track': 'seismic', 'sar': 'seismic', 'sites': 'sites', 'audit': 'audit-update', 'tools': 'tools', 'catalog': 'catalog',
+    'admin': 'site', 'prefs': 'site', 'search': 'start', 'welcome': 'start', 'seismic': 'seismic', 'seismic_station': 'seismic', 'track': 'seismic', 'sar': 'seismic', 'sites': 'sites', 'setup': 'setup', 'audit': 'audit-update', 'tools': 'tools', 'catalog': 'catalog',
 }
 
 

{gea_program-0.31.0 → gea_program-0.32.0}/gea/osdu.py

@@ -144,21 +144,21 @@ def well_record(well: dict, ctx: Context) -> dict:
     ident = P.well_identity(well)
     wn = ident.get('us_well_number') or {}
     data: Dict[str, Any] = {**_common(ctx), 'FacilityName': well.get('display') or well['id'],
-                            'FacilityID': wn.get('api10') if wn.get('status') == 'VALID' else (disp.get('api_number') or well['id']),
+                            'FacilityID': wn.get('api10') if wn.get('status') == 'VALID' else (P.declared_api(well) or well['id']),
                             'FacilityTypeID': ctx.ref('reference-data--FacilityType', 'Well'),
                             'OperatingEnvironmentID': ctx.ref('reference-data--OperatingEnvironment', 'Onshore'),
                             'NameAliases': [{'AliasName': well['id'], 'AliasNameTypeID': ctx.ref('reference-data--AliasNameType', 'UniqueIdentifier')}],
                             'ExtensionProperties': {'gea': {'well_id': well['id'], 'kind': well.get('kind'), 'role': disp.get('role')}}}
-    if disp.get('api_number'):
-        data['NameAliases'].append({'AliasName': disp['api_number'], 'AliasNameTypeID': ctx.ref('reference-data--AliasNameType', 'RegulatoryIdentifier')})
+    if P.declared_api(well):
+        data['NameAliases'].append({'AliasName': P.declared_api(well), 'AliasNameTypeID': ctx.ref('reference-data--AliasNameType', 'RegulatoryIdentifier')})
     if wn.get('status') == 'VALID':
         # the US Well Number as the standard writes it: the ten-digit well origin, typed; the state named in the extension
         data['NameAliases'].append({'AliasName': wn['api10'], 'AliasNameTypeID': ctx.ref('reference-data--AliasNameType', 'USWellNumber')})
         data['ExtensionProperties']['gea']['us_well_number'] = {'api10': wn['api10'], 'api12': wn.get('api12'), 'api14': wn.get('api14'),
                                                                'state': wn['state'], 'county_code': wn['county']['code'],
                                                                'unique_well': wn['unique_well'], 'identifies': wn['identifies']}
-    elif disp.get('api_number'):
-        data['ExtensionProperties']['gea']['us_well_number'] = {'declared': disp['api_number'], 'status': 'INVALID', 'problems': wn.get('problems')}
+    elif P.declared_api(well):
+        data['ExtensionProperties']['gea']['us_well_number'] = {'declared': P.declared_api(well), 'status': 'INVALID', 'problems': wn.get('problems')}
     if disp.get('uic_number'):
         data['NameAliases'].append({'AliasName': disp['uic_number'], 'AliasNameTypeID': ctx.ref('reference-data--AliasNameType', 'PermitNumber')})
     if ctx.operator_org_id:

{gea_program-0.31.0 → gea_program-0.32.0}/gea/ppdm.py

@@ -130,13 +130,19 @@ def parse_well_number(text: Any) -> dict:
 # --------------------------------------------------------------------------------------------------------------
 # the well's identity as "What is a Well" components
 # --------------------------------------------------------------------------------------------------------------
+def declared_api(well: dict) -> Optional[str]:
+    """The US Well Number the operator declared for a well: its identity block, or - for a well declared before the
+    identity block existed - its disposal block."""
+    return ((well.get('identity') or {}).get('api_number') or (well.get('disposal') or {}).get('api_number') or None)
+
+
 def well_identity(well: dict, site: Optional[dict] = None, channels: Optional[List[str]] = None) -> dict:
     """The components of PPDM's "What is a Well" the site can name for this well, from what the operator
     declared (set-well) and what the program holds; every component it cannot name is a gap by name."""
     disp = well.get('disposal') or {}
     surf = well.get('surface') or {}
     wid = well['id']
-    api = parse_well_number(disp.get('api_number')) if disp.get('api_number') else None
+    api = parse_well_number(declared_api(well)) if declared_api(well) else None
     comps: Dict[str, Any] = {}
     gaps: List[str] = []
     aliases: List[dict] = [{'name': well.get('display') or wid, 'type': 'operator name', 'basis': 'the name the operator gave the record'},

{gea_program-0.31.0 → gea_program-0.32.0}/gea/service.py

@@ -1222,7 +1222,16 @@ class App:
         return {'alarms_unacked': unacked, 'alarms_active': active, 'alarms_shelved': shelved, 'approvals_pending': pend,
                 'jobs_running': running, 'jobs_failed_24h': failed,
                 'patches_down': sum(1 for p in pst if p.get('status') in ('DOWN', 'DEGRADED')), 'patches': len(pst),
-                'generated_utc': utc_now_iso()}
+                'setup_todo': self._setup_todo(), 'generated_utc': utc_now_iso()}
+
+    def _setup_todo(self) -> int:
+        """The required setup items not done, for the Setup tab's badge."""
+        try:
+            from . import setup_checklist as _SC
+            c = _SC.checklist(self.ws)['counts']
+            return c['required'] - c['required_done']
+        except Exception:
+            return 0
 
     def since(self, after: Optional[str], limit: int = 50) -> dict:
         """What happened since `after` (ISO UTC; default: the signed-in user's previous sign-in): audit actions grouped, alarm events, jobs."""
@@ -1650,6 +1659,9 @@ def make_handler(app: App):
                 if path == '/api/tools':
                     from . import tool_catalog as _TC
                     return self._json(200, _TC.catalog())
+                if path == '/api/setup/checklist':
+                    from . import setup_checklist as _SC
+                    return self._json(200, _SC.checklist(app.ws))
                 if path == '/api/tools/taxonomy':
                     from . import tool_taxonomy as _TX
                     q = qs.get('q', [''])[0]; cat = qs.get('category', [''])[0] or None
@@ -1880,6 +1892,22 @@ def make_handler(app: App):
                                                                 depth_ft=(float(b['depth_ft']) if b.get('depth_ft') is not None else None), actor=user['name']))
                     except WorkspaceError as e:
                         raise ApiError(404, str(e))
+                if path == '/api/setup/confirm':
+                    App.require(user, 'operator')
+                    from . import setup_checklist as _SC
+                    b = body or {}
+                    try:
+                        return self._json(200, _SC.confirm(app.ws, str(b.get('item') or ''), user['name'], str(b.get('note') or '')))
+                    except ValueError as e:
+                        raise ApiError(400, str(e))
+                if path == '/api/sites/add':
+                    App.require(user, 'operator')
+                    b = body or {}
+                    try:
+                        return self._json(200, app.ws.add_site(str(b.get('display') or '').strip(), wells=[str(x) for x in (b.get('wells') or [])],
+                                                               client=str(b.get('client') or '').strip(), note=str(b.get('note') or ''), actor=user['name']))
+                    except WorkspaceError as e:
+                        raise ApiError(400, str(e))
                 if path == '/api/tools/fleet':
                     App.require(user, 'operator')
                     from . import tool_taxonomy as _TX
@@ -1944,7 +1972,8 @@ def make_handler(app: App):
                     wid = path[len('/api/wells/'):-len('/declare')]
                     b = body or {}
                     try:
-                        return self._json(200, app.ws.set_well(wid, surface=(b.get('surface') or None), disposal=(b.get('disposal') or None), actor=user['name']))
+                        return self._json(200, app.ws.set_well(wid, surface=(b.get('surface') or None), disposal=(b.get('disposal') or None),
+                                                               identity=(b.get('identity') or None), actor=user['name']))
                     except WorkspaceError as e:
                         raise ApiError(400, str(e))
                 if path == '/api/elevation':