Add the off-graph KV-cache cell layout to the neutral C++ layer

[kiymetakdemir]

Summary

Adds the cell layout to the neutral C++ cache. Cells are addressed absolutely: each holds a position and a bitset of the sequences that own it, so a sequence need not be contiguous, a fork sets a second bit instead of copying K/V, and a cell frees when its bitset empties.

plan() places a step's tokens once and every later layer of that forward reuses the placement. It classifies: a single sequence appending a contiguous run at the tail of a window it owns outright gets a fused kind and a run write; anything else
— multi-sequence, forks, holes from removals — gets each token's cell plus a dense mask. Layers may window differently, so the mask is memoized per policy.

A step is declared before the forward through begin_step, which is also the admission gate: it reports whether the tokens fit before any compute is spent. A step may only extend its sequences, and one that would rewrite a position a sequence still holds is refused rather than stored twice.

Nothing constructs a CellCache yet — this is the neutral layer only. The existing SequenceCache is untouched behaviourally.

Files

• extension/llm/cache/cache.h — CacheControl factored out of SequenceControl to hold can_extend/capacity/clear; new BatchControl (the sequence verbs) and CellPlanner faces; MaskKind; the four as_* accessors now default to nullptr so a cache exposes only the faces it has.
• extension/llm/cache/cell_cache.h — new. CellStepPlan, CellPlanner, CellCache: placement, the seq verbs, classification, and the per-policy mask.
• extension/llm/cache/test/cache_test.cpp — 9 cell tests.

Testing

cmake --build cmake-out --target extension_llm_cache_test && ctest --test-dir cmake-out -R extension_llm_cache --output-on-failure

Covers the fused path, a second sequence forcing an explicit mask, one plan shared
across layers, a fork sharing cells and the refcounted free, ranged removal, holes
giving up the fused path, a rejected rewrite, layers sharing a window sharing a
plan, and the step protocol.

[pytorch-bot]

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/21902

• 📄 Preview Python docs built from this PR

Note: Links to docs will display an error until the docs builds have been completed.

✅ No Failures

As of commit 12796fa with merge base c461421 ():
💚 Looks good so far! There are no failures yet. 💚

This comment was automatically generated by Dr. CI and updates every 15 minutes.

[github-actions]

This PR needs a release notes: label

If your change should be included in the release notes (i.e. would users of this library care about this change?), please use a label starting with release notes:. This helps us keep track and include your important work in the next release notes.

To add a label, you can comment to pytorchbot, for example
@pytorchbot label "release notes: none"

For more information, see
https://github.com/pytorch/pytorch/wiki/PyTorch-AutoLabel-Bot#why-categorize-for-release-notes-and-how-does-it-work.