Deep Research Self-Correction and Knowledgebase Architecture SSOT (2026)

Deep Research Self-Correction and Knowledgebase Architecture SSOT (2026)

This document establishes the single source of truth (SSOT) for Vox Deep Research’s self-correcting code engine, multi-wave epistemic verification loop, and cross-session knowledgebase persistence system.

Vox Deep Research (vox-research-shim, vox-orchestrator, vox-search, vox-db) was designed to exceed the capabilities of proprietary systems—specifically Google Gemini Deep Research and Anthropic Claude Deep Research—by replacing purely speculative text synthesis with empirical sandbox execution, formal contradiction isolation, zero-token memory recall, and deterministic code repair.

---

1. Competitive Superiority Matrix

Capability Axis	Google Gemini Deep Research	Anthropic Claude Deep Research	Vox Deep Research (Shipped Architecture)
Code Correctness Guarantee	None (Pure stochastic generation; hallucinates obsolete APIs or invalid syntax)	None (Pure text inference; cannot verify compiler or runtime behavior)	Empirical Sandbox Proof: rustc compiler execution with deterministic overrule hierarchy and self-correction
Code Self-Correction Loop	Absent (Generates once; human must debug broken code)	Absent (Relies on chat prompt turnarounds)	Automated Diagnostic Feedback: Subprocess compiler stderr fed into LLM repair until compilation passes or attempts exhausted
Research Execution Topology	Recursive search-read-synthesize loop (single execution thread)	Subagent tree (hierarchical agent delegation)	3-Wave Adaptive DAG: Wave 1 (Reconnaissance) $\to$ Wave 2 (Contradiction Isolation) $\to$ Wave 3 (Empirical Validation & Sandbox)
Contradiction Resolution	Opaque heuristic weighting; often averages opposing claims	Multi-agent debate; prone to sycophantic consensus	Epistemic Resolution: Empirical compiler tests overrule text claims (ResolvedByEmpiricalSandbox); strict category classification
Convergence & Termination	Iteration count or arbitrary confidence score	Budget exhaustion or agent heuristic stop	Mathematically Calibrated Stability ($S$): Normalised 4-factor equation with unverified and contradiction penalties
Knowledge Permanence & Recall	Ephemeral per-session chat context	Ephemeral per-session context	Durable Cross-Session Knowledgebase: VoxDB SQLite FTS5 index (vox_research_search) with BM25 ranking + MEMORY.md dual-write
Context Window Consumption	Massive (1M–2M tokens of raw web dump)	High (subagent summaries stored in context)	Hierarchical Distillation & Packing: Triplet extraction (ClaimEvidenceUnit), verbatim span grounding, and pre-budgeted RAG packing
Zero-Cost Local Retrieval	Impossible ($100%$ Google Cloud dependent)	Impossible ($100%$ Anthropic API dependent)	Tier 0 Instant Intercept: Instant <50ms, 0-token response from local knowledgebase before hitting web search
Process Security & Cleanliness	Managed cloud container	Managed cloud container	Local Windows/POSIX Isolation: tempfile::Builder RAII drop guards, cmd.kill_on_drop(true) child termination, strict crate allowlists

---

2. Empirical Code Verification & Self-Correction Engine

Proprietary models frequently generate code based on outdated training data, mixing breaking changes across library major versions (e.g. Tokio delay_for vs sleep, Reqwest 0.11 vs 0.12). Static deep research reports generated by Gemini or Claude present this broken code with high confidence, forcing users into tedious debugging cycles.

Vox eliminates this failure mode by integrating a deterministic compile-and-repair loop directly into the research pipeline (crates/vox-research-shim/src/research/domain/codegen.rs).

2.1. Extraction and Syntax-Aware Probe Wrapping

Snippets extracted from markdown research reports or web sources often consist of bare statements, expressions, or partial functions that fail rustc compilation if evaluated naively as standalone files.

wrap_code_snippet_if_needed inspects top-level tokens, ignoring leading attributes (#[...]) and doc comments (///):

• Top-level items (pub fn, async fn, struct, enum, trait, type, const, impl, use, mod) are preserved as-is.
• Bare statements (e.g. let x = ...; assert!(...);) are wrapped inside a test probe harness:

  # ! [allow(unused_imports, unused_variables, dead_code, unused_must_use)]
  pub fn __vox_sandbox_probe() {
      // User statement snippet
  }

2.2. Isolated Sandboxed Execution

verify_rust_code_in_sandbox executes Rust code under rigorous process isolation:

1. Zero-Dependency Fast Path: Uses rustc --crate-type lib --emit=metadata - via stdin. Completes syntax and type verification in sub-100ms without touching disk metadata.
2. Crate Dependency Path: Writes a temporary Cargo.toml with strict crate name allowlists (rejecting control characters, newlines, brackets, or suspicious paths) and runs cargo check --message-format=short.
3. Process Cleanup & Timeouts: Child processes use kill_on_drop(true) on tokio::process::Command, combined with an asynchronous tokio::time::timeout (10s default) to prevent runaway build scripts or hanging processes. All temporary workspaces utilize tempfile::Builder for deterministic RAII cleanup on drop.

2.3. Diagnostic Self-Correction Loop

When compiler verification fails, attempt_code_self_correction initiates an iterative repair cycle:

[Candidate Code]
       |
       v
+--------------+        Passed
| verify_rust  | ---------------------> [Return CodeSelfCorrectionResult]
|  in sandbox  |
+--------------+
       | Failed
       v
[Extract Compiler Stderr]
       |
       v
+--------------+
| LLM Repair   | <--- Max Attempts Guard
|  Invocation  |
+--------------+
       | Repaired Code
       v
(Repeat Loop)

1. The raw diagnostic output (including error codes such as E0308, E0425, and line spans) is supplied to the repair closure.
2. The repair step produces a candidate fix and an explanation.
3. If the repaired code succeeds, res.final_passed is set to true, and the fix is recorded alongside the number of iterations taken.

---

3. Epistemic Overrule Hierarchy & Wave 3 Resolution

In Vox’s 3-Wave Research DAG, LLM evaluations never hold final authority over empirical facts.

3.1. The Empirical Overrule Law

If an empirical compiler execution or test fails during research validation:

1. Unconditional Verdict Overrule: The claim verdict is forced to Verdict::Contradicted.
2. Maximum Confidence: The confidence is set to 1.0 (empirical proof outweighs consensus text claims).
3. Evidence Injection: The compiler diagnostic stderr is appended directly as an evidence span of type SpanType::Contradicting.
4. Harness Artifact Fallback: If failure indicates an incomplete harness rather than invalid logic (e.g. E0432 unresolved import when dependencies were omitted, or cannot find function main), the system safely degrades to Verdict::Unverified at confidence 0.50, preventing false negative rejections of valid logic.

3.2. Contradiction Resolution

When two sources disagree (e.g., “Library X method takes integer milliseconds” vs. “Library X method takes Duration”):

• In Wave 1, this is flagged as a ContradictionRecord.
• In Wave 3, apply_sandbox_self_correction checks if the claim is involved in any active contradiction.
• If empirical compilation passes for the corrected code, the contradiction’s status is immediately updated:

  ContradictionStatus::ResolvedByEmpiricalSandbox {
      winning_claim_id,
      compiler_stdout: rationale,
  }

• This resolves epistemic deadlocks deterministically, eliminating the risk of research loops hanging on contested technical details.

---

4. Multi-Factor Stability Equation ($S$)

Early termination of deep research must balance query efficiency with epistemic rigor. Premature termination when critical claims are unverified produces shallow, hallucinated reports. Infinite loops waste tokens and lock system resources.

Vox employs a calibrated multi-factor stability metric:

$$S = 0.50 \cdot \frac{N_{\text{sup}}}{N_{\text{tot}}} + 0.30 \cdot \bar{\sigma}{\text{resamp}} + 0.20 \cdot \left(\frac{N{\text{tot}} - N_{\text{unverified}}}{N_{\text{tot}}}\right) - 0.30 \cdot \min\left(1.0, \frac{N_{\text{unres}}}{N_{\text{tot}}}\right)$$

4.1. Mathematical Boundaries

• Supported Ratio Weight ($0.50$): Reflects the proportion of claims with positive, verified evidence.
• Resample Stability Weight ($0.30$): Measures consistency of verdicts across SelfCheckGPT $3\times$ temperature resamplings ($\bar{\sigma}_{\text{resamp}}$).
• Verified Coverage Weight ($0.20$): Rewards actively reaching a decision (Supported or Contradicted) over leaving claims in limbo (Unverified).
• Contradiction Penalty ($-0.30$): Penalizes the existence of open, unresolved contradictions.
• Base Range: Without verified claims or in an empty plan, $S = 0.0$.

4.2. Strict Early Exit Preconditions

Early exit terminates execution before reaching max_waves if and only if all of the following conditions hold simultaneously:

1. $S \ge 0.85$ (Stability threshold)
2. $N_{\text{unres}} == 0$ (Zero unresolved contradictions remain)
3. $\frac{N_{\text{sup}}}{N_{\text{tot}}} \ge 0.70$ (At least 70% of claims are affirmatively supported)
4. $\frac{N_{\text{unverified}}}{N_{\text{tot}}} \le 0.15$ (No more than 15% of claims remain unverified)

This multi-gate requirement guarantees that deep research never terminates early when substantial uncertainty or conflict remains.

---

5. Cross-Session Knowledgebase Storage & Search (vox_research_search)

Unlike stateless research agents that discard findings upon session termination, Vox persists all research sessions, publications, and verified claims into VoxDB SQLite FTS5 (scientia_research_fts).

5.1. The vox_research_search MCP Tool

Exposed via the Model Context Protocol (MCP) and registered in contracts/operations/catalog.v1.yaml and tool-registry.canonical.yaml:

• Inputs:
  • query: Search string (supports natural language, keywords, and Boolean phrases).
  • limit: Maximum number of research items to return (default: 5, max: 20).
  • domain: Optional domain filter (codegen, shopping, general).
  • min_confidence: Optional minimum claim confidence threshold (e.g. 0.80).
  • verified_only: When true, returns only claims with Verdict::Supported.
• Outputs: Formatted markdown knowledge blocks containing:
  • Session titles, dates, and query provenance.
  • Overall research syntheses.
  • Verified claim bullet points with confidence scores and source URLs.

5.2. Robust FTS5 Query Sanitization

User search queries often contain punctuation, unbalanced quotes, or Boolean tokens that trigger SQLite syntax errors. sanitize_fts_query strips control operators and ensures that queries containing spaces are safely transformed into token prefix searches (e.g. rust async $\to$ "rust" "async"*), preventing query crashes while maximizing recall.

---

6. Memory Systems Integration & Context Budgeting

Vox unifies research findings with long-term agent memory across two distinct layers:

6.1. Dual-Write Memory Sync

When research concludes, MemoryManager::sync_verified_research_findings:

1. Converts the research query into a canonical slug key: research:<slug> (e.g. research:rust-tokio-vs-async-std).
2. Dual-writes the summary and verified claims to:
   • MEMORY.md: Persisted in human-readable Markdown with a dedicated # Verified Research Knowledgebase header.
   • VoxDB Knowledge Graph: Recorded into the memories table and knowledge nodes via upsert_knowledge_node, establishing searchable edges between topics and claims.

6.2. Context Window Distillation & Budget Packing

Injecting raw research papers or multi-page web scrapes into an LLM context window causes context dilution and needle-in-a-haystack retrieval failure.

distillation.rs provides deterministic context compression:

1. Triplet Extraction: Evidence is decomposed into ClaimEvidenceUnit triplets ((subject, relation, object)) with associated epistemic modality.
2. Verbatim Span Grounding: Extracted evidence spans must match the raw source text character-for-character, eliminating hallucinated “facts” during distillation.
3. Partitioned RAG Budgeting (pack_rag_budget):
   • Reserving 15% of the token budget specifically for contested or contradicted claims, ensuring counter-evidence is never crowded out by repetitive supporting claims.
   • Domain-level log dampening to prevent high-volume domains from monopolizing evidence spans.
   • Hard character bounds (context_max_chars) strictly enforced before LLM synthesis.

---

7. Chat Integration & Zero-Cost Slash Routing

Deep research is fully integrated into Vox Chat (vox-gui and vox-orchestrator-mcp):

7.1. Token-Aware Slash Command Parser

In crates/vox-gui/ui/src/lib/slashRouter.ts, parseResearchSlashCommand parses command line inputs with full quotation awareness:

• /research search "rust async concurrency" --min-confidence=0.8
• /research-search mimalloc jemalloc
• /research --domain codegen tokio runtime

7.2. Zero-Cost Knowledgebase Intercept

When a user executes a search command (/research search <query> or /research-search <query>), crates/vox-orchestrator-mcp/src/chat_tools/chat/message.rs intercepts the turn:

1. Zero LLM Tokens: The query is resolved directly against the local VoxDB knowledgebase.
2. Sub-50ms Latency: Returns stored research findings, citations, and verified claims instantly without invoking external web crawlers or LLM synthesis models.
3. Autonomous Pre-Check: Before triggering expensive Tier 3 autonomous deep web research, the orchestrator consults the local knowledgebase (Tier 0). If high-confidence, fresh findings exist for the query, the research terminates early, saving user time and API credits.

---

8. Verification & Architectural Testing

The self-correcting research architecture is verified by automated integration tests:

Test Suite	File Location	Verified Invariants
Sandbox & Process Isolation	crates/vox-research-shim/tests/codegen_sandbox_isolation_test.rs	RAII tempdir cleanup; kill_on_drop process termination; syntax probe wrapping
Diagnostic Self-Correction	crates/vox-research-shim/tests/codegen_self_correction_test.rs	Iterative repair loop; E0308/syntax repair; attempt exhaustion; doc-comment preservation
Wave 3 Sandbox Overrule	crates/vox-research-shim/tests/wave_self_correction_test.rs	Empirical compiler overrule of LLM verdicts; contradiction resolution to ResolvedByEmpiricalSandbox
Stability Calibration	crates/vox-research-shim/tests/stability_calibration_test.rs	Zero premature exits with $>15%$ unverified claims; non-zero unverified penalty
Knowledgebase MCP Search	crates/vox-orchestrator-mcp/tests/research_search_mcp_test.rs	vox_research_search tool execution, parameter parsing, and markdown output formatting
Slash Router & Intercept	crates/vox-gui/ui/src/lib/slashRouter.test.ts	Tokenization with quotes; flag extraction; alias routing
Memory Systems Sync	crates/vox-orchestrator/tests/memory_research_sync_test.rs	Header initialization in MEMORY.md; correct upsert_knowledge_node argument alignment
Competitive Benchmarks	crates/vox-research-shim/tests/deep_research_competitive_benchmarks_test.rs	Outdated API signature self-correction; stability metric convergence; empirical overrule of hallucinated claims

---

9. Governance & Maintenance Directives

1. No Direct Secret Access: All external search and LLM calls must resolve secrets via vox-secrets (Clavis); never access environment variables directly.
2. Model-Agnostic Facade: LLM repair prompts and claim extraction must use vox_actor_runtime::llm; never hardcode vendor-specific endpoints.
3. Windows PowerShell Safety: All subprocess and CLI automation must remain compatible with Windows PowerShell; never run workspace-wide cargo fmt --all (use cargo fmt -p <crate>).
4. SSOT Integrity: When altering stability equation weights or adding sandbox languages (e.g. Python, TypeScript), update this document, WaveExecutionPlan, and tests/stability_calibration_test.rs concurrently.