create-feltdb 0.11.4 → 0.11.8

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

@@ -0,0 +1,363 @@
+//! 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");
+}

package/dist/server-source/crates/feltdb-server/src/app_state.rs

@@ -87,6 +87,11 @@ pub struct AppState {
     pub mesh: Arc<std::sync::Mutex<WorkerMeshStore>>,
     pub readiness_probe: Arc<PathBuf>,
     pub bounded_query_cursors: Arc<std::sync::Mutex<HashMap<String, BoundedQueryCursor>>>,
+    /// The deployment's semantic runtime binding for bounded semantic query
+    /// composition, or `None` when the deployment configures no runtime. A
+    /// query never names its runtime; this binding's identity is part of
+    /// every judgment the query stage produces or reuses.
+    pub semantic_runtime: Option<Arc<dyn feltdb::DecisionRuntime + Send + Sync>>,
     /// Bounds how many requests may be in flight at once.
     ///
     /// Every read and write serializes on one lock inside the database, so