KMP WorkManager

If you do not provide an explicit name to the @Worker annotation, KSP defaults to the simple class name. This is dangerous because:

1. ProGuard/R8 might obfuscate the class name.
2. Refactoring the class name will change the lookup key.

If a task is already persisted in the system queue under the old name, it will fail to run (resulting in a "worker not found" error).

Best Practice: Always provide a stable string name.

@Worker(name = "SyncWorker") // Stable across renames and ProGuard
class SyncWorker : AndroidWorker { ... }

In v2.5.0, ChainExecutor on iOS now honors the shouldRetry flag in WorkerResult.Failure.

• Failure(shouldRetry = false): Triggers immediate chain abandonment. The chain definition and progress files are deleted immediately.
• Failure(shouldRetry = true) or Retry(...): Continues to consume the chain-level retry budget (default MAX_RETRIES = 3).

Warning: Because the default value for shouldRetry in the Failure data class is false, any worker returning WorkerResult.Failure("message") without explicitly setting shouldRetry = true will now cause the entire chain to abort on the first attempt. If you want a transient failure to trigger a retry, you must use WorkerResult.Failure(message, shouldRetry = true) or WorkerResult.Retry(reason).

Android 15 enforces a cumulative 6-hour-per-day cap on dataSync foreground service runtime. If this cap is reached:

• setForeground() throws ForegroundServiceTypeException.
• WorkManager marks the work as FAILED and will not retry.

Recommendation: For long-running tasks (like large backups), use chunked work combined with the requiresUnmeteredNetwork constraint so that each worker instance remains short-lived.

An ExecutionRecord is a persisted record of a background task chain execution, written when a chain finishes.

ExecutionStatus values:

• SUCCESS: All steps completed successfully.
• FAILURE: A step failed; the chain is re-queued for retry.
• ABANDONED: Max retries exhausted or non-idempotent tasks after corrupt-progress self-heal.
• SKIPPED: Chain discarded before execution (due to REPLACE policy or deadline exceeded).
• TIMEOUT: Chain timed out within its BGTask window; re-queued for continuation.

Task chains allow you to orchestrate complex background workflows by executing multiple tasks in a specific order. They support both sequential execution (one task after another) and parallel execution (multiple tasks simultaneously).

Key features include:

• Automatic dependency management: Tasks run in the correct order based on the chain definition.
• Error handling: If any task in the chain fails, the entire chain stops.
• Parallel execution: Independent tasks can run at the same time to optimize performance.
• Type-safe builder API: Uses a fluent syntax for defining workflows.

The ParallelHttpDownloadWorker improves download speed by splitting a file into multiple HTTP Range chunks and downloading them concurrently.

Key features:

• Concurrency: Supports splitting a file into $N$ chunks, where $N$ is between 1 and 16 (default is 4).
• Resumability: Persists .partN files for each chunk, allowing individual chunks to resume after a process kill or retry.
• Fallback: Automatically falls back to sequential downloading if the server does not support Accept-Ranges: bytes or does not provide a Content-Length header.
• Merging: Once all chunks are complete, they are merged into the final file.

// Conceptual usage of ParallelHttpDownloadWorker
// It uses HTTP Range headers to download chunks concurrently.

The IosBackgroundDownloadWorker (experimental) allows downloads to survive full app termination by utilizing URLSessionConfiguration.background.

Lifecycle Note: The worker returns Success as soon as the iOS operating system accepts the request. The actual completion of the download is delivered later via the TaskEventBus. For host integration details, see docs/IOS_BACKGROUND_URL_SESSION.md.

In v2.5.0, both dedicated-identifier tasks and dynamic tasks on iOS follow the standard WorkManager retry contract. Workers must be idempotent because they may run up to 5 times by default.

Retry Contract:

• Success $\rightarrow$ Task completed, do not re-enqueue.
• Failure(shouldRetry = false) $\rightarrow$ Terminal failure, do not re-enqueue.
• Failure(shouldRetry = true) $\rightarrow$ Re-enqueue with incremented attempt counter.
• Retry(attemptCap = N) $\rightarrow$ Re-enqueue, abandon after N total attempts.
• Retry(attemptCap = null) $\rightarrow$ Re-enqueue, abandon after 5 attempts (default).
• Retry(delayMs = X) $\rightarrow$ Re-enqueue with earliestBeginDate = now + X.

Note: The attempt counter is persisted under the internal kmpAttemptCount key to survive process kills.