Lanes and adaptive concurrency#

Attic backs up two very different kinds of photo assets in parallel: ones that are already on disk, and ones that still live on Apple's servers. Mixing them in a single pool is a compromise that loses to both extremes, so the exporter partitions each batch into two lanes and runs each at a concurrency limit suited to its behavior.

The two kinds of assets#

With "Optimize Mac Storage" enabled, Photos.app keeps only recent or frequently-accessed originals on disk. Everything else is a thumbnail-only placeholder whose original lives in iCloud.

Local assets#

The original file is on disk in the Photos library bundle. Exporting one is essentially a file copy + inline SHA-256 hash.

• Fast — hundreds of MB/s, limited by disk and CPU.
• Predictable — no network in the loop.
• Few failure modes — "disk full" and "permission denied" are about it.
• Parallelism helps — more concurrency, more throughput, up to disk saturation.

iCloud-only assets#

Only the thumbnail is on disk. Exporting means asking Photos.app to pull the original from iCloud, which involves auth, a round-trip to cold storage, and a write back to local disk.

• Slow — network-bound, often seconds per asset.
• Heavily throttled — iCloud rate-limits hard if you ask for too many at once.
• Many transient failure modes — timeouts, -1712 AppleEvent timeouts, 503s from iCloud, rate-limit waits.
• Some permanent failures — shared-album derivatives that have gone missing server-side raise -1728 "Can't get media item". Retrying doesn't help.
• Parallelism past a point hurts — iCloud starts queuing you, total throughput drops.

Why a single pool is wrong#

If you run one pool at a single concurrency limit, you're stuck picking a number that's wrong for one side:

Neither number is right. Splitting the lanes lets each run at its own pace.

How the split is decided#

LadderKit exposes a LocalAvailabilityProviding protocol that answers "is this asset's original on disk?" The real implementation, PhotosDatabaseLocalAvailability, reads one column from Photos.sqlite:

ZINTERNALRESOURCE.ZLOCALAVAILABILITY = 1

This is the same flag Photos.app itself uses to decide whether to show the little download-cloud icon in the UI. It's cheap to read and doesn't touch PhotoKit.

At batch time, PhotoExporter partitions every UUID:

• ZLOCALAVAILABILITY = 1 → local lane
• everything else → iCloud lane

          ┌── local lane    ──→ concurrency = maxConcurrency (e.g. 16)
batch ────┤
          └── iCloud lane   ──→ concurrency = AIMDController.currentLimit()
                                (adapts: 1-12, starts at 6)

Each lane has its own TaskGroup, its own concurrency cap, and — critically — its own feedback signals. Congestion on the iCloud side doesn't slow the local side down.

The iCloud lane is adaptive#

Because iCloud's tolerance shifts minute to minute, picking a fixed iCloud concurrency is also wrong. The iCloud lane is gated by an AIMD controller (attic's AIMDController, implementing LadderKit's AdaptiveConcurrencyControlling protocol).

AIMD (Additive Increase, Multiplicative Decrease) is the congestion-control policy TCP uses. The asymmetry is the point: recover cautiously, back off hard.

• The controller keeps a sliding window of the last 20 outcomes.
• Transient failure rate > 30% → halve the limit (floor at minLimit).
• Transient failure rate ≤ 5% → grow the limit by 1 (cap at maxLimit).
• Window clears on every limit change — prevents stale pre-change outcomes from immediately re-tripping the new limit.

The exporter polls currentLimit() between dispatches and reports each ExportOutcome (.success, .transientFailure, .permanentFailure) via record(_:). The controller is observation-only — it doesn't hold permits or gate dispatch directly, it just publishes a number the exporter reads.

Why permanent failures don't affect the limit#

A batch full of -1728 shared-album tombstones isn't a lane-health signal — the lane is fine, those assets just don't exist anymore. Reporting them as transient failures would permanently pin the lane at minLimit.

Ladder classifies each export error as .other, .transientCloud, or .permanentlyUnavailable and reports .permanentFailure to the controller for the last category. The controller ignores .permanentFailure entirely — it doesn't enter the window, doesn't count toward the rate. Attic also records permanent-unavailable UUIDs in unavailable-assets.json so they're skipped forever on future runs.

What this looks like in practice#

On a mixed Optimize-Storage library:

Backup started — 2,431 assets pending
  Local lane:   1,804 assets  →  running at 16 concurrent
  iCloud lane:    627 assets  →  running at 6 concurrent (adaptive)

[...]

  iCloud lane throttling — limit 6 → 3
  iCloud lane recovering — limit 3 → 4
  iCloud lane recovering — limit 4 → 5

• The local lane blasts through cached originals in parallel.
• The iCloud lane ticks along at whatever rate iCloud currently tolerates.
• Failures in one lane don't slow the other down.
• Permanent failures (tombstones) are skipped, not retried, and don't affect concurrency tuning.

Where this lives in the code#

LadderKit supplies the mechanism (partitioning, protocol, outcome reporting). AtticCore supplies the policy (the actual AIMD controller implementation, the unavailable store, the backup pipeline). The two responsibilities are cleanly separated so a different caller could plug in a different controller (EWMA, PID, token bucket) without touching ladder.