common/direct_access/file/

file_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::File,
    event::{DirectAccessEntity, EntityEvent, Event, EventBuffer, Origin},
    snapshot::EntityTreeSnapshot,
    types::EntityId,
};

use crate::direct_access::system::SystemRelationshipField;
use crate::error::RepositoryError;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum FileRelationshipField {
    Entity,
    Feature,
    Field,
    UseCase,
}

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

pub trait FileTable {
    fn create(&mut self, entity: &File) -> Result<File, RepositoryError>;
    fn create_multi(&mut self, entities: &[File]) -> Result<Vec<File>, RepositoryError>;
    fn get(&self, id: &EntityId) -> Result<Option<File>, RepositoryError>;
    fn get_multi(&self, ids: &[EntityId]) -> Result<Vec<Option<File>>, RepositoryError>;
    fn get_all(&self) -> Result<Vec<File>, RepositoryError>;
    fn update(&mut self, entity: &File) -> Result<File, RepositoryError>;
    fn update_multi(&mut self, entities: &[File]) -> Result<Vec<File>, RepositoryError>;
    fn update_with_relationships(&mut self, entity: &File) -> Result<File, RepositoryError>;
    fn update_with_relationships_multi(
        &mut self,
        entities: &[File],
    ) -> Result<Vec<File>, 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: &FileRelationshipField,
    ) -> Result<Vec<EntityId>, RepositoryError>;
    fn get_relationship_many(
        &self,
        ids: &[EntityId],
        field: &FileRelationshipField,
    ) -> Result<std::collections::HashMap<EntityId, Vec<EntityId>>, RepositoryError>;
    fn get_relationship_count(
        &self,
        id: &EntityId,
        field: &FileRelationshipField,
    ) -> Result<usize, RepositoryError>;
    fn get_relationship_in_range(
        &self,
        id: &EntityId,
        field: &FileRelationshipField,
        offset: usize,
        limit: usize,
    ) -> Result<Vec<EntityId>, RepositoryError>;
    fn get_relationships_from_right_ids(
        &self,
        field: &FileRelationshipField,
        right_ids: &[EntityId],
    ) -> Result<Vec<(EntityId, Vec<EntityId>)>, RepositoryError>;
    fn set_relationship_multi(
        &mut self,
        field: &FileRelationshipField,
        relationships: Vec<(EntityId, Vec<EntityId>)>,
    ) -> Result<(), RepositoryError>;
    fn set_relationship(
        &mut self,
        id: &EntityId,
        field: &FileRelationshipField,
        right_ids: &[EntityId],
    ) -> Result<(), RepositoryError>;
    fn move_relationship_ids(
        &mut self,
        id: &EntityId,
        field: &FileRelationshipField,
        ids_to_move: &[EntityId],
        new_index: i32,
    ) -> Result<Vec<EntityId>, RepositoryError>;
}

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

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

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

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

    pub fn create_orphan_multi(
        &mut self,
        event_buffer: &mut EventBuffer,
        entities: &[File],
    ) -> Result<Vec<File>, RepositoryError> {
        let new_entities = self.table.create_multi(entities)?;
        event_buffer.push(Event {
            origin: Origin::DirectAccess(DirectAccessEntity::File(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: &File,
        owner_id: EntityId,
        index: i32,
    ) -> Result<File, 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::File(EntityEvent::Created)),
            ids: vec![created_id],
            data: None,
        });
        Ok(new)
    }

    pub fn create_multi(
        &mut self,
        event_buffer: &mut EventBuffer,
        entities: &[File],
        owner_id: EntityId,
        index: i32,
    ) -> Result<Vec<File>, 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::File(EntityEvent::Created)),
            ids: created_ids,
            data: None,
        });
        Ok(new_entities)
    }

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

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

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

    pub fn update_with_relationships_multi(
        &mut self,
        event_buffer: &mut EventBuffer,
        entities: &[File],
    ) -> Result<Vec<File>, RepositoryError> {
        let updated = self.table.update_with_relationships_multi(entities)?;
        event_buffer.push(Event {
            origin: Origin::DirectAccess(DirectAccessEntity::File(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

        // remove all strong relationships, initiating a cascade remove

        // Before removal, find which owner(s) reference this entity
        let affected_owner_ids: Vec<EntityId> = {
            let owner_repo = repository_factory::write::create_system_repository(self.transaction)?;
            owner_repo
                .get_relationships_from_right_ids(&SystemRelationshipField::Files, &[*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::File(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

        // remove all strong relationships, initiating a cascade remove

        // Before removal, find which owner(s) reference these entities
        let affected_owner_ids: Vec<EntityId> = {
            let owner_repo = repository_factory::write::create_system_repository(self.transaction)?;
            owner_repo
                .get_relationships_from_right_ids(&SystemRelationshipField::Files, 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::File(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: &FileRelationshipField,
    ) -> Result<Vec<EntityId>, RepositoryError> {
        self.table.get_relationship(id, field)
    }
    pub fn get_relationship_many(
        &self,
        ids: &[EntityId],
        field: &FileRelationshipField,
    ) -> Result<std::collections::HashMap<EntityId, Vec<EntityId>>, RepositoryError> {
        self.table.get_relationship_many(ids, field)
    }
    pub fn get_relationship_count(
        &self,
        id: &EntityId,
        field: &FileRelationshipField,
    ) -> Result<usize, RepositoryError> {
        self.table.get_relationship_count(id, field)
    }
    pub fn get_relationship_in_range(
        &self,
        id: &EntityId,
        field: &FileRelationshipField,
        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: &FileRelationshipField,
        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: &FileRelationshipField,
        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 {
                FileRelationshipField::Entity => {
                    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,
                        });
                    }
                }
                FileRelationshipField::Feature => {
                    let child_repo =
                        repository_factory::write::create_feature_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,
                        });
                    }
                }
                FileRelationshipField::Field => {
                    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,
                        });
                    }
                }
                FileRelationshipField::UseCase => {
                    let child_repo =
                        repository_factory::write::create_use_case_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::File(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: &FileRelationshipField,
        right_ids: &[EntityId],
    ) -> Result<(), RepositoryError> {
        // Validate that all right_ids exist
        if !right_ids.is_empty() {
            match field {
                FileRelationshipField::Entity => {
                    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,
                        });
                    }
                }
                FileRelationshipField::Feature => {
                    let child_repo =
                        repository_factory::write::create_feature_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,
                        });
                    }
                }
                FileRelationshipField::Field => {
                    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,
                        });
                    }
                }
                FileRelationshipField::UseCase => {
                    let child_repo =
                        repository_factory::write::create_use_case_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::File(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: &FileRelationshipField,
        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::File(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_system_repository(self.transaction)?;
        repo.get_relationship(owner_id, &SystemRelationshipField::Files)
    }

    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_system_repository(self.transaction)?;
        repo.set_relationship(event_buffer, owner_id, &SystemRelationshipField::Files, 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_system_files(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(("file", *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.files);
            for id in &ids {
                match (snap.files.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).

        // 2. Entity rows: revert/re-add from snapshot, delete the ones created after it.
        {
            let mut live = write_or_recover(&store.files);
            for id in to_create.iter().chain(to_update.iter()) {
                if let Some(row) = snap.files.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_entity_from_file_entity);
            for id in to_create.iter().chain(to_update.iter()) {
                match snap.jn_entity_from_file_entity.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_feature_from_file_feature);
            for id in to_create.iter().chain(to_update.iter()) {
                match snap.jn_feature_from_file_feature.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_field_from_file_field);
            for id in to_create.iter().chain(to_update.iter()) {
                match snap.jn_field_from_file_field.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_use_case_from_file_use_case);
            for id in to_create.iter().chain(to_update.iter()) {
                match snap.jn_use_case_from_file_use_case.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).

        // 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::File(EntityEvent::Created)),
                ids: to_create.clone(),
                data: None,
            });
            event_buffer.push(Event {
                origin: Origin::DirectAccess(DirectAccessEntity::File(EntityEvent::Updated)),
                ids: to_create.clone(),
                data: None,
            });
        }
        if !to_update.is_empty() {
            event_buffer.push(Event {
                origin: Origin::DirectAccess(DirectAccessEntity::File(EntityEvent::Updated)),
                ids: to_update.clone(),
                data: None,
            });
        }
        if !to_delete.is_empty() {
            event_buffer.push(Event {
                origin: Origin::DirectAccess(DirectAccessEntity::File(EntityEvent::Removed)),
                ids: to_delete.clone(),
                data: None,
            });
        }

        Ok(())
    }

    /// Surgically reconcile one external referrer junction (out-of-scope key -> in-scope values):
    /// `system.files`.
    fn reconcile_backref_system_files(
        &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_file_from_system_files.iter() {
            if rights.iter().any(|rid| scope.contains(rid)) {
                left_keys.insert(*left);
            }
        }
        {
            let live_jn = read_or_recover(&store.jn_file_from_system_files);
            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_file_from_system_files
                .get(&left)
                .cloned()
                .unwrap_or_default();
            let new_list = {
                let live_jn = read_or_recover(&store.jn_file_from_system_files);
                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_file_from_system_files).insert(left, reconciled);
                event_buffer.push(Event {
                    origin: Origin::DirectAccess(DirectAccessEntity::System(EntityEvent::Updated)),
                    ids: vec![left],
                    data: None,
                });
            }
        }
        Ok(())
    }
}

pub struct FileRepositoryRO<'a> {
    table: Box<dyn FileTableRO + 'a>,
}
impl<'a> FileRepositoryRO<'a> {
    pub fn new(table: Box<dyn FileTableRO + 'a>) -> Self {
        FileRepositoryRO { table }
    }
    pub fn get(&self, id: &EntityId) -> Result<Option<File>, RepositoryError> {
        self.table.get(id)
    }
    pub fn get_multi(&self, ids: &[EntityId]) -> Result<Vec<Option<File>>, RepositoryError> {
        self.table.get_multi(ids)
    }
    pub fn get_all(&self) -> Result<Vec<File>, RepositoryError> {
        self.table.get_all()
    }
    pub fn get_relationship(
        &self,
        id: &EntityId,
        field: &FileRelationshipField,
    ) -> Result<Vec<EntityId>, RepositoryError> {
        self.table.get_relationship(id, field)
    }
    pub fn get_relationship_many(
        &self,
        ids: &[EntityId],
        field: &FileRelationshipField,
    ) -> Result<std::collections::HashMap<EntityId, Vec<EntityId>>, RepositoryError> {
        self.table.get_relationship_many(ids, field)
    }
    pub fn get_relationship_count(
        &self,
        id: &EntityId,
        field: &FileRelationshipField,
    ) -> Result<usize, RepositoryError> {
        self.table.get_relationship_count(id, field)
    }
    pub fn get_relationship_in_range(
        &self,
        id: &EntityId,
        field: &FileRelationshipField,
        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: &FileRelationshipField,
        right_ids: &[EntityId],
    ) -> Result<Vec<(EntityId, Vec<EntityId>)>, RepositoryError> {
        self.table
            .get_relationships_from_right_ids(field, right_ids)
    }
}