fix: resolve LIKE/GLOB cache collisions, REGEXP error propagation, alias shadowing, and MVCC visibility bugs

Major fixes:
- LIKE/GLOB dynamic pattern cache collision: separate caches for LIKE vs GLOB,
  include escape char in LIKE cache key, skip fast paths for backslash-escaped
  patterns, fix trailing backslash handling in like_to_regex
- REGEXP error propagation: add matches_checked()/eval_bool_checked() that
  return Result instead of swallowing errors. Propagate through FilteredResult,
  all streaming wrappers, materialization helpers, subquery paths, DML write
  paths, FFI, and the Rows iterator/advance API
- SELECT alias shadowing WHERE clause: build_alias_map_excluding() skips aliases
  that shadow real table column names (including unqualified names from joins),
  preventing incorrect WHERE clause rewriting
- MVCC visibility cache sentinel: change last_txn_id init from -1 to 0 in
  sum_column/min_column/max_column, fixing incorrect aggregation results after
  snapshot recovery (RECOVERY_TRANSACTION_ID = -1 collided with the sentinel)
- RowVec/RowIdVec pool re-entrancy: use try_borrow_mut() instead of
  borrow_mut() to prevent RefCell panics on nested Drop
- View WHERE missing execution context: use RowFilter with ctx instead of
  FilteredResult::with_defaults for parameterized predicates on views
- EXISTS index-probe missing context: apply execution context to cached
  predicate filter before evaluation
- INSERT...SELECT atomicity: materialize source query before writes in
  explicit transactions to prevent partial inserts on late runtime errors
- ScannerResult missing last_error(): bridge scanner.err() to QueryResult trait
- Parallel filter order preservation: use mark-and-extract (bool mask) instead
  of try_reduce to maintain deterministic row order
- Rows close() on error: properly forward result.close() before setting closed

New test files for regression coverage of all fixed bugs.
Updated docs for LIKE ESCAPE, NOT variants, parameterized patterns, and
Node.js driver clone() API.

Author: semihalev

docs/_docs/drivers/nodejs.md

@@ -92,6 +92,7 @@ const db = await Database.open('file:///absolute/path/to/db');
 | Method | Returns | Description |
 |--------|---------|-------------|
 | `Database.open(path)` | `Promise<Database>` | Open a database |
+| `clone()` | `Database` | Clone handle (shared engine, own state) |
 | `execute(sql, params?)` | `Promise<RunResult>` | Execute DML statement |
 | `exec(sql)` | `Promise<void>` | Execute a DDL statement |
 | `query(sql, params?)` | `Promise<Object[]>` | Query rows as objects |
@@ -107,6 +108,7 @@ Sync methods run on the main thread. Faster for simple operations but blocks the
 | Method | Returns | Description |
 |--------|---------|-------------|
 | `Database.openSync(path)` | `Database` | Open a database |
+| `clone()` | `Database` | Clone handle (shared engine, own state) |
 | `executeSync(sql, params?)` | `RunResult` | Execute DML statement |
 | `execSync(sql)` | `void` | Execute a DDL statement |
 | `querySync(sql, params?)` | `Object[]` | Query rows as objects |
@@ -117,7 +119,7 @@ Sync methods run on the main thread. Faster for simple operations but blocks the
 | `prepare(sql)` | `PreparedStatement` | Create a prepared statement |
 | `closeSync()` | `void` | Close the database |
 
-`RunResult` is `{ changes: number }`:
+`RunResult` is `{ changes: number }`. It can be imported as a type:
 
 ```ts
 import { Database, RunResult } from '@stoolap/node';
@@ -146,10 +148,10 @@ await db2.close();
 Pass configuration as query parameters in the path:
 
 ```js
-// Maximum durability (fsync on every WAL write)
+// Maximum durability: fsync on every WAL write
 const db = await Database.open('./mydata?sync=full');
 
-// High throughput (no fsync, larger buffers)
+// High throughput: no fsync, larger buffers
 const db = await Database.open('./mydata?sync=none&wal_buffer_size=131072');
 
 // Custom snapshot interval with compression
@@ -167,7 +169,7 @@ Controls the durability vs. performance trade-off:
 
 | Mode | Value | Description |
 |------|-------|-------------|
-| `none` | `sync=none` | No fsync. Fastest, but data may be lost on crash |
+| `none` | `sync=none` | No fsync. Fastest, data may be lost on crash |
 | `normal` | `sync=normal` | Fsync on commit batches. Good balance (default) |
 | `full` | `sync=full` | Fsync on every WAL write. Slowest, maximum durability |
 
@@ -185,9 +187,27 @@ Controls the durability vs. performance trade-off:
 | `sync_interval_ms` | `10` | Minimum ms between syncs (normal mode) |
 | `wal_compression` | `on` | LZ4 compression for WAL entries |
 | `snapshot_compression` | `on` | LZ4 compression for snapshots |
-| `compression` | -- | Set both `wal_compression` and `snapshot_compression` |
+| `compression` | | Set both `wal_compression` and `snapshot_compression` |
 | `compression_threshold` | `64` | Minimum bytes before compressing an entry |
 
+## Cloning
+
+`clone()` creates a new `Database` handle that shares the same underlying engine (data, indexes, transactions) but has its own executor and error state. Useful for concurrent access patterns such as worker threads.
+
+```js
+const db = await Database.open('./mydata');
+const db2 = db.clone();
+
+// Both see the same data
+await db.execute('INSERT INTO users VALUES ($1, $2)', [1, 'Alice']);
+const row = db2.queryOneSync('SELECT * FROM users WHERE id = $1', [1]);
+// { id: 1, name: 'Alice' }
+
+// Each clone must be closed independently
+await db2.close();
+await db.close();
+```
+
 ## Raw Query Format
 
 `queryRaw` / `queryRawSync` return `{ columns: string[], rows: any[][] }` instead of an array of objects. Faster when you don't need named keys.
@@ -413,7 +433,7 @@ await db.exec('CREATE TABLE embeddings (id INTEGER PRIMARY KEY, vec VECTOR(3))')
 // Insert vectors via SQL string literals
 await db.execute("INSERT INTO embeddings VALUES (1, '[0.1, 0.2, 0.3]')");
 
-// Query — vectors are returned as Float32Array
+// Query: vectors are returned as Float32Array
 const row = await db.queryOne('SELECT vec FROM embeddings WHERE id = 1');
 console.log(row.vec);              // Float32Array(3) [0.1, 0.2, 0.3]
 console.log(row.vec instanceof Float32Array); // true

docs/_docs/sql-features/operators-expressions.md

@@ -82,6 +82,9 @@ SELECT * FROM products WHERE name LIKE '%Pro%';       -- Contains 'Pro'
 
 -- _ matches any single character
 SELECT * FROM products WHERE code LIKE 'A_C';         -- Matches 'ABC', 'A1C', etc.
+
+-- NOT LIKE
+SELECT * FROM products WHERE name NOT LIKE '%test%';
 ```
 
 #### ILIKE (Case-Insensitive)
@@ -90,8 +93,25 @@ SELECT * FROM products WHERE code LIKE 'A_C';         -- Matches 'ABC', 'A1C', e
 -- Same as LIKE but ignores case
 SELECT * FROM products WHERE name ILIKE 'apple%';     -- Matches 'Apple', 'APPLE', 'apple'
 SELECT * FROM users WHERE email ILIKE '%@gmail.com';
+
+-- NOT ILIKE
+SELECT * FROM users WHERE name NOT ILIKE 'admin%';
+```
+
+#### LIKE with ESCAPE
+
+Use the ESCAPE clause when your pattern needs to match literal `%` or `_` characters:
+
+```sql
+-- Match values containing a literal '%' character
+SELECT * FROM metrics WHERE label LIKE '%!%%' ESCAPE '!';
+
+-- Match values containing a literal '_' character
+SELECT * FROM codes WHERE code LIKE 'A!_B' ESCAPE '!';
 ```
 
+The escape character can be any single character. The character immediately after the escape is treated as a literal instead of a wildcard.
+
 #### GLOB (Shell-Style Patterns)
 
 ```sql
@@ -103,15 +123,38 @@ SELECT * FROM files WHERE name GLOB 'file?.dat';
 
 -- [...] matches any character in the set
 SELECT * FROM files WHERE name GLOB '[abc]*';
+
+-- NOT GLOB
+SELECT * FROM files WHERE name NOT GLOB '*.tmp';
 ```
 
 #### REGEXP (Regular Expressions)
 
 ```sql
--- Full regex pattern matching
+-- Full regex pattern matching (Rust regex syntax)
 SELECT * FROM logs WHERE message REGEXP 'error|warning';
 SELECT * FROM users WHERE email REGEXP '^[a-z]+@[a-z]+\.[a-z]+$';
 SELECT * FROM data WHERE value REGEXP '[0-9]{3}-[0-9]{4}';
+
+-- NOT REGEXP
+SELECT * FROM logs WHERE message NOT REGEXP 'debug|trace';
+```
+
+Invalid regex patterns return an error instead of silently matching nothing.
+
+#### Parameterized Patterns
+
+All pattern matching operators support parameterized patterns. The pattern is compiled once and reused for every row:
+
+```sql
+-- LIKE with parameter
+SELECT * FROM products WHERE name LIKE $1;
+
+-- REGEXP with parameter
+SELECT * FROM logs WHERE message REGEXP $1;
+
+-- GLOB with parameter
+SELECT * FROM files WHERE name GLOB $1;
 ```
 
 ## Range Operators

src/api/rows.rs

@@ -226,6 +226,8 @@ pub struct Rows {
     /// Shared column names (Arc to avoid cloning per row)
     columns: CompactArc<Vec<String>>,
     closed: bool,
+    /// Pending error from a filter runtime failure (e.g., invalid REGEXP)
+    pending_error: Option<crate::core::Error>,
 }
 
 impl Rows {
@@ -239,6 +241,7 @@ impl Rows {
             result,
             columns,
             closed: false,
+            pending_error: None,
         }
     }
 
@@ -269,7 +272,26 @@ impl Rows {
         if self.closed {
             return false;
         }
-        self.result.next()
+        if self.result.next() {
+            return true;
+        }
+        // Check for runtime filter errors (e.g., invalid REGEXP)
+        if let Some(err) = self.result.last_error() {
+            self.pending_error = Some(err);
+        }
+        // Clean up resources (scanner close, etc.) now that iteration is done
+        self.close();
+        false
+    }
+
+    /// Return any runtime error that caused `advance()` to return false.
+    ///
+    /// After `advance()` returns `false`, call this to distinguish between
+    /// normal end-of-stream (returns `None`) and a runtime filter error
+    /// like an invalid parameterized REGEXP (returns `Some(error)`).
+    #[inline]
+    pub fn error(&mut self) -> Option<crate::core::Error> {
+        self.pending_error.take()
     }
 
     /// Get a reference to the current row (after a successful `advance()`).
@@ -318,6 +340,11 @@ impl Iterator for Rows {
             let row = self.result.take_row();
             // Arc clone is O(1) - just increments reference count
             Some(Ok(ResultRow::new(row, CompactArc::clone(&self.columns))))
+        } else if let Some(err) = self.result.last_error() {
+            // Surface runtime errors (e.g. invalid REGEXP pattern).
+            // close() forwards to result.close() for proper scanner cleanup
+            self.close();
+            Some(Err(err))
         } else {
             None
         }

src/api/transaction.rs

@@ -336,7 +336,7 @@ impl Transaction {
                 let mut setter = |row: Row| -> Result<(Row, bool)> {
                     // Check WHERE clause if present (uses thread-local VM internally)
                     if let Some(ref filter) = where_filter {
-                        if !filter.matches(&row) {
+                        if !filter.matches_checked(&row)? {
                             return Ok((row, false));
                         }
                     }

src/core/row_vec.rs

@@ -46,7 +46,9 @@ thread_local! {
 #[inline]
 pub fn clear_row_vec_pool() {
     ROW_VEC_POOL.with(|pool| {
-        pool.borrow_mut().clear();
+        if let Ok(mut p) = pool.try_borrow_mut() {
+            p.clear();
+        }
     });
 }
 
@@ -284,7 +286,9 @@ impl RowVec {
     /// Takes the largest available buffer (end of sorted list).
     #[inline]
     pub fn new() -> Self {
-        let v = ROW_VEC_POOL.with(|pool| pool.borrow_mut().pop());
+        // Use try_borrow_mut to avoid panic on re-entrant access
+        // (can happen if Drop triggers nested RowVec creation on the same thread)
+        let v = ROW_VEC_POOL.with(|pool| pool.try_borrow_mut().ok().and_then(|mut p| p.pop()));
         match v {
             Some(buf) => {
                 track_hit!(buf.capacity());
@@ -303,8 +307,12 @@ impl RowVec {
     /// Uses binary search to find smallest buffer >= requested capacity.
     #[inline]
     pub fn with_capacity(capacity: usize) -> Self {
+        // Use try_borrow_mut to avoid panic on re-entrant access
         let v = ROW_VEC_POOL.with(|pool| {
-            let mut pool = pool.borrow_mut();
+            let mut pool = match pool.try_borrow_mut() {
+                Ok(p) => p,
+                Err(_) => return None, // Pool already borrowed — allocate fresh
+            };
             if pool.is_empty() {
                 return None;
             }
@@ -462,7 +470,11 @@ impl Drop for RowVec {
             }
             v.clear();
             ROW_VEC_POOL.with(|pool| {
-                let mut pool = pool.borrow_mut();
+                // Use try_borrow_mut to avoid panic on re-entrant access
+                let mut pool = match pool.try_borrow_mut() {
+                    Ok(p) => p,
+                    Err(_) => return, // Pool already borrowed — let buffer deallocate
+                };
                 if pool.len() < POOL_SIZE {
                     // Pool has room - insert in sorted position (by capacity, ascending)
                     let insert_idx = pool.partition_point(|b| b.capacity() < cap);
@@ -645,7 +657,9 @@ thread_local! {
 #[inline]
 pub fn clear_row_id_vec_pool() {
     ROW_ID_VEC_POOL.with(|pool| {
-        pool.borrow_mut().clear();
+        if let Ok(mut p) = pool.try_borrow_mut() {
+            p.clear();
+        }
     });
 }
 
@@ -663,7 +677,7 @@ impl RowIdVec {
     /// Takes the largest available buffer (end of sorted list).
     #[inline]
     pub fn new() -> Self {
-        let v = ROW_ID_VEC_POOL.with(|pool| pool.borrow_mut().pop());
+        let v = ROW_ID_VEC_POOL.with(|pool| pool.try_borrow_mut().ok().and_then(|mut p| p.pop()));
         match v {
             Some(buf) => Self { inner: Some(buf) },
             None => Self {
@@ -677,7 +691,10 @@ impl RowIdVec {
     #[inline]
     pub fn with_capacity(capacity: usize) -> Self {
         let v = ROW_ID_VEC_POOL.with(|pool| {
-            let mut pool = pool.borrow_mut();
+            let mut pool = match pool.try_borrow_mut() {
+                Ok(p) => p,
+                Err(_) => return None,
+            };
             if pool.is_empty() {
                 return None;
             }
@@ -832,7 +849,10 @@ impl Drop for RowIdVec {
             }
             v.clear();
             ROW_ID_VEC_POOL.with(|pool| {
-                let mut pool = pool.borrow_mut();
+                let mut pool = match pool.try_borrow_mut() {
+                    Ok(p) => p,
+                    Err(_) => return,
+                };
                 if pool.len() < ROW_ID_POOL_SIZE {
                     // Pool has room - insert in sorted position (by capacity, ascending)
                     let insert_idx = pool.partition_point(|b| b.capacity() < cap);

src/executor/aggregation.rs

@@ -1199,7 +1199,7 @@ impl Executor {
 
             // Filter rows using the pre-compiled filter
             for (id, row) in result_rows {
-                if having_filter.matches(&row) {
+                if having_filter.matches_checked(&row)? {
                     result_rows_with_ids.push((id, row));
                 }
             }
@@ -4736,7 +4736,7 @@ impl Executor {
         let mut filtered_rows = RowVec::new();
         let mut new_id = 0i64;
         for (_, row) in rows {
-            if having_filter.matches(&row) {
+            if having_filter.matches_checked(&row)? {
                 filtered_rows.push((new_id, row));
                 new_id += 1;
             }
@@ -5741,6 +5741,9 @@ impl Executor {
 
         // Sample first row to detect key type
         if !result.next() {
+            if let Some(err) = result.last_error() {
+                return Err(err);
+            }
             // Empty result - return empty aggregation
             let mut result_columns = Vec::with_capacity(1 + aggregations.len());
             result_columns.push(group_col_name.clone());
@@ -5875,6 +5878,9 @@ impl Executor {
                 let row = result.row();
                 process_row(row, &mut groups, &mut null_group, &state_template);
             }
+            if let Some(err) = result.last_error() {
+                return Err(err);
+            }
 
             // Build result columns
             let mut result_columns = Vec::with_capacity(1 + aggregations.len());

src/executor/cte.rs

@@ -798,7 +798,7 @@ impl Executor {
 
             let mut rows = RowVec::with_capacity(result_rows.len());
             for (row_id, row) in result_rows {
-                if where_eval.eval_bool(&row) {
+                if where_eval.eval_bool_checked(&row)? {
                     rows.push((row_id, row));
                 }
             }
@@ -1123,7 +1123,7 @@ impl Executor {
             let mut result = RowVec::new();
             let mut row_id = 0i64;
             for (_, row) in cte_rows {
-                if eval.eval_bool(&row) {
+                if eval.eval_bool_checked(&row)? {
                     result.push((row_id, row));
                     row_id += 1;
                 }
@@ -2296,7 +2296,7 @@ impl Executor {
 
             let mut rows = RowVec::with_capacity(result_rows.len());
             for (row_id, row) in result_rows {
-                if where_eval.eval_bool(&row) {
+                if where_eval.eval_bool_checked(&row)? {
                     rows.push((row_id, row));
                 }
             }

src/executor/ddl.rs

@@ -498,6 +498,9 @@ impl Executor {
         while result.next() {
             rows.push(result.take_row());
         }
+        if let Some(err) = result.last_error() {
+            return Err(err);
+        }
 
         // Infer schema from the result columns and first row (if available)
         let mut schema_builder = SchemaBuilder::new(table_name);