Patrons d’Integració

A Simple Vista

Què: Patrons de desplegament comuns per a CI/CD, bucles d’agents i fluxos de treball de compliment Per què: Trieu l’estratègia d’integració adequada per a les necessitats de confiança i auditoria Qui: Arquitectes i desenvolupadors que planifiquen desplegaments de Decision Gate Requisits previs: getting_started.md

Visió general del patró

Patró	Trust Lane	Velocitat	Audit Trail	Cas d’ús
CI/CD Gate	Verificat	Més lent	Execució completa	Desplegaments en producció
Agent Loop	Assertit -> Verificat	Ràpid -> Lent	Opcional -> Completa	Planificació LLM cap a portes
Controlled Disclosure	Verificat	Lent	Completa	Lliberació de dades amb auditoria
Compliance Workflow	Verificat	Lent	Completa	Portes de múltiples etapes
MCP Federation	Verificat	Varietat	Completa	Fonts d’evidència externes

Patró 1: CI/CD Gate

Quan utilitzar: Portes de qualitat automatitzades en canals CI/CD

Flux:

Executar eines -> emetre JSON
scenario_start -> crear execució
scenario_next -> DG llegeix JSON a través del proveïdor json
L’outcome de la decisió impulsa el desplegament

Configura el proveïdor json amb una arrel que apunti al teu espai de treball d’evidències, i mantingues les rutes de fitxers relatives a aquesta arrel.

Escenari (mínim, camps precisos):

{
  "scenario_id": "ci-gate",
  "namespace_id": 1,
  "spec_version": "v1",
  "stages": [
    {
      "stage_id": "quality",
      "entry_packets": [],
      "gates": [
        {
          "gate_id": "quality-checks",
          "requirement": {
            "And": [
              { "Condition": "tests_ok" },
              { "Condition": "coverage_ok" },
              { "Condition": "scan_ok" }
            ]
          }
        }
      ],
      "advance_to": { "kind": "terminal" },
      "timeout": null,
      "on_timeout": "fail"
    }
  ],
  "conditions": [
    {
      "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": []
    },
    {
      "condition_id": "coverage_ok",
      "query": {
        "provider_id": "json",
        "check_id": "path",
        "params": {
          "file": "coverage.json",
          "jsonpath": "$.total.lines.percent"
        }
      },
      "comparator": "greater_than_or_equal",
      "expected": 85,
      "policy_tags": []
    },
    {
      "condition_id": "scan_ok",
      "query": {
        "provider_id": "json",
        "check_id": "path",
        "params": {
          "file": "scan.json",
          "jsonpath": "$.summary.critical"
        }
      },
      "comparator": "equals",
      "expected": 0,
      "policy_tags": []
    }
  ],
  "policies": [],
  "schemas": [],
  "default_tenant_id": 1
}

Interpretant el resultat de scenario_next:

Look at result.decision.outcome.kind:
- advance / complete -> portes passades
- hold -> portes no satisfetes
- fail -> execució fallida
Opcional: feedback: "trace" pot retornar l’estat de la porta + condició (si ho permet la política de retroalimentació del servidor).

Quan utilitzar: Agents LLM que iteren cap a la satisfacció de les condicions de la porta

Quan utilitzar: Agents LLM que iteren cap a la satisfacció de la porta d’entrada

Flux:

L’agent executa eines -> extreu valors
precheck -> avaluació ràpida (evidència afirmada)
Si les portes passen -> executar en viu scenario_next

La sortida de precomprovació és limitada:

Retorns { decision, gate_evaluations }.
gate_evaluations conté gate_id, status i només el rastre de condicions.
No inclou valors d’evidència ni errors.

Si necessiteu errors d’evidència, utilitzeu evidence_query o runpack_export en una execució en viu.

Patró 3: Divulgació Controlada

Quan utilitzar: Lliberació de dades amb rastre d’auditoria

Flux típic:

Aprovar portes utilitzant RequireGroup.
En passar, utilitzeu scenario_submit per enregistrar metadades.
Enviar paquets de dades (controlats per polítiques).

scenario_submit és només per a auditoria i requereix:

run_id, tenant_id, namespace_id, submission_id
payload, content_type, submitted_at

Patró 4: Flux de treball de compliment (Múltiples etapes)

Utilitzeu l’ordenació de les etapes més advance_to.kind = "linear" per passar a l’etapa següent en l’ordre especificat:

{
  "stage_id": "dev",
  "advance_to": { "kind": "linear" }
}

Utilitzeu branch quan necessiteu diferents destinacions en funció del resultat de la porta d’entrada.

Pattern 5: Federació MCP (Proveïdors Externs)

Quan utilitzar: Fonts d’evidència fora dels integrats

Config (exact):

[[providers]]
name = "git"
type = "mcp"
command = ["/usr/local/bin/git-provider"]
capabilities_path = "contracts/git.json"

[[providers]]
name = "cloud"
type = "mcp"
url = "https://cloud.example.com/rpc"
capabilities_path = "contracts/cloud.json"
allow_insecure_http = false
timeouts = { connect_timeout_ms = 2000, request_timeout_ms = 10000 }

[trust]
# Require signatures from these key files
default_policy = { require_signature = { keys = ["/etc/decision-gate/keys/cloud.pub"] } }

Notes d’Interop (Runpack + Transcripcions)

checkedfiles en runpackexport vs runpack_verify

Quan runpack_export és cridat amb include_verification = true, el valor retornat de report.checked_files reflecteix la verificació executada abans que artifacts/verifier_report.json sigui afegit al manifest. Per al mateix runpack, s’espera que runpack_verify.report.checked_files sigui exactament +1 perquè valida el manifest finalitzat (incloent verifier_report.json).

Transcripció d’Artifacts: Contracte vs Test Harness

DG runpack artifact artifacts/tool_calls.json is the canonical contract L’artefacte de DG runpack artifacts/tool_calls.json és la superfície del contracte canònica i conté registres de trucades d’eines de l’estat d’execució només amb hash.
System-test artifact tool_transcript.json is raw client-side capture used L’artefacte de prova del sistema tool_transcript.json és una captura en brut del costat del client utilitzada per a diagnòstics i no és un artefacte de contracte de paquet d’execució de DG.

Advertència de càrrega sensible

scenario_submit.payload i scenario_trigger.payload es mantenen per registrar els estats d’execució i s’exporten en runpacks per disseny. No col·loqueu secrets en brut en aquests camps de càrrega útil.

Llista de verificació de desplegament

La configuració valida (decision-gate config validate)
Els proveïdors tenen fitxers capabilities_path vàlids
namespace.allow_default configurat correctament per a l’ús només local
Auth + TLS (o tls_termination = "upstream") configurat per a vinculacions no de loopback
trust.default_policy i min_lane configurats per a producció
Política de divulgació d’evidències establerta (allow_raw_values, require_provider_opt_in)