Python: FileCheckpointStorage save/load symmetry (#8181)

[lsmlhi_25 (FOWEPJF255)]

Motivation & Context

FileCheckpointStorage could save checkpoints that the same storage could not restore, surface raw JSONDecodeError/UnicodeDecodeError on load, and disagree between list_checkpoints and list_checkpoint_ids when decoding failed. This breaks durable pause/resume and makes failures harder to handle.

Fixes #8181.

Description & Review Guide

• What are the major changes?
  • Validate encoded checkpoints against this storage's allowed_checkpoint_types before writing (including encoding failures), so save refuses payloads that load would reject.
  • Wrap invalid JSON and invalid UTF-8 on load as WorkflowCheckpointException.
  • Make list_checkpoint_ids delegate to list_checkpoints so both share one decode path.
• What is the impact of these changes?
  • Save/load/list stay consistent; callers get a single exception type for corrupt files and unrestorable payloads.
• What do you want reviewers to focus on?
  • Save-time encode+restore validation, UTF-8/JSONDecodeError wrapping on load, and list_checkpoint_ids delegation.

Related Issue

Fixes #8181

This replaces closed PR #8193 (closed for missing PR template). Same issue; no other open PR for #8181.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

🟡 Changes recommended

save() still writes checkpoint JSON without an explicit UTF-8 encoding while load() now forces UTF-8, which can reintroduce save/load asymmetry on non-UTF-8 default locales.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR improves durability and debuggability of the Python FileCheckpointStorage by enforcing save/load symmetry, standardizing exception behavior for corrupt checkpoint files, and aligning listing APIs so they don’t disagree when decoding fails.

Changes:

• Validate at save-time that an encoded checkpoint can be decoded under the same storage’s allowed_checkpoint_types, preventing “save succeeds, load fails” scenarios.
• Wrap invalid JSON / invalid UTF-8 during load() into WorkflowCheckpointException (per the CheckpointStorage contract).
• Make list_checkpoint_ids() delegate to list_checkpoints() so both use the same decode/filter path.

File summaries

File	Description
python/packages/core/agent_framework/_workflows/_checkpoint.py	Adds save-time restore validation, wraps JSON/UTF-8 read failures on load, and aligns ID listing with decoded listing.
python/packages/core/tests/workflow/test_checkpoint.py	Adds regression tests for invalid JSON/UTF-8 on load and for list ID alignment with decode filtering.
python/packages/core/tests/workflow/test_checkpoint_unrestricted_pickle.py	Adds test ensuring file storage refuses to save checkpoints it cannot restore under its own allowed-types policy.

Review details

Suppressed comments (2)

python/packages/core/agent_framework/_workflows/_checkpoint.py:472

• Since list_checkpoint_ids() now delegates to list_checkpoints(), listing IDs inherits list_checkpoints() file-reading behavior. list_checkpoints() currently opens checkpoint files without encoding="utf-8", while load() explicitly uses UTF-8; this can make listing locale-dependent and cause list_checkpoint_ids()/get_latest() to miss checkpoints that load() could otherwise read (or vice versa) when non-ASCII is present.

        checkpoints = await self.list_checkpoints(workflow_name=workflow_name)
        return [checkpoint.checkpoint_id for checkpoint in checkpoints]

python/packages/core/agent_framework/_workflows/_checkpoint.py:382

• This error message is also used for UnicodeDecodeError (invalid UTF-8), but it only mentions JSON. That can be misleading when the file is valid JSON in another encoding or simply not UTF-8.

            raise WorkflowCheckpointException(
                f"Checkpoint file for {checkpoint_id} is not valid JSON and cannot be loaded."
            ) from ex

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[lsmlhi_25 (FOWEPJF255)]

Follow-up: save() and list now open checkpoint JSON with explicit encoding=utf-8 to match load().

[lsmlhi_25 (FOWEPJF255)]

Follow-up: save()/list/load all use explicit UTF-8; load distinguishes UnicodeDecodeError vs JSONDecodeError. Please re-review when convenient.

[lsmlhi_25 (FOWEPJF255)]

Thanks for the approval. Branch is up to date / CI running; ready to merge when checks are green.

[LI (ktz03)]

lsmlhi_25 (@FOWEPJF255) Already has Eduard van Valkenburg (@eavanvalkenburg) approval and the UTF-8 save/load follow-up. Flagging here in case this just needs a final maintainer merge once required workflows are green.

[lsmlhi_25 (FOWEPJF255)]

Friendly ping: this PR is mergeable and waiting on review (FileCheckpointStorage save/load symmetry for #8181). Happy to address any feedback.

[Eduard van Valkenburg (eavanvalkenburg)]

Looks good—thanks!

[LI (ktz03)]

Eduard van Valkenburg (@eavanvalkenburg) Thanks for the re-approval — CI looks green / mergeable on this head whenever you're ready to merge.