db-mcp 1.1.1 → 2.0.0

package/test-server/test-advanced/test-codemode-advanced-stats.md

@@ -0,0 +1,185 @@
+# db-mcp Advanced Stress Test — [stats]
+
+> [!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:** Execute each numbered stress test below using `sqlite_execute_code` (code mode).
+
+**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:
+
+- **Skip Category 4** entirely (Window Functions — items 19-23) — `[NATIVE ONLY]`.
+- **Category 6** (WASM Boundary Verification) — execute only in WASM mode.
+- All other categories (1-3, 5) are fully WASM-compatible — 16 stats tools work identically.
+
+## Code Mode Execution
+
+- **Code Over Docs**: Fix the handler code if standards (Structured Errors/Zod) are violated. Do NOT change docs/prompts to accommodate broken code.
+
+All tests via `sqlite_execute_code`. Use `sqlite.stats.*` for all stats/window tools.
+State persists across calls. Do NOT pass `readonly: true`. Group related tests into single calls.
+
+## Test Database Schema
+
+| Table             | Rows | Key Columns                                          |
+| ----------------- | ---- | ---------------------------------------------------- |
+| test_products     | 16   | id, name, price (REAL), category (3 values)          |
+| test_orders       | 20   | id, product_id, total_price, order_date, status      |
+| test_measurements | 200  | id, sensor_id (1-5), temperature, humidity, pressure |
+
+## Naming & Cleanup
+
+- **Temporary tables**: `stress_*` prefix. Drop at end.
+
+## Reporting Format
+
+- ❌ Fail | ⚠️ Issue | 📦 Payload (monitor `metrics.tokenEstimate`) | ✅ Confirmed (inline only)
+
+### Error Message Quality Rating
+
+| Level                                  | Verdict |
+| -------------------------------------- | ------- |
+| 5 - Excellent (name + code + context)  | ✅      |
+| 4 - Good (name)                        | ✅      |
+| 3 - Adequate (raw SQLite, informative) | ⚠️      |
+| 2 - Poor (no object name)              | ⚠️      |
+| 1 - Useless (generic)                  | ❌      |
+
+## Structured Error Response Pattern
+
+Handler error ✅ = JSON with `success` + `error`. MCP error ❌ = raw text, `isError: true`.
+
+---
+
+## stats Group Tools — Native (22)
+
+1. sqlite_stats_basic
+2. sqlite_stats_count
+3. sqlite_stats_group_by
+4. sqlite_stats_histogram
+5. sqlite_stats_percentile
+6. sqlite_stats_correlation
+7. sqlite_stats_top_n
+8. sqlite_stats_distinct
+9. sqlite_stats_summary
+10. sqlite_stats_frequency
+11. sqlite_stats_outliers
+12. sqlite_stats_regression
+13. sqlite_stats_hypothesis
+14. sqlite_detect_anomalies
+15. sqlite_detect_bloat
+16. sqlite_detect_schema_risks
+17. sqlite_window_row_number `[NATIVE ONLY]`
+18. sqlite_window_rank `[NATIVE ONLY]`
+19. sqlite_window_lag_lead `[NATIVE ONLY]`
+20. sqlite_window_running_total `[NATIVE ONLY]`
+21. sqlite_window_moving_avg `[NATIVE ONLY]`
+22. sqlite_window_ntile `[NATIVE ONLY]`
+
+### WASM (16)
+
+Same minus the 6 window function tools (items 17-22).
+
+---
+
+### Category 1: Boundary Values & Empty States
+
+Create `stress_stats_table (id INTEGER PRIMARY KEY, value REAL, category TEXT)`:
+
+**1.1 Empty Table Statistics**
+
+1. `sqlite.stats.statsBasic({table: "stress_stats_table", column: "value"})` → graceful error or empty stats (not crash)
+2. `sqlite.stats.statsCount({table: "stress_stats_table"})` → `{count: 0}`
+3. `sqlite.stats.statsHistogram({table: "stress_stats_table", column: "value", buckets: 5})` → graceful handling
+
+**1.2 Single-Row Statistics**
+
+Insert one row: `(1, 42.0, 'test')`:
+
+4. `sqlite.stats.statsBasic({table: "stress_stats_table", column: "value"})` → count=1, min=max=avg=42.0
+5. `sqlite.stats.statsPercentile({table: "stress_stats_table", column: "value", percentiles: [25, 50, 75]})` → all equal 42
+6. `sqlite.stats.statsRegression({table: "stress_stats_table", xColumn: "id", yColumn: "value", degree: 1})` → graceful handling (regression undefined for n=1)
+
+**1.3 NULL-Heavy Data**
+
+Insert 5 rows: 3 with `value IS NULL`, 2 with actual values:
+
+7. `sqlite.stats.statsBasic({table: "stress_stats_table", column: "value"})` → only count non-null values (3 total)
+8. `sqlite.stats.statsCount({table: "stress_stats_table", column: "value"})` → non-null count only
+
+**1.4 Extreme Numeric Values**
+
+Insert: `(99999999.99)`, `(-99999999.99)`, `(0.0)`, `(0.01)`:
+
+9. `sqlite.stats.statsBasic({table: "stress_stats_table", column: "value"})` → verify min/max/avg handle extreme values
+
+---
+
+### Category 2: Statistical Edge Cases
+
+10. `sqlite.stats.statsCorrelation({table: "test_products", column1: "id", column2: "id"})` → self-correlation = 1.0
+11. `sqlite.stats.statsHypothesis({table: "test_measurements", column: "temperature", testType: "ttest_one", expectedMean: 999})` → should reject null hypothesis
+12. `sqlite.stats.statsOutliers({table: "test_measurements", column: "temperature", method: "iqr"})` → IQR-based outliers
+13. `sqlite.stats.statsOutliers({table: "test_measurements", column: "temperature", method: "zscore"})` → Z-score outliers (compare with IQR)
+14. `sqlite.stats.statsRegression({table: "test_measurements", xColumn: "temperature", yColumn: "humidity", degree: 2})` → quadratic regression
+
+---
+
+### Category 3: Anomaly Detection Stress
+
+15. `sqlite.stats.detectAnomalies({table: "test_measurements", column: "temperature"})` → anomaly detection result
+16. `sqlite.stats.detectAnomalies({table: "stress_stats_table", column: "value"})` → graceful handling on mixed NULL/extreme data
+17. `sqlite.stats.detectBloat()` → bloat detection
+18. `sqlite.stats.detectSchemaRisks()` → schema risk assessment
+
+---
+
+### Category 4: Window Functions `[NATIVE ONLY]`
+
+19. `sqlite.stats.windowRowNumber({table: "test_products", orderBy: "price DESC"})` → 16 rows, Laptop Pro 15 at #1
+    > **Note:** `window_row_number` and `window_rank` do NOT have a `direction` param — embed in `orderBy` string.
+20. `sqlite.stats.windowRank({table: "test_orders", orderBy: "total_price DESC"})` → ranks with potential ties
+21. `sqlite.stats.windowRunningTotal({table: "test_orders", valueColumn: "total_price", orderBy: "order_date"})` → monotonically increasing cumulative total
+22. `sqlite.stats.windowMovingAvg({table: "test_measurements", valueColumn: "temperature", windowSize: 10, orderBy: "measured_at"})` → 10-row moving average
+23. `sqlite.stats.windowNtile({table: "test_products", buckets: 4, orderBy: "price"})` → 4 groups of ~4 products
+
+---
+
+### Category 5: Error Message Quality
+
+24. `sqlite.stats.statsBasic({table: "nonexistent_table_xyz", column: "x"})` → structured error mentioning table name
+25. `sqlite.stats.statsBasic({table: "test_products", column: "nonexistent_col"})` → structured error mentioning column
+26. `sqlite.stats.statsCorrelation({table: "test_products", column1: "name", column2: "description"})` → error about non-numeric columns
+27. `sqlite.stats.statsHistogram({table: "test_products", column: "price", buckets: 0})` → error (must be > 0)
+28. `sqlite.stats.statsHistogram({table: "test_products", column: "price", buckets: -1})` → error
+
+---
+
+### Category 6: WASM Boundary Verification
+
+For WASM testing only:
+
+29. Confirm window function tools are NOT present in the tool list
+30. All 16 non-window stats tools should produce identical results in WASM and Native
+
+---
+
+### Final Cleanup
+
+Drop `stress_stats_table`. Confirm `test_measurements` (200 rows) and `test_products` (16 rows) unchanged.
+
+## Post-Test Procedures
+
+1. **Cleanup**: Drop all `stress_*` objects
+2. **Fix EVERY finding** — ❌, ⚠️, 📦
+3. **Validate**: Instruct the user to run the test suite (Vitest/Playwright), lint, and typecheck. Do NOT run them yourself.
+4. **Commit**: Stage and commit — do NOT push
+5. **Re-test**: After server rebuild
+6. **Token audit**: Report most expensive block

package/test-server/test-advanced/test-codemode-advanced-text.md

@@ -0,0 +1,183 @@
+# db-mcp Advanced Stress Test — [text]
+
+> [!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:** Execute each numbered stress test below using `sqlite_execute_code` (code mode).
+
+**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:
+
+- **Skip Category 6** entirely (FTS5 State Integrity — items 21-26) — `[NATIVE ONLY]`.
+- **Category 7** (WASM Boundary Verification) — execute only in WASM mode.
+- **Category 8**: Skip item 32 (`ftsSearch`) — `[NATIVE ONLY]`.
+- **Final Cleanup**: Skip FTS integrity check with `ftsMatchInfo` — `[NATIVE ONLY]`.
+- All other categories (1-5, 7-8) are fully WASM-compatible — 14 text tools work identically.
+
+## Code Mode Execution
+
+- **Code Over Docs**: Fix the handler code if standards (Structured Errors/Zod) are violated. Do NOT change docs/prompts to accommodate broken code.
+
+All tests via `sqlite_execute_code`. Use `sqlite.text.*` for all text/regex/FTS tools.
+State persists across calls. Do NOT pass `readonly: true`. Group related tests into single calls.
+
+## Test Database Schema
+
+| Table             | Rows | Key Columns                                              |
+| ----------------- | ---- | -------------------------------------------------------- |
+| test_products     | 16   | id, name (row 16: `Café Décor Light`), price, category   |
+| test_users        | 9    | id, username, email, phone, bio                          |
+| test_articles     | 8    | id, title, body, author, category                        |
+| test_articles_fts | —    | FTS5 virtual table (title, body columns) `[NATIVE ONLY]` |
+
+**Key data:**
+
+- Emails: `@example.com`, `@company.org`, `@gmail.com`; one dotted local: `test.user@gmail.com`
+- Phones: `+1-555-0101`, `+44-20-7123-4567`, `+82-2-1234-5678` (1 NULL)
+- Usernames: lowercase single-word (`johndoe`, `janesmith`, `testuser`, etc.)
+
+## Naming & Cleanup
+
+- **Temporary tables/FTS**: `stress_*` prefix. Drop at end.
+
+## Reporting Format
+
+- ❌ Fail | ⚠️ Issue | 📦 Payload (monitor `metrics.tokenEstimate`) | ✅ Confirmed (inline only)
+
+### Error Message Quality Rating
+
+| Level                                  | Verdict |
+| -------------------------------------- | ------- |
+| 5 - Excellent (name + code + context)  | ✅      |
+| 4 - Good (name)                        | ✅      |
+| 3 - Adequate (raw SQLite, informative) | ⚠️      |
+| 2 - Poor (no object name)              | ⚠️      |
+| 1 - Useless (generic)                  | ❌      |
+
+## Structured Error Response Pattern
+
+Handler error ✅ = JSON with `success` + `error`. MCP error ❌ = raw text, `isError: true`.
+
+---
+
+## text Group Tools — Native (19)
+
+1. sqlite_regex_extract
+2. sqlite_regex_match
+3. sqlite_text_split
+4. sqlite_text_concat
+5. sqlite_text_replace
+6. sqlite_text_trim
+7. sqlite_text_case
+8. sqlite_text_substring
+9. sqlite_fuzzy_match
+10. sqlite_phonetic_match
+11. sqlite_text_normalize
+12. sqlite_text_validate
+13. sqlite_advanced_search
+14. sqlite_text_sentiment
+15. sqlite_fts_create `[NATIVE ONLY]`
+16. sqlite_fts_search `[NATIVE ONLY]`
+17. sqlite_fts_rebuild `[NATIVE ONLY]`
+18. sqlite_fts_match_info `[NATIVE ONLY]`
+19. sqlite_fts_headline `[NATIVE ONLY]`
+
+### WASM (14)
+
+Same minus the 5 FTS5 tools (items 15-19).
+
+---
+
+### Category 1: Regex Edge Cases
+
+1. `sqlite.text.regexMatch({table: "test_users", column: "email", pattern: "^[a-z]+\\.[a-z]+@"})` → match dotted local parts (test.user)
+2. `sqlite.text.regexMatch({table: "test_users", column: "phone", pattern: "^\\+1"})` → US phone numbers only (6 users, 1 NULL excluded)
+3. `sqlite.text.regexExtract({table: "test_users", column: "email", pattern: "@(.+)$", groupIndex: 1})` → full domain extraction
+4. `sqlite.text.regexMatch({table: "test_users", column: "bio", pattern: ".*"})` → should match all non-NULL bios (all 9 users have bios)
+
+---
+
+### Category 2: Fuzzy/Phonetic Matching Stress
+
+5. `sqlite.text.fuzzyMatch({table: "test_products", column: "name", search: "Keyborad", maxDistance: 3})` → find "Mechanical Keyboard" (Levenshtein)
+6. `sqlite.text.fuzzyMatch({table: "test_products", column: "name", search: "LAPTOP", maxDistance: 2, tokenize: true})` → match "Laptop" token in "Laptop Pro 15"
+7. `sqlite.text.fuzzyMatch({table: "test_products", column: "name", search: "xyznonexistent", maxDistance: 1})` → 0 results
+8. `sqlite.text.phoneticMatch({table: "test_users", column: "username", search: "jon", algorithm: "soundex"})` → 0 results (Soundex: "jon"=J500 ≠ "johndoe"=J530; single-word usernames aren't tokenized)
+9. `sqlite.text.phoneticMatch({table: "test_users", column: "username", search: "smith", algorithm: "soundex"})` → report behavior (janesmith contains "smith" as suffix)
+10. `sqlite.text.advancedSearch({table: "test_users", column: "username", searchTerm: "jhn", techniques: ["exact", "fuzzy", "phonetic"], fuzzyThreshold: 0.3})` → should find John via fuzzy/phonetic
+
+---
+
+### Category 3: Text Transformation Edge Cases
+
+11. `sqlite.text.normalize({table: "test_products", column: "name", mode: "strip_accents"})` → `"Café Décor Light"` → `"Cafe Decor Light"` — verify ALL rows returned
+12. `sqlite.text.normalize({table: "test_products", column: "name", mode: "nfkc"})` → NFKC normalization
+13. `sqlite.text.case({table: "test_users", column: "username", mode: "upper"})` → verify 9 uppercased usernames
+14. `sqlite.text.case({table: "test_users", column: "username", mode: "lower"})` → idempotent (already lowercase)
+15. `sqlite.text.substring({table: "test_users", column: "email", start: 1, length: 3})` → first 3 chars of each email
+
+---
+
+### Category 4: Validation Patterns
+
+16. `sqlite.text.validate({table: "test_users", column: "email", pattern: "email"})` → expect all 9 valid
+17. `sqlite.text.validate({table: "test_users", column: "phone", pattern: "phone"})` → report valid/invalid/null counts
+18. `sqlite.text.validate({table: "test_users", column: "email", pattern: "custom", customPattern: "^.+@.+\\..{2,}$"})` → custom regex validation
+
+---
+
+### Category 5: Sentiment Analysis Edge Cases
+
+19. `sqlite.text.sentiment({table: "test_articles", column: "body"})` → sentiment scores for all 8 articles
+20. Create `stress_sentiment_test` with rows: `"I love this!"` (positive), `"This is terrible"` (negative), `""` (empty), `NULL` → report behavior for edge cases
+
+---
+
+### Category 6: FTS5 State Integrity `[NATIVE ONLY]`
+
+21. `sqlite.text.ftsSearch({table: "test_articles_fts", query: "database"})` → results about databases
+22. `sqlite.text.ftsRebuild({table: "test_articles_fts"})` → success
+23. `sqlite.text.ftsSearch({table: "test_articles_fts", query: "database"})` → same results after rebuild (idempotent)
+24. `sqlite.text.ftsSearch({table: "test_articles_fts", query: "SQLite AND database"})` → boolean operator
+25. `sqlite.text.ftsSearch({table: "test_articles_fts", query: "\"full-text search\""})` → phrase query
+26. `sqlite.text.ftsHeadline({table: "test_articles_fts", query: "SQLite"})` → highlighted results
+
+---
+
+### Category 7: WASM Boundary Verification
+
+For WASM testing only:
+
+27. Confirm FTS5 tools are NOT present in the tool list (WASM mode excludes them)
+28. All 14 non-FTS text tools should work identically in WASM and Native
+
+---
+
+### Category 8: Error Message Quality
+
+29. `sqlite.text.regexMatch({table: "nonexistent_table_xyz", column: "x", pattern: "."})` → structured error
+30. `sqlite.text.fuzzyMatch({table: "test_users", column: "nonexistent_col", search: "test"})` → structured error
+31. `sqlite.text.validate({table: "test_users", column: "email", pattern: "custom"})` → error about missing `customPattern`
+32. `sqlite.text.ftsSearch({table: "nonexistent_fts_xyz", query: "test"})` `[NATIVE ONLY]` → structured error
+
+---
+
+### Final Cleanup
+
+Drop `stress_*` tables. Confirm `test_articles` row count is still 8. Verify FTS index integrity with `sqlite.text.ftsMatchInfo` `[NATIVE ONLY]`.
+
+## Post-Test Procedures
+
+1. **Cleanup**: Drop all `stress_*` objects
+2. **Fix EVERY finding** — ❌, ⚠️, 📦
+3. **Validate**: Instruct the user to run the test suite (Vitest/Playwright), lint, and typecheck. Do NOT run them yourself.
+4. **Commit**: Stage and commit — do NOT push
+5. **Re-test**: After server rebuild
+6. **Token audit**: Report most expensive block

package/test-server/test-advanced/test-codemode-advanced-transactions.md

@@ -0,0 +1,136 @@
+# db-mcp Advanced Stress Test — [transactions]
+
+> [!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:** Execute each numbered stress test below using `sqlite_execute_code` (code mode).
+
+**Step 3:** The agent should update C:\Users\chris\Desktop\db-mcp\UNRELEASED.md with any/all changes/fixes.
+
+> **Note:** All 8 transaction tools are **`[NATIVE ONLY]`** — they are not available in WASM mode.
+
+## WASM Mode
+
+> [!CAUTION]
+> **Skip this entire prompt in WASM mode.** All 8 transaction tools are `[NATIVE ONLY]` — they are not registered in the WASM adapter. The `sqlite.transactions` namespace exists but contains 0 methods. Use `test-tool-group-codemode-wasm-degradation.md` to verify this behavior.
+
+## Code Mode Execution
+
+- **Code Over Docs**: Fix the handler code if standards (Structured Errors/Zod) are violated. Do NOT change docs/prompts to accommodate broken code.
+
+All tests via `sqlite_execute_code`. Use `sqlite.transactions.*` for transaction tools, `sqlite.core.*` for read/write.
+State persists across calls. Do NOT pass `readonly: true`.
+
+> **⚠️ Transaction tests are sequential** — each depends on state from the previous. Run lifecycle tests individually, not batched.
+
+## Test Database Schema
+
+| Table         | Rows | Key Columns                              |
+| ------------- | ---- | ---------------------------------------- |
+| test_products | 16   | id, name, price, category                |
+| test_orders   | 20   | id, product_id (FK), total_price, status |
+
+## Naming & Cleanup
+
+- **Temporary tables**: `stress_*` prefix. Drop at end.
+- If an active transaction is left open, roll it back before cleanup.
+
+## Reporting Format
+
+- ❌ Fail | ⚠️ Issue | 📦 Payload (monitor `metrics.tokenEstimate`) | ✅ Confirmed (inline only)
+
+## Structured Error Response Pattern
+
+Handler error ✅ = JSON with `success` + `error`. MCP error ❌ = raw text, `isError: true`.
+
+---
+
+## transactions Group Tools — Native Only (8)
+
+1. sqlite_transaction_begin
+2. sqlite_transaction_commit
+3. sqlite_transaction_rollback
+4. sqlite_transaction_savepoint
+5. sqlite_transaction_release
+6. sqlite_transaction_rollback_to
+7. sqlite_transaction_execute
+8. sqlite_transaction_status
+
+---
+
+### Category 1: Aborted Transaction Recovery
+
+15. `sqlite.transactions.begin()` → get transaction ID
+16. `sqlite.transactions.execute({statements: ["INSERT INTO nonexistent_table VALUES (1)"]})` → should fail
+17. Start new transaction → verify it works normally (no lingering aborted state)
+
+---
+
+### Category 2: Savepoint Stress Test
+
+18. `sqlite.transactions.begin()` → begin
+19. Create savepoint `sp1`
+20. `sqlite.core.writeQuery("INSERT INTO stress_tx_sp (id, val) VALUES (1, 'a')")` → insert within transaction (create `stress_tx_sp` first)
+21. Create savepoint `sp2`
+22. `sqlite.core.writeQuery("INSERT INTO stress_tx_sp (id, val) VALUES (2, 'b')")` → insert
+23. `sqlite.transactions.rollbackTo({name: "sp2"})` → should undo sp2's insert
+24. `sqlite.transactions.rollbackTo({name: "sp1"})` → should undo all inserts
+25. `sqlite.transactions.commit()` → only pre-sp1 state persists
+
+---
+
+### Category 3: Transaction Execute — Mixed Statements
+
+26. `sqlite.transactions.execute({statements: ["CREATE TABLE stress_tx_test (id INTEGER PRIMARY KEY, name TEXT)", "INSERT INTO stress_tx_test VALUES (1, 'alpha')", "INSERT INTO stress_tx_test VALUES (2, 'beta')"]})` → success, 3 statements
+27. Verify `stress_tx_test` exists with 2 rows
+
+---
+
+### Category 4: Transaction Execute — Failure Rollback
+
+28. `sqlite.transactions.execute({statements: ["CREATE TABLE stress_tx_fail (id INT)", "INSERT INTO nonexistent_xyz VALUES (1)", "CREATE TABLE stress_tx_fail2 (id INT)"]})` → failure
+29. Verify: `stress_tx_fail` does NOT exist (atomic rollback worked)
+
+---
+
+### Category 5: Rapid State Transitions
+
+30. Begin → commit immediately (empty transaction)
+31. Begin → rollback immediately (empty transaction)
+32. `sqlite.transactions.status()` → verify `{active: false}` after both
+33. Begin → savepoint → release → commit (minimal lifecycle)
+
+---
+
+### Category 6: Error Message Quality
+
+34. `sqlite.transactions.rollback()` with no active transaction → report behavior
+35. `sqlite.transactions.release({name: "nonexistent_sp_xyz"})` → structured error
+36. `sqlite.transactions.execute({statements: []})` → report behavior for empty array
+
+---
+
+### Category 7: WASM Boundary Verification
+
+For WASM testing only:
+
+37. Confirm all 8 transaction tools are NOT present in the tool list
+
+---
+
+### Final Cleanup
+
+Drop `stress_tx_sp`, `stress_tx_test`, `stress_tx_fail` if they exist. Confirm `test_products` (16 rows) and `test_orders` (20 rows) unchanged.
+
+## Post-Test Procedures
+
+1. **Cleanup**: Roll back any active transaction, drop all `stress_*` objects
+2. **Fix EVERY finding** — ❌, ⚠️, 📦
+3. **Validate**: Instruct the user to run the test suite (Vitest/Playwright), lint, and typecheck. Do NOT run them yourself.
+4. **Commit**: Stage and commit — do NOT push
+5. **Re-test**: After server rebuild
+6. **Token audit**: Report most expensive block

package/test-server/test-advanced/test-codemode-advanced-vector.md

@@ -0,0 +1,141 @@
+# db-mcp Advanced Stress Test — [vector]
+
+> [!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:** Execute each numbered stress test below using `sqlite_execute_code` (code mode).
+
+**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 11 vector tools are fully WASM-compatible. No categories to skip or adjust.
+
+## Code Mode Execution
+
+- **Code Over Docs**: Fix the handler code if standards (Structured Errors/Zod) are violated. Do NOT change docs/prompts to accommodate broken code.
+
+All tests via `sqlite_execute_code`. Use `sqlite.vector.*` for vector tools, `sqlite.core.*` for read/write.
+State persists across calls. Do NOT pass `readonly: true`. Group related tests into single calls.
+
+## Test Database Schema
+
+| Table           | Rows | Key Columns                                               |
+| --------------- | ---- | --------------------------------------------------------- |
+| test_embeddings | 20   | id, content, category, embedding (8-dim JSON float array) |
+
+**Categories**: database, fitness, food, tech, travel (each ~4 rows)
+**Row 1**: content="Machine learning fundamentals", embedding=[0.12, 0.45, -0.23, 0.78, 0.34, -0.56, 0.89, 0.01]
+
+> Vector tools use pure JS computations with JSON-stored vectors — all 11 tools work identically in WASM and Native.
+
+## Naming & Cleanup
+
+- **Temporary tables**: `stress_*` prefix. Drop at end.
+
+## Reporting Format
+
+- ❌ Fail | ⚠️ Issue | 📦 Payload (monitor `metrics.tokenEstimate`) | ✅ Confirmed (inline only)
+
+## Structured Error Response Pattern
+
+Handler error ✅ = JSON with `success` + `error`. MCP error ❌ = raw text, `isError: true`.
+
+---
+
+## vector Group Tools (11)
+
+1. sqlite_vector_create_table
+2. sqlite_vector_store
+3. sqlite_vector_batch_store
+4. sqlite_vector_search
+5. sqlite_vector_get
+6. sqlite_vector_delete
+7. sqlite_vector_count
+8. sqlite_vector_stats
+9. sqlite_vector_dimensions
+10. sqlite_vector_normalize
+11. sqlite_vector_distance
+
+---
+
+### Category 1: Boundary Values
+
+> **Note:** `createTable` uses `tableName`, other ops use `table`. Store/batch-store require `idColumn` and `vectorColumn`.
+
+**1.1 Empty Vector Table**
+
+1. `sqlite.vector.createTable({tableName: "stress_vec_empty", dimensions: 4})` → success
+2. `sqlite.vector.count({table: "stress_vec_empty"})` → `{count: 0}`
+3. `sqlite.vector.search({table: "stress_vec_empty", vectorColumn: "vector", queryVector: [1, 2, 3, 4], metric: "cosine", limit: 5})` → empty results (not error)
+4. `sqlite.vector.stats({table: "stress_vec_empty", vectorColumn: "vector"})` → graceful: `{count: 0, message: "No valid vectors found"}`
+5. `sqlite.vector.dimensions({table: "stress_vec_empty", vectorColumn: "vector"})` → `{dimensions: null, message: "No vectors found"}` (inferred from data)
+
+**1.2 Single-Vector Table**
+
+6. `sqlite.vector.store({table: "stress_vec_empty", idColumn: "id", vectorColumn: "vector", id: 1, vector: [1, 0, 0, 0]})` → success
+7. `sqlite.vector.search({table: "stress_vec_empty", vectorColumn: "vector", queryVector: [1, 0, 0, 0], metric: "cosine", limit: 5})` → 1 result, similarity ≈ 1
+
+---
+
+### Category 2: Distance Metric Verification
+
+8. `sqlite.vector.distance({vector1: [1, 0, 0], vector2: [0, 1, 0], metric: "cosine"})` → ≈ 1.0 (orthogonal)
+9. `sqlite.vector.distance({vector1: [1, 0, 0], vector2: [1, 0, 0], metric: "cosine"})` → ≈ 0.0 (identical)
+10. `sqlite.vector.distance({vector1: [1, 0, 0], vector2: [-1, 0, 0], metric: "cosine"})` → ≈ 2.0 (opposite)
+11. `sqlite.vector.distance({vector1: [3, 4], vector2: [0, 0], metric: "euclidean"})` → exactly 5.0
+12. `sqlite.vector.distance({vector1: [1, 2, 3], vector2: [1, 2, 3], metric: "euclidean"})` → exactly 0.0
+13. `sqlite.vector.normalize({vector: [3, 4]})` → `{normalized: [0.6, 0.8], originalMagnitude: 5.0}`
+14. `sqlite.vector.normalize({vector: [0, 0, 0]})` → `{normalized: [0, 0, 0], originalMagnitude: 0}` (zero vector, no crash)
+
+---
+
+### Category 3: Dimension Mismatch
+
+> Dimension validation on store is best-effort. `distance` enforces strictly.
+
+15. `sqlite.vector.store({table: "stress_vec_empty", idColumn: "id", vectorColumn: "vector", id: 2, vector: [1, 2]})` → dimension mismatch error (table has 4-dim rows)
+16. `sqlite.vector.search({table: "stress_vec_empty", vectorColumn: "vector", queryVector: [1, 2], metric: "cosine"})` → search runs (dimension mismatch silently handled via try/catch)
+17. `sqlite.vector.distance({vector1: [1, 2, 3], vector2: [1, 2], metric: "cosine"})` → structured error: "Vector dimensions must match"
+
+---
+
+### Category 4: Batch Operations
+
+18. `sqlite.vector.batchStore({table: "stress_vec_empty", idColumn: "id", vectorColumn: "vector", items: []})` → `{stored: 0, message: "No items provided"}`
+19. `sqlite.vector.batchStore(...)` with 50 vectors into `stress_vec_empty` → `{stored: 50}`
+20. `sqlite.vector.count({table: "stress_vec_empty"})` → `{count: 51}` (1 from earlier + 50 batch)
+
+---
+
+### Category 5: Category Filtering
+
+21. `sqlite.vector.search({table: "test_embeddings", vectorColumn: "embedding", queryVector: [0.12, 0.45, -0.23, 0.78, 0.34, -0.56, 0.89, 0.01], metric: "cosine", limit: 20, whereClause: "category = 'tech'"})` → only tech results (4 rows)
+22. `sqlite.vector.search({table: "test_embeddings", vectorColumn: "embedding", queryVector: [0.12, 0.45, -0.23, 0.78, 0.34, -0.56, 0.89, 0.01], metric: "cosine", limit: 20, whereClause: "category = 'nonexistent'"})` → 0 results (not error)
+
+---
+
+### Category 6: Error Message Quality
+
+23. `sqlite.vector.search({table: "nonexistent_table_xyz", vectorColumn: "v", queryVector: [1, 2, 3], metric: "cosine"})` → structured error mentioning table name
+24. `sqlite.vector.get({table: "test_embeddings", idColumn: "id", vectorColumn: "embedding", id: 99999})` → `{success: false, error: "Vector not found"}`
+25. `sqlite.vector.delete({table: "test_embeddings", idColumn: "id", ids: [99999]})` → `{success: true, deleted: 0}` (idempotent)
+
+---
+
+### Final Cleanup
+
+Drop `stress_vec_empty`. Confirm `test_embeddings` count is still 20.
+
+## Post-Test Procedures
+
+1. **Cleanup**: Drop all `stress_*` objects
+2. **Fix EVERY finding** — ❌, ⚠️, 📦
+3. **Validate**: Instruct the user to run the test suite (Vitest/Playwright), lint, and typecheck. Do NOT run them yourself.
+4. **Commit**: Stage and commit — do NOT push
+5. **Re-test**: After server rebuild
+6. **Token audit**: Report most expensive block