Add opt-in unversioned fallback for versioned task dispatch

[torosent]

Intent

Per-task versioning today is a closed set for mixed registrations: once a task name has any [DurableTask(Version = "...")] registration, a request for a version that has no exact match returns "not found" instead of dispatching to a co-registered unversioned class. That makes the natural migration pattern — one current unversioned implementation that handles every live version, plus a small number of pinned legacy classes for specific old versions — impossible to express without registering every observed version explicitly, which is impractical for long-running orchestrations whose histories span many versions in the wild.

This PR introduces an UnversionedFallbackMode enum with three modes (configured independently for orchestrators and activities) that lets each worker choose how the unversioned registration participates in versioned dispatch:

• Implicit (default) — the long-standing implicit fallback: the unversioned registration serves versioned requests only when the task name has no versioned siblings. Matches pre-versioning behavior.
• CatchAll — opt-in catch-all: the unversioned registration also serves unmatched versioned requests on mixed names. Exact match still wins.
• StrictExactOnly — strict mode: every versioned request requires an exact (name, version) registration. Stale or bogus version values fail loudly instead of landing on the unversioned implementation.

builder.UseVersioning(new DurableTaskWorkerOptions.VersioningOptions
{
    // Activity fallback is the safer place to start: activities are stateless and do not replay history.
    ActivityUnversionedFallback = DurableTaskWorkerOptions.UnversionedFallbackMode.CatchAll,

    // Orchestrator fallback carries replay risk; enable only when the unversioned orchestrator is
    // replay-compatible with every version it may receive.
    OrchestratorUnversionedFallback = DurableTaskWorkerOptions.UnversionedFallbackMode.CatchAll,
});

Dispatch matrix for a versioned request

Registry shape for the name	Implicit	CatchAll	StrictExactOnly
Only unversioned [X]	unversioned	unversioned	not found
Mixed (versioned + unversioned), exact match	exact	exact	exact
Mixed, no exact match	not found	unversioned	not found
Only versioned, no exact match	not found	not found	not found

Unversioned requests (no version specified) always dispatch to the unversioned registration when one exists; they're an exact-match on the empty-version key and the mode does not affect them.

What changes

Public API surface

• DurableTaskWorkerOptions.UnversionedFallbackMode (new enum): Implicit (default), CatchAll (opt-in catch-all), StrictExactOnly (no fallback ever). A 4-row dispatch table appears on the enum's <remarks>.
• DurableTaskWorkerOptions.VersioningOptions.OrchestratorUnversionedFallback (new property): per-side mode for orchestrator dispatch. Replay risk is highest on this side; the property's <remarks> lays out interactions with MatchStrategy (Strict and CurrentOrOlder are pre-dispatch gates; this setting governs how instances that pass the gate are resolved).
• DurableTaskWorkerOptions.VersioningOptions.ActivityUnversionedFallback (new property): per-side mode for activity dispatch. Lower risk because activities are stateless; main concern is input contract compatibility.

Internal wiring

• DurableTaskRegistryExtensions.BuildFactory(options, loggerFactory?) (new internal overload): plumbs an optional ILoggerFactory into the factory so per-dispatch fallback diagnostics can be emitted. Called by DefaultDurableTaskWorkerBuilder; not part of the public API surface.
• DurableTaskFactory: ctor takes both per-side modes + optional ILoggerFactory; orchestrator and activity dispatch each consult their own mode via a small ShouldUseUnversionedFallback helper.
• DurableTaskWorkerWorkItemFilters: orchestration filter reads OrchestratorUnversionedFallback; activity filter reads ActivityUnversionedFallback. Under StrictExactOnly the filter emits the concrete registered version set instead of widening to a wildcard for unversioned-only names — otherwise the backend would deliver versioned work items the factory rejects after the fact.
• UseVersioning extension propagates both new fields.

Logging (EventIds 606–609)

EventId	Level	When	Purpose
606	Warning	OrchestratorUnversionedFallback = CatchAll at worker build	Surface the orchestrator-side replay-compatibility caveat
607	Warning	ActivityUnversionedFallback = CatchAll at worker build	Surface the activity-side input-shape caveat
608	Debug	Orchestrator dispatched to unversioned registration	Diagnose "did my v1.5 instance run on LegacyImpl or CatchAllImpl?"
609	Debug	Activity dispatched to unversioned registration	Same, for activities

StrictExactOnly is an opt-in tightening and does not get a warning at startup.

Sample

UnversionedFallbackSample enables both CatchAll flags (it specifically demos catch-all dispatch), but the README explicitly calls out activity-only as the safer starting point and explains the asymmetric replay risk.

What stays the same (compatibility)

• Not a breaking change. Both new properties default to Implicit (numeric value 0), preserving the long-standing implicit-fallback behavior that existed before this PR.
• Strict worker versioning is still a pre-dispatch gate. This setting never bypasses MatchStrategy = Strict: instance-version mismatches are rejected in EvaluateOrchestrationVersioning before the factory is consulted.
• Exact-version match always wins. Even with CatchAll on, a request for an explicitly registered version dispatches to that exact implementation, never to the unversioned catch-all.
• Per-side independence. Orchestrator and activity modes are configured and evaluated independently — there is no leak between the two sides.

Known limitation

When combined with MatchStrategy = Strict, the existing strict-override emits the worker's configured Version for every name regardless of whether the factory can resolve it. Under StrictExactOnly this can result in the backend delivering work items the worker rejects. A proper fix requires per-name dispatch-capability analysis and is out of scope here. The behavior is captured by WorkItemFilters_StrictMatchOverridesStrictExactOnly_KnownLimitation and documented in the OrchestratorUnversionedFallback <remarks>.

Safety guidance

The orchestrator-side unversioned implementation must be replay-compatible with every version that may reach it. Replaying an existing orchestration history against an incompatible implementation can cause non-determinism faults or deserialization failures. Activity-side risk is limited to input-contract compatibility because activities are stateless. The startup warning logs (EventId 606 / 607) and per-property XML docs both call this out.

Validation

• dotnet build samples/UnversionedFallbackSample/UnversionedFallbackSample.csproj --configuration Debug --verbosity minimal
• DTS-emulator sample run with DURABLE_TASK_SCHEDULER_CONNECTION_STRING='Endpoint=http://localhost:8080;TaskHub=default;Authentication=None'
• dotnet test test/Worker/Core.Tests/Worker.Tests.csproj --configuration Debug --verbosity minimal → 153/153 pass
• dotnet test test/Worker/Grpc.Tests/Worker.Grpc.Tests.csproj --configuration Debug --verbosity minimal → 136/136 pass
• git diff --check

[torosent]

Fixed the test

[Copilot]

Pull request overview

Adds an opt-in worker setting to allow unversioned task registrations to serve as a catch-all for unmatched versioned orchestration/activity dispatch, enabling more practical long-running version migration patterns while preserving the existing closed-set behavior by default.

Changes:

• Introduces DurableTaskWorkerOptions.UnversionedFallbackMode + VersioningOptions.UnversionedFallback and propagates it via UseVersioning(...).
• Updates DurableTaskFactory dispatch rules and DurableTaskWorkerWorkItemFilters generation to support the fallback behavior (including backend filter widening only when applicable).
• Adds warning logging and expands unit/integration tests plus a new end-to-end sample.

Reviewed changes

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

Show a summary per file

File	Description
test/Worker/Grpc.Tests/WorkItemStreamConsumerTests.cs	Makes heartbeat reset test more robust against CI timing jitter.
test/Worker/Grpc.Tests/GrpcDurableTaskWorkerTests.cs	Adds a strict-versioning guard test ensuring mismatch rejects before factory dispatch (even with fallback enabled).
test/Worker/Core.Tests/DurableTaskFactoryVersioningTests.cs	Verifies orchestrator unknown-version dispatch falls back to unversioned when opt-in is enabled.
test/Worker/Core.Tests/DurableTaskFactoryActivityVersioningTests.cs	Verifies activity unknown-version dispatch falls back to unversioned when opt-in is enabled.
test/Worker/Core.Tests/DependencyInjection/UseWorkItemFiltersTests.cs	Validates filter wildcard emission for mixed registrations when fallback is enabled, and strict versioning behavior.
test/Worker/Core.Tests/DependencyInjection/DefaultDurableTaskWorkerBuilderTests.cs	Ensures enabling fallback emits a warning log during worker build.
src/Worker/Core/Logs.cs	Adds warning log (EventId 606) for unversioned fallback enablement and replay-safety caveat.
src/Worker/Core/DurableTaskWorkerWorkItemFilters.cs	Emits wildcard version lists for names that can accept unknown versions via unversioned fallback.
src/Worker/Core/DurableTaskWorkerOptions.cs	Adds UnversionedFallbackMode enum and VersioningOptions.UnversionedFallback with replay-compat guidance.
src/Worker/Core/DurableTaskRegistryExtensions.cs	Builds factories with awareness of the configured unversioned fallback mode.
src/Worker/Core/DurableTaskFactory.cs	Enables optional unversioned catch-all dispatch for unmatched versioned requests.
src/Worker/Core/DependencyInjection/DurableTaskWorkerBuilderExtensions.cs	Propagates UnversionedFallback through UseVersioning(...).
src/Worker/Core/DependencyInjection/DefaultDurableTaskWorkerBuilder.cs	Logs warning when fallback is enabled and passes worker options into factory construction.
src/Abstractions/TaskOptions.cs	Updates documentation to reflect opt-in unversioned fallback behavior.
samples/UnversionedFallbackSample/UnversionedFallbackSample.csproj	Adds a new runnable sample project demonstrating the feature.
samples/UnversionedFallbackSample/README.md	Documents how to run the sample and expected behavior/output.
samples/UnversionedFallbackSample/Program.cs	Implements end-to-end DTS emulator demonstration of exact-match vs fallback dispatch.
README.md	Adds the new sample to the repository’s versioning sample list.
Microsoft.DurableTask.sln	Adds the new sample project to the solution.

[cgillum]

Posted on my behalf after a review pass with GitHub Copilot CLI. The lens here is API ergonomics and customer confusion — not correctness. The implementation itself looks sound; these are concerns about how the surface will land with users in the wild.

A few things I'd like the author and reviewers to consider before this ships, roughly in order of likely user impact:

1. The WhenNoExactMatch name overlaps with the pre-existing implicit fallback

Even with Never, the factory already falls back to an unversioned registration "when no exact match exists" — as long as the name is unversioned-only. So both modes are accurately described by the new enum value's name; the actual difference is "even when the name has versioned siblings." The xml-doc explains this, but the enum name alone doesn't reinforce it. Worth considering a name that captures the "mixed names" distinction (e.g. CatchAll, or doc-clarification at minimum).

2. Single switch governs both activities AND orchestrators

This is the biggest practical foot-gun. Replay-determinism risk is almost entirely on the orchestrator side; activities are stateless and replay-safe in comparison. The safest migration path ("turn on fallback for activities, keep orchestrators pinned") isn't expressible today. Splitting into two properties (e.g. OrchestratorUnversionedFallback, ActivityUnversionedFallback) would give users a safer onboarding ramp. This is also a one-way door — adding the split later is itself a breaking-ish change.

3. No per-dispatch observability — only a startup warning

EventId 606 fires once at Build(). There's no log/metric emitted when a versioned request is actually served by the unversioned registration. A user asking "did my v1.5 instance run on LegacyImpl or CatchAllImpl?" has no telemetry to answer it — which is exactly the question they'll be asking when something looks off. A debug/info log on the fallback path in DurableTaskFactory.TryCreateOrchestrator / TryCreateActivity would be low-overhead and high-diagnostic-value.

4. Strict + WhenNoExactMatch silently no-ops

Correct behavior, and tested — but undocumented. Customers will enable both and report "fallback doesn't work." Recommend an explicit remark in the xml-doc: "This setting has no effect when MatchStrategy is Strict — the strict filter narrows dispatch to the worker's exact version before fallback can apply."

5. CurrentOrOlder interaction is undocumented

With CurrentOrOlder + WhenNoExactMatch, the filter emits a wildcard but EvaluateOrchestrationVersioning still rejects newer-than-worker versions via FailureStrategy. So fallback works for "old/unknown" versions but not "newer" ones. Reasonable, but non-obvious; users with FailureStrategy = Fail may be surprised that enabling fallback doesn't prevent version-driven failures.

6. Setting lives in VersioningOptions but applies regardless of MatchStrategy

MatchStrategy defaults to None. Users who haven't opted into versioning will assume VersioningOptions doesn't apply to them — but UnversionedFallback is honored regardless. The FailureStrategy xml-doc notes "If MatchStrategy is None, this value has no effect" — UnversionedFallback deserves an inverted scope note: "This setting applies regardless of MatchStrategy."

7. No client-side visibility = environment drift risk

UnversionedFallback is a worker-side setting. A client scheduling TaskOptions.Version = "v1.5" has no way to know whether the receiving worker honors it via the unversioned registration. The same code can succeed in dev/test (fallback on) and fail in prod (fallback off), or vice versa, with no schedule-time signal. The modified xml-doc on TaskOptions.Version in src/Abstractions/TaskOptions.cs arguably makes this worse by referencing worker-side behavior in a client-side type — users may assume there's a per-call escape hatch when there isn't.

8. Never is technically "Never*" (*for mixed names)

The implicit unversioned-only fallback never goes away — there's no "exact-match-only, no fallback ever" mode. Pre-existing behavior, not a regression, but introducing UnversionedFallbackMode invites the question. Worth deciding now whether a future strict/lockdown enum value should exist, since adding it later is itself a behavior expansion.

---

Suggested mitigations, cheapest first:

• Doc-clarify Never so the existing implicit unversioned-only fallback is unmistakable.
• Add a <remarks> block covering the Strict / CurrentOrOlder / FailureStrategy interactions.
• Add a per-dispatch debug log on the fallback path in DurableTaskFactory.
• Strongly consider splitting orchestrator and activity fallback into two properties before this ships.

None of this is blocking from a correctness standpoint — feel free to push back on any of these. Mostly trying to surface things now while the API surface is still cheap to change.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

src/Worker/Core/DurableTaskRegistryExtensions.cs:12

• The PR description calls out DurableTaskRegistryExtensions.BuildFactory(options, loggerFactory?) as part of the public API surface, but the containing type DurableTaskRegistryExtensions is internal (no access modifier), so external consumers cannot call this overload. Either make the extension class public (if intended to be public API) or update the PR description/docs to reflect that this is internal-only plumbing.

/// <summary>
/// Extensions for <see cref="DurableTaskRegistry" />.
/// </summary>
static class DurableTaskRegistryExtensions
{

[Copilot]

Pull request overview

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