MCP Handler: bib_mark_verification_pending

Descripción

Handler MCP implementado en functions/api/mcp/handlers/wiki.ts. Forma parte de la Pieza 2B del ADR KB vs Graph Fase 2.

Recibe una lista de rutas de archivos tocadas por un commit y marca como verification_pending=1 todas las páginas wiki active cuyas sources de tipo code apunten a esos paths (o a un directorio padre de los mismos).

Signatura

bib_mark_verification_pending(file_paths: string[], actor?: string) → MarkResult

Parámetros

Parámetro	Tipo	Requerido	Descripción
`file_paths`	`string[]`	Sí	Rutas de archivos tocados en el commit. Array vacío devuelve `marked: 0`.
`actor`	`string`	No	Identificador del caller. Default: `'agent-tripwire'`.

Respuesta

{
  "ok": true,
  "marked": 3,
  "page_slugs": ["entity--racks--model--rack", "..."],
  "paths_processed": 5,
  "candidates_checked": 42
}

Lógica de matching

Para cada página candidata (status='active', verification_pending=0, sources != '[]'), parsea el campo sources y evalúa cada entrada type='code':

src.ref === fp                                        // coincidencia exacta
src.ref.endsWith('/') && fp.startsWith(src.ref)      // prefijo directorio (trailing slash)
fp.startsWith(`${src.ref}/`)                         // prefijo directorio (sin trailing slash)

Idempotencia y chunking D1

Las páginas ya con verification_pending=1 no se consultan (filtro en la query inicial).
Los slugs se actualizan en lotes de 90 para respetar el límite de bind params de D1 (footgun footguns_d1_bind_limit).
Persiste un evento operation='lint' en bib_wiki_log con los slugs afectados.

Invocador

Llamado desde trigger_tripwires() en .github/scripts/bib_ingest.py, siempre antes de los tiers Tier 1/2/3 del ingest. El ingest no falla si este handler devuelve error.

Filtros de paths en trigger_tripwires

El llamador (bib_ingest.py) excluye los siguientes prefijos antes de pasar paths al handler:

src/content/wiki/ — wiki .md (tienen su propio flow)
.github/scripts/bib_* — scripts internos del ingest
scripts/harness/ — scripts del harness
public/supercontext/ — briefings Supercontexto

Diagrama de flujo

commit → bib_ingest.py::trigger_tripwires()
           ↓  filtra paths (excluye wiki .md, scripts bib_, harness, supercontext/)
           ↓
         bib_mark_verification_pending(file_paths)
           ↓
         consulta bib_wiki_pages (active, pending=0, sources≠[])
           ↓  para cada página: compara sources[type=code].ref vs file_paths
           ↓
         UPDATE bib_wiki_pages SET verification_pending=1 WHERE slug IN (...)
           ↓
         INSERT bib_wiki_log (operation='lint')

Véase también

[[feature—biblioteca—kb-vs-graph-fase2]] — feature que introduce este handler (Fase 2)
[[entity—biblioteca—handler—bib-check-drift-for-doc]] — handler que procesa los slugs marcados por este
[[decision—20260514—knowledge-base-vs-graph]] — ADR origen
[[entity—biblioteca—handler—wiki-create-page]] — handler relacionado del mismo módulo wiki.ts
[[feature—biblioteca—kb-vs-graph-fase1]] — Fase 1 del mismo ADR