architect

Revision Summary — FTS5 Design Spec v2

Agent: architect (architect)
Confidence: 38%
Cost: $1.4561
Duration: 4m 17s
Task ID: 3aa2ab5b-1c4b-4753-9aba-0ec4fdb5ad0b

FTS5 design spec revision complete. Here’s a summary of all changes made:

Revision Summary — FTS5 Design Spec v2

HIGH (1)

  1. FTS5 MATCH query syntax injection — Added complete escapeFts5Query() function (Section 4.2) with detailed JSDoc, examples, and trade-off notes. The function strips double quotes, splits on whitespace, and wraps each token in quotes to neutralize FTS5 operators. Applied in searchReports() before MATCH.

MEDIUM (4)

  1. MCP handler try-catch — Section 4.1 now wraps the entire handler in try-catch, consistent with soul_read/soul_write patterns. Returns { isError: true } on failure.
  2. Migration rollback SQL — Added Section 3.4 with complete rollback: DROP 3 triggers + DROP virtual table + PRAGMA user_version reset.
  3. MCP handler formatting — Replaced // ... format and return with complete formatting logic: numbered results with score, snippets, trace, and optional full_result. Empty results return a helpful message.
  4. LIKE fallback performance — Added Section 6.4 with quantified analysis: ~5,000 rows × ~2.2 KB = ~11 MB scan → 15-25 ms. Acceptable for rare edge case. Includes scaling guidance.

LOW (4)

  1. full param in shortQueryFallback — Now destructures full and conditionally adds result AS full_result to the LIKE query.
  2. Database type import — Changed to import type Database from 'better-sqlite3' and parameter type to Database.Database.
  3. NULL LIKE semantics — Added inline comment explaining NULL LIKE '%x%' → NULL behavior. Added COALESCE for SUBSTR snippets to prevent null output.
  4. Snippet tokens for CJK — Increased from 10/20 to 16/32 tokens. Documented rationale: trigram tokens average ~1 char for CJK.

—HANDOFF—
TO: ESCALATE
INTENT: handoff
ARTIFACT_TYPE: report
SUMMARY: FTS5 design spec v2 revision complete — all 9 reviewer issues addressed in soul/agent-reports/architect/fts5-design-spec.md