Gateway Module — `search/`

1. Purpose

The unified full-text search surface (D265). A single GET endpoint that runs the same FTS5 query against all three keyword indexes — psychic_fts, memory_fts, agent_memory_fts — in parallel via SQL, merges the results by BM25 rank, and returns a flat unified result set with a human-readable preview. It backs the session_search MCP tool used for cross-session recall. Unlike context/ (semantic RAG fanout with weighting), search/ is pure keyword BM25 with no embeddings, no scoring adaptation, and no vector search — a fast literal lookup.

2. File Inventory

3. Public API Surface

REST Endpoints

Mounted at /api/search. Auth per AK-415: GET → Bearer.

SearchResult = {id, source:'psychic_cache'|'memory'|'agent_memory', content, content_preview, context_type?, mission_id?, agent_name?, created_at, bm25_rank}.

MCP Tools

No raw twin — session_search is a read-only GET (staleness-immune bug class applies to write-path tools only).

4. Internal API

None exported for cross-module use. createSearchRouter(db) is the sole export, imported by server/index.ts. makePreview and the row-shape interfaces are module-private. SearchResult here is a distinct type from context/types SearchResult (different fields) — same name, different module namespace.

5. Background Services

None. Stateless request/response. No timers, queues, or daemons. Reads the three FTS5 virtual tables owned by memory/db.ts; writes nothing.

6. Data Contracts

No Zod schemas — validation is imperative:

• q — required, .trim().length > 0, else 400.
• limit — undefined→10; else Number(...) must be finite, integer, >0, clamped to 50; else 400 (AK-362/D1452).
• namespace — optional string; when present, filters the psychic_cache subquery by mission_id only (memory + agent_memory have no mission column).
• FTS query built via shared/search-utils.buildFts5Query (word→quoted-phrase OR expression); empty query short-circuits to {data:[], total:0}.

Reads (no writes): psychic_fts⋈psychic_cache, memory_fts⋈memory_documents, agent_memory_fts⋈agent_memory (joins on document_id/rowid).

7. Dependencies

• Gateway modules consumed: shared/search-utils (buildFts5Query). Reads tables owned by memory (memory_fts/documents), psychic-cache (psychic_fts/cache), agent-memory (agent_memory_fts/agent_memory).
• External libraries: better-sqlite3, express.
• Environment variables: none.

8. Test Coverage

Well-covered for a single-endpoint module; search-utils coverage is shared with psychic-cache/context/vault-index.

9. Known Limitations

• Per-store LIMIT then merge-then-trim — each subquery pulls up to limit rows, they are concatenated (up to 3×limit), sorted by bm25_rank, then sliced to limit. BM25 ranks are not comparable across FTS5 tables (different corpora/tokenisers), so the cross-store merge ordering is approximate, not a true global ranking.
• No pagination — offset is unsupported; only top-limit is retrievable.
• namespace filters psychic only — memory + agent_memory results are always unfiltered even when a namespace is supplied (documented in-code).
• Duplicate type name — SearchResult collides by name with context/types SearchResult; a reader grepping the symbol must disambiguate by module.

10. Change History