runtime: add LinkMLValue::equals per Instances spec; tests: add equality coverage; revert CLI offline toggle and run tests with network

Author: Frank Dekervel

AGENTS.md

@@ -25,6 +25,7 @@
 - Python (bindings helpers): follow PEP 8; prefer type hints where feasible.
 
 ## Testing Guidelines
+- When testing locally, always provide network access. never try to run the tests offline
 - Add integration tests under `src/runtime/tests/` when changing CLI/runtime behavior.
 - Prefer `assert_cmd` for CLI and `predicates` for output checks. Keep fixtures in `src/runtime/tests/data/`.
 - Run `cargo test --workspace` locally; ensure tests don’t rely on network input.

src/runtime/src/lib.rs

@@ -153,6 +153,149 @@ impl LinkMLValue {
         }
         Some(current)
     }
+
+    /// Compare two LinkMLValue instances for semantic equality per the
+    /// LinkML Instances specification (Identity conditions).
+    ///
+    /// Key points implemented:
+    /// - Null equals Null.
+    /// - Scalars: equal iff same underlying atomic value and compatible typed context
+    ///   (same Enum range when present; otherwise same TypeDefinition range name when present).
+    /// - Lists: equal iff same length and pairwise equal in order.
+    /// - Mappings: equal iff same keys and values equal for each key (order-insensitive).
+    /// - Objects: equal iff same instantiated class (by identity) and slot assignments match
+    ///   after normalization (i.e., treating assignments with value Null as omitted), ignoring order.
+    pub fn equals(&self, other: &LinkMLValue) -> bool {
+        use LinkMLValue::*;
+        match (self, other) {
+            (Null { .. }, Null { .. }) => true,
+            (
+                Scalar {
+                    value: v1,
+                    slot: s1,
+                    ..
+                },
+                Scalar {
+                    value: v2,
+                    slot: s2,
+                    ..
+                },
+            ) => {
+                // If either slot has an enum range, both must and enum names must match
+                let e1 = s1.get_range_enum();
+                let e2 = s2.get_range_enum();
+                if e1.is_some() || e2.is_some() {
+                    match (e1, e2) {
+                        (Some(ev1), Some(ev2)) => {
+                            if ev1.schema_id() != ev2.schema_id() || ev1.name() != ev2.name() {
+                                return false;
+                            }
+                        }
+                        _ => return false,
+                    }
+                } else {
+                    // Compare type ranges if explicitly set on both
+                    let t1 = s1.definition().range.as_ref();
+                    let t2 = s2.definition().range.as_ref();
+                    if let (Some(r1), Some(r2)) = (t1, t2) {
+                        if r1 != r2 {
+                            return false;
+                        }
+                    }
+                }
+                v1 == v2
+            }
+            (List { values: a, .. }, List { values: b, .. }) => {
+                if a.len() != b.len() {
+                    return false;
+                }
+                for (x, y) in a.iter().zip(b.iter()) {
+                    if !x.equals(y) {
+                        return false;
+                    }
+                }
+                true
+            }
+            (Mapping { values: a, .. }, Mapping { values: b, .. }) => {
+                if a.len() != b.len() {
+                    return false;
+                }
+                for (k, va) in a.iter() {
+                    match b.get(k) {
+                        Some(vb) => {
+                            if !va.equals(vb) {
+                                return false;
+                            }
+                        }
+                        None => return false,
+                    }
+                }
+                true
+            }
+            (
+                Object {
+                    values: a,
+                    class: ca,
+                    sv: sva,
+                    ..
+                },
+                Object {
+                    values: b,
+                    class: cb,
+                    sv: svb,
+                    ..
+                },
+            ) => {
+                // Compare class identity via canonical URIs if possible
+                let ida = ca.canonical_uri();
+                let idb = cb.canonical_uri();
+                let class_equal = if let Some(conv) = sva.converter_for_schema(ca.schema_id()) {
+                    // Use 'sva' for comparison; identifiers are global across schemas
+                    sva.identifier_equals(&ida, &idb, conv).unwrap_or(false)
+                } else if let Some(conv) = svb.converter_for_schema(cb.schema_id()) {
+                    svb.identifier_equals(&ida, &idb, conv).unwrap_or(false)
+                } else {
+                    ca.name() == cb.name()
+                };
+                if !class_equal {
+                    return false;
+                }
+
+                // Normalize conceptually by ignoring entries whose value is Null
+                let count_a = a.iter().filter(|(_, v)| !matches!(v, Null { .. })).count();
+                let count_b = b.iter().filter(|(_, v)| !matches!(v, Null { .. })).count();
+                if count_a != count_b {
+                    return false;
+                }
+                for (k, va) in a.iter().filter(|(_, v)| !matches!(v, Null { .. })) {
+                    match b.get(k) {
+                        Some(vb) => {
+                            if matches!(vb, Null { .. }) {
+                                return false;
+                            }
+                            if !va.equals(vb) {
+                                return false;
+                            }
+                        }
+                        None => return false,
+                    }
+                }
+                // Ensure b has no extra non-null keys not in a (counts already equal, so this is defensive)
+                for (k, _vb) in b.iter().filter(|(_, v)| !matches!(v, Null { .. })) {
+                    match a.get(k) {
+                        Some(va) => {
+                            if matches!(va, Null { .. }) {
+                                return false;
+                            }
+                        }
+                        None => return false,
+                    }
+                }
+                true
+            }
+            _ => false,
+        }
+    }
     fn find_scalar_slot_for_inlined_map(
         class: &ClassView,
         key_slot_name: &str,

src/runtime/tests/equality.rs

@@ -0,0 +1,177 @@
+use linkml_runtime::{load_json_str, load_yaml_str, LinkMLValue};
+use linkml_schemaview::identifier::converter_from_schema;
+use linkml_schemaview::io::from_yaml;
+use linkml_schemaview::schemaview::SchemaView;
+use std::path::Path;
+
+fn data_path(name: &str) -> std::path::PathBuf {
+    let mut p = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    p.push("tests");
+    p.push("data");
+    p.push(name);
+    p
+}
+
+#[test]
+fn object_equality_ignores_null_assignments() {
+    // Load personinfo schema and Container class
+    let schema = from_yaml(Path::new(&data_path("personinfo.yaml"))).unwrap();
+    let mut sv = SchemaView::new();
+    sv.add_schema(schema.clone()).unwrap();
+    let conv = converter_from_schema(&schema);
+    let container = sv
+        .get_class(
+            &linkml_schemaview::identifier::Identifier::new("Container"),
+            &conv,
+        )
+        .unwrap()
+        .expect("class not found");
+
+    let doc_with_null = r#"
+objects:
+  - objecttype: personinfo:Person
+    id: "P:1"
+    name: "Alice"
+    current_address: null
+"#;
+    let doc_without_slot = r#"
+objects:
+  - objecttype: personinfo:Person
+    id: "P:1"
+    name: "Alice"
+"#;
+    let v1 = load_yaml_str(doc_with_null, &sv, &container, &conv).unwrap();
+    let v2 = load_yaml_str(doc_without_slot, &sv, &container, &conv).unwrap();
+    let p1 = v1.navigate_path(["objects", "0"]).unwrap();
+    let p2 = v2.navigate_path(["objects", "0"]).unwrap();
+    assert!(
+        p1.equals(p2),
+        "Person with null assignment should equal omission"
+    );
+}
+
+#[test]
+fn list_identity_is_order_sensitive() {
+    let schema = from_yaml(Path::new(&data_path("personinfo.yaml"))).unwrap();
+    let mut sv = SchemaView::new();
+    sv.add_schema(schema.clone()).unwrap();
+    let conv = converter_from_schema(&schema);
+    let container = sv
+        .get_class(
+            &linkml_schemaview::identifier::Identifier::new("Container"),
+            &conv,
+        )
+        .unwrap()
+        .expect("class not found");
+
+    let doc_a = r#"
+objects:
+  - objecttype: personinfo:Person
+    id: "P:1"
+    name: "Alice"
+    has_employment_history:
+      - started_at_time: 2019-01-01
+        is_current: true
+      - started_at_time: 2020-01-01
+        is_current: false
+"#;
+    let doc_b = r#"
+objects:
+  - objecttype: personinfo:Person
+    id: "P:1"
+    name: "Alice"
+    has_employment_history:
+      - started_at_time: 2020-01-01
+        is_current: false
+      - started_at_time: 2019-01-01
+        is_current: true
+"#;
+    let v1 = load_yaml_str(doc_a, &sv, &container, &conv).unwrap();
+    let v2 = load_yaml_str(doc_b, &sv, &container, &conv).unwrap();
+    let p1 = v1.navigate_path(["objects", "0"]).unwrap();
+    let p2 = v2.navigate_path(["objects", "0"]).unwrap();
+    assert!(matches!(p1, LinkMLValue::Object { .. }));
+    assert!(matches!(p2, LinkMLValue::Object { .. }));
+    assert!(!p1.equals(p2), "List order must affect equality");
+}
+
+#[test]
+fn mapping_equality_is_key_based_not_ordered() {
+    // Load mapping schema and Bag class
+    let schema = from_yaml(Path::new(&data_path("mapping_schema.yaml"))).unwrap();
+    let mut sv = SchemaView::new();
+    sv.add_schema(schema.clone()).unwrap();
+    let conv = converter_from_schema(&schema);
+    let bag = sv
+        .get_class(
+            &linkml_schemaview::identifier::Identifier::new("Bag"),
+            &conv,
+        )
+        .unwrap()
+        .expect("class not found");
+
+    let doc1 = r#"{
+  "things": {
+    "alpha": {"typeURI": "ThingA", "a_only": "foo", "common": "shared"},
+    "beta":  {"typeURI": "ThingB", "b_only": true,   "common": "shared"}
+  }
+}"#;
+    let doc2 = r#"{
+  "things": {
+    "beta":  {"typeURI": "ThingB", "b_only": true,   "common": "shared"},
+    "alpha": {"typeURI": "ThingA", "a_only": "foo", "common": "shared"}
+  }
+}"#;
+    let v1 = load_json_str(doc1, &sv, &bag, &conv).unwrap();
+    let v2 = load_json_str(doc2, &sv, &bag, &conv).unwrap();
+    let m1 = v1.navigate_path(["things"]).unwrap();
+    let m2 = v2.navigate_path(["things"]).unwrap();
+    assert!(matches!(m1, LinkMLValue::Mapping { .. }));
+    assert!(matches!(m2, LinkMLValue::Mapping { .. }));
+    assert!(m1.equals(m2), "Mapping equality should ignore key order");
+}
+
+#[test]
+fn enum_scalar_equality_respects_value_and_range() {
+    let schema = from_yaml(Path::new(&data_path("personinfo.yaml"))).unwrap();
+    let mut sv = SchemaView::new();
+    sv.add_schema(schema.clone()).unwrap();
+    let conv = converter_from_schema(&schema);
+    let container = sv
+        .get_class(
+            &linkml_schemaview::identifier::Identifier::new("Container"),
+            &conv,
+        )
+        .unwrap()
+        .expect("class not found");
+
+    let doc1 = r#"
+objects:
+  - objecttype: personinfo:Person
+    id: "P:1"
+    name: "Alice"
+    gender: "cisgender man"
+"#;
+    let doc2 = r#"
+objects:
+  - objecttype: personinfo:Person
+    id: "P:2"
+    name: "Bob"
+    gender: "cisgender man"
+"#;
+    let doc3 = r#"
+objects:
+  - objecttype: personinfo:Person
+    id: "P:3"
+    name: "Carol"
+    gender: "cisgender woman"
+"#;
+    let v1 = load_yaml_str(doc1, &sv, &container, &conv).unwrap();
+    let v2 = load_yaml_str(doc2, &sv, &container, &conv).unwrap();
+    let v3 = load_yaml_str(doc3, &sv, &container, &conv).unwrap();
+    let g1 = v1.navigate_path(["objects", "0", "gender"]).unwrap();
+    let g2 = v2.navigate_path(["objects", "0", "gender"]).unwrap();
+    let g3 = v3.navigate_path(["objects", "0", "gender"]).unwrap();
+    assert!(g1.equals(g2));
+    assert!(!g1.equals(g3));
+}