@feltdb/core 0.8.3 → 0.8.5

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

@@ -0,0 +1,1039 @@
+//! The revision identity and ancestry contract.
+//!
+//! This file **implements nothing**. It makes the semantics of identity,
+//! ancestry and mutation *executable*, so that the choice between candidate
+//! models is made against a written contract rather than against whatever the
+//! hash function happens to do.
+//!
+//! It is the executable half of
+//! `docs/architecture/revision-identity-and-ancestry.md`, which states the
+//! questions and the candidate answers in prose.
+//!
+//! # How to read this file
+//!
+//! Every clause is a question the project must answer before automatic minting
+//! can be built. Each is evaluated against today's implementation by *running
+//! it*, and the answer is a [`Verdict`]:
+//!
+//! | verdict | meaning |
+//! | --- | --- |
+//! | `Honoured` | today's implementation satisfies the clause |
+//! | `HonouredVacuously` | it satisfies the clause only because the behaviour the clause constrains does not exist yet |
+//! | `Violated` | today's implementation contradicts the clause |
+//! | `Unanswerable` | the clause cannot be evaluated, because the data model has no field that could answer it |
+//!
+//! [`LEDGER`] records every verdict. Each clause test recomputes its own
+//! verdict from live behaviour and asserts it matches the record, and
+//! `the_ledger_is_exactly_this` recomputes all of them. **A semantic change
+//! that flips any verdict fails this suite.** That is the point: the contract
+//! cannot drift silently, and cannot be satisfied by accident.
+//!
+//! The `#[ignore]`d tests at the end are the contract in *required* form —
+//! written as they must read once a model is chosen. They fail today, on
+//! purpose. `cargo test -- --ignored` prints exactly what is not yet true.
+
+use feltdb::state_model::{
+    ParentLookup, RetentionPolicy, RevisionError, StateId, StateRevision, StateStore, StateTopology,
+};
+use feltdb::{FeltDb, JsonCasResult};
+use serde_json::json;
+use std::collections::BTreeMap;
+use std::sync::Arc;
+use tempfile::TempDir;
+
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+enum Verdict {
+    Honoured,
+    HonouredVacuously,
+    Violated,
+    Unanswerable,
+}
+
+/// The contract, and what today's implementation does about it.
+///
+/// Ordered by the question it belongs to, not by verdict.
+const LEDGER: &[(&str, Verdict)] = &[
+    // Q1 — what makes two revisions the same revision?
+    (
+        "I1 identical content yields identical content identity",
+        Verdict::Honoured,
+    ),
+    (
+        "I2 the same content can occur twice in one history",
+        Verdict::Honoured,
+    ),
+    (
+        "I3 revision identity distinguishes two occurrences of one state",
+        Verdict::Honoured,
+    ),
+    // Q2 — what does `base` mean?
+    (
+        "B1 base as the parent in the revision DAG",
+        Verdict::Honoured,
+    ),
+    (
+        "B2 base as the previous state under the same key",
+        Verdict::Honoured,
+    ),
+    ("B3 base as the previous observed state", Verdict::Honoured),
+    (
+        "B4 base as the previous durable revision",
+        Verdict::Honoured,
+    ),
+    // Q3 — which mutations create ancestry?
+    (
+        "M1 an explicit mint validates the parent it is given",
+        Verdict::Honoured,
+    ),
+    ("M2 a fenced write creates ancestry", Verdict::Honoured),
+    (
+        "M3 an unconditional write creates ancestry",
+        Verdict::Honoured,
+    ),
+    (
+        "N1 content equality never confers ancestry",
+        Verdict::Honoured,
+    ),
+    // Q5 — what must topology guarantee?
+    ("T1 the durable parent chain is acyclic", Verdict::Honoured),
+    ("T2 ancestors terminates", Verdict::Honoured),
+    ("T3 is_ancestor terminates", Verdict::Honoured),
+    ("T4 common_ancestor terminates", Verdict::Honoured),
+    ("T5 every parent reference resolves", Verdict::Honoured),
+    (
+        "T6 a revision never silently changes its parent",
+        Verdict::Honoured,
+    ),
+    // Q6 — what does compaction promise?
+    (
+        "C1 compaction deletes acknowledged operation history",
+        Verdict::Honoured,
+    ),
+    ("C2 compaction preserves current state", Verdict::Honoured),
+    (
+        "C3 revision retention is promised rather than incidental",
+        Verdict::Honoured,
+    ),
+    (
+        "C4 the three promises can be requested separately",
+        Verdict::Honoured,
+    ),
+];
+
+fn recorded(clause: &str) -> Verdict {
+    LEDGER
+        .iter()
+        .find(|(name, _)| *name == clause)
+        .unwrap_or_else(|| panic!("{clause} is not in the ledger"))
+        .1
+}
+
+/// Evaluate a clause against today's implementation, by running it.
+fn evaluate(clause: &str) -> Verdict {
+    match clause {
+        "I1 identical content yields identical content identity" => i1(),
+        "I2 the same content can occur twice in one history" => i2(),
+        "I3 revision identity distinguishes two occurrences of one state" => i3(),
+        "B1 base as the parent in the revision DAG" => b1(),
+        "B2 base as the previous state under the same key" => b2(),
+        "B3 base as the previous observed state" => b3(),
+        "B4 base as the previous durable revision" => b4(),
+        "M1 an explicit mint validates the parent it is given" => m1(),
+        "M2 a fenced write creates ancestry" => m2(),
+        "M3 an unconditional write creates ancestry" => m3(),
+        "N1 content equality never confers ancestry" => n1(),
+        "T1 the durable parent chain is acyclic" => t1(),
+        "T2 ancestors terminates" => t2(),
+        "T3 is_ancestor terminates" => t3(),
+        "T4 common_ancestor terminates" => t4(),
+        "T5 every parent reference resolves" => t5(),
+        "T6 a revision never silently changes its parent" => t6(),
+        "C1 compaction deletes acknowledged operation history" => c1(),
+        "C2 compaction preserves current state" => c2(),
+        "C3 revision retention is promised rather than incidental" => c3(),
+        "C4 the three promises can be requested separately" => c4(),
+        other => panic!("{other} has no evaluator"),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+fn durable_store(name: &str) -> (TempDir, Arc<FeltDb>, StateStore) {
+    let directory = TempDir::new().unwrap();
+    let db = Arc::new(FeltDb::open(directory.path().join(name)).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+    (directory, db, store)
+}
+
+/// A revision built by hand, to name a parent the store has never seen.
+fn hand_built(content: &str, parent: Option<StateId>) -> StateRevision {
+    StateRevision {
+        id: StateId::compute(content),
+        resource: R.into(),
+        content: content.to_string(),
+        content_id: StateId::compute(content),
+        parent_id: parent,
+        sequence: 0,
+        authority: "contract".into(),
+        timestamp_ms: 0,
+        metadata: BTreeMap::new(),
+    }
+}
+
+/// The resource every clause exercises, now that a revision belongs to one.
+const R: &str = "tasks:1";
+
+const A: &str = r#"{"title":"A"}"#;
+const B: &str = r#"{"title":"B"}"#;
+
+/// Commit the sequence A → B → A and return the store. This is the sequence
+/// the whole contract turns on: the most ordinary edit there is.
+fn a_then_b_then_a(name: &str) -> (TempDir, Arc<FeltDb>, StateStore, StateId, StateId) {
+    let (directory, db, store) = durable_store(name);
+    let first = store.create(R, A.into(), "contract".into()).unwrap();
+    let second = store.commit(B.into(), &first, "contract".into()).unwrap();
+    store.commit(A.into(), &second, "contract".into()).unwrap();
+    let (a, b) = (first.id.clone(), second.id.clone());
+    (directory, db, store, a, b)
+}
+
+/// Whether a cycle is reachable by following parent links from `start`.
+///
+/// Deliberately bounded. The traversals this stands in for are not.
+fn cycle_reachable_from(store: &StateStore, start: &StateId) -> bool {
+    let mut seen: Vec<StateId> = Vec::new();
+    let mut current = start.clone();
+    for _ in 0..64 {
+        if seen.contains(&current) {
+            return true;
+        }
+        seen.push(current.clone());
+        match store.get(&current).and_then(|revision| revision.parent_id) {
+            Some(parent) => current = parent,
+            None => return false,
+        }
+    }
+    true
+}
+
+// ---------------------------------------------------------------------------
+// Q1 — What makes two revisions the same revision?
+// ---------------------------------------------------------------------------
+
+/// **Identical content yields identical identity.**
+///
+/// `StateId::compute` is SHA-256 over the canonical content and nothing else.
+/// This is a property worth keeping — it is what makes a revision verifiable
+/// against its own id, and what deduplicates repeated state.
+fn i1() -> Verdict {
+    if StateId::compute(A) == StateId::compute(A) && StateId::compute(A) != StateId::compute(B) {
+        Verdict::Honoured
+    } else {
+        Verdict::Violated
+    }
+}
+
+/// **The same content can occur at two points in one history.**
+///
+/// Not an edge case. A field set, changed, and changed back is the second most
+/// common edit there is.
+fn i2() -> Verdict {
+    let (_directory, _db, store, a, b) = a_then_b_then_a("i2.log");
+    // Both A-states are in one history, and B lies between them.
+    if store.exists(&a) && store.exists(&b) {
+        Verdict::Honoured
+    } else {
+        Verdict::Violated
+    }
+}
+
+/// **Content alone is a complete revision identity.**
+///
+/// This is the clause the project must reject or accept explicitly, because I1
+/// and I2 together make it false: if identity is content, and content recurs,
+/// then two distinct points in history are one revision. The third commit does
+/// not create a revision — it overwrites the first.
+fn i3() -> Verdict {
+    let (_directory, _db, store, a, b) = a_then_b_then_a("i3.log");
+    let history = store.history_of(R);
+    let distinct = history.len() == 3
+        && history[0].id != history[2].id
+        && history[0].content_id == history[2].content_id;
+    let first_intact = store.get(&a).unwrap().parent_id.is_none();
+    let third_descends = history[2].parent_id.as_ref() == Some(&b);
+    if distinct && first_intact && third_descends {
+        Verdict::Honoured
+    } else {
+        Verdict::Violated
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Q2 — What does `base` mean?
+// ---------------------------------------------------------------------------
+
+/// **`base` as the parent in the revision DAG.**
+///
+/// Sound as a definition, and unusable while T1, T5 and T6 hold: the parent
+/// link can point at a revision that was never stored, can be rewritten by a
+/// later commit, and can close a cycle.
+fn b1() -> Verdict {
+    let (_directory, _db, store, a, _b) = a_then_b_then_a("b1.log");
+    if cycle_reachable_from(&store, &a) {
+        Verdict::Violated
+    } else {
+        Verdict::Honoured
+    }
+}
+
+/// **`base` as the previous state under the same key.**
+///
+/// Cannot be evaluated at all. A `StateRevision` has six fields — `authority`,
+/// `content`, `id`, `metadata`, `parent_id`, `timestamp_ms` — and none of them
+/// says which resource the revision is a state *of*. The revision store is
+/// keyed by content hash alone, so "the previous state of `tasks:1`" is not a
+/// question it can be asked.
+///
+/// `metadata` could carry a key. Nothing puts one there, and if something did,
+/// the key would not participate in the identity.
+fn b2() -> Verdict {
+    let revision = hand_built(A, None);
+    let encoded = serde_json::to_value(&revision).unwrap();
+    let fields: Vec<&String> = encoded.as_object().unwrap().keys().collect();
+    let names_a_resource = fields
+        .iter()
+        .any(|field| matches!(field.as_str(), "key" | "resource" | "capability"));
+    if names_a_resource {
+        Verdict::Honoured
+    } else {
+        Verdict::Unanswerable
+    }
+}
+
+/// **`base` as the previous observed state.**
+///
+/// Available, and only at the fenced boundary, which reads the whole prior
+/// document before deciding. Established by the three-way input boundary audit;
+/// re-checked here because the contract depends on it.
+fn b3() -> Verdict {
+    let directory = TempDir::new().unwrap();
+    let db = FeltDb::open(directory.path().join("b3.log")).unwrap();
+    db.insert(
+        "tasks:1",
+        json!({"title": "A", "__version": 1, "authority": {"epoch": 7}}),
+    )
+    .unwrap();
+    let refused = db
+        .compare_and_set_json("tasks:1", 1, Some(6), None, false, json!({"title": "B"}))
+        .unwrap();
+    if matches!(refused, JsonCasResult::AuthorityConflict { .. }) {
+        Verdict::Honoured
+    } else {
+        Verdict::Violated
+    }
+}
+
+/// **`base` as the previous durable revision.**
+///
+/// Vacuous. No write path mints a revision, so no revision is ever the previous
+/// one. The definition is not wrong; there is simply nothing for it to denote.
+fn b4() -> Verdict {
+    let directory = TempDir::new().unwrap();
+    let db = Arc::new(FeltDb::open(directory.path().join("b4.log")).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+    db.insert("tasks:1", json!({"title": "A"})).unwrap();
+    db.update("tasks:1", json!({"title": "B"})).unwrap();
+
+    // The head is the state just written; its parent is the state before it,
+    // which is exactly `base`.
+    let head = store
+        .head_of("tasks:1")
+        .expect("the write minted a revision");
+    let Some(ParentLookup::Revision(previous)) = store.parent_of(&head.id) else {
+        return Verdict::Violated;
+    };
+    if previous.content == r#"{"title":"A"}"# {
+        Verdict::Honoured
+    } else {
+        Verdict::Violated
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Q3 — Which mutations create ancestry?
+// ---------------------------------------------------------------------------
+
+/// **An explicit mint validates the parent it is given.**
+///
+/// It does not. `commit` takes a `&StateRevision` the caller holds, and nothing
+/// requires that revision to be in the store. A child of a revision that was
+/// never stored is accepted, and its `parent_id` points at nothing.
+fn m1() -> Verdict {
+    let (_directory, _db, store) = durable_store("m1.log");
+    let never_stored = hand_built(r#"{"never":"stored"}"#, None);
+    match store.commit(A.into(), &never_stored, "contract".into()) {
+        Err(RevisionError::UnknownParent(id)) if id == never_stored.id => Verdict::Honoured,
+        _ => Verdict::Violated,
+    }
+}
+
+/// **A fenced write creates ancestry.**
+///
+/// Vacuous: it creates none, because nothing mints. Recorded separately from
+/// M3 because the two paths differ in what they *could* do — the fence already
+/// holds the prior document, and the unconditional paths do not.
+fn m2() -> Verdict {
+    let directory = TempDir::new().unwrap();
+    let db = Arc::new(FeltDb::open(directory.path().join("m2.log")).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+    db.insert("tasks:1", json!({"title": "A", "__version": 1}))
+        .unwrap();
+    db.compare_and_set_json("tasks:1", 1, None, None, false, json!({"title": "B"}))
+        .unwrap();
+    let history = store.history_of("tasks:1");
+    if history.len() == 2 && history[1].parent_id.as_ref() == Some(&history[0].id) {
+        Verdict::Honoured
+    } else {
+        Verdict::Violated
+    }
+}
+
+/// **An unconditional write creates ancestry.**
+///
+/// Vacuous, and doubly so: nothing mints, and `insert_internal` and
+/// `update_internal` never read the prior row, so there would be no parent to
+/// record even if something did.
+fn m3() -> Verdict {
+    let directory = TempDir::new().unwrap();
+    let db = Arc::new(FeltDb::open(directory.path().join("m3.log")).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+    db.insert("tasks:1", json!({"title": "A"})).unwrap();
+    db.update("tasks:1", json!({"title": "B"})).unwrap();
+    let history = store.history_of("tasks:1");
+    if history.len() == 2 && history[1].parent_id.as_ref() == Some(&history[0].id) {
+        Verdict::Honoured
+    } else {
+        Verdict::Violated
+    }
+}
+
+/// **Content equality never confers ancestry.** *(negative control)*
+///
+/// The distinction this protects is the one the whole contract turns on: a
+/// write whose result happens to equal an existing revision's content must not
+/// thereby inherit that revision's history. Arriving at the same value is not
+/// the same as descending from it.
+///
+/// Today this holds vacuously — no write mints anything, so no write can
+/// inherit anything. It is recorded now so that whatever model is chosen has to
+/// keep holding it, and the required-form version at the end of this file is
+/// the one that will matter.
+fn n1() -> Verdict {
+    let directory = TempDir::new().unwrap();
+    let db = Arc::new(FeltDb::open(directory.path().join("n1.log")).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+
+    // An unrelated resource whose history contains exactly the content the
+    // write is about to produce.
+    let unrelated_root = store
+        .create("other:1", r#"{"unrelated":true}"#.into(), "other".into())
+        .unwrap();
+    let planted = store
+        .commit(r#"{"title":"B"}"#.into(), &unrelated_root, "other".into())
+        .unwrap();
+
+    db.insert("tasks:1", json!({"title": "A"})).unwrap();
+    db.update("tasks:1", json!({"title": "B"})).unwrap();
+
+    let history = store.history_of("tasks:1");
+    if history.len() != 2 {
+        return Verdict::Violated;
+    }
+    let minted = &history[1];
+
+    // Same state, different revision, and the ancestry followed the resource
+    // rather than the content.
+    let reached_the_same_value = minted.content_id == planted.content_id;
+    let distinct_revision = minted.id != planted.id;
+    let descends_from_this_resource = minted.parent_id.as_ref() == Some(&history[0].id);
+    let planted_untouched = store.get(&planted.id).unwrap().parent_id == Some(unrelated_root.id);
+
+    if reached_the_same_value
+        && distinct_revision
+        && descends_from_this_resource
+        && planted_untouched
+    {
+        Verdict::Honoured
+    } else {
+        Verdict::Violated
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Q5 — What must topology guarantee?
+// ---------------------------------------------------------------------------
+
+/// **The durable parent chain is acyclic.**
+fn t1() -> Verdict {
+    let (_directory, _db, store, a, _b) = a_then_b_then_a("t1.log");
+    if cycle_reachable_from(&store, &a) {
+        Verdict::Violated
+    } else {
+        Verdict::Honoured
+    }
+}
+
+/// Whether the topology walkers can terminate on the graph A → B → A builds.
+///
+/// `ancestors`, `is_ancestor` and `common_ancestor`
+/// (`crates/feltdb/src/state_model.rs:186-230`) follow parent links in a
+/// `while let` loop with **no visited set**. A cycle reachable from their start
+/// node is therefore sufficient for non-termination.
+///
+/// This is established by demonstrating the cycle and reading the loop, not by
+/// calling the traversal. Calling it would not return.
+fn walkers_can_terminate() -> Verdict {
+    // Build the graph that used to hang: two revisions sharing an identity
+    // because they share content, closing a loop through their parents. The
+    // resource-scoped model no longer produces this, so it is assembled by hand
+    // — which is the point. The walkers must terminate on a graph they did not
+    // create, read from an older log or built by a careless caller.
+    let mut topology = StateTopology::new();
+    let first = hand_built(A, None);
+    let second = hand_built(B, Some(first.id.clone()));
+    let third = hand_built(A, Some(second.id.clone()));
+    assert_eq!(first.id, third.id, "the hand-built graph is cyclic");
+    topology.add_revision(first.clone());
+    topology.add_revision(second.clone());
+    topology.add_revision(third);
+
+    // These calls did not return before the visited sets were added. Reaching
+    // the line below is the whole claim; the answers themselves are whatever a
+    // cyclic graph deserves, and are not what this clause is about.
+    let ancestors = topology.ancestors(&first.id);
+    let is_ancestor = topology.is_ancestor(&hand_built(r#"{"unrelated":1}"#, None).id, &first.id);
+    let _common = topology.common_ancestor(&first.id, &second.id);
+
+    if ancestors.len() <= 4 && !is_ancestor {
+        Verdict::Honoured
+    } else {
+        Verdict::Violated
+    }
+}
+
+/// **`ancestors` terminates.**
+fn t2() -> Verdict {
+    walkers_can_terminate()
+}
+
+/// **`is_ancestor` terminates.**
+fn t3() -> Verdict {
+    walkers_can_terminate()
+}
+
+/// **`common_ancestor` terminates.**
+fn t4() -> Verdict {
+    walkers_can_terminate()
+}
+
+/// **Every parent reference resolves.**
+///
+/// Same mechanism as M1, stated as a graph invariant rather than as a property
+/// of the mint: a stored revision can name a parent that is not stored.
+fn t5() -> Verdict {
+    let (_directory, _db, store) = durable_store("t5.log");
+    let never_stored = hand_built(r#"{"never":"stored"}"#, None);
+    if store
+        .commit(A.into(), &never_stored, "contract".into())
+        .is_ok()
+    {
+        return Verdict::Violated;
+    }
+
+    // And every parent a real history names does resolve.
+    let first = store.create(R, A.into(), "contract".into()).unwrap();
+    let second = store.commit(B.into(), &first, "contract".into()).unwrap();
+    match store.parent_of(&second.id) {
+        Some(ParentLookup::Revision(parent)) if parent.id == first.id => Verdict::Honoured,
+        _ => Verdict::Violated,
+    }
+}
+
+/// **A revision never silently changes its parent.**
+///
+/// It changes in both directions, and neither is reported.
+///
+/// *Gains one it never had:* A → B → A gives the first revision B as a parent.
+///
+/// *Loses the one it had:* committing B as a child of A, then `create`-ing the
+/// same content as a parentless initial revision, sets B's parent back to
+/// `None` — erasing the fact that B ever descended from anything.
+fn t6() -> Verdict {
+    let (_directory, _db, store) = durable_store("t6.log");
+    let first = store.create(R, A.into(), "contract".into()).unwrap();
+    let second = store.commit(B.into(), &first, "contract".into()).unwrap();
+    assert_eq!(
+        store.get(&second.id).unwrap().parent_id,
+        Some(first.id.clone())
+    );
+
+    // Beginning the resource again is refused, so the parent cannot be erased
+    // that way.
+    let begun_again = store.create(R, B.into(), "contract".into());
+    let refused = matches!(begun_again, Err(RevisionError::ResourceAlreadyBegun { .. }));
+
+    // And a further commit of the same content is a new revision, not a
+    // rewrite of the existing one.
+    let third = store.commit(B.into(), &second, "contract".into()).unwrap();
+    let untouched = store.get(&second.id).unwrap().parent_id == Some(first.id);
+
+    if refused && untouched && third.id != second.id {
+        Verdict::Honoured
+    } else {
+        Verdict::Violated
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Q6 — What does compaction promise?
+// ---------------------------------------------------------------------------
+
+/// Compact a store holding both plain rows and revisions, and report what
+/// happened to each of the three things compaction touches.
+struct CompactionOutcome {
+    operations_pruned: bool,
+    current_state_survived: bool,
+    revisions_survived: bool,
+    revisions_rewritten: usize,
+}
+
+fn compact_and_observe(name: &str) -> CompactionOutcome {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join(name);
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+
+    db.insert("tasks:1", json!({"title": "A"})).unwrap();
+    db.update("tasks:1", json!({"title": "B"})).unwrap();
+    let mut ids = Vec::new();
+    let mut revision = store
+        .create("history:1", r#"{"n":0}"#.into(), "contract".into())
+        .unwrap();
+    ids.push(revision.id.clone());
+    for n in 1..5 {
+        revision = store
+            .commit(format!(r#"{{"n":{n}}}"#), &revision, "contract".into())
+            .unwrap();
+        ids.push(revision.id.clone());
+    }
+
+    let versions = db.operation_versions().unwrap();
+    db.acknowledge_peer_versions("peer-1".to_string(), versions)
+        .unwrap();
+    let removed = db.compact_operation_log(&["peer-1".to_string()]).unwrap();
+    let log = std::fs::read_to_string(&path).unwrap();
+
+    let current: Option<serde_json::Value> = db.get("tasks:1").unwrap();
+    CompactionOutcome {
+        operations_pruned: removed > 0,
+        current_state_survived: current.map(|v| v["title"] == json!("B")).unwrap_or(false),
+        revisions_survived: ids.iter().all(|id| store.exists(id)),
+        revisions_rewritten: log
+            .lines()
+            .filter(|line| line.contains("state:revision:"))
+            .count(),
+    }
+}
+
+/// **Compaction deletes acknowledged operation history.** Its stated purpose.
+fn c1() -> Verdict {
+    if compact_and_observe("c1.log").operations_pruned {
+        Verdict::Honoured
+    } else {
+        Verdict::Violated
+    }
+}
+
+/// **Compaction preserves current state.** Also its stated purpose.
+fn c2() -> Verdict {
+    if compact_and_observe("c2.log").current_state_survived {
+        Verdict::Honoured
+    } else {
+        Verdict::Violated
+    }
+}
+
+/// **Revision retention is promised rather than incidental.**
+///
+/// It is now a policy a resource carries, applied at the moment history is
+/// created. Revisions survive because the policy retains them, not because the
+/// rule that protects current state happens to sweep them up.
+fn c3() -> Verdict {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("c3.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+
+    store
+        .set_retention_policy("tasks:1", RetentionPolicy::keep_last(2))
+        .unwrap();
+    db.insert("tasks:1", json!({"n": 0})).unwrap();
+    for n in 1..6 {
+        db.update("tasks:1", json!({ "n": n })).unwrap();
+    }
+
+    let history = store.history_of("tasks:1");
+    let bounded = history.len() == 2;
+    let current_survived = history
+        .last()
+        .map(|revision| revision.content.contains("\"n\":5"))
+        .unwrap_or(false);
+    let horizon_recorded = store.retention_horizon("tasks:1") > 0;
+
+    if bounded && current_survived && horizon_recorded {
+        Verdict::Honoured
+    } else {
+        Verdict::Violated
+    }
+}
+
+/// **The three promises can be requested separately.**
+///
+/// Compaction bounds the operation log and preserves current state. Retention
+/// bounds revision history. Neither does the other's job, and each can be asked
+/// for on its own.
+fn c4() -> Verdict {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("c4.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+
+    db.insert("tasks:1", json!({"n": 0})).unwrap();
+    for n in 1..6 {
+        db.update("tasks:1", json!({ "n": n })).unwrap();
+    }
+
+    // Compaction alone: operations pruned, revisions untouched.
+    let before = store.history_of("tasks:1").len();
+    let versions = db.operation_versions().unwrap();
+    db.acknowledge_peer_versions("peer-1".to_string(), versions)
+        .unwrap();
+    let pruned = db.compact_operation_log(&["peer-1".to_string()]).unwrap();
+    let compaction_left_history_alone = store.history_of("tasks:1").len() == before;
+
+    // Retention alone: revisions expired, current state untouched.
+    let expired = store
+        .set_retention_policy("tasks:1", RetentionPolicy::keep_last(2))
+        .unwrap();
+    let current: Option<serde_json::Value> = db.get("tasks:1").unwrap();
+    let retention_left_state_alone = current.map(|v| v["n"] == json!(5)).unwrap_or(false);
+
+    if pruned > 0 && compaction_left_history_alone && expired > 0 && retention_left_state_alone {
+        Verdict::Honoured
+    } else {
+        Verdict::Violated
+    }
+}
+
+// ---------------------------------------------------------------------------
+// The clauses, as tests
+// ---------------------------------------------------------------------------
+
+macro_rules! clause {
+    ($test:ident, $clause:expr) => {
+        #[test]
+        fn $test() {
+            assert_eq!(
+                evaluate($clause),
+                recorded($clause),
+                "the behaviour of `{}` no longer matches the recorded contract verdict; \
+                 update docs/architecture/revision-identity-and-ancestry.md deliberately",
+                $clause
+            );
+        }
+    };
+}
+
+clause!(
+    i1_identical_content_yields_identical_content_identity,
+    "I1 identical content yields identical content identity"
+);
+clause!(
+    i2_the_same_content_can_occur_twice,
+    "I2 the same content can occur twice in one history"
+);
+clause!(
+    i3_revision_identity_distinguishes_occurrences,
+    "I3 revision identity distinguishes two occurrences of one state"
+);
+clause!(
+    b1_base_as_the_parent_in_the_dag,
+    "B1 base as the parent in the revision DAG"
+);
+clause!(
+    b2_base_as_the_previous_state_for_a_key,
+    "B2 base as the previous state under the same key"
+);
+clause!(
+    b3_base_as_the_previous_observed_state,
+    "B3 base as the previous observed state"
+);
+clause!(
+    b4_base_as_the_previous_durable_revision,
+    "B4 base as the previous durable revision"
+);
+clause!(
+    m1_explicit_mint_validates_its_parent,
+    "M1 an explicit mint validates the parent it is given"
+);
+clause!(
+    m2_a_fenced_write_creates_ancestry,
+    "M2 a fenced write creates ancestry"
+);
+clause!(
+    m3_an_unconditional_write_creates_ancestry,
+    "M3 an unconditional write creates ancestry"
+);
+clause!(
+    n1_content_equality_confers_no_ancestry,
+    "N1 content equality never confers ancestry"
+);
+clause!(
+    t1_the_parent_chain_is_acyclic,
+    "T1 the durable parent chain is acyclic"
+);
+clause!(t2_ancestors_terminates, "T2 ancestors terminates");
+clause!(t3_is_ancestor_terminates, "T3 is_ancestor terminates");
+clause!(
+    t4_common_ancestor_terminates,
+    "T4 common_ancestor terminates"
+);
+clause!(
+    t5_every_parent_reference_resolves,
+    "T5 every parent reference resolves"
+);
+clause!(
+    t6_a_revision_never_silently_changes_its_parent,
+    "T6 a revision never silently changes its parent"
+);
+clause!(
+    c1_compaction_deletes_operation_history,
+    "C1 compaction deletes acknowledged operation history"
+);
+clause!(
+    c2_compaction_preserves_current_state,
+    "C2 compaction preserves current state"
+);
+clause!(
+    c3_revision_retention_is_promised,
+    "C3 revision retention is promised rather than incidental"
+);
+clause!(
+    c4_the_promises_are_separable,
+    "C4 the three promises can be requested separately"
+);
+
+/// **The tripwire.**
+///
+/// Every clause, recomputed from live behaviour and checked against the record.
+/// A change to identity, ancestry or compaction semantics that flips any
+/// verdict fails here — including a change that *fixes* one. That is intended:
+/// the contract is a decision, and it should not be possible to satisfy it by
+/// accident and leave the document saying otherwise.
+#[test]
+fn the_ledger_is_exactly_this() {
+    let mut drifted = Vec::new();
+    for (clause, expected) in LEDGER {
+        let actual = evaluate(clause);
+        if actual != *expected {
+            drifted.push(format!(
+                "  {clause}: recorded {expected:?}, observed {actual:?}"
+            ));
+        }
+    }
+    assert!(
+        drifted.is_empty(),
+        "the contract ledger has drifted from the implementation:\n{}\n\n\
+         Update docs/architecture/revision-identity-and-ancestry.md and this ledger together.",
+        drifted.join("\n")
+    );
+}
+
+/// Every clause has an evaluator, and no evaluator is orphaned.
+#[test]
+fn the_ledger_is_complete() {
+    assert_eq!(
+        LEDGER.len(),
+        21,
+        "clauses were added or removed without updating the count"
+    );
+    for (clause, _) in LEDGER {
+        let _ = evaluate(clause);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// The contract in required form
+// ---------------------------------------------------------------------------
+//
+// These were written before a model was chosen, and were `#[ignore]`d because
+// they could not pass. They pass now, under the resource-scoped model.
+//
+// **Two of them were rewritten to get here, and it matters which.** The
+// centrepiece is unchanged apart from naming the resource a revision now
+// belongs to. But the fenced and unconditional path tests, and the negative
+// control, looked a minted revision up by `StateId::compute(content)` — they
+// assumed content *was* revision identity, which is the assumption the adopted
+// model rejects. Their assertions are preserved; the lookups are not, because
+// under model C there is no revision at a content hash. That is a deliberate
+// contract update, not a test bent to fit the code.
+
+/// **The centrepiece.** A → B → A, with the expected graph stated rather than
+/// left to the hash function.
+#[test]
+fn a_then_b_then_a_produces_three_revisions() {
+    let (_directory, _db, store) = durable_store("required-mint.log");
+
+    let first = store.create(R, A.into(), "contract".into()).unwrap();
+    let second = store.commit(B.into(), &first, "contract".into()).unwrap();
+    let third = store.commit(A.into(), &second, "contract".into()).unwrap();
+
+    assert_ne!(first.id, third.id, "arriving at A twice is two revisions");
+    assert_eq!(
+        first.content_id, third.content_id,
+        "and it is the same state both times"
+    );
+    assert_eq!(store.get(&first.id).unwrap().parent_id, None);
+    assert_eq!(
+        store.get(&second.id).unwrap().parent_id,
+        Some(first.id.clone())
+    );
+    assert_eq!(
+        store.get(&third.id).unwrap().parent_id,
+        Some(second.id.clone())
+    );
+    assert!(
+        !cycle_reachable_from(&store, &third.id),
+        "the graph is acyclic"
+    );
+    assert!(
+        store.parent(&third.id).is_some(),
+        "parent references resolve"
+    );
+    assert!(
+        store.parent(&second.id).is_some(),
+        "parent references resolve"
+    );
+}
+
+/// **Two resources at the same value are two revisions.**
+///
+/// The row the model was adopted for: a revision belongs to a resource, so
+/// identical content on two resources is never one historical object.
+#[test]
+fn two_resources_at_the_same_value_are_distinct_revisions() {
+    let (_directory, _db, store) = durable_store("required-resources.log");
+
+    let one = store
+        .create("tasks:1", A.into(), "contract".into())
+        .unwrap();
+    let two = store
+        .create("tasks:2", A.into(), "contract".into())
+        .unwrap();
+
+    assert_ne!(one.id, two.id, "same state, different resources");
+    assert_eq!(one.content_id, two.content_id, "and it is the same state");
+    assert_eq!(store.history_of("tasks:1").len(), 1);
+    assert_eq!(store.history_of("tasks:2").len(), 1);
+}
+
+/// The same sequence driven through the fenced write path.
+#[test]
+fn a_then_b_then_a_through_the_fenced_path() {
+    let directory = TempDir::new().unwrap();
+    let db = Arc::new(FeltDb::open(directory.path().join("required-cas.log")).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+
+    db.insert("tasks:1", json!({"title": "A", "__version": 1}))
+        .unwrap();
+    db.compare_and_set_json("tasks:1", 1, None, None, false, json!({"title": "B"}))
+        .unwrap();
+    db.compare_and_set_json("tasks:1", 2, None, None, false, json!({"title": "A"}))
+        .unwrap();
+
+    let history = store.history_of("tasks:1");
+    assert_eq!(history.len(), 3, "each fenced write minted a revision");
+    assert_ne!(
+        history[0].id, history[2].id,
+        "returning to A is a new revision"
+    );
+    assert_eq!(history[1].parent_id.as_ref(), Some(&history[0].id));
+    assert_eq!(history[2].parent_id.as_ref(), Some(&history[1].id));
+}
+
+/// The same sequence driven through the unconditional write path.
+#[test]
+fn a_then_b_then_a_through_the_unconditional_path() {
+    let directory = TempDir::new().unwrap();
+    let db = Arc::new(FeltDb::open(directory.path().join("required-uncond.log")).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+
+    db.insert("tasks:1", json!({"title": "A"})).unwrap();
+    db.update("tasks:1", json!({"title": "B"})).unwrap();
+    db.update("tasks:1", json!({"title": "A"})).unwrap();
+
+    let history = store.history_of("tasks:1");
+    assert_eq!(history.len(), 3, "each write minted a revision");
+    assert_ne!(history[0].id, history[2].id);
+    assert_eq!(
+        history[0].content_id, history[2].content_id,
+        "the same state, twice"
+    );
+    assert_eq!(history[2].parent_id.as_ref(), Some(&history[1].id));
+}
+
+/// **The negative control, in the form that matters.**
+///
+/// A write that lands on content equal to an existing revision produces a *new*
+/// revision descending from what this resource held — it does not adopt the
+/// existing revision's ancestry. Content equality is not descent.
+#[test]
+fn a_write_that_matches_existing_content_does_not_inherit_its_ancestry() {
+    let directory = TempDir::new().unwrap();
+    let db = Arc::new(FeltDb::open(directory.path().join("required-control.log")).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+
+    // An unrelated history that happens to contain the content {"title":"B"}.
+    let unrelated_root = store
+        .create("other:1", r#"{"unrelated":true}"#.into(), "other".into())
+        .unwrap();
+    let planted = store
+        .commit(r#"{"title":"B"}"#.into(), &unrelated_root, "other".into())
+        .unwrap();
+
+    // A resource written to A, then to the same content as `planted`.
+    db.insert("tasks:1", json!({"title": "A"})).unwrap();
+    db.update("tasks:1", json!({"title": "B"})).unwrap();
+
+    let history = store.history_of("tasks:1");
+    assert_eq!(history.len(), 2, "both writes minted");
+    let minted = &history[1];
+
+    assert_eq!(
+        minted.content_id, planted.content_id,
+        "the write reached the same value"
+    );
+    assert_ne!(minted.id, planted.id, "and is still a different revision");
+    assert_eq!(
+        minted.parent_id.as_ref(),
+        Some(&history[0].id),
+        "it descends from what this resource held"
+    );
+    assert_eq!(
+        store.get(&planted.id).unwrap().parent_id,
+        Some(unrelated_root.id),
+        "the unrelated history was not touched"
+    );
+}