epoch_forge/docs/repository.md

60 lines
2.5 KiB
Markdown

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