Turso Source Ref

Referencing the Turso source

Ahtola's goal is to stay as aligned as possible with Turso's design and capabilities — it is a pure-managed C# port of Turso's Rust core, not an independent engine. The turso-src/ git submodule (pinned to a release tag, currently v0.7.2) is the source of truth for "how does Turso do this?". Always consult the Rust source before designing or changing a behavior that has an upstream counterpart, and mirror Turso's structure, naming, and semantics where the managed/AOT constraints allow.

First, make sure the submodule is present

git submodule update --init --recursive

turso-src/ is read-only reference material. Never edit files there, never add it to a shipped project's item groups, and never package anything from it. It is not compiled or shipped by Ahtola.

Where things live in Turso → Ahtola

Use this map to jump to the right Rust source for a C# type you are working on:

The on-disk SQLite file format Turso implements is the same format Ahtola.Core/Storage must read/write — see docs/wal-interoperability-contract.md for the WAL interop target.

How to search effectively

Prefer grepping the submodule directly over fetching Turso sources from the web:

# Find the Rust type/function a C# port mirrors
rg -n 'struct Page'      turso-src/core/storage
rg -n 'fn btree_init'    turso-src/core
rg -n 'VdbeOp'           turso-src/core/vdbe

# Find every upstream symbol named in a C# doc comment
rg -n '<symbol-in-the-doc-comment>' turso-src

When a C# type's doc comment or the WAL contract names an upstream Rust symbol, treat that as the primary citation: open the Rust file, read the surrounding impl, and mirror the invariants (page sizes, header offsets, opcodes, error conditions) in the C# port.

Stay aligned, then adapt to managed constraints

When porting, preserve Turso's behavior and on-disk format exactly where the contract requires it (file format, WAL framing, VDBE opcode semantics, SQL dialect). Adapt the implementation language to C# / .NET idioms only where there is no format/semantic contract:

• Replace Turso's cooperative IOResult/Completion state-machine IO with async/await or synchronous managed IO — the semantics (what a read at offset X must return) must match, not the call style.
• Keep Ahtola.Core NativeAOT/trim-clean (see AGENTS.md). Do not port Rust traits/patterns that require runtime reflection or dynamic codegen.
• Do not introduce a native companion. Turso types under turso-src/sync/sdk-kit/ reference the native turso_sdk_kit — those are reference only. Ahtola's intentional Turso.* companion-load strings (Turso.Data.Native, Turso.Data.Sync) load optional assemblies by name and fail closed; that is a product decision, not something to "port over".

Bump the submodule when you port a newer release

If you need behavior from a newer Turso release, bump the submodule to that tag in the same change that ports the behavior, and note the new tag in the commit message and in AGENTS.md:

cd turso-src
git fetch --tags origin
git checkout <new-tag>        # e.g. v0.8.0
cd ..
git add turso-src             # records the new Subproject commit

Prefer release tags over main so the reference is reproducible.

Quick checklist before landing a port

• Found and read the matching Rust source in turso-src/ (cite the file and symbol in the PR description or a C# doc comment).
• Mirrored the upstream invariants (format, offsets, opcode/error semantics) — not just "produces the same output on the happy path".
• No native/Rust toolchain, no DllImport/LibraryImport, no AOT/trim breakage introduced (see AGENTS.md).
• If you bumped turso-src/, the new tag is recorded in the commit message and AGENTS.md.