Skip to content

ActorTemplate: replace on_pause/on_commit/on_resume with capture_scope and minimum_scope #2102

Description

@zoez7

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 / OnResumeConfig and ResumeSource.
  • 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

  1. added this to the M3 milestone on Oct 2, 2026
  2. added
    area/apiUser-facing API changes
    prio/P0Highest priority / required for next milestone
    on Oct 2, 2026
  3. changed the title [-]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[/+] on Oct 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

area/apiUser-facing API changesarea/api-machinerykind/featureAn enhancement / feature request or implementationprio/P0Highest priority / required for next milestone

Type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions