[BREAKING] Python: Validate checkpoint configuration consistency in sub-workflows, adjust workflow validation error

[moonbox3]

Motivation and Context

When a parent workflow has checkpointing enabled but a sub-workflow does not, the checkpoint/restore behavior is undefined. The current implementation in WorkflowExecutor.on_checkpoint_restore() manually rehydrates sub-workflow state by accessing the private _runner_context object, with a TODO acknowledging this is a temporary solution. This
PR adds validation to detect the mismatch early and error clearly, rather than letting developers hit undefined behavior at runtime.

Breaking changes

1. Checkpoint configuration validation: Previously, having a parent workflow with checkpointing and a sub-workflow without it was silently accepted but produced undefined checkpoint/restore
   behavior. Now this raises WorkflowValidationError with validation_type="checkpoint_configuration" at build time (or at runtime if checkpoint_storage is provided only via workflow.run()).

2. ValidationTypeEnum removed: WorkflowValidationError.validation_type is now a ValidationType string literal (e.g., "edge_duplication", "checkpoint_configuration") instead of a
   ValidationTypeEnum member. Compare directly against strings instead of enum values.

Migration for checkpoint validation: pass checkpoint_storage to every sub-workflow's WorkflowBuilder when the parent workflow uses checkpointing.

# Before (undefined behavior on restore)
sub_wf = WorkflowBuilder(start_executor="writer").build()
sub_executor = WorkflowExecutor(sub_wf, id="sub")

# After
sub_wf = WorkflowBuilder(start_executor="writer", checkpoint_storage=storage).build()
sub_executor = WorkflowExecutor(sub_wf, id="sub")

Migration for validation type: compare against string literals instead of enum members.

# Before
from agent_framework import ValidationTypeEnum

except WorkflowValidationError as e:
    if e.validation_type == ValidationTypeEnum.EDGE_DUPLICATION:
        ...

# After
except WorkflowValidationError as e:
    if e.validation_type == "edge_duplication":
        ...

Description

• Adds build-time validation in WorkflowBuilder.build() that checks all WorkflowExecutor children have checkpointing when the parent does
• Adds runtime validation in Workflow._run_core() for the case where checkpoint_storage is provided only at run() time
• Replaces ValidationTypeEnum with ValidationType string literal type for simpler error handling without enum imports
• Updates sub_workflow_checkpoint sample to demonstrate correct explicit configuration
• Closes Python: Handle checkpointing mismatch between parent and sub-workflows #3527

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_validation.py	144	5	96%	128, 149, 244, 325, 328
_workflow.py	272	26	90%	87, 289–291, 293–294, 312, 316, 344, 446, 622, 643, 669, 696, 698–699, 704–705, 711, 717, 722, 742–744, 757, 825
_workflow_builder.py	272	35	87%	257, 527, 625, 632–633, 733, 736, 741, 743, 750, 753–757, 759, 820, 894, 897, 953, 971, 984, 998–1005, 1007, 1010, 1012–1014
TOTAL	16554	2059	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3926	225 💤	0 ❌	0 🔥	1m 7s ⏱️

[Copilot]

Pull request overview

Adds explicit validation to prevent undefined checkpoint/restore behavior when a checkpoint-enabled parent workflow contains non-checkpointed sub-workflows, and simplifies workflow validation typing by replacing the enum with string-literal validation types.

Changes:

• Add build-time validation in WorkflowBuilder.build() to require checkpoint configuration consistency for WorkflowExecutor children when the parent has checkpointing enabled.
• Add runtime validation in Workflow._run_core() when checkpoint_storage is supplied via workflow.run(...).
• Replace ValidationTypeEnum with a ValidationType string-literal type and update tests/samples accordingly.

Reviewed changes

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

Show a summary per file

File	Description
python/packages/core/agent_framework/_workflows/_workflow_builder.py	Build-time validation for checkpointing consistency across nested workflows.
python/packages/core/agent_framework/_workflows/_workflow.py	Adds has_checkpointing and runtime validation for sub-workflow checkpoint configuration.
python/packages/core/agent_framework/_workflows/_validation.py	Replaces enum-based validation type with Literal[...] string types and updates error formatting.
python/packages/core/agent_framework/_workflows/init.py	Updates public exports to expose ValidationType instead of ValidationTypeEnum.
python/packages/core/tests/workflow/test_validation.py	Updates assertions to use string validation types instead of enums.
python/packages/core/tests/workflow/test_sub_workflow.py	Updates checkpointing-related sub-workflow construction to satisfy new validation rules.
python/packages/core/tests/workflow/test_checkpoint_configuration.py	Adds coverage for build-time/runtime checkpoint mismatch validation in nested workflows.
python/samples/getting_started/workflows/checkpoint/sub_workflow_checkpoint.py	Updates sample to explicitly configure checkpoint storage in sub-workflow builder.