feat: complete reversible format 2 history

This commit is contained in:
Dandaedre 2026-09-21 00:41:49 +02:00
parent c6442bdeac
commit 0b9fba78a0
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
22 changed files with 941 additions and 57 deletions

View File

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

View File

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

View File

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

View File

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

View File

@ -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 <older-epoch>\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;

View File

@ -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<PathBuf>,
/// 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<EpochId, AppError> {
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(())
}

View File

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

View File

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

View File

@ -46,13 +46,16 @@ impl From<EntityKind> 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<EntityKind>,
/// Names or stable `@UUID` identifiers selected with `--kind`.
#[arg(required_unless_present = "all")]
#[arg(required_unless_present_any = ["all", "world"])]
identifiers: Vec<EntityIdentifier>,
}
@ -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<EntityKind>,
/// Names or stable `@UUID` identifiers selected with `--kind`.
#[arg(required_unless_present = "all")]
#[arg(required_unless_present_any = ["all", "world"])]
identifiers: Vec<EntityIdentifier>,
}
@ -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<String> {
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::<Vec<_>>();
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 }

View File

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

View File

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

View File

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

View File

@ -10,8 +10,8 @@ parent directories. `efo <command> --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

View File

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

View File

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

View File

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

View File

@ -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<EpochId, Option<EpochInfo>>,
/// 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

View File

@ -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<MigrationOutcome, Migra
})
}
/// Restore the exact version-1 manifest before any format-2 commit exists.
pub fn rollback_migration(root: &Path) -> Result<PathBuf, MigrationError> {
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::<Result<Vec<_>, _>>()
.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<T: Serialize>(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<T: Serialize>(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(),

View File

@ -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<Uuid>,
/// 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<String>) -> Result<Self, TransactionError> {
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<Uuid> {
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);

View File

@ -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<Self, WorkspaceError> {
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<EpochInfo, WorkspaceError> {
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<crate::epoch::EpochId, WorkspaceError> {
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<crate::epoch::EpochId, WorkspaceError> {
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<Vec<crate::epoch::EpochId>, 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::<crate::epoch::EpochId>()
&& 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<PathBuf, WorkspaceError> {
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<usize, WorkspaceError> {
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<crate::entity::Entity>,
label: &str,
) -> Result<(), WorkspaceError> {
let mut ids = before
.iter()
.chain(changed)
.map(|entity| entity.id)
.collect::<Vec<_>>();
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],

View File

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

View File

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