How LLM Wiki Implements Cascade-Deletion Rules for Wiki Pages

LLM Wiki automatically removes orphaned wiki pages and cleans up vector-store entries when a raw source file is deleted, using a three-step matching process that preserves shared entity pages while eliminating source-specific summaries.

LLM Wiki is a Rust-based knowledge management system that maintains referential integrity between raw source files and generated wiki content. When users delete a source file, the application enforces cascade-deletion rules to prevent broken links and stale embeddings, ensuring the knowledge base remains consistent across filesystem, vector store, and Markdown index layers.

The Three-Step Cascade-Deletion Pipeline

According to the README section "File Deletion with Cascade Cleanup" (lines 36-46), the system executes a coordinated three-step pipeline whenever a raw source file is removed.

Step 1: Identifying Related Wiki Pages

The backend identifies affected wiki pages through three distinct matching methods:

• sources[] front-matter entries – The system scans YAML front-matter for any page listing the deleted file in its sources array.
• Source-summary page names – The specific page that summarizes the raw file (the source-summary page) is matched directly by name.
• Section references – Front-matter section references that explicitly point to the source file are detected and processed.

This multi-method approach ensures no orphaned relationships persist in the knowledge graph.

Step 2: Selective Deletion and Metadata Updates

Once identified, pages are processed according to their type:

• Source-summary pages are deleted outright, as they serve no purpose without their underlying source file.
• Entity and concept pages linked to multiple sources retain their content; only the deleted source's ID is removed from their sources[] array.
• Global index.md is refreshed to remove entries for deleted pages, maintaining an accurate table of contents.

This selective approach preserves shared knowledge while cleaning up source-specific artifacts.

Step 3: Wikilink Cleanup and Reference Integrity

After targeted deletions complete, the system performs a final sanitization pass:

• Dead [[wikilinks]] pointing to now-missing pages are pruned from remaining wiki files.
• Internal reference maps are rebuilt to reflect the new file structure.

This ensures the wiki remains free of broken internal links that would otherwise degrade the user experience.

Backend Implementation in Rust

The cascade-deletion logic is orchestrated by Rust backend commands located in src-tauri/src/, with specific responsibilities divided across modules.

File System Operations (fs.rs)

The delete_file command in src-tauri/src/commands/fs.rs (lines 1704-1714) handles the low-level filesystem deletion and reports success or failure to the command router. This function performs the initial removal that triggers the subsequent cascade.

// Located in src-tauri/src/commands/fs.rs
#[tauri::command]
pub async fn delete_file(path: String) -> Result<(), String> {
    std::fs::remove_file(&path)
        .map_err(|e| format!("Failed to delete {}: {}", path, e))?;
    Ok(())
}

Vector Store Cleanup (vectorstore.rs)

To prevent deleted content from appearing in semantic searches, the system invokes vector_delete_page in src-tauri/src/commands/vectorstore.rs (lines 279-306). This function removes associated vector-store entries for each deleted or updated wiki page, ensuring the embedding database stays synchronized with the filesystem.

// Located in src-tauri/src/commands/vectorstore.rs
#[tauri::command]
pub async fn vector_delete_page(page_id: String) -> Result<(), String> {
    // Removes vector chunks associated with the deleted page
    // Implementation spans lines 279-306
    delete_embeddings(&page_id).await
}

Command Routing and Orchestration (lib.rs)

The Tauri command router in src-tauri/src/lib.rs maps frontend requests to the appropriate backend actions. When the UI invokes deletion commands, the router coordinates between delete_file, the three-step matching logic, and vector_delete_page to execute the complete cascade atomically.

Practical Implementation Examples

Triggering Cascade Deletion via HTTP API

You can initiate cascade deletion by calling the local API endpoint, which forwards to commands::fs::delete_file and subsequently triggers the cleanup pipeline:

POST /api/v1/projects/123/sources/delete
Content-Type: application/json

{
  "path": "raw/sources/research_paper.pdf"
}

After the file is removed, the backend automatically:

1. Scans for pages with matching sources[] entries in their front-matter.
2. Deletes the corresponding source-summary page.
3. Calls vector_delete_page for each affected page to purge vector chunks.
4. Updates index.md and rewrites remaining pages to strip dead [[wikilinks]].

Frontend Invocation from React

From a React component, invoke the Tauri commands directly to trigger the cascade:

import { invoke } from '@tauri-apps/api/tauri';

async function deleteSourceAndCascade(projectId: string, sourcePath: string) {
  // Delete the raw source file
  await invoke('delete_file', { path: sourcePath });
  
  // Trigger orchestrated cascade cleanup
  await invoke('cascade_delete_source', { projectId, sourcePath });
}

The cascade_delete_source command guarantees that all linked wiki pages, vector entries, and index references update consistently, handling the three-method matching logic internally.

Verifying Cascade Behavior in Tests

The following Rust test demonstrates that entity pages survive source deletion while their sources[] arrays are correctly pruned:

#[tokio::test]
async fn test_cascade_deletion() {
    // Setup: create source and dependent wiki page
    create_source("raw/sources/foo.pdf").await;
    create_wiki_page("wiki/concepts/bar.md", r#"
        ---
        title: Bar
        sources: ["raw/sources/foo.pdf"]
        ---
        Content...
    "#).await;

    // Execute deletion
    delete_file("raw/sources/foo.pdf".into()).await.unwrap();

    // Verify: page exists but source reference removed
    let page = read_wiki_page("wiki/concepts/bar.md").await;
    assert!(!page.contains("raw/sources/foo.pdf"));
}

This test validates the core cascade-deletion rule: shared knowledge persists while specific source bindings are removed.

Summary

• Three-method matching identifies affected pages via sources[] arrays, source-summary page names, and section references in front-matter.
• Selective preservation deletes source-summary pages outright while updating entity pages to remove only the deleted source ID from their metadata.
• Vector store synchronization via vector_delete_page prevents stale embeddings from appearing in search results.
• Reference integrity is maintained through automated index.md updates and dead wikilink pruning across the wiki.
• Rust backend coordinates these actions through commands in fs.rs, vectorstore.rs, and lib.rs.

Frequently Asked Questions

What happens to wiki pages that reference multiple source files?

Entity and concept pages linked to multiple sources retain their full content and structure. Only the specific deleted source's ID is removed from the page's sources[] array in the YAML front-matter, preserving shared knowledge while maintaining accurate provenance metadata.

How does the system identify which pages to delete versus update?

The system applies three matching methods defined in the README: it checks for the deleted file in page sources[] arrays, matches against the source-summary page name, and scans section references in front-matter. Source-summary pages are deleted entirely, while other matched pages are updated to remove only the specific source reference.

Does deleting a source file affect the vector search functionality?

Yes. The system calls vector_delete_page (implemented in src-tauri/src/commands/vectorstore.rs) to remove embeddings associated with deleted wiki pages. This ensures that semantic searches do not return results pointing to content that no longer exists in the filesystem.

Can cascade deletion be triggered programmatically from a custom frontend?

Absolutely. Frontend applications can invoke the delete_file command for low-level deletion or use cascade_delete_source for full orchestrated cleanup. Both commands are exposed through Tauri bindings in src-tauri/src/lib.rs, allowing React, Vue, or other frameworks to trigger the complete three-step pipeline via standard invoke calls.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}