create-feltdb 0.11.3 → 0.11.7

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

@@ -740,6 +740,12 @@ pub struct CanonicalQuery {
     pub aggregates: Vec<AggregateDefinition>,
     #[serde(default)]
     pub references: Vec<QueryReference>,
+    /// A semantic clause is a recognized query concept that this surface does
+    /// not compose. It is carried through deserialization so `execute_query`
+    /// can refuse it with a structured failure instead of an unknown key
+    /// silently disappearing; see `docs/reference/semantic-query.md`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub semantic: Option<Value>,
 }
 /// Actual execution timing measurements for a query.
 /// All fields are MEASURED using Instant::now(), not estimated or derived.
@@ -1198,6 +1204,20 @@ pub fn execute_query(
 ) -> Result<QueryResult, StateFailure> {
     let query_start = Instant::now();
 
+    // Fail closed on semantic intent before any deterministic work. Every query
+    // surface must either implement a recognized semantic clause per the
+    // semantic-query contract or refuse it; this surface refuses, and it never
+    // answers the deterministic part as though the clause had been absent.
+    if let Some(clause) = &query.semantic {
+        return Err(if clause.is_object() {
+            StateFailure::new(
+                "SEMANTIC_UNSUPPORTED",
+                "canonical queries recognize the semantic clause but do not compose semantic decisions; use the bounded authority query",
+            )
+        } else {
+            StateFailure::new("INVALID_QUERY", "semantic clause must be an object")
+        });
+    }
     if query.limit == Some(0) || query.limit.is_some_and(|limit| limit > 1000) {
         return Err(StateFailure::new(
             "INVALID_QUERY",
@@ -3205,6 +3225,7 @@ mod tests {
                     field: None,
                 }],
                 references: vec![],
+                semantic: None,
             },
             None,
         )
@@ -3236,6 +3257,7 @@ mod tests {
                 group_by: vec![],
                 aggregates: vec![],
                 references: vec![],
+                semantic: None,
             },
             None,
         )
@@ -3498,6 +3520,7 @@ mod tests {
                 group_by: vec![],
                 aggregates: vec![],
                 references: vec![],
+                semantic: None,
             },
             None,
         )
@@ -3592,6 +3615,7 @@ mod tests {
                 group_by: vec![],
                 aggregates: vec![],
                 references: vec![],
+                semantic: None,
             },
             None,
         )
@@ -3654,6 +3678,7 @@ mod tests {
                 group_by: vec![],
                 aggregates: vec![],
                 references: vec![],
+                semantic: None,
             },
             None,
         )
@@ -3715,6 +3740,7 @@ mod tests {
                 group_by: vec![],
                 aggregates: vec![],
                 references: vec![],
+                semantic: None,
             },
             None,
         )
@@ -3774,6 +3800,7 @@ mod tests {
                 group_by: vec![],
                 aggregates: vec![],
                 references: vec![],
+                semantic: None,
             },
             None,
         )
@@ -3834,6 +3861,7 @@ mod tests {
             group_by: vec![],
             aggregates: vec![],
             references: vec![],
+            semantic: None,
         };
         let mut ids = Vec::new();
         let first_cursor = loop {
@@ -3888,6 +3916,186 @@ mod tests {
         );
     }
 
+    /// Every query surface must either implement a recognized semantic clause
+    /// per `docs/reference/semantic-query.md` or refuse it. This surface
+    /// refuses: a semantic clause is `SEMANTIC_UNSUPPORTED` before any
+    /// deterministic work, a malformed one is `INVALID_QUERY`, nothing is
+    /// read, nothing is judged, and the same query without the clause still
+    /// answers.
+    #[test]
+    fn semantic_clause_is_recognized_and_refused_never_ignored() {
+        let db = db("semantic-refusal");
+        let schema = schema();
+        execute_transaction(
+            &db,
+            &schema,
+            &TransactionRequest {
+                transaction_id: Some("seed".into()),
+                tenant_id: "tenant".into(),
+                application_id: "app".into(),
+                revision_id: "rev".into(),
+                schema_version: 1,
+                state_namespace: None,
+                causal_parent: None,
+                authorization: auth(),
+                preconditions: vec![],
+                operations: vec![TransactionOperation {
+                    kind: TransactionOperationKind::Insert,
+                    collection: "incidents".into(),
+                    id: "i1".into(),
+                    value: serde_json::json!({ "title": "First", "status": "open" }),
+                    if_version: None,
+                }],
+            },
+            None,
+        )
+        .unwrap();
+        let context = begin_query_read(&db, &schema, "app", auth()).unwrap();
+        let plain = CanonicalQuery {
+            collection: "incidents".into(),
+            filter: Some(QueryFilter::Eq {
+                field: "status".into(),
+                value: Value::String("open".into()),
+            }),
+            order_by: vec![],
+            limit: Some(10),
+            offset: 0,
+            cursor: None,
+            projection: vec![],
+            group_by: vec![],
+            aggregates: vec![],
+            references: vec![],
+            semantic: None,
+        };
+        let state_before = db.state_rows().unwrap().len();
+
+        // A semantic clause in the bounded query's own grammar, and one that
+        // only expresses semantic intent, are both recognized and refused.
+        for clause in [
+            serde_json::json!({
+                "decision": { "kind": "binary", "predicate": "needs a human" },
+                "filter": { "is": true },
+            }),
+            serde_json::json!({ "decision": "needs_human" }),
+            serde_json::json!({}),
+        ] {
+            let failure = execute_query(
+                &db,
+                &schema,
+                &context,
+                &CanonicalQuery {
+                    semantic: Some(clause),
+                    ..plain.clone()
+                },
+                None,
+            )
+            .expect_err("semantic intent is never silently dropped");
+            assert_eq!(failure.code, "SEMANTIC_UNSUPPORTED");
+        }
+
+        // A semantic value that is not a clause is a validation error, not a
+        // recognized-but-unsupported operation.
+        for malformed in [
+            serde_json::json!("yes"),
+            serde_json::json!(true),
+            serde_json::json!(1),
+            serde_json::json!(["needs_human"]),
+        ] {
+            let failure = execute_query(
+                &db,
+                &schema,
+                &context,
+                &CanonicalQuery {
+                    semantic: Some(malformed),
+                    ..plain.clone()
+                },
+                None,
+            )
+            .expect_err("a malformed semantic value is invalid");
+            assert_eq!(failure.code, "INVALID_QUERY");
+        }
+
+        // The clause is refused ahead of every other validation, so a query
+        // that is also otherwise invalid still fails on semantic intent.
+        let failure = execute_query(
+            &db,
+            &schema,
+            &context,
+            &CanonicalQuery {
+                semantic: Some(serde_json::json!({ "decision": "needs_human" })),
+                limit: Some(0),
+                ..plain.clone()
+            },
+            None,
+        )
+        .unwrap_err();
+        assert_eq!(failure.code, "SEMANTIC_UNSUPPORTED");
+
+        // Refusal reads nothing, judges nothing, and writes nothing: no
+        // judgment collection appears and the state is what it was.
+        assert_eq!(db.state_rows().unwrap().len(), state_before);
+        let judgments: Vec<Value> = db
+            .capability(crate::semantic_decision::DEFAULT_DECISION_COLLECTION)
+            .find(|_: &Value| true)
+            .unwrap();
+        assert!(judgments.is_empty());
+
+        // The same query without the clause answers as before.
+        let page = execute_query(&db, &schema, &context, &plain, None).unwrap();
+        assert_eq!(page.records.len(), 1);
+    }
+
+    /// Over the wire, `semantic` is carried into the query rather than lost
+    /// as an unknown key, `null` means absent, and an unrelated unknown key
+    /// keeps its existing behavior of being ignored: only semantic intent is
+    /// recognized, because only semantic intent changes what a query means.
+    #[test]
+    fn semantic_clause_survives_deserialization_and_changes_query_identity() {
+        let plain: CanonicalQuery = serde_json::from_value(serde_json::json!({
+            "collection": "incidents",
+            "limit": 10,
+        }))
+        .unwrap();
+        assert!(plain.semantic.is_none());
+        let with_clause: CanonicalQuery = serde_json::from_value(serde_json::json!({
+            "collection": "incidents",
+            "limit": 10,
+            "semantic": { "decision": "needs_human" },
+        }))
+        .unwrap();
+        assert_eq!(
+            with_clause.semantic,
+            Some(serde_json::json!({ "decision": "needs_human" }))
+        );
+        assert_ne!(
+            query_hash(&plain).unwrap(),
+            query_hash(&with_clause).unwrap(),
+            "a semantic clause is part of what the query is"
+        );
+        let malformed: CanonicalQuery = serde_json::from_value(serde_json::json!({
+            "collection": "incidents",
+            "semantic": "yes",
+        }))
+        .unwrap();
+        assert_eq!(malformed.semantic, Some(Value::String("yes".into())));
+        let null: CanonicalQuery = serde_json::from_value(serde_json::json!({
+            "collection": "incidents",
+            "semantic": null,
+        }))
+        .unwrap();
+        assert!(null.semantic.is_none());
+        let unrelated: CanonicalQuery = serde_json::from_value(serde_json::json!({
+            "collection": "incidents",
+            "limit": 10,
+            "refill": true,
+        }))
+        .unwrap();
+        assert_eq!(query_hash(&unrelated).unwrap(), query_hash(&plain).unwrap());
+        // Serialization of a query without a clause is unchanged, so every
+        // existing query hash and cursor binding is unchanged.
+        assert!(!serde_json::to_string(&plain).unwrap().contains("semantic"));
+    }
+
     #[test]
     fn scoped_index_work_is_independent_of_unrelated_growth() {
         fn examined(unrelated: usize) -> usize {
@@ -3941,6 +4149,7 @@ mod tests {
                     group_by: vec![],
                     aggregates: vec![],
                     references: vec![],
+                    semantic: None,
                 },
                 None,
             )
@@ -4002,6 +4211,7 @@ mod tests {
                 group_by: vec![],
                 aggregates: vec![],
                 references: vec![],
+                semantic: None,
             },
             None,
         )
@@ -4143,6 +4353,7 @@ mod tests {
                     group_by: vec![],
                     aggregates: vec![],
                     references: vec![],
+                    semantic: None,
                 },
                 None,
             )
@@ -4208,6 +4419,7 @@ mod tests {
             group_by: vec![],
             aggregates: vec![],
             references: vec![],
+            semantic: None,
         };
 
         let result = execute_query(&db, &schema, &context, &query, None);
@@ -4246,6 +4458,7 @@ mod tests {
             group_by: vec![],
             aggregates: vec![],
             references: vec![],
+            semantic: None,
         };
 
         let result = execute_query(&db, &schema, &context, &query, None);
@@ -4357,6 +4570,7 @@ mod tests {
             group_by: vec![],
             aggregates: vec![],
             references: vec![],
+            semantic: None,
         };
 
         let result = execute_query(&db, &schema, &context, &query, None);
@@ -4456,6 +4670,7 @@ mod tests {
             group_by: vec![],
             aggregates: vec![],
             references: vec![],
+            semantic: None,
         };
 
         let result = execute_query(&db, &schema, &context, &query, None);
@@ -4587,6 +4802,7 @@ mod tests {
             group_by: vec![],
             aggregates: vec![],
             references: vec![],
+            semantic: None,
         };
 
         let verify_result =
@@ -4705,6 +4921,7 @@ mod tests {
             group_by: vec![],
             aggregates: vec![],
             references: vec![],
+            semantic: None,
         };
 
         let result = execute_query(&db, &schema, &read_context, &query, None);
@@ -4743,6 +4960,7 @@ mod tests {
             group_by: vec![],
             aggregates: vec![],
             references: vec![],
+            semantic: None,
         };
 
         let result = execute_query(&db, &schema, &read_context, &query, None);
@@ -5009,6 +5227,7 @@ mod tests {
             group_by: vec![],
             aggregates: vec![],
             references: vec![],
+            semantic: None,
         };
 
         let alice_result = execute_query(
@@ -5104,6 +5323,7 @@ mod tests {
             group_by: vec![],
             aggregates: vec![],
             references: vec![],
+            semantic: None,
         };
 
         let result = execute_query(
@@ -5191,6 +5411,7 @@ mod tests {
             group_by: vec![],
             aggregates: vec![],
             references: vec![],
+            semantic: None,
         };
 
         let result = execute_query(
@@ -5280,6 +5501,7 @@ mod tests {
             group_by: vec![],
             aggregates: vec![],
             references: vec![],
+            semantic: None,
         };
 
         let result = execute_query(

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

@@ -336,6 +336,7 @@ fn pr7_phase3_self_authorization_proof() -> Result<(), Box<dyn std::error::Error
         group_by: vec![],
         aggregates: vec![],
         references: vec![],
+        semantic: None,
     };
 
     // We'll need to manually filter since the policy evaluation isn't automatic in tests

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

@@ -361,6 +361,7 @@ fn saas_invitation_lifecycle_phase_3_capability_gap_detection(
         group_by: vec![],
         aggregates: vec![],
         references: vec![],
+        semantic: None,
     };
 
     let result =