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

package/dist-engine-src/src/schema/definition.json

@@ -1,19 +1,30 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "Lix Schema Definition",
-  "description": "A Lix schema is a JSON Schema draft 2020-12 document augmented with `x-lix-*` extensions that identify, version, and constrain an entity type. Every schema must declare `x-lix-key` (snake_case identifier, preferably prefixed with a plugin or domain namespace such as `library_book` to avoid collisions), `x-lix-version` (string-as-integer, e.g. `\"1\"`), and `additionalProperties: false`; add `x-lix-primary-key` (array of JSON Pointers) to make the schema writable — Lix will auto-materialize a public virtual table named after `x-lix-key` with an `INSERT/UPDATE/DELETE` surface. See the `examples` field for a minimal working schema.",
+  "description": "A Lix schema is a JSON Schema draft 2020-12 document augmented with `x-lix-*` extensions that identify and constrain an entity type. Every schema must declare `x-lix-key` (snake_case identifier, preferably prefixed with a plugin or domain namespace such as `library_book` to avoid collisions) and `additionalProperties: false`; add `x-lix-primary-key` (array of JSON Pointers to required string properties) to make the schema writable. Lix will auto-materialize a public virtual table named after `x-lix-key` with an `INSERT/UPDATE/DELETE` surface. See the `examples` field for a minimal working schema.",
   "examples": [
     {
       "x-lix-key": "library_book",
-      "x-lix-version": "1",
       "type": "object",
-      "x-lix-primary-key": ["/id"],
+      "x-lix-primary-key": [
+        "/id"
+      ],
       "properties": {
-        "id": { "type": "string", "x-lix-default": "lix_uuid_v7()" },
-        "title": { "type": "string" },
-        "author": { "type": "string" }
+        "id": {
+          "type": "string",
+          "x-lix-default": "lix_uuid_v7()"
+        },
+        "title": {
+          "type": "string"
+        },
+        "author": {
+          "type": "string"
+        }
       },
-      "required": ["id", "title"],
+      "required": [
+        "id",
+        "title"
+      ],
       "additionalProperties": false
     }
   ],
@@ -47,7 +58,7 @@
           "type": "array",
           "minItems": 1,
           "uniqueItems": true,
-          "description": "Primary-key fields as JSON Pointers (RFC 6901) into the entity, e.g. `[\"/id\"]` for a single-column key or `[\"/tenant_id\", \"/handle\"]` for a composite key. Note the leading slash; `\"id\"` without a slash is not a valid pointer.",
+          "description": "Primary-key fields as JSON Pointers (RFC 6901) into required string-valued entity properties, e.g. `[\"/id\"]` for a single-column key or `[\"/tenant_id\", \"/handle\"]` for a composite key. Note the leading slash; `\"id\"` without a slash is not a valid pointer.",
           "items": {
             "type": "string",
             "format": "json-pointer",
@@ -103,6 +114,34 @@
             }
           }
         },
+        "x-lix-state-foreign-keys": {
+          "type": "array",
+          "description": "Foreign keys from local fields to arbitrary live state rows. Each entry is exactly three required local JSON Pointers ordered as `[entity_id, schema_key, file_id]`: index 0 points to the local entity_id JSON array, index 1 points to the local schema_key string, and index 2 points to the local file_id string-or-null. Use explicit null for global file_id targets; omitted fields are invalid. The referenced state row is resolved in the same version.",
+          "items": {
+            "type": "array",
+            "minItems": 3,
+            "maxItems": 3,
+            "uniqueItems": true,
+            "prefixItems": [
+              {
+                "type": "string",
+                "format": "json-pointer",
+                "description": "[0] Local JSON Pointer for the target entity_id. The value must be a non-empty JSON array of strings."
+              },
+              {
+                "type": "string",
+                "format": "json-pointer",
+                "description": "[1] Local JSON Pointer for the target schema_key. The value must be a string."
+              },
+              {
+                "type": "string",
+                "format": "json-pointer",
+                "description": "[2] Local JSON Pointer for the target file_id. The value must be a string or null."
+              }
+            ],
+            "items": false
+          }
+        },
         "x-lix-key": {
           "type": "string",
           "pattern": "^[a-z][a-z0-9_]*$",
@@ -112,14 +151,6 @@
             "csv_plugin_cell"
           ]
         },
-        "x-lix-version": {
-          "type": "string",
-          "pattern": "^[1-9]\\d*$",
-          "description": "Schema version identifier. Deliberately constrained to a monotonic integer (as a string) without leading zeros to keep translation rules open while avoiding future breaking changes.",
-          "examples": [
-            "1"
-          ]
-        },
         "properties": {
           "type": "object",
           "additionalProperties": {
@@ -149,7 +180,6 @@
       },
       "required": [
         "x-lix-key",
-        "x-lix-version",
         "additionalProperties"
       ]
     }

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

@@ -4,6 +4,7 @@ use serde_json::Value as JsonValue;
 use std::collections::BTreeSet;
 use std::sync::OnceLock;
 
+use crate::common::parse_json_pointer;
 use crate::LixError;
 
 static LIX_SCHEMA_DEFINITION: OnceLock<JsonValue> = OnceLock::new();
@@ -11,9 +12,6 @@ static LIX_SCHEMA_VALIDATOR: OnceLock<Result<JSONSchema, LixError>> = OnceLock::
 
 pub fn lix_schema_definition() -> &'static JsonValue {
     LIX_SCHEMA_DEFINITION.get_or_init(|| {
-        // NOTE: x-lix-version is intentionally constrained to a monotonic integer (as a string).
-        // This keeps translation rules open while avoiding a future breaking change when versioning
-        // semantics become concrete.
         let raw = include_str!("definition.json");
         serde_json::from_str(raw).expect("definition.json must be valid JSON")
     })
@@ -27,6 +25,9 @@ pub fn validate_lix_schema_definition(schema: &JsonValue) -> Result<(), LixError
     if let Some(err) = detect_missing_pointer_slash(schema) {
         return Err(err);
     }
+    if let Some(err) = detect_state_foreign_key_tuple_shape(schema) {
+        return Err(err);
+    }
 
     let validator = lix_schema_validator()?;
     if let Err(errors) = validator.validate(schema) {
@@ -41,13 +42,39 @@ pub fn validate_lix_schema_definition(schema: &JsonValue) -> Result<(), LixError
 
     assert_primary_key_pointers(schema)?;
     assert_unique_pointers(schema)?;
-    assert_non_aliased_lix_foreign_key_references(schema)?;
+    assert_state_foreign_key_pointers(schema)?;
     assert_known_x_lix_top_level_fields(schema)?;
+    assert_entity_properties_do_not_use_reserved_lix_prefix(schema)?;
     assert_entity_properties_have_projectable_types(schema)?;
 
     Ok(())
 }
 
+fn assert_entity_properties_do_not_use_reserved_lix_prefix(
+    schema: &JsonValue,
+) -> Result<(), LixError> {
+    let Some(schema_key) = schema.get("x-lix-key").and_then(JsonValue::as_str) else {
+        return Ok(());
+    };
+    let Some(properties) = schema.get("properties").and_then(JsonValue::as_object) else {
+        return Ok(());
+    };
+
+    for property_name in properties.keys() {
+        if property_name.starts_with("lix") {
+            return Err(LixError::new(
+                LixError::CODE_SCHEMA_DEFINITION,
+                format!(
+                    "Invalid Lix schema definition: schema '{schema_key}' property '/{property_name}' uses reserved prefix 'lix'."
+                ),
+            )
+            .with_hint("Property names starting with 'lix' are reserved for Lix system fields."));
+        }
+    }
+
+    Ok(())
+}
+
 fn assert_entity_properties_have_projectable_types(schema: &JsonValue) -> Result<(), LixError> {
     let Some(schema_key) = schema.get("x-lix-key").and_then(JsonValue::as_str) else {
         return Ok(());
@@ -57,9 +84,6 @@ fn assert_entity_properties_have_projectable_types(schema: &JsonValue) -> Result
     };
 
     for (property_name, property_schema) in properties {
-        if property_name.starts_with("lixcol_") {
-            continue;
-        }
         if !schema_property_has_sql_projection_type(property_schema) {
             return Err(LixError::new(
                 LixError::CODE_SCHEMA_DEFINITION,
@@ -110,7 +134,8 @@ fn collect_schema_type_kinds<'a>(schema: &'a JsonValue, out: &mut BTreeSet<&'a s
 
 /// Detect the common no-leading-slash mistake in JSON-Pointer-valued fields
 /// (`x-lix-primary-key`, `x-lix-unique`, `x-lix-foreign-keys[].properties`,
-/// `x-lix-foreign-keys[].references.properties`) and return a targeted
+/// `x-lix-foreign-keys[].references.properties`,
+/// `x-lix-state-foreign-keys[]`) and return a targeted
 /// error + hint suggesting the fix.
 ///
 /// Surfacing this before the meta-schema validator runs replaces the
@@ -166,6 +191,15 @@ fn detect_missing_pointer_slash(schema: &JsonValue) -> Option<LixError> {
         }
     }
 
+    if let Some(fks) = schema
+        .get("x-lix-state-foreign-keys")
+        .and_then(JsonValue::as_array)
+    {
+        for fk in fks {
+            collect(fk.as_array(), "x-lix-state-foreign-keys", &mut offenders);
+        }
+    }
+
     if offenders.is_empty() {
         return None;
     }
@@ -194,6 +228,26 @@ fn detect_missing_pointer_slash(schema: &JsonValue) -> Option<LixError> {
     )
 }
 
+fn detect_state_foreign_key_tuple_shape(schema: &JsonValue) -> Option<LixError> {
+    let foreign_keys = schema
+        .get("x-lix-state-foreign-keys")
+        .and_then(JsonValue::as_array)?;
+    for (index, foreign_key) in foreign_keys.iter().enumerate() {
+        let Some(local_pointers) = foreign_key.as_array() else {
+            continue;
+        };
+        if local_pointers.len() != 3 {
+            return Some(LixError::new(
+                LixError::CODE_SCHEMA_DEFINITION,
+                format!(
+                    "Invalid Lix schema definition: x-lix-state-foreign-keys[{index}] must contain exactly three JSON Pointers ordered as [entity_id, schema_key, file_id]; [0] entity_id, [1] schema_key, [2] file_id."
+                ),
+            ));
+        }
+    }
+    None
+}
+
 pub fn validate_lix_schema(schema: &JsonValue, data: &JsonValue) -> Result<(), LixError> {
     validate_lix_schema_definition(schema)?;
 
@@ -257,50 +311,6 @@ fn is_cel_expression(value: &str) -> bool {
     Program::compile(value).is_ok()
 }
 
-fn parse_json_pointer(pointer: &str) -> Result<Vec<String>, LixError> {
-    if pointer.is_empty() {
-        return Ok(Vec::new());
-    }
-    if !pointer.starts_with('/') {
-        return Err(LixError {
-            code: LixError::CODE_SCHEMA_DEFINITION.to_string(),
-            message: "Invalid JSON pointer".to_string(),
-            hint: None,
-            details: None,
-        });
-    }
-
-    let mut segments = Vec::new();
-    for raw in pointer[1..].split('/') {
-        segments.push(unescape_pointer_segment(raw)?);
-    }
-    Ok(segments)
-}
-
-fn unescape_pointer_segment(segment: &str) -> Result<String, LixError> {
-    let mut out = String::new();
-    let mut chars = segment.chars();
-    while let Some(ch) = chars.next() {
-        if ch == '~' {
-            match chars.next() {
-                Some('0') => out.push('~'),
-                Some('1') => out.push('/'),
-                _ => {
-                    return Err(LixError {
-                        code: LixError::CODE_SCHEMA_DEFINITION.to_string(),
-                        message: "Invalid JSON pointer".to_string(),
-                        hint: None,
-                        details: None,
-                    })
-                }
-            }
-        } else {
-            out.push(ch);
-        }
-    }
-    Ok(out)
-}
-
 fn assert_primary_key_pointers(schema: &JsonValue) -> Result<(), LixError> {
     let Some(primary_key) = schema
         .get("x-lix-primary-key")
@@ -314,7 +324,10 @@ fn assert_primary_key_pointers(schema: &JsonValue) -> Result<(), LixError> {
             continue;
         };
         let segments = parse_json_pointer(pointer)?;
-        if segments.is_empty() || !schema_has_property(schema, &segments) {
+        let Some(property_schema) = (!segments.is_empty())
+            .then(|| schema_property(schema, &segments))
+            .flatten()
+        else {
             return Err(LixError { code: LixError::CODE_SCHEMA_DEFINITION.to_string(), message: format!(
                     "Invalid Lix schema definition: x-lix-primary-key references missing property \"{}\".",
                     pointer
@@ -322,6 +335,22 @@ fn assert_primary_key_pointers(schema: &JsonValue) -> Result<(), LixError> {
                 hint: None,
             details: None,
             });
+        };
+        if !schema_property_is_string_only(property_schema) {
+            return Err(LixError::new(
+                LixError::CODE_SCHEMA_DEFINITION,
+                format!(
+                    "Invalid Lix schema definition: x-lix-primary-key property \"{pointer}\" must have type \"string\"."
+                ),
+            ));
+        }
+        if !schema_pointer_is_required(schema, &segments) {
+            return Err(LixError::new(
+                LixError::CODE_SCHEMA_DEFINITION,
+                format!(
+                    "Invalid Lix schema definition: x-lix-primary-key property \"{pointer}\" must be required."
+                ),
+            ));
         }
     }
 
@@ -360,33 +389,67 @@ fn assert_unique_pointers(schema: &JsonValue) -> Result<(), LixError> {
     Ok(())
 }
 
-fn assert_non_aliased_lix_foreign_key_references(schema: &JsonValue) -> Result<(), LixError> {
+fn assert_state_foreign_key_pointers(schema: &JsonValue) -> Result<(), LixError> {
     let Some(foreign_keys) = schema
-        .get("x-lix-foreign-keys")
+        .get("x-lix-state-foreign-keys")
         .and_then(|value| value.as_array())
     else {
         return Ok(());
     };
 
-    for foreign_key in foreign_keys {
-        let Some(schema_key) = foreign_key
-            .get("references")
-            .and_then(|value| value.get("schemaKey"))
-            .and_then(|value| value.as_str())
-        else {
+    for (index, foreign_key) in foreign_keys.iter().enumerate() {
+        let Some(local_pointers) = foreign_key.as_array() else {
             continue;
         };
-
-        let Some(replacement) = preferred_lix_schema_key_alias(schema_key) else {
+        if local_pointers.len() != 3 {
             continue;
-        };
+        }
 
-        return Err(LixError { code: LixError::CODE_SCHEMA_DEFINITION.to_string(), message: format!(
-                "Invalid Lix schema definition: x-lix-foreign-keys references.schemaKey uses deprecated alias \"{schema_key}\"; use \"{replacement}\"."
-            ),
-            hint: None,
-            details: None,
-        });
+        let roles = [
+            ("entity_id", "a non-empty JSON array of strings"),
+            ("schema_key", "a string"),
+            ("file_id", "a string or null"),
+        ];
+        for (slot, (role, expected)) in roles.iter().enumerate() {
+            let Some(pointer) = local_pointers[slot].as_str() else {
+                continue;
+            };
+            let segments = parse_json_pointer(pointer)?;
+            let Some(property_schema) = (!segments.is_empty())
+                .then(|| schema_property(schema, &segments))
+                .flatten()
+            else {
+                return Err(LixError::new(
+                    LixError::CODE_SCHEMA_DEFINITION,
+                    format!(
+                        "Invalid Lix schema definition: x-lix-state-foreign-keys[{index}][{slot}] ({role}) references missing property \"{pointer}\"."
+                    ),
+                ));
+            };
+            if !schema_pointer_is_required(schema, &segments) {
+                return Err(LixError::new(
+                    LixError::CODE_SCHEMA_DEFINITION,
+                    format!(
+                        "Invalid Lix schema definition: x-lix-state-foreign-keys[{index}][{slot}] ({role}) property \"{pointer}\" must be required. Tuple order is [entity_id, schema_key, file_id]."
+                    ),
+                ));
+            }
+
+            let valid = match *role {
+                "entity_id" => schema_property_is_string_array(property_schema),
+                "schema_key" => schema_property_is_string_only(property_schema),
+                "file_id" => schema_property_is_string_or_null(property_schema),
+                _ => unreachable!("state foreign key roles are exhaustive"),
+            };
+            if !valid {
+                return Err(LixError::new(
+                    LixError::CODE_SCHEMA_DEFINITION,
+                    format!(
+                        "Invalid Lix schema definition: x-lix-state-foreign-keys[{index}][{slot}] ({role}) property \"{pointer}\" must be {expected}. Tuple order is [entity_id, schema_key, file_id]."
+                    ),
+                ));
+            }
+        }
     }
 
     Ok(())
@@ -405,10 +468,10 @@ fn assert_known_x_lix_top_level_fields(schema: &JsonValue) -> Result<(), LixErro
         let known = matches!(
             key.as_str(),
             "x-lix-key"
-                | "x-lix-version"
                 | "x-lix-primary-key"
                 | "x-lix-unique"
                 | "x-lix-foreign-keys"
+                | "x-lix-state-foreign-keys"
         );
 
         if !known {
@@ -427,40 +490,84 @@ fn assert_known_x_lix_top_level_fields(schema: &JsonValue) -> Result<(), LixErro
     Ok(())
 }
 
-fn preferred_lix_schema_key_alias(schema_key: &str) -> Option<&'static str> {
-    match schema_key {
-        "state" => Some("lix_state"),
-        "state_by_version" => Some("lix_state_by_version"),
-        "state_history" => Some("lix_state_history"),
-        "state_history_by_version" => Some("lix_state_history_by_version"),
-        "label" => Some("lix_label"),
-        "entity_label" => Some("lix_entity_label"),
-        "conversation" => Some("lix_conversation"),
-        "entity_conversation" => Some("lix_entity_conversation"),
-        _ => None,
-    }
+fn schema_has_property(schema: &JsonValue, segments: &[String]) -> bool {
+    schema_property(schema, segments).is_some()
 }
 
-fn schema_has_property(schema: &JsonValue, segments: &[String]) -> bool {
+fn schema_pointer_is_required(schema: &JsonValue, segments: &[String]) -> bool {
+    if segments.is_empty() {
+        return false;
+    }
+
     let mut node = schema;
     for segment in segments {
-        let properties = match node.get("properties") {
-            Some(properties) => properties,
-            None => return false,
-        };
-        let properties = match properties.as_object() {
-            Some(properties) => properties,
-            None => return false,
-        };
-        let next = match properties.get(segment) {
-            Some(next) => next,
-            None => return false,
+        let required = node
+            .get("required")
+            .and_then(JsonValue::as_array)
+            .map(|required| {
+                required
+                    .iter()
+                    .any(|required_property| required_property.as_str() == Some(segment))
+            })
+            .unwrap_or(false);
+        if !required {
+            return false;
+        }
+
+        let Some(next) = node
+            .get("properties")
+            .and_then(JsonValue::as_object)
+            .and_then(|properties| properties.get(segment))
+        else {
+            return false;
         };
         node = next;
     }
+
     true
 }
 
+fn schema_property<'a>(schema: &'a JsonValue, segments: &[String]) -> Option<&'a JsonValue> {
+    let mut node = schema;
+    for segment in segments {
+        let properties = node.get("properties")?.as_object()?;
+        let next = properties.get(segment)?;
+        node = next;
+    }
+    Some(node)
+}
+
+fn schema_property_is_string_only(schema: &JsonValue) -> bool {
+    let mut kinds = BTreeSet::new();
+    collect_schema_type_kinds(schema, &mut kinds);
+    kinds.len() == 1 && kinds.contains("string")
+}
+
+fn schema_property_is_string_or_null(schema: &JsonValue) -> bool {
+    let mut kinds = BTreeSet::new();
+    collect_schema_type_kinds(schema, &mut kinds);
+    kinds.remove("null");
+    kinds.len() == 1 && kinds.contains("string")
+}
+
+fn schema_property_is_string_array(schema: &JsonValue) -> bool {
+    let mut kinds = BTreeSet::new();
+    collect_schema_type_kinds(schema, &mut kinds);
+    if kinds.len() != 1 || !kinds.contains("array") {
+        return false;
+    }
+    let Some(items) = schema.get("items") else {
+        return false;
+    };
+    if !schema_property_is_string_only(items) {
+        return false;
+    }
+    schema
+        .get("minItems")
+        .and_then(JsonValue::as_u64)
+        .is_some_and(|min_items| min_items >= 1)
+}
+
 pub(crate) fn format_lix_schema_validation_errors<'a>(
     errors: impl Iterator<Item = jsonschema::ValidationError<'a>>,
 ) -> String {
@@ -490,7 +597,6 @@ mod pointer_slash_detection_tests {
         let mut obj = json!({
             "type": "object",
             "x-lix-key": "book",
-            "x-lix-version": "1",
             "properties": {
                 "id": { "type": "string" },
                 "author_id": { "type": "string" },