Fix #820: refresh stale parent handle during nested merge patch

RFC 7396 merge-patch application recursed into a nested target object via a
held `JsonElement.Mutable`, but the recursion mutated the document (bumping
its version) without refreshing that parent handle. Processing any further
property of the same non-root parent then failed its staleness check —
surfacing as `InvalidOperationException` during the merge, or
`ObjectDisposedException: 'JsonDocument'` when a frozen patch copied into the
merge was read afterwards. The root element is exempt from the staleness
check, so only nested ("real") merges with an object-valued property followed
by another property were affected; the existing RFC 7396 suite (top-level /
single-property-per-level only) missed it.

A recursive merge mutates only the child's own subtree, so the parent's start
index is unchanged and only its cached version is stale. `ApplyMergePatch`
now re-mints the parent handle after each nested merge via a new
`IMutableJsonDocument.RefreshElementUnsafe<TElement>(int)` seam, surfaced as a
public, deliberately unsafe high-performance helper
`JsonMarshal.RefreshUnsafe<T>(in T)`. No `InternalsVisibleTo` is used (it would
leak the internal netstandard `ObsoleteAttribute` polyfill into the Patch
package); the merge reaches the seam alloc-free through constrained generics.

Adds regression tests (nested object-then-sibling merges, frozen-mutable patch
readability, an RFC 7396 correctness fuzz, and direct `JsonMarshal.RefreshUnsafe`
tests), documents the helper under the version-tracking section of
JsonDocumentBuilder.md, and adds the V5.1.17 version history entry.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mwadams

VERSIONHISTORY.md

@@ -1,5 +1,17 @@
 # Version History
 
+## V5.1.17
+
+V5.1.17 fixes an RFC 7396 JSON Merge Patch bug where merging a nested object corrupted the parent element handle.
+
+### Bug fixes
+
+- **`ApplyMergePatch` no longer leaves the parent element stale when merging a nested object** — When a merge patch recursed into a nested object (`JsonMergePatchExtensions.ApplyMergePatch`), the recursion mutated the document but the parent `JsonElement.Mutable` it was iterating kept its now-stale cached document version. Processing any further property of that same (non-root) parent then failed its staleness check, and a frozen patch document copied into the merge could appear disposed on a subsequent read — surfacing as `InvalidOperationException` ("Operation is not valid due to the current state of the object") during the merge or `ObjectDisposedException: 'JsonDocument'` when the patch was read afterwards. Because a recursive merge only mutates the child's own subtree, the parent element's start index is still valid; the merge now re-mints the parent handle with the current version after each nested merge so subsequent siblings and reads succeed. Simple single-property-per-level merges were unaffected, which is why the existing RFC 7396 suite did not catch it. See [#820](https://github.com/corvus-dotnet/Corvus.JsonSchema/issues/820).
+
+### New features
+
+- **`JsonMarshal.RefreshUnsafe<T>(in T)`** — Returns a fresh handle to a mutable JSON element whose cached document version is brought up to date with its parent document's current version, without re-validating the element's position. This is a deliberately **dangerous** marshalling helper: it must only be called when the caller knows the element's start index is still valid — i.e. the document has been mutated only *within that element's own subtree* (descendant nodes). It backs the RFC 7396 merge-patch fix above, where a recursive merge into a child object leaves the (structurally still valid) parent element version-stale. See [#820](https://github.com/corvus-dotnet/Corvus.JsonSchema/issues/820).
+
 ## V5.1.16
 
 V5.1.16 fixes schema reference resolution for `$ref`s expressed as `file://` URIs.

docs/JsonDocumentBuilder.md

@@ -1366,6 +1366,35 @@ Version tracking is a **safety feature** that prevents bugs caused by:
 
 Without version tracking, you could silently access incorrect data or crash with memory corruption. The `InvalidOperationException` is intentional and helps you write correct code. The root element exemption is safe because the root is always at index 0 and is never relocated.
 
+### Refreshing a stale reference without re-navigating (`JsonMarshal.RefreshUnsafe`) — advanced
+
+> ⚠️ **`JsonMarshal.RefreshUnsafe<T>` is a deliberately unsafe, high-performance escape hatch.** It is **only** for use where you *know* your changes cannot have altered the element's index in its parent document. Reach for it only in allocation- and lookup-sensitive code where you can *prove* the rule below holds. The safe, idiomatic option is always to re-navigate from the root (see [Best Practices](#best-practices-for-version-tracking)).
+
+There is one common case where re-navigating from the root is wasteful: you hold a cached *intermediate* element and then mutate **only inside that element's own subtree** (a descendant property or item). The mutation bumps the document version, so your cached handle is now version-stale — but the element itself has **not** moved: every descendant lives at a higher index than the element's own start row, so that start row is unchanged. Re-navigating from the root to find it again would be pure overhead.
+
+`Corvus.Runtime.InteropServices.JsonMarshal.RefreshUnsafe<T>(in T element)` takes such an element and returns a fresh handle to the *same* element, stamped with the document's current version — no lookup, no allocation:
+
+```csharp
+using Corvus.Runtime.InteropServices;
+
+JsonElement.Mutable root = doc.RootElement;
+JsonElement.Mutable order = root.GetProperty("order"u8);
+
+// Mutate only WITHIN 'order' (a descendant). This bumps the version, so 'order' is now stale,
+// but 'order' itself has not moved — only its subtree grew.
+order.GetProperty("lines"u8).SetProperty("count"u8, 3);
+
+// Refresh the handle in place instead of re-navigating from the root.
+order = JsonMarshal.RefreshUnsafe(in order);
+
+// 'order' is usable again.
+order.SetProperty("status"u8, "packed"u8);
+```
+
+This is exactly how RFC 7396 merge-patch application (`JsonMergePatchExtensions.ApplyMergePatch`) keeps the parent object live while recursively merging into its children.
+
+**The contract you must guarantee.** Use `RefreshUnsafe` **only where you know your changes cannot have modified the element's index in the parent document** — i.e. the document has been mutated **solely within the refreshed element's own subtree**, never at or before the element's position (the node itself replaced, an ancestor, or a *preceding sibling* changing size). If anything at or before the element moved, its start index is no longer valid and `RefreshUnsafe` returns a handle that **silently addresses the wrong node** — the very memory-corruption class that version tracking exists to prevent. `RefreshUnsafe` only checks for document disposal, never the correctness of the position, so it cannot catch this for you. When in doubt, re-navigate from the (always-live) root instead.
+
 ## Comparison with System.Text.Json.Nodes
 
 ### Similar Capabilities

docs/code-sample-catalog.yaml

@@ -967,11 +967,12 @@ main-docs:
       - {index: 38, language: csharp, lines: [1331, 1337], category: compilable, verified: false}
       - {index: 39, language: csharp, lines: [1340, 1348], category: compilable, verified: false}
       - {index: 40, language: csharp, lines: [1351, 1358], category: compilable, verified: false}
-      - {index: 41, language: csharp, lines: [1401, 1407], category: compilable, verified: false}
-      - {index: 42, language: csharp, lines: [1410, 1417], category: compilable, verified: false}
-      - {index: 43, language: csharp, lines: [1441, 1445], category: compilable, verified: false}
-      - {index: 44, language: csharp, lines: [1448, 1452], category: compilable, verified: false}
-      - {index: 45, language: csharp, lines: [1455, 1459], category: compilable, verified: false}
+      - {index: 41, language: csharp, lines: [1377, 1392], category: compilable, verified: false}
+      - {index: 42, language: csharp, lines: [1430, 1436], category: compilable, verified: false}
+      - {index: 43, language: csharp, lines: [1439, 1446], category: compilable, verified: false}
+      - {index: 44, language: csharp, lines: [1470, 1474], category: compilable, verified: false}
+      - {index: 45, language: csharp, lines: [1477, 1481], category: compilable, verified: false}
+      - {index: 46, language: csharp, lines: [1484, 1488], category: compilable, verified: false}
   - path: "docs/JsonLogic.md"
     blocks:
       - {index: 0, language: bash, lines: [29, 32]}

src/Corvus.Text.Json.Patch/JsonMergePatchExtensions.cs

@@ -2,6 +2,7 @@
 // Copyright (c) Endjin Limited. All rights reserved.
 // </copyright>
 
+using Corvus.Runtime.InteropServices;
 using Corvus.Text.Json.Internal;
 
 namespace Corvus.Text.Json.Patch;
@@ -65,6 +66,12 @@ public static void ApplyMergePatch(ref JsonElement.Mutable target, in JsonElemen
                 }
 
                 ApplyMergePatch(ref child, in patchValue);
+
+                // The recursive merge mutated only `child`'s subtree, so `target`'s start index is
+                // still valid, but its cached document version is now stale. Mint a fresh handle for
+                // the same element so the next property's staleness check — and any read of `target`
+                // after this method returns — succeeds.
+                target = JsonMarshal.RefreshUnsafe(in target);
             }
             else
             {

src/Corvus.Text.Json/Corvus/Runtime/InteropServices/JsonMarshal.cs

@@ -87,4 +87,45 @@ public static RawUtf8JsonString GetRawUtf8Value<T>(T element)
         element.CheckValidInstance();
         return element.ParentDocument.GetRawValue(element.ParentDocumentIndex, includeQuotes: true);
     }
+
+    /// <summary>
+    /// Returns a fresh handle to a mutable JSON element whose cached document version is brought up to
+    /// date with the parent document's current version, <strong>without</strong> re-validating the
+    /// element's position.
+    /// </summary>
+    /// <typeparam name="T">The type of the mutable <see cref="IJsonElement"/>.</typeparam>
+    /// <param name="element">The mutable element to refresh.</param>
+    /// <returns>A new <typeparamref name="T"/> for the same element, stamped with the parent document's
+    /// current version.</returns>
+    /// <exception cref="ObjectDisposedException">The underlying <see cref="JsonDocument"/> has been disposed.</exception>
+    /// <remarks>
+    /// <para>
+    /// This is a <strong>dangerous</strong>, high-performance helper. It is <strong>only</strong> safe
+    /// to call when you know that your mutations cannot have changed <paramref name="element"/>'s index
+    /// in its parent document. Unlike the other accessors here it deliberately does <strong>not</strong>
+    /// validate the element first — refreshing a version-stale handle is the whole point — so the
+    /// position is taken on trust.
+    /// </para>
+    /// <para>
+    /// That guarantee holds <strong>only</strong> when the document has been mutated entirely
+    /// <em>within this element's own subtree</em> (its descendant nodes) — never the element itself
+    /// (e.g. replaced), an ancestor, or a <em>preceding sibling</em> (whose size change would shift this
+    /// element). A descendant mutation only grows or shrinks the document at indices <em>after</em> the
+    /// element's start row, so that start row — and hence the element's index — is unchanged, and only
+    /// the cached version needs bringing up to date so subsequent staleness checks pass. Call it after
+    /// any other kind of mutation and it returns a handle that <strong>silently addresses the wrong
+    /// node</strong> — the memory-corruption class that version tracking exists to prevent. If you
+    /// cannot prove the index is unchanged, re-navigate from the (always-live) root element instead.
+    /// </para>
+    /// <para>
+    /// The canonical use is RFC 7396 merge-patch application, which re-mints the parent element after
+    /// recursively merging into one of its child objects.
+    /// </para>
+    /// </remarks>
+    [CLSCompliant(false)]
+    public static T RefreshUnsafe<T>(in T element)
+        where T : struct, IMutableJsonElement<T>
+    {
+        return ((IMutableJsonDocument)element.ParentDocument).RefreshElementUnsafe<T>(element.ParentDocumentIndex);
+    }
 }

src/Corvus.Text.Json/Corvus/Text/Json/DocumentBuilder/Internal/DefaultValueJsonDocument.cs

@@ -84,6 +84,15 @@ public TElement FreezeElement<TElement>(int index)
         => JsonElementHelpers.CreateInstance<TElement>(this.inner, index);
 #endif
 
+    /// <inheritdoc />
+    public TElement RefreshElementUnsafe<TElement>(int index)
+        where TElement : struct, IJsonElement<TElement>
+#if NET
+        => TElement.CreateInstance(this, index);
+#else
+        => JsonElementHelpers.CreateInstance<TElement>(this, index);
+#endif
+
     /// <inheritdoc />
     public JsonElement.Mutable GetArrayIndexElement(int currentIndex, int arrayIndex)
     {

src/Corvus.Text.Json/Corvus/Text/Json/DocumentBuilder/Internal/IMutableJsonDocument.cs

@@ -33,6 +33,27 @@ public interface IMutableJsonDocument : IWorkspaceManagedDocument
     TElement FreezeElement<TElement>(int index)
         where TElement : struct, IJsonElement<TElement>;
 
+    /// <summary>
+    /// Creates a fresh element of type <typeparamref name="TElement"/> for the element at the
+    /// specified index, capturing the document's current version.
+    /// </summary>
+    /// <typeparam name="TElement">The element type to return.</typeparam>
+    /// <param name="index">The metadata index of the element.</param>
+    /// <returns>A new element pointing at <paramref name="index"/>, stamped with the document's
+    /// current <see cref="Version"/>.</returns>
+    /// <remarks>
+    /// <para>
+    /// This is an <strong>unsafe</strong> operation: it does not validate that <paramref name="index"/>
+    /// still addresses the same logical element. It exists to refresh a held element after mutations
+    /// that are known to have affected only that element's descendant nodes (so its own start index —
+    /// which precedes all of its content — is unchanged), bringing its cached version up to date so
+    /// subsequent staleness checks pass. For example, RFC 7396 merge-patch application re-mints the
+    /// parent element after recursively merging into one of its child objects.
+    /// </para>
+    /// </remarks>
+    TElement RefreshElementUnsafe<TElement>(int index)
+        where TElement : struct, IJsonElement<TElement>;
+
     /// <summary>
     /// Gets the array element at the specified index as a mutable JSON element.
     /// </summary>

src/Corvus.Text.Json/Corvus/Text/Json/DocumentBuilder/JsonDocumentBuilder.cs

@@ -2119,6 +2119,17 @@ TElement IMutableJsonDocument.FreezeElement<TElement>(int index)
 #endif
     }
 
+    /// <inheritdoc />
+    TElement IMutableJsonDocument.RefreshElementUnsafe<TElement>(int index)
+    {
+        CheckNotDisposed();
+#if NET
+        return TElement.CreateInstance(this, index);
+#else
+        return JsonElementHelpers.CreateInstance<TElement>(this, index);
+#endif
+    }
+
     /// <summary>
     /// Initializes this builder as a frozen (immutable) copy of a segment of the
     /// source builder's metadb and value backing.