epoch_forge/docs/repository.md

3.1 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 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:

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.