# Upgrade Guide — vNEXT

<!-- assembled-by: assemble-next-md -->
<!-- bump: patch -->

## What Changed

Closed the remaining way a live data-comparison check could silently stall. The
previous fix made sure every comparison's outcome gets logged — but only once
the underlying download finishes. If the remote data source stalled mid-download
and never answered, the comparison hung forever with no outcome at all. Each
piece of the download now has its own time limit (90 seconds per page, 10
minutes overall), so a stalled download fails cleanly with a clear log line
instead of hanging.

## What to Tell Your User

Nothing changes day to day. If your agent runs live data comparisons for a
migration, a stalled remote server now produces a clear "timed out" failure in
the logs within minutes instead of a comparison that never finishes.

## Summary of New Capabilities

- Live parity-comparison downloads abort cleanly when the remote source stalls
  (90s per page, 10 minutes total), with the failure logged and classified.
- Operators can tune both limits in config
  (`feedbackMigration.paritySource.pageTimeoutMs` / `.totalTimeoutMs`).
- Maturity: stable; defaults preserve existing behavior for healthy sources.

## Evidence

Reproduced live on echo's production server (2026-06-05): a parity comparison
triggered at 09:11:57Z never produced an outcome — no log line, nothing
recorded — for 19+ minutes, while the remote endpoint's auth wall answered in
0.2s (the stall was inside the authenticated data download, which had no
timeout). After: with the new per-page abort budgets, the same stall aborts as
a classified 504 within the 90-second page limit and the failure is logged by
the always-logged-outcome path shipped in the previous fix. Unit tests
additionally prove the abort fires, the page number is named, the total budget
refuses the next page, and non-timeout errors pass through unmasked.
