# Telemetría mínima viable para Graph Health — propuesta de arquitectura v0.2 (pre-W2)

**Estado: PROPUESTA. Nada implementado. El motor y la zona Inngest no se tocan
hasta el OK de Roberto.** v0.1 escrita el 19-sep-2026 sobre reconocimiento del
motor real; **v0.2 incorpora las 8 correcciones del review adversarial del
cerebro (veredicto de v0.1: BLOQUEADO; el crudo está en
review-telemetria.md)**. La tesis central sobrevivió el review; lo que cambió
es cuánta certeza puede reclamar cada pieza.

**Principio nuevo, del review, que gobierna todo el documento**: las tablas
laterales son **evidencia diagnóstica reconciliable, nunca verdad soberana**.
Una contradicción entre telemetría y `work_items`/`run_events` produce
`telemetria_inconsistente`; jamás reescribe la historia oficial. Y la ausencia
de telemetría produce `telemetria_desconocida`; jamás se interpreta como
"no pasó".

---

## 0. Hechos del motor que condicionan el diseño (verificados en código)

| # | Hecho | Fuente |
|---|-------|--------|
| H1 | `run_events` es un log soberano con cadena de hashes: `hash_n = sha256(hash_prev ‖ event_key ‖ seq ‖ json canónico)`, idempotente por `event_key` UNIQUE, seq sin huecos, serializado por corrida | event-log.ts:141-153, 235-318 |
| H2 | El reducer RECHAZA tipos sin manejador de forma determinista: no cambia estado y no avanza `ultimo_seq_aplicado`; tolerado por diseño pero deja "huecos" que todo plegado repite | reducer.ts:816-824 |
| H3 | `NODE_STARTED` YA existe en el vocabulario y tiene manejador en el reducer; hoy solo lo emite el ESPEJO de v1 (gates); el soberano v2 nunca lo emite | estado.ts:271-273, reducer.ts:405, espejo.ts:321, research-report-load.ts:170 |
| H4 | `NODE_SUCCEEDED` lo emite el despachador al cerrar el work item, con payload mínimo `{node_id, resultado_ref}`; el resultado completo queda en `work_items.result` (jsonb); el costo viaja por `EFFECT_DONE` aparte | despachador.ts:820-849 |
| H5 | `work_items` NO tiene `created_at` ni `leased_at`; el lease se sobreescribe por intento (`leased_by`, `lease_until`, `heartbeat_at`): la historia de cola y ejecución se pierde | esquema work_items (Postgres) |
| H6 | `resolveStepRefs` es una función PURA que resuelve `{{steps.X.outputs...}}` contra el mapa de salidas; para una referencia completa a un step inexistente devuelve `null`, para una RUTA inexistente devuelve el template sin resolver, y las referencias inline dentro de strings más largos se sustituyen una por una; su regex NO acepta `?` | resolucion-de-inputs.ts:60-90 |
| H7 | El worker corre DENTRO de un cron de Inngest (`worker-orquestacion.ts`); las operations son handlers Inngest; despachador y worker son el motor v2 invocado desde ahí | worker.ts:51-56 |
| H8 | `NODE_READY` solo se emite para los nodos raíz; la readiness del resto es implícita (cierre de la última dependencia) | arrancar-corrida.ts:26, 421 |
| H9 | En recuperación/reparación las salidas consumidas pueden ser HEREDADAS de otra corrida (`salidasHeredadas`, fusión disjunta): el productor real de un valor puede NO estar en la corrida observada | worker.ts:490-505 |
| H10 | El claim vive dentro de un `pg_advisory_xact_lock` por recurso; el cierre tiene atomicidad deliberada entre work_item y evento soberano, y al descubrir un lease ajeno lanza `LeasePerdidoError` sin cerrar nada propio | despachador.ts:445-455, 820-849 |

## 1. Decisión de arquitectura: canal lateral de telemetría, NO el log soberano

**Recomendación (sobrevivió el review): la telemetría nueva vive en DOS tablas
laterales (`node_attempts` y `edge_transfers`), no en `run_events`.** El log
soberano es event sourcing de ESTADO con cadena de hashes y espejo de
verificación; la telemetría es observabilidad. Mezclarlas cobra tres impuestos
que el MVP no necesita pagar:

1. **Contención**: cada evento nuevo serializa contra la cadena de hashes por
   corrida (H1) en el camino caliente del claim.
2. **Reducer y espejo**: un tipo nuevo en el log es rechazo determinista (H2);
   y aunque `NODE_STARTED` ya tiene manejador (H3), su semántica está atada al
   espejo v1 y a la resurrección de gates: emitirlo desde el soberano exige su
   propio análisis.
3. **Reversibilidad**: una tabla lateral se apaga con un flag y se borra con un
   DROP; eventos escritos en el log soberano son para siempre.

**Camino de promoción documentado**: si mañana el ESTADO debe reaccionar a
estos hechos (no solo observarlos), `NODE_STARTED` se promueve al log (su
manejador ya existe) y `EDGE_TRANSFER` se evalúa como evento de primera clase.

**Regla de lectura (corrección del review)**: Graph Health filtra por
autoridad/engine (nunca mezcla `NODE_STARTED` del espejo v1 con intentos v2
laterales) y reconcilia SIEMPRE contra `work_items` y `run_events`.

## 2. Los cinco eventos evaluados

### Veredicto resumido

| Evento propuesto | Veredicto | Forma final |
|---|---|---|
| NODE_QUEUED | NO hace falta como evento | columna `work_items.created_at` (migración en dos pasos, NULL = histórico desconocido) |
| NODE_STARTED | SÍ, como registro de intento | fila en `node_attempts` al adquirir el lease, identidad = `lease_token` |
| NODE_COMPLETED | YA existe (`NODE_SUCCEEDED`) | cierre de la fila de `node_attempts` FUERA de la transacción soberana, reconciliable |
| NODE_FAILED | YA existe | ídem, outcome=`failed` + `error_code`; el log soberano no cambia |
| EDGE_TRANSFER | SÍ, lo genuinamente nuevo | filas en `edge_transfers` por ocurrencia de referencia + receipt de captura por intento |

### 2.1 NODE_QUEUED (cubierto por columna, sin evento nuevo)

- **Propósito exacto**: fijar el instante en que el trabajo quedó disponible,
  para separar cola de ejecución. La entrada a cola ES la creación del work
  item (más `run_after` si hay backoff); hoy ese instante no se guarda (H5).
- **Migración (corregida por el review, hallazgo 8)**: en DOS pasos y sin
  inventar historia:
  ```sql
  SET lock_timeout = '1s';
  ALTER TABLE work_items ADD COLUMN created_at timestamptz;        -- NULL, sin default
  ALTER TABLE work_items ALTER COLUMN created_at SET DEFAULT now(); -- solo filas nuevas
  ```
  Sin `NOT NULL`, sin backfill: las filas previas quedan `NULL` = "dato no
  disponible antes de la instrumentación" y Graph Health lo trata así. El
  `ALTER TABLE` necesita lock fuerte aunque sea metadata-only: `lock_timeout`
  corto y reintento del despliegue si no lo consigue rápido.
- **Productor**: el INSERT existente del despachador (DEFAULT de la base).
- **Consumidor**: Graph Health. **Idempotencia**: la del INSERT existente.
- **Volumen/privacidad**: 8 bytes por fila; timestamp, sin implicaciones.

### 2.2 NODE_STARTED → fila de intento en `node_attempts`

```sql
CREATE TABLE node_attempts (
  lease_token   text        PRIMARY KEY,       -- LA identidad del intento físico
  run_id        uuid        NOT NULL,
  node_id       text        NOT NULL,
  attempt       int,                           -- metadata (work_items.attempts al reclamar), NO identidad
  work_item_id  uuid        NOT NULL,
  resource_id   text        NOT NULL,
  queued_at     timestamptz,                   -- created_at o run_after del intento; NULL = desconocido
  leased_at     timestamptz NOT NULL,
  lease_until_at_claim timestamptz NOT NULL,   -- para reconstruir ocupación aunque el lease se pierda
  closed_at     timestamptz,
  outcome       text,                          -- done | failed | lease_perdido
  error_code    text,
  lost_at       timestamptz,                   -- cuándo se descubrió perdido (si outcome=lease_perdido)
  dur_cola_ms      bigint,
  dur_ejecucion_ms bigint,
  salida_bytes  bigint,
  salida_sha256 text,
  canonical_version text,                      -- versión del canonicalizador del hash
  edge_capture_status text,                    -- complete | failed | NULL=no aplica/desconocido
  edge_count    int                            -- cuántas filas de edge_transfers escribió este intento
);
CREATE INDEX ON node_attempts (run_id, node_id);
```

- **Propósito exacto**: registrar cuándo un intento físico concreto pasó de la
  cola a ejecución y cómo terminó. `leased_at` es la frontera cola/ejecución
  que hoy no existe; `lease_until_at_claim` conserva la ventana aunque el
  siguiente claim sobreescriba `work_items` (hallazgo 4 del review).
- **Identidad (corregida, hallazgo 1)**: `lease_token` como PK. El diseño v0.1
  asumía "lease robado ⇒ attempt+1" sin evidencia de que el claim incremente
  `attempts`; con `lease_token` la identidad es del lease físico y `attempt`
  queda como metadata informativa. INSERT INMUTABLE (`ON CONFLICT DO NOTHING`),
  nunca `DO UPDATE` (hallazgo 7: evita locks de fila/índice extra bajo el
  advisory lock).
- **Productores (tres, corregido por hallazgo 4)**:
  1. `despachador.reclamar()`: INSERT del intento, dentro de la transacción del
     claim SOLO si el benchmark de W2 prueba impacto aceptable en la sección
     crítica del advisory lock (es una sentencia inmutable; "lease concedido ⇔
     intento registrado" vale la pena mientras no se haya gastado dinero).
  2. **Post-commit del cierre** (`despachador.cerrar()`): UPDATE con closed_at,
     outcome, duraciones, hash. FUERA de la transacción soberana (hallazgo 7):
     una falla puramente telemétrica JAMÁS puede abortar el cierre de un paso
     que ya gastó dinero. El hueco entre commit y UPDATE se reconcilia desde
     `work_items.closed_at` y el evento soberano.
  3. **El camino que reclama un lease vencido cierra el intento anterior**
     usando su `lease_token`: outcome=`lease_perdido`, `lost_at=now()`. Sin
     este productor no hay historia de ocupación creíble (hallazgo 4).
- **Consumidor**: Graph Health; el dashboard de operaciones cuando exista.
- **Idempotencia**: PK `lease_token` + INSERT `DO NOTHING`; el UPDATE de cierre
  es idempotente por valores absolutos (no incrementos).
- **Correlación**: lease_token ↔ lease físico; (run_id, node_id) ↔ log;
  `attempt` ↔ `REROUTED.intento` (informativo).
- **Volumen**: 1 fila por intento (~25-35 por corrida del brief). Despreciable.
- **Privacidad**: metadata + hash; `error_code` es código, no mensaje.

### 2.3 NODE_COMPLETED / NODE_FAILED

No son eventos nuevos: `NODE_SUCCEEDED`/`NODE_FAILED` del log soberano quedan
EXACTAMENTE como están (H4), y su atomicidad con el cierre del work item no se
toca (confirmado por el review como correcto). Lo que faltaba (duración de
ejecución, tamaño y hash del output, intento físico) va a `node_attempts` en el
paso post-commit.

### 2.4 EDGE_TRANSFER → filas en `edge_transfers` + receipt de captura

**Renombre semántico del review, adoptado**: cada fila registra un **input
resuelto/bindeado**, no "dato consumido por el nodo" (que el handler use o
ignore el valor es otra pregunta). La prueba que ofrece es: "este valor, con
este hash, quedó bindeado a este input de este intento".

```sql
CREATE TABLE edge_transfers (
  lease_token   text        NOT NULL,          -- el intento físico que resolvió
  input_path    text        NOT NULL,          -- JSON Pointer al lugar del input (no solo el campo)
  ref_ordinal   int         NOT NULL,          -- n-ésima referencia dentro de ese path (inline múltiple)
  run_id        uuid        NOT NULL,
  to_node       text        NOT NULL,
  from_step     text        NOT NULL,
  ruta          text,                          -- steps.X.outputs.<ruta> pedida (dimensión, no identidad)
  campo         text,                          -- input de primer nivel (dimensión de consulta)
  resuelto      text        NOT NULL,          -- resolved | inline_resolved | path_missing | source_missing
  origen        text        NOT NULL,          -- propia | herencia | reparacion
  source_run_id uuid,                          -- OBLIGATORIO si origen != propia
  source_work_item_id uuid,                    -- OBLIGATORIO si origen != propia
  bytes         bigint,
  sha256        text,                          -- hash del VALOR resuelto, canónico versionado
  canonical_version text,
  occurred_at   timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (lease_token, input_path, ref_ordinal)
);
CREATE INDEX ON edge_transfers (run_id, to_node, from_step);
```

- **Identidad (corregida, hallazgo 2)**: la PK v0.1 `(run, to_node, attempt,
  from_step, campo)` perdía referencias inline múltiples al mismo step dentro
  del mismo campo (`ON CONFLICT DO NOTHING` se tragaba una en silencio).
  v0.2: `(lease_token, input_path, ref_ordinal)` identifica cada OCURRENCIA de
  referencia; `campo`, `ruta` y `from_step` quedan como dimensiones.
- **Semántica de `resuelto` (corregida, hallazgo 6)**: NO se infiere comparando
  input/output (un upstream puede producir literalmente el string del
  template, y una referencia completa a step inexistente devuelve `null`, no
  el template). La envoltura instrumenta LA RAMA del recorrido: encontró el
  step y la ruta (`resolved`/`inline_resolved`), no encontró la ruta
  (`path_missing`), no encontró el step (`source_missing`). Cada match inline
  se registra por separado. Los templates con `?` NO son referencias que este
  resolver reconozca (H6): no se les inventa semántica.
- **El receipt de captura (corrección del hallazgo 3, la más importante)**: el
  batch es best-effort y jamás tumba el nodo, PERO entonces la ausencia de
  filas era indistinguible de la pérdida de telemetría, y Graph Health habría
  fabricado `sin_consumo` falsos. v0.2: al terminar el batch, el worker
  escribe en `node_attempts` el receipt `edge_capture_status=complete` +
  `edge_count`; si el batch falló, `failed`. **Solo es legal concluir
  `sin_consumo` cuando `edge_capture_status=complete`; en cualquier otro caso
  el estado es `telemetria_desconocida`.**
- **La prueba por hash (corregida, hallazgo 5)**: reproducible offline solo con
  procedencia exacta y canonicalización versionada:
  - el verificador recomputa contra `work_items.result` del
    `source_work_item_id` (que en herencia vive en OTRA corrida, H9), nunca
    "del productor en la corrida actual";
  - `canonical_version` fija el canonicalizador; fixtures COMPARTIDOS entre el
    TypeScript productor y el verificador Python (floats, `-0`, números
    grandes, orden de claves, unicode);
  - el dominio del hash es el valor JSON persistible (jsonb); un valor no
    normalizable no produce hash "válido";
  - source ausente o `result` NULL ⇒ `unverifiable`, NUNCA `mismatch`;
  - las referencias inline se hashean sobre el valor del match ANTES de la
    coerción a string del template, y se declara así.
- **Productor**: worker, envoltura observadora sobre `resolveStepRefs` (la
  función pura NO cambia; candado: test de equivalencia byte a byte).
- **Cuándo**: una vez por intento del destino, antes de invocar el handler.
- **Volumen**: ~1 fila por referencia resuelta (~60-90 por corrida del brief,
  ~100 bytes c/u: ~10 KB por corrida). Despreciable.
- **Privacidad**: nombres de campo, rutas, hashes y tamaños; **payload NUNCA**.
  Si un debugging futuro necesita contenido, será un modo puntual con decisión
  propia, no un default.

## 3. Mapeo punto ciego → telemetría que lo elimina (v0.2, con los estados honestos)

| Punto ciego actual | Qué lo elimina | Cómo queda |
|---|---|---|
| **56 aristas `no_instrumentado`** | `edge_transfers` + receipt de captura | `datos_observados` ∈ {verificado, unverifiable, path_missing/source_missing (handoff incompleto), sin_consumo (SOLO con captura completa), telemetria_desconocida}. G1 se confirma observacionalmente solo con receipt completo |
| **Cola indistinguible de ejecución** | `created_at` + `node_attempts.leased_at` | `dur_cola_ms` y `dur_ejecucion_ms` exactos por intento físico; histórico pre-migración queda NULL=desconocido, no inventado |
| **14 SLAs aparentemente violados** | G10 recalculado sobre `dur_ejecucion_ms` | los que sobrevivan son violaciones reales; además queda definido contra qué mide `SLA_EXCEEDED` (H10 del recon v0.1) |
| **Contención de carril ambigua** | `node_attempts` con `resource_id`, `leased_at`, `closed_at`, `lease_until_at_claim` y cierres `lease_perdido` | ocupación real por carril con intervalos FINITOS aun con leases perdidos; demanda = items listos sin lease |
| **Lineage no reconstruible** | cierre transitivo de `edge_transfers` con procedencia (`source_run_id`/`source_work_item_id`) | grafo de procedencia observado por corrida, correcto incluso con herencia entre corridas; `lineage_from_steps` se valida contra él |

## 4. Telemetría útil que NO va todavía (y por qué)

1. **Payload completo por transferencia**: el hash + verificación offline cubre
   la prueba; contenido = costo de privacidad sin pregunta que lo pida.
2. **Esquema JSON por transferencia**: generador nuevo con sus propios bugs;
   campo reservado, no implementado.
3. **Promover NODE_STARTED al log soberano**: manejador listo (H3), pero exige
   el análisis espejo/gates que ningún punto ciego actual necesita.
4. **EDGE_TRANSFER como evento del log**: solo si el ESTADO debe reaccionar a
   una transferencia (hoy no). El review lo confirmó: el problema de v0.1 no
   eran las tablas laterales sino atribuirles más certeza de la que prueban.
5. **Fases internas de s4** (generación/verificación/reparación): patrón
   receipt de operación (como W3.1), frente propio, no motor.
6. **NODE_PROGRESS / historizar heartbeats**: volumen sin pregunta que lo pida.
7. **OTel/tracing distribuido**: infraestructura entera que el MVP no necesita.
8. **Generar el lineage desde edge_transfers**: primero un ciclo completo de
   VALIDAR declarado vs observado; generar es cambio de producto.

## 5. Impacto en el motor y zona crítica Inngest (v0.2)

| Cambio | Archivo/objeto | Zona | Tallaje | Riesgo y candado |
|---|---|---|---|---|
| Migración: 2 tablas nuevas + `created_at` en dos pasos con `lock_timeout='1s'` | migración SQL | **migraciones Postgres (crítica por protocolo)** | S | tablas nuevas reversibles con DROP; el ALTER de work_items puede encolar tráfico detrás del lock: timeout corto + reintento de despliegue |
| INSERT inmutable del intento al reclamar | despachador.ts `reclamar()` | motor v2 (camino caliente, dentro del advisory lock) | S | **benchmark obligatorio bajo concurrencia ANTES de fijarlo dentro de la transacción**; si el costo no es aceptable, se mueve post-claim y se acepta el hueco |
| UPDATE de cierre POST-COMMIT (fuera de la transacción soberana) | despachador.ts tras `cerrar()` | motor v2 | S | una falla telemétrica no puede abortar un cierre pagado; el hueco se reconcilia desde work_items/run_events |
| Cierre del intento anterior al reclamar lease vencido | despachador.ts (camino de lease vencido) | motor v2 | S | productor obligatorio del outcome `lease_perdido` |
| Resolver instrumentado (envoltura observadora) | resolucion-de-inputs.ts + worker.ts | motor v2 | M | candado: equivalencia byte a byte contra la función pura sobre corpus de templates reales |
| INSERT batch de consumos + receipt de captura | worker.ts | motor v2 | S | try/catch; el receipt es lo que hace legales las conclusiones de ausencia |
| Funciones y handlers de Inngest | NINGUNO | Inngest | 0 | no se tocan; el cron debe absorber ~2-3 sentencias más por nodo |
| run_events / reducer / espejo | NINGUNO | log soberano | 0 | intocados por diseño |

**Reversibilidad**: flag `TELEMETRIA_GRAPH_HEALTH` (default off). Apagado =
cero escrituras; rollback total = quitar flag + DROP de las dos tablas;
`created_at` queda (inofensiva, NULL-safe).

**Mordidas obligatorias de W2 (las dos del review + las tres de v0.1)**:
1. Inyectar fallo del batch de `edge_transfers` → el handler sigue ejecutándose
   Y Graph Health devuelve `telemetria_desconocida`, nunca `sin_consumo` ni
   `verificado`.
2. Robar/expirar un lease → el intento anterior queda cerrado como
   `lease_perdido` con intervalo temporal FINITO.
3. Fallo del insert de telemetría no tumba el nodo (claim y cierre).
4. Equivalencia byte a byte del resolver instrumentado vs el puro.
5. Lease ajeno no pisa la fila del dueño anterior (identidad por lease_token).

## 6. Cómo lo consume Graph Health (v0.2 de la herramienta, sin tocarla hoy)

- `extraer.py` lee `node_attempts` y `edge_transfers` filtrando por
  autoridad/engine; `datos_observados` deja de ser constante y adopta los
  estados honestos del §3 (incluyendo `telemetria_desconocida` y
  `telemetria_inconsistente` cuando contradice a `work_items`/`run_events`).
- Brechas nuevas deterministas: **G11 binding incompleto**
  (`path_missing`/`source_missing` medidos), **G12 ocupación de carril**
  (contención real con intervalos finitos), G10 recalculado sobre ejecución.
- El contrato v0.1 del reporte no cambia de esquema.

## 7. Review adversarial (resumen; crudo en review-telemetria.md)

Veredicto sobre v0.1: **BLOQUEADO**, con la tesis base declarada defendible
(tablas laterales, resolver observador, hash sin payload). Los 8 hallazgos y su
adopción en v0.2:

| # | Severidad | Hallazgo | Adopción en v0.2 |
|---|-----------|----------|------------------|
| 1 | BLOQUEANTE | identidad por `attempt` era un invariante asumido, no demostrado | PK = `lease_token`; attempt degradado a metadata |
| 2 | BLOQUEANTE | la PK de edge_transfers perdía referencias inline múltiples | PK = (lease_token, input_path, ref_ordinal) |
| 3 | BLOQUEANTE | "sin consumo" indistinguible de telemetría perdida ⇒ G1 falsos | receipt de captura por intento; sin receipt completo, `telemetria_desconocida` |
| 4 | SERIO | `lease_perdido` sin productor suficiente; ocupación histórica abierta | tercer productor (claim de lease vencido cierra el intento anterior) + `lease_until_at_claim` |
| 5 | BLOQUEANTE | el hash no era reproducible (herencia, canonicalización, source nulo) | `source_run_id`+`source_work_item_id` obligatorios en herencia; `canonical_version`; fixtures TS↔Python; estado `unverifiable` |
| 6 | SERIO | `fallback_sin_dato` inferido por comparación de strings; `?` inventado | instrumentar la RAMA del resolver (resolved/path_missing/source_missing/inline); sin semántica para `?` |
| 7 | SERIO | escribir telemetría en las transacciones soberanas (locks, dependencia operacional) | INSERT inmutable en claim SOLO con benchmark; UPDATE de cierre post-commit |
| 8 | BLOQUEANTE | `NOT NULL DEFAULT now()` inventaba historia y el ALTER arriesga cola de locks | migración en dos pasos, NULL = desconocido, `lock_timeout='1s'` |

Lo que el review confirmó como correcto y no se re-litiga: mantener
EDGE_TRANSFER fuera de run_events mientras sea observabilidad; no tocar la
atomicidad de NODE_SUCCEEDED con el cierre; `lease_token` como identidad del
intento físico; resolver puro con observador alrededor; no guardar payload;
flag y reversibilidad de las tablas laterales.
