Arxi Puerta de Decisión Asset Core
Docs
Documentos de Decision Gate

Evaluación de puertas determinista, reproducible con decisiones auditables.

Documentación de Asset Core

Libro de Cocina para la Autorización de Condiciones

A primera vista

Qué: Definir condiciones que evalúen de manera determinista y validen de forma clara Por qué: Las condiciones conectan puertas a evidencia; la precisión es importante Quién: Desarrolladores y operadores que redactan escenarios de Decision Gate Requisitos previos: evidence_flow_and_execution_model.md

¿Qué es una Condición?

Una condición es una verificación de evidencia:

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

Consiste en:

  1. Consulta: qué evidencia recuperar.
  2. Comparador: cómo comparar.
  3. Valor esperado: el valor con el que comparar (si es necesario).

Resultados de Tri-State

Los comparadores devuelven TriState:

  • verdadero
  • falso
  • desconocido

Reglas clave (exactas):

  • Si EvidenceResult.value está faltante, el resultado es unknown (excepto exists/not_exists).
  • Si expected está faltante, el resultado es unknown (excepto exists/not_exists).
  • equals / not_equals devuelve false/true en caso de desajuste de tipo.
  • Ordering, lexicográfico, contiene, in_set, deep_* devuelve unknown en caso de desajuste de tipo.

Referencia del Comparador

Reglas Generales

  • exists/not_exists verifica la presencia de EvidenceResult.value, no null de JSON.
  • JSON null es un valor presente (por lo que exists devuelve verdadero).

Tabla de Comparadores

ComparadorTipos de EvidenciaRequerido EsperadoComportamiento de Desajuste de Tipo
equalscualquier valor JSON, bytessídevuelve false
not_equalscualquier valor JSON, bytessídevuelve true
greater_than / >= / < / <=número o cadena de fecha/hora RFC3339síunknown
lex_*cadenasíunknown
containscadena o arraysíunknown
in_setJSON escalarsí (array)unknown
deep_equals / deep_not_equalsobjeto o arraysíunknown
exists / not_existscualquiernon/a

Detalles

Igualdad (equals, not_equals)

  • Los números se comparan mediante igualdad consciente de decimales (10 == 10.0).
  • Para tipos no numéricos, se utiliza la igualdad JSON.

Ordenación (greater_than, etc.)

  • Acepta números o cadenas de fecha/hora RFC3339 (incluyendo solo fecha YYYY-MM-DD).
  • Cualquier otro tipo -> unknown.

Lexicográfico (lex_*)

  • Solo cadenas; compara puntos de código Unicode.
  • Requiere configuración explícita + opción de esquema (ver “Validación estricta”).

Contiene

  • Cadena: coincidencia de subcadena.
  • Array: el array de evidencia debe contener todos los elementos del array esperado.

En Conjunto (in_set)

  • Se esperaba que fuera un array.
  • La evidencia debe ser escalar (no un array/objeto).

Deep Equals

  • Objetos/arrays solamente; tipos no coincidentes -> unknown.
  • Requiere configuración explícita + opción de esquema.

Bytes

  • Solo se definen equals / not_equals.
  • Se espera que sea un array JSON de enteros 0..255.

Validación Estricta (Activado por Defecto)

La puerta de decisión valida las condiciones en el momento de scenario_define:

  • Para las condiciones basadas en el proveedor, el contrato del proveedor define los comparadores y tipos de resultados permitidos.
  • Para la pre-verificación, el esquema de forma de datos define los comparadores y tipos permitidos.

Los comparadores especiales requieren ambos:

  1. Configurar las banderas (validation.enable_lexicographic / validation.enable_deep_equals), y
  2. Opción explícita de esquema a través de x-decision-gate.allowed_comparators (precheck) o contrato allowed_comparators.

Si la validación falla, scenario_define o precheck son rechazados.

Patrones de Proveedor

Proveedor de tiempo

  • Comprobaciones: now, after, before.
  • after/before aceptan timestamp como unix millis o cadena RFC3339.
  • after es estrictamente mayor que; before es estrictamente menor que.

proveedor env

  • Verificar: get.
  • La clave faltante devuelve value = None sin error.
  • Las claves bloqueadas o inválidas devuelven un error del proveedor (provider_error en el límite de la herramienta).

proveedor json

  • Verifique: path.
  • JSONPath no-match devuelve error.code = "jsonpath_not_found" y value = None.

Proveedor http

  • Comprobaciones: status, body_hash.
  • status devuelve un estado HTTP entero.
  • body_hash devuelve un objeto HashDigest { algorithm, value }.
  • body_hash permite solo exists / not_exists (según contrato).

Evitando unknown

Para minimizar los resultados unknown:

  1. Proporcionar expected para todos los comparadores excepto exists/not_exists.
  2. Coincidir tipos exactamente para comparadores de no igualdad.
  3. Utilice contratos de proveedor para confirmar los comparadores permitidos.

Divulgación de Evidencias

Los valores de evidencia no son devueltos por scenario_next por defecto. Utilice feedback: "evidence" si está permitido, o inspeccione la evidencia a través de:

  • Utilice evidence_query (sujeto a la política de divulgación), o
  • Exportar un runpack con runpack_export.

La política de divulgación está configurada en decision-gate.toml:

[evidence]
allow_raw_values = false
require_provider_opt_in = true

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

allow_raw es una bandera de config por proveedor (no forma parte del contrato del proveedor). Los nombres de los proveedores son únicos; los identificadores integrados (time, env, json, http) están reservados.

Checklist

  • Los IDs de condición son únicos dentro del escenario.
  • El nombre de verificación del proveedor coincide con el contrato del proveedor.
  • Se permite el comparador para el esquema de resultados.
  • El tipo de valor esperado coincide con el tipo de evidencia.
  • policy_tags presente (requerido por el esquema, puede estar vacío).

Referencias cruzadas