Decisión (ADR): Excluir nodos 'doc' del cálculo de salud de la Biblioteca

Contexto

El sensor de salud de la Biblioteca (stale-check.ts) contaba desactualizados incluyendo nodos de tipo doc (documentación wiki .md). Problema: el indexador de documentos no escribe content_hash, así que todos los ~957 doc nodos se marcaban permanentemente como “stale”. Esto inflaba artificialmente el porcentaje de alerta (rojo) del widget de Salud, ocultando problemas reales del índice de código.

Además, el sensor leía un denominador (COUNT(*) global) que incluía endpoint/schema/doc, mientras el numerador (stale_count) ya los excluía → inconsistencia matemática (66% reportado vs 58% real).

Symptoma visible: El widget Salud mostraba 66% cuando el cálculo interno acusaba 58% (s210).

Decisión

Excluir nodos de tipo doc del cálculo de salud de la Biblioteca.

Junto a endpoint y schema (ya excluidos), los docs salen de:

• El query de conteo de nodos stale.
• El query de conteo de nodos totales (“trackables”).

Justificación

1. Diferente responsabilidad de medición:

   • El sensor de Biblioteca mide la cobertura e integridad del índice de CÓDIGO (models, functions, services, handlers, etc.).
   • Los docs son documentación; su salud la mide otro sensor distinto (Bibliotecario-Checker que recorre archivos .md en la carpeta context/).

2. Ausencia de content_hash:

   • El indexador de documentos no escribe content_hash (diferente del indexador de código).
   • Sin este campo, un doc nunca puede “pasar” el criterio de staleness, aunque sea fresco.
   • Contar docs como stale permanente es falso.

3. Coherencia matemática:

   • Numerador y denominador ahora vienen del mismo activity_log (escrito por el cron).
   • Ambos excluyen endpoint/schema/doc.
   • Resultado: 58% real (honesto) vs 66% inflado anterior.

4. Señal correcta:

   • El sensor ahora refleja la verdadera cobertura de código.
   • El drift real (p. ej. una JS module con fecha vieja en workspace) sigue siendo detectado.
   • Se reduce ruido falso de docs “eternos”.

Alternativas consideradas

1. Hacer que el indexador de docs escriba content_hash:

   • Posible pero mayor esfuerzo; requiere cambios en el pipeline de ingesta de documentos.
   • Por ahora, excluyendo es más simple y más honesto.

2. Medir docs por separado en el widget:

   • Buen complemento futuro (sensor Bibliotecario específico para docs).
   • De momento, simplificar y dejar que cada sensor mida lo suyo.

Impacto

• ✅ Porcentaje de salud ahora coherente (denominador = numerador).
• ✅ Widget Salud reporta realidad (58% en lugar de 66% inflado).
• ✅ Se reduce falso positivo (docs no cuentan como stale).
• ✅ Código sigue siendo medido correctamente.

Cambios de código:

• stale-check.ts: WHERE clause excluye 'doc' junto a endpoint/schema.
• health.ts: Lee total_nodes del activity_log (escritura coordinada con cron).

Cambio real (commit@99817e5)

-WHERE node_type NOT IN ('endpoint', 'schema')
+WHERE node_type NOT IN ('endpoint', 'schema', 'doc')

En ambos queries de stale-check (conteo de stale y total de nodos).

Véase también

• [[entity—functions—handler—stale-check-cron]]
• [[entity—functions—handler—health-check-biblioteca]]
• [[concept—biblioteca—nodo-trackable]]