fix(historian): map Boolean historization to Int2, not degenerate Int1 (#441)
v2-ci / build (pull_request) Successful in 3m24s
v2-ci / unit-tests (pull_request) Failing after 8m19s

The historian's Int1 analog-tag creation path is server-degenerate:
EnsureTags(Int1) stores an unusable stub (live-probed on the deployed
2023 R2 historian; root-caused + documented gateway-side in
HistorianGateway #11 / PR #16). HistorianTypeMapper mapped
DriverDataType.Boolean -> HistorianDataType.Int1, so Boolean historized
tags failed auto-provisioning.

Map Boolean -> Int2 instead (store 0/1). Int2 is a proven-creatable
analog type, and the value-write path already sends every value as a
double on WriteLiveValues regardless of tag type, so Boolean 0.0/1.0
round-trips cleanly. Both Float and Int2 are supported, so a
pre-existing Float Boolean tag retypes cleanly on its next deploy.

- HistorianTypeMapper: Boolean => Int2 (+ remarks)
- Unit pins: HistorianTypeMapperTests, GatewayTagProvisionerTests
  (Boolean_definition_carries_explicit_Int2_presence)
- Live gate: EnsureTags_boolean_sandbox_provisions_as_Int2 (was _Int1);
  retype probe reframed Float->Int2 (drops the dead Int1 leg)
- Docs: docs/Historian.md 'Boolean historization maps to Int2', CLAUDE.md,
  archreview STATUS.md (R2-06 live gate -> 6/6)

Resolves #441.
This commit is contained in:
Joseph Doherty
2026-07-14 11:57:27 -04:00
parent 7f79cd5941
commit 9f62310b49
7 changed files with 106 additions and 96 deletions
@@ -255,25 +255,26 @@ public sealed class GatewayLiveIntegrationTests(GatewayLiveFixture fixture) : IC
}
/// <summary>
/// archreview 06/U-7 — Boolean provisioning leg on the 0.2.0 contract. Through the <b>real</b>
/// issue #441 — Boolean historization leg. Through the <b>real</b>
/// <see cref="GatewayTagProvisioner"/>, <c>EnsureTags</c> a <see cref="DriverDataType.Boolean"/>
/// request for the dedicated Boolean sandbox tag (mapped to <c>Int1</c> with explicit proto3
/// presence), assert it is ensured (not failed), then <c>WriteLiveValues</c> a <c>1.0</c> and read
/// it back over a wide window. This retires "the live EnsureTags leg has never run on 0.2.0" for
/// the Boolean path. The ±12h read window + timezone caveat mirror <see cref="Write_then_read_on_sandbox_tag"/>.
/// request for the dedicated Boolean sandbox tag (mapped to <c>Int2</c> — the historian's
/// <c>Int1</c> analog-tag creation path is server-degenerate, see issue #441 / HistorianGateway
/// #11, so Boolean historizes as a small 0/1 integer), assert it is ensured (not failed), then
/// <c>WriteLiveValues</c> a <c>1.0</c> and read it back over a wide window. The ±12h read window
/// + timezone caveat mirror <see cref="Write_then_read_on_sandbox_tag"/>.
/// </summary>
[Fact]
[Trait("Category", "LiveIntegration")]
public async Task EnsureTags_boolean_sandbox_provisions_as_Int1()
public async Task EnsureTags_boolean_sandbox_provisions_as_Int2()
{
if (_fx.NotConfigured) Assert.Skip(_fx.SkipReason!);
if (_fx.BoolSandboxTag is null)
Assert.Skip("Skipped: set HISTGW_BOOL_SANDBOX_TAG to a writable Boolean sandbox tag (e.g. HistGW.LiveTest.BoolSandbox) to run the 0.2.0 Boolean EnsureTags leg.");
Assert.Skip("Skipped: set HISTGW_BOOL_SANDBOX_TAG to a writable Boolean sandbox tag (e.g. HistGW.LiveTest.BoolSandbox) to run the Boolean historization leg.");
var ct = TestContext.Current.CancellationToken;
var tag = _fx.BoolSandboxTag;
// EnsureTags (Boolean → Int1) through the REAL provisioner seam (the same code path deploys use).
// EnsureTags (Boolean → Int2) through the REAL provisioner seam (the same code path deploys use).
await using var writeClient = _fx.CreateClient();
var provisioner = new GatewayTagProvisioner(writeClient, NullLogger<GatewayTagProvisioner>.Instance);
var provision = await provisioner.EnsureTagsAsync(
@@ -281,7 +282,7 @@ public sealed class GatewayLiveIntegrationTests(GatewayLiveFixture fixture) : IC
ct);
provision.Ensured.ShouldBe(1,
"the Boolean sandbox tag must be ensured (needs the gateway on 0.2.0 contracts + an API key carrying historian:tags:write).");
"the Boolean sandbox tag must be ensured as Int2 (needs the gateway on 0.2.0+ contracts + an API key carrying historian:tags:write).");
provision.Failed.ShouldBe(0);
// WriteLiveValues a Boolean-as-1.0 and read it back (SQL live path can lag a flush cadence → poll).
@@ -308,14 +309,16 @@ public sealed class GatewayLiveIntegrationTests(GatewayLiveFixture fixture) : IC
hit.ShouldNotBeNull($"the written Boolean sample ({written}) should read back from '{tag}'.");
TestContext.Current.SendDiagnosticMessage(
$"Boolean round-trip: EnsureTags(Int1) + WriteLiveValues '{tag}'={written} → read back at {hit!.SourceTimestampUtc:O}.");
$"Boolean round-trip: EnsureTags(Int2) + WriteLiveValues '{tag}'={written} → read back at {hit!.SourceTimestampUtc:O}.");
}
/// <summary>
/// archreview 06/U-7 retype probe — answers the assessment note's open question: what does the
/// deployed AVEVA Historian do when <c>EnsureTags</c> (an <b>upsert</b>) is asked to change an
/// existing tag's type? Against the <b>dedicated Boolean sandbox tag only</b> (never the shared
/// Float write sandbox), EnsureTags first as <c>Float</c> then as <c>Int1</c> and assert the second
/// Float write sandbox), EnsureTags first as <c>Float</c> then as <c>Int2</c> (both supported
/// analog types — <c>Int2</c> is the type Boolean now historizes as; the previously-probed
/// <c>Int1</c> is a documented server-degenerate exclusion, issue #441) and assert the second
/// call's per-tag outcome is <em>deterministic and observable</em> — either <c>Success=true</c>
/// (retype / tag-versioning accepted) or <c>Success=false</c> with a non-empty <c>Error</c> (mapped
/// to the provisioner's <c>failed</c> tally). The assertion accepts both because the contract
@@ -336,7 +339,7 @@ public sealed class GatewayLiveIntegrationTests(GatewayLiveFixture fixture) : IC
await using var client = _fx.CreateClient();
// First establish the tag as Float, then ask EnsureTags to retype it to Int1 (Boolean).
// First establish the tag as Float, then ask EnsureTags to retype it to Int2.
await client.EnsureTagsAsync(
new[]
{
@@ -357,9 +360,9 @@ public sealed class GatewayLiveIntegrationTests(GatewayLiveFixture fixture) : IC
new HistorianTagDefinition
{
TagName = tag,
DataType = HistorianDataType.Int1,
DataType = HistorianDataType.Int2,
EngineeringUnit = string.Empty,
Description = "OtOpcUa live validation retype probe (stage 2: Int1)",
Description = "OtOpcUa live validation retype probe (stage 2: Int2)",
StorageRateMs = 1000, // 0 makes the gateway's EnsureTags throw (storageRateMs must be > 0).
},
},
@@ -372,7 +375,7 @@ public sealed class GatewayLiveIntegrationTests(GatewayLiveFixture fixture) : IC
"or Success=false with a non-empty Error (mapped to the provisioner's failed tally).");
TestContext.Current.SendDiagnosticMessage(
$"retype probe '{tag}' Float→Int1: Success={outcome.Success}, Error='{outcome.Error}'. " +
$"retype probe '{tag}' Float→Int2: Success={outcome.Success}, Error='{outcome.Error}'. " +
"(records the deployed historian's in-place analog-retype policy — feed this back into docs/Historian.md).");
}
}