docs: record Java payload offloading architecture by zhongkechen · Pull Request #678 · aws/aws-durable-execution-sdk-java

zhongkechen · 2026-09-02T18:26:03Z

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Issue Link, if available

Related to #463 and #366.

Description

Add ADR-006 selecting a dedicated PayloadOffloader as the Java SDK payload-storage architecture.
Record the meeting decision to prioritize an idiomatic Java API over cross-language API parity.
Compare context-aware SerDes, composable pipeline, and dedicated offloader options.
Cover replay safety, error handling, performance, chained invokes, and existing custom SerDes configurations.
Use an explicit disablePayloadOffloading() operation-builder API rather than a public disabled sentinel.
Clarify that Python and JavaScript may retain filesystem SerDes APIs when those are more idiomatic for their languages.
Mark ADR-005 as superseded by ADR-006 without changing its historical design content.

Demo/Screenshots

Not applicable; documentation-only change.

Checklist

I have filled out every section of the PR template
I have thoroughly reviewed this change

Testing

git diff --cached --check
Verified balanced Markdown code fences and no trailing whitespace
No code tests were run because this change only adds and updates ADR documentation

Sign in to view

+The SDK-owned envelope distinguishes inline data from an external reference and carries preview, producer ownership,
+content digest, producer context, and load semantics. `PayloadOffloadContext` explicitly provides execution identity,
+payload kind, operation metadata, attempt, and the original serialization value when available.


Sign in to view

+The SDK envelope uses a reserved marker and version. During decoding:
+
+- data without the reserved marker is a legacy raw `SerDes` string and is passed directly to `SerDes`;
+- a recognized supported envelope is validated and decoded;
+- a recognized malformed or unsupported envelope fails closed;
+- disabling offloading writes the legacy raw format rather than an envelope.


zhongkechen · 2026-09-02T23:57:13Z

Sign in to view

+public interface PayloadOffloader {
+    StoredPayload store(
+            String serializedPayload,
+            PayloadOffloadContext context);
+
+    String load(
+            StoredPayload payload,
+            PayloadOffloadContext context);
+}


Good point. We will make lifecycle ownership explicit rather than add an SDK-managed release or expiry mechanism. The SDK does not know the application retention period for an execution, its history, or delayed result decoding, so PayloadOffloader will remain a store/load contract and the SDK will never delete stored payloads, including after operation completion or checkpoint failure. Applications and storage implementations must manage retention and garbage collection externally, retain immutable references while any execution, replay, history inspection, or result decoder may need them, and clean up checkpoint-failure orphans according to their own lifecycle policy. The SDK-provided execution and entity metadata can be used to organize that cleanup.

Sign in to view

+public record StoredPayload(
+        String reference,
+        Map<String, Object> preview) {}


Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

github-actions · 2026-09-03T00:53:52Z

+Ordinary Lambda payloads should remain the default. An offloaded request should use a versioned source frame and
+two-sided opt-in so a standard function, an older SDK, or a target using a different payload contract does not receive
+an opaque storage envelope accidentally.


Codex AI review · Finding arf_v1_a7axren6v3zm3tulbax62pwffy

[P1] Authenticate cross-execution reference frames. Two-sided opt-in prevents accidental incompatibility but does not prove the claimed producer context, reference, or tenant; a forged or leaked frame could load another execution's payload from shared storage. Require a signed/MACed capability or service-attested source plus tenant validation, with forged-reference and cross-tenant rejection tests.

github-actions · 2026-09-03T00:53:53Z

+
+The SDK envelope uses a reserved marker and version. During decoding:
+
+- data without the reserved marker is a legacy raw `SerDes` string and is passed directly to `SerDes`;


Codex AI review · Finding arf_v1_rheryyqbwobolm46tjwl6gxi6z

[P1] Make legacy detection collision-safe. SerDes historically permits arbitrary strings, so an existing checkpoint—or raw payload written while offloading was disabled—may already match the marker and be misread as an envelope. Use out-of-band format metadata or another migration scheme that cannot reinterpret legacy user data, and test a valid legacy payload matching the proposed marker.

github-actions · 2026-09-03T00:53:55Z

+public interface PayloadOffloader {
+    StoredPayload store(
+            String serializedPayload,
+            PayloadOffloadContext context);
+
+    String load(
+            StoredPayload payload,
+            PayloadOffloadContext context);
+}


Codex AI review · Finding arf_v1_zpmaifv6futdsizdh74idrh7ss

[P1] Define a lifecycle for stored references. A store/load-only contract cannot reclaim a successful publication whose checkpoint fails, while backend cleanup without a specified retention horizon can break late replay, history inspection, or root decoding. Define cleanup ownership and minimum safe retention, or add commit/expiry/release support, with checkpoint-failure and late-replay tests.

github-actions · 2026-09-03T00:53:56Z

+public record StoredPayload(
+        String reference,
+        Map<String, Object> preview) {}


Codex AI review · Finding arf_v1_mrow7c5lmd7sgoiwhmoypzf7pw

[P2] Make preview data immutable and wire-safe. This record exposes a mutable Map<String, Object> directly; mutation after sizing can change the final envelope, and arbitrary object graphs may fail SDK-owned serialization. Constrain previews to a defined wire type and defensively deep-copy them in the public model.

github-actions · 2026-09-03T00:53:58Z

Claude AI review

This PR is documentation-only: it adds docs/adr/006-java-payload-offloading.md (a new ADR comparing three payload-offloading designs and recording the decision to adopt a dedicated PayloadOffloader) and updates the Status line of docs/adr/005-filesystem-serdes.md to mark it superseded.

Review notes:

Verified all ~14 fenced code blocks in the new ADR open/close in matched pairs (consistent with the PR's stated whitespace/fence check).
Verified the Status line edit in ADR-005 retains the trailing two-space Markdown hard break used elsewhere in docs/adr/ (e.g. ADR-001), so the Status/Date lines still render on separate lines. A prior review pass on an earlier revision of this branch had flagged this line as dropping the hard break; that issue is no longer present in the current diff, so it is not repeated here.
Cross-checked the ADR's description of the existing SerDes interface and JacksonSerDes against the actual source (sdk/src/main/java/.../serde/SerDes.java, JacksonSerDes.java) — the ADR's characterization is accurate.
Checked heading hierarchy, the numbered option list vs. section ordering, and the comparison table's column counts — all consistent.
Internal links (006-java-payload-offloading.md, issue #463/#366 URLs) resolve to the correct new filename and existing issue references.

No code, public API, checkpoint/replay, concurrency, or test files are touched by this PR, so the SDK-specific correctness/regression concerns (replay semantics, stable operation IDs, thread coordination, etc.) do not apply. No residual test risk: per AGENTS.md/CONTRIBUTING.md, documentation-only changes do not require unit/integration tests, and none were expected here.

No actionable findings.

Reviewed commit 4d751be9025f5188d73fa525dd0e72105d864f40. Workflow run

github-actions · 2026-09-03T00:53:58Z

Codex AI review

Four architecture contract gaps remain around cross-execution trust, replay compatibility, payload lifecycle, and immutable preview data.

Reviewed commit 4d751be9025f5188d73fa525dd0e72105d864f40. Workflow run

docs: record Java payload offloading architecture

8331e58

zhongkechen requested a review from a team September 2, 2026 18:26

zhongkechen temporarily deployed to ai-pr-review-runtime September 2, 2026 18:26 — with GitHub Actions Inactive

docs: clarify cross-language API consistency

4202b81

zhongkechen temporarily deployed to ai-pr-review-runtime September 2, 2026 18:57 — with GitHub Actions Inactive

zhongkechen had a problem deploying to ai-pr-review-runtime September 2, 2026 18:57 — with GitHub Actions Failure

github-actions Bot reviewed Sep 2, 2026

View reviewed changes

Comment thread docs/adr/006-java-payload-offloading.md Outdated

github-actions Bot reviewed Sep 2, 2026

View reviewed changes

Comment thread docs/adr/006-java-payload-offloading.md Outdated

github-actions Bot reviewed Sep 2, 2026

View reviewed changes

Comment thread docs/adr/006-java-payload-offloading.md

github-actions Bot reviewed Sep 2, 2026

View reviewed changes

Comment thread docs/adr/006-java-payload-offloading.md Outdated

This comment has been minimized.

Sign in to view

docs: define payload offloading compatibility contracts

b073512

zhongkechen temporarily deployed to ai-pr-review-runtime September 2, 2026 20:27 — with GitHub Actions Inactive

Merge branch 'main' into docs/filesystem-offloading-comparison

4c6822c

zhongkechen mentioned this pull request Sep 2, 2026

feat: add payload offloader core runtime #649

Open

zhongkechen temporarily deployed to ai-pr-review-runtime September 2, 2026 21:54 — with GitHub Actions Inactive

This was referenced Sep 2, 2026

docs: add payload offloader examples and E2E coverage #683

Open

feat: add filesystem payload offloader and retries #681

Open

test: add payload offloader runners and integration coverage #682

Open

github-actions Bot reviewed Sep 2, 2026

View reviewed changes

Comment thread docs/adr/005-filesystem-serdes.md Outdated

This comment has been minimized.

Sign in to view

github-actions Bot reviewed Sep 2, 2026

View reviewed changes

Comment thread docs/adr/006-java-payload-offloading.md

Comment on lines +307 to +309

public record StoredPayload(

String reference,

Map<String, Object> preview) {}

This comment was marked as outdated.

Sign in to view

This comment has been minimized.

Sign in to view

Update docs/adr/005-filesystem-serdes.md

4d751be

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

zhongkechen temporarily deployed to ai-pr-review-runtime September 3, 2026 00:25 — with GitHub Actions Inactive

github-actions Bot reviewed Sep 3, 2026

View reviewed changes


		The SDK envelope uses a reserved marker and version. During decoding:

		- data without the reserved marker is a legacy raw `SerDes` string and is passed directly to `SerDes`;

Uh oh!

Conversation

zhongkechen commented Sep 2, 2026

Issue Link, if available

Description

Demo/Screenshots

Checklist

Testing

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

Uh oh!

This comment has been minimized.

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

zhongkechen Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment has been minimized.

github-actions Bot Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Sep 3, 2026

Claude AI review

Uh oh!

github-actions Bot commented Sep 3, 2026

Codex AI review

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant