feat(reconstruction): ffi interface

Author: rkuris

AGENTS.md

@@ -56,7 +56,7 @@ benchmark/            # Performance benchmarking suite
 ## Important Terminology
 
 - **Revision**: Historical point-in-time state of the trie
-- **View**: Interface to read from a Revision or Proposal
+- **View**: Interface to read from a Revision, Proposal, or Reconstructed view
 - **Node**: Portion of a trie that can point to other nodes and/or contain Key/Value pairs
 - **Hash/Root Hash**: Merkle hash for a node/root node
 - **Proposal**: Consists of base Root Hash and Batch, not yet committed

README.md

@@ -46,7 +46,8 @@ as well as carefully managing the free list during the creation and expiration o
 - `Revision` - A historical point-in-time state/version of the trie. This
   represents the entire trie, including all `Key`/`Value`s at that point
   in time, and all `Node`s.
-- `View` - This is the interface to read from a `Revision` or a `Proposal`.
+- `View` - This is the interface to read from a `Revision`, `Proposal`, or
+  `Reconstructed` view.
 - `Node` - A node is a portion of a trie. A trie consists of nodes that are linked
   together. Nodes can point to other nodes and/or contain `Key`/`Value` pairs.
 - `Hash` - In this context, this refers to the merkle hash for a specific node.
@@ -72,6 +73,14 @@ as well as carefully managing the free list during the creation and expiration o
 - `Proposal` - A proposal consists of a base `Root Hash` and a `Batch`, but is not
   yet committed to the trie. In Firewood's most recent API, a `Proposal` is required
   to `Commit`.
+- `Reconstructed` - A reconstructed view consists of a base historical view and a
+  `Batch` applied in-memory.
+  - It is read-only.
+  - It cannot be committed.
+  - It differs from a `Proposal` because reconstructed views are not tracked as
+    uncommitted branches and do not participate in proposal-parent branching.
+- `Reconstructible` - Either a `Historical` or `Reconstructed` view, which supports
+  building new `Reconstructed` views by applying a `Batch`.
 - `Commit` - The operation of applying one or more `Proposal`s to the most recent
   `Revision`.
 

ffi/firewood.go

@@ -384,8 +384,8 @@ func (db *Database) root() Hash {
 }
 
 // LatestRevision returns a [Revision] representing the latest state of the database.
-// If the latest revision has root [EmptyRoot], it returns an error. The [Revision] must
-// be dropped prior to closing the database.
+// If the latest revision has root [EmptyRoot], it returns an error. The
+// [Revision] must be released with [Revision.Drop] before closing the database.
 //
 // This function conflicts with all other calls that access the latest state of the database,
 // and will lock for the duration of this function.
@@ -406,8 +406,9 @@ func (db *Database) LatestRevision() (*Revision, error) {
 }
 
 // Revision returns a historical revision of the database.
-// If the provided root does not exist (or is the [EmptyRoot]), it returns an error.
-// The [Revision] must be dropped prior to closing the database.
+// If the provided root does not exist (or is the [EmptyRoot]), it returns an
+// error. The [Revision] must be released with [Revision.Drop] before closing
+// the database.
 //
 // This function is thread-safe with all other operations.
 func (db *Database) Revision(root Hash) (*Revision, error) {
@@ -435,7 +436,7 @@ func (db *Database) Revision(root Hash) (*Revision, error) {
 // [context.Context] is cancelled. That is, until all Revisions and Proposals
 // created from this Database are either unreachable or one of
 // [Proposal.Commit], [Proposal.Drop], or [Revision.Drop] has been called on
-// them. Unreachable objects will be automatically dropped before Close returns,
+// them. Unreachable objects will be automatically released before Close returns,
 // unless an alternate GC finalizer is set on them.
 //
 // This is safe to call multiple times; subsequent calls after the first will do

ffi/firewood.h

@@ -21,12 +21,12 @@ import (
 //
 // An Iterator holds a reference to the underlying view, so it can safely outlive the
 // Revision or Proposal it was created from. The underlying state will not be released
-// until the Iterator is dropped.
+// until the Iterator is released.
 //
 // Iterator supports two modes of accessing key-value pairs. [Iterator.Next] copies
 // the key and value into Go-managed memory. [Iterator.NextBorrowed] returns slices
 // that borrow Rust-owned memory, which is faster but the slices are only valid until
-// the next call to Next, NextBorrowed, or Drop.
+// the next call to Next, NextBorrowed, or [Iterator.Drop].
 type Iterator struct {
 	// handle is an opaque pointer to the iterator within Firewood. It should be
 	// passed to the C FFI functions that operate on iterators
@@ -47,7 +47,7 @@ type Iterator struct {
 	currentPair  *ownedKeyValue
 	currentKey   []byte
 	currentValue []byte
-	// FFI resource for current pair or batch to free on advance or drop
+	// FFI resource for current pair or batch to free on advance or release
 	currentResource interface{ free() error }
 
 	// err is the error from the iterator, if any
@@ -149,7 +149,7 @@ func (it *Iterator) NextBorrowed() bool {
 // If the iterator has not been advanced or is exhausted, it returns nil.
 //
 // If the iterator was advanced with [Iterator.NextBorrowed], the returned slice
-// borrows Rust memory and is only valid until the next advance or drop.
+// borrows Rust memory and is only valid until the next advance or release.
 func (it *Iterator) Key() []byte {
 	if it.currentPair == nil || it.err != nil {
 		return nil
@@ -161,7 +161,7 @@ func (it *Iterator) Key() []byte {
 // If the iterator has not been advanced or is exhausted, it returns nil.
 //
 // If the iterator was advanced with [Iterator.NextBorrowed], the returned slice
-// borrows Rust memory and is only valid until the next advance or drop.
+// borrows Rust memory and is only valid until the next advance or release.
 func (it *Iterator) Value() []byte {
 	if it.currentPair == nil || it.err != nil {
 		return nil
@@ -183,7 +183,7 @@ func (it *Iterator) Drop() error {
 	err := it.freeCurrentAllocation()
 	if it.handle != nil {
 		// Always free the iterator even if releasing the current KV/batch failed.
-		// The iterator holds a NodeStore ref that must be dropped.
+		// The iterator holds a NodeStore ref that must be released.
 		err = errors.Join(
 			err,
 			getErrorFromVoidResult(C.fwd_free_iterator(it.handle)))

ffi/iterator.go

@@ -21,11 +21,12 @@ var errDroppedProposal = errors.New("proposal already dropped")
 // Proposals are created via [Database.Propose] or [Proposal.Propose], and must be
 // either committed with [Proposal.Commit] or released with [Proposal.Drop].
 //
-// Proposals must be committed or dropped before the associated database is
-// closed. A finalizer is set on each Proposal to ensure that Drop is called
-// when the Proposal is garbage collected, but relying on finalizers is not
-// recommended. Failing to commit or drop a proposal before the database is
-// closed will cause it to block or fail.
+// Proposals must be committed or released before the associated database is
+// closed. Release is done by calling [Proposal.Drop]. A finalizer is set on
+// each Proposal to ensure Drop is called when the Proposal is garbage
+// collected, but relying on finalizers is not recommended. Failing to commit
+// or release a proposal before the database is closed will cause it to block
+// or fail.
 //
 // All read operations on a Proposal are thread-safe with respect to each other,
 // and can be performed regardless of the state of the associated database. However,
@@ -75,7 +76,7 @@ func (p *Proposal) Get(key []byte) ([]byte, error) {
 // The Iterator must be released with [Iterator.Drop] when no longer needed,
 // otherwise the underlying proposal will never be properly freed.
 //
-// It returns an error if Drop or Commit has already been called on the Proposal.
+// It returns an error if this Proposal has already been committed or released.
 func (p *Proposal) Iter(key []byte) (*Iterator, error) {
 	p.keepAliveHandle.mu.RLock()
 	defer p.keepAliveHandle.mu.RUnlock()
@@ -94,7 +95,7 @@ func (p *Proposal) Iter(key []byte) (*Iterator, error) {
 // Propose is equivalent to [Database.Propose] except that the new proposal is
 // based on `p`.
 // The returned proposal cannot be committed until the parent proposal `p` has been
-// committed. Additionally, it must be committed or dropped before the [Database] is closed.
+// committed. Additionally, it must be committed or released before the [Database] is closed.
 //
 // Use [Put], [Delete], and [PrefixDelete] to create batch operations.
 func (p *Proposal) Propose(batch []BatchOp) (*Proposal, error) {
@@ -142,7 +143,7 @@ func (p *Proposal) Commit() error {
 // Dump returns a DOT (Graphviz) format representation of the trie structure
 // of this proposal for debugging purposes.
 //
-// Returns errDroppedProposal if Commit or Drop has already been called.
+// Returns errDroppedProposal if this Proposal has already been committed or released.
 func (p *Proposal) Dump() (string, error) {
 	p.keepAliveHandle.mu.RLock()
 	defer p.keepAliveHandle.mu.RUnlock()