Endpoint /api/biblioteca/drift-checks — Estadísticas cron KB vs Graph

Endpoint /api/biblioteca/drift-checks

Endpoint CF Pages que expone las estadísticas del cron KB vs Graph (ADR decision--20260514--knowledge-base-vs-graph). Introducido en PR #39 como cierre de la Fase 5 de la iniciativa s61.

Localización

Nota de diseño: El endpoint vive en la subcarpeta drift-checks/index.ts (no como drift-checks.ts raíz) para evitar que el catch-all [id].ts lo capture e intente parsear "drift-checks" como un node ID. Mismo patrón que drift/.

Interfaz HTTP

GET /api/biblioteca/drift-checks
Authorization: Bearer <token>

Query params:
  window_days  int  1-∞   Default: 7   Ventana temporal en días
  limit        int  1-50  Default: 5   Máximo de top-drifts devueltos

Respuesta (DriftChecksReport)

interface DriftChecksReport {
  generated_at:    string;       // ISO 8601
  window_days:     number;
  total_checks:    number;       // Checks ejecutados en la ventana
  drift_detected:  number;       // Checks con drift_detected = 1
  drift_pct:       number;       // (drift_detected / total_checks) * 100
  avg_confidence:  number;       // AVG(confidence) — rango 0.0-1.0
  total_cost_usd:  number;       // SUM(haiku_cost_usd)
  drafts_created:  number;       // Pages con draft_slug_created NOT NULL
  last_check_at:   string | null;
  top_drifts:      DriftCheckItem[];
}

interface DriftCheckItem {
  slug:               string;
  checked_at:         string;
  confidence:         number;
  summary:            string | null;
  draft_slug_created: string | null;
}

Headers de respuesta: Cache-Control: no-store.

Función computeDriftChecks

// functions/_lib/drift_checks.ts
export async function computeDriftChecks(
  db: D1Database,
  opts: { windowDays?: number; limit?: number } = {},
): Promise<DriftChecksReport>

Lee la tabla D1 bib_drift_checks (poblada por el handler MCP bib_check_drift_for_doc) y computa el agregado:

SELECT COUNT(*), SUM(drift_detected), AVG(confidence),
       COALESCE(SUM(haiku_cost_usd), 0), ...
  FROM bib_drift_checks
 WHERE checked_at >= <since_iso>

Seguido de una query de top-N por confidence DESC, checked_at DESC filtrando drift_detected = 1.

Tabla fuente: bib_drift_checks

Ciclo de vida operativo

Coste estimado en régimen permanente: ~$2.4/mes (20 pages/día × $0.004/check).

Véase también

• [[feature—biblioteca—pulse-drift-checks-widget]]
• [[decision—20260514—knowledge-base-vs-graph]]
• [[entity—biblioteca—endpoint—drift]]
• [[concept—biblioteca—supercontext]]
• [[runbook—biblioteca—drift-checks-operacion]]