Arquitectura de Decision Gate Runpack

Audience: Engineers implementing runpack export/verification and Audiencia: Ingenieros que implementan la exportación/verificación de runpack y el manejo de artefactos de sistema de archivos/almacenamiento de objetos.

---

Tabla de Contenidos

1. Resumen Ejecutivo
2. Estructura del Manifiesto de Runpack
3. Pipeline de Exportación de Runpack
4. Modelo de Integridad de Artefactos
5. Flujo de Verificación de Runpack
6. Seguridad del Sumidero/Lector del Sistema de Archivos
7. Seguridad del Sumidero/Lector de Almacenamiento de Objetos
8. Referencia Cruzada Archivo por Archivo

---

Resumen Ejecutivo

Los runpacks son paquetes deterministas de especificaciones de escenario, registros del plano de control y metadatos de integridad. El constructor escribe artefactos JSON canónicos y calcula hashes para cada archivo, además de un hash raíz sobre la lista de hashes de archivos. La verificación reproduce controles de integridad, valida la unicidad del registro de decisiones y, opcionalmente, valida los anclajes de evidencia cuando hay una política de anclaje presente. F:crates/decision-gate-core/src/runtime/runpack.rs L83-L374

Los anclajes de evidencia se almacenan textualmente en los registros de runpack. Para los anclajes basados en archivos (file_path_rooted), los anclajes incluyen un root_id estable más una ruta relativa al estilo POSIX para garantizar que los hashes sean consistentes en todos los sistemas operativos.

Las exportaciones de Runpack seleccionan un destino en este orden: un backend RunpackStorage opcional (exporta a un directorio temporal y delega el almacenamiento), un backend de objeto OSS cuando está configurado, o una exportación de sistema de archivos que requiere output_dir. F:crates/decision-gate-mcp/src/runpack_storage.rs L31-L67 F:crates/decision-gate-mcp/src/tools.rs L2342-L2480

---

Estructura del Manifiesto de Runpack

El manifiesto es el índice canónico para los artefactos de runpack. Los campos clave incluyen:

• Identificadores de escenario/ejecución y hash de especificación
• Algoritmo de hash y modo de verificación
• Política de anclaje opcional y contexto de seguridad
• Lista de hash de archivos y hash raíz
• Entradas del índice de artefactos

F:crates/decision-gate-core/src/core/runpack.rs L57-L116

La versionado de manifiestos es explícito. El verificador actualmente soporta v1 y falla de manera cerrada en valores manifest_version desconocidos para preservar las garantías de compatibilidad hacia atrás a medida que se introducen nuevas versiones. F:crates/decision-gate-core/src/runtime/runpack.rs L60-L374

Los metadatos del contexto de seguridad capturan la postura de autoridad de dev-permissive y namespace cuando son proporcionados por el servidor MCP. F:crates/decision-gate-core/src/core/runpack.rs L94-L104

---

Pipeline de Exportación de Runpack

La exportación de Runpack se inicia a través de la herramienta MCP runpack_export:

1. El enrutador de herramientas carga el estado de ejecución desde el almacén configurado.
2. A RunpackBuilder is created with the active anchor policy and optional Se crea un RunpackBuilder con la política de anclaje activa y los metadatos de contexto de seguridad opcionales.
3. Artifacts are written via filesystem or object-store sinks depending on Los artefactos se escriben a través de sistemas de archivos o almacenes de objetos dependiendo de la configuración.
4. Se puede solicitar una verificación opcional en línea durante la exportación.

F:crates/decision-gate-mcp/src/tools.rs L2342-L2480 F:crates/decision-gate-mcp/src/runpack_object_store.rs L94-L260

Cuando se configura una anulación de RunpackStorage, MCP construye el runpack en disco y delega el almacenamiento al backend. De lo contrario, las exportaciones de object-store escriben objetos por artefacto directamente; las exportaciones del sistema de archivos requieren output_dir.

El constructor escribe artefactos JSON deterministas para:

• Especificación del escenario
• Registro de activación
• Registro de evaluación de puertas
• Registro de decisiones
• Registro de paquetes
• Registro de envíos
• Registro de llamadas a herramientas

F:crates/decision-gate-core/src/runtime/runpack.rs L130-L214

---

Modelo de Integridad del Artefacto

Para cada artefacto, el constructor:

• Serializa utilizando JCS
• Rechaza flotantes no finitos durante la canonicalización (NaN/±Infinity)
• Calcula un hash de archivo
• Agrega una entrada de hash de archivo y un registro de artefacto

Se calcula un hash raíz sobre la lista canónica de hashes de archivos para protegerse contra el reordenamiento u omisión de artefactos. F:crates/decision-gate-core/src/runtime/runpack.rs L433-L480

---

Flujo de Verificación de Runpack

La verificación valida la integridad y los invariantes estructurales:

• Todos los hashes de los artefactos coinciden con el manifiesto.
• El hash raíz coincide con la lista de hashes de archivos.
• El registro de decisiones no contiene decisiones duplicadas por id de activador.
• La validación de la política de anclaje se ejecuta cuando está presente en el manifiesto.

F:crates/decision-gate-core/src/runtime/runpack.rs L314-L567

La herramienta runpack_verify analiza el manifiesto, lee los artefactos del disco y devuelve un informe de verificación estructurado. F:crates/decision-gate-mcp/src/tools.rs L2497-L2513

Nota de interoperabilidad (semántica de checked_files): runpack_export con include_verification = true genera el informe de verificación antes de que el artefacto verifier_report.json se añada al manifiesto. Debido a eso, runpack_export.report.checked_files cuenta los archivos del manifiesto del pre-informe.

runpack_verify valida la lista de hashes del archivo de manifiesto finalizado (incluyendo verifier_report.json), por lo que se espera que runpack_verify.report.checked_files sea exactamente runpack_export.report.checked_files + 1 para el mismo runpack cuando la verificación en el momento de la exportación está habilitada.

---

Seguridad del Sumidero/Lector del Sistema de Archivos

Los artefactos del sistema de archivos son gestionados por implementaciones de sink/reader endurecidas:

• Las rutas deben ser relativas y no pueden escapar de la raíz del runpack.
• Se aplican límites en los componentes de la ruta y en la longitud total de la ruta.
• Las lecturas imponen límites máximos de bytes y fallan de manera cerrada en caso de violaciones.

F:crates/decision-gate-mcp/src/runpack.rs L43-L217

---

Seguridad del Sumidero/Lector de Almacenamiento de Objetos

Los adaptadores runpack de object-store imponen las mismas garantías de seguridad que el almacenamiento en sistemas de archivos:

• Las claves se derivan de tenant/namespace/scenario/run/spec_hash.
• Los segmentos de la ruta son validados y tienen un límite de longitud.
• Los artefactos están limitados a MAX_RUNPACK_ARTIFACT_BYTES.
• Las lecturas fallan en cerrado cuando se superan los límites de tamaño.

F:crates/decision-gate-mcp/src/runpack_object_store.rs L94-L260

---

Referencia Cruzada Archivo por Archivo

Área	Archivo	Notas
Esquema de manifiesto	crates/decision-gate-core/src/core/runpack.rs	Campos del manifiesto, integridad, contexto de seguridad.
Constructor + verificador	crates/decision-gate-core/src/runtime/runpack.rs	Lógica de escritura y verificación de artefactos.
Integración de herramientas	crates/decision-gate-mcp/src/tools.rs	Flujos de runpack_export/runpack_verify.
IO del sistema de archivos	crates/decision-gate-mcp/src/runpack.rs	Sumidero/lector de artefactos seguro con validación de ruta.
IO del almacenamiento de objetos	crates/decision-gate-mcp/src/runpack_object_store.rs	Sumidero/lector de almacenamiento de objetos para artefactos de runpack.