Local storage / explicit evidence
Understand what the database believes.
Tosumu is an experimental, single-file database engine for embedders who need durable local state without accepting an opaque storage boundary.
State and recovery evidence remain available to tools.
Failures are structured instead of hidden behind success-shaped APIs.
Small embedded use cases outrank server-database ambition.
Choose a path
Use
Build, open, inspect
Take the shortest path from a clean checkout to a database you can examine.
Getting started →Evaluate
Read guarantees first
Separate implemented behavior from intentional limits and future work.
Safety and limits →Integrate
Consume observations
Use the machine-readable inspection contract without parsing storage internals.
Inspect API →Current capability map
| Area | Maturity | Current claim |
|---|---|---|
| Storage engine | Implemented | Page-based key/value storage with B+ tree lookup |
| Recovery | Implemented | WAL-backed recovery with explicit diagnostics |
| Authenticated storage | Experimental | Authenticated pages and key protection; not audited |
| Inspection | Implemented | Read-only TUI and structured inspect output |
| Tosumu Command Language | Experimental | Bounded command/query surface under active validation |
| Sync and collaboration | Deferred | Reviews exist; no admitted synchronization contract |
Tosumu uses maturity words deliberately. Implemented describes observed behavior, not production readiness. Experimental identifies an active boundary that may change. Deferred is not a silent fallback.
How the pieces fit
application meaning
|
v
public storage and inspection contracts
|
v
pager -> B+ tree -> WAL -> authenticated pages
|
v
explicit observations and failures
The architecture is intentionally small enough to follow end-to-end. Start with Concepts for the model, then use Architecture for ownership and crate boundaries.
Engineering record
This site explains Tosumu's current meaning. GitHub preserves the complete path by which that meaning was discovered.
- Specifications define normative and current contracts.
- Accepted architecture decisions record binding design constraints.
- Project governance explains document authority.
- Document status separates current guidance, active work, speculation, and historical records.
Implementation plans, unresolved reviews, change-request internals, notes, and conversations remain engineering records rather than ordinary user guidance.