zhongkechen · Oct 22, 2026
diff --git a/docs/sdk-reference/languages/index.md b/docs/sdk-reference/languages/index.md
@@ -7,3 +7,12 @@ Language-specific installation and setup for the AWS Durable Execution SDK.
 - [Java](java/index.md)
 - [Go](go/index.md)
 - [C#](csharp/index.md)
+
+## Upgrade an existing application
+
+For the 3.0 major release, follow the upgrade summary for
+[TypeScript](typescript/index.md#upgrade-from-2x-to-30),
+[Python](python/index.md#upgrade-from-2x-to-30), or
+[Java](java/index.md#upgrade-from-2x-to-30). Each summary covers package versions, plugin
+registration changes, and validation, and links to the SDK repository's full migration
+guide.
diff --git a/docs/sdk-reference/languages/java/index.md b/docs/sdk-reference/languages/java/index.md
@@ -208,18 +208,21 @@ return DurableConfig.builder()
 
 ### Load plugins dynamically
 
-`withPlugins(...)` registers plugin instances in application code. Java can also load
-plugin providers from the application class path. Set `DURABLE_EXECUTION_PLUGINS` to an
-ordered, comma-separated list of provider names:
+In 2.x, `withPlugins(...)` registers plugin instances in application code. In 3.x, it
+registers factories that create one plugin per invocation. See
+[Upgrade from 2.x to 3.0](#upgrade-from-2x-to-30) for the new contract.
+
+Java can also load plugin providers from the application class path. Set
+`DURABLE_EXECUTION_PLUGINS` to an ordered, comma-separated list of provider names:
 
 ```text
 DURABLE_EXECUTION_PLUGINS=otel-invocation,com.example.audit
 ```
 
-The SDK discovers `DurableExecutionPluginProvider` implementations with
-`ServiceLoader`, but creates only the providers named in the environment variable.
-Dynamically loaded plugins run first in the listed order, followed by plugins supplied
-through `withPlugins(...)`.
+The SDK discovers `DurableExecutionPluginProvider` implementations with `ServiceLoader`
+and selects the providers named in the environment variable. Selected dynamically loaded
+plugins run first in the listed order, followed by plugins supplied through
+`withPlugins(...)`.
 
 For a Lambda layer, place the provider JAR under `java/lib`. The JAR must contain this
 service-provider configuration file:
@@ -230,9 +233,60 @@ META-INF/services/software.amazon.lambda.durable.plugin.DurableExecutionPluginPr
 
 The file contains the provider implementation class name. If you shade multiple
 providers into one JAR, configure the build to merge `META-INF/services` entries.
-Invalid or missing providers, duplicate configured or discovered provider names, and
-incompatible provider API versions cause `DurableConfig` construction to throw
-`IllegalStateException`.
+Invalid or missing providers and duplicate configured or discovered provider names cause
+`DurableConfig` construction to throw `IllegalStateException`. In 2.x, this includes
+incompatible provider API versions. In 3.x, selected providers must implement
+`createPlugin(InvocationInfo)`; rebuild providers compiled against the old interface.
+
+## Upgrade from 2.x to 3.0
+
+Core 3.0 creates a fresh instrumentation plugin for each Lambda invocation. This isolates
+plugin state when invocations run concurrently. Applications that register no plugins,
+select none through `DURABLE_EXECUTION_PLUGINS`, and ship no plugin providers or plugin
+JARs can update their dependencies without changing handler or durable operation calls.
+
+### Upgrade dependencies together
+
+Use these coordinated versions after publication. All three artifacts use group ID
+`software.amazon.lambda.durable`:
+
+| Artifact                                     | Version |
+| -------------------------------------------- | ------- |
+| `aws-durable-execution-sdk-java`             | `3.0.0` |
+| `aws-durable-execution-sdk-java-plugin-otel` | `3.0.0` |
+| `aws-durable-execution-sdk-java-testing`     | `3.0.0` |
+
+Update the artifacts your application uses together, including test dependencies and
+Lambda layers. OTel remains optional. Java's durable OTel plugin follows the SDK version
+and uses `3.0.0`. Check `mvn dependency:tree` for older transitive SDK or plugin artifacts.
+
+### Update plugin registrations
+
+Replace `withPlugins(pluginInstance)` with a `DurableExecutionPluginFactory`, such as
+`withPlugins(info -> new MyPlugin())`. Keep shared exporters and connection pools outside
+the factory lambda, and keep invocation state on the new plugin.
+
+Replace OTel plugin constructors with `InvocationOtelPlugin.factory(...)` or
+`ExecutionOtelPlugin.factory(...)`. Choose one OTel view across code and environment
+configuration.
+
+Rebuild plugin registration code and all provider JARs against 3.x. Providers now
+implement `createPlugin(InvocationInfo)`; remove `API_VERSION`, `getApiVersion()`, and
+`getPluginType()`. Update provider layers as well as the function package. Replace
+`DurableConfig.getPluginRunner()` with `getPluginFactories()` when inspecting configured
+plugins.
+
+### Validate the upgrade
+
+Compile and test the application with the coordinated artifacts. Exercise suspension,
+resume, and concurrent invocations, then verify plugin output. A stale discovered
+provider fails startup, while a stale directly registered provider can log a warning and
+produce no telemetry. Hooks within one invocation can still run on multiple threads.
+Preserve operation names, order, nesting, and serialization while executions remain
+in flight.
+
+For all API changes and before/after examples, see the
+[Java 2.x to 3.0 migration guide](https://github.com/aws/aws-durable-execution-sdk-java/blob/51222863a604910b8d6da97b00e7dde581803a87/docs/migration-2.x-to-3.x.md).
 
 ## 2.x Upgrade
 

diff --git a/docs/sdk-reference/languages/python/index.md b/docs/sdk-reference/languages/python/index.md
@@ -38,6 +38,56 @@ The SDK provides decorators to mark functions as durable:
 
 The Python SDK uses synchronous methods and does not support `await`.
 
+## Upgrade from 2.x to 3.0
+
+Core 3.0 creates a fresh instrumentation plugin for each Lambda invocation. This isolates
+plugin state when invocations run concurrently. Applications that register no plugins,
+select none through `DURABLE_EXECUTION_PLUGINS`, and ship no plugin providers can update
+their dependencies without changing handler or durable operation calls.
+
+### Upgrade dependencies together
+
+Use these coordinated versions after publication:
+
+| Package                                    | Version |
+| ------------------------------------------ | ------- |
+| `aws-durable-execution-sdk-python`         | `3.0.0` |
+| `aws-durable-execution-sdk-python-otel`    | `2.0.0` |
+| `aws-durable-execution-sdk-python-testing` | `1.3.0` |
+
+Upgrade Core and OTel together in your requirements, lock file, deployment bundle, and
+Lambda layers. OTel remains optional, but OTel 2 requires Core 3. Testing SDK 1.3.0 already
+declares a compatible Core range and does not need a major version bump. Run
+`python -m pip check` in the built application environment.
+
+### Update plugin registrations
+
+Replace plugin instances in `plugins` with factory objects. Each factory's synchronous
+`create_plugin(info)` method must return a fresh `DurableInstrumentationPlugin` subclass
+instance. Pass a factory instance, not a bare lambda or an uninstantiated factory class
+with an ordinary instance method. Keep shared resources on the factory and invocation
+state on the plugin.
+
+Replace `InvocationOtelPlugin(...)` with `InvocationOtelPluginFactory(...)`, or
+`ExecutionOtelPlugin(...)` with `ExecutionOtelPluginFactory(...)`. Choose one OTel view
+across the decorator and `DURABLE_EXECUTION_PLUGINS`.
+
+Replace the removed `DurableInstrumentationPluginProvider` wrapper with a factory
+object. Update the distribution's `aws_durable_execution.plugins` entry point to name
+that object, then rebuild and reinstall the provider package or layer.
+
+### Validate the upgrade
+
+Check the package versions imported by the deployed function and its layers. Test a
+workflow that suspends and resumes, then test concurrent invocations and parallel
+branches. Confirm fresh plugin instances and telemetry for each invocation. Plugin
+fields do not survive suspension, and shared resources still need synchronization.
+Preserve operation names, order, nesting, and serialization while executions remain
+in flight.
+
+For all API changes and before/after examples, see the
+[Python 2.x to 3.0 migration guide](https://github.com/aws/aws-durable-execution-sdk-python/blob/df8951032df6e4fbbb0468bafd2ac09e9a2fdbd4/docs/migration-2.x-to-3.0.md).
+
 ## 2.x Upgrade
 
 When upgrading from `1.x` to `2.x`, review the Python SDK migration guide in the

diff --git a/docs/sdk-reference/languages/typescript/index.md b/docs/sdk-reference/languages/typescript/index.md
@@ -27,3 +27,50 @@ export const handler = withDurableExecution(
 ```
 
 The TypeScript SDK uses `async/await` throughout.
+
+## Upgrade from 2.x to 3.0
+
+Core 3.0 creates a fresh instrumentation plugin for each Lambda invocation. This isolates
+plugin state when invocations run concurrently. Applications that register no plugins,
+select none through `DURABLE_EXECUTION_PLUGINS`, and ship no plugin providers can update
+their dependencies without changing handler or durable operation calls.
+
+### Upgrade dependencies together
+
+Use these coordinated versions after publication:
+
+| Package                                 | Version |
+| --------------------------------------- | ------- |
+| `@aws/durable-execution-sdk-js`         | `3.0.0` |
+| `@aws/durable-execution-sdk-js-otel`    | `2.0.0` |
+| `@aws/durable-execution-sdk-js-testing` | `1.3.2` |
+
+If you use the Testing SDK, upgrade it first. Version `1.3.1` excludes Core 3 from its
+peer range; `1.3.2` supports both Core 2 and Core 3. Then upgrade Core and OTel together.
+OTel remains optional, but OTel 2 requires Core 3. Rebuild application bundles and update
+any Lambda layers containing these packages.
+
+### Update plugin registrations
+
+Replace plugin instances in `plugins` with factory objects. Each factory's synchronous
+`createPlugin(info)` method must return a fresh plugin. Keep providers and exporters
+shared where appropriate, and keep invocation state on the new plugin.
+
+Replace `new InvocationOtelPlugin(...)` with `createInvocationOtelPluginFactory(...)`,
+or `new ExecutionOtelPlugin(...)` with `createExecutionOtelPluginFactory(...)`. Choose
+one OTel view across code and environment configuration.
+
+Environment-loaded modules still export `durableExecutionPluginProvider`. Change that
+export to the factory contract and remove the legacy `pluginApiVersion` and `pluginType`
+fields. Rebuild custom provider packages and their layers.
+
+### Validate the upgrade
+
+Check the package versions resolved by the deployed function and its layers. Test a
+workflow that suspends and resumes, then test concurrent invocations. Confirm that each
+invocation gets separate plugin state, completed steps do not repeat their side effects,
+and telemetry appears for both successful and failed executions. Preserve operation
+names, order, nesting, and serialization while executions remain in flight.
+
+For all API changes and before/after examples, see the
+[TypeScript 2.x to 3.0 migration guide](https://github.com/aws/aws-durable-execution-sdk-js/blob/8740dffd3080e481a4e6cbd82106cd3f2e8d1ae5/docs/migration-2.x-to-3.0.md).