---
name: vault_search
kind: function
lang: go
domain: infra
version: "1.0.0"
purity: impure
signature: "func VaultSearch(vaultPath, query string, limit int) ([]VaultSearchHit, error)"
description: "Busca en vault_index.db de un vault usando FTS5 sobre files_fts. Si el query rompe el parser FTS5, hace fallback a LIKE sobre rel_path. Retorna hits con snippet de contexto."
tags: [vault, search, fts5, sqlite, infra, pendiente-usar]
uses_functions: ["vault_index_open_go_infra"]
uses_types: ["vault_file_go_infra"]
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [database/sql, fmt, path/filepath, strings]
params:
  - name: vaultPath
    desc: "ruta absoluta al directorio raiz del vault (puede ser symlink)"
  - name: query
    desc: "termino o frase de busqueda; se escapa automaticamente para FTS5 salvo que ya incluya operadores booleanos o prefijos de columna"
  - name: limit
    desc: "maximo de resultados; si es <= 0 se usa 50"
output: "slice de VaultSearchHit ordenado por rank FTS5 (o mtime DESC en fallback LIKE); slice vacio si no hay resultados"
tested: true
tests:
  - "FTS match devuelve hit con snippet"
  - "query sin resultados retorna slice vacio"
  - "limit se respeta"
  - "query FTS invalida activa fallback LIKE"
  - "limit cero usa 50 por defecto"
test_file_path: "functions/infra/vault_search_test.go"
file_path: "functions/infra/vault_search.go"
---

## Ejemplo

```go
hits, err := infra.VaultSearch("/home/lucas/vaults/turismo_spain", "hoteles", 20)
if err != nil {
    log.Fatal(err)
}
for _, h := range hits {
    fmt.Printf("[%s] %s  %s\n", h.VaultName, h.RelPath, h.Snippet)
}
```

## Notas

`VaultSearchHit` es un struct local definido en este archivo (no en `vault_file.go`)
porque combina campos de `files` + metadatos de contexto de busqueda (Snippet, VaultPath, VaultName).

**FTS5 safety:** el helper `safeFTSQuery` envuelve la query en comillas dobles
cuando no contiene operadores booleanos ni prefijos de columna. Esto evita errores
del parser en tokens como `foo:bar:` o `hello-world`.

**Fallback LIKE:** si el MATCH falla con un error de sintaxis FTS5, se ejecuta
`WHERE rel_path LIKE '%' || query || '%'`. Los hits del fallback tienen `Snippet=""`.

**VaultName:** se deriva del `filepath.Base(filepath.EvalSymlinks(vaultPath))`.
Si `EvalSymlinks` falla (e.g. symlink roto), usa `filepath.Base(vaultPath)`.