refactor(opcuaserver): rename Phase7* address-space pipeline to AddressSpace*

The OPC UA address-space build pipeline was named after a v2-roadmap milestone number rather than its domain. Rename the family to describe what it does (build/diff/apply the OPC UA address space): Phase7Composer -> AddressSpaceComposer Phase7CompositionResult -> AddressSpaceComposition Phase7Planner -> AddressSpacePlanner Phase7Plan -> AddressSpacePlan Phase7Applier -> AddressSpaceApplier Phase7ApplyOutcome -> AddressSpaceApplyOutcome The 9 Phase7*Tests suites follow suit; Phase7ScriptingEntitiesTests -> ScriptingEntitiesTests (it tests the scripting migration, not the pipeline). Log-message prefixes move to the new class names. Pure mechanical rename, no behavioral change. EF migration classes/IDs (AddPhase7ScriptingTables, ExtendComputeGenerationDiffWithPhase7) are immutable and left untouched, as are historical design docs. Build clean; OpcUaServer 261/261, Runtime 272/272, ScriptingEntities 12/12 green.
2026-06-18 19:16:28 -04:00
parent 6af54ac935
commit 40e8a23e7c
44 changed files with 364 additions and 364 deletions
@@ -0,0 +1,436 @@
+using Microsoft.Extensions.Logging;
+using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+
+namespace ZB.MOM.WW.OtOpcUa.OpcUaServer;
+
+/// <summary>
+///     Side-effecting orchestrator over <see cref="AddressSpacePlan"/>. Drives an
+///     <see cref="IOpcUaAddressSpaceSink"/> to materialise the diff between two
+///     <see cref="AddressSpaceComposition"/> snapshots:
+///
+///     <list type="bullet">
+///         <item>RemovedEquipment / RemovedAlarms — write Bad-quality on every removed
+///             node id then call <c>RebuildAddressSpace</c> at the end so the sink can
+///             actually tear down the OPC UA folders + variables.</item>
+///         <item>AddedEquipment / AddedAlarms — same Rebuild trigger (real SDK NodeManager
+///             will repopulate from the persisted artifact). For now we record the work.</item>
+///         <item>ChangedEquipment / ChangedAlarms — record what changed; the SDK adapter
+///             that lands in F10b will decide between in-place property writes and
+///             tear-down + rebuild.</item>
+///     </list>
+///
+///     This is the side-effecting layer Task 47 deferred to F14. It stays pure-of-SDK so
+///     production binds a real SDK sink, dev/Mac binds <see cref="NullOpcUaAddressSpaceSink"/>,
+///     and tests can capture every call.
+/// </summary>
+public sealed class AddressSpaceApplier
+{
+    private readonly IOpcUaAddressSpaceSink _sink;
+    private readonly ILogger<AddressSpaceApplier> _logger;
+
+    /// <summary>Initializes a new instance of the AddressSpaceApplier class.</summary>
+    /// <param name="sink">The OPC UA address space sink to apply changes to.</param>
+    /// <param name="logger">The logger instance.</param>
+    public AddressSpaceApplier(IOpcUaAddressSpaceSink sink, ILogger<AddressSpaceApplier> logger)
+    {
+        ArgumentNullException.ThrowIfNull(sink);
+        ArgumentNullException.ThrowIfNull(logger);
+        _sink = sink;
+        _logger = logger;
+    }
+
+    /// <summary>
+    ///     Apply <paramref name="plan"/> to the sink. Returns a summary of what was applied so
+    ///     callers (OpcUaPublishActor) can correlate the work back to the originating deployment.
+    /// </summary>
+    /// <param name="plan">The plan to apply.</param>
+    /// <returns>A AddressSpaceApplyOutcome summarizing the applied changes.</returns>
+    public AddressSpaceApplyOutcome Apply(AddressSpacePlan plan)
+    {
+        ArgumentNullException.ThrowIfNull(plan);
+
+        if (plan.IsEmpty)
+        {
+            _logger.LogDebug("AddressSpaceApplier: plan is empty; skipping sink writes");
+            return new AddressSpaceApplyOutcome(RemovedNodes: 0, AddedNodes: 0, ChangedNodes: 0, RebuildCalled: false);
+        }
+
+        var ts = DateTime.UtcNow;
+        var removedCount = 0;
+        foreach (var eq in plan.RemovedEquipment)
+        {
+            SafeWriteAlarmCondition(eq.EquipmentId, RemovedConditionState, ts);
+            removedCount++;
+        }
+        foreach (var alarm in plan.RemovedAlarms)
+        {
+            SafeWriteAlarmCondition(alarm.ScriptedAlarmId, RemovedConditionState, ts);
+            removedCount++;
+        }
+        // Removed equipment tags / VirtualTags are plain variable nodes (no Part 9 condition to write
+        // before tear-down), but they ARE real removals — count them so AddressSpaceApplyOutcome.RemovedNodes
+        // is accurate on a removed-tag-only deploy, which now reaches the rebuild path below.
+        removedCount += plan.RemovedEquipmentTags.Count + plan.RemovedEquipmentVirtualTags.Count;
+
+        var changedCount =
+            plan.ChangedEquipment.Count + plan.ChangedDrivers.Count + plan.ChangedAlarms.Count +
+            plan.ChangedEquipmentTags.Count +
+            plan.ChangedEquipmentVirtualTags.Count;
+        var addedCount =
+            plan.AddedEquipment.Count + plan.AddedDrivers.Count + plan.AddedAlarms.Count +
+            plan.AddedEquipmentTags.Count +
+            plan.AddedEquipmentVirtualTags.Count;
+
+        // Any add / remove / in-place CHANGE of Equipment, ScriptedAlarm, Equipment tag, or Equipment
+        // VirtualTag topology requires a real address-space rebuild — the materialise passes re-derive
+        // every node from the composition, so a changed-only deploy (e.g. a renamed equipment, a
+        // re-severitied alarm, a flipped tag dataType) must still rebuild or the running server keeps
+        // the stale node.
+        // ChangedDrivers is deliberately EXCLUDED: a driver-instance config change doesn't touch the
+        // address-space topology — it routes through DriverHostActor's spawn-plan in Runtime, which
+        // re-spawns the affected driver actor without re-materialising any nodes.
+        // F10b (vtag skip): a CHANGED VirtualTag whose ONLY differences are Expression/DependencyRefs/
+        // Historize is node-IRRELEVANT (see VtagDeltaIsNodeIrrelevant) — its materialised node is
+        // byte-identical and the vtag engine adopts those edits via VirtualTagHostActor's INDEPENDENT
+        // respawn (DriverHostActor → ApplyVirtualTags), so it skips the rebuild and PRESERVES every
+        // client's server-wide subscriptions. Any structural / node-affecting vtag change (Name/
+        // FolderPath/DataType) — or any non-vtag change anywhere — still forces a full rebuild.
+        // F10b (surgical tag write): a CHANGED equipment tag whose ONLY differences are Writable /
+        // IsHistorized / HistorianTagname (a plain value variable — no alarm condition node) can be
+        // updated IN PLACE on the existing node via ISurgicalAddressSpaceSink.UpdateTagAttributes
+        // (see TagDeltaIsSurgicalEligible), again avoiding the full rebuild and preserving subscriptions.
+        // Any other tag difference (DataType/IsArray/ArrayLength/FullName/identity/alarm) — or a sink
+        // that lacks the surgical capability, or a node that turns out missing — falls back to a full
+        // rebuild (safe default).
+        var structuralRebuild =
+            plan.AddedEquipment.Count > 0 || plan.RemovedEquipment.Count > 0 || plan.ChangedEquipment.Count > 0 ||
+            plan.AddedAlarms.Count > 0 || plan.RemovedAlarms.Count > 0 || plan.ChangedAlarms.Count > 0 ||
+            plan.AddedEquipmentTags.Count > 0 || plan.RemovedEquipmentTags.Count > 0 ||
+            plan.ChangedEquipmentTags.Any(d => !TagDeltaIsSurgicalEligible(d)) ||
+            plan.AddedEquipmentVirtualTags.Count > 0 || plan.RemovedEquipmentVirtualTags.Count > 0 ||
+            plan.ChangedEquipmentVirtualTags.Any(d => !VtagDeltaIsNodeIrrelevant(d));
+
+        var surgicalTagDeltas = plan.ChangedEquipmentTags.Where(TagDeltaIsSurgicalEligible).ToList();
+        var rebuilt = false;
+
+        if (structuralRebuild)
+        {
+            SafeRebuild();
+            rebuilt = true;
+        }
+        else if (surgicalTagDeltas.Count > 0)
+        {
+            if (_sink is ISurgicalAddressSpaceSink surgical)
+            {
+                var allApplied = true;
+                foreach (var d in surgicalTagDeltas)
+                {
+                    // Compute the node id + writable + historian EXACTLY as MaterialiseEquipmentTags would
+                    // so the in-place update matches what a rebuild would have produced.
+                    var nodeId = EquipmentNodeIds.Variable(d.Current.EquipmentId, d.Current.FolderPath, d.Current.Name);
+                    var writable = d.Current.Writable && !d.Current.IsArray;
+                    var historian = d.Current.IsHistorized
+                        ? (string.IsNullOrWhiteSpace(d.Current.HistorianTagname) ? d.Current.FullName : d.Current.HistorianTagname)
+                        : null;
+                    bool ok;
+                    try { ok = surgical.UpdateTagAttributes(nodeId, writable, historian); }
+                    catch (Exception ex)
+                    {
+                        _logger.LogError(ex, "AddressSpaceApplier: surgical UpdateTagAttributes threw for {Node}", nodeId);
+                        ok = false;
+                    }
+                    if (!ok) { allApplied = false; break; }
+                }
+                if (!allApplied) { SafeRebuild(); rebuilt = true; }
+            }
+            else
+            {
+                // Sink lacks the surgical capability ⇒ rebuild (safe default).
+                SafeRebuild();
+                rebuilt = true;
+            }
+        }
+
+        _logger.LogInformation(
+            "AddressSpaceApplier: applied plan (added={Added}, removed={Removed}, changed={Changed}, surgicalTags={Surgical}, rebuild={Rebuild})",
+            addedCount, removedCount, changedCount, rebuilt ? 0 : surgicalTagDeltas.Count, rebuilt);
+
+        return new AddressSpaceApplyOutcome(removedCount, addedCount, changedCount, rebuilt);
+    }
+
+    private void SafeRebuild()
+    {
+        try
+        {
+            _sink.RebuildAddressSpace();
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "AddressSpaceApplier: sink.RebuildAddressSpace threw");
+        }
+    }
+
+    /// <summary>
+    ///     #85 — build the UNS Area/Line/Equipment folder hierarchy in the address space from a
+    ///     composition snapshot. Called by <c>OpcUaPublishActor</c> after a rebuild so OPC UA
+    ///     clients browsing the server see proper folder structure instead of flat tag ids.
+    ///     Idempotent: each <c>EnsureFolder</c> call returns the existing folder if already
+    ///     present, so re-applies are cheap.
+    /// </summary>
+    /// <param name="composition">The composition result containing the hierarchy to materialise.</param>
+    public void MaterialiseHierarchy(AddressSpaceComposition composition)
+    {
+        ArgumentNullException.ThrowIfNull(composition);
+
+        foreach (var area in composition.UnsAreas)
+        {
+            SafeEnsureFolder(area.UnsAreaId, parentNodeId: null, displayName: area.DisplayName);
+        }
+        foreach (var line in composition.UnsLines)
+        {
+            SafeEnsureFolder(line.UnsLineId, parentNodeId: line.UnsAreaId, displayName: line.DisplayName);
+        }
+        foreach (var equipment in composition.EquipmentNodes)
+        {
+            // Equipment with no UnsLineId (legacy / dev rows) hang under the root.
+            var parent = string.IsNullOrWhiteSpace(equipment.UnsLineId) ? null : equipment.UnsLineId;
+            SafeEnsureFolder(equipment.EquipmentId, parentNodeId: parent, displayName: equipment.DisplayName);
+        }
+
+        _logger.LogInformation(
+            "AddressSpaceApplier: hierarchy materialised (areas={Areas}, lines={Lines}, equipment={Equipment})",
+            composition.UnsAreas.Count, composition.UnsLines.Count, composition.EquipmentNodes.Count);
+    }
+
+    /// <summary>
+    ///     Materialise Equipment-namespace tags from a composition snapshot.
+    ///     For each <see cref="EquipmentTagPlan"/>,
+    ///     ensure its optional <c>FolderPath</c> sub-folder under the existing equipment folder, then
+    ///     ensure a Variable (NodeId = <c>FullName</c>, the driver-side ref) inside it. Variables
+    ///     start BadWaitingForInitialData; the driver fills live values in a later milestone.
+    ///     Idempotent.
+    ///     <para>
+    ///         <b>Task 0 architecture decisions (recorded per the equipment-namespace-structure
+    ///         plan).</b> Decision #1 = <b>A</b> — a sink-based pass, NOT a reuse of
+    ///         <c>EquipmentNodeWalker</c>: no sink-backed <c>IAddressSpaceBuilder</c> adapter exists
+    ///         (<c>GenericDriverNodeManager.CapturingBuilder</c> decorates another builder, not the
+    ///         sink), and the walker re-creates the whole Area/Line/Equipment tree with browse-path
+    ///         NodeIds — incompatible with this path's logical-Id NodeIds (decision #3) and the
+    ///         already-materialised equipment folders (decision #4). Decision #4 = this pass adds
+    ///         ONLY variables (and any per-tag sub-folder); <see cref="MaterialiseHierarchy"/> owns
+    ///         the equipment folders and this pass never re-creates them. The sink's
+    ///         <c>EnsureVariable</c> takes a plain <c>string dataType</c> (not a DriverAttributeInfo).
+    ///     </para>
+    /// </summary>
+    /// <param name="composition">The composition result containing the equipment tags to materialise.</param>
+    public void MaterialiseEquipmentTags(AddressSpaceComposition composition)
+    {
+        ArgumentNullException.ThrowIfNull(composition);
+        if (composition.EquipmentTags.Count == 0) return;
+
+        // Sub-folders first — a tag's FolderPath becomes one folder UNDER its equipment folder
+        // (deduped per distinct equipment+path). Tags with no FolderPath hang directly under the
+        // equipment folder, which MaterialiseHierarchy already created (decision #4: never re-create
+        // the equipment folder here).
+        var foldersCreated = new HashSet<string>(StringComparer.Ordinal);
+        foreach (var tag in composition.EquipmentTags)
+        {
+            if (string.IsNullOrWhiteSpace(tag.FolderPath)) continue;
+            var folderNodeId = EquipmentNodeIds.SubFolder(tag.EquipmentId, tag.FolderPath);
+            if (!foldersCreated.Add(folderNodeId)) continue;
+            SafeEnsureFolder(folderNodeId, parentNodeId: tag.EquipmentId, displayName: tag.FolderPath);
+        }
+
+        // Variables: NodeId is FOLDER-SCOPED ("<parent>/<Name>"), NOT the raw FullName — a driver
+        // ref (e.g. a Modbus register) is not unique across identical machines, so FullName-as-NodeId
+        // would collide in the sink (EnsureVariable keys on NodeId) and drop all but one machine's
+        // signal. The driver-side FullName lives on EquipmentTagPlan for the later values milestone to
+        // route by. Parent is the FolderPath sub-folder when set, else the equipment folder directly.
+        // Per-variable idempotency relies on the sink's own EnsureVariable.
+        foreach (var tag in composition.EquipmentTags)
+        {
+            var parent = string.IsNullOrWhiteSpace(tag.FolderPath)
+                ? tag.EquipmentId
+                : EquipmentNodeIds.SubFolder(tag.EquipmentId, tag.FolderPath);
+            var nodeId = EquipmentNodeIds.Variable(tag.EquipmentId, tag.FolderPath, tag.Name);
+            if (tag.Alarm is not null)
+            {
+                // Native alarm tag → a real Part 9 condition node (reuses the scripted-alarm path),
+                // NOT a value variable. Parent is the sub-folder when set, else the equipment folder.
+                SafeMaterialiseAlarmCondition(nodeId, parent, tag.Name, tag.Alarm.AlarmType, tag.Alarm.Severity, isNative: true);
+            }
+            else
+            {
+                // Phase C: a historized tag materialises Historizing + HistoryRead. Resolve the effective
+                // historian tagname HERE (default-vs-override): a null/blank override falls back to the
+                // driver-side FullName; null means the tag is not historized at all.
+                string? historianTagname = tag.IsHistorized
+                    ? (string.IsNullOrWhiteSpace(tag.HistorianTagname) ? tag.FullName : tag.HistorianTagname)
+                    : null;
+                // Array writes are out of scope (Phase 4c read-only surface): force array tags read-only
+                // even if authored ReadWrite, so a client write cannot reach the driver write path which
+                // does not handle arrays (e.g. S7 BoxValueForWrite would crash).
+                var writable = tag.Writable && !tag.IsArray;
+                SafeEnsureVariable(nodeId, parent, tag.Name, tag.DataType, writable, historianTagname, tag.IsArray, tag.ArrayLength);
+            }
+        }
+
+        _logger.LogInformation(
+            "AddressSpaceApplier: equipment tags materialised (tags={Tags}, equipment={Equipment})",
+            composition.EquipmentTags.Count,
+            composition.EquipmentTags.Select(t => t.EquipmentId).Distinct(StringComparer.Ordinal).Count());
+    }
+
+    /// <summary>
+    ///     Materialise Equipment-namespace VirtualTags from a composition snapshot — the VirtualTag
+    ///     analogue of <see cref="MaterialiseEquipmentTags"/>. For each <see cref="EquipmentVirtualTagPlan"/>,
+    ///     ensure its optional <c>FolderPath</c> sub-folder under the existing equipment folder (in
+    ///     practice <c>FolderPath</c> is empty for VirtualTags, so this is usually a no-op), then ensure
+    ///     a Variable inside it. Like the tag pass, the variable's NodeId is FOLDER-SCOPED
+    ///     (<c>parent/Name</c>) — NOT the <see cref="EquipmentVirtualTagPlan.VirtualTagId"/> or
+    ///     <see cref="EquipmentVirtualTagPlan.Expression"/> — so identically-named VirtualTags on
+    ///     different equipments never collide in the sink (which keys on NodeId). Variables start
+    ///     BadWaitingForInitialData; <c>VirtualTagActor</c> fills live values in a later milestone.
+    ///     Idempotent (per-variable idempotency relies on the sink's own <c>EnsureVariable</c>).
+    /// </summary>
+    /// <param name="composition">The composition result containing the equipment VirtualTags to materialise.</param>
+    public void MaterialiseEquipmentVirtualTags(AddressSpaceComposition composition)
+    {
+        ArgumentNullException.ThrowIfNull(composition);
+        if (composition.EquipmentVirtualTags.Count == 0) return;
+
+        // Sub-folders first — a VirtualTag's FolderPath becomes one folder UNDER its equipment folder
+        // (deduped per distinct equipment+path). VirtualTags with no FolderPath hang directly under the
+        // equipment folder, which MaterialiseHierarchy already created (never re-create it here).
+        var foldersCreated = new HashSet<string>(StringComparer.Ordinal);
+        foreach (var v in composition.EquipmentVirtualTags)
+        {
+            if (string.IsNullOrWhiteSpace(v.FolderPath)) continue;
+            var folderNodeId = EquipmentNodeIds.SubFolder(v.EquipmentId, v.FolderPath);
+            if (!foldersCreated.Add(folderNodeId)) continue;
+            SafeEnsureFolder(folderNodeId, parentNodeId: v.EquipmentId, displayName: v.FolderPath);
+        }
+
+        // Variables: NodeId is FOLDER-SCOPED ("<parent>/<Name>"), mirroring the equipment-tag pass.
+        // Parent is the FolderPath sub-folder when set, else the equipment folder directly.
+        // NOTE (H5): a VirtualTag's Historize flag is honoured on the WRITE side only — VirtualTagHostActor
+        // forwards historized results to IHistoryWriter. It is intentionally NOT materialised as an SDK
+        // Historizing/HistoryRead variable here (no server-side OPC UA HistoryRead for vtags), so these
+        // stay plain read-only computed-output nodes.
+        foreach (var v in composition.EquipmentVirtualTags)
+        {
+            var parent = string.IsNullOrWhiteSpace(v.FolderPath)
+                ? v.EquipmentId
+                : EquipmentNodeIds.SubFolder(v.EquipmentId, v.FolderPath);
+            var nodeId = EquipmentNodeIds.Variable(v.EquipmentId, v.FolderPath, v.Name);
+            // VirtualTags are computed outputs — read-only nodes (no inbound write).
+            SafeEnsureVariable(nodeId, parent, v.Name, v.DataType, writable: false);
+        }
+
+        _logger.LogInformation(
+            "AddressSpaceApplier: equipment virtualtags materialised (vtags={Vtags}, equipment={Equipment})",
+            composition.EquipmentVirtualTags.Count,
+            composition.EquipmentVirtualTags.Select(v => v.EquipmentId).Distinct(StringComparer.Ordinal).Count());
+    }
+
+    /// <summary>
+    ///     T14 — materialise real OPC UA Part 9 <c>AlarmConditionState</c> nodes from a composition
+    ///     snapshot. For each <b>enabled</b> <see cref="EquipmentScriptedAlarmPlan"/>, register a
+    ///     condition node (keyed by its <see cref="EquipmentScriptedAlarmPlan.ScriptedAlarmId"/>, which
+    ///     is the same id <c>OpcUaPublishActor.AlarmStateUpdate</c> targets) under its equipment folder.
+    ///     Disabled alarms are skipped — they expose no node. Must run AFTER
+    ///     <see cref="MaterialiseHierarchy"/> so the equipment folders exist. Idempotent (the sink's
+    ///     <c>MaterialiseAlarmCondition</c> re-creates cleanly on re-apply).
+    /// </summary>
+    /// <param name="composition">The composition result containing the scripted alarms to materialise.</param>
+    public void MaterialiseScriptedAlarms(AddressSpaceComposition composition)
+    {
+        ArgumentNullException.ThrowIfNull(composition);
+        if (composition.EquipmentScriptedAlarms.Count == 0) return;
+
+        var materialised = 0;
+        foreach (var alarm in composition.EquipmentScriptedAlarms)
+        {
+            if (!alarm.Enabled) continue;
+            SafeMaterialiseAlarmCondition(alarm.ScriptedAlarmId, alarm.EquipmentId, alarm.Name, alarm.AlarmType, alarm.Severity, isNative: false);
+            materialised++;
+        }
+
+        _logger.LogInformation(
+            "AddressSpaceApplier: scripted alarms materialised (alarms={Alarms}, equipment={Equipment})",
+            materialised,
+            composition.EquipmentScriptedAlarms.Where(a => a.Enabled)
+                .Select(a => a.EquipmentId).Distinct(StringComparer.Ordinal).Count());
+    }
+
+    private void SafeEnsureFolder(string nodeId, string? parentNodeId, string displayName)
+    {
+        try { _sink.EnsureFolder(nodeId, parentNodeId, displayName); }
+        catch (Exception ex) { _logger.LogWarning(ex, "AddressSpaceApplier: EnsureFolder threw for {Node}", nodeId); }
+    }
+
+    private void SafeEnsureVariable(string nodeId, string? parentNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null)
+    {
+        try { _sink.EnsureVariable(nodeId, parentNodeId, displayName, dataType, writable, historianTagname, isArray, arrayLength); }
+        catch (Exception ex) { _logger.LogWarning(ex, "AddressSpaceApplier: EnsureVariable threw for {Node}", nodeId); }
+    }
+
+    // A VirtualTag's materialised OPC UA node (MaterialiseEquipmentVirtualTags) is derived ONLY from
+    // {EquipmentId, FolderPath, Name, DataType}. Expression/DependencyRefs/Historize are engine/write-side
+    // only and are adopted by VirtualTagHostActor's INDEPENDENT respawn (DriverHostActor → ApplyVirtualTags),
+    // so a delta changing ONLY those three leaves a byte-identical node and needs no address-space rebuild.
+    // Whitelist-of-may-differ via `with` + the record's custom Equals: any OTHER field difference (current
+    // or future) makes the override unequal → falls back to a full rebuild (safe default).
+    private static bool VtagDeltaIsNodeIrrelevant(AddressSpacePlan.EquipmentVirtualTagDelta d) =>
+        (d.Previous with
+        {
+            Expression = d.Current.Expression,
+            DependencyRefs = d.Current.DependencyRefs,
+            Historize = d.Current.Historize,
+        }).Equals(d.Current);
+
+    // F10b: a CHANGED equipment tag whose ONLY differences are Writable / IsHistorized / HistorianTagname
+    // (a plain value variable — no alarm condition node) can be updated IN PLACE on the existing node via
+    // ISurgicalAddressSpaceSink.UpdateTagAttributes, avoiding a full rebuild (preserving subscriptions).
+    // DataType / IsArray / ArrayLength / FullName / DriverInstanceId / identity / alarm differences fall
+    // through to a rebuild — the override-unequal default also covers any future field.
+    private static bool TagDeltaIsSurgicalEligible(AddressSpacePlan.EquipmentTagDelta d) =>
+        d.Previous.Alarm is null && d.Current.Alarm is null &&
+        (d.Previous with
+        {
+            Writable = d.Current.Writable,
+            IsHistorized = d.Current.IsHistorized,
+            HistorianTagname = d.Current.HistorianTagname,
+        }).Equals(d.Current);
+
+    /// <summary>The "no-event" condition state written to a removed equipment / alarm node before the
+    /// rebuild tears it down: inactive, acked, confirmed, enabled, unshelved, severity 0, empty message.
+    /// Drives Retain to false so a removed condition stops replaying on ConditionRefresh.</summary>
+    private static readonly AlarmConditionSnapshot RemovedConditionState = new(
+        Active: false,
+        Acknowledged: true,
+        Confirmed: true,
+        Enabled: true,
+        Shelving: AlarmShelvingKind.Unshelved,
+        Severity: 0,
+        Message: string.Empty);
+
+    private void SafeWriteAlarmCondition(string nodeId, AlarmConditionSnapshot state, DateTime ts)
+    {
+        try { _sink.WriteAlarmCondition(nodeId, state, ts); }
+        catch (Exception ex) { _logger.LogWarning(ex, "AddressSpaceApplier: WriteAlarmCondition threw for {Node}", nodeId); }
+    }
+
+    private void SafeMaterialiseAlarmCondition(string alarmNodeId, string equipmentNodeId, string displayName, string alarmType, int severity, bool isNative)
+    {
+        try { _sink.MaterialiseAlarmCondition(alarmNodeId, equipmentNodeId, displayName, alarmType, severity, isNative); }
+        catch (Exception ex) { _logger.LogWarning(ex, "AddressSpaceApplier: MaterialiseAlarmCondition threw for {Node}", alarmNodeId); }
+    }
+}
+
+/// <summary>Summary of one apply pass. Useful for tests + audit-log entries on the deploy path.</summary>
+public sealed record AddressSpaceApplyOutcome(
+    int RemovedNodes,
+    int AddedNodes,
+    int ChangedNodes,
+    bool RebuildCalled);