use serde::Serialize;
use std::path::{Path, PathBuf};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum OracleBackend {
CanonicalCorpus,
FilesystemFuzzy,
SteerMetadata,
ContentSemantic,
Hybrid,
#[serde(rename = "hybrid_rrf")]
HybridRrf,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum OracleIndexKind {
None,
MetadataSteer,
CanonicalChunks,
ContentChunks,
OnionContent,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum OracleReadiness {
Ready,
Degraded,
UnsafeForLoctreeScope,
}
#[derive(Debug, Clone, Serialize)]
pub struct OracleStatus {
pub source_layer: String,
pub backend: OracleBackend,
pub index_kind: OracleIndexKind,
pub fallback_reason: Option<String>,
pub derived_view: String,
pub store_root: String,
pub indexed_count: usize,
pub scanned_count: usize,
pub candidate_count: usize,
pub source_paths_verified: bool,
pub stale_or_unknown: bool,
pub loctree_scope_safe: bool,
pub loctree_scope_note: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub manifest_generation_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub manifest_source_chunk_count: Option<usize>,
#[serde(skip_serializing_if = "Option::is_none")]
pub dense_count: Option<usize>,
#[serde(skip_serializing_if = "Option::is_none")]
pub lexical_doc_count: Option<usize>,
#[serde(skip_serializing_if = "Option::is_none")]
pub fusion_algorithm: Option<String>,
}
#[derive(Debug, Clone, Serialize)]
pub struct OracleEnvelope<T>
where
T: Serialize,
{
pub oracle_status: OracleStatus,
pub results: usize,
pub items: T,
}
impl OracleStatus {
pub fn canonical_corpus_scan(
store_root: &Path,
scanned_count: usize,
candidate_count: usize,
source_paths_verified: bool,
) -> Self {
Self {
source_layer: canonical_layer(),
backend: OracleBackend::CanonicalCorpus,
index_kind: OracleIndexKind::CanonicalChunks,
fallback_reason: None,
derived_view: "canonical_chunk_scan_no_semantic_index".to_string(),
store_root: display_path(store_root),
indexed_count: 0,
scanned_count,
candidate_count,
source_paths_verified,
stale_or_unknown: !source_paths_verified,
loctree_scope_safe: source_paths_verified,
loctree_scope_note: if source_paths_verified {
"safe_as_canonical_intent_evidence; not a semantic similarity oracle".to_string()
} else {
"unsafe_for_scope_narrowing; source chunks must be readable before Loctree trusts this surface".to_string()
},
manifest_generation_id: None,
manifest_source_chunk_count: None,
dense_count: None,
lexical_doc_count: None,
fusion_algorithm: None,
}
}
pub fn filesystem_fuzzy(
store_root: &Path,
scanned_count: usize,
candidate_count: usize,
source_paths_verified: bool,
) -> Self {
Self {
source_layer: canonical_layer(),
backend: OracleBackend::FilesystemFuzzy,
index_kind: OracleIndexKind::None,
fallback_reason: Some(
"fallback_filesystem_fuzzy: content index unavailable".to_string(),
),
derived_view: "none_filesystem_scan".to_string(),
store_root: display_path(store_root),
indexed_count: 0,
scanned_count,
candidate_count,
source_paths_verified,
stale_or_unknown: true,
loctree_scope_safe: false,
loctree_scope_note:
"unsafe_for_scope_narrowing; use as routing evidence, then read canonical chunks"
.to_string(),
manifest_generation_id: None,
manifest_source_chunk_count: None,
dense_count: None,
lexical_doc_count: None,
fusion_algorithm: None,
}
}
pub fn content_semantic(
store_root: &Path,
indexed_count: usize,
candidate_count: usize,
source_paths_verified: bool,
) -> Self {
Self {
source_layer: canonical_layer(),
backend: OracleBackend::ContentSemantic,
index_kind: OracleIndexKind::ContentChunks,
fallback_reason: None,
derived_view: "materialized_vector_index_from_canonical_chunks".to_string(),
store_root: display_path(store_root),
indexed_count,
scanned_count: indexed_count,
candidate_count,
source_paths_verified,
stale_or_unknown: !source_paths_verified,
loctree_scope_safe: source_paths_verified,
loctree_scope_note: if source_paths_verified {
"safe_for_semantic_scope_when_followed_by_canonical_chunk_read".to_string()
} else {
"unsafe_for_scope_narrowing; semantic index returned paths that are not all readable"
.to_string()
},
manifest_generation_id: None,
manifest_source_chunk_count: None,
dense_count: None,
lexical_doc_count: None,
fusion_algorithm: None,
}
}
pub fn hybrid_rrf(
store_root: &Path,
status: &crate::search_engine::HybridRetrievalStatus,
candidate_count: usize,
source_paths_verified: bool,
) -> Self {
Self {
source_layer: canonical_layer(),
backend: OracleBackend::HybridRrf,
index_kind: OracleIndexKind::OnionContent,
fallback_reason: None,
derived_view: "hybrid_rrf_manifest_bound_lexical_dense_index".to_string(),
store_root: display_path(store_root),
indexed_count: status.source_chunk_count,
scanned_count: status.source_chunk_count,
candidate_count,
source_paths_verified,
stale_or_unknown: !source_paths_verified,
loctree_scope_safe: source_paths_verified,
loctree_scope_note: if source_paths_verified {
"safe_for_hybrid_scope_when_followed_by_canonical_chunk_read".to_string()
} else {
"unsafe_for_scope_narrowing; hybrid index returned paths that are not all readable"
.to_string()
},
manifest_generation_id: Some(status.generation_id.clone()),
manifest_source_chunk_count: Some(status.source_chunk_count),
dense_count: Some(status.dense_count),
lexical_doc_count: Some(status.lexical_doc_count),
fusion_algorithm: Some(status.fusion_algorithm.clone()),
}
}
pub fn metadata_steer(
store_root: &Path,
indexed_count: usize,
candidate_count: usize,
source_paths_verified: bool,
) -> Self {
let loctree_scope_safe = source_paths_verified;
Self {
source_layer: canonical_layer(),
backend: OracleBackend::SteerMetadata,
index_kind: OracleIndexKind::MetadataSteer,
fallback_reason: None,
derived_view: "metadata_steer_index_rebuildable_from_canonical_chunks".to_string(),
store_root: display_path(store_root),
indexed_count,
scanned_count: indexed_count,
candidate_count,
source_paths_verified,
stale_or_unknown: !source_paths_verified,
loctree_scope_safe,
loctree_scope_note: if loctree_scope_safe {
"safe_for_metadata_scope_when_followed_by_canonical_chunk_read".to_string()
} else {
"unsafe_for_scope_narrowing; metadata index returned paths that are not all readable"
.to_string()
},
manifest_generation_id: None,
manifest_source_chunk_count: None,
dense_count: None,
lexical_doc_count: None,
fusion_algorithm: None,
}
}
}
pub fn readiness(statuses: &[OracleStatus]) -> OracleReadiness {
if statuses.iter().any(|status| status.stale_or_unknown) {
OracleReadiness::UnsafeForLoctreeScope
} else if statuses
.iter()
.any(|status| status.fallback_reason.is_some())
{
OracleReadiness::Degraded
} else {
OracleReadiness::Ready
}
}
pub fn verify_paths<I, P>(paths: I) -> bool
where
I: IntoIterator<Item = P>,
P: Into<PathBuf>,
{
paths.into_iter().all(|path| path.into().exists())
}
fn display_path(path: &Path) -> String {
path.to_string_lossy().to_string()
}
fn canonical_layer() -> String {
"layer_1_canonical_corpus".to_string()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn filesystem_fuzzy_status_is_explicitly_not_semantic_or_loctree_safe() {
let status = OracleStatus::filesystem_fuzzy(Path::new("/tmp/aicx"), 40, 3, true);
assert_eq!(status.source_layer, "layer_1_canonical_corpus");
assert_eq!(status.backend, OracleBackend::FilesystemFuzzy);
assert_eq!(status.index_kind, OracleIndexKind::None);
assert!(
status
.fallback_reason
.as_deref()
.unwrap()
.contains("fallback")
);
assert!(status.stale_or_unknown);
assert!(!status.loctree_scope_safe);
assert!(
status
.loctree_scope_note
.contains("unsafe_for_scope_narrowing")
);
}
#[test]
fn canonical_intents_status_is_corpus_evidence_not_semantic_oracle() {
let status = OracleStatus::canonical_corpus_scan(Path::new("/tmp/aicx"), 2, 2, true);
assert_eq!(status.backend, OracleBackend::CanonicalCorpus);
assert_eq!(status.index_kind, OracleIndexKind::CanonicalChunks);
assert_eq!(status.fallback_reason, None);
assert!(status.loctree_scope_safe);
assert!(
status
.loctree_scope_note
.contains("not a semantic similarity oracle")
);
}
}