Arquitectura de Decision Gate Runpack

Audience: Engineers implementing runpack export/verification and Audiència: Enginyers que implementen l’exportació/verificació de runpack i el maneig d’artefactes de sistema de fitxers/emmagatzematge d’objectes.

Taula de continguts

Visió Executiva
Estructura del Manifest de Runpack
Runpack Export Pipeline
Model d’Integritat d’Artifact
Flux de Verificació de Runpack
Seguretat del sistema de fitxers Sink/Reader
Object Store Sink/Reader Seguretat
File per Fitxer Referència Creuada

Executive Overview

Runpacks són paquets deterministes d’especificacions d’escenaris, registres del pla de control i metadades d’integritat. El constructor escriu artefactes JSON canònics i calcula hashes per a cada fitxer, més un hash arrel sobre la llista de hashes de fitxers. La verificació torna a executar les comprovacions d’integritat, valida la unicitat del registre de decisions i, opcionalment, valida els ancoratges d’evidència quan hi ha una política d’ancoratge present. F:crates/decision-gate-core/src/runtime/runpack.rs L83-L374

Els ancoratges d’evidència es guarden literalment als registres de runpack. Per als ancoratges basats en fitxers (file_path_rooted), els ancoratges inclouen un root_id estable més un camí relatiu al estil POSIX per assegurar que els hashes siguin coherents entre sistemes operatius.

Runpack exporta selecciona un destí en aquest ordre: un backend opcional RunpackStorage (exporta a un directori temporal i delega l’emmagatzematge), un backend d’emmagatzematge d’objectes OSS quan està configurat, o una exportació de sistema de fitxers que requereix 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 Manifest de Runpack

El manifest és l’índex canònic per als artefactes de runpack. Els camps clau inclouen:

Identificadors de scenario/execució i hash de especificació
Algorisme de hash i mode de verificador
Política d’ancoratge opcional i context de seguretat
Llista de hash de fitxers i hash arrel
Entrades de l’índex d’artefactes

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

La versionament del manifest és explícit. El verificador actualment suporta v1 i falla tancat en valors manifest_version desconeguts per preservar les garanties de compatibilitat amb versions anteriors a mesura que s’introdueixen noves versions. F:crates/decision-gate-core/src/runtime/runpack.rs L60-L374

La metadata del context de seguretat captura la postura de permissivitat del desenvolupament i l’autoritat de l’espai de noms quan és proporcionada pel servidor MCP. F:crates/decision-gate-core/src/core/runpack.rs L94-L104

Runpack Export Pipeline

L’exportació de Runpack s’initia mitjançant l’eina MCP runpack_export:

L’eina router carrega l’estat d’execució de la botiga configurada.
A RunpackBuilder is created with the active anchor policy and optional Es crea un RunpackBuilder amb la política d’ancoratge activa i metadades opcionals del context de seguretat.
Artifacts are written via filesystem or object-store sinks depending on Els artefactes es registren a través de sistemes de fitxers o emmagatzematges d’objectes segons la configuració.
Es pot sol·licitar una verificació opcional en línia durant l’exportació.

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

Quan es configura una sobreescriptura de RunpackStorage, MCP construeix el runpack al disc i delega l’emmagatzematge al backend. D’altra banda, les exportacions de l’object-store escriuen objectes per a cada artefacte directament; les exportacions del sistema de fitxers requereixen output_dir.

El constructor escriu artefactes JSON deterministes per:

Escenari espec
Registre d’activitats
Registre d’evaluació de portes
Registre de decisions
Registre de paquets
Registre de presentació
Registre de trucades d’eines

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

Model d’Integritat d’Artifact

Per a cada artefacte, el constructor:

Serialitza utilitzant JCS
Rebutja flotants no finits durant la canonicalització (NaN/±Infinity)
Calcula un hash de fitxer
Afegeix una entrada de hash de fitxer i un registre d’artifacte

Un hash arrel es calcula sobre la llista canònica de hashes de fitxers per protegir contra la reordenació o omissió d’artefactes. F:crates/decision-gate-core/src/runtime/runpack.rs L433-L480

Flux de Verificació de Runpack

La verificació valida la integritat i els invariants estructurals:

Tots els hashes d’artefactes coincideixen amb el manifest.
El hash arrel coincideix amb la llista de hashes de fitxers.
El registre de decisions no conté decisions duplicades per id de desencadenament.
La validació de la política d’ancoratge s’executa quan està present al manifest.

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

L’eina runpack_verify analitza el manifest, llegeix artefactes del disc i retorna un informe de verificació estructurat. F:crates/decision-gate-mcp/src/tools.rs L2497-L2513

Nota d’interoperabilitat (checked_files semantics): runpack_export amb include_verification = true genera l’informe de verificació abans que l’artifacte verifier_report.json s’afegeixi al manifest. A causa d’això, runpack_export.report.checked_files compta els fitxers del manifest pre-informe.

runpack_verify valida la llista de hash del fitxer de manifest finalitzat (incloent verifier_report.json), així que s’espera que runpack_verify.report.checked_files sigui exactament runpack_export.report.checked_files + 1 per al mateix runpack quan la verificació en el moment de l’exportació està habilitada.

Seguretat del sistema de fitxers Sink/Reader

Els artefactes del sistema de fitxers són gestionats per implementacions de sink/reader endurides:

Els camins han de ser relatius i no poden escapar de l’arrel del runpack.
Es fan complir els límits de components de ruta i de longitud total de la ruta.
Les lectures imposen límits màxims de bytes i fallen tancades en cas de violacions.

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

Object Store Sink/Reader Seguretat

Els adaptadors runpack de l’object-store imposen les mateixes garanties de seguretat que l’emmagatzematge de sistema de fitxers:

Les claus es deriven de tenant/namespace/scenario/run/spec_hash.
Els segments de la ruta són validats i tenen un límit de longitud.
Els artefactes estan limitats a MAX_RUNPACK_ARTIFACT_BYTES.
Les lectures fallen tancades quan es superen els límits de mida.

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

File per Fitxer Referència Creuada

Àrea	Fitxer	Notes
Esquema de manifest	`crates/decision-gate-core/src/core/runpack.rs`	Camps de manifest, integritat, context de seguretat.
Constructor + verificador	`crates/decision-gate-core/src/runtime/runpack.rs`	Lògica d’escriptura i verificació d’artefactes.
Integració d’eines	`crates/decision-gate-mcp/src/tools.rs`	Fluxos runpack_export/runpack_verify.
IO del sistema de fitxers	`crates/decision-gate-mcp/src/runpack.rs`	Dipòsit/lector d’artefactes segur amb validació de camí.
IO de l’emmagatzematge d’objectes	`crates/decision-gate-mcp/src/runpack_object_store.rs`	Dipòsit/lector d’objectes per a artefactes runpack.