use super::{SemanticIntentCandidate, SemanticObservation, target_fingerprint_digest};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use sha2::{Digest, Sha256};
use std::collections::BTreeSet;
use std::fmt;
use url::Url;
pub const KNOWLEDGE_SCHEMA_VERSION: u32 = 1;
pub const MAX_KNOWLEDGE_RECORDS: usize = 256;
const MAX_RECORD_ID_BYTES: usize = 128;
const MAX_SCOPE_VALUE_BYTES: usize = 256;
const MAX_ROLE_BYTES: usize = 64;
const MAX_TIMESTAMP_BYTES: usize = 64;
const MAX_LANDMARKS: usize = 32;
const MAX_HISTORY: usize = 32;
const MAX_RETRIEVAL_SIGNALS: usize = 16;
const MAX_BACKEND_CAPABILITIES: usize = 32;
const MAX_DATA_BYTES: usize = 16 * 1024;
const MAX_RECORD_BYTES: usize = 64 * 1024;
const MAX_EXTENSION_ID_BYTES: usize = 128;
const MAX_JSON_DEPTH: usize = 8;
const MAX_JSON_OBJECT_ENTRIES: usize = 64;
const MAX_JSON_ARRAY_ENTRIES: usize = 64;
const MAX_JSON_STRING_BYTES: usize = 4096;
const MAX_RETRIEVAL_QUERY_VALUES: usize = 32;
const MAX_RETRIEVAL_QUERY_VALUE_BYTES: usize = 256;
const MAX_WORKSPACE_ID_BYTES: usize = 128;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct KnowledgeLookupContext {
pub origin: String,
pub path: String,
pub profile_scope: KnowledgeProfileScope,
pub profile_key: Option<String>,
pub locale: Option<String>,
pub tenant_key: Option<String>,
pub browser_family: String,
pub browser_version: Option<String>,
pub glass_schema_version: u32,
pub policy_preset: String,
pub landmarks: Vec<String>,
pub now_epoch_seconds: i64,
pub current_revision: u64,
pub surface_kind: Option<KnowledgeSurfaceKind>,
pub backend_kind: Option<KnowledgeBackendKind>,
pub backend_capabilities: Vec<KnowledgeBackendCapability>,
pub current_extension_id: Option<String>,
pub workspace_id: Option<String>,
pub workspace_generation: Option<u64>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct KnowledgeLookupOptions {
pub profile_scope: KnowledgeProfileScope,
pub profile_key: Option<String>,
pub locale: Option<String>,
pub tenant_key: Option<String>,
pub browser_family: String,
pub browser_version: Option<String>,
pub glass_schema_version: u32,
pub policy_preset: String,
pub now_epoch_seconds: i64,
pub current_revision: Option<u64>,
pub current_extension_id: Option<String>,
pub surface_kind: Option<KnowledgeSurfaceKind>,
pub backend_kind: Option<KnowledgeBackendKind>,
pub backend_capabilities: Vec<KnowledgeBackendCapability>,
pub workspace_id: Option<String>,
pub workspace_generation: Option<u64>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct KnowledgeRecordBuildOptions {
pub record_id: String,
pub scope: KnowledgeScope,
pub glass_version: String,
pub observed_at: String,
pub surface: KnowledgeSurfaceProvenance,
pub backend: KnowledgeBackendProvenance,
pub portability: KnowledgePortability,
pub current_validation: KnowledgeCurrentValidation,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct KnowledgeLearningPolicy {
pub required_verified_uses: u32,
}
impl Default for KnowledgeLearningPolicy {
fn default() -> Self {
Self {
required_verified_uses: 2,
}
}
}
impl KnowledgeLearningPolicy {
pub fn validate(self) -> Result<(), KnowledgeValidationError> {
if self.required_verified_uses == 0 || self.required_verified_uses > 32 {
return Err(KnowledgeValidationError::new(
"requiredVerifiedUses",
"must be between 1 and 32",
));
}
Ok(())
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct KnowledgeVerifiedWorkflowEvidence {
pub guarded_revision: u64,
pub successful: bool,
pub postcondition_verified: bool,
pub evidence_quality: KnowledgeEvidenceQuality,
pub observed_at: String,
pub compatibility_key: String,
pub private_context: bool,
pub incognito: bool,
}
impl KnowledgeVerifiedWorkflowEvidence {
pub fn validate_against(
&self,
observation: &SemanticObservation,
) -> Result<(), KnowledgeValidationError> {
if self.private_context || self.incognito {
return Err(KnowledgeValidationError::new(
"privacy",
"private or incognito contexts cannot create persistent knowledge",
));
}
if !self.successful || !self.postcondition_verified {
return Err(KnowledgeValidationError::new(
"workflow",
"learning requires a successful workflow and verified postcondition",
));
}
if self.guarded_revision == 0 || self.guarded_revision != observation.revision {
return Err(KnowledgeValidationError::new(
"guardedRevision",
"workflow witness must guard the fresh observation revision",
));
}
if self.evidence_quality == KnowledgeEvidenceQuality::None {
return Err(KnowledgeValidationError::new(
"evidenceQuality",
"workflow witness requires non-empty evidence quality",
));
}
validate_timestamp("observedAt", &self.observed_at)?;
validate_text(
"compatibilityKey",
&self.compatibility_key,
MAX_SCOPE_VALUE_BYTES,
false,
)?;
validate_public_text("compatibilityKey", &self.compatibility_key)?;
Ok(())
}
}
#[derive(Debug, Clone)]
pub struct KnowledgeLearningRequest<'a> {
pub observation: &'a SemanticObservation,
pub build: KnowledgeRecordBuildOptions,
pub evidence: KnowledgeVerifiedWorkflowEvidence,
pub policy: KnowledgeLearningPolicy,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct KnowledgeLearningResult {
pub record_id: String,
pub confidence: KnowledgeConfidence,
pub verification_count: u32,
pub promoted: bool,
pub created: bool,
}
impl KnowledgeLookupContext {
pub fn from_observation(
observation: &SemanticObservation,
options: KnowledgeLookupOptions,
) -> Result<Self, KnowledgeValidationError> {
let url = Url::parse(&observation.route.url).map_err(|error| {
KnowledgeValidationError::new("observation.route.url", format!("invalid URL: {error}"))
})?;
let origin = url.origin().ascii_serialization();
let path = if url.path().is_empty() {
"/".to_string()
} else {
url.path().to_string()
};
let mut landmarks = BTreeSet::new();
landmarks.insert(
serde_json::to_string(&observation.page.kind).map_err(|error| {
KnowledgeValidationError::new("observation.page.kind", error.to_string())
})?,
);
for region in &observation.regions {
landmarks.insert(serde_json::to_string(®ion.kind).map_err(|error| {
KnowledgeValidationError::new("observation.regions.kind", error.to_string())
})?);
}
if observation.revision == 0 {
return Err(KnowledgeValidationError::new(
"observation.revision",
"must be positive",
));
}
if options
.current_revision
.is_some_and(|revision| revision != observation.revision)
{
return Err(KnowledgeValidationError::new(
"currentRevision",
"must match the fresh observation revision",
));
}
let current_revision = observation.revision;
let current_extension_id = options.current_extension_id.clone();
if options.surface_kind == Some(KnowledgeSurfaceKind::ExtensionDefined)
&& current_extension_id.is_none()
{
return Err(KnowledgeValidationError::new(
"currentExtensionId",
"extension-defined contexts require an extension identifier",
));
}
validate_workspace_scope(
"workspaceId",
options.workspace_id.as_deref(),
options.workspace_generation,
)?;
if options.surface_kind != Some(KnowledgeSurfaceKind::ExtensionDefined)
&& current_extension_id.is_some()
{
return Err(KnowledgeValidationError::new(
"currentExtensionId",
"extension identifiers are only valid for extension-defined contexts",
));
}
let workspace_id = options.workspace_id.clone();
let workspace_generation = options.workspace_generation;
if let Some(extension_id) = ¤t_extension_id {
validate_text(
"currentExtensionId",
extension_id,
MAX_EXTENSION_ID_BYTES,
false,
)?;
validate_public_text("currentExtensionId", extension_id)?;
}
validate_backend_capabilities("backendCapabilities", &options.backend_capabilities)?;
Ok(Self {
origin,
path,
profile_scope: options.profile_scope,
profile_key: options.profile_key,
locale: options.locale,
tenant_key: options.tenant_key,
browser_family: options.browser_family,
browser_version: options.browser_version,
glass_schema_version: options.glass_schema_version,
policy_preset: options.policy_preset,
landmarks: landmarks
.into_iter()
.map(|landmark| landmark.trim_matches('"').to_string())
.collect(),
now_epoch_seconds: options.now_epoch_seconds,
surface_kind: options.surface_kind,
backend_kind: options.backend_kind,
backend_capabilities: options.backend_capabilities,
current_extension_id,
current_revision,
workspace_id,
workspace_generation,
})
}
pub fn from_observation_with_portability(
observation: &SemanticObservation,
options: KnowledgeLookupOptions,
surface_kind: KnowledgeSurfaceKind,
backend_kind: KnowledgeBackendKind,
backend_capabilities: Vec<KnowledgeBackendCapability>,
current_extension_id: Option<String>,
) -> Result<Self, KnowledgeValidationError> {
validate_backend_capabilities("backendCapabilities", &backend_capabilities)?;
let mut context = Self::from_observation(observation, options)?;
context.surface_kind = Some(surface_kind);
context.backend_kind = Some(backend_kind);
context.backend_capabilities = backend_capabilities;
context.current_extension_id = current_extension_id;
if context.surface_kind == Some(KnowledgeSurfaceKind::ExtensionDefined)
&& context.current_extension_id.is_none()
{
return Err(KnowledgeValidationError::new(
"currentExtensionId",
"extension-defined contexts require an extension identifier",
));
}
if context.surface_kind != Some(KnowledgeSurfaceKind::ExtensionDefined)
&& context.current_extension_id.is_some()
{
return Err(KnowledgeValidationError::new(
"currentExtensionId",
"extension identifiers are only valid for extension-defined contexts",
));
}
if let Some(extension_id) = &context.current_extension_id {
validate_text(
"currentExtensionId",
extension_id,
MAX_EXTENSION_ID_BYTES,
false,
)?;
validate_public_text("currentExtensionId", extension_id)?;
}
Ok(context)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeSignalKind {
OriginMatch,
PathMatch,
ProfileScopeMatch,
WorkspaceMatch,
LocaleMatch,
TenantMatch,
BrowserMatch,
SchemaMatch,
PolicyMatch,
LandmarkMatch,
FreshnessMatch,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct KnowledgeAssessmentSignal {
pub kind: KnowledgeSignalKind,
pub detail: String,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeAssessmentStatus {
Eligible,
OutOfScope,
Stale,
Contradicted,
Quarantined,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct KnowledgeAssessment {
pub record_id: String,
pub status: KnowledgeAssessmentStatus,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub signals: Vec<KnowledgeAssessmentSignal>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub conflicts: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub missing_landmarks: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub age_seconds: Option<i64>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeObservationMode {
FreshOnly,
Assessed,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct KnowledgeObservationReport {
pub observation: SemanticObservation,
pub mode: KnowledgeObservationMode,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub assessments: Vec<KnowledgeAssessment>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub eligible_record_ids: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub stale_record_ids: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub out_of_scope_record_ids: Vec<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeRecordKind {
PageFamily,
RegionModel,
TargetFingerprint,
RouteTransition,
WorkflowEntryPoint,
VerifiedPostcondition,
ExtractionShape,
InvalidationRule,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum KnowledgeConfidence {
Candidate,
Observed,
Verified,
Stale,
Contradicted,
Quarantined,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct KnowledgeScopeSelector {
pub origin: String,
pub profile_scope: KnowledgeProfileScope,
pub profile_key: Option<String>,
pub workspace_id: Option<String>,
pub workspace_generation: Option<u64>,
}
impl KnowledgeScopeSelector {
pub fn new(
origin: String,
profile_scope: KnowledgeProfileScope,
profile_key: Option<String>,
workspace_id: Option<String>,
workspace_generation: Option<u64>,
) -> Result<Self, KnowledgeValidationError> {
let selector = Self {
origin,
profile_scope,
profile_key,
workspace_id,
workspace_generation,
};
selector.validate()?;
Ok(selector)
}
pub fn validate(&self) -> Result<(), KnowledgeValidationError> {
validate_text("selector.origin", &self.origin, 2048, false)?;
validate_public_text("selector.origin", &self.origin)?;
let url = Url::parse(&self.origin).map_err(|error| {
KnowledgeValidationError::new("selector.origin", format!("invalid origin: {error}"))
})?;
if url.origin().ascii_serialization() != self.origin {
return Err(KnowledgeValidationError::new(
"selector.origin",
"must be an exact serialized URL origin",
));
}
if let Some(profile_key) = self.profile_key.as_deref() {
validate_text(
"selector.profileKey",
profile_key,
MAX_SCOPE_VALUE_BYTES,
false,
)?;
validate_public_text("selector.profileKey", profile_key)?;
}
match self.profile_scope {
KnowledgeProfileScope::ProfileBound if self.profile_key.is_none() => {
return Err(KnowledgeValidationError::new(
"selector.profileKey",
"is required for profileBound access",
));
}
KnowledgeProfileScope::Anonymous if self.profile_key.is_some() => {
return Err(KnowledgeValidationError::new(
"selector.profileKey",
"must be absent for anonymous access",
));
}
_ => {}
}
validate_workspace_scope(
"selector.workspaceId",
self.workspace_id.as_deref(),
self.workspace_generation,
)?;
if let Some(workspace_id) = self.workspace_id.as_deref() {
validate_public_text("selector.workspaceId", workspace_id)?;
}
Ok(())
}
pub(crate) fn matches(&self, scope: &KnowledgeScope) -> bool {
self.origin == scope.origin
&& self.profile_scope == scope.profile_scope
&& self.profile_key == scope.profile_key
&& self.workspace_id == scope.workspace_id
&& self.workspace_generation == scope.workspace_generation
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct KnowledgeScope {
pub origin: String,
pub path_pattern: String,
pub profile_scope: KnowledgeProfileScope,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub profile_key: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub locale: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tenant_key: Option<String>,
pub browser_family: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub browser_version_range: Option<String>,
pub glass_schema_version: u32,
pub policy_preset: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub workspace_id: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub workspace_generation: Option<u64>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeProfileScope {
Anonymous,
Authenticated,
ProfileBound,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeSurfaceProvenance {
pub kind: KnowledgeSurfaceKind,
pub understanding: KnowledgeUnderstandingLevel,
pub coverage: KnowledgeSurfaceCoverage,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub extension_id: Option<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeSurfaceKind {
Document,
Accessibility,
ShadowDocument,
FrameDocument,
Svg,
Canvas2d,
Webgl,
Webgpu,
EmbeddedDocument,
Pdf,
EmbeddedPdf,
Media,
Terminal,
RemoteApplication,
BrowserNative,
ExtensionDefined,
Unknown,
#[default]
Opaque,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeUnderstandingLevel {
Opaque,
Inferred,
Partial,
Strong,
TaskCompilable,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeSurfaceCoverage {
None,
Structural,
Semantic,
Interaction,
Complete,
}
impl Default for KnowledgeSurfaceProvenance {
fn default() -> Self {
Self {
kind: KnowledgeSurfaceKind::Opaque,
understanding: KnowledgeUnderstandingLevel::Opaque,
coverage: KnowledgeSurfaceCoverage::None,
extension_id: None,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeBackendProvenance {
pub backend: KnowledgeBackendKind,
pub profile: String,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub capabilities: Vec<KnowledgeBackendCapability>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeBackendKind {
Cdp,
WebdriverBidi,
BrowserExtension,
Visual,
Terminal,
#[default]
Unknown,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeBackendCapability {
Navigation,
SemanticExtraction,
CoordinateInput,
Script,
Capture,
Verification,
Storage,
Prompt,
}
impl Default for KnowledgeBackendProvenance {
fn default() -> Self {
Self {
backend: KnowledgeBackendKind::Unknown,
profile: "legacy".into(),
capabilities: Vec::new(),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgePortability {
SemanticPortable,
SurfacePortable,
BackendCapabilityDependent,
BackendSpecific,
BrowserSpecific,
#[default]
NonPortable,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeMemoryInfluence {
#[default]
None,
RankingOnly,
TemplateSuggested,
VerificationSuggested,
RecoverySuggested,
IdentityContinuitySuggested,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeRetrievalSignalKind {
ExactPageFamilyMatch,
ExactFingerprintMatch,
OriginMatch,
SurfaceMatch,
BackendMatch,
GraphDistance,
SemanticSimilarity,
Freshness,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeRetrievalSignal {
pub kind: KnowledgeRetrievalSignalKind,
pub detail: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub score_millis: Option<u16>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeCurrentValidationStatus {
NotValidated,
Validated,
Rejected,
Stale,
Contradicted,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeEvidenceQuality {
None,
Weak,
Partial,
Strong,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeCurrentValidation {
pub status: KnowledgeCurrentValidationStatus,
pub evidence_quality: KnowledgeEvidenceQuality,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub current_revision: Option<u64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub validated_at: Option<String>,
}
impl Default for KnowledgeCurrentValidation {
fn default() -> Self {
Self {
status: KnowledgeCurrentValidationStatus::NotValidated,
evidence_quality: KnowledgeEvidenceQuality::None,
current_revision: None,
validated_at: None,
}
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeRetrievalExplanation {
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub signals: Vec<KnowledgeRetrievalSignal>,
#[serde(default)]
pub current_validation: KnowledgeCurrentValidation,
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct KnowledgeRetrievalQuery {
pub page_kind: Option<String>,
pub task_kind: Option<String>,
pub entity_roles: Vec<String>,
pub landmarks: Vec<String>,
pub max_results: usize,
}
impl KnowledgeRetrievalQuery {
pub fn is_bounded(&self) -> bool {
self.max_results <= 16
&& self
.page_kind
.as_deref()
.is_none_or(|value| value.len() <= MAX_RETRIEVAL_QUERY_VALUE_BYTES)
&& self
.task_kind
.as_deref()
.is_none_or(|value| value.len() <= MAX_RETRIEVAL_QUERY_VALUE_BYTES)
&& self.entity_roles.len() <= MAX_RETRIEVAL_QUERY_VALUES
&& self.landmarks.len() <= MAX_RETRIEVAL_QUERY_VALUES
&& self
.entity_roles
.iter()
.chain(self.landmarks.iter())
.all(|value| value.len() <= MAX_RETRIEVAL_QUERY_VALUE_BYTES)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeRejectionReason {
OutOfScope,
WorkspaceMismatch,
WorkspaceGenerationMismatch,
LegacyWorkspaceUnbound,
StaleLifecycle,
ContradictedLifecycle,
Quarantined,
Stale,
BackendIncompatible,
SurfaceIncompatible,
ExtensionMismatch,
OpaqueProvenance,
Contradicted,
CurrentValidationMissing,
NoExactOrGraphMatch,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeRetrievalCandidate {
pub record_id: String,
pub selected: bool,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub signals: Vec<KnowledgeRetrievalSignal>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub rejection: Option<KnowledgeRejectionReason>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub explanation: Option<String>,
#[serde(default)]
pub current_validation: KnowledgeCurrentValidation,
#[serde(default)]
pub portability: KnowledgePortability,
#[serde(default)]
pub surface_kind: KnowledgeSurfaceKind,
#[serde(default)]
pub backend_kind: KnowledgeBackendKind,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeRetrievalReport {
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub candidates: Vec<KnowledgeRetrievalCandidate>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub selected_record_ids: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub rejected_record_ids: Vec<String>,
pub embeddings_used: bool,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum KnowledgeGraphNodeKind {
Record,
PageKind,
Landmark,
Workflow,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeGraphNode {
pub id: String,
pub kind: KnowledgeGraphNodeKind,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeGraphEdge {
pub from: String,
pub to: String,
pub relation: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeGraph {
pub nodes: Vec<KnowledgeGraphNode>,
pub edges: Vec<KnowledgeGraphEdge>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeGraphTraversal {
pub start: String,
pub max_depth: usize,
pub node_ids: Vec<String>,
pub edges: Vec<KnowledgeGraphEdge>,
pub truncated: bool,
}
pub trait KnowledgeEmbeddingProvider {
fn similarity_millis(
&self,
query: &KnowledgeRetrievalQuery,
record: &KnowledgeRecord,
) -> Option<u16>;
}
impl KnowledgeRetrievalReport {
pub fn selected(&self) -> impl Iterator<Item = &KnowledgeRetrievalCandidate> {
self.candidates
.iter()
.filter(|candidate| candidate.selected)
}
pub fn rejected(&self) -> impl Iterator<Item = &KnowledgeRetrievalCandidate> {
self.candidates
.iter()
.filter(|candidate| candidate.rejection.is_some())
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeSource {
pub first_seen_at: String,
pub last_verified_at: String,
pub glass_version: String,
pub verification_count: u32,
#[serde(default, skip_serializing_if = "is_legacy_surface")]
pub surface: KnowledgeSurfaceProvenance,
#[serde(default, skip_serializing_if = "is_legacy_backend")]
pub backend: KnowledgeBackendProvenance,
}
fn is_legacy_surface(value: &KnowledgeSurfaceProvenance) -> bool {
*value == KnowledgeSurfaceProvenance::default()
}
fn is_legacy_backend(value: &KnowledgeBackendProvenance) -> bool {
*value == KnowledgeBackendProvenance::default()
}
fn is_nonportable(value: &KnowledgePortability) -> bool {
*value == KnowledgePortability::NonPortable
}
fn is_no_memory_influence(value: &KnowledgeMemoryInfluence) -> bool {
*value == KnowledgeMemoryInfluence::None
}
fn is_empty_retrieval(value: &KnowledgeRetrievalExplanation) -> bool {
value.signals.is_empty() && value.current_validation == KnowledgeCurrentValidation::default()
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct KnowledgeInvalidation {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max_age_seconds: Option<u64>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub required_landmarks: Vec<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct KnowledgeLifecycleEvent {
pub from: KnowledgeConfidence,
pub to: KnowledgeConfidence,
pub reason: String,
pub observed_at: String,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeRecord {
pub schema_version: u32,
pub record_id: String,
pub kind: KnowledgeRecordKind,
pub scope: KnowledgeScope,
pub source: KnowledgeSource,
pub confidence: KnowledgeConfidence,
pub invalidation: KnowledgeInvalidation,
pub data: Value,
#[serde(default, skip_serializing_if = "is_nonportable")]
pub portability: KnowledgePortability,
#[serde(default, skip_serializing_if = "is_no_memory_influence")]
pub memory_influence: KnowledgeMemoryInfluence,
#[serde(default, skip_serializing_if = "is_empty_retrieval")]
pub retrieval: KnowledgeRetrievalExplanation,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub history: Vec<KnowledgeLifecycleEvent>,
}
impl KnowledgeRecord {
pub fn from_page_observation(
observation: &SemanticObservation,
options: KnowledgeRecordBuildOptions,
) -> Result<Self, KnowledgeValidationError> {
observation.validate().map_err(|error| {
KnowledgeValidationError::new("observation", format!("invalid observation: {error}"))
})?;
validate_text("recordId", &options.record_id, MAX_RECORD_ID_BYTES, false)?;
validate_text(
"source.glassVersion",
&options.glass_version,
MAX_SCOPE_VALUE_BYTES,
false,
)?;
validate_timestamp("source.observedAt", &options.observed_at)?;
validate_scope(&options.scope)?;
let page_kind = serde_json::to_value(observation.page.kind)
.map_err(|error| KnowledgeValidationError::new("data.pageKind", error.to_string()))?;
let region_kinds = observation
.regions
.iter()
.map(|region| serde_json::to_value(region.kind))
.collect::<Result<Vec<_>, _>>()
.map_err(|error| {
KnowledgeValidationError::new("data.regionKinds", error.to_string())
})?;
let mut required_landmarks = BTreeSet::new();
required_landmarks.insert(page_kind.as_str().unwrap_or_default().to_owned());
for kind in ®ion_kinds {
if let Some(kind) = kind.as_str() {
required_landmarks.insert(kind.to_owned());
}
}
let record = Self {
schema_version: KNOWLEDGE_SCHEMA_VERSION,
record_id: options.record_id,
kind: KnowledgeRecordKind::PageFamily,
scope: options.scope,
source: KnowledgeSource {
first_seen_at: options.observed_at.clone(),
last_verified_at: options.observed_at,
glass_version: options.glass_version,
verification_count: 0,
surface: options.surface,
backend: options.backend,
},
confidence: KnowledgeConfidence::Observed,
invalidation: KnowledgeInvalidation {
max_age_seconds: Some(604_800),
required_landmarks: required_landmarks.into_iter().collect(),
},
data: json!({
"pageKind": page_kind,
"regionKinds": region_kinds,
}),
portability: options.portability,
memory_influence: KnowledgeMemoryInfluence::default(),
retrieval: KnowledgeRetrievalExplanation {
current_validation: options.current_validation,
..KnowledgeRetrievalExplanation::default()
},
history: Vec::new(),
};
record.validate()?;
Ok(record)
}
pub fn from_verified_observation(
observation: &SemanticObservation,
mut options: KnowledgeRecordBuildOptions,
evidence: &KnowledgeVerifiedWorkflowEvidence,
) -> Result<Self, KnowledgeValidationError> {
observation.validate().map_err(|error| {
KnowledgeValidationError::new("observation", format!("invalid observation: {error}"))
})?;
evidence.validate_against(observation)?;
if observation.limits.truncated {
return Err(KnowledgeValidationError::new(
"observation.limits",
"verified learning requires complete observation evidence",
));
}
if observation_contains_sensitive_data(observation)? {
return Err(KnowledgeValidationError::new(
"observation",
"sensitive fields are not eligible for persistent knowledge",
));
}
options.current_validation = KnowledgeCurrentValidation {
status: KnowledgeCurrentValidationStatus::Validated,
evidence_quality: evidence.evidence_quality,
current_revision: Some(evidence.guarded_revision),
validated_at: Some(evidence.observed_at.clone()),
};
let mut record = Self::from_page_observation(observation, options)?;
record.confidence = KnowledgeConfidence::Candidate;
record.source.verification_count = 1;
record.data["verifiedUseKey"] = Value::String(evidence.compatibility_key.clone());
record.validate()?;
Ok(record)
}
pub fn deterministic_page_family_id(
observation: &SemanticObservation,
scope: &KnowledgeScope,
) -> Result<String, KnowledgeValidationError> {
let page_kind = serde_json::to_string(&observation.page.kind).map_err(|error| {
KnowledgeValidationError::new("observation.page.kind", error.to_string())
})?;
let digest = hash_knowledge_identity(&[
&scope.origin,
&scope.path_pattern,
&scope.browser_family,
&scope.policy_preset,
&page_kind,
]);
Ok(format!("page-family-{digest}"))
}
pub fn from_intent_candidate(
candidate: &SemanticIntentCandidate,
options: KnowledgeRecordBuildOptions,
) -> Result<Self, KnowledgeValidationError> {
let fingerprint = candidate.fingerprint.as_ref().ok_or_else(|| {
KnowledgeValidationError::new(
"candidate.fingerprint",
"fresh intent candidates require a target fingerprint",
)
})?;
validate_text("recordId", &options.record_id, MAX_RECORD_ID_BYTES, false)?;
validate_text(
"source.glassVersion",
&options.glass_version,
MAX_SCOPE_VALUE_BYTES,
false,
)?;
validate_timestamp("source.observedAt", &options.observed_at)?;
validate_scope(&options.scope)?;
validate_text("candidate.role", &candidate.role, MAX_ROLE_BYTES, false)?;
let digest = target_fingerprint_digest(
&candidate.role,
&candidate.name,
candidate.input_type.as_deref(),
candidate.region_kind,
fingerprint.purpose,
);
let required_landmarks = candidate
.region_kind
.map(|kind| serde_json::to_string(&kind).unwrap_or_default())
.into_iter()
.map(|landmark| landmark.trim_matches('"').to_string())
.collect();
let record = Self {
schema_version: KNOWLEDGE_SCHEMA_VERSION,
record_id: options.record_id,
kind: KnowledgeRecordKind::TargetFingerprint,
scope: options.scope,
source: KnowledgeSource {
first_seen_at: options.observed_at.clone(),
last_verified_at: options.observed_at,
glass_version: options.glass_version,
verification_count: 0,
surface: options.surface,
backend: options.backend,
},
confidence: KnowledgeConfidence::Observed,
invalidation: KnowledgeInvalidation {
max_age_seconds: Some(604_800),
required_landmarks,
},
data: json!({
"fingerprint": digest,
"role": candidate.role,
"regionKind": candidate.region_kind,
"purpose": fingerprint.purpose,
}),
portability: options.portability,
memory_influence: KnowledgeMemoryInfluence::default(),
retrieval: KnowledgeRetrievalExplanation {
current_validation: options.current_validation,
..KnowledgeRetrievalExplanation::default()
},
history: Vec::new(),
};
record.validate()?;
Ok(record)
}
pub fn from_workflow_definition(
workflow: &super::WorkflowDefinition,
options: KnowledgeRecordBuildOptions,
) -> Result<Self, KnowledgeValidationError> {
workflow.validate().map_err(|error| {
KnowledgeValidationError::new("workflow", format!("invalid workflow: {error}"))
})?;
validate_text("recordId", &options.record_id, MAX_RECORD_ID_BYTES, false)?;
validate_text(
"source.glassVersion",
&options.glass_version,
MAX_SCOPE_VALUE_BYTES,
false,
)?;
validate_timestamp("source.observedAt", &options.observed_at)?;
validate_scope(&options.scope)?;
let workflow_hash = hash_knowledge_identity(&[&workflow.name, &workflow.workflow_version]);
let step_hashes: Vec<String> = workflow
.steps
.iter()
.map(|step| hash_knowledge_identity(&[&step.id]))
.collect();
let output_hashes: Vec<String> = workflow
.outputs
.keys()
.map(|key| hash_knowledge_identity(&[key]))
.collect();
let record = Self {
schema_version: KNOWLEDGE_SCHEMA_VERSION,
record_id: options.record_id,
kind: KnowledgeRecordKind::WorkflowEntryPoint,
scope: options.scope,
source: KnowledgeSource {
first_seen_at: options.observed_at.clone(),
last_verified_at: options.observed_at,
glass_version: options.glass_version,
verification_count: 0,
surface: options.surface,
backend: options.backend,
},
confidence: KnowledgeConfidence::Candidate,
invalidation: KnowledgeInvalidation {
max_age_seconds: Some(604_800),
required_landmarks: Vec::new(),
},
data: json!({
"workflowHash": workflow_hash,
"stepHashes": step_hashes,
"outputHashes": output_hashes,
"stepCount": workflow.steps.len(),
"intentStepCount": workflow.steps.iter().filter(|step| step.intent.is_some()).count(),
"postconditionCount": workflow.steps.iter().filter(|step| step.expect.is_some()).count() + 1,
}),
portability: options.portability,
memory_influence: KnowledgeMemoryInfluence::default(),
retrieval: KnowledgeRetrievalExplanation {
current_validation: options.current_validation,
..KnowledgeRetrievalExplanation::default()
},
history: Vec::new(),
};
record.validate()?;
Ok(record)
}
pub fn with_provenance(
mut self,
surface: KnowledgeSurfaceProvenance,
backend: KnowledgeBackendProvenance,
portability: KnowledgePortability,
) -> Result<Self, KnowledgeValidationError> {
self.source.surface = surface;
self.source.backend = backend;
self.portability = portability;
self.validate()?;
Ok(self)
}
pub fn with_current_validation(
mut self,
current_revision: u64,
evidence_quality: KnowledgeEvidenceQuality,
validated_at: String,
) -> Result<Self, KnowledgeValidationError> {
if current_revision == 0 {
return Err(KnowledgeValidationError::new(
"currentRevision",
"must be positive",
));
}
if evidence_quality == KnowledgeEvidenceQuality::None {
return Err(KnowledgeValidationError::new(
"evidenceQuality",
"must identify a current evidence quality",
));
}
validate_timestamp("validatedAt", &validated_at)?;
self.retrieval.current_validation = KnowledgeCurrentValidation {
status: KnowledgeCurrentValidationStatus::Validated,
evidence_quality,
current_revision: Some(current_revision),
validated_at: Some(validated_at),
};
self.validate()?;
Ok(self)
}
pub fn validate(&self) -> Result<(), KnowledgeValidationError> {
if self.schema_version != KNOWLEDGE_SCHEMA_VERSION {
return Err(KnowledgeValidationError::new(
"schemaVersion",
format!(
"unsupported schema version {}; expected {}",
self.schema_version, KNOWLEDGE_SCHEMA_VERSION
),
));
}
validate_text("recordId", &self.record_id, MAX_RECORD_ID_BYTES, false)?;
validate_scope(&self.scope)?;
validate_source(&self.source)?;
validate_retrieval(&self.retrieval)?;
if self.memory_influence != KnowledgeMemoryInfluence::None {
if self.retrieval.signals.is_empty() {
return Err(KnowledgeValidationError::new(
"memoryInfluence",
"memory influence requires retrieval signals",
));
}
if self.retrieval.current_validation.status
!= KnowledgeCurrentValidationStatus::Validated
{
return Err(KnowledgeValidationError::new(
"memoryInfluence",
"memory influence requires current validation",
));
}
}
if (matches!(
self.source.surface.kind,
KnowledgeSurfaceKind::Opaque | KnowledgeSurfaceKind::Unknown
) || self.source.backend.backend == KnowledgeBackendKind::Unknown)
&& self.portability != KnowledgePortability::NonPortable
{
return Err(KnowledgeValidationError::new(
"portability",
"opaque or unknown provenance is nonPortable",
));
}
validate_invalidation(&self.invalidation)?;
if self.history.len() > MAX_HISTORY {
return Err(KnowledgeValidationError::new(
"history",
format!("contains more than {MAX_HISTORY} events"),
));
}
for (index, event) in self.history.iter().enumerate() {
validate_text(
&format!("history[{index}].reason"),
&event.reason,
MAX_SCOPE_VALUE_BYTES,
false,
)?;
validate_timestamp(&format!("history[{index}].observedAt"), &event.observed_at)?;
}
if !matches!(self.data, Value::Object(_) | Value::Array(_)) {
return Err(KnowledgeValidationError::new(
"data",
"must be a JSON object or array",
));
}
validate_json_value("data", &self.data, 0)?;
let data_bytes = serde_json::to_vec(&self.data).map_err(|error| {
KnowledgeValidationError::new("data", format!("cannot serialize data: {error}"))
})?;
if data_bytes.len() > MAX_DATA_BYTES {
return Err(KnowledgeValidationError::new(
"data",
format!("exceeds the {MAX_DATA_BYTES}-byte limit"),
));
}
let record_bytes = serde_json::to_vec(self).map_err(|error| {
KnowledgeValidationError::new("$", format!("cannot serialize record: {error}"))
})?;
if record_bytes.len() > MAX_RECORD_BYTES {
return Err(KnowledgeValidationError::new(
"$",
format!("record exceeds the {MAX_RECORD_BYTES}-byte limit"),
));
}
Ok(())
}
pub fn to_canonical_json(&self) -> Result<String, KnowledgeValidationError> {
self.validate()?;
serde_json::to_string(self)
.map_err(|error| KnowledgeValidationError::new("$", error.to_string()))
}
pub fn content_hash(&self) -> Result<String, KnowledgeValidationError> {
let canonical = self.to_canonical_json()?;
let digest = Sha256::digest(canonical.as_bytes());
Ok(format!("sha256:{digest:x}"))
}
pub fn assess(&self, context: &KnowledgeLookupContext) -> KnowledgeAssessment {
let mut signals = Vec::new();
let mut conflicts = Vec::new();
let mut missing_landmarks = Vec::new();
if self.scope.origin == context.origin {
signals.push(signal(KnowledgeSignalKind::OriginMatch, "origin matches"));
} else {
conflicts.push("origin does not match".into());
}
if path_matches(&self.scope.path_pattern, &context.path) {
signals.push(signal(
KnowledgeSignalKind::PathMatch,
"path pattern matches",
));
} else {
conflicts.push("path is outside the record pattern".into());
}
if self.scope.profile_scope == context.profile_scope
&& self.scope.profile_key == context.profile_key
{
signals.push(signal(
KnowledgeSignalKind::ProfileScopeMatch,
"profile scope matches",
));
} else {
conflicts.push("profile scope does not match".into());
}
if context.workspace_id.is_none() {
if self.scope.workspace_id.is_none() {
signals.push(signal(
KnowledgeSignalKind::WorkspaceMatch,
"legacy workspace-unbound scope is allowed without live workspace binding",
));
} else {
conflicts.push("record is workspace-bound but context is not".into());
}
} else if self.scope.workspace_id == context.workspace_id
&& self.scope.workspace_generation == context.workspace_generation
{
signals.push(signal(
KnowledgeSignalKind::WorkspaceMatch,
"workspace identity and generation match",
));
} else if self.scope.workspace_id.is_none() {
conflicts.push("record has no workspace identity for the live context".into());
} else if self.scope.workspace_id != context.workspace_id {
conflicts.push("workspace identity does not match".into());
} else {
conflicts.push("workspace generation does not match".into());
}
compare_optional_scope(
&mut signals,
&mut conflicts,
KnowledgeSignalKind::LocaleMatch,
"locale",
&self.scope.locale,
&context.locale,
);
compare_optional_scope(
&mut signals,
&mut conflicts,
KnowledgeSignalKind::TenantMatch,
"tenant",
&self.scope.tenant_key,
&context.tenant_key,
);
if self.scope.browser_family == context.browser_family
&& browser_version_matches(
self.scope.browser_version_range.as_deref(),
context.browser_version.as_deref(),
)
{
signals.push(signal(
KnowledgeSignalKind::BrowserMatch,
"browser scope matches",
));
} else {
conflicts.push("browser family or version does not match".into());
}
if self.scope.glass_schema_version == context.glass_schema_version {
signals.push(signal(
KnowledgeSignalKind::SchemaMatch,
"schema scope matches",
));
} else {
conflicts.push("Glass schema scope does not match".into());
}
if self.scope.policy_preset == context.policy_preset {
signals.push(signal(
KnowledgeSignalKind::PolicyMatch,
"policy scope matches",
));
} else {
conflicts.push("policy scope does not match".into());
}
for required in &self.invalidation.required_landmarks {
if context.landmarks.iter().any(|current| current == required) {
signals.push(signal(
KnowledgeSignalKind::LandmarkMatch,
format!("landmark {required} is present"),
));
} else {
missing_landmarks.push(required.clone());
}
}
let age_seconds =
parse_age_seconds(&self.source.last_verified_at, context.now_epoch_seconds);
if let Some(age) = age_seconds {
if self
.invalidation
.max_age_seconds
.is_none_or(|maximum| age <= maximum as i64)
{
signals.push(signal(
KnowledgeSignalKind::FreshnessMatch,
format!("record age is {age} seconds"),
));
} else {
conflicts.push("record exceeded its maximum age".into());
}
} else {
conflicts.push("lastVerifiedAt is not a valid RFC3339 timestamp".into());
}
let current_contradiction = self.retrieval.current_validation.status
== KnowledgeCurrentValidationStatus::Contradicted;
let current_validation_conflict =
self.retrieval.current_validation.status != KnowledgeCurrentValidationStatus::Validated;
let current_revision_conflict =
self.retrieval.current_validation.current_revision != Some(context.current_revision);
if current_contradiction {
conflicts.push("current validation contradicts live Web IR".into());
} else if current_validation_conflict {
conflicts.push("record lacks current Web IR validation".into());
} else if current_revision_conflict {
conflicts.push("current Web IR revision does not match".into());
}
if self.confidence == KnowledgeConfidence::Stale {
conflicts.push("record lifecycle is stale".into());
} else if self.confidence == KnowledgeConfidence::Contradicted {
conflicts.push("record lifecycle is contradicted".into());
}
let record_extension = self.source.surface.kind == KnowledgeSurfaceKind::ExtensionDefined;
let context_extension =
context.surface_kind == Some(KnowledgeSurfaceKind::ExtensionDefined);
let extension_conflict = record_extension != context_extension
|| (record_extension
&& self.source.surface.extension_id.as_ref()
!= context.current_extension_id.as_ref());
if extension_conflict {
conflicts.push("extension provenance does not match".into());
}
let provenance_conflict = matches!(
self.source.surface.kind,
KnowledgeSurfaceKind::Opaque | KnowledgeSurfaceKind::Unknown
) || self.source.surface.understanding
== KnowledgeUnderstandingLevel::Opaque
|| self.source.surface.coverage == KnowledgeSurfaceCoverage::None
|| self.source.backend.backend == KnowledgeBackendKind::Unknown;
if provenance_conflict {
conflicts.push("surface or backend provenance is unknown".into());
}
let surface_conflict = self.portability == KnowledgePortability::SurfacePortable
&& context.surface_kind != Some(self.source.surface.kind);
let backend_conflict = match self.portability {
KnowledgePortability::BackendCapabilityDependent => {
context.backend_kind != Some(self.source.backend.backend)
|| self
.source
.backend
.capabilities
.iter()
.any(|capability| !context.backend_capabilities.contains(capability))
}
KnowledgePortability::BackendSpecific | KnowledgePortability::BrowserSpecific => {
context.backend_kind != Some(self.source.backend.backend)
}
_ => false,
};
let portability_conflict = self.portability == KnowledgePortability::NonPortable
|| surface_conflict
|| backend_conflict;
if portability_conflict {
conflicts.push(
if surface_conflict {
"record surface provenance is incompatible with this context"
} else if backend_conflict {
"record backend provenance is incompatible with this context"
} else {
"record portability is incompatible with this context"
}
.into(),
);
}
let scope_conflict = conflicts.iter().any(|conflict| {
matches!(
conflict.as_str(),
"origin does not match"
| "path is outside the record pattern"
| "profile scope does not match"
| "workspace identity does not match"
| "workspace generation does not match"
| "record has no workspace identity for the live context"
| "record is workspace-bound but context is not"
| "locale does not match"
| "tenant does not match"
| "browser family or version does not match"
| "Glass schema scope does not match"
| "policy scope does not match"
)
});
let status =
if current_contradiction || self.confidence == KnowledgeConfidence::Contradicted {
KnowledgeAssessmentStatus::Contradicted
} else if self.confidence == KnowledgeConfidence::Quarantined {
KnowledgeAssessmentStatus::Quarantined
} else if scope_conflict {
KnowledgeAssessmentStatus::OutOfScope
} else if current_validation_conflict
|| current_revision_conflict
|| extension_conflict
|| provenance_conflict
|| portability_conflict
|| !missing_landmarks.is_empty()
|| age_seconds.is_none()
|| self.confidence == KnowledgeConfidence::Stale
|| self
.invalidation
.max_age_seconds
.is_some_and(|maximum| age_seconds.is_some_and(|age| age > maximum as i64))
{
KnowledgeAssessmentStatus::Stale
} else {
KnowledgeAssessmentStatus::Eligible
};
KnowledgeAssessment {
record_id: self.record_id.clone(),
status,
signals,
conflicts,
missing_landmarks,
age_seconds,
}
}
pub fn retrieve_candidate(
&self,
context: &KnowledgeLookupContext,
query: &KnowledgeRetrievalQuery,
) -> KnowledgeRetrievalCandidate {
let assessment = self.assess(context);
if assessment.status != KnowledgeAssessmentStatus::Eligible {
return KnowledgeRetrievalCandidate {
record_id: self.record_id.clone(),
selected: false,
signals: Vec::new(),
rejection: Some(rejection_reason(&assessment)),
explanation: Some(assessment.conflicts.join("; ")),
current_validation: self.retrieval.current_validation.clone(),
portability: self.portability,
surface_kind: self.source.surface.kind,
backend_kind: self.source.backend.backend,
};
}
let mut provenance = vec![
KnowledgeRetrievalSignal {
kind: KnowledgeRetrievalSignalKind::OriginMatch,
detail: "current origin matches".into(),
score_millis: Some(300),
},
KnowledgeRetrievalSignal {
kind: KnowledgeRetrievalSignalKind::Freshness,
detail: "record passed current freshness validation".into(),
score_millis: Some(200),
},
];
if context.surface_kind == Some(self.source.surface.kind) {
provenance.push(KnowledgeRetrievalSignal {
kind: KnowledgeRetrievalSignalKind::SurfaceMatch,
detail: "surface provenance matches".into(),
score_millis: Some(350),
});
}
if context.backend_kind == Some(self.source.backend.backend) {
provenance.push(KnowledgeRetrievalSignal {
kind: KnowledgeRetrievalSignalKind::BackendMatch,
detail: "backend provenance matches".into(),
score_millis: Some(350),
});
}
let mut signals = Vec::new();
let page_kind = self.data.get("pageKind").and_then(Value::as_str);
let page_kind_mismatch = self.kind == KnowledgeRecordKind::PageFamily
&& query.page_kind.as_deref().is_some_and(|expected| {
page_kind.is_some_and(|actual| {
normalized_knowledge_value(actual) != normalized_knowledge_value(expected)
})
});
if page_kind_mismatch {
return KnowledgeRetrievalCandidate {
record_id: self.record_id.clone(),
selected: false,
signals: Vec::new(),
rejection: Some(KnowledgeRejectionReason::Contradicted),
explanation: Some("current page family contradicts live Web IR".into()),
current_validation: self.retrieval.current_validation.clone(),
portability: self.portability,
surface_kind: self.source.surface.kind,
backend_kind: self.source.backend.backend,
};
}
if query.page_kind.as_deref().is_some_and(|expected| {
page_kind.is_some_and(|actual| {
normalized_knowledge_value(actual) == normalized_knowledge_value(expected)
})
}) {
signals.push(KnowledgeRetrievalSignal {
kind: KnowledgeRetrievalSignalKind::ExactPageFamilyMatch,
detail: "current page family matches".into(),
score_millis: Some(1_000),
});
}
if query.landmarks.iter().any(|landmark| {
self.invalidation.required_landmarks.iter().any(|required| {
normalized_knowledge_value(required) == normalized_knowledge_value(landmark)
})
}) {
signals.push(KnowledgeRetrievalSignal {
kind: KnowledgeRetrievalSignalKind::GraphDistance,
detail: "current landmark is connected to the record".into(),
score_millis: Some(600),
});
}
if let Some(role) = self.data.get("role").and_then(Value::as_str)
&& query.entity_roles.iter().any(|expected| {
normalized_knowledge_value(role) == normalized_knowledge_value(expected)
})
{
signals.push(KnowledgeRetrievalSignal {
kind: KnowledgeRetrievalSignalKind::ExactFingerprintMatch,
detail: "current entity role matches remembered fingerprint".into(),
score_millis: Some(900),
});
}
if self.kind == KnowledgeRecordKind::WorkflowEntryPoint
&& query.task_kind.is_some()
&& !signals.is_empty()
{
signals.push(KnowledgeRetrievalSignal {
kind: KnowledgeRetrievalSignalKind::GraphDistance,
detail: "workflow entry is graph-compatible with the task".into(),
score_millis: Some(450),
});
}
if signals.is_empty() {
return KnowledgeRetrievalCandidate {
record_id: self.record_id.clone(),
selected: false,
signals: provenance,
rejection: Some(KnowledgeRejectionReason::NoExactOrGraphMatch),
explanation: Some("no exact or graph-compatible semantic match".into()),
current_validation: self.retrieval.current_validation.clone(),
portability: self.portability,
surface_kind: self.source.surface.kind,
backend_kind: self.source.backend.backend,
};
}
signals.extend(provenance);
KnowledgeRetrievalCandidate {
record_id: self.record_id.clone(),
selected: false,
signals,
rejection: None,
explanation: None,
current_validation: self.retrieval.current_validation.clone(),
portability: self.portability,
surface_kind: self.source.surface.kind,
backend_kind: self.source.backend.backend,
}
}
pub fn transition_with_validation(
&mut self,
next: KnowledgeConfidence,
reason: String,
observed_at: String,
current_revision: u64,
evidence_quality: KnowledgeEvidenceQuality,
) -> Result<(), KnowledgeValidationError> {
if current_revision == 0 {
return Err(KnowledgeValidationError::new(
"currentRevision",
"must be positive",
));
}
if evidence_quality == KnowledgeEvidenceQuality::None {
return Err(KnowledgeValidationError::new(
"evidenceQuality",
"must identify a current evidence quality",
));
}
let previous = self.retrieval.current_validation.clone();
self.retrieval.current_validation = KnowledgeCurrentValidation {
status: KnowledgeCurrentValidationStatus::Validated,
evidence_quality,
current_revision: Some(current_revision),
validated_at: Some(observed_at.clone()),
};
let result = self.transition(next, reason, observed_at, true);
if result.is_err() {
self.retrieval.current_validation = previous;
}
result
}
pub fn transition(
&mut self,
next: KnowledgeConfidence,
reason: String,
observed_at: String,
fresh_verification: bool,
) -> Result<(), KnowledgeValidationError> {
let mut candidate = self.clone();
candidate.transition_in_place(next, reason, observed_at, fresh_verification)?;
*self = candidate;
Ok(())
}
fn transition_in_place(
&mut self,
next: KnowledgeConfidence,
reason: String,
observed_at: String,
fresh_verification: bool,
) -> Result<(), KnowledgeValidationError> {
validate_text("reason", &reason, MAX_SCOPE_VALUE_BYTES, false)?;
validate_text("observedAt", &observed_at, MAX_TIMESTAMP_BYTES, false)?;
validate_timestamp("observedAt", &observed_at)?;
if self.confidence == next {
if fresh_verification {
self.source.last_verified_at = observed_at.clone();
self.source.verification_count = self.source.verification_count.saturating_add(1);
self.validate()?;
}
return Ok(());
}
let requires_fresh = matches!(
next,
KnowledgeConfidence::Verified | KnowledgeConfidence::Observed
) || matches!(
self.confidence,
KnowledgeConfidence::Contradicted | KnowledgeConfidence::Quarantined
);
if requires_fresh && !fresh_verification {
return Err(KnowledgeValidationError::new(
"freshVerification",
"this lifecycle transition requires fresh browser verification",
));
}
if next == KnowledgeConfidence::Verified
&& self.retrieval.current_validation.status
!= KnowledgeCurrentValidationStatus::Validated
{
return Err(KnowledgeValidationError::new(
"currentValidation",
"verified promotion requires a current Web IR witness",
));
}
if self.history.len() >= MAX_HISTORY {
return Err(KnowledgeValidationError::new(
"history",
format!("cannot append beyond {MAX_HISTORY} events"),
));
}
let event = KnowledgeLifecycleEvent {
from: self.confidence,
to: next,
reason,
observed_at: observed_at.clone(),
};
self.confidence = next;
if fresh_verification {
self.source.last_verified_at = observed_at.clone();
self.source.verification_count = self.source.verification_count.saturating_add(1);
}
if next == KnowledgeConfidence::Stale {
self.invalidate_current_validation(KnowledgeCurrentValidationStatus::Stale);
} else if matches!(
next,
KnowledgeConfidence::Contradicted | KnowledgeConfidence::Quarantined
) {
self.invalidate_current_validation(KnowledgeCurrentValidationStatus::Contradicted);
}
self.history.push(event);
self.validate()
}
fn invalidate_current_validation(&mut self, status: KnowledgeCurrentValidationStatus) {
self.retrieval.current_validation = KnowledgeCurrentValidation {
status,
evidence_quality: KnowledgeEvidenceQuality::None,
current_revision: None,
validated_at: None,
};
}
}
fn observation_contains_sensitive_data(
observation: &SemanticObservation,
) -> Result<bool, KnowledgeValidationError> {
let value = serde_json::to_value(observation).map_err(|error| {
KnowledgeValidationError::new(
"observation",
format!("cannot inspect observation: {error}"),
)
})?;
fn walk(value: &Value) -> bool {
match value {
Value::String(text) => {
let normalized = text
.chars()
.filter(char::is_ascii_alphanumeric)
.collect::<String>()
.to_ascii_lowercase();
[
"authorization",
"cookie",
"credential",
"password",
"secret",
"token",
]
.iter()
.any(|word| normalized.contains(word))
}
Value::Array(values) => values.iter().any(walk),
Value::Object(values) => values.iter().any(|(key, value)| {
let normalized = key
.chars()
.filter(char::is_ascii_alphanumeric)
.collect::<String>()
.to_ascii_lowercase();
[
"authorization",
"cookie",
"credential",
"password",
"secret",
"token",
]
.iter()
.any(|word| normalized.contains(word))
|| walk(value)
}),
Value::Null | Value::Bool(_) | Value::Number(_) => false,
}
}
Ok(walk(&value))
}
fn normalized_knowledge_value(value: &str) -> String {
value
.chars()
.filter(|character| character.is_ascii_alphanumeric())
.flat_map(char::to_lowercase)
.collect()
}
fn rejection_reason(assessment: &KnowledgeAssessment) -> KnowledgeRejectionReason {
match assessment.status {
KnowledgeAssessmentStatus::Contradicted => {
let joined = assessment.conflicts.join(" ").to_ascii_lowercase();
if joined.contains("current validation") {
KnowledgeRejectionReason::Contradicted
} else {
KnowledgeRejectionReason::ContradictedLifecycle
}
}
KnowledgeAssessmentStatus::Quarantined => KnowledgeRejectionReason::Quarantined,
KnowledgeAssessmentStatus::OutOfScope => {
let joined = assessment.conflicts.join(" ").to_ascii_lowercase();
if joined.contains("workspace generation") {
KnowledgeRejectionReason::WorkspaceGenerationMismatch
} else if joined.contains("workspace") {
if joined.contains("no workspace identity") {
KnowledgeRejectionReason::LegacyWorkspaceUnbound
} else {
KnowledgeRejectionReason::WorkspaceMismatch
}
} else {
KnowledgeRejectionReason::OutOfScope
}
}
KnowledgeAssessmentStatus::Stale => {
let joined = assessment.conflicts.join(" ").to_ascii_lowercase();
if joined.contains("record lifecycle is stale") {
KnowledgeRejectionReason::StaleLifecycle
} else if joined.contains("unknown") || joined.contains("opaque") {
KnowledgeRejectionReason::OpaqueProvenance
} else if joined.contains("extension") {
KnowledgeRejectionReason::ExtensionMismatch
} else if joined.contains("backend") {
KnowledgeRejectionReason::BackendIncompatible
} else if joined.contains("surface provenance") || joined.contains("portability") {
KnowledgeRejectionReason::SurfaceIncompatible
} else if joined.contains("current web ir") {
KnowledgeRejectionReason::CurrentValidationMissing
} else {
KnowledgeRejectionReason::Stale
}
}
KnowledgeAssessmentStatus::Eligible => KnowledgeRejectionReason::NoExactOrGraphMatch,
}
}
fn signal(kind: KnowledgeSignalKind, detail: impl Into<String>) -> KnowledgeAssessmentSignal {
KnowledgeAssessmentSignal {
kind,
detail: detail.into(),
}
}
fn hash_knowledge_identity(parts: &[&str]) -> String {
let canonical = serde_json::to_vec(parts).expect("JSON string arrays are serializable");
let digest = Sha256::digest(canonical);
format!("sha256:{digest:x}")
}
fn compare_optional_scope(
signals: &mut Vec<KnowledgeAssessmentSignal>,
conflicts: &mut Vec<String>,
kind: KnowledgeSignalKind,
label: &str,
expected: &Option<String>,
actual: &Option<String>,
) {
if expected
.as_ref()
.is_none_or(|expected| Some(expected) == actual.as_ref())
{
signals.push(signal(kind, format!("{label} scope matches")));
} else {
conflicts.push(format!("{label} does not match"));
}
}
fn browser_version_matches(expected_range: Option<&str>, actual: Option<&str>) -> bool {
match (expected_range, actual) {
(None, _) => true,
(Some(expected), Some(actual)) => {
if expected == actual || expected == ">=current" {
return true;
}
let (operator, expected_version) = [">=", "<=", ">", "<", "="]
.iter()
.find_map(|operator| {
expected
.strip_prefix(operator)
.map(|version| (*operator, version))
})
.unwrap_or(("=", expected));
let Some(expected_major) = version_major(expected_version) else {
return false;
};
let Some(actual_major) = version_major(actual) else {
return false;
};
match operator {
">=" => actual_major >= expected_major,
"<=" => actual_major <= expected_major,
">" => actual_major > expected_major,
"<" => actual_major < expected_major,
"=" => actual_major == expected_major,
_ => false,
}
}
(Some(_), None) => false,
}
}
fn version_major(value: &str) -> Option<u64> {
value
.trim()
.split_once('.')
.map_or(value.trim(), |(major, _)| major)
.parse()
.ok()
}
fn parse_age_seconds(last_verified_at: &str, now_epoch_seconds: i64) -> Option<i64> {
let timestamp = chrono::DateTime::parse_from_rfc3339(last_verified_at).ok()?;
Some(
now_epoch_seconds
.saturating_sub(timestamp.timestamp())
.max(0),
)
}
fn path_matches(pattern: &str, path: &str) -> bool {
if pattern == path {
return true;
}
let Some(prefix) = pattern.strip_suffix('*') else {
return false;
};
path.starts_with(prefix)
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct KnowledgeStoreSnapshot {
pub schema_version: u32,
pub records: Vec<KnowledgeRecord>,
}
impl KnowledgeStoreSnapshot {
pub fn validate(&self) -> Result<(), KnowledgeValidationError> {
if self.schema_version != KNOWLEDGE_SCHEMA_VERSION {
return Err(KnowledgeValidationError::new(
"schemaVersion",
format!(
"unsupported schema version {}; expected {}",
self.schema_version, KNOWLEDGE_SCHEMA_VERSION
),
));
}
if self.records.len() > MAX_KNOWLEDGE_RECORDS {
return Err(KnowledgeValidationError::new(
"records",
format!("contains more than {MAX_KNOWLEDGE_RECORDS} records"),
));
}
let mut record_ids = BTreeSet::new();
for (index, record) in self.records.iter().enumerate() {
record.validate().map_err(|error| error.at(index))?;
if !record_ids.insert(record.record_id.as_str()) {
return Err(KnowledgeValidationError::new(
format!("records[{index}].recordId"),
"record ID is duplicated",
));
}
}
Ok(())
}
pub fn to_canonical_json(&self) -> Result<String, KnowledgeValidationError> {
self.validate()?;
serde_json::to_string(self)
.map_err(|error| KnowledgeValidationError::new("$", error.to_string()))
}
}
fn validate_source(source: &KnowledgeSource) -> Result<(), KnowledgeValidationError> {
validate_timestamp("source.firstSeenAt", &source.first_seen_at)?;
validate_timestamp("source.lastVerifiedAt", &source.last_verified_at)?;
validate_text(
"source.glassVersion",
&source.glass_version,
MAX_SCOPE_VALUE_BYTES,
false,
)?;
validate_surface_provenance(&source.surface)?;
validate_backend_provenance(&source.backend)
}
fn validate_scope(scope: &KnowledgeScope) -> Result<(), KnowledgeValidationError> {
validate_text("scope.origin", &scope.origin, 2048, false)?;
validate_text("scope.pathPattern", &scope.path_pattern, 512, false)?;
validate_text(
"scope.browserFamily",
&scope.browser_family,
MAX_SCOPE_VALUE_BYTES,
false,
)?;
validate_text(
"scope.policyPreset",
&scope.policy_preset,
MAX_SCOPE_VALUE_BYTES,
false,
)?;
if scope.glass_schema_version == 0 {
return Err(KnowledgeValidationError::new(
"scope.glassSchemaVersion",
"must be positive",
));
}
validate_workspace_scope(
"scope.workspaceId",
scope.workspace_id.as_deref(),
scope.workspace_generation,
)?;
for (path, value) in [
("scope.profileKey", scope.profile_key.as_deref()),
("scope.locale", scope.locale.as_deref()),
("scope.tenantKey", scope.tenant_key.as_deref()),
(
"scope.browserVersionRange",
scope.browser_version_range.as_deref(),
),
] {
if let Some(value) = value {
validate_text(path, value, MAX_SCOPE_VALUE_BYTES, false)?;
}
}
match scope.profile_scope {
KnowledgeProfileScope::ProfileBound if scope.profile_key.is_none() => {
Err(KnowledgeValidationError::new(
"scope.profileKey",
"is required for profileBound knowledge",
))
}
KnowledgeProfileScope::Anonymous if scope.profile_key.is_some() => {
Err(KnowledgeValidationError::new(
"scope.profileKey",
"must be absent for anonymous knowledge",
))
}
_ => Ok(()),
}
}
fn validate_workspace_scope(
path: &str,
workspace_id: Option<&str>,
workspace_generation: Option<u64>,
) -> Result<(), KnowledgeValidationError> {
if let Some(workspace_id) = workspace_id {
validate_text(path, workspace_id, MAX_WORKSPACE_ID_BYTES, false)?;
validate_public_text(path, workspace_id)?;
} else if workspace_generation.is_some() {
return Err(KnowledgeValidationError::new(
"workspaceGeneration",
"requires a workspace identity",
));
}
if workspace_generation == Some(0) {
return Err(KnowledgeValidationError::new(
"workspaceGeneration",
"must be positive",
));
}
Ok(())
}
fn validate_surface_provenance(
surface: &KnowledgeSurfaceProvenance,
) -> Result<(), KnowledgeValidationError> {
if surface.kind == KnowledgeSurfaceKind::ExtensionDefined && surface.extension_id.is_none() {
return Err(KnowledgeValidationError::new(
"source.surface.extensionId",
"extension-defined surfaces require a bounded extension identifier",
));
}
if surface.kind != KnowledgeSurfaceKind::ExtensionDefined && surface.extension_id.is_some() {
return Err(KnowledgeValidationError::new(
"source.surface.extensionId",
"extension identifiers are only valid for extension-defined surfaces",
));
}
if let Some(extension_id) = &surface.extension_id {
validate_text(
"source.surface.extensionId",
extension_id,
MAX_EXTENSION_ID_BYTES,
false,
)?;
validate_public_text("source.surface.extensionId", extension_id)?;
}
if surface.coverage == KnowledgeSurfaceCoverage::None
&& surface.understanding != KnowledgeUnderstandingLevel::Opaque
{
return Err(KnowledgeValidationError::new(
"source.surface.coverage",
"none coverage requires opaque understanding",
));
}
if matches!(
surface.kind,
KnowledgeSurfaceKind::Opaque | KnowledgeSurfaceKind::Unknown
) && surface.understanding != KnowledgeUnderstandingLevel::Opaque
{
return Err(KnowledgeValidationError::new(
"source.surface.understanding",
"opaque or unknown surfaces cannot claim understanding",
));
}
if surface.understanding == KnowledgeUnderstandingLevel::TaskCompilable
&& surface.coverage != KnowledgeSurfaceCoverage::Complete
{
return Err(KnowledgeValidationError::new(
"source.surface.coverage",
"task-compilable understanding requires complete coverage",
));
}
Ok(())
}
fn validate_backend_provenance(
backend: &KnowledgeBackendProvenance,
) -> Result<(), KnowledgeValidationError> {
validate_text(
"source.backend.profile",
&backend.profile,
MAX_SCOPE_VALUE_BYTES,
false,
)?;
validate_public_text("source.backend.profile", &backend.profile)?;
validate_backend_capabilities("source.backend.capabilities", &backend.capabilities)
}
fn validate_backend_capabilities(
path: &str,
capabilities: &[KnowledgeBackendCapability],
) -> Result<(), KnowledgeValidationError> {
if capabilities.len() > MAX_BACKEND_CAPABILITIES {
return Err(KnowledgeValidationError::new(
path,
format!("contains more than {MAX_BACKEND_CAPABILITIES} capabilities"),
));
}
let mut unique = BTreeSet::new();
for (index, capability) in capabilities.iter().enumerate() {
if !unique.insert(*capability) {
return Err(KnowledgeValidationError::new(
format!("{path}[{index}]"),
"capability is duplicated",
));
}
}
Ok(())
}
fn validate_retrieval(
retrieval: &KnowledgeRetrievalExplanation,
) -> Result<(), KnowledgeValidationError> {
if retrieval.signals.len() > MAX_RETRIEVAL_SIGNALS {
return Err(KnowledgeValidationError::new(
"retrieval.signals",
format!("contains more than {MAX_RETRIEVAL_SIGNALS} signals"),
));
}
for (index, signal) in retrieval.signals.iter().enumerate() {
validate_text(
&format!("retrieval.signals[{index}].detail"),
&signal.detail,
MAX_SCOPE_VALUE_BYTES,
false,
)?;
validate_public_text(
&format!("retrieval.signals[{index}].detail"),
&signal.detail,
)?;
if signal.score_millis.is_some_and(|score| score > 1_000) {
return Err(KnowledgeValidationError::new(
format!("retrieval.signals[{index}].scoreMillis"),
"must be between 0 and 1000",
));
}
}
let current = &retrieval.current_validation;
match current.status {
KnowledgeCurrentValidationStatus::Validated => {
if current.evidence_quality == KnowledgeEvidenceQuality::None {
return Err(KnowledgeValidationError::new(
"retrieval.currentValidation.evidenceQuality",
"validated evidence requires a quality",
));
}
if current
.current_revision
.is_none_or(|revision| revision == 0)
{
return Err(KnowledgeValidationError::new(
"retrieval.currentValidation.currentRevision",
"validated evidence requires a positive current revision witness",
));
}
let timestamp = current.validated_at.as_deref().ok_or_else(|| {
KnowledgeValidationError::new(
"retrieval.currentValidation.validatedAt",
"is required for validated evidence",
)
})?;
validate_timestamp("retrieval.currentValidation.validatedAt", timestamp)?;
}
KnowledgeCurrentValidationStatus::NotValidated => {
if current.current_revision.is_some() || current.validated_at.is_some() {
return Err(KnowledgeValidationError::new(
"retrieval.currentValidation",
"notValidated evidence cannot include revision or timestamp",
));
}
if current.evidence_quality != KnowledgeEvidenceQuality::None {
return Err(KnowledgeValidationError::new(
"retrieval.currentValidation.evidenceQuality",
"notValidated evidence must have none quality",
));
}
}
_ => {
if current.current_revision.is_some() || current.validated_at.is_some() {
return Err(KnowledgeValidationError::new(
"retrieval.currentValidation",
"invalidated evidence cannot retain a revision or timestamp",
));
}
if current.evidence_quality != KnowledgeEvidenceQuality::None {
return Err(KnowledgeValidationError::new(
"retrieval.currentValidation.evidenceQuality",
"invalidated evidence must have none quality",
));
}
}
}
Ok(())
}
fn validate_public_text(path: &str, value: &str) -> Result<(), KnowledgeValidationError> {
let normalized = value
.chars()
.filter(char::is_ascii_alphanumeric)
.collect::<String>()
.to_ascii_lowercase();
const FORBIDDEN: &[&str] = &[
"authorization",
"cookie",
"credential",
"password",
"secret",
"session",
"token",
];
if FORBIDDEN.iter().any(|word| normalized.contains(word)) {
return Err(KnowledgeValidationError::new(
path,
"sensitive value is not permitted in provenance",
));
}
Ok(())
}
fn validate_timestamp(path: &str, value: &str) -> Result<(), KnowledgeValidationError> {
validate_text(path, value, MAX_TIMESTAMP_BYTES, false)?;
chrono::DateTime::parse_from_rfc3339(value).map_err(|error| {
KnowledgeValidationError::new(path, format!("must be RFC3339: {error}"))
})?;
Ok(())
}
fn validate_invalidation(
invalidation: &KnowledgeInvalidation,
) -> Result<(), KnowledgeValidationError> {
if invalidation.required_landmarks.len() > MAX_LANDMARKS {
return Err(KnowledgeValidationError::new(
"invalidation.requiredLandmarks",
format!("contains more than {MAX_LANDMARKS} landmarks"),
));
}
let mut landmarks = BTreeSet::new();
for (index, landmark) in invalidation.required_landmarks.iter().enumerate() {
validate_text(
&format!("invalidation.requiredLandmarks[{index}]"),
landmark,
MAX_SCOPE_VALUE_BYTES,
false,
)?;
if !landmarks.insert(landmark) {
return Err(KnowledgeValidationError::new(
format!("invalidation.requiredLandmarks[{index}]"),
"landmark is duplicated",
));
}
}
Ok(())
}
fn validate_json_value(
path: &str,
value: &Value,
depth: usize,
) -> Result<(), KnowledgeValidationError> {
if depth > MAX_JSON_DEPTH {
return Err(KnowledgeValidationError::new(
path,
format!("exceeds the {MAX_JSON_DEPTH}-level nesting limit"),
));
}
match value {
Value::Null | Value::Bool(_) | Value::Number(_) => Ok(()),
Value::String(value) => validate_text(path, value, MAX_JSON_STRING_BYTES, true),
Value::Array(values) => {
if values.len() > MAX_JSON_ARRAY_ENTRIES {
return Err(KnowledgeValidationError::new(
path,
format!("contains more than {MAX_JSON_ARRAY_ENTRIES} values"),
));
}
for (index, value) in values.iter().enumerate() {
validate_json_value(&format!("{path}[{index}]"), value, depth + 1)?;
}
Ok(())
}
Value::Object(values) => {
if values.len() > MAX_JSON_OBJECT_ENTRIES {
return Err(KnowledgeValidationError::new(
path,
format!("contains more than {MAX_JSON_OBJECT_ENTRIES} fields"),
));
}
for (key, value) in values {
validate_key(&format!("{path}.{key}"), key)?;
validate_json_value(&format!("{path}.{key}"), value, depth + 1)?;
}
Ok(())
}
}
}
fn validate_key(path: &str, key: &str) -> Result<(), KnowledgeValidationError> {
validate_text(path, key, MAX_SCOPE_VALUE_BYTES, false)?;
let normalized = key
.chars()
.filter(char::is_ascii_alphanumeric)
.collect::<String>()
.to_ascii_lowercase();
const FORBIDDEN: &[&str] = &[
"authorization",
"cookie",
"credential",
"formvalue",
"password",
"rawaccessibility",
"rawcdp",
"rawdom",
"secret",
"screenshot",
"token",
];
if FORBIDDEN.iter().any(|word| normalized.contains(word)) {
return Err(KnowledgeValidationError::new(
path,
"field name is not permitted in persistent knowledge",
));
}
Ok(())
}
fn validate_text(
path: &str,
value: &str,
maximum: usize,
allow_empty: bool,
) -> Result<(), KnowledgeValidationError> {
if (!allow_empty && value.is_empty()) || value.len() > maximum {
let requirement = if allow_empty {
format!("at most {maximum} bytes")
} else {
format!("non-empty and at most {maximum} bytes")
};
return Err(KnowledgeValidationError::new(
path,
format!("must be {requirement}"),
));
}
Ok(())
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct KnowledgeValidationError {
pub path: String,
pub reason: String,
}
impl KnowledgeValidationError {
pub(crate) fn new(path: impl Into<String>, reason: impl Into<String>) -> Self {
Self {
path: path.into(),
reason: reason.into(),
}
}
fn at(self, index: usize) -> Self {
Self::new(format!("records[{index}].{}", self.path), self.reason)
}
}
impl fmt::Display for KnowledgeValidationError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(formatter, "{}: {}", self.path, self.reason)
}
}
impl std::error::Error for KnowledgeValidationError {}
#[cfg(test)]
mod tests {
#[test]
fn lookup_options_propagate_live_portability_without_defaults() {
let corpus: Value = serde_json::from_str(include_str!(
"../../../benchmarks/scenarios/semantic-observation-v1.json"
))
.unwrap();
let observation =
SemanticObservation::from_json(&corpus["fixtures"][1]["observation"].to_string())
.unwrap();
let options = KnowledgeLookupOptions {
profile_scope: KnowledgeProfileScope::Anonymous,
profile_key: None,
locale: None,
tenant_key: None,
browser_family: "chromium".into(),
browser_version: Some("120.0".into()),
glass_schema_version: 1,
policy_preset: "balanced".into(),
now_epoch_seconds: 0,
current_revision: None,
current_extension_id: None,
surface_kind: Some(KnowledgeSurfaceKind::Svg),
backend_kind: Some(KnowledgeBackendKind::Visual),
backend_capabilities: vec![KnowledgeBackendCapability::Capture],
workspace_id: None,
workspace_generation: None,
};
let mut mismatch = options.clone();
mismatch.current_revision = Some(observation.revision.saturating_sub(1));
let error = KnowledgeLookupContext::from_observation(&observation, mismatch).unwrap_err();
assert_eq!(error.path, "currentRevision");
let context = KnowledgeLookupContext::from_observation(&observation, options).unwrap();
assert_eq!(context.surface_kind, Some(KnowledgeSurfaceKind::Svg));
assert_eq!(context.backend_kind, Some(KnowledgeBackendKind::Visual));
assert_eq!(
context.backend_capabilities,
vec![KnowledgeBackendCapability::Capture]
);
let mut absent = context;
absent.surface_kind = None;
absent.backend_kind = None;
absent.backend_capabilities.clear();
assert!(absent.surface_kind.is_none());
assert!(absent.backend_kind.is_none());
}
use super::*;
use crate::browser::session::{
FingerprintInvalidation, IntentConfidence, SemanticIntentPurpose, SemanticRegionKind,
SemanticRouteIdentity, SemanticTargetFingerprint, WorkflowDefinition,
};
use serde_json::json;
fn record() -> KnowledgeRecord {
KnowledgeRecord {
schema_version: KNOWLEDGE_SCHEMA_VERSION,
record_id: "knowledge_docs_1".into(),
kind: KnowledgeRecordKind::PageFamily,
scope: KnowledgeScope {
origin: "https://example.test".into(),
path_pattern: "/docs/*".into(),
profile_scope: KnowledgeProfileScope::Anonymous,
profile_key: None,
locale: Some("en-US".into()),
tenant_key: None,
browser_family: "chromium".into(),
browser_version_range: Some(">=120".into()),
glass_schema_version: 1,
policy_preset: "balanced".into(),
workspace_id: None,
workspace_generation: None,
},
source: KnowledgeSource {
first_seen_at: "2026-07-27T00:00:00Z".into(),
last_verified_at: "2026-07-27T00:00:00Z".into(),
glass_version: "0.2.0".into(),
verification_count: 1,
surface: KnowledgeSurfaceProvenance {
kind: KnowledgeSurfaceKind::Document,
understanding: KnowledgeUnderstandingLevel::Strong,
coverage: KnowledgeSurfaceCoverage::Semantic,
extension_id: None,
},
backend: KnowledgeBackendProvenance {
backend: KnowledgeBackendKind::Cdp,
profile: "production".into(),
capabilities: vec![
KnowledgeBackendCapability::SemanticExtraction,
KnowledgeBackendCapability::Verification,
],
},
},
confidence: KnowledgeConfidence::Observed,
invalidation: KnowledgeInvalidation {
max_age_seconds: Some(604_800),
required_landmarks: vec!["main".into(), "search".into()],
},
data: json!({"pageKind": "documentation", "regions": ["main", "search"]}),
portability: KnowledgePortability::SurfacePortable,
memory_influence: KnowledgeMemoryInfluence::None,
retrieval: KnowledgeRetrievalExplanation {
signals: Vec::new(),
current_validation: KnowledgeCurrentValidation {
status: KnowledgeCurrentValidationStatus::Validated,
evidence_quality: KnowledgeEvidenceQuality::Strong,
current_revision: Some(42),
validated_at: Some("2026-07-27T00:00:00Z".into()),
},
},
history: Vec::new(),
}
}
fn retrieval_context() -> KnowledgeLookupContext {
KnowledgeLookupContext {
origin: "https://example.test".into(),
path: "/docs/intro".into(),
profile_scope: KnowledgeProfileScope::Anonymous,
profile_key: None,
locale: Some("en-US".into()),
tenant_key: None,
browser_family: "chromium".into(),
browser_version: Some("120.0".into()),
glass_schema_version: 1,
policy_preset: "balanced".into(),
landmarks: vec!["main".into(), "search".into()],
now_epoch_seconds: 1_785_542_400,
current_revision: 42,
surface_kind: Some(KnowledgeSurfaceKind::Document),
backend_kind: Some(KnowledgeBackendKind::Cdp),
backend_capabilities: vec![
KnowledgeBackendCapability::SemanticExtraction,
KnowledgeBackendCapability::Verification,
],
current_extension_id: None,
workspace_id: None,
workspace_generation: None,
}
}
#[test]
fn exact_retrieval_is_bounded_and_explains_no_embedding_use() {
let record = record();
let candidate = record.retrieve_candidate(
&retrieval_context(),
&KnowledgeRetrievalQuery {
page_kind: Some("documentation".into()),
landmarks: vec!["main".into()],
max_results: 1,
..KnowledgeRetrievalQuery::default()
},
);
assert!(candidate.rejection.is_none());
assert_eq!(
candidate.current_validation.status,
KnowledgeCurrentValidationStatus::Validated
);
assert_eq!(candidate.portability, KnowledgePortability::SurfacePortable);
assert_eq!(candidate.surface_kind, KnowledgeSurfaceKind::Document);
assert_eq!(candidate.backend_kind, KnowledgeBackendKind::Cdp);
assert!(
candidate.signals.iter().any(|signal| {
signal.kind == KnowledgeRetrievalSignalKind::ExactPageFamilyMatch
})
);
assert!(
candidate
.signals
.iter()
.any(|signal| { signal.kind == KnowledgeRetrievalSignalKind::BackendMatch })
);
}
#[test]
fn contradictory_current_page_family_wins_over_historical_match() {
let candidate = record().retrieve_candidate(
&retrieval_context(),
&KnowledgeRetrievalQuery {
page_kind: Some("checkout".into()),
..KnowledgeRetrievalQuery::default()
},
);
assert_eq!(
candidate.rejection,
Some(KnowledgeRejectionReason::Contradicted)
);
}
#[test]
fn incompatible_backend_is_rejected_with_typed_provenance() {
let mut historical = record();
historical.portability = KnowledgePortability::BackendSpecific;
let mut context = retrieval_context();
context.backend_kind = Some(KnowledgeBackendKind::WebdriverBidi);
let candidate = historical.retrieve_candidate(
&context,
&KnowledgeRetrievalQuery {
page_kind: Some("documentation".into()),
..KnowledgeRetrievalQuery::default()
},
);
assert_eq!(
candidate.rejection,
Some(KnowledgeRejectionReason::BackendIncompatible)
);
assert!(candidate.explanation.is_some());
}
#[test]
fn record_round_trip_and_hash_are_deterministic() {
let record = record();
let canonical = record.to_canonical_json().unwrap();
let parsed: KnowledgeRecord = serde_json::from_str(&canonical).unwrap();
assert_eq!(parsed, record);
assert_eq!(
record.content_hash().unwrap(),
parsed.content_hash().unwrap()
);
}
#[test]
fn workspace_identity_and_generation_isolation_is_fail_closed() {
let mut context = retrieval_context();
context.workspace_id = Some("workspace-alpha".into());
context.workspace_generation = Some(7);
let legacy = record().retrieve_candidate(
&context,
&KnowledgeRetrievalQuery {
page_kind: Some("documentation".into()),
..KnowledgeRetrievalQuery::default()
},
);
assert_eq!(
legacy.rejection,
Some(KnowledgeRejectionReason::LegacyWorkspaceUnbound)
);
let mut bound = record();
bound.scope.workspace_id = Some("workspace-alpha".into());
bound.scope.workspace_generation = Some(7);
bound.validate().unwrap();
let wire = bound.to_canonical_json().unwrap();
assert!(wire.contains("\"workspaceId\":\"workspace-alpha\""));
assert!(wire.contains("\"workspaceGeneration\":7"));
assert_eq!(
bound
.retrieve_candidate(
&context,
&KnowledgeRetrievalQuery {
page_kind: Some("documentation".into()),
..KnowledgeRetrievalQuery::default()
},
)
.rejection,
None
);
context.workspace_generation = Some(8);
let stale = bound.retrieve_candidate(
&context,
&KnowledgeRetrievalQuery {
page_kind: Some("documentation".into()),
..KnowledgeRetrievalQuery::default()
},
);
assert_eq!(
stale.rejection,
Some(KnowledgeRejectionReason::WorkspaceGenerationMismatch)
);
}
#[test]
fn lifecycle_opaque_and_extension_records_fail_closed() {
let query = KnowledgeRetrievalQuery {
page_kind: Some("documentation".into()),
..KnowledgeRetrievalQuery::default()
};
for (confidence, expected) in [
(
KnowledgeConfidence::Stale,
KnowledgeRejectionReason::StaleLifecycle,
),
(
KnowledgeConfidence::Contradicted,
KnowledgeRejectionReason::ContradictedLifecycle,
),
(
KnowledgeConfidence::Quarantined,
KnowledgeRejectionReason::Quarantined,
),
] {
let mut historical = record();
historical.confidence = confidence;
assert_eq!(
historical
.retrieve_candidate(&retrieval_context(), &query)
.rejection,
Some(expected)
);
}
let mut opaque = record();
opaque.source.surface.understanding = KnowledgeUnderstandingLevel::Opaque;
assert_eq!(
opaque
.retrieve_candidate(&retrieval_context(), &query)
.rejection,
Some(KnowledgeRejectionReason::OpaqueProvenance)
);
let mut extension = record();
extension.source.surface.kind = KnowledgeSurfaceKind::ExtensionDefined;
extension.source.surface.extension_id = Some("com.example.alpha".into());
let mut extension_context = retrieval_context();
extension_context.current_extension_id = Some("com.example.alpha".into());
assert_eq!(
extension
.retrieve_candidate(&extension_context, &query)
.rejection,
Some(KnowledgeRejectionReason::ExtensionMismatch)
);
}
#[test]
fn stale_lifecycle_confidence_is_not_assessed_as_eligible() {
let mut historical = record();
historical.confidence = KnowledgeConfidence::Stale;
assert_eq!(
historical.assess(&retrieval_context()).status,
KnowledgeAssessmentStatus::Stale
);
}
#[test]
fn sensitive_data_keys_are_rejected() {
let mut record = record();
record.data = json!({"requiredLandmarks": ["main"], "password": "never"});
let error = record.validate().unwrap_err();
assert_eq!(error.path, "data.password");
}
#[test]
fn scalar_record_data_is_rejected_by_the_contract() {
let mut record = record();
record.data = json!("not-a-knowledge-object");
let error = record.validate().unwrap_err();
assert_eq!(error.path, "data");
}
#[test]
fn profile_bound_scope_requires_a_profile_key() {
let mut record = record();
record.scope.profile_scope = KnowledgeProfileScope::ProfileBound;
let error = record.validate().unwrap_err();
assert_eq!(error.path, "scope.profileKey");
}
#[test]
fn verified_promotion_requires_fresh_evidence() {
let mut record = record();
let error = record
.transition(
KnowledgeConfidence::Verified,
"imported record".into(),
"2026-07-27T00:00:01Z".into(),
false,
)
.unwrap_err();
assert_eq!(error.path, "freshVerification");
record
.transition(
KnowledgeConfidence::Verified,
"fresh landmark match".into(),
"2026-07-27T00:00:01Z".into(),
true,
)
.unwrap();
assert_eq!(record.confidence, KnowledgeConfidence::Verified);
assert_eq!(record.source.last_verified_at, "2026-07-27T00:00:01Z");
assert_eq!(record.source.verification_count, 2);
assert_eq!(record.history.len(), 1);
}
#[test]
fn fresh_verification_refreshes_an_unchanged_state() {
let mut record = record();
record
.transition(
KnowledgeConfidence::Observed,
"fresh observation repeated".into(),
"2026-07-27T00:00:02Z".into(),
true,
)
.unwrap();
assert_eq!(record.source.last_verified_at, "2026-07-27T00:00:02Z");
assert_eq!(record.source.verification_count, 2);
assert!(record.history.is_empty());
}
#[test]
fn snapshot_rejects_duplicate_record_ids() {
let record = record();
let snapshot = KnowledgeStoreSnapshot {
schema_version: KNOWLEDGE_SCHEMA_VERSION,
records: vec![record.clone(), record],
};
let error = snapshot.validate().unwrap_err();
assert_eq!(error.path, "records[1].recordId");
}
fn lookup_context() -> KnowledgeLookupContext {
KnowledgeLookupContext {
origin: "https://example.test".into(),
path: "/docs/getting-started".into(),
profile_scope: KnowledgeProfileScope::Anonymous,
profile_key: None,
locale: Some("en-US".into()),
tenant_key: None,
browser_family: "chromium".into(),
browser_version: Some(">=120".into()),
surface_kind: Some(KnowledgeSurfaceKind::Document),
backend_kind: Some(KnowledgeBackendKind::Cdp),
backend_capabilities: vec![
KnowledgeBackendCapability::SemanticExtraction,
KnowledgeBackendCapability::Verification,
],
glass_schema_version: 1,
policy_preset: "balanced".into(),
current_revision: 42,
current_extension_id: None,
workspace_id: None,
workspace_generation: None,
landmarks: vec!["documentation".into(), "main".into(), "search".into()],
now_epoch_seconds: chrono::DateTime::parse_from_rfc3339("2026-07-27T00:00:00Z")
.unwrap()
.timestamp(),
}
}
#[test]
fn assessment_accepts_fresh_matching_scope_and_landmarks() {
let assessment = record().assess(&lookup_context());
assert_eq!(assessment.status, KnowledgeAssessmentStatus::Eligible);
assert_eq!(assessment.missing_landmarks, Vec::<String>::new());
assert!(assessment.conflicts.is_empty());
}
#[test]
fn assessment_rejects_current_revision_mismatch() {
let mut context = lookup_context();
context.current_revision = 43;
let assessment = record().assess(&context);
assert_eq!(assessment.status, KnowledgeAssessmentStatus::Stale);
assert!(
assessment
.conflicts
.contains(&"current Web IR revision does not match".to_string())
);
}
#[test]
fn extension_identity_must_match_live_surface() {
let mut extension = record();
extension.source.surface.kind = KnowledgeSurfaceKind::ExtensionDefined;
extension.source.surface.extension_id = Some("com.example.alpha".into());
let mut context = lookup_context();
context.surface_kind = Some(KnowledgeSurfaceKind::ExtensionDefined);
context.current_extension_id = Some("com.example.alpha".into());
assert_eq!(
extension.assess(&context).status,
KnowledgeAssessmentStatus::Eligible
);
context.current_extension_id = Some("com.example.beta".into());
let mismatch = extension.assess(&context);
assert_eq!(mismatch.status, KnowledgeAssessmentStatus::Stale);
assert!(
mismatch
.conflicts
.contains(&"extension provenance does not match".to_string())
);
context.current_extension_id = None;
assert_eq!(
extension.assess(&context).status,
KnowledgeAssessmentStatus::Stale
);
}
#[test]
fn lookup_capabilities_are_bounded_and_unique() {
let oversized = vec![KnowledgeBackendCapability::Navigation; MAX_BACKEND_CAPABILITIES + 1];
let error = validate_backend_capabilities("backendCapabilities", &oversized).unwrap_err();
assert_eq!(error.path, "backendCapabilities");
let duplicate = vec![
KnowledgeBackendCapability::Navigation,
KnowledgeBackendCapability::Navigation,
];
let error = validate_backend_capabilities("backendCapabilities", &duplicate).unwrap_err();
assert_eq!(error.path, "backendCapabilities[1]");
}
#[test]
fn assessment_fails_closed_without_current_validation() {
let mut legacy = record();
legacy.retrieval.current_validation = KnowledgeCurrentValidation::default();
let assessment = legacy.assess(&lookup_context());
assert_eq!(assessment.status, KnowledgeAssessmentStatus::Stale);
assert!(
assessment
.conflicts
.contains(&"record lacks current Web IR validation".to_string())
);
}
#[test]
fn assessment_fails_closed_for_opaque_backend_and_nonportable_memory() {
let mut legacy = record();
legacy.source.surface = KnowledgeSurfaceProvenance::default();
legacy.source.backend = KnowledgeBackendProvenance::default();
legacy.portability = KnowledgePortability::NonPortable;
let assessment = legacy.assess(&lookup_context());
assert_eq!(assessment.status, KnowledgeAssessmentStatus::Stale);
assert!(
assessment
.conflicts
.contains(&"surface or backend provenance is unknown".to_string())
);
}
#[test]
fn surface_portability_requires_current_surface_witness() {
let mut context = lookup_context();
context.surface_kind = Some(KnowledgeSurfaceKind::Svg);
let assessment = record().assess(&context);
assert_eq!(assessment.status, KnowledgeAssessmentStatus::Stale);
assert!(
assessment
.conflicts
.contains(&"record surface provenance is incompatible with this context".into())
);
}
#[test]
fn lifecycle_invalidation_clears_current_validation() {
let mut value = record();
value
.transition(
KnowledgeConfidence::Stale,
"drift detected".into(),
"2026-07-27T00:00:01Z".into(),
false,
)
.unwrap();
assert_eq!(
value.retrieval.current_validation.status,
KnowledgeCurrentValidationStatus::Stale
);
assert_eq!(
value.assess(&lookup_context()).status,
KnowledgeAssessmentStatus::Stale
);
}
#[test]
fn validation_requires_revision_witness_and_retrieval_is_redacted() {
let mut value = record();
value.retrieval.current_validation.current_revision = None;
let error = value.validate().unwrap_err();
assert_eq!(error.path, "retrieval.currentValidation.currentRevision");
let mut signal_value = record();
signal_value
.retrieval
.signals
.push(KnowledgeRetrievalSignal {
kind: KnowledgeRetrievalSignalKind::SemanticSimilarity,
detail: "token from page".into(),
score_millis: None,
});
let error = signal_value.validate().unwrap_err();
assert_eq!(error.path, "retrieval.signals[0].detail");
assert!(
serde_json::from_value::<KnowledgeRetrievalSignal>(
json!({"kind":"freshness","detail":"ok","extra":"reject"})
)
.is_err()
);
}
#[test]
fn assessment_matches_browser_version_ranges() {
assert!(browser_version_matches(Some(">=120"), Some("120.0")));
assert!(browser_version_matches(Some("<121"), Some("120.0.1")));
assert!(!browser_version_matches(Some(">=121"), Some("120.0")));
assert!(!browser_version_matches(Some("120"), None));
}
#[test]
fn assessment_marks_missing_landmarks_stale() {
let mut context = lookup_context();
context.landmarks.retain(|landmark| landmark != "search");
let assessment = record().assess(&context);
assert_eq!(assessment.status, KnowledgeAssessmentStatus::Stale);
assert_eq!(assessment.missing_landmarks, vec!["search"]);
}
#[test]
fn assessment_rejects_cross_origin_scope() {
let mut context = lookup_context();
context.origin = "https://other.test".into();
let assessment = record().assess(&context);
assert_eq!(assessment.status, KnowledgeAssessmentStatus::OutOfScope);
assert!(
assessment
.conflicts
.contains(&"origin does not match".to_string())
);
}
#[test]
fn page_record_keeps_shape_but_not_current_targets() {
let corpus: Value = serde_json::from_str(include_str!(
"../../../benchmarks/scenarios/semantic-observation-v1.json"
))
.unwrap();
let observation =
SemanticObservation::from_json(&corpus["fixtures"][1]["observation"].to_string())
.unwrap();
let record = KnowledgeRecord::from_page_observation(
&observation,
KnowledgeRecordBuildOptions {
record_id: "knowledge_search".into(),
scope: record().scope,
glass_version: "0.2.0".into(),
observed_at: "2026-07-27T00:00:00Z".into(),
surface: KnowledgeSurfaceProvenance {
kind: KnowledgeSurfaceKind::Document,
understanding: KnowledgeUnderstandingLevel::Strong,
coverage: KnowledgeSurfaceCoverage::Semantic,
extension_id: None,
},
backend: KnowledgeBackendProvenance {
backend: KnowledgeBackendKind::Cdp,
profile: "test".into(),
capabilities: vec![KnowledgeBackendCapability::SemanticExtraction],
},
portability: KnowledgePortability::SemanticPortable,
current_validation: KnowledgeCurrentValidation::default(),
},
)
.unwrap();
let data = serde_json::to_string(&record.data).unwrap();
assert!(data.contains("searchResults"));
assert!(!data.contains("axr-8-9"));
assert_eq!(record.confidence, KnowledgeConfidence::Observed);
}
#[test]
fn target_record_keeps_digest_but_not_current_handles_or_names() {
let candidate = SemanticIntentCandidate {
id: "candidate_1".into(),
reference: "axr-42-1".into(),
role: "button".into(),
name: "Private Settings Label".into(),
input_type: None,
region_id: Some("region_navigation".into()),
region_kind: Some(SemanticRegionKind::Navigation),
confidence: IntentConfidence::Exact,
evidence: Vec::new(),
fingerprint: Some(SemanticTargetFingerprint {
revision: 42,
route: SemanticRouteIdentity {
target_id: "target-1".into(),
frame_id: "frame-1".into(),
url: "https://example.test/settings".into(),
},
role: "button".into(),
name: "Private Settings Label".into(),
input_type: None,
region_id: Some("region_navigation".into()),
region_kind: Some(SemanticRegionKind::Navigation),
purpose: SemanticIntentPurpose::Open,
invalidated_by: vec![FingerprintInvalidation::Revision],
}),
};
let record = KnowledgeRecord::from_intent_candidate(
&candidate,
KnowledgeRecordBuildOptions {
record_id: "knowledge-settings-target".into(),
scope: record().scope,
glass_version: "0.2.0".into(),
observed_at: "2026-07-27T00:00:00Z".into(),
surface: KnowledgeSurfaceProvenance {
kind: KnowledgeSurfaceKind::Document,
understanding: KnowledgeUnderstandingLevel::Strong,
coverage: KnowledgeSurfaceCoverage::Semantic,
extension_id: None,
},
backend: KnowledgeBackendProvenance {
backend: KnowledgeBackendKind::Cdp,
profile: "test".into(),
capabilities: vec![KnowledgeBackendCapability::SemanticExtraction],
},
portability: KnowledgePortability::SemanticPortable,
current_validation: KnowledgeCurrentValidation::default(),
},
)
.unwrap();
let data = serde_json::to_string(&record.data).unwrap();
assert!(data.contains("sha256:"));
assert!(!data.contains("axr-42-1"));
assert!(!data.contains("Private Settings Label"));
assert!(!data.contains("target-1"));
assert!(!data.contains("frame-1"));
}
#[test]
fn workflow_record_keeps_shape_without_definition_details() {
let corpus: Value = serde_json::from_str(include_str!(
"../../../benchmarks/scenarios/workflow-v1.json"
))
.unwrap();
let workflow =
WorkflowDefinition::from_value(corpus["scenarios"][0]["workflow"].clone()).unwrap();
let record = KnowledgeRecord::from_workflow_definition(
&workflow,
KnowledgeRecordBuildOptions {
record_id: "knowledge-workflow-entry".into(),
scope: record().scope,
glass_version: "0.2.0".into(),
observed_at: "2026-07-27T00:00:00Z".into(),
surface: KnowledgeSurfaceProvenance {
kind: KnowledgeSurfaceKind::Document,
understanding: KnowledgeUnderstandingLevel::Strong,
coverage: KnowledgeSurfaceCoverage::Semantic,
extension_id: None,
},
backend: KnowledgeBackendProvenance {
backend: KnowledgeBackendKind::Cdp,
profile: "test".into(),
capabilities: vec![KnowledgeBackendCapability::SemanticExtraction],
},
portability: KnowledgePortability::SemanticPortable,
current_validation: KnowledgeCurrentValidation::default(),
},
)
.unwrap();
assert_eq!(record.kind, KnowledgeRecordKind::WorkflowEntryPoint);
assert_eq!(record.confidence, KnowledgeConfidence::Candidate);
let data = serde_json::to_string(&record.data).unwrap();
assert!(data.contains("workflowHash"));
assert!(!data.contains("linear-typed-output"));
assert!(!data.contains("Glass Scorecard"));
assert!(!data.contains("target"));
}
#[test]
fn metadata_round_trip_is_serde_stable_and_bounded() {
let mut record = record();
record.source.surface = KnowledgeSurfaceProvenance {
kind: KnowledgeSurfaceKind::Document,
understanding: KnowledgeUnderstandingLevel::Strong,
coverage: KnowledgeSurfaceCoverage::Semantic,
extension_id: None,
};
record.source.backend = KnowledgeBackendProvenance {
backend: KnowledgeBackendKind::Cdp,
profile: "production".into(),
capabilities: vec![
KnowledgeBackendCapability::SemanticExtraction,
KnowledgeBackendCapability::Verification,
],
};
record.portability = KnowledgePortability::SurfacePortable;
record.retrieval.signals = vec![KnowledgeRetrievalSignal {
kind: KnowledgeRetrievalSignalKind::ExactPageFamilyMatch,
detail: "same page family".into(),
score_millis: Some(1_000),
}];
record.validate().unwrap();
let json = record.to_canonical_json().unwrap();
let parsed: KnowledgeRecord = serde_json::from_str(&json).unwrap();
assert_eq!(parsed, record);
assert!(json.contains("\"surface\""));
assert!(json.contains("\"backend\""));
assert!(json.contains("\"surfacePortable\""));
assert!(json.contains("\"exactPageFamilyMatch\""));
}
#[test]
fn legacy_snapshot_uses_fail_closed_additive_defaults() {
let legacy = r#"{
"schemaVersion":1,
"records":[{
"schemaVersion":1,
"recordId":"legacy",
"kind":"pageFamily",
"scope":{
"origin":"https://example.test",
"pathPattern":"/docs/*",
"profileScope":"anonymous",
"browserFamily":"chromium",
"glassSchemaVersion":1,
"policyPreset":"balanced"
},
"source":{
"firstSeenAt":"2026-07-27T00:00:00Z",
"lastVerifiedAt":"2026-07-27T00:00:00Z",
"glassVersion":"0.2.0",
"verificationCount":1
},
"confidence":"observed",
"invalidation":{},
"data":{"pageKind":"documentation"}
}]
}"#;
let snapshot: KnowledgeStoreSnapshot = serde_json::from_str(legacy).unwrap();
snapshot.validate().unwrap();
let migrated = &snapshot.records[0];
assert_eq!(migrated.source.surface.kind, KnowledgeSurfaceKind::Opaque);
assert_eq!(
migrated.source.backend.backend,
KnowledgeBackendKind::Unknown
);
assert_eq!(migrated.portability, KnowledgePortability::NonPortable);
assert_eq!(migrated.memory_influence, KnowledgeMemoryInfluence::None);
assert_eq!(
migrated.retrieval.current_validation.status,
KnowledgeCurrentValidationStatus::NotValidated
);
let expected: Value = serde_json::from_str(legacy).unwrap();
assert_eq!(serde_json::to_value(&snapshot).unwrap(), expected);
}
#[test]
fn invalid_metadata_fails_closed_and_sensitive_profile_is_rejected() {
let unknown = serde_json::from_str::<KnowledgeSurfaceKind>(r#""futureSurface""#);
assert!(unknown.is_err());
let mut base = record();
base.source.backend.profile = "session-token-profile".into();
let error = base.validate().unwrap_err();
assert_eq!(error.path, "source.backend.profile");
base.source.surface.kind = KnowledgeSurfaceKind::ExtensionDefined;
let error = base.validate().unwrap_err();
assert_eq!(error.path, "source.surface.extensionId");
base.source.surface.extension_id = Some("x".repeat(MAX_EXTENSION_ID_BYTES + 1));
let error = base.validate().unwrap_err();
assert_eq!(error.path, "source.surface.extensionId");
let mut influenced = record();
influenced.source.backend.profile = "production".into();
influenced.memory_influence = KnowledgeMemoryInfluence::RankingOnly;
influenced.retrieval.current_validation = KnowledgeCurrentValidation::default();
let error = influenced.validate().unwrap_err();
assert_eq!(error.path, "memoryInfluence");
}
#[test]
fn boolean_freshness_cannot_promote_without_witness() {
let mut value = record();
value.retrieval.current_validation = KnowledgeCurrentValidation::default();
let before = value.clone();
let error = value
.transition(
KnowledgeConfidence::Verified,
"boolean is insufficient".into(),
"2026-07-27T00:00:01Z".into(),
true,
)
.unwrap_err();
assert_eq!(error.path, "currentValidation");
assert_eq!(value, before);
value
.transition_with_validation(
KnowledgeConfidence::Verified,
"revision witness".into(),
"2026-07-27T00:00:01Z".into(),
43,
KnowledgeEvidenceQuality::Strong,
)
.unwrap();
assert_eq!(value.confidence, KnowledgeConfidence::Verified);
}
#[test]
fn fresh_transition_validates_memory_but_never_authorizes_mutation() {
let mut record = record();
assert_eq!(
record.retrieval.current_validation.status,
KnowledgeCurrentValidationStatus::Validated
);
record
.transition(
KnowledgeConfidence::Verified,
"historical-only".into(),
"2026-07-27T00:00:01Z".into(),
false,
)
.unwrap_err();
record
.transition(
KnowledgeConfidence::Verified,
"fresh browser evidence".into(),
"2026-07-27T00:00:01Z".into(),
true,
)
.unwrap();
assert_eq!(
record.retrieval.current_validation.status,
KnowledgeCurrentValidationStatus::Validated
);
assert!(record.data.get("reference").is_none());
assert!(record.data.get("target").is_none());
}
}