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

package/dist-engine-src/src/transaction/validation.rs

@@ -2,6 +2,7 @@ use std::collections::{BTreeMap, BTreeSet};
 
 use serde_json::Value as JsonValue;
 
+use crate::branch::{BRANCH_DESCRIPTOR_SCHEMA_KEY, BRANCH_REF_SCHEMA_KEY};
 use crate::catalog::{
     CatalogSnapshot, ForeignKeyPlan, SchemaCatalogKey, SchemaPlan, StateDeleteReferencePlan,
     StateForeignKeyPlan,
@@ -11,7 +12,7 @@ use crate::common::format_json_pointer;
 use crate::common::parse_json_pointer;
 use crate::common::{json_pointer_get, validate_row_metadata};
 use crate::domain::{Domain, DomainFileScope, DomainRowIdentity};
-use crate::entity_identity::{canonical_json_text, EntityIdentity, EntityIdentityError};
+use crate::entity_pk::{canonical_json_text, EntityPk, EntityPkError};
 #[cfg(test)]
 use crate::live_state::LiveStateRowIdentity;
 use crate::live_state::{
@@ -31,7 +32,6 @@ use crate::transaction::staging::{PreparedValidationRow, PreparedWriteValidation
 #[cfg(test)]
 use crate::transaction::types::PreparedStateRow;
 use crate::transaction::types::TransactionWriteOrigin;
-use crate::version::{VERSION_DESCRIPTOR_SCHEMA_KEY, VERSION_REF_SCHEMA_KEY};
 use crate::LixError;
 
 const REGISTERED_SCHEMA_KEY: &str = "lix_registered_schema";
@@ -83,15 +83,15 @@ async fn scan_committed_constraint_rows(
     live_state: &dyn LiveStateReader,
     domain: &Domain,
     schema_keys: Vec<String>,
-    entity_ids: Vec<EntityIdentity>,
+    entity_pks: Vec<EntityPk>,
     include_tombstones: bool,
 ) -> Result<Vec<MaterializedLiveStateRow>, LixError> {
     let rows = live_state
         .scan_rows(&LiveStateScanRequest {
             filter: LiveStateFilter {
                 schema_keys: schema_keys.clone(),
-                entity_ids: entity_ids.clone(),
-                version_ids: vec![domain.version_id().to_string()],
+                entity_pks: entity_pks.clone(),
+                branch_ids: vec![domain.branch_id().to_string()],
                 file_ids: domain.file_filters(),
                 untracked: Some(domain.untracked()),
                 include_tombstones,
@@ -105,7 +105,7 @@ async fn scan_committed_constraint_rows(
         .filter(|row| {
             domain.contains(row)
                 && (schema_keys.is_empty() || schema_keys.contains(&row.schema_key))
-                && (entity_ids.is_empty() || entity_ids.contains(&row.entity_id))
+                && (entity_pks.is_empty() || entity_pks.contains(&row.entity_pk))
         })
         .collect())
 }
@@ -114,14 +114,14 @@ async fn load_committed_constraint_row(
     live_state: &dyn LiveStateReader,
     domain: &Domain,
     schema_key: &str,
-    entity_id: EntityIdentity,
+    entity_pk: EntityPk,
     include_tombstones: bool,
 ) -> Result<Option<MaterializedLiveStateRow>, LixError> {
     Ok(scan_committed_constraint_rows(
         live_state,
         domain,
         vec![schema_key.to_string()],
-        vec![entity_id],
+        vec![entity_pk],
         include_tombstones,
     )
     .await?
@@ -188,7 +188,7 @@ pub(crate) async fn validate_prepared_writes(
     validate_committed_delete_restrictions(&input, input.schema_catalog, &pending_constraints)
         .await?;
     validate_file_descriptor_delete_restrictions(&input, &pending_constraints).await?;
-    validate_version_ref_delete_restrictions(&input, &pending_constraints).await?;
+    validate_branch_ref_delete_restrictions(&input, &pending_constraints).await?;
     validate_committed_insert_identities(&input, &pending_constraints).await?;
     validate_committed_unique_constraints(&input, &pending_constraints).await?;
     validate_directory_descriptor_parent_graph(&input, &staged_rows, &constraint_rows).await?;
@@ -245,7 +245,7 @@ async fn validate_registered_schema_identity_is_canonical(
             input.live_state,
             &pending_row.domain().with_exact_file_scope(None),
             REGISTERED_SCHEMA_KEY,
-            pending_row.entity_id().clone(),
+            pending_row.entity_pk().clone(),
             false,
         )
         .await?
@@ -347,7 +347,7 @@ fn apply_staged_directory_parent_rows(
         {
             continue;
         }
-        let id = row.entity_id().as_single_string_owned()?;
+        let id = row.entity_pk().as_single_string_owned()?;
         let Some(snapshot) = row.snapshot_json() else {
             parents.remove(&id);
             continue;
@@ -432,27 +432,27 @@ fn optional_snapshot_string(
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 struct FilesystemNamespaceIdentity {
     schema_key: String,
-    entity_id: EntityIdentity,
+    entity_pk: EntityPk,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 enum FilesystemNamespaceOccupant {
     Directory {
-        entity_id: EntityIdentity,
+        entity_pk: EntityPk,
         parent_id: Option<String>,
         name: String,
     },
     File {
-        entity_id: EntityIdentity,
+        entity_pk: EntityPk,
         directory_id: Option<String>,
         entry_name: String,
     },
 }
 
 impl FilesystemNamespaceOccupant {
-    fn entity_id(&self) -> &EntityIdentity {
+    fn entity_pk(&self) -> &EntityPk {
         match self {
-            Self::Directory { entity_id, .. } | Self::File { entity_id, .. } => entity_id,
+            Self::Directory { entity_pk, .. } | Self::File { entity_pk, .. } => entity_pk,
         }
     }
 
@@ -483,8 +483,8 @@ async fn validate_filesystem_namespace(
     staged_rows: &[PreparedValidationRow<'_>],
 ) -> Result<(), LixError> {
     // Filesystem namespace constraints are storage-scope local. Global rows are
-    // validated in the global scope and may be projected into version reads, but
-    // projected globals do not participate in version-local constraint checks.
+    // validated in the global scope and may be projected into branch reads, but
+    // projected globals do not participate in branch-local constraint checks.
     let domains = staged_filesystem_namespace_domains(staged_rows);
     for domain in domains {
         let mut occupants =
@@ -555,7 +555,7 @@ fn apply_staged_filesystem_namespace_rows(
         }
         let identity = FilesystemNamespaceIdentity {
             schema_key: row.schema_key().to_string(),
-            entity_id: row.entity_id().clone(),
+            entity_pk: row.entity_pk().clone(),
         };
         let Some(snapshot) = row.snapshot_json() else {
             occupants.remove(&identity);
@@ -577,13 +577,13 @@ fn filesystem_namespace_occupant_from_live_row(
     };
     let identity = FilesystemNamespaceIdentity {
         schema_key: row.schema_key.clone(),
-        entity_id: row.entity_id.clone(),
+        entity_pk: row.entity_pk.clone(),
     };
     let occupant = match row.schema_key.as_str() {
         DIRECTORY_DESCRIPTOR_SCHEMA_KEY => {
-            directory_namespace_occupant(&row.entity_id, snapshot_content)?
+            directory_namespace_occupant(&row.entity_pk, snapshot_content)?
         }
-        FILE_DESCRIPTOR_SCHEMA_KEY => file_namespace_occupant(&row.entity_id, snapshot_content)?,
+        FILE_DESCRIPTOR_SCHEMA_KEY => file_namespace_occupant(&row.entity_pk, snapshot_content)?,
         _ => return Ok(None),
     };
     Ok(Some((identity, occupant)))
@@ -595,9 +595,9 @@ fn filesystem_namespace_occupant_from_staged_row(
 ) -> Result<FilesystemNamespaceOccupant, LixError> {
     match row.schema_key() {
         DIRECTORY_DESCRIPTOR_SCHEMA_KEY => {
-            directory_namespace_occupant_from_value(row.entity_id(), snapshot)
+            directory_namespace_occupant_from_value(row.entity_pk(), snapshot)
         }
-        FILE_DESCRIPTOR_SCHEMA_KEY => file_namespace_occupant_from_value(row.entity_id(), snapshot),
+        FILE_DESCRIPTOR_SCHEMA_KEY => file_namespace_occupant_from_value(row.entity_pk(), snapshot),
         _ => Err(LixError::new(
             LixError::CODE_SCHEMA_VALIDATION,
             format!(
@@ -609,31 +609,31 @@ fn filesystem_namespace_occupant_from_staged_row(
 }
 
 fn directory_namespace_occupant(
-    entity_id: &EntityIdentity,
+    entity_pk: &EntityPk,
     snapshot_content: &str,
 ) -> Result<FilesystemNamespaceOccupant, LixError> {
     let snapshot = parse_directory_descriptor_snapshot(snapshot_content)?;
     Ok(FilesystemNamespaceOccupant::Directory {
-        entity_id: entity_id.clone(),
+        entity_pk: entity_pk.clone(),
         parent_id: snapshot.parent_id,
         name: snapshot.name,
     })
 }
 
 fn directory_namespace_occupant_from_value(
-    entity_id: &EntityIdentity,
+    entity_pk: &EntityPk,
     snapshot: &JsonValue,
 ) -> Result<FilesystemNamespaceOccupant, LixError> {
     let snapshot = directory_descriptor_snapshot_from_value(snapshot)?;
     Ok(FilesystemNamespaceOccupant::Directory {
-        entity_id: entity_id.clone(),
+        entity_pk: entity_pk.clone(),
         parent_id: snapshot.parent_id,
         name: snapshot.name,
     })
 }
 
 fn file_namespace_occupant(
-    entity_id: &EntityIdentity,
+    entity_pk: &EntityPk,
     snapshot_content: &str,
 ) -> Result<FilesystemNamespaceOccupant, LixError> {
     let snapshot =
@@ -644,19 +644,19 @@ fn file_namespace_occupant(
             )
         })?;
     Ok(FilesystemNamespaceOccupant::File {
-        entity_id: entity_id.clone(),
+        entity_pk: entity_pk.clone(),
         directory_id: snapshot.directory_id,
         entry_name: snapshot.name,
     })
 }
 
 fn file_namespace_occupant_from_value(
-    entity_id: &EntityIdentity,
+    entity_pk: &EntityPk,
     snapshot: &JsonValue,
 ) -> Result<FilesystemNamespaceOccupant, LixError> {
     let snapshot = file_descriptor_snapshot_from_value(snapshot)?;
     Ok(FilesystemNamespaceOccupant::File {
-        entity_id: entity_id.clone(),
+        entity_pk: entity_pk.clone(),
         directory_id: snapshot.directory_id,
         entry_name: snapshot.name,
     })
@@ -693,18 +693,18 @@ fn filesystem_namespace_conflict_error(
 ) -> LixError {
     let parent = parent_id.as_deref().unwrap_or("<root>");
     let existing_id = existing
-        .entity_id()
+        .entity_pk()
         .as_single_string_owned()
-        .unwrap_or_else(|_| "<non-string-entity-id>".to_string());
+        .unwrap_or_else(|_| "<non-string-entity-pk>".to_string());
     let conflicting_id = conflicting
-        .entity_id()
+        .entity_pk()
         .as_single_string_owned()
-        .unwrap_or_else(|_| "<non-string-entity-id>".to_string());
+        .unwrap_or_else(|_| "<non-string-entity-pk>".to_string());
     LixError::new(
         LixError::CODE_UNIQUE,
         format!(
-            "filesystem namespace conflict in version '{}' for parent {parent:?} entry {entry_name:?}: {} '{}' conflicts with {} '{}'",
-            domain.version_id(),
+            "filesystem namespace conflict in branch '{}' for parent {parent:?} entry {entry_name:?}: {} '{}' conflicts with {} '{}'",
+            domain.branch_id(),
             existing.kind(),
             existing_id,
             conflicting.kind(),
@@ -756,8 +756,8 @@ fn directory_parent_cycle_error(
     LixError::new(
         LixError::CODE_CONSTRAINT_VIOLATION,
         format!(
-            "lix_directory_descriptor parent_id cycle in version '{}': directory '{}' reaches ancestor '{}' twice",
-            scope.domain.version_id(), start_id, repeated_id
+            "lix_directory_descriptor parent_id cycle in branch '{}': directory '{}' reaches ancestor '{}' twice",
+            scope.domain.branch_id(), start_id, repeated_id
         ),
     )
     .with_hint("Set parent_id to null or to an existing directory outside the directory's descendants.")
@@ -771,8 +771,8 @@ fn directory_parent_missing_error(
     LixError::new(
         LixError::CODE_FOREIGN_KEY,
         format!(
-            "lix_directory_descriptor parent_id chain in version '{}' for directory '{}' references missing directory '{}'",
-            scope.domain.version_id(), start_id, missing_id
+            "lix_directory_descriptor parent_id chain in branch '{}' for directory '{}' references missing directory '{}'",
+            scope.domain.branch_id(), start_id, missing_id
         ),
     )
 }
@@ -781,8 +781,8 @@ fn directory_parent_depth_error(scope: &DirectoryDescriptorScope, start_id: &str
     LixError::new(
         LixError::CODE_CONSTRAINT_VIOLATION,
         format!(
-            "lix_directory_descriptor parent_id chain in version '{}' for directory '{}' exceeds maximum depth {}",
-            scope.domain.version_id(), start_id, MAX_DIRECTORY_PARENT_DEPTH
+            "lix_directory_descriptor parent_id chain in branch '{}' for directory '{}' exceeds maximum depth {}",
+            scope.domain.branch_id(), start_id, MAX_DIRECTORY_PARENT_DEPTH
         ),
     )
 }
@@ -797,12 +797,12 @@ async fn validate_committed_insert_identities(
         .map(|target| target.identity.clone())
         .collect::<BTreeSet<_>>();
     let mut checks_by_domain_schema =
-        BTreeMap::<(Domain, String), Vec<(EntityIdentity, Option<TransactionWriteOrigin>)>>::new();
+        BTreeMap::<(Domain, String), Vec<(EntityPk, Option<TransactionWriteOrigin>)>>::new();
     for (identity, origin) in input.staged_writes.insert_identities() {
         let pending_identity = DomainRowIdentity::in_domain(
             identity.domain(),
             identity.schema_key().to_string(),
-            identity.entity_id().clone(),
+            identity.entity_pk().clone(),
         );
         if !pending_identity_targets.contains(&pending_identity) {
             continue;
@@ -813,66 +813,66 @@ async fn validate_committed_insert_identities(
                 pending_identity.schema_key_owned(),
             ))
             .or_default()
-            .push((pending_identity.entity_id_owned(), origin.cloned()));
+            .push((pending_identity.entity_pk_owned(), origin.cloned()));
     }
 
     for ((domain, schema_key), checks) in checks_by_domain_schema {
-        let entity_ids = checks
+        let entity_pks = checks
             .iter()
-            .map(|(entity_id, _)| entity_id.clone())
+            .map(|(entity_pk, _)| entity_pk.clone())
             .collect::<Vec<_>>();
         let committed_rows = scan_committed_constraint_rows(
             input.live_state,
             &domain,
             vec![schema_key.clone()],
-            entity_ids,
+            entity_pks,
             false,
         )
         .await?;
-        let committed_rows_by_entity_id = committed_rows
+        let committed_rows_by_entity_pk = committed_rows
             .into_iter()
             .filter(|row| {
                 row.snapshot_content.is_some() && !pending_constraints.tombstones_identity(row)
             })
-            .map(|row| (row.entity_id.clone(), row))
+            .map(|row| (row.entity_pk.clone(), row))
             .collect::<BTreeMap<_, _>>();
-        for (entity_id, origin) in checks {
-            if !committed_rows_by_entity_id.contains_key(&entity_id) {
+        for (entity_pk, origin) in checks {
+            if !committed_rows_by_entity_pk.contains_key(&entity_pk) {
                 continue;
             }
             return Err(LixError::new(
                 LixError::CODE_UNIQUE,
-                duplicate_insert_identity_message(&schema_key, &entity_id, None, origin.as_ref()),
+                duplicate_insert_identity_message(&schema_key, &entity_pk, None, origin.as_ref()),
             ));
         }
     }
     Ok(())
 }
 
-async fn validate_version_ref_delete_restrictions(
+async fn validate_branch_ref_delete_restrictions(
     input: &TransactionValidationInput<'_>,
     pending_constraints: &PendingConstraintIndexes,
 ) -> Result<(), LixError> {
     for tombstone in &pending_constraints.tombstones {
-        if tombstone.identity.schema_key() != VERSION_REF_SCHEMA_KEY {
+        if tombstone.identity.schema_key() != BRANCH_REF_SCHEMA_KEY {
             continue;
         }
 
         for source_domain in tombstone
             .identity
             .domain()
-            .version_descriptor_domains_for_ref_delete()
+            .branch_descriptor_domains_for_ref_delete()
         {
             let descriptor_identity = DomainRowIdentity::in_domain(
                 source_domain,
-                VERSION_DESCRIPTOR_SCHEMA_KEY,
-                tombstone.identity.entity_id_owned(),
+                BRANCH_DESCRIPTOR_SCHEMA_KEY,
+                tombstone.identity.entity_pk_owned(),
             );
             if pending_constraints.tombstones_target_identity(&descriptor_identity) {
                 continue;
             }
             if pending_constraints.has_identity_target(&descriptor_identity) {
-                return Err(version_ref_delete_restriction_error(
+                return Err(branch_ref_delete_restriction_error(
                     &tombstone.identity,
                     &descriptor_identity,
                 )?);
@@ -882,7 +882,7 @@ async fn validate_version_ref_delete_restrictions(
                 input.live_state,
                 descriptor_identity.domain(),
                 descriptor_identity.schema_key(),
-                descriptor_identity.entity_id_owned(),
+                descriptor_identity.entity_pk_owned(),
                 false,
             )
             .await?
@@ -892,7 +892,7 @@ async fn validate_version_ref_delete_restrictions(
             if descriptor_row.snapshot_content.is_some()
                 && !pending_constraints.tombstones_identity(&descriptor_row)
             {
-                return Err(version_ref_delete_restriction_error(
+                return Err(branch_ref_delete_restriction_error(
                     &tombstone.identity,
                     &descriptor_identity,
                 )?);
@@ -902,19 +902,19 @@ async fn validate_version_ref_delete_restrictions(
     Ok(())
 }
 
-fn version_ref_delete_restriction_error(
+fn branch_ref_delete_restriction_error(
     ref_identity: &DomainRowIdentity,
     descriptor_identity: &DomainRowIdentity,
 ) -> Result<LixError, LixError> {
     Ok(LixError::new(
         LixError::CODE_FOREIGN_KEY,
         format!(
-            "cannot delete '{}' row '{}' in version '{}' because matching '{}' row '{}' would remain without a version ref",
+            "cannot delete '{}' row '{}' in branch '{}' because matching '{}' row '{}' would remain without a branch ref",
             ref_identity.schema_key(),
-            ref_identity.entity_id().as_single_string_owned()?,
-            ref_identity.domain().version_id(),
+            ref_identity.entity_pk().as_single_string_owned()?,
+            ref_identity.domain().branch_id(),
             descriptor_identity.schema_key(),
-            descriptor_identity.entity_id().as_single_string_owned()?,
+            descriptor_identity.entity_pk().as_single_string_owned()?,
         ),
     ))
 }
@@ -937,7 +937,7 @@ impl PendingFileDescriptorIndex {
             if row.schema_key() != FILE_DESCRIPTOR_SCHEMA_KEY || row.file_id().is_some() {
                 continue;
             }
-            if row.entity_id().as_single_string_owned().is_ok() {
+            if row.entity_pk().as_single_string_owned().is_ok() {
                 let state = if (*row).snapshot_json().is_some() {
                     PendingFileDescriptorState::Present
                 } else {
@@ -958,7 +958,7 @@ impl PendingFileDescriptorIndex {
             .get(&DomainRowIdentity::in_domain(
                 domain.with_exact_file_scope(None),
                 FILE_DESCRIPTOR_SCHEMA_KEY,
-                EntityIdentity::single(file_id),
+                EntityPk::single(file_id),
             ))
             .copied()
     }
@@ -1009,7 +1009,7 @@ async fn committed_file_descriptor_exists_in_domain(
         live_state,
         &domain.with_exact_file_scope(None),
         FILE_DESCRIPTOR_SCHEMA_KEY,
-        EntityIdentity::single(file_id),
+        EntityPk::single(file_id),
         false,
     )
     .await?
@@ -1018,7 +1018,7 @@ async fn committed_file_descriptor_exists_in_domain(
     };
     Ok(row.snapshot_content.is_some()
         && row.schema_key == FILE_DESCRIPTOR_SCHEMA_KEY
-        && row.entity_id == EntityIdentity::single(file_id)
+        && row.entity_pk == EntityPk::single(file_id)
         && row.file_id.is_none())
 }
 
@@ -1029,11 +1029,11 @@ fn missing_file_owner_reference_error(
     Ok(LixError::new(
         LixError::CODE_FILE_NOT_FOUND,
             format!(
-                "file ownership validation failed for schema '{}': entity '{}' references missing file_id '{}' in effective file scope for version '{}'",
+                "file ownership validation failed for schema '{}': entity '{}' references missing file_id '{}' in effective file scope for branch '{}'",
                 row.schema_key(),
-                row.entity_id().as_json_array_text()?,
+                row.entity_pk().as_json_array_text()?,
                 file_id,
-                row.version_id()
+                row.branch_id()
             ),
     )
     .with_hint("Insert a row into lix_file with this id first, or use null for a global entity."))
@@ -1051,7 +1051,7 @@ fn validate_staged_row_shape(row: PreparedValidationRow<'_>) -> Result<(), LixEr
             LixError::CODE_SCHEMA_DEFINITION,
             "lix_registered_schema rows must not be scoped to a file",
         )
-        .with_hint("Schema definitions are scoped by version and durability only; write them with null file_id."));
+        .with_hint("Schema definitions are scoped by branch and durability only; write them with null file_id."));
     }
     Ok(())
 }
@@ -1181,15 +1181,15 @@ fn validate_primary_key_identity(
     let Some(primary_key_paths) = schema_plan.primary_key.as_ref() else {
         return Ok(());
     };
-    let derived = EntityIdentity::from_primary_key_paths(snapshot, &primary_key_paths)
+    let derived = EntityPk::from_primary_key_paths(snapshot, &primary_key_paths)
         .map_err(|error| primary_key_identity_error(row, &primary_key_paths, error))?;
-    if row.entity_id() != &derived {
+    if row.entity_pk() != &derived {
         return Err(LixError::new(
             LixError::CODE_UNIQUE,
             format!(
-                "primary-key constraint violation on schema '{}': entity_id '{}' does not match derived primary key '{}'",
+                "primary-key constraint violation on schema '{}': entity_pk '{}' does not match derived primary key '{}'",
                 row.schema_key(),
-                row.entity_id().as_json_array_text()?,
+                row.entity_pk().as_json_array_text()?,
                 derived.as_json_array_text()?
             ),
         ));
@@ -1199,7 +1199,7 @@ fn validate_primary_key_identity(
 
 #[derive(Default)]
 struct PendingConstraintIndexes {
-    unique_values: BTreeMap<PendingUniqueKey, EntityIdentity>,
+    unique_values: BTreeMap<PendingUniqueKey, EntityPk>,
     identity_targets: Vec<PendingIdentityTarget>,
     fk_targets: BTreeMap<PendingForeignKeyTargetKey, Vec<PendingForeignKeyTarget>>,
     fk_references: BTreeMap<PendingForeignKeyReferenceTarget, Vec<PendingForeignKeyReference>>,
@@ -1259,11 +1259,11 @@ impl PendingConstraintIndexes {
                 pointer_group: unique_paths.clone(),
                 value,
             };
-            if let Some(existing_entity_id) = self
+            if let Some(existing_entity_pk) = self
                 .unique_values
-                .insert(key.clone(), row.entity_id().clone())
+                .insert(key.clone(), row.entity_pk().clone())
             {
-                if existing_entity_id != *row.entity_id() {
+                if existing_entity_pk != *row.entity_pk() {
                     return Err(LixError::new(
                         LixError::CODE_UNIQUE,
                         format!(
@@ -1271,8 +1271,8 @@ impl PendingConstraintIndexes {
                             row.schema_key(),
                             format_pointer_group(&key.pointer_group),
                             key.value.display(),
-                            existing_entity_id.as_json_array_text()?,
-                            row.entity_id().as_json_array_text()?
+                            existing_entity_pk.as_json_array_text()?,
+                            row.entity_pk().as_json_array_text()?
                         ),
                     ));
                 }
@@ -1299,7 +1299,7 @@ impl PendingConstraintIndexes {
             })
             .or_default()
             .push(PendingForeignKeyTarget {
-                entity_id: row.entity_id().clone(),
+                entity_pk: row.entity_pk().clone(),
             });
     }
 
@@ -1412,7 +1412,7 @@ impl PendingConstraintIndexes {
     fn has_fk_reference_to_key(
         &self,
         schema_key: &str,
-        version_id: &str,
+        branch_id: &str,
         file_id: Option<&str>,
         pointer_group: &[&str],
         value: UniqueConstraintValue,
@@ -1423,7 +1423,7 @@ impl PendingConstraintIndexes {
             .collect::<Result<Vec<_>, _>>()?;
         let key = PendingForeignKeyReferenceTarget::Key(PendingForeignKeyTargetKey {
             schema_key: schema_key.to_string(),
-            domain: Domain::exact_file(version_id.to_string(), false, file_id.map(str::to_string)),
+            domain: Domain::exact_file(branch_id.to_string(), false, file_id.map(str::to_string)),
             pointer_group,
             value,
         });
@@ -1442,7 +1442,7 @@ impl PendingConstraintIndexes {
     fn has_fk_target(
         &self,
         schema_key: &str,
-        version_id: &str,
+        branch_id: &str,
         file_id: Option<&str>,
         pointer_group: &[&str],
         value: UniqueConstraintValue,
@@ -1453,7 +1453,7 @@ impl PendingConstraintIndexes {
             .collect::<Result<Vec<_>, _>>()?;
         let key = PendingForeignKeyTargetKey {
             schema_key: schema_key.to_string(),
-            domain: Domain::exact_file(version_id.to_string(), false, file_id.map(str::to_string)),
+            domain: Domain::exact_file(branch_id.to_string(), false, file_id.map(str::to_string)),
             pointer_group,
             value,
         };
@@ -1473,7 +1473,7 @@ struct PendingIdentityTarget {
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 struct PendingForeignKeyTarget {
-    entity_id: EntityIdentity,
+    entity_pk: EntityPk,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -1552,8 +1552,8 @@ fn validate_pending_delete_restrictions(
                         schema_key: tombstone.identity.schema_key_owned(),
                         domain,
                         pointer_group: primary_key_paths.clone(),
-                        value: UniqueConstraintValue::from_entity_identity(
-                            tombstone.identity.entity_id(),
+                        value: UniqueConstraintValue::from_entity_pk(
+                            tombstone.identity.entity_pk(),
                         ),
                     })
                 })
@@ -1582,11 +1582,11 @@ fn reject_pending_delete_references(
     Err(LixError::new(
         LixError::CODE_FOREIGN_KEY,
         format!(
-            "cannot delete '{}' row '{}' in version '{}' because pending row '{}' references it{}",
+            "cannot delete '{}' row '{}' in branch '{}' because pending row '{}' references it{}",
             deleted_identity.schema_key(),
-            deleted_identity.entity_id().as_json_array_text()?,
-            deleted_identity.domain().version_id(),
-            reference.identity.entity_id().as_json_array_text()?,
+            deleted_identity.entity_pk().as_json_array_text()?,
+            deleted_identity.domain().branch_id(),
+            reference.identity.entity_pk().as_json_array_text()?,
             pending_foreign_key_reference_target_description(target)?
         ),
     ))
@@ -1605,7 +1605,7 @@ fn pending_foreign_key_reference_target_description(
         PendingForeignKeyReferenceTarget::StateSurfaceIdentity(target) => Ok(format!(
             " through '{}:{}'",
             target.schema_key(),
-            target.entity_id().as_json_array_text()?
+            target.entity_pk().as_json_array_text()?
         )),
     }
 }
@@ -1672,7 +1672,7 @@ async fn validate_file_descriptor_delete_restrictions(
         if !tombstone.identity.domain().is_exact_file(&None) {
             continue;
         }
-        let file_id = tombstone.identity.entity_id().as_single_string_owned()?;
+        let file_id = tombstone.identity.entity_pk().as_single_string_owned()?;
         for source_domain in tombstone
             .identity
             .domain()
@@ -1694,10 +1694,10 @@ async fn validate_file_descriptor_delete_restrictions(
                 return Err(LixError::new(
                     LixError::CODE_FOREIGN_KEY,
                     format!(
-                        "cannot delete file descriptor '{}' in version '{}' because committed row '{}' in schema '{}' is still scoped to that file",
+                        "cannot delete file descriptor '{}' in branch '{}' because committed row '{}' in schema '{}' is still scoped to that file",
                         file_id,
-                        tombstone.identity.domain().version_id(),
-                        row.entity_id.as_json_array_text()?,
+                        tombstone.identity.domain().branch_id(),
+                        row.entity_pk.as_json_array_text()?,
                         row.schema_key,
                     ),
                 ));
@@ -1810,7 +1810,7 @@ async fn committed_deleted_row_value(
         live_state,
         tombstone.identity.domain(),
         tombstone.identity.schema_key(),
-        tombstone.identity.entity_id_owned(),
+        tombstone.identity.entity_pk_owned(),
         true,
     )
     .await?
@@ -1835,11 +1835,11 @@ fn committed_delete_restriction_error(
     Ok(LixError::new(
         LixError::CODE_FOREIGN_KEY,
         format!(
-            "cannot delete '{}' row '{}' in version '{}' because committed row '{}' references it through {}",
+            "cannot delete '{}' row '{}' in branch '{}' because committed row '{}' references it through {}",
             deleted_identity.schema_key(),
-            deleted_identity.entity_id().as_json_array_text()?,
-            deleted_identity.domain().version_id(),
-            referencing_row.entity_id.as_json_array_text()?,
+            deleted_identity.entity_pk().as_json_array_text()?,
+            deleted_identity.domain().branch_id(),
+            referencing_row.entity_pk.as_json_array_text()?,
             format_pointer_group(local_properties)
         ),
     ))
@@ -1993,11 +1993,11 @@ fn reject_unresolved_foreign_keys(
     Err(LixError::new(
         LixError::CODE_FOREIGN_KEY,
         format!(
-            "foreign key on schema '{}' row '{}' via {} has no matching target in version '{}'{}",
+            "foreign key on schema '{}' row '{}' via {} has no matching target in branch '{}'{}",
             check.source_schema_key,
-            check.source_identity.entity_id().as_json_array_text()?,
+            check.source_identity.entity_pk().as_json_array_text()?,
             format_pointer_group(&check.source_pointer_group),
-            check.source_identity.domain().version_id(),
+            check.source_identity.domain().branch_id(),
             unresolved_foreign_key_target_description(&check.target)?
         ),
     ))
@@ -2016,7 +2016,7 @@ fn unresolved_foreign_key_target_description(
         UnresolvedForeignKeyTarget::StateSurfaceIdentity(target) => Ok(format!(
             " for target '{}:{}'",
             target.schema_key(),
-            target.entity_id().as_json_array_text()?
+            target.entity_pk().as_json_array_text()?
         )),
     }
 }
@@ -2076,7 +2076,7 @@ async fn committed_state_surface_foreign_key_target_exists(
             live_state,
             candidate.domain(),
             vec![candidate.schema_key_owned()],
-            vec![candidate.entity_id_owned()],
+            vec![candidate.entity_pk_owned()],
             false,
         )
         .await?;
@@ -2084,7 +2084,7 @@ async fn committed_state_surface_foreign_key_target_exists(
             if pending_constraints.tombstones_identity(&row) {
                 continue;
             }
-            if candidate.matches_parts(&Domain::for_live_row(&row), &row.schema_key, &row.entity_id)
+            if candidate.matches_parts(&Domain::for_live_row(&row), &row.schema_key, &row.entity_pk)
             {
                 return Ok(true);
             }
@@ -2098,8 +2098,8 @@ fn state_surface_target_identity(
     foreign_key: &StateForeignKeyPlan,
     snapshot: &JsonValue,
 ) -> Result<DomainRowIdentity, LixError> {
-    let entity_id =
-        state_surface_local_json_value(snapshot, &foreign_key.entity_id_property, "entity_id")?;
+    let entity_pk =
+        state_surface_local_json_value(snapshot, &foreign_key.entity_pk_property, "entity_pk")?;
     let schema_key =
         state_surface_local_value(snapshot, &foreign_key.schema_key_property, "schema_key")?;
     let file_id =
@@ -2107,10 +2107,10 @@ fn state_surface_target_identity(
     Ok(DomainRowIdentity::in_domain(
         source_domain.with_exact_file_scope(file_id),
         schema_key,
-        EntityIdentity::from_json_array_value(entity_id).map_err(|error| {
+        EntityPk::from_json_array_value(entity_pk).map_err(|error| {
             LixError::new(
                 LixError::CODE_FOREIGN_KEY,
-                format!("state-surface foreign key entity_id is invalid: {error}"),
+                format!("state-surface foreign key entity_pk is invalid: {error}"),
             )
         })?,
     ))
@@ -2200,15 +2200,15 @@ async fn validate_committed_unique_constraints(
 ) -> Result<(), LixError> {
     let mut pending_by_scope = BTreeMap::<
         PendingUniqueConstraintScope,
-        BTreeMap<UniqueConstraintValue, Vec<&EntityIdentity>>,
+        BTreeMap<UniqueConstraintValue, Vec<&EntityPk>>,
     >::new();
-    for (key, pending_entity_id) in &pending_constraints.unique_values {
+    for (key, pending_entity_pk) in &pending_constraints.unique_values {
         pending_by_scope
             .entry(PendingUniqueConstraintScope::from(key))
             .or_default()
             .entry(key.value.clone())
             .or_default()
-            .push(pending_entity_id);
+            .push(pending_entity_pk);
     }
 
     for (scope, pending_values) in pending_by_scope {
@@ -2246,11 +2246,11 @@ async fn validate_committed_unique_constraints(
             else {
                 continue;
             };
-            let Some(pending_entity_ids) = pending_values.get(&committed_value) else {
+            let Some(pending_entity_pks) = pending_values.get(&committed_value) else {
                 continue;
             };
-            for pending_entity_id in pending_entity_ids {
-                if committed_row.entity_id == **pending_entity_id {
+            for pending_entity_pk in pending_entity_pks {
+                if committed_row.entity_pk == **pending_entity_pk {
                     continue;
                 }
                 return Err(LixError::new(
@@ -2260,8 +2260,8 @@ async fn validate_committed_unique_constraints(
                         scope.schema_key,
                         format_pointer_group(&scope.pointer_group),
                         committed_value.display(),
-                        committed_row.entity_id.as_json_array_text()?,
-                        pending_entity_id.as_json_array_text()?
+                        committed_row.entity_pk.as_json_array_text()?,
+                        pending_entity_pk.as_json_array_text()?
                     ),
                 ));
             }
@@ -2275,8 +2275,8 @@ fn committed_row_is_in_exact_unique_scope(
     scope: &PendingUniqueConstraintScope,
 ) -> bool {
     // LiveStateReader may return serving projections such as global rows
-    // projected into a requested version. Constraint validation is root-local:
-    // only rows authored in the exact version participate.
+    // projected into a requested branch. Constraint validation is root-local:
+    // only rows authored in the exact branch participate.
     scope.domain.contains(row) && row.schema_key == scope.schema_key
 }
 
@@ -2294,7 +2294,7 @@ impl UniqueConstraintValue {
         )
     }
 
-    fn from_entity_identity(identity: &EntityIdentity) -> Self {
+    fn from_entity_pk(identity: &EntityPk) -> Self {
         Self(
             identity
                 .parts
@@ -2360,31 +2360,22 @@ fn format_pointer_group(group: &[Vec<String>]) -> String {
 fn primary_key_identity_error(
     row: PreparedValidationRow<'_>,
     primary_key_paths: &[Vec<String>],
-    error: EntityIdentityError,
+    error: EntityPkError,
 ) -> LixError {
     let reason = match error {
-        EntityIdentityError::EmptyPrimaryKey => "empty x-lix-primary-key".to_string(),
-        EntityIdentityError::EmptyPrimaryKeyPath { index } => {
+        EntityPkError::EmptyPrimaryKey => "empty x-lix-primary-key".to_string(),
+        EntityPkError::EmptyPrimaryKeyPath { index } => {
             format!("empty x-lix-primary-key pointer at index {index}")
         }
-        EntityIdentityError::EmptyPrimaryKeyValue { index } => {
-            let pointer = primary_key_paths
-                .get(index)
-                .map(|path| format_json_pointer(path))
-                .unwrap_or_else(|| format!("index {index}"));
-            format!("empty value at primary-key pointer '{pointer}'")
-        }
-        EntityIdentityError::MissingPrimaryKeyValue { index } => {
+        EntityPkError::MissingPrimaryKeyValue { index } => {
             let pointer = format_json_pointer(&primary_key_paths[index]);
             format!("missing value at primary-key pointer '{pointer}'")
         }
-        EntityIdentityError::UnsupportedPrimaryKeyValue { index } => {
+        EntityPkError::UnsupportedPrimaryKeyValue { index } => {
             let pointer = format_json_pointer(&primary_key_paths[index]);
             format!("non-string value at primary-key pointer '{pointer}'")
         }
-        EntityIdentityError::InvalidEncodedEntityIdentity => {
-            "invalid encoded entity identity".to_string()
-        }
+        EntityPkError::InvalidEncodedEntityPk => "invalid encoded entity primary key".to_string(),
     };
     LixError::new(
         LixError::CODE_UNIQUE,
@@ -2418,7 +2409,7 @@ fn validate_foreign_key_definition(
         return Err(LixError::new(
             LixError::CODE_SCHEMA_DEFINITION,
             format!(
-                "foreign key on schema '{}' must not reference schemaKey 'lix_state'; use x-lix-state-foreign-keys with pointers ordered as [entity_id, schema_key, file_id]",
+                "foreign key on schema '{}' must not reference schemaKey 'lix_state'; use x-lix-state-foreign-keys with pointers ordered as [entity_pk, schema_key, file_id]",
                 source_key.schema_key
             ),
         ));
@@ -2688,8 +2679,7 @@ mod tests {
         visible_schemas: &[JsonValue],
     ) -> Result<CatalogSnapshot, LixError> {
         let catalog = catalog_from_transaction_parts_unchecked(staged_writes, visible_schemas)?;
-        let mut pending_keys =
-            BTreeMap::<SchemaCatalogKey, crate::entity_identity::EntityIdentity>::new();
+        let mut pending_keys = BTreeMap::<SchemaCatalogKey, crate::entity_pk::EntityPk>::new();
         for row in staged_writes
             .validation_rows()
             .filter(|row| row.schema_key() == REGISTERED_SCHEMA_KEY)
@@ -2711,16 +2701,16 @@ mod tests {
                 })?;
             let (key, _) = schema_from_registered_snapshot(&snapshot)?;
             let catalog_key = SchemaCatalogKey::from_schema_key(key);
-            if let Some(existing_entity_id) =
-                pending_keys.insert(catalog_key.clone(), row.entity_id().clone())
+            if let Some(existing_entity_pk) =
+                pending_keys.insert(catalog_key.clone(), row.entity_pk().clone())
             {
                 return Err(LixError::new(
                     LixError::CODE_SCHEMA_DEFINITION,
                     format!(
                         "duplicate pending registered schema '{}' in transaction: rows '{}' and '{}'",
                         catalog_key.schema_key,
-                        existing_entity_id.as_json_array_text()?,
-                        row.entity_id().as_json_array_text()?
+                        existing_entity_pk.as_json_array_text()?,
+                        row.entity_pk().as_json_array_text()?
                     ),
                 ));
             }
@@ -2784,8 +2774,8 @@ mod tests {
                 .chain(test_file_descriptor_rows())
                 .find(|row| {
                     row.schema_key == request.schema_key
-                        && row.version_id == request.version_id
-                        && row.entity_id == request.entity_id
+                        && row.branch_id == request.branch_id
+                        && row.entity_pk == request.entity_pk
                         && request.file_id.matches(row.file_id.as_ref())
                 }))
         }
@@ -2834,8 +2824,8 @@ mod tests {
                 .scan_rows(&LiveStateScanRequest {
                     filter: LiveStateFilter {
                         schema_keys: vec![request.schema_key.clone()],
-                        entity_ids: vec![request.entity_id.clone()],
-                        version_ids: vec![request.version_id.clone()],
+                        entity_pks: vec![request.entity_pk.clone()],
+                        branch_ids: vec![request.branch_id.clone()],
                         file_ids: vec![request.file_id.clone()],
                         ..Default::default()
                     },
@@ -2945,7 +2935,7 @@ mod tests {
     }
 
     #[test]
-    fn schema_catalog_indexes_visible_schemas_by_key_and_version() {
+    fn schema_catalog_indexes_visible_schemas_by_key_and_branch() {
         let visible_schemas = vec![json!({
             "x-lix-key": "visible_schema",
             "type": "object",
@@ -2970,7 +2960,6 @@ mod tests {
         ];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![pending_registered_schema_row("pending_schema")],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let input = validation_input(&staged_writes, &visible_schemas);
@@ -2996,7 +2985,6 @@ mod tests {
         ];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![pending_registered_schema_row("same_schema")],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
 
@@ -3074,7 +3062,7 @@ mod tests {
     #[test]
     fn schema_catalog_rejects_duplicate_pending_registered_schema_identity() {
         let mut duplicate = pending_registered_schema_row("duplicate_schema");
-        duplicate.entity_id = registered_schema_entity_id("duplicate_schema_duplicate");
+        duplicate.entity_pk = registered_schema_entity_pk("duplicate_schema_duplicate");
         let staged_writes = PreparedWriteSet {
             state_rows: vec![pending_registered_schema_row("duplicate_schema"), duplicate],
             ..empty_staged_write_set()
@@ -3110,7 +3098,6 @@ mod tests {
     fn schema_catalog_rejects_foreign_key_missing_target_schema() {
         let staged_writes = PreparedWriteSet {
             state_rows: vec![pending_registered_schema_from_definition(fk_child_schema())],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let visible_schemas = vec![registered_schema()];
@@ -3203,11 +3190,10 @@ mod tests {
         schema["x-lix-foreign-keys"][0]["properties"] = json!(["/parent_id"]);
         schema["x-lix-foreign-keys"][0]["references"] = json!({
             "schemaKey": "lix_state",
-            "properties": ["/entity_id"]
+            "properties": ["/entity_pk"]
         });
         let staged_writes = PreparedWriteSet {
             state_rows: vec![pending_registered_schema_from_definition(schema)],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let visible_schemas = vec![registered_schema()];
@@ -3225,20 +3211,19 @@ mod tests {
     #[test]
     fn schema_catalog_rejects_state_surface_foreign_key_without_full_address_tuple() {
         let mut schema = state_surface_ref_schema();
-        schema["x-lix-state-foreign-keys"][0] = json!(["/target_entity_id"]);
+        schema["x-lix-state-foreign-keys"][0] = json!(["/target_entity_pk"]);
         let staged_writes = PreparedWriteSet {
             state_rows: vec![pending_registered_schema_from_definition(schema)],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let visible_schemas = vec![registered_schema()];
 
         let error = catalog_from_transaction_parts_unchecked(&staged_writes, &visible_schemas)
-            .expect_err("state FK target must include entity_id, schema_key, and file_id");
+            .expect_err("state FK target must include entity_pk, schema_key, and file_id");
 
         assert_eq!(error.code, LixError::CODE_SCHEMA_DEFINITION);
         assert!(
-            error.message.contains("[entity_id, schema_key, file_id]"),
+            error.message.contains("[entity_pk, schema_key, file_id]"),
             "unexpected error: {error:?}"
         );
     }
@@ -3263,7 +3248,6 @@ mod tests {
         let visible_schemas = vec![key_value_schema()];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![staged_row("unknown_schema", None)],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
 
@@ -3302,10 +3286,9 @@ mod tests {
             "untracked_only_schema",
             Some(json!({ "id": "row-1" }).to_string()),
         );
-        tracked_row.entity_id = EntityIdentity::single("row-1");
+        tracked_row.entity_pk = EntityPk::single("row-1");
         let staged_writes = PreparedWriteSet {
             state_rows: vec![untracked_schema, tracked_row],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
 
@@ -3347,7 +3330,6 @@ mod tests {
         let visible_schemas = vec![key_value_schema()];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![staged_row("lix_key_value", None)],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
 
@@ -3361,7 +3343,6 @@ mod tests {
         let visible_schemas = vec![unique_schema()];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![unique_row("post-1", "hello-world", "first")],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
 
@@ -3386,7 +3367,7 @@ mod tests {
         ];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![
-                staged_file_descriptor_row("file-a", "version-a"),
+                staged_file_descriptor_row("file-a", "branch-a"),
                 unique_row("post-1", "hello-world", "first"),
             ],
             ..empty_staged_write_set()
@@ -3408,7 +3389,7 @@ mod tests {
             file_descriptor_schema(),
             directory_descriptor_schema(),
         ];
-        let mut untracked_file_descriptor = staged_file_descriptor_row("file-a", "version-a");
+        let mut untracked_file_descriptor = staged_file_descriptor_row("file-a", "branch-a");
         mark_prepared_row_untracked(&mut untracked_file_descriptor);
         let staged_writes = PreparedWriteSet {
             state_rows: vec![
@@ -3441,7 +3422,7 @@ mod tests {
         mark_prepared_row_untracked(&mut untracked_row);
         let staged_writes = PreparedWriteSet {
             state_rows: vec![
-                staged_file_descriptor_row("file-a", "version-a"),
+                staged_file_descriptor_row("file-a", "branch-a"),
                 untracked_row,
             ],
             ..empty_staged_write_set()
@@ -3463,14 +3444,13 @@ mod tests {
             file_descriptor_schema(),
             directory_descriptor_schema(),
         ];
-        let mut file_descriptor_delete = staged_file_descriptor_row("file-a", "version-a");
+        let mut file_descriptor_delete = staged_file_descriptor_row("file-a", "branch-a");
         file_descriptor_delete.snapshot = None;
         let staged_writes = PreparedWriteSet {
             state_rows: vec![
                 file_descriptor_delete,
                 unique_row("post-1", "hello-world", "first"),
             ],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
 
@@ -3492,11 +3472,10 @@ mod tests {
         let visible_schemas = vec![unique_schema()];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![unique_row("post-1", "hello-world", "first")],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
-            rows: vec![committed_file_descriptor_row("file-a", "version-a")],
+            rows: vec![committed_file_descriptor_row("file-a", "branch-a")],
         };
 
         validate_prepared_writes(TransactionValidationInput::from_visible_schemas_for_tests(
@@ -3513,10 +3492,9 @@ mod tests {
         let visible_schemas = vec![unique_schema()];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![unique_row("post-1", "hello-world", "first")],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
-        let mut untracked_file_descriptor = committed_file_descriptor_row("file-a", "version-a");
+        let mut untracked_file_descriptor = committed_file_descriptor_row("file-a", "branch-a");
         mark_live_row_untracked(&mut untracked_file_descriptor);
         let live_state = StrictStaticLiveStateReader {
             rows: vec![untracked_file_descriptor],
@@ -3542,11 +3520,10 @@ mod tests {
         mark_prepared_row_untracked(&mut untracked_row);
         let staged_writes = PreparedWriteSet {
             state_rows: vec![untracked_row],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let live_state = StrictStaticLiveStateReader {
-            rows: vec![committed_file_descriptor_row("file-a", "version-a")],
+            rows: vec![committed_file_descriptor_row("file-a", "branch-a")],
         };
 
         validate_prepared_writes(TransactionValidationInput::from_visible_schemas_for_tests(
@@ -3563,11 +3540,10 @@ mod tests {
         let visible_schemas = vec![unique_schema()];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![unique_row("post-1", "hello-world", "first")],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
-        let tracked_file_descriptor = committed_file_descriptor_row("file-a", "version-a");
-        let mut untracked_tombstone = committed_file_descriptor_row("file-a", "version-a");
+        let tracked_file_descriptor = committed_file_descriptor_row("file-a", "branch-a");
+        let mut untracked_tombstone = committed_file_descriptor_row("file-a", "branch-a");
         untracked_tombstone.snapshot_content = None;
         mark_live_row_untracked(&mut untracked_tombstone);
         let live_state = OverlayingStaticLiveStateReader {
@@ -3590,11 +3566,10 @@ mod tests {
             file_descriptor_schema(),
             directory_descriptor_schema(),
         ];
-        let mut file_descriptor_delete = staged_file_descriptor_row("file-a", "version-a");
+        let mut file_descriptor_delete = staged_file_descriptor_row("file-a", "branch-a");
         file_descriptor_delete.snapshot = None;
         let staged_writes = PreparedWriteSet {
             state_rows: vec![file_descriptor_delete],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
@@ -3621,11 +3596,10 @@ mod tests {
             file_descriptor_schema(),
             directory_descriptor_schema(),
         ];
-        let mut file_descriptor_delete = staged_file_descriptor_row("file-a", "version-a");
+        let mut file_descriptor_delete = staged_file_descriptor_row("file-a", "branch-a");
         file_descriptor_delete.snapshot = None;
         let staged_writes = PreparedWriteSet {
             state_rows: vec![file_descriptor_delete],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let mut untracked_row =
@@ -3633,7 +3607,7 @@ mod tests {
         mark_live_row_untracked(&mut untracked_row);
         let live_state = StrictStaticLiveStateReader {
             rows: vec![
-                committed_file_descriptor_row("file-a", "version-a"),
+                committed_file_descriptor_row("file-a", "branch-a"),
                 untracked_row,
             ],
         };
@@ -3653,9 +3627,9 @@ mod tests {
     #[tokio::test]
     async fn validation_allows_untracked_directory_parent_to_tracked_directory() {
         let visible_schemas = vec![directory_descriptor_schema()];
-        let tracked_parent = directory_descriptor_row("dir-parent", None, "parent", "version-a");
+        let tracked_parent = directory_descriptor_row("dir-parent", None, "parent", "branch-a");
         let mut untracked_child =
-            directory_descriptor_row("dir-child", Some("dir-parent"), "child", "version-a");
+            directory_descriptor_row("dir-child", Some("dir-parent"), "child", "branch-a");
         mark_prepared_row_untracked(&mut untracked_child);
         let staged_writes = PreparedWriteSet {
             state_rows: vec![tracked_parent, untracked_child],
@@ -3672,13 +3646,12 @@ mod tests {
         let visible_schemas = vec![unique_schema()];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![unique_row("post-1", "hello-world", "first")],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let live_state = StrictStaticLiveStateReader {
             rows: vec![committed_file_descriptor_row(
                 "file-a",
-                crate::GLOBAL_VERSION_ID,
+                crate::GLOBAL_BRANCH_ID,
             )],
         };
 
@@ -3689,7 +3662,7 @@ mod tests {
                 &live_state,
             ))
             .await
-            .expect_err("global file descriptor should not satisfy a version-local row");
+            .expect_err("global file descriptor should not satisfy a branch-local row");
 
         assert_eq!(error.code, LixError::CODE_FILE_NOT_FOUND);
     }
@@ -3698,10 +3671,9 @@ mod tests {
     async fn validation_rejects_primary_key_duplicate_with_different_identity() {
         let visible_schemas = vec![unique_schema()];
         let mut conflicting = unique_row("post-1", "hello-world", "first");
-        conflicting.entity_id = crate::entity_identity::EntityIdentity::single("post-2");
+        conflicting.entity_pk = crate::entity_pk::EntityPk::single("post-2");
         let staged_writes = PreparedWriteSet {
             state_rows: vec![unique_row("post-1", "hello-world", "first"), conflicting],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
 
@@ -3749,37 +3721,35 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn validation_rejects_pending_unique_same_value_in_same_version() {
+    async fn validation_rejects_pending_unique_same_value_in_same_branch() {
         let visible_schemas = vec![unique_schema()];
         let mut duplicate = unique_row("post-2", "hello-world", "second");
-        duplicate.version_id = "version-a".to_string();
+        duplicate.branch_id = "branch-a".to_string();
         let staged_writes = PreparedWriteSet {
             state_rows: vec![unique_row("post-1", "hello-world", "first"), duplicate],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
 
         let error = validate_prepared_writes(validation_input(&staged_writes, &visible_schemas))
             .await
-            .expect_err("same unique value in the same version should fail");
+            .expect_err("same unique value in the same branch should fail");
 
         assert_eq!(error.code, LixError::CODE_UNIQUE);
     }
 
     #[tokio::test]
-    async fn validation_allows_pending_unique_same_value_in_different_versions() {
+    async fn validation_allows_pending_unique_same_value_in_different_branches() {
         let visible_schemas = vec![unique_schema()];
-        let mut version_b = unique_row("post-2", "hello-world", "second");
-        version_b.version_id = "version-b".to_string();
+        let mut branch_b = unique_row("post-2", "hello-world", "second");
+        branch_b.branch_id = "branch-b".to_string();
         let staged_writes = PreparedWriteSet {
-            state_rows: vec![unique_row("post-1", "hello-world", "first"), version_b],
-            adopted_rows: Vec::new(),
+            state_rows: vec![unique_row("post-1", "hello-world", "first"), branch_b],
             ..empty_staged_write_set()
         };
 
         validate_prepared_writes(validation_input(&staged_writes, &visible_schemas))
             .await
-            .expect("unique values should be scoped to the exact version_id");
+            .expect("unique values should be scoped to the exact branch_id");
     }
 
     #[tokio::test]
@@ -3805,7 +3775,6 @@ mod tests {
         tombstone.snapshot = None;
         let staged_writes = PreparedWriteSet {
             state_rows: vec![tombstone, unique_row("post-2", "hello-world", "second")],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
 
@@ -3815,24 +3784,24 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn validation_scopes_pending_unique_values_by_file_and_version() {
+    async fn validation_scopes_pending_unique_values_by_file_and_branch() {
         let visible_schemas = vec![unique_schema()];
         let mut different_file = unique_row("post-2", "hello-world", "second");
         different_file.file_id = Some("file-b".to_string());
-        let mut different_version = unique_row("post-3", "hello-world", "third");
-        different_version.version_id = "version-b".to_string();
+        let mut different_branch = unique_row("post-3", "hello-world", "third");
+        different_branch.branch_id = "branch-b".to_string();
         let staged_writes = PreparedWriteSet {
             state_rows: vec![
                 unique_row("post-1", "hello-world", "first"),
                 different_file,
-                different_version,
+                different_branch,
             ],
             ..empty_staged_write_set()
         };
 
         validate_prepared_writes(validation_input(&staged_writes, &visible_schemas))
             .await
-            .expect("unique values are scoped by file and version");
+            .expect("unique values are scoped by file and branch");
     }
 
     #[tokio::test]
@@ -3840,7 +3809,6 @@ mod tests {
         let visible_schemas = vec![unique_schema()];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![unique_row("post-2", "hello-world", "second")],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
@@ -3864,7 +3832,6 @@ mod tests {
         let visible_schemas = vec![unique_schema()];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![unique_row("post-2", "hello-world", "second")],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let tracked_duplicate = committed_unique_row("post-1", "hello-world", "first");
@@ -3898,7 +3865,6 @@ mod tests {
                 untracked_tombstone,
                 unique_row("post-2", "hello-world", "second"),
             ],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
@@ -3922,7 +3888,6 @@ mod tests {
         let visible_schemas = vec![nullable_unique_schema()];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![nullable_unique_row("row-2", None, "root-name")],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
@@ -3942,11 +3907,10 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn validation_rejects_committed_unique_same_value_in_same_version() {
+    async fn validation_rejects_committed_unique_same_value_in_same_branch() {
         let visible_schemas = vec![unique_schema()];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![unique_row("post-2", "hello-world", "second")],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
@@ -3960,19 +3924,18 @@ mod tests {
                 &live_state,
             ))
             .await
-            .expect_err("same unique value in the same version should conflict");
+            .expect_err("same unique value in the same branch should conflict");
 
         assert_eq!(error.code, LixError::CODE_UNIQUE);
     }
 
     #[tokio::test]
-    async fn validation_allows_committed_unique_same_value_in_different_versions() {
+    async fn validation_allows_committed_unique_same_value_in_different_branches() {
         let visible_schemas = vec![unique_schema()];
-        let mut version_b = unique_row("post-2", "hello-world", "second");
-        version_b.version_id = "version-b".to_string();
+        let mut branch_b = unique_row("post-2", "hello-world", "second");
+        branch_b.branch_id = "branch-b".to_string();
         let staged_writes = PreparedWriteSet {
-            state_rows: vec![version_b],
-            adopted_rows: Vec::new(),
+            state_rows: vec![branch_b],
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
@@ -3985,7 +3948,7 @@ mod tests {
             &live_state,
         ))
         .await
-        .expect("committed unique values should be scoped to the exact version_id");
+        .expect("committed unique values should be scoped to the exact branch_id");
     }
 
     #[tokio::test]
@@ -3993,11 +3956,10 @@ mod tests {
         let visible_schemas = vec![unique_schema()];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![unique_row("post-2", "hello-world", "second")],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let mut projected_overlay_row = committed_unique_row("post-1", "hello-world", "first");
-        projected_overlay_row.version_id = "version-a".to_string();
+        projected_overlay_row.branch_id = "branch-a".to_string();
         projected_overlay_row.global = true;
         let live_state = StaticLiveStateReader {
             rows: vec![projected_overlay_row],
@@ -4017,7 +3979,6 @@ mod tests {
         let visible_schemas = vec![unique_schema()];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![unique_row("post-1", "hello-world", "updated")],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
@@ -4046,7 +4007,6 @@ mod tests {
         committed_two.file_id = None;
         let staged_writes = PreparedWriteSet {
             state_rows: vec![staged_one, staged_two],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let live_state = CountingStaticLiveStateReader {
@@ -4072,7 +4032,6 @@ mod tests {
         tombstone.snapshot = None;
         let staged_writes = PreparedWriteSet {
             state_rows: vec![tombstone, unique_row("post-2", "hello-world", "second")],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
@@ -4089,15 +4048,14 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn validation_allows_committed_unique_same_value_in_different_file_or_version() {
+    async fn validation_allows_committed_unique_same_value_in_different_file_or_branch() {
         let visible_schemas = vec![unique_schema()];
         let mut different_file = unique_row("post-2", "hello-world", "second");
         different_file.file_id = Some("file-b".to_string());
-        let mut different_version = unique_row("post-3", "hello-world", "third");
-        different_version.version_id = "version-b".to_string();
+        let mut different_branch = unique_row("post-3", "hello-world", "third");
+        different_branch.branch_id = "branch-b".to_string();
         let staged_writes = PreparedWriteSet {
-            state_rows: vec![different_file, different_version],
-            adopted_rows: Vec::new(),
+            state_rows: vec![different_file, different_branch],
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
@@ -4110,39 +4068,38 @@ mod tests {
             &live_state,
         ))
         .await
-        .expect("committed uniqueness is scoped by file and version");
+        .expect("committed uniqueness is scoped by file and branch");
     }
 
     #[tokio::test]
-    async fn validation_rejects_foreign_key_target_missing_in_same_version() {
+    async fn validation_rejects_foreign_key_target_missing_in_same_branch() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
         let staged_writes = PreparedWriteSet {
-            state_rows: vec![fk_child_row("child-1", "parent-1", "version-a")],
-            adopted_rows: Vec::new(),
+            state_rows: vec![fk_child_row("child-1", "parent-1", "branch-a")],
             ..empty_staged_write_set()
         };
 
         let error = validate_prepared_writes(validation_input(&staged_writes, &visible_schemas))
             .await
-            .expect_err("foreign key must resolve in the same version");
+            .expect_err("foreign key must resolve in the same branch");
 
         assert_eq!(error.code, LixError::CODE_FOREIGN_KEY);
     }
 
     #[tokio::test]
-    async fn validation_allows_foreign_key_target_in_same_version() {
+    async fn validation_allows_foreign_key_target_in_same_branch() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![
-                fk_parent_row("parent-1", "version-a"),
-                fk_child_row("child-1", "parent-1", "version-a"),
+                fk_parent_row("parent-1", "branch-a"),
+                fk_child_row("child-1", "parent-1", "branch-a"),
             ],
             ..empty_staged_write_set()
         };
 
         validate_prepared_writes(validation_input(&staged_writes, &visible_schemas))
             .await
-            .expect("foreign key should resolve against pending rows in the same version");
+            .expect("foreign key should resolve against pending rows in the same branch");
     }
 
     #[tokio::test]
@@ -4153,15 +4110,15 @@ mod tests {
             file_descriptor_schema(),
             directory_descriptor_schema(),
         ];
-        let mut untracked_parent = fk_parent_row("parent-1", "version-a");
+        let mut untracked_parent = fk_parent_row("parent-1", "branch-a");
         mark_prepared_row_untracked(&mut untracked_parent);
-        let mut untracked_file_descriptor = staged_file_descriptor_row("file-a", "version-a");
+        let mut untracked_file_descriptor = staged_file_descriptor_row("file-a", "branch-a");
         mark_prepared_row_untracked(&mut untracked_file_descriptor);
         let staged_writes = PreparedWriteSet {
             state_rows: vec![
                 untracked_file_descriptor,
                 untracked_parent,
-                fk_child_row("child-1", "parent-1", "version-a"),
+                fk_child_row("child-1", "parent-1", "branch-a"),
             ],
             ..empty_staged_write_set()
         };
@@ -4181,11 +4138,11 @@ mod tests {
             file_descriptor_schema(),
             directory_descriptor_schema(),
         ];
-        let tracked_file_descriptor = staged_file_descriptor_row("file-a", "version-a");
-        let tracked_parent = fk_parent_row("parent-1", "version-a");
-        let mut untracked_file_descriptor = staged_file_descriptor_row("file-a", "version-a");
+        let tracked_file_descriptor = staged_file_descriptor_row("file-a", "branch-a");
+        let tracked_parent = fk_parent_row("parent-1", "branch-a");
+        let mut untracked_file_descriptor = staged_file_descriptor_row("file-a", "branch-a");
         mark_prepared_row_untracked(&mut untracked_file_descriptor);
-        let mut untracked_child = fk_child_row("child-1", "parent-1", "version-a");
+        let mut untracked_child = fk_child_row("child-1", "parent-1", "branch-a");
         mark_prepared_row_untracked(&mut untracked_child);
         let staged_writes = PreparedWriteSet {
             state_rows: vec![
@@ -4203,35 +4160,33 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn validation_rejects_foreign_key_target_that_exists_only_in_different_version() {
+    async fn validation_rejects_foreign_key_target_that_exists_only_in_different_branch() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
         let staged_writes = PreparedWriteSet {
             state_rows: vec![
-                fk_parent_row("parent-1", "version-b"),
-                fk_child_row("child-1", "parent-1", "version-a"),
+                fk_parent_row("parent-1", "branch-b"),
+                fk_child_row("child-1", "parent-1", "branch-a"),
             ],
             ..empty_staged_write_set()
         };
 
         let error = validate_prepared_writes(validation_input(&staged_writes, &visible_schemas))
             .await
-            .expect_err("foreign key target in another version should not satisfy this version");
+            .expect_err("foreign key target in another branch should not satisfy this branch");
 
         assert_eq!(error.code, LixError::CODE_FOREIGN_KEY);
     }
 
     #[tokio::test]
-    async fn validation_allows_foreign_key_target_committed_in_same_version() {
+    async fn validation_allows_foreign_key_target_committed_in_same_branch() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
         let staged_writes = PreparedWriteSet {
-            state_rows: vec![fk_child_row("child-1", "parent-1", "version-a")],
-            adopted_rows: Vec::new(),
+            state_rows: vec![fk_child_row("child-1", "parent-1", "branch-a")],
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
             rows: vec![MaterializedLiveStateRow::from(fk_parent_row(
-                "parent-1",
-                "version-a",
+                "parent-1", "branch-a",
             ))],
         };
 
@@ -4241,19 +4196,18 @@ mod tests {
             &live_state,
         ))
         .await
-        .expect("foreign key should resolve against committed rows in the same version");
+        .expect("foreign key should resolve against committed rows in the same branch");
     }
 
     #[tokio::test]
     async fn validation_rejects_tracked_foreign_key_target_committed_only_as_untracked() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
         let staged_writes = PreparedWriteSet {
-            state_rows: vec![fk_child_row("child-1", "parent-1", "version-a")],
-            adopted_rows: Vec::new(),
+            state_rows: vec![fk_child_row("child-1", "parent-1", "branch-a")],
             ..empty_staged_write_set()
         };
         let mut untracked_parent =
-            MaterializedLiveStateRow::from(fk_parent_row("parent-1", "version-a"));
+            MaterializedLiveStateRow::from(fk_parent_row("parent-1", "branch-a"));
         mark_live_row_untracked(&mut untracked_parent);
         let live_state = StaticLiveStateReader {
             rows: vec![untracked_parent],
@@ -4279,19 +4233,18 @@ mod tests {
             file_descriptor_schema(),
             directory_descriptor_schema(),
         ];
-        let mut untracked_file_descriptor = staged_file_descriptor_row("file-a", "version-a");
+        let mut untracked_file_descriptor = staged_file_descriptor_row("file-a", "branch-a");
         mark_prepared_row_untracked(&mut untracked_file_descriptor);
-        let mut untracked_child = fk_child_row("child-1", "parent-1", "version-a");
+        let mut untracked_child = fk_child_row("child-1", "parent-1", "branch-a");
         mark_prepared_row_untracked(&mut untracked_child);
         let staged_writes = PreparedWriteSet {
             state_rows: vec![untracked_file_descriptor, untracked_child],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
             rows: vec![
-                committed_file_descriptor_row("file-a", "version-a"),
-                MaterializedLiveStateRow::from(fk_parent_row("parent-1", "version-a")),
+                committed_file_descriptor_row("file-a", "branch-a"),
+                MaterializedLiveStateRow::from(fk_parent_row("parent-1", "branch-a")),
             ],
         };
 
@@ -4308,13 +4261,12 @@ mod tests {
     async fn validation_allows_tracked_foreign_key_target_committed_behind_untracked_overlay() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
         let staged_writes = PreparedWriteSet {
-            state_rows: vec![fk_child_row("child-1", "parent-1", "version-a")],
-            adopted_rows: Vec::new(),
+            state_rows: vec![fk_child_row("child-1", "parent-1", "branch-a")],
             ..empty_staged_write_set()
         };
-        let tracked_parent = MaterializedLiveStateRow::from(fk_parent_row("parent-1", "version-a"));
+        let tracked_parent = MaterializedLiveStateRow::from(fk_parent_row("parent-1", "branch-a"));
         let mut untracked_overlay =
-            MaterializedLiveStateRow::from(fk_parent_row("parent-1", "version-a"));
+            MaterializedLiveStateRow::from(fk_parent_row("parent-1", "branch-a"));
         mark_live_row_untracked(&mut untracked_overlay);
         let live_state = OverlayingStaticLiveStateReader {
             rows: vec![tracked_parent, untracked_overlay],
@@ -4334,18 +4286,17 @@ mod tests {
     #[tokio::test]
     async fn validation_rejects_deleting_tracked_fk_target_referenced_behind_untracked_overlay() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
-        let mut parent_delete = fk_parent_row("parent-1", "version-a");
+        let mut parent_delete = fk_parent_row("parent-1", "branch-a");
         parent_delete.snapshot = None;
         let staged_writes = PreparedWriteSet {
             state_rows: vec![parent_delete],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
-        let tracked_parent = MaterializedLiveStateRow::from(fk_parent_row("parent-1", "version-a"));
+        let tracked_parent = MaterializedLiveStateRow::from(fk_parent_row("parent-1", "branch-a"));
         let tracked_child =
-            MaterializedLiveStateRow::from(fk_child_row("child-1", "parent-1", "version-a"));
+            MaterializedLiveStateRow::from(fk_child_row("child-1", "parent-1", "branch-a"));
         let mut untracked_child_overlay =
-            MaterializedLiveStateRow::from(fk_child_row("child-1", "other-parent", "version-a"));
+            MaterializedLiveStateRow::from(fk_child_row("child-1", "other-parent", "branch-a"));
         mark_live_row_untracked(&mut untracked_child_overlay);
         let live_state = OverlayingStaticLiveStateReader {
             rows: vec![tracked_parent, tracked_child, untracked_child_overlay],
@@ -4366,16 +4317,15 @@ mod tests {
     #[tokio::test]
     async fn validation_rejects_deleting_tracked_fk_target_referenced_by_committed_untracked_row() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
-        let mut parent_delete = fk_parent_row("parent-1", "version-a");
+        let mut parent_delete = fk_parent_row("parent-1", "branch-a");
         parent_delete.snapshot = None;
         let staged_writes = PreparedWriteSet {
             state_rows: vec![parent_delete],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
-        let tracked_parent = MaterializedLiveStateRow::from(fk_parent_row("parent-1", "version-a"));
+        let tracked_parent = MaterializedLiveStateRow::from(fk_parent_row("parent-1", "branch-a"));
         let mut untracked_child =
-            MaterializedLiveStateRow::from(fk_child_row("child-1", "parent-1", "version-a"));
+            MaterializedLiveStateRow::from(fk_child_row("child-1", "parent-1", "branch-a"));
         mark_live_row_untracked(&mut untracked_child);
         let live_state = StaticLiveStateReader {
             rows: vec![tracked_parent, untracked_child],
@@ -4394,17 +4344,15 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn validation_rejects_foreign_key_target_committed_only_in_different_version() {
+    async fn validation_rejects_foreign_key_target_committed_only_in_different_branch() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
         let staged_writes = PreparedWriteSet {
-            state_rows: vec![fk_child_row("child-1", "parent-1", "version-a")],
-            adopted_rows: Vec::new(),
+            state_rows: vec![fk_child_row("child-1", "parent-1", "branch-a")],
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
             rows: vec![MaterializedLiveStateRow::from(fk_parent_row(
-                "parent-1",
-                "version-b",
+                "parent-1", "branch-b",
             ))],
         };
 
@@ -4416,7 +4364,7 @@ mod tests {
             ))
             .await
             .expect_err(
-                "foreign key target in another committed version should not satisfy this version",
+                "foreign key target in another committed branch should not satisfy this branch",
             );
 
         assert_eq!(error.code, LixError::CODE_FOREIGN_KEY);
@@ -4425,19 +4373,18 @@ mod tests {
     #[tokio::test]
     async fn validation_rejects_foreign_key_target_tombstoned_by_transaction() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
-        let mut parent_delete = fk_parent_row("parent-1", "version-a");
+        let mut parent_delete = fk_parent_row("parent-1", "branch-a");
         parent_delete.snapshot = None;
         let staged_writes = PreparedWriteSet {
             state_rows: vec![
                 parent_delete,
-                fk_child_row("child-1", "parent-1", "version-a"),
+                fk_child_row("child-1", "parent-1", "branch-a"),
             ],
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
             rows: vec![MaterializedLiveStateRow::from(fk_parent_row(
-                "parent-1",
-                "version-a",
+                "parent-1", "branch-a",
             ))],
         };
 
@@ -4456,21 +4403,19 @@ mod tests {
     #[tokio::test]
     async fn validation_allows_tracked_fk_target_when_untracked_tombstone_shadows_same_identity() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
-        let mut untracked_parent_delete = fk_parent_row("parent-1", "version-a");
+        let mut untracked_parent_delete = fk_parent_row("parent-1", "branch-a");
         untracked_parent_delete.snapshot = None;
         mark_prepared_row_untracked(&mut untracked_parent_delete);
         let staged_writes = PreparedWriteSet {
             state_rows: vec![
                 untracked_parent_delete,
-                fk_child_row("child-1", "parent-1", "version-a"),
+                fk_child_row("child-1", "parent-1", "branch-a"),
             ],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
             rows: vec![MaterializedLiveStateRow::from(fk_parent_row(
-                "parent-1",
-                "version-a",
+                "parent-1", "branch-a",
             ))],
         };
 
@@ -4486,19 +4431,18 @@ mod tests {
     #[tokio::test]
     async fn validation_rejects_pending_reference_to_deleted_identity() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
-        let mut parent_delete = fk_parent_row("parent-1", "version-a");
+        let mut parent_delete = fk_parent_row("parent-1", "branch-a");
         parent_delete.snapshot = None;
         let staged_writes = PreparedWriteSet {
             state_rows: vec![
                 parent_delete,
-                fk_child_row("child-1", "parent-1", "version-a"),
+                fk_child_row("child-1", "parent-1", "branch-a"),
             ],
             ..empty_staged_write_set()
         };
         let live_state = StaticLiveStateReader {
             rows: vec![MaterializedLiveStateRow::from(fk_parent_row(
-                "parent-1",
-                "version-a",
+                "parent-1", "branch-a",
             ))],
         };
 
@@ -4515,22 +4459,22 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn validation_allows_delete_with_pending_reference_in_different_version() {
+    async fn validation_allows_delete_with_pending_reference_in_different_branch() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
-        let mut parent_delete = fk_parent_row("parent-1", "version-a");
+        let mut parent_delete = fk_parent_row("parent-1", "branch-a");
         parent_delete.snapshot = None;
         let staged_writes = PreparedWriteSet {
             state_rows: vec![
                 parent_delete,
-                fk_parent_row("parent-1", "version-b"),
-                fk_child_row("child-1", "parent-1", "version-b"),
+                fk_parent_row("parent-1", "branch-b"),
+                fk_child_row("child-1", "parent-1", "branch-b"),
             ],
             ..empty_staged_write_set()
         };
 
         validate_prepared_writes(validation_input(&staged_writes, &visible_schemas))
             .await
-            .expect("pending references in another version should not block this delete");
+            .expect("pending references in another branch should not block this delete");
     }
 
     #[tokio::test]
@@ -4547,8 +4491,7 @@ mod tests {
         };
         let live_state = StaticLiveStateReader {
             rows: vec![MaterializedLiveStateRow::from(fk_parent_row(
-                "target-1",
-                "version-a",
+                "target-1", "branch-a",
             ))],
         };
 
@@ -4569,9 +4512,9 @@ mod tests {
             file_descriptor_schema(),
             directory_descriptor_schema(),
         ];
-        let mut untracked_target = fk_parent_row("target-1", "version-a");
+        let mut untracked_target = fk_parent_row("target-1", "branch-a");
         mark_prepared_row_untracked(&mut untracked_target);
-        let mut untracked_file_descriptor = staged_file_descriptor_row("file-a", "version-a");
+        let mut untracked_file_descriptor = staged_file_descriptor_row("file-a", "branch-a");
         mark_prepared_row_untracked(&mut untracked_file_descriptor);
         let staged_writes = PreparedWriteSet {
             state_rows: vec![
@@ -4604,7 +4547,7 @@ mod tests {
             ..empty_staged_write_set()
         };
         let mut untracked_target =
-            MaterializedLiveStateRow::from(fk_parent_row("target-1", "version-a"));
+            MaterializedLiveStateRow::from(fk_parent_row("target-1", "branch-a"));
         mark_live_row_untracked(&mut untracked_target);
         let live_state = StaticLiveStateReader {
             rows: vec![untracked_target],
@@ -4632,7 +4575,7 @@ mod tests {
             file_descriptor_schema(),
             directory_descriptor_schema(),
         ];
-        let mut untracked_file_descriptor = staged_file_descriptor_row("file-a", "version-a");
+        let mut untracked_file_descriptor = staged_file_descriptor_row("file-a", "branch-a");
         mark_prepared_row_untracked(&mut untracked_file_descriptor);
         let mut untracked_ref =
             state_surface_ref_row("ref-1", "target-1", "fk_parent_schema", "file-a");
@@ -4643,8 +4586,8 @@ mod tests {
         };
         let live_state = StaticLiveStateReader {
             rows: vec![
-                committed_file_descriptor_row("file-a", "version-a"),
-                MaterializedLiveStateRow::from(fk_parent_row("target-1", "version-a")),
+                committed_file_descriptor_row("file-a", "branch-a"),
+                MaterializedLiveStateRow::from(fk_parent_row("target-1", "branch-a")),
             ],
         };
 
@@ -4670,9 +4613,9 @@ mod tests {
             )],
             ..empty_staged_write_set()
         };
-        let tracked_target = MaterializedLiveStateRow::from(fk_parent_row("target-1", "version-a"));
+        let tracked_target = MaterializedLiveStateRow::from(fk_parent_row("target-1", "branch-a"));
         let mut untracked_overlay =
-            MaterializedLiveStateRow::from(fk_parent_row("target-1", "version-a"));
+            MaterializedLiveStateRow::from(fk_parent_row("target-1", "branch-a"));
         mark_live_row_untracked(&mut untracked_overlay);
         let live_state = OverlayingStaticLiveStateReader {
             rows: vec![tracked_target, untracked_overlay],
@@ -4690,10 +4633,10 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn validation_allows_state_surface_fk_target_with_composite_entity_id() {
+    async fn validation_allows_state_surface_fk_target_with_composite_entity_pk() {
         let visible_schemas = vec![composite_message_schema(), state_surface_ref_schema()];
         let staged_writes = PreparedWriteSet {
-            state_rows: vec![state_surface_ref_row_with_target_entity_id(
+            state_rows: vec![state_surface_ref_row_with_target_entity_pk(
                 "ref-1",
                 json!(["welcome.title", "en"]),
                 "composite_message_schema",
@@ -4705,7 +4648,7 @@ mod tests {
             rows: vec![MaterializedLiveStateRow::from(composite_message_row(
                 "welcome.title",
                 "en",
-                "version-a",
+                "branch-a",
             ))],
         };
 
@@ -4715,23 +4658,22 @@ mod tests {
             &live_state,
         ))
         .await
-        .expect("state FK should resolve composite JSON-array entity ids");
+        .expect("state FK should resolve composite JSON-array entity pks");
     }
 
     #[tokio::test]
-    async fn validation_rejects_delete_when_same_version_reference_exists() {
+    async fn validation_rejects_delete_when_same_branch_reference_exists() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
-        let mut parent_delete = fk_parent_row("parent-1", "version-a");
+        let mut parent_delete = fk_parent_row("parent-1", "branch-a");
         parent_delete.snapshot = None;
         let live_state = StaticLiveStateReader {
             rows: vec![
-                MaterializedLiveStateRow::from(fk_parent_row("parent-1", "version-a")),
-                MaterializedLiveStateRow::from(fk_child_row("child-1", "parent-1", "version-a")),
+                MaterializedLiveStateRow::from(fk_parent_row("parent-1", "branch-a")),
+                MaterializedLiveStateRow::from(fk_child_row("child-1", "parent-1", "branch-a")),
             ],
         };
         let staged_writes = PreparedWriteSet {
             state_rows: vec![parent_delete],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
 
@@ -4742,25 +4684,24 @@ mod tests {
                 &live_state,
             ))
             .await
-            .expect_err("delete should be restricted by same-version references");
+            .expect_err("delete should be restricted by same-branch references");
 
         assert_eq!(error.code, LixError::CODE_FOREIGN_KEY);
     }
 
     #[tokio::test]
-    async fn validation_allows_delete_when_only_different_version_reference_exists() {
+    async fn validation_allows_delete_when_only_different_branch_reference_exists() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
-        let mut parent_delete = fk_parent_row("parent-1", "version-a");
+        let mut parent_delete = fk_parent_row("parent-1", "branch-a");
         parent_delete.snapshot = None;
         let live_state = StaticLiveStateReader {
             rows: vec![
-                MaterializedLiveStateRow::from(fk_parent_row("parent-1", "version-a")),
-                MaterializedLiveStateRow::from(fk_child_row("child-1", "parent-1", "version-b")),
+                MaterializedLiveStateRow::from(fk_parent_row("parent-1", "branch-a")),
+                MaterializedLiveStateRow::from(fk_child_row("child-1", "parent-1", "branch-b")),
             ],
         };
         let staged_writes = PreparedWriteSet {
             state_rows: vec![parent_delete],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
 
@@ -4770,25 +4711,24 @@ mod tests {
             &live_state,
         ))
         .await
-        .expect("references in another version should not restrict this version");
+        .expect("references in another branch should not restrict this branch");
     }
 
     #[tokio::test]
     async fn validation_allows_delete_when_committed_reference_is_also_deleted() {
         let visible_schemas = vec![fk_parent_schema(), fk_child_schema()];
-        let mut parent_delete = fk_parent_row("parent-1", "version-a");
+        let mut parent_delete = fk_parent_row("parent-1", "branch-a");
         parent_delete.snapshot = None;
-        let mut child_delete = fk_child_row("child-1", "parent-1", "version-a");
+        let mut child_delete = fk_child_row("child-1", "parent-1", "branch-a");
         child_delete.snapshot = None;
         let live_state = StaticLiveStateReader {
             rows: vec![
-                MaterializedLiveStateRow::from(fk_parent_row("parent-1", "version-a")),
-                MaterializedLiveStateRow::from(fk_child_row("child-1", "parent-1", "version-a")),
+                MaterializedLiveStateRow::from(fk_parent_row("parent-1", "branch-a")),
+                MaterializedLiveStateRow::from(fk_child_row("child-1", "parent-1", "branch-a")),
             ],
         };
         let staged_writes = PreparedWriteSet {
             state_rows: vec![parent_delete, child_delete],
-            adopted_rows: Vec::new(),
             ..empty_staged_write_set()
         };
 
@@ -4821,7 +4761,7 @@ mod tests {
     #[test]
     fn pending_indexes_record_primary_key_fk_targets_by_exact_scope() {
         let mut indexes = PendingConstraintIndexes::default();
-        let row = fk_parent_row("parent-1", "version-a");
+        let row = fk_parent_row("parent-1", "branch-a");
         let snapshot = serde_json::from_str::<JsonValue>(
             row.snapshot
                 .as_ref()
@@ -4841,7 +4781,7 @@ mod tests {
         assert!(indexes
             .has_fk_target(
                 "fk_parent_schema",
-                "version-a",
+                "branch-a",
                 Some("file-a"),
                 &["/id"],
                 UniqueConstraintValue::string_values(["parent-1"]),
@@ -4850,7 +4790,7 @@ mod tests {
         assert!(!indexes
             .has_fk_target(
                 "fk_parent_schema",
-                "version-b",
+                "branch-b",
                 Some("file-a"),
                 &["/id"],
                 UniqueConstraintValue::string_values(["parent-1"]),
@@ -4881,7 +4821,7 @@ mod tests {
         assert!(indexes
             .has_fk_target(
                 "unique_schema",
-                "version-a",
+                "branch-a",
                 Some("file-a"),
                 &["/slug"],
                 UniqueConstraintValue::string_values(["hello-world"]),
@@ -4892,7 +4832,7 @@ mod tests {
     #[test]
     fn pending_indexes_record_normal_fk_references_by_exact_scope() {
         let mut indexes = PendingConstraintIndexes::default();
-        let row = fk_child_row("child-1", "parent-1", "version-a");
+        let row = fk_child_row("child-1", "parent-1", "branch-a");
         let snapshot = serde_json::from_str::<JsonValue>(
             row.snapshot
                 .as_ref()
@@ -4916,7 +4856,7 @@ mod tests {
         assert!(indexes
             .has_fk_reference_to_key(
                 "fk_parent_schema",
-                "version-a",
+                "branch-a",
                 Some("file-a"),
                 &["/id"],
                 UniqueConstraintValue::string_values(["parent-1"]),
@@ -4925,7 +4865,7 @@ mod tests {
         assert!(!indexes
             .has_fk_reference_to_key(
                 "fk_parent_schema",
-                "version-b",
+                "branch-b",
                 Some("file-a"),
                 &["/id"],
                 UniqueConstraintValue::string_values(["parent-1"]),
@@ -4959,11 +4899,11 @@ mod tests {
 
         assert!(
             indexes.has_fk_reference_to_identity(DomainRowIdentity::exact(
-                "version-a",
+                "branch-a",
                 false,
                 Some("file-a".to_string()),
                 "fk_parent_schema",
-                EntityIdentity::single("target-1"),
+                EntityPk::single("target-1"),
             ))
         );
     }
@@ -4971,11 +4911,11 @@ mod tests {
     #[test]
     fn pending_delete_restrictions_ignore_tombstoned_referencing_rows() {
         let mut indexes = PendingConstraintIndexes::default();
-        let mut parent_delete = fk_parent_row("parent-1", "version-a");
+        let mut parent_delete = fk_parent_row("parent-1", "branch-a");
         parent_delete.snapshot = None;
         indexes.remember_tombstone(PreparedValidationRow::State(&parent_delete));
 
-        let child = fk_child_row("child-1", "parent-1", "version-a");
+        let child = fk_child_row("child-1", "parent-1", "branch-a");
         let child_snapshot = serde_json::from_str::<JsonValue>(
             child
                 .snapshot
@@ -4996,7 +4936,7 @@ mod tests {
             )
             .expect("child row should index FK reference");
 
-        let mut child_delete = fk_child_row("child-1", "parent-1", "version-a");
+        let mut child_delete = fk_child_row("child-1", "parent-1", "branch-a");
         child_delete.snapshot = None;
         indexes.remember_tombstone(PreparedValidationRow::State(&child_delete));
 
@@ -5007,7 +4947,7 @@ mod tests {
     #[test]
     fn pending_fk_validation_collects_unresolved_normal_fk_check() {
         let indexes = PendingConstraintIndexes::default();
-        let row = fk_child_row("child-1", "parent-1", "version-a");
+        let row = fk_child_row("child-1", "parent-1", "branch-a");
         let snapshot = serde_json::from_str::<JsonValue>(
             row.snapshot
                 .as_ref()
@@ -5034,11 +4974,11 @@ mod tests {
         assert_eq!(
             unresolved[0].source_identity,
             DomainRowIdentity::exact(
-                "version-a",
+                "branch-a",
                 false,
                 Some("file-a".to_string()),
                 "fk_child_schema",
-                EntityIdentity::single("child-1"),
+                EntityPk::single("child-1"),
             )
         );
         assert_eq!(unresolved[0].source_schema_key, "fk_child_schema");
@@ -5050,7 +4990,7 @@ mod tests {
             panic!("normal FK should produce key target");
         };
         assert_eq!(target.schema_key, "fk_parent_schema");
-        assert_eq!(target.domain.version_id(), "version-a");
+        assert_eq!(target.domain.branch_id(), "branch-a");
         assert_eq!(
             target.domain.file_scope(),
             &DomainFileScope::Exact(Some("file-a".to_string()))
@@ -5065,7 +5005,7 @@ mod tests {
     #[test]
     fn pending_fk_validation_resolves_normal_fk_against_pending_target() {
         let mut indexes = PendingConstraintIndexes::default();
-        let parent = fk_parent_row("parent-1", "version-a");
+        let parent = fk_parent_row("parent-1", "branch-a");
         let parent_snapshot = serde_json::from_str::<JsonValue>(
             parent
                 .snapshot
@@ -5082,7 +5022,7 @@ mod tests {
             )
             .expect("parent should index as pending FK target");
 
-        let child = fk_child_row("child-1", "parent-1", "version-a");
+        let child = fk_child_row("child-1", "parent-1", "branch-a");
         let child_snapshot = serde_json::from_str::<JsonValue>(
             child
                 .snapshot
@@ -5108,14 +5048,14 @@ mod tests {
 
         assert!(
             unresolved.is_empty(),
-            "same-version pending parent should satisfy the child FK"
+            "same-branch pending parent should satisfy the child FK"
         );
     }
 
     #[test]
-    fn pending_fk_validation_keeps_normal_fk_unresolved_across_versions() {
+    fn pending_fk_validation_keeps_normal_fk_unresolved_across_branches() {
         let mut indexes = PendingConstraintIndexes::default();
-        let parent = fk_parent_row("parent-1", "version-b");
+        let parent = fk_parent_row("parent-1", "branch-b");
         let parent_snapshot = serde_json::from_str::<JsonValue>(
             parent
                 .snapshot
@@ -5132,7 +5072,7 @@ mod tests {
             )
             .expect("parent should index as pending FK target");
 
-        let child = fk_child_row("child-1", "parent-1", "version-a");
+        let child = fk_child_row("child-1", "parent-1", "branch-a");
         let child_snapshot = serde_json::from_str::<JsonValue>(
             child
                 .snapshot
@@ -5161,9 +5101,9 @@ mod tests {
             panic!("normal FK should produce key target");
         };
         assert_eq!(
-            target.domain.version_id(),
-            "version-a",
-            "FK checks are exact-version scoped, not overlay scoped"
+            target.domain.branch_id(),
+            "branch-a",
+            "FK checks are exact-branch scoped, not overlay scoped"
         );
     }
 
@@ -5197,18 +5137,18 @@ mod tests {
         assert_eq!(
             unresolved[0].source_identity,
             DomainRowIdentity::exact(
-                "version-a",
+                "branch-a",
                 false,
                 Some("file-a".to_string()),
                 "state_surface_ref_schema",
-                EntityIdentity::single("ref-1"),
+                EntityPk::single("ref-1"),
             )
         );
         assert_eq!(unresolved[0].source_schema_key, "state_surface_ref_schema");
         assert_eq!(
             unresolved[0].source_pointer_group,
             vec![
-                vec!["target_entity_id".to_string()],
+                vec!["target_entity_pk".to_string()],
                 vec!["target_schema_key".to_string()],
                 vec!["target_file_id".to_string()],
             ]
@@ -5216,9 +5156,9 @@ mod tests {
         let UnresolvedForeignKeyTarget::StateSurfaceIdentity(target) = &unresolved[0].target else {
             panic!("state FK should produce state-surface identity target");
         };
-        assert_eq!(target.domain().version_id(), "version-a");
+        assert_eq!(target.domain().branch_id(), "branch-a");
         assert_eq!(target.schema_key(), "fk_parent_schema");
-        assert_eq!(target.entity_id(), &EntityIdentity::single("target-1"));
+        assert_eq!(target.entity_pk(), &EntityPk::single("target-1"));
         assert_eq!(
             target.domain().file_scope(),
             &DomainFileScope::Exact(Some("file-a".to_string()))
@@ -5228,7 +5168,7 @@ mod tests {
     #[tokio::test]
     async fn committed_fk_lookup_resolves_normal_fk_in_exact_scope() {
         let indexes = PendingConstraintIndexes::default();
-        let child = fk_child_row("child-1", "parent-1", "version-a");
+        let child = fk_child_row("child-1", "parent-1", "branch-a");
         let child_snapshot = serde_json::from_str::<JsonValue>(
             child
                 .snapshot
@@ -5252,8 +5192,7 @@ mod tests {
         .expect("pending FK validation should collect unresolved check");
         let live_state = StaticLiveStateReader {
             rows: vec![MaterializedLiveStateRow::from(fk_parent_row(
-                "parent-1",
-                "version-a",
+                "parent-1", "branch-a",
             ))],
         };
 
@@ -5271,14 +5210,14 @@ mod tests {
 
         assert!(
             still_unresolved.is_empty(),
-            "same-version committed parent should satisfy unresolved FK"
+            "same-branch committed parent should satisfy unresolved FK"
         );
     }
 
     #[tokio::test]
-    async fn committed_fk_lookup_keeps_normal_fk_unresolved_across_versions() {
+    async fn committed_fk_lookup_keeps_normal_fk_unresolved_across_branches() {
         let indexes = PendingConstraintIndexes::default();
-        let child = fk_child_row("child-1", "parent-1", "version-a");
+        let child = fk_child_row("child-1", "parent-1", "branch-a");
         let child_snapshot = serde_json::from_str::<JsonValue>(
             child
                 .snapshot
@@ -5302,8 +5241,7 @@ mod tests {
         .expect("pending FK validation should collect unresolved check");
         let live_state = StaticLiveStateReader {
             rows: vec![MaterializedLiveStateRow::from(fk_parent_row(
-                "parent-1",
-                "version-b",
+                "parent-1", "branch-b",
             ))],
         };
 
@@ -5322,7 +5260,7 @@ mod tests {
         assert_eq!(
             still_unresolved.len(),
             1,
-            "committed FK lookup is exact-version scoped"
+            "committed FK lookup is exact-branch scoped"
         );
     }
 
@@ -5352,8 +5290,7 @@ mod tests {
         .expect("pending FK validation should collect unresolved check");
         let live_state = StaticLiveStateReader {
             rows: vec![MaterializedLiveStateRow::from(fk_parent_row(
-                "target-1",
-                "version-a",
+                "target-1", "branch-a",
             ))],
         };
 
@@ -5378,10 +5315,9 @@ mod tests {
     fn empty_staged_write_set() -> PreparedWriteSet {
         PreparedWriteSet {
             state_rows: Vec::new(),
-            adopted_rows: Vec::new(),
             insert_identities: BTreeMap::new(),
-            commit_members_by_version: BTreeMap::new(),
-            extra_commit_parents_by_version: BTreeMap::new(),
+            commit_change_refs_by_branch: BTreeMap::new(),
+            extra_commit_parents_by_branch: BTreeMap::new(),
             file_data_writes: Vec::new(),
         }
     }
@@ -5399,8 +5335,8 @@ mod tests {
         }
         (request.filter.schema_keys.is_empty()
             || request.filter.schema_keys.contains(&row.schema_key))
-            && (request.filter.version_ids.is_empty()
-                || request.filter.version_ids.contains(&row.version_id))
+            && (request.filter.branch_ids.is_empty()
+                || request.filter.branch_ids.contains(&row.branch_id))
             && (request.filter.file_ids.is_empty()
                 || request
                     .filter
@@ -5414,17 +5350,17 @@ mod tests {
         request: &LiveStateRowRequest,
     ) -> bool {
         row.schema_key == request.schema_key
-            && row.version_id == request.version_id
-            && row.entity_id == request.entity_id
+            && row.branch_id == request.branch_id
+            && row.entity_pk == request.entity_pk
             && request.file_id.matches(row.file_id.as_ref())
     }
 
     fn test_file_descriptor_rows() -> Vec<MaterializedLiveStateRow> {
         vec![
-            committed_file_descriptor_row("file-a", "version-a"),
-            committed_file_descriptor_row("file-a", "version-b"),
-            committed_file_descriptor_row("file-b", "version-a"),
-            committed_file_descriptor_row("file-b", "version-b"),
+            committed_file_descriptor_row("file-a", "branch-a"),
+            committed_file_descriptor_row("file-a", "branch-b"),
+            committed_file_descriptor_row("file-b", "branch-a"),
+            committed_file_descriptor_row("file-b", "branch-b"),
         ]
     }
 
@@ -5445,7 +5381,7 @@ mod tests {
         PreparedStateRow {
             schema_plan_id: crate::catalog::SchemaPlanId::for_test(0),
             facts: crate::transaction::types::PreparedRowFacts::default(),
-            entity_id: registered_schema_entity_id(&key.schema_key),
+            entity_pk: registered_schema_entity_pk(&key.schema_key),
             schema_key: REGISTERED_SCHEMA_KEY.to_string(),
             file_id: None,
             snapshot: Some(test_stage_json(&json!({ "value": schema }).to_string())),
@@ -5457,12 +5393,12 @@ mod tests {
             change_id: Some("change-registered-schema".to_string()),
             commit_id: Some("commit-registered-schema".to_string()),
             untracked: false,
-            version_id: crate::GLOBAL_VERSION_ID.to_string(),
+            branch_id: crate::GLOBAL_BRANCH_ID.to_string(),
         }
     }
 
-    fn registered_schema_entity_id(schema_key: &str) -> crate::entity_identity::EntityIdentity {
-        crate::entity_identity::EntityIdentity::from_primary_key_paths(
+    fn registered_schema_entity_pk(schema_key: &str) -> crate::entity_pk::EntityPk {
+        crate::entity_pk::EntityPk::from_primary_key_paths(
             &serde_json::json!({
                 "value": {
                     "x-lix-key": schema_key,
@@ -5583,12 +5519,12 @@ mod tests {
             "x-lix-key": "state_surface_ref_schema",
             "x-lix-primary-key": ["/id"],
             "x-lix-state-foreign-keys": [
-                ["/target_entity_id", "/target_schema_key", "/target_file_id"]
+                ["/target_entity_pk", "/target_schema_key", "/target_file_id"]
             ],
             "type": "object",
             "properties": {
                 "id": { "type": "string" },
-                "target_entity_id": {
+                "target_entity_pk": {
                     "type": "array",
                     "items": { "type": "string" },
                     "minItems": 1
@@ -5596,108 +5532,108 @@ mod tests {
                 "target_schema_key": { "type": "string" },
                 "target_file_id": { "type": ["string", "null"] }
             },
-            "required": ["id", "target_entity_id", "target_schema_key", "target_file_id"],
+            "required": ["id", "target_entity_pk", "target_schema_key", "target_file_id"],
             "additionalProperties": false
         })
     }
 
-    fn unique_row(entity_id: &str, slug: &str, title: &str) -> PreparedStateRow {
+    fn unique_row(entity_pk: &str, slug: &str, title: &str) -> PreparedStateRow {
         let mut row = staged_row(
             "unique_schema",
             Some(
                 json!({
-                    "id": entity_id,
+                    "id": entity_pk,
                     "slug": slug,
                     "title": title,
                 })
                 .to_string(),
             ),
         );
-        row.entity_id = crate::entity_identity::EntityIdentity::single(entity_id);
+        row.entity_pk = crate::entity_pk::EntityPk::single(entity_pk);
         row.file_id = Some("file-a".to_string());
-        row.version_id = "version-a".to_string();
+        row.branch_id = "branch-a".to_string();
         row.global = false;
         row
     }
 
-    fn nullable_unique_row(entity_id: &str, scope: Option<&str>, name: &str) -> PreparedStateRow {
+    fn nullable_unique_row(entity_pk: &str, scope: Option<&str>, name: &str) -> PreparedStateRow {
         let mut row = staged_row(
             "nullable_unique_schema",
             Some(
                 json!({
-                    "id": entity_id,
+                    "id": entity_pk,
                     "scope": scope,
                     "name": name,
                 })
                 .to_string(),
             ),
         );
-        row.entity_id = crate::entity_identity::EntityIdentity::single(entity_id);
+        row.entity_pk = crate::entity_pk::EntityPk::single(entity_pk);
         row.file_id = Some("file-a".to_string());
-        row.version_id = "version-a".to_string();
+        row.branch_id = "branch-a".to_string();
         row.global = false;
         row
     }
 
-    fn fk_parent_row(entity_id: &str, version_id: &str) -> PreparedStateRow {
+    fn fk_parent_row(entity_pk: &str, branch_id: &str) -> PreparedStateRow {
         let mut row = staged_row(
             "fk_parent_schema",
-            Some(json!({ "id": entity_id }).to_string()),
+            Some(json!({ "id": entity_pk }).to_string()),
         );
-        row.entity_id = crate::entity_identity::EntityIdentity::single(entity_id);
+        row.entity_pk = crate::entity_pk::EntityPk::single(entity_pk);
         row.file_id = Some("file-a".to_string());
-        row.version_id = version_id.to_string();
+        row.branch_id = branch_id.to_string();
         row.global = false;
         row
     }
 
-    fn fk_child_row(entity_id: &str, parent_id: &str, version_id: &str) -> PreparedStateRow {
+    fn fk_child_row(entity_pk: &str, parent_id: &str, branch_id: &str) -> PreparedStateRow {
         let mut row = staged_row(
             "fk_child_schema",
-            Some(json!({ "id": entity_id, "parent_id": parent_id }).to_string()),
+            Some(json!({ "id": entity_pk, "parent_id": parent_id }).to_string()),
         );
-        row.entity_id = crate::entity_identity::EntityIdentity::single(entity_id);
+        row.entity_pk = crate::entity_pk::EntityPk::single(entity_pk);
         row.file_id = Some("file-a".to_string());
-        row.version_id = version_id.to_string();
+        row.branch_id = branch_id.to_string();
         row.global = false;
         row
     }
 
-    fn composite_message_row(key: &str, locale: &str, version_id: &str) -> PreparedStateRow {
+    fn composite_message_row(key: &str, locale: &str, branch_id: &str) -> PreparedStateRow {
         let snapshot = json!({
             "key": key,
             "locale": locale,
             "text": "Welcome",
         });
         let mut row = staged_row("composite_message_schema", Some(snapshot.to_string()));
-        row.entity_id = EntityIdentity::from_primary_key_paths(
+        row.entity_pk = EntityPk::from_primary_key_paths(
             &snapshot,
             &[vec!["key".to_string()], vec!["locale".to_string()]],
         )
         .expect("composite message identity should derive");
         row.file_id = Some("file-a".to_string());
-        row.version_id = version_id.to_string();
+        row.branch_id = branch_id.to_string();
         row.global = false;
         row
     }
 
     fn state_surface_ref_row(
-        entity_id: &str,
-        target_entity_id: &str,
+        entity_pk: &str,
+        target_entity_pk: &str,
         target_schema_key: &str,
         target_file_id: &str,
     ) -> PreparedStateRow {
-        state_surface_ref_row_with_target_entity_id(
-            entity_id,
-            json!([target_entity_id]),
+        state_surface_ref_row_with_target_entity_pk(
+            entity_pk,
+            json!([target_entity_pk]),
             target_schema_key,
             target_file_id,
         )
     }
 
-    fn state_surface_ref_row_with_target_entity_id(
-        entity_id: &str,
-        target_entity_id: JsonValue,
+    fn state_surface_ref_row_with_target_entity_pk(
+        entity_pk: &str,
+        target_entity_pk: JsonValue,
         target_schema_key: &str,
         target_file_id: &str,
     ) -> PreparedStateRow {
@@ -5705,17 +5641,17 @@ mod tests {
             "state_surface_ref_schema",
             Some(
                 json!({
-                    "id": entity_id,
-                    "target_entity_id": target_entity_id,
+                    "id": entity_pk,
+                    "target_entity_pk": target_entity_pk,
                     "target_schema_key": target_schema_key,
                     "target_file_id": target_file_id,
                 })
                 .to_string(),
             ),
         );
-        row.entity_id = crate::entity_identity::EntityIdentity::single(entity_id);
+        row.entity_pk = crate::entity_pk::EntityPk::single(entity_pk);
         row.file_id = Some("file-a".to_string());
-        row.version_id = "version-a".to_string();
+        row.branch_id = "branch-a".to_string();
         row.global = false;
         row
     }
@@ -5732,7 +5668,7 @@ mod tests {
         row.commit_id = None;
     }
 
-    fn staged_file_descriptor_row(file_id: &str, version_id: &str) -> PreparedStateRow {
+    fn staged_file_descriptor_row(file_id: &str, branch_id: &str) -> PreparedStateRow {
         let mut row = staged_row(
             FILE_DESCRIPTOR_SCHEMA_KEY,
             Some(
@@ -5745,22 +5681,22 @@ mod tests {
                 .to_string(),
             ),
         );
-        row.entity_id = crate::entity_identity::EntityIdentity::single(file_id);
+        row.entity_pk = crate::entity_pk::EntityPk::single(file_id);
         row.file_id = None;
-        row.version_id = version_id.to_string();
-        row.global = version_id == crate::GLOBAL_VERSION_ID;
+        row.branch_id = branch_id.to_string();
+        row.global = branch_id == crate::GLOBAL_BRANCH_ID;
         row
     }
 
-    fn committed_file_descriptor_row(file_id: &str, version_id: &str) -> MaterializedLiveStateRow {
-        MaterializedLiveStateRow::from(staged_file_descriptor_row(file_id, version_id))
+    fn committed_file_descriptor_row(file_id: &str, branch_id: &str) -> MaterializedLiveStateRow {
+        MaterializedLiveStateRow::from(staged_file_descriptor_row(file_id, branch_id))
     }
 
     fn directory_descriptor_row(
         directory_id: &str,
         parent_id: Option<&str>,
         name: &str,
-        version_id: &str,
+        branch_id: &str,
     ) -> PreparedStateRow {
         let mut row = staged_row(
             DIRECTORY_DESCRIPTOR_SCHEMA_KEY,
@@ -5774,17 +5710,17 @@ mod tests {
                 .to_string(),
             ),
         );
-        row.entity_id = crate::entity_identity::EntityIdentity::single(directory_id);
+        row.entity_pk = crate::entity_pk::EntityPk::single(directory_id);
         row.file_id = None;
-        row.version_id = version_id.to_string();
-        row.global = version_id == crate::GLOBAL_VERSION_ID;
+        row.branch_id = branch_id.to_string();
+        row.global = branch_id == crate::GLOBAL_BRANCH_ID;
         row
     }
 
-    fn committed_unique_row(entity_id: &str, slug: &str, title: &str) -> MaterializedLiveStateRow {
-        let row = unique_row(entity_id, slug, title);
+    fn committed_unique_row(entity_pk: &str, slug: &str, title: &str) -> MaterializedLiveStateRow {
+        let row = unique_row(entity_pk, slug, title);
         MaterializedLiveStateRow {
-            entity_id: row.entity_id,
+            entity_pk: row.entity_pk,
             schema_key: row.schema_key,
             file_id: row.file_id,
             snapshot_content: row.snapshot.as_ref().map(|snapshot| snapshot.materialize()),
@@ -5796,23 +5732,23 @@ mod tests {
             change_id: row.change_id,
             commit_id: row.commit_id,
             untracked: row.untracked,
-            version_id: row.version_id,
+            branch_id: row.branch_id,
         }
     }
 
     fn committed_nullable_unique_row(
-        entity_id: &str,
+        entity_pk: &str,
         scope: Option<&str>,
         name: &str,
     ) -> MaterializedLiveStateRow {
-        MaterializedLiveStateRow::from(nullable_unique_row(entity_id, scope, name))
+        MaterializedLiveStateRow::from(nullable_unique_row(entity_pk, scope, name))
     }
 
     fn staged_row(schema_key: &str, snapshot_content: Option<String>) -> PreparedStateRow {
         PreparedStateRow {
             schema_plan_id: crate::catalog::SchemaPlanId::for_test(0),
             facts: crate::transaction::types::PreparedRowFacts::default(),
-            entity_id: crate::entity_identity::EntityIdentity::single("entity-1"),
+            entity_pk: crate::entity_pk::EntityPk::single("entity-1"),
             schema_key: schema_key.to_string(),
             file_id: None,
             snapshot: snapshot_content.as_deref().map(test_stage_json),
@@ -5824,7 +5760,7 @@ mod tests {
             change_id: Some("change-1".to_string()),
             commit_id: Some("commit-1".to_string()),
             untracked: false,
-            version_id: crate::GLOBAL_VERSION_ID.to_string(),
+            branch_id: crate::GLOBAL_BRANCH_ID.to_string(),
         }
     }
 }