Python: Prevent workflow checkpoints from being mutated outside of storage implementations

[Tao Chen (TaoChenOSU)]

Motivation & Context

Closes #7683 and #7685
Supersedes #7697, #7712, #7830, #7848

Description & Review Guide

• What are the major changes?
  • Checkpoint storage implementations should return deep copies of the stored checkpoints to prevent the owned checkpoints from being mutated outside of its boundary.
  • State export and import should also return and create deep copies of the state to prevent states from being mutated outside of its own boundary.
• What is the impact of these changes?
  • Workflow checkpoints and states are now isolated from mutations outside of their respective boundaries.
• What do you want reviewers to focus on?
  • If the checkpoint storage contract clear for developers.
  • If the default in memory checkpoint storage follows the contract correctly.

Related Issue

Fixes #7683, #7685

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.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_harness
_loop.py	303	7	97%	493, 532, 626, 703, 746, 821, 977
packages/core/agent_framework/_workflows
_agent.py	324	32	90%	80, 84, 128–129, 278, 291, 358, 369, 371, 427, 438, 493, 563, 641, 671, 699, 746, 755, 816, 823, 829–830, 841, 873, 880, 901, 910, 914, 916–918, 925
_checkpoint.py	158	1	99%	311
_state.py	46	0	100%
TOTAL	48074	4494	90%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9738	36 💤	0 ❌	0 🔥	2m 32s ⏱️

[Copilot]

Pull request overview

Strengthens Python workflow checkpoint isolation across state and storage boundaries.

Changes:

• Deep-copies state during export and restoration.
• Returns copied checkpoints from in-memory storage.
• Adds state, runner, and storage conformance tests.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
python/packages/core/agent_framework/_workflows/_state.py	Adds deep-copy state boundaries.
python/packages/core/agent_framework/_workflows/_checkpoint.py	Documents ownership and copies in-memory reads.
python/packages/core/tests/workflow/test_state.py	Tests nested state isolation.
python/packages/core/tests/workflow/test_runner.py	Tests storage-less restoration isolation.
python/packages/core/tests/workflow/test_checkpoint_storage_conformance.py	Adds backend ownership conformance tests.
python/packages/core/agent_framework/_workflows/_agent.py	Formatting-only change.
python/packages/core/agent_framework/_harness/_loop.py	Formatting-only changes.
python/packages/core/tests/core/test_harness_loop.py	Import-order-only change.

Suppressed comments (1)

python/packages/core/agent_framework/_workflows/_state.py:121

• The same custom __deepcopy__ behavior means restore isolation is still incomplete: importing a checkpoint containing Content/other SerializationMixin values copies raw_representation by reference, so later live-state mutation can mutate the caller's checkpoint. Please use a checkpoint-specific clone/sanitization policy rather than relying on generic deepcopy for the restoration boundary.

        self._committed.update(copy.deepcopy(state))

---

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

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): a5062c6c7bc2
Model: gpt-5.6-sol

Overview

The review found 2 verified inline finding(s).

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
2 verified findings remained after source verification (2 medium) across 2 files. Details are attached to the affected lines below.

Affected areas: python/packages/core/agent_framework/_workflows/_checkpoint.py, python/packages/core/agent_framework/_workflows/_state.py

[github-actions]

MAF Automated Review — Iteration 2

Result: Findings reported
Scope: 2 net-new commit(s): 588d16565ae6, ae8cd879229b
Model: gpt-5.6-sol

Overview

The review found 2 verified inline finding(s).

Reviewed the supplied incremental change set across correctness, security/reliability, architecture, and failure behavior.
2 verified findings remained after source verification (2 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/core/agent_framework/_workflows/_state.py