feat(cpp): SQLite integration and gaia::Database

[kovtcharov]

The C++ framework had no database. SessionStore and AllowedToolsStore persist as loose JSON files, so agent memory, scratchpad tables, and the email agent's state store had nothing to build on — and no C++ agent could do full-text search at all. This lands SQLite as a first-class part of gaia_core: #include <gaia/database.h> and you get an RAII connection, prepared statements, transactions, ordered schema migrations, and FTS5, with no package to install and no system SQLite to find. It ships with no consumer by design — it is the foundation Phase 5 and the email milestone build on.

The amalgamation is vendored rather than fetched, deliberately: a distro SQLite may lack FTS5 or carry different compile-time defaults, and that only surfaces at query time on one platform. Vendoring makes Windows, Linux, and macOS compile byte-identical sources with identical flags. Because a missing SQLITE_ENABLE_FTS5 builds fine and fails only when someone runs a query, three tests exist purely to catch that — verified by building with the flag removed: the build still succeeded and all three failed with no such module: fts5.

CI build-time impact (issue asks for it) — clang -O3, Apple M4; the delta is one extra translation unit:

Measurement	main	this PR	delta
Serial build (-j1), whole cpp/ tree	82.6s	92.3s	+9.7s (+12%)
sqlite3.c alone (best of 3)	—	9.2s	one TU, the longest in the build
database.cpp + test_database.cpp	—	1.7s
Parallel wall-clock (-j4, runner width)			+3–7s, run-to-run noise exceeds the signal

Incremental builds are unaffected — sqlite3.c only recompiles when the amalgamation or its flags change. Repo grows 10.2 MB in the working tree (~2.6 MB compressed in git). One-time cost worth flagging: the FetchContent cache key is hashFiles('cpp/CMakeLists.txt'), which this PR changes, so the first run on each OS re-fetches json/httplib/ftxui/gtest.

Three things a reviewer may want to know the reasoning for: the version file is SQLITE_VERSION.txt rather than VERSION because the directory is on the include path and a case-insensitive filesystem resolves #include <version> to it, breaking every TU in gaia_core (this bit during development); the amalgamation is an OBJECT library consumed via $<TARGET_OBJECTS:> rather than target_link_libraries so it stays out of gaia_core's link interface and install(EXPORT) has nothing extra to resolve; and .gitattributes marks the vendored sources -diff so 9.5 MB stays out of every diff (the reviewable diff is 2,554 lines).

Closes #2793

Test plan

• cmake -S cpp -B cpp/build -DGAIA_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Release && cmake --build cpp/build --parallel && ctest --test-dir cpp/build — 519/519 pass (463 pre-existing + 56 new), zero new warnings
• FTS5 flag actually takes: virtual table creation, MATCH, bm25() ranking, prefix queries, and update/delete reindexing
• Negative control — rebuild with SQLITE_ENABLE_FTS5 removed: build still succeeds, all 3 FTS5 tests fail with no such module: fts5
• CRUD via prepared statements; typed binds for every storage class including NULL, blobs with embedded NULs (256-byte round-trip), text with an embedded NUL, and empty-blob-is-not-NULL
• Transactions: commit, implicit rollback, rollback on a throwing scope, explicit rollback, IMMEDIATE, and nested savepoints
• Migration from an older on-disk schema (v1 → v3) preserving existing rows; idempotent re-run; resume after a partially-applied step; failing step rolls back and keeps the old version; malformed step lists and downgrades refused
• busy_timeout with a concurrent writer thread — the waiter blocks ~300 ms and succeeds; counterpart test with busyTimeoutMs = 0 fails immediately, proving the timeout did the work
• Install round-trip: cmake --install then a find_package(gaia_core) consumer that opens a database, creates an FTS5 table, and queries it — links and runs (sqlite=3.53.4 fts5=1 hits=1) without sqlite3.h on its include path
• BUILD_SHARED_LIBS=ON shared-library build links cleanly
• Upstream authenticity: SHA3-256 of the downloaded zip matches sqlite.org's published manifest (628a44cf…); both checksums recorded in SQLITE_VERSION.txt
• No handle leak when construction throws after sqlite3_open_v2 succeeds — leaks reports 0; negative control with the fix removed reports 61 leaks / 161,680 bytes

[github-actions]

Verdict: Approve ✅

This adds a vendored SQLite amalgamation and a RAII gaia::Database wrapper (connection, prepared statements, transactions, and versioned schema migrations) to the C++ SDK, with a comprehensive GoogleTest suite and API docs. The design is exemplary and lands squarely on GAIA's "fail loudly, no silent fallbacks" philosophy — no find_package fallback, WAL that can't take is a loud error rather than a mystery SQLITE_BUSY later, and every SQLite failure raises DatabaseError carrying the code, db path, and offending SQL.

The one thing worth a glance before merge is minor and non-blocking: the two security-hardening connection settings (disabling extension loading, enabling defensive mode) don't check their return code, while the adjacent busy_timeout call does — a small consistency gap against the fail-loudly rule, not a correctness bug.

Real-world evidence

N/A — this is a C++ SDK library, not a Python Agent-UI / CLI / MCP / HTTP surface, so none of the rubric's evidence surfaces apply. The appropriate proof for this layer is ctest, and the PR ships a thorough cpp/tests/test_database.cpp (lifecycle, every storage class incl. embedded-NUL blobs/text, WAL/busy-timeout under a real concurrent-writer thread, the full migration chain incl. partial-apply resume and downgrade refusal, and FTS5/BM25). No evidence bundle was produced for this run; verdict rests on static review plus the included test coverage.

🔍 Technical details

🟢 Minor — unchecked return on the two hardening sqlite3_db_config calls (cpp/src/database.cpp, constructor)

busy_timeout checks its rc and fail()s, but the two sqlite3_db_config calls that disable extension loading and enable defensive mode ignore theirs. These opcodes don't realistically fail on a freshly-opened handle, so this is cosmetic — but a silently-failing security config is exactly the kind of thing the fail-loudly rule targets, and checking it keeps the constructor internally consistent. For example:

        if (sqlite3_db_config(db_, SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION, 0, nullptr) != SQLITE_OK) {
            fail("cannot disable extension loading", sqlite3_errcode(db_));
        }
        // Defensive mode: SQL cannot corrupt the schema or write FTS5 shadow tables.
        if (sqlite3_db_config(db_, SQLITE_DBCONFIG_DEFENSIVE, 1, nullptr) != SQLITE_OK) {
            fail("cannot enable defensive mode", sqlite3_errcode(db_));
        }

(Only wire this if fail()/sqlite3_errcode are reachable at that point; otherwise a plain rc-check + throw matching the surrounding style is fine. Your call — it's a nit.)

Strengths

• Fail-loudly done right. The WAL-mode verification (cpp/src/database.cpp) reads back PRAGMA journal_mode and throws with an actionable message ("network mount? set Options::walMode = false") rather than letting a silently-non-WAL database surprise the caller later. Same spirit in the empty-path rejection, the downgrade refusal in migrate(), and DatabaseError carrying code/dbPath/sql.
• Clean dependency hygiene. sqlite3.h is forward-declared in the public header so consumers of gaia_core never need it on their include path; the OBJECT-library + $<TARGET_OBJECTS:> approach keeps SQLite out of the install export set and its warnings out of -Wall/-W4, matching how the file already handles httplib/json.
• Migrations mirror the Python MemoryStore model (ordered steps, PRAGMA user_version, idempotent addColumnIfMissing, per-step transaction that also stamps the version) — so a step that dies half-way is safely re-runnable, and the tests prove exactly that (MigrateResumesAfterAPartiallyAppliedStep).
• Test coverage is genuinely adversarial, not box-checking: embedded-NUL round-trips, SQLITE_DQS=0 enforcement, real two-thread busy-timeout contention with a timing assertion, and an FTS5 BM25-ranking check that a stub module couldn't pass.
• Docs and vendoring are honest — SQLITE_VERSION.txt records both checksums, the README calls out the SHA3-256 (not SHA-256) gotcha and the <version> header collision, and .gitattributes keeps the 9 MB amalgamation out of every diff.

[kovtcharov]

The failing C++ Integration Tests (STX) check is not this PR

Diagnosed during the milestone #63 sweep — all three open Wave 1 PRs (#2807, #2809, #2816) fail this same check, and none for a reason related to their diffs. The build never reaches compilation:

CMake Error: Could not find CMAKE_ROOT !!!
Modules directory not found in
C:/Windows/Temp/cmake/cmake-3.31.4-windows-x86_64/share/cmake-3.31

.github/workflows/build_cpp.yml caches CMake under $env:TEMP on the self-hosted runner and gates re-download on Test-Path "$cmakeCached\cmake.exe" — it validates that bin/cmake.exe exists but never that share/cmake-3.31/Modules/ does, which is what CMAKE_ROOT resolves to. Temp cleanup removed share/ and left bin/, so the guard sees a healthy cache, skips the re-download, and prepends a broken CMake to PATH.

Tracked as #2817, fix in flight. Nothing to do on this PR for it.