diff --git a/docs/architecture.md b/docs/architecture.md index f4e6ce0..016d6ba 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -96,7 +96,7 @@ The inference backend is similarly stateless. It always receives the complete fl ### 2. Single embedded storage backend -The storage layer uses [Pebble](https://github.com/cockroachdb/pebble), an embedded key-value store. All data — chain node metadata, payload blobs, LRU accounting, and staging records — lives in a single Pebble database directory. There are no external processes (no SQL server, no object store). +The storage layer uses [Pebble](https://github.com/cockroachdb/pebble), an embedded key-value store. All data — chain node metadata, payload blobs, LRU accounting, and staging records — lives in a single Pebble database directory. There are no external processes. | Deployment level | Storage | |-----------------|---------| @@ -257,7 +257,7 @@ For testing and development, proxy and Charon may be colocated in the same binar ### Access patterns -Charon's workload is append-only point-lookup and sequential parent-pointer walk — no joins, no predicate scans over payload content. These patterns fit an embedded key-value store far better than a relational database. +Charon's workload is append-only point-lookup and sequential parent-pointer walk — no joins, no predicate scans over payload content. ### Single-server throughput expectations diff --git a/docs/storage.md b/docs/storage.md index 24b3220..79d48fb 100644 --- a/docs/storage.md +++ b/docs/storage.md @@ -25,18 +25,6 @@ There are no range scans over content. The hot path is: node lookup → chain wa --- -## Why a Key-Value Store? - -Charon's access patterns are: -- **Append-only writes**: one new node per turn, committed atomically -- **Point lookups**: fetch a node by its response ID -- **Sequential parent-pointer walks**: N sequential node reads from leaf to root during resolve -- **Background eviction**: scan LRU-ordered keys to drop the oldest entries - -These patterns — no joins, no predicate scans over content — fit a key-value store far better than a relational database. An embedded KV store (Pebble) also removes the operational overhead of an external database process and allows the binary to run with no external dependencies. - ---- - ## Chain Reconstruction Strategy | Strategy | Write cost | Read cost | Storage cost | @@ -56,7 +44,7 @@ When `storage.data_dir` is empty or omitted, Charon opens an in-memory Pebble in ### What Is Stored -Charon stores four categories of objects in the KV database: **node metadata** (per-turn chain linkage and timestamps), **payload blobs** (the request and response content for each turn), an **LRU ordering index** (bucket-ordered keys used for capacity eviction), and **staging records** (transient in-flight streaming nodes that are invisible to chain walks and promoted to full nodes on stream commit). +Charon stores four categories of objects in the database: **node metadata** (per-turn chain linkage and timestamps), **payload blobs** (the request and response content for each turn), an **LRU ordering index** (bucket-ordered keys used for capacity eviction), and **staging records** (transient in-flight streaming nodes that are invisible to chain walks and promoted to full nodes on stream commit). ---