1use super::knowledge::{
8 KNOWLEDGE_SCHEMA_VERSION, KnowledgeAssessment, KnowledgeConfidence, KnowledgeEmbeddingProvider,
9 KnowledgeGraph, KnowledgeGraphEdge, KnowledgeGraphNode, KnowledgeGraphNodeKind,
10 KnowledgeGraphTraversal, KnowledgeLearningRequest, KnowledgeLearningResult,
11 KnowledgeLookupContext, KnowledgeRecord, KnowledgeRecordKind, KnowledgeRetrievalCandidate,
12 KnowledgeRetrievalQuery, KnowledgeRetrievalReport, KnowledgeScopeSelector,
13 KnowledgeStoreSnapshot, KnowledgeValidationError, MAX_KNOWLEDGE_RECORDS,
14};
15use fs2::FileExt;
16use serde::Serialize;
17use serde_json::Value;
18use sha2::{Digest, Sha256};
19use std::cmp::Ordering;
20use std::collections::{BTreeMap, BTreeSet};
21use std::fs::{self, File, OpenOptions};
22use std::io::{self, Write};
23use std::path::{Path, PathBuf};
24use std::sync::atomic::{AtomicU64, Ordering as AtomicOrdering};
25use url::Url;
26
27pub const DEFAULT_KNOWLEDGE_STORE_BYTES: usize = 4 * 1024 * 1024;
28const STORE_LOCK_SUFFIX: &str = ".lock";
29static TEMP_SEQUENCE: AtomicU64 = AtomicU64::new(1);
30
31pub fn default_knowledge_store_path(profile: &str) -> PathBuf {
33 std::env::var_os("GLASS_CONFIG_HOME")
34 .map(PathBuf::from)
35 .or_else(dirs::config_dir)
36 .unwrap_or_else(|| PathBuf::from("."))
37 .join("glass")
38 .join("knowledge")
39 .join(format!("{profile}.json"))
40}
41
42pub fn default_knowledge_store_path_for_workspace(
45 profile: &str,
46 workspace_id: &str,
47 workspace_generation: Option<u64>,
48) -> PathBuf {
49 let digest = Sha256::digest(
50 format!(
51 "{profile}\u{1f}{workspace_id}\u{1f}{:?}",
52 workspace_generation
53 )
54 .as_bytes(),
55 );
56 std::env::var_os("GLASS_CONFIG_HOME")
57 .map(PathBuf::from)
58 .or_else(dirs::config_dir)
59 .unwrap_or_else(|| PathBuf::from("."))
60 .join("glass")
61 .join(format!("workspace-{digest:x}.json"))
62}
63
64#[derive(Debug, Clone, Copy, PartialEq, Eq)]
66pub struct KnowledgeStoreLimits {
67 pub max_records: usize,
68 pub max_bytes: usize,
69}
70
71impl Default for KnowledgeStoreLimits {
72 fn default() -> Self {
73 Self {
74 max_records: MAX_KNOWLEDGE_RECORDS,
75 max_bytes: DEFAULT_KNOWLEDGE_STORE_BYTES,
76 }
77 }
78}
79
80impl KnowledgeStoreLimits {
81 fn validate(self) -> Result<(), KnowledgeStoreError> {
82 if self.max_records == 0 || self.max_records > MAX_KNOWLEDGE_RECORDS {
83 return Err(KnowledgeStoreError::InvalidConfiguration(format!(
84 "maxRecords must be between 1 and {MAX_KNOWLEDGE_RECORDS}"
85 )));
86 }
87 if self.max_bytes == 0 {
88 return Err(KnowledgeStoreError::InvalidConfiguration(
89 "maxBytes must be positive".into(),
90 ));
91 }
92 Ok(())
93 }
94}
95
96#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
98#[serde(rename_all = "camelCase")]
99pub struct KnowledgeStoreChange {
100 pub record_id: String,
101 pub retained: bool,
102 pub removed: bool,
103 pub pruned_record_ids: Vec<String>,
104}
105
106#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
108#[serde(rename_all = "camelCase")]
109pub struct KnowledgeStoreStats {
110 pub record_count: usize,
111 pub serialized_bytes: usize,
112 pub candidate_count: usize,
113 pub observed_count: usize,
114 pub verified_count: usize,
115 pub stale_count: usize,
116 pub contradicted_count: usize,
117 pub quarantined_count: usize,
118}
119
120#[derive(Debug)]
122pub struct KnowledgeStore {
123 path: PathBuf,
124 limits: KnowledgeStoreLimits,
125 snapshot: KnowledgeStoreSnapshot,
126 last_pruned: Option<Vec<String>>,
127}
128
129impl KnowledgeStore {
130 pub fn open(path: impl Into<PathBuf>) -> Result<Self, KnowledgeStoreError> {
132 Self::open_with_limits(path, KnowledgeStoreLimits::default())
133 }
134
135 pub fn open_with_limits(
137 path: impl Into<PathBuf>,
138 limits: KnowledgeStoreLimits,
139 ) -> Result<Self, KnowledgeStoreError> {
140 limits.validate()?;
141 let path = path.into();
142 let snapshot = read_snapshot(&path)?;
143 validate_snapshot_size(&snapshot, limits.max_bytes)?;
144 Ok(Self {
145 path,
146 limits,
147 snapshot,
148 last_pruned: None,
149 })
150 }
151
152 pub fn path(&self) -> &Path {
154 &self.path
155 }
156
157 pub fn limits(&self) -> KnowledgeStoreLimits {
159 self.limits
160 }
161
162 pub fn snapshot(&self) -> &KnowledgeStoreSnapshot {
164 &self.snapshot
165 }
166
167 pub fn refresh(&mut self) -> Result<(), KnowledgeStoreError> {
169 let _lock = StoreLock::acquire(&self.path)?;
170 let snapshot = read_snapshot(&self.path)?;
171 validate_snapshot_size(&snapshot, self.limits.max_bytes)?;
172 self.snapshot = snapshot;
173 self.last_pruned = None;
174 Ok(())
175 }
176
177 pub fn get(&self, record_id: &str) -> Option<&KnowledgeRecord> {
179 self.snapshot
180 .records
181 .iter()
182 .find(|record| record.record_id == record_id)
183 }
184
185 pub fn assess(&self, context: &KnowledgeLookupContext) -> Vec<KnowledgeAssessment> {
188 self.snapshot
189 .records
190 .iter()
191 .map(|record| record.assess(context))
192 .collect()
193 }
194
195 pub fn retrieve(
198 &self,
199 context: &KnowledgeLookupContext,
200 query: &KnowledgeRetrievalQuery,
201 ) -> KnowledgeRetrievalReport {
202 if !query.is_bounded() {
203 return KnowledgeRetrievalReport {
204 embeddings_used: false,
205 ..KnowledgeRetrievalReport::default()
206 };
207 }
208 let limit = query.max_results.clamp(1, 16);
209 let mut candidates = self
210 .snapshot
211 .records
212 .iter()
213 .map(|record| record.retrieve_candidate(context, query))
214 .collect::<Vec<_>>();
215 candidates.sort_by(|left, right| {
216 let left_score = retrieval_score(left);
217 let right_score = retrieval_score(right);
218 right_score
219 .cmp(&left_score)
220 .then_with(|| left.record_id.cmp(&right.record_id))
221 });
222 let mut selected_record_ids = Vec::new();
223 for candidate in candidates
224 .iter_mut()
225 .filter(|candidate| candidate.rejection.is_none())
226 {
227 if selected_record_ids.len() >= limit {
228 break;
229 }
230 candidate.selected = true;
231 selected_record_ids.push(candidate.record_id.clone());
232 }
233 let rejected_record_ids = candidates
234 .iter()
235 .filter(|candidate| candidate.rejection.is_some())
236 .map(|candidate| candidate.record_id.clone())
237 .collect();
238 KnowledgeRetrievalReport {
239 candidates,
240 selected_record_ids,
241 rejected_record_ids,
242 embeddings_used: false,
243 }
244 }
245
246 pub fn retrieve_with_embeddings(
250 &self,
251 context: &KnowledgeLookupContext,
252 query: &KnowledgeRetrievalQuery,
253 provider: Option<&dyn KnowledgeEmbeddingProvider>,
254 ) -> KnowledgeRetrievalReport {
255 let mut report = self.retrieve(context, query);
256 let Some(provider) = provider else {
257 return report;
258 };
259 report.embeddings_used = true;
260 for candidate in &mut report.candidates {
261 if let Some(record) = self.get(&candidate.record_id)
262 && let Some(score_millis) = provider.similarity_millis(query, record)
263 {
264 candidate
265 .signals
266 .push(super::knowledge::KnowledgeRetrievalSignal {
267 kind: super::knowledge::KnowledgeRetrievalSignalKind::SemanticSimilarity,
268 detail: "optional embedding provider supplied a bounded similarity score"
269 .into(),
270 score_millis: Some(score_millis),
271 });
272 }
273 }
274 report
275 }
276
277 pub fn records(&self) -> &[KnowledgeRecord] {
279 &self.snapshot.records
280 }
281
282 pub fn export_scoped(
288 &self,
289 selector: &KnowledgeScopeSelector,
290 ) -> Result<KnowledgeStoreSnapshot, KnowledgeStoreError> {
291 selector.validate()?;
292 let snapshot = KnowledgeStoreSnapshot {
293 schema_version: self.snapshot.schema_version,
294 records: self
295 .snapshot
296 .records
297 .iter()
298 .filter(|record| selector.matches(&record.scope))
299 .cloned()
300 .collect(),
301 };
302 snapshot.validate()?;
303 Ok(snapshot)
304 }
305
306 pub fn remove_scoped(
308 &mut self,
309 record_id: &str,
310 selector: &KnowledgeScopeSelector,
311 ) -> Result<KnowledgeStoreChange, KnowledgeStoreError> {
312 selector.validate()?;
313 let record_id = record_id.to_owned();
314 self.mutate(|snapshot| {
315 let record = snapshot
316 .records
317 .iter()
318 .find(|record| record.record_id == record_id)
319 .ok_or_else(|| KnowledgeStoreError::NotFound(record_id.clone()))?;
320 if !selector.matches(&record.scope) {
321 return Err(KnowledgeStoreError::ScopeMismatch(record_id.clone()));
322 }
323 snapshot
324 .records
325 .retain(|record| record.record_id != record_id);
326 Ok(())
327 })?;
328 Ok(KnowledgeStoreChange {
329 record_id,
330 retained: false,
331 removed: true,
332 pruned_record_ids: self.last_pruned.take().unwrap_or_default(),
333 })
334 }
335
336 pub fn purge_scoped(
338 &mut self,
339 selector: &KnowledgeScopeSelector,
340 ) -> Result<KnowledgePurgeResult, KnowledgeStoreError> {
341 selector.validate()?;
342 let mut removed_record_ids = Vec::new();
343 self.mutate(|snapshot| {
344 snapshot.records.retain(|record| {
345 if selector.matches(&record.scope) {
346 removed_record_ids.push(record.record_id.clone());
347 false
348 } else {
349 true
350 }
351 });
352 Ok(())
353 })?;
354 Ok(KnowledgePurgeResult {
355 removed_record_ids,
356 pruned_record_ids: self.last_pruned.take().unwrap_or_default(),
357 })
358 }
359
360 pub fn prune_scoped(
362 &mut self,
363 selector: &KnowledgeScopeSelector,
364 ) -> Result<KnowledgePurgeResult, KnowledgeStoreError> {
365 selector.validate()?;
366 let mut removed_record_ids = Vec::new();
367 self.mutate(|snapshot| {
368 snapshot.records.retain(|record| {
369 let removable = selector.matches(&record.scope)
370 && matches!(
371 record.confidence,
372 KnowledgeConfidence::Stale
373 | KnowledgeConfidence::Contradicted
374 | KnowledgeConfidence::Quarantined
375 );
376 if removable {
377 removed_record_ids.push(record.record_id.clone());
378 }
379 !removable
380 });
381 Ok(())
382 })?;
383 Ok(KnowledgePurgeResult {
384 removed_record_ids,
385 pruned_record_ids: self.last_pruned.take().unwrap_or_default(),
386 })
387 }
388
389 pub fn stats(&self) -> Result<KnowledgeStoreStats, KnowledgeStoreError> {
391 let mut stats = KnowledgeStoreStats {
392 record_count: self.snapshot.records.len(),
393 serialized_bytes: serialized_size(&self.snapshot)?,
394 candidate_count: 0,
395 observed_count: 0,
396 verified_count: 0,
397 stale_count: 0,
398 contradicted_count: 0,
399 quarantined_count: 0,
400 };
401 for record in &self.snapshot.records {
402 match record.confidence {
403 KnowledgeConfidence::Candidate => stats.candidate_count += 1,
404 KnowledgeConfidence::Observed => stats.observed_count += 1,
405 KnowledgeConfidence::Verified => stats.verified_count += 1,
406 KnowledgeConfidence::Stale => stats.stale_count += 1,
407 KnowledgeConfidence::Contradicted => stats.contradicted_count += 1,
408 KnowledgeConfidence::Quarantined => stats.quarantined_count += 1,
409 }
410 }
411 Ok(stats)
412 }
413
414 pub fn replace_snapshot(
416 &mut self,
417 snapshot: KnowledgeStoreSnapshot,
418 ) -> Result<(), KnowledgeStoreError> {
419 snapshot
420 .validate()
421 .map_err(KnowledgeStoreError::InvalidContract)?;
422 if snapshot.records.len() > self.limits.max_records {
423 return Err(KnowledgeStoreError::Capacity(
424 "snapshot exceeds the configured record limit".into(),
425 ));
426 }
427 validate_snapshot_size(&snapshot, self.limits.max_bytes)?;
428 let _lock = StoreLock::acquire(&self.path)?;
429 write_snapshot(&self.path, &snapshot, self.limits.max_bytes)?;
430 self.snapshot = snapshot;
431 self.last_pruned = None;
432 Ok(())
433 }
434
435 pub fn transition(
437 &mut self,
438 record_id: &str,
439 next: KnowledgeConfidence,
440 reason: String,
441 observed_at: String,
442 fresh_verification: bool,
443 ) -> Result<KnowledgeStoreChange, KnowledgeStoreError> {
444 let record_id = record_id.to_owned();
445 self.mutate(|snapshot| {
446 let record = snapshot
447 .records
448 .iter_mut()
449 .find(|record| record.record_id == record_id)
450 .ok_or_else(|| KnowledgeStoreError::NotFound(record_id.clone()))?;
451 record.transition(next, reason, observed_at, fresh_verification)?;
452 Ok(())
453 })?;
454 Ok(KnowledgeStoreChange {
455 retained: true,
456 removed: false,
457 record_id,
458 pruned_record_ids: self.last_pruned.take().unwrap_or_default(),
459 })
460 }
461
462 pub fn purge_origin(
464 &mut self,
465 origin: &str,
466 ) -> Result<KnowledgePurgeResult, KnowledgeStoreError> {
467 let mut removed_record_ids = Vec::new();
468 self.mutate(|snapshot| {
469 snapshot.records.retain(|record| {
470 if record.scope.origin == origin {
471 removed_record_ids.push(record.record_id.clone());
472 false
473 } else {
474 true
475 }
476 });
477 Ok(())
478 })?;
479 Ok(KnowledgePurgeResult {
480 removed_record_ids,
481 pruned_record_ids: self.last_pruned.take().unwrap_or_default(),
482 })
483 }
484
485 pub fn upsert(
487 &mut self,
488 record: KnowledgeRecord,
489 ) -> Result<KnowledgeStoreChange, KnowledgeStoreError> {
490 record.validate()?;
491 if record.to_canonical_json()?.len() > self.limits.max_bytes {
492 return Err(KnowledgeStoreError::Capacity(
493 "record exceeds the configured store byte limit".into(),
494 ));
495 }
496 let record_id = record.record_id.clone();
497 self.mutate(|snapshot| {
498 if let Some(existing) = snapshot
499 .records
500 .iter_mut()
501 .find(|existing| existing.record_id == record_id)
502 {
503 *existing = record;
504 } else {
505 snapshot.records.push(record);
506 }
507 Ok(())
508 })?;
509 let retained = self.get(&record_id).is_some();
510 if !retained {
511 return Err(KnowledgeStoreError::Capacity(
512 "record was pruned by the configured store limits".into(),
513 ));
514 }
515 Ok(KnowledgeStoreChange {
516 record_id,
517 retained,
518 removed: false,
519 pruned_record_ids: self.last_pruned.take().unwrap_or_default(),
520 })
521 }
522
523 pub fn remove(&mut self, record_id: &str) -> Result<KnowledgeStoreChange, KnowledgeStoreError> {
525 let record_id = record_id.to_owned();
526 let existed = self.mutate(|snapshot| {
527 let before = snapshot.records.len();
528 snapshot
529 .records
530 .retain(|record| record.record_id != record_id);
531 Ok(before != snapshot.records.len())
532 })?;
533 Ok(KnowledgeStoreChange {
534 record_id,
535 retained: false,
536 removed: existed,
537 pruned_record_ids: if existed {
538 self.last_pruned.take().unwrap_or_default()
539 } else {
540 Vec::new()
541 },
542 })
543 }
544
545 pub fn learn_verified(
548 &mut self,
549 request: KnowledgeLearningRequest<'_>,
550 ) -> Result<KnowledgeLearningResult, KnowledgeStoreError> {
551 request.policy.validate()?;
552 request.observation.validate().map_err(|error| {
553 KnowledgeStoreError::InvalidContract(KnowledgeValidationError::new(
554 "observation",
555 error.to_string(),
556 ))
557 })?;
558 request.evidence.validate_against(request.observation)?;
559 let route_url = Url::parse(&request.observation.route.url).map_err(|error| {
560 KnowledgeStoreError::InvalidContract(KnowledgeValidationError::new(
561 "observation.route.url",
562 format!("invalid URL: {error}"),
563 ))
564 })?;
565 let route_origin = route_url.origin().ascii_serialization();
566 let route_path = if route_url.path().is_empty() {
567 "/"
568 } else {
569 route_url.path()
570 };
571 let scope = &request.build.scope;
572 let path_matches = scope.path_pattern == route_path
573 || scope
574 .path_pattern
575 .strip_suffix('*')
576 .is_some_and(|prefix| route_path.starts_with(prefix));
577 if scope.origin != route_origin {
578 return Err(KnowledgeStoreError::InvalidContract(
579 KnowledgeValidationError::new(
580 "build.scope.origin",
581 "learning scope origin must match the fresh observation route",
582 ),
583 ));
584 }
585 if !path_matches {
586 return Err(KnowledgeStoreError::InvalidContract(
587 KnowledgeValidationError::new(
588 "build.scope.pathPattern",
589 "learning scope path pattern must match the fresh observation route",
590 ),
591 ));
592 }
593 let mut build = request.build.clone();
594 if build.record_id.is_empty() {
595 build.record_id =
596 KnowledgeRecord::deterministic_page_family_id(request.observation, &build.scope)?;
597 }
598 let incoming = KnowledgeRecord::from_verified_observation(
599 request.observation,
600 build,
601 &request.evidence,
602 )?;
603 let record_id = incoming.record_id.clone();
604 let compatibility_key = request.evidence.compatibility_key.clone();
605 let mut result = KnowledgeLearningResult {
606 record_id: record_id.clone(),
607 confidence: incoming.confidence,
608 verification_count: incoming.source.verification_count,
609 promoted: false,
610 created: false,
611 };
612 self.mutate(|snapshot| {
613 if let Some(existing) = snapshot
614 .records
615 .iter_mut()
616 .find(|record| record.record_id == record_id)
617 {
618 let existing_key = existing
619 .data
620 .get("verifiedUseKey")
621 .and_then(Value::as_str)
622 .unwrap_or_default();
623 if existing_key != compatibility_key {
624 return Err(KnowledgeStoreError::InvalidContract(
625 KnowledgeValidationError::new(
626 "compatibilityKey",
627 "verified workflow evidence is incompatible with the stored record",
628 ),
629 ));
630 }
631 let next_count = existing.source.verification_count.saturating_add(1);
632 let next = if next_count >= request.policy.required_verified_uses {
633 KnowledgeConfidence::Verified
634 } else {
635 KnowledgeConfidence::Candidate
636 };
637 existing.transition_with_validation(
638 next,
639 if next == KnowledgeConfidence::Verified {
640 "repeated compatible guarded workflow use promoted record"
641 } else {
642 "compatible guarded workflow use refreshed candidate"
643 }
644 .into(),
645 request.evidence.observed_at.clone(),
646 request.evidence.guarded_revision,
647 request.evidence.evidence_quality,
648 )?;
649 existing.data["verifiedUseKey"] = Value::String(compatibility_key.clone());
650 result.confidence = existing.confidence;
651 result.verification_count = existing.source.verification_count;
652 result.promoted = existing.confidence == KnowledgeConfidence::Verified;
653 } else {
654 let mut created = incoming.clone();
655 if request.policy.required_verified_uses <= 1 {
656 created.source.verification_count = 0;
657 created.transition_with_validation(
658 KnowledgeConfidence::Verified,
659 "single configured guarded workflow use promoted record".into(),
660 request.evidence.observed_at.clone(),
661 request.evidence.guarded_revision,
662 request.evidence.evidence_quality,
663 )?;
664 result.promoted = true;
665 }
666 result.confidence = created.confidence;
667 result.verification_count = created.source.verification_count;
668 snapshot.records.push(created);
669 result.created = true;
670 }
671 Ok(())
672 })?;
673 Ok(result)
674 }
675
676 pub fn contradict(
678 &mut self,
679 record_id: &str,
680 reason: String,
681 observed_at: String,
682 current_revision: u64,
683 evidence_quality: super::knowledge::KnowledgeEvidenceQuality,
684 ) -> Result<KnowledgeStoreChange, KnowledgeStoreError> {
685 let id = record_id.to_owned();
686 self.mutate(|snapshot| {
687 let record = snapshot
688 .records
689 .iter_mut()
690 .find(|record| record.record_id == id)
691 .ok_or_else(|| KnowledgeStoreError::NotFound(id.clone()))?;
692 record.transition_with_validation(
693 KnowledgeConfidence::Contradicted,
694 reason,
695 observed_at,
696 current_revision,
697 evidence_quality,
698 )?;
699 Ok(())
700 })?;
701 Ok(KnowledgeStoreChange {
702 record_id: id,
703 retained: true,
704 removed: false,
705 pruned_record_ids: self.last_pruned.take().unwrap_or_default(),
706 })
707 }
708
709 pub fn graph(&self) -> KnowledgeGraph {
711 let mut nodes = BTreeMap::new();
712 let mut edges = Vec::new();
713 for record in &self.snapshot.records {
714 let record_node = format!("record:{}", record.record_id);
715 nodes.insert(
716 record_node.clone(),
717 KnowledgeGraphNode {
718 id: record_node.clone(),
719 kind: KnowledgeGraphNodeKind::Record,
720 },
721 );
722 if let Some(page_kind) = record.data.get("pageKind").and_then(Value::as_str) {
723 let id = format!("page:{}", page_kind.to_ascii_lowercase());
724 nodes.entry(id.clone()).or_insert(KnowledgeGraphNode {
725 id: id.clone(),
726 kind: KnowledgeGraphNodeKind::PageKind,
727 });
728 edges.push(KnowledgeGraphEdge {
729 from: record_node.clone(),
730 to: id,
731 relation: "hasPageKind".into(),
732 });
733 }
734 for landmark in &record.invalidation.required_landmarks {
735 let id = format!("landmark:{}", landmark.to_ascii_lowercase());
736 nodes.entry(id.clone()).or_insert(KnowledgeGraphNode {
737 id: id.clone(),
738 kind: KnowledgeGraphNodeKind::Landmark,
739 });
740 edges.push(KnowledgeGraphEdge {
741 from: record_node.clone(),
742 to: id,
743 relation: "requiresLandmark".into(),
744 });
745 }
746 if record.kind == KnowledgeRecordKind::WorkflowEntryPoint {
747 let id = format!("workflow:{}", record.record_id);
748 nodes.entry(id.clone()).or_insert(KnowledgeGraphNode {
749 id: id.clone(),
750 kind: KnowledgeGraphNodeKind::Workflow,
751 });
752 edges.push(KnowledgeGraphEdge {
753 from: record_node,
754 to: id,
755 relation: "workflowEntry".into(),
756 });
757 }
758 }
759 edges.sort_by(|left, right| {
760 (&left.from, &left.to, &left.relation).cmp(&(&right.from, &right.to, &right.relation))
761 });
762 KnowledgeGraph {
763 nodes: nodes.into_values().collect(),
764 edges,
765 }
766 }
767
768 pub fn traverse_graph(
770 &self,
771 start: &str,
772 max_depth: usize,
773 max_nodes: usize,
774 ) -> Result<KnowledgeGraphTraversal, KnowledgeStoreError> {
775 if max_depth > 8 || max_nodes == 0 || max_nodes > 256 {
776 return Err(KnowledgeStoreError::InvalidConfiguration(
777 "graph traversal bounds exceed the local contract".into(),
778 ));
779 }
780 let graph = self.graph();
781 if !graph.nodes.iter().any(|node| node.id == start) {
782 return Err(KnowledgeStoreError::NotFound(start.into()));
783 }
784 let mut frontier = vec![(start.to_owned(), 0usize)];
785
786 let mut visited = BTreeSet::from([start.to_owned()]);
787 let mut edges = Vec::new();
788 let mut truncated = false;
789 while let Some((current, depth)) = frontier.pop() {
790 if depth >= max_depth {
791 continue;
792 }
793 for edge in graph.edges.iter().filter(|edge| edge.from == current) {
794 if visited.len() >= max_nodes && !visited.contains(&edge.to) {
795 truncated = true;
796 continue;
797 }
798 edges.push(edge.clone());
799 if visited.insert(edge.to.clone()) {
800 frontier.push((edge.to.clone(), depth + 1));
801 }
802 }
803 }
804 Ok(KnowledgeGraphTraversal {
805 start: start.into(),
806 max_depth,
807 node_ids: visited.into_iter().collect(),
808 edges,
809 truncated,
810 })
811 }
812
813 pub fn supersede(
816 &mut self,
817 old_record_id: &str,
818 new_record_id: &str,
819 observed_at: String,
820 current_revision: u64,
821 evidence_quality: super::knowledge::KnowledgeEvidenceQuality,
822 ) -> Result<KnowledgeStoreChange, KnowledgeStoreError> {
823 if self.get(new_record_id).is_none() {
824 return Err(KnowledgeStoreError::NotFound(new_record_id.into()));
825 }
826 self.contradict(
827 old_record_id,
828 format!("record superseded by {new_record_id}"),
829 observed_at,
830 current_revision,
831 evidence_quality,
832 )
833 }
834}
835
836impl KnowledgeStore {
837 fn mutate<T, F>(&mut self, operation: F) -> Result<T, KnowledgeStoreError>
838 where
839 F: FnOnce(&mut KnowledgeStoreSnapshot) -> Result<T, KnowledgeStoreError>,
840 {
841 let _lock = StoreLock::acquire(&self.path)?;
842 let mut snapshot = read_snapshot(&self.path)?;
843 let result = operation(&mut snapshot)?;
844 let pruned = prune_snapshot(&mut snapshot, self.limits)?;
845 write_snapshot(&self.path, &snapshot, self.limits.max_bytes)?;
846 self.snapshot = snapshot;
847 self.last_pruned = Some(pruned);
848 Ok(result)
849 }
850}
851
852fn read_snapshot(path: &Path) -> Result<KnowledgeStoreSnapshot, KnowledgeStoreError> {
853 let bytes = match fs::read(path) {
854 Ok(bytes) => bytes,
855 Err(error) if error.kind() == io::ErrorKind::NotFound => {
856 return Ok(KnowledgeStoreSnapshot {
857 schema_version: KNOWLEDGE_SCHEMA_VERSION,
858 records: Vec::new(),
859 });
860 }
861 Err(error) => return Err(KnowledgeStoreError::Io(error)),
862 };
863 let snapshot = serde_json::from_slice::<KnowledgeStoreSnapshot>(&bytes)
864 .map_err(|error| KnowledgeStoreError::Corrupt(format!("invalid JSON snapshot: {error}")))?;
865 snapshot
866 .validate()
867 .map_err(KnowledgeStoreError::InvalidContract)?;
868 Ok(snapshot)
869}
870
871fn write_snapshot(
872 path: &Path,
873 snapshot: &KnowledgeStoreSnapshot,
874 max_bytes: usize,
875) -> Result<(), KnowledgeStoreError> {
876 let canonical = snapshot
877 .to_canonical_json()
878 .map_err(KnowledgeStoreError::InvalidContract)?;
879 if canonical.len() > max_bytes {
880 return Err(KnowledgeStoreError::Capacity(
881 "snapshot exceeds the configured store byte limit".into(),
882 ));
883 }
884 let parent = parent_dir(path);
885 fs::create_dir_all(parent).map_err(KnowledgeStoreError::Io)?;
886 let file_name = path
887 .file_name()
888 .and_then(|name| name.to_str())
889 .ok_or_else(|| {
890 KnowledgeStoreError::InvalidConfiguration("store path has no filename".into())
891 })?;
892 let sequence = TEMP_SEQUENCE.fetch_add(1, AtomicOrdering::Relaxed);
893 let temporary = parent.join(format!(
894 ".{file_name}.{}.{}.tmp",
895 std::process::id(),
896 sequence
897 ));
898 let result = (|| {
899 let mut file = OpenOptions::new()
900 .write(true)
901 .create_new(true)
902 .open(&temporary)
903 .map_err(KnowledgeStoreError::Io)?;
904 file.write_all(canonical.as_bytes())
905 .map_err(KnowledgeStoreError::Io)?;
906 file.sync_all().map_err(KnowledgeStoreError::Io)?;
907 fs::rename(&temporary, path).map_err(KnowledgeStoreError::Io)?;
908 #[cfg(unix)]
909 File::open(parent)
910 .and_then(|directory| directory.sync_all())
911 .map_err(KnowledgeStoreError::Io)?;
912 Ok(())
913 })();
914 if result.is_err() {
915 let _ = fs::remove_file(&temporary);
916 }
917 result
918}
919
920fn validate_snapshot_size(
921 snapshot: &KnowledgeStoreSnapshot,
922 max_bytes: usize,
923) -> Result<(), KnowledgeStoreError> {
924 let bytes = snapshot
925 .to_canonical_json()
926 .map_err(KnowledgeStoreError::InvalidContract)?
927 .len();
928 if bytes > max_bytes {
929 return Err(KnowledgeStoreError::Capacity(format!(
930 "snapshot is {bytes} bytes, exceeding the {max_bytes}-byte limit"
931 )));
932 }
933 Ok(())
934}
935
936fn prune_snapshot(
937 snapshot: &mut KnowledgeStoreSnapshot,
938 limits: KnowledgeStoreLimits,
939) -> Result<Vec<String>, KnowledgeStoreError> {
940 let mut pruned = Vec::new();
941 while snapshot.records.len() > limits.max_records
942 || serialized_size(snapshot)? > limits.max_bytes
943 {
944 let Some(index) = snapshot
945 .records
946 .iter()
947 .enumerate()
948 .min_by(|(_, left), (_, right)| prune_order(left, right))
949 .map(|(index, _)| index)
950 else {
951 break;
952 };
953 pruned.push(snapshot.records.remove(index).record_id);
954 }
955 if serialized_size(snapshot)? > limits.max_bytes {
956 return Err(KnowledgeStoreError::Capacity(
957 "cannot fit the snapshot within the configured byte limit".into(),
958 ));
959 }
960 Ok(pruned)
961}
962
963fn serialized_size(snapshot: &KnowledgeStoreSnapshot) -> Result<usize, KnowledgeStoreError> {
964 snapshot
965 .to_canonical_json()
966 .map(|json| json.len())
967 .map_err(KnowledgeStoreError::InvalidContract)
968}
969
970fn prune_order(left: &KnowledgeRecord, right: &KnowledgeRecord) -> Ordering {
971 confidence_rank(left.confidence)
972 .cmp(&confidence_rank(right.confidence))
973 .then_with(|| {
974 left.source
975 .last_verified_at
976 .cmp(&right.source.last_verified_at)
977 })
978 .then_with(|| left.record_id.cmp(&right.record_id))
979}
980
981fn confidence_rank(confidence: KnowledgeConfidence) -> u8 {
982 match confidence {
983 KnowledgeConfidence::Quarantined => 0,
984 KnowledgeConfidence::Contradicted => 1,
985 KnowledgeConfidence::Stale => 2,
986 KnowledgeConfidence::Candidate => 3,
987 KnowledgeConfidence::Observed => 4,
988 KnowledgeConfidence::Verified => 5,
989 }
990}
991fn retrieval_score(candidate: &KnowledgeRetrievalCandidate) -> u16 {
992 candidate
993 .signals
994 .iter()
995 .filter_map(|signal| signal.score_millis)
996 .max()
997 .unwrap_or_default()
998}
999
1000struct StoreLock {
1001 file: File,
1002}
1003
1004impl StoreLock {
1005 fn acquire(path: &Path) -> Result<Self, KnowledgeStoreError> {
1006 let lock_path = PathBuf::from(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
1007 fs::create_dir_all(parent_dir(&lock_path)).map_err(KnowledgeStoreError::Io)?;
1008 let file = OpenOptions::new()
1009 .create(true)
1010 .truncate(false)
1011 .read(true)
1012 .write(true)
1013 .open(lock_path)
1014 .map_err(KnowledgeStoreError::Io)?;
1015 file.lock_exclusive().map_err(KnowledgeStoreError::Io)?;
1016 Ok(Self { file })
1017 }
1018}
1019
1020fn parent_dir(path: &Path) -> &Path {
1021 path.parent()
1022 .filter(|parent| !parent.as_os_str().is_empty())
1023 .unwrap_or_else(|| Path::new("."))
1024}
1025
1026impl Drop for StoreLock {
1027 fn drop(&mut self) {
1028 let _ = FileExt::unlock(&self.file);
1029 }
1030}
1031
1032#[derive(Debug)]
1034pub enum KnowledgeStoreError {
1035 Io(io::Error),
1036 Corrupt(String),
1037 InvalidContract(KnowledgeValidationError),
1038 InvalidConfiguration(String),
1039 Capacity(String),
1040 NotFound(String),
1041 ScopeMismatch(String),
1042}
1043
1044impl std::fmt::Display for KnowledgeStoreError {
1045 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1046 match self {
1047 Self::Io(error) => write!(formatter, "knowledge store I/O error: {error}"),
1048 Self::Corrupt(reason) => write!(formatter, "knowledge store is corrupt: {reason}"),
1049 Self::InvalidContract(error) => write!(formatter, "knowledge contract: {error}"),
1050 Self::InvalidConfiguration(reason) => {
1051 write!(formatter, "invalid knowledge store configuration: {reason}")
1052 }
1053 Self::Capacity(reason) => write!(formatter, "knowledge store capacity: {reason}"),
1054 Self::NotFound(record_id) => {
1055 write!(formatter, "knowledge record not found: {record_id}")
1056 }
1057 Self::ScopeMismatch(record_id) => {
1058 write!(
1059 formatter,
1060 "knowledge record is outside the requested scope: {record_id}"
1061 )
1062 }
1063 }
1064 }
1065}
1066
1067#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
1069#[serde(rename_all = "camelCase")]
1070pub struct KnowledgePurgeResult {
1071 pub removed_record_ids: Vec<String>,
1072 pub pruned_record_ids: Vec<String>,
1073}
1074
1075impl std::error::Error for KnowledgeStoreError {}
1076
1077impl From<KnowledgeValidationError> for KnowledgeStoreError {
1078 fn from(error: KnowledgeValidationError) -> Self {
1079 Self::InvalidContract(error)
1080 }
1081}
1082
1083#[cfg(test)]
1084mod tests {
1085 use super::super::knowledge::{
1086 KnowledgeBackendCapability, KnowledgeBackendKind, KnowledgeBackendProvenance,
1087 KnowledgeCurrentValidation, KnowledgeEmbeddingProvider, KnowledgeEvidenceQuality,
1088 KnowledgeMemoryInfluence, KnowledgePortability, KnowledgeRejectionReason,
1089 KnowledgeRetrievalExplanation, KnowledgeSurfaceCoverage, KnowledgeSurfaceKind,
1090 KnowledgeSurfaceProvenance, KnowledgeUnderstandingLevel,
1091 };
1092 use super::*;
1093 use crate::browser::session::{
1094 KnowledgeInvalidation, KnowledgeLearningPolicy, KnowledgeLearningRequest,
1095 KnowledgeLookupContext, KnowledgeProfileScope, KnowledgeRecordBuildOptions,
1096 KnowledgeRecordKind, KnowledgeScope, KnowledgeScopeSelector, KnowledgeSource,
1097 KnowledgeVerifiedWorkflowEvidence, SemanticObservation,
1098 };
1099 use serde_json::json;
1100 use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
1101
1102 static TEST_SEQUENCE: AtomicU64 = AtomicU64::new(1);
1103
1104 fn test_path() -> PathBuf {
1105 std::env::temp_dir().join(format!(
1106 "glass-knowledge-store-{}-{}",
1107 std::process::id(),
1108 TEST_SEQUENCE.fetch_add(1, Ordering::Relaxed)
1109 ))
1110 }
1111
1112 fn record(id: &str, confidence: KnowledgeConfidence, verified_at: &str) -> KnowledgeRecord {
1113 KnowledgeRecord {
1114 schema_version: KNOWLEDGE_SCHEMA_VERSION,
1115 record_id: id.into(),
1116 kind: KnowledgeRecordKind::PageFamily,
1117 scope: KnowledgeScope {
1118 origin: "https://example.test".into(),
1119 path_pattern: "/docs/*".into(),
1120 profile_scope: KnowledgeProfileScope::Anonymous,
1121 profile_key: None,
1122 locale: None,
1123 tenant_key: None,
1124 browser_family: "chromium".into(),
1125 browser_version_range: None,
1126 glass_schema_version: 1,
1127 policy_preset: "balanced".into(),
1128 workspace_id: None,
1129 workspace_generation: None,
1130 },
1131 source: KnowledgeSource {
1132 first_seen_at: format!("2026-07-27T00:00:{verified_at:0>2}Z"),
1133 last_verified_at: format!("2026-07-27T00:00:{verified_at:0>2}Z"),
1134 glass_version: "0.2.0".into(),
1135 verification_count: 1,
1136 surface: KnowledgeSurfaceProvenance {
1137 kind: KnowledgeSurfaceKind::Document,
1138 understanding: KnowledgeUnderstandingLevel::Strong,
1139 coverage: KnowledgeSurfaceCoverage::Semantic,
1140 extension_id: None,
1141 },
1142 backend: KnowledgeBackendProvenance {
1143 backend: KnowledgeBackendKind::Cdp,
1144 profile: "production".into(),
1145 capabilities: vec![
1146 KnowledgeBackendCapability::SemanticExtraction,
1147 KnowledgeBackendCapability::Verification,
1148 ],
1149 },
1150 },
1151 confidence,
1152 invalidation: KnowledgeInvalidation::default(),
1153 data: json!({"pageKind": "documentation"}),
1154 portability: KnowledgePortability::SurfacePortable,
1155 memory_influence: KnowledgeMemoryInfluence::None,
1156 retrieval: KnowledgeRetrievalExplanation {
1157 signals: Vec::new(),
1158 current_validation: KnowledgeCurrentValidation {
1159 status: super::super::knowledge::KnowledgeCurrentValidationStatus::Validated,
1160 evidence_quality: KnowledgeEvidenceQuality::Strong,
1161 current_revision: Some(1),
1162 validated_at: Some("2026-07-27T00:00:00Z".into()),
1163 },
1164 },
1165 history: Vec::new(),
1166 }
1167 }
1168
1169 #[test]
1170 fn upsert_reopens_from_an_atomic_snapshot() {
1171 let path = test_path();
1172 let mut store = KnowledgeStore::open(&path).unwrap();
1173 store
1174 .upsert(record("knowledge_1", KnowledgeConfidence::Verified, "2"))
1175 .unwrap();
1176 let reopened = KnowledgeStore::open(&path).unwrap();
1177 assert!(reopened.get("knowledge_1").is_some());
1178 assert_eq!(reopened.snapshot().records.len(), 1);
1179 let _ = fs::remove_file(&path);
1180 let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
1181 }
1182
1183 #[test]
1184 fn pruning_prefers_low_confidence_and_old_records() {
1185 let path = test_path();
1186 let limits = KnowledgeStoreLimits {
1187 max_records: 2,
1188 max_bytes: DEFAULT_KNOWLEDGE_STORE_BYTES,
1189 };
1190 let mut store = KnowledgeStore::open_with_limits(&path, limits).unwrap();
1191 store
1192 .upsert(record("verified", KnowledgeConfidence::Verified, "1"))
1193 .unwrap();
1194 store
1195 .upsert(record("stale", KnowledgeConfidence::Stale, "3"))
1196 .unwrap();
1197 let change = store
1198 .upsert(record("observed", KnowledgeConfidence::Observed, "2"))
1199 .unwrap();
1200 assert_eq!(change.pruned_record_ids, vec!["stale"]);
1201 assert!(store.get("verified").is_some());
1202 assert!(store.get("observed").is_some());
1203 let _ = fs::remove_file(&path);
1204 let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
1205 }
1206
1207 #[test]
1208 fn malformed_snapshot_is_not_silently_replaced() {
1209 let path = test_path();
1210 fs::write(&path, b"not-json").unwrap();
1211 let error = KnowledgeStore::open(&path).unwrap_err();
1212 assert!(matches!(error, KnowledgeStoreError::Corrupt(_)));
1213 let _ = fs::remove_file(&path);
1214 }
1215
1216 #[test]
1217 fn assessment_is_read_only_and_returns_current_evidence() {
1218 let path = test_path();
1219 let mut store = KnowledgeStore::open(&path).unwrap();
1220 store
1221 .upsert(record("knowledge_1", KnowledgeConfidence::Verified, "01"))
1222 .unwrap();
1223 let context = KnowledgeLookupContext {
1224 origin: "https://example.test".into(),
1225 path: "/docs/start".into(),
1226 profile_scope: KnowledgeProfileScope::Anonymous,
1227 profile_key: None,
1228 locale: None,
1229 tenant_key: None,
1230 browser_family: "chromium".into(),
1231 browser_version: None,
1232 glass_schema_version: 1,
1233 policy_preset: "balanced".into(),
1234 current_revision: 1,
1235 current_extension_id: None,
1236 landmarks: vec!["documentation".into()],
1237 now_epoch_seconds: chrono::DateTime::parse_from_rfc3339("2026-07-27T00:00:02Z")
1238 .unwrap()
1239 .timestamp(),
1240 surface_kind: None,
1241 backend_kind: None,
1242 backend_capabilities: Vec::new(),
1243 workspace_id: None,
1244 workspace_generation: None,
1245 };
1246 let assessments = store.assess(&context);
1247 assert_eq!(assessments.len(), 1);
1248 assert_eq!(assessments[0].record_id, "knowledge_1");
1249 assert_eq!(store.snapshot().records.len(), 1);
1250 let _ = fs::remove_file(&path);
1251 let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
1252 }
1253
1254 #[test]
1255 fn retrieval_report_is_explicitly_bounded_and_auditable_without_embeddings() {
1256 let path = test_path();
1257 let mut store = KnowledgeStore::open(&path).unwrap();
1258 store
1259 .upsert(record("eligible", KnowledgeConfidence::Observed, "01"))
1260 .unwrap();
1261 let mut stale = record("stale", KnowledgeConfidence::Stale, "01");
1262 stale.retrieval.current_validation = KnowledgeCurrentValidation {
1263 status: super::super::knowledge::KnowledgeCurrentValidationStatus::Stale,
1264 evidence_quality: KnowledgeEvidenceQuality::None,
1265 current_revision: None,
1266 validated_at: None,
1267 };
1268 store.upsert(stale).unwrap();
1269
1270 let context = KnowledgeLookupContext {
1271 origin: "https://example.test".into(),
1272 path: "/docs/start".into(),
1273 profile_scope: KnowledgeProfileScope::Anonymous,
1274 profile_key: None,
1275 locale: None,
1276 tenant_key: None,
1277 browser_family: "chromium".into(),
1278 browser_version: None,
1279 glass_schema_version: 1,
1280 policy_preset: "balanced".into(),
1281 landmarks: vec!["documentation".into()],
1282 now_epoch_seconds: chrono::DateTime::parse_from_rfc3339("2026-07-27T00:00:02Z")
1283 .unwrap()
1284 .timestamp(),
1285 current_revision: 1,
1286 surface_kind: Some(KnowledgeSurfaceKind::Document),
1287 backend_kind: Some(KnowledgeBackendKind::Cdp),
1288 backend_capabilities: vec![
1289 KnowledgeBackendCapability::SemanticExtraction,
1290 KnowledgeBackendCapability::Verification,
1291 ],
1292 current_extension_id: None,
1293 workspace_id: None,
1294 workspace_generation: None,
1295 };
1296 let report = store.retrieve(
1297 &context,
1298 &KnowledgeRetrievalQuery {
1299 page_kind: Some("documentation".into()),
1300 max_results: 1,
1301 ..KnowledgeRetrievalQuery::default()
1302 },
1303 );
1304
1305 assert!(!report.embeddings_used);
1306 assert_eq!(report.selected_record_ids, vec!["eligible"]);
1307 assert_eq!(report.rejected_record_ids, vec!["stale"]);
1308 let stale = report
1309 .candidates
1310 .iter()
1311 .find(|candidate| candidate.record_id == "stale")
1312 .unwrap();
1313 assert_eq!(
1314 stale.current_validation.status,
1315 super::super::knowledge::KnowledgeCurrentValidationStatus::Stale
1316 );
1317 assert_eq!(
1318 stale.rejection,
1319 Some(KnowledgeRejectionReason::StaleLifecycle)
1320 );
1321 let _ = fs::remove_file(&path);
1322 let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
1323 }
1324 #[test]
1325 fn lifecycle_management_and_stats_are_persisted() {
1326 let path = test_path();
1327 let mut store = KnowledgeStore::open(&path).unwrap();
1328 store
1329 .upsert(record("keep", KnowledgeConfidence::Observed, "01"))
1330 .unwrap();
1331 store
1332 .upsert(record("purge", KnowledgeConfidence::Observed, "02"))
1333 .unwrap();
1334 store
1335 .transition(
1336 "keep",
1337 KnowledgeConfidence::Verified,
1338 "fresh landmark verification".into(),
1339 "2026-07-27T00:00:03Z".into(),
1340 true,
1341 )
1342 .unwrap();
1343 let stats = store.stats().unwrap();
1344 assert_eq!(stats.record_count, 2);
1345 assert_eq!(stats.verified_count, 1);
1346 let purge = store.purge_origin("https://example.test").unwrap();
1347 assert_eq!(purge.removed_record_ids, vec!["keep", "purge"]);
1348 assert!(store.records().is_empty());
1349 let _ = fs::remove_file(&path);
1350 let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
1351 }
1352 #[test]
1353 fn workspace_path_hashes_untrusted_profile_and_is_bounded() {
1354 let path =
1355 default_knowledge_store_path_for_workspace("../escape", "workspace-alpha", Some(7));
1356 let file_name = path.file_name().unwrap().to_string_lossy();
1357 assert!(file_name.starts_with("workspace-"));
1358 assert!(!file_name.contains(".."));
1359 assert!(!path.to_string_lossy().contains("../escape"));
1360 }
1361 #[test]
1362 fn scoped_management_exports_and_prunes_only_matching_profile() {
1363 let path = test_path();
1364 let mut store = KnowledgeStore::open(&path).unwrap();
1365 store
1366 .upsert(record("anonymous", KnowledgeConfidence::Stale, "01"))
1367 .unwrap();
1368 let mut profile_record = record("profile", KnowledgeConfidence::Stale, "02");
1369 profile_record.scope.profile_scope = KnowledgeProfileScope::ProfileBound;
1370 profile_record.scope.profile_key = Some("alice".into());
1371 store.upsert(profile_record).unwrap();
1372
1373 let anonymous = KnowledgeScopeSelector::new(
1374 "https://example.test".into(),
1375 KnowledgeProfileScope::Anonymous,
1376 None,
1377 None,
1378 None,
1379 )
1380 .unwrap();
1381 let exported = store.export_scoped(&anonymous).unwrap();
1382 assert_eq!(
1383 exported
1384 .records
1385 .iter()
1386 .map(|record| record.record_id.as_str())
1387 .collect::<Vec<_>>(),
1388 vec!["anonymous"]
1389 );
1390 let removed = store.prune_scoped(&anonymous).unwrap();
1391 assert_eq!(removed.removed_record_ids, vec!["anonymous"]);
1392 assert!(store.get("profile").is_some());
1393 let _ = fs::remove_file(&path);
1394 let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
1395 }
1396
1397 #[test]
1398 fn scoped_removal_rejects_cross_profile_access() {
1399 let path = test_path();
1400 let mut store = KnowledgeStore::open(&path).unwrap();
1401 store
1402 .upsert(record("anonymous", KnowledgeConfidence::Observed, "01"))
1403 .unwrap();
1404 let profile = KnowledgeScopeSelector::new(
1405 "https://example.test".into(),
1406 KnowledgeProfileScope::ProfileBound,
1407 Some("alice".into()),
1408 None,
1409 None,
1410 )
1411 .unwrap();
1412 assert!(matches!(
1413 store.remove_scoped("anonymous", &profile),
1414 Err(KnowledgeStoreError::ScopeMismatch(id)) if id == "anonymous"
1415 ));
1416 assert!(store.get("anonymous").is_some());
1417 let _ = fs::remove_file(&path);
1418 let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
1419 }
1420
1421 #[test]
1422 fn scope_selector_rejects_unbounded_or_sensitive_dimensions() {
1423 assert!(
1424 KnowledgeScopeSelector::new(
1425 "https://example.test/path".into(),
1426 KnowledgeProfileScope::Anonymous,
1427 None,
1428 None,
1429 None,
1430 )
1431 .is_err()
1432 );
1433 assert!(
1434 KnowledgeScopeSelector::new(
1435 "https://example.test".into(),
1436 KnowledgeProfileScope::ProfileBound,
1437 None,
1438 None,
1439 None,
1440 )
1441 .is_err()
1442 );
1443 assert!(
1444 KnowledgeScopeSelector::new(
1445 "https://example.test".into(),
1446 KnowledgeProfileScope::Anonymous,
1447 None,
1448 None,
1449 Some(1),
1450 )
1451 .is_err()
1452 );
1453 assert!(
1454 KnowledgeScopeSelector::new(
1455 "https://example.test".into(),
1456 KnowledgeProfileScope::ProfileBound,
1457 Some("session-token".into()),
1458 None,
1459 None,
1460 )
1461 .is_err()
1462 );
1463 }
1464 fn learning_observation() -> SemanticObservation {
1465 let corpus: serde_json::Value = serde_json::from_str(include_str!(
1466 "../../../benchmarks/scenarios/semantic-observation-v1.json"
1467 ))
1468 .unwrap();
1469 SemanticObservation::from_json(&corpus["fixtures"][1]["observation"].to_string()).unwrap()
1470 }
1471
1472 fn learning_build(record_id: &str) -> KnowledgeRecordBuildOptions {
1473 let mut scope = record("template", KnowledgeConfidence::Observed, "01").scope;
1474 scope.path_pattern = "/search*".into();
1475 KnowledgeRecordBuildOptions {
1476 record_id: record_id.into(),
1477 scope,
1478 glass_version: "0.2.0".into(),
1479 observed_at: "2026-08-07T00:00:00Z".into(),
1480 surface: KnowledgeSurfaceProvenance {
1481 kind: KnowledgeSurfaceKind::Document,
1482 understanding: KnowledgeUnderstandingLevel::Strong,
1483 coverage: KnowledgeSurfaceCoverage::Semantic,
1484 extension_id: None,
1485 },
1486 backend: KnowledgeBackendProvenance {
1487 backend: KnowledgeBackendKind::Cdp,
1488 profile: "production".into(),
1489 capabilities: vec![
1490 KnowledgeBackendCapability::SemanticExtraction,
1491 KnowledgeBackendCapability::Verification,
1492 ],
1493 },
1494 portability: KnowledgePortability::SurfacePortable,
1495 current_validation: KnowledgeCurrentValidation::default(),
1496 }
1497 }
1498
1499 fn learning_evidence(
1500 observation: &SemanticObservation,
1501 compatibility_key: &str,
1502 ) -> KnowledgeVerifiedWorkflowEvidence {
1503 KnowledgeVerifiedWorkflowEvidence {
1504 guarded_revision: observation.revision,
1505 successful: true,
1506 postcondition_verified: true,
1507 evidence_quality: KnowledgeEvidenceQuality::Strong,
1508 observed_at: "2026-08-07T00:00:00Z".into(),
1509 compatibility_key: compatibility_key.into(),
1510 private_context: false,
1511 incognito: false,
1512 }
1513 }
1514
1515 fn learning_request<'a>(
1516 observation: &'a SemanticObservation,
1517 record_id: &str,
1518 compatibility_key: &str,
1519 ) -> KnowledgeLearningRequest<'a> {
1520 KnowledgeLearningRequest {
1521 observation,
1522 build: learning_build(record_id),
1523 evidence: learning_evidence(observation, compatibility_key),
1524 policy: KnowledgeLearningPolicy {
1525 required_verified_uses: 2,
1526 },
1527 }
1528 }
1529
1530 fn retrieval_context() -> KnowledgeLookupContext {
1531 KnowledgeLookupContext {
1532 origin: "https://example.test".into(),
1533 path: "/docs/start".into(),
1534 profile_scope: KnowledgeProfileScope::Anonymous,
1535 profile_key: None,
1536 locale: None,
1537 tenant_key: None,
1538 browser_family: "chromium".into(),
1539 browser_version: None,
1540 glass_schema_version: 1,
1541 policy_preset: "balanced".into(),
1542 landmarks: vec!["documentation".into()],
1543 now_epoch_seconds: 1_785_542_400,
1544 current_revision: 1,
1545 surface_kind: Some(KnowledgeSurfaceKind::Document),
1546 backend_kind: Some(KnowledgeBackendKind::Cdp),
1547 backend_capabilities: vec![
1548 KnowledgeBackendCapability::SemanticExtraction,
1549 KnowledgeBackendCapability::Verification,
1550 ],
1551 current_extension_id: None,
1552 workspace_id: None,
1553 workspace_generation: None,
1554 }
1555 }
1556
1557 #[test]
1558 fn learning_rejects_failed_private_truncated_and_sensitive_evidence() {
1559 let path = test_path();
1560 let mut store = KnowledgeStore::open(&path).unwrap();
1561 let observation = learning_observation();
1562
1563 let mut failed = learning_evidence(&observation, "failed");
1564 failed.successful = false;
1565 let error = store
1566 .learn_verified(KnowledgeLearningRequest {
1567 observation: &observation,
1568 build: learning_build("failed"),
1569 evidence: failed,
1570 policy: KnowledgeLearningPolicy::default(),
1571 })
1572 .unwrap_err();
1573 assert!(matches!(
1574 error,
1575 KnowledgeStoreError::InvalidContract(error) if error.path == "workflow"
1576 ));
1577
1578 let mut private = learning_evidence(&observation, "private");
1579 private.private_context = true;
1580 let error = store
1581 .learn_verified(KnowledgeLearningRequest {
1582 observation: &observation,
1583 build: learning_build("private"),
1584 evidence: private,
1585 policy: KnowledgeLearningPolicy::default(),
1586 })
1587 .unwrap_err();
1588 assert!(matches!(
1589 error,
1590 KnowledgeStoreError::InvalidContract(error) if error.path == "privacy"
1591 ));
1592
1593 let mut truncated_observation = observation.clone();
1594 truncated_observation.limits.truncated = true;
1595 let error = store
1596 .learn_verified(learning_request(
1597 &truncated_observation,
1598 "truncated",
1599 "truncated",
1600 ))
1601 .unwrap_err();
1602 assert!(matches!(
1603 error,
1604 KnowledgeStoreError::InvalidContract(error) if error.path == "observation.limits"
1605 ));
1606
1607 let mut sensitive_observation = observation;
1608 sensitive_observation.text = Some("password".into());
1609 let error = store
1610 .learn_verified(learning_request(
1611 &sensitive_observation,
1612 "sensitive",
1613 "sensitive",
1614 ))
1615 .unwrap_err();
1616 assert!(matches!(
1617 error,
1618 KnowledgeStoreError::InvalidContract(error) if error.path == "observation"
1619 ));
1620 assert!(store.records().is_empty());
1621 let _ = fs::remove_file(&path);
1622 let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
1623 }
1624
1625 #[test]
1626 fn learning_promotes_after_compatible_uses_and_merges_history() {
1627 let path = test_path();
1628 let mut store = KnowledgeStore::open(&path).unwrap();
1629 let observation = learning_observation();
1630 let first = store
1631 .learn_verified(learning_request(&observation, "learned", "same-workflow"))
1632 .unwrap();
1633 assert!(first.created);
1634 assert!(!first.promoted);
1635 assert_eq!(first.confidence, KnowledgeConfidence::Candidate);
1636 assert_eq!(first.verification_count, 1);
1637
1638 let second = store
1639 .learn_verified(learning_request(&observation, "learned", "same-workflow"))
1640 .unwrap();
1641 assert!(!second.created);
1642 assert!(second.promoted);
1643 assert_eq!(second.confidence, KnowledgeConfidence::Verified);
1644 assert_eq!(second.verification_count, 2);
1645 let learned = store.get("learned").unwrap();
1646 assert_eq!(learned.source.verification_count, 2);
1647 assert_eq!(learned.history.len(), 1);
1648 assert_eq!(learned.history[0].from, KnowledgeConfidence::Candidate);
1649 assert_eq!(learned.history[0].to, KnowledgeConfidence::Verified);
1650
1651 let reopened = KnowledgeStore::open(&path).unwrap();
1652 let persisted = reopened.get("learned").unwrap();
1653 assert_eq!(persisted.source.verification_count, 2);
1654 assert_eq!(persisted.history.len(), 1);
1655 let _ = fs::remove_file(&path);
1656 let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
1657 }
1658
1659 #[test]
1660 fn graph_construction_and_traversal_are_deterministic_and_bounded() {
1661 let path = test_path();
1662 let mut store = KnowledgeStore::open(&path).unwrap();
1663 store
1664 .upsert(record("graph-a", KnowledgeConfidence::Observed, "01"))
1665 .unwrap();
1666 store
1667 .upsert(record("graph-b", KnowledgeConfidence::Observed, "02"))
1668 .unwrap();
1669 let graph = store.graph();
1670 assert_eq!(graph, store.graph());
1671 assert!(graph.nodes.len() <= 256);
1672 assert!(graph.edges.iter().any(|edge| {
1673 edge.from == "record:graph-a"
1674 && edge.to == "page:documentation"
1675 && edge.relation == "hasPageKind"
1676 }));
1677
1678 let bounded = store.traverse_graph("record:graph-a", 1, 1).unwrap();
1679 assert_eq!(bounded.node_ids, vec!["record:graph-a"]);
1680 assert!(bounded.truncated);
1681 let repeat = store.traverse_graph("record:graph-a", 1, 1).unwrap();
1682 assert_eq!(bounded, repeat);
1683 assert!(matches!(
1684 store.traverse_graph("record:graph-a", 9, 2),
1685 Err(KnowledgeStoreError::InvalidConfiguration(_))
1686 ));
1687 let _ = fs::remove_file(&path);
1688 let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
1689 }
1690
1691 struct CountingEmbeddingProvider<'a> {
1692 calls: &'a AtomicUsize,
1693 }
1694
1695 impl KnowledgeEmbeddingProvider for CountingEmbeddingProvider<'_> {
1696 fn similarity_millis(
1697 &self,
1698 _query: &KnowledgeRetrievalQuery,
1699 _record: &KnowledgeRecord,
1700 ) -> Option<u16> {
1701 self.calls.fetch_add(1, Ordering::Relaxed);
1702 Some(777)
1703 }
1704 }
1705
1706 #[test]
1707 fn embeddings_are_disabled_by_default_and_only_used_when_injected() {
1708 let path = test_path();
1709 let mut store = KnowledgeStore::open(&path).unwrap();
1710 store
1711 .upsert(record("embedding", KnowledgeConfidence::Observed, "01"))
1712 .unwrap();
1713 let context = retrieval_context();
1714 let query = KnowledgeRetrievalQuery {
1715 page_kind: Some("documentation".into()),
1716 max_results: 1,
1717 ..KnowledgeRetrievalQuery::default()
1718 };
1719 let default_report = store.retrieve(&context, &query);
1720 let no_provider = store.retrieve_with_embeddings(&context, &query, None);
1721 assert_eq!(default_report, no_provider);
1722 assert!(!no_provider.embeddings_used);
1723
1724 let calls = AtomicUsize::new(0);
1725 let provider = CountingEmbeddingProvider { calls: &calls };
1726 let injected = store.retrieve_with_embeddings(&context, &query, Some(&provider));
1727 assert!(injected.embeddings_used);
1728 assert_eq!(calls.load(Ordering::Relaxed), 1);
1729 assert!(injected.candidates[0].signals.iter().any(|signal| {
1730 signal.kind == super::super::knowledge::KnowledgeRetrievalSignalKind::SemanticSimilarity
1731 && signal.score_millis == Some(777)
1732 }));
1733 let _ = fs::remove_file(&path);
1734 let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
1735 }
1736 #[test]
1737 fn learning_rejects_scope_provenance_mismatch_before_mutation() {
1738 let path = test_path();
1739 let mut store = KnowledgeStore::open(&path).unwrap();
1740 let observation = learning_observation();
1741 let mut build = learning_build("scope-mismatch");
1742 build.scope.origin = "https://other.example".into();
1743 let error = store
1744 .learn_verified(KnowledgeLearningRequest {
1745 observation: &observation,
1746 build,
1747 evidence: learning_evidence(&observation, "scope-mismatch"),
1748 policy: KnowledgeLearningPolicy::default(),
1749 })
1750 .unwrap_err();
1751 assert!(matches!(
1752 error,
1753 KnowledgeStoreError::InvalidContract(error) if error.path == "build.scope.origin"
1754 ));
1755 assert!(store.records().is_empty());
1756 let _ = fs::remove_file(&path);
1757 let _ = fs::remove_file(format!("{}{}", path.display(), STORE_LOCK_SUFFIX));
1758 }
1759}