# Repository, persistence, and recovery ## Layout ```text . ├── .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: ```bash git init git add .epoch epoch/ git commit -m "backup Epoch Forge world" ``` To revisit prior data without deleting the future: ```bash 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. 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).