feat: add atomic format 2 commits and log

This commit is contained in:
Dandaedre 2026-09-21 00:29:13 +02:00
parent d938e27288
commit c6442bdeac
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
10 changed files with 294 additions and 47 deletions

View File

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

View File

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

View File

@ -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(())
}

View File

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

View File

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

View File

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

View File

@ -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<EpochId>,
/// 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(),

View File

@ -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<TransactionEntry>,
}
/// 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<PathBuf>,
/// 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<u8>)],
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<RecoveryOutcome, TransactionError> {
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(&current) != 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<PathBuf, TransactionError> {
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<T: Serialize>(path: &Path, value: &T) -> Result<(), TransactionError> {
let bytes = serde_json::to_vec_pretty(value).map_err(|source| TransactionError::Json {

View File

@ -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<crate::epoch::EpochId, WorkspaceError> {
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<T: Serialize>(
Ok(())
}
/// Encode transaction content with a meaningful synthetic path.
fn encode<T: Serialize>(value: &T, label: &str) -> Result<Vec<u8>, 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 {

View File

@ -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());
}