petrolyst-infra/petrolyst-insights/dashboards/atoma/SPEC.md

ATOMA dashboard: Fleet map and Site details

Status: built and tested on a local Superset (P2, 24 Oct 2026); merged into one dashboard with the fleet-map view on 28 Oct 2026 (§9); not imported live.

• build_bundle.py generates the dashboard, every dataset and every chart from this specification, as one Superset import bundle; import_bundle.py imports it (§6).
• The local tests changed parts of this design. Each change is marked (P2) and §8 lists them.
• The merge of 28 Oct (owner's decisions PD-5 and PD-6, Petrolist/.context/design-decisions.md) replaced the Sites Map dashboard by a Fleet tab holding the fleet-map view of petrolyst-platform. Changed parts are marked (28 Oct); §9 lists the results.
• Nothing is imported into the live Superset without the owner's go-ahead (phase P3).

Datasets. The public.v_* views of stacks/fuel-monitoring/fuel-db/migrations/0003_bi_views.sql, read through Trino as fuel.public.

Design and rationale live in the fuel-monitoring corpus, in .context/plans/2026-10-24-fuel-db-baseline-dashboard.md:

• its §6 is this specification;
• the site-specific facts left out here (positions, distances, pilot sites) are there too;
• Q-numbers refer to its §7, and phases P0–P5 to its §8.

One dashboard (two until 28 Oct) replaces the earlier tab-per-site design; nothing in it is specific to a site.

1. Capabilities of the installed Superset 6.1.0

Source: read-only inspection of config.py, superset_config.py and the frontend bundle on 24 Oct 2026. The former (local test) items were tested in P2 (§8); rows marked (P2) changed as a result.

Requirement	What 6.1.0 provides	Choice
Map chart	deck_scatter (deck.gl Scatterplot): a modern plugin with the InteractiveChart behaviour. Also: deck_multi, deck_screengrid / hex / grid, country_map, world_map, cartodiagram, legacy mapbox	deck.gl Scatterplot
Basemap	DECKGL_BASE_MAP unset → OSM raster (tile.openstreetmap.org), OSM Swiss topo, Mapbox styles. MAPBOX_API_KEY is empty, so the Mapbox styles fail. CSP connect-src already allows the OSM host; Traefik sets no CSP	set DECKGL_BASE_MAP to OSM only; "© OpenStreetMap contributors" in a Markdown under the map
OSM terms	no key, no cost; tile usage policy: light use, attribution, no bulk download, a valid Referer (ours sends the origin)	fine for an internal user base; viewers' browsers reveal the viewed area (tile coordinates) and their IP to OSMF, not our data. Self-hosted tiles later if needed
Tooltip	"Tooltip contents" (drag columns) plus "Customize tooltips template" (Handlebars). js_tooltip exists but ENABLE_JAVASCRIPT_CONTROLS is False. The contents show column names, not labels, and leave out the colour column	contents only (P2): short tooltip-only calculated columns (code, name, l_per_h, method, status, validity, latest_record); no template, no JavaScript
Marker colour	"Categorical color" by a dimension, from the colour scheme; a fixed colour per label through the dashboard's label_colors (confirmed in P2)	colour by baseline_status_label
Marker size	fixed radius, with minimum = maximum pixel radius. No outline: the layer is drawn with stroked: false	uniform, no outline (P2)
Text cards	The Handlebars chart compiles its template with eval; Superset's own CSP (script-src 'self' 'strict-dynamic' + nonce) blocks that, so the chart shows a CSP error instead (P2)	no Handlebars: one-row tables. The CSP stays as it is
Chart descriptions	"Show description" (expanded_slices) never renders in 6.1: the dashboard loads description_markeddown, the chart holder reads description_markdown (P2)	descriptions stay on the charts; the visible reading notes are a Markdown block at the top of each tab
Viewport	autozoom fits the filtered points	on
Clustering	none in deck.gl; only the legacy mapbox chart (clustering_radius, needs a Mapbox key)	no clustering (§3)
Marker click	emits a cross-filter on the latitude and longitude columns: the exact point, or a box around the click that shrinks as you zoom in. It applies to other charts on the same dashboard	cross-filters the Sites list
Navigation	no chart-to-dashboard navigation. A dashboard reads ?native_filters=<rison> into preselected native filter values (also native_filters_key). Table cells render sanitized HTML (allow_render_html)	an "Open site detail" link column in the Sites list
Native filters	Select (single or multi, required, searchable, "first value by default"), Time range; scoping per chart and tab; cross-filter scoping per chart	§4, §5
Markdown iframe (28 Oct)	HTML_SANITIZATION is on and strips an iframe from a Markdown block; HTML_SANITIZATION_SCHEMA_EXTENSIONS lets named tags and attributes through. The CSP (default-src 'self', no frame-src) allows frames from this origin only	allow iframe with src, title, loading, style; the fleet-map view is served on the same origin under /views (§3)
Deep link into a tab (28 Oct)	#TAB-<id> after the URL opens that tab; it combines with ?native_filters= (tested 28 Oct)	the "Site details" button opens the Site details tab with the site preset

(28 Oct) The map moved out of Superset into the fleet-map view (§3). The rows Map chart, Basemap, Tooltip, Marker colour, Marker size, Viewport, Clustering and Marker click describe the deck.gl option the dashboard used until then; the view's choices are in §3. The Navigation row still holds: the view builds the same ?native_filters= link.

No custom frontend and no patch are needed.

2. Navigation flow

(28 Oct) One dashboard, two top-level tabs. (29 Oct) They are named Map (TAB-fleet) and Insights (TAB-site), the dashboard's lenses; earlier text in this document calls them Fleet and Site details. Readers see them as a lens switch, centred in the navbar (§6).

ATOMA  (slug atoma)
  filters, in Superset's left column: Site (exactly one, searchable) · Viewing period
           — both out of scope on Map; readers have no column there (§6)
  [Map]    the fleet-map view (iframe, /views/fleet-map/), the page's full width
           towers fitted to the placed sites ──hover or click──► popup
           "Find a site" (code or name) ──► the map flies to it ──► its popup
             └─"Site details"──► /superset/dashboard/atoma/?native_filters=(site preset)#TAB-site
           sites without an accepted location: counted in the map's key ("Choose them in Insights",
           the view's tab_label parameter); chosen in the Site filter
  [Insights]  D0 site header, then the tabs
           Summary · Fuel & Deliveries · Runtime & Electricity · Baseline & Evidence
           (a row of section buttons, not a second row of tabs: dashboard.css)

The filters sit in Superset's left column (filter_bar_orientation: VERTICAL) (owner, 29 Oct; build_bundle.py checks it). A filter shows in the column on the tabs where it is in scope; the others are listed under "Filters out of scope" (the Viewing period on Summary, for example). No filter applies to the Fleet tab, so readers have no column there and the map takes the full width (reader.css, §6); admins keep the column on both tabs. The column opens collapsed, a 32 px strip with an expand button (FILTERBAR_CLOSED_BY_DEFAULT, superset_config.py; owner, 29 Oct); the selected site shows in the Site table above the sections. So for a reader the tabs move sideways by 32 px between Fleet and Site details, or by the column's width once it is expanded; the owner accepted that.

From 28 to 29 Oct the filters sat in a row above the tabs (HORIZONTAL). On the Fleet tab that row held only an empty "More filters", and hiding it there made the tabs jump down on Site details. Superset 6.1 has no per-tab setting for the filter bar; it hides it only per link (?show_filters=0).

Until 28 Oct there were two dashboards: "ATOMA - Sites" (slug atoma-sites: a deck.gl map, five filters, a sites list) and "ATOMA - Site Detail" (slug atoma-site-detail), linked by "Open site detail" and "← Sites map".

3. Fleet tab: the fleet-map view (28 Oct)

The Fleet tab holds one Markdown block with an iframe of the fleet-map view, a page of petrolyst-platform (views/src/fleet-map/) served under /views/ on Superset's own origin. The view reads the read service's site_status operation (/views/api/v1/site-status, from public.v_site). It is not a Superset chart: it has no dataset and no native filter, and both filters are out of scope on this tab.

[Fleet tab: MARKDOWN-fleet-map, w12 h100]
  <iframe src="/views/fleet-map/?detail=/superset/dashboard/atoma/&filter=NATIVE_FILTER-site&tab=TAB-site">

Part	Content	Missing or insufficient
Map	MapLibre on OpenFreeMap Positron: OpenStreetMap data, English and Dari place names (chosen by the owner on 28 Oct after a side-by-side with OSM standard tiles, which carry the same data). Fitted to the placed sites, clear of the key	no placed site: Afghanistan, and the key says so
Towers	one per site with an accepted location: a pin holding a lattice tower, in the site's baseline status colour (below); a site that is not an active pilot site faded; uniform size. The site's identity is site_uid, since two sites can share a site_code (an alias cut to 20 characters)	sites without an accepted location are not drawn
Popup	opens 120 ms after hover; stays while the pointer is on the tower or the popup; closes 250 ms after it leaves both. A click, tap or keyboard focus pins it; Esc or a click on the map closes it. It springs out of the tower (a fade only with reduced motion) and takes the side with room; when neither side has room for all of it, the side with more room, where its figures scroll while the header, the status with any validity note, and Site details stay in view. Content: code, name; status as baseline_status_text ("not approved" for Eligible and Provisional); any baseline_validity_note right beside the status and the L/h; L/h with method ("not available" when NULL); L/day, "whole record, not per running hour"; latest record; pilot status by name (active, reference, candidate, withdrawn, or not in the pilot); other sites whose towers cover this one (the same or nearly the same position), each a button that switches the popup to it; Site details	an approved estimate whose inputs changed is never shown without its validity note
Site details	a link (target="_top") to this dashboard with the site preset in the Site filter, on the Site details tab: the ?native_filters= value of §5 plus #TAB-site. The iframe's address names the dashboard, the filter and the tab, and build_bundle.py checks them	no link when that address is missing or malformed: the view accepts only a dashboard path and filter and tab ids of a fixed shape
Search	"Find a site: code or name", top left. Matches ignore case: code prefixes first, then codes containing the text, then names containing it; at most 8, each with its status dot and status. Arrow keys and Enter, or the pointer, choose one; the map flies to it at zoom 14 or closer (past the clusters) and pins its popup. Esc clears the field	sites without an accepted location are not searched (owner's choice, 28 Oct): the key counts them and the Site filter finds them; "No site matches" when nothing does
Operator's logo	ATOMA's logo in its own colours, bottom right above the map's credits, on frosted glass (owner, 29 Oct). The dashboard passes it in the iframe's address (logo=/static/assets/branding/atoma_logo.svg, logo_alt=ATOMA; build_bundle.py checks the file exists); the view takes only an image from that folder on its own origin, so it carries no operator's branding	no logo in the address: no logo
Key	the four statuses; "Faded: not an active pilot site"; "Colours show evidence status, not performance"; the number of sites without an accepted location, with "Choose them in Site details"	—
Keyboard, screen readers	a hidden list of the sites with the same links; focusing one opens its popup	—

Baseline status and tower colours. Colours are neutral categorical hues, with no red or green and no reference to L/h:

Status	Definition (fm.v_site_baseline_status)	Colour
Approved baseline	an approved baseline_version with a decision reference. The only state that says "approved"	teal #009688
Eligible – not yet approved	no approval; the latest proposed KPI version has meets_policy (BP-1: ≥ 2 eligible G1 inputs, ≥ 30 matched days, no conditions, one population and metric)	blue #3987e5
Provisional	no approval; a proposed version below BP-1, or usable intervals with no version yet (no estimate shown, method "no baseline version proposed")	amber #c98500
Insufficient evidence	no usable interval. Every pilot site while no runtime evidence exists	slate #64748B

Nearby sites. Towers that would overlap cluster into a teal circle with their count (radius 36 px, up to zoom 13); a click on it zooms in until they separate. The pilot's sites, a few kilometres apart, separate at the zoom the map opens with. The towers are one symbol layer, so thousands of sites stay fast.

Sites without an accepted location are not plotted. The key counts them, and the Site filter in Site details lists every site, placed or not.

4. Site details tab (any site)

Filters

• Site (NATIVE_FILTER-site):
  • Select on v_site.site_label, single value, required, searchable, first value by default with requiredFirst (the §4 fallback, adopted in P2);
  • scope: every chart on every tab;
  • every detail dataset carries site_label from v_site, so this one filter drives all of them (confirmed in P2: every chart request carries the selected site).
• Viewing period (NATIVE_FILTER-period):
  • Time range, default no filter;
  • scope: the time-series charts on Fuel & Deliveries and Runtime & Electricity only;
  • Summary and Baseline & Evidence are outside its scope, so a viewing range never changes a baseline's fixed window.

Exactly one site, and never network totals:

1. A required, single-value filter. P2: "required" alone does not stop the charts: with no value they queried every site.
2. Therefore "Select first filter value by default", with requiredFirst, as the filter editor writes it: the charts wait for the filter, the first site is applied without "Apply filters", and "Clear all" stays disabled. Without requiredFirst the first value waits behind "Apply filters" while the charts have already queried every site.
3. No Big Number or aggregate tile for site figures. They are computed per site in v_site, never aggregated by Superset. (29 Oct, PD-12: the app's Overview, §10, adds up recorded amounts across sites; per-site rates are still never averaged.)
4. The Handlebars "Select one site" guard is gone with Handlebars (§1); with (2) the filter is never empty.

[D0 Site: one-row table, code · name · province · pilot status · baseline status · location] (28 Oct: inside Site details, no link)
every tab            [Reading notes (Markdown) w12]                                  (P2)
Summary              [S1 Fuel per running hour: one-row table w12]                   (P2)
                     [S2 Supporting measures w12]
                     [S3 Evidence coverage timeline (Gantt) w12]
Fuel & Deliveries    [F1 Deliveries w6][F2 Recorded stock w6]
                     [F5 Deliveries table w12]                                       (P2)
                     [F3 Fuel per calendar day by interval w12]
                     [F4 Interval table w12]
Runtime & Electricity[R1 Runtime per day by meter interval w6][R2 Hour-meter evidence w6]
                     [R1T Runtime pairs and their validity w12]                      (P2)
                     [R3 Grid energy, kWh w6][R4 Electricity cost, AFN: bar over table w6]
Baseline & Evidence  [B1 Baseline versions w6][B2 Inputs of each version w6]
                     [B3 All intervals: eligibility and exclusions w12]
                     [B4 Interval L/h against baseline w12]
                     [B5 Assumptions w6][B6 Missing data and quality checks w6]
                     [B7 Evidence references w6][B8 Workbook calculations, assessed w6]
                     [B9 Stock against engine-measured fuel w6][B10 Equipment specifications w6]
                     [B11 Modelled L/h under an assumed runtime w12]

#	Question it answers	Type	Dataset	Dims / measures (units)	Grain	When data are missing or insufficient
D0	Which site am I looking at?	Table, one row (P2)	v_site	code, name, province, pilot status, baseline status, location status (28 Oct: the link "← Sites map" is gone; the Fleet tab is one click away)	site	the Site filter is never empty (§4)
S1	What is the site's L/h, by which method, over which window, how strong?	Table, one row (P2)	v_site	lph_estimate, lph_method, baseline_status_label, baseline_validity_note, window, decision; L/day whole record	site	Keeps its position. In v1 every site shows "Insufficient runtime evidence: no hour-meter readings", plus L/day labelled "per calendar day, not per running hour". "Eligible" and "Provisional" carry "not approved"
S2	What supports it?	Table	v_kpi_measures	measure, value, unit, value_kind (recorded · calculated · assumed · not established), window. Two L/day rows: the whole record (moves with new records) and the L/day reference version (fixed window, its status and any input drift in the note)	site × measure	Rows stay and show "not established"
S3	Which periods are covered by which evidence, and where are the gaps?	Gantt	coverage_detail (P2: virtual dataset over v_coverage)	lane name without the view's sort number; start/end; colour = status; tooltip: litres delivered in a stock interval, or a bill's AFN amount	span	Nothing is interpolated. (P2) The view emits a lane only where spans exist, so the tab's notes name the four lanes and say that a missing lane means no span could be formed: no evidence of that kind, or too few readings (F2, R2 show single readings)
F1	When and how much was delivered?	Bar (time axis, day grain)	v_delivery (one row per delivery event)	delivery_date; SUM(delivered_l), titled "Litres delivered per day (all deliveries that day)"	day	Bars only on delivery dates; "deliveries are not consumption" in the tab's notes. (P2) The count and the individual deliveries are in F5, a table on v_delivery (date, visit of the day, event, litres, price, sources, review), which also lists a delivery of unknown quantity; its search box shows the number of records
F2	What stock was recorded?	Scatter (no lines)	v_stock_reading	observed_on; litres; series = reading type × value_kind, split by visit when a day has several (P2)	observation	Points only; nothing between readings
F3	How much fuel was used per calendar day in each observed interval?	Bar (categorical x, ordered by start)	v_interval	interval_label; MAX(fuel_l_per_day) (L/d); colour = stock_status	stock interval	Intervals that are not ok greyed (P2: fixed grey per status in Site Detail's label_colors); the status is the series name, so legend and tooltip give the reason; no monthly spreading
F4	Interval detail	Table	v_interval	dates, opening, deliveries, closing, used, L/d, status	interval	Shows the reasons
R1	How many hours did each generator run per day?	Bar (categorical)	v_runtime	interval × meter; MAX(h/day). h/day is NULL for an invalid pair (pair_valid false: two epochs, a decreasing timer or over 24 h/day); such pairs show no bar and are listed with their flags in R1T, a pair table with pair_valid, same_epoch, monotonic, over_24h_per_day (P2: the bar tooltip cannot show them)	meter interval	v1: empty, with "No hour-meter readings" in the tab's notes
R2	What runtime evidence exists?	Table	v_hour_meter_evidence	meter, mapped set, date, hours, state, epoch	reading	v1: no rows, "No hour-meter readings"
R3	How much grid energy did the site receive?	Table, the kWh row (P2); a bar once kWh exist	v_kpi_measures (kWh row)	kWh per bill month	month	"No kWh records; bills are cost only and are not converted to fuel or hours"
R4	What did grid electricity cost?	Bar (month) + table	v_electricity_cost	bill month; amount (AFN, inferred)	month	Own chart, never on a fuel axis. A disputed bill is listed without amount or kWh
B1	Which baseline versions exist, and who approved them?	Table	v_baseline_version	code, status, value, window, grade, decision	version	"No baseline defined"
B2	What went into each version?	Table	v_baseline_input	interval, included, reason, fuel, runtime, drift	version × interval	empty until a version exists
B3	Which intervals are usable, and why not?	Table	v_interval	eligibility, exclusion reasons, grade, conditions, in current baseline	interval	v1: every interval excluded, "no timer reading at both ends" (and "a generator has neither a counter nor an idle assumption")
B4	What L/h did each interval give, against the approved baseline?	Mixed: bars + line	v_interval	x interval_label; A: MAX(l_per_h) where eligibility ≠ excluded; B: MAX(current_baseline_l_per_h) (approved value only, and only beside intervals of the same metric and population, baseline_comparable)	interval	v1: no bars; description points to S1
B5	Which assumptions apply?	Table	v_assumption	code, topic, value and range, basis, status, rationale	assumption	"None recorded"
B6	What is missing or inconsistent?	Table	v_data_quality	check, status, detail	check	Lists the gaps: no runtime, placeholder rows, no kWh, no transfer records, location awaiting acceptance
B7	Which documents do the figures rest on?	Table	v_evidence	title, kind, issuer, date, used for	document	—
B8	What did the operator workbook calculate, and is it usable?	Table	v_imported_calculation	label, formula, value, our reading, use, reason, claim_status	cell	Shows "excluded" with the reason for "actual L/h" and "CP L/h". A disputed transcription shows its status, without formula or value
B9	Does stock depletion match engine-measured fuel?	Table	v_reconciliation	engine L of this generator, covered_h of interval_h; site-wide: stock L, engine L of all generators, all_generators_metered, difference L and % (P2: both engine totals shown, so the difference reconciles). The window runs from the opening visit's departure to the closing visit's arrival. The difference is shown only for an ok stock interval with both visit times recorded, in which every generator is placed at the site throughout and covered for the whole window	interval × generator	"No flow-meter data yet"; partial coverage, unknown visit times or a mid-interval placement show the hours covered and no difference
B10	What does the equipment specification say?	Table	v_spec_reference	attribute, value, unit, basis, applicability, claim_status	spec	Titled "Manufacturer and nameplate data, not site performance". A disputed specification shows its status, without value
B11	What would L/h be under the stated runtime?	Table	v_modelled_lph	assumption code, status, basis; h/day with low–high; window, matched_days; L/day; modelled L/h with low–high; value_kind	site × assumption	Titled "Modelled from an assumed runtime, not measured". "No runtime assumption recorded"

Modelled L/h (B11) is in v1 (Q9, decided 24 Oct 2026). It pools only the usable intervals inside the runtime assumption's dates, and shows that window and its days. It never reaches S1 or the fleet map.

5. Datasets and filter mapping

Physical datasets, one per public.v_* view on Trino fuel.public, plus one virtual dataset (P2). coverage_detail adds two columns to v_coverage:

• lane_name, the lane without its sort number, which read as a count;
• amount, a stock interval's delivered litres (from its opening visit up to its closing visit, so the opening refill is included) or a bill's AFN amount.

Both use only v_coverage, v_delivery and v_electricity_cost. Every dataset has the same four site columns from v_site: site_uid, site_code, site_name, site_label.

Dataset	Grain	Used by	Native filters that apply
v_site	site	D0, S1; the fleet-map view through the read service (28 Oct)	Site
v_kpi_measures	site × measure	S2, R3	Site
v_coverage	site × lane × span	— (S3 reads coverage_detail)	Site
coverage_detail (P2)	site × lane × span	S3	Site
v_delivery	delivery	F1	Site, Viewing period
v_stock_reading	observation	F2	Site, Viewing period
v_interval	stock interval	F3, F4, B3, B4	Site; Viewing period on F3 and F4 only
v_runtime	meter interval	R1	Site, Viewing period
v_hour_meter_evidence	reading	R2	Site, Viewing period
v_electricity_cost	bill month	R4	Site, Viewing period
v_baseline_version, v_baseline_input	version (× interval)	B1, B2	Site
v_assumption, v_data_quality, v_evidence, v_imported_calculation, v_reconciliation, v_spec_reference, v_modelled_lph	per view	B5–B11	Site

Metrics. Saved metrics enforce pooling, with the same eligibility filter on numerator and denominator, e.g. pooled_l_per_h = SUM(CASE WHEN eligibility <> 'excluded' THEN fuel_used_l END) / NULLIF(SUM(CASE WHEN eligibility <> 'excluded' THEN runtime_h END), 0). A chart that uses it is grouped or filtered by metric and population_key (both in v_interval), so it never pools across methods or generator sets. The site's L/h figure itself comes only from a baseline version (v_site), never from this metric. There is no AVG metric on ratio columns.

Site details link (28 Oct). The fleet-map view builds it (petrolyst-platform views/src/shared/deepLink.ts) from its iframe address: the dashboard path, the Site filter's id and the tab. The rison shape is the one the sites list used until 28 Oct, confirmed in P2, and the view's tests compare it with that list's Trino output:

/superset/dashboard/atoma/?native_filters=<url-encoded:>
  (NATIVE_FILTER-site:(id:NATIVE_FILTER-site,extraFormData:(filters:!((col:site_label,op:IN,val:!(q)))),
   filterState:(value:!(q)),ownState:()))
#TAB-site
-- q = the site label in rison quotes: 'label', with ! written !! and ' written !'

6. Build as code, scale, access

Build

• build_bundle.py --database-uuid <uuid> writes one import bundle containing the dashboard, every dataset and every chart:
  • stable UUIDs (uuid5), so a re-import updates instead of duplicating; the zip is byte-identical for the same inputs;
  • fixed native-filter ids (NATIVE_FILTER-site, NATIVE_FILTER-period) and tab ids (TAB-fleet, TAB-site, TAB-summary, …);
  • label_colors for the four statuses;
  • every view column, from columns.tsv (a snapshot of Trino's information_schema);
  • the existing "Fuel (Trino)" database UUID, which differs per instance: import_bundle.py --show-database prints it.
  • Before writing, it checks that every column a chart or filter uses exists in its dataset, that every chart in a Site filter's scope has site_label, that the fleet map's iframe address names this dashboard, its Site filter and the Site details tab (28 Oct), and that no row is wider than 12.
• Import: import_bundle.py <zip> --user <username>, inside the Superset container (P2: not superset import-dashboards, which leaves existing datasets and charts unchanged on a re-import). It runs the dataset, chart and dashboard importers with overwrite on, never creates or changes the database, and reports columns that differ between a dataset and its view.
• A re-import replaces edits made in the Superset UI to these objects.

Adding a site

• Import its site.yaml and its records. Nothing in the dashboard or the fleet-map view names a site.
• A new site appears in the Site filter, and on the map once its location is accepted; until then the map's key counts it.

Hundreds of sites

• v_site has one row per site; the fleet map draws its towers as one symbol layer and clusters overlapping ones, so thousands of sites stay fast.
• The Site filter loads the distinct labels; with thousands of sites, check its value limit (open point 6 of the design decisions).

Superset configuration changes (in superset_config.py; image rebuild in P3):

• DECKGL_BASE_MAP = [["tile://https://tile.openstreetmap.org/{z}/{x}/{y}.png", "OpenStreetMap"]] (no deck.gl chart since 28 Oct; kept for charts made by hand);
• (28 Oct) HTML_SANITIZATION_SCHEMA_EXTENSIONS lets an iframe (src, title, loading, style) through a Markdown block. The fleet-map view must be served on the same origin under /views (petrolyst-infra routing, not part of this step).

The CSP needs no change. P2: the tiles load and the map causes no CSP violation. One violation appears on every Superset page, including the stock dashboard list: a capability probe (Function("")) in the 6.1 frontend bundle, caught by the bundle itself.

Access, internal first. The dashboard for Admin and Alpha only; the read service behind the same sign-in (28 Oct: not built yet; locally it has none). No Gamma role until the ATOMA-facing edit.

ATOMA's readers (owner, 29 Oct). The Superset role "ATOMA Reader" (Keycloak client role atoma-reader) reads the ATOMA dashboard and nothing else.

• The role (petrolyst-insights/roles/atoma_reader.py): exactly 12 permissions, set by superset-init whenever the image changes, and reset by hand with the command in the README.

  • Dashboard and Chart can_read;
  • Superset can_dashboard, can_dashboard_permalink, can_log;
  • Api can_time_range;
  • the filter state (can_read and can_write), permalinks (can_read), the current user, the CSRF token and the menu.

  It has no menus, no write rights, no Explore, CSV, sharing, drill or query view. The bundle import attaches the role to the dashboard (DASHBOARD_RBAC).

• Rules a role cannot express (petrolyst_reader.py, in both security managers):

  • readers own nothing, and reach a dashboard only through its roles (published, role match);
  • the dashboard list shows them only those;
  • their chart-data responses carry no SQL (patches/fix_redact_query_for_readers.py; Superset itself drops it only for embedded guests).

• What they see:

  • every page they open leads to the ATOMA dashboard;
  • a stylesheet loaded only for them (assets/branding/reader.css) hides the dashboard's title row, the theme switcher, and Info and About in Settings, leaving Logout;
  • the same stylesheet hides the filter column on the Fleet tab, and while the dashboard loads. It sizes the map to the window: the full width at once (Superset measures widths again only about 0.3 s after loading), and down to 32 px above the window's bottom edge instead of the layout's 800 px, at least 560 px. build_bundle.py checks that it names the Fleet tab and that the map spans all 12 columns;
  • the same stylesheet turns the top-level tabs into a lens switch, centred in the navbar, with an icon each; the map's block then grows by the tab row's height. A scroll-linked animation moves the switch up with the navbar, which scrolls away. Without support for scroll-linked animations, or narrower than 900 px, the tab row stays in the page. From 1100 px the switch shows a third lens, AI, as a teaser: greyed, tagged PRO in green, drawn by the tab list (not a tab, not clickable; the layout keeps Map and Insights). Narrower, it would cover the logo. build_bundle.py checks that every layout id the stylesheet names exists;
  • the stylesheet's address carries a hash of its content (petrolyst_reader.register): Superset lets browsers keep static files for a year, so a changed file would otherwise not reach readers who loaded the old one;
  • Superset already hides the menus, "+" and editing from a role without them.

• One refused request remains, harmless: Superset stores a dashboard's label colours when they changed (PUT /api/v1/dashboard/<id>/colors). A reader may not, so it is refused until someone with edit rights opens the dashboard; the colours show either way.

• A reader is someone whose only roles are "ATOMA Reader" (and Public). Anyone with Admin, Alpha or Gamma as well sees everything as before.

7. Acceptance checks

Run in P2 against a local Superset, and repeated as a smoke test in P3.

1. New site, no new objects. Count dashboards, charts and datasets in the metadata database. Then import a synthetic fourth site with records and an accepted location, and a fifth with no location. The counts are unchanged; site 4 appears on the fleet map and in the Site filter; site 5 appears in the Site filter, and the map's count of sites without an accepted location goes up by 1 (28 Oct).
2. Site switching. In Site Detail, select pilot site A, then site B. D0 shows the new code and name; every chart's query (View query, or chart-data API) carries site_label = …<site B>…; no chart keeps site A's rows.
3. Clearing the selection. With the Site filter cleared, no chart shows multi-site data; D0 and S1 show "Select one site". If not, switch to the §4 fallback and re-test.
4. Unavailable L/h. For each pilot site:
   • the fleet map's popup says "not available" with the method "no runtime evidence" (28 Oct);
   • S1 shows the insufficient-evidence state plus L/day;
   • B3 shows every interval excluded, with its reason;
   • B11 shows a modelled range labelled "not measured", and that figure appears nowhere else.
5. Missing coordinates. A site without an accepted location is not plotted, is counted in the map's key, and can be chosen in the Site filter (28 Oct).
6. Filter propagation.
   • (28 Oct) Both filters are out of scope on the Fleet tab; the fleet map shows every placed site, sites that are not active pilot sites faded.
   • In Site details, the Viewing period changes F1–F5, R1, R1T, R2, R4 and R4T, but not S1 or B1–B4.
7. Detail links (28 Oct). For each placed site, "Site details" in its popup opens the Site details tab with exactly that site selected and Summary open; D0 matches, and every chart's request carries that site.
8. Colours.
   • Fixtures in each status show the four colours.
   • "Eligible" never renders as "Approved" unless the fixture has an approved version with a decision reference.
   • Marker size is identical across sites.
   • (28 Oct) An approved site whose inputs changed shows its validity note beside the status and the L/h in the popup.
9. Basemap. The fleet map's tiles load, the attribution is visible, and neither the view nor the dashboard adds a CSP violation (Superset's own probe, §6, stays) (28 Oct).

8. P2 results (local, 24 Oct 2026)

Local Superset 6.1.0 image built from this repository, Trino 484, fuel-db with migrations 0001–0003 and the corpus data loaded; browser checks in headless Chrome.

Check	Result
1 New site	pass: with a synthetic site with an accepted location and one without, the object counts stay unchanged (2 dashboards, 28 charts before R1T was added, 18 datasets); the first is in M1, M3 and the Site filter, the second in M5, and M4 goes from 0 to 1. Fixtures removed afterwards
2 Site switching	pass: for each active pilot site, every chart request on the four tabs carries that site's site_label, all HTTP 200 (25 per site; F5, added later, re-checked for one site)
3 Clearing	pass with the fallback (§4): "required" alone let the charts query every site
4 Unavailable L/h	pass: tooltip and M3 "not available", method "Not available: no runtime evidence"; S1 the same plus L/day; B3 every interval excluded with its reason; B11 the modelled range, labelled "not measured", nowhere else
5 Missing coordinates	pass (synthetic site, check 1): not plotted, in M4 and M5, its link opens its detail
6 Filter propagation	pass: the default "active" reaches M1, M3, M4, M5; a marker click re-queries M3 only, with a latitude/longitude box; the Viewing period reaches F1–F5, R1, R1T, R2, R4 and the bill table, and no Summary or Baseline & Evidence chart
7 Detail links	pass: from M3 for each active pilot site, and from M5
8 Colours	pass for the mapping: a throwaway fixture with one point per status shows the four colours and equal marker sizes. Not tested by fixture: that the database never labels an unapproved version "Approved baseline"
9 Basemap	pass: OSM tiles load, attribution visible, no CSP violation from the map

Changes forced by the tests and by two Codex inspection rounds of 24 Oct (F2 visits, R1T, B9 totals, coverage lanes; then F5, grey stock statuses, lane wording), all marked (P2) above. The second round's fixes were not inspected again. The grey colour for a non-ok stock interval is configured but not shown by the current data, which has no such interval.

• Handlebars charts (D0, S1, R3) became one-row tables.
• The Site filter uses "first value by default" with requiredFirst.
• Reading notes moved into a Markdown block per tab.
• The map tooltip uses short tooltip-only columns.
• The markers have no outline.

The marker palette is unchanged from §3. The dataviz palette check flags slate as reading grey, which is intended for "insufficient evidence", and amber at 2.99:1 contrast. The label is always also shown as text, in the legend, the tooltip and M3.

9. Fleet map results (local, 28 Oct 2026)

Local Superset 6.1.0 rebuilt with the iframe setting, behind a local Traefik that serves Superset and the petrolyst-platform read service on one origin (as on the server); the fuel-db of P2. Browser checks with Playwright in Chrome (petrolyst-platform/views/e2e/).

Spike, before building

• A Markdown iframe survives the sanitiser with the setting of §6.
• A target="_top" link inside it navigates the whole dashboard page.
• ?native_filters=…#TAB-… selects the site and opens that tab.
• Basemaps compared at zoom 11, 14 and 16 over the pilot area: OpenFreeMap Positron and OSM standard tiles show the same OpenStreetMap data; the owner chose Positron.

Bundle: 1 dashboard, 26 charts, 19 datasets; two builds are byte-identical; the import reports column drift 0. The two earlier dashboards and the charts M1, M3, M4 and M5 were deleted from the local Superset through its API. The live Superset never had them (P3 not done).

Check	Result
2 Site switching	pass: choosing a second site in the Site filter moves every chart request to it
3 Clearing	pass: after "Clear all" every chart request still carries exactly one site
4 Unavailable L/h	pass for the popup ("not available" and the method); S1, B3 and B11 are unchanged by this step and were not re-run
5 Missing coordinates	pass for the count: the map's key shows the 2 sites without an accepted location
7 Detail links	pass: for each of the 3 placed sites, hover, then "Site details", opens the Site details tab with Summary active, D0 shows the site, and every chart request carries exactly its site_label
8 Colours	the validity note beside an approved status and its L/h, and "(not approved)" for Provisional, pass as component tests on fixtures. Live, every site is "Insufficient evidence", so only slate was seen; the other three colours were checked by reading the code against §3, not on screen
9 Basemap	pass: tiles load, attribution visible; no CSP violation from the view. Superset's own script-src eval probe appears on every Superset page, as in P2 (§6), and nothing else. The test's watcher was checked with a deliberately disallowed image inside the view

Also passed: the popup opens on hover, stays while the pointer moves onto it, closes after the pointer leaves; a click pins it; Esc and a click on the map close it; with reduced motion it only fades and nothing pulses. The view's minimum size is 480 × 560 px (catalogue.json): there, and also at 480 × 360, every site's popup stays inside the map, and an approved estimate whose inputs changed is never in view without its warning, checked by scrolling the card. At 480 × 560 every site's L/h can be read. A single placed site sits clear of the key. Two sites at the same position can each be opened with the pointer. The states the scratch data lacks (approved with a changed input, one site, two at one spot) are made in the browser by changing the read service's answer; the database is unchanged.

Filters on top and the map search (owner, later on 28 Oct): the filter row was checked on screen first: the Fleet tab shows only "More filters", and Site details shows Site and Viewing period in the row. Browser checks:

• the map takes the page's width;
• the search finds a site by part of its name and by its code, and its popup's "Site details" opens exactly that site;
• a site inside a cluster is taken out of it;
• site switching and clearing (checks 2 and 3) still pass with the filters in the row.

ATOMA readers and the operator's logo (owner, 29 Oct): the plan was reviewed by Codex (approved after three rounds: deploy inputs, ownership and no-dataset paths, SQL in responses). Browser checks as the local user reader:

• every page leads to the dashboard;
• no title row and no menus; Settings shows only Logout;
• the whole fleet-map suite passes as the reader;
• reading needs nothing the role lacks (only the colours PUT above is refused);
• no chart-data response carries SQL, fresh, cached or as result_type=query (an admin's does);
• CSV and editing answer 403;
• two probe dashboards (Markdown only without roles, and one the reader owns) stay out of reach: page, API and permalink.

Also checked:

• the role script removes a permission added by hand;
• every new file changes the image tag;
• the patch's --verify fails on unpatched Superset and on a tampered line.

Found on the way: under many parallel requests the local proxy returned 502s. gunicorn closes idle connections after 2 s (--keep-alive 2) and Traefik reused them. The local proxy now drops idle connections after 1 s. The server has the same pairing (Traefik in front of gunicorn with the default keep-alive): open item.

Final inspection: two fresh Codex sessions reviewed the build.

• The first found four defects, all fixed and re-checked:

  • the popup could leave a small map;
  • two sites sharing a site_code could open each other's details;
  • every non-active pilot status was called "reference";
  • a failed database connection gave a 500 instead of the generic 503.

• The second confirmed those fixes and found three more:

  • in a short card the validity warning could scroll away from the L/h;
  • a single site was centred under the key;
  • sites at one position hid each other.

  All three are fixed and tested. Those last fixes, and the filter row and the map search, have not had an independent inspection.

Filters back on the left, the readers' Fleet tab, the navbar logo, section buttons (owner, 29 Oct): checked in the browser as reader and admin at 1400 × 1000, 1920 × 1080, 1440 × 760, 1280 × 600 and 1024 wide:

• a reader's Fleet tab has no filter column and no resize handle, and the map is as wide as the page and reaches 32 px above the window's bottom edge (no page scroll), at once rather than after Superset measures again; at 600 px high it keeps 560 px and the page scrolls;

• Site details shows the column collapsed (32 px, for readers and admins, also after the map's "Site details" link); expanded, it has the Site filter; switching back hides it again;

• an admin has the column on both tabs;

• the column no longer flashes up while the Fleet tab loads (one frame, about 20 ms, remains: the grid exists before its tabs do);

• after a switch to Site details its charts are too wide for one or two frames before Superset measures again; not changed;

• a reader's page links reader.css?v=<hash>, an admin's none;

• the navbar shows the wordmark at 24 px for readers, admins and the login page, white in dark mode;

• Site details' inner tabs are a row of section buttons (dashboard.css), lined up with the content, all four visible and switching, for readers and admins, light and dark; a vertical list was tried first and dropped: Superset sizes the charts for the full width, so they were cut off on the right;

• build_bundle.py stops when the orientation is not VERTICAL, when reader.css does not name the Fleet tab, when the map spans fewer than 12 columns, or when dashboard.css names an id that is not in the layout.

• (lenses) a reader at 1400 px: the switch centred in the navbar (Map | Insights), the map 735 px high in an 860 px window and 32 px above its bottom edge; scrolled by 30, 61 and 400 px the switch moves up by exactly as much and then stays out of view; at 820 px the tab row stays in the page; an admin keeps the tab row, named Map and Insights; the map's key says "Choose them in Insights".

• (AI teaser) a reader at 1400 px: the switch reads Map | Insights | AI PRO, still centred, 44 px high; a click on AI changes nothing; at 900 px the switch keeps Map | Insights.

These changes have not had an independent inspection (the owner skipped Codex).

Not run: check 1 (a synthetic fourth and fifth site), check 6 (the Viewing period's scope is unchanged), sign-in through Keycloak, the server's routing of /views, sign-in for the read service, thousands of sites, and dark mode.

10. The Petrolyst app's dashboards (PD-12, local trial, 29 Oct 2026)

The Petrolyst app (petrolyst-platform app/, PD-12) shows Superset dashboards inside its Insights lens, with guest passes from its app service. build_bundle.py builds them beside the unchanged ATOMA dashboard:

Slug	Content	Filters (set by the app; Superset's filter column is hidden)
atoma-overview	O1–O6: sites by pilot status and by baseline status, litres delivered, fuel cost by currency, electricity billed by currency and basis, litres delivered per month	Viewing period on O3–O6
atoma-site	the four §4 detail tabs as Superset's own tabs, the same rows and charts; no D0 (the app shows the site's header)	Site (all charts), Viewing period (as §4: fuel and runtime charts only)

• One site dashboard with tabs (owner, 29 Oct: "move it back inside the dashboard and make the tab as they were"): replaces the four one-tab dashboards atoma-site-summary, -fuel, -runtime, -baseline and the app's per-section pages. Switching tabs needs no reload. The app opens a site on its first tab; a new viewing period reloads the dashboard on the tab that was open (the app reads it from Superset and names it in the address, #TAB-fuel). Delete the four old dashboards by hand on an instance that has them.

• Overview rule (changes §4 rule 3 for the Overview only): only sums and counts of recorded values across sites (OVERVIEW_METRICS); per-site rates (L/h, L/day) are never averaged; money is grouped by currency_text, a missing currency is its own row, and no total crosses currencies. build_bundle.py checks both.

• They carry no CSS; dashboard.css and reader.css are checked against the ATOMA dashboard only.

• import_bundle.py --embedded-out FILE --embed-domain URL makes them embeddable from the app's origin and writes {slug: embedding id} for the app service; the reader role stays on the ATOMA dashboard only.

• Embedding is switched on in the local stack only (.local/fmdb-scratch, superset_config_local.py); production keeps it off until PD-12's open points are settled.

• Checked (local): a self-signed guest pass opens its own dashboard and nothing else (another embedded dashboard and ATOMA: 404; no pass or a wrong audience: 401); the embedded page answers only to the app's referrer (403 otherwise); chart-data responses to guests carry no SQL.