@feltdb/core 0.8.5 → 0.8.7

package/dist/create/server-source/crates/feltdb/src/operation.rs

@@ -30,6 +30,42 @@ pub struct Operation {
     /// Vector clock for causal tracking (optional for backward compatibility)
     #[serde(default)]
     pub vector_clock: Option<std::collections::HashMap<String, u64>>,
+    /// The historical revision this operation produced on the authority that
+    /// created it.
+    ///
+    /// Carried so a peer can **reconstruct the same revision** rather than mint
+    /// a local substitute for the resulting state. Without it a replica can
+    /// only reproduce what is current, and two authorities end up agreeing
+    /// about what *is* while disagreeing about what *happened*.
+    ///
+    /// Additive and outside `content_hash`, exactly like `vector_clock`: an
+    /// operation from a build that does not send it still verifies, and simply
+    /// carries no history.
+    #[serde(default)]
+    pub revision: Option<RevisionProvenance>,
+}
+
+/// The revision an operation produced, as its originating authority recorded it.
+///
+/// Everything a peer needs to rebuild the identical `StateRevision`. The content
+/// is not repeated — it is the operation's own value — so this adds a bounded
+/// amount to an operation regardless of record size.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct RevisionProvenance {
+    /// The resource whose history this revision belongs to.
+    pub resource: String,
+    /// The revision identity the originating authority committed.
+    pub id: String,
+    /// Its parent, as the origin recorded it — **not** whatever is current on
+    /// the peer. This is what preserves forks.
+    pub parent_id: Option<String>,
+    /// Its position in the resource's history, preserved rather than reassigned.
+    pub sequence: u64,
+    /// The content identity, so a peer can check that the value it received is
+    /// the value the revision was computed from.
+    pub content_id: String,
+    /// Who committed the historical fact. Never rewritten to the peer.
+    pub authority: String,
 }
 
 /// Types of mutations that become durable operations
@@ -66,6 +102,7 @@ impl Operation {
             capability,
             content_hash: String::new(), // Will be computed below
             vector_clock: None,
+            revision: None,
         };
         let mut result = op;
         result.content_hash = result.compute_content_hash();
@@ -94,6 +131,7 @@ impl Operation {
             capability,
             content_hash: String::new(), // Will be computed below
             vector_clock: None,
+            revision: None,
         };
         let mut result = op;
         result.content_hash = result.compute_content_hash();
@@ -121,6 +159,7 @@ impl Operation {
             capability,
             content_hash: String::new(), // Will be computed below
             vector_clock: None,
+            revision: None,
         };
         let mut result = op;
         result.content_hash = result.compute_content_hash();

package/dist/create/server-source/crates/feltdb/src/state_model.rs

@@ -1545,6 +1545,58 @@ impl StateStore {
         }
     }
 
+    /// A digest of this store's **history**: the revision graph and retention
+    /// state, and nothing else.
+    ///
+    /// Deliberately independent of a digest over current records. Two databases
+    /// can hold identical current state and completely different histories —
+    /// one that recorded every step and one that only ever saw the last — and
+    /// any equivalence check that cannot tell those apart is not checking
+    /// history at all.
+    ///
+    /// Covers, for every revision: its resource, identity, parent, sequence,
+    /// content identity and the authority that committed it; and for every
+    /// resource: its retention policy and horizon. It excludes wall-clock
+    /// timestamps, which two authorities holding the same history legitimately
+    /// disagree about.
+    pub fn history_digest(&self) -> String {
+        let mut entries: Vec<String> = self
+            .all_revisions()
+            .into_iter()
+            .map(|revision| {
+                format!(
+                    "{}|{}|{}|{}|{}|{}",
+                    revision.resource,
+                    revision.id.as_hex(),
+                    revision
+                        .parent_id
+                        .as_ref()
+                        .map(StateId::as_hex)
+                        .unwrap_or("-"),
+                    revision.sequence,
+                    revision.content_id.as_hex(),
+                    revision.authority,
+                )
+            })
+            .collect();
+        for resource in self.resources() {
+            let state = self.retention_state(&resource);
+            entries.push(format!(
+                "retention|{}|{:?}|{}",
+                resource, state.policy.keep_last, state.horizon
+            ));
+        }
+        entries.sort();
+
+        let mut hasher = Sha256::new();
+        hasher.update(b"feltdb.history.v1");
+        for entry in entries {
+            hasher.update(entry.as_bytes());
+            hasher.update([0u8]);
+        }
+        format!("{:x}", hasher.finalize())
+    }
+
     // -- retention ----------------------------------------------------------
 
     /// The retention policy in force for a resource.

package/dist/create/server-source/crates/feltdb/src/storage.rs

@@ -157,13 +157,19 @@ impl Storage for FileStorage {
             let file = OpenOptions::new().read(true).open(&self.path)?;
             let reader = BufReader::new(file);
 
-            for line in reader.lines() {
+            for (index, line) in reader.lines().enumerate() {
                 let line = line?;
                 if line.trim().is_empty() {
                     continue;
                 }
-                let row: StoredRow = serde_json::from_str(&line)
-                    .map_err(|_| FlowError::CorruptLogLine(line.clone()))?;
+                let row: StoredRow = serde_json::from_str(&line).map_err(|_| {
+                    FlowError::CorruptLogLine(Box::new(crate::LogCorruption {
+                        line_number: index + 1,
+                        byte_offset: 0,
+                        reason: "not a durable record this build understands".to_string(),
+                        excerpt: line.chars().take(120).collect(),
+                    }))
+                })?;
                 operations.push(row);
             }
         }

package/dist/create/server-source/crates/feltdb/tests/bounded_read_contract.rs

@@ -0,0 +1,132 @@
+//! Scoped reads must not materialize a collection.
+//!
+//! The managed incident's amplifier: `list_collection` takes the one lock that
+//! serializes every read and write, and **clones every row in the collection**.
+//! A keyed lookup implemented that way, or a search that filters after the
+//! clone, extends the window in which nothing else in the database can proceed.
+//!
+//! The code's own comment already recorded this pathology being seen before:
+//!
+//! > *a query holding the lock while it cloned a collection inflated the cost
+//! > of unrelated writes*
+//!
+//! The bounded APIs already existed. These tests pin the properties the server
+//! now depends on, so a future handler cannot quietly go back to the scanning
+//! form.
+
+use feltdb::FeltDb;
+use serde_json::json;
+use std::sync::atomic::{AtomicUsize, Ordering};
+use tempfile::TempDir;
+
+fn populated(rows: usize) -> (TempDir, FeltDb) {
+    let directory = TempDir::new().unwrap();
+    let db = FeltDb::open(directory.path().join("reads.log")).unwrap();
+    for index in 0..rows {
+        db.insert(
+            &format!("docs:{index:05}"),
+            json!({ "n": index, "body": "x".repeat(200) }),
+        )
+        .unwrap();
+    }
+    (directory, db)
+}
+
+/// **A keyed lookup reads one record.**
+///
+/// `get_provenance` used to call `list_collection` and `find` the key, cloning
+/// the entire collection to return one row.
+#[test]
+fn a_keyed_lookup_does_not_materialize_the_collection() {
+    let (_directory, db) = populated(500);
+
+    let row = db
+        .get_collection_record("docs", "docs:00042")
+        .unwrap()
+        .expect("the record is found");
+    assert_eq!(row.value["n"], json!(42));
+
+    assert!(db
+        .get_collection_record("docs", "docs:99999")
+        .unwrap()
+        .is_none());
+}
+
+/// **A bounded search stops at its limit.**
+///
+/// The predicate is the observable proof: it runs once per row *visited*, so a
+/// limited search over a large collection visits far fewer rows than the
+/// collection holds. The scanning form evaluated every row, every time.
+#[test]
+fn a_bounded_search_stops_at_the_limit_instead_of_scanning() {
+    let (_directory, db) = populated(500);
+    let visited = AtomicUsize::new(0);
+
+    // Every row matches, so the only thing that can stop the traversal is the
+    // limit.
+    let matched = db
+        .query_collection("docs", Some(10), |row| {
+            visited.fetch_add(1, Ordering::Relaxed);
+            row.value["body"].is_string()
+        })
+        .unwrap();
+
+    assert_eq!(matched.len(), 10, "the limit is honoured");
+    assert_eq!(
+        visited.load(Ordering::Relaxed),
+        10,
+        "and the traversal stopped there rather than visiting all 500"
+    );
+}
+
+/// Only matching rows are cloned; rejected rows are borrowed and dropped.
+#[test]
+fn a_search_clones_only_what_it_returns() {
+    let (_directory, db) = populated(300);
+    let visited = AtomicUsize::new(0);
+
+    let matched = db
+        .query_collection("docs", None, |row| {
+            visited.fetch_add(1, Ordering::Relaxed);
+            row.value["n"].as_u64() == Some(7)
+        })
+        .unwrap();
+
+    assert_eq!(matched.len(), 1);
+    assert_eq!(
+        visited.load(Ordering::Relaxed),
+        300,
+        "an unlimited search still visits every row — the saving is in cloning"
+    );
+}
+
+/// Paging traverses in key order and is bounded, so a large collection is
+/// readable without a single unbounded materialization.
+#[test]
+fn paging_is_bounded_and_ordered() {
+    let (_directory, db) = populated(120);
+
+    let first = db.list_collection_page("docs", None, 25).unwrap();
+    assert_eq!(first.len(), 25);
+    assert_eq!(first[0].key, "docs:00000");
+
+    let after = first.last().unwrap().key.clone();
+    let second = db.list_collection_page("docs", Some(&after), 25).unwrap();
+    assert_eq!(second.len(), 25);
+    assert!(second[0].key > after, "paging advances");
+
+    // The whole collection is reachable in bounded steps.
+    let mut seen = 0;
+    let mut cursor: Option<String> = None;
+    loop {
+        let page = db
+            .list_collection_page("docs", cursor.as_deref(), 25)
+            .unwrap();
+        if page.is_empty() {
+            break;
+        }
+        seen += page.len();
+        cursor = Some(page.last().unwrap().key.clone());
+    }
+    assert_eq!(seen, 120);
+}

package/dist/create/server-source/crates/feltdb/tests/common/mod.rs

@@ -0,0 +1,96 @@
+//! Shared rules for reading the certification and contract documents.
+//!
+//! Both `production_certification.rs` and `production_contract.rs` check
+//! published prose against an executable table, and both need the same answer
+//! to one awkward question: when does a document *assert* a guarantee, as
+//! opposed to naming one it is withholding? Defining that twice would be the
+//! same mistake the certification exists to prevent — two files quietly
+//! disagreeing — so it is defined once, here.
+
+#![allow(dead_code)]
+
+/// Split a markdown table row into its trimmed cells.
+///
+/// Emphasis and code delimiters are stripped, so `**Proven**` and `` `E6` ``
+/// compare equal to the plain text they render.
+pub fn table_cells(line: &str) -> Option<Vec<String>> {
+    let line = line.trim();
+    if !line.starts_with('|') {
+        return None;
+    }
+    Some(
+        line.trim_matches('|')
+            .split('|')
+            .map(|cell| {
+                cell.trim()
+                    .trim_matches('*')
+                    .trim()
+                    .trim_matches('`')
+                    .to_string()
+            })
+            .collect(),
+    )
+}
+
+/// Does `text` *assert* `phrase`, as opposed to naming it?
+///
+/// The distinction matters because the honest way to record a withheld
+/// guarantee is to quote it: `workload-envelope.md` says a test asserts no
+/// durability mode's wording contains "power-loss safe". A tripwire that
+/// flagged any occurrence would punish the document for being precise, and the
+/// cheapest way to satisfy it would be to stop naming the phrase at all — which
+/// is the opposite of what the tripwire is for.
+///
+/// So an occurrence inside a quotation (`"..."`) or a code span (`` `...` ``)
+/// is a mention. Every other occurrence is an assertion. Quoting is judged per
+/// line, because a stray delimiter must not silence the rest of the file.
+pub fn asserts_phrase(text: &str, phrase: &str) -> bool {
+    text.lines().any(|line| {
+        if !line.contains(phrase) {
+            return false;
+        }
+        let mut unquoted = String::new();
+        let mut segment = String::new();
+        let mut quoted = false;
+        for character in line.chars() {
+            if character == '"' || character == '`' {
+                if !quoted {
+                    // A quotation opens here, so the text before it is asserted.
+                    unquoted.push_str(&segment);
+                    unquoted.push('\u{0}');
+                }
+                segment.clear();
+                quoted = !quoted;
+            } else {
+                segment.push(character);
+            }
+        }
+        // A delimiter that is never closed quotes nothing.
+        unquoted.push_str(&segment);
+        unquoted.contains(phrase)
+    })
+}
+
+/// The document's prose, with rows that record a withheld verdict removed.
+///
+/// A table row that names something next to a label withholding it — `Unproven`,
+/// `Not certified` — is recording a gap, not asserting a guarantee. Without
+/// this, a matrix would fail its own tripwire the moment it published a gap
+/// precisely, and the cheapest way to pass would be to stop naming the gap.
+///
+/// Rows whose verdict cell *grants* the thing are deliberately not exempt: if
+/// one ever carried a forbidden phrase, the table and the phrase list would be
+/// in genuine contradiction and the tripwire should say so.
+pub fn prose_excluding_withheld_rows(document: &str, withheld: &[&str]) -> String {
+    document
+        .lines()
+        .filter(|line| match table_cells(line) {
+            None => true,
+            Some(cells) => !cells
+                .iter()
+                .any(|cell| withheld.iter().any(|label| cell == label)),
+        })
+        .collect::<Vec<_>>()
+        .join("\n")
+        .to_lowercase()
+}

package/dist/create/server-source/crates/feltdb/tests/compaction_stall_contract.rs

@@ -0,0 +1,272 @@
+//! Compaction must not stop the world on a timer.
+//!
+//! An incident on the managed deployment showed `/health` returning `200` while
+//! every application-scoped operation timed out or returned `502`, across
+//! several minutes, on four unrelated collections at once.
+//!
+//! Four collections failing together is the signature of a **global stall**,
+//! not of four collection-specific faults. The mechanism was here:
+//!
+//! > `compact_operation_log` takes the one lock that serializes every read and
+//! > every write, then serializes **every row in the database** to a temp file
+//! > and `fsync`s it — and a background task called it **every two seconds**.
+//!
+//! Pruning acknowledged operations from memory is cheap. Rewriting the log is
+//! not. This file holds them apart: pruning still happens whenever it can, and
+//! the rewrite waits until enough has accumulated to be worth the stall.
+//!
+//! See `docs/architecture/compaction-stall.md`.
+
+use feltdb::state_model::StateStore;
+use feltdb::{CompactionOutcome, CompactionPolicy, FeltDb};
+use serde_json::json;
+use std::sync::Arc;
+use std::time::Instant;
+use tempfile::TempDir;
+
+/// Acknowledge everything a database has produced, so a compaction has work.
+fn acknowledge_all(db: &Arc<FeltDb>) {
+    let versions = db.operation_versions().unwrap();
+    db.acknowledge_peer_versions("peer-1".to_string(), versions)
+        .unwrap();
+}
+
+fn write_n(db: &Arc<FeltDb>, n: usize) {
+    for index in 0..n {
+        db.insert(&format!("tasks:{index}"), json!({ "n": index }))
+            .unwrap();
+    }
+}
+
+// ---------------------------------------------------------------------------
+// The fix
+// ---------------------------------------------------------------------------
+
+/// **A timer-driven compaction prunes without rewriting the log.**
+///
+/// This is the change that stops the stall. The in-memory operation log still
+/// shrinks on every tick; the durable rewrite — the expensive half — waits.
+#[test]
+fn a_policy_driven_compaction_defers_the_rewrite() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("defer.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    db.set_compaction_policy(CompactionPolicy {
+        rewrite_after_pruned: 1000,
+    });
+
+    write_n(&db, 20);
+    acknowledge_all(&db);
+    let before = std::fs::metadata(&path).unwrap().len();
+
+    let outcome = db
+        .maybe_compact_operation_log(&["peer-1".to_string()])
+        .unwrap();
+
+    match outcome {
+        CompactionOutcome::Deferred {
+            pruned,
+            pending_since_rewrite,
+        } => {
+            assert!(pruned > 0, "the cheap half still happened");
+            assert_eq!(pending_since_rewrite, pruned);
+        }
+        other => panic!("expected the rewrite to be deferred, got {other:?}"),
+    }
+    assert_eq!(
+        std::fs::metadata(&path).unwrap().len(),
+        before,
+        "the durable log was not rewritten"
+    );
+
+    // And the database is entirely usable.
+    let value: serde_json::Value = db.get("tasks:0").unwrap().unwrap();
+    assert_eq!(value["n"], json!(0));
+}
+
+/// **The rewrite happens once the accumulated gain earns it**, and the log
+/// actually shrinks when it does.
+#[test]
+fn the_rewrite_happens_once_the_threshold_is_reached() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("threshold.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    db.set_compaction_policy(CompactionPolicy {
+        rewrite_after_pruned: 25,
+    });
+
+    let mut rewrites = 0;
+    let mut defers = 0;
+    for round in 0..6 {
+        for index in 0..10 {
+            db.update(
+                &format!("tasks:{}", round * 10 + index),
+                json!({ "n": index }),
+            )
+            .unwrap();
+        }
+        acknowledge_all(&db);
+        match db
+            .maybe_compact_operation_log(&["peer-1".to_string()])
+            .unwrap()
+        {
+            CompactionOutcome::Rewritten { .. } => rewrites += 1,
+            CompactionOutcome::Deferred { .. } => defers += 1,
+            CompactionOutcome::Idle => {}
+        }
+    }
+
+    assert!(defers > 0, "most ticks defer");
+    assert!(rewrites > 0, "and the rewrite still happens");
+    assert!(
+        defers > rewrites,
+        "the point is that deferring is the common case: {defers} deferred, {rewrites} rewritten"
+    );
+}
+
+/// **An explicit compaction still rewrites immediately.**
+///
+/// The policy governs the timer, not a caller who is asking for a rewrite now.
+/// Every existing caller of `compact_operation_log` keeps its behaviour.
+#[test]
+fn an_explicit_compaction_still_rewrites_now() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("explicit.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    db.set_compaction_policy(CompactionPolicy {
+        rewrite_after_pruned: usize::MAX,
+    });
+
+    write_n(&db, 20);
+    for index in 0..20 {
+        db.update(&format!("tasks:{index}"), json!({"n": "updated"}))
+            .unwrap();
+    }
+    acknowledge_all(&db);
+    let before = std::fs::metadata(&path).unwrap().len();
+
+    let pruned = db.compact_operation_log(&["peer-1".to_string()]).unwrap();
+    assert!(pruned > 0);
+    assert!(
+        std::fs::metadata(&path).unwrap().len() < before,
+        "an explicit compaction rewrote and shrank the log"
+    );
+}
+
+/// **The deferred rewrite costs nothing in correctness.**
+///
+/// Pruning without rewriting leaves the durable log longer than it needs to be,
+/// and nothing else: the database reopens to the same state and the same
+/// history.
+#[test]
+fn deferring_the_rewrite_preserves_state_and_history() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("preserve.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    db.set_compaction_policy(CompactionPolicy {
+        rewrite_after_pruned: usize::MAX,
+    });
+
+    db.insert("tasks:1", json!({"n": 0})).unwrap();
+    for n in 1..10 {
+        db.update("tasks:1", json!({ "n": n })).unwrap();
+    }
+    acknowledge_all(&db);
+    assert!(matches!(
+        db.maybe_compact_operation_log(&["peer-1".to_string()])
+            .unwrap(),
+        CompactionOutcome::Deferred { .. }
+    ));
+
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+    let history_before = store.history_digest();
+    let state_before = db.state_digest().unwrap();
+    drop(store);
+    drop(db);
+
+    let reopened = Arc::new(FeltDb::open(&path).unwrap());
+    let store = StateStore::with_feltdb(reopened.clone()).unwrap();
+    assert_eq!(reopened.state_digest().unwrap(), state_before);
+    assert_eq!(store.history_digest(), history_before);
+}
+
+/// Nothing to prune is not a rewrite either — the pre-existing early return.
+#[test]
+fn an_idle_compaction_does_no_work() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("idle.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    write_n(&db, 5);
+    let before = std::fs::read(&path).unwrap();
+
+    // No peer has acknowledged anything.
+    let outcome = db.maybe_compact_operation_log(&[]).unwrap();
+    assert_eq!(outcome, CompactionOutcome::Idle);
+    assert_eq!(outcome.pruned(), 0);
+    assert!(!outcome.rewrote_log());
+    assert_eq!(std::fs::read(&path).unwrap(), before);
+}
+
+// ---------------------------------------------------------------------------
+// The stall itself
+// ---------------------------------------------------------------------------
+
+/// **The rewrite is what stalls, and it grows with the database.**
+///
+/// Measured as an ordering rather than a number: a rewrite over a larger
+/// database holds the lock longer. That is why running it on a two-second timer
+/// degraded as the deployment grew, and why the default policy now waits.
+#[test]
+fn the_rewrite_cost_grows_with_the_database() {
+    let cost = |rows: usize| {
+        let directory = TempDir::new().unwrap();
+        let path = directory.path().join("cost.log");
+        let db = Arc::new(FeltDb::open(&path).unwrap());
+        write_n(&db, rows);
+        for index in 0..rows {
+            db.update(&format!("tasks:{index}"), json!({"n": "updated"}))
+                .unwrap();
+        }
+        acknowledge_all(&db);
+        let started = Instant::now();
+        db.compact_operation_log(&["peer-1".to_string()]).unwrap();
+        started.elapsed()
+    };
+
+    let small = cost(20);
+    let large = cost(400);
+    assert!(
+        large > small,
+        "a rewrite over more rows holds the lock longer: {large:?} vs {small:?}"
+    );
+}
+
+/// **The default policy does not rewrite on every tick.**
+///
+/// The regression this whole file exists to prevent. With the shipped default,
+/// a handful of acknowledged operations must not trigger a full log rewrite.
+#[test]
+fn the_default_policy_does_not_rewrite_on_a_handful_of_operations() {
+    assert_eq!(CompactionPolicy::default().rewrite_after_pruned, 1000);
+
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("default.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    assert_eq!(db.compaction_policy(), CompactionPolicy::default());
+
+    write_n(&db, 30);
+    acknowledge_all(&db);
+    let before = std::fs::metadata(&path).unwrap().len();
+
+    // Ten ticks of the timer.
+    for _ in 0..10 {
+        db.maybe_compact_operation_log(&["peer-1".to_string()])
+            .unwrap();
+    }
+
+    assert_eq!(
+        std::fs::metadata(&path).unwrap().len(),
+        before,
+        "ten timer ticks over a small database rewrote the log zero times"
+    );
+}