Decision Gate Runpack Architecture

Audience: Engineers implementing runpack export/verification and filesystem/object-store artifact handling.

Executive Overview
Runpack Manifest Structure
Runpack Export Pipeline
Artifact Integrity Model
Runpack Verification Flow
Filesystem Sink/Reader Safety
Object Store Sink/Reader Safety
File-by-File Cross Reference

Executive Overview

Runpacks are deterministic bundles of scenario specs, control-plane logs, and integrity metadata. The builder writes canonical JSON artifacts and computes hashes for every file, plus a root hash over the file hash list. Verification replays integrity checks, validates decision log uniqueness, and optionally validates evidence anchors when an anchor policy is present. F:crates/decision-gate-core/src/runtime/runpack.rs L83-L374

Evidence anchors are stored verbatim in the runpack logs. For file-based anchors (file_path_rooted), anchors include a stable root_id plus a POSIX-style relative path to ensure hashes are consistent across operating systems.

Runpack exports select a sink in this order: an optional RunpackStorage backend (exports to a temp directory and delegates storage), an OSS object-store backend when configured, or a filesystem export requiring output_dir. F:crates/decision-gate-mcp/src/runpack_storage.rs L31-L67 F:crates/decision-gate-mcp/src/tools.rs L2342-L2480

Runpack Manifest Structure

The manifest is the canonical index for runpack artifacts. Key fields include:

Scenario/run identifiers and spec hash
Hash algorithm and verifier mode
Optional anchor policy and security context
File hash list and root hash
Artifact index entries

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

Manifest versioning is explicit. The verifier currently supports v1 and fails closed on unknown manifest_version values to preserve backward compatibility guarantees as new versions are introduced. F:crates/decision-gate-core/src/runtime/runpack.rs L60-L374

Security context metadata captures dev-permissive and namespace authority posture when provided by the MCP server. F:crates/decision-gate-core/src/core/runpack.rs L94-L104

Runpack Export Pipeline

Runpack export is initiated via the MCP tool runpack_export:

Tool router loads run state from the configured store.
A RunpackBuilder is created with the active anchor policy and optional security context metadata.
Artifacts are written via filesystem or object-store sinks depending on configuration.
Optional in-line verification can be requested during export.

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

When a RunpackStorage override is configured, MCP builds the runpack on disk and delegates storage to the backend. Otherwise, object-store exports write per-artifact objects directly; filesystem exports require output_dir.

The builder writes deterministic JSON artifacts for:

Scenario spec
Trigger log
Gate evaluation log
Decision log
Packet log
Submission log
Tool call log

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

Artifact Integrity Model

For each artifact, the builder:

Serializes using JCS
Rejects non-finite floats during canonicalization (NaN/±Infinity)
Computes a file hash
Adds a file hash entry and artifact record

A root hash is computed over the canonical list of file hashes to guard against artifact reordering or omission. F:crates/decision-gate-core/src/runtime/runpack.rs L433-L480

Runpack Verification Flow

Verification validates integrity and structural invariants:

All artifact hashes match the manifest.
The root hash matches the file-hash list.
Decision log contains no duplicate decisions per trigger id.
Anchor policy validation runs when present in the manifest.

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

The runpack_verify tool parses the manifest, reads artifacts from disk, and returns a structured verification report. F:crates/decision-gate-mcp/src/tools.rs L2497-L2513

Interop note (checked_files semantics): runpack_export with include_verification = true generates the verification report before the verifier_report.json artifact is added to the manifest. Because of that, runpack_export.report.checked_files counts the pre-report manifest files.

runpack_verify validates the finalized manifest file hash list (including verifier_report.json), so runpack_verify.report.checked_files is expected to be exactly runpack_export.report.checked_files + 1 for the same runpack when export-time verification is enabled.

Filesystem Sink/Reader Safety

Filesystem artifacts are handled by hardened sink/reader implementations:

Paths must be relative and cannot escape the runpack root.
Path component and total path length limits are enforced.
Reads enforce max byte limits and fail closed on violations.

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

Object Store Sink/Reader Safety

Object-store runpack adapters enforce the same safety guarantees as filesystem storage:

Keys are derived from tenant/namespace/scenario/run/spec_hash.
Path segments are validated and length-bounded.
Artifacts are capped at MAX_RUNPACK_ARTIFACT_BYTES.
Reads fail closed when size limits are exceeded.

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

File-by-File Cross Reference

Area	File	Notes
Manifest schema	`crates/decision-gate-core/src/core/runpack.rs`	Manifest fields, integrity, security context.
Builder + verifier	`crates/decision-gate-core/src/runtime/runpack.rs`	Artifact writing and verification logic.
Tool integration	`crates/decision-gate-mcp/src/tools.rs`	runpack_export/runpack_verify flows.
Filesystem IO	`crates/decision-gate-mcp/src/runpack.rs`	Safe artifact sink/reader with path validation.
Object store IO	`crates/decision-gate-mcp/src/runpack_object_store.rs`	Object-store sink/reader for runpack artifacts.