feat(workflow): align history propagation API with go-sdk

[nelson-parente]

Summary

Aligns the workflow history propagation surface added in #1802 / #1818 with the canonical go-sdk shape — the same one python-sdk just adopted in python-sdk#1047. @cicoyle (durabletask-go author) flagged the divergence post-merge while building 1.18 quickstarts; this PR delivers what issue #1801 originally described.

This brings .NET in line for cross-SDK parity before 1.18 ships.

Three concrete gaps closed

1. Activity-level opt-in (was missing entirely)

Before this PR, PropagationScope only lived on ChildWorkflowTaskOptions — there was no way to propagate history when scheduling an activity. The go-sdk reference example uses exactly this pattern (SettlePayment activity with PropagateOwnHistory), so the cross-SDK quickstart literally couldn't be ported.

• PropagationScope moved to base WorkflowTaskOptions.
• WithHistoryPropagation() extension method available on both WorkflowTaskOptions and ChildWorkflowTaskOptions.
• scheduleTaskAction.HistoryPropagationScope wired in WorkflowOrchestrationContext.CallActivityInternalAsync, matching the existing child-workflow path.

2. Read API replaced (was lossy FilterBy* + minimal events)

The old PropagatedHistoryEvent only kept (EventId, Kind, Timestamp) — input/output/failure payloads were thrown away by ConvertChunk, making the high-level audit/fraud-detection patterns from the Go/Python quickstarts impossible.

• Removed: PropagatedHistory.FilterByAppId/InstanceId/WorkflowName, the old minimal PropagatedHistoryEvent, HistoryEventKind (clean break — 1.18 unreleased).
• New on PropagatedHistory: GetWorkflows(), GetWorkflowsByName(), TryGetLastWorkflowByName(), GetAppIds(), GetWorkflowsByAppId(), GetWorkflowsByInstanceId().
• New PropagatedHistoryEntry class (one per ancestor workflow) with TryGetLastActivityByName(), GetActivitiesByName(), TryGetLastChildWorkflowByName(), GetChildWorkflowsByName() — mirrors the GetLast*ByName rename merged in durabletask-go#105, adapted to the idiomatic .NET TryGet* pattern with [NotNullWhen(true)] out parameters.
• New PropagatedHistoryActivityResult(Name, Started, Completed, Failed, Input, Output, FailureDetails) record — matches the Go SDK's ActivityResult struct and Python's ActivityResult dataclass.
• New PropagatedHistoryChildWorkflowResult with the equivalent shape.
• Lookups by name and app ID are case-insensitive, matching how WorkflowsFactory registers workflow/activity names and how the SDK matches app IDs elsewhere.

3. Event payload preserved internally

ConvertChunk now walks the raw HistoryEvents, pre-indexes TaskCompleted / TaskFailed (and the child-workflow counterparts) by TaskScheduledId in a single pass — so each scheduled activity or child resolves in O(1) — and produces fully-populated PropagatedHistoryActivityResult / PropagatedHistoryChildWorkflowResult records. SDK retries reuse TaskExecutionId, so we match on the scheduling event ID (matching Go/Python semantics). The proto HistoryEvent type is never exposed publicly — resolution happens at construction time inside Dapr.Workflow.

Usage example (matches the go-sdk reference)

```csharp
// Parent workflow propagates lineage to a child workflow and own-history to an activity
var fraudResult = await context.CallChildWorkflowAsync(
nameof(FraudDetection),
input: req,
options: new ChildWorkflowTaskOptions()
.WithHistoryPropagation(HistoryPropagationScope.Lineage));

await context.CallActivityAsync(
nameof(SettlePayment),
input: req,
options: new WorkflowTaskOptions()
.WithHistoryPropagation(HistoryPropagationScope.OwnHistory));

// Receive side — query specific events by name with TryGet*
var history = context.GetPropagatedHistory();
if (history is not null &&
history.TryGetLastWorkflowByName("MerchantCheckout", out var merchant) &&
merchant.TryGetLastActivityByName("ValidateMerchant", out var validate))
{
if (validate.Completed) { /* inspect validate.Output */ }
}
```

Non-goals

• No example app in this PR. The cross-SDK quickstart lives in dapr/quickstarts#1310 and will be refreshed against this API once it merges.
• No proto / runtime changes. All proto fields already exist (ScheduleTaskAction.historyPropagationScope field 6, CreateChildWorkflowAction.historyPropagationScope field 6); we just had to wire the activity path.

Breaking changes (1.18 unreleased)

The propagation API shipped in #1802/#1818 has not been released. This PR replaces it cleanly rather than carrying [Obsolete] shims for an API that has no users yet. Removed types: the old minimal PropagatedHistoryEvent, HistoryEventKind, PropagatedHistory.FilterByAppId, FilterByInstanceId, FilterByWorkflowName. (PropagatedHistoryEntry is reused as the new per-ancestor entry type with a richer shape.)

Test plan

• WorkflowHistoryPropagationTests.cs rewritten end-to-end: activity resolution (completed/failed/pending/retried), child-workflow resolution, history helpers (GetAppIds, TryGetLastWorkflowByName, GetWorkflowsByName, case-insensitive name/AppId lookups), scheduling option records (both base + derived), activity-level + child-workflow outbound action scope wiring.
• HistoryPropagationWorkflowTests.cs (integration) updated to GetWorkflows().Count.
• dotnet build + dotnet test to be verified by CI — couldn't build locally (no .NET 10 SDK on dev machine). Sweep confirmed no stale references to removed types in src/ or test/.

References

• Closes Add support for workflow history propagation #1801
• go-sdk reference impl + example: dapr/go-sdk#823
• go-sdk GetLast*ByName rename: dapr/durabletask-go#105
• python-sdk parallel: dapr/python-sdk#1047
• java-sdk parallel: dapr/java-sdk#1739

cc @cicoyle @WhitWaldo

[WhitWaldo]

@nelson-parente I'm not inclined to accept the type name changes. For types that are exclusively used for workflow history propagation, it makes sense that they'd reflect that in the name. For example, there's no such thing as a WorkflowResult except in the context of history propagation - its more accurately described as a PropagatedHistoryEvent as originally named.

That said, completely agree about the activity propagation oversight.

I'll review this later this afternoon for specific notes, but I wanted to call this out for posterity.

[WhitWaldo]

Thank you for putting this PR together.

As I said in the earlier comment and repeat throughout, there's a distinction to me in terminology we use internally within the implementation of the project (in the gRPC protos, in the runtime) and the terminology we use in public-facing documentation. The protos refer to chunks and I've got no problem extending that to private methods, but most of this PR exposes public types with public-facing XML documentation - the names should be clear as to purpose and not introduce anything not present in publicly available Dapr documentation (like "chains" or "chunks"), especially when far more specific and particular names are already exposed in the implementation.

All of this work is scoped to history propagation - the names of these types should reflect this accordingly. It'd be one thing if you put them in a namespace like Dapr.Workflow.Abstractions.ProgagatedHistory and named them as such, but this isn't the long-standing Dapr .NET convention - most types are just left in the project root. So in this case, vague types like ActivityResult or ChildWorkflowResult just aren't clear. A developer shouldn't have to look at the XML documentation to understand that this isn't actually describing the returned result from a workflow or a child workflow - the name should be self-documenting, so I've proposed better alternatives like PropagatedHistoryActivityResult and PropagatedHistoryChildWorkflowResult.

The kind of event from the history was dropped in this implementation. Yes, it's not mentioned in #1801 but doesn't it provide some value to the user regarding what the event represents (e.g. activity started or completed)?

I certainly do appreciate you identifying the gap between supporting the activity propagation in addition to the existing workflow implementation.

Please do let me know if you have any follow-up questions.

[WhitWaldo]

As I said in the comment, ActivityResult isn't helpful, I don't think, because users provide their own types for activity results. Rather, this would be more aptly named as a PropagatedHistoryActivityResult.

[nelson-parente]

Done — renamed to PropagatedHistoryActivityResult in b604220.

[WhitWaldo]

Again, workflows (child or not) return user-defined types, so this isn't helpfully named. As the original implementation didn't have activity support, I think there's a great opportunity here to opt for a rename from the original and instead call this PropgatedHistoryChildWorkflowResult.

I'm not terribly enthused by including "Child" in the type name as a workflow is a workflow whether it has a parent or not - that's just a provenance question. In other words, if a child workflow doesn't do something distinctly different from any other workflow, I don't entirely follow why we would call it something else (and I extend this argument to the "Detached Workflows" - they're just workflows that don't have a parent).

But I digress - in the interest of uniformity to the gRPC prototype descriptions, I'm fine calling this PropgatedHistoryChildWorkflowResult.

[nelson-parente]

Done — renamed to PropagatedHistoryChildWorkflowResult in b604220.

[WhitWaldo]

I'd rather see this implemented using a primary constructor for conciseness and SDK uniformity as nothing is happening in the constructor outside of validation.

[nelson-parente]

Done — PropagatedHistoryEntry now uses a primary constructor.

[WhitWaldo]

As in other classes, let's not introduce vague new terminology like "chunks" or "chains" in public-facing XML documentation when we already have terms that accurately and more obviously describe what they actually refer to. Such descriptions might be perfectly fine in internal implementations as they reflect usage from the gRPC protos themselves, but this is a public type and there should be nothing in here that doesn't have an analog directly to the publicly accessible Dapr runtime documentation.

[nelson-parente]

Done — public XML scrubbed of "chunks" and "chains" across the abstractions.

[WhitWaldo]

The protos describe the type of history event returned. Is this not something meaningful to provide to the user?

[nelson-parente]

Lifecycle stage is captured by Started / Completed / Failed booleans on each result record — covers pending (Started && !Completed && !Failed) and matches go-sdk / python-sdk. HistoryEventKind removed.

[WhitWaldo]

No interest in reflecting what type of event was recorded here? It's in the protos.

[nelson-parente]

Captured via Started / Completed / Failed booleans rather than a separate event-kind enum, matching go-sdk ActivityResult and python-sdk.

[WhitWaldo]

No interest in reflecting what type of event was recorded here? It's in the protos.

[nelson-parente]

Same as PropagatedHistoryActivityResult — Started / Completed / Failed cover the lifecycle without a separate enum, matching go-sdk / python-sdk.

[WhitWaldo]

This seems like something the SDK should absolutely throw on if the runtime is throwing bad events to the SDK, right? Not just swallow the exception and pretend nothing is wrong here.

[nelson-parente]

Done — the try / catch around HistoryEvent.Parser.ParseFrom is gone; malformed event bytes now surface as exceptions. See b604220.

[Copilot]

Pull request overview

Aligns the .NET workflow history propagation API with the Go/Python SDK shape by (1) enabling propagation scope on activity scheduling and (2) upgrading the read-side propagated history model from “minimal events” to typed activity/child-workflow results reconstructed from raw history events.

Changes:

• Added PropagationScope to WorkflowTaskOptions and wired it into the activity scheduling (ScheduleTaskAction.HistoryPropagationScope) path.
• Reworked propagated history domain types to expose workflow entries with resolved Activities and ChildWorkflows (including input/output/failure details), removing the older “event-kind” model.
• Updated unit/integration tests to validate the new surface and behavior (including malformed raw-event handling).

Reviewed changes

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

Show a summary per file

File	Description
test/Dapr.Workflow.Test/Worker/Internal/WorkflowHistoryPropagationTests.cs	Rewritten unit tests for new propagated history shape, activity/child resolution, and outbound propagation scope wiring.
test/Dapr.IntegrationTest.Workflow/HistoryPropagationWorkflowTests.cs	Updated integration test assertion to use the new GetWorkflows() API.
src/Dapr.Workflow/Worker/Internal/WorkflowOrchestrationContext.cs	Wires activity propagation scope into ScheduleTaskAction; reconstructs propagated history entries from raw events.
src/Dapr.Workflow.Abstractions/WorkflowTaskOptions.cs	Adds PropagationScope to base options + fluent WithHistoryPropagation; updates child options accordingly.
src/Dapr.Workflow.Abstractions/WorkflowContext.cs	Updates GetPropagatedHistory() docs to point to the new lookup helpers.
src/Dapr.Workflow.Abstractions/PropagatedHistory.cs	Replaces filter-based API with Get*/TryGet* navigation helpers and app/workflow/instance querying.
src/Dapr.Workflow.Abstractions/PropagatedHistoryEntry.cs	Changes from a record of minimal events into a class representing a workflow entry with typed activity/child results + lookup helpers.
src/Dapr.Workflow.Abstractions/PropagatedHistoryActivityResult.cs	Introduces typed activity result surfaced through propagated history.
src/Dapr.Workflow.Abstractions/PropagatedHistoryChildWorkflowResult.cs	Introduces typed child-workflow result surfaced through propagated history.
src/Dapr.Workflow.Abstractions/PropagatedHistoryEvent.cs	Removes the old minimal propagated event model.
src/Dapr.Workflow.Abstractions/HistoryEventKind.cs	Removes the old public event-kind enum.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.