Design

Architecture

This page summarizes RAHN's architecture — ARCHITECTURE.md is the canonical document, and the accepted ADRs are the authority. What follows is the shape of the design and where its trade-offs are recorded.

The problem

Networks have no first-class state object. Desired-config tools and symptom-observing tools both exist; the state itself — the thing that fails — is reconstructed by hand. RAHN's answer is to make state a value: deterministic, content-addressed, changed only by explicit transitions.

Core lifecycle

1. Declare state — nodes, interfaces, links in canonical format v2.
2. Propose transitions — explicit operations from a closed vocabulary.
3. Verify — the constitution must hold; rahn test makes the verdict CI-consumable.
4. Simulate — apply produces an execution plan, simulated by default.
5. Execute — opt-in — isolated Linux namespaces only, after verification, behind --yes-i-know.

Implementation shape (v1.0)

A Cargo workspace with one responsibility per crate: rahn-core (object model), rahn-state (canonical serialization, transitions, diff, history, graph queries, observations, causal records), rahn-store (content-addressed persistence), rahn-verify (invariant engine, constitution parsing, fail-closed merge), rahn-sim (default, host-touching-free backend), rahn-exec (isolated namespace backend), rahn-dist (peer sync), rahn-sdk (curated semver-stable facade), and rahn-cli (the rahn binary). See why Rust for the language rationale.

Trade-offs, recorded

• Explicitness costs ergonomics. Transitions, verification, and provenance are more work than editing configs — accepted deliberately.
• Determinism costs resources. Canonical serialization and hashing cost CPU and storage; history grows until pruning is designed.
• Fail-closed merge rejects some mergeable states. Wrong merges are worse than rejected ones; the price is quantified in open research (RQ3/E3).
• Per-replica authority, no cross-replica strong consistency. The distributed model (ADR 0015) chose fail-closed divergence over consensus.

Failure modes

ARCHITECTURE.md §8 reasons about them explicitly: unmodeled reality, over-trusted verification, blind-spot encoding, and the gap between the model and the network. The recurring theme — verification is only as good as its encoding — is why limitations are part of the architecture rather than a footnote. For the decision history, read the 19 ADRs; for the normative rules, the specifications.