create-feltdb 0.11.4 → 0.11.8

package/dist/package-versions.js

@@ -1,4 +1,4 @@
 // One release train keeps generated applications installable. The repository
 // validation script checks these values against every workspace manifest.
-export const FELTDB_PACKAGE_VERSION = '0.11.4';
+export const FELTDB_PACKAGE_VERSION = '0.11.8';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

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

@@ -109,6 +109,7 @@ pub mod replication_manager;
 pub mod replication_protocol;
 mod routing;
 pub mod semantic_decision;
+pub mod semantic_query;
 pub mod sharding;
 pub mod state_conflict_contract;
 pub mod state_contract;
@@ -225,7 +226,8 @@ pub use routing::{
     RouteDecision,
 };
 pub use semantic_decision::{
-    authorize_context, decide_record, decision_cache_key, deterministic_request_key,
+    authorize_context, configured_decision_runtime, decide_record, decision_cache_key,
+    deterministic_request_key, reuse_record_judgment,
     execute_decision_batch, execute_decision_transport, execute_inline_decision_transport, jev,
     run_choice_diagnostics, run_decision_benchmark, validate_decision_definition,
     validate_decision_result, BinaryDecisionResult, ChoiceDecisionResult, ChoiceDiagnosticsReport,
@@ -240,6 +242,13 @@ pub use semantic_decision::{
     DecisionTransportExecutionResponse, DecisionTransportRuntime, DeterministicDecisionRuntime,
     ScoreDecisionResult, WeightedOption, DEFAULT_DECISION_COLLECTION,
 };
+pub use semantic_query::{
+    compose_semantic_page, semantic_clause_hash, semantic_definition_hash,
+    validate_semantic_clause, SemanticAnnotation, SemanticCandidate, SemanticOrderDirection,
+    SemanticPage, SemanticQueryClause, SemanticQueryError, SemanticQueryFilter,
+    SemanticQueryMode, SemanticQueryOrder, SemanticStageSummary, SemanticUnevaluated,
+    SemanticUnevaluatedReason, MAX_SEMANTIC_CANDIDATES,
+};
 pub use sharding::{
     HotspotAlert, RebalanceOperation, ShardDistributionSummary, ShardId, ShardKey, ShardManager,
     ShardMetrics, ShardRange, ShardingStrategy,

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

@@ -4,7 +4,7 @@ use serde::{Deserialize, Serialize};
 use serde_json::{json, Map, Value};
 use sha2::{Digest, Sha256};
 use std::collections::{BTreeMap, BTreeSet};
-use std::sync::Mutex;
+use std::sync::{Arc, Mutex};
 
 pub const DEFAULT_DECISION_COLLECTION: &str = "semantic_decisions";
 
@@ -578,10 +578,18 @@ impl std::fmt::Display for DecisionError {
 
 impl std::error::Error for DecisionError {}
 
-struct TransportAuthorizationGate {
+pub(crate) struct TransportAuthorizationGate {
     allowed_fields: BTreeSet<String>,
 }
 
+impl TransportAuthorizationGate {
+    pub(crate) fn new(allowed_fields: &[String]) -> Self {
+        Self {
+            allowed_fields: allowed_fields.iter().cloned().collect(),
+        }
+    }
+}
+
 impl DecisionAuthorizationGate for TransportAuthorizationGate {
     fn check(
         &self,
@@ -1312,6 +1320,118 @@ fn stored_to_evaluation(
     }
 }
 
+/// The stored judgment whose identity matches `cache_key`, if one exists.
+///
+/// A judgment superseded by an intermediate state change that has since been
+/// reversed carries the same identity as the state it was derived from, so it
+/// is reactivated rather than re-derived: the lineage's other judgments are
+/// superseded and this one becomes active again.
+fn reusable_judgment(
+    db: &FeltDb,
+    storage: &str,
+    cache_key: &str,
+    lineage: &str,
+) -> Result<Option<DecisionJudgmentRecord>, DecisionError> {
+    let Some(mut stored) = load_judgment(db, storage, cache_key)? else {
+        return Ok(None);
+    };
+    if stored.status != DecisionStatus::Active {
+        supersede_lineage(db, storage, lineage, &stored.id)?;
+        stored.status = DecisionStatus::Active;
+        stored.superseded_at = None;
+        update_judgment(db, storage, &stored.id, &stored)?;
+    }
+    Ok(Some(stored))
+}
+
+/// Reuse a durable judgment for a record without invoking the runtime.
+///
+/// This is the `reuse-only` path of semantic query composition: the record is
+/// read and authorized exactly as `decide_record` reads and authorizes it, the
+/// judgment identity is derived from that authorized state and the runtime's
+/// metadata, and the stored judgment is returned when one with that identity
+/// exists. `Ok(None)` means no reusable judgment exists; nothing is executed
+/// and nothing is written except the reactivation described on
+/// `reusable_judgment`.
+pub fn reuse_record_judgment(
+    db: &FeltDb,
+    target: &DecisionRecordRef,
+    definition: &DecisionDefinition,
+    runtime_metadata: &DecisionRuntimeMetadata,
+    options: &DecisionOptions,
+    authorization: Option<(&dyn DecisionAuthorizationGate, &DecisionAuthorizationConfig)>,
+) -> Result<Option<DecisionEvaluation>, DecisionError> {
+    let definition = validate_decision_definition(definition)?;
+    let record: Value = db
+        .capability(&target.collection)
+        .get(&target.record_id)
+        .map_err(|error| DecisionError::new("DECISION_STORAGE_ERROR", error.to_string()))?
+        .ok_or_else(|| {
+            DecisionError::new(
+                "DECISION_RECORD_NOT_FOUND",
+                "decision target record not found",
+            )
+        })?;
+    let context = authorize_context(
+        &target.collection,
+        &target.record_id,
+        &record,
+        options,
+        authorization,
+    )?;
+    if context.fields.is_empty() {
+        return Err(DecisionError::new(
+            "DECISION_CONTEXT_EMPTY",
+            "decision refuses to evaluate an empty authorized context",
+        ));
+    }
+    let cache_key = decision_cache_key(
+        &target.collection,
+        &target.record_id,
+        &definition,
+        &context,
+        runtime_metadata,
+        schema_version(options),
+    );
+    let lineage = lineage_key(
+        &target.collection,
+        &target.record_id,
+        &definition,
+        runtime_metadata,
+        schema_version(options),
+    );
+    Ok(
+        reusable_judgment(db, decision_collection(options), &cache_key, &lineage)?
+            .map(|stored| stored_to_evaluation(stored, &context, "cache")),
+    )
+}
+
+/// Build the runtime binding a FeltDB deployment configures for semantic
+/// query composition.
+///
+/// A query never names its runtime; the deployment does, and the binding's
+/// identity becomes part of every judgment the query stage produces. Only the
+/// deterministic runtime exists in Rust today, so this is the only binding a
+/// deployment can configure; the recording runtime is a transport test double
+/// that answers every request identically and is refused here.
+pub fn configured_decision_runtime(
+    runtime: &DecisionTransportRuntime,
+) -> Result<Arc<dyn DecisionRuntime + Send + Sync>, DecisionError> {
+    match runtime {
+        DecisionTransportRuntime::Deterministic {
+            metadata,
+            responses,
+        } => Ok(Arc::new(DeterministicDecisionRuntime::new(
+            metadata.clone(),
+            responses.clone(),
+        ))),
+        DecisionTransportRuntime::Recording { .. } => Err(DecisionError::new(
+            "DECISION_UNSUPPORTED",
+            "the recording runtime is a transport test double, not a configurable runtime binding",
+        )),
+    }
+}
+
 pub fn decide_record(
     db: &FeltDb,
     target: &DecisionRecordRef,
@@ -1362,13 +1482,7 @@ pub fn decide_record(
         schema_version(options),
     );
     let storage = decision_collection(options);
-    if let Some(mut stored) = load_judgment(db, storage, &cache_key)? {
-        if stored.status != DecisionStatus::Active {
-            supersede_lineage(db, storage, &lineage, &stored.id)?;
-            stored.status = DecisionStatus::Active;
-            stored.superseded_at = None;
-            update_judgment(db, storage, &stored.id, &stored)?;
-        }
+    if let Some(stored) = reusable_judgment(db, storage, &cache_key, &lineage)? {
         return Ok(stored_to_evaluation(stored, &context, "cache"));
     }
 
@@ -1537,9 +1651,7 @@ pub fn execute_inline_decision_transport(
     let runtime = TransportRuntimeHandle::new(&request.runtime);
     let authorization_gate = request.authorization.as_ref().map(|authorization| {
         (
-            TransportAuthorizationGate {
-                allowed_fields: authorization.allowed_fields.iter().cloned().collect(),
-            },
+            TransportAuthorizationGate::new(&authorization.allowed_fields),
             DecisionAuthorizationConfig {
                 principal: authorization.principal.clone(),
             },