The README makes claims. This file backs them up, traces the critical paths, and tells a reviewer exactly where to look.
Flatracoon operating system and networking stack.
How it works:
FlatRacoon is a workspace of independent subsystems, each a self-contained module
under netstack/modules/. The networking half (netstack/) holds crates for
DNS (Hesiod), BGP labs, IPFS overlay, ZeroTier Kubernetes bridging, and an IPv6
site enforcer. The OS half (os/) holds the FlatRacoon OS core, also in its own
module layout with src/, ffi/, and presentation layers following the
Idris2-ABI/Zig-FFI architecture standard.
The entry point for DNS work is netstack/modules/hesiod-dns-map/, a Rust
workspace that compiles to two binaries: hesiod-lib (the library) and
hesinfo (the CLI query tool). hesiod-lib/src/lib.rs re-exports five
sub-modules: config, health, records, server, and zone — providing
HS-class TXT record management, a lightweight UDP DNS server, and HTTP
health/metrics endpoints.
Honest caveat:
Most os/ sub-modules and several netstack/modules/ entries (e.g., bgp-backbone-lab,
poly-k8s-mcp) are at early/stub stage. The DNS modules are further along;
the broader OS layer is aspirational.
See TOPOLOGY.md for a visual architecture map and completion dashboard.
How it works:
TOPOLOGY.md at the repo root maps every module with a completion percentage.
The Hesiod DNS module (netstack/modules/hesiod-dns-map/) implements RFC 1035
HS-class (Hesiod class) TXT lookups. The library is #![forbid(unsafe_code)]
and uses Tokio for async I/O. A server.rs provides a UDP listener; zone.rs
manages zone file structures; records.rs holds the typed DNS record model;
health.rs exposes an HTTP metrics endpoint used in FlatRacoon CI pipelines.
Build path: cargo build --release in netstack/modules/hesiod-dns-map/ →
produces hesinfo (CLI) and libhesiod (library linked into OS components).
Honest caveat:
TSIG authentication and actual Hesiod NS delegation are documented in PROOF-NEEDS.md
as not yet implemented. The server currently resolves statically configured zones
only.
| Repo / System | How FlatRacoon is used | Status |
|---|---|---|
|
ZeroTier overlay networking sits inside netstack |
In-module |
|
IPFS gateway module within the netstack |
In-module |
|
DNS/Hesiod subsystem consumed by OS bootstrapper |
In-module |
|
Core OS module referencing netstack services |
In-module |
CI/CD pipelines |
|
Planned |
| Path | What’s There |
|---|---|
|
Network stack top-level; Rust workspace root with |
|
Hesiod DNS library + |
|
Library root; re-exports |
|
UDP DNS server implementation |
|
Typed DNS record model |
|
HTTP health/metrics endpoint |
|
Zone file structure management |
|
BGP lab environment (early stage) |
|
IPFS overlay gateway module |
|
ZeroTier + Kubernetes bridging |
|
IPv6 enforcement policy module |
|
Observability dashboard for the netstack |
|
FlatRacoon OS module; mirrored |
|
OS core source (Rust/Ada depending on subsystem) |
|
Zig FFI bridge (zero-logic pass-through) |
|
Architecture map and per-module completion percentages |
|
Formal verification backlog for this repo |
|
Build recipes: |
|
Reproducible environment definitions |
|
Contractile trust/dust/intend check files |
|
A2ML state, meta, ecosystem, agentic manifests |