Architecture overview
A small deterministic core with explicit ownership, immutable readers and bounded work.
Status: Foundation. Core storage/state modules exist. This overview distinguishes their role from the application, query and operational layers still to complete.
Keep the transaction path explicit
RURAL begins with one ordered mutation owner and immutable reader snapshots. The mutation owner prepares a candidate state, journals its exact intent and publishes the new root. Readers retain a committed root and work outside the mutation path.
This keeps ownership visible and makes failure boundaries testable. It does not remove contention for CPU, memory bandwidth, allocator work or storage I/O. Future partition writers require measured need and explicit cross-partition semantics.
| Layer | Responsibility | Current boundary |
|---|---|---|
| Persistent map | Share immutable records across roots; ordered lookup and iteration. | Implemented in memory. |
| Prepared state | Atomic byte batches, branch heads, versions and scoped receipts. | Implemented pure state layer. |
| Framing and journal | Bounded encoding, integrity, exclusive ownership, ordered synchronized append. | Implemented local foundations. |
| Durable owner | Coordinate locks, preparation, journal I/O and publication. | Integration source exists; complete checkout is not accepted. |
| Models, query and graph | Give records schemas, predicates, indexes and relationships. | Product layer pending. |
| Intake and analytics | Preserve source identity, corrections and metric meaning. | Design and acceptance work. |
| Oracle and application | Bind current authority, user workflows and compact evidence. | Integration pending. |
Share data instead of copying worlds
Persistent tree roots let a branch retain unchanged structure. Updating a record copies the affected paths and shares the rest. Payload ownership is separate, so changing a nearby key does not copy an ancestor's large value.
Snapshot depth does not create a chain of parent lookups. Retained history still consumes memory, and releasing the final owner may reclaim many nodes. The later disk engine must preserve these visibility rules while adding paging, checkpoints and reclamation.
Treat formats and limits as contracts
The log codec uses explicit field widths and byte order. The journal owns sequence continuity and its file identity. The state layer verifies deterministic typed intent and current version context. Each boundary admits a bounded amount of work.
Higher layers must connect those limits rather than assume a per-request cap also bounds an entire process. Readers, parsing buffers, queued writes, retained branches and maintenance all consume resources.
Preserve original authority
Repository code remains in Git/files. Providers remain authoritative for the observations they report. RURAL is intended to own accepted application transactions and their recorded provenance. A query result is a view over those sources, not a reason to silently change their authority.
For the implementation details, continue with the persistent map, state engine and journal.