Guard MutatingBucketIterator.replace against relinking an already-linked Entry

bric3 hit the case while trying the Hashtable API: splicing in an Entry
that's still part of another chain silently corrupts it. insertHeadEntryAt
already asserted against this; add the same assertion to replace(), note
the caller contract on D1.insert's javadoc, and add a regression test.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: dougqh

internal-api/src/main/java/datadog/trace/util/Hashtable.java

@@ -253,7 +253,10 @@ public TEntry remove(@Nullable K key) {
     /**
      * Unconditionally adds {@code newEntry} ({@code true}), or {@code false} if the table is
      * already at capacity. Caller-responsible: {@code newEntry}'s key must be absent, else it lands
-     * shadowed behind the existing entry.
+     * shadowed behind the existing entry. {@code newEntry} must also be a fresh entry, not already
+     * linked into this or any other table's bucket chain -- reinserting an already-linked entry
+     * corrupts the chain it's still part of (guarded by an assertion in {@link
+     * #insertHeadEntryAt(Hashtable.Entry[], int, Hashtable.Entry)}).
      */
     public boolean insert(@Nonnull TEntry newEntry) {
       return insertHeadEntryFor(this.sizeManager, this.buckets, newEntry.keyHash, newEntry);
@@ -1802,6 +1805,8 @@ public void replace(@Nonnull TEntry replacementEntry) {
       if (oldCurEntry == null) {
         throw new IllegalStateException();
       }
+      assert replacementEntry.next() == null
+          : "Entry already linked -- inserting the same Entry instance twice corrupts the chain";
 
       Hashtable.Entry oldNext = oldCurEntry.next();
       replacementEntry.setNext(oldNext);

internal-api/src/test/java/datadog/trace/util/HashtableTest.java

@@ -10,6 +10,7 @@
 import static org.junit.jupiter.api.Assertions.assertSame;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assumptions.assumeTrue;
 
 import datadog.trace.util.Hashtable.BucketIterator;
 import datadog.trace.util.Hashtable.MutatingBucketIterator;
@@ -200,6 +201,21 @@ void insertHeadEntrySplicesAsNewHead() {
       assertSame(a, b.next());
       assertNull(a.next());
     }
+
+    @Test
+    void insertHeadEntryOfAlreadyLinkedEntryTripsAssertion() {
+      assumeTrue(assertionsEnabled(), "assert-guard test requires -ea");
+      Hashtable.State<StringIntEntry> table = Hashtable.createCapped(4);
+      Hashtable.Entry[] buckets = table.buckets;
+      StringIntEntry a = new StringIntEntry("a", 1);
+      StringIntEntry b = new StringIntEntry("b", 2);
+      Hashtable.insertHeadEntryAt(buckets, 0, a);
+      Hashtable.insertHeadEntryAt(buckets, 0, b); // chain is now b -> a, so b.next() != null
+      assertThrows(
+          AssertionError.class,
+          () -> Hashtable.insertHeadEntryAt(buckets, 1, b),
+          "re-inserting an already-linked entry corrupts the chain and must be caught");
+    }
   }
 
   // ============ Deprecated Support facade ============
@@ -923,4 +939,10 @@ void tableSizeManagerOperatesOnItsOwnBuckets() {
       assertNull(table.buckets[0]);
     }
   }
+
+  private static boolean assertionsEnabled() {
+    boolean enabled = false;
+    assert enabled = true;
+    return enabled;
+  }
 }