Architectural research project · v1.0.0 · Rust

Network state, treated as a first-class computational object.

RAHN makes network state deterministic, content-addressed, and verifiable: state is a value, changed only by explicit transitions, gated by a constitution of invariants, and executed simulation-first.

Explore the repository See how it works

Simulation-only demo, byte-identical results on every machine — verified on Linux, Windows, and macOS CI.

RAHN — a path for evolving networks: the arch mark and wordmark beside an arched window opening onto mountains and a winding road
Releases
11
Accepted ADRs
19
Tests
136
Spec documents
11

The idea

What if a network's state were a value, not a vague condition?

Today, "the state of the network" is something you discover — by logging in, running show commands, and hoping. RAHN inverts that: state is a deterministic, content-addressed value you can hold, hash, branch, diff, and evolve deliberately.

Versioned

Every state change is a commit. History is a first-class, queryable structure — not a scattering of device configs.

Causal

Observations and commits are linked by explicitly labeled causal edges with epistemic status — from temporal-correlation to verified.

Verifiable

A constitution of invariants gates every transition. What cannot be proven to hold does not commit — let alone execute.

Safely evolvable

Branch, diff, and merge with a fail-closed semantic merge: wrong merges are worse than rejected ones, so conflicts are explained, never silently resolved.

Can network state become a first-class computational object — versioned, causal, verifiable, replayable, and safely evolvable?

— the question RAHN exists to test

Non-negotiables

Six principles the architecture refuses to trade away

  1. Determinism

    No nondeterministic iteration order, wall-clock logic, or hidden global state. Same inputs → byte-identical states, ids, and reports.

  2. Explicit transitions

    Committed state changes flow only through a closed vocabulary of operations. Nothing mutates a state in place, ever.

  3. Constitution-gated change

    Invariants — from referential integrity to named connectivity — are checked before a transition can commit. Failures carry the violated invariant, the offending objects, and the producing transition.

  4. Simulation first

    Every plan is executed in simulation by default. The simulation backend never touches the host.

  5. Verify before execute

    The execution path is structurally unreachable without a verification result, and real execution is opt-in against isolated Linux network namespaces only.

  6. No AI in the core

    The system must remain correct, explainable, and reproducible without any model. Causal memory records relationships; it does not guess them.

How it works

One path from intent to (opt-in) execution

Every change travels the same road — and the last step is behind a gate that cannot be bypassed.

  1. Declare state

    Nodes, interfaces, and links form a network state — a canonical, content-addressed value with format v2.

  2. Propose transitions

    Changes are explicit operations from a closed vocabulary — inspectable before anything happens.

  3. Verify

    The constitution of invariants must hold. rahn test turns the result into a CI-ready report with an exit-code contract.

  4. Simulate

    Apply produces an execution plan, simulated by default against a backend that cannot touch the host.

  5. Execute — opt-in

    Only --execute --yes-i-know, only against isolated Linux network namespaces, only after verification.

Demo output — the same ids on every machine
$ bash examples/demo/demo.sh
final ids (stable across runs on every machine):
  main       commit ad60e9186c674c46…
             state  fc9aac0400618034…
  experiment commit 684a0103807763af…
             state  5446796f93d189fc…

Honest boundaries

What RAHN is not

Research earns trust by stating its limits. RAHN's claims are claim-status-marked against a public limitations baseline.

  • Not a production network controller. It is an architectural research project, at research maturity by design.
  • Not a router, SDN controller, or IaC tool. It changes the substrate those tools could one day stand on.
  • Not “Git for networks.” Branching and merging exist, but the semantics — invariants, causality, verification-gated execution — are a different discipline.
  • Not AI-assisted. No model anywhere in the core; correctness never depends on one.

The code

A workspace with one job per crate

rahn-core

Object model: nodes, interfaces, links, network, state value.

rahn-state

Canonical serialization, state identity, transitions, commits, diff, history, graph queries, observations, causal records.

rahn-store

Content-addressed local persistence: objects, commits, refs, index.

rahn-verify

Invariant engine, constitution parsing, fail-closed semantic merge.

rahn-sim

Simulation-only execution planning. The default backend — never touches the host.

rahn-exec

Opt-in isolated Linux namespace backend, behind a capability-negotiated trait.

rahn-dist

Peer synchronization over content-addressed history.

rahn-sdk

The curated, semver-stable public API facade for external code.

rahn-cli

The rahn binary and its argument parsing.

19 Architecture Decision Records Normative specifications Research corpus & limitations White paper

Eleven releases, one question

The road to a stable architecture

  1. v0.1.0-alpha.1

    State foundation

    Deterministic state, canonical serialization, content-addressed identity, transitions, diff, branching, fail-closed merge.

  2. v0.1.0-alpha.2

    Hardening & research foundation

    Hardened engine, initial research corpus, CI for the core workspace.

  3. v0.2.0-alpha

    Network graph semantics

    Interfaces owned by nodes, graph queries, isolation constraints, canonical format v2 (ADR 0011).

  4. v0.3.0-alpha

    Isolated Linux execution

    Namespace execution backend with a structural host-safety boundary (ADR 0012).

  5. v0.4.0-alpha

    Observability

    Deterministic observation model with typed values and provenance (ADR 0013).

  6. v0.5.0-alpha

    Causal memory

    Causal anchors, status-labeled edges, incident query (ADR 0014).

  7. v0.6.0-alpha

    Distributed state

    Peer synchronization over content-addressed history (ADR 0015).

  8. v0.7.0-alpha

    Execution backends

    Backend abstraction with capability negotiation (ADR 0016).

  9. v0.8.0-alpha

    Network CI

    rahn test: machine-readable verification for pipelines (ADR 0017).

  10. v0.9.0-alpha

    Programmability

    Curated SDK facade and declared IR (ADR 0018).

  11. v1.0.0

    Stable architecture

    Core model frozen for 1.x, canonical format v2 frozen, 19 ADRs (ADR 0019). Nothing post-v1.0 is scheduled.

Questions

Frequently asked

Read the full technical FAQ

Read the architecture before you believe any of this.

That is the point: RAHN asks to be checked, not trusted.

Read ARCHITECTURE.md Read the limitations