gea-program 0.6.0__tar.gz → 0.7.0__tar.gz

{gea_program-0.6.0 → gea_program-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.6.0
+Version: 0.7.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
@@ -110,7 +110,10 @@ reaches a client document. Nothing unmeasured is ever reported as met.
   leg lives on the dashboard: a Seismic page where a station or an array is
   added by upload with its rigs list and station file, refreshed as a job,
   and read - spectrum, lines, verdicts, bearing - with its Seismic Station
-  Report under Reports. See *The second leg*.
+  Report under Reports; and the SAR panel on that page, a control panel and a
+  screen that plays the leg's arithmetic forward in time on the labelled
+  synthetic scene (`seismic_film.py`), every frame stamped SIMULATION_SELF_TEST.
+  See *The second leg*.
 
 ## Quick start
 
@@ -122,8 +125,8 @@ 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 (258 checks)
-gea help drift                 # the help library, by the job (15 pages; the same text is on every dashboard page)
+gea accept                     # the product gate (266 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]")
 gea workspace --path C:\site --action init --name "Pad 3"     # a site folder
@@ -251,10 +254,10 @@ text: JSON, JSON lines, CSV, Markdown, HTML.
 
 ### The help library
 
-`gea help` lists fifteen pages indexed by the job a reader arrives with -
+`gea help` lists sixteen pages indexed by the job a reader arrives with -
 start, bring data in, quality rules, drift, well tests, alarms and the month,
 the site, instruments, shut-ins and build-ups, seismic (the second leg),
-patches, files, notifications, which code is running, upkeep. Each page carries four lines and stops: the
+patches, files, notifications, which code is running, audit / update, upkeep. Each page carries four lines and stops: the
 command, what it writes, the one number to check, and what the page will not
 call a measurement. The pages ship inside the package (`gea/help/`), and the
 same text is what `/api/help` serves and what the dashboard shows under every
@@ -394,6 +397,70 @@ a rig not on the list, and any quantity in physical units until a station's
 response has been applied and named. `--action selftest` runs the test on a
 synthetic scene and labels its output SIMULATION_SELF_TEST.
 
+The SAR panel at the foot of the Seismic page is the control panel and the
+screen. "Run the scene" is `gea workspace --action sar-film` as a job: the
+labelled synthetic array scene, one frame per window, written under
+`reports/seismic/SIMULATION/`. The screen plays it - the trace, the
+spectrogram column arriving, the beam power map on the slowness grid swinging
+onto the working rig, the map with the bearing and the array's tolerance
+wedge against the rigs where the scene put them, the tally per rig, and at
+the end the array detectability test's verdict on the whole scene, the same
+function a real record goes through. Every frame carries SIMULATION_SELF_TEST
+and the line "not a measurement of any ground"; a real record is refreshed on
+its station and the page shows what it earned, never a film. `gea seismic
+--action sar-film --out film.json` writes the same film from the command line.
+
+### Tracks - the time dimension
+
+The array step gives one bearing for one window. `seismic_track.py` runs it
+window after window: a bearing history per array (a bearing with the array's
+own tolerance where the beam was coherent, a gap where it was not, change
+points where the bearing moved beyond the tolerance), a position history from
+two or more arrays crossed window by window (a position only where two or
+more arrays were coherent, the bearings crossed at 15 degrees or more and the
+point lies in front of every array - every other window a gap with its
+reason), and the track: the principal line through the longest continuous
+segment of positions, with its heading, length and rate, the ellipses beside
+every point, and segments listed apart where positions jump farther than
+their ellipses allow (a coherent background crossing in a quiet hour is not
+the rig an hour later). The verdict against ground truth - the lateral's
+surveyed points or a permit's surface hole with its date, interpolated to
+each position's time - is TRACKED, PARTIAL, NOT_TRACKED or INSUFFICIENT, with
+the fraction and the heading difference printed. The labelled scene behind
+`--action track-selftest` is a bit advancing along a straight lateral past
+two arrays. On a site a track is two or more array stations and an optional
+truth CSV, refreshed as a job into the Seismic Track Report; the track view
+shows the map with every position's ellipse, a slider through time and the
+bearings over time, and the SAR panel's second scene plays the same thing
+forward with the track drawn as it is earned.
+
+Ground truth from a permit export: `gea permits --file export.csv --out
+rigs.csv --within LAT LON KM` finds the columns of a regulator's query (an
+identifier, a surface position, a spud or approval date) by name, with a
+mapping file when the guesses are wrong, and writes the rigs CSV the tests
+read beside an import note that says which columns were used, how many rows
+were dropped and why, and how many end dates it assumed (a permit rarely says
+when drilling stopped). The Seismic page's add form takes a permit export in
+place of the rigs CSV and keeps both.
+
+### Audit / Update
+
+The Audit / Update tab holds three things. The whole audit log
+(`records/audit.jsonl`) with filters by who, by action and since a date, and
+a CSV download - Administration keeps the last hundred lines and points here.
+The program card: the running version and code path, the newest release on
+PyPI (`current`, `behind`, or `PyPI not reachable` when the machine is
+offline), which extras are installed here, and links to PyPI, the releases
+with the install kits, and the CHANGELOG; "Update the program from PyPI"
+(admin) is `gea update` as a job - pip --upgrade from the same Python, after
+which the service must be restarted; the program never restarts itself, and
+an offline kit is updated by installing the newer kit. The data card: every
+report against its source - `current` or `stale` when the source changed
+after the report was written - and "Update every report from its source"
+(operator), which is `gea workspace --action refresh-all` as a job: the
+dashboard for every well, then every seismic station, errors collected and
+listed, never hidden.
+
 ### Before a site goes live
 
 `deploy/README.md` is the checklist: keep the service on the loopback
@@ -446,7 +513,8 @@ docs/report_samples/  one rendered example of every client report, from this bui
 docs/           TESTER_GUIDE.md, REQUIREMENTS_MATRIX.md (the scope-of-work mirror that shaped the reports), examples/ (port configs),
                 SESSION_LOG.md (the working record, session by session),
                 commercial/ (pilot proposal, bench readiness, commercial use), HISTORY.md (the ship-by-ship record)
-tools/          standalone_check.py (the self-contained guard; run by ci and ship.ps1), build_installer.py (the kit)
+tools/          standalone_check.py (the self-contained guard; run by ci and ship.ps1), build_installer.py (the kit),
+                render_report_samples.py (docs/report_samples), seismic_reader_check.py (the reader against libmseed)
 CHANGELOG.md    per-release summary (a tag ships only with its section); SHIP_LOG.md is written by ship.ps1
 tests/          pytest wrapper around the acceptance suite and the standalone check
 ```

{gea_program-0.6.0 → gea_program-0.7.0}/README.md

@@ -71,7 +71,10 @@ reaches a client document. Nothing unmeasured is ever reported as met.
   leg lives on the dashboard: a Seismic page where a station or an array is
   added by upload with its rigs list and station file, refreshed as a job,
   and read - spectrum, lines, verdicts, bearing - with its Seismic Station
-  Report under Reports. See *The second leg*.
+  Report under Reports; and the SAR panel on that page, a control panel and a
+  screen that plays the leg's arithmetic forward in time on the labelled
+  synthetic scene (`seismic_film.py`), every frame stamped SIMULATION_SELF_TEST.
+  See *The second leg*.
 
 ## Quick start
 
@@ -83,8 +86,8 @@ 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 (258 checks)
-gea help drift                 # the help library, by the job (15 pages; the same text is on every dashboard page)
+gea accept                     # the product gate (266 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]")
 gea workspace --path C:\site --action init --name "Pad 3"     # a site folder
@@ -212,10 +215,10 @@ text: JSON, JSON lines, CSV, Markdown, HTML.
 
 ### The help library
 
-`gea help` lists fifteen pages indexed by the job a reader arrives with -
+`gea help` lists sixteen pages indexed by the job a reader arrives with -
 start, bring data in, quality rules, drift, well tests, alarms and the month,
 the site, instruments, shut-ins and build-ups, seismic (the second leg),
-patches, files, notifications, which code is running, upkeep. Each page carries four lines and stops: the
+patches, files, notifications, which code is running, audit / update, upkeep. Each page carries four lines and stops: the
 command, what it writes, the one number to check, and what the page will not
 call a measurement. The pages ship inside the package (`gea/help/`), and the
 same text is what `/api/help` serves and what the dashboard shows under every
@@ -355,6 +358,70 @@ a rig not on the list, and any quantity in physical units until a station's
 response has been applied and named. `--action selftest` runs the test on a
 synthetic scene and labels its output SIMULATION_SELF_TEST.
 
+The SAR panel at the foot of the Seismic page is the control panel and the
+screen. "Run the scene" is `gea workspace --action sar-film` as a job: the
+labelled synthetic array scene, one frame per window, written under
+`reports/seismic/SIMULATION/`. The screen plays it - the trace, the
+spectrogram column arriving, the beam power map on the slowness grid swinging
+onto the working rig, the map with the bearing and the array's tolerance
+wedge against the rigs where the scene put them, the tally per rig, and at
+the end the array detectability test's verdict on the whole scene, the same
+function a real record goes through. Every frame carries SIMULATION_SELF_TEST
+and the line "not a measurement of any ground"; a real record is refreshed on
+its station and the page shows what it earned, never a film. `gea seismic
+--action sar-film --out film.json` writes the same film from the command line.
+
+### Tracks - the time dimension
+
+The array step gives one bearing for one window. `seismic_track.py` runs it
+window after window: a bearing history per array (a bearing with the array's
+own tolerance where the beam was coherent, a gap where it was not, change
+points where the bearing moved beyond the tolerance), a position history from
+two or more arrays crossed window by window (a position only where two or
+more arrays were coherent, the bearings crossed at 15 degrees or more and the
+point lies in front of every array - every other window a gap with its
+reason), and the track: the principal line through the longest continuous
+segment of positions, with its heading, length and rate, the ellipses beside
+every point, and segments listed apart where positions jump farther than
+their ellipses allow (a coherent background crossing in a quiet hour is not
+the rig an hour later). The verdict against ground truth - the lateral's
+surveyed points or a permit's surface hole with its date, interpolated to
+each position's time - is TRACKED, PARTIAL, NOT_TRACKED or INSUFFICIENT, with
+the fraction and the heading difference printed. The labelled scene behind
+`--action track-selftest` is a bit advancing along a straight lateral past
+two arrays. On a site a track is two or more array stations and an optional
+truth CSV, refreshed as a job into the Seismic Track Report; the track view
+shows the map with every position's ellipse, a slider through time and the
+bearings over time, and the SAR panel's second scene plays the same thing
+forward with the track drawn as it is earned.
+
+Ground truth from a permit export: `gea permits --file export.csv --out
+rigs.csv --within LAT LON KM` finds the columns of a regulator's query (an
+identifier, a surface position, a spud or approval date) by name, with a
+mapping file when the guesses are wrong, and writes the rigs CSV the tests
+read beside an import note that says which columns were used, how many rows
+were dropped and why, and how many end dates it assumed (a permit rarely says
+when drilling stopped). The Seismic page's add form takes a permit export in
+place of the rigs CSV and keeps both.
+
+### Audit / Update
+
+The Audit / Update tab holds three things. The whole audit log
+(`records/audit.jsonl`) with filters by who, by action and since a date, and
+a CSV download - Administration keeps the last hundred lines and points here.
+The program card: the running version and code path, the newest release on
+PyPI (`current`, `behind`, or `PyPI not reachable` when the machine is
+offline), which extras are installed here, and links to PyPI, the releases
+with the install kits, and the CHANGELOG; "Update the program from PyPI"
+(admin) is `gea update` as a job - pip --upgrade from the same Python, after
+which the service must be restarted; the program never restarts itself, and
+an offline kit is updated by installing the newer kit. The data card: every
+report against its source - `current` or `stale` when the source changed
+after the report was written - and "Update every report from its source"
+(operator), which is `gea workspace --action refresh-all` as a job: the
+dashboard for every well, then every seismic station, errors collected and
+listed, never hidden.
+
 ### Before a site goes live
 
 `deploy/README.md` is the checklist: keep the service on the loopback
@@ -407,7 +474,8 @@ docs/report_samples/  one rendered example of every client report, from this bui
 docs/           TESTER_GUIDE.md, REQUIREMENTS_MATRIX.md (the scope-of-work mirror that shaped the reports), examples/ (port configs),
                 SESSION_LOG.md (the working record, session by session),
                 commercial/ (pilot proposal, bench readiness, commercial use), HISTORY.md (the ship-by-ship record)
-tools/          standalone_check.py (the self-contained guard; run by ci and ship.ps1), build_installer.py (the kit)
+tools/          standalone_check.py (the self-contained guard; run by ci and ship.ps1), build_installer.py (the kit),
+                render_report_samples.py (docs/report_samples), seismic_reader_check.py (the reader against libmseed)
 CHANGELOG.md    per-release summary (a tag ships only with its section); SHIP_LOG.md is written by ship.ps1
 tests/          pytest wrapper around the acceptance suite and the standalone check
 ```

{gea_program-0.6.0 → gea_program-0.7.0}/gea/__init__.py

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

{gea_program-0.6.0 → gea_program-0.7.0}/gea/__main__.py

@@ -280,7 +280,16 @@ def main(argv=None) -> int:
     p_ws.add_argument("--path", type=str, required=True, help="the workspace folder")
     p_ws.add_argument("--action", type=str, default="list",
                       choices=["init", "add-file", "add-catalog", "add-live", "remove", "list", "migrate", "refresh", "audit",
-                               "add-seismic", "refresh-seismic", "remove-seismic"])
+                               "add-seismic", "refresh-seismic", "remove-seismic", "sar-film", "refresh-all", "add-track", "refresh-track", "remove-track"])
+    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("--truth", type=str, default=None, help="add-track: ground truth CSV (point_id, lat, lon, utc[, note])")
+    p_ws.add_argument("--track", type=str, default=None, help="refresh-track / remove-track: the track id")
+    p_ws.add_argument("--win", type=float, default=600.0, help="add-track: the window length, s (default 600)")
+    p_ws.add_argument("--hours", type=float, default=8.0, help="sar-film: the synthetic scene's length, h")
+    p_ws.add_argument("--step", type=float, default=600.0, help="sar-film: seconds per frame")
+    p_ws.add_argument("--seed", type=int, default=5, help="sar-film: the scene's seed")
+    p_ws.add_argument("--method", type=str, default="bartlett", choices=["bartlett", "capon"], help="sar-film: the beamformer")
+    p_ws.add_argument("--scene", type=str, default="rigs", choices=["rigs", "lateral"], help="sar-film: fixed rigs, or a bit advancing along a lateral past two arrays")
     p_ws.add_argument("--files", type=str, nargs="+", default=None, help="add-seismic: the station's record (or one record per sensor of an array, in the sensors CSV's order)")
     p_ws.add_argument("--lat", type=float, default=None, help="add-seismic: the station's latitude")
     p_ws.add_argument("--lon", type=float, default=None, help="add-seismic: the station's longitude")
@@ -288,6 +297,7 @@ def main(argv=None) -> int:
     p_ws.add_argument("--sensors", type=str, default=None, help="add-seismic: sensors CSV (sensor_id, lat, lon) - makes the station an array")
     p_ws.add_argument("--sources", type=str, default=None, help="add-seismic: the rigs CSV (source_id, lat, lon, start_utc, end_utc[, kind, note])")
     p_ws.add_argument("--band", type=float, nargs=2, default=None, metavar=("LO", "HI"), help="add-seismic: the band, Hz (default 1 50)")
+    p_ws.add_argument("--permits", type=str, default=None, help="add-seismic: a permit export to turn into the rigs CSV (instead of --sources)")
     p_ws.add_argument("--station", type=str, default=None, help="refresh-seismic / remove-seismic: the station id")
     p_ws.add_argument("--name", type=str, default=None, help="init: site name; add-*: display name")
     p_ws.add_argument("--file", type=str, default=None, help="add-file: the client's data file; add-live: the port configuration JSON")
@@ -348,6 +358,19 @@ def main(argv=None) -> int:
     p_dr.add_argument("--port", type=int, default=8765)
     p_dr.add_argument("--json", action="store_true")
 
+    p_pm = sub.add_parser("permits", help="a drilling-permit export (CSV/TSV) to the rigs CSV the seismic tests judge against, with an import note")
+    p_pm.add_argument("--file", type=str, required=True, help="the permit export (a regulator's query CSV, an operator's schedule)")
+    p_pm.add_argument("--out", type=str, required=True, help="the rigs CSV to write (an .import.json note is written beside it)")
+    p_pm.add_argument("--mapping", type=str, default=None, help='JSON {"lat": "<column>", "lon": ..., "start": ..., "end": ..., "id": ..., "name": ...} when the guesses are wrong')
+    p_pm.add_argument("--default-days", type=float, default=30.0, help="a row without an end date works this many days from its start (default 30)")
+    p_pm.add_argument("--within", type=float, nargs=3, default=None, metavar=("LAT", "LON", "KM"), help="keep only rigs within KM of LAT, LON")
+    p_pm.add_argument("--json", action="store_true")
+
+    p_up = sub.add_parser("update", help="the program update: compare the running version with PyPI and, unless --check, run pip --upgrade for it from this Python")
+    p_up.add_argument("--check", action="store_true", help="only report the running and the newest version")
+    p_up.add_argument("--extras", type=str, default="live,plotting,xls,desktop", help="the extras to carry through the upgrade (default live,plotting,xls,desktop)")
+    p_up.add_argument("--json", action="store_true")
+
     p_nt = sub.add_parser("notify", help="notification rules: validate the configuration, send a test message, show the delivery log")
     p_nt.add_argument("--workspace", type=str, default=None)
     p_nt.add_argument("--test", type=str, default=None, help="send a test message through this channel name")
@@ -357,7 +380,14 @@ def main(argv=None) -> int:
 
     p_se = sub.add_parser("seismic", help="the second leg's ingest: miniSEED/SAC in, spectra and persistent lines out, an FDSN fetch, and the detectability test against known rigs")
     p_se.add_argument("--action", choices=["info", "spectrum", "lines", "fetch", "stations", "detect", "selftest", "convert", "response", "remove-response",
-                                           "beam", "array-detect", "locate", "array-selftest"], default="info")
+                                           "beam", "array-detect", "locate", "array-selftest", "sar-film", "bearings", "track", "track-selftest"], default="info")
+    p_se.add_argument("--histories", type=str, nargs="+", default=None, help="track: two or more bearing-history JSONs (from --action bearings), one per array")
+    p_se.add_argument("--truth", type=str, default=None, help="track: ground truth CSV (point_id, lat, lon, utc[, note]) - the lateral's points in time")
+    p_se.add_argument("--name", type=str, default=None, help="bearings: a name for the array in the history")
+    p_se.add_argument("--scene", type=str, default="rigs", choices=["rigs", "lateral"], help="sar-film: the labelled scene - fixed rigs, or a bit advancing along a lateral past two arrays")
+    p_se.add_argument("--hours", type=float, default=8.0, help="sar-film: the synthetic scene's length, h (default 8: four rigs, each working alone for an hour)")
+    p_se.add_argument("--step", type=float, default=600.0, help="sar-film: one frame per this many seconds (default 600)")
+    p_se.add_argument("--seed", type=int, default=5, help="sar-film: the scene's random seed")
     p_se.add_argument("--files", type=str, nargs="+", default=None, help="beam/array-detect: one record per sensor, in the order of --sensors")
     p_se.add_argument("--sensors", type=str, default=None, help="beam/array-detect: CSV of the array's sensors (sensor_id, lat, lon[, elevation_m])")
     p_se.add_argument("--bearings", type=str, default=None, help="locate: CSV of arrays' bearings (lat, lon, back_azimuth_deg, sigma_deg)")
@@ -760,6 +790,18 @@ def main(argv=None) -> int:
                 print(f"seismic: response of {chan.id} removed ({chan.sensor or 'sensor unnamed'}); the record is now in {note['unit']}", file=sys.stderr)
             return trs, tr
         band = (float(a.band[0]), float(a.band[1]))
+        if a.action == "sar-film":
+            from . import seismic_film as FM
+            film = FM.sar_film(seed=a.seed, hours=a.hours, step_s=a.step, band=(float(a.band[0]), float(a.band[1])) if a.band != [1.0, 50.0] else (1.0, 20.0), method=a.method, scene=a.scene)
+            if a.out:
+                FM.write_film(film, a.out)
+            if a.json:
+                print(_json.dumps(FM.film_summary(film), indent=1))
+            else:
+                print(FM.report_text(film))
+                if a.out:
+                    print(f"film: {a.out} ({len(film['frames'])} frames)")
+            return 0
         if a.action == "array-selftest":
             from . import seismic_array as AR
             r = AR.selftest()
@@ -772,7 +814,37 @@ def main(argv=None) -> int:
                 print(f"  three arrays' bearings cross {c['miss_km']:.2f} km from the rig; 1-sigma ellipse {c['ellipse_1sigma']['major_km']} x {c['ellipse_1sigma']['minor_km']} km; "
                       f"crossing angle {c['crossing_angle_deg']} deg; in front of every array: {c['in_front_of_every_array']}")
             return 0 if r["ok"] else 1
-        if a.action in ("beam", "array-detect"):
+        if a.action == "track-selftest":
+            from . import seismic_track as T
+            r = T.selftest()
+            if a.json:
+                print(_json.dumps({k: v for k, v in r.items() if k != "bearing_histories"}, indent=1, default=str))
+            else:
+                print(f"seismic track-selftest: {r['status']} ok={r['ok']}")
+                for h in r["bearing_histories"]:
+                    print(f"  {h['array']['name']}: {h['n_coherent']} coherent of {h['n_windows']} windows, tolerance {h['tolerance_deg']} deg, span {h['span_deg']} deg, {len(h['change_points'])} change point(s)")
+                print(T.report_text(r["positions"], r["verdict"]))
+            return 0 if r["ok"] else 1
+        if a.action == "track":
+            from . import seismic_track as T
+            if not a.histories or len(a.histories) < 2:
+                raise SystemExit("seismic track needs --histories (two or more bearing-history JSONs)")
+            hists = []
+            for hp in a.histories:
+                with open(hp, encoding="utf-8") as fh:
+                    hists.append(_json.load(fh))
+            pos = T.position_history(hists)
+            ver = T.track_verdict(pos, T.load_truth_csv(a.truth)) if a.truth else None
+            res = {"positions": pos, "verdict": ver}
+            if a.out:
+                with open(a.out, "w", encoding="utf-8") as fh:
+                    _json.dump(res, fh, indent=1, default=str)
+            if a.json:
+                print(_json.dumps(res, indent=1, default=str))
+            else:
+                print(T.report_text(pos, ver))
+            return 0
+        if a.action in ("beam", "array-detect", "bearings"):
             from . import seismic_array as AR
             if not a.files or not a.sensors:
                 raise SystemExit(f"seismic {a.action} needs --files (one per sensor) and --sensors CSV")
@@ -788,6 +860,22 @@ def main(argv=None) -> int:
                 if a.start or a.end:
                     tr = tr.slice(S.parse_time(a.start) if a.start else tr.starttime, S.parse_time(a.end) if a.end else tr.endtime)
                 trs.append(tr)
+            if a.action == "bearings":
+                from . import seismic_track as T
+                h = T.bearing_history(trs, sensors, band, a.win or 600.0, None, a.seg, a.smax, 41, a.method)
+                h["array"]["name"] = a.name or sensors[0].sensor_id
+                if a.out:
+                    with open(a.out, "w", encoding="utf-8") as fh:
+                        _json.dump(h, fh, indent=1)
+                if a.json:
+                    print(_json.dumps(h, indent=1))
+                else:
+                    print(f"seismic bearings: {h['array']['name']}, {h['n_coherent']} coherent of {h['n_windows']} windows of {h['win_s']:g} s, tolerance {h['tolerance_deg']} deg"
+                          + (f", span {h['span_deg']} deg" if h['span_deg'] is not None else "") + f", {len(h['change_points'])} change point(s)")
+                    for w in h["windows"]:
+                        print(f"  {w['start_utc']}  " + (f"{w['back_azimuth_deg']:7.2f} deg  coherence {w['coherence_max_bin']}" if w.get("back_azimuth_deg") is not None else "no beam")
+                              + ("" if w["coherent"] else "  (gap: not coherent)"))
+                return 0
             if a.action == "beam":
                 b = AR.beam(trs, sensors, band, a.seg, a.smax, 61, a.method)
                 b = {k: v for k, v in b.items() if not k.startswith("_")}
@@ -993,6 +1081,22 @@ def main(argv=None) -> int:
     elif a.cmd == "doctor":
         from .doctor import run as _doctor
         return _doctor(a.workspace, a.host, a.port, a.json)
+    elif a.cmd == "permits":
+        import json as _json
+        from . import permits as PM
+        mapping = None
+        if a.mapping:
+            with open(a.mapping, encoding="utf-8") as fh:
+                mapping = _json.load(fh)
+        try:
+            note = PM.import_permits(a.file, a.out, mapping=mapping, default_days=a.default_days, within=tuple(a.within) if a.within else None)
+        except ValueError as e:
+            raise SystemExit(f"permits: {e}")
+        print(_json.dumps(note, indent=1) if a.json else PM.report_text(note))
+        return 0
+    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 == "serve":
         from .service import Service
         from .workspace import WorkspaceError
@@ -1090,7 +1194,7 @@ def main(argv=None) -> int:
                 if not (a.name and a.files):
                     raise SystemExit("add-seismic needs --name and --files (one record, or one per sensor with --sensors)")
                 st = ws.add_seismic_station(a.name, a.files, a.lat, a.lon, actor=a.actor, stationxml=a.stationxml, sensors_csv=a.sensors,
-                                            sources_csv=a.sources, band=a.band)
+                                            sources_csv=a.sources, band=a.band, permits_csv=a.permits)
                 print("seismic station:", st["id"], f"({st['kind']}, {len(st['files'])} record(s))"); return 0
             elif a.action == "refresh-seismic":
                 ids = [a.station] if a.station else [x["id"] for x in ws.seismic_stations()]
@@ -1103,6 +1207,34 @@ def main(argv=None) -> int:
                           + (f"; beam {r['beam_back_azimuth_deg']} deg, pointed at {r['pointed']}" if r["beam_back_azimuth_deg"] is not None else "")
                           + f"\n  report: {r['report']}")
                 return 0
+            elif a.action == "add-track":
+                if not (a.name and a.stations):
+                    raise SystemExit("add-track needs --name and --stations (two or more array station ids)")
+                tk = ws.add_track(a.name, a.stations, actor=a.actor, truth_csv=a.truth, band=a.band, win_s=a.win)
+                print("track:", tk["id"], f"({len(tk['stations'])} arrays" + (f", truth {tk['truth']}" if tk["truth"] else ", no ground truth") + ")"); return 0
+            elif a.action == "refresh-track":
+                ids = [a.track] if a.track else [x["id"] for x in ws.tracks()]
+                if not ids:
+                    raise SystemExit("refresh-track: no track in the workspace")
+                for tid in ids:
+                    r = ws.refresh_track(tid, actor=a.actor)
+                    print(f"track {tid}: {r['arrays']} arrays, {r['positions']} positions of {r['windows']} windows"
+                          + (f", {r['segments']} segment(s), heading {r['heading_deg']} deg, length {r['length_km']} km" if r["heading_deg"] is not None else "")
+                          + (f"; verdict {r['verdict']} ({r['hit_fraction']:.0%})" if r["verdict"] else "; no ground truth") + f"\n  report: {r['report']}")
+                return 0
+            elif a.action == "remove-track":
+                if not a.track:
+                    raise SystemExit("remove-track needs --track <id>")
+                ws.remove_track(a.track, actor=a.actor); print("removed (folder kept):", a.track); return 0
+            elif a.action == "sar-film":
+                r = ws.sar_film(actor=a.actor, seed=a.seed, hours=a.hours, step_s=a.step, band=tuple(a.band) if a.band else (1.0, 20.0), method=a.method, scene=a.scene)
+                print(f"sar-film: {r['label']}, {r['frames']} frames over {r['hours']} h; verdicts {r['verdicts']}\n  film: {r['path']}"); return 0
+            elif a.action == "refresh-all":
+                r = ws.refresh_all(actor=a.actor)
+                print(f"refresh-all: {r['wells']} well(s) refreshed, {r['seismic']} seismic station(s) refreshed, {len(r['errors'])} error(s)")
+                for e in r["errors"]:
+                    print("  error:", e)
+                return 0 if not r["errors"] else 1
             elif a.action == "remove-seismic":
                 if not a.station:
                     raise SystemExit("remove-seismic needs --station <id>")