[AZ-320] Add C11 IdempotentRetryTileUploader decorator

Wraps HttpTileUploader (AZ-319) with two bounded retry budgets:

- In-call (per-batch) — re-invokes inner on PARTIAL outcome up to
  `max_in_call_retries` times with capped exponential backoff
  (`min(base ** attempt_number, cap)`). On exhaustion: surfaces an
  operator hint via `next_retry_at_s = now + backoff_cap_s`.
- Per-tile (cross-call) — atomically increments c6's
  `tiles.upload_attempts` counter for every rejection; once a tile
  hits `max_per_tile_attempts` it is forward-only transitioned to
  `voting_status = upload_giveup` (excluded from `pending_uploads`).
  Each transition emits FDR `kind="c11.upload.giveup"` plus an
  ERROR log.

C6 contract changes (AZ-303 v1.3.0):
- VotingStatus.UPLOAD_GIVEUP added (forward-only from PENDING/TRUSTED).
- TileMetadataStore.increment_upload_attempts(tile_id) -> int added
  with NotImplementedError default for backwards-compat.
- Migration 0003_c11_upload_attempts: additive column +
  widened ck_tiles_voting_status (preserves IS NULL clause).

C11 wiring:
- C11RetryConfig + disable_retry_decorator on C11Config.
- build_tile_uploader wraps in decorator by default; bypass flag
  returns the bare HttpTileUploader. New `clock` keyword.

Cross-component isolation honoured (AZ-507): the decorator declares
`_RetryMetadataStoreLike` Protocol cut over c6's TileMetadataStore
and references `UPLOAD_GIVEUP` via a local string constant — no c6
imports.

Tests: 13 decorator + 1 conformance + 2 factory bypass + AC-6 enum
update + alembic head bump + AZ-272 schema fixture. 238 passed across
c11/c6/fdr suites; pre-existing perf microbenches unrelated.

Code review: PASS_WITH_WARNINGS (5 Low/Informational findings,
docs-level or downstream-CI-blocked). See
_docs/03_implementation/reviews/batch_41_review.md.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-13 08:48:53 +03:00
parent 90f4ac78f4
commit a06b107fc3
19 changed files with 1788 additions and 21 deletions
@@ -144,6 +144,9 @@ class _FullTileMetadataStore:
def get_by_id(self, tile_id):
raise NotImplementedError
def increment_upload_attempts(self, tile_id):
raise NotImplementedError
class _PartialTileMetadataStore:
def query_by_bbox(self, bbox, zoom, *, voting_filter=None, source_filter=None):
@@ -559,10 +562,19 @@ def test_ac9_contract_methods_match_protocol(contract_filename: str, proto: type
def test_ac10_voting_status_has_documented_states_only() -> None:
assert {v.value for v in VotingStatus} == {"pending", "trusted", "rejected"}
# AC-6 (AZ-320): ``upload_giveup`` is the new terminal state set by
# the C11 retry decorator after a tile exhausts its per-tile retry
# budget. Forward-only — see tile_metadata_store.md v1.3.0 I-8.
assert {v.value for v in VotingStatus} == {
"pending",
"trusted",
"rejected",
"upload_giveup",
}
assert VotingStatus.PENDING.value == "pending"
assert VotingStatus.TRUSTED.value == "trusted"
assert VotingStatus.REJECTED.value == "rejected"
assert VotingStatus.UPLOAD_GIVEUP.value == "upload_giveup"
# ----------------------------------------------------------------------