Make LRU prefix caching eviction policy only evict child blocks

[santhnm2]

• I, the PR author, have personally reviewed every line of this PR.

What does this PR do?

The LRU prefix eviction policy only considered timestamps when selecting block to evict, but this could lead to parent blocks being evicted and leaving holes in the prefix chain. Instead, this PR ensures that parent <-> child relationships are taken into account by the LRU eviction policy so that only leaf node blocks are evicted. This PR also makes ref-count updates happen BEFORE allocation rather than AFTER allocation so that pending matched blocks are not accidentally evicted because their ref-counts were 0.

⚠️ For major changes (either in lines of code or in its impact), please make sure to first share a design doc with the team. If you're unsure what's the best way to do so, contact @NVIDIA/mcore-oncall.

Issue tracking

For PRs from open-source community contributors:

• New features: a linked issue is required. Please open a feature request and reference it here before submitting the PR.
• Small updates (bug fixes, minor improvements): a linked issue is recommended and will accelerate the PR review process.

Linked issue:

Contribution process

Pre-checks

• I have added relevant unit tests
• I have added relevant functional tests
• I have added proper typing to my code Typing guidelines
• I have added relevant documentation
• I have run the autoformatter.sh on my PR

Code review

Feel free to message or comment @NVIDIA/mcore-oncall to help accelerate your merge into main. The less complex your PR is, the faster it will be approved and merged!

All PRs start as draft. If you open a non-draft PR, it will be automatically converted to draft.

Step 1: Mark PR as "Ready for Review"

1. When your PR is ready, click Ready for Review.
2. An oncall reviewer is auto-assigned and expert reviewers are notified based on your changes.
   • Some PRs may jump straight to step 2. This is determined by .github/CODEOWNERS.

⚠️ Only mark as ready once merge-conflicts are resolved and the CI is passing.
Final Review might get declined if these requirements are not fulfilled.

Step 2: Final Review

For PRs that change megatron/core, once all expert reviewers have approved, the Final Review label is applied automatically and final reviewers are assigned.

For PRs outside megatron/core, this step is skipped.

Step 3: Approved

Once all required reviewers have approved, the Approved label is applied automatically.

Merge

Any member of mcore-engineers will be able to merge your PR.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[santhnm2]

/claude strict-review

[santhnm2]

/ok to test 0fd9e62

[claude]

Strict Review Summary

Findings: CRITICAL: 0 · IMPORTANT: 2 · SUGGESTION: 0

This is a well-constructed fix. The core eviction algorithm — keying each cached block by its subtree-max timestamp with a depth tie-break so children always precede parents in the eviction order — is sound, and the parent-chain invariant it preserves is exactly what _find_kv_match_count relies on. The cycle-safety cap, ref-count rollback on failed allocation, and the reset/deregister handling of block_parent_hashes are all correct. Test coverage (regression, cascade, branching, cycle-termination, and a randomized property test) is thorough. All newly introduced identifiers have real use paths.

Most impactful findings

1. [IMPORTANT] reserved_evictable=len(matched_block_ids) over-counts shared matched blocks (dynamic_context.py:2889). Matched prefix blocks already pinned by an in-flight request (ref_count > 0) were never part of get_evictable_block_count(), yet the full match length is subtracted from it. This under-reports availability and can make check_availability defer a request that add_request could actually satisfy — a scheduling/throughput regression concentrated in the shared-prefix workload prefix caching is meant to accelerate. Reserve only matched blocks currently at ref_count == 0.

2. [IMPORTANT] Eviction hot-path cost (kv_block_allocator.py:438). The new iterative subtree-max/depth fixpoint runs on every saturated allocation and recomputes over all cached blocks each call. The early-break keeps normal iteration counts low, but it is worth confirming latency under a full-cache benchmark and short-circuiting the no-cached-parent case back to the plain argsort.

Risk assessment

Low-to-moderate. No correctness or backward-compatibility regressions found — the new parent_hashes/reserved_evictable arguments are optional and default to prior behavior. Finding 1 is a schedulability/throughput concern rather than a data-correctness bug; finding 2 is a latency watch-item. Neither blocks merge, but finding 1 is worth addressing to avoid silently leaving cache capacity unused.

[santhnm2]

/ok to test 90b8f29

[santhnm2]

/ok to test 646b343