[Bug] Migration keeper reports MigrationCooldownNotMet as a failure for the full ~1-day timelock

[collinsezedike]

Summary

#557 lengthened migrate_adapter's MIN_LEDGER_GAP cooldown from ~1 minute to ~1 day. The migration keeper (packages/stellar-sdk-helpers/src/migration-keeper.ts) does not special-case the resulting MigrationCooldownNotMet rejection: it falls into the generic failure path, gets pushed to failures[], and api/v1/keepers/rebalance.ts returns HTTP 500 whenever failures.length > 0.

Motivation

While the cooldown was ~1 minute, a single MigrationCooldownNotMet failure on the run immediately after begin_migration was harmless noise, gone by the next hourly run. With the cooldown now ~1 day, every hourly run during that window hits the same rejection, producing roughly 24 consecutive HTTP 500s and failure log entries per migration. This creates sustained false-positive paging/monitoring noise during exactly the window #557 intends observers to calmly watch for a genuinely malicious begin_migration call, undermining that goal.

Proposed Solution

Special-case MigrationCooldownNotMet the same way isStaleAdapterError already is: detect it (the raw simulation error surfaces as Error(Contract, #20), matching MigrationCooldownNotMet = 20 in packages/contracts/vault/src/errors.rs) and report it as a skipped outcome with an informative reason, not a failures entry, so the keeper's HTTP status and logs correctly reflect "cooldown in progress, working as intended" rather than "something is wrong."

Scope

Field	Value
Area	SDK / API
Protocol affected	None
Network	Both
Breaking change?	No

Acceptance Criteria

• MigrationCooldownNotMet is detected and reported as skipped, not failures
• apps/docs/operations/migration-keeper.md updated to reflect the fixed behavior
• Test coverage for the cooldown-in-progress case reporting a skip, not a failure

Additional Context

Identified during review of #710. Not fixed there since it is a keeper/monitoring-quality issue, not a fund-safety one, and deserves its own dedicated fix and tests rather than being folded into a contract-focused PR.

[xtep103]

Hey Maintainer, I have gone through the details of the issue and i am capable of resolving it, I would love to be assigned to work on it ASAP. Thanks in advance

[JohnArayaE]

I would like to work on this issue because the migration keeper currently treats an expected cooldown condition as an operational failure, which can generate repeated HTTP 500 responses and monitoring noise for the entire ~1-day timelock introduced by #557. I can add a dedicated MigrationCooldownNotMet detector alongside the existing stale-adapter handling, map Error(Contract, #20) to a skipped result with a clear cooldown-in-progress reason, and ensure it no longer contributes to failures[] or false-positive keeper failures. I can also add focused test coverage for this path and update apps/docs/operations/migration-keeper.md so the documented keeper behavior matches the implementation.

[JohnArayaE]

I would like to work on this issue because the migration keeper currently treats an expected cooldown condition as an operational failure, which can generate repeated HTTP 500 responses and monitoring noise for the entire ~1-day timelock introduced by #557. I can add a dedicated MigrationCooldownNotMet detector alongside the existing stale-adapter handling, map Error(Contract, #20) to a skipped result with a clear cooldown-in-progress reason, and ensure it no longer contributes to failures[] or false-positive keeper failures. I can also add focused test coverage for this path and update apps/docs/operations/migration-keeper.md so the documented keeper behavior matches the implementation.

[Ranjeet2063]

Hi everyone,

I can tackle [Bug] Migration keeper reports MigrationCooldownNotMet as a failure for the full ~1-day timelock. Proposed implementation roadmap:

• Analysis: Inspect current behavior and edge cases in drydocs/meridian
• Implementation: Trace the regression in drydocs/meridian causing [Bug] Migration keeper reports MigrationCooldownNotMet as a failure for the full ~1-day timelock and implement a targeted, minimal patch.
• Testing: Add a reproduction test case to ensure this regression never reoccurs.
• PR: Atomic commit with clean git hygiene and passing CI

Looking forward to contributing—please feel free to assign!

[Iker2522]

I'd like to take this issue on!
​I can refactor packages/stellar-sdk-helpers/src/migration-keeper.ts to special-case the MigrationCooldownNotMet error during migration simulation.
​I will update the keeper to detect Soroban Error(Contract, #20) (matching MigrationCooldownNotMet = 20 in packages/contracts/vault/src/errors.rs) and process it as a benign skipped outcome rather than appending it to failures[]. This eliminates the false-positive HTTP 500 responses on api/v1/keepers/rebalance.ts and stops paging noise during the 24-hour cooldown window.
​I will also update apps/docs/operations/migration-keeper.md and write tests verifying that a cooldown rejection returns a skipped status without triggering failure alerts. All builds and tests will pass cleanly. PR ready in 1 day.

[grantfox-oss]

🦊 GrantFox — @Iker2522 has been assigned to this issue!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #725)
2. Your PR will be reviewed by the drydocs maintainers

Good luck! Track your progress on GrantFox.

[collinsezedike]

@Iker2522 Assigned, thank you for the detailed proposal.

@xtep103 @JohnArayaE @Ranjeet2063 Thank you for the interest. This one is taken for now, please feel free to pick up another open issue.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@Iker2522's PR #737 was approved and merged by @collinsezedike.

🏆 @Iker2522: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (223 total points). Track your full progress on GrantFox.

👏 Great work, @Iker2522! Keep contributing to drydocs.