Add segment reader pinning (refcount + RAII item guards)

[brayniac]

Summary

First step of making segcache concurrent-safe (and a latent bug fix today): an Item holds a raw pointer into segment memory with no lifetime tie, so a held Item could be silently invalidated by eviction — in-place compact() memmoves, copy_into relocation, or segment recycling — triggered by subsequent cache calls. This ports crucible's reader-pinning machinery: a per-segment ref_count with a two-phase acquire protocol, and an RAII SegmentGuard carried by every Item, so a segment cannot be touched while readers hold items into it.

Archaeology: Segment::clear still carries the comment "skips over seg_wait_refcount … because no threading" — the original implementation had exactly this wait, dropped in the single-threaded port. This restores it in crucible's form.

Design

• SegmentHeader gains ref_count: AtomicU32 (fits in padding, still 64 bytes) with crucible's two-phase acquisition: check state → increment → re-check → back out on failure. Items acquired via the four read paths (get, get_no_freq_incr, wrapping_add, saturating_sub) carry the guard.
• can_evict() requires zero readers, which gates every eviction selection path (Random/Fifo/Cte/Util ranking, merge chains, S3-FIFO); clear_segment fails cleanly on a pinned segment (covers RandomFifo); push_free debug-asserts the invariant.
• TtlBucket::{expire, clear} become cursor walks: every visited segment is drained from the hashtable, but pinned segments stay linked and are reclaimed by a later pass once readers drop — approximating crucible's AwaitingRelease handoff until the full segment state machine is ported (next step in the concurrency sequence). reserve no longer spins on an inaccessible tail (newly reachable state); it expands past it.
• A new segment_pinned_skip metric counts deferred reclamations.

Eviction-side internals (which hold &mut Segments) intentionally keep using unpinned access; the writer-side CAS state transitions arrive with the state-machine port, as noted in the loom model comments.

Testing

• Two loom models for the acquire protocol (two readers racing the eviction gate; acquisition fails in all interleavings once draining).
• Behavioral tests: a pinned segment survives ~10× heap of Fifo eviction churn with byte-stable value and unchanged CAS token (location + generation); items held across clear() stay readable while the hashtable drains, and a later clear() reclaims; numeric-op items pin like any other.
• All three behavioral tests verified to fail when ref_count() is neutralized to always return 0 (gates blind) and with the can_evict() gate removed.
• cargo test -p segcache (53 tests), --features debug, loom suite (10 models), workspace incl. doctests, clippy --all-targets --all-features -- -D warnings, fmt --check all green.

Sequencing

Built on #24's generation tokens (rebased onto main post-merge). Next steps in the concurrency sequence: segment state machine (crucible's 9 states, replacing plain state stores with CAS transitions and adding the AwaitingRelease deferred-release handoff), then the lock-free free queue and concurrent reserve path.

🤖 Generated with Claude Code