# 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. The earlier format-1.0 layout remains readable. Prototype layouts before 1.0 remain unsupported. The manifest currently records format `1.1` 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` places an inverse change in the worktree by default; `--commit` explicitly creates a new inverse commit and warns before doing so. `efo prune-future` previews later epochs and, with confirmation, moves them into a restorable backup rather than deleting them. Pruning removes future-pointing tags and preserves the monotonic allocator; its backup records both so restoration reconstructs the original timeline metadata without reusing removed IDs. `efo reset --hard TARGET --yes` is the exceptional destructive path. It resets HEAD, index, and worktree, permanently deletes all newer epoch directories, removes tags that point to them, and permits their numeric IDs to be reused. There is deliberately no Epoch Forge undo. Run it without `--yes` first to see the exact scope, and keep important repositories under external version control or backup. ## 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. ## Epoch resolution state (1.1) The optional `epoch_resolution` field stores ruleset `epoch-forge/epoch-resolution-1`, a complete first-resolution baseline, and the set of enrolled adjudication IDs. The baseline has no nested resolution state. Each new adjudication identifies its `epoch_baseline`; absent fields on 1.0 records mean historical sequential semantics. Old records are never enrolled implicitly; their already-applied effects become part of the first new baseline. Committed snapshots retain the interval's audit inputs; a new interval replaces the worktree's baseline rather than nesting previous ones. Existing 1.0 repositories open without writes. Applying a resolution upgrades the worktree and manifest together under the writer lock in a manifest-last transaction. A preview never upgrades. New repositories and newly published history use 1.1. Older binaries reject the newer minor version; there is no lossy downgrade path. Historical 1.0 epochs remain unmodified. Recovery uses `efo recover`; restoring a resolution removes its worktree changes while retaining the protective manifest version. To use an older binary again, restore an external backup of the entire pre-upgrade repository. A resolution couples entity statistics, source state, and audit membership. Stage or restore the complete change with `--all`; partial operations that would separate those parts fail before writing. `fsck` validates membership, epoch identity, local clamps, active aggregate statistics, and source reduction. Manual changes to an actively contributing statistic require committing the resolution first (or restoring it). Other fields remain editable; a newly resolved field must still match its frozen baseline. Resolution publication rejects any repository change since preview, including unrelated metadata.