From 1edfc263ec82c0489f1e74836f01c9d412f61f8e Mon Sep 17 00:00:00 2001
From: Joseph Doherty <dohejw01@gmail.com>
Date: Mon, 17 Aug 2026 05:31:28 -0400
Subject: [PATCH] docs(mtconnect): state AsStream's buffer aliasing and
 lifetime contract

---
 .../MTConnectStreamsParser.cs                         | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect/MTConnectStreamsParser.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect/MTConnectStreamsParser.cs
index a5409aba..b0d6bdff 100644
--- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect/MTConnectStreamsParser.cs
+++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect/MTConnectStreamsParser.cs
@@ -241,7 +241,16 @@ internal static class MTConnectStreamsParser
     /// <summary>
     ///     Views the (already trimmed) bytes as a stream without copying them where the memory is
     ///     array-backed — which it always is on the <c>/sample</c> path, whose framer hands over the
-    ///     part's own <c>byte[]</c>.
+    ///     part's own <c>byte[]</c>. That branch <b>aliases</b> the caller's array; only the
+    ///     non-array-backed fallback copies (via <c>ToArray</c>).
+    ///     <para>
+    ///         Ownership, so a caller can reason about the aliased buffer: nothing on this path pools
+    ///         or rents it (the framer allocates each <c>byte[]</c> fresh), and parsing is fully
+    ///         synchronous, so the buffer need only stay valid and unmutated for the duration of the
+    ///         <c>Parse</c> call. The returned <see cref="MTConnectStreamsResult"/> holds no reference
+    ///         into it — <see cref="XmlReader"/> materialises its own strings — so the caller may
+    ///         reuse or discard the buffer as soon as <c>Parse</c> returns.
+    ///     </para>
     /// </summary>
     private static MemoryStream AsStream(ReadOnlyMemory<byte> xml) =>
         MemoryMarshal.TryGetArray(xml, out ArraySegment<byte> segment) && segment.Array is not null