@feltdb/core 0.13.0 → 0.16.0

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

@@ -1,1188 +0,0 @@
-//! `AgentState` against the real transaction mechanism.
-//!
-//! `agent_transition_contract_conformance.rs` shows what the contract decides.
-//! These tests show the other half of the acceptance criterion: that the
-//! production operation (a) really does take its decisions from the contract,
-//! and (b) commits them through the guarded transaction so that a decision
-//! cannot outlive the state it was made against -- under real threads, a real
-//! file-backed store and a real restart.
-//!
-//! Sequential replay cannot show (b). Two threads that both read the same open
-//! handoff both decide "commit"; only the guarded commit can make one of them
-//! lose, and these tests are where that is demonstrated.
-
-use feltdb::agent_state::{AgentState, AgentStateError, Applied, AuthorityClock};
-use feltdb::agent_transition_contract::{ErrorCode, Operation};
-use feltdb::{AtomicMutation, FeltDb, PreconditionFailure, RecordPrecondition};
-use serde_json::{json, Value};
-use std::sync::atomic::{AtomicU64, Ordering};
-use std::sync::{Arc, Barrier};
-use std::thread;
-use std::time::Duration;
-use tempfile::TempDir;
-
-fn op(value: Value) -> Operation {
-    serde_json::from_value(value).expect("a well-formed operation")
-}
-
-fn open(dir: &TempDir) -> FeltDb {
-    FeltDb::open(dir.path().join("agents.log")).expect("open")
-}
-
-fn unique() -> String {
-    static NEXT: AtomicU64 = AtomicU64::new(0);
-    format!(
-        "{}-{}",
-        std::process::id(),
-        NEXT.fetch_add(1, Ordering::SeqCst)
-    )
-}
-
-/// Writes an external record the way a tool would: created, or bumped by one.
-fn write_external(db: &FeltDb, collection: &str, id: &str) {
-    let key = format!("{collection}:{id}");
-    let (precondition, value) = match db.get_value(&key).unwrap() {
-        None => (
-            RecordPrecondition {
-                capability: collection.into(),
-                key: key.clone(),
-                require_absent: true,
-                ..Default::default()
-            },
-            json!({"seeded": true}),
-        ),
-        Some(current) => (
-            RecordPrecondition {
-                capability: collection.into(),
-                key: key.clone(),
-                expected_version: Some(
-                    current
-                        .get("__version")
-                        .and_then(Value::as_u64)
-                        .unwrap_or(1),
-                ),
-                ..Default::default()
-            },
-            json!({"seeded": true, "again": true}),
-        ),
-    };
-    db.apply_atomic_transaction_guarded(
-        &format!("seed-{}", unique()),
-        None,
-        None,
-        &[],
-        &[precondition],
-        &[AtomicMutation {
-            capability: collection.into(),
-            key,
-            value: Some(value),
-        }],
-        None,
-    )
-    .expect("seed");
-}
-
-fn create(task: &str, actor: &str, lease: &str, lease_ms: u64) -> Operation {
-    op(
-        json!({"op": "create_task", "task_id": task, "actor": actor, "objective": "Ship it", "lease_id": lease, "lease_ms": lease_ms}),
-    )
-}
-fn checkpoint(
-    task: &str,
-    actor: &str,
-    fence: u64,
-    lease: &str,
-    version: u64,
-    status: Option<&str>,
-    evidence: Value,
-) -> Operation {
-    let mut o = json!({"op": "checkpoint", "task_id": task, "actor": actor, "fence": fence, "lease_id": lease, "expected_version": version, "summary": "progress", "evidence": evidence});
-    if let Some(status) = status {
-        o["status"] = json!(status);
-    }
-    op(o)
-}
-fn intent(task: &str, actor: &str, fence: u64, lease: &str, key: &str) -> Operation {
-    op(
-        json!({"op": "record_intent", "task_id": task, "actor": actor, "fence": fence, "lease_id": lease, "idempotency_key": key, "action": "charge-card"}),
-    )
-}
-fn reconcile(
-    task: &str,
-    actor: &str,
-    fence: u64,
-    lease: &str,
-    key: &str,
-    evidence: Value,
-) -> Operation {
-    op(
-        json!({"op": "reconcile", "task_id": task, "actor": actor, "fence": fence, "lease_id": lease, "idempotency_key": key, "conclusion": "executed", "evidence": evidence}),
-    )
-}
-fn acquire(task: &str, actor: &str, lease: &str, lease_ms: u64) -> Operation {
-    op(
-        json!({"op": "acquire", "task_id": task, "actor": actor, "lease_id": lease, "lease_ms": lease_ms}),
-    )
-}
-fn offer(task: &str, actor: &str, fence: u64, lease: &str) -> Operation {
-    op(
-        json!({"op": "create_handoff", "task_id": task, "handoff_id": "h1", "actor": actor, "fence": fence, "lease_id": lease}),
-    )
-}
-fn claim(who: &str, lease: &str) -> Operation {
-    op(
-        json!({"op": "claim_handoff", "handoff_id": "h1", "claimant": who, "lease_id": lease, "lease_ms": 60000}),
-    )
-}
-fn receipt() -> Value {
-    json!([{"kind": "record", "collection": "receipts", "id": "r1"}])
-}
-
-fn expect_refused(result: Result<Applied, AgentStateError>, code: ErrorCode) {
-    match result {
-        Err(AgentStateError::Refused(actual)) => assert_eq!(actual, code),
-        other => panic!("expected {}, got {other:?}", code.as_str()),
-    }
-}
-
-fn version_of(state: &AgentState, collection: &str, id: &str) -> u64 {
-    state
-        .read(collection, id)
-        .unwrap()
-        .map(|(v, _)| v)
-        .unwrap_or(0)
-}
-
-// ---------------------------------------------------------------------------
-// Lifecycle, durability and restart
-// ---------------------------------------------------------------------------
-
-#[test]
-fn a_lifecycle_commits_through_the_real_store() {
-    let dir = TempDir::new().unwrap();
-    let state = AgentState::new(open(&dir));
-
-    state.apply(&create("t1", "agent-a", "L1", 60_000)).unwrap();
-    assert_eq!(
-        version_of(&state, "_feltdb.AgentTask", "t1"),
-        1,
-        "a create writes version 1"
-    );
-    state
-        .apply(&checkpoint(
-            "t1",
-            "agent-a",
-            1,
-            "L1",
-            1,
-            Some("running"),
-            json!([]),
-        ))
-        .unwrap();
-    assert_eq!(
-        version_of(&state, "_feltdb.AgentTask", "t1"),
-        2,
-        "a fenced write stores N + 1"
-    );
-    state
-        .apply(&intent("t1", "agent-a", 1, "L1", "charge-1"))
-        .unwrap();
-
-    // The store holds exactly what the contract said, with the authority's version.
-    let (version, task) = state.read("_feltdb.AgentTask", "t1").unwrap().unwrap();
-    assert_eq!(version, 3);
-    assert_eq!(task["status"], "running");
-    assert_eq!(task["unresolved_intents"], 1);
-    let (_, stored_intent) = state
-        .read("_feltdb.AgentIntent", "t1~charge-1")
-        .unwrap()
-        .unwrap();
-    assert_eq!(stored_intent["state"], "intended");
-    assert_eq!(stored_intent["verified"], false);
-
-    // A repeat is a recognized no-op, not a second commit.
-    assert_eq!(
-        state.apply(&create("t1", "agent-a", "L1", 60_000)).unwrap(),
-        Applied::Noop
-    );
-    assert_eq!(version_of(&state, "_feltdb.AgentTask", "t1"), 3);
-}
-
-#[test]
-fn state_and_uncertainty_survive_a_restart() {
-    let dir = TempDir::new().unwrap();
-    {
-        let state = AgentState::new(open(&dir));
-        state
-            .apply(&create("t1", "agent-a", "L1", 600_000))
-            .unwrap();
-        state
-            .apply(&checkpoint(
-                "t1",
-                "agent-a",
-                1,
-                "L1",
-                1,
-                Some("running"),
-                json!([]),
-            ))
-            .unwrap();
-        // The side effect would happen here. The process dies before an outcome is recorded.
-        state
-            .apply(&intent("t1", "agent-a", 1, "L1", "charge-1"))
-            .unwrap();
-    }
-
-    let db = open(&dir);
-    let state = AgentState::new(db.clone());
-    let (_, task) = state
-        .read("_feltdb.AgentTask", "t1")
-        .unwrap()
-        .expect("the task survived");
-    assert_eq!(task["unresolved_intents"], 1);
-
-    // The recovered process may not treat the action as unstarted...
-    expect_refused(
-        state.apply(&intent("t1", "agent-a", 1, "L1", "charge-1")),
-        ErrorCode::OutcomeUncertain,
-    );
-    // ...nor finish the task around it, even with evidence in hand.
-    write_external(&db, "receipts", "r1");
-    expect_refused(
-        state.apply(&checkpoint(
-            "t1",
-            "agent-a",
-            1,
-            "L1",
-            2,
-            Some("completed"),
-            receipt(),
-        )),
-        ErrorCode::OutcomeUncertain,
-    );
-    // Evidence, and only evidence, settles it; then the task can finish.
-    state
-        .apply(&reconcile("t1", "agent-a", 1, "L1", "charge-1", receipt()))
-        .unwrap();
-    state
-        .apply(&checkpoint(
-            "t1",
-            "agent-a",
-            1,
-            "L1",
-            2,
-            Some("completed"),
-            receipt(),
-        ))
-        .unwrap();
-    let (_, task) = state.read("_feltdb.AgentTask", "t1").unwrap().unwrap();
-    assert_eq!(task["status"], "completed");
-    assert!(task["lease"].is_null());
-
-    // The terminal state survives another restart, and stays terminal.
-    drop(state);
-    drop(db);
-    let state = AgentState::new(open(&dir));
-    expect_refused(
-        state.apply(&checkpoint("t1", "agent-a", 1, "L1", 3, None, json!([]))),
-        ErrorCode::Terminal,
-    );
-    expect_refused(
-        state.apply(&acquire("t1", "agent-b", "L2", 1000)),
-        ErrorCode::Terminal,
-    );
-}
-
-/// Every step of every committed sequence, run through the real store with an
-/// injected clock, must come out as the corpus says. The decisions here are the
-/// contract's; the only thing this module adds is the store.
-#[test]
-fn the_production_path_reproduces_the_committed_sequences() {
-    struct Manual(AtomicU64);
-    impl AuthorityClock for Manual {
-        fn now_ms(&self) -> u64 {
-            self.0.load(Ordering::SeqCst)
-        }
-    }
-    let corpus: Value = serde_json::from_slice(
-        &std::fs::read(concat!(
-            env!("CARGO_MANIFEST_DIR"),
-            "/tests/fixtures/agent_transition_corpus.json"
-        ))
-        .unwrap(),
-    )
-    .unwrap();
-    // Logical time floats an hour above the real clock, so a lease the contract
-    // grants is also alive on the real clock the commit-time predicate uses.
-    let clock_db = FeltDb::open(TempDir::new().unwrap().path().join("clock.log")).unwrap();
-    let base = clock_db.authority_time_ms() + 3_600_000;
-    let mut steps = 0;
-    for sequence in corpus["sequences"].as_array().unwrap() {
-        let dir = TempDir::new().unwrap();
-        let db = open(&dir);
-        let clock = Arc::new(Manual(AtomicU64::new(base)));
-        let state = AgentState::with_clock(db.clone(), clock.clone());
-        for step in sequence["steps"].as_array().unwrap() {
-            let label = format!(
-                "{}/{}",
-                sequence["name"].as_str().unwrap(),
-                step["label"].as_str().unwrap()
-            );
-            for seed in step["seed"].as_array().into_iter().flatten() {
-                write_external(
-                    &db,
-                    seed["collection"].as_str().unwrap(),
-                    seed["id"].as_str().unwrap(),
-                );
-            }
-            clock
-                .0
-                .store(base + step["now_ms"].as_u64().unwrap(), Ordering::SeqCst);
-            let expected: Value =
-                serde_json::from_str(step["expected_output"].as_str().unwrap()).unwrap();
-            let result = state.apply(&op(step["operation"].clone()));
-            match (
-                &result,
-                expected["error"]["code"].as_str(),
-                expected["outcome"]["kind"].as_str(),
-            ) {
-                (Err(AgentStateError::Refused(actual)), Some(code), _) => {
-                    assert_eq!(actual.as_str(), code, "{label}")
-                }
-                (Ok(Applied::Noop), None, Some("noop")) => {}
-                (Ok(Applied::Committed(written)), None, Some("commit")) => {
-                    let expected_ids: Vec<String> = expected["outcome"]["writes"]
-                        .as_array()
-                        .unwrap()
-                        .iter()
-                        .map(|w| {
-                            format!(
-                                "{}/{}",
-                                w["collection"].as_str().unwrap(),
-                                w["id"].as_str().unwrap()
-                            )
-                        })
-                        .collect();
-                    let ids: Vec<String> = written
-                        .iter()
-                        .map(|w| format!("{}/{}", w.collection, w.id))
-                        .collect();
-                    assert_eq!(ids, expected_ids, "{label}");
-                    // The stored record is the contract's value, field for field
-                    // except for times, which are offset from the injected clock.
-                    for write in expected["outcome"]["writes"].as_array().unwrap() {
-                        let (_, stored) = state
-                            .read(
-                                write["collection"].as_str().unwrap(),
-                                write["id"].as_str().unwrap(),
-                            )
-                            .unwrap()
-                            .unwrap();
-                        for field in [
-                            "status",
-                            "fence",
-                            "owner",
-                            "state",
-                            "checkpoint_version",
-                            "unresolved_intents",
-                            "verified",
-                            "claimant",
-                            "claimed_fence",
-                        ] {
-                            assert_eq!(
-                                stored.get(field),
-                                write["value"].get(field),
-                                "{label}: {field}"
-                            );
-                        }
-                    }
-                }
-                other => panic!("{label}: got {other:?}, the corpus says {expected}"),
-            }
-            steps += 1;
-        }
-    }
-    assert!(
-        steps >= 100,
-        "the replay should cover the whole corpus, covered {steps}"
-    );
-}
-
-// ---------------------------------------------------------------------------
-// The guarded commit, under contention and against stale decisions
-// ---------------------------------------------------------------------------
-
-type Job = Box<dyn FnOnce() -> Result<Applied, AgentStateError> + Send>;
-
-fn setup_open_handoff(dir: &TempDir) -> AgentState {
-    let state = AgentState::new(open(dir));
-    state
-        .apply(&create("t1", "agent-a", "L1", 600_000))
-        .unwrap();
-    state
-        .apply(&checkpoint(
-            "t1",
-            "agent-a",
-            1,
-            "L1",
-            1,
-            Some("running"),
-            json!([]),
-        ))
-        .unwrap();
-    state.apply(&offer("t1", "agent-a", 1, "L1")).unwrap();
-    state
-}
-
-/// Runs `jobs` simultaneously, releasing them together.
-fn race(jobs: Vec<Job>) -> Vec<Result<Applied, AgentStateError>> {
-    let barrier = Arc::new(Barrier::new(jobs.len()));
-    let handles: Vec<_> = jobs
-        .into_iter()
-        .map(|job| {
-            let barrier = barrier.clone();
-            thread::spawn(move || {
-                barrier.wait();
-                job()
-            })
-        })
-        .collect();
-    handles
-        .into_iter()
-        .map(|h| h.join().expect("no thread panicked"))
-        .collect()
-}
-
-fn job(state: &AgentState, operation: Operation) -> Job {
-    let state = state.clone();
-    Box::new(move || state.apply(&operation))
-}
-
-/// (committed, conflicts, refused). Anything else -- a storage failure -- fails the test.
-fn classify(results: &[Result<Applied, AgentStateError>]) -> (usize, usize, usize) {
-    let (mut committed, mut conflicts, mut refused) = (0, 0, 0);
-    for result in results {
-        match result {
-            Ok(Applied::Committed(_)) => committed += 1,
-            Err(AgentStateError::Conflict(_)) => conflicts += 1,
-            Err(AgentStateError::Refused(_)) => refused += 1,
-            other => panic!("unexpected outcome: {other:?}"),
-        }
-    }
-    (committed, conflicts, refused)
-}
-
-#[test]
-fn exactly_one_of_many_concurrent_claims_wins() {
-    let mut conflicts_seen = 0;
-    for round in 0..40 {
-        let dir = TempDir::new().unwrap();
-        let state = setup_open_handoff(&dir);
-        let (handoff_before, task_before) = (
-            version_of(&state, "_feltdb.AgentHandoff", "h1"),
-            version_of(&state, "_feltdb.AgentTask", "t1"),
-        );
-        let claimants = [
-            "agent-b", "agent-c", "agent-d", "agent-e", "agent-f", "agent-g", "agent-h", "agent-i",
-        ];
-        // The handoff is addressed to agent-b only if `to` is set; ours is open to anyone.
-        let jobs: Vec<Job> = claimants
-            .iter()
-            .map(|who| job(&state, claim(who, &format!("lease-{who}"))))
-            .collect();
-        let results = race(jobs);
-        let (committed, conflicts, refused) = classify(&results);
-        conflicts_seen += conflicts;
-        assert_eq!(committed, 1, "round {round}: exactly one claim commits");
-        assert_eq!(committed + conflicts + refused, claimants.len());
-        // One winner, one set of effects.
-        let (_, handoff) = state.read("_feltdb.AgentHandoff", "h1").unwrap().unwrap();
-        let (_, task) = state.read("_feltdb.AgentTask", "t1").unwrap().unwrap();
-        assert_eq!(handoff["status"], "claimed");
-        assert_eq!(
-            handoff["claimant"], task["owner"],
-            "the task and the handoff name the same winner"
-        );
-        assert_eq!(task["fence"], 2, "the fence advanced exactly once");
-        assert_eq!(
-            version_of(&state, "_feltdb.AgentHandoff", "h1"),
-            handoff_before + 1
-        );
-        assert_eq!(
-            version_of(&state, "_feltdb.AgentTask", "t1"),
-            task_before + 1
-        );
-    }
-    // A run that never lost a race at the guard would prove nothing about the guard.
-    assert!(
-        conflicts_seen > 0,
-        "no thread ever reached the guarded commit and lost: the race was not exercised"
-    );
-}
-
-#[test]
-fn exactly_one_of_many_concurrent_acquires_after_expiry_wins() {
-    for round in 0..25 {
-        let dir = TempDir::new().unwrap();
-        let state = AgentState::new(open(&dir));
-        state.apply(&create("t1", "agent-a", "L1", 1)).unwrap();
-        thread::sleep(Duration::from_millis(15));
-        let jobs: Vec<Job> = (0..8)
-            .map(|i| {
-                job(
-                    &state,
-                    acquire("t1", &format!("agent-{i}"), &format!("lease-{i}"), 600_000),
-                )
-            })
-            .collect();
-        let (committed, _, _) = classify(&race(jobs));
-        assert_eq!(
-            committed, 1,
-            "round {round}: exactly one acquisition commits"
-        );
-        let (_, task) = state.read("_feltdb.AgentTask", "t1").unwrap().unwrap();
-        assert_eq!(task["fence"], 2, "the fence advanced exactly once");
-    }
-}
-
-#[test]
-fn concurrent_checkpoints_on_one_version_commit_once() {
-    for round in 0..40 {
-        let dir = TempDir::new().unwrap();
-        let state = AgentState::new(open(&dir));
-        state
-            .apply(&create("t1", "agent-a", "L1", 600_000))
-            .unwrap();
-        let jobs: Vec<Job> = (0..6)
-            .map(|_| {
-                job(
-                    &state,
-                    checkpoint("t1", "agent-a", 1, "L1", 1, Some("running"), json!([])),
-                )
-            })
-            .collect();
-        let (committed, _, _) = classify(&race(jobs));
-        assert_eq!(committed, 1, "round {round}");
-        let (_, task) = state.read("_feltdb.AgentTask", "t1").unwrap().unwrap();
-        assert_eq!(task["checkpoint_version"], 2);
-        assert!(state
-            .read("_feltdb.AgentCheckpoint", "t1~v2")
-            .unwrap()
-            .is_some());
-        assert!(
-            state
-                .read("_feltdb.AgentCheckpoint", "t1~v3")
-                .unwrap()
-                .is_none(),
-            "no second checkpoint slipped in"
-        );
-    }
-}
-
-// ---------------------------------------------------------------------------
-// Intents under contention: uncertainty is counted exactly, never lost
-// ---------------------------------------------------------------------------
-
-/// A running task owned by agent-a (fence 1, lease L1, checkpoint version 2),
-/// with an external receipt that can be cited as evidence.
-fn setup_running_with_receipt(dir: &TempDir) -> (FeltDb, AgentState) {
-    let db = open(dir);
-    let state = AgentState::new(db.clone());
-    state
-        .apply(&create("t1", "agent-a", "L1", 600_000))
-        .unwrap();
-    state
-        .apply(&checkpoint(
-            "t1",
-            "agent-a",
-            1,
-            "L1",
-            1,
-            Some("running"),
-            json!([]),
-        ))
-        .unwrap();
-    write_external(&db, "receipts", "r1");
-    (db, state)
-}
-
-fn outcome(
-    task: &str,
-    actor: &str,
-    fence: u64,
-    lease: &str,
-    key: &str,
-    evidence: Value,
-) -> Operation {
-    op(
-        json!({"op": "record_outcome", "task_id": task, "actor": actor, "fence": fence, "lease_id": lease, "idempotency_key": key, "result": "succeeded", "evidence": evidence}),
-    )
-}
-
-fn task_value(state: &AgentState) -> Value {
-    state.read("_feltdb.AgentTask", "t1").unwrap().unwrap().1
-}
-
-/// Two workers that both believe they are first to attempt an action must not
-/// both record it: the intent is created once, and the task counts one
-/// unresolved action, not two.
-#[test]
-fn concurrent_intents_for_one_key_are_recorded_once() {
-    let mut conflicts_seen = 0;
-    for round in 0..40 {
-        let dir = TempDir::new().unwrap();
-        let (_, state) = setup_running_with_receipt(&dir);
-        let task_before = version_of(&state, "_feltdb.AgentTask", "t1");
-        let jobs: Vec<Job> = (0..6)
-            .map(|_| job(&state, intent("t1", "agent-a", 1, "L1", "charge-1")))
-            .collect();
-        let results = race(jobs);
-        let (committed, conflicts, refused) = classify(&results);
-        conflicts_seen += conflicts;
-        assert_eq!(committed, 1, "round {round}: the intent is recorded once");
-        for result in &results {
-            if let Err(AgentStateError::Refused(code)) = result {
-                // A worker that read the recorded intent learns the action may have run.
-                assert_eq!(*code, ErrorCode::OutcomeUncertain, "round {round}");
-            }
-        }
-        assert_eq!(committed + conflicts + refused, 6);
-        assert_eq!(task_value(&state)["unresolved_intents"], 1, "round {round}");
-        assert_eq!(
-            version_of(&state, "_feltdb.AgentTask", "t1"),
-            task_before + 1
-        );
-        assert_eq!(version_of(&state, "_feltdb.AgentIntent", "t1~charge-1"), 1);
-    }
-    assert!(
-        conflicts_seen > 0,
-        "no worker ever reached the guarded commit and lost: the race was not exercised"
-    );
-}
-
-/// An outcome report and a reconciliation of the same intent, racing, settle it
-/// exactly once. Settling twice would decrement the task's count of uncertain
-/// actions twice and let it understate what may have happened.
-#[test]
-fn concurrent_settlements_of_one_intent_resolve_it_once() {
-    let mut conflicts_seen = 0;
-    for round in 0..40 {
-        let dir = TempDir::new().unwrap();
-        let (_, state) = setup_running_with_receipt(&dir);
-        state
-            .apply(&intent("t1", "agent-a", 1, "L1", "charge-1"))
-            .unwrap();
-        assert_eq!(task_value(&state)["unresolved_intents"], 1);
-        let intent_before = version_of(&state, "_feltdb.AgentIntent", "t1~charge-1");
-        let jobs: Vec<Job> = (0..6)
-            .map(|i| {
-                job(
-                    &state,
-                    if i % 2 == 0 {
-                        outcome("t1", "agent-a", 1, "L1", "charge-1", receipt())
-                    } else {
-                        reconcile("t1", "agent-a", 1, "L1", "charge-1", receipt())
-                    },
-                )
-            })
-            .collect();
-        let results = race(jobs);
-        let (committed, conflicts, refused) = classify(&results);
-        conflicts_seen += conflicts;
-        assert_eq!(committed, 1, "round {round}: the intent is settled once");
-        assert_eq!(committed + conflicts + refused, 6);
-        for result in &results {
-            if let Err(AgentStateError::Refused(code)) = result {
-                assert_eq!(*code, ErrorCode::IntentResolved, "round {round}");
-            }
-        }
-        assert_eq!(
-            task_value(&state)["unresolved_intents"],
-            0,
-            "round {round}: counted down exactly once"
-        );
-        let (version, resolved) = state
-            .read("_feltdb.AgentIntent", "t1~charge-1")
-            .unwrap()
-            .unwrap();
-        assert_eq!(version, intent_before + 1, "round {round}");
-        assert_eq!(resolved["state"], "resolved");
-        assert_eq!(resolved["verified"], true);
-    }
-    assert!(
-        conflicts_seen > 0,
-        "no settlement ever reached the guarded commit and lost: the race was not exercised"
-    );
-}
-
-/// A completion racing a new intent: one of them commits, and a task is never
-/// left completed with an action whose outcome is unknown. The loser, deciding
-/// again, gets the contract's refusal for the state the winner produced.
-#[test]
-fn a_completion_cannot_race_past_a_new_intent() {
-    let (mut completions_won, mut intents_won) = (0, 0);
-    for round in 0..40 {
-        let dir = TempDir::new().unwrap();
-        let (_, state) = setup_running_with_receipt(&dir);
-        let complete = checkpoint("t1", "agent-a", 1, "L1", 2, Some("completed"), receipt());
-        let new_intent = intent("t1", "agent-a", 1, "L1", "charge-1");
-        let results = race(vec![
-            job(&state, complete.clone()),
-            job(&state, new_intent.clone()),
-        ]);
-        let (committed, _, _) = classify(&results);
-        assert_eq!(
-            committed, 1,
-            "round {round}: exactly one transition commits"
-        );
-
-        let task = task_value(&state);
-        assert!(
-            !(task["status"] == "completed" && task["unresolved_intents"] != 0),
-            "round {round}: a completed task carries an unresolved intent: {task}"
-        );
-        if task["status"] == "completed" {
-            completions_won += 1;
-            assert!(state
-                .read("_feltdb.AgentIntent", "t1~charge-1")
-                .unwrap()
-                .is_none());
-            expect_refused(state.apply(&new_intent), ErrorCode::Terminal);
-        } else {
-            intents_won += 1;
-            assert_eq!(task["unresolved_intents"], 1);
-            let (version, recorded) = state
-                .read("_feltdb.AgentIntent", "t1~charge-1")
-                .unwrap()
-                .expect("the winning intent is persisted");
-            assert_eq!((version, &recorded["state"]), (1, &json!("intended")));
-            expect_refused(state.apply(&complete), ErrorCode::OutcomeUncertain);
-            assert_eq!(task_value(&state)["status"], "running");
-        }
-    }
-    assert_eq!(completions_won + intents_won, 40);
-}
-
-/// The same race, decided before either commits: a completion and a new intent,
-/// each valid against the task as both read it, cannot both be committed. With
-/// both decisions prepared first, the contract has nothing left to refuse, so
-/// the only thing that can stop the second is the guarded commit.
-#[test]
-fn a_completion_and_a_new_intent_decided_together_cannot_both_commit() {
-    for round in 0..40 {
-        let dir = TempDir::new().unwrap();
-        let (_, state) = setup_running_with_receipt(&dir);
-        let complete = checkpoint("t1", "agent-a", 1, "L1", 2, Some("completed"), receipt());
-        let new_intent = intent("t1", "agent-a", 1, "L1", "charge-1");
-        let task_before = version_of(&state, "_feltdb.AgentTask", "t1");
-        let prepared_completion = state.prepare(&complete).unwrap();
-        let prepared_intent = state.prepare(&new_intent).unwrap();
-        let commit = |prepared: feltdb::agent_state::Prepared| -> Job {
-            let state = state.clone();
-            Box::new(move || state.commit(&prepared))
-        };
-        let results = race(vec![commit(prepared_completion), commit(prepared_intent)]);
-        let (committed, conflicts, refused) = classify(&results);
-        assert_eq!(
-            (committed, conflicts, refused),
-            (1, 1, 0),
-            "round {round}: one commit wins and the other loses at the guard"
-        );
-        for result in &results {
-            if let Err(AgentStateError::Conflict(failure)) = result {
-                assert!(
-                    matches!(failure, PreconditionFailure::Version { .. }),
-                    "round {round}: lost on the task's version: {failure:?}"
-                );
-            }
-        }
-        assert_eq!(
-            version_of(&state, "_feltdb.AgentTask", "t1"),
-            task_before + 1
-        );
-
-        let task = task_value(&state);
-        let recorded = state.read("_feltdb.AgentIntent", "t1~charge-1").unwrap();
-        if results[0].is_ok() {
-            assert_eq!(task["status"], "completed", "round {round}");
-            assert_eq!(task["unresolved_intents"], 0, "round {round}");
-            assert!(
-                recorded.is_none(),
-                "round {round}: the losing intent wrote nothing"
-            );
-            expect_refused(state.apply(&new_intent), ErrorCode::Terminal);
-        } else {
-            assert_eq!(task["status"], "running", "round {round}");
-            assert_eq!(task["unresolved_intents"], 1, "round {round}");
-            assert_eq!(recorded.expect("the winning intent is persisted").0, 1);
-            expect_refused(state.apply(&complete), ErrorCode::OutcomeUncertain);
-        }
-    }
-}
-
-#[test]
-fn a_decision_goes_stale_when_the_state_it_read_moves() {
-    let dir = TempDir::new().unwrap();
-    let state = AgentState::new(open(&dir));
-    state
-        .apply(&create("t1", "agent-a", "L1", 600_000))
-        .unwrap();
-
-    // Decide against version 1 of the task...
-    let prepared = state
-        .prepare(&checkpoint(
-            "t1",
-            "agent-a",
-            1,
-            "L1",
-            1,
-            Some("running"),
-            json!([]),
-        ))
-        .unwrap();
-    // ...let someone else move it...
-    state
-        .apply(&checkpoint(
-            "t1",
-            "agent-a",
-            1,
-            "L1",
-            1,
-            Some("running"),
-            json!([]),
-        ))
-        .unwrap();
-    // ...and the old decision cannot be committed, and writes nothing.
-    match state.commit(&prepared) {
-        Err(AgentStateError::Conflict(
-            PreconditionFailure::Version { .. } | PreconditionFailure::Present { .. },
-        )) => {}
-        other => panic!("a stale decision must be refused by the guarded commit: {other:?}"),
-    }
-    assert_eq!(version_of(&state, "_feltdb.AgentTask", "t1"), 2);
-    assert!(state
-        .read("_feltdb.AgentCheckpoint", "t1~v3")
-        .unwrap()
-        .is_none());
-
-    // Retrying means deciding again, and the contract now says why.
-    expect_refused(
-        state.apply(&checkpoint(
-            "t1",
-            "agent-a",
-            1,
-            "L1",
-            1,
-            Some("running"),
-            json!([]),
-        )),
-        ErrorCode::VersionConflict,
-    );
-}
-
-#[test]
-fn a_decision_goes_stale_when_the_lease_expires_before_the_commit() {
-    let dir = TempDir::new().unwrap();
-    let state = AgentState::new(open(&dir));
-    state.apply(&create("t1", "agent-a", "L1", 250)).unwrap();
-
-    // Valid now: the owner holds an unexpired lease.
-    let prepared = state
-        .prepare(&checkpoint(
-            "t1",
-            "agent-a",
-            1,
-            "L1",
-            1,
-            Some("running"),
-            json!([]),
-        ))
-        .unwrap();
-    thread::sleep(Duration::from_millis(400));
-    // The version has not moved, but the authority's clock has: the commit-time
-    // lease predicate refuses, so an owner cannot act on a lease it no longer has.
-    match state.commit(&prepared) {
-        Err(AgentStateError::Conflict(PreconditionFailure::Lease { expected, .. })) => {
-            assert_eq!(expected, "L1")
-        }
-        other => panic!("expected a lease conflict at commit, got {other:?}"),
-    }
-    assert_eq!(
-        version_of(&state, "_feltdb.AgentTask", "t1"),
-        1,
-        "nothing was written"
-    );
-    assert!(state
-        .read("_feltdb.AgentCheckpoint", "t1~v2")
-        .unwrap()
-        .is_none());
-}
-
-#[test]
-fn a_previous_owner_cannot_commit_after_a_takeover() {
-    let dir = TempDir::new().unwrap();
-    let state = AgentState::new(open(&dir));
-    state.apply(&create("t1", "agent-a", "L1", 250)).unwrap();
-    state
-        .apply(&checkpoint(
-            "t1",
-            "agent-a",
-            1,
-            "L1",
-            1,
-            Some("running"),
-            json!([]),
-        ))
-        .unwrap();
-
-    let in_flight = state
-        .prepare(&checkpoint("t1", "agent-a", 1, "L1", 2, None, json!([])))
-        .unwrap();
-    thread::sleep(Duration::from_millis(400));
-    state
-        .apply(&acquire("t1", "agent-b", "L2", 600_000))
-        .unwrap();
-
-    assert!(
-        matches!(state.commit(&in_flight), Err(AgentStateError::Conflict(_))),
-        "the old owner's in-flight decision is refused"
-    );
-    // And any fresh attempt by the old owner is refused by the contract on the fence.
-    expect_refused(
-        state.apply(&checkpoint("t1", "agent-a", 1, "L1", 2, None, json!([]))),
-        ErrorCode::FenceStale,
-    );
-    let (_, task) = state.read("_feltdb.AgentTask", "t1").unwrap().unwrap();
-    assert_eq!(
-        (
-            task["owner"].as_str().unwrap(),
-            task["fence"].as_u64().unwrap()
-        ),
-        ("agent-b", 2)
-    );
-}
-
-/// A commit touches several records and either all of them or none. Here the
-/// guard that fails is on a record the commit only *cited*, so a failure must
-/// leave the written records untouched too.
-#[test]
-fn a_failed_guard_on_cited_evidence_commits_nothing() {
-    let dir = TempDir::new().unwrap();
-    let db = open(&dir);
-    let state = AgentState::new(db.clone());
-    state
-        .apply(&create("t1", "agent-a", "L1", 600_000))
-        .unwrap();
-    state
-        .apply(&checkpoint(
-            "t1",
-            "agent-a",
-            1,
-            "L1",
-            1,
-            Some("running"),
-            json!([]),
-        ))
-        .unwrap();
-    state
-        .apply(&intent("t1", "agent-a", 1, "L1", "charge-1"))
-        .unwrap();
-    write_external(&db, "receipts", "r1");
-
-    let (task_before, intent_before) = (
-        version_of(&state, "_feltdb.AgentTask", "t1"),
-        version_of(&state, "_feltdb.AgentIntent", "t1~charge-1"),
-    );
-    let prepared = state
-        .prepare(&reconcile("t1", "agent-a", 1, "L1", "charge-1", receipt()))
-        .unwrap();
-    // The cited record changes after FeltDB observed it.
-    write_external(&db, "receipts", "r1");
-
-    match state.commit(&prepared) {
-        Err(AgentStateError::Conflict(PreconditionFailure::Version {
-            collection,
-            expected,
-            actual,
-            ..
-        })) => {
-            assert_eq!((collection.as_str(), expected, actual), ("receipts", 1, 2));
-        }
-        other => panic!("expected the evidence guard to fail, got {other:?}"),
-    }
-    assert_eq!(
-        version_of(&state, "_feltdb.AgentTask", "t1"),
-        task_before,
-        "the task was not touched"
-    );
-    assert_eq!(
-        version_of(&state, "_feltdb.AgentIntent", "t1~charge-1"),
-        intent_before,
-        "the intent was not touched"
-    );
-    let (_, task) = state.read("_feltdb.AgentTask", "t1").unwrap().unwrap();
-    assert_eq!(
-        task["unresolved_intents"], 1,
-        "the action is still uncertain"
-    );
-
-    // Deciding again observes the record as it now is, pins that version, and succeeds.
-    state
-        .apply(&reconcile("t1", "agent-a", 1, "L1", "charge-1", receipt()))
-        .unwrap();
-    let (_, resolved) = state
-        .read("_feltdb.AgentIntent", "t1~charge-1")
-        .unwrap()
-        .unwrap();
-    assert_eq!(resolved["evidence"][0]["version"], 2);
-}
-
-#[test]
-fn a_conflict_is_reported_not_retried() {
-    let dir = TempDir::new().unwrap();
-    let state = AgentState::new(open(&dir));
-    state
-        .apply(&create("t1", "agent-a", "L1", 600_000))
-        .unwrap();
-    let prepared = state
-        .prepare(&checkpoint(
-            "t1",
-            "agent-a",
-            1,
-            "L1",
-            1,
-            Some("running"),
-            json!([]),
-        ))
-        .unwrap();
-    state
-        .apply(&checkpoint(
-            "t1",
-            "agent-a",
-            1,
-            "L1",
-            1,
-            Some("running"),
-            json!([]),
-        ))
-        .unwrap();
-    // Offering the same stale decision twice fails twice: it is never turned
-    // into a fresh decision behind the caller's back.
-    for _ in 0..2 {
-        assert!(matches!(
-            state.commit(&prepared),
-            Err(AgentStateError::Conflict(_))
-        ));
-    }
-    assert_eq!(version_of(&state, "_feltdb.AgentTask", "t1"), 2);
-}
-
-// ---------------------------------------------------------------------------
-// There is no second state machine
-// ---------------------------------------------------------------------------
-
-/// `agent_state.rs` is plumbing. If a lifecycle word appears in its code, a rule
-/// has leaked out of the contract and there are now two places to keep right.
-#[test]
-fn the_production_module_contains_no_lifecycle_rules() {
-    let source =
-        std::fs::read_to_string(concat!(env!("CARGO_MANIFEST_DIR"), "/src/agent_state.rs"))
-            .unwrap();
-    let code: String = source
-        .lines()
-        .filter(|line| !line.trim_start().starts_with("//"))
-        .collect::<Vec<_>>()
-        .join("\n");
-    for word in [
-        "\"ready\"",
-        "\"running\"",
-        "\"blocked\"",
-        "\"completed\"",
-        "\"cancelled\"",
-        "\"open\"",
-        "\"claimed\"",
-        "\"accepted\"",
-        "\"intended\"",
-        "\"reported\"",
-        "\"resolved\"",
-        "fence",
-        "expires",
-        "unresolved",
-    ] {
-        assert!(
-            !code.contains(word),
-            "agent_state.rs mentions {word}: lifecycle logic belongs to the contract"
-        );
-    }
-    assert!(
-        code.contains("evaluate(&input)"),
-        "the module must decide through the contract"
-    );
-}
-
-// ---------------------------------------------------------------------------
-// Cost
-// ---------------------------------------------------------------------------
-
-/// Not an assertion: prints what a decision and a full transition cost on this
-/// machine. Run with `--ignored --nocapture`. It measures the contract and one
-/// guarded commit, not query paths, which this change does not add.
-#[test]
-#[ignore = "prints measurements; not a pass/fail test"]
-fn measure_the_cost_of_a_decision_and_of_a_transition() {
-    use std::time::Instant;
-    let dir = TempDir::new().unwrap();
-    let state = AgentState::new(open(&dir));
-    state
-        .apply(&create("t1", "agent-a", "L1", 86_400_000))
-        .unwrap();
-    state
-        .apply(&checkpoint(
-            "t1",
-            "agent-a",
-            1,
-            "L1",
-            1,
-            Some("running"),
-            json!([]),
-        ))
-        .unwrap();
-
-    const N: u32 = 2000;
-    let mut version = 2;
-    let started = Instant::now();
-    for _ in 0..N {
-        let prepared = state
-            .prepare(&checkpoint(
-                "t1",
-                "agent-a",
-                1,
-                "L1",
-                version,
-                None,
-                json!([]),
-            ))
-            .unwrap();
-        std::hint::black_box(&prepared);
-    }
-    let decide = started.elapsed() / N;
-
-    let started = Instant::now();
-    for _ in 0..N {
-        state
-            .apply(&checkpoint(
-                "t1",
-                "agent-a",
-                1,
-                "L1",
-                version,
-                None,
-                json!([]),
-            ))
-            .unwrap();
-        version += 1;
-    }
-    let transition = started.elapsed() / N;
-    println!("read + decide (no commit):                       {decide:?} per operation");
-    println!("read + decide + guarded commit (two records):    {transition:?} per operation");
-}