Graph Health · MVP v0.1

01 El contrato: tres grafos que no son el mismo

Un workflow de Agent Squad existe tres veces, y las tres vistas divergen. Graph Health las modela por separado y las brechas nacen de compararlas. Contrato completo en CONTRATO.md.

1 · Grafo declarado

Lo que la definición dice que debe pasar. Fuente: graphs.definition + catálogo de operaciones (timeout, retry, propósito).

2 · Grafo observado

Lo que la telemetría prueba que pasó. Fuente: run_events + work_items (estado, intentos, duraciones, costos, fallos, contención).

3 · Grafo de lineage

Lo que el artefacto final declara que contribuyó. Fuente: lineage_from_steps del publisher y el lineage real si hubo publish.

Entidades

NODO

id, propósito, decide (anotable), inputs, consumidores, deps, recurso, retry, timeout, sla, topo.

ARISTA

from, to, contrato declarado (campos que interpolan), datos observados (hoy no_instrumentado: el motor no emite telemetría por transferencia), relación con lineage, clase (datos / orden sin datos / lineage intencional).

EJECUCIÓN

run × nodo: status, intentos, duración (incluye cola, etiquetado), fallos con código y tiempo relativo, costo, recurso.

SEÑAL

scope (node/edge/path/graph), target, tipo, origen (determinístico o JEV), valor, estabilidad 3 corridas, severidad, umbral y EVIDENCIA verificable. Toda señal es auditable.

02 El pipeline

Regla dura del contrato: lo que se puede probar con datos NUNCA se le pregunta a JEV. Los hechos deterministas llegan a JEV como evidencia en el state; JEV solo juzga lo semántico (necesidad, posición, pérdida de handoff, causa estructural).

extraer.py3 vistas → modelo.json
→
brechas.pyG1..G10 deterministas
→
preguntas_jev.pyconsultas autogeneradas ×3
→
reporte.py7 dimensiones
→
validar.pyesperados vs reporte
brechacomparación deterministavistas
G1arista declarada sin contrato de datosdeclarado
G2input referencia steps.X sin arista declaradadeclarado
G3fuente real del entregable ausente del lineagedeclarado vs lineage
G4output que nadie consume (no terminal)declarado
G5concentración de fallos por nodoobservado
G6fan-in excesivo (deps ≥6 o inputs ≥12)declarado
G7demanda concurrente sobre un carril > topedeclarado + observado
G8drift entre versiones del grafodeclarado vs declarado
G9tiempo quemado en reintentos fallidosobservado
G10duración medida > sla_ms (incluye cola, etiquetado)declarado vs observado

03 GraphHealthReport: siete dimensiones, cero score global

Corrido contra brief-synthesis-v13 v3 con la misma evidencia del escáner one-off (3 corridas del 18/19-sep). Cada dimensión es independiente: no se promedian.

04 Validación: ¿reproduce lo que ya sabíamos?

La discrepancia, sin maquillar

E2 (embudo de conciliación tardía): la elección dominante COINCIDE con el escáner one-off (embudo_conciliacion_tardia, elección estable 3/3) pero p=0.473 con margen 0.123, bajo el umbral de firmeza (≥0.60 con margen ≥0.25). El protocolo manda no emitir señal y así se reporta. Causa raíz: el escáner artesanal llevaba en el state la historia V14/V15 y el detalle de las tres fuentes de demanda; el generador automático no puede derivar ese contexto de dominio. La dirección se reproduce, la firmeza requiere anotaciones curadas.

Experimento A/B: cuánto vale el digest curado

La misma corrida con y sin anotaciones (el campo «decide» por nodo). La calidad del digest ES la variable: sin semántica curada, JEV defiende nodos que la telemetría ya condenó.

05 Hallazgos nuevos (que el escáner one-off no vio)

06 Revisión de generalización

Reusable de verdad

El extractor entero (cualquier graph_id del motor v2), las 10 brechas deterministas, el ensamblador de 7 dimensiones, el protocolo JEV (plantillas por nodo/arista/fan-in/handoff/global, 3 corridas, umbrales, descarte por inestabilidad) y validar.py. Nada de eso menciona al Content Brief.

Específico del Content Brief

Las anotaciones curadas (decide por nodo), la línea de contexto, los esperados de la validación, y el contexto de dominio que hizo firme la causa estructural en el escáner one-off (historia V14/V15, tres fuentes de demanda).

Para enchufar otro workflow

(1) su graph_id ya está en graphs si corrió con el motor v2; (2) regenerar catalogo.json desde COMPOSABLE_OPS (es compartido, el extractor de regex es lo frágil); (3) una línea de contexto; (4) recomendado: 1-2h de anotaciones «decide» por nodo, el A/B muestra que cambian veredictos.

Instrumentación faltante

(1) telemetría por arista: qué outputs se leyeron de verdad al resolver inputs; (2) NODE_STARTED o historización del lease: hoy cola y ejecución son indistinguibles y G10 queda ruidoso; (3) el catálogo como dato consultable, no regex sobre TS; (4) lineage observado: solo existe si publish corre; (5) fases internas de s4 (generación/verificación/reparación) con tiempos propios.

NO generalizar todavía

(1) el mapeo automático señal→recomendación: sigue siendo de Opus + cerebro + Roberto; (2) Graph Health como gate de CI o cron: primero madurar contra un segundo workflow; (3) la pregunta de causa estructural sin anotaciones: bajo el umbral es NO CONCLUYENTE y así debe quedarse; (4) tocar el motor para instrumentar: zona Inngest, diseño del cerebro + review adversarial.

Plan de implementación (pendiente de OK)

W1: catalogo como dato + segundo workflow enchufado (Done when: reporte de otro graph_id sin tocar código de la herramienta). W2: instrumentación del motor (NODE_STARTED + receipts de resolución de inputs; zona Inngest: cerebro + mordidas). W3: persistencia de reportes + comparación entre corridas en el tiempo.

STOP. Diseño, MVP y validación entregados. Nada de esto toca producción: la herramienta lee Postgres en READ ONLY y vive en ~/bin/graph-health. REC-1..REC-7 siguen SIN implementar. Espero aprobación antes de cualquier cambio en workflows o en el motor.