everruns_contracts/knowledge_store.rs
1//! Hosted knowledge retrieval service contracts.
2//!
3//! The execution kernel carries only a generic typed extension bag. Product
4//! projection installs these narrow, tenant-scoped services when the selected
5//! capability family is available.
6
7use std::sync::Arc;
8
9use crate::error::Result;
10use crate::typed_id::OrgId;
11use async_trait::async_trait;
12
13use crate::vector_store::{KnowledgeIndexCitation, KnowledgeIndexSearch};
14
15/// One ranked hit from an organization Knowledge Base search.
16#[derive(Debug, Clone, serde::Serialize)]
17pub struct KnowledgeSearchHit {
18 /// Entry public ID (`kbe_…`).
19 pub id: String,
20 /// Owning Knowledge Base public ID (`kb_…`).
21 pub kb_id: String,
22 /// Human-readable result title.
23 pub title: String,
24 /// Knowledge entry kind.
25 pub kind: String,
26 /// Normalized entry tags.
27 pub tags: Vec<String>,
28 /// Bounded body excerpt for the model.
29 pub snippet: String,
30 /// Optional OKF resource URI.
31 pub resource: Option<String>,
32}
33
34/// Tenant-scoped search over curated Knowledge Bases.
35///
36/// Implementations must scope every lookup to `org_id` and silently ignore
37/// requested Knowledge Base IDs owned by another organization so callers
38/// cannot use result differences as a cross-tenant existence oracle.
39/// THREAT[TM-TENANT-001]: the service boundary carries the required tenant key.
40#[async_trait]
41pub trait KnowledgeStore: Send + Sync {
42 async fn search_knowledge(
43 &self,
44 org_id: OrgId,
45 kb_public_ids: &[String],
46 query: &str,
47 kind: Option<&str>,
48 tags: &[String],
49 limit: usize,
50 ) -> Result<Vec<KnowledgeSearchHit>>;
51}
52
53/// Typed tool-context extension for Knowledge Base retrieval.
54#[derive(Clone)]
55pub struct KnowledgeStoreExt(pub Arc<dyn KnowledgeStore>);
56
57/// Typed tool-context extension for Knowledge Index retrieval.
58#[derive(Clone)]
59pub struct KnowledgeIndexSearchExt(pub Arc<dyn KnowledgeIndexSearch>);
60
61/// Citation result returned by the hosted Knowledge Index search service.
62pub type KnowledgeIndexSearchHit = KnowledgeIndexCitation;