76 lines
2.6 KiB
Markdown
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).
|