From c6442bdeac355a0e36944a773789d09fd8fdc1cc Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Mon, 21 Sep 2026 00:29:13 +0200 Subject: [PATCH] feat: add atomic format 2 commits and log --- AGENTS-TASKS.md | 5 +- bin_efo/src/commands.rs | 1 + bin_efo/src/commands/history.rs | 63 ++++++++++++++ bin_efo/src/main.rs | 7 ++ bin_efo/tests/cli_workflows.rs | 10 ++- docs/commands.md | 3 + lib_efo/src/epoch/epoch_info.rs | 12 +++ lib_efo/src/transaction.rs | 146 ++++++++++++++++++++++---------- lib_efo/src/workspace.rs | 63 +++++++++++++- lib_efo/tests/workspace.rs | 31 +++++++ 10 files changed, 294 insertions(+), 47 deletions(-) create mode 100644 bin_efo/src/commands/history.rs diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index 95c5ed7..d0970e0 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -100,8 +100,9 @@ portable release gates. - [x] Add durable single-file transaction journaling, exclusive writer locks, lock inspection/break primitives, and deterministic interrupted-write recovery. -- [ ] Extend transactions across multi-file commits and add automatic - pre-commit migration rollback. +- [x] Extend transactions across ordered multi-file commits with rollback + copies and a manifest-last commit point. +- [ ] Add automatic pre-commit migration rollback. - [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 diff --git a/bin_efo/src/commands.rs b/bin_efo/src/commands.rs index 6cbb948..223dd47 100644 --- a/bin_efo/src/commands.rs +++ b/bin_efo/src/commands.rs @@ -11,6 +11,7 @@ pub mod entity_generic; pub mod epoch; pub mod generate; +pub mod history; pub mod init; pub mod migrate; pub mod safety; diff --git a/bin_efo/src/commands/history.rs b/bin_efo/src/commands/history.rs new file mode 100644 index 0000000..50d132e --- /dev/null +++ b/bin_efo/src/commands/history.rs @@ -0,0 +1,63 @@ +//! Immutable format-2 commit and log commands. + +use std::{fs, path::Path}; + +use clap::Args; +use lib_efo::{epoch::EpochInfo, workspace::Workspace}; + +use crate::error::AppError; + +/// Create an immutable epoch from the index. +#[derive(Args, Debug)] +pub struct CommitCmd { + /// Required explanation stored with the new epoch. + #[arg(short, long, required = true)] + message: String, +} + +/// Options for displaying immutable history. +#[derive(Args, Debug)] +pub struct LogCmd { + /// Maximum number of newest entries to display. + #[arg(short, long, default_value_t = 20)] + limit: usize, +} + +/// Commit staged state through a manifest-last transaction. +pub fn commit(command: &CommitCmd) -> Result<(), AppError> { + let mut workspace = Workspace::open(Path::new("."))?; + let id = workspace.commit(command.message.clone())?; + println!("✓ Committed epoch {id}: {}", command.message); + println!(" HEAD, index, and worktree are now aligned."); + Ok(()) +} + +/// Display format-2 history newest first. +pub fn log(command: &LogCmd) -> Result<(), AppError> { + let workspace = Workspace::open(Path::new("."))?; + let mut id = Some(workspace.manifest.epoch_id); + let mut shown = 0; + while let Some(current) = id.filter(|_| shown < command.limit) { + let path = Path::new("epoch") + .join(current.to_string()) + .join("epochinfo.json"); + let epoch: EpochInfo = serde_json::from_slice(&fs::read(&path)?) + .map_err(lib_efo::error::StorageError::from)?; + let message = if epoch.commit_message.is_empty() { + "(legacy snapshot)" + } else { + &epoch.commit_message + }; + println!( + "{} epoch {} {}", + if shown == 0 { "*" } else { " " }, + current, + message + ); + id = epoch + .parent_epoch + .or_else(|| (current.id > 0).then(|| lib_efo::epoch::EpochId::new(current.id - 1))); + shown += 1; + } + Ok(()) +} diff --git a/bin_efo/src/main.rs b/bin_efo/src/main.rs index aafa440..b2d500c 100644 --- a/bin_efo/src/main.rs +++ b/bin_efo/src/main.rs @@ -32,6 +32,7 @@ use crate::{ entity_generic::EntitySubCommands, epoch::cli_epoch::EpochCmd, generate::GenCmd, + history::{CommitCmd, LogCmd}, init::InitCmd, migrate::MigrateCmd, safety::{LockCmd, RecoverCmd}, @@ -86,6 +87,10 @@ enum TopLevelCmd { Stage(StageCmd), /// Restore index or worktree state from its prior layer. Restore(RestoreCmd), + /// Create an immutable epoch from staged state. + Commit(CommitCmd), + /// Show immutable format-2 history newest first. + Log(LogCmd), /// Gives a very simple status. Status(StatusCmd), /// Advance or query the current epoch. @@ -171,6 +176,8 @@ fn exec_dispatch(cli: Cli) -> Result<(), AppError> { TopLevelCmd::Diff(cmd) => commands::state::diff(&cmd), TopLevelCmd::Stage(cmd) => commands::state::stage(&cmd), TopLevelCmd::Restore(cmd) => commands::state::restore(&cmd), + TopLevelCmd::Commit(cmd) => commands::history::commit(&cmd), + TopLevelCmd::Log(cmd) => commands::history::log(&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 a9f312a..99a36de 100644 --- a/bin_efo/tests/cli_workflows.rs +++ b/bin_efo/tests/cli_workflows.rs @@ -202,11 +202,19 @@ fn migration_is_dry_run_by_default_and_backs_up_before_commit() { let status = stdout(&efo(&repo, &["status"])); assert!(status.contains("Staged changes")); assert!(status.contains("Worktree clean")); + assert_success(&efo(&repo, &["commit", "-m", "Add Bryn"])); + let log = efo(&repo, &["log"]); + assert_success(&log); + assert!(stdout(&log).contains("epoch 1 Add Bryn")); + assert!(repo.path().join("epoch/1/epochinfo.json").is_file()); + + assert_success(&efo(&repo, &["chr", "add", "Cora"])); assert_success(&efo(&repo, &["restore", "--staged", "--all"])); assert_success(&efo(&repo, &["restore", "--worktree", "--all"])); let show = efo(&repo, &["show", "character"]); assert_success(&show); - assert!(!stdout(&show).contains("Bryn")); + assert!(stdout(&show).contains("Bryn")); + assert!(!stdout(&show).contains("Cora")); let recovery = efo(&repo, &["recover"]); assert_success(&recovery); diff --git a/docs/commands.md b/docs/commands.md index f9b331b..02a4c9e 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -55,6 +55,9 @@ worktree. Use `efo diff`, `efo stage --all` 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 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/lib_efo/src/epoch/epoch_info.rs b/lib_efo/src/epoch/epoch_info.rs index 183a244..f8bb9a0 100644 --- a/lib_efo/src/epoch/epoch_info.rs +++ b/lib_efo/src/epoch/epoch_info.rs @@ -35,6 +35,16 @@ pub struct EpochInfo { #[table(title = "ID")] pub epoch_id: EpochId, + /// Immutable predecessor in format-2 history. + #[serde(default)] + #[table(skip)] + pub parent_epoch: Option, + + /// User-supplied history message for format-2 commits. + #[serde(default)] + #[table(skip)] + pub commit_message: String, + /// RNG seed that was used to generate randomised data for /// this epoch. Keeping it in the file guarantees repeatable /// behaviour when replaying the same epoch. @@ -80,6 +90,8 @@ impl Default for EpochInfo { fn default() -> Self { Self { epoch_id: EpochId::new(0), + parent_epoch: None, + commit_message: String::new(), rng_seed: 0, tags: TagList::new(), summary: String::new(), diff --git a/lib_efo/src/transaction.rs b/lib_efo/src/transaction.rs index dfb8cab..baf3ef8 100644 --- a/lib_efo/src/transaction.rs +++ b/lib_efo/src/transaction.rs @@ -32,10 +32,19 @@ pub struct RepositoryLock { /// Durable record for an interrupted file replacement. #[derive(Debug, Clone, Serialize, Deserialize)] struct TransactionJournal { - /// Destination path relative to `.efo`'s parent. + /// Ordered replacements; the manifest must be supplied last. + entries: Vec, +} + +/// One recoverable file replacement. +#[derive(Debug, Clone, Serialize, Deserialize)] +struct TransactionEntry { + /// Destination path relative to repository root. destination: PathBuf, - /// Prepared replacement path relative to `.efo`'s parent. + /// Prepared replacement path relative to repository root. temporary: PathBuf, + /// Optional prior content used for rollback. + backup: Option, /// Checksum of the complete replacement. new_checksum: String, } @@ -152,36 +161,59 @@ pub fn replace_file( destination: &Path, bytes: &[u8], command: &str, +) -> Result<(), TransactionError> { + replace_files( + root, + &[(destination.to_path_buf(), bytes.to_vec())], + command, + ) +} + +/// Replace several files under one lock and journal, in the supplied order. +pub fn replace_files( + root: &Path, + replacements: &[(PathBuf, Vec)], + command: &str, ) -> Result<(), TransactionError> { let _lock = RepositoryLock::acquire(root, command)?; recover_unlocked(root)?; let workspace = root.join(".efo"); let journal_path = workspace.join("transaction.json"); - let temporary = workspace.join(format!("transaction-{}.tmp", std::process::id())); - let mut file = - File::create(&temporary).map_err(|source| io_error(temporary.clone(), source))?; - file.write_all(bytes) - .and_then(|_| file.sync_all()) - .map_err(|source| io_error(temporary.clone(), source))?; - let destination_relative = destination.strip_prefix(root).map_err(|_| { - TransactionError::Ambiguous(format!( - "destination `{}` is outside repository `{}`", - destination.display(), - root.display() - )) - })?; - let journal = TransactionJournal { - destination: destination_relative.to_path_buf(), - temporary: temporary - .strip_prefix(root) - .map_err(|_| TransactionError::Ambiguous("temporary path escaped repository".into()))? - .to_path_buf(), - new_checksum: checksum(bytes), - }; + let mut entries = Vec::new(); + for (index, (destination, bytes)) in replacements.iter().enumerate() { + let temporary = workspace.join(format!("transaction-{index}.tmp")); + let backup_path = workspace.join(format!("transaction-{index}.bak")); + write_bytes_synced(&temporary, bytes)?; + let backup = if destination.exists() { + write_bytes_synced( + &backup_path, + &fs::read(destination).map_err(|source| io_error(destination.clone(), source))?, + )?; + Some( + backup_path + .strip_prefix(root) + .map_err(|_| TransactionError::Ambiguous("backup escaped repository".into()))? + .to_path_buf(), + ) + } else { + None + }; + entries.push(TransactionEntry { + destination: relative(root, destination)?, + temporary: relative(root, &temporary)?, + backup, + new_checksum: checksum(bytes), + }); + } + let journal = TransactionJournal { entries }; write_json_synced(&journal_path, &journal)?; - fs::rename(&temporary, destination) - .map_err(|source| io_error(destination.to_path_buf(), source))?; - sync_directory(destination.parent().unwrap_or(root))?; + for entry in &journal.entries { + let destination = root.join(&entry.destination); + fs::rename(root.join(&entry.temporary), &destination) + .map_err(|source| io_error(destination.clone(), source))?; + sync_directory(destination.parent().unwrap_or(root))?; + } + cleanup_transaction(root, &journal)?; fs::remove_file(&journal_path).map_err(|source| io_error(journal_path.clone(), source))?; sync_directory(&workspace) } @@ -204,31 +236,59 @@ fn recover_unlocked(root: &Path) -> Result { path: journal_path.clone(), source, })?; - let destination = root.join(&journal.destination); - let temporary = root.join(&journal.temporary); - let outcome = if temporary.exists() { - fs::remove_file(&temporary).map_err(|source| io_error(temporary, source))?; - RecoveryOutcome::RolledBack - } else if destination.exists() { - let current = - fs::read(&destination).map_err(|source| io_error(destination.clone(), source))?; - if checksum(¤t) != journal.new_checksum { - return Err(TransactionError::Ambiguous(format!( - "`{}` matches neither prepared nor committed content", - destination.display() - ))); - } + let committed = journal.entries.iter().all(|entry| { + fs::read(root.join(&entry.destination)) + .ok() + .is_some_and(|bytes| checksum(&bytes) == entry.new_checksum) + }); + let outcome = if committed { RecoveryOutcome::Completed } else { - return Err(TransactionError::Ambiguous( - "both prepared and destination files are missing".to_owned(), - )); + for entry in journal.entries.iter().rev() { + let destination = root.join(&entry.destination); + if let Some(backup) = &entry.backup { + fs::rename(root.join(backup), &destination) + .map_err(|source| io_error(destination, source))?; + } else if destination.exists() { + fs::remove_file(&destination).map_err(|source| io_error(destination, source))?; + } + } + RecoveryOutcome::RolledBack }; + cleanup_transaction(root, &journal)?; fs::remove_file(&journal_path).map_err(|source| io_error(journal_path.clone(), source))?; sync_directory(journal_path.parent().unwrap_or(root))?; Ok(outcome) } +/// Remove prepared and backup files after commit or recovery. +fn cleanup_transaction(root: &Path, journal: &TransactionJournal) -> Result<(), TransactionError> { + for entry in &journal.entries { + for relative in std::iter::once(&entry.temporary).chain(entry.backup.iter()) { + let path = root.join(relative); + if path.exists() { + fs::remove_file(&path).map_err(|source| io_error(path, source))?; + } + } + } + Ok(()) +} + +/// Convert an absolute repository path into a journal-safe relative path. +fn relative(root: &Path, path: &Path) -> Result { + path.strip_prefix(root).map(Path::to_path_buf).map_err(|_| { + TransactionError::Ambiguous(format!("path `{}` escaped repository", path.display())) + }) +} + +/// Write and flush raw transaction data. +fn write_bytes_synced(path: &Path, bytes: &[u8]) -> Result<(), TransactionError> { + let mut file = File::create(path).map_err(|source| io_error(path.to_path_buf(), source))?; + file.write_all(bytes) + .and_then(|_| file.sync_all()) + .map_err(|source| io_error(path.to_path_buf(), source)) +} + /// Write durable JSON metadata before a transaction commit point. fn write_json_synced(path: &Path, value: &T) -> Result<(), TransactionError> { let bytes = serde_json::to_vec_pretty(value).map_err(|source| TransactionError::Json { diff --git a/lib_efo/src/workspace.rs b/lib_efo/src/workspace.rs index 0cfaebd..92fe5fa 100644 --- a/lib_efo/src/workspace.rs +++ b/lib_efo/src/workspace.rs @@ -14,7 +14,7 @@ use crate::{ DetectedManifest, FormatError, RepositoryManifest, RepositorySnapshot, detect_manifest, }, stats::EntityType, - transaction::{TransactionError, replace_file}, + transaction::{TransactionError, replace_file, replace_files}, }; /// A validated format-2 repository and its three state layers. @@ -65,6 +65,12 @@ pub enum WorkspaceError { /// A requested entity selector did not resolve safely. #[error("entity selector `{0}` did not match exactly one entity")] Selector(String), + /// A commit would discard unstaged edits. + #[error("worktree has unstaged changes; stage them or restore the worktree before committing")] + Unstaged, + /// The index is identical to HEAD. + #[error("index has no changes to commit")] + EmptyCommit, /// Transaction safety rejected the write. #[error(transparent)] Transaction(#[from] TransactionError), @@ -179,6 +185,53 @@ impl Workspace { pub fn save_index(&self, command: &str) -> Result<(), WorkspaceError> { save(&self.root, ".efo/index.json", &self.index, command) } + + /// Create an immutable epoch and advance all state layers atomically. + pub fn commit(&mut self, message: String) -> Result { + if self.has_unstaged_changes() { + return Err(WorkspaceError::Unstaged); + } + if !self.has_staged_changes() { + return Err(WorkspaceError::EmptyCommit); + } + let new_id = self.manifest.next_epoch_id; + let mut world = self.index.world.clone(); + world.parent_epoch = Some(self.manifest.epoch_id); + world.epoch_id = new_id; + world.commit_message = message; + let mut manifest = self.manifest.clone(); + manifest.epoch_id = 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()) + })?); + let snapshot = RepositorySnapshot::new(manifest.repository_id, new_id, world.clone()); + let epoch_path = self.root.join(format!("epoch/{new_id}/epochinfo.json")); + fs::create_dir_all( + epoch_path + .parent() + .ok_or_else(|| WorkspaceError::Inconsistent("epoch path has no parent".into()))?, + ) + .map_err(|source| io(&epoch_path, source))?; + let replacements = [ + (epoch_path, encode(&world, "epoch snapshot")?), + ( + 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, "commit")?; + self.manifest = manifest; + self.head = world; + self.index = snapshot.clone(); + self.worktree = snapshot; + Ok(new_id) + } } /// Copy selected collection entries with delete semantics. @@ -260,6 +313,14 @@ fn save( Ok(()) } +/// Encode transaction content with a meaningful synthetic path. +fn encode(value: &T, label: &str) -> Result, WorkspaceError> { + serde_json::to_vec_pretty(value).map_err(|source| WorkspaceError::Json { + path: PathBuf::from(label), + source, + }) +} + /// Attach the attempted path to an I/O error. fn io(path: &Path, source: std::io::Error) -> WorkspaceError { WorkspaceError::Io { diff --git a/lib_efo/tests/workspace.rs b/lib_efo/tests/workspace.rs index aadc1fd..5b632e5 100644 --- a/lib_efo/tests/workspace.rs +++ b/lib_efo/tests/workspace.rs @@ -71,3 +71,34 @@ fn entity_staging_and_both_restore_directions_are_isolated() { assert!(!workspace.has_unstaged_changes()); assert!(workspace.worktree.world.characters.is_empty()); } + +#[test] +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.name = "Aria".into(); + aria.entity_type = EntityType::Character; + workspace.worktree.world.characters.push(aria); + workspace.save_worktree("test edit").expect("worktree"); + let mut workspace = Workspace::open(directory.path()).expect("changed workspace"); + workspace.stage_all().expect("stage"); + + let id = workspace.commit("Add Aria".into()).expect("commit"); + + assert_eq!(id, EpochId::new(1)); + assert_eq!(workspace.manifest.next_epoch_id, EpochId::new(2)); + assert!(!workspace.has_staged_changes()); + assert!(!workspace.has_unstaged_changes()); + let committed: EpochInfo = serde_json::from_slice( + &fs::read(directory.path().join("epoch/1/epochinfo.json")).expect("epoch 1"), + ) + .expect("committed epoch"); + assert_eq!(committed.parent_epoch, Some(EpochId::new(0))); + assert_eq!(committed.commit_message, "Add Aria"); + let original: EpochInfo = serde_json::from_slice( + &fs::read(directory.path().join("epoch/0/epochinfo.json")).expect("epoch 0"), + ) + .expect("original epoch"); + assert!(original.characters.is_empty()); +}