@milaboratories/pl-middle-layer 1.45.5 → 1.46.0

package/dist/mutator/migration.js

@@ -1,6 +1,6 @@
-import { SchemaVersionKey, SchemaVersionCurrent, ProjectStructureKey, projectFieldName } from '../model/project_model.js';
+import { SchemaVersionKey, SchemaVersionCurrent, SchemaVersionV2, ProjectStructureKey, projectFieldName } from '../model/project_model.js';
 import { SchemaVersionV1, BlockFrontendStateKeyPrefixV1 } from '../model/project_model_v1.js';
-import { field } from '@milaboratories/pl-client';
+import { field, isNullResourceId } from '@milaboratories/pl-client';
 import { cachedDeserialize } from '@milaboratories/ts-helpers';
 import { allBlocks } from '../model/project_model_util.js';
 
@@ -12,13 +12,19 @@ import { allBlocks } from '../model/project_model_util.js';
  */
 async function applyProjectMigrations(pl, rid) {
     await pl.withWriteTx('ProjectMigration', async (tx) => {
-        const schemaVersion = await tx.getKValueJson(rid, SchemaVersionKey);
+        let schemaVersion = await tx.getKValueJson(rid, SchemaVersionKey);
         if (schemaVersion === SchemaVersionCurrent)
             return;
+        // Apply migrations in sequence
         if (schemaVersion === SchemaVersionV1) {
             await migrateV1ToV2(tx, rid);
+            schemaVersion = SchemaVersionV2;
         }
-        else {
+        if (schemaVersion === SchemaVersionV2) {
+            await migrateV2ToV3(tx, rid);
+        }
+        else if (schemaVersion !== SchemaVersionV1) {
+            // If we got here and it's not v1 (which was handled above), it's unknown
             throw new Error(`Unknown project schema version: ${schemaVersion}`);
         }
         tx.setKValue(rid, SchemaVersionKey, JSON.stringify(SchemaVersionCurrent));
@@ -45,11 +51,66 @@ async function migrateV1ToV2(tx, rid) {
         const uiState = kvMap.get(kvKey);
         const valueJson = uiState ? cachedDeserialize(uiState) : {};
         const uiStateR = tx.createJsonGzValue(valueJson);
-        const uiStateF = field(rid, projectFieldName(block.id, 'uiState'));
+        const uiStateF = field(rid, projectFieldName(block.id, 'blockStorage'));
         tx.createField(uiStateF, 'Dynamic', uiStateR);
         tx.deleteKValue(rid, kvKey);
     }
 }
+/**
+ * Migrates the project from schema version 2 to 3.
+ *
+ * Summary of changes:
+ * - Introduces unified 'blockStorage' field containing { args, uiState }
+ * - Adds 'currentPrerunArgs' field for staging/prerun rendering
+ * - For each block:
+ *   1. Read existing 'blockStorage' field (contains uiState in v2)
+ *   2. Read existing 'currentArgs' field (contains args)
+ *   3. Create unified state = { args: currentArgs, uiState: oldState }
+ *   4. Write to new {blockId}-blockStorage field (overwrites)
+ *   5. Initialize {blockId}-currentPrerunArgs (same as prodArgs for v1/v2 blocks)
+ * - Note: currentArgs and prodArgs fields remain for compatibility layer
+ *
+ * @param tx - The transaction to use.
+ * @param rid - The resource id of the project.
+ */
+async function migrateV2ToV3(tx, rid) {
+    const [structure, fullResourceState] = await Promise.all([
+        tx.getKValueJson(rid, ProjectStructureKey),
+        tx.getResourceData(rid, true),
+    ]);
+    // Build a map of field name -> resource id for quick lookup
+    const fieldMap = new Map();
+    for (const f of fullResourceState.fields) {
+        if (!isNullResourceId(f.value)) {
+            fieldMap.set(f.name, f.value);
+        }
+    }
+    for (const block of allBlocks(structure)) {
+        // Read existing field values
+        const uiStateFieldName = projectFieldName(block.id, 'uiState');
+        const currentArgsFieldName = projectFieldName(block.id, 'currentArgs');
+        const uiStateRid = fieldMap.get(uiStateFieldName);
+        const currentArgsRid = fieldMap.get(currentArgsFieldName);
+        // Read field data in parallel where available
+        const [uiStateData, currentArgsData] = await Promise.all([
+            uiStateRid ? tx.getResourceData(uiStateRid, false) : Promise.resolve(undefined),
+            currentArgsRid ? tx.getResourceData(currentArgsRid, false) : Promise.resolve(undefined),
+        ]);
+        // Extract values - in v2, 'blockStorage' contains raw uiState, not wrapped
+        const uiState = uiStateData?.data ? cachedDeserialize(uiStateData.data) : {};
+        const args = currentArgsData?.data ? cachedDeserialize(currentArgsData.data) : {};
+        // Create unified state: { args, uiState }
+        const unifiedState = {
+            args,
+            uiState,
+        };
+        const blockStorageFieldName = projectFieldName(block.id, 'blockStorage');
+        // Write new unified blockStorage field (overwrite existing)
+        const stateR = tx.createJsonGzValue(unifiedState);
+        const stateF = field(rid, blockStorageFieldName);
+        tx.createField(stateF, 'Dynamic', stateR);
+    }
+}
 
 export { applyProjectMigrations };
 //# sourceMappingURL=migration.js.map

package/dist/mutator/migration.js.map

@@ -1 +1 @@
-{"version":3,"file":"migration.js","sources":["../../src/mutator/migration.ts"],"sourcesContent":["import type { PlClient, PlTransaction, ResourceId } from '@milaboratories/pl-client';\nimport type { ProjectStructure } from '../model/project_model';\nimport { projectFieldName, ProjectStructureKey, SchemaVersionCurrent, SchemaVersionKey } from '../model/project_model';\nimport { BlockFrontendStateKeyPrefixV1, SchemaVersionV1 } from '../model/project_model_v1';\nimport { field } from '@milaboratories/pl-client';\nimport { cachedDeserialize } from '@milaboratories/ts-helpers';\nimport { allBlocks } from '../model/project_model_util';\n\n/**\n * Migrates the project to the latest schema version.\n *\n * @param pl - The client to use.\n * @param rid - The resource id of the project.\n */\nexport async function applyProjectMigrations(pl: PlClient, rid: ResourceId) {\n  await pl.withWriteTx('ProjectMigration', async (tx) => {\n    const schemaVersion = await tx.getKValueJson<string>(rid, SchemaVersionKey);\n    if (schemaVersion === SchemaVersionCurrent) return;\n    if (schemaVersion === SchemaVersionV1) {\n      await migrateV1ToV2(tx, rid);\n    } else {\n      throw new Error(`Unknown project schema version: ${schemaVersion}`);\n    }\n    tx.setKValue(rid, SchemaVersionKey, JSON.stringify(SchemaVersionCurrent));\n    await tx.commit();\n  });\n}\n\n/**\n * Migrates the project from schema version 1 to 2.\n *\n * Summary of changes:\n * - uiState is now stored in a field instead of a KV\n *\n * @param tx - The transaction to use.\n * @param rid - The resource id of the project.\n */\nasync function migrateV1ToV2(tx: PlTransaction, rid: ResourceId) {\n  const [structure, allKV] = await Promise.all([\n    tx.getKValueJson<ProjectStructure>(rid, ProjectStructureKey),\n    tx.listKeyValues(rid),\n  ]);\n  const kvMap = new Map<string, Uint8Array>(allKV.map((kv) => [kv.key, kv.value]));\n  for (const block of allBlocks(structure)) {\n    const kvKey = BlockFrontendStateKeyPrefixV1 + block.id;\n    const uiState = kvMap.get(kvKey);\n    const valueJson = uiState ? cachedDeserialize(uiState) : {};\n    const uiStateR = tx.createJsonGzValue(valueJson);\n    const uiStateF = field(rid, projectFieldName(block.id, 'uiState'));\n    tx.createField(uiStateF, 'Dynamic', uiStateR);\n    tx.deleteKValue(rid, kvKey);\n  }\n}\n"],"names":[],"mappings":";;;;;;AAQA;;;;;AAKG;AACI,eAAe,sBAAsB,CAAC,EAAY,EAAE,GAAe,EAAA;IACxE,MAAM,EAAE,CAAC,WAAW,CAAC,kBAAkB,EAAE,OAAO,EAAE,KAAI;QACpD,MAAM,aAAa,GAAG,MAAM,EAAE,CAAC,aAAa,CAAS,GAAG,EAAE,gBAAgB,CAAC;QAC3E,IAAI,aAAa,KAAK,oBAAoB;YAAE;AAC5C,QAAA,IAAI,aAAa,KAAK,eAAe,EAAE;AACrC,YAAA,MAAM,aAAa,CAAC,EAAE,EAAE,GAAG,CAAC;QAC9B;aAAO;AACL,YAAA,MAAM,IAAI,KAAK,CAAC,mCAAmC,aAAa,CAAA,CAAE,CAAC;QACrE;AACA,QAAA,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,gBAAgB,EAAE,IAAI,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC;AACzE,QAAA,MAAM,EAAE,CAAC,MAAM,EAAE;AACnB,IAAA,CAAC,CAAC;AACJ;AAEA;;;;;;;;AAQG;AACH,eAAe,aAAa,CAAC,EAAiB,EAAE,GAAe,EAAA;IAC7D,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;AAC3C,QAAA,EAAE,CAAC,aAAa,CAAmB,GAAG,EAAE,mBAAmB,CAAC;AAC5D,QAAA,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC;AACtB,KAAA,CAAC;IACF,MAAM,KAAK,GAAG,IAAI,GAAG,CAAqB,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAChF,KAAK,MAAM,KAAK,IAAI,SAAS,CAAC,SAAS,CAAC,EAAE;AACxC,QAAA,MAAM,KAAK,GAAG,6BAA6B,GAAG,KAAK,CAAC,EAAE;QACtD,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC;AAChC,QAAA,MAAM,SAAS,GAAG,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,GAAG,EAAE;QAC3D,MAAM,QAAQ,GAAG,EAAE,CAAC,iBAAiB,CAAC,SAAS,CAAC;AAChD,QAAA,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;QAClE,EAAE,CAAC,WAAW,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC;AAC7C,QAAA,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC;IAC7B;AACF;;;;"}
+{"version":3,"file":"migration.js","sources":["../../src/mutator/migration.ts"],"sourcesContent":["import type { PlClient, PlTransaction, ResourceId } from '@milaboratories/pl-client';\nimport type { ProjectField, ProjectStructure } from '../model/project_model';\nimport { projectFieldName, ProjectStructureKey, SchemaVersionCurrent, SchemaVersionKey, SchemaVersionV2 } from '../model/project_model';\nimport { BlockFrontendStateKeyPrefixV1, SchemaVersionV1 } from '../model/project_model_v1';\nimport { field, isNullResourceId } from '@milaboratories/pl-client';\nimport { cachedDeserialize } from '@milaboratories/ts-helpers';\nimport { allBlocks } from '../model/project_model_util';\n\n/**\n * Migrates the project to the latest schema version.\n *\n * @param pl - The client to use.\n * @param rid - The resource id of the project.\n */\nexport async function applyProjectMigrations(pl: PlClient, rid: ResourceId) {\n  await pl.withWriteTx('ProjectMigration', async (tx) => {\n    let schemaVersion = await tx.getKValueJson<string>(rid, SchemaVersionKey);\n    if (schemaVersion === SchemaVersionCurrent) return;\n\n    // Apply migrations in sequence\n    if (schemaVersion === SchemaVersionV1) {\n      await migrateV1ToV2(tx, rid);\n      schemaVersion = SchemaVersionV2;\n    }\n\n    if (schemaVersion === SchemaVersionV2) {\n      await migrateV2ToV3(tx, rid);\n    } else if (schemaVersion !== SchemaVersionV1) {\n      // If we got here and it's not v1 (which was handled above), it's unknown\n      throw new Error(`Unknown project schema version: ${schemaVersion}`);\n    }\n\n    tx.setKValue(rid, SchemaVersionKey, JSON.stringify(SchemaVersionCurrent));\n    await tx.commit();\n  });\n}\n\n/**\n * Migrates the project from schema version 1 to 2.\n *\n * Summary of changes:\n * - uiState is now stored in a field instead of a KV\n *\n * @param tx - The transaction to use.\n * @param rid - The resource id of the project.\n */\nasync function migrateV1ToV2(tx: PlTransaction, rid: ResourceId) {\n  const [structure, allKV] = await Promise.all([\n    tx.getKValueJson<ProjectStructure>(rid, ProjectStructureKey),\n    tx.listKeyValues(rid),\n  ]);\n  const kvMap = new Map<string, Uint8Array>(allKV.map((kv) => [kv.key, kv.value]));\n  for (const block of allBlocks(structure)) {\n    const kvKey = BlockFrontendStateKeyPrefixV1 + block.id;\n    const uiState = kvMap.get(kvKey);\n    const valueJson = uiState ? cachedDeserialize(uiState) : {};\n    const uiStateR = tx.createJsonGzValue(valueJson);\n    const uiStateF = field(rid, projectFieldName(block.id, 'blockStorage'));\n    tx.createField(uiStateF, 'Dynamic', uiStateR);\n    tx.deleteKValue(rid, kvKey);\n  }\n}\n\n/**\n * Migrates the project from schema version 2 to 3.\n *\n * Summary of changes:\n * - Introduces unified 'blockStorage' field containing { args, uiState }\n * - Adds 'currentPrerunArgs' field for staging/prerun rendering\n * - For each block:\n *   1. Read existing 'blockStorage' field (contains uiState in v2)\n *   2. Read existing 'currentArgs' field (contains args)\n *   3. Create unified state = { args: currentArgs, uiState: oldState }\n *   4. Write to new {blockId}-blockStorage field (overwrites)\n *   5. Initialize {blockId}-currentPrerunArgs (same as prodArgs for v1/v2 blocks)\n * - Note: currentArgs and prodArgs fields remain for compatibility layer\n *\n * @param tx - The transaction to use.\n * @param rid - The resource id of the project.\n */\nasync function migrateV2ToV3(tx: PlTransaction, rid: ResourceId) {\n  const [structure, fullResourceState] = await Promise.all([\n    tx.getKValueJson<ProjectStructure>(rid, ProjectStructureKey),\n    tx.getResourceData(rid, true),\n  ]);\n\n  // Build a map of field name -> resource id for quick lookup\n  const fieldMap = new Map<string, ResourceId>();\n  for (const f of fullResourceState.fields) {\n    if (!isNullResourceId(f.value)) {\n      fieldMap.set(f.name, f.value);\n    }\n  }\n\n  for (const block of allBlocks(structure)) {\n    // Read existing field values\n    const uiStateFieldName = projectFieldName(block.id, 'uiState' as ProjectField['fieldName']);\n    const currentArgsFieldName = projectFieldName(block.id, 'currentArgs');\n\n    const uiStateRid = fieldMap.get(uiStateFieldName);\n    const currentArgsRid = fieldMap.get(currentArgsFieldName);\n\n    // Read field data in parallel where available\n    const [uiStateData, currentArgsData] = await Promise.all([\n      uiStateRid ? tx.getResourceData(uiStateRid, false) : Promise.resolve(undefined),\n      currentArgsRid ? tx.getResourceData(currentArgsRid, false) : Promise.resolve(undefined),\n    ]);\n\n    // Extract values - in v2, 'blockStorage' contains raw uiState, not wrapped\n    const uiState = uiStateData?.data ? cachedDeserialize(uiStateData.data) : {};\n    const args = currentArgsData?.data ? cachedDeserialize(currentArgsData.data) : {};\n\n    // Create unified state: { args, uiState }\n    const unifiedState = {\n      args,\n      uiState,\n    };\n\n    const blockStorageFieldName = projectFieldName(block.id, 'blockStorage');\n\n    // Write new unified blockStorage field (overwrite existing)\n    const stateR = tx.createJsonGzValue(unifiedState);\n    const stateF = field(rid, blockStorageFieldName);\n    tx.createField(stateF, 'Dynamic', stateR);\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/mutator/project-v3.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=project-v3.test.d.ts.map

package/dist/mutator/project-v3.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-v3.test.d.ts","sourceRoot":"","sources":["../../src/mutator/project-v3.test.ts"],"names":[],"mappings":""}

package/dist/mutator/project.cjs

@@ -57,19 +57,57 @@ class BlockInfo {
             throw new Error('inconsistent stage cache fields');
         if (this.fields.blockPack === undefined)
             throw new Error('no block pack field');
-        if (this.fields.currentArgs === undefined)
-            throw new Error('no current args field');
+        if (this.fields.blockStorage === undefined)
+            throw new Error('no block storage field');
     }
-    currentArgsC = cached(() => this.fields.currentArgs.modCount, () => tsHelpers.cachedDeserialize(this.fields.currentArgs.value));
+    currentArgsC = cached(() => this.fields.currentArgs?.modCount, () => {
+        const bin = this.fields.currentArgs?.value;
+        if (bin === undefined)
+            return undefined;
+        return tsHelpers.cachedDeserialize(bin);
+    });
+    blockStorageC = cached(() => this.fields.blockStorage.modCount, () => {
+        const bin = this.fields.blockStorage?.value;
+        if (bin === undefined)
+            return undefined;
+        return tsHelpers.cachedDeserialize(bin);
+    });
+    blockStorageJ = cached(() => this.fields.blockStorage.modCount, () => {
+        const bin = this.fields.blockStorage?.value;
+        if (bin === undefined)
+            return undefined;
+        return tsHelpers.cachedDecode(bin);
+    });
     prodArgsC = cached(() => this.fields.prodArgs?.modCount, () => {
         const bin = this.fields.prodArgs?.value;
         if (bin === undefined)
             return undefined;
         return tsHelpers.cachedDeserialize(bin);
     });
+    currentPrerunArgsC = cached(() => this.fields.currentPrerunArgs?.modCount, () => {
+        const bin = this.fields.currentPrerunArgs?.value;
+        if (bin === undefined)
+            return undefined;
+        return tsHelpers.cachedDeserialize(bin);
+    });
     get currentArgs() {
         return this.currentArgsC();
     }
+    get blockStorage() {
+        try {
+            return this.blockStorageC();
+        }
+        catch (e) {
+            console.error('Error getting blockStorage:', e);
+            return undefined;
+        }
+    }
+    get blockStorageJson() {
+        return this.blockStorageJ();
+    }
+    get currentPrerunArgs() {
+        return this.currentPrerunArgsC();
+    }
     get stagingRendered() {
         return this.fields.stagingCtx !== undefined;
     }
@@ -81,12 +119,16 @@ class BlockInfo {
     }
     productionStaleC = cached(() => `${this.fields.currentArgs.modCount}_${this.fields.prodArgs?.modCount}`, () => this.fields.prodArgs === undefined
         || Buffer.compare(this.fields.currentArgs.value, this.fields.prodArgs.value) !== 0);
-    // get productionStale(): boolean {
-    //   return this.productionRendered && this.productionStaleC() && ;
-    // }
     get requireProductionRendering() {
         return !this.productionRendered || this.productionStaleC() || this.productionHasErrors;
     }
+    /** Returns true if staging should be re-rendered (stagingCtx is not set) */
+    get requireStagingRendering() {
+        // No staging needed if currentPrerunArgs is undefined (args derivation failed)
+        if (this.fields.currentPrerunArgs === undefined)
+            return false;
+        return !this.stagingRendered;
+    }
     get prodArgs() {
         return this.prodArgsC();
     }
@@ -161,7 +203,6 @@ class ProjectMutator {
             || this.renderingStateChanged);
     }
     get structure() {
-        // clone
         return JSON.parse(JSON.stringify(this.struct));
     }
     //
@@ -186,9 +227,13 @@ class ProjectMutator {
             args = bInfo.prodArgs;
         }
         else {
-            argsField = tsHelpers.notEmpty(bInfo.fields.currentArgs);
+            argsField = bInfo.fields.currentArgs;
             args = bInfo.currentArgs;
         }
+        // Can't compute enrichment targets without args
+        if (argsField === undefined) {
+            return { args, enrichmentTargets: undefined };
+        }
         const blockPackField = tsHelpers.notEmpty(bInfo.fields.blockPack);
         if (plClient.isResourceId(argsField.ref) && plClient.isResourceId(blockPackField.ref))
             return {
@@ -221,6 +266,8 @@ class ProjectMutator {
         return info;
     }
     createJsonFieldValueByContent(content) {
+        if (content === undefined)
+            throw new Error('content is undefined');
         const value = Buffer.from(content);
         const ref = this.tx.createValue(plClient.Pl.JsonObject, value);
         return { ref, value, status: 'Ready' };
@@ -321,6 +368,62 @@ class ProjectMutator {
             return this.deleteBlockFields(blockId, 'prodOutput', 'prodCtx', 'prodUiCtx', 'prodArgs', 'prodOutputPrevious', 'prodCtxPrevious', 'prodUiCtxPrevious');
         }
     }
+    /**
+     * Gets current block state and merges with partial updates.
+     * Used by legacy v1/v2 methods like setBlockArgs and setUiState.
+     *
+     * @param blockId The block to get state for
+     * @param partialUpdate Partial state to merge (e.g. { args } or { uiState })
+     * @returns Merged state in unified format { args, uiState }
+     */
+    mergeBlockState(blockId, partialUpdate) {
+        const info = this.getBlockInfo(blockId);
+        const currentState = info.blockStorage;
+        return { ...currentState, ...partialUpdate };
+    }
+    /**
+     * Sets raw block storage content directly (for testing purposes).
+     * This bypasses all normalization and VM transformations.
+     *
+     * @param blockId The block to set storage for
+     * @param rawStorageJson Raw storage as JSON string
+     */
+    setBlockStorageRaw(blockId, rawStorageJson) {
+        this.setBlockFieldObj(blockId, 'blockStorage', this.createJsonFieldValueByContent(rawStorageJson));
+        this.blocksWithChangedInputs.add(blockId);
+        this.updateLastModified();
+    }
+    /**
+     * Resets a v2+ block to its initial storage state.
+     * Gets initial storage from VM and derives args from it.
+     *
+     * For v1 blocks, use setStates() instead.
+     *
+     * @param blockId The block to reset
+     */
+    resetToInitialStorage(blockId) {
+        const info = this.getBlockInfo(blockId);
+        const blockConfig = info.config;
+        if (blockConfig.modelAPIVersion !== 2) {
+            throw new Error('resetToInitialStorage is only supported for model API version 2');
+        }
+        // Get initial storage from VM
+        const initialStorageJson = this.projectHelper.getInitialStorageInVM(blockConfig);
+        this.setBlockStorageRaw(blockId, initialStorageJson);
+        // Derive args from storage - set or clear currentArgs based on derivation result
+        const deriveArgsResult = this.projectHelper.deriveArgsFromStorage(blockConfig, initialStorageJson);
+        if (!deriveArgsResult.error) {
+            this.setBlockFieldObj(blockId, 'currentArgs', this.createJsonFieldValue(deriveArgsResult.value));
+            // Derive prerunArgs from storage
+            const prerunArgs = this.projectHelper.derivePrerunArgsFromStorage(blockConfig, initialStorageJson);
+            if (prerunArgs !== undefined) {
+                this.setBlockFieldObj(blockId, 'currentPrerunArgs', this.createJsonFieldValue(prerunArgs));
+            }
+        }
+        else {
+            this.deleteBlockFields(blockId, 'currentArgs');
+        }
+    }
     /** Optimally sets inputs for multiple blocks in one go */
     setStates(requests) {
         const changedArgs = [];
@@ -328,32 +431,76 @@ class ProjectMutator {
         for (const req of requests) {
             const info = this.getBlockInfo(req.blockId);
             let blockChanged = false;
-            for (const stateKey of ['args', 'uiState']) {
-                if (!(stateKey in req))
-                    continue;
-                const statePart = req[stateKey];
-                if (statePart === undefined || statePart === null)
-                    throw new Error(`Can't set ${stateKey} to null or undefined, please omit the key if you don't want to change it`);
-                const fieldName = stateKey === 'args' ? 'currentArgs' : 'uiState';
-                let data;
-                let gzipped = false;
-                if (stateKey === 'args') {
-                    // don't gzip args, workflow code can't uncompress gzip yet
-                    data = tsHelpers.canonicalJsonBytes(statePart);
+            const blockConfig = info.config;
+            // modelAPIVersion === 2 means BlockModelV3 with .args() lambda for deriving args
+            if (req.modelAPIVersion !== blockConfig.modelAPIVersion) {
+                throw new Error(`Model API version mismatch for block ${req.blockId}: ${req.modelAPIVersion} !== ${blockConfig.modelAPIVersion}`);
+            }
+            // Derive args from storage using the block's config.args() callback
+            let args;
+            let prerunArgs;
+            if (req.modelAPIVersion === 2) {
+                const currentStorageJson = info.blockStorageJson;
+                if (currentStorageJson === undefined) {
+                    throw new Error(`Block ${req.blockId} has no blockStorage - this should not happen`);
+                }
+                // Apply the state update to storage
+                const updatedStorageJson = this.projectHelper.applyStorageUpdateInVM(blockConfig, currentStorageJson, req.payload);
+                this.setBlockFieldObj(req.blockId, 'blockStorage', this.createJsonFieldValueByContent(updatedStorageJson));
+                // Derive args directly from storage (VM extracts data internally)
+                const derivedArgsResult = this.projectHelper.deriveArgsFromStorage(blockConfig, updatedStorageJson);
+                if (derivedArgsResult.error) {
+                    args = undefined;
+                    prerunArgs = undefined;
                 }
                 else {
-                    const { data: binary, isGzipped } = tsHelpers.canonicalJsonGzBytes(statePart);
-                    data = binary;
-                    gzipped = isGzipped;
+                    args = derivedArgsResult.value;
+                    // Derive prerunArgs from storage, or fall back to args
+                    prerunArgs = this.projectHelper.derivePrerunArgsFromStorage(blockConfig, updatedStorageJson);
                 }
-                if (Buffer.compare(info.fields[fieldName].value, data) === 0)
-                    continue;
-                // console.log('setting', fieldName, gzipped, data.length);
-                const statePartRef = this.tx.createValue(gzipped ? plClient.Pl.JsonGzObject : plClient.Pl.JsonObject, data);
-                this.setBlockField(req.blockId, fieldName, statePartRef, 'Ready', data);
-                blockChanged = true;
-                if (stateKey === 'args')
-                    changedArgs.push(req.blockId);
+            }
+            else {
+                this.setBlockFieldObj(req.blockId, 'blockStorage', this.createJsonFieldValue(req.state));
+                if (req.state !== null && typeof req.state === 'object' && 'args' in req.state) {
+                    args = req.state.args;
+                }
+                else {
+                    args = req.state;
+                }
+                // For the legacy blocks, prerunArgs = args (same as production args)
+                prerunArgs = args;
+            }
+            // Set or clear currentArgs based on derivation result
+            if (args !== undefined) {
+                const currentArgsData = tsHelpers.canonicalJsonBytes(args);
+                const argsPartRef = this.tx.createValue(plClient.Pl.JsonObject, currentArgsData);
+                this.setBlockField(req.blockId, 'currentArgs', argsPartRef, 'Ready', currentArgsData);
+            }
+            else {
+                this.deleteBlockFields(req.blockId, 'currentArgs');
+            }
+            // Set currentPrerunArgs field and check if it actually changed
+            let prerunArgsChanged = false;
+            if (prerunArgs !== undefined) {
+                const prerunArgsData = tsHelpers.canonicalJsonBytes(prerunArgs);
+                const oldPrerunArgsData = info.fields.currentPrerunArgs?.value;
+                // Check if prerunArgs actually changed
+                if (oldPrerunArgsData === undefined || Buffer.compare(oldPrerunArgsData, prerunArgsData) !== 0) {
+                    prerunArgsChanged = true;
+                }
+                const prerunArgsRef = this.tx.createValue(plClient.Pl.JsonObject, prerunArgsData);
+                this.setBlockField(req.blockId, 'currentPrerunArgs', prerunArgsRef, 'Ready', prerunArgsData);
+            }
+            else {
+                // prerunArgs is undefined - check if we previously had one
+                if (info.fields.currentPrerunArgs !== undefined) {
+                    prerunArgsChanged = true;
+                }
+            }
+            blockChanged = true;
+            // Only add to changedArgs if prerunArgs changed - this controls staging reset
+            if (prerunArgsChanged) {
+                changedArgs.push(req.blockId);
             }
             if (blockChanged) {
                 // will be assigned our author marker
@@ -395,15 +542,25 @@ class ProjectMutator {
     exportCtx(ctx) {
         return context_export.exportContext(this.tx, plClient.Pl.unwrapHolder(this.tx, this.ctxExportTplHolder), ctx);
     }
+    /**
+     * Renders staging for a block using currentPrerunArgs.
+     * If currentPrerunArgs is not set (prerunArgs returned undefined), skips staging for this block.
+     */
     renderStagingFor(blockId) {
         this.resetStaging(blockId);
         const info = this.getBlockInfo(blockId);
+        // If currentPrerunArgs is not set (prerunArgs returned undefined), skip staging for this block
+        const prerunArgsRef = info.fields.currentPrerunArgs?.ref;
+        if (prerunArgsRef === undefined) {
+            return;
+        }
         const ctx = this.createStagingCtx(this.getStagingGraph().nodes.get(blockId).upstream);
         if (this.getBlock(blockId).renderingMode !== 'Heavy')
             throw new Error('not supported yet');
         const tpl = info.getTemplate(this.tx);
+        // Use currentPrerunArgs for staging rendering
         const results = render_block.createRenderHeavyBlock(this.tx, tpl, {
-            args: info.fields.currentArgs.ref,
+            args: prerunArgsRef,
             blockId: this.tx.createValue(plClient.Pl.JsonString, JSON.stringify(blockId)),
             isProduction: this.tx.createValue(plClient.Pl.JsonBool, JSON.stringify(false)),
             context: ctx,
@@ -420,6 +577,10 @@ class ProjectMutator {
     renderProductionFor(blockId) {
         this.resetProduction(blockId);
         const info = this.getBlockInfo(blockId);
+        // Can't render production if currentArgs is not set
+        if (info.fields.currentArgs === undefined) {
+            throw new Error(`Can't render production for block ${blockId}: currentArgs not set`);
+        }
         const ctx = this.createProdCtx(this.getPendingProductionGraph().nodes.get(blockId).upstream);
         if (this.getBlock(blockId).renderingMode === 'Light')
             throw new Error('Can\'t render production for light block.');
@@ -450,10 +611,47 @@ class ProjectMutator {
         this.setBlockField(blockId, 'blockPack', plClient.Pl.wrapInHolder(this.tx, bp), 'NotReady');
         // settings
         this.setBlockFieldObj(blockId, 'blockSettings', this.createJsonFieldValue(plModelMiddleLayer.InitialBlockSettings));
-        // args
-        this.setBlockFieldObj(blockId, 'currentArgs', this.createJsonFieldValueByContent(spec.args));
-        // uiState
-        this.setBlockFieldObj(blockId, 'uiState', this.createJsonFieldValueByContent(spec.uiState ?? '{}'));
+        const blockConfig = info.config;
+        let args;
+        let prerunArgs;
+        let storageToWrite;
+        if (spec.storageMode === 'fromModel') {
+            // Model API v2+: get initial storage and derive args from it
+            storageToWrite = this.projectHelper.getInitialStorageInVM(blockConfig);
+            // Derive args directly from storage (VM extracts data internally)
+            const deriveArgsResult = this.projectHelper.deriveArgsFromStorage(blockConfig, storageToWrite);
+            if (deriveArgsResult.error) {
+                args = undefined;
+                prerunArgs = undefined;
+            }
+            else {
+                args = deriveArgsResult.value;
+                prerunArgs = this.projectHelper.derivePrerunArgsFromStorage(blockConfig, storageToWrite);
+            }
+        }
+        else if (spec.storageMode === 'legacy') {
+            // Model API v1: use legacyState from spec
+            const parsedState = JSON.parse(spec.legacyState);
+            args = parsedState.args;
+            if (args === undefined) {
+                throw new Error('args is undefined in legacyState');
+            }
+            prerunArgs = args;
+            storageToWrite = spec.legacyState;
+        }
+        else {
+            throw new Error(`Unknown storageMode: ${spec.storageMode}`);
+        }
+        // currentArgs
+        if (args !== undefined) {
+            this.setBlockFieldObj(blockId, 'currentArgs', this.createJsonFieldValue(args));
+        }
+        // currentPrerunArgs
+        if (prerunArgs !== undefined) {
+            this.setBlockFieldObj(blockId, 'currentPrerunArgs', this.createJsonFieldValue(prerunArgs));
+        }
+        // blockStorage
+        this.setBlockFieldObj(blockId, 'blockStorage', this.createJsonFieldValueByContent(storageToWrite));
         // checking structure
         info.check();
     }
@@ -629,14 +827,53 @@ class ProjectMutator {
     //
     // Block-pack migration
     //
-    migrateBlockPack(blockId, spec, newArgsAndUiState) {
+    migrateBlockPack(blockId, spec, newClearState) {
         const info = this.getBlockInfo(blockId);
+        const newConfig = model.extractConfig(spec.config);
         this.setBlockField(blockId, 'blockPack', plClient.Pl.wrapInHolder(this.tx, block_pack.createBlockPack(this.tx, spec)), 'NotReady');
-        if (newArgsAndUiState !== undefined) {
-            // this will also reset all downstream stagings
-            this.setStates([{ blockId, args: newArgsAndUiState.args, uiState: newArgsAndUiState.uiState }]);
+        if (newClearState !== undefined) {
+            // State is being reset - no migration needed
+            const supportsStorageFromVM = newConfig.modelAPIVersion === 2;
+            if (supportsStorageFromVM) {
+                // V2+: Get initial storage directly from VM and derive args from it
+                const initialStorageJson = this.projectHelper.getInitialStorageInVM(newConfig);
+                this.setBlockStorageRaw(blockId, initialStorageJson);
+                // Derive args from storage - only set currentArgs if derivation succeeds
+                const deriveArgsResult = this.projectHelper.deriveArgsFromStorage(newConfig, initialStorageJson);
+                if (!deriveArgsResult.error) {
+                    this.setBlockFieldObj(blockId, 'currentArgs', this.createJsonFieldValue(deriveArgsResult.value));
+                    // Derive prerunArgs from storage
+                    const prerunArgs = this.projectHelper.derivePrerunArgsFromStorage(newConfig, initialStorageJson);
+                    if (prerunArgs !== undefined) {
+                        this.setBlockFieldObj(blockId, 'currentPrerunArgs', this.createJsonFieldValue(prerunArgs));
+                    }
+                }
+                this.blocksWithChangedInputs.add(blockId);
+                this.updateLastModified();
+            }
+            else {
+                // V1: Use setStates with legacy state format
+                this.setStates([{ modelAPIVersion: 1, blockId, state: newClearState.state }]);
+            }
         }
         else {
+            // State is being preserved - run migrations if needed via VM
+            // Only Model API v2 blocks support migrations
+            const supportsStateMigrations = newConfig.modelAPIVersion === 2;
+            if (supportsStateMigrations) {
+                const currentStorageJson = info.blockStorageJson;
+                const migrationResult = this.projectHelper.migrateStorageInVM(newConfig, currentStorageJson);
+                if (migrationResult.error !== undefined) {
+                    console.error(`[migrateBlockPack] Block ${blockId} migration error: ${migrationResult.error}`);
+                }
+                else {
+                    console.log(`[migrateBlockPack] Block ${blockId}: ${migrationResult.info}`);
+                    if (migrationResult.warn) {
+                        console.warn(`[migrateBlockPack] Block ${blockId} migration warning: ${migrationResult.warn}`);
+                    }
+                    this.setBlockStorageRaw(blockId, migrationResult.newStorageJson);
+                }
+            }
             // resetting staging outputs for all downstream blocks
             this.getStagingGraph().traverse('downstream', [blockId], ({ id }) => this.resetStaging(id));
         }
@@ -737,13 +974,16 @@ class ProjectMutator {
         const stagingGraph = this.getStagingGraph();
         stagingGraph.nodes.forEach((node) => {
             const info = this.getBlockInfo(node.id);
-            let lag = info.stagingRendered ? 0 : 1;
+            // Use requireStagingRendering to check both: staging exists AND prerunArgs hasn't changed
+            const requiresRendering = info.requireStagingRendering;
+            let lag = requiresRendering ? 1 : 0;
             node.upstream.forEach((upstream) => {
                 const upstreamLag = lags.get(upstream);
                 if (upstreamLag === 0)
                     return;
                 lag = Math.max(upstreamLag + 1, lag);
             });
+            if (!requiresRendering && info.stagingRendered) ;
             cb(node.id, lag);
             lags.set(node.id, lag);
         });
@@ -760,6 +1000,7 @@ class ProjectMutator {
                 // meaning staging already rendered
                 return;
             if (lagThreshold === undefined || lag <= lagThreshold) {
+                // console.log(`[refreshStagings] RENDER staging for ${blockId} (lag=${lag})`);
                 this.renderStagingFor(blockId);
                 rendered++;
             }