db-mcp 1.1.0 → 2.0.0

package/test-server/reset-database.ps1

@@ -110,8 +110,8 @@ if ($backupFiles) {
 }
 
 # Warn about any node processes that hold the database file open (e.g. MCP servers)
-$dbFullPath = (Resolve-Path $DatabasePath -ErrorAction SilentlyContinue)?.Path
-if (-not $dbFullPath) { $dbFullPath = $DatabasePath }
+$resolvePath = Resolve-Path $DatabasePath -ErrorAction SilentlyContinue
+$dbFullPath = if ($resolvePath) { $resolvePath.Path } else { $DatabasePath }
 $dbNameEscaped = [regex]::Escape(($dbFullPath -replace '\\', '/'))
 $dbNameEscapedBackslash = [regex]::Escape($dbFullPath)
 
@@ -122,7 +122,7 @@ if ($nodeProcesses) {
     foreach ($proc in $nodeProcesses) {
         Write-Warn "Node process PID $($proc.ProcessId) is using this database (likely an MCP server)"
     }
-    Write-Info "The database file will be replaced in-place — existing connections will pick up the new data."
+    Write-Info "The database file will be replaced in-place - existing connections will pick up the new data."
 }
 
 $filesToDelete = @(
@@ -181,7 +181,7 @@ if (-not $useCli) {
 } else {
     # Use Node.js with better-sqlite3 via inline script
     $dbMcpRoot = Split-Path -Parent $ScriptDir
-    $nodeScript = @"
+    $nodeScript = @'
 import Database from 'better-sqlite3';
 import { readFileSync } from 'fs';
 
@@ -198,7 +198,7 @@ try {
     console.error('ERROR:', err.message);
     process.exit(1);
 }
-"@
+'@
 
     # Write temp script to project directory so node can resolve dependencies
     $tempScript = Join-Path $dbMcpRoot ".create-test-db.js"
@@ -269,7 +269,7 @@ if (-not $SkipVerify) {
         "_mcp_migrations"
     )
 
-    $verifyScript = @"
+    $verifyScript = @'
 import Database from 'better-sqlite3';
 const db = new Database(process.argv[2], { readonly: true });
 
@@ -282,7 +282,7 @@ for (const table of tables) {
 }
 
 db.close();
-"@
+'@
 
     $dbMcpRoot = Split-Path -Parent $ScriptDir
     # Write temp script to project directory so node can resolve dependencies
@@ -329,35 +329,77 @@ db.close();
         Write-Host "`n  Artifact check:" -ForegroundColor Yellow
         $allTableNames = ($output | Where-Object { $_ -match "^TABLES:" }) -replace "^TABLES:", ""
         # Get ALL tables from sqlite_master, not just test_* ones
-        $allTablesScript = @"
+        $allTablesScript = @'
 import Database from 'better-sqlite3';
 const db = new Database(process.argv[2], { readonly: true });
 const all = db.prepare("SELECT name, type FROM sqlite_master WHERE type IN ('table','view') ORDER BY name").all();
 for (const t of all) console.log('ALL:' + t.name);
 db.close();
-"@
+'@
         $tempAllTables = Join-Path $dbMcpRoot ".check-artifacts.js"
         $allTablesScript | Out-File -FilePath $tempAllTables -Encoding utf8 -NoNewline
         $allOutput = node $tempAllTables $DatabasePath 2>&1
         Remove-Item $tempAllTables -Force -ErrorAction SilentlyContinue
 
+        $temporaryTables = @()
         $unexpectedTables = @()
+        
         foreach ($line in $allOutput | Where-Object { $_ -match "^ALL:" }) {
             $name = ($line -replace "^ALL:", "").Trim()
             $isExpected = $expectedTables.ContainsKey($name) -or $knownSystemTables -contains $name
             if (-not $isExpected) {
-                $unexpectedTables += $name
+                if ($name.StartsWith("stress_") -or $name.StartsWith("idx_stress_") -or $name.StartsWith("temp_") -or $name.StartsWith("idx_temp_")) {
+                    $temporaryTables += $name
+                } else {
+                    $unexpectedTables += $name
+                }
             }
         }
 
-        if ($unexpectedTables.Count -gt 0) {
-            Write-Warn "Found $($unexpectedTables.Count) unexpected table(s) — possible stale test artifacts:"
-            foreach ($ut in $unexpectedTables) {
-                Write-Host "    [stale] " -ForegroundColor Yellow -NoNewline
-                Write-Host $ut -ForegroundColor Gray
+        $allTablesToDrop = $temporaryTables + $unexpectedTables
+
+        if ($allTablesToDrop.Count -gt 0) {
+            if ($unexpectedTables.Count -gt 0) {
+                Write-Warn "Found $($unexpectedTables.Count) unexpected table(s) - stale test artifacts:"
+            }
+            if ($temporaryTables.Count -gt 0) {
+                Write-Info "Found $($temporaryTables.Count) temporary test table(s) (stress_*, temp_*) - cleaning up:"
+            }
+            
+            $dropScript = "import Database from 'better-sqlite3'; const db = new Database(process.argv[2]); db.pragma('foreign_keys = OFF'); "
+            
+            # First pass: drop main tables (non-shadow)
+            foreach ($ut in $allTablesToDrop) {
+                if ($ut -notmatch "_(data|idx|docsize|config|content|node|parent|rowid)$") {
+                    $prefix = if ($unexpectedTables -contains $ut) { "    [dropping] " } else { "    [cleaning temp] " }
+                    $color = if ($unexpectedTables -contains $ut) { "Yellow" } else { "Cyan" }
+                    Write-Host $prefix -ForegroundColor $color -NoNewline
+                    Write-Host $ut -ForegroundColor Gray
+                    $dropScript += "try { db.exec('DROP TABLE IF EXISTS `"$ut`"'); } catch(e) {} "
+                }
+            }
+            # Second pass: drop any remaining tables (shadow tables left behind)
+            foreach ($ut in $allTablesToDrop) {
+                if ($ut -match "_(data|idx|docsize|config|content|node|parent|rowid)$") {
+                    $prefix = if ($unexpectedTables -contains $ut) { "    [dropping shadow] " } else { "    [cleaning temp shadow] " }
+                    $color = if ($unexpectedTables -contains $ut) { "DarkYellow" } else { "DarkCyan" }
+                    Write-Host $prefix -ForegroundColor $color -NoNewline
+                    Write-Host $ut -ForegroundColor Gray
+                    $dropScript += "try { db.exec('DROP TABLE IF EXISTS `"$ut`"'); } catch(e) {} "
+                }
+            }
+            $dropScript += "db.pragma('foreign_keys = ON'); db.close();"
+            
+            $tempDrop = Join-Path $dbMcpRoot ".drop-artifacts.js"
+            $dropScript | Out-File -FilePath $tempDrop -Encoding utf8 -NoNewline
+            node $tempDrop $DatabasePath | Out-Null
+            Remove-Item $tempDrop -Force -ErrorAction SilentlyContinue
+            
+            if ($unexpectedTables.Count -gt 0) {
+                Write-Success "Cleaned up stale test artifacts"
+            } else {
+                Write-Success "Cleaned up temporary test tables"
             }
-            Write-Info "These may be R-Tree shadow tables, _mcp_migrations, temp_* leftovers, or FTS tables from testing."
-            Write-Info "Consider running a full reset to remove them."
         } else {
             Write-Success "No stale test artifacts found"
         }

package/test-server/scripts/README.md

@@ -0,0 +1,27 @@
+# db-mcp Test Scripts
+
+This directory contains integration test scripts that verify the functional parity and proper configuration of the `db-mcp` server.
+
+## Running the tests
+
+You must run these scripts from the project root using Node. Ensure you have built the project (`npm run build`) before running them so that the compiled `dist/cli.js` reflects your latest changes.
+
+```bash
+# Run from the project root:
+npm run build
+
+# 1. Test tool annotations and total tool count (Native Mode)
+node test-server/scripts/test-tool-annotations.mjs
+
+# 2. Test help resources and dynamic filtering
+node test-server/scripts/test-help-resources.mjs
+
+# 3. Test prompts registration and validation
+node test-server/scripts/test-prompts.mjs
+```
+
+## What they verify
+
+- **test-tool-annotations.mjs**: Spins up the server in Native Mode (`--sqlite-native`) and verifies that all 154 tools (151 Native + 3 built-in) are properly exposed, and that they all contain the required `openWorldHint: false` annotation for local database safety.
+- **test-help-resources.mjs**: Starts the server with multiple `--tool-filter` configurations to verify that the core instructions remain slim (within context limits) and that the correct `sqlite://help/{group}` resources are dynamically registered only when their respective tool groups are enabled.
+- **test-prompts.mjs**: Starts the server and verifies that all 10 MCP prompts are successfully registered via `prompts/list`, and performs functional execution checks on `prompts/get` handling required vs. optional arguments, payload structure correctness, and proper JSON-RPC error rendering.

package/test-server/{test-help-resources.mjs → scripts/test-help-resources.mjs}

@@ -8,7 +8,7 @@
  *
  * Usage:
  *   npm run build
- *   node test-server/test-help-resources.mjs
+ *   node test-server/scripts/test-help-resources.mjs
  */
 
 import { spawn } from "child_process";
@@ -142,11 +142,15 @@ async function main() {
   console.log(`  Has sqlite://help: ${coreHasBaseHelp ? "✅" : "❌"}`);
   if (!coreHasBaseHelp) allPassed = false;
 
-  const coreNoGroupHelp = coreHelpUris.length === 1;
+  const coreHasCoreHelp = coreHelpUris.includes("sqlite://help/core");
+  console.log(`  Has sqlite://help/core: ${coreHasCoreHelp ? "✅" : "❌"}`);
+  if (!coreHasCoreHelp) allPassed = false;
+
+  const coreNoOtherGroupHelp = coreHelpUris.length === 2;
   console.log(
-    `  No group-specific help: ${coreNoGroupHelp ? "✅" : "❌"} (count: ${coreHelpUris.length})`,
+    `  No other group-specific help: ${coreNoOtherGroupHelp ? "✅" : "❌"} (count: ${coreHelpUris.length})`,
   );
-  if (!coreNoGroupHelp) allPassed = false;
+  if (!coreNoOtherGroupHelp) allPassed = false;
 
   // ── Test 3: Stats Filter ──
   console.log("\n=== Test 3: Stats Filter (--tool-filter stats) ===\n");
@@ -183,6 +187,7 @@ async function main() {
 
   const expectedMulti = [
     "sqlite://help",
+    "sqlite://help/core",
     "sqlite://help/json",
     "sqlite://help/text",
     "sqlite://help/stats",
@@ -212,17 +217,19 @@ async function main() {
 
   const expectedFull = [
     "sqlite://help",
+    "sqlite://help/core",
     "sqlite://help/json",
     "sqlite://help/text",
     "sqlite://help/stats",
     "sqlite://help/vector",
     "sqlite://help/geo",
     "sqlite://help/admin",
+    "sqlite://help/transactions",
     "sqlite://help/introspection",
     "sqlite://help/migration",
   ];
   const fullHasAll = expectedFull.every((u) => fullHelpUris.includes(u));
-  console.log(`  Has all 9 help resources: ${fullHasAll ? "✅" : "❌"}`);
+  console.log(`  Has all 11 help resources: ${fullHasAll ? "✅" : "❌"}`);
   if (!fullHasAll) allPassed = false;
 
   // ── Summary ──

package/test-server/scripts/test-prompts.mjs

@@ -0,0 +1,251 @@
+import { spawn } from "child_process";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectDir = resolve(__dirname, "../..");
+
+const proc = spawn(
+  "node",
+  [
+    "dist/cli.js",
+    "--sqlite-native",
+    "./test-server/test.db",
+    "--log-level",
+    "error",
+  ],
+  {
+    cwd: projectDir,
+    stdio: ["pipe", "pipe", "pipe"],
+  },
+);
+
+let buffer = "";
+const pending = new Map(); // id -> resolve
+
+proc.stdout.on("data", (chunk) => {
+  buffer += chunk.toString();
+  const lines = buffer.split("\n");
+  buffer = lines.pop(); // keep incomplete
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const msg = JSON.parse(trimmed);
+      if (msg.id && pending.has(msg.id)) {
+        pending.get(msg.id)(msg);
+        pending.delete(msg.id);
+      }
+    } catch {}
+  }
+});
+proc.stderr.on("data", () => {});
+
+let nextId = 1;
+function rpc(method, params = {}) {
+  const id = nextId++;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(new Error(`Timeout: ${method}`));
+    }, 20000);
+    pending.set(id, (msg) => {
+      clearTimeout(timer);
+      resolve(msg);
+    });
+    proc.stdin.write(
+      JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n",
+    );
+  });
+}
+function notify(method, params = {}) {
+  proc.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n");
+}
+
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function main() {
+  // Initialize
+  await rpc("initialize", {
+    protocolVersion: "2025-03-26",
+    capabilities: {},
+    clientInfo: { name: "test-prompts", version: "1.0" },
+  });
+  await delay(500);
+  notify("notifications/initialized");
+  await delay(1000);
+
+  // List prompts
+  const listResp = await rpc("prompts/list", {});
+  const prompts = listResp.result?.prompts ?? [];
+  console.log(`\n=== PROMPTS LIST: ${prompts.length} prompts ===`);
+  for (const p of prompts) {
+    const args = (p.arguments || [])
+      .map((a) => `${a.name}${a.required ? "*" : ""}`)
+      .join(", ");
+    console.log(`  ${p.name}(${args})`);
+  }
+
+  const testCases = [
+    // No-argument prompts
+    { name: "sqlite_explain_schema", args: {}, expect: "" },
+    { name: "sqlite_optimization", args: {}, expect: "" },
+    { name: "sqlite_documentation", args: {}, expect: "" },
+
+    // Required-argument prompts
+    {
+      name: "sqlite_query_builder",
+      args: {
+        operation: "SELECT",
+        tables: "users",
+        description: "find active",
+      },
+      expect: "",
+    },
+    {
+      name: "sqlite_data_analysis",
+      args: { table: "users" },
+      expect: "",
+    },
+    {
+      name: "sqlite_migration",
+      args: { change: "add desc" },
+      expect: "",
+    },
+    {
+      name: "sqlite_debug_query",
+      args: { query: "SELECT * FROM test" },
+      expect: "",
+    },
+    {
+      name: "sqlite_summarize_table",
+      args: { table_name: "users" },
+      expect: "",
+    },
+    {
+      name: "sqlite_hybrid_search_workflow",
+      args: { use_case: "product_search" },
+      expect: "",
+    },
+    {
+      name: "sqlite_demo",
+      args: { topic: "sales" },
+      expect: "",
+    },
+
+    // Optional-argument prompts
+    {
+      name: "sqlite_data_analysis",
+      args: { table: "users", focus: "growth" },
+      expect: "",
+    },
+    {
+      name: "sqlite_migration",
+      args: { change: "add id", reversible: "true" },
+      expect: "",
+    },
+  ];
+
+  console.log(`\n=== TESTING ${testCases.length} PROMPT CALLS ===\n`);
+  let pass = 0,
+    fail = 0;
+
+  for (const tc of testCases) {
+    const argsStr = Object.keys(tc.args).length
+      ? JSON.stringify(tc.args)
+      : "(none)";
+    try {
+      const resp = await rpc("prompts/get", {
+        name: tc.name,
+        arguments: tc.args,
+      });
+      if (resp.error) {
+        console.log(
+          `FAIL ${tc.name}(${argsStr}): MCP error: ${JSON.stringify(resp.error)}`,
+        );
+        fail++;
+        continue;
+      }
+      const messages = resp.result?.messages;
+      const checks = [];
+      if (!Array.isArray(messages)) checks.push("messages not array");
+      else if (messages.length < 1) checks.push("messages empty");
+      else {
+        const m = messages[0];
+        if (m.role !== "user") checks.push(`role=${m.role}`);
+        if (!m.content) checks.push("no content");
+        else {
+          const c = m.content;
+          if (c.type !== "text") checks.push(`type=${c.type}`);
+          if (!c.text || c.text.length === 0) checks.push("text empty");
+          else if (
+            tc.expect &&
+            !c.text.toLowerCase().includes(tc.expect.toLowerCase())
+          ) {
+            checks.push(`missing '${tc.expect}' (len=${c.text.length})`);
+          }
+        }
+      }
+      if (checks.length === 0) {
+        const textLen = messages?.[0]?.content?.text?.length ?? 0;
+        console.log(
+          `PASS ${tc.name}(${argsStr}) — msgs:${messages.length}, textLen:${textLen}`,
+        );
+        pass++;
+      } else {
+        console.log(`FAIL ${tc.name}(${argsStr}): ${checks.join("; ")}`);
+        fail++;
+      }
+    } catch (err) {
+      console.log(`FAIL ${tc.name}(${argsStr}): ${err.message}`);
+      fail++;
+    }
+  }
+
+  // Error handling tests
+  try {
+    const resp = await rpc("prompts/get", {
+      name: "nonexistent-prompt",
+      arguments: {},
+    });
+    if (resp.error) {
+      console.log(
+        `PASS nonexistent-prompt: MCP error (code=${resp.error.code})`,
+      );
+      pass++;
+    } else {
+      console.log(`FAIL nonexistent-prompt: expected error`);
+      fail++;
+    }
+  } catch (err) {
+    console.log(`FAIL nonexistent-prompt: ${err.message}`);
+    fail++;
+  }
+
+  try {
+    const resp = await rpc("prompts/get", {
+      name: "sqlite_query_builder",
+      arguments: {},
+    });
+    if (resp.error) {
+      console.log(`PASS sqlite_query_builder(no args): error returned`);
+    } else {
+      console.log(`PASS sqlite_query_builder(no args): handled gracefully`);
+    }
+    pass++;
+  } catch (err) {
+    console.log(`FAIL sqlite_query_builder(no args): ${err.message}`);
+    fail++;
+  }
+
+  console.log(
+    `\n=== RESULTS: ${pass} pass, ${fail} fail (${pass + fail} total) ===`,
+  );
+  proc.kill();
+  process.exit(fail > 0 ? 1 : 0);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/test-server/{test-tool-annotations.mjs → scripts/test-tool-annotations.mjs}

@@ -7,7 +7,7 @@
  *
  * Usage:
  *   npm run build
- *   node test-server/test-tool-annotations.mjs
+ *   node test-server/scripts/test-tool-annotations.mjs
  */
 
 import { spawn } from "child_process";
@@ -19,7 +19,7 @@ const proc = spawn(
     "dist/cli.js",
     "--instruction-level",
     "essential",
-    "--sqlite",
+    "--sqlite-native",
     "./test-server/test.db",
     "--tool-filter",
     "+all",
@@ -90,12 +90,17 @@ proc.stdout.on("data", (chunk) => {
         }
 
         // Verification
+        const expectedCount = 154; // 151 Native tools + 3 built-in tools
+        const hasExpectedCount = tools.length === expectedCount;
         const allHaveAnnotations = missing === 0;
         const allAreFalse =
           openWorldTrue === 0 && openWorldFalse === tools.length;
 
         console.log(
-          `\n  All tools have annotations: ${allHaveAnnotations ? "✅" : "❌"}`,
+          `\n  Has exactly ${expectedCount} tools: ${hasExpectedCount ? "✅" : "❌"} (actual: ${tools.length})`,
+        );
+        console.log(
+          `  All tools have annotations: ${allHaveAnnotations ? "✅" : "❌"}`,
         );
         console.log(
           `  All openWorldHint=false: ${allAreFalse ? "✅" : "⚠️ (some are true)"}`,
@@ -103,7 +108,7 @@ proc.stdout.on("data", (chunk) => {
 
         finished = true;
         proc.kill();
-        process.exit(allHaveAnnotations ? 0 : 1);
+        process.exit(allHaveAnnotations && hasExpectedCount ? 0 : 1);
       }
     } catch {
       // Not complete JSON yet

package/test-server/test-advanced/README.md

@@ -0,0 +1,70 @@
+# db-mcp Advanced Stress Tests
+
+> **This document is optimized for AI agent consumption.** It provides context and execution rules for the advanced stress testing suite located in this directory.
+
+This directory contains the "Second-Pass" advanced tests for the `db-mcp` tool groups. These tests simulate complex, edge-case, and boundary interactions using exclusively **Code Mode** (`sqlite_execute_code`).
+
+## Pre-requisites
+
+1. Basic deterministic tool group checklists (located in `../test-tool-groups/*.md`) MUST be successfully passed before running these advanced tests.
+2. Code Mode basic tests (located in `../test-tool-groups-codemode/*.md`) MUST be successfully passed.
+3. The testing database MUST be freshly seeded via `Set-Location C:\Users\chris\Desktop\db-mcp\test-server; .\reset-database.ps1` to ensure deterministic results.
+
+## File Inventory
+
+| File                                      | Primary Focus | Key Validations                                                                           |
+| ----------------------------------------- | ------------- | ----------------------------------------------------------------------------------------- |
+| `test-codemode-advanced-core.md`          | Core          | Boundary values, empty states, state pollution, idempotency, error quality, payload sizes |
+| `test-codemode-advanced-json.md`          | JSON          | Deep nesting, merge conflicts (RFC 7396), type coercion, write safety                     |
+| `test-codemode-advanced-text.md`          | Text          | Regex edge cases, fuzzy/phonetic stress, FTS5 state integrity `[NATIVE ONLY]`             |
+| `test-codemode-advanced-stats.md`         | Stats         | Empty/single-row/NULL-heavy stats, extreme values, window functions `[NATIVE ONLY]`       |
+| `test-codemode-advanced-vector.md`        | Vector        | Empty tables, distance metrics, dimension mismatch, batch operations                      |
+| `test-codemode-advanced-admin.md`         | Admin         | View lifecycle, virtual tables, backup/restore, pragma edge cases                         |
+| `test-codemode-advanced-transactions.md`  | Transactions  | Abort recovery, savepoint stress, execute rollback `[NATIVE ONLY]`                        |
+| `test-codemode-advanced-geo.md`           | Geo           | Haversine boundary conditions, nearby edge cases, SpatiaLite `[NATIVE ONLY]`              |
+| `test-codemode-advanced-introspection.md` | Introspection | Graph analysis, schema snapshot, storage/index audit, query plan depth                    |
+| `test-codemode-advanced-migration.md`     | Migration     | Lifecycle, state pollution, SHA-256 dedup, error paths                                    |
+
+## Agent Execution Protocol
+
+1. **Strict Code Mode Only:** All advanced stress tests must be executed entirely via `sqlite_execute_code`. Direct tool calls are forbidden unless specifically instructed for baseline comparison.
+2. **Sequential Grouping:** Execute only **one markdown file at a time**. Report findings, fix errors, apply updates to the changelog, and commit before advancing to the next file.
+3. **Payload Optimization (Token Monitoring):** Monitor `metrics.tokenEstimate` on every response. If extremely large unbounded responses are produced, flag as 📦 **Payload Issue**.
+4. **Structured Error Adherence:** When testing boundary failure parameters, assert that the handler outputs a proper structured error (`{success: false, error: "..."}`) rather than leaking raw SQLite errors.
+5. **No Persistent Pollution:** After finishing a file, verify all `stress_*` tables/views/indexes are dropped. No test state should bleed into the next run.
+6. **Code Over Docs (When Standards Violated)**: If the code deviates from established standards (e.g., throwing raw MCP errors instead of Structured Errors, or failing Zod validation), **fix the handler code**. Do not modify documentation, prompts, or `gotchas.md` to accommodate buggy code.
+7. **Documentation Parity & Test Prompt Integrity**: Only update files in `src/constants/server-instructions` (or test prompts) if the code's behavior is mathematically/logically correct and intended, but the documentation is inaccurate, outdated, or lacking specificity. You SHOULD directly edit the markdown test files in this directory to fix factual errors, broken code blocks, or incorrect test assertions.
+8. **Testing Limits**: Do not run build or tests automatically (`npm run lint`, `npm run typecheck`, `npm run test:e2e`, `vitest`, or `playwright`). The user will execute them manually. When you reach the validate step, explicitly instruct the user to run the validations.
+
+### 9. WASM Mode Execution
+
+When testing against a **WASM backend** (`--sqlite` flag, sql.js adapter), follow these additional rules:
+
+#### Skip Rules
+
+- **`[NATIVE ONLY]` items**: Skip all categories and individual test items annotated with `[NATIVE ONLY]`.
+- **Transactions prompt**: Skip entirely — all 8 transaction tools are `[NATIVE ONLY]`.
+- **Window function items** (stats Category 4): Skip — 6 window tools are Native-only.
+- **SpatiaLite items** (geo Category 5): Skip — 7 SpatiaLite tools are Native-only.
+- **FTS5 items** (text Category 6): Skip — 5 FTS5 tools are Native-only.
+
+#### Graceful Degradation (Don't Skip — Validate Errors)
+
+Several admin tools are **registered in WASM mode but return structured errors**. Test these as **negative validation**:
+
+| Tool                                 | Expected WASM Behavior                         |
+| ------------------------------------ | ---------------------------------------------- |
+| `sqlite.admin.backup(...)`           | `{success: false, error: "...WASM mode"}`      |
+| `sqlite.admin.restore(...)`          | `{success: false, error: "...WASM mode"}`      |
+| `sqlite.admin.verifyBackup(...)`     | `{success: false, error: "...WASM mode"}`      |
+| `sqlite.admin.createCsvTable(...)`   | `{success: false}` — CSV extension unavailable |
+| `sqlite.admin.analyzeCsvSchema(...)` | `{success: false}` — CSV extension unavailable |
+| `sqlite.admin.createRtreeTable(...)` | `{success: false}` — R-Tree module unavailable |
+
+#### Adjusted Expectations
+
+| Item                                                 | Native Behavior             | WASM Behavior                    |
+| ---------------------------------------------------- | --------------------------- | -------------------------------- |
+| `sqlite.admin.dbstat({summarize: true})`             | Per-table storage breakdown | Counts-only (JS fallback)        |
+| `sqlite.admin.pragmaCompileOptions({filter: "FTS"})` | Matches FTS5                | Matches FTS3                     |
+| `test_articles_fts` in `listVirtualTables`           | Present and queryable       | May appear but FTS5 queries fail |