Migration keeper can starve a completable migration under alternating candidate rates

[collinsezedike]

Summary

The migration keeper (packages/stellar-sdk-helpers/src/migration-keeper.ts) re-derives the best rate candidate from scratch on every run, with no memory of an already-begun migration. If the top candidate flips between two adapters across consecutive scheduled runs, each run overwrites the prior begin_migration snapshot and resets the ledger-gap cooldown, so a migration can in principle never reach migrate_adapter despite a real, sustained improvement opportunity existing throughout.

Reproduction

1. Run 1: candidate A clears minImprovementBps over the current adapter's rate. Keeper calls begin_migration(A), snapshotting A.
2. Before run 2 (an hour later on the documented schedule), rates shift so candidate B is now best.
3. Run 2 reads get_migration_snapshot(), sees adapter = A != best.adapterId = B, and calls begin_migration(B), overwriting A's snapshot and resetting the cooldown.
4. If rates keep alternating between A and B across runs, no single candidate's snapshot survives long enough to reach MIN_LEDGER_GAP with a matching "best" on a later run.

Impact

Not a fund-safety issue: the vault's position is never at risk, and the contract-side stability/slippage checks in migrate_adapter still hold. The impact is purely a liveness gap: an automated migration that should happen never does, so the vault keeps earning at the old adapter's rate.

Proposed fix

Before re-deriving "best" each run, check whether an active begin_migration snapshot already exists for this vault. If it does and that snapshot's adapter still clears minImprovementBps against the current rate, prefer completing it over switching to a fresher "best" candidate. Only let the snapshot lapse (and pick a new candidate) once the snapshotted adapter's rate genuinely stops clearing the threshold.

Scope

Field	Value
Area	SDK (migration keeper)
Protocol affected	None
Network	Both
Breaking change?	No

Additional Context

Found during review of #606 (two-phase migration with ledger-gap stability check). Deferred rather than folded into that PR to keep its scope to the security fix it was already carrying.

[Webghost01-NG]

Hi, I’d like to work on this issue. I understand the liveness problem caused by alternating best-rate candidates resetting the existing migration snapshot and cooldown. I’ll first inspect the migration keeper and related tests, then implement a minimal fix that preserves a qualifying active snapshot and only replaces it when it no longer meets minImprovementBps. I’ll add/extend tests for candidate flipping and verify the existing migration flow remains unchanged.

[xtep103]

Hi there, I’ve carefully reviewed the issue details and I’m confident I can provide a clean, efficient, and maintainable solution.

[telemarkdigital-publisher]

/try

I can take this on. I inspected packages/stellar-sdk-helpers/src/migration-keeper.ts and the nearby migration-keeper tests, and this looks like a focused liveness fix.

Plan:

• Preserve an active migration snapshot when the snapshotted adapter still clears minImprovementBps against the current adapter.
• Prefer completing the existing snapshot after cooldown instead of replacing it just because another candidate is temporarily best.
• Only start a new begin_migration when the existing snapshot no longer meets the threshold or is absent.
• Add/extend Vitest coverage for alternating candidate rates so the keeper does not keep resetting the cooldown.

Out of scope: protocol or contract behavior changes, unrelated keeper retry/lease refactors, and changes to migration economics.

Expected verification before PR: pnpm --filter @meridian/stellar-sdk-helpers test and pnpm --filter @meridian/stellar-sdk-helpers typecheck, plus pnpm test if the full workspace dependency install permits it.

[Stealth-cloud-droid]

hi maintainer i'll like to work on this issue and submit pr within 24hous

[aojomo]

Hi maintainer, Please I would like to work on this issue

[ZacLou]

Opened PR #705 with the fix and tests.

Approach: Before falling through to begin_migration for the freshly-derived best candidate, the keeper now checks whether an active migration snapshot already exists for a different adapter. If that adapter's rate still clears minImprovementBps against the current rate, best is overridden to the snapshotted adapter so the existing migrate_adapter path completes it instead of resetting the cooldown. Only when the snapshotted adapter's rate genuinely stops clearing the threshold does the keeper pick a new candidate.

Two test cases cover both halves: preservation when the snapshot still qualifies, and replacement when it has genuinely decayed. All 54 tests pass.

[devkryssie]

hi maintainer i'll like to work on this issue and submit pr within 24hours