histsdk/docs/plans/speculative-items-sweep.md

# Plan: Speculative Items Sweep (2026-05-04)

The five items I previously called out as speculative / deferred. Goal:
exercise the cheap ones, investigate the medium ones to feasibility, and
write sub-plans for anything too big to ship in one push.

## Items

| ID | Item | Effort | Touches |
|---|---|---|---|
| C3 | Expose `IntegralDivisor` on `HistorianTagDefinition` | small | `HistorianTagDefinition.cs`, `HistorianTagWriteProtocol.cs`, orchestrator, tests |
| E  | Unit tests for `AllowUntrustedServerCertificate` / `ServerDnsIdentity` | small | new test file under `tests/` |
| D3 | Root-cause Discrete/String/Int1/Int8/UInt8 EnsT2 failure | medium (investigation) | native harness, possibly serializer |
| D1 | Capture wire bytes for `AddTagExtendedProperties` | medium (capture + decode) | native harness, possibly new serializer + public API |
| D2 | Implement `AddRevisionValuesBegin/Value/End` (revision-write path) | large | new orchestrator + 3 new public APIs |

## Parallelism

Concurrency-safe groupings (each pair is independent at the file level):

- **C3 ↔ E** — C3 touches `HistorianTagDefinition.cs` + `HistorianTagWriteProtocol.cs` + orchestrator + integration tests; E adds a new test file + might add a small unit-test util. No file overlap.
- **D3 ↔ D1** — Both touch the native trace harness Program.cs, so they conflict if done concurrently. Sequence them.
- **C3/E ↔ D3/D1** — No file overlap; can run concurrently with the harness work.
- **D2** stands alone (different code paths entirely).

In a single-agent session, the order is:

1. C3 (small, predictable) — land first
2. E (small, predictable) — land second
3. D3 (investigation; documents findings whether or not implementation is possible)
4. D1 (investigation + capture; same pattern)
5. D2 — write a focused sub-plan; do NOT implement in this sweep

## Success Criteria

- C3: `HistorianTagDefinition.IntegralDivisor` (default 1.0) plumbed through serializer; unit test asserts non-default value flips the wire bytes; live test asserts the value persists in `Tag.IntegralDivisor` (or wherever it lands in SQL).
- E: 2-3 unit tests asserting `HistorianWcfClientCredentialsHelper.Configure` and `HistorianWcfBindingFactory.CreateEndpointAddress` honor the new options.
- D3: documented root cause + decision (workable path / not workable / requires further capture). If a workable path emerges quickly, also implement.
- D1: documented evidence summary + decision (worth implementing / defer / requires customer ask).
- D2: `docs/plans/revision-write-path.md` (or similar) with the 5-step capture sequence + open questions.

## Findings

### C3 — IntegralDivisor (executed 2026-05-05)

Plumbed through serializer + orchestrator; default 1.0. Unit test verifies
the 8-byte double immediately preceding the trailer flips with a non-default
value. Live probe: server accepts the wire bytes but `IntegralDivisor`
appears to be stored on `EngineeringUnit` (shared across all tags using that
EU) rather than per-tag, and the EU's stored value didn't change for the
test. Documented in the property's doc-comment. No live integration test
added (nothing to assert in SQL).

### E — Cert option unit tests (executed 2026-05-05)

Added `HistorianWcfCertOptionTests` (5 tests) covering:

- `Configure` is a no-op when `AllowUntrustedServerCertificate=false`
- `Configure` installs the accept-any validator + `RevocationMode.NoCheck`
  when the option is true
- `CreateEndpointAddress` with no DNS identity returns an address with
  `Identity == null`
- `CreateEndpointAddress` with a DNS identity attaches a `DnsEndpointIdentity`
- `CreateBindingPair(RemoteTcpCertificate)` propagates `ServerDnsIdentity`
  to the History endpoint (and not to the Retrieval endpoint, which uses
  plain MdasNetTcp without TLS)

### D3 — Discrete/String/Int1/Int8/UInt8 EnsT2 root cause (investigated 2026-05-05)

Probed each unsupported type via the native trace harness with
`--write-data-type {Type}`. Result for SingleByteString and Int1 (others
truncated in the same output):

- `HistorianAccess.AddTag` returns `Success=false`, `TagKey=0`
- Error: `ErrorCode=ValidationFailed`, `ErrorType=CustomError`,
  `ErrorDescription="Transaction validation failed"`

**Conclusion:** The failure is **server-side**, not wire-format. The
`/Hist.EnsT2` server-side validator rejects non-analog types when invoked
through the `AddTag → EnsT2` code path. To unlock these types from the SDK
we'd need to:

1. Capture a successful native creation of a discrete/string tag via some
   other mechanism (likely SMC's tag-import path or a different WCF op
   like `AddTagExtendedProperties` carrying the discrete/string-specific
   metadata)
2. Diff the working native flow against the failing one to see what
   ancillary fields the validator expects (TagType vs CDataType, separate
   StorageType, IO-server pre-registration, etc.)

**Decision:** defer until a customer asks. The native AVEVA wrapper itself
cannot create these tags via `AddTag` from a managed client — implementing
this would require RE work on a path the wrapper doesn't exercise, which
is much higher risk than the existing analog write surface.

### D1 — AddTagExtendedProperties feasibility (investigated 2026-05-05)

Managed surface confirmed. Native API:

- Public managed entry point: `ArchestrA.HistorianAccess.AddTagExtendedProperties`
  (token `0x0600619B`, 140 IL instructions, 6 locals)
- WCF op: `CHistoryConnectionWCF.AddTagExtendedPropertyGroups`
  (token `0x0600405C`)
- Underlying contract method: `IHistoryServiceContract2.AddTagExtendedProperties`
  (already declared in our reproduced contracts)
- Managed input type: `HistorianTagExtendedPropertyGroup` wrapping the native
  `CTagExtendedPropertyGroup` C++ class. Built from a `std::vector<CTagExtendedPropertyGroup>`
  (visible in the IL locals). Property group structure not yet decoded.

**Decision:** defer implementation. Cost estimate:

1. Reflect-construct `HistorianTagExtendedPropertyGroup` via the native
   harness (probably 2-4 hours — these C++/CLI types often have hidden
   constructor requirements that surface only at runtime).
2. Call `AddTagExtendedProperties` with a sandbox group; capture wire bytes
   via `instrument-wcf-writemessage` (1 hour).
3. Decode the `CTagExtendedPropertyGroup` payload — this is its own struct
   that needs walking field-by-field against the native serializer IL
   (token `0x06002038`, `CHistStorage.AddTagExtendedProperties`) (3-6 hours).
4. Implement managed `HistorianTagExtendedPropertyGroup` model + serializer
   + public `AddTagExtendedPropertiesAsync` API + tests (4-6 hours).

Total: 1-2 days of focused work. Defer until a customer asks for tag
extended properties or the analog write surface needs them as a
prerequisite.

### D2 — AddRevisionValuesBegin/Value/End

Sub-plan deferred to a dedicated session — see
`docs/plans/revision-write-path.md` (created in this sweep).

## Out of scope for this sweep

Refactoring `HistorianWcfTagClient` to respect `options.Transport` for browse / metadata (i.e., let it use cert binding from Windows). Worth doing but not part of the speculative-items list.