📋 Review and freeze RepositoryProtocol for v1.0.0 API stability

Description

Before v1.0.0, the RepositoryProtocol needs a comprehensive review to ensure it's complete and stable for all planned backends. Once frozen, the protocol becomes part of the stable public API with backward compatibility guarantees.

Context

The RepositoryProtocol was extracted in #150 (v0.5.0) and documented in ADR-108 and ADR-109. It currently supports:

• Core: Entity CRUD, bucket operations, transactions, limit config, lifecycle
• Extended: Audit logging, usage snapshots, infrastructure management (via BackendCapabilities)

Planned backends (v1.4.0 milestone):

• Redis (#149)
• SQLite (#156)
• In-Memory (#157, actually v0.9.0)
• Azure Cosmos DB (#158)
• Google Firestore (#159)
• OCI NoSQL (#160)

Review Checklist

1. Method Completeness

• All methods required by RateLimiter business logic are in the protocol
• Method signatures are stable (parameter names, types, return types)
• Default parameter values are appropriate for all backends
• No DynamoDB-specific terminology leaks into generic protocol (e.g., table_name property)

2. Property Review

Property	Current	Issue
region	str | None	Cloud-agnostic? Redis has no region
endpoint_url	str | None	OK - connection string concept is universal
stack_name	str	DynamoDB/CloudFormation-specific - should be generic name
table_name	str	DynamoDB-specific - rename to backend_id or remove
capabilities	BackendCapabilities	OK - extensibility pattern

3. BackendCapabilities Flags

Review if flags cover all planned backends:

Flag	DynamoDB	Redis	SQLite	In-Memory	Cosmos	Firestore
supports_audit_logging	Yes	Streams	Table	No	TBD	TBD
supports_usage_snapshots	Yes	Consumer	Polling	No	TBD	TBD
supports_infrastructure_management	Yes	No	No	No	ARM	Terraform
supports_change_streams	Yes	Yes	No	No	Yes	Yes
supports_batch_operations	Yes	Pipeline	No	No	Bulk	getAll

Missing flags to consider:

• supports_ttl - native TTL vs manual cleanup
• supports_transactions - true ACID vs Lua scripts vs none
• supports_hierarchical_queries - GSI vs manual joins

4. Error Contract

• Define standard exceptions that all backends must raise
• Document when EntityNotFoundError vs returning None
• Ensure TransactionCanceledException is backend-agnostic

5. Sync/Async Consistency

• All methods are async (sync wrapper via SyncRateLimiter)
• No blocking I/O hidden in sync methods like build_bucket_put_item

6. Documentation

• API docs in docs/api/repository.md are complete
• Each method has docstring with Args, Returns, Raises
• ADR-108 and ADR-109 are up to date

Proposed Changes

Based on review, potential changes before freeze:

1. Rename stack_name to name - More generic for non-CloudFormation backends
2. Rename table_name to store_name - Or remove if redundant with name
3. Add missing capability flags - supports_ttl, supports_transactions
4. Standardize error types - Create backend-agnostic exception hierarchy

Acceptance Criteria

• All protocol methods reviewed against Redis/SQLite/In-Memory requirements
• Property names are cloud-agnostic (no "table", "stack" in generic protocol)
• BackendCapabilities covers all feature flags needed by planned backends
• Error contract documented with standard exception types
• docs/api/repository.md updated with complete method documentation
• ADR-108 updated if protocol changes
• Breaking changes (if any) documented in CHANGELOG with migration guide
• In-Memory backend (#157) can implement protocol without workarounds

Dependencies

• Blocked by: None (review task)
• Blocking: #49 (v1.0.0 release), #157 (In-Memory backend implementation)

References

• ADR-108: Repository Protocol Design
• ADR-109: Backend Capability Matrix
• #150: Original protocol extraction
• #149: Redis backend (defines protocol requirements)
• #157: In-Memory backend (simplest implementation, good test case)

Start by reading ADR-108 and ADR-109, then inspect docs/api/repository.md and the requirements referenced from Redis (#149) and In-Memory (#157). Compare the protocol and BackendCapabilities against the checklist and planned backends. Done means the acceptance criteria are met, including documented errors, updated ADRs, and a migration guide for breaking changes.