Skip to main content

glass_browser/browser/session/
knowledge_store.rs

1//! Crash-safe local persistence for bounded [`super::KnowledgeRecord`] values.
2//!
3//! The store is intentionally an explicit library component. Opening it does
4//! not make a browser session consult remembered data; callers must opt into
5//! each later knowledge-assisted operation.
6
7use 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
31/// Default per-profile knowledge file used by local management surfaces.
32pub 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
42/// Derive a workspace-incarnation-specific path. The identity is hashed so
43/// arbitrary workspace names cannot escape the profile directory.
44pub 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/// Resource bounds for one local knowledge store.
65#[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/// Result of an upsert or removal, including deterministic pruning evidence.
97#[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/// Bounded store statistics suitable for CLI/TUI display.
107#[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/// A validated local knowledge store backed by one JSON snapshot file.
121#[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    /// Open an existing store or an empty store at `path`.
131    pub fn open(path: impl Into<PathBuf>) -> Result<Self, KnowledgeStoreError> {
132        Self::open_with_limits(path, KnowledgeStoreLimits::default())
133    }
134
135    /// Open a store with explicit record and serialized-byte limits.
136    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    /// Return the path used for the snapshot file.
153    pub fn path(&self) -> &Path {
154        &self.path
155    }
156
157    /// Return the active store limits.
158    pub fn limits(&self) -> KnowledgeStoreLimits {
159        self.limits
160    }
161
162    /// Return the last validated in-memory snapshot.
163    pub fn snapshot(&self) -> &KnowledgeStoreSnapshot {
164        &self.snapshot
165    }
166
167    /// Re-read the snapshot under the store lock.
168    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    /// Find one record by its stable ID.
178    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    /// Assess all records against fresh session dimensions without changing
186    /// the store or returning any executable browser reference.
187    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    /// Retrieve bounded exact/graph-compatible advisory records. Selection is
196    /// deterministic and never exposes a revision-local executable target.
197    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    /// Retrieve with an explicitly supplied semantic provider. Passing
247    /// `None` is byte-for-byte equivalent to [`Self::retrieve`] and leaves
248    /// embeddings disabled.
249    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    /// Return the validated records for inspection or export.
278    pub fn records(&self) -> &[KnowledgeRecord] {
279        &self.snapshot.records
280    }
281
282    /// Export only records in the exact origin/profile/workspace scope.
283    ///
284    /// The returned snapshot remains validated and contains only bounded
285    /// semantic records; revision-local handles and sensitive payload fields
286    /// cannot enter the store through record validation.
287    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    /// Remove one record only when its complete privacy scope matches.
307    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    /// Forget every record in one exact origin/profile/workspace scope.
337    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    /// Prune stale, contradicted, or quarantined records in one exact scope.
361    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    /// Return bounded serialized-size and lifecycle counts.
390    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    /// Replace the complete store only after validating its schema and bounds.
415    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    /// Transition one record and retain the lifecycle evidence in its history.
436    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    /// Remove every record scoped to one exact origin.
463    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    /// Insert or replace a record, then prune the least useful records first.
486    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    /// Remove one record and persist the resulting snapshot.
524    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    /// Persist fresh semantic evidence only after a successful guarded
546    /// workflow. Repeated compatible uses promote the record deterministically.
547    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    /// Mark a record contradicted by a fresh current Web IR witness.
677    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    /// Derive a bounded graph from the compact records in this local store.
710    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    /// Traverse the local graph with explicit depth and node bounds.
769    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    /// Record an explicit supersession as a contradiction transition on the
814    /// older record. The newer record must already be present in this store.
815    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/// Errors returned by the local knowledge store.
1033#[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/// Result of purging records for one origin.
1068#[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}