From 0b9fba78a0e1d0e3e7a44db9854d43f850f1f684 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Mon, 21 Sep 2026 00:41:49 +0200 Subject: [PATCH] feat: complete reversible format 2 history --- AGENTS-TASKS.md | 20 +- README.md | 12 +- bin_efo/src/commands/entity_generic.rs | 1 + bin_efo/src/commands/epoch.rs | 65 +++++ bin_efo/src/commands/epoch/cli_epoch.rs | 4 +- bin_efo/src/commands/history.rs | 102 ++++++- bin_efo/src/commands/migrate.rs | 24 +- bin_efo/src/commands/safety.rs | 4 + bin_efo/src/commands/state.rs | 86 +++++- bin_efo/src/main.rs | 11 +- bin_efo/tests/cli_workflows.rs | 59 ++++ docs/README.md | 2 +- docs/commands.md | 18 +- docs/repository.md | 20 +- docs/roadmap.md | 10 +- docs/staging-design.md | 4 +- lib_efo/src/epoch/epoch_config.rs | 13 + lib_efo/src/migration.rs | 66 ++++- lib_efo/src/transaction.rs | 26 ++ lib_efo/src/workspace.rs | 360 ++++++++++++++++++++++++ lib_efo/tests/migration_fixtures.rs | 20 +- lib_efo/tests/workspace.rs | 71 ++++- 22 files changed, 941 insertions(+), 57 deletions(-) diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index d0970e0..2cd8dcf 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -8,14 +8,17 @@ work belongs here before implementation. acceptance gates on 2026-09-20. **Milestone 2 — dependable daily CLI: complete.** Phase 3 passed its acceptance -gates on 2026-09-20. The Phase 4 format contract was approved on 2026-09-20; -implementation is now proceeding through isolated compatibility checkpoints. +gates on 2026-09-20. The Phase 4 format contract was approved on 2026-09-20. **Milestone 3 — safe format transition: complete.** On 2026-09-21, format detection, legacy fixtures, read-only migration planning, validated conversion, durable transient snapshots, and recoverable manifest backup passed default and portable release gates. +**Milestone 4 — Git-like reversible workflow: complete.** Phase 4 passed its +default and portable test, Clippy, and release gates on 2026-09-21. Format 2 is +explicitly migratable, transactional, staged, immutable, and recoverable. + ## Phase 0 — audit and guardrails - [x] Inventory workspace crates, commands, persistence files, CI, and tests. @@ -102,12 +105,13 @@ portable release gates. recovery. - [x] Extend transactions across ordered multi-file commits with rollback copies and a manifest-last commit point. -- [ ] Add automatic pre-commit migration rollback. +- [x] Add verified, explicit pre-commit migration rollback that preserves the + format-2 workspace for recovery. - [x] Implement worktree/index-aware `status`, `diff`, `stage`, and both restore directions without changing immutable epochs. -- [ ] Implement committed epochs, `log`, conflict-safe `revert`, and backed-up +- [x] Implement committed epochs, `log`, conflict-safe `revert`, and backed-up `prune-future`; retire the destructive `reset` spelling through deprecation. -- [ ] Complete Phase 4 only after every ordinary mistake is reversible without +- [x] Complete Phase 4 only after every ordinary mistake is reversible without manual JSON editing and both default and portable release gates pass. ## Phase 5 — organisation-agnostic extensibility (upcoming release) @@ -149,6 +153,12 @@ These require user approval and are not part of the current implementation: was removed in favor of read-only embedded defaults. - The binary now has eleven integration tests covering every exposed entity type, timeline workflows, invalid input, and corrupted repositories. +- Phase 4 adds worktree/index state, entity and world staging, explicit restore, + manifest-last commits, parent-linked log/revert/switch, backed-up pruning, + migration rollback, writer locks, journals, and deterministic recovery. +- The binary now has thirteen integration workflows; format-2 library coverage + includes clean/dirty layers, commits, conflict refusal, time advancement, + migration rollback, lock exclusion, and interrupted-journal refusal. - All 73 default-feature tests, 69 portable-output tests, strict Clippy, and both release builds passed on 2026-09-20. - The milestone-only `rust_autobadges` run was attempted, but this installed diff --git a/README.md b/README.md index 9047017..9bf7742 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,10 @@ current state, advance it, compare it with history, and deliberately discard a future timeline when needed. The current release manages organisations, characters, towns, events, -calamities, and blockers with statistics and relationships. Format-2 worktree, -staging, diff, and restore are available after explicit migration. Custom -fields, committed format-2 history/revert, and a TUI remain planned. There is no -GUI or web interface. +calamities, and blockers with statistics and relationships. After explicit +migration, format 2 provides worktree/index staging, immutable commits, restore, +conflict-safe revert, switching, and recoverable future pruning. Custom fields +and a TUI remain planned. There is no GUI or web interface. > Epoch Forge is not yet suitable as the only copy of important campaign data. > Keep the repository in Git or make a directory backup before destructive @@ -68,8 +68,8 @@ Run `efo --help`, `efo --help`, or see the | Area | Available now | Not available yet | |---|---|---| -| Repository | Initialise; inspect status; preview/apply backed-up format migration | Discovery from child directories; locking; automated migration rollback | -| Timeline | Advance, switch, log, tag, summarise, diff, check integrity, delete future epochs | Integrity repair; branching; atomic restore/revert | +| Repository | Initialise; inspect; migrate/roll back; lock and recover transactional writes | Discovery from child directories; integrity repair | +| Timeline | Advance legacy epochs; format-2 commit, switch, log, tag, summarise, diff, restore, revert, and backed-up future pruning | Branching and merging | | Entities | Add, edit, list, inspect, diff, and delete six built-in types | Custom types and custom fields; bulk operations | | Generation | Generate character, town, event, calamity, blocker, and exotic names | Deterministic seed controls and template packs | | Interfaces | CLI | TUI (possible stretch goal); GUI/web (out of scope) | diff --git a/bin_efo/src/commands/entity_generic.rs b/bin_efo/src/commands/entity_generic.rs index f46f6cb..55f468b 100644 --- a/bin_efo/src/commands/entity_generic.rs +++ b/bin_efo/src/commands/entity_generic.rs @@ -335,6 +335,7 @@ pub fn handle_entity_commands( version: state.manifest.version.clone(), tags: state.manifest.tags.clone().into_iter().collect(), list_existing_epochs: epochs, + preloaded_current: true, } } else { EpochConfig::new_from_path(None)? diff --git a/bin_efo/src/commands/epoch.rs b/bin_efo/src/commands/epoch.rs index 9e7b74c..1e5fbc2 100644 --- a/bin_efo/src/commands/epoch.rs +++ b/bin_efo/src/commands/epoch.rs @@ -83,6 +83,70 @@ pub mod cli_epoch; /// The function never panics under normal operation. All errors are /// reported via the returned `Result`. pub fn handle_cmd(cmd: &cli_epoch::EpochCmd) -> Result<(), AppError> { + let is_format_two = std::fs::read(".epoch") + .ok() + .and_then(|bytes| lib_efo::repository_format::detect_manifest(&bytes).ok()) + .is_some_and(|manifest| { + matches!( + manifest, + lib_efo::repository_format::DetectedManifest::Current(_) + ) + }); + if is_format_two { + match cmd { + cli_epoch::EpochCmd::Summary(args) => { + let mut workspace = lib_efo::workspace::Workspace::open(std::path::Path::new("."))?; + workspace.worktree.world.summary = args.summary.clone(); + workspace.save_worktree("edit summary")?; + println!("✓ Updated the worktree summary. Stage it with `efo stage --world`."); + return Ok(()); + } + cli_epoch::EpochCmd::Tag(args) => { + let mut workspace = lib_efo::workspace::Workspace::open(std::path::Path::new("."))?; + if workspace.worktree.world.tags.contains(&args.tag) + || workspace.manifest.tags.contains_key(&args.tag) + { + return Err(EpochError::TagAlreadyExists( + workspace.manifest.epoch_id, + args.tag.clone(), + ) + .into()); + } + workspace.worktree.world.tags.push(args.tag.clone()); + workspace.save_worktree("edit tags")?; + println!( + "✓ Added tag `{}` to the worktree. Stage it with `efo stage --world`.", + args.tag + ); + return Ok(()); + } + cli_epoch::EpochCmd::Reset(_) => { + return Err(EpochError::Unknown("`epoch reset` is deprecated for format 2; use `efo prune-future` for a preview and recoverable backup".into()).into()); + } + cli_epoch::EpochCmd::Next(_) => { + let mut workspace = lib_efo::workspace::Workspace::open(std::path::Path::new("."))?; + let id = workspace.advance_and_commit()?; + println!("✓ Advanced time and committed epoch {id}."); + return Ok(()); + } + cli_epoch::EpochCmd::Fsck(_) => { + let workspace = lib_efo::workspace::Workspace::open(std::path::Path::new("."))?; + let mut checked = 0; + for entry in std::fs::read_dir("epoch")? { + let entry = entry?; + if entry.file_type()?.is_dir() + && let Ok(id) = entry.file_name().to_string_lossy().parse() + { + workspace.load_epoch(id)?; + checked += 1; + } + } + println!("✓ Format-2 repository is consistent ({checked} epoch(s) checked)."); + return Ok(()); + } + _ => {} + } + } let mut main_epoch = EpochConfig::new_from_path(None)?; debug!("The main epoch before any action is {:#?}", main_epoch); match cmd { @@ -305,6 +369,7 @@ fn handle_next(_args: &cli_epoch::Next, main_epoch: &mut EpochConfig) -> Result< /// * `Err(AppError)` if any deletion fails. fn handle_reset(args: &cli_epoch::Reset, main_epoch: &mut EpochConfig) -> Result<(), AppError> { let _ = args; + eprintln!("warning: `efo epoch reset` is deprecated; migrate and use `efo prune-future`"); let current_id = main_epoch.epoch_id; // for id in main_epoch for id in main_epoch diff --git a/bin_efo/src/commands/epoch/cli_epoch.rs b/bin_efo/src/commands/epoch/cli_epoch.rs index a9ce60e..266ca89 100644 --- a/bin_efo/src/commands/epoch/cli_epoch.rs +++ b/bin_efo/src/commands/epoch/cli_epoch.rs @@ -33,7 +33,7 @@ pub enum EpochCmd { /// Compute the next epoch from the current one Next(Next), - /// Delete all future epochs after the current epoch (irreversible) + /// Deprecated legacy deletion; format 2 uses recoverable `prune-future` Reset(Reset), /// Show the differences between two epochs @@ -80,7 +80,7 @@ pub struct Next; /// Deletes all future epochs after the current epoch. #[derive(Args, Debug)] #[command( - after_long_help = "WARNING: This permanently removes later epoch directories.\n\nRECOVERY WORKFLOW:\n efo epoch switch \n efo status\n # Back up the repository, then:\n efo epoch reset" + after_long_help = "DEPRECATED: format-1 only. This permanently removes later epoch directories.\nUse `efo prune-future` after migrating to format 2 for preview, backup, and restore." )] pub struct Reset; diff --git a/bin_efo/src/commands/history.rs b/bin_efo/src/commands/history.rs index 50d132e..f26ca1e 100644 --- a/bin_efo/src/commands/history.rs +++ b/bin_efo/src/commands/history.rs @@ -1,9 +1,15 @@ //! Immutable format-2 commit and log commands. -use std::{fs, path::Path}; +use std::{ + fs, + path::{Path, PathBuf}, +}; use clap::Args; -use lib_efo::{epoch::EpochInfo, workspace::Workspace}; +use lib_efo::{ + epoch::{EpochId, EpochIdentifier, EpochInfo}, + workspace::Workspace, +}; use crate::error::AppError; @@ -23,6 +29,31 @@ pub struct LogCmd { limit: usize, } +/// Select an existing immutable epoch. +#[derive(Args, Debug)] +pub struct SwitchCmd { + /// Epoch ID or tag to check out. + target: EpochIdentifier, +} + +/// Create a new commit that inverses one historical epoch. +#[derive(Args, Debug)] +pub struct RevertCmd { + /// Epoch ID or tag whose introduced changes should be inverted. + target: EpochIdentifier, +} + +/// Preview, apply, or restore backed-up future-history pruning. +#[derive(Args, Debug)] +pub struct PruneFutureCmd { + /// Restore a backup directory previously printed by this command. + #[arg(long, value_name = "BACKUP")] + restore: Option, + /// Confirm moving history or restoring a backup. + #[arg(long)] + yes: bool, +} + /// Commit staged state through a manifest-last transaction. pub fn commit(command: &CommitCmd) -> Result<(), AppError> { let mut workspace = Workspace::open(Path::new("."))?; @@ -61,3 +92,70 @@ pub fn log(command: &LogCmd) -> Result<(), AppError> { } Ok(()) } + +/// Switch all clean state layers to an immutable epoch. +pub fn switch(command: &SwitchCmd) -> Result<(), AppError> { + let mut workspace = Workspace::open(Path::new("."))?; + let previous = workspace.manifest.epoch_id; + let target = resolve(&workspace, &command.target)?; + workspace.switch(target)?; + println!("✓ Switched HEAD from epoch {previous} to epoch {target}."); + Ok(()) +} + +/// Revert a historical change by creating a new immutable epoch. +pub fn revert(command: &RevertCmd) -> Result<(), AppError> { + let mut workspace = Workspace::open(Path::new("."))?; + let target = resolve(&workspace, &command.target)?; + let new_id = workspace.revert(target)?; + println!("✓ Reverted epoch {target} in new epoch {new_id}."); + Ok(()) +} + +/// Resolve a numeric ID or exact tag against the format-2 manifest. +fn resolve(workspace: &Workspace, identifier: &EpochIdentifier) -> Result { + match identifier { + EpochIdentifier::Id(id) => Ok(*id), + EpochIdentifier::Tag(tag) => workspace + .manifest + .tags + .get(tag) + .copied() + .ok_or_else(|| lib_efo::error::EpochError::EpochNotFound(tag.clone()).into()), + } +} + +/// Move future epochs into a recoverable backup, or restore that backup. +pub fn prune_future(command: &PruneFutureCmd) -> Result<(), AppError> { + let workspace = Workspace::open(Path::new("."))?; + if let Some(backup) = &command.restore { + if !command.yes { + println!("Restore preview: {}", backup.display()); + println!("Run again with `--yes` to restore this history."); + return Ok(()); + } + let count = workspace.restore_pruned(backup)?; + println!("✓ Restored {count} epoch(s) from {}.", backup.display()); + return Ok(()); + } + let future = workspace.future_epochs()?; + println!("Future-history prune preview: {} epoch(s)", future.len()); + for id in &future { + println!(" epoch {id}"); + } + if !command.yes { + println!("Nothing changed. Run again with `--yes` to move these epochs into a backup."); + return Ok(()); + } + let backup = workspace.prune_future()?; + println!( + "✓ Moved {} epoch(s) into {}.", + future.len(), + backup.display() + ); + println!( + " Undo: efo prune-future --restore '{}' --yes", + backup.display() + ); + Ok(()) +} diff --git a/bin_efo/src/commands/migrate.rs b/bin_efo/src/commands/migrate.rs index eb2d004..cc5340e 100644 --- a/bin_efo/src/commands/migrate.rs +++ b/bin_efo/src/commands/migrate.rs @@ -3,19 +3,22 @@ use std::path::Path; use clap::Args; -use lib_efo::migration::{execute_migration, plan_migration}; +use lib_efo::migration::{execute_migration, plan_migration, rollback_migration}; use crate::error::AppError; /// Arguments accepted by `efo migrate`. #[derive(Args, Debug)] #[command( - after_long_help = "EXAMPLES:\n efo migrate --to 2 # validate and preview only\n efo migrate --to 2 --yes # create backup and migrate" + after_long_help = "EXAMPLES:\n efo migrate --to 2 # validate and preview only\n efo migrate --to 2 --yes # create backup and migrate\n efo migrate --rollback # preview pre-commit rollback\n efo migrate --rollback --yes" )] pub struct MigrateCmd { /// Repository format to migrate to (currently only 2). - #[arg(long, value_parser = clap::value_parser!(u32).range(2..=2))] - to: u32, + #[arg(long, value_parser = clap::value_parser!(u32).range(2..=2), required_unless_present = "rollback")] + to: Option, + /// Restore the verified version-1 manifest before the first format-2 commit. + #[arg(long, conflicts_with = "to")] + rollback: bool, /// Apply the displayed plan; without this flag migration is a dry-run. #[arg(long)] yes: bool, @@ -23,8 +26,19 @@ pub struct MigrateCmd { /// Validate, preview, and optionally execute a repository migration. pub fn migrate(command: &MigrateCmd) -> Result<(), AppError> { + if command.rollback { + if !command.yes { + println!("Migration rollback preview"); + println!("No changes made. Run `efo migrate --rollback --yes` to restore format 1."); + return Ok(()); + } + let preserved = rollback_migration(Path::new("."))?; + println!("✓ Restored the verified format-1 manifest."); + println!(" Format-2 workspace preserved at {}.", preserved.display()); + return Ok(()); + } let plan = plan_migration(Path::new("."))?; - println!("Migration plan · format 1 → {}", command.to); + println!("Migration plan · format 1 → {}", command.to.unwrap_or(2)); println!("├─ Repository {}", plan.root().display()); println!("├─ HEAD epoch {}", plan.current_epoch()); println!("├─ History {} snapshot(s)", plan.epoch_count()); diff --git a/bin_efo/src/commands/safety.rs b/bin_efo/src/commands/safety.rs index 5ddec28..91489af 100644 --- a/bin_efo/src/commands/safety.rs +++ b/bin_efo/src/commands/safety.rs @@ -48,7 +48,11 @@ pub fn handle_lock(command: &LockCmd) -> Result<(), AppError> { LockCmd::Inspect => { let owner = inspect_lock(Path::new("."))?; println!("Writer lock"); + if let Some(repository_id) = owner.repository_id { + println!("├─ Repository {repository_id}"); + } println!("├─ PID {}", owner.pid); + println!("├─ Started {}", owner.process_start); println!("├─ Host {}", owner.hostname); println!("├─ Command {}", owner.command); println!("└─ Created {} (Unix time)", owner.created_at); diff --git a/bin_efo/src/commands/state.rs b/bin_efo/src/commands/state.rs index 4bf4151..cf2a072 100644 --- a/bin_efo/src/commands/state.rs +++ b/bin_efo/src/commands/state.rs @@ -46,13 +46,16 @@ impl From for EntityType { )] pub struct StageCmd { /// Stage the complete worktree. - #[arg(long, conflicts_with = "kind")] + #[arg(long, conflicts_with_all = ["kind", "world"])] all: bool, + /// Stage only world-level metadata such as summary and tags. + #[arg(long, conflicts_with_all = ["all", "kind"])] + world: bool, /// Stage only matching entities of this kind. - #[arg(long, value_enum, required_unless_present = "all")] + #[arg(long, value_enum, required_unless_present_any = ["all", "world"])] kind: Option, /// Names or stable `@UUID` identifiers selected with `--kind`. - #[arg(required_unless_present = "all")] + #[arg(required_unless_present_any = ["all", "world"])] identifiers: Vec, } @@ -69,13 +72,16 @@ pub struct RestoreCmd { #[arg(long, group = "layer", required = true)] worktree: bool, /// Restore the complete selected layer. - #[arg(long, conflicts_with = "kind")] + #[arg(long, conflicts_with_all = ["kind", "world"])] all: bool, + /// Restore only world-level metadata. + #[arg(long, conflicts_with_all = ["all", "kind"])] + world: bool, /// Restore only matching entities of this kind. - #[arg(long, value_enum, required_unless_present = "all")] + #[arg(long, value_enum, required_unless_present_any = ["all", "world"])] kind: Option, /// Names or stable `@UUID` identifiers selected with `--kind`. - #[arg(required_unless_present = "all")] + #[arg(required_unless_present_any = ["all", "world"])] identifiers: Vec, } @@ -115,6 +121,9 @@ pub fn stage(command: &StageCmd) -> Result<(), AppError> { if command.all { workspace.stage_all()?; println!("✓ Staged the complete worktree."); + } else if command.world { + workspace.stage_world()?; + println!("✓ Staged world metadata."); } else if let Some(kind) = command.kind { workspace.stage_entities(kind.into(), &command.identifiers)?; println!( @@ -128,13 +137,21 @@ pub fn stage(command: &StageCmd) -> Result<(), AppError> { /// Restore selected format-2 state from the explicitly named source layer. pub fn restore(command: &RestoreCmd) -> Result<(), AppError> { let mut workspace = Workspace::open(Path::new("."))?; - match (command.staged, command.worktree, command.all, command.kind) { - (true, false, true, _) => workspace.restore_index()?, - (false, true, true, _) => workspace.restore_worktree()?, - (true, false, false, Some(kind)) => { + match ( + command.staged, + command.worktree, + command.all, + command.world, + command.kind, + ) { + (true, false, true, false, _) => workspace.restore_index()?, + (false, true, true, false, _) => workspace.restore_worktree()?, + (true, false, false, true, _) => workspace.restore_index_world()?, + (false, true, false, true, _) => workspace.restore_worktree_world()?, + (true, false, false, false, Some(kind)) => { workspace.restore_index_entities(kind.into(), &command.identifiers)? } - (false, true, false, Some(kind)) => { + (false, true, false, false, Some(kind)) => { workspace.restore_worktree_entities(kind.into(), &command.identifiers)? } _ => unreachable!("clap enforces layer and selection groups"), @@ -194,10 +211,33 @@ fn print_diff(from: &EpochInfo, to: &EpochInfo) { serde_json::to_value(prior).ok() != serde_json::to_value(*item).ok() }) }) { - println!(" ~ {name}: {} @{}", entity.name, entity.id); + let prior = old.iter().find(|prior| prior.id == entity.id); + let fields = prior.map_or_else(Vec::new, |value| changed_fields(value, entity)); + println!( + " ~ {name}: {} @{}{}", + entity.name, + entity.id, + if fields.is_empty() { + String::new() + } else { + format!(" [{}]", fields.join(", ")) + } + ); count += 1; } } + if from.summary != to.summary { + println!(" ~ world summary: {:?} → {:?}", from.summary, to.summary); + count += 1; + } + if from.tags.as_slice() != to.tags.as_slice() { + println!( + " ~ world tags: {:?} → {:?}", + from.tags.as_slice(), + to.tags.as_slice() + ); + count += 1; + } if count == 0 { println!(" No changes."); } else { @@ -205,6 +245,28 @@ fn print_diff(from: &EpochInfo, to: &EpochInfo) { } } +/// List top-level persisted fields that changed on one entity. +fn changed_fields( + before: &lib_efo::entity::Entity, + after: &lib_efo::entity::Entity, +) -> Vec { + let (Ok(serde_json::Value::Object(before)), Ok(serde_json::Value::Object(after))) = + (serde_json::to_value(before), serde_json::to_value(after)) + else { + return Vec::new(); + }; + let mut keys = before + .keys() + .chain(after.keys()) + .cloned() + .collect::>(); + keys.sort(); + keys.dedup(); + keys.into_iter() + .filter(|key| before.get(key) != after.get(key)) + .collect() +} + /// Human-readable boolean state without relying on colour or icons. fn label(changed: bool, changed_label: &'static str, clean_label: &'static str) -> &'static str { if changed { changed_label } else { clean_label } diff --git a/bin_efo/src/main.rs b/bin_efo/src/main.rs index b2d500c..48c417e 100644 --- a/bin_efo/src/main.rs +++ b/bin_efo/src/main.rs @@ -32,7 +32,7 @@ use crate::{ entity_generic::EntitySubCommands, epoch::cli_epoch::EpochCmd, generate::GenCmd, - history::{CommitCmd, LogCmd}, + history::{CommitCmd, LogCmd, PruneFutureCmd, RevertCmd, SwitchCmd}, init::InitCmd, migrate::MigrateCmd, safety::{LockCmd, RecoverCmd}, @@ -91,6 +91,12 @@ enum TopLevelCmd { Commit(CommitCmd), /// Show immutable format-2 history newest first. Log(LogCmd), + /// Switch clean format-2 state to an existing epoch. + Switch(SwitchCmd), + /// Invert a historical change in a new commit. + Revert(RevertCmd), + /// Preview or safely back up future history; restore with `--restore`. + PruneFuture(PruneFutureCmd), /// Gives a very simple status. Status(StatusCmd), /// Advance or query the current epoch. @@ -178,6 +184,9 @@ fn exec_dispatch(cli: Cli) -> Result<(), AppError> { TopLevelCmd::Restore(cmd) => commands::state::restore(&cmd), TopLevelCmd::Commit(cmd) => commands::history::commit(&cmd), TopLevelCmd::Log(cmd) => commands::history::log(&cmd), + TopLevelCmd::Switch(cmd) => commands::history::switch(&cmd), + TopLevelCmd::Revert(cmd) => commands::history::revert(&cmd), + TopLevelCmd::PruneFuture(cmd) => commands::history::prune_future(&cmd), TopLevelCmd::Epoch(cmd) => commands::epoch::handle_cmd(&cmd), TopLevelCmd::Show(cmd) => commands::show::handle_show_cmd(&cmd), TopLevelCmd::Gen(cmd) => commands::generate::gen_handler(&cmd), diff --git a/bin_efo/tests/cli_workflows.rs b/bin_efo/tests/cli_workflows.rs index 99a36de..9434623 100644 --- a/bin_efo/tests/cli_workflows.rs +++ b/bin_efo/tests/cli_workflows.rs @@ -192,6 +192,10 @@ fn migration_is_dry_run_by_default_and_backs_up_before_commit() { assert_success(&status); assert!(stdout(&status).contains("Staged clean")); + assert_success(&efo(&repo, &["epoch", "summary", "First format-2 commit"])); + assert_success(&efo(&repo, &["epoch", "tag", "format2"])); + assert_success(&efo(&repo, &["stage", "--world"])); + assert_success(&efo(&repo, &["chr", "add", "Bryn"])); assert!(stdout(&efo(&repo, &["status"])).contains("Worktree changes")); let diff = efo(&repo, &["diff"]); @@ -216,11 +220,66 @@ fn migration_is_dry_run_by_default_and_backs_up_before_commit() { assert!(stdout(&show).contains("Bryn")); assert!(!stdout(&show).contains("Cora")); + assert_success(&efo(&repo, &["revert", "1"])); + let show = efo(&repo, &["show", "character"]); + assert_success(&show); + assert!(!stdout(&show).contains("Bryn")); + assert_success(&efo(&repo, &["switch", "format2"])); + let preview = efo(&repo, &["prune-future"]); + assert_success(&preview); + assert!(stdout(&preview).contains("1 epoch(s)")); + assert_success(&efo(&repo, &["prune-future", "--yes"])); + assert!(!repo.path().join("epoch/2").exists()); + let prune_root = repo.path().join(".efo/pruned"); + let backup = fs::read_dir(&prune_root) + .expect("prune backups") + .next() + .expect("one prune backup") + .expect("backup entry") + .path(); + assert_success(&efo( + &repo, + &[ + "prune-future", + "--restore", + backup.to_str().expect("backup path UTF-8"), + "--yes", + ], + )); + assert!(repo.path().join("epoch/2/epochinfo.json").exists()); + let recovery = efo(&repo, &["recover"]); assert_success(&recovery); assert!(stdout(&recovery).contains("no recovery is needed")); } +#[test] +fn migration_rollback_is_explicit_and_preserves_format_two_workspace() { + let repo = TestRepo::new(); + assert_success(&efo(&repo, &["init"])); + let original = fs::read(repo.path().join(".epoch")).expect("legacy manifest"); + assert_success(&efo(&repo, &["migrate", "--to", "2", "--yes"])); + let preview = efo(&repo, &["migrate", "--rollback"]); + assert_success(&preview); + assert_ne!( + fs::read(repo.path().join(".epoch")).expect("still v2"), + original + ); + assert_success(&efo(&repo, &["migrate", "--rollback", "--yes"])); + assert_eq!( + fs::read(repo.path().join(".epoch")).expect("restored v1"), + original + ); + assert!(!repo.path().join(".efo").exists()); + assert!(fs::read_dir(repo.path()).expect("repository").any(|entry| { + entry + .expect("entry") + .file_name() + .to_string_lossy() + .starts_with(".efo-format2-") + })); +} + #[test] fn init_force_preserves_unrelated_files_and_never_overwrites_a_repository() { let repo = TestRepo::new(); diff --git a/docs/README.md b/docs/README.md index 3a9262d..720ea36 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,7 +7,7 @@ behavior clearly. - [Repository format](repository.md): files, epochs, compatibility, backup, and recovery. - [Reversing changes](recovery.md): checkpoints and recovery for every mutation. - [Architecture](architecture.md): crate responsibilities, data flow, and quality gates. -- [Staging design](staging-design.md): proposed Phase 4 state, command, transaction, +- [Staging design](staging-design.md): approved Phase 4 state, command, transaction, and migration contract. - [Roadmap](roadmap.md): current work and stretch proposals. diff --git a/docs/commands.md b/docs/commands.md index 02a4c9e..6f63c96 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -10,8 +10,8 @@ parent directories. `efo --help` is the authoritative syntax. but never overwrites `.epoch` or epoch 0. - `efo migrate --to 2` validates and previews migration without writing. Add `--yes` to create a byte-for-byte manifest backup and initialise the - version-2 index/worktree. This is an opt-in Phase 4 transition: ordinary - commands deliberately refuse format 2 until the staging checkpoint lands. + version-2 index/worktree. Migration is explicit and format-1 repositories + remain supported. - `efo recover` deterministically rolls back a prepared replacement or verifies a committed one. It is safe to repeat. - `efo lock inspect` reports writer ownership. `efo lock break --yes` removes @@ -51,13 +51,25 @@ options, and prestige controls. `edit --delta` adds supplied stats rather than replacing them. See nested help (for example `efo chr add --help`) for exact syntax and values. Mutations write the current epoch immediately; staging does not exist in format 1. After format-2 migration, entity mutations edit only the -worktree. Use `efo diff`, `efo stage --all` or `efo stage --kind KIND ID...`, +worktree. Use `efo diff`, `efo stage --all`, `efo stage --world`, or +`efo stage --kind KIND ID...`, and `efo diff --staged` to prepare history. `efo restore --staged ...` copies HEAD into the index; `efo restore --worktree ...` copies the index into the worktree. Both restore modes require either `--all` or an entity kind and IDs. `efo commit -m MESSAGE` refuses unstaged or empty commits, creates an immutable epoch using a manifest-last transaction, and realigns all three layers. `efo log` shows the resulting parent-linked history newest first. +`efo switch ID` requires clean state and changes all layers without reusing +epoch IDs. `efo revert ID` applies that epoch's inverse and commits it; overlap +with later changes aborts without mutation. `efo prune-future` previews future +epochs, while `--yes` moves them into a backup. Restore using the exact command +printed after pruning. Legacy `efo epoch reset` is deprecated and remains only +for format-1 compatibility. + +`efo epoch summary` and `efo epoch tag` edit format-2 worktree metadata; +`stage --world` selects it. `efo epoch next` requires a clean worktree, includes +already staged changes, advances entity time, and commits one new monotonic ID. +`efo epoch fsck` validates format-2 layers and every immutable epoch. `efo show all` lists every collection in the current epoch. `show character`, `show town`, `show event`, `show calamity`, and `show blocker` select one diff --git a/docs/repository.md b/docs/repository.md index 113029f..deff6ae 100644 --- a/docs/repository.md +++ b/docs/repository.md @@ -59,17 +59,17 @@ history, creates complete `.efo/index.json` and `.efo/worktree.json` snapshots, and commits the versioned `.epoch` manifest last. The original manifest and its FNV-1a integrity checksum are stored under `.efo/migrations/`. -Format 2 is currently an implementation preview. Other commands refuse it so -they cannot accidentally write version-1 semantics over staged state. Until the -first format-2 commit is supported, roll back by preserving the generated -workspace and restoring the manifest: +Format 2 uses `.efo/worktree.json` for edits, `.efo/index.json` for staged state, +and immutable `epoch/` snapshots for commits. Version-aware commands never +write legacy semantics over these layers. Before the first format-2 commit, +preview or apply verified rollback with: ```bash -mv .efo .efo-format2-backup -cp .efo-format2-backup/migrations/v1-*/.epoch .epoch -efo epoch fsck +efo migrate --rollback +efo migrate --rollback --yes ``` -The wildcard must identify exactly one migration directory. Do not overwrite a -newer `.epoch`; copy the whole repository before manual recovery. Current work -is tracked in [the roadmap](roadmap.md). +Rollback restores the byte-identical manifest and preserves the complete +format-2 workspace under a timestamped name. Once a format-2 commit exists, +rollback refuses; use history commands instead. Current work is tracked in +[the roadmap](roadmap.md). diff --git a/docs/roadmap.md b/docs/roadmap.md index eef5a3c..7d8948f 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -22,12 +22,12 @@ consistent, organisations are managed directly, help includes examples, Nerd Font output has a portable build option, relationships are type-validated, and every mutation has documented and tested recovery guidance. -The [Phase 4 format contract](staging-design.md) is approved. Versioned format +The [Phase 4 format contract](staging-design.md) is implemented. Versioned format types, legacy fixtures, validation, dry-run migration, durable transient-state -creation, and byte-for-byte manifest backup are implemented. Format 2 remains -opt-in and ordinary commands refuse it until transaction locking and staging -land. Organisation-agnostic custom fields and types follow reversible history, -with unknown-field retention designed before that format change. +creation, byte-for-byte manifest backup, locking, recovery, staging, immutable +commits, revert, and recoverable pruning are implemented. Format 2 remains +opt-in. Organisation-agnostic custom fields and types follow, with +unknown-field retention designed before that format change. ## Proposed stretch goals diff --git a/docs/staging-design.md b/docs/staging-design.md index 30bccc0..51265aa 100644 --- a/docs/staging-design.md +++ b/docs/staging-design.md @@ -1,7 +1,7 @@ # Staging, history, and recovery design -Status: **approved on 2026-09-20**. This document is the Phase 4 implementation -contract; it does not describe behavior available in the current release. +Status: **implemented on 2026-09-21** after approval on 2026-09-20. This is the +Phase 4 persistence and recovery contract. The goal is a familiar Git-like workflow without pretending that Epoch Forge is Git. A repository has one editable timeline, every meaningful change can be diff --git a/lib_efo/src/epoch/epoch_config.rs b/lib_efo/src/epoch/epoch_config.rs index a397b07..a50bc88 100644 --- a/lib_efo/src/epoch/epoch_config.rs +++ b/lib_efo/src/epoch/epoch_config.rs @@ -56,6 +56,9 @@ pub struct EpochConfig { /// A hashmap containing the name of all existing epochs, only loaded in memory if used #[serde(skip)] pub list_existing_epochs: HashMap>, + /// Whether the current cache entry is an authoritative format-2 worktree. + #[serde(skip)] + pub preloaded_current: bool, } impl Default for EpochConfig { @@ -65,6 +68,7 @@ impl Default for EpochConfig { epoch_id: EpochId::new(0), tags: HashMap::new(), list_existing_epochs: HashMap::new(), + preloaded_current: false, version: env!("EFO_SHORT_VERSION").to_string(), } } @@ -147,6 +151,15 @@ impl EpochConfig { /// * `Err(EpochError::Serde { .. })` if the JSON file could not be parsed. /// * `Err(EpochError::Io { .. })` if the file could not be read. pub fn try_load(&mut self, epoch_id: &EpochId) -> Result<(), EpochError> { + if self.preloaded_current + && *epoch_id == self.epoch_id + && self + .list_existing_epochs + .get(epoch_id) + .is_some_and(Option::is_some) + { + return Ok(()); + } // Preload the epoch let version = self.version(); let value = self diff --git a/lib_efo/src/migration.rs b/lib_efo/src/migration.rs index 8c41a68..c463d48 100644 --- a/lib_efo/src/migration.rs +++ b/lib_efo/src/migration.rs @@ -94,6 +94,9 @@ pub enum MigrationError { /// Existing migration state may not be overwritten. #[error("migration workspace `{0}` already exists; nothing was changed")] WorkspaceExists(PathBuf), + /// Rollback is only safe before the first format-2 commit. + #[error("migration rollback is unavailable: {0}")] + RollbackUnavailable(String), /// JSON data could not be decoded or encoded. #[error("migration data at `{path}` is invalid: {source}")] Json { @@ -240,6 +243,62 @@ pub fn execute_migration(plan: &MigrationPlan) -> Result Result { + let workspace = crate::workspace::Workspace::open(root) + .map_err(|error| MigrationError::RollbackUnavailable(error.to_string()))?; + if workspace.head.parent_epoch.is_some() || !workspace.head.commit_message.is_empty() { + return Err(MigrationError::RollbackUnavailable( + "format-2 history already contains a commit; export or revert instead".into(), + )); + } + let migrations = workspace.root().join(".efo/migrations"); + let backups = fs::read_dir(&migrations) + .map_err(|source| MigrationError::Io { + path: migrations.clone(), + source, + })? + .collect::, _>>() + .map_err(|source| MigrationError::Io { + path: migrations.clone(), + source, + })?; + if backups.len() != 1 { + return Err(MigrationError::RollbackUnavailable(format!( + "expected exactly one migration backup, found {}", + backups.len() + ))); + } + let backup_manifest = backups[0].path().join(".epoch"); + let bytes = read(&backup_manifest)?; + let checksum_path = backups[0].path().join("checksums.fnv1a64"); + let checksum_text = String::from_utf8(read(&checksum_path)?) + .map_err(|_| MigrationError::RollbackUnavailable("backup checksum is not UTF-8".into()))?; + let expected = checksum_text + .split_whitespace() + .next() + .ok_or_else(|| MigrationError::RollbackUnavailable("backup checksum is empty".into()))?; + if expected != format!("{:016x}", fnv1a64(&bytes)) { + return Err(MigrationError::RollbackUnavailable( + "backup checksum does not match the saved manifest".into(), + )); + } + let stamp = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_err(|_| MigrationError::Invalid("system clock is before Unix epoch".into()))? + .as_secs(); + let preserved = workspace.root().join(format!(".efo-format2-{stamp}")); + fs::rename(workspace.root().join(".efo"), &preserved).map_err(|source| MigrationError::Io { + path: preserved.clone(), + source, + })?; + if let Err(error) = atomic_bytes(&workspace.root().join(".epoch"), &bytes) { + let _ = fs::rename(&preserved, workspace.root().join(".efo")); + return Err(error); + } + Ok(preserved) +} + /// Write and flush the complete version-2 workspace before its final rename. fn prepare_workspace( plan: &MigrationPlan, @@ -311,6 +370,11 @@ fn atomic_json(path: &Path, value: &T) -> Result<(), MigrationErro path: path.to_path_buf(), source, })?; + atomic_bytes(path, &bytes) +} + +/// Atomically replace one file with already encoded bytes. +fn atomic_bytes(path: &Path, bytes: &[u8]) -> Result<(), MigrationError> { let parent = path.parent().ok_or_else(|| { MigrationError::Invalid(format!("path `{}` has no parent", path.display())) })?; @@ -324,7 +388,7 @@ fn atomic_json(path: &Path, value: &T) -> Result<(), MigrationErro source, })?; temporary - .write_all(&bytes) + .write_all(bytes) .and_then(|_| temporary.as_file().sync_all()) .map_err(|source| MigrationError::Io { path: path.to_path_buf(), diff --git a/lib_efo/src/transaction.rs b/lib_efo/src/transaction.rs index baf3ef8..cf623c4 100644 --- a/lib_efo/src/transaction.rs +++ b/lib_efo/src/transaction.rs @@ -8,12 +8,17 @@ use std::{ }; use serde::{Deserialize, Serialize}; +use uuid::Uuid; /// Metadata describing the process that owns a repository writer lock. #[derive(Debug, Clone, Serialize, Deserialize)] pub struct LockInfo { + /// Stable repository identity when a format-2 manifest is readable. + pub repository_id: Option, /// Operating-system process identifier. pub pid: u32, + /// OS process-start token used to distinguish PID reuse. + pub process_start: String, /// Host identifier when available. pub hostname: String, /// User-facing operation holding the lock. @@ -101,7 +106,9 @@ impl RepositoryLock { pub fn acquire(root: &Path, command: impl Into) -> Result { let path = root.join(".efo/lock"); let info = LockInfo { + repository_id: repository_id(root), pid: std::process::id(), + process_start: process_start_token(), hostname: std::env::var("HOSTNAME").unwrap_or_else(|_| "unknown-host".to_owned()), command: command.into(), created_at: now()?, @@ -130,6 +137,25 @@ impl RepositoryLock { } } +/// Read repository identity without making lock acquisition depend on it. +fn repository_id(root: &Path) -> Option { + let bytes = fs::read(root.join(".epoch")).ok()?; + match crate::repository_format::detect_manifest(&bytes).ok()? { + crate::repository_format::DetectedManifest::Current(manifest) => { + Some(manifest.repository_id) + } + crate::repository_format::DetectedManifest::Legacy(_) => None, + } +} + +/// Capture a PID-reuse-resistant token where the host exposes one. +fn process_start_token() -> String { + fs::read_to_string(format!("/proc/{}/stat", std::process::id())) + .ok() + .and_then(|stat| stat.split_whitespace().nth(21).map(str::to_owned)) + .unwrap_or_else(|| format!("created-{}", now().unwrap_or_default())) +} + impl Drop for RepositoryLock { fn drop(&mut self) { let _ = fs::remove_file(&self.path); diff --git a/lib_efo/src/workspace.rs b/lib_efo/src/workspace.rs index 92fe5fa..a723e55 100644 --- a/lib_efo/src/workspace.rs +++ b/lib_efo/src/workspace.rs @@ -1,8 +1,10 @@ //! Format-2 HEAD, index, and worktree access. use std::{ + collections::BTreeMap, fs, path::{Path, PathBuf}, + time::{SystemTime, UNIX_EPOCH}, }; use serde::Serialize; @@ -71,15 +73,37 @@ pub enum WorkspaceError { /// The index is identical to HEAD. #[error("index has no changes to commit")] EmptyCommit, + /// Later snapshots must be pruned before creating a new linear commit. + #[error("future epochs exist; run `efo prune-future` before committing")] + FutureExists, + /// An interrupted transaction must be recovered before reading layers. + #[error("an unfinished transaction exists; run `efo recover` before continuing")] + RecoveryRequired, + /// A history operation requires all three layers to agree. + #[error("repository has staged or unstaged changes; commit or restore them first")] + Dirty, + /// An inverse change overlaps later edits. + #[error("revert conflicts with later changes in {0}; nothing was changed")] + Conflict(String), + /// The requested committed epoch does not exist. + #[error("committed epoch {0} does not exist")] + EpochMissing(crate::epoch::EpochId), /// Transaction safety rejected the write. #[error(transparent)] Transaction(#[from] TransactionError), } impl Workspace { + /// Canonical repository root. + pub fn root(&self) -> &Path { + &self.root + } /// Open and cross-check a format-2 repository. pub fn open(root: &Path) -> Result { let root = root.canonicalize().map_err(|source| io(root, source))?; + if root.join(".efo/transaction.json").exists() { + return Err(WorkspaceError::RecoveryRequired); + } let manifest_path = root.join(".epoch"); let manifest = match detect_manifest(&read(&manifest_path)?)? { DetectedManifest::Legacy(_) => return Err(WorkspaceError::Legacy), @@ -92,6 +116,12 @@ impl Workspace { let index: RepositorySnapshot = decode(&index_path)?; let worktree: RepositorySnapshot = decode(&worktree_path)?; for (name, snapshot) in [("index", &index), ("worktree", &worktree)] { + if snapshot.format_version != crate::repository_format::CURRENT_FORMAT_VERSION { + return Err(WorkspaceError::Inconsistent(format!( + "{name} has unsupported format {}", + snapshot.format_version + ))); + } if snapshot.repository_id != manifest.repository_id { return Err(WorkspaceError::Inconsistent(format!( "{name} belongs to another repository" @@ -109,6 +139,9 @@ impl Workspace { "HEAD snapshot ID does not match manifest".into(), )); } + validate_world("HEAD", &head)?; + validate_world("index", &index.world)?; + validate_world("worktree", &worktree.world)?; Ok(Self { root, manifest, @@ -134,6 +167,12 @@ impl Workspace { self.save_index("stage --all") } + /// Copy world-level metadata from worktree into index. + pub fn stage_world(&mut self) -> Result<(), WorkspaceError> { + copy_world_metadata(&self.worktree.world, &mut self.index.world); + self.save_index("stage --world") + } + /// Copy selected entities from worktree into index, including deletions. pub fn stage_entities( &mut self, @@ -156,6 +195,18 @@ impl Workspace { self.save_worktree("restore --worktree --all") } + /// Restore staged world metadata from HEAD. + pub fn restore_index_world(&mut self) -> Result<(), WorkspaceError> { + copy_world_metadata(&self.head, &mut self.index.world); + self.save_index("restore --staged --world") + } + + /// Restore worktree world metadata from index. + pub fn restore_worktree_world(&mut self) -> Result<(), WorkspaceError> { + copy_world_metadata(&self.index.world, &mut self.worktree.world); + self.save_worktree("restore --worktree --world") + } + /// Restore selected index entities from HEAD. pub fn restore_index_entities( &mut self, @@ -191,6 +242,10 @@ impl Workspace { if self.has_unstaged_changes() { return Err(WorkspaceError::Unstaged); } + if !self.future_epochs()?.is_empty() { + return Err(WorkspaceError::FutureExists); + } + validate_world("index", &self.index.world)?; if !self.has_staged_changes() { return Err(WorkspaceError::EmptyCommit); } @@ -201,6 +256,13 @@ impl Workspace { world.commit_message = message; let mut manifest = self.manifest.clone(); manifest.epoch_id = new_id; + for tag in world + .tags + .iter() + .filter(|tag| !self.head.tags.contains(tag)) + { + manifest.tags.insert(tag.clone(), new_id); + } manifest.next_epoch_id = crate::epoch::EpochId::new(new_id.id.checked_add(1).ok_or_else(|| { WorkspaceError::Inconsistent("epoch ID allocator is exhausted".into()) @@ -232,6 +294,228 @@ impl Workspace { self.worktree = snapshot; Ok(new_id) } + + /// Load one immutable epoch by ID. + pub fn load_epoch(&self, id: crate::epoch::EpochId) -> Result { + let path = self.root.join(format!("epoch/{id}/epochinfo.json")); + if !path.is_file() { + return Err(WorkspaceError::EpochMissing(id)); + } + decode(&path) + } + + /// Switch clean HEAD/index/worktree to an existing immutable epoch. + pub fn switch(&mut self, target: crate::epoch::EpochId) -> Result<(), WorkspaceError> { + if self.has_staged_changes() || self.has_unstaged_changes() { + return Err(WorkspaceError::Dirty); + } + let world = self.load_epoch(target)?; + let mut manifest = self.manifest.clone(); + manifest.epoch_id = target; + let snapshot = RepositorySnapshot::new(manifest.repository_id, target, world.clone()); + let replacements = [ + ( + self.root.join(".efo/index.json"), + encode(&snapshot, "index")?, + ), + ( + self.root.join(".efo/worktree.json"), + encode(&snapshot, "worktree")?, + ), + (self.root.join(".epoch"), encode(&manifest, "manifest")?), + ]; + replace_files(&self.root, &replacements, "switch")?; + self.manifest = manifest; + self.head = world; + self.index = snapshot.clone(); + self.worktree = snapshot; + Ok(()) + } + + /// Invert one historical epoch onto clean HEAD and commit the result. + pub fn revert( + &mut self, + target: crate::epoch::EpochId, + ) -> Result { + if self.has_staged_changes() || self.has_unstaged_changes() { + return Err(WorkspaceError::Dirty); + } + let changed = self.load_epoch(target)?; + let parent_id = changed + .parent_epoch + .or_else(|| (target.id > 0).then(|| crate::epoch::EpochId::new(target.id - 1))) + .ok_or_else(|| WorkspaceError::Conflict("root epoch has no change to invert".into()))?; + let before = self.load_epoch(parent_id)?; + let mut result = self.head.clone(); + invert_world(&before, &changed, &mut result)?; + result.epoch_id = self.manifest.epoch_id; + result.parent_epoch = self.head.parent_epoch; + result.commit_message = self.head.commit_message.clone(); + self.index.world = result.clone(); + self.worktree.world = result; + self.commit(format!("Revert epoch {target}")) + } + + /// Advance entity time in the index and commit it with any staged changes. + pub fn advance_and_commit(&mut self) -> Result { + if self.has_unstaged_changes() { + return Err(WorkspaceError::Unstaged); + } + self.index + .world + .iter_all_entities_mut() + .for_each(|entity| entity.increment_time()); + self.index.world.summary.clear(); + self.index.world.tags.clear(); + // Time advancement is meaningful even for an empty world; this marker + // makes the new history event non-empty before `commit` assigns its + // final message and epoch identity. + self.index.world.commit_message = "Advance time".into(); + self.worktree.world = self.index.world.clone(); + self.commit("Advance time".into()) + } + + /// List snapshots numerically newer than current HEAD. + pub fn future_epochs(&self) -> Result, WorkspaceError> { + let mut ids = Vec::new(); + for entry in fs::read_dir(self.root.join("epoch")) + .map_err(|source| io(&self.root.join("epoch"), source))? + { + let entry = entry.map_err(|source| io(&self.root.join("epoch"), source))?; + if entry + .file_type() + .map_err(|source| io(&entry.path(), source))? + .is_dir() + && let Ok(id) = entry + .file_name() + .to_string_lossy() + .parse::() + && id > self.manifest.epoch_id + { + ids.push(id); + } + } + ids.sort_unstable(); + Ok(ids) + } + + /// Move future snapshots into a recoverable backup directory. + pub fn prune_future(&self) -> Result { + if self.has_staged_changes() || self.has_unstaged_changes() { + return Err(WorkspaceError::Dirty); + } + let ids = self.future_epochs()?; + let stamp = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_err(|_| WorkspaceError::Inconsistent("system clock is before Unix epoch".into()))? + .as_secs(); + let backup = self.root.join(format!(".efo/pruned/{stamp}/epoch")); + fs::create_dir_all(&backup).map_err(|source| io(&backup, source))?; + let _lock = crate::transaction::RepositoryLock::acquire(&self.root, "prune-future")?; + for id in ids { + let source = self.root.join(format!("epoch/{id}")); + let destination = backup.join(id.to_string()); + fs::rename(&source, &destination).map_err(|source_error| io(&source, source_error))?; + } + Ok(backup.parent().unwrap_or(&backup).to_path_buf()) + } + + /// Restore all epoch directories from a prune backup. + pub fn restore_pruned(&self, backup: &Path) -> Result { + let epoch_backup = backup.join("epoch"); + let _lock = + crate::transaction::RepositoryLock::acquire(&self.root, "restore pruned history")?; + let mut restored = 0; + for entry in fs::read_dir(&epoch_backup).map_err(|source| io(&epoch_backup, source))? { + let entry = entry.map_err(|source| io(&epoch_backup, source))?; + let destination = self.root.join("epoch").join(entry.file_name()); + if destination.exists() { + return Err(WorkspaceError::Inconsistent(format!( + "cannot restore `{}` because it already exists", + destination.display() + ))); + } + fs::rename(entry.path(), &destination).map_err(|source| io(&destination, source))?; + restored += 1; + } + Ok(restored) + } +} + +/// Apply entity and summary inverses, refusing overlapping later edits. +fn invert_world( + before: &EpochInfo, + changed: &EpochInfo, + current: &mut EpochInfo, +) -> Result<(), WorkspaceError> { + macro_rules! invert_collection { + ($field:ident) => { + invert_entities( + &before.$field, + &changed.$field, + &mut current.$field, + stringify!($field), + )?; + }; + } + invert_collection!(characters); + invert_collection!(towns); + invert_collection!(events); + invert_collection!(calamities); + invert_collection!(organizations); + invert_collection!(blockers); + if before.summary != changed.summary { + if current.summary == changed.summary { + current.summary = before.summary.clone(); + } else if current.summary != before.summary { + return Err(WorkspaceError::Conflict("summary".into())); + } + } + Ok(()) +} + +/// Invert changed entities by stable UUID with whole-entity conflict checks. +fn invert_entities( + before: &[crate::entity::Entity], + changed: &[crate::entity::Entity], + current: &mut Vec, + label: &str, +) -> Result<(), WorkspaceError> { + let mut ids = before + .iter() + .chain(changed) + .map(|entity| entity.id) + .collect::>(); + ids.sort_unstable(); + ids.dedup(); + for id in ids { + let old = before.iter().find(|entity| entity.id == id); + let new = changed.iter().find(|entity| entity.id == id); + if same_entity(old, new) { + continue; + } + let now = current.iter().find(|entity| entity.id == id); + if same_entity(now, old) { + continue; + } + if !same_entity(now, new) { + return Err(WorkspaceError::Conflict(format!("{label} entity @{id}"))); + } + current.retain(|entity| entity.id != id); + if let Some(entity) = old { + current.push(entity.clone()); + } + } + Ok(()) +} + +/// Compare optional entities through their persisted representation. +fn same_entity( + left: Option<&crate::entity::Entity>, + right: Option<&crate::entity::Entity>, +) -> bool { + left.and_then(|value| serde_json::to_value(value).ok()) + == right.and_then(|value| serde_json::to_value(value).ok()) } /// Copy selected collection entries with delete semantics. @@ -263,6 +547,82 @@ fn copy_entities( Ok(()) } +/// Copy mutable metadata not owned by an entity collection. +fn copy_world_metadata(source: &EpochInfo, destination: &mut EpochInfo) { + destination.rng_seed = source.rng_seed; + destination.tags = source.tags.clone(); + destination.summary = source.summary.clone(); +} + +/// Validate stable identity, collection type, and relationship targets. +fn validate_world(label: &str, world: &EpochInfo) -> Result<(), WorkspaceError> { + let mut identities = BTreeMap::new(); + for (entities, expected) in [ + (&world.characters, EntityType::Character), + (&world.towns, EntityType::Town), + (&world.events, EntityType::Event), + (&world.calamities, EntityType::Calamity), + (&world.organizations, EntityType::Organization), + (&world.blockers, EntityType::Blocker), + ] { + for entity in entities { + if entity.id.is_nil() || identities.insert(entity.id, expected).is_some() { + return Err(WorkspaceError::Inconsistent(format!( + "{label} contains a missing or duplicate entity UUID" + ))); + } + if entity.entity_type != expected { + return Err(WorkspaceError::Inconsistent(format!( + "{label} stores `{}` in the wrong collection", + entity.name + ))); + } + } + } + for entity in world + .characters + .iter() + .chain(&world.towns) + .chain(&world.events) + .chain(&world.calamities) + .chain(&world.organizations) + .chain(&world.blockers) + { + let value = serde_json::to_value(entity).map_err(|source| WorkspaceError::Json { + path: PathBuf::from(label), + source, + })?; + if let Some(links) = value + .pointer("/metadata/links") + .and_then(serde_json::Value::as_array) + { + for link in links { + let id: uuid::Uuid = + serde_json::from_value(link["other_id"].clone()).map_err(|source| { + WorkspaceError::Json { + path: PathBuf::from(label), + source, + } + })?; + let kind: EntityType = + serde_json::from_value(link["other_type"].clone()).map_err(|source| { + WorkspaceError::Json { + path: PathBuf::from(label), + source, + } + })?; + if identities.get(&id) != Some(&kind) { + return Err(WorkspaceError::Inconsistent(format!( + "{label} entity `{}` links to missing or mistyped @{id}", + entity.name + ))); + } + } + } + } + Ok(()) +} + /// Find collection entries matching the public CLI identifier rules. fn matches<'a>( entities: &'a [crate::entity::Entity], diff --git a/lib_efo/tests/migration_fixtures.rs b/lib_efo/tests/migration_fixtures.rs index 5a6ac04..f37ab38 100644 --- a/lib_efo/tests/migration_fixtures.rs +++ b/lib_efo/tests/migration_fixtures.rs @@ -7,7 +7,7 @@ use std::{ use lib_efo::{ entity::Entity, epoch::{EpochId, EpochInfo}, - migration::{MigrationError, execute_migration, plan_migration}, + migration::{MigrationError, execute_migration, plan_migration, rollback_migration}, repository_format::{DetectedManifest, LegacyManifest, detect_manifest}, stats::{EntityType, Role, TypedLink}, }; @@ -223,6 +223,24 @@ fn migration_backs_up_manifest_and_commits_version_two_last() { } } +#[test] +fn migration_can_roll_back_before_the_first_format_two_commit() { + let directory = tempfile::tempdir().expect("temporary fixture repository"); + materialize_repository(directory.path(), 0, &[0]); + let original = fs::read(directory.path().join(".epoch")).expect("legacy manifest"); + let plan = plan_migration(directory.path()).expect("plan"); + execute_migration(&plan).expect("migrate"); + + let preserved = rollback_migration(directory.path()).expect("rollback migration"); + + assert_eq!( + fs::read(directory.path().join(".epoch")).expect("restored"), + original + ); + assert!(preserved.join("index.json").is_file()); + assert!(!directory.path().join(".efo").exists()); +} + fn materialize_repository(root: &Path, current: u64, epochs: &[u64]) { let manifest = LegacyManifest { epoch_id: EpochId::new(current), diff --git a/lib_efo/tests/workspace.rs b/lib_efo/tests/workspace.rs index 5b632e5..7222f7b 100644 --- a/lib_efo/tests/workspace.rs +++ b/lib_efo/tests/workspace.rs @@ -6,7 +6,7 @@ use lib_efo::{ migration::{execute_migration, plan_migration}, repository_format::LegacyManifest, stats::EntityType, - workspace::Workspace, + workspace::{Workspace, WorkspaceError}, }; fn migrated_repository() -> tempfile::TempDir { @@ -42,11 +42,31 @@ fn all_layers_begin_clean_and_complete() { assert_eq!(workspace.head.epoch_id, EpochId::new(0)); } +#[test] +fn unfinished_journal_blocks_layer_reads_until_recovery() { + let directory = migrated_repository(); + fs::write(directory.path().join(".efo/transaction.json"), "{}").expect("journal"); + let error = Workspace::open(directory.path()).expect_err("journal must block readers"); + assert!(matches!(error, WorkspaceError::RecoveryRequired)); +} + +#[test] +fn time_advance_commits_even_an_empty_world() { + let directory = migrated_repository(); + let mut workspace = Workspace::open(directory.path()).expect("workspace"); + assert_eq!( + workspace.advance_and_commit().expect("advance"), + EpochId::new(1) + ); + assert_eq!(workspace.head.commit_message, "Advance time"); +} + #[test] fn entity_staging_and_both_restore_directions_are_isolated() { let directory = migrated_repository(); let mut workspace = Workspace::open(directory.path()).expect("workspace"); let mut aria = Entity::default(); + aria.id = uuid::Uuid::from_u128(1); aria.name = "Aria".into(); aria.entity_type = EntityType::Character; workspace.worktree.world.characters.push(aria); @@ -77,6 +97,7 @@ fn commit_creates_immutable_history_and_advances_all_layers() { let directory = migrated_repository(); let mut workspace = Workspace::open(directory.path()).expect("workspace"); let mut aria = Entity::default(); + aria.id = uuid::Uuid::from_u128(1); aria.name = "Aria".into(); aria.entity_type = EntityType::Character; workspace.worktree.world.characters.push(aria); @@ -101,4 +122,52 @@ fn commit_creates_immutable_history_and_advances_all_layers() { ) .expect("original epoch"); assert!(original.characters.is_empty()); + + let reverted = workspace.revert(EpochId::new(1)).expect("revert epoch 1"); + assert_eq!(reverted, EpochId::new(2)); + assert!(workspace.head.characters.is_empty()); + assert_eq!(workspace.head.parent_epoch, Some(EpochId::new(1))); + + workspace + .switch(EpochId::new(1)) + .expect("switch to epoch 1"); + assert_eq!(workspace.head.characters.len(), 1); + assert_eq!(workspace.manifest.next_epoch_id, EpochId::new(3)); + assert_eq!( + workspace.future_epochs().expect("future"), + vec![EpochId::new(2)] + ); + let backup = workspace.prune_future().expect("prune future"); + assert!(!directory.path().join("epoch/2").exists()); + assert_eq!( + workspace.restore_pruned(&backup).expect("restore future"), + 1 + ); + assert!(directory.path().join("epoch/2/epochinfo.json").exists()); +} + +#[test] +fn revert_aborts_when_later_edits_overlap_the_target_change() { + let directory = migrated_repository(); + let mut workspace = Workspace::open(directory.path()).expect("workspace"); + let mut aria = Entity::default(); + aria.id = uuid::Uuid::from_u128(1); + aria.name = "Aria".into(); + aria.entity_type = EntityType::Character; + workspace.worktree.world.characters.push(aria); + workspace.stage_all().expect("stage addition"); + workspace.commit("Add Aria".into()).expect("first commit"); + workspace.worktree.world.characters[0].name = "Aria Changed".into(); + workspace.stage_all().expect("stage edit"); + workspace + .commit("Rename Aria".into()) + .expect("second commit"); + + let error = workspace + .revert(EpochId::new(1)) + .expect_err("overlap must conflict"); + + assert!(matches!(error, WorkspaceError::Conflict(_))); + assert_eq!(workspace.manifest.epoch_id, EpochId::new(2)); + assert!(!directory.path().join("epoch/3").exists()); }