Check a Motoko stable-state change before upgrading
A release can preserve its public Candid methods while changing stored values incompatibly. Motoko's stable signature describes the persistence side of an upgrade.
Compare storage separately from the API
Consider a service that originally stored an invoice amount as Nat and now wants formatted text. Existing invoice 17 contains the number 450. Inspect the old and new stable signatures with the compiler's compatibility tooling before attempting an upgrade. A simple type edit does not define how 450 should become text.
v1 stable state: invoices : [(Nat, Nat)]
proposed: invoices : [(Nat, Text)]
fixture: [(17, 450)]
Rehearse the conversion
Specify a migration supported by the chosen Motoko persistence mode, including rounding and formatting rules. Upgrade a populated test canister and verify old invoices and new writes. A type-compatible migration can still produce a semantically wrong amount if its unit conversion is incorrect.