Integración del Proveedor de Puertas de Decisión + Arquitectura del Registro de Capacidades

Audience: Engineers implementing provider integration or capability Audiencia: Ingenieros que implementan la integración de proveedores o la validación de capacidades para consultas de verificaciones, condiciones y evidencias.

Tabla de Contenidos

Resumen Ejecutivo
Configuración del proveedor
Registro de Capacidades
Contratos de Proveedores Externos
Federación de Proveedores de Evidencia
Cumplimiento a Nivel de Herramienta
Bloqueo de Contrato Typed REST/OpenAPI V3
Referencia Cruzada Archivo por Archivo

Resumen Ejecutivo

Decision Gate admite tres tipos de proveedores:

Proveedores integrados (compilados en el binario)
Proveedores MCP externos (transporte stdio o HTTP)
Proveedores tipados (capacidad precompilada + artefactos de perfil en tiempo de ejecución)

Los contratos de capacidad del proveedor son el esquema autoritativo para los parámetros de verificación, resultados y comparadores permitidos. El registro de capacidades valida las especificaciones de escenario y las consultas de evidencia antes de la evaluación. La federación de evidencia dirige las consultas a los proveedores y aplica políticas de confianza. F:crates/decision-gate-config/src/config.rs L1883-L1990 F:crates/decision-gate-mcp/src/capabilities.rs L229-L379 F:crates/decision-gate-mcp/src/evidence.rs L138-L210

Configuración del Proveedor

La configuración del proveedor se define en ProviderConfig:

tipo: builtin, mcp o typed
comando / url: selección de transporte para proveedores MCP
capabilities_path: ruta JSON del contrato (requerida para proveedores MCP/tipados)
runtime_profile_path: ruta JSON del perfil de ejecución tipado (requerido para proveedores tipados)
typed_protocol: selector de protocolo de tiempo de ejecución tipado (openapi_http o grpc)
auth.bearer_token: autenticación del proveedor opcional
trust: anulación de confianza por proveedor
allow_raw: opción para la divulgación de evidencia en bruto
timeouts: tiempos de espera para la conexión y la solicitud HTTP

Los controles de descubrimiento se definen en provider_discovery:

allowlist / denylist: restringir qué contratos de proveedores se divulgan
max_response_bytes: limitar el tamaño de la respuesta de descubrimiento

La validación impone:

Los proveedores de MCP deben especificar command o url y capabilities_path.
Typed providers must specify capabilities_path, runtime_profile_path, y typed_protocol.
allow_insecure_http es necesario para URLs http://.
Los nombres de los proveedores son únicos y están recortados.
Los identificadores incorporados (time, env, json, http, rest) están reservados; los proveedores de MCP no pueden usarlos.
Built-ins must use a reserved identifier and reject MCP-only fields (command, url, Los identificadores incorporados deben usar un identificador reservado y rechazar los campos solo de MCP (command, url, allow_insecure_http, auth, capabilities_path).
Los proveedores de MCP rechazan los campos solo de tipo (runtime_profile_path, typed_protocol).
Typed providers reject MCP-only fields (command, url, allow_insecure_http, auth) y cargas útiles config integradas.

F:crates/decision-gate-config/src/config.rs L1883-L1990

Registro de Capacidades

El registro de capacidades carga contratos de proveedores y compila esquemas JSON para verificar parámetros y resultados. Valida:

Proveedor y verificar existencia
Presencia de parámetros requeridos
Conformidad con el esquema de parámetros
Conformidad con el esquema de valor esperado
Listas de permitidos del comparador
Anchor types declared by provider contracts (e.g., file_path_rooted for the Tipos de anclaje declarados por contratos de proveedor (por ejemplo, file_path_rooted para el proveedor json incorporado)
Rechazo de check_id duplicado (cerrado por fallo; sin semántica de sobrescritura silenciosa)

F:crates/decision-gate-mcp/src/capabilities.rs L313-L379 F:crates/decision-gate-mcp/src/capabilities.rs L598-L636

Las consultas del registro de capacidades son utilizadas tanto por la definición de escenarios como por las herramientas de consulta de evidencia. F:crates/decision-gate-mcp/src/tools/router.rs L2029-L2050 F:crates/decision-gate-mcp/src/tools/router.rs L979-L1017

Contratos de Proveedores Externos

Los proveedores externos deben suministrar un archivo JSON de contrato que:

Coincide con el id del proveedor configurado
Declares transport matching provider type:
- Proveedores MCP: transport = "mcp"
- Proveedores tipados: transport = "typed"
Define comprobaciones con listas de comparadores permitidos

Los contratos tienen un tamaño limitado y son validados por ruta; los contratos inválidos fallan en cerrado. Para las importaciones de OpenAPI tipadas, verifique que allowed_comparators se sintetizan a partir del esquema de resultado normalizado utilizando la matriz de tipo de comparador estricto y el orden canónico de comparadores. F:crates/decision-gate-mcp/src/capabilities.rs L533-L591 F:crates/decision-gate-typed/src/openapi/check_synthesis.rs L34-L109 F:crates/decision-gate-typed/src/openapi/comparator_derivation.rs L52-L114

Federación de Proveedores de Evidencia

La federación de evidencia combina proveedores integrados y proveedores MCP:

Los componentes integrados se registran a través del registro de proveedores.
Los proveedores de MCP se instancian con transporte stdio o HTTP.
Typed providers are instantiated from runtime profile artifacts and execute verificaciones definidas por perfil a través del proveedor de tiempo de ejecución tipado.
El registro de proveedores rechaza registros duplicados para prevenir sobrescrituras silenciosas.
Stdio provider processes are terminated on drop to avoid orphaned provider Los procesos del proveedor de Stdio se terminan al eliminarse para evitar tiempos de ejecución de proveedor huérfanos durante el apagado o la desactivación de pruebas.
Las políticas del proveedor (trust + allow_raw) se aplican por proveedor.
Evidence results may include structured error metadata (code, message, Los resultados de evidencia pueden incluir metadatos de error estructurados (code, message, details) para apoyar bucles de recuperación determinísticos.
HTTP evidence providers enforce timeouts, disallow redirects, apply response size limits, fail closed on truncated bodies (Content-Length mismatch), pin DNS resolution per request, and deny private/link-local peers by default a menos que se haya optado explícitamente.
The built-in REST provider reuses the same HTTP security controls and adds GET-only extraction checks (json_path, header) plus header/auth hygiene aplicación para nombres de encabezados gestionados por autenticación y reservados.
The typed runtime provider applies the same hardened HTTP controls for openapi_http execution, enforces profile digest integrity, validates response status/content-type against profile policy, and emits deterministic anclas utilizando metadatos de perfil.
Typed lifecycle catalog semantics now exist in OSS compile tooling to support profile version registration, activation, rollback, and digest drift detection (decision-gate-typed), and OSS lifecycle tool plumbing is active via typed_providers_import, typed_providers_register, typed_providers_list, typed_providers_get, typed_providers_activate, y typed_providers_deprecate.
Typed runtime resolution now includes a resolver seam (TypedProfileResolver) keyed by (tenant_id, namespace_id, provider_id). Default OSS behavior resolves from scoped in-memory lifecycle state and falls back to static typed profile config entries. Resolver calls now snapshot the resolver handle before invocation so runtime la resolución no se ejecuta mientras se sostiene el mutex del resolvedor interno.
Built-in REST runtime now includes policy evaluator seams (RestPolicyEvaluator) for egress host/scheme decisions and auth-scheme decisiones. Negar caminos devuelve códigos de razón deterministas.

F:crates/decision-gate-mcp/src/evidence.rs L138-L210 F:crates/decision-gate-mcp/src/evidence.rs L248-L266 F:crates/decision-gate-providers/src/http.rs L82-L239 F:crates/decision-gate-providers/src/rest.rs L124-L570 F:crates/decision-gate-typed/src/lifecycle.rs L1-L286

La aplicación de la política de confianza (verificación de firmas) se ejecuta por respuesta del proveedor. F:crates/decision-gate-mcp/src/evidence.rs L636-L677

Cumplimiento a Nivel de Herramienta

El comportamiento de la herramienta impone la política de capacidad y divulgación:

scenario_define valida la especificación contra las capacidades antes de registrarse.
evidence_query valida consultas y aplica la política de redacción de evidencia en bruto.
evidence_query execution is offloaded to a blocking task to isolate evidence_query se ejecuta en una tarea bloqueante para aislar a los proveedores bloqueantes (HTTP) del tiempo de ejecución asíncrono de MCP.
provider_contract_get / provider_check_schema_get apply disclosure policy and provider_contract_get / provider_check_schema_get aplican la política de divulgación y devuelven contratos de proveedor canónicos o esquemas de verificación.
Typed lifecycle tools (typed_providers_import/register/list/get/activate/deprecate) require explicit tenant_id + namespace_id scope fields and provide deterministic scoped artifact registration, active-version selection, rollback-aware deprecation, digest drift status inspection, and bounded typed import/runtime security limits (timeout_ms, max_response_bytes, outbound_max_inflight, retry bounds, and allowlist cardinality). typed_providers_import requires an explicit credential_bindings field on every request ({} for unauthenticated imports) and explicit secured-scheme-to-credential_binding mappings for secured OpenAPI imports. Cada mapeo asegurado requiere tanto metadatos de renderizado de localizador como de valor de cable.
Provider-scoped authz context now includes provider_id for typed lifecycle tools and evidence_query, enabling provider-level enterprise authorization política en la costura de autorización del inquilino.
Comparator allow-lists are enforced from provider contracts; json.path Las listas de permitidos del comparador se aplican a partir de los contratos de proveedor; json.path expone toda la superficie del comparador para evidencia JSON determinista.

F:crates/decision-gate-mcp/src/tools/router.rs L1106-L1236 F:crates/decision-gate-mcp/src/tools/router.rs L1238-L1298 F:crates/decision-gate-mcp/src/tools/router.rs L3173-L3940 F:crates/decision-gate-mcp/src/tools/typed/lifecycle.rs L127-L210 F:crates/decision-gate-mcp/src/tools/typed/lifecycle.rs L213-L452 F:crates/decision-gate-mcp/src/tools/typed/lifecycle.rs L455-L544

Bloqueo de Contrato Typed REST/OpenAPI V4

Esta sección es el bloqueo de decisiones a nivel de arquitectura para el comportamiento del proveedor OSS de tipo REST/OpenAPI. Es intencionadamente estable para que el movimiento en la hoja de ruta/archivo no cambie el contrato activo.

Importar bloqueo de frontera (OSS V4):

OpenAPI version policy accepts 3.0.x and 3.1.x; other versions fail cerrado.
External ref mode is local_file_only in OSS runtime behavior. Network ref los caminos de ejecución se analizan para la clasificación de políticas pero son rechazados.
Unsupported or ambiguous constructs must fail closed with deterministic metadatos de mapeo/remediación de taxonomía.
Unsupported taxonomy and remediation metadata are single-source and enum-backed (OpenapiUnsupportedCode + OpenapiImportErrorKind), not message-substring acoplado.
Unsupported taxonomy fixture parity is enforced by typed importer unit pruebas de contrato, bloqueando la deriva de fixture/implementación en CI.

F:crates/decision-gate-typed/src/openapi/mod.rs L144-L301 F:crates/decision-gate-typed/src/openapi/refs.rs L22-L394 F:crates/decision-gate-typed/src/openapi/errors.rs L12-L212 F:crates/decision-gate-typed/src/openapi/errors.rs L447-L558 F:crates/decision-gate-typed/tests/openapi_unsupported_taxonomy_contract.rs L1-L105

Síntesis/bloqueo de tiempo de ejecución (OSS V4):

Projection-first synthesis is mandatory for JSON object/array-complex las respuestas: los esquemas deben declarar x-decision-gate.projections.
OpenAPI import emits one check per declared projection entry per tupla de estado/media; se ha eliminado la entrada heredada response_projection_mode.
json_only media support remains default unless explicit overrides se proporcionan.
Runtime request binding supports path, query, header, cookie, and objetivos body opcionales con conflictos de cierre en fallo y verificaciones de higiene.
La extracción en tiempo de ejecución sigue estando restringida por estado/tipo de contenido y falla en cerrado.
Runtime profile profile_version is hard-locked to typed-runtime-v4; older las versiones de perfil son rechazadas.
TypedOperationProfile always carries required operation-effective auth alternativas; la recuperación de autenticación a nivel de proveedor no es parte del modelo de tiempo de ejecución.

F:crates/decision-gate-typed/src/openapi/mod.rs L144-L248 F:crates/decision-gate-typed/src/openapi/check_synthesis.rs L34-L242 F:crates/decision-gate-typed/src/runtime_codegen.rs L42-L93 F:crates/decision-gate-providers/src/typed.rs L687-L799

Autenticación + bloqueo de credenciales (OSS V4):

Effective security is resolved per operation:
- operation.security anula security de nivel superior.
- security: [] significa operación no autenticada.
- El objeto de requisito vacío ({}) contribuye a una alternativa no autenticada.
Supported requirement shapes:
- Un requisito que contiene un esquema soportado.
- Multiple alternatives where each alternative contains exactly one supported esquema.
Supported schemes remain http bearer/basic and apiKey in header|query|cookie.
Credential locators are explicit and scheme-locked:
- secret://... se resuelve a través del backend de secretos OSS encriptados localmente.
- env://... is development-only and disabled unless dev.allow_dev_env_credentials=true.
- Se rechazan los nombres de variables de entorno desnudos y los esquemas de localización desconocidos.
Credential values are canonical raw secrets; runtime applies explicit value_render metadata (identity or deterministic prefix) before inyección de encabezado/query/cookie.
apiKey alternatives retain exact OpenAPI-derived name and location; no se utilizan nombres de clave API fijos sintéticos en tiempo de ejecución.
Import requires an explicit credential_bindings field and explicit credential_binding mapping input for every referenced secured scheme; los campos/mapeos faltantes fallan en cerrado.
Unsupported security types/schemes and unsupported requirement shapes (oauth2, openIdConnect, unsupported http schemes, unsupported apiKey locations, multi-scheme AND, missing scheme refs, malformed security los objetos) fallan cerrados con una taxonomía determinista.

F:crates/decision-gate-typed/src/openapi/security_mapping.rs L11-L216 F:crates/decision-gate-typed/src/openapi/errors.rs L125-L155 F:crates/decision-gate-providers/src/typed.rs L789-L904 F:crates/decision-gate-mcp/src/tools/typed/lifecycle.rs L55-L163

Resiliencia saliente + bloqueo de límites (OSS V3):

Runtime security policy includes per-provider outbound inflight caps and bounded retry policy (max_attempts, initial_backoff_ms, max_backoff_ms).
Runtime retries are deterministic and limited to timeout/429/503, with soporte Retry-After limitado cuando se codifica como segundos.
La importación/registro rechaza los límites/reintentos de salida mal formados.

F:crates/decision-gate-contract/src/types.rs L403-L439 F:crates/decision-gate-providers/src/typed.rs L448-L463 F:crates/decision-gate-providers/src/typed.rs L958-L980 F:crates/decision-gate-mcp/src/tools/typed/lifecycle.rs L586-L663

Requisito de control de cambios:

Any change to the above lock values requires same-change updates to:
- esta sección,
- Fixtures de conformidad con OpenAPI (system-tests/tests/fixtures/openapi_compat/),
- contratos de política/informe de cobertura REST (system-tests/tests/fixtures/coverage/),
- y deltas del modelo de amenazas cuando se expanden los límites de confianza.

Referencia Cruzada Archivo por Archivo

Área	Archivo	Notas
Configuración y validación del proveedor	`crates/decision-gate-config/src/config.rs`	Tipo de proveedor, transporte, ruta del contrato, tiempos de espera, descubrimiento permitir/negar.
Registro de capacidades	`crates/decision-gate-mcp/src/capabilities.rs`	Carga de contrato, compilación de esquema, validación.
Federación de evidencia	`crates/decision-gate-mcp/src/evidence.rs`	Registro de proveedores + aplicación de confianza.
Proveedor de tiempo de ejecución tipado	`crates/decision-gate-providers/src/typed.rs`	Carga de perfil de tiempo de ejecución y ejecución de verificación tipada.
IR tipado + adaptadores	`crates/decision-gate-typed/src/lib.rs`	Fundación de importación/código generador tipada independiente del protocolo.
Catálogo de ciclo de vida tipado	`crates/decision-gate-typed/src/lifecycle.rs`	Versionado de perfil OSS, activación/reversión y primitivas de estado de deriva de resumen.
Fachada del adaptador OpenAPI	`crates/decision-gate-typed/src/adapter_openapi.rs`	Re-exportación de compatibilidad para la API del módulo `openapi`.
Internos del adaptador OpenAPI	`crates/decision-gate-typed/src/openapi/`	División de módulo para opciones/errores/conformidad/referencias/esquema/seguridad/comprobador/lógica de comparador.
Orquestación de herramientas de ciclo de vida tipadas	`crates/decision-gate-mcp/src/tools/typed/lifecycle.rs`	Análisis de importación/registro/lista/obtener/activar/depreciar tipada y cableado de estado de ciclo de vida.
Integración de herramientas	`crates/decision-gate-mcp/src/tools/router.rs`	Despacho de herramientas, puertas de autorización/divulgación y sobre de manejador asíncrono.