create-feltdb 0.11.4 → 0.11.8

package/dist/server-source/crates/feltdb/tests/semantic_query.rs

@@ -0,0 +1,767 @@
+//! Semantic query composition — conformance to `docs/reference/semantic-query.md`.
+//!
+//! Every test here exercises `compose_semantic_page` over a candidate page the
+//! deterministic stage would have produced, with a runtime that counts what
+//! reaches a provider. The section numbers name the contract clause each test
+//! pins.
+
+use feltdb::semantic_decision::{
+    DecisionDefinition, DecisionError, DecisionRequest, DecisionResult, DecisionRuntime,
+    DecisionRuntimeCapabilities, DecisionRuntimeMetadata, DecisionStatus,
+    DecisionTransportAuthorization, DEFAULT_DECISION_COLLECTION,
+};
+use feltdb::semantic_query::{
+    compose_semantic_page, semantic_clause_hash, validate_semantic_clause, SemanticCandidate,
+    SemanticOrderDirection, SemanticQueryClause, SemanticQueryFilter, SemanticQueryMode,
+    SemanticQueryOrder, SemanticUnevaluatedReason,
+};
+use feltdb::FeltDb;
+use serde_json::{json, Value};
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::{Arc, Mutex};
+
+fn memory_db(name: &str) -> FeltDb {
+    let path = std::env::temp_dir().join(format!(
+        "feltdb-semantic-query-{name}-{}.log",
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .expect("time")
+            .as_nanos()
+    ));
+    FeltDb::open(path).expect("db")
+}
+
+/// Answers from the record's own fields and counts every provider call.
+#[derive(Clone)]
+struct CountingRuntime {
+    invocations: Arc<AtomicUsize>,
+    seen: Arc<Mutex<Vec<String>>>,
+    fail: bool,
+    malformed: bool,
+    capabilities: DecisionRuntimeCapabilities,
+}
+
+impl CountingRuntime {
+    fn new() -> Self {
+        Self {
+            invocations: Arc::new(AtomicUsize::new(0)),
+            seen: Arc::new(Mutex::new(Vec::new())),
+            fail: false,
+            malformed: false,
+            capabilities: DecisionRuntimeCapabilities::default(),
+        }
+    }
+
+    fn invocations(&self) -> usize {
+        self.invocations.load(Ordering::SeqCst)
+    }
+
+    fn seen_contexts(&self) -> Vec<String> {
+        self.seen.lock().expect("seen").clone()
+    }
+}
+
+impl DecisionRuntime for CountingRuntime {
+    fn metadata(&self) -> DecisionRuntimeMetadata {
+        DecisionRuntimeMetadata {
+            runtime: "deterministic".into(),
+            model: Some("deterministic-runtime".into()),
+            model_revision: Some("deterministic-v1".into()),
+            prompt_revision: Some("prompt-v1".into()),
+            execution_method: Some(feltdb::DecisionExecutionMethod::Logit),
+            decision_schema_revision: Some("semantic-decision-v1".into()),
+        }
+    }
+
+    fn capabilities(&self) -> DecisionRuntimeCapabilities {
+        self.capabilities.clone()
+    }
+
+    fn decide(&self, request: &DecisionRequest) -> Result<DecisionResult, DecisionError> {
+        self.invocations.fetch_add(1, Ordering::SeqCst);
+        self.seen
+            .lock()
+            .expect("seen")
+            .push(request.context().to_string());
+        if self.fail {
+            return Err(DecisionError::new("PROVIDER_DOWN", "connection refused"));
+        }
+        let context = request.context();
+        Ok(match request {
+            DecisionRequest::Binary { .. } => DecisionResult::Binary {
+                decision: context.get("employmentType").and_then(Value::as_str) == Some("remote"),
+                option_mass: 0.9,
+                supporting_fields: vec!["employmentType".into()],
+            },
+            DecisionRequest::Choice { options, .. } => {
+                let selected = context
+                    .get("actionHint")
+                    .and_then(Value::as_str)
+                    .unwrap_or("review")
+                    .to_string();
+                DecisionResult::Choice {
+                    selected: if self.malformed {
+                        "not-an-option".into()
+                    } else {
+                        selected.clone()
+                    },
+                    options: options
+                        .iter()
+                        .map(|option| feltdb::WeightedOption {
+                            value: option.clone(),
+                            probability: if *option == selected { 0.9 } else { 0.05 },
+                        })
+                        .collect(),
+                    option_mass: 0.9,
+                    supporting_fields: vec!["actionHint".into()],
+                }
+            }
+            DecisionRequest::Score { levels, .. } => {
+                let selected = context
+                    .get("urgency")
+                    .and_then(Value::as_str)
+                    .unwrap_or("low")
+                    .to_string();
+                DecisionResult::Score {
+                    selected: selected.clone(),
+                    levels: levels
+                        .iter()
+                        .map(|level| feltdb::WeightedOption {
+                            value: level.clone(),
+                            probability: if *level == selected { 0.9 } else { 0.05 },
+                        })
+                        .collect(),
+                    option_mass: 0.9,
+                    supporting_fields: vec!["urgency".into()],
+                }
+            }
+        })
+    }
+}
+
+fn urgency() -> DecisionDefinition {
+    DecisionDefinition::Score {
+        question: "What is the urgency?".into(),
+        levels: vec!["low".into(), "medium".into(), "high".into()],
+    }
+}
+
+fn remote() -> DecisionDefinition {
+    DecisionDefinition::Binary {
+        predicate: "could work from home".into(),
+    }
+}
+
+fn action() -> DecisionDefinition {
+    DecisionDefinition::Choice {
+        question: "Which action should be taken?".into(),
+        options: vec!["approve".into(), "reject".into(), "review".into()],
+    }
+}
+
+fn clause(decision: DecisionDefinition) -> SemanticQueryClause {
+    SemanticQueryClause {
+        decision,
+        mode: SemanticQueryMode::Evaluate,
+        filter: None,
+        order_by: None,
+        fields: None,
+        schema_version: None,
+        authorization: None,
+    }
+}
+
+/// Seeds `count` tickets and returns them as the deterministic page, in
+/// ascending `seq` order with the record id as tie-breaker.
+fn seed_page(db: &FeltDb, count: usize) -> Vec<SemanticCandidate> {
+    (0..count)
+        .map(|index| {
+            let urgency = ["low", "medium", "high"][index % 3];
+            let employment = if index % 2 == 0 { "remote" } else { "office" };
+            let hint = ["approve", "reject", "review"][index % 3];
+            let record = json!({
+                "id": format!("t-{index}"),
+                "__version": 1,
+                "seq": index,
+                "urgency": urgency,
+                "employmentType": employment,
+                "actionHint": hint,
+            });
+            db.insert(&format!("tickets:t-{index}"), record.clone())
+                .expect("insert");
+            SemanticCandidate {
+                record_id: format!("t-{index}"),
+                record,
+            }
+        })
+        .collect()
+}
+
+fn ids(records: &[Value]) -> Vec<String> {
+    records
+        .iter()
+        .map(|record| record["id"].as_str().unwrap().to_string())
+        .collect()
+}
+
+/// §3 / §13 — the stage evaluates exactly the page it is given: one provider
+/// call per candidate, none for the records outside the page, and a second
+/// request over the same page reuses every judgment.
+#[test]
+fn evaluates_exactly_the_candidate_page_and_reuses_judgments() {
+    let db = memory_db("page");
+    let all = seed_page(&db, 9);
+    let page = all[..4].to_vec();
+    let runtime = CountingRuntime::new();
+
+    let first = compose_semantic_page(
+        &db,
+        "tickets",
+        page.clone(),
+        &clause(urgency()),
+        Some(&runtime),
+        None,
+    )
+    .expect("page");
+    assert_eq!(runtime.invocations(), 4);
+    assert_eq!(ids(&first.records), ["t-0", "t-1", "t-2", "t-3"]);
+    assert!(first.complete);
+    assert_eq!(first.stage.candidates, 4);
+    assert_eq!(first.stage.evaluated, 4);
+    assert_eq!(first.stage.reused, 0);
+    assert!(first
+        .annotations
+        .iter()
+        .all(|annotation| annotation.as_ref().is_some_and(|a| !a.cached)));
+
+    let second = compose_semantic_page(
+        &db,
+        "tickets",
+        page,
+        &clause(urgency()),
+        Some(&runtime),
+        None,
+    )
+    .expect("page");
+    assert_eq!(
+        runtime.invocations(),
+        4,
+        "no provider call for a reusable judgment"
+    );
+    assert_eq!(second.stage.reused, 4);
+    assert_eq!(second.stage.evaluated, 0);
+    assert!(second.annotations.iter().all(|annotation| annotation
+        .as_ref()
+        .is_some_and(|a| a.cached && a.provenance.source == "cache")));
+
+    let judgments: Vec<feltdb::DecisionJudgmentRecord> = db
+        .capability(DEFAULT_DECISION_COLLECTION)
+        .find(|_: &feltdb::DecisionJudgmentRecord| true)
+        .expect("judgments");
+    assert_eq!(judgments.len(), 4, "judgments exist only for page records");
+    assert!(judgments
+        .iter()
+        .all(|judgment| judgment.status == DecisionStatus::Active));
+}
+
+/// §7 — binary and choice filters keep the deterministic order of the page
+/// and never refill it: a page whose filter removes candidates is shorter.
+#[test]
+fn binary_and_choice_filters_reduce_the_page_in_deterministic_order() {
+    let db = memory_db("filter");
+    let page = seed_page(&db, 6);
+    let runtime = CountingRuntime::new();
+
+    let mut remote_only = clause(remote());
+    remote_only.filter = Some(SemanticQueryFilter {
+        is: Some(true),
+        ..Default::default()
+    });
+    let filtered = compose_semantic_page(
+        &db,
+        "tickets",
+        page.clone(),
+        &remote_only,
+        Some(&runtime),
+        None,
+    )
+    .expect("page");
+    assert_eq!(ids(&filtered.records), ["t-0", "t-2", "t-4"]);
+    assert_eq!(filtered.stage.filtered, 3);
+    assert_eq!(filtered.stage.candidates, 6);
+    assert_eq!(
+        runtime.invocations(),
+        6,
+        "every candidate was evaluated once"
+    );
+
+    let mut reviews = clause(action());
+    reviews.filter = Some(SemanticQueryFilter {
+        within: Some(vec!["review".into(), "reject".into()]),
+        ..Default::default()
+    });
+    let filtered =
+        compose_semantic_page(&db, "tickets", page, &reviews, Some(&runtime), None).expect("page");
+    assert_eq!(ids(&filtered.records), ["t-1", "t-2", "t-4", "t-5"]);
+    assert_eq!(filtered.annotations.len(), filtered.records.len());
+}
+
+/// §8 — score ordering is by declared-level ordinal within the page, with the
+/// deterministic position as tie-breaker; `desc` reverses the ordinal only.
+#[test]
+fn score_orders_within_the_page_by_level_ordinal_with_deterministic_ties() {
+    let db = memory_db("order");
+    let page = seed_page(&db, 7); // low, medium, high, low, medium, high, low
+    let runtime = CountingRuntime::new();
+
+    let mut ranked = clause(urgency());
+    ranked.order_by = Some(SemanticQueryOrder {
+        direction: SemanticOrderDirection::Desc,
+    });
+    let composed =
+        compose_semantic_page(&db, "tickets", page.clone(), &ranked, Some(&runtime), None)
+            .expect("page");
+    assert_eq!(
+        ids(&composed.records),
+        ["t-2", "t-5", "t-1", "t-4", "t-0", "t-3", "t-6"],
+        "ordinal descending, then the deterministic page order"
+    );
+    let selected: Vec<_> = composed
+        .annotations
+        .iter()
+        .map(|annotation| match &annotation.as_ref().unwrap().result {
+            DecisionResult::Score { selected, .. } => selected.clone(),
+            other => panic!("unexpected {other:?}"),
+        })
+        .collect();
+    assert_eq!(
+        selected,
+        ["high", "high", "medium", "medium", "low", "low", "low"]
+    );
+
+    let mut at_least_medium = ranked.clone();
+    at_least_medium.order_by = Some(SemanticQueryOrder {
+        direction: SemanticOrderDirection::Asc,
+    });
+    at_least_medium.filter = Some(SemanticQueryFilter {
+        at_least: Some("medium".into()),
+        at_most: Some("high".into()),
+        ..Default::default()
+    });
+    let composed =
+        compose_semantic_page(&db, "tickets", page, &at_least_medium, Some(&runtime), None)
+            .expect("page");
+    assert_eq!(ids(&composed.records), ["t-1", "t-4", "t-2", "t-5"]);
+    assert_eq!(composed.stage.filtered, 3);
+}
+
+/// §5 / §8.3 / §11.3 — `reuse-only` never reaches the provider; candidates
+/// without a judgment are reported, sort last, and mark the page incomplete.
+#[test]
+fn reuse_only_never_reaches_the_provider_and_reports_what_it_could_not_answer() {
+    let db = memory_db("reuse-only");
+    let page = seed_page(&db, 5);
+    let runtime = CountingRuntime::new();
+
+    // Judge two of the five ahead of time, through the ordinary primitive.
+    for id in ["t-2", "t-4"] {
+        feltdb::decide_record(
+            &db,
+            &feltdb::DecisionRecordRef {
+                collection: "tickets".into(),
+                record_id: id.into(),
+            },
+            &urgency(),
+            &runtime,
+            &feltdb::DecisionOptions::default(),
+            None,
+        )
+        .expect("judgment");
+    }
+    assert_eq!(runtime.invocations(), 2);
+
+    let mut reuse = clause(urgency());
+    reuse.mode = SemanticQueryMode::ReuseOnly;
+    reuse.order_by = Some(SemanticQueryOrder {
+        direction: SemanticOrderDirection::Desc,
+    });
+    let composed =
+        compose_semantic_page(&db, "tickets", page.clone(), &reuse, Some(&runtime), None)
+            .expect("page");
+    assert_eq!(runtime.invocations(), 2, "reuse-only made no provider call");
+    assert!(!composed.complete);
+    assert_eq!(
+        ids(&composed.records),
+        ["t-2", "t-4", "t-0", "t-1", "t-3"],
+        "evaluated first by ordinal, then unevaluated in deterministic order"
+    );
+    assert!(composed.annotations[0].is_some() && composed.annotations[1].is_some());
+    assert!(composed.annotations[2..].iter().all(Option::is_none));
+    assert_eq!(composed.stage.reused, 2);
+    assert_eq!(composed.stage.unevaluated, 3);
+    assert_eq!(
+        composed
+            .unevaluated
+            .iter()
+            .map(|entry| (entry.record_id.as_str(), entry.reason))
+            .collect::<Vec<_>>(),
+        [
+            ("t-0", SemanticUnevaluatedReason::NoJudgment),
+            ("t-1", SemanticUnevaluatedReason::NoJudgment),
+            ("t-3", SemanticUnevaluatedReason::NoJudgment),
+        ]
+    );
+
+    // With a filter, an unevaluated candidate cannot match and is not guessed.
+    reuse.filter = Some(SemanticQueryFilter {
+        at_least: Some("low".into()),
+        ..Default::default()
+    });
+    let composed =
+        compose_semantic_page(&db, "tickets", page, &reuse, Some(&runtime), None).expect("page");
+    assert_eq!(ids(&composed.records), ["t-2", "t-4"]);
+    assert_eq!(composed.stage.filtered, 3);
+    assert!(!composed.complete);
+    assert_eq!(runtime.invocations(), 2);
+}
+
+/// §4 — the provider sees only the authorized packet; a candidate whose
+/// authorized context is empty is unevaluated, not evaluated over nothing,
+/// and the returned record keeps every field the deterministic stage gave it.
+#[test]
+fn authorization_narrows_the_provider_context_and_never_the_record() {
+    let db = memory_db("authorization");
+    let page = seed_page(&db, 2);
+    let runtime = CountingRuntime::new();
+
+    let mut narrowed = clause(urgency());
+    narrowed.authorization = Some(DecisionTransportAuthorization {
+        allowed_fields: vec!["urgency".into()],
+        principal: None,
+    });
+    let principal = feltdb::DecisionPrincipal {
+        subject: feltdb::authorization::Subject::Service("query-principal".into()),
+        tenant_id: "tenant".into(),
+        application_id: "app".into(),
+        capability: "state:read".into(),
+    };
+    let composed = compose_semantic_page(
+        &db,
+        "tickets",
+        page.clone(),
+        &narrowed,
+        Some(&runtime),
+        Some(principal.clone()),
+    )
+    .expect("page");
+    assert!(composed.complete);
+    for context in runtime.seen_contexts() {
+        let context: Value = serde_json::from_str(&context).unwrap();
+        assert_eq!(
+            context.as_object().unwrap().keys().collect::<Vec<_>>(),
+            ["urgency"],
+            "only the authorized field reached the provider"
+        );
+    }
+    assert!(
+        composed.records[0].get("employmentType").is_some(),
+        "the record itself is untouched"
+    );
+    let judgments: Vec<feltdb::DecisionJudgmentRecord> = db
+        .capability(DEFAULT_DECISION_COLLECTION)
+        .find(|_: &feltdb::DecisionJudgmentRecord| true)
+        .expect("judgments");
+    assert!(judgments.iter().all(|judgment| judgment
+        .state
+        .withheld_fields
+        .contains(&"employmentType".to_string())));
+    assert!(judgments
+        .iter()
+        .all(|judgment| judgment.state.reference.starts_with("flow://app/tickets/")));
+
+    let mut nothing = narrowed.clone();
+    nothing.authorization = Some(DecisionTransportAuthorization {
+        allowed_fields: vec![],
+        principal: None,
+    });
+    let before = runtime.invocations();
+    let composed = compose_semantic_page(
+        &db,
+        "tickets",
+        page,
+        &nothing,
+        Some(&runtime),
+        Some(principal),
+    )
+    .expect("page");
+    assert_eq!(
+        runtime.invocations(),
+        before,
+        "an empty authorized context never reaches the provider"
+    );
+    assert!(!composed.complete);
+    assert_eq!(
+        composed.records.len(),
+        2,
+        "unevaluated candidates stay in an unfiltered page"
+    );
+    assert!(composed.annotations.iter().all(Option::is_none));
+    assert!(composed
+        .unevaluated
+        .iter()
+        .all(|entry| entry.reason == SemanticUnevaluatedReason::Unauthorized));
+}
+
+/// §11 — the semantic stage fails as a unit. A provider failure is
+/// `SEMANTIC_PROVIDER_UNAVAILABLE`, a malformed provider result is
+/// `SEMANTIC_INVALID_RESULT`, a missing binding is unavailable in either
+/// mode, and an unsupported kind is refused before any candidate is
+/// evaluated. In none of these cases is the deterministic page returned.
+#[test]
+fn failures_never_degrade_into_the_deterministic_page() {
+    let db = memory_db("failure");
+    let page = seed_page(&db, 3);
+
+    let down = CountingRuntime {
+        fail: true,
+        ..CountingRuntime::new()
+    };
+    let error = compose_semantic_page(
+        &db,
+        "tickets",
+        page.clone(),
+        &clause(urgency()),
+        Some(&down),
+        None,
+    )
+    .expect_err("provider down");
+    assert_eq!(error.code, "SEMANTIC_PROVIDER_UNAVAILABLE");
+    assert!(error.message.contains("connection refused"));
+
+    let malformed = CountingRuntime {
+        malformed: true,
+        ..CountingRuntime::new()
+    };
+    let error = compose_semantic_page(
+        &db,
+        "tickets",
+        page.clone(),
+        &clause(action()),
+        Some(&malformed),
+        None,
+    )
+    .expect_err("malformed result");
+    assert_eq!(error.code, "SEMANTIC_INVALID_RESULT");
+
+    let error = compose_semantic_page(&db, "tickets", page.clone(), &clause(urgency()), None, None)
+        .expect_err("no binding");
+    assert_eq!(error.code, "SEMANTIC_PROVIDER_UNAVAILABLE");
+    let mut reuse = clause(urgency());
+    reuse.mode = SemanticQueryMode::ReuseOnly;
+    let error = compose_semantic_page(&db, "tickets", page.clone(), &reuse, None, None)
+        .expect_err("no binding, reuse-only");
+    assert_eq!(error.code, "SEMANTIC_PROVIDER_UNAVAILABLE");
+
+    let no_score = CountingRuntime {
+        capabilities: DecisionRuntimeCapabilities {
+            score: false,
+            ..DecisionRuntimeCapabilities::default()
+        },
+        ..CountingRuntime::new()
+    };
+    let error = compose_semantic_page(
+        &db,
+        "tickets",
+        page,
+        &clause(urgency()),
+        Some(&no_score),
+        None,
+    )
+    .expect_err("unsupported kind");
+    assert_eq!(error.code, "SEMANTIC_UNSUPPORTED");
+    assert_eq!(no_score.invocations(), 0);
+}
+
+/// §7 / §11.5 — an invalid clause is `INVALID_QUERY` before anything runs:
+/// undeclared options or levels, an operator for the wrong kind, ordering on
+/// a non-score decision, an empty filter, and unknown keys.
+#[test]
+fn invalid_clauses_are_refused_before_evaluation() {
+    let invalid = |clause: &SemanticQueryClause, expect: &str| {
+        let error = validate_semantic_clause(clause).expect_err(expect);
+        assert_eq!(error.code, "INVALID_QUERY", "{expect}: {error}");
+    };
+    let mut undeclared = clause(urgency());
+    undeclared.filter = Some(SemanticQueryFilter {
+        at_least: Some("critical".into()),
+        ..Default::default()
+    });
+    invalid(&undeclared, "undeclared level");
+
+    let mut wrong_operator = clause(remote());
+    wrong_operator.filter = Some(SemanticQueryFilter {
+        within: Some(vec!["true".into()]),
+        ..Default::default()
+    });
+    invalid(&wrong_operator, "binary takes `is`");
+
+    let mut ordered_choice = clause(action());
+    ordered_choice.order_by = Some(SemanticQueryOrder {
+        direction: SemanticOrderDirection::Asc,
+    });
+    invalid(&ordered_choice, "only score orders");
+
+    let mut empty = clause(urgency());
+    empty.filter = Some(SemanticQueryFilter::default());
+    invalid(&empty, "empty filter");
+
+    let mut bad_definition = clause(DecisionDefinition::Choice {
+        question: "?".into(),
+        options: vec!["a".into(), "a".into()],
+    });
+    bad_definition.filter = None;
+    invalid(&bad_definition, "duplicate option");
+
+    let unknown_key: Result<SemanticQueryClause, _> = serde_json::from_value(json!({
+        "decision": { "kind": "binary", "predicate": "is urgent" },
+        "refill": true,
+    }));
+    assert!(
+        unknown_key.is_err(),
+        "unknown clause keys are refused, never ignored"
+    );
+    let unknown_filter: Result<SemanticQueryClause, _> = serde_json::from_value(json!({
+        "decision": { "kind": "binary", "predicate": "is urgent" },
+        "filter": { "massAtLeast": 0.5 },
+    }));
+    assert!(
+        unknown_filter.is_err(),
+        "option_mass is never a filter operand"
+    );
+
+    let error = compose_semantic_page(
+        &memory_db("too-many"),
+        "tickets",
+        (0..1_001)
+            .map(|index| SemanticCandidate {
+                record_id: format!("t-{index}"),
+                record: json!({}),
+            })
+            .collect(),
+        &clause(urgency()),
+        Some(&CountingRuntime::new()),
+        None,
+    )
+    .expect_err("over the page bound");
+    assert_eq!(error.code, "INVALID_QUERY");
+}
+
+/// §10 — the clause hash that binds a cursor changes with the clause and
+/// with nothing else; results, judgments, and providers never enter it.
+#[test]
+fn clause_hash_binds_the_clause_and_not_its_results() {
+    let base = clause(urgency());
+    let same = clause(urgency());
+    assert_eq!(semantic_clause_hash(&base), semantic_clause_hash(&same));
+
+    let mut filtered = clause(urgency());
+    filtered.filter = Some(SemanticQueryFilter {
+        at_least: Some("medium".into()),
+        ..Default::default()
+    });
+    assert_ne!(semantic_clause_hash(&base), semantic_clause_hash(&filtered));
+
+    let mut reuse = clause(urgency());
+    reuse.mode = SemanticQueryMode::ReuseOnly;
+    assert_ne!(semantic_clause_hash(&base), semantic_clause_hash(&reuse));
+
+    // Evaluating a page does not change the hash of the clause that ran it.
+    let db = memory_db("hash");
+    let page = seed_page(&db, 2);
+    compose_semantic_page(
+        &db,
+        "tickets",
+        page,
+        &base,
+        Some(&CountingRuntime::new()),
+        None,
+    )
+    .expect("page");
+    assert_eq!(semantic_clause_hash(&base), semantic_clause_hash(&same));
+}
+
+/// §6 — a semantic query writes judgments and nothing else; the judged records
+/// are byte-for-byte what they were, and a state change supersedes the
+/// judgment through the primitive's own lifecycle.
+#[test]
+fn judgments_are_derived_state_that_state_changes_supersede() {
+    let db = memory_db("derived");
+    let page = seed_page(&db, 2);
+    let runtime = CountingRuntime::new();
+    let before: Vec<Value> = page
+        .iter()
+        .map(|candidate| {
+            db.get(&format!("tickets:{}", candidate.record_id))
+                .unwrap()
+                .unwrap()
+        })
+        .collect();
+
+    compose_semantic_page(
+        &db,
+        "tickets",
+        page.clone(),
+        &clause(urgency()),
+        Some(&runtime),
+        None,
+    )
+    .expect("page");
+    let after: Vec<Value> = page
+        .iter()
+        .map(|candidate| {
+            db.get(&format!("tickets:{}", candidate.record_id))
+                .unwrap()
+                .unwrap()
+        })
+        .collect();
+    assert_eq!(before, after);
+
+    let mut changed = before[0].clone();
+    changed["urgency"] = json!("high");
+    db.update("tickets:t-0", changed.clone()).expect("update");
+    let page = vec![
+        SemanticCandidate {
+            record_id: "t-0".into(),
+            record: changed,
+        },
+        page[1].clone(),
+    ];
+    let composed = compose_semantic_page(
+        &db,
+        "tickets",
+        page,
+        &clause(urgency()),
+        Some(&runtime),
+        None,
+    )
+    .expect("page");
+    assert_eq!(
+        runtime.invocations(),
+        3,
+        "only the changed record was re-evaluated"
+    );
+    assert_eq!(composed.stage.evaluated, 1);
+    assert_eq!(composed.stage.reused, 1);
+    let judgments: Vec<feltdb::DecisionJudgmentRecord> = db
+        .capability(DEFAULT_DECISION_COLLECTION)
+        .find(|row: &feltdb::DecisionJudgmentRecord| row.record_id == "t-0")
+        .expect("judgments");
+    assert_eq!(judgments.len(), 2);
+    assert_eq!(
+        judgments
+            .iter()
+            .filter(|row| row.status == DecisionStatus::Superseded)
+            .count(),
+        1
+    );
+}