common/direct_access/entity/

entity_repository.rs

// Generated by Qleany v1.11.0 from common_entity_repository.tera

use std::fmt::Display;

use crate::{
    database::hashmap_store::HashMapStoreSnapshot,
    // `*_or_recover` rather than a plain `.read()/.write().unwrap()`: a panic
    // anywhere under a table's guard poisons that lock for the rest of the
    // process, and the release profile unwinds, so the poison is reachable in a
    // shipped build. Recovering (and clearing) it keeps one unrelated failure
    // from escalating into a second panic on every later access to the store.
    database::hashmap_store::{read_or_recover, write_or_recover},
    database::transactions::Transaction,
    direct_access::repository_factory,
    entities::Entity,
    event::{DirectAccessEntity, EntityEvent, Event, EventBuffer, Origin},
    snapshot::EntityTreeSnapshot,
    types::EntityId,
};

use crate::direct_access::workspace::WorkspaceRelationshipField;
use crate::error::RepositoryError;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum EntityRelationshipField {
    Fields,
    InheritsFrom,
    Relationships,
}

impl Display for EntityRelationshipField {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        write!(f, "{:?}", self)
    }
}

pub trait EntityTable {
    fn create(&mut self, entity: &Entity) -> Result<Entity, RepositoryError>;
    fn create_multi(&mut self, entities: &[Entity]) -> Result<Vec<Entity>, RepositoryError>;
    fn get(&self, id: &EntityId) -> Result<Option<Entity>, RepositoryError>;
    fn get_multi(&self, ids: &[EntityId]) -> Result<Vec<Option<Entity>>, RepositoryError>;
    fn get_all(&self) -> Result<Vec<Entity>, RepositoryError>;
    fn update(&mut self, entity: &Entity) -> Result<Entity, RepositoryError>;
    fn update_multi(&mut self, entities: &[Entity]) -> Result<Vec<Entity>, RepositoryError>;
    fn update_with_relationships(&mut self, entity: &Entity) -> Result<Entity, RepositoryError>;
    fn update_with_relationships_multi(
        &mut self,
        entities: &[Entity],
    ) -> Result<Vec<Entity>, RepositoryError>;
    fn remove(&mut self, id: &EntityId) -> Result<(), RepositoryError>;
    fn remove_multi(&mut self, ids: &[EntityId]) -> Result<(), RepositoryError>;
    fn get_relationship(
        &self,
        id: &EntityId,
        field: &EntityRelationshipField,
    ) -> Result<Vec<EntityId>, RepositoryError>;
    fn get_relationship_many(
        &self,
        ids: &[EntityId],
        field: &EntityRelationshipField,
    ) -> Result<std::collections::HashMap<EntityId, Vec<EntityId>>, RepositoryError>;
    fn get_relationship_count(
        &self,
        id: &EntityId,
        field: &EntityRelationshipField,
    ) -> Result<usize, RepositoryError>;
    fn get_relationship_in_range(
        &self,
        id: &EntityId,
        field: &EntityRelationshipField,
        offset: usize,
        limit: usize,
    ) -> Result<Vec<EntityId>, RepositoryError>;
    fn get_relationships_from_right_ids(
        &self,
        field: &EntityRelationshipField,
        right_ids: &[EntityId],
    ) -> Result<Vec<(EntityId, Vec<EntityId>)>, RepositoryError>;
    fn set_relationship_multi(
        &mut self,
        field: &EntityRelationshipField,
        relationships: Vec<(EntityId, Vec<EntityId>)>,
    ) -> Result<(), RepositoryError>;
    fn set_relationship(
        &mut self,
        id: &EntityId,
        field: &EntityRelationshipField,
        right_ids: &[EntityId],
    ) -> Result<(), RepositoryError>;
    fn move_relationship_ids(
        &mut self,
        id: &EntityId,
        field: &EntityRelationshipField,
        ids_to_move: &[EntityId],
        new_index: i32,
    ) -> Result<Vec<EntityId>, RepositoryError>;
}

pub trait EntityTableRO {
    fn get(&self, id: &EntityId) -> Result<Option<Entity>, RepositoryError>;
    fn get_multi(&self, ids: &[EntityId]) -> Result<Vec<Option<Entity>>, RepositoryError>;
    fn get_all(&self) -> Result<Vec<Entity>, RepositoryError>;
    fn get_relationship(
        &self,
        id: &EntityId,
        field: &EntityRelationshipField,
    ) -> Result<Vec<EntityId>, RepositoryError>;
    fn get_relationship_many(
        &self,
        ids: &[EntityId],
        field: &EntityRelationshipField,
    ) -> Result<std::collections::HashMap<EntityId, Vec<EntityId>>, RepositoryError>;
    fn get_relationship_count(
        &self,
        id: &EntityId,
        field: &EntityRelationshipField,
    ) -> Result<usize, RepositoryError>;
    fn get_relationship_in_range(
        &self,
        id: &EntityId,
        field: &EntityRelationshipField,
        offset: usize,
        limit: usize,
    ) -> Result<Vec<EntityId>, RepositoryError>;
    fn get_relationships_from_right_ids(
        &self,
        field: &EntityRelationshipField,
        right_ids: &[EntityId],
    ) -> Result<Vec<(EntityId, Vec<EntityId>)>, RepositoryError>;
}

pub struct EntityRepository<'a> {
    table: Box<dyn EntityTable + 'a>,
    transaction: &'a Transaction,
}

impl<'a> EntityRepository<'a> {
    pub fn new(table: Box<dyn EntityTable + 'a>, transaction: &'a Transaction) -> Self {
        EntityRepository { table, transaction }
    }

    pub fn create_orphan(
        &mut self,
        event_buffer: &mut EventBuffer,
        entity: &Entity,
    ) -> Result<Entity, RepositoryError> {
        let new = self.table.create(entity)?;
        event_buffer.push(Event {
            origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Created)),
            ids: vec![new.id],
            data: None,
        });
        Ok(new)
    }

    pub fn create_orphan_multi(
        &mut self,
        event_buffer: &mut EventBuffer,
        entities: &[Entity],
    ) -> Result<Vec<Entity>, RepositoryError> {
        let new_entities = self.table.create_multi(entities)?;
        event_buffer.push(Event {
            origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Created)),
            ids: new_entities.iter().map(|e| e.id).collect(),
            data: None,
        });
        Ok(new_entities)
    }
    pub fn create(
        &mut self,
        event_buffer: &mut EventBuffer,
        entity: &Entity,
        owner_id: EntityId,
        index: i32,
    ) -> Result<Entity, RepositoryError> {
        let new = self.table.create(entity)?;
        let created_id = new.id;

        let mut relationship_ids = self.get_relationships_from_owner(&owner_id)?;
        // Insert at index
        if index >= 0 && (index as usize) < relationship_ids.len() {
            relationship_ids.insert(index as usize, created_id);
        } else {
            relationship_ids.push(created_id);
        }

        self.set_relationships_in_owner(event_buffer, &owner_id, &relationship_ids)?;
        event_buffer.push(Event {
            origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Created)),
            ids: vec![created_id],
            data: None,
        });
        Ok(new)
    }

    pub fn create_multi(
        &mut self,
        event_buffer: &mut EventBuffer,
        entities: &[Entity],
        owner_id: EntityId,
        index: i32,
    ) -> Result<Vec<Entity>, RepositoryError> {
        let new_entities = self.table.create_multi(entities)?;
        let created_ids: Vec<EntityId> = new_entities.iter().map(|e| e.id).collect();

        let mut relationship_ids = self.get_relationships_from_owner(&owner_id)?;
        if index >= 0 && (index as usize) < relationship_ids.len() {
            for (i, id) in created_ids.iter().enumerate() {
                relationship_ids.insert(index as usize + i, *id);
            }
        } else {
            relationship_ids.extend(created_ids.iter());
        }

        self.set_relationships_in_owner(event_buffer, &owner_id, &relationship_ids)?;
        event_buffer.push(Event {
            origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Created)),
            ids: created_ids,
            data: None,
        });
        Ok(new_entities)
    }

    pub fn get(&self, id: &EntityId) -> Result<Option<Entity>, RepositoryError> {
        self.table.get(id)
    }
    pub fn get_multi(&self, ids: &[EntityId]) -> Result<Vec<Option<Entity>>, RepositoryError> {
        self.table.get_multi(ids)
    }
    pub fn get_all(&self) -> Result<Vec<Entity>, RepositoryError> {
        self.table.get_all()
    }

    pub fn update(
        &mut self,
        event_buffer: &mut EventBuffer,
        entity: &Entity,
    ) -> Result<Entity, RepositoryError> {
        let updated = self.table.update(entity)?;
        event_buffer.push(Event {
            origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Updated)),
            ids: vec![updated.id],
            data: None,
        });
        Ok(updated)
    }

    pub fn update_multi(
        &mut self,
        event_buffer: &mut EventBuffer,
        entities: &[Entity],
    ) -> Result<Vec<Entity>, RepositoryError> {
        let updated = self.table.update_multi(entities)?;
        event_buffer.push(Event {
            origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Updated)),
            ids: updated.iter().map(|e| e.id).collect(),
            data: None,
        });
        Ok(updated)
    }

    pub fn update_with_relationships(
        &mut self,
        event_buffer: &mut EventBuffer,
        entity: &Entity,
    ) -> Result<Entity, RepositoryError> {
        let updated = self.table.update_with_relationships(entity)?;
        event_buffer.push(Event {
            origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Updated)),
            ids: vec![updated.id],
            data: None,
        });
        Ok(updated)
    }

    pub fn update_with_relationships_multi(
        &mut self,
        event_buffer: &mut EventBuffer,
        entities: &[Entity],
    ) -> Result<Vec<Entity>, RepositoryError> {
        let updated = self.table.update_with_relationships_multi(entities)?;
        event_buffer.push(Event {
            origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Updated)),
            ids: updated.iter().map(|e| e.id).collect(),
            data: None,
        });
        Ok(updated)
    }

    pub fn remove(
        &mut self,
        event_buffer: &mut EventBuffer,
        id: &EntityId,
    ) -> Result<(), RepositoryError> {
        let entity = match self.table.get(id)? {
            Some(e) => e,
            None => return Ok(()),
        };
        // get all strong forward relationship fields

        let fields = entity.fields.clone();
        let relationships = entity.relationships.clone();

        // remove all strong relationships, initiating a cascade remove

        repository_factory::write::create_field_repository(self.transaction)?
            .remove_multi(event_buffer, &fields)?;
        repository_factory::write::create_relationship_repository(self.transaction)?
            .remove_multi(event_buffer, &relationships)?;
        // Before removal, find which owner(s) reference this entity
        let affected_owner_ids: Vec<EntityId> = {
            let owner_repo =
                repository_factory::write::create_workspace_repository(self.transaction)?;
            owner_repo
                .get_relationships_from_right_ids(&WorkspaceRelationshipField::Entities, &[*id])?
                .into_iter()
                .map(|(owner_id, _)| owner_id)
                .collect()
        };
        // Save each owner's current relationship IDs (properly ordered via get_relationships_from_owner)
        let mut owner_rel_before: std::collections::HashMap<EntityId, Vec<EntityId>> =
            std::collections::HashMap::new();
        for owner_id in &affected_owner_ids {
            owner_rel_before.insert(*owner_id, self.get_relationships_from_owner(owner_id)?);
        }

        // remove entity
        self.table.remove(id)?;
        event_buffer.push(Event {
            origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Removed)),
            ids: vec![*id],
            data: None,
        });
        // Update each affected owner's relationship to exclude removed ID (emits Updated event)
        for owner_id in &affected_owner_ids {
            if let Some(rel_ids) = owner_rel_before.get(owner_id) {
                let updated: Vec<EntityId> =
                    rel_ids.iter().copied().filter(|rid| *rid != *id).collect();
                self.set_relationships_in_owner(event_buffer, owner_id, &updated)?;
            }
        }

        Ok(())
    }

    pub fn remove_multi(
        &mut self,
        event_buffer: &mut EventBuffer,
        ids: &[EntityId],
    ) -> Result<(), RepositoryError> {
        let entities = self.table.get_multi(ids)?;
        if entities.is_empty() || entities.iter().all(|e| e.is_none()) {
            return Ok(());
        }

        // get all strong forward relationship fields

        let mut fields_ids: Vec<EntityId> = entities
            .iter()
            .flat_map(|entity| entity.as_ref().map(|entity| entity.fields.clone()))
            .flatten()
            .collect();
        // remove duplicates
        fields_ids.sort();
        fields_ids.dedup();
        let mut relationships_ids: Vec<EntityId> = entities
            .iter()
            .flat_map(|entity| entity.as_ref().map(|entity| entity.relationships.clone()))
            .flatten()
            .collect();
        // remove duplicates
        relationships_ids.sort();
        relationships_ids.dedup();

        // remove all strong relationships, initiating a cascade remove

        repository_factory::write::create_field_repository(self.transaction)?
            .remove_multi(event_buffer, &fields_ids)?;
        repository_factory::write::create_relationship_repository(self.transaction)?
            .remove_multi(event_buffer, &relationships_ids)?;
        // Before removal, find which owner(s) reference these entities
        let affected_owner_ids: Vec<EntityId> = {
            let owner_repo =
                repository_factory::write::create_workspace_repository(self.transaction)?;
            owner_repo
                .get_relationships_from_right_ids(&WorkspaceRelationshipField::Entities, ids)?
                .into_iter()
                .map(|(owner_id, _)| owner_id)
                .collect()
        };
        // Save each owner's current relationship IDs (properly ordered via get_relationships_from_owner)
        let mut owner_rel_before: std::collections::HashMap<EntityId, Vec<EntityId>> =
            std::collections::HashMap::new();
        for owner_id in &affected_owner_ids {
            owner_rel_before.insert(*owner_id, self.get_relationships_from_owner(owner_id)?);
        }

        self.table.remove_multi(ids)?;
        event_buffer.push(Event {
            origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Removed)),
            ids: ids.into(),
            data: None,
        });
        // Update each affected owner's relationship to exclude removed IDs (emits Updated event)
        {
            let removed_set: std::collections::HashSet<EntityId> = ids.iter().copied().collect();
            for owner_id in &affected_owner_ids {
                if let Some(rel_ids) = owner_rel_before.get(owner_id) {
                    let updated: Vec<EntityId> = rel_ids
                        .iter()
                        .copied()
                        .filter(|rid| !removed_set.contains(rid))
                        .collect();
                    self.set_relationships_in_owner(event_buffer, owner_id, &updated)?;
                }
            }
        }

        Ok(())
    }
    pub fn get_relationship(
        &self,
        id: &EntityId,
        field: &EntityRelationshipField,
    ) -> Result<Vec<EntityId>, RepositoryError> {
        self.table.get_relationship(id, field)
    }
    pub fn get_relationship_many(
        &self,
        ids: &[EntityId],
        field: &EntityRelationshipField,
    ) -> Result<std::collections::HashMap<EntityId, Vec<EntityId>>, RepositoryError> {
        self.table.get_relationship_many(ids, field)
    }
    pub fn get_relationship_count(
        &self,
        id: &EntityId,
        field: &EntityRelationshipField,
    ) -> Result<usize, RepositoryError> {
        self.table.get_relationship_count(id, field)
    }
    pub fn get_relationship_in_range(
        &self,
        id: &EntityId,
        field: &EntityRelationshipField,
        offset: usize,
        limit: usize,
    ) -> Result<Vec<EntityId>, RepositoryError> {
        self.table
            .get_relationship_in_range(id, field, offset, limit)
    }
    pub fn get_relationships_from_right_ids(
        &self,
        field: &EntityRelationshipField,
        right_ids: &[EntityId],
    ) -> Result<Vec<(EntityId, Vec<EntityId>)>, RepositoryError> {
        self.table
            .get_relationships_from_right_ids(field, right_ids)
    }

    pub fn set_relationship_multi(
        &mut self,
        event_buffer: &mut EventBuffer,
        field: &EntityRelationshipField,
        relationships: Vec<(EntityId, Vec<EntityId>)>,
    ) -> Result<(), RepositoryError> {
        // Validate that all right_ids exist
        let all_right_ids: Vec<EntityId> = relationships
            .iter()
            .flat_map(|(_, ids)| ids.iter().copied())
            .collect();
        if !all_right_ids.is_empty() {
            match field {
                EntityRelationshipField::Fields => {
                    let child_repo =
                        repository_factory::write::create_field_repository(self.transaction)?;
                    let found = child_repo.get_multi(&all_right_ids)?;
                    let missing: Vec<_> = all_right_ids
                        .iter()
                        .zip(found.iter())
                        .filter(|(_, entity)| entity.is_none())
                        .map(|(id, _)| *id)
                        .collect();
                    if !missing.is_empty() {
                        return Err(RepositoryError::MissingRelationshipTarget {
                            operation: "set_relationship_multi",
                            ids: missing,
                        });
                    }
                }
                EntityRelationshipField::InheritsFrom => {
                    let child_repo =
                        repository_factory::write::create_entity_repository(self.transaction)?;
                    let found = child_repo.get_multi(&all_right_ids)?;
                    let missing: Vec<_> = all_right_ids
                        .iter()
                        .zip(found.iter())
                        .filter(|(_, entity)| entity.is_none())
                        .map(|(id, _)| *id)
                        .collect();
                    if !missing.is_empty() {
                        return Err(RepositoryError::MissingRelationshipTarget {
                            operation: "set_relationship_multi",
                            ids: missing,
                        });
                    }
                }
                EntityRelationshipField::Relationships => {
                    let child_repo = repository_factory::write::create_relationship_repository(
                        self.transaction,
                    )?;
                    let found = child_repo.get_multi(&all_right_ids)?;
                    let missing: Vec<_> = all_right_ids
                        .iter()
                        .zip(found.iter())
                        .filter(|(_, entity)| entity.is_none())
                        .map(|(id, _)| *id)
                        .collect();
                    if !missing.is_empty() {
                        return Err(RepositoryError::MissingRelationshipTarget {
                            operation: "set_relationship_multi",
                            ids: missing,
                        });
                    }
                }
            }
        }
        self.table
            .set_relationship_multi(field, relationships.clone())?;
        for (left_id, right_ids) in relationships {
            event_buffer.push(Event {
                origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Updated)),
                ids: vec![left_id],
                data: Some(format!(
                    "{}:{}",
                    field,
                    right_ids
                        .iter()
                        .map(|id| id.to_string())
                        .collect::<Vec<_>>()
                        .join(",")
                )),
            });
        }
        Ok(())
    }

    pub fn set_relationship(
        &mut self,
        event_buffer: &mut EventBuffer,
        id: &EntityId,
        field: &EntityRelationshipField,
        right_ids: &[EntityId],
    ) -> Result<(), RepositoryError> {
        // Validate that all right_ids exist
        if !right_ids.is_empty() {
            match field {
                EntityRelationshipField::Fields => {
                    let child_repo =
                        repository_factory::write::create_field_repository(self.transaction)?;
                    let found = child_repo.get_multi(right_ids)?;
                    let missing: Vec<_> = right_ids
                        .iter()
                        .zip(found.iter())
                        .filter(|(_, entity)| entity.is_none())
                        .map(|(id, _)| *id)
                        .collect();
                    if !missing.is_empty() {
                        return Err(RepositoryError::MissingRelationshipTarget {
                            operation: "set_relationship",
                            ids: missing,
                        });
                    }
                }
                EntityRelationshipField::InheritsFrom => {
                    let child_repo =
                        repository_factory::write::create_entity_repository(self.transaction)?;
                    let found = child_repo.get_multi(right_ids)?;
                    let missing: Vec<_> = right_ids
                        .iter()
                        .zip(found.iter())
                        .filter(|(_, entity)| entity.is_none())
                        .map(|(id, _)| *id)
                        .collect();
                    if !missing.is_empty() {
                        return Err(RepositoryError::MissingRelationshipTarget {
                            operation: "set_relationship",
                            ids: missing,
                        });
                    }
                }
                EntityRelationshipField::Relationships => {
                    let child_repo = repository_factory::write::create_relationship_repository(
                        self.transaction,
                    )?;
                    let found = child_repo.get_multi(right_ids)?;
                    let missing: Vec<_> = right_ids
                        .iter()
                        .zip(found.iter())
                        .filter(|(_, entity)| entity.is_none())
                        .map(|(id, _)| *id)
                        .collect();
                    if !missing.is_empty() {
                        return Err(RepositoryError::MissingRelationshipTarget {
                            operation: "set_relationship",
                            ids: missing,
                        });
                    }
                }
            }
        }
        self.table.set_relationship(id, field, right_ids)?;
        event_buffer.push(Event {
            origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Updated)),
            ids: vec![*id],
            data: Some(format!(
                "{}:{}",
                field,
                right_ids
                    .iter()
                    .map(|id| id.to_string())
                    .collect::<Vec<_>>()
                    .join(",")
            )),
        });
        Ok(())
    }

    pub fn move_relationship_ids(
        &mut self,
        event_buffer: &mut EventBuffer,
        id: &EntityId,
        field: &EntityRelationshipField,
        ids_to_move: &[EntityId],
        new_index: i32,
    ) -> Result<Vec<EntityId>, RepositoryError> {
        let reordered = self
            .table
            .move_relationship_ids(id, field, ids_to_move, new_index)?;
        event_buffer.push(Event {
            origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Updated)),
            ids: vec![*id],
            data: Some(format!(
                "{}:{}",
                field,
                reordered
                    .iter()
                    .map(|id| id.to_string())
                    .collect::<Vec<_>>()
                    .join(",")
            )),
        });
        Ok(reordered)
    }
    pub fn get_relationships_from_owner(
        &self,
        owner_id: &EntityId,
    ) -> Result<Vec<EntityId>, RepositoryError> {
        let repo = repository_factory::write::create_workspace_repository(self.transaction)?;
        repo.get_relationship(owner_id, &WorkspaceRelationshipField::Entities)
    }

    pub fn set_relationships_in_owner(
        &mut self,
        event_buffer: &mut EventBuffer,
        owner_id: &EntityId,
        ids: &[EntityId],
    ) -> Result<(), RepositoryError> {
        let mut repo = repository_factory::write::create_workspace_repository(self.transaction)?;
        repo.set_relationship(
            event_buffer,
            owner_id,
            &WorkspaceRelationshipField::Entities,
            ids,
        )
    }

    pub fn snapshot(&self, ids: &[EntityId]) -> Result<EntityTreeSnapshot, RepositoryError> {
        // O(1) whole-store capture (im::HashMap structural sharing). Restore is scoped to `ids`.
        let store_snap = self.transaction.snapshot_store();
        Ok(EntityTreeSnapshot {
            store_snapshot: Some(store_snap),
            root_ids: ids.to_vec(),
        })
    }

    pub fn restore(
        &mut self,
        event_buffer: &mut EventBuffer,
        snap: &EntityTreeSnapshot,
    ) -> Result<(), RepositoryError> {
        let store_snap = snap
            .store_snapshot
            .as_ref()
            .ok_or_else(|| RepositoryError::Serialization("missing store snapshot".into()))?;
        let snap_store = store_snap
            .downcast_ref::<HashMapStoreSnapshot>()
            .ok_or_else(|| RepositoryError::Serialization("snapshot type mismatch".into()))?;

        // Scoped restore: walk the subtree rooted at the captured ids (strong relationships only),
        // in both the snapshot and the live store, and reconcile only it.
        let mut visited = std::collections::HashSet::new();
        self.restore_subtree(event_buffer, snap_store, &snap.root_ids, &mut visited)?;

        // Surgically reconcile the root ids' placement in their (external) strong owner,
        // preserving sibling edits made on other undo stacks.
        self.reconcile_backref_workspace_entities(event_buffer, snap_store, &snap.root_ids)?;

        Ok(())
    }

    /// Restore the subtree rooted at `ids` (of this entity type) to the snapshot state, recursing
    /// into strong children. Touches only the subtree: in-scope rows and the forward junctions they
    /// own are restored wholesale; external referrers are reconciled surgically; everything else
    /// (other trunks, non-undoable data) is left untouched. `visited` guards against cycles.
    pub(crate) fn restore_subtree(
        &self,
        event_buffer: &mut EventBuffer,
        snap: &HashMapStoreSnapshot,
        ids: &[EntityId],
        // Keyed by (entity type, id): EntityIds are per-type, not globally unique, so a bare
        // id set would let one entity type's id falsely mask another's.
        visited: &mut std::collections::HashSet<(&'static str, EntityId)>,
    ) -> Result<(), RepositoryError> {
        let ids: Vec<EntityId> = ids
            .iter()
            .copied()
            .filter(|id| visited.insert(("entity", *id)))
            .collect();
        if ids.is_empty() {
            return Ok(());
        }

        let store = self.transaction.get_store();

        // Three-way partition by presence in snapshot vs live store (read before mutating).
        let mut to_create: Vec<EntityId> = Vec::new(); // in snapshot, gone from live -> re-add
        let mut to_update: Vec<EntityId> = Vec::new(); // in both                    -> revert
        let mut to_delete: Vec<EntityId> = Vec::new(); // live only (created after)  -> delete
        {
            let live = read_or_recover(&store.entities);
            for id in &ids {
                match (snap.entities.contains_key(id), live.contains_key(id)) {
                    (true, false) => to_create.push(*id),
                    (true, true) => to_update.push(*id),
                    (false, true) => to_delete.push(*id),
                    (false, false) => {}
                }
            }
        }

        // 1. Recurse into strong children first (collect child ids from snapshot + live, then drop
        //    all locks before recursing so self-referential ownership cannot deadlock).
        {
            let mut child_ids: Vec<EntityId> = Vec::new();
            for id in to_create.iter().chain(to_update.iter()) {
                if let Some(list) = snap.jn_field_from_entity_fields.get(id) {
                    child_ids.extend(list.iter().copied());
                }
            }
            {
                let live_jn = read_or_recover(&store.jn_field_from_entity_fields);
                for id in &ids {
                    if let Some(list) = live_jn.get(id) {
                        child_ids.extend(list.iter().copied());
                    }
                }
            }
            child_ids.sort();
            child_ids.dedup();
            if !child_ids.is_empty() {
                repository_factory::write::create_field_repository(self.transaction)?
                    .restore_subtree(event_buffer, snap, &child_ids, visited)?;
            }
        }
        {
            let mut child_ids: Vec<EntityId> = Vec::new();
            for id in to_create.iter().chain(to_update.iter()) {
                if let Some(list) = snap.jn_relationship_from_entity_relationships.get(id) {
                    child_ids.extend(list.iter().copied());
                }
            }
            {
                let live_jn = read_or_recover(&store.jn_relationship_from_entity_relationships);
                for id in &ids {
                    if let Some(list) = live_jn.get(id) {
                        child_ids.extend(list.iter().copied());
                    }
                }
            }
            child_ids.sort();
            child_ids.dedup();
            if !child_ids.is_empty() {
                repository_factory::write::create_relationship_repository(self.transaction)?
                    .restore_subtree(event_buffer, snap, &child_ids, visited)?;
            }
        }

        // 2. Entity rows: revert/re-add from snapshot, delete the ones created after it.
        {
            let mut live = write_or_recover(&store.entities);
            for id in to_create.iter().chain(to_update.iter()) {
                if let Some(row) = snap.entities.get(id) {
                    live.insert(*id, row.clone());
                }
            }
            for id in &to_delete {
                live.remove(id);
            }
        }

        // 3. This entity's own forward junctions (strong + weak): restored wholesale because the
        //    junction key is in-scope (owned exclusively by this trunk).
        {
            let mut live_jn = write_or_recover(&store.jn_field_from_entity_fields);
            for id in to_create.iter().chain(to_update.iter()) {
                match snap.jn_field_from_entity_fields.get(id) {
                    Some(v) => {
                        live_jn.insert(*id, v.clone());
                    }
                    None => {
                        live_jn.remove(id);
                    }
                }
            }
            for id in &to_delete {
                live_jn.remove(id);
            }
        }
        {
            let mut live_jn = write_or_recover(&store.jn_entity_from_entity_inherits_from);
            for id in to_create.iter().chain(to_update.iter()) {
                match snap.jn_entity_from_entity_inherits_from.get(id) {
                    Some(v) => {
                        live_jn.insert(*id, v.clone());
                    }
                    None => {
                        live_jn.remove(id);
                    }
                }
            }
            for id in &to_delete {
                live_jn.remove(id);
            }
        }
        {
            let mut live_jn = write_or_recover(&store.jn_relationship_from_entity_relationships);
            for id in to_create.iter().chain(to_update.iter()) {
                match snap.jn_relationship_from_entity_relationships.get(id) {
                    Some(v) => {
                        live_jn.insert(*id, v.clone());
                    }
                    None => {
                        live_jn.remove(id);
                    }
                }
            }
            for id in &to_delete {
                live_jn.remove(id);
            }
        }

        // 4. External weak referrers of these ids: reconcile surgically (membership only).
        self.reconcile_backref_use_case_entities(event_buffer, snap, &ids)?;
        self.reconcile_backref_field_entity(event_buffer, snap, &ids)?;
        self.reconcile_backref_file_entity(event_buffer, snap, &ids)?;
        self.reconcile_backref_entity_inherits_from(event_buffer, snap, &ids)?;
        self.reconcile_backref_relationship_left_entity(event_buffer, snap, &ids)?;
        self.reconcile_backref_relationship_right_entity(event_buffer, snap, &ids)?;

        // 5. Events: precise per-id (Created/Updated/Removed), not a whole-store storm.
        if !to_create.is_empty() {
            event_buffer.push(Event {
                origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Created)),
                ids: to_create.clone(),
                data: None,
            });
            event_buffer.push(Event {
                origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Updated)),
                ids: to_create.clone(),
                data: None,
            });
        }
        if !to_update.is_empty() {
            event_buffer.push(Event {
                origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Updated)),
                ids: to_update.clone(),
                data: None,
            });
        }
        if !to_delete.is_empty() {
            event_buffer.push(Event {
                origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Removed)),
                ids: to_delete.clone(),
                data: None,
            });
        }

        Ok(())
    }

    /// Surgically reconcile one external referrer junction (out-of-scope key -> in-scope values):
    /// `use_case.entities`.
    fn reconcile_backref_use_case_entities(
        &self,
        event_buffer: &mut EventBuffer,
        snap: &HashMapStoreSnapshot,
        scope_ids: &[EntityId],
    ) -> Result<(), RepositoryError> {
        let scope: std::collections::HashSet<EntityId> = scope_ids.iter().copied().collect();
        if scope.is_empty() {
            return Ok(());
        }
        let store = self.transaction.get_store();

        // External left keys whose ordered list references any scope id, in snapshot or live.
        let mut left_keys: std::collections::HashSet<EntityId> = std::collections::HashSet::new();
        for (left, rights) in snap.jn_entity_from_use_case_entities.iter() {
            if rights.iter().any(|rid| scope.contains(rid)) {
                left_keys.insert(*left);
            }
        }
        {
            let live_jn = read_or_recover(&store.jn_entity_from_use_case_entities);
            for (left, rights) in live_jn.iter() {
                if rights.iter().any(|rid| scope.contains(rid)) {
                    left_keys.insert(*left);
                }
            }
        }

        for left in left_keys {
            let snap_list: Vec<EntityId> = snap
                .jn_entity_from_use_case_entities
                .get(&left)
                .cloned()
                .unwrap_or_default();
            let new_list = {
                let live_jn = read_or_recover(&store.jn_entity_from_use_case_entities);
                let live_list: Vec<EntityId> = live_jn.get(&left).cloned().unwrap_or_default();
                let reconciled = crate::database::hashmap_store::reconcile_backref_list(
                    &live_list, &snap_list, &scope,
                );
                if reconciled == live_list {
                    None
                } else {
                    Some(reconciled)
                }
            };
            if let Some(reconciled) = new_list {
                write_or_recover(&store.jn_entity_from_use_case_entities).insert(left, reconciled);
                event_buffer.push(Event {
                    origin: Origin::DirectAccess(DirectAccessEntity::UseCase(EntityEvent::Updated)),
                    ids: vec![left],
                    data: None,
                });
            }
        }
        Ok(())
    }

    /// Surgically reconcile one external referrer junction (out-of-scope key -> in-scope values):
    /// `workspace.entities`.
    fn reconcile_backref_workspace_entities(
        &self,
        event_buffer: &mut EventBuffer,
        snap: &HashMapStoreSnapshot,
        scope_ids: &[EntityId],
    ) -> Result<(), RepositoryError> {
        let scope: std::collections::HashSet<EntityId> = scope_ids.iter().copied().collect();
        if scope.is_empty() {
            return Ok(());
        }
        let store = self.transaction.get_store();

        // External left keys whose ordered list references any scope id, in snapshot or live.
        let mut left_keys: std::collections::HashSet<EntityId> = std::collections::HashSet::new();
        for (left, rights) in snap.jn_entity_from_workspace_entities.iter() {
            if rights.iter().any(|rid| scope.contains(rid)) {
                left_keys.insert(*left);
            }
        }
        {
            let live_jn = read_or_recover(&store.jn_entity_from_workspace_entities);
            for (left, rights) in live_jn.iter() {
                if rights.iter().any(|rid| scope.contains(rid)) {
                    left_keys.insert(*left);
                }
            }
        }

        for left in left_keys {
            let snap_list: Vec<EntityId> = snap
                .jn_entity_from_workspace_entities
                .get(&left)
                .cloned()
                .unwrap_or_default();
            let new_list = {
                let live_jn = read_or_recover(&store.jn_entity_from_workspace_entities);
                let live_list: Vec<EntityId> = live_jn.get(&left).cloned().unwrap_or_default();
                let reconciled = crate::database::hashmap_store::reconcile_backref_list(
                    &live_list, &snap_list, &scope,
                );
                if reconciled == live_list {
                    None
                } else {
                    Some(reconciled)
                }
            };
            if let Some(reconciled) = new_list {
                write_or_recover(&store.jn_entity_from_workspace_entities).insert(left, reconciled);
                event_buffer.push(Event {
                    origin: Origin::DirectAccess(DirectAccessEntity::Workspace(
                        EntityEvent::Updated,
                    )),
                    ids: vec![left],
                    data: None,
                });
            }
        }
        Ok(())
    }

    /// Surgically reconcile one external referrer junction (out-of-scope key -> in-scope values):
    /// `field.entity`.
    fn reconcile_backref_field_entity(
        &self,
        event_buffer: &mut EventBuffer,
        snap: &HashMapStoreSnapshot,
        scope_ids: &[EntityId],
    ) -> Result<(), RepositoryError> {
        let scope: std::collections::HashSet<EntityId> = scope_ids.iter().copied().collect();
        if scope.is_empty() {
            return Ok(());
        }
        let store = self.transaction.get_store();

        // External left keys whose ordered list references any scope id, in snapshot or live.
        let mut left_keys: std::collections::HashSet<EntityId> = std::collections::HashSet::new();
        for (left, rights) in snap.jn_entity_from_field_entity.iter() {
            if rights.iter().any(|rid| scope.contains(rid)) {
                left_keys.insert(*left);
            }
        }
        {
            let live_jn = read_or_recover(&store.jn_entity_from_field_entity);
            for (left, rights) in live_jn.iter() {
                if rights.iter().any(|rid| scope.contains(rid)) {
                    left_keys.insert(*left);
                }
            }
        }

        for left in left_keys {
            let snap_list: Vec<EntityId> = snap
                .jn_entity_from_field_entity
                .get(&left)
                .cloned()
                .unwrap_or_default();
            let new_list = {
                let live_jn = read_or_recover(&store.jn_entity_from_field_entity);
                let live_list: Vec<EntityId> = live_jn.get(&left).cloned().unwrap_or_default();
                let reconciled = crate::database::hashmap_store::reconcile_backref_list(
                    &live_list, &snap_list, &scope,
                );
                if reconciled == live_list {
                    None
                } else {
                    Some(reconciled)
                }
            };
            if let Some(reconciled) = new_list {
                write_or_recover(&store.jn_entity_from_field_entity).insert(left, reconciled);
                event_buffer.push(Event {
                    origin: Origin::DirectAccess(DirectAccessEntity::Field(EntityEvent::Updated)),
                    ids: vec![left],
                    data: None,
                });
            }
        }
        Ok(())
    }

    /// Surgically reconcile one external referrer junction (out-of-scope key -> in-scope values):
    /// `file.entity`.
    fn reconcile_backref_file_entity(
        &self,
        event_buffer: &mut EventBuffer,
        snap: &HashMapStoreSnapshot,
        scope_ids: &[EntityId],
    ) -> Result<(), RepositoryError> {
        let scope: std::collections::HashSet<EntityId> = scope_ids.iter().copied().collect();
        if scope.is_empty() {
            return Ok(());
        }
        let store = self.transaction.get_store();

        // External left keys whose ordered list references any scope id, in snapshot or live.
        let mut left_keys: std::collections::HashSet<EntityId> = std::collections::HashSet::new();
        for (left, rights) in snap.jn_entity_from_file_entity.iter() {
            if rights.iter().any(|rid| scope.contains(rid)) {
                left_keys.insert(*left);
            }
        }
        {
            let live_jn = read_or_recover(&store.jn_entity_from_file_entity);
            for (left, rights) in live_jn.iter() {
                if rights.iter().any(|rid| scope.contains(rid)) {
                    left_keys.insert(*left);
                }
            }
        }

        for left in left_keys {
            let snap_list: Vec<EntityId> = snap
                .jn_entity_from_file_entity
                .get(&left)
                .cloned()
                .unwrap_or_default();
            let new_list = {
                let live_jn = read_or_recover(&store.jn_entity_from_file_entity);
                let live_list: Vec<EntityId> = live_jn.get(&left).cloned().unwrap_or_default();
                let reconciled = crate::database::hashmap_store::reconcile_backref_list(
                    &live_list, &snap_list, &scope,
                );
                if reconciled == live_list {
                    None
                } else {
                    Some(reconciled)
                }
            };
            if let Some(reconciled) = new_list {
                write_or_recover(&store.jn_entity_from_file_entity).insert(left, reconciled);
                event_buffer.push(Event {
                    origin: Origin::DirectAccess(DirectAccessEntity::File(EntityEvent::Updated)),
                    ids: vec![left],
                    data: None,
                });
            }
        }
        Ok(())
    }

    /// Surgically reconcile one external referrer junction (out-of-scope key -> in-scope values):
    /// `entity.inherits_from`.
    fn reconcile_backref_entity_inherits_from(
        &self,
        event_buffer: &mut EventBuffer,
        snap: &HashMapStoreSnapshot,
        scope_ids: &[EntityId],
    ) -> Result<(), RepositoryError> {
        let scope: std::collections::HashSet<EntityId> = scope_ids.iter().copied().collect();
        if scope.is_empty() {
            return Ok(());
        }
        let store = self.transaction.get_store();

        // External left keys whose ordered list references any scope id, in snapshot or live.
        let mut left_keys: std::collections::HashSet<EntityId> = std::collections::HashSet::new();
        for (left, rights) in snap.jn_entity_from_entity_inherits_from.iter() {
            if rights.iter().any(|rid| scope.contains(rid)) {
                left_keys.insert(*left);
            }
        }
        {
            let live_jn = read_or_recover(&store.jn_entity_from_entity_inherits_from);
            for (left, rights) in live_jn.iter() {
                if rights.iter().any(|rid| scope.contains(rid)) {
                    left_keys.insert(*left);
                }
            }
        }

        for left in left_keys {
            let snap_list: Vec<EntityId> = snap
                .jn_entity_from_entity_inherits_from
                .get(&left)
                .cloned()
                .unwrap_or_default();
            let new_list = {
                let live_jn = read_or_recover(&store.jn_entity_from_entity_inherits_from);
                let live_list: Vec<EntityId> = live_jn.get(&left).cloned().unwrap_or_default();
                let reconciled = crate::database::hashmap_store::reconcile_backref_list(
                    &live_list, &snap_list, &scope,
                );
                if reconciled == live_list {
                    None
                } else {
                    Some(reconciled)
                }
            };
            if let Some(reconciled) = new_list {
                write_or_recover(&store.jn_entity_from_entity_inherits_from)
                    .insert(left, reconciled);
                event_buffer.push(Event {
                    origin: Origin::DirectAccess(DirectAccessEntity::Entity(EntityEvent::Updated)),
                    ids: vec![left],
                    data: None,
                });
            }
        }
        Ok(())
    }

    /// Surgically reconcile one external referrer junction (out-of-scope key -> in-scope values):
    /// `relationship.left_entity`.
    fn reconcile_backref_relationship_left_entity(
        &self,
        event_buffer: &mut EventBuffer,
        snap: &HashMapStoreSnapshot,
        scope_ids: &[EntityId],
    ) -> Result<(), RepositoryError> {
        let scope: std::collections::HashSet<EntityId> = scope_ids.iter().copied().collect();
        if scope.is_empty() {
            return Ok(());
        }
        let store = self.transaction.get_store();

        // External left keys whose ordered list references any scope id, in snapshot or live.
        let mut left_keys: std::collections::HashSet<EntityId> = std::collections::HashSet::new();
        for (left, rights) in snap.jn_entity_from_relationship_left_entity.iter() {
            if rights.iter().any(|rid| scope.contains(rid)) {
                left_keys.insert(*left);
            }
        }
        {
            let live_jn = read_or_recover(&store.jn_entity_from_relationship_left_entity);
            for (left, rights) in live_jn.iter() {
                if rights.iter().any(|rid| scope.contains(rid)) {
                    left_keys.insert(*left);
                }
            }
        }

        for left in left_keys {
            let snap_list: Vec<EntityId> = snap
                .jn_entity_from_relationship_left_entity
                .get(&left)
                .cloned()
                .unwrap_or_default();
            let new_list = {
                let live_jn = read_or_recover(&store.jn_entity_from_relationship_left_entity);
                let live_list: Vec<EntityId> = live_jn.get(&left).cloned().unwrap_or_default();
                let reconciled = crate::database::hashmap_store::reconcile_backref_list(
                    &live_list, &snap_list, &scope,
                );
                if reconciled == live_list {
                    None
                } else {
                    Some(reconciled)
                }
            };
            if let Some(reconciled) = new_list {
                write_or_recover(&store.jn_entity_from_relationship_left_entity)
                    .insert(left, reconciled);
                event_buffer.push(Event {
                    origin: Origin::DirectAccess(DirectAccessEntity::Relationship(
                        EntityEvent::Updated,
                    )),
                    ids: vec![left],
                    data: None,
                });
            }
        }
        Ok(())
    }

    /// Surgically reconcile one external referrer junction (out-of-scope key -> in-scope values):
    /// `relationship.right_entity`.
    fn reconcile_backref_relationship_right_entity(
        &self,
        event_buffer: &mut EventBuffer,
        snap: &HashMapStoreSnapshot,
        scope_ids: &[EntityId],
    ) -> Result<(), RepositoryError> {
        let scope: std::collections::HashSet<EntityId> = scope_ids.iter().copied().collect();
        if scope.is_empty() {
            return Ok(());
        }
        let store = self.transaction.get_store();

        // External left keys whose ordered list references any scope id, in snapshot or live.
        let mut left_keys: std::collections::HashSet<EntityId> = std::collections::HashSet::new();
        for (left, rights) in snap.jn_entity_from_relationship_right_entity.iter() {
            if rights.iter().any(|rid| scope.contains(rid)) {
                left_keys.insert(*left);
            }
        }
        {
            let live_jn = read_or_recover(&store.jn_entity_from_relationship_right_entity);
            for (left, rights) in live_jn.iter() {
                if rights.iter().any(|rid| scope.contains(rid)) {
                    left_keys.insert(*left);
                }
            }
        }

        for left in left_keys {
            let snap_list: Vec<EntityId> = snap
                .jn_entity_from_relationship_right_entity
                .get(&left)
                .cloned()
                .unwrap_or_default();
            let new_list = {
                let live_jn = read_or_recover(&store.jn_entity_from_relationship_right_entity);
                let live_list: Vec<EntityId> = live_jn.get(&left).cloned().unwrap_or_default();
                let reconciled = crate::database::hashmap_store::reconcile_backref_list(
                    &live_list, &snap_list, &scope,
                );
                if reconciled == live_list {
                    None
                } else {
                    Some(reconciled)
                }
            };
            if let Some(reconciled) = new_list {
                write_or_recover(&store.jn_entity_from_relationship_right_entity)
                    .insert(left, reconciled);
                event_buffer.push(Event {
                    origin: Origin::DirectAccess(DirectAccessEntity::Relationship(
                        EntityEvent::Updated,
                    )),
                    ids: vec![left],
                    data: None,
                });
            }
        }
        Ok(())
    }
}

pub struct EntityRepositoryRO<'a> {
    table: Box<dyn EntityTableRO + 'a>,
}
impl<'a> EntityRepositoryRO<'a> {
    pub fn new(table: Box<dyn EntityTableRO + 'a>) -> Self {
        EntityRepositoryRO { table }
    }
    pub fn get(&self, id: &EntityId) -> Result<Option<Entity>, RepositoryError> {
        self.table.get(id)
    }
    pub fn get_multi(&self, ids: &[EntityId]) -> Result<Vec<Option<Entity>>, RepositoryError> {
        self.table.get_multi(ids)
    }
    pub fn get_all(&self) -> Result<Vec<Entity>, RepositoryError> {
        self.table.get_all()
    }
    pub fn get_relationship(
        &self,
        id: &EntityId,
        field: &EntityRelationshipField,
    ) -> Result<Vec<EntityId>, RepositoryError> {
        self.table.get_relationship(id, field)
    }
    pub fn get_relationship_many(
        &self,
        ids: &[EntityId],
        field: &EntityRelationshipField,
    ) -> Result<std::collections::HashMap<EntityId, Vec<EntityId>>, RepositoryError> {
        self.table.get_relationship_many(ids, field)
    }
    pub fn get_relationship_count(
        &self,
        id: &EntityId,
        field: &EntityRelationshipField,
    ) -> Result<usize, RepositoryError> {
        self.table.get_relationship_count(id, field)
    }
    pub fn get_relationship_in_range(
        &self,
        id: &EntityId,
        field: &EntityRelationshipField,
        offset: usize,
        limit: usize,
    ) -> Result<Vec<EntityId>, RepositoryError> {
        self.table
            .get_relationship_in_range(id, field, offset, limit)
    }
    pub fn get_relationships_from_right_ids(
        &self,
        field: &EntityRelationshipField,
        right_ids: &[EntityId],
    ) -> Result<Vec<(EntityId, Vec<EntityId>)>, RepositoryError> {
        self.table
            .get_relationships_from_right_ids(field, right_ids)
    }
}