db-mcp 1.1.0 → 2.0.0

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

@@ -0,0 +1,121 @@
+# db-mcp Code Mode Testing Suite
+
+**Directory Purpose**: This folder contains 12 self-contained, modular test prompts covering every tool group in `db-mcp`. These prompts are strictly designed for **Code Mode (`sqlite_execute_code`) validation only**.
+
+## Agent Instructions
+
+When tasked with running tests from this folder, adhere to the following optimized protocol:
+
+### 1. Execution Strictness
+
+- **Code Mode Exclusive**: Test tools ONLY using `sqlite_execute_code`. Do not use direct tool calls or the terminal unless specifically comparing behavior.
+- **Batching**: Group multiple method calls into a single JavaScript code execution script to save context window tokens and improve speed.
+- **Failures Array Format**: Design your JS script to capture both expected outputs and caught errors, appending assertions to a `failures` array, and returning `{ failures, success: failures.length === 0 }`.
+
+### 2. Validation Targets
+
+- **Happy Path Parity**: Validate that Code Mode handler execution matches expected database behavior.
+- **Structured Error Path**: Ensure domain errors (e.g., nonexistent table) return an object `{"success": false, "error": "..."}` instead of crashing or leaking raw MCP errors.
+- **Zod Resilience**: Pass `{}` with missing required parameters or invalid types. Verify that Zod errors are properly caught and formatted.
+- **Payload Limits**: If a response payload is excessively large, report it as a 📦 Payload issue.
+- **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.
+
+### 3. Tracking Progress
+
+You must maintain a **Strict Coverage Matrix** in `tmp/task.md` logging completion for:
+`| Tool | Code Mode (Happy Path) | Code Mode (Domain Error/Zod Error) |`
+Never proceed to the final step until every tool in a given group has both columns marked as ✅.
+
+### 4. Token Tracking
+
+Monitor `metrics.tokenEstimate` on every Code Mode response. Report the single most expensive execution block in your final summary.
+
+### 5. Cleanup
+
+- Any write tests should operate on temporary tables or objects prefixed with `temp_`.
+- **Active Connection Lock**: The MCP server holds a lock on the SQLite database, preventing the reset script from replacing the file outright. The reset script only seeds default tables, it does not drop unknown `temp_` tables.
+- **Mandatory Code Mode Cleanup**: Your final step MUST be a Code Mode script that explicitly drops ALL `temp_*` tables (e.g., `sqlite.core.dropTable({tableName: '...', force: true})`) BEFORE you run the reset script.
+
+### 6. 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.
+
+### 7. 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 phases and individual test items annotated with `[NATIVE ONLY]`. This annotation already exists in each prompt.
+- **Transactions prompt**: Skip entirely — the transactions group has 0 WASM tools. `sqlite.transactions.help()` returns an empty methods list.
+- **Window function items** (stats prompt Phases 3, 6): Skip — 6 window tools are Native-only.
+- **SpatiaLite items** (geo prompt Phase 2): Skip — 7 SpatiaLite tools are Native-only.
+- **FTS5 items** (text prompt Phase 2): 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** instead of succeeding. Test these as **negative validation** — verify the structured error response, don't skip them:
+
+| 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()`                           | Includes `ENABLE_FTS5`                    | Shows `ENABLE_FTS3` instead                                           |
+| `sqlite.admin.pragmaCompileOptions({filter: "FTS"})`            | Matches FTS5                              | Matches FTS3                                                          |
+| `sqlite.core.listTables()` / `sqlite.admin.listVirtualTables()` | `test_articles_fts` present and queryable | `test_articles_fts` may appear in sqlite_master but FTS5 queries fail |
+| `sqlite.help()`                                                 | `totalMethods` reflects 151 tools         | `totalMethods` reflects 125 tools                                     |
+| Phase 2.1 (sandbox prompt) top-level help                       | 10 groups listed                          | `transactions` group shows 0 methods                                  |
+
+#### WASM-Specific Degradation Prompt
+
+After completing the applicable prompts above, run `test-codemode-wasm-degradation.md` — a dedicated prompt that validates graceful degradation patterns unique to WASM mode. This prompt should **only** be run against a WASM backend.
+
+## File Inventory
+
+| File                                | Group         | Tools                                                                    |
+| ----------------------------------- | ------------- | ------------------------------------------------------------------------ |
+| `test-codemode-sandbox.md`          | sandbox       | Sandbox basics, API discoverability, security, readonly, state isolation |
+| `test-codemode-core.md`             | core          | 14                                                                       |
+| `test-codemode-json.md`             | json          | 24                                                                       |
+| `test-codemode-text.md`             | text          | 19N/14W                                                                  |
+| `test-codemode-stats.md`            | stats         | 22N/16W                                                                  |
+| `test-codemode-vector.md`           | vector        | 11                                                                       |
+| `test-codemode-admin.md`            | admin         | 26                                                                       |
+| `test-codemode-transactions.md`     | transactions  | 8 `[NATIVE ONLY]`                                                        |
+| `test-codemode-geo.md`              | geo           | 11N/4W                                                                   |
+| `test-codemode-introspection.md`    | introspection | 9                                                                        |
+| `test-codemode-migration.md`        | migration     | 6                                                                        |
+| `test-codemode-wasm-degradation.md` | cross-group   | WASM-only graceful degradation                                           |
+
+**Total**: 151 Native / 125 WASM tools across 10 groups + 1 sandbox prompt + 1 WASM degradation prompt.
+
+## Recommended Execution Order
+
+1. **`test-codemode-sandbox.md`** — Run first. Validates the sandbox execution environment (return values, API discoverability, security blocks, readonly mode, state isolation). If this fails, subsequent prompts will not work correctly.
+2. **`test-codemode-core.md`** — Run second. Tests the core tool group (read/write queries, tables, indexes, parameter binding).
+3. **Remaining group prompts** — Run in any order: `json`, `text`, `stats`, `vector`, `admin`, `transactions`, `geo`, `introspection`, `migration`.
+4. **`test-codemode-wasm-degradation.md`** — Run last, WASM only. Validates graceful degradation patterns.
+
+## Tool Groups Available
+
+1. `core`
+2. `json`
+3. `text`
+4. `stats`
+5. `vector`
+6. `admin`
+7. `transactions`
+8. `geo`
+9. `introspection`
+10. `migration`

package/test-server/test-codemode/test-codemode-admin.md

@@ -0,0 +1,223 @@
+# db-mcp Code Mode Testing: [admin]
+
+> [!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 Native mode.
+
+**Step 1:** Read `C:\Users\chris\Desktop\db-mcp\src\constants\server-instructions\gotchas.md` using `view_file`.
+
+**Step 2:** Conduct an exhaustive test of the **admin** tool group using ONLY `sqlite_execute_code`. Do not use direct tool calls or terminal.
+
+**Step 3:** The agent should update C:\Users\chris\Desktop\db-mcp\UNRELEASED.md with any/all changes/fixes.
+
+## WASM Mode
+
+> When testing against a **WASM backend** (`--sqlite` / sql.js), apply these adjustments:
+
+- **Phase 1**: Item 2 (`pragmaCompileOptions`) — WASM shows `FTS3` instead of `FTS5`. Item 3 (filter `"FTS"`) — matches FTS3. Item 9 (`dbstat`) — WASM returns counts-only (no per-table storage).
+- **Phase 3**: Item 13 (`listVirtualTables`) — `test_articles_fts` may appear but is not queryable. Item 16 (`createRtreeTable`) — returns `{success: false}` (R-Tree unavailable in WASM). Treat as **negative validation**.
+- **Phase 4** (Backup/Restore): All 3 items (19-21) return `{success: false, error: "...WASM mode"}`. Treat as **negative validation** — verify the structured error, do not skip.
+- **Phase 6** (CSV): Both items (25-26) return `{success: false}` (CSV extension unavailable in WASM). Treat as **negative validation**.
+- All other phases are WASM-compatible.
+
+## Reporting Format
+
+- ❌ Fail: Tool errors or produces incorrect results
+- ⚠️ Issue: Unexpected behavior or improvement opportunity
+- 📦 Payload: Unnecessarily large response — monitor `metrics.tokenEstimate`.
+
+## Test Database Schema
+
+| Table             | Rows | Key Columns                                            |
+| ----------------- | ---- | ------------------------------------------------------ |
+| test_products     | 16   | id, name, price, category, created_at                  |
+| test_orders       | 20   | id, product_id (FK→test_products), total_price, status |
+| test_articles     | 8    | id, title, body, author, category                      |
+| test_articles_fts | —    | FTS5 virtual table (title, body columns)               |
+
+> **CSV testing**: Use `C:\Users\chris\Desktop\db-mcp\test-server\sample.csv` (columns: id, name, category, price, quantity, created_at). **Absolute paths only** — relative paths resolve from IDE CWD.
+
+## Testing Requirements
+
+> [!CAUTION]
+> **Zero tolerance for raw MCP errors.** Report as ❌.
+
+1. **Batched scripting**: Bundle checks with `failures` array.
+2. **Error path testing**: Every tool with `{}` (Zod) and domain error.
+3. **Token tracking**: Monitor `metrics.tokenEstimate`.
+4. **Coverage Matrix**: `| Tool | Happy Path | Domain Error | Zod Error |`
+5. **Deterministic checklist first**.
+6. **Code Over Docs**: Fix the handler code if standards (Structured Errors/Zod) are violated. Do NOT change docs/prompts to accommodate broken code.
+
+## Structured Error Response Pattern
+
+Handler error ✅ = JSON with `success` + `error`. MCP error ❌ = raw text, `isError: true`.
+
+## Cleanup
+
+- Temporary tables: `temp_*` prefix. Views: `temp_view_*` prefix. Drop at end of script.
+
+---
+
+## Phase 1: Pragma & Inspection — Happy Paths (batched)
+
+1. `sqlite.admin.pragmaDatabaseList()` → verify database path matches `test.db`
+2. `sqlite.admin.pragmaCompileOptions()` → list of compile options
+3. `sqlite.admin.pragmaCompileOptions({filter: "FTS"})` → filtered to FTS options
+4. `sqlite.admin.pragmaSettings({pragma: "journal_mode"})` → `{value: "wal"}`
+5. `sqlite.admin.pragmaTableInfo({table: "test_products"})` → columns: id, name, description, price, category, created_at
+6. `sqlite.admin.indexStats()` → index statistics
+7. `sqlite.admin.integrityCheck()` → `ok`
+8. `sqlite.admin.analyze()` → success
+9. `sqlite.admin.dbstat({summarize: true})` → per-table storage
+
+---
+
+## Phase 2: View Management (batched)
+
+10. `sqlite.admin.createView({viewName: "temp_view_orders", selectQuery: "SELECT product_id, COUNT(*) as order_count, SUM(total_price) as revenue FROM test_orders GROUP BY product_id"})` → success
+11. `sqlite.admin.listViews()` → `temp_view_orders` present
+12. `sqlite.admin.dropView({viewName: "temp_view_orders"})` → success
+
+---
+
+## Phase 3: Virtual Tables (batched)
+
+13. `sqlite.admin.listVirtualTables()` → `test_articles_fts` present
+14. `sqlite.admin.virtualTableInfo({tableName: "test_articles_fts"})` → module and column info
+15. `sqlite.admin.generateSeries({start: 1, stop: 5, step: 1})` → 5 values
+16. `sqlite.admin.createRtreeTable({tableName: "temp_cm_rtree", dimensions: 2})` → R-Tree created
+17. `sqlite.admin.createSeriesTable({tableName: "temp_cm_series", start: 1, stop: 10})` → regular table with 10 rows
+18. Cleanup: drop `temp_cm_rtree` (virtual) and `temp_cm_series` (regular)
+
+---
+
+## Phase 4: Backup/Restore (batched)
+
+> Use absolute path for backup: `C:\Users\chris\Desktop\db-mcp\test-server\test-backup.db`
+
+19. `sqlite.admin.backup({targetPath: "C:\\Users\\chris\\Desktop\\db-mcp\\test-server\\test-backup.db"})` → success
+20. `sqlite.admin.verifyBackup({backupPath: "C:\\Users\\chris\\Desktop\\db-mcp\\test-server\\test-backup.db"})` → integrity verified
+21. `sqlite.admin.restore({sourcePath: "C:\\Users\\chris\\Desktop\\db-mcp\\test-server\\test-backup.db"})` → restore success
+
+---
+
+## Phase 5: Optimization (batched)
+
+22. `sqlite.admin.vacuum()` → success
+23. `sqlite.admin.optimize()` → optimization details
+24. `sqlite.admin.pragmaOptimize()` → distinct from `optimize` — runs `PRAGMA optimize`
+
+---
+
+## Phase 6: CSV (batched)
+
+> Use absolute path: `C:\Users\chris\Desktop\db-mcp\test-server\sample.csv`
+
+25. `sqlite.admin.analyzeCsvSchema({filePath: "C:\\Users\\chris\\Desktop\\db-mcp\\test-server\\sample.csv"})` → inferred column types
+26. `sqlite.admin.createCsvTable({tableName: "temp_cm_csv", filePath: "C:\\Users\\chris\\Desktop\\db-mcp\\test-server\\sample.csv"})` → virtual table
+27. Cleanup: drop `temp_cm_csv` (virtual)
+
+---
+
+## Phase 7: Insights
+
+28. `sqlite.admin.appendInsight({insight: "Test insight from codemode"})` → success
+
+---
+
+## Phase 8: Admin Domain Errors (batched)
+
+🔴 29. `sqlite.admin.pragmaTableInfo({table: "nonexistent_xyz"})` → report behavior
+🔴 30. `sqlite.admin.virtualTableInfo({tableName: "nonexistent_xyz"})` → `{success: false}`
+🔴 31. `sqlite.admin.verifyBackup({backupPath: "nonexistent_file.db"})` → `{success: false}`
+🔴 32. `sqlite.admin.dropView({viewName: "nonexistent_xyz", ifExists: false})` → `{success: false}`
+
+---
+
+## Phase 9: Admin Zod Validation (batched)
+
+🔴 33. `sqlite.admin.backup({})` → `{success: false}`
+🔴 34. `sqlite.admin.restore({})` → `{success: false}`
+🔴 35. `sqlite.admin.verifyBackup({})` → `{success: false}`
+🔴 36. `sqlite.admin.pragmaTableInfo({})` → `{success: false}`
+🔴 37. `sqlite.admin.pragmaSettings({})` → `{success: false}`
+🔴 38. `sqlite.admin.appendInsight({})` → `{success: false}`
+🔴 39. `sqlite.admin.createView({})` → `{success: false}`
+🔴 40. `sqlite.admin.dropView({})` → `{success: false}`
+🔴 41. `sqlite.admin.virtualTableInfo({})` → `{success: false}`
+🔴 42. `sqlite.admin.dropVirtualTable({})` → `{success: false}`
+🔴 43. `sqlite.admin.createCsvTable({})` → `{success: false}`
+🔴 44. `sqlite.admin.analyzeCsvSchema({})` → `{success: false}`
+🔴 45. `sqlite.admin.createRtreeTable({})` → `{success: false}`
+🔴 46. `sqlite.admin.createSeriesTable({})` → `{success: false}`
+🔴 47. `sqlite.admin.generateSeries({})` → `{success: false}`
+🔴 48. `sqlite.admin.dbstat({})` → `{success: false}` or success (no required params)
+
+---
+
+## Phase 9.5: Gotcha Edge Cases (batched)
+
+49. `sqlite.admin.generateSeries({start: 1, stop: 10, step: 2})` → 5 values: 1, 3, 5, 7, 9 (non-default step value)
+50. `sqlite.admin.pragmaSettings({pragma: "cache_size", value: "2000"})` → set cache_size, then `sqlite.admin.pragmaSettings({pragma: "cache_size"})` → verify read-back returns the set value
+51. `sqlite.admin.createSeriesTable({tableName: "temp_cm_series_regular", start: 1, stop: 5})` → creates a REGULAR table (not virtual). Verify with `sqlite.core.describeTable({table: "temp_cm_series_regular"})` → success, then `sqlite.core.dropTable({table: "temp_cm_series_regular"})` → success (gotcha #15: use `dropTable`, not `dropVirtualTable`)
+52. `sqlite.admin.dropVirtualTable({tableName: "test_products"})` → `{success: false}` — test_products is a regular table, not a virtual table (domain error)
+
+---
+
+## Phase 10: Multi-Step Workflow
+
+### 10.1 — Database health check pipeline
+
+```javascript
+const failures = [];
+const integrity = await sqlite.admin.integrityCheck();
+if (integrity.integrity !== "ok") failures.push("integrity check failed");
+
+const journal = await sqlite.admin.pragmaSettings({ pragma: "journal_mode" });
+if (journal.value !== "wal")
+  failures.push(`expected WAL, got ${journal.value}`);
+
+const storage = await sqlite.admin.dbstat({ summarize: true });
+const views = await sqlite.admin.listViews();
+const vtables = await sqlite.admin.listVirtualTables();
+
+return {
+  failures,
+  success: failures.length === 0,
+  summary: {
+    integrity: "ok",
+    journalMode: journal.value,
+    viewCount: views?.views?.length,
+    virtualTableCount: vtables?.virtualTables?.length,
+  },
+};
+```
+
+### 10.2 — View lifecycle
+
+```javascript
+const failures = [];
+await sqlite.admin.createView({
+  viewName: "temp_view_cm_test",
+  selectQuery: "SELECT COUNT(*) as n FROM test_products",
+});
+const views = await sqlite.admin.listViews();
+const found = views.views?.some((v) => v.name === "temp_view_cm_test");
+if (!found) failures.push("view not found after creation");
+await sqlite.admin.dropView({ viewName: "temp_view_cm_test" });
+return { failures, success: failures.length === 0 };
+```
+
+---
+
+## Post-Test Procedures
+
+1. **Cleanup**: Drop `temp_*` tables, views, and virtual tables
+2. **Triage findings**: Create implementation plan if issues found
+3. **Scope of fixes**: Handler code, server-instructions, this prompt
+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-codemode/test-codemode-core.md

@@ -0,0 +1,286 @@
+# db-mcp Code Mode Testing: [core]
+
+> [!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 Native mode.
+
+**Step 1:** Read `C:\Users\chris\Desktop\db-mcp\src\constants\server-instructions\gotchas.md` using `view_file`.
+
+**Step 2:** Conduct an exhaustive test of the **core** tool group using ONLY `sqlite_execute_code`. Do not use direct tool calls or terminal.
+
+**Step 3:** The agent should update C:\Users\chris\Desktop\db-mcp\UNRELEASED.md with any/all changes/fixes.
+
+## WASM Mode
+
+> When testing against a **WASM backend** (`--sqlite` / sql.js): All 14 core tools are fully WASM-compatible. No phases to skip or adjust.
+
+## Reporting Format
+
+- ❌ Fail: Tool errors or produces incorrect results (include error message)
+- ⚠️ Issue: Unexpected behavior or improvement opportunity
+- 📦 Payload: Unnecessarily large response — **blocking, equally important as ❌ bugs**. You **MUST** monitor `metrics.tokenEstimate` for every operation. Report the response size in tokens/KB and suggest optimization.
+
+## Test Database Schema
+
+| Table             | Rows | Key Columns                                                                                 |
+| ----------------- | ---- | ------------------------------------------------------------------------------------------- |
+| test_products     | 16   | id, name, description, price (REAL), category (TEXT lowercase), created_at                  |
+| test_orders       | 20   | id, product_id (FK→test_products), customer_name, quantity, total_price, order_date, status |
+| test_jsonb_docs   | 6    | id, doc (JSON), metadata (JSON), tags (JSON array), created_at                              |
+| test_articles     | 8    | id, title, body, author, category, published_at                                             |
+| test_users        | 9    | id, username, email, phone, bio, created_at                                                 |
+| test_measurements | 200  | id, sensor_id (INT 1-5), temperature, humidity, pressure, measured_at                       |
+| test_embeddings   | 20   | id, content, category, embedding (8-dim JSON array)                                         |
+| test_locations    | 15   | id, name, city, latitude, longitude, type                                                   |
+| test_categories   | 17   | id, name, path, level                                                                       |
+| test_events       | 100  | id, event_type, user_id (INT), payload (JSON), event_date                                   |
+
+> **Note:** `sensor_id` is INTEGER (1-5). String values use **lowercase**. Do **not** pass `readonly: true` unless specifically testing readonly filtering.
+
+## Testing Requirements
+
+> [!CAUTION]
+> **Zero tolerance for raw MCP errors.** Any response that is a raw MCP error (no `success` field) is a bug — report as ❌.
+
+1. **Batched scripting**: Bundle multiple checks into single `sqlite_execute_code` calls. Use a `failures` array pattern.
+2. **Error path testing**: For **every** tool, test with `{}` (Zod) and a domain error. Both must return `{success: false, error: "..."}`.
+3. **Token tracking**: Monitor `metrics.tokenEstimate` on every response. Report the most expensive block.
+4. **Strict Coverage Matrix**: Maintain in `tmp/task.md`: `| Tool | Happy Path | Domain Error | Zod Error |`
+5. **Deterministic checklist first**: Complete ALL numbered items before freeform exploration.
+6. **Code Over Docs**: Fix the handler code if standards (Structured Errors/Zod) are violated. Do NOT change docs/prompts to accommodate broken code.
+
+## 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     |
+
+### Zod Refinement Leak Pattern
+
+`.partial()` does NOT strip `.min(N)` / `.max(N)` refinements. If `{}` or invalid values trigger raw MCP `-32602` instead of handler error, report as ❌.
+
+### Output Schema Validation Errors
+
+If valid inputs return raw MCP `-32602` mentioning "output schema", report as ❌.
+
+## Batched Script Pattern
+
+```javascript
+const failures = [];
+
+// Happy path
+const count = await sqlite.core.readQuery({
+  query: "SELECT COUNT(*) AS n FROM test_products",
+});
+if (!count.rows || count.rows[0].n !== 16)
+  failures.push("readQuery: expected 16 products");
+
+// Domain error
+const err = await sqlite.core.describeTable("nonexistent_xyz");
+if (err.success !== false)
+  failures.push("describeTable(nonexistent): expected {success: false}");
+
+// Zod empty params
+const zod = await sqlite.core.createTable({});
+if (zod.success !== false)
+  failures.push("createTable({}): expected validation error");
+
+return { failures, success: failures.length === 0 };
+```
+
+## Cleanup Conventions
+
+- Temporary tables: `temp_*` prefix. Drop at end of each script.
+- If DROP fails due to lock, note and move on.
+
+---
+
+## Phase 1: Core Group — Happy Paths (batched)
+
+> **Instructions**: Construct a single `sqlite_execute_code` script to execute the numbered items below. Use the `sqlite.*` namespace. Compare responses against expected results and push deviations to a `failures` array.
+
+**Read/Query tools:**
+
+1. `sqlite.core.readQuery({query: "SELECT COUNT(*) AS n FROM test_products"})` → `{rows: [{n: 16}]}`
+2. `sqlite.core.readQuery("SELECT name, price FROM test_products WHERE price > 500")` → 1 result: `Laptop Pro 15` (1299.99)
+3. `sqlite.core.readQuery({query: "SELECT COUNT(*) AS n FROM test_orders WHERE status = 'completed'"})` → `{rows: [{n: 8}]}`
+4. `sqlite.core.listTables()` → tables array includes `test_products`, `test_orders`, etc.
+5. `sqlite.core.describeTable("test_products")` → columns include `id` (INTEGER), `name` (TEXT), `price` (REAL)
+6. `sqlite.core.getIndexes({table: "test_orders"})` → includes `idx_orders_status`
+
+**Convenience tools:**
+
+7. `sqlite.core.count({table: "test_products"})` → `{count: 16}`
+8. `sqlite.core.count({table: "test_products", column: "category", distinct: true})` → distinct category count
+9. `sqlite.core.exists({table: "test_products", whereClause: "price > 1000"})` → `{exists: true}`
+10. `sqlite.core.exists({table: "test_products", whereClause: "price > 99999"})` → `{exists: false}`
+
+**Write tools (use temp tables):**
+
+11. `sqlite.core.createTable({table: "temp_cm_core", columns: [{name: "id", type: "INTEGER", primaryKey: true}, {name: "name", type: "TEXT"}, {name: "value", type: "REAL"}]})` → success
+12. `sqlite.core.writeQuery("INSERT INTO temp_cm_core (id, name, value) VALUES (1, 'alpha', 10.5), (2, 'beta', 20.0)")` → `{rowsAffected: 2}`
+13. `sqlite.core.upsert({table: "temp_cm_core", data: {id: 1, name: "alpha_updated", value: 15.0}, conflictColumn: "id"})` → success, row 1 updated
+14. `sqlite.core.batchInsert({table: "temp_cm_core", rows: [{id: 3, name: "gamma", value: 30.0}, {id: 4, name: "delta", value: 40.0}]})` → 2 rows inserted
+15. `sqlite.core.count({table: "temp_cm_core"})` → `{count: 4}`
+16. `sqlite.core.truncate({table: "temp_cm_core"})` → success
+17. `sqlite.core.count({table: "temp_cm_core"})` → `{count: 0}`
+
+**Index lifecycle:**
+
+18. `sqlite.core.writeQuery("INSERT INTO temp_cm_core (id, name) VALUES (1, 'test')")` → re-populate
+19. `sqlite.core.createIndex({table: "temp_cm_core", columns: ["name"], indexName: "idx_temp_cm_name"})` → success
+20. `sqlite.core.getIndexes({table: "temp_cm_core"})` → includes `idx_temp_cm_name`
+21. `sqlite.core.dropIndex({indexName: "idx_temp_cm_name"})` → success
+22. `sqlite.core.dropTable({table: "temp_cm_core"})` → success
+
+**Parameter binding:**
+
+23. `sqlite.core.readQuery({query: "SELECT name, price FROM test_products WHERE price > ?", params: [500]})` → 1 result: `Laptop Pro 15` (1299.99)
+24. `sqlite.core.readQuery({query: "SELECT name FROM test_products WHERE category = ? AND price < ?", params: ["electronics", 100]})` → verify multi-parameter binding returns correct subset
+
+**Boundary tests:**
+
+25. `sqlite.core.dropTable({table: "nonexistent_drop_test", ifExists: true})` → succeeds silently (ifExists prevents error on nonexistent table)
+
+---
+
+## Phase 2: Core Group — Domain & Separation Errors (batched)
+
+🔴 26. `sqlite.core.readQuery({query: "SELECT * FROM nonexistent_xyz"})` → `{success: false}`
+🔴 27. `sqlite.core.writeQuery("INSERT INTO nonexistent_xyz VALUES (1)")` → `{success: false}`
+🔴 28. `sqlite.core.describeTable("nonexistent_xyz")` → `{success: false}` mentioning table
+🔴 29. `sqlite.core.getIndexes({table: "nonexistent_xyz"})` → report behavior
+🔴 30. `sqlite.core.dropTable({table: "nonexistent_xyz", ifExists: false})` → `{success: false}`
+🔴 31. `sqlite.core.count({table: "nonexistent_xyz"})` → `{success: false}`
+🔴 32. `sqlite.core.exists({table: "nonexistent_xyz"})` → `{success: false}`
+🔴 33. `sqlite.core.upsert({table: "nonexistent_xyz", data: {id: 1}})` → `{success: false}`
+🔴 34. `sqlite.core.batchInsert({table: "nonexistent_xyz", rows: [{id: 1}]})` → `{success: false}`
+🔴 35. `sqlite.core.truncate({table: "nonexistent_xyz"})` → `{success: false}`
+
+**Write/read separation (gotcha #1):**
+
+🔴 36. `sqlite.core.writeQuery("SELECT * FROM test_products")` → `{success: false}` — writeQuery rejects SELECT statements
+🔴 37. `sqlite.core.readQuery("INSERT INTO test_products (name) VALUES ('bad')")` → `{success: false}` — readQuery rejects INSERT/UPDATE/DELETE
+
+**Boundary conditions:**
+
+🔴 38. `sqlite.core.batchInsert({table: "test_products", rows: []})` → report behavior (empty rows array)
+
+---
+
+## Phase 3: Core Group — Zod Validation (batched)
+
+🔴 39. `sqlite.core.readQuery({})` → `{success: false}` handler error
+🔴 40. `sqlite.core.writeQuery({})` → `{success: false}` handler error
+🔴 41. `sqlite.core.createTable({})` → `{success: false}` handler error
+🔴 42. `sqlite.core.describeTable({})` → `{success: false}` handler error
+🔴 43. `sqlite.core.dropTable({})` → `{success: false}` handler error
+🔴 44. `sqlite.core.createIndex({})` → `{success: false}` handler error
+🔴 45. `sqlite.core.dropIndex({})` → `{success: false}` handler error
+🔴 46. `sqlite.core.upsert({})` → `{success: false}` handler error
+🔴 47. `sqlite.core.batchInsert({})` → `{success: false}` handler error
+🔴 48. `sqlite.core.count({})` → `{success: false}` handler error
+🔴 49. `sqlite.core.exists({})` → `{success: false}` handler error
+🔴 50. `sqlite.core.truncate({})` → `{success: false}` handler error
+
+---
+
+## Phase 4: Multi-Step Workflow (4 tests)
+
+### 4.1 — ETL pipeline
+
+```javascript
+await sqlite.core.createTable({
+  table: "temp_cm_etl",
+  columns: [
+    { name: "id", type: "INTEGER", primaryKey: true },
+    { name: "raw", type: "TEXT" },
+    { name: "processed", type: "TEXT" },
+  ],
+});
+for (let i = 1; i <= 5; i++) {
+  await sqlite.core.writeQuery({
+    query: `INSERT INTO temp_cm_etl (raw) VALUES ('item_${i}')`,
+  });
+}
+await sqlite.core.writeQuery("UPDATE temp_cm_etl SET processed = UPPER(raw)");
+const result = await sqlite.core.readQuery("SELECT * FROM temp_cm_etl");
+await sqlite.core.dropTable({ table: "temp_cm_etl", ifExists: true });
+return result;
+```
+
+### 4.2 — Schema introspection + query
+
+```javascript
+const tables = await sqlite.core.listTables();
+const first = tables.tables[0].name;
+const schema = await sqlite.core.describeTable(first);
+const sample = await sqlite.core.readQuery({
+  query: `SELECT * FROM ${first} LIMIT 3`,
+});
+return {
+  table: first,
+  columnCount: schema.columns?.length,
+  sampleRows: sample.rows?.length,
+};
+```
+
+### 4.3 — Loop with accumulator
+
+```javascript
+const tables = await sqlite.core.listTables();
+const counts = {};
+for (const t of tables.tables.slice(0, 5)) {
+  const r = await sqlite.core.count({ table: t.name });
+  counts[t.name] = r.count;
+}
+return counts;
+```
+
+### 4.4 — Schema mutation + introspection verification
+
+```javascript
+const failures = [];
+// Create table and verify it appears in introspection
+await sqlite.core.createTable({
+  table: "temp_cm_intro_check",
+  columns: [
+    { name: "id", type: "INTEGER", primaryKey: true },
+    { name: "data", type: "TEXT" },
+  ],
+});
+const snapshot = await sqlite.introspection.schemaSnapshot({ compact: true });
+const found = snapshot.snapshot?.tables?.some(
+  (t) => t.name === "temp_cm_intro_check",
+);
+if (!found) failures.push("temp table not in schema snapshot after creation");
+
+// Drop table and verify it's gone
+await sqlite.core.dropTable({ table: "temp_cm_intro_check" });
+const after = await sqlite.introspection.schemaSnapshot({ compact: true });
+const stillThere = after.snapshot?.tables?.some(
+  (t) => t.name === "temp_cm_intro_check",
+);
+if (stillThere) failures.push("temp table still in snapshot after drop");
+
+return { failures, success: failures.length === 0 };
+```
+
+---
+
+## Post-Test Procedures
+
+1. **Cleanup**: Confirm all `temp_*` tables are removed
+2. **Triage findings**: Create implementation plan if issues found
+3. **Scope of fixes**: Handler code, server-instructions, test database, this prompt
+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. **Live re-test**: After server rebuild
+7. **Token audit**: Report `metrics.tokenEstimate` for the most expensive block
+8. **Final summary**: After testing/re-testing