[Major Release]: Java SDK v2

[zhongkechen]

Major Release 2.0 Breaking Changes Summary

This document summarizes the currently open issues labeled BREAKING and organizes them using the structure from .github/DISCUSSION_TEMPLATE/major-releases.yml.

Source issue query: open BREAKING issues

Primary purpose of this major release: align Java logger metadata with the other SDKs. The headline change is renaming durableExecutionArn to executionArn, and the associated logger metadata cleanup also renames contextId to operationId and contextName to operationName. The other breaking changes are included as secondary 2.0 cleanup and correctness work.

Proposed Version Number

2.0.0

Description of the Breaking Changes

1. Align Java logger metadata with other SDKs (primary change for 2.0)
   Issue: #440, discussion #438, implementation PR #465

   • Before:

     {
       "durableExecutionArn": "arn:aws:lambda:...",
       "contextId": "child-context-id",
       "contextName": "inventory-check"
     }

   • After:

     {
       "executionArn": "arn:aws:lambda:...",
       "operationId": "child-context-id",
       "operationName": "inventory-check"
     }

2. Remove deprecated StepConfig.semantics in favor of semanticsPerRetry
   Issue: #452

   • Before:

     var config = StepConfig.builder()
             .semantics(StepSemantics.AT_MOST_ONCE_PER_RETRY)
             .build();

   • After:

     var config = StepConfig.builder()
             .semanticsPerRetry(StepSemantics.AT_MOST_ONCE_PER_RETRY)
             .build();

3. Use per-context replay status for logging and plugin callbacks
   Issue: #383

   • Before:
     • replay-aware logging decisions are based on global execution replay state
     • concurrent child contexts can emit logs or plugin events as if they were executing even while that child context is still replaying
   • After:
     • replay-aware logging decisions are based on each context's own replay state
     • concurrent child contexts suppress replay logs and report replay metadata accurately

4. Throw IllegalStateException for context validation failures instead of IllegalDurableOperationException
   Issue: #455

   • Before:
     • invalid context usage such as calling stepFuture.get() inside another step can surface as IllegalDurableOperationException
   • After:
     • the same validation failure surfaces as IllegalStateException

5. Always serialize and deserialize child context results before returning them, including large-payload and virtual child-context paths
   Issue: #456

   • Before:
     • some child context executions return the original in-memory result object on first run
     • replay may return a deserialized copy instead
   • After:
     • first run and replay both return the serialized-then-deserialized form of the child result

Justification for the Changes

1. Logger field-name consistency is the main reason for the 2.0 release. The discussion for #438 concluded that Java should align its logger field with the existing Python and JavaScript executionArn name, and PR #465 carries the related contextId to operationId and contextName to operationName cleanup.
2. StepConfig.semantics is already deprecated because it has incorrect behavior for interrupted steps. Keeping it in the API invites users onto the wrong knob and forces the SDK to preserve confusing semantics.
3. Replay-aware logging is currently inaccurate for concurrent child contexts. That can create duplicate or misleading logs and blocks correct plugin behavior for replay-sensitive integrations such as observability tooling.
4. IllegalDurableOperationException is intended for SDK or backend correctness problems. Using it for customer validation errors misclassifies the fault and makes operational handling noisier than it should be.
5. Child context return values should behave the same on first execution and replay. Today, some code paths only expose serialization problems after a replay, which makes bugs late, surprising, and harder to debug.

Changes Needed in Consuming Code

1. Update log queries, dashboards, and alerts for the new logger metadata keys

• Replace durableExecutionArn with executionArn in CloudWatch Logs Insights queries, metric filters, dashboards, parsers, and alert rules that read Java SDK logs.
• Replace contextId with operationId and contextName with operationName anywhere you parse or index Java SDK log metadata.
• If you need a mixed-version query during rollout, use a fallback expression such as:

fields coalesce(durableExecutionArn, executionArn) as durableExecutionArn,
       coalesce(contextId, operationId) as operationId,
       coalesce(contextName, operationName) as operationName
| filter durableExecutionArn = "arn:aws:lambda:..."

2. Replace semantics(...) with semanticsPerRetry(...)

• Update any StepConfig.builder().semantics(...) usage to semanticsPerRetry(...).
• Update helper methods, shared config builders, and tests that assert against config.semantics().
• If you expose wrapper APIs around step configuration, rename those wrappers now so downstream users do not inherit the deprecated term.

Migration example:

var config = StepConfig.builder()
        .retryStrategy(RetryStrategies.Presets.DEFAULT)
        .semanticsPerRetry(StepSemantics.AT_MOST_ONCE_PER_RETRY)
        .build();

• Review any structured-log ingestion pipelines that map Java SDK MDC fields into downstream schemas.

3. Rebaseline replay-sensitive logging and plugin expectations

• Revisit tests or assertions that count log lines during replay, especially for child contexts, parallel, map, and nested workflows.
• If you built custom plugins or observability logic around replay metadata, verify behavior in concurrent child-context scenarios.
• Expect fewer incorrectly emitted replay logs from child contexts after the fix.

4. Update exception handling and tests for validation failures

• Replace assertions that expect IllegalDurableOperationException for invalid context usage with IllegalStateException.
• Update any error-classification logic that treats IllegalDurableOperationException as an SDK defect signal.
• If you surface these exceptions to callers or telemetry, adjust runbooks and dashboards so validation mistakes are not classified as platform failures.

5. Make child context result types fully serialization-safe

• Ensure results returned from runInChildContext(...), concurrency branches, and virtual child contexts can survive a full SerDes round trip.
• Do not rely on object identity, transient fields, lazily initialized fields, or custom runtime-only state being preserved in returned child results.
• If you use a custom SerDes, test child-context result types explicitly on both normal-size and large-payload paths.

Validation example:

var childResult = context.runInChildContext("child", MyType.class, child -> {
    return child.step("build-result", MyType.class, step -> buildResult());
});

MyType should deserialize back into the shape your handler expects without depending on the original instance identity.

Deprecation Changes Required for Previous Versions

• Add explicit migration notes to logging docs showing the upcoming logger metadata changes: durableExecutionArn to executionArn, contextId to operationId, and contextName to operationName, along with the recommended coalesce(...) query pattern during mixed-version rollouts.
• [Done] Keep StepConfig.semantics() and StepConfig.Builder.semantics(...) deprecated in the current 1.x line, with docs and release notes pointing users to semanticsPerRetry(...).
• Call out the replay-logging behavior change in release notes before 2.0 so users with log-volume baselines or custom plugins can validate ahead of time.
• Add release-note guidance that child-context results must be serialization-safe on first run, not only on replay.
• Add a short migration note that IllegalStateException will replace IllegalDurableOperationException for context validation failures in 2.0.

Additional Context

• Primary release driver: #440 to align Java logger metadata with the other SDKs. PR #465 implements the logger metadata rename from durableExecutionArn to executionArn, plus contextId to operationId and contextName to operationName.
• Milestone 2.0 currently includes #452, #440, and #456.
• The logger field-name discussion concluded with: "We'll use executionArn only in logger and durableExecutionArn everywhere else."
• Some of the labeled issues are behavior breaks rather than public-signature breaks. They still merit major-release communication because they can affect production logging, exception handling, and determinism expectations.