Skip to content

Remove the top level --boot flag from ResumeActorRequest - #1548

Merged
Julian Gutierrez Oschmann (juli4n) merged 1 commit into
agent-substrate:mainfrom
zoez7:resume-boot
Sep 11, 2026
Merged

Julian Gutierrez Oschmann (juli4n) merged 1 commit into
agent-substrate:mainfrom
zoez7:resume-boot

Conversation

@zoez7

@zoez7 Zoe Zhao (zoez7) commented Sep 9, 2026 •

Copy link
Copy Markdown
Collaborator

Fixes #1566

Today the Resume workflow resolves its restore source in the following order

  1. First check if the actor has node-local snapshot,
  2. then its own durable external snapshot,
  3. then the template's golden snapshot.

The boot flag was consulted at exactly one point in that chain, where it suppressed using the golden-snapshot, which made its behavior much narrower than "boot from scratch" suggests:

  • Actor has its own external snapshot and boot=true: flag ignored, restores the actor's snapshot.
  • Actor has a local snapshot and boot=true: flag ignored, restores the local snapshot.
  • Actor has no snapshot, template has no golden snapshot: cold boot from the spec regardless of the boot flag.
  • Actor has no snapshot, template has a golden snapshot: boot=false restores the golden, boot=true cold boots from the spec. This is the only case where the flag is used.

The glutton benchmark was the only caller that set boot=true, on each actor's first resume, to report true cold-start latency as a separate ResumeActorColdStart stats row. Max Smythe (@maxsmythe) let me know if this is required.

The proto field number and name were reserved.

  • Tests pass
  • Appropriate changes to documentation are included in the PR

@zoez7 Zoe Zhao (zoez7) changed the title Remove the top level boot flag from ResumeActorRequest Remove the top level --boot flag from ResumeActorRequest Sep 9, 2026
@zoez7
Zoe Zhao (zoez7) marked this pull request as ready for review September 9, 2026 00:14
@maxsmythe

Copy link
Copy Markdown
Collaborator

This seems like it may actually be a different kind of bug... what happens when a snapshot with durdir gets into a permanently bad state (crashed)? What are the options for reading only the persisted data?

Otherwise, if this is never an expected action, I see no reason to benchmark it other than catching the edge case where there is no golden snapshot (which could still be interesting).

@zoez7

Copy link
Copy Markdown
Collaborator Author

what happens when a snapshot with durdir gets into a permanently bad state (crashed)? What are the options for reading only the persisted data?

This is the API being discussed in #1556

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs rebase.

Resume resolves its restore source in strict priority order: the
actor's node-local snapshot, then its own durable external snapshot,
then the template's golden snapshot, then a cold boot from the
template spec. The boot flag was consulted at exactly one point in
that chain, where it suppressed the golden-snapshot fallback, which
made its behavior much narrower than "boot from scratch" suggests:

- Actor has its own external snapshot, boot=true: flag ignored,
  restores the actor's snapshot.
- Actor has a local snapshot, boot=true: flag ignored, restores the
  local snapshot.
- Actor has no snapshot, template has a golden snapshot: boot=false
  restores the golden, boot=true cold boots from the spec. The only
  case the flag ever changed.
- Actor has no snapshot, template has no golden snapshot: cold boot
  from the spec regardless of the flag.

The one behavior the flag still controlled is not worth a public API
field: when a template has no golden snapshot, the golden actor is
cold booted from the template spec anyway, so the cold-boot path
remains exercised without a caller-facing escape hatch. The flag was
silently ignored in every other state, no caller outside the glutton
benchmark ever set it, and no test covered boot=true.

The glutton benchmark was the only caller that set boot=true, on each
actor's first resume, to report true cold-start latency as a separate
ResumeActorColdStart stats row. That row is renamed to
ResumeActorFirstResume: a fresh actor's first resume now restores the
template's golden snapshot instead of cold booting, so the old name
would misrepresent what it measures.

The proto field number and name are reserved per convention.
@juli4n
Julian Gutierrez Oschmann (juli4n) merged commit a536fab into agent-substrate:main Sep 11, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ResumeActor: the semantics of the --boot flag is not exactly "boot from scratch"

3 participants