@platforma-sdk/model 1.63.1 → 1.64.0

package/dist/block_storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage.js","names":[],"sources":["../src/block_storage.ts"],"sourcesContent":["/**\n * BlockStorage - Typed storage abstraction for block persistent data.\n *\n * This module provides:\n * - A typed structure for block storage with versioning and plugin support\n * - Utility functions for manipulating storage\n * - Handler interfaces for model-level customization\n *\n * @module block_storage\n */\n\nimport type { Branded } from \"@milaboratories/pl-model-common\";\nimport {\n  type DataVersioned,\n  type TransferRecord,\n  isDataUnrecoverableError,\n} from \"./block_migrations\";\nimport type { PluginHandle, PluginFactoryLike, InferFactoryData } from \"./plugin_handle\";\n\n// =============================================================================\n// Core Types\n// =============================================================================\n\n/**\n * Discriminator key for BlockStorage format detection.\n * This unique hash-based key identifies data as BlockStorage vs legacy formats.\n */\nexport const BLOCK_STORAGE_KEY = \"__pl_a7f3e2b9__\";\n\n/**\n * Current BlockStorage schema version.\n * Increment this when the storage structure itself changes (not block state migrations).\n */\nexport const BLOCK_STORAGE_SCHEMA_VERSION = \"v1\";\n\n/**\n * Default data version for new blocks without migrations.\n * Unique identifier ensures blocks are created via DataModel API.\n */\nexport const DATA_MODEL_LEGACY_VERSION = \"__pl_v1_d4e8f2a1__\";\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = \"v1\"; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Branded type for plugin names - globally unique plugin type identifiers.\n * Using a branded type enforces explicit casting (`as PluginName`) which makes\n * it easy to find all plugin name definitions in the codebase and verify uniqueness.\n */\nexport type PluginName = Branded<string, \"PluginName\">;\n\n/**\n * Plugin registry - maps pluginId (unique within a block) to pluginName (globally unique plugin type).\n * Using a Record highlights that pluginIds must be unique within a block.\n */\nexport type PluginRegistry = Record<PluginHandle, PluginName>;\n\n/**\n * Versioned data - used for both block data and plugin data\n */\nexport interface VersionedData<TData = unknown> {\n  /** Version of the data, used for migrations */\n  __dataVersion: string;\n  /** The persistent data */\n  __data: TData;\n}\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version key for block data migrations\n * - __data: The block's user-facing data (state)\n * - __pluginRegistry: Map from pluginId to pluginName (optional)\n * - __plugins: Plugin-specific data keyed by pluginId (optional)\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Registry of plugins: pluginId -> pluginName */\n  __pluginRegistry?: PluginRegistry;\n  /** Plugin-specific data, keyed by plugin handle */\n  __plugins?: Record<PluginHandle, VersionedData<unknown>>;\n} & VersionedData<TState>;\n\n/**\n * Type guard to check if a value is a valid BlockStorage object.\n * Checks for the discriminator key and valid schema version.\n */\nexport function isBlockStorage(value: unknown): value is BlockStorage {\n  if (value === null || typeof value !== \"object\") return false;\n  const obj = value as Record<string, unknown>;\n  const schemaVersion = obj[BLOCK_STORAGE_KEY];\n  // Currently only 'v1' is valid, but this allows future versions\n  return schemaVersion === \"v1\"; // Add more versions as schema evolves\n}\n\n// =============================================================================\n// Factory Functions\n// =============================================================================\n\n/**\n * Creates a BlockStorage with the given initial data\n *\n * @param initialData - The initial data value (defaults to empty object)\n * @param version - The initial data version key (defaults to DATA_MODEL_LEGACY_VERSION)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: string = DATA_MODEL_LEGACY_VERSION,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n    __pluginRegistry: {},\n    __plugins: {},\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is (with defaults for missing fields).\n * If the input is legacy format (raw state), wraps it in BlockStorage structure.\n *\n * @param raw - Raw storage data (may be legacy format or BlockStorage)\n * @returns Normalized BlockStorage\n */\nexport function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState> {\n  if (isBlockStorage(raw)) {\n    const storage = raw as BlockStorage<TState>;\n    return {\n      ...storage,\n      // Fix for early released version where __dataVersion was a number\n      __dataVersion:\n        typeof storage.__dataVersion === \"number\"\n          ? DATA_MODEL_LEGACY_VERSION\n          : storage.__dataVersion,\n      // Ensure plugin fields have defaults\n      __pluginRegistry: storage.__pluginRegistry ?? {},\n      __plugins: storage.__plugins ?? {},\n    };\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState);\n}\n\n// =============================================================================\n// Data Access & Update Functions\n// =============================================================================\n\n/**\n * Gets the data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data value\n */\nexport function getStorageData<TState>(storage: BlockStorage<TState>): TState {\n  return storage.__data;\n}\n\n/**\n * Derives data from raw block storage.\n * This function is meant to be called from sdk/ui-vue to extract\n * user-facing data from the raw storage returned by the middle layer.\n *\n * The middle layer returns raw storage (opaque to it), and the UI\n * uses this function to derive the actual data value.\n *\n * @param rawStorage - Raw storage data from middle layer (may be any format)\n * @returns The extracted data value, or undefined if storage is undefined/null\n */\nexport function deriveDataFromStorage<TData = unknown>(rawStorage: unknown): TData {\n  // Normalize to BlockStorage format (handles legacy formats too)\n  const storage = normalizeBlockStorage<TData>(rawStorage);\n  return getStorageData(storage);\n}\n\n/** Payload for storage mutation operations. SDK defines specific operations. */\nexport type MutateStoragePayload<T = unknown> =\n  | { operation: \"update-block-data\"; value: T }\n  | { operation: \"update-plugin-data\"; pluginId: PluginHandle; value: unknown };\n\n/**\n * Updates the data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param payload - The update payload with operation and value\n * @returns A new BlockStorage with updated data\n */\nexport function updateStorageData<TValue = unknown>(\n  storage: BlockStorage<TValue>,\n  payload: MutateStoragePayload<TValue>,\n): BlockStorage<TValue> {\n  switch (payload.operation) {\n    case \"update-block-data\":\n      return { ...storage, __data: payload.value };\n    case \"update-plugin-data\": {\n      const { pluginId, value } = payload;\n      const currentPlugins = storage.__plugins ?? {};\n      const existingEntry = currentPlugins[pluginId];\n      const version = existingEntry?.__dataVersion ?? DATA_MODEL_LEGACY_VERSION;\n      return {\n        ...storage,\n        __plugins: {\n          ...currentPlugins,\n          [pluginId]: {\n            __dataVersion: version,\n            __data: value,\n          },\n        },\n      };\n    }\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n// =============================================================================\n// Atomic Migration\n// =============================================================================\n\n/**\n * Result of a successful atomic migration.\n */\nexport interface MigrationSuccess<TState> {\n  success: true;\n  /** The fully migrated storage - commit this to persist */\n  storage: BlockStorage<TState>;\n}\n\n/**\n * Result of a failed atomic migration.\n * The original storage is untouched - user must choose to abort or reset.\n */\nexport interface MigrationFailure {\n  success: false;\n  /** Description of what failed */\n  error: string;\n  /** Which step failed: 'block' or pluginId */\n  failedAt: string;\n}\n\nexport type MigrationResult<TState> = MigrationSuccess<TState> | MigrationFailure;\n\n/**\n * Configuration for atomic block storage migration.\n * Callbacks use DataVersioned format (the DataModel API format).\n * Conversion to internal VersionedData format is handled by migrateBlockStorage().\n */\nexport interface MigrateBlockStorageConfig {\n  /** Migrate block data from any version to latest. Returns migrated data and transfers. */\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {\n    transfers: TransferRecord;\n  };\n  /** Migrate each plugin's data. Return undefined to remove the plugin. Throws on failure. */\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  /** The new plugin registry after migration (pluginId -> pluginName) */\n  newPluginRegistry: PluginRegistry;\n  /** Factory to create initial data for new plugins. Transfer is provided when a\n   *  .transfer() was defined for this plugin in the block's migration chain. */\n  createPluginData: (\n    handle: PluginHandle,\n    transfer?: DataVersioned<unknown>,\n  ) => DataVersioned<unknown>;\n}\n\n/**\n * Performs atomic migration of block storage including block data and all plugins.\n *\n * Migration is atomic: either everything succeeds and a new storage is returned,\n * or an error is returned and the original storage is completely untouched.\n *\n * Migration steps:\n * 1. Migrate block data\n * 2. For each plugin in newPluginRegistry:\n *    - If plugin exists with same name: migrate its data\n *    - Otherwise (new or type changed): create with initial data\n *    Plugins not in newPluginRegistry are dropped.\n *\n * If any step throws, migration fails and original storage is preserved.\n * User can then choose to:\n * - Abort: keep original storage, don't update block\n * - Reset: call createBlockStorage() to start fresh\n *\n * @param storage - The original storage (will not be modified)\n * @param config - Migration configuration\n * @returns Migration result - either success with new storage, or failure with error info\n *\n * @example\n * const result = migrateBlockStorage(storage, {\n *   migrateBlockData: (versioned) => blockDataModel.migrate(versioned),\n *   migratePluginData: (pluginId, versioned) => getPluginModel(pluginId).migrate(versioned),\n *   newPluginRegistry: { table1: 'dataTable' as PluginName },\n *   createPluginData: (pluginId) => getPluginModel(pluginId).getDefaultData(),\n * });\n *\n * if (result.success) {\n *   commitStorage(result.storage);\n * } else {\n *   const userChoice = await askUser(`Migration failed: ${result.error}. Reset data?`);\n *   if (userChoice === 'reset') {\n *     commitStorage(createBlockStorage(initialData, currentVersion));\n *   }\n *   // else: abort, keep original\n * }\n */\nexport function migrateBlockStorage(\n  storage: BlockStorage<unknown>,\n  config: MigrateBlockStorageConfig,\n): MigrationResult<unknown> {\n  const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config;\n\n  // Step 1: Migrate block data and collect transfers\n  let migratedData: unknown;\n  let newVersion: string;\n  let transfers: TransferRecord;\n  try {\n    const result = migrateBlockData({ version: storage.__dataVersion, data: storage.__data });\n    migratedData = result.data;\n    newVersion = result.version;\n    transfers = result.transfers;\n  } catch (error) {\n    return {\n      success: false,\n      error: error instanceof Error ? error.message : String(error),\n      failedAt: \"block\",\n    };\n  }\n\n  // Step 2: Migrate plugins\n  const oldPlugins = storage.__plugins ?? {};\n  const oldRegistry = storage.__pluginRegistry ?? {};\n  const newPlugins: Record<PluginHandle, VersionedData<unknown>> = {};\n\n  for (const [key, pluginName] of Object.entries(newPluginRegistry)) {\n    const handle = key as PluginHandle;\n    const existingEntry = oldPlugins[handle];\n    const existingName = oldRegistry[handle];\n\n    try {\n      if (existingEntry && existingName === pluginName) {\n        // Plugin exists with same type - migrate its data\n        const migrated = migratePluginData(handle, {\n          version: existingEntry.__dataVersion,\n          data: existingEntry.__data,\n        });\n        if (migrated) {\n          newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };\n        }\n        // If undefined returned, plugin is intentionally removed\n      } else if (existingEntry) {\n        // Plugin type changed — pass old data with DATA_MODEL_LEGACY_VERSION.\n        // If the new plugin has upgradeLegacy(), it migrates the old data.\n        // If not, defaultRecover throws DataUnrecoverableError → fall back to init.\n        let recovered = false;\n        try {\n          const migrated = migratePluginData(handle, {\n            version: DATA_MODEL_LEGACY_VERSION,\n            data: existingEntry.__data,\n          });\n          if (migrated) {\n            newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };\n            recovered = true;\n          }\n        } catch (recoverError) {\n          if (!isDataUnrecoverableError(recoverError)) throw recoverError;\n        }\n        if (!recovered) {\n          const transfer = transfers[handle];\n          const initial = createPluginData(handle, transfer);\n          newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n        }\n      } else {\n        // New plugin - create with initial data, passing transfer if available\n        const transfer = transfers[handle];\n        const initial = createPluginData(handle, transfer);\n        newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n      }\n    } catch (error) {\n      return {\n        success: false,\n        error: error instanceof Error ? error.message : String(error),\n        failedAt: handle,\n      };\n    }\n  }\n\n  // Step 3: Build final storage atomically\n  const migratedStorage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: newVersion,\n    __data: migratedData,\n    __pluginRegistry: newPluginRegistry,\n    __plugins: newPlugins,\n  };\n\n  return {\n    success: true,\n    storage: migratedStorage,\n  };\n}\n\n/**\n * Gets plugin-specific data from block storage.\n * Accepts raw storage (any format) and normalizes internally.\n *\n * When called with a typed PluginHandle<F>, the return type is automatically\n * inferred from the factory's phantom `__types.data` field.\n *\n * @param rawStorage - Raw block storage (may be legacy format or BlockStorage)\n * @param handle - The plugin handle (branded plugin instance id)\n * @returns The plugin data, typed via factory inference\n * @throws If plugin is not found in storage\n */\nexport function getPluginData<F extends PluginFactoryLike>(\n  rawStorage: unknown,\n  handle: PluginHandle<F>,\n): InferFactoryData<F> {\n  const storage = normalizeBlockStorage(rawStorage);\n  const pluginEntry = storage.__plugins?.[handle];\n  if (!pluginEntry) throw new Error(`Plugin '${handle}' not found in block storage`);\n  return pluginEntry.__data as InferFactoryData<F>;\n}\n"],"mappings":"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"}
+{"version":3,"file":"block_storage.js","names":[],"sources":["../src/block_storage.ts"],"sourcesContent":["/**\n * BlockStorage - Typed storage abstraction for block persistent data.\n *\n * This module provides:\n * - A typed structure for block storage with versioning and plugin support\n * - Utility functions for manipulating storage\n * - Handler interfaces for model-level customization\n *\n * @module block_storage\n */\n\nimport type { Branded } from \"@milaboratories/pl-model-common\";\nimport {\n  type DataVersioned,\n  type TransferRecord,\n  isDataUnrecoverableError,\n} from \"./block_migrations\";\nimport type { PluginHandle, PluginFactoryLike, InferFactoryData } from \"./plugin_handle\";\n\n// =============================================================================\n// Core Types\n// =============================================================================\n\n/**\n * Discriminator key for BlockStorage format detection.\n * This unique hash-based key identifies data as BlockStorage vs legacy formats.\n */\nexport const BLOCK_STORAGE_KEY = \"__pl_a7f3e2b9__\";\n\n/**\n * Current BlockStorage schema version.\n * Increment this when the storage structure itself changes (not block state migrations).\n */\nexport const BLOCK_STORAGE_SCHEMA_VERSION = \"v1\";\n\n/**\n * Default data version for new blocks without migrations.\n * Unique identifier ensures blocks are created via DataModel API.\n */\nexport const DATA_MODEL_LEGACY_VERSION = \"__pl_v1_d4e8f2a1__\";\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = \"v1\"; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Branded type for plugin names - globally unique plugin type identifiers.\n * Using a branded type enforces explicit casting (`as PluginName`) which makes\n * it easy to find all plugin name definitions in the codebase and verify uniqueness.\n */\nexport type PluginName = Branded<string, \"PluginName\">;\n\n/**\n * Plugin registry - maps pluginId (unique within a block) to pluginName (globally unique plugin type).\n * Using a Record highlights that pluginIds must be unique within a block.\n */\nexport type PluginRegistry = Record<PluginHandle, PluginName>;\n\n/**\n * Versioned data - used for both block data and plugin data\n */\nexport interface VersionedData<TData = unknown> {\n  /** Version of the data, used for migrations */\n  __dataVersion: string;\n  /** The persistent data */\n  __data: TData;\n}\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version key for block data migrations\n * - __data: The block's user-facing data (state)\n * - __pluginRegistry: Map from pluginId to pluginName (optional)\n * - __plugins: Plugin-specific data keyed by pluginId (optional)\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Registry of plugins: pluginId -> pluginName */\n  __pluginRegistry?: PluginRegistry;\n  /** Plugin-specific data, keyed by plugin handle */\n  __plugins?: Record<PluginHandle, VersionedData<unknown>>;\n} & VersionedData<TState>;\n\n/**\n * Type guard to check if a value is a valid BlockStorage object.\n * Checks for the discriminator key and valid schema version.\n */\nexport function isBlockStorage(value: unknown): value is BlockStorage {\n  if (value === null || typeof value !== \"object\") return false;\n  const obj = value as Record<string, unknown>;\n  const schemaVersion = obj[BLOCK_STORAGE_KEY];\n  // Currently only 'v1' is valid, but this allows future versions\n  return schemaVersion === \"v1\"; // Add more versions as schema evolves\n}\n\n// =============================================================================\n// Factory Functions\n// =============================================================================\n\n/**\n * Creates a BlockStorage with the given initial data\n *\n * @param initialData - The initial data value (defaults to empty object)\n * @param version - The initial data version key (defaults to DATA_MODEL_LEGACY_VERSION)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: string = DATA_MODEL_LEGACY_VERSION,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n    __pluginRegistry: {},\n    __plugins: {},\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is (with defaults for missing fields).\n * If the input is legacy format (raw state), wraps it in BlockStorage structure.\n *\n * @param raw - Raw storage data (may be legacy format or BlockStorage)\n * @returns Normalized BlockStorage\n */\nexport function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState> {\n  if (isBlockStorage(raw)) {\n    const storage = raw as BlockStorage<TState>;\n    return {\n      ...storage,\n      // Fix for early released version where __dataVersion was a number\n      __dataVersion:\n        typeof storage.__dataVersion === \"number\"\n          ? DATA_MODEL_LEGACY_VERSION\n          : storage.__dataVersion,\n      // Ensure plugin fields have defaults\n      __pluginRegistry: storage.__pluginRegistry ?? {},\n      __plugins: storage.__plugins ?? {},\n    };\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState);\n}\n\n// =============================================================================\n// Data Access & Update Functions\n// =============================================================================\n\n/**\n * Gets the data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data value\n */\nexport function getStorageData<TState>(storage: BlockStorage<TState>): TState {\n  return storage.__data;\n}\n\n/**\n * Derives data from raw block storage.\n * This function is meant to be called from sdk/ui-vue to extract\n * user-facing data from the raw storage returned by the middle layer.\n *\n * The middle layer returns raw storage (opaque to it), and the UI\n * uses this function to derive the actual data value.\n *\n * @param rawStorage - Raw storage data from middle layer (may be any format)\n * @returns The extracted data value, or undefined if storage is undefined/null\n */\nexport function deriveDataFromStorage<TData = unknown>(rawStorage: unknown): TData {\n  // Normalize to BlockStorage format (handles legacy formats too)\n  const storage = normalizeBlockStorage<TData>(rawStorage);\n  return getStorageData(storage);\n}\n\n/** Payload for storage mutation operations. SDK defines specific operations. */\nexport type MutateStoragePayload<T = unknown> =\n  | { operation: \"update-block-data\"; value: T }\n  | { operation: \"update-plugin-data\"; pluginId: PluginHandle; value: unknown };\n\n/**\n * Updates the data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param payload - The update payload with operation and value\n * @returns A new BlockStorage with updated data\n */\nexport function updateStorageData<TValue = unknown>(\n  storage: BlockStorage<TValue>,\n  payload: MutateStoragePayload<TValue>,\n): BlockStorage<TValue> {\n  switch (payload.operation) {\n    case \"update-block-data\":\n      return { ...storage, __data: payload.value };\n    case \"update-plugin-data\": {\n      const { pluginId, value } = payload;\n      const currentPlugins = storage.__plugins ?? {};\n      const existingEntry = currentPlugins[pluginId];\n      const version = existingEntry?.__dataVersion ?? DATA_MODEL_LEGACY_VERSION;\n      return {\n        ...storage,\n        __plugins: {\n          ...currentPlugins,\n          [pluginId]: {\n            __dataVersion: version,\n            __data: value,\n          },\n        },\n      };\n    }\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n// =============================================================================\n// Atomic Migration\n// =============================================================================\n\n/**\n * Result of a successful atomic migration.\n */\nexport interface MigrationSuccess<TState> {\n  success: true;\n  /** The fully migrated storage - commit this to persist */\n  storage: BlockStorage<TState>;\n}\n\n/**\n * Result of a failed atomic migration.\n * The original storage is untouched - user must choose to abort or reset.\n */\nexport interface MigrationFailure {\n  success: false;\n  /** Description of what failed */\n  error: string;\n  /** Which step failed: 'block' or pluginId */\n  failedAt: string;\n}\n\nexport type MigrationResult<TState> = MigrationSuccess<TState> | MigrationFailure;\n\n/**\n * Configuration for atomic block storage migration.\n * Callbacks use DataVersioned format (the DataModel API format).\n * Conversion to internal VersionedData format is handled by migrateBlockStorage().\n */\nexport interface MigrateBlockStorageConfig {\n  /** Migrate block data from any version to latest. Returns migrated data and transfers. */\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {\n    transfers: TransferRecord;\n  };\n  /** Migrate each plugin's data. Return undefined to remove the plugin. Throws on failure. */\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  /** The new plugin registry after migration (pluginId -> pluginName) */\n  newPluginRegistry: PluginRegistry;\n  /** Factory to create initial data for new plugins. Transfer is provided when a\n   *  .transfer() was defined for this plugin in the block's migration chain. */\n  createPluginData: (\n    handle: PluginHandle,\n    transfer?: DataVersioned<unknown>,\n  ) => DataVersioned<unknown>;\n}\n\n/**\n * Performs atomic migration of block storage including block data and all plugins.\n *\n * Migration is atomic: either everything succeeds and a new storage is returned,\n * or an error is returned and the original storage is completely untouched.\n *\n * Migration steps:\n * 1. Migrate block data\n * 2. For each plugin in newPluginRegistry:\n *    - If plugin exists with same name: migrate its data\n *    - Otherwise (new or type changed): create with initial data\n *    Plugins not in newPluginRegistry are dropped.\n *\n * If any step throws, migration fails and original storage is preserved.\n * User can then choose to:\n * - Abort: keep original storage, don't update block\n * - Reset: call createBlockStorage() to start fresh\n *\n * @param storage - The original storage (will not be modified)\n * @param config - Migration configuration\n * @returns Migration result - either success with new storage, or failure with error info\n *\n * @example\n * const result = migrateBlockStorage(storage, {\n *   migrateBlockData: (versioned) => blockDataModel.migrate(versioned),\n *   migratePluginData: (pluginId, versioned) => getPluginModel(pluginId).migrate(versioned),\n *   newPluginRegistry: { table1: 'dataTable' as PluginName },\n *   createPluginData: (pluginId) => getPluginModel(pluginId).getDefaultData(),\n * });\n *\n * if (result.success) {\n *   commitStorage(result.storage);\n * } else {\n *   const userChoice = await askUser(`Migration failed: ${result.error}. Reset data?`);\n *   if (userChoice === 'reset') {\n *     commitStorage(createBlockStorage(initialData, currentVersion));\n *   }\n *   // else: abort, keep original\n * }\n */\nexport function migrateBlockStorage(\n  storage: BlockStorage<unknown>,\n  config: MigrateBlockStorageConfig,\n): MigrationResult<unknown> {\n  const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config;\n\n  // Step 1: Migrate block data and collect transfers\n  let migratedData: unknown;\n  let newVersion: string;\n  let transfers: TransferRecord;\n  try {\n    const result = migrateBlockData({ version: storage.__dataVersion, data: storage.__data });\n    migratedData = result.data;\n    newVersion = result.version;\n    transfers = result.transfers;\n  } catch (error) {\n    return {\n      success: false,\n      error: error instanceof Error ? error.message : String(error),\n      failedAt: \"block\",\n    };\n  }\n\n  // Step 2: Migrate plugins\n  const oldPlugins = storage.__plugins ?? {};\n  const oldRegistry = storage.__pluginRegistry ?? {};\n  const newPlugins: Record<PluginHandle, VersionedData<unknown>> = {};\n\n  for (const [key, pluginName] of Object.entries(newPluginRegistry)) {\n    const handle = key as PluginHandle;\n    const existingEntry = oldPlugins[handle];\n    const existingName = oldRegistry[handle];\n\n    try {\n      if (existingEntry && existingName === pluginName) {\n        // Plugin exists with same type - migrate its data\n        const migrated = migratePluginData(handle, {\n          version: existingEntry.__dataVersion,\n          data: existingEntry.__data,\n        });\n        if (migrated) {\n          newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };\n        }\n        // If undefined returned, plugin is intentionally removed\n      } else if (existingEntry) {\n        // Plugin type changed — pass old data with DATA_MODEL_LEGACY_VERSION.\n        // If the new plugin has upgradeLegacy(), it migrates the old data.\n        // If not, defaultRecover throws DataUnrecoverableError → fall back to init.\n        let recovered = false;\n        try {\n          const migrated = migratePluginData(handle, {\n            version: DATA_MODEL_LEGACY_VERSION,\n            data: existingEntry.__data,\n          });\n          if (migrated) {\n            newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };\n            recovered = true;\n          }\n        } catch (recoverError) {\n          if (!isDataUnrecoverableError(recoverError)) throw recoverError;\n        }\n        if (!recovered) {\n          const transfer = transfers[handle];\n          const initial = createPluginData(handle, transfer);\n          newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n        }\n      } else {\n        // New plugin - create with initial data, passing transfer if available\n        const transfer = transfers[handle];\n        const initial = createPluginData(handle, transfer);\n        newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n      }\n    } catch (error) {\n      return {\n        success: false,\n        error: error instanceof Error ? error.message : String(error),\n        failedAt: handle,\n      };\n    }\n  }\n\n  // Step 3: Build final storage atomically\n  const migratedStorage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: newVersion,\n    __data: migratedData,\n    __pluginRegistry: newPluginRegistry,\n    __plugins: newPlugins,\n  };\n\n  return {\n    success: true,\n    storage: migratedStorage,\n  };\n}\n\n/**\n * Gets plugin-specific data from block storage.\n * Accepts raw storage (any format) and normalizes internally.\n *\n * When called with a typed PluginHandle<F>, the return type is automatically\n * inferred from the factory's phantom `__types.data` field.\n *\n * @param rawStorage - Raw block storage (may be legacy format or BlockStorage)\n * @param handle - The plugin handle (branded plugin instance id)\n * @returns The plugin data, typed via factory inference\n * @throws If plugin is not found in storage\n */\nexport function getPluginData<F extends PluginFactoryLike>(\n  rawStorage: unknown,\n  handle: PluginHandle<F>,\n): InferFactoryData<F> {\n  const storage = normalizeBlockStorage(rawStorage);\n  const pluginEntry = storage.__plugins?.[handle];\n  if (!pluginEntry) throw new Error(`Plugin '${handle}' not found in block storage`);\n  return pluginEntry.__data as InferFactoryData<F>;\n}\n"],"mappings":"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"}

package/dist/block_storage_callbacks.cjs

@@ -1,7 +1,6 @@
-const require_runtime = require('./_virtual/_rolldown/runtime.cjs');
-const require_block_storage = require('./block_storage.cjs');
+require("./_virtual/_rolldown/runtime.cjs");
+const require_block_storage = require("./block_storage.cjs");
 let _milaboratories_pl_model_common = require("@milaboratories/pl-model-common");
-
 //#region src/block_storage_callbacks.ts
 /**
 * BlockStorage Callback Implementations - wired to facade callbacks in BlockModelV3.done().
@@ -133,7 +132,7 @@ function createInitialStorage(hooks) {
 		};
 	}
 	return (0, _milaboratories_pl_model_common.stringifyJson)({
-		[require_block_storage.BLOCK_STORAGE_KEY]: require_block_storage.BLOCK_STORAGE_SCHEMA_VERSION,
+		[require_block_storage.BLOCK_STORAGE_KEY]: "v1",
 		__dataVersion: blockDefault.version,
 		__data: blockDefault.data,
 		__pluginRegistry: pluginRegistry,
@@ -178,7 +177,6 @@ function derivePrerunArgsFromStorage(storageJson, argsFunction, prerunArgsFuncti
 		return { error: `args() threw (fallback): ${e instanceof Error ? e.message : String(e)}` };
 	}
 }
-
 //#endregion
 exports.applyStorageUpdate = applyStorageUpdate;
 exports.createInitialStorage = createInitialStorage;
@@ -186,4 +184,5 @@ exports.deriveArgsFromStorage = deriveArgsFromStorage;
 exports.derivePrerunArgsFromStorage = derivePrerunArgsFromStorage;
 exports.getStorageDebugView = getStorageDebugView;
 exports.migrateStorage = migrateStorage;
+
 //# sourceMappingURL=block_storage_callbacks.cjs.map

package/dist/block_storage_callbacks.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage_callbacks.cjs","names":["createBlockStorage","isBlockStorage","normalizeBlockStorage","getStorageData","updateStorageData","migrateBlockStorage","BLOCK_STORAGE_KEY","BLOCK_STORAGE_SCHEMA_VERSION"],"sources":["../src/block_storage_callbacks.ts"],"sourcesContent":["/**\n * BlockStorage Callback Implementations - wired to facade callbacks in BlockModelV3.done().\n *\n * Provides pure functions for storage operations (migration, initialization,\n * args derivation, updates, debug views). Each function takes its dependencies\n * explicitly as parameters.\n *\n * @module block_storage_callbacks\n * @internal\n */\n\nimport {\n  BLOCK_STORAGE_KEY,\n  BLOCK_STORAGE_SCHEMA_VERSION,\n  type BlockStorage,\n  type MutateStoragePayload,\n  type PluginRegistry,\n  type VersionedData,\n  createBlockStorage,\n  getStorageData,\n  isBlockStorage,\n  migrateBlockStorage,\n  normalizeBlockStorage,\n  updateStorageData,\n} from \"./block_storage\";\nimport type { PluginHandle } from \"./plugin_handle\";\n\nimport { stringifyJson, type StringifiedJson } from \"@milaboratories/pl-model-common\";\nimport type { DataVersioned, TransferRecord } from \"./block_migrations\";\nimport type { StorageDebugView } from \"@milaboratories/pl-model-middle-layer\";\n\n// =============================================================================\n// Hook interfaces for dependency injection\n// =============================================================================\n\n/** Dependencies for storage migration */\nexport interface MigrationHooks {\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {\n    transfers: TransferRecord;\n  };\n  getPluginRegistry: () => PluginRegistry;\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  createPluginData: (\n    handle: PluginHandle,\n    transfer?: DataVersioned<unknown>,\n  ) => DataVersioned<unknown>;\n}\n\n/** Dependencies for initial storage creation */\nexport interface InitialStorageHooks {\n  getDefaultBlockData: () => DataVersioned<unknown>;\n  getPluginRegistry: () => PluginRegistry;\n  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;\n}\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 payload - Update payload with operation type and value\n * @returns Updated storage as StringifiedJson<BlockStorage>\n */\nexport function applyStorageUpdate(\n  currentStorageJson: string,\n  payload: MutateStoragePayload,\n): StringifiedJson<BlockStorage> {\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 stringifyJson(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// Facade Callback Implementations\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 */\nexport function 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// =============================================================================\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: StringifiedJson<BlockStorage>, info: string } - migration succeeded\n */\nexport type MigrationResult =\n  | { error: string }\n  | { error?: undefined; newStorageJson: StringifiedJson<BlockStorage>; info: string };\n\n/**\n * Runs storage migration using the provided hooks.\n * This is the main entry point for the middle layer to trigger migrations.\n *\n * @param currentStorageJson - Current storage as JSON string (or undefined)\n * @param hooks - Migration dependencies (block/plugin data migration and creation functions)\n * @returns MigrationResult\n */\nexport function migrateStorage(\n  currentStorageJson: string | undefined,\n  hooks: MigrationHooks,\n): MigrationResult {\n  // Normalize current storage\n  const { storage: currentStorage } = normalizeStorage(currentStorageJson);\n\n  const newPluginRegistry = hooks.getPluginRegistry();\n\n  // Perform atomic migration of block + all plugins\n  const migrationResult = migrateBlockStorage(currentStorage, {\n    migrateBlockData: hooks.migrateBlockData,\n    migratePluginData: hooks.migratePluginData,\n    newPluginRegistry,\n    createPluginData: hooks.createPluginData,\n  });\n\n  if (!migrationResult.success) {\n    return {\n      error: `Migration failed at '${migrationResult.failedAt}': ${migrationResult.error}`,\n    };\n  }\n\n  // Build info message\n  const oldVersion = currentStorage.__dataVersion;\n  const newVersion = migrationResult.storage.__dataVersion;\n  const info =\n    oldVersion === newVersion\n      ? `No migration needed (${oldVersion})`\n      : `Migrated ${oldVersion} -> ${newVersion}`;\n\n  return {\n    newStorageJson: stringifyJson(migrationResult.storage),\n    info,\n  };\n}\n\n// =============================================================================\n// Initial Storage Creation\n// =============================================================================\n\n/**\n * Creates complete initial storage (block data + all plugin data) atomically.\n *\n * @param hooks - Dependencies for creating initial block and plugin data\n * @returns Initial storage as branded JSON string\n * @throws If initialDataFn or createPluginData throws\n */\nexport function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage> {\n  const blockDefault = hooks.getDefaultBlockData();\n  const pluginRegistry = hooks.getPluginRegistry();\n\n  const plugins: Record<PluginHandle, VersionedData<unknown>> = {};\n  for (const handle of Object.keys(pluginRegistry) as PluginHandle[]) {\n    const initial = hooks.createPluginData(handle);\n    plugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n  }\n\n  const storage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: blockDefault.version,\n    __data: blockDefault.data,\n    __pluginRegistry: pluginRegistry,\n    __plugins: plugins,\n  };\n  return stringifyJson(storage);\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 = { error: string } | { error?: undefined; value: unknown };\n\n/**\n * Derives args from storage using the provided args function.\n * This extracts data from storage and passes it to the block's args() function.\n *\n * @param storageJson - Storage as JSON string\n * @param argsFunction - The block's args derivation function\n * @returns ArgsDeriveResult with derived args or error\n */\nexport function deriveArgsFromStorage(\n  storageJson: string,\n  argsFunction: (data: unknown) => unknown,\n): ArgsDeriveResult {\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Call the args function with extracted data\n  try {\n    const result = argsFunction(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/**\n * Derives prerunArgs from storage.\n * Uses prerunArgsFunction if provided, otherwise falls back to argsFunction.\n *\n * @param storageJson - Storage as JSON string\n * @param argsFunction - The block's args derivation function (fallback)\n * @param prerunArgsFunction - Optional prerun args derivation function\n * @returns ArgsDeriveResult with derived prerunArgs or error\n */\nexport function derivePrerunArgsFromStorage(\n  storageJson: string,\n  argsFunction: (data: unknown) => unknown,\n  prerunArgsFunction?: (data: unknown) => unknown,\n): ArgsDeriveResult {\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Try prerunArgs function first if available\n  if (prerunArgsFunction) {\n    try {\n      const result = prerunArgsFunction(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 function\n  try {\n    const result = argsFunction(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// Export discriminator key and schema version for external checks\nexport { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION };\n"],"mappings":"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"}
+{"version":3,"file":"block_storage_callbacks.cjs","names":["createBlockStorage","isBlockStorage","normalizeBlockStorage","getStorageData","updateStorageData","migrateBlockStorage","BLOCK_STORAGE_KEY"],"sources":["../src/block_storage_callbacks.ts"],"sourcesContent":["/**\n * BlockStorage Callback Implementations - wired to facade callbacks in BlockModelV3.done().\n *\n * Provides pure functions for storage operations (migration, initialization,\n * args derivation, updates, debug views). Each function takes its dependencies\n * explicitly as parameters.\n *\n * @module block_storage_callbacks\n * @internal\n */\n\nimport {\n  BLOCK_STORAGE_KEY,\n  BLOCK_STORAGE_SCHEMA_VERSION,\n  type BlockStorage,\n  type MutateStoragePayload,\n  type PluginRegistry,\n  type VersionedData,\n  createBlockStorage,\n  getStorageData,\n  isBlockStorage,\n  migrateBlockStorage,\n  normalizeBlockStorage,\n  updateStorageData,\n} from \"./block_storage\";\nimport type { PluginHandle } from \"./plugin_handle\";\n\nimport { stringifyJson, type StringifiedJson } from \"@milaboratories/pl-model-common\";\nimport type { DataVersioned, TransferRecord } from \"./block_migrations\";\nimport type { StorageDebugView } from \"@milaboratories/pl-model-middle-layer\";\n\n// =============================================================================\n// Hook interfaces for dependency injection\n// =============================================================================\n\n/** Dependencies for storage migration */\nexport interface MigrationHooks {\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {\n    transfers: TransferRecord;\n  };\n  getPluginRegistry: () => PluginRegistry;\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  createPluginData: (\n    handle: PluginHandle,\n    transfer?: DataVersioned<unknown>,\n  ) => DataVersioned<unknown>;\n}\n\n/** Dependencies for initial storage creation */\nexport interface InitialStorageHooks {\n  getDefaultBlockData: () => DataVersioned<unknown>;\n  getPluginRegistry: () => PluginRegistry;\n  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;\n}\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 payload - Update payload with operation type and value\n * @returns Updated storage as StringifiedJson<BlockStorage>\n */\nexport function applyStorageUpdate(\n  currentStorageJson: string,\n  payload: MutateStoragePayload,\n): StringifiedJson<BlockStorage> {\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 stringifyJson(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// Facade Callback Implementations\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 */\nexport function 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// =============================================================================\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: StringifiedJson<BlockStorage>, info: string } - migration succeeded\n */\nexport type MigrationResult =\n  | { error: string }\n  | { error?: undefined; newStorageJson: StringifiedJson<BlockStorage>; info: string };\n\n/**\n * Runs storage migration using the provided hooks.\n * This is the main entry point for the middle layer to trigger migrations.\n *\n * @param currentStorageJson - Current storage as JSON string (or undefined)\n * @param hooks - Migration dependencies (block/plugin data migration and creation functions)\n * @returns MigrationResult\n */\nexport function migrateStorage(\n  currentStorageJson: string | undefined,\n  hooks: MigrationHooks,\n): MigrationResult {\n  // Normalize current storage\n  const { storage: currentStorage } = normalizeStorage(currentStorageJson);\n\n  const newPluginRegistry = hooks.getPluginRegistry();\n\n  // Perform atomic migration of block + all plugins\n  const migrationResult = migrateBlockStorage(currentStorage, {\n    migrateBlockData: hooks.migrateBlockData,\n    migratePluginData: hooks.migratePluginData,\n    newPluginRegistry,\n    createPluginData: hooks.createPluginData,\n  });\n\n  if (!migrationResult.success) {\n    return {\n      error: `Migration failed at '${migrationResult.failedAt}': ${migrationResult.error}`,\n    };\n  }\n\n  // Build info message\n  const oldVersion = currentStorage.__dataVersion;\n  const newVersion = migrationResult.storage.__dataVersion;\n  const info =\n    oldVersion === newVersion\n      ? `No migration needed (${oldVersion})`\n      : `Migrated ${oldVersion} -> ${newVersion}`;\n\n  return {\n    newStorageJson: stringifyJson(migrationResult.storage),\n    info,\n  };\n}\n\n// =============================================================================\n// Initial Storage Creation\n// =============================================================================\n\n/**\n * Creates complete initial storage (block data + all plugin data) atomically.\n *\n * @param hooks - Dependencies for creating initial block and plugin data\n * @returns Initial storage as branded JSON string\n * @throws If initialDataFn or createPluginData throws\n */\nexport function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage> {\n  const blockDefault = hooks.getDefaultBlockData();\n  const pluginRegistry = hooks.getPluginRegistry();\n\n  const plugins: Record<PluginHandle, VersionedData<unknown>> = {};\n  for (const handle of Object.keys(pluginRegistry) as PluginHandle[]) {\n    const initial = hooks.createPluginData(handle);\n    plugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n  }\n\n  const storage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: blockDefault.version,\n    __data: blockDefault.data,\n    __pluginRegistry: pluginRegistry,\n    __plugins: plugins,\n  };\n  return stringifyJson(storage);\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 = { error: string } | { error?: undefined; value: unknown };\n\n/**\n * Derives args from storage using the provided args function.\n * This extracts data from storage and passes it to the block's args() function.\n *\n * @param storageJson - Storage as JSON string\n * @param argsFunction - The block's args derivation function\n * @returns ArgsDeriveResult with derived args or error\n */\nexport function deriveArgsFromStorage(\n  storageJson: string,\n  argsFunction: (data: unknown) => unknown,\n): ArgsDeriveResult {\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Call the args function with extracted data\n  try {\n    const result = argsFunction(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/**\n * Derives prerunArgs from storage.\n * Uses prerunArgsFunction if provided, otherwise falls back to argsFunction.\n *\n * @param storageJson - Storage as JSON string\n * @param argsFunction - The block's args derivation function (fallback)\n * @param prerunArgsFunction - Optional prerun args derivation function\n * @returns ArgsDeriveResult with derived prerunArgs or error\n */\nexport function derivePrerunArgsFromStorage(\n  storageJson: string,\n  argsFunction: (data: unknown) => unknown,\n  prerunArgsFunction?: (data: unknown) => unknown,\n): ArgsDeriveResult {\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Try prerunArgs function first if available\n  if (prerunArgsFunction) {\n    try {\n      const result = prerunArgsFunction(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 function\n  try {\n    const result = argsFunction(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// Export discriminator key and schema version for external checks\nexport { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION };\n"],"mappings":"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"}

package/dist/block_storage_callbacks.js

@@ -1,6 +1,5 @@
-import { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION, createBlockStorage, getStorageData, isBlockStorage, migrateBlockStorage, normalizeBlockStorage, updateStorageData } from "./block_storage.js";
+import { BLOCK_STORAGE_KEY, createBlockStorage, getStorageData, isBlockStorage, migrateBlockStorage, normalizeBlockStorage, updateStorageData } from "./block_storage.js";
 import { stringifyJson } from "@milaboratories/pl-model-common";
-
 //#region src/block_storage_callbacks.ts
 /**
 * BlockStorage Callback Implementations - wired to facade callbacks in BlockModelV3.done().
@@ -132,7 +131,7 @@ function createInitialStorage(hooks) {
 		};
 	}
 	return stringifyJson({
-		[BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
+		[BLOCK_STORAGE_KEY]: "v1",
 		__dataVersion: blockDefault.version,
 		__data: blockDefault.data,
 		__pluginRegistry: pluginRegistry,
@@ -177,7 +176,7 @@ function derivePrerunArgsFromStorage(storageJson, argsFunction, prerunArgsFuncti
 		return { error: `args() threw (fallback): ${e instanceof Error ? e.message : String(e)}` };
 	}
 }
-
 //#endregion
 export { applyStorageUpdate, createInitialStorage, deriveArgsFromStorage, derivePrerunArgsFromStorage, getStorageDebugView, migrateStorage };
+
 //# sourceMappingURL=block_storage_callbacks.js.map

package/dist/block_storage_callbacks.js.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage_callbacks.js","names":[],"sources":["../src/block_storage_callbacks.ts"],"sourcesContent":["/**\n * BlockStorage Callback Implementations - wired to facade callbacks in BlockModelV3.done().\n *\n * Provides pure functions for storage operations (migration, initialization,\n * args derivation, updates, debug views). Each function takes its dependencies\n * explicitly as parameters.\n *\n * @module block_storage_callbacks\n * @internal\n */\n\nimport {\n  BLOCK_STORAGE_KEY,\n  BLOCK_STORAGE_SCHEMA_VERSION,\n  type BlockStorage,\n  type MutateStoragePayload,\n  type PluginRegistry,\n  type VersionedData,\n  createBlockStorage,\n  getStorageData,\n  isBlockStorage,\n  migrateBlockStorage,\n  normalizeBlockStorage,\n  updateStorageData,\n} from \"./block_storage\";\nimport type { PluginHandle } from \"./plugin_handle\";\n\nimport { stringifyJson, type StringifiedJson } from \"@milaboratories/pl-model-common\";\nimport type { DataVersioned, TransferRecord } from \"./block_migrations\";\nimport type { StorageDebugView } from \"@milaboratories/pl-model-middle-layer\";\n\n// =============================================================================\n// Hook interfaces for dependency injection\n// =============================================================================\n\n/** Dependencies for storage migration */\nexport interface MigrationHooks {\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {\n    transfers: TransferRecord;\n  };\n  getPluginRegistry: () => PluginRegistry;\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  createPluginData: (\n    handle: PluginHandle,\n    transfer?: DataVersioned<unknown>,\n  ) => DataVersioned<unknown>;\n}\n\n/** Dependencies for initial storage creation */\nexport interface InitialStorageHooks {\n  getDefaultBlockData: () => DataVersioned<unknown>;\n  getPluginRegistry: () => PluginRegistry;\n  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;\n}\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 payload - Update payload with operation type and value\n * @returns Updated storage as StringifiedJson<BlockStorage>\n */\nexport function applyStorageUpdate(\n  currentStorageJson: string,\n  payload: MutateStoragePayload,\n): StringifiedJson<BlockStorage> {\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 stringifyJson(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// Facade Callback Implementations\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 */\nexport function 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// =============================================================================\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: StringifiedJson<BlockStorage>, info: string } - migration succeeded\n */\nexport type MigrationResult =\n  | { error: string }\n  | { error?: undefined; newStorageJson: StringifiedJson<BlockStorage>; info: string };\n\n/**\n * Runs storage migration using the provided hooks.\n * This is the main entry point for the middle layer to trigger migrations.\n *\n * @param currentStorageJson - Current storage as JSON string (or undefined)\n * @param hooks - Migration dependencies (block/plugin data migration and creation functions)\n * @returns MigrationResult\n */\nexport function migrateStorage(\n  currentStorageJson: string | undefined,\n  hooks: MigrationHooks,\n): MigrationResult {\n  // Normalize current storage\n  const { storage: currentStorage } = normalizeStorage(currentStorageJson);\n\n  const newPluginRegistry = hooks.getPluginRegistry();\n\n  // Perform atomic migration of block + all plugins\n  const migrationResult = migrateBlockStorage(currentStorage, {\n    migrateBlockData: hooks.migrateBlockData,\n    migratePluginData: hooks.migratePluginData,\n    newPluginRegistry,\n    createPluginData: hooks.createPluginData,\n  });\n\n  if (!migrationResult.success) {\n    return {\n      error: `Migration failed at '${migrationResult.failedAt}': ${migrationResult.error}`,\n    };\n  }\n\n  // Build info message\n  const oldVersion = currentStorage.__dataVersion;\n  const newVersion = migrationResult.storage.__dataVersion;\n  const info =\n    oldVersion === newVersion\n      ? `No migration needed (${oldVersion})`\n      : `Migrated ${oldVersion} -> ${newVersion}`;\n\n  return {\n    newStorageJson: stringifyJson(migrationResult.storage),\n    info,\n  };\n}\n\n// =============================================================================\n// Initial Storage Creation\n// =============================================================================\n\n/**\n * Creates complete initial storage (block data + all plugin data) atomically.\n *\n * @param hooks - Dependencies for creating initial block and plugin data\n * @returns Initial storage as branded JSON string\n * @throws If initialDataFn or createPluginData throws\n */\nexport function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage> {\n  const blockDefault = hooks.getDefaultBlockData();\n  const pluginRegistry = hooks.getPluginRegistry();\n\n  const plugins: Record<PluginHandle, VersionedData<unknown>> = {};\n  for (const handle of Object.keys(pluginRegistry) as PluginHandle[]) {\n    const initial = hooks.createPluginData(handle);\n    plugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n  }\n\n  const storage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: blockDefault.version,\n    __data: blockDefault.data,\n    __pluginRegistry: pluginRegistry,\n    __plugins: plugins,\n  };\n  return stringifyJson(storage);\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 = { error: string } | { error?: undefined; value: unknown };\n\n/**\n * Derives args from storage using the provided args function.\n * This extracts data from storage and passes it to the block's args() function.\n *\n * @param storageJson - Storage as JSON string\n * @param argsFunction - The block's args derivation function\n * @returns ArgsDeriveResult with derived args or error\n */\nexport function deriveArgsFromStorage(\n  storageJson: string,\n  argsFunction: (data: unknown) => unknown,\n): ArgsDeriveResult {\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Call the args function with extracted data\n  try {\n    const result = argsFunction(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/**\n * Derives prerunArgs from storage.\n * Uses prerunArgsFunction if provided, otherwise falls back to argsFunction.\n *\n * @param storageJson - Storage as JSON string\n * @param argsFunction - The block's args derivation function (fallback)\n * @param prerunArgsFunction - Optional prerun args derivation function\n * @returns ArgsDeriveResult with derived prerunArgs or error\n */\nexport function derivePrerunArgsFromStorage(\n  storageJson: string,\n  argsFunction: (data: unknown) => unknown,\n  prerunArgsFunction?: (data: unknown) => unknown,\n): ArgsDeriveResult {\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Try prerunArgs function first if available\n  if (prerunArgsFunction) {\n    try {\n      const result = prerunArgsFunction(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 function\n  try {\n    const result = argsFunction(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// Export discriminator key and schema version for external checks\nexport { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION };\n"],"mappings":"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"}
+{"version":3,"file":"block_storage_callbacks.js","names":[],"sources":["../src/block_storage_callbacks.ts"],"sourcesContent":["/**\n * BlockStorage Callback Implementations - wired to facade callbacks in BlockModelV3.done().\n *\n * Provides pure functions for storage operations (migration, initialization,\n * args derivation, updates, debug views). Each function takes its dependencies\n * explicitly as parameters.\n *\n * @module block_storage_callbacks\n * @internal\n */\n\nimport {\n  BLOCK_STORAGE_KEY,\n  BLOCK_STORAGE_SCHEMA_VERSION,\n  type BlockStorage,\n  type MutateStoragePayload,\n  type PluginRegistry,\n  type VersionedData,\n  createBlockStorage,\n  getStorageData,\n  isBlockStorage,\n  migrateBlockStorage,\n  normalizeBlockStorage,\n  updateStorageData,\n} from \"./block_storage\";\nimport type { PluginHandle } from \"./plugin_handle\";\n\nimport { stringifyJson, type StringifiedJson } from \"@milaboratories/pl-model-common\";\nimport type { DataVersioned, TransferRecord } from \"./block_migrations\";\nimport type { StorageDebugView } from \"@milaboratories/pl-model-middle-layer\";\n\n// =============================================================================\n// Hook interfaces for dependency injection\n// =============================================================================\n\n/** Dependencies for storage migration */\nexport interface MigrationHooks {\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {\n    transfers: TransferRecord;\n  };\n  getPluginRegistry: () => PluginRegistry;\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  createPluginData: (\n    handle: PluginHandle,\n    transfer?: DataVersioned<unknown>,\n  ) => DataVersioned<unknown>;\n}\n\n/** Dependencies for initial storage creation */\nexport interface InitialStorageHooks {\n  getDefaultBlockData: () => DataVersioned<unknown>;\n  getPluginRegistry: () => PluginRegistry;\n  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;\n}\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 payload - Update payload with operation type and value\n * @returns Updated storage as StringifiedJson<BlockStorage>\n */\nexport function applyStorageUpdate(\n  currentStorageJson: string,\n  payload: MutateStoragePayload,\n): StringifiedJson<BlockStorage> {\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 stringifyJson(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// Facade Callback Implementations\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 */\nexport function 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// =============================================================================\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: StringifiedJson<BlockStorage>, info: string } - migration succeeded\n */\nexport type MigrationResult =\n  | { error: string }\n  | { error?: undefined; newStorageJson: StringifiedJson<BlockStorage>; info: string };\n\n/**\n * Runs storage migration using the provided hooks.\n * This is the main entry point for the middle layer to trigger migrations.\n *\n * @param currentStorageJson - Current storage as JSON string (or undefined)\n * @param hooks - Migration dependencies (block/plugin data migration and creation functions)\n * @returns MigrationResult\n */\nexport function migrateStorage(\n  currentStorageJson: string | undefined,\n  hooks: MigrationHooks,\n): MigrationResult {\n  // Normalize current storage\n  const { storage: currentStorage } = normalizeStorage(currentStorageJson);\n\n  const newPluginRegistry = hooks.getPluginRegistry();\n\n  // Perform atomic migration of block + all plugins\n  const migrationResult = migrateBlockStorage(currentStorage, {\n    migrateBlockData: hooks.migrateBlockData,\n    migratePluginData: hooks.migratePluginData,\n    newPluginRegistry,\n    createPluginData: hooks.createPluginData,\n  });\n\n  if (!migrationResult.success) {\n    return {\n      error: `Migration failed at '${migrationResult.failedAt}': ${migrationResult.error}`,\n    };\n  }\n\n  // Build info message\n  const oldVersion = currentStorage.__dataVersion;\n  const newVersion = migrationResult.storage.__dataVersion;\n  const info =\n    oldVersion === newVersion\n      ? `No migration needed (${oldVersion})`\n      : `Migrated ${oldVersion} -> ${newVersion}`;\n\n  return {\n    newStorageJson: stringifyJson(migrationResult.storage),\n    info,\n  };\n}\n\n// =============================================================================\n// Initial Storage Creation\n// =============================================================================\n\n/**\n * Creates complete initial storage (block data + all plugin data) atomically.\n *\n * @param hooks - Dependencies for creating initial block and plugin data\n * @returns Initial storage as branded JSON string\n * @throws If initialDataFn or createPluginData throws\n */\nexport function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage> {\n  const blockDefault = hooks.getDefaultBlockData();\n  const pluginRegistry = hooks.getPluginRegistry();\n\n  const plugins: Record<PluginHandle, VersionedData<unknown>> = {};\n  for (const handle of Object.keys(pluginRegistry) as PluginHandle[]) {\n    const initial = hooks.createPluginData(handle);\n    plugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n  }\n\n  const storage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: blockDefault.version,\n    __data: blockDefault.data,\n    __pluginRegistry: pluginRegistry,\n    __plugins: plugins,\n  };\n  return stringifyJson(storage);\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 = { error: string } | { error?: undefined; value: unknown };\n\n/**\n * Derives args from storage using the provided args function.\n * This extracts data from storage and passes it to the block's args() function.\n *\n * @param storageJson - Storage as JSON string\n * @param argsFunction - The block's args derivation function\n * @returns ArgsDeriveResult with derived args or error\n */\nexport function deriveArgsFromStorage(\n  storageJson: string,\n  argsFunction: (data: unknown) => unknown,\n): ArgsDeriveResult {\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Call the args function with extracted data\n  try {\n    const result = argsFunction(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/**\n * Derives prerunArgs from storage.\n * Uses prerunArgsFunction if provided, otherwise falls back to argsFunction.\n *\n * @param storageJson - Storage as JSON string\n * @param argsFunction - The block's args derivation function (fallback)\n * @param prerunArgsFunction - Optional prerun args derivation function\n * @returns ArgsDeriveResult with derived prerunArgs or error\n */\nexport function derivePrerunArgsFromStorage(\n  storageJson: string,\n  argsFunction: (data: unknown) => unknown,\n  prerunArgsFunction?: (data: unknown) => unknown,\n): ArgsDeriveResult {\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Try prerunArgs function first if available\n  if (prerunArgsFunction) {\n    try {\n      const result = prerunArgsFunction(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 function\n  try {\n    const result = argsFunction(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// Export discriminator key and schema version for external checks\nexport { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION };\n"],"mappings":"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"}

package/dist/block_storage_facade.cjs

@@ -1,5 +1,4 @@
-const require_internal = require('./internal.cjs');
-
+const require_internal = require("./internal.cjs");
 //#region src/block_storage_facade.ts
 /**
 * The current facade version. This value is used for `requiresModelAPIVersion`
@@ -39,10 +38,10 @@ const BlockStorageFacadeHandles = createFacadeHandles(BlockStorageFacadeCallback
 function registerFacadeCallbacks(callbacks) {
 	for (const key of Object.values(BlockStorageFacadeCallbacks)) require_internal.tryRegisterCallback(key, callbacks[key]);
 }
-
 //#endregion
 exports.BLOCK_STORAGE_FACADE_VERSION = BLOCK_STORAGE_FACADE_VERSION;
 exports.BlockStorageFacadeCallbacks = BlockStorageFacadeCallbacks;
 exports.BlockStorageFacadeHandles = BlockStorageFacadeHandles;
 exports.registerFacadeCallbacks = registerFacadeCallbacks;
+
 //# sourceMappingURL=block_storage_facade.cjs.map

package/dist/block_storage_facade.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage_facade.cjs","names":["createRenderLambda"],"sources":["../src/block_storage_facade.ts"],"sourcesContent":["/**\n * Block Storage Facade - Contract between bundled blocks and middle layer.\n *\n * ============================================================================\n * VERSIONING\n * ============================================================================\n *\n * Blocks declare their model API version via the `requiresModelAPIVersion` feature flag\n * (see BlockCodeKnownFeatureFlags). This determines how the middle layer manages block state:\n *\n * - Version 1: Legacy BlockModel - state is {args, uiState}, managed directly by middle layer\n * - Version 2: BlockModelV3 - uses blockStorage with VM-based callbacks (this facade)\n *\n * This facade (BlockStorageFacade) is used by blocks with `requiresModelAPIVersion: 2`.\n * The version number matches the model API version for clarity.\n *\n * ============================================================================\n * BACKWARD COMPATIBILITY WARNING\n * ============================================================================\n *\n * This file documents the FACADE between the SDK (bundled into blocks) and the\n * middle layer. Once a block is published, its SDK version is frozen. The middle\n * layer must support ALL previously released callback signatures indefinitely.\n *\n * RULES:\n * 1. NEVER change the signature of existing callbacks\n * 2. NEVER remove existing callbacks\n * 3. New callbacks CAN be added (old blocks won't register them, middle layer\n *    should handle missing callbacks gracefully)\n * 4. Callback return types can be EXTENDED (add optional fields) but not changed\n * 5. Callback parameter types should remain compatible (middle layer may need\n *    to handle both old and new formats)\n *\n * The facade consists of callbacks registered via `tryRegisterCallback()` with\n * the `__pl_` prefix. These are registered by the SDK when a block loads and\n * called by the middle layer to perform operations.\n *\n * ============================================================================\n * WHAT CAN BE CHANGED FREELY\n * ============================================================================\n *\n * - Middle layer code (lib/node/pl-middle-layer)\n * - SDK internal implementation (as long as callback contracts are preserved)\n * - SDK exports used ONLY by middle layer (not by blocks themselves)\n * - New SDK features that don't affect existing callbacks\n *\n * @module block_storage_facade\n */\n\nimport type { MutateStoragePayload } from \"./block_storage\";\nimport type { ConfigRenderLambda } from \"./bconfig\";\nimport { createRenderLambda, tryRegisterCallback } from \"./internal\";\nimport type { StringifiedJson } from \"@milaboratories/pl-model-common\";\n\n// =============================================================================\n// Facade Version\n// =============================================================================\n\n/**\n * The current facade version. This value is used for `requiresModelAPIVersion`\n * feature flag in BlockModelV3.\n */\nexport const BLOCK_STORAGE_FACADE_VERSION = 2;\n\n// =============================================================================\n// Facade Callback Names\n// =============================================================================\n\n/**\n * All facade callback names as constants.\n * These are the source of truth - the interface is derived from these.\n *\n * IMPORTANT: When adding a new callback:\n * 1. Add the constant here\n * 2. Add the callback signature to FacadeCallbackTypes below\n * 3. The BlockStorageFacade type will automatically include it\n */\nexport const BlockStorageFacadeCallbacks = {\n  StorageApplyUpdate: \"__pl_storage_applyUpdate\",\n  StorageDebugView: \"__pl_storage_debugView\",\n  StorageMigrate: \"__pl_storage_migrate\",\n  ArgsDerive: \"__pl_args_derive\",\n  PrerunArgsDerive: \"__pl_prerunArgs_derive\",\n  StorageInitial: \"__pl_storage_initial\",\n} as const;\n\n/**\n * Creates a map of lambda handles from a callbacks constant object.\n * Keys are the callback string values (e.g., '__pl_storage_applyUpdate').\n */\nfunction createFacadeHandles<T extends Record<string, string>>(\n  callbacks: T,\n): { [K in T[keyof T]]: ConfigRenderLambda } {\n  return Object.fromEntries(\n    Object.values(callbacks).map((handle) => [handle, createRenderLambda({ handle })]),\n  ) as { [K in T[keyof T]]: ConfigRenderLambda };\n}\n\n/**\n * Lambda handles for facade callbacks.\n * Used by the middle layer to invoke callbacks via executeSingleLambda().\n */\nexport const BlockStorageFacadeHandles = createFacadeHandles(BlockStorageFacadeCallbacks);\n\n// =============================================================================\n// Facade Interface (source of truth for callback signatures)\n// =============================================================================\n\n/**\n * The complete facade interface between bundled blocks (SDK) and middle layer.\n *\n * This interface defines ALL callbacks that a block registers. The middle layer\n * calls these callbacks to perform storage operations.\n *\n * ALL types are inlined to simplify versioning - when a callback changes,\n * the entire signature is visible in one place.\n *\n * BACKWARD COMPATIBILITY:\n * - This interface can only be EXTENDED, never shrunk\n * - Existing callback signatures MUST NOT change\n * - Middle layer should use Partial<BlockStorageFacade> when dealing with\n *   blocks of unknown version (older blocks may not have all callbacks)\n *\n * Each callback is documented with:\n * - Purpose and when it's called\n * - Parameter descriptions\n * - Return value description\n */\nexport interface BlockStorageFacade {\n  /**\n   * Apply state update to storage.\n   * Called when UI updates block state (setState) or plugin data.\n   * @param currentStorageJson - Current storage as JSON string\n   * @param payload - Update payload with operation type and value\n   * @returns Updated storage as JSON string\n   */\n  [BlockStorageFacadeCallbacks.StorageApplyUpdate]: (\n    currentStorageJson: StringifiedJson,\n    payload: MutateStoragePayload,\n  ) => StringifiedJson;\n\n  /**\n   * Get debug view of storage.\n   * Called by developer tools to inspect storage state.\n   * @param storageJson - Storage as JSON string (or undefined for new blocks)\n   * @returns JSON string containing StorageDebugView\n   */\n  [BlockStorageFacadeCallbacks.StorageDebugView]: (\n    storageJson: StringifiedJson | undefined,\n  ) => StringifiedJson;\n\n  /**\n   * Run storage migration.\n   * Called when block loads to migrate data to latest version.\n   * @param currentStorageJson - Current storage as JSON string (or undefined for new blocks)\n   * @returns Migration result - either error or success with new storage\n   */\n  [BlockStorageFacadeCallbacks.StorageMigrate]: (currentStorageJson: StringifiedJson | undefined) =>\n    | { error: string }\n    | {\n        error?: undefined;\n        newStorageJson: StringifiedJson;\n        info: string;\n      };\n\n  /**\n   * Derive args from storage.\n   * Called to get block configuration args from storage.\n   * @param storageJson - Storage as JSON string\n   * @returns Args derivation result - either error or derived value\n   */\n  [BlockStorageFacadeCallbacks.ArgsDerive]: (\n    storageJson: StringifiedJson,\n  ) => { error: string } | { error?: undefined; value: unknown };\n\n  /**\n   * Derive prerunArgs from storage.\n   * Called to get prerun args; falls back to args callback if not registered.\n   * @param storageJson - Storage as JSON string\n   * @returns Args derivation result - either error or derived value\n   */\n  [BlockStorageFacadeCallbacks.PrerunArgsDerive]: (\n    storageJson: StringifiedJson,\n  ) => { error: string } | { error?: undefined; value: unknown };\n\n  /**\n   * Get initial storage JSON for new blocks.\n   * Called when creating a new block to get complete initial storage.\n   * @returns Initial storage as JSON string\n   */\n  [BlockStorageFacadeCallbacks.StorageInitial]: () => StringifiedJson;\n}\n\n/** Register all facade callbacks at once. Ensures all required callbacks are provided. */\nexport function registerFacadeCallbacks(callbacks: BlockStorageFacade): void {\n  for (const key of Object.values(BlockStorageFacadeCallbacks)) {\n    tryRegisterCallback(key, callbacks[key] as (...args: any[]) => any);\n  }\n}\n"],"mappings":";;;;;;;AA8DA,MAAa,+BAA+B;;;;;;;;;;AAe5C,MAAa,8BAA8B;CACzC,oBAAoB;CACpB,kBAAkB;CAClB,gBAAgB;CAChB,YAAY;CACZ,kBAAkB;CAClB,gBAAgB;CACjB;;;;;AAMD,SAAS,oBACP,WAC2C;AAC3C,QAAO,OAAO,YACZ,OAAO,OAAO,UAAU,CAAC,KAAK,WAAW,CAAC,QAAQA,oCAAmB,EAAE,QAAQ,CAAC,CAAC,CAAC,CACnF;;;;;;AAOH,MAAa,4BAA4B,oBAAoB,4BAA4B;;AA4FzF,SAAgB,wBAAwB,WAAqC;AAC3E,MAAK,MAAM,OAAO,OAAO,OAAO,4BAA4B,CAC1D,sCAAoB,KAAK,UAAU,KAAgC"}
+{"version":3,"file":"block_storage_facade.cjs","names":["createRenderLambda"],"sources":["../src/block_storage_facade.ts"],"sourcesContent":["/**\n * Block Storage Facade - Contract between bundled blocks and middle layer.\n *\n * ============================================================================\n * VERSIONING\n * ============================================================================\n *\n * Blocks declare their model API version via the `requiresModelAPIVersion` feature flag\n * (see BlockCodeKnownFeatureFlags). This determines how the middle layer manages block state:\n *\n * - Version 1: Legacy BlockModel - state is {args, uiState}, managed directly by middle layer\n * - Version 2: BlockModelV3 - uses blockStorage with VM-based callbacks (this facade)\n *\n * This facade (BlockStorageFacade) is used by blocks with `requiresModelAPIVersion: 2`.\n * The version number matches the model API version for clarity.\n *\n * ============================================================================\n * BACKWARD COMPATIBILITY WARNING\n * ============================================================================\n *\n * This file documents the FACADE between the SDK (bundled into blocks) and the\n * middle layer. Once a block is published, its SDK version is frozen. The middle\n * layer must support ALL previously released callback signatures indefinitely.\n *\n * RULES:\n * 1. NEVER change the signature of existing callbacks\n * 2. NEVER remove existing callbacks\n * 3. New callbacks CAN be added (old blocks won't register them, middle layer\n *    should handle missing callbacks gracefully)\n * 4. Callback return types can be EXTENDED (add optional fields) but not changed\n * 5. Callback parameter types should remain compatible (middle layer may need\n *    to handle both old and new formats)\n *\n * The facade consists of callbacks registered via `tryRegisterCallback()` with\n * the `__pl_` prefix. These are registered by the SDK when a block loads and\n * called by the middle layer to perform operations.\n *\n * ============================================================================\n * WHAT CAN BE CHANGED FREELY\n * ============================================================================\n *\n * - Middle layer code (lib/node/pl-middle-layer)\n * - SDK internal implementation (as long as callback contracts are preserved)\n * - SDK exports used ONLY by middle layer (not by blocks themselves)\n * - New SDK features that don't affect existing callbacks\n *\n * @module block_storage_facade\n */\n\nimport type { MutateStoragePayload } from \"./block_storage\";\nimport type { ConfigRenderLambda } from \"./bconfig\";\nimport { createRenderLambda, tryRegisterCallback } from \"./internal\";\nimport type { StringifiedJson } from \"@milaboratories/pl-model-common\";\n\n// =============================================================================\n// Facade Version\n// =============================================================================\n\n/**\n * The current facade version. This value is used for `requiresModelAPIVersion`\n * feature flag in BlockModelV3.\n */\nexport const BLOCK_STORAGE_FACADE_VERSION = 2;\n\n// =============================================================================\n// Facade Callback Names\n// =============================================================================\n\n/**\n * All facade callback names as constants.\n * These are the source of truth - the interface is derived from these.\n *\n * IMPORTANT: When adding a new callback:\n * 1. Add the constant here\n * 2. Add the callback signature to FacadeCallbackTypes below\n * 3. The BlockStorageFacade type will automatically include it\n */\nexport const BlockStorageFacadeCallbacks = {\n  StorageApplyUpdate: \"__pl_storage_applyUpdate\",\n  StorageDebugView: \"__pl_storage_debugView\",\n  StorageMigrate: \"__pl_storage_migrate\",\n  ArgsDerive: \"__pl_args_derive\",\n  PrerunArgsDerive: \"__pl_prerunArgs_derive\",\n  StorageInitial: \"__pl_storage_initial\",\n} as const;\n\n/**\n * Creates a map of lambda handles from a callbacks constant object.\n * Keys are the callback string values (e.g., '__pl_storage_applyUpdate').\n */\nfunction createFacadeHandles<T extends Record<string, string>>(\n  callbacks: T,\n): { [K in T[keyof T]]: ConfigRenderLambda } {\n  return Object.fromEntries(\n    Object.values(callbacks).map((handle) => [handle, createRenderLambda({ handle })]),\n  ) as { [K in T[keyof T]]: ConfigRenderLambda };\n}\n\n/**\n * Lambda handles for facade callbacks.\n * Used by the middle layer to invoke callbacks via executeSingleLambda().\n */\nexport const BlockStorageFacadeHandles = createFacadeHandles(BlockStorageFacadeCallbacks);\n\n// =============================================================================\n// Facade Interface (source of truth for callback signatures)\n// =============================================================================\n\n/**\n * The complete facade interface between bundled blocks (SDK) and middle layer.\n *\n * This interface defines ALL callbacks that a block registers. The middle layer\n * calls these callbacks to perform storage operations.\n *\n * ALL types are inlined to simplify versioning - when a callback changes,\n * the entire signature is visible in one place.\n *\n * BACKWARD COMPATIBILITY:\n * - This interface can only be EXTENDED, never shrunk\n * - Existing callback signatures MUST NOT change\n * - Middle layer should use Partial<BlockStorageFacade> when dealing with\n *   blocks of unknown version (older blocks may not have all callbacks)\n *\n * Each callback is documented with:\n * - Purpose and when it's called\n * - Parameter descriptions\n * - Return value description\n */\nexport interface BlockStorageFacade {\n  /**\n   * Apply state update to storage.\n   * Called when UI updates block state (setState) or plugin data.\n   * @param currentStorageJson - Current storage as JSON string\n   * @param payload - Update payload with operation type and value\n   * @returns Updated storage as JSON string\n   */\n  [BlockStorageFacadeCallbacks.StorageApplyUpdate]: (\n    currentStorageJson: StringifiedJson,\n    payload: MutateStoragePayload,\n  ) => StringifiedJson;\n\n  /**\n   * Get debug view of storage.\n   * Called by developer tools to inspect storage state.\n   * @param storageJson - Storage as JSON string (or undefined for new blocks)\n   * @returns JSON string containing StorageDebugView\n   */\n  [BlockStorageFacadeCallbacks.StorageDebugView]: (\n    storageJson: StringifiedJson | undefined,\n  ) => StringifiedJson;\n\n  /**\n   * Run storage migration.\n   * Called when block loads to migrate data to latest version.\n   * @param currentStorageJson - Current storage as JSON string (or undefined for new blocks)\n   * @returns Migration result - either error or success with new storage\n   */\n  [BlockStorageFacadeCallbacks.StorageMigrate]: (currentStorageJson: StringifiedJson | undefined) =>\n    | { error: string }\n    | {\n        error?: undefined;\n        newStorageJson: StringifiedJson;\n        info: string;\n      };\n\n  /**\n   * Derive args from storage.\n   * Called to get block configuration args from storage.\n   * @param storageJson - Storage as JSON string\n   * @returns Args derivation result - either error or derived value\n   */\n  [BlockStorageFacadeCallbacks.ArgsDerive]: (\n    storageJson: StringifiedJson,\n  ) => { error: string } | { error?: undefined; value: unknown };\n\n  /**\n   * Derive prerunArgs from storage.\n   * Called to get prerun args; falls back to args callback if not registered.\n   * @param storageJson - Storage as JSON string\n   * @returns Args derivation result - either error or derived value\n   */\n  [BlockStorageFacadeCallbacks.PrerunArgsDerive]: (\n    storageJson: StringifiedJson,\n  ) => { error: string } | { error?: undefined; value: unknown };\n\n  /**\n   * Get initial storage JSON for new blocks.\n   * Called when creating a new block to get complete initial storage.\n   * @returns Initial storage as JSON string\n   */\n  [BlockStorageFacadeCallbacks.StorageInitial]: () => StringifiedJson;\n}\n\n/** Register all facade callbacks at once. Ensures all required callbacks are provided. */\nexport function registerFacadeCallbacks(callbacks: BlockStorageFacade): void {\n  for (const key of Object.values(BlockStorageFacadeCallbacks)) {\n    tryRegisterCallback(key, callbacks[key] as (...args: any[]) => any);\n  }\n}\n"],"mappings":";;;;;;AA8DA,MAAa,+BAA+B;;;;;;;;;;AAe5C,MAAa,8BAA8B;CACzC,oBAAoB;CACpB,kBAAkB;CAClB,gBAAgB;CAChB,YAAY;CACZ,kBAAkB;CAClB,gBAAgB;CACjB;;;;;AAMD,SAAS,oBACP,WAC2C;AAC3C,QAAO,OAAO,YACZ,OAAO,OAAO,UAAU,CAAC,KAAK,WAAW,CAAC,QAAQA,iBAAAA,mBAAmB,EAAE,QAAQ,CAAC,CAAC,CAAC,CACnF;;;;;;AAOH,MAAa,4BAA4B,oBAAoB,4BAA4B;;AA4FzF,SAAgB,wBAAwB,WAAqC;AAC3E,MAAK,MAAM,OAAO,OAAO,OAAO,4BAA4B,CAC1D,kBAAA,oBAAoB,KAAK,UAAU,KAAgC"}

package/dist/block_storage_facade.d.ts

@@ -1,6 +1,5 @@
 import { MutateStoragePayload } from "./block_storage.js";
 import { ConfigRenderLambda } from "./bconfig/lambdas.js";
-import "./bconfig/index.js";
 import { StringifiedJson } from "@milaboratories/pl-model-common";
 
 //#region src/block_storage_facade.d.ts

package/dist/block_storage_facade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_storage_facade.d.ts","names":[],"sources":["../src/block_storage_facade.ts"],"mappings":";;;;;;;;;cA8Da,4BAAA;;;;;;;;;;cAeA,2BAAA;EAAA;;;;;;;;;;;cAyBA,yBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA0BI,kBAAA;EAuDR;;;;;;;EAAA,CA/CN,2BAAA,CAA4B,kBAAA,IAC3B,kBAAA,EAAoB,eAAA,EACpB,OAAA,EAAS,oBAAA,KACN,eAAA;EAmD8D;AAIrE;;;;;EAJqE,CA3ClE,2BAAA,CAA4B,gBAAA,IAC3B,WAAA,EAAa,eAAA,iBACV,eAAA;;;;;;;GAQJ,2BAAA,CAA4B,cAAA,IAAkB,kBAAA,EAAoB,eAAA;IAC7D,KAAA;EAAA;IAEA,KAAA;IACA,cAAA,EAAgB,eAAA;IAChB,IAAA;EAAA;;;;;;;GASL,2BAAA,CAA4B,UAAA,IAC3B,WAAA,EAAa,eAAA;IACR,KAAA;EAAA;IAAoB,KAAA;IAAmB,KAAA;EAAA;;;;;;;GAQ7C,2BAAA,CAA4B,gBAAA,IAC3B,WAAA,EAAa,eAAA;IACR,KAAA;EAAA;IAAoB,KAAA;IAAmB,KAAA;EAAA;;;;;;GAO7C,2BAAA,CAA4B,cAAA,SAAuB,eAAA;AAAA;;iBAItC,uBAAA,CAAwB,SAAA,EAAW,kBAAA"}

package/dist/block_storage_facade.js

@@ -1,5 +1,4 @@
 import { createRenderLambda, tryRegisterCallback } from "./internal.js";
-
 //#region src/block_storage_facade.ts
 /**
 * The current facade version. This value is used for `requiresModelAPIVersion`
@@ -39,7 +38,7 @@ const BlockStorageFacadeHandles = createFacadeHandles(BlockStorageFacadeCallback
 function registerFacadeCallbacks(callbacks) {
 	for (const key of Object.values(BlockStorageFacadeCallbacks)) tryRegisterCallback(key, callbacks[key]);
 }
-
 //#endregion
 export { BLOCK_STORAGE_FACADE_VERSION, BlockStorageFacadeCallbacks, BlockStorageFacadeHandles, registerFacadeCallbacks };
+
 //# sourceMappingURL=block_storage_facade.js.map

package/dist/block_storage_facade.js.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage_facade.js","names":[],"sources":["../src/block_storage_facade.ts"],"sourcesContent":["/**\n * Block Storage Facade - Contract between bundled blocks and middle layer.\n *\n * ============================================================================\n * VERSIONING\n * ============================================================================\n *\n * Blocks declare their model API version via the `requiresModelAPIVersion` feature flag\n * (see BlockCodeKnownFeatureFlags). This determines how the middle layer manages block state:\n *\n * - Version 1: Legacy BlockModel - state is {args, uiState}, managed directly by middle layer\n * - Version 2: BlockModelV3 - uses blockStorage with VM-based callbacks (this facade)\n *\n * This facade (BlockStorageFacade) is used by blocks with `requiresModelAPIVersion: 2`.\n * The version number matches the model API version for clarity.\n *\n * ============================================================================\n * BACKWARD COMPATIBILITY WARNING\n * ============================================================================\n *\n * This file documents the FACADE between the SDK (bundled into blocks) and the\n * middle layer. Once a block is published, its SDK version is frozen. The middle\n * layer must support ALL previously released callback signatures indefinitely.\n *\n * RULES:\n * 1. NEVER change the signature of existing callbacks\n * 2. NEVER remove existing callbacks\n * 3. New callbacks CAN be added (old blocks won't register them, middle layer\n *    should handle missing callbacks gracefully)\n * 4. Callback return types can be EXTENDED (add optional fields) but not changed\n * 5. Callback parameter types should remain compatible (middle layer may need\n *    to handle both old and new formats)\n *\n * The facade consists of callbacks registered via `tryRegisterCallback()` with\n * the `__pl_` prefix. These are registered by the SDK when a block loads and\n * called by the middle layer to perform operations.\n *\n * ============================================================================\n * WHAT CAN BE CHANGED FREELY\n * ============================================================================\n *\n * - Middle layer code (lib/node/pl-middle-layer)\n * - SDK internal implementation (as long as callback contracts are preserved)\n * - SDK exports used ONLY by middle layer (not by blocks themselves)\n * - New SDK features that don't affect existing callbacks\n *\n * @module block_storage_facade\n */\n\nimport type { MutateStoragePayload } from \"./block_storage\";\nimport type { ConfigRenderLambda } from \"./bconfig\";\nimport { createRenderLambda, tryRegisterCallback } from \"./internal\";\nimport type { StringifiedJson } from \"@milaboratories/pl-model-common\";\n\n// =============================================================================\n// Facade Version\n// =============================================================================\n\n/**\n * The current facade version. This value is used for `requiresModelAPIVersion`\n * feature flag in BlockModelV3.\n */\nexport const BLOCK_STORAGE_FACADE_VERSION = 2;\n\n// =============================================================================\n// Facade Callback Names\n// =============================================================================\n\n/**\n * All facade callback names as constants.\n * These are the source of truth - the interface is derived from these.\n *\n * IMPORTANT: When adding a new callback:\n * 1. Add the constant here\n * 2. Add the callback signature to FacadeCallbackTypes below\n * 3. The BlockStorageFacade type will automatically include it\n */\nexport const BlockStorageFacadeCallbacks = {\n  StorageApplyUpdate: \"__pl_storage_applyUpdate\",\n  StorageDebugView: \"__pl_storage_debugView\",\n  StorageMigrate: \"__pl_storage_migrate\",\n  ArgsDerive: \"__pl_args_derive\",\n  PrerunArgsDerive: \"__pl_prerunArgs_derive\",\n  StorageInitial: \"__pl_storage_initial\",\n} as const;\n\n/**\n * Creates a map of lambda handles from a callbacks constant object.\n * Keys are the callback string values (e.g., '__pl_storage_applyUpdate').\n */\nfunction createFacadeHandles<T extends Record<string, string>>(\n  callbacks: T,\n): { [K in T[keyof T]]: ConfigRenderLambda } {\n  return Object.fromEntries(\n    Object.values(callbacks).map((handle) => [handle, createRenderLambda({ handle })]),\n  ) as { [K in T[keyof T]]: ConfigRenderLambda };\n}\n\n/**\n * Lambda handles for facade callbacks.\n * Used by the middle layer to invoke callbacks via executeSingleLambda().\n */\nexport const BlockStorageFacadeHandles = createFacadeHandles(BlockStorageFacadeCallbacks);\n\n// =============================================================================\n// Facade Interface (source of truth for callback signatures)\n// =============================================================================\n\n/**\n * The complete facade interface between bundled blocks (SDK) and middle layer.\n *\n * This interface defines ALL callbacks that a block registers. The middle layer\n * calls these callbacks to perform storage operations.\n *\n * ALL types are inlined to simplify versioning - when a callback changes,\n * the entire signature is visible in one place.\n *\n * BACKWARD COMPATIBILITY:\n * - This interface can only be EXTENDED, never shrunk\n * - Existing callback signatures MUST NOT change\n * - Middle layer should use Partial<BlockStorageFacade> when dealing with\n *   blocks of unknown version (older blocks may not have all callbacks)\n *\n * Each callback is documented with:\n * - Purpose and when it's called\n * - Parameter descriptions\n * - Return value description\n */\nexport interface BlockStorageFacade {\n  /**\n   * Apply state update to storage.\n   * Called when UI updates block state (setState) or plugin data.\n   * @param currentStorageJson - Current storage as JSON string\n   * @param payload - Update payload with operation type and value\n   * @returns Updated storage as JSON string\n   */\n  [BlockStorageFacadeCallbacks.StorageApplyUpdate]: (\n    currentStorageJson: StringifiedJson,\n    payload: MutateStoragePayload,\n  ) => StringifiedJson;\n\n  /**\n   * Get debug view of storage.\n   * Called by developer tools to inspect storage state.\n   * @param storageJson - Storage as JSON string (or undefined for new blocks)\n   * @returns JSON string containing StorageDebugView\n   */\n  [BlockStorageFacadeCallbacks.StorageDebugView]: (\n    storageJson: StringifiedJson | undefined,\n  ) => StringifiedJson;\n\n  /**\n   * Run storage migration.\n   * Called when block loads to migrate data to latest version.\n   * @param currentStorageJson - Current storage as JSON string (or undefined for new blocks)\n   * @returns Migration result - either error or success with new storage\n   */\n  [BlockStorageFacadeCallbacks.StorageMigrate]: (currentStorageJson: StringifiedJson | undefined) =>\n    | { error: string }\n    | {\n        error?: undefined;\n        newStorageJson: StringifiedJson;\n        info: string;\n      };\n\n  /**\n   * Derive args from storage.\n   * Called to get block configuration args from storage.\n   * @param storageJson - Storage as JSON string\n   * @returns Args derivation result - either error or derived value\n   */\n  [BlockStorageFacadeCallbacks.ArgsDerive]: (\n    storageJson: StringifiedJson,\n  ) => { error: string } | { error?: undefined; value: unknown };\n\n  /**\n   * Derive prerunArgs from storage.\n   * Called to get prerun args; falls back to args callback if not registered.\n   * @param storageJson - Storage as JSON string\n   * @returns Args derivation result - either error or derived value\n   */\n  [BlockStorageFacadeCallbacks.PrerunArgsDerive]: (\n    storageJson: StringifiedJson,\n  ) => { error: string } | { error?: undefined; value: unknown };\n\n  /**\n   * Get initial storage JSON for new blocks.\n   * Called when creating a new block to get complete initial storage.\n   * @returns Initial storage as JSON string\n   */\n  [BlockStorageFacadeCallbacks.StorageInitial]: () => StringifiedJson;\n}\n\n/** Register all facade callbacks at once. Ensures all required callbacks are provided. */\nexport function registerFacadeCallbacks(callbacks: BlockStorageFacade): void {\n  for (const key of Object.values(BlockStorageFacadeCallbacks)) {\n    tryRegisterCallback(key, callbacks[key] as (...args: any[]) => any);\n  }\n}\n"],"mappings":";;;;;;;AA8DA,MAAa,+BAA+B;;;;;;;;;;AAe5C,MAAa,8BAA8B;CACzC,oBAAoB;CACpB,kBAAkB;CAClB,gBAAgB;CAChB,YAAY;CACZ,kBAAkB;CAClB,gBAAgB;CACjB;;;;;AAMD,SAAS,oBACP,WAC2C;AAC3C,QAAO,OAAO,YACZ,OAAO,OAAO,UAAU,CAAC,KAAK,WAAW,CAAC,QAAQ,mBAAmB,EAAE,QAAQ,CAAC,CAAC,CAAC,CACnF;;;;;;AAOH,MAAa,4BAA4B,oBAAoB,4BAA4B;;AA4FzF,SAAgB,wBAAwB,WAAqC;AAC3E,MAAK,MAAM,OAAO,OAAO,OAAO,4BAA4B,CAC1D,qBAAoB,KAAK,UAAU,KAAgC"}
+{"version":3,"file":"block_storage_facade.js","names":[],"sources":["../src/block_storage_facade.ts"],"sourcesContent":["/**\n * Block Storage Facade - Contract between bundled blocks and middle layer.\n *\n * ============================================================================\n * VERSIONING\n * ============================================================================\n *\n * Blocks declare their model API version via the `requiresModelAPIVersion` feature flag\n * (see BlockCodeKnownFeatureFlags). This determines how the middle layer manages block state:\n *\n * - Version 1: Legacy BlockModel - state is {args, uiState}, managed directly by middle layer\n * - Version 2: BlockModelV3 - uses blockStorage with VM-based callbacks (this facade)\n *\n * This facade (BlockStorageFacade) is used by blocks with `requiresModelAPIVersion: 2`.\n * The version number matches the model API version for clarity.\n *\n * ============================================================================\n * BACKWARD COMPATIBILITY WARNING\n * ============================================================================\n *\n * This file documents the FACADE between the SDK (bundled into blocks) and the\n * middle layer. Once a block is published, its SDK version is frozen. The middle\n * layer must support ALL previously released callback signatures indefinitely.\n *\n * RULES:\n * 1. NEVER change the signature of existing callbacks\n * 2. NEVER remove existing callbacks\n * 3. New callbacks CAN be added (old blocks won't register them, middle layer\n *    should handle missing callbacks gracefully)\n * 4. Callback return types can be EXTENDED (add optional fields) but not changed\n * 5. Callback parameter types should remain compatible (middle layer may need\n *    to handle both old and new formats)\n *\n * The facade consists of callbacks registered via `tryRegisterCallback()` with\n * the `__pl_` prefix. These are registered by the SDK when a block loads and\n * called by the middle layer to perform operations.\n *\n * ============================================================================\n * WHAT CAN BE CHANGED FREELY\n * ============================================================================\n *\n * - Middle layer code (lib/node/pl-middle-layer)\n * - SDK internal implementation (as long as callback contracts are preserved)\n * - SDK exports used ONLY by middle layer (not by blocks themselves)\n * - New SDK features that don't affect existing callbacks\n *\n * @module block_storage_facade\n */\n\nimport type { MutateStoragePayload } from \"./block_storage\";\nimport type { ConfigRenderLambda } from \"./bconfig\";\nimport { createRenderLambda, tryRegisterCallback } from \"./internal\";\nimport type { StringifiedJson } from \"@milaboratories/pl-model-common\";\n\n// =============================================================================\n// Facade Version\n// =============================================================================\n\n/**\n * The current facade version. This value is used for `requiresModelAPIVersion`\n * feature flag in BlockModelV3.\n */\nexport const BLOCK_STORAGE_FACADE_VERSION = 2;\n\n// =============================================================================\n// Facade Callback Names\n// =============================================================================\n\n/**\n * All facade callback names as constants.\n * These are the source of truth - the interface is derived from these.\n *\n * IMPORTANT: When adding a new callback:\n * 1. Add the constant here\n * 2. Add the callback signature to FacadeCallbackTypes below\n * 3. The BlockStorageFacade type will automatically include it\n */\nexport const BlockStorageFacadeCallbacks = {\n  StorageApplyUpdate: \"__pl_storage_applyUpdate\",\n  StorageDebugView: \"__pl_storage_debugView\",\n  StorageMigrate: \"__pl_storage_migrate\",\n  ArgsDerive: \"__pl_args_derive\",\n  PrerunArgsDerive: \"__pl_prerunArgs_derive\",\n  StorageInitial: \"__pl_storage_initial\",\n} as const;\n\n/**\n * Creates a map of lambda handles from a callbacks constant object.\n * Keys are the callback string values (e.g., '__pl_storage_applyUpdate').\n */\nfunction createFacadeHandles<T extends Record<string, string>>(\n  callbacks: T,\n): { [K in T[keyof T]]: ConfigRenderLambda } {\n  return Object.fromEntries(\n    Object.values(callbacks).map((handle) => [handle, createRenderLambda({ handle })]),\n  ) as { [K in T[keyof T]]: ConfigRenderLambda };\n}\n\n/**\n * Lambda handles for facade callbacks.\n * Used by the middle layer to invoke callbacks via executeSingleLambda().\n */\nexport const BlockStorageFacadeHandles = createFacadeHandles(BlockStorageFacadeCallbacks);\n\n// =============================================================================\n// Facade Interface (source of truth for callback signatures)\n// =============================================================================\n\n/**\n * The complete facade interface between bundled blocks (SDK) and middle layer.\n *\n * This interface defines ALL callbacks that a block registers. The middle layer\n * calls these callbacks to perform storage operations.\n *\n * ALL types are inlined to simplify versioning - when a callback changes,\n * the entire signature is visible in one place.\n *\n * BACKWARD COMPATIBILITY:\n * - This interface can only be EXTENDED, never shrunk\n * - Existing callback signatures MUST NOT change\n * - Middle layer should use Partial<BlockStorageFacade> when dealing with\n *   blocks of unknown version (older blocks may not have all callbacks)\n *\n * Each callback is documented with:\n * - Purpose and when it's called\n * - Parameter descriptions\n * - Return value description\n */\nexport interface BlockStorageFacade {\n  /**\n   * Apply state update to storage.\n   * Called when UI updates block state (setState) or plugin data.\n   * @param currentStorageJson - Current storage as JSON string\n   * @param payload - Update payload with operation type and value\n   * @returns Updated storage as JSON string\n   */\n  [BlockStorageFacadeCallbacks.StorageApplyUpdate]: (\n    currentStorageJson: StringifiedJson,\n    payload: MutateStoragePayload,\n  ) => StringifiedJson;\n\n  /**\n   * Get debug view of storage.\n   * Called by developer tools to inspect storage state.\n   * @param storageJson - Storage as JSON string (or undefined for new blocks)\n   * @returns JSON string containing StorageDebugView\n   */\n  [BlockStorageFacadeCallbacks.StorageDebugView]: (\n    storageJson: StringifiedJson | undefined,\n  ) => StringifiedJson;\n\n  /**\n   * Run storage migration.\n   * Called when block loads to migrate data to latest version.\n   * @param currentStorageJson - Current storage as JSON string (or undefined for new blocks)\n   * @returns Migration result - either error or success with new storage\n   */\n  [BlockStorageFacadeCallbacks.StorageMigrate]: (currentStorageJson: StringifiedJson | undefined) =>\n    | { error: string }\n    | {\n        error?: undefined;\n        newStorageJson: StringifiedJson;\n        info: string;\n      };\n\n  /**\n   * Derive args from storage.\n   * Called to get block configuration args from storage.\n   * @param storageJson - Storage as JSON string\n   * @returns Args derivation result - either error or derived value\n   */\n  [BlockStorageFacadeCallbacks.ArgsDerive]: (\n    storageJson: StringifiedJson,\n  ) => { error: string } | { error?: undefined; value: unknown };\n\n  /**\n   * Derive prerunArgs from storage.\n   * Called to get prerun args; falls back to args callback if not registered.\n   * @param storageJson - Storage as JSON string\n   * @returns Args derivation result - either error or derived value\n   */\n  [BlockStorageFacadeCallbacks.PrerunArgsDerive]: (\n    storageJson: StringifiedJson,\n  ) => { error: string } | { error?: undefined; value: unknown };\n\n  /**\n   * Get initial storage JSON for new blocks.\n   * Called when creating a new block to get complete initial storage.\n   * @returns Initial storage as JSON string\n   */\n  [BlockStorageFacadeCallbacks.StorageInitial]: () => StringifiedJson;\n}\n\n/** Register all facade callbacks at once. Ensures all required callbacks are provided. */\nexport function registerFacadeCallbacks(callbacks: BlockStorageFacade): void {\n  for (const key of Object.values(BlockStorageFacadeCallbacks)) {\n    tryRegisterCallback(key, callbacks[key] as (...args: any[]) => any);\n  }\n}\n"],"mappings":";;;;;;AA8DA,MAAa,+BAA+B;;;;;;;;;;AAe5C,MAAa,8BAA8B;CACzC,oBAAoB;CACpB,kBAAkB;CAClB,gBAAgB;CAChB,YAAY;CACZ,kBAAkB;CAClB,gBAAgB;CACjB;;;;;AAMD,SAAS,oBACP,WAC2C;AAC3C,QAAO,OAAO,YACZ,OAAO,OAAO,UAAU,CAAC,KAAK,WAAW,CAAC,QAAQ,mBAAmB,EAAE,QAAQ,CAAC,CAAC,CAAC,CACnF;;;;;;AAOH,MAAa,4BAA4B,oBAAoB,4BAA4B;;AA4FzF,SAAgB,wBAAwB,WAAqC;AAC3E,MAAK,MAAM,OAAO,OAAO,OAAO,4BAA4B,CAC1D,qBAAoB,KAAK,UAAU,KAAgC"}