@feltdb/core 0.13.0 → 0.16.0

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

@@ -1,363 +0,0 @@
-//! Semantic query composition contract — boundary tests.
-//!
-//! `docs/reference/semantic-query.md` fixes the semantics a FeltDB query
-//! surface must honor when a semantic decision participates in a query. The
-//! bounded authority query implements it (`tests/semantic_query.rs` proves the
-//! page transformation; `e2e/semantic-query-composition.test.mjs` proves the
-//! managed surface). These tests pin the boundaries the contract draws around
-//! the rest of the crate: the canonical query has no semantic vocabulary but
-//! recognizes and refuses a semantic clause rather than dropping it, the
-//! decision transport stays record-scoped, runtime capabilities describe
-//! decisions rather than composition, the record-scoped primitive itself has
-//! no page boundary (the page boundary is `semantic_query`'s), and judgments
-//! stay beside application state. Each test names the section it guards.
-
-use feltdb::semantic_decision::{
-    decide_record, execute_decision_transport, DecisionDefinition, DecisionError, DecisionOptions,
-    DecisionRecordRef, DecisionRequest, DecisionResult, DecisionRuntime,
-    DecisionRuntimeCapabilities, DecisionRuntimeMetadata, DecisionTransportExecutionRequest,
-    DecisionTransportRuntime, DEFAULT_DECISION_COLLECTION,
-};
-use feltdb::state_contract::{query_hash, CanonicalQuery, QueryFilter};
-use feltdb::FeltDb;
-use serde_json::{json, Value};
-use std::collections::BTreeSet;
-use std::sync::atomic::{AtomicUsize, Ordering};
-use std::sync::Arc;
-
-fn memory_db(name: &str) -> FeltDb {
-    let path = std::env::temp_dir().join(format!(
-        "feltdb-semantic-query-contract-{name}-{}.log",
-        std::time::SystemTime::now()
-            .duration_since(std::time::UNIX_EPOCH)
-            .expect("time")
-            .as_nanos()
-    ));
-    FeltDb::open(path).expect("db")
-}
-
-/// A runtime that answers `score` decisions from an `urgency` field and counts
-/// every invocation, so the tests can measure what reaches a provider.
-#[derive(Clone)]
-struct CountingRuntime {
-    invocations: Arc<AtomicUsize>,
-}
-
-impl CountingRuntime {
-    fn new() -> Self {
-        Self {
-            invocations: Arc::new(AtomicUsize::new(0)),
-        }
-    }
-
-    fn invocations(&self) -> usize {
-        self.invocations.load(Ordering::SeqCst)
-    }
-}
-
-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 decide(&self, request: &DecisionRequest) -> Result<DecisionResult, DecisionError> {
-        self.invocations.fetch_add(1, Ordering::SeqCst);
-        let urgency = request
-            .context()
-            .get("urgency")
-            .and_then(Value::as_str)
-            .unwrap_or("low")
-            .to_string();
-        let levels = ["low", "medium", "high"]
-            .into_iter()
-            .map(|level| feltdb::WeightedOption {
-                value: level.into(),
-                probability: if level == urgency { 0.9 } else { 0.05 },
-            })
-            .collect();
-        Ok(DecisionResult::Score {
-            selected: urgency,
-            levels,
-            option_mass: 0.9,
-            supporting_fields: vec!["urgency".into()],
-        })
-    }
-}
-
-fn urgency_definition() -> DecisionDefinition {
-    DecisionDefinition::Score {
-        question: "What is the urgency?".into(),
-        levels: vec!["low".into(), "medium".into(), "high".into()],
-    }
-}
-
-fn seed_tickets(db: &FeltDb, count: usize) {
-    for index in 0..count {
-        let urgency = ["low", "medium", "high"][index % 3];
-        db.insert(
-            &format!("tickets:t-{index}"),
-            json!({
-                "id": format!("t-{index}"),
-                "__version": 1,
-                "title": format!("Ticket {index}"),
-                "urgency": urgency,
-            }),
-        )
-        .expect("insert");
-    }
-}
-
-/// §7 / §11.6 — the canonical `QueryFilter` vocabulary has no semantic
-/// operator. A filter naming one is refused at deserialization, so no
-/// canonical query can currently express semantic filtering at all.
-#[test]
-fn canonical_query_filter_has_no_semantic_operator() {
-    let semantic = json!({
-        "operator": "semantic",
-        "field": "urgency",
-        "decision": { "kind": "binary", "predicate": "is urgent" },
-    });
-    let error = serde_json::from_value::<QueryFilter>(semantic).expect_err("no semantic operator");
-    assert!(
-        error.to_string().contains("semantic"),
-        "unexpected rejection reason: {error}"
-    );
-
-    // The deterministic vocabulary the contract composes with is intact.
-    let deterministic = serde_json::from_value::<QueryFilter>(json!({
-        "operator": "eq",
-        "field": "urgency",
-        "value": "high",
-    }))
-    .expect("deterministic filter");
-    assert!(matches!(deterministic, QueryFilter::Eq { .. }));
-}
-
-/// §11.6 — the canonical query recognizes a semantic clause it does not
-/// compose. The clause is carried into the query rather than lost as an
-/// unknown key, so the query's identity changes with it and `execute_query`
-/// can refuse it with `SEMANTIC_UNSUPPORTED` (`state_contract` tests prove
-/// the refusal; `e2e/semantic-query-composition.test.mjs` proves it over
-/// `/v1/query`). The bounded authority query implements the same clause.
-#[test]
-fn canonical_query_recognizes_a_semantic_clause_it_does_not_compose() {
-    let plain = json!({
-        "collection": "tickets",
-        "filter": { "operator": "eq", "field": "urgency", "value": "high" },
-        "limit": 10,
-    });
-    let mut with_clause = plain.clone();
-    with_clause["semantic"] = json!({
-        "decision": { "kind": "binary", "predicate": "is urgent" },
-        "filter": { "is": true },
-    });
-
-    let plain: CanonicalQuery = serde_json::from_value(plain).expect("plain query");
-    let with_clause: CanonicalQuery =
-        serde_json::from_value(with_clause).expect("the clause is carried, not refused here");
-
-    assert!(plain.semantic.is_none());
-    assert!(with_clause.semantic.is_some());
-    assert_ne!(
-        query_hash(&plain).expect("hash"),
-        query_hash(&with_clause).expect("hash"),
-        "the semantic clause is part of query identity"
-    );
-    // The same clause is exactly what the bounded authority query accepts.
-    let clause: feltdb::SemanticQueryClause =
-        serde_json::from_value(with_clause.semantic.clone().unwrap()).expect("bounded clause");
-    feltdb::validate_semantic_clause(&clause).expect("valid for the bounded query");
-}
-
-/// §3 / §5 — the semantic-decision transport addresses exactly one durable
-/// record. There is no candidate-set, page, or collection-level target: a
-/// target without a record id does not deserialize, and the transport refuses
-/// both "no target" and "two targets".
-#[test]
-fn decision_transport_targets_exactly_one_durable_record() {
-    let collection_only = serde_json::from_value::<DecisionRecordRef>(json!({
-        "collection": "tickets",
-    }))
-    .expect_err("a collection is not a decision target");
-    assert!(
-        collection_only.to_string().contains("record_id"),
-        "unexpected rejection reason: {collection_only}"
-    );
-
-    let db = memory_db("transport-target");
-    seed_tickets(&db, 1);
-    let runtime = DecisionTransportRuntime::Recording {
-        metadata: CountingRuntime::new().metadata(),
-        result: DecisionResult::Score {
-            selected: "low".into(),
-            levels: vec![],
-            option_mass: 0.9,
-            supporting_fields: vec![],
-        },
-    };
-    let request = |target: Option<DecisionRecordRef>, context: Option<Value>| {
-        DecisionTransportExecutionRequest {
-            target,
-            context,
-            definition: urgency_definition(),
-            options: DecisionOptions::default(),
-            authorization: None,
-            runtime: runtime.clone(),
-        }
-    };
-
-    let neither = execute_decision_transport(&db, &request(None, None)).expect_err("no target");
-    assert_eq!(neither.code, "DECISION_INVALID_RESULT");
-
-    let both = execute_decision_transport(
-        &db,
-        &request(
-            Some(DecisionRecordRef {
-                collection: "tickets".into(),
-                record_id: "t-0".into(),
-            }),
-            Some(json!({ "urgency": "high" })),
-        ),
-    )
-    .expect_err("two targets");
-    assert_eq!(both.code, "DECISION_INVALID_RESULT");
-}
-
-/// §14 — runtime capabilities describe decision kinds and batching only. No
-/// capability speaks about candidate sets, ordering, filtering, or cursors,
-/// so a runtime cannot currently advertise query composition and a query
-/// surface cannot currently negotiate it.
-#[test]
-fn runtime_capabilities_declare_no_query_composition() {
-    let capabilities =
-        serde_json::to_value(DecisionRuntimeCapabilities::default()).expect("capabilities");
-    let declared = capabilities
-        .as_object()
-        .expect("object")
-        .keys()
-        .cloned()
-        .collect::<BTreeSet<_>>();
-    let expected = [
-        "batch",
-        "binary",
-        "choice",
-        "execution_methods",
-        "probability_distribution",
-        "score",
-    ]
-    .into_iter()
-    .map(String::from)
-    .collect::<BTreeSet<_>>();
-    assert_eq!(declared, expected);
-}
-
-/// §8 / §13 — the record-scoped primitive has no page boundary of its own:
-/// evaluating N records is N calls, nothing in `semantic_decision` filters or
-/// orders judgments, and results come back in request order. The page boundary,
-/// filtering, and ordering belong to `semantic_query`, which consumes this
-/// primitive and never re-implements it. Reuse is the primitive's own bound:
-/// a second pass costs nothing.
-#[test]
-fn record_scoped_evaluation_has_no_page_boundary_and_no_ordering() {
-    let db = memory_db("page-boundary");
-    seed_tickets(&db, 6);
-    let runtime = CountingRuntime::new();
-    let ids = (0..6).map(|index| format!("t-{index}")).collect::<Vec<_>>();
-
-    let first_pass = ids
-        .iter()
-        .map(|id| {
-            decide_record(
-                &db,
-                &DecisionRecordRef {
-                    collection: "tickets".into(),
-                    record_id: id.clone(),
-                },
-                &urgency_definition(),
-                &runtime,
-                &DecisionOptions::default(),
-                None,
-            )
-            .expect("evaluation")
-        })
-        .collect::<Vec<_>>();
-    assert_eq!(runtime.invocations(), ids.len());
-    assert!(first_pass.iter().all(|evaluation| !evaluation.cached));
-
-    let selected = first_pass
-        .iter()
-        .map(|evaluation| match &evaluation.result {
-            DecisionResult::Score { selected, .. } => selected.clone(),
-            other => panic!("unexpected result {other:?}"),
-        })
-        .collect::<Vec<_>>();
-    assert_eq!(selected, ["low", "medium", "high", "low", "medium", "high"]);
-    let mut ordered = selected.clone();
-    ordered.sort_by_key(|level| ["low", "medium", "high"].iter().position(|l| l == level));
-    assert_ne!(
-        selected, ordered,
-        "results come back in request order; nothing in the crate ranks them"
-    );
-
-    for id in &ids {
-        let again = decide_record(
-            &db,
-            &DecisionRecordRef {
-                collection: "tickets".into(),
-                record_id: id.clone(),
-            },
-            &urgency_definition(),
-            &runtime,
-            &DecisionOptions::default(),
-            None,
-        )
-        .expect("reuse");
-        assert!(again.cached);
-        assert_eq!(again.provenance.source, "cache");
-    }
-    assert_eq!(runtime.invocations(), ids.len());
-}
-
-/// §6 — a judgment is durable derived state in the decision collection. The
-/// application record it judged is untouched: same value, same version. A
-/// semantic query must keep this separation; it may write judgments and
-/// nothing else.
-#[test]
-fn judgments_live_beside_application_state_and_never_inside_it() {
-    let db = memory_db("derived-judgment");
-    seed_tickets(&db, 1);
-    let before: Value = db.get("tickets:t-0").expect("get").expect("record");
-
-    let evaluation = decide_record(
-        &db,
-        &DecisionRecordRef {
-            collection: "tickets".into(),
-            record_id: "t-0".into(),
-        },
-        &urgency_definition(),
-        &CountingRuntime::new(),
-        &DecisionOptions::default(),
-        None,
-    )
-    .expect("evaluation");
-
-    let after: Value = db.get("tickets:t-0").expect("get").expect("record");
-    assert_eq!(before, after, "the judged record is not modified");
-
-    let judgments = db
-        .capability(DEFAULT_DECISION_COLLECTION)
-        .find(|_: &feltdb::DecisionJudgmentRecord| true)
-        .expect("judgments");
-    assert_eq!(judgments.len(), 1);
-    assert_eq!(judgments[0].id, evaluation.provenance.cache_key);
-    assert_eq!(judgments[0].collection, "tickets");
-    assert_eq!(judgments[0].record_id, "t-0");
-    assert_eq!(judgments[0].state.reference, "tickets:t-0");
-}