fix(pvc): complete restore populate handoff

[weicao]

Problem

DataProtection restore in a vCluster needs a four-step handoff between the guest target PVC, the temporary kb-populate-<target PVC UID> helper, the translated host PVCs, and the populated host PV. The previous syncer could reclaim the populated PV, synthesize guest Bound too early, or switch the host PV claimRef to the target while the populator helper was still active. The last race produced ClaimMisbound in a fresh PostgreSQL restore scene.

Change

• Keep the host restore target PVC present while the guest restore materializes and preserve the Backup data source as its placeholder.
• Sync WFFC selected-node annotations back to the guest.
• Keep guest binding ownership in DataProtection; the syncer does not write guest target/helper volumeName.
• Preserve orphaned helper host PVCs and fake PVs while handoff references are still live.
• Grant the fake-PV mode the host PV RBAC needed for claimRef handoff.
• Report the guest target PVC Bound only after the populated host PV exists and points at the exact host target PVC.
• Delay every accepted host claimRef handoff path until an uncached guest read proves:
  • exact target UID and the same non-empty volumeName;
  • target is not deleting;
  • Populating=True with terminal reason Succeed or Provisioned;
  • the exact helper PVC is NotFound (a deleting helper still counts as present).
• Use the same gate for an already-correct target claimRef, stale target UID refresh, and helper-to-target patch, so no path can bypass the populator terminal contract.

Required KubeBlocks contract

This head intentionally requires KubeBlocks DataProtection to publish a terminal Populating condition. KubeBlocks main/1.2 does this after helper cleanup (True/Succeed, with Provisioned also accepted). A legacy/custom populator that never writes this terminal condition will remain pending at the handoff gate instead of receiving an unsafe claimRef switch. Do not roll this image into such an environment without first adding the equivalent terminal condition contract.

The helper name contract remains deliberately narrow: kb-populate-<target PVC UID>. This is not generic external-populator support.

Validation

Exact head: 4b4091829b8f992b37e96356535c375441246ddf (base b98b1ae5a603fa504daf1e745d65784c5a0be0ea).

go test -count=1 ./pkg/controllers/resources/persistentvolumeclaims ./pkg/syncer/...
go test -race -count=1 ./pkg/controllers/resources/persistentvolumeclaims
go test -count=1 ./pkg/controllers/resources/...
go test -count=1 ./pkg/mappings/... ./pkg/syncer/...
git diff --check b98b1ae5a..4b4091829

All pass. Seven of the eight new focused cases fail on b98b1ae5a; the one case that stays green is the negative guard proving unrelated helpers do not over-block.

Independent XP review walked design-contract classes 1-8 and found no remaining source blocker. The reviewer also verified the KubeBlocks ordering is non-cyclic: rebind guest PV -> delete helper -> publish terminal Populating condition; none of those steps waits for the host handoff.

Independent kind Phase-B race validation at the exact head passed after the simulator was corrected to publish the real KubeBlocks terminal condition:

• helper and populated host PV survived the W5 window;
• fake PV keepalive remained effective;
• bridge, guest Bound, host Bound, and helper cleanup converged;
• data marker race-data-pr4 read back successfully;
• no test-resource residue remained after namespace cleanup.

Evidence SHA: ef09ad51e5bc5e72de0c66fdd1cb0ddfd3d3d8110b12393ddd9dae9ff742d2fc.

The first simulator run without a terminal Populating condition failed at the new gate as designed (evidence SHA f8cf56011fc35082e10b6759b07d0e9be715478ea9d5518078043c64db20bf75); this is harness-contract evidence, not a product regression.

Evidence boundary

The focused source and kind gates are green. Fresh PostgreSQL R1k runtime validation of this exact head is still N=0 and remains a separate gate. This PR is not broad restore compatibility or release-readiness evidence.

[weicao]

Phase A / Phase C runtime evidence for exact head 4b4091829b8f992b37e96356535c375441246ddf (supplements the Phase B evidence in the PR body; same environment and image identity).

Identity: local build CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -mod=vendor ./cmd/vcluster; in-pod /vcluster sha256 equals local build: 235287a36f2c1281b1ea64c1dc5606a7886a3d7062b63ab07144e72c7922ff0d. kind cluster (arm64), no-KubeBlocks simulation harness updated for the terminal Populating condition contract.

Phase A (normal KB order, script run-scenario-4b4.sh), N=1 PASS — log sha256 523f6dbb19dedec4b579187e795bef74b6dbd7093f581c4e9c92e0f49627051c:

B1_RBAC: OK
bridge_hostpv_rebound_to_target: OK
guest_target_bound: OK
host_target_bound: OK
helper_cleaned_after_convergence: OK
B3_NO_DEAD_HOOK_CM: OK
DATA_MARKER: restored-data-pr4
PHASE_A: PASS

Phase C (syncer killed inside the W5 race window, script run-phase-c-syncer-restart-4b4.sh), N=1 PASS — log sha256 92cec1988b50c70f31fc9f9da1a3522ac06b863e01b2aec6bf35e14157bd4186:

C_HOST_SIDE_SURVIVED_RESTART: yes
C_GUEST_FAKE_PV_SURVIVED_RESTART: yes
bridge: OK  guest_bound: OK  host_bound: OK  helper_cleaned: OK
DATA_MARKER: restart-data-pr4
PHASE_C: PASS

Cleanup: guest namespaces deleted; zero host PVC/PV residue beyond the vcluster data volume itself.

Boundary: kind/arm64, no-KB simulation, N=1 per phase. This is not a PG/IDC real-environment result and does not authorize release.