Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|-----------------|---------|
Expand Down Expand Up @@ -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

Expand Down
14 changes: 1 addition & 13 deletions docs/storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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).

---

Expand Down