# Alarm Historian Follow-ups Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans (or subagent-driven-development) to implement this plan task-by-task.

**Goal:** Close the six code follow-ups left open by the alarm-followups round-2 work (`f64f7ce6`): honor the per-alarm `HistorizeToAveva` opt-out at the durable historian write, expose drain/capacity/retention config knobs, validate the historian config at startup, record the real operator for shelve/enable/disable transitions, and fix two `SqliteStoreAndForwardSink` thread-safety nits.

**Architecture:** All six are bounded hardening fixes on the already-shipped historian + scripted-alarm surface — no new components. The load-bearing one (T1) threads a `HistorizeToAveva` flag through the engine emission → the DPS-serialized `AlarmTransitionEvent` → a gate in `HistorianAdapterActor` that suppresses **only the durable write** (the live `/alerts` UI keeps every transition). The rest are localized: options/registration hardening (T2), a one-line `TransitionUser` widening (T3), and field-visibility fixes on the SQLite sink (T4).

**Tech Stack:** C# / .NET 10, Akka.NET (cluster DistributedPubSub + TestKit), xUnit + Shouldly, Serilog, EF Core (untouched here), SQLite store-and-forward.

**Source of truth:** `pending.md` items 1–6 (item 7, the docker-dev rig cleanup, is an operational deferral and is **out of scope**). Round-2 design: `docs/plans/2026-06-11-alarm-followups-round2-design.md`.

**Base:** Branch off `master` @ `f64f7ce6`.

**Hard rules (carried from round 2):** stage by explicit path (never `git add .`); never stage `sql_login.txt` or `src/Server/ZB.MOM.WW.OtOpcUa.Host/pki/`; never echo the gateway API key into a new tracked file; no force-push, no `--no-verify`; **NO Configuration entity / EF migration change** — the historian queue is a standalone SQLite file, NOT the Config DB; commit per task by explicit path.

**Same-assembly build contention:** T1, T2, T3 all touch the `Runtime` assembly (and T1/T3 share `ScriptedAlarmHostActor.cs`) → they MUST run serially (build/test collide on `obj/`). T4 touches only `Core.AlarmHistorian` → it is the one task safe to run concurrently with the Runtime chain.

---

## Task 0: Branch

**Classification:** trivial
**Estimated implement time:** ~1 min
**Parallelizable with:** none

**Files:** none (git only)

**Step 1: Create the feature branch off master**

```bash
git checkout master
git status --short            # expect only untracked pending.md
git checkout -b feat/alarm-historian-followups
git rev-parse --short HEAD    # expect f64f7ce6
```

Expected: on `feat/alarm-historian-followups`, HEAD `f64f7ce6`.

(Do NOT commit `pending.md` — it is an untracked working note and stays untracked.)

---

## Task 1: Honor `HistorizeToAveva` opt-out at the durable write (pending #1)

**Classification:** high-risk
**Estimated implement time:** ~5 min
**Parallelizable with:** Task 4

**Why high-risk:** changes a DistributedPubSub-serialized data contract (`AlarmTransitionEvent`) and the warm-redundant historian gate. Mis-gating either double-writes, drops rows, or (the trap pending.md calls out) silently suppresses the **live UI** instead of just the durable write.

**The design (locked):**
- The flag is **already** on `ScriptedAlarmDefinition.HistorizeToAveva` (default `true`) and reaches the engine via `ToDefinition` (`ScriptedAlarmHostActor.cs:477`). It is NOT yet on the emitted event, so the historian can't see it.
- Carry it: `ScriptedAlarmEvent` (engine) → `AlarmTransitionEvent` (Commons, DPS-serialized) → gate in `HistorianAdapterActor`.
- **Gate the durable write ONLY.** `ScriptedAlarmHostActor.OnEngineEmission` must keep publishing every transition to `alerts` (its existing Primary gate is unchanged) so the live `/alerts` UI is unaffected. The `HistorizeToAveva` check lives solely in `HistorianAdapterActor.Receive<AlarmTransitionEvent>`.
- **Default `true`, non-nullable.** On a rolling restart Akka's JSON serializer applies `default(bool)` = `false` to an old-format message's missing field (the same quirk the `AlarmTypeName` null-coalesce in `Translate` guards). This is safe here because the node that *writes* is always the Primary (or a boot-window node), and that node also *published* the event — so the written event always carries the publisher's own same-version flag value. A cross-version old→new flow only reaches the Secondary, which never writes. Document this reasoning in a code comment.

**Files:**
- Modify: `src/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms/ScriptedAlarmEngine.cs` (`ScriptedAlarmEvent` record ~837; `BuildEmission` ~592)
- Modify: `src/Core/ZB.MOM.WW.OtOpcUa.Commons/Messages/Alerts/AlarmTransitionEvent.cs` (record ~19-29)
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/ScriptedAlarmHostActor.cs` (`OnEngineEmission` ~289-301)
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Historian/HistorianAdapterActor.cs` (ctor `Receive<AlarmTransitionEvent>` ~74)
- Test: `tests/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms.Tests/ScriptedAlarmEngineTests.cs`
- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/Historian/HistorianAdapterActorTests.cs`

**Step 1: Write the failing engine test (flag carried through emission)**

In `ScriptedAlarmEngineTests.cs`, add a test that an alarm defined with `HistorizeToAveva: false` emits a `ScriptedAlarmEvent` whose `HistorizeToAveva` is `false` (and `true` when the definition is `true`). Follow the existing engine-test setup pattern in that file (register a definition, drive the predicate active, capture `OnEvent`). Assert:

```csharp
emitted.HistorizeToAveva.ShouldBeFalse();
```

Run (expect FAIL — `ScriptedAlarmEvent` has no `HistorizeToAveva`):
```bash
dotnet test tests/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms.Tests --filter "FullyQualifiedName~HistorizeToAveva"
```

**Step 2: Add the field to `ScriptedAlarmEvent` + populate in `BuildEmission`**

`ScriptedAlarmEvent` record (append after `Comment`):
```csharp
public sealed record ScriptedAlarmEvent(
    string AlarmId,
    string EquipmentPath,
    string AlarmName,
    AlarmKind Kind,
    AlarmSeverity Severity,
    string Message,
    AlarmConditionState Condition,
    EmissionKind Emission,
    DateTime TimestampUtc,
    string? Comment = null,
    bool HistorizeToAveva = true);
```

`BuildEmission` — add to the `new ScriptedAlarmEvent(...)` initializer (the definition is on `state.Definition`):
```csharp
            Comment: kind switch
            {
                EmissionKind.Acknowledged => condition.LastAckComment,
                EmissionKind.Confirmed => condition.LastConfirmComment,
                EmissionKind.CommentAdded => condition.Comments.Count == 0 ? null : condition.Comments[^1].Text,
                _ => null,
            },
            HistorizeToAveva: state.Definition.HistorizeToAveva);
```

**Step 3: Add the field to `AlarmTransitionEvent` (Commons contract)**

Append after `Comment` (additive, default `true` — see the rolling-restart note above), and add the `<param>` doc line:
```csharp
/// <param name="HistorizeToAveva">When <c>false</c>, the durable historian sink suppresses this transition (the live <c>alerts</c> fan-out is unaffected). Defaults to <c>true</c>. On a rolling restart an old-format message deserializes this as <c>false</c> (CLR default); that is safe because the writing node is always the same-version publisher — see <c>HistorianAdapterActor</c>.</param>
public sealed record AlarmTransitionEvent(
    string AlarmId,
    string EquipmentPath,
    string AlarmName,
    string TransitionKind,
    int Severity,
    string Message,
    string User,
    DateTime TimestampUtc,
    string AlarmTypeName = "AlarmCondition",
    string? Comment = null,
    bool HistorizeToAveva = true);
```

**Step 4: Populate it in `ScriptedAlarmHostActor.OnEngineEmission`**

Add to the `new AlarmTransitionEvent(...)` initializer (after `Comment: e.Comment`):
```csharp
            AlarmTypeName: e.Kind.ToString(),
            Comment: e.Comment,
            HistorizeToAveva: e.HistorizeToAveva);
```
**Do NOT touch the Primary `_localRole` gate below it** — the `alerts` publish stays ungated by `HistorizeToAveva` (live UI must see every transition).

**Step 5: Gate the durable write in `HistorianAdapterActor`**

Change the `Receive<AlarmTransitionEvent>` handler (currently `~74`) to also require the flag:
```csharp
        // HistorizeToAveva=false is a per-alarm opt-out of DURABLE historization only — the live
        // `alerts` fan-out (browser UI) already happened upstream. Gate the sink write, not the publish.
        Receive<AlarmTransitionEvent>(t => { if (ShouldHistorize() && t.HistorizeToAveva) _ = EnqueueAsync(Translate(t)); });
```

**Step 6: Write the failing historian-gate test, then make it pass**

In `HistorianAdapterActorTests.cs`: add a `bool historizeToAveva = true` parameter to the `SampleTransition` helper (thread it into the `AlarmTransitionEvent`), then add:
```csharp
/// <summary>Per-alarm opt-out (pending #1): a Primary node MUST NOT write to the durable sink when the
/// transition carries HistorizeToAveva=false — even though it would otherwise historize. The live alerts
/// fan-out is upstream and unaffected.</summary>
[Fact]
public void Primary_node_does_not_historize_when_opted_out()
{
    var (actor, sink) = CreateActor();
    TellRedundancyRole(actor, RedundancyRole.Primary);
    actor.Tell(SampleTransition(historizeToAveva: false));
    // Give the actor time to (not) enqueue.
    ExpectNoMsg(Settle);
    sink.EnqueueCount.ShouldBe(0);
}
```
(Match the existing helpers — `CreateActor`, `TellRedundancyRole`, `Settle`, `ExpectNoMsg`. If `ExpectNoMsg` isn't the local idiom, mirror the existing `Secondary_node_does_not_historize` test's settle-then-assert-0 shape.)

**Step 7: Run the full affected suites**

```bash
dotnet test tests/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms.Tests
dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests --filter "FullyQualifiedName~HistorianAdapterActor|FullyQualifiedName~ScriptedAlarmHostActor"
```
Expected: PASS. The existing `ScriptedAlarmHostActorTests` already define alarms with `HistorizeToAveva: true`/`false`, so confirm those still pass (the `alerts` publish must still fire for the `false` alarm).

**Step 8: Commit**

```bash
git add src/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms/ScriptedAlarmEngine.cs \
        src/Core/ZB.MOM.WW.OtOpcUa.Commons/Messages/Alerts/AlarmTransitionEvent.cs \
        src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/ScriptedAlarmHostActor.cs \
        src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Historian/HistorianAdapterActor.cs \
        tests/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms.Tests/ScriptedAlarmEngineTests.cs \
        tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/Historian/HistorianAdapterActorTests.cs
git commit -m "feat(historian): honor per-alarm HistorizeToAveva opt-out at the durable write"
```

---

## Task 2: Historian config knobs + startup validation (pending #2, #3, #4)

**Classification:** standard
**Estimated implement time:** ~4 min
**Parallelizable with:** Task 4

**Files:**
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Historian/AlarmHistorianOptions.cs`
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ServiceCollectionExtensions.cs` (`AddAlarmHistorian` ~67-89)
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Host/appsettings.json` (the existing disabled `AlarmHistorian` example section)
- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/Historian/AlarmHistorianRegistrationTests.cs`

**Step 1: Write the failing tests**

In `AlarmHistorianRegistrationTests.cs`, add:
- A binding test: a config with `DrainIntervalSeconds`, `Capacity`, `DeadLetterRetentionDays` set binds them onto `AlarmHistorianOptions`.
- `Validate()` tests (pure, no DI): `{ Enabled = true, SharedSecret = "" }` → returns a warning mentioning `SharedSecret`; `{ Enabled = true, DatabasePath = "alarm-historian.db" }` (relative) → returns a warning mentioning the relative path; `{ Enabled = true, SharedSecret = "x", DatabasePath = "/abs/h.db" }` → returns empty; `{ Enabled = false, SharedSecret = "" }` → returns empty (disabled is never a misconfig).

```csharp
[Fact]
public void Validate_warns_on_empty_shared_secret_when_enabled()
{
    var opts = new AlarmHistorianOptions { Enabled = true, SharedSecret = "", DatabasePath = "/var/h.db" };
    opts.Validate().ShouldContain(w => w.Contains("SharedSecret"));
}

[Fact]
public void Validate_warns_on_relative_database_path_when_enabled()
{
    var opts = new AlarmHistorianOptions { Enabled = true, SharedSecret = "s", DatabasePath = "alarm-historian.db" };
    opts.Validate().ShouldContain(w => w.Contains("DatabasePath"));
}

[Fact]
public void Validate_is_silent_when_disabled()
{
    new AlarmHistorianOptions { Enabled = false, SharedSecret = "" }.Validate().ShouldBeEmpty();
}
```

Run (expect FAIL — no `Validate`, no new options):
```bash
dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests --filter "FullyQualifiedName~AlarmHistorianRegistration"
```

**Step 2: Add the knobs + `Validate()` to `AlarmHistorianOptions`**

```csharp
    /// <summary>Seconds between drain-worker ticks. Defaults to 5.</summary>
    public int DrainIntervalSeconds { get; init; } = 5;

    /// <summary>Maximum queued rows before the sink evicts the oldest. Defaults to 1,000,000
    /// (<c>SqliteStoreAndForwardSink.DefaultCapacity</c>).</summary>
    public long Capacity { get; init; } = 1_000_000;

    /// <summary>Days to retain dead-lettered rows before purge. Defaults to 30.</summary>
    public int DeadLetterRetentionDays { get; init; } = 30;

    /// <summary>Returns operator-facing misconfiguration warnings for an <c>Enabled</c> historian
    /// (empty when disabled or correctly configured). Pure — the registration logs each entry.</summary>
    /// <returns>Zero or more human-readable warning messages.</returns>
    public IReadOnlyList<string> Validate()
    {
        var warnings = new List<string>();
        if (!Enabled) return warnings;
        if (string.IsNullOrWhiteSpace(SharedSecret))
            warnings.Add("AlarmHistorian:SharedSecret is empty while the historian is enabled — the Wonderware sidecar Hello frame will carry an empty secret.");
        if (!Path.IsPathRooted(DatabasePath))
            warnings.Add($"AlarmHistorian:DatabasePath '{DatabasePath}' is relative — it resolves against the process working directory (e.g. System32 for a Windows service). Set an absolute path.");
        return warnings;
    }
```
(Add `using System.Collections.Generic;` and `using System.IO;` if the file lacks them.)

**Step 3: Thread the knobs + log warnings in `AddAlarmHistorian`**

Inside the existing `if (opts is not { Enabled: true }) return services;` guard's downstream block:
```csharp
        foreach (var warning in opts.Validate())
            Serilog.Log.Logger.ForContext<SqliteStoreAndForwardSink>().Warning("{HistorianConfigWarning}", warning);

        services.AddSingleton<IAlarmHistorianSink>(sp =>
        {
            var sink = new SqliteStoreAndForwardSink(
                opts.DatabasePath,
                writerFactory(opts, sp),
                Serilog.Log.Logger.ForContext<SqliteStoreAndForwardSink>(),
                batchSize: opts.BatchSize,
                capacity: opts.Capacity,
                deadLetterRetention: TimeSpan.FromDays(opts.DeadLetterRetentionDays));
            sink.StartDrainLoop(TimeSpan.FromSeconds(opts.DrainIntervalSeconds));
            return sink;
        });
        return services;
```

**Step 4: Update the appsettings example**

In `Host/appsettings.json`, extend the disabled `AlarmHistorian` example section with the three new keys (`DrainIntervalSeconds`, `Capacity`, `DeadLetterRetentionDays`) so operators see them. Keep `Enabled: false`. Make a targeted edit to that section only.

**Step 5: Run + commit**

```bash
dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests --filter "FullyQualifiedName~AlarmHistorianRegistration"
git add src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Historian/AlarmHistorianOptions.cs \
        src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ServiceCollectionExtensions.cs \
        src/Server/ZB.MOM.WW.OtOpcUa.Host/appsettings.json \
        tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/Historian/AlarmHistorianRegistrationTests.cs
git commit -m "feat(historian): drain/capacity/retention config knobs + startup config-warning validation"
```

---

## Task 3: Record the real operator for shelve/enable/disable transitions (pending #5)

**Classification:** small
**Estimated implement time:** ~3 min
**Parallelizable with:** Task 4

**The design:** every shelve/unshelve/enable/disable op in `Part9StateMachine` appends an audit `AlarmComment` carrying the acting `user` (`ApplyOneShotShelve` → `"ShelveOneShot"`, `ApplyTimedShelve` → `"ShelveTimed"`, `ApplyUnshelve` → `"Unshelve"`, `ApplyEnable` → `"Enable"`, `ApplyDisable` → `"Disable"`), and auto-unshelve appends with `user="system"`. So the operator is already the **last** `Comments` entry on the emitted condition — exactly the `CommentAdded` case. No Core/state change needed; widen the `TransitionUser` switch. (`Acknowledged`/`Confirmed` keep using `LastAckUser`/`LastConfirmUser` — leave them.)

**Files:**
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/ScriptedAlarmHostActor.cs` (`TransitionUser` ~508-514)
- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/ScriptedAlarms/ScriptedAlarmHostActorTests.cs`

**Step 1: Write the failing test**

Mirror the existing Acknowledge/AddComment command tests (they drive a command via the `alarm-commands` topic and `FishForMessage<AlarmTransitionEvent>` on the `alerts` probe). Add a test that an operator shelve command (`Operation: "OneShotShelve"`, `User: "carol"`) on an active alarm yields a transition with `evt.User.ShouldBe("carol")` (it currently returns `"system"`). Use the exact command-operation string the existing inbound tests use (check the host actor's command dispatch for the canonical `OneShotShelve`/`Shelve` spelling).

Run (expect FAIL — currently `"system"`):
```bash
dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests --filter "FullyQualifiedName~ScriptedAlarmHostActor"
```

**Step 2: Widen `TransitionUser`**

```csharp
    private static string TransitionUser(ScriptedAlarmEvent e) => e.Emission switch
    {
        EmissionKind.Acknowledged => e.Condition.LastAckUser ?? "system",
        EmissionKind.Confirmed => e.Condition.LastConfirmUser ?? "system",
        // Shelve / unshelve / enable / disable / comment ops each append the acting user as the last
        // audit entry on the emitted condition (auto-unshelve appends "system"); read it from there.
        EmissionKind.CommentAdded
            or EmissionKind.Shelved
            or EmissionKind.Unshelved
            or EmissionKind.Enabled
            or EmissionKind.Disabled => e.Condition.Comments.Count > 0 ? e.Condition.Comments[^1].User : "system",
        _ => "system",
    };
```

**Step 3: Run + commit**

```bash
dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests --filter "FullyQualifiedName~ScriptedAlarmHostActor"
git add src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/ScriptedAlarmHostActor.cs \
        tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/ScriptedAlarms/ScriptedAlarmHostActorTests.cs
git commit -m "fix(alarms): historize the real operator for shelve/unshelve/enable/disable transitions"
```

---

## Task 4: `SqliteStoreAndForwardSink` thread-safety nits (pending #6)

**Classification:** small
**Estimated implement time:** ~3 min
**Parallelizable with:** Task 1, Task 2, Task 3 (different assembly — `Core.AlarmHistorian`)

**The fixes (visibility-only, no functional behavior change):**
1. `_backoffIndex` (`~74`) is written by `BumpBackoff`/`ResetBackoff` (drain thread) and read by `CurrentBackoff` (status query thread) without a memory barrier → mark `volatile`.
2. The capacity-eviction log (`~659-661`) reads `_evictedCount` outside `_statusLock` (it's incremented inside the lock on `658`) → capture the total inside the lock and log the captured value.

**Files:**
- Modify: `src/Core/ZB.MOM.WW.OtOpcUa.Core.AlarmHistorian/SqliteStoreAndForwardSink.cs`

**Step 1: Make `_backoffIndex` volatile**

```csharp
    private volatile int _backoffIndex;
```

**Step 2: Capture `_evictedCount` under the lock for the log message**

Replace lines ~658-661:
```csharp
        Interlocked.Add(ref _queuedRowCount, -toEvict);
        long lifetimeEvicted;
        lock (_statusLock) { _evictedCount += toEvict; lifetimeEvicted = _evictedCount; }
        _logger.Warning(
            "Historian queue at capacity {Cap} — evicted {Count} oldest row(s) to make room (lifetime evictions: {Total})",
            _capacity, toEvict, lifetimeEvicted);
```

**Step 3: Build + run the sink suite (guards no regression)**

```bash
dotnet test tests/Core/ZB.MOM.WW.OtOpcUa.Core.AlarmHistorian.Tests
```
Expected: PASS (no behavior change; these are visibility/lock-scope fixes). No new test — thread-safety here isn't deterministically unit-testable; correctness is by inspection + the existing suite.

**Step 4: Commit**

```bash
git add src/Core/ZB.MOM.WW.OtOpcUa.Core.AlarmHistorian/SqliteStoreAndForwardSink.cs
git commit -m "fix(historian): volatile _backoffIndex + read _evictedCount under lock (thread-safety)"
```

---

## Task 5: Full-suite gate + docs + close out

**Classification:** small
**Estimated implement time:** ~4 min
**Parallelizable with:** none (depends on Tasks 1-4)

**Files:**
- Modify: `docs/ScriptedAlarms.md` and/or `docs/AlarmTracking.md` (historian config + `HistorizeToAveva` opt-out note)
- Modify: `pending.md` (strike the now-resolved items 1-6; keep item 7)

**Step 1: Build the whole solution**

```bash
dotnet build ZB.MOM.WW.OtOpcUa.slnx
```
Expected: 0 errors.

**Step 2: Run the full suite, capturing the real exit code**

```bash
dotnet test ZB.MOM.WW.OtOpcUa.slnx 2>&1 | tee /tmp/followups-test.log; echo "EXIT=${PIPESTATUS[0]}"
```
Expected: only the known pre-existing env/integration failures (AbCip/AbLegacy fixtures, OpcUaServer DualEndpoint/PKI, Host EquipmentNamespace deploy-Rejected) — NO new failures in `Core.ScriptedAlarms.Tests`, `Core.AlarmHistorian.Tests`, or `Runtime.Tests`. If anything in those three regresses, stop and fix before finishing. (Do NOT pipe to `tail` — it masks the exit code.)

**Step 3: Document the new behavior**

In the historian section of `docs/ScriptedAlarms.md` (and/or `docs/AlarmTracking.md`): note that (a) `HistorizeToAveva=false` now suppresses the durable historian write while the live `/alerts` UI still shows the transition; (b) the `AlarmHistorian` section exposes `DrainIntervalSeconds`, `Capacity`, `DeadLetterRetentionDays`; (c) an enabled historian logs a startup warning on empty `SharedSecret` or a relative `DatabasePath`.

**Step 4: Strike resolved items from `pending.md`**

Remove items 1-6 from `pending.md` (or mark them resolved in this branch) and leave item 7 (docker-dev rig cleanup, operational deferral). Note: `pending.md` is untracked — update it but it need not be committed unless the user asks.

**Step 5: Commit the docs**

```bash
git add docs/ScriptedAlarms.md docs/AlarmTracking.md
git commit -m "docs(historian): HistorizeToAveva opt-out + config knobs + startup validation"
```

**Step 6: Finish the branch**

Use **superpowers-extended-cc:finishing-a-development-branch** (verify tests → present the 4 options → execute the user's choice).

---

## Dependency spine

```
T0 (branch)
 ├─ T1 (HistorizeToAveva opt-out)      [high-risk]  ─┐
 │   └─ T2 (config knobs + validation) [standard]   │  (Runtime serial chain;
 │       └─ T3 (TransitionUser)        [small]       │   T1/T3 share a file)
 └─ T4 (sink thread-safety)            [small]      ─┘  (Core.AlarmHistorian — parallel)
              └──────────────┬───────────────┘
                             T5 (gate + docs + finish)  [blocked by T1,T2,T3,T4]
```

T4 is the only task safe to run concurrently with the Runtime chain. T1 → T2 → T3 serialize (same assembly; T1 and T3 edit `ScriptedAlarmHostActor.cs`).