fix(v3-batch4-wp2): AddReference sink seam for Organizes UNS→Raw (Wave A review M1)

Close the Wave-A M1 gap: the sink surface had no way to wire the mandated
cross-tree Organizes reference from each UNS reference Variable to its backing
Raw node, forcing WP3 to reopen the frozen surface. Add a dedicated
realm-qualified AddReference method instead.

- IOpcUaAddressSpaceSink.AddReference(sourceNodeId, sourceRealm, targetNodeId,
  targetRealm, referenceType="Organizes"): realm-qualified both ends; idempotent;
  a missing endpoint is a logged no-op (never throws) so a mid-rebuild race can't
  fault a deploy. Base-interface capability (no surgical sniff, no transitional
  default — WP3 wires it explicitly per UNS reference variable).
- SdkAddressSpaceSink forwards to the node manager; DeferredAddressSpaceSink
  forwards unconditionally (like EnsureFolder); NullOpcUaAddressSpaceSink no-ops.
- OtOpcUaNodeManager.AddReference: resolve both nodes by full ns-qualified key
  (variable/folder/condition via ResolveNodeState), guard both-exist, then wire
  the edge bidirectionally (forward Organizes on source, inverse on target) with a
  ReferenceExists idempotency guard + ClearChangeMasks on mutated sides. Reference
  type resolved by ResolveReferenceType (Organizes default). Added internal
  GetNodeReferences test/diagnostic accessor.
- Reflection guard: the exhaustive-forwarding test + the realm-discriminator guard
  auto-cover AddReference (it has two AddressSpaceRealm params) — no edit needed.
- New SdkAddressSpaceSinkTests: Organizes UNS→Raw edge created bidirectionally +
  idempotent; missing endpoint is a safe no-op.
- All 15 IOpcUaAddressSpaceSink test doubles gain the AddReference no-op so the
  solution still builds.

Build: dotnet build ZB.MOM.WW.OtOpcUa.slnx = 0 errors.
Tests: Commons.Tests 310/310; OpcUaServer.Tests 337 passed / 4 pre-existing skips.

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

tests/Core/ZB.MOM.WW.OtOpcUa.Commons.Tests/OpcUa/DeferredAddressSpaceSinkTests.cs

@@ -195,6 +195,7 @@ public class DeferredAddressSpaceSinkTests
         public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
         public void RebuildAddressSpace() => RebuildCalled = true;
         public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
+        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
     }
 
     private sealed class SpySurgicalSink : IOpcUaAddressSpaceSink, ISurgicalAddressSpaceSink
@@ -209,6 +210,7 @@ public class DeferredAddressSpaceSinkTests
         public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
         public void RebuildAddressSpace() { }
         public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
+        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
 
         public bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname, string dataType, bool isArray, uint? arrayLength, AddressSpaceRealm realm = AddressSpaceRealm.Uns)
         {

tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/AddressSpaceApplierFailureSurfaceTests.cs

@@ -189,5 +189,6 @@ public sealed class AddressSpaceApplierFailureSurfaceTests
         }
 
         public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
+        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
     }
 }

tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/AddressSpaceApplierHierarchyTests.cs

@@ -338,5 +338,6 @@ public sealed class AddressSpaceApplierHierarchyTests : IDisposable
         public void RebuildAddressSpace() { }
         /// <summary>Announces a NodeAdded model-change (stub implementation for testing).</summary>
         public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
+        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
     }
 }

tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/AddressSpaceApplierTests.cs

@@ -2307,6 +2307,7 @@ public sealed class AddressSpaceApplierTests
         /// <summary>Records a NodeAdded model-change announcement.</summary>
         /// <param name="affectedNodeId">The node under which discovered nodes were added.</param>
         public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) => ModelChangeQueue.Enqueue(affectedNodeId);
+        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
     }
 
     /// <summary>A recording sink that does NOT implement <see cref="ISurgicalAddressSpaceSink"/> — used to
@@ -2331,6 +2332,7 @@ public sealed class AddressSpaceApplierTests
         public void RebuildAddressSpace() => Interlocked.Increment(ref RebuildCalls);
         /// <summary>No-op NodeAdded model-change announcement.</summary>
         public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
+        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
     }
 
     private sealed class ThrowingSink : IOpcUaAddressSpaceSink
@@ -2379,5 +2381,6 @@ public sealed class AddressSpaceApplierTests
         public void RebuildAddressSpace() { }
         /// <summary>No-op NodeAdded model-change announcement.</summary>
         public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
+        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
     }
 }

tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/DeferredAddressSpaceSinkTests.cs

@@ -249,6 +249,7 @@ public sealed class DeferredAddressSpaceSinkTests
         public void RebuildAddressSpace() => CallQueue.Enqueue("RB");
         /// <inheritdoc />
         public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) => CallQueue.Enqueue($"NA:{affectedNodeId}");
+        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
     }
 
     private sealed class SurgicalRecordingSink : IOpcUaAddressSpaceSink, ISurgicalAddressSpaceSink
@@ -298,5 +299,6 @@ public sealed class DeferredAddressSpaceSinkTests
         public void RebuildAddressSpace() { }
         /// <inheritdoc />
         public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
+        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
     }
 }

tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/SdkAddressSpaceSinkTests.cs

@@ -52,6 +52,67 @@ public sealed class SdkAddressSpaceSinkTests : IDisposable
         await host.DisposeAsync();
     }
 
+    /// <summary>B4-WP2 M1: AddReference wires the cross-tree Organizes edge from a UNS reference variable
+    /// (source, realm=Uns) to its backing Raw node (target, realm=Raw), bidirectionally, so browse resolves
+    /// both ways — and is idempotent.</summary>
+    [Fact]
+    public async Task AddReference_wires_Organizes_edge_from_UNS_variable_to_Raw_node()
+    {
+        var (host, server) = await BootAsync();
+        var nm = server.NodeManager!;
+        var sink = new SdkAddressSpaceSink(nm);
+
+        // Backing Raw node (device tree) and the UNS reference variable (equipment tree).
+        sink.EnsureVariable("MAIN/modbus/dev/grp/temp", parentFolderNodeId: null, displayName: "Temp",
+            dataType: "Float", writable: false, realm: AddressSpaceRealm.Raw);
+        sink.EnsureVariable("Area/Line/Eq/Temperature", parentFolderNodeId: null, displayName: "Temperature",
+            dataType: "Float", writable: false, realm: AddressSpaceRealm.Uns);
+
+        sink.AddReference("Area/Line/Eq/Temperature", AddressSpaceRealm.Uns,
+                          "MAIN/modbus/dev/grp/temp", AddressSpaceRealm.Raw);
+
+        var unsVar = nm.TryGetVariable("Area/Line/Eq/Temperature", AddressSpaceRealm.Uns);
+        var rawVar = nm.TryGetVariable("MAIN/modbus/dev/grp/temp", AddressSpaceRealm.Raw);
+        unsVar.ShouldNotBeNull();
+        rawVar.ShouldNotBeNull();
+
+        // Forward Organizes on the UNS variable → Raw node; inverse (OrganizedBy) on the Raw node.
+        unsVar.ReferenceExists(ReferenceTypeIds.Organizes, isInverse: false, rawVar.NodeId).ShouldBeTrue();
+        rawVar.ReferenceExists(ReferenceTypeIds.Organizes, isInverse: true, unsVar.NodeId).ShouldBeTrue();
+
+        // Idempotent: a second identical call does not duplicate the edge. The UNS variable's only
+        // FORWARD Organizes ref is the one we added (its parent link manifests as an inverse ref).
+        sink.AddReference("Area/Line/Eq/Temperature", AddressSpaceRealm.Uns,
+                          "MAIN/modbus/dev/grp/temp", AddressSpaceRealm.Raw);
+        nm.GetNodeReferences("Area/Line/Eq/Temperature", AddressSpaceRealm.Uns)
+            .Count(r => r.ReferenceTypeId == ReferenceTypeIds.Organizes && !r.IsInverse).ShouldBe(1);
+
+        await host.DisposeAsync();
+    }
+
+    /// <summary>B4-WP2 M1: a missing endpoint makes AddReference a safe no-op (never throws, no edge added).</summary>
+    [Fact]
+    public async Task AddReference_with_missing_endpoint_is_a_safe_no_op()
+    {
+        var (host, server) = await BootAsync();
+        var nm = server.NodeManager!;
+        var sink = new SdkAddressSpaceSink(nm);
+
+        sink.EnsureVariable("Area/Line/Eq/Temperature", parentFolderNodeId: null, displayName: "Temperature",
+            dataType: "Float", writable: false, realm: AddressSpaceRealm.Uns);
+
+        // Target does not exist ⇒ no-op, no throw.
+        Should.NotThrow(() => sink.AddReference("Area/Line/Eq/Temperature", AddressSpaceRealm.Uns,
+                                                "MAIN/does/not/exist", AddressSpaceRealm.Raw));
+
+        var unsVar = nm.TryGetVariable("Area/Line/Eq/Temperature", AddressSpaceRealm.Uns);
+        unsVar.ShouldNotBeNull();
+        nm.GetNodeReferences("Area/Line/Eq/Temperature", AddressSpaceRealm.Uns)
+            .Any(r => r.ReferenceTypeId == ReferenceTypeIds.Organizes && !r.IsInverse).ShouldBeFalse();
+
+        await host.DisposeAsync();
+    }
+
     /// <summary>Verifies that RebuildAddressSpace clears all registered variables.</summary>
     [Fact]
     public async Task RebuildAddressSpace_clears_all_registered_variables()

tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/Drivers/DiscoveryInjectionEndToEndTests.cs

@@ -346,5 +346,6 @@ public sealed class DiscoveryInjectionEndToEndTests : RuntimeActorTestBase
 
         /// <summary>Records a NodeAdded model-change announcement.</summary>
         public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) => _modelChanges.Enqueue(affectedNodeId);
+        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
     }
 }

tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/Observability/OtOpcUaTelemetryHookTests.cs

@@ -224,5 +224,6 @@ public sealed class OtOpcUaTelemetryHookTests : RuntimeActorTestBase
         public void RebuildAddressSpace() { /* recorded via span */ }
         /// <summary>Announces a NodeAdded model-change (stub implementation).</summary>
         public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
+        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
     }
 }

tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/OpcUa/OpcUaPublishActorApplyFailureTests.cs

@@ -125,6 +125,7 @@ public sealed class OpcUaPublishActorApplyFailureTests : RuntimeActorTestBase
         public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
         public void RebuildAddressSpace() => throw new InvalidOperationException("simulated rebuild fault");
         public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
+        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
     }
 
     /// <summary>A no-op sink — a clean apply (no failures).</summary>
@@ -137,6 +138,7 @@ public sealed class OpcUaPublishActorApplyFailureTests : RuntimeActorTestBase
         public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
         public void RebuildAddressSpace() { }
         public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
+        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
     }
 
     /// <summary>Listens to a single instrument by name on the central meter and tallies value + tags.</summary>

tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/OpcUa/OpcUaPublishActorRebuildTests.cs

@@ -473,6 +473,7 @@ public sealed class OpcUaPublishActorRebuildTests : RuntimeActorTestBase
         /// <summary>Records a NodeAdded model-change announcement.</summary>
         /// <param name="affectedNodeId">The node under which discovered nodes were added.</param>
         public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) => Calls.Enqueue($"NA:{affectedNodeId}");
+        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
         /// <summary>Records a surgical in-place tag-attribute update (always succeeds in this recording sink).</summary>
         public bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname, string dataType, bool isArray, uint? arrayLength, AddressSpaceRealm realm = AddressSpaceRealm.Uns)
         {

tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/OpcUa/OpcUaPublishActorTests.cs

@@ -647,6 +647,7 @@ public sealed class OpcUaPublishActorTests : RuntimeActorTestBase
         /// <summary>Records a NodeAdded model-change announcement.</summary>
         /// <param name="affectedNodeId">The node under which discovered nodes were added.</param>
         public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) => ModelChangeQueue.Enqueue(affectedNodeId);
+        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
     }
 
     /// <summary>Test implementation of IServiceLevelPublisher that records publishes.</summary>