feat(plugin): add user function outcome enum

[wangyb-A]

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Issue Link, if available

Closes #636

Description

Replace the boolean user-function completion flag with UserFunctionOutcome, which has SUCCEEDED, FAILED, and INCOMPLETE values.

User functions now report INCOMPLETE when durable execution suspends. Normal returns report SUCCEEDED, and thrown failures report FAILED. Deprecated boolean constructor and accessor adapters preserve compatibility for existing plugin implementations.

The OTel plugins treat incomplete functions as a neutral outcome: the attempt span remains UNSET, records the INCOMPLETE attribute, and does not record the internal suspension exception. Conformance handlers and the plugin example now consume the enum directly.

Demo/Screenshots

Not applicable. This change updates the Java plugin API and lifecycle event behavior.

Checklist

• I have filled out every section of the PR template
• I have thoroughly tested this change

Testing

mvn clean install

Result: 1,803 tests passed with 0 failures and 0 errors. The 31 skipped tests are existing cloud-only example tests.

Unit Tests

Yes. Added converter coverage for all three outcomes and OTel tests that verify incomplete attempts remain neutral and do not record the suspension exception.

Integration Tests

Yes. Updated plugin integration tests to verify successful, failed, retried, and suspended user-function outcomes. Suspension, including a CompletionException-wrapped suspension, now asserts INCOMPLETE and exposes the unwrapped error.

Examples

Updated the existing plugin example to log outcome. No new example was needed.

[ayushiahjolia]

Do we need to keep this? Plugin is in preview mode.

[github-actions]

Codex AI review

One release-blocking compatibility issue found. New outcome paths are tested, but prior-version plugin ABI compatibility is not.

Reviewed commit e495ff19b299558c93c9698ce2aebe840689a246. Workflow run

[github-actions]

Claude AI review

Replacing the boolean succeeded record component with UserFunctionOutcome outcome removes the auto-generated public succeeded() accessor and changes the canonical constructor signature, with no deprecated shim. This is a source- and binary-incompatible change to a public plugin type: any third-party DurableExecutionPlugin that reads info.succeeded() (or constructs UserFunctionEndInfo with the boolean) will fail to compile/link against the new SDK. This directly contradicts the PR description's claim that "deprecated boolean constructor and accessor adapters preserve compatibility for existing plugin implementations" — no such adapters are present in the diff.

Concrete fix: if compatibility is required, add back a @Deprecated boolean succeeded() method (return outcome == UserFunctionOutcome.SUCCEEDED;, preserving the old semantics where suspension/failure are both false) and a @Deprecated boolean-based constructor that delegates to the enum one. If the break is intentional, remove the compatibility claim from the description and call out the breaking change in the migration notes.

[github-actions]

Claude AI review

This change replaces UserFunctionEndInfo.succeeded() with a UserFunctionOutcome enum. The core mapping in BaseDurableOperation.runUserFunction (unwrap CompletionException, null-fallback, SuspendExecutionException → INCOMPLETE) and the OTel plugin handling (leave the attempt span UNSET and record no exception for INCOMPLETE, while still ending the span) are correct, and they properly fix the original defect where suspensions were reported as errored attempt spans. Internal callers, conformance/example plugins, and tests are all updated consistently, and coverage (converter, OTel neutral span, suspension, and CompletionException-wrapped suspension) is solid.

One issue: the PR removes the public succeeded() accessor and the boolean canonical constructor of UserFunctionEndInfo with no deprecated replacement, a source/binary-incompatible break for third-party plugins. See sdk/src/main/java/software/amazon/lambda/durable/plugin/UserFunctionEndInfo.java:35.

Residual test risk is low: there is no direct assertion that a CompletionException-wrapped non-suspend user error is unwrapped before reaching the plugin (only the suspend variant is tested), and the error == null fallback branch is untested, but both are minor.

Reviewed commit e495ff19b299558c93c9698ce2aebe840689a246. Workflow run