@platforma-sdk/model 1.53.0 → 1.53.2

package/dist/block_storage_vm.js.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage_vm.js","sources":["../src/block_storage_vm.ts"],"sourcesContent":["/**\n * BlockStorage VM Integration - Internal module for VM-based storage operations.\n *\n * This module auto-registers internal callbacks that the middle layer can invoke\n * to perform storage transformations. Block developers never interact with these\n * directly - they only see `state`.\n *\n * Registered callbacks (all prefixed with `__pl_` for internal SDK use):\n * - `__pl_storage_applyUpdate`: (currentStorageJson, payload) => updatedStorageJson\n * - `__pl_storage_debugView`: (rawStorage) => JSON string with storage debug view\n * - `__pl_storage_migrate`: (currentStorageJson) => MigrationResult\n * - `__pl_args_derive`: (storageJson) => ArgsDeriveResult\n * - `__pl_prerunArgs_derive`: (storageJson) => ArgsDeriveResult\n *\n * Callbacks registered by DataModel.registerCallbacks():\n * - `__pl_data_initial`: () => initial data\n * - `__pl_data_upgrade`: (versioned) => UpgradeResult\n * - `__pl_storage_initial`: () => initial BlockStorage as JSON string\n *\n * @module block_storage_vm\n * @internal\n */\n\nimport {\n  BLOCK_STORAGE_KEY,\n  BLOCK_STORAGE_SCHEMA_VERSION,\n  type BlockStorage,\n  type MutateStoragePayload,\n  type StorageDebugView,\n  createBlockStorage,\n  getStorageData,\n  isBlockStorage,\n  updateStorageData,\n} from './block_storage';\nimport { stringifyJson, type StringifiedJson } from '@milaboratories/pl-model-common';\nimport { tryGetCfgRenderCtx, tryRegisterCallback } from './internal';\n\n/**\n * Result of storage normalization\n */\nexport interface NormalizeStorageResult {\n  /** The normalized BlockStorage object */\n  storage: BlockStorage;\n  /** The extracted data (what developers see) */\n  data: unknown;\n}\n\n/**\n * Normalizes raw storage data and extracts state.\n * Handles all formats:\n * - New BlockStorage format (has discriminator)\n * - Legacy V1/V2 format ({ args, uiState })\n * - Raw V3 state (any other format)\n *\n * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)\n * @returns Object with normalized storage and extracted state\n */\nfunction normalizeStorage(rawStorage: unknown): NormalizeStorageResult {\n  // Handle undefined/null\n  if (rawStorage === undefined || rawStorage === null) {\n    const storage = createBlockStorage({});\n    return { storage, data: {} };\n  }\n\n  // Parse JSON string if needed\n  let parsed = rawStorage;\n  if (typeof rawStorage === 'string') {\n    try {\n      parsed = JSON.parse(rawStorage);\n    } catch {\n      // If parsing fails, treat string as the data\n      const storage = createBlockStorage(rawStorage);\n      return { storage, data: rawStorage };\n    }\n  }\n\n  // Check for BlockStorage format (has discriminator)\n  if (isBlockStorage(parsed)) {\n    return { storage: parsed, data: getStorageData(parsed) };\n  }\n\n  // Check for legacy V1/V2 format: { args, uiState }\n  if (isLegacyModelV1ApiFormat(parsed)) {\n    // For legacy format, the whole object IS the data\n    const storage = createBlockStorage(parsed);\n    return { storage, data: parsed };\n  }\n\n  // Raw V3 data - wrap it\n  const storage = createBlockStorage(parsed);\n  return { storage, data: parsed };\n}\n\n/**\n * Applies a state update to existing storage.\n * Used when setData is called from the frontend.\n *\n * @param currentStorageJson - Current storage as JSON string (must be defined)\n * @param newData - New data from application\n * @returns Updated storage as JSON string\n */\nfunction applyStorageUpdate(currentStorageJson: string, payload: MutateStoragePayload): string {\n  const { storage: currentStorage } = normalizeStorage(currentStorageJson);\n\n  // Update data while preserving other storage fields (version, plugins)\n  const updatedStorage = updateStorageData(currentStorage, payload);\n\n  return JSON.stringify(updatedStorage);\n}\n\n/**\n * Checks if data is in legacy Model API v1 format.\n * Legacy format has { args, uiState? } at top level without the BlockStorage discriminator.\n */\nfunction isLegacyModelV1ApiFormat(data: unknown): data is { args?: unknown } {\n  if (data === null || typeof data !== 'object') return false;\n  if (isBlockStorage(data)) return false;\n\n  const obj = data as Record<string, unknown>;\n  return 'args' in obj;\n}\n\n// =============================================================================\n// Auto-register internal callbacks when module is loaded in VM\n// =============================================================================\n\n// Register apply update callback (requires existing storage)\ntryRegisterCallback('__pl_storage_applyUpdate', (currentStorageJson: string, payload: MutateStoragePayload) => {\n  return applyStorageUpdate(currentStorageJson, payload);\n});\n\n/**\n * Gets storage debug view from raw storage data.\n * Returns structured debug info about the storage state.\n *\n * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)\n * @returns JSON string with storage debug view\n */\nfunction getStorageDebugView(rawStorage: unknown): StringifiedJson<StorageDebugView> {\n  const { storage } = normalizeStorage(rawStorage);\n  const debugView: StorageDebugView = {\n    dataVersion: storage.__dataVersion,\n    data: storage.__data,\n  };\n  return stringifyJson(debugView);\n}\n\n// Register debug view callback\ntryRegisterCallback('__pl_storage_debugView', (rawStorage: unknown) => {\n  return getStorageDebugView(rawStorage);\n});\n\n// =============================================================================\n// Migration Support\n// =============================================================================\n\n/**\n * Result of storage migration.\n * Returned by __pl_storage_migrate callback.\n *\n * - Error result: { error: string } - serious failure (no context, etc.)\n * - Success result: { newStorageJson: string, info: string, warn?: string } - migration succeeded or reset to initial\n */\nexport type MigrationResult =\n  | { error: string }\n  | { error?: undefined; newStorageJson: string; info: string; warn?: string };\n\n/** Result from Migrator.upgrade() */\ninterface UpgradeResult {\n  version: number;\n  data: unknown;\n  warning?: string;\n}\n\n/**\n * Runs storage migration using the DataModel's upgrade callback.\n * This is the main entry point for the middle layer to trigger migrations.\n *\n * Uses the '__pl_data_upgrade' callback registered by DataModel.registerCallbacks() which:\n * - Handles all migration logic internally\n * - Returns { version, data, warning? } - warning present if reset to initial data\n *\n * @param currentStorageJson - Current storage as JSON string (or undefined)\n * @returns MigrationResult\n */\nfunction migrateStorage(currentStorageJson: string | undefined): MigrationResult {\n  // Get the callback registry context\n  const ctx = tryGetCfgRenderCtx();\n  if (ctx === undefined) {\n    return { error: 'Not in config rendering context' };\n  }\n\n  // Normalize storage to get current data and version\n  const { storage: currentStorage, data: currentData } = normalizeStorage(currentStorageJson);\n  const currentVersion = currentStorage.__dataVersion;\n\n  // Helper to create storage with given data and version\n  const createStorageJson = (data: unknown, version: number): string => {\n    return JSON.stringify({\n      ...currentStorage,\n      __dataVersion: version,\n      __data: data,\n    });\n  };\n\n  // Get the upgrade callback (registered by DataModel.registerCallbacks())\n  const upgradeCallback = ctx.callbackRegistry['__pl_data_upgrade'] as ((v: { version: number; data: unknown }) => UpgradeResult) | undefined;\n  if (typeof upgradeCallback !== 'function') {\n    return { error: '__pl_data_upgrade callback not found (DataModel not registered)' };\n  }\n\n  // Call the migrator's upgrade function\n  let result: UpgradeResult;\n  try {\n    result = upgradeCallback({ version: currentVersion, data: currentData });\n  } catch (e) {\n    const errorMsg = e instanceof Error ? e.message : String(e);\n    return { error: `upgrade() threw: ${errorMsg}` };\n  }\n\n  // Build info message\n  const info = result.version === currentVersion\n    ? `No migration needed (v${currentVersion})`\n    : result.warning\n      ? `Reset to initial data (v${result.version})`\n      : `Migrated v${currentVersion}→v${result.version}`;\n\n  return {\n    newStorageJson: createStorageJson(result.data, result.version),\n    info,\n    warn: result.warning,\n  };\n}\n\n// Register migrate callback\ntryRegisterCallback('__pl_storage_migrate', (currentStorageJson: string | undefined) => {\n  return migrateStorage(currentStorageJson);\n});\n\n// =============================================================================\n// Args Derivation from Storage\n// =============================================================================\n\n/**\n * Result of args derivation from storage.\n * Returned by __pl_args_derive and __pl_prerunArgs_derive callbacks.\n */\nexport type ArgsDeriveResult =\n  | { error: string }\n  | { error?: undefined; value: unknown };\n\n/**\n * Derives args from storage using the registered 'args' callback.\n * This extracts data from storage and passes it to the block's args() function.\n *\n * @param storageJson - Storage as JSON string\n * @returns ArgsDeriveResult with derived args or error\n */\nfunction deriveArgsFromStorage(storageJson: string): ArgsDeriveResult {\n  const ctx = tryGetCfgRenderCtx();\n  if (ctx === undefined) {\n    return { error: 'Not in config rendering context' };\n  }\n\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Get the args callback (registered by BlockModelV3.args())\n  const argsCallback = ctx.callbackRegistry['args'] as ((data: unknown) => unknown) | undefined;\n  if (typeof argsCallback !== 'function') {\n    return { error: 'args callback not found' };\n  }\n\n  // Call the args callback with extracted data\n  try {\n    const result = argsCallback(data);\n    return { value: result };\n  } catch (e) {\n    const errorMsg = e instanceof Error ? e.message : String(e);\n    return { error: `args() threw: ${errorMsg}` };\n  }\n}\n\n// Register args derivation callback\ntryRegisterCallback('__pl_args_derive', (storageJson: string) => {\n  return deriveArgsFromStorage(storageJson);\n});\n\n/**\n * Derives prerunArgs from storage using the registered 'prerunArgs' callback.\n * Falls back to 'args' callback if 'prerunArgs' is not defined.\n *\n * @param storageJson - Storage as JSON string\n * @returns ArgsDeriveResult with derived prerunArgs or error\n */\nfunction derivePrerunArgsFromStorage(storageJson: string): ArgsDeriveResult {\n  const ctx = tryGetCfgRenderCtx();\n  if (ctx === undefined) {\n    return { error: 'Not in config rendering context' };\n  }\n\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Try prerunArgs callback first\n  const prerunArgsCallback = ctx.callbackRegistry['prerunArgs'] as ((data: unknown) => unknown) | undefined;\n  if (typeof prerunArgsCallback === 'function') {\n    try {\n      const result = prerunArgsCallback(data);\n      return { value: result };\n    } catch (e) {\n      const errorMsg = e instanceof Error ? e.message : String(e);\n      return { error: `prerunArgs() threw: ${errorMsg}` };\n    }\n  }\n\n  // Fall back to args callback\n  const argsCallback = ctx.callbackRegistry['args'] as ((data: unknown) => unknown) | undefined;\n  if (typeof argsCallback !== 'function') {\n    return { error: 'args callback not found (fallback from missing prerunArgs)' };\n  }\n\n  try {\n    const result = argsCallback(data);\n    return { value: result };\n  } catch (e) {\n    const errorMsg = e instanceof Error ? e.message : String(e);\n    return { error: `args() threw (fallback): ${errorMsg}` };\n  }\n}\n\n// Register prerunArgs derivation callback\ntryRegisterCallback('__pl_prerunArgs_derive', (storageJson: string) => {\n  return derivePrerunArgsFromStorage(storageJson);\n});\n\n// Export discriminator key and schema version for external checks\nexport { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION };\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"block_storage_vm.js","sources":["../src/block_storage_vm.ts"],"sourcesContent":["/**\n * BlockStorage VM Integration - Internal module for VM-based storage operations.\n *\n * This module auto-registers internal callbacks that the middle layer can invoke\n * to perform storage transformations. Block developers never interact with these\n * directly - they only see `state`.\n *\n * Registered callbacks (all prefixed with `__pl_` for internal SDK use):\n * - `__pl_storage_applyUpdate`: (currentStorageJson, payload) => updatedStorageJson\n * - `__pl_storage_debugView`: (rawStorage) => JSON string with storage debug view\n * - `__pl_storage_migrate`: (currentStorageJson) => MigrationResult\n * - `__pl_args_derive`: (storageJson) => ArgsDeriveResult\n * - `__pl_prerunArgs_derive`: (storageJson) => ArgsDeriveResult\n *\n * Callbacks registered by DataModel.registerCallbacks():\n * - `__pl_data_initial`: () => initial data\n * - `__pl_data_upgrade`: (versioned) => DataMigrationResult\n * - `__pl_storage_initial`: () => initial BlockStorage as JSON string\n *\n * @module block_storage_vm\n * @internal\n */\n\nimport {\n  BLOCK_STORAGE_KEY,\n  BLOCK_STORAGE_SCHEMA_VERSION,\n  type BlockStorage,\n  type MutateStoragePayload,\n  type StorageDebugView,\n  createBlockStorage,\n  getStorageData,\n  isBlockStorage,\n  normalizeBlockStorage,\n  updateStorageData,\n} from './block_storage';\nimport { stringifyJson, type StringifiedJson } from '@milaboratories/pl-model-common';\nimport { tryGetCfgRenderCtx, tryRegisterCallback } from './internal';\n\n/**\n * Result of storage normalization\n */\nexport interface NormalizeStorageResult {\n  /** The normalized BlockStorage object */\n  storage: BlockStorage;\n  /** The extracted data (what developers see) */\n  data: unknown;\n}\n\n/**\n * Normalizes raw storage data and extracts state.\n * Handles all formats:\n * - New BlockStorage format (has discriminator)\n * - Legacy V1/V2 format ({ args, uiState })\n * - Raw V3 state (any other format)\n *\n * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)\n * @returns Object with normalized storage and extracted state\n */\nfunction normalizeStorage(rawStorage: unknown): NormalizeStorageResult {\n  // Handle undefined/null\n  if (rawStorage === undefined || rawStorage === null) {\n    const storage = createBlockStorage({});\n    return { storage, data: {} };\n  }\n\n  // Parse JSON string if needed\n  let parsed = rawStorage;\n  if (typeof rawStorage === 'string') {\n    try {\n      parsed = JSON.parse(rawStorage);\n    } catch {\n      // If parsing fails, treat string as the data\n      const storage = createBlockStorage(rawStorage);\n      return { storage, data: rawStorage };\n    }\n  }\n\n  // Check for BlockStorage format (has discriminator)\n  if (isBlockStorage(parsed)) {\n    const storage = normalizeBlockStorage(parsed);\n    return { storage, data: getStorageData(storage) };\n  }\n\n  // Check for legacy V1/V2 format: { args, uiState }\n  if (isLegacyModelV1ApiFormat(parsed)) {\n    // For legacy format, the whole object IS the data\n    const storage = createBlockStorage(parsed);\n    return { storage, data: parsed };\n  }\n\n  // Raw V3 data - wrap it\n  const storage = createBlockStorage(parsed);\n  return { storage, data: parsed };\n}\n\n/**\n * Applies a state update to existing storage.\n * Used when setData is called from the frontend.\n *\n * @param currentStorageJson - Current storage as JSON string (must be defined)\n * @param newData - New data from application\n * @returns Updated storage as JSON string\n */\nfunction applyStorageUpdate(currentStorageJson: string, payload: MutateStoragePayload): string {\n  const { storage: currentStorage } = normalizeStorage(currentStorageJson);\n\n  // Update data while preserving other storage fields (version, plugins)\n  const updatedStorage = updateStorageData(currentStorage, payload);\n\n  return JSON.stringify(updatedStorage);\n}\n\n/**\n * Checks if data is in legacy Model API v1 format.\n * Legacy format has { args, uiState? } at top level without the BlockStorage discriminator.\n */\nfunction isLegacyModelV1ApiFormat(data: unknown): data is { args?: unknown } {\n  if (data === null || typeof data !== 'object') return false;\n  if (isBlockStorage(data)) return false;\n\n  const obj = data as Record<string, unknown>;\n  return 'args' in obj;\n}\n\n// =============================================================================\n// Auto-register internal callbacks when module is loaded in VM\n// =============================================================================\n\n// Register apply update callback (requires existing storage)\ntryRegisterCallback('__pl_storage_applyUpdate', (currentStorageJson: string, payload: MutateStoragePayload) => {\n  return applyStorageUpdate(currentStorageJson, payload);\n});\n\n/**\n * Gets storage debug view from raw storage data.\n * Returns structured debug info about the storage state.\n *\n * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)\n * @returns JSON string with storage debug view\n */\nfunction getStorageDebugView(rawStorage: unknown): StringifiedJson<StorageDebugView> {\n  const { storage } = normalizeStorage(rawStorage);\n  const debugView: StorageDebugView = {\n    dataVersion: storage.__dataVersion,\n    data: storage.__data,\n  };\n  return stringifyJson(debugView);\n}\n\n// Register debug view callback\ntryRegisterCallback('__pl_storage_debugView', (rawStorage: unknown) => {\n  return getStorageDebugView(rawStorage);\n});\n\n// =============================================================================\n// Migration Support\n// =============================================================================\n\n/**\n * Result of storage migration.\n * Returned by __pl_storage_migrate callback.\n *\n * - Error result: { error: string } - serious failure (no context, etc.)\n * - Success result: { newStorageJson: string, info: string, warn?: string } - migration succeeded or reset to initial\n */\nexport type MigrationResult =\n  | { error: string }\n  | { error?: undefined; newStorageJson: string; info: string; warn?: string };\n\n/** Result from DataModel.migrate() */\ninterface DataMigrationResult {\n  version: string;\n  data: unknown;\n  warning?: string;\n}\n\n/**\n * Runs storage migration using the DataModel's migrate callback.\n * This is the main entry point for the middle layer to trigger migrations.\n *\n * Uses the '__pl_data_upgrade' callback registered by DataModel.registerCallbacks() which:\n * - Handles all migration logic internally\n * - Returns { version, data, warning? } - warning present if reset to initial data\n *\n * @param currentStorageJson - Current storage as JSON string (or undefined)\n * @returns MigrationResult\n */\nfunction migrateStorage(currentStorageJson: string | undefined): MigrationResult {\n  // Get the callback registry context\n  const ctx = tryGetCfgRenderCtx();\n  if (ctx === undefined) {\n    return { error: 'Not in config rendering context' };\n  }\n\n  // Normalize storage to get current data and version\n  const { storage: currentStorage, data: currentData } = normalizeStorage(currentStorageJson);\n  const currentVersion = currentStorage.__dataVersion;\n\n  // Helper to create storage with given data and version\n  const createStorageJson = (data: unknown, version: string): string => {\n    return JSON.stringify({\n      ...currentStorage,\n      __dataVersion: version,\n      __data: data,\n    });\n  };\n\n  // Get the migrate callback (registered by DataModel.registerCallbacks())\n  const migrateCallback = ctx.callbackRegistry['__pl_data_upgrade'] as ((v: { version: string; data: unknown }) => DataMigrationResult) | undefined;\n  if (typeof migrateCallback !== 'function') {\n    return { error: '__pl_data_upgrade callback not found (DataModel not registered)' };\n  }\n\n  // Call the migrator's migrate function\n  let result: DataMigrationResult;\n  try {\n    result = migrateCallback({ version: currentVersion, data: currentData });\n  } catch (e) {\n    const errorMsg = e instanceof Error ? e.message : String(e);\n    return { error: `migrate() threw: ${errorMsg}` };\n  }\n\n  // Build info message\n  const info = result.version === currentVersion\n    ? `No migration needed (${currentVersion})`\n    : result.warning\n      ? `Reset to initial data (${result.version})`\n      : `Migrated ${currentVersion}→${result.version}`;\n\n  return {\n    newStorageJson: createStorageJson(result.data, result.version),\n    info,\n    warn: result.warning,\n  };\n}\n\n// Register migrate callback\ntryRegisterCallback('__pl_storage_migrate', (currentStorageJson: string | undefined) => {\n  return migrateStorage(currentStorageJson);\n});\n\n// =============================================================================\n// Args Derivation from Storage\n// =============================================================================\n\n/**\n * Result of args derivation from storage.\n * Returned by __pl_args_derive and __pl_prerunArgs_derive callbacks.\n */\nexport type ArgsDeriveResult =\n  | { error: string }\n  | { error?: undefined; value: unknown };\n\n/**\n * Derives args from storage using the registered 'args' callback.\n * This extracts data from storage and passes it to the block's args() function.\n *\n * @param storageJson - Storage as JSON string\n * @returns ArgsDeriveResult with derived args or error\n */\nfunction deriveArgsFromStorage(storageJson: string): ArgsDeriveResult {\n  const ctx = tryGetCfgRenderCtx();\n  if (ctx === undefined) {\n    return { error: 'Not in config rendering context' };\n  }\n\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Get the args callback (registered by BlockModelV3.args())\n  const argsCallback = ctx.callbackRegistry['args'] as ((data: unknown) => unknown) | undefined;\n  if (typeof argsCallback !== 'function') {\n    return { error: 'args callback not found' };\n  }\n\n  // Call the args callback with extracted data\n  try {\n    const result = argsCallback(data);\n    return { value: result };\n  } catch (e) {\n    const errorMsg = e instanceof Error ? e.message : String(e);\n    return { error: `args() threw: ${errorMsg}` };\n  }\n}\n\n// Register args derivation callback\ntryRegisterCallback('__pl_args_derive', (storageJson: string) => {\n  return deriveArgsFromStorage(storageJson);\n});\n\n/**\n * Derives prerunArgs from storage using the registered 'prerunArgs' callback.\n * Falls back to 'args' callback if 'prerunArgs' is not defined.\n *\n * @param storageJson - Storage as JSON string\n * @returns ArgsDeriveResult with derived prerunArgs or error\n */\nfunction derivePrerunArgsFromStorage(storageJson: string): ArgsDeriveResult {\n  const ctx = tryGetCfgRenderCtx();\n  if (ctx === undefined) {\n    return { error: 'Not in config rendering context' };\n  }\n\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Try prerunArgs callback first\n  const prerunArgsCallback = ctx.callbackRegistry['prerunArgs'] as ((data: unknown) => unknown) | undefined;\n  if (typeof prerunArgsCallback === 'function') {\n    try {\n      const result = prerunArgsCallback(data);\n      return { value: result };\n    } catch (e) {\n      const errorMsg = e instanceof Error ? e.message : String(e);\n      return { error: `prerunArgs() threw: ${errorMsg}` };\n    }\n  }\n\n  // Fall back to args callback\n  const argsCallback = ctx.callbackRegistry['args'] as ((data: unknown) => unknown) | undefined;\n  if (typeof argsCallback !== 'function') {\n    return { error: 'args callback not found (fallback from missing prerunArgs)' };\n  }\n\n  try {\n    const result = argsCallback(data);\n    return { value: result };\n  } catch (e) {\n    const errorMsg = e instanceof Error ? e.message : String(e);\n    return { error: `args() threw (fallback): ${errorMsg}` };\n  }\n}\n\n// Register prerunArgs derivation callback\ntryRegisterCallback('__pl_prerunArgs_derive', (storageJson: string) => {\n  return derivePrerunArgsFromStorage(storageJson);\n});\n\n// Export discriminator key and schema version for external checks\nexport { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION };\n"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -40,6 +40,7 @@ exports.readOutput = block_state_util.readOutput;
 exports.wrapOutputs = block_state_util.wrapOutputs;
 exports.BLOCK_STORAGE_KEY = block_storage.BLOCK_STORAGE_KEY;
 exports.BLOCK_STORAGE_SCHEMA_VERSION = block_storage.BLOCK_STORAGE_SCHEMA_VERSION;
+exports.DATA_MODEL_DEFAULT_VERSION = block_storage.DATA_MODEL_DEFAULT_VERSION;
 exports.createBlockStorage = block_storage.createBlockStorage;
 exports.defaultBlockStorageHandlers = block_storage.defaultBlockStorageHandlers;
 exports.deriveDataFromStorage = block_storage.deriveDataFromStorage;
@@ -59,6 +60,12 @@ exports.updateStorageDataVersion = block_storage.updateStorageDataVersion;
 exports.BlockModel = builder.BlockModel;
 exports.BlockModelV3 = block_model.BlockModelV3;
 exports.DataModel = block_migrations.DataModel;
+exports.DataModelBuilder = block_migrations.DataModelBuilder;
+exports.DataUnrecoverableError = block_migrations.DataUnrecoverableError;
+exports.defaultRecover = block_migrations.defaultRecover;
+exports.defineDataVersions = block_migrations.defineDataVersions;
+exports.isDataUnrecoverableError = block_migrations.isDataUnrecoverableError;
+exports.makeDataVersioned = block_migrations.makeDataVersioned;
 exports.downgradeCfgOrLambda = normalization.downgradeCfgOrLambda;
 exports.extractConfig = normalization.extractConfig;
 exports.isConfigLambda = types.isConfigLambda;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export * from './block_state_util';
 export * from './block_storage';
 export * from './builder';
 export { BlockModelV3 } from './block_model';
-export { DataModel } from './block_migrations';
+export { DataModel, DataModelBuilder, DataUnrecoverableError, isDataUnrecoverableError, defineDataVersions, defaultRecover, makeDataVersioned, } from './block_migrations';
 export * from './bconfig';
 export * from './components';
 export * from './config';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAE9C,OAAO,KAAK,gBAAgB,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,sBAAsB,EACtB,wBAAwB,EACxB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAE9C,OAAO,KAAK,gBAAgB,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,8 +1,8 @@
 export { OutputError, readOutput, wrapOutputs } from './block_state_util.js';
-export { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION, createBlockStorage, defaultBlockStorageHandlers, deriveDataFromStorage, getFromStorage, getPluginData, getPluginNames, getStorageData, getStorageDataVersion, isBlockStorage, mergeBlockStorageHandlers, normalizeBlockStorage, removePluginData, setPluginData, updateStorage, updateStorageData, updateStorageDataVersion } from './block_storage.js';
+export { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION, DATA_MODEL_DEFAULT_VERSION, createBlockStorage, defaultBlockStorageHandlers, deriveDataFromStorage, getFromStorage, getPluginData, getPluginNames, getStorageData, getStorageDataVersion, isBlockStorage, mergeBlockStorageHandlers, normalizeBlockStorage, removePluginData, setPluginData, updateStorage, updateStorageData, updateStorageDataVersion } from './block_storage.js';
 export { BlockModel } from './builder.js';
 export { BlockModelV3 } from './block_model.js';
-export { DataModel } from './block_migrations.js';
+export { DataModel, DataModelBuilder, DataUnrecoverableError, defaultRecover, defineDataVersions, isDataUnrecoverableError, makeDataVersioned } from './block_migrations.js';
 export { downgradeCfgOrLambda, extractConfig } from './bconfig/normalization.js';
 export { isConfigLambda } from './bconfig/types.js';
 export { createPFrameForGraphs, enrichCompatible, getAvailableWithLinkersAxes, isHiddenFromGraphColumn, isHiddenFromUIColumn } from './components/PFrameForGraphs.js';

package/dist/package.json.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var version = "1.53.0";
+var version = "1.53.2";
 
 exports.version = version;
 //# sourceMappingURL=package.json.cjs.map

package/dist/package.json.js

@@ -1,4 +1,4 @@
-var version = "1.53.0";
+var version = "1.53.2";
 
 export { version };
 //# sourceMappingURL=package.json.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platforma-sdk/model",
-  "version": "1.53.0",
+  "version": "1.53.2",
   "description": "Platforma.bio SDK / Block Model",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -24,18 +24,18 @@
     "es-toolkit": "^1.39.10",
     "zod": "~3.23.8",
     "@milaboratories/ptabler-expression-js": "1.1.11",
-    "@milaboratories/pl-model-common": "1.24.1",
-    "@milaboratories/pl-error-like": "1.12.5"
+    "@milaboratories/pl-error-like": "1.12.5",
+    "@milaboratories/pl-model-common": "1.24.1"
   },
   "devDependencies": {
     "typescript": "~5.6.3",
     "vitest": "^4.0.16",
     "@vitest/coverage-istanbul": "^4.0.16",
     "fast-json-patch": "^3.1.1",
-    "@milaboratories/build-configs": "1.4.0",
-    "@milaboratories/eslint-config": "1.0.5",
     "@milaboratories/helpers": "1.13.0",
+    "@milaboratories/build-configs": "1.4.0",
     "@milaboratories/ts-builder": "1.2.4",
+    "@milaboratories/eslint-config": "1.0.5",
     "@milaboratories/ts-configs": "1.2.0"
   },
   "scripts": {

package/src/block_migrations.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DataModel,
+  DataModelBuilder,
+  defaultRecover,
+  defineDataVersions,
+  makeDataVersioned,
+} from './block_migrations';
+
+describe('defineDataVersions', () => {
+  it('throws on duplicate version values', () => {
+    expect(() =>
+      defineDataVersions({
+        V1: 'v1',
+        V2: 'v1', // duplicate!
+      }),
+    ).toThrow('Duplicate version values: v1');
+  });
+
+  it('throws on empty version values', () => {
+    expect(() =>
+      defineDataVersions({
+        V1: 'v1',
+        V2: '', // empty!
+      }),
+    ).toThrow('Version values must be non-empty strings (empty: V2)');
+  });
+
+  it('allows unique version values', () => {
+    const versions = defineDataVersions({
+      V1: 'v1',
+      V2: 'v2',
+    });
+    expect(versions.V1).toBe('v1');
+    expect(versions.V2).toBe('v2');
+  });
+});
+
+describe('makeDataVersioned', () => {
+  it('creates correct DataVersioned shape', () => {
+    const versioned = makeDataVersioned('v1', { count: 42 });
+    expect(versioned).toStrictEqual({ version: 'v1', data: { count: 42 } });
+  });
+});
+
+describe('DataModel migrations', () => {
+  it('resets to initial data on unknown version', () => {
+    const Version = defineDataVersions({
+      V1: 'v1',
+      V2: 'v2',
+    });
+
+    type VersionedData = {
+      [Version.V1]: { count: number };
+      [Version.V2]: { count: number; label: string };
+    };
+
+    const dataModel = new DataModelBuilder<VersionedData>()
+      .from(Version.V1)
+      .migrate(Version.V2, (v1) => ({ ...v1, label: '' }))
+      .init(() => ({ count: 0, label: '' }));
+
+    const result = dataModel.migrate(makeDataVersioned('legacy', { count: 42 }));
+    expect(result.version).toBe('v2');
+    expect(result.data).toStrictEqual({ count: 0, label: '' });
+    expect(result.warning).toBe(`Unknown version 'legacy'`);
+  });
+
+  it('uses recover() for unknown versions', () => {
+    const Version = defineDataVersions({
+      V1: 'v1',
+      V2: 'v2',
+    });
+
+    type VersionedData = {
+      [Version.V1]: { count: number };
+      [Version.V2]: { count: number; label: string };
+    };
+
+    const dataModel = new DataModelBuilder<VersionedData>()
+      .from(Version.V1)
+      .migrate(Version.V2, (v1) => ({ ...v1, label: '' }))
+      .recover((version, data) => {
+        if (version === 'legacy' && typeof data === 'object' && data !== null && 'count' in data) {
+          return { count: (data as { count: number }).count, label: 'recovered' };
+        }
+        return defaultRecover(version, data);
+      })
+      .init(() => ({ count: 0, label: '' }));
+
+    const result = dataModel.migrate(makeDataVersioned('legacy', { count: 7 }));
+    expect(result.version).toBe('v2');
+    expect(result.data).toStrictEqual({ count: 7, label: 'recovered' });
+    expect(result.warning).toBeUndefined();
+  });
+
+  it('allows recover() to delegate to defaultRecover', () => {
+    const Version = defineDataVersions({
+      V1: 'v1',
+      V2: 'v2',
+    });
+
+    type VersionedData = {
+      [Version.V1]: { count: number };
+      [Version.V2]: { count: number; label: string };
+    };
+
+    const dataModel = new DataModelBuilder<VersionedData>()
+      .from(Version.V1)
+      .migrate(Version.V2, (v1) => ({ ...v1, label: '' }))
+      .recover((version, data) => defaultRecover(version, data))
+      .init(() => ({ count: 0, label: '' }));
+
+    const result = dataModel.migrate(makeDataVersioned('legacy', { count: 7 }));
+    expect(result.version).toBe('v2');
+    expect(result.data).toStrictEqual({ count: 0, label: '' });
+    expect(result.warning).toBe(`Unknown version 'legacy'`);
+  });
+
+  it('returns initial data on migration failure', () => {
+    const Version = defineDataVersions({
+      V1: 'v1',
+      V2: 'v2',
+    });
+
+    type VersionedData = {
+      [Version.V1]: { numbers: number[] };
+      [Version.V2]: { numbers: number[]; label: string };
+    };
+
+    const dataModel = new DataModelBuilder<VersionedData>()
+      .from(Version.V1)
+      .migrate(Version.V2, (v1) => {
+        if (v1.numbers.includes(666)) {
+          throw new Error('Forbidden number');
+        }
+        return { ...v1, label: 'ok' };
+      })
+      .init(() => ({ numbers: [], label: '' }));
+
+    const result = dataModel.migrate(makeDataVersioned('v1', { numbers: [666] }));
+    expect(result.version).toBe('v2');
+    expect(result.data).toStrictEqual({ numbers: [], label: '' });
+    expect(result.warning).toBe(`Migration v1→v2 failed: Forbidden number`);
+  });
+});
+
+function _compileTimeTypeChecks() {
+  const Version = defineDataVersions({
+    V1: 'v1',
+    V2: 'v2',
+  });
+
+  type VersionedData = {
+    [Version.V1]: { count: number };
+    [Version.V2]: { count: number; label: string };
+  };
+
+  // Valid: complete migration chain
+  new DataModelBuilder<VersionedData>()
+    .from(Version.V1)
+    .migrate(Version.V2, (v1) => ({ ...v1, label: '' }))
+    .init(() => ({ count: 0, label: '' }));
+
+  // Valid: with recover()
+  new DataModelBuilder<VersionedData>()
+    .from(Version.V1)
+    .migrate(Version.V2, (v1) => ({ ...v1, label: '' }))
+    .recover((version, data) => defaultRecover(version, data))
+    .init(() => ({ count: 0, label: '' }));
+
+  new DataModelBuilder<VersionedData>()
+    // @ts-expect-error invalid initial version key
+    .from('v3');
+
+  new DataModelBuilder<VersionedData>()
+    .from(Version.V1)
+    // @ts-expect-error invalid migration target key
+    .migrate('v3', (v1) => ({ ...v1, label: '' }));
+
+  new DataModelBuilder<VersionedData>()
+    .from(Version.V1)
+    // @ts-expect-error migration return type must match target version
+    .migrate(Version.V2, (v1) => ({ ...v1, invalid: true }));
+
+  // Incomplete migration chain - V2 not covered
+  // This errors at compile-time with the `this` parameter constraint:
+  // "The 'this' context of type 'DataModelMigrationChain<..., "v1", "v2">' is not assignable to method's 'this' of type 'DataModelMigrationChain<..., "v1", never>'"
+  // Note: @ts-expect-error doesn't work reliably in unused functions
+  // new DataModelBuilder<VersionedData>()
+  //   .from(Version.V1)
+  //   .init(() => ({ count: 0 }));
+
+  new DataModelBuilder<VersionedData>()
+    .from(Version.V1)
+    .migrate(Version.V2, (v1) => ({ ...v1, label: '' }))
+    .recover((version, data) => defaultRecover(version, data))
+    // @ts-expect-error recover() returns builder without recover() method - cannot call twice (only init() available)
+    .recover((version, data) => defaultRecover(version, data));
+
+  new DataModelBuilder<VersionedData>()
+    .from(Version.V1)
+    .recover((version, data) => defaultRecover(version, data))
+    // @ts-expect-error recover() returns builder without migrate() method (only init() available)
+    .migrate(Version.V2, (v1) => ({ ...v1, label: '' }));
+}