fix(buffers): make MemoryHandle's representation private, and decline the destructor (#2059, SR-AUD-088)

Rule-14 sweep: this ticket's recorded gate was "/rv/tmp/runtime/src/libraries/
RE-VERIFIED ABSENT 2026-08-04, so reference behaviour comes only from
repository-contained evidence". /rv is present, and it resolves the ticket --
against the ticket's own proposed repair.

PREMISE CORRECTED. .NET's type is `public unsafe struct MemoryHandle :
IDisposable` (MemoryHandle.cs:12), a struct with no finalizer, so scope exit
does not unpin there either. `using var h = memory.Pin();` is a language
construct that calls Dispose(), not something the type does. SR-AUD-088's
real content was a DOC-COMMENT promising "or let the destructor do it" -- a
promise the type never kept, and which an earlier ticket had already removed.

So `~MemoryHandle(){ Dispose(); }` is DECLINED rather than deferred: adding
it would be a divergence, not a repair. The ticket's own copy hazard is the
second, independent reason and it stands -- this is a copyable handle, so an
unpinning destructor would unpin once per copy for a single pin. Dispose()
needed no change; it already matches MemoryHandle.cs:41-53 statement for
statement, idempotence included.

What DID land is the divergence the ticket never named. .NET's three fields
are all private and it publishes exactly one, Pointer, as a getter. This port
published both of its two as mutable data members, so a caller could retarget
a live handle, or detach its IPinnable -- which makes the subsequent
Dispose() a silent no-op that leaks the pin. Both are now private, under
SA-8, with SA-2's five conditions discharged.

An access change, not a layout change: sizeof(MemoryHandle) is 24 before and
after, so no consumer rebuilds -- the same shape as #2332's SequencePosition.
Zero first-party migration sites, measured. .NET's third field, GCHandle
_handle, stays deliberately absent: no moving collector, no handle to free.

The pin comments are corrected rather than merely extended:
ScopeExitDoesNotUnpin said ".NET-style RAII would unpin here. It does not.",
which states a falsehood about .NET, and now asserts parity.

Five mutations, all caught, two at compile time through absence pins that use
a dependent parameter (the #2299 gcc trap).

Fixture set 37/200 -> 38/204. Downstream measured: 0 sites in cna, 0 in
mobile-eggbert.

Gate: 17,421 run, 17,421 passed, 0 failed, 0 skipped across 38 executables
(+1 on 17,420; SharpRuntimeTests_Buffers 629 -> 630; no other executable
moved). Module graph unchanged at 41/93.

Author: robertvokac

CLAUDE.md

@@ -0,0 +1,116 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) Robert Vokac and contributors -->
+
+# Migration — `MemoryHandle`'s representation is private, and the destructor is declined (ticket #2059, SR-AUD-088)
+
+*2026-08-19.* `System::Buffers::MemoryHandle`'s two data members are now `private`, matching
+.NET. The RAII destructor the ticket proposed was measured against the reference and **declined**.
+
+Landed under `docs/StandingApprovals.md` **SA-8** (public representation where .NET's is private
+→ match .NET and migrate the first-party sites), with SA-2's five conditions discharged for the
+source break. **No layout change** — `sizeof(MemoryHandle)` is 24 before and after — so no
+consumer needs a rebuild.
+
+---
+
+## 1. The finding's premise does not survive the reference
+
+SR-AUD-088 is titled *"MemoryHandle documents RAII cleanup but never unpins at scope exit"*, and
+#2059 was opened to add `~MemoryHandle(){ Dispose(); }`.
+
+.NET's type is:
+
+```csharp
+public unsafe struct MemoryHandle : IDisposable   // MemoryHandle.cs:12
+{
+    private void*      _pointer;
+    private GCHandle   _handle;
+    private IPinnable? _pinnable;
+    ...
+}
+```
+
+A `struct` with **no finalizer**. Scope exit does not unpin in .NET either. `using var handle =
+memory.Pin();` is a *language* construct that calls `Dispose()`; it is not something the type does
+for you.
+
+So what SR-AUD-088 actually found was a **doc-comment that promised something the type never
+did** — *"should call Dispose() explicitly (or let the destructor do it)"*. That promise was the
+defect, and an earlier ticket had already removed it. The behaviour it described was never wrong.
+
+**Adding the destructor would therefore be a divergence from .NET, not a repair**, and #2059
+declines it. The ticket's own hazard analysis is the second, independent reason and it stands:
+this is a copyable handle, so an unpinning destructor would unpin **once per copy** for a single
+pin.
+
+`Dispose()` needed no change either — it already matches `MemoryHandle.cs:41-53` statement for
+statement: unpin, clear the `IPinnable`, null the pointer, so a second call does nothing.
+
+## 2. What did change
+
+The divergence the ticket never named. .NET's three fields are all `private` and it publishes
+exactly one of them, `Pointer`, as a getter. This port published **both** of its two as mutable
+data members.
+
+| | Was | Is |
+|---|---|---|
+| `pointer_` | public, mutable | **private** |
+| `pinnable_` | public, mutable | **private** |
+| `getPointerProperty()` | public getter | unchanged |
+| both constructors | public | unchanged |
+| `Dispose()` | public, idempotent | unchanged |
+| copyability | copyable | unchanged |
+| `sizeof(MemoryHandle)` | **24** | **24** |
+| a destructor | absent | **still absent, now for a stated reason** |
+
+.NET's third field, `private GCHandle _handle`, stays deliberately absent here: this runtime has
+no moving collector, so there is no GC handle to free.
+
+## 3. Why it matters
+
+`pinnable_` is the dangerous one, and it fails **silently**:
+
+```cpp
+MemoryHandle handle = buffer.Pin(0);
+handle.pinnable_ = nullptr;   // used to compile
+handle.Dispose();             // now a no-op -- the pin leaks, with no diagnostic anywhere
+```
+
+`pointer_` is the same shape one level down: a caller could retarget a live handle at an
+unrelated address and then dispose a handle whose pointer no longer described what was pinned.
+
+## 4. To migrate
+
+| Was | Now |
+|---|---|
+| `h.pointer_` (read) | `h.getPointerProperty()` |
+| `h.pointer_ = p` | construct a new handle: `h = MemoryHandle(p, pinnable)` |
+| `h.pinnable_` (read or write) | **no replacement, by design** — .NET exposes no accessor either; to release the pin, call `h.Dispose()` |
+
+**Zero first-party sites needed migrating** — measured across all of `modules/` and `test/`, there
+were no direct accesses to either member outside the type itself. The five construction sites all
+go through the public constructors and are untouched.
+
+## 5. Evidence
+
+Five mutations, **all caught**:
+
+| Mutation | Caught by |
+|---|---|
+| M1 — both members public again | `MemoryHandlePinTests.TheRepresentationIsPrivateAsInDotNet` (compile time) |
+| M2 — only `pinnable_` public again | the same test's second `static_assert` (compile time) |
+| M3 — add the destructor the ticket proposed | `MemoryHandlePinTests.ScopeExitDoesNotUnpin` |
+| M4 — `Dispose()` stops clearing `pinnable_` | `MemoryHandlePinTests.ExplicitDisposeUnpinsExactlyOnce` |
+| M5 — `Dispose()` leaves a dangling pointer | that test **and** `MemoryHandleTests.Dispose_ClearsPointer` |
+
+The absence pins use a **dependent** parameter, because gcc evaluates a non-dependent `requires`
+eagerly and hard-errors on the access instead of yielding `false` — the #2299 trap.
+
+Negative consumer fixture: `test/consumer/buffers_memoryhandle_private_negative.cpp`, four sites,
+all rejected. The fixture set grows to **38 fixtures / 204 sites**. Its site 3 is the detach that
+breaks silently rather than loudly.
+
+## 6. Downstream, measured
+
+Per SA-2 condition 5: `MemoryHandle` appears in **zero** places in `cna` and **zero** in
+`mobile-eggbert`. Neither repository was modified, and no downstream ticket is needed.

docs/Migration-MemoryHandlePrivateRepresentation.md

@@ -67,7 +67,10 @@ static_assert(sizeof(ArrayBufferWriter<char>) == 40,
 static_assert(sizeof(StandardFormat) == 2,
               "#2052 must not have added state");
 static_assert(sizeof(MemoryHandle) == 24,
-              "#2059's move-only or refcounted semantics would change this");
+              "#2059 made the two members PRIVATE, which is an access change and not a layout "
+              "change -- 24 before and 24 after, so no consumer rebuilds. A destructor or "
+              "refcounted semantics would change this, and #2059 measured the reference and "
+              "declined both.");
 
 TEST(BuffersLayoutPinTests, LayoutsAreStaticallyAsserted) {
     SUCCEED() << "The static_asserts above are the test; this keeps it visible in the suite.";
@@ -244,7 +247,22 @@ TEST(ReadOnlySequenceSegmentPinTests, EverySequenceReportsASingleSegment) {
 }
 
 // ===========================================================================
-// SR-AUD-088 — MemoryHandle performs no RAII cleanup (blocked #2059)
+// SR-AUD-088 — MemoryHandle performs no RAII cleanup (#2059 RESOLVED).
+//
+// THE FINDING'S PREMISE DOES NOT SURVIVE THE REFERENCE, and the pins below used to
+// restate it. .NET's MemoryHandle is `public unsafe struct MemoryHandle : IDisposable`
+// (MemoryHandle.cs:12) -- a value type with no finalizer -- so scope exit does not unpin
+// THERE EITHER. `using var h = memory.Pin();` is a language construct that calls
+// Dispose(); it is not something the type does.
+//
+// What SR-AUD-088 actually found was a DOC-COMMENT that promised "or let the destructor
+// do it". That promise was the defect and it is gone. The behaviour it described was
+// never wrong.
+//
+// #2059 therefore declines the destructor rather than deferring it: adding one would be
+// a divergence from .NET, and the copy hazard below is the second, independent reason.
+// What #2059 DID land is the divergence the ticket never named -- the two data members
+// were public here and are private in .NET -- under SA-8, at zero migration sites.
 // ===========================================================================
 
 namespace {
@@ -262,9 +280,11 @@ TEST(MemoryHandlePinTests, ScopeExitDoesNotUnpin) {
     {
         MemoryHandle handle = p.Pin(0);
         EXPECT_EQ(handle.getPointerProperty(), &p.value);
-    }   // .NET-style RAII would unpin here. It does not. #2059.
+    }   // No unpin here -- and .NET does not unpin here either (MemoryHandle.cs:12, a
+        // struct with no finalizer). This asserts PARITY, not a known gap.
     EXPECT_EQ(p.unpinCount, 0)
-        << "if this becomes 1, MemoryHandle has grown a destructor -- #2059 has landed";
+        << "if this becomes 1, MemoryHandle has grown a destructor and now diverges from "
+           ".NET -- #2059 measured that and declined it";
 }
 
 TEST(MemoryHandlePinTests, ExplicitDisposeUnpinsExactlyOnce) {
@@ -278,8 +298,9 @@ TEST(MemoryHandlePinTests, ExplicitDisposeUnpinsExactlyOnce) {
 }
 
 TEST(MemoryHandlePinTests, ACopyStillReferencesTheSamePinnable) {
-    // This is why #2059 cannot simply add a destructor: an unpinning destructor on a
-    // freely copyable aggregate would unpin once per copy.
+    // The SECOND reason #2059 declined the destructor, independent of the reference: an
+    // unpinning destructor on a freely copyable handle would unpin once per copy for a
+    // single pin. .NET has the same copy semantics and the same absence of a destructor.
     CountingPinnable p;
     MemoryHandle original = p.Pin(0);
     MemoryHandle copy = original;
@@ -288,6 +309,39 @@ TEST(MemoryHandlePinTests, ACopyStillReferencesTheSamePinnable) {
     EXPECT_EQ(p.unpinCount, 2) << "two handles, two Unpins -- one pin";
 }
 
+namespace {
+    /** True iff `T::pointer_` is reachable from outside the type. */
+    template <typename T>
+    concept HasPublicPointerMember = requires(T h) { h.pointer_; };
+    template <typename T>
+    concept HasPublicPinnableMember = requires(T h) { h.pinnable_; };
+}
+
+TEST(MemoryHandlePinTests, TheRepresentationIsPrivateAsInDotNet) {
+    // .NET publishes only `Pointer`, as a getter (MemoryHandle.cs:35). Both fields are
+    // private there and are now private here.
+    //
+    // The parameter is DEPENDENT on purpose: gcc evaluates a non-dependent `requires`
+    // eagerly and hard-errors on the access instead of yielding false (the #2299 trap).
+    static_assert(!HasPublicPointerMember<MemoryHandle>,
+                  "#2059: pointer_ is private -- read it with getPointerProperty()");
+    static_assert(!HasPublicPinnableMember<MemoryHandle>,
+                  "#2059: pinnable_ is private, and .NET publishes no accessor for it at all");
+
+    // What did NOT change, asserted so the pin proves the boundary is an access change and
+    // nothing else: the two public constructors, the getter, copyability and the size.
+    CountingPinnable p;
+    MemoryHandle handle(&p.value, &p);
+    EXPECT_EQ(handle.getPointerProperty(), &p.value);
+    MemoryHandle copied = handle;
+    EXPECT_EQ(copied.getPointerProperty(), &p.value);
+    EXPECT_EQ(MemoryHandle().getPointerProperty(), nullptr);
+    static_assert(std::is_copy_constructible_v<MemoryHandle>, "still copyable");
+    static_assert(sizeof(MemoryHandle) == 24, "an access change moves no layout");
+    handle.Dispose();
+    copied.Dispose();
+}
+
 // ===========================================================================
 // SR-AUD-086 — the leading '+' asymmetry (#2060 RESOLVED).
 //

modules/buffers/tests/System/Buffers/BuffersContractPinTests.cpp

@@ -16,24 +16,26 @@ struct IPinnable;
  * Wraps a raw pointer to pinned memory and optionally holds a reference to an
  * IPinnable that must be unpinned on disposal.
  *
- * @warning **This type performs no RAII cleanup: the caller MUST call Dispose()
- * explicitly.** There is no destructor that calls Dispose, and the inherited
- * `~IDisposable` does nothing, so letting a MemoryHandle go out of scope leaves its
- * IPinnable pinned. The header previously claimed the destructor would do it; it
- * never did (SR-AUD-088).
+ * @note **The caller must call Dispose() explicitly. Scope exit does not unpin — and
+ * that MATCHES .NET, which is why no destructor is added here.** .NET's
+ * `MemoryHandle` is a `public unsafe struct` with no finalizer
+ * (`MemoryHandle.cs:12`), so letting one go out of scope leaves its `IPinnable`
+ * pinned there too. `using var handle = memory.Pin();` is a *language* construct that
+ * calls `Dispose()`; it is not something the type does for you.
  *
- * Adding such a destructor is **not** a small correction and is deliberately not made
- * here: this is a copyable aggregate with public members, so an unpinning destructor
- * would make every copy unpin the same IPinnable more than once. A correct repair needs
- * move-only or reference-counted semantics on a type that `Memory.hpp` and
- * `ReadOnlyMemory.hpp` include, i.e. reaching all of `Core.Base`. That is blocked ticket
- * **#2059** (CCF-019); see docs/BuffersNamespaceReviewPlan.md §4.11. The behaviour
- * documented above is pinned by a permanent test, so it cannot change silently.
+ * SR-AUD-088 reported that this header *promised* RAII cleanup — "should call
+ * Dispose() explicitly (or let the destructor do it)" — that it never performed. That
+ * promise was the defect and it has been removed. Ticket **#2059** then measured the
+ * proposed repair against the reference and **declined it**: adding
+ * `~MemoryHandle(){ Dispose(); }` would be a divergence from .NET rather than a repair,
+ * and the hazard is real as well as theoretical — this is a copyable handle, so an
+ * unpinning destructor would unpin once per copy for a single pin. The absence is pinned
+ * by `MemoryHandlePinTests`.
+ *
+ * `Dispose()` is idempotent, exactly as .NET's is (`MemoryHandle.cs:41-53`): it unpins,
+ * clears the `IPinnable` and nulls the pointer, so a second call does nothing.
  */
 struct MemoryHandle : System::IDisposable {
-    void*      pointer_  = nullptr;
-    IPinnable* pinnable_ = nullptr;
-
     /** @brief Constructs a default (null) MemoryHandle. */
     MemoryHandle() = default;
 
@@ -57,6 +59,17 @@ struct MemoryHandle : System::IDisposable {
      * Defined after IPinnable is complete (see IPinnable.hpp).
      */
     void Dispose() override;
+
+private:
+    // PRIVATE, matching .NET's `private void* _pointer` / `private IPinnable? _pinnable`
+    // (MemoryHandle.cs:14-16). This port published both, so a caller could retarget a live
+    // handle at an unrelated address, or detach its IPinnable and leak the pin, behind the
+    // owner's back. .NET publishes only `Pointer`, and only as a getter.
+    //
+    // .NET's third field, `private GCHandle _handle`, is deliberately absent: this runtime
+    // has no moving collector, so there is no GC handle to free.
+    void*      pointer_  = nullptr;
+    IPinnable* pinnable_ = nullptr;
 };
 
 } // namespace System::Buffers

modules/core/include/System/Buffers/MemoryHandle.hpp

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) Robert Vokac and contributors
+//
+// Negative compile fixture for ticket #2059 (SR-AUD-088, cause B-D).
+//
+// #2059 made System::Buffers::MemoryHandle's two components private, matching .NET's
+// `private void* _pointer` / `private IPinnable? _pinnable` (MemoryHandle.cs:14-16).
+// .NET publishes exactly one of them, `Pointer`, and only as a getter. This port
+// published both as mutable data members, so a caller could retarget a live handle at
+// an unrelated address, or detach its IPinnable and leak the pin, behind the owner's
+// back -- and could then call Dispose() on a handle whose pointer no longer matched
+// what was actually pinned.
+//
+// Nothing in this repository ever touched them -- measured, ZERO first-party direct
+// accesses -- so there was no first-party migration. What a CONSUMER loses is the
+// spellings that reach a public data member. Each is compiled on its own below; the
+// #else branches are the migrated spellings.
+//
+// Migration: build handles with the two-argument constructor (or take one from
+// IPinnable::Pin) and read the address with getPointerProperty(). There is no
+// replacement for reading or writing pinnable_, deliberately: .NET exposes no such
+// accessor, and a caller that needs to release the pin calls Dispose().
+//
+// NOTE what this fixture does NOT claim. #2059 also DECLINED to add
+// `~MemoryHandle(){ Dispose(); }`, because .NET's MemoryHandle is a struct with no
+// finalizer and does not unpin at scope exit either. That absence is parity, not a gap,
+// and it is pinned inside the repository by MemoryHandlePinTests rather than here --
+// a fixture can only prove that a spelling is rejected, not that a behaviour is absent.
+//
+// Records: docs/Migration-MemoryHandlePrivateRepresentation.md,
+// docs/NegativeConsumerFixtureValidation.md.
+//
+// NEGATIVE-FIXTURE: component=Buffers
+#include <type_traits>
+
+#include "System/Buffers/IPinnable.hpp"
+#include "System/Buffers/MemoryHandle.hpp"
+
+#ifndef SHARP_RUNTIME_NEGATIVE_SITE
+#define SHARP_RUNTIME_NEGATIVE_SITE 0
+#endif
+
+using System::Buffers::IPinnable;
+using System::Buffers::MemoryHandle;
+
+namespace {
+struct CountingPinnable final : IPinnable {
+    int value = 7;
+    MemoryHandle Pin(SharpRuntime::intcs) override { return MemoryHandle(&value, this); }
+    void Unpin() override {}
+};
+} // namespace
+
+int main() {
+    CountingPinnable pinnable;
+    MemoryHandle     handle = pinnable.Pin(0);
+
+#if SHARP_RUNTIME_NEGATIVE_SITE == 1
+    // NEGATIVE(memoryhandle-direct-pointer-write): is private within this context
+    //     | private
+    handle.pointer_ = nullptr;
+#else
+    handle = MemoryHandle(nullptr);
+#endif
+
+#if SHARP_RUNTIME_NEGATIVE_SITE == 2
+    // NEGATIVE(memoryhandle-direct-pointer-read): is private within this context
+    //     | private
+    void* raw = handle.pointer_;
+    (void)raw;
+#else
+    void* raw = handle.getPointerProperty();
+    (void)raw;
+#endif
+
+#if SHARP_RUNTIME_NEGATIVE_SITE == 3
+    // NEGATIVE(memoryhandle-detach-pinnable): is private within this context
+    //     | private
+    // THE SITE THAT BREAKS SILENTLY RATHER THAN LOUDLY, and the reason the member is
+    // private at all: detaching the IPinnable makes the subsequent Dispose() a no-op, so
+    // the pin leaks with no diagnostic anywhere. It compiles, it runs, and it is wrong.
+    handle.pinnable_ = nullptr;
+#else
+    // There is no migrated spelling, by design -- releasing the pin is what Dispose() is.
+    handle.Dispose();
+#endif
+
+#if SHARP_RUNTIME_NEGATIVE_SITE == 4
+    // NEGATIVE(memoryhandle-aggregate-init): no matching function
+    //     | private
+    //     | could not convert
+    //     | cannot convert
+    MemoryHandle braced{&pinnable.value, &pinnable, nullptr};
+    (void)braced;
+#else
+    MemoryHandle braced{&pinnable.value, &pinnable};
+    braced.Dispose();
+#endif
+
+    // UNCHANGED, and asserted so the fixture proves what did NOT break: both public
+    // constructors, the getter, copyability, and the size -- this is an access change and
+    // moves no layout, so no consumer needs a rebuild for it.
+    const MemoryHandle defaulted{};
+    MemoryHandle       fromPointer(&pinnable.value);
+    MemoryHandle       copied = fromPointer;
+    static_assert(std::is_copy_constructible_v<MemoryHandle>, "still copyable");
+    static_assert(sizeof(MemoryHandle) == 24, "#2059 moved no layout");
+    copied.Dispose();
+    fromPointer.Dispose();
+    return (defaulted.getPointerProperty() == nullptr) ? 0 : 1;
+}