Data Dictionary

Every field of the sealed records Aquadrio keeps: the hour of a grid's electricity, the index day and the index month, a facility's hour, a building's hour, a named power plant's hour, and the correction. Each table names a field by its full path in the record (an array as name[], a field of an array's elements as name[].field), its type, its unit, what it states, and an example from the sample records:

• leave-behind/sample_hour_record.json, CAISO's hour ending 2026-06-29T23
• leave-behind/sample_index_record.json, MISO-Central's UTC day 2026-09-18
• leave-behind/sample_plant_record.json, Dearborn Industrial Generation's hour ending 2025-08-05T18
• measurement/agents/testdata/sample_facility_hour.json, a modeled campus on CAISO's sample hour
• measurement/agents/testdata/sample_building_hour.json, that campus's building
• measurement/agents/testdata/sample_correction_record.json, a correction of a plant's hour

Three record shapes appear in no sample above, and their examples come from other records the engine built: a building's priced line from measurement/agents/testdata/sample_building_hour_ford_field.json, an index month from the Index page's fixtures (web/tests/fixtures/upstream, built by scripts/index_fixture_series.py under the index check's test payload), and a plant's hour as Standard 0.9 seals it, with its valuation and its link to the grid hour, from Dearborn's hour ending 2025-08-05T18 as measurement/agents/test_valuation_block.py builds it on its fixture grid hour (the plant sample above was sealed before 0.9 and keeps its shape). The builders are measurement/agents/hour_record.py and measurement/agents/index_record.py. The seal's rule is docs/CERT_CANONICALIZATION.md. python scripts/dictionary_fields.py --check walks the six samples and names any path this document does not carry.

Conventions

Periods

An hour's period reads YYYY-MM-DDTHH and names the hour ending at that time, in UTC, as EIA-930 reports it: 2026-06-29T23 is the hour from 22:00 to 23:00 UTC. lag_hours runs from that close to sealed_at.

An index day's period reads YYYY-MM-DD and names a UTC day: the hours ending 01 through 23 of that date and the hour ending 00 of the next date. The day 2026-09-18 holds the periods 2026-09-18T01 through 2026-09-18T23 and 2026-09-19T00.

An index month's period reads YYYY-MM and names a UTC month: the UTC days of that month.

sealed_at reads UTC to the second, YYYY-MM-DDTHH:MM:SSZ, on every record.

Seals and Numbers

Every record carries canon_version, kind, its body under one key, and record_hash. The body sits under the key kind names (hour, facility_hour, building_hour, plant_hour, correction), apart from the two index kinds, whose body sits under index. record_hash is the SHA-256 of the record's canonical form with its top-level record_hash and signature left out: keys sorted, numbers at fixed places (six by default, four inside a generation mix), strings in Unicode NFC. A record_hash deeper in a record is a link to another sealed record, and a changed link breaks the seal of the record that holds it. The records carry no signature yet. node leave-behind/verify_record.mjs <file> recomputes any seal.

A figure prints to the places the record states it: gallons per MWh to two places, percents to the tenth, energy to four places on a site's record, dollars to the cent, and dollars per MWh to four places. A field the record states as null holds no value for that line, as a group with no ceiling holds no percent of prescription.

Labels

origin reads real on a record built from the grid's published data or from federal filings (every hour's record, a named site's records, and an index record built from real hours), and simulated on a modeled site's record. A record names what it models in plain words: an hour's hour.water.basis reads modeled from 2024 plant data; a site's load_basis reads modeled; a building's building_hour.compute.cooling_water.basis reads modeled; a plant's plant_hour.water.basis and plant_hour.modeled[] say how its water is modeled; a priced line's basis names the schedule's place (utility serving the place or nearest published rate).

Whole-Hour Rule

An hour is sealed only when its fuel rows are whole: it carries, with a value, every fuel code that held at least 5 percent of the grid's generation in any of the 48 hours before it. A half-loaded daily file renormalizes to a clean mix, so an hour short of a fuel is left unsealed until its rows arrive. The first record of an hour stands, and no sealed record is edited.

Short-Day Rule

An index day is sealed once it is older than yesterday in UTC and all 24 of its hours are sealed. A day still short of its 24 hours seals over the hours it has once it is more than seven days old: its index.hours_sealed counts them, its index.short reads true, and its level is taken over those hours alone. An index month is sealed once it has ended and each of its days holds a record or is past the seven days with no hours at all.

Basin Groups

A basin line's group is one of these ids, and its label is the name the records print. A group that carries a ceiling is held against it; a group with no ceiling prints "no grade" as its result. Each id names the basin group a plant's water is attributed to; the table lists the groups and the units that place them.

Fields Every Record Carries

Hour Record

One grid, one hour of electricity (kind hour). Example: leave-behind/sample_hour_record.json.

The Hours' Rows

The Hours carry each sealed hour as one row of hours.csv, each column's unit in its name, and hours.parquet holds the same columns typed. After each basin group's four columns stand the valuation's: the record's own sum, then each group's gallons within and over its ceiling and their dollars, read from the line's valuation block. A record sealed before Standard 0.9 carries no block, and a line with no ceiling carries none, so those cells are empty (null in Parquet). The index records in index.json carry the valuation of every hour in the span, including the hours sealed before Standard 0.9; a span's value is the sum of its index day records' dollars. The examples are the sample hour's row, its Lower Colorado line standing for <group>.

Index Day Record

One grid, one UTC day (kind index_day, Standard 0.8). A day's level is its gallons over its MWh, each hour's gallons taken as the hour's sealed gallons per MWh times its sealed demand in MWh, summed exactly at the records' own places. Example: leave-behind/sample_index_record.json.

Index Month Record

One grid, one UTC month (kind index_month). A month reads its day records' printed figures: its gallons and MWh are their sums, and each line's level, ceiling, percent, and result follow the day's rules over the month. It carries the day's fields under index apart from index.hours_expected and index.short, and adds the fields below. Example: MISO-Central's 2026-08 in the Index page's fixtures.

A month's index.record_id reads index_month_<jurisdiction>_<period>, as index_month_MISO-CENTRAL_2026-08.

Valuation Block

Aquadrio's valuation of a record's gallons, by the ratified method, while the valuation payload in force is ratified: a group's gallons within its ceiling valued at the base reference and its gallons above it at the scarcity step, each reference read per acre-foot on the UTC day the record's period belongs to and converted at the payload's gallons per acre-foot. An index record carries it from Standard 0.8: a day splits each hour's gallons against that hour's ceiling and sums the parts; a month sums its days' parts and dollars. From Standard 0.9 the hour, a facility's and a building's hour, and a plant's hour carry the same block (On Every Record below). The examples in this table are the sample index record's, valued under valuation-1.

On Every Record

From Standard 0.9 every record that states gallons by basin group carries its valuation, each graded line's block with the fields above and each record's sum of its own lines' dollars, inside the one record; nothing adds dollars across records. Each kind splits its gallons at the ceiling from the figures it already prints:

• The hour's record: a graded line's gallons within the ceiling are the lesser of its gallons per MWh and its ceiling, times the hour's MWh (hour.demand.gw times 1,000), and its gallons over the ceiling are its gallons per MWh above the ceiling times the hour's MWh, never below zero. This is the hour arithmetic the index day performs, so a day's hours' dollars sum to the day's within the rounding of 24 hours at a cent each.
• A facility's and a building's record: a graded line's gallons over the ceiling are its over_prescription_gallons, and the rest of its gallons are within it, over the block's energy_mwh. The cooling water of a building's compute block carries no valuation.
• A plant's hour: the plant's gallons over the ceiling are its gallons times the share of the grid hour's line for the plant's basin group that sits above the line's ceiling (its gallons per MWh less its ceiling, over its gallons per MWh), rounded half up to the tenth, and the rest are within it, over the plant's net MWh. The record names the grid hour it read (plant_hour.electricity_hour).

A line with no ceiling, an hour of no energy or no generation, and a record whose UTC day has no ratified payload in force carry valuation: null; the record seals all the same. A record sealed before 0.9 carries no block, and a reader values it from its own lines and the payload in force on its day. The price block beside it is the comparison line at the utility's rate.

On the hour's record (examples: the sample hour's Lower Colorado line and the hour's own sum):

On a facility's and a building's record, each over its own energy (examples: the sample building's groundwater and municipal line and its own sum; the facility of one building prints the same figures):

On a plant's hour (examples: Dearborn's hour ending 2025-08-05T18 on the fixture grid hour, valued at 2025's figures):

Facility Record

One site, one hour (kind facility_hour), led by the gridwater its buildings drew. Example: measurement/agents/testdata/sample_facility_hour.json.

A site whose place has a water rate on file carries a facility_hour.price block of the building's shape below, with one priced line for its gridwater.

Building Record

One building at a site, one hour (kind building_hour). Example: measurement/agents/testdata/sample_building_hour.json.

A building whose place has a water rate on file carries a price block, the comparison line beside its valuation, and so does its facility's record (facility_hour.price, with its gridwater line alone). Example: measurement/agents/testdata/sample_building_hour_ford_field.json, Ford Field's hour ending 2026-09-22T04, sealed before Standard 0.9.

A Building Record's Rows

A Building Record carries each of the building's hourly records as one row of records.csv, each column's unit in its name. Three columns carry the record's valuation, and the local rate's columns after them read its price block, the comparison line. summary.json states the span's value at the index as the sum of the rows' index_dollars. The examples are the sample building's hour as its row prints it.

Plant Record

One named power plant, one hour (kind plant_hour). Example: leave-behind/sample_plant_record.json, Fermi's hour ending 2026-10-24T06, sealed under Standard 0.9 from the NRC's daily level; the fields the EPA feed states (gross load, the net-to-gross ratios, the classes, the unit columns) take their examples from the Dearborn fixture hour, measurement/agents/testdata/sample_plant_hour_dearborn.json.

A place valued at the nearest published rate adds nearest_system, site_latitude, site_longitude, and distance_km to its price block, and a place with no schedule on file for the hour carries an empty lines list and a reason.

Correction Record

A new sealed record naming a record it corrects (kind correction). No sealed record is edited or deleted. Example: measurement/agents/testdata/sample_correction_record.json.

API Keys

The API's hours, index, and sites routes (/api/hours/, /api/index/, and /api/sites/ on aquadrio.com) answer a request with no key at the public tier and a request with a key at the standard tier. A key travels in the request header x-api-key.

• A key reads aq_ and then its payload and its signature, joined by a dot. It names the Stripe subscription that bought it, its tier, and its expiry, and it works while that subscription reads active in Stripe.
• A key that fails its signature, has expired, names a tier the API does not sell, or belongs to a subscription that no longer reads active answers 401.
• A request past the key's requests for the minute, or past its calls for the month, answers 429 with retry-after, the seconds to wait: to the end of the minute, or to the start of the next UTC month.
• The month's calls are counted in the web host's memory, so a deploy starts every count afresh.
• The web host reads each subscription's status from Stripe once an hour; in an hour when Stripe does not answer, a key passes on its signature.

Notice

The Notice mails a subscriber when what the subscriber watches crosses its prescription: one basin group on one grid, or one building on one grid. Each crossing is an event in its grid's list of events, which names the sealed index day record it reads.

• A basin group's event is recorded by the index pass when it seals a day record whose line for the group reads at or over. The pass records events for the days it seals and for no other day. The event's period is the day, and its figure is the line's pct_of_prescription to the tenth, as 221.9% of prescription.
• A building's event is taken by the daily send from its grid's sealed day records: the building's MWh a day times each graded group's gallons above its ceiling for one MWh of the day, summed over the days the grid has sealed in the month of its newest sealed day. A group's gallons above its ceiling for one MWh are the line's valuation.over_ceiling_gallons over the record's index.demand_mwh; a line with no ceiling adds nothing. A sum above zero is the building's event for the month, recorded once, and its figure is the sum to the tenth, as 4,800.0 gallons over the prescription this month. Its record_id names the newest sealed day the sum reaches.
• One event stands for each grid, kind, subject, and period: the first one recorded.
• The send runs once a day. It mails each event recorded in the last 48 hours that is not yet marked sent and reports a day no more than eight days old to every subscriber of the event's kind and subject whose subscription reads active in Stripe, then marks the event sent once every one of its mails has gone. An event whose mail failed is mailed again by the next day's send.
• Each mail names the subject and the grid, the day, the figure, and the sealed day record's address on the API, https://aquadrio.com/api/index/<day>?j=<grid>.
• Stripe holds the subscriptions. Every change of a subscription's status reaches the grid's list of subscribers through Stripe's webhook, and the daily send reads every subscription from Stripe before it mails.

Notice Events

Notice Subscribers