@feltdb/core 0.13.0 → 0.16.0

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

@@ -1,299 +0,0 @@
-//! Executable evidence for the Live State Branching audit
-//! (`docs/audits/BRANCHING-AUDIT.md`).
-//!
-//! These tests add no capability. Every one of them only *observes* what
-//! `feltdb::state_model` already does, so that the audit's branching claims
-//! rest on a run rather than on a reading. Where a test asserts an absence, the
-//! absence is the finding: it is what separates "FeltDB has branching" from
-//! "FeltDB has the durable lineage half of branching".
-
-use feltdb::state_model::StateStore;
-use feltdb::{
-    reconcile, ConflictClass, ConflictClassification, ReconciliationPlan, Relationship,
-    SemanticDiff, StateTopology,
-};
-use serde_json::json;
-use std::sync::Arc;
-use tempfile::TempDir;
-
-fn durable_store(directory: &TempDir, name: &str) -> StateStore {
-    let db = feltdb::FeltDb::open(directory.path().join(name)).expect("open");
-    StateStore::with_feltdb(Arc::new(db)).expect("store")
-}
-
-/// Q2 — **superseded.** Named branches no longer exist; a revision *is* the
-/// durable reference.
-///
-/// This test previously asserted that a branch is a durable named pointer at a
-/// `StateId` and survives a restart. Named branches were removed from
-/// `StateStore` because the record that held them, `state:current`, was the
-/// same record that held the global current pointer, and it carried both of the
-/// defects Q9 and Q11 recorded.
-///
-/// What survives is the load-bearing part: a revision is durable, and it is
-/// addressed by an identity derived from its own content — which is exactly
-/// what a branch name pointed at. The name was an alias for a value the caller
-/// already had.
-#[test]
-fn a_revision_is_its_own_durable_reference_across_restart() {
-    let directory = TempDir::new().unwrap();
-    let base = {
-        let store = durable_store(&directory, "state.log");
-        store
-            .create(
-                "docs:1",
-                json!({"balance": 100}).to_string(),
-                "authority".into(),
-            )
-            .expect("create")
-    };
-
-    let reopened = durable_store(&directory, "state.log");
-    let recovered = reopened
-        .get(&base.id)
-        .expect("a revision must survive a restart under its own identity");
-    assert_eq!(recovered.content, base.content);
-    assert!(
-        recovered.verify_integrity(),
-        "and still hash to the identity it was addressed by"
-    );
-}
-
-/// Q3/Q4 — mutation is **not** copy-on-write, and revisions share nothing.
-///
-/// Each revision carries the entire canonical state as its own `content`
-/// string. Two revisions that differ in one field still hold two full copies,
-/// so a "clone" costs the whole state. This is the storage half of branching
-/// FeltDB does not have.
-#[test]
-fn every_revision_holds_a_full_copy_of_state_rather_than_a_delta() {
-    let store = StateStore::new_volatile();
-    let filler = "x".repeat(4096);
-    let base = store
-        .create(
-            "docs:1",
-            json!({"blob": filler, "counter": 0}).to_string(),
-            "a".into(),
-        )
-        .expect("create");
-    let child = store
-        .commit(
-            json!({"blob": filler, "counter": 1}).to_string(),
-            &base,
-            "a".into(),
-        )
-        .expect("commit");
-
-    // One field changed; both revisions are still full-size.
-    assert!(base.content.len() > 4096);
-    assert!(child.content.len() > 4096);
-    assert_eq!(
-        base.content.len(),
-        child.content.len(),
-        "a one-field change produced two same-sized full copies, not a delta"
-    );
-    // And the parent link is the only thing they share: no structural sharing.
-    assert_eq!(child.parent_id.as_ref(), Some(&base.id));
-    assert_ne!(base.content, child.content);
-}
-
-/// Q5/Q6/Q7 — divergence, deterministic diff and conflict classification all
-/// work, but the topology is a structure the *caller* has to assemble.
-///
-/// `StateStore` exposes no topology of its own, so ancestry questions are only
-/// answerable by a caller that has already collected the revisions.
-#[test]
-fn divergence_diff_and_conflict_classification_work_over_a_caller_built_topology() {
-    let store = StateStore::new_volatile();
-    let base = store
-        .create(
-            "docs:1",
-            json!({"alice": 100, "bob": 50}).to_string(),
-            "a".into(),
-        )
-        .expect("create");
-    let left = store
-        .commit(
-            json!({"alice": 150, "bob": 50}).to_string(),
-            &base,
-            "a".into(),
-        )
-        .expect("left");
-    let right = store
-        .commit(
-            json!({"alice": 100, "bob": 150}).to_string(),
-            &base,
-            "a".into(),
-        )
-        .expect("right");
-
-    let mut topology = StateTopology::new();
-    for revision in [&base, &left, &right] {
-        topology.add_revision(revision.clone());
-    }
-    assert!(matches!(
-        topology.relationship(&left.id, &right.id),
-        Relationship::Diverged
-    ));
-    assert_eq!(
-        topology.common_ancestor(&left.id, &right.id),
-        Some(base.id.clone())
-    );
-
-    let base_value = serde_json::from_str(&base.content).unwrap();
-    let left_value = serde_json::from_str(&left.content).unwrap();
-    let diff = SemanticDiff::compute(&base_value, &left_value);
-    assert_eq!(diff.changes.len(), 1, "diff is deterministic and minimal");
-
-    let classification = ConflictClassification::classify(&base, &left, &right);
-    assert_eq!(classification.overall, ConflictClass::Independent);
-}
-
-/// Q8 — a plan can now be **applied**, but a branch still cannot be
-/// **reconciled**.
-///
-/// `apply_reconciliation_plan` turns an explicitly chosen plan into canonical
-/// content, and `reconcile` materializes that content as a `StateRevision`
-/// through the ordinary revision model. That is the half this evidence used to
-/// record as missing entirely.
-///
-/// What is still missing is the other half, and it is the half that would make
-/// this "branch reconciliation": nothing *chooses* a plan, and applying one
-/// moves no branch head. The caller supplies the parent choice and every
-/// override, and the branch points exactly where it did afterwards. FeltDB
-/// materializes the decision; it does not make it, and it does not record it as
-/// the branch's new position.
-#[test]
-fn a_plan_can_be_applied_but_applying_one_reconciles_no_branch() {
-    let store = StateStore::new_volatile();
-    let base = store
-        .create(
-            "docs:1",
-            json!({"alice": 100, "bob": 50}).to_string(),
-            "a".into(),
-        )
-        .expect("create");
-    let left = store
-        .commit(
-            json!({"alice": 150, "bob": 50}).to_string(),
-            &base,
-            "a".into(),
-        )
-        .expect("left");
-    let right = store
-        .commit(
-            json!({"alice": 100, "bob": 150}).to_string(),
-            &base,
-            "a".into(),
-        )
-        .expect("right");
-    let plan = ReconciliationPlan::new(left.id.clone(), right.id.clone(), base.id.clone(), true)
-        .with_override(vec![], json!({"alice": 150, "bob": 150}));
-    assert!(plan.validate(), "the plan validates structurally");
-
-    // The override is now read, and the plan is now applied.
-    let result =
-        reconcile(&base, &left, &right, &plan, "reconciler".into()).expect("the plan applies");
-    assert_eq!(
-        result.materialized_state.content,
-        r#"{"alice":150,"bob":150}"#
-    );
-    assert_eq!(
-        result.materialized_state.parent_id.as_ref(),
-        Some(&left.id),
-        "the chosen parent is the revision's parent"
-    );
-
-    // And nothing the plan started from changed. There is no branch head to
-    // advance — the store keeps none — and both source revisions are exactly
-    // as retrievable as before.
-    assert_eq!(store.get(&left.id).unwrap().content, left.content);
-    assert_eq!(store.get(&right.id).unwrap().content, right.content);
-
-    // And nothing chose this plan. Classification reports the conflict; the
-    // decision of what to do about it came from the caller.
-    let classification = ConflictClassification::classify(&base, &left, &right);
-    assert_eq!(classification.overall, ConflictClass::Independent);
-    assert!(
-        plan.unresolved_conflicts(&classification).is_empty(),
-        "the plan covers what the classifier reported, because the caller made it so"
-    );
-}
-
-/// Q9 — **the defect was removed rather than fixed.**
-///
-/// The original finding: `create_branch` recorded one `StateId` and never
-/// moved, while *any* commit moved the store's single global `current` pointer,
-/// so "which revision is this branch on now" was a question the store could not
-/// answer after the first commit. Both halves of that — the frozen branch
-/// pointer and the promiscuous global `current` — lived in one record.
-///
-/// Neither exists now. The store keeps no pointer, so there is none to be
-/// stale, and no commit can displace anything. Two siblings committed onto the
-/// same parent are simply two revisions, each addressed by its own identity,
-/// and the parent is untouched by either.
-///
-/// What this deliberately does *not* claim is that "which revision is current"
-/// has been answered. It has been **removed from this layer**, and no owner for
-/// it has been introduced.
-#[test]
-fn no_commit_can_displace_another_revision_because_there_is_no_pointer() {
-    let store = StateStore::new_volatile();
-    let base = store
-        .create("docs:1", json!({"v": 1}).to_string(), "a".into())
-        .expect("create");
-
-    let one = store
-        .commit(
-            json!({"v": 2, "side": "one"}).to_string(),
-            &base,
-            "a".into(),
-        )
-        .expect("commit one");
-    let two = store
-        .commit(
-            json!({"v": 2, "side": "two"}).to_string(),
-            &base,
-            "a".into(),
-        )
-        .expect("commit two");
-
-    // All three coexist, and neither sibling is privileged over the other.
-    for revision in [&base, &one, &two] {
-        assert_eq!(
-            store.get(&revision.id).expect("still present").content,
-            revision.content
-        );
-    }
-    assert_eq!(store.parent(&one.id).unwrap().id, base.id);
-    assert_eq!(store.parent(&two.id).unwrap().id, base.id);
-    assert_ne!(one.id, two.id, "the siblings are distinct revisions");
-}
-
-/// Q12 — nothing collects an abandoned revision, and nothing can.
-///
-/// Unchanged by the removal of branches, and worth re-recording because it is
-/// now the *only* remaining retention finding. Every revision ever committed
-/// stays in the store and on disk. There is no refcount, no unreachability
-/// sweep, and no delete.
-#[test]
-fn abandoned_revisions_are_retained_with_no_way_to_drop_them() {
-    let directory = TempDir::new().unwrap();
-    let abandoned = {
-        let store = durable_store(&directory, "state.log");
-        let base = store
-            .create("docs:1", json!({"v": 1}).to_string(), "a".into())
-            .expect("create");
-        // Nobody will ever ask for this revision again, and there is no way to
-        // tell the store that.
-        store
-            .commit(json!({"v": 2}).to_string(), &base, "a".into())
-            .expect("commit")
-    };
-
-    let reopened = durable_store(&directory, "state.log");
-    assert!(
-        reopened.exists(&abandoned.id),
-        "an abandoned revision is still durable after restart"
-    );
-}

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

@@ -1,96 +0,0 @@
-//! 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

@@ -1,272 +0,0 @@
-//! 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"
-    );
-}