✨ add bytes32 circular buffer lib

[aodhgan]

Description

Summary

Adds a gas-lean circular (ring) buffer for bytes32: LibCircularBuffer.

Highlights

• Packed meta (1 slot): cap:64 | size:64 | head:128 (head masked to 128b).
• Power-of-two capacity with mask = cap - 1 for O(1) wrap-around.
• Fixed backing array (bytes32[]) sized at initialize.
• Solady-style reverts via literal selectors: AlreadyInitialized, NotPowerOfTwo, NotInitialized, Empty, OutOfBounds.

API

initialize(cap), push(bytes32) -> bool overwritten, pushN(bytes32[]) -> uint overwritten, pop(), shift(), at(i), peekFirst(), peekLast(), size(), capacity(), isFull(), clear().

Tests

Covers init guards, overwrite semantics, FIFO/LIFO ops, bounds/empty reverts, pushN (no-op, overwrite, multi-wrap), and small-sequence fuzzing. All pass locally.

Gas

Minimized SLOAD/SSTORE via single-slot meta; pushN writes directly from calldata in a tight loop.

Checklist

Ensure you completed all of the steps below before submitting your pull request:

• [x] Ran forge fmt?
• [x] Ran forge test?

Pull requests with an incomplete checklist will be thrown out.