smolvm_protocol/forkpoint.rs
1//! Stable guest paths used to coordinate a live branch.
2
3/// Directory privately inherited by each restored VM.
4pub const STATE_DIR: &str = "/run/smolvm/forkpoint";
5
6/// Marker written by the workload when it reaches a safe fork boundary.
7pub const READY_PATH: &str = "/run/smolvm/forkpoint/ready";
8
9/// First line of every supported forkpoint readiness marker.
10pub const READY_VERSION: &str = "smolvm-forkpoint-v1";
11
12/// Prefix of the per-invocation token in a readiness marker. The token lets a
13/// releaser distinguish a new forkpoint from the previous helper's marker.
14pub const GENERATION_PREFIX: &str = "generation=";
15
16/// Optional readiness-marker capability requesting eager clone module loading.
17pub const CUDA_PRELOAD_MODULES_HINT: &str = "cuda-preload-modules";
18
19/// Agent capability required by readiness-gated fork-pool leases.
20pub const WORKER_READY_CAPABILITY: &str = "fork-worker-ready-v1";
21
22/// Agent capability for parking an idle branchpoint until the host arms it.
23pub const ARMING_CAPABILITY: &str = "branchpoint-arming-v1";
24
25/// Host marker that asks the branchpoint helper to enter its capture-safe loop.
26pub const ARM_PATH: &str = "/run/smolvm/forkpoint/arm";
27
28/// Helper acknowledgement that it is safe for the host to capture the vCPU.
29pub const ARMED_PATH: &str = "/run/smolvm/forkpoint/armed";
30
31/// Generation-addressed arm marker prefix.
32pub const ARM_PREFIX: &str = "smolvm-forkpoint-arm-v1:";
33
34/// Generation-addressed arm acknowledgement prefix.
35pub const ARMED_PREFIX: &str = "smolvm-forkpoint-armed-v1:";
36
37/// Marker written after a restored clone can safely enter ordinary timed waits.
38pub const RESTORED_PATH: &str = "/run/smolvm/forkpoint/restored";
39
40/// Container ID inherited with a live VM snapshot.
41///
42/// The restored container remains the owner of the workload's live process
43/// state, but new commands must join its namespaces directly: a post-restore
44/// `crun exec` can fail after trivial commands have already succeeded.
45pub const RESTORED_CONTAINER_PATH: &str = "/run/smolvm/forkpoint/restored-container";
46
47/// Marker written by the host after a clone is ready to resume.
48pub const RELEASE_PATH: &str = "/run/smolvm/forkpoint/release";
49
50/// Release token used before generation-addressed forkpoints. Accepting it in
51/// newer guests keeps independently-updated host and agent packages compatible.
52pub const LEGACY_RELEASE_TOKEN: &str = "smolvm-forkpoint-release-v1";
53
54/// Prefix of a generation-addressed release marker.
55pub const RELEASE_PREFIX: &str = "smolvm-forkpoint-release-v2:";
56
57/// Marker written after a released worker finishes clone-local preparation.
58pub const WORKER_READY_PATH: &str = "/run/smolvm/forkpoint/worker-ready";
59
60/// Per-clone environment installed by the host before workload release.
61pub const FORK_ENV_PATH: &str = "/etc/smolvm/fork-env";
62
63/// Preferred branch-lifecycle alias for [`FORK_ENV_PATH`].
64pub const BRANCH_ENV_PATH: &str = "/etc/smolvm/branch-env";
65
66/// Host-generated readiness token delivered through [`FORK_ENV_PATH`].
67pub const WORKER_READY_TOKEN_ENV: &str = "SMOLVM_WORKER_READY_TOKEN";
68
69/// Workload-facing helper installed in bare VMs and workload containers.
70pub const HELPER_PATH: &str = "/usr/local/bin/smolvm-fork-ready";
71
72/// Preferred branch-lifecycle alias for [`HELPER_PATH`].
73pub const BRANCH_HELPER_PATH: &str = "/usr/local/bin/smolvm-branch-ready";
74
75/// Helper used by a released workload after clone-local preparation finishes.
76pub const WORKER_READY_HELPER_PATH: &str = "/usr/local/bin/smolvm-worker-ready";