epoch_forge/docs/architecture.md

2.7 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 cannot attribute child-process execution to the thin CLI adapters, but keeps all production code in the measured surface. Routine CI runs formatting, all-target workspace tests, strict Clippy, a release build, and pinned Tarpaulin line coverage with the documented 65% floor. During cleanup, Jenkins generates, archives, and conditionally publishes the three mutable badges so failed builds cannot leave stale success or coverage status. 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.