R1.2 GetRuntimeParameter + string-handle wall RESOLVED (handle-format bug)

Execute HCAL roadmap R1.2 (GetRuntimeParameterAsync) end-to-end, and in doing so
discover that the "string-handle wall" blocking R1.1/R1.4/R1.5/R1.6 was a handle
FORMAT bug, not a missing native session/filter registration.

R1.2 (shipped, live-verified):
- Captured native GetRuntimeParameter -> WCF op aa/Stat/GETRP (string-handle op,
  GETHI's shape), via scripts/Capture-RuntimeParam.ps1 + instrument-wcf-{write,read}message.
- HistorianRuntimeParameterProtocol serializes pRequestBuff (54 67 01 00 + uint
  nameCount + per-name uint charCount + UTF-16) and parses pResponseBuff (version +
  uint resultCount + CRetVariant 0x43 VT_BSTR + uint16 len + uint16 charCount + UTF-16).
- IStatusServiceContract2.GetRuntimeParameter (GETRP) op; HistorianWcfStatusClient
  passes the Open2 storage-session GUID as the string handle, UPPERCASE.
- Public HistorianClient.GetRuntimeParameterAsync(name) via the dialect.
- Golden WcfRuntimeParameterProtocolTests + gated live test; returns HistorianVersion.

String-handle wall RESOLVED (proven, public APIs deferred):
- The Open2 storage GUID works as the string handle when sent UPPERCASE
  (ToString("D").ToUpperInvariant()); earlier "blocked" probes used lowercase.
- Live-probed GETHI (R1.4) -> returns data; ExeC (R1.1) -> Retr.GetV prime -> ExeC ->
  GetR returns a BinaryFormatter-serialized .NET DataTable. Gated
  StringHandleProbeDiagnosticTests + scripts/Capture-ExecSql.ps1 + exec-sql harness scenario.
- Docs flipped: wcf-string-handle-wall.md RESOLVED banner; roadmap R1.1/R1.4 reachable,
  R1.5/R1.6 likely; wcf-status-localhost.md GETRP section.
- R1.1/R1.4 public APIs NOT shipped: ExeC needs a GetR paging loop + a BinaryFormatter-
  stream parser (BinaryFormatter is removed from .NET 10); GETHI full-info struct needs
  its own capture.

223 unit tests pass; gated live tests green against the local 2020 Historian.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B6mcaT2PjRFKcogzp9UkfC

scripts/Capture-ExecSql.ps1

@@ -0,0 +1,91 @@
+<#
+.SYNOPSIS
+    Captures the native AVEVA client's ExecuteSqlCommand wire traffic (HCAL roadmap R1.1) so the
+    Retr.ExeC + Retr.GetR string-handle SQL surface (op names, handle format, command/option
+    encoding, Retr priming, GetR result byte stream) can be decoded instead of guessed.
+
+.DESCRIPTION
+    Drives the .NET-Framework NativeTraceHarness `exec-sql` scenario against the live Historian
+    with an IL-rewritten copy of aahClientManaged.dll whose ClientMessageEncoder.WriteMessage AND
+    ReadMessage are instrumented to log every MDAS body. Read-only benign query.
+
+.NOTES
+    Artifacts are diagnostic and gitignored. Sanitize before copying into docs/ -- never commit raw
+    capture NDJSON, credentials, hostnames, or customer tag names.
+#>
+[CmdletBinding()]
+param(
+    [string]$ServerName = "localhost",
+    [int]$TcpPort = 32568,
+    [string]$Sql = "SELECT 1 AS ProbeValue",
+    [string]$SqlOption = "ExecuteRecord",
+    [string]$Configuration = "Debug"
+)
+
+$ErrorActionPreference = "Stop"
+$repoRoot = Split-Path -Parent $PSScriptRoot
+Set-Location $repoRoot
+
+$reProj      = Join-Path $repoRoot "tools\AVEVA.Historian.ReverseEngineering\AVEVA.Historian.ReverseEngineering.csproj"
+$harnessProj = Join-Path $repoRoot "tools\AVEVA.Historian.NativeTraceHarness\AVEVA.Historian.NativeTraceHarness.csproj"
+$instrProj   = Join-Path $repoRoot "tools\AVEVA.Historian.ReverseInstrumentation\AVEVA.Historian.ReverseInstrumentation.csproj"
+
+$captureDir  = Join-Path $repoRoot "artifacts\reverse-engineering\instrumented-wcf-exec-sql"
+$currentCopy = Join-Path $captureDir "current-copy"
+$instrDll    = Join-Path $captureDir "aahClientManaged.dll"
+$capturePath = Join-Path $captureDir "exec-sql-capture-latest.ndjson"
+
+Write-Host "== Building tooling ($Configuration) ==" -ForegroundColor Cyan
+dotnet build $reProj      -c $Configuration --nologo -v q | Out-Null
+dotnet build $instrProj   -c $Configuration --nologo -v q | Out-Null
+dotnet build $harnessProj -c $Configuration --nologo -v q | Out-Null
+
+$instrSourceDll = Get-ChildItem -Recurse (Join-Path $repoRoot "tools\AVEVA.Historian.ReverseInstrumentation\bin\$Configuration") `
+    -Filter "AVEVA.Historian.ReverseInstrumentation.dll" | Select-Object -First 1 -ExpandProperty FullName
+if (-not $instrSourceDll) { throw "ReverseInstrumentation.dll not found under bin\$Configuration." }
+
+Write-Host "== Instrumenting WriteMessage + ReadMessage ==" -ForegroundColor Cyan
+New-Item -ItemType Directory -Force -Path $captureDir | Out-Null
+$writeOnly = Join-Path $captureDir "aahClientManaged.write.dll"
+dotnet run --no-build -c $Configuration --project $reProj -- `
+    instrument-wcf-writemessage (Join-Path $repoRoot "current\aahClientManaged.dll") $writeOnly | Out-Null
+dotnet run --no-build -c $Configuration --project $reProj -- `
+    instrument-wcf-readmessage $writeOnly $instrDll | Out-Null
+
+Write-Host "== Staging current-copy ==" -ForegroundColor Cyan
+robocopy (Join-Path $repoRoot "current") $currentCopy /MIR /NJH /NJS /NDL /NP /NC /NS | Out-Null
+Copy-Item -Force $instrDll (Join-Path $currentCopy "aahClientManaged.dll")
+Copy-Item -Force $instrSourceDll (Join-Path $currentCopy "AVEVA.Historian.ReverseInstrumentation.dll")
+
+$harnessDll = Join-Path $currentCopy "aahClientManaged.dll"
+if (Test-Path $capturePath) { Remove-Item -Force $capturePath }
+$env:AVEVA_HISTORIAN_RE_CAPTURE = $capturePath
+
+Write-Host "== Capturing exec-sql ==" -ForegroundColor Green
+$harnessArgs = @(
+    "--scenario", "exec-sql",
+    "--server-name", $ServerName,
+    "--tcp-port", "$TcpPort",
+    "--sql", $Sql,
+    "--sql-option", $SqlOption,
+    "--current-dir", $currentCopy,
+    "--managed-dll-path", $harnessDll
+)
+
+$harnessJson = $null
+try {
+    $prevEap = $ErrorActionPreference
+    $ErrorActionPreference = "Continue"
+    $harnessJson = & dotnet run --no-build -c $Configuration --project $harnessProj -- @harnessArgs 2>&1
+} catch {
+    Write-Host "   (exec-sql raised: $($_.Exception.Message))" -ForegroundColor Yellow
+} finally {
+    $ErrorActionPreference = $prevEap
+}
+
+Remove-Item Env:\AVEVA_HISTORIAN_RE_CAPTURE -ErrorAction SilentlyContinue
+
+$recCount = if (Test-Path $capturePath) { (Get-Content $capturePath | Where-Object { $_.Trim() }).Count } else { 0 }
+Write-Host "`n== Capture summary ==" -ForegroundColor Cyan
+Write-Host "   -> $recCount records -> $capturePath"
+$harnessJson | Select-Object -Last 6

scripts/Capture-RuntimeParam.ps1

@@ -0,0 +1,105 @@
+<#
+.SYNOPSIS
+    Captures the native AVEVA client's GetRuntimeParameter wire traffic (HCAL roadmap R1.2)
+    so the WCF op name, handle type (uint vs the string-handle wall), and the
+    btRequest/btResponse buffer format can be decoded instead of guessed.
+
+.DESCRIPTION
+    Drives the .NET-Framework NativeTraceHarness's `runtime-param` scenario against the live
+    Historian with an IL-rewritten copy of aahClientManaged.dll whose
+    ClientMessageEncoder.WriteMessage AND ReadMessage are instrumented to log every MDAS body
+    (the same pipeline that produced every other proven request/response shape). The harness
+    opens a normal authenticated process connection and calls
+    HistorianAccess.GetRuntimeParameter(List<string> names, out List<object> results, out err).
+
+    Decode with scripts/decode-runtime-param-capture.py: locate the WCF.WriteMessage.Body
+    whose op carries the parameter name(s) -> that is the GetRuntimeParameter request; read
+    off the SOAP action / op name, the leading handle param, and the btRequest layout. The
+    paired WCF.ReadMessage.Body is the btResponse (the CRetVariant value list).
+
+.NOTES
+    Read-only status call; no data is written. Artifacts are diagnostic and gitignored.
+    Sanitize before copying anything into docs/ -- never commit raw capture NDJSON,
+    credentials, hostnames, or customer tag names.
+#>
+[CmdletBinding()]
+param(
+    [string]$ServerName = "localhost",
+    [int]$TcpPort = 32568,
+    # Semicolon-separated runtime parameter names. HistorianVersion is a known-good name
+    # (returns the server version string) so the response decode has a real value.
+    [string]$Names = "HistorianVersion",
+    [string]$Configuration = "Debug"
+)
+
+$ErrorActionPreference = "Stop"
+$repoRoot = Split-Path -Parent $PSScriptRoot
+Set-Location $repoRoot
+
+$reProj      = Join-Path $repoRoot "tools\AVEVA.Historian.ReverseEngineering\AVEVA.Historian.ReverseEngineering.csproj"
+$harnessProj = Join-Path $repoRoot "tools\AVEVA.Historian.NativeTraceHarness\AVEVA.Historian.NativeTraceHarness.csproj"
+$instrProj   = Join-Path $repoRoot "tools\AVEVA.Historian.ReverseInstrumentation\AVEVA.Historian.ReverseInstrumentation.csproj"
+
+$captureDir  = Join-Path $repoRoot "artifacts\reverse-engineering\instrumented-wcf-runtime-param"
+$currentCopy = Join-Path $captureDir "current-copy"
+$instrDll    = Join-Path $captureDir "aahClientManaged.dll"
+$capturePath = Join-Path $captureDir "runtime-param-capture-latest.ndjson"
+
+Write-Host "== Building tooling ($Configuration) ==" -ForegroundColor Cyan
+dotnet build $reProj      -c $Configuration --nologo -v q | Out-Null
+dotnet build $instrProj   -c $Configuration --nologo -v q | Out-Null
+dotnet build $harnessProj -c $Configuration --nologo -v q | Out-Null
+
+$instrSourceDll = Get-ChildItem -Recurse (Join-Path $repoRoot "tools\AVEVA.Historian.ReverseInstrumentation\bin\$Configuration") `
+    -Filter "AVEVA.Historian.ReverseInstrumentation.dll" | Select-Object -First 1 -ExpandProperty FullName
+if (-not $instrSourceDll) { throw "ReverseInstrumentation.dll not found under bin\$Configuration." }
+
+Write-Host "== Instrumenting WriteMessage + ReadMessage ==" -ForegroundColor Cyan
+New-Item -ItemType Directory -Force -Path $captureDir | Out-Null
+# Chain via a distinct intermediate file (reading+writing the same path drops the second
+# hook on the mixed-mode native image). Final dll carries both hooks with distinct Phase
+# strings: WCF.WriteMessage.Body and WCF.ReadMessage.Body.
+$writeOnly = Join-Path $captureDir "aahClientManaged.write.dll"
+dotnet run --no-build -c $Configuration --project $reProj -- `
+    instrument-wcf-writemessage (Join-Path $repoRoot "current\aahClientManaged.dll") $writeOnly | Out-Null
+dotnet run --no-build -c $Configuration --project $reProj -- `
+    instrument-wcf-readmessage $writeOnly $instrDll | Out-Null
+
+Write-Host "== Staging current-copy ==" -ForegroundColor Cyan
+robocopy (Join-Path $repoRoot "current") $currentCopy /MIR /NJH /NJS /NDL /NP /NC /NS | Out-Null
+Copy-Item -Force $instrDll (Join-Path $currentCopy "aahClientManaged.dll")
+Copy-Item -Force $instrSourceDll (Join-Path $currentCopy "AVEVA.Historian.ReverseInstrumentation.dll")
+
+$harnessDll = Join-Path $currentCopy "aahClientManaged.dll"
+if (Test-Path $capturePath) { Remove-Item -Force $capturePath }
+$env:AVEVA_HISTORIAN_RE_CAPTURE = $capturePath
+
+Write-Host "== Capturing runtime-param ==" -ForegroundColor Green
+$harnessArgs = @(
+    "--scenario", "runtime-param",
+    "--server-name", $ServerName,
+    "--tcp-port", "$TcpPort",
+    "--runtime-param-names", $Names,
+    "--current-dir", $currentCopy,
+    "--managed-dll-path", $harnessDll
+)
+
+$harnessJson = $null
+try {
+    $prevEap = $ErrorActionPreference
+    $ErrorActionPreference = "Continue"
+    $harnessJson = & dotnet run --no-build -c $Configuration --project $harnessProj -- @harnessArgs 2>&1
+} catch {
+    Write-Host "   (runtime-param raised: $($_.Exception.Message))" -ForegroundColor Yellow
+} finally {
+    $ErrorActionPreference = $prevEap
+}
+
+Remove-Item Env:\AVEVA_HISTORIAN_RE_CAPTURE -ErrorAction SilentlyContinue
+
+$recCount = if (Test-Path $capturePath) { (Get-Content $capturePath | Where-Object { $_.Trim() }).Count } else { 0 }
+Write-Host "`n== Capture summary ==" -ForegroundColor Cyan
+Write-Host "   -> $recCount records -> $capturePath"
+Write-Host "Harness output (GetRuntimeParameterReturned / Results):" -ForegroundColor Cyan
+$harnessJson | Select-Object -Last 20
+Write-Host "`nDecode with: python scripts\decode-runtime-param-capture.py" -ForegroundColor Cyan

scripts/decode-runtime-param-capture.py

@@ -0,0 +1,128 @@
+"""Decode the GetRuntimeParameter WCF request/response (HCAL R1.2).
+
+Reads the chained WriteMessage+ReadMessage capture produced by
+scripts/Capture-RuntimeParam.ps1 and locates the GetRuntimeParameter exchange by
+searching every MDAS body for the parameter name (UTF-16) on the request side and the
+returned value on the response side. Dumps the surrounding bytes so the op name, the
+leading handle parameter, and the btRequest/btResponse buffer layout can be read off.
+
+Output is diagnostic. Sanitize before copying into docs/.
+"""
+import base64
+import json
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+CAPDIR = REPO_ROOT / "artifacts" / "reverse-engineering" / "instrumented-wcf-runtime-param"
+CAP = CAPDIR / "runtime-param-capture-latest.ndjson"
+
+# Markers we expect on the wire for the default "HistorianVersion" capture.
+NAME = "HistorianVersion"
+NAME_U16 = NAME.encode("utf-16-le")
+NAME_ASCII = NAME.encode("ascii")
+VALUE = "20,0,000,000"  # server runtime "HistorianVersion" value (version-shaped, not secret)
+VALUE_U16 = VALUE.encode("utf-16-le")
+VALUE_ASCII = VALUE.encode("ascii")
+
+
+def hexdump(label, buf, base=0):
+    print(f"=== {label}: {len(buf)} bytes ===")
+    for off in range(0, len(buf), 16):
+        c = buf[off:off + 16]
+        hp = " ".join(f"{x:02X}" for x in c)
+        ap = "".join(chr(x) if 32 <= x < 127 else "." for x in c)
+        print(f"  {base + off:04X}  {hp:<48}  |{ap}|")
+    print()
+
+
+def ascii_strings(buf, minlen=3):
+    out, cur, start = [], [], 0
+    for i, x in enumerate(buf):
+        if 32 <= x < 127:
+            if not cur:
+                start = i
+            cur.append(chr(x))
+        else:
+            if len(cur) >= minlen:
+                out.append((start, "".join(cur)))
+            cur = []
+    if len(cur) >= minlen:
+        out.append((start, "".join(cur)))
+    return out
+
+
+def u16_strings(buf, minlen=3):
+    out, i = [], 0
+    while i < len(buf) - 1:
+        j, chars = i, []
+        while j < len(buf) - 1 and 32 <= buf[j] < 127 and buf[j + 1] == 0:
+            chars.append(chr(buf[j]))
+            j += 2
+        if len(chars) >= minlen:
+            out.append((i, "".join(chars)))
+            i = j
+        else:
+            i += 1
+    return out
+
+
+def main() -> int:
+    if not CAP.exists():
+        print(f"Missing capture: {CAP}\nRun scripts/Capture-RuntimeParam.ps1 first.")
+        return 1
+
+    records = []
+    for line in CAP.open(encoding="utf-8-sig"):
+        if line.strip():
+            records.append(json.loads(line))
+
+    print(f"== {len(records)} MDAS bodies captured ==")
+    for idx, rec in enumerate(records):
+        body = base64.b64decode(rec["Base64"])
+        flags = []
+        if NAME_U16 in body or NAME_ASCII in body:
+            flags.append("NAME")
+        if VALUE_U16 in body or VALUE_ASCII in body:
+            flags.append("VALUE")
+        # The WS-Addressing action is the most reliable op label; show any string that
+        # looks like an op (contains a slash or is short and capitalized).
+        print(f"  [{idx:02d}] {rec.get('Phase'):26s} len={len(body):5d}  {','.join(flags)}")
+
+    def find(predicate):
+        hits = []
+        for idx, rec in enumerate(records):
+            body = base64.b64decode(rec["Base64"])
+            if predicate(rec, body):
+                hits.append((idx, rec, body))
+        return hits
+
+    print("\n== Request candidate(s): WriteMessage bodies containing the NAME ==")
+    for idx, rec, body in find(lambda r, b: r.get("Phase") == "WCF.WriteMessage.Body"
+                               and (NAME_U16 in b or NAME_ASCII in b)):
+        hexdump(f"[{idx}] WriteMessage", body)
+        print("  UTF-16 strings:")
+        for off, s in u16_strings(body):
+            print(f"    0x{off:04X} {s!r}")
+        print("  ASCII strings:")
+        for off, s in ascii_strings(body):
+            print(f"    0x{off:04X} {s!r}")
+        print()
+
+    print("\n== Response candidate(s): ReadMessage bodies containing the VALUE ==")
+    for idx, rec, body in find(lambda r, b: r.get("Phase") == "WCF.ReadMessage.Body"
+                               and (VALUE_U16 in b or VALUE_ASCII in b)):
+        hexdump(f"[{idx}] ReadMessage", body)
+        print("  UTF-16 strings:")
+        for off, s in u16_strings(body):
+            print(f"    0x{off:04X} {s!r}")
+        print("  ASCII strings:")
+        for off, s in ascii_strings(body):
+            print(f"    0x{off:04X} {s!r}")
+        print()
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())