gea-program 0.11.1__tar.gz → 0.13.0__tar.gz

{gea_program-0.11.1/gea_program.egg-info → gea_program-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.11.1
+Version: 0.13.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 (320 checks)
+gea accept                     # the product gate (327 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]")
@@ -566,6 +566,42 @@ operation between them written out; a point on an unknown datum gets no WGS
 84 coordinates and is named. Without the operator's partition, ACL and legal
 tag the manifest is NOT LOADABLE and says so. `gea help osdu`.
 
+### The QuakeML catalogue export
+
+The site's own events in the format the regulator's catalogue tools read.
+After `associate`, `gea workspace --action quakeml-export --site <id>
+[--agency "<name>"]` writes `reports/sites/<site>/quakeml/<site>_events.xml`
+as QuakeML 1.2 to the Basic Event Description schema: one event per
+associated event with its origin (the misfit region as the uncertainties,
+depth in metres and "operator assigned" because it was declared, the method
+and the earth model named, the quality block with the counts, the RMS, the
+azimuthal gap and the distances), one pick per station with the record's own
+FDSN codes, one arrival per pick with its residual. Every origin and pick is
+automatic and preliminary in the schema's own words; the catalogue's AGREES
+or DIFFERS is a comment with the catalogue's event id; no magnitude is
+written and a comment says why. The shape is checked the way a reader checks
+it first - identifiers, allowed children, required children, enumerations,
+references - and the file validates against the published XSD. `gea help
+quakeml`; `gea quakeml` runs the labelled scene.
+
+### The well as master data names it
+
+`gea workspace --action well-identity --well <id>` names a well the way the
+operator's master data and a regulator's well file name it: the US Well
+Number (the API number, whose standard PPDM has held since 2010) taken apart
+- state and offshore code, county code, unique well and its range, sidetrack
+and event when given, and which component the number identifies (ten digits
+the Well Origin, twelve a Wellbore, fourteen an event) - and the components
+of PPDM's "What is a Well" the site can name: the Well and its one Origin at
+the declared position on its datum, the Wellbore only when the sidetrack
+code was given, the gauge station as a measured depth along the wellbore,
+the Wellhead Stream as the channels recorded at the wellhead, the Well Set
+as the site, every alias typed. The identity rides on every well row of the
+SRA packet (section 2a) and in the OSDU export's Well and Wellbore records.
+It will not assume a sidetrack, invent an injection interval or a
+completion, or name a county. `gea ppdm --action parse --number ...` takes a
+number apart from the command line; `gea help ppdm`.
+
 ### Audit / Update
 
 The Audit / Update tab holds three things. The whole audit log

{gea_program-0.11.1 → gea_program-0.13.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 (320 checks)
+gea accept                     # the product gate (327 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]")
@@ -527,6 +527,42 @@ operation between them written out; a point on an unknown datum gets no WGS
 84 coordinates and is named. Without the operator's partition, ACL and legal
 tag the manifest is NOT LOADABLE and says so. `gea help osdu`.
 
+### The QuakeML catalogue export
+
+The site's own events in the format the regulator's catalogue tools read.
+After `associate`, `gea workspace --action quakeml-export --site <id>
+[--agency "<name>"]` writes `reports/sites/<site>/quakeml/<site>_events.xml`
+as QuakeML 1.2 to the Basic Event Description schema: one event per
+associated event with its origin (the misfit region as the uncertainties,
+depth in metres and "operator assigned" because it was declared, the method
+and the earth model named, the quality block with the counts, the RMS, the
+azimuthal gap and the distances), one pick per station with the record's own
+FDSN codes, one arrival per pick with its residual. Every origin and pick is
+automatic and preliminary in the schema's own words; the catalogue's AGREES
+or DIFFERS is a comment with the catalogue's event id; no magnitude is
+written and a comment says why. The shape is checked the way a reader checks
+it first - identifiers, allowed children, required children, enumerations,
+references - and the file validates against the published XSD. `gea help
+quakeml`; `gea quakeml` runs the labelled scene.
+
+### The well as master data names it
+
+`gea workspace --action well-identity --well <id>` names a well the way the
+operator's master data and a regulator's well file name it: the US Well
+Number (the API number, whose standard PPDM has held since 2010) taken apart
+- state and offshore code, county code, unique well and its range, sidetrack
+and event when given, and which component the number identifies (ten digits
+the Well Origin, twelve a Wellbore, fourteen an event) - and the components
+of PPDM's "What is a Well" the site can name: the Well and its one Origin at
+the declared position on its datum, the Wellbore only when the sidetrack
+code was given, the gauge station as a measured depth along the wellbore,
+the Wellhead Stream as the channels recorded at the wellhead, the Well Set
+as the site, every alias typed. The identity rides on every well row of the
+SRA packet (section 2a) and in the OSDU export's Well and Wellbore records.
+It will not assume a sidetrack, invent an injection interval or a
+completion, or name a county. `gea ppdm --action parse --number ...` takes a
+number apart from the command line; `gea help ppdm`.
+
 ### Audit / Update
 
 The Audit / Update tab holds three things. The whole audit log

{gea_program-0.11.1 → gea_program-0.13.0}/gea/__init__.py

@@ -122,7 +122,7 @@ from .profile_catalog import (
     read_pangaea_txt,
 )
 
-__version__ = "0.11.1"
+__version__ = "0.13.0"
 __all__ = [
     "aging_rate", "rate_psi_yr", "accuracy_psi",
     "Sensor", "SimulatorConfig", "DownholeEngine",

{gea_program-0.11.1 → gea_program-0.13.0}/gea/__main__.py

@@ -282,7 +282,7 @@ def main(argv=None) -> int:
                       choices=["init", "add-file", "add-catalog", "add-live", "remove", "list", "migrate", "refresh", "audit",
                                "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"])
+                               "set-well", "sra-define", "sra-report", "associate", "osdu-export", "quakeml-export", "well-identity"])
     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")
@@ -315,7 +315,8 @@ def main(argv=None) -> int:
     p_ws.add_argument("--legal-tag", type=str, nargs="*", default=None, help="osdu-export: legal tag(s)")
     p_ws.add_argument("--country", type=str, nargs="*", default=None, help="osdu-export: otherRelevantDataCountries (default US)")
     p_ws.add_argument("--operator-org", type=str, default="", help="osdu-export: the operator's Organisation record id on the platform")
-    p_ws.add_argument("--out", type=str, default=None, help="osdu-export: the folder to write the manifest and files into")
+    p_ws.add_argument("--out", type=str, default=None, help="osdu-export: the folder to write the manifest and files into; quakeml-export: the file to write")
+    p_ws.add_argument("--agency", type=str, default="", help="quakeml-export: the agencyID written in creationInfo (default: the site's name)")
     p_ws.add_argument("--depth-km", type=float, default=6.0, help="associate: the hypocentral depth the location is made under, km (declared)")
     p_ws.add_argument("--rms-tol", type=float, default=0.15, help="associate: the RMS residual an event must fit within, s")
     p_ws.add_argument("--wells", type=str, nargs="+", default=None, help="add-site: well ids of this workspace")
@@ -399,6 +400,12 @@ def main(argv=None) -> int:
 
     p_osdu = sub.add_parser("osdu", help="the OSDU-shaped export: the self-test on a labelled site")
     p_osdu.add_argument("--action", choices=["selftest"], default="selftest")
+    p_ppdm = sub.add_parser("ppdm", help="the well named as the US Well Number and PPDM name it: take a number apart, or run the self-test")
+    p_ppdm.add_argument("--action", choices=["selftest", "parse"], default="selftest")
+    p_ppdm.add_argument("--number", type=str, default=None, help="parse: a US Well Number (10, 12 or 14 digits, dashes optional)")
+    p_qml = sub.add_parser("quakeml", help="the QuakeML 1.2 catalogue export: the self-test on the association leg's labelled scene")
+    p_qml.add_argument("--action", choices=["selftest"], default="selftest")
+    p_qml.add_argument("--out", type=str, default=None, help="where to leave the self-test's file (default: a temporary folder)")
     p_sra = sub.add_parser("sra", help="the Seismicity Response Area packet: the self-test on a labelled scene")
     p_sra.add_argument("--action", choices=["selftest"], default="selftest")
     p_sra.add_argument("--json", action="store_true")
@@ -1496,6 +1503,36 @@ def main(argv=None) -> int:
             return 0
         print(f"notifications: {'configured' if n.cfg else 'not configured'}" + (f" - {len(n.cfg['channels'])} channel(s), {len(n.cfg['rules'])} rule(s), quiet {n.cfg['quiet_s']} s" if n.cfg else " (gea notify --example)"))
         return 0
+    elif a.cmd == "ppdm":
+        from . import ppdm as _P
+        if a.action == "parse":
+            if not a.number:
+                raise SystemExit("ppdm --action parse needs --number")
+            r = _P.parse_well_number(a.number)
+            print(f"{r['input']}: {r['status']}" + (f" - {r['form']}; identifies the {r['identifies'].replace('_', ' ')}" if r.get('form') and r['status'] == 'VALID' else ''))
+            if r.get('state'):
+                print(f"  state {r['state']['code']} ({r['state']['name'] or 'not a state code'}), county {r['county']['code']}, unique well {r['unique_well']['code']}"
+                      f" ({r['unique_well']['range'] or '-'})" + (f"; sidetrack {r['sidetrack']['code']}: {r['sidetrack']['meaning']}" if r.get('sidetrack') else '')
+                      + (f"; event {r['event']['code']}: {r['event']['meaning']}" if r.get('event') else ''))
+            for x in r["problems"]:
+                print(f"  problem: {x}")
+            for x in r.get("notes") or []:
+                print(f"  note: {x}")
+            return 0 if r["status"] == "VALID" else 1
+        r = _P.selftest()
+        print(f"ppdm selftest [{r['label']}]: {r['status']}")
+        for k, v in r["checks"].items():
+            print(f"  {'ok ' if v else 'BAD'} {k}")
+        print(_P.report_text(r["identity"]))
+        return 0 if r["status"] == "OK" else 1
+    elif a.cmd == "quakeml":
+        from . import quakeml as _Q
+        r = _Q.selftest(a.out)
+        print(f"quakeml selftest [{r['label']}]: {r['status']}")
+        for k, v in r["checks"].items():
+            print(f"  {'ok ' if v else 'BAD'} {k}")
+        print(_Q.report_text({**r, 'status': 'WRITTEN' if r['status'] == 'OK' else 'FAILED', 'agency': 'SIMULATION_SELF_TEST site', 'refused': 2}))
+        return 0 if r["status"] == "OK" else 1
     elif a.cmd == "osdu":
         from . import osdu as _O
         r = _O.selftest()
@@ -1753,6 +1790,18 @@ def main(argv=None) -> int:
                                    countries=a.country, operator_org_id=a.operator_org, out_dir=a.out, actor=a.actor)
                 print(_osdu_text(r)); v = r["validate"]
                 print(f"  structure: {'ok' if v['ok'] else 'PROBLEMS'} ({v['records']} record(s))" + ('' if v['ok'] else '; ' + '; '.join(v['problems'][:5]))); return 0
+            elif a.action == "well-identity":
+                from .ppdm import report_text as _ppdm_text
+                if not a.well:
+                    raise SystemExit("well-identity needs --well <id>")
+                r = ws.well_identity(a.well)
+                print(_ppdm_text(r)); return 0
+            elif a.action == "quakeml-export":
+                from .quakeml import report_text as _qml_text
+                if not a.site:
+                    raise SystemExit("quakeml-export needs --site <id>")
+                r = ws.quakeml_export(a.site, agency=a.agency, out=a.out, actor=a.actor)
+                print(_qml_text(r)); return 0 if r["status"] == "WRITTEN" else 1
             elif a.action == "seismic-dataset":
                 r = ws.write_seismic_dataset_report(actor=a.actor)
                 inv = r["inventory"]

{gea_program-0.11.1 → gea_program-0.13.0}/gea/acceptance_tests.py

@@ -4967,6 +4967,247 @@ def section_be_osdu(tmp: str) -> None:
        "file is a named gap; the structure validates; every export is audited; `gea osdu` runs the self-test from the command line")
 
 
+
+def section_bf_quakeml(tmp: str) -> None:
+    """Section BF - the QuakeML catalogue export: the site's own events in the exchange format a regulator's
+    catalogue tool reads, built to the Basic Event Description schema, automatic and preliminary in the
+    schema's own words, with no magnitude and with the catalogue's standing as a comment."""
+    import csv as _csv
+    import subprocess as _sp
+    import xml.etree.ElementTree as _ET
+    from . import quakeml as Q
+    from . import seismic as S
+    from . import seismic_assoc as SA
+    from .workspace import Workspace, WorkspaceError
+    from . import helplib as H
+    pkg = Path(__file__).parent
+    d = Path(tmp, "bf"); d.mkdir()
+    B = lambda t: "{%s}%s" % (Q.NS_BED, t)
+
+    # -- the self-test on the labelled scene, read back ------------------------------------------
+    r = Q.selftest(str(d / "self"))
+    root = _ET.parse(r["path"]).getroot()
+    origins = root.findall(".//" + B("origin"))
+    o = origins[0]
+    lat_u = float(o.find(B("latitude")).find(B("uncertainty")).text); lon_u = float(o.find(B("longitude")).find(B("uncertainty")).text)
+    hu = float(o.find(B("originUncertainty")).find(B("horizontalUncertainty")).text)
+    q = o.find(B("quality"))
+    ok(r["status"] == "OK" and all(r["checks"].values()) and r["label"] == "SIMULATION_SELF_TEST"
+       and root.tag == "{%s}quakeml" % Q.NS_Q and len(origins) == 2
+       and 0 < lat_u < 0.1 and 0 < lon_u < 0.1 and 0 < hu < 10000 and abs(hu - max(lat_u * Q.KM_PER_DEG, 0) * 1000) < 1.0 + hu * 0.5
+       and q.find(B("usedStationCount")).text == "5" and q.find(B("usedPhaseCount")).text == "5"
+       and float(q.find(B("standardError")).text) < 0.05 and 0 < float(q.find(B("azimuthalGap")).text) < 180
+       and 0 < float(q.find(B("minimumDistance")).text) < float(q.find(B("maximumDistance")).text) < 0.2
+       and o.find(B("methodID")).text.startswith("smi:local/gea/method/") and "vp-" in o.find(B("earthModelID")).text
+       and all(float(a.find(B("timeWeight")).text) == 1.0 and abs(float(a.find(B("timeResidual")).text)) < 0.15 and 0 < float(a.find(B("distance")).text) < 0.2
+               for a in o.findall(B("arrival"))),
+       "BF1 the self-test on the association leg's labelled scene: two events written and read back under the QuakeML 1.2 namespaces, five picks "
+       "and five arrivals each, depth in metres with depthType 'operator assigned' because it was declared, the misfit region as the latitude and "
+       "longitude uncertainties in degrees and the horizontal uncertainty in metres, the quality block with the counts, the RMS, the azimuthal gap "
+       "and the epicentral distances in degrees, every arrival with its residual and unit weight, the method and the earth model named, every "
+       "origin and pick automatic and preliminary, the catalogue's AGREES and DIFFERS as comments, the record's own FDSN codes in every waveformID, "
+       "and no magnitude anywhere")
+
+    # -- the shape check catches what a reader would refuse ------------------------------------------
+    text = Path(r["path"]).read_text(encoding="utf-8")
+    broken = []
+    bad1 = text.replace('publicID="smi:local/gea/SYNTHETIC/event/', 'publicID="bad id ', 1); broken.append(Q.validate(_ET.ElementTree(_ET.fromstring(bad1))))
+    bad2 = text.replace("<pickID>smi:local/gea/SYNTHETIC/pick/", "<pickID>smi:local/gea/SYNTHETIC/nopick/", 1); broken.append(Q.validate(_ET.ElementTree(_ET.fromstring(bad2))))
+    bad3 = text.replace("<evaluationStatus>preliminary</evaluationStatus>", "<evaluationStatus>reported</evaluationStatus>", 1); broken.append(Q.validate(_ET.ElementTree(_ET.fromstring(bad3))))
+    bad4 = text.replace("<depthType>", "<depthKind>").replace("</depthType>", "</depthKind>"); broken.append(Q.validate(_ET.ElementTree(_ET.fromstring(bad4))))
+    first_origin_end = text.index("</origin>")
+    bad5 = text[:first_origin_end] + '<magnitude publicID="smi:local/gea/x/mag/1"><mag><value>2.0</value></mag></magnitude>' + text[first_origin_end:]
+    broken.append(Q.validate(_ET.ElementTree(_ET.fromstring(bad5))))
+    bad6 = text.replace("<value>2026-03-05T11:03:", "<value>2026-03-05 11:03:", 1); broken.append(Q.validate(_ET.ElementTree(_ET.fromstring(bad6))))
+    ok(Q.validate(r["path"])["status"] == "VALID_SHAPE" and all(b["status"] == "INVALID" for b in broken)
+       and any("ResourceIdentifier" in p for p in broken[0]["problems"]) and any("pickID" in p for p in broken[1]["problems"])
+       and any("enumeration" in p for p in broken[2]["problems"]) and any("not in the schema" in p for p in broken[3]["problems"])
+       and any("magnitude" in p for p in broken[4]["problems"]) and any("dateTime" in p for p in broken[5]["problems"])
+       and all(Q.RID_PATTERN.match(x) for x in (Q.rid("Pad 3", "event", "assoc 1"), Q.rid("a", "x", authority="ab"), Q.rid("s", "comment", "a/b")))
+       and not Q.RID_PATTERN.match("smi:ab/x") and not Q.RID_PATTERN.match("urn:local/x"),
+       "BF2 the shape check is the first thing a QuakeML reader does, done here: an identifier off the schema's pattern, an arrival whose pick is "
+       "not in its event, an evaluation status outside the enumeration, a child element the schema does not know, a magnitude this program did "
+       "not estimate, and a time that is not an xs:dateTime are each named as a problem; and the identifier builder cleans a site name with a "
+       "space and a short authority to the pattern")
+
+    # -- through the workspace and the command line ---------------------------------------------------
+    sc = SA.synthetic_scene()
+    for sid, tr in sc["traces"].items():
+        S.write_mseed([tr], str(d / f"{sid}.mseed"))
+    cat = d / "cat.csv"
+    with open(cat, "w", newline="") as f:
+        w = _csv.writer(f); w.writerow(["EventID", "Origin Time", "Local Magnitude", "Latitude", "Longitude", "Depth"])
+        for c in sc["catalog"]:
+            w.writerow([c["event_id"], c["time"], c["magnitude"], c["lat"], c["lon"], 6.0])
+    ws = Workspace.create(str(d / "ws"), "Pad 3", actor="tester")
+    ids = [ws.add_seismic_station(sid, [str(d / f"{sid}.mseed")], st.lat, st.lon, "tester", datum=st.datum, band=[2.0, 20.0])["id"]
+           for sid, st in sc["stations"].items()]
+    ws.add_site("QML block", seismic=ids, client="Acme", actor="tester")
+    try:
+        ws.quakeml_export("QML-block"); early = False
+    except WorkspaceError as e:
+        early = "associate" in str(e)
+    run = lambda *a: _sp.run([sys.executable, "-m", "gea", "workspace", "--path", ws.path, "--actor", "tester", *a], capture_output=True, text=True)
+    r1 = run("--action", "associate", "--site", "QML-block", "--catalog", str(cat))
+    aj = json.loads(Path(ws.path, "reports", "sites", "QML-block", "association.json").read_text(encoding="utf-8"))
+    r2 = run("--action", "quakeml-export", "--site", "QML-block", "--agency", "Acme Operating")
+    xml_path = Path(ws.path, "reports", "sites", "QML-block", "quakeml", "QML-block_events.xml")
+    summ = json.loads(Path(ws.path, "reports", "sites", "QML-block", "quakeml", "export_summary.json").read_text(encoding="utf-8"))
+    root2 = _ET.parse(str(xml_path)).getroot()
+    agencies = {c.find(B("agencyID")).text for c in root2.iter(B("creationInfo"))}
+    wids = root2.findall(".//" + B("waveformID"))
+    audit = Path(ws.path, "records", "audit.jsonl").read_text(encoding="utf-8")
+    r3 = _sp.run([sys.executable, "-m", "gea", "quakeml", "--out", str(d / "cli")], capture_output=True, text=True)
+    help_md = (pkg / "help" / "quakeml.md").read_text(encoding="utf-8")
+    ok(early and r1.returncode == 0 and all((v.get("stream") or {}).get("station") == sid for sid, v in aj["stations"].items())
+       and r2.returncode == 0 and "WRITTEN - 2 event(s), 10 pick(s), 10 arrival(s)" in r2.stdout and "VALID_SHAPE" in r2.stdout and "gap:" not in r2.stdout
+       and xml_path.is_file() and summ["status"] == "WRITTEN" and summ["schema"] == "QuakeML-BED-1.2" and summ["n_events"] == 2 and not summ["gaps"]
+       and summ["validate"]["status"] == "VALID_SHAPE" and summ["association_generated_utc"] == aj["generated_utc"]
+       and agencies == {"Acme Operating"} and len(wids) == 10 and all(w.get("networkCode") == "XX" and w.get("channelCode") == "HHZ" for w in wids)
+       and "site.quakeml_export" in audit and r3.returncode == 0 and "SIMULATION_SELF_TEST" in r3.stdout and (d / "cli" / "SYNTHETIC_events.xml").is_file()
+       and H.VIEW_TOPIC.get("quakeml", "seismic") == "seismic" and any(t["topic"] == "quakeml" for t in H.topics()) and not H.check("quakeml")
+       and "operator assigned" in help_md and "preliminary" in help_md and "magnitude" in help_md.split("will not call a measurement")[1],
+       "BF3 `--action quakeml-export` refuses a site that has not been associated, and after `--action associate` (which now keeps each record's "
+       "FDSN codes) writes reports/sites/<site>/quakeml/<site>_events.xml with the agency the operator named in every creationInfo, the record's "
+       "codes in every waveformID, a summary beside it that carries the association's own timestamp, and audits it; `gea quakeml` runs the "
+       "labelled scene from the command line; the help page names the declared depth, the preliminary status and the magnitude it does not write")
+
+    # -- a station without codes or position is named as a gap, never invented ------------------------
+    doc = {"association": {"events": [{"id": "e1", "origin_utc": "2026-03-05T11:03:00.000Z", "lat": 31.95, "lon": -102.25, "depth_km": 6.0,
+                                        "depth_basis": "declared", "rms_s": 0.02, "n_stations": 3, "stations": ["A", "B", "C"], "dropped": [],
+                                        "picks": {"A": {"time": "2026-03-05T11:03:01.000Z", "snr": 10.0, "residual_s": 0.01},
+                                                  "B": {"time": "2026-03-05T11:03:01.200Z", "snr": 9.0, "residual_s": -0.01},
+                                                  "C": {"time": "2026-03-05T11:03:01.400Z", "snr": 8.0, "residual_s": 0.0}},
+                                        "region_km": {"extent_east_km": 1.0, "extent_north_km": 2.0, "nodes": 8, "reaches_grid_edge": False},
+                                        "magnitude": None, "magnitude_basis": "not estimated",
+                                        "model": {"vp_km_s": 5.8, "depth_km": 6.0, "pick_sigma_s": 0.05, "basis": "flat earth"}}],
+                           "refused": [], "n_unused_picks": 0, "model": {}, "basis": "b", "not_a_measurement": []}, "catalogue": None}
+    stations = {"A": {"id": "A", "lat": 31.99, "lon": -102.30, "stream": {"network": "TX", "station": "PB01", "location": "00", "channel": "HHZ"}},
+                "B": {"id": "B", "lat": 31.90, "lon": -102.20},                       # no codes
+                "C": {"id": "C"}}                                                       # no codes, no position
+    b = Q.build(doc, {"id": "s", "name": "Gap site"}, stations, version="0.0")
+    out = Path(d, "gaps.xml"); Q.write(b["tree"], str(out))
+    v = Q.validate(str(out))
+    rootg = _ET.parse(str(out)).getroot()
+    ws_ids = {w.get("stationCode"): w for w in rootg.findall(".//" + B("waveformID"))}
+    arrs = {a.find(B("pickID")).text.rsplit("/", 1)[1]: a for a in rootg.findall(".//" + B("arrival"))}
+    og = rootg.find(".//" + B("origin"))
+    ok(v["status"] == "VALID_SHAPE" and len(b["gaps"]) == 3 and sum("no network and station code" in g for g in b["gaps"]) == 2
+       and sum("no position" in g for g in b["gaps"]) == 1
+       and ws_ids["PB01"].get("networkCode") == "TX" and ws_ids["PB01"].get("locationCode") == "00"
+       and ws_ids["B"].get("networkCode") == "XX" and ws_ids["C"].get("networkCode") == "XX"
+       and arrs["A"].find(B("azimuth")) is not None and arrs["C"].find(B("azimuth")) is None and arrs["C"].find(B("distance")) is None
+       and abs(float(og.find(B("originUncertainty")).find(B("horizontalUncertainty")).text) - 1000.0) < 1e-6
+       and abs(float(og.find(B("latitude")).find(B("uncertainty")).text) - 1.0 / Q.KM_PER_DEG) < 1e-6
+       and og.find(B("quality")).find(B("azimuthalGap")) is not None,
+       "BF4 a station whose record carried no network and station code goes out under the test network XX with its own id and is named as a gap; "
+       "a station with no position gets a pick but an arrival without azimuth or distance and is named as a gap; neither is invented; the misfit "
+       "region of 1 km by 2 km becomes a 1000 m horizontal uncertainty and a latitude uncertainty of one kilometre in degrees")
+
+
+def section_bg_ppdm(tmp: str) -> None:
+    """Section BG - the well named the way the operator's master data names it: the US Well Number taken
+    apart and checked, the PPDM "What is a Well" components the site can name, and the identity carried into
+    the SRA packet and the OSDU export without a sidetrack, an interval or a county name being invented."""
+    import csv as _csv
+    import subprocess as _sp
+    from datetime import datetime as _dt, timedelta as _td, timezone as _tz
+    from . import ppdm as P
+    from . import helplib as H
+    from .client_reports import forbidden_terms
+    from .workspace import Workspace
+    pkg = Path(__file__).parent
+    d = Path(tmp, "bg"); d.mkdir()
+
+    # -- the number ----------------------------------------------------------------------------------
+    r = P.selftest()
+    a = P.parse_well_number("42 329 39123 01 00")
+    b = P.parse_well_number("4232939123")
+    ok(r["status"] == "OK" and all(r["checks"].values())
+       and a["status"] == "VALID" and a["api14"] == "42-329-39123-01-00" and a["identifies"] == "event" and a["event"]["meaning"].startswith("the original")
+       and b["status"] == "VALID" and b["api10"] == "42-329-39123" and b["api12"] is None and b["identifies"] == "well_origin"
+       and len(P.STATE_CODES) == 55 and P.STATE_CODES["42"] == "Texas" and P.STATE_CODES["60"] == "Northern Gulf of Mexico" and "52" not in P.STATE_CODES
+       and P.parse_well_number("42-329-61000")["unique_well"]["range"] == "reserved" and P.parse_well_number("42-329-00500")["unique_well"]["range"] == "historical"
+       and P.parse_well_number("42-329-96000")["unique_well"]["range"] == "exempt"
+       and "booklet" in P.parse_well_number("42-329-39123")["county"]["basis"],
+       "BG1 a US Well Number in any written form is taken apart to the standard - state and offshore codes named (51 states and territories, four "
+       "offshore areas, 52-54 reserved), the county code kept as a code because the county booklet is not held, the unique well placed in the "
+       "standard's historical, current, reserved or exempt range - and ten, twelve and fourteen digits name the Well Origin, a Wellbore and an "
+       "event; a reserved or unknown state, a wrong length, a stray letter and a zero unique well are each named as a problem, never repaired")
+
+    # -- the identity, and what it will not name ---------------------------------------------------
+    ident = r["identity"]; c = ident["components"]
+    ok(c["well"]["identifier"] == "42-329-39123" and c["wellbore"]["identifier"] is None and "sidetrack code" in c["wellbore"]["detail"]
+       and c["well_origin"]["position"]["datum"] == "NAD27" and c["wellhead_stream"]["direction"] == "into the ground"
+       and c["wellbore_contact_interval"]["identifier"] is None and c["wellbore_completion"]["identifier"] is None
+       and all(k in P.COMPONENTS for k in ("well", "well_origin", "wellbore", "wellbore_segment", "wellbore_contact_interval", "wellbore_completion", "wellhead_stream", "well_set"))
+       and "one and only one" in P.COMPONENTS["wellbore_segment"] and "not an activity" in P.COMPONENTS["wellbore_completion"]
+       and sum("not given" in g for g in ident["gaps"]) == 1 and sum("not held here" in g for g in ident["gaps"]) == 1,
+       "BG2 the identity names the Well and its Origin at the declared position on its datum, the Wellhead Stream with its direction, the Well Set "
+       "as the site and every alias typed, and names as not named - with the reason - the Wellbore when the sidetrack code was not given, and the "
+       "Contact Interval and the Completion that are the permit's and the completion report's facts; the component definitions are PPDM's")
+
+    # -- through the workspace: the packet and the OSDU export carry it ----------------------------
+    t0 = _dt(2026, 3, 1, tzinfo=_tz.utc)
+    hist = d / "swd.csv"
+    with open(hist, "w", newline="") as f:
+        w = _csv.writer(f); w.writerow(["timestamp", "P_surf_psi", "Q_bpm"])
+        for i in range(2 * 144):
+            w.writerow([(t0 + _td(seconds=600 * i)).strftime("%Y-%m-%dT%H:%M:%SZ"), "1500.0", "5.0"])
+    ws = Workspace.create(str(d / "ws"), "Pad 3", actor="tester")
+    w1 = ws.add_well_file(str(hist), display="SWD 1", actor="tester", station_md_ft=9800.0)
+    run = lambda *a: _sp.run([sys.executable, "-m", "gea", "workspace", "--path", ws.path, "--actor", "tester", *a], capture_output=True, text=True)
+    r0 = run("--action", "well-identity", "--well", w1["id"])                                       # nothing declared yet
+    r1 = run("--action", "set-well", "--well", w1["id"], "--lat", "31.96", "--lon", "-102.24", "--datum", "NAD27", "--api", "42-329-39123", "--uic", "123456",
+             "--depth-tier", "deep", "--formation", "completed below the base of the Wolfcamp", "--channel-pressure", "P_surf_psi", "--channel-rate", "Q_bpm",
+             "--rate-unit", "bbl/min", "--bhp-method", "calculated")
+    r2 = run("--action", "add-site", "--name", "PPDM block", "--wells", w1["id"], "--client", "Acme Operating")
+    r3 = run("--action", "well-identity", "--well", w1["id"])
+    r4 = run("--action", "sra-define", "--site", "PPDM-block", "--name", "Test SRA", "--lat", "31.95", "--lon", "-102.25", "--datum", "WGS84",
+             "--radius-km", "9.08", "--plan-date", "2026-02-25")
+    r5 = run("--action", "sra-report", "--site", "PPDM-block")
+    out = Path(ws.path, "reports", "sites", "PPDM-block")
+    md = (out / "sra_packet.md").read_text(encoding="utf-8"); html = (out / "sra_packet.html").read_text(encoding="utf-8")
+    pkj = json.loads((out / "sra_packet.json").read_text(encoding="utf-8"))["packet"]
+    ws2 = Workspace(ws.path)
+    o1 = ws2.osdu_export("PPDM-block", partition="opendes", acl_owners=["o"], acl_viewers=["v"], legal_tags=["t"], actor="tester")
+    man1 = json.loads(Path(o1["manifest"]).read_text(encoding="utf-8"))
+    wells1 = [x for x in man1["MasterData"] if x["kind"].endswith(":master-data--Well:1.0.0")]
+    bores1 = [x for x in man1["MasterData"] if x["kind"].endswith(":master-data--Wellbore:1.0.0")]
+    ws2.set_well(w1["id"], disposal={"api_number": "42-329-39123-01"}, actor="tester")
+    o2 = ws2.osdu_export("PPDM-block", partition="opendes", acl_owners=["o"], acl_viewers=["v"], legal_tags=["t"], actor="tester")
+    man2 = json.loads(Path(o2["manifest"]).read_text(encoding="utf-8"))
+    bores2 = [x for x in man2["MasterData"] if x["kind"].endswith(":master-data--Wellbore:1.0.0")]
+    r6 = _sp.run([sys.executable, "-m", "gea", "ppdm", "--action", "parse", "--number", "42-329-39123-01"], capture_output=True, text=True)
+    r7 = _sp.run([sys.executable, "-m", "gea", "ppdm", "--action", "parse", "--number", "53-329-39123"], capture_output=True, text=True)
+    r8 = _sp.run([sys.executable, "-m", "gea", "ppdm"], capture_output=True, text=True)
+    ident_w = pkj["wells"][0]["identity"]
+    ok(r0.returncode == 0 and "no US Well Number declared" in r0.stdout and r1.returncode == 0 and r2.returncode == 0
+       and r3.returncode == 0 and "US Well Number 42-329-39123" in r3.stdout and "state 42 (Texas)" in r3.stdout and "Wellbore: not identified" in r3.stdout
+       and "Well Set: PPDM block" in r3.stdout and "Wellhead Stream: 2 channel(s)" in r3.stdout and "into the ground" in r3.stdout
+       and "9800 ft MD" in r3.stdout and "123456 [UIC permit number]" in r3.stdout
+       and r4.returncode == 0 and r5.returncode == 0 and ident_w["us_well_number"] == "42-329-39123" and ident_w["state"] == "Texas"
+       and ident_w["wellbore"] is None and ident_w["origin_datum"] == "NAD27" and not any("sidetrack" in g or "Completion" in g for g in pkj["gaps"])
+       and "Well identity" in md and "42-329-39123" in md and "not identified" in md and "US Well Number and PPDM" in html
+       and not forbidden_terms(md) and not forbidden_terms(html)
+       and len(wells1) == 1 and wells1[0]["data"]["FacilityID"] == "42-329-39123"
+       and any(al["AliasName"] == "42-329-39123" and al["AliasNameTypeID"].endswith("AliasNameType:USWellNumber:") for al in wells1[0]["data"]["NameAliases"])
+       and wells1[0]["data"]["ExtensionProperties"]["gea"]["us_well_number"]["state"]["name"] == "Texas"
+       and len(bores1) == 1 and bores1[0]["data"]["FacilityID"] == w1["id"] and "not identified" in bores1[0]["data"]["ExtensionProperties"]["gea"]["wellbore_identifier"]
+       and bores2[0]["data"]["FacilityID"] == "42-329-39123-01" and bores2[0]["data"]["ExtensionProperties"]["gea"]["wellbore_identifier"] == "42-329-39123-01"
+       and o2["validate"]["ok"]
+       and r6.returncode == 0 and "identifies the wellbore" in r6.stdout and r7.returncode == 1 and "reserved" in r7.stdout
+       and r8.returncode == 0 and "ppdm selftest" in r8.stdout
+       and any(t["topic"] == "ppdm" for t in H.topics()) and not H.check("ppdm")
+       and "sidetrack code" in (pkg / "help" / "ppdm.md").read_text(encoding="utf-8").split("will not call a measurement")[1],
+       "BG3 `--action well-identity` names a bare well as unidentified and a declared one by its US Well Number, state, origin datum, wellbore "
+       "standing, gauge depth, wellhead stream, well set and typed aliases; the SRA packet carries the identity on every well row and in its own "
+       "table (section 2a) without counting its gaps against the packet, and the packet's prose passes the vocabulary gate; the OSDU export's Well "
+       "record carries the ten-digit number as FacilityID and a typed alias with the state in the extension, and its Wellbore record keeps the "
+       "program's id and says the sidetrack code was not given until a twelve-digit number is declared, when it carries that; `gea ppdm` parses "
+       "a number from the command line with the exit code saying whether it is valid, and runs the self-test; the help page names the sidetrack "
+       "it will not assume")
+
 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:
@@ -5027,6 +5268,8 @@ def main() -> int:
         section_bc_sra(tmp)
         section_bd_association(tmp)
         section_be_osdu(tmp)
+        section_bf_quakeml(tmp)
+        section_bg_ppdm(tmp)
     if _FAILS:
         print(f"[ACCEPTANCE] {len(_FAILS)} FAILURES ({_PASS} passed):")
         for f in _FAILS:

{gea_program-0.11.1 → gea_program-0.13.0}/gea/client_reports.py

@@ -1613,6 +1613,23 @@ def sra_packet_report(pk: dict, evaluated_at: Optional[datetime] = None, program
         f"from the centre, with every position carried to WGS84 first; {m['n_undecided']} could not be placed."],
         [Table(['Well', 'Name', 'API', 'UIC', 'Membership', 'Distance (km)', 'Depth tier', 'BHP method', 'Daily record'], wrows, 'Wells'),
          Table(['Station', 'Name', 'Kind', 'Membership', 'Distance (km)'], srows, 'Seismic stations')]))
+    # the wells named the way the operator's master data names them (v0.13.0)
+    irows = []
+    for w in pk['wells']:
+        i = w.get('identity')
+        if not i:
+            continue
+        irows.append([w['id'], i.get('us_well_number') or '-', (i.get('identifies') or '-').replace('_', ' '), i.get('state') or '-',
+                      i.get('wellbore') or 'not identified', i.get('origin_datum') or '-', '; '.join(i.get('aliases') or []),
+                      '; '.join(g.split(': ', 1)[1] if ': ' in g else g for g in (i.get('gaps') or [])) or '-'])
+    if irows:
+        secs.append(Section('2a', 'The wells as the US Well Number and PPDM name them', [
+            'Each well by its US Well Number taken apart - the state, the county, the unique well - and by the components of PPDM\'s "What is a '
+            'Well" the site can name: the Well and its one Origin at the declared surface position, the Wellbore when the sidetrack code was '
+            'given, the Well Set as the site, and every alias typed. Ten digits name the Well Origin and nothing below it; a Wellbore is named '
+            'only when the regulator\'s sidetrack code was declared. The injection interval and the completion are the permit\'s and the '
+            'completion report\'s facts and are named here as not held.'],
+            [Table(['Well', 'US Well Number', 'Identifies', 'State', 'Wellbore', 'Origin datum', 'Aliases', 'Not named'], irows, 'Well identity')]))
     n = 3
     inside_wells = [w for w in pk['wells'] if w['inside'] and w.get('months')]
     for w in inside_wells:

gea_program-0.13.0/gea/help/ppdm.md

@@ -0,0 +1,11 @@
+# The well as master data names it
+
+> The US Well Number taken apart - state, county, unique well, sidetrack, event - and the components of PPDM's "What is a Well" the site can name for each well: the Well and its one Origin, the Wellbore, the Wellhead Stream, the Well Set, and every alias typed.
+
+**The command**: `gea workspace --path C:\site --action well-identity --well <id>` prints a well's identity from its declarations (`set-well --api --uic --lat --lon --datum`) and the site it belongs to. `gea ppdm --action parse --number 42-329-39123-01` takes a number apart and names every way it is not valid. `gea ppdm` runs the self-test. The identity also rides on every well row of the SRA packet (section 2a) and in the OSDU export's Well record (the ten-digit number as a typed alias and `FacilityID`, the state and the parts in the extension; the Wellbore record's `FacilityID` is the twelve-digit number when it was given).
+
+**What it writes**: the US Well Number in the standard's form `SS-CCC-UUUUU-SS-EE` (the standard the API transferred to the PPDM Association in 2010; PPDM's 2013 US Well Number is its successor): the state or offshore code and its name, the county code, the unique well number and which of the standard's ranges it falls in (historical, current, reserved, exempt), the sidetrack code and the event sequence when given, and which component the number identifies - ten digits the Well Origin, twelve a Wellbore, fourteen an event. Then the components: the Well; the Well Origin at the declared surface position on its datum; the Wellbore, identified only when the sidetrack code was given; the gauge station as a measured depth along the wellbore; the Wellhead Stream as the channels recorded at the wellhead with the declared pressure, rate and bottomhole channels named and the direction (into the ground for a disposal well); the Well Set as the site; the aliases - the operator's name, the program's id, the US Well Number, the UIC permit - each typed.
+
+**The number to check**: `IDENTIFIED` or `UNIDENTIFIED` on the identity, `VALID` or `INVALID` on the number, and the `gap:` lines - every component the site cannot name is named as not named, with the reason.
+
+**What this page will not call a measurement**: a sidetrack code that was not given - ten digits name the Well Origin and nothing below it, and "00" is the original hole only when the regulator assigned it, so a Wellbore is not identified from a ten-digit number. A Wellbore Contact Interval (the injection interval) or a Wellbore Completion - those are the permit's and the completion report's facts, and the identity names them as not held. A county name - the standard's state and county booklet carries it, this program does not, and a county code is checked for its shape only. A state from a reserved code (52-54) or a code outside the standard.

gea_program-0.13.0/gea/help/quakeml.md

@@ -0,0 +1,11 @@
+# The QuakeML catalogue export
+
+> The site's own events - what its stations located together - in QuakeML 1.2, the exchange format a regulator's catalogue tool, a university network's review desk and every seismological package read.
+
+**The command**: `gea workspace --path C:\site --action quakeml-export --site <id> [--agency "<name>"] [--out <file.xml>]`, after `--action associate` has run on the site (the export is built from `reports/sites/<site>/association.json`). `--agency` is the agencyID written in every creationInfo; the site's name by default. `gea quakeml` runs the self-test on the association leg's labelled scene and leaves the file where `--out` says.
+
+**What it writes**: `reports/sites/<site>/quakeml/<site>_events.xml` - a `q:quakeml` document in the QuakeML 1.2 namespaces, built to the Basic Event Description schema (QuakeML-BED-1.2.xsd): one `event` per associated event with its `origin` (time; latitude and longitude with the misfit region's half-extent as their uncertainty in degrees; depth in metres with `depthType` "operator assigned", because the depth was declared; `methodID` and `earthModelID` naming the grid search and the one-velocity flat-earth model; `quality` with the station and phase counts, the RMS as standardError, the azimuthal gap and the epicentral distances in degrees; `originUncertainty` with the misfit region in metres), one `pick` per station that made the event (the onset time with the pick uncertainty, the record's own FDSN codes in `waveformID`, phaseHint P), and one `arrival` per pick on the origin (azimuth, distance, the residual, weight 1). Every origin and pick is `evaluationMode` automatic and `evaluationStatus` preliminary. The catalogue's standing - AGREES, DIFFERS with both positions, NOT IN CATALOGUE - is a comment on the event with the catalogue's own event id. `export_summary.json` beside it carries the counts, the gaps and the shape check. Every export is in `records/audit.jsonl`.
+
+**The number to check**: `shape VALID_SHAPE` on the second line - the first checks a QuakeML reader makes, made here first: the namespaces; every publicID to the schema's ResourceIdentifier pattern and used once; every child element one the schema allows for its parent; time, latitude and longitude on every origin; time and waveformID on every pick; every arrival's pickID a pick of the same event; every event's preferredOriginID one of its origins; every enumerated value in its enumeration. A `gap:` line names a station whose record carried no network and station code (written under the test network XX with the station id) or no position (its arrival carries no azimuth or distance).
+
+**What this page will not call a measurement**: a magnitude - the association does not estimate one, the file carries no `magnitude` element, and a comment on every event says why. The catalogue's events as this site's - they are the catalogue's to publish; the file names them in comments and carries only what the site's own stations located. A reviewed or final event - a person has not looked at these, and the file says automatic and preliminary in the schema's own words. A located depth - it was declared, and `depthType` says so. A full schema validation - the shape check is what a reader reads first, not a validator; the file was validated against the published XSD when this export was written, and the check here holds it to that shape.

{gea_program-0.11.1 → gea_program-0.13.0}/gea/helplib.py

@@ -40,6 +40,8 @@ INDEX: List[tuple] = [
     ('notifications', 'Notifications', 'rules, channels, the delivery log'),
     ('sra', 'The Seismicity Response Area', 'the packet an operator inside an SRA puts in front of the Commission'),
     ('osdu', 'The OSDU-shaped export', 'the site as the manifest an operator\'s data platform loads'),
+    ('quakeml', 'The QuakeML catalogue export', 'the site\'s own events in the format the regulator\'s catalogue tools read'),
+    ('ppdm', 'The well as master data names it', 'the US Well Number taken apart and the PPDM "What is a Well" components the site can name'),
     ('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'),
     ('upkeep', 'Upkeep', 'housekeeping, sessions, the TLS proxy, the load test'),

{gea_program-0.11.1 → gea_program-0.13.0}/gea/osdu.py

@@ -140,14 +140,25 @@ def spatial_location(lat: float, lon: float, datum: Optional[str], ctx: Context,
 def well_record(well: dict, ctx: Context) -> dict:
     disp = well.get('disposal') or {}
     surf = well.get('surface') or {}
+    from . import ppdm as P
+    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': disp.get('api_number') or well['id'],
+                            'FacilityID': wn.get('api10') if wn.get('status') == 'VALID' else (disp.get('api_number') 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 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')}
     if disp.get('uic_number'):
         data['NameAliases'].append({'AliasName': disp['uic_number'], 'AliasNameTypeID': ctx.ref('reference-data--AliasNameType', 'PermitNumber')})
     if ctx.operator_org_id:
@@ -171,12 +182,16 @@ def well_record(well: dict, ctx: Context) -> dict:
 
 
 def wellbore_record(well: dict, ctx: Context) -> dict:
+    from . import ppdm as P
+    wn = P.well_identity(well).get('us_well_number') or {}
     data: Dict[str, Any] = {**_common(ctx), 'FacilityName': (well.get('display') or well['id']) + ' wellbore',
-                            'FacilityID': (well.get('disposal') or {}).get('api_number') or well['id'],
+                            # twelve digits name a wellbore; ten name the origin only, so the wellbore keeps the program's id and says so
+                            'FacilityID': wn.get('api12') or well['id'],
                             'FacilityTypeID': ctx.ref('reference-data--FacilityType', 'Wellbore'),
                             'WellID': _sk('well', well['id']),
                             'TrajectoryTypeID': ctx.ref('reference-data--WellboreTrajectoryType', 'Unknown'),
-                            'ExtensionProperties': {'gea': {'well_id': well['id']}}}
+                            'ExtensionProperties': {'gea': {'well_id': well['id'],
+                                                            'wellbore_identifier': wn.get('api12') or 'not identified: the sidetrack code was not given'}}}
     surf = well.get('surface') or {}
     if surf.get('lat') is not None and surf.get('lon') is not None:
         sl = spatial_location(surf['lat'], surf['lon'], surf.get('datum'), ctx, well.get('added_utc')); sl.pop('_gap', None)