Artifact GC is reported in four JSON shapes, and the bytesFreed/bytes fields the contract documents are emitted by no command #1257

[agent] Filed by the scheduled architecture audit routine (CLI and core). Register: register comment.

Kind: bug. Source: new finding, register C79. It relates to C33 (#948, contract freshness) and C50 (#893, GC retention).

Problem (main @ a80b89e)

The contract's unified envelope documents three byte counters:

• summary.bytesDownloaded and summary.bytesFreed (CLI_CONTRACT.md#L1189-L1200);
• events[].bytes, which it says is "set" on downloaded and optional on removed (#L1221, #L1237-L1245).

None of them exists in the code. json_envelope::Summary has no byte fields, and PatchEvent has no bytes. The contract's own "GC summary" recipe, repair --json | jq '{removed: .summary.removed, bytesFreed: .summary.bytesFreed, …}' (#L1711-L1718), therefore returns bytesFreed: null. It also returns removed: 1 however many blobs were deleted.

The same GC result is reported four ways, with four key spellings:

The PatchAction table's "Emitted by" column has drifted too:

• discovered lists scan, but only list emits it.
• downloaded lists get and scan --mode agent, but only repair and update emit it.
• removed lists rollback, but rollback prints its legacy shape and no events.
• verified lists scan --dry-run, but scan prints no events.

Proof by execution (debug build at a80b89e, run twice under env -i, same result both times). The fixture is an agent-mode npm project: one applied patch, its before/after blobs, and four unreferenced blob files in .socket/blobs/. repair --offline --json deleted 5 of the 6 blobs. The contract recipe printed {"removed": 1, "bytesFreed": null, "failed": 0}, and the only event was {"action":"removed","details":{"count":5,"checked":6}}. The human run of the same fixture prints Removed 3 unused blobs (38 B freed). remove pkg:npm/left-pad@1.3.0 --json emitted two removed events (the entry, and blobsRemoved: 3), with summary.removed: 1 and no byte count.

Symptoms

None filed. #1066 (rollback counters count only the agent leg) is the same class of counter drift.

Impact

A CI or dashboard that follows the documented recipe gets null and a removal count of 1. The four shapes mean any consumer has to special-case each command. The risk is low, but the documented contract is wrong today, and every new GC caller adds another shape.

Proposed change

• Add one GcReport { removed_blobs, removed_diff_archives, removed_package_archives, bytes_freed } in json_envelope (or beside ArtifactReferences), serialized identically everywhere. rollback and scan build it instead of their hand-written json! blocks; the keys are unchanged.
• repair and remove attach it to their artifact-level removed event as additive details keys, keeping count/checked and blobsRemoved/archivesRemoved for compatibility.
• Either implement summary.bytesFreed (the sum of the removed events' bytes), or delete summary.bytesDownloaded, summary.bytesFreed and events[].bytes from the contract. Fix the jq recipe and the "Emitted by" column to match. Recommendation: implement bytesFreed, which is additive and MINOR; delete bytesDownloaded/downloaded.bytes, because blob downloads don't carry a byte count today and Remove --download-mode and the diff download path (#792) #1049 rewrites that path.
• Delete the four hand-written GC JSON blocks.

Size and scope

• json_envelope.rs, repair.rs, remove.rs, rollback.rs, scan/gc.rs and CLI_CONTRACT.md.
• About 80–150 production lines.
• Out of scope: what GC deletes (repair and scan --prune delete the beforeHash blobs of active patches, so a later offline rollback fails and tells the user to run repair #893) and rollback's top-level counters (rollback --json counters count only the agent leg, so hosted and vendored failures report failed: 0 #1066).

Acceptance criteria

• repair --json and remove --json report blobs removed and bytes freed under the same keys as rollback/scan --prune.
• The contract's GC recipe returns a number for bytesFreed (or the recipe is rewritten to the emitted keys), and an e2e test runs the recipe's paths.
• Every summary and PatchEvent field documented in the contract is serialized by json_envelope. A unit test pins the key set against the contract's schema block.
• The "Emitted by" column matches the emitters.
• Existing rollback_duality_invariants and covgap_commands_scan_vendor_flow GC assertions stay green.

Dependencies

• Blocks nothing.
• Coordinate with Remove --download-mode and the diff download path (#792) #1049, which changes repair's downloaded event, and Tracking: make CLI_CONTRACT.md a checked reference plus short prose #948 (contract freshness tests).