create-feltdb 0.8.6 → 0.8.7

package/dist/package-versions.js

@@ -1,4 +1,4 @@
 // One release train keeps generated applications installable. The repository
 // validation script checks these values against every workspace manifest.
-export const FELTDB_PACKAGE_VERSION = '0.8.6';
+export const FELTDB_PACKAGE_VERSION = '0.8.7';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

package/dist/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/server-source/crates/feltdb/tests/managed_incident_regression.rs

@@ -0,0 +1,191 @@
+//! The managed incident, composed.
+//!
+//! The four remediations each have their own contract: `compaction_stall_contract`
+//! covers the deferred rewrite, `bounded_read_contract` covers scoped reads, and
+//! the server crate's `admission_tests` cover the refusal. Every one of them
+//! exercises its fix in isolation, on an idle database.
+//!
+//! The incident was not any one of them in isolation. It was their composition:
+//! a populated collection, a timer firing compaction into the single lock that
+//! serializes every read and write, and scoped requests arriving throughout.
+//! A database that satisfies each contract separately can still fail the shape
+//! that actually happened, so the shape gets its own test.
+//!
+//! # What this file does not establish
+//!
+//! **It does not measure latency, and it does not prove the incident cannot
+//! recur.** No assertion here bounds how long a read waits, and every read
+//! still queues behind the same mutex. That is claim `M6`, and it is recorded
+//! in the certification matrix as `Unproven` precisely because a test like this
+//! one is not evidence for it. A timing assertion added here would either be
+//! flaky or be tuned until it passed, and both are worse than an honest gap.
+//!
+//! What it does establish is that under the composed load, the timer does not
+//! rewrite, scoped reads stay bounded, and no read observes a torn or missing
+//! database.
+
+use feltdb::{CompactionOutcome, CompactionPolicy, FeltDb};
+use serde_json::json;
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::sync::Arc;
+use tempfile::TempDir;
+
+const ROWS: usize = 800;
+
+/// A database shaped like the affected instance: one large collection, every
+/// operation acknowledged so a compaction always has work to do.
+fn incident_shaped() -> (TempDir, Arc<FeltDb>) {
+    let directory = TempDir::new().unwrap();
+    let db = Arc::new(FeltDb::open(directory.path().join("incident.log")).unwrap());
+    db.set_compaction_policy(CompactionPolicy::default());
+
+    for index in 0..ROWS {
+        db.insert(
+            &format!("docs:{index:05}"),
+            json!({ "n": index, "body": "x".repeat(200) }),
+        )
+        .unwrap();
+    }
+    let versions = db.operation_versions().unwrap();
+    db.acknowledge_peer_versions("peer-1".to_string(), versions)
+        .unwrap();
+
+    (directory, db)
+}
+
+/// **Scoped reads stay correct and bounded while the compaction timer runs.**
+///
+/// The compacting thread calls the same entry point the server's timer calls,
+/// continuously, for the whole run. The reading thread does what the handlers
+/// now do: a keyed lookup and a limited search, never a materializing scan.
+///
+/// Three properties are asserted, and each one is a way the incident could
+/// return:
+///
+/// 1. every read returns the right answer — a compaction running concurrently
+///    never exposes a partially pruned database;
+/// 2. every bounded search visits exactly its limit — the amplifier is still
+///    absent under load, not just on an idle database;
+/// 3. the timer performs no durable rewrite — the expensive half stays deferred
+///    when the policy says it should, and does not creep back in because
+///    something else about the workload changed.
+#[test]
+fn scoped_reads_stay_correct_and_bounded_while_compaction_runs() {
+    let (_directory, db) = incident_shaped();
+
+    let stop = Arc::new(AtomicBool::new(false));
+    let rewrites = Arc::new(AtomicUsize::new(0));
+    let ticks = Arc::new(AtomicUsize::new(0));
+
+    let compactor = {
+        let db = db.clone();
+        let stop = stop.clone();
+        let rewrites = rewrites.clone();
+        let ticks = ticks.clone();
+        std::thread::spawn(move || {
+            while !stop.load(Ordering::Relaxed) {
+                let outcome = db
+                    .maybe_compact_operation_log(&["peer-1".to_string()])
+                    .expect("a timer-driven compaction does not fail");
+                ticks.fetch_add(1, Ordering::Relaxed);
+                if matches!(outcome, CompactionOutcome::Rewritten { .. }) {
+                    rewrites.fetch_add(1, Ordering::Relaxed);
+                }
+            }
+        })
+    };
+
+    for round in 0..200 {
+        let key = format!("docs:{:05}", round % ROWS);
+        let row = db
+            .get_collection_record("docs", &key)
+            .unwrap()
+            .unwrap_or_else(|| panic!("{key} is readable while compaction runs"));
+        assert_eq!(row.value["n"], json!(round % ROWS));
+
+        let visited = AtomicUsize::new(0);
+        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 under load");
+        assert_eq!(
+            visited.load(Ordering::Relaxed),
+            10,
+            "and the search did not walk the collection"
+        );
+    }
+
+    stop.store(true, Ordering::Relaxed);
+    compactor.join().unwrap();
+
+    assert!(
+        ticks.load(Ordering::Relaxed) > 0,
+        "the compaction thread actually ran"
+    );
+    assert_eq!(
+        rewrites.load(Ordering::Relaxed),
+        0,
+        "the timer rewrote the durable log during the run; the deferred-rewrite \
+         fix does not hold under the composed workload"
+    );
+}
+
+/// **The composed run leaves the database intact.**
+///
+/// The incident's worst plausible outcome was not slowness, it was a database
+/// damaged by a rewrite interleaved with traffic. After the concurrent run the
+/// full collection is still present, still correct, and still there after a
+/// reopen — including once a rewrite is forced to happen.
+#[test]
+fn a_concurrent_compaction_leaves_the_database_intact() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("intact.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    db.set_compaction_policy(CompactionPolicy::default());
+
+    for index in 0..ROWS {
+        db.insert(&format!("docs:{index:05}"), json!({ "n": index }))
+            .unwrap();
+    }
+    let versions = db.operation_versions().unwrap();
+    db.acknowledge_peer_versions("peer-1".to_string(), versions)
+        .unwrap();
+
+    let stop = Arc::new(AtomicBool::new(false));
+    let compactor = {
+        let db = db.clone();
+        let stop = stop.clone();
+        std::thread::spawn(move || {
+            while !stop.load(Ordering::Relaxed) {
+                db.maybe_compact_operation_log(&["peer-1".to_string()])
+                    .unwrap();
+            }
+        })
+    };
+
+    for index in ROWS..ROWS + 200 {
+        db.insert(&format!("docs:{index:05}"), json!({ "n": index }))
+            .unwrap();
+    }
+
+    stop.store(true, Ordering::Relaxed);
+    compactor.join().unwrap();
+
+    // An explicit compaction still rewrites — the deferral is a policy, not a
+    // disablement — and the rewrite happens over a database that concurrent
+    // traffic has just been mutating.
+    db.compact_operation_log(&["peer-1".to_string()]).unwrap();
+    drop(db);
+
+    let reopened = FeltDb::open(&path).unwrap();
+    for index in 0..ROWS + 200 {
+        let value: serde_json::Value = reopened
+            .get(&format!("docs:{index:05}"))
+            .unwrap()
+            .unwrap_or_else(|| panic!("docs:{index:05} survived the composed run"));
+        assert_eq!(value["n"], json!(index));
+    }
+}