From c349dcbfeede15458ed3852319581a9157085074 Mon Sep 17 00:00:00 2001
From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com>
Date: Fri, 13 Nov 2026 09:38:58 +0000
Subject: [PATCH] State the confirmed aggregate completion transport limitation

---
 CHANGELOG.md |  7 +++++++
 README.md    | 10 +++++++++-
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9798633..f256692 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -47,6 +47,13 @@
   child workflows or continue as new. Other 413 and 5xx responses are
   unchanged. The README documents the completion size limit.
 
+  **Known transport limitation:** this typed failure requires the Server's
+  HTTP 413 to reach the worker. An aggregate over-limit request can currently
+  lose that response and return a transport error instead. Automatic
+  structural failure for that path is not yet qualified. The Server response
+  correction and published-artifact controls remain open in
+  [the fan-out issue](https://github.com/durable-workflow/.github/issues/228).
+
 - An update whose wait ends before its handler finishes now returns
   `Error::UpdateStillPending` instead of `Ok(Null)` (durable-workflow/.github#212).
   `update_workflow` used to return the Server's `result: null` for a 202
diff --git a/README.md b/README.md
index 05dffb6..2efb817 100644
--- a/README.md
+++ b/README.md
@@ -730,7 +730,15 @@ each command's arguments must still fit the per-payload limit. A larger
 completion, usually a very large fan-out, is refused with HTTP 413,
 `reason: "payload_too_large"` and `limit_kind: "workflow_task_completion_bytes"`.
 
-The SDK treats that refusal as a structural limit, not a transient error. It
+Automatic structural failure requires the HTTP 413 to reach the worker. A
+current native Server transport defect can close an over-limit request before
+that response is read. In that case the SDK reports a transport error, and the
+run is not yet guaranteed to fail structurally. Follow the
+[aggregate transport correction](https://github.com/durable-workflow/server/issues/1136)
+and [published fan-out acceptance](https://github.com/durable-workflow/.github/issues/228)
+before relying on automatic recovery from an over-limit completion.
+
+When the typed refusal reaches the SDK, it is a structural limit. It
 never resends the oversized completion. `Client::complete_workflow_task` returns
 `Error::WorkflowTaskCompletionTooLarge`, which carries the Server's `limit`, the
 encoded request `size` the SDK sent, and the Server's message. A `Worker`