archiveDownload.test.ts

import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
import { get, set, del } from 'idb-keyval'
import {
  downloadArchive,
  deleteArchive,
  ARCHIVE_PARTIAL_KEY,
  ARCHIVE_PROGRESS_KEY,
  ARCHIVE_SOURCE_KEY,
  ARCHIVE_VERSION_KEY,
  ArchiveSizeMismatchError,
  ArchiveHashMismatchError,
  ArchiveTooLargeError,
  readArchiveVersion,
} from './archiveDownload'
import { CORRIDOR_ARCHIVE_KEY } from '../map/pmtilesSource'
import { completedMarker, recordCompleted } from './storageHealth'
import { publishedHash } from './dataManifest'
import { Sha256, sha256Hex, type Sha256State } from './sha256'

// The download behind Downloads.tsx's buttons. WIREFRAMES.md `7a` requires a
// failed transfer to RESUME rather than restart, and that promise is the
// whole reason this module is more than a fetch call: re-pulling 300 MB from
// zero because a connection dropped at 90% is exactly the failure someone on
// trailhead wifi cannot afford.
//
// Two traps get specific attention below.
//
// **A server that ignores Range.** Ask for `bytes=N-` and a compliant server
// answers 206 with the remainder. A server that does not support ranges
// answers 200 with the WHOLE file - and appending that to the bytes already
// held produces a corrupt archive of exactly the right length, which passes
// every size check and then renders a broken map. The status code has to be
// checked, not assumed.
//
// **Never destroying a good archive.** Partial bytes live under their own
// key. A failed or aborted attempt must leave both the partial progress and
// any previously-completed archive intact.

vi.mock('idb-keyval', () => ({ get: vi.fn(), set: vi.fn(), del: vi.fn() }))

// The published-hash lookup is mocked rather than served through the fetch
// stub above: what it reads (latest.json under VITE_DATA_BASE_URL, which is
// unset under test) is dataManifest.ts's own subject, tested there. Here the
// interesting variable is only what the bucket claims - a hash, a different
// hash, or no answer at all.
vi.mock('./dataManifest', () => ({ publishedHash: vi.fn() }))

const mockedGet = vi.mocked(get)
const mockedSet = vi.mocked(set)
const mockedDel = vi.mocked(del)
const mockedPublishedHash = vi.mocked(publishedHash)

const URL_ = 'https://cdn.example.org/background.pmtiles'
/** What latest.json calls it - passed explicitly now, never guessed. */
const ARTIFACT = 'background.pmtiles'

/** In-memory stand-in for IndexedDB. */
function withStore(initial: Record<string, unknown> = {}) {
  const store: Record<string, unknown> = { ...initial }
  mockedGet.mockImplementation(async (key) => store[key as string])
  mockedSet.mockImplementation(async (key, value) => {
    store[key as string] = value
  })
  mockedDel.mockImplementation(async (key) => {
    delete store[key as string]
  })
  return store
}

function bytes(...values: number[]) {
  return new Uint8Array(values)
}

/** A fetch returning `chunks` as a stream, with the given status/headers. */
function mockFetch({
  chunks,
  status = 200,
  totalBytes,
  contentRange,
  etag,
}: {
  chunks: Uint8Array[]
  status?: number
  totalBytes?: number
  contentRange?: string
  etag?: string
}) {
  return vi.spyOn(globalThis, 'fetch').mockImplementation(async () => {
    const body = new ReadableStream<Uint8Array>({
      start(controller) {
        for (const chunk of chunks) controller.enqueue(chunk)
        controller.close()
      },
    })
    const headers = new Headers()
    const declared = totalBytes ?? chunks.reduce((n, c) => n + c.length, 0)
    headers.set('content-length', String(declared))
    if (contentRange) headers.set('content-range', contentRange)
    if (etag) headers.set('etag', etag)

    return new Response(body, { status, headers })
  })
}

/**
 * The archive the map would read out of this store, assembled the way
 * archiveStore.ts assembles it - or undefined where there is not one.
 *
 * Since #553 a finished archive is a run of segment records named by a
 * completion marker, so "is it stored" is no longer a lookup of one key. These
 * helpers keep the tests written in terms of the archive rather than the
 * layout: what a hiker has is a map, not a record count.
 */
function storedArchive(
  store: Record<string, unknown>,
  key = CORRIDOR_ARCHIVE_KEY,
): Blob | undefined {
  const complete = store[`${key}:complete`] as { generation: number } | undefined
  if (complete === undefined) {
    // The pre-#553 whole-archive record, which archiveStore.ts still serves.
    const legacy = store[key]
    return legacy instanceof Blob ? legacy : undefined
  }
  return new Blob(segmentsIn(store, complete.generation, key))
}

/** One generation's segment records, in order, up to the first gap. */
function segmentsIn(
  store: Record<string, unknown>,
  generation: number,
  key = CORRIDOR_ARCHIVE_KEY,
): Blob[] {
  const found: Blob[] = []
  for (let index = 0; ; index += 1) {
    const part = store[`${key}:g${generation}:${index}`]
    if (!(part instanceof Blob)) return found
    found.push(part)
  }
}

/**
 * The bytes a resume would pick up - segments on disk that are NOT the finished
 * archive - or undefined where there are none.
 *
 * Defined by exclusion rather than by reading the source record, because that is
 * the question the tests are actually asking: "was anything left behind". After
 * a completed download the segments are still there and are the archive itself,
 * which is not a partial by any reading.
 */
function heldPartial(
  store: Record<string, unknown>,
  key = CORRIDOR_ARCHIVE_KEY,
): Blob | undefined {
  const complete = store[`${key}:complete`] as { generation: number } | undefined
  for (const generation of [0, 1]) {
    if (complete?.generation === generation) continue
    const parts = segmentsIn(store, generation, key)
    if (parts.length > 0) return new Blob(parts)
  }
  return undefined
}

/**
 * Store contents standing in for an interrupted transfer holding `blob`.
 *
 * Spread into a `withStore` fixture. One segment, which is what a real transfer
 * under SEGMENT_BYTES produces, and generation 0, which is where a transfer
 * starts when nothing has completed under the key yet.
 */
function partialOf(
  blob: Blob,
  generation = 0,
  key = CORRIDOR_ARCHIVE_KEY,
): Record<string, unknown> {
  return { [`${key}:g${generation}:0`]: blob }
}

/** A completed archive holding `blob`, as `markComplete` leaves it: segments
 *  under a generation, named by a marker. What a phone that finished a download
 *  on a current build actually has. */
function completedOf(
  blob: Blob,
  generation = 0,
  key = CORRIDOR_ARCHIVE_KEY,
): Record<string, unknown> {
  return {
    ...partialOf(blob, generation, key),
    [`${key}:complete`]: {
      generation,
      segments: 1,
      totalBytes: blob.size,
    },
  }
}

beforeEach(() => {
  vi.clearAllMocks()
  // The default for every test that is not about verification: no published
  // answer, which is what a field-test server or an older release gives, and
  // which must leave the download behaving exactly as it did before #197.
  mockedPublishedHash.mockResolvedValue(null)
})

afterEach(() => {
  vi.restoreAllMocks()
})

describe('downloadArchive — a clean first run', () => {
  it('stores the finished archive where the map reads it from', async () => {
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3), bytes(4, 5, 6)] })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(storedArchive(store)).toBeInstanceOf(Blob)
  })

  it('stores every byte it was sent, in order', async () => {
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3), bytes(4, 5, 6)] })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })
    const stored = new Uint8Array(await (storedArchive(store) as Blob).arrayBuffer())

    expect([...stored]).toEqual([1, 2, 3, 4, 5, 6])
  })

  it('reports progress as chunks arrive, not only at the end', async () => {
    withStore()
    mockFetch({ chunks: [bytes(1, 2, 3), bytes(4, 5, 6)] })
    const onProgress = vi.fn()

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
      artifactKey: ARTIFACT,
      onProgress,
    })

    expect(onProgress.mock.calls.length).toBeGreaterThan(1)
    expect(onProgress).toHaveBeenLastCalledWith({ receivedBytes: 6, totalBytes: 6 })
  })

  it('clears the partial state once the archive is complete', async () => {
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)] })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(heldPartial(store)).toBeUndefined()
    expect(store[ARCHIVE_PROGRESS_KEY]).toBeUndefined()
  })

  it('asks for the whole file when nothing is held yet', async () => {
    withStore()
    const spy = mockFetch({ chunks: [bytes(1, 2, 3)] })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })
    const init = spy.mock.calls[0][1] as RequestInit | undefined

    expect(new Headers(init?.headers).get('range')).toBeNull()
  })
})

describe('downloadArchive — resuming', () => {
  it('asks only for the bytes it does not already have', async () => {
    withStore({
      ...partialOf(new Blob([bytes(1, 2, 3)])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 3, totalBytes: 6 },
      // A partial written by this module always records where it came from;
      // one without it is deliberately discarded rather than resumed onto.
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    const spy = mockFetch({
      chunks: [bytes(4, 5, 6)],
      status: 206,
      totalBytes: 3,
      contentRange: 'bytes 3-5/6',
    })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })
    const init = spy.mock.calls[0][1] as RequestInit | undefined

    expect(new Headers(init?.headers).get('range')).toBe('bytes=3-')
  })

  it('joins the resumed bytes onto what it already had', async () => {
    const store = withStore({
      ...partialOf(new Blob([bytes(1, 2, 3)])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 3, totalBytes: 6 },
      // A partial written by this module always records where it came from;
      // one without it is deliberately discarded rather than resumed onto.
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    mockFetch({
      chunks: [bytes(4, 5, 6)],
      status: 206,
      totalBytes: 3,
      contentRange: 'bytes 3-5/6',
    })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })
    const stored = new Uint8Array(await (storedArchive(store) as Blob).arrayBuffer())

    expect([...stored]).toEqual([1, 2, 3, 4, 5, 6])
  })

  it('counts resumed progress from what was already held, not from zero', async () => {
    withStore({
      ...partialOf(new Blob([bytes(1, 2, 3)])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 3, totalBytes: 6 },
      // A partial written by this module always records where it came from;
      // one without it is deliberately discarded rather than resumed onto.
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    const onProgress = vi.fn()
    mockFetch({
      chunks: [bytes(4, 5, 6)],
      status: 206,
      totalBytes: 3,
      contentRange: 'bytes 3-5/6',
    })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
      artifactKey: ARTIFACT,
      onProgress,
    })

    expect(onProgress).toHaveBeenLastCalledWith({ receivedBytes: 6, totalBytes: 6 })
  })

  it('starts over safely when the server ignores Range and sends the whole file', async () => {
    // The silent-corruption trap: appending a full 200 body to existing
    // partial bytes yields a file of plausible length that is entirely wrong.
    const store = withStore({
      ...partialOf(new Blob([bytes(1, 2, 3)])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 3, totalBytes: 6 },
      // A partial written by this module always records where it came from;
      // one without it is deliberately discarded rather than resumed onto.
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    mockFetch({ chunks: [bytes(9, 9, 9, 9, 9, 9)], status: 200, totalBytes: 6 })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })
    const stored = new Uint8Array(await (storedArchive(store) as Blob).arrayBuffer())

    expect([...stored]).toEqual([9, 9, 9, 9, 9, 9])
  })
})

describe('downloadArchive — failure', () => {
  it('keeps what it received when the connection drops', async () => {
    const store = withStore()
    vi.spyOn(globalThis, 'fetch').mockImplementation(async () => {
      // Pull-based, so the first read genuinely delivers a chunk and the
      // SECOND one fails. Calling controller.error() straight after an
      // enqueue in start() discards the queued chunk instead, which models a
      // connection that died before delivering anything - a different case,
      // and not the one this test is about.
      let pulls = 0
      const body = new ReadableStream<Uint8Array>({
        pull(controller) {
          if (pulls === 0) controller.enqueue(bytes(1, 2, 3))
          else controller.error(new TypeError('network error'))
          pulls += 1
        },
      })
      const headers = new Headers({ 'content-length': '6' })
      return new Response(body, { status: 200, headers })
    })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow()

    expect(heldPartial(store)).toBeInstanceOf(Blob)
    expect(store[ARCHIVE_PROGRESS_KEY]).toMatchObject({ receivedBytes: 3 })
  })

  it('leaves a previously-downloaded archive untouched when a new attempt fails', async () => {
    const store = withStore(completedOf(new Blob([bytes(7, 7, 7)])))
    vi.spyOn(globalThis, 'fetch').mockRejectedValue(new TypeError('offline'))

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow()

    expect(new Uint8Array(await (storedArchive(store) as Blob).arrayBuffer())).toEqual(
      bytes(7, 7, 7),
    )
  })

  it('keeps the archive readable while a re-download is under way', async () => {
    // The property generations exist for (#553). Segments live under fixed
    // names, so a re-download writing its own segment 0 over the working
    // archive's would destroy the map at the moment the hiker asked to update
    // it - and it would be gone before a single new byte was verified.
    const store = withStore(completedOf(new Blob([bytes(7, 7, 7)])))
    let midTransfer: Blob | undefined
    vi.spyOn(globalThis, 'fetch').mockImplementation(async () => {
      const body = new ReadableStream<Uint8Array>({
        start(controller) {
          controller.enqueue(bytes(1, 2, 3))
          // What the map would read if it drew a tile right now.
          midTransfer = storedArchive(store)
          controller.error(new TypeError('the connection dropped'))
        },
      })
      return new Response(body, { headers: new Headers({ 'content-length': '6' }) })
    })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow()

    expect(new Uint8Array(await (midTransfer as Blob).arrayBuffer())).toEqual(
      bytes(7, 7, 7),
    )
    // And still afterwards: the failed attempt took its own generation with it.
    expect(new Uint8Array(await (storedArchive(store) as Blob).arrayBuffer())).toEqual(
      bytes(7, 7, 7),
    )
  })

  it('refuses to store an archive shorter than the server said it would be', async () => {
    // Truncation is the failure a size check exists to catch: a short PMTiles
    // archive opens fine and then returns nothing for tiles past the cut.
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)], totalBytes: 99 })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toBeInstanceOf(ArchiveSizeMismatchError)
    expect(storedArchive(store)).toBeUndefined()
  })

  it('says the mismatch in a hiker’s units, keeping the raw counts as fields', () => {
    // The message IS the UI - the download card renders it in a role="alert" -
    // and it used to read "297483822 bytes but the server said 314572800",
    // which is a log line shown to the one person guaranteed not to want one.
    const error = new ArchiveSizeMismatchError(314_000_000, 297_000_000)

    expect(error.message).toMatch(/297 MB/)
    expect(error.message).toMatch(/314 MB/)
    expect(error.message).not.toMatch(/\d{6,}/)
    expect(error.expectedBytes).toBe(314_000_000)
    expect(error.actualBytes).toBe(297_000_000)
  })

  it('keeps the partial bytes after a size mismatch, so a resume can finish it', async () => {
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)], totalBytes: 99 })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow()

    expect(heldPartial(store)).toBeInstanceOf(Blob)
  })

  it('stops when aborted, keeping what it has', async () => {
    const store = withStore()
    const controller = new AbortController()
    mockFetch({ chunks: [bytes(1, 2, 3), bytes(4, 5, 6)] })

    // Aborted from the progress callback, which fires only after a chunk has
    // really been taken in. Triggering it from inside the stream instead raced
    // the read loop - the stream refills its queue as `read()` resolves, so the
    // abort landed before the first chunk was accounted for, and the assertion
    // below then held for an EMPTY partial: "keeping what it has" where it had
    // nothing.
    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
        artifactKey: ARTIFACT,
        signal: controller.signal,
        onProgress: ({ receivedBytes }) => {
          if (receivedBytes >= 3) controller.abort()
        },
      }),
    ).rejects.toThrow()

    // The bytes that arrived before the abort are on disk, so the next attempt
    // resumes from there.
    expect(new Uint8Array(await (heldPartial(store) as Blob).arrayBuffer())).toEqual(
      bytes(1, 2, 3),
    )
    expect(storedArchive(store)).toBeUndefined()
  })

  it('rejects a non-OK response without touching stored state', async () => {
    const store = withStore()
    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
      new Response(null, { status: 404, statusText: 'Not Found' }),
    )

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(/404/)
    expect(heldPartial(store)).toBeUndefined()
  })
})

// The failure mode the size check is structurally unable to catch. totalBytes is
// DEFINED as heldBytes + declared, and a completed resume accumulates exactly
// heldBytes + declared - both sides of that comparison are the same expression.
// So a spliced archive always passes it, and the result is a PMTiles file whose
// directory and tile offsets disagree: a map that reports itself downloaded and
// renders wrong past the seam, offline, with no network to correct it.
describe('downloadArchive — refusing to splice two different archives', () => {
  it('discards partial bytes that came from a different URL', async () => {
    // A hiker who starts Standard, fails, then picks Light. Appending z12 bytes
    // onto z11 bytes would produce exactly the right length and a broken map.
    const store = withStore({
      ...partialOf(new Blob([bytes(9, 9, 9)])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 3, totalBytes: 6 },
      [ARCHIVE_SOURCE_KEY]: { url: 'https://cdn.example.org/background_z13.pmtiles' },
    })
    const fetchSpy = mockFetch({ chunks: [bytes(1, 2, 3)] })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    // No Range header at all: this is a fresh start, not a resume.
    expect(fetchSpy.mock.calls[0][1]).toMatchObject({ headers: undefined })
    const stored = storedArchive(store) as Blob
    expect(stored.size).toBe(3)
  })

  it('discards a partial with no source record, rather than resuming onto it blindly', async () => {
    // Written by a build before the source record existed, or left behind when
    // a quota failure interrupted persistPartial partway through.
    const store = withStore({
      ...partialOf(new Blob([bytes(9, 9, 9)])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 3, totalBytes: 6 },
    })
    mockFetch({ chunks: [bytes(1, 2, 3)] })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect((storedArchive(store) as Blob).size).toBe(3)
  })

  it('sends If-Range so the server itself refuses a stale resume', async () => {
    const store = withStore({
      ...partialOf(new Blob([bytes(1, 2, 3)])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 3, totalBytes: 6 },
      [ARCHIVE_SOURCE_KEY]: { url: URL_, etag: '"v1"' },
    })
    const fetchSpy = mockFetch({
      chunks: [bytes(4, 5, 6)],
      status: 206,
      etag: '"v1"',
    })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(fetchSpy.mock.calls[0][1]).toMatchObject({
      headers: { Range: 'bytes=3-', 'If-Range': '"v1"' },
    })
    expect((storedArchive(store) as Blob).size).toBe(6)
  })

  it('starts clean when the archive was republished mid-download', async () => {
    // If-Range makes the server arbitrate: a changed object comes back 200 with
    // the whole body instead of 206, and the existing status check treats that
    // as "start clean". The held bytes must NOT survive into the result.
    const store = withStore({
      ...partialOf(new Blob([bytes(9, 9, 9)])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 3, totalBytes: 6 },
      [ARCHIVE_SOURCE_KEY]: { url: URL_, etag: '"v1"' },
    })
    mockFetch({ chunks: [bytes(1, 2, 3, 4)], status: 200, etag: '"v2"' })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    const stored = storedArchive(store) as Blob
    expect(stored.size).toBe(4)
    expect(new Uint8Array(await stored.arrayBuffer())).toEqual(bytes(1, 2, 3, 4))
  })

  it('refuses a 206 whose ETag is not the one those bytes came from', async () => {
    // THE CASE THE r2.dev BUCKET ACTUALLY PRODUCES (#506). The test above has
    // the server arbitrating correctly - stale If-Range, 200, whole body. This
    // one has it ignoring If-Range and serving the range anyway, which is what
    // was measured against the live bucket: a stale validator is answered 206.
    //
    // The 206 is therefore worthless as evidence and the ETag is the only thing
    // left saying which object these bytes are from. Without the comparison,
    // bytes 4,5,6 of a DIFFERENT archive get appended to a held 1,2,3 and the
    // result is a 6-byte file of exactly the expected length - the splice that
    // renders a wrong map past the seam with no network to correct it.
    const store = withStore({
      ...partialOf(new Blob([bytes(1, 2, 3)])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 3, totalBytes: 6 },
      [ARCHIVE_SOURCE_KEY]: { url: URL_, etag: '"v1"', generation: 0, segments: 1 },
    })
    mockFetch({ chunks: [bytes(4, 5, 6)], status: 206, etag: '"v2"' })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(/no longer matches what the server has/)

    // Nothing spliced was stored, and the unusable segments are gone rather than
    // left for the next attempt to append to all over again.
    expect(storedArchive(store)).toBeUndefined()
    expect(heldPartial(store)).toBeUndefined()
    expect(store[ARCHIVE_SOURCE_KEY]).toBeUndefined()
    expect(store[ARCHIVE_PROGRESS_KEY]).toBeUndefined()
  })

  it('leaves a previously-downloaded map alone when it refuses a stale 206', async () => {
    // The rule the whole module is built around: someone with a good map who
    // taps update and hits a republished archive still has their good map.
    // The good map is a completed archive in generation 0, so the interrupted
    // transfer is in generation 1 - which is what #553's generations are for,
    // and what makes "refusing the stale 206 does not touch it" a real claim
    // rather than one the fixture arranges by using a different record name.
    const store = withStore({
      ...completedOf(new Blob([bytes(7, 7, 7, 7, 7, 7)]), 0),
      ...partialOf(new Blob([bytes(1, 2, 3)]), 1),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 3, totalBytes: 6 },
      [ARCHIVE_SOURCE_KEY]: { url: URL_, etag: '"v1"', generation: 1, segments: 1 },
    })
    mockFetch({ chunks: [bytes(4, 5, 6)], status: 206, etag: '"v2"' })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(/no longer matches what the server has/)

    const good = storedArchive(store) as Blob
    expect(good.size).toBe(6)
    expect(new Uint8Array(await good.arrayBuffer())).toEqual(bytes(7, 7, 7, 7, 7, 7))
  })

  it('resumes onto a 206 that states the same strong ETag', async () => {
    // The other half of the discrimination: the check must refuse a CHANGED
    // object without refusing the ordinary resume, which is the case the
    // WIREFRAMES 7a promise is made of.
    const store = withStore({
      ...partialOf(new Blob([bytes(1, 2, 3)])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 3, totalBytes: 6 },
      [ARCHIVE_SOURCE_KEY]: { url: URL_, etag: '"v1"', generation: 0, segments: 1 },
    })
    mockFetch({ chunks: [bytes(4, 5, 6)], status: 206, etag: '"v1"' })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    const stored = storedArchive(store) as Blob
    expect(new Uint8Array(await stored.arrayBuffer())).toEqual(bytes(1, 2, 3, 4, 5, 6))
  })

  it('resumes when the 206 states no ETag at all, leaving the hash to decide', async () => {
    // A bucket that exposes no ETag is the case PartialSource.etag is optional
    // for. There is nothing to compare, so this must not become a refusal to
    // resume - the published-hash check is what covers that configuration, and
    // it still runs at the end.
    const store = withStore({
      ...partialOf(new Blob([bytes(1, 2, 3)])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 3, totalBytes: 6 },
      [ARCHIVE_SOURCE_KEY]: { url: URL_, etag: '"v1"', generation: 0, segments: 1 },
    })
    mockFetch({ chunks: [bytes(4, 5, 6)], status: 206 })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(storedArchive(store)?.size).toBe(6)
  })

  it('resumes when the 206 states only a weak ETag, which cannot validate a range', async () => {
    // A weak validator promises semantic equivalence, not byte identity, so it
    // is not evidence the object CHANGED any more than it is evidence it did
    // not. Refusing on one would strand a resume on a server that sends them.
    const store = withStore({
      ...partialOf(new Blob([bytes(1, 2, 3)])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 3, totalBytes: 6 },
      [ARCHIVE_SOURCE_KEY]: { url: URL_, etag: '"v1"', generation: 0, segments: 1 },
    })
    mockFetch({ chunks: [bytes(4, 5, 6)], status: 206, etag: 'W/"v2"' })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(storedArchive(store)?.size).toBe(6)
  })

  it('keeps the strong ETag it was holding when a resume is interrupted under a weak one', async () => {
    // The label a partial carries has to stay the strong validator those bytes
    // were held against. Overwriting it with a weak one would leave the next
    // attempt comparing against something that cannot arbitrate a range, which
    // is the check above quietly disarmed. Asserted on an interrupted transfer
    // because a completed one discards the record it would be read from.
    const store = withStore({
      ...partialOf(new Blob([bytes(1, 2, 3)])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 3, totalBytes: 9 },
      [ARCHIVE_SOURCE_KEY]: { url: URL_, etag: '"v1"', generation: 0, segments: 1 },
    })
    mockFetch({ chunks: [bytes(4, 5)], status: 206, totalBytes: 99, etag: 'W/"v2"' })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(ArchiveSizeMismatchError)

    expect(store[ARCHIVE_SOURCE_KEY]).toMatchObject({ etag: '"v1"' })
  })

  it('records the source alongside the bytes when a transfer is interrupted', async () => {
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2)], totalBytes: 99, etag: '"v1"' })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(ArchiveSizeMismatchError)

    // generation and segments are the layout #553 added: which run of segment
    // records these bytes are in, and how many of them there are.
    expect(store[ARCHIVE_SOURCE_KEY]).toEqual({
      url: URL_,
      etag: '"v1"',
      generation: 0,
      segments: 1,
    })
  })

  it('ignores a weak ETag, which does not promise the byte identity a resume needs', async () => {
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2)], totalBytes: 99, etag: 'W/"v1"' })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(ArchiveSizeMismatchError)

    expect(store[ARCHIVE_SOURCE_KEY]).toEqual({
      url: URL_,
      etag: undefined,
      generation: 0,
      segments: 1,
    })
  })

  describe('downloadArchive — a response with nothing to read', () => {
    it('fails loudly rather than storing an empty archive', async () => {
      // A 200 with a null body is not a zero-byte map, it is a broken response.
      // Writing it to CORRIDOR_ARCHIVE_KEY would leave the app convinced it has
      // a map, offline, with no way to find out otherwise.
      const store = withStore()
      vi.spyOn(globalThis, 'fetch').mockResolvedValue(
        new Response(null, { status: 200, headers: { 'content-length': '3' } }),
      )

      await expect(
        downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
      ).rejects.toThrow(/no map data arrived/)
      expect(storedArchive(store)).toBeUndefined()
    })
  })

  describe('downloadArchive — a server that never says how big the file is', () => {
    it('still stores what arrived, rather than treating no length as zero length', async () => {
      // A chunked response carries no content-length. There is nothing to check
      // the size against, so the length check has to stand down instead of
      // deciding the archive is short - refusing a complete download over a
      // header the server was never obliged to send would be its own bug.
      const store = withStore()
      vi.spyOn(globalThis, 'fetch').mockImplementation(
        async () =>
          new Response(
            new ReadableStream<Uint8Array>({
              start(controller) {
                controller.enqueue(bytes(1, 2, 3, 4))
                controller.close()
              },
            }),
            { status: 200 },
          ),
      )

      await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

      const stored = storedArchive(store) as Blob
      expect(stored.size).toBe(4)
      expect(heldPartial(store)).toBeUndefined()
    })

    it('reports progress against an unknown total rather than a made-up one', async () => {
      withStore()
      vi.spyOn(globalThis, 'fetch').mockImplementation(
        async () =>
          new Response(
            new ReadableStream<Uint8Array>({
              start(controller) {
                controller.enqueue(bytes(1, 2))
                controller.close()
              },
            }),
            { status: 200 },
          ),
      )
      const onProgress = vi.fn()

      await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
        artifactKey: ARTIFACT,
        onProgress,
      })

      expect(onProgress).toHaveBeenCalledWith({ receivedBytes: 2, totalBytes: 0 })
    })
  })
})

describe('downloadArchive — packages are independent (issue #200)', () => {
  // The multi-package guarantee in one sentence: every record a download
  // touches derives from its own package key, so nothing one package does -
  // succeed, fail mid-stream, or get deleted - can reach another package's
  // bytes. These tests run two packages through exactly those lifecycles.
  const OTHER_KEY = 'ourhike:test-dem'
  const OTHER_URL = 'https://cdn.example.org/dem.pmtiles'

  it("downloading one package leaves another package's archive and partial untouched", async () => {
    const corridorPartial = new Blob(['corridor partial'])
    const store = withStore({
      ...partialOf(corridorPartial),
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 16, totalBytes: 100 },
    })
    mockFetch({ chunks: [bytes(9, 9, 9)] })

    await downloadArchive(OTHER_KEY, OTHER_URL, { artifactKey: 'dem.pmtiles' })

    expect(storedArchive(store, OTHER_KEY)).toBeInstanceOf(Blob)
    // The corridor package's resumable state survives, byte for byte.
    expect(await (heldPartial(store) as Blob).text()).toBe('corridor partial')
    expect(store[ARCHIVE_SOURCE_KEY]).toEqual({ url: URL_ })
    expect(store[ARCHIVE_PROGRESS_KEY]).toEqual({ receivedBytes: 16, totalBytes: 100 })
  })

  it("a failed download persists its partial under its own package, not another's", async () => {
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2)], totalBytes: 10 })

    await expect(
      downloadArchive(OTHER_KEY, OTHER_URL, { artifactKey: 'dem.pmtiles' }),
    ).rejects.toThrow()

    expect(heldPartial(store, OTHER_KEY)).toBeInstanceOf(Blob)
    expect(heldPartial(store)).toBeUndefined()
  })

  it("deleting one package keeps every other package's archive", async () => {
    const store = withStore({
      ...completedOf(new Blob(['corridor'])),
      ...completedOf(new Blob(['dem']), 0, OTHER_KEY),
      ...partialOf(new Blob(['stale attempt']), 1, OTHER_KEY),
    })

    await deleteArchive(OTHER_KEY)

    expect(storedArchive(store, OTHER_KEY)).toBeUndefined()
    expect(heldPartial(store, OTHER_KEY)).toBeUndefined()
    expect(await (storedArchive(store) as Blob).text()).toBe('corridor')
  })

  it('resume identity is judged per package: the same URL on another package starts clean', async () => {
    // A partial held by the corridor package must not be resumed onto by a
    // different package downloading from the same URL - the records simply
    // never meet, because the keys differ.
    const store = withStore({
      ...partialOf(new Blob(['held'])),
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    const spy = mockFetch({ chunks: [bytes(5)] })

    await downloadArchive(OTHER_KEY, URL_, { artifactKey: ARTIFACT })

    const init = spy.mock.calls[0][1] as RequestInit | undefined
    expect(init?.headers).toBeUndefined()
    expect(heldPartial(store)).toBeInstanceOf(Blob)
  })
})

describe('the completion marker (#190)', () => {
  // Written on success, cleared on delete, and in localStorage rather than
  // IndexedDB - the whole point is surviving the store the archive did not.

  beforeEach(() => {
    localStorage.clear()
  })

  afterEach(() => {
    localStorage.clear()
  })

  it('records a completed download, after the bytes are really stored', async () => {
    withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)] })

    expect(completedMarker(CORRIDOR_ARCHIVE_KEY)).toBeNull()
    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(completedMarker(CORRIDOR_ARCHIVE_KEY)).toBeInstanceOf(Date)
  })

  it('does not record an attempt that failed short', async () => {
    // A marker without a completed archive is exactly the false eviction
    // claim the marker must never produce.
    withStore()
    mockFetch({ chunks: [bytes(1)], totalBytes: 3 })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow()

    expect(completedMarker(CORRIDOR_ARCHIVE_KEY)).toBeNull()
  })

  it('clears the marker when the hiker deletes the archive', async () => {
    // "The phone removed your map" about a deletion they performed would be
    // the marker lying in the other direction.
    withStore({ [CORRIDOR_ARCHIVE_KEY]: new Blob(['x']) })
    recordCompleted(CORRIDOR_ARCHIVE_KEY)

    await deleteArchive(CORRIDOR_ARCHIVE_KEY)

    expect(completedMarker(CORRIDOR_ARCHIVE_KEY)).toBeNull()
  })
})

describe('verification against the published hash (#197)', () => {
  // The failure being closed here is not a download that breaks - it is one
  // that succeeds and is wrong. Bytes from two builds spliced at the resume
  // point produce a file of exactly the expected length, so the size check
  // provably cannot see it (totalBytes is DEFINED as heldBytes + declared),
  // and what arrives is a PMTiles archive whose directory disagrees with its
  // tiles: a map that reports itself downloaded and renders wrong past the
  // seam, with no network to correct it.

  const HELD = bytes(1, 2, 3, 4)
  const REST = bytes(5, 6, 7, 8)
  const WHOLE = bytes(1, 2, 3, 4, 5, 6, 7, 8)

  /** The hash of a resume that went right: held bytes then the remainder. */
  const WHOLE_HASH = sha256Hex(WHOLE)

  it('stores an archive whose bytes hash to what was published', async () => {
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3), bytes(4, 5, 6)] })
    mockedPublishedHash.mockResolvedValue(sha256Hex(bytes(1, 2, 3, 4, 5, 6)))

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(storedArchive(store)).toBeInstanceOf(Blob)
  })

  it('keeps nothing when the completed bytes are not what was published', async () => {
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedPublishedHash.mockResolvedValue(sha256Hex(bytes(9, 9, 9)))

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(ArchiveHashMismatchError)

    // Not stored, and not left resumable either: the bytes are the right
    // length and the wrong file, so resuming onto them would only rebuild
    // the same wrong archive.
    expect(storedArchive(store)).toBeUndefined()
    expect(heldPartial(store)).toBeUndefined()
    expect(store[ARCHIVE_PROGRESS_KEY]).toBeUndefined()
    expect(store[ARCHIVE_SOURCE_KEY]).toBeUndefined()
  })

  it('leaves a working archive alone when an update fails verification', async () => {
    const working = new Blob(['the map that already works'])
    const store = withStore(completedOf(working))
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedPublishedHash.mockResolvedValue(sha256Hex(bytes(9, 9, 9)))

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(ArchiveHashMismatchError)

    expect(await (storedArchive(store) as Blob).text()).toBe('the map that already works')
  })

  it('catches a splice that completes to exactly the expected length', async () => {
    // The case the length check cannot reach. Four held bytes from one build,
    // four more from another; the server honours the range (206) and the
    // total is exactly what was promised. Only the digest can tell.
    const store = withStore({
      ...partialOf(new Blob([HELD])),
      [ARCHIVE_SOURCE_KEY]: { url: URL_, sha256: WHOLE_HASH },
    })
    mockFetch({ chunks: [bytes(90, 91, 92, 93)], status: 206, totalBytes: 4 })
    mockedPublishedHash.mockResolvedValue(WHOLE_HASH)

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(ArchiveHashMismatchError)

    expect(storedArchive(store)).toBeUndefined()
    expect(heldPartial(store)).toBeUndefined()
  })

  it('completes a resume whose bytes really do belong together', async () => {
    const store = withStore({
      ...partialOf(new Blob([HELD])),
      [ARCHIVE_SOURCE_KEY]: { url: URL_, sha256: WHOLE_HASH },
    })
    mockFetch({ chunks: [REST], status: 206, totalBytes: 4 })
    mockedPublishedHash.mockResolvedValue(WHOLE_HASH)

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    const stored = new Uint8Array(await (storedArchive(store) as Blob).arrayBuffer())
    expect([...stored]).toEqual([...WHOLE])
  })

  it('drops a partial the bucket has republished away from, before asking for bytes', async () => {
    // The defence that does not depend on CORS exposing ETag - which is
    // exactly the configuration DATA_RELEASES.md's consequence #1 describes.
    // A published hash that has moved says the archive was rebuilt, so the
    // held bytes are from the previous release and there is no Range to send.
    const store = withStore({
      ...partialOf(new Blob([HELD])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 4, totalBytes: 8 },
      [ARCHIVE_SOURCE_KEY]: { url: URL_, sha256: sha256Hex(bytes(77)) },
    })
    const spy = mockFetch({ chunks: [WHOLE] })
    mockedPublishedHash.mockResolvedValue(WHOLE_HASH)

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    const init = spy.mock.calls[0][1] as RequestInit | undefined
    expect(init?.headers).toBeUndefined()
    const stored = new Uint8Array(await (storedArchive(store) as Blob).arrayBuffer())
    expect([...stored]).toEqual([...WHOLE])
  })

  it('resumes onto a partial the bucket still publishes the same hash for', async () => {
    const store = withStore({
      ...partialOf(new Blob([HELD])),
      [ARCHIVE_SOURCE_KEY]: { url: URL_, sha256: WHOLE_HASH },
    })
    const spy = mockFetch({ chunks: [REST], status: 206, totalBytes: 4 })
    mockedPublishedHash.mockResolvedValue(WHOLE_HASH)

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    const init = spy.mock.calls[0][1] as RequestInit | undefined
    expect(new Headers(init?.headers).get('range')).toBe('bytes=4-')
    expect(storedArchive(store)).toBeInstanceOf(Blob)
  })

  it('carries the hash of held bytes across a failed attempt', async () => {
    // What makes a resume cheap: the next attempt starts from this state
    // rather than re-reading several hundred megabytes of Blob to catch up.
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)], totalBytes: 10 })
    mockedPublishedHash.mockResolvedValue(sha256Hex(WHOLE))

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(ArchiveSizeMismatchError)

    const carried = (store[ARCHIVE_SOURCE_KEY] as { hash?: Sha256State }).hash
    expect(carried?.byteLength).toBe(3)
    expect(Sha256.fromState(carried as Sha256State).digest()).toBe(
      sha256Hex(bytes(1, 2, 3)),
    )
  })

  it('resumes from a carried hash state without re-reading the held bytes', async () => {
    const store = withStore({
      ...partialOf(new Blob([HELD])),
      [ARCHIVE_SOURCE_KEY]: {
        url: URL_,
        sha256: WHOLE_HASH,
        hash: new Sha256().update(HELD).toState(),
      },
    })
    mockFetch({ chunks: [REST], status: 206, totalBytes: 4 })
    mockedPublishedHash.mockResolvedValue(WHOLE_HASH)

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(storedArchive(store)).toBeInstanceOf(Blob)
  })

  it('re-hashes the held bytes when no state was carried', async () => {
    // A partial written by a build before this existed, or by an attempt
    // that found no published hash to check against. Re-reading is the cost;
    // being unable to verify would be the alternative.
    const store = withStore({
      ...partialOf(new Blob([HELD])),
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    mockFetch({ chunks: [REST], status: 206, totalBytes: 4 })
    mockedPublishedHash.mockResolvedValue(WHOLE_HASH)

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(storedArchive(store)).toBeInstanceOf(Blob)
  })

  it('ignores a carried state that claims more bytes than the partial holds', async () => {
    // Reachable: persistPartial writes the source record BEFORE the blob, on
    // purpose, and the blob write is the one that fails under quota pressure.
    // A state ahead of the bytes must not be trusted - it would digest a file
    // nobody has - and re-hashing from zero is always safe because the
    // partial only ever grows.
    const store = withStore({
      ...partialOf(new Blob([HELD])),
      [ARCHIVE_SOURCE_KEY]: {
        url: URL_,
        sha256: WHOLE_HASH,
        hash: new Sha256().update(WHOLE).toState(),
      },
    })
    mockFetch({ chunks: [REST], status: 206, totalBytes: 4 })
    mockedPublishedHash.mockResolvedValue(WHOLE_HASH)

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(storedArchive(store)).toBeInstanceOf(Blob)
  })

  it('starts the hash clean when the server ignores the range and resends the file', async () => {
    // A 200 in reply to a Range request means the whole file is coming. The
    // held bytes are not part of it, and hashing as though they were would
    // fail an archive that is perfectly good.
    const store = withStore({
      ...partialOf(new Blob([HELD])),
      [ARCHIVE_SOURCE_KEY]: {
        url: URL_,
        sha256: WHOLE_HASH,
        hash: new Sha256().update(HELD).toState(),
      },
    })
    mockFetch({ chunks: [WHOLE], status: 200 })
    mockedPublishedHash.mockResolvedValue(WHOLE_HASH)

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    const stored = new Uint8Array(await (storedArchive(store) as Blob).arrayBuffer())
    expect([...stored]).toEqual([...WHOLE])
  })

  it('stores the archive unverified when nothing published a hash for it', async () => {
    // The download must not start failing because a metadata file moved.
    // Absence of an expectation is absence of a check, not a failed one.
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedPublishedHash.mockResolvedValue(null)

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(storedArchive(store)).toBeInstanceOf(Blob)
  })

  it('records no hash state when there is nothing to check against', async () => {
    // No expectation, no reason to spend a phone's CPU on a digest nobody
    // will compare.
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)], totalBytes: 10 })
    mockedPublishedHash.mockResolvedValue(null)

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(ArchiveSizeMismatchError)

    expect((store[ARCHIVE_SOURCE_KEY] as { hash?: unknown }).hash).toBeUndefined()
  })

  it('verifies against the hash the bucket publishes now, not the one held', async () => {
    // A partial with no recorded expectation (written before this existed)
    // resumed against a republished archive: the current manifest is what
    // the completed bytes are held to, and they will not match.
    const store = withStore({
      ...partialOf(new Blob([HELD])),
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    mockFetch({ chunks: [bytes(50, 51, 52, 53)], status: 206, totalBytes: 4 })
    mockedPublishedHash.mockResolvedValue(WHOLE_HASH)

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(ArchiveHashMismatchError)

    expect(storedArchive(store)).toBeUndefined()
  })

  it('says plainly what happened, in words a hiker can act on', async () => {
    // The next move is a clean re-download, and the sentence has to be enough
    // to know that without guessing - and without hex, which helps nobody
    // standing on a trail. The hashes stay on the error for a field report.
    withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedPublishedHash.mockResolvedValue(sha256Hex(bytes(9)))

    const thrown = await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
      artifactKey: ARTIFACT,
    }).catch((e) => e)

    expect(thrown).toBeInstanceOf(ArchiveHashMismatchError)
    expect(thrown.message).toBe(
      'The map that arrived is not the one the server published, so it was not saved. ' +
        'Any map already on this phone is untouched. Try the download again.',
    )
    expect(thrown.message).not.toMatch(/[0-9a-f]{12}/)
    expect(thrown.expected).toBe(sha256Hex(bytes(9)))
    expect(thrown.actual).toBe(sha256Hex(bytes(1, 2, 3)))
  })

  it('keeps a whole archive the bucket republished mid-download', async () => {
    // The innocent cause of a mismatch: the manifest was read at the start of
    // the attempt, the bucket was republished before the last byte landed,
    // and what arrived is a complete, correct, NEWER archive. Throwing away a
    // gigabyte of good map over that would be its own failure, so the
    // manifest is read once more and bytes matching what is published now
    // are kept.
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedPublishedHash
      .mockResolvedValueOnce(sha256Hex(bytes(7, 7, 7)))
      .mockResolvedValueOnce(sha256Hex(bytes(1, 2, 3)))

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(storedArchive(store)).toBeInstanceOf(Blob)
    // Recorded as the build it actually is, not the one the attempt began by
    // asking about.
    expect(store[ARCHIVE_VERSION_KEY]).toBe(sha256Hex(bytes(1, 2, 3)))
  })

  it('still refuses bytes that match no published build, old or new', async () => {
    // The re-read is a rescue for a republish, not a second chance for a
    // splice: spliced bytes match nothing the bucket ever published.
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedPublishedHash
      .mockResolvedValueOnce(sha256Hex(bytes(7, 7, 7)))
      .mockResolvedValueOnce(sha256Hex(bytes(8, 8, 8)))

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(ArchiveHashMismatchError)

    expect(storedArchive(store)).toBeUndefined()
    expect(store[ARCHIVE_VERSION_KEY]).toBeUndefined()
  })

  it('refuses when the second manifest read has no answer either', async () => {
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedPublishedHash
      .mockResolvedValueOnce(sha256Hex(bytes(7, 7, 7)))
      .mockResolvedValueOnce(null)

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(ArchiveHashMismatchError)

    expect(storedArchive(store)).toBeUndefined()
  })
})

describe('which build is on this phone', () => {
  // DATA_RELEASES.md consequence #2: "a completed archive is stored with no
  // hash, no ETag and no version, so a republish is invisible to a device
  // that already downloaded". The verification above computes exactly that
  // answer and used to throw it away.

  it('keeps the verified hash beside the archive it describes', async () => {
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedPublishedHash.mockResolvedValue(sha256Hex(bytes(1, 2, 3)))

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(store[ARCHIVE_VERSION_KEY]).toBe(sha256Hex(bytes(1, 2, 3)))
    expect(await readArchiveVersion(CORRIDOR_ARCHIVE_KEY)).toBe(sha256Hex(bytes(1, 2, 3)))
  })

  it('claims nothing for an archive that could not be verified', async () => {
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedPublishedHash.mockResolvedValue(null)

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(store[ARCHIVE_VERSION_KEY]).toBeUndefined()
    expect(await readArchiveVersion(CORRIDOR_ARCHIVE_KEY)).toBeNull()
  })

  it('clears an older claim when the replacement cannot be verified', async () => {
    // The dangerous combination is a hash from the previous archive sitting
    // beside bytes nobody checked - a wrong answer stated with more
    // confidence than no answer at all.
    const store = withStore({ [ARCHIVE_VERSION_KEY]: sha256Hex(bytes(9)) })
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedPublishedHash.mockResolvedValue(null)

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(store[ARCHIVE_VERSION_KEY]).toBeUndefined()
  })

  it('records nothing for an archive that failed verification', async () => {
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedPublishedHash.mockResolvedValue(sha256Hex(bytes(9, 9, 9)))

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(ArchiveHashMismatchError)

    expect(store[ARCHIVE_VERSION_KEY]).toBeUndefined()
  })

  it('lets the record go with the archive the hiker deleted', async () => {
    const store = withStore({
      [CORRIDOR_ARCHIVE_KEY]: new Blob(['x']),
      [ARCHIVE_VERSION_KEY]: sha256Hex(bytes(1)),
    })

    await deleteArchive(CORRIDOR_ARCHIVE_KEY)

    expect(store[ARCHIVE_VERSION_KEY]).toBeUndefined()
  })

  it('is per package, like every other record here', async () => {
    const store = withStore({ 'ourhike:test-dem:version': sha256Hex(bytes(7)) })
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedPublishedHash.mockResolvedValue(sha256Hex(bytes(1, 2, 3)))

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(store['ourhike:test-dem:version']).toBe(sha256Hex(bytes(7)))
  })
})

describe('reporting the re-read of bytes already held (#197)', () => {
  // Catching a held partial's hash up is local work, and on a phone it is
  // seconds of it. Silence there is indistinguishable from a stalled
  // connection - and someone standing in a dead spot responds to those two
  // in opposite ways, so the attempt says which is happening.

  const HELD = bytes(1, 2, 3, 4)
  const REST = bytes(5, 6, 7, 8)
  const WHOLE_HASH = sha256Hex(bytes(1, 2, 3, 4, 5, 6, 7, 8))

  it('reports the re-read when a partial carries no hash state', async () => {
    withStore({
      ...partialOf(new Blob([HELD])),
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    mockFetch({ chunks: [REST], status: 206, totalBytes: 4 })
    mockedPublishedHash.mockResolvedValue(WHOLE_HASH)
    const onChecking = vi.fn()

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
      artifactKey: ARTIFACT,
      onChecking,
    })

    // Opens at zero so the state appears before the first window is read,
    // and closes having accounted for every held byte.
    expect(onChecking).toHaveBeenCalledWith({ checkedBytes: 0, totalBytes: 4 })
    expect(onChecking).toHaveBeenLastCalledWith({ checkedBytes: 4, totalBytes: 4 })
  })

  it('says nothing when the carried state already covers the held bytes', async () => {
    // The common case, and the reason the state is worth carrying: there is
    // no re-read to report because there is no re-read.
    withStore({
      ...partialOf(new Blob([HELD])),
      [ARCHIVE_SOURCE_KEY]: {
        url: URL_,
        sha256: WHOLE_HASH,
        hash: new Sha256().update(HELD).toState(),
      },
    })
    mockFetch({ chunks: [REST], status: 206, totalBytes: 4 })
    mockedPublishedHash.mockResolvedValue(WHOLE_HASH)
    const onChecking = vi.fn()

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
      artifactKey: ARTIFACT,
      onChecking,
    })

    expect(onChecking).not.toHaveBeenCalled()
  })

  it('says nothing on a clean first download', async () => {
    withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedPublishedHash.mockResolvedValue(sha256Hex(bytes(1, 2, 3)))
    const onChecking = vi.fn()

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
      artifactKey: ARTIFACT,
      onChecking,
    })

    expect(onChecking).not.toHaveBeenCalled()
  })

  it('says nothing when there is no published hash to check against', async () => {
    // No expectation means no digest is computed at all, so there is no
    // re-read to announce - and announcing one would be a lie about what the
    // phone is doing.
    withStore({
      ...partialOf(new Blob([HELD])),
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    mockFetch({ chunks: [REST], status: 206, totalBytes: 4 })
    mockedPublishedHash.mockResolvedValue(null)
    const onChecking = vi.fn()

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
      artifactKey: ARTIFACT,
      onChecking,
    })

    expect(onChecking).not.toHaveBeenCalled()
  })
})

describe('the artifact key is given, never guessed (#197)', () => {
  it('looks the published hash up by the key the caller states', async () => {
    // Not by the URL's last segment, which is what this used to do: the
    // first artifact whose URL did not read like its manifest key would have
    // found no entry, and "no entry" means the download proceeds unverified.
    withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedPublishedHash.mockResolvedValue(sha256Hex(bytes(1, 2, 3)))

    await downloadArchive(
      CORRIDOR_ARCHIVE_KEY,
      'https://cdn.example.org/signed/xyz?token=1',
      {
        artifactKey: 'background_z13.pmtiles',
      },
    )

    expect(mockedPublishedHash).toHaveBeenCalledWith('background_z13.pmtiles', {
      signal: undefined,
    })
  })
})

// The failure a hiker reported against the Fine tier: 1.18 GB transferred, then
// nothing saved (#544). Measured in real Chromium before any of this existed -
// the archive is stored in ONE `set()` at the very end, and the Blob being
// accumulated before that is not charged against the origin's quota, so the
// browser has no reason to refuse until the last byte has arrived. What it
// throws then is a QuotaExceededError with an EMPTY message, so the card
// rendered a blank alert over a button offering the same doomed download again.
//
// Nothing here branches on platform, and neither did the failure: Chrome on
// Android is where it was seen, and iOS Safari (where every browser is WebKit,
// the per-origin allowance is around a gigabyte and `persist()` is not
// implemented at all) reaches it sooner.
describe('when the phone has no room for the archive (#544)', () => {
  /** A quota rejection shaped like the platform's: no message at all. */
  function quotaError(): DOMException {
    return new DOMException('', 'QuotaExceededError')
  }

  function stubEstimate(quota: number, usage: number): void {
    vi.stubGlobal('navigator', {
      ...globalThis.navigator,
      storage: { estimate: () => Promise.resolve({ quota, usage }) },
    })
  }

  afterEach(() => {
    vi.unstubAllGlobals()
  })

  it('refuses before reading the body, so the data is never spent', async () => {
    const store = withStore()
    // 1.18 GB declared against 600 MB free - the reported case, in miniature.
    stubEstimate(1_000_000_000, 400_000_000)
    const fetchSpy = mockFetch({ chunks: [bytes(1, 2, 3)], totalBytes: 1_184_700_000 })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(ArchiveTooLargeError)

    expect(fetchSpy).toHaveBeenCalledTimes(1)
    // Nothing stored, nothing half-kept: the transfer never started.
    expect(storedArchive(store)).toBeUndefined()
    expect(heldPartial(store)).toBeUndefined()
  })

  it('says both numbers and the way out, in a hiker’s units', async () => {
    const error = new ArchiveTooLargeError(1_184_700_000, 400_000_000, 0)

    expect(error.message).toContain('1.18 GB')
    expect(error.message).toContain('400 MB')
    expect(error.message).toContain('none of your data was spent')
    expect(error.message).toContain('lighter detail level')
    expect(error.requiredBytes).toBe(1_184_700_000)
    expect(error.availableBytes).toBe(400_000_000)
  })

  it('asks a resume for the remainder only, not for a second copy (#553)', async () => {
    // This used to require 9 for a 6-byte archive with 3 bytes already held:
    // the finished bytes were stored under the package key BEFORE the partial
    // was discarded, so both existed at once. Segments retire that - the held
    // bytes ARE part of the finished archive and completion is a marker - so a
    // resume asks only for what is not yet on disk.
    const store = withStore({
      ...partialOf(new Blob([bytes(1, 2, 3)])),
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    stubEstimate(100, 92) // 8 free: not enough for two copies, plenty for 3 more
    mockFetch({ chunks: [bytes(4, 5, 6)], status: 206, totalBytes: 3 })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(new Uint8Array(await (storedArchive(store) as Blob).arrayBuffer())).toEqual(
      bytes(1, 2, 3, 4, 5, 6),
    )
  })

  it('still refuses a resume whose remainder does not fit', async () => {
    withStore({
      ...partialOf(new Blob([bytes(1, 2, 3)])),
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    stubEstimate(100, 98) // 2 free, and 3 more bytes are coming
    mockFetch({ chunks: [bytes(4, 5, 6)], status: 206, totalBytes: 3 })

    const thrown = await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
      artifactKey: ARTIFACT,
    }).catch((error: unknown) => error)

    expect(thrown).toBeInstanceOf(ArchiveTooLargeError)
    expect((thrown as ArchiveTooLargeError).requiredBytes).toBe(3)
    // The sentence has to explain which figure is which, or being refused over
    // 3 bytes on a 6-byte map reads as nonsense.
    expect((thrown as Error).message).toContain('The rest of it')
  })

  it('goes ahead when the room is there', async () => {
    const store = withStore()
    stubEstimate(1_000_000_000, 0)
    mockFetch({ chunks: [bytes(1, 2, 3)] })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(storedArchive(store)).toBeInstanceOf(Blob)
  })

  it('refuses nothing when the browser will not say how much room there is', async () => {
    // No Storage API at all - old WebKit, and jsdom. Best-effort answers do not
    // become refusals here, the same way they do not anywhere in storageHealth.
    const store = withStore()
    vi.stubGlobal('navigator', { ...globalThis.navigator, storage: undefined })
    mockFetch({ chunks: [bytes(1, 2, 3)], totalBytes: 3 })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(storedArchive(store)).toBeInstanceOf(Blob)
  })

  it('turns a quota refusal at the store into the same explained failure', async () => {
    // The estimate is an estimate: a browser that rounds it generously, or a
    // second tab that filled the origin meanwhile, still lands on the store -
    // and an empty-message DOMException must not be what the hiker is shown.
    withStore()
    stubEstimate(1_000_000_000, 0)
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedSet.mockRejectedValueOnce(quotaError())

    const thrown = await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
      artifactKey: ARTIFACT,
    }).catch((error: unknown) => error)

    expect(thrown).toBeInstanceOf(ArchiveTooLargeError)
    expect((thrown as Error).message).toContain('not enough room')
  })

  it('leaves a real failure at the store alone rather than blaming space', async () => {
    withStore()
    mockFetch({ chunks: [bytes(1, 2, 3)] })
    mockedSet.mockRejectedValueOnce(new Error('the database is corrupt'))

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow('the database is corrupt')
  })

  it('reports the transfer’s own failure even when the partial cannot be kept', async () => {
    // Quota is exactly the situation that produces a partial, so the write that
    // keeps it can fail too - and its empty-message error must not replace the
    // dropped connection the hiker actually needs to hear about.
    withStore()
    vi.spyOn(globalThis, 'fetch').mockImplementation(async () => {
      const body = new ReadableStream<Uint8Array>({
        start(controller) {
          controller.enqueue(bytes(1, 2, 3))
          controller.error(new Error('the connection dropped'))
        },
      })
      return new Response(body, { status: 200, headers: new Headers() })
    })
    mockedSet.mockRejectedValue(quotaError())

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow('the connection dropped')
  })
})

// A partial that holds the whole object was a permanent dead end (#544): every
// resume asked for `bytes=<size>-`, every answer was 416, and the card offered
// Resume forever over bytes that could never complete. Reachable three ways -
// a drop after the last byte but before the stream closed, an abort at the
// tail, or a body that ran longer than the declared length.
describe('a resume the server answers 416 to (#544)', () => {
  const WHOLE = bytes(1, 2, 3, 4)

  it('finishes from the held bytes when they are the whole object', async () => {
    const store = withStore({
      ...partialOf(new Blob([WHOLE])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 4, totalBytes: 4 },
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    mockedPublishedHash.mockResolvedValue(sha256Hex(WHOLE))
    mockFetch({ chunks: [], status: 416, contentRange: 'bytes */4' })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    const stored = storedArchive(store) as Blob
    expect(new Uint8Array(await stored.arrayBuffer())).toEqual(WHOLE)
    expect(heldPartial(store)).toBeUndefined()
    expect(await readArchiveVersion(CORRIDOR_ARCHIVE_KEY)).toBe(sha256Hex(WHOLE))
  })

  it('reports progress as complete rather than leaving the bar where it stopped', async () => {
    withStore({
      ...partialOf(new Blob([WHOLE])),
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    mockFetch({ chunks: [], status: 416, contentRange: 'bytes */4' })
    const onProgress = vi.fn()

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
      artifactKey: ARTIFACT,
      onProgress,
    })

    expect(onProgress).toHaveBeenLastCalledWith({ receivedBytes: 4, totalBytes: 4 })
  })

  it('keeps nothing when the held bytes are not the published archive', async () => {
    // The length is right and the content is wrong, which is the one case where
    // resuming onto what is held could only rebuild the same wrong file.
    const store = withStore({
      ...partialOf(new Blob([WHOLE])),
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    mockedPublishedHash.mockResolvedValue(sha256Hex(bytes(9, 9, 9, 9)))
    mockFetch({ chunks: [], status: 416, contentRange: 'bytes */4' })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow(ArchiveHashMismatchError)

    expect(storedArchive(store)).toBeUndefined()
    expect(heldPartial(store)).toBeUndefined()
  })

  it('clears a partial longer than the object, so the next attempt is not stuck', async () => {
    const store = withStore({
      ...partialOf(new Blob([WHOLE])),
      [ARCHIVE_PROGRESS_KEY]: { receivedBytes: 4, totalBytes: 4 },
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    mockFetch({ chunks: [], status: 416, contentRange: 'bytes */3' })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow('starts a fresh copy')

    expect(heldPartial(store)).toBeUndefined()
    expect(store[ARCHIVE_PROGRESS_KEY]).toBeUndefined()
    expect(store[ARCHIVE_SOURCE_KEY]).toBeUndefined()
  })

  it('clears a partial the server states no length for', async () => {
    const store = withStore({
      ...partialOf(new Blob([WHOLE])),
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    mockFetch({ chunks: [], status: 416 })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow('starts a fresh copy')

    expect(heldPartial(store)).toBeUndefined()
  })

  it('still fails plainly on a 416 with nothing held', async () => {
    // Nothing was asked for by range, so this is the server being odd rather
    // than a resume to rescue: the generic message is the honest one.
    withStore()
    mockFetch({ chunks: [], status: 416, contentRange: 'bytes */4' })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT }),
    ).rejects.toThrow('it answered 416')
  })
})

describe('the room needed is what is not yet on disk (#544, narrowed by #553)', () => {
  function stubEstimate(quota: number, usage: number): void {
    vi.stubGlobal('navigator', {
      ...globalThis.navigator,
      storage: { estimate: () => Promise.resolve({ quota, usage }) },
    })
  }

  afterEach(() => {
    vi.unstubAllGlobals()
  })

  it('reclaims a partial the server ignored the range for, before writing over it', async () => {
    // 200 in reply to a Range request means the whole file is coming and the
    // archive is rebuilt from zero. Those held segments are then in the way
    // rather than useful - left in place they would be read back as part of the
    // archive - so they go before the first new byte is written, and the room
    // they occupied is not counted against the transfer that replaces them.
    const store = withStore({
      ...partialOf(new Blob([bytes(1, 2, 3)])),
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    stubEstimate(100, 92) // 8 free, and the whole 6-byte archive is coming
    mockFetch({ chunks: [bytes(1, 2, 3, 4, 5, 6)], status: 200, totalBytes: 6 })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(new Uint8Array(await (storedArchive(store) as Blob).arrayBuffer())).toEqual(
      bytes(1, 2, 3, 4, 5, 6),
    )
    expect(heldPartial(store)).toBeUndefined()
  })

  it('counts nothing extra once an unusable partial has been discarded', async () => {
    // A partial from a different URL is dropped before a byte is requested, so
    // its bytes are not in the way of anything.
    const store = withStore({
      ...partialOf(new Blob([bytes(1, 2, 3)])),
      [ARCHIVE_SOURCE_KEY]: { url: 'https://cdn.example.org/other.pmtiles' },
    })
    stubEstimate(100, 92) // 8 free, and the archive is 6
    mockFetch({ chunks: [bytes(1, 2, 3, 4, 5, 6)], totalBytes: 6 })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    expect(storedArchive(store)).toBeInstanceOf(Blob)
  })
})

// The defect #553 exists for: during a HEALTHY transfer nothing reached the
// disk, because `persistPartial` was called from two error paths and nowhere
// else. An app the OS kills throws no error, so no error path runs - and on
// Android a backgrounded tab holding a gigabyte is exactly what gets killed.
// The whole transfer was lost and the next launch started from zero.
//
// `segmentBytes` is passed throughout so the checkpointing is really exercised.
// At the production 32 MiB every test here would flush once at the end and pass
// whether the segment loop worked or not.
describe('bytes reach the disk as they arrive (#553)', () => {
  /** Every Blob byte the store holds, however many records it is spread over. */
  function storedBytes(store: Record<string, unknown>): number {
    return Object.values(store).reduce<number>(
      (total, value) => total + (value instanceof Blob ? value.size : 0),
      0,
    )
  }

  it('has the bytes on disk before the transfer ends', async () => {
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3, 4), bytes(5, 6, 7, 8), bytes(9, 10, 11, 12)] })

    // What a resume would find at each progress report - i.e. what would
    // survive the app being killed at that instant. Every entry was 0 before
    // this change, for the whole transfer.
    const onDiskAt: number[] = []

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
      artifactKey: ARTIFACT,
      segmentBytes: 4,
      onProgress: () => {
        onDiskAt.push(heldPartial(store)?.size ?? 0)
      },
    })

    // Four reports: one before the first byte, then one per chunk. Each is
    // taken before that chunk's checkpoint, so the figure trails one segment
    // behind - nothing yet at 4 bytes received, one segment down by 8, two by
    // 12. Before this change every entry was 0, for the whole transfer.
    expect(onDiskAt).toEqual([0, 0, 4, 8])
  })

  it('stores the archive exactly once, in segments', async () => {
    // The measured reason for append-only (#553): re-writing the accumulated
    // Blob at every checkpoint is quadratic in bytes written - ~21 GB of writes
    // to get 1.18 GB onto phone flash - and copying the finished segments into
    // one record would need room for two copies of the archive at the size
    // where that fails (#544).
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3, 4), bytes(5, 6, 7, 8), bytes(9, 10, 11, 12)] })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
      artifactKey: ARTIFACT,
      segmentBytes: 4,
    })

    expect(storedBytes(store)).toBe(12)
    expect(segmentsIn(store, 0).map((part) => part.size)).toEqual([4, 4, 4])
    // Completion is the marker, not a whole-archive write. `priorSegments: 0`
    // because a first download replaced nothing - the field exists so a later
    // delete can sweep a replaced generation to a known floor (#648).
    expect(store[`${CORRIDOR_ARCHIVE_KEY}:complete`]).toEqual({
      generation: 0,
      segments: 3,
      totalBytes: 12,
      priorSegments: 0,
    })
    expect(store[CORRIDOR_ARCHIVE_KEY]).toBeUndefined()
    expect(new Uint8Array(await (storedArchive(store) as Blob).arrayBuffer())).toEqual(
      bytes(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12),
    )
  })

  it('records the progress that is on disk, not the bytes still in memory', async () => {
    // What the Downloads screen offers to resume from. Claiming the in-memory
    // figure would promise bytes a kill takes with it, and the next attempt
    // would ask the server for a range starting past what it actually holds.
    const store = withStore()
    mockFetch({
      chunks: [bytes(1, 2, 3, 4), bytes(5, 6, 7, 8), bytes(9)],
      totalBytes: 99,
    })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
        artifactKey: ARTIFACT,
        segmentBytes: 4,
      }),
    ).rejects.toThrow(ArchiveSizeMismatchError)

    // Nine bytes arrived and all nine were checkpointed - the tail flush on the
    // way out is what makes the last partial segment resumable too.
    expect(store[ARCHIVE_PROGRESS_KEY]).toEqual({ receivedBytes: 9, totalBytes: 99 })
    expect(heldPartial(store)?.size).toBe(9)
  })

  it('resumes from the segments a killed transfer left behind', async () => {
    // The acceptance criterion: a transfer that died part-way carries on from
    // what arrived rather than from zero. The store is what the first attempt
    // left; nothing else about it is arranged.
    const first = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3, 4), bytes(5, 6, 7, 8)], totalBytes: 12 })

    await expect(
      downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
        artifactKey: ARTIFACT,
        segmentBytes: 4,
      }),
    ).rejects.toThrow(ArchiveSizeMismatchError)

    const store = withStore(first)
    const fetchSpy = mockFetch({
      chunks: [bytes(9, 10, 11, 12)],
      status: 206,
      totalBytes: 4,
    })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
      artifactKey: ARTIFACT,
      segmentBytes: 4,
    })

    // Asked for the rest, not the whole file. `lastCall` rather than the first:
    // re-spying an already-spied fetch keeps the earlier attempt's calls.
    expect(fetchSpy.mock.lastCall?.[1]).toMatchObject({
      headers: { Range: 'bytes=8-' },
    })
    expect(new Uint8Array(await (storedArchive(store) as Blob).arrayBuffer())).toEqual(
      bytes(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12),
    )
    expect(storedBytes(store)).toBe(12)
  })

  it('turns a quota refusal at a checkpoint into the explained failure', async () => {
    // Bytes are charged against the quota as they arrive now, so this lands
    // mid-transfer rather than after the last byte. What a browser throws here
    // carries no message at all (#544), and the card would show an empty alert.
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3, 4), bytes(5, 6, 7, 8)] })
    // Room enough to start - the pre-flight check is against an ESTIMATE, and
    // the store disagreeing with it partway is the case this branch is for.
    vi.stubGlobal('navigator', {
      ...globalThis.navigator,
      storage: { estimate: () => Promise.resolve({ quota: 100, usage: 92 }) },
    })
    // Segment writes fail, everything else works. Targeted by key rather than
    // by call order: `mockImplementationOnce` queues survive `clearAllMocks`, so
    // an unconsumed one leaks into whatever test runs next.
    mockedSet.mockImplementation(async (key, value) => {
      if (String(key).includes(':g0:')) {
        const error = new Error('') as Error & { name: string }
        error.name = 'QuotaExceededError'
        throw error
      }
      store[key as string] = value
    })

    const thrown = await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
      artifactKey: ARTIFACT,
      segmentBytes: 4,
    }).catch((error: unknown) => error)

    expect(thrown).toBeInstanceOf(ArchiveTooLargeError)
    expect((thrown as Error).message).toContain('not enough room')
    // Nothing half-written claims to be a map.
    expect(storedArchive(store)).toBeUndefined()
    vi.unstubAllGlobals()
  })

  it('reclaims every segment when the hiker deletes the map', async () => {
    // Someone deleting a 1.18 GB map to free room must not be left holding most
    // of it in records the delete path never looked for (#554).
    const store = withStore()
    mockFetch({ chunks: [bytes(1, 2, 3, 4), bytes(5, 6, 7, 8), bytes(9, 10, 11, 12)] })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, {
      artifactKey: ARTIFACT,
      segmentBytes: 4,
    })
    expect(storedBytes(store)).toBe(12)

    await deleteArchive(CORRIDOR_ARCHIVE_KEY)

    expect(storedBytes(store)).toBe(0)
    expect(storedArchive(store)).toBeUndefined()
  })
})

// The compatibility this change is held to. lib/packages.ts kept the corridor
// key so "an archive already in a tester's IndexedDB stays readable after this
// change, rather than silently re-downloading", and that promise outlives the
// layout it was written about.
describe('archives stored by the pre-segment build (#553)', () => {
  it('serves a whole-archive record as the archive it is', async () => {
    const whole = new Blob(['a map downloaded by the old build'])
    withStore({ [CORRIDOR_ARCHIVE_KEY]: whole })

    const { readArchive } = await import('./archiveStore')

    expect(await readArchive(CORRIDOR_ARCHIVE_KEY)).toBe(whole)
  })

  it('discards a pre-segment partial rather than resuming onto it', async () => {
    // Its bytes are one record with no generation and no segment index. Copying
    // them into segment 0 would need room for a second copy of a partial that
    // can be most of a gigabyte, and keeping the record as a permanent base
    // part would leave finished archives containing a ':partial' for good. So
    // the transfer restarts, and the record's space goes back.
    const store = withStore({
      [ARCHIVE_PARTIAL_KEY]: new Blob([bytes(1, 2, 3)]),
      [ARCHIVE_SOURCE_KEY]: { url: URL_ },
    })
    const fetchSpy = mockFetch({ chunks: [bytes(1, 2, 3, 4, 5, 6)] })

    await downloadArchive(CORRIDOR_ARCHIVE_KEY, URL_, { artifactKey: ARTIFACT })

    // No Range header: this is a fresh transfer, not a resume.
    expect(fetchSpy.mock.calls[0]?.[1]).toMatchObject({ headers: undefined })
    expect(store[ARCHIVE_PARTIAL_KEY]).toBeUndefined()
    expect(new Uint8Array(await (storedArchive(store) as Blob).arrayBuffer())).toEqual(
      bytes(1, 2, 3, 4, 5, 6),
    )
  })
})