Implement strict and lenient modes for Kotlin metadata reading

In strict mode, an exception will be thrown when inconsistent metadata is encountered. In lenient mode, the reader will attempt to handle the inconsistent metadata by ignoring certain inconsistencies. This is a solution to a problem of reading metadata 'from the future' that is not allowed by default, but desired in certain cases. See updated ReadMe for details.

Also fix problem with Strict Semantics flag.

#KT-57922 Fixed
#KT-59441 Fixed

libraries/kotlinx-metadata/jvm/ReadMe.md

@@ -35,18 +35,20 @@ dependencies {
 
 ## Overview
 
-The entry point for reading the Kotlin metadata of a `.class` file is [`KotlinClassMetadata.read`](src/kotlinx/metadata/jvm/KotlinClassMetadata.kt).
+The entry point for reading the Kotlin metadata of a `.class` file is [`KotlinClassMetadata.readStrict`](src/kotlinx/metadata/jvm/KotlinClassMetadata.kt).
 The data it takes is the [`kotlin.Metadata`](../../stdlib/jvm/runtime/kotlin/Metadata.kt) annotation on the class file generated by the Kotlin compiler.
 Obtain the `kotlin.Metadata` annotation reflectively or construct it from binary representation (e.g. by reading classfile with `org.objectweb.asm.ClassReader`),
-and then use `KotlinClassMetadata.read` to obtain the correct instance of the class metadata.
+and then use `KotlinClassMetadata.readStrict` to obtain the correct instance of the class metadata.
 
 ```kotlin
 val metadataAnnotation = Metadata(
     // pass arguments here
 )
-val metadata = KotlinClassMetadata.read(metadataAnnotation)
+val metadata = KotlinClassMetadata.readStrict(metadataAnnotation)
 ```
 
+> There are other methods of reading metadata, but `readStrict` is a preferred one. See the differences in [working with different versions section](#working-with-different-versions).
+
 `KotlinClassMetadata` is a sealed class, with subclasses representing all the different kinds of classes generated by the Kotlin compiler.
 Unless you are sure that you are reading a class of a specific kind and can do a simple cast, a `when` is a good choice to handle all the possibilities:
 
@@ -112,6 +114,9 @@ val klass = KmClass().apply {
 
     ...
 }
+```
+
+Then, you can encode a resulting KmClass to an annotation.
 
 val annotation = KotlinClassMetadata.writeClass(klass)
 
@@ -138,3 +143,39 @@ val module = metadata.kmModule
 val bytes = KotlinModuleMetadata.write(module)
 File("META-INF/main.kotlin_module").writeBytes(bytes)
 ```
+
+## Working with different versions
+
+### Short guide
+
+There are two methods to read metadata:
+
+`readStrict()`: This method allows you to read the metadata strictly, meaning it will throw an exception if the metadata version is greater than what kotlinx-metadata-jvm understands.
+It's suitable when your tooling can't tolerate reading potentially incomplete or incorrect information due to version differences.
+It's also the only method that allows metadata transformation and `KotlinClassMetadata.write` subsequent calls.
+
+`readLenient()`: This method allows you to read the metadata leniently. 
+If the metadata version is higher than what kotlinx-metadata-jvm can interpret, it may ignore parts of the metadata it doesn't understand but it won't throw an exception.
+It’s more suitable when your tooling needs to read metadata of possibly newer Kotlin versions and can handle incomplete data, because it is interested only in part of it (e.g. visibility of declarations)
+**Metadata read in lenient mode can not be written back.**
+
+### Detailed explanation
+
+Kotlin compiler and its features evolve over time, and so its metadata format. Metadata format version is equal to the Kotlin compiler version.
+As you might guess, evolving metadata format usually involves adding new fields for new Kotlin language features. Therefore, 
+some problems may occur when you're reading new metadata with an older version of Kotlin compiler or kotlinx-metadata-jvm library.
+
+By default, the Kotlin compiler (and similar, kotlinx-metadata-jvm library) have forward compatibility for versions not higher than current + 1.
+It means that Kotlin compiler 2.1 can read metadata from Kotlin compiler 2.2, but not 2.3. The same is true for `KotlinClassMetadata.readStrict()`
+method: it will throw an exception if you try to read metadata with version higher than `COMPATIBLE_METADATA_VERSION` + 1.
+Such restriction comes from the fact that higher metadata versions (e.g. 2.3) might have some unknown fields that we skip during reading; therefore, if we write 
+transformed metadata back, missing some fields may result in corrupted metadata that is no longer valid for version 2.3.
+
+However, there are a lot of use-cases for metadata introspection alone, without further transformations — for example, binary-compatibility-validator which is interested only in visibility and modality of declarations.
+For such use-cases it seems over restrictive to prohibit reading newer metadata versions (and therefore, requiring authors to do frequent updates of kotlinx-metadata-jvm dependency),
+so there is a relaxed version of the reading method: `KotlinClassMetadata.readLenient()`. It is a best-effort reading method that will potentially skip all unknown fields,
+but still provide some access to metadata. Keep in mind that this method has limitations:
+
+1. Metadata returned by this method can not be written back, because we are not sure if it is still valid format for newer versions. It is intended for introspection alone.
+2. While some unknown fields are skipped, we cannot guarantee that metadata is not changed in the other unpredictable ways in the future. `readLenient()` tries its best, but still may throw a decoding exception if metadata cannot be read at all. 
+