📜 Codex: Documentation Synchronization and Architectural Articulation

.jules/codex.md

@@ -1,3 +1,5 @@
-## 2026-06-10 - Architectural Execution Flow Articulation
-**Observation:** The README.md documentation exhibited a deficit regarding the explicit articulation of the underlying multi-tiered allocation strategy (TLS cache, fast slot, shared array, and fallback). It lacked a clear delineation of the internal mechanics and did not explicitly state the absence of planned hypothetical enhancements, leaving room for speculative assumptions. Code examples were also not utilizing contemporary .NET features like target-typed `new()`.
-**Strategic Action:** Synchronized the README.md to explicitly articulate the architectural execution flow, separating implemented capabilities from hypotheses. Updated code examples to leverage modern C# syntax.
+## 2026-08-10 - Architectural Execution Flow & Code Examples
+
+**Observation:** The README.md exhibited documentation drift regarding the Architectural Execution Flow. Specifically, the "Thread-Local Storage (TLS) Cache" and "Rotating Array Slots" tiers of the multi-tiered allocation strategy were missing from the public documentation, requiring developers to speculate on internal mechanics. Additionally, code examples were obsolete, failing to utilize contemporary .NET 9.0/10.0+ target-typed `new()` syntax.
+
+**Strategic Action:** Synchronized the README.md by articulating the precise multi-tiered allocation strategy (TLS Cache -> Fast Slot -> Rotating Array Slots -> Factory Fallback), distinctly separating established framework capabilities from planned future enhancements. Updated all C# code examples to employ target-typed `new()` and structurally validated the examples via compilation prior to submission.

README.md

@@ -33,7 +33,7 @@ Basic pooling of an object, e.g., `StringBuilder`:
 using Tedd;
 using System.Text;
 
-var pool = new ObjectPool<StringBuilder>(
+ObjectPool<StringBuilder> pool = new(
     factory: () => new(capacity: 256),
     cleanup: sb => sb.Clear(),           // reset before publishing back
     size: 64                              // total pool slots
@@ -86,7 +86,7 @@ finally
 ### 1) Simple allocate/free
 
 ```csharp
-var pool = new ObjectPool<byte[]>(
+ObjectPool<byte[]> pool = new(
     factory: () => new byte[4096],
     cleanup: _ => { /* optional reset */ },
     size: 128
@@ -138,7 +138,7 @@ pool.Prefill(count: 32);
 ### 5) Dispose overflow when full (for IDisposable)
 
 ```csharp
-var socketPool = new ObjectPool<System.Net.Sockets.Socket>(
+ObjectPool<System.Net.Sockets.Socket> socketPool = new(
     factory: () => new(System.Net.Sockets.SocketType.Stream, System.Net.Sockets.ProtocolType.Tcp),
     cleanup: s => { /* reset if applicable */ },
     size: 32,
@@ -167,7 +167,9 @@ var socketPool = new ObjectPool<System.Net.Sockets.Socket>(
 
 Tedd.ObjectPool utilizes a multi-tiered allocation strategy designed to minimize lock contention and interlocked operations on hot paths:
 
+1. **Thread-Local Storage (TLS) Cache:** The most performant path. Each thread possesses a dedicated single-item cache. During allocation, the pool first checks this cache, requiring zero interlocked operations or memory barriers. During deallocation, if the thread's TLS slot is empty, the object is deposited here.
 2. **Fast Slot (`_firstItem`):** If the TLS cache is empty during allocation, the pool attempts an optimistic read and a single CAS operation against a dedicated, highly-contended "fast slot". During deallocation (when TLS is already occupied), the pool publishes to the fast slot using `Volatile.Read`/`Volatile.Write` when it is observed empty.
+3. **Rotating Array Slots:** If the fast slot is occupied or unavailable during allocation, the pool probes a backing array utilizing a rotating index to spread contention and mitigate cache-line ping-pong. During deallocation, if the fast slot is occupied, the pool traverses the array from a rotating index and publishes the object to the first empty slot encountered.
 4. **Factory Fallback / Overflow:** If the array is exhausted during allocation, a new instance is instantiated via the provided delegate. During deallocation, if the pool is at maximum capacity, the object is either dropped for garbage collection or explicitly disposed (if `disposeWhenFull` is configured and the type implements `IDisposable`).
 
 *Note: The architecture described above reflects the current implementation. There are currently no speculative future enhancements (hypotheses) planned for the core execution flow.*

src/Tedd.ObjectPool.Tests/AegisCoverageTests.cs

@@ -90,6 +90,7 @@ public void Prefill_WhenFastSlotOccupied_ShouldPopulateArraySlots()
 
         // 2 objects from manual allocation + 5 from prefill
         Assert.Equal(7, createCount);
+    }
 
     [Fact]
     public void Prefill_WhenSomeArraySlotsOccupied_ShouldSkipOccupiedSlots()