Module json_envelope 

Unified JSON output envelope shared across every subcommand.

Every --json invocation of socket-patch (whether scan, apply, get, list, gc/repair, remove, or rollback) emits the same top-level shape:

{
  "command":  "scan" | "apply" | "get" | ...,
  "status":   "success" | "partialFailure" | "error" | "noManifest" | ...,
  "dryRun":   false,
  "events":   [ { "action": "...", "purl": "...", ... }, ... ],
  "summary":  { "applied": 0, "downloaded": 0, ... }
  // "error":  { "code": ..., "message": ... }  — present only on failure
}

The events array is the load-bearing payload — each entry describes one observable thing that happened during the run (a patch was downloaded, applied, skipped, etc.). A downstream consumer (PR-comment bot, dashboard, log shipper) only needs to learn this single vocabulary to interpret output from every subcommand.

See CLI_CONTRACT.md for the per-subcommand action matrix and example jq recipes.

Structs

Envelope

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

EnvelopeError

Top-level error payload set when the command failed before producing patch events.

PatchEvent

One observable thing that happened during a run.

PatchEventFile

One file referenced by a patch event.

SidecarAdvisory

Structured operator advisory. Replaces the previous free-form Option<String> field so consumers can switch on code and route on severity without regex-matching message.

SidecarFile

One file the fixup rewrote or deleted. Paths are relative to the package directory the patch landed in. (There is deliberately no “created” action — see SidecarFileAction, which reserves no variants ahead of an ecosystem that actually produces them.)

SidecarRecord

Per-package sidecar fixup outcome. Emitted under Envelope.sidecars[] one entry per package whose apply produced a fixup result (touched files or advisory).

Summary

Pre-aggregated counts across all events in this envelope. Field names match PatchAction variants for clarity.

VexSummary

Summary of an OpenVEX document emitted as a side-effect of an apply/scan run via --vex. The full document is written to path; this is just the pointer + headline count for JSON consumers.

Enums

AppliedVia

Patch-source strategy used to apply a file. Mirrors the existing socket_patch_core::patch::apply::AppliedVia enum, but lives here so the JSON layer doesn’t depend on core internals.

Command

Which subcommand produced the envelope. Serializes lowercase.

PatchAction

What kind of thing happened to a patch.

SidecarAdvisoryCode

Stable enum tag for the kind of advisory. Adding a variant is a non-breaking change; renaming or removing one is breaking.

SidecarFileAction

What the fixup did with a sidecar file. Stable snake_case JSON tag — consumers branch on this without parsing free-form text.

SidecarSeverity

Severity bucket. UI consumers use this for badge color; jq pipelines filter by it. Error is reserved for the fixup itself failing — informational consequences of the apply use Info or Warning.

Status

Top-level status. Serializes camelCase.