@feltdb/core 0.13.0 → 0.16.0

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

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