Skip to content

AGENTS.md: sqlite Architectural Context & Engagement Rules

1. System Context & Paradigm

You are operating within the sqlite repository, the definitive, self-contained, high-reliability SQL database engine. The codebase is heavily dominated by C (63.8%) and relies extensively on TCL (35.6%) for its massive testing infrastructure. * Architectural Paradigm: This repository functions as a "Cluster 3" macro-species and exhibits a high Architectural Drift Z-Score of 4.795. The network topology demonstrates a completely flat Modularity (0.0) and Assortativity (0.0). This indicates an aggressively monolithic, "hub-and-spoke" architecture. The entire system is engineered to be coalesced into a single amalgamation file (sqlite3.c), with all internal components highly centralized around core internal headers. * Core Rule: Maintain strict adherence to SQLite's zero-dependency, highly deterministic C programming paradigms. Do NOT attempt to decouple foundational orchestrators, modernize the C idioms into C++ paradigms, or circumvent the rigid memory allocation (sqlite3_malloc) and VFS (Virtual File System) layers.

2. Architectural Guardrails (Do's and Don'ts)

  • Algorithmic Complexity Limit: Core query parsing (sqlite3RunParser, sqlite3ParseURI), expression evaluation (sqlite3ExprCodeTarget), and Virtual Database Engine (VDBE) execution paths operate at extreme recursive time complexities (O(2^N) in static analysis) due to deep AST traversal and bytecode interpretation. You MUST NOT introduce unbounded recursive loops, heavy synchronous allocations, or complex evaluation traps inside the hot paths of src/vdbe.c, src/expr.c, or src/btree.c.
  • Orchestrator Fragility: Central orchestrators and internal headers such as src/sqliteInt.h (47 outbound dependencies) and src/vdbeInt.h (38 outbound dependencies) are incredibly fragile. Modifying these headers forces a complete recompilation of the database and carries an immense risk of breaking ABI/API compatibility or internal bytecode semantics.
  • Avoid Dead Code Pruning: The repository contains TCL test files (test/tester.tcl with 41 orphaned functions) and auxiliary C tools containing logic flagged as "dead code." DO NOT autonomously attempt to prune, format, or clean up these files. SQLite utilizes dynamic test case generation and macro-heavy C code that bypasses static dependency resolution.

3. Restricted Zones (The God Nodes)

The following files are load-bearing "God Nodes." They possess extreme cumulative risk, massive structural mass, volatile churn, or represent critical execution bottlenecks.

MANDATORY RULE: You require explicit human permission, exhaustive fuzzing, and downstream amalgamation compilation testing (make sqlite3.c) before modifying the structural signatures, bytecode generation, or public APIs of these files: * src/sqliteInt.h (Massive Structural Mass & Highest Cumulative Risk: 624.81. The absolute core internal header connecting all database subsystems). * src/vdbe.c & src/vdbeInt.h (The Virtual Database Engine. This is the heart of SQLite's execution model; modifications here risk catastrophic query execution failures). * src/expr.c (Highest Volatility Hotspot: 96.5% Churn. Core expression parsing and AST manipulation). * src/btree.c & src/pager.c (Core storage and transaction isolation layers. High risk of data corruption if locking or journaling logic is altered). * src/parse.c (Autogenerated or macro-heavy parser logic with extreme Data Gravity).

4. Threat & Security Boundaries

Status: SECURE PERIMETER (WITH CRITICAL RAW MEMORY CAVEATS). Structural XGBoost Threat Intelligence audits have flagged 0 malicious artifacts.

CRITICAL WARNINGS: 1. Raw Memory & VFS Manipulation: Operations within the pager (src/pager.c), memory allocators (src/mem1.c, src/mem2.c), and OS interfaces (src/os_unix.c, src/os_win.c) natively rely on raw pointer arithmetic, page cache manipulation, and direct system calls. Any modifications to memory bounds, B-Tree cell parsing, or VFS locks must be mathematically proven to prevent Out-Of-Bounds (OOB) reads/writes, Use-After-Free (UAF), or database corruption. 2. Exploit Generation Surface: The TCL testing infrastructure (test/tester.tcl, test/threadtest3.c) possesses exposure for Exploit Generation. Ensure any modifications to test harnesses do not inadvertently introduce arbitrary command execution vulnerabilities if interacting with the host shell during test runs. 3. Weaponizable Injection Vectors: By definition, SQLite parses SQL. Changes to src/tokenize.c or src/parse.y must rigorously validate syntax boundaries to ensure the parser itself cannot be exploited via malformed SQL strings.

5. Environmental Tooling (The Oracle)

Do not guess VDBE opcode behaviors, hallucinate B-Tree balancing mechanics, or rely on generalized C knowledge to determine blast radius within this 218K+ LOC database engine.

Leverage the deterministic GitGalaxy SQLite database to map the absolute syntactic physics of this repository. Before modifying any file listed in the Restricted Zones, you MUST query the database for dependency mapping. * To map inbound dependencies (Blast Radius), query the function_edges or file_edges tables for all callers targeting your target file. * Do not proceed with structural modifications until the specific blast radius has been statically confirmed via the database.