49 lines
2.6 KiB
Markdown
49 lines
2.6 KiB
Markdown
# Architecture and development
|
|
|
|
```text
|
|
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](staging-design.md). 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](tui-design.md) 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](../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](deterministic-execution-design.md).
|