Skip to main content

Rust Crates

Heavy computational tasks in Basalt are never executed in the JavaScript webview thread. Instead, parsing, indexing, search, physics simulation, query planning, and plugin sandboxing are partitioned into dedicated Rust crates under crates/ and plugins/.

Each crate follows single-responsibility architecture (ADR-009, ADR-030) with explicit dependency boundaries.

Workspace Crate Map​

crates/
├── basalt-types      Canonical domain structs (FileMetadata, TaskData, TypedValue)
├── basalt-parser     Zero-AST SIMD scanner for markdown, frontmatter, and DQL
├── basalt-vault      Parallel vault crawler, Rayon indexing, bincode disk cache
├── basalt-tables     DQL execution engine, task queries, aggregations, 3VL logic
├── basalt-task       Task signifier grammar, status cycle, urgency scoring
├── basalt-search     Tantivy full-text search engine + Nucleo fuzzy matching
├── basalt-graph      Link graph topology, backlinks, force simulation
├── basalt-canvas     Infinite spatial canvas data model and edge routing
├── basalt-drawing    Vector sketchpad and drawing document interchange
├── basalt-kanban     Kanban board columns and card state serialization
└── basalt-calendar   Daily note resolution and calendar date math

plugins/
├── host              Wasmtime plugin host, sandboxing, capability enforcement
└── sdk               Guest Rust SDK for compiling WebAssembly plugins

apps/tauri/src-tauri  Tauri 2.0 shell, window management, and typed IPC commands

Crate Responsibilities​

1. basalt-types​

The foundational data contract. Defines core models shared across the Rust backend and serialized over IPC to the React frontend:

  • FileMetadata: Frontmatter, tags, links, headings, block IDs, and tasks.
  • TaskData, TaskStatus, TaskPriority: Strongly typed task structures.
  • TypedValue: Three-valued logic type system for query results.

2. basalt-parser​

High-throughput scanner using SIMD vector instructions (memchr3):

  • Tier 1 (ASCII fast-path): Scans frontmatter boundaries, headings, links, and - [ ] task markers with zero heap allocations.
  • Tier 2 (Unicode fallback): Gracefully handles multi-byte UTF-8 glyphs.
  • DQL parser: nom-free recursive descent parser for query statements.

3. basalt-vault​

The file management and indexing coordinator:

  • Multi-threaded parallel file crawling powered by Rayon.
  • Instant two-tier boot (ADR-046): loads pre-compiled bincode caches from disk in <100ms before triggering background mtime diff checks.
  • Debounced file watcher event stream synchronization.

4. basalt-tables​

Dataview Query Language and task query processor:

  • Implements predicate push-down, Schwartzian transform sorting, and bounded Top-K heap selection.
  • Resolves GROUP BY, FLATTEN, and aggregate calculations.

5. basalt-task​

Encapsulates task line grammar and mutation logic:

  • Checkbox character mapping ([ ] → [/] → [x]).
  • Date signifier injection (📅, 🛫, ⏳, ✅, ❌).
  • Composite urgency calculation scoring.

Desktop-tier search infrastructure:

  • Tantivy: BM25 schema-based full-text inverted index for lightning-fast keyword search across note bodies.
  • Nucleo: Memory-mapped fuzzy search engine for instant note title and path jumping.

7. basalt-graph​

Vault relational graph:

  • Maintains in-memory adjacency lists for forward links and backlinks.
  • Calculates link neighborhood degrees and isolates.
  • Runs 2D velocity Verlet force-directed physics layout.

8. plugins/host & plugins/sdk​

WASM component model plugin engine (ADR-054):

  • Sandboxed execution via wasmtime with memory caps and CPU preemption.
  • Strict capability enforcement (vault:read, editor:cm6, net:http).