feat(commons): add surgical remove members to ISurgicalAddressSpaceSink + deferred forwarding (guard-verified) (R2-07 T7)

2026-07-13 12:07:01 -04:00
parent 4f1853b21f
commit 438004e371
9 changed files with 210 additions and 1 deletions
@@ -2013,6 +2013,35 @@ public sealed class AddressSpaceApplierTests
            return FolderRenameReturns;
        }

+        /// <summary>Gets the queue of surgical remove calls (kind + node id) in call order (R2-07 Phase 2).</summary>
+        public ConcurrentQueue<(string Kind, string NodeId)> RemoveQueue { get; } = new();
+        /// <summary>Gets the list of recorded surgical remove calls.</summary>
+        public List<(string Kind, string NodeId)> RemoveCalls => RemoveQueue.ToList();
+        /// <summary>When false, the Remove* members report the node missing (return false), driving the
+        /// applier's rebuild fallback. Defaults to true (node present, removal succeeds).</summary>
+        public bool RemoveReturns { get; init; } = true;
+
+        /// <summary>Records a surgical variable-node removal; returns <see cref="RemoveReturns"/>.</summary>
+        public bool RemoveVariableNode(string variableNodeId)
+        {
+            RemoveQueue.Enqueue(("var", variableNodeId));
+            return RemoveReturns;
+        }
+
+        /// <summary>Records a surgical alarm-condition-node removal; returns <see cref="RemoveReturns"/>.</summary>
+        public bool RemoveAlarmConditionNode(string alarmNodeId)
+        {
+            RemoveQueue.Enqueue(("alarm", alarmNodeId));
+            return RemoveReturns;
+        }
+
+        /// <summary>Records a surgical equipment-subtree removal; returns <see cref="RemoveReturns"/>.</summary>
+        public bool RemoveEquipmentSubtree(string equipmentNodeId)
+        {
+            RemoveQueue.Enqueue(("equipment", equipmentNodeId));
+            return RemoveReturns;
+        }
+
        /// <summary>Gets the queue of alarm condition write calls.</summary>
        public ConcurrentQueue<(string NodeId, AlarmConditionSnapshot State)> AlarmQueue { get; } = new();
        /// <summary>Gets the queue of folder creation calls.</summary>
@@ -174,6 +174,40 @@ public sealed class DeferredAddressSpaceSinkTests
        ((ISurgicalAddressSpaceSink)deferred).UpdateFolderDisplayName("area-1", "X").ShouldBeFalse();
    }

+    /// <summary>R2-07 Phase 2 — the three surgical remove members forward to a surgical inner with
+    /// arg-fidelity (kind + node id), returning the inner's own result; false when the inner is not surgical
+    /// so the caller falls back to a full rebuild.</summary>
+    [Fact]
+    public void Remove_members_forward_to_a_surgical_inner_sink_with_arg_fidelity()
+    {
+        var deferred = new DeferredAddressSpaceSink();
+        var inner = new SurgicalRecordingSink { Result = true };
+        deferred.SetSink(inner);
+
+        ((ISurgicalAddressSpaceSink)deferred).RemoveVariableNode("eq-1/A").ShouldBeTrue();
+        ((ISurgicalAddressSpaceSink)deferred).RemoveAlarmConditionNode("alm-1").ShouldBeTrue();
+        ((ISurgicalAddressSpaceSink)deferred).RemoveEquipmentSubtree("eq-1").ShouldBeTrue();
+
+        inner.RemoveCalls.ShouldBe(new[] { ("var", "eq-1/A"), ("alarm", "alm-1"), ("equipment", "eq-1") });
+    }
+
+    /// <summary>The remove forwards return the inner's own result (false ⇒ id unknown ⇒ caller rebuilds),
+    /// and return false when the inner is not surgical at all.</summary>
+    [Fact]
+    public void Remove_members_return_inner_result_and_false_when_not_surgical()
+    {
+        var deferred = new DeferredAddressSpaceSink();
+        deferred.SetSink(new SurgicalRecordingSink { Result = false });
+        ((ISurgicalAddressSpaceSink)deferred).RemoveVariableNode("v-1").ShouldBeFalse();
+        ((ISurgicalAddressSpaceSink)deferred).RemoveAlarmConditionNode("a-1").ShouldBeFalse();
+        ((ISurgicalAddressSpaceSink)deferred).RemoveEquipmentSubtree("eq-1").ShouldBeFalse();
+
+        deferred.SetSink(null);
+        ((ISurgicalAddressSpaceSink)deferred).RemoveVariableNode("v-1").ShouldBeFalse();
+        ((ISurgicalAddressSpaceSink)deferred).RemoveAlarmConditionNode("a-1").ShouldBeFalse();
+        ((ISurgicalAddressSpaceSink)deferred).RemoveEquipmentSubtree("eq-1").ShouldBeFalse();
+    }
+
    /// <summary>Builds a minimal <see cref="AlarmConditionSnapshot"/> for the forwarding tests (the
    /// inner sink only records the node id, so the exact state values don't matter here).</summary>
    private static AlarmConditionSnapshot Snapshot(bool active = false) =>
@@ -240,6 +274,16 @@ public sealed class DeferredAddressSpaceSinkTests
            return Result;
        }

+        /// <summary>Gets the recorded surgical remove calls (kind + node id), in call order (R2-07 Phase 2).</summary>
+        public List<(string Kind, string NodeId)> RemoveCalls { get; } = new();
+
+        /// <inheritdoc />
+        public bool RemoveVariableNode(string variableNodeId) { RemoveCalls.Add(("var", variableNodeId)); return Result; }
+        /// <inheritdoc />
+        public bool RemoveAlarmConditionNode(string alarmNodeId) { RemoveCalls.Add(("alarm", alarmNodeId)); return Result; }
+        /// <inheritdoc />
+        public bool RemoveEquipmentSubtree(string equipmentNodeId) { RemoveCalls.Add(("equipment", equipmentNodeId)); return Result; }
+
        /// <inheritdoc />
        public void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc) { }
        /// <inheritdoc />
@@ -487,5 +487,23 @@ public sealed class OpcUaPublishActorRebuildTests : RuntimeActorTestBase
            FolderRenameQueue.Enqueue((folderNodeId, displayName));
            return true;
        }
+        /// <summary>Records a surgical variable-node removal (always succeeds in this recording sink).</summary>
+        public bool RemoveVariableNode(string variableNodeId)
+        {
+            Calls.Enqueue($"RV:{variableNodeId}");
+            return true;
+        }
+        /// <summary>Records a surgical alarm-condition-node removal (always succeeds in this recording sink).</summary>
+        public bool RemoveAlarmConditionNode(string alarmNodeId)
+        {
+            Calls.Enqueue($"RA:{alarmNodeId}");
+            return true;
+        }
+        /// <summary>Records a surgical equipment-subtree removal (always succeeds in this recording sink).</summary>
+        public bool RemoveEquipmentSubtree(string equipmentNodeId)
+        {
+            Calls.Enqueue($"RE:{equipmentNodeId}");
+            return true;
+        }
    }
 }