From 5d2bc88a2e6b66978982d47cb72a35a95bb8959d Mon Sep 17 00:00:00 2001
From: Ed Hennis <ed@ripple.com>
Date: Wed, 1 Jul 2026 19:05:01 -0400
Subject: [PATCH] Document the reasons for the post-allocation assert

- Hopefully the AI bots will stop telling me to change it now.
---
 include/xrpl/basics/TaggedCache.ipp | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/include/xrpl/basics/TaggedCache.ipp b/include/xrpl/basics/TaggedCache.ipp
index 0d523feffe..7d7b9724a8 100644
--- a/include/xrpl/basics/TaggedCache.ipp
+++ b/include/xrpl/basics/TaggedCache.ipp
@@ -600,9 +600,7 @@ TaggedCache<Key, T, IsKeyCache, SharedWeakUnionPointer, SharedPointerType, Hash,
     {
         // Keep track of how many iterations are needed. Exit the loop if the number of retries gets
         // absurd. (Note that if this somehow ever happens, one more allocation will be done under
-        // lock, which is undesirable, but really should be almost impossible. Also, assert that
-        // there were fewer than 3 needed after the loop, because in a normal operating environment,
-        // even 2 is going to be unusual, and 3 shouldn't be needed.
+        // lock, which is undesirable, but really should be almost impossible.)
         std::size_t allocationIterations = 0;
         std::unique_lock lock(mutex_);
         for (auto size = cache_.size(); v.capacity() < size && allocationIterations < 20;
@@ -616,6 +614,10 @@ TaggedCache<Key, T, IsKeyCache, SharedWeakUnionPointer, SharedPointerType, Hash,
             v.reserve(size);
             ++allocationIterations;
         }
+        // In a normal operating environment, because of the padding added to size before
+        // allocating, even 2 iterations is going to be very rare. If 3 or more are ever needed,
+        // that's unusual enough that I want to know about it. Don't ask me to change it without
+        // empirical data. - Ed H.
         XRPL_ASSERT(
             allocationIterations < 3,
             "xrpl::TaggedCache::getKeys(): limited allocation iterations");