feat(core): add TAPI backoff v2 infrastructure (1/3)

[abueide]

Overview

This PR adds the core backoff infrastructure for TAPI backoff v2. This is part 1 of a 3-part implementation that establishes the foundation without integration into the upload flow.

Related PRs:

• Part 2: Error classification system (feat(core): add error classification and default HTTP config (3/3) #1150)
• Part 3: Integration with SegmentDestination (feat(core): integrate TAPI backoff v2 into upload flow (3/3) #1151)

Components Added

UploadStateMachine

Manages global rate limiting state for 429 responses.

Key methods:

• canUpload(): Upload gate that respects rate limit wait times
• handle429(): Sets rate limit state with configurable retry limits
• reset(): Clears rate limit state on successful upload

The state machine persists state across app restarts and supports two states: READY and RATE_LIMITED.

BatchUploadManager

Handles per-batch exponential backoff for transient errors like 5xx responses and network failures.

Key methods:

• createBatch(): Creates metadata for a batch (only called on first failure)
• handleRetry(): Calculates exponential backoff with jitter and updates metadata
• validatePersistedMetadata(): Validates timestamps on app restart and drops corrupted batches
• removeBatch(): Removes metadata after successful upload or when limits exceeded

Config Validation

Provides validation and default application for backoff configurations:

• validateRateLimitConfig(): Validates rate limit configuration
• validateBackoffConfig(): Validates backoff configuration

Ensures all numeric values are within safe bounds and applies sensible defaults when values are missing.

Type Definitions

Adds TypeScript types for the backoff system:

• HttpConfig: Container for Settings CDN configuration
• RateLimitConfig: Global rate limiting configuration
• BackoffConfig: Per-batch backoff configuration
• UploadStateData: State machine persistence types
• BatchMetadata: Per-batch retry metadata
• ErrorClassification: Error classification result type

Implementation Details

State Migration

The state machine automatically migrates legacy WAITING state to RATE_LIMITED on app startup to maintain compatibility with any persisted state from development builds.

Metadata Validation

On app restart, the BatchUploadManager validates all persisted batch metadata timestamps. Batches with corrupted or invalid timestamps (negative values, far-future dates, or dates in the past) are automatically dropped to prevent issues.

Batch Lifecycle

Batch metadata is only created on the first failure, not when the batch is initially created. This prevents unnecessary persistence overhead for successful uploads.

Configuration

Both rate limiting and backoff behavior can be configured via Settings CDN through the httpConfig field. The implementation includes production-ready defaults that can be overridden per workspace.

Testing

These components are designed to be unit-testable in isolation. Integration testing will be covered when these components are integrated into the upload flow in part 3.

Dependencies

This PR has no dependencies and can be reviewed independently.

[abueide]

Note: Unit tests for the backoff infrastructure will be added in a separate PR to keep the review focused on the implementation.

[abueide]

Closing this PR - infrastructure split into two separate PRs for better reviewability:

• UploadStateMachine: feature/tapi-state-machine (574 lines)
• BatchUploadManager: feature/tapi-batch-manager (926 lines)

New PRs to be created shortly.