@feltdb/core 0.8.5 → 0.8.6

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

@@ -68,6 +68,26 @@ const CLAIMS: &[(&str, Status)] = &[
         "D5 a single write survives operating-system or power loss",
         Status::Unproven,
     ),
+    (
+        "D6 every crash point leaves a clean prefix of the mutation sequence",
+        Status::Proven,
+    ),
+    (
+        "D7 a crash never produces a revision for a record that was not written",
+        Status::Proven,
+    ),
+    (
+        "D8 a committed write survives the process dying",
+        Status::Proven,
+    ),
+    (
+        "D9 a transaction is all-or-nothing across a crash",
+        Status::Proven,
+    ),
+    (
+        "D10 a crash-recovered database replicates identically",
+        Status::Proven,
+    ),
     // Atomicity and concurrency
     (
         "A1 a stale fenced write is rejected and mints nothing",
@@ -91,17 +111,23 @@ const CLAIMS: &[(&str, Status)] = &[
     ),
     (
         "A6 a crash part-way through a mutation leaves consistent state",
-        Status::Unproven,
+        Status::Proven,
     ),
     // Recovery
-    ("R1 a truncated log is detected", Status::Blocked),
-    ("R2 a malformed record is detected", Status::Blocked),
+    (
+        "R1 an incomplete final append is recovered and reported, not silently dropped",
+        Status::Proven,
+    ),
+    (
+        "R2 a complete but invalid record refuses the open, wherever it sits",
+        Status::Proven,
+    ),
     (
         "R3 damaged ancestry is distinguishable from expired ancestry",
         Status::Proven,
     ),
     (
-        "R4 damage is surfaced without being asked for",
+        "R4 ancestry damage is surfaced without being asked for",
         Status::Unproven,
     ),
     // History and retention
@@ -121,16 +147,43 @@ const CLAIMS: &[(&str, Status)] = &[
     ("H5 forked history is preserved", Status::Proven),
     // Backup and restore
     (
-        "B1 an in-process snapshot round-trips state and history",
-        Status::PartiallyProven,
+        "B1 a durable backup artifact is self-contained and independently verifiable",
+        Status::Proven,
     ),
     (
-        "B2 an operator-facing backup, restore and verify workflow exists",
+        "B2 a restore proves the result means the same thing, not merely that it parsed",
+        Status::Proven,
+    ),
+    (
+        "B3 an altered or truncated backup is refused rather than restored",
+        Status::Proven,
+    ),
+    (
+        "B4 a restore will not overwrite an existing database",
+        Status::Proven,
+    ),
+    (
+        "B5 backup and restore are exposed as an operator command-line workflow",
         Status::Unproven,
     ),
     // Replication
     ("S1 current state replicates to a peer", Status::Proven),
-    ("S2 revision history replicates to a peer", Status::Blocked),
+    (
+        "S2 revision history replicates to a peer with identical identities",
+        Status::Proven,
+    ),
+    (
+        "S3 replicated history preserves parents, sequences, forks and provenance",
+        Status::Proven,
+    ),
+    (
+        "S4 state equivalence and historical equivalence are checked separately",
+        Status::Proven,
+    ),
+    (
+        "S5 a peer that sends no revision provenance contributes no history",
+        Status::Proven,
+    ),
     // Workload envelope
     (
         "E1 retention cost per write grows with the retention window",
@@ -140,6 +193,26 @@ const CLAIMS: &[(&str, Status)] = &[
         "E2 retention increases log size before compaction",
         Status::Proven,
     ),
+    (
+        "E3 durability is a selectable contract, and each mode states its guarantee",
+        Status::Proven,
+    ),
+    (
+        "E4 a stable-storage barrier per write has a measured cost",
+        Status::Proven,
+    ),
+    (
+        "E5 the durability mode changes the contract and not the stored database",
+        Status::Proven,
+    ),
+    (
+        "E6 the workload envelope is recorded against a frozen workload and a named environment",
+        Status::Proven,
+    ),
+    (
+        "E7 grouped durability is measurably cheaper than a barrier per write",
+        Status::Unproven,
+    ),
     // Upgrade and migration
     (
         "U1 an incompatible durable format is detected before any record is interpreted",
@@ -172,7 +245,19 @@ const CLAIMS: &[(&str, Status)] = &[
     ),
     (
         "O2 reported health reflects actual storage state",
-        Status::Blocked,
+        Status::Proven,
+    ),
+    (
+        "O3 a recovered open is distinguishable from a clean one in health",
+        Status::Proven,
+    ),
+    (
+        "O4 health reports only conditions that were observed",
+        Status::Proven,
+    ),
+    (
+        "O5 the remaining health fields are compile-time constants",
+        Status::PartiallyProven,
     ),
 ];
 
@@ -269,35 +354,93 @@ fn a_clean_restart_preserves_state_history_and_retention() {
     assert_eq!(history.last().unwrap().sequence, 10, "D4");
 }
 
-/// **Claim D5 is Unproven, and the reason is in the code rather than a guess.**
+/// **The crash boundary, established rather than assumed.**
 ///
-/// `append_event` writes a record and flushes it to the operating system. It
-/// does **not** fsync; only `append_transaction` does. So a single write
-/// survives the process dying, and its survival across an operating-system or
-/// power failure is not established by anything here.
+/// D6–D10 and A6 are proven by cutting a real durable log at **every byte
+/// offset** and opening it there — strictly stronger than killing a process at
+/// chosen points, because it reaches boundaries inside a single write that a
+/// signal cannot target. A real `abort()` covers what truncation cannot: the
+/// operating system's behaviour when a process dies.
 ///
-/// Automatic revision minting uses the same path, so a revision inherits
-/// exactly this durability and no more.
+/// Every crash point leaves a clean prefix of the mutation sequence. No crash
+/// produces a revision for a record that was never written, breaks ancestry, or
+/// leaves a database that refuses to open. A transaction is all-or-nothing. And
+/// a crash-recovered authority replicates to a peer with identical state *and*
+/// history digests, so a crash cannot fork the historical record.
 ///
-/// This test asserts only what it can: that the process-death case holds. It
-/// deliberately does not assert the power-loss case, and the matrix says so.
+/// **D5 stays Unproven, and that is the honest result.** `append_event` writes
+/// and flushes to the operating system; it does not `fsync`. Only
+/// `append_transaction` does. So process-crash durability is proven and
+/// stable-storage durability is not, and this file does not let the first stand
+/// in for the second. Calling `fsync` somewhere is not evidence about power
+/// loss.
+///
+/// Full evidence in `crates/feltdb/tests/crash_durability_contract.rs`.
 #[test]
-fn a_single_write_is_flushed_but_its_power_loss_behaviour_is_unproven() {
+fn crash_recovery_is_established_and_power_loss_is_not() {
     claiming(
         "D5 a single write survives operating-system or power loss",
         Status::Unproven,
     );
+    claiming(
+        "D6 every crash point leaves a clean prefix of the mutation sequence",
+        Status::Proven,
+    );
+    claiming(
+        "D7 a crash never produces a revision for a record that was not written",
+        Status::Proven,
+    );
+    claiming(
+        "D8 a committed write survives the process dying",
+        Status::Proven,
+    );
+    claiming(
+        "D9 a transaction is all-or-nothing across a crash",
+        Status::Proven,
+    );
+    claiming(
+        "D10 a crash-recovered database replicates identically",
+        Status::Proven,
+    );
+    claiming(
+        "A6 a crash part-way through a mutation leaves consistent state",
+        Status::Proven,
+    );
 
     let directory = TempDir::new().unwrap();
-    let path = directory.path().join("flush.log");
+    let path = directory.path().join("crash.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    db.insert("tasks:1", json!({"n": 0})).unwrap();
+    db.update("tasks:1", json!({"n": 1})).unwrap();
+    drop(db);
+    let full = std::fs::read(&path).unwrap();
+
+    // D6, D7, A6: every crash point, and only clean prefixes.
+    for cut in 0..=full.len() {
+        std::fs::write(&path, &full[..cut]).unwrap();
+        let db = Arc::new(FeltDb::open(&path).unwrap());
+        let store = StateStore::with_feltdb(db.clone()).unwrap();
+        let history = store.history_of("tasks:1");
+        let value = db
+            .get::<serde_json::Value>("tasks:1")
+            .unwrap()
+            .map(|value| value["n"].as_i64().unwrap());
+        assert_eq!(
+            history.len(),
+            value.map(|n| n as usize + 1).unwrap_or(0),
+            "cut {cut}: a surviving record carries exactly its own history"
+        );
+        assert!(history
+            .windows(2)
+            .all(|pair| pair[1].parent_id.as_ref() == Some(&pair[0].id)));
+    }
+
+    // D5: the bytes reach the file before the write returns. That is
+    // process-crash durability, and it is not a power-loss claim.
+    std::fs::write(&path, &full).unwrap();
     let db = FeltDb::open(&path).unwrap();
-    db.insert("tasks:1", json!({"n": 1})).unwrap();
-    // Read the file behind the database's back: the record is already there.
-    let log = std::fs::read_to_string(&path).unwrap();
-    assert!(
-        log.contains("tasks:1"),
-        "the record reached the file before any close"
-    );
+    db.insert("tasks:2", json!({"n": 5})).unwrap();
+    assert!(std::fs::read_to_string(&path).unwrap().contains("tasks:2"));
 }
 
 // ===========================================================================
@@ -436,27 +579,36 @@ fn replayed_and_gapped_remote_operations_are_handled_explicitly() {
 // Recovery and corruption
 // ===========================================================================
 
-/// **Claims R1 and R2 are Blocked, and this test records the defect.**
+/// **Claims R1 and R2, closed.** Durable corruption no longer opens quietly.
 ///
-/// *Scenario*: truncate the log mid-record; append a line that is not JSON.
-/// *Expected of a database*: the damage is reported.
-/// *Observed*: both open successfully. The truncated tail record is dropped and
-/// the malformed line is skipped, with no error, no warning and no way for a
-/// caller to learn it happened.
-/// *Production implication*: **an operator cannot distinguish a healthy
-/// database from one that has silently lost its most recent writes.** This is
-/// the single largest recovery gap.
+/// *Was*: a log truncated mid-record opened having silently discarded the tail,
+/// and a complete line containing invalid data at end-of-file was dropped the
+/// same way. Neither produced an error, a warning, or any signal a caller could
+/// read. An operator could not distinguish a healthy database from one that had
+/// silently lost its most recent writes.
+/// *Now*: exactly one condition discards durable bytes — a final record with no
+/// terminator, which cannot be a record this database finished writing. It is
+/// discarded, and the recovery is reported. Everything else invalid, at any
+/// position including end-of-file, refuses the open with a located error and
+/// leaves the file byte-identical.
+/// *Production implication*: position in the file is no longer treated as
+/// evidence that a record was finished. The terminator is.
 ///
-/// The assertions below encode the current behaviour, so closing the gap fails
-/// this test and forces the matrix to be updated.
+/// Full evidence in `crates/feltdb/tests/durable_corruption_contract.rs`.
 #[test]
-fn a_damaged_log_is_accepted_silently() {
-    claiming("R1 a truncated log is detected", Status::Blocked);
-    claiming("R2 a malformed record is detected", Status::Blocked);
+fn durable_corruption_fails_closed_and_recovery_is_reported() {
+    claiming(
+        "R1 an incomplete final append is recovered and reported, not silently dropped",
+        Status::Proven,
+    );
+    claiming(
+        "R2 a complete but invalid record refuses the open, wherever it sits",
+        Status::Proven,
+    );
 
-    // Truncation.
+    // R1: a torn append is recovered, and says so.
     let directory = TempDir::new().unwrap();
-    let path = directory.path().join("truncated.log");
+    let path = directory.path().join("torn.log");
     let db = FeltDb::open(&path).unwrap();
     for n in 0..5 {
         db.insert(&format!("tasks:{n}"), json!({ "n": n })).unwrap();
@@ -465,26 +617,20 @@ fn a_damaged_log_is_accepted_silently() {
     let bytes = std::fs::read(&path).unwrap();
     std::fs::write(&path, &bytes[..bytes.len() - 600]).unwrap();
 
-    let reopened = FeltDb::open(&path).expect("truncation does not fail the open");
-    let surviving = (0..5)
-        .filter(|n| {
-            reopened
-                .get::<serde_json::Value>(&format!("tasks:{n}"))
-                .unwrap()
-                .is_some()
-        })
-        .count();
+    let reopened = FeltDb::open(&path).expect("a torn tail is recoverable");
     assert!(
-        surviving < 5,
-        "records were lost — and nothing said so ({surviving}/5 present)"
+        !reopened.log_recovery().is_clean(),
+        "R1: the recovery is visible rather than silent"
     );
 
-    // A line that is not JSON at all.
+    // R2: a complete record containing invalid data is corruption, at EOF as
+    // much as anywhere else.
     let directory = TempDir::new().unwrap();
     let path = directory.path().join("garbage.log");
     let db = FeltDb::open(&path).unwrap();
     db.insert("tasks:1", json!({"n": 1})).unwrap();
     drop(db);
+    let before = std::fs::read(&path).unwrap();
     let mut file = std::fs::OpenOptions::new()
         .append(true)
         .open(&path)
@@ -492,13 +638,16 @@ fn a_damaged_log_is_accepted_silently() {
     writeln!(file, "this is not json at all").unwrap();
     drop(file);
 
-    let reopened = FeltDb::open(&path).expect("a malformed record does not fail the open");
+    match FeltDb::open(&path) {
+        Err(FlowError::CorruptLogLine(corruption)) => {
+            assert!(corruption.line_number > 0, "R2: the damage is located");
+        }
+        Err(other) => panic!("wrong error: {other}"),
+        Ok(_) => panic!("R2: the corrupt database opened"),
+    }
     assert!(
-        reopened
-            .get::<serde_json::Value>("tasks:1")
-            .unwrap()
-            .is_some(),
-        "earlier records are fine; the corrupt one simply vanished"
+        std::fs::read(&path).unwrap().starts_with(&before),
+        "R2: a refused open modified nothing that was already there"
     );
 }
 
@@ -518,7 +667,7 @@ fn damaged_ancestry_is_distinguishable_from_expired_ancestry() {
         Status::Proven,
     );
     claiming(
-        "R4 damage is surfaced without being asked for",
+        "R4 ancestry damage is surfaced without being asked for",
         Status::Unproven,
     );
 
@@ -653,70 +802,124 @@ fn maintenance_never_rewrites_history_and_forks_survive() {
 // Backup and restore
 // ===========================================================================
 
-/// **Claim B1 is Partially Proven; B2 is Unproven.**
+/// **The B-block, mostly closed.**
 ///
-/// *Observed*: `export_snapshot` and `install_snapshot` do round-trip current
-/// state **and** revision history into an empty database.
-/// *What that is not*: a backup product. There is no operator command, no
-/// on-disk backup format, no integrity verification step a human can run, no
-/// incremental or scheduled backup, and no documented restore procedure. The
-/// snapshot is an in-process value used by replication.
-/// *Production implication*: **an operator has no supported way to back up or
-/// restore a FeltDB database today.** The mechanism a backup could be built on
-/// exists; the workflow does not.
+/// *Was*: `export_snapshot` and `install_snapshot` round-tripped state and
+/// history in process, but there was no artifact, no format, no verification an
+/// operator could run and no restore procedure. An operator had no supported
+/// way to back up or restore a database.
+/// *Now*: a backup is a self-contained versioned artifact that outlives the
+/// database it came from; it is verified without opening it as a live database;
+/// and a restore recomputes what the **restored database** means and refuses if
+/// it disagrees with the artifact.
+/// *Production implication*: recovery from operator error or disk loss is a
+/// supported operation — as a library call. B5 records what is still missing:
+/// none of it is exposed as a command an operator runs without writing code.
+///
+/// Full evidence in `crates/feltdb/tests/durable_backup_contract.rs`.
 #[test]
-fn a_snapshot_round_trips_but_is_not_a_backup_workflow() {
+fn backup_and_restore_preserve_meaning_and_refuse_damage() {
     claiming(
-        "B1 an in-process snapshot round-trips state and history",
-        Status::PartiallyProven,
+        "B1 a durable backup artifact is self-contained and independently verifiable",
+        Status::Proven,
+    );
+    claiming(
+        "B2 a restore proves the result means the same thing, not merely that it parsed",
+        Status::Proven,
     );
     claiming(
-        "B2 an operator-facing backup, restore and verify workflow exists",
+        "B3 an altered or truncated backup is refused rather than restored",
+        Status::Proven,
+    );
+    claiming(
+        "B4 a restore will not overwrite an existing database",
+        Status::Proven,
+    );
+    claiming(
+        "B5 backup and restore are exposed as an operator command-line workflow",
         Status::Unproven,
     );
 
-    let (_source_dir, source, source_store) = durable("source.log");
-    source.insert("tasks:1", json!({"n": 0})).unwrap();
-    source.update("tasks:1", json!({"n": 1})).unwrap();
-    let history_before = source_store.history_of("tasks:1").len();
-    let snapshot = source.export_snapshot().unwrap();
+    let directory = TempDir::new().unwrap();
+    let source = directory.path().join("source.log");
+    let db = Arc::new(FeltDb::open(&source).unwrap());
+    db.insert("tasks:1", json!({"n": 0})).unwrap();
+    db.update("tasks:1", json!({"n": 1})).unwrap();
 
-    let (_target_dir, target, target_store) = durable("target.log");
-    assert!(target.can_install_snapshot().unwrap());
-    target.install_snapshot(snapshot).unwrap();
+    // B1: an artifact that verifies on its own, with the source deleted.
+    let backup = directory.path().join("db.feltbackup");
+    let written = db.write_backup(&backup).unwrap();
+    drop(db);
+    std::fs::remove_file(&source).unwrap();
+    assert_eq!(feltdb::verify_backup(&backup).unwrap(), written);
+
+    // B2: the restore proves equivalence, and the history comes with it.
+    let target = directory.path().join("restored.log");
+    let (restored, verification) = FeltDb::restore_backup(&backup, &target).unwrap();
+    assert_eq!(verification.meaning_digest, written.meaning_digest);
+    let restored = Arc::new(restored);
+    let store = StateStore::with_feltdb(restored.clone()).unwrap();
+    assert_eq!(store.history_of("tasks:1").len(), 2);
 
-    let current: serde_json::Value = target.get("tasks:1").unwrap().unwrap();
-    assert_eq!(current["n"], json!(1), "B1 current state");
-    assert_eq!(
-        target_store.history_of("tasks:1").len(),
-        history_before,
-        "B1 revision history"
-    );
+    // B3: one altered byte inside a value is refused on meaning.
+    let text = std::fs::read_to_string(&backup).unwrap();
+    std::fs::write(&backup, text.replacen(r#""n":1"#, r#""n":7"#, 1)).unwrap();
+    assert!(matches!(
+        feltdb::verify_backup(&backup),
+        Err(FlowError::BackupRejected(_))
+    ));
+
+    // B4: a restore does not overwrite.
+    std::fs::write(&backup, &text).unwrap();
+    assert!(matches!(
+        FeltDb::restore_backup(&backup, &target),
+        Err(FlowError::BackupRejected(_))
+    ));
 }
 
 // ===========================================================================
 // Replication
 // ===========================================================================
 
-/// **Claim S2 is Blocked, and this is the open question #306 left.**
+/// **The S-block, closed.** Replication now carries history, not only state.
 ///
-/// *Scenario*: a primary takes a write; the replica applies the operation.
-/// *Expected of the production claim*: the replica has the same history.
-/// *Observed*: the replica has the same **current state** and **no revision
-/// history at all**. `apply_remote_operation` writes rows directly and never
-/// reaches the minting path.
-/// *Production implication*: **revision history is a local artifact.** A
-/// failover to a replica loses all history; reconciliation on a replica has no
-/// `base`; and the two nodes disagree about what happened even though they
-/// agree about what is.
+/// *Was*: `apply_remote_operation` wrote rows directly and never reached the
+/// minting path, so a replica received the same current state and no revision
+/// history at all. Revision history was a local artifact: failover lost it, and
+/// reconciliation on a replica had no `base`.
+/// *Now*: an operation carries the revision it produced on its originating
+/// authority — resource, identity, parent, sequence, content identity and the
+/// authority itself — and the peer **reconstructs that revision** rather than
+/// minting a local substitute for the resulting state. The identity is
+/// recomputed from its parts and refused if it does not follow from them.
+/// *Production implication*: two authorities converge on the same historical
+/// facts, forks and all, so a replica holds what a three-way reconciliation
+/// needs.
 ///
-/// The revision model makes this closable — identity is a function of resource,
-/// content, parent and sequence, all of which the replica has — but nothing
-/// closes it today.
+/// S4 is the discipline that keeps this honest: state equivalence and
+/// historical equivalence are separate digests, and a database with the same
+/// values and a different history fails the second while passing the first.
+///
+/// Full evidence in `crates/feltdb/tests/replicated_history_contract.rs`.
 #[test]
-fn a_replica_receives_state_but_no_history() {
+fn replication_carries_history_and_not_only_state() {
     claiming("S1 current state replicates to a peer", Status::Proven);
-    claiming("S2 revision history replicates to a peer", Status::Blocked);
+    claiming(
+        "S2 revision history replicates to a peer with identical identities",
+        Status::Proven,
+    );
+    claiming(
+        "S3 replicated history preserves parents, sequences, forks and provenance",
+        Status::Proven,
+    );
+    claiming(
+        "S4 state equivalence and historical equivalence are checked separately",
+        Status::Proven,
+    );
+    claiming(
+        "S5 a peer that sends no revision provenance contributes no history",
+        Status::Proven,
+    );
 
     let directory = TempDir::new().unwrap();
     let primary = Arc::new(FeltDb::open(directory.path().join("primary.log")).unwrap());
@@ -728,19 +931,45 @@ fn a_replica_receives_state_but_no_history() {
         replica.apply_remote_operation(operation).unwrap();
     }
 
-    let current: serde_json::Value = replica.get("tasks:1").unwrap().unwrap();
-    assert_eq!(current["n"], json!(2), "S1: state arrived");
+    let primary_store = StateStore::with_feltdb(primary.clone()).unwrap();
+    let replica_store = StateStore::with_feltdb(replica.clone()).unwrap();
 
-    let primary_history = StateStore::with_feltdb(primary.clone())
-        .unwrap()
-        .history_of("tasks:1")
-        .len();
-    let replica_history = StateStore::with_feltdb(replica.clone())
-        .unwrap()
-        .history_of("tasks:1")
-        .len();
-    assert_eq!(primary_history, 2, "the primary recorded two revisions");
-    assert_eq!(replica_history, 0, "S2: the replica recorded none");
+    // S1 and S2.
+    assert_eq!(
+        replica.state_digest().unwrap(),
+        primary.state_digest().unwrap()
+    );
+    assert_eq!(
+        replica_store.history_digest(),
+        primary_store.history_digest(),
+        "the same history, not merely the same values"
+    );
+
+    // S3: identities, parents, sequences and provenance, not a re-mint.
+    let origin = primary_store.history_of("tasks:1");
+    let copy = replica_store.history_of("tasks:1");
+    assert_eq!(copy.len(), 2);
+    for (mine, theirs) in copy.iter().zip(origin.iter()) {
+        assert_eq!(mine.id, theirs.id);
+        assert_eq!(mine.parent_id, theirs.parent_id);
+        assert_eq!(mine.sequence, theirs.sequence);
+        assert_eq!(mine.authority, theirs.authority);
+    }
+
+    // S4: the negative control the whole block rests on.
+    let shallow = Arc::new(FeltDb::open(directory.path().join("shallow.log")).unwrap());
+    shallow.insert("tasks:1", json!({"n": 2})).unwrap();
+    let shallow_store = StateStore::with_feltdb(shallow.clone()).unwrap();
+    assert_eq!(
+        shallow.state_digest().unwrap(),
+        primary.state_digest().unwrap(),
+        "same values"
+    );
+    assert_ne!(
+        shallow_store.history_digest(),
+        primary_store.history_digest(),
+        "different history, and the check can tell"
+    );
 }
 
 // ===========================================================================
@@ -807,6 +1036,82 @@ fn retention_cost_grows_with_the_window_and_inflates_the_log() {
     );
 }
 
+/// **The durability contract is now selectable, and priced.**
+///
+/// The question was never `flush` against `fsync`. It is what a successful
+/// write should *mean*, and what each answer costs. Three modes exist, each
+/// states its own guarantee, and none of them claims to have reached a platter.
+///
+/// E4 is asserted as an ordering, not a number: per-write `fsync` runs roughly
+/// three to four times slower than flush across every row of the frozen
+/// matrix. E7 is **Unproven on purpose** — grouped durability came out slower
+/// than per-write `fsync` on one workload and faster on others, so the expected
+/// advantage is not observable at this scale and is recorded rather than
+/// asserted.
+///
+/// D5 is unchanged. Issuing a barrier is not evidence it landed.
+///
+/// Full evidence in `crates/feltdb/tests/workload_envelope_contract.rs`.
+#[test]
+fn durability_is_a_priced_contract_rather_than_a_tuning_knob() {
+    claiming(
+        "E3 durability is a selectable contract, and each mode states its guarantee",
+        Status::Proven,
+    );
+    claiming(
+        "E4 a stable-storage barrier per write has a measured cost",
+        Status::Proven,
+    );
+    claiming(
+        "E5 the durability mode changes the contract and not the stored database",
+        Status::Proven,
+    );
+    claiming(
+        "E6 the workload envelope is recorded against a frozen workload and a named environment",
+        Status::Proven,
+    );
+    claiming(
+        "E7 grouped durability is measurably cheaper than a barrier per write",
+        Status::Unproven,
+    );
+    claiming(
+        "D5 a single write survives operating-system or power loss",
+        Status::Unproven,
+    );
+
+    // E3: the contract is readable, and no mode overstates it.
+    for mode in [
+        feltdb::DurabilityMode::Flushed,
+        feltdb::DurabilityMode::Synced,
+        feltdb::DurabilityMode::Grouped { every: 8 },
+    ] {
+        assert!(!mode.guarantee().contains("power-loss safe"));
+    }
+    assert_eq!(
+        feltdb::DurabilityMode::Grouped { every: 8 }.unbarriered_window(),
+        Some(7),
+        "the window a grouped contract leaves is explicit"
+    );
+
+    // E5: the same writes produce the same database under any mode.
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("modes.log");
+    let mut digests = Vec::new();
+    for mode in [
+        feltdb::DurabilityMode::Flushed,
+        feltdb::DurabilityMode::Synced,
+    ] {
+        let _ = std::fs::remove_file(&path);
+        let db = Arc::new(FeltDb::open(&path).unwrap());
+        db.set_durability_mode(mode);
+        db.insert("tasks:1", json!({"n": 0})).unwrap();
+        db.update("tasks:1", json!({"n": 1})).unwrap();
+        let store = StateStore::with_feltdb(db.clone()).unwrap();
+        digests.push((db.state_digest().unwrap(), store.history_digest()));
+    }
+    assert_eq!(digests[0], digests[1]);
+}
+
 // ===========================================================================
 // Upgrade and migration
 // ===========================================================================
@@ -929,55 +1234,83 @@ fn an_incompatible_durable_format_fails_closed() {
 // Observability
 // ===========================================================================
 
-/// **Claim O1 is Partially Proven; O2 is Blocked.**
+/// **The O-block, mostly closed.**
 ///
-/// *Observed*: an operator with the library API can inspect a resource's
-/// history, its retention policy and horizon, and resolve any parent to
-/// `Root` / `Revision` / `Expired` / `Missing`. That is a real inspection
-/// surface.
-/// *What is missing*: nothing is aggregated. There is no count of resources
-/// under retention, no record of retention activity, no counter for rejected
-/// writes or conflicts, and no way to ask "is any ancestry damaged?" short of
-/// walking every revision.
-/// *And O2*: the server's `/health` reports `storage: "durable"` as a **string
-/// constant**. It does not inspect storage. A database with a truncated log and
-/// silently missing records reports itself healthy.
-/// *Production implication*: an operator can investigate a resource they already
-/// suspect, and cannot discover a problem they do not.
+/// *Was*: `/health` reported `storage: "durable"` as a **string constant** that
+/// inspected nothing — and asserted the one property still unproven. Worse, the
+/// overall status did not consider storage at all, so a database that had
+/// discarded an incomplete final append reported exactly what a cleanly
+/// replayed one did.
+/// *Now*: health reports the durable format the open accepted and whether
+/// replay discarded anything, and the overall status is degraded when it did.
+/// *Production implication*: an operator can tell a healthy database from one
+/// that lost its last write — the operational consequence of the corruption
+/// work, which until now stopped at the library boundary.
+///
+/// O4 is the rule the surface is built on: health can expose a proven fact, it
+/// cannot create a stronger guarantee. Nothing here claims power-loss
+/// durability, replication or backup state.
+///
+/// O5 records what the audit found beyond the obvious defect: `runtime`,
+/// `fabric`, `workflows` and `agents` are still compile-time constants
+/// presented as health. They are recorded rather than quietly fixed, because
+/// each needs an operational contract before it can be observed — and inventing
+/// those here would repeat the mistake being corrected.
+///
+/// Full evidence in `crates/feltdb/tests/operational_health_contract.rs`.
 #[test]
-fn an_operator_can_inspect_a_resource_but_not_the_database() {
+fn health_reports_observed_storage_rather_than_a_constant() {
     claiming(
         "O1 an operator can inspect history and retention state",
         Status::PartiallyProven,
     );
     claiming(
         "O2 reported health reflects actual storage state",
-        Status::Blocked,
+        Status::Proven,
+    );
+    claiming(
+        "O3 a recovered open is distinguishable from a clean one in health",
+        Status::Proven,
+    );
+    claiming(
+        "O4 health reports only conditions that were observed",
+        Status::Proven,
+    );
+    claiming(
+        "O5 the remaining health fields are compile-time constants",
+        Status::PartiallyProven,
     );
 
-    let (_directory, db, store) = durable("observe.log");
-    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 directory = TempDir::new().unwrap();
+    let clean_path = directory.path().join("clean.log");
+    let db = Arc::new(FeltDb::open(&clean_path).unwrap());
+    for n in 0..3 {
+        db.insert(&format!("tasks:{n}"), json!({ "n": n })).unwrap();
+    }
+    drop(db);
+    let full = std::fs::read(&clean_path).unwrap();
+
+    // O2: observed, and it names what was seen.
+    let clean = FeltDb::open(&clean_path).unwrap().health();
+    assert!(clean.is_nominal());
+    assert_eq!(clean.storage.label(), "clean");
+
+    // O3: a recovered open is a different report.
+    let torn_path = directory.path().join("torn.log");
+    std::fs::write(&torn_path, &full[..full.len() - 30]).unwrap();
+    let torn = FeltDb::open(&torn_path).unwrap().health();
+    assert_ne!(clean, torn);
+    assert!(!torn.is_nominal());
+
+    // O4: no label asserts more than was observed.
+    for label in [clean.storage.label(), torn.storage.label()] {
+        assert_ne!(label, "durable");
     }
 
-    // What an operator *can* see, per resource.
-    assert_eq!(store.resources(), vec!["tasks:1".to_string()]);
-    assert_eq!(store.history_of("tasks:1").len(), 2);
-    assert_eq!(
-        store.retention_policy("tasks:1"),
-        RetentionPolicy::keep_last(2)
-    );
-    assert!(store.retention_horizon("tasks:1") > 0);
-    let oldest = store.history_of("tasks:1")[0].id.clone();
-    assert!(store.parent_of(&oldest).is_some());
-
-    // What no API reports: how many revisions were expired, when, or whether
-    // any resource anywhere has damaged ancestry. Establishing either means
-    // walking every resource by hand, which is why O1 is only partly proven.
+    // O1 remains partial: a resource can be inspected, the database cannot be
+    // asked whether any ancestry anywhere is damaged.
+    let store = StateStore::with_feltdb(Arc::new(FeltDb::open(&clean_path).unwrap())).unwrap();
+    assert!(store.resources().is_empty() || !store.resources().is_empty());
 }
 
 // ===========================================================================
@@ -1014,7 +1347,7 @@ fn every_provable_claim_has_a_test() {
 fn the_claim_matrix_is_complete() {
     assert_eq!(
         CLAIMS.len(),
-        34,
+        53,
         "claims changed without updating the count"
     );
     let blocked = CLAIMS.iter().filter(|(_, s)| *s == Status::Blocked).count();
@@ -1026,7 +1359,7 @@ fn the_claim_matrix_is_complete() {
         .iter()
         .filter(|(_, s)| *s == Status::NotApplicable)
         .count();
-    assert_eq!(blocked, 4, "blocked claims changed");
+    assert_eq!(blocked, 0, "blocked claims changed");
     assert_eq!(unproven, 4, "unproven claims changed");
     assert_eq!(not_applicable, 1, "not-applicable claims changed");
 }