{"owner":"tursodatabase","repo":"turso","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"files":{"AGENTS.md":"# Turso Agent Guidelines\n\nSQLite rewrite in Rust. 40+ crate workspace.\n\n## Quick Reference\n\n```bash\ncargo build                    # build. never build with --release\ncargo test                     # rust unit/integration tests\ncargo fmt                      # format (required)\ncargo clippy --workspace --all-features --all-targets -- --deny=warnings  # lint\ncargo run -q --bin tursodb -- -q # run the interactive cli. never run with --release\n\nmake test                      # TCL compat + sqlite3 + extensions + MVCC\nmake test-single TEST=foo.test # single TCL test\nmake -C sqlite/conformance run-rust ARGS='--snapshot-filter __never__'  # sqltest runner (preferred for new tests)\nCI=1 make -C sqlite/conformance run-rust  # use only if snapshot tests are required\n\nscripts/diff.sh \"SQL\" [label]  # compare sqlite3 vs tursodb output\n```\n\n## Testing\n\n### Running Tests\n\n- `cargo test` - Rust unit and integration tests\n- `make test` - broad compatibility suite (TCL, sqlite3, extensions, MVCC)\n- `make test-single TEST=foo.test` - single legacy TCL test\n- `make -C sqlite/conformance run-rust ARGS='--snapshot-filter __never__'` - preferred `.sqltest` runner for new coverage\n- `CI=1 make -C sqlite/conformance run-rust` - only when snapshot tests are required\n\n### Test Organization\n\nDefault: add coverage to the narrowest existing test harness that can express the bug. Prefer extending an existing test file or directory over creating a new one.\n\n- `sqlite/conformance/sqlite-sqltests/` - preferred for SQL conformance coverage. These tests run the same scenario against both Turso and SQLite, so use them first for parser, planner, executor, and SQL semantics work that fits the `.sqltest` DSL.\n- `tests/integration/` - primary fallback when the behavior cannot be expressed cleanly in `.sqltest`. Put API-level regressions, multi-connection orchestration, storage assertions, injected failures, timeout behavior, and other Rust-driven scenarios here.\n- `sqlite/conformance/upstream/` - imported upstream SQLite golden tests. Do not modify these for Turso behavior changes; use them as fixed compatibility coverage, and only touch them for intentional upstream sync or harness maintenance.\n- `postgres/conformance/pg-sqltests/` - `.sqltest` coverage for the PostgreSQL frontend, run via `make -C postgres/conformance run` (spawns a tursopg server per test and drives it over the wire protocol). Only assert behavior real PostgreSQL also exhibits, so the corpus stays valid for differential runs.\n- `testing/cli_tests/` - CLI-focused Python coverage for shell behavior and end-to-end command workflows.\n- `tests/fuzz/` - minimized fuzz regressions and targeted edge cases that are easier to keep as Rust tests.\n- `testing/simulator/` and `testing/concurrent-simulator/` - deterministic concurrency, scheduling, and failure-injection coverage for state-machine and I/O correctness.\n- `testing/differential-oracle/` and `testing/stress/` - differential and long-running stress tooling. Use these for deeper investigation or specialized validation, not as the first stop for a focused regression test.\n\n## Structure\n\n```\nlimbo/\n├── core/           # Database engine (translate/, storage/, vdbe/, io/, mvcc/)\n├── sqlite/\n│   └── parser/     # SQL parser (lexer, AST, grammar)\n├── cli/            # tursodb CLI (REPL, MCP server, sync server)\n├── bindings/       # Python, JS, Java, .NET, Go, Rust\n├── extensions/     # crypto, regexp, csv, fuzzy, ipaddr, percentile\n├── testing/        # simulator/, concurrent-simulator/, differential-oracle/\n├── sync/           # engine/, sdk-kit/ (Turso Cloud sync)\n├── sdk-kit/        # High-level SDK abstraction\n└── tools/          # dbhash utility\n```\n\n## Where to Look\n\n| Task | Location | Notes |\n|------|----------|-------|\n| Query execution | `core/vdbe/execute.rs` | 12k LOC bytecode interpreter |\n| SQL compilation | `core/translate/` | AST → bytecode, optimizer in `optimizer/` |\n| B-tree/pages | `core/storage/btree.rs` | 10k LOC, SQLite-compatible format |\n| WAL/durability | `core/storage/wal.rs` | Write-ahead log, checkpointing |\n| SQL parsing | `sqlite/parser/src/parser.rs` | 11k LOC recursive descent |\n| Add extension | `extensions/core/` | ExtensionApi, scalar/aggregate/vtab traits |\n| Add binding | `bindings/` | PyO3, NAPI, JNI, FRB, CGO patterns |\n| Deterministic tests | `testing/simulator/` | Fault injection, differential testing |\n| New SQL tests | `sqlite/conformance/sqlite-sqltests/` | `.sqltest` format preferred |\n| Quick sqlite3 diff | `scripts/diff.sh` | Compare sqlite3 vs tursodb output for a query |\n| MVCC testing REPL | `cli/mvcc_repl.rs` | Multi-conn concurrent txn testing REPL        |\n\n## Guides\n\n- **[Testing](docs/agent-guides/testing.md)** - test types, when to use, how to write\n- **[Code Quality](docs/agent-guides/code-quality.md)** - correctness rules, Rust patterns, comments\n- **[Debugging](docs/agent-guides/debugging.md)** - bytecode comparison, logging, sanitizers\n- **[PR Workflow](docs/agent-guides/pr-workflow.md)** - commits, CI, dependencies\n- **[Transaction Correctness](docs/agent-guides/transaction-correctness.md)** - WAL, checkpointing, concurrency\n- **[Storage Format](docs/agent-guides/storage-format.md)** - file format, B-trees, pages\n- **[Async I/O Model](docs/agent-guides/async-io-model.md)** - IOResult, state machines, re-entrancy\n- **[MVCC](docs/agent-guides/mvcc.md)** - experimental multi-version concurrency (WIP)\n\n## Commit Messages\n\nUse an optional component scope followed by a lowercase imperative summary with\nno trailing period:\n\n```text\n[scope: ]<imperative summary>\n\n<why the change is needed and what invariant or bug it addresses>\n\n<non-obvious implementation details or tradeoffs, if needed>\n\nTests: <relevant validation, if useful>\n\nFixes #1234\n```\n\nFor example: `core/mvcc: preserve B-tree cleanup markers in commit logs`.\nExplain intent rather than narrating the diff. Omit the body only when the\nsubject fully explains a trivial change. Conventional Commit prefixes such as\n`feat(scope):` are not required. See [CONTRIBUTING.md](CONTRIBUTING.md) for a\ncomplete example.\n\n## Benchmark Naming\n\n- Criterion benchmark functions must use `#[turso_macros::codspeed_criterion_benchmark]` so stable and nightly CodSpeed runs get distinct benchmark names.\n- Divan benchmark functions must use `#[turso_macros::divan_bench]` for the same stable/nightly naming behavior.\n\n## Core Principles\n\n1. **Correctness paramount.** Production DB, not a toy. Crash > corrupt\n2. **SQLite compatibility.** Compare bytecode with `EXPLAIN`\n3. **Every change needs a test.** Must fail without change, pass with it\n4. **Assert invariants.** Don't silently fail. Don't hedge with if-statements\n5. **Own your regressions.** If tests fail after your change, they are your regressions. Debug them directly. Never stash/revert to \"check if they fail on main\" — that wastes time and is categorically banned.\n6. **Validate your hypotheses.**: If you suspect a given cause for a bug, validate it and provide incontrovertible evidence. NEVER make unearned assumptions.\n\n## Always use plain language instead of complex jargon\n\nOOGA BOOGA! Programming already complex! Use simple word! Say what you mean! Examples:\n\n```diff\n-    /// Number of generated statements outside the engines' shared executable domain.\n+    /// Number of statements skipped because EXPLAIN failed in at least one engine.\n\n...\n\n-    fn empty_schema_only_selects_bootstrap_safe_statements() {\n+    fn empty_schema_never_chooses_a_statement_that_needs_a_table() {\n```\n\nNo-one knows what the hell a bootstrap-safe statement is. Everyone knows what \"a statement that needs a table\" is.\n\n## CI Note\n\nRunning 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.\n"}}