Arxi Decision Gate Asset Core
Docs
Decision Gate Docs

Avaluació de portes determinista, reproduïble amb decisions auditable.

Asset Core docs

Condition Authoring Cookbook

A Simple Vista

Què: Definir condicions que s’avaluen de manera determinista i validen de manera neta Per què: Les condicions connecten portes a evidències; la precisió és important Qui: Desenvolupadors i operadors que redacten escenaris de Decision Gate Requisits previs: evidence_flow_and_execution_model.md

Què és una Condició?

Una condició és una comprovació d’evidència:

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

Consisteix en:

  1. Consulta: quina evidència recuperar.
  2. Comparador: com comparar.
  3. Valor esperat: el valor amb el qual comparar (si és necessari).

Tri-State Outcomes

Els comparadors retornen TriState:

  • certament
  • fals
  • desconegut

Regles clau (exactes):

  • Si EvidenceResult.value és missing, el resultat és unknown (excepte exists/not_exists).
  • Si expected és inexistent, el resultat és unknown (excepte exists/not_exists).
  • equals / not_equals retorna false/true en cas de discrepància de tipus.
  • Ordering, lexicographic, contains, in_set, deep_* retorna unknown en cas de desajustament de tipus.

Referència del Comparator

Regles Generals

  • exists/not_exists comprova la presència d’EvidenceResult.value, no null de JSON.
  • JSON null és un valor present (per tant, exists retorna true).

Taula de Comparació

ComparatorTipus d’EvidènciaRequerit EsperatComportament de Desajustament de Tipus
equalsqualsevol valor JSON, bytessíretorna false
not_equalsqualsevol valor JSON, bytessíretorna true
greater_than / >= / < / <=número o cadena de data/hora RFC3339síunknown
lex_*cadenasíunknown
containscadena o arraysíunknown
in_setJSON escalarsí (array)unknown
deep_equals / deep_not_equalsobjecte o arraysíunknown
exists / not_existsqualsevolnon/a

Detalls

Igualtat (equals, not_equals)

  • Els números es comparen mitjançant igualtat conscient dels decimals (10 == 10.0).
  • Per a tipus no numèrics, s’utilitza la igualtat JSON.

Ordenació (greater_than, etc.)

  • Accepta números o cadenes de data/hora RFC3339 (incloent només la data YYYY-MM-DD).
  • Altres tipus -> unknown.

Lexicogràfic (lex_*)

  • Cadenes només; compara punts de codi Unicode.
  • Requereix configuració explícita + opt-in de l’esquema (vegeu “Validació Estricte”).

Conté

  • Cadena: coincidència de subcadena.
  • Array: l’array d’evidències ha de contenir tots els elements de l’array esperat.

En conjunt (in_set)

  • S’espera que sigui un array.
  • L’evidència ha de ser escalar (no array/objecte).

Iguals Profunds

  • Objectes/arrays només; tipus no coincidents -> unknown.
  • Requereix configuració explícita + opt-in de l’esquema.

Bytes

  • Només equals / not_equals estan definits.
  • S’espera que sigui un array JSON d’enters 0..255.

Validació Estricta (Activat per Defecte)

La Decision Gate valida les condicions en el moment de scenario_define:

  • Per a les condicions basades en proveïdors, el contracte del proveïdor defineix els comparadors i tipus de resultat permesos.
  • Per a la prevalidació, l’esquema de forma de dades defineix els comparadors i tipus permesos.

Els comparadors especials requereixen ambdós:

  1. Configura les banderes (validation.enable_lexicographic / validation.enable_deep_equals), i
  2. Opt-in explícit del esquema a través de x-decision-gate.allowed_comparators (precheck) o contracte allowed_comparators.

Si la validació falla, scenario_define o precheck es rebutgen.

Proveïdor de Patrons

proveïdor de temps

  • Comprovacions: ara, després, abans.
  • after/before accept timestamp com unix millis o cadena RFC3339.
  • after és estrictament major que; before és estrictament menor que.

proveïdor env

  • Comprovar: get.
  • La clau que falta retorna value = None sense error.
  • Les claus bloquejades o invàlides retornen un error del proveïdor (provider_error a la frontera de l’eina).

proveïdor json

  • Comprovar: path.
  • JSONPath no-match retorna error.code = "jsonpath_not_found" i value = None.

Proveïdor http

  • Comprovacions: status, body_hash.
  • status retorna un estat HTTP enter.
  • body_hash retorna un objecte HashDigest { algorithm, value }.
  • body_hash només permet exists / not_exists (per contracte).

Evitant desconegut

Per minimitzar els resultats unknown:

  1. Proporcioneu expected per a tots els comparadors excepte exists/not_exists.
  2. Coincidència de tipus exactament per a comparadors de no igualtat.
  3. Utilitzeu contractes de proveïdor per confirmar els comparadors permesos.

Divulgació de proves

Els valors d’evidència no es retornen per defecte per scenario_next. Utilitzeu feedback: "evidence" si està permès, o inspeccioneu l’evidència a través de:

  • Utilitzeu evidence_query (subjecte a la política de divulgació), o
  • Exporta un runpack amb runpack_export.

La política de divulgació està configurada a decision-gate.toml:

[evidence]
allow_raw_values = false
require_provider_opt_in = true

[[providers]]
name = "json"
type = "builtin"
allow_raw = true

allow_raw és un config flag per proveïdor (no forma part del contracte del proveïdor). Els noms dels proveïdors són únics; els identificadors integrats (time, env, json, http) estan reservats.

Checklist

  • Els IDs de condició són únics dins del escenari.
  • El nom de la comprovació del proveïdor coincideix amb el contracte del proveïdor.
  • El comparador està permès per a l’esquema de resultats.
  • El tipus de valor esperat coincideix amb el tipus d’evidència.
  • policy_tags present (required by schema, may be empty).

Referències Creuades