Manual de Evidencia JSON (Recetas de Plantilla)

A primera vista

Qué: Salidas de la herramienta Bridge a Decision Gate utilizando archivos JSON/YAML y consultas JSONPath Por qué: Evitar la ejecución arbitraria de código mientras se habilitan puertas para cualquier herramienta que pueda emitir JSON Quién: Desarrolladores que integran herramientas (pruebas, linters, escáneres) con Decision Gate Requisitos previos: Conceptos básicos de condiciones (ver condition_authoring.md)

¿Por qué JSON Evidence?

El proveedor json incorporado lee archivos JSON/YAML locales y evalúa expresiones JSONPath. Eso te proporciona:

No se ejecuta código en el Decision Gate: DG solo lee artefactos.
Integración independiente de herramientas: cualquier herramienta que emita JSON/YAML puede ser restringida.
Evaluación determinista: mismo archivo + mismo JSONPath -> misma evidencia.

JSONPath Esenciales

JSONPath extrae valores de un documento JSON.

JSONPath	Significado	Ejemplo
`$`	Objeto raíz	`$` (documento completo)
`.field`	Acceder al campo del objeto	`$.version` -> `"1.2.3"`
`.nested.field`	Acceder al campo anidado	`$.summary.failed` -> `0`
`[index]`	Elemento de array	`$.items[0]` -> primer elemento
`[*]`	Todos los elementos del array	`$.items[*].id` -> todos los IDs
`..field`	Descenso recursivo	`$..errors` -> todos los campos `errors`

Ejemplo de documento JSON:

{
  "version": "1.0",
  "summary": { "failed": 0, "passed": 128 },
  "items": [
    { "id": 1, "status": "pass" },
    { "id": 2, "status": "fail" }
  ]
}

Consultas de ejemplo:

$.version -> "1.0"
$.summary.failed -> 0
$.items[*].id -> [1, 2]

Comportamiento de coincidencia del proveedor JSON

El proveedor json se comporta de la siguiente manera:

Si se omite params.jsonpath -> devuelve todo el documento JSON/YAML.
Si JSONPath coincide con un valor -> devuelve ese valor.
Si JSONPath coincide con múltiples valores -> devuelve un array de valores coincidentes.
Si JSONPath no coincide con nada -> devuelve EvidenceResult.error con el código jsonpath_not_found y value = None.
Si JSONPath es inválido -> devuelve EvidenceResult.error con código invalid_jsonpath y value = None.

El proveedor no devuelve JSON null para rutas faltantes; devuelve ningún valor (value = None).

Archivo del Proveedor JSON y Reglas de Análisis

Límite de tamaño de archivo: max_bytes (por defecto 1_048_576). Tamaño excesivo devuelve size_limit_exceeded.
Soporte YAML: habilitado cuando allow_yaml = true y la extensión del archivo es .yaml/.yml.
Root restriction: root and root_id are required. File paths are relative to root. Restricción de raíz: root y root_id son requeridos. Las rutas de archivo son relativas a root. Las rutas absolutas devuelven absolute_path_forbidden; las escapadas devuelven path_outside_root.
Anclas: las anclas de evidencia utilizan file_path_rooted con root_id y la path relativa.
Errores de análisis: JSON no válido -> invalid_json; YAML no válido -> invalid_yaml; YAML deshabilitado -> yaml_disabled.

Todos los errores de archivo/JSONPath se devuelven a través de EvidenceResult.error (no errores de JSON-RPC).

Patrón de flujo de trabajo: Herramienta -> JSON -> Puerta

1. Run tool (outside DG) -> emit JSON file
2. Define condition (json.path + comparator + expected)
3. scenario_next -> DG reads file, extracts value, evaluates condition

Ejemplo de condición:

{
  "condition_id": "tests_ok",
  "query": {
    "provider_id": "json",
    "check_id": "path",
    "params": { "file": "test-results.json", "jsonpath": "$.summary.failed" }
  },
  "comparator": "equals",
  "expected": 0,
  "policy_tags": []
}

Recetas de Plantilla

Estos son ejemplos, no estándares. Úsalos como puntos de partida.

Plantilla 1: Resultados de la Prueba

Tool output (ejemplo):

{
  "summary": { "failed": 0, "passed": 128 },
  "tool": "tests",
  "version": "1.0"
}

Condición:

{
  "condition_id": "tests_ok",
  "query": {
    "provider_id": "json",
    "check_id": "path",
    "params": { "file": "report.json", "jsonpath": "$.summary.failed" }
  },
  "comparator": "equals",
  "expected": 0,
  "policy_tags": []
}

Desajuste de tipo (comportamiento exacto):

{ "summary": { "failed": "0" } }

El valor de evidencia es string; se esperaba number.
equals devuelve false (no unknown).

Plantilla 2: Umbral de Cobertura

Tool output (ejemplo):

{ "coverage": { "percent": 92 } }

Condición:

{
  "condition_id": "coverage_ok",
  "query": {
    "provider_id": "json",
    "check_id": "path",
    "params": { "file": "coverage.json", "jsonpath": "$.coverage.percent" }
  },
  "comparator": "greater_than_or_equal",
  "expected": 85,
  "policy_tags": []
}

Incompatibilidad de tipo para comparadores de ordenación:

{ "coverage": { "percent": "92%" } }

El valor de evidencia es string, no un número o una fecha RFC3339.
greater_than_or_equal devuelve desconocido.

Plantilla 3: Resumen del Escaneo de Seguridad

Tool output (ejemplo):

{ "summary": { "critical": 0, "high": 0, "medium": 2 } }

Condición:

{
  "condition_id": "no_critical",
  "query": {
    "provider_id": "json",
    "check_id": "path",
    "params": { "file": "scan.json", "jsonpath": "$.summary.critical" }
  },
  "comparator": "equals",
  "expected": 0,
  "policy_tags": []
}

Plantilla 4: Conteo de Aprobaciones de Revisión

Tool output (ejemplo):

{ "reviews": { "approvals": 2 } }

Condición:

{
  "condition_id": "approvals_ok",
  "query": {
    "provider_id": "json",
    "check_id": "path",
    "params": { "file": "reviews.json", "jsonpath": "$.reviews.approvals" }
  },
  "comparator": "greater_than_or_equal",
  "expected": 2,
  "policy_tags": []
}

Plantilla 5: Indicadores Booleanos Explícitos

Tool output (ejemplo):

{ "checks": { "lint_ok": true, "format_ok": true } }

Condición:

{
  "condition_id": "lint_ok",
  "query": {
    "provider_id": "json",
    "check_id": "path",
    "params": { "file": "quality.json", "jsonpath": "$.checks.lint_ok" }
  },
  "comparator": "equals",
  "expected": true,
  "policy_tags": []
}

Depuración de evidencia JSON de manera precisa

Utilice evidence_query para Errores del Proveedor

scenario_next no devuelve valores de evidencia ni errores de proveedor por defecto. Si se permite la retroalimentación, scenario_next puede devolver resúmenes de trazas/evidencias. Para depurar la evidencia JSON:

Llama a evidence_query con la misma query y cualquier context válido.
Inspeccionar EvidenceResult.error y evidence_anchor.

Códigos de Error Comunes del Proveedor JSON

Estos códigos provienen del proveedor json incorporado:

params_missing, params_invalid
archivo_no_encontrado, error_al_abrir_archivo, error_al_leer_archivo
size_limit_invalid, size_limit_exceeded
json_no_válido, yaml_no_válido, yaml_deshabilitado
invalid_jsonpath, jsonpath_not_found
invalid_root, path_outside_root

Otros proveedores pueden devolver provider_error (un envoltorio alrededor de fallos internos).

Guía de Diseño (Esquemas JSON Estables)

Mantener los resúmenes planos y estables.
Prefer escalas (números, booleanos) para la amabilidad del comparador.
Evite la anidación profunda ($.a.b.c.d) a menos que sea necesario.
Incluya un campo version si controla el esquema y espera evolución.

Rutas de Aprendizaje de Referencia Cruzada

getting_started.md -> condition_authoring.md -> ESTE GUIA
ESTE GUIA -> provider_development.md (cuando JSON no es suficiente)
ESTE GUIA -> llm_native_playbook.md (flujos de trabajo de prechequeo)

Glosario

JSONPath: Lenguaje de consulta para extraer valores de documentos JSON. Comparator: Operador que compara evidencias con valores esperados. Evidence: Salida del proveedor más metadatos (hashes, anclajes, errores). Condition: Definición de verificación de evidencia en un escenario.