@platforma-sdk/model 1.58.5 → 1.58.11

package/src/block_model.ts

@@ -12,6 +12,7 @@ import type { PlatformaV3 } from "./platforma";
 import type { InferRenderFunctionReturn, RenderFunction } from "./render";
 import { BlockRenderCtx, PluginRenderCtx } from "./render";
 import type { PluginData, PluginModel, PluginOutputs, PluginParams } from "./plugin_model";
+import { PluginInstance as PluginInstanceClass, CREATE_PLUGIN_MODEL } from "./plugin_model";
 import { type PluginHandle, pluginOutputKey } from "./plugin_handle";
 import type { RenderCtxBase } from "./render";
 import { PlatformaSDKVersion } from "./version";
@@ -79,10 +80,10 @@ function mergeFeatureFlags(
 }
 
 /**
- * Registered plugin: model + param derivation lambdas.
+ * Plugin record: model + param derivation lambdas.
  * Type parameters are carried by PluginModel generic.
  */
-export type PluginInstance<
+export type PluginRecord<
   Data extends PluginData = PluginData,
   Params extends PluginParams = undefined,
   Outputs extends PluginOutputs = PluginOutputs,
@@ -94,10 +95,11 @@ export type PluginInstance<
 interface BlockModelV3Config<
   OutputsCfg extends Record<string, ConfigRenderLambda>,
   Data,
-  Plugins extends Record<string, PluginInstance> = {},
+  Plugins extends Record<string, PluginRecord> = {},
+  Transfers extends Record<string, unknown> = {},
 > {
   renderingMode: BlockRenderingMode;
-  dataModel: DataModel<Data>;
+  dataModel: DataModel<Data, Transfers>;
   outputs: OutputsCfg;
   sections: ConfigRenderLambda;
   title: ConfigRenderLambda | undefined;
@@ -119,9 +121,12 @@ export class BlockModelV3<
   OutputsCfg extends Record<string, ConfigRenderLambda>,
   Data extends Record<string, unknown> = Record<string, unknown>,
   Href extends `/${string}` = "/",
-  Plugins extends Record<string, PluginInstance> = {},
+  Plugins extends Record<string, PluginRecord> = {},
+  Transfers extends Record<string, unknown> = {},
 > {
-  private constructor(private readonly config: BlockModelV3Config<OutputsCfg, Data, Plugins>) {}
+  private constructor(
+    private readonly config: BlockModelV3Config<OutputsCfg, Data, Plugins, Transfers>,
+  ) {}
 
   public static readonly INITIAL_BLOCK_FEATURE_FLAGS: BlockCodeKnownFeatureFlags = {
     supportsLazyState: true,
@@ -145,10 +150,11 @@ export class BlockModelV3<
    *
    * @param dataModel The data model that defines initial data and migrations
    */
-  public static create<Data extends Record<string, unknown>>(
-    dataModel: DataModel<Data>,
-  ): BlockModelV3<NoOb, {}, Data> {
-    return new BlockModelV3<NoOb, {}, Data>({
+  public static create<
+    Data extends Record<string, unknown>,
+    Transfers extends Record<string, unknown> = {},
+  >(dataModel: DataModel<Data, Transfers>): BlockModelV3<NoOb, {}, Data, "/", {}, Transfers> {
+    return new BlockModelV3<NoOb, {}, Data, "/", {}, Transfers>({
       renderingMode: "Heavy",
       dataModel,
       outputs: {},
@@ -185,7 +191,8 @@ export class BlockModelV3<
     },
     Data,
     Href,
-    Plugins
+    Plugins,
+    Transfers
   >;
   /**
    * Add output cell to the configuration
@@ -206,13 +213,14 @@ export class BlockModelV3<
     },
     Data,
     Href,
-    Plugins
+    Plugins,
+    Transfers
   >;
   public output(
     key: string,
     cfgOrRf: RenderFunction<Args, Data, unknown>,
     flags: ConfigRenderLambdaFlags = {},
-  ): BlockModelV3<Args, OutputsCfg, Data, Href, Plugins> {
+  ): BlockModelV3<Args, OutputsCfg, Data, Href, Plugins, Transfers> {
     return new BlockModelV3({
       ...this.config,
       outputs: {
@@ -240,7 +248,8 @@ export class BlockModelV3<
     },
     Data,
     Href,
-    Plugins
+    Plugins,
+    Transfers
   > {
     return this.output(key, rf, { retentive: true });
   }
@@ -266,10 +275,10 @@ export class BlockModelV3<
    *   return { numbers: data.numbers };
    * })
    */
-  public args<Args>(
-    lambda: (data: Data) => Args,
-  ): BlockModelV3<Args, OutputsCfg, Data, Href, Plugins> {
-    return new BlockModelV3<Args, OutputsCfg, Data, Href, Plugins>({
+  public args<A>(
+    lambda: (data: Data) => A,
+  ): BlockModelV3<A, OutputsCfg, Data, Href, Plugins, Transfers> {
+    return new BlockModelV3<A, OutputsCfg, Data, Href, Plugins, Transfers>({
       ...this.config,
       argsFunction: lambda as (data: unknown) => unknown,
     });
@@ -297,8 +306,8 @@ export class BlockModelV3<
    */
   public prerunArgs(
     fn: (data: Data) => unknown,
-  ): BlockModelV3<Args, OutputsCfg, Data, Href, Plugins> {
-    return new BlockModelV3<Args, OutputsCfg, Data, Href, Plugins>({
+  ): BlockModelV3<Args, OutputsCfg, Data, Href, Plugins, Transfers> {
+    return new BlockModelV3<Args, OutputsCfg, Data, Href, Plugins, Transfers>({
       ...this.config,
       prerunArgsFunction: fn as (data: unknown) => unknown,
     });
@@ -308,22 +317,24 @@ export class BlockModelV3<
   public sections<
     const Ret extends SectionsExpectedType,
     const RF extends RenderFunction<Args, Data, Ret>,
-  >(rf: RF): BlockModelV3<Args, OutputsCfg, Data, DeriveHref<ReturnType<RF>>, Plugins> {
-    return new BlockModelV3<Args, OutputsCfg, Data, DeriveHref<ReturnType<RF>>, Plugins>({
-      ...this.config,
-      // Replace the default sections callback with the user-provided one
-      sections: createAndRegisterRenderLambda(
-        { handle: "sections", lambda: () => rf(new BlockRenderCtx<Args, Data>()) },
-        true,
-      ),
-    });
+  >(rf: RF): BlockModelV3<Args, OutputsCfg, Data, DeriveHref<ReturnType<RF>>, Plugins, Transfers> {
+    return new BlockModelV3<Args, OutputsCfg, Data, DeriveHref<ReturnType<RF>>, Plugins, Transfers>(
+      {
+        ...this.config,
+        // Replace the default sections callback with the user-provided one
+        sections: createAndRegisterRenderLambda(
+          { handle: "sections", lambda: () => rf(new BlockRenderCtx<Args, Data>()) },
+          true,
+        ),
+      },
+    );
   }
 
   /** Sets a rendering function to derive block title, shown for the block in the left blocks-overview panel. */
   public title(
     rf: RenderFunction<Args, Data, string>,
-  ): BlockModelV3<Args, OutputsCfg, Data, Href, Plugins> {
-    return new BlockModelV3<Args, OutputsCfg, Data, Href, Plugins>({
+  ): BlockModelV3<Args, OutputsCfg, Data, Href, Plugins, Transfers> {
+    return new BlockModelV3<Args, OutputsCfg, Data, Href, Plugins, Transfers>({
       ...this.config,
       title: createAndRegisterRenderLambda({
         handle: "title",
@@ -334,8 +345,8 @@ export class BlockModelV3<
 
   public subtitle(
     rf: RenderFunction<Args, Data, string>,
-  ): BlockModelV3<Args, OutputsCfg, Data, Href, Plugins> {
-    return new BlockModelV3<Args, OutputsCfg, Data, Href, Plugins>({
+  ): BlockModelV3<Args, OutputsCfg, Data, Href, Plugins, Transfers> {
+    return new BlockModelV3<Args, OutputsCfg, Data, Href, Plugins, Transfers>({
       ...this.config,
       subtitle: createAndRegisterRenderLambda({
         handle: "subtitle",
@@ -346,8 +357,8 @@ export class BlockModelV3<
 
   public tags(
     rf: RenderFunction<Args, Data, string[]>,
-  ): BlockModelV3<Args, OutputsCfg, Data, Href, Plugins> {
-    return new BlockModelV3<Args, OutputsCfg, Data, Href, Plugins>({
+  ): BlockModelV3<Args, OutputsCfg, Data, Href, Plugins, Transfers> {
+    return new BlockModelV3<Args, OutputsCfg, Data, Href, Plugins, Transfers>({
       ...this.config,
       tags: createAndRegisterRenderLambda({
         handle: "tags",
@@ -359,8 +370,8 @@ export class BlockModelV3<
   /** Sets or overrides feature flags for the block. */
   public withFeatureFlags(
     flags: Partial<BlockCodeKnownFeatureFlags>,
-  ): BlockModelV3<Args, OutputsCfg, Data, Href, Plugins> {
-    return new BlockModelV3<Args, OutputsCfg, Data, Href, Plugins>({
+  ): BlockModelV3<Args, OutputsCfg, Data, Href, Plugins, Transfers> {
+    return new BlockModelV3<Args, OutputsCfg, Data, Href, Plugins, Transfers>({
       ...this.config,
       featureFlags: { ...this.config.featureFlags, ...flags },
     });
@@ -372,8 +383,8 @@ export class BlockModelV3<
    */
   public enriches(
     lambda: (args: Args) => PlRef[],
-  ): BlockModelV3<Args, OutputsCfg, Data, Href, Plugins> {
-    return new BlockModelV3<Args, OutputsCfg, Data, Href, Plugins>({
+  ): BlockModelV3<Args, OutputsCfg, Data, Href, Plugins, Transfers> {
+    return new BlockModelV3<Args, OutputsCfg, Data, Href, Plugins, Transfers>({
       ...this.config,
       enrichmentTargets: createAndRegisterRenderLambda({
         handle: "enrichmentTargets",
@@ -384,16 +395,18 @@ export class BlockModelV3<
 
   /**
    * Registers a plugin instance with the block.
+   * Consumes a transfer if one was defined for this plugin ID in the migration chain.
    *
-   * Plugins are UI components with their own model logic and persistent state.
-   * Each plugin must have a unique pluginId within the block.
+   * Type checks:
+   * - If Transfers[Id] exists, verifies it extends PTransferData (transfer type compatibility)
+   * - If no Transfers[Id], rejects plugins with transferAt set (missing .transfer() in data model)
+   * - Rejects duplicate plugin IDs (Id already in keyof Plugins)
    *
-   * @param pluginId - Unique identifier for this plugin instance within the block
-   * @param plugin - Configured PluginModel instance (created via factory.create(config))
+   * @param instance - PluginInstance created via factory.create({ pluginId, ... })
    * @param params - Per-property lambdas deriving plugin params from block RenderCtx
    *
    * @example
-   * .plugin('mainTable', dataTablePlugin.create({ defaultOps: {...} }), {
+   * .plugin(mainTable, {
    *   columns: (ctx) => ctx.outputs?.resolve("data")?.getPColumns(),
    *   sourceId: (ctx) => ctx.data.selectedSource,
    * })
@@ -403,32 +416,61 @@ export class BlockModelV3<
     PData extends PluginData,
     PParams extends PluginParams,
     POutputs extends PluginOutputs,
+    PTransferData,
   >(
-    pluginId: PluginId,
-    plugin: PluginModel<PData, PParams, POutputs>,
+    instance: PluginInstanceClass<
+      PluginId &
+        (PluginId extends keyof Transfers
+          ? Transfers[PluginId] extends PTransferData
+            ? string
+            : never
+          : [PTransferData] extends [never]
+            ? string
+            : never) &
+        (PluginId extends keyof Plugins ? never : string),
+      PData,
+      PParams,
+      POutputs,
+      PTransferData
+    >,
     params?: ParamsInput<PParams, Args, Data>,
   ): BlockModelV3<
     Args,
     OutputsCfg,
     Data,
     Href,
-    Plugins & { [K in PluginId]: PluginInstance<PData, PParams, POutputs> }
+    Plugins & { [K in PluginId]: PluginRecord<PData, PParams, POutputs> },
+    Omit<Transfers, PluginId>
+  >;
+  public plugin(
+    instance: PluginInstanceClass,
+    params?: ParamsInput<Record<string, unknown>, unknown, unknown>,
+  ): BlockModelV3<
+    Args,
+    OutputsCfg,
+    Data,
+    Href,
+    Record<string, PluginRecord>,
+    Record<string, unknown>
   > {
-    // Validate pluginId uniqueness
+    const pluginId = instance.id;
+    const plugin = instance[CREATE_PLUGIN_MODEL]();
+    const resolvedParams = (params ?? {}) as ParamsInputErased;
+
     if (pluginId in this.config.plugins) {
       throw new Error(`Plugin '${pluginId}' already registered`);
     }
 
-    const instance: PluginInstance<PData, PParams, POutputs> = {
+    const registered: PluginRecord = {
       model: plugin,
-      inputs: (params ?? {}) as ParamsInputErased,
+      inputs: resolvedParams,
     };
 
     return new BlockModelV3({
       ...this.config,
       plugins: {
         ...this.config.plugins,
-        [pluginId]: instance,
+        [pluginId]: registered,
       },
       featureFlags: mergeFeatureFlags(this.config.featureFlags, plugin.featureFlags ?? {}),
     });
@@ -436,16 +478,16 @@ export class BlockModelV3<
 
   /** Renders all provided block settings into a pre-configured platforma API
    * instance, that can be used in frontend to interact with block data, and
-   * other features provided by the platforma to the block. */
-  public done(): PlatformaExtended<
-    PlatformaV3<Data, Args, InferOutputsFromLambdas<OutputsCfg>, Href, Plugins>
-  > {
-    return this.withFeatureFlags({
-      ...this.config.featureFlags,
-    })._done();
-  }
-
-  public _done(): PlatformaExtended<
+   * other features provided by the platforma to the block.
+   *
+   * Type-level check: if there are unconsumed transfers (from `.transfer()` calls
+   * in the migration chain), this method requires an impossible `never` argument,
+   * producing a compile error. Register all transferred plugins via `.plugin(instance)`
+   * before calling `.done()`.
+   */
+  public done(
+    ..._: keyof Transfers extends never ? [] : [never]
+  ): PlatformaExtended<
     PlatformaV3<Data, Args, InferOutputsFromLambdas<OutputsCfg>, Href, Plugins>
   > {
     if (this.config.argsFunction === undefined) throw new Error("Args rendering function not set.");
@@ -462,7 +504,7 @@ export class BlockModelV3<
 
     const { dataModel, argsFunction, prerunArgsFunction } = this.config;
 
-    function getPlugin(handle: PluginHandle): PluginInstance {
+    function getPlugin(handle: PluginHandle): PluginRecord {
       const plugin = plugins[handle];
       if (!plugin) throw new Error(`Plugin model not found for '${handle}'`);
       return plugin;
@@ -477,13 +519,16 @@ export class BlockModelV3<
           migrateBlockData: (v) => dataModel.migrate(v),
           getPluginRegistry: () => pluginRegistry,
           migratePluginData: (handle, v) => getPlugin(handle).model.dataModel.migrate(v),
-          createPluginData: (handle) => getPlugin(handle).model.dataModel.getDefaultData(),
+          createPluginData: (handle, transfer) => {
+            if (transfer) return transfer;
+            return getPlugin(handle).model.getDefaultData();
+          },
         }),
       [BlockStorageFacadeCallbacks.StorageInitial]: () =>
         createInitialStorage({
           getDefaultBlockData: () => dataModel.getDefaultData(),
           getPluginRegistry: () => pluginRegistry,
-          createPluginData: (handle) => getPlugin(handle).model.dataModel.getDefaultData(),
+          createPluginData: (handle) => getPlugin(handle).model.getDefaultData(),
         }),
       [BlockStorageFacadeCallbacks.ArgsDerive]: (storageJson) =>
         deriveArgsFromStorage(storageJson, argsFunction),
@@ -600,7 +645,7 @@ type _CreateIsBlockModelV3 =
   _CreateResult extends BlockModelV3<infer _A, infer _O, infer _S> ? true : false;
 type _CreateTest = Expect<_CreateIsBlockModelV3>;
 
-// Test: BlockModelV3Config interface structure
+// Test: BlockModelV3Config interface structure (default generics)
 type _ConfigTest = Expect<
   Equal<
     BlockModelV3Config<_TestOutputs, _TestData>,
@@ -608,7 +653,7 @@ type _ConfigTest = Expect<
       renderingMode: BlockRenderingMode;
       argsFunction: ((data: unknown) => unknown) | undefined;
       prerunArgsFunction: ((data: unknown) => unknown) | undefined;
-      dataModel: DataModel<_TestData>;
+      dataModel: DataModel<_TestData, {}>;
       outputs: _TestOutputs;
       sections: ConfigRenderLambda;
       title: ConfigRenderLambda | undefined;

package/src/block_storage.test.ts

@@ -14,6 +14,7 @@ import {
   type PluginName,
   type PluginRegistry,
 } from "./block_storage";
+import { DataUnrecoverableError } from "./block_migrations";
 import type { PluginHandle } from "./plugin_handle";
 
 describe("BlockStorage", () => {
@@ -284,7 +285,7 @@ describe("BlockStorage", () => {
       const result = migrateBlockStorage(storage, {
         migrateBlockData: (versioned) => {
           const d = versioned.data as { count: number };
-          return { data: { count: d.count + 1 }, version: "v2" };
+          return { data: { count: d.count + 1 }, version: "v2", transfers: {} };
         },
         migratePluginData: (_pluginId, _versioned) => ({
           version: "v2",
@@ -338,6 +339,7 @@ describe("BlockStorage", () => {
         migrateBlockData: (versioned) => ({
           data: versioned.data as { count: number },
           version: "v2",
+          transfers: {},
         }),
         migratePluginData: (pluginId) => {
           throw new Error(`Plugin ${pluginId} migration failed`);
@@ -353,7 +355,7 @@ describe("BlockStorage", () => {
       }
     });
 
-    it("should reset plugin data when plugin type changes", () => {
+    it("should pass DATA_MODEL_LEGACY_VERSION when plugin type changes (upgradeLegacy handles it)", () => {
       const storage = createTestStorage();
       const newRegistry: PluginRegistry = { plugin1: "typeB" as PluginName }; // Different type
 
@@ -361,9 +363,43 @@ describe("BlockStorage", () => {
         migrateBlockData: (versioned) => ({
           data: versioned.data as { count: number },
           version: "v2",
+          transfers: {},
+        }),
+        migratePluginData: (_handle, versioned) => {
+          // Version should be reset to DATA_MODEL_LEGACY_VERSION
+          expect(versioned.version).toBe(DATA_MODEL_LEGACY_VERSION);
+          return {
+            version: "upgraded",
+            data: { upgraded: true, from: versioned.data },
+          };
+        },
+        newPluginRegistry: newRegistry,
+        createPluginData: () => {
+          throw new Error("Should not be called when upgradeLegacy succeeds");
+        },
+      });
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.storage.__plugins?.plugin1).toEqual({
+          __dataVersion: "upgraded",
+          __data: { upgraded: true, from: { value: "old" } },
+        });
+      }
+    });
+
+    it("should fall back to createPluginData when plugin type changes and no upgradeLegacy", () => {
+      const storage = createTestStorage();
+      const newRegistry: PluginRegistry = { plugin1: "typeB" as PluginName }; // Different type
+
+      const result = migrateBlockStorage(storage, {
+        migrateBlockData: (versioned) => ({
+          data: versioned.data as { count: number },
+          version: "v2",
+          transfers: {},
         }),
         migratePluginData: () => {
-          throw new Error("Should not be called for type change");
+          throw new DataUnrecoverableError(DATA_MODEL_LEGACY_VERSION);
         },
         newPluginRegistry: newRegistry,
         createPluginData: (pluginId) => ({
@@ -389,6 +425,7 @@ describe("BlockStorage", () => {
         migrateBlockData: (versioned) => ({
           data: versioned.data as { count: number },
           version: "v2",
+          transfers: {},
         }),
         migratePluginData: () => {
           throw new Error("Should not be called for new plugin");
@@ -417,6 +454,7 @@ describe("BlockStorage", () => {
         migrateBlockData: (versioned) => ({
           data: versioned.data as { count: number },
           version: "v2",
+          transfers: {},
         }),
         migratePluginData: () => {
           throw new Error("Should not be called for dropped plugin");
@@ -442,6 +480,7 @@ describe("BlockStorage", () => {
         migrateBlockData: (versioned) => ({
           data: versioned.data as { count: number },
           version: "v2",
+          transfers: {},
         }),
         migratePluginData: () => undefined, // Remove plugin
         newPluginRegistry: newRegistry,
@@ -453,5 +492,110 @@ describe("BlockStorage", () => {
         expect(result.storage.__plugins).toEqual({});
       }
     });
+
+    it("should pass transfer data to createPluginData for new plugins", () => {
+      const storage = createBlockStorage({ count: 1, tableState: "expanded" }, "v1");
+      const newRegistry: PluginRegistry = { table1: "dataTable" as PluginName };
+
+      const result = migrateBlockStorage(storage, {
+        migrateBlockData: (versioned) => ({
+          data: { count: (versioned.data as any).count },
+          version: "v2",
+          transfers: {
+            table1: { version: "__legacy__", data: { state: (versioned.data as any).tableState } },
+          },
+        }),
+        migratePluginData: () => {
+          throw new Error("Should not be called for new plugin");
+        },
+        newPluginRegistry: newRegistry,
+        createPluginData: (_handle, transfer) => {
+          // Transfer should be passed through
+          if (transfer) {
+            return { version: "v1", data: { upgraded: true, fromState: transfer.data } };
+          }
+          return { version: "v1", data: { upgraded: false } };
+        },
+      });
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.storage.__plugins?.table1).toEqual({
+          __dataVersion: "v1",
+          __data: { upgraded: true, fromState: { state: "expanded" } },
+        });
+      }
+    });
+
+    it("should not pass transfer to existing plugin with same type (uses migration instead)", () => {
+      const storage = createTestStorage(); // has plugin1 of typeA
+      const newRegistry: PluginRegistry = { plugin1: "typeA" as PluginName };
+
+      const result = migrateBlockStorage(storage, {
+        migrateBlockData: (versioned) => ({
+          data: versioned.data,
+          version: "v2",
+          transfers: {
+            plugin1: { version: "__legacy__", data: { should: "be ignored" } },
+          },
+        }),
+        migratePluginData: (_handle, versioned) => ({
+          version: "v2",
+          data: { migrated: true, from: versioned.data },
+        }),
+        newPluginRegistry: newRegistry,
+        createPluginData: () => {
+          throw new Error("Should not be called — existing plugin migrates");
+        },
+      });
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.storage.__plugins?.plugin1).toEqual({
+          __dataVersion: "v2",
+          __data: { migrated: true, from: { value: "old" } },
+        });
+      }
+    });
+
+    it("should handle multiple plugins: one transferred, one fresh", () => {
+      const storage = createBlockStorage({ count: 1 }, "v1");
+      const newRegistry: PluginRegistry = {
+        transferred: "typeT" as PluginName,
+        fresh: "typeF" as PluginName,
+      };
+
+      const result = migrateBlockStorage(storage, {
+        migrateBlockData: (versioned) => ({
+          data: versioned.data,
+          version: "v2",
+          transfers: {
+            transferred: { version: "__legacy__", data: { legacy: true } },
+          },
+        }),
+        migratePluginData: () => {
+          throw new Error("No existing plugins to migrate");
+        },
+        newPluginRegistry: newRegistry,
+        createPluginData: (_handle, transfer) => {
+          if (transfer) {
+            return { version: "v1", data: { fromTransfer: transfer.data } };
+          }
+          return { version: "v1", data: { default: true } };
+        },
+      });
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.storage.__plugins?.transferred).toEqual({
+          __dataVersion: "v1",
+          __data: { fromTransfer: { legacy: true } },
+        });
+        expect(result.storage.__plugins?.fresh).toEqual({
+          __dataVersion: "v1",
+          __data: { default: true },
+        });
+      }
+    });
   });
 });

package/src/block_storage.ts

@@ -10,7 +10,11 @@
  */
 
 import type { Branded } from "@milaboratories/pl-model-common";
-import type { DataVersioned } from "./block_migrations";
+import {
+  type DataVersioned,
+  type TransferRecord,
+  isDataUnrecoverableError,
+} from "./block_migrations";
 import type { PluginHandle, PluginFactoryLike, InferFactoryData } from "./plugin_handle";
 
 // =============================================================================
@@ -258,8 +262,10 @@ export type MigrationResult<TState> = MigrationSuccess<TState> | MigrationFailur
  * Conversion to internal VersionedData format is handled by migrateBlockStorage().
  */
 export interface MigrateBlockStorageConfig {
-  /** Migrate block data from any version to latest. Throws on failure. */
-  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown>;
+  /** Migrate block data from any version to latest. Returns migrated data and transfers. */
+  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {
+    transfers: TransferRecord;
+  };
   /** Migrate each plugin's data. Return undefined to remove the plugin. Throws on failure. */
   migratePluginData: (
     handle: PluginHandle,
@@ -267,8 +273,12 @@ export interface MigrateBlockStorageConfig {
   ) => DataVersioned<unknown> | undefined;
   /** The new plugin registry after migration (pluginId -> pluginName) */
   newPluginRegistry: PluginRegistry;
-  /** Factory to create initial data for new plugins */
-  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;
+  /** Factory to create initial data for new plugins. Transfer is provided when a
+   *  .transfer() was defined for this plugin in the block's migration chain. */
+  createPluginData: (
+    handle: PluginHandle,
+    transfer?: DataVersioned<unknown>,
+  ) => DataVersioned<unknown>;
 }
 
 /**
@@ -317,13 +327,15 @@ export function migrateBlockStorage(
 ): MigrationResult<unknown> {
   const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config;
 
-  // Step 1: Migrate block data
+  // Step 1: Migrate block data and collect transfers
   let migratedData: unknown;
   let newVersion: string;
+  let transfers: TransferRecord;
   try {
     const result = migrateBlockData({ version: storage.__dataVersion, data: storage.__data });
     migratedData = result.data;
     newVersion = result.version;
+    transfers = result.transfers;
   } catch (error) {
     return {
       success: false,
@@ -353,9 +365,32 @@ export function migrateBlockStorage(
           newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };
         }
         // If undefined returned, plugin is intentionally removed
+      } else if (existingEntry) {
+        // Plugin type changed — pass old data with DATA_MODEL_LEGACY_VERSION.
+        // If the new plugin has upgradeLegacy(), it migrates the old data.
+        // If not, defaultRecover throws DataUnrecoverableError → fall back to init.
+        let recovered = false;
+        try {
+          const migrated = migratePluginData(handle, {
+            version: DATA_MODEL_LEGACY_VERSION,
+            data: existingEntry.__data,
+          });
+          if (migrated) {
+            newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };
+            recovered = true;
+          }
+        } catch (recoverError) {
+          if (!isDataUnrecoverableError(recoverError)) throw recoverError;
+        }
+        if (!recovered) {
+          const transfer = transfers[handle];
+          const initial = createPluginData(handle, transfer);
+          newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };
+        }
       } else {
-        // New plugin or type changed - create with initial data
-        const initial = createPluginData(handle);
+        // New plugin - create with initial data, passing transfer if available
+        const transfer = transfers[handle];
+        const initial = createPluginData(handle, transfer);
         newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };
       }
     } catch (error) {