Document gRPC history compatibility boundary

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a28a3fa8-303a-4a74-8fbc-8e062e39d97f

Author: andystaples

CHANGELOG.md

@@ -41,8 +41,6 @@ import paths, `__all__`, `dir()`, and star-imports behave exactly as before.
 
 FIXED
 
-- Failed task and sub-orchestration history events now retain the host-provided
-  failure `reason` and redacted `details` alongside structured failure details.
 - Fixed `AsyncTaskHubGrpcClient` failing during construction when no current
 event loop was set. SDK-owned async gRPC channels are now created on first use,
 binding them to the event loop that performs the RPC.

azure-functions-durable/CHANGELOG.md

@@ -33,8 +33,11 @@ avoiding repeated allocation of unused worker resources.
 FIXED
 
 - The v1-compatible `get_status()` API now supports `show_history` and
-  `show_history_output`, including compacted `historyEvents` output without an
-  additional history request when history is not requested.
+`show_history_output`, including compacted `historyEvents` output without an
+additional history request when history is not requested. Failed activity and
+sub-orchestration events expose the structured `FailureDetails` supplied by
+the gRPC host, but not the v1-only top-level `Reason` and `Details` fields,
+which are not represented by the shared gRPC history protocol.
 - Check-status responses now include the standard `Retry-After: 10` polling
 header. Failed orchestrations return HTTP 200 from the wait helper by default;
 callers can request HTTP 500 responses through

azure-functions-durable/MIGRATION_GUIDE.md

@@ -269,6 +269,10 @@ instead of calling `context.set_result`.
 
 - `DurableOrchestrationContext.histories` is unavailable. Retrieve history with
   `client.get_orchestration_history(instance_id)`.
+- `get_status(show_history=True)` cannot reproduce the v1 top-level `Reason`
+  and `Details` fields for failed activities or sub-orchestrations because the
+  shared gRPC history protocol represents only structured `FailureDetails`.
+  Read `FailureDetails` when present.
 - Distributed tracing is not yet wired through the Python provider.
 - Continuous history export is not supported by Azure Functions.
 - Unusual callable signatures can be misclassified by the compatibility layer.

durabletask/history.py

@@ -94,8 +94,6 @@ class TaskCompletedEvent(HistoryEvent):
 class TaskFailedEvent(HistoryEvent):
     task_scheduled_id: int
     failure_details: task.FailureDetails | None = None
-    reason: str | None = None
-    details: str | None = None
 
 
 @dataclass(slots=True)
@@ -118,8 +116,6 @@ class SubOrchestrationInstanceCompletedEvent(HistoryEvent):
 class SubOrchestrationInstanceFailedEvent(HistoryEvent):
     task_scheduled_id: int
     failure_details: task.FailureDetails | None = None
-    reason: str | None = None
-    details: str | None = None
 
 
 @dataclass(slots=True)
@@ -290,15 +286,6 @@ def _failure_details(msg: Message, field_name: str) -> task.FailureDetails | Non
     )
 
 
-def _failure_event_kwargs(msg: Message) -> dict[str, Any]:
-    failure_details = _failure_details(msg, 'failureDetails')
-    return {
-        'failure_details': failure_details,
-        'reason': failure_details.message if failure_details is not None else None,
-        'details': failure_details.stack_trace if failure_details is not None else None,
-    }
-
-
 def _trace_context(msg: Message, field_name: str) -> TraceContext | None:
     if not msg.HasField(field_name):
         return None
@@ -503,7 +490,7 @@ def _to_serializable(value: Any) -> Any:
     'taskFailed': lambda event: TaskFailedEvent(
         **_base_kwargs(event),
         task_scheduled_id=event.taskFailed.taskScheduledId,
-        **_failure_event_kwargs(event.taskFailed),
+        failure_details=_failure_details(event.taskFailed, 'failureDetails'),
     ),
     'subOrchestrationInstanceCreated': lambda event: SubOrchestrationInstanceCreatedEvent(
         **_base_kwargs(event),
@@ -522,7 +509,7 @@ def _to_serializable(value: Any) -> Any:
     'subOrchestrationInstanceFailed': lambda event: SubOrchestrationInstanceFailedEvent(
         **_base_kwargs(event),
         task_scheduled_id=event.subOrchestrationInstanceFailed.taskScheduledId,
-        **_failure_event_kwargs(event.subOrchestrationInstanceFailed),
+        failure_details=_failure_details(event.subOrchestrationInstanceFailed, 'failureDetails'),
     ),
     'timerCreated': lambda event: TimerCreatedEvent(
         **_base_kwargs(event),

tests/azure-functions-durable/test_client_compat.py

@@ -968,9 +968,7 @@ def _fake_history():
             timestamp=started_at + timedelta(seconds=5),
             task_scheduled_id=4,
             failure_details=dt_task.FailureDetails(
-                "activity failed", "RuntimeError", "activity details"),
-            reason="activity failed",
-            details="activity details"),
+                "activity failed", "RuntimeError", "activity stack trace")),
         dt_history.SubOrchestrationInstanceCreatedEvent(
             event_id=6,
             timestamp=started_at + timedelta(seconds=6),
@@ -980,11 +978,7 @@ def _fake_history():
         dt_history.SubOrchestrationInstanceFailedEvent(
             event_id=7,
             timestamp=started_at + timedelta(seconds=7),
-            task_scheduled_id=6,
-            failure_details=dt_task.FailureDetails(
-                "child failed", "RuntimeError", "child details"),
-            reason="child failed",
-            details="child details"),
+            task_scheduled_id=6),
         dt_history.ExecutionCompletedEvent(
             event_id=8,
             timestamp=started_at + timedelta(seconds=8),
@@ -994,7 +988,7 @@ def _fake_history():
 
 
 @pytest.mark.parametrize("show_history_output", [False, True])
-async def test_get_status_projects_v1_history(show_history_output):
+async def test_get_status_projects_available_v1_history(show_history_output):
     client = _make_client()
     try:
         history_mock = AsyncMock(return_value=_fake_history())
@@ -1039,14 +1033,16 @@ async def test_get_status_projects_v1_history(show_history_output):
         assert completed["ScheduledTime"] == (
             "2026-01-01T00:00:01.000000Z")
         task_failed = events_by_type["TaskFailed"]
-        assert task_failed["Reason"] == "activity failed"
-        assert task_failed["Details"] == "activity details"
         assert task_failed["FailureDetails"]["ErrorMessage"] == (
             "activity failed")
+        assert task_failed["FailureDetails"]["StackTrace"] == (
+            "activity stack trace")
+        assert "Reason" not in task_failed
+        assert "Details" not in task_failed
         child_failed = events_by_type["SubOrchestrationInstanceFailed"]
-        assert child_failed["Reason"] == "child failed"
-        assert child_failed["Details"] == "child details"
-        assert child_failed["FailureDetails"]["ErrorMessage"] == "child failed"
+        assert "Reason" not in child_failed
+        assert "Details" not in child_failed
+        assert "FailureDetails" not in child_failed
         execution_completed = events_by_type["ExecutionCompleted"]
         assert execution_completed["OrchestrationStatus"] == "Completed"
         if show_history_output:

tests/durabletask/test_history_serialization.py

@@ -19,10 +19,8 @@
 from typing import Any, NamedTuple, cast
 
 import pytest
-from google.protobuf import timestamp_pb2, wrappers_pb2
 
 from durabletask import history, task
-import durabletask.internal.orchestrator_service_pb2 as pb
 
 _TS = datetime(2025, 1, 2, 3, 4, 5, 678901, tzinfo=timezone.utc)
 _NAIVE_TS = datetime(2024, 12, 31, 23, 59, 58)
@@ -52,40 +50,6 @@ def _failure(message: str = 'boom') -> task.FailureDetails:
     return task.FailureDetails(message, 'RuntimeError', 'Traceback...')
 
 
-@pytest.mark.parametrize(
-    ("proto_field", "expected_type"),
-    [
-        ("taskFailed", history.TaskFailedEvent),
-        ("subOrchestrationInstanceFailed",
-         history.SubOrchestrationInstanceFailedEvent),
-    ],
-)
-def test_failed_events_preserve_legacy_failure_fields_from_proto(
-        proto_field: str,
-        expected_type: type[history.HistoryEvent]):
-    timestamp = timestamp_pb2.Timestamp()
-    timestamp.FromDatetime(_TS)
-    event = pb.HistoryEvent(eventId=2, timestamp=timestamp)
-    failed_event = getattr(event, proto_field)
-    failed_event.taskScheduledId = 1
-    failed_event.failureDetails.CopyFrom(pb.TaskFailureDetails(
-        errorMessage="activity failed",
-        errorType="RuntimeError",
-        stackTrace=wrappers_pb2.StringValue(value="redacted details")))
-
-    converted = history._from_protobuf(event)  # pyright: ignore[reportPrivateUsage]
-
-    assert type(converted) is expected_type
-    assert isinstance(
-        converted,
-        (history.TaskFailedEvent,
-         history.SubOrchestrationInstanceFailedEvent))
-    assert converted.reason == "activity failed"
-    assert converted.details == "redacted details"
-    assert converted.failure_details == task.FailureDetails(
-        "activity failed", "RuntimeError", "redacted details")
-
-
 @dataclass
 class _Inner:
     """A dataclass the walker should convert wherever it is nested."""