Merge hw4-alma (#592/#611)

Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe

docs/drivers/AbCip.md

@@ -19,7 +19,7 @@ coverage map, see [AbServer-Test-Fixture.md](AbServer-Test-Fixture.md).
 
 | Project | Role |
 |---------|------|
-| `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbCip/` | The driver — `AbCipDriver`, the libplctag runtime/enumerator/template-reader wrappers, the UDT read planner + template decoders, the host-address parser, and the ALMD alarm projection. |
+| `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbCip/` | The driver — `AbCipDriver`, the libplctag runtime/enumerator/template-reader wrappers, the UDT read planner + template decoders, the host-address parser, and the ALMD/ALMA alarm projection. |
 | `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Ab.LibplctagShared/` | Project-less shared source (`LibplctagOrphanRelease.cs`, #578/#580) compiled into both `Driver.AbCip` and `Driver.AbLegacy`. The `AbStatus` → OPC UA table is shared in `Driver.Ab.Transport` (`AbOpcUaStatusMap`). |
 | `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbCip.Contracts/` | `AbCipDriverOptions`, `AbCipDeviceOptions`, `AbCipTagDefinition` / `AbCipStructureMember`, and the `AbCipDataType` / `AbCipPlcFamily` enums bound from the driver's `DriverConfig` JSON. |
 
@@ -44,7 +44,7 @@ AB Legacy surface.
 | `ISubscribable` | `SubscribeAsync` driven by the shared `PollGroupEngine` | CIP has no push model — subscriptions become polling groups. |
 | `IHostConnectivityProbe` | `ProbeLoopAsync` + `GetHostStatuses` | One probe loop per device reading `Probe.ProbeTagPath`; no path configured ⇒ a warning is logged and the device stays `Unknown`. |
 | `IPerCallHostResolver` | `ResolveHost` | Routes each call to the tag's `DeviceHostAddress`, the breaker key for the resilience pipeline so one dead PLC trips only its own breaker. |
-| `IAlarmSource` | `AbCipAlarmProjection` (ALMD) | Opt-in via `EnableAlarmProjection`; off by default the subscribe path is a no-op so capability negotiation still works. |
+| `IAlarmSource` | `AbCipAlarmProjection` (ALMD + ALMA) | Opt-in via `EnableAlarmProjection`; off by default the subscribe path is a no-op so capability negotiation still works. |
 
 ## Addressing Model
 
@@ -80,7 +80,7 @@ the driver's `DriverConfig` JSON. Key fields:
 - AdminUI driver forms (AbCip/AbLegacy) overlay only the keys they edit onto the stored JSON, so unmodelled keys survive a save (#576). They also write durations as the integer-millisecond keys the factory binds (`timeoutMs`, `alarmPollIntervalMs`, `probe.intervalMs`, `probe.timeoutMs`); a legacy TimeSpan-string key (`timeout`: "00:00:05") is loaded and migrated on save.
 - **`Transport`** — absent (default ⇒ `Native`), `Native`, or `Libplctag` (fallback); see [Transport](#transport-transport-option).
 - **Discovery** — `EnableControllerBrowse` (`@tags` walk), `EnableDeclarationOnlyUdtGrouping` (whole-UDT read fast path) and `browsePageDelayMs` (native browse pacing, see [Native browse](#native-browse-paging-pacing-and-template-leases)).
-- **Alarms** — `EnableAlarmProjection` + `AlarmPollInterval` for the ALMD projection.
+- **Alarms** — `EnableAlarmProjection` + `AlarmPollInterval` for the ALMD/ALMA projection.
 
 Full per-field descriptions live in `AbCipDriverOptions.cs`. The JSON skeleton is
 reproduced in [docs/v2/driver-specs.md §3](../v2/driver-specs.md).
@@ -262,9 +262,9 @@ The driver has two interchangeable wire transports, selected by one `DriverConfi
 ## Alarm Projection
 
 `IAlarmSource` is served by `AbCipAlarmProjection`, which polls each subscribed
-ALMD UDT's `InFaulted` + `Severity` members at `AlarmPollInterval` and fires
-`OnAlarmEvent` on raise/clear transitions. It is **ALMD-only** in this pass (ALMA
-analog alarms are a follow-up) and **disabled by default** — shops running FT
+ALMD UDT's `InAlarm` + `Severity` members (or an ALMA's limit members, below) at
+`AlarmPollInterval` and fires `OnAlarmEvent` on raise/clear transitions. It handles
+ALMD (digital) and ALMA (analog, `ALARM_ANALOG`, Gitea #611) and is **disabled by default** — shops running FT
 Alarm & Events should keep it off and take alarms through the native route, since
 the projection semantics don't exactly mirror Rockwell FT A&E.
 
@@ -272,6 +272,56 @@ Each event carries `ConditionId` = the subscribed reference (the alarm tag's Raw
 routes native transitions on) and `Kind` = `Raise` / `Clear`. Before Gitea #641 the projection sent
 `"{ref}#active"` with no kind, so the host dropped every ALMD transition as unrouted.
 
+**ALMD's active bit is `InAlarm`** (Rockwell's ALMD reference). Until hw4 the projection polled `InFaulted`, which
+is the *input-health* flag (Status.1, set when the program raises `InFault`), so a live ALMD would have raised on
+input faults and never on the alarm itself. Declare `InAlarm` (and `Severity`) on an ALMD tag.
+**Migration:** a tag that declared `InFaulted` but not `InAlarm` now never raises (the `InAlarm` read is
+`BadNodeIdUnknown`); the projection logs a once-per-tag Warning at subscribe — add `InAlarm` to the tag's members.
+
+### ALMA (analog alarms)
+
+A subscribed ref is ALMA when its declared tag definition (`Structure` with `members`) carries a per-limit
+status bit — any of `HHInAlarm` / `HInAlarm` / `LInAlarm` / `LLInAlarm` / `ROCPosInAlarm` / `ROCNegInAlarm` — **and
+no plain `Acked`** (an ALMD member; `AbCipAlarmDetector.IsAlma`). Anything else stays ALMD, so an ALMD-shaped user
+UDT is not misclassified. ⚠️ **An ALMA authored without `members` cannot be told apart from an ALMD and is
+projected as an ALMD** (it would poll `InAlarm`/`Severity`, which an ALMA lacks, and never raise) — declare the members.
+**Declare the members you want projected**: the projection reads only the limits declared (their `*InAlarm`, and
+where declared their `*Acked` and `*Severity`). Names/types are from Rockwell's Studio 5000 "Analog Alarm (ALMA)"
+reference (BOOL status bits, DINT severities 1..1000). ⚠️ With `EnableDeclarationOnlyUdtGrouping` the whole-UDT
+decode computes offsets from the DECLARATION order, which for a partially declared ALMA is not the controller's
+layout — leave grouping off for ALMA tags (BOOL members are read member by member anyway).
+
+- **One condition per ALMA tag**, `ConditionId` = the RawPath, `AlarmType` = `ALMA`. Active = any polled limit
+  bit set. Severity (exact, `OpcUaSeverity`, plus the 4-bucket enum) and message (`ALMA <ref> HH alarm`,
+  `H`, `L`, `LL`, `ROC+`, `ROC-`) come from the **most severe active limit** (ties: HH, LL, H, L, ROC+, ROC-).
+- **What the host is told** (last-told state — active-limit mask, acked, governing limit + severity — is
+  driver-owned, so a re-subscribe never re-raises a still-active alarm):
+  none→active `Raise`, or the atomic `ActiveAcknowledged` when every declared `*Acked` is true (always so when the
+  instruction's `AckRequired` is false); active→none `Clear`; a limit **newly** entering while active `Retrigger`
+  (a new unacknowledged occurrence) — or `ActiveAcknowledged` if nothing is pending ack, never
+  Retrigger-then-Acknowledge; every declared `*Acked` bit going true while the condition was unacknowledged
+  `Acknowledge`; a Good `*Acked` read going false on a fully-acked condition with the same limits active
+  `Retrigger` (an occurrence the poll missed); a limit dropping out (the governing limit or its severity changes, no new occurrence) an
+  `Unspecified` event flagged `IsRestatement`, which `NativeAlarmProjector` applies as a text/severity move with
+  **no `/alerts` row**. A non-governing limit flickering emits nothing.
+- **"Acked" is judged over every declared limit, active or not.** In Logix an occurrence that returned to normal
+  unacknowledged keeps its `*Acked` bit false, so it keeps the condition unacknowledged — a surviving, already-acked
+  limit never turns it into a device "Acknowledged" for an excursion nobody acknowledged.
+- **Bad reads:** a Bad `*InAlarm` or severity read skips that tick (no false Clear, no text change); a Bad `*Acked`
+  read carries the last-told ack state forward instead of recording "unacknowledged".
+- **Acknowledge** writes the ALMA's `OperAckAll` input (not `Acked`, which ALMA lacks); declare `OperAckAll` as a
+  writable member. A failed acknowledge write is now logged at Warning (it used to vanish silently). The `*Acked` bits
+  are instruction outputs and are never written.
+- **Not projected:** `Disabled`, `Suppressed` and `InFaulted` (input-health) — the event contract has no
+  enable/suppress channel — and the aggregate `AnyInAlarmUnack` / per-limit `*InAlarmUnack` bits (derivable from the
+  polled `*InAlarm` + `*Acked`).
+- **Evidence:** unit tests over fake runtimes (`AbCipAlmaProjectionTests`, BOOL members, member-by-member reads, plus a
+  mixed ALMD+ALMA subscription) and a host-level test, `Runtime.Tests/AbCipAlmaNativeAlarmEndToEndTests`, that walks
+  raise → escalate → drop-out → ack → unacked excursion → clear through `DriverHostActor` and asserts the Part 9
+  updates and `/alerts` rows. `ab_server` has no alarm instructions and the Z35162 press (CompactLogix
+  5069-L320ERS2) has no ALMA/ALMD, so there is **no wire-level or live gate** for ALMA or ALMD; it needs a controller
+  that actually runs the instruction (Logix Emulate tier).
+
 ## Testing
 
 - **Unit tests** — `tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbCip.Tests/` cover the driver, host-address parser, UDT planner, and alarm projection via fake tag runtimes.

docs/drivers/AbServer-Test-Fixture.md

@@ -92,7 +92,7 @@ Depends on the ALMD UDT shape, which `ab_server` cannot emulate. The
 `OnAlarmEvent` raise/clear path + ack-write semantics are not exercised
 end-to-end.
 
-Unit coverage: `AbCipAlarmProjectionTests` — fakes feed `InFaulted` /
+Unit coverage: `AbCipAlarmProjectionTests` — fakes feed `InAlarm` /
 `Severity` via `ValuesByOffset` + assert the emitted `AlarmEventArgs`.
 
 ### 3. Micro800 unconnected-only path