diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index 7cd0115..0f0dfde 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -246,6 +246,8 @@ These require user approval and are not part of the current implementation: - [x] Replace duplicated epoch/layer comparison code with a deterministic, serializable `WorldDiff`, changed-field details, importance marks, and a buffered CLI renderer (tracker issues #11 and part of #10). +- [x] Add ephemeral UUID/name `EntityIndex` lookup and duplicate detection while + preserving ordered vectors as the stable repository representation (#6). - [ ] Tracker issue #13 is intentionally deferred at the maintainer's request. - The old README described organisation/link/event interfaces absent from the diff --git a/docs/issue-audit.md b/docs/issue-audit.md index b9b7490..837ff89 100644 --- a/docs/issue-audit.md +++ b/docs/issue-audit.md @@ -20,7 +20,7 @@ absent. | [#10 Display functions](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/10) | Partially addressed: unified show routing and three detail levels are coherent, and every diff is rendered into a buffer before one output write. Older entity renderers still print directly. | Finish the writer/buffer boundary for `show`. | | [#9 Adding influx](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/9) | Open and underspecified. | Define versioned deterministic severity and avoidance rules before commands. | | [#8 Event diffusion](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/8) | Planned in the simulation roadmap; blocked on roads, residency, and deterministic routing. | Complete simulation checkpoints 2–3 in order. | -| [#6 HashMap/HashSet](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/6) | Vectors remain the stable serialized representation; replacing them would churn the format. | Add ephemeral UUID/name indexes only if profiling justifies them. | +| [#6 HashMap/HashSet](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/6) | Addressed without format churn: `EntityIndex` provides ephemeral UUID/name hash indexes and duplicate-ID detection over the stable vector representation. Repository validation uses the index and hash lookup for relationships. | Rebuild indexes after mutation; never persist them. | Preferred order: finish display buffering/structured output and custom fields, implement roads/residency, then build influx, diff --git a/lib_efo/src/epoch.rs b/lib_efo/src/epoch.rs index bf58b16..a727515 100644 --- a/lib_efo/src/epoch.rs +++ b/lib_efo/src/epoch.rs @@ -33,6 +33,8 @@ pub use epoch_config::EpochConfig; pub mod epoch_info; pub use epoch_info::EpochInfo; +pub mod index; +pub use index::{EntityIndex, EntityLocation}; pub mod epoch_traits; // TODO(5): Try to load from a config and have it inserted as a backup diff --git a/lib_efo/src/epoch/index.rs b/lib_efo/src/epoch/index.rs new file mode 100644 index 0000000..a1ffa78 --- /dev/null +++ b/lib_efo/src/epoch/index.rs @@ -0,0 +1,112 @@ +//! Ephemeral indexes over the vector-backed persisted world. +//! +//! Repository files deliberately retain ordered vectors for compatibility and +//! deterministic output. `EntityIndex` can be rebuilt cheaply after a world +//! mutation and gives read-heavy operations hash-based exact lookup without +//! becoming another piece of state that can go stale on disk. + +use std::collections::{HashMap, HashSet}; + +use uuid::Uuid; + +use crate::{entity::Entity, stats::EntityType}; + +use super::EpochInfo; + +/// An entity's stable collection and current offset within that collection. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub struct EntityLocation { + /// Persisted entity collection. + pub entity_type: EntityType, + /// Offset in the collection's vector. + pub index: usize, +} + +/// A rebuildable UUID and normalized-name index for one world snapshot. +#[derive(Debug, Clone, Default)] +pub struct EntityIndex { + /// First location seen for each UUID. + by_id: HashMap, + /// Every location sharing the same case-insensitive name. + by_name: HashMap>, + /// UUIDs occurring more than once across any collection. + duplicate_ids: HashSet, +} + +impl EntityIndex { + /// Build an index without changing the world or its serialized form. + #[must_use] + pub fn build(world: &EpochInfo) -> Self { + let mut result = Self::default(); + for entity_type in [ + EntityType::Character, + EntityType::Town, + EntityType::Event, + EntityType::Calamity, + EntityType::Organization, + EntityType::Blocker, + ] { + for (index, entity) in world.vec_entities(&entity_type).iter().enumerate() { + let location = EntityLocation { entity_type, index }; + if result.by_id.insert(entity.id, location).is_some() { + result.duplicate_ids.insert(entity.id); + } + result + .by_name + .entry(normalize_name(&entity.name)) + .or_default() + .push(location); + } + } + result + } + + /// Return the indexed location for an exact UUID. + #[must_use] + pub fn location_by_id(&self, id: Uuid) -> Option { + self.by_id.get(&id).copied() + } + + /// Return every entity whose full name matches case-insensitively. + #[must_use] + pub fn locations_by_name(&self, name: &str) -> &[EntityLocation] { + self.by_name + .get(&normalize_name(name)) + .map_or(&[], Vec::as_slice) + } + + /// Resolve a previously indexed location against the unchanged world. + #[must_use] + pub fn resolve<'world>( + &self, + world: &'world EpochInfo, + location: EntityLocation, + ) -> Option<&'world Entity> { + world + .vec_entities(&location.entity_type) + .get(location.index) + } + + /// UUIDs that occur more than once, in unspecified order. + #[must_use] + pub fn duplicate_ids(&self) -> &HashSet { + &self.duplicate_ids + } + + /// Number of unique UUID keys in the index. + #[must_use] + pub fn len(&self) -> usize { + self.by_id.len() + } + + /// Whether the index contains no entities. + #[must_use] + pub fn is_empty(&self) -> bool { + self.by_id.is_empty() + } +} + +/// Normalize human names for exact case-insensitive lookup. +fn normalize_name(name: &str) -> String { + name.trim().to_lowercase() +} diff --git a/lib_efo/src/stats.rs b/lib_efo/src/stats.rs index ce38cb9..525665d 100644 --- a/lib_efo/src/stats.rs +++ b/lib_efo/src/stats.rs @@ -623,7 +623,7 @@ pub enum ListStats { /// The list of all types of entities #[allow(missing_docs)] -#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Default)] +#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Hash, Default)] pub enum EntityType { Character, Player, diff --git a/lib_efo/src/workspace.rs b/lib_efo/src/workspace.rs index 9e079c0..7d9ce59 100644 --- a/lib_efo/src/workspace.rs +++ b/lib_efo/src/workspace.rs @@ -1,7 +1,7 @@ //! Format-2 HEAD, index, and worktree access. use std::{ - collections::BTreeMap, + collections::{BTreeMap, HashMap}, fs, path::{Path, PathBuf}, time::{SystemTime, UNIX_EPOCH}, @@ -12,7 +12,7 @@ use uuid::Uuid; use crate::{ entity::EntityIdentifier, - epoch::EpochInfo, + epoch::{EntityIndex, EpochInfo}, repository_format::{FormatError, RepositoryManifest, RepositorySnapshot, decode_manifest}, stats::EntityType, transaction::{ @@ -824,7 +824,13 @@ fn copy_world_metadata(source: &EpochInfo, destination: &mut EpochInfo) { /// Validate stable identity, collection type, and relationship targets. fn validate_world(label: &str, world: &EpochInfo) -> Result<(), WorkspaceError> { - let mut identities = BTreeMap::new(); + let index = EntityIndex::build(world); + if !index.duplicate_ids().is_empty() { + return Err(WorkspaceError::Inconsistent(format!( + "{label} contains a duplicate entity UUID" + ))); + } + let mut identities = HashMap::new(); for (entities, expected) in [ (&world.characters, EntityType::Character), (&world.towns, EntityType::Town), @@ -834,11 +840,12 @@ fn validate_world(label: &str, world: &EpochInfo) -> Result<(), WorkspaceError> (&world.blockers, EntityType::Blocker), ] { for entity in entities { - if entity.id.is_nil() || identities.insert(entity.id, expected).is_some() { + if entity.id.is_nil() { return Err(WorkspaceError::Inconsistent(format!( - "{label} contains a missing or duplicate entity UUID" + "{label} contains a missing entity UUID" ))); } + identities.insert(entity.id, expected); if entity.entity_type != expected { return Err(WorkspaceError::Inconsistent(format!( "{label} stores `{}` in the wrong collection", diff --git a/lib_efo/tests/entity_index.rs b/lib_efo/tests/entity_index.rs new file mode 100644 index 0000000..89b1485 --- /dev/null +++ b/lib_efo/tests/entity_index.rs @@ -0,0 +1,50 @@ +use lib_efo::{ + entity::Entity, + epoch::{EntityIndex, EpochInfo}, + stats::EntityType, +}; +use uuid::Uuid; + +fn entity(id: u128, name: &str, entity_type: EntityType) -> Entity { + let mut entity = Entity::default(); + entity.id = Uuid::from_u128(id); + entity.name = name.into(); + entity.entity_type = entity_type; + entity +} + +#[test] +fn index_resolves_ids_and_case_insensitive_names_without_serialized_state() { + let mut world = EpochInfo::default(); + world + .characters + .push(entity(1, " Aria ", EntityType::Character)); + world.towns.push(entity(2, "Haven", EntityType::Town)); + + let index = EntityIndex::build(&world); + let aria = index.location_by_id(Uuid::from_u128(1)).expect("UUID"); + assert_eq!(index.resolve(&world, aria).expect("entity").name, " Aria "); + assert_eq!(index.locations_by_name("ARIA"), &[aria]); + assert_eq!(index.len(), 2); + assert!(index.duplicate_ids().is_empty()); + + let serialized = serde_json::to_value(&world).expect("serialize world"); + assert!(serialized.get("by_id").is_none()); + assert!(serialized.get("by_name").is_none()); +} + +#[test] +fn index_reports_duplicate_ids_and_ambiguous_names() { + let mut world = EpochInfo::default(); + world.events.push(entity(9, "The Fall", EntityType::Event)); + world + .calamities + .push(entity(9, "the fall", EntityType::Calamity)); + + let index = EntityIndex::build(&world); + assert_eq!(index.len(), 1); + assert_eq!(index.locations_by_name("the fall").len(), 2); + assert_eq!(index.duplicate_ids(), &HashSet::from([Uuid::from_u128(9)])); +} + +use std::collections::HashSet;