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

package/dist-engine-src/src/schema/annotations/defaults.rs

@@ -0,0 +1,280 @@
+use serde_json::{Map as JsonMap, Value as JsonValue};
+
+use crate::cel::{CelEvaluator, CelFunctionProvider};
+use crate::LixError;
+
+pub(crate) fn apply_schema_defaults<P>(
+    snapshot: &mut JsonMap<String, JsonValue>,
+    schema: &JsonValue,
+    evaluator: &CelEvaluator,
+    functions: P,
+    schema_key: &str,
+    schema_version: &str,
+) -> Result<bool, LixError>
+where
+    P: CelFunctionProvider,
+{
+    apply_schema_defaults_with_context(
+        snapshot,
+        schema,
+        &snapshot.clone(),
+        evaluator,
+        functions,
+        schema_key,
+        schema_version,
+    )
+}
+
+pub(crate) fn apply_schema_defaults_with_shared_runtime<P>(
+    snapshot: &mut JsonMap<String, JsonValue>,
+    schema: &JsonValue,
+    functions: P,
+    schema_key: &str,
+    schema_version: &str,
+) -> Result<bool, LixError>
+where
+    P: CelFunctionProvider,
+{
+    apply_schema_defaults(
+        snapshot,
+        schema,
+        crate::cel::shared_runtime(),
+        functions,
+        schema_key,
+        schema_version,
+    )
+}
+
+pub(crate) fn apply_schema_defaults_with_context<P>(
+    snapshot: &mut JsonMap<String, JsonValue>,
+    schema: &JsonValue,
+    context: &JsonMap<String, JsonValue>,
+    evaluator: &CelEvaluator,
+    functions: P,
+    schema_key: &str,
+    schema_version: &str,
+) -> Result<bool, LixError>
+where
+    P: CelFunctionProvider,
+{
+    let Some(properties) = schema.get("properties").and_then(|value| value.as_object()) else {
+        return Ok(false);
+    };
+    let mut ordered_properties: Vec<(&String, &JsonValue)> = properties.iter().collect();
+    ordered_properties.sort_by(|(left_name, _), (right_name, _)| left_name.cmp(right_name));
+
+    let mut changed = false;
+    for (field_name, field_schema) in ordered_properties {
+        if snapshot.contains_key(field_name) {
+            continue;
+        }
+
+        if let Some(expression) = field_schema
+            .get("x-lix-default")
+            .and_then(|value| value.as_str())
+        {
+            let value = evaluator
+                .evaluate_with_functions(expression, context, functions.clone())
+                .map_err(|err| LixError {
+                    code: "LIX_ERROR_UNKNOWN".to_string(),
+                    message: format!(
+                        "failed to evaluate x-lix-default for '{}.{}' ({}): {}",
+                        schema_key, field_name, schema_version, err.message
+                    ),
+                    hint: None,
+                    details: None,
+                })?;
+            snapshot.insert(field_name.clone(), value);
+            changed = true;
+            continue;
+        }
+
+        if let Some(default_value) = field_schema.get("default") {
+            snapshot.insert(field_name.clone(), default_value.clone());
+            changed = true;
+        }
+    }
+
+    Ok(changed)
+}
+
+#[cfg(test)]
+mod tests {
+    use serde_json::{json, Map as JsonMap, Value as JsonValue};
+
+    use crate::cel::{CelEvaluator, CelFunctionProvider};
+
+    use super::apply_schema_defaults_with_context;
+
+    #[test]
+    fn applies_x_lix_default_for_missing_fields() {
+        let evaluator = CelEvaluator::new();
+        let schema = json!({
+            "properties": {
+                "slug": {
+                    "type": "string",
+                    "x-lix-default": "name + '-slug'"
+                }
+            }
+        });
+        let mut snapshot = JsonMap::new();
+        snapshot.insert("name".to_string(), JsonValue::String("sample".to_string()));
+        let context = snapshot.clone();
+
+        let changed = apply_schema_defaults_with_context(
+            &mut snapshot,
+            &schema,
+            &context,
+            &evaluator,
+            fixed_functions(),
+            "test_schema",
+            "1",
+        )
+        .expect("apply defaults");
+
+        assert!(changed);
+        assert_eq!(
+            snapshot.get("slug"),
+            Some(&JsonValue::String("sample-slug".to_string()))
+        );
+    }
+
+    #[test]
+    fn x_lix_default_overrides_json_default() {
+        let evaluator = CelEvaluator::new();
+        let schema = json!({
+            "properties": {
+                "status": {
+                    "type": "string",
+                    "default": "literal",
+                    "x-lix-default": "'computed'"
+                }
+            }
+        });
+        let mut snapshot = JsonMap::new();
+        let context = snapshot.clone();
+
+        let changed = apply_schema_defaults_with_context(
+            &mut snapshot,
+            &schema,
+            &context,
+            &evaluator,
+            fixed_functions(),
+            "test_schema",
+            "1",
+        )
+        .expect("apply defaults");
+
+        assert!(changed);
+        assert_eq!(
+            snapshot.get("status"),
+            Some(&JsonValue::String("computed".to_string()))
+        );
+    }
+
+    #[test]
+    fn does_not_default_explicit_null_values() {
+        let evaluator = CelEvaluator::new();
+        let schema = json!({
+            "properties": {
+                "status": {
+                    "type": "string",
+                    "x-lix-default": "'computed'"
+                }
+            }
+        });
+        let mut snapshot = JsonMap::new();
+        snapshot.insert("status".to_string(), JsonValue::Null);
+        let context = snapshot.clone();
+
+        let changed = apply_schema_defaults_with_context(
+            &mut snapshot,
+            &schema,
+            &context,
+            &evaluator,
+            fixed_functions(),
+            "test_schema",
+            "1",
+        )
+        .expect("apply defaults");
+
+        assert!(!changed);
+        assert_eq!(snapshot.get("status"), Some(&JsonValue::Null));
+    }
+
+    #[test]
+    fn applies_cel_defaults_in_stable_sorted_field_order() {
+        #[derive(Clone)]
+        struct CountingFunctions {
+            next: std::sync::Arc<std::sync::atomic::AtomicI64>,
+        }
+
+        impl CelFunctionProvider for CountingFunctions {
+            fn call_uuid_v7(&self) -> String {
+                let current = self.next.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+                format!("uuid-{current}")
+            }
+
+            fn call_timestamp(&self) -> String {
+                let current = self.next.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+                format!("ts-{current}")
+            }
+        }
+
+        let evaluator = CelEvaluator::new();
+        let schema = json!({
+            "properties": {
+                "z_uuid": {
+                    "type": "string",
+                    "x-lix-default": "lix_uuid_v7()"
+                },
+                "a_timestamp": {
+                    "type": "string",
+                    "x-lix-default": "lix_timestamp()"
+                }
+            }
+        });
+        let mut snapshot = JsonMap::new();
+        let context = snapshot.clone();
+
+        let changed = apply_schema_defaults_with_context(
+            &mut snapshot,
+            &schema,
+            &context,
+            &evaluator,
+            CountingFunctions {
+                next: std::sync::Arc::new(std::sync::atomic::AtomicI64::new(0)),
+            },
+            "test_schema",
+            "1",
+        )
+        .expect("apply defaults");
+
+        assert!(changed);
+        assert_eq!(
+            snapshot.get("a_timestamp"),
+            Some(&JsonValue::String("ts-0".to_string()))
+        );
+        assert_eq!(
+            snapshot.get("z_uuid"),
+            Some(&JsonValue::String("uuid-1".to_string()))
+        );
+    }
+
+    #[derive(Clone)]
+    struct FixedFunctions;
+
+    impl CelFunctionProvider for FixedFunctions {
+        fn call_uuid_v7(&self) -> String {
+            "uuid-fixed".to_string()
+        }
+
+        fn call_timestamp(&self) -> String {
+            "1970-01-01T00:00:00.000Z".to_string()
+        }
+    }
+
+    fn fixed_functions() -> FixedFunctions {
+        FixedFunctions
+    }
+}

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

@@ -0,0 +1 @@
+pub(crate) mod defaults;

package/dist-engine-src/src/schema/builtin/lix_account.json

@@ -0,0 +1,22 @@
+{
+  "x-lix-key": "lix_account",
+  "x-lix-version": "1",
+  "x-lix-primary-key": [
+    "/id"
+  ],
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "x-lix-default": "lix_uuid_v7()"
+    },
+    "name": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "name"
+  ],
+  "additionalProperties": false
+}

package/dist-engine-src/src/schema/builtin/lix_active_account.json

@@ -0,0 +1,30 @@
+{
+  "x-lix-key": "lix_active_account",
+  "x-lix-version": "1",
+  "x-lix-primary-key": [
+    "/account_id"
+  ],
+  "x-lix-foreign-keys": [
+    {
+      "properties": [
+        "/account_id"
+      ],
+      "references": {
+        "schemaKey": "lix_account",
+        "properties": [
+          "/id"
+        ]
+      }
+    }
+  ],
+  "type": "object",
+  "properties": {
+    "account_id": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "account_id"
+  ],
+  "additionalProperties": false
+}

package/dist-engine-src/src/schema/builtin/lix_binary_blob_ref.json

@@ -0,0 +1,30 @@
+{
+  "x-lix-key": "lix_binary_blob_ref",
+  "x-lix-version": "1",
+  "description": "Metadata pointer from a file version to its binary payload in internal CAS storage.",
+  "x-lix-primary-key": [
+    "/id"
+  ],
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "File/entity identifier (matches lix_file.id) for this binary reference row."
+    },
+    "blob_hash": {
+      "type": "string",
+      "description": "BLAKE3 content hash used as the canonical CAS key for the binary payload."
+    },
+    "size_bytes": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Logical uncompressed file size in bytes for the referenced binary payload."
+    }
+  },
+  "required": [
+    "id",
+    "blob_hash",
+    "size_bytes"
+  ],
+  "additionalProperties": false
+}

package/dist-engine-src/src/schema/builtin/lix_change.json

@@ -0,0 +1,62 @@
+{
+  "x-lix-key": "lix_change",
+  "x-lix-version": "1",
+  "description": "Canonical immutable change fact. This surface represents the authoritative stream of journaled change facts. Commit lineage and non-commit scope are modeled separately around these facts.",
+  "x-lix-primary-key": [
+    "/id"
+  ],
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "x-lix-default": "lix_uuid_v7()",
+      "description": "Stable change identifier (UUIDv7). Referenced from `lix_commit.change_ids` and `lix_change_set_element.change_id`."
+    },
+    "entity_id": {
+      "type": "string",
+      "description": "The entity this change applies to, scoped by (`schema_key`, `file_id`)."
+    },
+    "schema_key": {
+      "type": "string",
+      "description": "Schema identifier of the entity (e.g. `lix_file_descriptor`, `lix_commit`, or a user-registered key)."
+    },
+    "schema_version": {
+      "type": "string",
+      "description": "Schema version the snapshot_content was written against (matches `x-lix-version` on the schema at write time)."
+    },
+    "file_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Filesystem-scoped file identifier when the change belongs to a file; NULL for engine-internal entities (commits, versions, settings)."
+    },
+    "metadata": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "description": "Optional user-provided JSON metadata attached to the change; NULL when nothing was supplied."
+    },
+    "created_at": {
+      "type": "string",
+      "description": "ISO-8601 timestamp at which the change was recorded (set via `lix_timestamp()` at write time)."
+    },
+    "snapshot_content": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "description": "Entity JSON body at this change; NULL represents a tombstone (deletion)."
+    }
+  },
+  "required": [
+    "id",
+    "entity_id",
+    "schema_key",
+    "schema_version",
+    "file_id",
+    "created_at"
+  ],
+  "additionalProperties": false
+}

package/dist-engine-src/src/schema/builtin/lix_change_author.json

@@ -0,0 +1,46 @@
+{
+  "x-lix-key": "lix_change_author",
+  "x-lix-version": "1",
+  "x-lix-primary-key": [
+    "/change_id",
+    "/account_id"
+  ],
+  "x-lix-foreign-keys": [
+    {
+      "properties": [
+        "/change_id"
+      ],
+      "references": {
+        "schemaKey": "lix_change",
+        "properties": [
+          "/id"
+        ]
+      }
+    },
+    {
+      "properties": [
+        "/account_id"
+      ],
+      "references": {
+        "schemaKey": "lix_account",
+        "properties": [
+          "/id"
+        ]
+      }
+    }
+  ],
+  "type": "object",
+  "properties": {
+    "change_id": {
+      "type": "string"
+    },
+    "account_id": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "change_id",
+    "account_id"
+  ],
+  "additionalProperties": false
+}

package/dist-engine-src/src/schema/builtin/lix_change_set.json

@@ -0,0 +1,18 @@
+{
+  "x-lix-key": "lix_change_set",
+  "x-lix-version": "1",
+  "x-lix-primary-key": [
+    "/id"
+  ],
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "x-lix-default": "lix_uuid_v7()"
+    }
+  },
+  "required": [
+    "id"
+  ],
+  "additionalProperties": false
+}

package/dist-engine-src/src/schema/builtin/lix_change_set_element.json

@@ -0,0 +1,75 @@
+{
+  "x-lix-key": "lix_change_set_element",
+  "x-lix-version": "1",
+  "description": "Derived relational index mapping a change_set to the canonical changes introduced by its commit relative to the commit's first parent. Rebuildable from `lix_commit.change_ids` plus the referenced `lix_change` rows; the unique constraint enforces at most one change per (entity, schema, file) tuple within a single change_set.",
+  "x-lix-primary-key": [
+    "/change_set_id",
+    "/change_id"
+  ],
+  "x-lix-unique": [
+    [
+      "/change_set_id",
+      "/entity_id",
+      "/schema_key",
+      "/file_id"
+    ]
+  ],
+  "x-lix-foreign-keys": [
+    {
+      "properties": [
+        "/change_set_id"
+      ],
+      "references": {
+        "schemaKey": "lix_change_set",
+        "properties": [
+          "/id"
+        ]
+      }
+    },
+    {
+      "properties": [
+        "/change_id"
+      ],
+      "references": {
+        "schemaKey": "lix_change",
+        "properties": [
+          "/id"
+        ]
+      }
+    }
+  ],
+  "type": "object",
+  "properties": {
+    "change_set_id": {
+      "type": "string",
+      "description": "The change_set this element belongs to (references `lix_change_set.id`)."
+    },
+    "change_id": {
+      "type": "string",
+      "description": "The canonical change introduced/adopted by the change_set's commit (references `lix_change.id`)."
+    },
+    "entity_id": {
+      "type": "string",
+      "description": "Denormalized from the referenced `lix_change` for fast entity-scoped queries and to anchor the unique constraint."
+    },
+    "schema_key": {
+      "type": "string",
+      "description": "Denormalized schema identifier from the referenced `lix_change`; part of the per-change_set uniqueness tuple."
+    },
+    "file_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Denormalized file scope from the referenced `lix_change`; NULL for engine-internal entities. Part of the per-change_set uniqueness tuple."
+    }
+  },
+  "required": [
+    "change_set_id",
+    "change_id",
+    "entity_id",
+    "schema_key",
+    "file_id"
+  ],
+  "additionalProperties": false
+}

package/dist-engine-src/src/schema/builtin/lix_commit.json

@@ -0,0 +1,62 @@
+{
+  "x-lix-key": "lix_commit",
+  "x-lix-version": "1",
+  "description": "Commit header change. Canonical commit membership is stored in change_ids as the ordered list of canonical changes whose effects this commit introduces relative to its first parent. A merge commit may reference canonical changes originally authored in another parent instead of copying them. Derived projections such as lix_change_set_element must be rebuildable from this header plus the referenced change rows. Version head pointers such as lix_version_ref are maintained separately and are not commit members.",
+  "x-lix-primary-key": [
+    "/id"
+  ],
+  "x-lix-foreign-keys": [
+    {
+      "properties": [
+        "/change_set_id"
+      ],
+      "references": {
+        "schemaKey": "lix_change_set",
+        "properties": [
+          "/id"
+        ]
+      }
+    }
+  ],
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "x-lix-default": "lix_uuid_v7()",
+      "description": "Stable commit identifier."
+    },
+    "change_set_id": {
+      "type": "string",
+      "description": "Commit-local grouping identifier used by derived relational indexes and projections such as lix_change_set_element."
+    },
+    "change_ids": {
+      "type": "array",
+      "default": [],
+      "items": {
+        "type": "string"
+      },
+      "description": "Canonical ordered membership list of non-header change IDs whose effects this commit introduces relative to its first parent. Merge commits may reference existing changes from another parent instead of minting equivalent copies. Derived indexes such as lix_change_set_element must be rebuildable from this list. This does not include lix_version_ref pointer rows."
+    },
+    "author_account_ids": {
+      "type": "array",
+      "default": [],
+      "items": {
+        "type": "string"
+      },
+      "description": "Ordered set of author account IDs associated with this commit."
+    },
+    "parent_commit_ids": {
+      "type": "array",
+      "default": [],
+      "items": {
+        "type": "string"
+      },
+      "description": "Parent commit IDs for commit graph topology."
+    }
+  },
+  "required": [
+    "id",
+    "change_set_id"
+  ],
+  "additionalProperties": false
+}

package/dist-engine-src/src/schema/builtin/lix_commit_edge.json

@@ -0,0 +1,46 @@
+{
+  "x-lix-key": "lix_commit_edge",
+  "x-lix-version": "1",
+  "x-lix-primary-key": [
+    "/parent_id",
+    "/child_id"
+  ],
+  "x-lix-foreign-keys": [
+    {
+      "properties": [
+        "/parent_id"
+      ],
+      "references": {
+        "schemaKey": "lix_commit",
+        "properties": [
+          "/id"
+        ]
+      }
+    },
+    {
+      "properties": [
+        "/child_id"
+      ],
+      "references": {
+        "schemaKey": "lix_commit",
+        "properties": [
+          "/id"
+        ]
+      }
+    }
+  ],
+  "type": "object",
+  "properties": {
+    "parent_id": {
+      "type": "string"
+    },
+    "child_id": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "parent_id",
+    "child_id"
+  ],
+  "additionalProperties": false
+}