R1.5 GetTagExtendedPropertiesAsync (GetTepByNm) + R1.6 closed (no op)

Ship tag extended-property reads over the 2020 WCF aa/Retr/GetTepByNm op:
HistorianClient.GetTagExtendedPropertiesAsync(tag) -> name/value pairs.

String-handle op reached with the Open2 storage-session GUID formatted
uppercase (same format that unlocked GETRP/GETHI/ExeC). Routed via the
name-based native path (GetTagExtendedPropertiesByName, server-fetch flag),
not the index-based TagQuery path.

Evidence-backed findings from the capture:
- GetTepByNm (and GetTgByNm) succeed with the uppercase handle -- further
  validates the resolved string-handle wall.
- QTB (StartTagQuery) does NOT punch through: captured uppercase, it still
  fails server-side (CMdServer::StartActiveTagnamesQuery over the
  aahMetadataServer pipe) -- a metadata-server blocker, not handle format.
- R1.6 (localized properties) has NO distinct op (only error-message/UI-text
  localization in the managed client); collapses into R1.5. Closed, not throwing.

Wire format (golden-pinned, synthetic bytes -- no dev tag names committed):
- request tagNames = uint count + per-name(uint charCount + UTF-16)
- response = uint tagCount + per-tag(marker + compact-ASCII name +
  uint propCount + per-prop(marker + compact-ASCII name + 0x43 VT_BSTR value)
  + trailer); sequence-paged.

Adds: HistorianTagExtendedProperty model, HistorianTagExtendedPropertyProtocol
(codec), HistorianWcfTagExtendedPropertyClient (orchestration), dialect +
public API; golden WcfTagExtendedPropertyProtocolTests (4) + gated live test
(HISTORIAN_TEP_TAG). Tooling: Capture-TagExtendedProperties.ps1,
decode-tag-properties-capture.py, harness tag-extended-properties scenario.
Docs: wcf-tag-extended-properties.md; roadmap R1.5 DONE / R1.6 collapsed;
wall doc + memory updated with the QTB-server-side nuance. 228 tests green.

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

src/AVEVA.Historian.Client/HistorianClient.cs

@@ -166,6 +166,19 @@ public sealed class HistorianClient : IAsyncDisposable
         return _protocol.GetRuntimeParameterAsync(name, cancellationToken);
     }
 
+    /// <summary>
+    /// Reads the extended (user-defined) properties attached to a tag via the 2020 WCF
+    /// <c>GetTepByNm</c> op. Returns the property name/value pairs (empty when the tag has none).
+    /// String-valued properties only (the evidence-backed surface); other value variants throw
+    /// <see cref="ProtocolEvidenceMissingException"/>. See
+    /// <c>HistorianTagExtendedPropertyProtocol</c>.
+    /// </summary>
+    public Task<IReadOnlyList<HistorianTagExtendedProperty>> GetTagExtendedPropertiesAsync(string tag, CancellationToken cancellationToken = default)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(tag);
+        return _protocol.GetTagExtendedPropertiesAsync(tag, cancellationToken);
+    }
+
     /// <summary>
     /// Creates or updates the named tag in the Historian Runtime database via
     /// <c>EnsureTags2</c>. Currently only <see cref="HistorianDataType.Float"/> is

src/AVEVA.Historian.Client/Models/HistorianTagExtendedProperty.cs

@@ -0,0 +1,11 @@
+namespace AVEVA.Historian.Client.Models;
+
+/// <summary>
+/// A single extended (user-defined) property attached to a Historian tag — a name/value pair
+/// returned by <c>GetTagExtendedPropertiesAsync</c>. Extended properties are stored separately
+/// from the core tag metadata (server table <c>_TagExtendedProperty</c>) and are exposed over the
+/// 2020 WCF <c>aa/Retr/GetTepByNm</c> op.
+/// </summary>
+/// <param name="Name">The property name (e.g., <c>Location</c>).</param>
+/// <param name="Value">The property value as a string (the wire format is a VT_BSTR variant).</param>
+public sealed record HistorianTagExtendedProperty(string Name, string Value);

src/AVEVA.Historian.Client/Protocol/Historian2020ProtocolDialect.cs

@@ -74,6 +74,13 @@ internal sealed class Historian2020ProtocolDialect
         return Wcf.HistorianWcfStatusClient.GetRuntimeParameterAsync(_options, name, cancellationToken);
     }
 
+    public Task<IReadOnlyList<Models.HistorianTagExtendedProperty>> GetTagExtendedPropertiesAsync(string tag, CancellationToken cancellationToken)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        ArgumentException.ThrowIfNullOrWhiteSpace(tag);
+        return Wcf.HistorianWcfTagExtendedPropertyClient.GetTagExtendedPropertiesAsync(_options, tag, cancellationToken);
+    }
+
     private static async IAsyncEnumerable<T> Missing<T>(
         string operation,
         [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken)

src/AVEVA.Historian.Client/Wcf/HistorianTagExtendedPropertyProtocol.cs

@@ -0,0 +1,174 @@
+using System.Buffers.Binary;
+using System.Text;
+using AVEVA.Historian.Client.Models;
+using AVEVA.Historian.Client.Protocol;
+
+namespace AVEVA.Historian.Client.Wcf;
+
+/// <summary>
+/// Serializes the <c>GetTepByNm</c> (GetTagExtendedPropertiesFromName) request buffer and parses
+/// its response buffer for AVEVA Historian 2020 over WCF/MDAS.
+/// </summary>
+/// <remarks>
+/// Wire format captured from the native client (<c>scripts/Capture-TagExtendedProperties.ps1</c>
+/// + instrument-wcf-{write,read}message; golden-pinned in
+/// <c>WcfTagExtendedPropertyProtocolTests</c>). The op is
+/// <c>aa/Retr/GetTepByNm(string handle, byte[] tagNames, ref uint sequence) -&gt; (bool,
+/// byte[] tagExtendedProperties, byte[] errorBuffer)</c> — a string-handle op reachable from the
+/// pure-managed client using the Open2 storage-session GUID as an <b>uppercase</b> handle (the
+/// same format that unlocked GETRP/GETHI/ExeC; see <c>wcf-string-handle-wall.md</c>).
+///
+/// <para><b>tagNames</b> request buffer: <c>uint32 count</c> then per name <c>uint32 charCount</c>
+/// + UTF-16LE chars.</para>
+///
+/// <para><b>tagExtendedProperties</b> response buffer: <c>uint32 tagCount</c> then per tag a
+/// 1-byte group marker (observed <c>0x01</c>) + compact-ASCII tag name (<c>0x09</c> + uint16 byte
+/// length + ASCII), <c>uint32 propertyCount</c>, then per property a 1-byte marker (observed
+/// <c>0x02</c>) + compact-ASCII property name + a CRetVariant value (<c>0x43</c> VT_BSTR + uint16
+/// payload length + uint16 charCount + UTF-16LE), and a 1-byte trailing marker (observed
+/// <c>0x01</c>). Only the string value variant (<c>0x43</c>) is evidence-backed; other variant
+/// types throw <see cref="ProtocolEvidenceMissingException"/>.</para>
+///
+/// <para>The op is sequence-paged: call with <c>sequence = 0</c>, parse the buffer, then re-call
+/// with the returned sequence until the response carries no rows. Only string-valued properties
+/// from a single capture are exercised; the single-byte group/property markers are pinned as
+/// observed constants and their full semantics are not independently disambiguated.</para>
+/// </remarks>
+internal static class HistorianTagExtendedPropertyProtocol
+{
+    private const byte CompactStringMarker = 0x09;
+    private const byte VariantTypeBStr = 0x43;
+
+    /// <summary>Serializes the <c>tagNames</c> request buffer for a single tag.</summary>
+    public static byte[] SerializeRequest(string tagName)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(tagName);
+
+        using MemoryStream stream = new();
+        using BinaryWriter writer = new(stream, Encoding.Unicode, leaveOpen: true);
+
+        writer.Write(1u);                          // name count = 1
+        writer.Write((uint)tagName.Length);        // char count
+        writer.Write(Encoding.Unicode.GetBytes(tagName));
+
+        writer.Flush();
+        return stream.ToArray();
+    }
+
+    /// <summary>
+    /// Parses the <c>tagExtendedProperties</c> response buffer into a flat list of
+    /// (tagName, propertyName, value) rows. Returns an empty list when the buffer carries no rows
+    /// (the terminal page of the sequence loop), which is how callers know to stop paging.
+    /// </summary>
+    public static IReadOnlyList<HistorianTagExtendedPropertyRow> ParseResponse(ReadOnlySpan<byte> buffer)
+    {
+        if (buffer.Length < 4)
+        {
+            return [];
+        }
+
+        int cursor = 0;
+        uint tagCount = ReadUInt32(buffer, ref cursor);
+        if (tagCount == 0)
+        {
+            return [];
+        }
+
+        List<HistorianTagExtendedPropertyRow> rows = [];
+        for (uint t = 0; t < tagCount; t++)
+        {
+            // 1-byte group marker (observed 0x01).
+            SkipByte(buffer, ref cursor);
+            string tagName = ReadCompactAsciiString(buffer, ref cursor);
+
+            uint propertyCount = ReadUInt32(buffer, ref cursor);
+            for (uint p = 0; p < propertyCount; p++)
+            {
+                // 1-byte property marker (observed 0x02 — likely the property value type).
+                SkipByte(buffer, ref cursor);
+                string propertyName = ReadCompactAsciiString(buffer, ref cursor);
+                string value = ReadVariantStringValue(buffer, ref cursor);
+                rows.Add(new HistorianTagExtendedPropertyRow(tagName, propertyName, value));
+            }
+
+            // 1-byte trailing marker (observed 0x01) after the property block. Read it only if a
+            // byte remains so a tightly-packed terminal buffer doesn't over-read.
+            if (cursor < buffer.Length)
+            {
+                SkipByte(buffer, ref cursor);
+            }
+        }
+
+        return rows;
+    }
+
+    private static string ReadCompactAsciiString(ReadOnlySpan<byte> buffer, ref int cursor)
+    {
+        EnsureAvailable(buffer, cursor, 3);
+        byte marker = buffer[cursor++];
+        if (marker != CompactStringMarker)
+        {
+            throw new ProtocolEvidenceMissingException(
+                $"GetTepByNm response expected compact string marker 0x09, found 0x{marker:X2}.");
+        }
+
+        ushort byteLength = ReadUInt16(buffer, ref cursor);
+        EnsureAvailable(buffer, cursor, byteLength);
+        string value = Encoding.ASCII.GetString(buffer.Slice(cursor, byteLength));
+        cursor += byteLength;
+        return value;
+    }
+
+    private static string ReadVariantStringValue(ReadOnlySpan<byte> buffer, ref int cursor)
+    {
+        EnsureAvailable(buffer, cursor, 5);
+        byte variantType = buffer[cursor++];
+        if (variantType != VariantTypeBStr)
+        {
+            throw new ProtocolEvidenceMissingException(
+                $"GetTepByNm response value variant type 0x{variantType:X2} is not the evidence-backed string variant (0x43).");
+        }
+
+        // uint16 payload length (bytes that follow the charCount field), then uint16 charCount.
+        _ = ReadUInt16(buffer, ref cursor);
+        ushort charCount = ReadUInt16(buffer, ref cursor);
+        int byteCount = charCount * 2;
+        EnsureAvailable(buffer, cursor, byteCount);
+        string value = Encoding.Unicode.GetString(buffer.Slice(cursor, byteCount));
+        cursor += byteCount;
+        return value;
+    }
+
+    private static void SkipByte(ReadOnlySpan<byte> buffer, ref int cursor)
+    {
+        EnsureAvailable(buffer, cursor, 1);
+        cursor++;
+    }
+
+    private static ushort ReadUInt16(ReadOnlySpan<byte> buffer, ref int cursor)
+    {
+        EnsureAvailable(buffer, cursor, 2);
+        ushort value = BinaryPrimitives.ReadUInt16LittleEndian(buffer.Slice(cursor, 2));
+        cursor += 2;
+        return value;
+    }
+
+    private static uint ReadUInt32(ReadOnlySpan<byte> buffer, ref int cursor)
+    {
+        EnsureAvailable(buffer, cursor, 4);
+        uint value = BinaryPrimitives.ReadUInt32LittleEndian(buffer.Slice(cursor, 4));
+        cursor += 4;
+        return value;
+    }
+
+    private static void EnsureAvailable(ReadOnlySpan<byte> buffer, int cursor, int byteCount)
+    {
+        if (cursor < 0 || byteCount < 0 || cursor > buffer.Length - byteCount)
+        {
+            throw new InvalidDataException("GetTepByNm response ended unexpectedly.");
+        }
+    }
+}
+
+/// <summary>One (tag, propertyName, value) row parsed from a GetTepByNm response buffer.</summary>
+internal sealed record HistorianTagExtendedPropertyRow(string TagName, string PropertyName, string Value);

src/AVEVA.Historian.Client/Wcf/HistorianWcfTagExtendedPropertyClient.cs

@@ -0,0 +1,107 @@
+using System.ServiceModel;
+using System.ServiceModel.Channels;
+using AVEVA.Historian.Client.Models;
+using AVEVA.Historian.Client.Wcf.Contracts;
+
+namespace AVEVA.Historian.Client.Wcf;
+
+/// <summary>
+/// Reads tag extended properties (HCAL R1.5) over the 2020 WCF <c>aa/Retr/GetTepByNm</c> op. This
+/// is a string-handle op reached with the Open2 storage-session GUID formatted UPPERCASE — the same
+/// handle format that unlocked GETRP/GETHI/ExeC (see <c>wcf-string-handle-wall.md</c>).
+/// </summary>
+internal static class HistorianWcfTagExtendedPropertyClient
+{
+    // GetTepByNm is sequence-paged. A single tag with a handful of properties returns everything in
+    // the first buffer and an empty buffer on the next call; the cap is a runaway guard.
+    private const int MaxPages = 64;
+
+    /// <summary>Diagnostic: the GetTepByNm return code / error from the last call (set only on
+    /// server rejection).</summary>
+    public static string? LastError { get; private set; }
+
+    public static Task<IReadOnlyList<HistorianTagExtendedProperty>> GetTagExtendedPropertiesAsync(
+        HistorianClientOptions options,
+        string tag,
+        CancellationToken cancellationToken)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(tag);
+        return Task.Run(() => GetTagExtendedProperties(options, tag), cancellationToken);
+    }
+
+    private static IReadOnlyList<HistorianTagExtendedProperty> GetTagExtendedProperties(
+        HistorianClientOptions options,
+        string tag)
+    {
+        Guid contextKey = Guid.NewGuid();
+        var (histBinding, histEndpoint, retrBinding, retrEndpoint) = HistorianWcfBindingFactory.CreateBindingPair(options);
+
+        LastError = null;
+        List<HistorianTagExtendedProperty> properties = [];
+        HistorianWcfAuthChainHelper.OpenAuthenticatedConnection(
+            options, histBinding, histEndpoint, contextKey, CancellationToken.None,
+            additionalSetup: (_, context) =>
+                QueryExtendedProperties(retrBinding, retrEndpoint, options, context.StorageSessionId, tag, properties));
+        return properties;
+    }
+
+    private static void QueryExtendedProperties(
+        Binding retrBinding,
+        EndpointAddress retrEndpoint,
+        HistorianClientOptions options,
+        Guid storageSessionId,
+        string tag,
+        List<HistorianTagExtendedProperty> sink)
+    {
+        // GetTepByNm takes the storage-session GUID as a string handle, formatted exactly as the
+        // native client sends it: uppercase, dash-separated, no braces.
+        string handle = storageSessionId.ToString("D").ToUpperInvariant();
+        byte[] tagNames = HistorianTagExtendedPropertyProtocol.SerializeRequest(tag);
+
+        ChannelFactory<IRetrievalServiceContract4> factory = new(retrBinding, retrEndpoint);
+        HistorianWcfClientCredentialsHelper.Configure(factory, options);
+        IRetrievalServiceContract4 channel = factory.CreateChannel();
+        ICommunicationObject co = (ICommunicationObject)channel;
+        try
+        {
+            // Prime the Retrieval service version handshake (Retr.GetV), as the native client does
+            // before any string-handle Retrieval op.
+            channel.GetInterfaceVersion(out _);
+
+            uint sequence = 0;
+            for (int page = 0; page < MaxPages; page++)
+            {
+                bool ok = channel.GetTagExtendedPropertiesFromName(
+                    handle, tagNames, ref sequence, out byte[] responseBuffer, out byte[] errorBuffer);
+                if (!ok)
+                {
+                    // A non-success on the first page is a real failure; on a later page it is the
+                    // benign end-of-paging terminator (server returns nil + a FillBufferFromVector
+                    // marker once the rows are exhausted).
+                    if (page == 0)
+                    {
+                        LastError = $"GetTepByNm returned false (responseLen={responseBuffer?.Length ?? 0}, errorLen={errorBuffer?.Length ?? 0}).";
+                    }
+                    break;
+                }
+
+                IReadOnlyList<HistorianTagExtendedPropertyRow> rows =
+                    HistorianTagExtendedPropertyProtocol.ParseResponse(responseBuffer ?? []);
+                if (rows.Count == 0)
+                {
+                    break;
+                }
+
+                foreach (HistorianTagExtendedPropertyRow row in rows)
+                {
+                    sink.Add(new HistorianTagExtendedProperty(row.PropertyName, row.Value));
+                }
+            }
+        }
+        finally
+        {
+            try { if (co.State == CommunicationState.Faulted) co.Abort(); else co.Close(); } catch { try { co.Abort(); } catch { } }
+            try { if (factory.State == CommunicationState.Faulted) factory.Abort(); else factory.Close(); } catch { try { factory.Abort(); } catch { } }
+        }
+    }
+}