@lix-js/sdk 0.6.0-preview.2 → 0.6.0-preview.3

package/dist-engine-src/src/schema/key.rs

@@ -6,20 +6,14 @@ use crate::LixError;
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct SchemaKey {
     pub schema_key: String,
-    pub schema_version: String,
 }
 
 impl SchemaKey {
-    pub fn new(schema_key: impl Into<String>, schema_version: impl Into<String>) -> Self {
+    pub fn new(schema_key: impl Into<String>) -> Self {
         Self {
             schema_key: schema_key.into(),
-            schema_version: schema_version.into(),
         }
     }
-
-    pub fn version_number(&self) -> Option<u64> {
-        self.schema_version.parse::<u64>().ok()
-    }
 }
 
 pub fn schema_key_from_definition(schema: &JsonValue) -> Result<SchemaKey, LixError> {
@@ -38,20 +32,8 @@ pub fn schema_key_from_definition(schema: &JsonValue) -> Result<SchemaKey, LixEr
             hint: None,
             details: None,
         })?;
-    let schema_version = object
-        .get("x-lix-version")
-        .and_then(JsonValue::as_str)
-        .ok_or_else(|| LixError {
-            code: "LIX_ERROR_UNKNOWN".to_string(),
-            message: "schema definition must include string x-lix-version".to_string(),
-            hint: None,
-            details: None,
-        })?;
 
-    Ok(SchemaKey::new(
-        schema_key.to_string(),
-        schema_version.to_string(),
-    ))
+    Ok(SchemaKey::new(schema_key.to_string()))
 }
 
 pub fn schema_from_registered_snapshot(
@@ -79,59 +61,26 @@ pub fn schema_from_registered_snapshot(
             hint: None,
             details: None,
         })?;
-    let schema_version = value
-        .get("x-lix-version")
-        .and_then(|value| value.as_str())
-        .ok_or_else(|| LixError {
-            code: "LIX_ERROR_UNKNOWN".to_string(),
-            message: "registered schema value.x-lix-version must be string".to_string(),
-            hint: None,
-            details: None,
-        })?;
 
     Ok((
-        SchemaKey::new(schema_key.to_string(), schema_version.to_string()),
+        SchemaKey::new(schema_key.to_string()),
         JsonValue::Object(value.clone()),
     ))
 }
 
-pub(crate) fn reject_unsupported_registered_schema_version(
-    key: &SchemaKey,
-) -> Result<(), LixError> {
-    if key.schema_version != "1" {
-        return Err(LixError::new(
-            LixError::CODE_SCHEMA_DEFINITION,
-            format!(
-                "schema '{}' uses x-lix-version '{}', but schema evolution is not supported yet; register schemas with x-lix-version '1'",
-                key.schema_key, key.schema_version
-            ),
-        ));
-    }
-    Ok(())
-}
-
-pub(crate) fn registered_schema_entity_id(
-    schema_key: &str,
-    schema_version: &str,
-) -> Result<EntityIdentity, LixError> {
+pub(crate) fn registered_schema_entity_id(schema_key: &str) -> Result<EntityIdentity, LixError> {
     EntityIdentity::from_primary_key_paths(
         &serde_json::json!({
             "value": {
                 "x-lix-key": schema_key,
-                "x-lix-version": schema_version,
             }
         }),
-        &[
-            vec!["value".to_string(), "x-lix-key".to_string()],
-            vec!["value".to_string(), "x-lix-version".to_string()],
-        ],
+        &[vec!["value".to_string(), "x-lix-key".to_string()]],
     )
     .map_err(|error| {
         LixError::new(
             LixError::CODE_SCHEMA_DEFINITION,
-            format!(
-                "registered schema identity could not be derived for schema '{schema_key}' version '{schema_version}': {error}"
-            ),
+            format!("registered schema identity could not be derived for schema '{schema_key}': {error}"),
         )
     })
 }
@@ -142,32 +91,17 @@ mod tests {
 
     use super::{schema_from_registered_snapshot, schema_key_from_definition, SchemaKey};
 
-    #[test]
-    fn schema_key_entity_id_and_numeric_version() {
-        let key = SchemaKey::new("users", "42");
-
-        assert_eq!(key.version_number(), Some(42));
-    }
-
-    #[test]
-    fn schema_key_non_numeric_version_returns_none() {
-        let key = SchemaKey::new("users", "v2");
-
-        assert_eq!(key.version_number(), None);
-    }
-
     #[test]
     fn schema_from_registered_snapshot_extracts_key_and_schema() {
         let snapshot = json!({
             "value": {
                 "x-lix-key": "profile",
-                "x-lix-version": "1",
                 "type": "object"
             }
         });
 
         let (key, schema) = schema_from_registered_snapshot(&snapshot).expect("schema is valid");
-        assert_eq!(key, SchemaKey::new("profile", "1"));
+        assert_eq!(key, SchemaKey::new("profile"));
         assert_eq!(schema["type"], json!("object"));
     }
 
@@ -184,7 +118,6 @@ mod tests {
         let snapshot = json!({
             "value": {
                 "x-lix-key": 1,
-                "x-lix-version": "1"
             }
         });
 
@@ -193,14 +126,13 @@ mod tests {
     }
 
     #[test]
-    fn schema_key_from_definition_extracts_key_and_version() {
+    fn schema_key_from_definition_extracts_key() {
         let schema = json!({
             "x-lix-key": "users",
-            "x-lix-version": "2",
             "type": "object"
         });
 
         let key = schema_key_from_definition(&schema).expect("schema key");
-        assert_eq!(key, SchemaKey::new("users", "2"));
+        assert_eq!(key, SchemaKey::new("users"));
     }
 }

package/dist-engine-src/src/schema/mod.rs

@@ -1,19 +1,19 @@
-mod annotations;
 mod builtin;
+#[allow(dead_code)]
+pub(crate) mod compatibility;
 mod definition;
 mod key;
 pub(crate) mod seed;
 #[cfg(test)]
 mod tests;
 
-pub(crate) use annotations::defaults::apply_schema_defaults_with_shared_runtime;
-pub(crate) use builtin::lix_state_surface_schema_definition;
+pub(crate) use compatibility::validate_schema_amendment;
 pub(crate) use definition::{compile_lix_schema, format_lix_schema_validation_errors};
 pub use definition::{
     lix_schema_definition, lix_schema_definition_json, validate_lix_schema,
     validate_lix_schema_definition,
 };
-pub(crate) use key::{registered_schema_entity_id, reject_unsupported_registered_schema_version};
+pub(crate) use key::registered_schema_entity_id;
 pub use key::{schema_from_registered_snapshot, schema_key_from_definition, SchemaKey};
 #[cfg(test)]
 pub(crate) use seed::seed_schema_definition;

package/dist-engine-src/src/schema/tests.rs

@@ -5,7 +5,6 @@ use serde_json::json;
 fn validate_lix_schema_definition_passes_for_valid_schema() {
     let valid_schema = json!({
         "x-lix-key": "test_entity",
-        "x-lix-version": "1",
         "type": "object",
         "properties": {
             "id": { "type": "string" }
@@ -20,7 +19,6 @@ fn validate_lix_schema_definition_passes_for_valid_schema() {
 fn validate_lix_schema_definition_rejects_unprojectable_entity_properties() {
     let schema = json!({
         "x-lix-key": "test_entity",
-        "x-lix-version": "1",
         "type": "object",
         "properties": {
             "id": { "type": "string" },
@@ -41,10 +39,34 @@ fn validate_lix_schema_definition_rejects_unprojectable_entity_properties() {
     );
 }
 
+#[test]
+fn validate_lix_schema_definition_rejects_reserved_lix_property_prefixes() {
+    for property_name in ["lixcol_entity_id", "lix_internal", "lixfoo"] {
+        let schema = json!({
+            "x-lix-key": "test_entity",
+            "type": "object",
+            "properties": {
+                "id": { "type": "string" },
+                property_name: { "type": "string" }
+            },
+            "required": ["id", property_name],
+            "additionalProperties": false
+        });
+
+        let err = validate_lix_schema_definition(&schema)
+            .expect_err("reserved property names should be rejected");
+        assert!(
+            err.to_string().contains(&format!(
+                "property '/{property_name}' uses reserved prefix 'lix'"
+            )),
+            "error should identify the reserved property name: {err:?}"
+        );
+    }
+}
+
 #[test]
 fn validate_lix_schema_definition_throws_for_invalid_schema() {
     let invalid_schema = json!({
-        "x-lix-version": "1",
         "type": "object",
         "properties": {
             "id": { "type": "string" }
@@ -60,7 +82,6 @@ fn validate_lix_schema_definition_throws_for_invalid_schema() {
 fn validate_lix_schema_validates_both_schema_and_data_successfully() {
     let schema = json!({
         "x-lix-key": "user",
-        "x-lix-version": "1",
         "type": "object",
         "properties": {
             "id": { "type": "string" },
@@ -81,7 +102,6 @@ fn validate_lix_schema_validates_both_schema_and_data_successfully() {
 #[test]
 fn validate_lix_schema_throws_when_schema_is_invalid() {
     let invalid_schema = json!({
-        "x-lix-version": "1",
         "type": "object",
         "properties": {
             "id": { "type": "string" }
@@ -99,7 +119,6 @@ fn validate_lix_schema_throws_when_schema_is_invalid() {
 fn validate_lix_schema_throws_when_data_does_not_match_schema() {
     let schema = json!({
         "x-lix-key": "user",
-        "x-lix-version": "1",
         "type": "object",
         "properties": {
             "id": { "type": "string" },
@@ -119,7 +138,6 @@ fn validate_lix_schema_throws_when_data_does_not_match_schema() {
 fn validate_lix_schema_definition_rejects_when_additional_properties_missing() {
     let schema = json!({
         "x-lix-key": "user",
-        "x-lix-version": "1",
         "type": "object",
         "properties": {
             "id": { "type": "string" }
@@ -135,7 +153,6 @@ fn validate_lix_schema_definition_rejects_when_additional_properties_missing() {
 fn additional_properties_must_be_false() {
     let schema_with_additional_props = json!({
         "x-lix-key": "user",
-        "x-lix-version": "1",
         "type": "object",
         "properties": {
             "id": { "type": "string" },
@@ -149,7 +166,6 @@ fn additional_properties_must_be_false() {
 
     let valid_schema = json!({
         "x-lix-key": "user",
-        "x-lix-version": "1",
         "type": "object",
         "properties": {
             "id": { "type": "string" },
@@ -175,7 +191,6 @@ fn additional_properties_must_be_false() {
 fn validate_lix_schema_definition_rejects_missing_primary_key_properties() {
     let schema = json!({
         "x-lix-key": "missing_pk",
-        "x-lix-version": "1",
         "type": "object",
         "properties": {
             "value": { "type": "string" }
@@ -191,11 +206,51 @@ fn validate_lix_schema_definition_rejects_missing_primary_key_properties() {
         .contains("x-lix-primary-key references missing property"));
 }
 
+#[test]
+fn validate_lix_schema_definition_rejects_non_string_primary_key_properties() {
+    let schema = json!({
+        "x-lix-key": "numeric_pk",
+        "type": "object",
+        "properties": {
+            "id": { "type": "number" },
+            "value": { "type": "string" }
+        },
+        "required": ["id", "value"],
+        "x-lix-primary-key": ["/id"],
+        "additionalProperties": false
+    });
+
+    let err = validate_lix_schema_definition(&schema).unwrap_err();
+    assert!(err
+        .to_string()
+        .contains("x-lix-primary-key property \"/id\" must have type \"string\""));
+}
+
+#[test]
+fn validate_lix_schema_definition_rejects_optional_primary_key_properties() {
+    let schema = json!({
+        "x-lix-key": "optional_pk",
+        "type": "object",
+        "properties": {
+            "id": { "type": "string" },
+            "value": { "type": "string" }
+        },
+        "required": ["value"],
+        "x-lix-primary-key": ["/id"],
+        "additionalProperties": false
+    });
+
+    let err = validate_lix_schema_definition(&schema)
+        .expect_err("primary-key property should be required");
+    assert!(err
+        .to_string()
+        .contains("x-lix-primary-key property \"/id\" must be required"));
+}
+
 #[test]
 fn validate_lix_schema_definition_rejects_missing_unique_constraint_properties() {
     let schema = json!({
         "x-lix-key": "missing_unique",
-        "x-lix-version": "1",
         "type": "object",
         "properties": {
             "value": { "type": "string" }
@@ -215,7 +270,6 @@ fn x_key_is_required() {
     let schema = json!({
         "type": "object",
         "x-lix-key": null,
-        "x-lix-version": "1",
         "properties": {
             "name": { "type": "string" }
         },
@@ -230,7 +284,6 @@ fn x_key_is_required() {
 fn x_lix_key_must_be_snake_case() {
     let base_schema = json!({
         "type": "object",
-        "x-lix-version": "1",
         "properties": {
             "name": { "type": "string" }
         },
@@ -266,7 +319,6 @@ fn x_lix_unique_is_optional() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "mock",
-        "x-lix-version": "1",
         "properties": {
             "name": { "type": "string" }
         },
@@ -282,7 +334,6 @@ fn x_lix_unique_must_be_array_of_arrays_when_present() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "mock",
-        "x-lix-version": "1",
         "x-lix-unique": [["/id"], ["/name", "/age"]],
         "properties": {
             "id": { "type": "string" },
@@ -301,7 +352,6 @@ fn x_lix_unique_fails_with_invalid_structure() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "mock",
-        "x-lix-version": "1",
         "x-lix-unique": ["/id", "/name"],
         "properties": {
             "id": { "type": "string" },
@@ -319,7 +369,6 @@ fn x_lix_primary_key_must_include_at_least_one_unique_pointer() {
     let base_schema = json!({
         "type": "object",
         "x-lix-key": "mock",
-        "x-lix-version": "1",
         "properties": {
             "id": { "type": "string" }
         },
@@ -345,7 +394,6 @@ fn x_lix_unique_groups_must_include_unique_pointers() {
     let base_schema = json!({
         "type": "object",
         "x-lix-key": "mock",
-        "x-lix-version": "1",
         "properties": {
             "id": { "type": "string" },
             "email": { "type": "string" }
@@ -372,7 +420,6 @@ fn x_lix_entity_views_is_rejected() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "mock",
-        "x-lix-version": "1",
         "x-lix-entity-views": ["lix_state", "lix_state_by_version"],
         "properties": {
             "name": { "type": "string" }
@@ -391,7 +438,6 @@ fn x_lix_primary_key_is_optional() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "mock",
-        "x-lix-version": "1",
         "properties": {
             "name": { "type": "string" }
         },
@@ -407,7 +453,6 @@ fn x_lix_primary_key_must_be_array_of_strings_when_present() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "mock",
-        "x-lix-version": "1",
         "x-lix-primary-key": ["/id", "/version"],
         "properties": {
             "id": { "type": "string" },
@@ -426,7 +471,6 @@ fn x_lix_foreign_keys_is_optional() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "blog_post",
-        "x-lix-version": "1",
         "properties": {
             "id": { "type": "string" },
             "author_id": { "type": "string" }
@@ -443,7 +487,6 @@ fn x_lix_foreign_keys_with_valid_structure() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "blog_post",
-        "x-lix-version": "1",
         "x-lix-foreign-keys": [
             {
                 "properties": ["/author_id"],
@@ -477,7 +520,6 @@ fn x_lix_foreign_keys_reject_duplicate_pointers() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "invalid_fk_duplicates",
-        "x-lix-version": "1",
         "x-lix-foreign-keys": [
             {
                 "properties": ["/local", "/local"],
@@ -502,7 +544,6 @@ fn x_lix_foreign_keys_fails_without_required_fields() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "blog_post",
-        "x-lix-version": "1",
         "x-lix-foreign-keys": [
             {
                 "properties": ["/author_id"]
@@ -520,18 +561,16 @@ fn x_lix_foreign_keys_fails_without_required_fields() {
 }
 
 #[test]
-fn x_lix_foreign_keys_rejects_schema_version() {
+fn x_lix_foreign_keys_use_schema_key_identity_only() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "comment",
-        "x-lix-version": "1",
         "x-lix-foreign-keys": [
             {
                 "properties": ["/post_id"],
                 "references": {
                     "schemaKey": "blog_post",
-                    "properties": ["/id"],
-                    "schemaVersion": "1"
+                    "properties": ["/id"]
                 }
             }
         ],
@@ -543,7 +582,7 @@ fn x_lix_foreign_keys_rejects_schema_version() {
         "additionalProperties": false
     });
 
-    assert!(validate_lix_schema_definition(&schema).is_err());
+    assert!(validate_lix_schema_definition(&schema).is_ok());
 }
 
 #[test]
@@ -551,7 +590,6 @@ fn x_lix_foreign_keys_rejects_mode_field() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "child_entity",
-        "x-lix-version": "1",
         "x-lix-primary-key": ["/id"],
         "x-lix-foreign-keys": [
             {
@@ -577,7 +615,6 @@ fn x_lix_foreign_keys_rejects_scope_field() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "child_entity",
-        "x-lix-version": "1",
         "x-lix-primary-key": ["/id"],
         "x-lix-foreign-keys": [
             {
@@ -599,19 +636,14 @@ fn x_lix_foreign_keys_rejects_scope_field() {
 }
 
 #[test]
-fn x_lix_foreign_keys_with_composite_key() {
+fn x_lix_state_foreign_keys_with_ordered_state_address_tuple() {
     let schema = json!({
         "type": "object",
-        "x-lix-key": "entity_label",
-        "x-lix-version": "1",
+        "x-lix-key": "label_assignment",
+        "x-lix-state-foreign-keys": [
+            ["/target_entity_id", "/target_schema_key", "/target_file_id"]
+        ],
         "x-lix-foreign-keys": [
-            {
-                "properties": ["/entity_id", "/schema_key", "/file_id"],
-                "references": {
-                    "schemaKey": "lix_state",
-                    "properties": ["/entity_id", "/schema_key", "/file_id"]
-                }
-            },
             {
                 "properties": ["/label_id"],
                 "references": {
@@ -621,12 +653,16 @@ fn x_lix_foreign_keys_with_composite_key() {
             }
         ],
         "properties": {
-            "entity_id": { "type": "string" },
-            "schema_key": { "type": "string" },
-            "file_id": { "type": "string" },
+            "target_entity_id": {
+                "type": "array",
+                "items": { "type": "string" },
+                "minItems": 1
+            },
+            "target_schema_key": { "type": "string" },
+            "target_file_id": { "type": ["string", "null"] },
             "label_id": { "type": "string" }
         },
-        "required": ["entity_id", "schema_key", "file_id", "label_id"],
+        "required": ["target_entity_id", "target_schema_key", "target_file_id", "label_id"],
         "additionalProperties": false
     });
 
@@ -634,78 +670,85 @@ fn x_lix_foreign_keys_with_composite_key() {
 }
 
 #[test]
-fn x_lix_foreign_keys_rejects_unaliased_lix_table_reference() {
+fn x_lix_state_foreign_keys_rejects_wrong_tuple_order_by_type() {
     let schema = json!({
         "type": "object",
-        "x-lix-key": "entity_label",
-        "x-lix-version": "1",
-        "x-lix-foreign-keys": [
-            {
-                "properties": ["/entity_id", "/schema_key", "/file_id"],
-                "references": {
-                    "schemaKey": "state",
-                    "properties": ["/entity_id", "/schema_key", "/file_id"]
-                }
-            }
+        "x-lix-key": "bad_label_assignment",
+        "x-lix-state-foreign-keys": [
+            ["/target_schema_key", "/target_entity_id", "/target_file_id"]
         ],
         "properties": {
-            "entity_id": { "type": "string" },
-            "schema_key": { "type": "string" },
-            "file_id": { "type": "string" }
-        },
-        "required": ["entity_id", "schema_key", "file_id"],
-        "additionalProperties": false
-    });
-
-    assert!(validate_lix_schema_definition(&schema).is_err());
-}
-
-#[test]
-fn x_version_is_required() {
-    let schema = json!({
-        "type": "object",
-        "x-lix-version": null,
-        "x-lix-key": "mock",
-        "properties": {
-            "name": { "type": "string" }
+            "target_entity_id": {
+                "type": "array",
+                "items": { "type": "string" },
+                "minItems": 1
+            },
+            "target_schema_key": { "type": "string" },
+            "target_file_id": { "type": ["string", "null"] }
         },
-        "required": ["name"],
+        "required": ["target_entity_id", "target_schema_key", "target_file_id"],
         "additionalProperties": false
     });
 
-    assert!(validate_lix_schema_definition(&schema).is_err());
+    let err =
+        validate_lix_schema_definition(&schema).expect_err("wrong tuple order should be rejected");
+    assert!(
+        err.message.contains("[entity_id, schema_key, file_id]"),
+        "unexpected error: {err:?}"
+    );
 }
 
 #[test]
-fn x_version_must_be_monotonic_integer() {
+fn x_lix_state_foreign_keys_requires_address_tuple_properties() {
     let schema = json!({
         "type": "object",
-        "x-lix-version": "v1",
-        "x-lix-key": "mock",
+        "x-lix-key": "optional_label_assignment",
+        "x-lix-state-foreign-keys": [
+            ["/target_entity_id", "/target_schema_key", "/target_file_id"]
+        ],
         "properties": {
-            "name": { "type": "string" }
+            "target_entity_id": {
+                "type": "array",
+                "items": { "type": "string" },
+                "minItems": 1
+            },
+            "target_schema_key": { "type": "string" },
+            "target_file_id": { "type": ["string", "null"] }
         },
-        "required": ["name"],
+        "required": ["target_entity_id", "target_schema_key"],
         "additionalProperties": false
     });
 
-    assert!(validate_lix_schema_definition(&schema).is_err());
+    let err = validate_lix_schema_definition(&schema)
+        .expect_err("state foreign key tuple fields should be required");
+    assert!(
+        err.message.contains("file_id") && err.message.contains("must be required"),
+        "unexpected error: {err:?}"
+    );
 }
 
 #[test]
-fn x_version_rejects_leading_zeros() {
+fn x_lix_foreign_keys_treat_schema_keys_literally() {
     let schema = json!({
         "type": "object",
-        "x-lix-version": "01",
-        "x-lix-key": "mock",
+        "x-lix-key": "custom_label_assignment",
+        "x-lix-foreign-keys": [
+            {
+                "properties": ["/label_id"],
+                "references": {
+                    "schemaKey": "label",
+                    "properties": ["/id"]
+                }
+            }
+        ],
         "properties": {
-            "name": { "type": "string" }
+            "label_id": { "type": "string" }
         },
-        "required": ["name"],
+        "required": ["label_id"],
         "additionalProperties": false
     });
 
-    assert!(validate_lix_schema_definition(&schema).is_err());
+    assert!(validate_lix_schema_definition(&schema).is_ok());
 }
 
 #[test]
@@ -713,7 +756,6 @@ fn x_lix_default_accepts_valid_cel_expression() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "mock",
-        "x-lix-version": "1",
         "properties": {
             "id": { "type": "string", "x-lix-default": "lix_uuid_v7()" }
         },
@@ -728,7 +770,6 @@ fn x_lix_default_rejects_invalid_cel_expression() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "mock",
-        "x-lix-version": "1",
         "properties": {
             "id": { "type": "string", "x-lix-default": "lix_uuid_v7(" }
         },