.NET: Add bounded parallel declarative Foreach execution

[KirschQAQ (KirschBluteX)]

Motivation & Context

Declarative Foreach currently executes each item serially. Workflows that fan out independent items cannot opt into bounded parallelism without changing their model or losing deterministic state semantics. This adds opt-in parallel execution for issue #2793 while leaving existing workflows unchanged.

Description & Review Guide

• What are the major changes? Add mode: Parallel, validated maxParallelism (default 4), and per-iteration timeoutInMilliseconds through the existing Foreach extension-data path. A fixed worker pool runs isolated in-process branch workflows, deep-copies formula state and loop values, buffers state/events/conversation writes, then commits and replays by source index. Branch failures are aggregated in source order and cancel peers. Bodies that can suspend for external input, mutate shared conversations, target explicit conversations, terminate workflow-wide control flow, jump outside the body, or target the parallel loop are rejected at build/runtime.
• What is the impact of these changes? Serial Foreach remains the default and existing YAML/object-model consumers keep their behavior. Parallel mode has deterministic last-index-wins state commits, real per-loop concurrency limits (nested limits multiply), cooperative timeout/cancellation, and no staged state/event/conversation commit when an iteration fails. In-flight parallel checkpoint suspension is rejected; completed-loop checkpoint/resume remains safe. Provider-side effects already issued before cancellation are not rolled back.
• What do you want reviewers to focus on?
  Please focus on whether the branch-local state snapshots and source-index commit order preserve existing declarative state semantics; whether maxParallelism truly bounds active iterations, including nested loops; and whether failure, timeout, cancellation, and checkpoint-rejection behavior matches the workflow runtime contract. In particular, please review the explicit safety boundaries for external input, conversation mutation, and loop-control actions.

Related Issue

Fixes#2793

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]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds opt-in parallel execution for declarative Foreach, including isolated per-iteration formula state, deterministic commit ordering, timeout/cancellation behavior, and documentation + end-to-end tests validating concurrency and failure semantics.

Changes:

• Introduces ForeachExecutionOptions and ParallelForeachIterationRunner to execute Foreach bodies concurrently with bounded parallelism and per-iteration timeouts.
• Extends WorkflowFormulaState to snapshot/branch state and track variable writes for deterministic, ordered commits.
• Adds unit tests and README documentation describing parallel Foreach behavior and limitations.

Reviewed changes

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

Show a summary per file

File	Description
dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/ParallelForeachWorkflowTests.cs	New E2E behavioral tests covering concurrency, ordering, failures, cancellation, and timeouts.
dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/README.md	Documents how to opt into parallel Foreach, limits/timeouts, and checkpointing constraints.
dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/PowerFx/WorkflowFormulaState.cs	Adds state snapshotting, branch creation, and change tracking for parallel iteration isolation/commit.
dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/ParallelForeachIterationRunner.cs	Executes a single iteration in an isolated runtime and returns buffered state changes/events.
dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/ForeachExecutor.cs	Adds parallel execution path, bounded worker pool, and ordered commit replay into parent context.
dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/ForeachExecutionOptions.cs	Parses/validates Foreach execution options from extension data (mode, maxParallelism, timeoutInMilliseconds).
dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/WorkflowElementWalker.cs	Prevents walking into parallel Foreach descendants to avoid double-compiling its body.
dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/WorkflowActionVisitor.cs	Passes workflow options into ForeachExecutor and short-circuits visitor logic for parallel loops.

---

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

[KirschQAQ (KirschBluteX)]

@microsoft-github-policy-service agree