epoch_forge/docs/repository.md

2.6 KiB

Repository, persistence, and recovery

Layout

.
├── .epoch                  current epoch, build version, global tag map
└── epoch/
    ├── 0/epochinfo.json    complete epoch-0 world snapshot
    ├── 1/epochinfo.json    complete epoch-1 world snapshot
    └── …

.epoch is JSON despite having no extension. Each snapshot stores its ID, random seed, tags, summary, and arrays of events, characters, towns, calamities, and blockers. The full world is duplicated per epoch.

Entity commands edit the current snapshot directly. epoch next creates a new snapshot; epoch switch only changes the current pointer. epoch reset deletes later directories. Individual JSON files are written through same-directory temporary files and atomically replaced. This is not yet Git-equivalent: there is no working tree/index separation, reflog, repository locking, atomic transaction spanning multiple files, or built-in undelete.

Safety and recovery

Keep the directory in Git or copy it before important changes:

git init
git add .epoch epoch/
git commit -m "backup Epoch Forge world"

To revisit prior data without deleting the future:

efo epoch log
efo epoch switch 0
efo status

Back up before epoch reset; Epoch Forge cannot recover its deleted folders. For corruption, stop mutating, copy the complete directory, and run the read-only efo epoch fsck. Restore from a known-good backup; fsck deliberately does not repair or discard data.

The config records a writer version, but automatic migrations and unknown-field retention are not implemented. Format-2 migration is explicit and preview-only unless confirmed:

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

efo migrate --rollback
efo migrate --rollback --yes

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.