96 lines
4.8 KiB
Markdown
96 lines
4.8 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. 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.
|