@platforma-sdk/model 1.58.0 → 1.58.1

package/src/block_migrations.ts

@@ -1,3 +1,5 @@
+import { DATA_MODEL_LEGACY_VERSION } from "./block_storage";
+
 export type DataVersionKey = string;
 export type DataMigrateFn<From, To> = (prev: Readonly<From>) => To;
 export type DataCreateFn<T> = () => T;
@@ -14,10 +16,13 @@ export function makeDataVersioned<T>(version: DataVersionKey, data: T): DataVers
   return { version, data };
 }
 
-/** Result of migration operation, may include warning if migration failed */
-export type DataMigrationResult<T> = DataVersioned<T> & {
-  warning?: string;
-};
+/** Thrown when a migration step fails. */
+export class DataMigrationError extends Error {
+  name = "DataMigrationError";
+  constructor(message: string) {
+    super(message);
+  }
+}
 
 /** Thrown by recover() to signal unrecoverable data. */
 export class DataUnrecoverableError extends Error {
@@ -68,14 +73,11 @@ type BuilderState<S> = {
   /** Index of the first step to run after recovery. Equals the number of steps
    *  present at the time recover() was called. */
   recoverFromIndex?: number;
-  /** Transforms legacy V1 model data ({ args, uiState }) at the initial version. */
-  upgradeLegacyFn?: (data: unknown) => unknown;
 };
 
 type RecoverState = {
   recoverFn?: (version: DataVersionKey, data: unknown) => unknown;
   recoverFromIndex?: number;
-  upgradeLegacyFn?: (data: unknown) => unknown;
 };
 
 /**
@@ -148,7 +150,6 @@ abstract class MigrationChainBase<Current> {
 class DataModelMigrationChainWithRecover<Current> extends MigrationChainBase<Current> {
   private readonly recoverFn?: (version: DataVersionKey, data: unknown) => unknown;
   private readonly recoverFromIndex?: number;
-  private readonly upgradeLegacyFn?: (data: unknown) => unknown;
 
   /** @internal */
   constructor(state: {
@@ -156,19 +157,16 @@ class DataModelMigrationChainWithRecover<Current> extends MigrationChainBase<Cur
     steps: MigrationStep[];
     recoverFn?: (version: DataVersionKey, data: unknown) => unknown;
     recoverFromIndex?: number;
-    upgradeLegacyFn?: (data: unknown) => unknown;
   }) {
     super(state);
     this.recoverFn = state.recoverFn;
     this.recoverFromIndex = state.recoverFromIndex;
-    this.upgradeLegacyFn = state.upgradeLegacyFn;
   }
 
   protected override recoverState(): RecoverState {
     return {
       recoverFn: this.recoverFn,
       recoverFromIndex: this.recoverFromIndex,
-      upgradeLegacyFn: this.upgradeLegacyFn,
     };
   }
 
@@ -186,7 +184,6 @@ class DataModelMigrationChainWithRecover<Current> extends MigrationChainBase<Cur
       steps,
       recoverFn: this.recoverFn,
       recoverFromIndex: this.recoverFromIndex,
-      upgradeLegacyFn: this.upgradeLegacyFn,
     });
   }
 }
@@ -239,10 +236,9 @@ class DataModelMigrationChain<Current> extends MigrationChainBase<Current> {
    * steps added after recover() will then run on the recovered data.
    *
    * Can only be called once — the returned chain has no recover() method.
-   * Mutually exclusive with upgradeLegacy().
    *
    * @param fn - Recovery function returning Current (the type at this chain position)
-   * @returns Builder with migrate() and init() but without recover() or upgradeLegacy()
+   * @returns Builder with migrate() and init() but without recover()
    *
    * @example
    * // Recover between migrations — recovered data goes through v3 migration
@@ -263,19 +259,28 @@ class DataModelMigrationChain<Current> extends MigrationChainBase<Current> {
       recoverFromIndex: this.migrationSteps.length,
     });
   }
+}
 
+/**
+ * Initial migration chain returned by `.from()`.
+ * Extends DataModelMigrationChain with `upgradeLegacy()` — available only before
+ * any `.migrate()` calls, since legacy data always arrives at the initial version.
+ *
+ * @typeParam Current - Data type at the initial version
+ * @internal
+ */
+class DataModelInitialChain<Current> extends DataModelMigrationChain<Current> {
   /**
    * Handle legacy V1 model state ({ args, uiState }) when upgrading a block from
    * BlockModel V1 to BlockModelV3.
    *
-   * When a V1 block is upgraded, its stored state `{ args, uiState }` arrives at the
-   * initial version (DATA_MODEL_DEFAULT_VERSION) in the migration chain. This method
-   * detects the legacy shape and transforms it to the current chain type using the
-   * provided typed callback. Non-legacy data passes through unchanged.
+   * When a V1 block is upgraded, its stored state `{ args, uiState }` is normalized
+   * to the internal default version. This method inserts a migration step from that
+   * internal version to the version specified in `.from()`, using the provided typed
+   * callback to transform the legacy shape. Non-legacy data passes through unchanged.
    *
-   * Should be called right after `.from()` (before any `.migrate()` calls), since legacy
-   * data always arrives at the initial version. Any `.migrate()` steps added after
-   * `upgradeLegacy()` will run on the transformed result.
+   * Must be called right after `.from()` — not available after `.migrate()` calls.
+   * Any `.migrate()` steps added after `upgradeLegacy()` will run on the transformed result.
    *
    * Can only be called once — the returned chain has no upgradeLegacy() method.
    * Mutually exclusive with recover().
@@ -291,7 +296,7 @@ class DataModelMigrationChain<Current> extends MigrationChainBase<Current> {
    * type BlockData = { inputFile: string; threshold: number; selectedTab: string };
    *
    * const dataModel = new DataModelBuilder()
-   *   .from<BlockData>(DATA_MODEL_DEFAULT_VERSION)
+   *   .from<BlockData>("v1")
    *   .upgradeLegacy<OldArgs, OldUiState>(({ args, uiState }) => ({
    *     inputFile: args.inputFile,
    *     threshold: args.threshold,
@@ -308,10 +313,18 @@ class DataModelMigrationChain<Current> extends MigrationChainBase<Current> {
       }
       return data;
     };
+
+    // Insert DATA_MODEL_LEGACY_VERSION as the true first version
+    // with a migration step that transforms legacy data to the user's initial version.
+    const initialVersion = this.versionChain[0];
+    const step: MigrationStep = {
+      fromVersion: DATA_MODEL_LEGACY_VERSION,
+      toVersion: initialVersion,
+      migrate: wrappedFn,
+    };
     return new DataModelMigrationChainWithRecover<Current>({
-      versionChain: this.versionChain,
-      steps: this.migrationSteps,
-      upgradeLegacyFn: wrappedFn,
+      versionChain: [DATA_MODEL_LEGACY_VERSION, ...this.versionChain],
+      steps: [step, ...this.migrationSteps],
     });
   }
 }
@@ -322,13 +335,13 @@ class DataModelMigrationChain<Current> extends MigrationChainBase<Current> {
  * @example
  * // Simple (no migrations):
  * const dataModel = new DataModelBuilder()
- *   .from<BlockData>(DATA_MODEL_DEFAULT_VERSION)
+ *   .from<BlockData>("v1")
  *   .init(() => ({ numbers: [] }));
  *
  * @example
  * // With migrations:
  * const dataModel = new DataModelBuilder()
- *   .from<BlockDataV1>(DATA_MODEL_DEFAULT_VERSION)
+ *   .from<BlockDataV1>("v1")
  *   .migrate<BlockDataV2>("v2", (v1) => ({ ...v1, labels: [] }))
  *   .migrate<BlockDataV3>("v3", (v2) => ({ ...v2, description: '' }))
  *   .init(() => ({ numbers: [], labels: [], description: '' }));
@@ -336,7 +349,7 @@ class DataModelMigrationChain<Current> extends MigrationChainBase<Current> {
  * @example
  * // With recover() between migrations — recovered data goes through remaining migrations:
  * const dataModelChain = new DataModelBuilder()
- *   .from<BlockDataV1>(DATA_MODEL_DEFAULT_VERSION)
+ *   .from<BlockDataV1>("v1")
  *   .migrate<BlockDataV2>("v2", (v1) => ({ ...v1, labels: [] }));
  *
  * // recover() placed before the v3 migration: recovered data goes through v3
@@ -355,7 +368,7 @@ class DataModelMigrationChain<Current> extends MigrationChainBase<Current> {
  * type BlockData = { inputFile: string; selectedTab: string };
  *
  * const dataModel = new DataModelBuilder()
- *   .from<BlockData>(DATA_MODEL_DEFAULT_VERSION)
+ *   .from<BlockData>("v1")
  *   .upgradeLegacy<OldArgs, OldUiState>(({ args, uiState }) => ({
  *     inputFile: args.inputFile,
  *     selectedTab: uiState.selectedTab,
@@ -367,11 +380,11 @@ export class DataModelBuilder {
    * Start the migration chain with the given initial data type and version key.
    *
    * @typeParam T - Data type for the initial version
-   * @param initialVersion - Version key string (e.g. DATA_MODEL_DEFAULT_VERSION or "v1")
+   * @param initialVersion - Version key string (e.g. "v1")
    * @returns Migration chain builder
    */
-  from<T>(initialVersion: string): DataModelMigrationChain<T> {
-    return new DataModelMigrationChain<T>({ versionChain: [initialVersion] });
+  from<T>(initialVersion: string): DataModelInitialChain<T> {
+    return new DataModelInitialChain<T>({ versionChain: [initialVersion] });
   }
 }
 
@@ -385,7 +398,7 @@ export class DataModelBuilder {
  * // With recover() between migrations:
  * // Recovered data (V2) goes through the v2→v3 migration automatically.
  * const dataModel = new DataModelBuilder()
- *   .from<V1>(DATA_MODEL_DEFAULT_VERSION)
+ *   .from<V1>("v1")
  *   .migrate<V2>("v2", (v1) => ({ ...v1, label: "" }))
  *   .recover((version, data) => {
  *     if (version === "legacy") return transformLegacy(data); // returns V2
@@ -403,8 +416,6 @@ export class DataModel<State> {
   private readonly initialDataFn: () => State;
   private readonly recoverFn: (version: DataVersionKey, data: unknown) => unknown;
   private readonly recoverFromIndex: number;
-  /** Transforms legacy V1 model data at the initial version before running migrations. */
-  private readonly upgradeLegacyFn?: (data: unknown) => unknown;
 
   private constructor({
     versionChain,
@@ -412,7 +423,6 @@ export class DataModel<State> {
     initialDataFn,
     recoverFn = defaultRecover,
     recoverFromIndex,
-    upgradeLegacyFn,
   }: BuilderState<State>) {
     if (versionChain.length === 0) {
       throw new Error("DataModel requires at least one version key");
@@ -423,7 +433,6 @@ export class DataModel<State> {
     this.initialDataFn = initialDataFn;
     this.recoverFn = recoverFn;
     this.recoverFromIndex = recoverFromIndex ?? steps.length;
-    this.upgradeLegacyFn = upgradeLegacyFn;
   }
 
   /**
@@ -457,34 +466,15 @@ export class DataModel<State> {
     return makeDataVersioned(this.latestVersion, this.initialDataFn());
   }
 
-  private recoverFrom(data: unknown, version: DataVersionKey): DataMigrationResult<State> {
+  private recoverFrom(data: unknown, version: DataVersionKey): DataVersioned<State> {
     // Step 1: call the recover function to get data at the recover point
-    let currentData: unknown;
-    try {
-      currentData = this.recoverFn(version, data);
-    } catch (error) {
-      if (isDataUnrecoverableError(error)) {
-        return { ...this.getDefaultData(), warning: error.message };
-      }
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      return {
-        ...this.getDefaultData(),
-        warning: `Recover failed for version '${version}': ${errorMessage}`,
-      };
-    }
+    // Let errors (including DataUnrecoverableError) propagate to the caller.
+    let currentData: unknown = this.recoverFn(version, data);
 
     // Step 2: run any migrations that were added after recover() in the chain
     for (let i = this.recoverFromIndex; i < this.steps.length; i++) {
       const step = this.steps[i];
-      try {
-        currentData = step.migrate(currentData);
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        return {
-          ...this.getDefaultData(),
-          warning: `Migration ${step.fromVersion}→${step.toVersion} failed: ${errorMessage}`,
-        };
-      }
+      currentData = step.migrate(currentData);
     }
 
     return { version: this.latestVersion, data: currentData as State };
@@ -494,13 +484,14 @@ export class DataModel<State> {
    * Migrate versioned data from any version to the latest.
    *
    * - If version is in chain, applies needed migrations (O(1) lookup)
-   * - If version is unknown, calls recover function then runs remaining migrations
-   * - If migration/recovery fails, returns default data with warning
+   * - If version is unknown, attempts recovery; falls back to initial data
+   * - If a migration step fails, throws so the caller can preserve original data
    *
    * @param versioned - Data with version tag
-   * @returns Migration result with data at latest version
+   * @returns Migrated data at the latest version
+   * @throws If a migration step from a known version fails
    */
-  migrate(versioned: DataVersioned<unknown>): DataMigrationResult<State> {
+  migrate(versioned: DataVersioned<unknown>): DataVersioned<State> {
     const { version: fromVersion, data } = versioned;
 
     if (fromVersion === this.latestVersion) {
@@ -509,35 +500,20 @@ export class DataModel<State> {
 
     const startIndex = this.stepsByFromVersion.get(fromVersion);
     if (startIndex === undefined) {
-      return this.recoverFrom(data, fromVersion);
-    }
-
-    let currentData: unknown = data;
-
-    // Legacy V1 upgrade: detect and transform { args, uiState } at the initial version
-    if (startIndex === 0 && this.upgradeLegacyFn) {
       try {
-        currentData = this.upgradeLegacyFn(currentData);
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        return {
-          ...this.getDefaultData(),
-          warning: `Legacy upgrade failed: ${errorMessage}`,
-        };
+        return this.recoverFrom(data, fromVersion);
+      } catch {
+        // Recovery failed (unknown version, recover fn threw, or post-recover
+        // migration failed) — reset to initial data rather than blocking the update.
+        return this.getDefaultData();
       }
     }
 
+    let currentData: unknown = data;
+
     for (let i = startIndex; i < this.steps.length; i++) {
       const step = this.steps[i];
-      try {
-        currentData = step.migrate(currentData);
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        return {
-          ...this.getDefaultData(),
-          warning: `Migration ${step.fromVersion}→${step.toVersion} failed: ${errorMessage}`,
-        };
-      }
+      currentData = step.migrate(currentData);
     }
 
     return { version: this.latestVersion, data: currentData as State };

package/src/block_model.ts

@@ -114,7 +114,7 @@ export class BlockModelV3<
    *
    * @example
    * const dataModel = new DataModelBuilder()
-   *   .from<BlockData>(DATA_MODEL_DEFAULT_VERSION)
+   *   .from<BlockData>("v1")
    *   .init(() => ({ numbers: [], labels: [] }));
    *
    * BlockModelV3.create(dataModel)

package/src/block_storage.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
 import {
   BLOCK_STORAGE_KEY,
   BLOCK_STORAGE_SCHEMA_VERSION,
-  DATA_MODEL_DEFAULT_VERSION,
+  DATA_MODEL_LEGACY_VERSION,
   createBlockStorage,
   getPluginData,
   getStorageData,
@@ -72,7 +72,7 @@ describe("BlockStorage", () => {
     it("should create storage with discriminator key and default values", () => {
       const storage = createBlockStorage();
       expect(storage[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
-      expect(storage.__dataVersion).toBe(DATA_MODEL_DEFAULT_VERSION);
+      expect(storage.__dataVersion).toBe(DATA_MODEL_LEGACY_VERSION);
       expect(storage.__data).toEqual({});
     });
 
@@ -80,7 +80,7 @@ describe("BlockStorage", () => {
       const data = { numbers: [1, 2, 3] };
       const storage = createBlockStorage(data);
       expect(storage[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
-      expect(storage.__dataVersion).toBe(DATA_MODEL_DEFAULT_VERSION);
+      expect(storage.__dataVersion).toBe(DATA_MODEL_LEGACY_VERSION);
       expect(storage.__data).toEqual(data);
     });
 
@@ -136,7 +136,7 @@ describe("BlockStorage", () => {
       const legacyData = { numbers: [1, 2, 3], name: "test" };
       const normalized = normalizeBlockStorage(legacyData);
       expect(normalized[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
-      expect(normalized.__dataVersion).toBe(DATA_MODEL_DEFAULT_VERSION);
+      expect(normalized.__dataVersion).toBe(DATA_MODEL_LEGACY_VERSION);
       expect(normalized.__data).toEqual(legacyData);
       expect(normalized.__pluginRegistry).toEqual({});
       expect(normalized.__plugins).toEqual({});
@@ -145,14 +145,14 @@ describe("BlockStorage", () => {
     it("should wrap primitive legacy data", () => {
       const normalized = normalizeBlockStorage("simple string");
       expect(normalized[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
-      expect(normalized.__dataVersion).toBe(DATA_MODEL_DEFAULT_VERSION);
+      expect(normalized.__dataVersion).toBe(DATA_MODEL_LEGACY_VERSION);
       expect(normalized.__data).toBe("simple string");
     });
 
     it("should wrap null legacy data", () => {
       const normalized = normalizeBlockStorage(null);
       expect(normalized[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
-      expect(normalized.__dataVersion).toBe(DATA_MODEL_DEFAULT_VERSION);
+      expect(normalized.__dataVersion).toBe(DATA_MODEL_LEGACY_VERSION);
       expect(normalized.__data).toBeNull();
     });
   });
@@ -188,7 +188,7 @@ describe("BlockStorage", () => {
       });
       expect(storage.__plugins).toEqual({
         table1: {
-          __dataVersion: DATA_MODEL_DEFAULT_VERSION,
+          __dataVersion: DATA_MODEL_LEGACY_VERSION,
           __data: { columns: ["a", "b"] },
         },
       });
@@ -254,7 +254,7 @@ describe("BlockStorage", () => {
         value: { foo: "bar" },
       });
       expect(updated.__plugins?.plugin1).toEqual({
-        __dataVersion: DATA_MODEL_DEFAULT_VERSION,
+        __dataVersion: DATA_MODEL_LEGACY_VERSION,
         __data: { foo: "bar" },
       });
     });

package/src/block_storage.ts

@@ -10,7 +10,7 @@
  */
 
 import type { Branded } from "@milaboratories/pl-model-common";
-import type { DataMigrationResult, DataVersioned } from "./block_migrations";
+import type { DataVersioned } from "./block_migrations";
 import type { PluginHandle, PluginFactoryLike, InferFactoryData } from "./plugin_handle";
 
 // =============================================================================
@@ -33,7 +33,7 @@ export const BLOCK_STORAGE_SCHEMA_VERSION = "v1";
  * Default data version for new blocks without migrations.
  * Unique identifier ensures blocks are created via DataModel API.
  */
-export const DATA_MODEL_DEFAULT_VERSION = "__pl_v1_d4e8f2a1__";
+export const DATA_MODEL_LEGACY_VERSION = "__pl_v1_d4e8f2a1__";
 
 /**
  * Type for valid schema versions
@@ -100,12 +100,12 @@ export function isBlockStorage(value: unknown): value is BlockStorage {
  * Creates a BlockStorage with the given initial data
  *
  * @param initialData - The initial data value (defaults to empty object)
- * @param version - The initial data version key (defaults to DATA_MODEL_DEFAULT_VERSION)
+ * @param version - The initial data version key (defaults to DATA_MODEL_LEGACY_VERSION)
  * @returns A new BlockStorage instance with discriminator key
  */
 export function createBlockStorage<TState = unknown>(
   initialData: TState = {} as TState,
-  version: string = DATA_MODEL_DEFAULT_VERSION,
+  version: string = DATA_MODEL_LEGACY_VERSION,
 ): BlockStorage<TState> {
   return {
     [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
@@ -132,7 +132,7 @@ export function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStor
       // Fix for early released version where __dataVersion was a number
       __dataVersion:
         typeof storage.__dataVersion === "number"
-          ? DATA_MODEL_DEFAULT_VERSION
+          ? DATA_MODEL_LEGACY_VERSION
           : storage.__dataVersion,
       // Ensure plugin fields have defaults
       __pluginRegistry: storage.__pluginRegistry ?? {},
@@ -197,7 +197,7 @@ export function updateStorageData<TValue = unknown>(
       const { pluginId, value } = payload;
       const currentPlugins = storage.__plugins ?? {};
       const existingEntry = currentPlugins[pluginId];
-      const version = existingEntry?.__dataVersion ?? DATA_MODEL_DEFAULT_VERSION;
+      const version = existingEntry?.__dataVersion ?? DATA_MODEL_LEGACY_VERSION;
       return {
         ...storage,
         __plugins: {
@@ -258,13 +258,13 @@ 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 */
-  migrateBlockData: (versioned: DataVersioned<unknown>) => DataMigrationResult<unknown>;
-  /** Migrate each plugin's data. Return undefined to remove the plugin. */
+  /** Migrate block data from any version to latest. Throws on failure. */
+  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown>;
+  /** Migrate each plugin's data. Return undefined to remove the plugin. Throws on failure. */
   migratePluginData: (
     handle: PluginHandle,
     versioned: DataVersioned<unknown>,
-  ) => DataMigrationResult<unknown> | undefined;
+  ) => DataVersioned<unknown> | undefined;
   /** The new plugin registry after migration (pluginId -> pluginName) */
   newPluginRegistry: PluginRegistry;
   /** Factory to create initial data for new plugins */

package/src/block_storage_callbacks.ts

@@ -27,7 +27,7 @@ import {
 import type { PluginHandle } from "./plugin_handle";
 
 import { stringifyJson, type StringifiedJson } from "@milaboratories/pl-model-common";
-import type { DataMigrationResult, DataVersioned } from "./block_migrations";
+import type { DataVersioned } from "./block_migrations";
 
 // =============================================================================
 // Hook interfaces for dependency injection
@@ -35,12 +35,12 @@ import type { DataMigrationResult, DataVersioned } from "./block_migrations";
 
 /** Dependencies for storage migration */
 export interface MigrationHooks {
-  migrateBlockData: (versioned: DataVersioned<unknown>) => DataMigrationResult<unknown>;
+  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown>;
   getPluginRegistry: () => PluginRegistry;
   migratePluginData: (
     handle: PluginHandle,
     versioned: DataVersioned<unknown>,
-  ) => DataMigrationResult<unknown> | undefined;
+  ) => DataVersioned<unknown> | undefined;
   createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;
 }
 
@@ -229,6 +229,7 @@ export function migrateStorage(
  *
  * @param hooks - Dependencies for creating initial block and plugin data
  * @returns Initial storage as branded JSON string
+ * @throws If initialDataFn or createPluginData throws
  */
 export function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage> {
   const blockDefault = hooks.getDefaultBlockData();

package/src/index.ts

@@ -1,7 +1,27 @@
 export * from "./block_state_patch";
 export * from "./block_state_util";
 export * from "./plugin_handle";
-export * from "./block_storage";
+export {
+  type BlockStorageSchemaVersion,
+  type PluginName,
+  type PluginRegistry,
+  type VersionedData,
+  type BlockStorage,
+  isBlockStorage,
+  createBlockStorage,
+  normalizeBlockStorage,
+  getStorageData,
+  deriveDataFromStorage,
+  type MutateStoragePayload,
+  updateStorageData,
+  type StorageDebugView,
+  type MigrationSuccess,
+  type MigrationFailure,
+  type MigrationResult,
+  type MigrateBlockStorageConfig,
+  migrateBlockStorage,
+  getPluginData,
+} from "./block_storage";
 export * from "./block_storage_facade";
 export * from "./block_model_legacy";
 export { BlockModelV3 } from "./block_model";
@@ -9,6 +29,7 @@ export type { PluginInstance, ParamsInput } from "./block_model";
 export {
   DataModel,
   DataModelBuilder,
+  DataMigrationError,
   DataUnrecoverableError,
   isDataUnrecoverableError,
   defaultRecover,

package/src/plugin_model.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
 import { PluginModel } from "./plugin_model";
 import type { PluginRenderCtx } from "./plugin_model";
 import { DataModelBuilder } from "./block_migrations";
-import { DATA_MODEL_DEFAULT_VERSION, type PluginName } from "./block_storage";
+import { type PluginName } from "./block_storage";
 import type { ResultPool } from "./render";
 
 // =============================================================================
@@ -11,7 +11,7 @@ import type { ResultPool } from "./render";
 
 type Data = { count: number; label: string };
 
-const dataModelChain = new DataModelBuilder().from<Data>(DATA_MODEL_DEFAULT_VERSION);
+const dataModelChain = new DataModelBuilder().from<Data>("v1");
 
 // Mock ResultPool for testing
 const mockResultPool = {} as ResultPool;

package/src/plugin_model.ts

@@ -83,7 +83,7 @@ export class PluginModel<
    * @returns PluginModelBuilder for chaining output definitions
    *
    * @example
-   * const dataModelChain = new DataModelBuilder().from<MyData>(DATA_MODEL_DEFAULT_VERSION);
+   * const dataModelChain = new DataModelBuilder().from<MyData>("v1");
    *
    * const myPlugin = PluginModel.define({
    *   name: 'myPlugin' as PluginName,
@@ -169,7 +169,7 @@ class PluginModelFactory<
  * @typeParam Outputs - Accumulated output types
  *
  * @example
- * const dataModelChain = new DataModelBuilder().from<TableData>(DATA_MODEL_DEFAULT_VERSION);
+ * const dataModelChain = new DataModelBuilder().from<TableData>("v1");
  *
  * const dataTable = PluginModel.define<TableData, TableParams, TableConfig>({
  *     name: 'dataTable' as PluginName,