histsdk/docs/reverse-engineering/managed-wrapper-findings.md

# Managed Wrapper Findings

Source assembly: `current\aahClientManaged.dll`

Tooling used: `ilspycmd 10.0.0.8330`

## Confirmed Shape

`aahClientManaged.dll` is a mixed-mode C++/CLI wrapper. The public managed API is
under the `ArchestrA` namespace, but query execution calls native
`HistorianClient` methods through C++ pointers rather than plain P/Invoke
methods.

`dumpbin /dependents` confirms the deployed wrapper does not import
`aahClient.dll` or `aahClientCommon.dll`. It is a self-contained mixed-mode
wrapper over system DLLs and the CLR (`mscoree.dll`), so the active wrapper path
must be captured inside `aahClientManaged.dll` or at system/WCF boundaries.

The production read surface maps to these wrapper types:

- `ArchestrA.HistorianAccess`
- `ArchestrA.HistorianConnectionArgs`
- `ArchestrA.HistoryQueryArgs`
- `ArchestrA.HistoryQuery`
- `ArchestrA.HistoryQueryResult`
- `ArchestrA.EventQueryArgs`
- `ArchestrA.EventQuery`
- `ArchestrA.HistorianEvent`

## Connection Facts

`HistorianConnectionArgs` defaults:

- `TcpPort = 32568`
- `ServerName = "localhost"`
- `ReadOnly = true`
- `PacketTimeout = 1000`
- `ConnectionType = Process`
- `Compression = false`
- `IntegratedSecurity = false`

`HistorianConnectionType` is a flags enum:

- `Process = 1`
- `Event = 2`

The wrapper keeps separate client slots for process/history and event
connections.

`HistorianAccess.OpenConnection` can return `true` while the native connection
is still pending. Callers must poll `HistorianAccess.GetConnectionStatus` and
wait for `ConnectedToServer = true` and `Pending = false` before starting
queries. Starting `HistoryQuery.StartQuery` immediately after `OpenConnection`
can return native `notConnected` (`242`).

## History Query Contract

`HistoryQuery.StartQuery` eventually calls native `HistorianClient.StartDataQuery`.
It does not build or call `RetrievalServiceContract.StartQuery2` directly from
managed C#. The managed wrapper converts `HistoryQueryArgs` into native
strings, arrays, selector buffers, and enum values, then hands those to the
native `HistorianClient` implementation. That native boundary is the next
capture point for exact data-query request bytes.

Confirmed arguments include:

- Retrieval mode: cast from `ArchestrA.HistorianRetrievalMode`.
- Query format: `0`.
- Summary type: `0`.
- Tag count and UTF-16 tag pointer array.
- Start/end timestamps converted with `DateTime.ToUniversalTime().ToFileTime()`.
- Resolution, value deadband, time deadband.
- Time zone string: `UTC`.
- Version type from `DataVersion`.
- Interpolation, timestamp, quality, value selector, and aggregation enums.
- Option and filter strings converted as UTF-16 buffers.
- Selected query-column buffer.
- Max states.
- Output query handle.

Decompiled selected-column stream construction is:

- `ushort` value `1`
- 8 bytes of `QueryColumnSelector` state after
  `QueryColumnSelector.SelectNonSummaryColumns`

Focused IL extraction of `DataQueryRequest.Save<SByteStream<SCrtMemFile>>`
confirmed several request-buffer details used by the .NET 10 serializer probe:

- request packet version is `ushort 3` only when option text is exactly
  `NoOption`; otherwise it is `ushort 9` and the option string is serialized.
- offset `300` is serialized as a packed `CQTIFlags` `ushort` before
  option/filter text, not the query-column selector flags. The low byte is
  interpolation (`None` is stored as `255`; `SystemDefault` `254` is normalized
  to `255`), bits `8..11` are `HistorianTimestampRule`, and bits `12..15` are
  `HistorianQualityRule`. Ordinary full reads therefore write `0x01FF`
  (`Interpolation=None`, `TimestampRule=End`, `QualityRule=Extended`).
- the query-column selector is serialized later as `ushort 1` followed by the
  exact 8-byte selector state.
- after the MDS and storage redundant endpoint blocks, the request writes the
  raw 8-byte resolution tick field again.
- empty `CMetadataNamespace.Save` writes flag byte `1` and three empty
  `SaveScrambled` strings; each empty scrambled string is `ushort 1` followed
  by a single zero compressed-string marker byte.
- default `AutoSummaryParameters.Save` writes `ushort 2`, two zero `int64`
  values, five empty compressed strings, and the trailing zero GUID.
- `CValueSelector.Save`, `CStateCalcSelector.Save`, and `CQTIFlags.Save` each
  write a single `ushort` value.
- `SRedundantEndpoint.Save` writes endpoint name and then endpoint entries as
  node-name and pipe-name strings; there is no numeric port field in this block.

The resulting byte count and pointer are passed to `StartDataQuery` as the
selected query-column buffer arguments.

The decompiled call site passes the following high-level arguments to
`HistorianClient.StartDataQuery`:

- client pointer from the process connection slot
- retrieval mode as `INSQL_QUERYTYPE`
- query format `0`
- summary type `0`
- tag count and native UTF-16 tag array
- source count `0` and null source array
- start/end as UTC FILETIME values
- resolution, value deadband, and time deadband
- literal timezone `UTC`
- data version, interpolation type, timestamp rule, quality rule
- option text, with `NoOption` substituted when the option is not available
- value selector, aggregation type, selected-column byte count and buffer
- filter text and max states
- output query handle and native error structure

This explains the current managed WCF negative evidence: the reconstructed
`DataQueryRequest.Save` buffer is only one downstream native serialization
artifact, while the public wrapper path reaches that serializer through
`HistorianClient.StartDataQuery`.

`BaseQueryArgs.ProcessQueryArgs` clears `Resolution` to `0` for `Full`, `Delta`,
and `Slope` retrieval modes.

`HistoryQuery.MoveNext` calls native `HistorianClient.GetNextRow<DataQueryResultRow>`.

## Runtime Method Pointer Evidence

`tools\AVEVA.Historian.NativeTraceHarness` can now dump prepared CLR runtime
method pointers with `--dump-method-pointers <filter>`. This is reverse-
engineering-only evidence for hook targeting; it is not production SDK code.

Important artifacts:

- `runtime-method-pointers-startquery-latest.json`
- `runtime-method-pointers-startdataquery-latest.json`
- `runtime-method-pointers-getnextrow-latest.json`
- `runtime-method-pointers-starteventquery-latest.json`

The dump must include `assembly.ManifestModule.GetMethods(...)` because many
useful mixed-mode functions are global `<Module>` methods rather than ordinary
managed type methods. Confirmed runtime-discoverable methods include:

- `<Module>.Query.StartDataQuery`
- `<Module>.HistorianClient.StartDataQuery`
- `<Module>.ClientApp.StartDataQuery`
- `<Module>.CRetrievalConnectionWCF.StartQuery2`
- `<Module>.Query.GetNextRow`
- `<Module>.HistorianClient.GetNextRow<class DataQueryResultRow>`
- `<Module>.Query.StartEventQuery`
- `<Module>.HistorianClient.StartEventQuery`

The prepared function pointers are process-specific CLR/JIT entry addresses.
They are outside the loaded `aahClientManaged.dll` image in the current runs
(`FunctionPointerInModule = false`, `FunctionPointerRva = null`), so they must
not be treated as stable DLL RVAs. They can still be useful if discovered inside
the same target process immediately before attaching a hook, or if a CLR
profiler/rewrite pass resolves the runtime target directly.

A same-process Frida pass using these absolute runtime pointers is also
negative evidence so far. `Attach-NativeTraceHarnessRuntimePointerCapture.ps1`
launched the native trace harness, wrote the runtime pointer snapshot before
`HistoryQuery.StartQuery`, paused, generated a temporary Frida script from those
exact addresses, and installed 37 hooks. The native direct history read still
succeeded, but no hook `enter`/`leave` callbacks fired. This suggests
`MethodHandle.GetFunctionPointer()` is not the callable edge used by the
mixed-mode wrapper path in a way Frida can intercept directly.

## IL Instrumentation Evidence

Focused `ildasm` excerpts are stored as:

- `ildasm-historyquery-startquery-excerpt-latest.il`
- `ildasm-historyquery-movenext-excerpt-latest.il`
- `ildasm-classlist-filtered-latest.txt`

These excerpts confirm `ArchestrA.HistoryQuery.StartQuery` is IL with a normal
metadata-token call to the mixed-mode target:

- call site: `IL_02d2`
- target: `HistorianClient.StartDataQuery`
- metadata token: `060055E4`

`ArchestrA.HistoryQuery.MoveNext` has the same shape for row retrieval:

- call site: `IL_0054`
- target: `HistorianClient.GetNextRow<class DataQueryResultRow>`
- metadata token: `0600588D`

This is now a proven instrumentation path. A dnlib `NativeWrite` copy of
`aahClientManaged.dll` loads and runs in the native trace harness when placed in
a disposable copied DLL folder. A reverse-only IL rewrite of
`<Module>.Query.StartDataQuery` token `0600574B` inserted a logger immediately
after `DataQueryRequest.Save<SByteStream<SCrtMemFile>>` and
`endstream`. The instrumented wrapper completed a local direct read and emitted
the serialized `StartDataQuery.Request` buffer before the native WCF call.

The read-boundary instrumentation now also logs the explicit
`HistorianClient.GetNextRow<class DataQueryResultRow>` `arg.1` query handle
before dumping the `arg.2` row memory. A combined local read captured these
records in one session:

- `StartDataQuery.Request`: length `251`, SHA-256
  `543ea11af87607044067a0274b1da423cef2acbb7b4f4fab137af023a7153d7f`
- `GetNextRow.QueryHandle`: value `1`
- `GetNextRow.DataQueryResultRow`: length `512`, SHA-256
  `702f5248cf8319e3e02da33678ed97dfaa43666bddb88c42101d5290990a4198`

The harness snapshot from the same run shows `HistoryQuery.queryHandle = 1`,
so the managed wrapper field, native `GetNextRow` argument, and row buffer are
now correlated without relying on inferred state.

The next successful run instrumented the native WCF retrieval boundary itself.
`CRetrievalConnectionWCF.StartQuery2` sent the same 251-byte request through
`RetrievalServiceContract.IRetrievalServiceContract2.StartQuery2` with
`clientHandle = 256524568` and `queryRequestType = 1`. The server returned a
31-byte response buffer, SHA-256
`4c062b5ce8181308f0f46bfd8c6088acb52e6ade94401651b7d3ccc8952edfb5`, and WCF
query handle `2967`. `CRetrievalConnectionWCF.GetNextQueryResultBuffer2` then
used `clientHandle = 256524568` and `queryHandle = 2967` and returned a
570-byte result buffer, SHA-256
`f4126e0610a4c63b3dff0e41e8d15e51d75fdbc736f3ec490e7c66d1bb31638d`.

This separates the two handles: `HistoryQuery.queryHandle = 1` is the
client-side `HistorianClient` query table handle, while `/Retr` uses the server
query handle returned from `StartQuery2`.

A later correlation run added scalar logging inside
`<Module>.HistorianClient.OpenConnection` and `<Module>.Query.StartDataQuery`.
`OpenConnection` wrote legacy native handle `2`, and `Query.StartDataQuery`
read the same `*(HistorianClient + 8)` value immediately before the vtable call
into the common retrieval layer. The WCF transport method still called
`IRetrievalServiceContract2.StartQuery2` with a different transient retrieval
client handle. That means the managed read blocker is not the public
`HistoryQuery.queryHandle`, not the legacy native handle, and not the
`DataQueryRequest` bytes; it is the session mapping maintained by the native
common retrieval layer before the WCF contract call. The sanitized correlation
summary is stored in `query-handle-correlation-latest.json`.

`aahClientCommon.CServerClient.GetHandle` returns `*(this + 2528)`, but an
instrumented copy of that accessor emitted no records during the same successful
history read path. A direct metadata-token reference scan also found no IL call
sites for token `060017F9`. The handle translation is therefore either direct
field access or a virtual/calli continuation below `CRetrieval.StartQuery2`, not
this accessor.

Additional probes ruled out that assumed `CRetrieval` branch for the successful
local WCF read path: instrumented copies of
`aahClientCommon.CRetrieval.StartQuery2`,
`aahClientCommon.CSrvRetrievalConnection.StartQuery`, and
`CRetrievalConsoleClient.StartQuery` emitted no records while the WCF boundary
hooks still fired. The active handoff is `aahClientCommon.CClientCommon.StartQuery`
token `06002E86`.

`CClientCommon.StartQuery` performs the missing handle lookup immediately before
calling the WCF retrieval method. The value returned by the `CClient` vtable
call at IL offset `0x01A3` exactly matches the
`CRetrievalConnectionWCF.StartQuery2` client handle. After the WCF call returns,
the `queryHandle` pointer contains the same server query handle later passed to
`GetNextQueryResultBuffer2`. This narrows the remaining session problem to
reproducing or replacing the native `CClient` open/session state that produces
the `/Retr` client handle, not rebuilding the data-query request envelope.

`CClientBase.OpenConnection` uses the same vtable offset `24` as a handle
accessor. At the beginning of open it returns `0`; after the secondary open
branch at IL offset `0x06D4` succeeds, the accessor returns the same transient
handle consumed by `CClientCommon.StartQuery` and WCF `StartQuery2`. The primary
open branch did not fire in the local integrated read capture. The next concrete
reverse-engineering target is the secondary open vtable call and the WCF/native
contract behind it.

That secondary branch is `CHistoryConnectionWCF.OpenConnection3`, which wraps
`IHistoryServiceContract2.OpenConnection2`. The successful local read capture
logged a 1346-byte OpenConnection3 request, a 42-byte response, and an empty
error buffer. In that response, byte `0` is `0x03` and the transient `/Retr`
client handle is UInt32 little-endian at offset `1`. Deserializing the 42-byte
response initializes the vtable offset `24` handle. Raw request bytes include
local identity/process metadata, so only hashes and redacted handle relationships
are documented in
`openconnection3-correlation-latest.json`.

The first captured full-history request for deterministic tag
`OtOpcUaParityTest_001.Counter` is 251 bytes with SHA-256
`3581ef3b42b59b46503d1aa0127fa60fe4b40943e419aeab99e47e4683888851`.
The sanitized byte dump is stored in
`startdataquery-request-buffer-latest.json`; raw generated binaries and runtime
capture files stay under ignored `artifacts\reverse-engineering`.

This fixture corrected the managed serializer in three places:

- `BatchSize` is not serialized in `DataQueryRequest`.
- A reserved `uint32 0` follows `SkipRows`.
- `AutoSummaryParameters` serializes as version `1`, two zero `int64` values,
  five zero flag bytes, and a final `uint32 0`.

The production-side WCF request serializer now has a byte-for-byte test against
this native buffer.

The same instrumentation captured a `TimeWeightedAverage` aggregate
`StartDataQuery.Request` for a one-minute resolution window. It is also 251
bytes; SHA-256 is
`954874bf851bdea6333b8a8159f036e19b124b7a5febefb0cb9c9a8564b20981`, and the
sanitized dump is stored in
`startdataquery-timeweightedaverage-request-buffer-latest.json`.

Confirmed aggregate differences versus full-history:

- request query type at offset `0x02` is `5`
- first resolution field at offset `0x1E` is `double 600000000.0`
- later resolution field at offset `0xD0` is `int64 6000000000000`
- `BatchSize = 3` from `HistoryQueryArgs` is still not serialized in the
  `DataQueryRequest` buffer

The managed serializer now has a second byte-for-byte fixture test for this
aggregate request.

An `Interpolated` request with the same one-minute resolution also serializes
to 251 bytes. SHA-256 is
`fc3a2fcc28d1926d2bd1de477e306cb0930e80a3327be6309b6e834e2951ca26`, and the
sanitized dump is stored in
`startdataquery-interpolated-request-buffer-latest.json`.

Confirmed interpolated request details:

- request query type at offset `0x02` is `3`
- first resolution field at offset `0x1E` is `double 600000000.0`
- later resolution field at offset `0xD0` is `int64 6000000000000`
- the rest of the default filter, metadata namespace, endpoint, and
  auto-summary tail match the full-history and aggregate fixtures

The managed serializer now has byte-for-byte fixture coverage for full history,
time-weighted aggregate, and interpolated data requests.

A second IL rewrite instrumented
`<Module>.HistorianClient.GetNextRow<class DataQueryResultRow>` token
`0600588D` immediately after the call to
`Query.GetNextQueryResultRow<class DataQueryResultRow>` token `060058AF`.
The successful one-row local read emitted a 512-byte snapshot of the native
`DataQueryResultRow*` output structure. The sanitized first-pass dump is stored
in `getnextrow-dataqueryresultrow-memory-latest.json`; the artifact hash is
`2c2cb06988187c1bd7793a52a71f33599542a69d5e83885c583de8bf3df5d43b`.

Confirmed basic row-memory offsets for this full-history sample:

- offset `0x00`: `uint32` tag key `238`
- offset `0x28`: FILETIME UTC start timestamp
  `2026-05-01T14:26:51.1956318Z`
- offset `0x30`: `uint32` quality `133`
- offset `0x34`: `uint32` quality detail `248`
- offset `0x38`: `uint32` OPC quality `192`
- offset `0x80`: `double` percent good `100`

The managed `HistoryQueryResult` reflection snapshot from the same run maps
these fields to tag name `OtOpcUaParityTest_001.Counter`, value `0`, quality
`133`, OPC quality `192`, quality detail `248`, and percent good `100`.

For `TimeWeightedAverage`, `GetNextRow` emits a different row-memory layout for
time bounds. The sanitized summary is in
`getnextrow-timeweightedaverage-memory-latest.json`.

Confirmed aggregate row offsets from the two returned rows:

- offset `0x00`: `uint32` tag key `238`
- offset `0x28`: managed `EndDateTime`
- offset `0x150`: managed `StartDateTime`
- offset `0x30`: `uint32` quality
- offset `0x34`: `uint32` quality detail
- offset `0x38`: `uint32` OPC quality
- offset `0x80`: `double` percent good

The third logged row snapshot duplicated the second row after the managed
enumerator reached native result code `30` (`No more data`), so row-result
instrumentation should correlate captures with the managed `MoveNext` return
status before treating every logged struct as a logical row.

`Interpolated` row memory follows the same time-bound layout in the captured
fixture. The sanitized summary is in
`getnextrow-interpolated-memory-latest.json`.

- offset `0x00`: `uint32` tag key `238`
- offset `0x28`: managed `EndDateTime`
- offset `0x150`: managed `StartDateTime`
- offset `0x30`: `uint32` quality `0`
- offset `0x34`: `uint32` quality detail `248`
- offset `0x38`: `uint32` OPC quality `192`
- offset `0x80`: `double` percent good `100`

The second logged interpolated row snapshot duplicated the first after
`No more data`, matching the aggregate instrumentation behavior.

Integrated-auth native harness evidence (`tools\AVEVA.Historian.NativeTraceHarness`,
latest JSON artifact
`docs\reverse-engineering\native-trace-harness-integrated-read-latest.json`)
confirms these runtime state transitions for
`OtOpcUaParityTest_001.Counter`:

- `HistorianAccess.OpenConnection` succeeds and sets
  `clientHandlerArray[0] = 1` for the process connection slot.
- `HistoryQuery` starts with `queryHandle = 0`, `retrievalMode = Cyclic`,
  `dataVersion = Original`, and no result object.
- `HistoryQueryArgs` for the read uses `RetrievalMode = Full`,
  `DataVersion = Latest`, `BatchSize = 1`, `QualityRule = Extended`,
  `TimeStampRule = End`, `InterpolationType = None`, `Filter = NoFilter`,
  `ValueSelector = Auto`, and `AggregationType = Total`.
- `HistoryQuery.StartQuery` succeeds, normalizes `dataSourceId` from `null` to
  empty string, allocates a `HistoryQueryResult`, and assigns
  `queryHandle = 1`.
- First `MoveNext` returns one row with tag key `238`, value `0`,
  quality `133`, OPC quality `192`, quality detail `248`, and
  percent good `100`.

Later local runs show a distinction between local direct history reads and the
WCF history path:

- `--direct-connection` succeeds for Galaxy-discovered historized tags such as
  `TestMachine_001.TestHistoryValue`, returning one row with value `0`, quality
  `133`, OPC quality `192`, and quality detail `248`.
- non-direct local history reads currently open and connect successfully but
  throw `SEHException` inside native `DataQueryResponse.Load` during
  `HistoryQuery.StartQuery`; the hardened harness now reports this as
  `StartQueryException` instead of crashing.
- event queries still succeed over the local non-direct path, so the Historian
  service is reachable and the failure is specific to data query response
  handling on the local WCF history path.

The harness accepts `--retrieval-mode`, `--start-utc`, `--end-utc`, and
`--resolution-ticks` so scenarios can be repeated with fixed UTC windows. Latest
native wrapper evidence artifacts:

- `native-trace-harness-full-latest.json`: `Full`, one raw row.
- `native-trace-harness-cyclic-latest.json`: `Cyclic`, 60-second resolution,
  two rows.
- `native-trace-harness-interpolated-latest.json`: `Interpolated`, 60-second
  resolution, one row.
- `native-trace-harness-timeweightedaverage-latest.json`:
  `TimeWeightedAverage`, 60-second resolution, two rows.

`HistoryQueryResult` allocates a native `DataQueryResultRow` of 544 bytes.
Confirmed offsets used by the managed wrapper:

- `0`: tag key (`uint`)
- `4`: data type discriminator (`int`)
- `8`: tag name (`std::wstring`)
- `40`: end timestamp (`FILETIME`)
- `48`: quality (`ushort` read through `int`)
- `52`: quality detail (`uint`)
- `56`: OPC quality (`ushort` read through `int`)
- `72`: string value (`std::wstring`)
- `104`: numeric value (`double`)
- `128`: percent good (`double`)
- `336`: start timestamp (`FILETIME`)
- `400`: interpolation/timestamp/quality packed flags (`ushort`)
- `416`: source tag (`std::wstring`)
- `448`: source server (`std::wstring`)
- `488`: actual resolution in FILETIME ticks

## Enum Values Mirrored Into The .NET 10 Scaffold

`HistorianRetrievalMode`:

- `Cyclic = 0`
- `Delta = 1`
- `Full = 2`
- `Interpolated = 3`
- `BestFit = 4`
- `TimeWeightedAverage = 5`
- `MinimumWithTime = 6`
- `MaximumWithTime = 7`
- `Integral = 8`
- `Slope = 9`
- `Counter = 10`
- `ValueState = 11`
- `RoundTrip = 12`
- `StartBound = 13`
- `EndBound = 14`

Other confirmed enums:

- `HistorianInterpolationType`: `StairStep = 0`, `Linear = 1`,
  `SystemDefault = 254`, `None = 255`
- `HistorianTimestampRule`: `Start = 0`, `End = 1`, `None = 2`
- `HistorianQualityRule`: `Extended = 0`, `Good = 1`, `None = 2`,
  `Optimistic = 3`
- `HistorianValueSelector`: `Auto = 1`, `First = 2`, `Last = 3`,
  `Integral = 4`, `StdDev = 5`, `Minimum = 6`, `Maximum = 7`,
  `Average = 8`
- `HistorianAggregationType`: `Minimum = 0`, `Maximum = 1`, `Average = 2`,
  `Total = 3`, `Percent = 4`, `MinContained = 5`, `MaxContained = 6`,
  `TotalContained = 7`, `AverageContained = 8`, `PercentContained = 9`

## Retrieval Metadata Contract

Decompiled WCF retrieval contract signatures in `aahClientManaged.dll` match
the .NET 10 scaffold for the scalar and byte-buffer metadata calls:

- `GetTagTypeFromName(uint clientHandle, string tagName, out uint tagType)`
- `IsOriginalAllowed(uint clientHandle, out bool isAllowed)`
- `IsManualTag(uint clientHandle, string tagName, out bool isManual)`
- `GetTagInfoFromName(uint clientHandle, string tagName,
  out uint tagMetadataByteCnt, out byte[] tagMetadata)`
- `GetTagInfosFromId(uint handle, uint tagIdsSize, byte[] tagIds,
  ref uint sequence, out uint tagInfosSize, out byte[] tagInfos)`
- `GetTagInfosFromName(uint handle, uint tagNamesSize, byte[] tagNames,
  ref uint sequence, out uint tagInfosSize, out byte[] tagInfos)`

Remote managed evidence against `10.100.0.48:32568` confirms the integrated
session handle works for scalar retrieval calls. For
`OtOpcUaParityTest_001.Counter`, `GetTagTypeFromName` returns type `1`,
`IsManualTag` returns `false`, and `GetTagInfoFromName` returns `238` with no
metadata bytes. `GetTgByNm` and `GetTg` buffer probes currently return the same
`238` and no output bytes for all tried encodings. That keeps exact metadata
buffer construction unresolved.

`ArchestrA.TagQuery.StartQuery` is a separate tag browse/query path. It calls
`HistorianClient.StartTagQuery` with a UTF-16 tag-filter pointer, an output
query handle, an output tag count, and `SError*`. The WCF continuation in
`CRetrievalConnectionWCF.StartTagQuery` serializes a request buffer before
calling `IRetrievalServiceContract3.StartTagQuery(handle, byte[], out byte[],
out byte[])`.

IL instrumentation of `CRetrievalConnectionWCF.StartTagQuery` token `06004A15`
captured the exact WCF request buffer for deterministic OData filter
`TagName eq 'OtOpcUaParityTest_001.Counter'`. The request is 92 bytes with
SHA-256 `af1dbcdd3eb0ad91a18882c22252aa74aff82998e96a39b63415ab4792a962ac`;
sanitized field notes are stored in `starttagquery-request-buffer-latest.json`.

Confirmed tag-query request fields:

- offset `0x00`: `ushort` marker `26449` (`0x6751`)
- offset `0x02`: `ushort` version `1`
- offset `0x04`: `uint32` filter character length
- offset `0x08`: UTF-16LE filter text without a trailing null

The same instrumentation also captures the successful WCF response byte array.
For the current local run the response is 8 bytes with SHA-256
`db49223a2cf9616171322e5325816a7a579582ebdce91c2f89df8df7aa8aac01`.

Confirmed start-tag-query response fields:

- offset `0x00`: `uint32` query handle
- offset `0x04`: `uint32` tag count

The local native tag query succeeds with that OData filter and returns
`TagCount = 1`, tag name
`OtOpcUaParityTest_001.Counter`, and metadata summary `TagKey = 238`,
`TagDataType = 4`, `TagStorageType = 3`, `EngineeringUnit = None`. Plain tag
name filters reach the server but fail with native failure code `1`, while
wildcard filters fail as invalid OData/WWFilter syntax. Response buffers and
the native `CTagMetadata` vector layout for `GetTagInfo` still need byte-level
instrumentation.

`TagQuery.GetTagNames` calls `HistorianClient.GetTagNames`, while
`TagQuery.GetTagInfo` calls `HistorianClient.GetTagInfos` and then
`HistorianTag.LoadFromTagMetadata` for each 224-byte `CTagMetadata` entry in
the returned native vector. The separate wildcard-style browse path is not
`TagQuery`; method inventory shows it as
`HistorianClient.StartLikeTagNameSearch` / `GetLikeTagnames` with WCF
continuations `CRetrievalConnectionWCF.StartLikeTagNameSearch` /
`GetLikeTagnames`.

IL instrumentation of `aahClientCommon.CClientCommon.GetTagInfos` token
`06002EC9` captured the pre-deserialization response stream used by
`TagQuery.GetTagInfo`. For the deterministic tag
`OtOpcUaParityTest_001.Counter`, the stream is 106 bytes with SHA-256
`77b2bf720d8888f08a1499a8162e706c2cef567a1f6d74d7e92efe0cd3e3e34b`;
sanitized details are stored in `tagquery-gettaginfo-response-latest.json`.

Confirmed `GetTagInfo` response stream fields for the current fixture:

- offset `0x0000`: `uint32` tag count
- offset `0x0004`: 4-byte native data-type descriptor; `CTagUtil.GetDataValueType`
  maps this fixture to public `HistorianDataType = 4`
- offset `0x0008`: type GUID
- offset `0x0018`: `uint32` tag key
- offset `0x001C`: compact ASCII tag name: marker `0x09`, `uint16` byte length,
  then bytes
- offset `0x003C`: compact ASCII metadata provider, observed as `MDAS`
- offset `0x0043`: native tag class byte
- offset `0x0044`: storage type byte
- offset `0x0045`: deadband type byte
- offset `0x0046`: interpolation type byte

The same instrumentation captured the native `std::vector<CTagMetadata>` after
`Load<CTagMetadata,SByteStream<SCrtMemFile>>`; the vector has 224-byte elements.
`HistorianTag.LoadFromTagMetadata` reads tag key from vector offset `0x0030`,
tag name from `0x0038`, description from `0x0058`, storage type from `0x00C1`,
deadband type from `0x00C2`, and inactive status from vector offset `0x0034`.

The wildcard browse path is confirmed separately through managed WCF calls to
`Retr.StartLikeTagNameSearch` and `Retr.GetLikeTagnames`. With integrated
Windows `Open2` and filter `OtOpcUaParityTest%`, `StartLikeTagNameSearch`
returns `0`, and `GetLikeTagnames` returns one 66-byte buffer with SHA-256
`2d450a55f392aed0026e9a957fefa3b116aab6ec81912c5d824c6b9a1ff5a4a1`.
The buffer layout for the one-tag fixture is `uint32 count`, then for each tag
`uint32 UTF-16 character length` and UTF-16LE tag name bytes. Sanitized details
are stored in `like-tag-browse-response-latest.json`.

## Event Query Contract

`EventQuery.StartQuery` calls native `HistorianClient.StartEventQuery`.

Confirmed arguments include:

- Start/end timestamps converted to FILETIME.
- Event count.
- Skip count.
- Event order as `ushort`.
- Filter block pointer.
- Time zone string: `UTC`.
- Output query handle.

The decompiled wrapper passes event query type value `1` into
`HistorianClient.StartEventQuery` for ordinary event reads. This is distinct
from the WCF retrieval `queryRequestType`: `Query.StartEventQuery` stores
`ushort 3` immediately before calling
`CRetrievalConnectionWCF.StartEventQuery`, so the WCF operation must use
`queryRequestType = 3`.

`EventQueryRequest.Save<SByteStream<SCrtMemFile>>` now has a byte-level field
order from `ildasm`:

- constant request version `ushort 5`
- start and end FILETIME values from the embedded `TIMERANGE`
- `eventCount` as `uint32`
- `skipCount` as `uint32`
- `eventOrder` as `uint16`
- `queryType` as `uint16`
- `EventQueryFilters.Save`
- result buffer size as `uint32`; native construction passes `0x10000`
- timezone `std::wstring`; ordinary reads pass `UTC`
- `CMetadataNamespace.Save`
- `EventQueryFilters.SaveSelect`

`EventQueryFilters.Save` writes `ushort 0`, a `uint32` filter count, each
filter, a continuation flag byte, and only writes continuation FILETIME/GUID
when that flag is non-zero. Empty event reads therefore serialize the filter
block as `00 00 00 00 00 00 00`. `SaveSelect` writes a `uint32` selected
property count followed by compressed strings; default event reads write count
zero.

`EventQuery` allocates `EventQueryFilters` as a 72-byte native object. It rejects
filters on `EventTime`, limits filter count to 500, and converts filter property
names and values to UTF-16 strings.

`EventQuery.MoveNext` calls `HistorianClient.GetNextRow<EventQueryResultRow>` and
then `HistorianEvent.CreateHistorianEvent`.

Integrated-auth native harness event evidence
(`native-trace-harness-event-latest.json`) confirms:

- Opening with `HistorianConnectionType = Event` succeeds and reaches
  `ConnectedToServer = true`.
- `HistorianAccessUtil.SetConnectionMode(Event, integratedSecurity: true)`
  produces Open2 connection mode `0x501` (`1281`). The process read-only
  integrated mode is `0x402` (`1026`).
- Native `HistorianAccess.OpenConnection` creates the event connection at
  `ConnectionIndex.Event` and then calls `CreateDefaultEventTag`.
  `CreateDefaultEventTag` builds a synthetic `HistorianTag` named
  `CM_EVENT`, sets description `AnE Event`, engineering unit `NONE`, data type
  `10`, and calls `AddTagInternal`; the native
  access snapshot then has `clientHandlerArray = [0, 1]` and
  `eventTagHandle = 10000000`.
- `EventQueryArgs` uses UTC `StartDateTime` / `EndDateTime`, `QueryType =
  Events`, `EventOrder = Ascending`, and `EventCount` from `--max-rows`.
- `EventQuery.StartQuery` succeeds with native `Success`.
- A seven-day local-dev window returned three sanitized event rows; raw event
  IDs and opaque event source details are not written by the harness.
- A managed WCF `StartEventQuery` probe using this reconstructed version-5
  empty-filter request and `queryRequestType = 3` reaches
  `/Retr.StartEventQuery` but returns `false` with no native error buffer. This
  remains true for process-mode Open2 (`1026`) and event-mode Open2 (`1281`),
  and for the returned Open2 handle, the native `ClientApp` event slot handle
  `1`, and the observed event tag handle `10000000`.
- `CRetrievalConnectionWCF.StartEventQuery` has a server-interface-version
  branch: interface versions `<= 2` call `/Retr.StartQuery2`; newer versions
  call `/Retr.StartEventQuery`. The managed probe now tries both operations
  with the same reconstructed request. On the local 2020 server, both operation
  paths still return `false` with no native error buffer, so the mismatch is
  likely connection/session state rather than this dispatch branch.
- Because native event open performs `CreateDefaultEventTag` before event query
  start, the next gap is likely the `HistorianClient.AddHistorianTag` /
  `AddTagInternal` setup for `CM_EVENT`, not the basic event request field
  order or WCF contract signature.
- Follow-up decompile of `aahClientCommon.CClient.RegisterTag` shows this part
  is client-local: it calls `RegisterRealtimeTag`, inserts the tag id into
  local sets, marks the cached `CTagInfo` as registered, and flips
  synchronization flags. There is still a server-visible registration path
  elsewhere (`IHistoryServiceContract.RTag` / storage `RTag`), but
  `CreateDefaultEventTag` does not directly prove its byte payload.
- The server-visible `RTag2` WCF edge is now partially mapped. Decompiled
  `CHistoryConnectionWCF.RegisterTags` converts a native `_GUID Handle` to a
  string, calls `IHistoryServiceContract2.RegisterTags2` (`RTag2`), and passes a
  byte buffer serialized as `uint32 count` followed by `count` 16-byte `_GUID`
  values. The local managed probe `wcf-register-event-tag` tried empty,
  zero-GUID, and event-handle-shaped GUID vectors with Open2-derived handle
  candidates. All failed before event query start could succeed: first-16
  handle candidates returned native error `51`, while the bytes 4-19 .NET GUID
  candidate reached the server but returned native error `1`. This makes simple
  `RTag2` replay unlikely to be the missing event setup by itself; the richer
  `AddHistorianTag`/`CTagMetadata` path remains the lead.
- `HistorianClient.ConvertEventTagToTagMetadata` now has a concrete event-tag
  metadata map from IL/native data:
  - synthetic tag name: `CM_EVENT`
  - description from `CreateDefaultEventTag`: `AnE Event`
  - event tag id: `353b8145-5df0-4d46-a253-871aef49b321`
  - common ArchestrA event type id:
    `5f59ae42-3bb6-4760-91a5-ab0be01f2f27`
  - ArchestrA event type id:
    `f3ef1a17-fd27-4c3c-84cf-bac55c0e47de`
  - converted `CDataType` byte: `5`
  - storage type passed to `CTagMetadata.Initialize`: `2`
- `CTagMetadata.Save<SByteStream<SCrtMemFile>>` writes a one-byte serialization
  version, a two-byte optional-field mask, the `CDataType` byte, the 16-byte tag
  id, and compressed strings for present string fields. Short ASCII UTF-16
  strings use the compact form `09 <length> 00 <ASCII bytes>`, so `CM_EVENT`
  serializes as `09 08 00 43 4d 5f 45 56 45 4e 54`.
- A direct managed replay of this approximate event metadata through
  `IHistoryServiceContract.AddTags` (`AddT`) is negative evidence:
  `wcf-add-event-tag` opened `/Hist-Integrated`, tried both a raw
  `CTagMetadata` payload and a vector-count-prefixed payload, and both returned
  `AddReturnCode = 4` with no output buffer. The subsequent
  `StartEventQuery` still returned `false`. This means the missing native event
  setup is not reproduced by the current `AddT` approximation.
- A fake WCF capture server on an alternate port exposed `/Hist`,
  `/Hist-Integrated`, and `/Retr`, but the native event harness still reached
  the real local Historian and the fake server saw no calls. The
  `HistorianConnectionArgs.TcpPort` field does not redirect this native WCF
  path sufficiently for server-side capture.
- The expanded Frida event add-tag pass hooked the candidate MethodDef RVAs
  before `OpenConnection` and the native event query still succeeded, but no
  enter/leave callbacks fired. MethodDef RVAs remain insufficient hook targets
  for this mixed-mode wrapper; use CLR method rewriting/profiling or lower-level
  transport/API capture next.
- IL instrumentation of `<Module>.Query.StartEventQuery` token `0600574A`
  now captures the exact native `EventQueryRequest` buffer immediately after
  `EventQueryRequest.Save<SByteStream<SCrtMemFile>>` and `endstream`. A local
  seven-day event query succeeded and returned three rows while logging a
  65-byte request. SHA-256 is
  `6b955b02087047a3199a8c74f3eee85c3b49aaa29b05de12eff2dd536f2da0d5`, and
  the sanitized dump is stored in `starteventquery-request-buffer-latest.json`.
  The managed event query serializer now has a byte-for-byte test against this
  native fixture.
- A matching IL rewrite of
  `<Module>.HistorianClient.GetNextRow<class EventQueryResultRow>` token
  `06005965` captures native `EventQueryResultRow*` memory immediately after
  `Query.GetNextEventQueryResultRow<class EventQueryResultRow>` returns. The
  successful local seven-day event query emitted three 2048-byte raw snapshots
  under ignored `artifacts\reverse-engineering`; the sanitized summary is
  stored in `getnexteventrow-memory-latest.json`.

Confirmed first-pass event row evidence:

- offset `0x18`: managed `HistorianEvent.EventTime` as FILETIME UTC for all
  three rows
- `ReceivedTime` was not present as a direct FILETIME value in the captured
  2048-byte native struct snapshot
- managed event type was `User.Write.Secured` for all three rows, but the raw
  struct contains pointer-like fields and no safely decoded inline event-type
  string yet

This keeps event result parsing unresolved, but it proves the IL rewrite path
can capture both event request bytes and native event row memory without adding
production dependencies.

## Tag Query Session Evidence

`CRetrievalConnectionWCF.StartTagQuery` does not carry the tag filter in the
latest successful WCF call. Combined IL instrumentation of native
`OpenConnection` plus tag-query start captured a successful local tag metadata
query where the WCF `StartTagQuery` request was only:

- marker/version bytes: `51 67 01 00`
- SHA-256:
  `17956e4fbe53d5edc0f9170203b013432e4afcc0591c795a10522a98d9fce926`
- response bytes: `0C 00 00 00 01 00 00 00`
- parsed response: query handle `12`, tag count `1`

The tag filter `TagName eq 'OtOpcUaParityTest_001.Counter'` was already
processed before this WCF request. The native WCF handle string is an uppercase
GUID generated for the native retrieval session; it is not the numeric Open2
handle, the Open2 storage session id, the first 16 Open2 bytes, or the full
Open2 output. Managed replay of both the older 92-byte filter-shaped candidate
and the latest 4-byte header-only request with all Open2-derived handle
candidates returned native errors `51` or `1`.

Conclusion: public metadata should not be wired through `StartTagQuery`.
`BrowseTagNamesAsync` can stay on the proven `StartLikeTagNameSearch` /
`GetLikeTagnames` path. `GetTagMetadataAsync` now uses the direct
`GetTagInfoFromName` WCF path, which returned a 98-byte metadata record for the
deterministic parity tag. More guessed `StartTagQuery` envelopes are not the
useful next target; the missing evidence is the native session registration or
the earlier metadata-layer call that binds the filter to the retrieval GUID.

## Immediate Unknowns

These still require native ABI inspection and packet captures:

- Session handshake frame.
- Authentication frame.
- Query frame envelope and length/correlation fields.
- Native `StartDataQuery` message type identifier.
- Native `StartEventQuery` message type identifier.
- `GetNextRow` request/response frame shape.
- Error frame layout.

See `native-exports.md` for the first PE export-table pass over
`aahClient.dll`.