Escriba drift detector + cron

User value

Resuelve un problema silencioso: los documentos de la Biblioteca envejecen sin que nadie lo note. Un doc creado hace 6 meses puede seguir apareciendo en búsquedas y en supercontexto aunque su contenido ya no refleje el estado real. Esta feature vigila continuamente, calcula score de “desactualización” por doc y lo expone en UI (widget Pulse) y API, permitiendo que agentes y humanos prioricen qué material necesita revisión urgente.

Cómo usarla

Widget Pulse muestra en tiempo real docs con mayor drift score, ordenados por urgencia. Consume GET /api/biblioteca/drift → lista paginada con doc_id, title, drift_score, last_updated, staleness_days.

Recálculo manual vía POST /api/biblioteca/drift-run — ejecuta pipeline completo y devuelve resumen. Protegido, solo agentes autorizados o panel admin.

Cron diario (.github/workflows/drift-cron.yml) dispara drift-run a las 03:00 UTC via schedule: cron. Scores frescos al inicio de cada jornada sin intervención manual.

Implementación (CTEs SQL sobre bib_*)

Núcleo en functions/_lib/drift.ts. computeDrift construye cadena de CTEs sobre bib_docs, bib_events, bib_refs:

1. Primera CTE: fecha del último evento relevante por doc (edición, confirmación de vigencia, referencia entrante).
2. Segunda: staleness_days como diferencia entre now() y ese último evento.
3. Tercera: función de scoring logarítmica que penaliza exponencialmente inactividad prolongada y bonifica docs con alta densidad de referencias activas.

drift_score normalizado 0-1. Umbral stale >0.7, critical >0.9. drift.ts envuelve computeDrift con validación de sesión y serialización JSON. drift-run.ts persiste scores en columna drift_score de bib_docs y registra evento drift_recalc en bib_events.

Decisiones

• Cálculo íntegramente SQL (CTEs) en lugar de traer datos a TypeScript y procesar en memoria. Mantiene volumen transferido bajo control y aprovecha índices existentes sobre bib_events.doc_id y bib_events.created_at.
• Scoring logarítmico, no lineal, para evitar que docs moderadamente viejos reciban scores alarmantes. Reserva zona crítica para inactividad real.
• Cron en GitHub Actions, no trigger de BD. Mantiene lógica de scheduling auditable en repo y desacoplada del proveedor de BD.

Commits relacionados

• f3a9bf4 (2026-04-20) — feat(escriba): Fase 3 — doc drift detector + widget + cron diario. Commit raíz: introduce drift.ts, drift-run.ts, workflow y widget Pulse.

Véase también

• [[concept—biblioteca—supercontexto]]