histsdk/AGENTS.md

AGENTS.md

Mission

Build a fully managed .NET 10 replacement for AVEVA Historian's aahClientManaged / aahClient.dll stack by reverse-engineering the native binary Historian protocol.

The target is an in-process managed SDK that can replace the current .NET Framework/native sidecar used by OtOpcUa.Driver.Historian.Wonderware.

Chosen Approach

Use the reverse-engineering path from instructions.md:

1. Decompile current\aahClientManaged.dll to understand the managed wrapper surface, connection flow, query types, data models, error handling, and native calls.
2. Inspect current\aahClient.dll and the matching AVEVA install DLLs to map the native ABI and identify transport/framing responsibilities.
3. Capture traffic from real Historian sessions and derive the on-the-wire protocol for the required read-only operations.
4. Implement the protocol in a pure managed .NET 10 client.

Do not pursue the REST API implementation unless explicitly asked. Do not build a P/Invoke shim as the primary solution; it is useful only as an analysis aid.

Repository Layout

This workspace is a full Git repo (origin: gitea.dohertylan.com) with the shipping SDK under src/, tests under tests/, RE tooling under tools/, and decoded protocol notes under docs/. See CLAUDE.md for the authoritative architecture overview.

• instructions.md - source planning document and decision record.
• src\AVEVA.Historian.Client\ - the production managed SDK (pure .NET 10, no native AVEVA references).
• tests\AVEVA.Historian.Client.Tests\ - unit + gated live integration tests.
• tools\ - reverse-engineering tooling (CLI, native trace harness, WCF capture server, IL-rewrite instrumentation helper).
• docs\reverse-engineering\ - sanitized RE evidence and decoded notes.
• current\ - the seven DLLs the existing sidecar links against today.
• aveva-install-x64\ and aveva-install-x86\ - full AVEVA Historian client-side DLL sets for cross-version reference.

Use current\ first because it represents the deployed sidecar dependency set. Use aveva-install-* to compare architecture-specific behavior and locate adjacent client APIs.

Required SDK Surface

The shipping public surface (all live-verified against localhost — see CLAUDE.md "Required SDK Surface" for the authoritative list and caveats):

Reads:

• ProbeAsync
• ReadRawAsync
• ReadAggregateAsync
• ReadAtTimeAsync
• ReadEventsAsync
• BrowseTagNamesAsync
• GetTagMetadataAsync
• Status helpers: GetConnectionStatusAsync, GetStoreForwardStatusAsync, GetSystemParameterAsync

Writes (added 2026-05-04 by explicit request):

• EnsureTagAsync for analog Float / Double / Int2 / Int4 / UInt4 (with optional ApplyScaling=true for distinct MinRaw/MaxRaw and optional StorageRateMs for non-default sampling).
• DeleteTagAsync.

AddS2 (write samples) is architecturally blocked — the server's runtime cache only ingests from configured IOServer / Application Server pipelines. Do not extend write support without an explicit new request.

Reverse-Engineering Workflow

The bulk of the original RE workflow has been executed and is now backed by docs/reverse-engineering/ evidence. The notes below are the durable process in case new captures are needed (e.g., for a new Historian version or a new write op).

1. Managed Wrapper Analysis

Use dnSpy / ILSpy / the in-repo dnlib-method CLI on current\aahClientManaged.dll.

Document:

• Public types and methods used for connections and queries.
• P/Invoke or native interop entry points.
• Constructor arguments, enum values, flags, and default values.
• Query argument structures for raw, aggregate, at-time, and event reads.
• Returned sample/event models, quality fields, timestamp handling, and error propagation.

Sanitized notes go under docs\reverse-engineering\ (the folder exists and is the canonical home for committed RE evidence).

2. Native ABI Mapping

Inspect current\aahClient.dll and compare with:

• aveva-install-x64\aahClient.dll
• aveva-install-x86\aahClient.dll
• aahClientCommon.dll
• aahDataSetClient.dll
• aahClientConfig.dll

Useful tools:

• dumpbin /exports
• Dependencies or Process Monitor
• API Monitor
• Detours or equivalent call hooks

Document function names, calling conventions, pointer ownership, HRESULT/error patterns, string encodings, and architecture differences.

3. Wire Capture

Capture real Historian sessions with Wireshark while running the existing Wonderware sidecar/client against a development Historian.

Capture each scenario independently:

• Connection open/close and health probe.
• Raw history query.
• Aggregate query for each required retrieval mode.
• At-time/interpolated query.
• Event query.
• Error cases: bad tag, empty range, invalid credentials, server offline.

For every capture, record:

• Historian version and architecture.
• Client DLL version and file hash.
• Server host/port.
• Query parameters.
• Expected logical result set.
• Packet capture filename.

Do not commit sensitive packet captures, credentials, server names, or customer tag names. Sanitize before adding any fixtures or notes.

4. Protocol Model

Derive and document:

• Session handshake.
• Authentication exchange, if present.
• Message framing and length prefixes.
• Message type identifiers.
• Request/response correlation.
• Endianness.
• Timestamp encoding.
• String encoding.
• Numeric value encoding.
• Quality/status encoding.
• Error frame format.
• Event payload format.

Add version notes whenever behavior differs between the installed 2020 DLLs and newer Historian versions.

5. Managed Implementation Shape

The implementation has landed and is the authoritative reference. See CLAUDE.md "Code Architecture" for the actual layout. The original abstract shape is preserved as historical context only.

Key design rule still in force: keep protocol parsing isolated from transport I/O so captured frames can be tested without a live Historian.

Testing Expectations

Start with deterministic tests around protocol encoding/decoding:

• Golden byte fixtures for each message kind.
• Round-trip tests for request builders.
• Parser tests for captured and sanitized response frames.
• Timestamp, quality, and string encoding edge cases.
• Error frame parsing.

Add live integration tests only behind explicit configuration, such as:

• HISTORIAN_HOST
• HISTORIAN_PORT
• HISTORIAN_USER
• HISTORIAN_PASSWORD
• HISTORIAN_TEST_TAG

Integration tests must skip cleanly when these values are not configured.

Constraints

• Keep the final SDK managed .NET 10. The single P/Invoke surface allowed in production is HistorianSspiClient (Windows SSPI for integrated auth); do not add unrelated P/Invokes.
• Avoid adding native runtime dependencies to the production SDK. No reference to aahClientManaged.dll / aahClient.dll from src/.
• Avoid broad API design. Implement only the operations listed in "Required SDK Surface".
• Treat AVEVA protocol details as version-sensitive; document assumptions in docs/reverse-engineering/.
• Do not redistribute AVEVA binaries.
• Do not commit credentials, proprietary captures, or customer data.
• Do not delete or overwrite DLLs in current\ or aveva-install-*.

Definition of Done

Both the RE phase and the SDK phase are met as of 2026-05-04:

• Managed wrapper public surface and native entry points are documented in docs/reverse-engineering/.
• Required query flows have sanitized captures + byte-level notes; golden fixtures live under fixtures/protocol/.
• Message framing, request/response/error layouts are decoded sufficiently for round-trip parser tests.
• The shipping SDK implements the Required SDK Surface (reads + writes).
• 169 unit + live integration tests pass.
• Local consumers can replace the sidecar without aahClientManaged.dll or aahClient.dll at runtime.

Future RE work (e.g., new Historian version, additional write ops) should follow the same workflow above; new evidence updates docs/reverse-engineering/ and the relevant plan file under docs/plans/.