Guia d’Autorització d’Esquema de Proveïdor (Autònom)

Aquest document està destinat a ser exhaustiu i autònom. Podeu pujar aquest fitxer sol per redactar un contracte JSON del proveïdor del Decision Gate, però la correcció encara depèn de la validació i de la implementació del vostre proveïdor.

Si només recordes una frase: Decision Gate avalua proves. No executa tasques arbitràries.

---

1) Què és un Decision Gate (Objectiu i Model Mental)

La Decision Gate (DG) respon a una única pregunta: “S’ha fet X?”

Això ho fa avaluant evidències contra condicions, combinant els resultats amb un Requirement Evaluation Tree (RET), i decidint si un gate passa.

DG és data-first:

• Eines, scripts o serveis que s’executen fora de DG.
• Aquests eines emeten evidència (JSON o bytes).
• DG avalua aquesta evidència de manera determinista.

Canal d’avaluació central

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

• Resultats de tres estats són true, false o unknown.
• Evidència perduda o error del proveïdor dóna unknown (fail-closed).
• Comparator type mismatches may yield unknown or false/true depending on the Les incompatibilitats del tipus de comparador poden donar lloc a unknown o false/true depenent del comparador (vegeu la Secció 7).
• Les portes només es poden passar quan el RET s’avalua com a true.

Modes de font d’evidència

1. Provider-pulled evidence (live runs)
   • DG crida un proveïdor per obtenir proves.
2. Asserted evidence (precheck only)
   • El que truca subministra proves directament; cap estat d’execució es modifica.
3. Audit submissions (scenario_submit)
   • Emmagatzemat per a l’auditoria, però no afecta l’avaluació.

Aquesta guia se centra en proveïdors i els seus contractes de proveïdor.

---

2) Glossari (Termes Essencials)

• Proveïdor: Una font de dades que pot respondre a consultes d’evidència.
• Provider contract: A JSON document describing provider capabilities, Contracte del proveïdor: Un document JSON que descriu les capacitats del proveïdor, esquemes i comparadors permesos (això és el que esteu redactant).
• Provider check: A single queryable capability exposed by a provider. Comprovació del proveïdor: Una única capacitat consultable exposada per un proveïdor. Les comprovacions del proveïdor viuen dins del contracte del proveïdor sota checks.
• Scenario condition: A condition in a ScenarioSpec that references a Condició de l’escenari: Una condició en un ScenarioSpec que fa referència a un control del proveïdor a través de query.check_id. No confongueu aquests dos conceptes.
• EvidenceQuery: { provider_id, check_id, params } enviat a un proveïdor.
• EvidenceResult: Resposta del proveïdor amb value més un hash/ancora opcional.
• Comparador: Operador que compara proves amb un valor esperat.
• RET: Arbre d’Avaluació de Requisits que combina els resultats de les condicions.
• Determinism: Classification of provider checks:
  • determinista, dependent del temps, o extern.

---

3) Protocol del Proveïdor (El que realment fan els Proveïdors)

Els proveïdors implementen una única eina MCP anomenada evidence_query i retornen un EvidenceResult dins la resposta de l’eina.

EvidenceQuery shape

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

• params és opcional. Si està present, ha de coincidir amb el params_schema de la comprovació.
• La majoria dels proveïdors integrats requereixen que params sigui un objecte JSON.

Forma de EvidenceResult (el valor és el que descriu el teu contracte)

{
  "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"
}

Notes:

• Tots els camps són obligatoris en l’esquema; utilitzeu null quan estiguin absents.
• evidence_anchor.anchor_value is a string. If an anchor policy requires evidence_anchor.anchor_value és una cadena. Si una política d’ancoratge requereix camps, aquesta cadena ha de ser JSON canònic per a un objecte (vegeu la Secció 9).
• signature.signature és un array de bytes (array JSON d’enters 0-255).

El teu contracte de proveïdor ha de descriure la forma dels params i del value retornats aquí. DG mai confia en els proveïdors per decidir els resultats de les portes.

---

4) Què és un Contracte de Proveïdor (Per què existeix)

Un contracte de proveïdor (contracte de capacitat) és l’esquema de prova. Declara:

• Quins controls de proveïdor existeixen (noms + descripcions).
• Paràmetres requerits per a cada comprovació.
• Esquemes de resultats per a cada comprovació.
• Quins comparadors estan permesos per a cada comprovació.
• Classificació del determinisme, ancoratges, tipus de contingut i exemples.

DG utilitza el contracte per:

• Valida les condicions de ScenarioSpec.
• Aplicar llistes d’acceptació de comparadors per a cada comprovació.
• Generar eines i formularis d’UI.
• Suport per a la descoberta de LLMs i eines d’autoria.

Si un contracte de proveïdor és incorrecte o incomplet, l’autoria de l’escenari serà incorrecta, i l’avaluació fallarà tancada.

---

5) Contracte del Proveïdor JSON: Especificació Completa

Un contracte és un únic objecte JSON amb els següents camps requerits. Els camps marcats com a opcionals es poden ometre.

5.1 Camps de nivell superior (requerits a menys que s’indiqui el contrari)

• provider_id (string, required)

  • Identificador estable utilitzat en EvidenceQuery.provider_id.
  • Utilitzeu snake_case i mantingueu-ho estable.

• name (string, required)

  • Nom llegible per a humans per a la interfície d’usuari i les eines.

• description (string, required)

  • Quina font d’evidència representa aquest proveïdor.

• transport (string, required)

  • Ha de ser “mcp” (proveïdors externs) o “builtin” (integrats).
  • Els contractes de proveïdors externs han de configurar el transport: “mcp” o seran rebutjats.

• notes (array of strings, required)

  • Notes lliures per a humans i LLMs.
  • Utilitzeu [] si no hi ha notes.

• config_schema (JSON Schema, required)

  • Esquema per al bloc de configuració del proveïdor a decision-gate.toml.
  • The contract schema accepts any JSON Schema value, but **Decision Gate tooling L’esquema del contracte accepta qualsevol valor de JSON Schema, però l’eina de Decision Gate assumeix un esquema d’objecte. Utilitzeu un esquema d’objecte amb additionalProperties: false.
  • If the provider has no config, use:

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

• checks (array, required)

  • Cada entrada és una definició de comprovació del proveïdor.
  • L’array pot estar buit, però llavors el proveïdor no exposa cap comprovació utilitzable.

5.2 Comprovar camps (tots requerits)

Cada entrada en checks defineix una comprovació del proveïdor.

• check_id (string)

  • Identificador estable utilitzat en EvidenceQuery.check_id.
  • Utilitzeu snake_case i mantingueu-ho estable.

• description (string)

  • Descriu què significa el valor retornat, no com s’obté.

• determinism (string)

  • Un de: determinista, dependent del temps, extern.

• params_required (boolean)

  • Cert si els params han de ser proporcionats; fals si els params són opcionals o cap.

• params_schema (JSON Schema)

  • Esquema per a EvidenceQuery.params.
  • Utilitzeu un esquema d’objecte i establiu additionalProperties: false (recomanat).
  • If no params, use:

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

• result_schema (JSON Schema)

  • Esquema per al valor de l’evidència (EvidenceResult.value.value).
  • Utilitzeu l’esquema més ajustat possible.

• allowed_comparators (array of strings)

  • Llista blanca de comparadors per a aquesta comprovació.
  • Ha de ser no buit i en ordre canònic (vegeu la llista de la Secció 7).
  • Ha de ser compatible amb result_schema i regles de validació estrictes.

• anchor_types (array of strings)

  • Tipus d’ancora que aquesta comprovació pot emetre.
  • Utilitzeu [] si no n’hi ha.

• content_types (array of strings)

  • Tipus MIME per a EvidenceResult.content_type.
  • Pot estar buit ([]) per significar “no especificat”.
  • Si és present, utilitzeu tipus MIME vàlids (per exemple, application/json).

• examples (array of objects)

  • Cada exemple és { “description”: ”…”, “params”: { … }, “result”: … }.
  • L’esquema permet un array buit, però es recomanen fortament exemples.

---

6) Orientació sobre JSON Schema (Paràmetres i Resultats)

DG utilitza JSON Schema (esborrany 2020-12) per validar els paràmetres i els resultats. Mantingueu els esquemes precisos i mínims.

Regles del esquema de paràmetres (recomanat)

• Utilitzeu type: "object".
• Estableix additionalProperties: false.
• Declara required per a cada camp que sigui obligatori.
• Preferir tipus i límits explícits.

Regles de l’esquema de resultats

• Descriu el valor real de l’evidència, no el wrapper EvidenceResult.
• Use the narrowest possible type (boolean, integer, number, string, Utilitzeu el tipus més estret possible (boolean, integer, number, string, array, object o null).
• If you need multiple types, use oneOf / anyOf. Strict validation Si necessiteu múltiples tipus, utilitzeu oneOf / anyOf. La validació estricta intersecciona les allowances del comparador a través de totes les variants.

Resultats de Bytes (cas especial)

Si el proveïdor retorna EvidenceValue::Bytes, el valor de l’evidència es compara com a bytes. Es recomana l’esquema:

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

Per a les proves de bytes, només equals i not_equals són vàlids en temps d’execució. Construeix allowed_comparators en conseqüència.

Resultats dinàmics (sortida d’emergència)

Si una comprovació pot retornar formes JSON arbitràries que no es poden expressar, marca l’esquema de resultat com a dinàmic:

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

Els esquemes dinàmics permeten tots els comparadors en validació estricta, però els comparadors lex/deep encara requereixen flags de configuració (vegeu la Secció 8).

---

7) Semàntica del Comparator i Compatibilitat

Els comparadors converteixen proves en resultats de tres estats. Per als comparadors que requereixen expected, la manca de expected dóna com a resultat unknown.

Llista de comparadors (ordre canònic)

• iguals
• not_equals
• major_que
• major_que_o_igual
• menys_que
• menor_o_igual
• lex_més_gran_que
• lex_greater_than_or_equal
• lex_menys_que
• lex_menys_que_o_igual
• conté
• in_set
• deep_equals
• deep_not_equals
• existeix
• no_existeix

Utilitzeu aquest ordre quan escriviu allowed_comparators.

Semàntica d’execució (nucli de Decision Gate)

• equals / not_equals: JSON equality. Numbers are compared as decimals equals / not_equals: igualtat JSON. Els números es comparen com a decimals (10 == 10.0). Les incompatibilitats de tipus retornen false / true respectivament.
• greater_than / less_than (and _or_equal):
  • Ordenació numèrica per a números JSON.
  • Temporal ordering for strings that parse as RFC3339 date-time or date-only Ordenació temporal per cadenes que es parsegen com a data-hora o només data RFC3339 (YYYY-MM-DD) en ambdós costats. Altres desconeguts.
• lex_*: Ordenació lexicogràfica només per a cadenes; en cas contrari unknown.
• contains:
  • Cadenes: contenció de subcadenes.
  • Arrays: evidence array contains all elements of the expected array Arrays: l’array d’evidència conté tots els elements de l’array esperat (només membres, no comptatges de multiset).
• in_set:
  • S’espera que sigui un array.
  • La evidència ha de ser escalar (no objecte/array). La pertinença utilitza la igualtat JSON.
• exists / not_exists:
  • Ignora el que s’espera.
  • Comprova només si EvidenceResult.value està present.
  • JSON null compta com a present.
• deep_equals / deep_not_equals:
  • Només per a arrays o objects; d’altra banda desconegut.

Compatibilitat de validació estricta (per defecte a decision-gate-mcp)

La porta de decisió MCP realitza una validació estricta de comparadors/tipus per defecte. Un comparador de ScenarioSpec ha de:

1. Estar present a la llista allowed_comparators del contracte del proveïdor.
2. Ser permès per la classificació del tipus d’esquema de resultat.
3. Estar habilitat per configuració (les famílies lex/deep estan desactivades per defecte).

Permisos per tipus d’esquema de resultat (validació estricta):

• boolean

  • Permès: equals, not_equals, in_set, exists, not_exists

• integer / number

  • Allowed: equals, not_equals, greater_than, greater_than_or_equal, Permès: equals, not_equals, greater_than, greater_than_or_equal, less_than, less_than_or_equal, in_set, exists, not_exists

• string (no format)

  • Permès: equals, not_equals, contains, in_set, exists, not_exists
  • Opt-in: lex_* (vegeu la Secció 8)

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

  • Allowed: equals, not_equals, greater_than, greater_than_or_equal, Permès: equals, not_equals, greater_than, greater_than_or_equal, less_than, less_than_or_equal, in_set, exists, not_exists

• string with format: "uuid"

  • Permès: equals, not_equals, in_set, exists, not_exists

• enum (scalar values only)

  • Permès: equals, not_equals, in_set, exists, not_exists

• array with scalar items

  • Permès: conté, existeix, not_exists
  • Optar: deep_equals, deep_not_equals (vegeu la Secció 8)

• array with complex items

  • Permès: exists, not_exists
  • Optar: deep_equals, deep_not_equals

• object

  • Permès: exists, not_exists
  • Optar: deep_equals, deep_not_equals

• null

  • Permès: equals, not_equals, exists, not_exists

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

  • Permès: tots els comparadors (sota les banderes de configuració)

Si la validació estricta està desactivada (validation.strict = false amb validation.allow_permissive = true), es salten les comprovacions de compatibilitat d’esquema, però la semàntica del comparador en temps d’execució encara s’aplica.

---

8) Comparadors Opt-in (Lex i Deep)

Els comparadors d’igualtat lexicogràfica i profunda són opcionals en la validació estricta per a esquemes no dinàmics i requereixen dos passos:

1. Enable in decision-gate.toml:

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

2. Declara les opcions d’acceptació en l’esquema de resultats (per a esquemes no dinàmics):

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

Regles addicionals:

• The comparator must also appear in the provider contract’s El comparador també ha d’aparèixer a la llista allowed_comparators del contracte del proveïdor.
• If x-decision-gate.allowed_comparators is present, every comparator Si x-decision-gate.allowed_comparators està present, cada comparador utilitzat pels escenaris ha de ser llistat allí.
• For dynamic schemas (dynamic_type: true), schema opt-in is not required, Per a esquemes dinàmics (dynamic_type: true), no es requereix l’opt-in de l’esquema, però les banderes de configuració encara s’apliquen.

---

9) Metadades d’Evidència: Ancoratges i Tipus de Contingut

Els contractes declaren quins metadades d’evidència un proveïdor pot emetre.

• anchor_types: Strings describing anchor kinds (for audit or external references). Examples: file_path_rooted, url, receipt_id, log_offset. anchor_types: Cadenes que descriuen els tipus d’ancoratge (per a auditoria o referències externes). Exemples: file_path_rooted, url, receipt_id, log_offset. Utilitzeu [] si no s’emeten ancoratges.

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

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

Els valors de EvidenceResult.content_type haurien de coincidir amb aquesta llista quan estiguin presents. Una llista buida significa “no especificat” (les polítiques ho tracten com un comodí).

Nota sobre el valor d’ancoratge: EvidenceResult.evidence_anchor.anchor_value és una cadena. Si configureu una política d’ancoratge que requereix camps, aquesta cadena ha de ser JSON canònic per a un únic objecte amb camps escalar. Per a ancoratges basats en fitxers, file_path_rooted utilitza camps escalar root_id i path (camins relatius només).

---

10) Classificació del Determinisme (Sigues Honest)

• determinista: La sortida depèn només d’entrades i de l’estat intern.
• time_dependent: La sortida depèn del temps, però és determinista donat el temps.
• extern: La sortida depèn de l’estat extern (xarxa, DB, APIs).

Aquesta classificació s’utilitza per a raonaments d’auditoria i confiança. No etiqueteu incorrectament.

---

11) Flux de treball d’autoria de principi a fi (Humans o LLMs)

Pas 1: Recollir les entrades requerides

Haureu de tenir tot el següent per a cada comprovació del proveïdor:

• Comproveu el nom i la descripció (què significa el resultat).
• Classificació del determinisme.
• Esquema de paràmetres (JSON Schema o llista completa de paràmetres amb tipus/requerits).
• Esquema de resultat (JSON Schema per al valor de l’evidència).
• Comparadors permesos (o permetre que l’autor els derivin estrictament).
• Almenys un exemple de parell de paràmetres + resultat (recomanat).
• Tipus d’ancoratge i tipus de contingut (o explícitament “cap”).

Pas 2: Mapejar entrades als camps del contracte

• Converteix noms a identificadors estables snake_case.
• Traduir els tipus de sol·licitud en params_schema.
• Traduïu els valors de resposta a result_schema.
• Trieu llistes d’allow-list de comparadors de la Secció 7 i regles de validació estrictes.

Pas 3: Validar internament

• Assegureu-vos que params_schema i result_schema són esquemes JSON vàlids.
• Assegureu-vos que allowed_comparators no estigui buit i estigui en ordre canònic.
• Assegureu-vos que les llistes de comparadors siguin compatibles amb les regles de validació estrictes.
• Assegureu-vos que els exemples (si s’ofereixen) coincideixin amb els esquemes.
• Assegureu-vos que content_types i anchor_types siguin precisos.

Pas 4: Produir el JSON final

• Només sortida JSON.
• Eviteu markdown en la sortida final.

---

12) Full de Recepció del Proveïdor (Plantilla)

Copia/enganxa i omple això abans d’escriure el contracte:

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 algun camp, no endevinis. Pregunta-ho explícitament.

---

13) LLM Authoring Prompt (Estricte, Autònom)

Utilitzeu aquest missatge verbatim amb un LLM, juntament amb la fitxa completada i qualsevol definició d’OpenAPI o tipus. Aquest missatge està dissenyat per prevenir al·lucinations i forçar preguntes explícites quan falta informació.

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.

---