refactor(model-datastructure): introduction of IObjectGraph, which controls how objects are loaded

This makes it more flexible for different use cases. There can be lazy loading or a fully
instantiated in-memory graph or something mixed.
For the model client there is an implementation that keeps the model data inside a version in
memory, but tries to unload the unused history.

BREAKING CHANGE: Some of the constructors of `CLVersion` and `CLTree` were removed. There are either
  static methods as a replacements or some of the parameters need be converted to a non-deprecated
  type before passing them to the constructor.

Author: slisson

bulk-model-sync-lib/src/commonTest/kotlin/org/modelix/model/sync/bulk/AbstractModelSyncTest.kt

@@ -605,7 +605,7 @@ internal fun createOTBranchFromModel(model: ModelData): OTBranch {
     pBranch.runWrite {
         ModelImporter(pBranch.getRootNode()).import(model)
     }
-    return OTBranch(pBranch, IdGenerator.getInstance(1), createObjectStoreCache(MapBasedStore()))
+    return OTBranch(pBranch, IdGenerator.getInstance(1))
 }
 
 internal fun IBranch.importIncrementally(model: ModelData) {

bulk-model-sync-lib/src/commonTest/kotlin/org/modelix/model/sync/bulk/ModelImporterTest.kt

@@ -58,7 +58,7 @@ class ModelImporterTest : AbstractModelSyncTest() {
             val importer = ModelImporter(branch1.getRootNode())
             importer.import(ModelData(root = initialState))
         }
-        val otBranch = OTBranch(branch1, idGenerator, store)
+        val otBranch = OTBranch(branch1, idGenerator)
 
         otBranch.runWrite {
             val importer = ModelImporter(otBranch.getRootNode())

bulk-model-sync-lib/src/commonTest/kotlin/org/modelix/model/sync/bulk/ModelSynchronizerTest.kt

@@ -173,7 +173,7 @@ open class ModelSynchronizerTest : AbstractModelSyncTest() {
                 importer.import(ModelData(root = sourceBranch.getRootNode().asExported()))
             }
         }
-        val otBranch = OTBranch(targetBranch, idGenerator, store)
+        val otBranch = OTBranch(targetBranch, idGenerator)
 
         otBranch.runWrite {
             ModelSynchronizer(
@@ -196,5 +196,5 @@ open class ModelSynchronizerTest : AbstractModelSyncTest() {
 }
 
 private fun IBranch.toOTBranch(): OTBranch {
-    return OTBranch(this, IdGenerator.getInstance(1), createObjectStoreCache(MapBasedStore()))
+    return OTBranch(this, IdGenerator.getInstance(1))
 }

bulk-model-sync-lib/src/jvmTest/kotlin/org/modelix/model/sync/bulk/ModelSynchronizerWithInvalidationTreeTest.kt

@@ -83,7 +83,7 @@ class ModelSynchronizerWithInvalidationTreeTest : ModelSynchronizerTest() {
                 sourceTree.visitChanges(targetTree, InvalidatingVisitor(sourceTree, invalidationTree))
             }
         }
-        val otBranch = OTBranch(targetBranch, idGenerator, store)
+        val otBranch = OTBranch(targetBranch, idGenerator)
         otBranch.runWrite {
             ModelSynchronizer(
                 filter = invalidationTree,

gradle/libs.versions.toml

@@ -53,6 +53,8 @@ kotlin-serialization-yaml = { group = "com.charleskorn.kaml", name = "kaml", ver
 kotlin-logging = { group = "io.github.microutils", name = "kotlin-logging", version = "3.0.5" }
 kotlin-datetime = { group = "org.jetbrains.kotlinx", name = "kotlinx-datetime", version = "0.6.2" }
 kotlin-html = { group = "org.jetbrains.kotlinx", name = "kotlinx-html", version = "0.9.1" }
+kotlin-collections-immutable = { group = "org.jetbrains.kotlinx", name = "kotlinx-collections-immutable", version = "0.3.8" }
+kotlinJs = { module = "org.jetbrains.kotlin-wrappers:kotlin-js", version = "2025.1.4" }
 kotlin-gradlePlugin = { group = "org.jetbrains.kotlin", name = "kotlin-gradle-plugin", version.ref = "kotlin" }
 
 kotlin-coroutines-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "kotlinCoroutines" }

kotlin-utils/build.gradle.kts

@@ -19,6 +19,7 @@ kotlin {
         val jvmMain by getting {
             dependencies {
                 implementation(libs.trove4j)
+                implementation(libs.guava)
             }
         }
         val jvmTest by getting {
@@ -27,6 +28,7 @@ kotlin {
         }
         val jsMain by getting {
             dependencies {
+                implementation(libs.kotlinJs)
             }
         }
         val jsTest by getting {

kotlin-utils/src/commonMain/kotlin/org/modelix/kotlin/utils/UnstableModelixFeature.kt renamed to kotlin-utils/src/commonMain/kotlin/org/modelix/kotlin/utils/Annotations.kt

@@ -25,3 +25,19 @@ annotation class UnstableModelixFeature(
     val reason: String,
     val intendedFinalization: String,
 )
+
+/**
+ * Marks declarations in Modelix that are **delicate** —
+ * they have limited use-case and shall be used with care in general code.
+ * Any use of a delicate declaration has to be carefully reviewed to make sure it is
+ * properly used.
+ * Carefully read documentation of any declaration marked as `DelicateModelixApi`.
+ */
+@MustBeDocumented
+@Retention(value = AnnotationRetention.BINARY)
+@RequiresOptIn(
+    level = RequiresOptIn.Level.WARNING,
+    message = "This is a delicate API and its use requires care." +
+        " Make sure you fully read and understand documentation of the declaration that is marked as a delicate API.",
+)
+annotation class DelicateModelixApi

kotlin-utils/src/commonMain/kotlin/org/modelix/kotlin/utils/WeakValueMap.kt

@@ -0,0 +1,11 @@
+package org.modelix.kotlin.utils
+
+expect class WeakValueMap<K : Any, V : Any>() {
+    fun get(key: K): V?
+    fun put(key: K, value: V)
+    fun toMap(): Map<K, V>
+}
+
+fun <K : Any, V : Any> WeakValueMap<K, V>.getOrPut(key: K, provider: () -> V): V {
+    return get(key) ?: provider().also { put(key, it) }
+}

kotlin-utils/src/jsMain/kotlin/org/modelix/kotlin/utils/WeakValueMap.js.kt

@@ -0,0 +1,22 @@
+package org.modelix.kotlin.utils
+
+import js.memory.FinalizationRegistry
+import js.memory.WeakRef
+
+actual class WeakValueMap<K : Any, V : Any> {
+    private val map = LinkedHashMap<K, WeakRef<V>>()
+    private val registry = FinalizationRegistry<K> { map.remove(it) }
+
+    actual fun get(key: K): V? {
+        return map[key]?.deref()
+    }
+
+    actual fun put(key: K, value: V) {
+        map.put(key, WeakRef(value))
+        registry.register(value, key, value)
+    }
+
+    actual fun toMap(): Map<K, V> {
+        return map.mapValues { it.value.deref() }.filterNotNullValues()
+    }
+}

kotlin-utils/src/jvmMain/kotlin/org/modelix/kotlin/utils/WeakValueMap.jvm.kt

@@ -0,0 +1,19 @@
+package org.modelix.kotlin.utils
+
+import com.google.common.collect.MapMaker
+
+actual class WeakValueMap<K : Any, V : Any> {
+    private val map = MapMaker().weakValues().makeMap<K, V>()
+
+    actual fun get(key: K): V? {
+        return map[key]
+    }
+
+    actual fun put(key: K, value: V) {
+        map.put(key, value)
+    }
+
+    actual fun toMap(): Map<K, V> {
+        return map.toMap()
+    }
+}