Llibre de jugades d’evidència JSON (Recepcions de plantilla)

A Simple Vista

Què: Sortides de l’eina Bridge a Decision Gate mitjançant fitxers JSON/YAML i consultes JSONPath Per què: Evitar l’execució arbitrària de codi mentre s’habiliten portes per a qualsevol eina que pugui emetre JSON Qui: Desenvolupadors que integren eines (proves, linters, escàners) amb Decision Gate Requisits previs: Fonaments de condicions (vegeu condition_authoring.md)

Per què JSON Evidence?

El proveïdor json integrat llegeix fitxers JSON/YAML locals i avalua expressions JSONPath. Això et proporciona:

No s’executa codi a la Decision Gate: DG només llegeix artefactes.
Integració independent de l’eina: qualsevol eina que emeti JSON/YAML pot ser restringida.
Avaluació determinista: mateix fitxer + mateix JSONPath -> mateixa evidència.

JSONPath Essentials

JSONPath extreu valors d’un document JSON.

JSONPath	Significat	Exemple
`$`	Objecte arrel	`$` (document complet)
`.field`	Accedir al camp de l’objecte	`$.version` -> `"1.2.3"`
`.nested.field`	Accedir al camp anidat	`$.summary.failed` -> `0`
`[index]`	Element de l’array	`$.items[0]` -> primer element
`[*]`	Tots els elements de l’array	`$.items[*].id` -> tots els IDs
`..field`	Descens recursiu	`$..errors` -> tots els camps `errors`

Exemple de document JSON:

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

Consultes d’exemple:

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

Comportament de coincidència del proveïdor JSON

El proveïdor json es comporta de la següent manera:

Si params.jsonpath és omès -> retorna tot el document JSON/YAML.
Si JSONPath coincideix amb un valor -> retorna aquest valor.
Si JSONPath coincideix amb múltiples valors -> retorna un array de valors coincidents.
Si JSONPath no coincideix amb res -> retorna EvidenceResult.error amb codi jsonpath_not_found i value = None.
Si JSONPath és invàlid -> retorna EvidenceResult.error amb codi invalid_jsonpath i value = None.

El proveïdor no retorna JSON null per a rutes que falten; retorna cap valor (value = None).

Fitxer de Proveïdor JSON i Regles d’Anàlisi

Límit de mida de fitxer: max_bytes (per defecte 1_048_576). Si és massa gran, retorna size_limit_exceeded.
Suport YAML: habilitat quan allow_yaml = true i l’extensió del fitxer és .yaml/.yml.
Root restriction: root and root_id are required. File paths are relative to root. Restricció de root: root i root_id són requerits. Els camins de fitxer són relatius a root. Els camins absoluts retornen absolute_path_forbidden; les escapades retornen path_outside_root.
Ancoratges: els ancoratges d’evidència utilitzen file_path_rooted amb root_id i el path relatiu.
Errors de parsing: JSON no vàlid -> invalid_json; YAML no vàlid -> invalid_yaml; YAML desactivat -> yaml_disabled.

Tots els errors de fitxer/JSONPath es retornen a través de EvidenceResult.error (no errors de JSON-RPC).

Patró de Flux de Treball: Eina -> JSON -> Portó

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

Exemple de condició:

{
  "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": []
}

Plantilles de receptes

Aquests són exemples, no estàndards. Utilitzeu-los com a punts de partida.

Plantilla 1: Resultats de la prova

Eina de sortida (exemple):

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

Condició:

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

Incompatibilitat de tipus (comportament exacte):

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

El valor de l’evidència és cadena; s’esperava número.
equals retorna fals (no desconegut).

Plantilla 2: Llindar de cobertura

Eina de sortida (exemple):

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

Condició:

{
  "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": []
}

Incompatibilitat de tipus per a comparadors d’ordenació:

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

El valor de l’evidència és string, no un número ni una data RFC3339.
greater_than_or_equal retorna desconegut.

Plantilla 3: Resum de l’Escaneig de Seguretat

Eina de sortida (exemple):

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

Condició:

{
  "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: Comptador d’ aprovacions de revisió

Eina de sortida (exemple):

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

Condició:

{
  "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: Flags Booleanes Explícits

Eina de sortida (exemple):

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

Condició:

{
  "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ó de proves JSON de manera precisa

Utilitzeu evidence_query per Errors del Proveïdor

scenario_next no retorna valors d’evidència ni errors del proveïdor per defecte. Si es permet la retroalimentació, scenario_next pot retornar resums de traç/evidència. Per depurar l’evidència JSON:

Crida evidence_query amb la mateixa query i qualsevol context vàlid.
Inspeccioneu EvidenceResult.error i evidence_anchor.

Codi d’Error Comú del Proveïdor JSON

Aquests codis provenen del proveïdor json integrat:

params_missing, params_invalid
fitxer_no_trobat, fitxer_obrir_fallat, fitxer_llegir_fallat
size_limit_invalid, size_limit_exceeded
invalid_json, invalid_yaml, yaml_disabled
invalid_jsonpath, jsonpath_not_found
arrel_invàlida, camí_fora_arrel

Altres proveïdors poden retornar provider_error (un embolcall al voltant de fallades internes).

Guia de Disseny (Esquemes JSON Estables)

Mantingueu els resums plans i estables.
Prefer escalars (números, booleans) per a la compatibilitat amb comparadors.
Eviteu la profunditat de la jerarquia ($.a.b.c.d) llevat que sigui necessari.
Inclou un camp version si controles l’esquema i esperes evolució.

Camins d’Aprenentatge de Referència Creuada

getting_started.md -> condition_authoring.md -> AQUESTA GUIA
AQUESTA GUIA -> provider_development.md (quan JSON no és suficient)
AQUESTA GUIA -> llm_native_playbook.md (precomprovacions de fluxos de treball)

Glossari

JSONPath: Llenguatge de consulta per extreure valors de documents JSON. Comparator: Operador que compara evidències amb valors esperats. Evidence: Sortida del proveïdor més metadades (hashos, ancoratges, errors). Condition: Definició de la comprovació d’evidències en un escenari.