lmxopcua/docs/plans/2026-06-10-script-log-and-scripted-alarm-runtime.md

# Script-log Engine Emit + Scripted-Alarm Runtime — Implementation Plan

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

**Goal:** Make the Script-log page tail real script output, and stand up scripted
alarms end-to-end including real OPC UA Part 9 condition nodes + client ack.

**Architecture:** Three sequenced layers off one shared seam (a root script logger
fanning to file + companion + a new DPS topic sink). Layer 0 = emit (F8 live). Layer 1
= F9 engine runtime on the Akka equipment-namespace runtime. Layer 2 = F14b real Part 9
nodes + events + inbound ack. Design: `docs/plans/2026-06-10-script-log-and-scripted-alarm-runtime-design.md`.
Verified gap analysis: `pending.md`.

**Tech:** .NET 10, Akka.NET, EF Core (SQL prod / InMemory tests), Serilog, OPC
Foundation UA .NET Standard, xUnit + Shouldly, Akka TestKit. No bUnit.

**Hard rules (every task):** 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** (`ScriptedAlarmState` table already exists). Agent does **not**
sign in to the AdminUI — the user drives live `/run`.

**Branch:** `feat/scriptlog-alarm-runtime` off `master @ df4c2657` (design committed there).

**Reference patterns to mirror:** `VirtualTagHostActor` (host actor shape),
`EfAlarmActorStateStore` (EF store shape), the `{{equip}}` two-seam parity work
(`Phase7Composer` ↔ `DeploymentArtifact`), `RoslynVirtualTagEvaluator` (evaluator).

---

# LAYER 0 — Shared script-log emit + F8 live

### Task 0: Branch + test-project check

**Classification:** small · **~2 min** · **Parallelizable with:** none

**Files:** none created (branch + verification only)

**Steps:**
1. `git switch -c feat/scriptlog-alarm-runtime` (off `master @ df4c2657`).
2. Confirm `tests/Core/ZB.MOM.WW.OtOpcUa.Core.Scripting.Tests/` exists and is in the
   `.slnx` (it does — `ScriptLoggerFactoryTests.cs` lives there). New Layer-0 tests land
   here. Confirm `tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/` for Layer-1 tests.
3. `dotnet build ZB.MOM.WW.OtOpcUa.slnx` — green baseline. Commit nothing.

---

### Task 1: `IScriptLogPublisher` + `ScriptLogTopicSink`

**Classification:** standard · **~4 min** · **Parallelizable with:** none

**Files:**
- Create: `src/Core/ZB.MOM.WW.OtOpcUa.Core.Scripting/IScriptLogPublisher.cs`
- Create: `src/Core/ZB.MOM.WW.OtOpcUa.Core.Scripting/ScriptLogTopicSink.cs`
- Test: `tests/Core/ZB.MOM.WW.OtOpcUa.Core.Scripting.Tests/ScriptLogTopicSinkTests.cs`
- Maybe modify: `Core.Scripting.csproj` (add ProjectReference to `Commons` for
  `ScriptLogEntry` if not already referenced — verify first).

**Step 1 — failing tests** (`ScriptLogTopicSinkTests`):
- A `LogEvent` (Information) with properties `ScriptId="S1"`, `VirtualTagId="V1"`,
  `EquipmentId="EQ1"`, message `"hello"` → publisher receives one `ScriptLogEntry` with
  those fields, `Level=="Information"`, `Message=="hello"`.
- `AlarmId` property maps to `ScriptLogEntry.AlarmId`; absent properties → null fields.
- A `Debug` event with default `minLevel=Information` → publisher receives **nothing**.
- Template message renders (`"v={V}"` + prop V=3 → `"v=3"`).
Use a fake `IScriptLogPublisher` capturing entries.

**Step 2 — run, expect fail** (types don't exist).

**Step 3 — implement:**
```csharp
public interface IScriptLogPublisher { void Publish(ScriptLogEntry entry); }

public sealed class ScriptLogTopicSink : ILogEventSink
{
    private readonly IScriptLogPublisher _publisher;
    private readonly LogEventLevel _min;
    public ScriptLogTopicSink(IScriptLogPublisher publisher,
        LogEventLevel min = LogEventLevel.Information) { _publisher = publisher; _min = min; }
    public void Emit(LogEvent e)
    {
        if (e is null || e.Level < _min) return;
        string? P(string k) => e.Properties.TryGetValue(k, out var v)
            && v is ScalarValue { Value: string s } ? s : null;
        _publisher.Publish(new ScriptLogEntry(
            ScriptId: P("ScriptId") ?? P("ScriptName") ?? "unknown",
            Level: e.Level.ToString(),
            Message: e.RenderMessage(),
            TimestampUtc: e.Timestamp.UtcDateTime,
            VirtualTagId: P("VirtualTagId"), AlarmId: P("AlarmId"), EquipmentId: P("EquipmentId")));
    }
}
```
(Property-name constants — reuse/extend `ScriptLoggerFactory`'s `ScriptNameProperty`;
add `ScriptIdProperty`/`VirtualTagIdProperty`/`AlarmIdProperty`/`EquipmentIdProperty`.)

**Step 4 — run tests, expect pass. Step 5 — commit** (`git add` the 3 files by path).

---

### Task 2: Root script logger + `DpsScriptLogPublisher` + Host wiring

**Classification:** standard · **~5 min** · **Parallelizable with:** none (depends T1)

**Files:**
- Create: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Scripting/DpsScriptLogPublisher.cs`
  (or Host — wherever the `ActorSystem`/`Mediator` is reachable at construction).
- Create: `src/Server/ZB.MOM.WW.OtOpcUa.Host/Logging/ScriptRootLoggerFactory.cs`
  (builds the root `ILogger`: rolling `scripts-*.log` + `ScriptLogCompanionSink` +
  `ScriptLogTopicSink`).
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Host/Program.cs` (build + register root logger;
  register `IScriptLogPublisher`).
- Test: `tests/.../Core.Scripting.Tests/ScriptRootLoggerFanoutTests.cs` (or Host.Tests).

**Steps (TDD):**
1. Failing test: a logger built by `ScriptRootLoggerFactory` with a fake publisher +
   in-memory companion → an `Error` event reaches the companion mirror AND the topic
   publisher; a `Debug` event reaches neither topic nor companion (file only). (Assert
   via fakes; don't assert the physical file.)
2. Implement `DpsScriptLogPublisher` — ctor takes the DPS mediator `IActorRef` (or
   `ActorSystem`); `Publish` → `mediator.Tell(new Publish("script-logs", entry))`
   (topic constant `VirtualTagActor.ScriptLogsTopic`).
3. Implement `ScriptRootLoggerFactory.Build(IScriptLogPublisher, config)` →
   `LoggerConfiguration().WriteTo.File(...).WriteTo.Sink(new ScriptLogCompanionSink(Log.Logger))
   .WriteTo.Sink(new ScriptLogTopicSink(publisher, minLevel)).CreateLogger()`.
4. `Program.cs`: resolve the mediator after the ActorSystem is up; register
   `IScriptLogPublisher` (singleton) + the root `ILogger` (keyed/named for scripts).
   Min-level from config (`Scripting:LogTopicMinLevel`, default `Information`).
5. Run + commit by path.

---

### Task 3: Rewire evaluators to the root script logger

**Classification:** standard · **~5 min** · **Parallelizable with:** none (depends T1, T2)

**Files:**
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Host/Engines/RoslynVirtualTagEvaluator.cs`
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Host/Engines/RoslynScriptedAlarmEvaluator.cs`
- Modify: `src/Core/ZB.MOM.WW.OtOpcUa.Core.Scripting/ScriptLoggerFactory.cs` (bind the
  full property set, not just `ScriptName`).
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Host/Program.cs` (inject root logger into the
  evaluators).
- Test: `tests/.../Core.Scripting.Tests/` — evaluator emits via fake publisher.

**Steps:**
1. Failing test: a `RoslynVirtualTagEvaluator` built with a root logger wired to a fake
   publisher; evaluate a script `ctx.Logger.Information("hi"); return 1;` → publisher
   gets one entry with `ScriptId`/`VirtualTagId` bound and `Message=="hi"`.
2. Replace the static `ScriptLogger` field with a ctor-injected root `ILogger`. Per
   evaluation, `var log = _root.ForContext("ScriptId", id).ForContext("VirtualTagId", virtualTagId)`
   (+ `EquipmentId` when available) and pass into the `VirtualTagContext`. Same for the
   alarm evaluator (binds `AlarmId`).
3. `ScriptLoggerFactory`: add a `Create(scriptId, virtualTagId?, alarmId?, equipmentId?)`
   overload binding the standard properties (keep the old `Create(scriptName)` for
   compatibility).
4. `Program.cs`: pass the root logger to both evaluator registrations.
5. Run + commit by path.

> Note: `IVirtualTagEvaluator.Evaluate` carries `virtualTagId`; in the live path
> `scriptId == virtualTagId`, so Layer 0 binds both from it. Threading a distinct
> `EquipmentId` (nice-to-have on the page) is optional here — if it requires an
> interface change, defer it to a Layer-1 follow-up rather than expanding T3.

---

### Task 4: Live-verify Layer 0

**Classification:** verification · **Parallelizable with:** none (depends T2, T3)

**Steps:**
1. Rebuild docker-dev central nodes (user-driven `/run`). Author a virtual tag whose
   script calls `ctx.Logger.Information(...)`.
2. Open `/script-log`; drive the dependency so the script evaluates; confirm the line
   appears live with the right ScriptId/level. Confirm Debug stays off the page,
   Information+ shows.
3. **Agent does not sign in** — user signs in and drives. Record outcome. No code unless
   a defect surfaces (→ new fix task).

---

# LAYER 1 — F9 engine runtime

### Task 5: `EquipmentScriptedAlarmPlan` + Phase7Composer enrichment

**Classification:** standard · **~5 min** · **Parallelizable with:** Task 7, Task 8

**Files:**
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Composer.cs` (new record +
  build the enriched list from `ScriptedAlarm` + `Script` rows).
- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Server.Tests/Phase7/` (or wherever Phase7Composer
  is tested) — new `Phase7ComposerScriptedAlarmTests.cs`.

**Steps:**
1. Failing test: compose two equipments each with a scripted alarm referencing a script;
   assert each `EquipmentScriptedAlarmPlan` carries the resolved `PredicateSource`,
   extracted `DependencyRefs` (via `DependencyExtractor`), `AlarmType`, `Severity`,
   `MessageTemplate`, `HistorizeToAveva`, `Retain`, `Enabled`, `Name`.
2. Add `public sealed record EquipmentScriptedAlarmPlan(string ScriptedAlarmId, string
   EquipmentId, string Name, string AlarmType, int Severity, string MessageTemplate,
   string PredicateScriptId, string PredicateSource, IReadOnlyList<string> DependencyRefs,
   bool HistorizeToAveva, bool Retain, bool Enabled);`
3. In `Compose`: join `ScriptedAlarm.PredicateScriptId → Script.SourceCode`; run
   `DependencyExtractor.Extract(source).Reads` (∪ `MessageTemplate` token paths) for
   `DependencyRefs`; project into the new list on the composition result. Skip
   `Enabled=false` alarms (or carry the flag — carry it; host decides). Drop alarms whose
   script is missing with a structured warning (don't throw the whole compose).
4. Run + commit by path.

---

### Task 6: DeploymentArtifact parity for the alarm plan

**Classification:** standard · **~5 min** · **Parallelizable with:** Task 7, Task 8 (depends T5)

**Files:**
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DeploymentArtifact.cs`
  (encode/decode `EquipmentScriptedAlarmPlan`; add
  `Phase7CompositionResult.EquipmentScriptedAlarms`; filter-by-equipment like
  `EquipmentVirtualTags` at :263).
- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/` — artifact round-trip + parity
  with the Composer for the same input.

**Steps:**
1. Failing test: build a composition via `Phase7Composer`, serialize to artifact, parse
   back → `EquipmentScriptedAlarms` is byte-identical (same discipline as the `{{equip}}`
   parity tests). Equipment-filter test (only alarms for resident equipment survive).
2. Add the field to `Phase7CompositionResult`; mirror the `EquipmentVirtualTags`
   encode/decode/filter exactly (`:202`, `:263`).
3. Run + commit by path.

---

### Task 7: `DependencyMuxTagUpstreamSource`

**Classification:** standard · **~4 min** · **Parallelizable with:** Task 5, Task 6, Task 8

**Files:**
- Create: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/DependencyMuxTagUpstreamSource.cs`
  (implements `Core.ScriptedAlarms`/`Core.VirtualTags` `ITagUpstreamSource`).
- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/ScriptedAlarms/DependencyMuxTagUpstreamSourceTests.cs`

**Steps:**
1. Failing tests: `Push(path, snapshot)` updates cache so `ReadTag(path)` returns it;
   `SubscribeTag(path, obs)` → `obs` fires on the next `Push`; `ReadTag` for an unknown
   path returns a Bad-quality snapshot; dispose removes the observer.
2. Implement: a thread-safe cache (`ConcurrentDictionary<string, DataValueSnapshot>`) +
   per-path observer list; `Push` updates cache then invokes observers; `ReadTag` reads
   cache (Bad if absent); `SubscribeTag` returns an `IDisposable` that deregisters. The
   host actor calls `Push` from its `DependencyValueChanged` handler. Value wrap:
   `new DataValueSnapshot(value, StatusCode:0, ts, ts)`.
3. Run + commit by path.

---

### Task 8: `EfAlarmConditionStateStore : IAlarmStateStore`

**Classification:** standard · **~5 min** · **Parallelizable with:** Task 5, Task 6, Task 7

**Files:**
- Create: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/EfAlarmConditionStateStore.cs`
- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/ScriptedAlarms/EfAlarmConditionStateStoreTests.cs`
  (in-memory EF).

**Steps:**
1. Failing tests (in-memory `OtOpcUaConfigDbContext`): `SaveAsync(state)` then
   `LoadAsync(alarmId)` round-trips Enabled/Acked/Confirmed/Shelving(+UnshelveAtUtc)/
   LastAck*/LastConfirm*/Comments; `LoadAsync` of an unknown id → null; `ActiveState`
   is **not** persisted (a saved state's Active is ignored on load — load returns the
   stored operator state, Active defaults). Comments JSON round-trips.
2. Implement mapping `AlarmConditionState` ↔ `ScriptedAlarmState` entity (mirror
   `EfAlarmActorStateStore`'s `IDbContextFactory` upsert pattern; serialize
   `ImmutableList<AlarmComment>` ↔ `CommentsJson`). Map enum states ↔ the entity's string
   columns.
3. Run + commit by path.

---

### Task 9: `ScriptedAlarmHostActor`

**Classification:** high-risk · **~5 min** · **Parallelizable with:** none (depends T6, T7, T8; needs Layer 0 T2/T3 root logger)

**Files:**
- Create: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/ScriptedAlarmHostActor.cs`
- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/ScriptedAlarms/ScriptedAlarmHostActorTests.cs`
  (Akka TestKit + a real engine with the fake upstream, or a fake engine seam).

**Design:** mirrors `VirtualTagHostActor`. Owns one `ScriptedAlarmEngine` (built with the
`DependencyMuxTagUpstreamSource`, the `EfAlarmConditionStateStore`, a `ScriptLoggerFactory`
wrapping the **Layer 0 root logger**, and the engine's root logger). Message
`ApplyScriptedAlarms(IReadOnlyList<EquipmentScriptedAlarmPlan> Plans)`.

**Steps:**
1. Failing TestKit tests:
   - `ApplyScriptedAlarms` with one alarm → engine loaded (assert via a probe/seam);
     registers interest with the (probe) mux for the alarm's dep refs.
   - A `DependencyValueChanged` that makes the predicate true → the host tells the
     (probe) `OpcUaPublishActor` a `WriteAlarmState(alarmId, active:true, …)`, tells the
     (probe) historian an `AlarmHistorianEvent` (when `HistorizeToAveva`), and publishes
     an `AlarmTransitionEvent` on `alerts`.
   - Re-`ApplyScriptedAlarms` with a different set reloads the engine (LoadAsync replace).
2. Implement: on `ApplyScriptedAlarms`, build `ScriptedAlarmDefinition`s from the plans
   (map `AlarmType`→`AlarmKind`, `Severity`→`AlarmSeverity`, `EquipmentId`→`EquipmentPath`),
   `engine.LoadAsync`; register mux interest for `⋃ DependencyRefs`; on
   `DependencyValueChanged` → `_upstream.Push(...)`. Subscribe `engine.OnEvent` once →
   map `ScriptedAlarmEvent.Condition` to `(active, acknowledged)` →
   `OpcUaPublishActor.WriteAlarmState`; map → `AlarmHistorianEvent` → historian (if
   Historize); publish `AlarmTransitionEvent` on `alerts`. Dispose engine in `PostStop`.
3. Run targeted tests (`dotnet test --filter ScriptedAlarmHostActor`). Commit by path.

---

### Task 10: Spawn + apply in DriverHostActor

**Classification:** standard · **~4 min** · **Parallelizable with:** none (depends T9)

**Files:**
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DriverHostActor.cs`
  (spawn `ScriptedAlarmHostActor` next to `VirtualTagHostActor` ~:197; tell
  `ApplyScriptedAlarms(composition.EquipmentScriptedAlarms)` next to the vtag apply ~:532;
  add an override field for tests like `_virtualTagHostOverride`).
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ServiceCollectionExtensions.cs` if the
  host needs new injected deps (EF store factory, root logger, historian ref).
- Test: extend `DriverHostActorTests` — apply pushes `ApplyScriptedAlarms`.

**Steps:** mirror the VirtualTag spawn/apply exactly; thread `_opcUaPublishActor`,
`_dependencyMux`, the EF store, the root logger, the historian actor ref. Run + commit.

---

### Task 11: Retire the orphaned actor + F9b evaluator

**Classification:** small · **~3 min** · **Parallelizable with:** none (depends T9, T10)

**Files:**
- Delete: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/ScriptedAlarmActor.cs`
  (+ its tests) and `src/Server/ZB.MOM.WW.OtOpcUa.Host/Engines/RoslynScriptedAlarmEvaluator.cs`.
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Host/Program.cs` (remove F9b DI registration,
  lines ~110-114) and any `IScriptedAlarmEvaluator` references. Keep
  `EfAlarmActorStateStore` only if nothing else uses it — otherwise delete with the actor.

**Steps:** delete, fix build, run full `dotnet test` for the touched projects, commit by
path. (If something unexpectedly depends on these, stop and surface — don't expand scope.)

---

### Task 12: Live-verify Layer 1

**Classification:** verification · **Parallelizable with:** none (depends T10, T11)

**Steps:** rebuild docker-dev; author a scripted alarm whose predicate references a live
tag; drive the tag; confirm the alarm node flips active/clear, the historian queue
advances (`/alarms/historian`), the `alerts`/Alerts page shows it, and predicate
`ctx.Logger` output appears on `/script-log`. User drives sign-in. Defects → new tasks.

---

# LAYER 2 — F14b real Part 9 + client ack

### Task 13: SDK research spike (DeepWiki)

**Classification:** small (research) · **~5 min** · **Parallelizable with:** Layer-1 tasks

**Steps:** Use the DeepWiki MCP (`OPCFoundation/UA-.NETStandard`) to confirm: how to
create + add an `AlarmConditionState` (and Limit/OffNormal/Discrete subtypes) under a
parent in a `CustomNodeManager2`; how to set ActiveState/AckedState/ConfirmedState/
ShelvingState/Severity/Retain; how transitions fire events (`ReportEvent`); how inbound
`Acknowledge`/`Shelve`/`Confirm` method calls are dispatched + where to hook them. Write
findings to `docs/v2/f14b-part9-sdk-notes.md` (committed). This de-risks T14-T17.

---

### Task 14: Real condition-node materialisation

**Classification:** high-risk · **~5 min** · **Parallelizable with:** none (depends T13)

**Files:** `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs` (replace the
placeholder `[active, ack]` variable in `WriteAlarmState` / add a `MaterialiseAlarmCondition`
path per `AlarmType`); `Phase7Applier.cs` (call the new materialiser); tests where the
SDK allows (node existence/type assertions).

**Steps:** create real condition nodes on materialise; keep `WriteAlarmState` as a thin
shim during transition or replace its callers. Run + commit. (SDK threading: all via the
pinned `OpcUaPublishActor` dispatcher.)

---

### Task 15: Richer alarm-state bridge

**Classification:** standard · **~4 min** · **Parallelizable with:** Task 17 (depends T14, T9)

**Files:** `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/OpcUa/OpcUaPublishActor.cs` (new message
carrying the full `AlarmConditionState`, not 2 bools); `ScriptedAlarmHostActor` bridge
(send the richer message); `OtOpcUaNodeManager` (apply full state to the condition).
Tests: message mapping.

---

### Task 16: Event firing on transition

**Classification:** high-risk · **~5 min** · **Parallelizable with:** none (depends T14, T15)

**Files:** `OtOpcUaNodeManager.cs` (`condition.ReportEvent(...)` on state change). Tests:
mapping/coverage where feasible; behaviour proven in T19.

---

# LAYER 2 — inbound client ack/shelve (re-scoped 2026-06-11)

> **Status:** T0–T16 are **merged to `master`** (Layers 0+1 live-verified; Layer 2 Part-9
> nodes/state/events done). The original single **T17 "Inbound method dispatch + ack plumbing"**
> (`high-risk · ~5 min`) proved to be **four separate hard problems**, each its own task. After a
> 2026-06-11 deep dive into the real code, T17 is split into **T17–T20** and the old T18–T20 shift
> to **T21–T24** (old T19's Client.CLI work also grew a feature half, T22). This is the deferred
> "fresh piece": branch off the **current** `master` (`git switch -c feat/scriptlog-alarm-ack`),
> not the old `feat/scriptlog-alarm-runtime` base.

### Layer 2 design decisions (resolved in the re-scope deep dive)

These are the load-bearing findings the new tasks rest on — verified against the current code, not
the original recon's assumptions:

1. **Topology — same-node co-location, multi-node ownership.** The OPC UA SDK server (+
   `OtOpcUaNodeManager`) and the `ScriptedAlarmHostActor` are **both spawned on every
   driver-role node** in the same `ActorSystem` (`OtOpcUaServerHostedService` +
   `DriverHostActor.SpawnScriptedAlarmHost`). So per node they're co-located and an in-process
   `Tell` would reach the local host. **But** in a multi-driver-node cluster each node owns a
   **disjoint** subset of alarms (its resident equipment, via the T6 artifact equipment-filter),
   and a client connects to **one** node's server. Whether that node owns the alarm the client
   acks is **not guaranteed**. **Decision:** route inbound commands over a new DPS topic
   `alarm-commands` (mirrors `alerts`/`script-logs`), and have each `ScriptedAlarmHostActor`
   **ignore commands for alarmIds its engine doesn't own**. This works same-node and cross-node
   with one mechanism. (Open item to confirm in T18: whether each node's address space is
   partitioned to its own equipment or replicated — if partitioned, a client can only ever ack
   local alarms and the DPS broadcast is still correct, just always locally satisfied.)

2. **The node manager has no Akka handle and must stay that way.** `OtOpcUaNodeManager(server,
   configuration)` (`OtOpcUaSdkServer.CreateMasterNodeManager`) holds **no** `IActorRef` /
   `ActorSystem` / DI. The existing **forward** seam is `OpcUaPublishActor → IOpcUaAddressSpaceSink
   (DeferredAddressSpaceSink → SdkAddressSpaceSink → node manager)`. For the **reverse** path the
   node manager gets a **settable command-router delegate** (`Action<AlarmCommand>`), wired at
   boot by `OtOpcUaServerHostedService` (which *does* have the DPS mediator) to publish onto
   `alarm-commands`. The node manager itself never touches Akka.

3. **No explicit re-projection after an engine op.** Every `ScriptedAlarmEngine` op
   (`AcknowledgeAsync`/`ConfirmAsync`/`OneShotShelveAsync`/`TimedShelveAsync`/`UnshelveAsync`/
   `EnableAsync`/`DisableAsync`/`AddCommentAsync` — all exist, signatures verified) raises the
   engine's `OnEvent`, which the host's **existing** `OnEngineEmission` already projects to the
   node. So the inbound handler just calls the op and awaits — the ack visibly updates the node
   for free. This makes T19 small.

4. **Roles are dropped at the impersonation seam.** `OpcUaApplicationHost.cs:292` does
   `args.Identity = new UserIdentity(token)` and **discards** `result.Roles` (only logs them at
   :293). `OpcUaUserAuthResult.Roles` is `IReadOnlyList<string>` (`ReadOnly`/`WriteOperate`/
   `WriteTune`/`WriteConfigure`/`AlarmAck`); there is an `OpcUaOperation` enum
   (`Core.Abstractions`) with `AlarmAcknowledge`/`AlarmConfirm`/`AlarmShelve`, but **no role is
   consulted anywhere post-auth today** (writes aren't gated either — this is greenfield, not a
   pattern to copy). **Risk (drives T17 being its own task):** it is **unconfirmed** that a custom
   `UserIdentity` subclass survives the SDK round-trip back to `context.UserIdentity` inside a
   method handler. T17 must *prove* the round-trip (integration assertion); fallback is populating
   `GrantedRoleIds` (`NodeIdCollection`) by mapping role strings → role NodeIds, which is more work.

5. **Double-emit is real, and delta-gating resolves it.** `WriteAlarmCondition` calls
   `ReportConditionEvent` **unconditionally** (`OtOpcUaNodeManager.cs:156`); the node manager keeps
   **no** previous snapshot. Once inbound acks route through the engine, the SDK's own
   `OnAcknowledgeCalled` auto-fires event E2 (applying acked state to the node) **and** the engine
   round-trip re-projects → would fire E3. Because the SDK applies the acked state *before* the
   async engine round-trip completes, **delta-gating `WriteAlarmCondition` against the node's
   current state** suppresses E3 (no delta) while still firing on genuine engine-driven
   transitions. That's T20. (Fallback if it proves racy: the correlation-suppression option already
   sketched in the `:190-198` in-code note — skip engine re-projection for inbound-originated
   transitions.)

---

### Task 17: Carry LDAP roles onto the OPC UA session identity

**Classification:** high-risk · **~5 min** · **Parallelizable with:** Task 22

**Files:**
- Create: `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Security/RoleCarryingUserIdentity.cs`
  (`: UserIdentity`, adds `IReadOnlyList<string> Roles`).
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OpcUaApplicationHost.cs:292`
  (`args.Identity = new RoleCarryingUserIdentity(token, result.Roles)`).
- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/OpcUaApplicationHostImpersonationTests.cs`
  (existing home for `HandleImpersonation`).

**Steps:**
1. **Round-trip spike FIRST (de-risk the whole task).** Before building anything, confirm the SDK
   preserves a custom `IUserIdentity` instance: in a booted in-process server test (mirror
   `SdkAddressSpaceSinkTests`' server fixture), set `args.Identity` to a sentinel subclass during
   impersonation and assert a method handler reads it back via
   `(context as ISessionOperationContext)?.UserIdentity` **as that subclass**. If it does NOT
   survive (SDK wraps/strips it), STOP and switch to the `GrantedRoleIds` approach — surface this
   as a scope change, don't silently expand.
2. Failing unit test: `HandleImpersonation` on a successful auth sets `args.Identity` to a
   `RoleCarryingUserIdentity` whose `Roles` equals `result.Roles` (and the existing
   identity/denial/anonymous tests still pass).
3. Implement `RoleCarryingUserIdentity` + the one-line `:292` swap.
4. Run (`OpcUaServer.Tests` + the impersonation tests) + commit by path.

> Security-path change → high-risk. Touches only the identity construction; no auth-decision logic
> changes (roles were already resolved, just discarded). Do **not** change `IOpcUaUserAuthenticator`
> or the LDAP bind.

---

### Task 18: Node-manager command router + `AlarmAck` veto gate + `alarm-commands` topic

**Classification:** high-risk · **~5 min** · **Parallelizable with:** none (depends T17)

**Files:**
- Create: `src/Core/ZB.MOM.WW.OtOpcUa.Commons/OpcUa/AlarmCommand.cs`
  (`record AlarmCommand(string AlarmId, string Operation, string User, string? Comment, DateTime? UnshelveAtUtc)`;
  `Operation` ∈ Acknowledge/Confirm/OneShotShelve/TimedShelve/Unshelve/Enable/Disable/AddComment).
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs` — add a settable
  `Action<AlarmCommand>? AlarmCommandRouter`; in `MaterialiseAlarmCondition` (after `Create` +
  initial state, before `AddChild`) wire `alarm.OnAcknowledge`/`OnConfirm`/`OnAddComment`/
  `OnShelve`/`OnTimedUnshelve`. Each delegate: (a) read principal via
  `(context as ISessionOperationContext)?.UserIdentity as RoleCarryingUserIdentity`, **gate on
  `AlarmAck`** → return `StatusCodes.BadUserAccessDenied` if absent; (b) invoke `AlarmCommandRouter`
  with the mapped `AlarmCommand` (so the engine updates the **domain** store + audit + alerts
  historization); (c) return `ServiceResult.Good` so the SDK applies node state + auto-fires (the
  engine re-projection is de-duped in T20).
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaSdkServer.cs` (pass-through to expose
  the router setter on the node manager).
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Host/OpcUa/OtOpcUaServerHostedService.cs` (after the server
  starts + node manager exists: resolve the DPS mediator, set the router to
  `mediator.Tell(new Publish(ScriptedAlarmHostActor.AlarmCommandsTopic, cmd))`).
- Add the topic const `AlarmCommandsTopic = "alarm-commands"` on `ScriptedAlarmHostActor` (used here
  and in T19).
- Test: `OpcUaServer.Tests` — veto gate allows with `AlarmAck` / denies without (drive a wired
  condition's `OnAcknowledge` with a `RoleCarryingUserIdentity` context); router invoked with the
  correctly-mapped `AlarmCommand` (fake `Action`).

**Steps:** TDD the gate + router-mapping in the node manager; then the SDK-server pass-through; then
the hosted-service wiring (no unit test for the boot wiring — exercised by T23 live-verify). Commit
by path. **Serialize with T20** (both touch `OtOpcUaNodeManager.cs`).

---

### Task 19: `ScriptedAlarmHostActor` inbound command handler

**Classification:** standard · **~4 min** · **Parallelizable with:** Task 20 (depends T18)

**Files:**
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/ScriptedAlarmHostActor.cs` —
  subscribe to `AlarmCommandsTopic` in `PreStart` (alongside the existing `_mediator` use);
  `Receive<AlarmCommand>(OnAlarmCommand)`; `OnAlarmCommand` is `async void`, switches on
  `Operation` → the matching `engine.<Op>Async(AlarmId, User, …, CancellationToken.None)`.
  **Ownership filter:** if the engine doesn't own `AlarmId`, no-op (multi-node broadcast). Catch +
  log op failures (mirror `OnLoadFailed`). **No explicit re-projection** — the engine's `OnEvent`
  drives the existing `OnEngineEmission` → node update.
- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/ScriptedAlarms/ScriptedAlarmHostActorTests.cs`
  (extend) — TestKit: an `AlarmCommand{Operation="Acknowledge"}` for a loaded alarm calls the
  engine's `AcknowledgeAsync` (fake/probe engine seam); an unknown `AlarmId` is ignored;
  `TimedShelve` without `UnshelveAtUtc` is rejected/logged, not thrown.

**Steps:** TDD via the existing host-actor test seam; run `dotnet test --filter ScriptedAlarmHostActor`;
commit by path.

---

### Task 20: Delta-gate event firing (kill the inbound double-emit)

**Classification:** high-risk · **~4 min** · **Parallelizable with:** Task 19 (depends T18)

**Files:**
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs` — keep a
  `ConcurrentDictionary<string, AlarmConditionSnapshot> _lastAlarmState`; in `WriteAlarmCondition`,
  after projecting, compare the new `state` to the stored snapshot and **only call
  `ReportConditionEvent` when it differs** (then store it). Replace the now-stale `:151-156`
  "fire exactly one event" comment + tighten the `:190-198` double-emit note to "resolved by
  delta-gate".
- Test: `tests/.../OpcUaServer.Tests/SdkAddressSpaceSinkTests.cs` (extend) — two identical
  `WriteAlarmCondition` calls fire the condition event **once**; a changed call fires again.
  (Assert via an event-count probe / monitored-item on the booted server fixture.)

**Steps:** TDD the delta-gate; run `OpcUaServer.Tests`; commit by path. If the booted-server test
can't cleanly count events, fall back to asserting the gate's decision via a seam and prove
end-to-end in T23. **Serialize after T18** (same file).

---

### Task 21: AdminUI ack/shelve control

**Classification:** standard · **~5 min** · **Parallelizable with:** none (depends T19)

**Files:**
- Create: `src/Core/ZB.MOM.WW.OtOpcUa.Commons/Messages/Admin/AcknowledgeAlarmCommand.cs` +
  `ShelveAlarmCommand.cs` (control-plane messages, mirror `StartDeployment`'s shape with a
  `CorrelationId`).
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.ControlPlane/AdminOperations/AdminOperationsActor.cs`
  (the existing admin-pinned cluster singleton) — `ReceiveAsync` handlers that publish onto
  `alarm-commands` (reusing T18's topic + the host's ownership filter → the singleton solves
  cross-node routing for the AdminUI path too).
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Clients/AdminOperationsClient.cs`
  (+ its interface) — `AcknowledgeAlarmAsync` / `ShelveAlarmAsync` (mirror `StartDeploymentAsync`).
- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Alerts.razor` — per-row
  Acknowledge / Shelve buttons → `IAdminOperationsClient`; operator from
  `AuthState … User.Identity?.Name`.
- Test: the control-plane command service + the new `AdminOperationsActor` handlers (TestKit / Ask).
  **No bUnit** — the razor is proven in T23.

**Steps:** TDD the messages + actor handlers + client; wire the razor; run + commit by path.

---

### Task 22: Client.CLI ack / confirm / shelve commands

**Classification:** standard · **~5 min** · **Parallelizable with:** Task 17–T21 (disjoint `Client.*`)

**Files:**
- Modify: `src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/IOpcUaClientService.cs` +
  `OpcUaClientService.cs` — `AcknowledgeAlarmAsync` already declared (no command wires it yet); add
  `ConfirmAlarmAsync` + `ShelveAlarmAsync` (call the SDK `Confirm`/`OneShotShelve`/`TimedShelve`/
  `Unshelve` methods on the condition).
- Create: `src/Client/ZB.MOM.WW.OtOpcUa.Client.CLI/Commands/{Acknowledge,Confirm,Shelve}Command.cs`
  (`--node`, `--event-id`, `--comment`; shelve adds `--kind OneShot|Timed --unshelve-at`).
- Test: unit-test what's pure (arg→request mapping); the live round-trip is T23.

**Steps:** add the service methods + CLI commands; build; commit by path. This is **net-new client
feature work** (the reason old "T19 verification" couldn't just be a verify pass).

---

### Task 23: Live-verify Layer 2 end-to-end

**Classification:** verification · **Parallelizable with:** none (depends T18, T19, T20, T21, T22)

**Steps:** docker-dev up. Use the **already-deployed `t12-overheat`** alarm (rig state, below) as the
live condition. With `Client.CLI`: `alarms --refresh` shows the real condition; drive
`TestMachine_002.TestChangingInt` past the predicate so it fires an event on transition; call the new
`acknowledge` command → confirm the ack **round-trips** (node `AckedState` flips, exactly **one** ack
event fires — no double-emit, T20 — state **persists** across a node restart). Repeat the ack from
the AdminUI `/alerts` buttons (T21) and confirm parity. Verify the `AlarmAck` gate: a user **without**
`AlarmAck` is denied (`BadUserAccessDenied`). **Agent does not sign in** — user drives. Defects → new
fix tasks.

---

### Task 24: Docs + cleanup + finish branch

**Classification:** small · **~5 min** · **Parallelizable with:** none (depends all)

**Files:** update `docs/ScriptedAlarms.md`, `docs/VirtualTags.md`, `docs/v2/Runtime.md`,
`docs/AlarmTracking.md` (the inbound-ack + `AlarmAck`-gate flow is now real); **correct the stale
`docs/v2/phase-7-status.md` alarm-runtime status**; CLAUDE.md note. **Clean up the deliberately-left
rig artifacts** (`t12-overheat`, script `SC-ba675b168a85`, the `layer0-logcheck` vtag, and revert
filler-02's inert `cycle-time-s` logger line — redeploy). Delete/condense `resume.md` + `pending.md`.
Then run superpowers-extended-cc:finishing-a-development-branch (full `dotnet test`, merge to master).

---

## Execution notes

- **Parallel dispatch (Layers 0+1, done):** Layer 0 serial (T1→T2→T3→T4). Layer 1: **T5→T6** serial;
  **T7, T8 parallel** with T5/T6; T9 waits on T6/T7/T8; T10→T11→T12 serial.
- **Parallel dispatch (Layer 2 remainder, T17–T24):**
  - **T17** first (roles) — its **step-1 round-trip spike is a go/no-go gate** for the gate design.
  - **T18** after T17 (the veto gate needs the roles). **T19 ∥ T20** after T18 (disjoint files:
    `ScriptedAlarmHostActor.cs` vs `OtOpcUaNodeManager.cs`).
  - **T22 runs in parallel with the whole T17–T21 server chain** (only `Client.*` files).
  - **T21** after T19. **T23** after T18/T19/T20/T21/T22. **T24** last.
- **One writer at a time** within a shared file: `OtOpcUaNodeManager.cs` is touched by **T18 and
  T20 — serialize T18 → T20**. (Layers 0/1 already merged, so Program.cs/T14-T16 contention is moot.)
- **Layer boundaries are natural checkpoints** — Layers 0+1 shipped; the T17 round-trip spike is the
  next gate before committing to the rest of the Layer 2 inbound epic.