# Alarms

> The alarms waiting for an answer, acknowledged where they are read, over the durable timeline of every alarm state transition.

The Alarms tab is the operation screen for alarms: what is waiting now, and the record of what
already happened, stacked on one screen. It is the first tab of [Events](events)
(`/events?view=alarms`), the tab the page opens on, and where the status bar's alarm indicator lands
when you click it. Seeing it takes **View events**; answering an alarm here takes **Operate logic**;
exporting the history takes **Export/import histories**. Alarms themselves are defined on
[Logic > Alarms](logic-alarms); this tab never edits one.

The tab stacks two cards: **Current alarms** above, read live from the alarm registry, and
**History** below, read from the durable journal.

## Current alarms {#current-alarms}

The card lists every alarm that is active or still waiting for an acknowledgement: exactly the
population the status bar counts, so the two can never disagree. It is read straight from the live
registry and redrawn on the registry's own signals (a rise, a clear or an acknowledgement from any
surface, a definition saved, disabled or deleted), never on a clock.

### The head {#the-head}

| Element | What it shows |
| --- | --- |
| Bell | The alarm mark. It switches to its ringing variant while anything is active or unacked and takes the colour of the worst priority in the list. |
| Summary | "N active (M unacked)": how many conditions are true right now, and how many alarms still await an answer. An alarm that cleared before anyone acknowledged it stays counted as unacked. The text takes the tone of the worst priority. |
| Acknowledge all | Answers every waiting alarm in one command. Drawn only for a role with **Operate logic**. Greyed with the reason in its tooltip while the runtime is stopped ("Runtime stopped") or while nothing is waiting ("No alarm is waiting for a response."); otherwise the tooltip reads "Acknowledge every alarm still waiting for a response". The action feed answers "All alarms acknowledged." |

### The rows {#the-rows}

Rows are ordered by priority, worst first (Critical, High, Medium, Low), and within one priority by
the oldest activation first, so the alarm that most deserves an answer is nearest the top. The grid
is compact, at most 240 pixels tall, and scrolls inside the card.

| Column | What it is |
| --- | --- |
| Name | A dot in the priority's tone, then the alarm's name. Hovering the name shows the alarm's message. |
| Address | The alarm's rooted Logic address, `Alarms.<folders>.<name>`, the way expressions and dashboards refer to it. |
| State | The state and the priority, for example "Active, unacked · Critical". The state words are the four of the alarm state machine: **Normal**, **Active, unacked**, **Active, acked** and **Cleared, unacked** (the condition went back to normal before anyone answered). |
| Since | The date and time the current activation began; a dash once the condition has cleared and the row only waits for its acknowledgement. |
| Ack | Drawn only on a row that is still unacked, and only for a role with **Operate logic**. Its tooltip reads "Acknowledge" followed by the alarm's name; it is greyed with "Runtime stopped" while the runtime is stopped. The action feed answers with the alarm's name followed by "acknowledged." |

One acknowledgement is dispatched at a time; a second press while the first is still on the logic
queue is ignored rather than answering a row the list has already let go of. Every acknowledgement
from this card goes through the same journaled funnel the Logic page uses and is recorded in the
history below with the source **Operator**; it does not record which signed-in user pressed it.
Acknowledging an alarm that has nothing pending is a no-op. An alarm whose definition does not
require acknowledgement never appears as unacked: it rises straight to "Active, acked" and falls
straight to Normal, so its row shows while it is active and carries no **Ack**.

When nothing is active or waiting, the card reads "No alarm is active or waiting for a response."
with "When an alarm rises it appears here so it can be acknowledged."

### Refusals {#refusals}

| Situation | What happens |
| --- | --- |
| The role lacks Operate logic | Neither **Ack** nor **Acknowledge all** is drawn; the rows stay readable. A press that reaches the handler anyway answers "Your role can view Logic but cannot operate it (write values, run actions, acknowledge alarms)." |
| The runtime is stopped | Both verbs stay drawn and greyed with "Runtime stopped"; the list still shows the state the registry holds. |
| Nothing is waiting | **Acknowledge all** is greyed with "No alarm is waiting for a response."; no row carries **Ack**. |

## History {#history}

The card under the current alarms is the durable timeline: one row per alarm state transition, in
the shared conduct of the three timelines described on
[Events](events#how-the-three-timelines-behave).

### Search and filter {#search-and-filter}

| Control | Values | What it does |
| --- | --- | --- |
| Search | Placeholder "Search name, message or source" | Contains-match on the alarm's name, its message and the source of the transition, as they were snapshotted at the time. |
| Priority | **All priorities** (default), **Critical**, **High**, **Medium**, **Low** | Keeps only transitions of alarms that had that priority when they happened. |
| Refresh | | Re-reads the journal; tooltip "Refresh alarm events". |
| Export | **Export as CSV…**, **Export as JSON…** | Writes the rows currently listed. Drawn only with **Export/import histories**; greyed while the list is empty. |

### The rows {#the-rows-1}

| Part of the row | Content |
| --- | --- |
| Time | Date and time of the transition. |
| Dot | The priority's tone: critical for Critical, caution for High, attention for Medium, neutral for Low. |
| Name | The alarm's name at the time of the transition. |
| Summary | "From → To · Source", for example "Normal → Active, unacked · Logic". |
| Level | The priority word. |

Every transition of the state machine is recorded, whatever caused it. The **Source** names the
origin:

| Source | Meaning |
| --- | --- |
| Logic | The logic sweep evaluated the condition: a rise after the on-delay, or a fall after the off-delay. |
| Operator | An acknowledgement pressed on this tab or on the Logic page. |
| MCP | An acknowledgement made by an agent over MCP. |
| Configuration | The alarm was reset to Normal because its definition was saved with a changed condition, delays, acknowledgement requirement or enabled state, or because it was deleted. |

### The detail panel {#the-detail-panel}

Selecting a row opens the panel with the priority badge and the name, the full timestamp, the
transition summary, the message the alarm announced at the time (or "No message captured."), and
two cards:

| Card | Field | Content |
| --- | --- | --- |
| EVENT | Level | The priority. |
| EVENT | Event ID | The journal's identity of this transition. |
| ALARM SNAPSHOT | Transition | "From → To" in the state words. |
| ALARM SNAPSHOT | Source | Logic, Operator, MCP or Configuration. |
| ALARM SNAPSHOT | Alarm ID | The stable id of the alarm definition, the same after a rename. |

**Copy event** copies "timestamp | Alarm | priority | name | From → To · Source | message" as one
line and answers "Event copied to clipboard."

### Export columns {#export-columns}

| Column | CSV | JSON |
| --- | --- | --- |
| Timestamp | First column, headed "Timestamp (UTC-03:00)" (the station's own offset) | `Timestamp` |
| Priority | `Priority` | `Priority` |
| Name | `Name` | `Name` |
| Transition | `Transition`, written "From -> To" | `From` and `To`, two fields |
| Source | `Source` | `Source` |
| Message | `Message` | `Message` |
| Event id | `EventId` | `EventId` |
| Alarm id | `AlarmId` | `AlarmId` |

The JSON file is an envelope, `{ "TimeZone": "...", "Events": [ ... ] }`. File names are
`alarm-history-<yyyyMMdd-HHmmss>.csv` and `.json`. The CSV follows the station's
decimal-separator preference like every other export: with point decimals the list separator is
`,`, with comma decimals it is `;`. A cell beginning with `=`, `+`, `-` or `@` is prefixed with an
apostrophe so a spreadsheet reads it as text.

### Empty states and the status line {#empty-states-and-the-status-line}

- "No alarm events yet" with "Alarm transitions will appear here as the runtime observes them."
- "No alarm events match these filters" with "Adjust the priority or search terms to widen this
  history."
- The status line reads "N shown · page 1", then " · filtered" when a search, a priority or a date
  range is in force; on the right, "1 selected" and "Updated hh:mm:ss".

## What the Alarms tab does not do {#what-the-alarms-tab-does-not-do}

- It does not create, edit, enable, disable or delete an alarm; that is [Logic > Alarms](logic-alarms).
- It does not shelve or silence an alarm, and it makes no sound.
- It does not restore acknowledged state after a restart: the registry re-derives every state from
  the first sweep, and an acknowledgement that was pending must be given again. The history keeps
  the transitions from before and after.
- It records the origin of an acknowledgement (Operator, MCP) but not the name of the signed-in
  user.
- It does not filter the history by alarm, date range or state; search by name or export the
  window.
- The history has no verb of its own: nothing here deletes a transition.