fix(sdk): report invalid suspension without pending operations

[Harini410]

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

Fixes #753

Related: #752, #370, #736, #706

Description

Problem

When a durable execution suspends without any pending operations, ExecutionManager.preSuspendCheck() previously logged a warning but allowed the SDK to return PENDING. The service subsequently rejected the output with:

InvalidParameterValueException: Cannot return PENDING status with no pending operations

This obscured the underlying cause and made it difficult to identify which operations suspended threads were waiting for. LocalDurableTestRunner also failed to surface this invalid state.

Solution

• Detect invalid suspension when no durable operation is pending and the checkpoint token has not been revoked.
• Raise a retryable IllegalDurableOperationException containing the names and IDs of awaited operations.
• Preserve thread deregistration and concurrency behavior by capturing the exception and propagating it at the DurableExecutor invocation boundary.
• Notify plugins with InvocationStatus.RETRYING when an invalid suspension is detected.
• Preserve graceful PENDING behavior when the service withholds the checkpoint token.
• Make LocalDurableTestRunner surface invalid suspension errors instead of silently returning PENDING.

Demo/Screenshots

Not applicable. The change is covered by automated unit and integration tests.

Example error message:

Invalid suspension. No operation is pending. Suspended threads were waiting for: [branch-2 (id=0-1)]

Testing

Unit Tests

Have unit tests been written for these changes?

Yes.

• DurableExecutionTest: Verifies retryable invalid-suspension exceptions, awaited-operation details, plugin notifications, and graceful handling of revoked checkpoint tokens.
• LocalDurableTestRunnerTest: Verifies that the local test runner surfaces invalid suspension errors.

Integration Tests

Have integration tests been written for these changes?

Yes.

• ParallelIntegrationTest: Reproduces awaiting a skipped parallel branch and verifies that the retryable exception identifies the branch.
• PluginIntegrationTest: Preserves the suspension plugin test by providing a valid pending operation.

Validation performed:

• mvn test — passed across all Maven reactor modules, with zero failures or errors.
• git diff --check — passed with no whitespace errors.

[Harini410]

Hello maintainers,

I've submitted PR #785 to address issue #753. The fix includes regression tests, and the full Maven test suite passes. I would appreciate your review and feedback.

Thank you for your time.

[zhongkechen]

Validated commit 1ae5075f85de10c4069268633d5dc9054fbd9900 after resolving conflicts with main (1064d0ec32e5b1650b4fa08e65ca960361c7cd1b).

Validation	Result
Full local Maven reactor — Java 17	2,740 passed; 0 failures/errors
Full local Maven reactor — Java 25	2,743 passed; 0 failures/errors
Cloud integration — Lambda Java 17	33 passed; 1 expected virtual-thread skip
Cloud integration — Lambda Java 21	36 passed; 0 failures/errors/skips
Cloud integration — Lambda Java 25	36 passed; 0 failures/errors/skips

Both local runs include 522 SDK integration tests. The default-disabled cloud tests were run separately against real Lambda; all 105 executed cloud cases passed. Java 21 Lambda was tested using a JDK 25 client.

All 110 deployed Lambda code hashes were verified against the tested build. CloudWatch scans covered 110 log groups / 929 records, with zero checkpoint-invariant or invalid-suspension errors. Two additional targeted checks of actual last-thread suspension also passed: revoked checkpoint tokens preserve PENDING, while invalid suspension with a retained token raises the retryable exception and reports RETRYING.

No new regression was detected in these runs. All temporary AWS test resources were removed.

[zhongkechen]

Approved the conflict resolution and regression validation at 1ae5075f85de10c4069268633d5dc9054fbd9900. Main's handler-thread lifecycle finalization and continuation accounting are preserved, along with the PR's retryable invalid-suspension behavior and revoked-token PENDING behavior. Full local Java 17/25 tests and cloud Java 17/21/25 integration tests passed; detailed results are recorded in the test-results comment.

[Harini410]

Thank you for the thorough validation and review! I appreciate your time and feedback.