2.6 KiB
Architecture and development
CLI (`bin_efo`) TUI (`tui_efo`)
│ │
└─────┬──────┘
▼
domain and persistence (`lib_efo`)
│
▼
`.epoch` and `epoch/*`
bin_efo defines the Clap command tree and presentation. tui_efo owns only
its input loop, view state, and terminal presentation. lib_efo owns entities,
statistics, identifiers, epochs, naming, and JSON persistence. New behavior
should be a testable library operation with thin CLI and TUI adapters.
The design direction is to make repository paths explicit; replace truncating 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 approved persistence boundary is specified in the
staging, history, and recovery design. It separates HEAD,
the index, and the editable worktree, and defines the atomic transaction rules
that implementation must preserve. Repository format 1.1 adds a persisted epoch-resolution baseline; 1.0 remains
readable and upgrades atomically on resolution publication or new history.
The structured version rejects readers that cannot preserve the new state.
The TUI contract covers browsing and previewed entity editing.
EntityDraft validates forms in the library; Workspace::apply_entity_change
checks the editor snapshot and writes the worktree under one transaction lock.
The TUI retains the prior entity for one-step, conflict-checked undo.
Library tests cover parsing, statistics, display snapshots, entity/epoch
behavior, and repository transactions. CLI behavior is covered by subprocess
integration workflows; Tarpaulin excludes those thin adapters because its
ptrace backend cannot reliably attribute child-process execution. Routine CI
should run formatting, all-target workspace tests, strict Clippy, and a release
build. Tarpaulin and rust_autobadges remain local significant-release-only
tools. See AGENTS.md for contributor rules.
epoch_resolution owns independent baseline previews and exact contribution
reduction for adjudication, diffusion arrivals, and conflict rounds. CLI handlers
render local and aggregate outcomes and call Workspace::apply_resolution for
locked stale-snapshot validation and publication. event_rng provides immutable
named ChaCha12 draws from frozen event inputs; adjudication remains externally
rolled. See the execution contract.