diff --git a/.run_status.toml b/.run_status.toml
index e67f0d2..9355a43 100644
--- a/.run_status.toml
+++ b/.run_status.toml
@@ -1,8 +1,16 @@
[last_run_clean]
run_status = "Success"
-lines_parsed = 110
-coverage = 48.83
+lines_parsed = 5
[last_run_clean.run_duration]
-secs = 27
-nanos = 30003945
+secs = 0
+nanos = 55273825
+
+[last_run_incremental]
+run_status = "Success"
+lines_parsed = 174
+coverage = 78.44
+
+[last_run_incremental.run_duration]
+secs = 6
+nanos = 681584522
diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md
index 57122eb..7a984c6 100644
--- a/AGENTS-TASKS.md
+++ b/AGENTS-TASKS.md
@@ -249,3 +249,7 @@ These require user approval and are not part of the current implementation:
- The milestone-only `rust_autobadges` run was attempted, but this installed
version misreported passing tests as failing and coverage as unavailable.
Its false generated badges were discarded; the prior badges were preserved.
+- [x] Add focused `EpochInfo` collection, lookup, link, replacement, and
+ position tests; document and provide a runnable `lib_efo` repository example.
+- [x] Configure Tarpaulin around its subprocess-attribution limitation and
+ refresh `rust_autobadges` at a directly measured coverage level above 70%.
diff --git a/README.md b/README.md
index dc4156a..362b818 100644
--- a/README.md
+++ b/README.md
@@ -96,6 +96,21 @@ glyphs. Press `?` for its complete keyboard reference.
## Development
+### Library example
+
+`lib_efo` exposes repository initialization and the complete HEAD/index/worktree
+model without going through the CLI. To create a repository in an existing
+empty directory and inspect its initial epoch:
+
+```bash
+mkdir /tmp/epoch-forge-example
+cargo run -p lib_efo --example repository -- /tmp/epoch-forge-example
+```
+
+See [`lib_efo/examples/repository.rs`](lib_efo/examples/repository.rs) for the
+complete program. Mutations should use `Workspace` methods so they retain the
+same transactional guarantees as `efo`.
+
```bash
cargo fmt --all -- --check
cargo test --workspace --all-targets --all-features --locked
@@ -104,7 +119,9 @@ cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
Tarpaulin and `rust_autobadges` are intentionally release-only. They do not run
in routine CI because of their cost; badge files are refreshed for significant
-releases.
+releases. The Tarpaulin configuration excludes the thin CLI adapters because
+their subprocess integration tests cannot be attributed reliably by its ptrace
+backend; library and TUI code remain directly measured.
## Release archives
diff --git a/badges/coverage.svg b/badges/coverage.svg
index 0db759b..6eab54f 100644
--- a/badges/coverage.svg
+++ b/badges/coverage.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/docs/architecture.md b/docs/architecture.md
index aff660c..2440729 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -30,8 +30,10 @@ version 1.0; its structured major/minor discriminator leaves room for explicit
The approved [first-pass TUI contract](tui-design.md) adds a separate read-only
repository browser without creating another persistence path.
-Library tests currently cover parsing, statistics, display snapshots, and parts
-of entity/epoch behavior. CLI integration coverage is the main gap. Routine CI
+Library tests cover parsing, statistics, display snapshots, entity/epoch
+behavior, and repository transactions. CLI behavior is covered by subprocess
+integration workflows; Tarpaulin excludes those thin adapters because its
+ptrace backend cannot reliably attribute child-process execution. Routine CI
should run formatting, all-target workspace tests, strict Clippy, and a release
build. Tarpaulin and `rust_autobadges` remain local significant-release-only
tools. See [AGENTS.md](../AGENTS.md) for contributor rules.
diff --git a/lib_efo/examples/repository.rs b/lib_efo/examples/repository.rs
new file mode 100644
index 0000000..ef8b285
--- /dev/null
+++ b/lib_efo/examples/repository.rs
@@ -0,0 +1,21 @@
+//! Initialise a repository and inspect its initial world through `lib_efo`.
+
+use std::{env, error::Error, path::PathBuf};
+
+use lib_efo::workspace::Workspace;
+
+fn main() -> Result<(), Box> {
+ let root = env::args_os()
+ .nth(1)
+ .map(PathBuf::from)
+ .ok_or("usage: cargo run -p lib_efo --example repository -- ")?;
+
+ let mut workspace = Workspace::initialize(&root, env!("CARGO_PKG_VERSION"))?;
+ println!("repository: {}", workspace.root().display());
+ println!("current epoch: {}", workspace.head.epoch_id);
+ println!(
+ "entities: {}",
+ workspace.head.iter_all_entities_mut().count()
+ );
+ Ok(())
+}
diff --git a/lib_efo/src/epoch/epoch_info.rs b/lib_efo/src/epoch/epoch_info.rs
index 38d5a9e..8f96a1e 100644
--- a/lib_efo/src/epoch/epoch_info.rs
+++ b/lib_efo/src/epoch/epoch_info.rs
@@ -403,3 +403,174 @@ impl Symbols for EpochId {
format!("[{} {:<2}]", crate::output::symbol("", "epoch"), self)
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::stats::Role;
+
+ 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
+ }
+
+ fn populated_epoch() -> EpochInfo {
+ let mut epoch = EpochInfo::default();
+ epoch
+ .events
+ .push(entity(1, "Coronation", EntityType::Event));
+ epoch
+ .characters
+ .push(entity(2, "Aria", EntityType::Character));
+ epoch
+ .organizations
+ .push(entity(3, "Guild", EntityType::Organization));
+ epoch.towns.push(entity(4, "Haven", EntityType::Town));
+ epoch
+ .calamities
+ .push(entity(5, "Flood", EntityType::Calamity));
+ epoch.blockers.push(entity(6, "Gate", EntityType::Blocker));
+ epoch
+ }
+
+ #[test]
+ fn entity_collections_are_selected_for_every_stored_type() {
+ let mut epoch = populated_epoch();
+ for entity_type in [
+ EntityType::Event,
+ EntityType::Character,
+ EntityType::Organization,
+ EntityType::Town,
+ EntityType::Calamity,
+ EntityType::Blocker,
+ ] {
+ assert_eq!(epoch.vec_entities(&entity_type).len(), 1);
+ epoch.vec_entities_mut(&entity_type)[0].description = "visited".into();
+ }
+ assert_eq!(
+ epoch
+ .iter_all_entities_mut()
+ .filter(|entity| entity.description == "visited")
+ .count(),
+ 6
+ );
+ }
+
+ #[test]
+ fn lookup_supports_names_prefixes_ids_and_strict_types() {
+ let mut epoch = populated_epoch();
+ assert_eq!(
+ epoch
+ .find_any_entity(EntityIdentifier::Name("ar".into()))
+ .expect("name prefix")
+ .name,
+ "Aria"
+ );
+ assert_eq!(
+ epoch
+ .find_any_entity(EntityIdentifier::Id("00000000-0000".into()))
+ .expect("id prefix")
+ .name,
+ "Coronation"
+ );
+ assert_eq!(
+ epoch
+ .find_entity_of_type(
+ &Some(EntityIdentifier::Name("hav".into())),
+ &EntityType::Town,
+ )
+ .expect("typed lookup")
+ .id,
+ Uuid::from_u128(4)
+ );
+ assert!(
+ epoch
+ .find_entity_strict(Uuid::from_u128(4), Some(EntityType::Character))
+ .is_err()
+ );
+ epoch
+ .find_entity_strict_as_mut(Uuid::from_u128(4), None)
+ .expect("mutable lookup")
+ .name = "New Haven".into();
+ assert_eq!(
+ epoch
+ .find_entity_strict(Uuid::from_u128(4), Some(EntityType::Town))
+ .expect("strict lookup")
+ .name,
+ "New Haven"
+ );
+ assert!(
+ epoch
+ .find_any_entity(EntityIdentifier::Name("missing".into()))
+ .is_err()
+ );
+ }
+
+ #[test]
+ fn link_remove_and_swap_operations_preserve_collection_integrity() {
+ let mut epoch = populated_epoch();
+ let link = TypedLink::new(Uuid::from_u128(4), Role::Capital, EntityType::Town);
+ epoch
+ .add_to_links(Uuid::from_u128(2), &EntityType::Character, link)
+ .expect("add link");
+ epoch
+ .del_from_links(Uuid::from_u128(2), &EntityType::Character, link)
+ .expect("delete link");
+ assert!(
+ epoch
+ .add_to_links(Uuid::from_u128(99), &EntityType::Character, link)
+ .is_err()
+ );
+
+ let mut replacement = entity(2, "Aria II", EntityType::Character);
+ replacement.description = "replacement".into();
+ let old = epoch.swap_entity(replacement).expect("swap entity");
+ assert_eq!(old.name, "Aria");
+ assert_eq!(epoch.characters[0].name, "Aria II");
+ assert!(
+ epoch
+ .swap_entity(entity(99, "Nobody", EntityType::Character))
+ .is_err()
+ );
+ let removed = epoch
+ .remove_entity(
+ &Some(EntityIdentifier::Name("aria".into())),
+ &EntityType::Character,
+ )
+ .expect("remove entity");
+ assert_eq!(removed.id, Uuid::from_u128(2));
+ assert!(epoch.characters.is_empty());
+ }
+
+ #[test]
+ fn positions_resolve_from_exact_grid_and_entity_references() {
+ let mut epoch = populated_epoch();
+ epoch.towns[0].modify_position("12,34".parse().expect("position"));
+ assert_eq!(
+ epoch
+ .resolve_position(&"1,2".parse().expect("exact position"))
+ .expect("exact")
+ .to_inner(),
+ (1, 2)
+ );
+ assert_eq!(
+ epoch
+ .resolve_position(&"~2,3".parse().expect("grid position"))
+ .expect("grid")
+ .to_inner(),
+ (400, 600)
+ );
+ assert_eq!(
+ epoch
+ .resolve_position(&PositionIdentifier::Id(EntityIdentifier::Name(
+ "haven".into(),
+ )))
+ .expect("entity")
+ .to_inner(),
+ (12, 34)
+ );
+ }
+}
diff --git a/tarpaulin.toml b/tarpaulin.toml
new file mode 100644
index 0000000..7f11411
--- /dev/null
+++ b/tarpaulin.toml
@@ -0,0 +1,12 @@
+[coverage]
+workspace = true
+all-features = true
+exclude-files = ["bin_efo/src/*"]
+
+[report]
+out = ["Html"]
+
+# CLI behavior is exercised through subprocess integration tests. Tarpaulin's
+# ptrace backend cannot attribute those child executions reliably (and its
+# follow-exec mode currently segfaults), so measure the directly instrumented
+# library and TUI code rather than reporting every CLI adapter as uncovered.