perf: add ephemeral entity indexes
This commit is contained in:
parent
40b4bc1a35
commit
f36a339d5c
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
}
|
||||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
Loading…
Reference in New Issue