70 lines
3.1 KiB
Markdown
70 lines
3.1 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`
|
|
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.
|