# Graph Health — Contrato canónico (MVP v0.1, 19-sep-2026)

Capacidad reusable para evaluar la salud arquitectónica de un workflow de
Agent Squad. Nace del escáner one-off del Content Brief (sesión 205ac71d,
playground escaner-bosque-brief.html) y lo generaliza SIN tocar producción:
es una herramienta de análisis externa que lee Postgres en READ ONLY.

## Principio rector: tres grafos que NO son equivalentes

1. **GRAFO DECLARADO** — lo que la definición dice que debe pasar.
   Fuente: `graphs.definition` (nodos, depends_on, inputs con templates,
   gates, sla) + catálogo de operaciones (timeout, retry, propósito).
2. **GRAFO OBSERVADO** — lo que la telemetría prueba que pasó.
   Fuente: `run_events` (NODE_READY/NODE_SUCCEEDED/NODE_FAILED/REROUTED/
   EFFECT_DONE) + `work_items` (status, attempts, error).
3. **GRAFO DE LINEAGE** — lo que el artefacto final declara que contribuyó.
   Fuente: `lineage_from_steps` del nodo publish en la definición, y el
   lineage del artefacto real cuando la corrida llegó a publicar.

Toda comparación entre vistas es un chequeo DETERMINISTA (fase de brechas).
JEV entra después, SOLO para juicios semánticos que la estructura y la
telemetría no pueden decidir (necesidad, posición, pérdida de handoff,
causa estructural). Regla dura: **nada que se pueda probar con datos se le
pregunta a JEV**.

## Entidades (modelo.json)

### NODO
```json
{
  "id": "s4",
  "proposito": "texto del catálogo o vacío",
  "decide": "responsabilidades/decisiones (del catálogo o derivado)",
  "capability": "text.compose_brief@1.0.0",
  "inputs": {"campo": "template o literal"},
  "inputs_n": 18,
  "outputs_consumidos_por": ["s5", "s6"],
  "depends_on": ["s0_audience", "..."],
  "resource_id": "capacidad:text.compose_brief",
  "retry": "R1 | {max_attempts,...} | null",
  "timeout_ms": "240000 | expresión del catálogo | null",
  "sla_ms": 640000,
  "topo": 7,
  "es_gate": false
}
```

### ARISTA
```json
{
  "from": "r4", "to": "s4",
  "contrato_declarado": ["research", "topic_demand_receipt", "..."],
  "datos_observados": "no_instrumentado | resultado_ref_presente",
  "relacion_lineage": "en_lineage | fuera_de_lineage | no_aplica",
  "clase": "datos | orden_sin_datos | lineage_intencional"
}
```
- `contrato_declarado`: los campos de inputs del destino que interpolan
  `{{steps.<from>...}}`. Vacío = arista declarada sin contrato de datos.
- `datos_observados`: el motor v2 HOY no emite telemetría por arista (los
  inputs se resuelven con resolveStepRefs desde el state); el MVP lo declara
  `no_instrumentado` y la brecha queda registrada como instrumentación
  faltante, no se inventa.
- `clase lineage_intencional`: arista al nodo publish cuyo único propósito
  es procedencia (el destino la nombra en lineage_from_steps).

### EJECUCIÓN (por corrida × nodo)
```json
{
  "run_id": "27e31613-...", "graph_id": "brief-synthesis-v13",
  "graph_version": 3, "node_id": "s4",
  "status": "done | failed | no_corrio",
  "attempts": 2,
  "dur_s": 120.1,
  "nota_duracion": "cierre propio menos cierre de la última dependencia; INCLUYE cola/carril",
  "fallos": [{"code": "brief_demand_claim_unverified", "t_rel_s": 300}],
  "costo_usd": 0.06,
  "recurso": "dataforseo"
}
```

### SEÑAL DE SALUD
```json
{
  "id": "G1-r14-r12",
  "scope": "node | edge | path | graph",
  "target": "r14→r12",
  "tipo": "arista_declarada_sin_datos",
  "origen": "deterministico | jev",
  "valor": {"p": 0.213, "score": null, "eleccion": null},
  "estabilidad": {"corridas": 3, "rango": 0.02, "veredicto": "estable"},
  "severidad": "info | menor | mayor | critica",
  "umbral": "texto del umbral aplicado",
  "evidencia": ["hecho verificable con su fuente (tabla/evento/valor)"],
  "recomendacion_ref": "REC-2 | null"
}
```
Las señales deterministas llevan `valor: null` y evidencia con los datos
crudos; las de JEV llevan probabilidad/score/elección + estabilidad de las
3 corridas. Toda señal preserva evidencia y procedencia: otro modelo o un
humano tiene que poder verificar POR QUÉ se levantó.

## Brechas deterministas (brechas.json)

| id | comparación | vistas |
|----|-------------|--------|
| G1 | arista declarada sin contrato de datos | declarado vs declarado |
| G2 | input referencia steps.X sin arista declarada a X | declarado vs declarado |
| G3 | fuente real del entregable ausente del lineage | declarado vs lineage |
| G4 | output que ningún nodo consume (y no es terminal) | declarado |
| G5 | concentración de fallos por nodo | observado |
| G6 | fan-in excesivo (deps ≥6 o inputs ≥12) | declarado |
| G7 | demanda concurrente sobre un carril > tope del recurso | declarado+observado |
| G8 | drift entre versiones del grafo (diff de definición + corridas por versión) | declarado vs declarado |
| G9 | tiempo quemado en reintentos fallidos | observado |
| G10 | duración medida > sla_ms declarado (incluye cola, se etiqueta) | declarado vs observado |

## Capa JEV (solo juicios semánticos)

Preguntas AUTOGENERADAS desde el modelo y las brechas:
- por nodo: `necesario_<id>`, `bien_posicionado_<id>` (boolean)
- por brecha G1: `arista_<from>_<to>_necesaria` (boolean)
- por brecha G6: `fanin_<id>_sano` (boolean)
- por arista agregador→concentrador: `handoff_<from>_<to>_perdida` (score)
- por brecha G3: `lineage_incompleto_defecto` (boolean)
- global, parametrizado por el nodo F de G5: `causa_estructural_<F>` (choice
  entre 5 hipótesis genéricas), `falta_validacion_intermedia` (boolean),
  `split_<F>` (boolean), `secuenciacion_global` (score),
  `profundidad_topologica` (choice)

Protocolo: cada consulta lleva el marco del grafo ENTERO + digests del foco;
3 corridas idénticas; rango ≤0.06 estable, ≤0.15 borde, >0.15 la señal se
DESCARTA. Umbrales de lectura: necesidad/posición p≤0.30 rojo, ≤0.55 ámbar;
defecto afirmado p≥0.70 firme, ≥0.55 débil; choice dominante ≥0.60 con
margen ≥0.25 y elección estable 3/3.

## GraphHealthReport (graph-health-report.json)

SIN score global único. Siete dimensiones independientes, cada una con
`estado: ok | degradado | critico` (el peor de sus señales) y sus señales:

1. `integridad_estructural` — G1, G2, G4, G6 (+ JEV necesidad/posición)
2. `integridad_flujo_datos` — G2, G4, handoffs JEV, instrumentación por arista
3. `integridad_lineage` — G3 + cobertura (fuentes en lineage / fuentes reales)
4. `confiabilidad_ejecucion` — G5, G9, G10
5. `concentracion_cuellos` — cola serial, camino crítico, JEV secuenciación/profundidad
6. `contencion_recursos` — G7
7. `drift_arquitectura` — G8

Severidad → estado: critica→critico; mayor→degradado; menor/info→ok con nota.

## Uso

```bash
~/bin/graph-health/graph-health <graph_id> [version] \
  [--catalogo catalogo.json] [--contexto "una línea del dominio"] \
  [--workdir DIR] [--sin-jev]
```
Encadena: extraer.py → brechas.py → preguntas_jev.py → reporte.py.
Postgres SIEMPRE en transacción READ ONLY vía docker exec substrate-postgres.
