create-feltdb 0.11.4 → 0.11.8

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

@@ -75,7 +75,7 @@ use feltdb_server::{
     authenticated_principal::AuthenticatedPrincipal,
     authorization::{authorize, AuthorizationRequest, Subject},
     backup::{
-        create_bundle, create_bundle_with_virtual, restore_bundle, select_bundle_at,
+        restore_bundle, select_bundle_at,
         server_artifacts, verify_bundle,
     },
     causal::{
@@ -7303,6 +7303,7 @@ async fn run_runtime_query(
         group_by: vec![],
         aggregates: vec![],
         references: vec![],
+        semantic: None,
     };
     let context = feltdb::state_contract::begin_query_read(
         &state.db,
@@ -7555,6 +7556,7 @@ fn state_contract_error(error: feltdb::state_contract::StateFailure) -> ApiError
         "AUTHORIZATION_DENIED" => StatusCode::FORBIDDEN,
         "PRECONDITION_FAILED" | "CONFLICT" | "IDEMPOTENCY_CONFLICT" => StatusCode::CONFLICT,
         "UNKNOWN_COLLECTION" => StatusCode::NOT_FOUND,
+        "SEMANTIC_UNSUPPORTED" => StatusCode::NOT_IMPLEMENTED,
         "STORAGE_FAILURE" | "STATE_UNAVAILABLE" => StatusCode::SERVICE_UNAVAILABLE,
         _ => StatusCode::UNPROCESSABLE_ENTITY,
     };
@@ -8527,6 +8529,9 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     if manage_backup()? {
         return Ok(());
     }
+    if manage_doctor()? {
+        return Ok(());
+    }
     if manage_application_runtime()? {
         return Ok(());
     }
@@ -8675,6 +8680,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         mesh: Arc::new(std::sync::Mutex::new(mesh_store)),
         readiness_probe: Arc::new(readiness_probe),
         bounded_query_cursors: Arc::new(std::sync::Mutex::new(HashMap::new())),
+        semantic_runtime: configured_semantic_runtime()?,
     };
     start_peer_sessions(&state, &config)?;
     start_membership_recovery(&state);
@@ -9986,8 +9992,16 @@ async fn health_ready(State(state): State<AppState>) -> axum::response::Response
     match outcome {
         Ok(Ok(Ok(health))) => {
             let ready = health.is_nominal();
+            let recovering = matches!(
+                state.cluster.proposal().map(|value| value.phase),
+                Some(ProposalPhase::Preparing | ProposalPhase::Prepared)
+            );
             let body = Json(json!({
                 "ready": ready,
+                // The explicit health model. A running server has already
+                // refused a corrupt or incompatible log at open, so `corrupt`
+                // is reported offline by `feltdb-server doctor`, never here.
+                "state": if !ready { "degraded" } else if recovering { "recovering" } else { "healthy" },
                 "storage": health.storage.label(),
                 "durable_format": health.durable_format.to_string(),
                 "probe_ms": waited_ms,
@@ -10003,6 +10017,7 @@ async fn health_ready(State(state): State<AppState>) -> axum::response::Response
             StatusCode::SERVICE_UNAVAILABLE,
             Json(json!({
                 "ready": false,
+                "state": "unavailable",
                 "error": error.to_string(),
                 "code": "STORAGE_UNAVAILABLE",
                 "probe_ms": waited_ms,
@@ -10013,6 +10028,7 @@ async fn health_ready(State(state): State<AppState>) -> axum::response::Response
             StatusCode::SERVICE_UNAVAILABLE,
             Json(json!({
                 "ready": false,
+                "state": "unavailable",
                 "error": error.to_string(),
                 "code": "STORAGE_PROBE_FAILED",
                 "probe_ms": waited_ms,
@@ -10023,6 +10039,7 @@ async fn health_ready(State(state): State<AppState>) -> axum::response::Response
             StatusCode::SERVICE_UNAVAILABLE,
             Json(json!({
                 "ready": false,
+                "state": "unavailable",
                 "error": "storage probe exceeded the server deadline",
                 "code": "STORAGE_STALLED",
                 "probe_ms": waited_ms,
@@ -10367,7 +10384,6 @@ fn manage_backup() -> Result<bool, Box<dyn std::error::Error>> {
     if arguments.get(1).map(String::as_str) != Some("backup") {
         return Ok(false);
     }
-    let command = arguments.get(2).map(String::as_str).unwrap_or("");
     let option = |name: &str| {
         arguments
             .iter()
@@ -10375,27 +10391,105 @@ fn manage_backup() -> Result<bool, Box<dyn std::error::Error>> {
             .and_then(|index| arguments.get(index + 1))
             .cloned()
     };
+    let json_output = arguments.iter().any(|value| value == "--json");
+    // `backup <path>` is `backup create --output <path>`; `backup verify <path>`
+    // is `backup verify --archive <path>`. The flag forms remain supported.
+    let positional = |from: usize| {
+        let mut index = from;
+        while let Some(value) = arguments.get(index) {
+            if value == "--json" {
+                index += 1;
+            } else if value.starts_with("--") {
+                index += 2;
+            } else {
+                return Some(value.clone());
+            }
+        }
+        None
+    };
+    let (command, target) = match arguments.get(2).map(String::as_str) {
+        Some(command @ ("create" | "verify" | "restore")) => (command, positional(3)),
+        Some(value) if !value.starts_with("--") => ("create", Some(value.to_string())),
+        _ if option("--output").is_some() && option("--archive").is_none() => ("create", None),
+        _ => ("", None),
+    };
+    let usage = "usage: feltdb-server backup [create] <output> | backup verify <archive> | backup restore --archive <archive> --output <directory> [--at-ms timestamp]  (options: --data path --keys path --audit path --json)";
+    let started = Instant::now();
+    let emit = |report: &feltdb_server::backup::BackupReport, human: String| {
+        if json_output {
+            println!("{}", serde_json::to_string_pretty(report).unwrap_or_default());
+        } else if report.status == "ok" {
+            println!("{human}");
+        } else {
+            eprintln!(
+                "Backup {} failed: {} ({})",
+                report.operation,
+                report.path,
+                report.error.as_deref().unwrap_or("unknown error")
+            );
+        }
+    };
     match command {
         "create" => {
             let data = PathBuf::from(option("--data").unwrap_or_else(|| "./data/feltdb.log".into()));
             let keys = PathBuf::from(option("--keys").unwrap_or_else(|| "./data/api-keys.json".into()));
             let audit = PathBuf::from(option("--audit").unwrap_or_else(|| data.with_extension("audit.log").to_string_lossy().into_owned()));
-            let output = PathBuf::from(option("--output").ok_or("backup create requires --output")?);
-            let manifest = create_bundle(&output, &server_artifacts(&data, &keys, &audit))?;
-            println!("Backup created: {} (format {}, {} files)", output.display(), manifest.format, manifest.entries.len());
+            let output = option("--output").or(target).ok_or("backup create requires an output path")?;
+            let output = feltdb_server::backup::normalize_path(std::path::Path::new(&output))?;
+            let data = feltdb_server::backup::normalize_path(&data)?;
+            if !data.exists() {
+                return Err(format!("backup source does not exist: {}", data.display()).into());
+            }
+            let source = feltdb_server::backup::BackupSource {
+                data: Some(data.display().to_string()),
+                state_sha256: None,
+                server_version: Some(env!("CARGO_PKG_VERSION").into()),
+                durable_format: Some(feltdb::DURABLE_FORMAT_VERSION),
+            };
+            feltdb_server::backup::create_bundle_with_source(&output, &server_artifacts(&data, &keys, &audit), &[], source)?;
+            // A backup is reported as successful only after it verifies
+            // independently of the code path that wrote it.
+            let mut report = feltdb_server::backup::verification_report(&output, started, "create");
+            if report.status == "ok" {
+                if let Err(error) = verify_restorable(&output) {
+                    report.status = "failed".into();
+                    report.verification = "failed".into();
+                    report.error = Some(error.to_string());
+                }
+            }
+            let human = format!("Backup created: {} (id {}, format {}, {} files, {} bytes, verified, {} ms)", report.path, &report.backup_id[..report.backup_id.len().min(12)], report.format, report.files, report.bytes_written, report.duration_ms);
+            emit(&report, human);
+            if report.status != "ok" {
+                std::process::exit(1);
+            }
         }
         "verify" => {
-            let archive = PathBuf::from(option("--archive").ok_or("backup verify requires --archive")?);
-            let manifest = verify_bundle(&archive)?;
-            println!("Backup verified: {} (format {}, {} files)", archive.display(), manifest.format, manifest.entries.len());
+            let archive = option("--archive").or(target).ok_or("backup verify requires an archive path")?;
+            let mut report = feltdb_server::backup::verification_report(std::path::Path::new(&archive), started, "verify");
+            let mut restorable = None;
+            if report.status == "ok" {
+                match verify_restorable(std::path::Path::new(&report.path)) {
+                    Ok(detail) => restorable = Some(detail),
+                    Err(error) => {
+                        report.status = "failed".into();
+                        report.verification = "failed".into();
+                        report.error = Some(error.to_string());
+                    }
+                }
+            }
+            let human = format!("Backup verified: {} (id {}, format {}, {} files, {} bytes{})", report.path, &report.backup_id[..report.backup_id.len().min(12)], report.format, report.files, report.bytes_written, restorable.map(|detail| format!(", {detail}")).unwrap_or_default());
+            emit(&report, human);
+            if report.status != "ok" {
+                std::process::exit(1);
+            }
         }
         "restore" => {
-            let archive = PathBuf::from(option("--archive").ok_or("backup restore requires --archive")?);
+            let archive = PathBuf::from(option("--archive").or(target).ok_or("backup restore requires --archive")?);
             let archive = match option("--at-ms") {
                 Some(value) => select_bundle_at(&archive, value.parse().map_err(|_| "backup restore --at-ms must be an unsigned millisecond timestamp")?)?,
                 None => archive,
             };
-            let output = PathBuf::from(option("--output").ok_or("backup restore requires --output")?);
+            let output = feltdb_server::backup::normalize_path(std::path::Path::new(&option("--output").ok_or("backup restore requires --output")?))?;
             let manifest = restore_bundle(&archive, &output)?;
             let snapshot_path = output.join("files/database.snapshot.json");
             if snapshot_path.exists() {
@@ -10403,13 +10497,199 @@ fn manage_backup() -> Result<bool, Box<dyn std::error::Error>> {
                 let database = FeltDb::open(output.join("files/state.log"))?;
                 database.install_snapshot(snapshot)?;
             }
-            println!("Backup restored: {} (format {}, {} files)", output.display(), manifest.format, manifest.entries.len());
+            let mut report = feltdb_server::backup::verification_report(&archive, started, "restore");
+            report.path = output.display().to_string();
+            emit(&report, format!("Backup restored: {} (format {}, {} files)", output.display(), manifest.format, manifest.entries.len()));
+            if report.status != "ok" {
+                std::process::exit(1);
+            }
         }
-        _ => return Err("usage: feltdb-server backup <create|verify|restore> [--data path] [--keys path] [--audit path] --output directory | --archive directory [--at-ms timestamp]".into()),
+        _ => return Err(usage.into()),
     }
     Ok(true)
 }
 
+/// `feltdb-server doctor` — what an operator needs to know, offline.
+///
+/// Answers, for a data path: is the database healthy; is the durable log
+/// valid; what state/version is it in; is recovery pending; can a backup be
+/// created; can that backup be restored; which server and format versions are
+/// active. It never opens the live files: the state is bundled exactly as
+/// `backup create` would, and every probe — open, read, write — runs against a
+/// private restored copy. `--backup <archive>` additionally verifies an
+/// existing bundle.
+///
+/// The health state is one of `healthy`, `recovering`, `degraded`,
+/// `unavailable`, or `corrupt`, and `healthy` requires every probe to pass:
+/// a readable durable log in a supported format, a clean replay, a working
+/// read, a working write, and a restorable backup.
+fn manage_doctor() -> Result<bool, Box<dyn std::error::Error>> {
+    let arguments: Vec<String> = std::env::args().collect();
+    if arguments.get(1).map(String::as_str) != Some("doctor") {
+        return Ok(false);
+    }
+    let option = |name: &str| {
+        arguments
+            .iter()
+            .position(|value| value == name)
+            .and_then(|index| arguments.get(index + 1))
+            .cloned()
+    };
+    let json_output = arguments.iter().any(|value| value == "--json");
+    let data = feltdb_server::backup::normalize_path(&PathBuf::from(
+        option("--data").unwrap_or_else(|| "./data/feltdb.log".into()),
+    ))?;
+    let keys = PathBuf::from(option("--keys").unwrap_or_else(|| "./data/api-keys.json".into()));
+    let audit = PathBuf::from(option("--audit").unwrap_or_else(|| data.with_extension("audit.log").to_string_lossy().into_owned()));
+
+    let mut checks: Vec<Value> = Vec::new();
+    let mut check = |name: &str, ok: bool, detail: String| {
+        checks.push(json!({ "name": name, "status": if ok { "PASS" } else { "FAIL" }, "detail": detail }));
+        ok
+    };
+    let scratch = std::env::temp_dir().join(format!(
+        "feltdb-doctor-{}-{}",
+        std::process::id(),
+        rand::random::<u64>()
+    ));
+    let bundle = scratch.join("bundle");
+    let restored = scratch.join("restored");
+    let mut state = "healthy";
+    let mut facts = json!({
+        "data": data.display().to_string(),
+        "server_version": env!("CARGO_PKG_VERSION"),
+        "supported_durable_format": feltdb::DURABLE_FORMAT_VERSION,
+        "backup_format": feltdb_server::backup::BACKUP_FORMAT,
+    });
+
+    if !check("data present", data.exists(), data.display().to_string()) {
+        state = "unavailable";
+    } else {
+        std::fs::create_dir_all(&scratch)?;
+        let source = feltdb_server::backup::BackupSource {
+            data: Some(data.display().to_string()),
+            state_sha256: None,
+            server_version: Some(env!("CARGO_PKG_VERSION").into()),
+            durable_format: Some(feltdb::DURABLE_FORMAT_VERSION),
+        };
+        let bundled = feltdb_server::backup::create_bundle_with_source(&bundle, &server_artifacts(&data, &keys, &audit), &[], source);
+        if !check("backup can be created", bundled.is_ok(), bundled.as_ref().map(|manifest| format!("{} files", manifest.entries.len())).unwrap_or_else(|error| error.to_string())) {
+            state = "unavailable";
+        } else {
+            let restorable = restore_bundle(&bundle, &restored);
+            check("backup can be restored", restorable.is_ok(), restorable.as_ref().map(|_| "restored to a private copy".to_string()).unwrap_or_else(|error| error.to_string()));
+            match FeltDb::open(restored.join("files/state.log")) {
+                Err(error) => {
+                    let corrupt = matches!(error, feltdb::FlowError::CorruptLogLine(_) | feltdb::FlowError::IncompatibleFormat(_));
+                    check("durable log valid", false, error.to_string());
+                    state = if corrupt { "corrupt" } else { "unavailable" };
+                }
+                Ok(database) => {
+                    let health = database.health();
+                    facts["durable_format"] = json!(health.durable_format.to_string());
+                    facts["storage"] = json!(health.storage.label());
+                    facts["recovery"] = json!(health.recovery.to_string());
+                    facts["sequence"] = json!(database.sequence().unwrap_or(0));
+                    check("durable log valid", true, format!("durable format {}", health.durable_format));
+                    if !check("replay clean", health.storage.is_clean(), health.recovery.to_string()) {
+                        state = "degraded";
+                    }
+                    let read = database.list_collection_page("_flow_capabilities", None, 1);
+                    if !check("read path", read.is_ok(), read.as_ref().map(|_| "bounded read succeeded".to_string()).unwrap_or_else(|error| error.to_string())) {
+                        state = "unavailable";
+                    }
+                    let probe_key = "_feltdb_doctor:probe";
+                    let wrote = database
+                        .insert(probe_key, json!({ "probe": true }))
+                        .and_then(|_| database.get_value(probe_key))
+                        .map(|value| value.is_some());
+                    if !check("mutation path", matches!(wrote, Ok(true)), match &wrote { Ok(true) => "write and read-back on the private copy".into(), Ok(false) => "write was not readable".into(), Err(error) => error.to_string() }) {
+                        state = "unavailable";
+                    }
+                }
+            }
+        }
+        if let Ok(cluster) = ClusterStore::load(data.with_extension("cluster.json"), Vec::new()) {
+            let pending = matches!(cluster.proposal().map(|value| value.phase), Some(ProposalPhase::Preparing | ProposalPhase::Prepared));
+            facts["pending_recovery"] = json!(pending);
+            check("no pending membership recovery", !pending, if pending { "a membership change is mid-flight".into() } else { "none".into() });
+            if pending && state == "healthy" {
+                state = "recovering";
+            }
+        }
+    }
+    if let Some(archive) = option("--backup") {
+        let started = Instant::now();
+        let report = feltdb_server::backup::verification_report(std::path::Path::new(&archive), started, "verify");
+        let restorable = if report.status == "ok" { verify_restorable(std::path::Path::new(&report.path)).map_err(|error| error.to_string()) } else { Err(report.error.clone().unwrap_or_default()) };
+        check("supplied backup restorable", restorable.is_ok(), restorable.unwrap_or_else(|error| error));
+        facts["backup"] = json!(report);
+    }
+    let _ = std::fs::remove_dir_all(&scratch);
+    let healthy_requires_all = checks.iter().all(|entry| entry["status"] == "PASS");
+    if state == "healthy" && !healthy_requires_all {
+        state = "degraded";
+    }
+    let report = json!({ "command": "doctor", "state": state, "facts": facts, "checks": checks });
+    if json_output {
+        println!("{}", serde_json::to_string_pretty(&report)?);
+    } else {
+        println!("FeltDB doctor: {state}");
+        for entry in report["checks"].as_array().into_iter().flatten() {
+            println!("  {} {}: {}", if entry["status"] == "PASS" { "✓" } else { "✗" }, entry["name"].as_str().unwrap_or(""), entry["detail"].as_str().unwrap_or(""));
+        }
+    }
+    if state != "healthy" {
+        std::process::exit(1);
+    }
+    Ok(true)
+}
+
+/// Prove a bundle restores into a database this build can open.
+///
+/// Checksums prove the bytes are the ones recorded; they cannot prove the
+/// recorded bytes are a FeltDB database in a format this build understands.
+/// This restores into a private temporary directory, opens it, and reads it —
+/// the same path `backup restore` and a subsequent server start take — and
+/// never touches the bundle or any live database.
+fn verify_restorable(archive: &std::path::Path) -> Result<String, Box<dyn std::error::Error>> {
+    let manifest = verify_bundle(archive)?;
+    let has_log = manifest.entries.iter().any(|entry| entry.path == "files/state.log");
+    let has_snapshot = manifest
+        .entries
+        .iter()
+        .any(|entry| entry.path == "files/database.snapshot.json");
+    if !has_log && !has_snapshot {
+        return Err("backup holds no authoritative state (neither state.log nor database.snapshot.json)".into());
+    }
+    let scratch = std::env::temp_dir().join(format!(
+        "feltdb-backup-verify-{}-{}",
+        std::process::id(),
+        rand::random::<u64>()
+    ));
+    let restored = scratch.join("restored");
+    let result = (|| -> Result<String, Box<dyn std::error::Error>> {
+        std::fs::create_dir_all(&scratch)?;
+        restore_bundle(archive, &restored)?;
+        let database = FeltDb::open(restored.join("files/state.log"))?;
+        if has_snapshot {
+            let snapshot: DatabaseSnapshot = serde_json::from_slice(&std::fs::read(
+                restored.join("files/database.snapshot.json"),
+            )?)?;
+            database.install_snapshot(snapshot)?;
+        }
+        let health = database.health();
+        Ok(format!(
+            "restorable: durable format {}, storage {}, sequence {}",
+            health.durable_format,
+            health.storage.label(),
+            database.sequence()?
+        ))
+    })();
+    let _ = std::fs::remove_dir_all(&scratch);
+    result
+}
+
 fn manage_application_runtime() -> Result<bool, Box<dyn std::error::Error>> {
     let arguments: Vec<String> = std::env::args().collect();
     if arguments.get(1).map(String::as_str) != Some("app") {
@@ -10512,12 +10792,24 @@ async fn create_online_backup(
         .cloned()
         .collect();
     let output = PathBuf::from(request.output);
+    let source = feltdb_server::backup::BackupSource {
+        data: state
+            .backup_artifacts
+            .iter()
+            .find(|(label, _)| label == "state.log")
+            .and_then(|(_, path)| feltdb_server::backup::normalize_path(path).ok())
+            .map(|path| path.display().to_string()),
+        state_sha256: None,
+        server_version: Some(env!("CARGO_PKG_VERSION").into()),
+        durable_format: Some(feltdb::DURABLE_FORMAT_VERSION),
+    };
     let manifest = tokio::task::spawn_blocking(move || {
         let _guard = guard;
-        create_bundle_with_virtual(
+        feltdb_server::backup::create_bundle_with_source(
             &output,
             &artifacts,
             &[("database.snapshot.json".to_string(), snapshot_bytes)],
+            source,
         )
     })
     .await
@@ -12759,6 +13051,11 @@ struct BoundedQueryRequest {
     limit: usize,
     #[serde(default)]
     cursor: Option<String>,
+    /// Semantic composition over the deterministic page, per
+    /// `docs/reference/semantic-query.md`. Bound into the request hash so a
+    /// continuation cursor is valid only under the clause it was issued for.
+    #[serde(default)]
+    semantic: Option<feltdb::SemanticQueryClause>,
 }
 
 #[derive(Clone, Deserialize, Serialize)]
@@ -12781,6 +13078,63 @@ struct BoundedQueryPage {
     #[serde(skip_serializing_if = "Option::is_none")]
     next_cursor: Option<String>,
     exhausted: bool,
+    /// Present exactly when the request carried a semantic clause. Its
+    /// `annotations` align with `records`.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    semantic: Option<BoundedQuerySemanticResult>,
+}
+
+#[derive(Serialize)]
+struct BoundedQuerySemanticResult {
+    complete: bool,
+    stage: feltdb::SemanticStageSummary,
+    annotations: Vec<Option<feltdb::SemanticAnnotation>>,
+    unevaluated: Vec<feltdb::SemanticUnevaluated>,
+}
+
+/// The deployment's semantic runtime binding, from `FELTDB_SEMANTIC_RUNTIME`.
+///
+/// The variable names a JSON file in the semantic-decision transport's runtime
+/// shape (`{"kind": "deterministic", "metadata": {...}, "responses": {...}}`).
+/// A deployment that sets nothing has no binding, and every semantic query
+/// fails with `SEMANTIC_PROVIDER_UNAVAILABLE` rather than answering the
+/// deterministic part as if the clause had been honored. A file that cannot be
+/// read or parsed is a startup failure: a misconfigured binding must not look
+/// like an unconfigured one.
+fn configured_semantic_runtime(
+) -> Result<Option<Arc<dyn feltdb::DecisionRuntime + Send + Sync>>, String> {
+    let Ok(path) = std::env::var("FELTDB_SEMANTIC_RUNTIME") else {
+        return Ok(None);
+    };
+    let source = std::fs::read_to_string(&path)
+        .map_err(|error| format!("FELTDB_SEMANTIC_RUNTIME {path} is unreadable: {error}"))?;
+    let runtime: feltdb::DecisionTransportRuntime =
+        serde_json::from_str(&source).map_err(|error| {
+            format!("FELTDB_SEMANTIC_RUNTIME {path} is not a runtime binding: {error}")
+        })?;
+    feltdb::configured_decision_runtime(&runtime)
+        .map(Some)
+        .map_err(|error| format!("FELTDB_SEMANTIC_RUNTIME {path} is refused: {error}"))
+}
+
+fn semantic_query_error(error: feltdb::SemanticQueryError) -> ApiError {
+    let status = match error.code.as_str() {
+        "INVALID_QUERY" | "INVALID_CURSOR" => StatusCode::UNPROCESSABLE_ENTITY,
+        "SEMANTIC_PROVIDER_UNAVAILABLE" | "DECISION_STORAGE_ERROR" => {
+            StatusCode::SERVICE_UNAVAILABLE
+        }
+        "SEMANTIC_UNSUPPORTED" => StatusCode::NOT_IMPLEMENTED,
+        "SEMANTIC_INVALID_RESULT" => StatusCode::BAD_GATEWAY,
+        _ => StatusCode::BAD_REQUEST,
+    };
+    ApiError::structured(
+        status,
+        json!({
+            "code": error.code,
+            "message": error.message,
+            "http_status": status.as_u16(),
+        }),
+    )
 }
 
 fn bounded_query_error(code: &str, message: impl Into<String>) -> ApiError {
@@ -12794,11 +13148,15 @@ fn bounded_query_error(code: &str, message: impl Into<String>) -> ApiError {
 }
 
 fn bounded_query_hash(request: &BoundedQueryRequest) -> Result<String, ApiError> {
+    // The semantic clause is part of the request a cursor is bound to, so a
+    // continuation presented under a different clause is `INVALID_CURSOR`. The
+    // clause's identity, never its results, enters the hash.
     let context = json!({
         "collection": request.collection,
         "where": request.conditions,
         "orderBy": request.order_by,
         "limit": request.limit,
+        "semantic": request.semantic.as_ref().map(feltdb::semantic_clause_hash),
     });
     let bytes = serde_json::to_vec(&context)
         .map_err(|error| bounded_query_error("INVALID_QUERY", error.to_string()))?;
@@ -13058,10 +13416,15 @@ async fn execute_bounded_query(
     State(state): State<AppState>,
     Extension(principal): Extension<Principal>,
     headers: HeaderMap,
-    Json(request): Json<BoundedQueryRequest>,
+    Json(request): Json<Value>,
 ) -> Result<Json<BoundedQueryPage>, ApiError> {
     let _handler =
         feltdb::workload_diagnostics::span(feltdb::workload_diagnostics::Phase::HandlerBody);
+    // A request this surface cannot represent — including a semantic clause
+    // with keys the contract does not define — is a structured `INVALID_QUERY`,
+    // so a client can tell a refused clause from a transport failure.
+    let request: BoundedQueryRequest = serde_json::from_value(request)
+        .map_err(|error| bounded_query_error("INVALID_QUERY", error.to_string()))?;
     let execution = bounded_query_execution(&headers)?;
     validate_segment(&request.collection)?;
     if request.limit == 0 || request.limit > MAX_BOUNDED_QUERY_LIMIT {
@@ -13100,6 +13463,10 @@ async fn execute_bounded_query(
             ));
         }
     }
+    // A malformed semantic clause fails before any deterministic work runs.
+    if let Some(clause) = &request.semantic {
+        feltdb::validate_semantic_clause(clause).map_err(semantic_query_error)?;
+    }
     let hash = bounded_query_hash(&request)?;
     let (records, position) = if let Some(token) = &request.cursor {
         let cursor = state
@@ -13187,7 +13554,7 @@ async fn execute_bounded_query(
             &state,
             BoundedQueryCursor {
                 query_hash: hash,
-                principal_key_id: principal.key_id,
+                principal_key_id: principal.key_id.clone(),
                 namespace: state.namespace.to_string(),
                 records: records.clone(),
                 position: end,
@@ -13197,10 +13564,80 @@ async fn execute_bounded_query(
     } else {
         None
     };
+    // The semantic stage transforms exactly this page. It runs after the
+    // deterministic cursor is issued because continuation is by deterministic
+    // position: the page may return fewer records than `limit` and still not
+    // be exhausted.
+    let semantic = match &request.semantic {
+        None => None,
+        Some(clause) => {
+            let candidates = page
+                .iter()
+                .map(|record| feltdb::SemanticCandidate {
+                    record_id: record
+                        .get("recordId")
+                        .and_then(Value::as_str)
+                        .unwrap_or_default()
+                        .to_string(),
+                    record: record.clone(),
+                })
+                .collect();
+            let composed = feltdb::compose_semantic_page(
+                &state.db,
+                &request.collection,
+                candidates,
+                clause,
+                state
+                    .semantic_runtime
+                    .as_deref()
+                    .map(|runtime| runtime as &dyn feltdb::DecisionRuntime),
+                clause.authorization.as_ref().map(|authorization| {
+                    let requested = authorization.principal.as_ref();
+                    feltdb::DecisionPrincipal {
+                        subject: decision_subject(&principal),
+                        tenant_id: requested
+                            .map(|value| value.tenant_id.clone())
+                            .unwrap_or_default(),
+                        application_id: requested
+                            .map(|value| value.application_id.clone())
+                            .unwrap_or_default(),
+                        capability: "state:read".into(),
+                    }
+                }),
+            )
+            .map_err(semantic_query_error)?;
+            audit(
+                &state,
+                &principal.key_id,
+                "semantic_query.compose",
+                &format!("{}@{}", request.collection, composed.stage.definition_hash),
+                if composed.complete {
+                    "complete"
+                } else {
+                    "incomplete"
+                },
+                200,
+            );
+            Some(composed)
+        }
+    };
+    let (page, semantic) = match semantic {
+        None => (page, None),
+        Some(composed) => (
+            composed.records,
+            Some(BoundedQuerySemanticResult {
+                complete: composed.complete,
+                stage: composed.stage,
+                annotations: composed.annotations,
+                unevaluated: composed.unevaluated,
+            }),
+        ),
+    };
     Ok(Json(BoundedQueryPage {
         records: page,
         exhausted: next_cursor.is_none(),
         next_cursor,
+        semantic,
     }))
 }
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "create-feltdb",
   "private": false,
   "description": "Create a new FeltDB application with one command",
-  "version": "0.11.4",
+  "version": "0.11.8",
   "license": "MIT",
   "bin": {
     "create-feltdb": "bin/create-feltdb.js"