chore: prepare SDK 3 and OTel 2 releases by zhongkechen · Pull Request #801 · aws/aws-durable-execution-sdk-python

zhongkechen · 2026-10-21T22:38:21Z

Prepare the coordinated Core 3.0.0 / OTel 2.0.0 release on top of #737. The plugin contract changes from shared instances to per-invocation factories; the release now includes a complete 2.x to 3.0 migration guide so consumers can update their packages, providers, and Lambda layers together.

Release scope

Package	Prepared version
Core SDK	3.0.0
OpenTelemetry	2.0.0
Extras	0.1.0
Testing	1.3.0

Core, OTel, and Extras version changes are inherited from #737. Testing keeps the previously published 1.3.0 version. The compatibility check verifies that OTel accepts later Core 3.x minor releases.

Migration guidance

Use the same section order, sentence-case headings, terminology, and version-labeled examples as the JavaScript and Java migration guides.

The new guide follows the existing 1.x-to-2.0 guide: why upgrade, porting steps, before/after examples, searches for affected code, and post-upgrade validation. It covers the removed provider wrapper, factory and invocation state ownership, OTel registration and layer upgrades, optional registration metadata, and replay/concurrency checks. The root README, Core/OTel READMEs, and release instructions link to it.

The guide also covers #737's failed-Start context change: Core 3 retains partial context-variable bindings for later hooks, handler code and cleanup. Plugins own restoration; invocation End retains token ownership and the caller remains isolated. This restack preserves the existing release metadata and passes the ten OTel package-metadata tests.

Merge order

Merge #737 first, then retarget this PR to main and refresh it. Finalize any additional release content and publication notes before publishing.

Validation

For the migration-guide update:

66 existing Python tests passed: plugin discovery, invocation-operation replay integration, and OTel package metadata.
The documented custom factory, provider object, and both OTel factory variants execute against the release source. Factory instances are fresh and carry the expected execution identity.
Python code-block syntax and the new examples' types pass (mypy with silent imported-module checking and missing-import tolerance).
Local links/anchors and git diff --check pass. The style update preserves all 10 code blocks apart from version-label comments and leaves package versions unchanged.

This update changes documentation only; cloud release acceptance remains part of final release validation.

Restacked on #737's registration-cleanup fix (e1e0ae47). Invalid loaded candidates now receive rejection cleanup; type inspection cannot interrupt notification or replace the original error. The changed validator and new regression tests match #737 exactly. Shared validation passes 1,978 Core tests, 736 OTel tests, 204 Telemetry tests, and installed-wheel compatibility checks. The final stack's focused 100-test registration run and Core type checks also pass.

Restacked on #737 after its integration of main 531969b5. This carries the worker suspension and plugin lifecycle logging fixes while preserving this PR’s own layer. The incoming replay regression uses the Core 3 factory API. Shared validation passes all 436 worker tests and 14 general conformance tests, worker type checks, package formatting and builds.

* fix(telemetry): write error shape, plain results and log envelope Write every record error as {name, message} in that key order. The plugin hooks carry only ErrorObject, which has no cause, so Python records never have a cause. Names are unchanged. Decode an opted-in operation result that is the default ExtendedTypeSerDes envelope into plain JSON values. A result that fails to decode keeps its parsed or raw value. LambdaLogExporter now prints the Lambda JSON log envelope {"timestamp","level":"INFO","message":"<record JSON>"}. * fix(telemetry): bound numbers and the log line Decode an integral Decimal to an int only when abs(n) <= 2**53 - 1. Otherwise write a float only when it round-trips exactly and is within DynamoDB's number range (38 significant digits, magnitude 1E-130 to 9.99...E+125), else str(value). DynamoDBExporter also writes any number it cannot store, including NaN and Infinity, as a string attribute, so a decoded or plain JSON result no longer makes the item fail. LambdaLogExporter.render returns the printed envelope, so the existing single truncation pass measures the line. U+2028 and U+2029 are escaped in the line, and the size check counts them escaped. Cap every error message at 8,192 characters plus an ellipsis. Truncation first drops every cause and sets droppedCauses; Python records have no cause, so this step does not change them. Plain JSON results skip the conversion walk unless they contain NaN or an infinite number. Replace the wall-clock test assertion with a count of int conversions. * docs(telemetry): describe number, line size and message limits Document the Decimal rules, including negative zero, the DynamoDB string fallback, the line limit of LambdaLogExporter, the message cap, the cause truncation step, and that Python records have no cause. State that WARN filtering applies only with the JSON log format, and which envelope-shaped results are decoded or passed through. * fix(telemetry): keep lone surrogates and measure sizes exactly json_byte_size encodes inside its try again, so a lone surrogate makes the size unknown and the record is kept instead of raising and being dropped by every size-limited exporter. json_byte_size is exact again: it no longer counts U+2028 and U+2029 as escapes. truncate_record takes an optional measure function, and the scheduler passes an exporter's measure when it has one. LambdaLogExporter measures the exact printed line, which escapes U+2028, U+2029 and lone surrogates as \uXXXX, so printing a lone surrogate never raises and other exporters no longer over-count. * fix(telemetry): cap error names and bound large integers Cap every error name, like the message, at 8,192 code points followed by an ellipsis. An int result, from an envelope or from plain JSON, whose absolute value is greater than 2**53 - 1 is written as its decimal string, like a Decimal. Plain JSON is only walked when it has a run of 16 or more digits, NaN or an infinite number. Remove the 38-digit check on the float path, which could never fail. DynamoDBExporter stores an integer with more than 38 digits but at most 38 significant digits, such as 10**38, as a number. * docs(telemetry): describe name cap, int bound and size assumptions State that names and messages are capped at 8,192 code points, the ARN and name length assumptions behind the 64 KB statement, the 128 KB worst case, the 2**53 - 1 bound for int results, lone surrogate escaping in LambdaLogExporter, and that a DynamoDB attribute can be a number in one item and a string in another.

github-actions · 2026-10-22T22:54:51Z

 ## Installation

+For an existing Core 2.x / OTel 1.x application, start with the
+[Core 3.0 / OTel 2.0 migration guide](../../docs/migration-2.x-to-3.0.md#migrate-opentelemetry-registrations).


Codex AI review · Finding arf_v1_2x33oj2suty4tp5kwuwbdamxvb

[P3] Use absolute migration links in published package READMEs

Both OTel and Core declare readme = "README.md", so these relative links are included unchanged in their PyPI descriptions. On PyPI, ../../docs/... resolves against PyPI rather than this repository, leaving users with a broken migration-guide link. Use absolute repository URLs here and in the corresponding new Core README link.

To suppress repeats, reply /ai verdict deferred, /ai verdict false-positive, or /ai verdict out-of-scope on the first nonblank line. Add rationale on later lines. A new /ai verdict accepted allows future repeats again.

github-actions · 2026-10-22T22:54:54Z

Codex AI review

One low-priority documentation issue at packages/aws-durable-execution-sdk-python-otel/README.md:18, also affecting the Core README. Tests and examples were inspected but not executed, as requested.

Reviewed commit f14ead96789b255f619a07e31187c5439b017777. Workflow run

zhongkechen force-pushed the chore/prepare-python-major-release-20261021 branch from dced913 to 24add8b Compare October 21, 2026 22:43

zhongkechen changed the base branch from main to refactor/per-invocation-plugin-instances October 21, 2026 22:43

zhongkechen added this pull request to stack #802 October 21, 2026 22:48

zhongkechen marked this pull request as ready for review October 21, 2026 22:49

zhongkechen deployed to ai-pr-review-runtime October 21, 2026 22:49 — with GitHub Actions Active

zhongkechen force-pushed the chore/prepare-python-major-release-20261021 branch from 24add8b to bd955be Compare October 21, 2026 22:49

zhongkechen deployed to ai-pr-review-runtime October 21, 2026 22:49 — with GitHub Actions Active