🐛 fix(repository): restore slow-path bucket read dropped by shard migration

[sodre]

Summary

Fixes a latent bug in Repository.batch_get_entity_and_buckets() (the acquire() slow-path / refill-recovery read) that silently dropped every bucket from the BatchGetItem response.

• Bug: The method classified response items with sk.startswith(schema.SK_BUCKET) ("#BUCKET#"). Since the per-shard partition-key migration (GHSA-76rv-2r9v-c5m6), bucket state records use SK == "#STATE" (sk_state()), so the filter never matched and every bucket was discarded. The slow path then treated existing buckets as new, the conditional write failed, and acquire() raised RateLimitExceeded with retry_after=0.0 instead of refilling.
• Effect: wait-then-acquire refill recovery was broken. With speculative_writes=True it breaks the refill fallback (masked in production only when the aggregator Lambda refills out-of-band); with speculative_writes=False or --no-aggregator it is fully broken.
• When it broke: latent since v0.7.0 (commit 663b687, where the robust else branch was narrowed to elif sk.startswith(SK_BUCKET)); activated in v0.10.1 (commit 94a129a, "migrate bucket items to per-shard partition keys") which changed the bucket SK to "#STATE" but missed this one response-classification filter. The sibling batch_get_buckets() has no such filter, which is why cascade/parent reads and get_buckets() still worked. Still present on main (v0.10.2).
• Fix: one line in batch_get_entity_and_buckets — elif sk.startswith(schema.SK_BUCKET): → elif sk == schema.sk_state(): (async source repository.py; regenerated into sync_repository.py).
• Also: added a TODO(clock-seam) at Repository._now_ms() noting that limiter.py/lease.py use inline int(time.time() * 1000) instead of routing through _now_ms(), so it is not the single injectable clock; follow-up to put _now_ms() on RepositoryProtocol and route both through it.

Test plan

Added regression tests the suite lacked (verified RED before the fix, GREEN after):

• tests/unit/test_repository.py: test_batch_get_entity_and_buckets_returns_existing_buckets, test_batch_get_entity_and_buckets_finds_bucket_without_meta (the no-#META real-world trigger)
• tests/unit/test_limiter.py: TestRateLimiterRefillRecovery — exhaust → wait → acquire succeeds, on both speculative and non-speculative paths; asserts the rejection reports a real retry_after (catches the retry_after=0.0 symptom)
• Sync twins regenerated (test_sync_repository.py, test_sync_limiter.py)
• New tests: 8 passed (async + sync); full unit suite: 2623 passed
• mypy clean; ruff check/format clean; sync-generation drift: none; pre-push patch coverage: 100%

Fixes #428

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.43%. Comparing base (4f7cd02) to head (8123fea).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #429      +/-   ##
==========================================
+ Coverage   92.39%   92.43%   +0.03%     
==========================================
  Files          37       37              
  Lines        7854     7854              
==========================================
+ Hits         7257     7260       +3     
+ Misses        597      594       -3     

Flag	Coverage Δ
doctest	29.14% <0.00%> (ø)
e2e	42.92% <100.00%> (+0.56%)	⬆️
integration	51.34% <100.00%> (+0.58%)	⬆️
unit	92.23% <100.00%> (+0.03%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.