feat: add should_complete to CompletionConfig

[ayushiahjolia]

Issue #, if available: #519

Description of changes:
Adds a should_complete predicate to CompletionConfig for map and parallel operations, giving full control over when a batch completes early.

from aws_durable_execution_sdk_python import complete_batch, continue_batch

config = CompletionConfig(
    should_complete=lambda status: (
        complete_batch() if status.success_count >= 2
        else continue_batch()
    )
)

The predicate receives a CompletionStatus snapshot (counts + per-item statuses) and returns a CompletionDecision - either continue_batch() or complete_batch(outcome). The outcome determines whether CUSTOM_COMPLETION_SUCCEEDED or CUSTOM_COMPLETION_FAILED is reported.

Key design decisions -

• Cannot be combined with threshold fields (raises ValidationError)
• Predicate must be deterministic and side-effect-free
• Replay uses the checkpointed decision, never re-invokes the predicate
• On resumed invocations, deferred until prior checkpoints replay

Testing -

• Unit tests, integration tests and examples

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Codex AI review

[P1] Restore prior terminal state before evaluating the predicate

On a resumed incomplete batch, prior child checkpoints replay asynchronously while these counters start at zero. Evaluating after whichever replay event arrives first can make a deterministic status predicate choose a different outcome than before suspension, potentially checkpointing a different result and skipping work. Determine the terminal branches present at invocation start and defer predicate evaluation until all of that state has been restored, including equivalent handling for FLAT nesting.

[github-actions]

Codex AI review

[P2] Evaluate the new STARTED snapshot before blocking

This flag is set after submission, but execution proceeds directly to events.get() rather than returning to the loop. Consequently, the predicate is not called for the PENDING to STARTED transition; with max_concurrency=1, it may never observe STARTED before the branch becomes terminal. Predicates based on scheduling state can therefore fail to complete early or block indefinitely. Continue the outer loop after any submissions, or evaluate the rebuilt snapshot immediately before waiting for events.

[github-actions]

Codex AI review

Two correctness issues affect replay determinism and STARTED-state predicates. Existing tests do not cover these event-order cases.

Reviewed commit 04483d54ad90899c9ac25a59186f685c31f88354. Workflow run