Guía de Autorización del Esquema del Proveedor (Autónoma)

Este documento tiene la intención de ser exhaustivo y autónomo. Puede cargar este archivo solo para redactar un contrato JSON del proveedor de Decision Gate, pero la corrección aún depende de la validación y de la implementación de su proveedor.

Si solo recuerdas una frase: Decision Gate evalúa evidencia. No ejecuta tareas arbitrarias.

---

1) Qué es un Decision Gate (Objetivo y Modelo Mental)

La Puerta de Decisión (DG) responde a una única pregunta: “¿Se ha hecho X?”

Evalúa evidencia contra condiciones, combinando los resultados con un Árbol de Evaluación de Requisitos (RET) y decidiendo si un gate pasa.

DG es data-first:

• Herramientas, scripts o servicios que se ejecutan fuera de DG.
• Esas herramientas emiten evidencia (JSON o bytes).
• DG evalúa que la evidencia es determinista.

Canal de evaluación central

EvidenceQuery -> Provider -> EvidenceResult -> Comparator -> Tri-state
               -> RET -> Gate outcome

• Los resultados de tres estados son true, false o unknown.
• Evidencia faltante o error del proveedor produce unknown (fail-closed).
• Comparator type mismatches may yield unknown or false/true depending on the Los desajustes en el tipo de comparador pueden dar como resultado unknown o false/true dependiendo del comparador (ver Sección 7).
• Las puertas solo se abren cuando el RET evalúa a true.

Modos de obtención de evidencia

1. Provider-pulled evidence (live runs)
   • DG llama a un proveedor para obtener evidencia.
2. Asserted evidence (precheck only)
   • El llamador proporciona evidencia directamente; no se muta ningún estado de ejecución.
3. Audit submissions (scenario_submit)
   • Almacenado para auditoría, pero no afecta la evaluación.

Esta guía se centra en proveedores y sus contratos de proveedor.

---

2) Glosario (Términos Esenciales)

• Proveedor: Una fuente de datos que puede responder a consultas de evidencia.
• Provider contract: A JSON document describing provider capabilities, Contrato del proveedor: Un documento JSON que describe las capacidades del proveedor, esquemas y comparadores permitidos (esto es lo que estás redactando).
• Provider check: A single queryable capability exposed by a provider. Verificación del proveedor: Una capacidad consultable única expuesta por un proveedor. Las verificaciones del proveedor viven dentro del contrato del proveedor bajo checks.
• Scenario condition: A condition in a ScenarioSpec that references a Condición del escenario: Una condición en un ScenarioSpec que hace referencia a una verificación de proveedor a través de query.check_id. No confunda estos dos conceptos.
• EvidenceQuery: { provider_id, check_id, params } enviado a un proveedor.
• EvidenceResult: Respuesta del proveedor con value más un hash/ancla opcional.
• Comparador: Operador que compara evidencia con un valor esperado.
• RET: Árbol de Evaluación de Requisitos que combina los resultados de las condiciones.
• Determinism: Classification of provider checks:
  • determinista, dependiente del tiempo o externo.

---

3) Protocolo del Proveedor (Lo que los Proveedores Realmente Hacen)

Los proveedores implementan una única herramienta MCP llamada evidence_query y devuelven un EvidenceResult dentro de la respuesta de la herramienta.

Forma de EvidenceQuery

{
  "provider_id": "string",
  "check_id": "string",
  "params": { "any": "json" }
}

• params es opcional. Si está presente, debe coincidir con el params_schema de la verificación.
• La mayoría de los proveedores integrados requieren que params sea un objeto JSON.

Forma de EvidenceResult (el valor es lo que describe su contrato)

{
  "value": { "kind": "json|bytes", "value": "any" } | null,
  "lane": "verified|asserted",
  "error": { "code": "string", "message": "string", "details": "any|null" } | null,
  "evidence_hash": { "algorithm": "sha256", "value": "hex" } | null,
  "evidence_ref": { "uri": "string" } | null,
  "evidence_anchor": { "anchor_type": "string", "anchor_value": "string" } | null,
  "signature": { "scheme": "string", "key_id": "string", "signature": [0] } | null,
  "content_type": "string|null"
}

Notas:

• Todos los campos son obligatorios en el esquema; use null cuando estén ausentes.
• evidence_anchor.anchor_value is a string. If an anchor policy requires evidence_anchor.anchor_value es una cadena. Si una política de anclaje requiere campos, esta cadena debe ser JSON canónico para un objeto (ver Sección 9).
• signature.signature es un array de bytes (array JSON de enteros de 0 a 255).

Su contrato de proveedor debe describir la forma de params y value devuelta aquí. DG nunca confía en que los proveedores decidan los resultados de las puertas de decisión.

---

4) Qué es un Contrato de Proveedor (Por qué existe)

Un contrato de proveedor (contrato de capacidad) es el esquema de evidencia. Declara:

• ¿Qué verificaciones de proveedor existen (nombres + descripciones)?
• Parámetros requeridos para cada verificación.
• Esquemas de resultados para cada verificación.
• Qué comparadores están permitidos para cada verificación.
• Clasificación del determinismo, anclajes, tipos de contenido y ejemplos.

DG utiliza el contrato para:

• Validar las condiciones de ScenarioSpec.
• Hacer cumplir las listas de permitidos del comparador por verificación.
• Generar herramientas y formularios de interfaz de usuario.
• Soporte para el descubrimiento de LLMs y herramientas de autoría.

Si un contrato de proveedor es incorrecto o incompleto, la autoría del escenario será incorrecta, y la evaluación fallará.

---

5) Contrato de Proveedor JSON: Especificación Completa

Un contrato es un único objeto JSON con los siguientes campos requeridos. Los campos marcados como opcionales pueden omitirse.

5.1 Campos de nivel superior (requeridos a menos que se indique lo contrario)

• provider_id (string, required)

  • Identificador estable utilizado en EvidenceQuery.provider_id.
  • usa_snake_case_y_manténlo_estable.

• name (string, required)

  • Nombre legible por humanos para la interfaz de usuario y las herramientas.

• description (string, required)

  • Qué fuente de evidencia representa este proveedor.

• transport (string, required)

  • Debe ser “mcp” (proveedores externos) o “builtin” (integrados).
  • Los contratos de proveedores externos deben establecer transport: “mcp” o serán rechazados.

• notes (array of strings, required)

  • Notas libres para humanos y LLMs.
  • Use [] si no hay notas.

• config_schema (JSON Schema, required)

  • Esquema para el bloque de configuración del proveedor en decision-gate.toml.
  • The contract schema accepts any JSON Schema value, but **Decision Gate tooling El esquema del contrato acepta cualquier valor de JSON Schema, pero las herramientas de Decision Gate asumen un esquema de objeto. Utilice un esquema de objeto con additionalProperties: false.
  • If the provider has no config, use:

    { "type": "object", "additionalProperties": false, "properties": {} }
    

• checks (array, required)

  • Cada entrada es una definición de verificación de proveedor.
  • El array puede estar vacío, pero entonces el proveedor no expone ninguna verificación utilizable.

5.2 Comprobar campos (todos requeridos)

Cada entrada en checks define una verificación de proveedor.

• check_id (string)

  • Identificador estable utilizado en EvidenceQuery.check_id.
  • usa_snake_case_y_manténlo_estable.

• description (string)

  • Describe lo que significa el valor devuelto, no cómo se obtiene.

• determinism (string)

  • Uno de: determinista, dependiente del tiempo, externo.

• params_required (boolean)

  • Verdadero si se deben proporcionar parámetros; falso si los parámetros son opcionales o ninguno.

• params_schema (JSON Schema)

  • Esquema para EvidenceQuery.params.
  • Utilice un esquema de objeto y establezca additionalProperties: false (recomendado).
  • If no params, use:

    { "type": "object", "additionalProperties": false, "properties": {} }
    

• result_schema (JSON Schema)

  • Esquema para el valor de la evidencia (EvidenceResult.value.value).
  • Usa el esquema más ajustado posible.

• allowed_comparators (array of strings)

  • Lista de permitidos del comparador para esta verificación.
  • Debe ser no vacío y estar en orden canónico (ver la lista de la Sección 7).
  • Debería ser compatible con result_schema y reglas de validación estrictas.

• anchor_types (array of strings)

  • Tipos de anclaje que esta verificación puede emitir.
  • Use [] si ninguno.

• content_types (array of strings)

  • Tipos MIME para EvidenceResult.content_type.
  • Puede estar vacío ([]) para significar “no especificado”.
  • Si está presente, use tipos MIME válidos (por ejemplo, application/json).

• examples (array of objects)

  • Cada ejemplo es { “description”: ”…”, “params”: { … }, “result”: … }.
  • El esquema permite un array vacío, pero se recomiendan encarecidamente ejemplos.

---

6) Guía de JSON Schema (Parámetros y Resultados)

DG utiliza JSON Schema (borrador 2020-12) para validar parámetros y resultados. Mantenga los esquemas precisos y mínimos.

Reglas del esquema de parámetros (recomendado)

• Utilice type: "object".
• Establecer additionalProperties: false.
• Declare required para cada campo obligatorio.
• Prefiera tipos y límites explícitos.

Reglas del esquema de resultados

• Describe el valor real de la evidencia, no el envoltorio EvidenceResult.
• Use the narrowest possible type (boolean, integer, number, string, Utilice el tipo más estrecho posible (boolean, integer, number, string, array, object o null).
• If you need multiple types, use oneOf / anyOf. Strict validation Si necesita múltiples tipos, utilice oneOf / anyOf. La validación estricta interseca las concesiones del comparador en todas las variantes.

Resultados de bytes (caso especial)

Si el proveedor devuelve EvidenceValue::Bytes, el valor de evidencia se compara como bytes. Esquema recomendado:

{
  "type": "array",
  "items": { "type": "integer", "minimum": 0, "maximum": 255 }
}

Para la evidencia de bytes, solo equals y not_equals son válidos en tiempo de ejecución. Restringir allowed_comparators en consecuencia.

Resultados dinámicos (salida de emergencia)

Si una verificación puede devolver formas JSON arbitrarias que no se pueden expresar, marque el esquema de resultado como dinámico:

{
  "description": "Dynamic JSON result",
  "x-decision-gate": { "dynamic_type": true }
}

Los esquemas dinámicos permiten todos los comparadores en validación estricta, pero los comparadores lex/deep aún requieren banderas de configuración (ver Sección 8).

---

7) Semántica y Compatibilidad del Comparador

Los comparadores convierten la evidencia en resultados de tres estados. Para los comparadores que requieren expected, la falta de expected produce unknown.

Lista de comparadores (orden canónico)

• equals
• not_equals
• greater_than
• greater_than_or_equal
• less_than
• less_than_or_equal
• lex_greater_than
• lex_greater_than_or_equal
• lex_less_than
• lex_less_than_or_equal
• contiene
• in_set
• deep_equals
• deep_not_equals
• exists
• not_exists

Utilice este orden al redactar allowed_comparators.

Semántica de tiempo de ejecución (núcleo de Decision Gate)

• equals / not_equals: JSON equality. Numbers are compared as decimals equals / not_equals: igualdad JSON. Los números se comparan como decimales (10 == 10.0). Las incompatibilidades de tipo devuelven false / true respectivamente.
• greater_than / less_than (and _or_equal):
  • Orden numérico para números JSON.
  • Temporal ordering for strings that parse as RFC3339 date-time or date-only Ordenamiento temporal para cadenas que se analizan como fecha-hora o solo fecha RFC3339 (YYYY-MM-DD) en ambos lados. De lo contrario, desconocido.
• lex_*: Orden lexicográfico solo para cadenas; de lo contrario unknown.
• contains:
  • Cadenas: contención de subcadenas.
  • Arrays: evidence array contains all elements of the expected array Arrays: el array de evidencia contiene todos los elementos del array esperado (solo membresía, no conteos de multiconjunto).
• in_set:
  • Se esperaba que fuera un array.
  • La evidencia debe ser escalar (no objeto/array). La pertenencia utiliza igualdad JSON.
• exists / not_exists:
  • Ignorar lo esperado.
  • Verifique únicamente si EvidenceResult.value está presente.
  • JSON null cuenta como presente.
• deep_equals / deep_not_equals:
  • Solo para arrays u objetos; de lo contrario, unknown.

Compatibilidad de validación estricta (predeterminado en decision-gate-mcp)

La puerta de decisión MCP realiza una validación estricta de comparadores/tipos por defecto. Un comparador de ScenarioSpec debe:

1. Estar presente en la lista allowed_comparators del contrato del proveedor.
2. Ser permitido por la clasificación del tipo de esquema de resultado.
3. Ser habilitado por la configuración (las familias lex/deep están desactivadas por defecto).

Asignaciones por tipo de esquema de resultado (validación estricta):

• boolean

  • Permitido: equals, not_equals, in_set, exists, not_exists

• integer / number

  • Allowed: equals, not_equals, greater_than, greater_than_or_equal, Permitido: equals, not_equals, greater_than, greater_than_or_equal, less_than, less_than_or_equal, in_set, exists, not_exists

• string (no format)

  • Permitido: equals, not_equals, contains, in_set, exists, not_exists
  • Optar por: lex_* (ver Sección 8)

• string with format: "date" or format: "date-time"

  • Allowed: equals, not_equals, greater_than, greater_than_or_equal, Permitido: equals, not_equals, greater_than, greater_than_or_equal, less_than, less_than_or_equal, in_set, exists, not_exists

• string with format: "uuid"

  • Permitido: equals, not_equals, in_set, exists, not_exists

• enum (scalar values only)

  • Permitido: equals, not_equals, in_set, exists, not_exists

• array with scalar items

  • Permitido: contains, exists, not_exists
  • Optar por: deep_equals, deep_not_equals (ver Sección 8)

• array with complex items

  • Permitido: exists, not_exists
  • Optar por: deep_equals, deep_not_equals

• object

  • Permitido: exists, not_exists
  • Optar por: deep_equals, deep_not_equals

• null

  • Permitido: equals, not_equals, exists, not_exists

• dynamic (x-decision-gate.dynamic_type: true)

  • Permitido: todos los comparadores (sujeto a las banderas de configuración)

Si la validación estricta está desactivada (validation.strict = false con validation.allow_permissive = true), se omiten las comprobaciones de compatibilidad del esquema, pero aún se aplican las semánticas del comparador en tiempo de ejecución.

---

8) Comparadores de Opt-in (Lex y Deep)

Los comparadores de igualdad lexicográfica y profunda son optativos en la validación estricta para esquemas no dinámicos y requieren dos pasos:

1. Enable in decision-gate.toml:

   • validation.enable_lexicographic = true
   • validation.enable_deep_equals = true

2. Declarar las opciones de aceptación en el esquema de resultados (para esquemas no dinámicos):

"result_schema": {
  "type": "string",
  "x-decision-gate": {
    "allowed_comparators": ["lex_greater_than", "lex_less_than"]
  }
}

Reglas adicionales:

• The comparator must also appear in the provider contract’s El comparador también debe aparecer en la lista allowed_comparators del contrato del proveedor.
• If x-decision-gate.allowed_comparators is present, every comparator Si x-decision-gate.allowed_comparators está presente, cada comparador utilizado por los escenarios debe estar listado allí.
• For dynamic schemas (dynamic_type: true), schema opt-in is not required, Para esquemas dinámicos (dynamic_type: true), no se requiere optar por el esquema, pero aún se aplican las banderas de configuración.

---

9) Metadatos de Evidencia: Anclas y Tipos de Contenido

Los contratos declaran qué metadatos de evidencia un proveedor puede emitir.

• anchor_types: Strings describing anchor kinds (for audit or external references). Examples: file_path_rooted, url, receipt_id, log_offset. anchor_types: Cadenas que describen tipos de anclaje (para auditoría o referencias externas). Ejemplos: file_path_rooted, url, receipt_id, log_offset. Use [] si no se emiten anclajes.

• content_types: MIME types of the evidence value. Examples:

  • application/json
  • text/plain
  • aplicación/octet-stream

Los valores de EvidenceResult.content_type deben coincidir con esta lista cuando estén presentes. Una lista vacía significa “no especificado” (las políticas lo tratan como un comodín).

Nota sobre el valor del ancla: EvidenceResult.evidence_anchor.anchor_value es una cadena. Si configuras una política de anclaje que requiere campos, esta cadena debe ser JSON canónico para un solo objeto con campos escalares. Para anclajes basados en archivos, file_path_rooted utiliza campos escalares root_id y path (solo rutas relativas).

---

10) Clasificación del Determinismo (Sé Honesto)

• determinista: La salida depende únicamente de las entradas y del estado interno.
• time_dependent: La salida depende del tiempo, pero es determinista dado el tiempo.
• externo: La salida depende del estado externo (red, base de datos, APIs).

Esta clasificación se utiliza para la auditoría y el razonamiento de confianza. No etiquetar incorrectamente.

---

11) Flujo de trabajo de autoría de extremo a extremo (Humanos o LLMs)

Paso 1: Reunir los insumos requeridos

Deberías tener todo lo siguiente para cada verificación de proveedor:

• Verifique el nombre y la descripción (lo que significa el resultado).
• Clasificación del determinismo.
• Esquema de parámetros (JSON Schema o lista completa de parámetros con tipos/requeridos).
• Esquema de resultados (Esquema JSON para el valor de evidencia).
• Comparadores permitidos (o permitir que el autor los derive estrictamente).
• Al menos un par de parámetros de ejemplo + resultado (recomendado).
• Tipos de anclaje y tipos de contenido (o explícitamente “ninguno”).

Paso 2: Mapear entradas a campos del contrato

• Convertir nombres a identificadores estables en snake_case.
• Traducir los tipos de solicitud en params_schema.
• Traducir los valores de respuesta en result_schema.
• Elija las listas de permitidos del comparador de la Sección 7 y las reglas de validación estrictas.

Paso 3: Validar internamente

• Asegúrese de que params_schema y result_schema sean esquemas JSON válidos.
• Asegúrese de que allowed_comparators no esté vacío y esté en orden canónico.
• Asegúrese de que las listas de comparadores sean compatibles con las reglas de validación estrictas.
• Asegúrese de que los ejemplos (si se proporcionan) coincidan con los esquemas.
• Asegúrese de que content_types y anchor_types sean precisos.

Paso 4: Producir el JSON final

• Salida solo en JSON.
• Evitar markdown en la salida final.

---

12) Hoja de Trabajo de Admisión del Proveedor (Plantilla)

Copia/pega y completa esto antes de redactar el contrato:

Provider
- provider_id:
- name:
- description:
- transport: mcp | builtin
- config_schema (JSON Schema):
- notes (required; use [] if none):

Checks (repeat per check)
- name:
- description (what the value means):
- determinism: deterministic | time_dependent | external
- params_required: true | false
- params_schema (JSON Schema):
- result_schema (JSON Schema):
- allowed_comparators (if known):
- anchor_types (array or empty):
- content_types (array; can be empty):
- examples (recommended):
  - description:
  - params:
  - result:

Si falta algún campo, no adivine. Pídalo explícitamente.

---

13) LLM Autoría de Prompt (Estricto, Autocontenido)

Utilice este aviso verbatim con un LLM, junto con la hoja de trabajo completada y cualquier definición de OpenAPI o tipo. Este aviso está diseñado para prevenir la alucinación y forzar preguntas explícitas cuando falta información.

You are generating a Decision Gate provider contract JSON.

Rules:
- Output JSON only (no markdown).
- Do not assume missing information. If any required field is missing or
  ambiguous, output a JSON object with a single key "questions" containing an
  array of clarifying questions, then stop.
- Use this exact contract shape:
  provider_id, name, description, transport, config_schema, notes, checks.
- Each check must include:
  check_id, description, determinism, params_required, params_schema, result_schema,
  allowed_comparators, anchor_types, content_types, examples.
- allowed_comparators must be non-empty and in canonical order.
- Comparators must be compatible with strict validation rules for the result_schema.
- If you include lex_* or deep_* comparators and the result_schema is not dynamic,
  also add result_schema.x-decision-gate.allowed_comparators.
- Note that server config must enable lex/deep comparator families for them to be used.
- Provide at least one example per check unless explicitly told to omit.

Inputs:
- Provider worksheet:
- OpenAPI/DTO schemas (if any):
- Example requests/responses (if any):

Return the final contract JSON.

---