feat(stdlib): Sqlite prepared statements — db-theory #1b (Stmt + 10 typed externs) (#524)

## Summary

Layers the prepared-statement surface on top of the #522 convenience
surface. Use this for anything carrying **user input**, anything
iterating over **more than a handful of rows**, and anything where
**typed value marshalling** matters (Int / Text / NULL).

## New stdlib surface (`stdlib/Sqlite.affine`)

| extern | purpose |
|---|---|
| `extern type Stmt` | opaque statement handle |
| `db_prepare(d, sql) -> Stmt` | compile SQL with `?` placeholders |
| `db_bind_int(s, idx, v) -> Int` | bind 1-indexed param (sqlite3
convention) |
| `db_bind_text(s, idx, v) -> Int` | bind text |
| `db_bind_null(s, idx) -> Int` | bind NULL |
| `db_step(s) -> Int` | `1` = `SQLITE_ROW`, `0` = `SQLITE_DONE` |
| `db_column_count(s) -> Int` | current-row width |
| `db_column_int(s, idx) -> Int` | 0-indexed read; NULL → 0 |
| `db_column_text(s, idx) -> String` | 0-indexed read; NULL → "" |
| `db_reset(s) -> Int` | re-step from row 0 without recompiling |
| `db_finalize(s) -> Int` | release |

Bind-index is 1-based, column-index is 0-based — matches both
`jsr:@db/sqlite` and `better-sqlite3` (the two reference `__as_sqlite`
adapters). NULL coercion happens at the JS-helper layer; callers needing
NULL/value-zero discrimination use the convenience `db_query_one` path.

## Smoke harness
(`tests/codegen-deno/sqlite_prepared.{affine,harness.mjs}`)

| smoke fn | exercises |
|---|---|
| `smoke_prepare_bind_int_step_finalize` | `INSERT(?, ?)` with two int
binds + finalize + query-back |
| `smoke_step_iteration` | `SELECT` N rows, loop `db_step` until 0,
accumulate via `db_column_int` |
| `smoke_text_bind_and_column` | bind_text → step → column_text
round-trip |
| `smoke_null_bind` | bind_null → column_int coerces to 0 |
| `smoke_reset_and_reuse` | prepare once + bind/step + reset +
re-bind/step → 2 rows |
| `smoke_column_count_basic` | `SELECT a, b, c FROM t` → column_count =
3 |

Mock extends #522's in-memory adapter with 10 statement-side methods;
production adapters (`jsr:@db/sqlite` / `better-sqlite3`) provide
near-1:1 wrappers.

## Verification

- `dune build bin/main.exe`: clean
- `dune runtest`: **363 / 363** green (codegen ⊆ stdlib consistency
picks up the 10 new builtins; all match `stdlib/Sqlite.affine`)
- `tools/run_codegen_deno_tests.sh`: **32 / 32** harnesses pass (was 31)

## Stacked on #522

#522 merged 12:43Z; this branch forks from the resulting main HEAD.
Clean diff.

## db-theory #1c (next PR, separate)

- Schema introspection (`db_schema_tables`, `db_schema_columns`)
- Bulk I/O (`db_import_csv`, `db_export_csv`)
- Typed `DbError` + `Result<T, DbError>` variants

## Test plan

- [x] dune build clean
- [x] dune runtest 363/363 green
- [x] tools/run_codegen_deno_tests.sh 32/32 pass
- [x] 6 prepared-statement smoke assertions pass

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

lib/codegen_deno.ml

@@ -516,6 +516,31 @@ const __as_dbQueryInt = (h, sql, paramsJson) => {
   const v = globalThis.__as_sqlite.queryInt(h, sql, params);
   return Number(v) | 0;
 };
+// ---- Sqlite prepared statements (db-theory #1b) ----
+// Layered on top of the convenience surface above. The host adapter
+// gains nine extra methods (`prepare`, `bindInt`, `bindText`, `bindNull`,
+// `step`, `columnCount`, `columnInt`, `columnText`, `reset`, `finalize`);
+// the smoke harness's mock implements them, and both `jsr:@db/sqlite`
+// and `better-sqlite3` provide direct one-line wrappers (each library
+// already exposes a `prepare()` + iterator-style step + typed column
+// accessors). Bind-index convention is sqlite3's 1-indexed; column-index
+// convention is 0-indexed (matches both adapter libraries).
+const __as_dbPrepare      = (h, sql) => globalThis.__as_sqlite.prepare(h, sql);
+const __as_dbBindInt      = (s, idx, v) => { globalThis.__as_sqlite.bindInt(s, idx, v); return 0; };
+const __as_dbBindText     = (s, idx, v) => { globalThis.__as_sqlite.bindText(s, idx, v); return 0; };
+const __as_dbBindNull     = (s, idx) => { globalThis.__as_sqlite.bindNull(s, idx); return 0; };
+const __as_dbStep         = (s) => (globalThis.__as_sqlite.step(s) ? 1 : 0);
+const __as_dbColumnCount  = (s) => Number(globalThis.__as_sqlite.columnCount(s)) | 0;
+const __as_dbColumnInt    = (s, idx) => {
+  const v = globalThis.__as_sqlite.columnInt(s, idx);
+  return v == null ? 0 : (Number(v) | 0);
+};
+const __as_dbColumnText   = (s, idx) => {
+  const v = globalThis.__as_sqlite.columnText(s, idx);
+  return v == null ? "" : String(v);
+};
+const __as_dbReset        = (s) => { globalThis.__as_sqlite.reset(s); return 0; };
+const __as_dbFinalize     = (s) => { globalThis.__as_sqlite.finalize(s); return 0; };
 const __as_httpFetch = async (url, method, headers, bodyOpt) => {
   const init = { method, headers: __as_httpHeadersToObject(headers) };
   if (bodyOpt && bodyOpt.tag === "Some") init.body = bodyOpt.value;
@@ -804,7 +829,18 @@ let () =
   b "db_execute"   (fun a -> Printf.sprintf "__as_dbExecute(%s, %s)" (arg 0 a) (arg 1 a));
   b "db_query"     (fun a -> Printf.sprintf "__as_dbQuery(%s, %s, %s)" (arg 0 a) (arg 1 a) (arg 2 a));
   b "db_query_one" (fun a -> Printf.sprintf "__as_dbQueryOne(%s, %s, %s)" (arg 0 a) (arg 1 a) (arg 2 a));
-  b "db_query_int" (fun a -> Printf.sprintf "__as_dbQueryInt(%s, %s, %s)" (arg 0 a) (arg 1 a) (arg 2 a))
+  b "db_query_int" (fun a -> Printf.sprintf "__as_dbQueryInt(%s, %s, %s)" (arg 0 a) (arg 1 a) (arg 2 a));
+  (* ---- Sqlite prepared statements (db-theory #1b) ---- *)
+  b "db_prepare"     (fun a -> Printf.sprintf "__as_dbPrepare(%s, %s)" (arg 0 a) (arg 1 a));
+  b "db_bind_int"    (fun a -> Printf.sprintf "__as_dbBindInt(%s, %s, %s)" (arg 0 a) (arg 1 a) (arg 2 a));
+  b "db_bind_text"   (fun a -> Printf.sprintf "__as_dbBindText(%s, %s, %s)" (arg 0 a) (arg 1 a) (arg 2 a));
+  b "db_bind_null"   (fun a -> Printf.sprintf "__as_dbBindNull(%s, %s)" (arg 0 a) (arg 1 a));
+  b "db_step"        (fun a -> Printf.sprintf "__as_dbStep(%s)" (arg 0 a));
+  b "db_column_count" (fun a -> Printf.sprintf "__as_dbColumnCount(%s)" (arg 0 a));
+  b "db_column_int"  (fun a -> Printf.sprintf "__as_dbColumnInt(%s, %s)" (arg 0 a) (arg 1 a));
+  b "db_column_text" (fun a -> Printf.sprintf "__as_dbColumnText(%s, %s)" (arg 0 a) (arg 1 a));
+  b "db_reset"       (fun a -> Printf.sprintf "__as_dbReset(%s)" (arg 0 a));
+  b "db_finalize"    (fun a -> Printf.sprintf "__as_dbFinalize(%s)" (arg 0 a))
 
 (* ============================================================================
    Identifier sanitisation (JS reserved words -> trailing underscore)

stdlib/Sqlite.affine

@@ -3,17 +3,68 @@
 //
 // Sqlite.affine — extern bindings for an SQLite backend.
 //
-// All database handles are opaque Int. Query parameters are JSON-encoded
-// strings; each result row is returned as a JSON-encoded string for
-// caller-side decoding. The Node-CJS shim wraps Deno sqlite or node:sqlite.
+// Two layers:
+//   1. **Convenience surface** (`db_open`, `db_execute`, `db_query*`):
+//      JSON-encoded parameters in, JSON-encoded rows out. Sufficient
+//      for one-shot queries and prototyping; *not* sufficient for
+//      injection-safe parametrised queries or cursor-style iteration
+//      over large result sets.
+//   2. **Prepared-statement surface** (`Stmt` type + `db_prepare` +
+//      `db_bind_*` + `db_step` + `db_column_*` + `db_finalize`):
+//      sqlite3-style bind-step-column-finalize loop. Use this for
+//      anything carrying user input, anything iterating over more
+//      than a handful of rows, and anything where typed value
+//      marshalling matters (Int / Text / null).
+//
+// All database + statement handles are opaque from the AffineScript
+// side. The Deno-ESM backend's `__as_sqlite` adapter contract
+// (documented in `lib/codegen_deno.ml`) maps each extern to a host
+// SQL library (`jsr:@db/sqlite` for Deno; `better-sqlite3` for Node).
 
 module Sqlite;
 
 pub extern type Db;
+pub extern type Stmt;
+
+// ── Convenience surface (db-theory #1a) ────────────────────────────
 
 pub extern fn db_open(path: String) -> Db;
 pub extern fn db_close(d: Db) -> Int;
 pub extern fn db_execute(d: Db, sql: String) -> Int;
 pub extern fn db_query(d: Db, sql: String, params_json: String) -> String;
 pub extern fn db_query_one(d: Db, sql: String, params_json: String) -> String;
 pub extern fn db_query_int(d: Db, sql: String, params_json: String) -> Int;
+
+// ── Prepared statements (db-theory #1b) ────────────────────────────
+//
+// Lifecycle: `db_prepare` returns a `Stmt`; bind each `?` placeholder
+// (1-indexed, sqlite3 convention) via the typed `db_bind_*` calls;
+// iterate rows by calling `db_step` until it returns 0 (`SQLITE_DONE`);
+// read column values from the current row via `db_column_*`; release
+// the statement with `db_finalize`. A statement may be reset via
+// `db_reset` and re-stepped if reused.
+//
+// Return value conventions:
+//   - `db_step(s) -> Int`: 1 if a row is available (`SQLITE_ROW`),
+//     0 if iteration is complete (`SQLITE_DONE`). Adapter raises on
+//     other sqlite3 codes (error / busy / misuse).
+//   - `db_bind_*(s, idx, v) -> Int`: returns 0 on success.
+//   - `db_column_count(s) -> Int`: number of columns in the current row.
+//   - `db_column_int(s, idx) -> Int`: column value as integer
+//     (0-indexed). NULL columns coerce to 0; use `db_query_one` + JSON
+//     null-check if NULL must be distinguished.
+//   - `db_column_text(s, idx) -> String`: column value as text.
+//     NULL columns coerce to "".
+//   - `db_finalize(s) -> Int`: returns 0; the `Stmt` handle is invalid
+//     after this call.
+
+pub extern fn db_prepare(d: Db, sql: String) -> Stmt;
+pub extern fn db_bind_int(s: Stmt, idx: Int, v: Int) -> Int;
+pub extern fn db_bind_text(s: Stmt, idx: Int, v: String) -> Int;
+pub extern fn db_bind_null(s: Stmt, idx: Int) -> Int;
+pub extern fn db_step(s: Stmt) -> Int;
+pub extern fn db_column_count(s: Stmt) -> Int;
+pub extern fn db_column_int(s: Stmt, idx: Int) -> Int;
+pub extern fn db_column_text(s: Stmt, idx: Int) -> String;
+pub extern fn db_reset(s: Stmt) -> Int;
+pub extern fn db_finalize(s: Stmt) -> Int;

tests/codegen-deno/sqlite_prepared.affine

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: MPL-2.0
+// db-theory #1b — Sqlite prepared-statement codegen smoke
+//
+// Exercises the 10 prepared-statement externs added in #1b. The
+// `.harness.mjs` extends the #1a in-memory mock with prepare / bind* /
+// step / column* / reset / finalize methods on `globalThis.__as_sqlite`.
+//
+// Each smoke function exercises one shape of the lifecycle:
+//   - smoke_prepare_bind_int_step_finalize: classic `INSERT (?, ?)`
+//     with two int binds, then re-query via the convenience surface to
+//     prove the row landed.
+//   - smoke_step_iteration: SELECT returning N rows; loop `db_step`
+//     until it returns 0, accumulating an int sum from column 0.
+//   - smoke_text_bind_and_column: round-trip a string through bind_text
+//     and column_text.
+//   - smoke_null_bind: bind NULL; verify column_int coerces to 0.
+//   - smoke_reset_and_reuse: prepare once, bind+step, reset, re-bind
+//     with different params, step again.
+
+use Sqlite::{db_open, db_close, db_execute, db_prepare, db_bind_int, db_bind_text, db_bind_null, db_step, db_column_count, db_column_int, db_column_text, db_reset, db_finalize, db_query_int, db_query_one};
+
+pub fn smoke_prepare_bind_int_step_finalize(path: String) -> Int {
+  let d = db_open(path);
+  let _id1 = db_execute(d, "CREATE TABLE t(a INTEGER, b INTEGER)");
+  let s = db_prepare(d, "INSERT INTO t(a, b) VALUES (?, ?)");
+  let _id2 = db_bind_int(s, 1, 7);
+  let _id3 = db_bind_int(s, 2, 35);
+  let _step1 = db_step(s);
+  let _id4 = db_finalize(s);
+  let v = db_query_int(d, "SELECT a + b FROM t LIMIT 1", "[]");
+  let _id5 = db_close(d);
+  v
+}
+
+pub fn smoke_step_iteration(path: String) -> Int {
+  let d = db_open(path);
+  let _id1 = db_execute(d, "CREATE TABLE t(n INTEGER)");
+  let _id2 = db_execute(d, "INSERT INTO t VALUES (1), (2), (3), (4), (5)");
+  let s = db_prepare(d, "SELECT n FROM t ORDER BY n");
+  let mut sum = 0;
+  let mut row = db_step(s);
+  while row == 1 {
+    sum = sum + db_column_int(s, 0);
+    row = db_step(s);
+  }
+  let _id3 = db_finalize(s);
+  let _id4 = db_close(d);
+  sum
+}
+
+pub fn smoke_text_bind_and_column(path: String) -> String {
+  let d = db_open(path);
+  let _id1 = db_execute(d, "CREATE TABLE t(name TEXT)");
+  let s_ins = db_prepare(d, "INSERT INTO t VALUES (?)");
+  let _id2 = db_bind_text(s_ins, 1, "affinescript");
+  let _step1 = db_step(s_ins);
+  let _id3 = db_finalize(s_ins);
+  let s_sel = db_prepare(d, "SELECT name FROM t LIMIT 1");
+  let _step2 = db_step(s_sel);
+  let out = db_column_text(s_sel, 0);
+  let _id4 = db_finalize(s_sel);
+  let _id5 = db_close(d);
+  out
+}
+
+pub fn smoke_null_bind(path: String) -> Int {
+  let d = db_open(path);
+  let _id1 = db_execute(d, "CREATE TABLE t(v INTEGER)");
+  let s_ins = db_prepare(d, "INSERT INTO t VALUES (?)");
+  let _id2 = db_bind_null(s_ins, 1);
+  let _step1 = db_step(s_ins);
+  let _id3 = db_finalize(s_ins);
+  let s_sel = db_prepare(d, "SELECT v FROM t LIMIT 1");
+  let _step2 = db_step(s_sel);
+  let v = db_column_int(s_sel, 0);
+  let _id4 = db_finalize(s_sel);
+  let _id5 = db_close(d);
+  v
+}
+
+pub fn smoke_reset_and_reuse(path: String) -> Int {
+  let d = db_open(path);
+  let _id1 = db_execute(d, "CREATE TABLE t(n INTEGER)");
+  let s = db_prepare(d, "INSERT INTO t VALUES (?)");
+  let _id2 = db_bind_int(s, 1, 10);
+  let _step1 = db_step(s);
+  let _id3 = db_reset(s);
+  let _id4 = db_bind_int(s, 1, 32);
+  let _step2 = db_step(s);
+  let _id5 = db_finalize(s);
+  let count = db_query_int(d, "SELECT COUNT(*) FROM t", "[]");
+  let _id6 = db_close(d);
+  count
+}
+
+pub fn smoke_column_count_basic(path: String) -> Int {
+  let d = db_open(path);
+  let _id1 = db_execute(d, "CREATE TABLE t(a INTEGER, b INTEGER, c INTEGER)");
+  let _id2 = db_execute(d, "INSERT INTO t VALUES (1, 2, 3)");
+  let s = db_prepare(d, "SELECT a, b, c FROM t");
+  let _step1 = db_step(s);
+  let n = db_column_count(s);
+  let _id3 = db_finalize(s);
+  let _id4 = db_close(d);
+  n
+}