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

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

@@ -0,0 +1,29 @@
+{
+  "x-lix-key": "lix_label",
+  "description": "Catalog of labels that can be assigned to arbitrary live Lix rows through lix_label_assignment.",
+  "x-lix-primary-key": [
+    "/id"
+  ],
+  "x-lix-unique": [
+    [
+      "/name"
+    ]
+  ],
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "x-lix-default": "lix_uuid_v7()",
+      "description": "Stable label identifier. Label assignments reference this value."
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable label name. Unique across labels."
+    }
+  },
+  "required": [
+    "id",
+    "name"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,74 @@
+{
+  "x-lix-key": "lix_label_assignment",
+  "description": "Mapping table that assigns a label to any live Lix row addressed by (target_entity_id, target_schema_key, target_file_id). The state foreign-key tuple is ordered as [0] target_entity_id, [1] target_schema_key, [2] target_file_id.",
+  "x-lix-primary-key": [
+    "/id"
+  ],
+  "x-lix-unique": [
+    [
+      "/target_entity_id",
+      "/target_schema_key",
+      "/target_file_id",
+      "/label_id"
+    ]
+  ],
+  "x-lix-state-foreign-keys": [
+    [
+      "/target_entity_id",
+      "/target_schema_key",
+      "/target_file_id"
+    ]
+  ],
+  "x-lix-foreign-keys": [
+    {
+      "properties": [
+        "/label_id"
+      ],
+      "references": {
+        "schemaKey": "lix_label",
+        "properties": [
+          "/id"
+        ]
+      }
+    }
+  ],
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "x-lix-default": "lix_uuid_v7()",
+      "description": "Stable identifier for this label assignment row."
+    },
+    "target_entity_id": {
+      "type": "array",
+      "description": "Target row entity_id. This is slot [0] in x-lix-state-foreign-keys and must be the canonical JSON array of string primary-key parts.",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    },
+    "target_schema_key": {
+      "type": "string",
+      "description": "Target row schema key. This is slot [1] in x-lix-state-foreign-keys."
+    },
+    "target_file_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Target row file scope. This is slot [2] in x-lix-state-foreign-keys; null targets global rows."
+    },
+    "label_id": {
+      "type": "string",
+      "description": "Label assigned to the target row. References lix_label.id."
+    }
+  },
+  "required": [
+    "id",
+    "target_entity_id",
+    "target_schema_key",
+    "target_file_id",
+    "label_id"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,25 @@
+{
+  "x-lix-key": "lix_registered_schema",
+  "x-lix-primary-key": [
+    "/value/x-lix-key"
+  ],
+  "type": "object",
+  "properties": {
+    "value": {
+      "type": "object",
+      "properties": {
+        "x-lix-key": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "x-lix-key"
+      ],
+      "additionalProperties": true
+    }
+  },
+  "required": [
+    "value"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,34 @@
+{
+  "x-lix-key": "lix_version_descriptor",
+  "description": "User-facing version metadata (name and visibility) for a branch-like version. The stable identity of a version; the matching `lix_version_ref` carries the moving head pointer. The catalog's `lix_version` surface joins this descriptor with its ref to present a single user-visible version row.",
+  "x-lix-primary-key": [
+    "/id"
+  ],
+  "x-lix-unique": [
+    [
+      "/name"
+    ]
+  ],
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "x-lix-default": "lix_uuid_v7()",
+      "description": "Stable version identifier (UUIDv7). Referenced by `lix_version_ref.id`."
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable version name (e.g. `main`, `feature-x`) shown in version listings and CLI output."
+    },
+    "hidden": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, the version is filtered from default listings (CLI, catalog views); operations by explicit id still succeed."
+    }
+  },
+  "required": [
+    "id",
+    "name"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,48 @@
+{
+  "x-lix-key": "lix_version_ref",
+  "description": "Version head pointer. Records which commit a version should currently resolve to in the local runtime. Intentionally not part of canonical commit membership: refs may be reset client-side after sync without introducing content conflicts. Each `lix_version_descriptor.id` has exactly one `lix_version_ref` row.",
+  "x-lix-primary-key": [
+    "/id"
+  ],
+  "x-lix-foreign-keys": [
+    {
+      "properties": [
+        "/id"
+      ],
+      "references": {
+        "schemaKey": "lix_version_descriptor",
+        "properties": [
+          "/id"
+        ]
+      }
+    },
+    {
+      "properties": [
+        "/commit_id"
+      ],
+      "references": {
+        "schemaKey": "lix_commit",
+        "properties": [
+          "/id"
+        ]
+      }
+    }
+  ],
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "x-lix-default": "lix_uuid_v7()",
+      "description": "Version identifier whose head pointer is being stored; matches `lix_version_descriptor.id`."
+    },
+    "commit_id": {
+      "type": "string",
+      "description": "Commit the version should currently resolve to in the local runtime (references `lix_commit.id`)."
+    }
+  },
+  "required": [
+    "id",
+    "commit_id"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,222 @@
+use serde_json::Value as JsonValue;
+use std::sync::OnceLock;
+
+use crate::schema::lix_schema_definition;
+
+const LIX_REGISTERED_SCHEMA_KEY: &str = "lix_registered_schema";
+const LIX_KEY_VALUE_SCHEMA_KEY: &str = "lix_key_value";
+const LIX_ACCOUNT_SCHEMA_KEY: &str = "lix_account";
+const LIX_ACTIVE_ACCOUNT_SCHEMA_KEY: &str = "lix_active_account";
+const LIX_LABEL_SCHEMA_KEY: &str = "lix_label";
+const LIX_LABEL_ASSIGNMENT_SCHEMA_KEY: &str = "lix_label_assignment";
+const LIX_CHANGE_SCHEMA_KEY: &str = "lix_change";
+const LIX_CHANGE_AUTHOR_SCHEMA_KEY: &str = "lix_change_author";
+const LIX_COMMIT_SCHEMA_KEY: &str = "lix_commit";
+const LIX_VERSION_DESCRIPTOR_SCHEMA_KEY: &str = "lix_version_descriptor";
+const LIX_VERSION_REF_SCHEMA_KEY: &str = "lix_version_ref";
+const LIX_COMMIT_EDGE_SCHEMA_KEY: &str = "lix_commit_edge";
+const LIX_FILE_DESCRIPTOR_SCHEMA_KEY: &str = "lix_file_descriptor";
+const LIX_DIRECTORY_DESCRIPTOR_SCHEMA_KEY: &str = "lix_directory_descriptor";
+const LIX_BINARY_BLOB_REF_SCHEMA_KEY: &str = "lix_binary_blob_ref";
+
+const LIX_REGISTERED_SCHEMA_JSON: &str = include_str!("lix_registered_schema.json");
+const LIX_KEY_VALUE_SCHEMA_JSON: &str = include_str!("lix_key_value.json");
+const LIX_ACCOUNT_SCHEMA_JSON: &str = include_str!("lix_account.json");
+const LIX_ACTIVE_ACCOUNT_SCHEMA_JSON: &str = include_str!("lix_active_account.json");
+const LIX_LABEL_SCHEMA_JSON: &str = include_str!("lix_label.json");
+const LIX_LABEL_ASSIGNMENT_SCHEMA_JSON: &str = include_str!("lix_label_assignment.json");
+const LIX_CHANGE_SCHEMA_JSON: &str = include_str!("lix_change.json");
+const LIX_CHANGE_AUTHOR_SCHEMA_JSON: &str = include_str!("lix_change_author.json");
+const LIX_COMMIT_SCHEMA_JSON: &str = include_str!("lix_commit.json");
+const LIX_VERSION_DESCRIPTOR_SCHEMA_JSON: &str = include_str!("lix_version_descriptor.json");
+const LIX_VERSION_REF_SCHEMA_JSON: &str = include_str!("lix_version_ref.json");
+const LIX_COMMIT_EDGE_SCHEMA_JSON: &str = include_str!("lix_commit_edge.json");
+const LIX_FILE_DESCRIPTOR_SCHEMA_JSON: &str = include_str!("lix_file_descriptor.json");
+const LIX_DIRECTORY_DESCRIPTOR_SCHEMA_JSON: &str = include_str!("lix_directory_descriptor.json");
+const LIX_BINARY_BLOB_REF_SCHEMA_JSON: &str = include_str!("lix_binary_blob_ref.json");
+
+static LIX_REGISTERED_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+static LIX_KEY_VALUE_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+static LIX_ACCOUNT_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+static LIX_ACTIVE_ACCOUNT_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+static LIX_LABEL_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+static LIX_LABEL_ASSIGNMENT_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+static LIX_CHANGE_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+static LIX_CHANGE_AUTHOR_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+static LIX_COMMIT_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+static LIX_VERSION_DESCRIPTOR_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+static LIX_VERSION_REF_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+static LIX_COMMIT_EDGE_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+static LIX_FILE_DESCRIPTOR_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+static LIX_DIRECTORY_DESCRIPTOR_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+static LIX_BINARY_BLOB_REF_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+
+const BUILTIN_SCHEMA_KEYS: &[&str] = &[
+    LIX_REGISTERED_SCHEMA_KEY,
+    LIX_KEY_VALUE_SCHEMA_KEY,
+    LIX_ACCOUNT_SCHEMA_KEY,
+    LIX_ACTIVE_ACCOUNT_SCHEMA_KEY,
+    LIX_LABEL_SCHEMA_KEY,
+    LIX_LABEL_ASSIGNMENT_SCHEMA_KEY,
+    LIX_CHANGE_SCHEMA_KEY,
+    LIX_CHANGE_AUTHOR_SCHEMA_KEY,
+    LIX_COMMIT_SCHEMA_KEY,
+    LIX_VERSION_DESCRIPTOR_SCHEMA_KEY,
+    LIX_VERSION_REF_SCHEMA_KEY,
+    LIX_COMMIT_EDGE_SCHEMA_KEY,
+    LIX_FILE_DESCRIPTOR_SCHEMA_KEY,
+    LIX_DIRECTORY_DESCRIPTOR_SCHEMA_KEY,
+    LIX_BINARY_BLOB_REF_SCHEMA_KEY,
+];
+
+pub(super) fn is_seed_schema_key(schema_key: &str) -> bool {
+    BUILTIN_SCHEMA_KEYS.contains(&schema_key)
+}
+
+pub(super) fn seed_schema_definitions() -> Vec<&'static JsonValue> {
+    BUILTIN_SCHEMA_KEYS
+        .iter()
+        .map(|schema_key| {
+            seed_schema_definition(schema_key)
+                .unwrap_or_else(|| panic!("missing seed schema definition for '{schema_key}'"))
+        })
+        .collect()
+}
+
+pub(super) fn seed_schema_definition(schema_key: &str) -> Option<&'static JsonValue> {
+    match schema_key {
+        LIX_REGISTERED_SCHEMA_KEY => Some(
+            LIX_REGISTERED_SCHEMA.get_or_init(|| parse_registered_schema_with_inlined_definition()),
+        ),
+        LIX_KEY_VALUE_SCHEMA_KEY => {
+            Some(LIX_KEY_VALUE_SCHEMA.get_or_init(|| {
+                parse_builtin_schema("lix_key_value.json", LIX_KEY_VALUE_SCHEMA_JSON)
+            }))
+        }
+        LIX_ACCOUNT_SCHEMA_KEY => Some(
+            LIX_ACCOUNT_SCHEMA
+                .get_or_init(|| parse_builtin_schema("lix_account.json", LIX_ACCOUNT_SCHEMA_JSON)),
+        ),
+        LIX_ACTIVE_ACCOUNT_SCHEMA_KEY => Some(LIX_ACTIVE_ACCOUNT_SCHEMA.get_or_init(|| {
+            parse_builtin_schema("lix_active_account.json", LIX_ACTIVE_ACCOUNT_SCHEMA_JSON)
+        })),
+        LIX_LABEL_SCHEMA_KEY => Some(
+            LIX_LABEL_SCHEMA
+                .get_or_init(|| parse_builtin_schema("lix_label.json", LIX_LABEL_SCHEMA_JSON)),
+        ),
+        LIX_LABEL_ASSIGNMENT_SCHEMA_KEY => Some(LIX_LABEL_ASSIGNMENT_SCHEMA.get_or_init(|| {
+            parse_builtin_schema(
+                "lix_label_assignment.json",
+                LIX_LABEL_ASSIGNMENT_SCHEMA_JSON,
+            )
+        })),
+        LIX_CHANGE_SCHEMA_KEY => Some(
+            LIX_CHANGE_SCHEMA
+                .get_or_init(|| parse_builtin_schema("lix_change.json", LIX_CHANGE_SCHEMA_JSON)),
+        ),
+        LIX_CHANGE_AUTHOR_SCHEMA_KEY => Some(LIX_CHANGE_AUTHOR_SCHEMA.get_or_init(|| {
+            parse_builtin_schema("lix_change_author.json", LIX_CHANGE_AUTHOR_SCHEMA_JSON)
+        })),
+        LIX_COMMIT_SCHEMA_KEY => Some(
+            LIX_COMMIT_SCHEMA
+                .get_or_init(|| parse_builtin_schema("lix_commit.json", LIX_COMMIT_SCHEMA_JSON)),
+        ),
+        LIX_VERSION_DESCRIPTOR_SCHEMA_KEY => {
+            Some(LIX_VERSION_DESCRIPTOR_SCHEMA.get_or_init(|| {
+                parse_builtin_schema(
+                    "lix_version_descriptor.json",
+                    LIX_VERSION_DESCRIPTOR_SCHEMA_JSON,
+                )
+            }))
+        }
+        LIX_VERSION_REF_SCHEMA_KEY => Some(LIX_VERSION_REF_SCHEMA.get_or_init(|| {
+            parse_builtin_schema("lix_version_ref.json", LIX_VERSION_REF_SCHEMA_JSON)
+        })),
+        LIX_COMMIT_EDGE_SCHEMA_KEY => Some(LIX_COMMIT_EDGE_SCHEMA.get_or_init(|| {
+            parse_builtin_schema("lix_commit_edge.json", LIX_COMMIT_EDGE_SCHEMA_JSON)
+        })),
+        LIX_FILE_DESCRIPTOR_SCHEMA_KEY => Some(LIX_FILE_DESCRIPTOR_SCHEMA.get_or_init(|| {
+            parse_builtin_schema("lix_file_descriptor.json", LIX_FILE_DESCRIPTOR_SCHEMA_JSON)
+        })),
+        LIX_DIRECTORY_DESCRIPTOR_SCHEMA_KEY => {
+            Some(LIX_DIRECTORY_DESCRIPTOR_SCHEMA.get_or_init(|| {
+                parse_builtin_schema(
+                    "lix_directory_descriptor.json",
+                    LIX_DIRECTORY_DESCRIPTOR_SCHEMA_JSON,
+                )
+            }))
+        }
+        LIX_BINARY_BLOB_REF_SCHEMA_KEY => Some(LIX_BINARY_BLOB_REF_SCHEMA.get_or_init(|| {
+            parse_builtin_schema("lix_binary_blob_ref.json", LIX_BINARY_BLOB_REF_SCHEMA_JSON)
+        })),
+        _ => None,
+    }
+}
+
+#[allow(dead_code)]
+pub(crate) fn builtin_schema_json(schema_key: &str) -> Option<&'static str> {
+    match schema_key {
+        LIX_REGISTERED_SCHEMA_KEY => Some(LIX_REGISTERED_SCHEMA_JSON),
+        LIX_KEY_VALUE_SCHEMA_KEY => Some(LIX_KEY_VALUE_SCHEMA_JSON),
+        LIX_ACCOUNT_SCHEMA_KEY => Some(LIX_ACCOUNT_SCHEMA_JSON),
+        LIX_ACTIVE_ACCOUNT_SCHEMA_KEY => Some(LIX_ACTIVE_ACCOUNT_SCHEMA_JSON),
+        LIX_LABEL_SCHEMA_KEY => Some(LIX_LABEL_SCHEMA_JSON),
+        LIX_LABEL_ASSIGNMENT_SCHEMA_KEY => Some(LIX_LABEL_ASSIGNMENT_SCHEMA_JSON),
+        LIX_CHANGE_SCHEMA_KEY => Some(LIX_CHANGE_SCHEMA_JSON),
+        LIX_CHANGE_AUTHOR_SCHEMA_KEY => Some(LIX_CHANGE_AUTHOR_SCHEMA_JSON),
+        LIX_COMMIT_SCHEMA_KEY => Some(LIX_COMMIT_SCHEMA_JSON),
+        LIX_VERSION_DESCRIPTOR_SCHEMA_KEY => Some(LIX_VERSION_DESCRIPTOR_SCHEMA_JSON),
+        LIX_VERSION_REF_SCHEMA_KEY => Some(LIX_VERSION_REF_SCHEMA_JSON),
+        LIX_COMMIT_EDGE_SCHEMA_KEY => Some(LIX_COMMIT_EDGE_SCHEMA_JSON),
+        LIX_FILE_DESCRIPTOR_SCHEMA_KEY => Some(LIX_FILE_DESCRIPTOR_SCHEMA_JSON),
+        LIX_DIRECTORY_DESCRIPTOR_SCHEMA_KEY => Some(LIX_DIRECTORY_DESCRIPTOR_SCHEMA_JSON),
+        LIX_BINARY_BLOB_REF_SCHEMA_KEY => Some(LIX_BINARY_BLOB_REF_SCHEMA_JSON),
+        _ => None,
+    }
+}
+
+fn parse_builtin_schema(file_name: &str, raw_json: &str) -> JsonValue {
+    serde_json::from_str(raw_json).unwrap_or_else(|error| {
+        panic!("builtin schema file '{file_name}' must contain valid JSON: {error}")
+    })
+}
+
+fn parse_registered_schema_with_inlined_definition() -> JsonValue {
+    let mut schema = parse_builtin_schema("lix_registered_schema.json", LIX_REGISTERED_SCHEMA_JSON);
+    let value_schema = schema
+        .pointer_mut("/properties/value")
+        .expect("lix_registered_schema.json must define /properties/value");
+    let value_schema_object = value_schema
+        .as_object_mut()
+        .expect("lix_registered_schema.json /properties/value must be an object");
+
+    value_schema_object.insert(
+        "allOf".to_string(),
+        JsonValue::Array(vec![lix_schema_definition().clone()]),
+    );
+
+    schema
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{seed_schema_definition, BUILTIN_SCHEMA_KEYS};
+
+    #[test]
+    fn builtin_schemas_load_without_extra_override_metadata() {
+        for schema_key in BUILTIN_SCHEMA_KEYS {
+            seed_schema_definition(schema_key).expect("schema should exist");
+        }
+    }
+
+    #[test]
+    fn registered_schema_value_inlines_lix_schema_definition() {
+        let schema = seed_schema_definition("lix_registered_schema").expect("schema should exist");
+        let all_of = schema
+            .pointer("/properties/value/allOf")
+            .and_then(|value| value.as_array())
+            .expect("registered schema value must define allOf array");
+        assert_eq!(all_of.len(), 1);
+        assert_eq!(all_of[0], *crate::schema::lix_schema_definition());
+    }
+}