@platforma-sdk/model 1.81.1 → 1.82.0

package/dist/block_storage_callbacks.js.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage_callbacks.js","names":["obj"],"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":["obj"],"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 {\n  stringifyJson,\n  expandTemplateRefs,\n  relocateBlockIds,\n  type StringifiedJson,\n} 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  return assembleStorage(hooks.getDefaultBlockData(), hooks);\n}\n\n/**\n * Wraps freshly created block data and freshly created plugin data into storage.\n *\n * Shared by the two ways a block's first storage comes into being — from defaults\n * and from template params. Only the block's own data differs between them:\n * plugins have no params channel, so they are always created at their defaults.\n */\nfunction assembleStorage(\n  blockData: DataVersioned<unknown>,\n  hooks: Omit<InitialStorageHooks, \"getDefaultBlockData\">,\n): StringifiedJson<BlockStorage> {\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: blockData.version,\n    __data: blockData.data,\n    __pluginRegistry: pluginRegistry,\n    __plugins: plugins,\n  };\n  return stringifyJson(storage);\n}\n\n/** Dependencies for creating storage from a template entry's params. */\nexport interface ParamsStorageHooks extends Omit<InitialStorageHooks, \"getDefaultBlockData\"> {\n  /** The block's init factory, called with the entry's params. */\n  getBlockDataFromParams: (params: unknown) => DataVersioned<unknown>;\n  /**\n   * The kind's runtime params check. Applied before the factory sees anything, and its\n   * output is what the factory gets.\n   */\n  parseInitializationParams: (value: unknown) => unknown;\n}\n\n/** Result of checking params against their kind: the params to use, or why they lost. */\nexport type TemplateParamsValidationResult =\n  | { error: string }\n  | { error?: undefined; value: unknown };\n\n/**\n * Check params against their kind's declared shape.\n *\n * The kind owns this rather than the block because the params contract belongs to the\n * kind: many block versions implement one kind, and a per-block check would let them\n * drift from each other and from the type.\n *\n * A parser rejects by throwing and accepts by returning the params to use, so its\n * output — not the input — is what flows onward. That is what lets a kind strip keys\n * it does not declare, which is the difference between a typo being ignored and a typo\n * being reported.\n *\n * Every kind declares a parser, so every set of params that reaches here is checked;\n * there is no pass-through path.\n *\n * @param value The params to check, references already in live form\n * @param parseInitializationParams The kind's parser\n */\nexport function validateTemplateParams(\n  value: unknown,\n  parseInitializationParams: (value: unknown) => unknown,\n): TemplateParamsValidationResult {\n  try {\n    return { value: parseInitializationParams(value) };\n  } catch (e) {\n    // A rejection is an expected outcome for a hand-written file, so it is reported,\n    // not thrown.\n    return { error: `params do not match this block's kind: ${describeRejection(e)}` };\n  }\n}\n\n/** One `{ path, message }` entry of a schema library's error. */\ntype IssueLike = { path?: unknown; message?: unknown };\n\n/**\n * Render whatever a parser threw as one readable line.\n *\n * An error carrying an `issues` array is unpacked rather than printed: that is the\n * shape zod (and several others) use, and its `message` is the whole issue list as\n * JSON — technically complete and unreadable in a dialog. Duck-typed on purpose, since\n * this package prescribes no schema library and takes no dependency on one; anything\n * else falls back to its own message.\n */\nfunction describeRejection(e: unknown): string {\n  const issues = (e as { issues?: unknown }).issues;\n  if (!Array.isArray(issues) || issues.length === 0) return messageOf(e);\n\n  return issues\n    .map((issue) => {\n      const { path, message } = issue as IssueLike;\n      const what = typeof message === \"string\" ? message : \"is invalid\";\n      const where = Array.isArray(path) ? formatPath(path) : \"\";\n      return where === \"\" ? what : `${where}: ${what}`;\n    })\n    .join(\"; \");\n}\n\n/** `[\"numbers\", 0]` → `numbers[0]` — how the params are written, not how they parse. */\nfunction formatPath(path: readonly unknown[]): string {\n  return path.reduce<string>((acc, segment) => {\n    if (typeof segment === \"number\") return `${acc}[${segment}]`;\n    return acc === \"\" ? String(segment) : `${acc}.${String(segment)}`;\n  }, \"\");\n}\n\n/**\n * Result of the `__pl_params_validate` callback.\n *\n * Carries no params back. The check is a pre-flight — its answer is \"may this entry be\n * applied\", and the params that actually reach the block are produced by\n * {@link createInitialStorageFromParams}, which parses again. One authoritative\n * producer, rather than two values that could differ.\n */\nexport type InitializationParamsValidateCallbackResult = { error: string } | { error?: undefined };\n\n/**\n * Check params that crossed into the model VM as text.\n *\n * The pre-flight entry point: a caller asks this before creating anything, once per\n * template entry, so params a kind rejects are reported while there is still no\n * project to half-build.\n *\n * The readable reference spelling is expanded here too, so what the kind checks is the shape it\n * declared. The ids it sees are the file's own — no block exists yet — which is why a kind must\n * not read meaning into a specific id.\n *\n * @param paramsJson The entry's params as JSON string\n * @param parseInitializationParams The kind's parser\n */\nexport function validateTemplateParamsJson(\n  paramsJson: string,\n  parseInitializationParams: (value: unknown) => unknown,\n): InitializationParamsValidateCallbackResult {\n  let params: unknown;\n  try {\n    params = JSON.parse(paramsJson);\n  } catch (e) {\n    return { error: `params are not valid JSON: ${messageOf(e)}` };\n  }\n\n  // Expanded before the kind sees anything, or a hand-written file would be rejected by every\n  // kind that declares a reference: `{ block, name }` is not a `PlRef` and no contract accepts\n  // one. Expansion needs nothing but the params, so this stays a two-argument check — the ids\n  // are not known yet and are not needed to answer the question this asks.\n  const result = validateTemplateParams(expandTemplateRefs(params), parseInitializationParams);\n  if (result.error !== undefined) return { error: result.error };\n  return {};\n}\n\nfunction messageOf(e: unknown): string {\n  return e instanceof Error ? e.message : String(e);\n}\n\n/**\n * Result of building initial storage from params.\n * Returned by the `__pl_storage_initialFromParams` callback.\n */\nexport type ParamsStorageResult =\n  | { error: string }\n  | { error?: undefined; storageJson: StringifiedJson<BlockStorage> };\n\n/**\n * Creates complete initial storage for a block being created from template params.\n *\n * The inverse of {@link deriveTemplateParamsFromStorage}: that projects storage\n * into params, this builds storage from them. The params are handed to the block's\n * init factory, whose output is versioned and wrapped exactly as\n * {@link createInitialStorage} wraps the defaults — so a block created from a\n * template is indistinguishable from one created in the UI and then edited.\n *\n * **This is where a template's references become the block's own**, and it is the only place in\n * a template's life where a reference is recognized at all. Params travel from the file\n * untouched — the engine carrying them neither marks a reference nor reads one, because\n * recognizing one means knowing the reference system, and that knowledge is here.\n *\n * Two things happen, in this order. The readable spelling a person may have written\n * (`{ block, name }`) is expanded into the `PlRef` it stands for. Then every reference naming\n * an entry that has a block is repointed at it: `blockIds` maps each template-local entry id to\n * the block id it was given, and an id it does not name is left alone, which is how a reference\n * to an entry created later ends up naming nothing rather than naming the wrong block.\n *\n * Relocation happens before the kind's parser and before the factory, so both see the ids the\n * block will actually hold. It is one step of this function rather than a callback of its own\n * precisely because nothing else wants its result: every VM call re-instantiates the runtime\n * and re-evaluates the whole model bundle, so a separate call would parse the block twice per\n * entry to produce a value only the next line reads.\n *\n * Params arrive as JSON text because this runs across the model-VM boundary, where\n * only strings pass. Anything the factory rejects is returned as an error rather\n * than thrown: applying a hand-written template is expected to surface bad params,\n * and the applier reports every entry's problem in one pass.\n *\n * @param paramsJson - The entry's params as JSON string, exactly as the file held them\n * @param blockIdsJson - template-local entry id → assigned block id, as a JSON object\n * @param hooks - The block's init factory plus plugin creation\n * @returns The storage to write, or why the params could not produce any\n */\nexport function createInitialStorageFromParams(\n  paramsJson: string,\n  blockIdsJson: string,\n  hooks: ParamsStorageHooks,\n): ParamsStorageResult {\n  let params: unknown;\n  try {\n    params = JSON.parse(paramsJson);\n  } catch (e) {\n    return { error: `params are not valid JSON: ${messageOf(e)}` };\n  }\n\n  // Read separately from the params, and reported separately, because the two fail for\n  // completely different reasons. Params are the file's and a bad one is the author's mistake;\n  // this argument is the caller's, so the only way it arrives unreadable is a caller that does\n  // not send it — a middle layer older than this block, which is a build to refresh rather than\n  // anything to fix in the template. Folding both into one message sent the reader to the file.\n  let blockIds: Map<string, string>;\n  try {\n    blockIds = new Map(Object.entries(JSON.parse(blockIdsJson) as Record<string, string>));\n  } catch (e) {\n    return {\n      error:\n        `this block was not told which blocks the template's references should point at ` +\n        `(${messageOf(e)}). The application applying the template is older than the block; ` +\n        `rebuild or update it.`,\n    };\n  }\n\n  try {\n    // Spelling first, ids second. Expansion turns `{ block, name }` into a `PlRef` naming an\n    // ENTRY, which is exactly what relocation then repoints — so both spellings reach the\n    // block through the same step and cannot diverge in how they behave.\n    params = relocateBlockIds(expandTemplateRefs(params), blockIds);\n  } catch (e) {\n    return { error: `this entry's references could not be relocated: ${messageOf(e)}` };\n  }\n\n  // Checked here too, not only in the caller's pre-flight pass. The pre-flight is\n  // about reporting every bad entry before anything is created; this is about the\n  // factory never being handed a value the kind rejects, whichever path got here.\n  const checked = validateTemplateParams(params, hooks.parseInitializationParams);\n  if (checked.error !== undefined) return { error: checked.error };\n\n  try {\n    return { storageJson: assembleStorage(hooks.getBlockDataFromParams(checked.value), hooks) };\n  } catch (e) {\n    return { error: `init() threw on the given params: ${messageOf(e)}` };\n  }\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 deriveArgs - The block's args derivation function\n * @returns ArgsDeriveResult with derived args or error\n */\nexport function deriveArgsFromStorage(\n  storageJson: string,\n  deriveArgs: (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 = deriveArgs(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 derivePrerunArgs if provided, otherwise falls back to deriveArgs.\n *\n * @param storageJson - Storage as JSON string\n * @param deriveArgs - The block's args derivation function (fallback)\n * @param derivePrerunArgs - Optional prerun args derivation function\n * @returns ArgsDeriveResult with derived prerunArgs or error\n */\nexport function derivePrerunArgsFromStorage(\n  storageJson: string,\n  deriveArgs: (data: unknown) => unknown,\n  derivePrerunArgs?: (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 (derivePrerunArgs) {\n    try {\n      const result = derivePrerunArgs(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 = deriveArgs(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// =============================================================================\n// Template Entry Derivation from Storage\n// =============================================================================\n\n/**\n * Derives this block's template-entry params from storage.\n *\n * The inverse of the data model's `init`: `init` turns `params` into data, this\n * turns data back into the params that would recreate it.\n *\n * The lambda returns ordinary live params — references as `PlRef`s, column identifiers as they\n * are stored — and that is exactly what gets written. Nothing is marked, normalized or\n * rewritten on the way out: a template holds what the block holds. Repointing those references\n * at another project is the business of {@link createInitialStorageFromParams}, on the way back\n * in, where the ids to point at are known.\n *\n * Every block declares the lambda, so every export produces params; a block with\n * nothing worth restoring returns `{}` rather than declining.\n *\n * @param storageJson - Storage as JSON string\n * @param deriveTemplateParams - The block's templateParams lambda\n * @returns ArgsDeriveResult holding the params exactly as the block projected them\n */\nexport function deriveTemplateParamsFromStorage<TP extends (data: unknown) => unknown>(\n  storageJson: string,\n  deriveTemplateParams: TP,\n): ArgsDeriveResult {\n  const { data } = normalizeStorage(storageJson);\n\n  try {\n    return { value: deriveTemplateParams(data) };\n  } catch (e) {\n    const errorMsg = e instanceof Error ? e.message : String(e);\n    return { error: `templateParams() threw: ${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

@@ -20,7 +20,10 @@ const BlockStorageFacadeCallbacks = {
 	StorageMigrate: "__pl_storage_migrate",
 	ArgsDerive: "__pl_args_derive",
 	PrerunArgsDerive: "__pl_prerunArgs_derive",
-	StorageInitial: "__pl_storage_initial"
+	StorageInitial: "__pl_storage_initial",
+	InitializationParamsDerive: "__pl_initializationParams_derive",
+	StorageInitialFromParams: "__pl_storage_initialFromParams",
+	InitializationParamsValidate: "__pl_initializationParams_validate"
 };
 /**
 * Creates a map of lambda handles from a callbacks constant object.

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;AAClB;;;;;AAMA,SAAS,oBACP,WAC2C;CAC3C,OAAO,OAAO,YACZ,OAAO,OAAO,SAAS,CAAC,CAAC,KAAK,WAAW,CAAC,QAAQA,iBAAAA,mBAAmB,EAAE,OAAO,CAAC,CAAC,CAAC,CACnF;AACF;;;;;AAMA,MAAa,4BAA4B,oBAAoB,2BAA2B;;AA4FxF,SAAgB,wBAAwB,WAAqC;CAC3E,KAAK,MAAM,OAAO,OAAO,OAAO,2BAA2B,GACzD,iBAAA,oBAAoB,KAAK,UAAU,IAA+B;AAEtE"}
+{"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  InitializationParamsDerive: \"__pl_initializationParams_derive\",\n  StorageInitialFromParams: \"__pl_storage_initialFromParams\",\n  InitializationParamsValidate: \"__pl_initializationParams_validate\",\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   * Derive this block's template entry params from storage.\n   * Called when exporting the project as a template.\n   *\n   * Every V3 block declares `.templateParams()` — the model does not build without\n   * it — so every export produces params. A block whose state carries nothing worth\n   * restoring returns `{}`, which is written out and used as-is by init.\n   *\n   * The returned params are written out exactly as they come back, references included: the\n   * template engine carrying them recognizes nothing in there, and the block that receives\n   * them on the way back in is what repoints them. The caller supplies everything else in the\n   * entry — `id`, `kind` — so the lambda cannot set them.\n   *\n   * @param storageJson - Storage as JSON string\n   * @returns Either an error, or the params to write\n   */\n  [BlockStorageFacadeCallbacks.InitializationParamsDerive]: (\n    storageJson: StringifiedJson,\n  ) => { error: string } | { error?: undefined; value: unknown };\n\n  /**\n   * Get initial storage JSON for a block created from params.\n   * Called when applying a template, once per entry that carries `params`.\n   *\n   * The mirror image of {@link BlockStorageFacadeCallbacks.InitializationParamsDerive}:\n   * that one turns storage into params, this one turns params into storage. Every\n   * applied entry comes through here, including one whose file omitted `params` —\n   * an omitted key is read as `{}` and checked like any other value, so no entry\n   * reaches a block without passing its kind's contract.\n   * {@link BlockStorageFacadeCallbacks.StorageInitial} stays the UI-creation path,\n   * where there are genuinely no params.\n   *\n   * Separate from `StorageInitial` rather than an optional argument to it,\n   * deliberately: a block bundled with an older SDK does not register this\n   * callback at all, so the caller sees it missing and can say so. Widening\n   * `StorageInitial` would instead have that block silently ignore the params and\n   * produce a default-initialized block that looks successfully applied.\n   *\n   * The params arrive as ordinary live params — references are `PlRef`s, already\n   * pointing at the ids the target project just assigned. Resolution happens in\n   * the engine, before this call, so a block's init factory never handles a\n   * template-local reference.\n   *\n   * Errors are returned, not thrown: a factory rejecting params it cannot use is\n   * an expected outcome for a hand-written template file, and every entry's\n   * problem is reported together.\n   *\n   * **Also where the entry's references are pointed at this project.** Params reach here\n   * exactly as the file held them: nothing between the block that exported them and this call\n   * marks a reference, reads one, or rewrites one, because recognizing one means knowing the\n   * reference system and this bundle is where that knowledge lives. `blockIdsJson` maps each\n   * template-local entry id to the block id it was given, holding the entries created so far —\n   * so an id it does not name is left alone, and a reference to an entry created later names\n   * nothing rather than naming the wrong block.\n   *\n   * Relocating and initializing are one call rather than two because every call\n   * re-instantiates the runtime and re-evaluates the whole model bundle: splitting them would\n   * parse the block twice per entry to produce an intermediate only the second half reads.\n   *\n   * @param paramsJson - The entry's params as JSON string, as the file held them\n   * @param blockIdsJson - template-local entry id → assigned block id, as a JSON object\n   * @returns Either an error, or the initial storage as JSON string\n   */\n  [BlockStorageFacadeCallbacks.StorageInitialFromParams]: (\n    paramsJson: StringifiedJson,\n    blockIdsJson: StringifiedJson,\n  ) => { error: string } | { error?: undefined; storageJson: StringifiedJson };\n\n  /**\n   * Check params against this block's kind, creating nothing.\n   *\n   * Called once per entry before a template is applied, so params a kind rejects are\n   * reported against the entry that carries them while there is still no project — the\n   * same reason references and ids are checked before construction starts. Applying\n   * without this call is safe but worse: `StorageInitialFromParams` runs the same check\n   * and refuses, by which point earlier entries have already been created.\n   *\n   * A pass carries nothing back but its own absence of error: every kind declares a\n   * parser, so a pass means the params were checked against the contract, not merely\n   * that they were valid JSON.\n   *\n   * Reference ids inside the params may be placeholders at this point: the check runs\n   * before blocks exist, so what is verified is the shape of the params, not what they\n   * point at.\n   *\n   * @param paramsJson The entry's params as JSON string\n   * @returns Why the params were rejected, or nothing\n   */\n  [BlockStorageFacadeCallbacks.InitializationParamsValidate]: (\n    paramsJson: StringifiedJson,\n  ) => { error: string } | { error?: undefined };\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;CAChB,4BAA4B;CAC5B,0BAA0B;CAC1B,8BAA8B;AAChC;;;;;AAMA,SAAS,oBACP,WAC2C;CAC3C,OAAO,OAAO,YACZ,OAAO,OAAO,SAAS,CAAC,CAAC,KAAK,WAAW,CAAC,QAAQA,iBAAAA,mBAAmB,EAAE,OAAO,CAAC,CAAC,CAAC,CACnF;AACF;;;;;AAMA,MAAa,4BAA4B,oBAAoB,2BAA2B;;AAwLxF,SAAgB,wBAAwB,WAAqC;CAC3E,KAAK,MAAM,OAAO,OAAO,OAAO,2BAA2B,GACzD,iBAAA,oBAAoB,KAAK,UAAU,IAA+B;AAEtE"}

package/dist/block_storage_facade.d.ts

@@ -24,6 +24,9 @@ declare const BlockStorageFacadeCallbacks: {
   readonly ArgsDerive: "__pl_args_derive";
   readonly PrerunArgsDerive: "__pl_prerunArgs_derive";
   readonly StorageInitial: "__pl_storage_initial";
+  readonly InitializationParamsDerive: "__pl_initializationParams_derive";
+  readonly StorageInitialFromParams: "__pl_storage_initialFromParams";
+  readonly InitializationParamsValidate: "__pl_initializationParams_validate";
 };
 /**
  * Lambda handles for facade callbacks.
@@ -36,6 +39,9 @@ declare const BlockStorageFacadeHandles: {
   __pl_args_derive: ConfigRenderLambda<unknown>;
   __pl_prerunArgs_derive: ConfigRenderLambda<unknown>;
   __pl_storage_initial: ConfigRenderLambda<unknown>;
+  __pl_initializationParams_derive: ConfigRenderLambda<unknown>;
+  __pl_storage_initialFromParams: ConfigRenderLambda<unknown>;
+  __pl_initializationParams_validate: ConfigRenderLambda<unknown>;
 };
 /**
  * The complete facade interface between bundled blocks (SDK) and middle layer.
@@ -116,6 +122,102 @@ interface BlockStorageFacade {
    * @returns Initial storage as JSON string
    */
   [BlockStorageFacadeCallbacks.StorageInitial]: () => StringifiedJson;
+  /**
+   * Derive this block's template entry params from storage.
+   * Called when exporting the project as a template.
+   *
+   * Every V3 block declares `.templateParams()` — the model does not build without
+   * it — so every export produces params. A block whose state carries nothing worth
+   * restoring returns `{}`, which is written out and used as-is by init.
+   *
+   * The returned params are written out exactly as they come back, references included: the
+   * template engine carrying them recognizes nothing in there, and the block that receives
+   * them on the way back in is what repoints them. The caller supplies everything else in the
+   * entry — `id`, `kind` — so the lambda cannot set them.
+   *
+   * @param storageJson - Storage as JSON string
+   * @returns Either an error, or the params to write
+   */
+  [BlockStorageFacadeCallbacks.InitializationParamsDerive]: (storageJson: StringifiedJson) => {
+    error: string;
+  } | {
+    error?: undefined;
+    value: unknown;
+  };
+  /**
+   * Get initial storage JSON for a block created from params.
+   * Called when applying a template, once per entry that carries `params`.
+   *
+   * The mirror image of {@link BlockStorageFacadeCallbacks.InitializationParamsDerive}:
+   * that one turns storage into params, this one turns params into storage. Every
+   * applied entry comes through here, including one whose file omitted `params` —
+   * an omitted key is read as `{}` and checked like any other value, so no entry
+   * reaches a block without passing its kind's contract.
+   * {@link BlockStorageFacadeCallbacks.StorageInitial} stays the UI-creation path,
+   * where there are genuinely no params.
+   *
+   * Separate from `StorageInitial` rather than an optional argument to it,
+   * deliberately: a block bundled with an older SDK does not register this
+   * callback at all, so the caller sees it missing and can say so. Widening
+   * `StorageInitial` would instead have that block silently ignore the params and
+   * produce a default-initialized block that looks successfully applied.
+   *
+   * The params arrive as ordinary live params — references are `PlRef`s, already
+   * pointing at the ids the target project just assigned. Resolution happens in
+   * the engine, before this call, so a block's init factory never handles a
+   * template-local reference.
+   *
+   * Errors are returned, not thrown: a factory rejecting params it cannot use is
+   * an expected outcome for a hand-written template file, and every entry's
+   * problem is reported together.
+   *
+   * **Also where the entry's references are pointed at this project.** Params reach here
+   * exactly as the file held them: nothing between the block that exported them and this call
+   * marks a reference, reads one, or rewrites one, because recognizing one means knowing the
+   * reference system and this bundle is where that knowledge lives. `blockIdsJson` maps each
+   * template-local entry id to the block id it was given, holding the entries created so far —
+   * so an id it does not name is left alone, and a reference to an entry created later names
+   * nothing rather than naming the wrong block.
+   *
+   * Relocating and initializing are one call rather than two because every call
+   * re-instantiates the runtime and re-evaluates the whole model bundle: splitting them would
+   * parse the block twice per entry to produce an intermediate only the second half reads.
+   *
+   * @param paramsJson - The entry's params as JSON string, as the file held them
+   * @param blockIdsJson - template-local entry id → assigned block id, as a JSON object
+   * @returns Either an error, or the initial storage as JSON string
+   */
+  [BlockStorageFacadeCallbacks.StorageInitialFromParams]: (paramsJson: StringifiedJson, blockIdsJson: StringifiedJson) => {
+    error: string;
+  } | {
+    error?: undefined;
+    storageJson: StringifiedJson;
+  };
+  /**
+   * Check params against this block's kind, creating nothing.
+   *
+   * Called once per entry before a template is applied, so params a kind rejects are
+   * reported against the entry that carries them while there is still no project — the
+   * same reason references and ids are checked before construction starts. Applying
+   * without this call is safe but worse: `StorageInitialFromParams` runs the same check
+   * and refuses, by which point earlier entries have already been created.
+   *
+   * A pass carries nothing back but its own absence of error: every kind declares a
+   * parser, so a pass means the params were checked against the contract, not merely
+   * that they were valid JSON.
+   *
+   * Reference ids inside the params may be placeholders at this point: the check runs
+   * before blocks exist, so what is verified is the shape of the params, not what they
+   * point at.
+   *
+   * @param paramsJson The entry's params as JSON string
+   * @returns Why the params were rejected, or nothing
+   */
+  [BlockStorageFacadeCallbacks.InitializationParamsValidate]: (paramsJson: StringifiedJson) => {
+    error: string;
+  } | {
+    error?: undefined;
+  };
 }
 /** Register all facade callbacks at once. Ensures all required callbacks are provided. */
 declare function registerFacadeCallbacks(callbacks: BlockStorageFacade): void;

package/dist/block_storage_facade.d.ts.map

@@ -1 +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;;;;AAAqE;EAJA,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,SAA6B,EAAlB,kBAAkB"}
+{"version":3,"file":"block_storage_facade.d.ts","names":[],"sources":["../src/block_storage_facade.ts"],"mappings":";;;;;;;;;cA8Da,4BAAA;;;;;AAqEb;;;;;cAtDa,2BAAA;EAAA;;;;;;;;;;;;;;cA4BA,yBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA0BI,kBAAA;EAkCT;;;;;;;EAAA,CA1BL,2BAAA,CAA4B,kBAAA,IAC3B,kBAAA,EAAoB,eAAA,EACpB,OAAA,EAAS,oBAAA,KACN,eAAA;EAkCyC;;;;;;EAAA,CA1B7C,2BAAA,CAA4B,gBAAA,IAC3B,WAAA,EAAa,eAAA,iBACV,eAAA;EAkCsB;;;;;;EAAA,CA1B1B,2BAAA,CAA4B,cAAA,IAAkB,kBAAA,EAAoB,eAAA;IAC7D,KAAA;EAAA;IAEA,KAAA;IACA,cAAA,EAAgB,eAAA;IAChB,IAAA;EAAA;EAgDwC;;;;;;EAAA,CAvC7C,2BAAA,CAA4B,UAAA,IAC3B,WAAA,EAAa,eAAA;IACR,KAAA;EAAA;IAAoB,KAAA;IAAmB,KAAA;EAAA;EA2G7C;;;;;;EAAA,CAnGA,2BAAA,CAA4B,gBAAA,IAC3B,WAAA,EAAa,eAAA;IACR,KAAA;EAAA;IAAoB,KAAA;IAAmB,KAAA;EAAA;EAuGG;AAAkB;;;;EAAlB,CAhGhD,2BAAA,CAA4B,cAAA,SAAuB,eAAA;;;;;;;;;;;;;;;;;GAkBnD,2BAAA,CAA4B,0BAAA,IAC3B,WAAA,EAAa,eAAA;IACR,KAAA;EAAA;IAAoB,KAAA;IAAmB,KAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6C7C,2BAAA,CAA4B,wBAAA,IAC3B,UAAA,EAAY,eAAA,EACZ,YAAA,EAAc,eAAA;IACT,KAAA;EAAA;IAAoB,KAAA;IAAmB,WAAA,EAAa,eAAA;EAAA;;;;;;;;;;;;;;;;;;;;;GAsB1D,2BAAA,CAA4B,4BAAA,IAC3B,UAAA,EAAY,eAAA;IACP,KAAA;EAAA;IAAoB,KAAA;EAAA;AAAA;;iBAIb,uBAAA,CAAwB,SAA6B,EAAlB,kBAAkB"}

package/dist/block_storage_facade.js

@@ -20,7 +20,10 @@ const BlockStorageFacadeCallbacks = {
 	StorageMigrate: "__pl_storage_migrate",
 	ArgsDerive: "__pl_args_derive",
 	PrerunArgsDerive: "__pl_prerunArgs_derive",
-	StorageInitial: "__pl_storage_initial"
+	StorageInitial: "__pl_storage_initial",
+	InitializationParamsDerive: "__pl_initializationParams_derive",
+	StorageInitialFromParams: "__pl_storage_initialFromParams",
+	InitializationParamsValidate: "__pl_initializationParams_validate"
 };
 /**
 * Creates a map of lambda handles from a callbacks constant object.

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;AAClB;;;;;AAMA,SAAS,oBACP,WAC2C;CAC3C,OAAO,OAAO,YACZ,OAAO,OAAO,SAAS,CAAC,CAAC,KAAK,WAAW,CAAC,QAAQ,mBAAmB,EAAE,OAAO,CAAC,CAAC,CAAC,CACnF;AACF;;;;;AAMA,MAAa,4BAA4B,oBAAoB,2BAA2B;;AA4FxF,SAAgB,wBAAwB,WAAqC;CAC3E,KAAK,MAAM,OAAO,OAAO,OAAO,2BAA2B,GACzD,oBAAoB,KAAK,UAAU,IAA+B;AAEtE"}
+{"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  InitializationParamsDerive: \"__pl_initializationParams_derive\",\n  StorageInitialFromParams: \"__pl_storage_initialFromParams\",\n  InitializationParamsValidate: \"__pl_initializationParams_validate\",\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   * Derive this block's template entry params from storage.\n   * Called when exporting the project as a template.\n   *\n   * Every V3 block declares `.templateParams()` — the model does not build without\n   * it — so every export produces params. A block whose state carries nothing worth\n   * restoring returns `{}`, which is written out and used as-is by init.\n   *\n   * The returned params are written out exactly as they come back, references included: the\n   * template engine carrying them recognizes nothing in there, and the block that receives\n   * them on the way back in is what repoints them. The caller supplies everything else in the\n   * entry — `id`, `kind` — so the lambda cannot set them.\n   *\n   * @param storageJson - Storage as JSON string\n   * @returns Either an error, or the params to write\n   */\n  [BlockStorageFacadeCallbacks.InitializationParamsDerive]: (\n    storageJson: StringifiedJson,\n  ) => { error: string } | { error?: undefined; value: unknown };\n\n  /**\n   * Get initial storage JSON for a block created from params.\n   * Called when applying a template, once per entry that carries `params`.\n   *\n   * The mirror image of {@link BlockStorageFacadeCallbacks.InitializationParamsDerive}:\n   * that one turns storage into params, this one turns params into storage. Every\n   * applied entry comes through here, including one whose file omitted `params` —\n   * an omitted key is read as `{}` and checked like any other value, so no entry\n   * reaches a block without passing its kind's contract.\n   * {@link BlockStorageFacadeCallbacks.StorageInitial} stays the UI-creation path,\n   * where there are genuinely no params.\n   *\n   * Separate from `StorageInitial` rather than an optional argument to it,\n   * deliberately: a block bundled with an older SDK does not register this\n   * callback at all, so the caller sees it missing and can say so. Widening\n   * `StorageInitial` would instead have that block silently ignore the params and\n   * produce a default-initialized block that looks successfully applied.\n   *\n   * The params arrive as ordinary live params — references are `PlRef`s, already\n   * pointing at the ids the target project just assigned. Resolution happens in\n   * the engine, before this call, so a block's init factory never handles a\n   * template-local reference.\n   *\n   * Errors are returned, not thrown: a factory rejecting params it cannot use is\n   * an expected outcome for a hand-written template file, and every entry's\n   * problem is reported together.\n   *\n   * **Also where the entry's references are pointed at this project.** Params reach here\n   * exactly as the file held them: nothing between the block that exported them and this call\n   * marks a reference, reads one, or rewrites one, because recognizing one means knowing the\n   * reference system and this bundle is where that knowledge lives. `blockIdsJson` maps each\n   * template-local entry id to the block id it was given, holding the entries created so far —\n   * so an id it does not name is left alone, and a reference to an entry created later names\n   * nothing rather than naming the wrong block.\n   *\n   * Relocating and initializing are one call rather than two because every call\n   * re-instantiates the runtime and re-evaluates the whole model bundle: splitting them would\n   * parse the block twice per entry to produce an intermediate only the second half reads.\n   *\n   * @param paramsJson - The entry's params as JSON string, as the file held them\n   * @param blockIdsJson - template-local entry id → assigned block id, as a JSON object\n   * @returns Either an error, or the initial storage as JSON string\n   */\n  [BlockStorageFacadeCallbacks.StorageInitialFromParams]: (\n    paramsJson: StringifiedJson,\n    blockIdsJson: StringifiedJson,\n  ) => { error: string } | { error?: undefined; storageJson: StringifiedJson };\n\n  /**\n   * Check params against this block's kind, creating nothing.\n   *\n   * Called once per entry before a template is applied, so params a kind rejects are\n   * reported against the entry that carries them while there is still no project — the\n   * same reason references and ids are checked before construction starts. Applying\n   * without this call is safe but worse: `StorageInitialFromParams` runs the same check\n   * and refuses, by which point earlier entries have already been created.\n   *\n   * A pass carries nothing back but its own absence of error: every kind declares a\n   * parser, so a pass means the params were checked against the contract, not merely\n   * that they were valid JSON.\n   *\n   * Reference ids inside the params may be placeholders at this point: the check runs\n   * before blocks exist, so what is verified is the shape of the params, not what they\n   * point at.\n   *\n   * @param paramsJson The entry's params as JSON string\n   * @returns Why the params were rejected, or nothing\n   */\n  [BlockStorageFacadeCallbacks.InitializationParamsValidate]: (\n    paramsJson: StringifiedJson,\n  ) => { error: string } | { error?: undefined };\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;CAChB,4BAA4B;CAC5B,0BAA0B;CAC1B,8BAA8B;AAChC;;;;;AAMA,SAAS,oBACP,WAC2C;CAC3C,OAAO,OAAO,YACZ,OAAO,OAAO,SAAS,CAAC,CAAC,KAAK,WAAW,CAAC,QAAQ,mBAAmB,EAAE,OAAO,CAAC,CAAC,CAAC,CACnF;AACF;;;;;AAMA,MAAa,4BAA4B,oBAAoB,2BAA2B;;AAwLxF,SAAgB,wBAAwB,WAAqC;CAC3E,KAAK,MAAM,OAAO,OAAO,OAAO,2BAA2B,GACzD,oBAAoB,KAAK,UAAU,IAA+B;AAEtE"}

package/dist/package.cjs

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "1.81.1";
+var version = "1.82.0";
 //#endregion
 Object.defineProperty(exports, "version", {
 	enumerable: true,

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "1.81.1";
+var version = "1.82.0";
 //#endregion
 export { version };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platforma-sdk/model",
-  "version": "1.81.1",
+  "version": "1.82.0",
   "description": "Platforma.bio SDK / Block Model",
   "files": [
     "./dist/**/*",
@@ -32,10 +32,10 @@
     "utility-types": "^3.11.0",
     "zod": "~3.25.76",
     "@milaboratories/helpers": "1.14.5",
-    "@milaboratories/pl-model-middle-layer": "1.31.0",
-    "@milaboratories/ptabler-expression-js": "1.2.37",
     "@milaboratories/pl-error-like": "1.12.10",
-    "@milaboratories/pl-model-common": "1.47.3"
+    "@milaboratories/pl-model-middle-layer": "1.32.0",
+    "@milaboratories/ptabler-expression-js": "1.2.38",
+    "@milaboratories/pl-model-common": "1.48.0"
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^4.1.3",
@@ -43,11 +43,12 @@
     "typescript": "~5.9.3",
     "vitest": "^4.1.3",
     "@milaboratories/build-configs": "2.0.0",
-    "@milaboratories/pf-driver": "1.9.0",
-    "@milaboratories/columns-collection-driver": "0.2.3",
-    "@milaboratories/pf-spec-driver": "1.5.0",
-    "@milaboratories/ts-builder": "1.6.2",
-    "@milaboratories/ts-configs": "1.4.0"
+    "@milaboratories/columns-collection-driver": "0.2.4",
+    "@milaboratories/pf-driver": "1.9.1",
+    "@milaboratories/pf-spec-driver": "1.5.1",
+    "@milaboratories/ts-configs": "1.4.0",
+    "@platforma-sdk/block-kind": "1.1.0",
+    "@milaboratories/ts-builder": "1.7.0"
   },
   "scripts": {
     "build": "ts-builder build --target node",