Repository navigation
ActorTemplate: replace on_pause/on_commit/on_resume with capture_scope and minimum_scope #2102
Description
Motivation
Part of actor lifecycle v2. The contract we want is
Every actor must be bootable from its OCI image + its volumes alone; anything not reconstructible that way must live on a volume. This is the invariant that demotes memory and rootfs snapshots to accelerators. Applications that cannot meet this contract must declare a minimumResumeFidelity floor - the worst resume they can survive - and pay for a stricter floor in scheduling freedom and blocked upgrade automation.
Today's SnapshotConfig can't express that floor.
Proposal
1. Updated SnapshotConfig
message SnapshotConfig {
string storage_location = 1;
// capture_scope defines the scope captured when taking a snapshot on suspend.
// Defaults to SNAPSHOT_SCOPE_MEMORY when unset.
SnapshotScope capture_scope = 2;
// minimum_scope defines the lowest state layer required for the actor
// to resume safely. The system attempts to resume at capture_scope, but may
// be unable to (e.g. the sandbox config changed, or the target hardware
// can't restore the snapshot) and fall back to a lower scope. If the scope
// it can resume at is below minimum_resume_scope, the actor enters CRASHED.
// Must be <= capture_scope.
// Defaults to SNAPSHOT_SCOPE_VOLUMES when unset.
SnapshotScope minimum_scope = 3;
}SnapshotScope is an ordered enum of state layers, lowest to highest (it replaces SnapshotContentScope):
enum SnapshotScope {
SNAPSHOT_SCOPE_UNSPECIFIED = 0;
// Durable volumes only; the actor cold boots from its OCI image.
SNAPSHOT_SCOPE_VOLUMES = 1;
// Volumes plus root filesystem changes.
SNAPSHOT_SCOPE_ROOTFS = 2;
// Volumes, root filesystem changes, and process memory.
SNAPSHOT_SCOPE_MEMORY = 3;
}Also ResumeActorResponse needs to tell user what was actually used.
message ResumeActorResponse {
Actor actor = 1;
bool resumed = 2;
// The scope that we actually resumed.
SnapshotScope scope = 3;
}2. Remove the old per-operation fields
- Remove
on_pause,on_commit,on_resume/OnResumeConfigandResumeSource. - Every suspend captures up to
capture_scope. Pause vs suspend distinction is being removed separately in Opt-in durability instead of Pause vs Suspend API #798. - On resume, the system picks the highest scope it can satisfy, up to
capture_scope.
cc: Julian Gutierrez Oschmann (@juli4n) Dmitry Berkovich (@dberkov) Jaana Dogan (@rakyll)
Activity
[-]ActorTemplate: replace on_pause/on_commit/on_resume with capture_scope and minimum_resume_scope[/-][+]ActorTemplate: replace on_pause/on_commit/on_resume with capture_scope and minimum_scope[/+]ateapi: remove SnapshotConfig.on_pause, pause captures the on_commit …
Replace SnapshotContentScope with the SnapshotFidelity ladder and pre…
ROOTFS snapshot fidelity: micro-VM capture and restore, API opened fo…
Sync upstream sandbox, snapshot, and HTTPS egress updates (#69)
Sync upstream snapshot and SandboxConfig updates (#70)
zoez7 commentedon Oct 18, 2026
Re: minimum_fidelity: #2818
We discussed offline and decided to defer adding this API to post-M3, the current semantics defined in actor lifecycle v2 has some problems
zoez7 commentedon Oct 18, 2026
Moved Rootfs fidelity to be under the parent issue #2069 directly