Chapter 4 · honesty rules
Information, evidence, and uncertainty
The domain model separates what is configured from what is observed, and what is known from what is merely silent.
Figure 4. Domain relationships — reads vs powers
Takeaway: The collector uses a source to read a UPS. That UPS has a battery installation and powers equipment. Each arrow ends on its target.
Entities
| Entity | Meaning |
|---|---|
| Site | Place with timezone, witnesses, circuits, network namespace |
| Collector / probe | Agent that reports; witness (expected always-on) or workstation (sleep normal) |
| Source | USB or network endpoint identity used to read a UPS |
| UPS asset | Monitored unit; identity persists across battery replacements |
| Powered equipment | Loads linked by configured powers relationships |
| Battery installation | One installed cartridge interval with its own id |
Time semantics
- Observation time — when the condition was true at the edge.
- Recording / receipt time — when MainsKeeper stored or received it.
- Replayed history keeps observation time and is labelled Received late · replayed.
The same Broadwater names continue through the telemetry and replay figures: bw-pi-01 and ups-bw-rack. Idempotency is what makes a retried batch safe.
Figure 7. Normal telemetry flow
Takeaway: The collector appends locally before upload. Ingestion acknowledges a prefix. Local retirement after that cursor is Proposed.
Related: Telemetry interface
Figure 8. Offline buffer → reconnect → replay → acknowledgement
Takeaway: Sampling continues while upload fails. Replay writes history at observation time and does not repeat an alert that already fired.
Related: Replay · Replay sequence · Monitoring choices
Figure 9. Outage timeline — known vs unknown
Takeaway: Utility, the WAN, and the collector change at different times. The 09:41 cell is local history. Recovery is the fresh reading near 09:48, and silence is not a power failure.
Related: Contact lost · Broadwater outage walkthrough · Durable buffer
Connectivity vocabulary
| Phrase | Means | Does not mean |
|---|---|---|
| Heartbeat late / contact lost | Collector check-in problem | UPS on battery |
| UPS communication lost | Collector up; UPS source silent | Site unreachable |
| Site contact lost — cause unknown | All expected witnesses silent | Confirmed ISP failure |
| Connectivity failure confirmed by local probe | Probe saw targets fail | Particular UPS empty |
| Asleep (ordinary workstation) | Expected non-report | Incident |
Technical detail — freshness, grace, gaps
Accepted Reading freshness vs interval I: On schedule ≤ I+g · Overdue ≤ 2I+g · Stale · last known, with g = max(30 s, I/2).
Accepted Heartbeat H: late after 2H; contact lost after max(5 min, 3H).
Accepted Unknown spans are never interpolated as up/down. Monitoring-disabled gaps use exact stop/resume intervals.