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 branch state before invoking the predicate

On a resumed invocation, all branches start in memory as PENDING and prior terminal checkpoints are replayed concurrently. The predicate is therefore evaluated against partial, synthetic snapshots whose order depends on worker scheduling. For example, if A previously succeeded before B failed, replay may report B first; a deterministic predicate such as “fail when B fails unless A succeeded” can now choose a different outcome and omit previously started branches. Add a restoration barrier that reconstructs all branch state present at invocation start before evaluating should_complete, then add a resume test that reverses prior checkpoint event order.

[github-actions]

Codex AI review

Found one high-severity replay-determinism defect. Current resume coverage only exercises a monotonic predicate and cannot detect restoration-order changes across multiple prior branches.

Reviewed commit 8131d24c2715a047913ba2e02e38b2bb1612bea9. Workflow run

[yaythomas]

just two minor noin-func nits :)

[yaythomas]

nit: "prefer" is a "must"? You argued on the codex review comments that resume determinism relies on monotonicity as a hard contract. A predicate that is false on the suspension time terminal set is false on every subset of it, but only if monotonicity is required.

[yaythomas]

inline `import. Please move it to the top of the module. Google style §3.13 via CONTRIBUTING → General style.