docs: refresh Java, TypeScript, and Python references by zhongkechen · Pull Request #300 · aws/aws-durable-execution-docs

zhongkechen · 2026-10-27T20:35:03Z

The reference pages still register plugin instances rejected by SDK 3, label Java filesystem serialization as unavailable, and omit released operation and testing APIs. Update the Java, TypeScript, and Python references and examples for the releases through October 26, 2026.

The changes cover per-invocation plugin factories, Java context-aware and filesystem serialization, OpenTelemetry setup and trace behavior, telemetry exporter/MCP APIs, custom subtypes, batch results, and local testing controls. Review corrections include Python invoke-target registration by name, TypeScript plugin-load failure timing and class-method snippets, precise filesystem storage modes, named Java provider interfaces and fatal errors, and the telemetry write-access result and prompt lifecycle.

Scope and related PRs

docs: add SDK 3 upgrade summaries #298 contains the SDK 3 upgrade summaries, including the TypeScript Testing SDK peer-range and OpenTelemetry memory-unit migration notes. Those migration notes are not repeated in the reference sections here.
.NET serialization guidance and examples belong to docs(csharp): document the per-operation serializer override (Step/Callback/Invoke/WaitForCondition/ChildContext + Map/Parallel ItemSerializer) #279/docs(csharp): document the .NET FileSystem serializer (#2540) #280. The 11 reopened .NET review threads remain outstanding there; docs: complete .NET operation and testing references #303 covers operation/testing references and does not change the serialization guide or examples.

Validation

Checked review claims against released TypeScript Core 3.0.0, Python Core 3.0.0/Testing 1.4.0, Java 3.0.0, and telemetry MCP/exporter 1.0 source.
Zensical 0.0.40 clean build, full-site Markdown formatting/spelling, hidden-character checks, example-reference checks, and vendored-asset integrity checks passed. All 694 examples are referenced.
Checked local links and anchors across all 18 changed rendered pages.
Compiled all eight TypeScript hook snippets inside plugin classes, plus the complete example, against Core 3.0.0. Runtime checks confirm invalid factories return FAILED on every invocation before the handler runs and verify filesystem undefined/null and overflow round trips.
Python runtime checks confirm bare/qualified-name invoke registration, failure when registering the ARN itself, and filesystem None and overflow round trips.
git diff --check passed. Validation harnesses remain outside the PR.
The follow-up review fixes address all 32 current TypeScript, Python, and Java threads. Re-ran the clean build and full-site quality checks, and verified local links and anchors on all 10 pages changed by the follow-up. The review wording was checked against released SDK source and the Lambda API.

Generated HTML and the browser DOM were inspected directly. Chromium loaded the localhost preview but produced blank screenshots, so visual screenshot verification was unavailable. No SDK implementation changed. Cloud integration and full cross-SDK conformance were not run.

SilanHe · 2026-10-28T20:22:03Z

+
+    A `FileSystemSerializer` built without an inner serializer only resolves the global
+    serializer when it is used through a per-operation slot (for example
+    `StepConfig.Serializer`). Using it without a bound inner serializer throws


C# failure mode is half right. NotSupportedException is thrown when used as a plain ILambdaSerializer. InvalidOperationException is thrown only when the inner serializer is missing.

Fixed in the new PR #303

aws-durable-execution-docs PR #303: complete .NET operation and testing references doesn't change this file. Not addressed in the current version of aws-durable-execution-docs PR #280: document the .NET FileSystem serializer.

SilanHe · 2026-10-28T20:22:03Z

+using Amazon.Lambda.Serialization.SystemTextJson;
+
+// The inner serializer controls the on-the-wire format. Wrap one to compress results before
+// they are written to the filesystem — FileSystemSerializer just handles storage.


Four em-dashes, plus long comments that repeat the page prose. Both break the authoring guide.

Fixed in the new PR #303

aws-durable-execution-docs PR #303: complete .NET operation and testing references doesn't change this file. Not addressed in the current version of aws-durable-execution-docs PR #280: document the .NET FileSystem serializer.

SilanHe

might be easier to review if we split this doc PR up into smaller PRs per language or per associated per language PRs

yaythomas · 2026-10-28T21:41:31Z

+    Not yet supported in the .NET SDK. Set `FileSystemSerializer` per operation via
+    `StepConfig.Serializer` (or `ItemSerializer` for Map/Parallel). An execution-wide default
+    serializer is not supported. The `ILambdaSerializer` you
+    register at the host boundary applies to any operation that does not set its own.


"Not yet supported" and "is not supported" say the same thing, and "yet" promises future work. The Java tab gives the reason, and the same reason applies here: FileSystemSerializer throws NotSupportedException at the host boundary. How about this?

The FileSystem serializer cannot be the handler-wide default, because the host-boundary serializer also handles Lambda input and output, which have no operation identity. Set it per operation through StepConfig.Serializer or ItemSerializer.

Closed here because the C# filesystem-guide changes were removed from #300. The handler-boundary explanation remains applicable to #280: plain ILambdaSerializer calls lack operation identity and throw NotSupportedException. The narrowed #303 excludes this guide, so this is a scope resolution rather than a landed fix there.

Not addressed in the current version of aws-durable-execution-docs PR #280: document the .NET FileSystem serializer.

yaythomas · 2026-10-28T21:41:31Z

        var config = new CallbackConfig
        {
            Timeout = TimeSpan.FromHours(1),
+            Serializer = new DefaultLambdaJsonSerializer(),


DefaultLambdaJsonSerializer is also the usual host-boundary serializer, so this override looks the same as the default. The Step and Map examples use CamelCaseLambdaJsonSerializer. Could this one use it too?

Closed here after removing the C# serialization examples from #300. The callback example remains owned by #279/#280, where changing it to CamelCaseLambdaJsonSerializer would make the override visible. The narrowed #303 excludes that example; it has not applied this correction to those PRs.

Not addressed in the current version of aws-durable-execution-docs PR #280: document the .NET FileSystem serializer.

zhongkechen · 2026-10-28T21:58:00Z

might be easier to review if we split this doc PR up into smaller PRs per language or per associated per language PRs

I'll split C#/.Net doc updates into separate PRs and let @GarrettBeatty handle them

Update Java, TypeScript, and Python references for released serialization, plugin factories, telemetry, operation, and testing APIs. Keep .NET changes in a separate pull request. Validate review feedback against released SDK source. Fix Python invoke registration, plugin failure timing, hook snippets, telemetry details, and shared filesystem guidance. Keep migration notes in the upgrade summaries. Run formatting, spelling, example-reference and generated-HTML checks, plus a clean Zensical build. Compile the eight TypeScript hook snippets and run focused TypeScript and Python behavior checks.

Clarify null defaults and per-branch serializer precedence in one place. Remove repeated filesystem constructor guidance and restore spacing in the examples after removing redundant comments. Recheck the C# feedback carried from PR #300 into PR #303. Documentation quality checks, example references, the clean site build, and generated HTML links pass. Example changes contain only whitespace.

Document missing operation config signatures, incremental parallel branches, custom subtype rules, terminal serializer failures, and local checkpoint-token omission for Core 2.2.0 and Testing 1.1.0. Leave the serialization guide and its examples to PRs #279 and #280. Keep shared prose and other language updates in PR #300. All remaining Markdown changes are inside C# tabs; no file overlaps #279 or #280. Validate formatting, spelling, snippets, vendored assets, rendered links, and a clean Zensical build. Retained examples match the previously compiled and runtime-checked versions.

yaythomas · 2026-10-29T01:33:31Z

+    Set `CallbackConfig.Serializer` to deserialize the callback payload with a specific
+    `ILambdaSerializer`. When it is `null` (default), the payload the external system
+    delivers is deserialized with the `ILambdaSerializer` registered at the host boundary.
+    Only the deserialize path is used for callbacks.


Not addressed in the current version of aws-durable-execution-docs PR #280: document the .NET FileSystem serializer.

yaythomas · 2026-10-29T01:33:33Z

+    Set `MapConfig<TItem>.ItemSerializer` (and `ParallelConfig.ItemSerializer`) to serialize
+    each item / branch **result** with a specific `ILambdaSerializer`. When `null` (default),
+    item results use the `ILambdaSerializer` registered at the host boundary. There is no
+    separate whole-result serializer: the aggregated batch envelope (per-item statuses and
+    completion reason) is an SDK-internal, source-generated structure and is not
+    user-serialized: only the per-item results are.


Not addressed in the current version of aws-durable-execution-docs PR #280: document the .NET FileSystem serializer.

yaythomas · 2026-10-29T01:33:35Z

+    holds only the pointer. `FileSystemStorageMode.Overflow` keeps the result inline until it
+    would exceed the durable execution checkpoint size limit, then spills to a file.


Not addressed in the current version of aws-durable-execution-docs PR #280: document the .NET FileSystem serializer.

yaythomas · 2026-10-29T01:33:36Z

+    Not yet supported in the .NET SDK. Set `FileSystemSerializer` per operation via
+    `StepConfig.Serializer` (or `ItemSerializer` for Map/Parallel). An execution-wide default
+    serializer is not supported. The `ILambdaSerializer` you
+    register at the host boundary applies to any operation that does not set its own.


Not addressed in the current version of aws-durable-execution-docs PR #280: document the .NET FileSystem serializer.

yaythomas · 2026-10-29T01:33:38Z

        var config = new CallbackConfig
        {
            Timeout = TimeSpan.FromHours(1),
+            Serializer = new DefaultLambdaJsonSerializer(),


Not addressed in the current version of aws-durable-execution-docs PR #280: document the .NET FileSystem serializer.

Describe pause and resume, subtype comparisons, and early completion in terms of current behavior. Keep migration steps in the upgrade guide. Make ESLint guidance easier to find and link to the current plugin README for configuration details.

Restore TypeScript and Python path, preview, and default-serdes guidance. Qualify Java callback and invoke requirements and describe current APIs. Remove the incorrect S3 Files durability warning and release-bound prose.

Remove release-specific installation and migration text from the reference pages. Clarify invocation trace headers, chained-invoke parenting, plugin factory validation, and hook waiting semantics. Link Powertools logging to the shared execution metadata reference and remove confusing fallback trace and memory attribute details.

zhongkechen deployed to ai-pr-review-runtime October 27, 2026 20:35 — with GitHub Actions Active

zhongkechen had a problem deploying to ai-pr-review-runtime October 27, 2026 20:35 — with GitHub Actions Failure

zhongkechen changed the title ~~docs: refresh references for October SDK releases~~ docs: refresh references for recent SDK releases Oct 27, 2026

zhongkechen had a problem deploying to ai-pr-review-runtime October 27, 2026 21:45 — with GitHub Actions Failure

SilanHe self-requested a review October 28, 2026 19:44

This comment was marked as duplicate.

Sign in to view

SilanHe reviewed Oct 28, 2026

View reviewed changes

Comment thread docs/testing/api-reference.md Outdated

SilanHe reviewed Oct 28, 2026

View reviewed changes

yaythomas requested changes Oct 28, 2026

View reviewed changes

zhongkechen force-pushed the docs/refresh-released-sdk-reference branch from 4c3768b to b6aa899 Compare October 28, 2026 22:01

zhongkechen had a problem deploying to ai-pr-review-runtime October 28, 2026 22:01 — with GitHub Actions Failure

zhongkechen mentioned this pull request Oct 28, 2026

docs: complete .NET operation and testing references #303

Draft

zhongkechen changed the title ~~docs: refresh references for recent SDK releases~~ docs: refresh Java, TypeScript, and Python references Oct 28, 2026

zhongkechen requested review from SilanHe and yaythomas October 28, 2026 22:31

SilanHe reviewed Oct 29, 2026

View reviewed changes

yaythomas requested changes Oct 29, 2026

View reviewed changes

zhongkechen added 2 commits October 29, 2026 01:40

docs: clarify filesystem serialization

5bcf863

Restore TypeScript and Python path, preview, and default-serdes guidance. Qualify Java callback and invoke requirements and describe current APIs. Remove the incorrect S3 Files durability warning and release-bound prose.

zhongkechen had a problem deploying to ai-pr-review-runtime October 29, 2026 01:42 — with GitHub Actions Failure

		holds only the pointer. `FileSystemStorageMode.Overflow` keeps the result inline until it
		would exceed the durable execution checkpoint size limit, then spills to a file.

Conversation

zhongkechen commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Scope and related PRs

Validation

Uh oh!

This comment was marked as duplicate.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

SilanHe left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zhongkechen commented Oct 28, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch had an error being deployed

Reviewers

Uh oh!

Assignees

Labels

zhongkechen commented Oct 27, 2026 •

edited

Loading

SilanHe left a comment •

edited

Loading