perf: add ephemeral entity indexes

This commit is contained in:
Dandaedre 2026-09-22 00:29:21 +02:00
parent 40b4bc1a35
commit f36a339d5c
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
7 changed files with 180 additions and 7 deletions

View File

@ -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

View File

@ -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,

View File

@ -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

112
lib_efo/src/epoch/index.rs Normal file
View File

@ -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<Uuid, EntityLocation>,
/// Every location sharing the same case-insensitive name.
by_name: HashMap<String, Vec<EntityLocation>>,
/// UUIDs occurring more than once across any collection.
duplicate_ids: HashSet<Uuid>,
}
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<EntityLocation> {
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<Uuid> {
&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()
}

View File

@ -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,

View File

@ -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",

View File

@ -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;