feat(stdlib): Sqlite.affine codegen foundation — db-theory #1a (6 externs wired Deno-ESM end-to-end) (#522)

## Summary

First step of the **db-theory programme**. SQLite's surface looked
partial in the roadmap but was actually vapourware: 6 externs declared
in `stdlib/Sqlite.affine`, **zero codegen / zero adapter / zero tests /
zero consumers**. This PR lands the foundation so the extension PR (#1b
— prepared statements, schema introspection, bulk I/O) has a real
pathway.

## Changes

- **`lib/codegen_deno.ml` `deno_builtins`** — 6 new entries lowering
each extern to its `__as_db*` JS helper.
- **`lib/codegen_deno.ml` prelude** — `// ---- Sqlite ----` block with 6
`const __as_db*` helpers delegating to `globalThis.__as_sqlite`. Same
shape as Motion / Pixi / PixiSound (only Tier-2 binding without it).
Inline comment gives the Deno (`jsr:@db/sqlite`) and Node
(`better-sqlite3`) adapter recipes.
- **`tests/codegen-deno/sqlite_smoke.{affine,harness.mjs}`** — 3 smoke
functions exercising full lifecycle, `WHERE id = ?` param-bound
projection, and ordered multi-row retrieval. Harness installs an
in-memory SQL mock (CREATE / INSERT / SELECT / WHERE / ORDER BY /
COUNT(*) subset) explicitly marked as smoke-only.

## Verification

- `dune build bin/main.exe`: clean
- `dune runtest`: **357 / 357** green
- `tools/run_codegen_deno_tests.sh`: **all 31** harnesses pass (was 30)

## Next (db-theory #1b — separate PR)

- `Stmt` opaque type + `db_prepare` / `db_bind_*` / `db_step` /
`db_column_*` / `db_finalize`
- `db_schema_tables()` + `db_schema_columns(table)` introspection
- `db_import_csv` / `db_export_csv` bulk I/O
- Typed `DbError` + `Result<T, DbError>` returns

## Test plan

- [x] `dune build` clean
- [x] `dune runtest` 357 / 357 green (codegen ⊆ stdlib consistency picks
up the 6 new builtins)
- [x] `tools/run_codegen_deno_tests.sh` 31 / 31 harnesses pass
- [x] `sqlite_smoke` mock validates all three smoke functions

🤖 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

@@ -476,6 +476,46 @@ const __as_hpmJsonEscapeString = (s) => {
   }
   return out;
 };
+// ---- Sqlite (db-theory #1a / stdlib/Sqlite.affine): SQL via host adapter ----
+// Host JS environment must expose globalThis.__as_sqlite, a namespace
+// implementing the small adapter contract below. Consumers init once
+// (Deno):
+//   import * as s from "jsr:@db/sqlite";
+//   globalThis.__as_sqlite = {
+//     open: (p) => new s.Database(p),
+//     close: (db) => db.close(),
+//     execute: (db, sql) => db.exec(sql),
+//     query: (db, sql, params) => db.prepare(sql).all(...params),
+//     queryOne: (db, sql, params) => db.prepare(sql).get(...params),
+//     queryInt: (db, sql, params) => db.prepare(sql).value(...params),
+//   };
+// or (Node + better-sqlite3): adapt the same shape. The smoke harness
+// installs an in-memory mock that implements the same contract.
+//
+// Parameter marshalling is intentionally simple: the AffineScript side
+// hands the adapter a JSON-encoded `params` string (`"[]"` for none);
+// rows + single-row results come back as JSON strings for caller-side
+// decoding via `json::parse`. This matches the existing 6-extern
+// stdlib/Sqlite.affine surface; richer typed bindings (prepared
+// statements, schema introspection, bulk I/O) land in db-theory #1b.
+const __as_dbOpen = (path) => globalThis.__as_sqlite.open(path);
+const __as_dbClose = (h) => { globalThis.__as_sqlite.close(h); return 0; };
+const __as_dbExecute = (h, sql) => { globalThis.__as_sqlite.execute(h, sql); return 0; };
+const __as_dbQuery = (h, sql, paramsJson) => {
+  const params = paramsJson === "" || paramsJson === "[]" ? [] : JSON.parse(paramsJson);
+  const rows = globalThis.__as_sqlite.query(h, sql, params);
+  return JSON.stringify(rows);
+};
+const __as_dbQueryOne = (h, sql, paramsJson) => {
+  const params = paramsJson === "" || paramsJson === "[]" ? [] : JSON.parse(paramsJson);
+  const row = globalThis.__as_sqlite.queryOne(h, sql, params);
+  return JSON.stringify(row);
+};
+const __as_dbQueryInt = (h, sql, paramsJson) => {
+  const params = paramsJson === "" || paramsJson === "[]" ? [] : JSON.parse(paramsJson);
+  const v = globalThis.__as_sqlite.queryInt(h, sql, params);
+  return Number(v) | 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;
@@ -757,7 +797,14 @@ let () =
   b "hpm_json_object_get"    (fun a -> Printf.sprintf "__as_hpmJsonObjectGet(%s, %s)" (arg 0 a) (arg 1 a));
   b "hpm_json_array_len"     (fun a -> Printf.sprintf "__as_hpmJsonArrayLen(%s)" (arg 0 a));
   b "hpm_json_array_get"     (fun a -> Printf.sprintf "__as_hpmJsonArrayGet(%s, %s)" (arg 0 a) (arg 1 a));
-  b "hpm_json_escape_string" (fun a -> Printf.sprintf "__as_hpmJsonEscapeString(%s)" (arg 0 a))
+  b "hpm_json_escape_string" (fun a -> Printf.sprintf "__as_hpmJsonEscapeString(%s)" (arg 0 a));
+  (* ---- Sqlite (db-theory #1a / stdlib/Sqlite.affine): SQL via host adapter ---- *)
+  b "db_open"      (fun a -> Printf.sprintf "__as_dbOpen(%s)" (arg 0 a));
+  b "db_close"     (fun a -> Printf.sprintf "__as_dbClose(%s)" (arg 0 a));
+  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))
 
 (* ============================================================================
    Identifier sanitisation (JS reserved words -> trailing underscore)

tests/codegen-deno/sqlite_smoke.affine

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MPL-2.0
+// db-theory #1a — Sqlite codegen smoke
+//
+// Exercises the 6 stdlib/Sqlite.affine externs through the Deno-ESM
+// codegen path. The .harness.mjs installs an in-memory `globalThis
+// .__as_sqlite` mock implementing the adapter contract documented in
+// `lib/codegen_deno.ml :: __as_dbOpen` so this runs under plain Node
+// without requiring a real sqlite library.
+//
+// db-theory #1b (prepared statements, schema introspection, bulk I/O,
+// typed `DbError`) layers on top of this foundation; landing the
+// foundation first keeps each PR independently reviewable.
+
+use Sqlite::{ db_open, db_close, db_execute, db_query, db_query_one, db_query_int };
+
+pub fn smoke_full_lifecycle(path: String) -> Int {
+  let d = db_open(path);
+  let _id1 = db_execute(d, "CREATE TABLE t(id INTEGER, name TEXT)");
+  let _id2 = db_execute(d, "INSERT INTO t VALUES (1, 'a'), (2, 'b'), (3, 'c')");
+  let count = db_query_int(d, "SELECT COUNT(*) FROM t", "[]");
+  let _id3 = db_close(d);
+  count
+}
+
+pub fn smoke_query_one(path: String) -> String {
+  let d = db_open(path);
+  let _id1 = db_execute(d, "CREATE TABLE t(id INTEGER, name TEXT)");
+  let _id2 = db_execute(d, "INSERT INTO t VALUES (1, 'first')");
+  let row = db_query_one(d, "SELECT * FROM t WHERE id = ?", "[1]");
+  let _id3 = db_close(d);
+  row
+}
+
+pub fn smoke_query_all(path: String) -> String {
+  let d = db_open(path);
+  let _id1 = db_execute(d, "CREATE TABLE t(id INTEGER)");
+  let _id2 = db_execute(d, "INSERT INTO t VALUES (1), (2), (3)");
+  let rows = db_query(d, "SELECT id FROM t ORDER BY id", "[]");
+  let _id3 = db_close(d);
+  rows
+}

tests/codegen-deno/sqlite_smoke.harness.mjs

@@ -0,0 +1,147 @@
+// SPDX-License-Identifier: MPL-2.0
+// db-theory #1a — Node ESM harness for the Sqlite codegen smoke.
+//
+// Installs a minimal in-memory mock at `globalThis.__as_sqlite` BEFORE
+// importing the compiled module, then asserts the three smoke
+// functions return what the SQL-subset semantics dictate.
+//
+// The mock is intentionally narrow — just enough SQL parsing to drive
+// the 6-extern codegen path. Production deployments swap it for a
+// real adapter (Deno: `jsr:@db/sqlite`; Node: `better-sqlite3`)
+// satisfying the same `__as_sqlite` contract documented in
+// `lib/codegen_deno.ml :: __as_dbOpen`.
+
+import assert from "node:assert/strict";
+
+let nextHandle = 1;
+const dbs = new Map();
+
+const parseRowLiteral = (s) => {
+  // Split on commas at top-level (no nested parens, no embedded commas
+  // inside quoted strings beyond a single value).  Sufficient for the
+  // smoke's CREATE / INSERT / SELECT subset.
+  const out = [];
+  let buf = "";
+  let inStr = false;
+  for (const ch of s) {
+    if (ch === "'") { inStr = !inStr; buf += ch; }
+    else if (ch === "," && !inStr) { out.push(buf.trim()); buf = ""; }
+    else buf += ch;
+  }
+  if (buf.trim()) out.push(buf.trim());
+  return out.map((t) => (
+    t.startsWith("'") && t.endsWith("'") ? t.slice(1, -1) :
+    /^-?\d+$/.test(t) ? Number(t) :
+    /^-?\d*\.\d+$/.test(t) ? Number(t) :
+    t
+  ));
+};
+
+globalThis.__as_sqlite = {
+  open(path) {
+    const h = nextHandle++;
+    dbs.set(h, { path, tables: new Map(), schema: new Map() });
+    return h;
+  },
+  close(h) { dbs.delete(h); },
+  execute(h, sql) {
+    const db = dbs.get(h);
+    if (!db) throw new Error("invalid handle " + h);
+
+    const create = sql.match(/CREATE TABLE (\w+)\s*\(([^)]+)\)/i);
+    if (create) {
+      const cols = create[2].split(",").map((c) => c.trim().split(/\s+/)[0]);
+      db.tables.set(create[1], []);
+      db.schema.set(create[1], cols);
+      return;
+    }
+
+    const insert = sql.match(/INSERT INTO (\w+)\s+VALUES\s+(.+)/i);
+    if (insert) {
+      const tableName = insert[1];
+      const valuesPart = insert[2].replace(/;$/, "").trim();
+      const tupleRe = /\(([^)]+)\)/g;
+      let m;
+      while ((m = tupleRe.exec(valuesPart))) {
+        const cols = parseRowLiteral(m[1]);
+        const tbl = db.tables.get(tableName);
+        if (!tbl) throw new Error("no such table " + tableName);
+        tbl.push(cols);
+      }
+      return;
+    }
+
+    // Unknown DDL — accept silently for smoke purposes.
+  },
+
+  // Project a row (array) into a row object keyed by column name.
+  _project(db, tableName, row) {
+    const cols = db.schema.get(tableName) || [];
+    const obj = {};
+    for (let i = 0; i < cols.length; i++) obj[cols[i]] = row[i];
+    return obj;
+  },
+
+  query(h, sql, params) {
+    const db = dbs.get(h);
+    const tbl = sql.match(/FROM\s+(\w+)/i);
+    if (!tbl) return [];
+    const rows = db.tables.get(tbl[1]) || [];
+
+    // WHERE id = ? — single-column equality filter on a positional bind.
+    const where = sql.match(/WHERE\s+(\w+)\s*=\s*\?/i);
+    let filtered = rows;
+    if (where) {
+      const col = where[1];
+      const cols = db.schema.get(tbl[1]) || [];
+      const idx = cols.indexOf(col);
+      const v = params[0];
+      filtered = rows.filter((r) => r[idx] === v);
+    }
+
+    const ordered = /ORDER\s+BY/i.test(sql)
+      ? [...filtered].sort((a, b) => (a[0] > b[0] ? 1 : a[0] < b[0] ? -1 : 0))
+      : filtered;
+
+    return ordered.map((r) => this._project(db, tbl[1], r));
+  },
+
+  queryOne(h, sql, params) {
+    const all = this.query(h, sql, params);
+    return all.length > 0 ? all[0] : null;
+  },
+
+  queryInt(h, sql, params) {
+    if (/COUNT\(\*\)/i.test(sql)) {
+      const tbl = sql.match(/FROM\s+(\w+)/i);
+      const db = dbs.get(h);
+      return (db.tables.get(tbl[1]) || []).length;
+    }
+    const all = this.query(h, sql, params);
+    if (all.length === 0) return 0;
+    const first = all[0];
+    const k = Object.keys(first)[0];
+    return Number(first[k]);
+  },
+};
+
+const mod = await import("./sqlite_smoke.deno.js");
+
+assert.equal(
+  mod.smoke_full_lifecycle(":memory:"),
+  3,
+  "smoke_full_lifecycle: CREATE + 3-row INSERT + COUNT(*) returns 3",
+);
+
+const oneStr = mod.smoke_query_one(":memory:");
+const one = JSON.parse(oneStr);
+assert.equal(one.id, 1, "smoke_query_one: param-bound WHERE id=1 returns row with id=1");
+assert.equal(one.name, "first", "smoke_query_one: row['name'] field round-trips");
+
+const allStr = mod.smoke_query_all(":memory:");
+const all = JSON.parse(allStr);
+assert.equal(all.length, 3, "smoke_query_all: ORDER BY id returns 3 rows");
+assert.equal(all[0].id, 1, "smoke_query_all: row[0].id = 1");
+assert.equal(all[2].id, 3, "smoke_query_all: row[2].id = 3");
+
+console.log("sqlite_smoke OK");