histsdk/docs/reverse-engineering/wcf-contract-evidence.md

# WCF Contract Evidence

## Local run evidence

- `current\aahClient.dll` export inventory ran successfully. SHA256:
  `77a778988e2d8f2d0e88113f8c8b0788a0ef34fa5134938a353976778144dc83`.
- `ArchestrA.HistorianAccess.OpenConnection` succeeded against `localhost:32568`
  using `HistorianConnectionArgs` with `ConnectionType=Process` and `ReadOnly=true`.
- Holding that native connection open produced established TCP sessions from the
  native PowerShell process to `127.0.0.1:32568`; the server-side listener was
  owned by `SMSvcHost.exe`, consistent with WCF Net.TCP port sharing.
- The managed harness command
  `dotnet run --no-build --project tools\AVEVA.Historian.ReverseEngineering -- wcf-probe localhost 32568`
  successfully called `GetV` through fully managed WCF/MDAS:
  - `net.tcp://localhost:32568/Hist` returned version `11`
  - `net.tcp://localhost:32568/Retr` returned version `4`
  - `net.tcp://localhost:32568/Stat` returned version `0`
  - `net.tcp://localhost:32568/Trx` returned version `2`
  - `net.tcp://localhost:32568/Storage` did not listen on this local install
  - `net.tcp://localhost:32568/HistCert` and `/Hist-Integrated` reset when
    called with the plain managed `GetV` contract, while prefixed variants such
    as `/HCAP/HistCert` returned `EndpointNotFound`
  Sanitized output is stored in `docs\reverse-engineering\wcf-probe-localhost.json`.
- `netsh trace` and `pktmon` produced ETL files under
  `%TEMP%\histsdk-captures`, but their converted PCAPNG files contained zero
  packets. Built-in Windows packet capture is not sufficient for loopback
  evidence on this machine.
- A dedicated managed certificate-binding probe now reaches `HistCert.GetV`
  through MDAS over WCF Net.TCP transport security:
  - `net.tcp://localhost:32568/HistCert` returned version `11`
  - `net.tcp://10.100.0.48:32568/HistCert` initially failed endpoint identity
    validation because the server certificate presented DNS identity
    `localhost`
  - the same remote endpoint returned version `11` when the client supplied
    endpoint DNS identity `localhost`
  Sanitized outputs are stored in
  `docs\reverse-engineering\wcf-cert-probe-localhost-latest.json`,
  `docs\reverse-engineering\wcf-cert-probe-remote-latest.json`, and
  `docs\reverse-engineering\wcf-cert-probe-remote-localhost-identity-latest.json`.
- The same remote server also accepts the plain managed WCF/MDAS probe on the
  expected non-security-specific service paths:
  - `net.tcp://10.100.0.48:32568/Hist` returned version `11`
  - `net.tcp://10.100.0.48:32568/Retr` returned version `4`
  - `net.tcp://10.100.0.48:32568/Stat` returned version `0`
  - `net.tcp://10.100.0.48:32568/Trx` returned version `2`
  Sanitized output is stored in
  `docs\reverse-engineering\wcf-probe-remote-latest.json`.
- Managed remote `Open2` evidence matches localhost: integrated Windows auth
  succeeds on `net.tcp://10.100.0.48:32568/Hist-Integrated`, while the same
  Windows transport binding fails on plain `/Hist` before dispatch. The
  successful returned handle is accepted by `Retr.IsOriginalAllowed`. Session
  output bytes and transient handle values are redacted in
  `docs\reverse-engineering\wcf-open2-remote-latest.json`.
- Managed remote `StartQuery2` evidence is still negative but sharper: all 22
  reconstructed `DataQueryRequest` variants successfully open the integrated
  session and pass `Retr.IsOriginalAllowed`, then `StartQuery2` returns `false`
  with zero response and error sizes. The legacy `StartQuery` call returns code
  `238` for each request and also returns zero response size/no response buffer.
  Sanitized request hashes are stored in
  `docs\reverse-engineering\wcf-start-query-remote-latest.json`.
- A later bounded managed replay of the first byte-matched full-history
  candidate used the same integrated open and `Retr.IsOriginalAllowed` path;
  `StartQuery2` still returned `false` with zero response/error sizes, while
  legacy `StartQuery` faulted with a server null-reference. This keeps
  `Open2` as useful connection evidence, but not as a viable replacement for
  the native `OpenConnection3` session state required by query reads.
- Managed wildcard tag browse remains positive evidence for an `Open2`-backed
  operation: `Retr.StartLikeTagNameSearch` returned `0`, and one
  `GetLikeTagnames` batch returned the deterministic 66-byte single-tag buffer
  with SHA-256
  `2d450a55f392aed0026e9a957fefa3b116aab6ec81912c5d824c6b9a1ff5a4a1`.
- Managed remote scalar tag calls also accept the integrated session handle:
  `Retr.GetTagTypeFromName` returns code `0` and tag type `1` for
  `OtOpcUaParityTest_001.Counter`; `Retr.IsManualTag` returns code `0` and
  `false`; legacy `Retr.GetTagInfoFromName` returns `238` with zero metadata
  bytes. Five `GetTgByNm` tag-name buffer variants and five `GetTg` tag-id
  buffer variants all return `238`, sequence `0`, and zero output bytes. This
  suggests the calls are reaching server logic but the metadata-returning
  contract shape or request buffer is still incomplete. Sanitized output is
  stored in
  `docs\reverse-engineering\wcf-tag-info-remote-latest.json`.

## Decompiled service contracts

`current\aahClientManaged.dll` contains WCF contracts with namespace `aa`:

- `HistoryServiceContract.IHistoryServiceContract`
  - `[ServiceContract(Name = "Hist", Namespace = "aa")]`
  - `GetInterfaceVersion` as operation `GetV`
  - `OpenConnection` as operation `Open`
  - `CloseConnection` as operation `Close`
  - `ValidateClient` as operation `VldC`
  - `UpdateClientStatus` as operation `UpdC`
  - `AddTags` as `AddT`, `RegisterTags` as `RTag`
  - `AddStreamValues` as `AddS`, `SetClientTimeOut` as `SetT`
- `HistoryServiceContract.IHistoryServiceContract2`
  - `[ServiceContract(Name = "Hist", Namespace = "aa")]`
  - byte-buffer session open uses `OpenConnection2` as operation `Open2`
  - extended client status uses `UpdC2` / `UpdC3`
  - extended write and maintenance calls include `EnsT`, `DelT`, `AddS2`,
    `ExKey`, `ValCl`, and `GetI`
- `RetrievalServiceContract.IRetrievalServiceContract`
  - `[ServiceContract(Name = "Retr", Namespace = "aa")]`
  - `StartQuery`, `GetNextQueryResultBuffer`, `EndQuery` use default
    operation names
  - tag type/name helpers and tag info calls use default operation names
- `RetrievalServiceContract.IRetrievalServiceContract2/3/4`
  - extended bool/error-buffer variants
  - SQL/recordset byte stream calls
  - tag query calls `QTB`, `QTG`, `QTE`
  - event query calls use default operation names
  - extended property calls include `GetTgByNm2` and `GetTepByNm`
- `StorageServiceContract.IStorageServiceContract`
  - `[ServiceContract(Name = "Storage", Namespace = "aa")]`
  - storage/session, metadata, streamed-value, block, snapshot, and delete-tag
    calls
- `StatusServiceContract.IStatusServiceContract`
  - `[ServiceContract(Name = "Stat", Namespace = "aa")]`
  - `GetInterfaceVersion` as `GetV`
  - server time, timezone, DB case sensitivity, and logging use default
    operation names
- `StatusServiceContract.IStatusServiceContract2`
  - extended status operations include `GetSystemParameter`, `GetTimeZoneNames`,
    license checks, historian info, and process/ping helpers
  - ping and historian-info helpers use aliases `PNGS`, `PNGP`, and `GETHI`
- `TransactionServiceContract.ITransactionServiceContract`
  - `[ServiceContract(Name = "Trx", Namespace = "aa")]`
  - snapshot forwarding and non-streamed value transactions

`aahMDASEncoder.ClientMessageEncoder` wraps an inner WCF encoder and exposes
media/content type `application/x-mdas`. This means the first managed driver
transport target should be WCF Net.TCP plus the MDAS content-type encoder, not
the earlier speculative raw-frame layer.

## Current unknowns

- Endpoint URI paths `net.tcp://{host}:32568/Hist`, `/Retr`, `/Stat`, and
  `/Trx` are confirmed for `GetV` calls on the local 2020 install.
- Relay and local WCF probe evidence also identify security-specific history
  endpoints `/HistCert` and `/Hist-Integrated`. `/HistCert` is confirmed as a
  `Hist` contract endpoint when called with MDAS over TLS transport security;
  `/Hist-Integrated` remains the Windows negotiate endpoint for integrated
  session open.
- Managed `Open2` evidence confirms `/Hist-Integrated` is the correct endpoint
  for integrated Windows auth. The plain `/Hist` endpoint rejects the Windows
  transport-security upgrade before dispatching the operation.
- The storage contract is confirmed statically, but `/Storage` was not a
  listening endpoint in the local probe; storage may be routed through
  session-specific storage/shard endpoints.
- `Hist.OpenConnection` reaches server logic, but the native password/session
  packet encoding is not decoded yet. See `wcf-open-localhost.md`.
- `Hist.Open2` is confirmed reachable with a managed version-1 byte buffer.
  Empty credentials return custom native error `171` (`AuthenticationFailed`),
  and the harness decodes observed five-byte error buffers as type plus
  little-endian error code. This confirms framing has progressed past
  packet-version rejection. See `wcf-open2-localhost.md`.
- `Stat` is reachable, but `CStatusConnectionWCF.GetServerTime` is a no-op stub
  in the decompiled native WCF path and handle-dependent status calls fail with
  handle `0`. See `wcf-status-localhost.md`.
- Query request and response byte-buffer layouts are still proprietary payloads
  inside WCF operations such as `StartQuery` and `GetNextQueryResultBuffer`.
- Write payload layouts decoded for the two supported ops:
  - `Hist.EnsT2(analog)` 144-byte `CTagMetadata` `InBuff` payload —
    leading `0x4E` marker, fixed 10-byte signature, 1-byte CDataType
    discriminator (`0x01` Float / `0x21` Double / `0x09` UInt2 / `0x11`
    UInt4 / `0x29` Int2 / `0x31` Int4), 16 zero placeholder bytes,
    compact-ASCII tag name, 16 bytes of `0xFF`, compact-ASCII description,
    compact-ASCII `MDAS`, 7-byte flag block, uint32 storage rate,
    int64 FILETIME, scaling block (compact `1A 03` for default
    0/100/0/100 ranges OR `1F 00` + 4 doubles MinEU/MaxEU/MinRaw/MaxRaw
    for explicit), compact-ASCII engineering unit, uint32 `0x2710`
    constant, double 1.0 (IntegralDivisor), 2-byte trailer `FE xx`
    where `xx` is the ApplyScaling flag (`0x00` false / `0x01` true).
    Live-verified: with `0x01` the server persists distinct
    MinRaw/MaxRaw and sets `AnalogTag.Scaling=1`; with `0x00` it
    mirrors MinRaw to MinEU. Captured fixtures live at
    `artifacts/reverse-engineering/instrumented-wcf-writemessage-writes/`
    (default ranges) and
    `artifacts/reverse-engineering/apply-scaling-experiment/` (both
    ApplyScaling values for the same input ranges). Connection mode is
    `0x401` (Process | Write | IntegratedSecurity) — the read-mode
    `0x402` makes the server return err 132 silently.
  - `Hist.DelT` `tagNames` byte buffer — `ushort 0x6751`, `ushort 1`,
    `uint32 tagCount`, then per tag `uint32 charCount + UTF-16-LE chars`.
    Decoded via wire capture against the sandbox tag.
  - `Hist.AddS2` (write samples) is architecturally blocked — server
    runtime cache requires IOServer / Application Server pipeline
    registration, not just a `Tag` row in `Runtime.dbo`. Three
    reproduction attempts (real wwTagKey, fresh session, 8s settle
    wait) confirmed `129 "Tag not found in cache"` is the gate. No
    AddS2 wire bytes leave the client.