---
name: vault_index_write
kind: function
lang: go
domain: infra
version: "1.0.0"
purity: impure
signature: "func VaultIndexWrite(db *sql.DB, files []VaultFile, prune bool) (WriteReport, error)"
description: "Upserta un slice de VaultFile en vault_index.db (tabla files + FTS5 files_fts) dentro de una sola transaccion. Cuenta Inserted/Updated/FTS. Con prune=true elimina filas no presentes en el slice."
tags: [vault, sqlite, index, write, upsert, fts, infra]
uses_functions: []
uses_types: ["vault_file_go_infra"]
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [database/sql, fmt, strings, time]
params:
  - name: db
    desc: "*sql.DB abierto sobre vault_index.db (tipicamente retornado por VaultIndexOpen)"
  - name: files
    desc: "slice de VaultFile a insertar/actualizar; puede ser vacio"
  - name: prune
    desc: "si true, elimina de 'files' todas las filas cuyo rel_path no este en el slice (sincronizacion destructiva)"
output: "WriteReport con conteos Inserted/Updated/Pruned/FTS; error si falla la transaccion"
tested: true
tests:
  - "N archivos nuevos — Inserted=N"
  - "re-escritura con mtime distinto — Updated=N"
  - "prune elimina filas ausentes"
  - "sin prune, filas previas persisten"
  - "FTS5 MATCH funciona tras escritura"
test_file_path: "functions/infra/vault_index_write_test.go"
file_path: "functions/infra/vault_index_write.go"
---

## Ejemplo

```go
db, _ := VaultIndexOpen("/data/vaults/turismo")
defer db.Close()

files, _ := VaultInventoryScan("/data/vaults/turismo", "turismo_v1", "turismo")
report, err := VaultIndexWrite(db, files, true)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("inserted=%d updated=%d pruned=%d fts=%d\n",
    report.Inserted, report.Updated, report.Pruned, report.FTS)
```

## Notas

### WriteReport
Struct local al paquete infra:
```go
type WriteReport struct {
    Inserted int
    Updated  int
    Pruned   int
    FTS      int
}
```

### Estrategia de conteo Inserted vs Updated
Se carga el conjunto de rel_paths existentes en un map antes del loop. Un upsert
se clasifica como Inserted si el rel_path no estaba en el map, Updated si estaba.
Esto evita N+1 SELECTs y es correcto porque la transaccion serializa los cambios.

### FTS5
`files_fts` usa `content=''` (tabla de contenido externo vacio). Para cada archivo
se borra la fila FTS existente y se reinserta con `content_text=''`. Los profilers
posteriores (csv_profiles, knowledge_docs) son responsables de actualizar
`content_text` con texto indexable real.

### Prune
Con `prune=true` se construye un IN clause con los rel_paths del slice. La FK con
`ON DELETE CASCADE` propaga el DELETE a csv_profiles, pdf_extracts y knowledge_docs
automaticamente. Con slice vacio + prune=true se borra todo (DELETE FROM files).

### Escapado SQL
El IN clause se construye escapando las comillas simples en rel_path (duplicandolas).
Evita inyeccion en rutas con apostrofos. Para entornos con rutas controladas
(interior de vaults sin apostrofos) esto es suficiente; para entornos adversariales
usar parametros binding con VALUES multiples via prepared statement.