Struct Envelope 

pub struct Envelope {
    pub command: Command,
    pub status: Status,
    pub dry_run: bool,
    pub events: Vec<PatchEvent>,
    pub summary: Summary,
    pub error: Option<EnvelopeError>,
    pub sidecars: Vec<SidecarRecord>,
    pub vex: Option<VexSummary>,
}

Top-level JSON envelope emitted by every --json invocation.

Fields

command: Command

Which subcommand produced this output. Lets a generic consumer (one that doesn’t know which subcommand it’s piping) route on it.

status: Status

High-level success/failure summary. Use Status::PartialFailure when at least one event has action = Failed but the run as a whole completed.

dry_run: bool

True if the command was a preview (--dry-run, --prune-dry-run, etc.). When true, events describe what would happen — no disk state was modified.

events: Vec<PatchEvent>

Per-patch (and per-artifact) observations from the run. Ordering is best-effort: events appear in the order the engine produced them, but downstream consumers should not rely on it.

summary: Summary

Aggregate counts derived from events. Pre-computed so consumers don’t need to re-walk the array.

error: Option<EnvelopeError>

Set when the command itself failed before producing meaningful events (manifest unreadable, network unreachable in non-offline mode, etc.). Implies events is empty.

sidecars: Vec<SidecarRecord>

Per-package sidecar fixup records. Each entry describes what the post-apply integrity fixup did for one package — rewriting .cargo-checksum.json, deleting .nupkg.metadata, surfacing an advisory for PyPI / gem / Go, etc.

Top-level (not per-event) so consumers can iterate sidecar outcomes directly with jq '.sidecars[]'. Records carry purl so a consumer that needs the matching apply event can JOIN against events[].

Empty (and omitted from JSON via skip_serializing_if) for commands that don’t produce sidecar work — rollback, repair, list, etc. — and for apply runs against ecosystems with no sidecar contract (e.g. npm).

vex: Option<VexSummary>

Present only when --vex <path> was passed to apply/scan and an OpenVEX document was successfully generated as a side-effect of the run. Describes where it landed and how many statements it carries. A failed embedded VEX generation surfaces via error (and flips the exit code), not here.

Implementations

impl Envelope

pub fn new(command: Command) -> Self

Build a fresh envelope. summary starts at zero — callers are expected to push events with Envelope::record (or update fields directly) so summary stays consistent with the event list.

pub fn record(&mut self, event: PatchEvent)

Append an event and bump the matching summary counter. Centralizes the “events list must agree with summary counts” invariant so per- command code can’t drift.

Recording a Failed event also marks the run as a partial failure (unless it’s already a hard Error), enforcing the status invariant documented on Envelope::status here rather than relying on every command to remember a follow-up mark_partial_failure call. A run can never end up reporting Success while carrying a Failed event.

pub fn record_sidecar(&mut self, sidecar: SidecarRecord)

Append a sidecar fixup record. Called once per ApplyResult whose sidecar field is Some. Order matches the order apply processed packages, which is best-effort.

pub fn mark_partial_failure(&mut self)

Mark the run as a partial failure. Idempotent.

pub fn mark_error(&mut self, error: EnvelopeError)

Mark the run as a top-level error (replaces any prior status).

pub fn to_pretty_json(&self) -> String

Serialize as pretty JSON for printing.

Trait Implementations

impl Clone for Envelope

fn clone(&self) -> Envelope

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Envelope

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Serialize for Envelope

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.