docs: propose reversible staging contract

This commit is contained in:
Dandaedre 2026-09-20 22:09:02 +02:00
parent 1f24bc58b9
commit d4548ff479
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
5 changed files with 180 additions and 9 deletions

View File

@ -78,11 +78,12 @@ format-level decisions before implementation.
## Phase 4 — Git-like reversible workflow
- [ ] Write and approve a design for working state, pseudo-staging, committed
epochs, and recovery semantics before implementing it.
- [ ] Define `diff`, `stage`, `unstage`/`restore --staged`, `commit`, `restore`,
- [ ] Approve the written design for working state, pseudo-staging, committed
epochs, and recovery semantics before implementing it. See
[the Phase 4 proposal](docs/staging-design.md).
- [x] Define `diff`, `stage`, `unstage`/`restore --staged`, `commit`, `restore`,
`revert`, and `log` behavior, including entity-level selection.
- [ ] Define crash consistency, locking, concurrent-process behavior, and
- [x] Define crash consistency, locking, concurrent-process behavior, and
repository format versioning.
- [ ] Add migration fixtures for all prior supported repository versions.
- [ ] Implement only after the design preserves current data and allows every

View File

@ -7,6 +7,8 @@ behavior clearly.
- [Repository format](repository.md): files, epochs, compatibility, backup, and recovery.
- [Reversing changes](recovery.md): checkpoints and recovery for every mutation.
- [Architecture](architecture.md): crate responsibilities, data flow, and quality gates.
- [Staging design](staging-design.md): proposed Phase 4 state, command, transaction,
and migration contract.
- [Roadmap](roadmap.md): current work and stretch proposals.
Start with the project [README](../README.md). Contributors should also read

View File

@ -19,6 +19,12 @@ writes with temporary-file plus rename; add locking; remove unsafe cache
accessors; separate styling from semantic output; and retain unknown custom
metadata as the model becomes organisation-agnostic.
Phase 4's proposed persistence boundary is specified in the
[staging, history, and recovery design](staging-design.md). It separates HEAD,
the index, and the editable worktree, and defines the atomic transaction and
migration rules that implementation must preserve. The proposal requires user
approval before repository-format code changes begin.
Library tests currently cover parsing, statistics, display snapshots, and parts
of entity/epoch behavior. CLI integration coverage is the main gap. Routine CI
should run formatting, all-target workspace tests, strict Clippy, and a release

View File

@ -24,11 +24,11 @@ and every mutation has documented and tested recovery guidance.
The next milestone is the reviewed repository-format design for working state,
pseudo-staging, restore, and revert. Implementation begins only after those
compatibility and crash-consistency decisions are approved.
Next comes a reviewed Git-like model for working changes, pseudo-staging,
committed epochs, restore, and revert. Organisation-agnostic custom fields and
types follow, with migrations and unknown-field retention designed first.
compatibility and crash-consistency decisions in the
[Phase 4 proposal](staging-design.md) are approved. Implementation then proceeds
through migration fixtures, transactions and locking, staging, and reversible
history. Organisation-agnostic custom fields and types follow, with migrations
and unknown-field retention designed first.
## Proposed stretch goals

162
docs/staging-design.md Normal file
View File

@ -0,0 +1,162 @@
# Staging, history, and recovery design
Status: **proposed for approval**. This document is the Phase 4 contract; it
does not describe behavior available in the current release. Persisted-format
implementation must not begin until this contract is approved.
The goal is a familiar Git-like workflow without pretending that Epoch Forge
is Git. A repository has one editable timeline, every meaningful change can be
inspected before it becomes history, and ordinary mistakes are reversible from
the CLI.
## State model
Version 2 repositories have three intentionally separate states:
1. **HEAD** is the immutable committed snapshot at
`epoch/<id>/epochinfo.json`.
2. **Index** is the complete proposed next snapshot in `.efo/index.json`.
3. **Worktree** is the complete editable snapshot in `.efo/worktree.json`.
Complete snapshots keep recovery understandable and avoid reconstructing state
from a fragile chain of patches. Entity-level staging copies selected entities
between snapshots; it does not change the on-disk representation into partial
patches. Every snapshot carries a schema version and repository identity.
The root `.epoch` manifest remains the small source of repository identity and
HEAD selection. Version 2 adds `format_version: 2` and a monotonic
`next_epoch_id`; existing identity, current epoch, version, and tag information
is retained. Epoch IDs are never reused, including after old future history is
pruned.
Transient state lives under `.efo/`:
```text
.epoch repository manifest and commit point
.efo/index.json staged complete snapshot
.efo/worktree.json editable complete snapshot
.efo/lock exclusive writer ownership
.efo/transaction.json recoverable in-progress operation journal
.efo/migrations/ byte-for-byte pre-migration backups
epoch/<id>/epochinfo.json immutable committed snapshots
```
## Command contract
Commands use both plain text and decorative symbols: symbols and colour may
reinforce meaning, but never carry meaning alone.
- `efo status` reports HEAD plus staged and unstaged changes separately. It
names entity kind and ID and gives the next useful command.
- `efo diff` compares index to worktree. `efo diff --staged` compares HEAD to
index. Output is deterministic and field-oriented; `--no-color` remains
readable and scriptable.
- `efo stage --all` copies the complete worktree to the index. Entity selectors
(`--kind <kind> <id>...`) copy only those entities, including deletion.
`efo stage --world` selects world-level metadata. Invalid or ambiguous
selectors change nothing.
- `efo restore --staged ...` copies selected state from HEAD to the index.
`efo restore --worktree ...` copies from the index to the worktree. One layer
flag is mandatory, and the same entity selectors and `--all` are supported.
This explicitness prevents accidental data loss. `unstage` may exist only as
a documented alias for `restore --staged`.
- `efo commit -m <message>` validates the index, creates one immutable epoch,
advances HEAD, then makes index and worktree equal to the new HEAD. An empty
commit is rejected with guidance. Commit messages are required and stored as
snapshot metadata.
- `efo epoch next` remains the simulation-oriented convenience operation. It
requires no unstaged changes, advances time in the index, validates it, and
commits it as one transaction. Already staged changes are included and shown
in the confirmation summary.
- `efo log` displays newest-first immutable history with epoch ID, in-world
date, message, and tags. Stable plain output is available independently of
Nerd Fonts and colour.
- `efo switch <epoch>` changes HEAD only when index and worktree are clean, then
resets both transient snapshots to the selected commit. `--force` is not a
shortcut; users must explicitly restore or commit first.
- `efo revert <epoch>` computes the inverse of that epoch relative to its
predecessor and applies it to the current index. It then creates a new commit
after confirmation. It never deletes history. Conflicts abort without
changing any layer and list affected fields.
- The destructive historical `reset` operation is renamed `prune-future`.
`reset` remains a deprecated alias for one release. Pruning always shows a
dry-run, requires confirmation unless `--yes` is supplied, never rewinds the
ID allocator, and leaves a migration-style backup that can be restored.
Mutating commands refuse to proceed with an invalid layer. Errors state what
happened, what was left unchanged, and the safest recovery command.
## Atomicity and crash recovery
All mutations use one repository transaction:
1. Create the writer lock exclusively.
2. Resolve the repository once, read all inputs, and validate preconditions.
3. Write replacement files into a transaction directory on the same
filesystem, flush them, and record old/new hashes plus ordered renames in
`.efo/transaction.json`.
4. Rename immutable epoch data first, transient snapshots second, and `.epoch`
last. The manifest rename is the commit point.
5. Flush affected directories, verify hashes and invariants, remove the journal,
then release the lock.
Before the commit point, recovery rolls back transient replacements. After it,
recovery finishes the recorded operation. `efo recover` performs that decision
deterministically and explains it before changing files; normal commands refuse
to mutate a repository with an unfinished journal. Re-running recovery is safe.
Readers may operate while no journal exists. Only one writer is allowed. The
lock records repository UUID, PID plus process-start token, hostname, command,
and creation time. A lock is never considered stale from age alone. `efo lock
inspect` explains ownership; `efo lock break` requires proof that the local
process is gone or an explicit confirmation for a remote/unverifiable owner.
## Format migration
Opening format 1 remains read-only compatible. The first write instructs the
user to run `efo migrate --to 2`; migration is never implicit. Migration is a
dry-run by default and requires confirmation (or `--yes`) to execute.
The migration procedure is:
1. Run format-1 integrity checks and reject ambiguity.
2. Copy every affected byte into `.efo/migrations/v1-<timestamp>/` and write a
hash manifest.
3. Create worktree and index from the selected epoch and set `next_epoch_id` to
one greater than the maximum ID ever observed, including future epochs.
4. Commit the version-2 manifest atomically, then run version-2 integrity
checks.
Rollback from the backup is supported until the first version-2 commit. After
that, migration is one-way; export remains available. Fixtures must cover empty
and populated repositories, tags, a switched-back repository with future
epochs, relationships, legacy `Monster` naming, and malformed repositories
whose migration must be rejected without modification.
## Compatibility invariants
- Existing epoch contents, IDs, tags, dates, entity IDs, and relationships do
not change during migration.
- Unknown fields survive load/save and migration once the custom-field model is
introduced; Phase 4 must not reserve a representation that prevents this.
- Repository discovery remains independent of the current working directory.
- Every selector is stable by entity ID; display names are never identity.
- Machine-readable output will be versioned separately from human presentation.
- Branching, merging, and remote synchronization are deferred. The format may
gain parent references now, but the CLI remains a single linear timeline.
## Approval checklist
Approval of this design confirms these product choices:
- direct entity edits modify the worktree;
- the index is a complete snapshot with entity-level selection;
- commits are immutable, linear, and use never-reused monotonic IDs;
- restore always names the layer it may overwrite;
- revert creates new history and aborts on conflicts;
- destructive pruning requires a preview, confirmation, and backup;
- format migration is explicit, validated, backed up, and initially reversible.
After approval, implementation proceeds in small commits: format types and
fixtures, migration, transaction/locking infrastructure, state/diff/staging,
commit/log/revert, then compatibility cleanup and full release validation.