Rebuild the stand-in historian on CI Server item names

The three open Phase 5 findings were one defect: the stand-in was keyed on
CI Server POINT names (PS_STN_WET_WELL_LEVEL) when the historian is keyed on
CI Server ITEM names (AID.WRPS.STN.LEVEL). Modbus carries register numbers,
not names, so those two layers are free to differ - and do. Reconciling
against the register map, as planned, would only have proved the first three
namespaces agreed with each other.

Rebuilt from WRPS/05-scada/modbus, so item names, sample rates, retention and
timestamp semantics come from the machine rather than from a guess.

(a) Level tag does not join. PS_STN_WET_WELL_LEVEL becomes a tag row in its
    own right; LIT-101 is marked NOT HISTORISED - a field input on %IW0 that
    never reaches SCADA. It was the only seed row carrying two addresses.
    public.historian_items holds the item-to-tag mapping, generated by
    scripts/gen_historian_items.py and enforced non-empty at generate, at
    deploy and at verify.

(b) first_alarm/last_alarm returned UTC. Converted inside the measure, so it
    stays in Cube and happens once. Aggregate first, convert after - the other
    order picks the wrong row across a DST fall-back. Returned as a formatted
    string with a companion site_timezone measure. Storage being UTC is now
    confirmed, not assumed: all 49 points carry TIME_ZONE "Date+time GMT" and
    every history group CORRECT_DAYLIGHT=0. This answers Phase 4 task 4.

(c) High level alarm filed against the wrong equipment. Both sides were right
    about different things; the defect was asserting equipment twice. The
    history now carries no equipment column at all - faithful, since CI
    Server's section tree stops at the station and three pumps. Equipment is
    reached bit -> tag -> equipment via public.alarm_bits.

Alarms are derived, not stored: CI Server's ALARM_HISTORY group is empty
because every item imports with alarming off. Decomposing the alarm word needs
no configuration that does not exist.

Three things the SCADA config changed that were never filed as faults:
  - retention is 7 days, not 30. The advisory path was reporting a month of
    evidence drawn from a week of data
  - the analogue rate is 5 s, not 60. Two measures multiplied sample counts by
    a hardcoded 60 - a twelvefold overstatement that read as plausible
  - the deadband warning in process_values.yml was wrong and was steering
    people away from the correct measure

db/002_fixtures.sql now asserts its own counts at load and cross-checks the
alarm derivation against two independent signals. Those prove the pipeline,
not the plant.

db/README-standin-historian.md documents removal: the seam between generation
and contract, and twelve assumptions about imh that are NOT confirmed. Two of
them fail silently.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

BUILD-AI-CONTAINERS.md

@@ -487,62 +487,149 @@ Deployed early, deliberately: from here on, every experiment is traced.
 4. Confirm timestamp semantics: UTC or local, and DST behaviour.
 5. Set an application name on the connection so DBAs can see who is connecting.
 6. Test from a throwaway container on `lin001`, not from your laptop.
-7. **Settle the two deferred Phase 5 findings below.** Both were found by
+7. **Re-verify the three Phase 5 findings below, which are now fixed against
-   hand-verifying the measures against fixtures on `lin001`; both were left
+   the SCADA configuration.** All three came from one substitution, and it has
-   deliberately unfixed, because fixing either against fixture data would mean
+   been removed rather than patched.
-   guessing at what `imh` actually contains.
 
-**Deferred from Phase 5 — decide these when `imh` is connected**
+**Resolved 2026-08-31 — settled against the SCADA configuration, not against fixtures**
 
-**(a) The wet well level tag does not join, and fails as "no records found".**
+The three findings were symptoms of a single defect: **the stand-in historian
-The process value history is keyed `PS_STN_WET_WELL_LEVEL`, and
+was keyed on the wrong namespace.** Four names describe the same measurement
-`process_values.yml` hardcodes that name in `seconds_above_high_level_alarm`
+and only the last is what CI Server historises:
-and `seconds_above_lshh`. But `db/seed/tags.csv` carries `PS_STN_WET_WELL_LEVEL`
-only as an *alias* of `LIT-101`, so `public.tags` has no row with that
-`tag_id`. Every one of the 43,201 level rows — a third of the history, and the
-most important tag at this station — is unreachable from a tag-level lookup:
-resolve "wet well" → `WW-101` → `LIT-101` → filter history on `LIT-101` → zero
-rows → **"no records found"**, which the operator cannot tell apart from a
-genuine absence of data. Equipment-level filtering (`equipment_id = 'WW-101'`)
-works, so whether a question fails depends on which path the agent takes.
 
-The two flow tags use the opposite and self-consistent convention:
+| Layer | Example | Authoritative in |
-`PS_STN_INFLOW` and `PS_STN_TOTAL_DISCHARGE_FLOW` are rows in their own right,
+|---|---|---|
-and the instruments `FIT-201`/`FIT-301` are marked NOT HISTORISED. Applying
+| Instrument tag | `LIT-101` | `WRPS/01-design-doc` |
-that convention to level — a `PS_STN_WET_WELL_LEVEL` row, `LIT-101` marked NOT
+| PLC symbol + address | `%QW0` | `WRPS/04-plc/register-map.csv` |
-HISTORISED — is the likely fix, **but do not make it until `imh` says what CI
+| CI Server **point** | `PS_STN_WET_WELL_LEVEL` | `WRPS/05-scada/modbus/scada-points.csv` |
-Server actually historises the point as.** `db/seed/tags.csv` is derived from
+| CI Server **item** | `AID.WRPS.STN.LEVEL` | `WRPS/05-scada/modbus/wrps_item_df.qli` |
-`WRPS/04-plc/register-map.csv` and `WRPS/05-scada/modbus/scada-points.csv`;
-reconcile against those and against the real historian, then change the seed,
-the model's hardcoded tag names, and `db/002_fixtures.sql` together.
-Eval case `H26` fails until this is settled.
 
-**(b) `alarms.first_alarm` / `last_alarm` return UTC, not `SITE_TIMEZONE`.**
+`db/002_fixtures.sql` was keyed on the third. The historian is keyed on the
-Cube converts time *dimensions* to the query timezone, but these are `min`/`max`
+fourth. Everything else followed from that.
-measures over a timestamp and are returned unconverted. On the Sydney day
-bucket `2026-08-01` the measure returns `2026-07-31T20:00:35` — the correct
-instant, labelled ten hours and one calendar day wrong, inside a row whose own
-bucket label is in site time. An answer that says "the first alarm was at 20:00
-on 31 July" is wrong twice over.
 
-This breaks "convert to `SITE_TIMEZONE` exactly once, in Cube" and the fix must
+Modbus TCP carries register *numbers*, not names — which is why the point layer
-stay in Cube — the API must not do timezone arithmetic to compensate. Two
+and the item layer can differ at all, and why nothing in this repository had
-options, and the choice depends on what `imh` returns: convert inside the
+ever recorded the item names. There are 49 items in six sections (`STN`,
-measure, which means getting `SITE_TIMEZONE` into the model rather than
+`PU301/302/303`, `SP`, `SIM`), and the section tree **stops at the station and
-hardcoding `Australia/Sydney` in it; or return the value as a timestamp that
+the three pumps**: CI Server has no wet well, no weir, no manifold and no
-carries its offset, so nothing downstream has to assume. Decide once the real
+switchboard.
-timestamp semantics from task 4 above are known, since a historian storing
+
-local time changes the answer.
+**(a) The wet well level tag does not join — FIXED.**
+`AID.WRPS.STN.LEVEL` is a real item in the `WRPS_ONE_SEC` group. The correct
+reading was the one already suspected: `PS_STN_WET_WELL_LEVEL` becomes a tag row
+in its own right, and `LIT-101` is marked NOT HISTORISED — it is a field input
+on `%IW0` and never reaches SCADA. `LIT-101` was the only row in the seed
+carrying two addresses (`%QW0,%IW0`), which is the instrument and the published
+value merged into one row; the two flow tags had the convention right all along.
+
+The mapping now lives in `public.historian_items`, generated from the SCADA
+configuration by `scripts/gen_historian_items.py`. **It is enforced in three
+places**, because a silent zero-row join is what made this expensive: the
+generator refuses to write the seed, `scripts/deploy.sh` refuses to load it, and
+`scripts/verify.sh` checks the running database. A historised item with neither
+a tag nor a written reason for having none is an error, not a "no records found".
+
+**(b) `first_alarm` / `last_alarm` returned UTC — FIXED.**
+The conversion now happens inside the measure, which keeps it inside Cube and
+exactly once. Two details matter and neither is obvious:
+
+- The aggregate is taken **first** and converted after — `MIN(x) AT TIME ZONE z`,
+  not `MIN(x AT TIME ZONE z)`. The second form takes the minimum of local clock
+  readings and picks the wrong row across a daylight-saving fall-back, where one
+  local hour occurs twice.
+- The result is a **formatted string with a companion `site_timezone` measure**,
+  not a bare timestamp. A timestamp with no offset is what made the original
+  defect invisible.
+
+The zone name is a literal in `alarms.yml` rather than `{{ env_var(...) }}`,
+because a model that fails to compile takes every query down and Jinja support
+could not be tested against the pinned Cube v1.1.7. `verify.sh` asserts the
+literal matches `SITE_TIMEZONE` in `api.env` so the two cannot drift silently.
+
+**Task 4 above — "confirm timestamp semantics" — is answered.** All 49 Modbus
+points carry `TIME_ZONE "Date+time GMT"` and every WRPS history group carries
+`CORRECT_DAYLIGHT = 0`. Storage is UTC. Read from the configuration, not
+assumed, and the one Phase 4 task that turned out not to need the `imh` owner.
+
+**(c) The high level alarm was registered against the wrong equipment — FIXED,
+structurally.** Both sides were right about different things: the tag seed said
+`STN-001` because CI Server's section for that item is `STN`; the fixtures said
+`WW-101` because the alarm is a wet well level condition. The defect was that
+**equipment was asserted in two places at once.**
+
+It is now asserted in exactly one: `tags.equipment_id`. **The history carries no
+equipment column at all**, which is also faithful — CI Server has no wet well to
+put there. Equipment is reached `bit → tag → equipment` through
+`public.alarm_bits` and `public.historian_items`. `verify.sh` fails if an
+`equipment_id` column reappears anywhere in the history schema.
+
+**Alarms are now derived, not stored.** CI Server's built-in `ALARM_HISTORY`
+group exists on the server and is **empty**: every WRPS item imports with
+alarming off and limits at 0, which `05-scada/modbus/README.md` records as
+outstanding engineering judgement. Every alarm at this station is a bit of the
+PLC alarm word, so `fixture.alarm_history` decomposes `AID.WRPS.STN.ALARM_WORD`
+into bit transitions. That needs no SCADA configuration that does not exist, and
+it is the same derivation that will run against `imh`.
+
+**Three things the SCADA configuration changed that were not findings**
+
+1. **Retention is seven days**, not thirty. Every WRPS history group is
+   `LIFE_TIME "1 weeks"`. The fixtures now match, so a question about last month
+   fails here exactly as it would on `imh`. `metrics.HISTORY_RETENTION_DAYS` and
+   `MetricResult.outside_retention` carry the distinction between "the historian
+   does not go back that far" and "nothing happened" — different answers, and
+   only one of them true. The advisory path was asking for 30 days and reporting
+   a month's evidence drawn from a week's data; it now asks for seven. See
+   `REQUESTS.md` for the request to extend retention.
+
+2. **Samples are regular, not deadband-compressed.** `DATA_COMP = 0` on every
+   group, `STORE_DEADBAND = 0` on every item, `COL_STOR_TYPE "Scan/Time"`. The
+   prominent warning in `process_values.yml` that real history would be
+   irregular, and that a plain average would therefore be biased, was wrong. It
+   is corrected, and it holds only for `WRPS_EVENT`.
+
+3. **The analogue rate is 5 seconds, not 60.** Two Cube measures turned sample
+   counts into durations by multiplying by a hardcoded 60. Against a 5-second
+   group that overstates by **twelve times**, and it would have read as entirely
+   plausible. They now sum the item's declared `scan_interval_seconds`.
+
+**Still to confirm with the `imh` owner — the shape is now right, the names are ours**
+
+- The SQL Server table and column names `imh` exposes these items as. One
+  item-keyed history table is the correct shape; `fixture.item_history` is a
+  guess at what it is called.
+- Whether `imh` exposes CI Server's `ALARM_HISTORY` group at all, and whether
+  anyone intends to configure item alarm limits. If they do, only
+  `fixture.alarm_history` changes — no Cube model does.
+- **A conflict worth raising:** the repository's `his_group.qli` and the live
+  server's `export_his_group.qli` disagree. The file says `WRPS_ONE_SEC` is a
+  1-second group paired with a 60-second `WRPS_ONE_MIN`; the server runs
+  `WRPS_ONE_SEC` at 5 seconds with a 30-second `WRPS_THIRTY_SEC`. The live
+  server was taken as authoritative here. Someone should decide which is
+  intended and re-run the WRPS generators — right now the repository does not
+  describe the running system.
+- **A name collision in `scada-points.csv`:** `PS_STN_HIGH_LEVEL_ALARM` names
+  both the coil 10 status bit and the holding register 1032 setpoint. The point
+  name is not unique; the item layer is the first place the two are
+  distinguishable (`STN.HIGH_LEVEL` versus `SP.HIGH_ALARM`). Harmless now that
+  the item is the key, but it will confuse anyone reading the point list.
 
 **Gate**
 - [ ] A `SELECT` from a container on `lin001` returns rows
 - [ ] An `INSERT` attempt fails on permissions — verified, not assumed
 - [ ] Row counts for a known window are sane
 - [ ] Timestamp semantics documented in section 10
-- [ ] Finding (a) settled against the register map: a level question returns
+- [ ] Findings (a), (b) and (c) re-verified against `imh` rather than the
-      rows, and "no records found" means no records
+      stand-in. They are fixed against the SCADA configuration and asserted at
-- [ ] Finding (b) settled: `first_alarm` in a site-time bucket reads in site
+      fixture load; that proves the pipeline, not the plant
-      time, and the conversion still happens exactly once, in Cube
+- [ ] `public.historian_items` regenerated from the WRPS repository, and every
+      historised item still resolving to a tag or a written reason
+- [ ] The gap between consecutive `AID.WRPS.STN.LEVEL` samples on real `imh`
+      data is the declared 5 seconds. If it is not, every duration measure in
+      `process_values.yml` is wrong and must compute gaps with a `LEAD` window
+- [ ] "How many wet well high level alarms in the last 7 days" returns a count
+      **an engineer has verified against `imh`** — the stand-in says 14, which
+      is a fact about the fixtures and nothing else
 
 ---
 

CLAUDE.md

@@ -50,6 +50,9 @@ the right number by hand, prove retrieval finds the right procedure by hand, *th
 
 - Prefer additive changes. Snapshot config before editing.
 - **Do not invent schema.** `imh` is pending — inspect it, or ask. Fixtures are marked as fixtures.
+  Before connecting it, work through `db/README-standin-historian.md` — the stand-in's shape is
+  reasoned from the SCADA config, but **every SQL Server detail in it is a guess**, and two of the
+  twelve listed assumptions fail silently rather than erroring.
 - Store UTC. Convert to `SITE_TIMEZONE` exactly once, in Cube. Never do timezone maths in a prompt.
 - Fix failures in the classifier, Cube or ingestion — **not by adding instructions to the prompt.**
 - **A document becomes citable only after a human confirms its number, revision and effective date** —
@@ -65,5 +68,27 @@ Waterloo Road Pump Station: a three-pump wastewater station. Wet well `WW-101` (
 120 m³/m), duty/assist/assist pumps `PU-301/302/303` on a common VSD speed reference, discharging
 through manifold `MAN-301` against 22 m static lift. Spill weir at 6000 mm, `LSHH-102` at 5500 mm.
 Control runs on `openplc-runtime`; Yokogawa CI Server on `cicore1` polls it over Modbus TCP and
-historises the result. Source of truth for tags: `db/seed/tags.csv`, derived from
+historises the result.
-`WRPS/04-plc/register-map.csv` and `WRPS/05-scada/modbus/scada-points.csv`.
+
+**Four namespaces name the same measurement. Know which one you are holding.**
+
+| Layer | Example | Source of truth |
+|---|---|---|
+| Instrument tag | `LIT-101` | `WRPS/01-design-doc` |
+| PLC symbol + address | `%QW0` | `WRPS/04-plc/register-map.csv` |
+| CI Server point | `PS_STN_WET_WELL_LEVEL` | `WRPS/05-scada/modbus/scada-points.csv` |
+| **CI Server item** | **`AID.WRPS.STN.LEVEL`** | `WRPS/05-scada/modbus/wrps_item_df.qli` |
+
+**The historian is keyed on the item, and only the item.** Modbus carries register numbers,
+not names, so the point layer and the item layer are free to differ — and they do. Keying
+history on a point name is what produced all three Phase 5 findings. `db/seed/tags.csv` owns
+plant facts; `db/seed/historian_items.csv` owns the item-to-tag mapping and is **generated**
+by `scripts/gen_historian_items.py` — never hand-edited.
+
+- **Equipment is asserted in exactly one place: `tags.equipment_id`.** Nothing in the
+  history carries an equipment column. CI Server's section tree stops at the station and the
+  three pumps; it has no wet well, weir, manifold or switchboard.
+- **The historian retains seven days.** Zero rows outside that window means "the historian
+  does not go back that far", never "nothing happened". `metrics.HISTORY_RETENTION_DAYS`.
+- **Never hardcode a sample interval.** Read `scan_interval_seconds` from the item. The
+  analogue groups run at 5 s and 30 s; a measure that assumed 60 s was wrong by twelvefold.

README.md

@@ -107,6 +107,7 @@ equipment/tag reference data.
 |---|---|---|---|
 | `pg-ai` | `pgvector/pgvector:pg16` | `ai-internal` only | none |
 | `cube` | `cubejs/cube` (pinned) | `ai-internal` + `proxy` | `cube.yokogawa.tech` |
+| `cubestore` | `cubejs/cubestore` (pinned) | `ai-internal` only | none |
 | `ai-api` | Python 3.12 + FastAPI | `ai-internal` + `proxy` | `api.yokogawa.tech` |
 | `ai-web` | Vite build → `nginx:alpine` | `proxy` | `ai.yokogawa.tech` |
 | `ai-ingest` | Python 3.12, on demand | `ai-internal` | none |
@@ -212,16 +213,29 @@ semantics, and an NSG rule allowing `lin001` → `imh` on 1433 only. Then update
 Until then everything runs on fixtures, and every answer carries a fixture
 banner all the way to the operator's screen.
 
-**Two Phase 5 findings are deferred to this phase**, both found by
+**The three Phase 5 findings are fixed** (2026-08-31), against the SCADA
-hand-verifying the Cube measures against fixtures and both left unfixed
+configuration rather than against the fixtures. All three came from one
-because fixing them against fixture data means guessing at `imh`. The wet well
+substitution: the stand-in historian was keyed on CI Server **point** names
-level tag does not join — history is keyed `PS_STN_WET_WELL_LEVEL`, which
+(`PS_STN_WET_WELL_LEVEL`) when the historian is keyed on CI Server **item**
-`tags.csv` carries only as an alias of `LIT-101` — so a level question can fail
+names (`AID.WRPS.STN.LEVEL`) — two layers apart, not one. Nothing is aliased
-as **"no records found"**, which reads exactly like a genuine absence of data.
+across that gap now: `public.historian_items` holds the mapping, generated from
-And `alarms.first_alarm`/`last_alarm` come back in UTC inside rows whose bucket
+`WRPS/05-scada/modbus` by [`scripts/gen_historian_items.py`](scripts/gen_historian_items.py),
-labels are in site time. Full detail, and what has to be true to close them, in
+and an item that resolves to neither a tag nor a written reason is a build
-[`BUILD-AI-CONTAINERS.md`](BUILD-AI-CONTAINERS.md) Phase 4, "Deferred from
+error rather than a silent "no records found".
-Phase 5"; eval cases `H26` and `H27` fail until they are settled.
+
+Two consequences worth knowing before you read a number off this system:
+
+- **The historian keeps seven days.** Every WRPS history group is
+  `LIFE_TIME "1 weeks"`, and the fixtures now match, so a question about last
+  month fails here exactly as it would against `imh`. Zero rows outside
+  retention is reported as a retention limit, never as "nothing happened".
+- **Equipment is asserted in exactly one place**, `tags.equipment_id`. The
+  history carries no equipment column, because CI Server's section tree stops
+  at the station and the three pumps and has no wet well to put there.
+
+Full detail in [`BUILD-AI-CONTAINERS.md`](BUILD-AI-CONTAINERS.md) Phase 4,
+"Resolved 2026-08-31". Eval cases `H26`, `H27` and `H31` cover them, and `H29`
+covers the retention limit.
 
 ### 6. Phases 5–7 — Cube, API, UI
 

REQUESTS.md

@@ -1,28 +1,52 @@
 # Outstanding requests — WRPS Plant Assistant
 
-Two things are still needed from other people, of the three originally raised. Nothing else
+**One thing is still needed from other people, of the three originally raised.** Nothing else
-is blocking: as at **21 August 2026** the assistant runs end to end on `lin001` — the question box, name
+is blocking: as at **28 August 2026** the assistant runs end to end on `lin001` with a real
-resolution, the data translator, document search, all four answer lanes, the rulebook, the
+model — the question box, name resolution, the data translator, document search, all four
-working panel and the logbook are all live and were exercised by hand on the host.
+answer lanes, the rulebook, the working panel, the logbook and the document library are all
+live and were exercised by hand on the host.
 
-**Item 2 was delivered on 27 August 2026 and is closed** — it is kept below as a record of
+**Items 1 and 2 are both delivered and closed** — they are kept below as a record of what was
-what was asked for and what arrived. What is still missing is the AI model itself and real
+asked for and what arrived. What is still missing is real plant data. That is the request
-plant data. Both depend on someone outside this project and neither can be hurried at the
+furthest outside this project's control, and it cannot be hurried at the end.
-end: the model account is the longest pole and also gates the OT/safety review, and the
-historian is the one furthest outside our control.
 
-Contact for item 1: **Daniel Watson** (daniel.watson@yokogawa.com).
 Item 3 needs the owner of the `imh` historian, who is not yet identified.
+Contact for items 1 and 2, both closed: **Daniel Watson** (daniel.watson@yokogawa.com).
 
 | # | Request | Needed for | Blocks |
 |---|---|---|---|
-| 1 | Azure OpenAI account, 3 deployments | The two AI steps — classifying the question, wording the answer | Phases 6, 8; the safety review |
+| 1 | ~~Azure OpenAI account, 3 deployments~~ | The two AI steps — classifying the question, wording the answer | **Delivered 27 Aug 2026 — closed** |
 | 2 | ~~Three public DNS records + DC pinpoint records~~ | Reaching the assistant by name from a control-room PC | **Delivered 27 Aug 2026 — closed** |
 | 3 | Read-only login to the `imh` historian | Real plant figures instead of stand-ins | Phases 4, 5; every data answer |
 
 ---
 
-## 1. Azure OpenAI account
+## 1. Azure OpenAI account — DELIVERED
+
+**Closed 27 August 2026.** The resource is live at `yau-dem-oai.openai.azure.com`, API version
+`2024-10-21`, and `lin001` reaches it outbound over HTTPS. `NO_LLM_STUB=false` on the host:
+both AI steps — classifying the question and wording the answer — run against the real model,
+and the documents were indexed with real embeddings the same day. Switching it on surfaced
+eight failures the stand-in had hidden; all eight are fixed and pinned by cases in
+`eval/testset.jsonl`, which grew from 67 to 75.
+
+**Two things are worth recording, and the second needs a decision.**
+
+- **The deployments as built are not the deployments as requested.** The host runs
+  `CHAT_DEPLOYMENT=gpt-4o` and `CHEAP_DEPLOYMENT=gpt-4o` — the *same model on both lanes* —
+  with `text-embedding-3-small` for embeddings as asked. The request was for a
+  GPT-5-mini-class model on the cheap lane specifically so that classification, entity
+  extraction and tool selection would not bill at flagship rates.
+- **The cost estimate below therefore no longer holds.** ≈US$35/month at 3,000 questions was
+  computed on three calls per question with two of them on a cheap model. With both chat lanes
+  on `gpt-4o`, the same traffic bills materially higher. Either deploy a cheap-lane model and
+  repoint `CHEAP_DEPLOYMENT`, or re-cost the budget ask before the demo period. **The US$50
+  monthly budget alert should be confirmed as actually set**, since it is now the thing that
+  catches this rather than the estimate.
+
+The original request follows, unchanged.
+
+---
 
 ### Action
 
@@ -66,6 +90,10 @@ The assistant runs end to end today except for the two steps that need a model:
 each question, and wording the answer. Without the account those two cannot be built,
 tested or reviewed, and the 67-question acceptance test cannot be run at all.
 
+*(As delivered: both steps now run. The acceptance test is runnable and has grown to 75
+cases, but has not yet been run as a formal Phase 8 gate — that is a task inside this
+project, not a request of anybody.)*
+
 ---
 
 ## 2. Three public DNS records, plus pinpoint records on the DC — DELIVERED
@@ -154,35 +182,56 @@ when a person outside this project opens a browser. It also depends on two diffe
 ### What it is for
 
 Every figure the assistant produces today is a stand-in. Cube — the data translator — is
-running and answering questions against fixture tables (145 alarm records, 309 pump
+running and answering questions against generated tables (32 alarm activations, 72 pump-downs,
-operations, about 130,000 level readings), and every answer built on one carries a warning
+about 685,000 analogue samples over seven days), and every answer built on one carries a
-label all the way to the operator's screen. The definitions Cube uses are the real ones and
+warning label all the way to the operator's screen. The definitions Cube uses are the real
-will not change when the historian arrives; only the source will.
+ones and will not change when the historian arrives; only the source will.
 
-### Why the schema conversation cannot be deferred
+**The stand-in is now keyed the same way the historian is.** It was rebuilt on 2026-08-31
+against `WRPS/05-scada/modbus` — CI Server item names, the real historisation groups, the
+real sample rates and the real retention. Three defects that had been left open closed as a
+result, and the schema conversation below is correspondingly narrower than it was: the
+*shape* is now right, and what remains is names.
 
-Two defects found while hand-verifying Cube's measures were **deliberately left unfixed**,
+### Why the schema conversation is still needed
-because fixing either against fixture data would mean guessing at what `imh` actually
-contains:
 
-- **The wet well level tag does not join.** History is keyed `PS_STN_WET_WELL_LEVEL`, but
+- **What `imh` calls these tables and columns.** One item-keyed history table is the right
-  the tag seed carries that only as an alias of `LIT-101`. A tag-level lookup therefore
+  shape; `fixture.item_history` is our guess at its name. Everything else — alarms,
-  returns zero rows for a third of the history — and reports it as **"no records found"**,
+  pump-down operations — is derived from it, so this is the only naming question that
-  which an operator cannot distinguish from a genuine absence of data. Equipment-level
+  actually blocks anything.
-  lookup works, so whether a question fails depends on which path it takes. The likely fix
+- **Whether `imh` exposes CI Server's `ALARM_HISTORY` group at all.** It exists on the
-  is known, but must not be applied until `imh` says what CI Server actually historises the
+  server and is empty: every WRPS item was imported with alarming off and limits at 0, which
-  point as.
+  `05-scada/modbus/README.md` records as engineering judgement nobody has made yet. Alarms
-- **First/last alarm times return UTC, not site time.** Inside a row labelled in Sydney
+  are derived from the PLC alarm word instead, which needs no configuration that does not
-  time, the measure returns an instant labelled ten hours and a calendar day wrong. Which
+  exist. If someone does configure item alarm limits, we would rather use them.
-  of the two available fixes is correct depends on what `imh` returns.
+- **An engineer must confirm Cube's first real numbers by hand** before anybody trusts one.
+  The stand-in asserts its own counts at load and cross-checks them two ways, but that
+  proves the pipeline, not the plant. This is a person's time, not just a login.
 
-Both fail eval cases (`H26`, `H27`) until settled.
+### A separate request: extend the historian's retention
+
+**Every WRPS history group is `LIFE_TIME "1 weeks"`.** The assistant therefore cannot answer
+a question about anything older than seven days — not badly, but at all. "How did last month
+compare with this one", "when did we last spill", "how many trips this quarter" are all
+outside reach, and they are among the questions an operator is most likely to ask.
+
+The system now reports this honestly: a window reaching past retention is answered as *"the
+historian does not go back that far"*, never as *"no records found"*, because those are
+different answers and only one is true. But honest is not the same as useful.
+
+**Asked for:** raise `LIFE_TIME` on `WRPS_ONE_SEC`, `WRPS_THIRTY_SEC` and `WRPS_EVENT` to at
+least 90 days, or confirm that seven days is a deliberate constraint we should design around
+and stop asking. Storage is the trade: the 5-second group is five items, which is roughly
+120,000 samples per item per week.
+
+**Also worth a decision while someone is in there:** the repository's `his_group.qli` and the
+live server's `export_his_group.qli` disagree about sample rates — the file says 1 s and
+60 s, the server runs 5 s and 30 s. The live server was taken as authoritative. The
+repository does not currently describe the running system, and one of the two should change.
 
 ### What it unblocks
 
-Phase 4 and the remainder of Phase 5. Note that an engineer must independently confirm
+Phase 4 and the remainder of Phase 5.
-Cube's first real numbers by hand before anybody trusts one — that is a person's time, not
-just a login.
 
 ---
 

api/agent.py

@@ -230,8 +230,15 @@ def gather_procedural(state: State) -> State:
 def gather_advisory(state: State) -> State:
     """Both paths: what was done (Cube) and what is allowed (documents)."""
     trace = state.get("trace")
-    result = metrics.run(metrics.pump_down_evidence(days=30), trace=trace)
+    # Was 30 days. The historian keeps seven — every WRPS history group is
-    _, _, window_description = metrics.rolling_window(30)
+    # LIFE_TIME "1 weeks" — so a 30-day window returned the same evidence a
+    # 7-day one does while telling the reader it covered a month. The sample
+    # size behind an advisory answer is part of the evidence, and overstating
+    # it by four times is the kind of error nobody would catch downstream.
+    result = metrics.run(
+        metrics.pump_down_evidence(days=metrics.HISTORY_RETENTION_DAYS), trace=trace
+    )
+    _, _, window_description = metrics.rolling_window(metrics.HISTORY_RETENTION_DAYS)
     if stub.enabled():
         chunks = retrieval.rerank(
             retrieval.lexical_search(state["question"], top_k=8, doc_type="design"),

api/tools/metrics.py

@@ -32,6 +32,20 @@ from guardrails import check_cube_query
 log = logging.getLogger("tools.metrics")
 
 
+# How far back the historian goes. Every WRPS history group on CI Server
+# carries LIFE_TIME "1 weeks" (05-scada/modbus/export_his_group.qli), so there
+# is nothing older than this to find — on imh or on the fixtures standing in
+# for it.
+#
+# THIS IS NOT A TUNING KNOB. A question reaching past it returns zero rows, and
+# zero rows outside retention means "the historian does not go back that far",
+# NOT "nothing happened". Those are different answers and only one of them is
+# true. `outside_retention` on the result below is what lets the answer say so;
+# reporting the second when the first is the case would be an answer outside
+# the evidence, which is the third line this system does not cross.
+HISTORY_RETENTION_DAYS = 7
+
+
 @dataclass
 class MetricResult:
     query: dict[str, Any]
@@ -40,6 +54,9 @@ class MetricResult:
     used_fixture_data: bool
     time_window: dict[str, str]
     annotation: dict[str, Any]
+    # True when the window asked for reaches past what the historian keeps.
+    # An empty result with this set must be reported as a retention limit.
+    outside_retention: bool = False
 
 
 def _token() -> str:
@@ -59,11 +76,18 @@ def rolling_window(days: int) -> tuple[str, str, str]:
     end = datetime.now(timezone.utc).astimezone(tz)
     start = end - timedelta(days=days)
     fmt = "%Y-%m-%dT%H:%M:%S"
-    return (
+    note = f"rolling {days} days to {end.strftime('%Y-%m-%d %H:%M')} {end.tzname()}"
-        start.strftime(fmt),
+    if days > HISTORY_RETENTION_DAYS:
-        end.strftime(fmt),
+        # Deliberately NOT clamped. A silently shortened window would answer a
-        f"rolling {days} days to {end.strftime('%Y-%m-%d %H:%M')} {end.tzname()}",
+        # question nobody asked and read as though it had answered the one they
+        # did. Let it run, return nothing, and let outside_retention say why.
+        note += (
+            f" - BEYOND RETENTION: the historian keeps "
+            f"{HISTORY_RETENTION_DAYS} days, so part of this window does not exist"
         )
+        log.warning("window of %d days exceeds the %d day historian retention",
+                    days, HISTORY_RETENTION_DAYS)
+    return start.strftime(fmt), end.strftime(fmt), note
 
 
 def run(query: dict[str, Any], *, trace=None) -> MetricResult:
@@ -84,6 +108,21 @@ def run(query: dict[str, Any], *, trace=None) -> MetricResult:
     rows = body.get("data", [])
 
     window = capped["timeDimensions"][0]["dateRange"]
+
+    # Did the window reach past what the historian holds? Compared against the
+    # window actually run, not the days argument, so a caller passing explicit
+    # dates is checked the same way as one asking for a rolling window.
+    outside_retention = False
+    if isinstance(window, list) and window:
+        try:
+            asked_from = datetime.fromisoformat(window[0])
+            if asked_from.tzinfo is None:
+                asked_from = asked_from.replace(tzinfo=ZoneInfo(cfg.site_timezone))
+            horizon = datetime.now(timezone.utc) - timedelta(days=HISTORY_RETENTION_DAYS)
+            outside_retention = asked_from < horizon
+        except ValueError:
+            log.warning("could not parse window start %r for a retention check", window[0])
+
     result = MetricResult(
         query=capped,
         rows=rows,
@@ -98,8 +137,10 @@ def run(query: dict[str, Any], *, trace=None) -> MetricResult:
             # like it to have run in. check_cube_query pins it onto the query
             # itself, so these two can no longer disagree.
             "timezone": capped.get("timezone", cfg.site_timezone),
+            "retention_days": str(HISTORY_RETENTION_DAYS),
         },
         annotation=body.get("annotation", {}),
+        outside_retention=outside_retention,
     )
 
     if trace is not None:
@@ -188,7 +229,7 @@ def alarm_detail(*, equipment_id: str | None = None, days: int = 7) -> dict[str,
     }
 
 
-def pump_down_evidence(*, days: int = 30) -> dict[str, Any]:
+def pump_down_evidence(*, days: int = HISTORY_RETENTION_DAYS) -> dict[str, Any]:
     """The evidence behind an advisory question about discharge rate.
 
     Rates actually used, how high the well got, how often it alarmed, how often
@@ -235,7 +276,11 @@ def level_profile(*, days: int = 7, granularity: str = "hour") -> dict[str, Any]
             }
         ],
         "filters": [
-            {"member": "process_values.tag_id", "operator": "equals",
+            # The CI Server ITEM name, which is what the historian is keyed on.
-             "values": ["PS_STN_WET_WELL_LEVEL"]}
+            # This used to be PS_STN_WET_WELL_LEVEL - a SCADA POINT name, one
+            # layer up - and it matched nothing on a tag-level lookup. See
+            # cube/model/process_values.yml for the four namespaces involved.
+            {"member": "process_values.item_name", "operator": "equals",
+             "values": ["AID.WRPS.STN.LEVEL"]}
         ],
     }

cube/model/alarms.yml

@@ -1,41 +1,74 @@
 # =============================================================================
 # alarms.yml — alarm and event history.
 #
-# SOURCE: fixture.alarm_history while USE_FIXTURES=true. When imh is live this
+# REMOVING THE STAND-IN: db/README-standin-historian.md. The view below is
-# becomes the agreed imh alarm table and the column names below change with it.
+# CONTRACT - repoint it at imh, do not edit this file to absorb a difference.
-# Nothing else in this file should need to change; that is the point of it.
+#
+# SOURCE: fixture.alarm_history while USE_FIXTURES=true. That is a VIEW, not a
+# table, and it is derived rather than stored — see below. When imh is live the
+# view is repointed at imh and nothing in this file changes. That is the point
+# of it.
+#
+# WHERE ALARMS COME FROM, AND WHY IT IS A DERIVATION
+# --------------------------------------------------
+# Every alarm at this station is a bit of the PLC alarm word, historised as the
+# CI Server item AID.WRPS.STN.ALARM_WORD. The bit map is reference data in
+# public.alarm_bits, and it is what carries an alarm to the equipment it
+# belongs to: a bitmask packs several units' alarms into one item, so the item
+# alone cannot say which pump a seal leak is about, but the bit can.
+#
+# CI Server's own ALARM_HISTORY group is configured on the server and is EMPTY:
+# every WRPS item imports with alarming off and limits at 0, which
+# 05-scada/modbus/README.md records as deliberate and still outstanding
+# engineering judgement. Deriving from the alarm word needs no configuration
+# that does not exist. If alarm limits are later configured on the items, this
+# file does not change either — fixture.alarm_history does.
 #
 # THREE DEFINITIONS THAT DECIDE WHETHER THE ANSWERS ARE RIGHT. They are here in
 # comments because the person checking the number needs to read them, and they
 # are not obvious from the measure names.
 #
 # 1. AN ALARM IS A TRANSITION INTO THE ACTIVE STATE.
-#    state = 'ACTIVE' only. RTN is the return-to-normal of the activation that
+#    state = 'ACTIVE' only — a 0 -> 1 on one bit. RTN is the return-to-normal
-#    preceded it, and ACK is an operator acknowledging one. Counting every row
+#    of the activation that preceded it. Counting every row roughly doubles
-#    roughly doubles every answer. "6 times last week" must mean six
+#    every answer. "6 times last week" must mean six activations.
-#    activations.
 #
 # 2. "LAST WEEK" IS A ROLLING 7 x 24 h WINDOW IN SITE_TIMEZONE.
 #    Not the previous calendar week, not 7 calendar days. Storage is UTC and
 #    the conversion happens here, once. If someone means the calendar week they
 #    have to say so, and the answer must state the window it used.
 #
+#    A ROLLING WEEK IS NOW ALSO THE WHOLE OF THE AVAILABLE HISTORY. Every WRPS
+#    history group carries LIFE_TIME "1 weeks", so a question about anything
+#    older returns no rows — correctly, and it must be reported as "outside
+#    retention", never as "no alarms occurred".
+#
 # 3. CHATTERING IS 3 OR MORE ACTIVATIONS OF THE SAME TAG WITHIN 60 MINUTES.
 #    An arbitrary threshold, chosen to match the site's alarm rationalisation
 #    convention. It is stated in the answer whenever chattering is reported,
 #    because a different threshold gives a different story.
+#
+# THERE IS NO equipment_id IN THE SOURCE, AND THERE MUST NOT BE ONE.
+# Equipment is reached bit -> tag -> equipment, through public.tags, which is
+# the single place equipment is asserted. A denormalised equipment column in
+# the history disagreeing with the tag seed is what made the station's most
+# obvious question unanswerable; there is now nothing left to disagree.
 # =============================================================================
 
 cubes:
   - name: alarms
-    sql_table: fixture.alarm_history      # -> imh alarm table at Phase 4
+    sql_table: fixture.alarm_history      # -> imh-backed view at Phase 4
     description: >
-      Alarm and event history for the Waterloo Road Pump Station. One row per
+      Alarm and event history for the Waterloo Road Pump Station, derived from
-      state transition. Activations only are counted as alarms.
+      bit transitions of the PLC alarm word. One row per state transition.
+      Activations only are counted as alarms.
 
     joins:
-      - name: equipment
+      # tag first, then equipment through it. Both hops are defined once, here
-        sql: "{CUBE}.equipment_id = {equipment}.equipment_id"
+      # and in equipment.yml, so "how many wet well alarms" resolves without
+      # anything in this file naming a piece of equipment.
+      - name: tags
+        sql: "{CUBE}.tag_id = {tags}.tag_id"
         relationship: many_to_one
 
     dimensions:
@@ -47,15 +80,31 @@ cubes:
       - name: event_time
         sql: event_time
         type: time
-        description: Transition time. Stored UTC, presented in SITE_TIMEZONE.
+        description: >
+          Transition time. Stored UTC — every WRPS Modbus point carries
+          TIME_ZONE "Date+time GMT" and every history group CORRECT_DAYLIGHT=0
+          — and presented in SITE_TIMEZONE. Cube converts time DIMENSIONS
+          automatically; see first_alarm below for why measures are different.
+
+      - name: item_name
+        sql: item_name
+        type: string
+        description: >
+          The CI Server item the alarm was derived from — always
+          AID.WRPS.STN.ALARM_WORD. Kept so an engineer can go from an answer
+          back to the raw history in one step.
+
+      - name: bit
+        sql: bit
+        type: number
+        description: Which bit of the alarm word. See public.alarm_bits.
 
       - name: tag_id
         sql: tag_id
         type: string
-
+        description: >
-      - name: equipment_id
+          The tag the alarm is ABOUT, from the bit map — MSE-333 for a PU-303
-        sql: equipment_id
+          seal leak, not the bitmask item. This is the join to equipment.
-        type: string
 
       - name: alarm_type
         sql: alarm_type
@@ -63,36 +112,42 @@ cubes:
         description: >
           HIGH_LEVEL, HIGH_HIGH_LEVEL, LOW_LOW_LEVEL, SPILL, PUMP_TRIP,
           SEAL_LEAK, HIGH_VIBRATION, LEVEL_SIGNAL_FAULT, MAINS_FAILURE,
-          SETPOINT_REJECTED. These correspond to the bits of the PLC alarm
+          SETPOINT_REJECTED. One per bit of %QW17 — see db/seed/alarm_bits.csv.
-          bitmask %QW17 - see db/seed/tags.csv, PS_STN_ALARM_BITMASK.
 
       - name: state
         sql: state
         type: string
-        description: ACTIVE, RTN or ACK. Only ACTIVE counts as an alarm.
+        description: ACTIVE or RTN. Only ACTIVE counts as an alarm.
 
       - name: priority
         sql: priority
         type: number
         description: >
-          1 highest, 3 lowest. Priority 1 is SPILL, PUMP_TRIP and
+          1 highest, 3 lowest, from the bit map. Priority 1 is SPILL,
-          LEVEL_SIGNAL_FAULT - losing the level signal on a well that can spill
+          PUMP_TRIP, HIGH_HIGH_LEVEL, LOW_LOW_LEVEL, MAINS_FAILURE and
-          is a priority 1 condition, and the fixtures already treat it as one.
+          LEVEL_SIGNAL_FAULT — losing the level signal on a well that can spill
-          This comment previously named only SPILL and PUMP_TRIP and disagreed
+          is a priority 1 condition. Reference data, not a constant in this
-          with the data, which matters because this is the line an engineer
+          file, so this comment cannot drift out of step with the data again.
-          reads when checking a priority_1_count.
 
       - name: value
         sql: value
         type: number
-        description: Process value at the transition, in engineering_unit.
+        description: >
+          Process value at the transition, for the alarms that have one — a
+          level reading for a high level alarm, NULL for a pump trip. Do not
+          present NULL as zero.
+
+      - name: alarm_text
+        sql: alarm_text
+        type: string
 
       - name: is_fixture
         sql: is_fixture
         type: boolean
         description: >
-          TRUE means this row came from db/002_fixtures.sql and is generated
+          TRUE means this row was derived from db/002_fixtures.sql and is
-          test data, not plant history. The API surfaces this to the operator.
+          generated test data, not plant history. The API surfaces this to the
+          operator.
 
     measures:
       - name: alarm_count
@@ -106,8 +161,8 @@ cubes:
       - name: transition_count
         type: count
         description: >
-          Every row including RTN and ACK. Diagnostics only - do not answer an
+          Every row including RTN. Diagnostics only - do not answer an operator
-          operator question with this.
+          question with this.
 
       - name: distinct_tags
         sql: tag_id
@@ -116,43 +171,81 @@ cubes:
           - sql: "{CUBE}.state = 'ACTIVE'"
         description: How many different tags alarmed in the window.
 
-      # DEFERRED DEFECT - these two return UTC, not SITE_TIMEZONE. Cube converts
+      # -----------------------------------------------------------------------
-      # time DIMENSIONS to the query timezone; a min/max MEASURE over a
+      # first_alarm / last_alarm — Phase 5 finding (b), FIXED.
-      # timestamp comes back unconverted. In a Sydney day bucket for
-      # 2026-08-01, first_alarm returns 2026-07-31T20:00:35 - the right
-      # instant, ten hours and one calendar day out, next to a bucket label
-      # that IS in site time.
       #
-      # Left unfixed on purpose until imh is connected: the fix must keep the
+      # These used to be plain min/max measures over a timestamp and came back
-      # conversion inside Cube, and which fix is right depends on whether imh
+      # in UTC. Cube converts time DIMENSIONS to the query timezone but not
-      # stores UTC or local time (Phase 4, task 4). Until then, do NOT quote
+      # min/max MEASURES, so on the Sydney day bucket 2026-08-01 the measure
-      # either of these to an operator as a clock time. See Phase 4,
+      # returned 2026-07-31T20:00:35 — the right instant, ten hours and one
-      # "Deferred from Phase 5", finding (b) in BUILD-AI-CONTAINERS.md.
+      # calendar day out, beside a bucket label that WAS in site time.
+      #
+      # The conversion now happens here, inside the measure, which keeps it
+      # inside Cube and exactly once. The aggregate is taken FIRST and
+      # converted after — MIN(x) AT TIME ZONE z, not MIN(x AT TIME ZONE z) —
+      # because the second form takes the minimum of local clock readings and
+      # picks the wrong row across a daylight-saving fall-back, where one local
+      # hour occurs twice.
+      #
+      # Returned as a formatted string rather than a timestamp, deliberately:
+      # a bare timestamp with no offset is exactly what made the old defect
+      # invisible. The answer must state the timezone alongside it, and
+      # site_timezone below is what it states.
+      #
+      # THE ZONE NAME IS HARDCODED HERE, WHICH THE BUILD SPEC WOULD RATHER IT
+      # WERE NOT. Cube can read env vars in a YAML model through Jinja
+      # (`{{ env_var('SITE_TIMEZONE') }}`), which would take it from api.env
+      # like everything else. That was not shipped because a model that fails
+      # to compile takes every query down with it and Jinja support could not
+      # be tested against the pinned v1.1.7 before writing this. scripts/
+      # verify.sh asserts this literal matches SITE_TIMEZONE in api.env, so the
+      # two cannot drift silently. Switch it to env_var once someone can
+      # confirm the model still compiles on lin001.
+      # -----------------------------------------------------------------------
       - name: first_alarm
-        sql: event_time
+        sql: >
-        type: min
+          to_char(MIN({CUBE}.event_time) FILTER (WHERE {CUBE}.state = 'ACTIVE')
-        filters:
+                  AT TIME ZONE 'Australia/Sydney', 'YYYY-MM-DD HH24:MI:SS')
-          - sql: "{CUBE}.state = 'ACTIVE'"
+        type: string
+        description: >
+          Earliest activation in the window, in SITE_TIMEZONE. Quote it with
+          the timezone - see site_timezone.
 
       - name: last_alarm
-        sql: event_time
+        sql: >
-        type: max
+          to_char(MAX({CUBE}.event_time) FILTER (WHERE {CUBE}.state = 'ACTIVE')
-        filters:
+                  AT TIME ZONE 'Australia/Sydney', 'YYYY-MM-DD HH24:MI:SS')
-          - sql: "{CUBE}.state = 'ACTIVE'"
+        type: string
+        description: >
+          Latest activation in the window, in SITE_TIMEZONE. Quote it with the
+          timezone - see site_timezone.
+
+      - name: site_timezone
+        sql: "MAX('Australia/Sydney')"
+        type: string
+        description: >
+          The zone first_alarm and last_alarm are expressed in. A clock time
+          without its zone is what finding (b) shipped; this exists so the
+          answer never has to assume one.
 
       - name: priority_1_count
         type: count
         filters:
           - sql: "{CUBE}.state = 'ACTIVE' AND {CUBE}.priority = 1"
-        description: Priority 1 activations - trips and spills.
+        description: >
+          Priority 1 activations - trips, spills, high high level, dry run,
+          mains failure and level signal fault.
 
     pre_aggregations:
       # Keeps "count alarms last week" fast without repeatedly scanning imh.
-      # Materialised into pg-ai schema cube_preagg. Watch its growth on
+      # Materialised into Cube Store. first_alarm, last_alarm and
-      # /datadisk; the retention policy is the refresh_key plus manual pruning.
+      # site_timezone are deliberately NOT here: they are string measures over
+      # a non-additive aggregate and cannot be rolled up from an hourly
+      # partition. A query asking for them falls through to the source, which
+      # is correct and cheap at this volume.
       - name: alarms_by_hour
         measures: [alarm_count, distinct_tags, priority_1_count]
-        dimensions: [alarm_type, equipment_id, tag_id]
+        dimensions: [alarm_type, tag_id, bit]
         time_dimension: event_time
         granularity: hour
         partition_granularity: month
@@ -163,29 +256,45 @@ cubes:
           # deliberately when imh makes the data genuinely live.
           every: 24 hours
         build_range_start:
-          sql: "SELECT now() - interval '180 days'"
+          # Seven days, matching the historian's own retention. Building 180
+          # days of partitions over a source that only ever holds seven is
+          # work that produces empty partitions.
+          sql: "SELECT now() - interval '8 days'"
         build_range_end:
           sql: "SELECT now()"
 
 views:
   - name: alarm_activity
     description: >
-      Alarm activations joined to equipment, so a question about "Pump 02" can
+      Alarm activations joined to the tag they are about and the equipment that
-      be answered without the caller knowing which tags belong to it.
+      tag belongs to, so a question about "Pump 02" or "the wet well" can be
+      answered without the caller knowing which bit of the alarm word carries
+      it.
     cubes:
       - join_path: alarms
         includes:
           - event_time
           - alarm_type
           - tag_id
+          - bit
           - state
           - priority
           - value
+          - alarm_text
           - is_fixture
           - alarm_count
           - distinct_tags
           - priority_1_count
-      - join_path: alarms.equipment
+          - first_alarm
+          - last_alarm
+          - site_timezone
+      - join_path: alarms.tags
+        prefix: true
+        includes:
+          - display_name
+          - signal_type
+          - engineering_unit
+      - join_path: alarms.tags.equipment
         prefix: true
         includes:
           - equipment_id

cube/model/equipment.yml

@@ -141,7 +141,145 @@ cubes:
       - name: count
         type: count
 
+  # ---------------------------------------------------------------------------
+  # historian_items — the CI Server item dictionary.
+  #
+  # WHY IT IS A CUBE AT ALL: so "what is AID.WRPS.STN.LEVEL" and "which item
+  # holds the wet well level" are both answerable, and so an engineer checking
+  # a number can walk from the answer back through item -> point -> PLC address
+  # without leaving the assistant. Four namespaces name the same measurement
+  # and this table is the only place all four appear together.
+  #
+  # It is also where an item's SAMPLE RATE and RETENTION come from, both taken
+  # from the live CI Server historisation groups rather than assumed.
+  # ---------------------------------------------------------------------------
+  - name: historian_items
+    sql_table: public.historian_items
+    description: >
+      CI Server items - what the historian is actually keyed on - and how each
+      maps to a tag, a SCADA point and a PLC register.
+
+    joins:
+      - name: tags
+        sql: "{CUBE}.tag_id = {tags}.tag_id"
+        relationship: many_to_one
+
+    dimensions:
+      - name: item_name
+        sql: item_name
+        type: string
+        primary_key: true
+        description: AID.WRPS.STN.LEVEL. The historian's own key.
+
+      - name: tag_id
+        sql: tag_id
+        type: string
+        description: >
+          NULL only for items deliberately excluded from answering - see
+          exclusion_reason. A NULL here with no reason is a build failure.
+
+      - name: exclusion_reason
+        sql: exclusion_reason
+        type: string
+        description: >
+          Why this item cannot be asked about. Present it verbatim rather than
+          reporting "no records found" - the two mean very different things.
+
+      - name: section
+        sql: section
+        type: string
+        description: >
+          CI Server's own grouping - STN, PU301, PU302, PU303, SP, SIM. It is
+          COARSER than plant equipment: there is no wet well, weir, manifold or
+          switchboard section. Use equipment for the plant view, not this.
+
+      - name: attribute
+        sql: attribute
+        type: string
+
+      - name: description
+        sql: description
+        type: string
+
+      - name: eng_unit
+        sql: eng_unit
+        type: string
+        description: The unit CI Server presents, which is not the PLC's unit.
+
+      - name: raw_to_eng
+        sql: raw_to_eng
+        type: string
+        description: >
+          How the raw register becomes the engineering value, as written in the
+          SCADA point list - "value / 60" for level. Quote this when explaining
+          why a level reads 70.3 and not 4217.
+
+      - name: his_group
+        sql: his_group
+        type: string
+        description: WRPS_ONE_SEC (5 s), WRPS_THIRTY_SEC (30 s), WRPS_EVENT (on change).
+
+      - name: scan_interval_seconds
+        sql: scan_interval_seconds
+        type: number
+
+      - name: life_time
+        sql: life_time
+        type: string
+        description: >
+          Retention on the item's history group - "1 weeks" on every WRPS
+          group. This is the answer to "why can it not tell me about last
+          month".
+
+      - name: scada_point
+        sql: scada_point
+        type: string
+
+      - name: iec_address
+        sql: iec_address
+        type: string
+        description: The PLC address, %QW0. Field inputs (%IW/%IX) are not historised.
+
+    measures:
+      - name: count
+        type: count
+
 views:
+  - name: item_reference
+    description: >
+      The CI Server item dictionary joined to the tag and equipment each item
+      belongs to. This is the lookup behind "which item holds the wet well
+      level", "how often is it sampled" and "how far back does it go".
+    cubes:
+      - join_path: historian_items
+        includes:
+          - item_name
+          - tag_id
+          - exclusion_reason
+          - section
+          - attribute
+          - description
+          - eng_unit
+          - raw_to_eng
+          - his_group
+          - scan_interval_seconds
+          - life_time
+          - scada_point
+          - iec_address
+          - count
+      - join_path: historian_items.tags
+        prefix: true
+        includes:
+          - display_name
+          - signal_type
+          - engineering_unit
+      - join_path: historian_items.tags.equipment
+        prefix: true
+        includes:
+          - equipment_id
+          - display_name
+          - equipment_type
+
   - name: equipment_reference
     description: >
       Equipment joined to its tags - the lookup behind "what does the PVHI

cube/model/operations.yml

@@ -7,21 +7,37 @@
 # what the documented limits are - then a deferral. Everything needed for that
 # is a measure here.
 #
-# SOURCE: fixture.operation_history while USE_FIXTURES=true.
+# REMOVING THE STAND-IN: db/README-standin-historian.md. The view below is
+# CONTRACT - repoint it at imh, do not edit this file to absorb a difference.
+#
+# SOURCE: fixture.operation_history while USE_FIXTURES=true. It is a
+# MATERIALIZED VIEW and it is DERIVED, not stored - confirmed now rather than
+# assumed: CI Server has no operations concept, and the WRPS item list is 49
+# points with nothing resembling a batch or campaign record.
 #
-# IF imh HAS NO OPERATIONS TABLE - and it probably does not - derive it here.
 # The heuristic, kept deliberately simple so it can be explained to the person
-# checking the number:
+# checking the number, and implemented in db/002_fixtures.sql exactly as
+# written here:
 #
-#   A PUMP-DOWN starts at the sample where PS_STN_PUMPS_RUNNING goes from 0 to
+#   A PUMP-DOWN starts at the sample where AID.WRPS.STN.PUMPS_RUNNING goes from
-#   non-zero, and ends at the next sample where it returns to 0. Its max level
+#   0 to non-zero, and ends at the next sample where it returns to 0. Its max
-#   is the maximum PS_STN_WET_WELL_LEVEL over that span plus the 10 minutes
+#   level is the maximum AID.WRPS.STN.LEVEL over that span plus the 10 minutes
 #   before it, because the peak is usually just before the pumps catch up.
 #   Operations shorter than 5 minutes are discarded as start/stop noise.
 #
 # Do not make this cleverer. A heuristic nobody can explain is not evidence,
 # and this cube's whole job is to produce evidence.
 #
+# THE TWO SOURCE ITEMS ARE SAMPLED AT DIFFERENT RATES - PUMPS_RUNNING every 30
+# seconds, LEVEL every 5 - and the boundaries line up only because 30 is a
+# multiple of 5. If either group's rate is retuned on the server, check that
+# assumption before trusting start_level_pct or end_level_pct.
+#
+# THERE IS NO equipment_id. A pump-down belongs to the station and to nothing
+# else; duty_pump names the unit that led it. The column used to exist, carried
+# the literal 'STN-001', and was part of the same denormalisation that made
+# alarm equipment disagree with the tag seed.
+#
 # ON THE WORD "FILL": the generic spec calls these fills. WRPS is a pump
 # station, so the operation is a pump-down - the well fills passively on inflow
 # and the station draws it back down. Same shape, opposite sign. The measures
@@ -36,11 +52,6 @@ cubes:
       how high the well got, how much came in, how much was pumped, which unit
       was duty, and whether it alarmed or spilled.
 
-    joins:
-      - name: equipment
-        sql: "{CUBE}.equipment_id = {equipment}.equipment_id"
-        relationship: many_to_one
-
     dimensions:
       - name: operation_id
         sql: operation_id
@@ -56,10 +67,6 @@ cubes:
         sql: end_time
         type: time
 
-      - name: equipment_id
-        sql: equipment_id
-        type: string
-
       - name: operation_type
         sql: operation_type
         type: string
@@ -160,7 +167,7 @@ cubes:
           - max_level_reached
           - high_alarm_count
           - spill_count
-        dimensions: [equipment_id, duty_pump, operation_type]
+        dimensions: [duty_pump, operation_type, peak_pumps_running]
         time_dimension: start_time
         granularity: day
         partition_granularity: month
@@ -171,6 +178,8 @@ cubes:
           # deliberately when imh makes the data genuinely live.
           every: 24 hours
         build_range_start:
-          sql: "SELECT now() - interval '365 days'"
+          # Eight days, not 365. The historian retains one week, so a pump-down
+          # older than that does not exist to be aggregated.
+          sql: "SELECT now() - interval '8 days'"
         build_range_end:
           sql: "SELECT now()"

cube/model/process_values.yml

@@ -1,100 +1,126 @@
 # =============================================================================
 # process_values.yml — sampled analogue history.
 #
-# SOURCE: fixture.process_value_history while USE_FIXTURES=true; the agreed imh
+# REMOVING THE STAND-IN: db/README-standin-historian.md. The view below is
-# process value table from Phase 4.
+# CONTRACT - repoint it at imh, do not edit this file to absorb a difference.
 #
-# THE THING THAT WILL BITE WHEN imh IS CONNECTED: CI Server historises with a
+# SOURCE: fixture.process_value_history while USE_FIXTURES=true; the same view
-# deadband, so real samples are IRREGULAR. The fixtures are regular 1-minute
+# repointed at imh from Phase 4. It is keyed on CI SERVER ITEM NAMES
-# samples. Any measure that averages rows rather than time-weighting them will
+# (AID.WRPS.STN.LEVEL), which is what the historian is keyed on, and it
-# look correct on fixtures and be wrong on imh - a flat period compresses to
+# resolves each item onto its tag through public.historian_items.
-# one row and a noisy period to hundreds, so a plain avg is weighted by how
-# interesting the signal was. avg_value below is a plain average and is
-# documented as an approximation; time_weighted_avg is the one to trust, and it
-# must be re-verified against imh at the Phase 5 gate.
 #
-# SENTINELS: PS_STN_TIME_TO_SPILL_WEIR and PS_STN_TIME_TO_LSHH use 32767 to
+# PHASE 5 FINDING (a), FIXED — AND HOW.
-# mean "drawing down or holding" - it is not a duration. Every measure here
+# The history used to be keyed PS_STN_WET_WELL_LEVEL, a CI Server POINT name,
-# excludes it. Do not remove that filter to make a number look tidier.
+# while db/seed/tags.csv carried that string only as an ALIAS of LIT-101. So
+# public.tags had no row with that tag_id, a tag-level lookup for the wet well
+# matched ZERO of 43,201 level rows, and it surfaced as "no records found" —
+# which an operator cannot tell apart from an absence of data.
+#
+# The names were two layers apart, not one:
+#
+#   LIT-101                instrument tag     WRPS/01-design-doc
+#   %QW0                   PLC symbol         WRPS/04-plc/register-map.csv
+#   PS_STN_WET_WELL_LEVEL  CI Server point    WRPS/05-scada/modbus/scada-points.csv
+#   AID.WRPS.STN.LEVEL     CI Server ITEM     <- what the historian stores
+#
+# Nothing is aliased across that gap any more. public.historian_items holds the
+# item-to-tag mapping, it is generated from the SCADA configuration by
+# scripts/gen_historian_items.py, and both that script and scripts/deploy.sh
+# refuse to proceed if a historised item resolves to neither a tag nor a
+# written reason for having none. LIT-101 is now correctly marked NOT
+# HISTORISED: it is a field input on %IW0 and never reaches SCADA.
+#
+# SAMPLE RATES ARE DECLARED, NOT ASSUMED.
+# scan_interval_seconds rides on every row, from the historisation group the
+# item belongs to: 5 s for WRPS_ONE_SEC, 30 s for WRPS_THIRTY_SEC. Two measures
+# below convert sample counts into durations and USED TO HARDCODE 60 SECONDS.
+# Against a 5-second group that is wrong by a factor of twelve, and it would
+# have read as plausible.
+#
+# ON DEADBAND COMPRESSION — the previous note here was WRONG and it mattered.
+# It warned that real CI Server history is deadband-compressed and therefore
+# irregular, so a plain average would be biased and only a time-weighted one
+# could be trusted. The WRPS configuration says otherwise: every history group
+# has DATA_COMP = 0, every item STORE_DEADBAND = 0, and the analogue groups are
+# COL_STOR_TYPE "Scan/Time". These samples are regular. The warning is true
+# only of WRPS_EVENT, which is Event/Item and genuinely on-change, and which
+# this cube does not read.
+#
+# THE CHECK THAT MUST STILL RUN AT THE PHASE 4 GATE: confirm against real imh
+# data that the gap between consecutive samples of AID.WRPS.STN.LEVEL really is
+# the declared 5 seconds. If it is not — if someone enables compression, or the
+# link drops — every duration measure here is wrong, and the fix is to compute
+# gaps with a LEAD window rather than trusting the declaration.
+#
+# SENTINELS: AID.WRPS.STN.TIME_TO_SPILL and .TIME_TO_LSHH use 32767 to mean
+# "drawing down or holding" - it is not a duration. Every measure here excludes
+# it. Do not remove that filter to make a number look tidier.
 #
 # QUALITY: rows with quality other than GOOD are excluded from every measure.
-# A BAD sample from a failed transmitter is not a low reading.
+# A BAD sample from a failed transmitter is not a low reading. The fixtures
+# exercise this - the level transmitter is frozen for an hour and those samples
+# are flagged BAD.
 #
 # UNITS: whatever the historian stores, which is not always what the PLC works
 # in. Wet well level is historised as percent of the spill weir crest (raw mm
-# divided by 60): 100.0 % = 6000 mm. See db/seed/tags.csv for every conversion.
+# divided by 60): 100.0 % = 6000 mm. See db/seed/historian_items.csv for every
-#
+# gain, taken from the SCADA point list rather than restated here.
-# DEFERRED DEFECT - THE LEVEL TAG NAME DOES NOT AGREE WITH THE REFERENCE DATA.
-# The history is keyed PS_STN_WET_WELL_LEVEL, hardcoded below in
-# seconds_above_high_level_alarm and seconds_above_lshh. db/seed/tags.csv
-# carries that name only as an ALIAS of LIT-101, so public.tags has no row with
-# that tag_id and a tag-level lookup for WW-101 matches ZERO history rows -
-# surfacing as "no records found", which an operator cannot distinguish from
-# there genuinely being no data. Filtering by equipment_id works, so whether a
-# level question fails depends on the path the agent takes.
-#
-# Unfixed on purpose: which name is correct is a question for the WRPS register
-# map and for imh, not something to guess against fixtures. See Phase 4,
-# "Deferred from Phase 5", finding (a) in BUILD-AI-CONTAINERS.md, and eval case
-# H26. Fix the seed, these hardcoded names and db/002_fixtures.sql together.
 # =============================================================================
 
 cubes:
   - name: process_values
-    # NOT sql_table, because time_weighted_avg needs to know how long each
+    sql_table: fixture.process_value_history   # -> imh-backed view at Phase 4
-    # sample stood, and that is a window function - which Postgres will not
-    # allow inside an aggregate. So the gap is computed once here, per tag, and
-    # the measure just sums it. The alternative (LEAD inside SUM) is what this
-    # file used to say, and it failed every query outright on lin001.
-    #
-    # The last sample of each tag gets a NULL duration, which is correct: how
-    # long it stood is not yet known, and SUM skips it.
-    #
-    # AT PHASE 4 this window runs over imh, not over 130k fixture rows next
-    # door. Check the plan before trusting it - if it scans the whole history
-    # per query, push the LEAD into a pre-aggregation or a derived table.
-    sql: >
-      SELECT
-        sample_time,
-        tag_id,
-        equipment_id,
-        value,
-        engineering_unit,
-        quality,
-        is_fixture,
-        EXTRACT(EPOCH FROM (
-          LEAD(sample_time) OVER (PARTITION BY tag_id ORDER BY sample_time)
-          - sample_time
-        )) AS sample_duration_seconds
-      FROM fixture.process_value_history    -- -> imh PV table at Phase 4
     description: >
       Sampled analogue history - wet well level, inflow, discharge flow, drive
-      speed, run hours. This is what makes an advisory question answerable with
+      speed, net accumulation, and the 30-second station items. This is what
-      evidence; you cannot answer a flow question from alarms.
+      makes an advisory question answerable with evidence; you cannot answer a
+      flow question from alarms.
 
     joins:
-      - name: equipment
+      - name: tags
-        sql: "{CUBE}.equipment_id = {equipment}.equipment_id"
+        sql: "{CUBE}.tag_id = {tags}.tag_id"
         relationship: many_to_one
 
     dimensions:
       - name: id
-        sql: "{CUBE}.tag_id || '@' || {CUBE}.sample_time"
+        sql: "{CUBE}.item_name || '@' || {CUBE}.sample_time"
         type: string
         primary_key: true
 
       - name: sample_time
         sql: sample_time
         type: time
-        description: Stored UTC, presented in SITE_TIMEZONE. Converted once, here.
+        description: >
+          Stored UTC - every WRPS Modbus point carries TIME_ZONE
+          "Date+time GMT" - and presented in SITE_TIMEZONE. Converted once,
+          here.
+
+      - name: item_name
+        sql: item_name
+        type: string
+        description: >
+          The CI Server item. This is the historian's own key; filter on it
+          when you know exactly which point you want.
 
       - name: tag_id
         sql: tag_id
         type: string
+        description: >
+          The tag the item corresponds to, resolved through
+          public.historian_items. The join to equipment goes through here.
 
-      - name: equipment_id
+      - name: his_group
-        sql: equipment_id
+        sql: his_group
         type: string
+        description: WRPS_ONE_SEC (5 s) or WRPS_THIRTY_SEC (30 s).
+
+      - name: scan_interval_seconds
+        sql: scan_interval_seconds
+        type: number
+        description: >
+          Seconds between samples, from the item's historisation group. Any
+          measure turning a count of samples into a duration must use this and
+          never a literal.
 
       - name: engineering_unit
         sql: engineering_unit
@@ -123,24 +149,24 @@ cubes:
         filters:
           - sql: "{CUBE}.quality = 'GOOD' AND {CUBE}.value <> 32767"
         description: >
-          APPROXIMATION. Plain average of samples. Correct on the regular
+          Plain average of samples. Correct on Scan/Time history, which is
-          fixture data; biased on deadband-compressed imh data. Prefer
+          regular - CI Server has compression and deadband switched off on
-          time_weighted_avg for anything an engineer will check.
+          every WRPS group. Prefer time_weighted_avg only if that ever changes.
 
       - name: time_weighted_avg
         sql: >
           SUM(CASE WHEN {CUBE}.quality = 'GOOD' AND {CUBE}.value <> 32767
-                   THEN {CUBE}.value * {CUBE}.sample_duration_seconds END)
+                   THEN {CUBE}.value * {CUBE}.scan_interval_seconds END)
           / NULLIF(SUM(CASE WHEN {CUBE}.quality = 'GOOD' AND {CUBE}.value <> 32767
-                            THEN {CUBE}.sample_duration_seconds END), 0)
+                            THEN {CUBE}.scan_interval_seconds END), 0)
         type: number
         description: >
-          Time-weighted average - each sample weighted by how long it stood,
+          Each sample weighted by how long it stood, using the item's declared
-          from sample_duration_seconds in the cube's source query above. This
+          scan interval. On regular Scan/Time history this agrees with
-          is the honest average on deadband-compressed history, and on regular
+          avg_value exactly, which is why the Phase 4 gate has to confirm the
-          fixture data it agrees with avg_value to a rounding error - which is
+          real gaps ARE the declared interval - if they are not, this is the
-          exactly why it must be re-verified against imh, where the two will
+          measure that stays honest and avg_value is the one that quietly
-          NOT agree. Bad and sentinel samples are excluded in the CASE rather
+          stops being. Bad and sentinel samples are excluded in the CASE rather
           than by a measure filter, for the same reason as p95_value below.
 
       - name: max_value
@@ -170,33 +196,48 @@ cubes:
           95th percentile. More useful than max for "how high does it normally
           get", because max is one sample and often a transient.
 
+      - name: bad_sample_count
+        type: count
+        filters:
+          - sql: "{CUBE}.quality <> 'GOOD'"
+        description: >
+          Samples excluded for quality. Report this whenever it is non-zero:
+          an average over a window in which the transmitter was frozen is an
+          average over less data than the operator thinks, and the level signal
+          fault (alarm word bit 13) is the reason to look.
+
       - name: seconds_above_high_level_alarm
+        # Sums the DECLARED scan interval per qualifying sample rather than a
+        # literal. The previous version summed 60 per sample against what is
+        # now a 5-second group - a twelvefold overstatement that would have
+        # read as entirely plausible.
         sql: >
-          SUM(CASE WHEN {CUBE}.tag_id = 'PS_STN_WET_WELL_LEVEL'
+          SUM(CASE WHEN {CUBE}.item_name = 'AID.WRPS.STN.LEVEL'
-                    AND {CUBE}.value >= 86.7 THEN 60 ELSE 0 END)
+                    AND {CUBE}.quality = 'GOOD'
+                    AND {CUBE}.value >= 86.7
+                   THEN {CUBE}.scan_interval_seconds ELSE 0 END)
         type: number
         description: >
           Seconds the wet well spent above the high level alarm setpoint
-          (86.7 % = 5200 mm, the %MW8 default). ASSUMES A 60 SECOND SAMPLE
+          (86.7 % = 5200 mm, the %MW8 default). If the setpoint itself was
-          INTERVAL, true of the fixtures and NOT true of imh. When imh is
+          changed during the window - AID.WRPS.SP.HIGH_ALARM - this measure is
-          connected this must be rewritten to sum actual sample gaps - it is on
+          wrong and the answer must say so.
-          the Phase 5 gate list for exactly that reason. If the setpoint itself
-          was changed during the window (PS_STN_HIGH_LEVEL_ALARM_SP), this
-          measure is wrong and the answer must say so.
 
       - name: seconds_above_lshh
         sql: >
-          SUM(CASE WHEN {CUBE}.tag_id = 'PS_STN_WET_WELL_LEVEL'
+          SUM(CASE WHEN {CUBE}.item_name = 'AID.WRPS.STN.LEVEL'
-                    AND {CUBE}.value >= 91.7 THEN 60 ELSE 0 END)
+                    AND {CUBE}.quality = 'GOOD'
+                    AND {CUBE}.value >= 91.7
+                   THEN {CUBE}.scan_interval_seconds ELSE 0 END)
         type: number
         description: >
-          Seconds above LSHH (91.7 % = 5500 mm). Same 60 second assumption as
+          Seconds above LSHH (91.7 % = 5500 mm). Any non-zero value here is
-          above. Any non-zero value here is worth reporting explicitly.
+          worth reporting explicitly.
 
     pre_aggregations:
       - name: pv_by_hour
-        measures: [avg_value, max_value, min_value, sample_count]
+        measures: [avg_value, max_value, min_value, sample_count, bad_sample_count]
-        dimensions: [tag_id, equipment_id, engineering_unit]
+        dimensions: [item_name, tag_id, engineering_unit, his_group]
         time_dimension: sample_time
         granularity: hour
         partition_granularity: month
@@ -207,6 +248,46 @@ cubes:
           # deliberately when imh makes the data genuinely live.
           every: 24 hours
         build_range_start:
-          sql: "SELECT now() - interval '180 days'"
+          # Eight days, not 180. The historian retains one week; partitions
+          # older than that would be built empty, every refresh, forever.
+          sql: "SELECT now() - interval '8 days'"
         build_range_end:
           sql: "SELECT now()"
+
+views:
+  - name: process_history
+    description: >
+      Analogue history joined to the tag and equipment it belongs to, so a
+      level question about "the wet well" resolves without the caller knowing
+      the item is called AID.WRPS.STN.LEVEL.
+    cubes:
+      - join_path: process_values
+        includes:
+          - sample_time
+          - item_name
+          - tag_id
+          - his_group
+          - scan_interval_seconds
+          - engineering_unit
+          - quality
+          - is_fixture
+          - sample_count
+          - avg_value
+          - time_weighted_avg
+          - max_value
+          - min_value
+          - p95_value
+          - bad_sample_count
+          - seconds_above_high_level_alarm
+          - seconds_above_lshh
+      - join_path: process_values.tags
+        prefix: true
+        includes:
+          - display_name
+          - signal_type
+      - join_path: process_values.tags.equipment
+        prefix: true
+        includes:
+          - equipment_id
+          - display_name
+          - equipment_type

db/001_schema.sql

@@ -66,6 +66,98 @@ CREATE TABLE IF NOT EXISTS tags (
 CREATE INDEX IF NOT EXISTS tags_aliases_gin  ON tags USING gin (aliases);
 CREATE INDEX IF NOT EXISTS tags_equipment_ix ON tags (equipment_id);
 
+-- -----------------------------------------------------------------------------
+-- historian_items — the CI Server item dictionary, and the ONLY place an
+-- item name is joined to a tag.
+--
+-- FOUR NAMESPACES DESCRIBE THE SAME MEASUREMENT and only the last is what the
+-- historian is keyed on:
+--
+--   LIT-101                instrument tag     WRPS/01-design-doc
+--   %QW0                   PLC symbol         WRPS/04-plc/register-map.csv
+--   PS_STN_WET_WELL_LEVEL  CI Server point    WRPS/05-scada/modbus/scada-points.csv
+--   AID.WRPS.STN.LEVEL     CI Server ITEM     WRPS/05-scada/modbus/wrps_item_df.qli
+--
+-- The history was previously keyed on the third of those while the tag seed
+-- carried it only as an alias of the first, so a tag-level lookup for the wet
+-- well matched zero rows and reported "no records found" — indistinguishable
+-- from an absence of data. That was Phase 5 finding (a).
+--
+-- Two rules keep it from recurring, and both are enforced rather than reviewed:
+--
+--   1. tag_id is NULLABLE, but a NULL one must carry an exclusion_reason.
+--      The CHECK below is the enforcement. scripts/gen_historian_items.py
+--      refuses to write the seed at all if a historised item has neither.
+--   2. NOTHING IN THE HISTORY CARRIES AN equipment_id. Equipment is asserted
+--      once, in tags.equipment_id, and reached from history through this
+--      table. Finding (c) was a denormalised equipment column in the history
+--      disagreeing with the tag seed; there is now only one assertion to
+--      disagree with.
+--
+-- Regenerate with:  python scripts/gen_historian_items.py --wrps <path>
+-- -----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS historian_items (
+    item_name        TEXT PRIMARY KEY,      -- AID.WRPS.STN.LEVEL
+    tag_id           TEXT REFERENCES tags(tag_id),
+    exclusion_reason TEXT,                  -- why this item is unanswerable
+    section_path     TEXT,                  -- AID.WRPS.STN
+    section          TEXT,                  -- STN, PU301, SP, SIM
+    attribute        TEXT,                  -- LEVEL, RUNNING, TRIPPED
+    section_description TEXT,
+    description      TEXT,
+    eng_unit         TEXT,                  -- what CI Server presents, not PLC units
+    value_format     TEXT,
+    conv_type        TEXT,                  -- Linear | Digital
+    has_sign         BOOLEAN,
+    phys_low         DOUBLE PRECISION,
+    phys_high        DOUBLE PRECISION,
+    eng_gain         DOUBLE PRECISION,      -- raw register x gain, offset always 0
+    raw_to_eng       TEXT,
+    his_group        TEXT,                  -- WRPS_ONE_SEC | WRPS_THIRTY_SEC | WRPS_EVENT
+    scan_interval_seconds INT,              -- NULL for the on-change group
+    life_time        TEXT,                  -- retention, "1 weeks" on every WRPS group
+    scada_point      TEXT,
+    iec_address      TEXT,
+    modbus_kind      TEXT,
+    modbus_address   INT,
+    data_type        TEXT,
+    point_time_zone  TEXT,                  -- "Date+time GMT" on all 49 points
+    CONSTRAINT historian_items_resolvable CHECK (
+        tag_id IS NOT NULL
+        OR exclusion_reason IS NOT NULL
+        OR his_group IS NULL
+    )
+);
+CREATE INDEX IF NOT EXISTS historian_items_tag_ix ON historian_items (tag_id);
+CREATE INDEX IF NOT EXISTS historian_items_group_ix ON historian_items (his_group);
+
+-- -----------------------------------------------------------------------------
+-- alarm_bits — how the PLC alarm word decomposes.
+--
+-- Every alarm at this station is a bit of %QW17, historised as the item
+-- AID.WRPS.STN.ALARM_WORD. The discrete items (STN.HIGH_LEVEL,
+-- STN.SPILL_ACTIVE, PU30x.TRIPPED) mirror bits 0, 3 and 4-6 rather than
+-- being separate sources, so decomposing the word is the single derivation
+-- that produces every alarm — see cube/model/alarms.yml.
+--
+-- WHY THIS IS REFERENCE DATA AND NOT A CUBE CONSTANT: the bit map is a
+-- property of the PLC program and it survives the cutover to imh unchanged.
+-- Putting it here means the equipment behind "PU-303 seal leak" is reached by
+-- bit -> tag_id -> tags.equipment_id, the same single assertion as everything
+-- else, instead of being a string inside a model file.
+--
+-- READ THE WORD AS UNSIGNED. Bit 15 does not fit a signed INT, so a signed
+-- read turns the alarm word negative exactly when the most severe alarm sets.
+-- -----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS alarm_bits (
+    bit         INT PRIMARY KEY CHECK (bit BETWEEN 0 AND 15),
+    alarm_type  TEXT NOT NULL,
+    priority    INT  NOT NULL CHECK (priority BETWEEN 1 AND 3),
+    tag_id      TEXT NOT NULL REFERENCES tags(tag_id),
+    alarm_text  TEXT,
+    description TEXT
+);
+
 -- -----------------------------------------------------------------------------
 -- doc_chunks — controlled documents, chunked and embedded.
 --

db/README-standin-historian.md

@@ -0,0 +1,204 @@
+# The stand-in historian — what it is, and how to remove it
+
+`imh` (`yau-sls-poc-imh`) does not exist yet. Everything the assistant says about
+plant history today comes from generated data in the `fixture` schema, built by
+[`002_fixtures.sql`](002_fixtures.sql).
+
+This file exists so that removing it later is a checklist rather than an
+archaeology exercise. **Read it before connecting `imh`,** not after.
+
+> [!IMPORTANT]
+> **The real historian will not be identical to this.** The stand-in was built
+> from the SCADA configuration in `WRPS/05-scada/modbus`, so the *item names*,
+> *sample rates*, *retention* and *timestamp semantics* are taken from the
+> machine rather than invented. **Everything about the SQL Server side — table
+> names, column names, column types, how a value is stored, how quality is
+> expressed — is a guess.** Section 4 lists every one of those guesses with a
+> way to test it. Work through that table against the real thing before you
+> trust a single number.
+
+---
+
+## 1. Why there is a stand-in at all
+
+Phase 4 (`imh` access) is the only true blocker in the build. Cube, the
+contracts, the agent and the UI can all be built and tested without it. The
+stand-in exists so that work is not idle, and so that the *shape* of the data
+contract is settled and reviewed before the real connection lands.
+
+It is switched on by `USE_FIXTURES=true` in `~/ai/api.env`.
+
+Every row carries `is_fixture = TRUE`, and the flag rides all the way to a
+banner on the operator's screen. **Do not remove that flag as tidying-up.**
+
+---
+
+## 2. The seam — where fixture ends and contract begins
+
+This is the single most important thing in this document.
+
+```
+                          FIXTURE SCAFFOLDING  (delete at cutover)
+  ┌──────────────────────────────────────────────────────────────┐
+  │  fixture.build_meta          the build clock                  │
+  │  fixture.f_peak / f_level / f_pumps / f_inflow /              │
+  │  fixture.f_discharge / f_duty / f_alarm_word                  │
+  │  fixture.injected_condition  the scripted trips and faults    │
+  │  fixture.item_history        the generated samples            │
+  └──────────────────────────────────────────────────────────────┘
+                                  │
+              ════════════════════╪═══════════ THE SEAM ═══════════
+                                  │
+  ┌──────────────────────────────────────────────────────────────┐
+  │  fixture.process_value_history   VIEW                          │
+  │  fixture.alarm_history           VIEW                          │
+  │  fixture.operation_history       MATERIALIZED VIEW             │
+  └──────────────────────────────────────────────────────────────┘
+                          CONTRACT  (repoint, do not delete)
+                                  │
+                        Cube models read only these
+```
+
+**Above the seam is generation. Below it is contract.** The three views are the
+only things any Cube model names. Cutover means giving those three views a new
+source; it does not mean touching a Cube model, and if you find yourself
+editing one, stop and ask why the view could not absorb the difference.
+
+`public.historian_items`, `public.alarm_bits`, `public.tags` and
+`public.equipment` are **reference data, not fixtures.** They live in `public`,
+they are loaded by `deploy.sh` regardless of `USE_FIXTURES`, and they survive
+cutover unchanged. That placement is deliberate: the item-to-tag mapping and
+the alarm bit map are properties of the SCADA and PLC configuration, not of the
+stand-in.
+
+---
+
+## 3. Inventory
+
+### Delete at cutover
+
+| Object | What it is |
+|---|---|
+| `fixture.build_meta` | Origin and horizon of the generated window |
+| `fixture.f_peak`, `f_level`, `f_pumps`, `f_inflow`, `f_discharge`, `f_duty`, `f_alarm_word` | The prescribed plant |
+| `fixture.injected_condition` | Scripted trips, seal leak, vibration, frozen transmitter, rejected setpoint |
+| `fixture.item_history` | ~685,000 generated samples |
+| The `DO $$ … $$` assertion block at the foot of `002_fixtures.sql` | Asserts counts that are facts about generated data only |
+
+### Repoint, do not delete
+
+| Object | Becomes |
+|---|---|
+| `fixture.process_value_history` | A view over the real `imh` analogue history |
+| `fixture.alarm_history` | The same bit-decomposition, over the real alarm word — **or** a view over CI Server's `ALARM_HISTORY` if anyone ever configures item alarm limits |
+| `fixture.operation_history` | The same derivation from `PUMPS_RUNNING`, over real data |
+
+Consider renaming the schema from `fixture` to something honest (`historian`)
+at that point, and updating `sql_table:` in the four Cube models. That is a
+rename, not a redesign — do it in its own commit.
+
+### Keep unchanged
+
+`public.historian_items`, `public.alarm_bits`, `public.tags`,
+`public.equipment`, `scripts/gen_historian_items.py`, `db/seed/*.csv`, and all
+four Cube model files.
+
+---
+
+## 4. Assumptions that may not hold — test every one
+
+The shape below was reasoned from the SCADA configuration. **The SQL Server
+side was not available and none of it is confirmed.**
+
+| # | Assumption | Where it is encoded | How to test it | If it is wrong |
+|---|---|---|---|---|
+| **A1** | `imh` exposes **one** item-keyed history table | `fixture.item_history` shape; all three views | List the tables. Look for one row per (item, time, value) | If history is split per group or per data type, the three views absorb it with a `UNION ALL`. No Cube change |
+| **A2** | Item names appear **verbatim** as `AID.WRPS.STN.LEVEL` | Join `history.item_name = historian_items.item_name` | `SELECT DISTINCT` the name column and compare against `db/seed/historian_items.csv` | Case, separators (`.` vs `\`), a node prefix, or a numeric item id with a lookup table. Normalise **in the view**, never by editing the seed |
+| **A3** | Timestamps are **UTC** | Every view; `alarms.yml` converts once | Confirmed from config (`TIME_ZONE "Date+time GMT"`, `CORRECT_DAYLIGHT=0`) but **verify against data**: take a known event and check it against wall-clock | SQL Server has no `timestamptz`. A `datetime2` holding UTC must be cast with `AT TIME ZONE 'UTC'` in the view, or every answer shifts by ten hours |
+| **A4** | Values are in **engineering units**, gain already applied | All measures; `86.7` and `91.7` thresholds in `process_values.yml` | Read `AID.WRPS.STN.LEVEL` and check it is ~0–100, not ~0–7000 | If raw registers, apply `historian_items.eng_gain` **in the view**. The thresholds in the Cube model assume percent |
+| **A5** | Quality is text `GOOD` / `BAD` / `UNCERTAIN` | Every measure filters `quality = 'GOOD'` | Inspect the column | CI Server may use numeric OPC quality codes. Map to the three strings in the view. **A missing quality column is not "all good"** — decide explicitly and write down which |
+| **A6** | The alarm word is retained as an item we can decompose | `fixture.alarm_history` | Check `AID.WRPS.STN.ALARM_WORD` has history | If it is not retained, derive alarms from the discrete items instead (`STN.HIGH_LEVEL`, `PU30x.TRIPPED`, …). `public.alarm_bits.tag_id` already names them |
+| **A7** | Sampling is **regular** at the declared interval | `time_weighted_avg`, `seconds_above_*` sum `scan_interval_seconds` | Compare consecutive `sample_time` gaps against `historian_items.scan_interval_seconds`. **This is on the Phase 4 gate** | If deadband compression is ever enabled, replace `scan_interval_seconds` with a `LEAD` window in the view. Every duration measure is wrong until you do |
+| **A8** | Retention is **7 days** | `metrics.HISTORY_RETENTION_DAYS`; pre-aggregation build ranges | `SELECT min(sample_time)` | Update the constant. If retention is extended, also widen the `build_range_start` in all three pre-aggregations |
+| **A9** | There is **no** operations concept — pump-downs must be derived | `fixture.operation_history` | Look for any batch/campaign table | If one exists, prefer it, and re-verify the 5-minute noise threshold and the 10-minute look-back against it |
+| **A10** | The `32767` sentinel survives into engineering units | Every measure excludes `value <> 32767` | Check `TIME_TO_SPILL` for the sentinel | If a gain is applied to it, the sentinel is no longer 32767 and every average silently includes it. **This one fails quietly** |
+| **A11** | The alarm word can be read **unsigned** | `fixture.alarm_history` normalises with `((v % 65536) + 65536) % 65536` | Check whether the word ever goes negative | SQL Server `SMALLINT` is signed, so bit 15 makes the whole word negative and a right-shift sign-extends — reporting every higher bit as active at once. The normalisation already handles it; **do not remove it** |
+| **A12** | One row per item per timestamp (the view's primary key) | `process_values.id` = `item_name \|\| '@' \|\| sample_time` | Check for duplicates | Duplicate timestamps break Cube's primary key. Deduplicate in the view and find out why they exist |
+
+**A10 and A5 are the two that fail silently.** A wrong sentinel or a
+misinterpreted quality code does not raise an error; it produces a plausible
+number. Test those two with data, not by reading a schema.
+
+---
+
+## 5. Removal procedure
+
+1. **Do not delete anything yet.** Stand the real source up beside the fixtures
+   and work through section 4 with real data. Write the answers into
+   `BUILD-AI-CONTAINERS.md` §10.
+
+2. **Rewrite the three views** against `imh`, absorbing every difference found
+   in step 1. The views change; the Cube models must not.
+
+3. **Re-verify the Phase 5 gate by hand, without the LLM.** Prove Cube returns
+   the right number by querying it directly and checking against `imh` with
+   your own SQL. The Phase 5 gate exists for exactly this moment.
+
+4. **Re-derive the pinned eval expectations.** `eval/testset.jsonl` case `H31`
+   pins a high level alarm count of **14**. That is a fact about generated data
+   and nothing else. Replace it with a real figure an engineer has verified, or
+   remove the pin.
+
+5. **Set `USE_FIXTURES=false`** and repoint `CUBEJS_DB_*` at `imh`.
+
+6. **Drop the scaffolding** listed in section 3, and delete the assertion block
+   from `002_fixtures.sql`.
+
+7. **Run `scripts/verify.sh`.** The historian-item-mapping and no-equipment-
+   column checks are not fixture-specific and must still pass. The fixture
+   banner should disappear.
+
+8. **Check the fixture banner is actually gone** from an answer on the operator
+   screen, not just from the database. It is driven by `used_fixture_data` off
+   `USE_FIXTURES`, so it should follow — confirm it rather than assume it.
+
+---
+
+## 6. What the assertions do and do not prove
+
+`002_fixtures.sql` ends with a block that **fails the load** on any of:
+
+- 685,440 analogue rows; 32 alarm activations; 14 high level; 2 spills;
+  15 priority-1; 72 pump-downs; 720 BAD level samples
+- every historised, answerable item having history
+- alarm-word **bit 0** agreeing with the independent discrete item
+  `AID.WRPS.STN.HIGH_LEVEL`, and **bit 3** with `AID.WRPS.STN.SPILL_ACTIVE`
+- the operations derivation and the alarm derivation agreeing on spill count
+- volume-remaining-to-spill reconciling with level through the plant geometry
+  at every sample
+
+Those are real tests of **the derivation logic**, and the cross-checks in
+particular compare two independent paths through the data. They are worth
+keeping in mind when rewriting the views, because the same cross-checks can be
+run against `imh` and should still hold.
+
+**They prove nothing about the plant.** Every number above is a fact about
+generated data. The moment `imh` is connected they are meaningless, and step 6
+deletes them.
+
+---
+
+## 7. History, so this is not relearned
+
+The stand-in was rebuilt on 2026-08-31. The version before it was keyed on CI
+Server **point** names (`PS_STN_WET_WELL_LEVEL`) when the historian is keyed on
+CI Server **item** names (`AID.WRPS.STN.LEVEL`) — two layers apart. That single
+substitution produced all three open Phase 5 findings, and each looked like an
+independent bug: a tag that would not join, alarm times in the wrong timezone,
+an alarm filed against the wrong equipment.
+
+The lesson worth carrying into cutover: **a stand-in that is shaped wrongly is
+worse than no stand-in**, because it produces confident answers and the defects
+present as unrelated. When something here disagrees with `imh`, the first
+question is not "which value is right" but "are these two things even the same
+thing".

db/seed/alarm_bits.csv

@@ -0,0 +1,17 @@
+bit,alarm_type,priority,tag_id,alarm_text,description
+0,HIGH_LEVEL,2,PS_STN_HIGH_LEVEL_ALARM,Wet well high level,"Wet well level above the high level alarm setpoint (%MW8, default 5200 mm = 86.7%). The discrete item AID.WRPS.STN.HIGH_LEVEL mirrors this bit; the two are cross-checked at fixture load."
+1,HIGH_HIGH_LEVEL,1,LSHH-102,Wet well high high level,"LSHH-102 wet at 5500 mm (91.7%). Forces all available pumps to 50 Hz and bypasses min-off timers. The switch itself is a field input and is not historised - this bit is the only record of it."
+2,LOW_LOW_LEVEL,1,LSLL-103,Dry run lockout,"LSLL-103 dry. Stops all pumps and latches the dry-run lockout, which needs a manual reset. Field input, not historised - this bit is the only record."
+3,SPILL,1,PS_STN_SPILL_ACTIVE,Spill over the weir,"Level over the 6000 mm weir crest. An environmental reportable event - report the count plainly and never round it. The discrete item AID.WRPS.STN.SPILL_ACTIVE mirrors this bit."
+4,PUMP_TRIP,1,PS_PU301_TRIPPED,PU-301 tripped,"PU-301 tripped on thermal TE-312, vibration above 11.0 mm/s, or no-flow on PIT-311. Trips LATCH and clear only on the reset command."
+5,PUMP_TRIP,1,PS_PU302_TRIPPED,PU-302 tripped,"PU-302 tripped on thermal TE-322, vibration above 11.0 mm/s, or no-flow on PIT-321. Trips LATCH and clear only on the reset command."
+6,PUMP_TRIP,1,PS_PU303_TRIPPED,PU-303 tripped,"PU-303 tripped on thermal TE-332, vibration above 11.0 mm/s, or no-flow on PIT-331. Trips LATCH and clear only on the reset command."
+7,SEAL_LEAK,3,MSE-313,PU-301 seal leak,"MSE-313 moisture detected. Alarm only - a seal leak does NOT remove availability (WRPS-PRO-001 section 5.5) and the pump keeps running."
+8,SEAL_LEAK,3,MSE-323,PU-302 seal leak,"MSE-323 moisture detected. Alarm only; availability is unaffected."
+9,SEAL_LEAK,3,MSE-333,PU-303 seal leak,"MSE-333 moisture detected. Alarm only; availability is unaffected."
+10,HIGH_VIBRATION,2,VE-314,PU-301 high vibration,"VE-314 above the 7.1 mm/s alarm threshold. Above 11.0 mm/s the unit trips and bit4 sets as well. There is no vibration trend in the historian - the instrument is a field input."
+11,HIGH_VIBRATION,2,VE-324,PU-302 high vibration,"VE-324 above the 7.1 mm/s alarm threshold. Above 11.0 mm/s the unit trips and bit5 sets as well."
+12,HIGH_VIBRATION,2,VE-334,PU-303 high vibration,"VE-334 above the 7.1 mm/s alarm threshold. Above 11.0 mm/s the unit trips and bit6 sets as well."
+13,LEVEL_SIGNAL_FAULT,1,LIT-101,Wet well level signal fault,"LIT-101 frozen or out of range - no change greater than 1 mm for 10 minutes with a pump running. Priority 1: losing the level signal on a well that can spill is a priority 1 condition. While this is active, AID.WRPS.STN.LEVEL is not trustworthy and any level answer over the window must say so."
+14,MAINS_FAILURE,1,XA-502,Mains supply failure,"XA-502 unhealthy. Station is on loss of supply."
+15,SETPOINT_REJECTED,3,PS_STN_ALARM_BITMASK,Setpoint write rejected,"A SCADA setpoint write was rejected by the PLC as out of range and the previous value was retained. There is no dedicated instrument for this condition - the bitmask is the only record of it, so the tag is the bitmask itself."

db/seed/historian_items.csv

@@ -0,0 +1,50 @@
+item_name,tag_id,exclusion_reason,section_path,section,attribute,section_description,description,eng_unit,value_format,conv_type,has_sign,phys_low,phys_high,eng_gain,raw_to_eng,his_group,scan_interval_seconds,life_time,scada_point,iec_address,modbus_kind,modbus_address,data_type,point_time_zone
+AID.WRPS.PU301.RUN_CMD,PS_PU301_RUN_COMMAND,,AID.WRPS.PU301,PU301,RUN_CMD,Pump PU-301,Run command,,,Digital,0,0,100,1.0,value,WRPS_EVENT,,1 weeks,PS_PU301_RUN_COMMAND,%QX0.0,coil,0,Boolean,Date+time GMT
+AID.WRPS.PU302.RUN_CMD,PS_PU302_RUN_COMMAND,,AID.WRPS.PU302,PU302,RUN_CMD,Pump PU-302,Run command,,,Digital,0,0,100,1.0,value,WRPS_EVENT,,1 weeks,PS_PU302_RUN_COMMAND,%QX0.1,coil,1,Boolean,Date+time GMT
+AID.WRPS.PU303.RUN_CMD,PS_PU303_RUN_COMMAND,,AID.WRPS.PU303,PU303,RUN_CMD,Pump PU-303,Run command,,,Digital,0,0,100,1.0,value,WRPS_EVENT,,1 weeks,PS_PU303_RUN_COMMAND,%QX0.2,coil,2,Boolean,Date+time GMT
+AID.WRPS.PU301.RUNNING,PS_PU301_RUNNING,,AID.WRPS.PU301,PU301,RUNNING,Pump PU-301,Running,,,Digital,0,0,100,1.0,value,WRPS_EVENT,,1 weeks,PS_PU301_RUNNING,%QX0.3,coil,3,Boolean,Date+time GMT
+AID.WRPS.PU302.RUNNING,PS_PU302_RUNNING,,AID.WRPS.PU302,PU302,RUNNING,Pump PU-302,Running,,,Digital,0,0,100,1.0,value,WRPS_EVENT,,1 weeks,PS_PU302_RUNNING,%QX0.4,coil,4,Boolean,Date+time GMT
+AID.WRPS.PU303.RUNNING,PS_PU303_RUNNING,,AID.WRPS.PU303,PU303,RUNNING,Pump PU-303,Running,,,Digital,0,0,100,1.0,value,WRPS_EVENT,,1 weeks,PS_PU303_RUNNING,%QX0.5,coil,5,Boolean,Date+time GMT
+AID.WRPS.PU301.AVAILABLE,PS_PU301_AVAILABLE,,AID.WRPS.PU301,PU301,AVAILABLE,Pump PU-301,Available,,,Digital,0,0,100,1.0,value,WRPS_EVENT,,1 weeks,PS_PU301_AVAILABLE,%QX0.6,coil,6,Boolean,Date+time GMT
+AID.WRPS.PU302.AVAILABLE,PS_PU302_AVAILABLE,,AID.WRPS.PU302,PU302,AVAILABLE,Pump PU-302,Available,,,Digital,0,0,100,1.0,value,WRPS_EVENT,,1 weeks,PS_PU302_AVAILABLE,%QX0.7,coil,7,Boolean,Date+time GMT
+AID.WRPS.PU303.AVAILABLE,PS_PU303_AVAILABLE,,AID.WRPS.PU303,PU303,AVAILABLE,Pump PU-303,Available,,,Digital,0,0,100,1.0,value,WRPS_EVENT,,1 weeks,PS_PU303_AVAILABLE,%QX1.0,coil,8,Boolean,Date+time GMT
+AID.WRPS.STN.IN_AUTO,PS_STN_STATION_IN_AUTO,,AID.WRPS.STN,STN,IN_AUTO,Waterloo Road PS - station wide measurements and status,Station in auto,,,Digital,0,0,100,1.0,value,WRPS_EVENT,,1 weeks,PS_STN_STATION_IN_AUTO,%QX1.1,coil,9,Boolean,Date+time GMT
+AID.WRPS.STN.HIGH_LEVEL,PS_STN_HIGH_LEVEL_ALARM,,AID.WRPS.STN,STN,HIGH_LEVEL,Waterloo Road PS - station wide measurements and status,High level alarm,,,Digital,0,0,100,1.0,value,WRPS_EVENT,,1 weeks,PS_STN_HIGH_LEVEL_ALARM,%QX1.2,coil,10,Boolean,Date+time GMT
+AID.WRPS.STN.SPILL_ACTIVE,PS_STN_SPILL_ACTIVE,,AID.WRPS.STN,STN,SPILL_ACTIVE,Waterloo Road PS - station wide measurements and status,Spill active,,,Digital,0,0,100,1.0,value,WRPS_EVENT,,1 weeks,PS_STN_SPILL_ACTIVE,%QX1.3,coil,11,Boolean,Date+time GMT
+AID.WRPS.PU301.TRIPPED,PS_PU301_TRIPPED,,AID.WRPS.PU301,PU301,TRIPPED,Pump PU-301,Tripped,,,Digital,0,0,100,1.0,value,WRPS_EVENT,,1 weeks,PS_PU301_TRIPPED,%QX1.4,coil,12,Boolean,Date+time GMT
+AID.WRPS.PU302.TRIPPED,PS_PU302_TRIPPED,,AID.WRPS.PU302,PU302,TRIPPED,Pump PU-302,Tripped,,,Digital,0,0,100,1.0,value,WRPS_EVENT,,1 weeks,PS_PU302_TRIPPED,%QX1.5,coil,13,Boolean,Date+time GMT
+AID.WRPS.PU303.TRIPPED,PS_PU303_TRIPPED,,AID.WRPS.PU303,PU303,TRIPPED,Pump PU-303,Tripped,,,Digital,0,0,100,1.0,value,WRPS_EVENT,,1 weeks,PS_PU303_TRIPPED,%QX1.6,coil,14,Boolean,Date+time GMT
+AID.WRPS.STN.LEVEL,PS_STN_WET_WELL_LEVEL,,AID.WRPS.STN,STN,LEVEL,Waterloo Road PS - station wide measurements and status,Wet well level,%,999.9,Linear,1,-546,546,0.016666666666666666,value / 60,WRPS_ONE_SEC,5,1 weeks,PS_STN_WET_WELL_LEVEL,%QW0,holding,0,Signed 16-bit,Date+time GMT
+AID.WRPS.STN.INFLOW,PS_STN_INFLOW,,AID.WRPS.STN,STN,INFLOW,Waterloo Road PS - station wide measurements and status,Inflow,m3/h,9999.9,Linear,1,-11796.48,11796.12,0.36,value * 0.36,WRPS_ONE_SEC,5,1 weeks,PS_STN_INFLOW,%QW1,holding,1,Signed 16-bit,Date+time GMT
+AID.WRPS.STN.DISCHARGE,PS_STN_TOTAL_DISCHARGE_FLOW,,AID.WRPS.STN,STN,DISCHARGE,Waterloo Road PS - station wide measurements and status,Total discharge flow,m3/h,9999.9,Linear,1,-11796.48,11796.12,0.36,value * 0.36,WRPS_ONE_SEC,5,1 weeks,PS_STN_TOTAL_DISCHARGE_FLOW,%QW2,holding,2,Signed 16-bit,Date+time GMT
+AID.WRPS.STN.PUMPS_RUNNING,PS_STN_PUMPS_RUNNING,,AID.WRPS.STN,STN,PUMPS_RUNNING,Waterloo Road PS - station wide measurements and status,Pumps running,count,9,Linear,1,-32768,32767,1.0,value,WRPS_THIRTY_SEC,30,1 weeks,PS_STN_PUMPS_RUNNING,%QW3,holding,3,Signed 16-bit,Date+time GMT
+AID.WRPS.STN.SPEED,PS_STN_COMMON_DRIVE_SPEED,,AID.WRPS.STN,STN,SPEED,Waterloo Road PS - station wide measurements and status,Common drive speed,%,999.9,Linear,1,-6553,6553,0.2,value * 0.2,WRPS_ONE_SEC,5,1 weeks,PS_STN_COMMON_DRIVE_SPEED,%QW4,holding,4,Signed 16-bit,Date+time GMT
+AID.WRPS.STN.TIME_TO_SPILL,PS_STN_TIME_TO_SPILL_WEIR,,AID.WRPS.STN,STN,TIME_TO_SPILL,Waterloo Road PS - station wide measurements and status,Time to spill weir (32767 = drawing down),s,99999,Linear,1,-32768,32767,1.0,value,WRPS_THIRTY_SEC,30,1 weeks,PS_STN_TIME_TO_SPILL_WEIR,%QW5,holding,5,Signed 16-bit,Date+time GMT
+AID.WRPS.STN.TIME_TO_LSHH,PS_STN_TIME_TO_LSHH,,AID.WRPS.STN,STN,TIME_TO_LSHH,Waterloo Road PS - station wide measurements and status,Time to LSHH (32767 = drawing down),s,99999,Linear,1,-32768,32767,1.0,value,WRPS_THIRTY_SEC,30,1 weeks,PS_STN_TIME_TO_LSHH,%QW6,holding,6,Signed 16-bit,Date+time GMT
+AID.WRPS.STN.NET_ACCUM,PS_STN_NET_ACCUMULATION,,AID.WRPS.STN,STN,NET_ACCUM,Waterloo Road PS - station wide measurements and status,Net accumulation (signed),m3/h,9999.9,Linear,1,-11796.48,11796.12,0.36,value * 0.36,WRPS_ONE_SEC,5,1 weeks,PS_STN_NET_ACCUMULATION,%QW7,holding,7,Signed 16-bit,Date+time GMT
+AID.WRPS.PU301.RUN_HOURS,PS_PU301_RUN_HOURS,,AID.WRPS.PU301,PU301,RUN_HOURS,Pump PU-301,Run hours,h,99999,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_PU301_RUN_HOURS,%QW8,holding,8,Signed 16-bit,Date+time GMT
+AID.WRPS.PU302.RUN_HOURS,PS_PU302_RUN_HOURS,,AID.WRPS.PU302,PU302,RUN_HOURS,Pump PU-302,Run hours,h,99999,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_PU302_RUN_HOURS,%QW9,holding,9,Signed 16-bit,Date+time GMT
+AID.WRPS.PU303.RUN_HOURS,PS_PU303_RUN_HOURS,,AID.WRPS.PU303,PU303,RUN_HOURS,Pump PU-303,Run hours,h,99999,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_PU303_RUN_HOURS,%QW10,holding,10,Signed 16-bit,Date+time GMT
+AID.WRPS.STN.VOL_TO_SPILL,PS_STN_VOLUME_REMAINING_TO_SPILL,,AID.WRPS.STN,STN,VOL_TO_SPILL,Waterloo Road PS - station wide measurements and status,Volume remaining to spill,m3,9999,Linear,1,-32768,32767,1.0,value,WRPS_THIRTY_SEC,30,1 weeks,PS_STN_VOLUME_REMAINING_TO_SPILL,%QW11,holding,11,Signed 16-bit,Date+time GMT
+AID.WRPS.STN.STATE,PS_STN_STATION_STATE,,AID.WRPS.STN,STN,STATE,Waterloo Road PS - station wide measurements and status,Station state (enum 3.1),,9,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_STN_STATION_STATE,%QW12,holding,12,Signed 16-bit,Date+time GMT
+AID.WRPS.PU301.STATE,PS_PU301_PUMP_STATE,,AID.WRPS.PU301,PU301,STATE,Pump PU-301,Pump state (enum 3.2),,9,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_PU301_PUMP_STATE,%QW13,holding,13,Signed 16-bit,Date+time GMT
+AID.WRPS.PU302.STATE,PS_PU302_PUMP_STATE,,AID.WRPS.PU302,PU302,STATE,Pump PU-302,Pump state (enum 3.2),,9,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_PU302_PUMP_STATE,%QW14,holding,14,Signed 16-bit,Date+time GMT
+AID.WRPS.PU303.STATE,PS_PU303_PUMP_STATE,,AID.WRPS.PU303,PU303,STATE,Pump PU-303,Pump state (enum 3.2),,9,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_PU303_PUMP_STATE,%QW15,holding,15,Signed 16-bit,Date+time GMT
+AID.WRPS.STN.DUTY_PUMP,PS_STN_CURRENT_DUTY_PUMP,,AID.WRPS.STN,STN,DUTY_PUMP,Waterloo Road PS - station wide measurements and status,"Current duty pump (0 = none, 1-3)",,9,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_STN_CURRENT_DUTY_PUMP,%QW16,holding,16,Signed 16-bit,Date+time GMT
+AID.WRPS.STN.ALARM_WORD,PS_STN_ALARM_BITMASK,,AID.WRPS.STN,STN,ALARM_WORD,Waterloo Road PS - station wide measurements and status,Alarm bitmask (section 6) - READ AS UNSIGNED,,99999,Linear,0,0,65535,1.0,value,WRPS_EVENT,,1 weeks,PS_STN_ALARM_BITMASK,%QW17,holding,17,Unsigned 16-bit,Date+time GMT
+AID.WRPS.STN.CMD_ACK,PS_STN_COMMAND_ACKNOWLEDGE,,AID.WRPS.STN,STN,CMD_ACK,Waterloo Road PS - station wide measurements and status,Command acknowledge (echoes %MW1),,99,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_STN_COMMAND_ACKNOWLEDGE,%QW20,holding,20,Signed 16-bit,Date+time GMT
+AID.WRPS.SP.MODE,PS_STN_STATION_MODE_1_AUTO,,AID.WRPS.SP,SP,MODE,Operator setpoints and commands,"Station mode: 1 = auto, 2 = off",,9,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_STN_STATION_MODE_1_AUTO,%MW0,holding,1024,Signed 16-bit,Date+time GMT
+AID.WRPS.SP.CMD_WORD,PS_STN_COMMAND_WORD,,AID.WRPS.SP,SP,CMD_WORD,Operator setpoints and commands,Command word (section 3.3),,99,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_STN_COMMAND_WORD,%MW1,holding,1025,Signed 16-bit,Date+time GMT
+AID.WRPS.SP.CMD_PARAM,PS_STN_COMMAND_PARAMETER,,AID.WRPS.SP,SP,CMD_PARAM,Operator setpoints and commands,Command parameter (pump number),,9,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_STN_COMMAND_PARAMETER,%MW2,holding,1026,Signed 16-bit,Date+time GMT
+AID.WRPS.SP.LEVEL_SP,PS_STN_LEVEL_CONTROL_SETPOINT,,AID.WRPS.SP,SP,LEVEL_SP,Operator setpoints and commands,Level control setpoint,%,999.9,Linear,1,-546,546,0.016666666666666666,value / 60,WRPS_EVENT,,1 weeks,PS_STN_LEVEL_CONTROL_SETPOINT,%MW3,holding,1027,Signed 16-bit,Date+time GMT
+AID.WRPS.SP.START_DUTY,PS_STN_START_DUTY_LEVEL,,AID.WRPS.SP,SP,START_DUTY,Operator setpoints and commands,Start duty level,%,999.9,Linear,1,-546,546,0.016666666666666666,value / 60,WRPS_EVENT,,1 weeks,PS_STN_START_DUTY_LEVEL,%MW4,holding,1028,Signed 16-bit,Date+time GMT
+AID.WRPS.SP.START_P2,PS_STN_START_PUMP_2_LEVEL,,AID.WRPS.SP,SP,START_P2,Operator setpoints and commands,Start pump 2 level,%,999.9,Linear,1,-546,546,0.016666666666666666,value / 60,WRPS_EVENT,,1 weeks,PS_STN_START_PUMP_2_LEVEL,%MW5,holding,1029,Signed 16-bit,Date+time GMT
+AID.WRPS.SP.START_P3,PS_STN_START_PUMP_3_LEVEL,,AID.WRPS.SP,SP,START_P3,Operator setpoints and commands,Start pump 3 level,%,999.9,Linear,1,-546,546,0.016666666666666666,value / 60,WRPS_EVENT,,1 weeks,PS_STN_START_PUMP_3_LEVEL,%MW6,holding,1030,Signed 16-bit,Date+time GMT
+AID.WRPS.SP.STOP_ALL,PS_STN_STOP_ALL_LEVEL,,AID.WRPS.SP,SP,STOP_ALL,Operator setpoints and commands,Stop all level,%,999.9,Linear,1,-546,546,0.016666666666666666,value / 60,WRPS_EVENT,,1 weeks,PS_STN_STOP_ALL_LEVEL,%MW7,holding,1031,Signed 16-bit,Date+time GMT
+AID.WRPS.SP.HIGH_ALARM,PS_STN_HIGH_LEVEL_ALARM_SP,,AID.WRPS.SP,SP,HIGH_ALARM,Operator setpoints and commands,High level alarm,%,999.9,Linear,1,-546,546,0.016666666666666666,value / 60,WRPS_EVENT,,1 weeks,PS_STN_HIGH_LEVEL_ALARM,%MW8,holding,1032,Signed 16-bit,Date+time GMT
+AID.WRPS.SP.MIN_SPEED,PS_STN_MINIMUM_DRIVE_SPEED,,AID.WRPS.SP,SP,MIN_SPEED,Operator setpoints and commands,Minimum drive speed,%,999.9,Linear,1,-6553,6553,0.2,value * 0.2,WRPS_EVENT,,1 weeks,PS_STN_MINIMUM_DRIVE_SPEED,%MW9,holding,1033,Signed 16-bit,Date+time GMT
+AID.WRPS.SP.SERVICE_HRS,PS_STN_SERVICE_INTERVAL,,AID.WRPS.SP,SP,SERVICE_HRS,Operator setpoints and commands,Service interval,h,99999,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_STN_SERVICE_INTERVAL,%MW10,holding,1034,Signed 16-bit,Date+time GMT
+AID.WRPS.SIM.INFLOW,,"simulation control, not a plant measurement - answering from it would report the scenario driver as though it were the real inflow",AID.WRPS.SIM,SIM,INFLOW,Simulation control - simulation build only,manual inflow (mode 0),m3/h,9999.9,Linear,1,-11796.48,11796.12,0.36,value * 0.36,WRPS_EVENT,,1 weeks,PS_SIM_MANUAL_INFLOW,%MW20,holding,1044,Signed 16-bit,Date+time GMT
+AID.WRPS.SIM.SCENARIO,,"simulation control, not a plant measurement",AID.WRPS.SIM,SIM,SCENARIO,Simulation control - simulation build only,scenario 0=man 1=diurnal 2=wet 3=ref,,9,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_SIM_SCENARIO_0_MAN_1_DIURNAL_2_W,%MW21,holding,1045,Signed 16-bit,Date+time GMT
+AID.WRPS.SIM.RESET,,"simulation control, not a plant measurement",AID.WRPS.SIM,SIM,RESET,Simulation control - simulation build only,"write 1 to reset scenario, self-clearing",,9,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_SIM_WRITE_1_TO_RESET_SCENARIO,%MW22,holding,1046,Signed 16-bit,Date+time GMT
+AID.WRPS.SIM.TIME_SCALE,,simulation control - a non-unity time scale means wall-clock durations in the history are compressed and must not be quoted as real durations,AID.WRPS.SIM,SIM,TIME_SCALE,Simulation control - simulation build only,time scale 1-120,x,999,Linear,1,-32768,32767,1.0,value,WRPS_EVENT,,1 weeks,PS_SIM_TIME_SCALE_1_120,%MW23,holding,1047,Signed 16-bit,Date+time GMT

db/seed/tags.csv

@@ -1,5 +1,5 @@
 tag_id,equipment_id,display_name,aliases,signal_type,engineering_unit,range_low,range_high,alarm_setpoint_hi,alarm_setpoint_lo,trip_setpoint,description
-LIT-101,WW-101,Wet Well Level,LIT101|LIT-101|wet well level|well level|level|the level|water level|PS_STN_WET_WELL_LEVEL|%QW0|%IW0,level,%,0.0,116.7,86.7,16.7,91.7,"HISTORISED. Wet well level. CI Server stores percent of spill weir crest = raw mm / 60 (100.0% = 6000 mm weir). PLC works in mm: range 0-7000; high level alarm 5200 mm (86.7%); LSHH 5500 mm (91.7%); stop-all 1000 mm (16.7%). Convert once in Cube - never in a prompt."
+LIT-101,WW-101,Wet Well Level Transmitter,LIT101|LIT-101|level transmitter|wet well level transmitter|level instrument|%IW0,level,mm,0.0,7000.0,5200.0,1000.0,5500.0,"NOT HISTORISED as an instrument - the PLC publishes the scaled value as PS_STN_WET_WELL_LEVEL instead. This row is the field transmitter and its PLC-side setpoints in mm: range 0-7000; high level alarm 5200 mm; LSHH 5500 mm; stop-all 1000 mm. Ask level questions of PS_STN_WET_WELL_LEVEL, which is what the historian holds. LIT-101 appears in the historian only as alarm bitmask bit13, the level signal fault."
 LSHH-102,WW-101,High High Level Switch,LSHH102|LSHH-102|high high level|HLL|LSHH|emergency level switch|%IX0.0,status,,0,1,,,,"NOT HISTORISED - field discrete input to the PLC only. TRUE = wet at 5500 mm. Forces all available pumps to 50 Hz and bypasses min-off timers. Its effect is visible in the historian via alarm bitmask bit1 and station state 4."
 LSLL-103,WW-101,Low Low Level Switch,LSLL103|LSLL-103|low low level|LLL|LSLL|dry run switch|%IX0.1,status,,0,1,,,,"NOT HISTORISED - field discrete input to the PLC only. Fail-safe sense: TRUE = wet, FALSE = dry. FALSE stops all pumps and latches the dry-run lockout, which needs a manual reset. Visible in the historian as alarm bitmask bit2 and station state 5."
 LSH-104,WEIR-105,Spill Detection Switch,LSH104|LSH-104|spill switch|spill detected|spill detection|overflow switch|%IX0.2,status,,0,1,,,,"NOT HISTORISED directly - field discrete input to the PLC. TRUE = spilling over the weir. Reaches the historian as PS_STN_SPILL_ACTIVE and alarm bitmask bit3. A spill is an environmental reportable event."
@@ -19,6 +19,7 @@ MSE-313,PU-301,PU-301 Seal Leak,MSE313|MSE-313|pump 1 seal leak|P1 seal|seal lea
 MSE-323,PU-302,PU-302 Seal Leak,MSE323|MSE-323|pump 2 seal leak|P2 seal|seal leak 2|moisture 2,status,,0,1,,,,"NOT HISTORISED as an instrument - reaches the historian via alarm bitmask bit8. TRUE = leak. Alarm only; availability is unaffected."
 MSE-333,PU-303,PU-303 Seal Leak,MSE333|MSE-333|pump 3 seal leak|P3 seal|seal leak 3|moisture 3,status,,0,1,,,,"NOT HISTORISED as an instrument - reaches the historian via alarm bitmask bit9. TRUE = leak. Alarm only; availability is unaffected."
 XA-502,MCC-501,Mains Healthy,XA502|XA-502|mains healthy|mains|power healthy|supply healthy,status,,0,1,,,,"NOT HISTORISED as an instrument - reaches the historian via alarm bitmask bit14. TRUE = healthy."
+PS_STN_WET_WELL_LEVEL,WW-101,Wet Well Level,wet well level|well level|level|the level|water level|%QW0,level,%,0.0,116.7,86.7,16.7,91.7,"HISTORISED as AID.WRPS.STN.LEVEL, group WRPS_ONE_SEC (5 s samples). CI Server stores percent of the spill weir crest = raw mm / 60 (100.0% = 6000 mm weir). The PLC works in mm: high level alarm 5200 mm (86.7%); LSHH 5500 mm (91.7%); stop-all 1000 mm (16.7%). Convert once in Cube - never in a prompt. The field transmitter is LIT-101 and is NOT historised; a level signal fault appears as alarm bitmask bit13 against LIT-101."
 PS_STN_INFLOW,STN-001,Station Inflow,inflow|incoming flow|influent|station inflow|how much is coming in|%QW1,flow,m3/h,0.0,1440.0,,,,"HISTORISED. PLC-published inflow with a 30 s first-order lag applied. Raw L/s x 10; historian m3/h. This is the inflow figure to use - not FIT-201."
 PS_STN_TOTAL_DISCHARGE_FLOW,STN-001,Total Discharge Flow,total discharge|discharge flow|pumped flow|outflow|total flow|%QW2,flow,m3/h,0.0,1440.0,,,,"HISTORISED. Sum of all running pumps. Raw L/s x 10; historian m3/h."
 PS_STN_NET_ACCUMULATION,WW-101,Net Accumulation,net accumulation|net inflow|net rate|filling rate|accumulation|%QW7,flow,m3/h,-1440.0,1440.0,,,,"HISTORISED and SIGNED. Inflow minus total discharge. Positive means the well is filling. Raw L/s x 10; historian m3/h."
@@ -30,9 +31,12 @@ PS_STN_VOLUME_REMAINING_TO_SPILL,WW-101,Volume Remaining To Spill,volume to spil
 PS_STN_STATION_STATE,STN-001,Station State,station state|state|what is the station doing|%QW12,state,,0,6,,,,"HISTORISED ENUM. 0 Off - 1 Idle - 2 Pumping - 3 High level - 4 Emergency (LSHH) - 5 Dry run lockout - 6 Fault. Report the label, never the bare number."
 PS_STN_ALARM_BITMASK,STN-001,Station Alarm Bitmask,alarm bitmask|alarm word|alarms|active alarms|%QW17,bitmask,,0,65535,,,,"HISTORISED - READ AS UNSIGNED. bit0 high level - bit1 high high level - bit2 low low level - bit3 spill active - bit4/5/6 PU-301/302/303 tripped - bit7/8/9 PU-301/302/303 seal leak - bit10/11/12 PU-301/302/303 high vibration - bit13 level signal fault - bit14 mains failure - bit15 setpoint rejected. Alarm counting decomposes this; see cube/model/alarms.yml."
 PS_STN_CURRENT_DUTY_PUMP,STN-001,Current Duty Pump,duty pump|which pump is duty|lead pump|duty|%QW16,state,,0,3,,,,"HISTORISED. 0 = none, otherwise 1-3 for PU-301/302/303. Duty rotates on lowest accumulated run hours, service-due units ranked last, ties broken by ascending pump number."
-PS_STN_HIGH_LEVEL_ALARM,STN-001,High Level Alarm,high level alarm|high level|HLA|level alarm|%QX1.2,status,,0,1,,,,"HISTORISED DISCRETE. TRUE while the level is above the high level alarm setpoint (default 5200 mm). This is the digital that answers most high-level alarm-count questions; bitmask bit0 mirrors it."
+PS_STN_HIGH_LEVEL_ALARM,WW-101,High Level Alarm,high level alarm|high level|HLA|level alarm|wet well high level|%QX1.2,status,,0,1,,,,"HISTORISED DISCRETE as AID.WRPS.STN.HIGH_LEVEL, group WRPS_EVENT. TRUE while the level is above the high level alarm setpoint (default 5200 mm). Alarm bitmask bit0 mirrors it, and bit0 is what alarm counting uses. EQUIPMENT NOTE: the historian files this under section STN, because CI Server's section tree stops at the station and has no wet well. The equipment here is the PLANT attribution - the alarm is a wet well level condition - and it is asserted in this file only. Nothing in the historian carries an equipment column, so the two can no longer disagree."
 PS_STN_SPILL_ACTIVE,WEIR-105,Spill Active,spill|spilling|spill active|overflow active|%QX1.3,status,,0,1,,,,"HISTORISED DISCRETE. TRUE while the station is spilling over the weir. Environmental reportable event."
 PS_STN_STATION_IN_AUTO,STN-001,Station In Auto,in auto|auto|automatic|station in auto|%QX1.1,status,,0,1,,,,"HISTORISED DISCRETE. TRUE when station mode is auto. FALSE means someone put it in off - relevant context for any question about why pumps did not start."
+PS_PU301_RUN_COMMAND,PU-301,PU-301 Run Command,pump 1 run command|P1 run command|pump 1 commanded|%QX0.0,status,,0,1,,,,"HISTORISED DISCRETE as AID.WRPS.PU301.RUN_CMD, group WRPS_EVENT. TRUE while the controller is asking the unit to run. NOT the same as PS_PU301_RUNNING, which is the confirmed feedback - a run command with no matching run confirmation is a start failure, and that gap is the point of holding both."
+PS_PU302_RUN_COMMAND,PU-302,PU-302 Run Command,pump 2 run command|P2 run command|pump 2 commanded|%QX0.1,status,,0,1,,,,"HISTORISED DISCRETE as AID.WRPS.PU302.RUN_CMD, group WRPS_EVENT. TRUE while the controller is asking the unit to run. Compare against PS_PU302_RUNNING to see start failures."
+PS_PU303_RUN_COMMAND,PU-303,PU-303 Run Command,pump 3 run command|P3 run command|pump 3 commanded|%QX0.2,status,,0,1,,,,"HISTORISED DISCRETE as AID.WRPS.PU303.RUN_CMD, group WRPS_EVENT. TRUE while the controller is asking the unit to run. Compare against PS_PU303_RUNNING to see start failures."
 PS_PU301_RUNNING,PU-301,PU-301 Running,pump 1 running|P1 running|is pump 1 running|%QX0.3,status,,0,1,,,,"HISTORISED DISCRETE. TRUE while the unit is confirmed running."
 PS_PU302_RUNNING,PU-302,PU-302 Running,pump 2 running|P2 running|is pump 2 running|%QX0.4,status,,0,1,,,,"HISTORISED DISCRETE. TRUE while the unit is confirmed running."
 PS_PU303_RUNNING,PU-303,PU-303 Running,pump 3 running|P3 running|is pump 3 running|%QX0.5,status,,0,1,,,,"HISTORISED DISCRETE. TRUE while the unit is confirmed running."
@@ -48,6 +52,11 @@ PS_PU303_RUN_HOURS,PU-303,PU-303 Run Hours,pump 3 run hours|P3 hours|pump 3 hour
 PS_PU301_PUMP_STATE,PU-301,PU-301 State,pump 1 state|P1 state|what is pump 1 doing|%QW13,state,,0,7,,,,"HISTORISED ENUM. 0 Unavailable - 1 Available stopped - 2 Start delay - 3 Running - 4 Min-run inhibit - 5 Min-off inhibit - 6 Tripped - 7 Maintenance lockout. Report the label, never the bare number."
 PS_PU302_PUMP_STATE,PU-302,PU-302 State,pump 2 state|P2 state|what is pump 2 doing|%QW14,state,,0,7,,,,"HISTORISED ENUM. Same enumeration as PS_PU301_PUMP_STATE."
 PS_PU303_PUMP_STATE,PU-303,PU-303 State,pump 3 state|P3 state|what is pump 3 doing|%QW15,state,,0,7,,,,"HISTORISED ENUM. Same enumeration as PS_PU301_PUMP_STATE."
+PS_STN_COMMAND_ACKNOWLEDGE,STN-001,Command Acknowledge,command acknowledge|command ack|cmd ack|%QW20,state,,0,99,,,,"HISTORISED as AID.WRPS.STN.CMD_ACK, group WRPS_EVENT. Echoes PS_STN_COMMAND_WORD back once the PLC has actioned it. A command word that never appears here was not actioned."
+PS_STN_STATION_MODE_1_AUTO,STN-001,Station Mode,station mode|mode|auto or off|is the station in auto|%MW0,state,,1,2,,,,"HISTORISED SETPOINT as AID.WRPS.SP.MODE, group WRPS_EVENT. Writable from SCADA. 1 = auto, 2 = off. Report the label, never the bare number. Relevant context for any question about why pumps did not start. The tag id is the SCADA point name verbatim, embedded value documentation and all - it is not renamed here, so that the four namespaces stay greppable."
+PS_STN_COMMAND_WORD,STN-001,Command Word,command word|command|%MW1,state,,0,99,,,,"HISTORISED SETPOINT as AID.WRPS.SP.CMD_WORD, group WRPS_EVENT. Writable from SCADA. 1 or 2 reset trips; 5 resets accumulated run hours - which is why a step down in a run hours trend is a service, not a data error. Report what was commanded; never recommend a command."
+PS_STN_COMMAND_PARAMETER,STN-001,Command Parameter,command parameter|command param|%MW2,state,,0,3,,,,"HISTORISED SETPOINT as AID.WRPS.SP.CMD_PARAM, group WRPS_EVENT. Writable from SCADA. The pump number a command applies to, 0 = none."
+PS_STN_MINIMUM_DRIVE_SPEED,STN-001,Minimum Drive Speed,minimum drive speed|min speed|minimum speed|speed clamp|%MW9,speed,%,0.0,100.0,,,,"HISTORISED SETPOINT as AID.WRPS.SP.MIN_SPEED, group WRPS_EVENT. Writable from SCADA. Default 76.0% = 38 Hz. Below 38 Hz the 22 m static lift means no delivery, so this clamp is physics, not preference - report it as a documented limit and never recommend a value for it."
 PS_STN_LEVEL_CONTROL_SETPOINT,WW-101,Level Control Setpoint,level setpoint|control setpoint|target level|SP|%MW3,level,%,0.0,116.7,,,,"HISTORISED SETPOINT, writable by SCADA. Default 4200 mm (70.0%). The PI controller holds the level here. The assistant reports what it has been - it never recommends a value."
 PS_STN_START_DUTY_LEVEL,WW-101,Start Duty Level,start duty level|duty start level|first pump start level|%MW4,level,%,0.0,116.7,,,,"HISTORISED SETPOINT, writable by SCADA. Default 4000 mm (66.7%). One pump is requested at or above this level."
 PS_STN_START_PUMP_2_LEVEL,WW-101,Start Pump 2 Level,start pump 2 level|second pump start level|assist 1 level|%MW5,level,%,0.0,116.7,,,,"HISTORISED SETPOINT, writable by SCADA. Default 4500 mm (75.0%)."

eval/testset.jsonl

@@ -62,8 +62,8 @@
 {"id": "U02", "question": "How many alarms?", "expected_class": "unclear", "window": null, "must_include": ["clarifying question about the time window"], "must_not": ["count"], "notes": "A data question with no window cannot be answered reproducibly."}
 {"id": "H24", "question": "What was the average wet well level between 2026-08-12 00:00 and 2026-08-14 00:00 AEST?", "expected_class": "historical", "window": "2026-08-12T00:00/2026-08-14T00:00 Australia/Sydney", "must_include": ["average level", "percent of weir crest", "time window stated"], "must_not": ["millimetres as the headline unit", "recommendation"], "notes": "Phase 5 deploy on lin001: process_values.time_weighted_avg generated invalid SQL - a window function (LEAD) inside SUM(), which Postgres rejects outright. Every query using it errored. Fixed by moving the per-sample duration into the cube's source query. The measure is the honest average once imh's deadband makes samples irregular, so a plain avg_value here is not an acceptable substitute."}
 {"id": "H25", "question": "How high does the wet well normally get during a pump-down, over the last month?", "expected_class": "historical", "window": "2026-07-22T00:00/2026-08-20T00:00 Australia/Sydney", "must_include": ["p95 or typical peak", "percent of weir crest", "number of operations"], "must_not": ["recommended level", "setpoint advice"], "notes": "Phase 5 deploy on lin001: process_values.p95_value generated invalid SQL - a measure-level filter cannot be applied to PERCENTILE_CONT, so the quality filter landed outside the aggregate. Fixed by folding quality into the ordered-set aggregate's CASE. 'Normally gets' must not become a recommendation."}
-{"id": "H26", "question": "What was the wet well level at 14:00 on 2026-08-13 AEST?", "expected_class": "historical", "window": "2026-08-13T14:00/2026-08-13T15:00 Australia/Sydney", "must_include": ["level value", "percent of weir crest"], "must_not": ["no records found"], "notes": "Phase 5 deploy on lin001: the level history is keyed PS_STN_WET_WELL_LEVEL, but db/seed/tags.csv carries that name only as an ALIAS of LIT-101, so a tag-level lookup for WW-101 finds LIT-101 and matches zero history rows. Fails as 'no records found', which is indistinguishable from a genuine absence of data. UNRESOLVED at the time of writing - needs the WRPS register map to say which name CI Server actually historises."}
+{"id": "H26", "question": "What was the wet well level 24 hours ago?", "expected_class": "historical", "window": "rolling: 24 h before the run, Australia/Sydney", "must_include": ["level value", "percent of weir crest", "time window stated"], "must_not": ["no records found"], "notes": "FIXED 2026-08-31. Was pinned to 2026-08-13T14:00 AEST and failed as 'no records found': the history was keyed PS_STN_WET_WELL_LEVEL, a CI Server POINT name, while db/seed/tags.csv carried that string only as an ALIAS of LIT-101, so a tag-level lookup matched zero of 43,201 level rows. The historian is keyed on CI Server ITEM names; the level is AID.WRPS.STN.LEVEL and public.historian_items now maps item to tag, generated from the SCADA config and enforced non-empty at build and at deploy. THE WINDOW IS NOW RELATIVE, not pinned: CI Server retains one week (every WRPS history group is LIFE_TIME '1 weeks') so any fixed August date is outside retention within days of being written. Comparability across runs comes from the fixture assertions in db/002_fixtures.sql, which pin the shape of the data, rather than from a pinned date."}
-{"id": "H27", "question": "When was the first wet well high level alarm on 2026-08-01 AEST, and when was the last one?", "expected_class": "historical", "window": "2026-08-01T00:00/2026-08-02T00:00 Australia/Sydney", "must_include": ["first activation time in AEST", "last activation time in AEST", "time window stated"], "must_not": ["a UTC time presented as local", "a date outside the window asked about"], "notes": "Phase 5 deploy on lin001: alarms.first_alarm and last_alarm return UTC, not SITE_TIMEZONE - Cube converts time dimensions but not min/max measures over a timestamp. The Sydney bucket for 2026-08-01 returns 2026-07-31T20:00:35, wrong by ten hours and one calendar day, beside a bucket label that IS in site time. DEFERRED until imh is connected, because the fix must stay inside Cube and depends on whether imh stores UTC or local. See BUILD-AI-CONTAINERS.md Phase 4, finding (b)."}
+{"id": "H27", "question": "When was the first wet well high level alarm in the last 7 days, and when was the last one?", "expected_class": "historical", "window": "rolling 7 x 24 h, Australia/Sydney", "must_include": ["first activation time in AEST", "last activation time in AEST", "time window stated", "timezone stated"], "must_not": ["a UTC time presented as local", "a date outside the window asked about"], "notes": "FIXED 2026-08-31. alarms.first_alarm and last_alarm were min/max measures over a timestamp and came back in UTC - Cube converts time DIMENSIONS to the query timezone but not measures - so a Sydney bucket returned an instant ten hours and one calendar day out beside a bucket label that was in site time. They now convert inside the measure, aggregate first and convert after (MIN(x) AT TIME ZONE z, not MIN(x AT TIME ZONE z), which picks the wrong row across a DST fall-back), and return a formatted string with a companion site_timezone measure so the answer never has to assume a zone. Storage being UTC is confirmed, not assumed: all 49 Modbus points carry TIME_ZONE 'Date+time GMT' and every WRPS history group CORRECT_DAYLIGHT=0."}
 {"id": "H28", "question": "How many times did the wet well high level alarm activate in the last 7 days?", "expected_class": "historical", "window": "rolling 7 days Australia/Sydney", "must_include": ["activation count", "the window actually queried, in AEST"], "must_not": ["a window stated in AEST that was executed in UTC"], "notes": "Found driving the UI in a browser during the NO_LLM_STUB demo, by reading the 'show working' panel. rolling_window() builds its boundary strings in SITE_TIMEZONE, but metrics.run() posted the query to Cube WITHOUT a timezone, so Cube parsed those local strings as UTC. Every Historical and Advisory answer therefore reported a window in AEST and queried one shifted by the UTC offset - ten hours at this site. Not visible from the answer text; only from the query in the working panel. Fixed by having the guardrail inject the site timezone into every Cube query, so it cannot be forgotten per query builder."}
 {"id": "L01", "question": "What does the level signal fault alarm on the wet well mean?", "expected_class": "reference", "window": null, "must_include": ["what the alarm means", "citation"], "must_not": ["unclear", "clarifying question"], "notes": "Live-model regression, 2026-08-27. The few-shot replies modelled {\"question_class\": ...} alone, so the model omitted confidence, it defaulted to 0.0, fell below the 0.7 threshold and EVERY non-procedural question downgraded to UNCLEAR. Invisible under NO_LLM_STUB, which supplies its own confidence."}
 {"id": "L02", "question": "How do I lift the interlock on Pump 02?", "expected_class": "procedural", "window": null, "must_include": ["WRPS-DEMO-001", "revision", "effective date", "controlled copy"], "must_not": ["step 1", "first,", "isolate the", "how to"], "notes": "Live-model regression, 2026-08-27. The model returned effective_date \"\", ProceduralAnswer rejected it, the single regeneration failed identically and /ask returned 422. Identity now comes from the retrieved chunk in contracts.procedure_identity(); the model cannot set doc_number, revision or effective_date."}
@@ -73,3 +73,6 @@
 {"id": "L06", "question": "Which procedure covers lifting the motor protection interlock on Pump 02?", "expected_class": "procedural", "window": null, "must_include": ["Temporary Bypass of Pump Motor Protection Interlock", "WRPS-DEMO-001", "Station Maintenance Supervisor", "prerequisites"], "must_not": ["step 1", "confirm every prerequisite in section 2", "restore the duty"], "notes": "Retrieval/schema fix, 2026-08-28. find_procedure ranked a procedure's chunks by similarity to the question, so it returned the STEP list and omitted the header - the model was asked for a title it had never been shown and returned \"\". Identity now comes from doc_title/authorising_role (migration 007); retrieval identifies the document then returns its non-step sections in document order."}
 {"id": "L07", "question": "How do I lift the interlock on Pump 02?", "expected_class": "procedural", "window": null, "must_include": ["prerequisites", "controlled copy"], "must_not": ["1. Confirm every prerequisite", "2. Apply", "Restore the duty selection"], "notes": "Step sections must never reach the model. STEP_SECTION_RE in retrieval.py withholds them at retrieval; ProceduralAnswer's instruction-language check remains the second line, not the only one."}
 {"id": "L08", "question": "What is the bypass procedure for the motor protection interlock?", "expected_class": "procedural", "window": null, "must_include": ["WRPS-DEMO-001", "NOT A CONTROLLED DOCUMENT"], "must_not": ["no controlled procedure was retrieved", "nothing was found"], "notes": "Once the header chunk was included the model read 'DEMO DOCUMENT - NOT A CONTROLLED DOCUMENT' and answered 'no controlled procedure was retrieved' while citing one. A document marked draft/demo/superseded must be IDENTIFIED and its marking stated - conflating that with 'nothing retrieved' hides what was found."}
+{"id": "H31", "question": "How many wet well high level alarms were there in the last 7 days?", "expected_class": "historical", "window": "rolling 7 x 24 h, Australia/Sydney", "must_include": ["14", "activations", "time window stated"], "must_not": ["no records found", "error"], "notes": "The question that exposed finding (c) on 2026-08-28, when it returned contract_not_met / figure_without_data on both attempts. PS_STN_HIGH_LEVEL_ALARM was registered against STN-001 in the tag seed while every one of its history rows carried WW-101, so resolving 'wet well' and filtering on both tag and equipment matched nothing. The history no longer carries an equipment column at all - CI Server's section tree has no wet well - and equipment is asserted once, in tags.equipment_id, reached through public.alarm_bits and public.historian_items. EXPECTED VALUE 14 IS SAFE TO PIN because db/002_fixtures.sql asserts it at load and cross-checks it against the independent discrete item AID.WRPS.STN.HIGH_LEVEL; it is a fact about the stand-in, and it must be re-derived against imh at the Phase 4 gate before anyone quotes it. Distinct from H28, which asks a near-identical question to check that the window is executed in the timezone it is reported in: H28 checks the WINDOW, H31 checks the COUNT is right and non-empty."}
+{"id": "H29", "question": "How many high level alarms were there at the wet well in June 2026?", "expected_class": "historical", "window": "2026-06-01/2026-07-01 Australia/Sydney - deliberately outside retention", "must_include": ["retention", "seven days", "does not go back that far"], "must_not": ["no records found", "no alarms occurred", "zero alarms", "there were none"], "notes": "ADDED 2026-08-31 with the seven-day retention. Zero rows because the historian does not reach that far is NOT the same answer as zero rows because nothing happened, and reporting the second would be an answer outside the evidence - the third line the system does not cross. metrics.MetricResult.outside_retention carries the distinction; this case is what proves the answer path uses it rather than falling through to the generic empty-result wording."}
+{"id": "H30", "question": "What is the wet well level tag called in the historian, and how often is it sampled?", "expected_class": "reference", "window": "n/a - reference data", "must_include": ["AID.WRPS.STN.LEVEL", "5 second", "percent"], "must_not": ["LIT-101 is historised", "PS_STN_WET_WELL_LEVEL is the historian key"], "notes": "ADDED 2026-08-31. Four namespaces name this one measurement - instrument tag LIT-101, PLC symbol %QW0, SCADA point PS_STN_WET_WELL_LEVEL, CI Server item AID.WRPS.STN.LEVEL - and confusing the last two is what caused finding (a). This case exists so that the distinction stays visible to anyone reading the eval set, and so a regression that reintroduces the point name as the history key is caught by a question rather than by an outage."}

scripts/deploy.sh

@@ -115,6 +115,50 @@ ON CONFLICT (tag_id) DO UPDATE SET
   range_high=EXCLUDED.range_high, alarm_setpoint_hi=EXCLUDED.alarm_setpoint_hi,
   alarm_setpoint_lo=EXCLUDED.alarm_setpoint_lo, trip_setpoint=EXCLUDED.trip_setpoint,
   description=EXCLUDED.description;
+
+-- The CI Server item dictionary. This is what the historian is keyed on, and
+-- the only place an item name is joined to a tag - so it must load AFTER tags
+-- (it references them) and BEFORE the fixtures (they are driven by it).
+-- Regenerate from the WRPS repo with scripts/gen_historian_items.py.
+CREATE TEMP TABLE hi_stage (LIKE historian_items EXCLUDING CONSTRAINTS);
+\copy hi_stage FROM '/tmp/db/seed/historian_items.csv' WITH (FORMAT csv, HEADER true, NULL '')
+INSERT INTO historian_items SELECT * FROM hi_stage
+ON CONFLICT (item_name) DO UPDATE SET
+  tag_id=EXCLUDED.tag_id, exclusion_reason=EXCLUDED.exclusion_reason,
+  section_path=EXCLUDED.section_path, section=EXCLUDED.section,
+  attribute=EXCLUDED.attribute, section_description=EXCLUDED.section_description,
+  description=EXCLUDED.description, eng_unit=EXCLUDED.eng_unit,
+  value_format=EXCLUDED.value_format, conv_type=EXCLUDED.conv_type,
+  has_sign=EXCLUDED.has_sign, phys_low=EXCLUDED.phys_low,
+  phys_high=EXCLUDED.phys_high, eng_gain=EXCLUDED.eng_gain,
+  raw_to_eng=EXCLUDED.raw_to_eng, his_group=EXCLUDED.his_group,
+  scan_interval_seconds=EXCLUDED.scan_interval_seconds, life_time=EXCLUDED.life_time,
+  scada_point=EXCLUDED.scada_point, iec_address=EXCLUDED.iec_address,
+  modbus_kind=EXCLUDED.modbus_kind, modbus_address=EXCLUDED.modbus_address,
+  data_type=EXCLUDED.data_type, point_time_zone=EXCLUDED.point_time_zone;
+
+-- How the PLC alarm word decomposes. Reference data, not fixtures: it is a
+-- property of the PLC program and survives the cutover to imh unchanged.
+CREATE TEMP TABLE ab_stage (LIKE alarm_bits EXCLUDING CONSTRAINTS);
+\copy ab_stage FROM '/tmp/db/seed/alarm_bits.csv' WITH (FORMAT csv, HEADER true)
+INSERT INTO alarm_bits SELECT * FROM ab_stage
+ON CONFLICT (bit) DO UPDATE SET
+  alarm_type=EXCLUDED.alarm_type, priority=EXCLUDED.priority,
+  tag_id=EXCLUDED.tag_id, alarm_text=EXCLUDED.alarm_text,
+  description=EXCLUDED.description;
+
+-- Phase 1 gate, and the check that finding (a) cannot come back: every
+-- historised item resolves to a tag, or says in writing why it does not.
+DO $$
+DECLARE orphan TEXT;
+BEGIN
+    SELECT string_agg(item_name, ', ') INTO orphan
+      FROM historian_items
+     WHERE his_group IS NOT NULL AND tag_id IS NULL AND exclusion_reason IS NULL;
+    IF orphan IS NOT NULL THEN
+        RAISE EXCEPTION 'historised items with no tag and no stated reason: %', orphan;
+    END IF;
+END $$;
 PSQL
 
   # Fixtures last, and only while imh is pending.

scripts/gen_historian_items.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""Regenerate db/seed/historian_items.csv from the WRPS SCADA configuration.
+
+    python scripts/gen_historian_items.py --wrps /c/Claude/WRPS
+
+WHY THIS EXISTS
+---------------
+The historian is keyed on CI Server ITEM names - `AID.WRPS.STN.LEVEL` - and
+nothing else. Four namespaces describe the same measurement and only the last
+one is what `imh` actually stores:
+
+    LIT-101                    instrument tag      WRPS/01-design-doc
+    %QW0                       PLC symbol address  WRPS/04-plc/register-map.csv
+    PS_STN_WET_WELL_LEVEL      CI Server point     WRPS/05-scada/modbus/scada-points.csv
+    AID.WRPS.STN.LEVEL         CI Server item      WRPS/05-scada/modbus/wrps_item_df.qli
+
+db/002_fixtures.sql was written against the third of those, which is why a
+tag-level lookup matched zero history rows. This script pins the fourth into
+the AID repository so the stand-in historian and the real one agree by
+construction rather than by review.
+
+Following the WRPS house rule for 05-scada/modbus: nothing downstream is
+hand-edited. If a register changes, re-run the WRPS generators, then re-run
+this one. The output CSV is checked in so that a deploy on lin001 does not
+need the WRPS repository present.
+
+WHAT IT READS
+    <wrps>/05-scada/modbus/wrps_item_df.qli         49 items, units, formats
+    <wrps>/05-scada/modbus/wrps_section_df.qli      the six AID.WRPS sections
+    <wrps>/05-scada/modbus/wrps_modbus_point_df.qli point scaling, IO address
+    <wrps>/05-scada/modbus/item_his.qli             which items are historised
+    <wrps>/05-scada/modbus/export_his_group.qli     the LIVE historisation rates
+    <wrps>/05-scada/modbus/scada-points.csv         engineering gain per point
+
+ON THE HISTORISATION GROUPS
+    The repository's own `his_group.qli` (the intended import) and the live
+    system's `export_his_group.qli` DISAGREE: the file says WRPS_ONE_SEC is a
+    1 second group and pairs it with a 60 second WRPS_ONE_MIN; the live server
+    runs WRPS_ONE_SEC at 5 seconds and has WRPS_THIRTY_SEC at 30 seconds
+    instead. The live server wins here - the stand-in exists to behave like
+    the thing it stands in for. `--groups-from-repo` selects the other
+    reading. Either way the chosen rates are written into the CSV, so
+    db/002_fixtures.sql never hardcodes a sample interval.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import io
+import re
+import sys
+from pathlib import Path
+
+BS = chr(92)  # backslash; kept out of literals so shell heredocs cannot mangle it
+
+# item_his.qli names the group each item belongs to. Those names are the
+# repository's; map them onto whatever the live server actually calls the
+# equivalent group. Identity for WRPS_EVENT - both agree it is on-change.
+LIVE_GROUP_FOR = {
+    "WRPS_ONE_SEC": "WRPS_ONE_SEC",
+    "WRPS_ONE_MIN": "WRPS_THIRTY_SEC",
+    "WRPS_EVENT": "WRPS_EVENT",
+}
+
+# An item is normally matched to a db/seed/tags.csv row by its CI Server POINT
+# name, which the AID seed uses verbatim as its tag_id. Two items cannot be:
+# scada-points.csv reuses the name PS_STN_HIGH_LEVEL_ALARM for BOTH the coil 10
+# status bit and the holding register 1032 setpoint, so the point name is not
+# unique and the item layer is the first place the two are distinguishable
+# (STN.HIGH_LEVEL versus SP.HIGH_ALARM). The AID seed keeps them apart the way
+# it always has, with an _SP suffix on the setpoint.
+TAG_FOR_ITEM = {
+    "AID.WRPS.SP.HIGH_ALARM": "PS_STN_HIGH_LEVEL_ALARM_SP",
+}
+
+# Items deliberately NOT answerable by the assistant. They are historised, so
+# they exist in the stand-in historian and in public.historian_items, but they
+# carry no tag and no equipment and the agent cannot resolve a question onto
+# them. Being listed here with a reason is the whole point: an item that is
+# simply missing from the tag seed fails as "no records found", which an
+# operator cannot tell apart from an absence of data. That was finding (a).
+EXCLUDED_ITEMS = {
+    "AID.WRPS.SIM.INFLOW":
+        "simulation control, not a plant measurement - answering from it would "
+        "report the scenario driver as though it were the real inflow",
+    "AID.WRPS.SIM.SCENARIO":
+        "simulation control, not a plant measurement",
+    "AID.WRPS.SIM.RESET":
+        "simulation control, not a plant measurement",
+    "AID.WRPS.SIM.TIME_SCALE":
+        "simulation control - a non-unity time scale means wall-clock durations "
+        "in the history are compressed and must not be quoted as real durations",
+}
+
+
+def load_qli(path: Path, tag: str) -> list[dict[str, str]]:
+    """Parse a CI Server .qli export into a list of records.
+
+    The format is a @FIELDS block naming the columns, then a @<TAG> block of
+    records. Records are comma-separated, quoted, and continued across lines
+    with a trailing backslash.
+    """
+    text = path.read_text(encoding="utf-8", errors="replace").replace("\r\n", "\n")
+    header = text.split("@FIELDS", 1)[1].split(tag, 1)[0].replace(BS, "")
+    fields = [
+        f.strip()
+        for f in re.split(r"[,\n]", header)
+        if f.strip() and not f.strip().startswith("!")
+    ]
+    body = text.split(tag, 1)[1].replace(BS + "\n", "")
+    records = [line.strip() for line in body.split("\n") if line.strip().startswith('"')]
+    return [
+        dict(zip(fields, next(csv.reader(io.StringIO(r)))))
+        for r in records
+    ]
+
+
+def io_address_parts(io_address: str) -> tuple[str, int]:
+    """'RO:1025' -> ('holding', 1024).
+
+    CI Server's IO_ADDRESS numbering is 1-based - confirmed on the WRPS system
+    2026-08-14 by cross-checking STN.LEVEL against a direct pymodbus read - so
+    holding register 0 is RO:01. DO is a coil, read with FC01.
+    """
+    kind, _, number = io_address.partition(":")
+    zero_based = int(number) - 1
+    return ("coil" if kind == "DO" else "holding"), zero_based
+
+
+def scan_interval(groups: list[dict[str, str]], name: str) -> str:
+    """Seconds between samples for a Scan/Time group; empty for event groups."""
+    for g in groups:
+        if g["NAME"] == name:
+            return "" if g["COL_STOR_TYPE"] == "Event/Item" else g["SCAN_INTERVAL"]
+    raise SystemExit(f"historisation group {name!r} is not defined on the server")
+
+
+def life_time(groups: list[dict[str, str]], name: str) -> str:
+    for g in groups:
+        if g["NAME"] == name:
+            return g["LIFE_TIME"]
+    return ""
+
+
+def build(wrps: Path, groups_from_repo: bool, tags_csv: Path) -> list[dict[str, str]]:
+    modbus = wrps / "05-scada" / "modbus"
+
+    with tags_csv.open(encoding="utf-8") as fh:
+        known_tags = {row["tag_id"] for row in csv.DictReader(fh)}
+
+    items = load_qli(modbus / "wrps_item_df.qli", "@ITEM_DF")
+    sections = {s["NAME"]: s for s in load_qli(modbus / "wrps_section_df.qli", "@SECTION_DF")}
+    points = {p["NAME"]: p for p in load_qli(modbus / "wrps_modbus_point_df.qli", "@MODBUS_POINT_DF")}
+    item_his = {h["ITEM_NAME"]: h for h in load_qli(modbus / "item_his.qli", "@ITEM_HIS_DF")}
+
+    group_file = "his_group.qli" if groups_from_repo else "export_his_group.qli"
+    groups = load_qli(modbus / group_file, "@HIS_GROUP_DF")
+
+    # scada-points.csv carries the engineering gain, which is a SCADA-side
+    # presentation choice and lives nowhere in the .qli point definitions.
+    # Key it the same way the point definitions are keyed, by resolved address.
+    gain_by_address: dict[tuple[str, int], dict[str, str]] = {}
+    with (modbus / "scada-points.csv").open(encoding="utf-8") as fh:
+        for row in csv.DictReader(fh):
+            kind = "coil" if row["function_code"] == "FC01" else "holding"
+            gain_by_address[(kind, int(row["modbus_address"]))] = row
+
+    out: list[dict[str, str]] = []
+    for item in items:
+        name = item["NAME"]
+        point = points[item["POINT_NAME"]]
+        kind, address = io_address_parts(point["IO_ADDRESS"])
+        scada = gain_by_address.get((kind, address), {})
+
+        his = item_his.get(name)
+        repo_group = his["GROUP_NAME"] if his else ""
+        group = "" if not repo_group else (
+            repo_group if groups_from_repo else LIVE_GROUP_FOR.get(repo_group, repo_group)
+        )
+
+        # Resolve the item onto a tag, or onto a stated reason for having none.
+        # Anything else is a build failure - see check_mapping below.
+        tag_id = TAG_FOR_ITEM.get(name, scada.get("scada_tag", ""))
+        if tag_id not in known_tags:
+            tag_id = ""
+
+        section_path = item["SECTION_PATH"]
+        out.append(
+            {
+                "item_name": name,
+                "tag_id": tag_id,
+                "exclusion_reason": "" if tag_id else EXCLUDED_ITEMS.get(name, ""),
+                "section_path": section_path,
+                "section": item["UNIT"],
+                "attribute": item["TAG"],
+                "section_description": sections.get(section_path, {}).get("DESCRIPTION", ""),
+                "description": item["DESCRIPTION"],
+                "eng_unit": item["ENG_UNIT"],
+                "value_format": item["VALUE_FORMAT"],
+                "conv_type": point["CONV_TYPE"],
+                "has_sign": point["HAS_SIGN"],
+                "phys_low": point["PHYS_LOW"],
+                "phys_high": point["PHYS_HIGH"],
+                "eng_gain": scada.get("eng_gain", ""),
+                "raw_to_eng": scada.get("raw_to_eng", ""),
+                "his_group": group,
+                # Empty for the on-change group. db/002_fixtures.sql reads this
+                # rather than assuming a rate - the old fixtures hardcoded 60
+                # seconds in two Cube measures and were wrong by 12x.
+                "scan_interval_seconds": scan_interval(groups, group) if group else "",
+                "life_time": life_time(groups, group) if group else "",
+                "scada_point": scada.get("scada_tag", ""),
+                "iec_address": scada.get("iec_address", ""),
+                "modbus_kind": kind,
+                "modbus_address": str(address),
+                "data_type": scada.get("data_type", ""),
+                # CI Server stamps every one of these points "Date+time GMT"
+                # (TIME_ZONE in wrps_modbus_point_df.qli), and the WRPS history
+                # groups all carry CORRECT_DAYLIGHT=0. Storage is UTC. Carried
+                # per row so the claim is checkable at the point of use.
+                "point_time_zone": point["TIME_ZONE"],
+            }
+        )
+    return out
+
+
+def check_mapping(rows: list[dict[str, str]]) -> list[str]:
+    """Every historised item must resolve to a tag or to a stated reason.
+
+    This is the check that stops finding (a) recurring. The old failure was an
+    item the history was keyed on with no matching row in the tag seed: the
+    join silently matched nothing and the assistant reported "no records
+    found". Here that is a build error instead, and the only way past it is to
+    add the tag or to write down why the item is deliberately unanswerable.
+    """
+    problems = []
+    for r in rows:
+        if not r["his_group"]:
+            continue
+        if not r["tag_id"] and not r["exclusion_reason"]:
+            problems.append(
+                f"  {r['item_name']} (point {r['scada_point'] or '?'}) has no row in "
+                f"db/seed/tags.csv and no entry in EXCLUDED_ITEMS"
+            )
+    return problems
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--wrps", type=Path, default=Path("C:/Claude/WRPS"),
+                        help="path to the WRPS repository")
+    parser.add_argument("--out", type=Path,
+                        default=Path(__file__).parent.parent / "db" / "seed" / "historian_items.csv")
+    parser.add_argument("--groups-from-repo", action="store_true",
+                        help="take historisation rates from his_group.qli (the intended "
+                             "import) rather than export_his_group.qli (what the server runs)")
+    args = parser.parse_args()
+
+    if not (args.wrps / "05-scada" / "modbus").is_dir():
+        print(f"not a WRPS repository: {args.wrps}", file=sys.stderr)
+        return 1
+
+    tags_csv = args.out.parent / "tags.csv"
+    rows = build(args.wrps, args.groups_from_repo, tags_csv)
+
+    problems = check_mapping(rows)
+    if problems:
+        print("historised items that resolve to nothing:", file=sys.stderr)
+        print("\n".join(problems), file=sys.stderr)
+        print("\nAdd the tag to db/seed/tags.csv, or add the item to "
+              "EXCLUDED_ITEMS with a reason. Nothing is written.", file=sys.stderr)
+        return 1
+
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    with args.out.open("w", encoding="utf-8", newline="") as fh:
+        writer = csv.DictWriter(fh, fieldnames=list(rows[0].keys()), lineterminator="\n")
+        writer.writeheader()
+        writer.writerows(rows)
+
+    historised = [r for r in rows if r["his_group"]]
+    print(f"wrote {len(rows)} items to {args.out}")
+    print(f"  historised: {len(historised)}"
+          f"   answerable: {sum(1 for r in historised if r['tag_id'])}"
+          f"   deliberately excluded: {sum(1 for r in historised if r['exclusion_reason'])}")
+    for group in sorted({r['his_group'] for r in historised}):
+        members = [r for r in historised if r["his_group"] == group]
+        interval = members[0]["scan_interval_seconds"] or "on change"
+        print(f"    {group:16} {len(members):2} items   every {interval}"
+              f"   life {members[0]['life_time']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/verify.sh

@@ -147,12 +147,51 @@ else
   bad "pgvector extension missing"
 fi
 
+head_ "Historian item mapping"
+# The check that stops Phase 5 finding (a) coming back. A historised item with
+# no tag and no written reason is unreachable from a tag-level lookup, and it
+# fails as "no records found" - which an operator cannot tell apart from an
+# absence of data. It is enforced at generation and at load; this confirms what
+# is actually in the running database.
+orphans=$(docker exec pg-ai psql -U postgres -d plant -tAc \
+  "SELECT count(*) FROM historian_items
+    WHERE his_group IS NOT NULL AND tag_id IS NULL AND exclusion_reason IS NULL" 2>/dev/null || echo "?")
+[ "$orphans" = "0" ] && ok "every historised item resolves to a tag or a stated reason" \
+                     || bad "$orphans historised items resolve to nothing"
+
+# Equipment must be asserted in exactly one place. Nothing in the history may
+# carry an equipment column - that denormalisation is what made the station's
+# most obvious question unanswerable in finding (c).
+stray=$(docker exec pg-ai psql -U postgres -d plant -tAc \
+  "SELECT count(*) FROM information_schema.columns
+    WHERE table_schema='fixture' AND column_name='equipment_id'" 2>/dev/null || echo "?")
+[ "$stray" = "0" ] && ok "no equipment column in the history (equipment is asserted once, in tags)" \
+                   || bad "$stray history columns named equipment_id - equipment is asserted twice"
+
+head_ "Timezone"
+# alarms.yml converts first_alarm/last_alarm inside the measure and names the
+# zone as a literal, because Jinja env_var support could not be tested against
+# the pinned Cube v1.1.7. That literal must not drift from api.env.
+env_tz=$(grep -E '^SITE_TIMEZONE=' "$HOME/ai/api.env" 2>/dev/null | cut -d= -f2 | tr -d ' ')
+model_tz=$(grep -oE "AT TIME ZONE '[^']+'" "$HOME/ai/cube/model/alarms.yml" 2>/dev/null \
+             | head -1 | sed "s/.*'\(.*\)'/\1/")
+if [ -z "$env_tz" ] || [ -z "$model_tz" ]; then
+  bad "could not read SITE_TIMEZONE from api.env ($env_tz) or alarms.yml ($model_tz)"
+elif [ "$env_tz" = "$model_tz" ]; then
+  ok "alarms.yml converts to $model_tz, matching SITE_TIMEZONE"
+else
+  bad "alarms.yml converts to '$model_tz' but SITE_TIMEZONE is '$env_tz' - first_alarm will be reported in the wrong zone"
+fi
+
 head_ "Fixture data"
 if docker exec pg-ai psql -U postgres -d plant -tAc \
      "SELECT 1 FROM information_schema.schemata WHERE schema_name='fixture'" 2>/dev/null | grep -q 1; then
   rows=$(docker exec pg-ai psql -U postgres -d plant -tAc \
-    "SELECT count(*) FROM fixture.alarm_history" 2>/dev/null)
+    "SELECT count(*) FROM fixture.alarm_history WHERE state='ACTIVE'" 2>/dev/null)
-  printf '  \033[33m!!\033[0m   fixture schema present (%s alarm rows) - answers are TEST DATA, not plant history\n' "$rows"
+  span=$(docker exec pg-ai psql -U postgres -d plant -tAc \
+    "SELECT horizon_days || ' days from ' || origin::date FROM fixture.build_meta" 2>/dev/null)
+  printf '  \033[33m!!\033[0m   fixture schema present (%s alarm activations over %s) - answers are TEST DATA, not plant history\n' "$rows" "$span"
+  printf '  \033[33m!!\033[0m   history is retained for 7 days, matching CI Server. Questions older than that return nothing, correctly.\n'
 fi
 
 head_ "Disk"