KB vs Graph · Fase 2 — Tripwires + Drift Check

KB vs Graph · Fase 2 — Tripwires + Drift Check

Contexto

La Fase 2 del ADR decision--20260514--knowledge-base-vs-graph implementa el mecanismo de sincronización activa entre la base de conocimiento (wiki Supercontexto) y el grafo de conocimiento (D1 + grafo de nodos). El objetivo es detectar automáticamente cuándo un commit toca código que una página wiki declara como source, marcándola como pendiente de verificación y, en el siguiente cron, auditando si el contenido ha derivado (drift).

Piezas implementadas

Pieza 2A — trigger_tripwires (bib_ingest.py)

Función añadida al script bib_ingest.py, ejecutada siempre en el entrypoint main() antes del flow Tier 1/2/3.

Responsabilidad: dado el conjunto de archivos cambiados en un commit, filtra los que NO son wiki .md, ni scripts internos del harness, ni briefings Supercontexto; llama al MCP handler bib_mark_verification_pending con los paths restantes.

Criterios de exclusión de paths (no disparan tripwire):

• src/content/wiki/ (wiki .md — tienen su propio flow vía reconcile_wiki_to_d1)
• .github/scripts/bib_*
• scripts/harness/
• public/supercontext/

Comportamiento ante errores: no falla el ingest. Si el MCP devuelve error, solo loguea y continúa — el drift se recuperará en el siguiente commit.

Pieza 2B — bib_mark_verification_pending (wiki.ts)

Nuevo MCP handler en functions/api/mcp/handlers/wiki.ts.

Flujo:

1. Recibe file_paths[] y un actor.
2. Consulta bib_wiki_pages donde status='active', verification_pending=0, sources != '[]'.
3. Para cada página, parsea sources y busca entradas type='code' cuyo ref coincida exactamente con algún path, o sea prefijo de directorio del path.
4. Marca verification_pending=1 en las páginas coincidentes (chunked en lotes de 90 para respetar el límite de bind params de D1).
5. Persiste evento en bib_wiki_log con operation='lint'.
6. Idempotente: páginas ya con verification_pending=1 no se re-marcan.

Pieza 3 — bib_check_drift_for_doc (wiki.ts)

Nuevo MCP handler invocado típicamente por cron (drift-cron workflow).

Flujo:

1. Recibe slug y dry_run.
2. Carga la página de D1. Si no tiene sources tipo code, devuelve skipped: 'no_code_sources'.
3. Por cada code source, consulta GitHub Commits API para obtener commits desde last_verified (cap: 10 commits totales, 5 con diff completo).
4. Si no hay commits → refresca last_verified y borra verification_pending.
5. Si hay commits → obtiene diff parcial (truncado a 900 chars/archivo), fetcha el cuerpo del .md sin front-matter (cap 6 KB), y llama a Haiku 4.5 con un system prompt de auditor de drift.
6. Haiku responde JSON {drift, confidence, summary, suggested_changes_excerpt}.
7. Si drift=true y confidence>0.7 y no dry_run: crea un draft <slug>--drift-fix-YYYYMMDD para que el Curator lo triage.
8. Persiste la auditoría en bib_drift_checks con tokens, coste USD y resultado.
9. Si no hay drift (o confidence<0.3) y no dry_run: refresca last_verified y borra verification_pending.

Campos nuevos en FrontMatter / D1

El handler wikiCreatePage ahora soporta y persiste dos campos nuevos:

Ambos se almacenan en bib_wiki_pages (columnas kind, lifecycle) y se renderizan en el bloque YAML del .md vía renderFrontMatter.

Cambios en callAnthropicHaiku

La función callAnthropicHaiku ahora devuelve { text, tokens, inputTokens, outputTokens } (antes solo text, tokens). Se añade la función auxiliar haikuCostUsd(inputTokens, outputTokens) con precios Haiku 4.5 de mediados de 2026 ($0.0008/1K input, $0.004/1K output).

Tabla bib_drift_checks

Nueva tabla D1 persistida por bib_check_drift_for_doc:

Routing MCP

En el switch de handleWiki se añaden dos nuevos cases:

• bib_mark_verification_pending → bibMarkVerificationPending(db, args)
• bib_check_drift_for_doc → bibCheckDriftForDoc(db, args, env)

Véase también

• [[entity—biblioteca—handler—bib-mark-verification-pending]]
• [[entity—biblioteca—handler—bib-check-drift-for-doc]]
• [[decision—20260514—knowledge-base-vs-graph]]
• [[entity—biblioteca—handler—wiki-create-page]]
• [[feature—biblioteca—kb-vs-graph-fase1]]