feat(billing): Add contract-owned retention override config

[dashed]

Stacks on #369. Adds RetentionConfig as a fourth Contract component, carrying contract-owned retention overrides layered on top of the package retention defaults added in #369.

Shape

message RetentionOverride {
  DataCategory category = 1;                     // keyed by billing category, matching PackageConfig.retention_defaults
  optional StandardRetention standard = 2;       // absent -> inherit the package default's standard
  optional DownsampledRetention downsampled = 3; // absent -> inherit the package default's downsampled
}
message RetentionConfig {
  string revision = 1;                           // opaque; consumers must not parse
  optional StandardRetention organization = 2;   // org-wide scalar, legacy-compat, applies to every category
  repeated RetentionOverride overrides = 3;
}
// Contract { ...; RetentionConfig retention_config = 4; }

Semantics

• An override is a sparse per-category patch, not a whole-policy replacement. standard and downsampled are independently optional; an absent field inherits the corresponding package default, and the two resolve as independent chains (a standard-only override keeps the package's downsampled).
• Retention identity is the billing DataCategory, so package defaults and contract overrides always resolve against the same key.
• organization is a single duration applied to standard and downsampled alike — a temporary mirror of the legacy scalar organization retention; per-category overrides are the forward-looking mechanism.
• RetentionConfig is the raw stored input to effective-retention resolution, not the resolved policy. Nothing consumes it authoritatively yet.

Python and Rust round-trip coverage exercises sparse standard-only and downsampled-only overrides, the inherit-standard downsampled marker, an absent organization scalar, and embedding on Contract.

[github-actions]

The latest Buf updates on your PR. Results from workflow ci / buf-checks (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	✅ passed	Jul 17, 2026, 11:30 PM