# Contributor handoff — sqlite/sqlite

> Canonical page: https://codevetter.com/unpack/sqlite/agent-handoff

# Contributor handoff — sqlite/sqlite

Scanned commit fde3a84dddf35f4c19797c8afad04a44c596f4d8 (2026-09-21). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

The hard constraints here are unusual and worth internalizing before touching anything: this is public-domain C with no license headers ever added, it is developed in Fossil (the Git remote is a mirror with different check-in names), and AGENTS.md states outright that the project does not accept agentic code — agentic *bug reports with reproducible test cases* are welcome, and patches are accepted only as proof-of-concept documentation. Practically, that means the safe posture is: read, reproduce, write a `.test` case, and propose rather than land. When editing is in scope, the rules are C89/C99 only, `sqlite3Malloc` family for all allocation, `i64`/`u32`/`u64` for width-sensitive values, `SQLITE_OK`/`SQLITE_*` return codes, liberal `assert` with `ALWAYS`/`NEVER` for compiler-opaque invariants, and never touching a generated file. Always run at least `make devtest` after any `src/` change.
- Read first, in this order: `AGENTS.md` (project constraints and generated-file table), `README.md` (source tree map and build instructions), `src/sqliteInt.h` (6,031 lines — the master internal header), and `src/sqlite.h.in` (the public API template and the source of the API docs). — [AGENTS.md](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/AGENTS.md) [README.md#L175-L215](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/README.md#L175-L215) [src/sqliteInt.h](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/sqliteInt.h) [src/sqlite.h.in](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/sqlite.h.in)
- Never add a copyright or license header: every file carries the intentional 'May you do good and not evil' blessing comment instead, and adding a header would jeopardize the public-domain status the project depends on. — [AGENTS.md](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/AGENTS.md) [LICENSE.md](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/LICENSE.md) [src/pager.c#L1-L12](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/pager.c#L1-L12) [test/fuzzcheck.c#L1-L10](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/test/fuzzcheck.c#L1-L10)
- Do not hand-edit generated files: `sqlite3.h` (from `tool/mksqlite3h.tcl`), `parse.c`/`parse.h` (lemon on `src/parse.y`), `opcodes.h`/`opcodes.c` (`mkopcodeh.tcl`/`mkopcodec.tcl`), `keywordhash.h` (`tool/mkkeywordhash.c`), `pragma.h` (`tool/mkpragmatab.tcl`), `sqlite3.c` (`tool/mksqlite3c.tcl`). — [AGENTS.md](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/AGENTS.md) [tool/mksqlite3h.tcl](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/tool/mksqlite3h.tcl) [tool/mkkeywordhash.c](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/tool/mkkeywordhash.c) [tool/mkpragmatab.tcl](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/tool/mkpragmatab.tcl) [tool/mksqlite3c.tcl](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/tool/mksqlite3c.tcl)
- Build for development with `./configure --dev`, which `auto.def` translates into `--all --debug`, amalgamation *off* (so each `src/*.c` compiles separately and errors point at real files), and `CFLAGS=-O0 -g`. — [auto.def#L20-L35](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/auto.def#L20-L35) [README.md#L118-L124](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/README.md#L118-L124)
- The configure script is autosetup, not GNU Autoconf, and must stay JimTCL-compatible — `autosetup/jimsh0.c` is bundled so the tree can configure without a system tclsh. Project-specific procs are prefixed `sqlite-` (in `autosetup/sqlite-config.tcl`), generic ones `proj-` (in `autosetup/proj.tcl`). — [auto.def#L1-L19](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/auto.def#L1-L19) [autosetup/jimsh0.c](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/autosetup/jimsh0.c) [autosetup/sqlite-config.tcl](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/autosetup/sqlite-config.tcl) [autosetup/proj.tcl](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/autosetup/proj.tcl)
- Tests need TCL: install `tcl-dev`, run `make tclextension-install` before `make devtest`, and note that `testrunner.tcl` will try to re-exec itself under `./testfixture` if `package require sqlite3` fails. — [AGENTS.md](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/AGENTS.md) [main.mk#L1719](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/main.mk#L1719) [test/testrunner.tcl#L26-L60](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/test/testrunner.tcl#L26-L60) [README.md#L128-L136](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/README.md#L128-L136)
- Minimum test bar for any `src/` change is `make devtest` (`srctree-check` + `sourcetest` + `testrunner.tcl mdevtest`); targeted runs use `./testfixture test/<file>.test` or `test/testrunner.tcl fts5%` pattern matching, and failures are found with `grep '!' testrunner.log`. — [main.mk#L1860-L1876](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/main.mk#L1860-L1876) [AGENTS.md](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/AGENTS.md) [doc/testrunner.md#L28-L60](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/doc/testrunner.md#L28-L60)
- Coding conventions to match: C89/C99 only (no C++/VLAs), all allocation through `sqlite3Malloc`/`sqlite3MallocZero`/`sqlite3_malloc64` rather than raw `malloc`, `i64`/`u32`/`u64` instead of bare `long`/`int` for values that can exceed 2G, `SQLITE_OK`-style return codes with `db->mallocFailed` for deferred OOM detection. — [AGENTS.md](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/AGENTS.md) [src/main.c#L3448-L3450](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/main.c#L3448-L3450) [src/prepare.c#L727-L731](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/prepare.c#L727-L731)
- `assert()` is used as executable documentation throughout and is expected in new code; use `ALWAYS(x)`/`NEVER(x)` for conditions the compiler cannot prove — e.g. `ALWAYS(cnt<=SQLITE_MAX_PREPARE_RETRY)` in the prepare retry loop and `NEVER(pPager->errCode)` in commit. — [AGENTS.md](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/AGENTS.md) [src/prepare.c#L883-L886](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/prepare.c#L883-L886) [src/pager.c#L6542](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/pager.c#L6542)
- Requirement-traceability comments matter: `EVIDENCE-OF: R-#####-#####` markers in the sources tie code to numbered statements in the external documentation (e.g. in `sqlite3_prepare_v2`/`_v3`), and `testcase()` markers mark branches the test suite is expected to cover — preserve both when editing. — [src/prepare.c#L957-L963](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/prepare.c#L957-L963) [src/prepare.c#L975-L982](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/prepare.c#L975-L982) [src/vdbe.c#L952](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/vdbe.c#L952)
- Match the file's existing idiom: this codebase uses two-space indentation, `if( cond ){` spacing with no space after `if`, `/* ... */` block comments only, and `**` comment continuation banners — deviating is immediately visible in diffs. — [src/pager.c#L6527-L6560](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/pager.c#L6527-L6560) [src/vdbeapi.c#L838-L870](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/vdbeapi.c#L838-L870)
- Safe edit boundaries: `ext/misc/*.c` single-file extensions and `test/*.test` scripts are the lowest-risk places to add code; `src/btree.c`, `src/pager.c`, `src/wal.c`, `src/vdbe.c` and `src/where.c` are the highest-risk and should not be touched without a reproducing test. — [ext/misc/series.c](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/ext/misc/series.c) [test/main.test](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/test/main.test) [src/btree.c](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/btree.c) [src/wal.c](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/wal.c) [AGENTS.md](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/AGENTS.md)
- Known trap: the CLI is not built from `src/shell.c` — that file does not exist in the tree. Edit `src/shell.c.in` and let the build's `INCLUDE`-processing step produce `shell.c`. — [src/shell.c.in](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/shell.c.in) [main.mk#L2186](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/main.mk#L2186) [tool/mkshellc.tcl](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/tool/mkshellc.tcl)
- Known trap: when reporting a check-in, use the official Fossil name from `manifest.uuid` (`c9b4695ffae5a3388a49643d6819355851a0fda362cdaf140c59fc934759dcac`), not the Git SHA — the README states these differ for all mirrors. — [manifest.uuid](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/manifest.uuid) [README.md#L16-L30](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/README.md#L16-L30)
- Useful debugging levers already in-tree: `SQLITE_DEBUG_BREAK` env var (shell attaches a debugger), `PRAGMA vdbe_trace`/`vdbe_listing`/`vdbe_eqp` via `SQLITE_VdbeTrace` flags in `sqlite3VdbeExec`, `SQLITE_ParserTrace` in `sqlite3RunParser`, and the `.wheretrace`/`.iotrace` dot-commands. — [src/shell.c.in#L14057-L14078](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/shell.c.in#L14057-L14078) [src/vdbe.c#L962-L985](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/vdbe.c#L962-L985) [src/tokenize.c#L621-L628](https://github.com/sqlite/sqlite/blob/fde3a84dddf35f4c19797c8afad04a44c596f4d8/src/tokenize.c#L621-L628)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)