feat(commons): additive SiteIdentifier on browse/verify/cert-trust commands for management-API routing (arch-review C4)

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

src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/BrowseCommands.cs

@@ -21,10 +21,16 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
 /// request carry back the token from the prior <see cref="BrowseNodeResult.ContinuationToken"/>.
 /// Additive (appended last) so positional construction stays source-compatible.
 /// </param>
+/// <param name="SiteIdentifier">
+/// Target site identifier — REQUIRED when the command is invoked via the management
+/// HTTP API/CLI (the actor must route it to a site); ignored on the site side, where
+/// routing already happened. Additive per the message-contract evolution rules.
+/// </param>
 public record BrowseNodeCommand(
     string ConnectionName,
     string? ParentNodeId,
-    string? ContinuationToken = null);
+    string? ContinuationToken = null,
+    string? SiteIdentifier = null);
 
 /// <param name="Children">Immediate children resolved for the browsed node (this page only).</param>
 /// <param name="Truncated">True when the result was clipped (frame-budget cap or adapter-reported truncation).</param>
@@ -59,11 +65,17 @@ public record BrowseNodeResult(
 /// <param name="Query">Case-insensitive substring matched against each node's DisplayName and root-relative path.</param>
 /// <param name="MaxDepth">Maximum number of levels below the root to descend. Must be non-negative.</param>
 /// <param name="MaxResults">Maximum number of matches to return; when reached the walk stops early and <see cref="SearchAddressSpaceResult.CapReached"/> is set.</param>
+/// <param name="SiteIdentifier">
+/// Target site identifier — REQUIRED when the command is invoked via the management
+/// HTTP API/CLI (the actor must route it to a site); ignored on the site side, where
+/// routing already happened. Additive per the message-contract evolution rules.
+/// </param>
 public record SearchAddressSpaceCommand(
     string ConnectionName,
     string Query,
     int MaxDepth,
-    int MaxResults);
+    int MaxResults,
+    string? SiteIdentifier = null);
 
 /// <param name="Matches">The matched address-space nodes, in breadth-first discovery order (capped at <see cref="SearchAddressSpaceCommand.MaxResults"/>).</param>
 /// <param name="CapReached">True when a bound (result cap or the adapter's node-visit ceiling) cut the walk short, so more matches may exist than were returned.</param>

src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/CertTrustCommands.cs

@@ -22,21 +22,36 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
 /// <param name="ConnectionName">The data-connection the certificate was captured from (diagnostics / correlation only).</param>
 /// <param name="DerBase64">The server certificate's DER encoding, base64-encoded.</param>
 /// <param name="Thumbprint">The certificate thumbprint — used as the store filename key.</param>
-public record TrustServerCertCommand(string ConnectionName, string DerBase64, string Thumbprint);
+/// <param name="SiteIdentifier">
+/// Target site identifier — REQUIRED when the command is invoked via the management
+/// HTTP API/CLI (the actor must route it to a site); ignored on the site side, where
+/// routing already happened. Additive per the message-contract evolution rules.
+/// </param>
+public record TrustServerCertCommand(string ConnectionName, string DerBase64, string Thumbprint, string? SiteIdentifier = null);
 
 /// <summary>
 /// Remove a previously-trusted OPC UA server certificate from every site
 /// node's trusted-peer PKI store, identified by thumbprint.
 /// </summary>
 /// <param name="Thumbprint">The thumbprint of the certificate to remove.</param>
-public record RemoveServerCertCommand(string Thumbprint);
+/// <param name="SiteIdentifier">
+/// Target site identifier — REQUIRED when the command is invoked via the management
+/// HTTP API/CLI (the actor must route it to a site); ignored on the site side, where
+/// routing already happened. Additive per the message-contract evolution rules.
+/// </param>
+public record RemoveServerCertCommand(string Thumbprint, string? SiteIdentifier = null);
 
 /// <summary>
 /// List the certificates currently present in this site's trusted-peer and
 /// rejected PKI stores. Answered from the local node (the Deployment Manager
 /// singleton's own node).
 /// </summary>
-public record ListServerCertsCommand();
+/// <param name="SiteIdentifier">
+/// Target site identifier — REQUIRED when the command is invoked via the management
+/// HTTP API/CLI (the actor must route it to a site); ignored on the site side, where
+/// routing already happened. Additive per the message-contract evolution rules.
+/// </param>
+public record ListServerCertsCommand(string? SiteIdentifier = null);
 
 /// <summary>
 /// Read-only projection of a certificate found in a site PKI store.

src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/VerifyEndpointCommands.cs

@@ -12,7 +12,12 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
 /// <param name="ConnectionName">Name of the data connection being verified (for logging/correlation).</param>
 /// <param name="Protocol">Protocol type string (e.g. "OpcUa"); matched case-insensitively.</param>
 /// <param name="ConfigJson">Serialized endpoint configuration JSON (the typed OPC UA endpoint shape).</param>
-public record VerifyEndpointCommand(string ConnectionName, string Protocol, string ConfigJson);
+/// <param name="SiteIdentifier">
+/// Target site identifier — REQUIRED when the command is invoked via the management
+/// HTTP API/CLI (the actor must route it to a site); ignored on the site side, where
+/// routing already happened. Additive per the message-contract evolution rules.
+/// </param>
+public record VerifyEndpointCommand(string ConnectionName, string Protocol, string ConfigJson, string? SiteIdentifier = null);
 
 /// <summary>
 /// Classification of why an endpoint verification failed. Distinguishes the cases the

tests/ZB.MOM.WW.ScadaBridge.Commons.Tests/Messages/BrowseVerifyCertSiteIdentifierTests.cs

@@ -0,0 +1,134 @@
+using System.Text.Json;
+using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
+
+namespace ZB.MOM.WW.ScadaBridge.Commons.Tests.Messages;
+
+/// <summary>
+/// Task 21 (PLAN-07): the additive optional <c>SiteIdentifier</c> trailing param on the
+/// Browse/Verify/Cert-trust management commands. Verifies backward compatibility (legacy
+/// JSON without the field deserializes to null) and round-trip survival when set.
+/// </summary>
+public class BrowseVerifyCertSiteIdentifierTests
+{
+    private static readonly JsonSerializerOptions Options = new()
+    {
+        PropertyNameCaseInsensitive = true
+    };
+
+    // ── Backward compatibility: legacy JSON (no SiteIdentifier) → null ──
+
+    [Fact]
+    public void BrowseNodeCommand_LegacyJson_SiteIdentifierNull()
+    {
+        var json = """{"ConnectionName":"conn","ParentNodeId":"ns=2;s=Node","ContinuationToken":null}""";
+        var cmd = JsonSerializer.Deserialize<BrowseNodeCommand>(json, Options)!;
+        Assert.Null(cmd.SiteIdentifier);
+        Assert.Equal("conn", cmd.ConnectionName);
+    }
+
+    [Fact]
+    public void SearchAddressSpaceCommand_LegacyJson_SiteIdentifierNull()
+    {
+        var json = """{"ConnectionName":"conn","Query":"pump","MaxDepth":5,"MaxResults":100}""";
+        var cmd = JsonSerializer.Deserialize<SearchAddressSpaceCommand>(json, Options)!;
+        Assert.Null(cmd.SiteIdentifier);
+        Assert.Equal("pump", cmd.Query);
+    }
+
+    [Fact]
+    public void VerifyEndpointCommand_LegacyJson_SiteIdentifierNull()
+    {
+        var json = """{"ConnectionName":"conn","Protocol":"OpcUa","ConfigJson":"{}"}""";
+        var cmd = JsonSerializer.Deserialize<VerifyEndpointCommand>(json, Options)!;
+        Assert.Null(cmd.SiteIdentifier);
+        Assert.Equal("OpcUa", cmd.Protocol);
+    }
+
+    [Fact]
+    public void TrustServerCertCommand_LegacyJson_SiteIdentifierNull()
+    {
+        var json = """{"ConnectionName":"conn","DerBase64":"AAAA","Thumbprint":"ABCD"}""";
+        var cmd = JsonSerializer.Deserialize<TrustServerCertCommand>(json, Options)!;
+        Assert.Null(cmd.SiteIdentifier);
+        Assert.Equal("ABCD", cmd.Thumbprint);
+    }
+
+    [Fact]
+    public void RemoveServerCertCommand_LegacyJson_SiteIdentifierNull()
+    {
+        var json = """{"Thumbprint":"ABCD"}""";
+        var cmd = JsonSerializer.Deserialize<RemoveServerCertCommand>(json, Options)!;
+        Assert.Null(cmd.SiteIdentifier);
+        Assert.Equal("ABCD", cmd.Thumbprint);
+    }
+
+    [Fact]
+    public void ListServerCertsCommand_LegacyJson_SiteIdentifierNull()
+    {
+        var json = "{}";
+        var cmd = JsonSerializer.Deserialize<ListServerCertsCommand>(json, Options)!;
+        Assert.Null(cmd.SiteIdentifier);
+    }
+
+    // ── Round-trip: SiteIdentifier set survives serialize → deserialize ──
+
+    [Fact]
+    public void BrowseNodeCommand_RoundTrip_SiteIdentifierSurvives()
+    {
+        var original = new BrowseNodeCommand("conn", "ns=2;s=Node", "tok", "SITE-01");
+        var json = JsonSerializer.Serialize(original, Options);
+        var round = JsonSerializer.Deserialize<BrowseNodeCommand>(json, Options)!;
+        Assert.Equal("SITE-01", round.SiteIdentifier);
+        Assert.Equal(original, round);
+    }
+
+    [Fact]
+    public void SearchAddressSpaceCommand_RoundTrip_SiteIdentifierSurvives()
+    {
+        var original = new SearchAddressSpaceCommand("conn", "pump", 5, 100, "SITE-01");
+        var json = JsonSerializer.Serialize(original, Options);
+        var round = JsonSerializer.Deserialize<SearchAddressSpaceCommand>(json, Options)!;
+        Assert.Equal("SITE-01", round.SiteIdentifier);
+        Assert.Equal(original, round);
+    }
+
+    [Fact]
+    public void VerifyEndpointCommand_RoundTrip_SiteIdentifierSurvives()
+    {
+        var original = new VerifyEndpointCommand("conn", "OpcUa", "{}", "SITE-01");
+        var json = JsonSerializer.Serialize(original, Options);
+        var round = JsonSerializer.Deserialize<VerifyEndpointCommand>(json, Options)!;
+        Assert.Equal("SITE-01", round.SiteIdentifier);
+        Assert.Equal(original, round);
+    }
+
+    [Fact]
+    public void TrustServerCertCommand_RoundTrip_SiteIdentifierSurvives()
+    {
+        var original = new TrustServerCertCommand("conn", "AAAA", "ABCD", "SITE-01");
+        var json = JsonSerializer.Serialize(original, Options);
+        var round = JsonSerializer.Deserialize<TrustServerCertCommand>(json, Options)!;
+        Assert.Equal("SITE-01", round.SiteIdentifier);
+        Assert.Equal(original, round);
+    }
+
+    [Fact]
+    public void RemoveServerCertCommand_RoundTrip_SiteIdentifierSurvives()
+    {
+        var original = new RemoveServerCertCommand("ABCD", "SITE-01");
+        var json = JsonSerializer.Serialize(original, Options);
+        var round = JsonSerializer.Deserialize<RemoveServerCertCommand>(json, Options)!;
+        Assert.Equal("SITE-01", round.SiteIdentifier);
+        Assert.Equal(original, round);
+    }
+
+    [Fact]
+    public void ListServerCertsCommand_RoundTrip_SiteIdentifierSurvives()
+    {
+        var original = new ListServerCertsCommand("SITE-01");
+        var json = JsonSerializer.Serialize(original, Options);
+        var round = JsonSerializer.Deserialize<ListServerCertsCommand>(json, Options)!;
+        Assert.Equal("SITE-01", round.SiteIdentifier);
+        Assert.Equal(original, round);
+    }
+}