@feltdb/core 0.8.6 → 0.8.8

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

@@ -0,0 +1,771 @@
+//! The FeltDB production contract.
+//!
+//! The certification matrix records what the repository *proves*. This file
+//! records what FeltDB is willing to *promise*, which is a smaller and
+//! different thing: a promise has an audience, and an audience reads a
+//! guarantee as unconditional unless the condition is written next to it.
+//!
+//! # Why this is executable
+//!
+//! A public contract is the natural place for evidence drift to end up. Nobody
+//! edits a matrix to make a sale; people edit a promise. So no promise here
+//! stands on its own wording — every one names the certification claims that
+//! back it, and the tier it may occupy is *derived* from their statuses:
+//!
+//! - **Certified** — every backing claim is `Proven`. Promised without
+//!   qualification.
+//! - **Conditional** — every backing claim is `Proven`, and the promise states
+//!   the condition it holds under. Fully proven, deliberately scoped.
+//! - **Not certified** — at least one backing claim is not `Proven`. Written
+//!   down as a thing FeltDB does not promise, with the evidence that would
+//!   change that.
+//!
+//! Promoting a promise therefore requires promoting a claim, which requires a
+//! test. There is no path from wanting a guarantee to publishing one.
+//!
+//! # What this is not
+//!
+//! It is not a second source of truth. Statuses are read out of
+//! `production_certification.rs`; nothing about a claim is restated here.
+
+use std::collections::{BTreeMap, BTreeSet};
+
+mod common;
+
+/// How strongly FeltDB stands behind a promise.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Tier {
+    Certified,
+    Conditional,
+    NotCertified,
+}
+
+impl Tier {
+    const ALL: [Tier; 3] = [Tier::Certified, Tier::Conditional, Tier::NotCertified];
+
+    fn label(self) -> &'static str {
+        match self {
+            Tier::Certified => "Certified",
+            Tier::Conditional => "Conditional",
+            Tier::NotCertified => "Not certified",
+        }
+    }
+
+    /// A tier that promises something, as opposed to recording that FeltDB does
+    /// not. The distinction decides which checks apply.
+    fn promises(self) -> bool {
+        matches!(self, Tier::Certified | Tier::Conditional)
+    }
+}
+
+struct Promise {
+    id: &'static str,
+    area: &'static str,
+    promise: &'static str,
+    tier: Tier,
+    /// For `Conditional`, the condition the promise holds under. For
+    /// `Not certified`, the evidence that would change the answer. Empty only
+    /// for `Certified`, which holds unconditionally or not at all.
+    condition: &'static str,
+    /// The certification claims this rests on. Never empty.
+    backing: &'static [&'static str],
+}
+
+#[rustfmt::skip]
+const CONTRACT: &[Promise] = &[
+    // ------------------------------------------------------------- Certified
+    Promise { id: "P1", area: "Durability",
+        promise: "State, revision history, retention policy and retention horizon survive a clean \
+                  restart, and a reopened database continues its history rather than starting a new one.",
+        tier: Tier::Certified, condition: "", backing: &["D1", "D2", "D3", "D4"] },
+    Promise { id: "P2", area: "Mutation",
+        promise: "A write that has lost its fence is rejected and mints no revision, and concurrent \
+                  writes produce correct per-resource revision chains.",
+        tier: Tier::Certified, condition: "", backing: &["A1", "A2", "A3"] },
+    Promise { id: "P3", area: "Mutation",
+        promise: "A duplicate remote operation is idempotent, and a remote operation arriving with a \
+                  sequence gap is rejected rather than applied.",
+        tier: Tier::Certified, condition: "", backing: &["A4", "A5"] },
+    Promise { id: "P4", area: "Crash recovery",
+        promise: "A crash at any point leaves a clean prefix of the mutation sequence: never a partial \
+                  mutation, and never a revision for a record that was not written.",
+        tier: Tier::Certified, condition: "", backing: &["A6", "D6", "D7"] },
+    Promise { id: "P5", area: "Crash recovery",
+        promise: "A transaction is all-or-nothing across a crash.",
+        tier: Tier::Certified, condition: "", backing: &["D9"] },
+    Promise { id: "P6", area: "Crash recovery",
+        promise: "A committed write survives the process dying.",
+        tier: Tier::Certified, condition: "", backing: &["D8"] },
+    Promise { id: "P7", area: "Crash recovery",
+        promise: "A database recovered from a crash replicates identically to one that never crashed.",
+        tier: Tier::Certified, condition: "", backing: &["D10"] },
+    Promise { id: "P8", area: "History",
+        promise: "History is bounded by a retention policy and unbounded without one, a policy change \
+                  takes effect in both directions, maintenance never rewrites history, and forked \
+                  history is preserved.",
+        tier: Tier::Certified, condition: "", backing: &["H1", "H2", "H3", "H4", "H5"] },
+    Promise { id: "P9", area: "History",
+        promise: "Ancestry expired by retention is distinguishable from ancestry that was damaged.",
+        tier: Tier::Certified, condition: "", backing: &["R3"] },
+    Promise { id: "P10", area: "Corruption",
+        promise: "An incomplete final append is recovered and reported rather than silently dropped, \
+                  and a complete but invalid record refuses the open wherever it sits.",
+        tier: Tier::Certified, condition: "", backing: &["R1", "R2"] },
+    Promise { id: "P11", area: "Format",
+        promise: "A durable database declares its format, and a format this build cannot interpret \
+                  refuses the open before any record is read, leaving the file byte-identical.",
+        tier: Tier::Certified, condition: "", backing: &["U1", "U3", "U4", "U5", "U6"] },
+    Promise { id: "P12", area: "Backup",
+        promise: "A backup is self-contained and independently verifiable, a restore proves the result \
+                  means the same thing rather than merely that it parsed, an altered backup is refused, \
+                  and a restore never overwrites an existing database.",
+        tier: Tier::Certified, condition: "", backing: &["B1", "B2", "B3", "B4"] },
+    Promise { id: "P13", area: "Replication",
+        promise: "Replication carries revision history with identical identities, preserving parents, \
+                  sequences, forks and provenance, and evaluates state equivalence separately from \
+                  historical equivalence.",
+        tier: Tier::Certified, condition: "", backing: &["S1", "S2", "S3", "S4", "S5"] },
+    Promise { id: "P14", area: "Overload",
+        promise: "A request arriving while the server is saturated is refused with a status, an error \
+                  code and a retry hint, rather than absorbed into an unbounded queue.",
+        tier: Tier::Certified, condition: "", backing: &["M4"] },
+    Promise { id: "P15", area: "Reads",
+        promise: "A keyed lookup reads one record, and a limited search visits no more rows than its limit.",
+        tier: Tier::Certified, condition: "", backing: &["M5"] },
+    Promise { id: "P16", area: "Maintenance",
+        promise: "A timer-driven compaction prunes without rewriting the durable log, an explicit \
+                  compaction still rewrites immediately, and deferring the rewrite preserves state and history.",
+        tier: Tier::Certified, condition: "", backing: &["M1", "M2", "M3"] },
+    Promise { id: "P17", area: "Maintenance",
+        promise: "A compaction running concurrently with traffic leaves scoped reads correct and bounded, \
+                  and leaves the database intact across a forced rewrite and a reopen.",
+        tier: Tier::Certified, condition: "", backing: &["M8", "M9"] },
+    Promise { id: "P18", area: "Health",
+        promise: "A health report names only conditions that were observed, and a recovered open is \
+                  distinguishable from a clean one.",
+        tier: Tier::Certified, condition: "", backing: &["O3", "O4"] },
+
+    // ----------------------------------------------------------- Conditional
+    Promise { id: "P19", area: "Durability mode",
+        promise: "`Flushed`, the default, hands the write to the operating system and states that as its guarantee.",
+        tier: Tier::Conditional,
+        condition: "The write survives the process dying. It is not promised to survive the machine \
+                    losing power.",
+        backing: &["D8", "E3", "E5"] },
+    Promise { id: "P20", area: "Durability mode",
+        promise: "`Synced` issues a stable-storage barrier for every write, at a cost this repository has measured.",
+        tier: Tier::Conditional,
+        condition: "The barrier is issued. What the hardware does with it is outside FeltDB's evidence, \
+                    so this narrows the power-loss window rather than closing it.",
+        backing: &["E3", "E4", "E5"] },
+    Promise { id: "P21", area: "Durability mode",
+        promise: "`Grouped` names an exact bound on how many acknowledged writes have not yet been \
+                  through a barrier.",
+        tier: Tier::Conditional,
+        condition: "Up to `every - 1` acknowledged writes may be in that window. Choose this mode for \
+                    the stated window, not for throughput.",
+        backing: &["E3", "E5"] },
+    Promise { id: "P22", area: "Workload",
+        promise: "Retention cost per write grows with the retention window, and retention inflates the \
+                  log before compaction.",
+        tier: Tier::Conditional,
+        condition: "Under the frozen workload in the envelope contract. The ordering is the promise; \
+                    the measured numbers are not.",
+        backing: &["E1", "E2"] },
+    Promise { id: "P23", area: "Durability mode",
+        promise: "Selecting a durability mode changes the contract and not the stored database, so a \
+                  mode can be changed without migrating anything.",
+        tier: Tier::Conditional,
+        condition: "The stored bytes are identical across modes; the acknowledgement semantics are not.",
+        backing: &["E5"] },
+
+    // --------------------------------------------------------- Not certified
+    Promise { id: "N1", area: "Durability",
+        promise: "FeltDB does not promise that a single write survives operating-system or power loss.",
+        tier: Tier::NotCertified,
+        condition: "A test on hardware that can actually be cut, verifying the database after recovery.",
+        backing: &["D5"] },
+    Promise { id: "N2", area: "Workload",
+        promise: "FeltDB does not promise that `Grouped` is faster than a barrier per write.",
+        tier: Tier::NotCertified,
+        condition: "A stable measurement showing the ordering holds across repeated runs. An earlier \
+                    assertion was removed after a run inverted it.",
+        backing: &["E7"] },
+    Promise { id: "N3", area: "Workload",
+        promise: "FeltDB does not promise that its published performance numbers transfer to your hardware.",
+        tier: Tier::NotCertified,
+        condition: "A test asserting that each measurement carries the environment that produced it, \
+                    as the frozen workload already is.",
+        backing: &["E6"] },
+    Promise { id: "N4", area: "Backup",
+        promise: "FeltDB does not provide an operator backup workflow. Backup and restore are library \
+                  primitives that something else must schedule and run.",
+        tier: Tier::NotCertified,
+        condition: "A command-line entry point with a contract test of its own.",
+        backing: &["B5"] },
+    Promise { id: "N5", area: "Monitoring",
+        promise: "FeltDB does not surface ancestry damage on its own. Damage is found when ancestry is \
+                  walked, and nothing walks it unprompted.",
+        tier: Tier::NotCertified,
+        condition: "A database-wide ancestry scan, and something that runs it on a schedule.",
+        backing: &["R4"] },
+    Promise { id: "N6", area: "Inspection",
+        promise: "FeltDB does not answer database-wide questions about history. Inspection is per resource.",
+        tier: Tier::NotCertified,
+        condition: "An aggregate across resources, so that \"is any ancestry anywhere damaged?\" does \
+                    not mean walking every revision.",
+        backing: &["O1"] },
+    Promise { id: "N7", area: "Health",
+        promise: "FeltDB does not certify the behaviour of its HTTP health and readiness endpoints. The \
+                  values they report are tested at the library boundary; the handlers that compose them \
+                  are not exercised.",
+        tier: Tier::NotCertified,
+        condition: "An HTTP-level harness covering both handlers, including the stalled-storage path.",
+        backing: &["O2", "M7"] },
+    Promise { id: "N8", area: "Health",
+        promise: "The `runtime`, `fabric`, `workflows` and `agents` fields of a health response are \
+                  compile-time constants and carry no information about the running system.",
+        tier: Tier::NotCertified,
+        condition: "An operational contract for each field, and then observation of it. Inventing those \
+                    contracts to fill the fields would repeat the defect being recorded.",
+        backing: &["O5"] },
+    Promise { id: "N9", area: "Operations",
+        promise: "FeltDB does not promise a latency bound, and does not promise that a compaction will \
+                  not block concurrent requests. Reads and writes are serialized behind a single lock, \
+                  the durable rewrite is deferred rather than eliminated, and no test in this repository \
+                  measures latency. That is a statement about the available evidence, not a prediction \
+                  about any particular deployment.",
+        tier: Tier::NotCertified,
+        condition: "Latency measured under load, and a compaction that does not hold the lock that \
+                    serializes every read and write.",
+        backing: &["M6"] },
+];
+
+/// What an operator has to do because FeltDB does not.
+///
+/// Every withheld claim lands here as work someone else owns. A gap that
+/// produced no obligation would be a gap nobody had to plan around, which is
+/// how a stated limitation quietly becomes an operational surprise.
+struct Obligation {
+    id: &'static str,
+    obligation: &'static str,
+    because: &'static [&'static str],
+}
+
+#[rustfmt::skip]
+const OBLIGATIONS: &[Obligation] = &[
+    Obligation { id: "G1",
+        obligation: "If the deployment can lose power, treat the most recent acknowledged writes as at \
+                     risk and size recovery accordingly. `Synced` narrows that window; nothing in this \
+                     repository closes it.",
+        because: &["D5"] },
+    Obligation { id: "G2",
+        obligation: "Schedule, run and retain backups yourself, and keep the verification step: FeltDB \
+                     will tell you a backup is sound, but only when asked.",
+        because: &["B5"] },
+    Obligation { id: "G3",
+        obligation: "Walk ancestry on a schedule if damage needs to be found before a reader stumbles on it.",
+        because: &["R4"] },
+    Obligation { id: "G4",
+        obligation: "Aggregate per-resource history yourself when the question is about the database \
+                     rather than about one resource.",
+        because: &["O1"] },
+    Obligation { id: "G5",
+        obligation: "Re-measure the workload envelope on the hardware you intend to run on, before sizing anything.",
+        because: &["E6"] },
+    Obligation { id: "G6",
+        obligation: "Do not select `Grouped` for throughput. Select it for the window it states.",
+        because: &["E7"] },
+    Obligation { id: "G7",
+        obligation: "Monitor request latency and refusal rate outside the database. FeltDB reports \
+                     neither, and a saturated instance answers `/health` normally.",
+        because: &["M6"] },
+    Obligation { id: "G8",
+        obligation: "Treat the HTTP health and readiness responses as unverified composition. Where \
+                     storage state matters, confirm it at the library boundary.",
+        because: &["O2", "M7"] },
+    Obligation { id: "G9",
+        obligation: "Ignore the `runtime`, `fabric`, `workflows` and `agents` fields of a health response.",
+        because: &["O5"] },
+];
+
+/// Certification claims that deliberately reach no promise, and why.
+///
+/// Enumerated rather than filtered, so the exemption cannot grow silently.
+const OUTSIDE_THE_CONTRACT: &[(&str, &str)] = &[(
+    "U2",
+    "Not Applicable: there is no pre-model revision history to migrate, so there is nothing to \
+     promise or withhold about migrating it.",
+)];
+
+// ===========================================================================
+// The certification, read rather than restated
+// ===========================================================================
+
+struct Claim {
+    status: String,
+    kind: String,
+}
+
+/// Parse the certification matrix out of its own source.
+///
+/// Reading the Rust rather than the published document is deliberate: the
+/// document is checked against the matrix by a different test binary, and a
+/// contract that depended on that check would silently lose its footing if the
+/// check were ever removed.
+fn certification() -> BTreeMap<String, Claim> {
+    let source = include_str!("production_certification.rs");
+    let start = source
+        .find("const CERTIFICATION")
+        .expect("the certification declares CERTIFICATION");
+    let end = start
+        + source[start..]
+            .find("\n];")
+            .expect("the certification table terminates");
+    let table = &source[start..end];
+
+    let mut claims = BTreeMap::new();
+    for chunk in table.split("Claim {").skip(1) {
+        let id = quoted_after(chunk, "id: \"").expect("every claim has an id");
+        let status = word_after(chunk, "status: Status::").expect("every claim has a status");
+        let kind = word_after(chunk, "kind: Evidence::").expect("every claim has an evidence kind");
+        assert!(
+            claims
+                .insert(id.to_string(), Claim { status, kind })
+                .is_none(),
+            "{id} appears twice in the certification"
+        );
+    }
+    assert!(
+        claims.len() > 50,
+        "the certification did not parse; it yielded {} claims",
+        claims.len()
+    );
+    claims
+}
+
+fn quoted_after<'a>(chunk: &'a str, key: &str) -> Option<&'a str> {
+    let rest = &chunk[chunk.find(key)? + key.len()..];
+    Some(&rest[..rest.find('"')?])
+}
+
+fn word_after(chunk: &str, key: &str) -> Option<String> {
+    let rest = &chunk[chunk.find(key)? + key.len()..];
+    Some(
+        rest.chars()
+            .take_while(|character| character.is_alphanumeric())
+            .collect(),
+    )
+}
+
+fn contract() -> BTreeMap<&'static str, &'static Promise> {
+    CONTRACT
+        .iter()
+        .map(|promise| (promise.id, promise))
+        .collect()
+}
+
+// ===========================================================================
+// The tripwires
+// ===========================================================================
+
+/// Every promise rests on claims that exist, and no promise rests on nothing.
+#[test]
+fn every_promise_names_backing_that_exists() {
+    let certified = certification();
+    let mut problems = Vec::new();
+
+    for promise in CONTRACT {
+        if promise.backing.is_empty() {
+            problems.push(format!(
+                "{}: promises something and names no claim",
+                promise.id
+            ));
+        }
+        for id in promise.backing {
+            if !certified.contains_key(*id) {
+                problems.push(format!(
+                    "{}: rests on `{id}`, which is not a certification claim",
+                    promise.id
+                ));
+            }
+        }
+    }
+
+    assert!(problems.is_empty(), "{}", problems.join("\n"));
+}
+
+/// **A promise may not be stronger than its evidence.**
+///
+/// This is the whole mechanism. A `Certified` or `Conditional` promise requires
+/// every backing claim to be `Proven`; a `Not certified` entry requires at least
+/// one that is not. Wanting to promise something more is not a way to promise
+/// it — the only route is to prove a claim, which means writing a test.
+#[test]
+fn a_promises_tier_is_derived_from_its_evidence() {
+    let certified = certification();
+    let mut problems = Vec::new();
+
+    for promise in CONTRACT {
+        let statuses: Vec<&str> = promise
+            .backing
+            .iter()
+            .filter_map(|id| certified.get(*id))
+            .map(|claim| claim.status.as_str())
+            .collect();
+
+        let unproven: Vec<&&str> = promise
+            .backing
+            .iter()
+            .filter(|id| {
+                certified
+                    .get(**id)
+                    .map(|claim| claim.status != "Proven")
+                    .unwrap_or(false)
+            })
+            .collect();
+
+        match promise.tier {
+            Tier::Certified | Tier::Conditional if !unproven.is_empty() => problems.push(format!(
+                "{} is published as `{}` and rests on {unproven:?}, which {} not Proven",
+                promise.id,
+                promise.tier.label(),
+                if unproven.len() == 1 { "is" } else { "are" }
+            )),
+            Tier::NotCertified if unproven.is_empty() => problems.push(format!(
+                "{} is published as `Not certified` and every claim it names is Proven ({statuses:?}); \
+                 either promise it or point it at the gap",
+                promise.id
+            )),
+            _ => {}
+        }
+    }
+
+    assert!(problems.is_empty(), "{}", problems.join("\n"));
+}
+
+/// A promise we make must not rest on someone having read the implementation.
+///
+/// `inspection_alone_never_proves_a_behavioural_claim` already stops inspection
+/// from producing a `Proven` claim. This is the same rule one level up, so that
+/// a promise cannot inherit inspection through a chain of ids.
+#[test]
+fn no_promise_rests_on_implementation_inspection() {
+    let certified = certification();
+    for promise in CONTRACT {
+        if !promise.tier.promises() {
+            continue;
+        }
+        for id in promise.backing {
+            let claim = &certified[*id];
+            assert_ne!(
+                claim.kind, "ImplementationInspection",
+                "{} promises something backed by `{id}`, which rests on inspection",
+                promise.id
+            );
+        }
+    }
+}
+
+/// A conditional promise states its condition; a withheld one states what would
+/// change the answer. Only an unconditional promise may say nothing further.
+#[test]
+fn every_qualified_promise_states_its_qualification() {
+    for promise in CONTRACT {
+        match promise.tier {
+            Tier::Certified => assert!(
+                promise.condition.is_empty(),
+                "{} is Certified and carries a condition; it belongs in Conditional",
+                promise.id
+            ),
+            Tier::Conditional | Tier::NotCertified => assert!(
+                !promise.condition.trim().is_empty(),
+                "{} is `{}` and states no qualification",
+                promise.id,
+                promise.tier.label()
+            ),
+        }
+    }
+}
+
+/// **Every claim reaches the contract, or is exempted by name.**
+///
+/// Coverage in the direction that matters: a claim the certification withholds
+/// must not simply be left out of the public document. Silence about a gap
+/// reads as an absence of the gap.
+#[test]
+fn every_certification_claim_reaches_the_contract() {
+    let certified = certification();
+    let mentioned: BTreeSet<&str> = CONTRACT
+        .iter()
+        .flat_map(|promise| promise.backing.iter().copied())
+        .collect();
+
+    let mut missing = Vec::new();
+    for (id, claim) in &certified {
+        if mentioned.contains(id.as_str()) {
+            continue;
+        }
+        match OUTSIDE_THE_CONTRACT.iter().find(|(exempt, _)| exempt == id) {
+            Some((_, reason)) => assert!(
+                !reason.trim().is_empty(),
+                "{id} is exempted from the contract with no reason"
+            ),
+            None => missing.push(format!("{id} ({})", claim.status)),
+        }
+    }
+    missing.sort();
+
+    assert!(
+        missing.is_empty(),
+        "certified and absent from the contract: {}",
+        missing.join(", ")
+    );
+
+    for (id, _) in OUTSIDE_THE_CONTRACT {
+        assert!(
+            certified.contains_key(*id),
+            "{id} is exempted from a contract it was never in"
+        );
+        assert!(
+            !mentioned.contains(id),
+            "{id} is exempted and also named by a promise"
+        );
+    }
+}
+
+/// **Every gap becomes somebody's job.**
+///
+/// A claim that is not `Proven` is work FeltDB is not doing. If nothing else
+/// picks it up, the limitation is real and invisible at the same time — the
+/// worst combination. So each one must produce at least one operator
+/// obligation.
+#[test]
+fn every_withheld_claim_creates_an_operator_obligation() {
+    let certified = certification();
+    let excused: BTreeSet<&str> = OUTSIDE_THE_CONTRACT.iter().map(|(id, _)| *id).collect();
+    let owned: BTreeSet<&str> = OBLIGATIONS
+        .iter()
+        .flat_map(|obligation| obligation.because.iter().copied())
+        .collect();
+
+    let mut orphaned = Vec::new();
+    for (id, claim) in &certified {
+        let withheld = claim.status == "Unproven" || claim.status == "PartiallyProven";
+        if withheld && !excused.contains(id.as_str()) && !owned.contains(id.as_str()) {
+            orphaned.push(format!("{id} ({})", claim.status));
+        }
+    }
+    orphaned.sort();
+
+    assert!(
+        orphaned.is_empty(),
+        "withheld and nobody's job: {}",
+        orphaned.join(", ")
+    );
+
+    for obligation in OBLIGATIONS {
+        assert!(
+            !obligation.because.is_empty(),
+            "{} is an obligation with no cause",
+            obligation.id
+        );
+        for id in obligation.because {
+            let claim = certified
+                .get(*id)
+                .unwrap_or_else(|| panic!("{} cites `{id}`, which is not a claim", obligation.id));
+            assert_ne!(
+                claim.status, "Proven",
+                "{} makes an operator responsible for `{id}`, which FeltDB proves",
+                obligation.id
+            );
+        }
+    }
+}
+
+/// **A promise reads as a promise; a refusal reads as a refusal.**
+///
+/// Hedging inside a promise is how an unconditional guarantee gets quietly
+/// weakened after the fact, and guarantee-language inside a withheld one is how
+/// a gap gets quietly read as a feature. Both are wording failures that no
+/// status check would catch.
+///
+/// The hedge rule applies to the promise itself and **not** to its condition.
+/// Describing what a promise does not cover is exactly where words like "may"
+/// belong: `Grouped`'s condition says up to `every - 1` acknowledged writes may
+/// not yet have been through a barrier, and that sentence is precise, not
+/// evasive. Forbidding it there would push the condition towards vaguer wording
+/// to satisfy a check — the opposite of the intent.
+#[test]
+fn a_promise_does_not_hedge_and_a_refusal_does_not_guarantee() {
+    let hedges = [
+        " may ",
+        " might ",
+        " should ",
+        " typically",
+        " generally",
+        " usually",
+        "best effort",
+        "best-effort",
+        " aims to ",
+        " tries to ",
+        " intended to ",
+    ];
+    let guarantees = [
+        "guarantees that",
+        "is guaranteed",
+        "is certified",
+        "we promise",
+    ];
+
+    let mut problems = Vec::new();
+    for promise in CONTRACT {
+        let text = format!("{} {}", promise.promise, promise.condition).to_lowercase();
+        if promise.tier.promises() {
+            let promised = promise.promise.to_lowercase();
+            for hedge in hedges {
+                if promised.contains(hedge) {
+                    problems.push(format!(
+                        "{} is `{}` and hedges with \"{}\"",
+                        promise.id,
+                        promise.tier.label(),
+                        hedge.trim()
+                    ));
+                }
+            }
+        } else {
+            for guarantee in guarantees {
+                if common::asserts_phrase(&text, guarantee) {
+                    problems.push(format!(
+                        "{} is `Not certified` and asserts \"{guarantee}\"",
+                        promise.id
+                    ));
+                }
+            }
+        }
+    }
+
+    assert!(problems.is_empty(), "{}", problems.join("\n"));
+}
+
+// ===========================================================================
+// The published contract
+// ===========================================================================
+
+fn published_document() -> String {
+    let path = concat!(
+        env!("CARGO_MANIFEST_DIR"),
+        "/../../docs/architecture/production-contract.md"
+    );
+    std::fs::read_to_string(path).expect("the contract document exists and is readable")
+}
+
+/// **The published contract is a rendering, not a retelling.**
+///
+/// Every promise appears with the same tier and the same backing. A promise
+/// that exists only in the document, or a tier that differs between the two,
+/// fails here — which is the case this whole file exists to prevent.
+#[test]
+fn the_published_contract_matches_the_executable_contract() {
+    let document = published_document();
+    let promised = contract();
+
+    let mut rows: BTreeMap<String, (String, String)> = BTreeMap::new();
+    for line in document.lines() {
+        let Some(cells) = common::table_cells(line) else {
+            continue;
+        };
+        // id | area | promise | tier | condition | backing
+        if cells.len() != 6 {
+            continue;
+        }
+        let id = cells[0].clone();
+        let looks_like_an_id = id.len() >= 2
+            && (id.starts_with('P') || id.starts_with('N'))
+            && id[1..].chars().all(|c| c.is_ascii_digit());
+        if !looks_like_an_id {
+            continue;
+        }
+        assert!(
+            rows.insert(id.clone(), (cells[3].clone(), cells[5].clone()))
+                .is_none(),
+            "the document publishes `{id}` more than once"
+        );
+    }
+
+    let mut problems = Vec::new();
+    for promise in CONTRACT {
+        match rows.get(promise.id) {
+            None => problems.push(format!("{}: absent from the document", promise.id)),
+            Some((tier, backing)) => {
+                if tier != promise.tier.label() {
+                    problems.push(format!(
+                        "{}: the document publishes `{tier}`, the contract says `{}`",
+                        promise.id,
+                        promise.tier.label()
+                    ));
+                }
+                let expected = promise.backing.join(", ");
+                let published: String = backing.replace('`', "");
+                if published != expected {
+                    problems.push(format!(
+                        "{}: the document rests it on `{published}`, the contract rests it on `{expected}`",
+                        promise.id
+                    ));
+                }
+            }
+        }
+    }
+    for id in rows.keys() {
+        if !promised.contains_key(id.as_str()) {
+            problems.push(format!("{id}: in the document, absent from the contract"));
+        }
+    }
+
+    assert!(problems.is_empty(), "{}", problems.join("\n"));
+}
+
+/// Every tier is published, including an empty one, so a bucket cannot vanish
+/// from the document because it was inconvenient.
+#[test]
+fn the_published_contract_publishes_every_tier() {
+    let document = published_document();
+    for tier in Tier::ALL {
+        assert!(
+            document.contains(tier.label()),
+            "the contract document never mentions `{}`",
+            tier.label()
+        );
+    }
+    for obligation in OBLIGATIONS {
+        assert!(
+            document.contains(obligation.id),
+            "{} is an operator obligation the document does not publish",
+            obligation.id
+        );
+    }
+}
+
+/// The contract document is held to the same rule as every other document: it
+/// may name a withheld guarantee, and may not assert one.
+#[test]
+fn the_contract_document_asserts_nothing_the_certification_withholds() {
+    let forbidden = [
+        "power-loss safe",
+        "power loss safe",
+        "guaranteed durable",
+        "compaction is non-blocking",
+        "compaction no longer blocks",
+        "all reads are bounded",
+        "supported capacity",
+    ];
+
+    let prose = common::prose_excluding_withheld_rows(&published_document(), &["Not certified"]);
+    let mut violations = Vec::new();
+    for phrase in forbidden {
+        if common::asserts_phrase(&prose, phrase) {
+            violations.push(format!("the contract asserts \"{phrase}\""));
+        }
+    }
+    assert!(violations.is_empty(), "{}", violations.join("\n"));
+}