✨ Add Azure Cosmos DB backend support

Summary

Add an optional Azure Cosmos DB backend for users on Azure or multi-cloud deployments.

Motivation

Aspect	DynamoDB	Cosmos DB
Latency (p50)	36-51ms (txn)	10-20ms (txn)
Transactions	✅ TransactWriteItems	✅ Stored procedures / Batch
Cost model	Pay-per-request	Pay-per-RU
Multi-region	✅ Global Tables	✅ Multi-region writes

Cosmos DB offers:

• Potentially better transaction latency
• Native Azure integration
• Multi-model support (could use document or key-value)

Usage

from zae_limiter import RateLimiter
from zae_limiter.backends.cosmosdb import CosmosDBRepository

repo = CosmosDBRepository(
    endpoint="https://myaccount.documents.azure.com:443/",
    key="...",
    database="rate-limits",
    container="buckets",
)
limiter = RateLimiter(repository=repo)

Implementation Considerations

Transaction Support

Cosmos DB transactions via transactional batch:

# Cosmos DB transactional batch (single partition)
batch = container.create_batch(partition_key)
batch.upsert_item(bucket1)
batch.upsert_item(bucket2)
await container.execute_batch(batch)

Limitation: Transactional batch only works within a single partition key. May need to design partition strategy carefully for cascade support.

Partition Key Strategy

Options:

1. entity_id as partition key (cascade requires cross-partition txn)
2. Composite key with parent chain (complex)
3. Accept eventual consistency for cascade

Change Feed (for Aggregator)

Cosmos DB has Change Feed similar to DynamoDB Streams:

# Could trigger Azure Functions instead of Lambda
async for change in container.query_items_change_feed():
    process_change(change)

Dependencies

• #150 - Repository Protocol extraction (must be completed first)

Investigation Tasks

• Benchmark Cosmos DB transaction latency
• Evaluate partition key strategies for cascade
• Compare cost at various volumes
• Prototype transactional batch for acquire()

Acceptance Criteria

• CosmosDBRepository implements RepositoryProtocol
• Token bucket via transactional batch
• Entity CRUD operations
• Cascade support (or documented limitation)
• Optional dependency: pip install zae-limiter[cosmosdb]
• Benchmark comparison with DynamoDB
• Azure Functions aggregator (or documented as unsupported)

Related

• #150 - Repository Protocol extraction
• #149 - Redis backend (similar pattern)

No source files or tests are named. First review prerequisite issue #150, then investigate the transactional-batch, partition-key, change-feed, and Azure Functions requirements; done means the acceptance criteria are met, including the optional dependency and documented limitations where support is not implemented.