[zhongkechen]

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.

[github-actions]

Codex AI review

No actionable findings in the six changed files. The migration guidance matches the checked-out source and release metadata. Tests and documentation examples were inspected but not executed under the read-only review constraints.

Reviewed commit 249c340b816112234c785a400dffdfd18433821c. Workflow run