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

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

@@ -0,0 +1,34 @@
+{
+  "x-lix-key": "lix_branch_descriptor",
+  "description": "User-facing branch metadata (name and visibility). The stable identity of a branch; the matching `lix_branch_ref` carries the moving head pointer. The catalog's `lix_branch` surface joins this descriptor with its ref to present a single user-visible branch row.",
+  "x-lix-primary-key": [
+    "/id"
+  ],
+  "x-lix-unique": [
+    [
+      "/name"
+    ]
+  ],
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "x-lix-default": "lix_uuid_v7()",
+      "description": "Stable branch identifier (UUIDv7). Referenced by `lix_branch_ref.id`."
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable branch name (e.g. `main`, `feature-x`) shown in branch listings and CLI output."
+    },
+    "hidden": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, the branch 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_branch_ref.json

@@ -0,0 +1,48 @@
+{
+  "x-lix-key": "lix_branch_ref",
+  "description": "Branch head pointer. Records which commit a branch 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_branch_descriptor.id` has exactly one `lix_branch_ref` row.",
+  "x-lix-primary-key": [
+    "/id"
+  ],
+  "x-lix-foreign-keys": [
+    {
+      "properties": [
+        "/id"
+      ],
+      "references": {
+        "schemaKey": "lix_branch_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": "Branch identifier whose head pointer is being stored; matches `lix_branch_descriptor.id`."
+    },
+    "commit_id": {
+      "type": "string",
+      "description": "Commit the branch 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/lix_change.json

@@ -11,7 +11,7 @@
       "x-lix-default": "lix_uuid_v7()",
       "description": "Stable identifier for this change."
     },
-    "entity_id": {
+    "entity_pk": {
       "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": {
@@ -28,7 +28,7 @@
         "string",
         "null"
       ],
-      "description": "Filesystem-scoped file identifier when the change belongs to a file; NULL for engine-internal entities (commits, versions, settings)."
+      "description": "Filesystem-scoped file identifier when the change belongs to a file; NULL for engine-internal entities (commits, branches, settings)."
     },
     "metadata": {
       "type": [
@@ -54,7 +54,7 @@
   },
   "required": [
     "id",
-    "entity_id",
+    "entity_pk",
     "schema_key",
     "file_id",
     "created_at"

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

@@ -1,6 +1,6 @@
 {
   "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.",
+  "description": "A commit is a stable point in project history. Branches point to commits. Use lix_commit_edge to inspect parent commits.",
   "examples": [
     {
       "id": "commit_01jexample"

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

@@ -1,12 +1,12 @@
 {
   "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.",
+  "description": "Mapping table that assigns a label to any live Lix row addressed by (target_entity_pk, target_schema_key, target_file_id). The state foreign-key tuple is ordered as [0] target_entity_pk, [1] target_schema_key, [2] target_file_id.",
   "x-lix-primary-key": [
     "/id"
   ],
   "x-lix-unique": [
     [
-      "/target_entity_id",
+      "/target_entity_pk",
       "/target_schema_key",
       "/target_file_id",
       "/label_id"
@@ -14,7 +14,7 @@
   ],
   "x-lix-state-foreign-keys": [
     [
-      "/target_entity_id",
+      "/target_entity_pk",
       "/target_schema_key",
       "/target_file_id"
     ]
@@ -39,9 +39,9 @@
       "x-lix-default": "lix_uuid_v7()",
       "description": "Stable identifier for this label assignment row."
     },
-    "target_entity_id": {
+    "target_entity_pk": {
       "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.",
+      "description": "Target row entity_pk. 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"
       },
@@ -65,7 +65,7 @@
   },
   "required": [
     "id",
-    "target_entity_id",
+    "target_entity_pk",
     "target_schema_key",
     "target_file_id",
     "label_id"

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

@@ -12,8 +12,8 @@ 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_BRANCH_DESCRIPTOR_SCHEMA_KEY: &str = "lix_branch_descriptor";
+const LIX_BRANCH_REF_SCHEMA_KEY: &str = "lix_branch_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";
@@ -28,8 +28,8 @@ const LIX_LABEL_ASSIGNMENT_SCHEMA_JSON: &str = include_str!("lix_label_assignmen
 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_BRANCH_DESCRIPTOR_SCHEMA_JSON: &str = include_str!("lix_branch_descriptor.json");
+const LIX_BRANCH_REF_SCHEMA_JSON: &str = include_str!("lix_branch_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");
@@ -44,8 +44,8 @@ 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_BRANCH_DESCRIPTOR_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
+static LIX_BRANCH_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();
@@ -61,8 +61,8 @@ const BUILTIN_SCHEMA_KEYS: &[&str] = &[
     LIX_CHANGE_SCHEMA_KEY,
     LIX_CHANGE_AUTHOR_SCHEMA_KEY,
     LIX_COMMIT_SCHEMA_KEY,
-    LIX_VERSION_DESCRIPTOR_SCHEMA_KEY,
-    LIX_VERSION_REF_SCHEMA_KEY,
+    LIX_BRANCH_DESCRIPTOR_SCHEMA_KEY,
+    LIX_BRANCH_REF_SCHEMA_KEY,
     LIX_COMMIT_EDGE_SCHEMA_KEY,
     LIX_FILE_DESCRIPTOR_SCHEMA_KEY,
     LIX_DIRECTORY_DESCRIPTOR_SCHEMA_KEY,
@@ -121,16 +121,14 @@ pub(super) fn seed_schema_definition(schema_key: &str) -> Option<&'static JsonVa
             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_BRANCH_DESCRIPTOR_SCHEMA_KEY => Some(LIX_BRANCH_DESCRIPTOR_SCHEMA.get_or_init(|| {
+            parse_builtin_schema(
+                "lix_branch_descriptor.json",
+                LIX_BRANCH_DESCRIPTOR_SCHEMA_JSON,
+            )
+        })),
+        LIX_BRANCH_REF_SCHEMA_KEY => Some(LIX_BRANCH_REF_SCHEMA.get_or_init(|| {
+            parse_builtin_schema("lix_branch_ref.json", LIX_BRANCH_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)
@@ -165,8 +163,8 @@ pub(crate) fn builtin_schema_json(schema_key: &str) -> Option<&'static str> {
         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_BRANCH_DESCRIPTOR_SCHEMA_KEY => Some(LIX_BRANCH_DESCRIPTOR_SCHEMA_JSON),
+        LIX_BRANCH_REF_SCHEMA_KEY => Some(LIX_BRANCH_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),

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

@@ -3,7 +3,7 @@ use std::collections::{BTreeMap, BTreeSet};
 use serde_json::Value as JsonValue;
 
 use crate::common::top_level_property_name;
-use crate::entity_identity::canonical_json_text;
+use crate::entity_pk::canonical_json_text;
 use crate::LixError;
 
 const DOC_ONLY_SCHEMA_FIELDS: &[&str] = &["$comment", "deprecated", "description", "title"];
@@ -23,7 +23,7 @@ const CONSTRAINT_FIELDS: &[&str] = &[
 /// 0.6; recursive schema evolution is a later, explicit feature.
 ///
 /// Primary-key column order is semantic because it defines composite
-/// `entity_id` tuple order, so primary keys are never normalized. Relational
+/// `entity_pk` tuple order, so primary keys are never normalized. Relational
 /// constraints are frozen even when a particular addition could be
 /// retroactively safe, such as a new FK on a new optional property. That is a
 /// deliberate MVP rule we may relax later.
@@ -129,7 +129,7 @@ fn validate_constraints_unchanged(
     schema_key: &str,
 ) -> Result<(), LixError> {
     // Primary-key column order is semantic because it defines composite
-    // entity_id tuple order, so it is compared directly and never normalized.
+    // entity_pk tuple order, so it is compared directly and never normalized.
     if previous.get("x-lix-primary-key") != next.get("x-lix-primary-key") {
         return schema_amendment_error(format!(
             "schema '{schema_key}' cannot amend constraint field 'x-lix-primary-key'"
@@ -344,14 +344,14 @@ mod tests {
                 }
             ],
             "x-lix-state-foreign-keys": [
-                ["/target_entity_id", "/target_schema_key", "/target_file_id"]
+                ["/target_entity_pk", "/target_schema_key", "/target_file_id"]
             ],
             "properties": {
                 "id": { "type": "string", "description": "Stable id" },
                 "isbn": { "type": "string" },
                 "title": { "type": "string", "title": "Title" },
                 "author_id": { "type": "string" },
-                "target_entity_id": {
+                "target_entity_pk": {
                     "type": "array",
                     "items": { "type": "string" }
                 },
@@ -363,7 +363,7 @@ mod tests {
                 "isbn",
                 "title",
                 "author_id",
-                "target_entity_id",
+                "target_entity_pk",
                 "target_schema_key",
                 "target_file_id"
             ],
@@ -442,8 +442,8 @@ mod tests {
             }
         ]);
         previous["x-lix-state-foreign-keys"] = json!([
-            ["/target_entity_id", "/target_schema_key", "/target_file_id"],
-            ["/other_entity_id", "/other_schema_key", "/other_file_id"]
+            ["/target_entity_pk", "/target_schema_key", "/target_file_id"],
+            ["/other_entity_pk", "/other_schema_key", "/other_file_id"]
         ]);
         let mut next = previous.clone();
         next["x-lix-unique"] = json!([["/title"], ["/isbn"]]);
@@ -464,8 +464,8 @@ mod tests {
             }
         ]);
         next["x-lix-state-foreign-keys"] = json!([
-            ["/other_entity_id", "/other_schema_key", "/other_file_id"],
-            ["/target_entity_id", "/target_schema_key", "/target_file_id"]
+            ["/other_entity_pk", "/other_schema_key", "/other_file_id"],
+            ["/target_entity_pk", "/target_schema_key", "/target_file_id"]
         ]);
 
         validate_schema_amendment(&previous, &next)
@@ -480,7 +480,7 @@ mod tests {
             "id",
             "isbn",
             "author_id",
-            "target_entity_id",
+            "target_entity_pk",
             "target_schema_key",
             "target_file_id"
         ]);

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

@@ -116,7 +116,7 @@
         },
         "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.",
+          "description": "Foreign keys from local fields to arbitrary live state rows. Each entry is exactly three required local JSON Pointers ordered as `[entity_pk, schema_key, file_id]`: index 0 points to the local entity_pk 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 branch.",
           "items": {
             "type": "array",
             "minItems": 3,
@@ -126,7 +126,7 @@
               {
                 "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."
+                "description": "[0] Local JSON Pointer for the target entity_pk. The value must be a non-empty JSON array of strings."
               },
               {
                 "type": "string",

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

@@ -240,7 +240,7 @@ fn detect_state_foreign_key_tuple_shape(schema: &JsonValue) -> Option<LixError>
             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."
+                    "Invalid Lix schema definition: x-lix-state-foreign-keys[{index}] must contain exactly three JSON Pointers ordered as [entity_pk, schema_key, file_id]; [0] entity_pk, [1] schema_key, [2] file_id."
                 ),
             ));
         }
@@ -406,7 +406,7 @@ fn assert_state_foreign_key_pointers(schema: &JsonValue) -> Result<(), LixError>
         }
 
         let roles = [
-            ("entity_id", "a non-empty JSON array of strings"),
+            ("entity_pk", "a non-empty JSON array of strings"),
             ("schema_key", "a string"),
             ("file_id", "a string or null"),
         ];
@@ -430,13 +430,13 @@ fn assert_state_foreign_key_pointers(schema: &JsonValue) -> Result<(), LixError>
                 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]."
+                        "Invalid Lix schema definition: x-lix-state-foreign-keys[{index}][{slot}] ({role}) property \"{pointer}\" must be required. Tuple order is [entity_pk, schema_key, file_id]."
                     ),
                 ));
             }
 
             let valid = match *role {
-                "entity_id" => schema_property_is_string_array(property_schema),
+                "entity_pk" => 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"),
@@ -445,7 +445,7 @@ fn assert_state_foreign_key_pointers(schema: &JsonValue) -> Result<(), LixError>
                 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]."
+                        "Invalid Lix schema definition: x-lix-state-foreign-keys[{index}][{slot}] ({role}) property \"{pointer}\" must be {expected}. Tuple order is [entity_pk, schema_key, file_id]."
                     ),
                 ));
             }

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

@@ -1,6 +1,6 @@
 use serde_json::Value as JsonValue;
 
-use crate::entity_identity::EntityIdentity;
+use crate::entity_pk::EntityPk;
 use crate::LixError;
 
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
@@ -68,8 +68,8 @@ pub fn schema_from_registered_snapshot(
     ))
 }
 
-pub(crate) fn registered_schema_entity_id(schema_key: &str) -> Result<EntityIdentity, LixError> {
-    EntityIdentity::from_primary_key_paths(
+pub(crate) fn registered_schema_entity_pk(schema_key: &str) -> Result<EntityPk, LixError> {
+    EntityPk::from_primary_key_paths(
         &serde_json::json!({
             "value": {
                 "x-lix-key": schema_key,

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

@@ -13,7 +13,7 @@ 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;
+pub(crate) use key::registered_schema_entity_pk;
 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

@@ -41,7 +41,7 @@ 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"] {
+    for property_name in ["lixcol_entity_pk", "lix_internal", "lixfoo"] {
         let schema = json!({
             "x-lix-key": "test_entity",
             "type": "object",
@@ -196,7 +196,7 @@ fn validate_lix_schema_definition_rejects_missing_primary_key_properties() {
             "value": { "type": "string" }
         },
         "required": ["value"],
-        "x-lix-primary-key": ["/entity_id"],
+        "x-lix-primary-key": ["/entity_pk"],
         "additionalProperties": false
     });
 
@@ -255,7 +255,7 @@ fn validate_lix_schema_definition_rejects_missing_unique_constraint_properties()
         "properties": {
             "value": { "type": "string" }
         },
-        "x-lix-unique": [["/entity_id", "/value"]],
+        "x-lix-unique": [["/entity_pk", "/value"]],
         "additionalProperties": false
     });
 
@@ -420,7 +420,7 @@ fn x_lix_entity_views_is_rejected() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "mock",
-        "x-lix-entity-views": ["lix_state", "lix_state_by_version"],
+        "x-lix-entity-views": ["lix_state", "lix_state_by_branch"],
         "properties": {
             "name": { "type": "string" }
         },
@@ -453,13 +453,13 @@ fn x_lix_primary_key_must_be_array_of_strings_when_present() {
     let schema = json!({
         "type": "object",
         "x-lix-key": "mock",
-        "x-lix-primary-key": ["/id", "/version"],
+        "x-lix-primary-key": ["/id", "/branch"],
         "properties": {
             "id": { "type": "string" },
-            "version": { "type": "string" },
+            "branch": { "type": "string" },
             "name": { "type": "string" }
         },
-        "required": ["id", "version", "name"],
+        "required": ["id", "branch", "name"],
         "additionalProperties": false
     });
 
@@ -525,7 +525,7 @@ fn x_lix_foreign_keys_reject_duplicate_pointers() {
                 "properties": ["/local", "/local"],
                 "references": {
                     "schemaKey": "remote_schema",
-                    "properties": ["/id", "/version"]
+                    "properties": ["/id", "/branch"]
                 }
             }
         ],
@@ -641,7 +641,7 @@ fn x_lix_state_foreign_keys_with_ordered_state_address_tuple() {
         "type": "object",
         "x-lix-key": "label_assignment",
         "x-lix-state-foreign-keys": [
-            ["/target_entity_id", "/target_schema_key", "/target_file_id"]
+            ["/target_entity_pk", "/target_schema_key", "/target_file_id"]
         ],
         "x-lix-foreign-keys": [
             {
@@ -653,7 +653,7 @@ fn x_lix_state_foreign_keys_with_ordered_state_address_tuple() {
             }
         ],
         "properties": {
-            "target_entity_id": {
+            "target_entity_pk": {
                 "type": "array",
                 "items": { "type": "string" },
                 "minItems": 1
@@ -662,7 +662,7 @@ fn x_lix_state_foreign_keys_with_ordered_state_address_tuple() {
             "target_file_id": { "type": ["string", "null"] },
             "label_id": { "type": "string" }
         },
-        "required": ["target_entity_id", "target_schema_key", "target_file_id", "label_id"],
+        "required": ["target_entity_pk", "target_schema_key", "target_file_id", "label_id"],
         "additionalProperties": false
     });
 
@@ -675,10 +675,10 @@ fn x_lix_state_foreign_keys_rejects_wrong_tuple_order_by_type() {
         "type": "object",
         "x-lix-key": "bad_label_assignment",
         "x-lix-state-foreign-keys": [
-            ["/target_schema_key", "/target_entity_id", "/target_file_id"]
+            ["/target_schema_key", "/target_entity_pk", "/target_file_id"]
         ],
         "properties": {
-            "target_entity_id": {
+            "target_entity_pk": {
                 "type": "array",
                 "items": { "type": "string" },
                 "minItems": 1
@@ -686,14 +686,14 @@ fn x_lix_state_foreign_keys_rejects_wrong_tuple_order_by_type() {
             "target_schema_key": { "type": "string" },
             "target_file_id": { "type": ["string", "null"] }
         },
-        "required": ["target_entity_id", "target_schema_key", "target_file_id"],
+        "required": ["target_entity_pk", "target_schema_key", "target_file_id"],
         "additionalProperties": false
     });
 
     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]"),
+        err.message.contains("[entity_pk, schema_key, file_id]"),
         "unexpected error: {err:?}"
     );
 }
@@ -704,10 +704,10 @@ fn x_lix_state_foreign_keys_requires_address_tuple_properties() {
         "type": "object",
         "x-lix-key": "optional_label_assignment",
         "x-lix-state-foreign-keys": [
-            ["/target_entity_id", "/target_schema_key", "/target_file_id"]
+            ["/target_entity_pk", "/target_schema_key", "/target_file_id"]
         ],
         "properties": {
-            "target_entity_id": {
+            "target_entity_pk": {
                 "type": "array",
                 "items": { "type": "string" },
                 "minItems": 1
@@ -715,7 +715,7 @@ fn x_lix_state_foreign_keys_requires_address_tuple_properties() {
             "target_schema_key": { "type": "string" },
             "target_file_id": { "type": ["string", "null"] }
         },
-        "required": ["target_entity_id", "target_schema_key"],
+        "required": ["target_entity_pk", "target_schema_key"],
         "additionalProperties": false
     });