gea-program 0.3.0__tar.gz → 0.5.0__tar.gz

{gea_program-0.3.0/gea_program.egg-info → gea_program-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.3.0
+Version: 0.5.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
@@ -92,6 +92,14 @@ reaches a client document. Nothing unmeasured is ever reported as met.
 - **Survey track** (`earth_model.py`, `strata_join.py`, `inverse_engine.py`,
   `blind_harness.py`, `rock_inventory.py`, `forward_model.py`, ...): strata
   property estimation over a public co-located library, blind-scored on every run.
+- **The second leg - seismic** (`seismic.py`, `seismic_detect.py`): raw seismic
+  records in (miniSEED with Steim1/Steim2, SAC, or fetched from any FDSN
+  archive - TexNet, EarthScope), Welch spectra, spectrograms and the persistent
+  lines above the local floor out, and the detectability test: one station's
+  record against a list of known rigs with positions and working windows,
+  verdict per rig, the detection radius bracketed between the farthest rig
+  heard and the nearest not heard. The decoder is proven against records
+  written by libmseed. See *The second leg*.
 
 ## Quick start
 
@@ -103,11 +111,17 @@ 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 (199 checks)
+gea accept                     # the product gate (246 checks)
+gea help drift                 # the help library, by the job (15 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
 gea serve --workspace C:\site                                 # the dashboard as the door: http://127.0.0.1:8765/
+gea doctor --workspace C:\site                                # which code runs, can it serve, with every fix
+gea files --workspace C:\site --action list --root historian  # the import roots, detection by content, import, export, packs
+gea transient --file historian.csv --params params.json --out pta   # shut-ins and build-up analysis with a band
+gea seismic --action detect --file tx.mseed --station-lat 31.9 --station-lon -102.1 --sources rigs.csv   # the second leg: is a known rig in this record?
+gea swaps / gea certificates / gea notify / gea housekeeping / gea loadtest   # instruments, notification rules, site upkeep
 ```
 
 `gea` is the front door (`gea/cli.py`); every other subcommand passes through to
@@ -186,11 +200,23 @@ alarms and commits configuration; **approver** decides well tests and re-fits;
 ranking), Wells (add from a file, the catalogue or a live tag map; each well's
 reports, quality, trends, tests and alarms), Patch panel (supervised sources,
 their state and live values, their maps, live values), Alarms (the wall, acknowledge, definitions), Approvals (one queue),
+Files (the import and export roots an administrator allows, browse with
+detection by content, import into a well, "save to..." on every report, the
+evidence pack, watch folders), Alarms (the wall: acknowledge one or all, shelve
+with a reason and an expiry, unshelve; definitions), Approvals (one queue),
 Configuration (versioned JSON with history, diff and rollback), Reports
 (generate and open every report), Verification (the acceptance suite, FAT/SAT,
 SBOM and the standalone check from the page), Survey (a LAS file in, a strata
-report out), Jobs (every run with its log), Administration (users, schedule,
-audit log).
+report out), Jobs (every run with its log), Administration (users, live
+sessions, file roots, schedule, site settings, notifications, audit log). A
+search box in the header spans wells, alarms, reports, jobs, configuration,
+patches and schedules; the navigation shows badge counts (unacknowledged
+alarms, decisions waiting, failed jobs, patches down); Home opens with what
+happened since your last sign-in; every page has a help panel (the Help
+button hides them); every timestamp is shown in your time zone and every
+value in your units (field or SI - "Your preferences", with site defaults
+under Administration); a first-run guide walks a new site through its
+settings, first well, people and first refresh; every page prints cleanly.
 
 Every action the page takes is a job: `python -m gea <command>` run by the
 service with its log kept under `jobs/`, so one code path serves the page, the
@@ -212,16 +238,151 @@ evaluations and change logs), `reports/` (the printed dashboard and every
 report), `jobs/` (every run), `records/audit.jsonl`, `users.json`. All of it is
 text: JSON, JSON lines, CSV, Markdown, HTML.
 
+### The help library
+
+`gea help` lists fifteen 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
+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
+heading and under Help, so the terminal and the page cannot drift apart. The
+click-by-click tester guide ships with them: `gea guide`.
+
+### Which code is running
+
+`gea doctor` answers the question every stale-page report comes down to:
+which Python, which copy of the package, does pip's record match the code
+that runs (an editable checkout or an installed release), is another copy
+shadowing it, is the page present, which dependencies are installed, is a
+newer release on PyPI; with `--workspace` it also checks the site folder, the
+accounts, the patches, a free port and write access. Every finding carries
+its fix. `gea serve` runs the same checks and does not start on a blocking
+finding, so a stale page is never served silently.
+
+### Notifications
+
+Rules route events to channels: a webhook URL or an SMTP mailbox. Events:
+`alarm.activated` (by priority), `alarm.shelved`, `job.failed`, `patch.down`
+and `patch.up`, `approval.pending`, `file.imported`. A quiet window stops
+repeats of the same key; every attempt and every suppression is in
+`records/notifications.jsonl`; an SMTP password is read from the environment
+variable the channel names, never from the configuration. `gea notify
+--example` prints a configuration to commit as `notifications` (Administration
+has the editor and a "send a test" button per channel).
+
+### Instruments and transients
+
+A swapped gauge is a new instrument. Record the swap on the well page (or
+confirm one the step detector proposes - it looks for a jump in a gauge's
+offset against its peers, which a process change does not produce) and the
+drift fit restarts at the swap, with the swap printed in the report. File the
+calibration certificate of each instrument (serial, lab, dates, stated
+accuracy; the document is kept and hashed) and its status - VALID, EXPIRING,
+EXPIRED, MISSING - is on the well page, on Home, and beside the measured bias
+in the drift report, so a reader sees whether a bias is inside the
+instrument's own class.
+
+Every shut-in in a record (found by the rate channel, the on-stream hours, or
+the pressure signature alone when there is no rate - marked so) gets a
+build-up analysis on the next refresh: Horner slope and p* on a middle-time
+region chosen by the flat Bourdet derivative, wellbore storage, and - once the
+rock and fluid parameters are saved on the well page - kh, k, skin and the
+radius of investigation, each with a 90 % band from a residual bootstrap. The
+Shut-in and Pressure Transient report prints the region and the rule that
+chose it; an analyst can move the region (`gea transient --mtr 2:40`) and the
+result follows. It is the first look every shut-in should get automatically,
+not a replacement for a full interpretation, and it says so.
+
+### The second leg
+
+The second leg of the program is seismic: the client's site records ground
+motion that conventional processing treats as noise, and in that noise are
+the machinery lines of every rig working within range - mud pumps and their
+harmonics, rotary tables, engines. The leg starts with ingest and one measured
+number, not with a map. `gea seismic` reads the two formats the archives and
+most field recorders write (miniSEED with Steim1/Steim2 and integer/float
+encodings, decided by content; SAC), fetches records from any FDSN web service
+(`--base texnet` for the Texas network TX, `--base iris` for EarthScope), and
+produces the standard spectral products: the Welch PSD, a spectrogram, and
+the lines that persist above a running-median floor in the band where rig
+machinery sits (1-50 Hz by default). The decoder is proven in the acceptance
+suite against records written by libmseed, the format's reference
+implementation (`gea/reference/`).
+
+The first number is the detectability test (`--action detect`): one station's
+continuous record, the station's position, and a CSV of known rigs - position
+and working window from a public permit register or the operator's own
+schedule. For every rig that worked alone for enough windows the test
+compares the band power in its windows with the quiet baseline (the windows
+when no listed rig was working) and says DETECTED or NOT_DETECTED, with the
+excess in dB and the lines that belong to those windows and not to the quiet
+ones; a rig that never worked alone is AMBIGUOUS, and a record with no quiet
+hour gets NO_QUIET_BASELINE and no verdict at all. The result is the radius
+bracketed between the farthest rig heard and the nearest not heard - the
+station's measured reach for rigs like those on the list. Everything the leg
+can later claim sits inside that radius. What the test will not call a
+measurement is printed with it: a well's position or track (one station
+detects, it does not locate - locating is the array step that comes after
+this number exists), a radius beyond the farthest listed rig, anything about
+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.
+
+### Before a site goes live
+
+`deploy/README.md` is the checklist: keep the service on the loopback
+address and put a TLS proxy in front (`deploy/Caddyfile`,
+`deploy/nginx-gea.conf`), start with `--behind-proxy`. The service itself
+rate-limits sign-ins (five failures lock the name and the address for 15
+minutes, audited), lists and revokes live sessions, sends the security
+headers on every response, and `gea housekeeping --workspace C:\site --apply`
+(schedule it daily from Administration) segments the append-only logs rather
+than truncating them and prunes finished job folders and old recordings. `gea
+loadtest --patches 16 --seconds 60 --with-service` tells you whether the site
+machine carries the patches it will be given, with the page still answering.
+
+## The standalone install kit
+
+A client site often has no internet and no Python. The kit is one folder
+(and one zip) that carries its own Python, the package and every dependency
+as files, with the scripts a site needs; it installs without a network and
+without administrator rights, and keeps the site's data in a separate
+workspace folder it never deletes.
+
+```
+python tools/build_installer.py                       # dist/gea-program-<version>-win64/ and .zip (needs internet here, none there)
+python tools/build_installer.py --extras live,plotting,xls   # a smaller kit without the PyQt6 desktop window
+python tools/build_installer.py --platform linux      # a venv-based kit for a Linux site server
+```
+
+The kit carries every optional dependency by default - the live ports
+(asyncua, paho-mqtt, pymodbus, pyserial), matplotlib, xlrd and the PyQt6
+desktop window - so `gea sbom` from an installed kit lists all of them as
+installed; and `report-samples/`, one rendered example of every report.
+
+At the site: unzip, `install.cmd`, `start-dashboard.cmd`; the browser opens
+`http://127.0.0.1:8765/`. `verify.cmd` runs the acceptance gate from the
+installed kit (the client's own evidence), `register-service.cmd` starts the
+dashboard at logon, `uninstall.cmd` removes the kit and leaves the workspace.
+`SHA256SUMS.txt` lets the site verify the kit after copying it. Every tag
+builds the Windows and Linux kits in CI (`build-installer.yml`), installs
+them the way a client does, runs the gate from the installed kit, and
+attaches the zips to the GitHub release of that tag.
+
 ## Layout
 
 ```
 gea/            the package: engines, record layer, reports, monitor, dashboard, cli, shell, acceptance suite,
                 workspace, jobs, service, patches and web/app.html (the served dashboard)
 gea/catalog/    52 public archive entries, each with a provenance file
+gea/reference/  miniSEED records written by libmseed, with their provenance: the decoder's independent reference
+docs/report_samples/  one rendered example of every client report, from this build (tools/render_report_samples.py; SAMPLES.md names each command)
 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: imports, text, metadata; run by ci and ship.ps1)
+tools/          standalone_check.py (the self-contained guard; run by ci and ship.ps1), build_installer.py (the kit)
 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
 ```
@@ -238,10 +399,22 @@ density anchors and Vp ranges with their citations (Telford, Geldart and
 Sheriff; Schon). Every catalogue entry under `gea/catalog/` has a provenance
 file naming its public source.
 
-Two statements the product carries on its own model cards: the gauge aging
-envelope's lower bound is an engineering model with no field validation on
-record, and five of the fourteen back-tested strata quantities are NOT
-ACCEPTABLE at the 95 % target. Both are printed, never claimed otherwise.
+The gauge aging rate the drift evaluation uses is the instrument's published
+drift specification, read from a cited datasheet (`gea/gauge_specs.py`), with
+nothing added for temperature or pressure - above the rating the rate is
+flagged, not changed. The program carries no aging model of its own, no
+engineering constant that is not a datasheet number, and no claim about a
+gauge beyond what its datasheet says; `tools/standalone_check.py` fails the
+build on the names, phrases and numbers of the model that once stood there.
+The seismic leg is textbook signal processing - Welch's PSD estimate, a
+running-median floor, band power, great-circle distance - and the decoder is
+checked against libmseed; the synthetic scene behind its self-test states its
+own assumptions (body-wave spreading, a Q) and is labelled as a scene, not a
+ground. Two statements the product carries on its own model cards: the datasheet
+rate has no field validation on record against a gauge with a known history
+(`gea bench` is the instrument for it), and five of the fourteen back-tested
+strata quantities are NOT ACCEPTABLE at the 95 % target. Both are printed,
+never claimed otherwise.
 
 ## Shipping
 
@@ -251,7 +424,9 @@ not exist anywhere, every version in `SHIP_LOG.md` must have its tag, `python -m
 accept` must be green, `SHIP_MESSAGE.txt` must start with the tag; then commit, tag,
 push, and the remote tag must be seen before SHIPPED is printed. `CHANGELOG.md` must carry a
 section headed by the tag, and `tools/standalone_check.py` must report no findings. `-DryRun` runs every
-check and changes nothing; `-NoPush` stops after the local tag.
+check and changes nothing; `-NoPush` stops after the local tag. Before the gate, after the bump:
+`python tools/render_report_samples.py` re-renders `docs/report_samples/` from the new build
+(section AM fails on a stale build number).
 
 ## Publishing to PyPI
 

{gea_program-0.3.0 → gea_program-0.5.0}/README.md

@@ -53,6 +53,14 @@ reaches a client document. Nothing unmeasured is ever reported as met.
 - **Survey track** (`earth_model.py`, `strata_join.py`, `inverse_engine.py`,
   `blind_harness.py`, `rock_inventory.py`, `forward_model.py`, ...): strata
   property estimation over a public co-located library, blind-scored on every run.
+- **The second leg - seismic** (`seismic.py`, `seismic_detect.py`): raw seismic
+  records in (miniSEED with Steim1/Steim2, SAC, or fetched from any FDSN
+  archive - TexNet, EarthScope), Welch spectra, spectrograms and the persistent
+  lines above the local floor out, and the detectability test: one station's
+  record against a list of known rigs with positions and working windows,
+  verdict per rig, the detection radius bracketed between the farthest rig
+  heard and the nearest not heard. The decoder is proven against records
+  written by libmseed. See *The second leg*.
 
 ## Quick start
 
@@ -64,11 +72,17 @@ 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 (199 checks)
+gea accept                     # the product gate (246 checks)
+gea help drift                 # the help library, by the job (15 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
 gea serve --workspace C:\site                                 # the dashboard as the door: http://127.0.0.1:8765/
+gea doctor --workspace C:\site                                # which code runs, can it serve, with every fix
+gea files --workspace C:\site --action list --root historian  # the import roots, detection by content, import, export, packs
+gea transient --file historian.csv --params params.json --out pta   # shut-ins and build-up analysis with a band
+gea seismic --action detect --file tx.mseed --station-lat 31.9 --station-lon -102.1 --sources rigs.csv   # the second leg: is a known rig in this record?
+gea swaps / gea certificates / gea notify / gea housekeeping / gea loadtest   # instruments, notification rules, site upkeep
 ```
 
 `gea` is the front door (`gea/cli.py`); every other subcommand passes through to
@@ -147,11 +161,23 @@ alarms and commits configuration; **approver** decides well tests and re-fits;
 ranking), Wells (add from a file, the catalogue or a live tag map; each well's
 reports, quality, trends, tests and alarms), Patch panel (supervised sources,
 their state and live values, their maps, live values), Alarms (the wall, acknowledge, definitions), Approvals (one queue),
+Files (the import and export roots an administrator allows, browse with
+detection by content, import into a well, "save to..." on every report, the
+evidence pack, watch folders), Alarms (the wall: acknowledge one or all, shelve
+with a reason and an expiry, unshelve; definitions), Approvals (one queue),
 Configuration (versioned JSON with history, diff and rollback), Reports
 (generate and open every report), Verification (the acceptance suite, FAT/SAT,
 SBOM and the standalone check from the page), Survey (a LAS file in, a strata
-report out), Jobs (every run with its log), Administration (users, schedule,
-audit log).
+report out), Jobs (every run with its log), Administration (users, live
+sessions, file roots, schedule, site settings, notifications, audit log). A
+search box in the header spans wells, alarms, reports, jobs, configuration,
+patches and schedules; the navigation shows badge counts (unacknowledged
+alarms, decisions waiting, failed jobs, patches down); Home opens with what
+happened since your last sign-in; every page has a help panel (the Help
+button hides them); every timestamp is shown in your time zone and every
+value in your units (field or SI - "Your preferences", with site defaults
+under Administration); a first-run guide walks a new site through its
+settings, first well, people and first refresh; every page prints cleanly.
 
 Every action the page takes is a job: `python -m gea <command>` run by the
 service with its log kept under `jobs/`, so one code path serves the page, the
@@ -173,16 +199,151 @@ evaluations and change logs), `reports/` (the printed dashboard and every
 report), `jobs/` (every run), `records/audit.jsonl`, `users.json`. All of it is
 text: JSON, JSON lines, CSV, Markdown, HTML.
 
+### The help library
+
+`gea help` lists fifteen 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
+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
+heading and under Help, so the terminal and the page cannot drift apart. The
+click-by-click tester guide ships with them: `gea guide`.
+
+### Which code is running
+
+`gea doctor` answers the question every stale-page report comes down to:
+which Python, which copy of the package, does pip's record match the code
+that runs (an editable checkout or an installed release), is another copy
+shadowing it, is the page present, which dependencies are installed, is a
+newer release on PyPI; with `--workspace` it also checks the site folder, the
+accounts, the patches, a free port and write access. Every finding carries
+its fix. `gea serve` runs the same checks and does not start on a blocking
+finding, so a stale page is never served silently.
+
+### Notifications
+
+Rules route events to channels: a webhook URL or an SMTP mailbox. Events:
+`alarm.activated` (by priority), `alarm.shelved`, `job.failed`, `patch.down`
+and `patch.up`, `approval.pending`, `file.imported`. A quiet window stops
+repeats of the same key; every attempt and every suppression is in
+`records/notifications.jsonl`; an SMTP password is read from the environment
+variable the channel names, never from the configuration. `gea notify
+--example` prints a configuration to commit as `notifications` (Administration
+has the editor and a "send a test" button per channel).
+
+### Instruments and transients
+
+A swapped gauge is a new instrument. Record the swap on the well page (or
+confirm one the step detector proposes - it looks for a jump in a gauge's
+offset against its peers, which a process change does not produce) and the
+drift fit restarts at the swap, with the swap printed in the report. File the
+calibration certificate of each instrument (serial, lab, dates, stated
+accuracy; the document is kept and hashed) and its status - VALID, EXPIRING,
+EXPIRED, MISSING - is on the well page, on Home, and beside the measured bias
+in the drift report, so a reader sees whether a bias is inside the
+instrument's own class.
+
+Every shut-in in a record (found by the rate channel, the on-stream hours, or
+the pressure signature alone when there is no rate - marked so) gets a
+build-up analysis on the next refresh: Horner slope and p* on a middle-time
+region chosen by the flat Bourdet derivative, wellbore storage, and - once the
+rock and fluid parameters are saved on the well page - kh, k, skin and the
+radius of investigation, each with a 90 % band from a residual bootstrap. The
+Shut-in and Pressure Transient report prints the region and the rule that
+chose it; an analyst can move the region (`gea transient --mtr 2:40`) and the
+result follows. It is the first look every shut-in should get automatically,
+not a replacement for a full interpretation, and it says so.
+
+### The second leg
+
+The second leg of the program is seismic: the client's site records ground
+motion that conventional processing treats as noise, and in that noise are
+the machinery lines of every rig working within range - mud pumps and their
+harmonics, rotary tables, engines. The leg starts with ingest and one measured
+number, not with a map. `gea seismic` reads the two formats the archives and
+most field recorders write (miniSEED with Steim1/Steim2 and integer/float
+encodings, decided by content; SAC), fetches records from any FDSN web service
+(`--base texnet` for the Texas network TX, `--base iris` for EarthScope), and
+produces the standard spectral products: the Welch PSD, a spectrogram, and
+the lines that persist above a running-median floor in the band where rig
+machinery sits (1-50 Hz by default). The decoder is proven in the acceptance
+suite against records written by libmseed, the format's reference
+implementation (`gea/reference/`).
+
+The first number is the detectability test (`--action detect`): one station's
+continuous record, the station's position, and a CSV of known rigs - position
+and working window from a public permit register or the operator's own
+schedule. For every rig that worked alone for enough windows the test
+compares the band power in its windows with the quiet baseline (the windows
+when no listed rig was working) and says DETECTED or NOT_DETECTED, with the
+excess in dB and the lines that belong to those windows and not to the quiet
+ones; a rig that never worked alone is AMBIGUOUS, and a record with no quiet
+hour gets NO_QUIET_BASELINE and no verdict at all. The result is the radius
+bracketed between the farthest rig heard and the nearest not heard - the
+station's measured reach for rigs like those on the list. Everything the leg
+can later claim sits inside that radius. What the test will not call a
+measurement is printed with it: a well's position or track (one station
+detects, it does not locate - locating is the array step that comes after
+this number exists), a radius beyond the farthest listed rig, anything about
+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.
+
+### Before a site goes live
+
+`deploy/README.md` is the checklist: keep the service on the loopback
+address and put a TLS proxy in front (`deploy/Caddyfile`,
+`deploy/nginx-gea.conf`), start with `--behind-proxy`. The service itself
+rate-limits sign-ins (five failures lock the name and the address for 15
+minutes, audited), lists and revokes live sessions, sends the security
+headers on every response, and `gea housekeeping --workspace C:\site --apply`
+(schedule it daily from Administration) segments the append-only logs rather
+than truncating them and prunes finished job folders and old recordings. `gea
+loadtest --patches 16 --seconds 60 --with-service` tells you whether the site
+machine carries the patches it will be given, with the page still answering.
+
+## The standalone install kit
+
+A client site often has no internet and no Python. The kit is one folder
+(and one zip) that carries its own Python, the package and every dependency
+as files, with the scripts a site needs; it installs without a network and
+without administrator rights, and keeps the site's data in a separate
+workspace folder it never deletes.
+
+```
+python tools/build_installer.py                       # dist/gea-program-<version>-win64/ and .zip (needs internet here, none there)
+python tools/build_installer.py --extras live,plotting,xls   # a smaller kit without the PyQt6 desktop window
+python tools/build_installer.py --platform linux      # a venv-based kit for a Linux site server
+```
+
+The kit carries every optional dependency by default - the live ports
+(asyncua, paho-mqtt, pymodbus, pyserial), matplotlib, xlrd and the PyQt6
+desktop window - so `gea sbom` from an installed kit lists all of them as
+installed; and `report-samples/`, one rendered example of every report.
+
+At the site: unzip, `install.cmd`, `start-dashboard.cmd`; the browser opens
+`http://127.0.0.1:8765/`. `verify.cmd` runs the acceptance gate from the
+installed kit (the client's own evidence), `register-service.cmd` starts the
+dashboard at logon, `uninstall.cmd` removes the kit and leaves the workspace.
+`SHA256SUMS.txt` lets the site verify the kit after copying it. Every tag
+builds the Windows and Linux kits in CI (`build-installer.yml`), installs
+them the way a client does, runs the gate from the installed kit, and
+attaches the zips to the GitHub release of that tag.
+
 ## Layout
 
 ```
 gea/            the package: engines, record layer, reports, monitor, dashboard, cli, shell, acceptance suite,
                 workspace, jobs, service, patches and web/app.html (the served dashboard)
 gea/catalog/    52 public archive entries, each with a provenance file
+gea/reference/  miniSEED records written by libmseed, with their provenance: the decoder's independent reference
+docs/report_samples/  one rendered example of every client report, from this build (tools/render_report_samples.py; SAMPLES.md names each command)
 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: imports, text, metadata; run by ci and ship.ps1)
+tools/          standalone_check.py (the self-contained guard; run by ci and ship.ps1), build_installer.py (the kit)
 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
 ```
@@ -199,10 +360,22 @@ density anchors and Vp ranges with their citations (Telford, Geldart and
 Sheriff; Schon). Every catalogue entry under `gea/catalog/` has a provenance
 file naming its public source.
 
-Two statements the product carries on its own model cards: the gauge aging
-envelope's lower bound is an engineering model with no field validation on
-record, and five of the fourteen back-tested strata quantities are NOT
-ACCEPTABLE at the 95 % target. Both are printed, never claimed otherwise.
+The gauge aging rate the drift evaluation uses is the instrument's published
+drift specification, read from a cited datasheet (`gea/gauge_specs.py`), with
+nothing added for temperature or pressure - above the rating the rate is
+flagged, not changed. The program carries no aging model of its own, no
+engineering constant that is not a datasheet number, and no claim about a
+gauge beyond what its datasheet says; `tools/standalone_check.py` fails the
+build on the names, phrases and numbers of the model that once stood there.
+The seismic leg is textbook signal processing - Welch's PSD estimate, a
+running-median floor, band power, great-circle distance - and the decoder is
+checked against libmseed; the synthetic scene behind its self-test states its
+own assumptions (body-wave spreading, a Q) and is labelled as a scene, not a
+ground. Two statements the product carries on its own model cards: the datasheet
+rate has no field validation on record against a gauge with a known history
+(`gea bench` is the instrument for it), and five of the fourteen back-tested
+strata quantities are NOT ACCEPTABLE at the 95 % target. Both are printed,
+never claimed otherwise.
 
 ## Shipping
 
@@ -212,7 +385,9 @@ not exist anywhere, every version in `SHIP_LOG.md` must have its tag, `python -m
 accept` must be green, `SHIP_MESSAGE.txt` must start with the tag; then commit, tag,
 push, and the remote tag must be seen before SHIPPED is printed. `CHANGELOG.md` must carry a
 section headed by the tag, and `tools/standalone_check.py` must report no findings. `-DryRun` runs every
-check and changes nothing; `-NoPush` stops after the local tag.
+check and changes nothing; `-NoPush` stops after the local tag. Before the gate, after the bump:
+`python tools/render_report_samples.py` re-renders `docs/report_samples/` from the new build
+(section AM fails on a stale build number).
 
 ## Publishing to PyPI
 

gea_program-0.5.0/gea/BENCH_TEST_PROTOCOL.md

@@ -0,0 +1,91 @@
+# Bench-Test Protocol - Does this gauge drift within its datasheet?
+
+The program judges a measured drift trend against one number: the
+instrument's published drift specification (percent of full scale per year,
+from its datasheet). That number is a specification, not a measurement of
+the gauge in your hand. This protocol is the measurement: one gauge, one
+held setpoint, one reference standard, enough weeks, and a verdict written
+down - the bench record the drift report cites as `NONE ON RECORD` until it
+exists.
+
+---
+
+## 1. What is being tested
+
+For a gauge of serial number S with datasheet drift specification D (%FS/yr):
+
+```
+measured drift rate (|slope| of the gauge's reading against the reference, at a held setpoint)
+compared with D, with the slope's own standard error
+```
+
+The outcome is one of four words (section 5). A gauge that drifts faster
+than its datasheet is a finding, not an error.
+
+## 2. Apparatus
+
+- The gauge under test, with its serial number and its calibration
+  certificate id (both go on the record; `gea certificates` files the
+  certificate).
+- A temperature-controlled bath or pressure vessel holding a setpoint inside
+  the gauge's rating (the rating check applies on the bench too).
+- A reference pressure standard of a class better than the specification
+  under test (deadweight tester or transfer standard), logged at the same
+  cadence, or at least checked weekly and logged.
+- Logging at one reading per day or better into the program's historian CSV
+  format (a timestamp or `time_s` column and one pressure column per
+  instrument).
+
+## 3. Duration - the program's own rule applies
+
+The reconciler refuses trend verdicts below its minimum span
+(`ReconcilerConfig.min_trend_span_years`, the 18-day rule), and the bench
+analysis reads that floor from the same configuration: a shorter record is
+`INSUFFICIENT_SPAN`, no verdict. The protocol asks for **at least 90 days**
+at setpoint; 180 days or more when the specification is tight (a 0.01 %FS/yr
+gauge at 30,000 psi full scale drifts 3 psi in a year - 0.75 psi in 90
+days - so the reference and the logging must resolve tenths of a psi).
+
+## 4. Procedure
+
+1. File the certificate (`gea certificates --action add ...`) and record the
+   serial number.
+2. Install the gauge and the reference at the setpoint; log continuously.
+3. Weekly: verify the setpoint against the reference; do not adjust the gauge
+   under test. Log every intervention.
+4. Export the gauge's series and the reference's series as historian CSVs.
+5. Run:
+
+       gea bench --gauge-csv gauge.csv --reference-csv reference.csv --spec geoq177_30k --serial SN --certificate CERT --out bench_register.jsonl
+
+   The reference series is subtracted first (the setpoint's own wander is
+   not the gauge's drift). `--spec` names the datasheet preset or a JSON
+   datasheet of your own.
+6. Keep the record: the JSON line appended to the register carries the fit,
+   the band, the datasheet source, the serial, the certificate and the verdict.
+
+## 5. Analysis and verdict vocabulary
+
+- The slope of the (gauge - reference) series is fitted by least squares;
+  its standard error comes from the residuals.
+- A band of k sigma (default 2) is placed around the measured rate.
+- `WITHIN_DATASHEET` - the whole band is at or below the specification.
+- `EXCEEDS_DATASHEET` - the whole band is above the specification: this
+  gauge, at these conditions, drifts faster than its datasheet says. A
+  first-class outcome.
+- `INSUFFICIENT_SPAN` - shorter than the 18-day floor; no verdict.
+- `INSUFFICIENT_SNR` - the band straddles the specification; a longer span
+  or a quieter setpoint is needed; no verdict.
+
+`gea bench --selftest` runs the arithmetic on synthetic series and labels
+its output `SIMULATION_SELF_TEST`; it proves nothing about a physical gauge.
+
+## 6. What the record changes
+
+Nothing in the program's arithmetic changes with a bench result; the
+datasheet rate stays the rate the reports use. What changes is the model
+card's `field validation` line, which can cite the register once a gauge
+with a known history has been run, and the reader's confidence in a
+`DRIFT_CONSISTENT` label on that instrument. An `EXCEEDS_DATASHEET` record
+is the reason to recalibrate, replace or re-rate that gauge, and to file
+the result with its certificate.