Publicar el índice curado y evitar que el Hub acumule ficheros huérfanos

Al publicar el índice curado (6772 → 6201 fragmentos) aparecieron dos fallos en
la ruta de publicación:

- `upload_folder` no borraba lo que ya no existe en local. LanceDB versiona por
ficheros, así que al compactar desaparecen los datos viejos y el remoto se los
quedaba: el repo tenía 2 ficheros de datos y 2 índices FTS huérfanos, 73 MB
para servir 33 MB — que además se hornean en la imagen. Ahora el remoto es un
espejo del local (`delete_patterns="*"`).

- `manifest.json` lo escribe la ingesta, pero `curar_indice.py` cambia el número
de filas después. Publicaba un recuento desfasado sin romper nada visible, que
es lo peligroso: el mensaje de commit del Hub y `fetch-index` anunciaban 6772
fragmentos sobre un índice de 6201. `curar_indice.py` lo reconcilia y
`publish-index` aborta si no cuadra.

Verificado descargando el índice publicado en limpio: 13 ficheros, 33 MB, los 51
tests de alcance en verde y la eval de recuperación en 0.814/0.941/0.912.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

scripts/curar_indice.py

@@ -19,6 +19,7 @@ demás máquinas se lo lleven; si no, sólo queda arreglado en local.
 from __future__ import annotations
 
 import argparse
+import json
 import sys
 from collections import Counter
 from pathlib import Path
@@ -35,6 +36,20 @@ from app.rag.alcance_corpus import (  # noqa: E402
 )
 
 
+def actualizar_manifiesto(ruta: Path, n_fragmentos: int) -> None:
+    """Deja `manifest.json` de acuerdo con lo que hay realmente en la tabla."""
+    destino = ruta / "manifest.json"
+    if not destino.exists():
+        print("⚠ Sin manifest.json: no se puede dejar constancia del recuento.")
+        return
+    datos = json.loads(destino.read_text(encoding="utf-8"))
+    antes = datos.get("n_fragmentos")
+    datos["n_fragmentos"] = n_fragmentos
+    datos["curado"] = "data/rag_alcance.json"
+    destino.write_text(json.dumps(datos, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    print(f"manifest.json actualizado: n_fragmentos {antes} → {n_fragmentos}")
+
+
 def main() -> int:
     parser = argparse.ArgumentParser()
     parser.add_argument(
@@ -83,7 +98,19 @@ def main() -> int:
     print(f"  cambian de especie:                     {reetiquetados}")
     print(f"  especies tras curar:                    {dict(Counter(nueva))}")
 
+    manifiesto = ruta / "manifest.json"
+    if manifiesto.exists():
+        declarado = json.loads(manifiesto.read_text(encoding="utf-8")).get("n_fragmentos")
+        if declarado != len(df_quedan):
+            print(f"\n⚠ manifest.json declara {declarado} fragmentos y quedarían {len(df_quedan)}.")
+
     if not fuera.any() and not reetiquetados:
+        if manifiesto.exists() and declarado != len(df_quedan):
+            if not args.aplicar:
+                print("Repite con --aplicar para corregir sólo el manifiesto.")
+                return 0
+            actualizar_manifiesto(ruta, len(df_quedan))
+            return 0
         print("\nNada que hacer.")
         return 0
     if not args.aplicar:
@@ -111,6 +138,11 @@ def main() -> int:
     tamano = sum(f.stat().st_size for f in ruta.rglob("*") if f.is_file()) / 1e6
     print(f"Versiones antiguas purgadas. Tamaño en disco: {tamano:.0f} MB")
 
+    # El manifiesto lo escribe la ingesta y aquí acaba de cambiar el número de fragmentos. Si no
+    # se actualiza, miente: `fetch-index` lo imprime y `publish-index` lo usa como mensaje de
+    # commit, así que el Hub anunciaría un recuento que no es el del índice que sirve.
+    actualizar_manifiesto(ruta, len(df_quedan))
+
     print(f"\n✅ {total} → {len(df_quedan)} fragmentos. Recuerda `make publish-index`.")
     return 0
 

scripts/hub.py

@@ -43,11 +43,35 @@ def _asegurar_repo(api: HfApi, repo_id: str) -> None:
         )
 
 
+def _comprobar_manifiesto(manifiesto: dict) -> None:
+    """Aborta si `manifest.json` no coincide con la tabla que se va a publicar.
+
+    El manifiesto lo escribe la ingesta, pero `curar_indice.py` cambia el número de filas
+    después. Publicar uno desfasado no rompe nada visible —y por eso es peligroso—: el mensaje
+    de commit del Hub y lo que imprime `fetch-index` anuncian un recuento que no es el del
+    índice que sirve, y a partir de ahí nadie sabe qué hay publicado.
+    """
+    try:
+        import lancedb
+    except ImportError:
+        print("AVISO: sin lancedb no se puede verificar el manifiesto; se publica a ciegas.")
+        return
+    tabla = lancedb.connect(str(DIR_INDICE)).open_table("literatura")
+    reales = tabla.count_rows()
+    declarados = manifiesto.get("n_fragmentos")
+    if declarados != reales:
+        sys.exit(
+            f"ABORTADO: manifest.json declara {declarados} fragmentos y la tabla tiene {reales}.\n"
+            f"Ejecuta 'make curar-indice ARGS=--aplicar' para reconciliarlo antes de publicar."
+        )
+
+
 def publicar_indice() -> None:
     if not DIR_INDICE.exists():
         sys.exit(f"ERROR: no existe {DIR_INDICE}. Ejecuta 'make ingest' primero.")
     manifiesto = json.loads((DIR_INDICE / "manifest.json").read_text(encoding="utf-8"))
     hash_corpus = manifiesto.get("hash_corpus", "desconocido")
+    _comprobar_manifiesto(manifiesto)
     api = HfApi()
     _asegurar_repo(api, REPO_INDICE)
     api.upload_folder(
@@ -55,6 +79,11 @@ def publicar_indice() -> None:
         repo_type="dataset",
         folder_path=str(DIR_INDICE),
         commit_message=f"Índice RAG · corpus {hash_corpus} · {manifiesto.get('n_fragmentos')} fragmentos",
+        # El remoto debe ser un ESPEJO del local, no una acumulación. LanceDB versiona por
+        # ficheros: al compactar desaparecen los datos viejos, y sin esto se quedarían en el Hub
+        # para siempre. Medido: el repo tenía 2 ficheros de datos y 2 índices FTS huérfanos de
+        # versiones anteriores — 73 MB para servir 33 MB, que además se hornean en la imagen.
+        delete_patterns="*",
     )
     print(f"OK: índice publicado en {REPO_INDICE} (corpus {hash_corpus})")