feat(sql): IS NULL / IS NOT NULL + typed Option<Value> INSERT pipeline (SQLR-7) (#95)

Two related fixes from SQLR-2 fallout:

1) `WHERE col IS NULL` / `IS NOT NULL` now work — two new arms in
   `eval_expr`. NULLs aren't stored in secondary / HNSW / FTS indexes,
   so these predicates correctly fall through to a full scan via the
   existing `select_rowids` logic.

2) INSERT no longer carries values as `Vec<Vec<String>>` with the
   string sentinel `"Null"` standing in for SQL NULL. `InsertQuery.rows`
   is now `Vec<Vec<Option<Value>>>`; the parser emits `None` for NULL
   and typed `Value::*` for everything else. `Table::insert_row` and
   `Table::validate_unique_constraint` dispatch on `Option<Value>`,
   leaving the per-column BTreeMap entry absent for NULL (reads come
   back as `Value::Null` via the existing missing-rowid path).

   Fixes:
   - `INSERT INTO t (n) VALUES (NULL)` for INTEGER / REAL / BOOLEAN /
     VECTOR columns no longer errors via `"Null".parse::<T>()`
   - `INSERT INTO t (s) VALUES (NULL)` for TEXT no longer stores the
     literal string `"Null"`
   - `Table::restore_row` accepts NULL for non-text column types so
     persisted NULLs reopen cleanly (without this, a saved DB
     containing any NULL outside TEXT failed to reload)
   - SQL UNIQUE allows multiple NULLs (standard SQL three-valued
     logic)
   - `DEFAULT NULL` collapses to "no default" — explicit NULL in
     INSERT is preserved over a column DEFAULT, matching SQLite

Tests: 8 new INSERT-NULL tests across all column types; 5 IS NULL /
IS NOT NULL executor tests (non-indexed, indexed, omitted-column,
combined-with-AND); restored the SQLR-2 `default_does_not_override_
explicit_null` test that had to be dropped because of this bug; new
file-backed `null_values_round_trip_through_disk`. The previous
`process_command_insert_missing_integer_returns_error_test` codified
the bug as a graceful error and is replaced with a positive
"omitted INTEGER stores NULL" assertion.

Docs: removed "not yet supported" notes for IS NULL / IS NOT NULL
from README, supported-sql.md, usage.md, roadmap.md.

Out of scope (deferred):
  - Removing the legacy `Row::Text "Null"` sentinel-strip on read
    (kept as back-compat for pre-fix saved DBs; revisit at next
    file-format bump)
  - Negative numeric literals in INSERT VALUES (pre-existing gap)
  - IS NULL index optimization (full scan is fine for now)

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

Author: joaoh82

README.md

@@ -165,12 +165,13 @@ sqlrite> DELETE FROM users WHERE age < 30;
 Expressions in `WHERE` and `UPDATE`'s `SET` RHS:
 
 - Comparisons — `=`, `<>`, `<`, `<=`, `>`, `>=`
+- Null tests — `IS NULL`, `IS NOT NULL`
 - Logical — `AND`, `OR`, `NOT` (SQL three-valued logic; NULL-as-false in `WHERE`)
 - Arithmetic — `+`, `-`, `*`, `/`, `%` (integer ops stay integer; any `REAL` promotes to `f64`; divide/modulo by zero is a clean error)
 - String concat — `||`
 - Literals — integer + real numbers, `'single-quoted strings'`, `TRUE` / `FALSE`, `NULL`; parentheses for grouping
 
-**Not yet supported** (common ones): joins, subqueries, CTEs, `GROUP BY` / aggregates, `DISTINCT`, `LIKE` / `IN` / `IS NULL`, expressions in the projection list, column aliases, `OFFSET`, multi-column `ORDER BY`, savepoints, `ALTER TABLE`, `DROP TABLE`, `DROP INDEX`. The [full list with context](docs/supported-sql.md#not-yet-supported) lives in the reference.
+**Not yet supported** (common ones): joins, subqueries, CTEs, `GROUP BY` / aggregates, `DISTINCT`, `LIKE` / `IN`, expressions in the projection list, column aliases, `OFFSET`, multi-column `ORDER BY`, savepoints, `ALTER TABLE`, `DROP TABLE`, `DROP INDEX`. The [full list with context](docs/supported-sql.md#not-yet-supported) lives in the reference.
 
 #### Meta commands
 
@@ -309,7 +310,7 @@ Lockstep versioning — one dispatch bumps every product to the same `vX.Y.Z`. T
 
 **Possible extras** *(no committed phase)*
 - Joins (`INNER`, `LEFT OUTER`, `CROSS` — SQLite does not support `RIGHT`/`FULL OUTER`)
-- `GROUP BY`, aggregates (`COUNT`, `SUM`, `AVG`, ...), `DISTINCT`, `LIKE`, `IN`, `IS NULL`
+- `GROUP BY`, aggregates (`COUNT`, `SUM`, `AVG`, ...), `DISTINCT`, `LIKE`, `IN`
 - Composite and expression indexes (with cost analysis)
 - Alternate storage engines — LSM/SSTable for write-heavy workloads alongside the B-Tree
 - Benchmarks against SQLite

docs/roadmap.md

@@ -520,7 +520,7 @@ Final docs pass — canonical [`fts.md`](fts.md) reference (mirrors `ask.md`'s s
 ## "Possible extras" not pinned to a phase
 
 - Joins (`INNER`, `LEFT OUTER`, `CROSS`)
-- `GROUP BY`, aggregates (`COUNT`, `SUM`, `AVG`, ...), `DISTINCT`, `LIKE`, `IN`, `IS NULL`
+- `GROUP BY`, aggregates (`COUNT`, `SUM`, `AVG`, ...), `DISTINCT`, `LIKE`, `IN`
 - Composite and expression indexes
 - Alternate storage engines (LSM/SSTable for write-heavy workloads)
 - Benchmarks against SQLite

docs/supported-sql.md

@@ -158,7 +158,7 @@ FROM <table>
 ### What works
 
 - **Projection**: `*` (all columns in declaration order) or a bare column list. Columns not declared on the table are rejected.
-- **`WHERE`**: any [expression](#expressions). Evaluated per row; NULL-as-false in WHERE context (three-valued logic collapsed to two-valued for filtering).
+- **`WHERE`**: any [expression](#expressions). Evaluated per row; NULL-as-false in WHERE context (three-valued logic collapsed to two-valued for filtering). Includes **`IS NULL`** / **`IS NOT NULL`** for explicit null tests.
 - **`ORDER BY`**: single sort key, `ASC` (default) or `DESC`. The sort key can be a bare column reference OR any expression — including function calls — so KNN queries like `ORDER BY vec_distance_l2(embedding, [...]) LIMIT k` work end-to-end *(Phase 7b)*. Sort key types must match; mixing `INTEGER` and `TEXT` across rows under a single `ORDER BY` is a runtime error.
 - **`LIMIT`**: non-negative integer literal. `LIMIT 0` is valid (returns zero rows).
 
@@ -172,7 +172,7 @@ The executor includes a tiny optimizer: if the `WHERE` is exactly `<indexed_col>
 - **Subqueries**, CTEs (`WITH`), views
 - **`GROUP BY`**, aggregate functions (`COUNT`, `SUM`, `AVG`, `MIN`, `MAX`), `HAVING`
 - **`DISTINCT`**
-- **`LIKE`**, **`IN`**, **`IS NULL`** / **`IS NOT NULL`**, `BETWEEN`
+- **`LIKE`**, **`IN`**, `BETWEEN`
 - **Expressions in the projection list** (`SELECT age + 1 FROM users`) — projection is bare column references only
 - **Multi-column `ORDER BY`**, `NULLS FIRST/LAST` (single sort key only; the sort key itself can be an expression as of Phase 7b)
 - **`OFFSET`**
@@ -382,7 +382,7 @@ See [`docs/fts.md`](fts.md) for the canonical FTS reference (tokenizer rules, BM
 
 SQLRite follows standard SQL three-valued logic:
 
-- **Comparisons involving NULL** (`NULL = 1`, `1 < NULL`) evaluate to unknown, which behaves as `false` inside `WHERE`. Neither the NULL = NULL equality nor the NULL <> NULL inequality is true — use `IS NULL` / `IS NOT NULL` for explicit null tests (both **not yet supported**).
+- **Comparisons involving NULL** (`NULL = 1`, `1 < NULL`) evaluate to unknown, which behaves as `false` inside `WHERE`. Neither the NULL = NULL equality nor the NULL <> NULL inequality is true — use **`IS NULL`** / **`IS NOT NULL`** for explicit null tests (`SELECT … WHERE col IS NULL`). NULLs are not stored in secondary, HNSW, or FTS indexes, so `IS NULL` always falls through to a full scan; that's correct, just not as fast as an indexed equality probe.
 - **Logical operators with NULL**: `NULL AND false` → `false`, `NULL AND true` → `NULL`, `NULL OR true` → `true`, `NOT NULL` → `NULL`. The short-circuit rules prevent NULL from propagating when one operand already decides the result.
 - **Arithmetic with NULL**: any operand NULL → result NULL. `NULL + 1` → `NULL`.
 - **String concat with NULL**: `'foo' || NULL` → `NULL` (same propagation as arithmetic).
@@ -503,7 +503,6 @@ For context when you hit `NotImplemented`. See [Roadmap](roadmap.md) for when th
 ### Predicate & expression
 - `LIKE`, `GLOB`, `REGEXP`
 - `IN (...)`, `NOT IN`, `BETWEEN`
-- `IS NULL`, `IS NOT NULL` (pending — use `col = NULL` is NOT a workaround since it's always false; the only current way to select NULL rows is to rely on the NULL-as-false-in-WHERE behavior being absent when the column isn't referenced)
 - `CASE WHEN ... THEN ... END`
 - Expressions in the `SELECT` projection list
 - Column aliases (`AS`)

docs/usage.md

@@ -42,9 +42,9 @@ Quick hits worth knowing when you're working at the REPL:
 - **One statement per call.** The REPL / `Connection::execute` expects a single statement; multi-statement strings return `Expected a single query statement, but there are N`. For batch execution use the SDKs' `executescript` / `execute_batch`.
 - **Transactions are real.** `BEGIN` / `COMMIT` / `ROLLBACK` land as expected; auto-save is suppressed inside a transaction and everything flushes in one WAL commit frame on `COMMIT`. No nested transactions yet.
 - **Arithmetic stays honest.** Integer-only operations stay integer; any `REAL` operand promotes to `f64`; divide-by-zero is a typed runtime error, never a panic.
-- **NULL follows three-valued logic.** `NULL = NULL` is unknown (not true) — treated as false in `WHERE`. Use `IS NULL` / `IS NOT NULL` — oh wait, [those aren't supported yet](supported-sql.md#not-yet-supported). Track via Roadmap.
+- **NULL follows three-valued logic.** `NULL = NULL` is unknown (not true) — treated as false in `WHERE`. Use `IS NULL` / `IS NOT NULL` for explicit null tests, e.g. `SELECT id FROM t WHERE qty IS NULL;`.
 - **Identifiers are case-sensitive** (table / column names; no normalization), but keywords aren't. String literals preserve case.
-- **Not yet supported**: joins, subqueries, `GROUP BY` / aggregates, `DISTINCT`, `LIKE` / `IN` / `IS NULL`, projection expressions, column aliases, `OFFSET`, multi-column `ORDER BY`, savepoints, `ALTER TABLE`, `DROP TABLE`, `DROP INDEX`. See the [full list in the reference](supported-sql.md#not-yet-supported).
+- **Not yet supported**: joins, subqueries, `GROUP BY` / aggregates, `DISTINCT`, `LIKE` / `IN`, projection expressions, column aliases, `OFFSET`, multi-column `ORDER BY`, savepoints, `ALTER TABLE`, `DROP TABLE`, `DROP INDEX`. See the [full list in the reference](supported-sql.md#not-yet-supported).
 
 ## History