Add a prototype AGENTS.md file

FossilOrigin-Name: 3dd1181120b9910a96090b5b3cad5f0829fadeffeb6ffaad17031540a5749513

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644 (file)
index 0000000..2353027
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,125 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Project nature
+
+SQLite is a self-contained, serverless SQL database engine written in C. The
+source is **public domain** — no copyright or license header should ever be
+added to any file. The blessing comment that appears at the top of each source
+file is intentional and should be preserved unchanged.
+
+SQLite does not accept pull requests without prior agreement and/or
+accompanying legal paperwork that places the pull request in the public domain.
+However, the human SQLite developers will review a concise and well-written
+pull request as a proof-of-concept prior to reimplementing the changes
+themselves.
+
+SQLite does not (currently) accept agentic code.  However the project
+will accept agentic bug reports that include a reproducible test case.
+Patches or pull requests demonstrating a possible fix, for documentation
+purposes, are welcomed.
+
+SQLite uses the [Fossil](https://fossil-scm.org/) for version control,
+not Git.  The canonical repository is at <https://sqlite.org/src>.
+
+## Build
+
+The configure script uses [autosetup](https://msteveb.github.io/autosetup/),
+not GNU Autoconf.
+
+```bash
+apt install gcc make tcl-dev   # prerequisites (Debian/Ubuntu)
+
+./configure --dev              # debug build
+make sqlite3                   # CLI shell
+make sqlite3d                  # Debugging variant of the CLI shell
+make sqlite3.c                 # amalgamation (single-file distribution form)
+make testfixture               # test runner binary (requires tcl-dev)
+make tclextension-install      # install TCL extension before running tests
+```
+
+## Testing
+
+Tests are TCL scripts run through the `testfixture` enhanced interpreter.
+
+```bash
+# From the build directory:
+./testfixture test/main.test   # single test file
+test/testrunner.tcl            # quick suite
+test/testrunner.tcl full       # full suite
+test/testrunner.tcl fts5%      # pattern match
+
+# Check for failures:
+grep '!' testrunner.log
+```
+
+`make devtest` is the fastest way to run a representative subset. Always run
+at least `devtest` after any change to `src/`.
+
+## Architecture
+
+SQL text → **tokenizer** (`tokenize.c`) → **parser** (`parse.y` / Lemon) →
+**code generator** (`build.c`, `select.c`, `insert.c`, `update.c`, `delete.c`,
+`expr.c`) → **optimizer** (`where*.c`) → **VDBE** (`vdbe.c`) → **B-Tree**
+(`btree.c`) → **Pager** (`pager.c`) → **WAL** (`wal.c`) → **VFS**
+(`os_unix.c`, `os_win.c`).
+
+The master internal header is `src/sqliteInt.h`. Major subsystems have private
+headers: `vdbeInt.h`, `btreeInt.h`, `whereInt.h`. The public API is defined in
+`src/sqlite.h.in` (template) which generates `sqlite3.h`.
+
+## Do not edit generated files
+
+These files are produced by scripts and must not be edited by hand:
+
+| File | Regenerate with |
+|---|---|
+| `sqlite3.h` | `tool/mksqlite3h.tcl` |
+| `parse.c`, `parse.h` | build lemon (`tool/lemon.c`) then run on `src/parse.y` |
+| `opcodes.h` | `tool/mkopcodeh.tcl` (reads `src/vdbe.c`) |
+| `opcodes.c` | `tool/mkopcodec.tcl` (reads `opcodes.h`) |
+| `keywordhash.h` | `tool/mkkeywordhash.c` |
+| `pragma.h` | `tool/mkpragmatab.tcl` |
+| `sqlite3.c` | `tool/mksqlite3c.tcl` (the amalgamation) |
+
+Editing rules:
+- To add a PRAGMA: edit `tool/mkpragmatab.tcl`, then regenerate `pragma.h`.
+- To add a VDBE opcode: add the `case OP_Xxx:` handler in `src/vdbe.c`; the
+  opcode number and name are extracted automatically by `mkopcodeh.tcl`.
+- To change the SQL grammar: edit `src/parse.y`, not `parse.c`.
+
+## Coding conventions
+
+- C89/C99 compatible C only. No C++, no STL, no exceptions, no VLAs.
+- All memory allocation goes through `sqlite3Malloc` / `sqlite3_malloc64`
+  (never raw `malloc`). The `sqlite3MallocZero` variant zero-initializes.
+- Integer widths: use `i64` (`sqlite3_int64`) for 64-bit values, `u32`/`u64`
+  for unsigned. Avoid bare `long` or `int` for values that could exceed 2G.
+- Error propagation: functions return `SQLITE_OK` (0) on success and a
+  `SQLITE_*` error code on failure. Many routines also set `db->mallocFailed`
+  on OOM, allowing deferred error checking.
+- Assert liberally for invariants that must hold in correct code; use
+  `ALWAYS(x)` / `NEVER(x)` for conditions that are logically always
+  true/false but that the compiler cannot prove.
+
+## Extensions (`ext/`)
+
+Extensions are compiled separately from the core and are not part of the
+amalgamation by default (except where explicitly included). Major subsystems:
+
+- `ext/fts5/` — Full-Text Search 5 (current)
+- `ext/rtree/` — R-Tree spatial indexing
+- `ext/session/` — Changesets and sessions
+- `ext/recover/` — Database file recovery
+- `ext/misc/` — Single-file utility extensions (many included in the CLI)
+- `ext/qrf/` — Query Result Formatter utility library
+
+## Useful references
+
+- Architecture: <https://sqlite.org/arch.html>
+- File format: <https://sqlite.org/fileformat2.html>
+- VDBE opcodes: <https://sqlite.org/opcode.html>
+- Query planner: <https://sqlite.org/optoverview.html>
+- Lemon parser generator: <https://sqlite.org/doc/trunk/doc/lemon.html>
+- Compile-time options: <https://sqlite.org/compile.html>

diff --git a/manifest b/manifest
index ea05a71d533558f22177e34d3254c13359328a58..46e29a6f5738a00794163fe3b94256005bbca283 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,8 +1,9 @@
-C Fix\sthe\sVFSes\sso\sthat\sthere\sis\sno\s32-bit\sinteger\soverflow\sin\sthe\nxShmMap\smethod\sif\sthe\sWAL\sfile\ssize\sexceeds\sabout\s25\sterabytes,\sor\nif\sthe\sheader\sis\scorrupted\sto\smake\sSQLite\sthink\sthat\sthe\sWAL\sfile\ssize\nis\sthat\sbig.\n[bugs:/info/2026-05-21T03:53:03Z|Bug\s2026-05-21T03:53:03Z].
-D 2026-05-21T15:14:35.420
+C Add\sa\sprototype\sAGENTS.md\sfile
+D 2026-05-22T11:15:25.905
 F .fossil-settings/binary-glob 61195414528fb3ea9693577e1980230d78a1f8b0a54c78cf1b9b24d0a409ed6a x
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
+F AGENTS.md 911864e3bae0566aa318b4134ad3568fbbe7b250815f4a55fd3b6c6b0f9bcf47
 F LICENSE.md 6bc480fc673fb4acbc4094e77edb326267dd460162d7723c7f30bee2d3d9e97d
 F Makefile.in 5fda086f33b144da08119255da1d2557f983d0764a13707f05acf0159fd89ba5
 F Makefile.linux-generic bd3e3cacd369821a6241d4ea1967395c962dfe3057e38cb0a435cee0e8b789d0
@@ -2205,8 +2206,8 @@ F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee
 F tool/warnings.sh a554d13f6e5cf3760f041b87939e3d616ec6961859c3245e8ef701d1eafc2ca2
 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
 F tool/winmain.c 00c8fb88e365c9017db14c73d3c78af62194d9644feaf60e220ab0f411f3604c
-P 869a51ae84dfaaf824c872e4b3024f35eea7fa67bb584759a2d42ebf8404ef6e
-R 9253aad57f0e0c2cd700de54d1f4d82b
+P 9ac4a33a2932d353c4871fd8e09c10addf827f1fc3fc9380037d738cf2cd0353
+R 2bd6937d433d800bf75d925a3aef6528
 U drh
-Z 444f216a004346dc782c26e43224aa07
+Z 83c1080ffcb6a157fc9e6d16bda364e0
 # Remove this line to create a well-formed Fossil manifest.

diff --git a/manifest.uuid b/manifest.uuid
index 5970dfeaa7bb05ed0510e46e5200f5659f79a849..b7bfd73f0c98f2d4c1e732a249ea845d3c6f45f4 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-9ac4a33a2932d353c4871fd8e09c10addf827f1fc3fc9380037d738cf2cd0353
+3dd1181120b9910a96090b5b3cad5f0829fadeffeb6ffaad17031540a5749513