feat: limit in-flight operations in map/parallel

[yaythomas]

Description of changes:

BREAKING CHANGE -- see the behavior changes section; config validation, result shape, and the large-result summary payload format change in this PR.
max_concurrency previously sized the thread pool only, so branches that suspended (invoke, wait, callbacks) released their thread and the next item started immediately. All items were initiated at once regardless of the configured limit.

Rework the concurrency executor around a single coordinator loop:

• The calling thread owns all branch state and schedules work; worker threads only run branches and report outcomes on a queue. No locks remain in the module.
• max_concurrency now bounds in-flight branches. A suspended branch keeps its slot until it reaches a terminal state, matching the JS and Java SDKs. When every in-flight branch is suspended, the parent suspends with the earliest resume timestamp, or indefinitely.
• Branches start in index order and operation ids derive from the branch index, so scheduling stays deterministic across invocations.
• Timed suspends resume in-process via the event queue timeout, replacing the TimerScheduler background thread.
• Consolidate completion logic (thresholds and reason inference) into CompletionPolicy, replacing ExecutionCounters and the duplicated logic in BatchResult.
• Stop scheduling when a branch is orphaned: an ancestor completed, so all further checkpoints under it would be rejected.
• Record the completion decision in an SDK-owned envelope and obey it on replay. When a map/parallel result exceeds the checkpoint size limit, the SDK now writes the parent payload itself: type, totalCount, completionReason, the started-branch index set (startedIndexes, or completedIndexes when smaller), and stats fields (startedCount, successCount, failureCount, status). Replay reads the record and reconstructs the exact live result — same items, same statuses, same reason — instead of re-deriving from child checkpoints. A configured summary_generator no longer produces the payload: its output is stored verbatim under the envelope's summary key for observability and is never read by the SDK, so custom generators get exact replay and cannot displace the record. An exception raised by a custom generator propagates and fails the operation, matching the JS SDK. The envelope is checkpointed as provided; a payload exceeding the checkpoint size limit fails the operation with the service's payload validation error (terminal map failure, no retry loop -- checkpoint API 4xx errors are classified non-retryable). The envelope is written and parsed with plain JSON, independent of any configured serdes. Payloads without the record (checkpoints written by earlier SDK versions) fall back to checkpoint derivation, preserving old behavior. This also makes FLAT-nesting results reconstructable on replay, which checkpoint derivation cannot discriminate.

Behavior changes

• BatchResult omits never-started branches (matching the JS SDK). Previously every item appeared as STARTED even when an early completion meant it never ran; total_count now reflects branches that actually started.
• Configs with only min_successful set no longer fail fast on the first failure. The old tolerance check ignored min_successful when deciding whether criteria existed, so a single failure stopped scheduling; scheduling now continues past failures until min_successful is reached or all items finish, matching the JS and Java SDKs.
• Config bounds are validated at construction, matching the Java SDK: max_concurrency and min_successful must be at least 1, tolerated_failure_count non-negative, tolerated_failure_percentage within 0–100. Previously max_concurrency=0 silently meant unlimited and min_successful=0 silently meant all items.
• min_successful greater than the item count now raises ValidationError at the operation call, matching the Java SDK. Previously it silently degraded to "complete when everything finishes".
• CompletionConfig.all_completed() now tolerates all failures (tolerated_failure_percentage=100), matching its documentation and the Java SDK. Previously its all-None fields selected the fail-fast default, so a single failure stopped scheduling -- the opposite of the factory's name.
• Large map/parallel results now checkpoint a summary at all. The summary generator was previously attached to the iteration child contexts rather than the map/parallel context itself, so the parent payload of a large result was an empty string and the execution history carried no summary.
• A branch whose own item result exceeds the checkpoint size limit no longer fails. The default summary generator was previously applied to the raw item value, which raised and silently failed the branch. Large item results now checkpoint an empty payload with replay-children set and re-execute on replay, matching the JS SDK.
• The MapSummaryGenerator and ParallelSummaryGenerator classes are removed (not exported from the package root; reachable only by deep import, referenced by no examples or docs, and never invoked on the released large-result path). The envelope writes their fields directly.
• The large-result summary payload is the envelope for every execution. The default fields are a superset of the previous default summary (same keys and meanings, plus the index set, and startedCount now on map as well as parallel). Output from a custom summary_generator appears under the summary key instead of replacing the whole payload.

Testing

• Unit: 1424 tests, typecheck and format clean, examples suite green.
• Fatal errors from branches (for example a background checkpoint failure) propagate to the caller instead of being recorded as branch failures, and failed FLAT branches carry the same error type live and on replay.
• Cloud conformance (in-repo aws-durable-execution-sdk-python-conformance-tests, deployed against this branch's SDK): all 9 suites pass with 145/145 validations — map 20/20 (including 9-16 MapLargeResult, which exercises the summarized-replay path, and the early-stop cases for fail-fast, min-successful, and failure-tolerance semantics), parallel 22/22, callback 19/19, child 17/17, invoke 16/16, step 20/20, wait 5/5, wait_for_callback 15/15, wait_for_condition 11/11.

Issue #, if available:
Closes #279

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

[zhongkechen]

Should ValidationError be checkpointed?

[yaythomas]

The raise occurs inside map_handler, which runs inside child_handler's try block, so it is checkpointed and the map context FAILs terminally with error_type: ValidationError, surfacing as a catchable ChildContextError.

That's deterministic (replay re-raises the recorded error), loud, and visible in history. And the current placement means the error behaves exactly like every other failure inside a map.

The alternative is to validate in context.py before the child context starts, so no STARTED-then-FAILED context appears in history, which is closer to matching Java's constructor validation + throw IllegalArgumentException?

So the diffs is
a) ChildContextError wrapping ValidatorError, with a STARTED/FAILED checkpoint for the map (current)
vs
b) a bare exception at execution level?

There's prob an argument to make for either. I instinctively would've thought a STARTED/FAILED on the map makes sense since this can only rear its head at runtime rather than design time (like a compiler err), but happy to reconsider if you think otherwise?

[zhongkechen]

Would this cause the threads and resources to accumulate if users heavily use early return with long running tasks