@spooky-sync/core 0.0.1-canary.172 → 0.0.1-canary.174

package/dist/index.js

@@ -1693,6 +1693,7 @@ function translateStatement(stmt, vars) {
 			};
 		})
 	};
+	if (/^INFO\s+FOR\s+DB(\s+STRUCTURE)?$/i.test(s)) return { kind: "infoForDb" };
 	if (/^(DEFINE|REMOVE|USE|INFO|RETURN|CANCEL|COMMIT|BEGIN)\b/i.test(s)) return { kind: "noop" };
 	let m = /^CREATE\s+ONLY\s+\$(\w+)\s+CONTENT\s+\$(\w+)$/i.exec(s) || /^UPSERT\s+ONLY\s+\$(\w+)\s+REPLACE\s+\$(\w+)$/i.exec(s);
 	if (m) return {
@@ -1701,10 +1702,10 @@ function translateStatement(stmt, vars) {
 		data: asRow(vars[m[2]]),
 		mode: "replace"
 	};
-	m = /^UPSERT\s+ONLY\s+\$(\w+)\s+MERGE\s+\$(\w+)$/i.exec(s) || /^UPDATE\s+ONLY\s+\$(\w+)\s+MERGE\s+\$(\w+)$/i.exec(s);
+	m = idRe(String.raw`^UPSERT\s+ONLY\s+%ID%\s+MERGE\s+\$(\w+)$`).exec(s) || idRe(String.raw`^UPDATE\s+(?:ONLY\s+)?%ID%\s+MERGE\s+\$(\w+)$`).exec(s);
 	if (m) return {
 		kind: "upsert",
-		id: rid(vars[m[1]]),
+		id: idOperand(m[1], vars),
 		data: asRow(vars[m[2]]),
 		mode: "merge"
 	};
@@ -1719,54 +1720,132 @@ function translateStatement(stmt, vars) {
 			mode: "replace"
 		};
 	}
-	m = /^UPDATE\s+\$(\w+)\s+SET\s+(.+?)(\s+RETURN\s+NONE)?$/i.exec(s);
+	m = idRe(String.raw`^UPDATE\s+%ID%\s+SET\s+(.+?)(\s+RETURN\s+NONE)?$`).exec(s);
 	if (m) return {
 		kind: "updateSet",
-		id: rid(vars[m[1]]),
+		id: idOperand(m[1], vars),
 		sets: parseSetClauses(m[2], vars),
 		returnNone: !!m[3]
 	};
-	m = /^DELETE\s+\$(\w+)$/i.exec(s);
-	if (m) return {
-		kind: "delete",
-		id: rid(vars[m[1]])
-	};
 	m = /^DELETE\s+([A-Za-z_]\w*)$/i.exec(s);
 	if (m) return {
 		kind: "deleteAll",
 		table: m[1]
 	};
-	m = /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+ONLY\s+\$(\w+)$/i.exec(s);
+	m = idRe(String.raw`^DELETE\s+%ID%$`).exec(s);
+	if (m) return {
+		kind: "delete",
+		id: idOperand(m[1], vars)
+	};
+	const { head, limit, start } = peelWindow(s, vars);
+	m = /^SELECT\s+count\(\)\s+FROM\s+([A-Za-z_]\w*)(?:\s+WHERE\s+(.+?))?\s+GROUP\s+ALL$/i.exec(head);
+	if (m) return {
+		kind: "count",
+		table: m[1],
+		where: m[2] ? parseWhere(m[2], vars) : void 0
+	};
+	m = idRe(String.raw`^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+ONLY\s+%ID%$`).exec(head);
 	if (m) {
 		const value = m[1] ? m[2].trim() : void 0;
 		return {
 			kind: "getById",
-			id: rid(vars[m[3]]),
+			id: idOperand(m[3], vars),
 			select: projFields(m[2], !!m[1]),
 			value
 		};
 	}
-	m = /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+\$(\w+)$/i.exec(s);
+	m = /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+\$(\w+)$/i.exec(head);
 	if (m) {
 		const value = m[1] ? m[2].trim() : void 0;
 		return {
 			kind: "selectByIds",
 			ids: vars[m[3]] ?? [],
 			select: projFields(m[2], !!m[1]),
-			value
+			value,
+			limit,
+			start
 		};
 	}
-	m = /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+([A-Za-z_]\w*)(?:\s+WHERE\s+(.+?))?(?:\s+ORDER\s+BY\s+(.+?))?$/i.exec(s);
+	m = /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+([A-Za-z_]\w*)(?:\s+WHERE\s+(.+?))?(?:\s+ORDER\s+BY\s+(.+?))?$/i.exec(head);
 	if (m) return {
 		kind: "selectTable",
 		table: m[3],
 		where: m[4] ? parseWhere(m[4], vars) : void 0,
 		orderBy: m[5] ? parseOrderBy(m[5]) : void 0,
 		select: projFields(m[2], !!m[1]),
-		value: m[1] ? m[2].trim() : void 0
+		value: m[1] ? m[2].trim() : void 0,
+		limit,
+		start
 	};
 	throw new Error(`SqliteCacheEngine: unsupported SurrealQL for translation: ${stmt}`);
 }
+/**
+* Split a SELECT's trailing `LIMIT n [START m]` off its head.
+*
+* Peeled rather than folded into the SELECT regexes because those match WHERE
+* and ORDER BY lazily: with the window left in place the WHERE group happily
+* expands over `… LIMIT 20`, which is how `SELECT * FROM t LIMIT 20 START 0`
+* ended up unmatched entirely.
+*
+* A tail sitting inside a string literal (`WHERE note = 'LIMIT 5'`) is left
+* alone — an odd quote count in the head means the match is inside a string.
+*/
+function peelWindow(stmt, vars) {
+	let head = stmt;
+	let limit;
+	let start;
+	const peel = (re) => {
+		const m = re.exec(head);
+		if (!m) return void 0;
+		const before = head.slice(0, m.index);
+		if (countQuotes(before) % 2 !== 0) return void 0;
+		head = before;
+		return m[1];
+	};
+	const startTok = peel(/\s+START(?:\s+AT)?\s+(\$?\w+)\s*$/i);
+	const limitTok = peel(/\s+LIMIT(?:\s+BY)?\s+(\$?\w+)\s*$/i);
+	if (startTok !== void 0) start = numOperand(startTok, vars);
+	if (limitTok !== void 0) limit = numOperand(limitTok, vars);
+	return {
+		head,
+		limit,
+		start
+	};
+}
+function countQuotes(s) {
+	let n = 0;
+	for (let i = 0; i < s.length; i++) if (s[i] === "'" && s[i - 1] !== "\\") n++;
+	return n;
+}
+/** A `LIMIT`/`START` operand: a literal integer or a `$var` holding one. */
+function numOperand(token, vars) {
+	const raw = token.startsWith("$") ? vars[token.slice(1)] : token;
+	const n = Number(raw);
+	return Number.isFinite(n) ? n : void 0;
+}
+/**
+* A single-record operand: `$var` or a LITERAL `table:id`.
+*
+* A bare identifier deliberately does NOT match: in SurrealQL that is a table,
+* and `UPDATE game MERGE $x` rewrites every row of `game` — a shape this
+* vocabulary does not implement. Not matching means such a statement reaches
+* the "unsupported SurrealQL" throw instead of quietly writing one row called
+* `game`.
+*/
+const ID_TOKEN = String.raw`(\$\w+|[A-Za-z_]\w*:\S+)`;
+/** Build a statement regex, `%ID%` expanding to {@link ID_TOKEN}. */
+function idRe(pattern) {
+	return new RegExp(pattern.replace("%ID%", ID_TOKEN), "i");
+}
+/**
+* Resolve an {@link ID_TOKEN} match. Literals matter because the DevTools row
+* editor inlines the id (`UPDATE game:abc MERGE $updates`) rather than binding
+* it; `stableKey` treats that string and a `RecordId` identically downstream.
+*/
+function idOperand(token, vars) {
+	const t = token.trim();
+	return t.startsWith("$") ? rid(vars[t.slice(1)]) : t;
+}
 function projFields(proj, isValue) {
 	const p = proj.trim();
 	if (isValue) return void 0;
@@ -2680,14 +2759,44 @@ var SqliteCacheEngine = class {
 					select: op.select,
 					orderBy: op.orderBy
 				});
+				if (op.start !== void 0 || op.limit !== void 0) {
+					const from = op.start ?? 0;
+					rows = rows.slice(from, op.limit === void 0 ? void 0 : from + op.limit);
+				}
 				if (op.value) return rows.map((r) => r[op.value]);
 				return rows;
 			}
 			case "selectTable": {
-				const rows = await this.rawSelectTable(op.table, op.where, op.orderBy);
+				const rows = await this.rawSelectTable(op.table, op.where, op.orderBy, {
+					limit: op.limit,
+					start: op.start
+				});
 				if (op.value) return rows.map((r) => r[op.value]);
 				return op.select ? rows.map((r) => project(r, op.select)) : rows;
 			}
+			case "count": {
+				await this.ensureTable(op.table);
+				const bind = [];
+				let sql = `SELECT COUNT(*) AS n FROM "${op.table}"`;
+				if (op.where && op.where.length > 0) sql += ` WHERE ${renderWhereSql(op.where, bind, {})}`;
+				const { rows } = await this.call("exec", {
+					sql,
+					bind
+				});
+				return [{ count: rows?.[0]?.n ?? 0 }];
+			}
+			case "infoForDb": {
+				const { rows } = await this.call("exec", { sql: "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name" });
+				const tables = {};
+				for (const r of rows ?? []) tables[r.name] = `DEFINE TABLE ${r.name} SCHEMALESS`;
+				return {
+					tables,
+					analyzers: {},
+					functions: {},
+					params: {},
+					users: {}
+				};
+			}
 			case "upsert":
 				await this.upsert(tableOf(op.id), op.id, op.data, op.mode);
 				return pureWriteOpResult(op);
@@ -2774,12 +2883,15 @@ var SqliteCacheEngine = class {
 		}
 		if (stmts.length > 0) await this.call("batch", stmts);
 	}
-	async rawSelectTable(table, where, orderBy) {
+	async rawSelectTable(table, where, orderBy, window) {
 		await this.ensureTable(table);
 		const bind = [];
 		let sql = `SELECT data FROM "${table}"`;
 		if (where && where.length > 0) sql += ` WHERE ${renderWhereSql(where, bind, {})}`;
 		if (orderBy && orderBy.length > 0) sql += renderOrderSql(orderBy);
+		if (window?.limit !== void 0) sql += ` LIMIT ${Number(window.limit)}`;
+		else if (window?.start !== void 0) sql += " LIMIT -1";
+		if (window?.start !== void 0) sql += ` OFFSET ${Number(window.start)}`;
 		return this.execRows(sql, bind);
 	}
 	async transaction(fn) {
@@ -6754,8 +6866,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.172";
-const WASM_VERSION = "0.0.1-canary.172";
+const CORE_VERSION = "0.0.1-canary.174";
+const WASM_VERSION = "0.0.1-canary.174";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -6980,6 +7092,7 @@ var DevToolsService = class DevToolsService {
 			database: {
 				tables: this.localTables.length ? this.localTables : this.schema.tables.map((t) => t.name),
 				tableData: {},
+				engine: this.databaseService.engineKind ?? "custom",
 				storage: this.databaseService.storageHealth ?? {
 					status: "unknown",
 					fallback: false
@@ -11185,7 +11298,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.172",
+				coreVersion: "0.0.1-canary.174",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.172",
+  "version": "0.0.1-canary.174",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.172",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.172",
+    "@spooky-sync/query-builder": "0.0.1-canary.174",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.174",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",

package/src/modules/devtools/index.ts

@@ -370,6 +370,10 @@ export class DevToolsService implements StreamUpdateReceiver {
           ? this.localTables
           : this.schema.tables.map((t) => t.name),
         tableData: {},
+        // Which backend answers "Local". The Database explorer labels its source
+        // picker with it and explains translation failures against `sqlite`,
+        // whose SurrealQL vocabulary is a bounded subset.
+        engine: this.databaseService.engineKind ?? 'custom',
         // Durability of the local store. `fallback: true` means persistence was
         // requested but the dataset is actually sitting in RAM.
         storage: this.databaseService.storageHealth ?? { status: 'unknown', fallback: false },

package/src/services/database/sqlite-cache-engine.ts

@@ -906,14 +906,44 @@ export class SqliteCacheEngine implements LocalStore {
           select: op.select,
           orderBy: op.orderBy,
         });
+        // Windowed in JS, not SQL: the id list is already the whole result set,
+        // and its order is restored after the fetch (see selectByIds).
+        if (op.start !== undefined || op.limit !== undefined) {
+          const from = op.start ?? 0;
+          rows = rows.slice(from, op.limit === undefined ? undefined : from + op.limit);
+        }
         if (op.value) return rows.map((r) => r[op.value!]);
         return rows;
       }
       case 'selectTable': {
-        const rows = await this.rawSelectTable(op.table, op.where, op.orderBy);
+        const rows = await this.rawSelectTable(op.table, op.where, op.orderBy, {
+          limit: op.limit,
+          start: op.start,
+        });
         if (op.value) return rows.map((r) => r[op.value!]);
         return op.select ? rows.map((r) => project(r, op.select!)) : rows;
       }
+      case 'count': {
+        await this.ensureTable(op.table);
+        const bind: unknown[] = [];
+        let sql = `SELECT COUNT(*) AS n FROM "${op.table}"`;
+        if (op.where && op.where.length > 0) sql += ` WHERE ${renderWhereSql(op.where, bind, {})}`;
+        const { rows } = await this.call<{ rows: { n: number }[] }>('exec', { sql, bind });
+        // `GROUP ALL` collapses to a single `{ count }` row on SurrealDB; match
+        // it exactly so callers can read `rows[0].count` on either engine.
+        return [{ count: rows?.[0]?.n ?? 0 }];
+      }
+      case 'infoForDb': {
+        const { rows } = await this.call<{ rows: { name: string }[] }>('exec', {
+          sql: "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name",
+        });
+        // SurrealDB answers with the DEFINE statement per table. Nothing here
+        // parses it (the DevTools explorer only reads the keys), so a truthful
+        // schemaless stand-in beats inventing field definitions.
+        const tables: Record<string, string> = {};
+        for (const r of rows ?? []) tables[r.name] = `DEFINE TABLE ${r.name} SCHEMALESS`;
+        return { tables, analyzers: {}, functions: {}, params: {}, users: {} };
+      }
       case 'upsert':
         await this.upsert(tableOf(op.id), op.id, op.data, op.mode);
         // Cheap return — no read-back. The full merged row is only needed by a
@@ -1018,13 +1048,19 @@ export class SqliteCacheEngine implements LocalStore {
   private async rawSelectTable(
     table: string,
     where?: WhereNode[],
-    orderBy?: OrderBy
+    orderBy?: OrderBy,
+    window?: { limit?: number; start?: number }
   ): Promise<Row[]> {
     await this.ensureTable(table);
     const bind: unknown[] = [];
     let sql = `SELECT data FROM "${table}"`;
     if (where && where.length > 0) sql += ` WHERE ${renderWhereSql(where, bind, {})}`;
     if (orderBy && orderBy.length > 0) sql += renderOrderSql(orderBy);
+    // SQLite has no bare OFFSET, so a START without a LIMIT needs `LIMIT -1`
+    // (its documented "no limit" sentinel) to stay valid SQL.
+    if (window?.limit !== undefined) sql += ` LIMIT ${Number(window.limit)}`;
+    else if (window?.start !== undefined) sql += ' LIMIT -1';
+    if (window?.start !== undefined) sql += ` OFFSET ${Number(window.start)}`;
     return this.execRows(sql, bind);
   }
 

package/src/services/database/sqlite-devtools-queries.integration.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
+import { SqliteCacheEngine } from './sqlite-cache-engine';
+import { stubTransport } from './sqlite-transport.fixture';
+import { serializeRow } from './sqlite-plan-sql';
+import type { Row } from './cache-engine';
+
+/**
+ * Integration: the DevTools Database explorer's statements run end-to-end
+ * (translate → engine SQL → REAL in-memory SQLite, the same
+ * @sqlite.org/sqlite-wasm build the worker loads). The unit test asserts the
+ * translation; this asserts the SQL actually executes and returns the right
+ * rows — the paging window in particular is easy to render into invalid SQLite
+ * (there is no bare OFFSET).
+ */
+
+let db: any;
+
+function makeLogger(): any {
+  const noop = () => {};
+  const l: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  l.child = () => l;
+  return l;
+}
+
+/** An engine whose transport is a real SQLite database. */
+function realEngine(): SqliteCacheEngine {
+  const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, makeLogger());
+  stubTransport(engine, (type, payload: any) => {
+    switch (type) {
+      case 'open':
+        for (const t of payload.systemTables ?? []) {
+          db.exec({
+            sql: `CREATE TABLE IF NOT EXISTS "${t}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)`,
+          });
+        }
+        return { persisted: true };
+      case 'exec':
+        return {
+          rows: db.exec({
+            sql: payload.sql,
+            bind: payload.bind,
+            rowMode: 'object',
+            returnValue: 'resultRows',
+          }),
+        };
+      case 'run':
+        db.exec({ sql: payload.sql, bind: payload.bind });
+        return {};
+      case 'batch':
+        for (const stmt of payload as { sql: string; bind?: unknown[] }[]) {
+          db.exec({ sql: stmt.sql, bind: stmt.bind });
+        }
+        return {};
+      default:
+        return {};
+    }
+  });
+  return engine;
+}
+
+function seed(table: string, rows: Row[]): void {
+  db.exec({
+    sql: `CREATE TABLE IF NOT EXISTS "${table}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)`,
+  });
+  for (const row of rows) {
+    db.exec({
+      sql: `INSERT INTO "${table}"(id, data) VALUES(?, ?)`,
+      bind: [row.id, serializeRow(row)],
+    });
+  }
+}
+
+beforeAll(async () => {
+  const sqlite3: any = await sqlite3InitModule();
+  db = new sqlite3.oo1.DB(':memory:', 'c');
+  seed(
+    'game_insight',
+    Array.from({ length: 5 }, (_, i) => ({
+      id: `game_insight:${i}`,
+      n: i,
+      tag: i % 2 ? 'odd' : 'even',
+    }))
+  );
+});
+
+describe('DevTools explorer against real SQLite', () => {
+  it('pages a table with LIMIT/START', async () => {
+    const engine = realEngine();
+    await engine.connect('anon');
+
+    const [page1] = await engine.query<[Row[]]>('SELECT * FROM game_insight LIMIT 2 START 0');
+    const [page2] = await engine.query<[Row[]]>('SELECT * FROM game_insight LIMIT 2 START 2');
+    const [tail] = await engine.query<[Row[]]>('SELECT * FROM game_insight LIMIT 20 START 4');
+
+    expect(page1.map((r) => r.id)).toEqual(['game_insight:0', 'game_insight:1']);
+    expect(page2.map((r) => r.id)).toEqual(['game_insight:2', 'game_insight:3']);
+    expect(tail.map((r) => r.id)).toEqual(['game_insight:4']);
+  });
+
+  it('counts rows, with and without a filter', async () => {
+    const engine = realEngine();
+    await engine.connect('anon');
+
+    const [all] = await engine.query<[{ count: number }[]]>(
+      'SELECT count() FROM game_insight GROUP ALL'
+    );
+    const [odd] = await engine.query<[{ count: number }[]]>(
+      "SELECT count() FROM game_insight WHERE tag = 'odd' GROUP ALL"
+    );
+
+    expect(all).toEqual([{ count: 5 }]);
+    expect(odd).toEqual([{ count: 2 }]);
+  });
+
+  it('lists tables via INFO FOR DB', async () => {
+    const engine = realEngine();
+    await engine.connect('anon');
+
+    const [info] = await engine.query<[{ tables: Record<string, string> }]>('INFO FOR DB');
+
+    expect(Object.keys(info.tables)).toContain('game_insight');
+    // Seeded system tables show up too — the panel's "internal" toggle filters
+    // them, the engine must not pre-filter.
+    expect(Object.keys(info.tables)).toContain('_00_query');
+    expect(Object.keys(info.tables).some((t) => t.startsWith('sqlite_'))).toBe(false);
+  });
+
+  it('edits and deletes a row by literal record id', async () => {
+    const engine = realEngine();
+    await engine.connect('anon');
+
+    await engine.query('UPDATE game_insight:1 MERGE $updates', { updates: { tag: 'edited' } });
+    const [edited] = await engine.query<[Row[]]>('SELECT * FROM game_insight LIMIT 20 START 1');
+    expect(edited[0]).toMatchObject({ id: 'game_insight:1', n: 1, tag: 'edited' });
+
+    await engine.query('DELETE game_insight:1');
+    const [after] = await engine.query<[{ count: number }[]]>(
+      'SELECT count() FROM game_insight GROUP ALL'
+    );
+    expect(after).toEqual([{ count: 4 }]);
+  });
+});

package/src/services/database/sqlite-devtools-queries.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect } from 'vitest';
+import { SqliteCacheEngine } from './sqlite-cache-engine';
+import { stubTransport } from './sqlite-transport.fixture';
+import { translateSurql } from './surql-translate';
+
+/**
+ * The statements the DevTools Database explorer emits against the LOCAL store.
+ * None of them come from `surql`, so they only ever exercised the SurrealDB
+ * engine: on SQLite the paging read threw "unsupported SurrealQL for
+ * translation: SELECT * FROM game_insight LIMIT 20 START 0", the table list came
+ * back empty (`INFO FOR DB` lowered to a noop) and row edit/delete never
+ * matched (they inline a literal record id).
+ */
+
+function makeLogger(): any {
+  const noop = () => {};
+  const l: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  l.child = () => l;
+  return l;
+}
+
+/** Records every exec/run SQL so the paging window can be asserted. */
+function recordingEngine(rows: Record<string, unknown[]> = {}) {
+  const sql: string[] = [];
+  const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, makeLogger());
+  stubTransport(engine, (type, payload: any) => {
+    if (type === 'open') return { persisted: true };
+    if (type === 'exec' || type === 'run') {
+      sql.push(payload.sql);
+      for (const [needle, out] of Object.entries(rows)) {
+        if (payload.sql.includes(needle)) return { rows: out };
+      }
+      return { rows: [] };
+    }
+    return {};
+  });
+  return { engine, sql };
+}
+
+describe('DevTools table paging (LIMIT/START)', () => {
+  it('translates the window instead of throwing', () => {
+    const { ops } = translateSurql('SELECT * FROM game_insight LIMIT 20 START 0', {});
+    expect(ops).toEqual([
+      {
+        kind: 'selectTable',
+        table: 'game_insight',
+        where: undefined,
+        orderBy: undefined,
+        select: undefined,
+        value: undefined,
+        limit: 20,
+        start: 0,
+      },
+    ]);
+  });
+
+  it('renders LIMIT/OFFSET in SQL, page 3 of 20', async () => {
+    const { engine, sql } = recordingEngine();
+    await engine.connect('anon');
+    await engine.query('SELECT * FROM game_insight LIMIT 20 START 40');
+    expect(sql.some((s) => /SELECT data FROM "game_insight" LIMIT 20 OFFSET 40$/.test(s))).toBe(
+      true
+    );
+  });
+
+  it('keeps WHERE and ORDER BY alongside the window', () => {
+    const { ops } = translateSurql(
+      'SELECT * FROM game WHERE done = true ORDER BY date desc LIMIT 10 START 30',
+      {}
+    );
+    expect(ops[0]).toMatchObject({
+      kind: 'selectTable',
+      table: 'game',
+      where: [{ field: 'done', op: '=', value: true }],
+      orderBy: [['date', 'desc']],
+      limit: 10,
+      start: 30,
+    });
+  });
+
+  it('leaves a LIMIT that is part of a string literal alone', () => {
+    const { ops } = translateSurql("SELECT * FROM game WHERE note = 'LIMIT 5'", {});
+    expect(ops[0]).toMatchObject({
+      kind: 'selectTable',
+      where: [{ field: 'note', op: '=', value: 'LIMIT 5' }],
+      limit: undefined,
+      start: undefined,
+    });
+  });
+
+  it('a START with no LIMIT still renders valid SQLite', async () => {
+    const { engine, sql } = recordingEngine();
+    await engine.connect('anon');
+    await engine.query('SELECT * FROM game START 5');
+    // SQLite has no bare OFFSET — `LIMIT -1` is its "everything" sentinel.
+    expect(sql.some((s) => s.endsWith('LIMIT -1 OFFSET 5'))).toBe(true);
+  });
+});
+
+describe('DevTools row count', () => {
+  it("answers `SELECT count() FROM t GROUP ALL` in SurrealDB's shape", async () => {
+    const { engine } = recordingEngine({ 'COUNT(*)': [{ n: 137 }] });
+    await engine.connect('anon');
+    const res = await engine.query<[{ count: number }[]]>(
+      'SELECT count() FROM game_insight GROUP ALL'
+    );
+    expect(res[0]).toEqual([{ count: 137 }]);
+  });
+
+  it('counts zero rows as 0, not undefined', async () => {
+    const { engine } = recordingEngine();
+    await engine.connect('anon');
+    const res = await engine.query<[{ count: number }[]]>('SELECT count() FROM empty GROUP ALL');
+    expect(res[0]).toEqual([{ count: 0 }]);
+  });
+});
+
+describe('DevTools table list', () => {
+  it('answers INFO FOR DB from sqlite_master, minus SQLite internals', async () => {
+    const { engine } = recordingEngine({
+      sqlite_master: [{ name: 'game' }, { name: '_00_query' }],
+    });
+    await engine.connect('anon');
+    const [info] = await engine.query<[{ tables: Record<string, string> }]>('INFO FOR DB');
+    expect(Object.keys(info.tables)).toEqual(['game', '_00_query']);
+  });
+});
+
+describe('DevTools row edit / delete (literal record ids)', () => {
+  it('UPDATE <table>:<id> MERGE $updates writes that row', async () => {
+    const { engine, sql } = recordingEngine();
+    await engine.connect('anon');
+    await engine.query('UPDATE game:abc MERGE $updates', { updates: { white: 'hikaru' } });
+    const write = sql.find((s) => s.startsWith('INSERT INTO "game"'));
+    expect(write).toBeDefined();
+    expect(write).toContain('json_patch');
+  });
+
+  it('DELETE <table>:<id> deletes one row, DELETE <table> still clears the table', () => {
+    expect(translateSurql('DELETE game:abc', {}).ops[0]).toEqual({
+      kind: 'delete',
+      id: 'game:abc',
+    });
+    expect(translateSurql('DELETE game', {}).ops[0]).toEqual({ kind: 'deleteAll', table: 'game' });
+  });
+
+  it('refuses a table-wide MERGE rather than writing a row named after the table', () => {
+    // `UPDATE game MERGE $x` means every row of `game` in SurrealQL. Unsupported
+    // here — and it must SAY so, not silently create `game:undefined`.
+    expect(() => translateSurql('UPDATE game MERGE $x', { x: {} })).toThrow(
+      /unsupported SurrealQL/
+    );
+  });
+});

package/src/services/database/surql-translate.ts

@@ -18,8 +18,29 @@ import { stableKey } from './relation-resolver';
 
 export type SqlOp =
   | { kind: 'getById'; id: unknown; select?: string[]; value?: string }
-  | { kind: 'selectByIds'; ids: unknown[]; select?: string[]; orderBy?: OrderBy; value?: string }
-  | { kind: 'selectTable'; table: string; where?: WhereNode[]; orderBy?: OrderBy; select?: string[]; value?: string }
+  | {
+      kind: 'selectByIds';
+      ids: unknown[];
+      select?: string[];
+      orderBy?: OrderBy;
+      value?: string;
+      limit?: number;
+      start?: number;
+    }
+  | {
+      kind: 'selectTable';
+      table: string;
+      where?: WhereNode[];
+      orderBy?: OrderBy;
+      select?: string[];
+      value?: string;
+      limit?: number;
+      start?: number;
+    }
+  /** `SELECT count() FROM t [WHERE …] GROUP ALL` — one `{ count }` row. */
+  | { kind: 'count'; table: string; where?: WhereNode[] }
+  /** `INFO FOR DB` — the table list, in SurrealDB's `{ tables: {…} }` shape. */
+  | { kind: 'infoForDb' }
   | { kind: 'upsert'; id: unknown; data: Row; mode: 'replace' | 'merge' }
   | { kind: 'updateSet'; id: unknown; sets: SetClause[]; returnNone: boolean }
   | { kind: 'delete'; id: unknown }
@@ -95,6 +116,12 @@ function translateStatement(stmt: string, vars: Record<string, unknown>): SqlOp
     return { kind: 'return', entries };
   }
 
+  // `INFO FOR DB` is the ONE INFO statement with a real answer here: the
+  // DevTools Database explorer enumerates tables with it. Answered from
+  // `sqlite_master` (see the engine) instead of being swallowed by the DDL
+  // noop below, which left the explorer with an empty table list.
+  if (/^INFO\s+FOR\s+DB(\s+STRUCTURE)?$/i.test(s)) return { kind: 'infoForDb' };
+
   // ---- schema / session DDL: no-ops on a schemaless engine --------------
   // SQLite creates tables lazily and has no namespaces/DB DDL, so DEFINE /
   // REMOVE / USE / INFO / RETURN statements are safely ignored.
@@ -110,11 +137,13 @@ function translateStatement(stmt: string, vars: Record<string, unknown>): SqlOp
     return { kind: 'upsert', id: rid(vars[m[1]]), data: asRow(vars[m[2]]), mode: 'replace' };
   }
 
+  // The `ONLY` variants come from `surql`; the bare `UPDATE <id> MERGE $x` form
+  // (with a LITERAL record id) is what the DevTools row editor emits.
   m =
-    /^UPSERT\s+ONLY\s+\$(\w+)\s+MERGE\s+\$(\w+)$/i.exec(s) ||
-    /^UPDATE\s+ONLY\s+\$(\w+)\s+MERGE\s+\$(\w+)$/i.exec(s);
+    idRe(String.raw`^UPSERT\s+ONLY\s+%ID%\s+MERGE\s+\$(\w+)$`).exec(s) ||
+    idRe(String.raw`^UPDATE\s+(?:ONLY\s+)?%ID%\s+MERGE\s+\$(\w+)$`).exec(s);
   if (m) {
-    return { kind: 'upsert', id: rid(vars[m[1]]), data: asRow(vars[m[2]]), mode: 'merge' };
+    return { kind: 'upsert', id: idOperand(m[1], vars), data: asRow(vars[m[2]]), mode: 'merge' };
   }
 
   // CREATE ONLY $id SET a = ..., b = ...  (createSet / createMutation)
@@ -126,32 +155,46 @@ function translateStatement(stmt: string, vars: Record<string, unknown>): SqlOp
   }
 
   // UPDATE $id SET a.b = $x, c = $y [RETURN NONE]
-  m = /^UPDATE\s+\$(\w+)\s+SET\s+(.+?)(\s+RETURN\s+NONE)?$/i.exec(s);
+  m = idRe(String.raw`^UPDATE\s+%ID%\s+SET\s+(.+?)(\s+RETURN\s+NONE)?$`).exec(s);
   if (m) {
     return {
       kind: 'updateSet',
-      id: rid(vars[m[1]]),
+      id: idOperand(m[1], vars),
       sets: parseSetClauses(m[2], vars),
       returnNone: !!m[3],
     };
   }
 
-  m = /^DELETE\s+\$(\w+)$/i.exec(s);
-  if (m) return { kind: 'delete', id: rid(vars[m[1]]) };
-
-  m = /^DELETE\s+([A-Za-z_]\w*)$/i.exec(s); // DELETE <table>
+  m = /^DELETE\s+([A-Za-z_]\w*)$/i.exec(s); // DELETE <table> (no `:` — a table)
   if (m) return { kind: 'deleteAll', table: m[1] };
 
+  // DELETE $id, and `DELETE <table>:<id>` from the DevTools row actions.
+  m = idRe(String.raw`^DELETE\s+%ID%$`).exec(s);
+  if (m) return { kind: 'delete', id: idOperand(m[1], vars) };
+
   // ---- reads ------------------------------------------------------------
-  // SELECT [VALUE] <proj> FROM ONLY $id
-  m = /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+ONLY\s+\$(\w+)$/i.exec(s);
+  // The paging tail (`LIMIT n [START m]`) is peeled off first so it can't be
+  // swallowed by the lazily-matched WHERE/ORDER BY groups below. Everything
+  // after this point sees a window-free statement.
+  const { head, limit, start } = peelWindow(s, vars);
+
+  // SELECT count() FROM <table> [WHERE ...] GROUP ALL — the row-count query the
+  // DevTools Database explorer pages with. GROUP ALL is required: without it
+  // SurrealDB counts per row, which is a different result this can't fake.
+  m = /^SELECT\s+count\(\)\s+FROM\s+([A-Za-z_]\w*)(?:\s+WHERE\s+(.+?))?\s+GROUP\s+ALL$/i.exec(head);
+  if (m) {
+    return { kind: 'count', table: m[1], where: m[2] ? parseWhere(m[2], vars) : undefined };
+  }
+
+  // SELECT [VALUE] <proj> FROM ONLY <id>
+  m = idRe(String.raw`^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+ONLY\s+%ID%$`).exec(head);
   if (m) {
     const value = m[1] ? m[2].trim() : undefined;
-    return { kind: 'getById', id: rid(vars[m[3]]), select: projFields(m[2], !!m[1]), value };
+    return { kind: 'getById', id: idOperand(m[3], vars), select: projFields(m[2], !!m[1]), value };
   }
 
   // SELECT [VALUE] <proj> FROM $arrayParam
-  m = /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+\$(\w+)$/i.exec(s);
+  m = /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+\$(\w+)$/i.exec(head);
   if (m) {
     const value = m[1] ? m[2].trim() : undefined;
     return {
@@ -159,13 +202,16 @@ function translateStatement(stmt: string, vars: Record<string, unknown>): SqlOp
       ids: (vars[m[3]] as unknown[]) ?? [],
       select: projFields(m[2], !!m[1]),
       value,
+      limit,
+      start,
     };
   }
 
   // SELECT <proj> FROM <table> [WHERE ...] [ORDER BY ...]
-  m = /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+([A-Za-z_]\w*)(?:\s+WHERE\s+(.+?))?(?:\s+ORDER\s+BY\s+(.+?))?$/i.exec(
-    s
-  );
+  m =
+    /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+([A-Za-z_]\w*)(?:\s+WHERE\s+(.+?))?(?:\s+ORDER\s+BY\s+(.+?))?$/i.exec(
+      head
+    );
   if (m) {
     return {
       kind: 'selectTable',
@@ -174,6 +220,8 @@ function translateStatement(stmt: string, vars: Record<string, unknown>): SqlOp
       orderBy: m[5] ? parseOrderBy(m[5]) : undefined,
       select: projFields(m[2], !!m[1]),
       value: m[1] ? m[2].trim() : undefined,
+      limit,
+      start,
     };
   }
 
@@ -182,6 +230,83 @@ function translateStatement(stmt: string, vars: Record<string, unknown>): SqlOp
 
 // ==================== clause parsers ====================
 
+/**
+ * Split a SELECT's trailing `LIMIT n [START m]` off its head.
+ *
+ * Peeled rather than folded into the SELECT regexes because those match WHERE
+ * and ORDER BY lazily: with the window left in place the WHERE group happily
+ * expands over `… LIMIT 20`, which is how `SELECT * FROM t LIMIT 20 START 0`
+ * ended up unmatched entirely.
+ *
+ * A tail sitting inside a string literal (`WHERE note = 'LIMIT 5'`) is left
+ * alone — an odd quote count in the head means the match is inside a string.
+ */
+function peelWindow(
+  stmt: string,
+  vars: Record<string, unknown>
+): { head: string; limit?: number; start?: number } {
+  let head = stmt;
+  let limit: number | undefined;
+  let start: number | undefined;
+
+  const peel = (re: RegExp): string | undefined => {
+    const m = re.exec(head);
+    if (!m) return undefined;
+    const before = head.slice(0, m.index);
+    if (countQuotes(before) % 2 !== 0) return undefined;
+    head = before;
+    return m[1];
+  };
+
+  // START is the outer token, so it comes off first.
+  const startTok = peel(/\s+START(?:\s+AT)?\s+(\$?\w+)\s*$/i);
+  const limitTok = peel(/\s+LIMIT(?:\s+BY)?\s+(\$?\w+)\s*$/i);
+  if (startTok !== undefined) start = numOperand(startTok, vars);
+  if (limitTok !== undefined) limit = numOperand(limitTok, vars);
+  return { head, limit, start };
+}
+
+function countQuotes(s: string): number {
+  let n = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "'" && s[i - 1] !== '\\') n++;
+  }
+  return n;
+}
+
+/** A `LIMIT`/`START` operand: a literal integer or a `$var` holding one. */
+function numOperand(token: string, vars: Record<string, unknown>): number | undefined {
+  const raw = token.startsWith('$') ? vars[token.slice(1)] : token;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/**
+ * A single-record operand: `$var` or a LITERAL `table:id`.
+ *
+ * A bare identifier deliberately does NOT match: in SurrealQL that is a table,
+ * and `UPDATE game MERGE $x` rewrites every row of `game` — a shape this
+ * vocabulary does not implement. Not matching means such a statement reaches
+ * the "unsupported SurrealQL" throw instead of quietly writing one row called
+ * `game`.
+ */
+const ID_TOKEN = String.raw`(\$\w+|[A-Za-z_]\w*:\S+)`;
+
+/** Build a statement regex, `%ID%` expanding to {@link ID_TOKEN}. */
+function idRe(pattern: string): RegExp {
+  return new RegExp(pattern.replace('%ID%', ID_TOKEN), 'i');
+}
+
+/**
+ * Resolve an {@link ID_TOKEN} match. Literals matter because the DevTools row
+ * editor inlines the id (`UPDATE game:abc MERGE $updates`) rather than binding
+ * it; `stableKey` treats that string and a `RecordId` identically downstream.
+ */
+function idOperand(token: string, vars: Record<string, unknown>): unknown {
+  const t = token.trim();
+  return t.startsWith('$') ? rid(vars[t.slice(1)]) : t;
+}
+
 function projFields(proj: string, isValue: boolean): string[] | undefined {
   const p = proj.trim();
   if (isValue) return undefined; // VALUE returns a scalar, no projection object