feat(historian): Part 11 modified-value history on SqlServer + QuestDB (#668)

Every HistoryUpdate a SQL backend applies now leaves a modification trail
(prior value, principal, Part 11 update type, modification time), and
HistoryReadRaw with IsReadModified=true serves it as HistoryModifiedData.

- Core: HistoryUpdateContext threaded into all three IHistorianDataUpdater
  methods; IHistorianDataSource.ReadModifiedAsync (default NotSupported =>
  BadHistoryOperationUnsupported on Gateway/Null); HistoryModified* contracts.
- SqlServer: schema v2 (002_sample_modified.sql, RequiredVersion=2, docs copy);
  trail written by OUTPUT ... INTO on the same MERGE/DELETE statement, so a
  failed update leaves no audit row; retention purges SampleModified per tag on
  the source-time cutoff; ReadModifiedAsync keyed on (SourceTimeUtc, ModifiedId).
- QuestDB: append-only {prefix}sample_modified (TTL like samples), trail row
  written BEFORE the change (orphan-on-crash, never an untracked change);
  existence reads now carry the prior value; ReadModifiedAsync.
- Node manager: modified reads dispatch + page via the #669 continuation store
  (HistoryContinuationState gains HistoryCursorKind + LastModifiedId), gated by
  the existing HistoryRead decision; session principal / key id passed to the
  updater. IsDeleteModified stays unsupported.
- Client.CLI: historyread --modified.
- Tests: node-manager dispatch/paging/cursor binding/principal threading,
  over-the-wire HistoryModifiedData, shared ModifiedValueConformance on both
  backends, SqlServer atomicity (forced trail failure => no change) + v1->v2
  upgrade + retention trail purge.
- Docs: Historian.md (Modified-value history section, schema v2 upgrade note),
  security.md, Client.CLI.md, CLAUDE.md.

tests/Client/ZB.MOM.WW.OtOpcUa.Client.CLI.Tests/Fakes/FakeOpcUaClientService.cs

@@ -326,6 +326,20 @@ public sealed class FakeOpcUaClientService : IOpcUaClientService
         return Task.FromResult(HistoryReadResult);
     }
 
+    /// <summary>Gets the list of (NodeId, start, end, maxValues) tuples from HistoryReadModifiedAsync calls.</summary>
+    public List<(NodeId NodeId, DateTime Start, DateTime End, int MaxValues)> HistoryReadModifiedCalls { get; } = [];
+
+    /// <summary>Gets or sets the entries returned by HistoryReadModifiedAsync.</summary>
+    public IReadOnlyList<HistoryModifiedEntry> HistoryReadModifiedResult { get; set; } = [];
+
+    /// <inheritdoc />
+    public Task<IReadOnlyList<HistoryModifiedEntry>> HistoryReadModifiedAsync(
+        NodeId nodeId, DateTime startTime, DateTime endTime, int maxValues = 1000, CancellationToken ct = default)
+    {
+        HistoryReadModifiedCalls.Add((nodeId, startTime, endTime, maxValues));
+        return Task.FromResult(HistoryReadModifiedResult);
+    }
+
     /// <summary>Gets the details passed to HistoryUpdateAsync.</summary>
     public List<HistoryUpdateDetails> HistoryUpdateCalls { get; } = [];
 

tests/Client/ZB.MOM.WW.OtOpcUa.Client.CLI.Tests/HistoryReadCommandTests.cs

@@ -146,4 +146,55 @@ public class HistoryReadCommandTests
         fakeService.DisconnectCalled.ShouldBeTrue();
         fakeService.DisposeCalled.ShouldBeTrue();
     }
-}
+
+    /// <summary>#668: --modified reads the modification trail (not raw) and prints update type, user and prior value.</summary>
+    [Fact]
+    public async Task Execute_ModifiedRead_CallsHistoryReadModified_and_prints_the_trail()
+    {
+        var t = new DateTime(2025, 6, 15, 10, 0, 0, DateTimeKind.Utc);
+        var fakeService = new FakeOpcUaClientService
+        {
+            HistoryReadModifiedResult =
+            [
+                new HistoryModifiedEntry(new DataValue(Variant.Null, StatusCodes.BadNoData, t, t), t.AddDays(1), HistoryUpdateType.Insert, "editor"),
+                new HistoryModifiedEntry(new DataValue(new Variant(1.5), StatusCodes.Good, t, t), t.AddDays(2), HistoryUpdateType.Replace, "editor"),
+            ],
+        };
+        var command = new HistoryReadCommand(new FakeOpcUaClientServiceFactory(fakeService))
+        {
+            Url = "opc.tcp://localhost:4840",
+            NodeId = "ns=2;s=HistNode",
+            Modified = true,
+            MaxValues = 50,
+        };
+
+        using var console = TestConsoleHelper.CreateConsole();
+        await command.ExecuteAsync(console);
+
+        fakeService.HistoryReadModifiedCalls.ShouldHaveSingleItem().MaxValues.ShouldBe(50);
+        fakeService.HistoryReadRawCalls.ShouldBeEmpty();
+        var output = TestConsoleHelper.GetOutput(console);
+        output.ShouldContain("Modified history for ns=2;s=HistNode");
+        output.ShouldContain("Replace");
+        output.ShouldContain("Insert");
+        output.ShouldContain("editor");
+        output.ShouldContain("(none)");
+        output.ShouldContain("2 modifications returned.");
+    }
+
+    /// <summary>--modified cannot be combined with --aggregate.</summary>
+    [Fact]
+    public async Task Execute_ModifiedWithAggregate_ThrowsCommandException()
+    {
+        var command = new HistoryReadCommand(new FakeOpcUaClientServiceFactory(new FakeOpcUaClientService()))
+        {
+            Url = "opc.tcp://localhost:4840",
+            NodeId = "ns=2;s=HistNode",
+            Modified = true,
+            Aggregate = "Average",
+        };
+
+        using var console = TestConsoleHelper.CreateConsole();
+        await Should.ThrowAsync<CliFx.Exceptions.CommandException>(async () => await command.ExecuteAsync(console));
+    }
+}