edda-framework 0.6.0__tar.gz → 0.8.0__tar.gz

{edda_framework-0.6.0 → edda_framework-0.8.0}/.gitignore

@@ -99,3 +99,4 @@ site/
 
 # Cache directories
 .cache/
+.nicegui/

{edda_framework-0.6.0 → edda_framework-0.8.0}/Justfile

@@ -31,18 +31,22 @@ test-file FILE:
 
 # Format code with black
 format:
+    @uv sync --extra dev --quiet
     uv run black edda tests
 
 # Check code formatting
 format-check:
+    @uv sync --extra dev --quiet
     uv run black --check edda tests
 
 # Lint code with ruff
 lint:
+    @uv sync --extra dev --quiet
     uv run ruff check edda tests
 
 # Type check with mypy
 type-check:
+    @uv sync --extra dev --quiet
     uv run mypy edda
 
 # Run all checks (format, lint, type-check, test)
@@ -50,6 +54,7 @@ check: format-check lint type-check test
 
 # Auto-fix issues (format + lint with auto-fix)
 fix:
+    @uv sync --extra dev --quiet
     uv run black edda tests
     uv run ruff check --fix edda tests
 
@@ -116,6 +121,18 @@ viewer-demo DB='demo.db' PORT='8080':
     just viewer {{DB}} {{PORT}} "--import-module demo_app"
 
 
+# Build documentation (clears cache for fresh API reference)
+docs:
+    rm -rf .cache site
+    uv run zensical build
+
+# Serve documentation locally (clears cache for fresh API reference)
+docs-serve:
+    @lsof -ti :8000 | xargs kill -15 2>/dev/null || true
+    @sleep 1
+    rm -rf .cache site
+    uv run zensical serve
+
 # Clean build artifacts and caches
 clean:
     rm -rf .pytest_cache
@@ -123,9 +140,102 @@ clean:
     rm -rf .coverage
     rm -rf .mypy_cache
     rm -rf .ruff_cache
+    rm -rf .cache
+    rm -rf site
     rm -rf dist
     rm -rf build
     rm -rf *.egg-info
     find . -type d -name __pycache__ -exec rm -rf {} +
     find . -type f -name "*.pyc" -delete
     rm -f demo.db
+
+# Helper recipe for point-to-point test (uses bash for command substitution)
+_test-point-to-point LOG_FILE:
+    #!/usr/bin/env bash
+    set -e
+    echo "=== Test 3: Point-to-Point Mode (Direct Message) ==="
+    echo "Starting receiver..."
+    curl -s -X POST http://localhost:8001/ \
+        -H "Content-Type: application/cloudevents+json" \
+        -d '{"specversion":"1.0","type":"direct_message_receiver_workflow","source":"test","id":"receiver-1","data":{"receiver_id":"receiver-1"}}' > /dev/null
+    sleep 2
+    # Parse instance_id from server log (format: [RECEIVER] Instance ID: workflow-uuid)
+    # Strip ANSI color codes before grepping
+    INSTANCE_ID=$(sed 's/\x1b\[[0-9;]*m//g' "{{LOG_FILE}}" | grep -o '\[RECEIVER\] Instance ID: [^ ]*' | tail -1 | cut -d' ' -f4)
+    echo "Receiver instance_id: $INSTANCE_ID"
+    if [ -z "$INSTANCE_ID" ]; then
+        echo "ERROR: Could not extract instance_id from server log"
+        echo "Log content (stripped):"
+        sed 's/\x1b\[[0-9;]*m//g' "{{LOG_FILE}}" | grep -i receiver || echo "(no receiver logs found)"
+        exit 1
+    fi
+    echo "Sending direct message to receiver..."
+    curl -s -X POST http://localhost:8001/ \
+        -H "Content-Type: application/cloudevents+json" \
+        -d "{\"specversion\":\"1.0\",\"type\":\"direct_message_sender_workflow\",\"source\":\"test\",\"id\":\"sender-1\",\"data\":{\"target_instance_id\":\"$INSTANCE_ID\",\"message\":\"Hello from sender!\"}}"
+    echo ""
+    sleep 5
+    # Verify receiver got the message (strip ANSI codes)
+    if sed 's/\x1b\[[0-9;]*m//g' "{{LOG_FILE}}" | grep -q "\[RECEIVER\] Received message:"; then
+        echo "✓ Point-to-Point message delivered successfully!"
+    else
+        echo "✗ Point-to-Point message delivery failed"
+    fi
+
+# Test message passing (competing, broadcast, and point-to-point modes)
+test-messages:
+    #!/usr/bin/env bash
+    set -e
+    LOG_FILE=$(mktemp)
+    echo "=== Message Passing Test ==="
+    echo "Server log: $LOG_FILE"
+    echo "Starting demo app in background..."
+    rm -f demo.db
+    uv sync --extra server --quiet
+    PYTHONUNBUFFERED=1 uv run tsuno demo_app:application --bind 127.0.0.1:8001 --workers 1 > "$LOG_FILE" 2>&1 &
+    SERVER_PID=$!
+    sleep 2
+
+    echo ""
+    echo "=== Test 1: Competing Mode (Job Worker) ==="
+    echo "Starting worker..."
+    curl -s -X POST http://localhost:8001/ \
+        -H "Content-Type: application/cloudevents+json" \
+        -d '{"specversion":"1.0","type":"job_worker_workflow","source":"test","id":"worker-1","data":{"worker_id":"worker-1"}}'
+    echo ""
+    sleep 1
+    echo "Publishing job..."
+    curl -s -X POST http://localhost:8001/ \
+        -H "Content-Type: application/cloudevents+json" \
+        -d '{"specversion":"1.0","type":"job_publisher_workflow","source":"test","id":"job-1","data":{"task":"test-task"}}'
+    echo ""
+    sleep 2
+
+    echo ""
+    echo "=== Test 2: Broadcast Mode (Notification) ==="
+    echo "Starting notification service..."
+    curl -s -X POST http://localhost:8001/ \
+        -H "Content-Type: application/cloudevents+json" \
+        -d '{"specversion":"1.0","type":"notification_service_workflow","source":"test","id":"service-1","data":{"service_id":"service-1"}}'
+    echo ""
+    sleep 1
+    echo "Publishing notification..."
+    curl -s -X POST http://localhost:8001/ \
+        -H "Content-Type: application/cloudevents+json" \
+        -d '{"specversion":"1.0","type":"notification_publisher_workflow","source":"test","id":"notification-1","data":{"message":"Test notification"}}'
+    echo ""
+    sleep 2
+
+    just _test-point-to-point "$LOG_FILE"
+
+    echo ""
+    echo "=== Stopping demo app ==="
+    kill -15 $SERVER_PID 2>/dev/null || true
+    sleep 1
+
+    echo ""
+    echo "=== Server Log ==="
+    cat "$LOG_FILE"
+    rm -f "$LOG_FILE"
+    echo ""
+    echo "Done!"

{edda_framework-0.6.0 → edda_framework-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.6.0
+Version: 0.8.0
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme
@@ -30,11 +30,13 @@ Requires-Dist: sqlalchemy[asyncio]>=2.0.0
 Requires-Dist: uvloop>=0.22.1
 Provides-Extra: dev
 Requires-Dist: black>=25.9.0; extra == 'dev'
+Requires-Dist: mcp>=1.22.0; extra == 'dev'
 Requires-Dist: mypy>=1.18.2; extra == 'dev'
 Requires-Dist: pytest-asyncio>=1.2.0; extra == 'dev'
 Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
 Requires-Dist: pytest>=8.4.2; extra == 'dev'
 Requires-Dist: ruff>=0.14.2; extra == 'dev'
+Requires-Dist: starlette>=0.40.0; extra == 'dev'
 Requires-Dist: testcontainers[mysql]>=4.0.0; extra == 'dev'
 Requires-Dist: testcontainers[postgres]>=4.0.0; extra == 'dev'
 Requires-Dist: tsuno>=0.1.3; extra == 'dev'
@@ -83,6 +85,7 @@ For detailed documentation, visit [https://i2y.github.io/edda/](https://i2y.gith
 - 📦 **Transactional Outbox**: Reliable event publishing with guaranteed delivery
 - ☁️ **CloudEvents Support**: Native support for CloudEvents protocol
 - ⏱️ **Event & Timer Waiting**: Free up worker resources while waiting for events or timers, resume on any available worker
+- 📬 **Channel-based Messaging**: Actor-model style communication with competing (job queue) and broadcast (fan-out) modes
 - 🤖 **MCP Integration**: Expose durable workflows as AI tools via Model Context Protocol
 - 🌍 **ASGI/WSGI Support**: Deploy with your preferred server (uvicorn, gunicorn, uWSGI)
 
@@ -105,14 +108,14 @@ Edda's waiting functions make it ideal for time-based and event-driven business
 - **📦 Scheduled Notifications**: Shipping updates, subscription renewals, appointment reminders
 
 **Waiting functions**:
-- `wait_timer(duration_seconds)`: Wait for a relative duration
-- `wait_until(until_time)`: Wait until an absolute datetime (e.g., campaign end date)
+- `sleep(seconds)`: Wait for a relative duration
+- `sleep_until(target_time)`: Wait until an absolute datetime (e.g., campaign end date)
 - `wait_event(event_type)`: Wait for external events (near real-time response)
 
 ```python
 @workflow
 async def onboarding_reminder(ctx: WorkflowContext, user_id: str):
-    await wait_timer(ctx, duration_seconds=3*24*60*60)  # Wait 3 days
+    await sleep(ctx, seconds=3*24*60*60)  # Wait 3 days
     if not await check_completed(ctx, user_id):
         await send_reminder(ctx, user_id)
 ```
@@ -164,7 +167,7 @@ graph TB
 
 - Multiple workers can run simultaneously across different pods/servers
 - Each workflow instance runs on only one worker at a time (automatic coordination)
-- `wait_event()` and `wait_timer()` free up worker resources while waiting, resume on any worker when event arrives or timer expires
+- `wait_event()` and `sleep()` free up worker resources while waiting, resume on any worker when event arrives or timer expires
 - Automatic crash recovery with stale lock cleanup and workflow auto-resume
 
 ## Quick Start
@@ -484,7 +487,10 @@ Multiple workers can safely process workflows using database-based exclusive con
 
 app = EddaApp(
     db_url="postgresql://localhost/workflows",  # Shared database for coordination
-    service_name="order-service"
+    service_name="order-service",
+    # Connection pool settings (optional)
+    pool_size=5,        # Concurrent connections
+    max_overflow=10,    # Additional burst capacity
 )
 ```
 
@@ -612,10 +618,32 @@ async def payment_workflow(ctx: WorkflowContext, order_id: str):
     return payment_event.data
 ```
 
-**wait_timer() for time-based waiting**:
+**ReceivedEvent attributes**: The `wait_event()` function returns a `ReceivedEvent` object:
+
+```python
+event = await wait_event(ctx, "payment.completed")
+amount = event.data["amount"]           # Event payload (dict or bytes)
+source = event.metadata.source          # CloudEvents source
+event_type = event.metadata.type        # CloudEvents type
+extensions = event.extensions           # CloudEvents extensions
+```
+
+**Timeout handling with EventTimeoutError**:
 
 ```python
-from edda import wait_timer
+from edda import wait_event, EventTimeoutError
+
+try:
+    event = await wait_event(ctx, "payment.completed", timeout_seconds=60)
+except EventTimeoutError:
+    # Handle timeout (e.g., cancel order, send reminder)
+    await cancel_order(ctx, order_id)
+```
+
+**sleep() for time-based waiting**:
+
+```python
+from edda import sleep
 
 @workflow
 async def order_with_timeout(ctx: WorkflowContext, order_id: str):
@@ -623,7 +651,7 @@ async def order_with_timeout(ctx: WorkflowContext, order_id: str):
     await create_order(ctx, order_id)
 
     # Wait 60 seconds for payment
-    await wait_timer(ctx, duration_seconds=60)
+    await sleep(ctx, seconds=60)
 
     # Check payment status
     return await check_payment(ctx, order_id)
@@ -637,6 +665,136 @@ async def order_with_timeout(ctx: WorkflowContext, order_id: str):
 
 **For technical details**, see [Multi-Worker Continuations](local-docs/distributed-coroutines.md).
 
+### Message Passing (Workflow-to-Workflow)
+
+Edda provides actor-model style message passing for direct workflow-to-workflow communication:
+
+```python
+from edda import workflow, wait_message, send_message_to, WorkflowContext
+
+# Receiver workflow - waits for approval message
+@workflow
+async def approval_workflow(ctx: WorkflowContext, request_id: str):
+    # Wait for message on "approval" channel
+    msg = await wait_message(ctx, channel="approval")
+
+    if msg.data["approved"]:
+        return {"status": "approved", "approver": msg.data["approver"]}
+    return {"status": "rejected"}
+
+# Sender workflow - sends approval decision
+@workflow
+async def manager_workflow(ctx: WorkflowContext, request_id: str):
+    # Review and make decision
+    decision = await review_request(ctx, request_id)
+
+    # Send message to waiting workflow
+    await send_message_to(
+        ctx,
+        target_instance_id=request_id,
+        channel="approval",
+        data={"approved": decision, "approver": "manager-123"},
+    )
+```
+
+**Group Communication (Erlang pg style)** - for fan-out messaging without knowing receiver instance IDs:
+
+```python
+from edda import workflow, join_group, wait_message, publish_to_group
+
+# Receiver workflow - joins a group and listens
+@workflow
+async def notification_service(ctx: WorkflowContext, service_id: str):
+    # Join group at startup (loose coupling - sender doesn't need to know us)
+    await join_group(ctx, group="order_watchers")
+
+    while True:
+        msg = await wait_message(ctx, channel="order.created")
+        await send_notification(ctx, msg.data)
+
+# Sender workflow - publishes to all group members
+@workflow
+async def order_processor(ctx: WorkflowContext, order_id: str):
+    result = await process_order(ctx, order_id)
+
+    # Broadcast to all watchers (doesn't need to know instance IDs)
+    count = await publish_to_group(
+        ctx,
+        group="order_watchers",
+        channel="order.created",
+        data={"order_id": order_id, "status": "completed"},
+    )
+    print(f"Notified {count} watchers")
+```
+
+**Channel API with Delivery Modes** - subscribe to channels with explicit delivery semantics:
+
+```python
+from edda import workflow, subscribe, receive, publish, WorkflowContext
+
+# Job Worker - processes jobs exclusively (competing mode)
+@workflow
+async def job_worker(ctx: WorkflowContext, worker_id: str):
+    # Subscribe with competing mode - each job goes to ONE worker only
+    await subscribe(ctx, channel="jobs", mode="competing")
+
+    while True:
+        job = await receive(ctx, channel="jobs")  # Get next job
+        await process_job(ctx, job.data)
+        await ctx.recur(worker_id)  # Continue processing
+
+# Notification Handler - receives ALL messages (broadcast mode)
+@workflow
+async def notification_handler(ctx: WorkflowContext, handler_id: str):
+    # Subscribe with broadcast mode - ALL handlers receive each message
+    await subscribe(ctx, channel="notifications", mode="broadcast")
+
+    while True:
+        msg = await receive(ctx, channel="notifications")
+        await send_notification(ctx, msg.data)
+        await ctx.recur(handler_id)
+
+# Publisher - send messages to channel
+await publish(ctx, channel="jobs", data={"task": "send_report"})
+```
+
+**Delivery modes**:
+- **`competing`**: Each message goes to exactly ONE subscriber (job queue/task distribution)
+- **`broadcast`**: Each message goes to ALL subscribers (notifications/fan-out)
+
+**Key features**:
+- **Channel-based messaging**: Messages are delivered to workflows waiting on specific channels
+- **Competing vs Broadcast**: Choose semantics per subscription
+- **Group communication**: Erlang pg-style groups for loose coupling and fan-out
+- **Database-backed**: All messages are persisted for durability
+- **Lock-first delivery**: Safe for multi-worker environments
+
+### Workflow Recurrence
+
+Long-running workflows can use `ctx.recur()` to restart with fresh history while maintaining the same instance ID. This is essential for workflows that run indefinitely (job workers, notification handlers, etc.):
+
+```python
+from edda import workflow, subscribe, receive, WorkflowContext
+
+@workflow
+async def job_worker(ctx: WorkflowContext, worker_id: str):
+    await subscribe(ctx, channel="jobs", mode="competing")
+
+    # Process one job
+    job = await receive(ctx, channel="jobs")
+    await process_job(ctx, job.data)
+
+    # Archive history and restart with same instance_id
+    # Prevents unbounded history growth
+    await ctx.recur(worker_id)
+```
+
+**Key benefits**:
+- **Prevents history growth**: Archives old history, starts fresh
+- **Maintains instance ID**: Same workflow continues logically
+- **Preserves subscriptions**: Channel subscriptions survive recurrence
+- **Enables infinite loops**: Essential for long-running workers
+
 ### ASGI Integration
 
 Edda runs as an ASGI application:

{edda_framework-0.6.0 → edda_framework-0.8.0}/README.md

@@ -27,6 +27,7 @@ For detailed documentation, visit [https://i2y.github.io/edda/](https://i2y.gith
 - 📦 **Transactional Outbox**: Reliable event publishing with guaranteed delivery
 - ☁️ **CloudEvents Support**: Native support for CloudEvents protocol
 - ⏱️ **Event & Timer Waiting**: Free up worker resources while waiting for events or timers, resume on any available worker
+- 📬 **Channel-based Messaging**: Actor-model style communication with competing (job queue) and broadcast (fan-out) modes
 - 🤖 **MCP Integration**: Expose durable workflows as AI tools via Model Context Protocol
 - 🌍 **ASGI/WSGI Support**: Deploy with your preferred server (uvicorn, gunicorn, uWSGI)
 
@@ -49,14 +50,14 @@ Edda's waiting functions make it ideal for time-based and event-driven business
 - **📦 Scheduled Notifications**: Shipping updates, subscription renewals, appointment reminders
 
 **Waiting functions**:
-- `wait_timer(duration_seconds)`: Wait for a relative duration
-- `wait_until(until_time)`: Wait until an absolute datetime (e.g., campaign end date)
+- `sleep(seconds)`: Wait for a relative duration
+- `sleep_until(target_time)`: Wait until an absolute datetime (e.g., campaign end date)
 - `wait_event(event_type)`: Wait for external events (near real-time response)
 
 ```python
 @workflow
 async def onboarding_reminder(ctx: WorkflowContext, user_id: str):
-    await wait_timer(ctx, duration_seconds=3*24*60*60)  # Wait 3 days
+    await sleep(ctx, seconds=3*24*60*60)  # Wait 3 days
     if not await check_completed(ctx, user_id):
         await send_reminder(ctx, user_id)
 ```
@@ -108,7 +109,7 @@ graph TB
 
 - Multiple workers can run simultaneously across different pods/servers
 - Each workflow instance runs on only one worker at a time (automatic coordination)
-- `wait_event()` and `wait_timer()` free up worker resources while waiting, resume on any worker when event arrives or timer expires
+- `wait_event()` and `sleep()` free up worker resources while waiting, resume on any worker when event arrives or timer expires
 - Automatic crash recovery with stale lock cleanup and workflow auto-resume
 
 ## Quick Start
@@ -428,7 +429,10 @@ Multiple workers can safely process workflows using database-based exclusive con
 
 app = EddaApp(
     db_url="postgresql://localhost/workflows",  # Shared database for coordination
-    service_name="order-service"
+    service_name="order-service",
+    # Connection pool settings (optional)
+    pool_size=5,        # Concurrent connections
+    max_overflow=10,    # Additional burst capacity
 )
 ```
 
@@ -556,10 +560,32 @@ async def payment_workflow(ctx: WorkflowContext, order_id: str):
     return payment_event.data
 ```
 
-**wait_timer() for time-based waiting**:
+**ReceivedEvent attributes**: The `wait_event()` function returns a `ReceivedEvent` object:
+
+```python
+event = await wait_event(ctx, "payment.completed")
+amount = event.data["amount"]           # Event payload (dict or bytes)
+source = event.metadata.source          # CloudEvents source
+event_type = event.metadata.type        # CloudEvents type
+extensions = event.extensions           # CloudEvents extensions
+```
+
+**Timeout handling with EventTimeoutError**:
 
 ```python
-from edda import wait_timer
+from edda import wait_event, EventTimeoutError
+
+try:
+    event = await wait_event(ctx, "payment.completed", timeout_seconds=60)
+except EventTimeoutError:
+    # Handle timeout (e.g., cancel order, send reminder)
+    await cancel_order(ctx, order_id)
+```
+
+**sleep() for time-based waiting**:
+
+```python
+from edda import sleep
 
 @workflow
 async def order_with_timeout(ctx: WorkflowContext, order_id: str):
@@ -567,7 +593,7 @@ async def order_with_timeout(ctx: WorkflowContext, order_id: str):
     await create_order(ctx, order_id)
 
     # Wait 60 seconds for payment
-    await wait_timer(ctx, duration_seconds=60)
+    await sleep(ctx, seconds=60)
 
     # Check payment status
     return await check_payment(ctx, order_id)
@@ -581,6 +607,136 @@ async def order_with_timeout(ctx: WorkflowContext, order_id: str):
 
 **For technical details**, see [Multi-Worker Continuations](local-docs/distributed-coroutines.md).
 
+### Message Passing (Workflow-to-Workflow)
+
+Edda provides actor-model style message passing for direct workflow-to-workflow communication:
+
+```python
+from edda import workflow, wait_message, send_message_to, WorkflowContext
+
+# Receiver workflow - waits for approval message
+@workflow
+async def approval_workflow(ctx: WorkflowContext, request_id: str):
+    # Wait for message on "approval" channel
+    msg = await wait_message(ctx, channel="approval")
+
+    if msg.data["approved"]:
+        return {"status": "approved", "approver": msg.data["approver"]}
+    return {"status": "rejected"}
+
+# Sender workflow - sends approval decision
+@workflow
+async def manager_workflow(ctx: WorkflowContext, request_id: str):
+    # Review and make decision
+    decision = await review_request(ctx, request_id)
+
+    # Send message to waiting workflow
+    await send_message_to(
+        ctx,
+        target_instance_id=request_id,
+        channel="approval",
+        data={"approved": decision, "approver": "manager-123"},
+    )
+```
+
+**Group Communication (Erlang pg style)** - for fan-out messaging without knowing receiver instance IDs:
+
+```python
+from edda import workflow, join_group, wait_message, publish_to_group
+
+# Receiver workflow - joins a group and listens
+@workflow
+async def notification_service(ctx: WorkflowContext, service_id: str):
+    # Join group at startup (loose coupling - sender doesn't need to know us)
+    await join_group(ctx, group="order_watchers")
+
+    while True:
+        msg = await wait_message(ctx, channel="order.created")
+        await send_notification(ctx, msg.data)
+
+# Sender workflow - publishes to all group members
+@workflow
+async def order_processor(ctx: WorkflowContext, order_id: str):
+    result = await process_order(ctx, order_id)
+
+    # Broadcast to all watchers (doesn't need to know instance IDs)
+    count = await publish_to_group(
+        ctx,
+        group="order_watchers",
+        channel="order.created",
+        data={"order_id": order_id, "status": "completed"},
+    )
+    print(f"Notified {count} watchers")
+```
+
+**Channel API with Delivery Modes** - subscribe to channels with explicit delivery semantics:
+
+```python
+from edda import workflow, subscribe, receive, publish, WorkflowContext
+
+# Job Worker - processes jobs exclusively (competing mode)
+@workflow
+async def job_worker(ctx: WorkflowContext, worker_id: str):
+    # Subscribe with competing mode - each job goes to ONE worker only
+    await subscribe(ctx, channel="jobs", mode="competing")
+
+    while True:
+        job = await receive(ctx, channel="jobs")  # Get next job
+        await process_job(ctx, job.data)
+        await ctx.recur(worker_id)  # Continue processing
+
+# Notification Handler - receives ALL messages (broadcast mode)
+@workflow
+async def notification_handler(ctx: WorkflowContext, handler_id: str):
+    # Subscribe with broadcast mode - ALL handlers receive each message
+    await subscribe(ctx, channel="notifications", mode="broadcast")
+
+    while True:
+        msg = await receive(ctx, channel="notifications")
+        await send_notification(ctx, msg.data)
+        await ctx.recur(handler_id)
+
+# Publisher - send messages to channel
+await publish(ctx, channel="jobs", data={"task": "send_report"})
+```
+
+**Delivery modes**:
+- **`competing`**: Each message goes to exactly ONE subscriber (job queue/task distribution)
+- **`broadcast`**: Each message goes to ALL subscribers (notifications/fan-out)
+
+**Key features**:
+- **Channel-based messaging**: Messages are delivered to workflows waiting on specific channels
+- **Competing vs Broadcast**: Choose semantics per subscription
+- **Group communication**: Erlang pg-style groups for loose coupling and fan-out
+- **Database-backed**: All messages are persisted for durability
+- **Lock-first delivery**: Safe for multi-worker environments
+
+### Workflow Recurrence
+
+Long-running workflows can use `ctx.recur()` to restart with fresh history while maintaining the same instance ID. This is essential for workflows that run indefinitely (job workers, notification handlers, etc.):
+
+```python
+from edda import workflow, subscribe, receive, WorkflowContext
+
+@workflow
+async def job_worker(ctx: WorkflowContext, worker_id: str):
+    await subscribe(ctx, channel="jobs", mode="competing")
+
+    # Process one job
+    job = await receive(ctx, channel="jobs")
+    await process_job(ctx, job.data)
+
+    # Archive history and restart with same instance_id
+    # Prevents unbounded history growth
+    await ctx.recur(worker_id)
+```
+
+**Key benefits**:
+- **Prevents history growth**: Archives old history, starts fresh
+- **Maintains instance ID**: Same workflow continues logically
+- **Preserves subscriptions**: Channel subscriptions survive recurrence
+- **Enables infinite loops**: Essential for long-running workers
+
 ### ASGI Integration
 
 Edda runs as an ASGI application: