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

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

@@ -0,0 +1,275 @@
+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,
+) -> Result<bool, LixError>
+where
+    P: CelFunctionProvider,
+{
+    apply_schema_defaults_with_context(
+        snapshot,
+        schema,
+        &snapshot.clone(),
+        evaluator,
+        functions,
+        schema_key,
+    )
+}
+
+pub(crate) fn apply_schema_defaults_with_shared_runtime<P>(
+    snapshot: &mut JsonMap<String, JsonValue>,
+    schema: &JsonValue,
+    functions: P,
+    schema_key: &str,
+) -> Result<bool, LixError>
+where
+    P: CelFunctionProvider,
+{
+    apply_schema_defaults(
+        snapshot,
+        schema,
+        crate::cel::shared_runtime(),
+        functions,
+        schema_key,
+    )
+}
+
+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,
+) -> 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, 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,21 @@
+{
+  "x-lix-key": "lix_account",
+  "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,29 @@
+{
+  "x-lix-key": "lix_active_account",
+  "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,29 @@
+{
+  "x-lix-key": "lix_binary_blob_ref",
+  "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,63 @@
+{
+  "x-lix-key": "lix_change",
+  "description": "A change records one edit to a Lix entity, including what changed, when it changed, and which entity was affected.",
+  "x-lix-primary-key": [
+    "/id"
+  ],
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "x-lix-default": "lix_uuid_v7()",
+      "description": "Stable identifier for this change."
+    },
+    "entity_id": {
+      "type": "array",
+      "description": "Canonical JSON primary-key tuple for the entity this change applies to, scoped by (`schema_key`, `file_id`). Values are ordered according to the target schema's `x-lix-primary-key`.",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    },
+    "schema_key": {
+      "type": "string",
+      "description": "Schema identifier of the entity (e.g. `lix_file_descriptor`, `lix_commit`, or a user-registered key)."
+    },
+    "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",
+      "examples": [
+        "2026-05-08T17:42:31.123Z"
+      ],
+      "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",
+    "file_id",
+    "created_at"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,45 @@
+{
+  "x-lix-key": "lix_change_author",
+  "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_commit.json

@@ -0,0 +1,24 @@
+{
+  "x-lix-key": "lix_commit",
+  "description": "A commit is a stable point in project history. Versions point to commits. Use lix_commit_edge to inspect parent commits.",
+  "examples": [
+    {
+      "id": "commit_01jexample"
+    }
+  ],
+  "x-lix-primary-key": [
+    "/id"
+  ],
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "x-lix-default": "lix_uuid_v7()",
+      "description": "Stable identifier of this commit."
+    }
+  },
+  "required": [
+    "id"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,53 @@
+{
+  "x-lix-key": "lix_commit_edge",
+  "description": "Direct parent relationship between two commits. Merge commits have one row per parent. The first parent is useful for showing mainline history or comparing a merge commit against the commit that was checked out before the merge.",
+  "examples": [
+    {
+      "parent_id": "commit-main",
+      "child_id": "commit-merge",
+      "parent_order": 0
+    },
+    {
+      "parent_id": "commit-feature",
+      "child_id": "commit-merge",
+      "parent_order": 1
+    }
+  ],
+  "x-lix-primary-key": ["/child_id", "/parent_order"],
+  "x-lix-unique": [["/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",
+      "description": "Identifier of the parent commit."
+    },
+    "child_id": {
+      "type": "string",
+      "description": "Identifier of the child commit."
+    },
+    "parent_order": {
+      "type": "integer",
+      "minimum": 0,
+      "examples": [0, 1],
+      "description": "Zero-based position of this parent in the child commit's ordered parent list. The first parent has order 0; additional merge parents have order 1, 2, and so on."
+    }
+  },
+  "required": ["parent_id", "child_id", "parent_order"],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,52 @@
+{
+  "x-lix-key": "lix_directory_descriptor",
+  "x-lix-primary-key": [
+    "/id"
+  ],
+  "x-lix-unique": [
+    [
+      "/parent_id",
+      "/name"
+    ]
+  ],
+  "x-lix-foreign-keys": [
+    {
+      "properties": [
+        "/parent_id"
+      ],
+      "references": {
+        "schemaKey": "lix_directory_descriptor",
+        "properties": [
+          "/id"
+        ]
+      }
+    }
+  ],
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "x-lix-default": "lix_uuid_v7()"
+    },
+    "parent_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^(?!\\.{1,2}$)[^/\\\\]+$"
+    },
+    "hidden": {
+      "type": "boolean",
+      "x-lix-default": "false"
+    }
+  },
+  "required": [
+    "id",
+    "parent_id",
+    "name"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,52 @@
+{
+  "x-lix-key": "lix_file_descriptor",
+  "x-lix-primary-key": [
+    "/id"
+  ],
+  "x-lix-unique": [
+    [
+      "/directory_id",
+      "/name"
+    ]
+  ],
+  "x-lix-foreign-keys": [
+    {
+      "properties": [
+        "/directory_id"
+      ],
+      "references": {
+        "schemaKey": "lix_directory_descriptor",
+        "properties": [
+          "/id"
+        ]
+      }
+    }
+  ],
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "x-lix-default": "lix_uuid_v7()"
+    },
+    "directory_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^(?!\\.{1,2}$)[^/\\\\]+$"
+    },
+    "hidden": {
+      "type": "boolean",
+      "x-lix-default": "false"
+    }
+  },
+  "required": [
+    "id",
+    "directory_id",
+    "name"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,40 @@
+{
+  "x-lix-key": "lix_key_value",
+  "x-lix-primary-key": [
+    "/key"
+  ],
+  "type": "object",
+  "properties": {
+    "key": {
+      "type": "string"
+    },
+    "value": {
+      "description": "Arbitrary JSON value. This field stays in the JSON domain even when different rows hold different JSON kinds.",
+      "anyOf": [
+        {
+          "type": "object"
+        },
+        {
+          "type": "array"
+        },
+        {
+          "type": "string"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "key",
+    "value"
+  ],
+  "additionalProperties": false
+}