[YouHengfei]

Required human contributor answers

1. What outcome are you trying to achieve?

Provide the M9 PD walkthrough as maintained architecture documentation, replacing the closed, unmerged #64 and reflecting the current configuration and prefill execution contracts.

2. What is the highest-leverage variable for that outcome?

Documentation accuracy and maintainability: explain current ownership and handoff mechanics rather than retain a historical review report.

3. How will this work move that variable rather than create busywork?

The contributor approved maintaining the walkthrough in the style of docs/kv_cache_walkthrough.md, then reviewed and approved this update after #140 merged. The document explains entry-owned configuration, scheduler-driven prefill/export boundaries and resource retirement, with links to their implementations. Review findings remain separate from the living documentation.

4. Who is the customer or user, and what do they actually need?

Maintainers and RFC #111 participants reviewing PD contracts need a current description of which component owns configuration, request execution, transfer progress and safe resource release.

PR necessity and bugfix evidence

Yes: the contributor approved replacing the closed #64 with maintained in-tree documentation through this PR. This is a documentation change, not a runtime bugfix or new feature implementation.

Purpose

Refs #32 and #111. Add docs/pd_walkthrough.md and its documentation-index entry. Rebased onto main 8fbf4cd, including #140's unified model configuration and #144's wavefront prefill integration.

The walkthrough covers:

• Component ownership, entry-owned ModelConfig, spawned configuration copies and runtime-only ready messages; P/D fingerprints still verify runtime compatibility.
• Reservation, prefill, commit, receipt, activation and retirement. received triggers ack independently of compute admission.
• Scheduler-selected execution boundaries and WCPB export progress, including the distinction between intermediate depth work and exportable full-depth KV.
• Prefix asymmetry, KV layouts, bounded transfers, reservation credits and generic profiling control.
• Cancellation and asynchronous retirement: logical completion does not establish that execution storage or staging can be reused.
• Current execution restrictions, explicit pre-spawn rejection of unsupported model families, and limits on cross-geometry BF16 agreement claims.

The document describes current behavior without pinned-baseline review framing or historical defect lists. No runtime code is changed.

Test Plan

vllm-rlt Version / Commit: 0203a2e323ea5f53e959c4c5d1bf5b3d89f67258, one documentation commit based on main 8fbf4cd9d4c96a84dd64b40f4b56f61e6658d66a.

• Trace documented behavior through the current coordinator, stage client/worker, scheduler, connector and engine lifecycle code.
• Verify relative link targets and git diff --check.
• Contextual baseline check on 8fbf4cd: CPU tests for PD, transfer connectors, stage engines and split/wavefront prefill.

Test Result

• git diff --check: passed.
• All 13 relative link targets resolve.
• Baseline targeted CPU tests: 118 passed, 66 skipped in 17.08s. These results describe the base runtime, not new behavior introduced by this document.
• Final diff contains only the walkthrough and one index row. No additional runtime/GPU testing was needed for this documentation-only change; no performance or new feature-qualification claim is made.