[TRTLLM-13969][perf] Optimize M3 head-mismatched KV transfer

[peihu-nv]

@coderabbitai summary

Description

This PR is stacked on the MiniMax M3 disaggregated-serving enablement branch:
peihengh/trtllm-13969-minimax-m3-disagg.

Generic native bounce (NVIDIA#15618) provides the transfer-performance foundation by
gathering fragmented KV data into a contiguous buffer and issuing a coalesced
NIXL write. Enabling it unchanged is not safe for MiniMax M3 because M3 combines
head-sharded NHD K/V with a replicated INDEX_KEY side cache:

• Generic bounce can under-reserve for M3's mapped pool geometry.
• TEP/DEP fan-in cannot split replicated owner-only INDEX_KEY bytes equally
  among writers.
• The non-bounce head-mismatched path materializes roughly one million small
  transfer fragments for an exact-8K request.

This change teaches the bounce path about MiniMax M3's V2 pool layout:

• computes receiver capacity from actual mapped pool geometry;
• elects one owner for replicated pools while preserving equal fan-in sections;
• supports the post-review V2 PoolBufferMapper path, not only the legacy
  NHDHeadMismatchMapper path;
• replaces materialized pointer tables for NHD sections with compact analytic
  gather/scatter specs;
• rejects oversized or incompatible transfers instead of accessing memory
  outside a reservation.

The optimization remains opt-in behind TRTLLM_KV_BOUNCE_STRUCTURED_NHD=1;
default behavior is unchanged.

After the pool-level-view refactor in the base MiniMax PR, structured staging
now reports sections=1 for the coalesced V2 pool view instead of the older
per-layer sections=60. That is expected and is the desired lower-view-count
behavior.

Latest exact-8K MSA DEP2→TEP2 comparison on GB300:

Metric	A: no bounce	B: generic bounce	C: this PR
E2E mean	40,047.407 ms	30,686.938 ms	30,847.710 ms
Warm transfer latency, peer 0	3,451.520 ms	1.431 ms	1.294 ms
Warm transfer latency, peer 1	3,434.705 ms	1.299 ms	1.212 ms
Warm sender task, peer 0	3,463.561 ms	23.115 ms	10.028 ms
Warm sender task, peer 1	6,905.636 ms	38.496 ms	16.117 ms

C engaged structured staging successfully:

[kv-bounce] structured NHD staging engaged (sections=1, direct_rest=False, expected_transfers=2)

Test Coverage

• Pre-commit on commit af6641bd8e passed, including Ruff, formatting, DCO,
  diff --check, and repository hooks.
• Lyris GB300 focused regression (2326035):
  • 5 passed, 43 warnings in 32.55s
  • Covers PoolBufferMapper structured staging, V2
    buffer_entries/buffer_roles/buffer_mapper_kinds dispatch, and
    transfer.py consuming the V2 structured-staging interface.
• Lyris GB300 exact-8K MSA C E2E (2326036):
  • two measured DEP2→TEP2 requests completed;
  • structured staging engaged with sections=1, direct_rest=False;
  • no Invalid role, data mismatch, tail rejection, event-loop failure,
    TypeError, or bad-request marker was present.
• Latest A/B/C exact-8K MSA comparison:
  • A no bounce: 2325921
  • B generic bounce: 2325923
  • C structured: 2326036

Note: the exact-8K perf harness currently sets max_num_tokens=8192, equal to
the prompt length, while requesting SamplingParams(max_tokens=1). Those timing
runs validate prefill/KV-transfer behavior, not generation quality. Generation
quality is covered by the separate 32-token MSA functional run and will be
rechecked with a non-empty decode-budget quality run.

PR Checklist

Please review the following before submitting your PR:

• PR description clearly explains what and why. If using CodeRabbit's summary, please make sure it makes sense.

• PR Follows TRT-LLM CODING GUIDELINES to the best of your knowledge.

• Test cases are provided for new code paths (see test instructions)

• If PR introduces API changes, an appropriate PR label is added - either api-compatible or api-breaking. For api-breaking, include BREAKING in the PR title.

• Any new dependencies have been scanned for license and vulnerabilities

• CODEOWNERS updated if ownership changes

• Documentation updated as needed

• Update tava architecture diagram if there is a significant design change in PR.

• The reviewers assigned automatically/manually are appropriate for the PR.

• Please check this after reviewing the above items as appropriate for this PR.

GitHub Bot Help

To see a list of available CI bot commands, please comment /bot help.

[peihu-nv]

Superseded by direct push to brb-nv:feat/branch_m3.

Final side-branch commits:

• 43c9c93 [TRTLLM-13969][fix] Address MiniMax M3 pool-view review comments
• d8069ae [TRTLLM-13969][perf] Optimize MiniMax M3 disagg bounce transfer

The C bounce changes were squashed and validated on Lyris with MiniMax M3 MSA DEP2→TEP2 disagg, including structured bounce enabled with 1024 MiB.