2.5 KiB
Repository, persistence, and recovery
Layout
.
├── .epoch format version, repository ID, HEAD, allocator, tags
├── .efo/
│ ├── index.json complete staged snapshot
│ ├── worktree.json complete editable snapshot
│ ├── lock present only while a writer owns the repository
│ └── transaction.json present only during/recovering a transaction
└── epoch/
├── 0/epochinfo.json immutable initial world
├── 1/epochinfo.json immutable committed world
└── …
efo init creates this layout directly. There is no earlier supported format:
Epoch Forge has not made a stable release, so the former prototype layout and
its temporary migration path were removed rather than carried as compatibility
debt.
The manifest currently records format 1.0 as a structured major/minor value.
The application version is separate. Minor format releases (1.1, 1.2, …)
may use explicit migrations while preserving the major compatibility family;
a future breaking layout would increment the major version. Newer minor or
major formats are rejected instead of guessed.
State and history
Entity and annotation commands edit .efo/worktree.json. efo stage copies
selected state into .efo/index.json; efo commit creates a new immutable
epoch from the index and aligns all three layers. efo restore always names
which layer it replaces. IDs are monotonic and never reused.
efo switch requires clean state and never deletes later history. efo revert
creates a new inverse commit. efo prune-future previews later epochs and,
with confirmation, moves them into a restorable backup rather than deleting
them. The old destructive epoch reset behavior is not supported.
Transaction safety and recovery
Writes use an exclusive repository lock and a durable manifest-last transaction. If a command is interrupted, stop other writers and run:
efo lock inspect
efo recover
Only use efo lock break --yes after verifying that the recorded process no
longer owns the repository, then immediately run efo recover. Recovery either
rolls back a prepared operation or verifies a committed one and is safe to
repeat.
Keep important repositories in Git or another backup system. For corruption,
copy the complete directory before investigation and run the read-only
efo epoch fsck; it reports damage but never guesses a repair.