PLATINUM DOCS

Shared Volume checkpoint recovery

Shared Volume checkpoint recovery

Live-RW checkpoints keep the existing filesystem-freeze contract: every writer attachment must freeze its still-mounted guest filesystem, fence its host export, and flush before the control plane clones the volume. An unsupported guest FIFREEZE is a failed checkpoint, not permission to clone an active writer.

The host distinguishes a definite EOPNOTSUPP response from a lost response. The former writes a durable aborted/noFreeze tombstone; the latter retains the freezing barrier until an exact cancellation proves recovery. Guest mounts and writer processes are never replaced by an unmount fallback.

Cancellation uses the original attachment identity, epoch, checkpoint lease and quiesceOperationId. Its own operation ID becomes durable before any mutation. It can resume each legacy freeze phase and replay an interrupted resuming phase. A pre-start cancellation records a no-effect tombstone, preventing the delayed original quiesce from freezing a released attachment. Repeated completed resume proves the transport but does not issue another thaw.

Before releasing writes, the host proves the persisted daemon PID/start, scope, socket, device, guest mount and actual export mode. It holds root-recovery admission against the exact root-client generation through thaw. A live guest cannot be made writable while root recovery is active.

Deleted guests use a separate no-write proof. An authorized sandbox.delete cleanup or retry records the exact checkpoint's guest-deleted evidence only after the VM is absent from both the agent and a complete process inventory, all attachment scopes are gone, and the export is absent. This also covers legacy checkpoint records whose attachment metadata an older agent already removed. Exact cancellation re-proves those absences and retires the checkpoint without requiring a writable root client or recreating a guest.

If quiesce never created a barrier, cancellation cannot recover identity from a deleted attachment's missing metadata. The authorized sandbox.delete handler therefore durably records its command and sandbox identity after cleanup and a complete no-VM proof. Cancellation may use that record to create the exact original quiesce/lease/epoch tombstone, but must still re-prove the current VM, attachment scopes and export absent. Missing metadata, an absent VM alone, or an unreadable deletion record never grants this authority. Deletion records live outside sandbox directories and are retained for delayed command recovery.

Unknown protocols, unreadable inventories, mismatched epochs/leases and uncertain transport remain fenced. A process-inventory permission or I/O error is never proof that a VM died.

Behavioral regression coverage lives in hosts/host-agent/cmd/host-agent/juicefs_checkpoint_recovery_test.go: every freeze phase, interrupted resume, cancellation before delivery, unsupported versus ambiguous ioctl results, stale identities, root recovery, deleted legacy guests, receipt binding and unreadable process inventory. These tests do not establish that virtio-fs supports transparent freeze on a particular guest kernel; that requires the real live-writer acceptance rig.