Skip to content

Error handling and recovery

HieraChain keeps recovery responsibilities close to the component that owns the state: ErrorClassifier records and classifies failures, TransactionJournal protects pending events, and the BFT consensus implementation handles view changes when a leader becomes unavailable. Snapshot and infrastructure recovery are deployment responsibilities, not automatic services in this package.

Runtime flow

flowchart TD
    ERR["Error or node failure"] --> CLASS["ErrorClassifier\nclassify and log"]
    CLASS -->|Eligible priority/category and configured callback| LOCK["Optional lockdown callback"]
    EVENT["Pending journal event"] --> JOURNAL["TransactionJournal\nwrite before ordering"]
    JOURNAL --> RECOVERY["OrderingRecovery\nreplay after restart"]
    RECOVERY --> VALIDATE["Validate before ordering"]
    LEADER["Leader unavailable"] --> VIEW["BFTConsensus\nBFTViewChangeManager"]
    VIEW --> CONSENSUS["Install new view\nresume BFT phases"]

These are separate component-owned paths, not a dispatch chain from ErrorClassifier. Its classify_error() records and returns an ErrorInfo; it may invoke the optional lockdown callback only for CRITICAL security/performance errors or HIGH security errors, and only when a callback is configured. OrderingRecovery replays journal entries, while BFTConsensus owns leader-failure view changes.

Consensus recovery

BFTConsensus owns leader failure handling through BFTViewChangeManager. The manager broadcasts view-change messages, collects the quorum, and installs the new view. This path is part of the consensus runtime and does not depend on a separate recovery engine.

Event durability

TransactionJournal writes pending events before ordering. After a restart, the ordering service can replay journal entries and validate them before they re-enter the event pipeline.

If an append fails after writing part of a frame, the journal truncates back to the frame's original offset and fsyncs that repair before accepting another append. If it cannot confirm the repair, it refuses later writes until the journal is closed and reopened as a new instance, which repairs an incomplete active tail during startup.

from hierachain.error_mitigation.journal import TransactionJournal

journal = TransactionJournal(storage_dir="data/journal")
journal.log_event(event_dict)

Operational recovery

Database backups, filesystem snapshots, key recovery, and infrastructure scaling must be provided by the deployment environment. The repository does not claim automatic rollback, backup restoration, redundant network transport, or node autoscaling through error_mitigation classes.