[thxCode]

What type of PR is this?

/kind enhancement
/area worker

What this PR does / why we need it:

• Allows ordinary ModelDeployment.spec.roles[] updates to size, resources, instanceType, and command through whole-replica replacement with fresh Kueue admission.
• Preserves role identity, untouched Prefill/Decode siblings, deployed routing, leader selection, and peer DNS while old members remain during replacement.
• Retains peer Services for desired and still-standing surplus ordinals, then prunes them after the last member leaves.
• Adds case 115 scheduling coverage for queued edits, size changes, whole-card/slice transitions, command updates, P/D sibling identity, and ownership-safe cleanup after an ambiguous create response.
• Keeps Elastic EP and hardware-specific restrictions explicit in the documentation.

Validation:

• make test passed for the full repository with race detection, shuffled tests, and coverage.
• make lint, make lint docs, make lint agents-shell, make build, make generate (two passes), and git diff --check passed.
• Independent Spec and Standards reviews found no confirmed Spec or Service-rendering defect. The final local review fixed the case 115 ambiguous-create cleanup gap before this PR.
• Runtime validation passed the applicable role-update and inference legs. Ascend, native RDMA, Elastic EP replacement, and unavailable hardware geometry remain documented limits.

Which issue(s) this PR links to:

NONE

Special notes for your reviewer:

• member-index=0 is shape-dependent: ordinary multi-member roles select the leader, External DP selects qualified ranks, and mixed old/new configurations use the deployed member shape until replacement completes.
• Runtime evidence includes real Kubernetes/Kueue object transitions and serving checks. Placeholder legs do not claim engine inference or serving continuity.
• The Spec records only role-mutability evidence and its limits; unrelated campaign failures remain outside the Spec.

Does this PR introduce a user-facing change?

ModelDeployment roles can update size, resources, instanceType, and command through safe whole-replica replacement while preserving role identity and peer routing during rollout.

[gpustack-code-review]

✅ OpenCodeReview: Review complete: 0 finding(s) across 1 selected item(s).

Reviewed 21b4c35..e88f1e2 only; earlier commits in this PR were reviewed in a previous run.

[thxCode]

Addressed in ca03323 and 2e85bc2.

Fixed:

• model_deployment_pod_group.go: unreadable External-DP reading now holds membership (tri-state).
• model_deployment_replacement_slot.go: server read failures are returned as errors, so the slot requeues.
• model_deployment_service.go: the front Service gate reads only the front role's standing members.
• admission.md: the stop gate is stated for the whole template, with spec.volume as the only unconditional exception.
• elastic-ep.md: the Limitations entry now points to the section above instead of repeating the frozen fields.
• status.md: the rollout rule is left to deployment.md#rollout-behavior.
• prefill-decode.md: the shared-document mechanism now lives in deployment.md only.

Not changed here: the two performance comments (per-pass uncached Workload lists and per-role Service reads). The uncached reads guard against informer lag in the replacement window, so replacing them needs its own change. Follow-up.

Also added the missing Signed-off-by to one earlier commit; the branch history was rewritten with no content change. Tests: go test ./pkg/worker/..., make lint and make lint docs pass.

[thxCode]

Addressed the latest review round (8 inline threads and 6 summary-routed findings, 14 in total, matching the bot's count). The fixes are committed as fixups of the commits that own the code and will be pushed as a fast-forward.

Fixed

• Initial-queue check (model_deployment_initial_queue.go): cached status that already shows a node assignment or container status now refuses the replica before any API-server Get. Test added.
• Replacement slot cleanup (model_deployment_replacement_slot.go): replacementWorkloadDeletes deletes only the Workload the slot captured; the unreachable uncaptured-delete branch and its unused parameters are removed. Test added.
• Retirement hold reason (model_deployment_retirement.go): a replica with no members now reports the replica has no members to read instead of a missing engine container. Test added.
• Rollout log (model_deployment.go): the broken-first path now logs short of its members as its reason.
• kubectl-shim: trap collapsed to a single expansion, same behavior.
• docs/modules/kv-cache/pool.md: the deletion sentence moved after the reason list so the paragraph reads as one unit.

Not changed, with reasons (replied in each thread)

• Index-out-of-range panic at model_deployment.go:589: desired[role] is a map keyed by ordinal, so a missing ordinal returns nil and does not panic; verified.
• Namespace-wide Workload lists (two threads): Kueue copies only configured labelKeysToCopy onto the Workload and this repo configures none, so the suggested label filter would match nothing; the vacancy read also has to come from the API server.
• Uncached pod list before the Service sync: deliberate, documented in the code, to avoid retiring peer records of members still running.
• poolRef re-judge in the webhook: spec.kvCache is rejected on update by the identity check, so it cannot change.

Already satisfied (no change): the three reminders to include regression tests and regenerated output. Tests for those contracts are in the PR, and this round changes no API types or markers.

Checks run locally: make lint (0 issues) and go test ./pkg/worker/... ./api/worker/... pass. make generate cannot run in this worktree because the generators require a checkout path ending in gpustack.ai/gpustack; CI's verify-generated covers it.

Resolved the two threads whose fixes landed; the others stay open for the reviewer.

[thxCode]

Addressed the follow-up review on the previous fixups (1 inline thread, no findings routed to the summary).

Fixed

• Replacement slot cleanup (model_deployment_replacement_slot.go): a slot that captured no Workload UID, because the Workload had not reached the informer yet, can now still release it when the Workload names a captured member as an owner. Name matches and ownerless Workloads remain untouched. Added an end-to-end test of cleanReplacementSlot for the empty-WorkloadUID case, and confirmed it fails without the fix.

Verification

• make lint reports 0 issues, go test ./pkg/worker/... passes, and make generate leaves the tree clean on the fix commit (the commit after it only adds a test).