sochdb_kernel/
lib.rs

1// SPDX-License-Identifier: AGPL-3.0-or-later
2// SochDB - LLM-Optimized Embedded Database
3// Copyright (C) 2026 Sushanth Reddy Vanagala (https://github.com/sushanthpy)
4//
5// This program is free software: you can redistribute it and/or modify
6// it under the terms of the GNU Affero General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// This program is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU Affero General Public License for more details.
14//
15// You should have received a copy of the GNU Affero General Public License
16// along with this program. If not, see <https://www.gnu.org/licenses/>.
17
18//! # SochDB Kernel
19//!
20//! The minimal ACID core of SochDB with a plugin architecture.
21//!
22//! ## Architecture
23//!
24//! ```text
25//! ┌─────────────────────────────────────────────────────────────┐
26//! │                    Extension Layer                          │
27//! │  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐   │
28//! │  │ LSCS Plugin │ │Vector Plugin│ │ Observability Plugin│   │
29//! │  └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘   │
30//! │         │               │                    │              │
31//! │         ▼               ▼                    ▼              │
32//! │  ┌─────────────────────────────────────────────────────┐   │
33//! │  │              Plugin Manager (Registry)               │   │
34//! │  └─────────────────────────┬───────────────────────────┘   │
35//! └────────────────────────────┼────────────────────────────────┘
36//!                              │
37//! ┌────────────────────────────┼────────────────────────────────┐
38//! │                            ▼                                │
39//! │  ┌─────────────────────────────────────────────────────┐   │
40//! │  │                 Kernel API (Traits)                  │   │
41//! │  │   KernelStorage, KernelTransaction, KernelCatalog    │   │
42//! │  └─────────────────────────────────────────────────────┘   │
43//! │                                                             │
44//! │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
45//! │  │   WAL    │ │   MVCC   │ │  Pager   │ │   Catalog    │   │
46//! │  │ Recovery │ │   Txn    │ │  Buffer  │ │   Schema     │   │
47//! │  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
48//! │                                                             │
49//! │                     KERNEL (~5K LOC)                        │
50//! │              Auditable • Stable API • ACID                  │
51//! └─────────────────────────────────────────────────────────────┘
52//! ```
53//!
54//! ## Design Principles
55//!
56//! 1. **Minimal Core**: Only ACID-critical code in kernel (<5K LOC)
57//! 2. **Plugin Everything**: Storage backends, indices, observability are plugins
58//! 3. **No Dependency Bloat**: Core has minimal deps, plugins bring their own
59//! 4. **Stable API**: Kernel API is versioned, plugins can evolve independently
60//! 5. **Auditable**: Small enough for formal verification
61//!
62//! ## WASM Plugin System
63//!
64//! The kernel supports secure WASM-sandboxed plugins with:
65//! - Memory isolation (linear memory per plugin)
66//! - Fuel limits (instruction counting)
67//! - Capability-based access control
68//! - Hot-reload without restart
69
70pub mod atomic_claim; // Atomic claim protocol for queue operations (Task: Linearizable Dequeue)
71pub mod boot_fsm; // Deterministic Boot FSM with migration + recovery budgets (Production Task 1)
72pub mod error;
73pub mod kernel_api;
74pub mod page;
75pub mod plugin;
76pub mod plugin_hot_reload;
77pub mod plugin_manifest;
78pub mod python_sandbox;
79pub mod transaction;
80pub mod wal;
81pub mod wasm_host_abi;
82pub mod wasm_runtime;
83pub mod wasm_sandbox_runtime;
84
85// Re-exports for convenience
86pub use error::{KernelError, KernelResult};
87pub use kernel_api::{KernelCatalog, KernelStorage, KernelTransaction};
88pub use plugin::{
89    Extension, ExtensionCapability, ExtensionInfo, IndexExtension, ObservabilityExtension,
90    PluginManager, StorageExtension,
91};
92pub use transaction::{IsolationLevel, TransactionId, TransactionState, TxnManager};
93pub use wal::{LogSequenceNumber, WalManager, WalRecord, WalRecordType};
94
95// Boot FSM for production-grade lifecycle management
96pub use boot_fsm::{
97    BootBudgets, BootError, BootMetrics, BootOrchestrator, BootPhase, BootStateMachine,
98    HealthStatus, PhaseProgress, PreloadHints, RecoveryMode,
99};
100
101// Atomic claim protocol for queue operations
102pub use atomic_claim::{
103    AtomicClaimManager, ClaimResult, ClaimStats, ClaimToken, CompareAndSwap, LeaseConfig,
104    LeaseManager,
105};
106
107/// Kernel version for API stability tracking
108pub const KERNEL_VERSION: &str = env!("CARGO_PKG_VERSION");
109
110/// Kernel API version - bump when breaking changes occur
111pub const KERNEL_API_VERSION: u32 = 1;
112
113/// Maximum recommended kernel code size for auditability
114pub const MAX_KERNEL_LOC: usize = 5000;
sochdb_kernel/lib.rs

sochdb_kernel/
lib.rs
