# Downloads, cache, and reproducibility

`bluertopo_download()` is for workflows where the durable deliverable is the original NOAA BlueTopo source file set. The function preserves NOAA basenames, keeps GeoTIFF and RAT sidecar files unmodified, verifies SHA-256 checksums by default, and writes manifests for future auditing.

## Plan first

    plan <- bluertopo_download(
      aoi,
      path = file.path(tempdir(), "bluertopo-downloads"),
      coverage = "fill",
      dry_run = TRUE
    )

Dry runs return planned assets without creating the destination directory.

## Download with verification

    manifest <- bluertopo_download(
      aoi,
      path = file.path(tempdir(), "bluertopo-downloads"),
      rat = TRUE,
      verify = "sha256",
      on_exists = "verify"
    )

Each row records the tile identifier, asset type, source URL, destination path, verification status, SHA-256 value, attempts, and timestamps. A fixed manifest is written at the download root for convenience, and query-addressed manifest copies are written under `manifests/` when a query hash is available.

## Existing files

`on_exists = "verify"` reuses an existing file only when verification succeeds. `on_exists = "skip"` records a skipped file without verification. `on_exists = "replace"` redownloads the asset.

    reused <- bluertopo_download(
      aoi,
      path = file.path(tempdir(), "bluertopo-downloads"),
      on_exists = "verify"
    )

## Package cache

`bluertopo()` uses the package cache for catalog files, downloaded source assets, and VRTs. Cache roots are marked with `.bluertopo-cache.json` before package-owned content is written. The default cache is session-temporary; set `options(bluertopo.cache_dir = "/path/to/cache")` when a persistent cache is wanted.

    bluertopo_cache_dir()

`bluertopo_cache_clear()` clears only the configured package cache. It refuses unmarked directories, suspicious roots, and symlinked cache paths.

    bluertopo_cache_clear(confirm = TRUE)

## Concurrency and retries

Downloads are currently deterministic and single-worker. `workers = NULL` and `workers = 1` are accepted; higher values are rejected until bounded parallel downloads are implemented. Individual assets still use retry/backoff behavior for transient transfer failures.

    manifest <- bluertopo_download(
      aoi,
      path = file.path(tempdir(), "bluertopo-downloads"),
      workers = 1,
      retries = 3
    )