# kcode-kweb-db
`kcode-kweb-db` is a blocking, filesystem-backed, convergent store for signed Kweb node and object transactions.
## Public API
```rust
KwebDb::open(path, Config) -> Result<KwebDb>
KwebDb::start_transaction(&self, Provenance) -> Result<Transaction<'_>>
KwebDb::accept_transaction(&self, TransactionPackage) -> Result<bool>
KwebDb::get_node(&self, NodeId) -> Result<Node>
KwebDb::get_node_history(&self, NodeId) -> Result<NodeHistory>
KwebDb::get_object(&self, ObjectId) -> Result<Vec<u8>>
Transaction::create_object(&mut self, Vec<u8>) -> Result<ObjectId>
Transaction::create_node(&mut self, NodeData) -> Result<NodeId>
Transaction::update_node(&mut self, NodeId, NodeData) -> Result<()>
Transaction::connect_node(&mut self, NodeId, NodeId) -> Result<()>
Transaction::merge(&mut self, TransactionId, TransactionId) -> Result<()>
Transaction::finalize(self) -> Result<TransactionId>
```
`Config` contains a 32-byte Ed25519 signing key, a unique strict `writers_by_priority` list containing the local writer, and an `Arc<dyn Gossip>`. Use `WriterId::from_signing_key` to derive the local writer ID. `Gossip::announce` receives a complete `TransactionPackage` after its transaction is durable and the mutation lock is released. It is also called for every retained package on open.
`NodeId` and `ObjectId` are random six-byte locators rendered as exactly 12 lowercase hex characters. `TransactionId` and `WriterId` render as exactly 64 lowercase hex characters. Locators are not hashes or capabilities.
A transaction guard excludes another local builder or inbound package while it exists. Reads continue against the last finalized projection. Dropping the guard commits nothing; `finalize` durably commits and then announces. `accept_transaction` returns `false` only for an exact retained duplicate.
`NodeData` is a complete node revision. Names contain 4–50 characters, short descriptions at most 200 characters, long descriptions at most 1,000 words, and fixed/object references must be unique and locally resolvable. Ordinary connections are additive and directed. `NodeHistory` is the conflict-inspection surface and includes the current frontier, provisionally visible transaction, and deterministic touching entries.
Transactions acknowledge all locally known DAG heads. Missing parents remain durable but pending. Active incomparable node revisions remain on a frontier; descendants supersede ancestors, then writer priority and lexicographically higher same-writer transaction hash select provisional visibility. `merge` only records an exact conflict pair and requires a complete update for a node on that pair's current frontier; it runs no merge algorithm.
Objects are whole-buffer values declared by length and SHA-256 inside signed transactions. A package must carry every declared payload exactly. The ledger is authoritative, object envelopes are self-verifying and transaction-qualified, and node files are rebuildable. One process may open a root at a time. Networking, authorization, migration, deletion, disconnect, garbage collection, streaming, search, and automatic merging are outside this crate.