feat: add explicit format migration workflow

This commit is contained in:
Dandaedre 2026-09-21 00:03:04 +02:00
parent 50d9c3bff8
commit b73030a4fb
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
13 changed files with 193 additions and 28 deletions

View File

@ -11,6 +11,11 @@ acceptance gates on 2026-09-20.
gates on 2026-09-20. The Phase 4 format contract was approved on 2026-09-20;
implementation is now proceeding through isolated compatibility checkpoints.
**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.
## Phase 0 — audit and guardrails
- [x] Inventory workspace crates, commands, persistence files, CI, and tests.
@ -89,8 +94,17 @@ implementation is now proceeding through isolated compatibility checkpoints.
histories, tags, future epochs, relationships, legacy `Monster` naming, and
malformed input; materialise each case through the real legacy manifest and
snapshot types.
- [ ] Implement only after the design preserves current data and allows every
ordinary mistake to be reversed without manual JSON editing.
- [x] Implement explicit `migrate --to 2` planning and confirmation with
read-only validation, monotonic ID allocation, complete transient snapshots,
a byte-for-byte manifest backup, and manifest-last commit semantics.
- [ ] Add transaction journaling, exclusive writer locks, deterministic
recovery, and automatic pre-commit migration rollback.
- [ ] 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
`prune-future`; retire the destructive `reset` spelling through deprecation.
- [ ] 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)

View File

@ -67,7 +67,7 @@ Run `efo --help`, `efo <command> --help`, or see the
| Area | Available now | Not available yet |
|---|---|---|
| Repository | Initialise in the current directory; inspect status | Discovery from child directories; locking; migrations |
| 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 |
| 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 |

View File

@ -12,6 +12,7 @@ pub mod entity_generic;
pub mod epoch;
pub mod generate;
pub mod init;
pub mod migrate;
// pub mod roll;
pub mod show;
pub mod status;

View File

@ -0,0 +1,48 @@
//! Explicit repository-format migration command.
use std::path::Path;
use clap::Args;
use lib_efo::migration::{execute_migration, plan_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"
)]
pub struct MigrateCmd {
/// Repository format to migrate to (currently only 2).
#[arg(long, value_parser = clap::value_parser!(u32).range(2..=2))]
to: u32,
/// Apply the displayed plan; without this flag migration is a dry-run.
#[arg(long)]
yes: bool,
}
/// Validate, preview, and optionally execute a repository migration.
pub fn migrate(command: &MigrateCmd) -> Result<(), AppError> {
let plan = plan_migration(Path::new("."))?;
println!("Migration plan · format 1 → {}", command.to);
println!("├─ Repository {}", plan.root().display());
println!("├─ HEAD epoch {}", plan.current_epoch());
println!("├─ History {} snapshot(s)", plan.epoch_count());
println!("├─ Next ID {}", plan.next_epoch_id());
println!("├─ Tags {}", plan.tags().len());
println!("└─ Validation passed; no source snapshot will be rewritten");
if !command.yes {
println!();
println!("Dry run only — nothing changed.");
println!("Run `efo migrate --to 2 --yes` to create a backup and apply this plan.");
return Ok(());
}
let outcome = execute_migration(&plan)?;
println!();
println!("✓ Repository migrated to format 2.");
println!(" Backup: {}", outcome.backup_directory.display());
println!(" Recovery: preserve `.efo/` and this backup until the first format-2 commit.");
Ok(())
}

View File

@ -5,7 +5,10 @@
#![warn(missing_docs, clippy::missing_docs_in_private_items)]
use lib_efo::error::{EpochError, StorageError};
use lib_efo::{
error::{EpochError, StorageError},
migration::MigrationError,
};
use miette::Diagnostic;
use thiserror::Error;
@ -31,6 +34,10 @@ pub enum AppError {
#[error("Storage error: {0}")]
// #[diagnostic(transparent)]
Storage(#[from] StorageError),
/// Repository-format migration failed safely.
#[error("Migration stopped: {0}")]
Migration(#[from] MigrationError),
// /// Anything else we didn't anticipate.
// #[error("Unknown error: {0}")]
// Other(String),

View File

@ -30,7 +30,7 @@ use clap::{Parser, Subcommand};
use crate::{
commands::{
entity_generic::EntitySubCommands, epoch::cli_epoch::EpochCmd, generate::GenCmd,
init::InitCmd, show::ShowCmd, status::StatusCmd,
init::InitCmd, migrate::MigrateCmd, show::ShowCmd, status::StatusCmd,
},
error::AppError,
};
@ -66,6 +66,8 @@ struct Cli {
enum TopLevelCmd {
/// Initialise a new epoch folder.
Init(InitCmd),
/// Preview or apply a repository-format migration.
Migrate(MigrateCmd),
/// Gives a very simple status.
Status(StatusCmd),
/// Advance or query the current epoch.
@ -145,6 +147,7 @@ fn main() -> miette::Result<()> {
fn exec_dispatch(cli: Cli) -> Result<(), AppError> {
match cli.command {
TopLevelCmd::Init(cmd) => commands::init::init(&cmd),
TopLevelCmd::Migrate(cmd) => commands::migrate::migrate(&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

@ -67,6 +67,7 @@ fn help_is_available_without_a_repository() {
let text = stdout(&output);
assert!(text.contains("Usage: efo <COMMAND>"));
assert!(text.contains("epoch"));
assert!(text.contains("migrate"));
assert!(text.contains("status"));
}
@ -77,6 +78,7 @@ fn help_version_and_invalid_invocations_follow_cli_conventions() {
&["epoch", "--help"][..],
&["chr", "add", "--help"][..],
&["show", "--help"][..],
&["migrate", "--help"][..],
&["gen", "event", "--help"][..],
] {
let output = efo(&repo, args);
@ -147,6 +149,48 @@ fn init_status_diff_and_fsck_workflow() {
assert!(stdout(&fsck).contains("Repository is consistent (2 epoch(s) checked)"));
}
#[test]
fn migration_is_dry_run_by_default_and_backs_up_before_commit() {
let repo = TestRepo::new();
assert_success(&efo(&repo, &["init"]));
assert_success(&efo(&repo, &["chr", "add", "Aria"]));
let legacy_manifest = fs::read(repo.path().join(".epoch")).expect("legacy manifest");
let preview = efo(&repo, &["migrate", "--to", "2"]);
assert_success(&preview);
let preview_text = stdout(&preview);
assert!(preview_text.contains("Migration plan · format 1 → 2"));
assert!(preview_text.contains("Dry run only — nothing changed"));
assert_eq!(
fs::read(repo.path().join(".epoch")).expect("manifest after preview"),
legacy_manifest
);
assert!(!repo.path().join(".efo").exists());
let applied = efo(&repo, &["migrate", "--to", "2", "--yes"]);
assert_success(&applied);
assert!(stdout(&applied).contains("Repository migrated to format 2"));
let manifest: serde_json::Value =
serde_json::from_slice(&fs::read(repo.path().join(".epoch")).expect("migrated manifest"))
.expect("parse migrated manifest");
assert_eq!(manifest["format_version"], 2);
assert!(repo.path().join(".efo/index.json").is_file());
assert!(repo.path().join(".efo/worktree.json").is_file());
let backups = fs::read_dir(repo.path().join(".efo/migrations"))
.expect("migration backups")
.collect::<Result<Vec<_>, _>>()
.expect("list migration backups");
assert_eq!(backups.len(), 1);
assert_eq!(
fs::read(backups[0].path().join(".epoch")).expect("backed-up manifest"),
legacy_manifest
);
let protected = efo(&repo, &["status"]);
assert!(!protected.status.success());
assert!(stderr(&protected).contains("does not yet support repository format 2"));
}
#[test]
fn init_force_preserves_unrelated_files_and_never_overwrites_a_repository() {
let repo = TestRepo::new();

View File

@ -8,6 +8,10 @@ parent directories. `efo <command> --help` is the authoritative syntax.
- `efo init [--force]` creates `.epoch` and `epoch/0/epochinfo.json`. The normal
form requires an empty directory; `--force` permits unrelated existing files
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.
- `efo status [EPOCH_ID]` shows an epoch summary, tags, and entity counts.
- `efo epoch log [-c N]` shows epochs around the current epoch.
- `efo epoch next` creates and checks out the next snapshot. It refuses while
@ -42,7 +46,7 @@ Common add/edit options include `--stats key:value ...`, `--position x,y`,
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 yet.
not exist yet in format 1.
`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

@ -46,7 +46,30 @@ read-only `efo epoch fsck`. Restore from a known-good backup; `fsck` deliberatel
does not repair or discard data.
The config records a writer version, but automatic migrations and unknown-field
retention are not implemented. The intended compatibility policy is that newer
supported binaries migrate without data loss, format changes provide preview
and backup, and future custom fields survive round trips. Current work is
tracked in [the roadmap](roadmap.md).
retention are not implemented. Format-2 migration is explicit and preview-only
unless confirmed:
```bash
efo migrate --to 2
efo migrate --to 2 --yes
```
Migration validates every epoch before writing, preserves epoch IDs and future
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:
```bash
mv .efo .efo-format2-backup
cp .efo-format2-backup/migrations/v1-*/.epoch .epoch
efo epoch fsck
```
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).

View File

@ -22,13 +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 next milestone is the reviewed repository-format design for working state,
pseudo-staging, restore, and revert. Implementation begins only after those
compatibility and crash-consistency decisions in the
[Phase 4 proposal](staging-design.md) are approved. Implementation then proceeds
through migration fixtures, transactions and locking, staging, and reversible
history. Organisation-agnostic custom fields and types follow, with migrations
and unknown-field retention designed first.
The [Phase 4 format contract](staging-design.md) is approved. 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.
## Proposed stretch goals

View File

@ -77,16 +77,23 @@ impl EpochConfig {
if path.is_file() {
// TODO(6): write a trait for this
let config: EpochConfig = serde_json::from_str(&io_err_with_help!(
read_to_string(path),
"Reading config from path {:?}",
path
)?)
.map_err(|e| EpochError::Serde {
source: e,
file_name: path.to_string_lossy().to_string(),
version: format!("Current version: {}", env!("EFO_SHORT_VERSION")),
})?;
let contents =
io_err_with_help!(read_to_string(path), "Reading config from path {:?}", path)?;
let value: serde_json::Value =
serde_json::from_str(&contents).map_err(|e| EpochError::Serde {
source: e,
file_name: path.to_string_lossy().to_string(),
version: format!("Current version: {}", env!("EFO_SHORT_VERSION")),
})?;
if value.get("format_version").and_then(|v| v.as_u64()) == Some(2) {
return Err(EpochError::FormatTwoCommandPending);
}
let config: EpochConfig =
serde_json::from_value(value).map_err(|e| EpochError::Serde {
source: e,
file_name: path.to_string_lossy().to_string(),
version: format!("Current version: {}", env!("EFO_SHORT_VERSION")),
})?;
Ok(config.initialize()?)
} else {
Err(EpochError::MainFolderInvalid(

View File

@ -54,6 +54,14 @@ pub enum StorageError {
// TODO(2): Split effectively user errors to avoid the usage of advice and such
#[derive(Error, Debug, Diagnostic)]
pub enum EpochError {
/// A format-2 repository was opened by a legacy command path.
#[error("This command does not yet support repository format 2")]
#[diagnostic(code(EpochError::FormatTwoCommandPending))]
#[diagnostic(help(
"Your data is intact. Use `efo migrate --to 2` to inspect the repository; staging commands arrive in the next checkpoint."
))]
FormatTwoCommandPending,
/// Problems with the `.epochconfig` file.
#[error("Failed to read epoch configuration")]
#[diagnostic(code(EpochError::ConfigRead))]

View File

@ -160,6 +160,13 @@ pub fn plan_migration(root: &Path) -> Result<MigrationPlan, MigrationError> {
)));
}
validate_entities(id, &snapshot)?;
for tag in snapshot.tags.iter() {
if legacy.tags.get(tag) != Some(&id) {
return Err(MigrationError::Invalid(format!(
"tag `{tag}` in epoch {id} is inconsistent with .epoch"
)));
}
}
epoch_ids.push(id);
snapshots.insert(id, snapshot);
}
@ -257,7 +264,7 @@ fn prepare_workspace(
repository_id,
plan.legacy.epoch_id,
plan.next_epoch_id,
plan.legacy.version.clone(),
env!("EFO_SHORT_VERSION").to_owned(),
plan.legacy.tags.clone(),
))
}