db-mcp 1.1.1 → 2.0.0

package/test-server/test-codemode/test-codemode-wasm-degradation.md

@@ -0,0 +1,394 @@
+# db-mcp Code Mode Testing: [wasm-degradation]
+
+> [!IMPORTANT]
+> **Do not track progress in this file.** Track your test progress, coverage matrix, and findings in your internal task tracking system (artifact). However, you SHOULD edit this file to fix any factual errors, broken code, or incorrect assertions in the test prompts.
+> If there is nothing to fix, don't update UNRELEASED.md.
+> We're currently testing WASM mode.
+
+> [!CAUTION]
+> **WASM ONLY** — This prompt must be run against a WASM backend (`--sqlite` flag). Running it against Native will produce false results since the tools being tested are expected to _fail_ in WASM but _succeed_ in Native.
+
+**Step 1:** Read `C:\Users\chris\Desktop\db-mcp\src\constants\server-instructions\gotchas.md` using `view_file`.
+
+**Step 2:** Validate that WASM-unavailable features degrade gracefully with structured errors, not crashes or raw MCP exceptions.
+
+**Step 3:** The agent should update C:\Users\chris\Desktop\db-mcp\UNRELEASED.md with any/all changes/fixes.
+
+## Purpose
+
+This prompt validates the **graceful degradation contract**: tools that are registered in WASM mode but rely on unavailable Native extensions must return structured `{success: false, error: "..."}` responses. It also validates that the Code Mode API bridge correctly reflects the reduced WASM tool surface.
+
+## Reporting Format
+
+- ❌ Fail: Tool crashes, returns raw MCP error, or doesn't return `{success: false}`
+- ⚠️ Issue: Error message is unclear or missing `wasmLimitation` hint
+- ✅ Pass: Returns `{success: false, error: "..."}` with helpful message
+
+## Test Database Schema
+
+Same seed database as all other prompts. Key difference: `test_articles_fts` (FTS5 virtual table) exists in `sqlite_master` because the seed was created with native SQLite, but FTS5 queries will fail in WASM.
+
+## Testing Requirements
+
+> [!CAUTION]
+> **Zero tolerance for raw MCP errors.** Every tool in this prompt is expected to return a structured error — not crash.
+
+1. **Batched scripting**: Bundle checks into `sqlite_execute_code` calls with `failures` array.
+2. **Structured error validation**: Every response must have `success: false` and a human-readable `error` string.
+3. **Token tracking**: Monitor `metrics.tokenEstimate`.
+4. **Coverage Matrix**: `| Category | Test | Result | Error Message Quality |`
+5. **Code Over Docs**: Fix the handler code if a tool returns a raw MCP error instead of a structured error.
+
+## Structured Error Response Pattern
+
+```json
+{ "success": false, "error": "Human-readable error message" }
+```
+
+| Type                 | What you see                                  | Verdict |
+| -------------------- | --------------------------------------------- | ------- |
+| **Handler error** ✅ | JSON object with `success` and `error` fields | Correct |
+| **MCP error** ❌     | Raw text, `isError: true`, no `success` field | Bug     |
+
+---
+
+## Phase 1: API Surface Verification (3 tests)
+
+> Verify the Code Mode bridge correctly reflects the reduced WASM tool surface.
+
+### 1.1 — Total method count
+
+```javascript
+const help = await sqlite.help();
+return { groups: help.groups, totalMethods: help.totalMethods };
+```
+
+Expected: `totalMethods` should be significantly less than 151 (the Native count). The exact WASM count depends on adapter registration but should be approximately 125.
+
+### 1.2 — Transactions group is empty
+
+```javascript
+const txHelp = await sqlite.transactions.help();
+return {
+  group: txHelp.group,
+  methodCount: txHelp.methods.length,
+  methods: txHelp.methods,
+};
+```
+
+Expected: `methodCount: 0` (or only `help` itself). No transaction methods should be available.
+
+### 1.3 — Window functions absent from stats
+
+```javascript
+const statsHelp = await sqlite.stats.help();
+const windowMethods = statsHelp.methods.filter((m) => m.startsWith("window"));
+return { totalStatsMethods: statsHelp.methods.length, windowMethods };
+```
+
+Expected: `windowMethods` is empty (`[]`). The 6 window tools should not appear.
+
+### 1.4 — SpatiaLite absent from geo
+
+```javascript
+const geoHelp = await sqlite.geo.help();
+const spatialMethods = geoHelp.methods.filter((m) =>
+  m.startsWith("spatialite"),
+);
+return {
+  totalGeoMethods: geoHelp.methods.length,
+  spatialMethods,
+  haversineMethods: geoHelp.methods,
+};
+```
+
+Expected: `spatialMethods` is empty. Only 4 Haversine methods remain: `distance`, `nearby`, `boundingBox`, `cluster`.
+
+### 1.5 — FTS5 absent from text
+
+```javascript
+const textHelp = await sqlite.text.help();
+const ftsMethods = textHelp.methods.filter((m) => m.startsWith("fts"));
+return { totalTextMethods: textHelp.methods.length, ftsMethods };
+```
+
+Expected: `ftsMethods` is empty. The 5 FTS5 tools should not appear.
+
+---
+
+## Phase 2: Backup/Restore/Verify — Graceful Errors (batched)
+
+> These 3 tools are registered in WASM but return structured errors because file system access is unavailable.
+
+```javascript
+const failures = [];
+
+// 2.1 — Backup
+const backup = await sqlite.admin.backup({
+  targetPath:
+    "C:\\Users\\chris\\Desktop\\db-mcp\\test-server\\test-wasm-backup.db",
+});
+if (backup.success !== false)
+  failures.push("backup: expected {success: false}");
+if (!backup.error || !backup.error.toLowerCase().includes("wasm")) {
+  failures.push(
+    "backup: error message should mention WASM — got: " + backup.error,
+  );
+}
+
+// 2.2 — Restore
+const restore = await sqlite.admin.restore({
+  sourcePath: "C:\\Users\\chris\\Desktop\\db-mcp\\test-server\\test.db",
+});
+if (restore.success !== false)
+  failures.push("restore: expected {success: false}");
+if (!restore.error || !restore.error.toLowerCase().includes("wasm")) {
+  failures.push(
+    "restore: error message should mention WASM — got: " + restore.error,
+  );
+}
+
+// 2.3 — Verify Backup
+const verify = await sqlite.admin.verifyBackup({
+  backupPath: "C:\\Users\\chris\\Desktop\\db-mcp\\test-server\\test.db",
+});
+if (verify.success !== false)
+  failures.push("verifyBackup: expected {success: false}");
+if (!verify.error || !verify.error.toLowerCase().includes("wasm")) {
+  failures.push(
+    "verifyBackup: error message should mention WASM — got: " + verify.error,
+  );
+}
+
+return { failures, success: failures.length === 0 };
+```
+
+---
+
+## Phase 3: CSV Tools — Graceful Errors (batched)
+
+> CSV virtual tables require the `csv` extension which is not available in WASM.
+
+```javascript
+const failures = [];
+
+// 3.1 — Create CSV Table
+const csvCreate = await sqlite.admin.createCsvTable({
+  tableName: "temp_wasm_csv",
+  filePath: "C:\\Users\\chris\\Desktop\\db-mcp\\test-server\\sample.csv",
+});
+if (csvCreate.success !== false)
+  failures.push("createCsvTable: expected {success: false}");
+
+// 3.2 — Analyze CSV Schema
+const csvAnalyze = await sqlite.admin.analyzeCsvSchema({
+  filePath: "C:\\Users\\chris\\Desktop\\db-mcp\\test-server\\sample.csv",
+});
+if (csvAnalyze.success !== false)
+  failures.push("analyzeCsvSchema: expected {success: false}");
+
+return { failures, success: failures.length === 0 };
+```
+
+---
+
+## Phase 4: R-Tree — Graceful Error
+
+> R-Tree spatial indexing requires a module not available in WASM's sql.js.
+
+```javascript
+const failures = [];
+
+const rtree = await sqlite.admin.createRtreeTable({
+  tableName: "temp_wasm_rtree",
+  dimensions: 2,
+});
+if (rtree.success !== false)
+  failures.push("createRtreeTable: expected {success: false}");
+
+return { failures, success: failures.length === 0 };
+```
+
+---
+
+## Phase 5: FTS5 — Phantom Table Behavior (batched)
+
+> `test_articles_fts` exists in sqlite_master (created by native seed) but FTS5 queries will fail in WASM.
+
+```javascript
+const failures = [];
+
+// 5.1 — Verify phantom table appears in sqlite_master
+const tables = await sqlite.core.readQuery(
+  "SELECT name, type FROM sqlite_master WHERE name = 'test_articles_fts'",
+);
+if (!tables.rows || tables.rows.length === 0) {
+  failures.push(
+    "test_articles_fts not found in sqlite_master — seed may not include FTS5",
+  );
+}
+
+// 5.2 — Attempting FTS5 query should fail gracefully
+const ftsQuery = await sqlite.core.readQuery({
+  query:
+    "SELECT * FROM test_articles_fts WHERE test_articles_fts MATCH 'SQLite' LIMIT 1",
+});
+// This should either return {success: false} or empty results — it should NOT crash
+if (ftsQuery.success === false) {
+  // Expected: structured error
+} else if (ftsQuery.rows && ftsQuery.rows.length > 0) {
+  failures.push(
+    "FTS5 query succeeded in WASM — unexpected (sql.js should not support FTS5)",
+  );
+}
+
+return { failures, success: failures.length === 0 };
+```
+
+---
+
+## Phase 6: dbstat WASM Fallback
+
+> In WASM, `dbstat` returns counts-only (JS fallback) rather than per-table storage breakdown.
+
+```javascript
+const failures = [];
+
+const dbstat = await sqlite.admin.dbstat({ summarize: true });
+// Should succeed but with limited data
+if (dbstat.success === false) {
+  failures.push("dbstat failed entirely in WASM — expected JS fallback");
+}
+
+return {
+  failures,
+  success: failures.length === 0,
+  dbstatResult: dbstat,
+};
+```
+
+---
+
+## Phase 7: PRAGMA Compile Options — FTS3 vs FTS5
+
+> WASM (sql.js) is compiled with FTS3, not FTS5.
+
+```javascript
+const failures = [];
+
+const options = await sqlite.admin.pragmaCompileOptions({});
+const optionList = options.compileOptions || options.options || [];
+
+const hasFTS5 = optionList.some((o) => o.toUpperCase().includes("FTS5"));
+const hasFTS3 = optionList.some((o) => o.toUpperCase().includes("FTS3"));
+
+if (hasFTS5) {
+  failures.push("WASM should NOT have FTS5 compile option");
+}
+
+return {
+  failures,
+  success: failures.length === 0,
+  hasFTS3,
+  hasFTS5,
+  optionCount: optionList.length,
+};
+```
+
+---
+
+## Phase 8: Zod Validation — WASM-Degraded Tools (batched)
+
+> Even though these tools degrade gracefully for domain reasons, their Zod validation must also work. Passing `{}` should return a structured error, not a raw MCP exception.
+
+```javascript
+const failures = [];
+
+const zodTests = [
+  { name: "backup", fn: () => sqlite.admin.backup({}) },
+  { name: "restore", fn: () => sqlite.admin.restore({}) },
+  { name: "verifyBackup", fn: () => sqlite.admin.verifyBackup({}) },
+  { name: "createCsvTable", fn: () => sqlite.admin.createCsvTable({}) },
+  { name: "analyzeCsvSchema", fn: () => sqlite.admin.analyzeCsvSchema({}) },
+  { name: "createRtreeTable", fn: () => sqlite.admin.createRtreeTable({}) },
+];
+
+for (const test of zodTests) {
+  const result = await test.fn();
+  if (result.success !== false) {
+    failures.push(`${test.name}({}): expected {success: false}`);
+  }
+}
+
+return { failures, success: failures.length === 0 };
+```
+
+---
+
+## Phase 9: Multi-Step WASM Workflow
+
+### 9.1 — WASM capability audit pipeline
+
+```javascript
+const failures = [];
+
+// Step 1: Get full API surface
+const help = await sqlite.help();
+const groups = help.groups;
+const totalMethods = help.totalMethods;
+
+// Step 2: Check each group's method count
+const groupSizes = {};
+for (const g of groups) {
+  const gHelp = await sqlite[g].help();
+  groupSizes[g] = gHelp.methods.length;
+}
+
+// Step 3: Verify transactions is empty
+if (groupSizes.transactions > 0) {
+  failures.push(
+    `transactions should have 0 methods, got ${groupSizes.transactions}`,
+  );
+}
+
+// Step 4: Verify no window methods in stats
+const statsHelp = await sqlite.stats.help();
+const windowMethods = statsHelp.methods.filter((m) => m.startsWith("window"));
+if (windowMethods.length > 0) {
+  failures.push(
+    `stats should have 0 window methods, got ${windowMethods.length}`,
+  );
+}
+
+// Step 5: Test a WASM-compatible tool works
+const count = await sqlite.core.count({ table: "test_products" });
+if (count.count !== 16)
+  failures.push(`expected 16 products, got ${count.count}`);
+
+// Step 6: Test a degraded tool fails gracefully
+const backup = await sqlite.admin.backup({ targetPath: "wasm-test.db" });
+if (backup.success !== false) failures.push("backup should fail in WASM");
+
+return {
+  failures,
+  success: failures.length === 0,
+  summary: {
+    totalGroups: groups.length,
+    totalMethods,
+    groupSizes,
+    wasmCompatible: true,
+  },
+};
+```
+
+---
+
+## Post-Test Procedures
+
+1. **No cleanup needed**: This prompt does not create any tables (all write operations are expected to fail)
+2. **Triage findings**: Create implementation plan if any tool returns raw MCP error instead of structured error
+3. **Scope of fixes**: Handler code only — fix WASM error handling paths
+4. **Validate**: Instruct the user to run the test suite (Vitest/Playwright), lint, and typecheck. Do NOT run them yourself.
+5. **Commit**: Stage and commit — do NOT push
+6. **Token audit**: Report most expensive block
+7. **Final summary**: After testing/re-testing

package/test-server/test-database.sql

@@ -2,7 +2,7 @@
 -- DB-MCP Test Database - Seed Data
 -- =============================================================================
 -- This file creates all test tables needed for comprehensive testing of
--- the db-mcp SQLite MCP server's 9 tool groups.
+-- the db-mcp SQLite MCP server's 10 tool groups.
 --
 -- Usage: sqlite3 test.db < test-database.sql
 -- =============================================================================
@@ -367,10 +367,46 @@ FROM (
 -- =============================================================================
 -- When the MCP server holds the DB open, the reset script overwrites in-place.
 -- Non-test tables from prior runs survive because only test_* tables are re-created.
+-- This section drops all known artifact patterns to prevent stale warnings.
 
+-- temp_* leftovers from ad-hoc testing
 DROP TABLE IF EXISTS temp_text_test;
+DROP TABLE IF EXISTS temp_series_test;
 DROP TABLE IF EXISTS "";
 
+-- stress_* leftovers from advanced stress tests
+DROP TABLE IF EXISTS stress_empty_table;
+DROP TABLE IF EXISTS stress_cycle_table;
+DROP TABLE IF EXISTS stress_json_test;
+DROP TABLE IF EXISTS stress_json_write;
+DROP TABLE IF EXISTS stress_json_inject;
+DROP TABLE IF EXISTS stress_sentiment_test;
+DROP TABLE IF EXISTS stress_stats_table;
+DROP TABLE IF EXISTS stress_vec_empty;
+DROP TABLE IF EXISTS stress_pipeline;
+DROP TABLE IF EXISTS stress_search;
+DROP TABLE IF EXISTS stress_migrated;
+DROP TABLE IF EXISTS stress_migration_data;
+DROP TABLE IF EXISTS stress_tx_test;
+DROP TABLE IF EXISTS stress_tx_fail;
+DROP TABLE IF EXISTS stress_tx_fail2;
+DROP TABLE IF EXISTS stress_tx_sp;
+DROP TABLE IF EXISTS stress_geo_spatial;
+DROP TABLE IF EXISTS stress_rtree_test;
+DROP TABLE IF EXISTS stress_csv;
+DROP VIEW IF EXISTS stress_view_orders;
+DROP INDEX IF EXISTS stress_idx_cycle;
+DROP INDEX IF EXISTS stress_idx_flag;
+
+-- E2E Playwright SpatiaLite R-Tree shadow tables
+DROP TABLE IF EXISTS idx__e2e_spatial_test_geom;
+DROP TABLE IF EXISTS idx__e2e_spatial_test_geom_node;
+DROP TABLE IF EXISTS idx__e2e_spatial_test_geom_parent;
+DROP TABLE IF EXISTS idx__e2e_spatial_test_geom_rowid;
+
+-- Migration tracking table
+DROP TABLE IF EXISTS _mcp_migrations;
+
 -- =============================================================================
 -- Summary: Test Tables Created
 -- =============================================================================

package/test-server/test-resources.md

@@ -1,19 +1,22 @@
 # db-mcp Resource Testing Plan
 
-Please test all db-mcp resources (8 data + up to 9 help) using the test database (test-server/test.db) and concisely report any issues.
+Please test all db-mcp resources (11 data + up to 9 help) using the test database (test-server/test.db) and concisely report any issues.
 
 ## Resources to Test
 
-| #   | Resource Name       | URI                          | Type      | Expected Data Source                       |
-| --- | ------------------- | ---------------------------- | --------- | ------------------------------------------ |
-| 1   | sqlite_schema       | sqlite://schema              | Static    | Full schema via adapter.getSchema()        |
-| 2   | sqlite_tables       | sqlite://tables              | Static    | Table list via adapter.listTables()        |
-| 3   | sqlite_table_schema | sqlite://table/{name}/schema | Templated | Specific table via adapter.describeTable() |
-| 4   | sqlite_indexes      | sqlite://indexes             | Static    | All indexes via adapter.getAllIndexes()    |
-| 5   | sqlite_views        | sqlite://views               | Static    | Views from sqlite_master                   |
-| 6   | sqlite_health       | sqlite://health              | Static    | Connection health via adapter.getHealth()  |
-| 7   | sqlite_meta         | sqlite://meta                | Static    | PRAGMA values + adapter info               |
-| 8   | sqlite_insights     | memo://insights              | Static    | In-memory insights memo                    |
+| #   | Resource Name          | URI                          | Type      | Expected Data Source                       |
+| --- | ---------------------- | ---------------------------- | --------- | ------------------------------------------ |
+| 1   | sqlite_schema          | sqlite://schema              | Static    | Full schema via adapter.getSchema()        |
+| 2   | sqlite_tables          | sqlite://tables              | Static    | Table list via adapter.listTables()        |
+| 3   | sqlite_table_schema    | sqlite://table/{name}/schema | Templated | Specific table via adapter.describeTable() |
+| 4   | sqlite_indexes         | sqlite://indexes             | Static    | All indexes via adapter.getAllIndexes()    |
+| 5   | sqlite_views           | sqlite://views               | Static    | Views from sqlite_master                   |
+| 6   | sqlite_health          | sqlite://health              | Static    | Connection health via adapter.getHealth()  |
+| 7   | sqlite_meta            | sqlite://meta                | Static    | PRAGMA values + adapter info               |
+| 8   | sqlite_compile_options | sqlite://compile_options     | Static    | SQLite compile-time build options          |
+| 9   | sqlite_pragma          | sqlite://pragma              | Static    | Runtime PRAGMA config snapshot             |
+| 10  | sqlite_insights        | memo://insights              | Static    | In-memory insights memo                    |
+| 11  | sqlite_audit           | sqlite://audit               | Static    | Audit log access (if enabled)              |
 
 ---
 
@@ -147,9 +150,9 @@ DROP VIEW IF EXISTS test_view_order_summary;
 **Test Sequence:**
 
 1. Read memo://insights — May be empty or have default content ("No business insights have been discovered yet.")
-2. Call sqlite_append_insight tool with a test insight (requires admin tools)
+2. Call sqlite_append_insight tool with a test insight `{"insight": "Test insight"}` (requires admin tools)
 3. Read memo://insights again — Should contain the new insight
-4. Verify timestamp, category, and finding text are present
+4. Verify the exact insight text is present
 
 **Expected Output:**
 
@@ -158,7 +161,31 @@ DROP VIEW IF EXISTS test_view_order_summary;
 
 ---
 
-### 9. Help Resources — On-Demand Reference Documentation
+### 9. sqlite_compile_options — Compile-Time Options
+
+**URI:** `sqlite://compile_options`  
+**Test:** Read the compile options resource.
+
+**Expected Output:**
+
+- JSON with an `options` array, `count`, and `highlights` array.
+- Should contain fundamental build options (e.g., `THREADSAFE`).
+
+---
+
+### 10. sqlite_pragma — Runtime Configuration Snapshot
+
+**URI:** `sqlite://pragma`  
+**Test:** Read the pragma configuration resource.
+
+**Expected Output:**
+
+- JSON with a `settings` object grouping configuration into categories (storage, performance, safety, behavior).
+- Each setting should include `value`, `category`, and `description`.
+
+---
+
+### 11. Help Resources — On-Demand Reference Documentation
 
 **Test A — sqlite://help (always registered):**
 
@@ -231,9 +258,9 @@ Use live MCP resource reads via the `read_resource` tool against the running sql
 
 | Metric                    | Value                                        |
 | ------------------------- | -------------------------------------------- |
-| Data resources to test    | 8                                            |
+| Data resources to test    | 10                                           |
 | Help resources to test    | 1 (sqlite://help) + up to 8 group-specific   |
-| Static resources          | 7                                            |
+| Static resources          | 9                                            |
 | Templated resources       | 1 (sqlite_table_schema with URI parameter)   |
 | Protocol validation tests | 2 (help resource content + tool annotations) |
 | Error cases to test       | 1 (nonexistent table in template)            |

package/test-server/test-tool-groups/README.md

@@ -0,0 +1,100 @@
+# db-mcp Standard Testing Suite
+
+**Directory Purpose**: This folder contains 10 self-contained, modular test prompts covering every tool group in `db-mcp`. Each file is a **complete, standalone prompt** — paste it directly into a conversation to test that tool group without needing any other files.
+
+## File Inventory
+
+| File                                | Group                     | Tools          | Notes                            |
+| ----------------------------------- | ------------------------- | -------------- | -------------------------------- |
+| `test-core-data.md`                 | core-data                 | 7              | Identical Native/WASM            |
+| `test-core-schema.md`               | core-schema               | 8 + Code Mode  | Identical Native/WASM            |
+| `test-json-read.md`                 | json-read                 | 18             | Identical Native/WASM            |
+| `test-json-write.md`                | json-write                | 7              | Identical Native/WASM            |
+| `test-text-basic.md`                | text-basic                | 11 + Code Mode | Identical Native/WASM            |
+| `test-text-advanced.md`             | text-advanced             | 9N/4W          | FTS5 tools `[NATIVE ONLY]`       |
+| `test-stats-basic.md`               | stats-basic               | 16 + Code Mode | Identical Native/WASM            |
+| `test-stats-advanced.md`            | stats-advanced            | 6N/0W          | Window functions `[NATIVE ONLY]` |
+| `test-vector-read.md`               | vector-read               | 7 + Code Mode  | Identical Native/WASM            |
+| `test-vector-write.md`              | vector-write              | 4              | Identical Native/WASM            |
+| `test-admin-core.md`                | admin-core                | 19 + Code Mode | Identical Native/WASM            |
+| `test-admin-extensions.md`          | admin-extensions          | 8              | CSV, series, rtree               |
+| `test-transactions.md`              | transactions              | 8 + Code Mode  | `[NATIVE ONLY]`                  |
+| `test-geo-haversine.md`             | geo-haversine             | 4 + Code Mode  | Identical Native/WASM            |
+| `test-geo-spatialite.md`            | geo-spatialite            | 7N/0W          | SpatiaLite `[NATIVE ONLY]`       |
+| `test-introspection-schema.md`      | introspection-schema      | 6              | Identical Native/WASM            |
+| `test-introspection-diagnostics.md` | introspection-diagnostics | 3 + Code Mode  | Identical Native/WASM            |
+| `test-migration.md`                 | migration                 | 6 + Code Mode  | Identical Native/WASM            |
+
+**Total**: 151 Native / 125 WASM tools across 10 groups + Code Mode.
+
+## Agent Instructions
+
+When tasked with running tests from this folder, adhere to the following protocol:
+
+### 1. Execution Strictness
+
+- **Direct Calls Exclusive**: Test tools ONLY using direct MCP tool calls (e.g., calling `mcp_sqlite_sqlite_read_query`). Do not use Code Mode (`sqlite_execute_code`) or scripts to batch the tests, except for checklist items explicitly testing Code Mode.
+- **No Scripted Loops**: Each happy and error path must be tested individually with a distinct tool call. This simulates exact client interaction behavior.
+
+### 2. Validation Targets
+
+- **Happy Path Consistency**: Validate that each tool outputs exactly what is expected from the explicit checklist items given in the prompt.
+- **Structured Error Path**: Ensure domain errors (e.g., nonexistent table) return an object `{"success": false, "error": "..."}`. A raw MCP error indicates a missing try/catch in the handler.
+- **Zod Exceptions**: Pass `{}` with missing required parameters or invalid types. The response must be a handler error, not a raw MCP `-32602` error.
+- **Payload Limits**: Watch for payload bloat and explicitly log it as a 📦 warning if it risks overflowing context window token limits.
+- **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.
+- **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.
+
+### 2.5 Testing Limits
+
+- **No Automated Execution**: 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.
+
+### 2.6 WASM Mode Execution
+
+When testing against a **WASM backend** (`sqlite-wasm` server entry, sql.js adapter), follow these additional rules:
+
+#### Skip Rules
+
+- **`[NATIVE ONLY]` items**: Skip all checklist items and Zod sweep items for tools annotated with `[NATIVE ONLY]`.
+- **Transactions prompt**: Skip entirely — all 8 transaction tools are `[NATIVE ONLY]`.
+- **Window function tools** (stats items 20-25): Skip — 6 window tools are Native-only.
+- **SpatiaLite tools** (geo items 8-14): Skip — 7 SpatiaLite tools are Native-only.
+- **FTS5 tools** (text items 18-22): Skip — 5 FTS5 tools are Native-only.
+- **Unregistered tools**: In WASM mode, `[NATIVE ONLY]` tools are not registered at all. Direct MCP calls to them will fail with an "unknown tool" error — this is expected, not a bug.
+
+#### 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_backup`             | `{success: false, error: "...WASM mode"}`      |
+| `sqlite_restore`            | `{success: false, error: "...WASM mode"}`      |
+| `sqlite_verify_backup`      | `{success: false, error: "...WASM mode"}`      |
+| `sqlite_create_csv_table`   | `{success: false}` — CSV extension unavailable |
+| `sqlite_analyze_csv_schema` | `{success: false}` — CSV extension unavailable |
+| `sqlite_create_rtree_table` | `{success: false}` — R-Tree module unavailable |
+
+#### Adjusted Expectations
+
+| Item                                                | Native Behavior             | WASM Behavior                    |
+| --------------------------------------------------- | --------------------------- | -------------------------------- |
+| `sqlite_dbstat({summarize: true})`                  | Per-table storage breakdown | Counts-only (JS fallback)        |
+| `sqlite_pragma_compile_options({filter: "FTS"})`    | Matches FTS5                | Matches FTS3                     |
+| `test_articles_fts` in `sqlite_list_virtual_tables` | Present and queryable       | May appear but FTS5 queries fail |
+
+### 3. Tracking Metrics & Progress
+
+- **Strict Coverage Matrix**: Maintain a table tracking your progress in `tmp/task.md` logging completion for:
+  `| Tool | Direct Call (Happy Path) | Domain Error | Zod Empty Param | Alias Acceptance |`
+  Never proceed to the final step until every tool in a given group is fully checked off.
+
+### 4. Cleanup & Scope
+
+- Direct write tests should operate on temporary tables or objects prefixed with `temp_`.
+- When completed, explicitly drop all `temp_` artifacts.
+- Update `code-map.md`, handlers, and instructions if bugs are uncovered, then update the Changelog with fixes before summarizing your work.
+
+## Execution
+
+Begin with any requested group prompt from this folder (e.g., `test-admin.md`), and execute the deterministic checklist line-by-line using direct tool calls only.