db-mcp 2.0.0 → 3.0.0

package/test-server/README.md

@@ -1,115 +0,0 @@
-# db-mcp Test Database — Agent Testing Instructions
-
-> **This README is optimized for AI agent consumption.** It serves as the primary orchestration document for running manual MCP functionality tests against the local SQLite database.
-
-## Files
-
-| File                         | Size  | Purpose                                                                                                                                                        | When to Read                                                                        |
-| ---------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `test-tool-groups/`          | —     | **10 self-contained test prompts** — one per tool group. Each is a complete, standalone prompt (paste directly). See `test-tool-groups/README.md` for details. | **Primary testing method** — use instead of `test-tools.md` + `test-group-tools.md` |
-| `test-codemode/`             | —     | **10 self-contained Code Mode test prompts** — one per tool group. Tests via `sqlite_execute_code` only. See `test-codemode/README.md`.                        | **Primary Code Mode testing method**                                                |
-| `test-advanced/`             | —     | **10 self-contained advanced stress test prompts** — one per tool group. Second-pass edge cases via Code Mode. See `test-advanced/README.md`.                  | **Primary advanced testing method**                                                 |
-| `test-resources.md`          | ~6KB  | Resource testing plan (8 data + 7 help resources via `read_resource`)                                                                                          | When testing resources                                                              |
-| `test-preflight.md`          | ~2KB  | **Pre-flight check** — validates slim instructions, help resources, data resources, and tool-filter alignment in 5 steps                                       | Before any test pass                                                                |
-| `test-prompts.md`            | ~10KB | Prompt testing plan (10 prompts, tested manually since agents typically don't invoke prompts)                                                                  | When testing prompts                                                                |
-| `tool-groups-list.md`        | —     | **Canonical tool inventory** — all 10 groups + codemode, 151 Native / 125 WASM tools. Source of truth for tool counts.                                         | Reference / auditing                                                                |
-| `tool-reference.md`          | ~18KB | **Complete Tool Reference** — Detailed list of all 151 Native / 125 WASM tools organized by group.                                                             | Reference                                                                           |
-| [`code-map.md`](code-map.md) | ~12KB | **Source Code Map** — Directory tree, handler→tool mapping, type/schema locations, error hierarchy, constants, architecture patterns.                          | When debugging source code or making changes                                        |
-| `reset-database.ps1`         | ~11KB | PowerShell script to delete + re-seed `test.db` from `test-database.sql`. Verifies row counts.                                                                 | After migration group testing or if data is polluted                                |
-| `test-database.sql`          | ~21KB | Seed SQL (DDL + DML) for all `test_*` tables                                                                                                                   | Reference only — reset script consumes this                                         |
-| `sample.csv`                 | <1KB  | CSV fixture for `sqlite_create_csv_table` / `sqlite_analyze_csv_schema` testing                                                                                | Used by admin group checklist                                                       |
-
-## Test Database Schema
-
-| Table               | Rows | Notable Columns                                                                                                   |
-| ------------------- | ---- | ----------------------------------------------------------------------------------------------------------------- |
-| `test_products`     | 16   | price (REAL), category (TEXT, lowercase). Row 16: `Café Décor Light` (accented)                                   |
-| `test_orders`       | 20   | product_id FK → test_products, status (TEXT)                                                                      |
-| `test_jsonb_docs`   | 6    | **doc** (JSON), **metadata** (nested JSON), **tags** (JSON array). Row 4: `$.nested.level1.level2 = "deep value"` |
-| `test_articles`     | 8    | FTS5 searchable: SQLite, database, JSON, FTS, vector, API, search, MCP                                            |
-| `test_users`        | 9    | email, phone (`+1-555-...` format), bio. 1 NULL phone.                                                            |
-| `test_measurements` | 200  | sensor_id (INTEGER 1-5), temperature, humidity, pressure                                                          |
-| `test_embeddings`   | 20   | 8-dim float vectors. Categories: tech, database, food, fitness, travel                                            |
-| `test_locations`    | 15   | latitude/longitude. Cities: NYC(3), Paris(3), London(3), Tokyo(2), Sydney(2), SF(2)                               |
-| `test_categories`   | 17   | Hierarchical: name, path, level                                                                                   |
-| `test_events`       | 100  | **payload** (JSON), event_type, user_id (INT, 8 values)                                                           |
-
-**Key FK:** `test_orders.product_id → test_products.id`
-**Redundant index (intentional):** `idx_orders_status` is a prefix of `idx_orders_status_date` — used to test index audit tools.
-
-## Conventions
-
-| Convention                     | Rule                                                                                                                       |
-| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
-| **Temp tables (basic tests)**  | `temp_*` prefix → drop after testing                                                                                       |
-| **Temp tables (stress tests)** | `stress_*` prefix → drop after testing                                                                                     |
-| **String values**              | Lowercase (`'electronics'`, not `'Electronics'`)                                                                           |
-| **sensor_id**                  | INTEGER (use `= 1`, not `= 'S001'`)                                                                                        |
-| **Reporting**                  | ❌ Fail, ⚠️ Issue, 📦 Payload concern. ✅ inline only, omit from final summary.                                            |
-| **Error testing**              | Every tool: test (a) domain error + (b) Zod error (`{}`). Must return `{success: false, error: "..."}`, NOT raw MCP error. |
-| **Error item prefix**          | All error-path checklist items use 🔴 prefix to distinguish from happy-path items                                          |
-| **Code mode**                  | Don't pass `readonly: true` unless specifically testing read-only filtering                                                |
-| **Post-test**                  | Clean up temps → plan fixes → implement → lint+typecheck → changelog → commit (no push) → re-test fixes                    |
-| **Database reset**             | Run `.\reset-database.ps1` after migration testing or data pollution                                                       |
-
-## WASM Parity Protocol
-
-To validate WASM mode produces identical results for shared tools:
-
-1. **Configure for WASM**: Set `--sqlite` (not `--sqlite-native`) in your MCP client config
-2. **Expected tool count**: 115 WASM vs 140 Native (25 fewer: 4 FTS5, 6 window, 8 transaction, 7 SpatiaLite)
-3. **Run the same checklists**: Use `test-group-tools.md` but skip items marked `[NATIVE ONLY]`
-4. **Verify shared tools**: All non-`[NATIVE ONLY]` items should produce identical output in both backends
-5. **Verify absent tools**: Calling a Native-only tool in WASM mode should return a structured error (not crash)
-6. **Key groups to verify**: text (FTS5 absent), stats (window functions absent), admin (transactions absent), geo (SpatiaLite absent)
-
-## Integration Test Scripts
-
-These scripts test features that require separate server processes — they **cannot** be run via MCP tool calls. All scripts are Node.js (`.mjs`), require no dependencies beyond Node.js, and exit with code 0 on success.
-
-> [!IMPORTANT]
-> Always `npm run build` before running these scripts — they execute `dist/cli.js` directly.
-
-### Script Reference
-
-| Script                      | Tests                                                           | Transport | Duration |
-| --------------------------- | --------------------------------------------------------------- | --------- | -------- |
-| `test-help-resources.mjs`   | Slim instructions + `sqlite://help` resource filtering by group | stdio     | ~15s     |
-| `test-tool-annotations.mjs` | `tools/list` openWorldHint annotation presence and consistency  | stdio     | ~5s      |
-
-### Quick Run
-
-```powershell
-cd C:\Users\chris\Desktop\db-mcp
-npm run build
-
-# Help resources
-node test-server/test-help-resources.mjs
-
-# Tool annotations
-node test-server/test-tool-annotations.mjs
-```
-
-### Success Criteria
-
-#### Help Resources
-
-- [ ] Instructions under 1000 chars (~680)
-- [ ] `sqlite://help` always registered
-- [ ] Group-specific help only for enabled groups
-- [ ] No old content leaked into slim instructions
-
-#### Tool Annotations
-
-- [ ] All tools have `annotations` object with `openWorldHint` set
-- [ ] All `openWorldHint` values are `false` (db-mcp tools are local-only)
-- [ ] 0 missing annotations
-
-## Agent Workflow
-
-1. Read `sqlite://help` resource (or `view_file` on `src/constants/server-instructions/gotchas.md`).
-2. Open the target group prompt from `test-tool-groups/` (e.g., `test-admin-core.md`). Each file is self-contained.
-3. Execute via direct MCP tool calls to test logic. Run both happy-path and error-path tests.
-4. Clean up any temporary tables generated during execution.
-5. Report findings using the designated reporting convention.
-6. (Optional) Run stress tests from `test-advanced/` folder.

package/test-server/code-map.md

@@ -1,421 +0,0 @@
-# db-mcp Code Map
-
-> **Agent-optimized navigation reference.** Read this before searching the codebase. Covers directory layout, handler→tool mapping, type/schema locations, error hierarchy, and key constants.
->
-> Last updated: May 16, 2026
-
----
-
-## Directory Tree
-
-```
-src/
-├── cli.ts                          # CLI entry point (arg parsing, transport selection)
-├── index.ts                        # Barrel re-export for library consumers
-├── version.ts                      # SSoT version constant (reads package.json)
-│
-├── server/
-│   └── mcp-server.ts               # McpServer setup, adapter registration, tool/resource/prompt wiring
-│
-├── types/                          # Core TypeScript types (barrel: types/index.ts)
-│   ├── adapter.ts                  # ToolDefinition, ResourceDefinition, PromptDefinition, AdapterCapabilities
-│   ├── auth.ts                     # OAuthConfig, OAuthScope, TokenClaims, RequestContext
-│   ├── database.ts                 # DatabaseConfig, QueryResult, ColumnInfo, TableInfo, SchemaInfo, IndexInfo
-│   ├── filtering.ts                # ToolGroup, MetaGroup, ToolFilterRule, ToolFilterConfig
-│   ├── server.ts                   # TransportType, McpServerConfig (incl. authToken, oauth)
-│   └── index.ts                    # Barrel — also re-exports error classes from utils/errors
-│
-├── constants/
-│   ├── server-instructions.ts      # Generated: slim INSTRUCTIONS constant (~680 chars) + HELP_CONTENT map (per-group help)
-│   └── server-instructions/        # Source .md files for each help resource
-│       ├── overview.md             # Root help content (sqlite://help)
-│       ├── gotchas.md              # Common gotchas and critical usage patterns
-│       ├── admin.md                # Admin group help
-│       ├── geo.md                  # Geo group help
-│       ├── introspection.md        # Introspection group help
-│       ├── json.md                 # JSON group help
-│       ├── migration.md            # Migration group help
-│       ├── stats.md                # Stats group help
-│       ├── text.md                 # Text group help
-│       └── vector.md              # Vector group help
-│
-├── filtering/
-│   ├── tool-constants.ts           # TOOL_GROUPS arrays, META_GROUPS shortcuts, group→tools map
-│   └── tool-filter.ts              # ToolFilter class — parse/apply --tool-filter expressions
-│
-├── utils/
-│   ├── annotations.ts              # MCP tool annotation helpers (readOnly, destructive hints)
-│   ├── icons.ts                    # MCP icon definitions per tool group
-│   ├── identifiers.ts              # SQL identifier validation/sanitization (table names, columns)
-│   ├── insights-manager.ts         # memo://insights resource accumulator
-│   ├── progress-utils.ts           # MCP progress notification helpers
-│   ├── resource-annotations.ts     # MCP resource annotation helpers
-│   ├── where-clause.ts             # WHERE clause builder/validator
-│   ├── index.ts                    # Barrel re-export
-│   ├── errors/                     # Error class hierarchy (see § Error Classes below)
-│   │   ├── base.ts                 # DbMcpError (abstract base) — auto-refines generic codes via suggestions
-│   │   ├── categories.ts           # ErrorCategory enum + ErrorResponse interface
-│   │   ├── classes.ts              # 8 concrete error subclasses
-│   │   ├── error-response-fields.ts # ErrorResponseFields mixin (SSoT, re-exported from format.ts)
-│   │   ├── format.ts               # formatHandlerError() — structured {success:false} builder
-│   │   ├── suggestions.ts          # Error suggestion helpers (typo hints, table/column suggestions)
-│   │   └── index.ts                # Barrel
-│   └── logger/
-│       ├── logger.ts               # Logger class (structured JSON, severity filtering)
-│       ├── module-logger.ts        # createModuleLogger() factory
-│       ├── error-codes.ts          # Module-prefixed error code constants
-│       ├── types.ts                # LogLevel, LogEntry types
-│       └── index.ts                # Barrel
-│
-├── auth/                           # OAuth 2.1 implementation
-│   ├── auth-context.ts             # Auth context utilities
-│   ├── middleware/                  # Express-style OAuth middleware (split from middleware.ts)
-│   │   └── index.ts
-│   ├── token-validator.ts          # JWT/JWKS token validation
-│   ├── scopes/                     # Scope parsing, enforcement (split from scopes.ts)
-│   │   └── index.ts
-│   ├── scope-map.ts                # Tool→scope mapping
-│   ├── oauth-resource-server.ts    # RFC 9728 /.well-known/oauth-protected-resource
-│   ├── authorization-server-discovery.ts  # RFC 8414 auth server metadata discovery
-│   ├── transport-agnostic.ts       # Non-Express auth re-exports for transport portability
-│   ├── errors.ts                   # OAuth-specific error classes
-│   └── types.ts                    # OAuth TypeScript types
-│
-├── audit/                          # Audit logging subsystem
-│   ├── types.ts                    # AuditEntry, AuditConfig, BackupConfig, SnapshotMetadata types
-│   ├── logger.ts                   # AuditLogger — async-buffered JSONL writer with rotation
-│   ├── interceptor.ts              # createAuditInterceptor() — wraps tool handlers with around(), reads OAuth identity from AsyncLocalStorage
-│   ├── backup-manager.ts           # BackupManager — pre-mutation DDL snapshots (gzip)
-│   └── index.ts                    # Barrel
-│
-├── transports/
-│   └── http/
-│       ├── transport.ts            # HTTP/SSE transport (Streamable HTTP + legacy SSE)
-│       ├── session.ts              # Session management (stateful + stateless modes)
-│       ├── middleware.ts            # Security headers, rate limiting, CORS, body parsing, DNS rebinding guard
-│       ├── oauth.ts                # OAuth 2.1 integration + simple bearer auth middleware
-│       ├── type-adapters.ts        # Hono→Express type bridges
-│       ├── types.ts                # HTTP transport types
-│       └── index.ts                # Barrel
-│
-├── codemode/                       # Code Mode sandbox (secure JS execution)
-│   ├── sandbox.ts                  # SandboxPool lifecycle manager
-│   ├── sandbox-factory.ts          # Sandbox creation factory
-│   ├── auto-return.ts              # Last-expression auto-return transform (IIFE helper)
-│   ├── worker-sandbox.ts           # Worker thread sandbox (MessagePort RPC bridge)
-│   ├── worker-script.ts            # Worker thread entry point (runs inside vm)
-│   ├── api.ts                      # sqlite.* API bridge (exposes tools to sandbox)
-│   ├── api-constants.ts            # API bridge constants and JSON-RPC codes
-│   ├── security.ts                 # Code validation (blocked patterns, injection prevention)
-│   ├── types.ts                    # Sandbox TypeScript types
-│   └── index.ts                    # Barrel
-│
-├── adapters/
-│   ├── database-adapter.ts         # Abstract DatabaseAdapter base class
-│   ├── query-validation.ts         # Shared query validation (SELECT vs write detection)
-│   ├── sqlite-helpers.ts           # Shared SQLite helper utilities
-│   │
-│   ├── sqlite/                     # ── WASM adapter (sql.js) ──
-│   │   ├── sqlite-adapter.ts       # SqliteAdapter class (extends DatabaseAdapter)
-│   │   ├── query-executor.ts       # WASM query execution
-│   │   ├── schema-manager.ts       # Schema cache + metadata (TTL-based)
-│   │   ├── json-utils.ts           # JSON column detection and normalization
-│   │   ├── types.ts                # WASM-specific Zod schemas + TS types
-│   │   ├── resources.ts            # 10 data MCP resources (schema, tables, indexes, compile_options, etc.)
-│   │   ├── index.ts                # Barrel
-│   │   ├── output-schemas/         # Zod outputSchema definitions per group (see § below)
-│   │   ├── prompts/                # 10 MCP prompts (see § below)
-│   │   └── tools/                  # Tool handler files (see § Handler Map below)
-│   │       ├── column-validation.ts  # validateColumnExists() + validateTableExists() — used by geo, stats, text, FTS, window
-│   │       └── ...                   # Group subdirectories below
-│   │
-│   └── sqlite-native/              # ── Native adapter (better-sqlite3) ──
-│       ├── native-sqlite-adapter.ts     # NativeSqliteAdapter class (extends DatabaseAdapter)
-│       ├── native-query-executor.ts     # Native query execution
-│       ├── extensions.ts               # Extension loader (CSV, SpatiaLite) — uses findProjectRoot()
-│       ├── transaction-methods.ts      # Transaction state management
-│       ├── registration/               # Extracted tool/resource registration logic
-│       │   └── index.ts
-│       ├── index.ts                    # Barrel
-│       └── tools/                      # Native-only tool handlers (see § below)
-```
-
----
-
-## Handler → Tool Mapping
-
-Each file below registers tools with `group` labels. Native-only tools are marked.
-
-### WASM Handlers (`src/adapters/sqlite/tools/`)
-
-| Group             | Handler File(s)                           | Tools | Key Exports                                                                                                                   |
-| ----------------- | ----------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------- |
-| **codemode**      | `codemode.ts`                             | 1     | `sqlite_execute_code`                                                                                                         |
-| **core**          | `core/queries.ts`                         | 2     | `sqlite_read_query`, `sqlite_write_query`                                                                                     |
-|                   | `core/convenience.ts`                     | 5     | `sqlite_upsert`, `sqlite_batch_insert`, `sqlite_count`, `sqlite_exists`, `sqlite_truncate`                                    |
-|                   | `core/tables.ts`                          | 4     | `create_table`, `list_tables`, `describe_table`, `drop_table`                                                                 |
-|                   | `core/indexes.ts`                         | 3     | `get_indexes`, `create_index`, `drop_index`                                                                                   |
-| **json**          | `json-operations/crud.ts`                 | 3     | `json_insert`, `json_update`, `json_select`                                                                                   |
-|                   | `json-operations/query.ts`                | 4     | `json_query`, `json_validate_path`, `json_merge`, `json_analyze_schema`                                                       |
-|                   | `json-operations/transform.ts`            | 4     | `json_valid`, `json_extract`, `json_set`, `json_remove`                                                                       |
-|                   | `json-helpers/read.ts`                    | 7     | `json_type`, `json_array_length`, `json_keys`, `json_each`, `json_pretty`, `json_storage_info`, `json_group_array`            |
-|                   | `json-helpers/write.ts`                   | 5     | `json_array_append`, `json_group_object`, `jsonb_convert`, `json_normalize_column`, `create_json_collection`                  |
-| **text**          | `text/regex.ts`                           | 2     | `regex_extract`, `regex_match`                                                                                                |
-|                   | `text/formatting.ts`                      | 6     | `text_split`, `text_concat`, `text_replace`, `text_trim`, `text_case`, `text_substring`                                       |
-|                   | `text/search.ts`                          | 3     | `fuzzy_match`, `phonetic_match`, `advanced_search`                                                                            |
-|                   | `text/validate.ts`                        | 2     | `text_normalize`, `text_validate`                                                                                             |
-|                   | `text/sentiment.ts`                       | 1     | `text_sentiment`                                                                                                              |
-| **text** (FTS5)   | `fts.ts`                                  | 5     | `fts_create`, `fts_search`, `fts_rebuild`, `fts_match_info`, `fts_headline`                                                   |
-| **stats**         | `stats/basic.ts`                          | 7     | `stats_basic`, `stats_count`, `stats_group_by`, `stats_histogram`, `stats_percentile`, `stats_correlation`, `stats_top_n`     |
-|                   | `stats/advanced.ts`                       | 6     | `stats_distinct`, `stats_summary`, `stats_frequency`, `stats_outliers`, `stats_regression`, `stats_hypothesis`                |
-|                   | `stats/anomaly-detection.ts`              | 2     | `stats_detect_anomalies`, `stats_detect_bloat`                                                                                |
-|                   | `stats/schema-risks.ts`                   | 1     | `stats_detect_schema_risks`                                                                                                   |
-| **vector**        | `vector/storage.ts`                       | 4     | `vector_create_table`, `vector_store`, `vector_batch_store`, `vector_delete`                                                  |
-|                   | `vector/search.ts`                        | 2     | `vector_search`, `vector_get`                                                                                                 |
-|                   | `vector/metadata.ts`                      | 5     | `vector_count`, `vector_stats`, `vector_dimensions`, `vector_normalize`, `vector_distance`                                    |
-| **geo**           | `geo.ts`                                  | 4     | `geo_distance`, `geo_nearby`, `geo_bounding_box`, `geo_cluster`                                                               |
-| **admin**         | `admin/backup/create.ts`                  | 1     | `backup`                                                                                                                      |
-|                   | `admin/backup/restore.ts`                 | 1     | `restore`                                                                                                                     |
-|                   | `admin/backup/analyze.ts`                 | 1     | `analyze`                                                                                                                     |
-|                   | `admin/backup/integrity.ts`               | 1     | `integrity_check`                                                                                                             |
-|                   | `admin/backup/optimize.ts`                | 1     | `optimize`                                                                                                                    |
-|                   | `admin/verify.ts`                         | 2     | `verify_backup`, `index_stats`                                                                                                |
-|                   | `admin/pragma.ts`                         | 6     | `pragma_compile_options`, `pragma_database_list`, `pragma_optimize`, `pragma_settings`, `pragma_table_info`, `append_insight` |
-|                   | `virtual/views.ts`                        | 3     | `create_view`, `list_views`, `drop_view`                                                                                      |
-|                   | `virtual/vtable.ts`                       | 5     | `list_virtual_tables`, `virtual_table_info`, `drop_virtual_table`, `create_csv_table`, `analyze_csv_schema`                   |
-|                   | `virtual/extensions.ts`                   | 2     | `create_rtree_table`, `create_series_table`                                                                                   |
-|                   | `virtual/analysis.ts`                     | 3     | `generate_series`, `dbstat`, `vacuum`                                                                                         |
-| **introspection** | `introspection/graph/tools.ts`            | 3     | `dependency_graph`, `topological_sort`, `cascade_simulator`                                                                   |
-|                   | `introspection/analysis/constraints.ts`   | 1     | `constraint_analysis`                                                                                                         |
-|                   | `introspection/analysis/risks.ts`         | 1     | `migration_risks`                                                                                                             |
-|                   | `introspection/analysis/snapshot.ts`      | 1     | `schema_snapshot`                                                                                                             |
-|                   | `introspection/diagnostics/storage.ts`    | 1     | `storage_analysis`                                                                                                            |
-|                   | `introspection/diagnostics/indexes.ts`    | 1     | `index_audit`                                                                                                                 |
-|                   | `introspection/diagnostics/query-plan.ts` | 1     | `query_plan`                                                                                                                  |
-| **migration**     | `migration/tracking/init.ts`              | 1     | `migration_init`                                                                                                              |
-|                   | `migration/tracking/record.ts`            | 1     | `migration_record`                                                                                                            |
-|                   | `migration/tracking/apply.ts`             | 1     | `migration_apply`                                                                                                             |
-|                   | `migration/tracking/rollback.ts`          | 1     | `migration_rollback`                                                                                                          |
-|                   | `migration/tracking/history.ts`           | 1     | `migration_history`                                                                                                           |
-|                   | `migration/tracking/status.ts`            | 1     | `migration_status`                                                                                                            |
-
-### Native-Only Handlers (`src/adapters/sqlite-native/tools/`)
-
-| Group                | Handler File             | Tools | Notes                                                                                                              |
-| -------------------- | ------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------ |
-| **stats** (window)   | `window.ts`              | 6     | `window_row_number`, `window_rank`, `window_lag_lead`, `window_running_total`, `window_moving_avg`, `window_ntile` |
-| **transactions**     | `transactions.ts`        | 8     | `transaction_begin/status/commit/rollback/savepoint/release/rollback_to/execute`                                   |
-| **geo** (SpatiaLite) | `spatialite/tools.ts`    | 4     | `spatialite_load/create_table/query/index`                                                                         |
-|                      | `spatialite/analysis.ts` | 3     | `spatialite_analyze/transform/import`                                                                              |
-
-### Utility Files (no tools, shared helpers)
-
-Files that provide shared logic but do **not** register tools:
-
-| File                             | Purpose                                                                                                                                                                    |
-| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `core/tables.ts`                 | Also exports `isSpatialiteSystemTable()`, `isSpatialiteSystemView()`, `isSpatialiteSystemIndex()` — used by core + introspection tools for `excludeSystemTables` filtering |
-| `column-validation.ts`           | `validateColumnExists()`, `validateTableExists()` — used by geo, stats, text, FTS, window                                                                                  |
-| `json-operations/helpers.ts`     | JSON path/value normalization                                                                                                                                              |
-| `json-helpers/helpers.ts`        | JSON helper utilities                                                                                                                                                      |
-| `text/helpers.ts`                | Text processing shared logic                                                                                                                                               |
-| `stats/helpers.ts`               | Stats calculation utilities                                                                                                                                                |
-| `stats/inference.ts`             | Statistical type inference engine                                                                                                                                          |
-| `stats/math-helpers.ts`          | Math utility functions (median, std dev)                                                                                                                                   |
-| `vector/helpers.ts`              | Vector math utilities                                                                                                                                                      |
-| `vector/schemas.ts`              | Zod schemas for vector tools                                                                                                                                               |
-| `vector/tools.ts`                | Vector tool registration barrel                                                                                                                                            |
-| `admin/helpers.ts`               | Admin tool shared utilities                                                                                                                                                |
-| `migration/schemas.ts`           | Zod input schemas for migration tools (re-exports output schemas from `output-schemas/migration.ts`)                                                                       |
-| `virtual/helpers.ts`             | Virtual table helper utilities                                                                                                                                             |
-| `introspection/graph/helpers.ts` | FK graph traversal helpers                                                                                                                                                 |
-| `spatialite/schemas.ts` (native) | Zod schemas for SpatiaLite tools                                                                                                                                           |
-| `spatialite/loader.ts` (native)  | SpatiaLite extension loader + path resolution                                                                                                                              |
-
----
-
-## Output Schemas (`src/adapters/sqlite/output-schemas/`)
-
-Zod schemas that define the `outputSchema` for MCP tool responses. All output schemas are centralized here with named exports — **zero inline definitions** remain across all tool groups.
-
-| File               | Groups Covered                                                                                                                                                                                 |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `common.ts`        | Shared base schemas (e.g., success/error shape)                                                                                                                                                |
-| `error-mixin.ts`   | `ErrorFieldsMixin` — 6 optional error fields merged into all output schemas                                                                                                                    |
-| `core.ts`          | Core group output schemas                                                                                                                                                                      |
-| `json.ts`          | JSON group output schemas                                                                                                                                                                      |
-| `text.ts`          | Text group output schemas (incl. `TextConcatOutputSchema`, `TextTrimOutputSchema`, `TextCaseOutputSchema`, `TextSubstringOutputSchema`, `AdvancedSearchOutputSchema`)                          |
-| `fts.ts`           | FTS5 output schemas                                                                                                                                                                            |
-| `stats.ts`         | Stats group output schemas (incl. `StatsHypothesisOutputSchema`)                                                                                                                               |
-| `vector.ts`        | Vector group output schemas                                                                                                                                                                    |
-| `admin.ts`         | Admin group output schemas (incl. `AppendInsightOutputSchema`, `DbstatOutputSchema`)                                                                                                           |
-| `geo.ts`           | Geo group output schemas                                                                                                                                                                       |
-| `introspection.ts` | Introspection group output schemas (9 schemas: DependencyGraph, TopologicalSort, CascadeSimulator, SchemaSnapshot, ConstraintAnalysis, MigrationRisks, StorageAnalysis, IndexAudit, QueryPlan) |
-| `migration.ts`     | Migration group output schemas (7 schemas: MigrationInit, MigrationRecord, MigrationApply, MigrationRollback, MigrationHistory, MigrationStatus + MigrationRecordEntry)                        |
-| `virtual.ts`       | Virtual table output schemas (7 schemas: ListVirtualTables, VirtualTableInfo, DropVirtualTable, CreateCsvTable, AnalyzeCsvSchema, CreateRtreeTable, CreateSeriesTable)                         |
-| `native.ts`        | Native-only output schemas (transactions — 8 schemas, window functions — 6 schemas)                                                                                                            |
-| `spatialite.ts`    | SpatiaLite output schemas (7 tools — native only)                                                                                                                                              |
-| `server.ts`        | Type aliases for core output schemas (built-in tools use `content` pattern, not `structuredContent`)                                                                                           |
-| `index.ts`         | Barrel re-export                                                                                                                                                                               |
-
----
-
-## Prompts (`src/adapters/sqlite/prompts/`)
-
-| File          | Prompts                                                                       |
-| ------------- | ----------------------------------------------------------------------------- |
-| `analysis.ts` | `sqlite_data_analysis`, `sqlite_summarize_table`, `sqlite_demo`               |
-| `query.ts`    | `sqlite_query_builder`, `sqlite_debug_query`, `sqlite_hybrid_search_workflow` |
-| `schema.ts`   | `sqlite_explain_schema`, `sqlite_documentation`, `sqlite_migration`           |
-| `index.ts`    | Barrel + `sqlite_optimization`                                                |
-
-Prompts with required arguments expose typed `argsSchema` via `prompts/list`. All-optional and zero-arg prompts correctly omit `argsSchema`.
-
----
-
-## Error Class Hierarchy
-
-All errors extend `DbMcpError` (defined in `src/utils/errors/base.ts`). Every tool returns structured `{success: false, error, code, category, suggestion, recoverable}` via `formatHandlerError()` — never raw MCP exceptions.
-
-The `DbMcpError` constructor auto-refines generic codes (`DB_QUERY_FAILED`, `DB_WRITE_FAILED`, `QUERY_ERROR`, `RESOURCE_ERROR`, `UNKNOWN_ERROR`) to more specific codes (e.g., `TABLE_NOT_FOUND`, `COLUMN_NOT_FOUND`, `VIEW_NOT_FOUND`, `FILE_NOT_FOUND`, `MALFORMED_JSON`, `TRANSACTION_CONFLICT`) when the error message matches a suggestion pattern.
-
-```
-DbMcpError (base.ts)
-├── ValidationError              code: VALIDATION_ERROR      category: validation
-├── ConnectionError              code: CONNECTION_ERROR       category: connection      recoverable: true
-├── QueryError                   code: QUERY_ERROR            category: query            accepts: sql option
-├── PermissionError              code: PERMISSION_ERROR       category: permission
-├── ResourceNotFoundError        code: RESOURCE_NOT_FOUND     category: resource         accepts: resourceType, resourceName
-├── ConfigurationError           code: CONFIG_ERROR           category: config
-├── InternalError                code: INTERNAL_ERROR         category: internal
-├── AuthenticationError          code: AUTHENTICATION_ERROR   category: authentication
-├── AuthorizationError           code: AUTHORIZATION_ERROR    category: authorization
-├── TransactionError             code: TRANSACTION_ERROR      category: query            recoverable: true
-└── ExtensionNotAvailableError   code: EXTENSION_MISSING      category: config           accepts: extensionName
-```
-
-**Usage pattern** — all tool handlers:
-
-```typescript
-import { ValidationError } from "../../utils/errors/index.js";
-import { formatHandlerError } from "../../utils/errors/index.js";
-
-// Throw typed errors:
-throw new ValidationError("Table name required", "TABLE_NAME_REQUIRED", {
-  suggestion: "Provide a valid table name",
-});
-
-// Catch at handler boundary:
-catch (error) {
-  return formatHandlerError(error);
-}
-```
-
-**Error suggestions** — `src/utils/errors/suggestions.ts` provides:
-
-- `suggestTableName(input, existingTables)` — fuzzy-matches typos
-- `suggestColumnName(input, existingColumns)` — fuzzy-matches columns
-- `suggestToolName(input)` — suggests similar tool names
-- Pattern-based refinement: `TABLE_NOT_FOUND`, `COLUMN_NOT_FOUND`, `VIEW_NOT_FOUND`, `FILE_NOT_FOUND`, `MALFORMED_JSON`, `TRANSACTION_CONFLICT`, `DUPLICATE_MIGRATION`, `DUPLICATE_VERSION`, `ALREADY_ROLLED_BACK`, `DIMENSION_MISMATCH`, `VECTOR_NOT_FOUND`
-
----
-
-## Key Constants & Config
-
-| What                               | Where                                  | Notes                                                                                                         |
-| ---------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| Server instructions (agent prompt) | `src/constants/server-instructions.ts` | Generated: slim `INSTRUCTIONS` (~680 chars) + `HELP_CONTENT` map. Source: `server-instructions/*.md`          |
-| Tool group arrays                  | `src/filtering/tool-constants.ts`      | `TOOL_GROUPS` map, `META_GROUPS` shortcuts                                                                    |
-| Tool filter logic                  | `src/filtering/tool-filter.ts`         | `ToolFilter` class                                                                                            |
-| JSON-RPC constants                 | `src/codemode/api-constants.ts`        | Error codes, method names for sandbox RPC                                                                     |
-| Logger error codes                 | `src/utils/logger/error-codes.ts`      | Module-prefixed codes (`DB_`, `AUTH_`, etc.)                                                                  |
-| Version SSoT                       | `src/version.ts`                       | Reads from `package.json` at runtime. Both adapters `import { VERSION }` — **never hardcode version strings** |
-
----
-
-## Architecture Patterns (Quick Reference)
-
-| Pattern                 | Description                                                                                                                                                                                                                                                                                |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Structured Errors**   | Every tool returns `{success: false, error, code, category, suggestion, recoverable}` — never raw exceptions. Uses `formatHandlerError()`.                                                                                                                                                 |
-| **Adapter Pattern**     | `DatabaseAdapter` (abstract) → `SqliteAdapter` (WASM) / `NativeSqliteAdapter` (Native). Both share tool handler files from `sqlite/tools/`.                                                                                                                                                |
-| **Schema Cache**        | `SchemaManager` caches table/column metadata with configurable TTL. Auto-invalidates on DDL ops.                                                                                                                                                                                           |
-| **Code Mode Bridge**    | `sqlite.*` API in worker thread communicates via MessagePort RPC to main thread tool handlers. All 9 groups exposed (`core`, `json`, `text`, `stats`, `vector`, `geo`, `admin`, `introspection`, `migration`).                                                                             |
-| **Tool Filtering**      | `ToolFilter` parses `--tool-filter` string → whitelist/blacklist of tool names. `codemode` auto-injected unless excluded. Help resources filtered to match enabled groups.                                                                                                                 |
-| **Output Schemas**      | All Zod output schemas live in `output-schemas/` with named exports — **never inline** in handler files. Handlers import from `../../output-schemas/index.js`. All schemas extend `ErrorFieldsMixin.shape`. Domain-specific fields are optional so error responses pass validation.        |
-| **Input Coercion**      | All numeric params use `z.preprocess(coerceNumber, ...)` so wrong-type strings fall to defaults. Required enums use `z.string()` + handler validation. Optional enums use `coerceEnumValues()` factory. Array params coerce non-arrays to empty arrays for SDK `.partial()` compatibility. |
-| **Readonly Guard**      | Code mode `isWriteTool()` uses fail-closed logic (`readOnlyHint === true`) — tools without annotations are blocked in readonly mode.                                                                                                                                                       |
-| **Parameter Aliases**   | Core tools support backward-compatible aliases (`tableName`→`table`, `sql`→`query`, `name`→`indexName`) via `resolveAliases()` in handlers. Canonical names take precedence.                                                                                                               |
-| **Barrel Re-exports**   | Every directory has `index.ts` barrel. Import from `./module/index.js` (with `.js` extension for ESM).                                                                                                                                                                                     |
-| **Module Logger**       | `createModuleLogger("moduleName")` → structured logs with `[module]` prefix.                                                                                                                                                                                                               |
-| **Help Resources**      | Pull-based `sqlite://help` + `sqlite://help/{group}` replace the old push-based `--instruction-level` flag. Per-group `.md` sources in `server-instructions/`.                                                                                                                             |
-| **DNS Rebinding Guard** | `localhostHostValidation()` middleware from MCP SDK on HTTP transport.                                                                                                                                                                                                                     |
-
----
-
-## Import Path Conventions
-
-- All imports use **`.js` extension** (ESM requirement): `import { x } from "./foo/index.js"`
-- After splitting `foo.ts` → `foo/` directory: update imports from `./foo.js` → `./foo/index.js`
-- Error classes can be imported from either:
-  - `../../utils/errors/index.js` (direct)
-  - `../../types/index.js` (re-exported subset: `DbMcpError`, `ValidationError`, `ConnectionError`, `QueryError`, `AuthenticationError`, `AuthorizationError`)
-
----
-
-## Test Infrastructure
-
-| File / Directory                             | Purpose                                                                                                            |
-| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `test-server/README.md`                      | Agent testing orchestration doc                                                                                    |
-| `test-server/test-database.sql`              | Seed DDL+DML (10 tables, ~400 rows)                                                                                |
-| `test-server/reset-database.ps1`             | Reset script — drops + re-seeds `test.db`                                                                          |
-| `test-server/tool-reference.md`              | Complete 151/125 tool inventory with descriptions                                                                  |
-| `test-server/test-preflight.md`              | Pre-test verification checklist                                                                                    |
-| `test-server/test-tool-groups/`              | 10 self-contained test prompts — one per tool group. Direct calls only.                                            |
-| `test-server/test-codemode/`                 | 10 self-contained test prompts — one per tool group. Code Mode execution only.                                     |
-| `test-server/test-advanced/`                 | 10 self-contained advanced stress test prompts — one per tool group.                                               |
-| `test-server/test-resources.md`              | MCP resource verification prompts                                                                                  |
-| `test-server/test-prompts.md`                | MCP prompt verification prompts                                                                                    |
-| `test-server/test-agent-experience.md`       | 20 open-ended scenarios — validates help resource sufficiency                                                      |
-| `test-server/test-help-resources.mjs`        | Integration test — slim instructions + help resource filtering                                                     |
-| `test-server/test-tool-annotations.mjs`      | Integration test — openWorldHint annotation verification                                                           |
-| `test-server/fixtures/`                      | Test fixture files (e.g., `sample.csv`)                                                                            |
-| `tests/adapters/tool-annotations.test.ts`    | Vitest invariant — every tool has `annotations` with explicit `readOnlyHint`, per-group checks, title validation   |
-| `tests/adapters/tool-output-schemas.test.ts` | Vitest invariant — every tool has `outputSchema`, error response acceptance, centralized schema wiring, no orphans |
-| `tests/`                                     | Vitest unit tests (per-module)                                                                                     |
-| `tests/e2e/`                                 | Playwright E2E tests (~50 spec files, ~300+ tests) — HTTP/SSE transport parity                                     |
-| `benchmarks/`                                | Vitest bench performance benchmarks                                                                                |
-
-### E2E Spec Files (`tests/e2e/`)
-
-| Spec File                                      | Coverage                                                                                                                                                   |
-| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `zod-sweep.spec.ts`                            | Zod validation sweep — every WASM tool called with `{}`                                                                                                    |
-| `zod-sweep-native.spec.ts`                     | Zod validation sweep — 20 native-only tools (FTS5, window, transactions, SpatiaLite)                                                                       |
-| `errors.spec.ts`                               | Basic error path tests                                                                                                                                     |
-| `errors-extended.spec.ts`                      | Per-group domain error paths                                                                                                                               |
-| `errors-native.spec.ts`                        | Native-only error paths (20 tests)                                                                                                                         |
-| `codemode.spec.ts`                             | Sandbox lifecycle, security, readonly, workflows, window function smoke tests, API discoverability                                                         |
-| `codemode-groups.spec.ts`                      | All 9 groups via `sqlite.*` API                                                                                                                            |
-| `codemode-introspection.spec.ts`               | Introspection code-mode-only params (~16 tests)                                                                                                            |
-| `numeric-coercion.spec.ts`                     | String-typed numeric param coercion                                                                                                                        |
-| `numeric-coercion-native.spec.ts`              | Native-only numeric coercion (8 tests)                                                                                                                     |
-| `boundary.spec.ts`                             | Empty tables, NULLs, idempotency, edge cases, vector empty table edges                                                                                     |
-| `help-resources.spec.ts`                       | Root + 8 group help resources listed, readable, non-empty                                                                                                  |
-| `aliases.spec.ts`                              | Backward-compatible parameter aliases (14 tests)                                                                                                           |
-| `resources.spec.ts`                            | MCP resource verification (schema, tables, indexes, health, meta, insights, help)                                                                          |
-| `prompts.spec.ts`                              | MCP prompt verification (argsSchema, required args, content assertions)                                                                                    |
-| `transactions-nested.spec.ts`                  | Nested savepoint data correctness (~4 tests)                                                                                                               |
-| `integration-workflows.spec.ts`                | Cross-group pipelines (~8 tests)                                                                                                                           |
-| `payloads-*.spec.ts`                           | Per-group payload correctness (core, json, text, fts, stats, vector, geo, admin, introspection, migration, spatialite, transactions, window, virtual, csv) |
-| `auth.spec.ts`, `oauth-discovery.spec.ts`      | OAuth 2.1 and RFC 9728 metadata                                                                                                                            |
-| `health.spec.ts`                               | Health endpoint verification                                                                                                                               |
-| `security.spec.ts`                             | Security header assertions, HSTS                                                                                                                           |
-| `sessions.spec.ts`, `session-advanced.spec.ts` | Session management (cross-protocol, sequential isolation, post-DELETE)                                                                                     |
-| `streaming.spec.ts`, `streamable-http.spec.ts` | Raw SSE streaming verification                                                                                                                             |
-| `rate-limiting.spec.ts`                        | 429 burst, Retry-After header, health exemption                                                                                                            |
-| `protocols.spec.ts`                            | Transport protocol tests                                                                                                                                   |
-| `stateless.spec.ts`                            | Stateless mode tests                                                                                                                                       |
-| `tools.spec.ts`                                | Core tool listing and invocation                                                                                                                           |
-| `native.spec.ts`, `wasm.spec.ts`               | Backend-specific tests                                                                                                                                     |

package/test-server/fixtures/sample.csv

@@ -1,6 +0,0 @@
-id,name,category,price,in_stock
-1,Widget A,hardware,9.99,true
-2,Widget B,hardware,14.50,true
-3,Gadget X,electronics,29.99,false
-4,Gadget Y,electronics,49.99,true
-5,Tool Z,accessories,5.25,true