# historian — collection groups and item bindings

**Hand-made. There is no generator for this.** Everything else under
`modbus_points/` is generated from `03-plc/register-map.csv`; these two files are
not, and that is the reason they have drifted from the server.

| File | Class | Holds |
|---|---|---|
| `his_group.qli` | `@HIS_GROUP_DF` | 3 collection groups |
| `item_his.qli` | `@ITEM_HIS_DF` | 49 item → group bindings |

## The three groups

| Group | Items | Collection |
|---|---|---|
| `WRPS_ONE_SEC` | 5 | 1 s scan — the fast analogues: level, inflow, discharge |
| `WRPS_ONE_MIN` | 4 | 1 min scan — slower trends |
| `WRPS_EVENT` | 40 | on change — states, commands, alarms, trips |

Written 2026-08-21.

## Why this matters more than it looks

The demo this project exists to support is built on **historical grounding**. From
`01-design/00-origin/`:

> "Are you sure? What did inflow actually do last time we had rain like this?"

The answer to that question comes from the historian. Layer 1 of the demo — risk
and headroom — works from live values alone. The push-back that earns trust does
not. **Without these two files there is no historian, and the demo loses the layer
it was designed around.**

## ⚠️ These files disagree with the server

`ciserver-backup-2026-08/export_his_group.qli`, exported from CI Server around
2026-08-20, contains groups that `his_group.qli` does not define:

| In the CI Server export | In `his_group.qli` |
|---|---|
| `WRPS_EVENT` | ✅ |
| `WRPS_ONE_SEC` | ✅ |
| `WRPS_THIRTY_SEC` | ❌ not defined here |
| `WRPS_ONE_MIN` | — not in the export |
| `FIVE_SECONDS` (binding `STN.LEVEL`, `STN.INFLOW`) | ❌ not a WRPS group at all |

**Nobody currently knows which is right.** The export is dated a day before these
files, but contains groups they do not. Resolve it by exporting from `cicore1` and
comparing — see `../../QUICKLOAD.md`.

Until then: **do not import these files onto a working server** without checking
what is already there. You may remove a group something depends on.

## Worth doing: generate these too

The points and items chain is generated end to end, which is what keeps the PLC
and SCADA from drifting apart. The historian stops short of that, is maintained by
hand, and has drifted — exactly the failure the generated chain exists to prevent.

Extending `../gen_ciserver_qli.py` to emit `@HIS_GROUP_DF` and `@ITEM_HIS_DF`
would close the gap. The item list is already there; what it needs is a table
saying which item belongs to which group at what rate. Not done in this audit.