qleany-common 2.0.1

// Generated by Qleany v2.0.0 from hashmap_store.tera

//! HashMap-based storage backend with O(1) snapshots.
//!
//! Uses `im::HashMap` (persistent/immutable data structure with structural sharing)
//! so that cloning the store for savepoints and undo is O(1).
//! The store uses `RwLock` for interior mutability and thread safety,
//! allowing `&HashMapStore` to be shared across threads via `Arc`.

use crate::entities::*;
use crate::snapshot::{StoreSnapshot, StoreSnapshotTrait};
use crate::types::EntityId;
use im::HashMap;
use std::sync::RwLock;

// ─────────────────────────────────────────────────────────────────────────────
// The Store
// ─────────────────────────────────────────────────────────────────────────────

#[derive(Debug)]
pub struct HashMapStore {
    // ── Entity tables ──────────────────────────────────────────────────
    pub roots: RwLock<HashMap<EntityId, Root>>,
    pub workspaces: RwLock<HashMap<EntityId, Workspace>>,
    pub systems: RwLock<HashMap<EntityId, System>>,
    pub entities: RwLock<HashMap<EntityId, Entity>>,
    pub fields: RwLock<HashMap<EntityId, Field>>,
    pub features: RwLock<HashMap<EntityId, Feature>>,
    pub files: RwLock<HashMap<EntityId, File>>,
    pub use_cases: RwLock<HashMap<EntityId, UseCase>>,
    pub dtos: RwLock<HashMap<EntityId, Dto>>,
    pub dto_fields: RwLock<HashMap<EntityId, DtoField>>,
    pub globals: RwLock<HashMap<EntityId, Global>>,
    pub relationships: RwLock<HashMap<EntityId, Relationship>>,
    pub user_interfaces: RwLock<HashMap<EntityId, UserInterface>>,

    // ── Junction tables (one per forward relationship, shared for backward cleanup) ─
    pub jn_system_from_root_system: RwLock<HashMapJunction>,
    pub jn_workspace_from_root_workspace: RwLock<HashMapJunction>,
    pub jn_entity_from_workspace_entities: RwLock<HashMapJunction>,
    pub jn_feature_from_workspace_features: RwLock<HashMapJunction>,
    pub jn_global_from_workspace_global: RwLock<HashMapJunction>,
    pub jn_user_interface_from_workspace_user_interface: RwLock<HashMapJunction>,
    pub jn_file_from_system_files: RwLock<HashMapJunction>,
    pub jn_field_from_entity_fields: RwLock<HashMapJunction>,
    pub jn_entity_from_entity_inherits_from: RwLock<HashMapJunction>,
    pub jn_relationship_from_entity_relationships: RwLock<HashMapJunction>,
    pub jn_entity_from_field_entity: RwLock<HashMapJunction>,
    pub jn_use_case_from_feature_use_cases: RwLock<HashMapJunction>,
    pub jn_entity_from_file_entity: RwLock<HashMapJunction>,
    pub jn_feature_from_file_feature: RwLock<HashMapJunction>,
    pub jn_field_from_file_field: RwLock<HashMapJunction>,
    pub jn_use_case_from_file_use_case: RwLock<HashMapJunction>,
    pub jn_dto_from_use_case_dto_in: RwLock<HashMapJunction>,
    pub jn_dto_from_use_case_dto_out: RwLock<HashMapJunction>,
    pub jn_entity_from_use_case_entities: RwLock<HashMapJunction>,
    pub jn_dto_field_from_dto_fields: RwLock<HashMapJunction>,
    pub jn_entity_from_relationship_left_entity: RwLock<HashMapJunction>,
    pub jn_entity_from_relationship_right_entity: RwLock<HashMapJunction>,

    // ── ID counters (one per entity type) ──────────────────────────
    pub counters: RwLock<std::collections::HashMap<String, EntityId>>,

    // ── Savepoints ──────────────────────────────────────────────────
    savepoints: RwLock<std::collections::HashMap<u64, HashMapStoreSnapshot>>,
    next_savepoint_id: RwLock<u64>,
}
impl Default for HashMapStore {
    fn default() -> Self {
        Self {
            roots: RwLock::default(),
            workspaces: RwLock::default(),
            systems: RwLock::default(),
            entities: RwLock::default(),
            fields: RwLock::default(),
            features: RwLock::default(),
            files: RwLock::default(),
            use_cases: RwLock::default(),
            dtos: RwLock::default(),
            dto_fields: RwLock::default(),
            globals: RwLock::default(),
            relationships: RwLock::default(),
            user_interfaces: RwLock::default(),
            jn_system_from_root_system: RwLock::new(HashMapJunction::exclusive()),
            jn_workspace_from_root_workspace: RwLock::new(HashMapJunction::exclusive()),
            jn_entity_from_workspace_entities: RwLock::new(HashMapJunction::exclusive()),
            jn_feature_from_workspace_features: RwLock::new(HashMapJunction::exclusive()),
            jn_global_from_workspace_global: RwLock::new(HashMapJunction::exclusive()),
            jn_user_interface_from_workspace_user_interface: RwLock::new(
                HashMapJunction::exclusive(),
            ),
            jn_file_from_system_files: RwLock::new(HashMapJunction::exclusive()),
            jn_field_from_entity_fields: RwLock::new(HashMapJunction::exclusive()),
            jn_entity_from_entity_inherits_from: RwLock::new(HashMapJunction::shared()),
            jn_relationship_from_entity_relationships: RwLock::new(HashMapJunction::exclusive()),
            jn_entity_from_field_entity: RwLock::new(HashMapJunction::shared()),
            jn_use_case_from_feature_use_cases: RwLock::new(HashMapJunction::exclusive()),
            jn_entity_from_file_entity: RwLock::new(HashMapJunction::shared()),
            jn_feature_from_file_feature: RwLock::new(HashMapJunction::shared()),
            jn_field_from_file_field: RwLock::new(HashMapJunction::shared()),
            jn_use_case_from_file_use_case: RwLock::new(HashMapJunction::shared()),
            jn_dto_from_use_case_dto_in: RwLock::new(HashMapJunction::exclusive()),
            jn_dto_from_use_case_dto_out: RwLock::new(HashMapJunction::exclusive()),
            jn_entity_from_use_case_entities: RwLock::new(HashMapJunction::shared()),
            jn_dto_field_from_dto_fields: RwLock::new(HashMapJunction::exclusive()),
            jn_entity_from_relationship_left_entity: RwLock::new(HashMapJunction::shared()),
            jn_entity_from_relationship_right_entity: RwLock::new(HashMapJunction::shared()),
            counters: RwLock::default(),
            savepoints: RwLock::default(),
            next_savepoint_id: RwLock::default(),
        }
    }
}

impl HashMapStore {
    pub fn new() -> Self {
        Self::default()
    }

    /// Clone the entire store for savepoint support. O(1) thanks to im::HashMap.
    /// (Poison-tolerant, but NOT atomic across tables — used for savepoints, which
    /// are taken on the single writer thread with no concurrent writer; use
    /// [`Self::freeze`] when an atomic cross-table snapshot is required.)
    pub fn snapshot(&self) -> HashMapStoreSnapshot {
        HashMapStoreSnapshot {
            roots: read_or_recover(&self.roots).clone(),
            workspaces: read_or_recover(&self.workspaces).clone(),
            systems: read_or_recover(&self.systems).clone(),
            entities: read_or_recover(&self.entities).clone(),
            fields: read_or_recover(&self.fields).clone(),
            features: read_or_recover(&self.features).clone(),
            files: read_or_recover(&self.files).clone(),
            use_cases: read_or_recover(&self.use_cases).clone(),
            dtos: read_or_recover(&self.dtos).clone(),
            dto_fields: read_or_recover(&self.dto_fields).clone(),
            globals: read_or_recover(&self.globals).clone(),
            relationships: read_or_recover(&self.relationships).clone(),
            user_interfaces: read_or_recover(&self.user_interfaces).clone(),
            jn_system_from_root_system: read_or_recover(&self.jn_system_from_root_system).clone(),
            jn_workspace_from_root_workspace: read_or_recover(
                &self.jn_workspace_from_root_workspace,
            )
            .clone(),
            jn_entity_from_workspace_entities: read_or_recover(
                &self.jn_entity_from_workspace_entities,
            )
            .clone(),
            jn_feature_from_workspace_features: read_or_recover(
                &self.jn_feature_from_workspace_features,
            )
            .clone(),
            jn_global_from_workspace_global: read_or_recover(&self.jn_global_from_workspace_global)
                .clone(),
            jn_user_interface_from_workspace_user_interface: read_or_recover(
                &self.jn_user_interface_from_workspace_user_interface,
            )
            .clone(),
            jn_file_from_system_files: read_or_recover(&self.jn_file_from_system_files).clone(),
            jn_field_from_entity_fields: read_or_recover(&self.jn_field_from_entity_fields).clone(),
            jn_entity_from_entity_inherits_from: read_or_recover(
                &self.jn_entity_from_entity_inherits_from,
            )
            .clone(),
            jn_relationship_from_entity_relationships: read_or_recover(
                &self.jn_relationship_from_entity_relationships,
            )
            .clone(),
            jn_entity_from_field_entity: read_or_recover(&self.jn_entity_from_field_entity).clone(),
            jn_use_case_from_feature_use_cases: read_or_recover(
                &self.jn_use_case_from_feature_use_cases,
            )
            .clone(),
            jn_entity_from_file_entity: read_or_recover(&self.jn_entity_from_file_entity).clone(),
            jn_feature_from_file_feature: read_or_recover(&self.jn_feature_from_file_feature)
                .clone(),
            jn_field_from_file_field: read_or_recover(&self.jn_field_from_file_field).clone(),
            jn_use_case_from_file_use_case: read_or_recover(&self.jn_use_case_from_file_use_case)
                .clone(),
            jn_dto_from_use_case_dto_in: read_or_recover(&self.jn_dto_from_use_case_dto_in).clone(),
            jn_dto_from_use_case_dto_out: read_or_recover(&self.jn_dto_from_use_case_dto_out)
                .clone(),
            jn_entity_from_use_case_entities: read_or_recover(
                &self.jn_entity_from_use_case_entities,
            )
            .clone(),
            jn_dto_field_from_dto_fields: read_or_recover(&self.jn_dto_field_from_dto_fields)
                .clone(),
            jn_entity_from_relationship_left_entity: read_or_recover(
                &self.jn_entity_from_relationship_left_entity,
            )
            .clone(),
            jn_entity_from_relationship_right_entity: read_or_recover(
                &self.jn_entity_from_relationship_right_entity,
            )
            .clone(),
            counters: read_or_recover(&self.counters).clone(),
        }
    }

    /// Atomically snapshot the whole store into a fresh, isolated `HashMapStore`.
    ///
    /// Unlike [`Self::snapshot`], this holds a read guard on **every** table, junction,
    /// and the counters *simultaneously* while cloning, so the result is a single
    /// consistent point-in-time view of the store *at the instant freeze runs*.
    /// O(1) clones (im::HashMap structural sharing); the lock hold is just the
    /// clones. The returned store carries no savepoints and is meant to back a
    /// read-only (frozen) transaction.
    ///
    /// Deadlock-freedom depends on an **invariant** (unenforced by the type
    /// system): guards are acquired in the struct's declared field order (all
    /// entity tables, then all junctions, then counters), and no writer ever
    /// holds two *entity-table* locks simultaneously — each writer takes at most
    /// one entity table, then its junctions, in table-before-junction order (see
    /// `remove_multi`). A future cascade that nested two entity-table locks would
    /// violate this and could deadlock against freeze; keep cascades single-table.
    ///
    /// SCOPE: freeze is atomic w.r.t. *itself*, not w.r.t. a writer's *multi-step*
    /// cascade. A write transaction is not one critical section — its per-repo
    /// calls each lock/unlock independently — so a cascading delete/create can
    /// leave a brief window (e.g. child rows removed but the parent's junction not
    /// yet cleared) into which freeze can land and capture a cross-table-torn
    /// snapshot (`gather` then hits "entity vanished mid-read", or silently omits
    /// a just-added-but-unlinked row). This shrinks the torn-read window from the
    /// whole read to a single instant, but does not eliminate it; a store-wide
    /// writer/reader gate would be required to fully close it.
    pub fn freeze(&self) -> HashMapStore {
        // Acquire ALL read guards first (declared order), then clone under that
        // one consistent lock set.
        let g_roots = read_or_recover(&self.roots);
        let g_workspaces = read_or_recover(&self.workspaces);
        let g_systems = read_or_recover(&self.systems);
        let g_entities = read_or_recover(&self.entities);
        let g_fields = read_or_recover(&self.fields);
        let g_features = read_or_recover(&self.features);
        let g_files = read_or_recover(&self.files);
        let g_use_cases = read_or_recover(&self.use_cases);
        let g_dtos = read_or_recover(&self.dtos);
        let g_dto_fields = read_or_recover(&self.dto_fields);
        let g_globals = read_or_recover(&self.globals);
        let g_relationships = read_or_recover(&self.relationships);
        let g_user_interfaces = read_or_recover(&self.user_interfaces);
        let g_jn_system_from_root_system = read_or_recover(&self.jn_system_from_root_system);
        let g_jn_workspace_from_root_workspace =
            read_or_recover(&self.jn_workspace_from_root_workspace);
        let g_jn_entity_from_workspace_entities =
            read_or_recover(&self.jn_entity_from_workspace_entities);
        let g_jn_feature_from_workspace_features =
            read_or_recover(&self.jn_feature_from_workspace_features);
        let g_jn_global_from_workspace_global =
            read_or_recover(&self.jn_global_from_workspace_global);
        let g_jn_user_interface_from_workspace_user_interface =
            read_or_recover(&self.jn_user_interface_from_workspace_user_interface);
        let g_jn_file_from_system_files = read_or_recover(&self.jn_file_from_system_files);
        let g_jn_field_from_entity_fields = read_or_recover(&self.jn_field_from_entity_fields);
        let g_jn_entity_from_entity_inherits_from =
            read_or_recover(&self.jn_entity_from_entity_inherits_from);
        let g_jn_relationship_from_entity_relationships =
            read_or_recover(&self.jn_relationship_from_entity_relationships);
        let g_jn_entity_from_field_entity = read_or_recover(&self.jn_entity_from_field_entity);
        let g_jn_use_case_from_feature_use_cases =
            read_or_recover(&self.jn_use_case_from_feature_use_cases);
        let g_jn_entity_from_file_entity = read_or_recover(&self.jn_entity_from_file_entity);
        let g_jn_feature_from_file_feature = read_or_recover(&self.jn_feature_from_file_feature);
        let g_jn_field_from_file_field = read_or_recover(&self.jn_field_from_file_field);
        let g_jn_use_case_from_file_use_case =
            read_or_recover(&self.jn_use_case_from_file_use_case);
        let g_jn_dto_from_use_case_dto_in = read_or_recover(&self.jn_dto_from_use_case_dto_in);
        let g_jn_dto_from_use_case_dto_out = read_or_recover(&self.jn_dto_from_use_case_dto_out);
        let g_jn_entity_from_use_case_entities =
            read_or_recover(&self.jn_entity_from_use_case_entities);
        let g_jn_dto_field_from_dto_fields = read_or_recover(&self.jn_dto_field_from_dto_fields);
        let g_jn_entity_from_relationship_left_entity =
            read_or_recover(&self.jn_entity_from_relationship_left_entity);
        let g_jn_entity_from_relationship_right_entity =
            read_or_recover(&self.jn_entity_from_relationship_right_entity);
        let g_counters = read_or_recover(&self.counters);

        HashMapStore {
            roots: RwLock::new(g_roots.clone()),
            workspaces: RwLock::new(g_workspaces.clone()),
            systems: RwLock::new(g_systems.clone()),
            entities: RwLock::new(g_entities.clone()),
            fields: RwLock::new(g_fields.clone()),
            features: RwLock::new(g_features.clone()),
            files: RwLock::new(g_files.clone()),
            use_cases: RwLock::new(g_use_cases.clone()),
            dtos: RwLock::new(g_dtos.clone()),
            dto_fields: RwLock::new(g_dto_fields.clone()),
            globals: RwLock::new(g_globals.clone()),
            relationships: RwLock::new(g_relationships.clone()),
            user_interfaces: RwLock::new(g_user_interfaces.clone()),
            jn_system_from_root_system: RwLock::new(g_jn_system_from_root_system.clone()),
            jn_workspace_from_root_workspace: RwLock::new(
                g_jn_workspace_from_root_workspace.clone(),
            ),
            jn_entity_from_workspace_entities: RwLock::new(
                g_jn_entity_from_workspace_entities.clone(),
            ),
            jn_feature_from_workspace_features: RwLock::new(
                g_jn_feature_from_workspace_features.clone(),
            ),
            jn_global_from_workspace_global: RwLock::new(g_jn_global_from_workspace_global.clone()),
            jn_user_interface_from_workspace_user_interface: RwLock::new(
                g_jn_user_interface_from_workspace_user_interface.clone(),
            ),
            jn_file_from_system_files: RwLock::new(g_jn_file_from_system_files.clone()),
            jn_field_from_entity_fields: RwLock::new(g_jn_field_from_entity_fields.clone()),
            jn_entity_from_entity_inherits_from: RwLock::new(
                g_jn_entity_from_entity_inherits_from.clone(),
            ),
            jn_relationship_from_entity_relationships: RwLock::new(
                g_jn_relationship_from_entity_relationships.clone(),
            ),
            jn_entity_from_field_entity: RwLock::new(g_jn_entity_from_field_entity.clone()),
            jn_use_case_from_feature_use_cases: RwLock::new(
                g_jn_use_case_from_feature_use_cases.clone(),
            ),
            jn_entity_from_file_entity: RwLock::new(g_jn_entity_from_file_entity.clone()),
            jn_feature_from_file_feature: RwLock::new(g_jn_feature_from_file_feature.clone()),
            jn_field_from_file_field: RwLock::new(g_jn_field_from_file_field.clone()),
            jn_use_case_from_file_use_case: RwLock::new(g_jn_use_case_from_file_use_case.clone()),
            jn_dto_from_use_case_dto_in: RwLock::new(g_jn_dto_from_use_case_dto_in.clone()),
            jn_dto_from_use_case_dto_out: RwLock::new(g_jn_dto_from_use_case_dto_out.clone()),
            jn_entity_from_use_case_entities: RwLock::new(
                g_jn_entity_from_use_case_entities.clone(),
            ),
            jn_dto_field_from_dto_fields: RwLock::new(g_jn_dto_field_from_dto_fields.clone()),
            jn_entity_from_relationship_left_entity: RwLock::new(
                g_jn_entity_from_relationship_left_entity.clone(),
            ),
            jn_entity_from_relationship_right_entity: RwLock::new(
                g_jn_entity_from_relationship_right_entity.clone(),
            ),
            counters: RwLock::new(g_counters.clone()),
            savepoints: RwLock::new(std::collections::HashMap::new()),
            next_savepoint_id: RwLock::new(0),
        }
    }

    /// Restore from a savepoint snapshot.
    pub fn restore(&self, snap: &HashMapStoreSnapshot) {
        *write_or_recover(&self.roots) = snap.roots.clone();
        *write_or_recover(&self.workspaces) = snap.workspaces.clone();
        *write_or_recover(&self.systems) = snap.systems.clone();
        *write_or_recover(&self.entities) = snap.entities.clone();
        *write_or_recover(&self.fields) = snap.fields.clone();
        *write_or_recover(&self.features) = snap.features.clone();
        *write_or_recover(&self.files) = snap.files.clone();
        *write_or_recover(&self.use_cases) = snap.use_cases.clone();
        *write_or_recover(&self.dtos) = snap.dtos.clone();
        *write_or_recover(&self.dto_fields) = snap.dto_fields.clone();
        *write_or_recover(&self.globals) = snap.globals.clone();
        *write_or_recover(&self.relationships) = snap.relationships.clone();
        *write_or_recover(&self.user_interfaces) = snap.user_interfaces.clone();
        *write_or_recover(&self.jn_system_from_root_system) =
            snap.jn_system_from_root_system.clone();
        *write_or_recover(&self.jn_workspace_from_root_workspace) =
            snap.jn_workspace_from_root_workspace.clone();
        *write_or_recover(&self.jn_entity_from_workspace_entities) =
            snap.jn_entity_from_workspace_entities.clone();
        *write_or_recover(&self.jn_feature_from_workspace_features) =
            snap.jn_feature_from_workspace_features.clone();
        *write_or_recover(&self.jn_global_from_workspace_global) =
            snap.jn_global_from_workspace_global.clone();
        *write_or_recover(&self.jn_user_interface_from_workspace_user_interface) =
            snap.jn_user_interface_from_workspace_user_interface.clone();
        *write_or_recover(&self.jn_file_from_system_files) = snap.jn_file_from_system_files.clone();
        *write_or_recover(&self.jn_field_from_entity_fields) =
            snap.jn_field_from_entity_fields.clone();
        *write_or_recover(&self.jn_entity_from_entity_inherits_from) =
            snap.jn_entity_from_entity_inherits_from.clone();
        *write_or_recover(&self.jn_relationship_from_entity_relationships) =
            snap.jn_relationship_from_entity_relationships.clone();
        *write_or_recover(&self.jn_entity_from_field_entity) =
            snap.jn_entity_from_field_entity.clone();
        *write_or_recover(&self.jn_use_case_from_feature_use_cases) =
            snap.jn_use_case_from_feature_use_cases.clone();
        *write_or_recover(&self.jn_entity_from_file_entity) =
            snap.jn_entity_from_file_entity.clone();
        *write_or_recover(&self.jn_feature_from_file_feature) =
            snap.jn_feature_from_file_feature.clone();
        *write_or_recover(&self.jn_field_from_file_field) = snap.jn_field_from_file_field.clone();
        *write_or_recover(&self.jn_use_case_from_file_use_case) =
            snap.jn_use_case_from_file_use_case.clone();
        *write_or_recover(&self.jn_dto_from_use_case_dto_in) =
            snap.jn_dto_from_use_case_dto_in.clone();
        *write_or_recover(&self.jn_dto_from_use_case_dto_out) =
            snap.jn_dto_from_use_case_dto_out.clone();
        *write_or_recover(&self.jn_entity_from_use_case_entities) =
            snap.jn_entity_from_use_case_entities.clone();
        *write_or_recover(&self.jn_dto_field_from_dto_fields) =
            snap.jn_dto_field_from_dto_fields.clone();
        *write_or_recover(&self.jn_entity_from_relationship_left_entity) =
            snap.jn_entity_from_relationship_left_entity.clone();
        *write_or_recover(&self.jn_entity_from_relationship_right_entity) =
            snap.jn_entity_from_relationship_right_entity.clone();
        *write_or_recover(&self.counters) = snap.counters.clone();
    }

    /// Create a savepoint by snapshotting the entire store. Returns a savepoint id.
    /// O(1) thanks to im::HashMap structural sharing.
    pub fn create_savepoint(&self) -> u64 {
        let snap = self.snapshot();
        let mut id_counter = write_or_recover(&self.next_savepoint_id);
        let id = *id_counter;
        *id_counter += 1;
        write_or_recover(&self.savepoints).insert(id, snap);
        id
    }

    /// Restore the store to a previously created savepoint.
    pub fn restore_savepoint(&self, savepoint_id: u64) {
        // A missing savepoint is a caller bug, but this is reached from
        // `Transaction`'s **`Drop`-time rollback** — and panicking in a `Drop`
        // that is itself running because of an earlier panic aborts the process
        // outright, no matter what the panic strategy is. That double-panic is
        // exactly what this module's poison recovery exists to avoid, so the
        // rollback must not be the thing that reintroduces it.
        //
        // Loud in a debug build, a no-op in a shipped one: nothing to restore
        // to means the store simply stays as it is.
        let Some(snap) = read_or_recover(&self.savepoints)
            .get(&savepoint_id)
            .cloned()
        else {
            debug_assert!(
                false,
                "restore_savepoint: savepoint {savepoint_id} does not exist — it was already \
                 restored, discarded, or never created"
            );
            return;
        };
        self.restore(&snap);
    }

    /// Discard a savepoint without restoring (used on successful commit, and
    /// after a rollback so a rolled-back transaction doesn't leak its snapshot).
    pub fn discard_savepoint(&self, savepoint_id: u64) {
        write_or_recover(&self.savepoints).remove(&savepoint_id);
    }

    /// Get-and-increment counter for an entity type.
    pub(crate) fn next_id(&self, entity_name: &str) -> EntityId {
        let mut counters = write_or_recover(&self.counters);
        let counter = counters.entry(entity_name.to_string()).or_insert(1);
        let id = *counter;
        *counter += 1;
        id
    }

    /// Restore entity and junction data but preserve current counters.
    /// Used for undo snapshots where IDs must remain monotonically increasing.
    pub fn restore_without_counters(&self, snap: &HashMapStoreSnapshot) {
        *write_or_recover(&self.roots) = snap.roots.clone();
        *write_or_recover(&self.workspaces) = snap.workspaces.clone();
        *write_or_recover(&self.systems) = snap.systems.clone();
        *write_or_recover(&self.entities) = snap.entities.clone();
        *write_or_recover(&self.fields) = snap.fields.clone();
        *write_or_recover(&self.features) = snap.features.clone();
        *write_or_recover(&self.files) = snap.files.clone();
        *write_or_recover(&self.use_cases) = snap.use_cases.clone();
        *write_or_recover(&self.dtos) = snap.dtos.clone();
        *write_or_recover(&self.dto_fields) = snap.dto_fields.clone();
        *write_or_recover(&self.globals) = snap.globals.clone();
        *write_or_recover(&self.relationships) = snap.relationships.clone();
        *write_or_recover(&self.user_interfaces) = snap.user_interfaces.clone();
        *write_or_recover(&self.jn_system_from_root_system) =
            snap.jn_system_from_root_system.clone();
        *write_or_recover(&self.jn_workspace_from_root_workspace) =
            snap.jn_workspace_from_root_workspace.clone();
        *write_or_recover(&self.jn_entity_from_workspace_entities) =
            snap.jn_entity_from_workspace_entities.clone();
        *write_or_recover(&self.jn_feature_from_workspace_features) =
            snap.jn_feature_from_workspace_features.clone();
        *write_or_recover(&self.jn_global_from_workspace_global) =
            snap.jn_global_from_workspace_global.clone();
        *write_or_recover(&self.jn_user_interface_from_workspace_user_interface) =
            snap.jn_user_interface_from_workspace_user_interface.clone();
        *write_or_recover(&self.jn_file_from_system_files) = snap.jn_file_from_system_files.clone();
        *write_or_recover(&self.jn_field_from_entity_fields) =
            snap.jn_field_from_entity_fields.clone();
        *write_or_recover(&self.jn_entity_from_entity_inherits_from) =
            snap.jn_entity_from_entity_inherits_from.clone();
        *write_or_recover(&self.jn_relationship_from_entity_relationships) =
            snap.jn_relationship_from_entity_relationships.clone();
        *write_or_recover(&self.jn_entity_from_field_entity) =
            snap.jn_entity_from_field_entity.clone();
        *write_or_recover(&self.jn_use_case_from_feature_use_cases) =
            snap.jn_use_case_from_feature_use_cases.clone();
        *write_or_recover(&self.jn_entity_from_file_entity) =
            snap.jn_entity_from_file_entity.clone();
        *write_or_recover(&self.jn_feature_from_file_feature) =
            snap.jn_feature_from_file_feature.clone();
        *write_or_recover(&self.jn_field_from_file_field) = snap.jn_field_from_file_field.clone();
        *write_or_recover(&self.jn_use_case_from_file_use_case) =
            snap.jn_use_case_from_file_use_case.clone();
        *write_or_recover(&self.jn_dto_from_use_case_dto_in) =
            snap.jn_dto_from_use_case_dto_in.clone();
        *write_or_recover(&self.jn_dto_from_use_case_dto_out) =
            snap.jn_dto_from_use_case_dto_out.clone();
        *write_or_recover(&self.jn_entity_from_use_case_entities) =
            snap.jn_entity_from_use_case_entities.clone();
        *write_or_recover(&self.jn_dto_field_from_dto_fields) =
            snap.jn_dto_field_from_dto_fields.clone();
        *write_or_recover(&self.jn_entity_from_relationship_left_entity) =
            snap.jn_entity_from_relationship_left_entity.clone();
        *write_or_recover(&self.jn_entity_from_relationship_right_entity) =
            snap.jn_entity_from_relationship_right_entity.clone();
        // counters intentionally NOT restored — IDs must remain monotonically increasing
    }

    /// Create a type-erased store snapshot for undo.
    pub fn store_snapshot(&self) -> StoreSnapshot {
        StoreSnapshot::new(self.snapshot())
    }

    /// Restore from a type-erased store snapshot (preserves counters).
    pub fn restore_store_snapshot(&self, snap: &StoreSnapshot) {
        let s = snap
            .downcast_ref::<HashMapStoreSnapshot>()
            .expect("StoreSnapshot must contain HashMapStoreSnapshot");
        self.restore_without_counters(s);
    }

    /// Check every junction's reverse index against a rebuild from its rows,
    /// and that each junction is exclusive exactly when its relationship is.
    ///
    /// A diagnostic for tests: it walks every junction, so it costs O(store).
    /// Nothing calls it on a write path. Returns the first discrepancy found.
    pub fn check_junction_indexes(&self) -> Result<(), String> {
        {
            let jn = read_or_recover(&self.jn_system_from_root_system);
            if !jn.is_exclusive() {
                return Err(
                    "jn_system_from_root_system: exclusivity does not match the relationship"
                        .into(),
                );
            }
            jn.check_index()
                .map_err(|e| format!("jn_system_from_root_system: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_workspace_from_root_workspace);
            if !jn.is_exclusive() {
                return Err(
                    "jn_workspace_from_root_workspace: exclusivity does not match the relationship"
                        .into(),
                );
            }
            jn.check_index()
                .map_err(|e| format!("jn_workspace_from_root_workspace: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_entity_from_workspace_entities);
            if !jn.is_exclusive() {
                return Err("jn_entity_from_workspace_entities: exclusivity does not match the relationship".into());
            }
            jn.check_index()
                .map_err(|e| format!("jn_entity_from_workspace_entities: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_feature_from_workspace_features);
            if !jn.is_exclusive() {
                return Err("jn_feature_from_workspace_features: exclusivity does not match the relationship".into());
            }
            jn.check_index()
                .map_err(|e| format!("jn_feature_from_workspace_features: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_global_from_workspace_global);
            if !jn.is_exclusive() {
                return Err(
                    "jn_global_from_workspace_global: exclusivity does not match the relationship"
                        .into(),
                );
            }
            jn.check_index()
                .map_err(|e| format!("jn_global_from_workspace_global: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_user_interface_from_workspace_user_interface);
            if !jn.is_exclusive() {
                return Err("jn_user_interface_from_workspace_user_interface: exclusivity does not match the relationship".into());
            }
            jn.check_index()
                .map_err(|e| format!("jn_user_interface_from_workspace_user_interface: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_file_from_system_files);
            if !jn.is_exclusive() {
                return Err(
                    "jn_file_from_system_files: exclusivity does not match the relationship".into(),
                );
            }
            jn.check_index()
                .map_err(|e| format!("jn_file_from_system_files: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_field_from_entity_fields);
            if !jn.is_exclusive() {
                return Err(
                    "jn_field_from_entity_fields: exclusivity does not match the relationship"
                        .into(),
                );
            }
            jn.check_index()
                .map_err(|e| format!("jn_field_from_entity_fields: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_entity_from_entity_inherits_from);
            if jn.is_exclusive() {
                return Err("jn_entity_from_entity_inherits_from: exclusivity does not match the relationship".into());
            }
            jn.check_index()
                .map_err(|e| format!("jn_entity_from_entity_inherits_from: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_relationship_from_entity_relationships);
            if !jn.is_exclusive() {
                return Err("jn_relationship_from_entity_relationships: exclusivity does not match the relationship".into());
            }
            jn.check_index()
                .map_err(|e| format!("jn_relationship_from_entity_relationships: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_entity_from_field_entity);
            if jn.is_exclusive() {
                return Err(
                    "jn_entity_from_field_entity: exclusivity does not match the relationship"
                        .into(),
                );
            }
            jn.check_index()
                .map_err(|e| format!("jn_entity_from_field_entity: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_use_case_from_feature_use_cases);
            if !jn.is_exclusive() {
                return Err("jn_use_case_from_feature_use_cases: exclusivity does not match the relationship".into());
            }
            jn.check_index()
                .map_err(|e| format!("jn_use_case_from_feature_use_cases: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_entity_from_file_entity);
            if jn.is_exclusive() {
                return Err(
                    "jn_entity_from_file_entity: exclusivity does not match the relationship"
                        .into(),
                );
            }
            jn.check_index()
                .map_err(|e| format!("jn_entity_from_file_entity: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_feature_from_file_feature);
            if jn.is_exclusive() {
                return Err(
                    "jn_feature_from_file_feature: exclusivity does not match the relationship"
                        .into(),
                );
            }
            jn.check_index()
                .map_err(|e| format!("jn_feature_from_file_feature: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_field_from_file_field);
            if jn.is_exclusive() {
                return Err(
                    "jn_field_from_file_field: exclusivity does not match the relationship".into(),
                );
            }
            jn.check_index()
                .map_err(|e| format!("jn_field_from_file_field: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_use_case_from_file_use_case);
            if jn.is_exclusive() {
                return Err(
                    "jn_use_case_from_file_use_case: exclusivity does not match the relationship"
                        .into(),
                );
            }
            jn.check_index()
                .map_err(|e| format!("jn_use_case_from_file_use_case: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_dto_from_use_case_dto_in);
            if !jn.is_exclusive() {
                return Err(
                    "jn_dto_from_use_case_dto_in: exclusivity does not match the relationship"
                        .into(),
                );
            }
            jn.check_index()
                .map_err(|e| format!("jn_dto_from_use_case_dto_in: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_dto_from_use_case_dto_out);
            if !jn.is_exclusive() {
                return Err(
                    "jn_dto_from_use_case_dto_out: exclusivity does not match the relationship"
                        .into(),
                );
            }
            jn.check_index()
                .map_err(|e| format!("jn_dto_from_use_case_dto_out: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_entity_from_use_case_entities);
            if jn.is_exclusive() {
                return Err(
                    "jn_entity_from_use_case_entities: exclusivity does not match the relationship"
                        .into(),
                );
            }
            jn.check_index()
                .map_err(|e| format!("jn_entity_from_use_case_entities: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_dto_field_from_dto_fields);
            if !jn.is_exclusive() {
                return Err(
                    "jn_dto_field_from_dto_fields: exclusivity does not match the relationship"
                        .into(),
                );
            }
            jn.check_index()
                .map_err(|e| format!("jn_dto_field_from_dto_fields: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_entity_from_relationship_left_entity);
            if jn.is_exclusive() {
                return Err("jn_entity_from_relationship_left_entity: exclusivity does not match the relationship".into());
            }
            jn.check_index()
                .map_err(|e| format!("jn_entity_from_relationship_left_entity: {e}"))?;
        }
        {
            let jn = read_or_recover(&self.jn_entity_from_relationship_right_entity);
            if jn.is_exclusive() {
                return Err("jn_entity_from_relationship_right_entity: exclusivity does not match the relationship".into());
            }
            jn.check_index()
                .map_err(|e| format!("jn_entity_from_relationship_right_entity: {e}"))?;
        }
        Ok(())
    }
}

/// Snapshot of the entire store. O(1) to create thanks to im::HashMap structural sharing.
///
/// Entity-table and junction fields are `pub(crate)` so the generated per-entity
/// repositories (same crate) can read the captured rows/junctions during a *scoped*
/// restore. Counters stay private (restore never touches them — ids stay monotonic).
#[derive(Debug, Clone)]
pub struct HashMapStoreSnapshot {
    pub(crate) roots: HashMap<EntityId, Root>,
    pub(crate) workspaces: HashMap<EntityId, Workspace>,
    pub(crate) systems: HashMap<EntityId, System>,
    pub(crate) entities: HashMap<EntityId, Entity>,
    pub(crate) fields: HashMap<EntityId, Field>,
    pub(crate) features: HashMap<EntityId, Feature>,
    pub(crate) files: HashMap<EntityId, File>,
    pub(crate) use_cases: HashMap<EntityId, UseCase>,
    pub(crate) dtos: HashMap<EntityId, Dto>,
    pub(crate) dto_fields: HashMap<EntityId, DtoField>,
    pub(crate) globals: HashMap<EntityId, Global>,
    pub(crate) relationships: HashMap<EntityId, Relationship>,
    pub(crate) user_interfaces: HashMap<EntityId, UserInterface>,
    pub(crate) jn_system_from_root_system: HashMapJunction,
    pub(crate) jn_workspace_from_root_workspace: HashMapJunction,
    pub(crate) jn_entity_from_workspace_entities: HashMapJunction,
    pub(crate) jn_feature_from_workspace_features: HashMapJunction,
    pub(crate) jn_global_from_workspace_global: HashMapJunction,
    pub(crate) jn_user_interface_from_workspace_user_interface: HashMapJunction,
    pub(crate) jn_file_from_system_files: HashMapJunction,
    pub(crate) jn_field_from_entity_fields: HashMapJunction,
    pub(crate) jn_entity_from_entity_inherits_from: HashMapJunction,
    pub(crate) jn_relationship_from_entity_relationships: HashMapJunction,
    pub(crate) jn_entity_from_field_entity: HashMapJunction,
    pub(crate) jn_use_case_from_feature_use_cases: HashMapJunction,
    pub(crate) jn_entity_from_file_entity: HashMapJunction,
    pub(crate) jn_feature_from_file_feature: HashMapJunction,
    pub(crate) jn_field_from_file_field: HashMapJunction,
    pub(crate) jn_use_case_from_file_use_case: HashMapJunction,
    pub(crate) jn_dto_from_use_case_dto_in: HashMapJunction,
    pub(crate) jn_dto_from_use_case_dto_out: HashMapJunction,
    pub(crate) jn_entity_from_use_case_entities: HashMapJunction,
    pub(crate) jn_dto_field_from_dto_fields: HashMapJunction,
    pub(crate) jn_entity_from_relationship_left_entity: HashMapJunction,
    pub(crate) jn_entity_from_relationship_right_entity: HashMapJunction,
    counters: std::collections::HashMap<String, EntityId>,
}

impl StoreSnapshotTrait for HashMapStoreSnapshot {
    fn clone_box(&self) -> Box<dyn StoreSnapshotTrait> {
        Box::new(self.clone())
    }

    fn as_any(&self) -> &dyn std::any::Any {
        self
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// Junctions
// ─────────────────────────────────────────────────────────────────────────────

/// One relationship's junction: each source id mapped to its ordered target ids.
///
/// The junction of an *exclusive* relationship (one-to-one, one-to-many,
/// ordered one-to-many) also keeps a reverse index, target to the sources
/// holding it, so that "this target already belongs to another source" costs
/// one lookup per target of a write instead of a walk over every row of the
/// relationship. Without it, creating N rows that each own a child is O(N²).
///
/// The rows are private, so nothing can change them behind the index: every
/// mutation goes through [`Self::insert`], [`Self::remove`] or
/// [`Self::remove_target`], which update both in the same call, and a
/// whole-junction clone (snapshot, savepoint, [`HashMapStore::freeze`],
/// restore) carries both together. Both are `im::HashMap`s, so that clone
/// stays O(1).
///
/// The read methods mirror the map it wraps (`get`, `iter`, `contains_key`, …),
/// so code that only reads a junction reads it as before.
#[derive(Debug, Clone, Default)]
pub struct HashMapJunction {
    rows: HashMap<EntityId, Vec<EntityId>>,
    /// `None` for a shared relationship (many-to-one, many-to-many), which has
    /// no ownership rule to check. For an exclusive one, every source whose row
    /// holds the target, once per occurrence. A consistent store has exactly
    /// one; keeping a list makes the index exact even when a write that is not
    /// validated (a scoped undo restoring rows from its snapshot) leaves one
    /// target in two rows, so every check still answers exactly as a walk over
    /// the rows would.
    owners: Option<HashMap<EntityId, Vec<EntityId>>>,
}

impl HashMapJunction {
    /// An empty junction for an exclusive relationship, with its reverse index.
    pub fn exclusive() -> Self {
        Self {
            rows: HashMap::new(),
            owners: Some(HashMap::new()),
        }
    }

    /// An empty junction for a shared relationship, without a reverse index.
    pub fn shared() -> Self {
        Self::default()
    }

    /// Whether this junction belongs to an exclusive relationship.
    pub fn is_exclusive(&self) -> bool {
        self.owners.is_some()
    }

    /// The ordered targets of `source`, if it has a row.
    pub fn get(&self, source: &EntityId) -> Option<&Vec<EntityId>> {
        self.rows.get(source)
    }

    /// Whether `source` has a row (possibly empty).
    pub fn contains_key(&self, source: &EntityId) -> bool {
        self.rows.contains_key(source)
    }

    /// Every row, as `(source, targets)`, in no particular order.
    pub fn iter(&self) -> impl Iterator<Item = (&EntityId, &Vec<EntityId>)> {
        self.rows.iter()
    }

    /// Every source that has a row, in no particular order.
    pub fn keys(&self) -> impl Iterator<Item = &EntityId> {
        self.rows.keys()
    }

    /// Every row's targets, in no particular order.
    pub fn values(&self) -> impl Iterator<Item = &Vec<EntityId>> {
        self.rows.values()
    }

    /// The number of rows.
    pub fn len(&self) -> usize {
        self.rows.len()
    }

    /// Whether the junction has no row at all.
    pub fn is_empty(&self) -> bool {
        self.rows.is_empty()
    }

    /// Every source whose row holds `target`, once per occurrence: none or one
    /// in a consistent exclusive junction. One lookup on an exclusive junction;
    /// a walk over every row on a shared one, which has no index.
    pub fn sources_of(&self, target: &EntityId) -> Vec<EntityId> {
        match &self.owners {
            Some(owners) => owners.get(target).cloned().unwrap_or_default(),
            None => self
                .rows
                .iter()
                .flat_map(|(source, targets)| {
                    targets
                        .iter()
                        .filter(|t| *t == target)
                        .map(move |_| *source)
                })
                .collect(),
        }
    }

    /// Replace the row of `source` with `targets`, returning the previous row.
    pub fn insert(&mut self, source: EntityId, targets: Vec<EntityId>) -> Option<Vec<EntityId>> {
        if let Some(owners) = self.owners.as_mut() {
            let previous = self
                .rows
                .get(&source)
                .map(Vec::as_slice)
                .unwrap_or_default();
            reindex(owners, source, previous, &targets);
        }
        self.rows.insert(source, targets)
    }

    /// Remove the row of `source`, returning it.
    pub fn remove(&mut self, source: &EntityId) -> Option<Vec<EntityId>> {
        let removed = self.rows.remove(source)?;
        if let Some(owners) = self.owners.as_mut() {
            reindex(owners, *source, &removed, &[]);
        }
        Some(removed)
    }

    /// Remove `target` from every row holding it, as when the target entity is
    /// deleted. Visits only those rows on an exclusive junction, every row on a
    /// shared one.
    pub fn remove_target(&mut self, target: &EntityId) {
        let sources: Vec<EntityId> = match self.owners.as_mut() {
            Some(owners) => {
                let mut sources = owners.remove(target).unwrap_or_default();
                sources.sort_unstable();
                sources.dedup();
                sources
            }
            None => self
                .rows
                .iter()
                .filter(|(_, targets)| targets.contains(target))
                .map(|(source, _)| *source)
                .collect(),
        };
        for source in sources {
            if let Some(targets) = self.rows.get_mut(&source) {
                targets.retain(|t| t != target);
            }
        }
    }

    /// Compare the reverse index with one rebuilt from the rows.
    ///
    /// A diagnostic for tests, O(junction): see
    /// [`HashMapStore::check_junction_indexes`]. A shared junction has no index
    /// and always passes.
    pub fn check_index(&self) -> Result<(), String> {
        let Some(owners) = &self.owners else {
            return Ok(());
        };
        let mut expected: std::collections::HashMap<EntityId, Vec<EntityId>> =
            std::collections::HashMap::new();
        for (source, targets) in self.rows.iter() {
            for target in targets {
                expected.entry(*target).or_default().push(*source);
            }
        }
        if expected.len() != owners.len() {
            return Err(format!(
                "the reverse index lists {} targets but the rows hold {}",
                owners.len(),
                expected.len()
            ));
        }
        for (target, mut holders) in expected {
            let mut indexed = owners.get(&target).cloned().unwrap_or_default();
            holders.sort_unstable();
            indexed.sort_unstable();
            if holders != indexed {
                return Err(format!(
                    "target {target} is held by {holders:?} but indexed under {indexed:?}"
                ));
            }
        }
        Ok(())
    }
}

/// Move `source`'s entries in a reverse index from its `previous` targets to
/// its `next` ones. Only the difference is written, counted per occurrence, so
/// re-saving a long ordered list with one target appended (how a child is
/// added to its owner) updates one index entry, not one per child.
fn reindex(
    owners: &mut HashMap<EntityId, Vec<EntityId>>,
    source: EntityId,
    previous: &[EntityId],
    next: &[EntityId],
) {
    // A new row and a removed one need no difference: the common cases of
    // creating and deleting a source skip the scratch map below.
    if previous.is_empty() {
        for target in next {
            link(owners, source, *target, 1);
        }
        return;
    }
    if next.is_empty() {
        for target in previous {
            unlink(owners, source, *target, 1);
        }
        return;
    }
    if previous == next {
        return;
    }
    let mut delta: std::collections::HashMap<EntityId, isize> =
        std::collections::HashMap::with_capacity(previous.len() + next.len());
    for target in previous {
        *delta.entry(*target).or_default() -= 1;
    }
    for target in next {
        *delta.entry(*target).or_default() += 1;
    }
    for (target, change) in delta {
        if change > 0 {
            link(owners, source, target, change.unsigned_abs());
        } else if change < 0 {
            unlink(owners, source, target, change.unsigned_abs());
        }
    }
}

/// Record `count` more occurrences of `target` in the row of `source`.
fn link(
    owners: &mut HashMap<EntityId, Vec<EntityId>>,
    source: EntityId,
    target: EntityId,
    count: usize,
) {
    owners
        .entry(target)
        .or_default()
        .extend(std::iter::repeat_n(source, count));
}

/// Forget `count` occurrences of `target` in the row of `source`, dropping the
/// index entry once no row holds the target any more.
fn unlink(
    owners: &mut HashMap<EntityId, Vec<EntityId>>,
    source: EntityId,
    target: EntityId,
    count: usize,
) {
    let emptied = match owners.get_mut(&target) {
        Some(holders) => {
            for _ in 0..count {
                if let Some(at) = holders.iter().position(|h| *h == source) {
                    holders.swap_remove(at);
                }
            }
            holders.is_empty()
        }
        None => false,
    };
    if emptied {
        owners.remove(&target);
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// Helper functions
// ─────────────────────────────────────────────────────────────────────────────

/// Acquire a read guard, recovering the inner value if the lock was poisoned by
/// a panic elsewhere — and **clearing** the poison so recovery is permanent, not
/// one-shot (a recovered-but-still-poisoned lock would re-panic on the next plain
/// `.read()/.write().unwrap()`). Used throughout the store's own snapshot /
/// savepoint / restore paths so a single table poisoned by an unrelated panic
/// can't escalate a rollback (the Drop-time `restore_savepoint`) — or the very
/// next write transaction's `create_savepoint` — into a process-wide abort.
pub(crate) fn read_or_recover<T>(lock: &RwLock<T>) -> std::sync::RwLockReadGuard<'_, T> {
    match lock.read() {
        Ok(guard) => guard,
        Err(poisoned) => {
            let guard = poisoned.into_inner();
            lock.clear_poison();
            guard
        }
    }
}

/// Write-guard counterpart of [`read_or_recover`] (also clears the poison).
pub(crate) fn write_or_recover<T>(lock: &RwLock<T>) -> std::sync::RwLockWriteGuard<'_, T> {
    match lock.write() {
        Ok(guard) => guard,
        Err(poisoned) => {
            let guard = poisoned.into_inner();
            lock.clear_poison();
            guard
        }
    }
}

/// Remove `id` from every row of a junction that points at it (the entity `id`
/// is being deleted). See [`HashMapJunction::remove_target`].
pub(crate) fn delete_from_backward_junction(junction: &RwLock<HashMapJunction>, id: &EntityId) {
    write_or_recover(junction).remove_target(id);
}

pub(crate) fn junction_get(junction: &RwLock<HashMapJunction>, id: &EntityId) -> Vec<EntityId> {
    read_or_recover(junction)
        .get(id)
        .cloned()
        .unwrap_or_default()
}

pub(crate) fn junction_set(junction: &RwLock<HashMapJunction>, id: EntityId, ids: Vec<EntityId>) {
    write_or_recover(junction).insert(id, ids);
}

/// Validate a complete replacement batch before changing any junction rows.
/// Ownership exclusivity is per relationship, independently of cascade strength,
/// and belongs to the junction itself (see [`HashMapJunction::exclusive`]).
///
/// The cost follows the batch, never the junction: an exclusive target is
/// looked up in the reverse index, so a batch of k targets costs O(k) however
/// many rows the relationship holds, and a batch carrying no target at all
/// does not even take the junction's lock.
pub(crate) fn validate_junction_updates(
    junction: &RwLock<HashMapJunction>,
    replacements: &[(EntityId, Vec<EntityId>)],
    scalar: bool,
) -> Result<(), crate::error::RepositoryError> {
    use crate::error::RepositoryError::ConstraintViolation;
    use std::collections::HashSet;
    let mut owners = HashSet::new();
    for (owner, targets) in replacements {
        if !owners.insert(*owner) {
            return Err(ConstraintViolation(
                "duplicate source in relationship batch".into(),
            ));
        }
        if scalar && targets.len() > 1 {
            return Err(ConstraintViolation(
                "to-one relationship accepts at most one target".into(),
            ));
        }
        let mut unique = HashSet::new();
        if targets.iter().any(|id| !unique.insert(*id)) {
            return Err(ConstraintViolation("duplicate relationship target".into()));
        }
    }
    if replacements.iter().all(|(_, targets)| targets.is_empty()) {
        return Ok(());
    }
    let current = read_or_recover(junction);
    let Some(index) = current.owners.as_ref() else {
        // A shared relationship: any number of sources may hold a target.
        return Ok(());
    };
    // A target is taken when a source outside this batch holds it, or when two
    // rows of the batch both claim it. Sources in the batch are being replaced,
    // so moving a target between two of them within one batch is valid.
    let mut claimed = HashSet::new();
    for (_, targets) in replacements {
        for id in targets {
            let held_outside = index
                .get(id)
                .is_some_and(|holders| holders.iter().any(|holder| !owners.contains(holder)));
            if held_outside || !claimed.insert(*id) {
                return Err(ConstraintViolation(
                    "relationship target already belongs to another source".into(),
                ));
            }
        }
    }
    Ok(())
}

pub(crate) fn junction_remove(junction: &RwLock<HashMapJunction>, id: &EntityId) {
    write_or_recover(junction).remove(id);
}

pub(crate) fn junction_get_relationships_from_right_ids(
    junction: &RwLock<HashMapJunction>,
    right_ids: &[EntityId],
) -> Vec<(EntityId, Vec<EntityId>)> {
    let jn = read_or_recover(junction);
    jn.iter()
        .filter(|(_, rids)| right_ids.iter().any(|eid| rids.contains(eid)))
        .map(|(left_id, rids)| (*left_id, rids.clone()))
        .collect()
}

pub(crate) fn junction_move_ids(
    junction: &RwLock<HashMapJunction>,
    id: &EntityId,
    ids_to_move: &[EntityId],
    new_index: i32,
) -> Vec<EntityId> {
    let current = junction_get(junction, id);
    if ids_to_move.is_empty() {
        return current;
    }
    let move_set: std::collections::HashSet<EntityId> = ids_to_move.iter().copied().collect();
    let mut remaining: Vec<EntityId> = current
        .into_iter()
        .filter(|eid| !move_set.contains(eid))
        .collect();
    let insert_pos = if new_index < 0 || (new_index as usize) > remaining.len() {
        remaining.len()
    } else {
        new_index as usize
    };
    for (i, &eid) in ids_to_move.iter().enumerate() {
        remaining.insert(insert_pos + i, eid);
    }
    junction_set(junction, *id, remaining.clone());
    remaining
}

/// Surgically reconcile an external (out-of-scope) junction list during a scoped undo restore.
///
/// `live_list` is the current ordered value of an external referrer's junction row; `snap_list`
/// is the same row at snapshot time; `scope` is the set of subtree ids being restored. Only the
/// membership/position of `scope` ids is reconciled to match the snapshot — non-scope siblings are
/// preserved in their current relative order. Scope ids absent from the snapshot are removed
/// (undo-of-create); scope ids present in the snapshot are re-inserted at their snapshot-relative
/// position (undo-of-remove). This is what keeps undo from clobbering other trunks' edits.
pub(crate) fn reconcile_backref_list(
    live_list: &[EntityId],
    snap_list: &[EntityId],
    scope: &std::collections::HashSet<EntityId>,
) -> Vec<EntityId> {
    // Scope ids that should be present after restore, in snapshot order.
    let snap_members: Vec<EntityId> = snap_list
        .iter()
        .copied()
        .filter(|x| scope.contains(x))
        .collect();
    let snap_member_set: std::collections::HashSet<EntityId> =
        snap_members.iter().copied().collect();

    // Start from the live list, dropping only scope ids that are NOT in the snapshot.
    let mut work: Vec<EntityId> = live_list
        .iter()
        .copied()
        // De Morgan'd from `!(in_scope && !in_snapshot)`: same rule, stated the
        // way clippy's `nonminimal_bool` wants it, and arguably plainer — keep
        // anything outside the scope, plus anything the snapshot still holds.
        .filter(|x| !scope.contains(x) || snap_member_set.contains(x))
        .collect();

    // Re-insert missing scope ids at their snapshot-relative position (count of snapshot
    // predecessors that survive in `work`), so they return next to their original neighbours.
    for id in &snap_members {
        if work.contains(id) {
            continue;
        }
        let snap_idx = snap_list.iter().position(|x| x == id).unwrap_or(0);
        let pos = snap_list[..snap_idx]
            .iter()
            .filter(|x| work.contains(x))
            .count()
            .min(work.len());
        work.insert(pos, *id);
    }
    work
}

// ═════════════════════════════════════════════════════════════════════════════
// Macros for entities WITH relationships (reduces boilerplate)
// ═════════════════════════════════════════════════════════════════════════════

/// Generate standard relationship methods for a HashMap table implementation.
#[macro_export]
macro_rules! impl_relationship_methods {
    ($table_type:ty, $field_enum:ty) => {
        fn get_relationship(
            &self,
            id: &$crate::types::EntityId,
            field: &$field_enum,
        ) -> Result<Vec<$crate::types::EntityId>, $crate::error::RepositoryError> {
            Ok($crate::database::hashmap_store::junction_get(
                self.resolve_junction(field),
                id,
            ))
        }

        fn get_relationship_many(
            &self,
            ids: &[$crate::types::EntityId],
            field: &$field_enum,
        ) -> Result<
            std::collections::HashMap<$crate::types::EntityId, Vec<$crate::types::EntityId>>,
            $crate::error::RepositoryError,
        > {
            let jn = self.resolve_junction(field);
            let mut map = std::collections::HashMap::new();
            for id in ids {
                map.insert(*id, $crate::database::hashmap_store::junction_get(jn, id));
            }
            Ok(map)
        }

        fn get_relationship_count(
            &self,
            id: &$crate::types::EntityId,
            field: &$field_enum,
        ) -> Result<usize, $crate::error::RepositoryError> {
            Ok(
                $crate::database::hashmap_store::junction_get(self.resolve_junction(field), id)
                    .len(),
            )
        }

        fn get_relationship_in_range(
            &self,
            id: &$crate::types::EntityId,
            field: &$field_enum,
            offset: usize,
            limit: usize,
        ) -> Result<Vec<$crate::types::EntityId>, $crate::error::RepositoryError> {
            let all =
                $crate::database::hashmap_store::junction_get(self.resolve_junction(field), id);
            Ok(all.into_iter().skip(offset).take(limit).collect())
        }

        fn get_relationships_from_right_ids(
            &self,
            field: &$field_enum,
            right_ids: &[$crate::types::EntityId],
        ) -> Result<
            Vec<($crate::types::EntityId, Vec<$crate::types::EntityId>)>,
            $crate::error::RepositoryError,
        > {
            Ok(
                $crate::database::hashmap_store::junction_get_relationships_from_right_ids(
                    self.resolve_junction(field),
                    right_ids,
                ),
            )
        }
    };
}

#[macro_export]
macro_rules! impl_write_relationship_methods {
    ($table_type:ty, $field_enum:ty) => {
        $crate::impl_relationship_methods!($table_type, $field_enum);

        fn set_relationship_multi(
            &mut self,
            field: &$field_enum,
            relationships: Vec<($crate::types::EntityId, Vec<$crate::types::EntityId>)>,
        ) -> Result<(), $crate::error::RepositoryError> {
            for (id, _) in &relationships {
                if !self.relationship_source_exists(id) {
                    return Err($crate::error::RepositoryError::ConstraintViolation(
                        "relationship source does not exist".into(),
                    ));
                }
            }
            self.validate_relationship_updates(field, &relationships, &[])?;
            let jn = self.resolve_junction(field);
            for (left_id, entities) in relationships {
                $crate::database::hashmap_store::junction_set(jn, left_id, entities);
            }
            Ok(())
        }

        fn set_relationship(
            &mut self,
            id: &$crate::types::EntityId,
            field: &$field_enum,
            right_ids: &[$crate::types::EntityId],
        ) -> Result<(), $crate::error::RepositoryError> {
            self.set_relationship_multi(field, vec![(*id, right_ids.to_vec())])
        }

        fn move_relationship_ids(
            &mut self,
            id: &$crate::types::EntityId,
            field: &$field_enum,
            ids_to_move: &[$crate::types::EntityId],
            new_index: i32,
        ) -> Result<Vec<$crate::types::EntityId>, $crate::error::RepositoryError> {
            if !self.relationship_is_ordered(field) {
                return Err($crate::error::RepositoryError::ConstraintViolation(
                    "only ordered relationships can be moved".into(),
                ));
            }
            let current =
                $crate::database::hashmap_store::junction_get(self.resolve_junction(field), id);
            let mut seen = std::collections::HashSet::new();
            if ids_to_move
                .iter()
                .any(|target| !seen.insert(*target) || !current.contains(target))
            {
                return Err($crate::error::RepositoryError::ConstraintViolation(
                    "move requires distinct existing relationship members".into(),
                ));
            }
            self.validate_relationship_updates(field, &[(*id, current)], &[])?;
            if !self.relationship_source_exists(id) {
                return Err($crate::error::RepositoryError::ConstraintViolation(
                    "relationship source does not exist".into(),
                ));
            }
            Ok($crate::database::hashmap_store::junction_move_ids(
                self.resolve_junction(field),
                id,
                ids_to_move,
                new_index,
            ))
        }
    };
}

// ═════════════════════════════════════════════════════════════════════════════
// Leaf entity macro (entities without forward relationships)
// ═════════════════════════════════════════════════════════════════════════════

#[macro_export]
macro_rules! impl_leaf_entity_table {
    (
        entity: $Entity:ident,
        entity_name: $entity_name:expr,
        store_field: $store_field:ident,
        table_trait: $TableTrait:ident,
        table_ro_trait: $TableROTrait:ident,
        table_struct: $TableStruct:ident,
        table_ro_struct: $TableROStruct:ident,
        backward_junctions: [ $( ($bj_field:ident) ),* $(,)? ],
    ) => {
        pub struct $TableStruct<'a> {
            store: &'a $crate::database::hashmap_store::HashMapStore,
        }

        impl<'a> $TableStruct<'a> {
            pub fn new(store: &'a $crate::database::hashmap_store::HashMapStore) -> Self {
                Self { store }
            }
        }

        impl<'a> $TableTrait for $TableStruct<'a> {
            fn create(&mut self, entity: &$Entity) -> Result<$Entity, $crate::error::RepositoryError> {
                self.create_multi(std::slice::from_ref(entity))
                    .and_then(|v| {
                        v.into_iter().next().ok_or_else(|| {
                            $crate::error::RepositoryError::Other(::anyhow::anyhow!(
                                "create: the store returned no row for the entity it was given"
                            ))
                        })
                    })
            }

            fn create_multi(&mut self, entities: &[$Entity]) -> Result<Vec<$Entity>, $crate::error::RepositoryError> {
                let mut created = Vec::with_capacity(entities.len());
                let mut map = $crate::database::hashmap_store::write_or_recover(&self.store.$store_field);

                for entity in entities {
                    let new_entity = if entity.id == $crate::types::EntityId::default() {
                        let id = self.store.next_id($entity_name);
                        $Entity {
                            id,
                            ..entity.clone()
                        }
                    } else {
                        if map.contains_key(&entity.id) {
                            return Err($crate::error::RepositoryError::DuplicateId {
                                entity: stringify!($Entity),
                                id: entity.id,
                            });
                        }
                        entity.clone()
                    };

                    map.insert(new_entity.id, new_entity.clone());
                    created.push(new_entity);
                }
                Ok(created)
            }

            fn get(&self, id: &$crate::types::EntityId) -> Result<Option<$Entity>, $crate::error::RepositoryError> {
                Ok($crate::database::hashmap_store::read_or_recover(&self.store.$store_field).get(id).cloned())
            }

            fn get_multi(&self, ids: &[$crate::types::EntityId]) -> Result<Vec<Option<$Entity>>, $crate::error::RepositoryError> {
                let map = $crate::database::hashmap_store::read_or_recover(&self.store.$store_field);
                Ok(ids.iter().map(|id| map.get(id).cloned()).collect())
            }

            fn get_all(&self) -> Result<Vec<$Entity>, $crate::error::RepositoryError> {
                Ok($crate::database::hashmap_store::read_or_recover(&self.store.$store_field).values().cloned().collect())
            }

            fn update(&mut self, entity: &$Entity) -> Result<$Entity, $crate::error::RepositoryError> {
                self.update_multi(std::slice::from_ref(entity))
                    .and_then(|v| {
                        v.into_iter().next().ok_or_else(|| {
                            $crate::error::RepositoryError::Other(::anyhow::anyhow!(
                                "update: the store returned no row for the entity it was given"
                            ))
                        })
                    })
            }

            fn update_multi(&mut self, entities: &[$Entity]) -> Result<Vec<$Entity>, $crate::error::RepositoryError> {
                let mut map = $crate::database::hashmap_store::write_or_recover(&self.store.$store_field);
                let mut result = Vec::with_capacity(entities.len());
                for entity in entities {
                    map.insert(entity.id, entity.clone());
                    result.push(entity.clone());
                }
                Ok(result)
            }

            fn update_with_relationships(&mut self, entity: &$Entity) -> Result<$Entity, $crate::error::RepositoryError> {
                self.update(entity)
            }

            fn update_with_relationships_multi(&mut self, entities: &[$Entity]) -> Result<Vec<$Entity>, $crate::error::RepositoryError> {
                self.update_multi(entities)
            }

            fn remove(&mut self, id: &$crate::types::EntityId) -> Result<(), $crate::error::RepositoryError> {
                self.remove_multi(std::slice::from_ref(id))
            }

            fn remove_multi(&mut self, ids: &[$crate::types::EntityId]) -> Result<(), $crate::error::RepositoryError> {
                let mut map = $crate::database::hashmap_store::write_or_recover(&self.store.$store_field);
                for id in ids {
                    map.remove(id);
                    $(
                        $crate::database::hashmap_store::delete_from_backward_junction(&self.store.$bj_field, id);
                    )*
                }
                Ok(())
            }
        }

        pub struct $TableROStruct<'a> {
            store: &'a $crate::database::hashmap_store::HashMapStore,
        }

        impl<'a> $TableROStruct<'a> {
            pub fn new(store: &'a $crate::database::hashmap_store::HashMapStore) -> Self {
                Self { store }
            }
        }

        impl<'a> $TableROTrait for $TableROStruct<'a> {
            fn get(&self, id: &$crate::types::EntityId) -> Result<Option<$Entity>, $crate::error::RepositoryError> {
                Ok($crate::database::hashmap_store::read_or_recover(&self.store.$store_field).get(id).cloned())
            }

            fn get_multi(&self, ids: &[$crate::types::EntityId]) -> Result<Vec<Option<$Entity>>, $crate::error::RepositoryError> {
                let map = $crate::database::hashmap_store::read_or_recover(&self.store.$store_field);
                Ok(ids.iter().map(|id| map.get(id).cloned()).collect())
            }

            fn get_all(&self) -> Result<Vec<$Entity>, $crate::error::RepositoryError> {
                Ok($crate::database::hashmap_store::read_or_recover(&self.store.$store_field).values().cloned().collect())
            }
        }
    };
}

// ═════════════════════════════════════════════════════════════════════════════
// Junction index tests (entity-independent, so generated into every project)
// ═════════════════════════════════════════════════════════════════════════════

#[cfg(test)]
mod junction_tests {
    use super::*;
    use crate::error::RepositoryError;

    /// The 2.0.0 check, kept verbatim as the reference: it walks every row of
    /// the junction that is not being replaced. The indexed check must give
    /// the same answer for every junction and every batch.
    fn validate_by_walking(
        junction: &HashMapJunction,
        replacements: &[(EntityId, Vec<EntityId>)],
        scalar: bool,
    ) -> Result<(), RepositoryError> {
        use RepositoryError::ConstraintViolation;
        use std::collections::HashSet;
        let mut owners = HashSet::new();
        for (owner, targets) in replacements {
            if !owners.insert(*owner) {
                return Err(ConstraintViolation(
                    "duplicate source in relationship batch".into(),
                ));
            }
            if scalar && targets.len() > 1 {
                return Err(ConstraintViolation(
                    "to-one relationship accepts at most one target".into(),
                ));
            }
            let mut unique = HashSet::new();
            if targets.iter().any(|id| !unique.insert(*id)) {
                return Err(ConstraintViolation("duplicate relationship target".into()));
            }
        }
        if junction.is_exclusive() {
            let mut used = HashSet::new();
            for (_, targets) in junction.iter().filter(|(id, _)| !owners.contains(id)) {
                used.extend(targets.iter().copied());
            }
            for (_, targets) in replacements {
                if targets.iter().any(|id| !used.insert(*id)) {
                    return Err(ConstraintViolation(
                        "relationship target already belongs to another source".into(),
                    ));
                }
            }
        }
        Ok(())
    }

    /// xorshift64: deterministic, so a failure replays exactly.
    struct Rng(u64);

    impl Rng {
        fn below(&mut self, bound: u64) -> u64 {
            self.0 ^= self.0 << 13;
            self.0 ^= self.0 >> 7;
            self.0 ^= self.0 << 17;
            self.0 % bound
        }

        fn ids(&mut self, max_len: u64, bound: u64) -> Vec<EntityId> {
            (0..self.below(max_len + 1))
                .map(|_| self.below(bound))
                .collect()
        }
    }

    /// Drive every writer at random, including the unvalidated ones a scoped
    /// undo uses, so rows may share a target or repeat one. After each step the
    /// index must equal a rebuild from the rows, and the indexed check must
    /// answer a random batch exactly as the walk does.
    #[test]
    fn the_index_stays_exact_and_the_check_matches_the_walk() {
        for exclusive in [true, false] {
            let mut rng = Rng(0x9E37_79B9_7F4A_7C15 + u64::from(exclusive));
            let junction = RwLock::new(if exclusive {
                HashMapJunction::exclusive()
            } else {
                HashMapJunction::shared()
            });
            for step in 0..3000 {
                {
                    let mut jn = write_or_recover(&junction);
                    match rng.below(6) {
                        0..=2 => {
                            let (source, targets) = (rng.below(12), rng.ids(4, 16));
                            jn.insert(source, targets);
                        }
                        3 => {
                            jn.remove(&rng.below(12));
                        }
                        4 => jn.remove_target(&rng.below(16)),
                        // What snapshot, savepoint and restore do: swap in a clone.
                        _ => {
                            let copy = jn.clone();
                            *jn = copy;
                        }
                    }
                    if let Err(problem) = jn.check_index() {
                        panic!("exclusive={exclusive}, step {step}: {problem}");
                    }
                }
                let batch: Vec<(EntityId, Vec<EntityId>)> = (0..=rng.below(3))
                    .map(|_| (rng.below(12), rng.ids(2, 16)))
                    .collect();
                for scalar in [false, true] {
                    let walked = validate_by_walking(&read_or_recover(&junction), &batch, scalar);
                    let indexed = validate_junction_updates(&junction, &batch, scalar);
                    assert_eq!(
                        format!("{indexed:?}"),
                        format!("{walked:?}"),
                        "exclusive={exclusive}, step {step}, scalar={scalar}, batch {batch:?}"
                    );
                }
            }
        }
    }

    #[test]
    fn a_transfer_within_one_batch_is_valid_but_not_from_outside_it() {
        let junction = RwLock::new(HashMapJunction::exclusive());
        junction_set(&junction, 1, vec![10, 11]);
        junction_set(&junction, 2, vec![20]);
        let check = |batch: &[(EntityId, Vec<EntityId>)]| {
            validate_junction_updates(&junction, batch, false)
        };
        assert!(check(&[(1, vec![11]), (2, vec![20, 10])]).is_ok());
        assert!(check(&[(2, vec![20, 10])]).is_err());
        assert!(check(&[(3, vec![10])]).is_err());
        assert!(check(&[(1, vec![]), (2, vec![10]), (3, vec![10])]).is_err());
        // Nothing to place: valid however full the junction is.
        assert!(check(&[(3, vec![]), (4, vec![])]).is_ok());
        // Deleting the owner, or the target, frees the target.
        junction_remove(&junction, &1);
        assert!(check(&[(3, vec![10])]).is_ok());
        delete_from_backward_junction(&junction, &20);
        assert!(check(&[(3, vec![20])]).is_ok());
        assert_eq!(junction_get(&junction, &2), Vec::<EntityId>::new());
        assert!(read_or_recover(&junction).check_index().is_ok());
    }
}