Skip to content

docs: retrieve externally stored payloads when they are decoded - #931

Merged
jmaeagle99 merged 2 commits into
mainfrom
extstore-spec-defer-retrieval
Oct 29, 2026
Merged

jmaeagle99 merged 2 commits into
mainfrom
extstore-spec-defer-retrieval

Conversation

@jmaeagle99

Copy link
Copy Markdown
Contributor

What changed

Adds a "When to retrieve" subsection to the Retrieval section of the external storage spec. An SDK retrieves a payload when it decodes it, not when the response carrying it arrives. A payload that is never decoded is never retrieved, and a raw payload is handed to the caller as the server sent it. A worker follows the same rule for a whole task: it decodes the whole task before running it, so it retrieves the whole task first.

The opening sentence of the Retrieval section now says retrieval runs when an SDK decodes payloads, not when it receives them.

Why

Describe and list responses carry payloads that callers often never read, such as memo fields, inputs, heartbeat details and schedule action arguments. An SDK that retrieves the whole response on arrival gets both cases wrong:

  • With no external storage configured, one reference in a field nobody asked for fails the call with TMPRL1105, so the caller can't even list its workflows.
  • With external storage configured, the SDK calls the driver for every stored payload in the response, on every page of a list.

This came up when implementing each SDK and was re-derived each time.

@jmaeagle99
jmaeagle99 requested review from a team as code owners October 28, 2026 23:38
@jmaeagle99
jmaeagle99 enabled auto-merge (squash) October 29, 2026 22:07
@jmaeagle99
jmaeagle99 merged commit 126944d into main Oct 29, 2026
29 checks passed
@jmaeagle99
jmaeagle99 deleted the extstore-spec-defer-retrieval branch October 29, 2026 22:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants