use std::collections::HashMap;
use serde_json::{json, Value};
use uuid::Uuid;
use khive_runtime::{
micros_to_iso, uuid_prefix_bounds, KhiveRuntime, NamespaceToken, RuntimeError,
};
use khive_storage::types::{SqlStatement, SqlValue};
use super::schema::{
AtomWrite, DeleteAtomsParams, GetParams, ListParams, StatsParams, UpsertAtomsParams,
UpsertDomainsParams,
};
use super::sections::{section_from_row, section_to_json};
use super::util::{
atom_from_row, atom_to_json, compute_embedding_coverage, deser, domain_from_row,
domain_to_json, new_id, now_us, row_i64, row_str, sql_err, status_sql_clause, status_values,
tags_to_json, validate_atom_content,
};
use super::KnowledgeHandlers;
#[path = "cursor_query.rs"]
mod cursor_query;
use cursor_query::cursor_query;
const ATOM_LIST_FIELDS: &[&str] = &[
"id",
"namespace",
"slug",
"name",
"content",
"tags",
"properties",
"status",
"source_uri",
"source_type",
"finalized",
"kind",
"created_at",
"updated_at",
];
const DOMAIN_LIST_FIELDS: &[&str] = &[
"id",
"namespace",
"slug",
"name",
"description",
"tags",
"members",
"kind",
"created_at",
"updated_at",
];
const LIST_CURSOR_ORDER: &str = "created_at_asc_id_asc";
const LIST_OFFSET_ORDER: &str = "created_at_desc_id_desc";
#[derive(Clone, Copy)]
enum KnowledgeListKind {
Atom,
Domain,
}
impl KnowledgeListKind {
fn name(self) -> &'static str {
match self {
Self::Atom => "atom",
Self::Domain => "domain",
}
}
fn projection_fields(self) -> &'static [&'static str] {
match self {
Self::Atom => ATOM_LIST_FIELDS,
Self::Domain => DOMAIN_LIST_FIELDS,
}
}
}
fn parse_list_after(raw: &str) -> Result<Option<Uuid>, RuntimeError> {
if raw.is_empty() {
return Ok(None);
}
Uuid::parse_str(raw).map(Some).map_err(|error| {
RuntimeError::InvalidInput(format!(
"knowledge.list: `after` must be a full UUID returned as `next_after`; \
prefixes are unsafe for keyset pagination; got {raw:?}: {error}"
))
})
}
fn validate_list_fields(
kind: KnowledgeListKind,
fields: Option<&[String]>,
) -> Result<(), RuntimeError> {
let Some(fields) = fields else {
return Ok(());
};
if fields.is_empty() {
return Err(RuntimeError::InvalidInput(
"knowledge.list: `fields` must be non-empty".into(),
));
}
if let Some(unknown) = fields
.iter()
.find(|field| !kind.projection_fields().contains(&field.as_str()))
{
return Err(RuntimeError::InvalidInput(format!(
"knowledge.list: unknown {} projection field {unknown:?}; expected one of: {}",
kind.name(),
kind.projection_fields().join(", ")
)));
}
Ok(())
}
fn list_select_columns(fields: Option<&[String]>) -> String {
let Some(fields) = fields else {
return "*".into();
};
let mut columns: Vec<&str> = Vec::with_capacity(fields.len() + 2);
for field in fields {
if field != "kind" && !columns.contains(&field.as_str()) {
columns.push(field);
}
}
for pagination_column in ["id", "created_at"] {
if !columns.contains(&pagination_column) {
columns.push(pagination_column);
}
}
columns.join(", ")
}
fn json_text_column(row: &khive_storage::types::SqlRow, column: &str) -> Value {
row_str(row, column).map_or(Value::Null, Value::String)
}
fn json_array_column(row: &khive_storage::types::SqlRow, column: &str) -> Value {
row_str(row, column)
.and_then(|raw| serde_json::from_str::<Value>(&raw).ok())
.unwrap_or_else(|| Value::Array(vec![]))
}
fn json_object_column(row: &khive_storage::types::SqlRow, column: &str) -> Value {
row_str(row, column)
.and_then(|raw| serde_json::from_str::<Value>(&raw).ok())
.unwrap_or(Value::Null)
}
fn json_timestamp_column(row: &khive_storage::types::SqlRow, column: &str) -> Value {
row_i64(row, column)
.map(micros_to_iso)
.map_or(Value::Null, Value::String)
}
fn project_list_row(
row: &khive_storage::types::SqlRow,
kind: KnowledgeListKind,
fields: Option<&[String]>,
) -> Option<Value> {
let Some(fields) = fields else {
return match kind {
KnowledgeListKind::Atom => atom_from_row(row).map(|atom| atom_to_json(&atom)),
KnowledgeListKind::Domain => domain_from_row(row).map(|domain| domain_to_json(&domain)),
};
};
let mut projected = serde_json::Map::new();
for field in fields {
let value = match field.as_str() {
"id" | "namespace" | "slug" | "name" | "content" | "description" | "status"
| "source_uri" | "source_type" => json_text_column(row, field),
"tags" | "members" => json_array_column(row, field),
"properties" => json_object_column(row, field),
"finalized" => Value::Bool(row_i64(row, field).is_some_and(|value| value == 1)),
"kind" => Value::String(kind.name().into()),
"created_at" | "updated_at" => json_timestamp_column(row, field),
_ => unreachable!("projection field was validated"),
};
projected.insert(field.clone(), value);
}
Some(Value::Object(projected))
}
fn knowledge_get_prefix_statement(prefix: &str) -> Option<SqlStatement> {
let (lower, upper) = uuid_prefix_bounds(prefix)?;
Some(SqlStatement {
sql: "SELECT id FROM knowledge_domains \
WHERE id >= ?1 AND id < ?2 AND deleted_at IS NULL \
UNION \
SELECT id FROM knowledge_atoms \
WHERE id >= ?1 AND id < ?2 AND deleted_at IS NULL \
ORDER BY id LIMIT 2"
.into(),
params: vec![SqlValue::Text(lower), SqlValue::Text(upper)],
label: Some("knowledge.get.resolve_prefix".into()),
})
}
impl KnowledgeHandlers {
pub(crate) async fn resolve_feedback_target(
runtime: &KhiveRuntime,
input: &str,
) -> Result<(Uuid, &'static str), RuntimeError> {
let sql = runtime.sql();
let mut reader = sql
.reader()
.await
.map_err(|e| sql_err("feedback target reader", e))?;
let id = if let Ok(id) = input.parse::<Uuid>() {
id
} else if let Some(statement) = knowledge_get_prefix_statement(input) {
let rows = reader
.query_all(statement)
.await
.map_err(|e| sql_err("feedback target prefix", e))?;
let ids: Vec<Uuid> = rows
.iter()
.filter_map(|r| row_str(r, "id"))
.map(|id| {
id.parse()
.map_err(|_| RuntimeError::Internal("invalid stored knowledge UUID".into()))
})
.collect::<Result<_, _>>()?;
match ids.as_slice() {
[] => {
return Err(
khive_types::KhiveError::not_found("knowledge target", input).into(),
)
}
[id] => *id,
_ => {
return Err(RuntimeError::AmbiguousPrefix {
prefix: input.into(),
matches: ids,
})
}
}
} else {
return Err(khive_types::KhiveError::invalid_input(
"knowledge feedback target must be a full UUID or 8+ hex prefix",
)
.into());
};
for (table, kind) in [("knowledge_domains", "domain"), ("knowledge_atoms", "atom")] {
let row = reader
.query_row(SqlStatement {
sql: format!(
"SELECT id FROM {table} WHERE id = ?1 AND deleted_at IS NULL LIMIT 1"
),
params: vec![SqlValue::Text(id.to_string())],
label: Some("knowledge.feedback.target".into()),
})
.await
.map_err(|e| sql_err("feedback target", e))?;
if row.is_some() {
return Ok((id, kind));
}
}
Err(khive_types::KhiveError::not_found("knowledge target", input).into())
}
pub(crate) async fn upsert_atoms(
runtime: &KhiveRuntime,
token: &NamespaceToken,
params: Value,
) -> Result<Value, RuntimeError> {
Self::upsert_atoms_with_content_policy(runtime, token, params, false).await
}
pub(super) async fn upsert_import_atoms(
runtime: &KhiveRuntime,
token: &NamespaceToken,
params: Value,
) -> Result<Value, RuntimeError> {
Self::upsert_atoms_with_content_policy(runtime, token, params, true).await
}
async fn upsert_atoms_with_content_policy(
runtime: &KhiveRuntime,
token: &NamespaceToken,
params: Value,
preserve_content_whitespace: bool,
) -> Result<Value, RuntimeError> {
let p: UpsertAtomsParams = deser(params)?;
if p.chunk_size.is_some() {
tracing::warn!(
chunk_size = ?p.chunk_size,
"upsert_atoms: chunk_size is accepted but not yet implemented; \
server-side chunking is not performed"
);
}
if p.atoms.is_empty() {
return Err(RuntimeError::InvalidInput(
"atoms list must not be empty".into(),
));
}
if p.atoms.len() > 5000 {
return Err(RuntimeError::InvalidInput(
"max 5000 atoms per request".into(),
));
}
if p.dry_run {
return super::atom_validation::dry_run(
runtime,
token,
&p.atoms,
preserve_content_whitespace,
)
.await;
}
let ns = token.namespace().as_str().to_owned();
let sql = runtime.sql();
let now = now_us();
let failures: Vec<_> = p
.atoms
.iter()
.enumerate()
.map(|(index, atom)| {
super::refusal::validate_submission(atom, index, preserve_content_whitespace).err()
})
.collect();
if failures.iter().any(Option::is_some) {
return Err(super::refusal::refuse_batch(
runtime,
token,
&p.atoms,
failures,
preserve_content_whitespace,
)
.await);
}
let mut reader = sql
.reader()
.await
.map_err(|e| sql_err("upsert_atoms reader", e))?;
let mut ids_by_slug: HashMap<String, String> = HashMap::new();
let mut operations = Vec::with_capacity(p.atoms.len());
let mut failed_index = 0;
let preparation: Result<(), RuntimeError> = async {
for (index, atom_in) in p.atoms.iter().enumerate() {
failed_index = index;
if let AtomWrite::Upsert(input) = atom_in {
if let Some(id) = ids_by_slug.get(input.slug.trim()) {
operations.push((id.clone(), false));
continue;
}
}
let target = super::atom_validation::target(reader.as_mut(), &ns, atom_in).await?;
let (id, insert) = match target {
Some(id) => (id, false),
None => (new_id(), true),
};
if let AtomWrite::Upsert(input) = atom_in {
ids_by_slug.insert(input.slug.trim().to_owned(), id.clone());
}
operations.push((id, insert));
}
Ok(())
}
.await;
drop(reader);
if let Err(error) = preparation {
if matches!(
error,
RuntimeError::InvalidInput(_) | RuntimeError::NotFound(_)
) {
let mut failures: Vec<_> = (0..p.atoms.len()).map(|_| None).collect();
failures[failed_index] = Some(error);
return Err(super::refusal::refuse_batch(
runtime,
token,
&p.atoms,
failures,
preserve_content_whitespace,
)
.await);
}
return Err(error);
}
let mut created = 0usize;
let mut updated = 0usize;
let mut statements = Vec::with_capacity(p.atoms.len());
for (atom_in, (id, insert)) in p.atoms.iter().zip(operations) {
let atom_in = match atom_in {
AtomWrite::Upsert(atom_in) => atom_in,
AtomWrite::PropertiesOnly(atom_in) => {
statements.push(SqlStatement {
sql: "UPDATE knowledge_atoms SET properties=?1, updated_at=?2 WHERE id=?3"
.into(),
params: vec![
if atom_in.properties.is_null() {
SqlValue::Null
} else {
SqlValue::Text(atom_in.properties.to_string())
},
SqlValue::Integer(now),
SqlValue::Text(id),
],
label: None,
});
updated += 1;
continue;
}
};
let slug = atom_in.slug.trim().to_string();
let raw_content = atom_in.content.as_deref().unwrap_or("");
let content = if preserve_content_whitespace {
raw_content.to_string()
} else {
raw_content.trim().to_string()
};
let tags_json = tags_to_json(atom_in.tags.as_ref());
let props_json = atom_in
.properties
.as_ref()
.map(|v| serde_json::to_string(v).unwrap_or_default());
let source_uri = atom_in
.source_uri
.as_ref()
.and_then(Option::as_ref)
.map(|s| s.trim())
.filter(|s| !s.is_empty());
let source_uri_present =
matches!(&atom_in.source_uri, Some(None)) || source_uri.is_some();
let source_type = atom_in
.source_type
.as_ref()
.and_then(Option::as_ref)
.map(|s| s.trim())
.filter(|s| !s.is_empty());
let source_type_present =
matches!(&atom_in.source_type, Some(None)) || source_type.is_some();
let finalized_present = atom_in.finalized.is_some();
let finalized = atom_in.finalized.flatten().unwrap_or(false);
if insert {
statements.push(SqlStatement {
sql: "INSERT INTO knowledge_atoms (id, namespace, slug, name, content, tags, properties, source_uri, source_type, status, finalized, created_at, updated_at) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9,?10,?11,?12,?13)".into(),
params: vec![
SqlValue::Text(id),
SqlValue::Text(ns.clone()),
SqlValue::Text(slug.clone()),
SqlValue::Text(atom_in.name.clone()),
SqlValue::Text(content.clone()),
SqlValue::Text(tags_json.clone()),
props_json.as_ref().map_or(SqlValue::Null, |p| SqlValue::Text(p.clone())),
source_uri.map_or(SqlValue::Null, |s| SqlValue::Text(s.to_string())),
source_type.map_or(SqlValue::Null, |s| SqlValue::Text(s.to_string())),
SqlValue::Text(if finalized { "reviewed" } else { "draft" }.to_string()),
SqlValue::Integer(finalized as i64),
SqlValue::Integer(now),
SqlValue::Integer(now),
],
label: None,
});
created += 1;
} else {
statements.push(SqlStatement {
sql: "UPDATE knowledge_atoms SET name=?1, content=?2, tags=?3, properties=?4, source_uri=CASE WHEN ?5 = 1 THEN ?6 ELSE source_uri END, source_type=CASE WHEN ?7 = 1 THEN ?8 ELSE source_type END, finalized=CASE WHEN ?9 = 1 THEN ?10 ELSE finalized END, status=CASE WHEN ?9 = 1 AND ?10 = 1 AND status = 'draft' THEN 'reviewed' ELSE status END, updated_at=?11 WHERE id=?12 AND namespace=?13".into(),
params: vec![
SqlValue::Text(atom_in.name.clone()),
SqlValue::Text(content),
SqlValue::Text(tags_json),
props_json.map_or(SqlValue::Null, SqlValue::Text),
SqlValue::Integer(source_uri_present as i64),
source_uri.map_or(SqlValue::Null, |s| SqlValue::Text(s.to_string())),
SqlValue::Integer(source_type_present as i64),
source_type.map_or(SqlValue::Null, |s| SqlValue::Text(s.to_string())),
SqlValue::Integer(finalized_present as i64),
SqlValue::Integer(finalized as i64),
SqlValue::Integer(now),
SqlValue::Text(id),
SqlValue::Text(ns.clone()),
],
label: None,
});
updated += 1;
}
}
let mut writer = sql
.writer()
.await
.map_err(|e| sql_err("upsert_atoms writer", e))?;
writer
.execute_batch(statements)
.await
.map_err(|e| sql_err("upsert_atoms batch", e))?;
Ok(json!({
"created": created,
"updated": updated,
"total": p.atoms.len(),
}))
}
pub(crate) async fn upsert_domains(
runtime: &KhiveRuntime,
token: &NamespaceToken,
params: Value,
) -> Result<Value, RuntimeError> {
let p: UpsertDomainsParams = deser(params)?;
if p.domains.is_empty() {
return Err(RuntimeError::InvalidInput(
"domains list must not be empty".into(),
));
}
let ns = token.namespace().as_str().to_owned();
let sql = runtime.sql();
let now = now_us();
let mut created = 0usize;
let mut updated = 0usize;
for domain_in in &p.domains {
let slug = domain_in.slug.trim().to_string();
let name = domain_in.name.trim().to_string();
if slug.is_empty() {
return Err(RuntimeError::InvalidInput(
"domain slug must not be empty".into(),
));
}
if name.is_empty() {
return Err(RuntimeError::InvalidInput(
"domain name must not be empty".into(),
));
}
khive_runtime::secret_gate::check_at(&slug, "domain", "slug")?;
khive_runtime::secret_gate::check_at(&name, "domain", "name")?;
let mirror_content = domain_in.description.as_deref().unwrap_or("").trim();
validate_atom_content(mirror_content).map_err(|e| {
RuntimeError::InvalidInput(format!("domain {slug:?}: description {e}"))
})?;
khive_runtime::secret_gate::check_at(mirror_content, "domain", "description")?;
if let Some(ref tags_vec) = domain_in.tags {
khive_runtime::secret_gate::check_tags_at(tags_vec, "domain", "tags")?;
}
if let Some(ref members_vec) = domain_in.members {
khive_runtime::secret_gate::check_tags_at(members_vec, "domain", "members")?;
}
let mut tags: Vec<String> = domain_in.tags.clone().unwrap_or_default();
if !tags.iter().any(|t| t == "type:domain") {
tags.push("type:domain".to_string());
}
let tags_json = serde_json::to_string(&tags).unwrap_or_else(|_| "[]".into());
let members_json = match &domain_in.members {
Some(m) => serde_json::to_string(m).unwrap_or_else(|_| "[]".into()),
None => "[]".to_string(),
};
let properties_json = serde_json::to_string(
&serde_json::json!({ "members": domain_in.members.as_deref().unwrap_or(&[]) }),
)
.unwrap_or_else(|_| "{}".into());
let mut reader = sql
.reader()
.await
.map_err(|e| sql_err("upsert_domains reader", e))?;
let existing = reader
.query_row(SqlStatement {
sql: "SELECT id, deleted_at FROM knowledge_domains WHERE namespace = ?1 AND slug = ?2 LIMIT 1".into(),
params: vec![SqlValue::Text(ns.clone()), SqlValue::Text(slug.clone())],
label: None,
})
.await
.map_err(|e| sql_err("upsert_domains lookup", e))?;
if let Some(row) = &existing {
if row_i64(row, "deleted_at").is_some() {
return Err(RuntimeError::InvalidInput(format!(
"domain slug {slug:?} was previously deleted; choose a new slug"
)));
}
}
let id = match &existing {
Some(row) => row_str(row, "id").ok_or_else(|| {
RuntimeError::Internal("missing id in existing domain row".into())
})?,
None => new_id(),
};
let atom_collision = reader
.query_row(SqlStatement {
sql:
"SELECT id FROM knowledge_atoms WHERE namespace = ?1 AND slug = ?2 LIMIT 1"
.into(),
params: vec![SqlValue::Text(ns.clone()), SqlValue::Text(slug.clone())],
label: None,
})
.await
.map_err(|e| sql_err("upsert_domains atom collision check", e))?;
if let Some(row) = &atom_collision {
let collision_id = row_str(row, "id").ok_or_else(|| {
RuntimeError::Internal("missing id in colliding atom row".into())
})?;
if collision_id != id {
return Err(RuntimeError::InvalidInput(format!(
"domain slug {slug:?} collides with an existing atom of the same slug"
)));
}
}
let mirror_stmt = SqlStatement {
sql: "INSERT INTO knowledge_atoms (id, namespace, slug, name, content, tags, properties, status, finalized, created_at, updated_at) \
VALUES (?1,?2,?3,?4,?5,?6,?7,'reviewed',1,?8,?9) \
ON CONFLICT(id) DO UPDATE SET slug=?3, name=?4, content=?5, tags=?6, properties=?7, status='reviewed', finalized=1, updated_at=?9".into(),
params: vec![
SqlValue::Text(id.clone()),
SqlValue::Text(ns.clone()),
SqlValue::Text(slug.clone()),
SqlValue::Text(name.clone()),
SqlValue::Text(domain_in.description.clone().unwrap_or_default()),
SqlValue::Text(tags_json.clone()),
SqlValue::Text(properties_json.clone()),
SqlValue::Integer(now),
SqlValue::Integer(now),
],
label: None,
};
let mut writer = sql
.writer()
.await
.map_err(|e| sql_err("upsert_domains writer", e))?;
if existing.is_some() {
let domain_stmt = SqlStatement {
sql: "UPDATE knowledge_domains SET name=?1, description=?2, tags=?3, members=?4, updated_at=?5 WHERE id=?6 AND namespace=?7".into(),
params: vec![
SqlValue::Text(name.clone()),
domain_in.description.as_ref().map_or(SqlValue::Null, |d| SqlValue::Text(d.clone())),
SqlValue::Text(tags_json.clone()),
SqlValue::Text(members_json.clone()),
SqlValue::Integer(now),
SqlValue::Text(id.clone()),
SqlValue::Text(ns.clone()),
],
label: None,
};
writer
.execute_batch(vec![domain_stmt, mirror_stmt])
.await
.map_err(|e| sql_err("upsert_domains update batch", e))?;
updated += 1;
} else {
let domain_stmt = SqlStatement {
sql: "INSERT INTO knowledge_domains (id, namespace, slug, name, description, tags, members, created_at, updated_at) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9)".into(),
params: vec![
SqlValue::Text(id.clone()),
SqlValue::Text(ns.clone()),
SqlValue::Text(slug.clone()),
SqlValue::Text(name.clone()),
domain_in.description.as_ref().map_or(SqlValue::Null, |d| SqlValue::Text(d.clone())),
SqlValue::Text(tags_json.clone()),
SqlValue::Text(members_json.clone()),
SqlValue::Integer(now),
SqlValue::Integer(now),
],
label: None,
};
writer
.execute_batch(vec![domain_stmt, mirror_stmt])
.await
.map_err(|e| sql_err("upsert_domains insert batch", e))?;
created += 1;
}
}
Ok(json!({
"created": created,
"updated": updated,
"total": p.domains.len(),
}))
}
pub(crate) async fn get(
runtime: &KhiveRuntime,
token: &NamespaceToken,
params: Value,
) -> Result<Value, RuntimeError> {
let p: GetParams = deser(params)?;
let ns = token.namespace().as_str().to_owned();
let sql = runtime.sql();
let id = p.id.trim().to_string();
let with_sections = p.include_sections.unwrap_or(false);
let mut reader = sql.reader().await.map_err(|e| sql_err("get reader", e))?;
let resolved_id = if let Ok(uuid) = id.parse::<Uuid>() {
Some(uuid.to_string())
} else {
let row = reader
.query_row(SqlStatement {
sql: "SELECT * FROM knowledge_domains WHERE namespace = ?1 AND slug = ?2 AND deleted_at IS NULL LIMIT 1".into(),
params: vec![SqlValue::Text(ns.clone()), SqlValue::Text(id.clone())],
label: Some("knowledge.get.domain_by_slug".into()),
})
.await
.map_err(|e| sql_err("get domain by slug", e))?;
if let Some(r) = row {
return domain_from_row(&r)
.map(|d| domain_to_json(&d))
.ok_or_else(|| RuntimeError::Internal("domain row parse failed".into()));
}
let row = reader
.query_row(SqlStatement {
sql: "SELECT * FROM knowledge_atoms WHERE namespace = ?1 AND slug = ?2 AND deleted_at IS NULL LIMIT 1".into(),
params: vec![SqlValue::Text(ns.clone()), SqlValue::Text(id.clone())],
label: Some("knowledge.get.atom_by_slug".into()),
})
.await
.map_err(|e| sql_err("get atom by slug", e))?;
if let Some(r) = row {
let atom = atom_from_row(&r)
.ok_or_else(|| RuntimeError::Internal("atom row parse failed".into()))?;
let atom_id = atom.id.to_string();
let mut out = atom_to_json(&atom);
if with_sections {
out["sections"] = fetch_sections(runtime, &ns, &atom_id).await?;
}
return Ok(out);
}
if id.len() >= 8 && id.chars().all(|c| c.is_ascii_hexdigit()) {
let rows = if let Some(statement) = knowledge_get_prefix_statement(&id) {
reader
.query_all(statement)
.await
.map_err(|e| sql_err("get by prefix", e))?
} else {
Vec::new()
};
let matches: Vec<String> =
rows.iter().filter_map(|row| row_str(row, "id")).collect();
match matches.as_slice() {
[] => {
return Err(RuntimeError::InvalidInput(format!(
"no knowledge record matches prefix: {id:?}"
)))
}
[only] => Some(only.clone()),
_ => {
return Err(RuntimeError::AmbiguousPrefix {
prefix: id.clone(),
matches: matches
.iter()
.filter_map(|matched| matched.parse::<Uuid>().ok())
.collect(),
})
}
}
} else {
None
}
};
if let Some(resolved_id) = resolved_id {
let row = reader
.query_row(SqlStatement {
sql: "SELECT * FROM knowledge_domains WHERE id = ?1 AND deleted_at IS NULL LIMIT 1".into(),
params: vec![SqlValue::Text(resolved_id.clone())],
label: Some("knowledge.get.domain_by_id".into()),
})
.await
.map_err(|e| sql_err("get domain by id", e))?;
if let Some(r) = row {
return domain_from_row(&r)
.map(|d| domain_to_json(&d))
.ok_or_else(|| RuntimeError::Internal("domain row parse failed".into()));
}
let row = reader
.query_row(SqlStatement {
sql:
"SELECT * FROM knowledge_atoms WHERE id = ?1 AND deleted_at IS NULL LIMIT 1"
.into(),
params: vec![SqlValue::Text(resolved_id)],
label: Some("knowledge.get.atom_by_id".into()),
})
.await
.map_err(|e| sql_err("get atom by id", e))?;
if let Some(r) = row {
let atom = atom_from_row(&r)
.ok_or_else(|| RuntimeError::Internal("atom row parse failed".into()))?;
let atom_id = atom.id.to_string();
let atom_namespace = atom.namespace.clone();
let mut out = atom_to_json(&atom);
if with_sections {
out["sections"] = fetch_sections(runtime, &atom_namespace, &atom_id).await?;
}
return Ok(out);
}
return Err(RuntimeError::NotFound(format!(
"atom or domain not found: {id:?}"
)));
}
Err(RuntimeError::NotFound(format!(
"atom or domain not found: {id:?}"
)))
}
pub(crate) async fn list(
runtime: &KhiveRuntime,
token: &NamespaceToken,
params: Value,
) -> Result<Value, RuntimeError> {
let p: ListParams = deser(params)?;
let kind = match p.kind.as_deref() {
Some("domain") => KnowledgeListKind::Domain,
Some("atom") | None => KnowledgeListKind::Atom,
Some(other) => {
return Err(RuntimeError::InvalidInput(format!(
"unknown type {other:?}; valid: atom | domain"
)))
}
};
let cursor_mode = p.after.is_some();
if cursor_mode && p.offset.is_some() {
return Err(RuntimeError::InvalidInput(
"knowledge.list: `after` and `offset` are mutually exclusive".into(),
));
}
validate_list_fields(kind, p.fields.as_deref())?;
let after_id = p
.after
.as_deref()
.map(parse_list_after)
.transpose()?
.flatten();
let ns = token.namespace().as_str().to_owned();
let sql = runtime.sql();
let limit_usize = p.limit.unwrap_or(20).clamp(1, 500);
let limit = limit_usize as i64;
let offset = p.offset.unwrap_or(0) as i64;
let select_columns = list_select_columns(p.fields.as_deref());
let mut reader = sql.reader().await.map_err(|e| sql_err("list reader", e))?;
let cursor_key = if let Some(after_id) = after_id {
let cursor_sql = match kind {
KnowledgeListKind::Atom => {
"SELECT created_at, id FROM knowledge_atoms WHERE namespace = ?1 AND id = ?2 AND tags NOT LIKE '%type:domain%' LIMIT 1"
}
KnowledgeListKind::Domain => {
"SELECT created_at, id FROM knowledge_domains WHERE namespace = ?1 AND id = ?2 LIMIT 1"
}
};
let row = reader
.query_row(SqlStatement {
sql: cursor_sql.into(),
params: vec![
SqlValue::Text(ns.clone()),
SqlValue::Text(after_id.to_string()),
],
label: Some(format!("knowledge.list.{}.cursor", kind.name())),
})
.await
.map_err(|e| sql_err("resolve list cursor", e))?
.ok_or_else(|| {
RuntimeError::NotFound(format!(
"knowledge.list: {} cursor {} not found in namespace {ns:?}",
kind.name(),
after_id
))
})?;
let created_at = row_i64(&row, "created_at").ok_or_else(|| {
RuntimeError::Internal("knowledge.list cursor row lacks created_at".into())
})?;
let id = row_str(&row, "id").ok_or_else(|| {
RuntimeError::Internal("knowledge.list cursor row lacks id".into())
})?;
Some((created_at, id))
} else {
None
};
match kind {
KnowledgeListKind::Domain => {
let (data_sql, data_params) = if cursor_mode {
let fetch_limit = limit.saturating_add(1);
match cursor_key.as_ref() {
Some((created_at, id)) => (
cursor_query("knowledge_domains", &select_columns, true, ""),
vec![
SqlValue::Text(ns.clone()),
SqlValue::Integer(*created_at),
SqlValue::Text(id.clone()),
SqlValue::Integer(fetch_limit),
],
),
None => (
cursor_query("knowledge_domains", &select_columns, false, ""),
vec![SqlValue::Text(ns.clone()), SqlValue::Integer(fetch_limit)],
),
}
} else {
(
format!(
"SELECT {select_columns} FROM knowledge_domains \
WHERE namespace = ?1 AND deleted_at IS NULL \
ORDER BY created_at DESC, id DESC LIMIT ?2 OFFSET ?3"
),
vec![
SqlValue::Text(ns.clone()),
SqlValue::Integer(limit),
SqlValue::Integer(offset),
],
)
};
let mut rows = reader
.query_all(SqlStatement {
sql: data_sql,
params: data_params,
label: Some("knowledge.list.domains".into()),
})
.await
.map_err(|e| sql_err("list domains", e))?;
let has_more = cursor_mode && rows.len() > limit_usize;
if has_more {
rows.truncate(limit_usize);
}
let next_after = has_more
.then(|| rows.last().and_then(|row| row_str(row, "id")))
.flatten();
let items: Vec<Value> = rows
.iter()
.filter_map(|row| project_list_row(row, kind, p.fields.as_deref()))
.collect();
if cursor_mode {
Ok(json!({
"results": items,
"limit": limit,
"order": LIST_CURSOR_ORDER,
"next_after": next_after,
}))
} else {
let total_row = reader
.query_scalar(SqlStatement {
sql: "SELECT COUNT(*) FROM knowledge_domains WHERE namespace = ?1 AND deleted_at IS NULL".into(),
params: vec![SqlValue::Text(ns)],
label: None,
})
.await
.map_err(|e| sql_err("list domains count", e))?;
let total = match total_row {
Some(SqlValue::Integer(n)) => n,
_ => 0,
};
Ok(json!({
"results": items,
"total": total,
"limit": limit,
"offset": offset,
"order": LIST_OFFSET_ORDER,
}))
}
}
KnowledgeListKind::Atom => {
let requested_statuses = status_values(p.status.as_ref());
let exclude_buf: Vec<&str> = p
.exclude_status
.as_deref()
.filter(|s| !s.trim().is_empty())
.into_iter()
.collect();
let (count_status_clause, count_status_params) =
status_sql_clause(&requested_statuses, &exclude_buf, 2);
let (sql_str, row_params) = if cursor_mode {
let fetch_limit = limit.saturating_add(1);
match cursor_key.as_ref() {
Some((created_at, id)) => {
let (data_status_clause, data_status_params) =
status_sql_clause(&requested_statuses, &exclude_buf, 5);
let mut row_params = vec![
SqlValue::Text(ns.clone()),
SqlValue::Integer(*created_at),
SqlValue::Text(id.clone()),
SqlValue::Integer(fetch_limit),
];
row_params.extend(data_status_params);
(
cursor_query(
"knowledge_atoms",
&select_columns,
true,
&data_status_clause,
),
row_params,
)
}
None => {
let (data_status_clause, data_status_params) =
status_sql_clause(&requested_statuses, &exclude_buf, 3);
let mut row_params =
vec![SqlValue::Text(ns.clone()), SqlValue::Integer(fetch_limit)];
row_params.extend(data_status_params);
(
cursor_query(
"knowledge_atoms",
&select_columns,
false,
&data_status_clause,
),
row_params,
)
}
}
} else {
let (data_status_clause, data_status_params) =
status_sql_clause(&requested_statuses, &exclude_buf, 4);
let mut row_params = vec![
SqlValue::Text(ns.clone()),
SqlValue::Integer(limit),
SqlValue::Integer(offset),
];
row_params.extend(data_status_params);
(
format!(
"SELECT {select_columns} FROM knowledge_atoms \
WHERE namespace = ?1 AND deleted_at IS NULL \
AND tags NOT LIKE '%type:domain%'{} \
ORDER BY created_at DESC, id DESC LIMIT ?2 OFFSET ?3",
data_status_clause
),
row_params,
)
};
let count_sql = format!(
"SELECT COUNT(*) FROM knowledge_atoms WHERE namespace = ?1 AND deleted_at IS NULL AND tags NOT LIKE '%type:domain%'{}",
count_status_clause
);
let mut rows = reader
.query_all(SqlStatement {
sql: sql_str,
params: row_params,
label: Some("knowledge.list.atoms".into()),
})
.await
.map_err(|e| sql_err("list atoms", e))?;
let has_more = cursor_mode && rows.len() > limit_usize;
if has_more {
rows.truncate(limit_usize);
}
let next_after = has_more
.then(|| rows.last().and_then(|row| row_str(row, "id")))
.flatten();
let items: Vec<Value> = rows
.iter()
.filter_map(|row| project_list_row(row, kind, p.fields.as_deref()))
.collect();
if cursor_mode {
Ok(json!({
"results": items,
"limit": limit,
"order": LIST_CURSOR_ORDER,
"next_after": next_after,
}))
} else {
let mut count_params = vec![SqlValue::Text(ns)];
count_params.extend(count_status_params);
let total_row = reader
.query_scalar(SqlStatement {
sql: count_sql,
params: count_params,
label: Some("knowledge.list.atom_count".into()),
})
.await
.map_err(|e| sql_err("list atoms count", e))?;
let total = match total_row {
Some(SqlValue::Integer(n)) => n,
_ => 0,
};
Ok(json!({
"results": items,
"total": total,
"limit": limit,
"offset": offset,
"order": LIST_OFFSET_ORDER,
}))
}
}
}
}
pub(crate) async fn delete_atoms(
runtime: &KhiveRuntime,
token: &NamespaceToken,
params: Value,
) -> Result<Value, RuntimeError> {
let p: DeleteAtomsParams = deser(params)?;
if p.cascade.is_some() {
tracing::warn!(
cascade = ?p.cascade,
"delete_atoms: cascade is accepted but not yet implemented; \
sections are not cascade-deleted when atoms are soft-deleted"
);
}
if p.ids.is_empty() {
return Err(RuntimeError::InvalidInput("ids must not be empty".into()));
}
let ns = token.namespace().as_str().to_owned();
let sql = runtime.sql();
let now = now_us();
let mut deleted = 0usize;
let mut reader = sql
.reader()
.await
.map_err(|e| sql_err("delete_atoms reader", e))?;
for id_or_slug in &p.ids {
let key = id_or_slug.trim().to_string();
let domain = reader
.query_row(SqlStatement {
sql: "SELECT id FROM knowledge_domains WHERE namespace = ?1 AND (id = ?2 OR slug = ?2) AND deleted_at IS NULL LIMIT 1".into(),
params: vec![SqlValue::Text(ns.clone()), SqlValue::Text(key.clone())],
label: None,
})
.await
.map_err(|e| sql_err("delete_atoms domain preflight", e))?;
if domain.is_some() {
return Err(RuntimeError::InvalidInput(format!(
"knowledge.delete_atoms cannot delete domain {key:?}; use the generic delete verb by domain UUID"
)));
}
let mirror = reader
.query_row(SqlStatement {
sql: "SELECT tags FROM knowledge_atoms WHERE namespace = ?1 AND (id = ?2 OR slug = ?2) AND deleted_at IS NULL LIMIT 1".into(),
params: vec![SqlValue::Text(ns.clone()), SqlValue::Text(key.clone())],
label: None,
})
.await
.map_err(|e| sql_err("delete_atoms mirror preflight", e))?;
if let Some(row) = mirror {
let tags = row_str(&row, "tags").unwrap_or_default();
if tags.contains("type:domain") {
return Err(RuntimeError::InvalidInput(format!(
"knowledge.delete_atoms cannot delete domain mirror {key:?}; use the generic delete verb by domain UUID"
)));
}
}
}
let mut writer = sql
.writer()
.await
.map_err(|e| sql_err("delete_atoms writer", e))?;
for id_or_slug in &p.ids {
let id_or_slug = id_or_slug.trim().to_string();
let affected = writer
.execute(SqlStatement {
sql: "UPDATE knowledge_atoms SET deleted_at = ?1 WHERE namespace = ?2 AND (id = ?3 OR slug = ?3) AND deleted_at IS NULL".into(),
params: vec![
SqlValue::Integer(now),
SqlValue::Text(ns.clone()),
SqlValue::Text(id_or_slug),
],
label: None,
})
.await
.map_err(|e| sql_err("delete_atoms update", e))?;
deleted += affected as usize;
}
Ok(json!({
"deleted": deleted,
"requested": p.ids.len(),
}))
}
pub(crate) async fn stats(
runtime: &KhiveRuntime,
token: &NamespaceToken,
params: Value,
) -> Result<Value, RuntimeError> {
let _: StatsParams = deser(params)?;
let ns = token.namespace().as_str().to_owned();
let sql = runtime.sql();
let mut reader = sql.reader().await.map_err(|e| sql_err("stats reader", e))?;
let atom_stats = reader
.query_row(SqlStatement {
sql: "SELECT COUNT(*) AS total_atoms, \
COALESCE(SUM(CASE WHEN finalized = 1 THEN 1 ELSE 0 END), 0) \
AS finalized_atoms \
FROM knowledge_atoms \
WHERE namespace = ?1 AND deleted_at IS NULL \
AND tags NOT LIKE '%type:domain%'"
.into(),
params: vec![SqlValue::Text(ns.clone())],
label: Some("knowledge.stats.atom_aggregates".into()),
})
.await
.map_err(|e| sql_err("stats atom aggregates", e))?;
let domain_count = reader
.query_scalar(SqlStatement {
sql: "SELECT COUNT(*) FROM knowledge_domains WHERE namespace = ?1 AND deleted_at IS NULL".into(),
params: vec![SqlValue::Text(ns.clone())],
label: None,
})
.await
.map_err(|e| sql_err("stats domains", e))?;
let event_count = reader
.query_scalar(SqlStatement {
sql: "SELECT COUNT(*) FROM events WHERE namespace = ?1 AND verb LIKE 'knowledge.%'"
.into(),
params: vec![SqlValue::Text(ns.clone())],
label: Some("knowledge.stats.event_count".into()),
})
.await
.map_err(|e| sql_err("stats events", e))?;
let retrieval_eval_run_count = reader
.query_scalar(SqlStatement {
sql: "SELECT COUNT(*) FROM knowledge_eval_runs WHERE namespace = ?1".into(),
params: vec![SqlValue::Text(ns.clone())],
label: Some("knowledge.stats.eval_run_count".into()),
})
.await
.map_err(|e| sql_err("stats eval run count", e))?;
let latest_retrieval_eval = reader
.query_row(SqlStatement {
sql: "SELECT run_at, precision_at_5, mrr FROM knowledge_eval_runs \
WHERE namespace = ?1 ORDER BY run_at DESC, rowid DESC LIMIT 1"
.into(),
params: vec![SqlValue::Text(ns.clone())],
label: Some("knowledge.stats.latest_eval_run".into()),
})
.await
.map_err(|e| sql_err("stats latest eval run", e))?;
let total_atoms = atom_stats
.as_ref()
.and_then(|row| row_i64(row, "total_atoms"))
.unwrap_or(0);
let total_domains = match domain_count {
Some(SqlValue::Integer(n)) => n,
_ => 0,
};
let finalized = atom_stats
.as_ref()
.and_then(|row| row_i64(row, "finalized_atoms"))
.unwrap_or(0);
let total_events = match event_count {
Some(SqlValue::Integer(n)) => n,
_ => 0,
};
let retrieval_eval_run_count = match retrieval_eval_run_count {
Some(SqlValue::Integer(n)) => n,
_ => 0,
};
let retrieval_eval_coverage = latest_retrieval_eval
.as_ref()
.and_then(|row| match row.get("precision_at_5") {
Some(SqlValue::Float(value)) => Some(*value),
Some(SqlValue::Integer(value)) => Some(*value as f64),
_ => None,
})
.unwrap_or(0.0);
let retrieval_eval_last_run_at =
latest_retrieval_eval
.as_ref()
.and_then(|row| match row.get("run_at") {
Some(SqlValue::Integer(value)) => Some(*value),
_ => None,
});
let retrieval_eval_last_mrr =
latest_retrieval_eval
.as_ref()
.and_then(|row| match row.get("mrr") {
Some(SqlValue::Float(value)) => Some(*value),
Some(SqlValue::Integer(value)) => Some(*value as f64),
_ => None,
});
let eval_coverage = if total_atoms > 0 {
finalized as f64 / total_atoms as f64
} else {
0.0
};
let embedding_coverage =
compute_embedding_coverage(runtime, token, &ns, total_atoms).await?;
Ok(json!({
"total_atoms": total_atoms,
"total_domains": total_domains,
"total_events": total_events,
"eval_coverage": eval_coverage,
"embedding_coverage": embedding_coverage,
"retrieval_eval_coverage": retrieval_eval_coverage,
"retrieval_eval_run_count": retrieval_eval_run_count,
"retrieval_eval_last_run_at": retrieval_eval_last_run_at,
"retrieval_eval_last_mrr": retrieval_eval_last_mrr,
"namespace": ns,
}))
}
}
async fn fetch_sections(
runtime: &KhiveRuntime,
ns: &str,
atom_id: &str,
) -> Result<Value, RuntimeError> {
let sql = runtime.sql();
let mut reader = sql
.reader()
.await
.map_err(|e| sql_err("get sections reader", e))?;
let rows = reader
.query_all(SqlStatement {
sql: "SELECT * FROM knowledge_sections \
WHERE atom_id = ?1 AND namespace = ?2 \
ORDER BY sort_order ASC, created_at ASC, id ASC"
.into(),
params: vec![
SqlValue::Text(atom_id.to_owned()),
SqlValue::Text(ns.to_owned()),
],
label: None,
})
.await
.map_err(|e| sql_err("get sections query", e))?;
let mut sections: Vec<Value> = Vec::with_capacity(rows.len());
for r in &rows {
match section_from_row(r) {
Some(s) => sections.push(section_to_json(&s)),
None => {
return Err(RuntimeError::Internal(
"knowledge_sections row is malformed (invalid UUID or section_type); \
data integrity check required"
.into(),
));
}
}
}
Ok(Value::Array(sections))
}
#[cfg(test)]
mod tests {
use khive_runtime::secret_gate::check;
use khive_runtime::{KhiveRuntime, VerbRegistryBuilder};
use khive_storage::SqlValue;
#[test]
fn key_only_list_projection_does_not_select_atom_content() {
let fields = vec!["id".to_string(), "slug".to_string()];
let columns = super::list_select_columns(Some(&fields));
assert_eq!(columns, "id, slug, created_at");
assert!(!columns.contains("content"));
}
#[tokio::test]
async fn get_prefix_query_plan_uses_primary_key_range_seeks() {
let runtime = KhiveRuntime::memory().expect("memory runtime");
let mut builder = VerbRegistryBuilder::new();
builder.register(khive_pack_kg::KgPack::new(runtime.clone()));
builder.register(crate::KnowledgePack::new(runtime.clone()));
let registry = builder.build().expect("registry builds");
registry.apply_schema_plans(runtime.backend());
let mut reader = runtime.sql().reader().await.expect("prefix plan reader");
let rows = reader
.explain(
super::knowledge_get_prefix_statement("0b6cf134")
.expect("valid compact UUID prefix"),
)
.await
.expect("explain knowledge prefix query");
let details: Vec<String> = rows
.iter()
.filter_map(|row| match row.get("detail") {
Some(SqlValue::Text(detail)) => Some(detail.clone()),
_ => None,
})
.collect();
assert!(
["knowledge_domains", "knowledge_atoms"]
.iter()
.all(|table| {
details.iter().any(|detail| {
detail.contains(&format!("SEARCH {table}"))
&& detail.contains("id>?")
&& detail.contains("id<?")
}) && !details
.iter()
.any(|detail| detail.contains(&format!("SCAN {table}")))
}),
"knowledge.get short-id tables must use primary-key range seeks: {details:?}"
);
}
#[test]
fn atom_body_with_fake_aws_key_is_blocked() {
let body = "provider: aws\naccess_key_id: AKIAFAKE000000000000\nregion: us-east-1";
assert!(
check(body).is_err(),
"atom body containing fake AWS key must be blocked"
);
}
#[test]
fn atom_body_with_sha256_hash_passes() {
let body =
"checksum = \"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\"";
assert!(
check(body).is_ok(),
"atom body with sha256 manifest hash must pass; fired: {:?}",
check(body).err()
);
}
#[test]
fn atom_name_with_fake_openai_key_is_blocked() {
let name = format!("sk-proj-{}", "A".repeat(80));
assert!(
check(&name).is_err(),
"atom name containing fake OpenAI key must be blocked"
);
}
#[test]
fn normal_atom_name_passes() {
let name = "FlashAttention-2: efficient transformer self-attention";
assert!(
check(name).is_ok(),
"normal atom name must pass; fired: {:?}",
check(name).err()
);
}
#[test]
fn upsert_atoms_chunk_size_accepted_and_detectable() {
use crate::knowledge::schema::UpsertAtomsParams;
let p: UpsertAtomsParams = serde_json::from_value(serde_json::json!({
"atoms": [{"slug": "s", "name": "n", "content": "placeholder content for test"}],
"chunk_size": 100,
}))
.expect("upsert_atoms params with chunk_size must deserialize without error");
assert!(
p.chunk_size.is_some(),
"chunk_size must be Some when supplied so the warning branch precondition is satisfiable"
);
}
#[test]
fn delete_atoms_cascade_accepted_and_detectable() {
use crate::knowledge::schema::DeleteAtomsParams;
let p: DeleteAtomsParams = serde_json::from_value(serde_json::json!({
"ids": ["some-atom-id"],
"cascade": true,
}))
.expect("delete_atoms params with cascade must deserialize without error");
assert!(
p.cascade.is_some(),
"cascade must be Some when supplied so the warning branch precondition is satisfiable"
);
}
}