docs: undocumented identity-based comparison in equalimmutablelists

`equalImmutableLists` is public and uses referential equality (`===`) per element rather than structural equality (`==`). Without documentation, callers may assume normal list equality and get false negatives for value-equal but distinct instances. This is a non-obvious contract and should be documented explicitly to prevent subtle logic bugs.


Affected files: ListUtils.kt

Signed-off-by: Nguyen Van Nam <nam.nv205106@gmail.com>

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/utils/ListUtils.kt

@@ -22,6 +22,14 @@ package com.vitorpamplona.amethyst.commons.utils
 
 import kotlinx.collections.immutable.ImmutableList
 
+/**
+ * Compares two [ImmutableList] instances by element identity (`===`), not value equality (`==`).
+ *
+ * Returns `true` only when both lists have the same size and each element at the same index
+ * is the exact same object reference.
+ *
+ * Useful for cheap change detection in UI/state pipelines where object identity is meaningful.
+ */
 fun <T> equalImmutableLists(
     list1: ImmutableList<T>,
     list2: ImmutableList<T>,