test(migrate): verify canonical SQL-only version ordering

migrate/migrate.go

@@ -23,8 +23,9 @@ import (
 // affinity (transaction-pooling proxies cannot safely hold session locks).
 //
 // Use the returned Provider's Up, UpTo, DownTo, Status, GetDBVersion, GetVersions,
-// and HasPending methods directly. Versions may be sequential or timestamps;
-// Goose orders and tracks them. Global Go migration registration is ignored.
+// and HasPending methods directly. Filenames must sort lexically in numeric
+// version order: use zero-padded sequential or fixed-width timestamp prefixes,
+// as produced by Goose's migration creator. Global Go registration is ignored.
 func New(db *sql.DB, dialect goose.Dialect, files embed.FS, dir string, logger *slog.Logger, migrations ...*goose.Migration) (*goose.Provider, error) {
 	for i, migration := range migrations {
 		if migration == nil {