epoch_forge/docs/architecture.md

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).