Python: fix: raise WorkflowCheckpointException when loading a corrupted checkpoint file (#8181, item 4)

[ptimizeroracle]

description

this is item 4 of #8181 only, the small one. the design questions in that issue stay open, not touching them here

the load docstring says it raises WorkflowCheckpointException when decoding fails, but the json read itself was unwrapped. so a truncated checkpoint file came out as a raw json.JSONDecodeError instead. now the read is wrapped and raises WorkflowCheckpointException with the decode error as the cause

the graceful list behavior that test_file_checkpoint_storage_corrupted_file pins is untouched

validation

before: truncate a saved checkpoint mid json, load raises json.JSONDecodeError
after: same thing raises WorkflowCheckpointException with "corrupted" in the message

added test_file_checkpoint_storage_load_corrupted_raises_checkpoint_exception, scoped to load only on purpose, so the pinned list contract stays exactly as it is

test_checkpoint.py 47/47 local, ruff clean

ai assistance: change and test written with agent help, verified by running everything locally

[Copilot]

🟡 Changes recommended

The new wrapping handles json.JSONDecodeError but still allows other corruption-related decode failures (e.g., UnicodeDecodeError) to bypass WorkflowCheckpointException.

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

Pull request overview

This PR tightens FileCheckpointStorage.load()’s error contract by ensuring corrupted/truncated checkpoint JSON surfaces as WorkflowCheckpointException (instead of leaking json.JSONDecodeError), and adds a focused regression test for that behavior.

Changes:

• Wrap JSON parsing during FileCheckpointStorage.load() to raise WorkflowCheckpointException on decode failure, chaining the original exception.
• Add a new test that truncates a saved checkpoint file and asserts load() raises the documented exception.

File summaries

File	Description
python/packages/core/agent_framework/_workflows/_checkpoint.py	Wraps JSON parsing errors during checkpoint load to standardize on WorkflowCheckpointException for corrupted files.
python/packages/core/tests/workflow/test_checkpoint.py	Adds a regression test asserting load() raises the documented exception when a checkpoint file is truncated mid-JSON.

Review details

• Files reviewed: 2/2 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.

[ptimizeroracle]

@microsoft-github-policy-service agree

[ptimizeroracle]

addressed in 2db04de: the except now pairs json.JSONDecodeError with UnicodeDecodeError, so invalid utf-8 in a checkpoint file also surfaces as WorkflowCheckpointException. added a test writing raw invalid bytes. 48/48 local.

[ptimizeroracle]

closing as superseded. #8214 already covers this and more of #8181, including the invalid utf-8 case, and it was open before this PR was built. my miss for not checking open PRs before implementing. the regression tests here (truncated json, raw invalid utf-8 bytes) stay available as extra evidence if useful.