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]

The max_concurrency is no longer bound by the max threads in the pool. Maybe we can consider share the same pool for all concurrency operations.

[yaythomas]

The pool is still created with max_workers=max_in_flight, where max_in_flight = max_concurrency or len(executables))? And submission is gated on in_flight < max_in_flight.

To make sure I'm understanding, you're proposing one effectively-unbounded cached pool?

While considering this, Python’s ThreadPoolExecutor does not reap idle threads, so the pool retains its high-water thread count until invocation end, and we'd lose isolation. Maybe debugging thread names and dumps get harder too?