Grounding Check Validation

Grounding Check Validation responde a la pregunta: "Las comprobaciones gp.* del Grounding Audit son una teoría sobre la disposición de citación de LLM. ¿Se cumple esta teoría en MIS páginas?" El módulo comprueba, para cada check, si las páginas citadas pasan el check significativamente con más frecuencia que las páginas de comparación (SERP-Counterfactuals procedentes de la Citation Causality Engine).

Matemáticamente: lift = P(check aprobado | citado) / P(check aprobado | counterfactual). Lift > 1 = el check aparece con más frecuencia en páginas citadas.

Dos fases

Fase 1 — Reporting (siempre activo, solo lectura). Una ejecución de validación muestrea n URLs citadas y n URLs counterfactual (por defecto 150 por página), las renderiza a través de todos los checks gp.* y entrega por cada check lift, p-value, verdict. El resultado aparece en el panel de administración en /admin/grounding-check-validation. Sin efecto en las auditorías en curso.

Fase 2 — Bucle de feedback (opt-in, con control de acceso). Las señales con un lift positivo significativo se guardan como candidate en una tabla de observación. Un administrador las promueve o las descarta. Las señales promovidas son gestionadas — siempre que feedback_loop_enabled = true en config/grounding.php — por la Engine Capability Matrix como Tier A "observed". Por defecto, este control está DESACTIVADO. Tú decides cuándo (o si) tus datos de validación se integran en la matriz global.

Cuándo usarlo

• Quieres demostrar (para TU equipo / TUS URLs) qué teorías GEO realmente funcionan.
• Quieres respaldar empíricamente las señales Tier B de la Engine Capability Matrix antes de construir decisiones de roadmap sobre ellas.
• Realizas ejecuciones de validación periódicas (programación por defecto: cada día 17 del mes a las 04:00) y las usas como señal de auditoría para tu estrategia GEO.

Flujo de trabajo

1. Iniciar la ejecución — POST /v1/grounding/check-validations con opcional {sample_size: 150} (máx. 400). 0 créditos. Respuesta: 202 + run_id.
2. Polling — GET /v1/grounding/check-validations/{run} hasta status=completed (típicamente 2-5 min con la muestra por defecto).
3. Leer el resultado — results[] con, por cada check: check_id, signal, dimension, n_cited, cited_pass_rate, cf_pass_rate, lift, p_value, verdict (positive / neutral / negative / insufficient_data). Ordenado por lift.
4. Fase 2 (Admin) — cola de revisión — en /admin/grounding-check-validation ves las observaciones candidatas pendientes con botones de promover/rechazar. O vía API: POST /v1/grounding/signal-observations/{id}/promote y POST .../reject.
5. Activar la Fase 2 (opcional) — configura GROUNDING_VALIDATION_FEEDBACK=true en el .env. Solo entonces las señales promovidas surten efecto en la Engine Capability Matrix. Recomendación: curar las candidatas ANTES de la activación.

API

Throttling: start 10/min, Promote/Reject 30/min, GET 60-120/min.

Cómo debe leerse el Lift

Nunca leas lift de forma aislada. Léelo siempre en contexto:

• lift = 3.4 con n_cited = 2 → ruido estadístico, no es una señal.
• lift = 1.8 con n_cited = 78 y p_value = 0.001 → señal real, candidato a promoción.
• lift = NULL (en lugar de 999.0) → la tasa de aprobación counterfactual era 0, el lift es matemáticamente indefinido. Se muestra en la interfaz como —. (Es la lección deliberada del bug del CCE-Sentinel — directamente no introducimos el valor centinela.)

Limitaciones conocidas

• Requisito de CCE — sin un pipeline de Citation-Causality activo para tu equipo no hay páginas counterfactual → todos los verdicts serán insufficient_data.
• No es at-least-once-safe. El job tiene tries = 1 — ante un error transitorio, falla de forma explícita en lugar de reintentar y duplicar los conteos. Re-ejecución manual vía php artisan grounding:validate-checks --team={id}.
• Sin desglose por motor — el validador mide "fue citado" en binario, no "fue citado por ChatGPT vs. Perplexity vs. Claude".
• La promoción de Fase 2 es global — una observación promovida eleva la señal en la matriz para TODOS los equipos. No existen overrides por equipo. (La matriz es SSOT.)

Módulos relacionados

• Grounding Audit — produce las comprobaciones gp.* que se validan aquí.
• Engine Capability Matrix — objetivo de las promociones de Fase 2.
• AI Visibility Tracking — entrega los datos crudos de citas que agrega el módulo CCE.