Evaluación Understand-Anything vs Bibliotecario propio · NO adoptar, cherry-pick parcial

ADR 2026-05-22: Understand-Anything vs Bibliotecario — cherry-pick scope reducido

Contexto

El proyecto Understand-Anything propone 8 tipos de edges adicionales para enriquecer el grafo de conocimiento estático del Bibliotecario. La pregunta era: ¿importar el proyecto completo o hacer cherry-pick selectivo?

El análisis previo a esta decisión evaluó cada edge type propuesto frente a dos criterios:

AST-friendly: detectable con parsing Python puro, sin dependencias externas.
Valor inmediato: el Oráculo (bib_ask / bib_impact_query) puede usarlo en queries reales sobre el corpus de CreaRack Pro.

Decisión

Cherry-pick de 3 edge types (scope reducido) implementados directamente en scripts/bib_ast.py. No se incorpora Understand-Anything como dependencia ni submódulo.

Edge types incluidos

Edge type	Mecanismo AST	Justificación
`reads_from`	`<Model>.objects.<READ>()` en `visit_Call`	Directo, sin ambigüedad, alto valor para queries de impacto
`writes_to`	`<Model>.objects.<WRITE>()` en `visit_Call`	Idem, distingue lecturas de mutaciones
`triggers`	`@receiver(signal, sender=Model)` en `_visit_function`	Conecta signal handlers a sus modelos; útil para trazabilidad de efectos secundarios

Edge types descartados (en esta iteración)

Edge type	Motivo de descarte
`subscribes` / `publishes`	Requieren parsers no-Python (Dockerfile, docker-compose, variables de entorno)
`middleware`	Sensible a configuración runtime de Django; no inferible sólo del AST
`deploys`	Dominio de infraestructura, fuera del scope del AST Python
`serves`	Depende de Django Channels o Huey — frameworks externos no siempre presentes

Los 5 tipos descartados quedan como candidatos para iteración futura si emergen necesidades concretas en queries del Oráculo.

Consecuencias

Positivas

+660 edges nuevos sobre corpus de 340 archivos (+10 % de enriquecimiento).
0 falsos positivos detectados en muestra manual.
Riesgo bajo: solo añade edges, no modifica/elimina nodos ni edges existentes.
Sin nuevas dependencias en requirements.txt.
Si el cron falla, el grafo queda obsoleto, no corrupto.

Negativas / Limitaciones

Receivers de Django signals sin sender explícito no generan edge (señales globales no trazadas).
Los 5 edge types descartados siguen siendo puntos ciegos del grafo para infraestructura y mensajería.
La resolución de alias de import es best-effort: si _resolve_name no resuelve, el edge no se emite.

Implementación

Commit: 544548bbf243bcc48b546fcef435645938744e6d
Archivo: scripts/bib_ast.py — constantes ORM_READ_METHODS, ORM_WRITE_METHODS, SIGNAL_DECORATOR_NAMES + lógica en visit_Call y _visit_function.
Backup pre-cambio: /opt/biblioteca-crons-bak-20260522-pre-cherrypick/
Revert: git revert 544548b + rsync desde backup si el cron Hetzner falla.

Alternativas consideradas

Importar Understand-Anything completo — descartado por scope excesivo, dependencias externas y riesgo de romper el pipeline existente.
No hacer nada — descartado: el grafo carecía de trazabilidad ORM, lo que limitaba la utilidad de bib_impact_query para cambios en modelos.
Implementar los 8 edge types — descartado: los 5 no-AST requieren parsers adicionales que elevan la complejidad de mantenimiento desproporcionadamente.

Estado

Aceptada — implementada en s79, 2026-05-22 · commit 544548b.

Véase también

[[entity—biblioteca—script—bib-ast]]