fix(aggregates): live PercentGood/DurationGood count Good time only (#809)

The frozen 1.5.378.182 StatusAggregateCalculator counts Uncertain regions as
Good under TreatUncertainAsBad=false, so live AggregateFilter PercentGood /
DurationGood disagreed with HistoryRead (Part 13 §5.4.3.31/§5.4.3.33, Mantis
0006166) whenever Uncertain data was present. Owner-approved 2026-11-11.

- New app-owned GoodOnlyStatusAggregateCalculator subclasses the baseline and
  replaces only the PercentGood/DurationGood computation (Good regions only);
  CompatibilityAggregateFactory routes exactly those two IDs to it. The copied
  SDK files are untouched; the other 35 aggregates are byte-identical.
- Golden test: the 64 changed vectors (38 PercentGood + 26 DurationGood) are
  exempted exactly — those whose baseline output differs from the same case's
  baseline TreatUncertainAsBad=true twin — and pinned to that twin (baseline
  evidence, not regenerated from the implementation); plus a full Good-only
  pin over all 352 PercentGood/DurationGood vectors and a hand-computed case.
- Live-vs-history parity over Good/Uncertain/Bad mixes (no masks), with a
  discrimination check against the pre-#809 baseline; the booted-runtime facts
  test now expects 8000 ms / 40 %.
- SdkAggregateOracle: Run/RunLive = the registered factory; RunSdkAsIs = the
  untouched baseline; its Part13GoodCalculator duplicate is removed.
- README (recorded decision), ServerAggregateConfiguration remarks,
  docs/Historian.md and .claude/rules/historian.md updated.

Claude-Session: https://claude.ai/code/session_01GT67AD99zQQqpLCVm3p7xk
This commit is contained in:
Joseph Doherty
2026-11-11 12:05:34 -05:00
parent e857135e8b
commit ed05d50795
11 changed files with 421 additions and 126 deletions
@@ -71,7 +71,7 @@ public abstract class QualityMixConformance : ConformanceBase
/// <summary>Hand-computed Part 13 DurationBad of Q's eight intervals, seconds.</summary>
private static readonly double[] QDurationBad = [3, 0, 0, 0, 5, 0, 0, 3];
/// <summary>What the 1.5.378.182 baseline answers for Q's PercentGood (Uncertain counted as Good, #796).</summary>
/// <summary>What the untouched 1.5.378.182 baseline answers for Q's PercentGood (Uncertain counted as Good, #796; live before #809).</summary>
private static readonly double[] QBaselinePercentGood = [70, 100, 100, 100, 50, 100, 100, 70];
/// <summary>
@@ -182,7 +182,8 @@ public abstract class QualityMixConformance : ConformanceBase
var pGood = (await src.ReadProcessedAsync("Q", At(0), At(80), Ten, HistoryAggregateType.PercentGood, Ct)).Samples;
ShouldBeClose(Values(good), Values(pGood).Select(p => p * Ten.TotalMilliseconds / 100).ToArray(), "DurationGood vs PercentGood");
// The baseline (the live AggregateFilter calculator, #809) answers Q's DurationGood with the Uncertain time added.
// The untouched baseline (the live AggregateFilter calculator before #809) answers Q's DurationGood with the
// Uncertain time added; the live calculator now answers the Part 13 values above (SdkAggregateParityTests).
var baseline = SdkAggregateOracle.RunSdkAsIs(HistoryAggregateType.DurationGood, At(0), At(80), Ten,
Q.Select(r => (r.T, r.V, r.Status)));
ShouldBeClose(baseline.Select(r => Convert.ToDouble(r.Value)).ToArray(),
@@ -2,7 +2,7 @@ using Opc.Ua;
using Opc.Ua.Server;
using ZB.MOM.WW.OtOpcUa.OpcUaServer.Compatibility.Aggregates;
using BaselineAggregateCalculator = ZB.MOM.WW.OtOpcUa.OpcUaServer.Compatibility.Aggregates.AggregateCalculator;
using BaselineStatusAggregateCalculator = ZB.MOM.WW.OtOpcUa.OpcUaServer.Compatibility.Aggregates.StatusAggregateCalculator;
using BaselineAggregators = ZB.MOM.WW.OtOpcUa.OpcUaServer.Compatibility.Aggregates.Aggregators;
using Shouldly;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
@@ -18,17 +18,18 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Conformance;
/// <remarks>
/// <para>Shared (source-linked) by <c>Sql.Common.Tests</c> and both SQL backends' integration suites.</para>
/// <para>
/// <b>PercentGood (and, since #820, DurationGood) are the aggregates not taken as-is (#796).</b> The 1.5.378.182 baseline changed
/// <b>PercentGood / DurationGood (#796, #820, #809).</b> The 1.5.378.182 baseline changed
/// <c>StatusAggregateCalculator.ComputeDurationGoodBad</c> (1.5.378.106 and earlier counted Good regions only):
/// with TreatUncertainAsBad = false it counts Uncertain regions as <b>Good</b> time (as Bad when true). Part 13
/// keeps Uncertain out of both (§5.4.3.31 DurationGood counts Good regions; §5.4.3.33 PercentGood =
/// DurationGood ÷ interval; Mantis 0006166, closed "no change required": an all-Uncertain interval is
/// PercentGood 0 <i>and</i> PercentBad 0), and so does ours. <see cref="Run"/> therefore answers PercentGood
/// (and DurationGood) through <see cref="Part13GoodCalculator"/>: the SAME baseline calculator, region machinery (simple
/// bounds, end-of-data 1 ms region, status and Partial bits) and server-default configuration, counting only
/// Good regions — exactly what the pre-.182 oracle computed. PercentBad / DurationBad still count Bad regions only
/// (unchanged by .182) and are compared as-is. <see cref="RunSdkAsIs"/> runs the baseline untouched, for the test that pins
/// the divergence.
/// PercentGood 0 <i>and</i> PercentBad 0), and so does ours. Since #809 the LIVE calculators follow Part 13 too:
/// <c>CompatibilityAggregateFactory</c> serves those two through the application's
/// <c>GoodOnlyStatusAggregateCalculator</c> (the same baseline region machinery — simple bounds, end-of-data 1 ms
/// region, status and Partial bits — counting only Good regions), so <see cref="Run"/> / <see cref="RunLive"/> are
/// exactly what a live AggregateFilter computes, for every aggregate. PercentBad / DurationBad count Bad regions only
/// (unchanged by .182). <see cref="RunSdkAsIs"/> runs the untouched baseline (what live served before #809), for the
/// tests that pin that divergence.
/// </para>
/// <para>
/// Not <c>100 − PercentBad</c> under TreatUncertainAsBad = true: that flag also changes the region machinery
@@ -54,8 +55,9 @@ public static class SdkAggregateOracle
};
/// <summary>
/// Runs the Part 13 oracle for <paramref name="aggregate"/> over <paramref name="samples"/>: the baseline calculator,
/// except PercentGood / DurationGood, which count Good regions only (see the remarks, #796/#820).
/// Runs the Part 13 oracle for <paramref name="aggregate"/> over <paramref name="samples"/>: the live calculator
/// (<see cref="RunLive"/>) — the baseline, except PercentGood / DurationGood, which count Good regions only (see the
/// remarks, #796/#820/#809).
/// </summary>
/// <param name="aggregate">The aggregate.</param>
/// <param name="start">Request start (later than <paramref name="end"/> for a reverse read).</param>
@@ -65,16 +67,29 @@ public static class SdkAggregateOracle
/// <returns>The oracle's processed values, in the order it returns them.</returns>
public static IReadOnlyList<Result> Run(HistoryAggregateType aggregate, DateTime start, DateTime end, TimeSpan interval,
IEnumerable<(DateTime Time, HistorianValue Value, uint Status)> samples) =>
aggregate is HistoryAggregateType.PercentGood or HistoryAggregateType.DurationGood
? RunCore(new LegacyCalculatorAdapter(new Part13GoodCalculator(AggregateId(aggregate),
start, end, interval.TotalMilliseconds, false, DefaultConfiguration, Telemetry,
usePercent: aggregate == HistoryAggregateType.PercentGood)), start, end, samples)
: RunSdkAsIs(aggregate, start, end, interval, samples);
RunLive(aggregate, start, end, interval, samples);
/// <summary>
/// Runs the baseline (1.5.378.182) calculator for <paramref name="aggregate"/> exactly as it computes it, under
/// <see cref="DefaultConfiguration"/> — including its PercentGood rule (Uncertain counted as Good) that
/// <see cref="Run"/> deliberately does not use (#796).
/// Runs exactly the calculator the server registers for live AggregateFilter monitored items
/// (<c>CompatibilityAggregateFactory.Create</c>, the #809 Good-only PercentGood / DurationGood included).
/// </summary>
/// <param name="aggregate">The aggregate.</param>
/// <param name="start">Request start (later than <paramref name="end"/> for a reverse read).</param>
/// <param name="end">Request end.</param>
/// <param name="interval">Processing interval.</param>
/// <param name="samples">Every stored sample of the tag, any order (sorted here).</param>
/// <param name="configuration">The configuration (default <see cref="DefaultConfiguration"/>).</param>
/// <returns>The calculator's processed values, in the order it returns them.</returns>
public static IReadOnlyList<Result> RunLive(HistoryAggregateType aggregate, DateTime start, DateTime end,
TimeSpan interval, IEnumerable<(DateTime Time, HistorianValue Value, uint Status)> samples,
AggregateConfiguration? configuration = null) =>
RunCore(CompatibilityAggregateFactory.Create(AggregateId(aggregate), start, end, interval.TotalMilliseconds, false,
configuration ?? DefaultConfiguration, Telemetry), start, end, samples);
/// <summary>
/// Runs the untouched baseline (1.5.378.182) calculator for <paramref name="aggregate"/> exactly as it computes it,
/// under <see cref="DefaultConfiguration"/> — including its PercentGood / DurationGood rule (Uncertain counted as
/// Good) that neither HistoryRead nor, since #809, the live calculators use.
/// </summary>
/// <param name="aggregate">The aggregate.</param>
/// <param name="start">Request start (later than <paramref name="end"/> for a reverse read).</param>
@@ -86,8 +101,9 @@ public static class SdkAggregateOracle
public static IReadOnlyList<Result> RunSdkAsIs(HistoryAggregateType aggregate, DateTime start, DateTime end,
TimeSpan interval, IEnumerable<(DateTime Time, HistorianValue Value, uint Status)> samples,
AggregateConfiguration? configuration = null) =>
RunCore(CompatibilityAggregateFactory.Create(AggregateId(aggregate), start, end, interval.TotalMilliseconds, false,
configuration ?? DefaultConfiguration, Telemetry), start, end, samples);
RunCore(new LegacyCalculatorAdapter(BaselineAggregators.CreateStandardCalculator(AggregateId(aggregate), start, end,
interval.TotalMilliseconds, false, configuration ?? DefaultConfiguration, Telemetry)
?? throw new ArgumentOutOfRangeException(nameof(aggregate))), start, end, samples);
private static IReadOnlyList<Result> RunCore(IAggregateCalculator calc, DateTime start, DateTime end,
IEnumerable<(DateTime Time, HistorianValue Value, uint Status)> samples)
@@ -155,42 +171,7 @@ public static class SdkAggregateOracle
problems.ShouldBeEmpty($"{label} differs from the SDK:\n" + string.Join("\n", problems));
}
/// <summary>
/// The baseline <see cref="BaselineStatusAggregateCalculator"/> with PercentGood / DurationGood counting <b>Good</b>
/// regions only — Part 13 §5.4.3.31/§5.4.3.33, and the 1.5.378.106 rule. Everything else (bounds, regions, Partial,
/// status, the millisecond Duration unit) is the baseline's own code, run under the same configuration as
/// PercentBad / DurationBad.
/// </summary>
private sealed class Part13GoodCalculator(NodeId aggregateId, DateTime startTime, DateTime endTime,
double processingInterval, bool stepped, AggregateConfiguration configuration, ITelemetryContext telemetry,
bool usePercent)
: BaselineStatusAggregateCalculator(aggregateId, startTime, endTime, processingInterval, stepped, configuration, telemetry)
{
protected override LegacyDataValue ComputeValue(TimeSlice slice)
{
var values = GetValuesWithSimpleBounds(slice);
if (values == null || values.Count == 0) return GetNoDataValue(slice);
var regions = GetRegionsInValueSet(values, false, true);
double good = 0, total = 0;
foreach (var region in regions)
{
total += region.Duration;
if (StatusCode.IsGood(region.StatusCode)) good += region.Duration;
}
var value = new LegacyDataValue
{
WrappedValue = ZB.MOM.WW.OtOpcUa.OpcUaServer.SdkValueBoundary.FromClr(usePercent ? good / total * 100 : good),
SourceTimestamp = GetTimestamp(slice),
ServerTimestamp = GetTimestamp(slice),
};
value.StatusCode = value.StatusCode.WithAggregateBits(AggregateBits.Calculated);
return value;
}
}
/// <summary>The <see cref="CompatibilityAggregateFactory"/> adapter, for a calculator built here.</summary>
/// <summary>The <see cref="CompatibilityAggregateFactory"/> adapter, for a baseline calculator built here.</summary>
private sealed class LegacyCalculatorAdapter(BaselineAggregateCalculator calculator) : IAggregateCalculator
{
public NodeId AggregateId => calculator.AggregateId;
@@ -414,9 +414,10 @@ public sealed class SdkAggregateParityTests
public void PercentGood_keeps_Uncertain_out_of_Good_per_Part_13_where_the_baseline_SDK_counts_it_as_Good(
double from, double to)
{
// #796, documented divergence (SdkAggregateOracle remarks). Part 13 §5.4.3.31 / §5.4.3.33: PercentGood is the Good
// share of the interval. The 1.5.378.182 StatusAggregateCalculator, under the server's TreatUncertainAsBad = false,
// adds Uncertain regions to it (1.5.378.106 did not). Hand-computed over 4 × 5 s regions G / U / B / G:
// #796, documented divergence of the untouched baseline (SdkAggregateOracle remarks; live follows Part 13 since
// #809). Part 13 §5.4.3.31 / §5.4.3.33: PercentGood is the Good share of the interval. The 1.5.378.182
// StatusAggregateCalculator, under the server's TreatUncertainAsBad = false, adds Uncertain regions to it
// (1.5.378.106 did not). Hand-computed over 4 × 5 s regions G / U / B / G:
// Good 10 s ⇒ 50 %, Bad 5 s ⇒ 25 %, Uncertain 5 s in neither; the baseline says 75 % Good.
Pct(AsIs(HistoryAggregateType.PercentGood, from, to, GoodUncertainBadGood))
.ShouldBe(75d, 1e-9, "the baseline counts the Uncertain 5 s as Good — if this moves, revisit the oracle (#796)");
@@ -524,15 +525,16 @@ public sealed class SdkAggregateParityTests
public void An_Uncertain_first_sample_in_a_late_start_interval_makes_the_SDK_integrate_the_time_before_the_data(
double from, double to)
{
// #821, pinned divergence (pending the #809/#821 owner decision — this test records, it does not choose).
// #821, pinned divergence (pending the #821 owner decision — this test records, it does not choose).
// Part 13 §5.4.3.3/§5.4.3.8: the interpolated-bounding signal is defined from the first sample only — 10 → 11 over
// [5,12) (73.5) and 11 → 11 + 8/13 over [12,20) (4·(22 + 8/13)) ⇒ Total 163.96…, TimeAverage = Total ÷ 15 s.
const double part13Total = 73.5 + 88 + 32d / 13;
Pct(Ours(HistoryAggregateType.Total, from, to, 0, UncertainFirstLateStart)).ShouldBe(part13Total, 1e-9);
Pct(Ours(HistoryAggregateType.TimeAverage, from, to, 0, UncertainFirstLateStart)).ShouldBe(part13Total / 15, 1e-9);
// The frozen 1.5.378.182 calculators — exactly what the server registers for live AggregateFilter items
// (CompatibilityAggregateFactory; Sdk2AggregateCompatibilityTests proves the runtime manager serves the same code)
// The frozen 1.5.378.182 calculators — for Total / TimeAverage exactly what the server registers for live
// AggregateFilter items (CompatibilityAggregateFactory; Sdk2AggregateCompatibilityTests proves the runtime manager
// serves the same code)
// — integrate the uncovered [0,5) as a ramp 0 → 10 (+25) and divide TimeAverage by the WHOLE 20 s interval.
Pct(AsIs(HistoryAggregateType.Total, from, to, UncertainFirstLateStart)).ShouldBe(part13Total + 25, 1e-9);
Pct(AsIs(HistoryAggregateType.TimeAverage, from, to, UncertainFirstLateStart)).ShouldBe((part13Total + 25) / 20, 1e-9);
@@ -557,16 +559,108 @@ public sealed class SdkAggregateParityTests
Stock201(agg, from, to, GoodFirstLateStart).Single().Value!.Value.ShouldBe(expected, 1e-9);
}
// #809 on the same input: DurationGood / PercentGood — Part 13 (ours) and stock SDK 2.0.1 count Good regions only
// ([12,20) = 8 s); the frozen live calculators also count the Uncertain [5,12) as Good (15 s).
// #809 on the same input: DurationGood / PercentGood — Part 13 (ours), stock SDK 2.0.1 and, since #809, the live
// calculators count Good regions only ([12,20) = 8 s); the untouched baseline (live before #809) also counted the
// Uncertain [5,12) as Good (15 s).
Pct(Ours(HistoryAggregateType.DurationGood, from, to, 0, UncertainFirstLateStart)).ShouldBe(8_000d, 1e-9);
Stock201(HistoryAggregateType.DurationGood, from, to, UncertainFirstLateStart).Single().Value!.Value.ShouldBe(8_000d, 1e-9);
Pct(Sdk(HistoryAggregateType.DurationGood, from, to, 0, UncertainFirstLateStart)).ShouldBe(8_000d, 1e-9);
Pct(AsIs(HistoryAggregateType.DurationGood, from, to, UncertainFirstLateStart)).ShouldBe(15_000d, 1e-9);
Pct(Ours(HistoryAggregateType.PercentGood, from, to, 0, UncertainFirstLateStart)).ShouldBe(40d, 1e-9);
Stock201(HistoryAggregateType.PercentGood, from, to, UncertainFirstLateStart).Single().Value!.Value.ShouldBe(40d, 1e-9);
Pct(Sdk(HistoryAggregateType.PercentGood, from, to, 0, UncertainFirstLateStart)).ShouldBe(40d, 1e-9);
Pct(AsIs(HistoryAggregateType.PercentGood, from, to, UncertainFirstLateStart)).ShouldBe(75d, 1e-9);
}
/// <summary>
/// #809: the #810 QualityMix tag Q — Good / Uncertain / Bad samples and an outage marker, Uncertain regions starting
/// at a sample, through a sloped bound and held into an outage, with Good samples before (−10) and after (+90) every
/// window so no interval holds the start or the end of the data.
/// </summary>
private static readonly StoredSample[] UncertainMix =
[
S(-10, HistorianValue.FromDouble(10), Good),
S(0, HistorianValue.FromDouble(10), Good),
S(4, HistorianValue.FromDouble(12), Uncertain),
S(7, HistorianValue.FromDouble(13), Bad),
S(10, HistorianValue.FromDouble(14), Good),
S(13, HistorianValue.FromDouble(15), Uncertain),
S(20, HistorianValue.FromDouble(16), Uncertain),
S(25, HistorianValue.FromDouble(17), Uncertain),
S(33, HistorianValue.FromDouble(18), Uncertain),
S(40, HistorianValue.FromDouble(20), Good),
S(45, HistorianValue.Empty, BadNoCommunication),
S(50, HistorianValue.FromDouble(22), Uncertain),
S(56, HistorianValue.FromDouble(23), Good),
S(64, HistorianValue.FromDouble(25), Uncertain),
S(67, HistorianValue.FromDouble(26), Good),
S(75, HistorianValue.FromDouble(27), Bad),
S(78, HistorianValue.FromDouble(28), Good),
S(90, HistorianValue.FromDouble(30), Good),
];
/// <summary>Windows of whole intervals only (no truncated interval — ours flags it Partial, a documented divergence).</summary>
public static TheoryData<double, double, double> WholeIntervalWindows => new()
{
{ 0, 80, 20 }, { 80, 0, 20 },
{ 0, 80, 10 }, { 80, 0, 10 },
{ 5, 80, 15 }, { 80, 5, 15 },
{ 0, 60, 0 }, { 60, 0, 0 },
};
[Theory]
[MemberData(nameof(WholeIntervalWindows))]
public void Live_AggregateFilter_PercentGood_and_DurationGood_equal_HistoryRead_over_Uncertain_samples(
double from, double to, double intervalS)
{
// #809: a live AggregateFilter monitored item and a HistoryRead-Processed (SqlServer / QuestDB share
// TimeWeightedAggregator) answer PercentGood / DurationGood identically over Uncertain data — same values,
// timestamps, status and Partial / Calculated bits, with NO documented-divergence mask. RunLive is exactly
// CompatibilityAggregateFactory.Create, the calculator the server registers (Sdk2AggregateCompatibilityTests
// proves the booted runtime manager serves the same code).
var interval = intervalS > 0 ? TimeSpan.FromSeconds(intervalS) : (At(to) - At(from)).Duration();
var failures = new List<string>();
var discriminated = 0;
foreach (var agg in new[] { HistoryAggregateType.PercentGood, HistoryAggregateType.DurationGood })
foreach (var (name, data) in new[] { ("UncertainMix", UncertainMix), ("DenseUncertain", DenseUncertain) })
{
var rows = data.Select(x => (x.TimeUtc, x.Value, x.Status)).ToArray();
var live = SdkAggregateOracle.RunLive(agg, At(from), At(to), interval, rows);
try
{
SdkAggregateOracle.ShouldMatch(Ours(agg, from, to, intervalS, data), live, $"live {agg} {name} {from}→{to}/{intervalS}s");
}
catch (Exception ex)
{
failures.Add(ex.Message);
}
// The data must discriminate: the pre-#809 live calculator (the untouched baseline) counts the Uncertain
// time as Good, so it disagrees somewhere — or this parity would pass against the old behaviour too.
var before = SdkAggregateOracle.RunSdkAsIs(agg, At(from), At(to), interval, rows);
if (before.Zip(live).Any(p => Math.Abs(Convert.ToDouble(p.First.Value) - Convert.ToDouble(p.Second.Value)) > 1e-9))
discriminated++;
}
failures.ShouldBeEmpty(string.Join("\n", failures));
discriminated.ShouldBe(4, "every aggregate × data set must differ from the pre-#809 live answer somewhere");
}
[Fact]
public void Live_AggregateFilter_PercentGood_and_DurationGood_are_the_hand_computed_Part_13_values()
{
// #809, hand-computed over UncertainMix's eight 10 s intervals (QualityMixConformance derives them region by
// region): Good seconds 4, 3, 0, 0, 5, 4, 3, 2. The pre-#809 live answer added the Uncertain time
// (7, 10, 10, 10, 5, 10, 10, 7 s).
double[] goodSeconds = [4, 3, 0, 0, 5, 4, 3, 2];
var rows = UncertainMix.Select(x => (x.TimeUtc, x.Value, x.Status)).ToArray();
var ten = TimeSpan.FromSeconds(10);
SdkAggregateOracle.RunLive(HistoryAggregateType.DurationGood, At(0), At(80), ten, rows)
.Select(r => Convert.ToDouble(r.Value)).ShouldBe(goodSeconds.Select(g => g * 1000), tolerance: 1e-9);
SdkAggregateOracle.RunLive(HistoryAggregateType.PercentGood, At(0), At(80), ten, rows)
.Select(r => Convert.ToDouble(r.Value)).ShouldBe(goodSeconds.Select(g => g * 10), tolerance: 1e-9);
SdkAggregateOracle.RunSdkAsIs(HistoryAggregateType.DurationGood, At(0), At(80), ten, rows)
.Select(r => Convert.ToDouble(r.Value)).ShouldBe([7000d, 10000, 10000, 10000, 5000, 10000, 10000, 7000], tolerance: 1e-9);
}
/// <summary>#684: Good 10 / 30 with an Uncertain value BELOW the Good minimum (+4) and one ABOVE the maximum (+6).</summary>
private static readonly StoredSample[] UncertainBeyond =
[