epoch_forge/docs/repository.md

76 lines
2.6 KiB
Markdown

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