use super::knowledge::{
KNOWLEDGE_SCHEMA_VERSION, KnowledgeAssessment, KnowledgeConfidence, KnowledgeEmbeddingProvider,
KnowledgeGraph, KnowledgeGraphEdge, KnowledgeGraphNode, KnowledgeGraphNodeKind,
KnowledgeGraphTraversal, KnowledgeLearningRequest, KnowledgeLearningResult,
KnowledgeLookupContext, KnowledgeRecord, KnowledgeRecordKind, KnowledgeRetrievalCandidate,
KnowledgeRetrievalQuery, KnowledgeRetrievalReport, KnowledgeScopeSelector,
KnowledgeStoreSnapshot, KnowledgeValidationError, MAX_KNOWLEDGE_RECORDS,
};
use fs2::FileExt;
use serde::Serialize;
use serde_json::Value;
use sha2::{Digest, Sha256};
use std::cmp::Ordering;
use std::collections::{BTreeMap, BTreeSet};
use std::fs::{self, File, OpenOptions};
use std::io::{self, Write};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering as AtomicOrdering};
use url::Url;
pub const DEFAULT_KNOWLEDGE_STORE_BYTES: usize = 4 * 1024 * 1024;
const STORE_LOCK_SUFFIX: &str = ".lock";
static TEMP_SEQUENCE: AtomicU64 = AtomicU64::new(1);
pub fn default_knowledge_store_path(profile: &str) -> PathBuf {
std::env::var_os("GLASS_CONFIG_HOME")
.map(PathBuf::from)
.or_else(dirs::config_dir)
.unwrap_or_else(|| PathBuf::from("."))
.join("glass")
.join("knowledge")
.join(format!("{profile}.json"))
}
pub fn default_knowledge_store_path_for_workspace(
profile: &str,
workspace_id: &str,
workspace_generation: Option<u64>,
) -> PathBuf {
let digest = Sha256::digest(
format!(
"{profile}\u{1f}{workspace_id}\u{1f}{:?}",
workspace_generation
)
.as_bytes(),
);
std::env::var_os("GLASS_CONFIG_HOME")
.map(PathBuf::from)
.or_else(dirs::config_dir)
.unwrap_or_else(|| PathBuf::from("."))
.join("glass")
.join(format!("workspace-{digest:x}.json"))
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct KnowledgeStoreLimits {
pub max_records: usize,
pub max_bytes: usize,
}
impl Default for KnowledgeStoreLimits {
fn default() -> Self {
Self {
max_records: MAX_KNOWLEDGE_RECORDS,
max_bytes: DEFAULT_KNOWLEDGE_STORE_BYTES,
}
}
}
impl KnowledgeStoreLimits {
fn validate(self) -> Result<(), KnowledgeStoreError> {
if self.max_records == 0 || self.max_records > MAX_KNOWLEDGE_RECORDS {
return Err(KnowledgeStoreError::InvalidConfiguration(format!(
"maxRecords must be between 1 and {MAX_KNOWLEDGE_RECORDS}"
)));
}
if self.max_bytes == 0 {
return Err(KnowledgeStoreError::InvalidConfiguration(
"maxBytes must be positive".into(),
));
}
Ok(())
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct KnowledgeStoreChange {
pub record_id: String,
pub retained: bool,
pub removed: bool,
pub pruned_record_ids: Vec<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct KnowledgeStoreStats {
pub record_count: usize,
pub serialized_bytes: usize,
pub candidate_count: usize,
pub observed_count: usize,
pub verified_count: usize,
pub stale_count: usize,
pub contradicted_count: usize,
pub quarantined_count: usize,
}
#[derive(Debug)]
pub struct KnowledgeStore {
path: PathBuf,
limits: KnowledgeStoreLimits,
snapshot: KnowledgeStoreSnapshot,
last_pruned: Option<Vec<String>>,
}
impl KnowledgeStore {
pub fn open(path: impl Into<PathBuf>) -> Result<Self, KnowledgeStoreError> {
Self::open_with_limits(path, KnowledgeStoreLimits::default())
}
pub fn open_with_limits(
path: impl Into<PathBuf>,
limits: KnowledgeStoreLimits,
) -> Result<Self, KnowledgeStoreError> {
limits.validate()?;
let path = path.into();
let snapshot = read_snapshot(&path)?;
validate_snapshot_size(&snapshot, limits.max_bytes)?;
Ok(Self {
path,
limits,
snapshot,
last_pruned: None,
})
}
pub fn path(&self) -> &Path {
&self.path
}
pub fn limits(&self) -> KnowledgeStoreLimits {
self.limits
}
pub fn snapshot(&self) -> &KnowledgeStoreSnapshot {
&self.snapshot
}
pub fn refresh(&mut self) -> Result<(), KnowledgeStoreError> {
let _lock = StoreLock::acquire(&self.path)?;
let snapshot = read_snapshot(&self.path)?;
validate_snapshot_size(&snapshot, self.limits.max_bytes)?;
self.snapshot = snapshot;
self.last_pruned = None;
Ok(())
}
pub fn get(&self, record_id: &str) -> Option<&KnowledgeRecord> {
self.snapshot
.records
.iter()
.find(|record| record.record_id == record_id)
}
pub fn assess(&self, context: &KnowledgeLookupContext) -> Vec<KnowledgeAssessment> {
self.snapshot
.records
.iter()
.map(|record| record.assess(context))
.collect()
}
pub fn retrieve(
&self,
context: &KnowledgeLookupContext,
query: &KnowledgeRetrievalQuery,
) -> KnowledgeRetrievalReport {
if !query.is_bounded() {
return KnowledgeRetrievalReport {
embeddings_used: false,
..KnowledgeRetrievalReport::default()
};
}
let limit = query.max_results.clamp(1, 16);
let mut candidates = self
.snapshot
.records
.iter()
.map(|record| record.retrieve_candidate(context, query))
.collect::<Vec<_>>();
candidates.sort_by(|left, right| {
let left_score = retrieval_score(left);
let right_score = retrieval_score(right);
right_score
.cmp(&left_score)
.then_with(|| left.record_id.cmp(&right.record_id))
});
let mut selected_record_ids = Vec::new();
for candidate in candidates
.iter_mut()
.filter(|candidate| candidate.rejection.is_none())
{
if selected_record_ids.len() >= limit {
break;
}
candidate.selected = true;
selected_record_ids.push(candidate.record_id.clone());
}
let rejected_record_ids = candidates
.iter()
.filter(|candidate| candidate.rejection.is_some())
.map(|candidate| candidate.record_id.clone())
.collect();
KnowledgeRetrievalReport {
candidates,
selected_record_ids,
rejected_record_ids,
embeddings_used: false,
}
}
pub fn retrieve_with_embeddings(
&self,
context: &KnowledgeLookupContext,
query: &KnowledgeRetrievalQuery,
provider: Option<&dyn KnowledgeEmbeddingProvider>,
) -> KnowledgeRetrievalReport {
let mut report = self.retrieve(context, query);
let Some(provider) = provider else {
return report;
};
report.embeddings_used = true;
for candidate in &mut report.candidates {
if let Some(record) = self.get(&candidate.record_id)
&& let Some(score_millis) = provider.similarity_millis(query, record)
{
candidate
.signals
.push(super::knowledge::KnowledgeRetrievalSignal {
kind: super::knowledge::KnowledgeRetrievalSignalKind::SemanticSimilarity,
detail: "optional embedding provider supplied a bounded similarity score"
.into(),
score_millis: Some(score_millis),
});
}
}
report
}
pub fn records(&self) -> &[KnowledgeRecord] {
&self.snapshot.records
}
pub fn export_scoped(
&self,
selector: &KnowledgeScopeSelector,
) -> Result<KnowledgeStoreSnapshot, KnowledgeStoreError> {
selector.validate()?;
let snapshot = KnowledgeStoreSnapshot {
schema_version: self.snapshot.schema_version,
records: self
.snapshot
.records
.iter()
.filter(|record| selector.matches(&record.scope))
.cloned()
.collect(),
};
snapshot.validate()?;
Ok(snapshot)
}
pub fn remove_scoped(
&mut self,
record_id: &str,
selector: &KnowledgeScopeSelector,
) -> Result<KnowledgeStoreChange, KnowledgeStoreError> {
selector.validate()?;
let record_id = record_id.to_owned();
self.mutate(|snapshot| {
let record = snapshot
.records
.iter()
.find(|record| record.record_id == record_id)
.ok_or_else(|| KnowledgeStoreError::NotFound(record_id.clone()))?;
if !selector.matches(&record.scope) {
return Err(KnowledgeStoreError::ScopeMismatch(record_id.clone()));
}
snapshot
.records
.retain(|record| record.record_id != record_id);
Ok(())
})?;
Ok(KnowledgeStoreChange {
record_id,
retained: false,
removed: true,
pruned_record_ids: self.last_pruned.take().unwrap_or_default(),
})
}
pub fn purge_scoped(
&mut self,
selector: &KnowledgeScopeSelector,
) -> Result<KnowledgePurgeResult, KnowledgeStoreError> {
selector.validate()?;
let mut removed_record_ids = Vec::new();
self.mutate(|snapshot| {
snapshot.records.retain(|record| {
if selector.matches(&record.scope) {
removed_record_ids.push(record.record_id.clone());
false
} else {
true
}
});
Ok(())
})?;
Ok(KnowledgePurgeResult {
removed_record_ids,
pruned_record_ids: self.last_pruned.take().unwrap_or_default(),
})
}
pub fn prune_scoped(
&mut self,
selector: &KnowledgeScopeSelector,
) -> Result<KnowledgePurgeResult, KnowledgeStoreError> {
selector.validate()?;
let mut removed_record_ids = Vec::new();
self.mutate(|snapshot| {
snapshot.records.retain(|record| {
let removable = selector.matches(&record.scope)
&& matches!(
record.confidence,
KnowledgeConfidence::Stale
| KnowledgeConfidence::Contradicted
| KnowledgeConfidence::Quarantined
);
if removable {
removed_record_ids.push(record.record_id.clone());
}
!removable
});
Ok(())
})?;
Ok(KnowledgePurgeResult {
removed_record_ids,
pruned_record_ids: self.last_pruned.take().unwrap_or_default(),
})
}
pub fn stats(&self) -> Result<KnowledgeStoreStats, KnowledgeStoreError> {
let mut stats = KnowledgeStoreStats {
record_count: self.snapshot.records.len(),
serialized_bytes: serialized_size(&self.snapshot)?,
candidate_count: 0,
observed_count: 0,
verified_count: 0,
stale_count: 0,
contradicted_count: 0,
quarantined_count: 0,
};
for record in &self.snapshot.records {
match record.confidence {
KnowledgeConfidence::Candidate => stats.candidate_count += 1,
KnowledgeConfidence::Observed => stats.observed_count += 1,
KnowledgeConfidence::Verified => stats.verified_count += 1,
KnowledgeConfidence::Stale => stats.stale_count += 1,
KnowledgeConfidence::Contradicted => stats.contradicted_count += 1,
KnowledgeConfidence::Quarantined => stats.quarantined_count += 1,
}
}
Ok(stats)
}
pub fn replace_snapshot(
&mut self,
snapshot: KnowledgeStoreSnapshot,
) -> Result<(), KnowledgeStoreError> {
snapshot
.validate()
.map_err(KnowledgeStoreError::InvalidContract)?;
if snapshot.records.len() > self.limits.max_records {
return Err(KnowledgeStoreError::Capacity(
"snapshot exceeds the configured record limit".into(),
));
}
validate_snapshot_size(&snapshot, self.limits.max_bytes)?;
let _lock = StoreLock::acquire(&self.path)?;
write_snapshot(&self.path, &snapshot, self.limits.max_bytes)?;
self.snapshot = snapshot;
self.last_pruned = None;
Ok(())
}
pub fn transition(
&mut self,
record_id: &str,
next: KnowledgeConfidence,
reason: String,
observed_at: String,
fresh_verification: bool,
) -> Result<KnowledgeStoreChange, KnowledgeStoreError> {
let record_id = record_id.to_owned();
self.mutate(|snapshot| {
let record = snapshot
.records
.iter_mut()
.find(|record| record.record_id == record_id)
.ok_or_else(|| KnowledgeStoreError::NotFound(record_id.clone()))?;
record.transition(next, reason, observed_at, fresh_verification)?;
Ok(())
})?;
Ok(KnowledgeStoreChange {
retained: true,
removed: false,
record_id,
pruned_record_ids: self.last_pruned.take().unwrap_or_default(),
})
}
pub fn purge_origin(
&mut self,
origin: &str,
) -> Result<KnowledgePurgeResult, KnowledgeStoreError> {
let mut removed_record_ids = Vec::new();
self.mutate(|snapshot| {
snapshot.records.retain(|record| {
if record.scope.origin == origin {
removed_record_ids.push(record.record_id.clone());
false
} else {
true
}
});
Ok(())
})?;
Ok(KnowledgePurgeResult {
removed_record_ids,
pruned_record_ids: self.last_pruned.take().unwrap_or_default(),
})
}
pub fn upsert(
&mut self,
record: KnowledgeRecord,
) -> Result<KnowledgeStoreChange, KnowledgeStoreError> {
record.validate()?;
if record.to_canonical_json()?.len() > self.limits.max_bytes {
return Err(KnowledgeStoreError::Capacity(
"record exceeds the configured store byte limit".into(),
));
}
let record_id = record.record_id.clone();
self.mutate(|snapshot| {
if let Some(existing) = snapshot
.records
.iter_mut()
.find(|existing| existing.record_id == record_id)
{
*existing = record;
} else {
snapshot.records.push(record);
}
Ok(())
})?;
let retained = self.get(&record_id).is_some();
if !retained {
return Err(KnowledgeStoreError::Capacity(
"record was pruned by the configured store limits".into(),
));
}
Ok(KnowledgeStoreChange {
record_id,
retained,
removed: false,
pruned_record_ids: self.last_pruned.take().unwrap_or_default(),
})
}
pub fn remove(&mut self, record_id: &str) -> Result<KnowledgeStoreChange, KnowledgeStoreError> {
let record_id = record_id.to_owned();
let existed = self.mutate(|snapshot| {
let before = snapshot.records.len();
snapshot
.records
.retain(|record| record.record_id != record_id);
Ok(before != snapshot.records.len())
})?;
Ok(KnowledgeStoreChange {
record_id,
retained: false,
removed: existed,
pruned_record_ids: if existed {
self.last_pruned.take().unwrap_or_default()
} else {
Vec::new()
},
})
}
pub fn learn_verified(
&mut self,
request: KnowledgeLearningRequest<'_>,
) -> Result<KnowledgeLearningResult, KnowledgeStoreError> {
request.policy.validate()?;
request.observation.validate().map_err(|error| {
KnowledgeStoreError::InvalidContract(KnowledgeValidationError::new(
"observation",
error.to_string(),
))
})?;
request.evidence.validate_against(request.observation)?;
let route_url = Url::parse(&request.observation.route.url).map_err(|error| {
KnowledgeStoreError::InvalidContract(KnowledgeValidationError::new(
"observation.route.url",
format!("invalid URL: {error}"),
))
})?;
let route_origin = route_url.origin().ascii_serialization();
let route_path = if route_url.path().is_empty() {
"/"
} else {
route_url.path()
};
let scope = &request.build.scope;
let path_matches = scope.path_pattern == route_path
|| scope
.path_pattern
.strip_suffix('*')
.is_some_and(|prefix| route_path.starts_with(prefix));
if scope.origin != route_origin {
return Err(KnowledgeStoreError::InvalidContract(
KnowledgeValidationError::new(
"build.scope.origin",
"learning scope origin must match the fresh observation route",
),
));
}
if !path_matches {
return Err(KnowledgeStoreError::InvalidContract(
KnowledgeValidationError::new(
"build.scope.pathPattern",
"learning scope path pattern must match the fresh observation route",
),
));
}
let mut build = request.build.clone();
if build.record_id.is_empty() {
build.record_id =
KnowledgeRecord::deterministic_page_family_id(request.observation, &build.scope)?;
}
let incoming = KnowledgeRecord::from_verified_observation(
request.observation,
build,
&request.evidence,
)?;
let record_id = incoming.record_id.clone();
let compatibility_key = request.evidence.compatibility_key.clone();
let mut result = KnowledgeLearningResult {
record_id: record_id.clone(),
confidence: incoming.confidence,
verification_count: incoming.source.verification_count,
promoted: false,
created: false,
};
self.mutate(|snapshot| {
if let Some(existing) = snapshot
.records
.iter_mut()
.find(|record| record.record_id == record_id)
{
let existing_key = existing
.data
.get("verifiedUseKey")
.and_then(Value::as_str)
.unwrap_or_default();
if existing_key != compatibility_key {
return Err(KnowledgeStoreError::InvalidContract(
KnowledgeValidationError::new(
"compatibilityKey",
"verified workflow evidence is incompatible with the stored record",
),
));
}
let next_count = existing.source.verification_count.saturating_add(1);
let next = if next_count >= request.policy.required_verified_uses {
KnowledgeConfidence::Verified
} else {
KnowledgeConfidence::Candidate
};
existing.transition_with_validation(
next,
if next == KnowledgeConfidence::Verified {
"repeated compatible guarded workflow use promoted record"
} else {
"compatible guarded workflow use refreshed candidate"
}
.into(),
request.evidence.observed_at.clone(),
request.evidence.guarded_revision,
request.evidence.evidence_quality,
)?;
existing.data["verifiedUseKey"] = Value::String(compatibility_key.clone());
result.confidence = existing.confidence;
result.verification_count = existing.source.verification_count;
result.promoted = existing.confidence == KnowledgeConfidence::Verified;
} else {
let mut created = incoming.clone();
if request.policy.required_verified_uses <= 1 {
created.source.verification_count = 0;
created.transition_with_validation(
KnowledgeConfidence::Verified,
"single configured guarded workflow use promoted record".into(),
request.evidence.observed_at.clone(),
request.evidence.guarded_revision,
request.evidence.evidence_quality,
)?;
result.promoted = true;
}
result.confidence = created.confidence;
result.verification_count = created.source.verification_count;
snapshot.records.push(created);
result.created = true;
}
Ok(())
})?;
Ok(result)
}
pub fn contradict(
&mut self,
record_id: &str,
reason: String,
observed_at: String,
current_revision: u64,
evidence_quality: super::knowledge::KnowledgeEvidenceQuality,
) -> Result<KnowledgeStoreChange, KnowledgeStoreError> {
let id = record_id.to_owned();
self.mutate(|snapshot| {
let record = snapshot
.records
.iter_mut()
.find(|record| record.record_id == id)
.ok_or_else(|| KnowledgeStoreError::NotFound(id.clone()))?;
record.transition_with_validation(
KnowledgeConfidence::Contradicted,
reason,
observed_at,
current_revision,
evidence_quality,
)?;
Ok(())
})?;
Ok(KnowledgeStoreChange {
record_id: id,
retained: true,
removed: false,
pruned_record_ids: self.last_pruned.take().unwrap_or_default(),
})
}
pub fn graph(&self) -> KnowledgeGraph {
let mut nodes = BTreeMap::new();
let mut edges = Vec::new();
for record in &self.snapshot.records {
let record_node = format!("record:{}", record.record_id);
nodes.insert(
record_node.clone(),
KnowledgeGraphNode {
id: record_node.clone(),
kind: KnowledgeGraphNodeKind::Record,
},
);
if let Some(page_kind) = record.data.get("pageKind").and_then(Value::as_str) {
let id = format!("page:{}", page_kind.to_ascii_lowercase());
nodes.entry(id.clone()).or_insert(KnowledgeGraphNode {
id: id.clone(),
kind: KnowledgeGraphNodeKind::PageKind,
});
edges.push(KnowledgeGraphEdge {
from: record_node.clone(),
to: id,
relation: "hasPageKind".into(),
});
}
for landmark in &record.invalidation.required_landmarks {
let id = format!("landmark:{}", landmark.to_ascii_lowercase());
nodes.entry(id.clone()).or_insert(KnowledgeGraphNode {
id: id.clone(),
kind: KnowledgeGraphNodeKind::Landmark,
});
edges.push(KnowledgeGraphEdge {
from: record_node.clone(),
to: id,
relation: "requiresLandmark".into(),
});
}
if record.kind == KnowledgeRecordKind::WorkflowEntryPoint {
let id = format!("workflow:{}", record.record_id);
nodes.entry(id.clone()).or_insert(KnowledgeGraphNode {
id: id.clone(),
kind: KnowledgeGraphNodeKind::Workflow,
});
edges.push(KnowledgeGraphEdge {
from: record_node,
to: id,
relation: "workflowEntry".into(),
});
}
}
edges.sort_by(|left, right| {
(&left.from, &left.to, &left.relation).cmp(&(&right.from, &right.to, &right.relation))
});
KnowledgeGraph {
nodes: nodes.into_values().collect(),
edges,
}
}
pub fn traverse_graph(
&self,
start: &str,
max_depth: usize,
max_nodes: usize,
) -> Result<KnowledgeGraphTraversal, KnowledgeStoreError> {
if max_depth > 8 || max_nodes == 0 || max_nodes > 256 {
return Err(KnowledgeStoreError::InvalidConfiguration(
"graph traversal bounds exceed the local contract".into(),
));
}
let graph = self.graph();
if !graph.nodes.iter().any(|node| node.id == start) {
return Err(KnowledgeStoreError::NotFound(start.into()));
}
let mut frontier = vec![(start.to_owned(), 0usize)];
let mut visited = BTreeSet::from([start.to_owned()]);
let mut edges = Vec::new();
let mut truncated = false;
while let Some((current, depth)) = frontier.pop() {
if depth >= max_depth {
continue;
}
for edge in graph.edges.iter().filter(|edge| edge.from == current) {
if visited.len() >= max_nodes && !visited.contains(&edge.to) {
truncated = true;
continue;
}
edges.push(edge.clone());
if visited.insert(edge.to.clone()) {
frontier.push((edge.to.clone(), depth + 1));
}
}
}
Ok(KnowledgeGraphTraversal {
start: start.into(),
max_depth,
node_ids: visited.into_iter().collect(),
edges,
truncated,
})
}
pub fn supersede(
&mut self,
old_record_id: &str,
new_record_id: &str,
observed_at: String,
current_revision: u64,
evidence_quality: super::knowledge::KnowledgeEvidenceQuality,
) -> Result<KnowledgeStoreChange, KnowledgeStoreError> {
if self.get(new_record_id).is_none() {
return Err(KnowledgeStoreError::NotFound(new_record_id.into()));
}
self.contradict(
old_record_id,
format!("record superseded by {new_record_id}"),
observed_at,
current_revision,
evidence_quality,
)
}
}
impl KnowledgeStore {
fn mutate<T, F>(&mut self, operation: F) -> Result<T, KnowledgeStoreError>
where
F: FnOnce(&mut KnowledgeStoreSnapshot) -> Result<T, KnowledgeStoreError>,
{
let _lock = StoreLock::acquire(&self.path)?;
let mut snapshot = read_snapshot(&self.path)?;
let result = operation(&mut snapshot)?;
let pruned = prune_snapshot(&mut snapshot, self.limits)?;
write_snapshot(&self.path, &snapshot, self.limits.max_bytes)?;
self.snapshot = snapshot;
self.last_pruned = Some(pruned);
Ok(result)
}
}
fn read_snapshot(path: &Path) -> Result<KnowledgeStoreSnapshot, KnowledgeStoreError> {
let bytes = match fs::read(path) {
Ok(bytes) => bytes,
Err(error) if error.kind() == io::ErrorKind::NotFound => {
return Ok(KnowledgeStoreSnapshot {
schema_version: KNOWLEDGE_SCHEMA_VERSION,
records: Vec::new(),
});
}
Err(error) => return Err(KnowledgeStoreError::Io(error)),
};
let snapshot = serde_json::from_slice::<KnowledgeStoreSnapshot>(&bytes)
.map_err(|error| KnowledgeStoreError::Corrupt(format!("invalid JSON snapshot: {error}")))?;
snapshot
.validate()
.map_err(KnowledgeStoreError::InvalidContract)?;
Ok(snapshot)
}
fn write_snapshot(
path: &Path,
snapshot: &KnowledgeStoreSnapshot,
max_bytes: usize,
) -> Result<(), KnowledgeStoreError> {
let canonical = snapshot
.to_canonical_json()
.map_err(KnowledgeStoreError::InvalidContract)?;
if canonical.len() > max_bytes {
return Err(KnowledgeStoreError::Capacity(
"snapshot exceeds the configured store byte limit".into(),
));
}
let parent = parent_dir(path);
fs::create_dir_all(parent).map_err(KnowledgeStoreError::Io)?;
let file_name = path
.file_name()
.and_then(|name| name.to_str())
.ok_or_else(|| {
KnowledgeStoreError::InvalidConfiguration("store path has no filename".into())
})?;
let sequence = TEMP_SEQUENCE.fetch_add(1, AtomicOrdering::Relaxed);
let temporary = parent.join(format!(
".{file_name}.{}.{}.tmp",
std::process::id(),
sequence
));
let result = (|| {
let mut file = OpenOptions::new()
.write(true)
.create_new(true)
.open(&temporary)
.map_err(KnowledgeStoreError::Io)?;
file.write_all(canonical.as_bytes())
.map_err(KnowledgeStoreError::Io)?;
file.sync_all().map_err(KnowledgeStoreError::Io)?;
fs::rename(&temporary, path).map_err(KnowledgeStoreError::Io)?;
#[cfg(unix)]
File::open(parent)
.and_then(|directory| directory.sync_all())
.map_err(KnowledgeStoreError::Io)?;
Ok(())
})();
if result.is_err() {
let _ = fs::remove_file(&temporary);
}
result
}
fn validate_snapshot_size(
snapshot: &KnowledgeStoreSnapshot,
max_bytes: usize,
) -> Result<(), KnowledgeStoreError> {
let bytes = snapshot
.to_canonical_json()
.map_err(KnowledgeStoreError::InvalidContract)?
.len();
if bytes > max_bytes {
return Err(KnowledgeStoreError::Capacity(format!(
"snapshot is {bytes} bytes, exceeding the {max_bytes}-byte limit"
)));
}
Ok(())
}
fn prune_snapshot(
snapshot: &mut KnowledgeStoreSnapshot,
limits: KnowledgeStoreLimits,
) -> Result<Vec<String>, KnowledgeStoreError> {
let mut pruned = Vec::new();
while snapshot.records.len() > limits.max_records
|| serialized_size(snapshot)? > limits.max_bytes
{
let Some(index) = snapshot
.records
.iter()
.enumerate()
.min_by(|(_, left), (_, right)| prune_order(left, right))
.map(|(index, _)| index)
else {
break;
};
pruned.push(snapshot.records.remove(index).record_id);
}
if serialized_size(snapshot)? > limits.max_bytes {
return Err(KnowledgeStoreError::Capacity(
"cannot fit the snapshot within the configured byte limit".into(),
));
}
Ok(pruned)
}
fn serialized_size(snapshot: &KnowledgeStoreSnapshot) -> Result<usize, KnowledgeStoreError> {
snapshot
.to_canonical_json()
.map(|json| json.len())
.map_err(KnowledgeStoreError::InvalidContract)
}
fn prune_order(left: &KnowledgeRecord, right: &KnowledgeRecord) -> Ordering {
confidence_rank(left.confidence)
.cmp(&confidence_rank(right.confidence))
.then_with(|| {
left.source
.last_verified_at
.cmp(&right.source.last_verified_at)
})
.then_with(|| left.record_id.cmp(&right.record_id))
}
fn confidence_rank(confidence: KnowledgeConfidence) -> u8 {
match confidence {
KnowledgeConfidence::Quarantined => 0,
KnowledgeConfidence::Contradicted => 1,
KnowledgeConfidence::Stale => 2,
KnowledgeConfidence::Candidate => 3,
KnowledgeConfidence::Observed => 4,
KnowledgeConfidence::Verified => 5,
}
}
fn retrieval_score(candidate: &KnowledgeRetrievalCandidate) -> u16 {
candidate
.signals
.iter()
.filter_map(|signal| signal.score_millis)
.max()
.unwrap_or_default()
}
struct StoreLock {
file: File,
}
impl StoreLock {
fn acquire(path: &Path) -> Result<Self, KnowledgeStoreError> {
let lock_path = PathBuf::from(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
fs::create_dir_all(parent_dir(&lock_path)).map_err(KnowledgeStoreError::Io)?;
let file = OpenOptions::new()
.create(true)
.truncate(false)
.read(true)
.write(true)
.open(lock_path)
.map_err(KnowledgeStoreError::Io)?;
file.lock_exclusive().map_err(KnowledgeStoreError::Io)?;
Ok(Self { file })
}
}
fn parent_dir(path: &Path) -> &Path {
path.parent()
.filter(|parent| !parent.as_os_str().is_empty())
.unwrap_or_else(|| Path::new("."))
}
impl Drop for StoreLock {
fn drop(&mut self) {
let _ = FileExt::unlock(&self.file);
}
}
#[derive(Debug)]
pub enum KnowledgeStoreError {
Io(io::Error),
Corrupt(String),
InvalidContract(KnowledgeValidationError),
InvalidConfiguration(String),
Capacity(String),
NotFound(String),
ScopeMismatch(String),
}
impl std::fmt::Display for KnowledgeStoreError {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Io(error) => write!(formatter, "knowledge store I/O error: {error}"),
Self::Corrupt(reason) => write!(formatter, "knowledge store is corrupt: {reason}"),
Self::InvalidContract(error) => write!(formatter, "knowledge contract: {error}"),
Self::InvalidConfiguration(reason) => {
write!(formatter, "invalid knowledge store configuration: {reason}")
}
Self::Capacity(reason) => write!(formatter, "knowledge store capacity: {reason}"),
Self::NotFound(record_id) => {
write!(formatter, "knowledge record not found: {record_id}")
}
Self::ScopeMismatch(record_id) => {
write!(
formatter,
"knowledge record is outside the requested scope: {record_id}"
)
}
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct KnowledgePurgeResult {
pub removed_record_ids: Vec<String>,
pub pruned_record_ids: Vec<String>,
}
impl std::error::Error for KnowledgeStoreError {}
impl From<KnowledgeValidationError> for KnowledgeStoreError {
fn from(error: KnowledgeValidationError) -> Self {
Self::InvalidContract(error)
}
}
#[cfg(test)]
mod tests {
use super::super::knowledge::{
KnowledgeBackendCapability, KnowledgeBackendKind, KnowledgeBackendProvenance,
KnowledgeCurrentValidation, KnowledgeEmbeddingProvider, KnowledgeEvidenceQuality,
KnowledgeMemoryInfluence, KnowledgePortability, KnowledgeRejectionReason,
KnowledgeRetrievalExplanation, KnowledgeSurfaceCoverage, KnowledgeSurfaceKind,
KnowledgeSurfaceProvenance, KnowledgeUnderstandingLevel,
};
use super::*;
use crate::browser::session::{
KnowledgeInvalidation, KnowledgeLearningPolicy, KnowledgeLearningRequest,
KnowledgeLookupContext, KnowledgeProfileScope, KnowledgeRecordBuildOptions,
KnowledgeRecordKind, KnowledgeScope, KnowledgeScopeSelector, KnowledgeSource,
KnowledgeVerifiedWorkflowEvidence, SemanticObservation,
};
use serde_json::json;
use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
static TEST_SEQUENCE: AtomicU64 = AtomicU64::new(1);
fn test_path() -> PathBuf {
std::env::temp_dir().join(format!(
"glass-knowledge-store-{}-{}",
std::process::id(),
TEST_SEQUENCE.fetch_add(1, Ordering::Relaxed)
))
}
fn record(id: &str, confidence: KnowledgeConfidence, verified_at: &str) -> KnowledgeRecord {
KnowledgeRecord {
schema_version: KNOWLEDGE_SCHEMA_VERSION,
record_id: id.into(),
kind: KnowledgeRecordKind::PageFamily,
scope: KnowledgeScope {
origin: "https://example.test".into(),
path_pattern: "/docs/*".into(),
profile_scope: KnowledgeProfileScope::Anonymous,
profile_key: None,
locale: None,
tenant_key: None,
browser_family: "chromium".into(),
browser_version_range: None,
glass_schema_version: 1,
policy_preset: "balanced".into(),
workspace_id: None,
workspace_generation: None,
},
source: KnowledgeSource {
first_seen_at: format!("2026-07-27T00:00:{verified_at:0>2}Z"),
last_verified_at: format!("2026-07-27T00:00:{verified_at:0>2}Z"),
glass_version: "0.2.0".into(),
verification_count: 1,
surface: KnowledgeSurfaceProvenance {
kind: KnowledgeSurfaceKind::Document,
understanding: KnowledgeUnderstandingLevel::Strong,
coverage: KnowledgeSurfaceCoverage::Semantic,
extension_id: None,
},
backend: KnowledgeBackendProvenance {
backend: KnowledgeBackendKind::Cdp,
profile: "production".into(),
capabilities: vec![
KnowledgeBackendCapability::SemanticExtraction,
KnowledgeBackendCapability::Verification,
],
},
},
confidence,
invalidation: KnowledgeInvalidation::default(),
data: json!({"pageKind": "documentation"}),
portability: KnowledgePortability::SurfacePortable,
memory_influence: KnowledgeMemoryInfluence::None,
retrieval: KnowledgeRetrievalExplanation {
signals: Vec::new(),
current_validation: KnowledgeCurrentValidation {
status: super::super::knowledge::KnowledgeCurrentValidationStatus::Validated,
evidence_quality: KnowledgeEvidenceQuality::Strong,
current_revision: Some(1),
validated_at: Some("2026-07-27T00:00:00Z".into()),
},
},
history: Vec::new(),
}
}
#[test]
fn upsert_reopens_from_an_atomic_snapshot() {
let path = test_path();
let mut store = KnowledgeStore::open(&path).unwrap();
store
.upsert(record("knowledge_1", KnowledgeConfidence::Verified, "2"))
.unwrap();
let reopened = KnowledgeStore::open(&path).unwrap();
assert!(reopened.get("knowledge_1").is_some());
assert_eq!(reopened.snapshot().records.len(), 1);
let _ = fs::remove_file(&path);
let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
}
#[test]
fn pruning_prefers_low_confidence_and_old_records() {
let path = test_path();
let limits = KnowledgeStoreLimits {
max_records: 2,
max_bytes: DEFAULT_KNOWLEDGE_STORE_BYTES,
};
let mut store = KnowledgeStore::open_with_limits(&path, limits).unwrap();
store
.upsert(record("verified", KnowledgeConfidence::Verified, "1"))
.unwrap();
store
.upsert(record("stale", KnowledgeConfidence::Stale, "3"))
.unwrap();
let change = store
.upsert(record("observed", KnowledgeConfidence::Observed, "2"))
.unwrap();
assert_eq!(change.pruned_record_ids, vec!["stale"]);
assert!(store.get("verified").is_some());
assert!(store.get("observed").is_some());
let _ = fs::remove_file(&path);
let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
}
#[test]
fn malformed_snapshot_is_not_silently_replaced() {
let path = test_path();
fs::write(&path, b"not-json").unwrap();
let error = KnowledgeStore::open(&path).unwrap_err();
assert!(matches!(error, KnowledgeStoreError::Corrupt(_)));
let _ = fs::remove_file(&path);
}
#[test]
fn assessment_is_read_only_and_returns_current_evidence() {
let path = test_path();
let mut store = KnowledgeStore::open(&path).unwrap();
store
.upsert(record("knowledge_1", KnowledgeConfidence::Verified, "01"))
.unwrap();
let context = KnowledgeLookupContext {
origin: "https://example.test".into(),
path: "/docs/start".into(),
profile_scope: KnowledgeProfileScope::Anonymous,
profile_key: None,
locale: None,
tenant_key: None,
browser_family: "chromium".into(),
browser_version: None,
glass_schema_version: 1,
policy_preset: "balanced".into(),
current_revision: 1,
current_extension_id: None,
landmarks: vec!["documentation".into()],
now_epoch_seconds: chrono::DateTime::parse_from_rfc3339("2026-07-27T00:00:02Z")
.unwrap()
.timestamp(),
surface_kind: None,
backend_kind: None,
backend_capabilities: Vec::new(),
workspace_id: None,
workspace_generation: None,
};
let assessments = store.assess(&context);
assert_eq!(assessments.len(), 1);
assert_eq!(assessments[0].record_id, "knowledge_1");
assert_eq!(store.snapshot().records.len(), 1);
let _ = fs::remove_file(&path);
let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
}
#[test]
fn retrieval_report_is_explicitly_bounded_and_auditable_without_embeddings() {
let path = test_path();
let mut store = KnowledgeStore::open(&path).unwrap();
store
.upsert(record("eligible", KnowledgeConfidence::Observed, "01"))
.unwrap();
let mut stale = record("stale", KnowledgeConfidence::Stale, "01");
stale.retrieval.current_validation = KnowledgeCurrentValidation {
status: super::super::knowledge::KnowledgeCurrentValidationStatus::Stale,
evidence_quality: KnowledgeEvidenceQuality::None,
current_revision: None,
validated_at: None,
};
store.upsert(stale).unwrap();
let context = KnowledgeLookupContext {
origin: "https://example.test".into(),
path: "/docs/start".into(),
profile_scope: KnowledgeProfileScope::Anonymous,
profile_key: None,
locale: None,
tenant_key: None,
browser_family: "chromium".into(),
browser_version: None,
glass_schema_version: 1,
policy_preset: "balanced".into(),
landmarks: vec!["documentation".into()],
now_epoch_seconds: chrono::DateTime::parse_from_rfc3339("2026-07-27T00:00:02Z")
.unwrap()
.timestamp(),
current_revision: 1,
surface_kind: Some(KnowledgeSurfaceKind::Document),
backend_kind: Some(KnowledgeBackendKind::Cdp),
backend_capabilities: vec![
KnowledgeBackendCapability::SemanticExtraction,
KnowledgeBackendCapability::Verification,
],
current_extension_id: None,
workspace_id: None,
workspace_generation: None,
};
let report = store.retrieve(
&context,
&KnowledgeRetrievalQuery {
page_kind: Some("documentation".into()),
max_results: 1,
..KnowledgeRetrievalQuery::default()
},
);
assert!(!report.embeddings_used);
assert_eq!(report.selected_record_ids, vec!["eligible"]);
assert_eq!(report.rejected_record_ids, vec!["stale"]);
let stale = report
.candidates
.iter()
.find(|candidate| candidate.record_id == "stale")
.unwrap();
assert_eq!(
stale.current_validation.status,
super::super::knowledge::KnowledgeCurrentValidationStatus::Stale
);
assert_eq!(
stale.rejection,
Some(KnowledgeRejectionReason::StaleLifecycle)
);
let _ = fs::remove_file(&path);
let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
}
#[test]
fn lifecycle_management_and_stats_are_persisted() {
let path = test_path();
let mut store = KnowledgeStore::open(&path).unwrap();
store
.upsert(record("keep", KnowledgeConfidence::Observed, "01"))
.unwrap();
store
.upsert(record("purge", KnowledgeConfidence::Observed, "02"))
.unwrap();
store
.transition(
"keep",
KnowledgeConfidence::Verified,
"fresh landmark verification".into(),
"2026-07-27T00:00:03Z".into(),
true,
)
.unwrap();
let stats = store.stats().unwrap();
assert_eq!(stats.record_count, 2);
assert_eq!(stats.verified_count, 1);
let purge = store.purge_origin("https://example.test").unwrap();
assert_eq!(purge.removed_record_ids, vec!["keep", "purge"]);
assert!(store.records().is_empty());
let _ = fs::remove_file(&path);
let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
}
#[test]
fn workspace_path_hashes_untrusted_profile_and_is_bounded() {
let path =
default_knowledge_store_path_for_workspace("../escape", "workspace-alpha", Some(7));
let file_name = path.file_name().unwrap().to_string_lossy();
assert!(file_name.starts_with("workspace-"));
assert!(!file_name.contains(".."));
assert!(!path.to_string_lossy().contains("../escape"));
}
#[test]
fn scoped_management_exports_and_prunes_only_matching_profile() {
let path = test_path();
let mut store = KnowledgeStore::open(&path).unwrap();
store
.upsert(record("anonymous", KnowledgeConfidence::Stale, "01"))
.unwrap();
let mut profile_record = record("profile", KnowledgeConfidence::Stale, "02");
profile_record.scope.profile_scope = KnowledgeProfileScope::ProfileBound;
profile_record.scope.profile_key = Some("alice".into());
store.upsert(profile_record).unwrap();
let anonymous = KnowledgeScopeSelector::new(
"https://example.test".into(),
KnowledgeProfileScope::Anonymous,
None,
None,
None,
)
.unwrap();
let exported = store.export_scoped(&anonymous).unwrap();
assert_eq!(
exported
.records
.iter()
.map(|record| record.record_id.as_str())
.collect::<Vec<_>>(),
vec!["anonymous"]
);
let removed = store.prune_scoped(&anonymous).unwrap();
assert_eq!(removed.removed_record_ids, vec!["anonymous"]);
assert!(store.get("profile").is_some());
let _ = fs::remove_file(&path);
let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
}
#[test]
fn scoped_removal_rejects_cross_profile_access() {
let path = test_path();
let mut store = KnowledgeStore::open(&path).unwrap();
store
.upsert(record("anonymous", KnowledgeConfidence::Observed, "01"))
.unwrap();
let profile = KnowledgeScopeSelector::new(
"https://example.test".into(),
KnowledgeProfileScope::ProfileBound,
Some("alice".into()),
None,
None,
)
.unwrap();
assert!(matches!(
store.remove_scoped("anonymous", &profile),
Err(KnowledgeStoreError::ScopeMismatch(id)) if id == "anonymous"
));
assert!(store.get("anonymous").is_some());
let _ = fs::remove_file(&path);
let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
}
#[test]
fn scope_selector_rejects_unbounded_or_sensitive_dimensions() {
assert!(
KnowledgeScopeSelector::new(
"https://example.test/path".into(),
KnowledgeProfileScope::Anonymous,
None,
None,
None,
)
.is_err()
);
assert!(
KnowledgeScopeSelector::new(
"https://example.test".into(),
KnowledgeProfileScope::ProfileBound,
None,
None,
None,
)
.is_err()
);
assert!(
KnowledgeScopeSelector::new(
"https://example.test".into(),
KnowledgeProfileScope::Anonymous,
None,
None,
Some(1),
)
.is_err()
);
assert!(
KnowledgeScopeSelector::new(
"https://example.test".into(),
KnowledgeProfileScope::ProfileBound,
Some("session-token".into()),
None,
None,
)
.is_err()
);
}
fn learning_observation() -> SemanticObservation {
let corpus: serde_json::Value = serde_json::from_str(include_str!(
"../../../benchmarks/scenarios/semantic-observation-v1.json"
))
.unwrap();
SemanticObservation::from_json(&corpus["fixtures"][1]["observation"].to_string()).unwrap()
}
fn learning_build(record_id: &str) -> KnowledgeRecordBuildOptions {
let mut scope = record("template", KnowledgeConfidence::Observed, "01").scope;
scope.path_pattern = "/search*".into();
KnowledgeRecordBuildOptions {
record_id: record_id.into(),
scope,
glass_version: "0.2.0".into(),
observed_at: "2026-08-07T00:00:00Z".into(),
surface: KnowledgeSurfaceProvenance {
kind: KnowledgeSurfaceKind::Document,
understanding: KnowledgeUnderstandingLevel::Strong,
coverage: KnowledgeSurfaceCoverage::Semantic,
extension_id: None,
},
backend: KnowledgeBackendProvenance {
backend: KnowledgeBackendKind::Cdp,
profile: "production".into(),
capabilities: vec![
KnowledgeBackendCapability::SemanticExtraction,
KnowledgeBackendCapability::Verification,
],
},
portability: KnowledgePortability::SurfacePortable,
current_validation: KnowledgeCurrentValidation::default(),
}
}
fn learning_evidence(
observation: &SemanticObservation,
compatibility_key: &str,
) -> KnowledgeVerifiedWorkflowEvidence {
KnowledgeVerifiedWorkflowEvidence {
guarded_revision: observation.revision,
successful: true,
postcondition_verified: true,
evidence_quality: KnowledgeEvidenceQuality::Strong,
observed_at: "2026-08-07T00:00:00Z".into(),
compatibility_key: compatibility_key.into(),
private_context: false,
incognito: false,
}
}
fn learning_request<'a>(
observation: &'a SemanticObservation,
record_id: &str,
compatibility_key: &str,
) -> KnowledgeLearningRequest<'a> {
KnowledgeLearningRequest {
observation,
build: learning_build(record_id),
evidence: learning_evidence(observation, compatibility_key),
policy: KnowledgeLearningPolicy {
required_verified_uses: 2,
},
}
}
fn retrieval_context() -> KnowledgeLookupContext {
KnowledgeLookupContext {
origin: "https://example.test".into(),
path: "/docs/start".into(),
profile_scope: KnowledgeProfileScope::Anonymous,
profile_key: None,
locale: None,
tenant_key: None,
browser_family: "chromium".into(),
browser_version: None,
glass_schema_version: 1,
policy_preset: "balanced".into(),
landmarks: vec!["documentation".into()],
now_epoch_seconds: 1_785_542_400,
current_revision: 1,
surface_kind: Some(KnowledgeSurfaceKind::Document),
backend_kind: Some(KnowledgeBackendKind::Cdp),
backend_capabilities: vec![
KnowledgeBackendCapability::SemanticExtraction,
KnowledgeBackendCapability::Verification,
],
current_extension_id: None,
workspace_id: None,
workspace_generation: None,
}
}
#[test]
fn learning_rejects_failed_private_truncated_and_sensitive_evidence() {
let path = test_path();
let mut store = KnowledgeStore::open(&path).unwrap();
let observation = learning_observation();
let mut failed = learning_evidence(&observation, "failed");
failed.successful = false;
let error = store
.learn_verified(KnowledgeLearningRequest {
observation: &observation,
build: learning_build("failed"),
evidence: failed,
policy: KnowledgeLearningPolicy::default(),
})
.unwrap_err();
assert!(matches!(
error,
KnowledgeStoreError::InvalidContract(error) if error.path == "workflow"
));
let mut private = learning_evidence(&observation, "private");
private.private_context = true;
let error = store
.learn_verified(KnowledgeLearningRequest {
observation: &observation,
build: learning_build("private"),
evidence: private,
policy: KnowledgeLearningPolicy::default(),
})
.unwrap_err();
assert!(matches!(
error,
KnowledgeStoreError::InvalidContract(error) if error.path == "privacy"
));
let mut truncated_observation = observation.clone();
truncated_observation.limits.truncated = true;
let error = store
.learn_verified(learning_request(
&truncated_observation,
"truncated",
"truncated",
))
.unwrap_err();
assert!(matches!(
error,
KnowledgeStoreError::InvalidContract(error) if error.path == "observation.limits"
));
let mut sensitive_observation = observation;
sensitive_observation.text = Some("password".into());
let error = store
.learn_verified(learning_request(
&sensitive_observation,
"sensitive",
"sensitive",
))
.unwrap_err();
assert!(matches!(
error,
KnowledgeStoreError::InvalidContract(error) if error.path == "observation"
));
assert!(store.records().is_empty());
let _ = fs::remove_file(&path);
let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
}
#[test]
fn learning_promotes_after_compatible_uses_and_merges_history() {
let path = test_path();
let mut store = KnowledgeStore::open(&path).unwrap();
let observation = learning_observation();
let first = store
.learn_verified(learning_request(&observation, "learned", "same-workflow"))
.unwrap();
assert!(first.created);
assert!(!first.promoted);
assert_eq!(first.confidence, KnowledgeConfidence::Candidate);
assert_eq!(first.verification_count, 1);
let second = store
.learn_verified(learning_request(&observation, "learned", "same-workflow"))
.unwrap();
assert!(!second.created);
assert!(second.promoted);
assert_eq!(second.confidence, KnowledgeConfidence::Verified);
assert_eq!(second.verification_count, 2);
let learned = store.get("learned").unwrap();
assert_eq!(learned.source.verification_count, 2);
assert_eq!(learned.history.len(), 1);
assert_eq!(learned.history[0].from, KnowledgeConfidence::Candidate);
assert_eq!(learned.history[0].to, KnowledgeConfidence::Verified);
let reopened = KnowledgeStore::open(&path).unwrap();
let persisted = reopened.get("learned").unwrap();
assert_eq!(persisted.source.verification_count, 2);
assert_eq!(persisted.history.len(), 1);
let _ = fs::remove_file(&path);
let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
}
#[test]
fn graph_construction_and_traversal_are_deterministic_and_bounded() {
let path = test_path();
let mut store = KnowledgeStore::open(&path).unwrap();
store
.upsert(record("graph-a", KnowledgeConfidence::Observed, "01"))
.unwrap();
store
.upsert(record("graph-b", KnowledgeConfidence::Observed, "02"))
.unwrap();
let graph = store.graph();
assert_eq!(graph, store.graph());
assert!(graph.nodes.len() <= 256);
assert!(graph.edges.iter().any(|edge| {
edge.from == "record:graph-a"
&& edge.to == "page:documentation"
&& edge.relation == "hasPageKind"
}));
let bounded = store.traverse_graph("record:graph-a", 1, 1).unwrap();
assert_eq!(bounded.node_ids, vec!["record:graph-a"]);
assert!(bounded.truncated);
let repeat = store.traverse_graph("record:graph-a", 1, 1).unwrap();
assert_eq!(bounded, repeat);
assert!(matches!(
store.traverse_graph("record:graph-a", 9, 2),
Err(KnowledgeStoreError::InvalidConfiguration(_))
));
let _ = fs::remove_file(&path);
let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
}
struct CountingEmbeddingProvider<'a> {
calls: &'a AtomicUsize,
}
impl KnowledgeEmbeddingProvider for CountingEmbeddingProvider<'_> {
fn similarity_millis(
&self,
_query: &KnowledgeRetrievalQuery,
_record: &KnowledgeRecord,
) -> Option<u16> {
self.calls.fetch_add(1, Ordering::Relaxed);
Some(777)
}
}
#[test]
fn embeddings_are_disabled_by_default_and_only_used_when_injected() {
let path = test_path();
let mut store = KnowledgeStore::open(&path).unwrap();
store
.upsert(record("embedding", KnowledgeConfidence::Observed, "01"))
.unwrap();
let context = retrieval_context();
let query = KnowledgeRetrievalQuery {
page_kind: Some("documentation".into()),
max_results: 1,
..KnowledgeRetrievalQuery::default()
};
let default_report = store.retrieve(&context, &query);
let no_provider = store.retrieve_with_embeddings(&context, &query, None);
assert_eq!(default_report, no_provider);
assert!(!no_provider.embeddings_used);
let calls = AtomicUsize::new(0);
let provider = CountingEmbeddingProvider { calls: &calls };
let injected = store.retrieve_with_embeddings(&context, &query, Some(&provider));
assert!(injected.embeddings_used);
assert_eq!(calls.load(Ordering::Relaxed), 1);
assert!(injected.candidates[0].signals.iter().any(|signal| {
signal.kind == super::super::knowledge::KnowledgeRetrievalSignalKind::SemanticSimilarity
&& signal.score_millis == Some(777)
}));
let _ = fs::remove_file(&path);
let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
}
#[test]
fn learning_rejects_scope_provenance_mismatch_before_mutation() {
let path = test_path();
let mut store = KnowledgeStore::open(&path).unwrap();
let observation = learning_observation();
let mut build = learning_build("scope-mismatch");
build.scope.origin = "https://other.example".into();
let error = store
.learn_verified(KnowledgeLearningRequest {
observation: &observation,
build,
evidence: learning_evidence(&observation, "scope-mismatch"),
policy: KnowledgeLearningPolicy::default(),
})
.unwrap_err();
assert!(matches!(
error,
KnowledgeStoreError::InvalidContract(error) if error.path == "build.scope.origin"
));
assert!(store.records().is_empty());
let _ = fs::remove_file(&path);
let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
}
}