[RWKV] Integrate state refs with request lifecycle

[w1c2j3]

Motivation

The cache primitives in #51 can hold an RWKV snapshot, but they do not define when a request may read it, when a child snapshot becomes visible, or what happens on abort and preemption. A correct continuation must restore state before the new delta is processed, retain the source while it is in use, and publish the child only after a successful terminal outcome.

RWKV adds one subtle requirement: the sampled terminal token can leave the scheduler before the model has consumed it. Saving only the resident tensor state would therefore lose a token at the next turn. The lifecycle needs to carry that unprocessed tail alongside the snapshot.

What changed

• thread read ref, read lease, write ref, terminal reason, and unprocessed tail metadata through request, scheduler output, model runner, and model-state interfaces
• restore the parent snapshot when the request acquires its RWKV state row
• hold a read lease for the request lifetime so a parent cannot be dropped during continuation
• consume a preflight write reservation at admission and commit the child snapshot only for successful terminal reasons
• retain sampled-but-unprocessed terminal tokens in the committed record for the next turn
• release reservations and leases on failed admission, abort, preemption, and other non-committable exits
• bypass both generic prefix-cache reads and writes for restored requests so KV-prefix state and RWKV recurrent state cannot be mixed
• keep non-RWKV model-state implementations source-compatible with the richer removal contract
• add focused tests for exact tensor restore/commit, tail propagation, terminal metadata, rollback, lease retention, and prefix-cache isolation

Scope and design boundary

This layer consumes internal request metadata only. It does not create public routes, generate client refs, or alter chat templates; those serving concerns are isolated in #53.

Stack

This is PR 2 of a four-PR stack:

• base and cache primitives: [RWKV] Add process-local state cache primitives #51
• OpenAI API: [RWKV] Expose process-local stateful chat API #53
• benchmark and user guide: [RWKV] Add stateful chat replay benchmark and guide #54

Duplicate-work check

I searched open PRs in both rwkv-rs/vllm-rwkv and vllm-project/vllm for RWKV state ref, RWKV state cache, and RWKV stateful chat. No open PR implements this state-reference request lifecycle. Upstream PRs vllm-project#48686 and vllm-project#50077 cover native RWKV7 model/serving work, not detached state continuation. No issue number was provided for an issue-specific lookup.

Tests

• changed-file pre-commit suite — passed
• pre-commit run mypy-3.12 --all-files --hook-stage manual — passed
• .venv/bin/python -m pytest tests/model_executor/models/test_rwkv7.py -k "state_ref or prefix_state_cache or cached_recurrence or model_state" -v — 39 passed
• scheduler completion/tail metadata tests — 2 passed using a process-local validation stub because the reduced RWKV build profile intentionally rejects the OPT fixture model
• .venv/bin/python -m pytest tests/v1/core/test_prefix_caching.py -k rwkv_state_restore -v — 1 passed
• the streaming-input runner suite was attempted, but its two fixtures require UVA and fail during setup in this auxiliary worktree; neither reaches the changed request-removal path

Model evaluation

End-to-end stack validation is reported in #53 and #54. In the strict three-turn run at 6 output tokens per turn, all 3 token sequences matched exact full-token replay, prompt processing fell from 177 to 76 tokens, and the final cache audit found no leaked refs, bytes, reservations, or prepared reads. The longer-output limitation is disclosed in those follow-up PRs.

AI assistance

This change was developed with OpenAI Codex assistance. The human submitter must review and understand every changed line before merge.

[github-actions]

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

PRs do not trigger a full CI run by default. Reviewers with write access and configured trusted contributors can comment /ci run whenever CI signals are needed.

Once the PR is approved or has the ready label, the PR author can also use /ci run or /ci retry. New commits do not start CI automatically.

If you have any questions, please reach out to us on Slack at https://slack.vllm.ai.

Agent Guidelines

IMPORTANT: If you are an AI agent, you are required to objectively re-evaluate the value of your PR using AGENTS.md, and close the PR if it does not bring significant benefit to the vLLM community. Failure to do so may result in an immediate ban.

🚀