cleanup

Signed-off-by: Filinto Duran <[email protected]>

Author: filintod

README.md

@@ -358,7 +358,7 @@ export DAPR_WF_DISABLE_DETERMINISTIC_DETECTION=false
 
 ### Async workflow authoring
 
-For a deeper tour of the async authoring surface (determinism helpers, sandbox modes, timeouts, concurrency patterns), see the Async Enhancements guide: [ASYNC_ENHANCEMENTS.md](./ASYNC_ENHANCEMENTS.md). The developer-facing migration notes are in [DEVELOPER_TRANSITION_GUIDE.md](./DEVELOPER_TRANSITION_GUIDE.md).
+For a deeper tour of the async authoring surface (determinism helpers, sandbox modes, timeouts, concurrency patterns), see the Async Enhancements guide: [ASYNC_ENHANCEMENTS.md](./ASYNC_ENHANCEMENTS.md).
 
 You can author orchestrators with `async def` using the new `durabletask.aio` package, which provides a comprehensive async workflow API:
 
@@ -376,9 +376,11 @@ with TaskHubGrpcWorker() as worker:
     worker.add_orchestrator(my_orch)
 ```
 
-Optional sandbox mode (`best_effort` or `strict`) patches `asyncio.sleep`, `random`, `uuid.uuid4`, and `time.time` within the workflow step to deterministic equivalents. This is best-effort and not a correctness guarantee.
+The sandbox (enabled by default) patches standard Python functions to deterministic equivalents during workflow execution. This allows natural async code like `asyncio.sleep()`, `random.random()`, and `asyncio.gather()` to work correctly with workflow replay. Three modes are available:
 
-In `strict` mode, `asyncio.create_task` is blocked inside workflows to preserve determinism and will raise a `SandboxViolationError` if used.
+- `"best_effort"` (default): Patches functions, minimal overhead
+- `"strict"`: Patches + blocks dangerous operations (file I/O, `asyncio.create_task`)
+- `"off"`: No patching (requires manual use of `ctx.*` methods everywhere)
 
 > **Enhanced Sandbox Features**: The enhanced version includes comprehensive non-determinism detection, timeout support, enhanced concurrency primitives, and debugging tools. See [ASYNC_ENHANCEMENTS.md](./durabletask/aio/ASYNCIO_ENHANCEMENTS.md) for complete documentation.
 
@@ -406,13 +408,10 @@ val = await ctx.wait_for_external_event("approval")
 - Concurrency:
 ```python
 t1 = ctx.call_activity("a"); t2 = ctx.call_activity("b")
-await ctx.when_all([t1, t2])
-winner = await ctx.when_any([ctx.wait_for_external_event("x"), ctx.sleep(5)])
-
-# gather combines awaitables and preserves order
-results = await ctx.gather(t1, t2)
-# gather with exception capture
-results_or_errors = await ctx.gather(t1, t2, return_exceptions=True)
+# when_all waits for all tasks and returns results in order
+results = await ctx.when_all([t1, t2])
+# when_any returns (index, result) tuple of first completed task
+idx, result = await ctx.when_any([ctx.wait_for_external_event("x"), ctx.create_timer(5)])
 ```
 
 #### Async vs. generator API differences
@@ -457,15 +456,6 @@ except Exception as e:
     ...
 ```    
 
-Or capture with gather:
-
-```python
-res = await ctx.gather(ctx.call_activity("a"), return_exceptions=True)
-if isinstance(res[0], Exception):
-    ...
-```
-
-
 - Sub-orchestrations (function reference or registered name):
 ```python
 out = await ctx.call_sub_orchestrator(child_fn, input=payload)
@@ -477,20 +467,6 @@ out = await ctx.call_sub_orchestrator(child_fn, input=payload)
 now = ctx.now(); rid = ctx.random().random(); uid = ctx.uuid4()
 ```
 
-- Workflow metadata/headers (async only for now):
-```python
-# Attach contextual metadata (e.g., tracing, tenant, app info)
-ctx.set_metadata({"x-trace": trace_id, "tenant": "acme"})
-md = ctx.get_metadata()
-
-# Header aliases (same data)
-ctx.set_headers({"region": "us-east"})
-headers = ctx.get_headers()
-```
-Notes:
-- Useful for routing, observability, and cross-cutting concerns passed along activity/sub-orchestrator calls via the sidecar.
-- In python-sdk, available for both async and generator orchestrators. In this repo, currently implemented on `durabletask.aio`; generator parity is planned.
-
 - Cross-app activity/sub-orchestrator routing (async only for now):
 ```python
 # Route activity to a different app via app_id

durabletask/aio/ASYNCIO_ENHANCEMENTS.md

@@ -63,18 +63,14 @@ with TaskHubGrpcWorker() as worker:
 
 ### 2. **Non-Determinism Detection**
 - Automatic detection of non-deterministic function calls
-- Three modes: `"off"` (default), `"best_effort"` (warnings), `"strict"` (errors)
+- Three modes: `"best_effort"` (default), `"strict"` (errors), `"off"` (no patching)
 - Comprehensive coverage of problematic functions
 - Helpful suggestions for deterministic alternatives
 
 ### 3. **Enhanced Concurrency Primitives**
-- `when_any_with_result()` - Returns (index, result) tuple
+- `when_all()` - Waits for all tasks to complete and returns list of results in order
+- `when_any()` - Returns (index, result) tuple indicating which task completed first
 - `with_timeout()` - Add timeout to any operation
-- `gather(*awaitables, return_exceptions=False)` - Compose awaitables:
-  - Preserves input order; returns list of results
-  - `return_exceptions=True` captures exceptions as values
-  - Empty gather resolves immediately to `[]`
-  - Safe to await the same gather result multiple times (cached)
 
 ### 4. **Async Context Management**
 - Full async context manager support (`async with ctx:`)
@@ -125,52 +121,39 @@ Note: The `sandbox_mode` parameter accepts both `SandboxMode` enum values and st
 Control non-determinism detection with the `sandbox_mode` parameter:
 
 ```python
-# Production: Zero overhead (default)
-worker.add_orchestrator(workflow, sandbox_mode="off")
+# Default: Patches asyncio functions for determinism, optional warnings
+worker.add_orchestrator(workflow)  # Uses "best_effort" by default
 
-# Development: Warnings for non-deterministic calls
+# Development: Same as default, warnings when debug mode enabled
 worker.add_orchestrator(workflow, sandbox_mode=SandboxMode.BEST_EFFORT)
 
 # Testing: Errors for non-deterministic calls
 worker.add_orchestrator(workflow, sandbox_mode=SandboxMode.STRICT)
+
+# No patching: Use only if all code uses ctx.* methods explicitly
+worker.add_orchestrator(workflow, sandbox_mode="off")
 ```
 
-Why enable detection (briefly):
-- Catch accidental non-determinism in development (BEST_EFFORT) before it ships.
-- Keep production fast with zero overhead (OFF).
-- Enforce determinism in CI (STRICT) to prevent regressions.
+Why "best_effort" is the default:
+- Makes standard asyncio patterns work correctly (asyncio.sleep, asyncio.gather, etc.)
+- Patches random/time/uuid to be deterministic automatically
+- Optional warnings only when debug mode is enabled (low overhead)
+- Provides "pit of success" for async workflow authoring
 
 ### Performance Impact
-- `"off"`: Zero overhead (recommended for production)
-- `"best_effort"/"strict"`: ~100-200% overhead due to Python tracing
+- `"best_effort"` (default): Minimal overhead from function patching. Tracing overhead present but uses lightweight noop tracer unless debug mode is enabled.
+- `"strict"`: ~100-200% overhead due to full Python tracing for detection
+- `"off"`: Zero overhead (no patching, no tracing)
 - Global disable: Set `DAPR_WF_DISABLE_DETERMINISTIC_DETECTION=true` environment variable
 
+Note: Function patching overhead is minimal (single-digit percentage). Tracing overhead (when enabled) is more significant due to Python's sys.settrace() mechanism.
+
 ## Environment Variables
 
 - `DAPR_WF_DEBUG=true` / `DT_DEBUG=true` - Enable debug logging, operation tracking, and non-determinism warnings
 - `DAPR_WF_DISABLE_DETERMINISTIC_DETECTION=true` - Globally disable non-determinism detection
 
 ## Developer Mode
-## Workflow Metadata and Headers (Async Only)
-
-Purpose:
-- Carry lightweight key/value context (e.g., tracing IDs, tenant, app info) across workflow steps.
-- Enable routing and observability without embedding data into workflow inputs/outputs.
-
-API:
-```python
-md_before = ctx.get_metadata()  # Optional[Dict[str, str]]
-ctx.set_metadata({"tenant": "acme", "x-trace": trace_id})
-
-# Header aliases (same data for users familiar with other SDKs)
-ctx.set_headers({"region": "us-east"})
-headers = ctx.get_headers()
-```
-
-Notes:
-- In python-sdk, metadata/headers are available for both async and generator orchestrators; this repo currently implements the asyncio path.
-- Metadata is intended for small strings; avoid large payloads.
-- Sidecar integrations may forward metadata as gRPC headers to activities and sub-orchestrations.
 
 Set `DAPR_WF_DEBUG=true` during development to enable:
 - Non-determinism warnings for problematic function calls
@@ -206,14 +189,8 @@ async def workflow_with_timeout(ctx: AsyncWorkflowContext, input_data) -> str:
     return result
 ```
 
-### Enhanced when_any
-Note: `when_any` still exists. `when_any_with_result` is an addition for cases where you also want the index of the first completed.
+### when_any with index and result
 
-```python
-# Both forms are supported
-winner_value = await ctx.when_any(tasks)
-winner_index, winner_value = await ctx.when_any_with_result(tasks)
-```
 ```python
 async def competitive_workflow(ctx, input_data):
     tasks = [
@@ -222,8 +199,8 @@ async def competitive_workflow(ctx, input_data):
         ctx.call_activity("provider_c")
     ]
 
-    # Get both index and result of first completed
-    winner_index, result = await ctx.when_any_with_result(tasks)
+    # when_any returns (index, result) tuple
+    winner_index, result = await ctx.when_any(tasks)
     return f"Provider {winner_index} won with: {result}"
 ```
 
@@ -258,9 +235,9 @@ async def workflow_with_cleanup(ctx, input_data):
    - `ctx.random()` instead of `random`
    - `ctx.uuid4()` instead of `uuid.uuid4()`
 
-2. **Enable detection during development**:
+2. **Use strict mode in testing**:
    ```python
-   sandbox_mode = "best_effort" if os.getenv("ENV") == "dev" else "off"
+   sandbox_mode = "strict" if os.getenv("CI") else "best_effort"
    ```
 
 3. **Add timeouts to external operations**:

durabletask/aio/ASYNCIO_INTERNALS.md

@@ -140,18 +140,25 @@ Optional Sandbox (per activation):
 
 ## Sandboxing and Non‑Determinism Detection
 
-The sandbox provides optional, scoped compatibility and detection for common non‑deterministic stdlib calls. It is opt‑in per orchestrator via `sandbox_mode`:
+The sandbox provides scoped compatibility and detection for common non‑deterministic stdlib calls. It is configured per orchestrator via `sandbox_mode`:
 
-- `off` (default): No patching or detection; zero overhead. Use deterministic APIs only.
-- `best_effort`: Patch common functions within a scope and emit warnings on detected non‑determinism.
-- `strict`: As above, but raise `SandboxViolationError` on detected calls.
+- `best_effort` (default): Patch common functions within a scope and emit warnings on detected non‑determinism when debug mode is enabled.
+- `strict`: Patch common functions and raise `SandboxViolationError` on detected calls.
+- `off`: No patching or detection; zero overhead. Use deterministic APIs only.
 
-Patched targets (best‑effort):
+Patched targets (best‑effort and strict):
 - `asyncio.sleep` → deterministic timer awaitable
-- `random` module functions (via a deterministic `Random` instance)
+- `asyncio.gather` → replay-safe one-shot awaitable wrapper using WhenAllAwaitable
+- `random` module functions (random, randrange, randint, getrandbits via deterministic PRNG)
 - `uuid.uuid4` → derived from deterministic PRNG
 - `time.time/time_ns` → orchestration time
 
+Additional blocks in strict mode only:
+- `asyncio.create_task` → raises SandboxViolationError
+- `builtins.open` → raises SandboxViolationError
+- `os.urandom` → raises SandboxViolationError
+- `secrets.token_bytes/token_hex` → raises SandboxViolationError
+
 Important limitations:
 - `datetime.datetime.now()` is not patched (type immutability). Use `ctx.now()` or `ctx.current_utc_datetime`.
 - `from x import y` may bypass patches due to direct binding.
@@ -174,23 +181,21 @@ Modes and behavior:
 - `SandboxMode.OFF`:
   - No tracing, no patching, zero overhead
   - Detector is not active
-- `SandboxMode.BEST_EFFORT`:
-  - Patches selected stdlib functions
-  - Installs tracer only when `ctx._debug_mode` is true; otherwise a no‑op tracer is used to keep overhead minimal
+- `SandboxMode.BEST_EFFORT` (default):
+  - Patches selected stdlib functions (asyncio.sleep, random, uuid.uuid4, time.time, asyncio.gather)
+  - Installs tracer only when `ctx._debug_mode` is true; otherwise no tracer (minimal overhead)
   - Emits `NonDeterminismWarning` once per unique callsite with a suggested deterministic alternative
 - `SandboxMode.STRICT`:
-  - Patches selected stdlib functions and blocks dangerous operations (e.g., `open`, `os.urandom`, `secrets.*`)
+  - Patches selected stdlib functions and blocks dangerous operations (e.g., `open`, `os.urandom`, `secrets.*`, `asyncio.create_task`)
   - Installs full tracer regardless of debug flag
   - Raises `SandboxViolationError` on first detection with details and suggestions
 
-When to use it (recommended):
-- During development to quickly surface accidental non‑determinism in orchestrator code
-- When integrating third‑party libraries that might call time/random/uuid internally
-- In CI for a dedicated “determinism” job (short test matrix), using `BEST_EFFORT` for warnings or `STRICT` for enforcement
+When to use each mode:
+- `BEST_EFFORT` (default): Recommended for most use cases. Patches make standard asyncio patterns work correctly with minimal overhead.
+- `STRICT`: Use in CI/testing to enforce determinism and catch violations early.
+- `OFF`: Use only if you're certain all code uses `ctx.*` methods exclusively and want absolute zero overhead.
 
-When not to use it:
-- Production environments (prefer `OFF` for zero overhead)
-- Performance‑sensitive local loops (e.g., microbenchmarks) unless you are specifically testing detection overhead
+Note: `BEST_EFFORT` is now the default because it makes workflows "just work" with standard asyncio code patterns.
 
 Enabling and controlling the detector:
 - Per‑orchestrator registration:
@@ -220,9 +225,11 @@ What warnings/errors look like:
   - Includes violation type, suggested alternative, `workflow_name`, and `instance_id` when available
 
 Overhead and performance:
-- `OFF`: zero overhead
-- `BEST_EFFORT`: minimal overhead by default; full detection overhead only when debug is enabled
-- `STRICT`: tracing overhead present; recommended only for testing/enforcement, not for production
+- `OFF`: zero overhead (no patching, no detection)
+- `BEST_EFFORT` (default): minimal overhead from patching; lightweight noop tracer unless debug mode enabled (full detection tracer only when `DAPR_WF_DEBUG=true`)
+- `STRICT`: ~100-200% overhead due to full Python tracing; recommended only for testing/enforcement
+
+Note: The patching overhead (module-level function replacement) is minimal. The tracing overhead (sys.settrace) is more significant when full detection is enabled.
 
 Limitations and caveats:
 - Direct imports like `from random import random` bind the function and may bypass patching

durabletask/aio/__init__.py

@@ -18,8 +18,6 @@
     TimeoutAwaitable,
     WhenAllAwaitable,
     WhenAnyAwaitable,
-    WhenAnyResultAwaitable,
-    gather,
 )
 from .client import AsyncTaskHubGrpcClient
 
@@ -60,10 +58,8 @@
     "ExternalEventAwaitable",
     "WhenAllAwaitable",
     "WhenAnyAwaitable",
-    "WhenAnyResultAwaitable",
     "TimeoutAwaitable",
     "SwallowExceptionAwaitable",
-    "gather",
     # Sandbox and utilities
     "SandboxMode",
     "_NonDeterminismDetector",