chore(keyring-sdk): fix review issues in migration module

- Remove broken {@link defineMigrations} reference from JSDoc
- Add test: version-0 versioned state triggers all migrations
- Add test: default JsonStruct validation fires without inputSchema
- Fix serialize() example to use VersionedState<HdStateV2> return type
- Add `as const` guidance to Best Practices in migrations.md

Author: danroc

packages/keyring-sdk/docs/migrations.md

@@ -81,6 +81,7 @@ const migrations = [
 
 ```typescript
 import { applyMigrations, getLatestVersion } from '@metamask/keyring-sdk';
+import type { VersionedState } from '@metamask/keyring-sdk';
 import type { Json } from '@metamask/utils';
 
 class MyKeyring {
@@ -93,21 +94,22 @@ class MyKeyring {
     this.#hdPath = data.hdPath;
   }
 
-  async serialize(): Promise<Json> {
+  async serialize(): Promise<VersionedState<HdStateV2>> {
     return {
       version: getLatestVersion(migrations),
       data: {
         mnemonic: this.#mnemonic,
         accountCount: this.#accountCount,
         hdPath: this.#hdPath,
       },
-    } as Json;
+    };
   }
 }
 ```
 
 ## Best Practices
 
+- **`as const` arrays**: Declare the migrations array with `as const` so TypeScript infers the final state type from `applyMigrations`. Without it, `data` falls back to `Json`.
 - **Idempotent migrations**: Design migrations so re-running them on already-migrated data is harmless.
 - **Immutability**: Treat the input `data` as immutable within the `migrate` function.
 - **Schema coverage**: Ensure `schema` covers all fields expected in the new version to prevent runtime errors.

packages/keyring-sdk/src/migration.test.ts

@@ -157,6 +157,22 @@ describe('defineMigration', () => {
 
       expect(migrateFn).not.toHaveBeenCalled();
     });
+
+    it('validates input as JSON even when inputSchema is omitted', async () => {
+      const migrateFn = jest.fn();
+      const migrations = [
+        defineMigration({ version: 1, migrate: migrateFn }),
+      ] as const;
+
+      // undefined is not valid JSON
+      await expect(
+        applyMigrations(undefined as unknown as Json, migrations),
+      ).rejects.toThrow(
+        'Expected a value of type `JSON`, but received: `undefined`',
+      );
+
+      expect(migrateFn).not.toHaveBeenCalled();
+    });
   });
 });
 
@@ -336,6 +352,33 @@ describe('applyMigrations', () => {
         migrated: true,
       });
     });
+
+    it('treats explicitly versioned state at version 0 as unversioned', async () => {
+      const migrations = [
+        defineMigration<HdStateV1>({
+          version: 1,
+          migrate: (state) => {
+            const prev = state as UnversionedHdState;
+            return { ...prev, newField: 'added' };
+          },
+        }),
+      ] as const;
+
+      const result = await applyMigrations(
+        { version: 0, data: { oldField: 'value', existing: true } },
+        migrations,
+      );
+
+      expect(result).toStrictEqual({
+        version: 1,
+        data: {
+          oldField: 'value',
+          existing: true,
+          newField: 'added',
+        } satisfies HdStateV1,
+        migrated: true,
+      });
+    });
   });
 
   describe('when migrate is async', () => {

packages/keyring-sdk/src/migration.ts

@@ -69,8 +69,8 @@ export type KeyringMigration<
  * called, and the `Input` type parameter is inferred so `migrate` receives a typed
  * argument with no manual cast needed.
  *
- * Returns `KeyringMigration<Output>` so that {@link defineMigrations} and
- * {@link applyMigrations} can infer the output type.
+ * Returns `KeyringMigration<Output>` so that {@link applyMigrations} can infer the
+ * output type.
  *
  * @param config - The migration configuration.
  * @param config.version - The version this migration produces.