@mindstudio-ai/agent 0.1.162 → 0.1.163

package/dist/index.js

@@ -572,36 +572,35 @@ function serializeParam(val) {
   return JSON.stringify(val);
 }
 function serializeColumnParam(val, columnName, columns) {
-  const col = columns.find((c) => c.name === columnName);
+  const col = columnsByName(columns).get(columnName);
   if (col?.type === "user" && typeof val === "string") {
     return val.startsWith(USER_PREFIX) ? val : `${USER_PREFIX}${val}`;
   }
   return serializeParam(val);
 }
-function escapeValue(val) {
-  if (val === null || val === void 0) {
-    return "NULL";
-  }
-  if (typeof val === "boolean") {
-    return val ? "1" : "0";
-  }
-  if (typeof val === "number") {
-    return String(val);
-  }
-  if (typeof val === "string") {
-    return `'${val.replace(/'/g, "''")}'`;
+var USER_PREFIX = "@@user@@";
+var byNameCache = /* @__PURE__ */ new WeakMap();
+function columnsByName(columns) {
+  let byName = byNameCache.get(columns);
+  if (!byName) {
+    byName = /* @__PURE__ */ new Map();
+    for (const column of columns) {
+      if (!byName.has(column.name)) {
+        byName.set(column.name, column);
+      }
+    }
+    byNameCache.set(columns, byName);
   }
-  const json = JSON.stringify(val);
-  return `'${json.replace(/'/g, "''")}'`;
+  return byName;
 }
-var USER_PREFIX = "@@user@@";
 function deserializeRow(row, columns) {
   if (row == null) {
     return row;
   }
   const result = {};
+  const byName = columnsByName(columns);
   for (const [key, value] of Object.entries(row)) {
-    const col = columns.find((c) => c.name === key);
+    const col = byName.get(key);
     if (typeof value === "string" && value.startsWith(USER_PREFIX)) {
       result[key] = value.slice(USER_PREFIX.length);
     } else if (col?.type === "json" && typeof value === "string") {
@@ -627,8 +626,50 @@ function deserializeRow(row, columns) {
   }
   return result;
 }
+function storageClass(value) {
+  if (value === null || value === void 0) {
+    return 0;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return 1;
+  }
+  if (value instanceof Uint8Array) {
+    return 3;
+  }
+  return 2;
+}
+function compareAsSqlite(a, b) {
+  const classA = storageClass(a);
+  const classB = storageClass(b);
+  if (classA !== classB) {
+    return classA - classB;
+  }
+  if (classA === 1) {
+    return Number(a) - Number(b);
+  }
+  if (classA === 2) {
+    const textA = typeof a === "string" ? a : JSON.stringify(a);
+    const textB = typeof b === "string" ? b : JSON.stringify(b);
+    return textA < textB ? -1 : textA > textB ? 1 : 0;
+  }
+  if (classA === 3) {
+    const bytesA = a;
+    const bytesB = b;
+    for (let i = 0; i < Math.min(bytesA.length, bytesB.length); i++) {
+      if (bytesA[i] !== bytesB[i]) {
+        return bytesA[i] - bytesB[i];
+      }
+    }
+    return bytesA.length - bytesB.length;
+  }
+  return 0;
+}
 function buildSelect(table, options = {}) {
-  let sql = `SELECT * FROM ${table}`;
+  for (const column of options.columns ?? []) {
+    assertSqlIdentifier(column, "selected column");
+  }
+  const selected = options.columns?.length ? options.columns.join(", ") : "*";
+  let sql = `SELECT ${selected} FROM ${table}`;
   const params = [];
   if (options.where) {
     sql += ` WHERE ${options.where}`;
@@ -639,11 +680,13 @@ function buildSelect(table, options = {}) {
   if (options.orderBy) {
     sql += ` ORDER BY ${options.orderBy}${options.desc ? " DESC" : " ASC"}`;
   }
-  if (options.limit != null) {
-    sql += ` LIMIT ${options.limit}`;
+  if (options.limit != null || options.offset != null) {
+    sql += " LIMIT ?";
+    params.push(options.limit ?? -1);
   }
   if (options.offset != null) {
-    sql += ` OFFSET ${options.offset}`;
+    sql += " OFFSET ?";
+    params.push(options.offset);
   }
   return { sql, params: params.length > 0 ? params : void 0 };
 }
@@ -712,13 +755,12 @@ function buildGroupedAggregate(table, options) {
   if (options.orderBy) {
     sql += ` ORDER BY ${options.orderBy}${options.desc ? " DESC" : " ASC"}`;
   }
+  const params = [...options.whereParams ?? []];
   if (options.limit != null) {
-    sql += ` LIMIT ${options.limit}`;
+    sql += " LIMIT ?";
+    params.push(options.limit);
   }
-  return {
-    sql,
-    params: options.whereParams?.length ? options.whereParams : void 0
-  };
+  return { sql, params: params.length > 0 ? params : void 0 };
 }
 function buildExists(table, where, whereParams, negate) {
   const inner = where ? `SELECT 1 FROM ${table} WHERE ${where}` : `SELECT 1 FROM ${table}`;
@@ -788,6 +830,16 @@ function stripSystemColumns(data) {
   return result;
 }
 
+// src/db/time.ts
+var timeHelpers = {
+  now: () => Date.now(),
+  days: (n) => n * 864e5,
+  hours: (n) => n * 36e5,
+  minutes: (n) => n * 6e4,
+  ago: (ms) => Date.now() - ms,
+  fromNow: (ms) => Date.now() + ms
+};
+
 // src/db/predicate.ts
 function compilePredicate(fn, bindings, columns = []) {
   try {
@@ -802,9 +854,9 @@ function compilePredicate(fn, bindings, columns = []) {
     }
     const tokens = tokenize(body);
     if (tokens.length === 0) {
-      return { type: "js", fn, reason: "empty token stream" };
+      return { type: "js", fn, reason: "unsupported syntax" };
     }
-    const parser = new Parser(tokens, names.row, names.bindings, bindings, fn);
+    const parser = new Parser(tokens, names.row, names.bindings, bindings);
     const ast = parser.parseExpression();
     if (!ast) {
       return { type: "js", fn, reason: "could not parse expression" };
@@ -812,11 +864,12 @@ function compilePredicate(fn, bindings, columns = []) {
     if (parser.pos < tokens.length) {
       return { type: "js", fn, reason: "unexpected tokens after expression" };
     }
-    const where = compileNode(ast, columns);
+    const params = [];
+    const where = compileNode(ast, false, columns, params);
     if (!where) {
       return { type: "js", fn, reason: "could not compile to SQL" };
     }
-    return { type: "sql", where };
+    return { type: "sql", where, params };
   } catch (err) {
     return {
       type: "js",
@@ -896,146 +949,221 @@ function extractBody(source) {
   }
   return body.trim() || null;
 }
+var OPERATORS = [
+  "===",
+  "!==",
+  "==",
+  "!=",
+  "<=",
+  ">=",
+  "&&",
+  "||",
+  "!",
+  "<",
+  ">",
+  "+",
+  "-",
+  "*",
+  "/",
+  "%"
+];
+var PUNCTUATION = {
+  ".": "dot",
+  "(": "lparen",
+  ")": "rparen",
+  "[": "lbracket",
+  "]": "rbracket",
+  ",": "comma"
+};
+var Unreadable = class extends Error {
+};
 function tokenize(expr) {
   const tokens = [];
   let i = 0;
-  while (i < expr.length) {
-    const ch = expr[i];
-    if (/\s/.test(ch)) {
-      i++;
-      continue;
-    }
-    if (ch === "'" || ch === '"') {
-      const quote = ch;
-      let str = "";
-      i++;
-      while (i < expr.length && expr[i] !== quote) {
-        if (expr[i] === "\\") {
-          i++;
-          if (i < expr.length) {
-            str += expr[i];
-          }
-        } else {
-          str += expr[i];
-        }
+  try {
+    while (i < expr.length) {
+      const ch = expr[i];
+      if (/\s/.test(ch)) {
         i++;
+        continue;
       }
-      if (i >= expr.length) {
-        return [];
+      if (ch === "'" || ch === '"' || ch === "`") {
+        const read = readString(expr, i);
+        tokens.push({ type: "string", value: read.value });
+        i = read.end;
+        continue;
       }
-      i++;
-      tokens.push({ type: "string", value: str });
-      continue;
-    }
-    if (ch === "`") {
-      return [];
-    }
-    if (/[0-9]/.test(ch) || ch === "-" && i + 1 < expr.length && /[0-9]/.test(expr[i + 1])) {
-      let num = ch;
-      i++;
-      while (i < expr.length && /[0-9.]/.test(expr[i])) {
-        num += expr[i];
+      if (/[0-9]/.test(ch) || ch === "." && /[0-9]/.test(expr[i + 1] ?? "")) {
+        const read = readNumber(expr, i);
+        tokens.push({ type: "number", value: read.text, number: read.value });
+        i = read.end;
+        continue;
+      }
+      const op = OPERATORS.find((o) => expr.startsWith(o, i));
+      if (op) {
+        tokens.push({ type: "operator", value: op });
+        i += op.length;
+        continue;
+      }
+      if (PUNCTUATION[ch]) {
+        tokens.push({ type: PUNCTUATION[ch], value: ch });
         i++;
+        continue;
       }
-      tokens.push({ type: "number", value: num });
-      continue;
-    }
-    if (expr.slice(i, i + 3) === "===" || expr.slice(i, i + 3) === "!==") {
-      tokens.push({ type: "operator", value: expr.slice(i, i + 3) });
-      i += 3;
-      continue;
-    }
-    if (expr.slice(i, i + 2) === "==" || expr.slice(i, i + 2) === "!=" || expr.slice(i, i + 2) === "<=" || expr.slice(i, i + 2) === ">=" || expr.slice(i, i + 2) === "&&" || expr.slice(i, i + 2) === "||") {
-      tokens.push({ type: "operator", value: expr.slice(i, i + 2) });
-      i += 2;
-      continue;
-    }
-    if (ch === "!" || ch === "<" || ch === ">") {
-      tokens.push({ type: "operator", value: ch });
-      i++;
-      continue;
-    }
-    if (ch === ".") {
-      tokens.push({ type: "dot", value: "." });
-      i++;
-      continue;
-    }
-    if (ch === "(") {
-      tokens.push({ type: "lparen", value: "(" });
-      i++;
-      continue;
+      if (/[a-zA-Z_$]/.test(ch)) {
+        let ident = ch;
+        i++;
+        while (i < expr.length && /[a-zA-Z0-9_$]/.test(expr[i])) {
+          ident += expr[i];
+          i++;
+        }
+        tokens.push({ type: "identifier", value: ident });
+        continue;
+      }
+      return [];
     }
-    if (ch === ")") {
-      tokens.push({ type: "rparen", value: ")" });
-      i++;
-      continue;
+  } catch (err) {
+    if (err instanceof Unreadable) {
+      return [];
     }
-    if (ch === "[") {
-      tokens.push({ type: "lbracket", value: "[" });
-      i++;
-      continue;
+    throw err;
+  }
+  return tokens;
+}
+function readString(expr, start) {
+  const quote = expr[start];
+  let value = "";
+  let i = start + 1;
+  while (i < expr.length && expr[i] !== quote) {
+    const ch = expr[i];
+    if (quote === "`" && ch === "$" && expr[i + 1] === "{") {
+      throw new Unreadable("template substitution");
     }
-    if (ch === "]") {
-      tokens.push({ type: "rbracket", value: "]" });
+    if (ch !== "\\") {
+      value += ch;
       i++;
       continue;
     }
-    if (ch === ",") {
-      tokens.push({ type: "comma", value: "," });
-      i++;
-      continue;
+    const escaped = readEscape(expr, i + 1);
+    value += escaped.value;
+    i = escaped.end;
+  }
+  if (i >= expr.length) {
+    throw new Unreadable("unterminated string");
+  }
+  return { value, end: i + 1 };
+}
+var SINGLE_ESCAPES = {
+  n: "\n",
+  r: "\r",
+  t: "	",
+  b: "\b",
+  f: "\f",
+  v: "\v"
+};
+function readEscape(expr, start) {
+  const ch = expr[start];
+  if (ch === void 0) {
+    throw new Unreadable("unterminated escape");
+  }
+  if (ch in SINGLE_ESCAPES) {
+    return { value: SINGLE_ESCAPES[ch], end: start + 1 };
+  }
+  if (ch === "0" && !/[0-9]/.test(expr[start + 1] ?? "")) {
+    return { value: "\0", end: start + 1 };
+  }
+  if (/[0-9]/.test(ch)) {
+    throw new Unreadable("octal escape");
+  }
+  if (ch === "x") {
+    const hex = expr.slice(start + 1, start + 3);
+    if (!/^[0-9a-fA-F]{2}$/.test(hex)) {
+      throw new Unreadable("bad \\x escape");
     }
-    if (/[a-zA-Z_$]/.test(ch)) {
-      let ident = ch;
-      i++;
-      while (i < expr.length && /[a-zA-Z0-9_$]/.test(expr[i])) {
-        ident += expr[i];
-        i++;
+    return { value: String.fromCharCode(parseInt(hex, 16)), end: start + 3 };
+  }
+  if (ch === "u") {
+    if (expr[start + 1] === "{") {
+      const close = expr.indexOf("}", start + 2);
+      const hex2 = close === -1 ? "" : expr.slice(start + 2, close);
+      const code = parseInt(hex2, 16);
+      if (!/^[0-9a-fA-F]{1,6}$/.test(hex2) || code > 1114111) {
+        throw new Unreadable("bad \\u{} escape");
       }
-      tokens.push({ type: "identifier", value: ident });
-      continue;
+      return { value: String.fromCodePoint(code), end: close + 1 };
     }
-    return [];
+    const hex = expr.slice(start + 1, start + 5);
+    if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
+      throw new Unreadable("bad \\u escape");
+    }
+    return { value: String.fromCharCode(parseInt(hex, 16)), end: start + 5 };
   }
-  return tokens;
+  if (ch === "\r" && expr[start + 1] === "\n") {
+    return { value: "", end: start + 2 };
+  }
+  if (ch === "\n" || ch === "\r" || ch === "\u2028" || ch === "\u2029") {
+    return { value: "", end: start + 1 };
+  }
+  return { value: ch, end: start + 1 };
+}
+function readNumber(expr, start) {
+  const match = /^0[xX][0-9a-fA-F_]+|^0[oO][0-7_]+|^0[bB][01_]+|^(?:[0-9][0-9_]*)?\.?[0-9_]*(?:[eE][+-]?[0-9_]+)?/.exec(
+    expr.slice(start)
+  );
+  const text = match?.[0] ?? "";
+  const end = start + text.length;
+  if (!text || /[a-zA-Z0-9_$]/.test(expr[end] ?? "")) {
+    throw new Unreadable("unsupported number");
+  }
+  const value = Number(text.replace(/_/g, ""));
+  if (!Number.isFinite(value)) {
+    throw new Unreadable("non-finite number");
+  }
+  return { text, value, end };
 }
+var PARSE_FAILED = /* @__PURE__ */ Symbol("PARSE_FAILED");
+var COMPARISON_OPS = /* @__PURE__ */ new Set([
+  "===",
+  "!==",
+  "==",
+  "!=",
+  "<",
+  ">",
+  "<=",
+  ">="
+]);
+var FLIPPED = {
+  "===": "===",
+  "!==": "!==",
+  "==": "==",
+  "!=": "!=",
+  "<": ">",
+  ">": "<",
+  "<=": ">=",
+  ">=": "<="
+};
 var Parser = class {
-  constructor(tokens, paramName, bindingsName, bindingsValue, originalFn) {
+  constructor(tokens, paramName, bindingsName, bindingsValue) {
     this.tokens = tokens;
     this.paramName = paramName;
     this.bindingsName = bindingsName;
     this.bindingsValue = bindingsValue;
-    this.originalFn = originalFn;
   }
   tokens;
   paramName;
   bindingsName;
   bindingsValue;
-  originalFn;
   pos = 0;
-  /** Peek at the current token without consuming it. */
-  peek() {
-    return this.tokens[this.pos];
+  peek(offset = 0) {
+    return this.tokens[this.pos + offset];
   }
-  /** Consume the current token and advance. */
   advance() {
     return this.tokens[this.pos++];
   }
-  /** Check if the current token matches an expected type and value. */
-  match(type, value) {
-    const t = this.peek();
-    if (!t) {
-      return false;
-    }
-    if (t.type !== type) {
-      return false;
-    }
-    if (value !== void 0 && t.value !== value) {
-      return false;
-    }
-    return true;
+  match(type, value, offset = 0) {
+    const t = this.peek(offset);
+    return !!t && t.type === type && (value === void 0 || t.value === value);
   }
-  /** Consume a token if it matches, otherwise return false. */
   eat(type, value) {
     if (this.match(type, value)) {
       this.advance();
@@ -1044,18 +1172,15 @@ var Parser = class {
     return false;
   }
   // --- Grammar rules ---
-  /** Entry point: parse a full expression. */
   parseExpression() {
     return this.parseOr();
   }
-  /** or_expr → and_expr ( '||' and_expr )* */
   parseOr() {
     let left = this.parseAnd();
     if (!left) {
       return null;
     }
-    while (this.match("operator", "||")) {
-      this.advance();
+    while (this.eat("operator", "||")) {
       const right = this.parseAnd();
       if (!right) {
         return null;
@@ -1064,14 +1189,12 @@ var Parser = class {
     }
     return left;
   }
-  /** and_expr → not_expr ( '&&' not_expr )* */
   parseAnd() {
     let left = this.parseNot();
     if (!left) {
       return null;
     }
-    while (this.match("operator", "&&")) {
-      this.advance();
+    while (this.eat("operator", "&&")) {
       const right = this.parseNot();
       if (!right) {
         return null;
@@ -1080,72 +1203,48 @@ var Parser = class {
     }
     return left;
   }
-  /** not_expr → '!' not_expr | primary */
   parseNot() {
-    if (this.match("operator", "!")) {
-      this.advance();
-      if (this.match("lparen")) {
-        this.advance();
-        const inner2 = this.parseExpression();
-        if (!inner2) {
-          return null;
-        }
-        if (!this.eat("rparen")) {
-          return null;
-        }
-        return { kind: "not", operand: inner2 };
-      }
-      const inner = this.parsePrimary();
-      if (!inner) {
-        return null;
-      }
-      if (inner.kind === "booleanField") {
-        return { ...inner, negated: !inner.negated };
-      }
-      return { kind: "not", operand: inner };
+    if (this.eat("operator", "!")) {
+      const operand = this.parseNot();
+      return operand ? { kind: "not", operand } : null;
     }
     return this.parsePrimary();
   }
-  /**
-   * primary → field_comparison | null_check | includes_expr | paren_expr | boolean_field
-   *
-   * This is the workhorse — handles the different patterns that can appear
-   * as atomic expressions within a larger &&/|| combination.
-   */
   parsePrimary() {
-    if (this.match("lparen")) {
-      this.advance();
+    if (this.eat("lparen")) {
       const inner = this.parseExpression();
-      if (!inner) {
-        return null;
-      }
-      if (!this.eat("rparen")) {
+      if (!inner || !this.eat("rparen")) {
         return null;
       }
       return inner;
     }
-    if (this.match("lbracket")) {
-      return this.parseArrayIncludes();
-    }
     if (this.match("identifier", this.paramName)) {
       return this.parseFieldExpression();
     }
-    if (this.bindingsName && this.match("identifier", this.bindingsName)) {
-      return this.parseBindingsArrayIncludes();
+    const membership = this.tryParseMembership();
+    if (membership) {
+      return membership;
     }
-    if (this.match("identifier")) {
-      return this.parseNonParamExpression();
+    const start = this.pos;
+    const value = this.parseValue();
+    if (value !== PARSE_FAILED && this.match("operator")) {
+      const op = this.peek().value;
+      if (COMPARISON_OPS.has(op) && this.match("identifier", this.paramName, 1)) {
+        this.advance();
+        this.advance();
+        const field = this.parseFieldPath();
+        if (field && !this.lookAheadForIncludes()) {
+          return comparisonNode(field, FLIPPED[op], value);
+        }
+      }
     }
+    this.pos = start;
     return null;
   }
   /**
-   * Parse an expression that starts with the parameter name (e.g. `o.field`).
-   *
-   * Could be:
-   * - `o.field === value` (comparison)
-   * - `o.field != null` (null check)
-   * - `o.field.includes('text')` (LIKE)
-   * - `o.field` alone (boolean field check)
+   * An expression starting with the row parameter: a comparison
+   * (`o.field === value`), `o.field.includes(x)`, or the field alone, read
+   * for its truthiness.
    */
   parseFieldExpression() {
     this.advance();
@@ -1153,236 +1252,185 @@ var Parser = class {
     if (!field) {
       return null;
     }
-    const next = this.peek();
-    if (next?.type === "dot" && this.lookAheadForIncludes()) {
+    if (this.lookAheadForIncludes()) {
       return this.parseFieldIncludes(field);
     }
-    if (next?.type === "operator" && isComparisonOp(next.value)) {
-      return this.parseComparison(field);
+    const next = this.peek();
+    if (next?.type === "operator" && COMPARISON_OPS.has(next.value)) {
+      this.advance();
+      const value = this.parseValue();
+      if (value === PARSE_FAILED) {
+        return null;
+      }
+      return comparisonNode(field, next.value, value);
     }
-    return { kind: "booleanField", field, negated: false };
+    return { kind: "truthy", field };
   }
   /**
-   * Parse a dot-separated field path after the parameter name.
-   * `o.status` → `"status"`, `o.address.city` → `"json_extract(address, '$.city')"`.
+   * The field path after the row parameter: `.status` → the column,
+   * `.address.city` → `json_extract(address, '$.city')`. Stops before a
+   * method call. `.length` isn't a field (it's a string's or array's length,
+   * which `json_extract` can't read), so a path holding it fails.
    */
   parseFieldPath() {
-    if (!this.eat("dot")) {
-      return null;
-    }
-    if (!this.match("identifier")) {
+    if (!this.eat("dot") || !this.match("identifier")) {
       return null;
     }
     const parts = [this.advance().value];
-    while (this.match("dot") && this.tokens[this.pos + 1]?.type === "identifier") {
-      if (this.tokens[this.pos + 2]?.type === "lparen") {
+    while (this.match("dot") && this.match("identifier", void 0, 1)) {
+      if (this.match("lparen", void 0, 2)) {
         break;
       }
       this.advance();
       parts.push(this.advance().value);
     }
-    if (parts.length === 1) {
-      return parts[0];
-    }
-    const root = parts[0];
-    const jsonPath = "$." + parts.slice(1).join(".");
-    return `json_extract(${root}, '${jsonPath}')`;
-  }
-  /**
-   * Parse a comparison: `field OP value`.
-   * The field has already been parsed; we need the operator and right-hand value.
-   */
-  parseComparison(field) {
-    const opToken = this.advance();
-    const jsOp = opToken.value;
-    const value = this.parseValue();
-    if (value === PARSE_FAILED) {
-      return null;
-    }
-    if (value === null || value === void 0) {
-      if (jsOp === "===" || jsOp === "==") {
-        return { kind: "nullCheck", field, isNull: true };
-      }
-      if (jsOp === "!==" || jsOp === "!=") {
-        return { kind: "nullCheck", field, isNull: false };
-      }
+    if (parts.slice(1).includes("length")) {
       return null;
     }
-    const sqlOp = JS_TO_SQL_OP[jsOp];
-    if (!sqlOp) {
-      return null;
+    const column = parts[0];
+    if (parts.length === 1) {
+      return { sql: column, column, nested: false };
     }
-    return { kind: "comparison", field, operator: sqlOp, value };
+    const path = `$.${parts.slice(1).join(".")}`;
+    return {
+      sql: `json_extract(${column}, '${path}')`,
+      column,
+      nested: true,
+      path
+    };
   }
-  /**
-   * Parse `o.field.includes('text')` → LIKE expression.
-   * The field name has already been parsed.
-   */
+  /** `o.field.includes(needle)`, the field already read. */
   parseFieldIncludes(field) {
     this.advance();
     this.advance();
     if (!this.eat("lparen")) {
       return null;
     }
-    const value = this.parseValue();
-    if (value === PARSE_FAILED || typeof value !== "string") {
+    const needle = this.parseValue();
+    if (typeof needle !== "string" && typeof needle !== "number" && typeof needle !== "boolean") {
       return null;
     }
     if (!this.eat("rparen")) {
       return null;
     }
-    const escaped = value.replace(/%/g, "\\%").replace(/_/g, "\\_");
-    return { kind: "like", field, pattern: `%${escaped}%` };
+    return { kind: "includes", field, needle };
   }
   /**
-   * Parse `['a', 'b', 'c'].includes(o.field)` → IN expression.
-   * The opening bracket has been peeked but not consumed.
+   * `[...].includes(o.field)` or `$.path.includes(o.field)`, when that's what
+   * follows; null (position restored) otherwise.
    */
-  parseArrayIncludes() {
-    this.advance();
-    const values = [];
-    while (!this.match("rbracket")) {
-      if (values.length > 0) {
-        if (!this.eat("comma")) {
+  tryParseMembership() {
+    const start = this.pos;
+    let values = null;
+    if (this.eat("lbracket")) {
+      const items = [];
+      while (!this.match("rbracket")) {
+        if (items.length > 0 && !this.eat("comma")) {
+          this.pos = start;
+          return null;
+        }
+        const item = this.parseValue();
+        if (item === PARSE_FAILED) {
+          this.pos = start;
           return null;
         }
+        items.push(item);
       }
-      const val = this.parseValue();
-      if (val === PARSE_FAILED) {
-        return null;
+      this.advance();
+      values = items;
+    } else if (this.bindingsName && this.match("identifier", this.bindingsName)) {
+      const bound = this.tryResolveBindingsValue();
+      if (Array.isArray(bound)) {
+        values = bound;
       }
-      values.push(val);
-    }
-    this.advance();
-    if (!this.eat("dot")) {
-      return null;
     }
-    if (!this.match("identifier", "includes")) {
+    if (!values || !this.lookAheadForIncludes() || !this.match("identifier", this.paramName, 3)) {
+      this.pos = start;
       return null;
     }
     this.advance();
-    if (!this.eat("lparen")) {
-      return null;
-    }
-    if (!this.match("identifier", this.paramName)) {
-      return null;
-    }
     this.advance();
-    const field = this.parseFieldPath();
-    if (!field) {
-      return null;
-    }
-    if (!this.eat("rparen")) {
-      return null;
-    }
-    return { kind: "in", field, values };
-  }
-  /**
-   * Parse an expression that starts with an identifier that is NOT the
-   * parameter name. This could be:
-   * - A keyword literal: `true`, `false`, `null`, `undefined`
-   * - A closure variable used in a comparison (handled by backtracking)
-   */
-  parseNonParamExpression() {
-    const ident = this.peek().value;
-    if (ident === "true" || ident === "false") {
-      return null;
-    }
-    return null;
-  }
-  /**
-   * Parse `$.ids.includes(o.field)` → IN expression with resolved values.
-   * The bindings identifier has been peeked but not consumed.
-   *
-   * Falls back (returns null) if the resolved bindings value isn't an array,
-   * or if the path doesn't exist on the bindings object.
-   */
-  parseBindingsArrayIncludes() {
-    const bound = this.tryResolveBindingsValue();
-    if (bound === PARSE_FAILED) {
-      return null;
-    }
-    if (!Array.isArray(bound)) {
-      return null;
-    }
-    if (!this.eat("dot")) {
-      return null;
-    }
-    if (!this.match("identifier", "includes")) {
-      return null;
-    }
     this.advance();
-    if (!this.eat("lparen")) {
-      return null;
-    }
-    if (!this.match("identifier", this.paramName)) {
-      return null;
-    }
     this.advance();
     const field = this.parseFieldPath();
-    if (!field) {
+    if (!field || !this.eat("rparen")) {
       return null;
     }
-    if (!this.eat("rparen")) {
-      return null;
-    }
-    return { kind: "in", field, values: bound };
+    return { kind: "in", field, values };
   }
   /**
-   * If the current token is the bindings parameter name, walk a dotted path
-   * (`$.foo.bar`) and resolve the value from the bindings object. Returns
-   * the resolved value or `PARSE_FAILED`.
-   *
-   * Stops walking before a method call (e.g. doesn't consume `.includes` in
-   * `$.ids.includes(...)`) so the caller can dispatch on what follows.
-   *
-   * Restores `pos` on failure so callers can fall through cleanly.
+   * Walk a dotted bindings path (`$.foo.bar`) and resolve it from the
+   * bindings object. Stops before a method call (`.includes(`), so the caller
+   * can dispatch on what follows. Restores `pos` and returns `PARSE_FAILED`
+   * when the path doesn't resolve: a missing key or `undefined` value falls
+   * back rather than being compared as NULL.
    */
   tryResolveBindingsValue() {
-    if (!this.bindingsName) {
-      return PARSE_FAILED;
-    }
-    if (!this.match("identifier", this.bindingsName)) {
-      return PARSE_FAILED;
-    }
-    if (this.bindingsValue == null) {
+    if (!this.bindingsName || !this.match("identifier", this.bindingsName) || this.bindingsValue == null) {
       return PARSE_FAILED;
     }
     const startPos = this.pos;
     this.advance();
     const path = [];
-    while (this.match("dot") && this.tokens[this.pos + 1]?.type === "identifier") {
-      if (this.tokens[this.pos + 2]?.type === "lparen") {
+    while (this.match("dot") && this.match("identifier", void 0, 1)) {
+      if (this.match("lparen", void 0, 2)) {
         break;
       }
       this.advance();
       path.push(this.advance().value);
     }
-    if (path.length === 0) {
-      this.pos = startPos;
-      return PARSE_FAILED;
-    }
     let value = this.bindingsValue;
     for (const key of path) {
       if (value == null || typeof value !== "object") {
-        this.pos = startPos;
-        return PARSE_FAILED;
+        value = void 0;
+        break;
       }
       value = value[key];
     }
-    if (value === void 0) {
+    if (path.length === 0 || value === void 0) {
       this.pos = startPos;
       return PARSE_FAILED;
     }
     return value;
   }
-  /**
-   * Parse a literal value or closure variable reference.
-   *
-   * Returns the parsed value, or PARSE_FAILED if parsing fails.
-   * Returns `null` or `undefined` for those keyword literals.
-   */
+  // --- Values: constant expressions, evaluated here ---
+  /** A value: a literal, binding or helper call, or arithmetic over numbers. */
   parseValue() {
+    let left = this.parseTerm();
+    while (this.match("operator", "+") || this.match("operator", "-")) {
+      const op = this.advance().value;
+      const right = this.parseTerm();
+      if (typeof left !== "number" || typeof right !== "number") {
+        return PARSE_FAILED;
+      }
+      left = op === "+" ? left + right : left - right;
+    }
+    return left;
+  }
+  parseTerm() {
+    let left = this.parseUnary();
+    while (this.match("operator", "*") || this.match("operator", "/") || this.match("operator", "%")) {
+      const op = this.advance().value;
+      const right = this.parseUnary();
+      if (typeof left !== "number" || typeof right !== "number") {
+        return PARSE_FAILED;
+      }
+      left = op === "*" ? left * right : op === "/" ? left / right : left % right;
+    }
+    return left;
+  }
+  parseUnary() {
+    if (this.match("operator", "-") || this.match("operator", "+")) {
+      const op = this.advance().value;
+      const operand = this.parseUnary();
+      if (typeof operand !== "number") {
+        return PARSE_FAILED;
+      }
+      return op === "-" ? -operand : operand;
+    }
+    return this.parseAtom();
+  }
+  parseAtom() {
     const t = this.peek();
     if (!t) {
       return PARSE_FAILED;
@@ -1393,122 +1441,105 @@ var Parser = class {
     }
     if (t.type === "number") {
       this.advance();
-      return Number(t.value);
+      return t.number;
+    }
+    if (t.type === "lparen") {
+      this.advance();
+      const inner = this.parseValue();
+      return this.eat("rparen") ? inner : PARSE_FAILED;
+    }
+    if (t.type !== "identifier") {
+      return PARSE_FAILED;
     }
-    if (t.type === "identifier") {
-      if (t.value === "true") {
+    switch (t.value) {
+      case "true":
         this.advance();
         return true;
-      }
-      if (t.value === "false") {
+      case "false":
         this.advance();
         return false;
-      }
-      if (t.value === "null") {
+      case "null":
         this.advance();
         return null;
-      }
-      if (t.value === "undefined") {
+      case "undefined":
         this.advance();
         return void 0;
-      }
-      if (this.bindingsName && t.value === this.bindingsName) {
-        const bound = this.tryResolveBindingsValue();
-        if (bound !== PARSE_FAILED) {
-          return bound;
+      case "void":
+        if (this.match("number", void 0, 1)) {
+          this.advance();
+          this.advance();
+          return void 0;
         }
-      }
-      return this.resolveClosureVariable();
+        return PARSE_FAILED;
     }
-    if (t.type === "operator" && t.value === "-") {
-      this.advance();
-      const next = this.peek();
-      if (next?.type === "number") {
+    if (this.bindingsName && t.value === this.bindingsName) {
+      return this.tryResolveBindingsValue();
+    }
+    if (t.value === "Date" && this.match("dot", void 0, 1) && this.match("identifier", "now", 2) && this.match("lparen", void 0, 3) && this.match("rparen", void 0, 4)) {
+      this.pos += 5;
+      return Date.now();
+    }
+    if (t.value === "db" && this.match("dot", void 0, 1) && this.match("lparen", void 0, 3)) {
+      const name = this.peek(2).value;
+      if (Object.hasOwn(timeHelpers, name)) {
+        this.pos += 4;
+        const args = [];
+        while (!this.match("rparen")) {
+          if (args.length > 0 && !this.eat("comma")) {
+            return PARSE_FAILED;
+          }
+          const arg = this.parseValue();
+          if (typeof arg !== "number") {
+            return PARSE_FAILED;
+          }
+          args.push(arg);
+        }
         this.advance();
-        return -Number(next.value);
+        const helper = timeHelpers[name];
+        return helper(...args);
       }
-      return PARSE_FAILED;
-    }
-    return PARSE_FAILED;
-  }
-  /**
-   * Attempt to resolve a closure variable's value.
-   *
-   * This handles the common pattern:
-   * ```ts
-   * const userId = auth.userId;
-   * orders.filter(o => o.requestedBy === userId)
-   * ```
-   *
-   * Closure variable resolution is fundamentally limited in JavaScript —
-   * we can't access another function's closure scope from outside without
-   * `eval`. The `===` operator can't be overridden via Proxy or
-   * Symbol.toPrimitive, so we can't intercept comparisons.
-   *
-   * For now, this falls back to JS execution. The predicate still works
-   * correctly — it just scans all rows instead of generating SQL.
-   * This is the most common reason for JS fallback in practice, since
-   * almost every real-world filter references a variable like `userId`.
-   *
-   * A future improvement could accept an explicit `vars` argument:
-   * ```ts
-   * orders.filter(o => o.requestedBy === $userId, { $userId: auth.userId })
-   * ```
-   */
-  resolveClosureVariable() {
-    this.advance();
-    while (this.match("dot") && this.tokens[this.pos + 1]?.type === "identifier") {
-      this.advance();
-      this.advance();
     }
     return PARSE_FAILED;
   }
-  /**
-   * Look ahead to check if the next tokens form `.includes(`.
-   * Used to disambiguate `o.field.includes(...)` from `o.field.nested`.
-   */
+  /** Whether the next tokens are `.includes(`. */
   lookAheadForIncludes() {
-    return this.tokens[this.pos]?.type === "dot" && this.tokens[this.pos + 1]?.type === "identifier" && this.tokens[this.pos + 1]?.value === "includes" && this.tokens[this.pos + 2]?.type === "lparen";
+    return this.match("dot") && this.match("identifier", "includes", 1) && this.match("lparen", void 0, 2);
   }
 };
-function compileNode(node, columns) {
-  const stored = (field, value) => escapeValue(serializeColumnParam(value, field, columns));
-  switch (node.kind) {
-    case "comparison":
-      return `${node.field} ${node.operator} ${stored(node.field, node.value)}`;
-    case "nullCheck":
-      return `${node.field} ${node.isNull ? "IS NULL" : "IS NOT NULL"}`;
-    case "in": {
-      if (node.values.length === 0) {
-        return "0";
-      }
-      const vals = node.values.map((v) => stored(node.field, v)).join(", ");
-      return `${node.field} IN (${vals})`;
-    }
-    case "like":
-      return `${node.field} LIKE ${escapeValue(node.pattern)}`;
-    case "booleanField":
-      return node.negated ? `${node.field} = 0` : `${node.field} = 1`;
-    case "logical": {
-      const left = compileNode(node.left, columns);
-      const right = compileNode(node.right, columns);
-      if (!left || !right) {
-        return null;
-      }
-      return `(${left} ${node.operator} ${right})`;
-    }
-    case "not": {
-      const inner = compileNode(node.operand, columns);
-      if (!inner) {
-        return null;
-      }
-      return `NOT (${inner})`;
+function comparisonNode(field, op, value) {
+  if (value === null || value === void 0) {
+    if (op === "===" || op === "==" || op === "!==" || op === "!=") {
+      return {
+        kind: "nullCheck",
+        field,
+        strict: op === "===" || op === "!==",
+        isNull: op === "===" || op === "=="
+      };
     }
-    default:
+    return null;
+  }
+  if (value instanceof Date) {
+    if (op === "===" || op === "==" || op === "!==" || op === "!=") {
       return null;
+    }
+    return comparisonNode(field, op, value.getTime());
   }
+  if (typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+    return { kind: "comparison", field, op, value };
+  }
+  return null;
 }
-var JS_TO_SQL_OP = {
+var NEGATED = {
+  "===": "!==",
+  "!==": "===",
+  "==": "!=",
+  "!=": "==",
+  "<": ">=",
+  ">=": "<",
+  ">": "<=",
+  "<=": ">"
+};
+var SQL_OP = {
   "===": "=",
   "==": "=",
   "!==": "!=",
@@ -1518,9 +1549,144 @@ var JS_TO_SQL_OP = {
   "<=": "<=",
   ">=": ">="
 };
-var PARSE_FAILED = /* @__PURE__ */ Symbol("PARSE_FAILED");
-function isComparisonOp(value) {
-  return value in JS_TO_SQL_OP;
+function jsCompare(a, op, b) {
+  const x = a;
+  const y = b;
+  switch (op) {
+    case "===":
+      return x === y;
+    case "!==":
+      return x !== y;
+    case "==":
+      return x == y;
+    case "!=":
+      return x != y;
+    case "<":
+      return x < y;
+    case ">":
+      return x > y;
+    case "<=":
+      return x <= y;
+    case ">=":
+      return x >= y;
+  }
+}
+var VALUE_KIND = {
+  text: "string",
+  user: "string",
+  number: "number",
+  boolean: "boolean"
+};
+var JSON_TYPES = {
+  string: "('text')",
+  number: "('integer', 'real')"
+};
+function nestedComparison(node, negated, params) {
+  const strictEquals = node.op === "===" ? !negated : node.op === "!==" ? negated : null;
+  const types = JSON_TYPES[typeof node.value];
+  if (strictEquals === null || !types) {
+    return null;
+  }
+  params.push(node.value);
+  const equals = `(json_type(${node.field.column}, '${node.field.path}') IN ${types} AND ${node.field.sql} = ?)`;
+  return strictEquals ? equals : `NOT coalesce(${equals}, 0)`;
+}
+function withNulls(core, field, nullsMatch) {
+  return nullsMatch ? `(${core} OR ${field.sql} IS NULL)` : core;
+}
+function compileNode(node, negated, columns, params) {
+  const column = (field) => field.nested ? void 0 : columns.find((c) => c.name === field.column);
+  const stored = (field, value) => field.nested ? serializeColumnParam(value, "", []) : serializeColumnParam(value, field.column, columns);
+  switch (node.kind) {
+    case "logical": {
+      const operator = negated ? node.operator === "AND" ? "OR" : "AND" : node.operator;
+      const left = compileNode(node.left, negated, columns, params);
+      const right = left && compileNode(node.right, negated, columns, params);
+      return left && right ? `(${left} ${operator} ${right})` : null;
+    }
+    case "not":
+      return compileNode(node.operand, !negated, columns, params);
+    case "comparison": {
+      if (node.field.nested) {
+        return nestedComparison(node, negated, params);
+      }
+      const type = column(node.field)?.type;
+      if (!type || typeof node.value !== VALUE_KIND[type]) {
+        return null;
+      }
+      const op = negated ? NEGATED[node.op] : node.op;
+      const nullsMatch = negated ? !jsCompare(null, node.op, node.value) : jsCompare(null, node.op, node.value);
+      params.push(stored(node.field, node.value));
+      if (SQL_OP[op] === "!=" && nullsMatch) {
+        return `${node.field.sql} IS NOT ?`;
+      }
+      return withNulls(
+        `${node.field.sql} ${SQL_OP[op]} ?`,
+        node.field,
+        nullsMatch
+      );
+    }
+    case "nullCheck": {
+      if (node.strict && node.field.nested) {
+        return null;
+      }
+      const isNull = negated ? !node.isNull : node.isNull;
+      return `${node.field.sql} ${isNull ? "IS NULL" : "IS NOT NULL"}`;
+    }
+    case "in": {
+      const type = column(node.field)?.type;
+      if (!type || node.values.some(
+        (v) => v !== null && v !== void 0 && typeof v !== VALUE_KIND[type]
+      )) {
+        return null;
+      }
+      const listed = node.values.filter((v) => v !== null && v !== void 0);
+      const nullsMatch = negated ? !node.values.includes(null) : node.values.includes(null);
+      let core;
+      if (listed.length === 0) {
+        core = negated ? `${node.field.sql} IS NOT NULL` : "0";
+      } else {
+        params.push(JSON.stringify(listed.map((v) => stored(node.field, v))));
+        core = `${node.field.sql} ${negated ? "NOT IN" : "IN"} (SELECT value FROM json_each(?))`;
+      }
+      return withNulls(core, node.field, nullsMatch);
+    }
+    case "includes": {
+      const type = column(node.field)?.type;
+      if (type === "json") {
+        let element;
+        if (typeof node.needle === "boolean") {
+          element = `type = '${node.needle}'`;
+        } else {
+          params.push(node.needle);
+          element = `type IN ${JSON_TYPES[typeof node.needle]} AND value = ?`;
+        }
+        return `(json_type(${node.field.sql}) = 'array' AND ${negated ? "NOT EXISTS" : "EXISTS"} (SELECT 1 FROM json_each(${node.field.sql}) WHERE ${element}))`;
+      }
+      if ((type === "text" || type === "user") && typeof node.needle === "string") {
+        params.push(node.needle);
+        return `instr(${node.field.sql}, ?) ${negated ? "=" : ">"} 0`;
+      }
+      return null;
+    }
+    case "truthy": {
+      const type = column(node.field)?.type;
+      if (node.field.nested) {
+        return negated ? `(${node.field.sql} IN (0, '') OR ${node.field.sql} IS NULL)` : `${node.field.sql} NOT IN (0, '')`;
+      }
+      switch (type) {
+        case "boolean":
+          return negated ? `${node.field.sql} IS NOT 1` : `${node.field.sql} = 1`;
+        case "number":
+          return negated ? `(${node.field.sql} = 0 OR ${node.field.sql} IS NULL)` : `${node.field.sql} <> 0`;
+        case "text":
+        case "user":
+          return negated ? `(${node.field.sql} = '' OR ${node.field.sql} IS NULL)` : `${node.field.sql} <> ''`;
+        default:
+          return null;
+      }
+    }
+  }
 }
 
 // src/db/aggregate.ts
@@ -1631,24 +1797,6 @@ function aggregateValues(fn, values) {
       return present.length === 0 ? null : present.reduce((m, v) => v > m ? v : m);
   }
 }
-function compareForOrder(a, b) {
-  if (a == null && b == null) {
-    return 0;
-  }
-  if (a == null) {
-    return -1;
-  }
-  if (b == null) {
-    return 1;
-  }
-  if (a < b) {
-    return -1;
-  }
-  if (a > b) {
-    return 1;
-  }
-  return 0;
-}
 function computeAggregateInJs(rows, spec) {
   const groups = /* @__PURE__ */ new Map();
   for (const row of rows) {
@@ -1678,7 +1826,7 @@ function computeAggregateInJs(rows, spec) {
   });
   if (spec.orderBy) {
     const key = spec.orderBy;
-    out.sort((a, b) => compareForOrder(a[key], b[key]));
+    out.sort((a, b) => compareAsSqlite(a[key], b[key]));
     if (spec.desc) {
       out.reverse();
     }
@@ -1732,6 +1880,8 @@ var Query = class _Query {
   _rawWhereParams;
   /** @internal See AggregateState — set by aggregate terminals. */
   _aggregate;
+  /** @internal The columns `select()` named; every column when unset. */
+  _columns;
   /** @internal Post-process transform applied after row deserialization. */
   _postProcess;
   constructor(config, options) {
@@ -1745,6 +1895,7 @@ var Query = class _Query {
     this._rawWhere = options?.rawWhere;
     this._rawWhereParams = options?.rawWhereParams;
     this._aggregate = options?.aggregate;
+    this._columns = options?.columns;
   }
   _clone(overrides) {
     return new _Query(this._config, {
@@ -1756,7 +1907,8 @@ var Query = class _Query {
       postProcess: overrides.postProcess,
       rawWhere: this._rawWhere,
       rawWhereParams: this._rawWhereParams,
-      aggregate: overrides.aggregate ?? this._aggregate
+      aggregate: overrides.aggregate ?? this._aggregate,
+      columns: overrides.columns ?? this._columns
     });
   }
   filter(predicate, bindings) {
@@ -1776,6 +1928,21 @@ var Query = class _Query {
   skip(n) {
     return this._clone({ offset: n });
   }
+  /**
+   * Return only these columns: `SELECT id, name` rather than every column of
+   * a wide row. Chain it before a terminal (`first()`, `take()`); filters and
+   * sorts still see the whole row.
+   *
+   * ```ts
+   * const names = await Companies
+   *   .filter((c, $) => c.firmId === $.firmId, { firmId })
+   *   .select('id', 'name');
+   * // Array<{ id: string; name: string }>
+   * ```
+   */
+  select(...columns) {
+    return this._clone({ columns });
+  }
   // -------------------------------------------------------------------------
   // Terminal methods
   // -------------------------------------------------------------------------
@@ -1863,8 +2030,8 @@ var Query = class _Query {
     if (compiled.allSql && compiled.sqlWhere) {
       const query = buildExists(
         this._config.tableName,
-        `NOT (${compiled.sqlWhere})`,
-        void 0,
+        `NOT coalesce(${compiled.sqlWhere}, 0)`,
+        compiled.params,
         true
       );
       const results = await this._config.executeBatch([query]);
@@ -1906,116 +2073,152 @@ var Query = class _Query {
   // Batch compilation — used by db.batch() to extract SQL without executing
   // -------------------------------------------------------------------------
   /**
-   * @internal Compile this query into a SqlQuery for batch execution.
-   *
-   * Returns the compiled SQL query (if all predicates compile to SQL),
-   * or null (if JS fallback is needed). In the fallback case, a bare
-   * `SELECT *` is returned as `fallbackQuery` so the batch can fetch
-   * all rows and this query can filter them in JS post-fetch.
+   * @internal Compile this query into the statement to run, plus whatever
+   * JS has to do with its rows (see the module header's three cases). Used by
+   * db.batch() and by a standalone await alike.
    */
   _compile() {
+    const table = this._config.tableName;
     if (this._rawWhere) {
-      const query = buildSelect(this._config.tableName, {
-        where: this._rawWhere,
-        whereParams: this._rawWhereParams,
-        orderBy: void 0,
-        limit: this._limit,
-        offset: this._offset
-      });
       return {
         type: "query",
-        query,
-        fallbackQuery: null,
+        query: buildSelect(table, {
+          columns: this._columns,
+          where: this._rawWhere,
+          whereParams: this._rawWhereParams,
+          limit: this._limit,
+          offset: this._offset
+        }),
         config: this._config,
         postProcess: this._postProcess
       };
     }
     const compiled = this._compilePredicates();
-    const sortField = this._sortAccessor ? extractFieldName(this._sortAccessor) : void 0;
-    if (compiled.allSql) {
-      const agg = this._compileAggregateSql(compiled.sqlWhere);
-      if (agg) {
-        return {
-          type: "query",
-          query: agg.query,
-          fallbackQuery: null,
-          config: this._config,
-          processRaw: agg.processRaw
-        };
-      }
-      const query = buildSelect(this._config.tableName, {
-        where: compiled.sqlWhere || void 0,
-        orderBy: sortField ?? void 0,
-        desc: this._reversed,
-        limit: this._limit,
-        offset: this._offset
-      });
+    if (!compiled.allSql) {
+      const reasons = compiled.compiled.flatMap(
+        (c) => c.type === "js" && c.reason ? [c.reason] : []
+      );
       return {
         type: "query",
-        query,
-        fallbackQuery: null,
+        query: buildSelect(table, {
+          orderBy: !this._sortAccessor && this._reversed ? "rowid" : void 0
+        }),
         config: this._config,
+        inJs: {
+          why: `filter could not be compiled to SQL${reasons.length ? ` (${reasons.join("; ")})` : ""}`,
+          predicates: this._predicates,
+          sortAccessor: this._sortAccessor,
+          reversed: this._reversed,
+          limit: this._limit,
+          offset: this._offset,
+          columns: this._columns
+        },
+        postProcess: this._postProcess
+      };
+    }
+    const agg = this._compileAggregateSql(compiled.sqlWhere, compiled.params);
+    if (agg) {
+      return {
+        type: "query",
+        query: agg.query,
+        config: this._config,
+        processRaw: agg.processRaw
+      };
+    }
+    const sortField = this._sortAccessor ? extractFieldName(this._sortAccessor) : null;
+    if (this._sortAccessor && sortField == null) {
+      return {
+        type: "query",
+        query: buildSelect(table, {
+          where: compiled.sqlWhere || void 0,
+          whereParams: compiled.params
+        }),
+        config: this._config,
+        inJs: {
+          why: "sortBy is computed, not a column, so it sorts in JS",
+          sortAccessor: this._sortAccessor,
+          reversed: this._reversed,
+          limit: this._limit,
+          offset: this._offset,
+          columns: this._columns
+        },
         postProcess: this._postProcess
       };
     }
-    const fallbackQuery = buildSelect(this._config.tableName);
     return {
       type: "query",
-      query: null,
-      fallbackQuery,
+      query: buildSelect(table, {
+        columns: this._columns,
+        where: compiled.sqlWhere || void 0,
+        whereParams: compiled.params,
+        orderBy: sortField ?? (this._reversed ? "rowid" : void 0),
+        desc: this._reversed,
+        limit: this._limit,
+        offset: this._offset
+      }),
       config: this._config,
-      predicates: this._predicates,
-      sortAccessor: this._sortAccessor,
-      reversed: this._reversed,
-      limit: this._limit,
-      offset: this._offset,
       postProcess: this._postProcess
     };
   }
   /**
    * @internal Process raw SQL results into typed rows. Used by db.batch()
-   * after executing the compiled query.
+   * after executing the compiled query, and by a standalone await.
    *
-   * For SQL-compiled queries: just deserialize the rows.
-   * For JS-fallback queries: filter, sort, and slice in JS.
+   * Deserializes the rows, then does in JS whatever the SQL couldn't
+   * (`inJs`): the filter, the sort, the page, the projection.
    */
   static _processResults(result, compiled) {
     if (compiled.processRaw) {
       return compiled.processRaw(result);
     }
-    const rows = result.rows.map(
-      (row) => deserializeRow(
-        row,
-        compiled.config.columns
-      )
+    const columns = compiled.config.columns;
+    let rows = result.rows.map(
+      (row) => deserializeRow(row, columns)
     );
-    if (compiled.query) {
-      return compiled.postProcess ? compiled.postProcess(rows) : rows;
-    }
-    let filtered = compiled.predicates ? rows.filter(
-      (row) => compiled.predicates.every((p) => p.fn(row, p.bindings))
-    ) : rows;
-    if (compiled.sortAccessor) {
-      const accessor = compiled.sortAccessor;
-      const reversed = compiled.reversed ?? false;
-      filtered.sort((a, b) => {
-        const aVal = accessor(a);
-        const bVal = accessor(b);
-        if (aVal < bVal) {
-          return reversed ? 1 : -1;
-        }
-        if (aVal > bVal) {
-          return reversed ? -1 : 1;
-        }
-        return 0;
-      });
+    const inJs = compiled.inJs;
+    if (inJs) {
+      if (inJs.predicates?.length) {
+        rows = rows.filter(
+          (row) => inJs.predicates.every((p) => p.fn(row, p.bindings))
+        );
+      }
+      if (inJs.sortAccessor) {
+        const accessor = inJs.sortAccessor;
+        const direction = inJs.reversed ? -1 : 1;
+        rows.sort(
+          (a, b) => direction * compareAsSqlite(accessor(a), accessor(b))
+        );
+      } else if (inJs.reversed) {
+        rows.reverse();
+      }
+      if (inJs.offset != null || inJs.limit != null) {
+        const start = inJs.offset ?? 0;
+        const end = inJs.limit != null ? start + inJs.limit : void 0;
+        rows = rows.slice(start, end);
+      }
+      if (inJs.columns?.length) {
+        const keep = inJs.columns;
+        rows = rows.map(
+          (row) => Object.fromEntries(
+            keep.map((column) => [
+              column,
+              row[column]
+            ])
+          )
+        );
+      }
     }
-    if (compiled.offset != null || compiled.limit != null) {
-      const start = compiled.offset ?? 0;
-      const end = compiled.limit != null ? start + compiled.limit : void 0;
-      filtered = filtered.slice(start, end);
+    return compiled.postProcess ? compiled.postProcess(rows) : rows;
+  }
+  /** @internal Say that part of a query ran in JS, and why. */
+  static _warnInJs(compiled, rowsRead) {
+    if (!compiled.inJs) {
+      return;
     }
-    return compiled.postProcess ? compiled.postProcess(filtered) : filtered;
+    const read = rowsRead == null ? "" : ` (${rowsRead} rows read)`;
+    console.warn(
+      `[mindstudio] Query on '${compiled.config.tableName}': ${compiled.inJs.why} \u2014 processing in JS${read}`
+    );
   }
   // -------------------------------------------------------------------------
   // PromiseLike
@@ -2025,18 +2228,10 @@ var Query = class _Query {
   }
   async _run() {
     await this._config.ready?.();
-    if (this._aggregate && !this._rawWhere) {
-      const compiled = this._compilePredicates();
-      if (compiled.allSql) {
-        const agg = this._compileAggregateSql(compiled.sqlWhere);
-        if (agg) {
-          const results = await this._config.executeBatch([agg.query]);
-          return agg.processRaw(results[0]);
-        }
-      }
-    }
-    const rows = await this._execute();
-    return this._postProcess ? this._postProcess(rows) : rows;
+    const compiled = this._compile();
+    const results = await this._config.executeBatch([compiled.query]);
+    _Query._warnInJs(compiled, results[0]?.rows.length);
+    return _Query._processResults(results[0], compiled);
   }
   /**
    * @internal Compile the pending aggregate into a single SQL statement +
@@ -2047,7 +2242,7 @@ var Query = class _Query {
    * when a scalar accessor doesn't extract to a column (computed accessors
    * stay correct via JS, with a warning to prompt optimization).
    */
-  _compileAggregateSql(sqlWhere) {
+  _compileAggregateSql(sqlWhere, whereParams) {
     const agg = this._aggregate;
     if (!agg || this._rawWhere || this._limit != null || this._offset != null) {
       return null;
@@ -2068,7 +2263,8 @@ var Query = class _Query {
         this._config.tableName,
         agg.fn,
         column,
-        where
+        where,
+        whereParams
       );
       const processRaw2 = (result) => {
         const value = result.rows[0]?.value;
@@ -2084,6 +2280,7 @@ var Query = class _Query {
       by: spec.by,
       select: spec.select,
       where,
+      whereParams,
       orderBy: spec.orderBy,
       desc: spec.desc,
       limit: spec.limit
@@ -2104,89 +2301,22 @@ var Query = class _Query {
   // -------------------------------------------------------------------------
   // Execution internals
   // -------------------------------------------------------------------------
-  async _execute() {
-    if (this._rawWhere) {
-      const query = buildSelect(this._config.tableName, {
-        where: this._rawWhere,
-        whereParams: this._rawWhereParams,
-        limit: this._limit,
-        offset: this._offset
-      });
-      const results = await this._config.executeBatch([query]);
-      return results[0].rows.map(
-        (row) => deserializeRow(
-          row,
-          this._config.columns
-        )
-      );
-    }
-    const compiled = this._compilePredicates();
-    if (compiled.allSql) {
-      const sortField = this._sortAccessor ? extractFieldName(this._sortAccessor) : void 0;
-      const query = buildSelect(this._config.tableName, {
-        where: compiled.sqlWhere || void 0,
-        orderBy: sortField ?? void 0,
-        desc: this._reversed,
-        limit: this._limit,
-        offset: this._offset
-      });
-      const results = await this._config.executeBatch([query]);
-      return results[0].rows.map(
-        (row) => deserializeRow(
-          row,
-          this._config.columns
-        )
-      );
-    }
-    let rows = await this._fetchAndFilterInJs(compiled);
-    if (this._sortAccessor) {
-      const accessor = this._sortAccessor;
-      rows.sort((a, b) => {
-        const aVal = accessor(a);
-        const bVal = accessor(b);
-        if (aVal < bVal) {
-          return this._reversed ? 1 : -1;
-        }
-        if (aVal > bVal) {
-          return this._reversed ? -1 : 1;
-        }
-        return 0;
-      });
-    }
-    if (this._offset != null || this._limit != null) {
-      const start = this._offset ?? 0;
-      const end = this._limit != null ? start + this._limit : void 0;
-      rows = rows.slice(start, end);
-    }
-    return rows;
-  }
   _compilePredicates() {
     if (this._predicates.length === 0) {
-      return { allSql: true, sqlWhere: "", compiled: [] };
+      return { allSql: true, sqlWhere: "", params: [], compiled: [] };
     }
+    const columns = this._config.columns;
     const compiled = this._predicates.map(
-      (p) => compilePredicate(p.fn, p.bindings, this._config.columns)
-    );
-    const allSql = compiled.every((c) => c.type === "sql");
-    let sqlWhere = "";
-    if (allSql) {
-      sqlWhere = compiled.map((c) => c.where).join(" AND ");
-    }
-    return { allSql, sqlWhere, compiled };
-  }
-  async _fetchAndFilterInJs(compiled) {
-    const allRows = await this._fetchAllRows();
-    const jsFallbacks = compiled.compiled.filter((c) => c.type === "js");
-    if (jsFallbacks.length > 0) {
-      const reasons = jsFallbacks.map((c) => c.type === "js" ? c.reason : void 0).filter(Boolean);
-      const reasonSuffix = reasons.length > 0 ? ` (${reasons.join("; ")})` : "";
-      console.warn(
-        `[mindstudio] Filter on '${this._config.tableName}' could not be compiled to SQL${reasonSuffix} \u2014 scanning ${allRows.length} rows in JS`
-      );
-    }
-    return allRows.filter(
-      (row) => this._predicates.every((p) => p.fn(row, p.bindings))
+      (p) => compilePredicate(p.fn, p.bindings, columns)
     );
+    const sql = compiled.flatMap((c) => c.type === "sql" ? [c] : []);
+    const allSql = sql.length === compiled.length;
+    return {
+      allSql,
+      sqlWhere: allSql ? sql.map((c) => c.where).join(" AND ") : "",
+      params: allSql ? sql.flatMap((c) => c.params) : [],
+      compiled
+    };
   }
   async _fetchAllRows() {
     const query = buildSelect(this._config.tableName);
@@ -2205,38 +2335,20 @@ function extractFieldName(accessor) {
 }
 
 // src/db/mutation.ts
-var Mutation = class _Mutation {
+var Mutation = class {
   /** @internal */
   _config;
-  /** @internal */
+  /** @internal The statements, or null when the write can't be one batch. */
   _build;
   /** @internal */
   _processResult;
-  /** @internal Non-batchable executor for complex mutations (e.g. removeAll JS fallback). */
-  _executor;
-  constructor(config, build, processResult) {
+  /** @internal What runs when `_build` returns null (e.g. removeAll's JS fallback). */
+  _fallback;
+  constructor(config, build, processResult, fallback) {
     this._config = config;
     this._build = build;
     this._processResult = processResult;
-    this._executor = void 0;
-  }
-  /**
-   * Create a non-batchable mutation that wraps an async executor.
-   * Used for operations that require multi-step execution (e.g. removeAll
-   * with a JS-fallback predicate: fetch all rows → filter → delete).
-   *
-   * Works fine when awaited standalone. Throws if passed to db.batch().
-   *
-   * @internal
-   */
-  static fromExecutor(config, executor) {
-    const m = new _Mutation(
-      config,
-      () => [],
-      () => void 0
-    );
-    Object.defineProperty(m, "_executor", { value: executor });
-    return m;
+    this._fallback = fallback;
   }
   // -------------------------------------------------------------------------
   // PromiseLike — executes on await
@@ -2254,10 +2366,11 @@ var Mutation = class _Mutation {
    * @internal Compile this mutation into SQL for batch execution.
    * Returns the queries and a result processor.
    *
-   * Throws if this is a non-batchable mutation (created via fromExecutor).
+   * Throws if it can't be expressed as SQL (its builder returned null).
    */
   _compile() {
-    if (this._executor) {
+    const queries = this._build();
+    if (!queries) {
       throw new MindStudioError(
         "This operation cannot be batched (e.g. removeAll with a JS-fallback predicate). Await it separately instead of passing to db.batch().",
         "not_batchable",
@@ -2266,7 +2379,7 @@ var Mutation = class _Mutation {
     }
     return {
       type: "mutation",
-      queries: this._build(),
+      queries,
       config: this._config,
       processResult: this._processResult
     };
@@ -2283,10 +2396,11 @@ var Mutation = class _Mutation {
   // -------------------------------------------------------------------------
   async _execute() {
     await this._config.ready?.();
-    if (this._executor) {
-      return this._executor();
+    const queries = this._build();
+    if (!queries) {
+      return this._fallback();
     }
-    const results = await this._config.executeBatch(this._build());
+    const results = await this._config.executeBatch(queries);
     return this._processResult(results);
   }
 };
@@ -2390,6 +2504,10 @@ var Table = class {
   sortBy(accessor) {
     return new Query(this._config).sortBy(accessor);
   }
+  /** Every row, with only these columns. See Query.select(). */
+  select(...columns) {
+    return new Query(this._config).select(...columns);
+  }
   push(data) {
     const isArray = Array.isArray(data);
     const items = (isArray ? data : [data]).map(
@@ -2460,42 +2578,47 @@ var Table = class {
     );
   }
   removeAll(predicate, bindings) {
-    const sqlWhere = () => {
-      const compiled = compilePredicate(
-        predicate,
-        bindings,
-        this._config.columns
-      );
-      return compiled.type === "sql" ? compiled.where : null;
-    };
-    if (sqlWhere() !== null) {
-      return new Mutation(
-        this._config,
-        () => [buildDelete(this._config.tableName, sqlWhere())],
-        (results) => results[0].changes
-      );
-    }
-    return Mutation.fromExecutor(this._config, async () => {
-      console.warn(
-        `[mindstudio] removeAll predicate on ${this._config.tableName} could not be compiled to SQL \u2014 fetching all rows first`
-      );
-      const allQuery = buildSelect(this._config.tableName);
-      const allResults = await this._config.executeBatch([allQuery]);
-      const allRows = allResults[0].rows.map(
-        (r) => deserializeRow(r, this._config.columns)
-      );
-      const matching = allRows.filter((row) => predicate(row, bindings));
-      if (matching.length === 0) {
-        return 0;
-      }
-      const deleteQueries = matching.filter((row) => row.id).map(
-        (row) => buildDelete(this._config.tableName, `id = ?`, [row.id])
-      );
-      if (deleteQueries.length > 0) {
-        await this._config.executeBatch(deleteQueries);
+    return new Mutation(
+      this._config,
+      () => {
+        const compiled = compilePredicate(
+          predicate,
+          bindings,
+          this._config.columns
+        );
+        return compiled.type === "sql" ? [
+          buildDelete(
+            this._config.tableName,
+            compiled.where,
+            compiled.params
+          )
+        ] : null;
+      },
+      (results) => results[0].changes,
+      // Fallback: multi-step execution — not batchable
+      async () => {
+        console.warn(
+          `[mindstudio] removeAll predicate on ${this._config.tableName} could not be compiled to SQL \u2014 fetching all rows first`
+        );
+        const allQuery = buildSelect(this._config.tableName);
+        const allResults = await this._config.executeBatch([allQuery]);
+        const columns = this._config.columns;
+        const allRows = allResults[0].rows.map(
+          (r) => deserializeRow(r, columns)
+        );
+        const matching = allRows.filter((row) => predicate(row, bindings));
+        if (matching.length === 0) {
+          return 0;
+        }
+        const deleteQueries = matching.filter((row) => row.id).map(
+          (row) => buildDelete(this._config.tableName, `id = ?`, [row.id])
+        );
+        if (deleteQueries.length > 0) {
+          await this._config.executeBatch(deleteQueries);
+        }
+        return matching.length;
       }
-      return matching.length;
-    });
+    );
   }
   clear() {
     const query = buildDelete(this._config.tableName);
@@ -2700,12 +2823,7 @@ function createDb(databases, executeBatch, authConfig, syncRoles) {
     },
     // --- Time helpers ---
     // Pure JS, no platform dependency. All timestamps are unix ms.
-    now: () => Date.now(),
-    days: (n) => n * 864e5,
-    hours: (n) => n * 36e5,
-    minutes: (n) => n * 6e4,
-    ago: (ms) => Date.now() - ms,
-    fromNow: (ms) => Date.now() + ms,
+    ...timeHelpers,
     // --- User references ---
     userRef: (id) => id.startsWith(USER_PREFIX) ? id.slice(USER_PREFIX.length) : id,
     // --- Raw SQL (read-only) ---
@@ -2745,8 +2863,7 @@ function createDb(databases, executeBatch, authConfig, syncRoles) {
             groups.set(dbId, []);
           }
           if (c.type === "query") {
-            const sqlQuery = c.query ?? c.fallbackQuery;
-            groups.get(dbId).push({ opIndex: i, sqlQueries: [sqlQuery] });
+            groups.get(dbId).push({ opIndex: i, sqlQueries: [c.query] });
           } else if (c.type === "raw") {
             groups.get(dbId).push({ opIndex: i, sqlQueries: [c.query] });
           } else {
@@ -2775,11 +2892,7 @@ function createDb(databases, executeBatch, authConfig, syncRoles) {
         return compiled.map((c, i) => {
           const results = opResults.get(i);
           if (c.type === "query") {
-            if (!c.query && c.predicates?.length) {
-              console.warn(
-                `[mindstudio] db.batch(): filter on '${c.config.tableName}' could not be compiled to SQL \u2014 processing in JS`
-              );
-            }
+            Query._warnInJs(c, results[0]?.rows.length);
             return Query._processResults(results[0], c);
           } else if (c.type === "raw") {
             return RawQuery._processResults(results[0], c);
@@ -2875,6 +2988,84 @@ function resolveTable(databases, tableName, databaseHint) {
   );
 }
 
+// src/db/readBatching.ts
+var nextTick = typeof setImmediate === "function" ? (fn) => setImmediate(fn) : (fn) => setTimeout(fn, 0);
+var DbReadBatching = class {
+  constructor(send) {
+    this.send = send;
+  }
+  send;
+  pending = /* @__PURE__ */ new Map();
+  inFlight = /* @__PURE__ */ new Map();
+  /** Run `queries` for the request holding `token`, sharing a round trip where it can. */
+  async run(token, databaseId, queries) {
+    const batchKey = `${token}\0${databaseId}`;
+    if (queries.length === 0 || !queries.every((q) => isReadOnlySql(q.sql))) {
+      this.flush(batchKey);
+      return this.send(databaseId, queries);
+    }
+    const readKey = `${batchKey}\0${JSON.stringify(queries)}`;
+    const shared = this.inFlight.get(readKey);
+    if (shared) {
+      return structuredClone(await shared);
+    }
+    const read = this.queue(batchKey, databaseId, queries);
+    this.inFlight.set(readKey, read);
+    try {
+      return await read;
+    } finally {
+      this.inFlight.delete(readKey);
+    }
+  }
+  queue(batchKey, databaseId, queries) {
+    let pending = this.pending.get(batchKey);
+    if (!pending) {
+      pending = { databaseId, queries: [], parts: [] };
+      this.pending.set(batchKey, pending);
+      nextTick(() => this.flush(batchKey));
+    }
+    const batch = pending;
+    return new Promise((resolve, reject) => {
+      batch.parts.push({
+        queries,
+        start: batch.queries.length,
+        resolve,
+        reject
+      });
+      batch.queries.push(...queries);
+    });
+  }
+  flush(batchKey) {
+    const pending = this.pending.get(batchKey);
+    if (!pending) {
+      return;
+    }
+    this.pending.delete(batchKey);
+    const { databaseId, parts } = pending;
+    if (parts.length === 1) {
+      this.send(databaseId, parts[0].queries).then(
+        parts[0].resolve,
+        parts[0].reject
+      );
+      return;
+    }
+    this.send(databaseId, pending.queries).then(
+      (results) => {
+        for (const part of parts) {
+          part.resolve(
+            results.slice(part.start, part.start + part.queries.length)
+          );
+        }
+      },
+      () => {
+        for (const part of parts) {
+          this.send(databaseId, part.queries).then(part.resolve, part.reject);
+        }
+      }
+    );
+  }
+};
+
 // src/files/store.ts
 import { createHash, randomUUID } from "crypto";
 import { createReadStream, createWriteStream } from "fs";
@@ -7879,15 +8070,25 @@ var MindStudioAgent = class {
     }
     return json;
   }
+  /** @internal Reads started together share a round trip (`db/readBatching.ts`). */
+  _dbReads = new DbReadBatching(
+    (databaseId, queries) => this._sendDbBatch(databaseId, queries)
+  );
   /**
    * @internal Execute a batch of SQL queries against a managed database.
-   * Used as the `executeBatch` callback for Table/Query instances.
-   *
-   * Calls `POST /_internal/v2/db/query` directly with the hook token
-   * (raw, no Bearer prefix). All queries run on a single SQLite connection,
-   * enabling RETURNING clauses and multi-statement batches.
+   * Used as the `executeBatch` callback for Table/Query instances. Reads one
+   * request starts in the same tick go to the platform as one batch.
    */
   async _executeDbBatch(databaseId, queries) {
+    return this._dbReads.run(this._token, databaseId, queries);
+  }
+  /**
+   * @internal Send one batch: `POST /_internal/v2/db/query` directly with the
+   * hook token (raw, no Bearer prefix), or its DB WebSocket. All queries run
+   * on a single SQLite connection, enabling RETURNING clauses and
+   * multi-statement batches.
+   */
+  async _sendDbBatch(databaseId, queries) {
     const dbWsUrl = typeof process !== "undefined" ? process.env?.DB_WS_URL : void 0;
     if (dbWsUrl) {
       try {
@@ -8033,12 +8234,7 @@ var MindStudioAgent = class {
         return new Table(tableConfig);
       },
       // Time helpers work without context
-      now: () => Date.now(),
-      days: (n) => n * 864e5,
-      hours: (n) => n * 36e5,
-      minutes: (n) => n * 6e4,
-      ago: (ms) => Date.now() - ms,
-      fromNow: (ms) => Date.now() + ms,
+      ...timeHelpers,
       userRef: (id) => id.startsWith("@@user@@") ? id.slice("@@user@@".length) : id,
       // Raw SQL — validate synchronously; database resolution needs context,
       // so it happens inside the executeBatch closure at execution time