@milaboratories/pl-middle-layer 1.38.0 → 1.39.0

package/dist/js_render/index.d.ts

@@ -3,6 +3,54 @@ import { BlockCodeWithInfo, ConfigRenderLambda } from '@platforma-sdk/model';
 import { ComputableRenderingOps, Computable } from '@milaboratories/computable';
 import { QuickJSWASMModule } from 'quickjs-emscripten';
 import { BlockContextAny } from '../middle_layer/block_ctx';
+/**
+ * Creates a Computable that executes a render function (`fh`) from a block's code in a QuickJS virtual machine.
+ * This function handles both synchronous and asynchronous execution patterns of the sandboxed JS code.
+ *
+ * The overall data flow is as follows:
+ * 1. A QuickJS VM is initialized.
+ * 2. A `JsExecutionContext` is created to bridge the host (TypeScript) and guest (QuickJS) environments. It injects a
+ *    context object (`cfgRenderCtx`) into the VM, providing helper methods for the sandboxed code to interact with the
+ *    platform (e.g., to request data).
+ * 3. The block's Javascript bundle is evaluated in the VM.
+ * 4. The specified render function (`fh.handle`) is executed.
+ *
+ * Two execution paths are possible depending on the behavior of the render function:
+ *
+ * ### Synchronous Path
+ * If the render function computes its result without requesting any external data requiring asynchronous calculations,
+ * it executes synchronously.
+ * - The `computablesToResolve` map in `JsExecutionContext` remains empty.
+ * - The function returns an object with an `ir` field holding the result (`{ ir: importedResult }`).
+ *   Since `postprocessValue` is not specified, `ir` is treated as the final resolved value of the Computable.
+ * - The QuickJS VM is disposed of immediately as it's no longer needed.
+ *
+ * ### Asynchronous Path (with `postprocessValue`)
+ * If the render function needs external data requiring asynchronous calculations (e.g., fetching a file), it calls
+ * one of the injected helper methods. These methods don't return data directly. Instead, they:
+ *  a. Create a new `Computable` for the data request (e.g., to fetch a blob).
+ *  b. Register this new `Computable` in the `computablesToResolve` map.
+ *  c. Return a handle (string) to the sandboxed code.
+ *
+ * In this case:
+ * - The initial execution of the render function returns a scaffold of the final result, which depends on the pending
+ *   computables.
+ * - The `computablesToResolve` map is passed as the `ir` (initial result) to `Computable.makeRaw`.
+ * - The `postprocessValue` function is provided to handle the results once the computables are resolved.
+ * - The QuickJS VM is kept alive (`keepVmAlive = true`) because its state is needed in `postprocessValue`.
+ * - Once the `computable` framework resolves all dependencies, it calls `postprocessValue` with the resolved data.
+ * - `postprocessValue` feeds the resolved data back into the VM, allowing the sandboxed code to compute the final
+ *   result.
+ * - The VM is eventually disposed of when the host Computable is destroyed.
+ *
+ * @param env The middle layer environment.
+ * @param ctx The block context.
+ * @param fh The config render lambda to execute.
+ * @param codeWithInfo The block's code and feature flags.
+ * @param configKey A key for the configuration, used for cache busting.
+ * @param ops Options for the computable.
+ * @returns A `Computable` that will resolve to the result of the lambda execution.
+ */
 export declare function computableFromRF(env: MiddleLayerEnvironment, ctx: BlockContextAny, fh: ConfigRenderLambda, codeWithInfo: BlockCodeWithInfo, configKey: string, ops?: Partial<ComputableRenderingOps>): Computable<unknown>;
 export declare function executeSingleLambda(quickJs: QuickJSWASMModule, fh: ConfigRenderLambda, codeWithInfo: BlockCodeWithInfo, ...args: unknown[]): unknown;
 //# sourceMappingURL=index.d.ts.map

package/dist/js_render/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/js_render/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAI5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAGjE,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,sBAAsB,EAC3B,GAAG,EAAE,eAAe,EACpB,EAAE,EAAE,kBAAkB,EACtB,YAAY,EAAE,iBAAiB,EAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,OAAO,CAAC,sBAAsB,CAAM,GACxC,UAAU,CAAC,OAAO,CAAC,CAiErB;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,iBAAiB,EAC1B,EAAE,EAAE,kBAAkB,EACtB,YAAY,EAAE,iBAAiB,EAC/B,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CA4BT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/js_render/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAI5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAYjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,sBAAsB,EAC3B,GAAG,EAAE,eAAe,EACpB,EAAE,EAAE,kBAAkB,EACtB,YAAY,EAAE,iBAAiB,EAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,OAAO,CAAC,sBAAsB,CAAM,GACxC,UAAU,CAAC,OAAO,CAAC,CA4ErB;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,iBAAiB,EAC1B,EAAE,EAAE,kBAAkB,EACtB,YAAY,EAAE,iBAAiB,EAC/B,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CA4BT"}

package/dist/pool/driver.d.ts

@@ -3,6 +3,7 @@ import { PlTreeNodeAccessor } from '@milaboratories/pl-tree';
 import { ComputableCtx } from '@milaboratories/computable';
 import { CalculateTableDataRequest, CalculateTableDataResponse, FindColumnsRequest, FindColumnsResponse, PColumnIdAndSpec, PColumnSpec, PFrameHandle, PObjectId, PTableColumnSpec, PTableHandle, PTableShape, PTableVector, TableRange, UniqueValuesRequest, UniqueValuesResponse, PFrameDriver as SdkPFrameDriver, PColumn, PFrameDef, PTableDef, PColumnValues, DataInfo } from '@platforma-sdk/model';
 import { MiLogger } from '@milaboratories/ts-helpers';
+export type PColumnDataUniversal = PlTreeNodeAccessor | DataInfo<PlTreeNodeAccessor> | PColumnValues;
 /**
  * Extends public and safe SDK's driver API with methods used internally in the middle
  * layer and in tests.
@@ -17,9 +18,9 @@ export interface InternalPFrameDriver extends SdkPFrameDriver {
      */
     pprofDump(): Promise<Uint8Array>;
     /** Create a new PFrame */
-    createPFrame(def: PFrameDef<PlTreeNodeAccessor | PColumnValues | DataInfo<PlTreeNodeAccessor>>, ctx: ComputableCtx): PFrameHandle;
+    createPFrame(def: PFrameDef<PColumnDataUniversal>, ctx: ComputableCtx): PFrameHandle;
     /** Create a new PTable */
-    createPTable(def: PTableDef<PColumn<PlTreeNodeAccessor | PColumnValues | DataInfo<PlTreeNodeAccessor>>>, ctx: ComputableCtx): PTableHandle;
+    createPTable(def: PTableDef<PColumn<PColumnDataUniversal>>, ctx: ComputableCtx): PTableHandle;
     /** Calculates data for the table and returns complete data representation of it */
     calculateTableData(handle: PFrameHandle, request: CalculateTableDataRequest<PObjectId>, range: TableRange | undefined, signal?: AbortSignal): Promise<CalculateTableDataResponse>;
     /** Calculate set of unique values for a specific axis for the filtered set of records */
@@ -47,8 +48,8 @@ export declare class PFrameDriver implements InternalPFrameDriver {
     pprofDump(): Promise<Uint8Array>;
     static init(blobDriver: DownloadDriver, logger: MiLogger, spillPath: string): Promise<PFrameDriver>;
     private constructor();
-    createPFrame(def: PFrameDef<PlTreeNodeAccessor | PColumnValues | DataInfo<PlTreeNodeAccessor>>, ctx: ComputableCtx): PFrameHandle;
-    createPTable(rawDef: PTableDef<PColumn<PlTreeNodeAccessor | PColumnValues | DataInfo<PlTreeNodeAccessor>>>, ctx: ComputableCtx): PTableHandle;
+    createPFrame(def: PFrameDef<PColumnDataUniversal>, ctx: ComputableCtx): PFrameHandle;
+    createPTable(rawDef: PTableDef<PColumn<PColumnDataUniversal>>, ctx: ComputableCtx): PTableHandle;
     findColumns(handle: PFrameHandle, request: FindColumnsRequest): Promise<FindColumnsResponse>;
     getColumnSpec(handle: PFrameHandle, columnId: PObjectId): Promise<PColumnSpec>;
     listColumns(handle: PFrameHandle): Promise<PColumnIdAndSpec[]>;

package/dist/pool/driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/pool/driver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/pool/driver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,KAAK,EAAE,kBAAkB,EAAgB,MAAM,yBAAyB,CAAC;AAEhF,OAAO,KAAK,EAAE,aAAa,EAA2B,MAAM,4BAA4B,CAAC;AACzF,OAAO,KAAK,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,kBAAkB,EAClB,mBAAmB,EAEnB,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,UAAU,EACV,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,IAAI,eAAe,EAC/B,OAAO,EACP,SAAS,EAET,SAAS,EAIT,aAAa,EACb,QAAQ,EAET,MAAM,sBAAsB,CAAC;AAc9B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAQ3D,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GAAG,QAAQ,CAAC,kBAAkB,CAAC,GAAG,aAAa,CAAC;AA+KrG;;;GAGG;AACH,MAAM,WAAW,oBAAqB,SAAQ,eAAe;IAC3D;;;;;;OAMG;IACH,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAEjC,0BAA0B;IAC1B,YAAY,CACV,GAAG,EAAE,SAAS,CAAC,oBAAoB,CAAC,EACpC,GAAG,EAAE,aAAa,GACjB,YAAY,CAAC;IAEhB,0BAA0B;IAC1B,YAAY,CACV,GAAG,EAAE,SAAS,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC,EAC7C,GAAG,EAAE,aAAa,GACjB,YAAY,CAAC;IAEhB,mFAAmF;IACnF,kBAAkB,CAChB,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,yBAAyB,CAAC,SAAS,CAAC,EAC7C,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAEvC,yFAAyF;IACzF,eAAe,CACb,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,mBAAmB,EAC5B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEjC,0BAA0B;IAC1B,QAAQ,CACN,MAAM,EAAE,YAAY,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB;;;;;;;SAOK;IACL,OAAO,CACL,MAAM,EAAE,YAAY,EACpB,aAAa,EAAE,MAAM,EAAE,EACvB,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAC5B;AAED,qBAAa,YAAa,YAAW,oBAAoB;IAqBrD,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAtB5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyD;IACjF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoD;IAC5E,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAA8B;IACtE,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAA8B;IAEzD,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC;WAIzB,IAAI,CACtB,UAAU,EAAE,cAAc,EAC1B,MAAM,EAAE,QAAQ,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,YAAY,CAAC;IAMxB,OAAO;IA+FA,YAAY,CACjB,GAAG,EAAE,SAAS,CAAC,oBAAoB,CAAC,EACpC,GAAG,EAAE,aAAa,GACjB,YAAY;IAiBR,YAAY,CACjB,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC,EAChD,GAAG,EAAE,aAAa,GACjB,YAAY;IAoBF,WAAW,CACtB,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,mBAAmB,CAAC;IA4BlB,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;IAK9E,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAK9D,kBAAkB,CAC7B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,yBAAyB,CAAC,SAAS,CAAC,EAC7C,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,0BAA0B,CAAC;IA2BzB,eAAe,CAC1B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,mBAAmB,EAC5B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC;IAwBzB,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAUpD,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAW1E,OAAO,CAClB,MAAM,EAAE,YAAY,EACpB,aAAa,EAAE,MAAM,EAAE,EACvB,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,YAAY,EAAE,CAAC;CAW3B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-middle-layer",
-  "version": "1.38.0",
+  "version": "1.39.0",
   "description": "Pl Middle Layer",
   "engines": {
     "node": ">=20.16.0"
@@ -22,7 +22,7 @@
   "keywords": [],
   "license": "UNLICENSED",
   "dependencies": {
-    "@milaboratories/pframes-rs-node": "1.0.47",
+    "@milaboratories/pframes-rs-node": "1.0.49",
     "canonicalize": "~2.1.0",
     "denque": "^2.1.0",
     "lru-cache": "^11.1.0",
@@ -33,21 +33,21 @@
     "zod": "~3.23.8",
     "remeda": "^2.22.6",
     "@milaboratories/pl-http": "^1.1.4",
+    "@platforma-sdk/block-tools": "^2.5.63",
     "@milaboratories/resolve-helper": "^1.1.0",
     "@milaboratories/pl-client": "^2.11.2",
     "@milaboratories/pl-drivers": "^1.6.0",
-    "@milaboratories/computable": "^2.6.0",
-    "@platforma-sdk/block-tools": "^2.5.62",
-    "@milaboratories/pl-model-middle-layer": "~1.7.44",
+    "@platforma-sdk/model": "~1.39.0",
     "@milaboratories/pl-model-common": "~1.16.0",
+    "@milaboratories/computable": "^2.6.0",
     "@milaboratories/pl-tree": "~1.7.0",
-    "@platforma-sdk/model": "~1.39.0",
-    "@milaboratories/pl-config": "^1.6.1",
-    "@milaboratories/ts-helpers": "^1.4.1",
-    "@milaboratories/pl-errors": "^1.1.9",
     "@platforma-sdk/workflow-tengo": "4.9.2",
     "@milaboratories/pl-model-backend": "~1.1.2",
-    "@milaboratories/pl-deployments": "^2.4.3"
+    "@milaboratories/pl-model-middle-layer": "~1.7.45",
+    "@milaboratories/pl-errors": "^1.1.9",
+    "@milaboratories/pl-config": "^1.6.1",
+    "@milaboratories/pl-deployments": "^2.4.3",
+    "@milaboratories/ts-helpers": "^1.4.1"
   },
   "devDependencies": {
     "semver": "^7.7.2",

package/src/js_render/index.ts

@@ -9,6 +9,63 @@ import { JsExecutionContext } from './context';
 import type { BlockContextAny } from '../middle_layer/block_ctx';
 import { getDebugFlags } from '../debug';
 
+function logOutputStatus(handle: string, renderedResult: unknown, stable: boolean, recalculationCounter: number, unstableMarker?: string) {
+  if (getDebugFlags().logOutputStatus && (getDebugFlags().logOutputStatus === 'any' || !stable)) {
+    if (stable)
+      console.log(`Stable output ${handle} calculated ${renderedResult !== undefined ? 'defined' : 'undefined'}; (#${recalculationCounter})`);
+    else
+      console.log(`Unstable output ${handle}; marker = ${unstableMarker}; ${renderedResult !== undefined ? 'defined' : 'undefined'} (#${recalculationCounter})`);
+  }
+}
+
+/**
+ * Creates a Computable that executes a render function (`fh`) from a block's code in a QuickJS virtual machine.
+ * This function handles both synchronous and asynchronous execution patterns of the sandboxed JS code.
+ *
+ * The overall data flow is as follows:
+ * 1. A QuickJS VM is initialized.
+ * 2. A `JsExecutionContext` is created to bridge the host (TypeScript) and guest (QuickJS) environments. It injects a
+ *    context object (`cfgRenderCtx`) into the VM, providing helper methods for the sandboxed code to interact with the
+ *    platform (e.g., to request data).
+ * 3. The block's Javascript bundle is evaluated in the VM.
+ * 4. The specified render function (`fh.handle`) is executed.
+ *
+ * Two execution paths are possible depending on the behavior of the render function:
+ *
+ * ### Synchronous Path
+ * If the render function computes its result without requesting any external data requiring asynchronous calculations,
+ * it executes synchronously.
+ * - The `computablesToResolve` map in `JsExecutionContext` remains empty.
+ * - The function returns an object with an `ir` field holding the result (`{ ir: importedResult }`).
+ *   Since `postprocessValue` is not specified, `ir` is treated as the final resolved value of the Computable.
+ * - The QuickJS VM is disposed of immediately as it's no longer needed.
+ *
+ * ### Asynchronous Path (with `postprocessValue`)
+ * If the render function needs external data requiring asynchronous calculations (e.g., fetching a file), it calls
+ * one of the injected helper methods. These methods don't return data directly. Instead, they:
+ *  a. Create a new `Computable` for the data request (e.g., to fetch a blob).
+ *  b. Register this new `Computable` in the `computablesToResolve` map.
+ *  c. Return a handle (string) to the sandboxed code.
+ *
+ * In this case:
+ * - The initial execution of the render function returns a scaffold of the final result, which depends on the pending
+ *   computables.
+ * - The `computablesToResolve` map is passed as the `ir` (initial result) to `Computable.makeRaw`.
+ * - The `postprocessValue` function is provided to handle the results once the computables are resolved.
+ * - The QuickJS VM is kept alive (`keepVmAlive = true`) because its state is needed in `postprocessValue`.
+ * - Once the `computable` framework resolves all dependencies, it calls `postprocessValue` with the resolved data.
+ * - `postprocessValue` feeds the resolved data back into the VM, allowing the sandboxed code to compute the final
+ *   result.
+ * - The VM is eventually disposed of when the host Computable is destroyed.
+ *
+ * @param env The middle layer environment.
+ * @param ctx The block context.
+ * @param fh The config render lambda to execute.
+ * @param codeWithInfo The block's code and feature flags.
+ * @param configKey A key for the configuration, used for cache busting.
+ * @param ops Options for the computable.
+ * @returns A `Computable` that will resolve to the result of the lambda execution.
+ */
 export function computableFromRF(
   env: MiddleLayerEnvironment,
   ctx: BlockContextAny,
@@ -27,59 +84,70 @@ export function computableFromRF(
       console.log(`Block lambda recalculation : ${key} (${cCtx.changeSourceMarker}; ${cCtx.bodyInvocations} invocations)`);
 
     const scope = new Scope();
-    cCtx.addOnDestroy(() => scope.dispose());
-
-    const runtime = scope.manage(env.quickJs.newRuntime());
-    runtime.setMemoryLimit(1024 * 1024 * 8);
-    runtime.setMaxStackSize(1024 * 320);
-
-    let deadlineSettings: DeadlineSettings | undefined;
-    runtime.setInterruptHandler(() => {
-      if (deadlineSettings === undefined) return false;
-      if (Date.now() > deadlineSettings.deadline) return true;
-      return false;
+    let keepVmAlive = false;
+    cCtx.addOnDestroy(() => {
+      // If keepVmAlive is false, the scope will be disposed by the finally block,
+      // no need to dispose it here.
+      if (keepVmAlive) scope.dispose();
     });
-    const vm = scope.manage(runtime.newContext());
-    const rCtx = new JsExecutionContext(scope, vm,
-      (s) => { deadlineSettings = s; },
-      featureFlags,
-      { computableCtx: cCtx, blockCtx: ctx, mlEnv: env });
-
-    rCtx.evaluateBundle(code.content);
-    const result = rCtx.runCallback(fh.handle);
-
-    rCtx.resetComputableCtx();
-
-    let recalculationCounter = 0;
-
-    if (getDebugFlags().logOutputStatus === 'any')
-      console.log(`Output ${fh.handle} scaffold calculated.`);
 
-    return {
-      ir: rCtx.computableHelper!.computablesToResolve,
-      postprocessValue: (resolved: Record<string, unknown>, { unstableMarker, stable }) => {
+    try {
+      const runtime = scope.manage(env.quickJs.newRuntime());
+      runtime.setMemoryLimit(1024 * 1024 * 8);
+      runtime.setMaxStackSize(1024 * 320);
+
+      let deadlineSettings: DeadlineSettings | undefined;
+      runtime.setInterruptHandler(() => {
+        if (deadlineSettings === undefined) return false;
+        if (Date.now() > deadlineSettings.deadline) return true;
+        return false;
+      });
+      const vm = scope.manage(runtime.newContext());
+      const rCtx = new JsExecutionContext(scope, vm,
+        (s) => { deadlineSettings = s; },
+        featureFlags,
+        { computableCtx: cCtx, blockCtx: ctx, mlEnv: env });
+
+      rCtx.evaluateBundle(code.content);
+      const result = rCtx.runCallback(fh.handle);
+
+      rCtx.resetComputableCtx();
+
+      const toBeResolved = rCtx.computableHelper!.computablesToResolve;
+
+      if (Object.keys(toBeResolved).length === 0) {
+        const importedResult = rCtx.importObjectUniversal(result);
+        logOutputStatus(fh.handle, importedResult, cCtx.unstableMarker === undefined, -1, cCtx.unstableMarker);
+        return { ir: importedResult };
+      }
+
+      let recalculationCounter = 0;
+      if (getDebugFlags().logOutputStatus)
+        console.log(`Output ${fh.handle} scaffold calculated (not all computables resolved yet).`);
+      keepVmAlive = true;
+
+      return {
+        ir: toBeResolved,
+        postprocessValue: (resolved: Record<string, unknown>, { unstableMarker, stable }) => {
         // resolving futures
-        for (const [handle, value] of Object.entries(resolved)) rCtx.runCallback(handle, value);
-
-        // rendering result
-        const renderedResult = rCtx.importObjectUniversal(result);
-
-        // logging
-        recalculationCounter++;
-        if (getDebugFlags().logOutputStatus && (getDebugFlags().logOutputStatus === 'any' || !stable)) {
-          if (stable)
-            console.log(
-              `Stable output ${fh.handle} calculated ${renderedResult !== undefined ? 'defined' : 'undefined'}; (#${recalculationCounter})`,
-            );
-          else
-            console.log(
-              `Unstable output ${fh.handle}; marker = ${unstableMarker}; ${renderedResult !== undefined ? 'defined' : 'undefined'} (#${recalculationCounter})`,
-            );
-        }
-
-        return renderedResult;
-      },
-    };
+          for (const [handle, value] of Object.entries(resolved)) rCtx.runCallback(handle, value);
+
+          // rendering result
+          const renderedResult = rCtx.importObjectUniversal(result);
+
+          // logging
+          recalculationCounter++;
+          logOutputStatus(fh.handle, renderedResult, stable, recalculationCounter, unstableMarker);
+
+          return renderedResult;
+        },
+      };
+    } catch (e) {
+      keepVmAlive = false;
+      throw e;
+    } finally {
+      if (!keepVmAlive) scope.dispose();
+    }
   }, ops);
 }