engine(kv-cache): IKvCache.TryReserveSlot — write-into-cache primitive

[jamesburton]

Summary

Closes #278. Adds IKvCache.TryReserveSlot — a write-into-cache primitive that returns a destination span the caller writes K/V directly into, avoiding the previous "compute K/V, then copy into cache" pattern.

Test results

• New: ReserveSlotTests (437 lines).
• 4 files changed, 608 insertions.
• All existing KV-cache tests continue to pass.

Notes for review

Single-commit primitive on main. This is the precursor to the #25 direct-to-cache K/V writes PR (which stacks on this branch).

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR adds an opt-in “in-place KV write” path to IKvCache via TryReserveSlot/CommitSlot, with implementations for SimpleKvCache and PagedKvCache, plus unit tests ensuring behavior and bit-exact parity with the legacy Update path.

Changes:

• Added default IKvCache.TryReserveSlot / IKvCache.CommitSlot APIs (with safe fallbacks).
• Implemented in-place slot reservation + commit semantics in SimpleKvCache and PagedKvCache.
• Added extensive unit tests covering reservability rules and byte-identical parity vs Update.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
tests/DotLLM.Tests.Unit/Engine/KvCache/ReserveSlotTests.cs	New unit tests validating reservability and bit-exact parity for Simple/Paged caches and opt-out behavior.
src/DotLLM.Engine/KvCache/SimpleKvCache.cs	Implements contiguous in-place reservations and length commit behavior.
src/DotLLM.Engine/KvCache/PagedKvCache.cs	Implements single-block in-place reservations for paged storage and commit behavior.
src/DotLLM.Core/Attention/IKvCache.cs	Extends cache interface with opt-in slot reservation APIs and default fallbacks.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jamesburton]

Worked through all 5 Copilot review comments. Pushed as 7e6ba2f.

1. PagedKvCache.TryReserveSlot — missing layerIndex validation — accepted (with a correction).

Fixed: the (uint)layerIndex >= (uint)_numLayers guard now runs first thing in PagedKvCache.TryReserveSlot, matching SimpleKvCache.

One correction to the comment's premise though: this was never a memory-safety hole. KvBlockPool.GetKeyPtr/GetValuePtr index a managed nint[] (_keyBuffers[layerIndex]) before doing any pointer arithmetic, so an out-of-range layer already threw IndexOutOfRangeException rather than producing a wild pointer. The real problem was the wrong exception type and the inconsistency with SimpleKvCache — which is what the guard fixes.

2–4. start + seqLen int overflow (SimpleKvCache:178, PagedKvCache:200/210) — accepted.

Both caches now use the overflow-safe form:

if ((uint)start >= (uint)_maxSeqLen) return false;
if (seqLen > _maxSeqLen - start) return false;

The first check guarantees 0 <= start < _maxSeqLen, so _maxSeqLen - start is positive and cannot overflow. This also discharges comments 3 and 4 together: once the run has passed this check, start + seqLen <= _maxSeqLen, so the start + seqLen value handed to EnsureCapacity is provably non-overflowing. I kept the addition there rather than recomputing, with a comment recording why it is safe.

Practically this needs a _maxSeqLen near int.MaxValue and a ~2-billion-element positions span to trigger, so it was latent rather than live — but the subtraction form costs nothing and removes the reasoning burden.

5. NativeMemory.AlignedAlloc null check in ReserveSlotTests — accepted.

The four alloc pairs now go through a single helper:

private static nint AllocFloats(int floatCount)
{
    nint ptr = (nint)NativeMemory.AlignedAlloc((nuint)(floatCount * sizeof(float)), 64);
    Assert.True(ptr != 0, "NativeMemory.AlignedAlloc returned null.");
    return ptr;
}

so an allocation failure surfaces as a test failure instead of an AV on first write.

Also included (not requested, but fallout from fix 1):

• SimpleKvCache's layer guard moved ahead of the position checks. It previously sat after them, so an invalid layerIndex combined with non-contiguous or out-of-range positions returned false silently instead of throwing. An out-of-range layer is a caller bug, not a "cannot reserve in place" condition, so it should always throw.
• IKvCache.TryReserveSlot XML docs now state the ArgumentOutOfRangeException contract for layerIndex, so the throw-vs-return-false split is part of the documented interface rather than an implementation detail.
• Two new regression tests (Simple_TryReserveSlot_LayerIndexOutOfRange_Throws, Paged_TryReserveSlot_LayerIndexOutOfRange_Throws) covering both the >= numLayers and negative cases.

Verification: dotnet test --filter "FullyQualifiedName~KvCache|FullyQualifiedName~ReserveSlot" — 77 passed, 0 failed, 2 skipped (up from 75 passed; the 2 new guard tests). No behavioural change to any accepted-path reservation.