# Repository, persistence, and recovery ## Layout ```text . ├── .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: ```bash 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.